@adhdev/mesh-shared 1.0.60-rc.72 → 1.0.60-rc.74

package/dist/turn-ipc-queue.d.ts

@@ -0,0 +1,196 @@
+/**
+ * turn-ipc — local records, queue composites and active work (C-W9a):
+ * record_local, queue_query, queue_enqueue, queue_enqueue_batch, queue_cancel,
+ * queue_requeue, direct_dispatch_record, active_work_query,
+ * recovery_context_query. Part of the turn-ipc wire contract (./turn-ipc.ts).
+ */
+import { TURN_IPC_PROTOCOL_VERSION } from './turn-ipc-guards';
+/** A queue row as the daemon's `getQueue` returns it — a JSON passthrough (see the section note). */
+export type QueueEntryWire = Record<string, unknown> & {
+    id: string;
+    status: string;
+};
+export interface RecordLocalRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** A `MeshLedgerKind` (daemon-core); an identifier here (mesh-shared cannot import that union). */
+    kind: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskId?: string;
+    payload: Record<string, unknown>;
+}
+export interface RecordLocalResponse {
+    eventId: string;
+    timestamp: string;
+    storedLocally: boolean;
+    published: boolean;
+}
+export declare function decodeRecordLocalRequest(value: unknown): RecordLocalRequest | null;
+export declare function decodeRecordLocalResponse(value: unknown): RecordLocalResponse | null;
+export interface QueueQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** Status filter (queue statuses); omitted = every row. */
+    statuses?: readonly string[];
+    /** One row by id (returns 0 or 1 entries). */
+    taskId?: string;
+    /** Project for a VIEW surface: the persisted input envelope → `inputSummary` (summarizeQueueEntryInputForView). */
+    view?: boolean;
+    /**
+     * Also return the per-status row counts of the WHOLE mesh queue (columns only,
+     * no payload parse) — lets a view read only the rows it shows yet report
+     * mesh-wide counts. An older daemon rejects the key.
+     */
+    withCounts?: boolean;
+    /** With `withCounts`: also count terminal rows whose `updated_at` is older than this age. */
+    historicalOlderThanMs?: number;
+    /**
+     * Also return `dependencyHeads`: id/status/cancelReason of every
+     * row the returned entries list in `dependsOn` that is not itself returned —
+     * enough to annotate dependency state without reading the whole queue.
+     */
+    withDependencyHeads?: boolean;
+}
+/** A dependency row reduced to the fields dependency-state annotation reads. */
+export interface QueueDependencyHeadWire {
+    id: string;
+    status: string;
+    cancelReason?: string;
+}
+export interface QueueQueryResponse {
+    entries: readonly QueueEntryWire[];
+    /** `withCounts`: row count per status over the whole mesh queue. */
+    counts?: Record<string, number>;
+    /** `withCounts` + `historicalOlderThanMs`: terminal rows older than that age. */
+    oldHistoricalCount?: number;
+    /** `withDependencyHeads`. */
+    dependencyHeads?: readonly QueueDependencyHeadWire[];
+}
+export declare function decodeQueueQueryRequest(value: unknown): QueueQueryRequest | null;
+export declare function decodeQueueQueryResponse(value: unknown): QueueQueryResponse | null;
+export interface QueueEnqueueRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** Free text (the task message — see the section note). */
+    message: string;
+    options?: Record<string, unknown>;
+}
+export interface QueueEnqueueResponse {
+    entry: QueueEntryWire;
+}
+export declare function decodeQueueEnqueueRequest(value: unknown): QueueEnqueueRequest | null;
+export declare function decodeQueueEnqueueResponse(value: unknown): QueueEnqueueResponse | null;
+export interface QueueEnqueueBatchRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** `MeshTaskBatchEntrySpec[]` (daemon-core, JSON passthrough). */
+    specs: readonly Record<string, unknown>[];
+}
+export type QueueEnqueueBatchResponse = {
+    ok: true;
+    tasks: readonly QueueEntryWire[];
+} | {
+    ok: false;
+    refusalCode?: string;
+    message: string;
+    extra?: Record<string, unknown>;
+};
+export declare function decodeQueueEnqueueBatchRequest(value: unknown): QueueEnqueueBatchRequest | null;
+export declare function decodeQueueEnqueueBatchResponse(value: unknown): QueueEnqueueBatchResponse | null;
+export interface QueueCancelRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    taskId: string;
+    /** Operator reason (free text, local IPC). */
+    reason?: string;
+}
+export interface QueueCancelResponse {
+    /** The cancelled row, or null when no such task. */
+    task: QueueEntryWire | null;
+    /** The row as it was BEFORE the cancel (its assignment is what a caller stops). */
+    before: QueueEntryWire | null;
+}
+export declare function decodeQueueCancelRequest(value: unknown): QueueCancelRequest | null;
+export declare function decodeQueueCancelResponse(value: unknown): QueueCancelResponse | null;
+export interface QueueRequeueRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    taskId: string;
+    /** `requeueTask` options (reason / targetNodeId / targetSessionId / clear* / force / message / maxRetries / notBefore), JSON passthrough. */
+    options?: Record<string, unknown>;
+}
+export interface QueueRequeueResponse {
+    task: QueueEntryWire | null;
+}
+export declare function decodeQueueRequeueRequest(value: unknown): QueueRequeueRequest | null;
+export declare function decodeQueueRequeueResponse(value: unknown): QueueRequeueResponse | null;
+export interface DirectDispatchRecordRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    taskId: string;
+    /** Free text (the authored task message — the materialised row keeps it). */
+    message: string;
+    /** `recordDirectDispatchTask` options minus `id` (JSON passthrough). */
+    task?: Record<string, unknown>;
+}
+export interface DirectDispatchRecordResponse {
+    taskRecorded: boolean;
+}
+export declare function decodeDirectDispatchRecordRequest(value: unknown): DirectDispatchRecordRequest | null;
+export declare function decodeDirectDispatchRecordResponse(value: unknown): DirectDispatchRecordResponse | null;
+export interface ActiveWorkQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** Live node probe results (`buildMeshActiveWork`'s `nodes`), JSON passthrough. */
+    nodes?: readonly Record<string, unknown>[];
+    /** Substitute queue rows (default: the daemon's `getQueue`). */
+    queue?: readonly Record<string, unknown>[];
+    /** Record tail fed to active work (default 200). */
+    recordTail?: number;
+    includeTerminalDirect?: boolean;
+    /** Default true. */
+    compute?: boolean;
+    includeInputs?: boolean;
+    includeSummary?: boolean;
+    includeSchedulingRuntime?: boolean;
+    /**
+     * The caller's mesh snapshot for the scheduling runtime, JSON passthrough.
+     * Optional since the daemon resolves its own mesh record when it is absent;
+     * an older daemon rejects `includeSchedulingRuntime` without it (the caller's
+     * feature-detect signal to resend with the mesh).
+     */
+    mesh?: Record<string, unknown>;
+}
+export interface ActiveWorkQueryResponse {
+    /** `MeshActiveWorkEvidence` (daemon-core), JSON passthrough; absent when `compute: false`. */
+    activeWork?: Record<string, unknown>;
+    records?: readonly Record<string, unknown>[];
+    directDispatches?: readonly Record<string, unknown>[];
+    /** `MeshLedgerSummary`-shaped record summary. */
+    summary?: Record<string, unknown>;
+    schedulingRuntime?: Record<string, unknown>;
+}
+export declare function decodeActiveWorkQueryRequest(value: unknown): ActiveWorkQueryRequest | null;
+export declare function decodeActiveWorkQueryResponse(value: unknown): ActiveWorkQueryResponse | null;
+export interface RecoveryContextQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    nodeId?: string;
+    sessionId?: string;
+    maxRetries?: number;
+    /**
+     * Batch: one context per node id, computed over ONE record read (answers
+     * `contexts`). Exclusive with `nodeId`/`sessionId`. An older daemon rejects it.
+     */
+    nodeIds?: readonly string[];
+}
+export interface RecoveryContextQueryResponse {
+    /** Single mode (nodeId/sessionId). */
+    context?: Record<string, unknown>;
+    /** Batch mode (`nodeIds`): context per node id. */
+    contexts?: Record<string, Record<string, unknown>>;
+}
+export declare function decodeRecoveryContextQueryRequest(value: unknown): RecoveryContextQueryRequest | null;
+export declare function decodeRecoveryContextQueryResponse(value: unknown): RecoveryContextQueryResponse | null;

