harnery 0.35.0 → 0.36.0

package/src/core/presence/relay-client.ts

@@ -24,6 +24,7 @@
 
 import { spawn } from "node:child_process";
 import {
+  closeSync,
   existsSync,
   mkdirSync,
   openSync,
@@ -34,9 +35,12 @@ import {
   writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
+import { coordEnv } from "../../lib/env.ts";
 import { resolveMachineLabel } from "../../lib/machine.ts";
 import { presenceRelayUrl } from "../config.ts";
 import { eventV3ActiveWatchPath } from "../events/v3/reader.ts";
+import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.ts";
+import { RotatingTextSink } from "../storage/process-log.ts";
 import { buildPresenceBlob, type PresenceBlob } from "./blob.ts";
 import { originUrl, rootCommitSha, sanitizeRefComponent } from "./git.ts";
 import {
@@ -127,13 +131,15 @@ export function ensureRelayDaemon(coordRoot: string): void {
     if (!existsSync(harnBin)) return;
 
     mkdirSync(presenceDir(coordRoot), { recursive: true });
-    const log = openSync(logFilePath(coordRoot), "a");
+    const sharedLogs = coordEnv("SHARED_LOGS") !== "0";
+    const log = sharedLogs ? undefined : openSync(logFilePath(coordRoot), "a");
     const child = spawn(harnBin, ["presence", "relay-daemon"], {
       cwd: coordRoot,
       detached: true,
-      stdio: ["ignore", log, log],
+      stdio: log === undefined ? ["ignore", "ignore", "ignore"] : ["ignore", log, log],
       env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
     });
+    if (log !== undefined) closeSync(log);
     child.unref();
   } catch {
     /* best-effort */
@@ -144,17 +150,32 @@ export function ensureRelayDaemon(coordRoot: string): void {
 export async function runRelayDaemon(coordRoot: string): Promise<number> {
   const url = presenceRelayUrl(coordRoot);
   if (!url) {
-    console.error("relay-daemon: no relay configured (presence.relay)");
+    const message = "relay-daemon: no relay configured (presence.relay)";
+    console.error(message);
+    if (coordEnv("SHARED_LOGS") !== "0") {
+      appendPresenceRelayDiagnostic(coordRoot, "relay.configuration_error", { message });
+    }
+    await closeProcessLoggers();
     return 2;
   }
   if (typeof WebSocket === "undefined") {
-    console.error("relay-daemon: no global WebSocket in this runtime (need Bun or Node >= 21)");
+    const message = "relay-daemon: no global WebSocket in this runtime (need Bun or Node >= 21)";
+    console.error(message);
+    if (coordEnv("SHARED_LOGS") !== "0") {
+      appendPresenceRelayDiagnostic(coordRoot, "relay.runtime_error", { message });
+    }
+    await closeProcessLoggers();
     return 2;
   }
   const sha = rootCommitSha(coordRoot);
   const origin = originUrl(coordRoot);
   if (!sha || !origin) {
-    console.error("relay-daemon: repo has no commits or no origin remote");
+    const message = "relay-daemon: repo has no commits or no origin remote";
+    console.error(message);
+    if (coordEnv("SHARED_LOGS") !== "0") {
+      appendPresenceRelayDiagnostic(coordRoot, "relay.repository_error", { message });
+    }
+    await closeProcessLoggers();
     return 2;
   }
 
@@ -184,6 +205,9 @@ export async function runRelayDaemon(coordRoot: string): Promise<number> {
 
   const log = (msg: string) => {
     console.log(`[${new Date().toISOString()}] ${msg}`);
+    if (coordEnv("SHARED_LOGS") !== "0") {
+      appendPresenceRelayDiagnostic(coordRoot, "relay.lifecycle", { message: msg });
+    }
   };
 
   const publishNow = async (force = false): Promise<void> => {
@@ -286,7 +310,8 @@ export async function runRelayDaemon(coordRoot: string): Promise<number> {
       } catch {
         /* ignore */
       }
-      process.exit(0);
+      void closeProcessLoggers().finally(() => process.exit(0));
+      return;
     }
     // Idle machine (no live sessions for a while) → exit; hooks restart us.
     if (idleSince && Date.now() - idleSince > IDLE_EXIT_MS) {
@@ -299,7 +324,7 @@ export async function runRelayDaemon(coordRoot: string): Promise<number> {
       } catch {
         /* ignore */
       }
-      process.exit(0);
+      void closeProcessLoggers().finally(() => process.exit(0));
     }
   }, KEEPALIVE_MS);
 
@@ -307,6 +332,29 @@ export async function runRelayDaemon(coordRoot: string): Promise<number> {
   return await new Promise<number>(() => {});
 }
 
+export function appendPresenceRelayDiagnostic(
+  coordRoot: string,
+  event: string,
+  fields: Record<string, unknown> = {},
+): "shared" | "legacy" {
+  if (coordEnv("SHARED_LOGS") !== "0") {
+    try {
+      const logger = processLogger(coordRoot, "presence-relay");
+      if (event.includes("error")) logger.error(event, legacyLogFields(fields));
+      else logger.info(event, legacyLogFields(fields));
+      return "shared";
+    } catch {
+      // Bootstrap failures retain a bounded text file for process diagnostics.
+    }
+  }
+  const sink = new RotatingTextSink({ path: logFilePath(coordRoot), max_bytes: 512 * 1_024 });
+  sink.append(
+    `${JSON.stringify({ schema_version: 1, ts: new Date().toISOString(), event, ...fields })}\n`,
+  );
+  sink.close();
+  return "legacy";
+}
+
 /** Daemon status for `presence peers`/doctor surfaces. */
 export function relayDaemonStatus(coordRoot: string): {
   running: boolean;

package/src/core/semantic/adapters.ts

@@ -6,23 +6,22 @@ import { promisify } from "node:util";
 import type { TSchema } from "@sinclair/typebox";
 import { whichBin } from "../../lib/headless/index.ts";
 import {
-  type SemanticConfiguredModel,
   type SemanticHarness,
   SemanticModelReplyV2Schema,
+  type SemanticUsageReceiptV1,
 } from "./contract.ts";
+import { SEMANTIC_READER_ROUTES, type SemanticReaderRoute } from "./routes.ts";
 import type { SemanticReaderResolution } from "./storage.ts";
+import {
+  estimateVisibleSemanticUsage,
+  nativeSemanticUsage,
+  unreportedSemanticUsage,
+} from "./usage.ts";
 
 const execFileAsync = promisify(execFile);
 const MAX_OUTPUT_BYTES = 512 * 1024;
 const DEFAULT_TIMEOUT_MS = 90_000;
 
-export interface SemanticReaderRoute {
-  harness: SemanticHarness;
-  binary: string;
-  configured_model: SemanticConfiguredModel;
-  invocation_model_id: string;
-}
-
 export interface SemanticAdapterSuccess {
   ok: true;
   text: string;
@@ -30,6 +29,7 @@ export interface SemanticAdapterSuccess {
   model_attestation: "verified" | "requested-only";
   duration_ms: number;
   output_bytes: number;
+  usage: SemanticUsageReceiptV1;
 }
 
 export interface SemanticAdapterFailure {
@@ -42,6 +42,7 @@ export interface SemanticAdapterFailure {
   resolved_model_id?: string;
   model_attestation?: "verified" | "requested-only";
   duration_ms: number;
+  usage: SemanticUsageReceiptV1;
 }
 
 export type SemanticAdapterResult = SemanticAdapterSuccess | SemanticAdapterFailure;
@@ -56,26 +57,7 @@ export interface SemanticAdapter {
   ): Promise<SemanticAdapterResult>;
 }
 
-export const SEMANTIC_READER_ROUTES: Record<SemanticHarness, SemanticReaderRoute> = {
-  "claude-code": {
-    harness: "claude-code",
-    binary: "claude",
-    configured_model: "haiku-4.5",
-    invocation_model_id: "claude-haiku-4-5-20251001",
-  },
-  codex: {
-    harness: "codex",
-    binary: "codex",
-    configured_model: "gpt-5.6-luna",
-    invocation_model_id: "gpt-5.6-luna",
-  },
-  cursor: {
-    harness: "cursor",
-    binary: "cursor-agent",
-    configured_model: "composer-2.5",
-    invocation_model_id: "composer-2.5",
-  },
-};
+export { SEMANTIC_READER_ROUTES, type SemanticReaderRoute } from "./routes.ts";
 
 export function createSemanticAdapters(): Record<SemanticHarness, SemanticAdapter> {
   return {
@@ -119,7 +101,12 @@ function createAdapter(route: SemanticReaderRoute): SemanticAdapter {
       responseSchema = SemanticModelReplyV2Schema,
     ) {
       if (!whichBin(route.binary)) {
-        return { ok: false, reason_code: "harness_unavailable", duration_ms: 0 };
+        return {
+          ok: false,
+          reason_code: "harness_unavailable",
+          duration_ms: 0,
+          usage: unreportedSemanticUsage(),
+        };
       }
       return await invokeRoute(route, prompt, timeoutMs, responseSchema);
     },
@@ -144,16 +131,22 @@ async function invokeRoute(
     });
     pending.child.stdin?.end();
     const { stdout } = await pending;
-    const raw = invocation.outputFile ? readFileSync(invocation.outputFile, "utf8") : stdout;
-    const parsed = parseHarnessOutput(route.harness, raw);
+    const outputFileText = invocation.outputFile
+      ? readFileSync(invocation.outputFile, "utf8")
+      : undefined;
+    const parsed = parseSemanticHarnessOutput(route.harness, stdout, outputFileText);
     if (!parsed.text.trim()) throw new Error("empty semantic response");
-    if (parsed.executedModelId && parsed.executedModelId !== route.invocation_model_id) {
+    if (
+      parsed.executedModelId &&
+      !modelIdsMatch(parsed.executedModelId, route.invocation_model_id)
+    ) {
       return {
         ok: false,
         reason_code: "model_mismatch",
         resolved_model_id: parsed.executedModelId,
         model_attestation: "verified",
         duration_ms: Date.now() - started,
+        usage: parsed.usage ?? unreportedSemanticUsage(),
       };
     }
     return {
@@ -163,6 +156,7 @@ async function invokeRoute(
       model_attestation: parsed.executedModelId ? "verified" : "requested-only",
       duration_ms: Date.now() - started,
       output_bytes: Buffer.byteLength(parsed.text),
+      usage: parsed.usage ?? estimateVisibleSemanticUsage(prompt, parsed.text),
     };
   } catch (error) {
     return {
@@ -171,6 +165,7 @@ async function invokeRoute(
       resolved_model_id: route.invocation_model_id,
       model_attestation: "requested-only",
       duration_ms: Date.now() - started,
+      usage: unreportedSemanticUsage(),
     };
   } finally {
     rmSync(dir, { recursive: true, force: true });
@@ -222,6 +217,7 @@ function buildInvocation(
         "--ephemeral",
         "--ignore-user-config",
         "--ignore-rules",
+        "--json",
         "--output-last-message",
         outputFile,
         "--cd",
@@ -235,7 +231,7 @@ function buildInvocation(
       "-p",
       prompt,
       "--output-format",
-      "json",
+      "stream-json",
       "--mode",
       "ask",
       "--sandbox",
@@ -247,28 +243,191 @@ function buildInvocation(
   };
 }
 
-function parseHarnessOutput(
+export interface ParsedSemanticHarnessOutput {
+  text: string;
+  executedModelId?: string;
+  usage?: SemanticUsageReceiptV1;
+}
+
+export function parseSemanticHarnessOutput(
   harness: SemanticHarness,
-  raw: string,
-): { text: string; executedModelId?: string } {
-  if (harness === "codex") return { text: raw };
+  stdout: string,
+  outputFileText?: string,
+): ParsedSemanticHarnessOutput {
+  if (harness === "codex") return parseCodexOutput(stdout, outputFileText);
+  if (harness === "cursor") return parseCursorOutput(stdout);
   try {
-    const envelope = JSON.parse(raw) as {
+    const envelope = JSON.parse(stdout) as {
       is_error?: boolean;
       result?: unknown;
+      structured_output?: unknown;
       model?: unknown;
+      usage?: unknown;
+      modelUsage?: unknown;
+      model_usage?: unknown;
     };
     if (envelope.is_error) throw new Error("harness returned an error envelope");
+    const structured = envelope.structured_output;
+    const modelUsage = objectValue(envelope.modelUsage) ?? objectValue(envelope.model_usage);
+    const modelUsageEntries = modelUsage ? Object.entries(modelUsage) : [];
+    const executedModelId =
+      typeof envelope.model === "string"
+        ? envelope.model
+        : modelUsageEntries.length === 1
+          ? modelUsageEntries[0]![0]
+          : undefined;
+    const usage = parseClaudeUsage(envelope.usage) ?? aggregateClaudeModelUsage(modelUsageEntries);
     return {
-      text: typeof envelope.result === "string" ? envelope.result : "",
-      ...(typeof envelope.model === "string" ? { executedModelId: envelope.model } : {}),
+      text:
+        structured !== undefined
+          ? JSON.stringify(structured)
+          : typeof envelope.result === "string"
+            ? envelope.result
+            : "",
+      ...(executedModelId ? { executedModelId } : {}),
+      ...(usage ? { usage } : {}),
     };
   } catch (error) {
-    if (error instanceof SyntaxError) return { text: raw };
+    if (error instanceof SyntaxError) return { text: stdout };
     throw error;
   }
 }
 
+function parseCodexOutput(stdout: string, outputFileText?: string): ParsedSemanticHarnessOutput {
+  const events = parseJsonLines(stdout);
+  const completed = [...events]
+    .reverse()
+    .find((event) => event.type === "turn.completed" && objectValue(event.usage));
+  const usage = completed ? parseCodexUsage(completed.usage) : undefined;
+  const streamedText = [...events]
+    .reverse()
+    .map((event) => objectValue(event.item))
+    .find((item) => item?.type === "agent_message" && typeof item.text === "string")?.text;
+  return {
+    text: outputFileText ?? (typeof streamedText === "string" ? streamedText : ""),
+    ...(usage ? { usage } : {}),
+  };
+}
+
+function parseCursorOutput(stdout: string): ParsedSemanticHarnessOutput {
+  const events = parseJsonLines(stdout);
+  const init = events.find(
+    (event) =>
+      event.type === "system" && event.subtype === "init" && typeof event.model === "string",
+  );
+  const terminal = [...events]
+    .reverse()
+    .find((event) => event.type === "result" && typeof event.result === "string");
+  if (!terminal) {
+    try {
+      const envelope = JSON.parse(stdout) as Record<string, unknown>;
+      if (envelope.is_error) throw new Error("harness returned an error envelope");
+      return {
+        text: typeof envelope.result === "string" ? envelope.result : "",
+        ...(typeof envelope.model === "string" ? { executedModelId: envelope.model } : {}),
+        ...(parseCursorUsage(envelope.usage) ? { usage: parseCursorUsage(envelope.usage) } : {}),
+      };
+    } catch (error) {
+      if (error instanceof SyntaxError) return { text: stdout };
+      throw error;
+    }
+  }
+  if (terminal.is_error) throw new Error("harness returned an error envelope");
+  const usage = parseCursorUsage(terminal.usage);
+  return {
+    text: terminal.result as string,
+    ...(typeof init?.model === "string" ? { executedModelId: init.model } : {}),
+    ...(usage ? { usage } : {}),
+  };
+}
+
+function parseClaudeUsage(value: unknown): SemanticUsageReceiptV1 | undefined {
+  const usage = objectValue(value);
+  if (!usage) return undefined;
+  return nativeSemanticUsage({
+    input_tokens: usage.input_tokens,
+    cached_input_tokens: usage.cache_read_input_tokens,
+    cache_creation_input_tokens: usage.cache_creation_input_tokens,
+    output_tokens: usage.output_tokens,
+    reasoning_tokens: usage.reasoning_tokens ?? usage.reasoning_output_tokens,
+    total_tokens: usage.total_tokens,
+  });
+}
+
+function aggregateClaudeModelUsage(
+  entries: [string, unknown][],
+): SemanticUsageReceiptV1 | undefined {
+  const values: Record<string, number> = {};
+  for (const [, raw] of entries) {
+    const usage = objectValue(raw);
+    if (!usage) continue;
+    addNumber(values, "input_tokens", usage.inputTokens);
+    addNumber(values, "cached_input_tokens", usage.cacheReadInputTokens);
+    addNumber(values, "cache_creation_input_tokens", usage.cacheCreationInputTokens);
+    addNumber(values, "output_tokens", usage.outputTokens);
+  }
+  return nativeSemanticUsage(values);
+}
+
+function parseCodexUsage(value: unknown): SemanticUsageReceiptV1 | undefined {
+  const usage = objectValue(value);
+  if (!usage) return undefined;
+  return nativeSemanticUsage({
+    input_tokens: usage.input_tokens,
+    cached_input_tokens: usage.cached_input_tokens,
+    cache_creation_input_tokens: usage.cache_write_input_tokens,
+    output_tokens: usage.output_tokens,
+    reasoning_tokens: usage.reasoning_output_tokens,
+    total_tokens: usage.total_tokens,
+  });
+}
+
+function parseCursorUsage(value: unknown): SemanticUsageReceiptV1 | undefined {
+  const usage = objectValue(value);
+  if (!usage) return undefined;
+  return nativeSemanticUsage({
+    input_tokens: usage.inputTokens ?? usage.input_tokens,
+    cached_input_tokens:
+      usage.cacheReadTokens ?? usage.cachedInputTokens ?? usage.cached_input_tokens,
+    cache_creation_input_tokens:
+      usage.cacheWriteTokens ?? usage.cacheCreationInputTokens ?? usage.cache_write_input_tokens,
+    output_tokens: usage.outputTokens ?? usage.output_tokens,
+    reasoning_tokens: usage.reasoningTokens ?? usage.reasoning_output_tokens,
+    total_tokens: usage.totalTokens ?? usage.total_tokens,
+  });
+}
+
+function parseJsonLines(raw: string): Record<string, unknown>[] {
+  return raw
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0)
+    .flatMap((line) => {
+      try {
+        const value = JSON.parse(line) as unknown;
+        return objectValue(value) ? [value as Record<string, unknown>] : [];
+      } catch {
+        return [];
+      }
+    });
+}
+
+function objectValue(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function addNumber(target: Record<string, number>, field: string, value: unknown): void {
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
+    target[field] = (target[field] ?? 0) + value;
+  }
+}
+
+function modelIdsMatch(attested: string, requested: string): boolean {
+  const normalize = (value: string) => value.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  return normalize(attested) === normalize(requested);
+}
+
 function semanticChildEnv(): NodeJS.ProcessEnv {
   const env = { ...process.env };
   for (const key of Object.keys(env)) {

package/src/core/semantic/contract.ts

@@ -3,7 +3,10 @@ import { type Static, type TProperties, type TSchema, Type } from "@sinclair/typ
 export const SEMANTIC_EVIDENCE_SCHEMA_VERSION = 1 as const;
 export const SEMANTIC_READ_MODEL_SCHEMA_VERSION = 2 as const;
 export const SEMANTIC_EVIDENCE_CONTRACT_VERSION = 1 as const;
-export const SEMANTIC_PROMPT_CONTRACT_VERSION = 3 as const;
+export const SEMANTIC_PROMPT_CONTRACT_VERSION = 4 as const;
+export const SEMANTIC_USAGE_SCHEMA_VERSION = 1 as const;
+export const SEMANTIC_VISIBLE_USAGE_ESTIMATOR_ID = "visible-o200k-base" as const;
+export const SEMANTIC_VISIBLE_USAGE_ESTIMATOR_VERSION = 1 as const;
 
 const StrictObject = <T extends TProperties>(properties: T) =>
   Type.Object(properties, { additionalProperties: false });
@@ -74,6 +77,16 @@ export const SEMANTIC_EVIDENCE_KINDS = [
   "recovery",
   "claim-conflict",
 ] as const;
+export const SEMANTIC_INVALID_REASON_CODES = [
+  "schema",
+  "identity",
+  "citation",
+  "basis",
+  "confidence",
+  "privacy",
+  "unsupported_claim",
+  "unknown",
+] as const;
 
 export type SemanticHarness = (typeof SEMANTIC_HARNESSES)[number];
 export type SemanticConfiguredModel = (typeof SEMANTIC_CONFIGURED_MODELS)[number];
@@ -81,6 +94,7 @@ export type SemanticPhase = (typeof SEMANTIC_PHASES)[number];
 export type SemanticExpressionCue = (typeof SEMANTIC_EXPRESSION_CUES)[number];
 export type SemanticTag = (typeof SEMANTIC_TAGS)[number];
 export type SemanticEvidenceKind = (typeof SEMANTIC_EVIDENCE_KINDS)[number];
+export type SemanticInvalidReasonCode = (typeof SEMANTIC_INVALID_REASON_CODES)[number];
 export type SemanticBasis =
   | "direct-fact"
   | "deterministic-projection"
@@ -98,12 +112,67 @@ const ExpressionCueSchema = Type.Union(
 );
 const TagSchema = Type.Union(SEMANTIC_TAGS.map((value) => Type.Literal(value)));
 const EvidenceKindSchema = Type.Union(SEMANTIC_EVIDENCE_KINDS.map((value) => Type.Literal(value)));
+const InvalidReasonCodeSchema = Type.Union(
+  SEMANTIC_INVALID_REASON_CODES.map((value) => Type.Literal(value)),
+);
 const ConfidenceSchema = Type.Union([
   Type.Literal("high"),
   Type.Literal("medium"),
   Type.Literal("low"),
 ]);
 
+const NativeUsageTokenSchema = StrictObject({
+  value: Type.Integer({ minimum: 0 }),
+  provenance: Type.Literal("native"),
+});
+const EstimatedUsageTokenSchema = StrictObject({
+  value: Type.Integer({ minimum: 0 }),
+  provenance: Type.Literal("estimated"),
+});
+const NativeUsageTokensSchema = StrictObject({
+  input_tokens: Type.Optional(NativeUsageTokenSchema),
+  cached_input_tokens: Type.Optional(NativeUsageTokenSchema),
+  cache_creation_input_tokens: Type.Optional(NativeUsageTokenSchema),
+  output_tokens: Type.Optional(NativeUsageTokenSchema),
+  reasoning_tokens: Type.Optional(NativeUsageTokenSchema),
+  total_tokens: Type.Optional(NativeUsageTokenSchema),
+});
+const EstimatedUsageTokensSchema = StrictObject({
+  input_tokens: EstimatedUsageTokenSchema,
+  output_tokens: EstimatedUsageTokenSchema,
+  total_tokens: EstimatedUsageTokenSchema,
+});
+
+export const SemanticNativeUsageReceiptV1Schema = StrictObject({
+  schema_version: Type.Literal(SEMANTIC_USAGE_SCHEMA_VERSION),
+  source: Type.Literal("native"),
+  scope: Type.Literal("harness-call"),
+  tokens: NativeUsageTokensSchema,
+});
+
+export const SemanticEstimatedUsageReceiptV1Schema = StrictObject({
+  schema_version: Type.Literal(SEMANTIC_USAGE_SCHEMA_VERSION),
+  source: Type.Literal("estimated"),
+  scope: Type.Literal("visible-payload"),
+  estimator: StrictObject({
+    id: Type.Literal(SEMANTIC_VISIBLE_USAGE_ESTIMATOR_ID),
+    version: Type.Literal(SEMANTIC_VISIBLE_USAGE_ESTIMATOR_VERSION),
+  }),
+  tokens: EstimatedUsageTokensSchema,
+});
+
+export const SemanticUnreportedUsageReceiptV1Schema = StrictObject({
+  schema_version: Type.Literal(SEMANTIC_USAGE_SCHEMA_VERSION),
+  source: Type.Literal("unreported"),
+  scope: Type.Literal("unreported"),
+});
+
+export const SemanticUsageReceiptV1Schema = Type.Union([
+  SemanticNativeUsageReceiptV1Schema,
+  SemanticEstimatedUsageReceiptV1Schema,
+  SemanticUnreportedUsageReceiptV1Schema,
+]);
+
 function SemanticFieldSchema<T extends TSchema>(
   value: T,
   options: {
@@ -207,12 +276,56 @@ export const SemanticModelReplyV2Schema = StrictObject({
 export function semanticModelReplyV2SchemaFor(expected: {
   generation_id: string;
   evidence_digest: string;
+  evidence_event_ids: string[];
 }) {
+  const citationSchema = Type.Union(
+    expected.evidence_event_ids.map((value) => Type.Literal(value)),
+  );
+  const field = <T extends TSchema>(
+    value: T,
+    options: {
+      allowEmptyCitations?: boolean;
+      kind?: "synthesis" | "prediction" | "expression";
+    } = {},
+  ) => {
+    const kind = options.kind ?? "synthesis";
+    return StrictObject({
+      value,
+      basis: Type.Literal(kind === "prediction" ? "prediction" : "model-synthesis"),
+      confidence:
+        kind === "prediction"
+          ? Type.Literal("low")
+          : kind === "expression"
+            ? Type.Union([Type.Literal("medium"), Type.Literal("low")])
+            : ConfidenceSchema,
+      evidence_event_ids: Type.Array(citationSchema, {
+        minItems: options.allowEmptyCitations ? 0 : 1,
+        maxItems: 16,
+        uniqueItems: true,
+      }),
+    });
+  };
   return StrictObject({
     schema_version: Type.Literal(SEMANTIC_READ_MODEL_SCHEMA_VERSION),
     generation_id: Type.Literal(expected.generation_id),
     evidence_digest: Type.Literal(expected.evidence_digest),
-    meaning: SemanticMeaningV2Schema,
+    meaning: StrictObject({
+      headline: field(Type.String({ minLength: 1, maxLength: 60 })),
+      summary: field(Type.String({ minLength: 1, maxLength: 240 })),
+      phase: field(PhaseSchema),
+      expression_cue: Type.Optional(field(ExpressionCueSchema, { kind: "expression" })),
+      purpose: Type.Optional(field(Type.String({ minLength: 1, maxLength: 180 }))),
+      recent_result: Type.Optional(field(Type.String({ minLength: 1, maxLength: 180 }))),
+      attention: Type.Optional(field(Type.String({ minLength: 1, maxLength: 180 }))),
+      next_step: Type.Optional(
+        field(Type.String({ minLength: 1, maxLength: 180 }), { kind: "prediction" }),
+      ),
+      tags: Type.Optional(
+        field(Type.Array(TagSchema, { maxItems: 8, uniqueItems: true }), {
+          allowEmptyCitations: true,
+        }),
+      ),
+    }),
   });
 }
 
@@ -246,6 +359,7 @@ export const SemanticAcceptedReadModelV2Schema = StrictObject({
   ...ReadModelBase,
   reader_outcome: Type.Literal("accepted"),
   reader: ResolvedReaderSchema,
+  receipt: Type.Optional(StrictObject({ usage: SemanticUsageReceiptV1Schema })),
   meaning: SemanticMeaningV2Schema,
 });
 
@@ -260,6 +374,7 @@ export const SemanticUnavailableReadModelV2Schema = StrictObject({
       Type.Literal("model_unavailable"),
       Type.Literal("model_mismatch"),
     ]),
+    usage: Type.Optional(SemanticUsageReceiptV1Schema),
   }),
 });
 
@@ -267,7 +382,15 @@ export const SemanticInvalidReadModelV2Schema = StrictObject({
   ...ReadModelBase,
   reader_outcome: Type.Literal("invalid"),
   reader: ResolvedReaderSchema,
-  receipt: StrictObject({ reason_code: Type.Literal("invalid_output") }),
+  receipt: StrictObject({
+    reason_code: Type.Literal("invalid_output"),
+    validation_issue_codes: Type.Array(InvalidReasonCodeSchema, {
+      minItems: 1,
+      maxItems: SEMANTIC_INVALID_REASON_CODES.length,
+      uniqueItems: true,
+    }),
+    usage: Type.Optional(SemanticUsageReceiptV1Schema),
+  }),
 });
 
 export const SemanticDeferredReadModelV2Schema = StrictObject({
@@ -294,5 +417,14 @@ export type SemanticField<T> = {
 };
 export type SemanticMeaningV2 = Static<typeof SemanticMeaningV2Schema>;
 export type SemanticModelReplyV2 = Static<typeof SemanticModelReplyV2Schema>;
+export type SemanticUsageToken =
+  | Static<typeof NativeUsageTokenSchema>
+  | Static<typeof EstimatedUsageTokenSchema>;
+export type SemanticNativeUsageReceiptV1 = Static<typeof SemanticNativeUsageReceiptV1Schema>;
+export type SemanticEstimatedUsageReceiptV1 = Static<typeof SemanticEstimatedUsageReceiptV1Schema>;
+export type SemanticUnreportedUsageReceiptV1 = Static<
+  typeof SemanticUnreportedUsageReceiptV1Schema
+>;
+export type SemanticUsageReceiptV1 = Static<typeof SemanticUsageReceiptV1Schema>;
 export type SemanticAcceptedReadModelV2 = Static<typeof SemanticAcceptedReadModelV2Schema>;
 export type SemanticAgentReadModelV2 = Static<typeof SemanticAgentReadModelV2Schema>;