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

v0.1.7 — Portability: exporters, reusable configurations, source bindings, and MappingSets

Updated

Goal

Section titled “Goal”

Make the portable parts of the import/export chain explicit without collapsing distinct artifact roles. ImportRecipe remains the reusable configuration; a separate source/run binding records the exact input and parameters selected for replay; a minimal MappingSet envelope governs portable mapping assertions; exporters serialize canonical Tier 1 data as STRM-shaped TSV, OSCAL JSON, SSSOM-flavored TSV, and CSV. See the artifact roles and authority and artifact-role synthesis. Hybrid SSSOM↔STRM resolution remains per v0.1 stack pivot §6.

Status

Section titled “Status”

🚧 In progress (started 2026-07-12) — exporter first slice ✅; ImportRecipe fidelity foundation ✅ 2026-07-21; recipe library ✅ 2026-10-02; Run again with source/run binding ✅ 2026-10-02; full NIST replay proofs ✅ 2026-10-03; mapping set release record slices 1 and 2 ✅ 2026-10-03 (Track 3 closed). Remaining scope is exporter completion and the OSCAL target-shape decision. Delivery detail lives only in CHANGELOG.md [Unreleased]. This milestone also tracks nested source records (SchemaVer 1.13.0) and body projection (1.14.0), assigned 2026-09-23; both are on feat/body-projection, unmerged.

Scoped addendum, 2026-09-23 — the Status paragraph and the nested-records scope bullet only. Nested records and body projection were assigned to this milestone; no status symbol, checkbox or success criterion changed.

Scoped addendum, 2026-09-09 — the Track 2 paragraph below only, re-checked against the targeted real-Obsidian acceptance run of tests/e2e/visual-wizard-formats.spec.ts and its independent evidence review. No status cell, checkbox or success criterion changed — a passing targeted runtime acceptance on unmerged branch work satisfies none of them, and the source-byte-hash clause still asks for a hash recorded in a run binding that does not exist. No other section of this page was re-verified on this date.

Scoped addendum, 2026-09-07 — the Track 2 paragraph below only. Re-checked against the local working tree (src/import/parsers/xlsx-parser.ts, src/generation/hash.ts, src/generation/generation-engine.ts, src/generation/provenance.ts) and CHANGELOG.md [Unreleased]. No status cell, checkbox or success criterion changed, and no other section of this page was re-verified on this date.

Status last verified: 2026-10-03 (Track 3 release record slice 2: checkboxes 4, 5 and 6, the MappingSet success criterion and the STRM and SSSOM round-trip criterion ticked, verified against spec/recipe.schema.json SchemaVer 1.18.0, src/import/strm-importer.ts, src/export/strm-tsv-exporter.ts, src/export/sssom-exporter.ts, src/generation/crosswalk-edge-pass.ts, tests/strm-import-roundtrip.test.ts, tests/crosswalk-edge-pass.test.ts and tests/recipe-crosswalk-mapping-set.test.ts; real-Obsidian run of tests/e2e/strm-import.spec.ts (export, import with the release file, record equality) plus the four updated mapping e2e specs. Slice 1, same day: checkboxes 1 to 3 ticked and notes on 4 and 5, verified against spec/tier1.schema.json SchemaVer 1.7.0, src/mappings/mapping-set.ts, src/export/sssom-exporter.ts, tests/mapping-set-roundtrip.test.ts and a real-Obsidian run of tests/e2e/mapping-set-envelope.spec.ts. Track 2 replay proofs: the full-source replay checkbox and its two success criteria, verified against tests/replay-proof-nist.test.ts and a real-Obsidian run of tests/e2e/replay-proof-nist.spec.ts with CW_SCALE=1; the library criterion (save, reopen, browse, inspect, export, delete) re-checked against src/import/recipe-library-modal.ts. Earlier, 2026-10-02, Track 2: the three run-binding checkboxes and the run-binding success criterion, verified against src/import/recipe-runs.ts, src/generation/managed-equivalence.ts and real-Obsidian runs of tests/e2e/recipe-run-again.spec.ts and tests/e2e/visual-recipe-library.spec.ts. Track 1: the three library checkboxes and Gate 2, verified against src/import/recipe-library.ts, src/import/recipe-library-modal.ts and real-Obsidian runs of tests/e2e/recipe-library-flow.spec.ts and tests/e2e/visual-recipe-library.spec.ts). Rest of the page last verified 2026-09-06 against CHANGELOG.md [Unreleased], src/main.ts, src/export/, and the targeted real-Obsidian typed-export walkthrough. Typed mapping command wiring is complete; see CHANGELOG.md — Unreleased for measured delivery detail. The parent command/settings task and OSCAL target-shape decision remain open. The per-import-root work already on this unmerged branch remains separate from this milestone slice.

