Rust Rewrite with Deck Federation and Yaml Deck Source

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2

.envrc

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+
+eval "$(devenv direnvrc)"
+use devenv

.frontloop/AUDIT-REMEDIATION.md

@@ -0,0 +1,98 @@
+# Brain Brew audit remediation program
+
+Source of truth: `audit/16-synthesis.md`, supported by `audit/01-flow-map.md` through `audit/15-release-security.md`.
+
+This file defines cross-epic ordering. Within each epic, ready-task numeric prefixes are strict sequence, not estimates of parallel safety. A task whose Implementation Notes names a clarification or another epic must not start until that prerequisite is resolved.
+
+## Epics
+
+1. `release-baseline` — immutable versions, extracted crate verification, Nix, release gating, trusted channels.
+2. `canonical-source-integrity` — fail-closed YAML, one source-document interface, recoverable transactions, safe CLI output.
+3. `core-compose-correctness` — semantic field values, expected bases, tombstones, messages, semantic diff, typed errors.
+4. `package-federation-security` — contained/authenticated packages, bounded fetches, one planner, media provenance.
+5. `workbench-hardening` — containment, typed contract, security, CAS/preview/transactions, complete UI, bounded caches.
+6. `translation-integrity` — structural content policy, compositional ownership, explicit deletion/adaptation, shared mutation policy.
+7. `crowdanki-roundtrip` — Unicode identity, GUID/ordinal validation, reviewable import, media handoff, equivalence/reconciliation.
+8. `ultimate-geography-production` — real-consumer canonical/media/translation/parity/package/release baseline.
+9. `quality-docs-observability` — truthful ADRs/docs, initialization, executable examples, generated/fuzz/mutation/platform/budget gates.
+10. `architecture-performance` — later structural deepening and measured optimization after correctness stabilizes.
+
+## Phase 0 — decisions and immediate containment
+
+Resolve these clarification gates before starting their dependent tasks:
+
+- Release version and supported channels.
+- Replacement precondition representation and typed tombstone model.
+- Package symlink, compatibility-version, and release-media policies.
+- Workbench trust/transaction scope.
+- Structural field-name, strict translation ownership, and blank translation policies.
+- UG fixture contract and legacy workflow disposition.
+- Public Rust crate support commitment.
+- Existing `default/clarify/7500` for Anki-to-existing-source reconciliation.
+
+Immediate code containment that does not wait for every decision:
+
+1. `workbench-hardening/0010` — mark Apply experimental or make release Workbench read-only.
+2. `canonical-source-integrity/0010` — reject duplicate dynamic keys.
+3. `package-federation-security/0010` — central safe-relative-path authorization.
+4. `core-compose-correctness/0010` — semantic field values.
+5. `ultimate-geography-production/0010` — pinned/reconciled consumer baseline.
+6. `quality-docs-observability/0010` — make ADRs and architecture records truthful.
+
+## Phase 1 — integrity foundations
+
+These streams may proceed in parallel, preserving each epic's numeric order:
+
+- `canonical-source-integrity/0010–0040`: strict decoding, source documents, transactions.
+- `core-compose-correctness/0010–0050`: value semantics, preconditions, tombstones, messages, complete diff.
+- `package-federation-security/0010–0030`: path authorization, immutable lock schema, safe extraction.
+- `release-baseline/0010–0030`: version synchronization, extracted crates, Nix/E2E separation.
+- `crowdanki-roundtrip/0010–0020`: imported stable IDs and identity validation.
+
+Exit: no silent source loss, no unauthenticated package-tree reads, destructive composition has complete regression coverage, and package artifacts can be verified independently.
+
+## Phase 2 — shared mutation, planning, and Workbench safety
+
+1. Complete `canonical-source-integrity/0050–0070`.
+2. Complete `package-federation-security/0040–0090`.
+3. Complete `translation-integrity/0010–0050` once its decisions are resolved.
+4. Complete `workbench-hardening/0020–0060`; remove read-only/experimental containment only after 0030–0060 pass.
+5. Complete `crowdanki-roundtrip/0030–0050`.
+6. Complete `core-compose-correctness/0060` with the typed Workbench contract.
+
+Exit: every mutator plans and validates before writing, uses canonical document operations, has recoverable commit semantics, and carries package/media provenance.
+
+## Phase 3 — production Ultimate Geography acceptance
+
+Follow `ultimate-geography-production/0020–0100` in order. Translation tasks 0050/0060 require the translation-integrity epic; golden tasks 0070/0080 require the complete CrowdAnki oracle; packaging and final consumer gate require media ownership and release verification policy.
+
+In parallel after their prerequisites:
+
+- `release-baseline/0040–0070`.
+- `quality-docs-observability/0020–0040`.
+
+Exit: actual UG—not only the fixture—formats, verifies all 74+26 targets with media, exports representative goldens, packages declared media reproducibly, and gates Brain Brew releases.
+
+## Phase 4 — product completeness
+
+- `workbench-hardening/0070–0110`: complete list/detail, drafts, bounded caches, accessibility/lifecycle, pivot removal.
+- `crowdanki-roundtrip/0060`: implement or deprecate existing-source reconciliation after `default/7500`.
+- Remaining executable docs and supported installation/Rust interface work.
+- Resolve/complete existing `default/ready/0150` cross-language matrix in coordination with Workbench pagination and translation ownership; do not duplicate it.
+
+## Phase 5 — architecture and long-horizon quality
+
+Only after affected behavior is stable:
+
+1. `architecture-performance/0010–0040` — typed paths and implementation splits.
+2. `architecture-performance/0050–0070` — measured composition, media, and list-index optimization.
+3. `quality-docs-observability/0050–0100` — property, fuzz, mutation, cross-platform, accessibility/performance, and public-crate gates.
+
+## Global delivery rules
+
+- Use red-green-refactor for every behavior change.
+- Each task must preserve deterministic canonical output and run the relevant Devenv gates.
+- Security/correctness tasks require the reproduced audit probe as a regression test.
+- Structural cleanup follows behavior fixes; do not mix mass refactors with semantic corrections.
+- Real UG acceptance is mandatory before release claims are restored.
+- Do not mark an epic done while any clarification that affects its shipped behavior remains unresolved.

