@cats-inc/cats-platform 0.1.21 → 0.2.8

package/build/server/platform/transports/work-delivery/outbox.js

@@ -0,0 +1,270 @@
+/**
+ * Durable transport delivery outbox (SPEC-114 FR-32..FR-33, FR-42..FR-47).
+ *
+ * This is a narrow, replaceable platform interface rather than a new Core
+ * record family (ADR-112 section 1). Production supplies a transport state
+ * store; isolated tests may keep using the in-memory form.
+ *
+ * Three invariants earn this module its existence:
+ *
+ *  1. one `idempotencyKey` sends at most one external message, across duplicate
+ *     callbacks, retries, and process restarts;
+ *  2. messages for one work item are sent in causal order;
+ *  3. a routine progress message that lost its race against a newer decision or
+ *     terminal message is dropped rather than delivered late.
+ */
+/** Purposes that must never be suppressed by a newer message. */
+const PRIORITY_PURPOSES = new Set([
+    'decision',
+    'result',
+    'publish_result',
+]);
+/** Purposes that are routine and may be coalesced away when stale. */
+const ROUTINE_PURPOSES = new Set([
+    'progress',
+]);
+function isTerminalState(state) {
+    return state === 'sent' || state === 'ambiguous';
+}
+export function createTransportWorkOutbox(options) {
+    const now = options.now ?? (() => new Date());
+    const telemetry = options.telemetry;
+    const rows = new Map();
+    const sequenceByWorkItem = new Map();
+    const inFlight = new Map();
+    const recoveredRows = [
+        ...(options.store?.listDeliveries() ?? []),
+        ...(options.initialRows ?? []),
+    ];
+    for (const recovered of recoveredRows) {
+        // A process that died while `send` was in flight cannot know whether the
+        // transport accepted the message. Preserve that uncertainty; never turn it
+        // into an automatic duplicate after restart.
+        const wasInterrupted = recovered.state === 'sending';
+        const row = wasInterrupted
+            ? {
+                ...recovered,
+                state: 'ambiguous',
+                lastErrorCode: recovered.lastErrorCode ?? 'interrupted_send',
+                updatedAt: now().toISOString(),
+            }
+            : { ...recovered };
+        rows.set(row.idempotencyKey, row);
+        if (wasInterrupted) {
+            options.store?.putDelivery(row);
+        }
+        const highest = sequenceByWorkItem.get(row.workItemId) ?? 0;
+        sequenceByWorkItem.set(row.workItemId, Math.max(highest, row.sequence));
+    }
+    function put(row) {
+        rows.set(row.idempotencyKey, row);
+        options.store?.putDelivery(row);
+    }
+    function nextSequence(workItemId) {
+        const next = (sequenceByWorkItem.get(workItemId) ?? 0) + 1;
+        sequenceByWorkItem.set(workItemId, next);
+        return next;
+    }
+    function listRows(workItemId) {
+        return [...rows.values()]
+            .filter((row) => row.workItemId === workItemId)
+            .sort((left, right) => left.sequence - right.sequence);
+    }
+    /**
+     * A routine progress row is stale once a priority row with a higher sequence
+     * exists, whether or not that row has been sent yet. Waiting for the newer
+     * row to send first would let a slow decision message unblock an obsolete
+     * progress message behind it.
+     */
+    function isStaleRoutine(row) {
+        if (!ROUTINE_PURPOSES.has(row.purpose)) {
+            return false;
+        }
+        return listRows(row.workItemId).some((candidate) => candidate.sequence > row.sequence
+            && (PRIORITY_PURPOSES.has(candidate.purpose) || candidate.purpose === 'progress'));
+    }
+    async function flushRow(row) {
+        if (row.state === 'sent') {
+            telemetry?.record('dedupe_hit', 'update');
+            return { outcome: 'already_sent', row };
+        }
+        if (row.state === 'ambiguous') {
+            return { outcome: 'ambiguous', row };
+        }
+        if (isStaleRoutine(row)) {
+            const suppressed = {
+                ...row,
+                state: 'failed',
+                lastErrorCode: 'suppressed_stale',
+                updatedAt: now().toISOString(),
+            };
+            put(suppressed);
+            return { outcome: 'suppressed_stale', row: suppressed };
+        }
+        const sending = {
+            ...row,
+            state: 'sending',
+            attemptCount: row.attemptCount + 1,
+            updatedAt: now().toISOString(),
+        };
+        put(sending);
+        let result;
+        try {
+            result = await options.send(sending);
+        }
+        catch (error) {
+            result = {
+                ok: false,
+                externalMessageRef: null,
+                errorCode: error instanceof Error ? error.name : 'send_threw',
+                ambiguous: true,
+            };
+        }
+        if (sending.attemptCount > 1) {
+            telemetry?.record('outbox_retry', 'attempt');
+        }
+        if (result.ok) {
+            telemetry?.record('delivery_receipt', 'sent');
+            const sent = {
+                ...sending,
+                state: 'sent',
+                externalMessageRef: result.externalMessageRef,
+                lastErrorCode: null,
+                updatedAt: now().toISOString(),
+                sentAt: now().toISOString(),
+            };
+            put(sent);
+            return { outcome: 'sent', row: sent };
+        }
+        // Ambiguity is terminal for automatic recovery. Only an explicit owner
+        // retry may move it back to pending, because the message may be on the wire.
+        const failed = {
+            ...sending,
+            state: result.ambiguous === true ? 'ambiguous' : 'failed',
+            lastErrorCode: result.errorCode ?? 'send_failed',
+            updatedAt: now().toISOString(),
+        };
+        put(failed);
+        telemetry?.record('delivery_receipt', result.ambiguous === true ? 'ambiguous' : 'failed');
+        return { outcome: result.ambiguous === true ? 'ambiguous' : 'failed', row: failed };
+    }
+    function flushOne(idempotencyKey) {
+        const active = inFlight.get(idempotencyKey);
+        if (active) {
+            return active;
+        }
+        const row = rows.get(idempotencyKey);
+        if (!row) {
+            return Promise.reject(new Error(`Unknown transport work delivery key: ${idempotencyKey}`));
+        }
+        const started = flushRow(row).finally(() => {
+            if (inFlight.get(idempotencyKey) === started) {
+                inFlight.delete(idempotencyKey);
+            }
+        });
+        inFlight.set(idempotencyKey, started);
+        return started;
+    }
+    return {
+        enqueue(input) {
+            const existing = rows.get(input.idempotencyKey);
+            if (existing) {
+                return existing;
+            }
+            const timestamp = now().toISOString();
+            const row = {
+                version: 1,
+                idempotencyKey: input.idempotencyKey,
+                bindingId: input.bindingId,
+                externalConversationRef: input.externalConversationRef,
+                workItemId: input.workItemId,
+                taskId: input.taskId ?? null,
+                runId: input.runId ?? null,
+                purpose: input.purpose,
+                payload: input.payload,
+                state: 'pending',
+                externalMessageRef: null,
+                attemptCount: 0,
+                lastErrorCode: null,
+                sequence: nextSequence(input.workItemId),
+                createdAt: timestamp,
+                updatedAt: timestamp,
+                sentAt: null,
+            };
+            put(row);
+            return row;
+        },
+        flush(idempotencyKey) {
+            return flushOne(idempotencyKey);
+        },
+        async retry(idempotencyKey) {
+            const active = inFlight.get(idempotencyKey);
+            if (active) {
+                return active;
+            }
+            const row = rows.get(idempotencyKey);
+            if (!row) {
+                throw new Error(`Unknown transport work delivery key: ${idempotencyKey}`);
+            }
+            if (row.state === 'sent') {
+                return { outcome: 'already_sent', row };
+            }
+            const pending = {
+                ...row,
+                state: 'pending',
+                updatedAt: now().toISOString(),
+            };
+            put(pending);
+            return flushOne(idempotencyKey);
+        },
+        async flushWorkItem(workItemId) {
+            const results = [];
+            // Sequential on purpose: causal ordering per work item is a requirement,
+            // not an implementation detail (FR-33).
+            for (const row of listRows(workItemId)) {
+                if (isTerminalState(row.state)) {
+                    continue;
+                }
+                results.push(await flushOne(row.idempotencyKey));
+            }
+            return results;
+        },
+        async recoverPending() {
+            const results = [];
+            const pending = [...rows.values()]
+                .filter((row) => row.state === 'pending')
+                .sort((left, right) => left.createdAt.localeCompare(right.createdAt)
+                || left.sequence - right.sequence);
+            for (const row of pending) {
+                results.push(await flushOne(row.idempotencyKey));
+            }
+            return results;
+        },
+        get(idempotencyKey) {
+            return rows.get(idempotencyKey) ?? null;
+        },
+        list(workItemId) {
+            return listRows(workItemId);
+        },
+        hasDeliveredResult(workItemId) {
+            return listRows(workItemId).some((row) => row.state === 'sent'
+                && (row.purpose === 'result' || row.purpose === 'publish_result'));
+        },
+    };
+}
+/**
+ * Stable idempotency key for one outbound message.
+ *
+ * Every input is either an authoritative id or an owner-visible revision, so
+ * the same logical message recomputes the same key after a restart.
+ */
+export function buildTransportWorkDeliveryKey(input) {
+    return [
+        'twd',
+        input.bindingId,
+        input.workItemId,
+        input.purpose,
+        input.discriminator,
+    ].join(':');
+}
+//# sourceMappingURL=outbox.js.map