package/dist/turn-ipc-stats.d.ts

@@ -0,0 +1,72 @@
+/**
+ * turn-ipc — task stats and maintenance commands: task_stats_query,
+ * prune_stale_direct, orphaned_pin_notify. Part of the turn-ipc wire contract
+ * (./turn-ipc.ts).
+ */
+import { TURN_IPC_PROTOCOL_VERSION } from './turn-ipc-guards';
+export interface TaskStatsQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    taskIds?: readonly string[];
+    missionId?: string;
+    tail?: number;
+    /** Also compute `computeMeshMissionStats` — requires `missionId`. */
+    rollup?: boolean;
+    /**
+     * Batch rollups: `computeMeshMissionStats` for every id, over ONE queue read and
+     * ONE record read (answers `missions`, `tasks` empty). Exclusive with
+     * `taskIds`/`missionId`. An older daemon rejects the key.
+     */
+    missionIds?: readonly string[];
+}
+export interface TaskStatsQueryResponse {
+    /** `MeshTaskStats[]`, JSON passthrough. */
+    tasks: readonly Record<string, unknown>[];
+    /** `MeshMissionStats`, JSON passthrough; present only when `rollup: true` was requested and satisfiable. */
+    mission?: Record<string, unknown>;
+    /** Batch mode: `MeshMissionStats` per requested mission id, JSON passthrough. */
+    missions?: Record<string, Record<string, unknown>>;
+}
+export declare function decodeTaskStatsQueryRequest(value: unknown): TaskStatsQueryRequest | null;
+export declare function decodeTaskStatsQueryResponse(value: unknown): TaskStatsQueryResponse | null;
+export interface PruneStaleDirectRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    execute?: boolean;
+    includeTerminal?: boolean;
+    source?: string;
+}
+export interface PruneStaleDirectResponse {
+    mode: 'execute' | 'dry_run';
+    includeTerminal: boolean;
+    candidateCount: number;
+    /** `MeshActiveWorkRecord[]`, JSON passthrough. */
+    prunable: readonly Record<string, unknown>[];
+    prunedCount: number;
+    preservedUnacknowledged: readonly Record<string, unknown>[];
+    preservedLedgerOnly: readonly Record<string, unknown>[];
+    preservedNotOrphan: readonly Record<string, unknown>[];
+}
+export declare function decodePruneStaleDirectRequest(value: unknown): PruneStaleDirectRequest | null;
+export declare function decodePruneStaleDirectResponse(value: unknown): PruneStaleDirectResponse | null;
+export interface OrphanedPinNotifyRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    stoppedSessionId: string;
+    excludeTaskId?: string;
+    cause?: string;
+    nodeId?: string;
+    coordinatorSessionId?: string;
+}
+export interface OrphanedPinnedTaskWire {
+    taskId: string;
+    title: string;
+    targetSessionId: string;
+    targetNodeId?: string;
+    missionId?: string;
+}
+export interface OrphanedPinNotifyResponse {
+    orphans: readonly OrphanedPinnedTaskWire[];
+}
+export declare function decodeOrphanedPinNotifyRequest(value: unknown): OrphanedPinNotifyRequest | null;
+export declare function decodeOrphanedPinNotifyResponse(value: unknown): OrphanedPinNotifyResponse | null;

