Design — Remediating Zero Bespoke Tables Violation (GAP-01)

Related Gap: GAP-01 — kazi and Materra tables not mapped to canonical primitives AGENTS.md Mandate: Mandate 1 — Zero bespoke tables: "NEVER create module-specific tables (e.g. materra_, kazi_). All domain entities MUST be mapped directly into the existing canonical base infrastructure: claim, truth_node/truth_edge, resource/resource_edge, integration_entity." Status: DESIGN — design document for remediation

1. Problem Statement

KaziSasa vertical (V8 in the commercial catalog) and potentially Materra have created module-specific tables (kazi_, materra_) that violate the zero-bespoke-tables mandate. These fork the data model, making federation, audit, and cross-vertical collaboration point-to-point wiring that cannot be governed or audited as one platform.

The apps/agent-bff/src/kazisasa-bff-routes.js is a "thin compat shim" with no data-plane logic, routing through ERPNext REST via Camel. The full kazi-app and kazi-composable-template-routes implementation was not verified in this read.

2. Remediation Strategy

2.1 Map All KaziSasa Entities to Canonical Primitives

Every KaziSasa endpoint must map to one of the canonical kinds:

2.2 Delete or Rename Any kazi_ / materra_ Tables

Audit the SurrealDB schema for any tables named:

• kazi_*
• materra_*
• Any table not in the canonical list: claim, truth_node, truth_edge, resource, resource_edge, integration_entity, resource_graph_node, resource_graph_edge, universal_mirror, sync_audit, bridge_config, event_queue, interface_catalog, type_catalog, scope, delegation, scope_hierarchy, type_registry, execution_path_spec, execution_session, step_receipt, lifecycle_event, compliance_gate, compliance_stage, compliance_eval, admin_region, region_cover, targeted_event, boundary_rule, boundary_event, app_definition, permission_vocab, role, role_assignment, permission_grant, secret_registry, rotation_log, quorum, quorum_sig, integration_registry, durable_outbox

Any tables not in the canonical list must be:

1. Dropped if they can be expressed as canonical kinds, OR
2. Migrated to the canonical kind with a data migration script, OR
3. Kept only if absolutely unmappable — but this requires stopping and asking the user per mandate 1

2.3 Update All KaziSasa Routes to Use Canonical Planes

Update apps/agent-bff/src/kazisasa-bff-routes.js (and any successor files) to:

1. Claim creation: Use fn::claim_processing::create_claim or equivalent canonical function, NOT create a kazi_* table
2. Claim transitions: Use the guarded transition operations on the claims plane, NOT vertical-specific logic
3. Outbox enqueue: Use the canonical outbox envelope, NOT a vertical-specific outbox
4. Proof recording: Use fn::lifecycle::start_poce_session, fn::lifecycle::record_poce_step, fn::lifecycle::finalize_poce_session — these are horizontal functions, not vertical
5. Integration entity dual-write: Use fn::integration::upsert_entity to write to integration_entity alongside any legacy writes (best-effort, never blocking)

2.4 Ensure Scenario Packs Are Declarative, Not Hardcoded

Kazi scenario packs (journey definitions, panel configurations, SLA windows, quorum bands) must be declared in the NATS KV buckets SOVEREIGN_SCENARIOS or SOVEREIGN_LOOKUPS, NOT hardcoded in JavaScript. The verify-kazi-headless-api.mjs script should validate that all scenario packs are loaded from KV at runtime.

Pattern:

• Pack definitions in datasets/scenarios/kazi/*.yaml or similar
• Seeded via scripts/seed-nats-kv-declarative.mjs into SOVEREIGN_SCENARIOS
• Read at runtime from NATS KV, NOT from fs.readFile paths

2.5 Add Validation and Guardrails

1. Schema validation: Add SurrealDB schema checks that reject any CREATE TABLE with name matching kazi_ or materra_ patterns (except the canonical tables)
2. Route guard: Add a middleware check in the BFF that rejects any route handler attempting to write to a non-canonical table
3. CI check: Add a script that scans the codebase for kazi_ or materra_ table references and fails the build if found (unless mapped to canonical kind in documentation)

3. Migration Script Design

Create a migration script scripts/migrate-kazi-to-canonical.surql that:

1. Reads all existing kazi_* rows
2. For each row, determines the canonical mapping:

• kazi_health → integration_entity with entity_type = "kazi_health" and appropriate normalized_data
• kazi_claim_ → claim with claim_type = "cns://claim/type/kazi/..." and traits mapped from kazi_ traits
• kazi_truth_* → truth_node + truth_edge with appropriate CNS names

1. Creates canonical rows
2. Marks legacy rows as migrated (adds migrated_to_canonical: true field, or moves to a migrations_log table)
3. Outputs a report of what was migrated, what was unmappable (requires user stoppage)

Important: The migration must be best-effort. If any kazi_* row cannot be mapped to a canonical kind, the script must STOP and ask the user, not silently skip or invent data.

4. Interface Contract

All KaziSasa external interfaces must conform to the canonical contract:

Claim creation request:

{
  "claim_type": "cns://claim/type/kazi/...",
  "traits": ["assignable", "time_bound", "completable", "blockable"], // or relevant subset
  "payload": { /* claim-specific data */ },
  "link_to_graph": true // always true — must also create graph link
}

Claim transition request:

{
  "transition_from": "draft", // or relevant state
  "transition_to": "submitted",
  "actor": "user_id_or_service_id",
  "guards": "declarative_guard_check", // from scenarios plane
  "proof": "poce_session_ref" // optional but recommended
}

Integration entity dual-write:

{
  "service": "kaza-api",
  "external_id": "crew_12345", 
  "entity_type": "crew_member",
  "sovereign_id": "crew_12345", // or a sovereign-generated UUID
  "sovereign_type": "claim",
  "tenant_slug": "kazi",
  "normalized_data": { /* canonical subset */ },
  "raw_data": { /* original data */ },
  "metadata": { "migrated_from": "kazi_crew_members", "migration_timestamp": "..." }
}

5. Validation Checklist

After remediation, verify:

• [ ] No kazi_ or materra_ tables exist in SurrealDB (or have been migrated)
• [ ] All KaziSasa routes map to canonical claim, truth_node, truth_edge, resource, or integration_entity
• [ ] All scenario packs are loaded from NATS KV at runtime, not from disk
• [ ] The verify-kazi-headless-api.mjs script passes all 9 gates
• [ ] No route handler creates a non-canonical table or writes to a non-canonical field
• [ ] The codebase scan for kazi_ / materra_ table references fails (as it should — all are mapped canonically)
• [ ] Dual-write to integration_entity is best-effert (LET $_ = ...) but never blocks the legacy write

6. Dependencies

This design depends on:

• AGENTS.md mandates 1, 2, 4 (zero bespoke, declarative-first, no runtime FS reads)
• Existing canonical functions: fn::claim_processing::create_claim, fn::integration::upsert_entity, fn::lifecycle::*
• NATS KV buckets SOVEREIGN_SCENARIOS and SOVEREIGN_LOOKUPS properly seeded
• SurrealDB schema already deployed with canonical tables
• The verify-kazi-headless-api.mjs script and its imported helpers