Dependencies

Section titled “Dependencies”

Scope

Section titled “Scope”

In:

  • STRM-shaped TSV exporter — produces NIST IR 8278A r1 OLIR template format; Excel-friendly
  • OSCAL JSON exporter — target shape must be selected explicitly before edge emission; no claim that OSCAL Profile itself contains a crosswalk mapping construct
  • SSSOM-flavored TSV (optional, opt-in) — for users who want to share crosswalks with the SSSOM academic ecosystem
  • CSV exporter — any generated framework folder back to a spreadsheet (scope addition, delivered 2026-07-12 ahead of plan)
  • Reusable-configuration library lifecycle — canonical ImportRecipe save/open/browse/inspect/export/delete under _crosswalker/recipes/import/
  • Separate source/run binding — recipe reference + recipe hash, exact source-byte hash, parser selectors, destination, and bound parameters; source drift is diagnosed before replay
  • Nested source records and body projection — nested levels become folders, notes, sections inside the parent note, or are left out, set from the Depth dial (decision log)
  • Minimal MappingSet portability envelope — stable set identity/version, participants, membership/integrity, provenance/license, canonical SSSOM/STRM round-trip, and inspect/export UI
  • Command palette entries: “Crosswalker: Export STRM TSV”, “Export OSCAL JSON” (only after target shape settles), “Export SSSOM TSV”
  • Roundtrip test: STRM TSV → import → STRM TSV produces identical bytes (deterministic)

Out:

  • A generalized KnowledgeSet schema or governance model; v0.1.7 defines only the minimum MappingSet portability envelope needed for crosswalk interchange
  • OSCAL catalog export (deferred to v1.0+)
  • Compliance dashboards / report generation (community phase)
  • AI-assisted mapping suggestions (community phase)

Concrete tasks

Section titled “Concrete tasks”
  • SSSOM TSV exporter — shipped 2026-07-12 as src/export/sssom-exporter.ts, reading Tier 1 directly via src/export/vault-reader.ts (implementation delta from the sidecar-read plan above; vault is canonical, sidecar not required for export)
  • Round-trip test (SSSOM) — import → export → import, edge sets deep-equal order-independent; the STRM round trip (export, import, export again byte identical) is proved in tests/strm-import-roundtrip.test.ts (release record slice 2, 2026-10-03)
  • STRM-shaped typed mapping table exporter — engine and typed-command wiring complete. See CHANGELOG.md — Unreleased
  • OSCAL JSON exporter — skeleton shipped (imports shell real); make an explicit target-shape decision before crosswalk-edge emission. OSCAL 1.1.x Profile has no mapping construct, so the exporter must remain an honest non-implementation unless a valid OSCAL target shape is selected and documented
  • Command-palette + settings UI — typed mapping command wiring is complete; remaining exporter commands and the settings toggle for SSSOM remain pending (off by default since “zero GRC adoption” per Ch 19). See CHANGELOG.md — Unreleased
  • Validation — exports against published STRM / OSCAL / SSSOM JSON Schemas (not all are formal but where they exist)

