Epic: prove Notion sync contracts across datasource, .nmd, and React owned-region rendering

Context

Follow-up to #775 and umbrella for #798, #797, #796, and #790.

This branch establishes the intended VRS hierarchy:

• context/notion-sync-architecture/ is the stack-wide Notion sync VRS root.
• 01-shared-sync-contract/ owns shared vocabulary and evidence semantics, not a shared engine.
• 02-realizations/01-datasource-markdown-workspace/ owns the datasource + .nmd workspace realization.
• 02-realizations/02-react-owned-region/ keeps React in the stack while preserving its owned-region renderer semantics.
• 03-verification-and-evidence/ is the home for cross-realization proof.

This epic is the implementation and proof pass that should follow that VRS settlement.

Goal

Make the Notion sync system principled enough that shared concepts are single-sourced and reusable, while preserving the different authority models:

• datasource Markdown workspace: shared bidirectional local workspace, no silent LWW, fail-closed writes,
• NotionMD: standalone .nmd page editing/sync contracts and the body/property primitives consumed by the workspace page-file surface,
• React: owned-region JSX renderer/reconciler with explicit overwrite semantics inside its owned region.

The goal is not to force one sync engine. The first reusable layer is contracts, evidence shapes, guard/result vocabulary, and verification. A shared implementation can be extracted only where at least two realizations prove they need the same mechanism.

Phase checklist