package/build/server/platform/transports/work-delivery/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../../../../../src/platform/transports/work-delivery/outbox.ts"],"names":[],"mappings":"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"}

package/build/server/platform/transports/work-delivery/permissionEnvelope.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The permission envelope a transport-originated run executes under
+ * (SPEC-114 FR-4, PLAN-105 Phase 1 / gate G1).
+ *
+ * This replaces the placeholder that treated "a workspace path is configured"
+ * as the whole permission model. Two things were wrong with it, and the second
+ * one mattered more than the first:
+ *
+ *  1. The configured path was never checked against reality. An operator could
+ *     name a directory that does not exist, or claim a plain folder is a repo,
+ *     and the run only discovered it deep inside a provider turn.
+ *
+ *  2. It granted `broad_write`, which classifies as externally-visible,
+ *     destructive, and expensive tools. That silently contradicted the design's
+ *     own rule that execution authorization must not clear a publish gate: the
+ *     provider could have pushed or deployed through its own tools while Cats
+ *     still believed publication was waiting on an owner approval.
+ *
+ * So the envelope here is capped at `narrow_write` — local workspace state — for
+ * every delivery mode. External effects (push, pull request, preview deploy)
+ * never travel on provider tools; they run through the gated delivery API after
+ * an approval, carrying that approval's id. A mode with bigger side effects
+ * needs a *gate*, not a wider grant.
+ */
+import type { CoreDeliveryMode } from '../../../core/types.js';
+import type { SupervisionToolScope } from '../../supervision/contracts.js';
+/** What the runtime actually observed about the configured workspace. */
+export interface TransportWorkWorkspaceCapability {
+    /** The runtime could inspect the path at all. */
+    reachable: boolean;
+    /** The path is a git repository. */
+    repository: boolean;
+    /** Whether the repository has no staged, modified, or untracked files. */
+    clean: boolean | null;
+    /** HEAD observed before admission; later commit evidence is bound to it. */
+    headOid: string | null;
+}
+export declare const TRANSPORT_WORK_PERMISSION_REASONS: readonly ["workspace_not_configured", "workspace_unreachable", "workspace_not_a_repository", "workspace_not_clean"];
+export type TransportWorkPermissionReason = (typeof TRANSPORT_WORK_PERMISSION_REASONS)[number];
+export interface TransportWorkPermissionEnvelope {
+    /** Granted to the supervision boundary. Never wider than `narrow_write`. */
+    toolScope: SupervisionToolScope;
+    sufficient: boolean;
+    reasons: TransportWorkPermissionReason[];
+}
+export interface TransportWorkPermissionEnvelopeInput {
+    workspacePath: string | null;
+    /**
+     * The runtime's observation, or `null` when it could not be obtained — an
+     * unreachable runtime is reported as an unusable workspace rather than
+     * optimistically assumed usable.
+     */
+    workspace: TransportWorkWorkspaceCapability | null;
+    deliveryMode: CoreDeliveryMode | null;
+}
+export declare function resolveTransportWorkPermissionEnvelope(input: TransportWorkPermissionEnvelopeInput): TransportWorkPermissionEnvelope;
+//# sourceMappingURL=permissionEnvelope.d.ts.map

