Skip to content
Crosswalker
🚧 Early alpha — building the foundation. See the roadmap →

The xwalk identity space: frozen as legacy, never migrated

Created Updated

1. In one breath

Section titled “1. In one breath”

A crosswalk edge (a note saying “control A in one framework relates to control B in another”) has been given its identity under two different prefixes depending on which path created it. That splits one kind of thing across two identity spaces, so duplicate checks and closure pairing can miss a match. The decision: one space, sssom, for every new edge; the old xwalk notes stay exactly as they are and are recognized, never rewritten.

2. The facts

Section titled “2. The facts”
FactSource
The bundled recipe olir-crosswalk-edge declares source.ontology: "xwalk", so the engine mints xwalk: curies (the stable identifiers stamped on each note) for every import through it, including a wizard import of an OLIR spreadsheetrecipes/import/crosswalk-edge.json, src/import/recipe-registry.ts
The headless tool tools/crosswalk-from-olir.ts hard-codes the same xwalk: formtools/crosswalk-from-olir.ts (the curie template near line 270)
The SSSOM importer and the crosswalk-column pass mint under a named constant, sssom, and say explicitly that the ontology pair is not the identity spacesrc/import/sssom-importer.ts (SSSOM_CURIE_PREFIX), src/generation/crosswalk-edge-pass.ts
The local development vault holds 7,608 xwalk: edge notes under _crosswalker/mappings/, all written by the headless tools in May 2026, none stamped with an import set, and zero stamped sets exist under either prefixCounted 2026-09-21; see the 2026-09-21 synthesis §5.4
Those notes are untracked local data (part of the source is licensed and stays local). No released build has written xwalk: edges into a user vault through an import setgit ls-files; the plugin is on 0.1.x prereleases

The last row is why this is cheap to settle now: the only population at stake is our own development data.

3. The options

Section titled “3. The options”

Option A: migrate everything to sssom

Section titled “Option A: migrate everything to sssom”

What: change the recipe and tools, then rewrite the 7,608 curies from xwalk: to sssom:. Pros: one space with no legacy branch in the code. Cons: it rewrites identities, which the project treats as recorded facts. Any junction, closure row, or user link that captured the old curie breaks silently. It also sets the precedent that a rename of the identity scheme justifies rewriting every note, which is the same move that four failed passes taught us to stop making.

Section titled “Option B: freeze xwalk as a legacy space; mint sssom going forward (recommended)”

What: new edges from any path mint sssom:. Existing xwalk: notes keep their curies. Any lookup for an edge also checks the legacy xwalk: form of the same pair, and on a match it updates that note where it lives instead of creating a twin. Pros: it matches the rule already used for junction notes (the legacy form is kept as a recorded alias and is adopted on a match). Nothing is rewritten, and one space holds all new work. Cons: there is one more alias form to test, and the xwalk space never fully disappears from old vaults.

Option C: a one-time stamping pass

Section titled “Option C: a one-time stamping pass”

What: walk the 7,608 notes, mint an import set for each mapping folder, and stamp it in. Pros: legacy edges become owned and refreshable immediately. Cons: stamping asserts ownership, and ownership is minted at import, never derived. A pass that infers “this folder is one set” from a path is exactly the guess the project has ruled out. The honest route to ownership already exists: an explicit refresh chosen by the user adopts the notes and pins the prefix they already carry.

4. Decision

Section titled “4. Decision”

Option B. Concretely:

  1. One space for new edges. Every crosswalk edge, whether it comes from an SSSOM file, a crosswalk column, the bundled OLIR recipe, or a headless tool, mints under sssom:. The identity is a property of the kind of note (a crosswalk edge), not of the recipe’s source.ontology label.
  2. Legacy identities are facts, not errors. Existing xwalk: curies are never rewritten, renamed, or bulk-stamped.
  3. Recognize before creating. Edge lookup checks the pair’s sssom: form, then its legacy xwalk: form. A match on either updates that note in place, so no vault gains a duplicate edge because the scheme changed. This follows the junction precedent: the pair decides.
  4. Ownership only by explicit refresh. A legacy mapping folder becomes an owned set only when the user chooses to refresh it. That follows the standing rule that a refresh is chosen, never guessed. On that refresh the set is pinned to the prefix its notes already carry (xwalk), so it matches its own notes and nothing is orphaned.
  5. The development vault is regenerated, not migrated. When convenient, our local _crosswalker/mappings/ data is deleted and re-imported through the plugin. That is a fixture refresh, not a product migration path.

5. Follow-up work

Section titled “5. Follow-up work”
ItemWhere
Make the crosswalk-edge kind mint sssom: regardless of source.ontology; decide whether the recipe keeps xwalk as a descriptive source label or drops itsrc/generation/generation-engine.ts (the prefix derivation), recipes/import/crosswalk-edge.json
Point the headless tools at the shared constant instead of a literaltools/crosswalk-from-olir.ts, tools/crosswalk-from-melt.ts
Add the legacy xwalk: form to edge lookup, with a test for a vault holding a legacy edge plus an import of the same pair: one note, updated in placesrc/generation/crosswalk-edge-pass.ts, src/import/sssom-importer.ts
A test that a legacy-refresh of an xwalk mapping folder pins xwalk and reports zero orphansalongside tests/legacy-vault-refresh.test.ts
Remove the “owner decision” line from CHANGELOG.md [Unreleased] once ratifiedCHANGELOG.md
Section titled “Related”