@agenticprimitives/fabric 0.0.0-alpha.4 → 0.0.0-alpha.41

package/dist/cloudflare/interaction-store.js

@@ -0,0 +1,281 @@
+/// <reference types="@cloudflare/workers-types" />
+// DO-local InteractionStore (spec 340 W6) — durable homes for the records W2–W5 defined and nothing
+// wrote. The `PrincipalGatewayDO` is the single writer for its principal, so no cross-writer races.
+//
+// Five tables, and the reason they are five rather than one wide row is the reason there are six state
+// machines: an interaction's lifecycle, a decision, a commitment and a viewer's inbox state are
+// answered by different parties at different times, and one row would make them one write.
+//
+// TWO INVARIANTS THIS LAYER OWNS, both about immutability rather than authority:
+//
+//   1. A ContextSnapshot is CONTENT-ADDRESSED, and the digest check IS the immutability guarantee.
+//      `putContextSnapshot` verifies the digest against the bytes before storing, so a party cannot
+//      rewrite what an evaluator saw while every Exchange still pins the same hash — the forged
+//      snapshot is refused at the door, not detected later.
+//
+//      There is deliberately no separate `immutable-conflict` outcome. It was written first and was
+//      BOTH dead and wrong: dead, because content that differs necessarily fails the digest check
+//      already; and wrong, because it compared `JSON.stringify` output, so the same snapshot re-put
+//      with a different key insertion order would have been rejected as a conflicting overwrite. A
+//      verified digest with a row already at it means the content is the same — that is what
+//      content-addressing means — so the re-put is a no-op.
+//   2. Every transition goes through its machine. The store never sets a state directly, so "the
+//      creditor discharges, not the debtor" cannot be bypassed by writing the row.
+//
+// It confers nothing. Persisting a commitment does not make it owed; persisting a decision does not
+// authorize anything. Authority is `delegation` + `entitlements` + `tool-policy` at the moment of
+// acting (ADR-0041, ADR-0043).
+import { verifyContextSnapshot } from '../interaction-record.js';
+import { applyInteractionTransition, applyDecisionTransition, applyCommitmentTransition, applyInboxTransition, TERMINAL_INTERACTION_STATES, TERMINAL_DECISION_STATES, TERMINAL_COMMITMENT_STATES, } from '../interaction-machines.js';
+import { bindingKey, resolveInteractionByBinding, } from '../protocol-binding.js';
+import { canonicalizeJson } from '@agenticprimitives/types';
+const CREATE_TABLES = [
+    `CREATE TABLE IF NOT EXISTS interaction_records (
+     interaction_id TEXT PRIMARY KEY,
+     record_json    TEXT NOT NULL,
+     state          TEXT NOT NULL,
+     rev            INTEGER NOT NULL,
+     updated_at     TEXT NOT NULL
+   )`,
+    // Keyed by the binding, not by the interaction: the lookup direction is foreign → ours, and a
+    // duplicate key across two interactions is the AMBIGUITY the resolver must be able to see. A UNIQUE
+    // constraint here would silently drop the second one and manufacture a confident wrong answer.
+    `CREATE TABLE IF NOT EXISTS interaction_bindings (
+     binding_key    TEXT NOT NULL,
+     interaction_id TEXT NOT NULL,
+     binding_json   TEXT NOT NULL,
+     PRIMARY KEY (binding_key, interaction_id)
+   )`,
+    `CREATE TABLE IF NOT EXISTS context_snapshots (
+     digest        TEXT PRIMARY KEY,
+     snapshot_json TEXT NOT NULL
+   )`,
+    `CREATE TABLE IF NOT EXISTS decision_records (
+     decision_id  TEXT PRIMARY KEY,
+     record_json  TEXT NOT NULL,
+     updated_at   TEXT NOT NULL
+   )`,
+    `CREATE TABLE IF NOT EXISTS commitment_records (
+     commitment_id TEXT PRIMARY KEY,
+     record_json   TEXT NOT NULL,
+     state         TEXT NOT NULL,
+     updated_at    TEXT NOT NULL
+   )`,
+    `CREATE TABLE IF NOT EXISTS inbox_entries (
+     viewer      TEXT NOT NULL,
+     exchange_id TEXT NOT NULL,
+     record_json TEXT NOT NULL,
+     PRIMARY KEY (viewer, exchange_id)
+   )`,
+];
+/**
+ * A `put*` was offered over a record that has already ENDED (spec 445 §3.4, audit DATB-6).
+ *
+ * THE RULE: a put creates a record or replaces one that is still live; it never replaces one in a
+ * terminal state. A concluded interaction, a refused decision and a discharged commitment are facts
+ * about how something ended, and the machines refuse every transition out of them — a put that could
+ * write `active` over `discharged` would make that refusal a convention rather than a property.
+ *
+ * Thrown, not returned: the port's `put*` return `void`, and a refusal a caller can ignore by not
+ * looking is the silent overwrite again. Re-putting the IDENTICAL record is a no-op, not an error —
+ * a replayed import says nothing new. The reducers are unaffected: a transition is only ever applied
+ * to a non-terminal record, so their own writes never meet this guard.
+ */
+export class TerminalRecordError extends Error {
+    family;
+    id;
+    state;
+    reason = 'terminal-state';
+    constructor(family, id, state) {
+        super(`interaction-store: ${family} ${id} is ${state} (terminal); a put may not replace it`);
+        this.family = family;
+        this.id = id;
+        this.state = state;
+        this.name = 'TerminalRecordError';
+    }
+}
+/** The guard both stores share, so "terminal" cannot mean one thing over DO-SQL and another over the
+ *  vault. Returns `'skip'` when the offered record is identical to the stored terminal one. */
+export function guardPutOverTerminal(family, id, existing, incoming, stateOf) {
+    if (!existing)
+        return 'write';
+    const terminal = family === 'interaction' ? TERMINAL_INTERACTION_STATES
+        : family === 'decision' ? TERMINAL_DECISION_STATES
+            : TERMINAL_COMMITMENT_STATES;
+    const state = stateOf(existing);
+    if (!terminal.includes(state))
+        return 'write';
+    if (canonicalizeJson(existing) === canonicalizeJson(incoming))
+        return 'skip';
+    throw new TerminalRecordError(family, id, state);
+}
+/** States an obligation is still live in. `discharged`/`breached`/`void` are ended, differently. */
+const OPEN_COMMITMENT_STATES = ['proposed', 'active', 'fulfilment-claimed'];
+export function createDurableObjectInteractionStore(sql) {
+    for (const ddl of CREATE_TABLES)
+        sql.exec(ddl);
+    const one = (query, ...binds) => {
+        const rows = sql.exec(query, ...binds).toArray();
+        return rows[0] ? JSON.parse(rows[0].record_json) : null;
+    };
+    const saveInteraction = (record) => {
+        sql.exec(`INSERT INTO interaction_records (interaction_id, record_json, state, rev, updated_at)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(interaction_id) DO UPDATE SET
+         record_json = excluded.record_json, state = excluded.state,
+         rev = excluded.rev, updated_at = excluded.updated_at`, record.interactionId, JSON.stringify(record), lifecycleStateOf(record), record.rev, record.updatedAt);
+    };
+    const saveCommitment = (record) => {
+        sql.exec(`INSERT INTO commitment_records (commitment_id, record_json, state, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(commitment_id) DO UPDATE SET
+         record_json = excluded.record_json, state = excluded.state, updated_at = excluded.updated_at`, record.commitmentId, JSON.stringify(record), record.state, record.updatedAt);
+    };
+    const store = {
+        async putInteraction(record) {
+            const existing = await this.getInteraction(record.interactionId);
+            if (guardPutOverTerminal('interaction', String(record.interactionId), existing, record, lifecycleStateOf) === 'skip')
+                return;
+            saveInteraction(record);
+            for (const b of record.protocolBindings ?? []) {
+                sql.exec(`INSERT INTO interaction_bindings (binding_key, interaction_id, binding_json) VALUES (?, ?, ?)
+           ON CONFLICT(binding_key, interaction_id) DO UPDATE SET binding_json = excluded.binding_json`, bindingKey(b.protocol, b.field, b.value), record.interactionId, JSON.stringify(b));
+            }
+        },
+        async getInteraction(id) {
+            return one('SELECT record_json FROM interaction_records WHERE interaction_id = ?', String(id));
+        },
+        async listInteractions() {
+            return sql
+                .exec('SELECT record_json FROM interaction_records ORDER BY updated_at DESC')
+                .toArray()
+                .map((r) => JSON.parse(r.record_json));
+        },
+        async transitionInteraction(id, event) {
+            const record = await this.getInteraction(id);
+            if (!record)
+                return null;
+            const result = applyInteractionTransition(lifecycleOf(record), event);
+            // Fail-closed: a rejection leaves the row exactly as it was. The store never sets state itself,
+            // so "concluding is custodial" cannot be bypassed by writing the row directly.
+            if (result.ok) {
+                saveInteraction({
+                    ...record,
+                    lifecycleState: result.next.state,
+                    updatedAt: event.at,
+                    rev: record.rev + 1,
+                });
+            }
+            return result;
+        },
+        async bindProtocolTo(id, binding) {
+            sql.exec(`INSERT INTO interaction_bindings (binding_key, interaction_id, binding_json) VALUES (?, ?, ?)
+         ON CONFLICT(binding_key, interaction_id) DO UPDATE SET binding_json = excluded.binding_json`, bindingKey(binding.protocol, binding.field, binding.value), id, JSON.stringify(binding));
+        },
+        async resolveByBinding(protocol, field, value) {
+            const key = bindingKey(protocol, field, value);
+            const ids = sql
+                .exec('SELECT interaction_id FROM interaction_bindings WHERE binding_key = ?', key)
+                .toArray()
+                .map((r) => r.interaction_id);
+            // Reuses the in-memory resolver over a one-key index so SQL and non-SQL callers cannot disagree
+            // about what "ambiguous" means — one definition, two backing stores.
+            return resolveInteractionByBinding(new Map([[key, ids]]), protocol, field, value);
+        },
+        async putContextSnapshot(snapshot) {
+            // A snapshot whose digest does not match its bytes is not evidence, and storing it would let a
+            // later `verifyContextSnapshot` fail on a record that arrived corrupt rather than was tampered.
+            if (!(await verifyContextSnapshot(snapshot)))
+                return { ok: false, reason: 'digest-mismatch' };
+            const existing = sql
+                .exec('SELECT snapshot_json FROM context_snapshots WHERE digest = ?', snapshot.digest)
+                .toArray()[0];
+            // The digest verified and a row is already here, so the content is the same — two parties
+            // observing one context legitimately store it twice. A no-op, and the stored bytes win.
+            if (existing)
+                return { ok: true, stored: 'identical' };
+            sql.exec('INSERT INTO context_snapshots (digest, snapshot_json) VALUES (?, ?)', snapshot.digest, JSON.stringify(snapshot));
+            return { ok: true, stored: 'new' };
+        },
+        async getContextSnapshot(digest) {
+            const rows = sql
+                .exec('SELECT snapshot_json FROM context_snapshots WHERE digest = ?', digest)
+                .toArray();
+            return rows[0] ? JSON.parse(rows[0].snapshot_json) : null;
+        },
+        async putDecision(record) {
+            const existing = await this.getDecision(record.decisionId);
+            if (guardPutOverTerminal('decision', record.decisionId, existing, record, (r) => r.state) === 'skip')
+                return;
+            sql.exec(`INSERT INTO decision_records (decision_id, record_json, updated_at) VALUES (?, ?, ?)
+         ON CONFLICT(decision_id) DO UPDATE SET record_json = excluded.record_json, updated_at = excluded.updated_at`, record.decisionId, JSON.stringify(record), record.updatedAt);
+        },
+        async getDecision(id) {
+            return one('SELECT record_json FROM decision_records WHERE decision_id = ?', id);
+        },
+        async transitionDecision(id, event) {
+            const record = await this.getDecision(id);
+            if (!record)
+                return null;
+            const result = applyDecisionTransition(record, event);
+            if (result.ok)
+                await this.putDecision(result.next);
+            return result;
+        },
+        async putCommitment(record) {
+            const existing = await this.getCommitment(record.commitmentId);
+            if (guardPutOverTerminal('commitment', record.commitmentId, existing, record, (r) => r.state) === 'skip')
+                return;
+            saveCommitment(record);
+        },
+        async getCommitment(id) {
+            return one('SELECT record_json FROM commitment_records WHERE commitment_id = ?', id);
+        },
+        async listOpenCommitments() {
+            return sql
+                .exec(`SELECT record_json FROM commitment_records WHERE state IN (?, ?, ?) ORDER BY updated_at DESC`, ...OPEN_COMMITMENT_STATES)
+                .toArray()
+                .map((r) => JSON.parse(r.record_json));
+        },
+        async transitionCommitment(id, event) {
+            const record = await this.getCommitment(id);
+            if (!record)
+                return null;
+            const result = applyCommitmentTransition(record, event);
+            if (result.ok)
+                saveCommitment(result.next);
+            return result;
+        },
+        async putInboxEntry(entry) {
+            sql.exec(`INSERT INTO inbox_entries (viewer, exchange_id, record_json) VALUES (?, ?, ?)
+         ON CONFLICT(viewer, exchange_id) DO UPDATE SET record_json = excluded.record_json`, entry.viewer, entry.exchangeId, JSON.stringify(entry));
+        },
+        async getInboxEntry(viewer, exchangeId) {
+            return one('SELECT record_json FROM inbox_entries WHERE viewer = ? AND exchange_id = ?', viewer, exchangeId);
+        },
+        async transitionInbox(viewer, exchangeId, event) {
+            const entry = await this.getInboxEntry(viewer, exchangeId);
+            if (!entry)
+                return null;
+            const result = applyInboxTransition(entry, event);
+            if (result.ok)
+                await this.putInboxEntry(result.next);
+            return result;
+        },
+    };
+    return store;
+}
+/** The lifecycle facet of a stored interaction, for the machine to operate on. */
+function lifecycleOf(record) {
+    return {
+        interactionId: record.interactionId,
+        state: lifecycleStateOf(record),
+        principal: record.principal,
+        participations: record.participations,
+        updatedAt: record.updatedAt,
+    };
+}
+function lifecycleStateOf(record) {
+    return record.lifecycleState;
+}
+//# sourceMappingURL=interaction-store.js.map

