feat(diff): structural schema diff + migration SQL

[seonghobae]

Independent PR against main (split out of #440). Now also contains the merged stack: #468 (migration-safety risk classification) and #484 (down-migration direction=down).

• Name-keyed structural diff (diff/schema_diff.py, oid-independent): GET /diff?against=
• Migration SQL (ddl/migration.py): GET /migration.sql?against=&dialect=&direction=up|down — up and rollback are exact mirrors
• Migration safety: GET /migration-safety?against= — safe/warning/destructive per change, has_destructive/has_blocking
  IDOR-safe. backend +23 tests; mypy clean.

🤖 Generated with Claude Code

[opencode-agent]

OpenCode Review Overview

• Head SHA: dc44afaefd9a1cfd32e3d6d82361ed0c489676f4
• Workflow run: 29098613855
• Workflow attempt: 1
• Gate result: APPROVE (approval step)

Pull request overview

OpenCode reviewed the current-head bounded evidence and found no blocking issues.

Findings

No blocking findings.

Summary

Approval sufficiency: bounded evidence supplied affirmative approval evidence for changed files, coverage/docstring posture, risk surfaces, and current-head verification; approval is not based merely on the absence of known blockers.
Verification posture: CodeGraph evidence was initialized and bounded current-head evidence reviewed for changed-file evidence including backend/app/api/snapshots.py, backend/app/ddl/migration.py, backend/app/ddl/migration_safety.py, backend/app/diff/init.py, backend/app/diff/schema_diff.py, and 7 more.
Linter/static: workflow/static review evidence is bounded by the current-head GitHub Checks gate and changed-file evidence.
TDD/regression: coverage execution evidence and focused changed hunks were reviewed from bounded-review-evidence.md.
Coverage: coverage execution evidence reports supported repository test suites passed.
Docstring coverage: coverage execution evidence reports configured repository docstring gates passed or docstring coverage was advisory.
DAG: CodeGraph/source-backed behavior map connects backend/app/api/snapshots.py to the affected review, runtime, or workflow path and required checks.
PoC/execution: coverage-evidence job executed on the current head and reported PASS.
DDD/domain: workflow and repository-governance invariants were reviewed against changed files in bounded evidence.
CDD/context: CodeGraph evidence, changed-file history, and focused hunks were reviewed from bounded-review-evidence.md.
Similar issues: changed-file history evidence was reviewed for comparable local precedents.
Claim/concept check: bounded evidence, repository source, current-head workflow evidence, and, where numeric, scientific, statistical, or literature-backed claims are affected, original-paper/formula evidence and parameter-recovery expectations were used for claims.
Standards search: standards and external-source checks are delegated to configured OpenCode web_search/Context7/DeepWiki sources when applicable; no evidence-backed standards blocker is present in bounded evidence.
Compatibility/convention: changed workflow/script conventions, object naming, and reserved-word safety for schema/API/config/code surfaces were checked in bounded evidence.
Breaking-change/backcompat: deployment evidence and changed-file history were checked for backward-compatibility risk.
Performance: changed surfaces were checked for performance risk in bounded evidence.
Developer experience: changed automation, review, test, setup, and maintenance surfaces were checked for helpful or obstructive DX impact in bounded evidence.
User experience: connected user, operator, API, CLI, documentation, review-comment, status-check, rendering, and workflow-reader behavior was checked for contradictions against code, docs, and tests in bounded evidence.
Visual/DOM: Playwright visual, DOM locator, ARIA snapshot, console, and responsive evidence were checked when a web UI surface was present; for non-web surfaces, API/CLI/log/docs/workflow interaction evidence was reviewed instead.
Accessibility/i18n: accessibility, localization, and human-readable text surfaces were checked where UI, CLI, API message, docs, logs, or review text changed.
Supply-chain/license: dependency, package, model, container, and external-tool changes were checked in bounded evidence.
Packaging: package, build, test, lint, and security contracts were checked in bounded evidence.
Security/privacy: workflow-token, review-gate, and repository-automation security/privacy boundaries were checked in bounded evidence.

• Result: APPROVE
• Reason: The PR introduces structural schema diff and migration SQL functionality with comprehensive tests and coverage.
• Head SHA: dc44afaefd9a1cfd32e3d6d82361ed0c489676f4
• Workflow run: 29098613855
• Workflow attempt: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Backend (12 files)"]
  S1 --> I1["API and service runtime"]
  I1 --> R1["Review risk: Backend (12 files)"]
  R1 --> V1["backend tests"]

Loading

[seonghobae]

🔀 Rebased onto origin/main (now at 174b0f4) to clear the merge conflict — branch went from CONFLICTING → MERGEABLE.

Conflicts (both in the import/declaration blocks, resolved by keeping BOTH sides):

• backend/app/schemas.py — main added WideTablesOut; this PR adds SnapshotDiffOut / MigrationSafetyOut. Kept all three.
• backend/app/api/snapshots.py — merged the from app.schemas import (...) list and the module imports so main's NamingLintOut/lint_naming/detect_wide_tables and this PR's diff_snapshots/snapshot_diff_to_migration_sql/analyze_migration_safety all coexist.

The IDOR-safe authorization (independent _get_authorized_snapshot on base + target, uniform not_found to prevent existence enumeration) is fully preserved. No security remediation dropped; no changes to main's naming-lint/wide-table features.

Verification: net diff vs main is exactly the PR's feature set (only backend/ diff/migration files, +1367). Focused suites green — test_schema_diff, test_migration, test_migration_safety, test_down_migration, test_api_snapshot_diff (23 passed) plus main's test_naming_lint (5 passed). All changed Python compiles.

🤖 Rebase performed by Claude Opus 4.8.

[opencode-agent]

Pull request overview

OpenCode reviewed the current-head bounded evidence and found no blocking issues.

Findings

No blocking findings.

Summary

Approval sufficiency: bounded evidence supplied affirmative approval evidence for changed files, coverage/docstring posture, risk surfaces, and current-head verification; approval is not based merely on the absence of known blockers.
Verification posture: CodeGraph evidence was initialized and bounded current-head evidence reviewed for changed-file evidence including backend/app/api/snapshots.py, backend/app/ddl/migration.py, backend/app/ddl/migration_safety.py, backend/app/diff/init.py, backend/app/diff/schema_diff.py, and 7 more.
Linter/static: workflow/static review evidence is bounded by the current-head GitHub Checks gate and changed-file evidence.
TDD/regression: coverage execution evidence and focused changed hunks were reviewed from bounded-review-evidence.md.
Coverage: coverage execution evidence reports supported repository test suites passed.
Docstring coverage: coverage execution evidence reports configured repository docstring gates passed or docstring coverage was advisory.
DAG: CodeGraph/source-backed behavior map connects backend/app/api/snapshots.py to the affected review, runtime, or workflow path and required checks.
PoC/execution: coverage-evidence job executed on the current head and reported PASS.
DDD/domain: workflow and repository-governance invariants were reviewed against changed files in bounded evidence.
CDD/context: CodeGraph evidence, changed-file history, and focused hunks were reviewed from bounded-review-evidence.md.
Similar issues: changed-file history evidence was reviewed for comparable local precedents.
Claim/concept check: bounded evidence, repository source, current-head workflow evidence, and, where numeric, scientific, statistical, or literature-backed claims are affected, original-paper/formula evidence and parameter-recovery expectations were used for claims.
Standards search: standards and external-source checks are delegated to configured OpenCode web_search/Context7/DeepWiki sources when applicable; no evidence-backed standards blocker is present in bounded evidence.
Compatibility/convention: changed workflow/script conventions, object naming, and reserved-word safety for schema/API/config/code surfaces were checked in bounded evidence.
Breaking-change/backcompat: deployment evidence and changed-file history were checked for backward-compatibility risk.
Performance: changed surfaces were checked for performance risk in bounded evidence.
Developer experience: changed automation, review, test, setup, and maintenance surfaces were checked for helpful or obstructive DX impact in bounded evidence.
User experience: connected user, operator, API, CLI, documentation, review-comment, status-check, rendering, and workflow-reader behavior was checked for contradictions against code, docs, and tests in bounded evidence.
Visual/DOM: Playwright visual, DOM locator, ARIA snapshot, console, and responsive evidence were checked when a web UI surface was present; for non-web surfaces, API/CLI/log/docs/workflow interaction evidence was reviewed instead.
Accessibility/i18n: accessibility, localization, and human-readable text surfaces were checked where UI, CLI, API message, docs, logs, or review text changed.
Supply-chain/license: dependency, package, model, container, and external-tool changes were checked in bounded evidence.
Packaging: package, build, test, lint, and security contracts were checked in bounded evidence.
Security/privacy: workflow-token, review-gate, and repository-automation security/privacy boundaries were checked in bounded evidence.

• Result: APPROVE
• Reason: The PR introduces structural schema diff and migration SQL functionality with comprehensive tests and coverage.
• Head SHA: dc44afaefd9a1cfd32e3d6d82361ed0c489676f4
• Workflow run: 29098613855
• Workflow attempt: 1

Changed-File Evidence Map

flowchart LR
  PR["PR changed files"] --> Evidence["OpenCode bounded evidence"]
  Evidence --> S1["Backend (12 files)"]
  S1 --> I1["API and service runtime"]
  I1 --> R1["Review risk: Backend (12 files)"]
  R1 --> V1["backend tests"]

Loading