.frontloop/_archive/DECISIONS-2026-07-11.md

@@ -0,0 +1,12 @@
+# Remediation decision record — 2026-07-11
+
+These decisions close the Frontloop clarification gates created by the audit-remediation plan.
+
+- **Release**: next preview is `1.0.0-alpha.2`. Supported channels are crates.io (manually published once gates pass), pinned GitHub release artifacts, and a pinned Nix flake/tag channel.
+- **Workbench**: local user-selected workspaces are trusted; the experimental local API may be reached by any local browser page; Apply rejects cross-root and cross-filesystem batches. This is not a release-safe browser trust boundary.
+- **Translations**: field-name translations are optional display labels and do not count toward required coverage by default. True Anki identifier renames require an explicit atomic validated operation. Ownership belongs to the overlay that introduces a unit; completeness is checked across the final target stack. Blank direct translations are invalid; explicit path-scoped deletion/adaptation intents are required.
+- **Ultimate Geography fixture**: Brain Brew maintains an exact pinned production snapshot plus explicit reviewed migration transform and requires fixture plus live-consumer gates. UG legacy workflow choices are out of scope for Brain Brew and belong to the external UG migration PR.
+- **Rust crates**: `brain-brew-core` and `brain-brew-formats` are implementation packages for alpha.2, without a supported public Rust API commitment.
+- **Core replacement safety**: complete replacements use canonical stable fingerprints; sparse changes use typed property-level expectations.
+- **Core tombstones**: typed entity/path variants remain canonical, with a compatibility reader for the prior flat representation.
+- **CrowdAnki pull-back**: defer the optional Anki/CrowdAnki-to-source workflow until a real maintainer requests it; it is not current Brain Brew scope.

