Contracts & interfaces — meetLab Docs

I.

Architecture

Three repositories share data but never share write authority. The shared contract layer sits above the domain adapters; the operational data is read-only source.

┌─────────────────────────────────────────────────┐
│              Shared Contract Layer              │
│   shared_contracts.py · validators.py           │
│   boundary_enforcement.py                       │
└────────────┬─────────────────┬──────────────────┘
             │                 │
   ┌─────────▼─────────┐   ┌───▼─────────────────┐
   │  ReviewAdapter    │   │ CorpusReviewAdapter │
   └─────────┬─────────┘   └───┬─────────────────┘
             │                 │
             ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌────────────────────┐
│RELAYS_ARCHIVE│  │ REVIEW_ROOT  │  │ CORPUS_REVIEW_ROOT │
│/meetLab_arch/│  │ /Review/     │  │ /CorpusReview/     │
│ relays/      │  │              │  │                    │
└──────┬───────┘  └──────────────┘  └────────────────────┘
       │
       ▼
┌──────────────────────────────────────────┐
│  Operational data (read-only source)     │
│  /meetLab_archive/relays/transcripts/    │
│  /meetLab_archive/relays/transcripts_    │
│                       augmented/         │
│  /meetLab_archive/relays/artifacts/      │
└──────────────────────────────────────────┘

II.

Domains

archive — `meetLab_archive/relays`

The canonical domain. Sole writer to corpus DBs and analysis artifacts.

corpus_v1_5_2.db — sessions, turns, cycles, event markers
file_registry.db — file inventory plus reviewed turns
corpus_vectors.db — vector embeddings
All analysis artifacts under artifacts/
Python processing pipeline (tools/, bin/)
PUBPIPE publication pipeline

review — `/Review`

Human annotation domain. Sole writer to its own state and annotation files. Reads operational transcripts read-only.

turns.json — human-reviewed turn-level annotations
review_state.json — review cursor and per-file decisions
promotion_manifest.json — staged files for promotion
ChatGPT_Review/ — 361 transcript review folders

corpus — `/CorpusReview`

iOS application domain (Swift / SwiftUI). Sole writer to its own source and resources. Reads operational transcripts read-only via HTTP API or file bundle.

Resources/SampleTranscripts/ — bundled samples
Swift data models in Models/, Data/, Views/

III.

Boundary rules

Allowed and denied operations across domains. The matrix is enforced by boundary_enforcement.py; violations fail closed.

Operation	Allowed
archive → archive (write)	✅
archive → operational / artifacts (write)	✅
archive → transcripts (read)	✅
review → review (write)	✅
review → transcripts (read)	✅
corpus → corpus (write)	✅
corpus → transcripts (read)	✅
review → archive (write)	❌ DENIED
corpus → archive (write)	❌ DENIED
corpus → review (write)	❌ DENIED
review → archive DB (direct connect)	❌ DENIED
corpus → archive DB (direct connect)	❌ DENIED
any → deprecated DB (write)	❌ DENIED
cross-domain schema read (unversioned)	❌ DENIED

IV.

Version policy

Change	Version bump
Add optional fields, clarify comments	Patch (1.0.x)
Add required fields with migration path	Minor (1.x.0)
Breaking change to required fields or domain roots	Major (x.0.0)

unversioned reads forbidden

Cross-domain schema reads must specify an explicit contract version. Unversioned cross-domain reads fail closed.

V.

Turn schema

Required fields

Field	Type	Description
id	str	Turn identifier. Format: `{stem}_{kind}{NNN}` e.g. `transcript_001_P001`.
kind	str	`"P"` (prompt) or `"R"` (response).
turn_index	int	1-based index within the session.
speaker	str	Must be in the augmented speaker set.
body	str	Full turn text.
char_count	int	`len(body)` — must match exactly.

Optional fields

file, label, score, study_marked, is_flagged, paper_sections, note, saved_passages, file_summary, file_rationale, assigned_speaker, reviewed_at.

Turn ID pattern

^[A-Za-z0-9_]+-?\w*_[PR]\d{3}$

VI.

Session schema

