# Contracts and Schema Blueprint_ Founder CRM and Platform Planning

**Date:** 2026-04-18  
**Status:** Draft  
**Owner:** Sagnik  
**Reviewers:** Sayan, Sourik  
**Scope:** Canonical artifact contracts for client graph, imports, interactions, writebacks, and approvals  
**Purpose:** Define the internal artifact contracts, schema boundaries, versioning rules, and validation strategy for the founder-side CRM and platform model.  
**Decision Boundary:** This document defines target contracts. It does not itself create runtime validators or database migrations.

## 1. Purpose

This contract system exists to stop Project Velocity from passing loosely structured lead and interaction data between subsystems with no canonical artifact shape.

## 2. Contract Design Principles

- preserve raw evidence and normalized projections separately
- make producer and consumer ownership explicit
- version artifacts from the start
- keep provenance and confidence attached to inferred data
- require approval-aware contracts for destructive or merging operations

## 3. Canonical Artifact Set

- `RawImportBatch`
- `ImportRowRecord`
- `ImportMappingManifest`
- `NormalizedEntityProposal`
- `ClientGraphDelta`
- `InteractionBundle`
- `TranscriptBundle`
- `QdSignalBundle`
- `OracleWritebackProposal`
- `ApprovalDecision`
- `Client360Snapshot`

## 4. Schema Rules

Required metadata for every artifact:

- `artifact_id`
- `artifact_type`
- `schema_version`
- `source_system`
- `created_at`
- `created_by`
- `confidence`
- `provenance`

Versioning model:

- semantic schema version per artifact family
- additive evolution preferred
- breaking changes require a new version and explicit reader mapping

## 5. Artifact Definitions

### `RawImportBatch`

- purpose: preserve the uploaded import exactly as received
- required fields:
  - `batch_id`
  - `source_system`
  - `uploaded_filename`
  - `mime_type`
  - `storage_ref`
  - `row_count`
  - `uploaded_by`
- validation rules:
  - immutable after upload

### `ImportMappingManifest`

- purpose: define how source columns map to canonical fields
- required fields:
  - `manifest_id`
  - `batch_id`
  - `source_profile`
  - `column_mappings`
  - `unmapped_columns`
  - `resolver_notes`
- validation rules:
  - every imported column is either mapped, ignored, or unresolved

### `NormalizedEntityProposal`

- purpose: represent AI-assisted structured projections before approval
- required fields:
  - `proposal_id`
  - `batch_id`
  - `entity_type`
  - `canonical_payload`
  - `confidence`
  - `merge_candidate_refs`
  - `review_required`
- validation rules:
  - cannot become committed data without an approval or low-risk auto rule

### `InteractionBundle`

- purpose: capture messages, calls, visits, and related communication artifacts for one interaction thread or event cluster
- required fields:
  - `bundle_id`
  - `client_ref`
  - `channel`
  - `event_refs`
  - `attachments`
  - `summary`
- validation rules:
  - must preserve raw event refs even when summarized

### `TranscriptBundle`

- purpose: group transcripts, speaker segmentation, timing metadata, and related media refs
- required fields:
  - `transcript_id`
  - `interaction_ref`
  - `media_ref`
  - `speaker_segments`
  - `language`
  - `text`
- validation rules:
  - speaker segmentation and timing metadata are first-class, not comments

### `QdSignalBundle`

- purpose: package QD-relevant signals and time-series projections
- required fields:
  - `signal_id`
  - `client_ref`
  - `source_ref`
  - `score_type`
  - `value`
  - `time_window`
  - `supporting_evidence_refs`
- validation rules:
  - every score must point back to evidence refs or explicit operator input

### `OracleWritebackProposal`

- purpose: capture an AI-suggested change from Oracle or NemoClaw before commit
- required fields:
  - `proposal_id`
  - `target_domain`
  - `target_entity_ref`
  - `proposed_change`
  - `reasoning_summary`
  - `evidence_refs`
  - `approval_required`
- validation rules:
  - writeback proposals never masquerade as committed state

### `ApprovalDecision`

- purpose: represent explicit human review outcome
- required fields:
  - `decision_id`
  - `proposal_ref`
  - `reviewer_ref`
  - `decision`
  - `decision_notes`
  - `decided_at`
- validation rules:
  - immutable audit record

### `Client360Snapshot`

- purpose: provide a stable read model for UI and Oracle
- required fields:
  - `client_ref`
  - `identity`
  - `account_links`
  - `active_opportunities`
  - `recent_interactions`
  - `property_interests`
  - `tasks`
  - `qd_overview`
  - `risk_flags`
- validation rules:
  - derived snapshot; never the sole source of truth

## 6. Storage Mapping

- raw batches and raw rows map to raw import storage plus structured index tables
- normalized proposals map to workflow/governance tables
- client graph deltas map to canonical domains
- interaction and transcript bundles map to `intel_*`
- snapshots map to materialized read models or service aggregation outputs

## 7. Validation Strategy

Service layer:

- validate schema presence and required metadata

Root layer:

- validate auth, ownership, and approval gates

Persistence layer:

- validate referential integrity and lifecycle rules

## 8. Compatibility Strategy

- additive extensions preferred
- preserve readers for older import manifests during transition
- all schema migrations should be tied to explicit artifact version upgrades

## 9. Implementation Order

1. raw import and mapping artifacts
2. normalized proposals
3. writeback and approval artifacts
4. interaction and transcript bundles
5. client 360 snapshot contracts

## 10. Bottom Line

Without stable artifact contracts, the future CRM/client-graph implementation will drift again. These contracts are the minimum spine required to keep AI, UI, and persistence working against the same truth.