core/docs/workbench/data-shapes-v1.md

CORE Workbench v1 — Data Shape Contracts

Status: draft

This document defines the canonical UI-facing shapes for CORE Workbench v1. They are intentionally narrower than internal runtime structures.

The workbench should expose enough information to audit and replay behavior without leaking unnecessary internals into the UI contract.

Naming conventions

• IDs are stable strings.
• Hashes/digests should include an algorithm prefix when possible.
• Timestamps are ISO-8601 UTC strings.
• Unknown values should be explicit ("unknown") rather than omitted when they materially affect audit interpretation.

---

Envelope

export type WorkbenchResponse<T> =
  | {
      ok: true;
      generated_at: string;
      data: T;
    }
  | {
      ok: false;
      generated_at: string;
      error: WorkbenchError;
    };

export type WorkbenchError = {
  code:
    | "bad_request"
    | "evidence_unavailable"
    | "not_found"
    | "unsupported"
    | "read_error"
    | "eval_failed"
    | "runtime_unavailable";
  message: string;
  detail?: unknown;
};

---

Runtime

export type RuntimeStatus = {
  backend: "numpy" | "mlx" | "rust" | "unknown";
  git_revision: string;
  engine_state_present: boolean;
  checkpoint_revision: string | "unknown";
  revision_warning: boolean;
  active_session_id: string | null;
  mutation_mode: "read_only" | "runtime_turn";
};

mutation_mode is UI-facing. It does not redefine runtime doctrine. It tells an operator whether the current surface is purely reading artifacts or executing normal runtime turns.

---

Chat

export type ChatTurnRequest = {
  prompt: string;
};

export type ChatTurnSummary = {
  turn_id: string;
  surface: string;
  grounding_source: string | null;
  trace_hash: string | null;
  replay_available: boolean;
  proposal_state: "none" | "pending" | "accepted" | "rejected" | null;
  mutation_state: "none" | "transient" | "proposal_only" | "ratified";
  leeway_evidence?: LeewayEvidence | null;
  pipeline_record?: CognitivePipelineRecord | null;
  field_evidence?: FieldEvidence | null;
};

surface is the user-visible response. The UI must not substitute telemetry surfaces into the user surface.

---

Trace

export type TraceDetail = {
  turn_id: string;
  surface: string;
  articulation_surface: string | null;
  walk_surface: string | null;
  trace_hash: string | null;
  replay_digest: string | null;
  grounding_source: string | null;
  proposal_refs: string[];
  candidate_refs: string[];
  admissibility: {
    rejected_attempts: number | null;
    exhausted: boolean | null;
  };
  pipeline_record?: CognitivePipelineRecord | null;
  field_evidence?: FieldEvidence | null;
  raw?: unknown;
};

The trace drawer may show raw, but only behind an explicit expand action.

export type CognitivePipelineStageKind =
  | "input"
  | "intent"
  | "proposition_graph"
  | "articulation_target"
  | "realizer"
  | "walk_telemetry"
  | "trace_hash";

export type CognitivePipelineRecord = {
  schema_version: "cognitive_pipeline_record_v1";
  status: "recorded" | "missing_evidence";
  missing_reason: string | null;
  trace_hash: string | null;
  versor_condition: number | null;
  field_digest: string | null;
  stages: {
    stage_id: CognitivePipelineStageKind;
    label: string;
    status: "recorded" | "missing_evidence";
    summary: string;
    detail: Record<string, unknown>;
  }[];
  edges: {
    from_stage: CognitivePipelineStageKind;
    to_stage: CognitivePipelineStageKind;
    label: string | null;
  }[];
};

pipeline_record is required for newly journaled turns and nullable for pre-widening rows. The UI must render missing_evidence when it is absent and must not reconstruct stage internals from replay as if they were persisted. The first-class read endpoint is GET /trace/{turn_id}/pipeline; it returns a CognitivePipelineRecord directly and uses status: "missing_evidence" for pre-widening rows. The Trace route renders the record as a deterministic stage rail, DAG, and selected-stage detail inspector; those views are projections of stages and edges only, not replay-derived cognition.

FieldEvidence (C3 field substrate)