Required fields

Field	Type	Description
session_id	str	Unique session identifier (usually transcript filename stem).
primary_model	str	Responding AI model (must be in speaker set, excluding `HUMAN_RELAY`).
turn_count	int	Total turns in the session (≥ 0).

Optional fields: session_type, session_order, inversion_ratio, regime_tier.

VII.

Speaker ontology

Canonical set · Phase 1–3

Speaker	Role
HUMAN_RELAY	Human operator / facilitator
CLAUDE	Anthropic Claude
GEMINI	Google Gemini
CHATGPT	OpenAI ChatGPT

Phase D extensions

Speaker	Role
GROK	xAI Grok
LECHAT	Mistral Le Chat
NOTEBOOKLM	Google NotebookLM
DEEPSEEK	DeepSeek

role boundary

HUMAN_RELAY is valid as a turn speaker but is not a valid primary_model for sessions.

VIII.

Transcript format

Canonical marker syntax

> [!P-001]
**SPEAKER:** Prompt text here.

> [!R-001]
**SPEAKER:** Response text here.

Legacy syntax · tolerated, not preferred

## Prompt:
Text here.

## Response:
Text here.

The validator returns ok=True for both forms but emits a warning for legacy format so callers can track migration progress.

IX.

Semantic label values

ARCHITECTURE_DECISION    AUTHORITY_ASSERTION     BOUNDARY_PROBE
COMPLIANCE_SIGNAL        CONSTRAINT_VIOLATION    CORPUS_NORMAL
DATASET_ARTIFACT         DELEGATION_CHAIN        EVIDENCE_ARTIFACT
GOVERNANCE_SIGNAL        HALT_EVENT              HIGH_VALUE_RELAY
IDENTITY_PROBE           INVERSION_EVENT         MULTI_AGENT_RELAY
NORMAL_RELAY             OVERRIDE_EVENT          PATTERN_SIGNAL
REFUSAL_EVENT            REVOCATION_EVENT        STRUCTURAL_ANOMALY
UNKNOWN

UNKNOWN triggers re-review and should not appear in finalized data.

X.

Compatibility matrices

DB compatibility

DB stem	Version	Min supported	Domain	Deprecated
corpus_v1_5_2	1.5.2	1.5.0	archive	No
corpus_v1	1.0.0	1.0.0	archive	Yes
file_registry	1.0.0	1.0.0	archive	No
corpus_vectors	1.0.0	1.0.0	archive	No

Cross-domain compatibility

	archive	review	corpus	transcripts	artifacts
archive	R/W	R	R	R	R/W
review	—	R/W	—	R	—
corpus	—	—	R/W	R	—

R = read allowed · W = write allowed · — = denied. All cross-domain reads must specify CONTRACT_VERSION = "1.0.0".

XI.

Orchestrator

integration/orchestrate_unified.py provides a single command that runs per-domain checks (root existence, schema compliance, DB state), runs shared validators (contract version, forbidden operation patterns), writes consolidated reports to RELAYS_ARTIFACTS, and returns exit code 1 on any contract or boundary violation.

Make targets

ORCHESTRATED=1 make unified-check           # full cross-domain validation
ORCHESTRATED=1 make unified-check-archive   # archive domain only
ORCHESTRATED=1 make unified-check-review    # review domain only
ORCHESTRATED=1 make unified-check-corpus    # CorpusReview domain only
ORCHESTRATED=1 make unified-test            # integration test suite
ORCHESTRATED=1 make unified-report-json     # JSON output for CI

Architecture

Domains

archive — meetLab_archive/relays

review — /Review

corpus — /CorpusReview

Boundary rules

Version policy

Turn schema

Required fields

Optional fields

Turn ID pattern

Session schema

Required fields

Speaker ontology

Canonical set · Phase 1–3

Phase D extensions

Transcript format

Canonical marker syntax

Legacy syntax · tolerated, not preferred

Semantic label values

Compatibility matrices

DB compatibility

Cross-domain compatibility

Orchestrator

Make targets

archive — `meetLab_archive/relays`

review — `/Review`

corpus — `/CorpusReview`