@cats-inc/cats-platform 0.1.10 → 0.2.8

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"}

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

@@ -0,0 +1,61 @@
+/**
+ * Shared delegation-readiness evaluator (SPEC-114 FR-1..FR-5, PLAN-105 Phase 1).
+ *
+ * Telegram and Desktop must answer "can this binding accept work right now?"
+ * with the same reason codes. Duplicating the rules in a transport handler and
+ * again in a settings page is how a bot ends up claiming work is queued while
+ * Desktop shows a missing provider, so both call this.
+ */
+import type { CoreDeliveryGate, CoreDeliveryMode } from '../../../core/types.js';
+import type { TransportWorkPermissionEnvelope } from './permissionEnvelope.js';
+import type { TransportWorkReadiness } from './contracts.js';
+/**
+ * Facts the evaluator needs. Every field is a resolved observation rather than
+ * a service handle, so the evaluator stays pure and both callers can assemble
+ * it from whatever they already hold.
+ */
+export interface TransportWorkReadinessInput {
+    bindingEnabled: boolean;
+    /** Polling or webhook ingress is currently healthy. */
+    bindingHealthy: boolean;
+    /** The external user is the authorized owner for this binding. */
+    ownerAuthorized: boolean;
+    boundCatId: string | null;
+    /** Resolved provider/model execution target for the bound Cat. */
+    executionTargetId: string | null;
+    /** A provider capability profile has been resolved (not merely defaulted). */
+    capabilityProfileResolved: boolean;
+    /** Absolute workspace/project root the work would run against. */
+    workspacePath: string | null;
+    /**
+     * The resolved permission envelope, not a summary of it. Its reasons become
+     * blockers directly so Desktop can say *which* prerequisite is missing
+     * instead of "permissions".
+     */
+    permission: TransportWorkPermissionEnvelope;
+    deliveryMode: CoreDeliveryMode | null;
+    deliveryGates: readonly CoreDeliveryGate[] | null;
+    /**
+     * Desktop background service is running. A local-first binding cannot honour
+     * work while the host is asleep, and FR-5 forbids implying otherwise.
+     */
+    backgroundServiceAvailable: boolean;
+}
+/**
+ * Evaluates every prerequisite and reports *all* blockers rather than the first.
+ *
+ * Reporting one at a time turns setup into a guessing game where each fix
+ * reveals the next missing piece.
+ */
+export declare function evaluateTransportWorkReadiness(input: TransportWorkReadinessInput): TransportWorkReadiness;
+/**
+ * Default delivery mode for a target (PLAN-105 Phase 0 open question, resolved
+ * by owner direction): a repo workspace commits, anything else produces an
+ * artifact. The proposal must still show the resolved mode before confirmation,
+ * so this is a default and never a silent decision.
+ */
+export declare function resolveDefaultDeliveryMode(input: {
+    workspacePath: string | null;
+    isRepo: boolean;
+}): CoreDeliveryMode;
+//# sourceMappingURL=readiness.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../../../../src/platform/transports/work-delivery/readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,KAAK,EACV,+BAA+B,EAEhC,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,sBAAsB,EAGvB,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,cAAc,EAAE,OAAO,CAAC;IACxB,uDAAuD;IACvD,cAAc,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,8EAA8E;IAC9E,yBAAyB,EAAE,OAAO,CAAC;IACnC,kEAAkE;IAClE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,UAAU,EAAE,+BAA+B,CAAC;IAC5C,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACtC,aAAa,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CAAC;IAClD;;;OAGG;IACH,0BAA0B,EAAE,OAAO,CAAC;CACrC;AA8ED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,2BAA2B,GACjC,sBAAsB,CAgCxB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,gBAAgB,CAEnB"}

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

