Savvi Studio

Phase 3 Work Package: Deterministic Constraints and Canonical Graph Contract Alignment

Status: PASS (checkpoint 2 complete) Date: 2026-03-29

Objective

Advance from Phase 2 cutover verification into a bounded Phase 3 implementation slice that hardens deterministic DB contracts and removes remaining legacy graph namespace assumptions in high-signal integration tests.

Bounded Scope

  1. Canonical graph contract alignment in integration tests.
  • Update graph contract assertions and fixtures to prefer canonical fields/semantics (kind, path, predicate_path) over legacy namespace assumptions where those assumptions are now obsolete.
  1. Deterministic constraint enforcement signal preservation.
  • Preserve and verify deterministic behavior for IDs and audit patch helpers.
  • Preserve RLS/predicate-policy semantic guarantees while moving assertions to canonical contract language.
  1. Forward migration only if required.
  • Add a single forward migration only when implementation reveals a real contract mismatch that cannot be addressed at test/contract-call level.
  • No destructive or compatibility-window rollback behavior.

In-Scope Files

  1. integration-tests/graph-access-control.db-contract.test.ts
  2. integration-tests/graph-db-functions.db-contract.test.ts
  3. docs/reference/modules/phase-2-cutover-handoff-2026-03-29.md
  4. Optional forward migration in db/migrations if test-driven gap requires it.

Out of Scope

  1. Rewriting baseline historical schema files under db/migrations/20251207_001_initial_schema.
  2. Non-graph unrelated workflow suites.
  3. Backward-compat alias restoration.

Acceptance Checks

Run these before and after edits:

  1. pnpm vitest run --project integration-tests-node-pglite-memory integration-tests/db-ids.db-contract.test.ts integration-tests/db-audit.db-contract.test.ts integration-tests/graph-access-control.db-contract.test.ts --reporter=dot
  2. 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
  3. 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

Baseline Snapshot (Pre-Implementation)

  1. Command (1) current baseline:
  • Test Files 3 passed (3)
  • Tests 15 passed (15)
  • Duration 10.43s

Progress Checkpoint 1 (Post-Edit)

Implemented change:

  1. Updated graph access-control contract tests to use canonical graph columns in direct SQL assertions (kind, path, predicate_path) instead of legacy type_namespace/predicate assumptions.

Post-edit acceptance results:

  1. Command (1): Test Files 3 passed (3), Tests 15 passed (15), Duration 11.44s.
  2. Command (2): Test Files 2 passed (2), Tests 19 passed (19), Duration 34.86s.
  3. Command (3): Test Files 2 passed (2), Tests 10 passed (10), Duration 7.39s.

Objective alignment status:

  1. Canonical graph contract alignment: on track.
  2. Deterministic constraint enforcement signal preservation: on track.
  3. No Phase 1/2 gate regression: on track (acceptance suite remains green).

Progress Checkpoint 2 (Hard-Rename Stabilization)

Implemented changes:

  1. Completed full hard rename of graph function parameter contracts to canonical p_kind/*_kind naming in migration sources and regenerated contract bindings.
  2. Added forward-only migrations for already-migrated environments to force signature/body convergence:
  • db/migrations/20260329_013_function_param_kind_hard_rename.sql
  • db/migrations/20260329_014_create_resource_kind_collision_recovery.sql
  • db/migrations/20260329_015_create_resource_kind_collision_recovery_v2.sql
  • db/migrations/20260329_016_collection_helpers_kind_arg_forward_fix.sql
  1. Resolved remaining 42883 undefined_function failures caused by stale function-body named-argument metadata in persistent migration state.

Post-stabilization acceptance results:

  1. Command (1): Test Files 3 passed (3), Tests 15 passed (15), Duration 10.48s.
  2. Command (2): Test Files 2 passed (2), Tests 19 passed (19), Duration 30.93s.
  3. Command (3): Test Files 2 passed (2), Tests 10 passed (10), Duration 7.83s.

Objective alignment status:

  1. Canonical graph contract alignment: complete for this bounded slice.
  2. Deterministic constraint enforcement signal preservation: complete for this bounded slice.
  3. Forward migration policy: satisfied (forward-only migrations used for replay-safe convergence).
  4. Phase 1/2 gate compatibility: preserved (acceptance triplet remains green).

Broader integration slice revalidation:

  1. Command:
  • 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 integration-tests/db-error-handling.workflow.test.ts integration-tests/graph-db-functions.db-contract.test.ts integration-tests/graph-access-control.db-contract.test.ts integration-tests/graph.router.test.ts integration-tests/entities-crud.profile.workflow.test.ts --reporter=dot
  1. Result:
  • Test Files 7 passed (7)
  • Tests 70 passed (70)
  • Duration 45.32s
  1. Interpretation:
  • Hard-rename and forward convergence changes remain stable on the broader verification slice, not only the minimal acceptance triplet.

Exit Criteria

  1. Acceptance checks pass post-implementation.
  2. No regression in Phase 1 and Phase 2 gate docs/evidence.
  3. Any migration added is forward-only and justified by failing contract evidence.