package/build/server/platform/transports/work-delivery/permissionEnvelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissionEnvelope.d.ts","sourceRoot":"","sources":["../../../../../src/platform/transports/work-delivery/permissionEnvelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,yEAAyE;AACzE,MAAM,WAAW,gCAAgC;IAC/C,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;IACnB,oCAAoC;IACpC,UAAU,EAAE,OAAO,CAAC;IACpB,0EAA0E;IAC1E,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,eAAO,MAAM,iCAAiC,qHAKpC,CAAC;AAEX,MAAM,MAAM,6BAA6B,GACvC,CAAC,OAAO,iCAAiC,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,MAAM,WAAW,+BAA+B;IAC9C,4EAA4E;IAC5E,SAAS,EAAE,oBAAoB,CAAC;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,6BAA6B,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,oCAAoC;IACnD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,SAAS,EAAE,gCAAgC,GAAG,IAAI,CAAC;IACnD,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACvC;AAaD,wBAAgB,sCAAsC,CACpD,KAAK,EAAE,oCAAoC,GAC1C,+BAA+B,CAgCjC"}

package/build/server/platform/transports/work-delivery/permissionEnvelope.js

@@ -0,0 +1,74 @@
+/**
+ * The permission envelope a transport-originated run executes under
+ * (SPEC-114 FR-4, PLAN-105 Phase 1 / gate G1).
+ *
+ * This replaces the placeholder that treated "a workspace path is configured"
+ * as the whole permission model. Two things were wrong with it, and the second
+ * one mattered more than the first:
+ *
+ *  1. The configured path was never checked against reality. An operator could
+ *     name a directory that does not exist, or claim a plain folder is a repo,
+ *     and the run only discovered it deep inside a provider turn.
+ *
+ *  2. It granted `broad_write`, which classifies as externally-visible,
+ *     destructive, and expensive tools. That silently contradicted the design's
+ *     own rule that execution authorization must not clear a publish gate: the
+ *     provider could have pushed or deployed through its own tools while Cats
+ *     still believed publication was waiting on an owner approval.
+ *
+ * So the envelope here is capped at `narrow_write` — local workspace state — for
+ * every delivery mode. External effects (push, pull request, preview deploy)
+ * never travel on provider tools; they run through the gated delivery API after
+ * an approval, carrying that approval's id. A mode with bigger side effects
+ * needs a *gate*, not a wider grant.
+ */
+export const TRANSPORT_WORK_PERMISSION_REASONS = [
+    'workspace_not_configured',
+    'workspace_unreachable',
+    'workspace_not_a_repository',
+    'workspace_not_clean',
+];
+/**
+ * Delivery modes whose evidence is a commit, and which therefore cannot run
+ * against a directory that is not a repository.
+ */
+const REPO_BACKED_MODES = new Set([
+    'commit_only',
+    'push_branch',
+    'pr_with_checks',
+    'deploy_preview',
+]);
+export function resolveTransportWorkPermissionEnvelope(input) {
+    if (input.workspacePath === null) {
+        return { toolScope: 'none', sufficient: false, reasons: ['workspace_not_configured'] };
+    }
+    if (input.workspace === null || !input.workspace.reachable) {
+        // A path we cannot inspect is a path we must not hand write tools for.
+        return { toolScope: 'none', sufficient: false, reasons: ['workspace_unreachable'] };
+    }
+    if (input.deliveryMode !== null
+        && REPO_BACKED_MODES.has(input.deliveryMode)
+        && !input.workspace.repository) {
+        // Readable, so the run could still be inspected, but it can never produce
+        // the commit this mode's completion evidence requires.
+        return {
+            toolScope: 'read_only',
+            sufficient: false,
+            reasons: ['workspace_not_a_repository'],
+        };
+    }
+    if (input.deliveryMode !== null
+        && REPO_BACKED_MODES.has(input.deliveryMode)
+        && input.workspace.clean !== true) {
+        // The runtime commit endpoint cannot distinguish changes created by this
+        // run from files that were already present. Never let transport work claim
+        // ownership of an operator's dirty worktree.
+        return {
+            toolScope: 'read_only',
+            sufficient: false,
+            reasons: ['workspace_not_clean'],
+        };
+    }
+    return { toolScope: 'narrow_write', sufficient: true, reasons: [] };
+}
+//# sourceMappingURL=permissionEnvelope.js.map

