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

Portable ImportRecipe fidelity — synthesis (canonical recipe survives the workbench)

Created Updated

§1 The verdict

Section titled “§1 The verdict”

A validated ImportRecipe is now the preservation authority throughout the import workbench. The editable mapping patches only fields the workbench owns; untouched canonical fields survive, and unsupported edits block instead of disappearing.

DecisionVerdict
Canonical recipe ↔ editable workbench boundaryAdopted: RecipeDocument retains the original recipe plus editable ImportMapping and session-only metadata
Body projectionAdopted: ordered target.also_emit.body; evaluated only by pure render()
EqualityAdopted: normalized semantic equality + deterministic canonical JSON, not literal source whitespace/key order
Recipe ancestryAdopted: structured metadata.based_on with recipe ID and optional target hash/spec URI
Source versionAdopted: compatibility declaration; verified run metadata remains authoritative
Persistent user recipe libraryDeferred: namespace reserved; no save/open/browser UI in this slice
Public UI nameDeferred: internal term remains ImportRecipe until product wording is settled
Mapping-set packagingDeferred: recipes, crosswalk mapping sets, and ontology content remain independently modeled

§2 Why this boundary is correct

Section titled “§2 Why this boundary is correct”
  • Preserve first: the workbench cannot safely reconstruct fields it does not edit, including kind, query, graph_edges, and linkStyle.
  • Block loss: nonportable mapping states such as table-row body output, lookup naming, row filters, materialized notes, and non-default missing policies now return explicit blockers.
  • Keep render pure: body templates and formats are resolved into ordered body regions by render(); generation only assembles Markdown.
  • Separate recipe compatibility from run truth: source.version can describe intended compatibility, but _crosswalker.source_ref records the source actually used.

§3 Load-bearing principle

Section titled “§3 Load-bearing principle”

An editor over a portable artifact must patch a validated original; it must never rebuild the artifact from a smaller view model.

This is the recipe-side application of schema-as-primitive: the canonical artifact outranks any one UI projection.

§4 What is locked in

Section titled “§4 What is locked in”
Aspectv0.1 lock
Preservation authorityRecipeDocument.original
Editor-owned fieldslayout; tags; aliases; managed frontmatter/links; user_preserve; enrichment; canonical body
Opaque preserved fieldsleaf kind; query; graph_edges; linkStyle; display/source metadata not edited by the workbench
Fresh identitycustom-<source-ontology-slug>
Customized identity<original-id>-custom plus metadata.based_on
Body positionsappend, section; table rows remain blocked
Body formatstext, code, quote, list
Validationschema → recipe semantics → source compatibility → editable-model portability
User recipe namespacefuture _crosswalker/recipes/import/*.json; existing query templates stay _crosswalker/recipes/*.json
Scalar typingexact managed templates may use `

§5 Verification and the defect it exposed

Section titled “§5 Verification and the defect it exposed”

The contract is pinned by a rich fixture plus unit and real-Obsidian E2E coverage:

  • canonical load → no-op patch retains recipe ID and canonical equality;
  • one edit changes only owned regions and writes ancestry;
  • array order survives when emissions attach to different mapping levels;
  • prefixed multi-column templates such as cw-{subject_id|slug}--{object_id|slug}.md survive exactly;
  • canonical body renders and generates through the workbench;
  • recognized and detected crosswalk-edge kinds survive preview/generation.

The real crosswalk E2E found one additional portability defect: CSV confidence values remained strings, but Tier 1 requires numeric match_confidence. The closed template filter set now includes number, and the bundled OLIR-style recipe uses {match_confidence|number}. This is why real runtime validation remains part of the recipe-fidelity gate.

§6 Reconciliation with prior decisions

Section titled “§6 Reconciliation with prior decisions”
Prior commitmentReconciliation
Closed five-mechanism grammarUnchanged. Body remains cross-cutting output, not a sixth layout mechanism.
Runtime-agnostic JSON Schema recipesStrengthened: generated boundary types, AJV narrowing, deterministic codegen drift check.
Shape workbenchCorrected: internal mapping conversion is now lossless for supported fields, but durable user recipe-file lifecycle is still open.
UI parity principleThe active import UI edits canonical recipes safely; standalone save/open/share UI remains a named gap.
v0.1.7 exportersRecipe portability joins output export as the other side of the same portability milestone.

§7 What this does not do

Section titled “§7 What this does not do”
  • no persistent user ImportRecipe store or browser;
  • no final public term such as “blueprint” or “reusable configuration”;
  • no automatic SavedConfig → ImportRecipe migration;
  • no first-class mapping-set identity or authoring UI;
  • no claim that every valid future recipe field is editable;
  • no full NIST CSF / NIST 800-53 save-reopen-reapply proof yet.

§8 What this unblocks

Section titled “§8 What this unblocks”
  1. Settle the public term and add a local recipe library under _crosswalker/recipes/import/.
  2. Prove NIST CSF 2.0 and NIST SP 800-53 portability on full verbose sources.
  3. Design first-class mapping-set storage and authoring independently from ImportRecipe storage.
  4. Stress breadth across D3FEND, ATT&CK, and the 369-column SCF workbook.
Section titled “§9 Related”