@@ -0,0 +1,123 @@
+/**
+ * Shared delegation-readiness evaluator (SPEC-114 FR-1..FR-5, PLAN-105 Phase 1).
+ *
+ * Telegram and Desktop must answer "can this binding accept work right now?"
+ * with the same reason codes. Duplicating the rules in a transport handler and
+ * again in a settings page is how a bot ends up claiming work is queued while
+ * Desktop shows a missing provider, so both call this.
+ */
+/**
+ * Remediation copy is referenced by key, never inlined: FR-3 requires localized
+ * remediation, and a raw English string here would bypass product i18n.
+ */
+const REMEDIATION = {
+    binding_disabled: {
+        remediationKey: 'workDelivery.readiness.bindingDisabled',
+        remediationPath: '/settings/chat',
+    },
+    binding_unhealthy: {
+        remediationKey: 'workDelivery.readiness.bindingUnhealthy',
+        remediationPath: '/settings/chat',
+    },
+    owner_not_authorized: {
+        remediationKey: 'workDelivery.readiness.ownerNotAuthorized',
+        remediationPath: '/settings/work',
+    },
+    cat_not_bound: {
+        remediationKey: 'workDelivery.readiness.catNotBound',
+        remediationPath: '/settings/chat',
+    },
+    execution_target_missing: {
+        remediationKey: 'workDelivery.readiness.executionTargetMissing',
+        remediationPath: '/settings/assistants',
+    },
+    capability_profile_missing: {
+        remediationKey: 'workDelivery.readiness.capabilityProfileMissing',
+        remediationPath: '/settings/assistants',
+    },
+    workspace_missing: {
+        remediationKey: 'workDelivery.readiness.workspaceMissing',
+        remediationPath: '/settings/work',
+    },
+    workspace_unreachable: {
+        remediationKey: 'workDelivery.readiness.workspaceUnreachable',
+        remediationPath: '/settings/work',
+    },
+    workspace_not_a_repository: {
+        remediationKey: 'workDelivery.readiness.workspaceNotARepository',
+        remediationPath: '/settings/work',
+    },
+    workspace_not_clean: {
+        remediationKey: 'workDelivery.readiness.workspaceNotClean',
+        remediationPath: '/workspaces',
+    },
+    delivery_policy_unresolved: {
+        remediationKey: 'workDelivery.readiness.deliveryPolicyUnresolved',
+        remediationPath: '/settings/work',
+    },
+    background_service_unavailable: {
+        remediationKey: 'workDelivery.readiness.backgroundServiceUnavailable',
+        remediationPath: '/settings/desktop',
+    },
+};
+/**
+ * Permission reasons are readiness blockers in their own right. Collapsing them
+ * into one "permissions" code is what made the old surface unactionable.
+ */
+const PERMISSION_BLOCKERS = {
+    workspace_not_configured: 'workspace_missing',
+    workspace_unreachable: 'workspace_unreachable',
+    workspace_not_a_repository: 'workspace_not_a_repository',
+    workspace_not_clean: 'workspace_not_clean',
+};
+function blocker(reason) {
+    return { reason, ...REMEDIATION[reason] };
+}
+/**
+ * Evaluates every prerequisite and reports *all* blockers rather than the first.
+ *
+ * Reporting one at a time turns setup into a guessing game where each fix
+ * reveals the next missing piece.
+ */
+export function evaluateTransportWorkReadiness(input) {
+    const blockers = [];
+    if (!input.bindingEnabled) {
+        blockers.push(blocker('binding_disabled'));
+    }
+    else if (!input.bindingHealthy) {
+        // Only meaningful for an enabled binding; a disabled one is not "unhealthy".
+        blockers.push(blocker('binding_unhealthy'));
+    }
+    if (!input.ownerAuthorized) {
+        blockers.push(blocker('owner_not_authorized'));
+    }
+    if (input.boundCatId === null) {
+        blockers.push(blocker('cat_not_bound'));
+    }
+    if (input.executionTargetId === null) {
+        blockers.push(blocker('execution_target_missing'));
+    }
+    if (!input.capabilityProfileResolved) {
+        blockers.push(blocker('capability_profile_missing'));
+    }
+    for (const reason of input.permission.reasons) {
+        blockers.push(blocker(PERMISSION_BLOCKERS[reason]));
+    }
+    if (input.deliveryMode === null || input.deliveryGates === null) {
+        blockers.push(blocker('delivery_policy_unresolved'));
+    }
+    if (!input.backgroundServiceAvailable) {
+        blockers.push(blocker('background_service_unavailable'));
+    }
+    return { ready: blockers.length === 0, blockers };
+}
+/**
+ * Default delivery mode for a target (PLAN-105 Phase 0 open question, resolved
+ * by owner direction): a repo workspace commits, anything else produces an
+ * artifact. The proposal must still show the resolved mode before confirmation,
+ * so this is a default and never a silent decision.
+ */
+export function resolveDefaultDeliveryMode(input) {
+    return input.workspacePath !== null && input.isRepo ? 'commit_only' : 'artifact_only';
+}
+//# sourceMappingURL=readiness.js.map

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

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

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