package/dist/cloudflare/interaction-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction-store.js","sourceRoot":"","sources":["../../src/cloudflare/interaction-store.ts"],"names":[],"mappings":"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"}

package/dist/cloudflare/orchestration-runtime.d.ts

@@ -1,20 +1,31 @@
 import type { Vault } from '@agenticprimitives/vault';
 import { type Intent, type Planner, type RunResult, type ToolInvoker, type ToolSpec } from '@agenticprimitives/orchestration';
-import type { GatewayToolRegistry } from './gateway-tools.js';
+import type { GatewayTool, GatewayToolRegistry } from './gateway-tools.js';
 /** The co-resident tools as the planner's tool catalog (id + description; the plan may only reference these). */
 export declare function gatewayToolSpecs(registry: GatewayToolRegistry): ToolSpec[];
+/**
+ * The per-step gate (spec 445 §3.4, audit DATA-4). Called for EVERY planned step, with the concrete tool
+ * and the resolved arguments, BEFORE the tool runs; it throws to refuse. REQUIRED — the planner's input
+ * is by design a peer's text, so a step is authorized where it is used, never by having been planned.
+ * `PrincipalGatewayDO.orchestrate` supplies the §3a gate here (caveat pass B per step, request id for a
+ * write); a caller with no gate to offer has no business binding vault tools to a planner.
+ */
+export type GatewayStepGate = (tool: GatewayTool, args: Record<string, unknown>) => Promise<void>;
 /** Bind the co-resident tool registry as an orchestration `ToolInvoker`: each planned step dispatches to a
- *  DO tool, run over `vault` under `principal`. Fail-closed on an unknown tool (the plan is validated against
- *  the tool catalog too, but this is the last line). */
+ *  DO tool, run over `vault` under `principal` — after `authorizeStep` has passed it. Fail-closed on an
+ *  unknown tool (the plan is validated against the tool catalog too, but this is the last line). */
 export declare function bindGatewayToolInvoker(opts: {
     registry: GatewayToolRegistry;
     vault: Vault;
     principal: string;
+    authorizeStep: GatewayStepGate;
 }): ToolInvoker;
 /**
  * Run a T2 intent to completion over the co-resident tools. `planner` is injected (LLM adapter in prod, the
- * deterministic rule-based planner in tests). The loop is bounded (`maxSteps`); authority is NOT the loop's
- * concern — the tools run under the already-verified `principal` (ADR-0041). Returns the orchestration
+ * deterministic rule-based planner in tests). The loop is bounded (`maxSteps`). The loop itself decides no
+ * authority — `principal` is the VERIFIED verdict's principal and every step passes `authorizeStep`
+ * (ADR-0041; spec 445 §3.4). `tools` narrows the catalog the planner is shown (e.g. read tools only when
+ * the run carries no request id); the invoker's gate still stands behind it. Returns the orchestration
  * `RunResult` (outcome + observations + composed result) the DO records onto the exchange stream.
  */
 export declare function runGatewayOrchestration(intent: Intent, opts: {
@@ -22,6 +33,9 @@ export declare function runGatewayOrchestration(intent: Intent, opts: {
     registry: GatewayToolRegistry;
     vault: Vault;
     principal: string;
+    authorizeStep: GatewayStepGate;
+    /** The subset of the registry offered to the planner. Default: all of it. */
+    tools?: ToolSpec[];
     maxSteps?: number;
     maxReplans?: number;
 }): Promise<RunResult>;

package/dist/cloudflare/orchestration-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestration-runtime.d.ts","sourceRoot":"","sources":["../../src/cloudflare/orchestration-runtime.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAa,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACzI,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,iHAAiH;AACjH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,QAAQ,EAAE,CAK1E;AAED;;wDAEwD;AACxD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAM5H;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACjI,OAAO,CAAC,SAAS,CAAC,CAQpB"}
+{"version":3,"file":"orchestration-runtime.d.ts","sourceRoot":"","sources":["../../src/cloudflare/orchestration-runtime.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAa,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACzI,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE3E,iHAAiH;AACjH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,QAAQ,EAAE,CAK1E;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAElG;;oGAEoG;AACpG,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,eAAe,CAAC;CAChC,GAAG,WAAW,CAQd;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IACJ,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,eAAe,CAAC;IAC/B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,OAAO,CAAC,SAAS,CAAC,CAQpB"}

package/dist/cloudflare/orchestration-runtime.js

@@ -7,27 +7,32 @@ export function gatewayToolSpecs(registry) {
     }));
 }
 /** Bind the co-resident tool registry as an orchestration `ToolInvoker`: each planned step dispatches to a
- *  DO tool, run over `vault` under `principal`. Fail-closed on an unknown tool (the plan is validated against
- *  the tool catalog too, but this is the last line). */
+ *  DO tool, run over `vault` under `principal` — after `authorizeStep` has passed it. Fail-closed on an
+ *  unknown tool (the plan is validated against the tool catalog too, but this is the last line). */
 export function bindGatewayToolInvoker(opts) {
+    if (typeof opts.authorizeStep !== 'function')
+        throw new Error('orchestration: authorizeStep is required (no gate ⇒ no tools)');
     return async (toolId, args) => {
         const tool = opts.registry.get(toolId);
         if (!tool)
             throw new Error(`orchestration: unknown tool ${toolId}`);
+        await opts.authorizeStep(tool, args);
         return tool.run({ principal: opts.principal, vault: opts.vault, args });
     };
 }
 /**
  * Run a T2 intent to completion over the co-resident tools. `planner` is injected (LLM adapter in prod, the
- * deterministic rule-based planner in tests). The loop is bounded (`maxSteps`); authority is NOT the loop's
- * concern — the tools run under the already-verified `principal` (ADR-0041). Returns the orchestration
+ * deterministic rule-based planner in tests). The loop is bounded (`maxSteps`). The loop itself decides no
+ * authority — `principal` is the VERIFIED verdict's principal and every step passes `authorizeStep`
+ * (ADR-0041; spec 445 §3.4). `tools` narrows the catalog the planner is shown (e.g. read tools only when
+ * the run carries no request id); the invoker's gate still stands behind it. Returns the orchestration
  * `RunResult` (outcome + observations + composed result) the DO records onto the exchange stream.
  */
 export function runGatewayOrchestration(intent, opts) {
     return runIntent(intent, {
         planner: opts.planner,
-        tools: gatewayToolSpecs(opts.registry),
-        invoke: bindGatewayToolInvoker({ registry: opts.registry, vault: opts.vault, principal: opts.principal }),
+        tools: opts.tools ?? gatewayToolSpecs(opts.registry),
+        invoke: bindGatewayToolInvoker({ registry: opts.registry, vault: opts.vault, principal: opts.principal, authorizeStep: opts.authorizeStep }),
         maxSteps: opts.maxSteps,
         maxReplans: opts.maxReplans,
     });

package/dist/cloudflare/orchestration-runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"orchestration-runtime.js","sourceRoot":"","sources":["../../src/cloudflare/orchestration-runtime.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,SAAS,EAA8E,MAAM,kCAAkC,CAAC;AAGzI,iHAAiH;AACjH,MAAM,UAAU,gBAAgB,CAAC,QAA6B;IAC5D,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACjC,EAAE,EAAE,CAAC,CAAC,IAAI;QACV,WAAW,EAAE,GAAG,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,2BAA2B,CAAC,CAAC,IAAI,GAAG;KAC3F,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;wDAEwD;AACxD,MAAM,UAAU,sBAAsB,CAAC,IAAwE;IAC7G,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,MAAM,EAAE,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAc,EACd,IAAkI;IAElI,OAAO,SAAS,CAAC,MAAM,EAAE;QACvB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,EAAE,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC;QACtC,MAAM,EAAE,sBAAsB,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;QACzG,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,UAAU,EAAE,IAAI,CAAC,UAAU;KAC5B,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"orchestration-runtime.js","sourceRoot":"","sources":["../../src/cloudflare/orchestration-runtime.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,SAAS,EAA8E,MAAM,kCAAkC,CAAC;AAGzI,iHAAiH;AACjH,MAAM,UAAU,gBAAgB,CAAC,QAA6B;IAC5D,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACjC,EAAE,EAAE,CAAC,CAAC,IAAI;QACV,WAAW,EAAE,GAAG,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,2BAA2B,CAAC,CAAC,IAAI,GAAG;KAC3F,CAAC,CAAC,CAAC;AACN,CAAC;AAWD;;oGAEoG;AACpG,MAAM,UAAU,sBAAsB,CAAC,IAKtC;IACC,IAAI,OAAO,IAAI,CAAC,aAAa,KAAK,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;IAC/H,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,MAAM,EAAE,CAAC,CAAC;QACpE,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAc,EACd,IAUC;IAED,OAAO,SAAS,CAAC,MAAM,EAAE;QACvB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC;QACpD,MAAM,EAAE,sBAAsB,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC;QAC5I,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,UAAU,EAAE,IAAI,CAAC,UAAU;KAC5B,CAAC,CAAC;AACL,CAAC"}