.frontloop/_archive/canonical-source-integrity/done/0010-reject-duplicate-keys-in-every-dynamic-yaml-map.md

@@ -0,0 +1,50 @@
+---
+title: Reject duplicate keys in every dynamic YAML map
+priority: critical
+---
+
+## Goal
+
+Make canonical deck, overlay, translation, manifest, lock, and media-map decoders reject duplicate IDs or fields before any value is overwritten.
+
+## Acceptance Criteria
+
+- Duplicate keys fail at all dynamic map levels identified by the audit
+- Errors name the source file, schema path, and duplicate key where available
+- `fmt` and every mutator leave bytes unchanged on duplicate-key failure
+- Regression tests cover overlays, contextual translations, manifests, locks, media maps, notes, and targets
+- Canonical positive round trips remain byte-stable
+
+## Implementation Notes
+
+First implementation task in this epic; use TDD against the reproduced data-loss probes.
+
+
+## Completion Summary
+
+- Added recursive fail-closed duplicate-key detection before serde map deserialization
+- Wired strict duplicate validation through canonical decks, overlays/translations, manifests, locks, media maps, includes, CLI mutators, verify, and Workbench
+- Added source/schema/key diagnostics and byte-unchanged failure regressions
+- Added focused coverage for notes, targets, contextual translations, overlays, locks, manifests, media maps, and canonical round trips
+- Passed delegated fmt, 413-test non-browser suite, clippy, and independent Claude judgment
+
+### Files Changed
+
+- crates/brain-brew-formats/src/strict_yaml.rs
+- crates/brain-brew-formats/src/canonical_yaml.rs
+- crates/brain-brew-formats/src/manifest.rs
+- crates/brain-brew-formats/src/lockfile.rs
+- crates/brain-brew-formats/src/media_map.rs
+- crates/brain-brew-formats/src/source_includes.rs
+- crates/brain-brew-formats/src/lib.rs
+- crates/brain-brew-formats/tests/canonical_yaml.rs
+- crates/brain-brew-formats/tests/overlay_yaml.rs
+- crates/brain-brew-formats/tests/manifest_yaml.rs
+- crates/brain-brew-formats/tests/lockfile_yaml.rs
+- crates/brain-brew-formats/tests/media_map.rs
+- crates/brain-brew-cli/src/io.rs
+- crates/brain-brew-cli/src/commands/lock.rs
+- crates/brain-brew-cli/src/commands/media.rs
+- crates/brain-brew-cli/src/commands/verify.rs
+- crates/brain-brew-cli/src/commands/workbench.rs
+- crates/brain-brew-cli/tests/cli.rs

.frontloop/_archive/canonical-source-integrity/done/0020-validate-yaml-unions-and-scalar-types-before-conversion.md