@@ -0,0 +1,43 @@
+/**
+ * Golden-path stage projection (ADR-112 section 2, SPEC-114 FR-49).
+ *
+ * This is a pure derivation from authoritative Cats Core records plus transport
+ * receipts. It holds no state of its own, which is what keeps it from becoming
+ * the second state machine ADR-112 forbids: every call recomputes the stage
+ * from scratch, so it cannot drift away from Core.
+ */
+import type { CoreArtifactRecord, CoreDeliveryGate, CoreDeliveryMode, CoreOrchestrationOutcomeRecord, CoreRunRecord, CoreTaskRecord, CoreWorkItemRecord } from '../../../core/types.js';
+import type { TransportWorkAction, TransportWorkProposalV1, TransportWorkStage } from './contracts.js';
+import type { TransportWorkDeliveryV1 } from './contracts.js';
+export interface TransportWorkStageInput {
+    workItem: CoreWorkItemRecord;
+    proposal: TransportWorkProposalV1 | null;
+    task: CoreTaskRecord | null;
+    run: CoreRunRecord | null;
+    outcome: CoreOrchestrationOutcomeRecord | null;
+    artifacts: readonly CoreArtifactRecord[];
+    /** Commit evidence for repository-backed modes; null for `artifact_only`. */
+    commitId: string | null;
+    /** Gates that still require an owner decision before publication. */
+    outstandingGates: readonly CoreDeliveryGate[];
+    deliveryRows: readonly TransportWorkDeliveryV1[];
+    /** True when the supervised run is waiting on an owner decision. */
+    awaitingOwnerDecision: boolean;
+}
+export interface TransportWorkStageProjection {
+    stage: TransportWorkStage;
+    /** Why the stage is what it is; surfaced in Desktop and diagnostics. */
+    rationale: string;
+    allowedActions: TransportWorkAction[];
+    deliveryMode: CoreDeliveryMode | null;
+    outstandingGates: CoreDeliveryGate[];
+}
+/**
+ * Derives the owner-visible stage.
+ *
+ * Order matters: terminal states win over progress states, and a persisted
+ * delivery receipt wins over everything, because `delivered` is defined by the
+ * receipt rather than by the Run (ADR-112 section 6).
+ */
+export declare function projectTransportWorkStage(input: TransportWorkStageInput): TransportWorkStageProjection;
+//# sourceMappingURL=stageProjection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stageProjection.d.ts","sourceRoot":"","sources":["../../../../../src/platform/transports/work-delivery/stageProjection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEV,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,8BAA8B,EAC9B,aAAa,EACb,cAAc,EACd,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAE9D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACzC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,GAAG,EAAE,aAAa,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,8BAA8B,GAAG,IAAI,CAAC;IAC/C,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACzC,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qEAAqE;IACrE,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,YAAY,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACjD,oEAAoE;IACpE,qBAAqB,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,kBAAkB,CAAC;IAC1B,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,mBAAmB,EAAE,CAAC;IACtC,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACtC,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;CACtC;AAyBD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,uBAAuB,GAC7B,4BAA4B,CA8G9B"}

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

