@adhdev/mesh-shared 1.0.60-rc.4 → 1.0.60-rc.41

package/dist/turn-evidence.d.ts

@@ -0,0 +1,407 @@
+/**
+ * turn-evidence — the ONE vocabulary for "what happened to a turn".
+ *
+ * Wiring-unification Phase C1 (docs/design/2026-09-23-wiring-unification.md §5).
+ *
+ * Every producer that today decides "done" on its own (completion flush, stall
+ * rescue, reconcile synthesis, MCP probes, worker report tools, …) instead
+ * submits one of these evidence records to the turn ledger, whose pure reducer
+ * is the only authority for a turn's state. Worker daemons and the MCP server
+ * build them, so the types live here (a dependency-free leaf).
+ *
+ * CONTENT-FREE BY CONSTRUCTION
+ * ----------------------------
+ * Evidence crosses machines (seqscribe `mesh.<id>.events` replication) and must
+ * never carry anything a user or an agent wrote. Every field is one of: an
+ * identifier, a closed enum, a boolean, a number, or a `SummaryRef` — a pointer
+ * `{topic, writer, seq}` to a content-class topic entry (`mesh.<id>.handoff`)
+ * where the text actually lives. `TURN_EVIDENCE_FIELD_SPECS` declares the class
+ * of every field of every member (the compiler forces it to stay total and
+ * exact), the runtime guard validates against it, and a test walks it to prove
+ * no free-text field exists.
+ */
+import { type WorkerBranchState, type WorkerReportOutcome } from './mesh-vocabulary';
+import { type SessionStatus } from './session-status';
+import { type SendRefusal } from './outbound-message';
+/** Protocol version stamped on every `mesh.<id>.events` entry written by the turn ledger. */
+export declare const MESH_TOPIC_PROTOCOL_VERSION: 2;
+export declare const EVIDENCE_SOURCE_IDS: readonly ["fsm_edge", "short_gen_inline", "completion_flush_genuine", "completion_flush_weak", "monitor_final_summary", "pre_cleanup_transcript", "stall_transcript", "startup_grace_collapse", "acp_prompt_response", "cdp_state", "approval_gate", "modal_button", "mesh_stall_watchdog", "status_monitor", "pty_exit", "provider_error", "coordinator_probe", "mcp_probe", "worker_tool", "dispatch", "input_service", "operator", "intentional_cleanup", "scheduler", "git_probe", "session_registry"];
+export type EvidenceSourceId = typeof EVIDENCE_SOURCE_IDS[number];
+export declare const TURN_SCOPES: readonly ["mesh_queue", "mesh_direct", "plain"];
+export type TurnScope = typeof TURN_SCOPES[number];
+/**
+ * Refusals (D1 `SendRefusal`, owned by ./outbound-message) that mean the target
+ * can never take this dispatch, so the attempt is reclaimed (R3). Every other
+ * refusal is retried by the sender and only recorded.
+ */
+export declare const RECLAIMING_SEND_REFUSALS: readonly ["session_exited", "no_target", "unsupported_input"];
+export type ReclaimingSendRefusal = typeof RECLAIMING_SEND_REFUSALS[number];
+export declare const DELIVERY_OUTCOMES: readonly ["delivered", "queued"];
+export type DeliveryOutcome = typeof DELIVERY_OUTCOMES[number];
+export declare const DELIVERY_VIAS: readonly ["local", "p2p"];
+export type DeliveryVia = typeof DELIVERY_VIAS[number];
+export declare const DISPATCH_FAILURE_REASONS: readonly ["worker_absent", "transport_error", "spawn_failed", "rejected_by_worker", "timeout"];
+export type DispatchFailureReason = typeof DISPATCH_FAILURE_REASONS[number];
+export declare const CONSUME_PROFILES: readonly ["default", "native_source"];
+export type ConsumeProfile = typeof CONSUME_PROFILES[number];
+export declare const SESSION_REBOUND_REASONS: readonly ["restart", "live_holder"];
+export type SessionReboundReason = typeof SESSION_REBOUND_REASONS[number];
+export declare const SUSPENSION_MODALS: readonly ["approval", "choice"];
+export type SuspensionModal = typeof SUSPENSION_MODALS[number];
+export declare const SUSPENSION_RESOLUTIONS: readonly ["approved", "rejected", "answered"];
+export type SuspensionResolution = typeof SUSPENSION_RESOLUTIONS[number];
+export declare const SUSPENSION_RESOLUTION_VIAS: readonly ["modal_button", "auto_approve", "prompt_answer"];
+export type SuspensionResolutionVia = typeof SUSPENSION_RESOLUTION_VIAS[number];
+export declare const TURN_END_STRENGTHS: readonly ["genuine", "weak"];
+export type TurnEndStrength = typeof TURN_END_STRENGTHS[number];
+/** Why a provider-side weak end was released (was free text `blockReason`). */
+export declare const TURN_END_BLOCK_REASONS: readonly ["missing_final_assistant", "finalization_timeout", "terminal_block_hard_cap", "decoupled_completion"];
+export type TurnEndBlockReason = typeof TURN_END_BLOCK_REASONS[number];
+export declare const NATIVE_TURN_OUTCOMES: readonly ["completed", "aborted"];
+export type NativeTurnOutcome = typeof NATIVE_TURN_OUTCOMES[number];
+export declare const LIVENESS_RESULTS: readonly ["alive", "unknown", "read_failed", "dead"];
+export type LivenessResult = typeof LIVENESS_RESULTS[number];
+export declare const PROVIDER_FAILURES: readonly ["auth_failed", "billing_failed"];
+export type ProviderFailure = typeof PROVIDER_FAILURES[number];
+/**
+ * `daemon_restart` (wiring-unification follow-up, design §5): a boot-time
+ * reconciliation observes this for a plain attempt whose session is gone
+ * after a restart — the daemon never saw the session's own exit, so it is
+ * not `provider_error`/`adapter_error`/etc.; it is the daemon itself
+ * reporting "this session no longer exists".
+ */
+export declare const SESSION_ERROR_REASONS: readonly ["provider_error", "adapter_error", "spawn_failed", "auth_failed", "billing_failed", "unknown", "daemon_restart"];
+export type SessionErrorReason = typeof SESSION_ERROR_REASONS[number];
+export declare const CANCEL_REASONS: readonly ["operator_cancel", "intentional_cleanup", "task_removed", "mission_abandoned", "superseded"];
+export type CancelReason = typeof CANCEL_REASONS[number];
+export declare const OPERATOR_STATUSES: readonly ["completed", "failed"];
+export type OperatorStatus = typeof OPERATOR_STATUSES[number];
+export declare const OPERATOR_STATUS_REASONS: readonly ["operator_update", "refine_terminal", "validation_terminal"];
+export type OperatorStatusReason = typeof OPERATOR_STATUS_REASONS[number];
+export declare const COORDINATOR_ACK_OUTCOMES: readonly ["delivered", "queued", "duplicate"];
+export type CoordinatorAckOutcome = typeof COORDINATOR_ACK_OUTCOMES[number];
+/** Observed status as a no-progress monitor saw it (canonical session status or `unknown`). */
+export declare const NO_PROGRESS_OBSERVED_STATUSES: readonly ["idle", "generating", "waiting_approval", "waiting_choice", "finalizing", "error", "stopped", "starting", "panel_hidden", "not_monitored", "disconnected", "unknown"];
+export type NoProgressObservedStatus = SessionStatus | 'unknown';
+/**
+ * Reasons a turn hold exists. Holds are attempt-scoped only (C2: delivery-side
+ * waits are consumer deferral on the `turn.deliver` cursor, not hold rows).
+ */
+export declare const HOLD_REASONS: readonly ["await_delivery", "await_consume", "await_turn", "liveness", "hard_ceiling", "live_pending", "transcript_quiet", "weak_candidate", "suspension_before_consumed", "await_report"];
+export type HoldReason = typeof HOLD_REASONS[number];
+export declare const TURN_OUTCOMES: readonly ["completed", "failed", "cancelled"];
+export type TurnOutcome = typeof TURN_OUTCOMES[number];
+export declare const COMMIT_STRENGTHS: readonly ["genuine", "weak", "tool_report", "operator"];
+export type CommitStrength = typeof COMMIT_STRENGTHS[number];
+/** Every terminal or reclaim reason the ledger writes. Closed: no free-text reasons. */
+export declare const TURN_REASONS: readonly ["turn_end", "weak_end_confirmed", "transcript_final", "worker_reported", "finalization_timeout_no_response", "session_error", "provider_auth_failed", "provider_billing_failed", "operator_cancel", "intentional_cleanup", "task_removed", "mission_abandoned", "superseded", "operator_update", "refine_terminal", "validation_terminal", "hard_ceiling", "reclaim_budget_exhausted", "hollow_max_retries", "migration_orphan", "dispatch_refused_session_exited", "dispatch_refused_no_target", "dispatch_refused_unsupported_input", "dispatch_failed", "session_exit", "session_exit_before_turn", "session_dead", "hollow_completion", "assigned_stranded_dispatch_unconfirmed", "delivered_not_consumed_redrive", "delivered_no_turn_deadline"];
+export type TurnReason = typeof TURN_REASONS[number];
+/**
+ * What a `turn.notify` entry tells a coordinator.
+ *
+ * `late_completion` (C1 R27, owner revision 2026-09-23): a superseded
+ * generation finished while the current one was already running; the
+ * coordinator decides whether to salvage it (the entry carries the g−1
+ * summary as its append `ref`). `mesh_event`: a non-turn coordinator notice
+ * (refine terminal, worktree bootstrap, …) whose text lives only in the
+ * owner's local `turn_events.payload_json` and is rendered at deliver time.
+ */
+export declare const NOTIFY_KINDS: readonly ["completed", "failed", "cancelled", "stopped", "approval", "choice", "approval_resolved", "candidate", "no_progress", "progress", "late_completion", "mesh_event"];
+export type NotifyKind = typeof NOTIFY_KINDS[number];
+export interface TurnAttemptRef {
+    attemptId: string;
+    generation: number;
+}
+/**
+ * Pointer to text that lives in a content-class topic entry (`mesh.<id>.handoff`).
+ * Text never travels inside evidence; the deliver side renders it from the ref.
+ */
+export interface SummaryRef {
+    topic: string;
+    writer: string;
+    seq: number;
+}
+/** Live-state observations that make a transcript end premature (admission input). */
+export interface LiveTurnPending {
+    modal: boolean;
+    adapterPending: boolean;
+    trailingTool: boolean;
+    newestActivityAt?: number;
+}
+/** Structural copy of daemon-core's `CoordinatorIdentity` (this package cannot import daemon-core). */
+export interface EvidenceCoordinatorIdentity {
+    daemonId: string;
+    coordinatorRunId: string;
+    sessionId?: string;
+}
+export interface NativeTurnMarkerRef {
+    outcome: NativeTurnOutcome;
+    turnId?: string;
+}
+export interface EvidenceEnvelope {
+    /** Stable id of this observation; dedupe key across republish/replication. */
+    eventId: string;
+    /** Producer clock, epoch ms. */
+    at: number;
+    source: EvidenceSourceId;
+    /** The session that produced / is the subject of the observation. */
+    sessionId: string;
+    attemptRef?: TurnAttemptRef;
+    /** Only when attemptRef is absent (legacy relay / MCP probe). */
+    taskId?: string;
+    /** Daemon id that observed it. */
+    observedBy: string;
+}
+/** Kind-specific bodies. `TurnEvidence = EvidenceEnvelope & TurnEvidenceBody`. */
+export type TurnEvidenceBody = {
+    kind: 'dispatch_accepted';
+    scope: TurnScope;
+    messageId: string;
+    meshId?: string;
+    nodeId?: string;
+    providerType?: string;
+    attemptNo?: number;
+    dispatchNonce?: number;
+    consumeProfile?: ConsumeProfile;
+    maxTaskRetries?: number;
+    coordinator?: EvidenceCoordinatorIdentity;
+} | {
+    kind: 'delivered';
+    messageId: string;
+    outcome: DeliveryOutcome;
+    via: DeliveryVia;
+} | {
+    kind: 'delivery_refused';
+    messageId: string;
+    reason: SendRefusal;
+} | {
+    kind: 'dispatch_failed';
+    workerAbsent: boolean;
+    reason: DispatchFailureReason;
+} | {
+    kind: 'duplicate_dispatch_refusal';
+    holderSessionId: string;
+    holderAttemptId?: string;
+} | {
+    kind: 'session_rebound';
+    toSessionId: string;
+    reason: SessionReboundReason;
+} | {
+    kind: 'turn_started';
+    retro: boolean;
+} | {
+    kind: 'suspension';
+    modal: SuspensionModal;
+    modalKey?: string;
+} | {
+    kind: 'suspension_resolved';
+    resolution: SuspensionResolution;
+    via: SuspensionResolutionVia;
+} | {
+    kind: 'turn_end';
+    strength: TurnEndStrength;
+    afterFinalizationTimeout?: boolean;
+    hollow?: boolean;
+    summary?: SummaryRef;
+    blockReason?: TurnEndBlockReason;
+    releasedByHardCap?: boolean;
+    nativeOutcome?: NativeTurnOutcome;
+    live?: LiveTurnPending;
+    /**
+     * Stamped (true only) by the WORKER's daemon when the session holds a live
+     * worker-MCP session bind, i.e. the worker can call report_completion. The
+     * owner then treats a genuine end as a report-awaiting candidate (R9r), not
+     * a commit. Absent = no reporting surface = today's genuine-end commit.
+     */
+    reportExpected?: boolean;
+} | {
+    kind: 'transcript_final';
+    selfAttributing: boolean;
+    nativeRead: boolean;
+    nativeMarker?: NativeTurnMarkerRef;
+    live: LiveTurnPending;
+    summary?: SummaryRef;
+    messageAt?: number;
+} | {
+    kind: 'transcript_activity';
+    newestActivityAt: number;
+} | {
+    kind: 'no_progress';
+    stalledMs: number;
+    observedStatus: NoProgressObservedStatus;
+    finalAssistantPresent: boolean;
+} | {
+    kind: 'liveness';
+    result: LivenessResult;
+} | {
+    kind: 'process_exit';
+    exitCode: number | null;
+    providerFailure?: ProviderFailure;
+} | {
+    kind: 'session_error';
+    reason: SessionErrorReason;
+} | {
+    kind: 'worker_report';
+    outcome: WorkerReportOutcome;
+    summary: SummaryRef;
+    hasHandoffNotes: boolean;
+    branchState?: WorkerBranchState;
+    touchedFileCount?: number;
+} | {
+    kind: 'worker_progress';
+    note?: SummaryRef;
+} | {
+    kind: 'git_side_effect';
+    dirty: boolean;
+    commitsSinceDispatch: number;
+    attributable: boolean;
+} | {
+    kind: 'cancel';
+    reason: CancelReason;
+} | {
+    kind: 'operator_status';
+    status: OperatorStatus;
+    reason: OperatorStatusReason;
+} | {
+    kind: 'coordinator_ack';
+    notify: NotifyKind;
+    outcome: CoordinatorAckOutcome;
+} | {
+    kind: 'hold_expired';
+    holdId: string;
+    reason: HoldReason;
+};
+export type TurnEvidence = EvidenceEnvelope & TurnEvidenceBody;
+export type TurnEvidenceKind = TurnEvidenceBody['kind'];
+export type TurnEvidenceOf<K extends TurnEvidenceKind> = EvidenceEnvelope & Extract<TurnEvidenceBody, {
+    kind: K;
+}>;
+/**
+ * The class of every declared field. There is deliberately NO free-text class:
+ * `id` strings are length-bounded and whitespace-free, so prose cannot be
+ * smuggled through an identifier slot either.
+ */
+export type EvidenceFieldSpec = {
+    t: 'id';
+    optional?: true;
+} | {
+    t: 'enum';
+    values: readonly string[];
+    optional?: true;
+} | {
+    t: 'bool';
+    optional?: true;
+} | {
+    t: 'int';
+    optional?: true;
+    nullable?: true;
+} | {
+    t: 'ms';
+    optional?: true;
+} | {
+    t: 'summary_ref';
+    optional?: true;
+} | {
+    t: 'attempt_ref';
+    optional?: true;
+} | {
+    t: 'live';
+    optional?: true;
+} | {
+    t: 'native_marker';
+    optional?: true;
+} | {
+    t: 'coordinator';
+    optional?: true;
+};
+type FieldsOf<K extends TurnEvidenceKind> = Exclude<keyof Extract<TurnEvidenceBody, {
+    kind: K;
+}>, 'kind'>;
+/** Exact per-kind registry: a missing or extra field fails to compile. */
+export type TurnEvidenceFieldSpecs = {
+    readonly [K in TurnEvidenceKind]: {
+        readonly [F in FieldsOf<K>]-?: EvidenceFieldSpec;
+    };
+};
+export declare const EVIDENCE_ENVELOPE_FIELD_SPECS: {
+    readonly [F in keyof EvidenceEnvelope]-?: EvidenceFieldSpec;
+};
+export declare const TURN_EVIDENCE_FIELD_SPECS: TurnEvidenceFieldSpecs;
+export declare const TURN_EVIDENCE_KINDS: readonly TurnEvidenceKind[];
+/** Evidence kinds that, on their own, can end a turn (the ones R18/R19/R27 reason about). */
+export declare const TERMINAL_CLASS_EVIDENCE_KINDS: readonly ["turn_end", "transcript_final", "no_progress", "worker_report", "session_error", "process_exit", "cancel", "operator_status"];
+export declare const isEvidenceSourceId: (value: unknown) => value is "fsm_edge" | "short_gen_inline" | "completion_flush_genuine" | "completion_flush_weak" | "monitor_final_summary" | "pre_cleanup_transcript" | "stall_transcript" | "startup_grace_collapse" | "acp_prompt_response" | "cdp_state" | "approval_gate" | "modal_button" | "mesh_stall_watchdog" | "status_monitor" | "pty_exit" | "provider_error" | "coordinator_probe" | "mcp_probe" | "worker_tool" | "dispatch" | "input_service" | "operator" | "intentional_cleanup" | "scheduler" | "git_probe" | "session_registry";
+export declare const isTurnEvidenceKind: (value: unknown) => value is "no_progress" | "delivered" | "liveness" | "turn_end" | "transcript_final" | "session_error" | "dispatch_failed" | "dispatch_accepted" | "delivery_refused" | "duplicate_dispatch_refusal" | "session_rebound" | "turn_started" | "suspension" | "suspension_resolved" | "transcript_activity" | "process_exit" | "worker_report" | "worker_progress" | "git_side_effect" | "cancel" | "operator_status" | "coordinator_ack" | "hold_expired";
+export declare const isTurnReason: (value: unknown) => value is "intentional_cleanup" | "operator_cancel" | "task_removed" | "mission_abandoned" | "superseded" | "operator_update" | "refine_terminal" | "validation_terminal" | "hard_ceiling" | "turn_end" | "weak_end_confirmed" | "transcript_final" | "worker_reported" | "finalization_timeout_no_response" | "session_error" | "provider_auth_failed" | "provider_billing_failed" | "reclaim_budget_exhausted" | "hollow_max_retries" | "migration_orphan" | "dispatch_refused_session_exited" | "dispatch_refused_no_target" | "dispatch_refused_unsupported_input" | "dispatch_failed" | "session_exit" | "session_exit_before_turn" | "session_dead" | "hollow_completion" | "assigned_stranded_dispatch_unconfirmed" | "delivered_not_consumed_redrive" | "delivered_no_turn_deadline";
+export declare const isNotifyKind: (value: unknown) => value is "stopped" | "failed" | "no_progress" | "completed" | "cancelled" | "approval" | "choice" | "approval_resolved" | "candidate" | "progress" | "late_completion" | "mesh_event";
+export declare const isHoldReason: (value: unknown) => value is "await_delivery" | "await_consume" | "await_turn" | "liveness" | "hard_ceiling" | "live_pending" | "transcript_quiet" | "weak_candidate" | "suspension_before_consumed" | "await_report";
+export declare const isTurnOutcome: (value: unknown) => value is "failed" | "completed" | "cancelled";
+export declare const isCommitStrength: (value: unknown) => value is "operator" | "genuine" | "weak" | "tool_report";
+export declare function isEvidenceIdentifier(value: unknown): value is string;
+export declare function isSummaryRef(value: unknown): value is SummaryRef;
+export declare function isTurnAttemptRef(value: unknown): value is TurnAttemptRef;
+/**
+ * Strict structural guard: known kind, every declared field of the right class,
+ * and NO undeclared field (an unknown key is how free text would sneak in).
+ */
+export declare function isTurnEvidence(value: unknown): value is TurnEvidence;
+export declare function isTerminalClassEvidenceKind(kind: TurnEvidenceKind): kind is typeof TERMINAL_CLASS_EVIDENCE_KINDS[number];
+export declare const TURN_EVIDENCE_FLAGS: readonly ["hollow", "afterFinalizationTimeout", "nativeMarker", "selfAttributing"];
+export type TurnEvidenceFlag = typeof TURN_EVIDENCE_FLAGS[number];
+/** Scalar-only payload for `mesh.record` (the existing allow-list projection's output). */
+export type ProjectedScalars = Readonly<Record<string, string | number | boolean | null>>;
+export declare const MESH_TOPIC_ENTRY_KINDS: readonly ["turn.evidence", "turn.committed", "turn.notify", "mesh.record"];
+export type MeshTopicEntryKind = typeof MESH_TOPIC_ENTRY_KINDS[number];
+export type MeshTopicEntry = {
+    v: typeof MESH_TOPIC_PROTOCOL_VERSION;
+    eventId: string;
+    at: number;
+} & ({
+    k: 'turn.evidence';
+    attemptId: string;
+    generation: number;
+    ownerDaemonId: string;
+    taskId?: string;
+    sessionId: string;
+    ev: TurnEvidenceKind;
+    strength?: TurnEndStrength;
+    flags?: Partial<Record<TurnEvidenceFlag, boolean>>;
+    /** The full (content-free) evidence, so a foreign `turn.ingest` can re-observe it losslessly. */
+    evidence?: TurnEvidence;
+} | {
+    k: 'turn.committed';
+    attemptId: string;
+    generation: number;
+    taskId?: string;
+    outcome: TurnOutcome;
+    strength: CommitStrength;
+    reason: TurnReason;
+} | {
+    k: 'turn.notify';
+    attemptId?: string;
+    notify: NotifyKind;
+    targetDaemonId: string;
+    targetSessionId?: string;
+    taskId?: string;
+} | {
+    k: 'mesh.record';
+    ledgerKind: string;
+    nodeId?: string;
+    sessionId?: string;
+    taskId?: string;
+    payload: ProjectedScalars;
+});
+export declare const isMeshTopicEntryKind: (value: unknown) => value is "turn.evidence" | "turn.committed" | "turn.notify" | "mesh.record";
+export declare function isMeshTopicEntry(value: unknown): value is MeshTopicEntry;
+/**
+ * Project evidence onto its `turn.evidence` topic entry. Pure; the attempt
+ * identity comes from the resolved attempt (the evidence may lack attemptRef).
+ */
+export declare function projectTurnEvidenceEntry(evidence: TurnEvidence, attempt: {
+    attemptId: string;
+    generation: number;
+    ownerDaemonId: string;
+}): Extract<MeshTopicEntry, {
+    k: 'turn.evidence';
+}>;
+export {};