package/build/server/platform/transports/work-delivery/permissionEnvelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissionEnvelope.js","sourceRoot":"","sources":["../../../../../src/platform/transports/work-delivery/permissionEnvelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAiBH,MAAM,CAAC,MAAM,iCAAiC,GAAG;IAC/C,0BAA0B;IAC1B,uBAAuB;IACvB,4BAA4B;IAC5B,qBAAqB;CACb,CAAC;AAuBX;;;GAGG;AACH,MAAM,iBAAiB,GAAkC,IAAI,GAAG,CAAC;IAC/D,aAAa;IACb,aAAa;IACb,gBAAgB;IAChB,gBAAgB;CACjB,CAAC,CAAC;AAEH,MAAM,UAAU,sCAAsC,CACpD,KAA2C;IAE3C,IAAI,KAAK,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;QACjC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,0BAA0B,CAAC,EAAE,CAAC;IACzF,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC;QAC3D,uEAAuE;QACvE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,uBAAuB,CAAC,EAAE,CAAC;IACtF,CAAC;IACD,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI;WAC1B,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC;WACzC,CAAC,KAAK,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;QACjC,0EAA0E;QAC1E,uDAAuD;QACvD,OAAO;YACL,SAAS,EAAE,WAAW;YACtB,UAAU,EAAE,KAAK;YACjB,OAAO,EAAE,CAAC,4BAA4B,CAAC;SACxC,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI;WAC1B,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC;WACzC,KAAK,CAAC,SAAS,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QACpC,yEAAyE;QACzE,2EAA2E;QAC3E,6CAA6C;QAC7C,OAAO;YACL,SAAS,EAAE,WAAW;YACtB,UAAU,EAAE,KAAK;YACjB,OAAO,EAAE,CAAC,qBAAqB,CAAC;SACjC,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AACtE,CAAC"}