@@ -0,0 +1,132 @@
+/**
+ * Golden-path stage projection (ADR-112 section 2, SPEC-114 FR-49).
+ *
+ * This is a pure derivation from authoritative Cats Core records plus transport
+ * receipts. It holds no state of its own, which is what keeps it from becoming
+ * the second state machine ADR-112 forbids: every call recomputes the stage
+ * from scratch, so it cannot drift away from Core.
+ */
+function hasSentResult(rows) {
+    return rows.some((row) => row.state === 'sent'
+        && (row.purpose === 'result' || row.purpose === 'publish_result'));
+}
+function hasAcceptedResultEvidence(input) {
+    if (input.outcome === null || input.outcome.status !== 'succeeded') {
+        return false;
+    }
+    if (input.proposal !== null && input.proposal.deliveryMode !== 'artifact_only') {
+        return input.commitId !== null;
+    }
+    return input.artifacts.some((artifact) => artifact.status === 'ready' || artifact.status === 'published');
+}
+function isOwnerApproved(status) {
+    return status === 'approved';
+}
+/**
+ * Derives the owner-visible stage.
+ *
+ * Order matters: terminal states win over progress states, and a persisted
+ * delivery receipt wins over everything, because `delivered` is defined by the
+ * receipt rather than by the Run (ADR-112 section 6).
+ */
+export function projectTransportWorkStage(input) {
+    const deliveryMode = input.proposal?.deliveryMode ?? null;
+    const outstandingGates = [...input.outstandingGates];
+    const base = {
+        deliveryMode,
+        outstandingGates,
+    };
+    if (hasSentResult(input.deliveryRows)) {
+        return {
+            ...base,
+            stage: 'delivered',
+            rationale: 'A result message reached the source binding and its receipt is persisted.',
+            allowedActions: ['view'],
+        };
+    }
+    if (input.run?.status === 'cancelled' || input.task?.status === 'cancelled') {
+        return {
+            ...base,
+            stage: 'cancelled',
+            rationale: 'The authoritative Task or Run is cancelled.',
+            allowedActions: ['view'],
+        };
+    }
+    if (input.run?.status === 'failed' || input.outcome?.status === 'failed') {
+        return {
+            ...base,
+            stage: 'failed',
+            rationale: 'The authoritative Run or Outcome recorded a terminal failure.',
+            allowedActions: ['retry', 'cancel', 'view'],
+        };
+    }
+    if (hasAcceptedResultEvidence(input)) {
+        if (outstandingGates.length === 0) {
+            return {
+                ...base,
+                stage: 'publish_authorized',
+                rationale: 'Result evidence is accepted and no delivery gate remains outstanding.',
+                allowedActions: ['view'],
+            };
+        }
+        return {
+            ...base,
+            stage: 'result_ready',
+            rationale: 'Result evidence is accepted but a delivery gate still requires an owner decision.',
+            allowedActions: ['publish', 'deny', 'cancel', 'view'],
+        };
+    }
+    if (input.awaitingOwnerDecision || input.run?.status === 'blocked') {
+        return {
+            ...base,
+            stage: 'decision_needed',
+            rationale: 'The supervised Run is blocked on an owner decision.',
+            allowedActions: ['approve', 'deny', 'retry', 'cancel', 'view'],
+        };
+    }
+    if (input.run?.status === 'running') {
+        return {
+            ...base,
+            stage: 'running',
+            rationale: 'The supervised Run is active.',
+            // `resume` is offered because a Run can be `running` with nothing driving
+            // it — the usual cause being a host restart mid-flight.
+            allowedActions: ['resume', 'cancel', 'view'],
+        };
+    }
+    if (input.run?.status === 'queued') {
+        return {
+            ...base,
+            stage: 'admitted',
+            rationale: 'An approved Task and a queued supervised Run exist.',
+            allowedActions: ['cancel', 'view'],
+        };
+    }
+    // No Run yet. An approved Task means the owner authorized this revision and
+    // admission is mid-flight or was interrupted; that is deliberately distinct
+    // from `admitted`, which requires the Run to exist.
+    if (input.task !== null && isOwnerApproved(input.task.approval.status)) {
+        return {
+            ...base,
+            stage: 'execution_authorized',
+            rationale: 'The owner approved this proposal revision; the supervised Run is not queued yet.',
+            allowedActions: ['view'],
+        };
+    }
+    if (input.proposal !== null) {
+        return {
+            ...base,
+            stage: 'scope_proposed',
+            rationale: 'A versioned scope proposal is visible and awaiting owner authorization.',
+            // `adjust` is withdrawn until the FR-16 clarification loop exists.
+            allowedActions: ['start_work', 'cancel', 'view'],
+        };
+    }
+    return {
+        ...base,
+        stage: 'received',
+        rationale: 'The source update was accepted and a durable intake anchor exists.',
+        allowedActions: ['cancel', 'view'],
+    };
+}
+//# sourceMappingURL=stageProjection.js.map

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

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

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

@@ -0,0 +1,21 @@
+/**
+ * Durable state owned by the transport work-delivery boundary.
+ *
+ * Cats Core remains the work ledger. This store contains only the transport
+ * details Core deliberately does not own: opaque callback grants and outbound
+ * delivery intents/receipts. Both families share one atomic file so a token or
+ * receipt update cannot overwrite the other family with a stale snapshot.
+ */
+import type { TransportWorkActionTokenV1, TransportWorkDeliveryV1 } from './contracts.js';
+export interface TransportWorkStateStore {
+    listDeliveries(): TransportWorkDeliveryV1[];
+    putDelivery(row: TransportWorkDeliveryV1): void;
+    listActionTokens(): TransportWorkActionTokenV1[];
+    putActionToken(token: TransportWorkActionTokenV1): void;
+    deleteActionToken(token: string): boolean;
+    deleteActionTokensForWorkItem(workItemId: string): number;
+}
+export declare function createMemoryTransportWorkStateStore(): TransportWorkStateStore;
+export declare function createFileTransportWorkStateStore(statePath: string): TransportWorkStateStore;
+export declare function resolveTransportWorkStatePath(platformStateDir: string): string;
+//# sourceMappingURL=stateStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stateStore.d.ts","sourceRoot":"","sources":["../../../../../src/platform/transports/work-delivery/stateStore.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACxB,MAAM,gBAAgB,CAAC;AAQxB,MAAM,WAAW,uBAAuB;IACtC,cAAc,IAAI,uBAAuB,EAAE,CAAC;IAC5C,WAAW,CAAC,GAAG,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAChD,gBAAgB,IAAI,0BAA0B,EAAE,CAAC;IACjD,cAAc,CAAC,KAAK,EAAE,0BAA0B,GAAG,IAAI,CAAC;IACxD,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1C,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3D;AAoMD,wBAAgB,mCAAmC,IAAI,uBAAuB,CAE7E;AAED,wBAAgB,iCAAiC,CAAC,SAAS,EAAE,MAAM,GAAG,uBAAuB,CAE5F;AAED,wBAAgB,6BAA6B,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAE9E"}