Phase 1 Design Freeze Evidence Matrix

Status: PASS (Phase 1 evidence gate for compatibility patch scope) Last updated: 2026-03-29

Scope

This artifact tracks Phase 1 evidence-gate requirements from session plan.md:

Storage/index overhead estimates
Hot-path query impact
Determinism/constraint enforceability
Blast radius inventory

Decision Log

2026-03-29: Deferred the real GitLab studio-mcp pipeline run until end-of-pass (explicitly requested). Local dry-run evidence remains valid as interim signal.
2026-03-29: Closed Phase 1 evidence gate for the current compatibility patch scope after green runtime benchmarks and concrete DDL delta capture.

Baseline Metrics (2026-03-29)

Storage and Schema Surface

Migration files under db/migrations/20251207_001_initial_schema: 44 files (inventory baseline).
Legacy type-based identity references across key graph SQL files: 121 matches.
- Query used: rg for type_namespace/type_name and statement namespace/name fields in:
  - 301_graph_resource.sql
  - 302_graph_statement.sql
  - 303_graph_functions.sql
  - 307_graph_permissions.sql
  - 308_graph_permission_functions.sql
  - 309_graph_rls_policies.sql
  - 310_graph_workspace_view.sql
  - 311_graph_query.sql
external_id references across the same key graph SQL files: 35 matches.

Path Usage Signal

Path/ltree-oriented references across key graph SQL files: 75 matches.
Direct examples from 301_graph_resource.sql:
- graph.resource.external_id column
- unique_resource constraint on (type_namespace, external_id)
- idx_resource_external_id index

Code Blast Radius (Packages)

Affected package pool scanned:
- packages/graph-module-model
- packages/graph-module-compile
- packages/graph-module-engine
- packages/studio-mcp
Total files in pool: 170
Semantics-related references (kind/path/external_id/predicate predicates): 238 matches

Hot-Path Query and Function Surface (Static Baseline)

Key graph query functions in 311_graph_query.sql: 8 function definitions
- graph.resource_filters_to_predicates
- graph.statement_filters_to_predicates
- graph.query_resources (multiple overloads)
- graph.query_statements (multiple overloads)
Key workspace-scoped graph access functions in 310_graph_workspace_view.sql: 5 function definitions
- graph.get_workspace_resources
- graph.count_workspace_resources
- graph.get_workspace_entity_by_id
- graph.get_workspace_resources_by_types
- graph.is_resource_in_workspace
Key permission-path functions in 308_graph_permission_functions.sql: 14 function definitions
- includes graph.compute_permission, graph.has_permission, graph.check_access and cache-refresh functions.
Core graph CRUD/query functions in 303_graph_functions.sql: 12 function definitions
- includes create/get/update/delete paths for resources and statements.

Migration Overhead (Concrete DDL Delta for Current Patch)

Patch set evaluated:

20260328_004_create_resource_idempotent.sql
20260328_005_create_resource_id_collision_recovery.sql
20260329_006_collection_predicate_signature_compat.sql
20260329_007_collection_helper_signature_compat.sql

Aggregate DDL delta:

Function redefinitions: +8 (CREATE OR REPLACE FUNCTION)
Index DDL: +0
Table/constraint DDL: +0
Net storage/index overhead for this patch set: none (function-body compatibility only)

Area	Baseline Signal	Implemented Delta	Confidence	Notes
Resource identity path	`graph.create_resource` core behavior in 303	+2 function redefs	High	Idempotency + explicit-id collision recovery via forward migrations
Collection helper path	Legacy positional helper calls in collection SQL	+6 function redefs	High	Signature-compat updates for get/create/list/set helper functions
Statement/index physical shape	`unique_statement` + existing indexes	0	High	No index/table changes in this patch set
Resource/index physical shape	`unique_resource` + existing indexes	0	High	No index/table changes in this patch set
Permission policy tables	Existing predicate-policy/cache structures	0	High	No schema/index changes; runtime behavior adjusted in service layer

Runtime Hot-Path Evidence

Command executed:
- pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts --reporter=verbose
Initial outcome:
- 1 failed, 11 passed, total duration 19.08s.
Latest outcome (rerun after collection helper compatibility migrations):
- 12 passed, 0 failed, total duration 18.29s.
Signals captured:
- Resource create behavior is idempotent for duplicate (type_namespace, external_id) requests and covered by contract assertion.
- Collection helper signature compatibility is restored via forward migrations redefining collection helper function calls to current core graph signatures.
Interpretation:
- Hot-path benchmark execution path is stable and green with collection operations validated under success semantics.
- Phase 1 runtime evidence no longer depends on expected-error collection assertions.

