ai-contract-platform/project-docs/V2-phase3-ai-platform-tenant-trace-governance-2026-07-02.md

V2 Phase 3 AI Platform Tenant And Trace Governance

Date: 2026-07-02

Status

This slice adds the first AI Platform governance baseline for knowledge assets, AI Trace, and quality actions.

Completed:

1. Added migration 20260624_0019_add_tenant_trace_governance.py.
2. Added tenant_id to:
   • knowledge_documents
   • knowledge_import_batches
   • knowledge_chunks
   • knowledge_reindex_executions
   • knowledge_ingestion_jobs
   • ai_run_audits
   • ai_quality_improvement_actions
3. Added AI Trace governance fields to ai_run_audits:
   • redaction_status
   • redaction_policy
   • retention_until
   • archive_status
   • archived_at
4. Added tenant/governance indexes for high-frequency knowledge, trace, ingestion, and quality-action paths.
5. Updated SQLAlchemy models and DTO mappers.
6. Updated SQLAlchemy persistence to write and read the default tenant boundary.
7. Updated AI Platform runtime schema-check with:
   • tenant_columns
   • trace_governance_columns
8. Added/updated tests for schema-check, Trace response compatibility, and SQLAlchemy roundtrip persistence.

Compatibility

The original tenant/governance migration slice did not require frontends or callers to pass tenant IDs yet.

Current behavior:

• New rows default to tenant_id = "default".
• Existing rows are backfilled by migration defaults.
• AI Trace list/detail responses include governance fields with safe defaults.
• The API surface remains backward compatible for existing callers.

Follow-up completed on 2026-07-02:

• Request-level X-Tenant-Id context.
• Tenant-aware API filtering for knowledge documents, AI Trace, and quality actions.
• Cross-tenant AI Trace detail isolation with 404.
• Backward-compatible default tenant behavior when X-Tenant-Id is omitted.

Deferred to later slices:

• Tenant-aware auth/permission enforcement.
• Row-level security.
• Actual redaction job implementation.
• Retention/archive worker.
• Sensitive field encryption.

Validation

Local validation passed:

python -m py_compile `
  yuqei-ai-platform/services/ai-platform-api/src/yuqei_ai_platform_api/models.py `
  yuqei-ai-platform/services/ai-platform-api/src/yuqei_ai_platform_api/schema_check.py `
  yuqei-ai-platform/services/ai-platform-api/src/yuqei_ai_platform_api/persistence/audit.py `
  yuqei-ai-platform/services/ai-platform-api/src/yuqei_ai_platform_api/persistence/knowledge.py `
  yuqei-ai-platform/services/ai-platform-api/src/yuqei_ai_platform_api/persistence/quality.py `
  yuqei-ai-platform/services/ai-platform-api/src/yuqei_ai_platform_api/repository.py `
  yuqei-ai-platform/services/ai-platform-api/migrations/versions/20260624_0019_add_tenant_trace_governance.py

python -m pytest yuqei-ai-platform/services/ai-platform-api/tests/test_health.py -q
python -m pytest `
  yuqei-ai-platform/services/ai-platform-api/tests/test_provider_flow.py::test_legal_qa_uses_provider_answer_when_enabled `
  yuqei-ai-platform/services/ai-platform-api/tests/test_platform_data.py::test_sqlalchemy_repository_persists_platform_data -q
python -m pytest yuqei-ai-platform/services/ai-platform-api/tests -q

Result:

• AI Platform API tests: passed.

Remaining Items From Closure List

Done in this slice:

• AI Platform tenant fields for knowledge assets, AI Trace, and quality actions.
• AI Trace redaction/retention/archive metadata.
• Runtime schema-check coverage for these fields.

Still pending:

• Implement actual Trace redaction worker.
• Implement retention/archive worker.
• Delivery quality gates rerun.

Recommended Next Step

Continue with Trace redaction/retention/archive workers and delivery quality gates.

Smoke verification for this slice is recorded in:

• project-docs/V2-phase3-ai-platform-tenant-trace-governance-smoke-verification-2026-07-02.md

Request-level tenant context implementation and smoke verification are recorded in:

• project-docs/V2-phase3-ai-platform-request-tenant-context-2026-07-02.md

Provider/OCR secret ref compatibility and pgvector schema-check hardening are recorded in:

• project-docs/V2-phase3-provider-ocr-secret-ref-pgvector-schema-2026-07-02.md