diff --git a/.cursor/rules b/.cursor/rules index 444f3212..2bc70cff 100644 --- a/.cursor/rules +++ b/.cursor/rules @@ -1,4 +1,4 @@ - + ## Settled decisions (RAC) @@ -67,4 +67,5 @@ These decisions are already accepted. Do not re-open or contradict them; ask the - **RAC-KW5A03ZHXN9F** — ADR-092: Repository Topology — One Repo Per Concern, rac-* Naming _(Architecture)_ - **RAC-KW6HY8W1CBK6** — ADR-093: Roadmap Intent Lives in the Corpus; Execution Is Tracked in GitHub Issues _(Process)_ - **RAC-KW6NQ4Y814N7** — ADR-094: Roadmaps Are Identified by Stable Codename, Not a vX.Y.Z Scope-Fence _(Process)_ +- **RAC-KW8ZTVEQJ366** — ADR-095: rac-connectors Repackage, PyPI Rename, and Outbound Field Rename _(Architecture)_ diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 444f3212..2bc70cff 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,4 +1,4 @@ - + ## Settled decisions (RAC) @@ -67,4 +67,5 @@ These decisions are already accepted. Do not re-open or contradict them; ask the - **RAC-KW5A03ZHXN9F** — ADR-092: Repository Topology — One Repo Per Concern, rac-* Naming _(Architecture)_ - **RAC-KW6HY8W1CBK6** — ADR-093: Roadmap Intent Lives in the Corpus; Execution Is Tracked in GitHub Issues _(Process)_ - **RAC-KW6NQ4Y814N7** — ADR-094: Roadmaps Are Identified by Stable Codename, Not a vX.Y.Z Scope-Fence _(Process)_ +- **RAC-KW8ZTVEQJ366** — ADR-095: rac-connectors Repackage, PyPI Rename, and Outbound Field Rename _(Architecture)_ diff --git a/AGENTS.md b/AGENTS.md index 444f3212..2bc70cff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ - + ## Settled decisions (RAC) @@ -67,4 +67,5 @@ These decisions are already accepted. Do not re-open or contradict them; ask the - **RAC-KW5A03ZHXN9F** — ADR-092: Repository Topology — One Repo Per Concern, rac-* Naming _(Architecture)_ - **RAC-KW6HY8W1CBK6** — ADR-093: Roadmap Intent Lives in the Corpus; Execution Is Tracked in GitHub Issues _(Process)_ - **RAC-KW6NQ4Y814N7** — ADR-094: Roadmaps Are Identified by Stable Codename, Not a vX.Y.Z Scope-Fence _(Process)_ +- **RAC-KW8ZTVEQJ366** — ADR-095: rac-connectors Repackage, PyPI Rename, and Outbound Field Rename _(Architecture)_ diff --git a/CLAUDE.md b/CLAUDE.md index 4024d856..d5b49644 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -23,7 +23,7 @@ to the corpus artifact and they load through the imports below. - Previous series: `rac/roadmaps/v0.21.x-editor/` (complete) - Decisions (ADRs): `rac/decisions/` - + ## Settled decisions (RAC) @@ -92,4 +92,5 @@ These decisions are already accepted. Do not re-open or contradict them; ask the - **RAC-KW5A03ZHXN9F** — ADR-092: Repository Topology — One Repo Per Concern, rac-* Naming _(Architecture)_ - **RAC-KW6HY8W1CBK6** — ADR-093: Roadmap Intent Lives in the Corpus; Execution Is Tracked in GitHub Issues _(Process)_ - **RAC-KW6NQ4Y814N7** — ADR-094: Roadmaps Are Identified by Stable Codename, Not a vX.Y.Z Scope-Fence _(Process)_ +- **RAC-KW8ZTVEQJ366** — ADR-095: rac-connectors Repackage, PyPI Rename, and Outbound Field Rename _(Architecture)_ diff --git a/rac/decisions/adr-095-rac-connectors-repackage-and-rename.md b/rac/decisions/adr-095-rac-connectors-repackage-and-rename.md new file mode 100644 index 00000000..371f7b11 --- /dev/null +++ b/rac/decisions/adr-095-rac-connectors-repackage-and-rename.md @@ -0,0 +1,121 @@ +--- +schema_version: 1 +id: RAC-KW8ZTVEQJ366 +type: decision +tags: [structure, org, connectors, distribution, contract] +--- +# ADR-095: rac-connectors Repackage, PyPI Rename, and Outbound Field Rename + +## Context + +ADR-092 converges the `itsthelore` organisation onto `rac-*` repository slugs, +and the `rac-connectors` roadmap renames `lore-connectors` → `rac-connectors`. +ADR-073 had already consolidated the backend connectors into one repository with a +subdir per backend; ADR-063/ADR-002 fix them as thin consumers of the public +export contract that reimplement no engine internals. + +The convergence series is framed as **topology only** — slugs and locations, not +code or contracts. Landing `rac-connectors` surfaced three changes that go beyond +a slug rename and therefore need a recorded decision rather than being folded +silently into a topology move: + +1. The Python **distribution and import package** still carried the `lore` + name (`lore-connectors` / `lore_connectors`), leaving the `rac-*` convergence + half-applied inside the repo. +2. The **CLI entry point** was `lore-connect`, incoherent with a `rac-connectors` + distribution. +3. The connectors write an **outbound field** `lore_id` (and a cognee `Lore-Id:` + header) into external backends; its value is already the canonical `RAC-*` + artifact id, so the field name and its value disagreed (`lore_id: RAC-…`). + +The engine's export contract is unaffected: `rac export` emits `"id"` +(`rac/services/export.py`); the `lore_id`/`rac_id` field is a name the connectors +coin on the way out, mapped from that `id`. + +## Decision + +Land `rac-connectors` with the `rac-*` naming applied through the package and its +outbound surface, as one distribution. + +1. **One distribution, providers as submodules.** The distribution is + `rac-connectors` (to be registered on PyPI), the import package is + `rac_connectors`, and each integration stays a submodule under + `src/rac_connectors/` (`cognee/`, `letta/`, `mem0/`, `neo4j/`, `supermemory/`, + `zep/`) sharing the core (`base`, `contract`, `records`, `graph`, `cli`). This + is "subdir per integration" (ADR-092) realised within a single distribution; + future integrations (e.g. `atlassian/`) join as sibling submodules. A provider + graduates to its own distribution only via the ADR-092 escape hatch. +2. **CLI entry point** `lore-connect` → `rac-connect`. +3. **Outbound field rename** `lore_id` → `rac_id`, and the cognee header + `Lore-Id:` → `Rac-Id:`. The value is unchanged (the canonical `RAC-*` id), so + the field name now agrees with its value. This is a deliberate change to the + connectors' *outbound* data contract (the records written into Supermemory, + mem0, zep, letta, cognee), accepted before broad adoption rather than carried + as a permanent `lore`-named field. +4. **Retained on purpose.** The "Lore" product brand in prose, the `itsthelore` + org name, and the engine export field `"id"` are unchanged — consistent with + ADR-036/ADR-039 keeping the Lore brand at the product surface while slugs go + `rac-*`. + +History is preserved across the move (the package directory rename is a tracked +`git mv`; `git log --follow` traces through it). + +## Consequences + +### Positive + +- The `rac-*` scheme is consistent end to end for connectors: repo slug, + distribution, import package, CLI, and the outbound id field. +- The outbound id field name and value agree (`rac_id: RAC-…`). +- No engine or export-contract change; connectors stay thin contract consumers + (ADR-063, ADR-002). + +### Negative + +- `rac-connectors` is a fresh PyPI registration. `lore-connectors` was never + published to PyPI, so no transitional shim or PyPI redirect is needed; the old + GitHub repository is simply archived. +- The outbound-field rename is, in principle, a contract change; in practice it + ships before the first release, so there are no adopters or already-pushed + `lore_id`-keyed records to migrate. + +### Risks + +- The outbound field name is effectively frozen once `rac-connectors` is published + and adopted. Mitigation: the `rac_id` rename lands now — before any release — so + no migration is ever required. + +## Status + +Accepted + +## Category + +Architecture + +## Alternatives Considered + +### Pure slug rename, keep `lore_connectors` / `lore-connect` / `lore_id` + +Rejected: it leaves the `rac-*` convergence half-applied inside the repo and keeps +the field name disagreeing with its `RAC-*` value, deferring the same churn to a +later, post-adoption break. + +### Split integrations into separate top-level distributions + +Rejected: it fragments the shared core (`base`, `contract`, `records`) across +distributions and contradicts the one-`rac-connectors`-dist intent. A provider can +still graduate later via the ADR-092 escape hatch if it grows independent cadence. + +## Related Decisions + +- adr-092 +- adr-073 +- adr-063 +- adr-002 +- adr-036 + +## Related Roadmaps + +- rac-connectors +- repo-topology-convergence diff --git a/rac/roadmaps/repo-topology/rac-connectors.md b/rac/roadmaps/repo-topology/rac-connectors.md index 18c12a4d..ed8caa6d 100644 --- a/rac/roadmaps/repo-topology/rac-connectors.md +++ b/rac/roadmaps/repo-topology/rac-connectors.md @@ -70,6 +70,7 @@ item applies the `rac-*` name and the wider remit. - adr-073 - adr-063 - adr-002 +- adr-095 ## Related Roadmaps