docs: align SchemaBot integration contract with execution-mode verdicts

[Kiran01bm]

Summary

Docs-only sweep aligning the public doc set with the latest internal low-level design. The one real drift was the SchemaBot integration contract: SchemaBot has since shipped per-statement execution-mode verdicts, a direct-execution policy, and engine-keyed consent copy, and docs/schemabot-integration.md — the designated single home for that contract — predated all of it.

What

• docs/schemabot-integration.md:
  • Plan returns TableChange{…, ExecutionMode, ModeReason} and maps a pg-sprite refusal to engine.ExecutionModeBlocked at plan time (previously misplaced under Apply).
  • Apply must re-resolve the routing decision at execution time rather than trusting the stored plan-time verdict.
  • New "Execution-mode verdicts and direct execution" section: the empty/blocked/direct verdict vocabulary, the v1 decision that PostgreSQL targets do not get direct_execution (the native route holds ACCESS EXCLUSIVE and blocks reads, so MySQL's risk framing does not transfer), plan-time-advisory / apply-time-re-resolve as OC-4, fail-closed partition ordering, the transactional-DDL advantage (LK-4), and the split-outcome consent-copy wording.
  • Fixed a broken TOC anchor.
• docs/low-level-design.md: the ALTER/DROP PRIMARY KEY refusal row regains its route decision — PK reshape goes through expand/contract; SchemaBot's small-table direct-execution answer is deliberately not adopted on PostgreSQL.

Why

The adapter contract shapes pg-sprite's verdict and plan surfaces long before the adapter exists; documenting the current upstream contract (verdict fields, TOCTOU discipline, ordering rules) keeps the seam accurate for both external users and the future integration. All upstream references were verified against block/schemabot main (pkg/engine/engine.go verdict vocabulary, docs/direct-execution.md § Engine compatibility).

References

• SchemaBot execution-mode verdicts / direct execution / consent copy: feat(engine): resolve plan-time execution-mode verdicts under the direct execution policy schemabot#886, feat(engine): execute direct-routed ALTERs as native MySQL DDL under the policy's lock bound schemabot#836, feat(github): disclose direct-execution changes and require manual confirmation schemabot#839
• https://github.com/block/schemabot/blob/main/docs/direct-execution.md#engine-compatibility

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.