• Phase 1: VRS traceability and residual cleanup (#796, #797)
• Phase 2: Property mutation evidence (#798)
• Phase 3: Body convergence boundary and dry-run proof (#797, #798)
• Phase 4: React shared-contract participation without authority collapse (#798)
• Phase 5: NotionMD test architecture cleanup (#790)
• Phase 6: Public package boundary and telemetry audit
• Phase 7: Validated shared contract extraction

Sequencing decision

Phase 1 is a blocking prerequisite for contract-changing work in Phases 2, 3, 4, 6, and 7. Those phases should not start until VRS traceability is clean enough that each implementation change has a stable requirements/spec/decision home.

Phase 5 (#790) may proceed independently because it is test-harness hygiene and should not change the architecture contract.

What counts as proof

A proof must be more than matching prose. At least one of the following must exist and be linked from the VRS or scenario metadata:

• deterministic unit tests for pure contracts,
• fake-service integration tests proving realization behavior,
• fixture/golden tests where the artifact is the reviewed contract,
• dry-run tests with instrumented fakes proving no durable mutation occurred,
• live-workspace evidence when local proof is impossible, with the live gap explicitly tracked,
• production code usage plus a regression test that would fail if the claimed evidence disappeared.

Paper-only alignment is not enough to graduate a shared contract.

Workstreams

1. Finish VRS traceability and residual cleanup

Related: #796, #797.

Tasks:

• Treat context/notion-sync-architecture as the canonical stack-wide VRS root.
• Keep package VRS docs as refinements of the stack root and their realization nodes.
• Update or close stale open questions such as transactional createReplicaSchema if already implemented.
• Remove references to deleted proposed decision ledgers.
• Ensure scenario metadata does not point generically at docs/vrs/spec.md when an executable test exists.
• Split true fixture/live-lane gaps into concrete follow-up issues.
• Keep .decisions/ as the live VRS decision convention and avoid visible decisions/ under Notion VRS docs.

Acceptance:

• rg 'notion-db-markdown-sync|docs/vrs/decisions|decisions/proposed' context packages/@overeng/notion-* shows only expected historical prose or no matches.
• VRS links resolve for changed Notion VRS docs.
• Package docs clearly state whether they refine the stack root, datasource Markdown realization, or React owned-region realization.

2. Make property mutation evidence real

Related: #798.

Current issue: the shared property-write core exists, but providers still have weak evidence paths.

Tasks:

• notion-datasource-sync stops deriving propertyType from the desired value.
• Observed Notion schema/property type is threaded through datasource planner snapshots/proofs.
• notion-md stops using placeholder desired values such as { _tag: 'empty' } for writable types where tag-fit safety is claimed.
• notion-md constructs real canonical desired values through the shared codecs or fails closed when unsupported.
• Type/config-specific guards are preserved for files, relations, options, status, people, and other write classes.
• Persisted proof formats, telemetry attributes, fixtures, and golden expectations are audited for assumptions about the weaker proof shape.

Acceptance:

• Tests fail if datasource planner proof lacks an observed Notion property type/config.
• Tests fail if NotionMD claims a writable value through an empty placeholder where a concrete canonical value is required.
• Shared property-write tests prove the same observed-schema evidence shape is accepted from at least datasource-sync and NotionMD.
• Any proof-format or telemetry change is documented as public, internal, or migration-free.

3. Clarify and prove the body convergence boundary

Related: #797, #798.

Current issue: body is mostly single-surface and adapter-owned, but there is a forward-looking convergence rail that should not be mistaken for full body unification.

Tasks:

• Keep the current VRS stance: body is single-surface and adapter-owned unless a later decision changes it.
• Remove/demote dormant body-body convergence claims, or make the dormant rail production-observable and resolvable before any second body surface is wired.
• Add dry-run/materialization proof for .nmd body paths where coverage is still weak.
• Add dry-run/materialization proof for object/attachment storage where coverage is still weak.

Acceptance:

• Docs and scenario metadata do not claim active body unification beyond what production does.
• Body dry-run tests use instrumented fakes or observable stores to prove no durable mutation to Notion, filesystem, SQLite, outbox, settlement state, or object storage when dry-run is selected.
• If body-body-delegated remains, it has a clear user resolution story or is explicitly documented as not product-reachable.

4. Bring React into the shared contract without collapsing authority models

Related: #798.

React overlaps mechanically: desired tree, cache/base, digesting, drift, fallback, mutation plan, checkpointing. Its authority model differs: it owns a rendered region and may overwrite manual edits inside that region.

Tasks:

• Map React surface identity concepts to shared vocabulary where useful.
• Map React digest spaces to shared vocabulary where useful.
• Map React desired/base/observed snapshots to shared vocabulary where useful.
• Map React checkpoints to shared vocabulary where useful.
• Map React mutation plans/results to shared vocabulary where useful.
• Map React drift/fallback outcomes to shared vocabulary where useful.
• Keep React renderer-specific LCS diffing, host config, page operation ordering, cache persistence, and owned-region overwrite semantics package-local.
• Add contract tests or snapshots showing which shared terms React refines and which datasource shared-mode semantics it intentionally rejects.

Acceptance:

• React VRS and tests participate in shared vocabulary without claiming the datasource planner or NotionMD clean-base adoption path.
• React owned-region overwrite semantics are documented as incompatible with datasource shared-mode no-silent-LWW semantics.
• A test or fixture demonstrates that React does not silently adopt datasource shared-mode clean-base/conflict assumptions.
• Any future shared code extracted for React is mechanism-free or separately justified by a decision.

5. Clean up NotionMD test architecture

Related: #790.

Tasks:

• Converge repeated NotionMdGateway fake implementations onto a shared harness pattern.
• Replace incidental full-body byte assertions with semantic equivalence where byte identity is not the behavior under test.
• Add one golden/fixpoint around demo/showcase.nmd so intentional canonical-body changes have a single review point.

Acceptance:

• Adding a gateway method no longer requires synchronized edits across many test-local fake classes.
• Body tests distinguish semantic behavior from byte-stability behavior.
• The showcase fixture has one intentional golden/fixpoint assertion.

6. Audit public package boundaries and telemetry semantics

Any shared contract or vocabulary extraction must be explicit about API status.

Tasks:

• Decide whether each new contract is package-internal, exported from an existing package, or a new shared package/module.
• Update changelog entries for public or semi-public surface changes.
• Keep telemetry/event names low-cardinality and realization-aware.
• Avoid names that imply one shared engine when the contract is only shared vocabulary or evidence.

Acceptance:

• Every new export has an owner and stability story.
• Telemetry and verification events identify realization and outcome without leaking private content or implying false engine unification.
• Changelog entries distinguish docs-only, internal, and public API changes.

7. Validate candidate shared vocabulary/contracts

This is deliberately last. The following are candidates to validate, not pre-approved abstractions.

Candidate tasks:

• Validate or reject SurfaceIdentity.
• Validate or reject DigestSpace.
• Validate or reject BaseSnapshot, DesiredSnapshot, and ObservedSnapshot.
• Validate or reject Checkpoint.
• Validate or reject GuardResult, ConflictResult, and FallbackReason.
• Validate or reject MutationCommand and ApplyResult.
• Validate or reject low-cardinality verification/telemetry event shapes.

Non-goals until proven:

• Do not create one shared sync engine.
• Do not create one shared Notion gateway.
• Do not create one shared cache or SQLite store.
• Do not make React use datasource planner semantics.
• Do not make datasource shared mode inherit React owned-region overwrite semantics.

Acceptance:

• A shared contract is introduced only with at least two realization proofs or an explicit decision explaining why it is still worth centralizing.
• Package-local mechanisms remain local unless the VRS and tests prove common semantics.
• Candidate names that fail to get proof are removed from the VRS or explicitly marked deferred.

Done when

• The VRS hierarchy is current and package docs point at the right root/realization.
• Shared property mutation safety is evidence-driven across providers.
• Body sync claims match production behavior and dry-run proof is falsifiable.
• React is integrated into the shared contract layer while preserving its owned-region model.
• NotionMD tests have one reusable fake gateway pattern and less incidental byte brittleness.
• Any shared sync package or module is contract-first and backed by at least two realizations.

Posted on behalf of @schickling

field	value
agent_name	🕸️ co3-chasm
agent_session_id	d3d43740-7120-482f-9bb7-30220ad0a577
agent_tool	Codex CLI
agent_tool_version	0.140.0
agent_runtime	Codex CLI 0.140.0
agent_model	unknown
runtime_profile	/nix/store/k125mrp5qn2yy7izvvxmxjkv4zlf71w0-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/w4ngydqypq1g9dmcr011xc5yyvc42rcc-agent-skills-corpus/share/agent-skills/manifest.json
worktree	effect-utils/schickling/2026-06-17-notion-refactor
machine	dev3
tooling_profile	dotfiles@9aa40af

Start with the VRS root at context/notion-sync-architecture/ and the prerequisite issues #796 and #797 before examining packages/@overeng/notion-* and the related realization work. Use the phase acceptance checklists as the completion criteria: proofs and tests must support the documented contracts without collapsing datasource, NotionMD, and React authority models.