export type FieldEvidence = {
  schema_version: "field_evidence_v1";
  status: "recorded" | "missing_evidence";
  missing_reason: string | null;
  trace_hash: string | null;
  versor_condition: number | null;       // exact, measured over field_state_after
  versor_condition_ceiling: number;      // 1e-6 — the CLAUDE.md invariant bound
  field_valid: boolean | null;           // versor_condition < ceiling
  field_digest: string | null;           // sha256 of the canonical field bytes
  parent_field_digest: string | null;    // sha256 of field_state_before, or null
  transition_inner_product: number | null; // cga_inner(before, after), or null
};

field_evidence is the geometry under a turn: only the engine's EXACT scalar invariants and a content-addressed digest cross the boundary — never the raw CL(4,1) multivector. It is required for newly journaled turns and nullable for pre-widening rows; the UI renders missing_evidence when absent and never reconstructs the field. field_valid is consistency-checked against the ceiling at construction, so the Field tab can never claim a valid field while versor_condition breaches 1e-6 (the wrong=0 analogue for the geometry). The first-class read endpoint is GET /trace/{turn_id}/field; it returns a FieldEvidence directly. The Trace route's Field tab renders it as the measured value against the ceiling, the cga_inner transition, and the digests — inspectable exact numbers and invariant status, no decorative geometry.

EvidenceBundle (D3 shareable evidence bundle)

export type EvidenceBundle = {
  schema_version: "evidence_bundle_v1";
  turn_id: number;
  generated_from: "turn_journal";
  trace_hash: string | null;
  trace_integrity: "pipeline_trace" | "legacy_unhashed";
  prompt: string;
  surface: string;
  grounding_source: GroundingSource;
  epistemic_state: EpistemicState;
  normative_clearance: NormativeClearance;
  refusal_emitted: boolean;
  journal_digest: string;              // provenance — NOT in the content digest
  pipeline_record: CognitivePipelineRecord | null;
  field_evidence: FieldEvidence | null;
  leeway_evidence: LeewayEvidence | null;
  replay_reproducer: string;           // how to verify — NOT in the content digest
  bundle_digest: string;               // sha256 content address of the evidence
};

A turn's evidence exported as one citable artifact — reproducibility as a deliverable. bundle_digest content-addresses the deterministic cognitive evidence only (prompt, surface, trace_hash, grounding/epistemic/normative state, pipeline + field evidence, leeway verdict). Journal position and wall-clock metadata (turn_id, journal_digest, replay_reproducer, generated_from) are carried for provenance but excluded from the digest, so the same turn content always yields the same digest regardless of where it landed in a journal. Read-only — a pure projection of a persisted journal entry, no engine execution. Endpoint: GET /trace/{turn_id}/bundle. The Trace route's Bundle tab shows the citable digest, a "what this proves / does not prove" honesty note, the reproducer, and a deterministic JSON download.

DeterminismTour (D1/D2 guided tour)

export type TourStepKind = "intro" | "demo" | "payoff";
export type TourStep = {
  step_id: string;
  order: number;
  kind: TourStepKind;
  headline: string;                       // authored narrative
  narrative: string;                      // authored framing
  demo_id: string | null;                 // a real registered demo
  demo_title: string | null;              // pulled from the demo spec
  what_this_proves: string | null;        // pulled from the demo spec
  what_this_does_not_prove: string | null;// pulled from the demo spec
  route_hint: string | null;              // where to go deeper
};
export type DeterminismTour = {
  schema_version: "determinism_tour_v1";
  title: string;
  thesis: string;                         // the provider-agnostic pitch
  steps: TourStep[];
};

The first-run, provider-agnostic narrative. Authored headlines/narrative frame the story, but every demo step is bound to a real demo: the honesty cards (what_this_proves / what_this_does_not_prove) and demo_title are pulled from the demo spec, never re-authored, and a step referencing a missing demo fails closed. Read-only. Endpoint: GET /tour. Surfaced as the /tour route (Determinism section) — thesis hero + ordered step cards with the honesty cards and links to the real demos / replay.

---

Proposal

export type ProposalSummary = {
  proposal_id: string;
  state: "pending" | "accepted" | "rejected" | "unknown";
  source_kind: string;
  replay_equivalent: boolean | null;
  created_at: string | null;
  downstream_effect: "unknown" | "none" | "observed";
};

export type ProposalDetail = ProposalSummary & {
  proposed_chain: unknown;
  replay_evidence: unknown;
  source: unknown;
  evidence: unknown[];
  artifact_refs: ArtifactRef[];
  suggested_cli?: string;
  leeway_evidence?: LeewayEvidence | null;
};

V1 may include suggested_cli for copy-only operator review. It must not execute it.

export type LeewayEvidence = {
  class_name: string;
  license: "PROPOSE" | "SERVE" | "blocked" | "unknown";
  theta: number | null;
  claim_disclosure: "approximate" | "verified" | "proposal_only" | "none";
  source_digest: string | null;
  calibration_evidence_ref: string | null;
};

LeewayEvidence is nullable. The UI may render it when present, but must render explicit absence when it is null/missing and must never derive class/license/theta in the frontend.

---

Eval

export type EvalLaneSummary = {
  lane: string;
  versions: string[];
  read_only: boolean;
  description: string | null;
};

export type EvalRunRequest = {
  lane: string;
  version?: string;
  split?: "dev" | "public" | "holdout";
};

export type EvalRunResult = {
  lane: string;
  version: string;
  split: string;
  passed: boolean | null;
  metrics: Record<string, unknown>;
  cases: unknown[];
  source_digest?: string;
};

The API should initially allow only explicitly safe lanes. holdout should be disabled unless the backend proves the sealed-eval path is configured.

---

Demo Evidence DAG

export type DemoEvidenceDag = {
  graph_id: string;
  graph_kind: "proof_carrying_promotion" | "deductive_entailment";
  title: string;
  source_digest: string | null;
  nodes: {
    node_id: string;
    label: string;
    summary: string;
    detail: Record<string, unknown>;
  }[];
  edges: {
    from_node: string;
    to_node: string;
    label: string | null;
  }[];
};

DemoScenarioRunResult.evidence_dag is nullable. It is populated by the backend reader for proof-carrying coherence promotion and deductive-entailment authority scenarios from the committed demo authority response. The UI may render it with the deterministic DAG primitive but must not infer proof edges from raw response JSON.

---

Calibration

export type CalibrationClass = {
  class_name: string;
  correct: number;
  wrong: number;
  refused: number;
  committed: number;
  reliability_floor: number;
  coverage: number;
  propose_required: number;
  propose_licensed: boolean;
  serve_required: number;
  serve_licensed: boolean;
  source_path: string;
  source_digest: string;
};

export type ServingMetrics = {
  lane: string;
  correct: number;
  refused: number;
  wrong: number;
  sample_count: number;
  source_path: string;
  source_digest: string;
};

Reliability and license verdicts are engine-owned derivations from core.reliability_gate; the workbench mirrors the read model.

---

Contemplation

export type ContemplationScene = {
  scene_id: string;
  claim: string;
  detail: Record<string, unknown>;
};

export type ContemplationRunSummary = {
  run_id: string;
  source_path: string;
  source_digest: string | null;
  prompt: string | null;
  cold_subject: string | null;
  scene_count: number;
  learning_arc_closed: boolean | null;
  all_claims_supported: boolean | null;
  active_corpus_byte_identical: boolean | null;
};

export type ContemplationRunDetail = ContemplationRunSummary & {
  before: Record<string, unknown> | null;
  after: Record<string, unknown> | null;
  engine_chain: Record<string, unknown> | null;
  scenes: ContemplationScene[];
};

