omk-adaptorch-wpl 0.91.0

package/dist/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../src/state-machine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;GAIG;AACH,MAAM,WAAW,GAA+C;IAC/D,OAAO,EAAE,CAAC,QAAQ,CAAC;IACnB,MAAM,EAAE,CAAC,mBAAmB,EAAE,YAAY,CAAC;IAC3C,iBAAiB,EAAE,CAAC,YAAY,EAAE,QAAQ,CAAC;IAC3C,UAAU,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,QAAQ,CAAC;IAChD,MAAM,EAAE,CAAC,cAAc,EAAE,SAAS,EAAE,QAAQ,CAAC;IAC7C,OAAO,EAAE,CAAC,cAAc,EAAE,QAAQ,CAAC;IACnC,YAAY,EAAE,CAAC,cAAc,EAAE,qBAAqB,CAAC;IACrD,YAAY,EAAE,CAAC,qBAAqB,EAAE,WAAW,EAAE,UAAU,CAAC;IAC9D,mBAAmB,EAAE,CAAC,cAAc,EAAE,WAAW,CAAC;IAClD,SAAS,EAAE,CAAC,QAAQ,CAAC;IACrB,QAAQ,EAAE,CAAC,WAAW,EAAE,cAAc,EAAE,QAAQ,CAAC;IACjD,YAAY,EAAE,CAAC,QAAQ,CAAC;IACxB,SAAS,EAAE,CAAC,cAAc,EAAE,QAAQ,CAAC;IACrC,MAAM,EAAE,EAAE;CACV,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAqB,EAAE,EAAmB,EAAW;IAClF,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAAA,CACtC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC9B,MAAkB,EAClB,EAAmB,EACnB,KAAa,EACb,GAAG,GAAiB,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EACrC;IACb,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACd,mCAAmC,MAAM,CAAC,KAAK,OAAO,EAAE,eAAe,MAAM,CAAC,SAAS,YAAY,KAAK,GAAG,CAC3G,CAAC;IACH,CAAC;IACD,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC;IACjB,OAAO;QACN,GAAG,MAAM;QACT,KAAK,EAAE,EAAE;QACT,cAAc,EAAE,CAAC,GAAG,MAAM,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;KACjF,CAAC;AAAA,CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAsB,EAAW;IAChE,OAAO,KAAK,KAAK,QAAQ,CAAC;AAAA,CAC1B;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACpC,MAAkB,EAClB,UAAmB,EACnB,WAA0C,EAC1C,UAAsB,EACZ;IACV,IAAI,UAAU,CAAC,kBAAkB,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC;IACd,CAAC;IAED,sFAAsF;IACtF,0FAA0F;IAC1F,qFAAqF;IACrF,0FAA0F;IAC1F,sFAAsF;IACtF,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,2BAA2B,CAAC,CAAC;IAEzG,MAAM,eAAe,GACpB,WAAW,KAAK,IAAI;QACpB,MAAM,CAAC,iBAAiB,KAAK,IAAI;QACjC,WAAW,KAAK,MAAM,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAEzD,OAAO,cAAc,IAAI,eAAe,CAAC;AAAA,CACzC","sourcesContent":["/**\n * Design-fidelity note: this file implements the packet-level state machine defined in\n * Part 1 (`final-part1-core-algorithm.md`), Section 2 (transition table), Section 4 (terminal\n * state, since only CLOSED is terminal per §2's own text), and Section 2 state 3\n * (AWAITING_APPROVAL's trigger condition). It is an implementation of that document, not a\n * restatement of it.\n */\n\nimport type { LoopConfig, TopologyClassification, WorkPacket, WorkPacketState } from \"./types.ts\";\n\n/**\n * Part 1 §2 — the full transition table, as an adjacency map keyed by source state. This is\n * the single source of truth for which transitions are legal; every other state-machine\n * function in this file is built on top of `canTransition`.\n */\nconst TRANSITIONS: Record<WorkPacketState, WorkPacketState[]> = {\n\tDRAFTED: [\"ROUTED\"],\n\tROUTED: [\"AWAITING_APPROVAL\", \"DISPATCHED\"],\n\tAWAITING_APPROVAL: [\"DISPATCHED\", \"CLOSED\"],\n\tDISPATCHED: [\"ACTIVE\", \"RAW_TERMINAL\", \"CLOSED\"],\n\tACTIVE: [\"RAW_TERMINAL\", \"HALTING\", \"CLOSED\"],\n\tHALTING: [\"RAW_TERMINAL\", \"CLOSED\"],\n\tRAW_TERMINAL: [\"UNDER_REVIEW\", \"ADJUDICATION_FAILED\"],\n\tUNDER_REVIEW: [\"ADJUDICATION_FAILED\", \"CONFIRMED\", \"DECLINED\"],\n\tADJUDICATION_FAILED: [\"UNDER_REVIEW\", \"ESCALATED\"],\n\tCONFIRMED: [\"CLOSED\"],\n\tDECLINED: [\"ESCALATED\", \"RETRY_QUEUED\", \"CLOSED\"],\n\tRETRY_QUEUED: [\"ROUTED\"],\n\tESCALATED: [\"RETRY_QUEUED\", \"CLOSED\"],\n\tCLOSED: [],\n};\n\n/**\n * Part 1 §2 — returns whether `from -> to` is a legal Work Packet state transition, per the\n * transition table. Pure and side-effect free.\n */\nexport function canTransition(from: WorkPacketState, to: WorkPacketState): boolean {\n\treturn TRANSITIONS[from].includes(to);\n}\n\n/**\n * Part 1 §2 / §7 — applies a state transition to a Work Packet, returning a new packet object\n * with `state` updated and a new `TransitionLogEntry` appended to `transition_log`. Throws if\n * the transition is not legal per `canTransition`. Does not mutate `packet`.\n *\n * `now` defaults to the wall-clock ISO timestamp but is accepted as a parameter so callers\n * (and tests) can supply a deterministic clock.\n */\nexport function applyTransition(\n\tpacket: WorkPacket,\n\tto: WorkPacketState,\n\tcause: string,\n\tnow: () => string = () => new Date().toISOString(),\n): WorkPacket {\n\tif (!canTransition(packet.state, to)) {\n\t\tthrow new Error(\n\t\t\t`Illegal work packet transition: ${packet.state} -> ${to} for packet ${packet.packet_id} (cause: ${cause})`,\n\t\t);\n\t}\n\tconst at = now();\n\treturn {\n\t\t...packet,\n\t\tstate: to,\n\t\ttransition_log: [...packet.transition_log, { from: packet.state, to, at, cause }],\n\t};\n}\n\n/**\n * Part 1 §2 state 14 / §4 \"Completion exhaustion\" — CLOSED is the only terminal state.\n * ESCALATED and RETRY_QUEUED are explicitly not terminal: both can still transition further\n * (ESCALATED via an explicit external unblock signal; RETRY_QUEUED back into ROUTED).\n */\nexport function isTerminalState(state: WorkPacketState): boolean {\n\treturn state === \"CLOSED\";\n}\n\n/**\n * Part 1 §2 state 3 — whether the next attempt for `packet` must be held in\n * AWAITING_APPROVAL before its first `adaptorch_run` call, rather than going straight from\n * ROUTED to DISPATCHED.\n *\n * True only if the proposed payload differs from the packet's last-human-approved baseline,\n * or the proposed topology classification differs from the packet's currently stored topology\n * decision — unless the loop instance is running in pre-approved-batch mode (§2 state 3's\n * documented opt-in escape hatch), in which case this always returns false.\n */\nexport function requiresHumanApproval(\n\tpacket: WorkPacket,\n\tnewPayload: unknown,\n\tnewTopology: TopologyClassification | null,\n\tloopConfig: LoopConfig,\n): boolean {\n\tif (loopConfig.pre_approved_batch) {\n\t\treturn false;\n\t}\n\n\t// Pragmatic choice, not a claim of full structural equality semantics: JSON.stringify\n\t// comparison is order-sensitive for object keys and does not handle non-JSON-serializable\n\t// values (e.g. undefined, functions, symbols) specially. Adequate for the plain task\n\t// payloads this design assumes; a caller with payloads that need true structural equality\n\t// should compare upstream and pass an already-decided `newPayload` reference instead.\n\tconst payloadChanged = JSON.stringify(newPayload) !== JSON.stringify(packet.last_human_approved_payload);\n\n\tconst topologyChanged =\n\t\tnewTopology !== null &&\n\t\tpacket.topology_decision !== null &&\n\t\tnewTopology !== packet.topology_decision.classification;\n\n\treturn payloadChanged || topologyChanged;\n}\n"]}