package/dist/turn-ipc-turn.d.ts

@@ -0,0 +1,176 @@
+/**
+ * turn-ipc — the turn-ledger commands: turn_observe, mesh_record, turn_cancel,
+ * operator_status, turn_query, mesh_index_query. Part of the turn-ipc wire
+ * contract (./turn-ipc.ts).
+ */
+import { TURN_IPC_PROTOCOL_VERSION } from './turn-ipc-guards';
+import { type TurnEvidence, type TurnAttemptRef, type TurnOutcome, type ProjectedScalars, type TurnReason, type TurnEvidenceKind } from './turn-evidence';
+/** Reducer verdict, mirrored from the C1 reducer's `reduce()` return shape. */
+export declare const TURN_OBSERVE_VERDICTS: readonly ["applied", "recorded", "rejected"];
+export type TurnObserveVerdict = typeof TURN_OBSERVE_VERDICTS[number];
+export interface TurnObserveRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    evidence: TurnEvidence;
+}
+export interface TurnObserveResponse {
+    verdict: TurnObserveVerdict;
+    attemptRef: TurnAttemptRef;
+    /** Present only when the evidence committed the attempt (verdict 'applied' + a terminal-class kind). */
+    outcome?: TurnOutcome;
+}
+export declare function decodeTurnObserveRequest(value: unknown): TurnObserveRequest | null;
+export declare function decodeTurnObserveResponse(value: unknown): TurnObserveResponse | null;
+/**
+ * Structural pin of `seqscribe/mesh-event-projection.ts` `PROJECTED_PAYLOAD_KEYS`
+ * (daemon-core; this leaf cannot import it). A test in this package's test
+ * suite AND a daemon-core test each assert their list equals this one — see
+ * `mesh-shared/test/turn-ipc.test.ts` and the C-W6 report's break-once table.
+ * Adding a key here is the SAME assertion as adding it there: non-content
+ * (identifier, enum, boolean, or counter), never free text.
+ */
+export declare const MESH_RECORD_PAYLOAD_KEYS: readonly ["taskId", "deliveryId", "attemptId", "missionId", "checkpointId", "promptId", "providerSessionId", "targetNoteId", "nodeId", "sessionId", "providerType", "transport", "attemptedSessionId", "holderSessionId", "reason", "status", "outcome", "terminalKind", "event", "source", "intentionalStopReason", "retryable", "rebound", "forced", "fallback", "membershipRemoved", "requestedForce", "removedByRemoteDaemon", "completedViaReady", "intentional", "weak", "attempt", "attemptCount", "count"];
+/** Maximum length of any string value in a `mesh_record` payload (mirrors `MAX_PROJECTED_STRING`). */
+export declare const MAX_MESH_RECORD_STRING = 200;
+export interface MeshRecordRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** The original ledger `kind` string (daemon-core `MeshLedgerKind`; mesh-shared cannot import that union, so it is an identifier here). */
+    ledgerKind: string;
+    nodeId?: string;
+    sessionId?: string;
+    taskId?: string;
+    /** Restricted to `MESH_RECORD_PAYLOAD_KEYS` — an unknown key is a decode failure, not a silently dropped field. */
+    payload: ProjectedScalars;
+}
+export interface MeshRecordResponse {
+    /** `mesh.<id>.events` append coordinates, for callers that need to reference the entry (e.g. a `ref`'d handoff). */
+    eventId: string;
+    seq: number;
+}
+/** Every payload key must be a member of `MESH_RECORD_PAYLOAD_KEYS` — the allow-list boundary at the wire. */
+export declare function isMeshRecordPayload(value: unknown): value is ProjectedScalars;
+export declare function decodeMeshRecordRequest(value: unknown): MeshRecordRequest | null;
+export declare function decodeMeshRecordResponse(value: unknown): MeshRecordResponse | null;
+export interface TurnCancelRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    /** Exactly one of the two must be present — the decoder rejects both-or-neither. */
+    attemptId?: string;
+    taskId?: string;
+    reason: TurnReason;
+}
+export interface TurnCancelResponse {
+    attemptRef: TurnAttemptRef;
+    verdict: TurnObserveVerdict;
+}
+export declare function decodeTurnCancelRequest(value: unknown): TurnCancelRequest | null;
+export declare function decodeTurnCancelResponse(value: unknown): TurnCancelResponse | null;
+/**
+ * Fire-and-forget operator/tool-call status record — replaces
+ * `recordMeshCoordinatorToolCall` (10 sites, `mesh_tool_call_log`) and doubles
+ * as the `operator_status` evidence kind's wire shape.
+ *
+ * NAMING NOTE (flagged for the C-W6 implementer, see report §"mismatch"):
+ * the C-W6 brief's DELIVERABLES describes this request as
+ * `{taskId, status: MeshTaskStatus, reason}`, but C1's `operator_status`
+ * evidence kind (`turn-evidence.ts` `OPERATOR_STATUSES`) is the closed
+ * 2-value set `'completed' | 'failed'` — a verdict on an operator ACTION, not
+ * a `MeshTaskStatus` (5-value queue-row status: pending/assigned/completed/
+ * failed/cancelled). This contract follows `turn-evidence.ts` because that is
+ * what the C1 reducer actually consumes for this evidence kind; using the
+ * 5-value `MeshTaskStatus` here would let this request carry `pending` or
+ * `assigned`, which the reducer has no transition for.
+ */
+export declare const OPERATOR_STATUS_VALUES: readonly ["completed", "failed"];
+export type OperatorStatusValue = typeof OPERATOR_STATUS_VALUES[number];
+export declare const OPERATOR_STATUS_REASON_VALUES: readonly ["operator_update", "refine_terminal", "validation_terminal"];
+export type OperatorStatusReasonValue = typeof OPERATOR_STATUS_REASON_VALUES[number];
+export interface OperatorStatusRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    taskId: string;
+    status: OperatorStatusValue;
+    reason: OperatorStatusReasonValue;
+}
+/** Acknowledgement only — this command is fire-and-forget by design (the daemon owns rate-limiting the underlying log). */
+export interface OperatorStatusResponse {
+    accepted: true;
+}
+export declare function decodeOperatorStatusRequest(value: unknown): OperatorStatusRequest | null;
+export declare function decodeOperatorStatusResponse(value: unknown): OperatorStatusResponse | null;
+/** Row shape returned by `turn_query` — scalar projection of a `turn_attempts` row (C3 schema), never `data_json`/`payload_json` content. */
+export interface TurnQueryAttemptRow {
+    attemptId: string;
+    generation: number;
+    meshId?: string;
+    taskId?: string;
+    sessionId: string;
+    nodeId?: string;
+    providerType?: string;
+    state: string;
+    terminalOutcome?: TurnOutcome;
+    terminalReason?: TurnReason;
+    acceptedAt: number;
+    terminalAt?: number;
+}
+/** Row shape returned by `turn_query` for the event stream — scalar projection of a `turn_events` row, `payload_json` NEVER included. */
+export interface TurnQueryEventRow {
+    eventId: string;
+    attemptId?: string;
+    generation?: number;
+    sessionId: string;
+    kind: TurnEvidenceKind;
+    source: string;
+    verdict: TurnObserveVerdict | 'forwarded';
+    atMs: number;
+}
+export interface TurnQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    taskId?: string;
+    attemptId?: string;
+    sessionId?: string;
+    state?: string;
+    since?: number;
+    tail?: number;
+}
+export interface TurnQueryResponse {
+    attempts: readonly TurnQueryAttemptRow[];
+    events: readonly TurnQueryEventRow[];
+    /** C7-5: set while `mesh.<id>.events` replication is behind for this mesh — the caller must not treat a fleet-scope answer as complete. */
+    replicationPending?: boolean;
+}
+export declare function decodeTurnQueryRequest(value: unknown): TurnQueryRequest | null;
+export declare function decodeTurnQueryResponse(value: unknown): TurnQueryResponse | null;
+export declare const MESH_INDEX_QUERY_WRITER_SCOPES: readonly ["own", "fleet"];
+export type MeshIndexQueryWriterScope = typeof MESH_INDEX_QUERY_WRITER_SCOPES[number];
+export interface MeshIndexQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    ledgerKind?: string;
+    sessionId?: string;
+    taskId?: string;
+    writer?: MeshIndexQueryWriterScope;
+    since?: number;
+    tail?: number;
+}
+/** Row shape returned by `mesh_index_query` — a `mesh_topic_index` row (C3 schema). */
+export interface MeshTopicIndexRow {
+    writer: string;
+    seq: number;
+    meshId: string;
+    eventId: string;
+    kind: string;
+    ledgerKind?: string;
+    taskId?: string;
+    sessionId?: string;
+    nodeId?: string;
+    atMs: number;
+    payload: ProjectedScalars;
+}
+export interface MeshIndexQueryResponse {
+    rows: readonly MeshTopicIndexRow[];
+    /** C7-5: true while `mesh.<id>.events` replication is behind for this mesh. */
+    replicationPending?: boolean;
+}
+export declare function decodeMeshIndexQueryRequest(value: unknown): MeshIndexQueryRequest | null;
+export declare function isMeshIndexQueryResponse(value: unknown): value is MeshIndexQueryResponse;
+export declare function decodeMeshIndexQueryResponse(value: unknown): MeshIndexQueryResponse | null;