Save and exact replay — open decision register (aligned direction, unsettled details)

This is a decision register, not a decision

A decision register is a working log of open choices — what was found, what the options are, what each one costs. Nothing in it is policy until the owner ratifies it. This register (the log tracking how a saved import can be re-run later and produce the same result) is not settled. Three read-only audits checked the proposed Save and exact replay slice against the five-mechanism grammar, the artifact roles and authority model (the concept page defining which artifact is allowed to assert what), and prior provenance/migration/audit research. The direction survives. Eight decisions do not have answers yet, and each one changes what gets built.

For an executive-readable version of all eight — plain-English title, tradeoffs, and a recommendation — see the owner review queue (the single checklist of everything awaiting the project owner’s ratification) § 1c. This page is the evidence; that page is the decidable surface.

Reading this page today (annotation added 2026-09-07). The text above is preserved as written on 2026-07-25, when all eight were open. Four are now settled: D1–D4 were ratified on 2026-09-06 and Gate 1 is closed — see the Gate 1 ratification and the stamped § Gate 1 below. D5–D8 remain open and unchanged. Options recorded below for the closed decisions stay in place as the record of what was considered, not as live choices.

Update 2026-10-02. Gate 2 is closed: D5 settled on (a) fork lineage with replace-in-place for user-owned recipes, and D6 on (a) keep both for v0.1.7 with the opt-in converter tracked as a follow-up. See the Gate 2 record. D7 and D8 remain open.

Verdict in one line

The direction is the natural next layer around Crosswalker’s existing primitives, but the generic reproducible-build sketch that produced it must not be implemented verbatim.

Question	Answer
Does it conflict with schema-as-primitive?	No — provided stored recipes stay canonical and schema-validated
Does it conflict with the closed 5-mechanism grammar?	No — provided the binding never gains row-dependent target behavior
Does it conflict with render(Recipe, ConceptIdentity)?	No — the binding sits around the pure function, not inside it
Does it conflict with the RecipeDocument preservation boundary?	No — it is the natural completion of it. (RecipeDocument is the wrapper that keeps a saved recipe byte-faithful to the original it was derived from, patching rather than rebuilding it.)
Does it conflict with artifact roles and authority?	No — provided the new objects stay subtypes, bindings, descriptors, and index state
Can it be implemented as originally sketched?	No — eight decisions below are load-bearing and unanswered

Illustration 1 — it is a join, not a chain

The roadmap currently reads source bytes → reusable configuration → output. That is ontologically wrong: source bytes do not produce the recipe. They are independent inputs joined by a binding.

Source snapshotExact Tier 0 bytes + digest

Recipe revisionCanonical ImportRecipe

Parser selectorsSheet / header / iterator / filter

Destination + policyRoot path, skip/replace/error

→

Recipe bindingIntent only. No outcomes.

→

Runparse → render() → generate → validate → merge

Canonical Tier 1Managed knowledge representation

Execution RecordLater. Reports what happened.

inputs join at the binding · the binding never transforms rows

Illustration 2 — five digests, five different questions

The single biggest correction. The existing computeRecipeHash() at src/generation/hash.ts is not a recipe-artifact digest, and must not be repurposed as one.

recipe_document_digestWhich exact portable recipe revision is this?New

effective_target_hashDid output-affecting target behavior change?Exists today

source_byte_digestWhich exact pre-parse source bytes?New

binding_digestWhich exact locked input set?New

concept_cidWhich concept, before render() ran?Exists today

overloading any one of these breaks drift diagnosis

metadata.based_on.hash currently stores the effective target hash of an ancestor. Silently redefining it would break existing ancestry semantics.

Illustration 3 — what is allowed to live where

Recipe

Intended behavior

• layout mechanisms
• also_emit / body
• enrichment
• graph_edges, linkStyle
• source compatibility declaration
• ancestry

Binding

Selected inputs

• recipe revision digest
• source identity
• parser id + version
• decode selectors
• destination root
• write policy

Execution Record

Later. Outcomes

• execution id
• start/end, status
• actor
• output inventory
• validation results
• warnings

Local index

Rebuildable state

• favorites, recency
• display order
• active pointer
• retained/missing status
• locator hints
• last proof time

no new root artifact nouns · index state never becomes authority

Illustration 4 — the decision gates