package/dist/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Design-fidelity note: this file implements the Work Packet on-disk schema and supporting
+ * type vocabulary defined in Part 1 (`final-part1-core-algorithm.md`), Sections 1, 2, 3, 4,
+ * and 7. It is an implementation of that document, not a restatement of it — see the design
+ * doc for rationale, transition semantics, and the open questions left for other lanes.
+ */
+/**
+ * Work Packet lifecycle states.
+ *
+ * Part 1 §2 — the fourteen states of the packet-level state machine, including the
+ * ESCALATED / AWAITING_APPROVAL / ADJUDICATION_FAILED additions from this revision.
+ */
+export type WorkPacketState = "DRAFTED" | "ROUTED" | "AWAITING_APPROVAL" | "DISPATCHED" | "ACTIVE" | "HALTING" | "RAW_TERMINAL" | "UNDER_REVIEW" | "ADJUDICATION_FAILED" | "CONFIRMED" | "DECLINED" | "RETRY_QUEUED" | "ESCALATED" | "CLOSED";
+/**
+ * Part 1 §3.3 — whether a Dispatch Record's run_id set was produced by a single
+ * `adaptorch_run` call (`single_call`) or by N calls the loop itself issued (`fanout_n`).
+ * This tag is what lets the rest of the state machine stay agnostic to the Section 3.2
+ * single-call-vs-client-side-fanout ambiguity.
+ */
+export type CardinalityMode = "single_call" | "fanout_n";
+/**
+ * Part 1 §3.1 — the four topology classes `adaptorch_route_topology` can return for a
+ * packet's payload, decided once per packet before any `adaptorch_run` call.
+ */
+export type TopologyClassification = "singleton" | "pipeline" | "dag" | "ensemble";
+/**
+ * Part 1 §3.3 / §7 — one concrete submission attempt for a Work Packet. A Dispatch Record
+ * holds a run_id *set* (not a single run_id) tagged with its cardinality mode, so polling,
+ * cancellation, and review packaging work the same way regardless of which Section 3.2
+ * reading turns out to be correct.
+ */
+export interface DispatchRecord {
+    attempt_n: number;
+    cardinality_mode: CardinalityMode;
+    run_ids: string[];
+    submitted_at: string;
+    mode: "blocking" | "polling";
+    terminal_status?: string;
+    terminal_at?: string;
+}
+/**
+ * Part 1 §7 — one append-only entry in a Work Packet's transition log. Recorded for every
+ * state change, including adjudication-call failures that have no `AdjudicationResult` to
+ * archive elsewhere.
+ */
+export interface TransitionLogEntry {
+    from: WorkPacketState;
+    to: WorkPacketState;
+    at: string;
+    cause: string;
+}
+/**
+ * Part 1 §1 / §7 — the Work Packet: the durable unit of intent this loop manages, potentially
+ * resubmitted across several Dispatch Records over its life.
+ *
+ * The design doc (§7) also describes `adjudication_retry_count` (a separate bounded counter
+ * for retrying the `adjudicate()` call itself, Part 1 §2/§6) and
+ * `last_human_approved_topology_class` as persisted fields. Those are not modeled on this
+ * type in this cut; a later change can add them without breaking the fields defined here.
+ */
+export interface WorkPacket {
+    packet_id: string;
+    kind: string;
+    created_at: string;
+    payload: unknown;
+    topology_decision: {
+        classification: TopologyClassification;
+        decided_at: string;
+        raw_route_response: unknown;
+    } | null;
+    dispatch_records: DispatchRecord[];
+    state: WorkPacketState;
+    retry_count: number;
+    transition_log: TransitionLogEntry[];
+    last_adjudication_ref: string | null;
+    /** Part 1 §4 — the per-packet attempt budget (`max_dispatch_attempts`) and how much of it has been used. */
+    attempt_budget: {
+        max_dispatch_attempts: number;
+        dispatch_attempts_used: number;
+    };
+    /**
+     * Part 1 §2 state 3 / §7 — the payload most recently approved by a human reviewer (or the
+     * original payload at creation, implicitly approved). `null` only if the packet has not yet
+     * been assigned an initial baseline. Used by `requiresHumanApproval` to decide whether the
+     * next attempt needs an AWAITING_APPROVAL gate before its first dispatch.
+     */
+    last_human_approved_payload: unknown | null;
+}
+/**
+ * Part 1 §4 — the named reasons the loop stops admitting new DRAFTED packets and begins
+ * draining. `capacity_ceiling` and the cardinality-mismatch guard are soft governors (they
+ * reduce admission/concurrency rather than terminating the loop outright); the others are
+ * hard termination conditions.
+ */
+export type LoopTerminationCondition = "completion_exhaustion" | "per_packet_attempt_budget" | "wall_clock_budget" | "dispatch_call_budget" | "stagnation_guard" | "capacity_ceiling" | "external_abort";
+/**
+ * Part 1 §4 — loop-instance configuration. Per the "Budget immutability" rule in §4, every
+ * field here is fixed at loop-instance creation and must not be mutated for that instance's
+ * lifetime; raising a threshold requires starting a new loop instance.
+ */
+export interface LoopConfig {
+    loop_instance_id: string;
+    /** Part 1 §4 "Per-packet attempt budget" — illustrative default in the design doc is 3. */
+    max_dispatch_attempts_per_packet: number;
+    /** Part 1 §4 "Loop wall-clock budget", expressed in milliseconds. */
+    max_loop_duration_ms: number;
+    /** Part 1 §4 "Loop dispatch-call budget" — total `adaptorch_run` invocations allowed across the loop's life. */
+    max_total_dispatch_calls: number;
+    /**
+     * Part 1 §4 "Stagnation guard" — the number of consecutive loop-wide DECLINED verdicts
+     * with indistinguishable evidence (same reason text / same evidence digest) that triggers
+     * a halt.
+     */
+    stagnation_repeat_threshold: number;
+    /**
+     * Part 1 §4 "Capacity ceiling (soft governor)". Shape chosen for this implementation, not
+     * dictated verbatim by the design doc: a saturation fraction/duration pair that must be
+     * sustained before the governor engages, and the reduced concurrency ceiling it engages to.
+     */
+    capacity_governor_thresholds: {
+        /** Fraction (0-1) of `adaptorch_server_metrics` saturation considered "sustained saturation". */
+        saturation_threshold: number;
+        /** How long saturation must persist, in milliseconds, before the governor engages. */
+        sustained_duration_ms: number;
+        /** Concurrency budget (max packets allowed into ACTIVE at once) while the governor is engaged. */
+        reduced_concurrency_ceiling: number;
+    };
+    /**
+     * Part 1 §2 state 3 — the documented opt-in escape hatch that skips AWAITING_APPROVAL
+     * for every attempt in this loop instance, regardless of payload/topology drift.
+     */
+    pre_approved_batch: boolean;
+    /**
+     * Part 1 §3.4 — the result of the one-time cardinality calibration probe, or `null` before
+     * that probe has run. Continuously cross-checked (at zero extra call cost) against later
+     * `adaptorch_get_run`/reconciliation-sweep observations per §3.4.
+     */
+    observed_cardinality_mode: CardinalityMode | null;
+}
+/**
+ * Part 1 §7 — on-disk file layout constants, rooted at a loop-instance directory. Exported so
+ * other modules never hardcode these path segments.
+ */
+export declare const PACKETS_DIR = "packets";
+export declare const PACKET_INDEX_FILE = "packet_index.json";
+export declare const RUN_MAP_FILE = "run_map.json";
+export declare const LOOP_STATE_FILE = "loop_state.json";
+export declare const ADJUDICATIONS_DIR = "adjudications";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACxB,SAAS,GACT,QAAQ,GACR,mBAAmB,GACnB,YAAY,GACZ,QAAQ,GACR,SAAS,GACT,cAAc,GACd,cAAc,GACd,qBAAqB,GACrB,WAAW,GACX,UAAU,GACV,cAAc,GACd,WAAW,GACX,QAAQ,CAAC;AAEZ;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,UAAU,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,UAAU,GAAG,KAAK,GAAG,UAAU,CAAC;AAEnF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,eAAe,CAAC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,EAAE,EAAE,eAAe,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,EAAE;QAClB,cAAc,EAAE,sBAAsB,CAAC;QACvC,UAAU,EAAE,MAAM,CAAC;QACnB,kBAAkB,EAAE,OAAO,CAAC;KAC5B,GAAG,IAAI,CAAC;IACT,gBAAgB,EAAE,cAAc,EAAE,CAAC;IACnC,KAAK,EAAE,eAAe,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,kBAAkB,EAAE,CAAC;IACrC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,+GAA4G;IAC5G,cAAc,EAAE;QACf,qBAAqB,EAAE,MAAM,CAAC;QAC9B,sBAAsB,EAAE,MAAM,CAAC;KAC/B,CAAC;IACF;;;;;OAKG;IACH,2BAA2B,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GACjC,uBAAuB,GACvB,2BAA2B,GAC3B,mBAAmB,GACnB,sBAAsB,GACtB,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,CAAC;AAEpB;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,8FAA2F;IAC3F,gCAAgC,EAAE,MAAM,CAAC;IACzC,sEAAqE;IACrE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mHAAgH;IAChH,wBAAwB,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,2BAA2B,EAAE,MAAM,CAAC;IACpC;;;;OAIG;IACH,4BAA4B,EAAE;QAC7B,iGAAiG;QACjG,oBAAoB,EAAE,MAAM,CAAC;QAC7B,sFAAsF;QACtF,qBAAqB,EAAE,MAAM,CAAC;QAC9B,kGAAkG;QAClG,2BAA2B,EAAE,MAAM,CAAC;KACpC,CAAC;IACF;;;OAGG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,yBAAyB,EAAE,eAAe,GAAG,IAAI,CAAC;CAClD;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,YAAY,CAAC;AACrC,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AACrD,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAC3C,eAAO,MAAM,eAAe,oBAAoB,CAAC;AACjD,eAAO,MAAM,iBAAiB,kBAAkB,CAAC","sourcesContent":["/**\n * Design-fidelity note: this file implements the Work Packet on-disk schema and supporting\n * type vocabulary defined in Part 1 (`final-part1-core-algorithm.md`), Sections 1, 2, 3, 4,\n * and 7. It is an implementation of that document, not a restatement of it — see the design\n * doc for rationale, transition semantics, and the open questions left for other lanes.\n */\n\n/**\n * Work Packet lifecycle states.\n *\n * Part 1 §2 — the fourteen states of the packet-level state machine, including the\n * ESCALATED / AWAITING_APPROVAL / ADJUDICATION_FAILED additions from this revision.\n */\nexport type WorkPacketState =\n\t| \"DRAFTED\"\n\t| \"ROUTED\"\n\t| \"AWAITING_APPROVAL\"\n\t| \"DISPATCHED\"\n\t| \"ACTIVE\"\n\t| \"HALTING\"\n\t| \"RAW_TERMINAL\"\n\t| \"UNDER_REVIEW\"\n\t| \"ADJUDICATION_FAILED\"\n\t| \"CONFIRMED\"\n\t| \"DECLINED\"\n\t| \"RETRY_QUEUED\"\n\t| \"ESCALATED\"\n\t| \"CLOSED\";\n\n/**\n * Part 1 §3.3 — whether a Dispatch Record's run_id set was produced by a single\n * `adaptorch_run` call (`single_call`) or by N calls the loop itself issued (`fanout_n`).\n * This tag is what lets the rest of the state machine stay agnostic to the Section 3.2\n * single-call-vs-client-side-fanout ambiguity.\n */\nexport type CardinalityMode = \"single_call\" | \"fanout_n\";\n\n/**\n * Part 1 §3.1 — the four topology classes `adaptorch_route_topology` can return for a\n * packet's payload, decided once per packet before any `adaptorch_run` call.\n */\nexport type TopologyClassification = \"singleton\" | \"pipeline\" | \"dag\" | \"ensemble\";\n\n/**\n * Part 1 §3.3 / §7 — one concrete submission attempt for a Work Packet. A Dispatch Record\n * holds a run_id *set* (not a single run_id) tagged with its cardinality mode, so polling,\n * cancellation, and review packaging work the same way regardless of which Section 3.2\n * reading turns out to be correct.\n */\nexport interface DispatchRecord {\n\tattempt_n: number;\n\tcardinality_mode: CardinalityMode;\n\trun_ids: string[];\n\tsubmitted_at: string;\n\tmode: \"blocking\" | \"polling\";\n\tterminal_status?: string;\n\tterminal_at?: string;\n}\n\n/**\n * Part 1 §7 — one append-only entry in a Work Packet's transition log. Recorded for every\n * state change, including adjudication-call failures that have no `AdjudicationResult` to\n * archive elsewhere.\n */\nexport interface TransitionLogEntry {\n\tfrom: WorkPacketState;\n\tto: WorkPacketState;\n\tat: string;\n\tcause: string;\n}\n\n/**\n * Part 1 §1 / §7 — the Work Packet: the durable unit of intent this loop manages, potentially\n * resubmitted across several Dispatch Records over its life.\n *\n * The design doc (§7) also describes `adjudication_retry_count` (a separate bounded counter\n * for retrying the `adjudicate()` call itself, Part 1 §2/§6) and\n * `last_human_approved_topology_class` as persisted fields. Those are not modeled on this\n * type in this cut; a later change can add them without breaking the fields defined here.\n */\nexport interface WorkPacket {\n\tpacket_id: string;\n\tkind: string;\n\tcreated_at: string;\n\tpayload: unknown;\n\ttopology_decision: {\n\t\tclassification: TopologyClassification;\n\t\tdecided_at: string;\n\t\traw_route_response: unknown;\n\t} | null;\n\tdispatch_records: DispatchRecord[];\n\tstate: WorkPacketState;\n\tretry_count: number;\n\ttransition_log: TransitionLogEntry[];\n\tlast_adjudication_ref: string | null;\n\t/** Part 1 §4 — the per-packet attempt budget (`max_dispatch_attempts`) and how much of it has been used. */\n\tattempt_budget: {\n\t\tmax_dispatch_attempts: number;\n\t\tdispatch_attempts_used: number;\n\t};\n\t/**\n\t * Part 1 §2 state 3 / §7 — the payload most recently approved by a human reviewer (or the\n\t * original payload at creation, implicitly approved). `null` only if the packet has not yet\n\t * been assigned an initial baseline. Used by `requiresHumanApproval` to decide whether the\n\t * next attempt needs an AWAITING_APPROVAL gate before its first dispatch.\n\t */\n\tlast_human_approved_payload: unknown | null;\n}\n\n/**\n * Part 1 §4 — the named reasons the loop stops admitting new DRAFTED packets and begins\n * draining. `capacity_ceiling` and the cardinality-mismatch guard are soft governors (they\n * reduce admission/concurrency rather than terminating the loop outright); the others are\n * hard termination conditions.\n */\nexport type LoopTerminationCondition =\n\t| \"completion_exhaustion\"\n\t| \"per_packet_attempt_budget\"\n\t| \"wall_clock_budget\"\n\t| \"dispatch_call_budget\"\n\t| \"stagnation_guard\"\n\t| \"capacity_ceiling\"\n\t| \"external_abort\";\n\n/**\n * Part 1 §4 — loop-instance configuration. Per the \"Budget immutability\" rule in §4, every\n * field here is fixed at loop-instance creation and must not be mutated for that instance's\n * lifetime; raising a threshold requires starting a new loop instance.\n */\nexport interface LoopConfig {\n\tloop_instance_id: string;\n\t/** Part 1 §4 \"Per-packet attempt budget\" — illustrative default in the design doc is 3. */\n\tmax_dispatch_attempts_per_packet: number;\n\t/** Part 1 §4 \"Loop wall-clock budget\", expressed in milliseconds. */\n\tmax_loop_duration_ms: number;\n\t/** Part 1 §4 \"Loop dispatch-call budget\" — total `adaptorch_run` invocations allowed across the loop's life. */\n\tmax_total_dispatch_calls: number;\n\t/**\n\t * Part 1 §4 \"Stagnation guard\" — the number of consecutive loop-wide DECLINED verdicts\n\t * with indistinguishable evidence (same reason text / same evidence digest) that triggers\n\t * a halt.\n\t */\n\tstagnation_repeat_threshold: number;\n\t/**\n\t * Part 1 §4 \"Capacity ceiling (soft governor)\". Shape chosen for this implementation, not\n\t * dictated verbatim by the design doc: a saturation fraction/duration pair that must be\n\t * sustained before the governor engages, and the reduced concurrency ceiling it engages to.\n\t */\n\tcapacity_governor_thresholds: {\n\t\t/** Fraction (0-1) of `adaptorch_server_metrics` saturation considered \"sustained saturation\". */\n\t\tsaturation_threshold: number;\n\t\t/** How long saturation must persist, in milliseconds, before the governor engages. */\n\t\tsustained_duration_ms: number;\n\t\t/** Concurrency budget (max packets allowed into ACTIVE at once) while the governor is engaged. */\n\t\treduced_concurrency_ceiling: number;\n\t};\n\t/**\n\t * Part 1 §2 state 3 — the documented opt-in escape hatch that skips AWAITING_APPROVAL\n\t * for every attempt in this loop instance, regardless of payload/topology drift.\n\t */\n\tpre_approved_batch: boolean;\n\t/**\n\t * Part 1 §3.4 — the result of the one-time cardinality calibration probe, or `null` before\n\t * that probe has run. Continuously cross-checked (at zero extra call cost) against later\n\t * `adaptorch_get_run`/reconciliation-sweep observations per §3.4.\n\t */\n\tobserved_cardinality_mode: CardinalityMode | null;\n}\n\n/**\n * Part 1 §7 — on-disk file layout constants, rooted at a loop-instance directory. Exported so\n * other modules never hardcode these path segments.\n */\nexport const PACKETS_DIR = \"packets\";\nexport const PACKET_INDEX_FILE = \"packet_index.json\";\nexport const RUN_MAP_FILE = \"run_map.json\";\nexport const LOOP_STATE_FILE = \"loop_state.json\";\nexport const ADJUDICATIONS_DIR = \"adjudications\";\n"]}

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Design-fidelity note: this file implements the Work Packet on-disk schema and supporting
+ * type vocabulary defined in Part 1 (`final-part1-core-algorithm.md`), Sections 1, 2, 3, 4,
+ * and 7. It is an implementation of that document, not a restatement of it — see the design
+ * doc for rationale, transition semantics, and the open questions left for other lanes.
+ */
+/**
+ * Part 1 §7 — on-disk file layout constants, rooted at a loop-instance directory. Exported so
+ * other modules never hardcode these path segments.
+ */
+export const PACKETS_DIR = "packets";
+export const PACKET_INDEX_FILE = "packet_index.json";
+export const RUN_MAP_FILE = "run_map.json";
+export const LOOP_STATE_FILE = "loop_state.json";
+export const ADJUDICATIONS_DIR = "adjudications";
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoKH;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AACrC,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AACrD,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC;AAC3C,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AACjD,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC","sourcesContent":["/**\n * Design-fidelity note: this file implements the Work Packet on-disk schema and supporting\n * type vocabulary defined in Part 1 (`final-part1-core-algorithm.md`), Sections 1, 2, 3, 4,\n * and 7. It is an implementation of that document, not a restatement of it — see the design\n * doc for rationale, transition semantics, and the open questions left for other lanes.\n */\n\n/**\n * Work Packet lifecycle states.\n *\n * Part 1 §2 — the fourteen states of the packet-level state machine, including the\n * ESCALATED / AWAITING_APPROVAL / ADJUDICATION_FAILED additions from this revision.\n */\nexport type WorkPacketState =\n\t| \"DRAFTED\"\n\t| \"ROUTED\"\n\t| \"AWAITING_APPROVAL\"\n\t| \"DISPATCHED\"\n\t| \"ACTIVE\"\n\t| \"HALTING\"\n\t| \"RAW_TERMINAL\"\n\t| \"UNDER_REVIEW\"\n\t| \"ADJUDICATION_FAILED\"\n\t| \"CONFIRMED\"\n\t| \"DECLINED\"\n\t| \"RETRY_QUEUED\"\n\t| \"ESCALATED\"\n\t| \"CLOSED\";\n\n/**\n * Part 1 §3.3 — whether a Dispatch Record's run_id set was produced by a single\n * `adaptorch_run` call (`single_call`) or by N calls the loop itself issued (`fanout_n`).\n * This tag is what lets the rest of the state machine stay agnostic to the Section 3.2\n * single-call-vs-client-side-fanout ambiguity.\n */\nexport type CardinalityMode = \"single_call\" | \"fanout_n\";\n\n/**\n * Part 1 §3.1 — the four topology classes `adaptorch_route_topology` can return for a\n * packet's payload, decided once per packet before any `adaptorch_run` call.\n */\nexport type TopologyClassification = \"singleton\" | \"pipeline\" | \"dag\" | \"ensemble\";\n\n/**\n * Part 1 §3.3 / §7 — one concrete submission attempt for a Work Packet. A Dispatch Record\n * holds a run_id *set* (not a single run_id) tagged with its cardinality mode, so polling,\n * cancellation, and review packaging work the same way regardless of which Section 3.2\n * reading turns out to be correct.\n */\nexport interface DispatchRecord {\n\tattempt_n: number;\n\tcardinality_mode: CardinalityMode;\n\trun_ids: string[];\n\tsubmitted_at: string;\n\tmode: \"blocking\" | \"polling\";\n\tterminal_status?: string;\n\tterminal_at?: string;\n}\n\n/**\n * Part 1 §7 — one append-only entry in a Work Packet's transition log. Recorded for every\n * state change, including adjudication-call failures that have no `AdjudicationResult` to\n * archive elsewhere.\n */\nexport interface TransitionLogEntry {\n\tfrom: WorkPacketState;\n\tto: WorkPacketState;\n\tat: string;\n\tcause: string;\n}\n\n/**\n * Part 1 §1 / §7 — the Work Packet: the durable unit of intent this loop manages, potentially\n * resubmitted across several Dispatch Records over its life.\n *\n * The design doc (§7) also describes `adjudication_retry_count` (a separate bounded counter\n * for retrying the `adjudicate()` call itself, Part 1 §2/§6) and\n * `last_human_approved_topology_class` as persisted fields. Those are not modeled on this\n * type in this cut; a later change can add them without breaking the fields defined here.\n */\nexport interface WorkPacket {\n\tpacket_id: string;\n\tkind: string;\n\tcreated_at: string;\n\tpayload: unknown;\n\ttopology_decision: {\n\t\tclassification: TopologyClassification;\n\t\tdecided_at: string;\n\t\traw_route_response: unknown;\n\t} | null;\n\tdispatch_records: DispatchRecord[];\n\tstate: WorkPacketState;\n\tretry_count: number;\n\ttransition_log: TransitionLogEntry[];\n\tlast_adjudication_ref: string | null;\n\t/** Part 1 §4 — the per-packet attempt budget (`max_dispatch_attempts`) and how much of it has been used. */\n\tattempt_budget: {\n\t\tmax_dispatch_attempts: number;\n\t\tdispatch_attempts_used: number;\n\t};\n\t/**\n\t * Part 1 §2 state 3 / §7 — the payload most recently approved by a human reviewer (or the\n\t * original payload at creation, implicitly approved). `null` only if the packet has not yet\n\t * been assigned an initial baseline. Used by `requiresHumanApproval` to decide whether the\n\t * next attempt needs an AWAITING_APPROVAL gate before its first dispatch.\n\t */\n\tlast_human_approved_payload: unknown | null;\n}\n\n/**\n * Part 1 §4 — the named reasons the loop stops admitting new DRAFTED packets and begins\n * draining. `capacity_ceiling` and the cardinality-mismatch guard are soft governors (they\n * reduce admission/concurrency rather than terminating the loop outright); the others are\n * hard termination conditions.\n */\nexport type LoopTerminationCondition =\n\t| \"completion_exhaustion\"\n\t| \"per_packet_attempt_budget\"\n\t| \"wall_clock_budget\"\n\t| \"dispatch_call_budget\"\n\t| \"stagnation_guard\"\n\t| \"capacity_ceiling\"\n\t| \"external_abort\";\n\n/**\n * Part 1 §4 — loop-instance configuration. Per the \"Budget immutability\" rule in §4, every\n * field here is fixed at loop-instance creation and must not be mutated for that instance's\n * lifetime; raising a threshold requires starting a new loop instance.\n */\nexport interface LoopConfig {\n\tloop_instance_id: string;\n\t/** Part 1 §4 \"Per-packet attempt budget\" — illustrative default in the design doc is 3. */\n\tmax_dispatch_attempts_per_packet: number;\n\t/** Part 1 §4 \"Loop wall-clock budget\", expressed in milliseconds. */\n\tmax_loop_duration_ms: number;\n\t/** Part 1 §4 \"Loop dispatch-call budget\" — total `adaptorch_run` invocations allowed across the loop's life. */\n\tmax_total_dispatch_calls: number;\n\t/**\n\t * Part 1 §4 \"Stagnation guard\" — the number of consecutive loop-wide DECLINED verdicts\n\t * with indistinguishable evidence (same reason text / same evidence digest) that triggers\n\t * a halt.\n\t */\n\tstagnation_repeat_threshold: number;\n\t/**\n\t * Part 1 §4 \"Capacity ceiling (soft governor)\". Shape chosen for this implementation, not\n\t * dictated verbatim by the design doc: a saturation fraction/duration pair that must be\n\t * sustained before the governor engages, and the reduced concurrency ceiling it engages to.\n\t */\n\tcapacity_governor_thresholds: {\n\t\t/** Fraction (0-1) of `adaptorch_server_metrics` saturation considered \"sustained saturation\". */\n\t\tsaturation_threshold: number;\n\t\t/** How long saturation must persist, in milliseconds, before the governor engages. */\n\t\tsustained_duration_ms: number;\n\t\t/** Concurrency budget (max packets allowed into ACTIVE at once) while the governor is engaged. */\n\t\treduced_concurrency_ceiling: number;\n\t};\n\t/**\n\t * Part 1 §2 state 3 — the documented opt-in escape hatch that skips AWAITING_APPROVAL\n\t * for every attempt in this loop instance, regardless of payload/topology drift.\n\t */\n\tpre_approved_batch: boolean;\n\t/**\n\t * Part 1 §3.4 — the result of the one-time cardinality calibration probe, or `null` before\n\t * that probe has run. Continuously cross-checked (at zero extra call cost) against later\n\t * `adaptorch_get_run`/reconciliation-sweep observations per §3.4.\n\t */\n\tobserved_cardinality_mode: CardinalityMode | null;\n}\n\n/**\n * Part 1 §7 — on-disk file layout constants, rooted at a loop-instance directory. Exported so\n * other modules never hardcode these path segments.\n */\nexport const PACKETS_DIR = \"packets\";\nexport const PACKET_INDEX_FILE = \"packet_index.json\";\nexport const RUN_MAP_FILE = \"run_map.json\";\nexport const LOOP_STATE_FILE = \"loop_state.json\";\nexport const ADJUDICATIONS_DIR = \"adjudications\";\n"]}

