Skip to content

Reconcile active SQL schema ownership with migration truth matrix guard - #2683

Open
groupthinking with Codex wants to merge 3 commits into
mainfrom
codex/audit-007-reconcile-sql-models
Open

groupthinking with Codex wants to merge 3 commits into
mainfrom
codex/audit-007-reconcile-sql-models

Conversation

@Codex

@Codex Codex AI commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Canonical issue

Issue linking is handled by repository automation.

Outcome

This PR addresses schema-drift ambiguity by replacing legacy assumptions with a current, explicit SQL ownership matrix. It adds a guard that fails when production model columns, migration SQL, and documented mapping diverge.

Scope

  • Included: docs/MIGRATION_TRUTH.md now contains a machine-readable active model→migration matrix, production/non-production domain classification, RLS/tenant boundary evidence, and Alembic status.
  • Included: tests/unit/test_migration_truth_matrix.py enforces studio_chats mapping and column parity across chat-store.ts, Supabase migration SQL, and documented matrix.
  • Included: explicit classification of shared_sql_state tables as runtime-managed (create_all) non-production schema surfaces.
  • Explicitly excluded: new SQL migrations, destructive schema changes, deployment-time DB reconciliation, and dependency/version changes.
{
  "production_domains": [
    {
      "table": "studio_chats",
      "migration_file": "apps/web/supabase/migrations/20260912214530_create_private_studio_chat_ownership.sql",
      "rls": "enabled+forced"
    }
  ]
}

Risk

  • Risk level: low
  • Failure mode: stale matrix metadata or contract drift causes guard failures until mapping is updated.
  • Rollback: revert docs/MIGRATION_TRUTH.md and tests/unit/test_migration_truth_matrix.py.

Verification

List exact automated and manual checks, tied to the current head SHA.

  • Focused tests
  • Required CI
  • Review threads resolved

Production evidence

Not applicable: documentation/test guard change only; no runtime behavior or production state transition.

Agent handoff

  • One canonical issue is linked
  • No competing PR implements the same issue
  • Acceptance criteria are satisfied
  • Required checks pass on the current head
  • Human decision is requested only for product, security, irreversible infrastructure, or production approval

Security dependency evidence

  • Advisory: Not applicable (no dependency changes).
  • Package and versions: Not applicable.
  • Validation: Secret scan run on changed files; no findings.
  • Rollback: Revert this PR.

@vercel

vercel Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
v0-uvai Ready Ready Preview, v0 Nov 16, 2026 6:13pm UTC

Co-authored-by: groupthinking <154503486+groupthinking@users.noreply.github.com>
@Codex Codex AI changed the title [WIP] Reconcile SQL models with migration files to address schema drift Reconcile active SQL schema ownership with migration truth matrix guard Nov 16, 2026
@Codex
Codex AI requested a review from groupthinking November 16, 2026 15:56
@github-actions github-actions Bot added documentation Improvements or additions to documentation python labels Nov 16, 2026
@github-actions

Copy link
Copy Markdown
Contributor

🔍 PR Validation

⚠️ PR title should follow conventional commits format

@groupthinking
groupthinking marked this pull request as ready for review November 16, 2026 18:38
Copilot AI max review requested due to automatic review settings November 16, 2026 18:38
@groupthinking
groupthinking enabled auto-merge (squash) November 16, 2026 18:39
Comment on lines +54 to +57
def _extract_studio_columns_from_chat_store(chat_store: str) -> set[str]:
match = re.search(r"const columns = '([^']+)';", chat_store)
assert match, "Expected `const columns = '...';` in chat-store.ts"
return {value.strip() for value in match.group(1).split(",")}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding or renaming a required field in rowSchema leaves this drift guard green because it reads only the SELECT column string, not the model contract.

Fix on Vercel

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Production-reachable tables are incorrectly exempted from migration coverage, while the guard can miss schema, table-inventory, and security-policy drift.

6 open issues
What changed in this PR

Documents SQL schema ownership and adds a source-level drift guard for UVAI’s Studio persistence and internal orchestration state, addressing part of AUDIT-007 (#2169). No runtime code or SQL migrations change.

Changes:

  • Replaces the obsolete inventory with a machine-readable ownership matrix.
  • Records shared runtime table classifications, tenant boundaries, row-level security, and Alembic status.
  • Adds checks comparing Studio chat columns across migration SQL, the application’s query projection, and documentation.
File Description
tests/​unit/​test_migration_truth_matrix.py Adds column-parity and required matrix-metadata checks.
docs/​MIGRATION_TRUTH.md Defines the ownership matrix, security notes, and guard scope.

Review effort: Max

Comment thread docs/MIGRATION_TRUTH.md
Comment on lines +40 to +46
"non_production_domains": [
{
"service": "internal runtime shared SQL state",
"table": "shared_sessions",
"owner_file": "src/youtube_extension/services/shared_sql_state.py",
"migration_strategy": "runtime_create_all",
"status": "allowed_non_migrated"
Comment on lines +55 to +57
match = re.search(r"const columns = '([^']+)';", chat_store)
assert match, "Expected `const columns = '...';` in chat-store.ts"
return {value.strip() for value in match.group(1).split(",")}
Comment on lines +67 to +70
production_by_table = {
entry["table"]: entry for entry in matrix["production_domains"] if "table" in entry
}
assert "studio_chats" in production_by_table
Comment on lines +76 to +79
assert studio_entry.get("rls") == "enabled+forced"
assert studio_entry.get("tenant_boundary") == "owner_subject + service_role access"

migration_sql = MIGRATION_PATH.read_text(encoding="utf-8")
assert studio_entry.get("rls") == "enabled+forced"
assert studio_entry.get("tenant_boundary") == "owner_subject + service_role access"

migration_sql = MIGRATION_PATH.read_text(encoding="utf-8")
Comment on lines +89 to +99
non_prod_by_table = {
entry["table"]: entry
for entry in matrix["non_production_domains"]
if "table" in entry
}
for table_name in ("shared_sessions", "shared_timeline_events", "shared_a2a_messages"):
assert table_name in non_prod_by_table
assert non_prod_by_table[table_name]["migration_strategy"] == "runtime_create_all"
assert non_prod_by_table[table_name]["owner_file"] == str(
SHARED_SQL_STATE_PATH.relative_to(REPO_ROOT).as_posix()
)

This branch was successfully deployed

1 active deployment
Preview — 4f22dc25 Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[AUDIT-007] Reconcile SQL models with migration files (schema drift)

4 participants