@@ -0,0 +1,50 @@
+---
+title: Validate YAML unions and scalar types before conversion
+priority: critical
+---
+
+## Goal
+
+Reject conflicting, orphaned, or partial field/message/image/media alternatives and unintended YAML scalar coercions instead of accepting then discarding data.
+
+## Acceptance Criteria
+
+- Each union shape has exactly one valid representation
+- Conflicting or incomplete structured values fail with schema-location diagnostics
+- Boolean, null, and numeric scalars are rejected where canonical strings are required
+- Public emitters return errors rather than panic on constructible invalid map keys
+- A malformed-union matrix and hostile scalar corpus cover all decoder entry points
+
+## Implementation Notes
+
+Depends on duplicate-aware decoding so one strict decoder path owns all failures.
+
+
+## Completion Summary
+
+- Added fail-closed schema validation for malformed field, message, image, media, and overlay union representations
+- Rejected unintended boolean, null, and numeric coercion at canonical string positions while preserving intentional typed schema values
+- Added schema-path diagnostics and unchanged-byte CLI failure coverage
+- Made overlay, manifest, and lock emitters fallible and validated constructible invalid states instead of panicking
+- Added malformed-union/scalar matrices and preserved UG canonical formatting, idempotence, and all-target composition
+- Passed delegated fmt, full non-browser tests, clippy, focused fixture tests, and independent Claude judgment
+
+### Files Changed
+
+- crates/brain-brew-formats/src/strict_yaml.rs
+- crates/brain-brew-formats/src/canonical_yaml.rs
+- crates/brain-brew-formats/src/manifest.rs
+- crates/brain-brew-formats/src/lockfile.rs
+- crates/brain-brew-formats/src/media_map.rs
+- crates/brain-brew-formats/tests/yaml_schema_strictness.rs
+- crates/brain-brew-formats/tests/yaml_scalar_adversarial.rs
+- crates/brain-brew-formats/tests/emitter_roundtrip.rs
+- crates/brain-brew-formats/tests/overlay_yaml.rs
+- crates/brain-brew-formats/tests/ultimate_geography_fixture.rs
+- crates/brain-brew-cli/src/commands/diff.rs
+- crates/brain-brew-cli/src/commands/lock.rs
+- crates/brain-brew-cli/src/commands/translations.rs
+- crates/brain-brew-cli/src/commands/workbench.rs
+- crates/brain-brew-cli/tests/cli.rs
+- crates/brain-brew-cli/tests/media_includes.rs
+- crates/brain-brew-cli/tests/translations_cli.rs

.frontloop/_archive/canonical-source-integrity/done/0030-introduce-include-preserving-canonical-source-document-modules.md

@@ -0,0 +1,39 @@
+---
+title: Introduce include-preserving canonical source document modules
+priority: critical
+---
+
+## Goal
+
+Create deep `CanonicalSourceDocument` and `OverlaySourceDocument` modules in formats that expose validated edits while preserving include directives and canonical emission.
+
+## Acceptance Criteria
+
+- Deck and overlay documents preserve scalar/media includes through unrelated edits
+- Typed operations cover field, translation, media, and metadata changes needed by current mutators
+- All operations enforce duplicate, union, and canonical invariants
+- The interface returns source/schema-aware errors without filesystem dependencies
+- Round-trip and edit-locality tests demonstrate unchanged unrelated bytes or defined canonical changes
+
+## Implementation Notes
+
+Depends on strict decoders; this becomes the sole source-mutation seam for later tasks.
+
+
+## Completion Summary
+
+- Added pure include-preserving CanonicalSourceDocument and OverlaySourceDocument modules in brain-brew-formats
+- Kept YAML representation private while exposing typed metadata, field, translation, media, image, stale-resolution, and import construction edits
+- Routed included scalar/media edits to provenance-tagged outputs while preserving unrelated directives and canonical root bytes
+- Made edits atomic by validating cloned state before commit and reused strict duplicate/union/scalar/canonical invariants
+- Added exact-byte locality, include routing, source/schema diagnostics, translation/media/image, and idempotence tests
+- Passed focused formats tests, full repository tests, fmt, clippy, and independent Claude judgment
+
+### Files Changed
+
+- crates/brain-brew-formats/src/canonical_source_document.rs
+- crates/brain-brew-formats/src/overlay_source_document.rs
+- crates/brain-brew-formats/src/source_document.rs
+- crates/brain-brew-formats/src/source_includes.rs
+- crates/brain-brew-formats/src/lib.rs
+- crates/brain-brew-formats/tests/source_documents.rs

.frontloop/_archive/canonical-source-integrity/done/0040-build-a-journaled-recoverable-workspace-transaction-module.md

