From a194d5f2f0358cd13889865271b0189818aea61d Mon Sep 17 00:00:00 2001 From: Tom Ballard Date: Mon, 29 Jun 2026 06:14:25 +0000 Subject: [PATCH 1/2] docs(decision): add ADR-095 for the rac-connectors repackage and rename [roadmap:rac-connectors] Implements rac/roadmaps/repo-topology/rac-connectors.md. Records the decision to land rac-connectors as one distribution (renamed from lore-connectors / lore_connectors), with providers as submodules under src/rac_connectors/, the CLI entry point renamed lore-connect -> rac-connect, and the outbound contract field lore_id -> rac_id (cognee header Lore-Id: -> Rac-Id:). These changes exceed the topology-only framing of the convergence series, so they are recorded as ADR-095. Links the rac-connectors roadmap to the new ADR and regenerates the agent-rules managed blocks. --- .cursor/rules | 3 +- .github/copilot-instructions.md | 3 +- AGENTS.md | 3 +- CLAUDE.md | 3 +- ...095-rac-connectors-repackage-and-rename.md | 120 ++++++++++++++++++ rac/roadmaps/repo-topology/rac-connectors.md | 1 + 6 files changed, 129 insertions(+), 4 deletions(-) create mode 100644 rac/decisions/adr-095-rac-connectors-repackage-and-rename.md 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..fe53f167 --- /dev/null +++ b/rac/decisions/adr-095-rac-connectors-repackage-and-rename.md @@ -0,0 +1,120 @@ +--- +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 + +- A PyPI registration for `rac-connectors` is required, and the old + `lore-connectors` repo/name must be archived with a redirect. +- The outbound-field rename is a contract break: records already pushed to a + backend under `lore_id` would need a re-push, and any downstream reader keyed on + `lore_id` updated. Accepted because it lands before broad adoption. + +### Risks + +- A backend already holds `lore_id`-keyed records in production. Mitigation: do + the rename now, ahead of adoption; if such data exists, re-push and update + readers as a one-time migration. + +## 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 From b7bdc5038ead5997f0e065fbfa143255578ee435 Mon Sep 17 00:00:00 2001 From: Tom Ballard Date: Mon, 29 Jun 2026 06:29:34 +0000 Subject: [PATCH 2/2] docs(decision): note lore-connectors was never on PyPI in ADR-095 [roadmap:rac-connectors] lore-connectors had no published PyPI release, so rac-connectors is a fresh registration with no transitional shim or PyPI redirect, and the outbound lore_id -> rac_id rename has no adopters or pushed records to migrate. --- ...r-095-rac-connectors-repackage-and-rename.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/rac/decisions/adr-095-rac-connectors-repackage-and-rename.md b/rac/decisions/adr-095-rac-connectors-repackage-and-rename.md index fe53f167..371f7b11 100644 --- a/rac/decisions/adr-095-rac-connectors-repackage-and-rename.md +++ b/rac/decisions/adr-095-rac-connectors-repackage-and-rename.md @@ -72,17 +72,18 @@ History is preserved across the move (the package directory rename is a tracked ### Negative -- A PyPI registration for `rac-connectors` is required, and the old - `lore-connectors` repo/name must be archived with a redirect. -- The outbound-field rename is a contract break: records already pushed to a - backend under `lore_id` would need a re-push, and any downstream reader keyed on - `lore_id` updated. Accepted because it lands before broad adoption. +- `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 -- A backend already holds `lore_id`-keyed records in production. Mitigation: do - the rename now, ahead of adoption; if such data exists, re-push and update - readers as a one-time migration. +- 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