Track 1 — ImportRecipe / reusable-configuration library lifecycle

Section titled “Track 1 — ImportRecipe / reusable-configuration library lifecycle”
  • Add canonical metadata/ancestry, source compatibility version, and ordered body projections to spec/recipe.schema.json
  • Add lossless RecipeDocument patching with normalized/canonical equality and explicit portability blockers
  • Preserve recognized/fresh recipe identity, crosswalk-edge kind, opaque fields, and canonical body through workbench preview/generation
  • Verify with rich fixture, codegen drift gate, unit suite, and real Obsidian E2E (synthesis)
  • Settle the public UI term while retaining ImportRecipe as the machine-contract name (recipe; Gate 2 record)
  • Store canonical user configurations under _crosswalker/import-recipes/ (moved from the sketched _crosswalker/recipes/import/ so the query-recipe loader never reads them) without rebuilding them from the smaller workbench model. Each import also keeps the recipe it ran under _crosswalker/import-sets/ (see CHANGELOG.md [Unreleased])
  • Add save, reopen, browse, inspect, export, and delete UI; preserve identity, hash, ancestry, opaque fields, and portability blockers across the full lifecycle (library slice 2026-10-02; delivery detail in CHANGELOG.md — Unreleased)

Track 2 — Source/run binding and exact replay

Section titled “Track 2 — Source/run binding and exact replay”

Gate 1 of the save-and-exact-replay register closed 2026-09-06 — see the Gate 1 ratification for the ratified digest, binding-surface, replay-promise, and source-retention answers. That unblocks writing the design specification; Gate 2 (D5, D6) closed 2026-10-02 in the Gate 2 record. A first recipe-document digest slice is implemented locally and has passed independent verification; it remains unmerged and unreleased — see CHANGELOG.md — Unreleased. None of the checkboxes below are satisfied by it.

A second slice — XLSX source-byte provenance, 2026-09-07 — gives the pre-existing _crosswalker.source_ref.source_hash contract its first live runtime producer and guarantees that a primary sheet and any joined sheet come from one byte snapshot. It is unmerged and unreleased. Its core gates passed on 2026-09-07, and its targeted Tier 1 runtime acceptance passed on 2026-09-09, including the negative control that a JSON import records no byte fingerprint. That is a scoped runtime result with open qualifications, not a full-suite, Tier 2 or milestone clearance. Counts, outcomes and the qualification list in CHANGELOG.md — Real-Obsidian acceptance rerun. It satisfies none of the checkboxes below, including the source-byte-hash clause, which asks for a hash recorded in a run binding alongside recipe reference, parser selectors, destination and parameters — none of which existed then (the Run again slice below added it on 2026-10-02). Remaining gates: Gate 2 closed 2026-10-02; Gate 3 (D7, D8) lands at v0.1.8; D4’s opt-in for retained source copies is ratified but unimplemented.

Run again slice, 2026-10-02 (synthesis): run records in plugin settings, Run again from the recipe library, and file/recipe change status before a run. Delivery detail in CHANGELOG.md — Unreleased. D4’s opt-in retained source copy is still unimplemented, so a run always asks for the file again.

  • Keep the reusable configuration independent from a concrete run binding (Run again slice 2026-10-02)
  • Record recipe reference + canonical recipe hash, exact source-byte hash, parser selectors (for example sheet/header/iterator), destination, and bound parameters (Run again slice 2026-10-02)
  • Diagnose missing or drifted source bytes before replay; never silently treat a changed source as the original input (Run again slice 2026-10-02; with no retained copy, a missing source is simply asked for again)
  • Prove NIST CSF 2.0 and NIST SP 800-53 full-source save → reopen → replay equivalence through both UI and programmatic paths (replay proofs slice 2026-10-03)

Track 3 — Minimal MappingSet portability envelope

