Declarative code-as-source-of-truth Notion DB schema convergence (schema IaC)

Problem

There is no code-as-source-of-truth path for Notion database schema: define a
database's schema (properties/columns, types, options) declaratively in code, then
plan / apply / reconcile the live Notion DB to match it.

Everything today points the other direction or is content-scoped:

• notion-cli schema generate/introspect/diff — Notion is authoritative; generates
  typed Effect schemas from a live DB and detects drift of the generated file.
• notion-datasource-sync — reconciles a local SQLite/.nmd replica against Notion
  rows/content, not a code-authored schema definition.

The result: a database whose structure is part of a product contract must be set up
by hand in the Notion UI, creating undocumented drift — the exact manual exception an
IaC path removes.

What already exists to build on

• NotionDatabases.create / update / retrieve (@overeng/notion-effect-client,
  src/databases.ts) — create a DB from a property map; PATCH property schema.
• Additive schema-write engine (@overeng/notion-datasource-sync,
  src/core/commands.ts): SchemaPatchOperation = AddProperty / RenameProperty
  (ID-preserving) / AddSelectOptions, base-schema-hash gated, fail-closed.
• Native status schema convergence — plan + apply with read-after-write verification
  (notion-cli/src/status-schema-plan.ts, status-schema-convergence.ts; see #803).
  This is a working converge loop for one property type; generalize it.
• Reverse-direction diff (notion-cli/src/diff.ts, computeDiff) — reusable, but its
  "desired" = Notion; a reconciler needs "desired" = the code definition (semantics
  need inverting; option-value diffing is currently stubbed).

Proposed shape

Consolidate the status-planner slice + the propDef converge surface (#827) into one
declarative path. Concrete surface (from #803):

notion schema plan  --config notion-schema.config.ts
notion schema apply --config notion-schema.config.ts --database <id>
notion schema diff  --config notion-schema.config.ts --exit-code   # CI drift gate

Settled posture (already the design intent across #803/#827): plan against freshly
introspected live schema, additive by default, fail-closed on destructive/ambiguous,
read-after-write verification, dry-run/plan output for review + CI.

Scope

• Definition → operation-set planner, including create-DB-from-definition (no such
  workflow today — schema only reads).
• Re-orient diff.ts so desired = code definition; implement option-value diffs.
• Additive property convergence incl. descriptions / formulas / basic views (#827).
• Generalize status convergence beyond the standalone slice.
• Destructive migrations (delete / type-change / option removal) stay deferred —
  gated on impact reports + explicit policy + live proof of Notion API behavior, per
  the existing datasource-sync capability-gaps posture. Status groups and some surfaces
  are Notion-API-limited regardless.

Related

• #803 — native status schema convergence (partial implementation; proposes the config + CLI)
• #827 — notion-effect-client converge path cannot emit descriptions / formulas / views
• #718 — datasource-sync schema/property authority model
• #734 — shared Notion domain/transport reuse architecture
• #698 — epic: productionize Notion datasource sync

Start with notion-cli/src/status-schema-plan.ts and status-schema-convergence.ts to understand the existing converge loop, then read notion-cli/src/diff.ts and notion-datasource-sync/src/core/commands.ts. Review NotionDatabases in @overeng/notion-effect-client/src/databases.ts for create/update/retrieve behavior. Done means a code-defined schema can plan, apply, diff, and verify additive convergence through the proposed CLI surface.