Plan shared Notion domain and transport reuse architecture

Context

The Notion package VRS docs were aligned with current implementation reality on branch schickling/2026-05-25-notion-md-db. The review found recurring duplication and architectural pressure across NotionMD, datasource-sync, notion-react, notion-cli, @overeng/notion-effect-schema, and @overeng/notion-effect-client.

Existing related issue: #729 covers CLI descriptor/parser/help drift. This issue covers the broader domain and transport architecture.

Findings to address

• Decide which shared Notion identity/property/block concepts belong in @overeng/notion-effect-schema versus package-local domains.
• Make the lower Notion client boundary explicit: typed API/transport/decode failures versus today's datasource-sync gateway adapter receiving unknown client failures.
• Define whether canonical property capability descriptors should be shared, and how they map between raw Notion schema, datasource-sync planners, and .nmd frontmatter.
• Keep datasource-sync store/planner/outbox boundaries extractable without prematurely inventing public notion-domain or notion-sync-core packages.
• Preserve public API migration discipline for branded IDs and canonical value types.

Proposed milestone order

1. Characterization tests for current cross-package behavior before refactors.
2. Shared schema primitives only where contracts already exist or are easy to prove.
3. Gateway/client typed-error cleanup with adapter tests.
4. Property/block capability reuse behind explicit adapters.
5. Re-evaluate package extraction only after imports and tests show a stable boundary.

Open decisions

• Should branded Notion IDs become public API immediately, or stay decoder-internal during a transition?
• Should .nmd preserve author-written frontmatter shape over normalization when semantically equivalent?
• Should transport/decode errors become normative client API variants now, or remain gateway-local until implemented?

Verification expectations

Use focused unit/adapter tests first, then fake datasource-sync E2E and existing NotionMD/React regression tests. Avoid changing requirements-level VRS docs until decisions above are confirmed.

Start with characterization tests for current behavior across NotionMD, datasource-sync, notion-react, notion-cli, @overeng/notion-effect-schema, and @overeng/notion-effect-client. Trace the current client gateway, schema, planner, store, and outbox boundaries before making changes. Done means the open API, error, capability, and package-boundary decisions are resolved and focused unit, adapter, fake E2E, NotionMD, and React regression tests pass.