package/build/server/platform/transports/work-delivery/port.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The seam between a transport and the golden path (ADR-112 section 4).
+ *
+ * The transport hands over raw external facts and learns only whether the
+ * update was consumed. Everything the product owns — readiness, scope,
+ * authorization, policy, outbound copy — stays behind this interface, which is
+ * why `platform/` can define it without importing any product.
+ *
+ * Outbound messages are *not* returned from these calls. The product enqueues
+ * them on its own durable outbox, so a transport that crashes between "command
+ * handled" and "reply sent" recovers by flushing the outbox rather than by
+ * replaying the command.
+ */
+export interface TransportWorkCommandInput {
+    bindingId: string;
+    conversationId: string;
+    /** Opaque reference to the external user that sent the request. */
+    externalUserRef: string;
+    /** Opaque reference to the external chat. Also the delivery destination. */
+    externalConversationRef: string;
+    externalUpdateRef: string;
+    externalMessageRef: string | null;
+    goal: string;
+    locale: string | null;
+}
+export interface TransportWorkCallbackInput {
+    callbackData: string;
+    bindingId: string;
+    conversationId: string;
+    externalUserRef: string;
+    externalConversationRef: string;
+    /** The external callback id. Distinguishes owner events, never scopes. */
+    ownerEventRef: string;
+    locale: string | null;
+}
+export interface TransportWorkRefusalInput {
+    bindingId: string;
+    conversationId: string;
+    externalConversationRef: string;
+    externalUpdateRef: string;
+    reasonKey: string;
+    locale: string | null;
+}
+export type TransportWorkHandledOutcome = 'accepted' | 'not_ready' | 'admitted' | 'already_admitted' | 'cancelled' | 'published' | 'publish_denied' | 'publish_blocked' | 'retried' | 'resumed' | 'rejected' | 'refused';
+export interface TransportWorkHandledResult {
+    handled: boolean;
+    outcome: TransportWorkHandledOutcome;
+    workItemId: string | null;
+    /** Rejection reason code when `outcome` is `rejected`; for diagnostics. */
+    rejection: string | null;
+}
+export interface TransportWorkGoldenPathPort {
+    /** True when this callback belongs to the golden path and nothing else. */
+    ownsCallback(callbackData: string): boolean;
+    handleWorkCommand(input: TransportWorkCommandInput): Promise<TransportWorkHandledResult>;
+    handleActionCallback(input: TransportWorkCallbackInput): Promise<TransportWorkHandledResult>;
+    /** Explains an input the first slice cannot ingest, e.g. a bare attachment. */
+    refuse(input: TransportWorkRefusalInput): Promise<TransportWorkHandledResult>;
+}
+//# sourceMappingURL=port.d.ts.map

