Add safe Notion native status schema convergence

Problem

@overeng/notion-effect-schema can represent Notion native status properties, and notion schema generate-config / introspect / diff can observe and generate typed schemas. What is missing is a principled, safe way to converge a live Notion database's native status options and groups from code.

This matters for operator-facing Notion databases where the native status property is part of the product contract, not cosmetic view state. In those cases, manual setup creates an undocumented exception for the most visible field, while projector/runtime code still needs stable typed values.

Desired capability

Add a code-owned convergence path for native Notion status properties, including options and groups.

Principled shape:

• Desired status schema lives in the existing schema/IaC config surface, or a closely adjacent typed config surface consumed by notion schema.
• status convergence is explicit and opt-in per database/property; it must not silently mutate arbitrary status properties discovered during introspection.
• The implementation plans against freshly introspected live schema before any mutation.
• The planner classifies changes into safe additive/update operations vs destructive or ambiguous operations.
• Destructive or identity-ambiguous operations fail closed unless an explicit policy is provided.
• Application performs read-after-write verification and then runs the same schema diff path used by CI.
• The command supports dry-run/plan output suitable for code review and CI logs.

Suggested API / CLI surface

One possible shape:

// notion-schema-gen.config.ts
{
  id: '...',
  name: 'Deployments',
  output: 'src/generated/notion/deployments.ts',
  includeWrite: true,
  statusProperties: {
    Status: {
      groups: [
        { name: 'Active', color: 'yellow', options: ['Queued', 'Running'] },
        { name: 'Success', color: 'green', options: ['Published'] },
        { name: 'Problem', color: 'red', options: ['Blocked', 'Needs developer'] },
      ],
      options: {
        Queued: { color: 'gray' },
        Running: { color: 'yellow' },
        Published: { color: 'green' },
        Blocked: { color: 'red' },
        'Needs developer': { color: 'orange' },
      },
      policy: {
        createMissingOptions: true,
        renameByIdOnly: true,
        archiveOrRemoveExtraOptions: 'fail',
        regroupExistingOptions: true,
      },
    },
  },
}

CLI surface could be either:

notion schema plan --config notion-schema-gen.config.ts
notion schema apply --config notion-schema-gen.config.ts --database <id>
notion schema diff --config notion-schema-gen.config.ts --exit-code

or a narrower first command:

notion schema converge-status --config notion-schema-gen.config.ts --database <id> --property Status

Safety requirements

• Use stable Notion option/group IDs when known; never infer a rename from name-only collisions without making the ambiguity visible.
• If an option exists remotely but not in desired state, default to fail/diagnostic rather than delete/archive.
• If Notion's API does not support a desired operation for status groups/options, fail with an actionable unsupported-capability diagnostic.
• Preserve existing status values on pages unless an explicit migration policy maps old option IDs/names to new ones.
• Treat status group changes separately from option creation/update so partial support can be reasoned about.
• Produce structured plan output with property id, option ids, group ids, desired names/colors, live names/colors, and policy decision.

Acceptance criteria

• Unit tests cover planning for create, color update, regroup, extra remote option, ambiguous rename, missing group, and unsupported operation cases.
• Fake gateway/client tests cover the Notion update payloads without live credentials.
• A live e2e test or documented demo fixture proves: preflight introspection -> apply -> read-after-write -> schema diff clean.
• notion schema diff --exit-code can fail CI when native status options/groups drift from desired config.
• Generated typed schemas keep NotionSchema.status() / typed option unions aligned with the converged live property.
• Documentation explains when to use native status convergence vs plain select, and how to avoid destructive changes.

Notes

Relevant existing surfaces:

• @overeng/notion-effect-schema already models StatusPropertySchema with options and groups.
• notion schema generate-config, introspect, and diff already provide the right read/generate/drift-check foundation.
• @overeng/notion-datasource-sync already has the broader safety posture this should follow: observe first, plan explicitly, fail closed for unsupported surfaces, and verify after writes.

This issue is intentionally about native status schema convergence only. Notion view convergence should remain a separate surface.

Posted on behalf of @schickling

field	value
agent_name	🔭 co2-reach
agent_session_id	4d9a3e19-f884-47ec-ae33-97c3a2745f8a
agent_tool	Codex CLI
agent_tool_version	0.140.0
agent_runtime	Codex CLI 0.140.0
agent_model	unknown
runtime_profile	/nix/store/wbb5q5n2gbk751hcyr5ndp0zrmar602x-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/3i12shfqx3wqzq2di3jy1m7f8fn4prmm-agent-skills-corpus/share/agent-skills/manifest.json
worktree	schickling-stiftung/schickling-assistant/2026-06-19-stiftung-vrs-systems
machine	dev3
tooling_profile	dotfiles@unknown-dirty

Start by reading the existing StatusPropertySchema model and the notion schema generate-config, introspect, and diff surfaces, then review the safety patterns in @overeng/notion-datasource-sync. Done includes explicit plan/apply support for native status options and groups, fake gateway tests, read-after-write verification, clean schema diff behavior, and documentation of safe usage.