Section titled “Track 3 — Minimal MappingSet portability envelope”
  • Define stable MappingSet identity and version plus explicit source/target participants and participant versions (release record slice 2026-10-03)
  • Define assertion membership and integrity hashes without inferring set identity from a folder, filename, tag, or repeated edge values (release record slice 2026-10-03)
  • Carry minimum provenance, provider/contributor, and license fields required for responsible interchange (release record slice 2026-10-03)
  • Round-trip the same semantic set through canonical SSSOM and STRM representations while preserving set identity/version and assertion membership (release record slice 2, 2026-10-03; STRM carries the release in a .mapping-set.json release file beside the table)
  • Add MappingSet inspect/export UI and programmatic access (release record slice 2, 2026-10-03: review view, export lines, typed mapping table import command, release records for recipe crosswalk columns)
  • Keep generalized Knowledge Set governance deferred to the Evolution phase (release record slice 2, 2026-10-03: kept deferred by decision M12)

Success criteria

Section titled “Success criteria”
  • STRM TSV opens cleanly in Excel; column ordering matches NIST IR 8278A r1
  • OSCAL target shape is explicitly selected and documented; the chosen representation validates against its published OSCAL schema. If no valid mapping-bearing target is selected, the exporter remains explicitly unsupported rather than emitting misleading JSON
  • SSSOM TSV passes the sssom-py validator (optional CI step)
  • All three exporters handle large vaults (~10K mappings) without UI freeze (cooperative yielding)
  • STRM and SSSOM round-trip determinism verified at both assertion and MappingSet-envelope levels (release record slice 2, 2026-10-03: tests/mapping-set-roundtrip.test.ts and tests/strm-import-roundtrip.test.ts; limitation: a typed mapping table cannot carry explicit negations or release lineage (both skipped on export, so such a set always exports as partial), ‘roughly the same’ (exported as ‘intersects with’ and comes back as that), confidence beyond tenths (rounded to the 0 to 10 strength scale), labels, per-row providers, or review columns; release identity and metadata travel in the release file beside the table)
  • Untouched canonical ImportRecipe retains normalized semantics, canonical JSON, identity, and deferred fields through the workbench
  • Customized recipe receives deterministic identity + structured ancestry without mutating the original
  • User can durably save, reopen, browse, inspect, export, and delete a portable reusable configuration through UI (recipe library slice 2026-10-02; reopen-then-replay proved 2026-10-03)
  • A saved run binding retains recipe reference/hash, exact source-byte hash, parser selectors, destination, and parameters; source drift is visible before replay (Run again slice 2026-10-02)
  • Full NIST CSF 2.0 and NIST SP 800-53 save/reopen/replay produce equivalent canonical Tier 1 output (replay proofs slice 2026-10-03)
  • A portable MappingSet retains stable identity/version, participants, membership/integrity, provenance/license, and canonical SSSOM/STRM round-trip semantics (release record slice 2, 2026-10-03; delivery detail in CHANGELOG.md — Unreleased)

Files to touch

Section titled “Files to touch”
  • src/export/strm-tsv.ts — new
  • src/export/oscal-profile.ts — new
  • src/export/sssom-tsv.ts — new
  • src/export/index.ts — exports + command-palette wiring
  • src/main.ts — register commands
  • tests/export/strm-roundtrip.test.ts — new
  • tests/export/oscal-validation.test.ts — new

Open questions

Section titled “Open questions”
  • Where does the user choose the export destination — OS file picker, or a vault path? Both have UX trade-offs
  • OSCAL target shape — OSCAL Profile is useful for imports/tailoring but does not represent crosswalk mappings in OSCAL 1.1.x. Select and document a valid mapping-bearing target before implementing edge emission; Catalog remains out of scope for v0.1
Section titled “Related”

Concept pages:

Agent context:

Design decisions (synthesis logs):

Research deliverables:

Spec & schema files:

Registry references:

Other milestones: