theorum 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ORCHID AI LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+```text
+ _______  __   __  _______  _______  ______    __   __  __   __
+|       ||  | |  ||       ||       ||    _ |  |  | |  ||  |_|  |
+|_     _||  |_|  ||    ___||   _   ||   | ||  |  | |  ||       |
+  |   |  |       ||   |___ |  | |  ||   |_||_ |  |_|  ||       |
+  |   |  |       ||    ___||  |_|  ||    __  ||       ||       |
+  |   |  |   _   ||   |___ |       ||   |  | ||       || ||_|| |
+  |___|  |__| |__||_______||_______||___|  |_||_______||_|   |_|
+```
+
+# THEORUM: The Flat Agent Kernel
+
+> **"Profiles describe the contract. Providers move bytes. The runner enforces the turn."**
+
+THEORUM is a compact TypeScript agent kernel for apps that need deterministic agent execution without embedding product logic inside the runtime. It gives a host application one runner, typed profiles, multimodal input normalization, dynamic tool dispatch, provider adapters, trace sinks, and guardrail hooks.
+
+The package is intentionally **not** an agent product. It ships no app profiles, no prompts, no secrets, no database policy, no business rules, and no channel-specific UX. Those belong in the host application.
+
+---
+
+## Core Principles
+
+```toml
+[kernel_contract]
+profiles = "Host-owned declarations for model, inputs, outputs, tools, and guardrails"
+runner = "Single deterministic execution path for one agent turn"
+providers = "Adapters for OpenRouter-compatible chat and Google Interactions"
+tools = "Profile allowlist ceiling plus per-turn dynamic declarations"
+egress = "Typed host hook for outbound disclosure checks and repair loops"
+traces = "Host-injected sinks; no environment variables or bundled destinations"
+
+[non_goals]
+app_profiles = "No bundled assistants, demos, product personas, or business tasks"
+secrets = "No .env files, no ambient key reads in the kernel"
+realtime_voice = "Not included yet; persistent duplex sessions stay host-owned"
+product_copy = "No channel wording, refusal copy, iMessage/Alexa/Web policy, or UX defaults"
+```
+
+---
+
+## Architecture
+
+THEORUM is organized around a deliberately small execution boundary.
+
+```mermaid
+flowchart TD
+    subgraph Host["Host application"]
+        Profile["Profiles"]
+        Schemas["Structured schemas"]
+        Tools["Tool handlers"]
+        Keys["Provider keys"]
+        TraceSink["Trace sink"]
+        Policy["Business rules"]
+    end
+
+    subgraph Kernel["THEORUM"]
+        Resolve["resolveTurn"]
+        Guard["sanitize + canary + egress"]
+        Runner["runTurn"]
+        ToolLoop["dynamic tool loop"]
+        Repair["repair attempts"]
+    end
+
+    subgraph Providers["Provider adapters"]
+        OR["OpenRouter"]
+        GI["Google Interactions"]
+        TTS["OpenRouter TTS"]
+    end
+
+    Profile --> Resolve
+    Schemas --> Resolve
+    Tools --> ToolLoop
+    Keys --> Providers
+    TraceSink --> Runner
+    Policy --> Guard
+    Resolve --> Runner
+    Guard --> Runner
+    Runner --> Providers
+    Providers --> Runner
+    Runner --> TraceSink
+```
+
+### Turn Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> ResolveProfile: host sends TurnRequest
+    ResolveProfile --> NormalizeInput: profile input rules
+    NormalizeInput --> BindBoundary: canary + user data fencing
+    BindBoundary --> ProviderStream: ModelProvider.complete
+    ProviderStream --> ToolDispatch: tool event
+    ToolDispatch --> ProviderStream: autonomous loop continues
+    ProviderStream --> EgressGate: final candidate
+    EgressGate --> RepairTurn: blocked + retry budget
+    RepairTurn --> ProviderStream
+    EgressGate --> ValidateOutput: clear
+    ValidateOutput --> EmitEvents: text/media/structured/tokens/done
+    EmitEvents --> Trace: host sink receives audit record
+    Trace --> [*]
+```
+
+---
+
+## Install
+
+### Deno / JSR
+
+```bash
+deno add jsr:@theorum/core
+```
+
+```ts
+import { defineProfile, registerProfile, runTurn } from "jsr:@theorum/core";
+```
+
+### npm
+
+```bash
+npm install theorum
+```
+
+```ts
+import { defineProfile, registerProfile, runTurn } from "theorum";
+```
+
+---
+
+## Minimal Example
+
+This example uses a local mock provider so it runs without secrets. Real provider keys should be passed into the provider adapter by the host application.
+
+```ts
+import {
+  defineProfile,
+  registerProfile,
+  runTurn,
+  type ModelProvider,
+  type TurnEvent,
+} from "jsr:@theorum/core";
+
+const profile = defineProfile({
+  id: "assistant.basic",
+  identity: {
+    handle: "assistant",
+    system: "Answer plainly.",
+  },
+  model: {
+    protocol: "openAi",
+    provider: "openrouter",
+    allow: ["gemini35FlashLite"],
+    thinking: "minimal",
+    maxSteps: 1,
+  },
+  outputs: {
+    streaming: { streamThoughts: false },
+  },
+  guardrails: {
+    quota: { perDay: 100 }, // Optional. Omit when the host owns metering.
+  },
+});
+
+registerProfile(profile);
+
+const provider: ModelProvider = {
+  async *complete(): AsyncIterable<TurnEvent> {
+    yield { type: "text", text: "The turn completed." };
+    yield { type: "tokens", tokens: { input: 8, output: 4, total: 12 } };
+    yield { type: "done" };
+  },
+};
+
+for await (const event of runTurn(
+  { profile: "assistant.basic", input: { text: "Ping" } },
+  provider,
+)) {
+  console.log(event);
+}
+```
+
+---
+
+## Dynamic Tools
+
+THEORUM separates tool concerns into three layers.
+
+| Layer | Owner | Purpose |
+| :--- | :--- | :--- |
+| **Access** | Profile | Hard ceiling: the agent cannot use a tool outside `profile.tools.allow`. |
+| **Visibility** | Turn request | Per-turn declarations: T0/T1/T2 schemas can be passed or loaded dynamically. |
+| **Permission** | Host app | `auto`, `session_consent`, and `always_confirm` determine whether execution pauses. |
+
+```ts
+const dynamicTools = [
+  {
+    name: "lookup_order",
+    description: "Fetch order state from the host application.",
+    loadTier: "T1",
+    permissionTier: "session_consent",
+    parameters: {
+      type: "object",
+      properties: { orderId: { type: "string" } },
+      required: ["orderId"],
+    },
+    handler: async (args) => ({
+      status: "ok",
+      finding: "Order is in transit.",
+      data: { orderId: args.orderId, state: "in_transit" },
+    }),
+  },
+] as const;
+```
+
+The host owns the handler and authorization state. The kernel only enforces the declared contract.
+
+---
+
+## Guardrails and Egress
+
+Inbound and outbound safety are generic kernel hooks.
+
+```ts
+const guardedProfile = defineProfile({
+  id: "assistant.guarded",
+  model: { allow: ["gemini35FlashLite"] },
+  guardrails: {
+    egress: {
+      onBlock: "reject_to_agent",
+      maxRetries: 2,
+      enforce: ({ text, canary }) => {
+        if (canary && text.includes(canary)) {
+          return {
+            blocked: true,
+            text: "",
+            hits: ["canary_token_leak"],
+            rejectionMessage: "Remove private runtime tokens from the reply.",
+          };
+        }
+        return { blocked: false, text };
+      },
+    },
+  },
+});
+```
+
+The egress function is host-owned. One application may block internal tool names, another may block regulated disclosures, and another may disable egress entirely for a trusted development profile.
+
+Quota is optional. If a profile omits `guardrails.quota`, the quota helper returns `not_configured` so the host can decide whether that route should be unmetered, rejected, or handled by a separate rate limiter.
+
+---
+
+## Provider Adapters
+
+THEORUM includes provider adapters but does not own credentials.
+
+```ts
+import { createOpenRouterProvider } from "jsr:@theorum/core/openrouter";
+
+const provider = createOpenRouterProvider({
+  apiKey: hostSecrets.openRouterApiKey,
+  siteName: "Your app",
+  siteUrl: "https://example.com",
+});
+```
+
+```ts
+import { createInteractionsProvider } from "jsr:@theorum/core/providers";
+
+const provider = createInteractionsProvider({
+  keys: hostGeminiKeyVault,
+  fetch,
+});
+```
+
+Provider support is intentionally split by wire protocol:
+
+| Provider | Protocol | Use |
+| :--- | :--- | :--- |
+| OpenRouter | `openAi` | Chat completions, reasoning streams, tool calls, structured output, TTS gateway. |
+| Google Interactions | `geminiInteractions` | Native Google Interactions streaming, image response format, interaction continuity, grounding metadata. |
+
+---
+
+## Public Entrypoints
+
+| Entrypoint | Purpose |
+| :--- | :--- |
+| `jsr:@theorum/core` / `theorum` | Main kernel API: profiles, schemas, runner, core types, provider constructors. |
+| `jsr:@theorum/core/kernel` / `theorum/kernel` | Profile, turn, event, tool, egress, provider, and schema types. |
+| `jsr:@theorum/core/providers` / `theorum/providers` | Provider constructors and provider utility types. |
+| `jsr:@theorum/core/openrouter` / `theorum/openrouter` | OpenRouter payload and streaming adapter. |
+| `jsr:@theorum/core/guardrails` / `theorum/guardrails` | Sanitization, public error mapping, inbound injection/sensitive-data primitives. |
+| `jsr:@theorum/core/observability` / `theorum/observability` | Trace sinks and trace record helpers. |
+
+Internal files remain present in source for maintainability, but package consumers should use the public entrypoints above.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run test
+npm run lint
+deno publish --dry-run --allow-dirty
+```
+
+Build the npm package from the Deno source:
+
+```bash
+npm run build:npm
+cd npm
+npm pack
+```
+
+---
+
+## Package Boundary
+
+THEORUM is ready for host applications when these statements stay true:
+
+```toml
+[boundary]
+profiles_in_package = false
+env_files_in_package = false
+ambient_secret_reads = false
+business_logic_in_kernel = false
+provider_keys_host_owned = true
+trace_sinks_host_injected = true
+realtime_duplex_voice = "out of scope"
+```
+
+If an app needs domain rules, platform delivery policy, product copy, database access, or session memory, that belongs outside THEORUM.
+
+---
+
+## License
+
+MIT License. Copyright (c) ORCHID AI LLC.

package/docs/AGENT_PROFILE_CONTRACT.md

@@ -0,0 +1,161 @@
+# Theorum Profile Specification
+
+A **Profile** is the deterministic, typed security and behavioral contract for an agent role in Theorum.
+
+Every profile strictly namespaces its capabilities across 6 functional domains:
+1. `identity` — Persona, display handle, and static base system prompts.
+2. `model` — Protocol, provider backend, model whitelist, thinking level, and controls.
+3. `tools` — Tool access ceiling.
+4. `inputs` — Strict ingress constraints, file limits, and routing slots.
+5. `outputs` — Structured schemas, voice, media, streaming, and validation/auto-repair.
+6. `guardrails` — Rate limits, canary leak detection, content safety, and outbound disclosure policies.
+
+---
+
+## 1. Authoring Shape
+
+Host apps should author profile definitions, not hand-build normalized runtime
+profiles. The minimum useful profile is:
+
+```typescript
+defineProfile({
+  id: 'host.agent',
+  model: { allow: ['your-model-id'] },
+});
+```
+
+Everything except `id` and `model.allow` is optional at authoring time:
+
+```typescript
+export type ProfileDefinition = {
+  id: ProfileId;
+  identity?: Partial<Profile['identity']>;
+  model: Partial<Profile['model']> & Pick<Profile['model'], 'allow'>;
+  tools?: Partial<Profile['tools']>;
+  inputs?: Partial<Profile['inputs']>;
+  outputs?: Partial<Profile['outputs']>;
+  guardrails?: Partial<Profile['guardrails']>;
+};
+```
+
+`defineProfile()` and `registerProfile()` normalize this shape into a complete
+runtime `Profile`.
+
+## 2. Runtime Type Definition
+
+```typescript
+export interface Profile {
+  /** Unique host-defined profile identifier. */
+  id: ProfileId;
+
+  /** 1. Identity & Persona */
+  identity: {
+    handle: string;
+    chat?: boolean;
+    system?: string;
+    systemByRole?: Record<string, string>;
+  };
+
+  /** 2. Model & Execution Bounds */
+  model: {
+    protocol: 'geminiInteractions' | 'openAi';
+    provider: 'google' | 'openrouter';
+    allow: ModelId[];
+    select?: Record<string, ModelId>;
+    thinking?: ThinkingLevel | Record<string, ThinkingLevel>;
+    controls?: ControlId[];
+    maxSteps?: number;
+    key?: GeminiFreeBucket;
+  };
+
+  /** 3. Tools Envelope */
+  tools: {
+    allow: ToolId[];
+  };
+
+  /** 4. Ingress (Input constraints & slots) */
+  inputs: {
+    text?: boolean;
+    attachments?: { accept: string[] };
+    voice?: { accept: string[] };
+    maxFiles?: number;
+    maxBytes?: number;
+    maxTurnBytes?: number;
+    limitsByMime?: Record<string, number>;
+    slots?: Record<string, string[]>;
+  };
+
+  /** 5. Outputs (Structured output, voice, media, validation, streaming) */
+  outputs: {
+    structured?: StructuredSchemaId | StructuredBySlot | null;
+    media?: boolean;
+    voice?: ProfileVoiceSpec;
+    validation?: ProfileValidationSpec;
+    streaming?: ProfileStreamingSpec;
+  };
+
+  /** 6. Guardrails (Policies & safety boundaries) */
+  guardrails: {
+    quota?: { perDay: number };
+    canary?: boolean;
+    sanitizeInput?: boolean;
+    redactSensitive?: boolean;
+    egress?: ProfileEgressSpec;
+  };
+}
+```
+
+---
+
+## 3. Field Reference
+
+### `identity`
+- `identity.handle`: Public-facing display handle for the persona.
+- `identity.chat`: Flag marking whether this profile participates in interactive chat.
+- `identity.system`: Base system prompt block. Fenced and bound by Theorum guardrails.
+- `identity.systemByRole`: Role-specialized system prompts (e.g., `{ reviewer: '...', drafter: '...' }`).
+
+### `model`
+- `model.protocol`: Wire framing protocol (`'geminiInteractions'` for Google Interactions API, `'openAi'` for OpenAI/OpenRouter compatible chat completions API).
+- `model.provider`: Provider execution backend (`'google'` or `'openrouter'`).
+- `model.allow`: Whitelist of allowable `ModelId`s for this profile.
+- `model.select`: Named model mappings (e.g. `{ fast: 'gemini35FlashLite', deep: 'gemini31ProPreview' }`).
+- `model.thinking`: Pinned thinking level (`'minimal' | 'low' | 'medium' | 'high'`) when not user-controllable.
+- `model.controls`: User-togglable controls on this profile (e.g. `['thinking']`).
+- `model.maxSteps`: Step limit on autonomous tool loops (1 = one-shot; >1 = autonomous tool loop).
+- `model.key`: Gemini free bucket quota pool (`'freeA' | 'freeB' | 'freeC'`).
+
+### `tools`
+- `tools.allow`: Whitelist of tool IDs permitted to run under this profile. Calls to unlisted tools are blocked at the kernel boundary.
+
+### `inputs`
+- `inputs.text`: Boolean flag accepting user text input.
+- `inputs.attachments`: Allowed mime types for uploaded file attachments.
+- `inputs.voice`: Allowed mime types for recorded audio clips.
+- `inputs.maxFiles`: Maximum number of files permitted per message.
+- `inputs.maxBytes`: Maximum byte size permitted per single file.
+- `inputs.maxTurnBytes`: Maximum total byte size permitted across all files in one turn.
+- `inputs.limitsByMime`: Granular per-MIME byte limits (e.g. `{ 'application/pdf': 50 * 1024 * 1024, 'video/*': 100 * 1024 * 1024 }`).
+- `inputs.slots`: Allowed values for dynamic routing slots.
+
+### `outputs`
+- `outputs.structured`: Structured JSON schema specification (or slot-based schema routing).
+- `outputs.media`: Flag enabling native image generation output.
+- `outputs.voice`: Voice specification for TTS (`voice.voice`, `voice.responseFormat: 'pcm' | 'mp3'`).
+- `outputs.validation`: In-harness auto-correction validator (`validate`, optional `extract`, `maxRetries`, `repairGuidance`). If `extract` is omitted, the structured output itself is validated.
+- `outputs.streaming`: SSE streaming behaviors (`streamThoughts`, `gateMedia`).
+
+### `guardrails`
+- `guardrails.quota.perDay`: Optional daily turn quota enforced per client IP. If omitted, quota enforcement is explicitly `not_configured`.
+- `guardrails.canary`: Enable unique token canary leak interception (default `true`).
+- `guardrails.sanitizeInput`: Run prompt injection / jailbreak redaction on ingress text (default `true`).
+- `guardrails.redactSensitive`: Redact SSN, credit cards, IP addresses, API keys from inputs (default `true`).
+- `guardrails.egress`: Generic outbound disclosure control engine (`enforce`, `onBlock: 'reject_to_agent' | 'refuse_to_user'`, `maxRetries`, `repairGuidance`). Runs deterministic auto-repair loops for chat or immediate in-character refusal for voice.
+
+### Per-turn Interactions state
+- `TurnRequest.input`: Optional turn input object. If omitted, Theorum normalizes it to an empty input and still runs the profile/provider turn.
+- `TurnRequest.previousInteractionId`: Optional Google Interactions server-side conversation pointer. Theorum passes it through as `previous_interaction_id` for profiles using `geminiInteractions`.
+- `TurnRequest.store`: Optional Google Interactions storage override. If omitted, Theorum does not send `store`; provider/project policy remains the authority. If supplied, Theorum serializes the explicit boolean.
+
+### Grounding events
+- `TurnEvent.type: 'grounding'`: Provider evidence passthrough for Google Search / Maps grounding. The event carries raw `groundingMetadata`, raw `groundingChunks`, optional search widget HTML, and lightweight `sources` for maps/web URIs. Host apps own domain-specific interpretation, such as store cards or citation display.

package/docs/CLI_SPEC.md

@@ -0,0 +1,183 @@
+# Theorum CLI & Testing Architecture Specification
+
+## 1. Overview & Goals
+
+The `theorum` CLI provides developer tooling, profile inspection, and stress-matrix synthesis for applications powered by Theorum.
+
+### Core Objectives:
+1. **Zero-Config Profile Stress Testing**: Automatically construct the most demanding valid payload (multimodal, deep reasoning, maximum tools) for any registered profile.
+2. **Capability Matrix Permutations**: Systematically test or isolate specific capabilities (`--lite`, `--attachment`, `--voice`, `--map`, `--search`).
+3. **Conflict Resolution**: Deterministically resolve provider conflicts (e.g. `search XOR maps`) and mutual exclusions without crashing.
+4. **Host-Owned Execution**: The CLI never reads secrets or creates providers. Hosts supply providers when executing live tests programmatically.
+5. **Interactive Turn REPL**: Execute ad-hoc runs only when the host has supplied a `ModelProvider`.
+
+---
+
+## 2. Command Surface & UX
+
+```bash
+theorum <command> [subcommand] [flags]
+```
+
+### 2.1 `theorum test` (Profile Verification & Stress Runner)
+
+Builds validation turns against registered profiles. Live execution requires an explicit host-provided `ModelProvider`; Theorum does not read keys or create providers.
+
+```bash
+# 1. Stress Combo (Default): Auto-constructs the toughest valid test for this host profile
+theorum test --profile your-profile
+
+# 2. Lite (Smoke ping): Minimal prompt, fast mode, tools disabled
+theorum test --profile your-profile --lite
+
+# 3. Explicit capability flags: Override/test specific modalities
+theorum test --profile your-profile --attachment ./reference.png --map --voice ./audio.wav
+
+# 4. Full matrix test: Runs every permutation of supported tools/inputs for a profile
+theorum test --profile your-profile --matrix
+
+# 5. Global suite: Test all registered profiles
+theorum test --all [--lite] [--concurrency 4]
+```
+
+#### CLI Flag Matrix:
+| Flag | Type | Description |
+| :--- | :--- | :--- |
+| `--profile, -p` | `string` | Target profile ID registered by the host application |
+| `--all, -a` | `boolean` | Run test across all registered profiles |
+| `--lite` | `boolean` | Minimal single-turn connectivity ping (fast mode, tools off, text only) |
+| `--matrix` | `boolean` | Generate and execute all valid permutations for the profile |
+| `--attachment` | `string[]` | Path(s) to custom attachment files (PNG, PDF, CSV, etc.) |
+| `--voice` | `string` | Path to custom voice audio (WAV, PCM) |
+| `--search` | `boolean` | Force Google Search tool on |
+| `--map` | `boolean` | Force Google Maps tool on |
+| `--mode` | `'fast' \| 'smart'` | Force reasoning / model speed tier |
+| `--timeout` | `number` | Timeout in seconds (default: 30) |
+
+---
+
+### 2.2 `theorum run` (Terminal REPL & Ad-hoc Execution)
+
+Interactive execution in the terminal with live streaming when called from a host that supplies a provider.
+
+```bash
+# Interactive REPL
+theorum run --profile your-profile
+
+# One-shot CLI run
+theorum run --profile your-profile --prompt "Create a 3-tier architecture plan" --mode smart
+```
+
+---
+
+### 2.3 `theorum profile` (Registry Inspection & Validation)
+
+```bash
+# List all registered profiles and supported modalities
+theorum profile list
+
+# Show detailed profile definition (inputs, tools, schema, model config)
+theorum profile show your-profile
+
+# Validate structured output schemas
+theorum profile validate
+```
+
+---
+
+## 3. Stress Matrix Synthesizer Logic
+
+When `theorum test --profile <id>` is invoked without explicit flags, the synthesizer inspects `Profile` metadata:
+
+```ts
+interface SynthesizedTurn {
+  profile: string;
+  select?: 'fast' | 'smart';
+  input: {
+    text: string;
+    voice?: AudioFixture;
+    attachments?: AttachmentFixture[];
+  };
+  tools?: {
+    googleSearch?: boolean;
+    googleMaps?: boolean;
+    codeExecution?: boolean;
+    customTools?: string[];
+  };
+}
+```
+
+### Auto-Synthesis Rules:
+1. **Model & Thinking Selection**:
+   - If profile supports `smart` mode $\to$ select `smart` (highest pinned thinking tokens).
+   - Otherwise $\to$ use default profile model.
+2. **Multimodal Fixtures**:
+   - If `inputs.voice === true` $\to$ inject synthetic 16kHz PCM/WAV speech fixture.
+   - If `inputs.attachments === true` $\to$ inject synthetic test document/image matching allowed MIME types within byte ceilings (`maxBytes`).
+3. **Tool Resolution & Conflict Handling**:
+   - Turn on all allowed tools in `profile.tools.allow`.
+   - **Mutual Exclusion Rule**: If both `googleSearch` and `googleMaps` are allowed, default to testing `googleSearch`. When `--matrix` is passed, split into two separate test runs (`[search]` and `[maps]`).
+4. **Structured Schema Validation**:
+   - If `profile.outputs.structured` is defined, validate that the final LLM response strictly parses against the JSON schema.
+
+---
+
+## 4. Fixture Management (`src/cli/matrix/fixtures.ts`)
+
+Built-in zero-dependency synthetic fixtures:
+- **`TEST_PNG`**: 1x1 valid PNG image byte buffer (`image/png`).
+- **`TEST_PDF`**: Minimal valid PDF 1.4 document buffer (`application/pdf`).
+- **`TEST_WAV`**: 1-second 16kHz mono PCM/WAV audio tone (`audio/wav`).
+- **`TEST_CSV`**: Minimal CSV table data (`text/csv`).
+
+---
+
+## 5. File Structure in `theorum` Package
+
+```
+theorum/
+├── docs/
+│   ├── AGENT_PROFILE_CONTRACT.md
+│   └── CLI_SPEC.md                      <-- This specification
+├── src/
+│   ├── cli/
+│   │   ├── index.ts                     # CLI Entry point & router
+│   │   ├── commands/
+│   │   │   ├── test.ts                  # 'theorum test' execution & reporting
+│   │   │   ├── run.ts                   # 'theorum run' REPL & SSE streaming
+│   │   │   └── profile.ts               # 'theorum profile' inspector
+│   │   └── matrix/
+│   │       ├── fixtures.ts              # Built-in synthetic media fixtures
+│   │       └── synthesizer.ts           # Matrix & stress combo generator
+│   ├── guardrails/
+│   ├── kernel/
+│   └── observability/
+├── deno.json                            # "tasks": { "theorum": "deno run -A src/cli/index.ts" }
+└── mod.ts
+```
+
+---
+
+## 6. Output & Reporting Contract
+
+`theorum test` outputs concise terminal telemetry:
+
+```
+[THEORUM TEST] Profile: your-profile (smart mode)
+------------------------------------------------------------
+Inputs:      [Text, Voice (1s WAV), Attachment (1 PNG)]
+Tools:       [googleSearch, codeExecution]
+Provider:    host-supplied ModelProvider
+
+⚡ Streaming Turn Execution:
+  ✓ Thinking tokens: 1,420 tokens (1.12s)
+  ✓ Tool dispatched: codeExecution (0.34s)
+  ✓ Schema output: 852 tokens (0.78s)
+
+Validation Checks:
+  ✓ Security Canary: Intact & Redacted
+  ✓ Schema Conformity: Valid (AST JSON)
+  ✓ Latency: 2.24s total
+
+STATUS: PASSED ✓
+```