package/build/server/platform/transports/work-delivery/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../../../../src/platform/transports/work-delivery/port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,uBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,uBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,MAAM,2BAA2B,GACnC,UAAU,GACV,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,WAAW,GACX,WAAW,GACX,gBAAgB,GAChB,iBAAiB,GACjB,SAAS,GACT,SAAS,GACT,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,2BAA2B,CAAC;IACrC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,2EAA2E;IAC3E,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5C,iBAAiB,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACzF,oBAAoB,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAC7F,+EAA+E;IAC/E,MAAM,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC/E"}

package/build/server/platform/transports/work-delivery/port.js

@@ -0,0 +1,15 @@
+/**
+ * The seam between a transport and the golden path (ADR-112 section 4).
+ *
+ * The transport hands over raw external facts and learns only whether the
+ * update was consumed. Everything the product owns — readiness, scope,
+ * authorization, policy, outbound copy — stays behind this interface, which is
+ * why `platform/` can define it without importing any product.
+ *
+ * Outbound messages are *not* returned from these calls. The product enqueues
+ * them on its own durable outbox, so a transport that crashes between "command
+ * handled" and "reply sent" recovers by flushing the outbox rather than by
+ * replaying the command.
+ */
+export {};
+//# sourceMappingURL=port.js.map

package/build/server/platform/transports/work-delivery/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../../../../src/platform/transports/work-delivery/port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/build/server/platform/transports/work-delivery/proposal.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Versioned scope proposals (SPEC-114 FR-15..FR-19).
+ *
+ * The digest is the load-bearing part. An owner confirms a specific block of
+ * text; binding the authorization to a hash of exactly the execution-relevant
+ * fields is what makes "Start work" mean "run *that*" rather than "run whatever
+ * the work item says now".
+ */
+import type { CoreDeliveryGate, CoreDeliveryMode } from '../../../core/types.js';
+import type { TransportWorkProposalV1 } from './contracts.js';
+export interface BuildTransportWorkProposalInput {
+    revision: number;
+    goal: string;
+    targetLabel: string;
+    projectId: string | null;
+    workspacePath: string | null;
+    acceptanceCriteria: readonly string[];
+    deliveryMode: CoreDeliveryMode;
+    deliveryGates: readonly CoreDeliveryGate[];
+    sideEffects: readonly string[];
+    openQuestion: string | null;
+    createdAt: Date;
+}
+export declare function buildTransportWorkProposalDigest(input: BuildTransportWorkProposalInput): string;
+export declare function buildTransportWorkProposal(input: BuildTransportWorkProposalInput): TransportWorkProposalV1;
+/**
+ * True when a new proposal changes what would execute, which is the trigger for
+ * bumping the revision and invalidating outstanding action tokens (FR-17).
+ */
+export declare function isTransportWorkProposalMateriallyChanged(previous: TransportWorkProposalV1 | null, next: TransportWorkProposalV1): boolean;
+//# sourceMappingURL=proposal.d.ts.map

