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

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;