These are this register’s own gates. The sibling primitives reconciliation register (the log tracking proposed upgrades to the core building blocks every imported note is made of) has its own three gates — Gate 1 — schema fields, Gate 2 — cleanup, Gate 3 — language — and its Gate 1 must land before D1 below. Always name the register when citing a gate.

Gate 1

Blocks the design specD1 · Hash taxonomy + wire syntaxD2 · Binding parameter surfaceD3 · Replay-equivalence profileD4 · Source retention model

Gate 2

Blocks v0.1.7 shippingD5 · Revision vs fork lineageD6 · SavedConfig coexistence

Gate 3

Blocks v0.1.8D7 · Retire audit-snapshot manifestD8 · Signed-git default vs opt-in

gate 1 must close before any storage or UI code

The eight open decisions

Gate 1 — before the design specification

Sequencing: D1 must be decided after the primitives reconciliation register’s Gate 1 (schema fields), because adding Tier 1 fields after digests are locked would invalidate stored hashes.

Ratified 2026-09-06 — Gate 1 is closed. The options below are preserved as the record of what was considered; the owner’s answers are:

#	Ratified answer
D1	(a) a separate recipe_document_digest; every existing hash and ancestry field keeps its current meaning and stored value; sha256-<hex> is the only accepted syntax
D2	(a) a closed set of explicit parser, destination, and write-policy override fields; no arbitrary or free-form parameters
D3	(a) equivalence of Crosswalker-managed content, excluding run metadata that legitimately changes and user-owned edits. Tightened: byte-identical whole files are neither promised nor implemented as an opt-in check now
D4	(c) verified reselection and optional retained copies with explicit per-binding status. Tightened: explicit opt-in is required before any retained copy of a source file is stored, unconditionally; ordinary in-memory parsing is not what this gates. Location, quota, and the mobile path remain separate open questions

Full rationale and non-commitments: Gate 1 ratification. This unblocks the design specification only — nothing below has been implemented, and D5–D8 remain open.

#	Decision	Options	Connects to
D1	Hash taxonomy. Add a full canonical recipe digest (a fingerprint identifying the exact recipe revision) without disturbing the existing effective-target hash (which answers only “did output-affecting behavior change?”). Also pick one wire syntax.	(a) new recipe_document_digest field, leave recipe.hash alone; (b) rename recipe.hash to effective_target_hash with migration. Syntax: keep sha256-<hex> everywhere, or allow sha256:<hex>	v0.1 schema spec · Terminology · Recipe fidelity · spec/tier1.schema.json, spec/recipe.schema.json, src/generation/hash.ts
D2	Binding parameter surface. A binding is the record joining a saved recipe to the specific inputs it ran against: which file, which sheet, where output goes, what to do on conflict. A free-form parameter bag would create a hidden sixth mechanism.	(a) closed parser/destination/policy union only, no general parameters; (b) additive Recipe Schema change declaring typed parameter slots	Target-structure synthesis · Hierarchy primitives · ETL and import
D3	What “exact replay” promises. Byte-identical whole files are not currently achievable because produced_at, producer version, and user_preserve (the regions of a note the user owns and the tool must never overwrite) all vary.	(a) managed-projection equivalence, excluding execution-scoped provenance and user-owned regions; (b) byte-identical only into a clean destination	Conventions · Consistency models · src/generation/provenance.ts, src/generation/frontmatter-merge.ts
D4	Source retention. A hash verifies bytes; it does not recover them.	(a) retain bytes by default in a content-addressed store; (b) verified reselection only; (c) both, with explicit per-binding status. Plus: vault-visible vs plugin-private, quota, license/privacy warnings	Ontology lifecycle · Acquire · System architecture · v0.1.7 milestone

Gate 2 — before v0.1.7 ships

#	Decision	Options	Connects to
D5	Lineage semantics. Today, customizing a recognized recipe forks it to <id>-custom with based_on ancestry. An “active revision pointer” would blur that.	(a) storage snapshots only, keep fork semantics; (b) true revision chains per logical recipe; (c) both, explicitly distinguished	Recipe fidelity · Artifact roles · src/import/recipe-document.ts
D6	SavedConfig coexistence. SavedConfig is the older “remember my setup” object. Legacy saved setups are fingerprint-bound convenience state, not portable recipes.	(a) keep both, no migration; (b) explicit opt-in convert with blocker reporting; (c) deprecate new SavedConfig creation	UI lexicon · UI parity audit · v0.1 schema spec