@@ -0,0 +1,40 @@
+---
+title: Build a journaled recoverable workspace transaction module
+priority: critical
+---
+
+## Goal
+
+Replace misleading sequential-renames atomicity with plan, validate, commit, rollback, and restart recovery for multi-file workspace writes.
+
+## Acceptance Criteria
+
+- All target files and expected fingerprints are validated before mutation
+- Commit records a journal and recoverable backups before the first replacement
+- Injected failures at every commit step either roll back or leave an explicit recoverable state
+- Cross-filesystem and external-include cases are rejected or handled according to a documented contract
+- Crash/restart recovery tests prove no silently mixed old/new workspace
+
+## Implementation Notes
+
+May be developed beside source-document modules; filesystem implementation belongs in CLI.
+
+
+## Completion Summary
+
+- Added a CLI-owned typed workspace transaction plan with canonical-root, target-type, duplicate, expected fingerprint/existence, and same-filesystem validation
+- Persisted durable journals, staged replacements, complete backups, commit progress, rollback state, and cooperative locking before replacements
+- Added deterministic failure injection across prepare, backup, replace, finalize, rollback, and restart recovery
+- Rejected external-root, cross-filesystem, symlink-escape, unsupported, and conflicting target plans under a documented fail-closed contract
+- Fixed judge-found stale rollback restore-stage recovery wedge and proved attacker-modified derived stages are discarded and regenerated from verified backups
+- Documented durability, platform, recovery, and migration contracts; left existing mutators unmigrated for tasks 0050/0060
+- Passed focused transaction tests, full fmt/test/clippy, parent full CI, and independent Claude re-judgment
+
+### Files Changed
+
+- Cargo.lock
+- crates/brain-brew-cli/Cargo.toml
+- crates/brain-brew-cli/src/main.rs
+- crates/brain-brew-cli/src/workspace_transaction.rs
+- documentation/docs/reference/workspace-transactions.md
+- documentation/sidebars.js

.frontloop/_archive/canonical-source-integrity/done/0050-migrate-formatting-and-translation-mutations-to-source-documents.md

@@ -0,0 +1,46 @@
+---
+title: Migrate formatting and translation mutations to source documents
+priority: high
+---
+
+## Goal
+
+Remove direct serde-value and line-surgery paths from `fmt` and translation insertion/resolution, using the canonical source-document and transaction modules.
+
+## Acceptance Criteria
+
+- Formatting and translation writes use typed document operations
+- Include-bearing files remain canonical after edits
+- All multi-file translation operations are plan-first and recoverable
+- Existing formatting/idempotence and stale-translation behavior remain green
+- Direct mutation implementations are deleted rather than retained as fallbacks
+
+## Implementation Notes
+
+Depends on source-document and transaction modules.
+
+
+## Completion Summary
+
+- Migrated canonical and overlay fmt paths to typed source documents with strict validation and canonical emission
+- Migrated all CLI translation apply, interactive/contextual insertion, stale confirm/replace/batch, and source-impact writes to typed overlay operations
+- Added plan-first affected-target composition validation, expected fingerprints, recovery-first behavior, and one journaled transaction per operation
+- Removed legacy YAML line-surgery, serde-value mutation, and direct command write fallback implementations
+- Preserved unrelated scalar includes, canonical idempotence, stale precedence, and shadowed current translation decisions
+- Documented canonical rewrite and transaction behavior; retained format-specific strict codecs where appropriate
+- Passed full fmt/test/clippy, focused CLI/formats/UG suites, and independent Claude judgment
+
+### Files Changed
+
+- crates/brain-brew-cli/src/commands/fmt.rs
+- crates/brain-brew-cli/src/commands/translations.rs
+- crates/brain-brew-cli/src/io.rs
+- crates/brain-brew-cli/src/main.rs
+- crates/brain-brew-cli/src/workspace_mutation.rs
+- crates/brain-brew-cli/src/workspace_transaction.rs
+- crates/brain-brew-cli/tests/cli.rs
+- crates/brain-brew-cli/tests/translations_cli.rs
+- crates/brain-brew-formats/src/overlay_source_document.rs
+- crates/brain-brew-formats/tests/source_documents.rs
+- documentation/docs/authoring/translations.md
+- documentation/docs/reference/workspace-transactions.md