@adhdev/daemon-core 0.9.82-rc.137 → 0.9.82-rc.138

package/src/commands/router.ts

@@ -3645,7 +3645,13 @@ export class DaemonCommandRouter {
 
             case 'get_pending_mesh_events': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
-                const events = drainPendingMeshCoordinatorEvents(meshId || undefined);
+                // (B3) Respect coordinatorDaemonId when the caller declares it
+                // so unicast events route to the right coordinator instead of
+                // being silently consumed by the first drainer.
+                const coordinatorDaemonId = typeof args?.coordinatorDaemonId === 'string' && args.coordinatorDaemonId.trim()
+                    ? args.coordinatorDaemonId.trim()
+                    : undefined;
+                const events = drainPendingMeshCoordinatorEvents(meshId || undefined, coordinatorDaemonId);
                 return { success: true, events };
             }
 
@@ -5887,7 +5893,13 @@ export class DaemonCommandRouter {
                         nodeStatuses.push(status);
                     }
 
-                    const pendingCoordinatorEvents = drainPendingMeshCoordinatorEvents(meshId);
+                    // (B3) Pass coordinatorDaemonId when the caller declares
+                    // it so v1.5 unicast routing (targetCoordinatorDaemonId)
+                    // delivers events to the right coordinator.
+                    const callerCoordinatorDaemonId = typeof args?.coordinatorDaemonId === 'string' && args.coordinatorDaemonId.trim()
+                        ? args.coordinatorDaemonId.trim()
+                        : undefined;
+                    const pendingCoordinatorEvents = drainPendingMeshCoordinatorEvents(meshId, callerCoordinatorDaemonId);
                     const previewFreshness = (() => {
                         const localRepoRoot = nodeStatuses
                             .map((node: any) => readStringValue(node?.git?.repoRoot, node?.repoRoot, node?.workspace))

package/src/config/chat-history.ts

@@ -1375,19 +1375,42 @@ function normalizeProviderNativeHistoryRecords(agentType: string, historySession
     if (!Array.isArray(records)) return [];
     const normalizedSessionId = normalizeSavedHistorySessionId(historySessionId);
     return records
-        .map((record: any) => sanitizeHistoryMessage(agentType, {
-            ts: typeof record?.ts === 'string' ? record.ts : new Date(Number(record?.receivedAt) || Date.now()).toISOString(),
-            receivedAt: Number(record?.receivedAt) || Date.parse(record?.ts || '') || Date.now(),
-            role: record?.role,
-            content: String(record?.content || ''),
-            kind: record?.kind || (record?.role === 'system' ? 'session_start' : 'standard'),
-            senderName: record?.senderName,
-            agent: agentType,
-            instanceId: record?.instanceId,
-            historySessionId: normalizeSavedHistorySessionId(record?.historySessionId || normalizedSessionId),
-            sessionTitle: record?.sessionTitle,
-            workspace: record?.workspace,
-        } as HistoryMessage))
+        .map((record: any) => {
+            const base: HistoryMessage = {
+                ts: typeof record?.ts === 'string' ? record.ts : new Date(Number(record?.receivedAt) || Date.now()).toISOString(),
+                receivedAt: Number(record?.receivedAt) || Date.parse(record?.ts || '') || Date.now(),
+                role: record?.role,
+                content: String(record?.content || ''),
+                kind: record?.kind || (record?.role === 'system' ? 'session_start' : 'standard'),
+                senderName: record?.senderName,
+                agent: agentType,
+                instanceId: record?.instanceId,
+                historySessionId: normalizeSavedHistorySessionId(record?.historySessionId || normalizedSessionId),
+                sessionTitle: record?.sessionTitle,
+                workspace: record?.workspace,
+            } as HistoryMessage;
+            // (A2.3 v2 identity passthrough) — if the producer (native_history.js)
+            // emitted v2 stable identity, keep it across the sanitize layer so
+            // downstream (chat-commands.ts normalizeNativeHistoryMessages) sees
+            // the producer's contract output instead of recomputing from index
+            // and content hash. v1 producers without these fields are unaffected.
+            if (typeof record?.providerUnitKey === 'string' && record.providerUnitKey) {
+                (base as any).providerUnitKey = record.providerUnitKey;
+            }
+            if (typeof record?.bubbleId === 'string' && record.bubbleId) {
+                (base as any).bubbleId = record.bubbleId;
+            }
+            if (typeof record?.sequence === 'number' && Number.isFinite(record.sequence)) {
+                (base as any).sequence = record.sequence;
+            }
+            if (typeof record?._turnKey === 'string' && record._turnKey) {
+                (base as any)._turnKey = record._turnKey;
+            }
+            if (typeof record?.bubbleState === 'string' && record.bubbleState) {
+                (base as any).bubbleState = record.bubbleState;
+            }
+            return sanitizeHistoryMessage(agentType, base);
+        })
         .filter(Boolean) as HistoryMessage[];
 }
 

package/src/mesh/contracts.ts

@@ -0,0 +1,329 @@
+/**
+ * Mesh contract v2 — first-class identity, scopes, and protocol version.
+ *
+ * Replaces the implicit conventions that grew across mesh-events.ts,
+ * mesh-work-queue.ts, mesh-ledger.ts, and mesh-tools.ts where the same
+ * concept (a coordinator, a session, a task status) appeared in different
+ * shapes per file. The audit found:
+ *
+ *   - PendingMeshCoordinatorEvent had no targetCoordinatorDaemonId. All
+ *     events were broadcast to every coordinator that drained them. Two
+ *     coordinators sharing a mesh would each receive every event,
+ *     leading to duplicate completion handling and missed targeting.
+ *   - drainPendingMeshCoordinatorEvents accepted only meshId. The caller's
+ *     coordinator identity was never available, so per-coordinator
+ *     routing was impossible by construction.
+ *   - Session identifier keys diverged across stores: targetSessionId /
+ *     assignedSessionId / instanceId / runtimeSessionId / providerSessionId.
+ *     resolveEventSessionId() tried four fallbacks per call.
+ *   - No protocol version on the JSONL ledger or BeadsDB. Schema
+ *     evolutions had no guard rail.
+ *   - mesh_reconcile_ledger existed as a routine recovery tool, not as
+ *     an incident-response escape hatch. That itself signals the routing
+ *     layer cannot be trusted.
+ *
+ * This module introduces the types; the actual wiring lands in B2 (data
+ * model + 3-way transactional store), B3 (MCP layer enforcement), and B4
+ * (frontend consumption). B1 is intentionally non-breaking — it adds the
+ * types and leaves runtime behaviour unchanged.
+ */
+
+/** Provider type identifier (e.g. 'claude-cli', 'codex-cli', 'roo-code').
+ *  Free-form string; no shared enum exists in daemon-core yet. */
+type ProviderType = string;
+
+// ─── Protocol version ────────────────────────────────────────────────────
+
+export const MESH_PROTOCOL_VERSION_V1 = '1.0' as const;
+export const MESH_PROTOCOL_VERSION_V2 = '2.0' as const;
+
+export type MeshProtocolVersion =
+  | typeof MESH_PROTOCOL_VERSION_V1
+  | typeof MESH_PROTOCOL_VERSION_V2;
+
+export const SUPPORTED_MESH_PROTOCOL_VERSIONS: readonly MeshProtocolVersion[] = [
+  MESH_PROTOCOL_VERSION_V1,
+  MESH_PROTOCOL_VERSION_V2,
+] as const;
+
+export function isSupportedMeshProtocolVersion(value: unknown): value is MeshProtocolVersion {
+  return typeof value === 'string'
+    && (SUPPORTED_MESH_PROTOCOL_VERSIONS as readonly string[]).includes(value);
+}
+
+// ─── Coordinator identity ────────────────────────────────────────────────
+
+/**
+ * Identity of a mesh coordinator. Required (non-optional) on every dispatch
+ * and drain operation in v2 — opaque/missing identity is the audit's
+ * smoking gun for routing failures and is structurally banned by the v2
+ * types.
+ *
+ * - daemonId: the machineId of the daemon hosting the coordinator. Stable
+ *   across coordinator restarts on the same machine.
+ * - coordinatorRunId: a UUID generated when the coordinator process starts.
+ *   Stable for the coordinator's lifetime, fresh on restart. Required so
+ *   two coordinators on the same daemon (one CLI, one MCP) can be told
+ *   apart without conflating their drains.
+ * - sessionId: optional CLI coordinator session identifier (instanceId).
+ *   Present when the coordinator is itself a CLI session, absent for
+ *   pure MCP coordinators.
+ */
+export interface CoordinatorIdentity {
+  readonly daemonId: string;
+  readonly coordinatorRunId: string;
+  readonly sessionId?: string;
+}
+
+export function coordinatorIdentityEquals(a: CoordinatorIdentity, b: CoordinatorIdentity): boolean {
+  return a.daemonId === b.daemonId
+      && a.coordinatorRunId === b.coordinatorRunId
+      && (a.sessionId ?? '') === (b.sessionId ?? '');
+}
+
+export function coordinatorIdentityKey(identity: CoordinatorIdentity): string {
+  // Stable string form for map keys and ledger payloads. Avoids the
+  // {a:b, c:d} JSON.stringify ordering trap by enforcing field order.
+  return `${identity.daemonId}|${identity.coordinatorRunId}|${identity.sessionId ?? ''}`;
+}
+
+// ─── Session handle ──────────────────────────────────────────────────────
+
+/**
+ * Unified mesh session identifier. v1 referred to "the session" with five
+ * different field names depending on which store you were reading; v2
+ * collapses them into one explicit handle that carries every disambiguator
+ * a consumer might need.
+ *
+ * - nodeId: the mesh node this session belongs to (FK into mesh node table).
+ * - sessionId: provider-instance identifier (the runtime session id).
+ * - providerType: which provider category/type the session runs (e.g.
+ *   'claude-cli', 'codex-cli', 'roo-code').
+ * - coordinatorDaemonId: which coordinator dispatched the work that
+ *   spawned this session. Used for completion event routing.
+ * - assignedAt: ms epoch when the session was bound to its current task.
+ */
+export interface MeshSessionHandle {
+  readonly nodeId: string;
+  readonly sessionId: string;
+  readonly providerType: ProviderType;
+  readonly coordinatorDaemonId: string;
+  readonly assignedAt: number;
+}
+
+export function meshSessionHandleKey(handle: MeshSessionHandle): string {
+  return `${handle.nodeId}|${handle.sessionId}`;
+}
+
+// ─── Task status (canonical enum) ────────────────────────────────────────
+
+/**
+ * Single canonical task status enum. v1 had at least three overlapping
+ * sets (queue / ledger / direct-dispatch). v2 consumers import from here.
+ */
+export const MESH_TASK_STATUSES = [
+  'pending',
+  'assigned',
+  'in_progress',
+  'completed',
+  'failed',
+  'cancelled',
+] as const;
+export type MeshTaskStatus = typeof MESH_TASK_STATUSES[number];
+
+export function isMeshTaskStatus(value: unknown): value is MeshTaskStatus {
+  return typeof value === 'string'
+    && (MESH_TASK_STATUSES as readonly string[]).includes(value);
+}
+
+// ─── Event scope ─────────────────────────────────────────────────────────
+
+/**
+ * Explicit scope for pending coordinator events. v1 had no scope: every
+ * event was broadcast to every drainer. v2 forces producers to declare
+ * intent.
+ *
+ * - 'unicast': delivered to exactly one coordinator (intendedFor). Other
+ *   coordinators' drains skip it.
+ * - 'broadcast': delivered to every coordinator on the mesh. Used for
+ *   system-wide signals (e.g. mesh-wide policy changes). The v1 default
+ *   becomes explicit here so audit tools can flag unintended broadcasts.
+ * - 'system': delivered to the daemon-level handler, not coordinators.
+ *   Reserved for infrastructure events that no coordinator should see
+ *   (e.g. ledger reconciliation outcomes).
+ */
+export const MESH_EVENT_SCOPES = ['unicast', 'broadcast', 'system'] as const;
+export type MeshEventScope = typeof MESH_EVENT_SCOPES[number];
+
+export function isMeshEventScope(value: unknown): value is MeshEventScope {
+  return typeof value === 'string'
+    && (MESH_EVENT_SCOPES as readonly string[]).includes(value);
+}
+
+// ─── Pending coordinator event v2 ────────────────────────────────────────
+
+/**
+ * v2 shape of a pending coordinator event. Strict supersets of the v1
+ * shape — every v1 field is preserved so existing readers do not break;
+ * v2 fields (scope, dispatchedBy, intendedFor, protocolVersion) are
+ * additive and consulted by v2-aware drainers only.
+ *
+ * Mixed v1/v2 events coexist during the rollout window. B2 fully cuts
+ * over once every coordinator drain is v2-aware.
+ */
+export interface PendingMeshCoordinatorEventV2 {
+  // v1 fields (preserved exactly)
+  readonly event: string;
+  readonly meshId: string;
+  readonly nodeLabel: string;
+  readonly nodeId?: string;
+  readonly workspace?: string;
+  readonly metadataEvent: Record<string, unknown>;
+  readonly coordinatorMessage?: string;
+  readonly queuedAt: number;
+
+  // v2 additions
+  readonly protocolVersion: MeshProtocolVersion;
+  readonly scope: MeshEventScope;
+  readonly dispatchedBy: CoordinatorIdentity;
+  /**
+   * Required when scope === 'unicast', forbidden otherwise. Drainers MUST
+   * skip unicast events whose intendedFor does not equal their own identity.
+   */
+  readonly intendedFor?: CoordinatorIdentity;
+}
+
+// ─── Ledger entry v2 ─────────────────────────────────────────────────────
+
+/**
+ * v2 ledger entry additions. The originatingCoordinator field is the
+ * source of truth that lets completion events route back to the
+ * coordinator that dispatched the task. v1's "worker settings carried it
+ * if it happened to be set" approach is replaced.
+ */
+export interface MeshLedgerOriginatingCoordinatorV2 {
+  readonly originatingCoordinator: CoordinatorIdentity;
+  readonly protocolVersion: MeshProtocolVersion;
+}
+
+// ─── Validation primitives ───────────────────────────────────────────────
+
+export class MeshContractViolationError extends Error {
+  readonly violationPath: string;
+  readonly protocolVersion: MeshProtocolVersion;
+  constructor(
+    protocolVersion: MeshProtocolVersion,
+    violationPath: string,
+    detail: string,
+  ) {
+    super(`mesh contract ${protocolVersion} violation at ${violationPath}: ${detail}`);
+    this.name = 'MeshContractViolationError';
+    this.violationPath = violationPath;
+    this.protocolVersion = protocolVersion;
+  }
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+export function assertCoordinatorIdentity(raw: unknown, path: string): CoordinatorIdentity {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, path, 'must be an object');
+  }
+  const obj = raw as Record<string, unknown>;
+  if (!isNonEmptyString(obj.daemonId)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.daemonId`, 'must be a non-empty string');
+  }
+  if (!isNonEmptyString(obj.coordinatorRunId)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.coordinatorRunId`, 'must be a non-empty string');
+  }
+  const sessionId = obj.sessionId;
+  if (sessionId !== undefined && !isNonEmptyString(sessionId)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.sessionId`, 'must be a non-empty string when provided');
+  }
+  return sessionId !== undefined
+    ? { daemonId: obj.daemonId, coordinatorRunId: obj.coordinatorRunId, sessionId }
+    : { daemonId: obj.daemonId, coordinatorRunId: obj.coordinatorRunId };
+}
+
+export function assertPendingMeshCoordinatorEventV2(raw: unknown, path = '$'): PendingMeshCoordinatorEventV2 {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, path, 'must be an object');
+  }
+  const obj = raw as Record<string, unknown>;
+  if (!isSupportedMeshProtocolVersion(obj.protocolVersion)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.protocolVersion`, `must be one of ${SUPPORTED_MESH_PROTOCOL_VERSIONS.join(', ')}`);
+  }
+  if (!isMeshEventScope(obj.scope)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.scope`, `must be one of ${MESH_EVENT_SCOPES.join(', ')}`);
+  }
+  if (!isNonEmptyString(obj.event)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.event`, 'must be a non-empty string');
+  }
+  if (!isNonEmptyString(obj.meshId)) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.meshId`, 'must be a non-empty string');
+  }
+  const dispatchedBy = assertCoordinatorIdentity(obj.dispatchedBy, `${path}.dispatchedBy`);
+
+  if (obj.scope === 'unicast') {
+    if (!obj.intendedFor) {
+      throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.intendedFor`, 'unicast scope requires intendedFor');
+    }
+  } else if (obj.intendedFor !== undefined) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.intendedFor`, 'only unicast scope may set intendedFor');
+  }
+  const intendedFor = obj.intendedFor
+    ? assertCoordinatorIdentity(obj.intendedFor, `${path}.intendedFor`)
+    : undefined;
+
+  const metadata = obj.metadataEvent && typeof obj.metadataEvent === 'object' && !Array.isArray(obj.metadataEvent)
+    ? (obj.metadataEvent as Record<string, unknown>)
+    : null;
+  if (!metadata) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.metadataEvent`, 'must be an object');
+  }
+  const queuedAt = typeof obj.queuedAt === 'number' && Number.isFinite(obj.queuedAt) ? obj.queuedAt : null;
+  if (queuedAt === null) {
+    throw new MeshContractViolationError(MESH_PROTOCOL_VERSION_V2, `${path}.queuedAt`, 'must be a finite number');
+  }
+
+  return {
+    event: obj.event,
+    meshId: obj.meshId,
+    nodeLabel: isNonEmptyString(obj.nodeLabel) ? obj.nodeLabel : '',
+    nodeId: typeof obj.nodeId === 'string' ? obj.nodeId : undefined,
+    workspace: typeof obj.workspace === 'string' ? obj.workspace : undefined,
+    metadataEvent: metadata,
+    coordinatorMessage: typeof obj.coordinatorMessage === 'string' ? obj.coordinatorMessage : undefined,
+    queuedAt,
+    protocolVersion: obj.protocolVersion,
+    scope: obj.scope,
+    dispatchedBy,
+    ...(intendedFor ? { intendedFor } : {}),
+  };
+}
+
+// ─── Routing helper ──────────────────────────────────────────────────────
+
+/**
+ * Decide whether a v2 pending event should be delivered to the given drainer.
+ * Centralised so every drain implementation uses the same rule.
+ *
+ *   - 'broadcast': always delivered.
+ *   - 'system': never delivered to coordinators (system handler only).
+ *   - 'unicast': delivered iff intendedFor matches drainer identity.
+ *
+ * v1 events (no scope / no protocolVersion) are treated as broadcast for
+ * backward compatibility during rollout; B3 tightens this so v1 events
+ * are quarantined to a dedicated drain endpoint instead.
+ */
+export function shouldDeliverPendingEventToCoordinator(
+  event: PendingMeshCoordinatorEventV2,
+  drainer: CoordinatorIdentity,
+): boolean {
+  if (event.scope === 'system') return false;
+  if (event.scope === 'broadcast') return true;
+  if (!event.intendedFor) return false;
+  return coordinatorIdentityEquals(event.intendedFor, drainer);
+}