package/dist/wall-meta.d.ts

@@ -0,0 +1,3 @@
+/** Correctness wall receipt schema / policy batch identifier. */
+export declare const CORRECTNESS_WALL_VERSION: "2026-07-08.batch2";
+//# sourceMappingURL=wall-meta.d.ts.map

package/dist/wall-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wall-meta.d.ts","sourceRoot":"","sources":["../src/wall-meta.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,qBAA+B,CAAC","sourcesContent":["/** Correctness wall receipt schema / policy batch identifier. */\nexport const CORRECTNESS_WALL_VERSION = \"2026-07-08.batch2\" as const;\n"]}

package/dist/wall-meta.js

@@ -0,0 +1,3 @@
+/** Correctness wall receipt schema / policy batch identifier. */
+export const CORRECTNESS_WALL_VERSION = "2026-07-08.batch2";
+//# sourceMappingURL=wall-meta.js.map

package/dist/wall-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wall-meta.js","sourceRoot":"","sources":["../src/wall-meta.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,CAAC,MAAM,wBAAwB,GAAG,mBAA4B,CAAC","sourcesContent":["/** Correctness wall receipt schema / policy batch identifier. */\nexport const CORRECTNESS_WALL_VERSION = \"2026-07-08.batch2\" as const;\n"]}

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "omk-adaptorch-wpl",
+	"version": "0.91.0",
+	"description": "AdaptOrch-native Work Packet Loop (WPL) — state machine, verification layer, and integration bridge for OMK orchestration.",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"build": "tsgo -p tsconfig.build.json",
+		"test": "vitest --run"
+	},
+	"keywords": [
+		"adaptorch",
+		"orchestration",
+		"experimental"
+	],
+	"author": "dmae",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dmae97/omk.git",
+		"directory": "packages/adaptorch-wpl"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"devDependencies": {
+		"@types/node": "24.12.4",
+		"@vitest/coverage-v8": "3.2.6",
+		"shx": "0.4.0",
+		"typescript": "5.9.3",
+		"vitest": "3.2.6"
+	}
+}