Gate 3 — before v0.1.8

#	Decision	Options	Connects to
D7	Audit manifest overlap. Earlier audit research proposed a snapshot manifest.json whose fields now overlap the Execution Record (the record of what one run actually did) plus the Package Manifest (the record of what a distributed bundle contains).	(a) retire the audit-specific manifest; (b) keep it as a package_kind: audit-snapshot Package Manifest; (c) keep three contracts (not recommended)	Artifact roles · v0.1.8 milestone · Ch 28 deliverable C
D8	Signed git: default or opt-in. The v0.1 stack pivot committed to git plus signed commits (a cryptographic guarantee that a change came from a specific, verifiable person) as the audit floor; the current v0.1.8 page makes signing opt-in.	(a) restore signed-by-default; (b) keep opt-in and downgrade public language from “audit trail” to “version history”	v0.1 stack pivot · v0.1.8 milestone · Tradeoffs

Settled — do not relitigate

Already decided	Where
The binding role exists and is not a new artifact family	Artifact roles and authority
Execution Record and Package Manifest stay separate and later	Artifact-role synthesis
RecipeDocument.original is preservation authority; save the patched canonical recipe, never the editor model	Recipe fidelity synthesis
Source paths, URLs, and byte hashes stay out of ImportRecipe	spec/recipe.schema.json source block
source.version is a compatibility declaration; verified run facts outrank it	v0.1 schema spec
Retained bytes stay Tier 0 inputs, never Tier 1 authority or Knowledge Sets	System architecture
Direct Tier 1 producers stay first-class without any recipe or replay binding	ETL and import
Every lifecycle capability needs a UI; config is the escape hatch	UI parity audit
MappingSet identity stays independent of parser column mapping	Artifact roles and authority
Save and replay is infrastructure for version migration, not the migration loop itself	Ontology evolution

Implementation gaps the audits surfaced

These are facts about the current code, not decisions. They become work once Gate 1 closes.

Gap	Where
sha256Hex() takes a string; exact source hashing needs a byte-oriented path	src/generation/hash.ts
Generation call sites never pass sourceHash, though provenance can emit it	src/generation/generation-engine.ts, src/generation/provenance.ts
Draft resume reparses the current file with no digest comparison	src/import/import-wizard.ts
Drafts persist only the selected sheet; header row, JSON iterator, and filter are dropped	src/import/draft-store.ts
Destination and write policy live in workflow state, not in any durable binding	src/import/draft-store.ts
Mobile storage for retained bytes is unproven and currently scheduled at RC	v0.1-RC milestone

Roadmap correction to make

The linear acceptance chain appears in three places and should be restated as the join shown in Illustration 1:

• Roadmap index
• Milestone hub
• v0.1-RC milestone
• ROADMAP.md at the repo root

What happens after Gate 1 closes

1. Write the Crosswalker-native design specification in .workspace/, with worked examples and acceptance cases.
2. Implement identity and binding primitives, test-first, no storage or UI.
3. Add portable storage and the retained-object store, mobile-proven.
4. Build the library and replay UI.
5. Prove full NIST CSF 2.0 and NIST SP 800-53 replay.

Small sequential waves, reviewed between each. Not one large fan-out.

Related

• Gate 1 ratification (2026-09-06) — the owner’s answers to D1–D4, what is locked, and what remains unbuilt
• Owner review queue — the single checklist of everything awaiting the owner’s ratification; D1–D8 restated as executive decision cards
• Primitives reconciliation — decision register — the sibling log tracking proposed upgrades to the core building blocks every imported note is made of; its Gate 1 (schema fields) must land before D1 here
• Artifact roles and authority — the concept page defining which artifact is allowed to assert what; the model these decisions must not violate
• Artifact roles and authority synthesis — build sequence this register refines
• Portable ImportRecipe fidelity — the preservation boundary being completed
• Target-structure synthesis — closed grammar and the render() coupling point
• ETL and import — schema-as-primitive and the two producer modes
• Ontology lifecycle — Acquire, Shape, and Maintain context
• Ontology evolution — the migration loop this only lays groundwork for
• Terminology — Recipe, binding, RecipeDocument, Tier definitions
• v0.1.7 milestone — where Gate 1 and Gate 2 land
• v0.1.8 milestone — where Gate 3 lands