Focused Timing Slices (2026-03-29)

Statement pagination workflow probe:
- Command: pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts -t "should support path filtering and statement pagination workflows" --reporter=verbose
- Result: 1 passed, 11 skipped; targeted test runtime 1539ms; total command duration 4.95s.
Traversal workflow probe:
- Command: pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts -t "should traverse outgoing and incoming edges with depth constraints" --reporter=verbose
- Result: 1 passed, 11 skipped; targeted test runtime 1328ms; total command duration 5.08s.
Permission router probe:
- Command: pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph.router.test.ts -t "permissionRouter" --reporter=verbose
- Result: 1 passed, 6 skipped; targeted test runtime 1320ms; total command duration 5.51s.
- Note: No permission output-validation or undefined-function diagnostics observed in latest focused run.

Gate Close Verification (Consolidated)

Command:
- pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts integration-tests/graph.router.test.ts --reporter=dot
Result:
- Test Files: 2 passed (2)
- Tests: 19 passed (19)
- Duration: 24.89s
Interpretation:
- Consolidated DB-contract plus router-contract verification is green for the current Phase 1 compatibility patch scope.

Gate Revalidation (Post-Phase-2 Forward Fix)

Command:
- pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts integration-tests/graph.router.test.ts --reporter=dot
Result:
- Test Files: 2 passed (2)
- Tests: 19 passed (19)
- Duration: 35.28s
Interpretation:
- Phase 1 evidence gate remains green after Phase 2 forward-migration fixes (20260329_011/20260329_012).

Gate Revalidation (Post-Bundle Refresh)

Commands:
- pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/db-bootstrap.db-contract.test.ts integration-tests/db-migrations.db-contract.test.ts --reporter=dot
- pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts integration-tests/graph.router.test.ts --reporter=dot
Result:
- Test Files: 2 passed (2) and 2 passed (2)
- Tests: 10 passed (10) and 19 passed (19)
- Duration: 7.93s and 32.78s
Interpretation:
- Phase 1 evidence gate remains green after migration bundle refresh and focused rerun.

Evidence Classification

Requirement	Status	Evidence	Notes
Storage/index overhead estimates	BASELINED	SQL reference baseline + concrete DDL delta counters captured	Current patch set is function-only (+8 redefinitions, 0 index/table changes)
Hot-path query impact	BASELINED	Static inventory + green runtime benchmark command captured	Runtime command passes (12/12) with collection helpers running against current signatures
Determinism/constraint enforceability	PARTIAL	studio-mcp contract suite + fixture lock + coverage map pass	DB/model deterministic constraints still pending in Phase 2/4/5
Blast radius inventory	BASELINED	SQL + package match counts captured	Use as denominator for migration PR slicing

Verification Commands (Executed)

rg --files db/migrations/20251207_001_initial_schema | sort
rg legacy type-identity fields in key SQL files | wc -l => 121
rg external_id in key SQL files | wc -l => 35
rg path/ltree variants in key SQL files | wc -l => 75
rg semantics fields in target packages | wc -l => 238
rg --files in target packages | wc -l => 170
rg function/query surface in 303/308/310/311 graph SQL files (hot-path baseline)
rg index/constraint baseline in 301/302/307/309/310 graph SQL files
pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts --reporter=verbose
pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts -t "should support path filtering and statement pagination workflows" --reporter=verbose
pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts -t "should traverse outgoing and incoming edges with depth constraints" --reporter=verbose
pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph.router.test.ts -t "permissionRouter" --reporter=verbose
pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts integration-tests/graph.router.test.ts --reporter=dot
pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts integration-tests/graph.router.test.ts --reporter=dot (post-Phase-2 revalidation: 19/19)
pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/db-bootstrap.db-contract.test.ts integration-tests/db-migrations.db-contract.test.ts --reporter=dot (post-bundle refresh: 10/10)
pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/graph-db-functions.db-contract.test.ts integration-tests/graph.router.test.ts --reporter=dot (post-bundle refresh: 19/19)
rg/awk aggregate DDL counters across 20260328_004, 20260328_005, 20260329_006, 20260329_007 migrations (function_redefinitions_total=8, index_ddl_total=0, table_constraint_ddl_total=0)

Next Actions

Carry remaining schema-shape and deterministic-model enforcement work into Phase 2/4/5 migration phases; this artifact is closed for Phase 1 compatibility scope.