package/build/server/platform/transports/work-delivery/proposal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal.d.ts","sourceRoot":"","sources":["../../../../../src/platform/transports/work-delivery/proposal.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAE9D,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,YAAY,EAAE,gBAAgB,CAAC;IAC/B,aAAa,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC3C,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,IAAI,CAAC;CACjB;AAsBD,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,+BAA+B,GACrC,MAAM,CAKR;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,+BAA+B,GACrC,uBAAuB,CAgBzB;AAED;;;GAGG;AACH,wBAAgB,wCAAwC,CACtD,QAAQ,EAAE,uBAAuB,GAAG,IAAI,EACxC,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAET"}

package/build/server/platform/transports/work-delivery/proposal.js

@@ -0,0 +1,59 @@
+/**
+ * Versioned scope proposals (SPEC-114 FR-15..FR-19).
+ *
+ * The digest is the load-bearing part. An owner confirms a specific block of
+ * text; binding the authorization to a hash of exactly the execution-relevant
+ * fields is what makes "Start work" mean "run *that*" rather than "run whatever
+ * the work item says now".
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Fields that change what actually executes.
+ *
+ * `createdAt` and `openQuestion` are excluded on purpose: re-rendering the same
+ * scope at a later time, or resolving a question without changing the plan,
+ * must not invalidate a confirmation the owner already saw.
+ */
+function buildDigestSource(input) {
+    return JSON.stringify([
+        input.goal.trim(),
+        input.targetLabel.trim(),
+        input.projectId,
+        input.workspacePath,
+        [...input.acceptanceCriteria].map((criterion) => criterion.trim()),
+        input.deliveryMode,
+        [...input.deliveryGates].sort(),
+        [...input.sideEffects].map((effect) => effect.trim()).sort(),
+    ]);
+}
+export function buildTransportWorkProposalDigest(input) {
+    return createHash('sha256')
+        .update(buildDigestSource(input))
+        .digest('hex')
+        .slice(0, 32);
+}
+export function buildTransportWorkProposal(input) {
+    return {
+        version: 1,
+        revision: input.revision,
+        digest: buildTransportWorkProposalDigest(input),
+        goal: input.goal.trim(),
+        targetLabel: input.targetLabel.trim(),
+        projectId: input.projectId,
+        workspacePath: input.workspacePath,
+        acceptanceCriteria: [...input.acceptanceCriteria].map((criterion) => criterion.trim()),
+        deliveryMode: input.deliveryMode,
+        deliveryGates: [...input.deliveryGates],
+        sideEffects: [...input.sideEffects],
+        openQuestion: input.openQuestion,
+        createdAt: input.createdAt.toISOString(),
+    };
+}
+/**
+ * True when a new proposal changes what would execute, which is the trigger for
+ * bumping the revision and invalidating outstanding action tokens (FR-17).
+ */
+export function isTransportWorkProposalMateriallyChanged(previous, next) {
+    return previous === null || previous.digest !== next.digest;
+}
+//# sourceMappingURL=proposal.js.map

package/build/server/platform/transports/work-delivery/proposal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal.js","sourceRoot":"","sources":["../../../../../src/platform/transports/work-delivery/proposal.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAmBzC;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAC,KAAsC;IAC/D,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE;QACjB,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE;QACxB,KAAK,CAAC,SAAS;QACf,KAAK,CAAC,aAAa;QACnB,CAAC,GAAG,KAAK,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QAClE,KAAK,CAAC,YAAY;QAClB,CAAC,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,IAAI,EAAE;QAC/B,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;KAC7D,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC9C,KAAsC;IAEtC,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;SAChC,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,KAAsC;IAEtC,OAAO;QACL,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,gCAAgC,CAAC,KAAK,CAAC;QAC/C,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE;QACvB,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE;QACrC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,kBAAkB,EAAE,CAAC,GAAG,KAAK,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QACtF,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,aAAa,EAAE,CAAC,GAAG,KAAK,CAAC,aAAa,CAAC;QACvC,WAAW,EAAE,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC;QACnC,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,EAAE;KACzC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wCAAwC,CACtD,QAAwC,EACxC,IAA6B;IAE7B,OAAO,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC;AAC9D,CAAC"}