package/src/providers/contracts.ts

@@ -15,6 +15,14 @@ import type { ChatMessageKind } from './chat-message-normalization.js';
 export type ReadChatTurnStatus = 'open' | 'waiting_approval' | 'complete' | 'error';
 
 export interface ReadChatResult {
+  /**
+   * Declared chat contract version. Absent or `'1.0'` → legacy v1 payload
+   * (current shape). `'2.0'` → v2 payload conforming to transcript-v2.ts
+   * (ReadChatResultV2). Validators in read-chat-contract.ts route on this
+   * field. A1 only adds the field; A2 will make v2 the daemon-internal
+   * canonical form and reject unrecognised versions at provider load time.
+   */
+  contractVersion?: import('./transcript-v2.js').ChatContractVersion;
   messages: ChatMessage[];
   status: AgentStatus;
   activeModal?: ModalInfo | null;
@@ -702,6 +710,17 @@ export interface ProviderCanonicalHistoryConfig {
    * Omitted mode defaults to 'native-source'.
    */
   mode?: 'native-source' | 'materialized-mirror' | 'disabled';
+  /**
+   * Chat transcript contract version this provider's read_chat output
+   * conforms to. See transcript-v2.ts for the v2 invariants. Absent or `'1.0'`
+   * → legacy v1 payload (current behaviour). `'2.0'` → strict v2 payload
+   * (stable providerUnitKey/bubbleId/sequence, strict enums, honest coverage).
+   *
+   * A1 only surfaces this field; validators in read-chat-contract.ts route
+   * on it. A2 makes v2 the daemon-internal canonical form and rejects
+   * unrecognised values at provider load time.
+   */
+  contractVersion?: import('./transcript-v2.js').ChatContractVersion;
 }
 
 /**

package/src/providers/provider-loader.ts

@@ -1378,11 +1378,15 @@ export class ProviderLoader {
       return args ? args.map((arg) => /\s/.test(arg) ? JSON.stringify(arg) : arg).join(' ') : '';
     }
     const schemaDef = this.getSettingsSchema(providerType)[key];
-    const defaultVal = schemaDef
-      ? (key === 'autoApprove' && schemaDef.type === 'boolean'
-        ? true
-        : schemaDef.default)
-      : undefined;
+    // (fix) Previously this hard-coded `autoApprove` boolean default to `true`,
+    // overriding whatever schemaDef.default the provider.json declared. That
+    // surfaced as soon as a provider added an `autoApprove` schema entry with
+    // default=false: the user had never opted in but the daemon treated the
+    // session as auto-approve, which then triggered recordAutoApproval every
+    // time the CLI showed an approval modal — producing a flood of system
+    // "Auto-approved: ..." messages and keeping the session pinned to
+    // generating while modals cycled in and out. Trust the schemaDef.default.
+    const defaultVal = schemaDef ? schemaDef.default : undefined;
 
     const config = this.readConfig();
     const userVal = config?.providerSettings?.[providerType]?.[key];
@@ -1496,10 +1500,17 @@ export class ProviderLoader {
       ...this.getSyntheticSettings(type, provider),
       ...(provider.settings || {}),
     };
+    // (fix) Previously this clause forced `autoApprove.default = true` for any
+    // boolean autoApprove schema, even when the provider.json explicitly set
+    // `default: false`. Combined with the synthetic-settings fallback at
+    // getSyntheticSettings (which also defaults autoApprove to true when the
+    // provider doesn't supply one), that meant CLI providers silently turned on
+    // auto-approval, producing a flood of "Auto-approved: ..." system messages
+    // every time an approval modal appeared and pinning the session to
+    // generating while modals cycled. Trust the provider's declared default.
     if (result.autoApprove?.type === 'boolean') {
       result.autoApprove = {
         ...result.autoApprove,
-        default: true,
         public: true,
         label: result.autoApprove.label || 'Auto Approve',
         description: result.autoApprove.description || 'Automatically approve actionable prompts without sending approval alerts.',
@@ -1524,7 +1535,10 @@ export class ProviderLoader {
     if (!provider.settings?.autoApprove) {
       result.autoApprove = {
         type: 'boolean',
-        default: true,
+        // (fix) Safe default is *off*. Auto-approving every modal without the
+        // user opting in produced silent-bash-execution surprises and the
+        // "Auto-approved: ..." system-message flood seen on AGY/Codex.
+        default: false,
         public: true,
         label: 'Auto Approve',
         description: 'Automatically approve actionable prompts without sending approval alerts.',

package/src/providers/provider-schema.ts

@@ -253,6 +253,16 @@ function validateCanonicalHistory(raw: unknown, errors: string[]): void {
     errors.push('canonicalHistory.mode must be one of: native-source, materialized-mirror, disabled')
   }
 
+  // Chat transcript contract version (transcript-v2.ts). Absent → treated as
+  // v1 by readDeclaredChatContractVersion(). A2 will reject unrecognised
+  // values at load time; A1 only validates the field shape.
+  const chatContractVersion = canonicalHistory.contractVersion
+  if (chatContractVersion !== undefined
+      && chatContractVersion !== '1.0'
+      && chatContractVersion !== '2.0') {
+    errors.push(`canonicalHistory.contractVersion must be '1.0' or '2.0' when provided (got ${JSON.stringify(chatContractVersion)})`)
+  }
+
   const scripts = canonicalHistory.scripts
   if (scripts === undefined) return
   if (!scripts || typeof scripts !== 'object' || Array.isArray(scripts)) {

package/src/providers/read-chat-contract.ts

@@ -1,6 +1,14 @@
 import type { MessagePart, ModalInfo, ReadChatResult } from './contracts.js'
 import { normalizeMessageParts } from './contracts.js'
 import type { ChatBubbleState, ChatMessage } from '../types.js'
+import {
+  CHAT_CONTRACT_VERSION_V1,
+  CHAT_CONTRACT_VERSION_V2,
+  assertReadChatResultV2Payload,
+  isSupportedChatContractVersion,
+  type ChatContractVersion,
+  type ReadChatResultV2,
+} from './transcript-v2.js'
 
 const VALID_STATUSES = ['idle', 'generating', 'waiting_approval', 'error', 'panel_hidden', 'starting', 'streaming', 'long_generating'] as const
 const VALID_ROLES = ['user', 'assistant', 'system', 'human'] as const
@@ -63,7 +71,7 @@ function validateMessage(message: unknown, source: string, index: number): ChatM
     content: validateMessageContent(message.content, source, index),
   }
 
-  if (typeof message.kind === 'string') normalized.kind = message.kind as any
+  if (typeof message.kind === 'string') normalized.kind = message.kind as ChatMessage['kind']
   if (typeof message.id === 'string') normalized.id = message.id
   if (typeof message.bubbleId === 'string') normalized.bubbleId = message.bubbleId
   if (typeof message.providerUnitKey === 'string') normalized.providerUnitKey = message.providerUnitKey
@@ -71,20 +79,23 @@ function validateMessage(message: unknown, source: string, index: number): ChatM
   if (isFiniteNumber(message.index)) normalized.index = message.index
   if (isFiniteNumber(message.timestamp)) normalized.timestamp = message.timestamp
   if (isFiniteNumber(message.receivedAt)) normalized.receivedAt = message.receivedAt
-  if (typeof (message as any)._turnKey === 'string') normalized._turnKey = (message as any)._turnKey
-  if (Array.isArray(message.toolCalls)) normalized.toolCalls = message.toolCalls as any
-  if (isPlainObject(message.meta)) normalized.meta = message.meta as any
+  // (A2.3) sequence is the monotonic ordering key consumed by ChatSourceMachine.
+  // v1 producers omit it; the daemon derives it in normalizeNativeHistoryMessages.
+  if (isFiniteNumber(message.sequence)) normalized.sequence = message.sequence
+  if (typeof message._turnKey === 'string') normalized._turnKey = message._turnKey
+  if (Array.isArray(message.toolCalls)) normalized.toolCalls = message.toolCalls as ChatMessage['toolCalls']
+  if (isPlainObject(message.meta)) normalized.meta = message.meta as ChatMessage['meta']
   if (typeof message.senderName === 'string') normalized.senderName = message.senderName
-  if (typeof (message as any)._type === 'string') normalized._type = (message as any)._type
-  if (typeof (message as any)._sub === 'string') normalized._sub = (message as any)._sub
-  if (typeof (message as any).visibility === 'string') normalized.visibility = (message as any).visibility
-  if (typeof (message as any).transcriptVisibility === 'string') normalized.transcriptVisibility = (message as any).transcriptVisibility
-  if (typeof (message as any).audience === 'string') normalized.audience = (message as any).audience
-  if (typeof (message as any).source === 'string') normalized.source = (message as any).source
-  if (typeof (message as any).userFacing === 'boolean') normalized.userFacing = (message as any).userFacing
-  if (typeof (message as any).internal === 'boolean') normalized.internal = (message as any).internal
-  if (typeof (message as any).isInternal === 'boolean') normalized.isInternal = (message as any).isInternal
-  if (typeof (message as any).debug === 'boolean') normalized.debug = (message as any).debug
+  if (typeof message._type === 'string') normalized._type = message._type
+  if (typeof message._sub === 'string') normalized._sub = message._sub
+  if (typeof message.visibility === 'string') normalized.visibility = message.visibility
+  if (typeof message.transcriptVisibility === 'string') normalized.transcriptVisibility = message.transcriptVisibility
+  if (typeof message.audience === 'string') normalized.audience = message.audience
+  if (typeof message.source === 'string') normalized.source = message.source
+  if (typeof message.userFacing === 'boolean') normalized.userFacing = message.userFacing
+  if (typeof message.internal === 'boolean') normalized.internal = message.internal
+  if (typeof message.isInternal === 'boolean') normalized.isInternal = message.isInternal
+  if (typeof message.debug === 'boolean') normalized.debug = message.debug
 
   return normalized
 }
@@ -129,6 +140,55 @@ function validateControlValues(controlValues: unknown, source: string): Record<s
   return normalized
 }
 
+/**
+ * Read the producer-declared contract version from a raw read_chat payload.
+ * Returns v1 when absent or unrecognised, so legacy producers keep working
+ * through A1. A2 will tighten this to throw when an unsupported version is
+ * declared.
+ */
+export function readPayloadContractVersion(raw: unknown): ChatContractVersion {
+  if (!isPlainObject(raw)) return CHAT_CONTRACT_VERSION_V1
+  const declared = (raw as Record<string, unknown>).contractVersion
+  if (isSupportedChatContractVersion(declared)) return declared
+  return CHAT_CONTRACT_VERSION_V1
+}
+
+/**
+ * Validate a v2 payload. Thin wrapper around assertReadChatResultV2Payload
+ * that prefixes the contract violation with the caller's source label.
+ */
+export function validateReadChatResultV2Payload(raw: unknown, source = 'read_chat'): ReadChatResultV2 {
+  try {
+    return assertReadChatResultV2Payload(raw)
+  } catch (err) {
+    if (err instanceof Error) {
+      err.message = `${source}: ${err.message}`
+    }
+    throw err
+  }
+}
+
+/**
+ * Versioned entry point. Routes on the producer-declared contractVersion:
+ *   - v2 → strict v2 validation (transcript-v2.ts invariants)
+ *   - v1 (or absent) → legacy permissive validation
+ *
+ * Callers that have not yet been audited to handle v2 outputs should use
+ * validateReadChatResultPayload directly; that path stays bound to v1 shape
+ * during the A1 transition.
+ */
+export function validateReadChatResultPayloadVersioned(
+  raw: unknown,
+  source = 'read_chat',
+): { version: typeof CHAT_CONTRACT_VERSION_V1; payload: ReadChatResult & Record<string, unknown> }
+  | { version: typeof CHAT_CONTRACT_VERSION_V2; payload: ReadChatResultV2 } {
+  const version = readPayloadContractVersion(raw)
+  if (version === CHAT_CONTRACT_VERSION_V2) {
+    return { version, payload: validateReadChatResultV2Payload(raw, source) }
+  }
+  return { version: CHAT_CONTRACT_VERSION_V1, payload: validateReadChatResultPayload(raw, source) }
+}
+
 export function validateReadChatResultPayload(raw: unknown, source = 'read_chat'): ReadChatResult & Record<string, unknown> {
   if (!isPlainObject(raw)) {
     throw new Error(`${source}: payload must be an object`)