Contemplation runs are read-only projections over committed contemplation/runs/*.json reports. run_id is the report filename stem, not a synthesized session id. Scene details remain report-authored evidence; the route must not promote speculative findings or apply proposals.

---

Replay

export type ReplayComparison = {
  artifact_id: string;
  original_hash: string | null;
  replay_hash: string | null;
  equivalent: boolean;
  divergences: ReplayDivergence[];
};

export type ReplayDivergence = {
  path: string;
  original: unknown;
  replay: unknown;
  severity: "info" | "warning" | "failure";
};

---

Artifact

export type ArtifactRef = {
  artifact_id: string;
  kind:
    | "trace"
    | "eval_result"
    | "proposal"
    | "contemplation_report"
    | "telemetry"
    | "engine_state_manifest"
    | "unknown";
  path: string;
  digest: string | null;
  created_at: string | null;
};

export type ArtifactDetail = ArtifactRef & {
  content_type: "json" | "jsonl" | "text" | "unknown";
  content: unknown;
};

Artifact paths must be repo-root constrained. The backend must never honor an arbitrary user-supplied filesystem path.

---

R2 Read Projections

export type PackSummary = {
  pack_id: string;
  source: "language_pack" | "runtime_pack";
  manifest_path: string;
  version: string | null;
  language: string | null;
  modality: string | null;
  determinism_class: string | null;
  checksum: string | null;
  checksums: Record<string, string>;
};

export type PackDetail = PackSummary & {
  manifest_digest: string;
  manifest: Record<string, unknown>;
};

checksum and checksums are manifest-authored values and must remain verbatim. manifest_digest is the backend-computed digest of the manifest file bytes.

export type AuditEvent = {
  event_id: string;
  source:
    | "engine_state_manifest"
    | "math_proposal_log"
    | "operator_telemetry"
    | "reboot_telemetry"
    | "teaching_proposal_log";
  source_path: string;
  timestamp: string | null;
  event_type: string;
  mutation_boundary: boolean;
  summary: string;
  ref_id: string | null;
  payload_digest: string;
  payload: unknown;
};

Audit events are projections over existing artifacts. event_id and payload_digest are deterministic backend digests; they are not new stored identifiers.

export type RunSummary = {
  session_id: string;
  source: "engine_state_manifest" | "turn_journal";
  turn_count: number;
  started_at: string | null;
  updated_at: string | null;
  checkpoint_present: boolean;
  checkpoint_revision: string | null;
  artifact_refs: ArtifactRef[];
  evidence_gap: string | null;
};

export type RunTurnRef = {
  turn_id: number;
  trace_hash: string | null;
  timestamp: string;
  trace_path: string;
  surface_excerpt: string;
};

export type IdentityContinuity = {
  status: "verified" | "break" | "missing_evidence";
  engine_identity: string | null;
  parent_engine_identity: string | null;
  current_engine_identity: string | null;
  written_at_revision: string | null;
  current_revision: string;
  lineage_relation:
    | "self_parent"
    | "descends_from_parent"
    | "missing_parent"
    | "unavailable";
  verification_summary: string;
  evidence_gap: string | null;
};

export type RunDetail = RunSummary & {
  turns: RunTurnRef[];
  manifest: Record<string, unknown> | null;
  identity_continuity: IdentityContinuity | null;
};

When no durable per-session id exists, session_id names the artifact boundary (workbench_turn_journal or engine_state_checkpoint) and evidence_gap states the missing persisted fact.

identity_continuity is backend-projected from engine_state/manifest.json plus the current ratified substrate identity. The UI must render this field directly; it must not infer continuity status by parsing raw manifest JSON. Legacy manifests that predate engine_identity return status: "missing_evidence" instead of a synthesized verdict.

export type VaultSummary = {
  source_path: string;
  entry_count: number;
  store_count: number;
  reproject_interval: number;
  max_entries: number | null;
  persisted: boolean;
};

export type VaultEntry = {
  entry_index: number;
  epistemic_status: string;
  epistemic_state: string;
  metadata: Record<string, unknown>;
  versor_digest: string | null;
};

// One result of CORE's exact CGA recall scan over the persisted vault.
// `cga_inner` is the genuine, finite exact inner product (never a similarity
// proxy). `exact_self_match` flags a byte-identical entry, promoted ahead of
// metric ranking (stored versors are CGA null vectors → ~0 self inner-product).
export type VaultRecallHit = {
  entry_index: number;
  rank: number;
  cga_inner: number;
  exact_self_match: boolean;
  epistemic_status: string;
  epistemic_state: string;
  versor_digest: string | null;
};

// Read-only proof that a persisted vault entry is recallable by CORE's actual
// exact CGA machinery. `exact_cga` is always true / `approximate` always false:
// this is the exact `cga_inner` scan, never ANN / cosine / approximate ranking.
export type VaultRecall = {
  entry_index: number;
  query_versor_digest: string | null;
  top_k: number;
  hits: VaultRecallHit[];
  self_hit_rank: number | null;
  self_hit_found: boolean;
  exact_cga: boolean;
  approximate: boolean;
  source_path: string;
};

Vault shapes are available only from persisted engine_state/session_state.json evidence. If absent, the API returns 501 evidence_unavailable.

---

UI state tags

These are display-only semantic tags.

export type TrustBadge =
  | "replay_passed"
  | "replay_failed"
  | "grounded"
  | "ungrounded"
  | "pending_review"
  | "mutation_none"
  | "mutation_transient"
  | "mutation_ratified"
  | "revision_warning"
  | "refusal";

Colors should be mapped only to these operational meanings.

---

Backward compatibility rule

Internal runtime objects may evolve faster than the workbench UI. The API layer must normalize into these v1 shapes so the frontend does not depend on private runtime structure.