@methodts/runtime 0.1.0

package/dist/sessions/session-store/in-memory-session-store.test.js

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for the in-memory SessionStore reference impl. Covers the
+ * gate invariants: port purity, lease semantics, fencing, schema rejection.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createInMemorySessionStore } from './in-memory-session-store.js';
+import { isSessionStoreError } from '../../ports/session-store-errors.js';
+function makeSnapshot(sessionId = 'ses_1') {
+    return {
+        schemaVersion: 1,
+        sessionId,
+        scopeId: 'app_test',
+        pactRef: { id: 'p', version: '1.0.0', fingerprint: 'sha256:abc' },
+        status: 'initializing',
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        latestCheckpointSequence: null,
+        depth: 0,
+    };
+}
+function makeCheckpoint(sessionId, sequence) {
+    return {
+        schemaVersion: 1,
+        sequence,
+        sessionId,
+        createdAt: new Date().toISOString(),
+        eventCursor: { sequence: sequence * 10, id: `evt_${sequence}` },
+        agentState: { kind: 'inline', data: { step: sequence } },
+        pendingBudget: null,
+        nextAction: { kind: 'await-prompt' },
+    };
+}
+describe('InMemorySessionStore — lifecycle', () => {
+    it('create + load round-trips a snapshot', async () => {
+        const store = createInMemorySessionStore();
+        const snap = makeSnapshot();
+        await store.create(snap);
+        const loaded = await store.load('ses_1');
+        assert.ok(loaded);
+        assert.equal(loaded?.sessionId, 'ses_1');
+    });
+    it('create rejects duplicate sessionId with DUPLICATE', async () => {
+        const store = createInMemorySessionStore();
+        const snap = makeSnapshot();
+        await store.create(snap);
+        await assert.rejects(() => store.create(snap), (err) => isSessionStoreError(err) && err.code === 'DUPLICATE');
+    });
+    it('load returns null for unknown session', async () => {
+        const store = createInMemorySessionStore();
+        assert.equal(await store.load('missing'), null);
+    });
+    it('rejects non-v1 schema on create', async () => {
+        const store = createInMemorySessionStore();
+        const snap = { ...makeSnapshot(), schemaVersion: 2 };
+        await assert.rejects(() => store.create(snap), (err) => isSessionStoreError(err) && err.code === 'SCHEMA_INCOMPATIBLE' && err.retryable === false);
+    });
+});
+describe('InMemorySessionStore — lease + fencing (G-RESUME-IDEMPOTENT, G-LEASE-FENCING)', () => {
+    it('resume acquires a lease and returns a fencing token', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        const rc = await store.resume('ses_1', 'worker-a');
+        assert.ok(rc.fencingToken.length > 0);
+        assert.equal(rc.snapshot.sessionId, 'ses_1');
+    });
+    it('is idempotent: same worker resuming twice gets the same token', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        const first = await store.resume('ses_1', 'worker-a');
+        const second = await store.resume('ses_1', 'worker-a');
+        assert.equal(first.fencingToken, second.fencingToken);
+        assert.equal(first.leaseExpiresAt, second.leaseExpiresAt);
+    });
+    it('blocks a different worker with FENCED while the lease is live', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        await store.resume('ses_1', 'worker-a');
+        await assert.rejects(() => store.resume('ses_1', 'worker-b'), (err) => isSessionStoreError(err) && err.code === 'FENCED');
+    });
+    it('allows a new worker to reclaim a stale lease', async () => {
+        let t = 1_000_000;
+        const store = createInMemorySessionStore({ now: () => t, defaultLeaseTtlMs: 1000 });
+        await store.create(makeSnapshot());
+        await store.resume('ses_1', 'worker-a');
+        // Advance past TTL.
+        t += 5_000;
+        const rc = await store.resume('ses_1', 'worker-b');
+        assert.ok(rc.fencingToken.length > 0);
+    });
+    it('rejects appendCheckpoint with a stale fencing token', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        await store.resume('ses_1', 'worker-a');
+        await assert.rejects(() => store.appendCheckpoint('ses_1', makeCheckpoint('ses_1', 1), 'bogus-token'), (err) => isSessionStoreError(err) && err.code === 'FENCED');
+    });
+    it('renewLease fails with FENCED when the token is unknown', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        await store.resume('ses_1', 'worker-a');
+        await assert.rejects(() => store.renewLease('ses_1', 'wrong'), (err) => isSessionStoreError(err) && err.code === 'FENCED');
+    });
+    it('releaseLease is idempotent', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        const rc = await store.resume('ses_1', 'worker-a');
+        await store.releaseLease('ses_1', rc.fencingToken);
+        await store.releaseLease('ses_1', rc.fencingToken); // no throw
+    });
+    it('fingerprint mismatch throws FINGERPRINT_MISMATCH', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        await assert.rejects(() => store.resume('ses_1', 'worker-a', {
+            requireFingerprint: true,
+            expectedFingerprint: 'sha256:different',
+        }), (err) => isSessionStoreError(err) && err.code === 'FINGERPRINT_MISMATCH');
+    });
+});
+describe('InMemorySessionStore — checkpoints', () => {
+    it('appends monotonically and loadLatest returns the latest', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        const rc = await store.resume('ses_1', 'worker-a');
+        await store.appendCheckpoint('ses_1', makeCheckpoint('ses_1', 1), rc.fencingToken);
+        await store.appendCheckpoint('ses_1', makeCheckpoint('ses_1', 2), rc.fencingToken);
+        const latest = await store.loadLatestCheckpoint('ses_1');
+        assert.equal(latest?.sequence, 2);
+        const snap = await store.load('ses_1');
+        assert.equal(snap?.latestCheckpointSequence, 2);
+    });
+    it('rejects non-monotonic sequences', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        const rc = await store.resume('ses_1', 'worker-a');
+        await store.appendCheckpoint('ses_1', makeCheckpoint('ses_1', 1), rc.fencingToken);
+        await assert.rejects(() => store.appendCheckpoint('ses_1', makeCheckpoint('ses_1', 5), rc.fencingToken), (err) => isSessionStoreError(err) && err.code === 'INTERNAL');
+    });
+    it('listCheckpoints returns most-recent first, bounded by limit', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        const rc = await store.resume('ses_1', 'worker-a');
+        for (let i = 1; i <= 5; i++) {
+            await store.appendCheckpoint('ses_1', makeCheckpoint('ses_1', i), rc.fencingToken);
+        }
+        const listed = await store.listCheckpoints('ses_1', 3);
+        assert.equal(listed.length, 3);
+        assert.equal(listed[0]?.sequence, 5);
+        assert.equal(listed[2]?.sequence, 3);
+    });
+    it('ring retention caps the stored checkpoint count', async () => {
+        const store = createInMemorySessionStore({ checkpointRingSize: 3 });
+        await store.create(makeSnapshot());
+        const rc = await store.resume('ses_1', 'worker-a');
+        for (let i = 1; i <= 6; i++) {
+            await store.appendCheckpoint('ses_1', makeCheckpoint('ses_1', i), rc.fencingToken);
+        }
+        const listed = await store.listCheckpoints('ses_1', 10);
+        assert.equal(listed.length, 3);
+        assert.equal(listed[0]?.sequence, 6);
+        assert.equal(listed[2]?.sequence, 4);
+        // Earlier sequence falls out of the ring.
+        assert.equal(await store.loadCheckpoint('ses_1', 1), null);
+    });
+    it('finalize releases any held lease and records status', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        await store.resume('ses_1', 'worker-a');
+        await store.finalize('ses_1', 'completed', 'ok');
+        const snap = await store.load('ses_1');
+        assert.equal(snap?.status, 'completed');
+        // A different worker can resume after finalize — lease is released.
+        const rc = await store.resume('ses_1', 'worker-b');
+        assert.ok(rc.fencingToken.length > 0);
+    });
+    it('destroy removes the session', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(makeSnapshot());
+        await store.destroy('ses_1');
+        assert.equal(await store.load('ses_1'), null);
+    });
+});
+//# sourceMappingURL=in-memory-session-store.test.js.map

package/dist/sessions/session-store/in-memory-session-store.test.js.map

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

package/dist/sessions/session-store/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @methodts/runtime/sessions/session-store — PRD-061 composition surface.
+ *
+ * Re-exports the SessionStore port, default CheckpointSink implementation,
+ * adapter-agnostic resume algorithm, and the in-memory reference store used
+ * by the pacta-testkit conformance fixtures and unit tests.
+ */
+export type { SessionStore } from '../../ports/session-store.js';
+export type { SessionStatus, PactRef, SessionSnapshot, EventCursor, AgentStateBlob, BudgetReservation, NextAction, Checkpoint, CheckpointMeta, ResumeOptions, ResumeContext, } from '../../ports/session-store-types.js';
+export { SessionStoreError, isSessionStoreError, } from '../../ports/session-store-errors.js';
+export type { SessionStoreErrorCode, SessionStoreErrorOptions, } from '../../ports/session-store-errors.js';
+export type { CheckpointSink, CheckpointSinkOptions, CheckpointCapture, } from '../../ports/checkpoint-sink.js';
+export { createCheckpointSink, SESSION_LIFECYCLE_TYPES } from './checkpoint-sink-impl.js';
+export { performResume, startLeaseHeartbeat, } from './resume.js';
+export type { BudgetEnforcer, ResumedPact, LeaseHeartbeat, PerformResumeArgs, ResumeOutcome, TimerBindings, } from './resume.js';
+export { createInMemorySessionStore } from './in-memory-session-store.js';
+export type { InMemorySessionStoreOptions } from './in-memory-session-store.js';
+export { DEFAULT_SESSION_STORE_FIXTURES, resumeMidTurnFixture, staleLeaseTheftFixture, schemaVersionRejectionFixture, runSessionStoreConformance, } from './conformance.js';
+export type { SessionStoreConformanceFixture, SessionStoreFactory, FixtureResult, } from './conformance.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/sessions/session-store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sessions/session-store/index.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,YAAY,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,YAAY,EACV,aAAa,EACb,OAAO,EACP,eAAe,EACf,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EACV,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,qCAAqC,CAAC;AAC7C,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAC1F,OAAO,EACL,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,cAAc,EACd,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,YAAY,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAGhF,OAAO,EACL,8BAA8B,EAC9B,oBAAoB,EACpB,sBAAsB,EACtB,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,8BAA8B,EAC9B,mBAAmB,EACnB,aAAa,GACd,MAAM,kBAAkB,CAAC"}

package/dist/sessions/session-store/index.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @methodts/runtime/sessions/session-store — PRD-061 composition surface.
+ *
+ * Re-exports the SessionStore port, default CheckpointSink implementation,
+ * adapter-agnostic resume algorithm, and the in-memory reference store used
+ * by the pacta-testkit conformance fixtures and unit tests.
+ */
+export { SessionStoreError, isSessionStoreError, } from '../../ports/session-store-errors.js';
+export { createCheckpointSink, SESSION_LIFECYCLE_TYPES } from './checkpoint-sink-impl.js';
+export { performResume, startLeaseHeartbeat, } from './resume.js';
+export { createInMemorySessionStore } from './in-memory-session-store.js';
+// ── Conformance fixtures (PRD-061 §8.2) ──
+export { DEFAULT_SESSION_STORE_FIXTURES, resumeMidTurnFixture, staleLeaseTheftFixture, schemaVersionRejectionFixture, runSessionStoreConformance, } from './conformance.js';
+//# sourceMappingURL=index.js.map

package/dist/sessions/session-store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sessions/session-store/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC;;;;;;GAMG;AAgBH,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,qCAAqC,CAAC;AAW7C,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAC1F,OAAO,EACL,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAUrB,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAG1E,4CAA4C;AAC5C,OAAO,EACL,8BAA8B,EAC9B,oBAAoB,EACpB,sBAAsB,EACtB,6BAA6B,EAC7B,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC"}

package/dist/sessions/session-store/resume.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Adapter-agnostic resume algorithm — PRD-061 §6.3 / S4 §6.
+ *
+ * Callers pass a `SessionStore` plus a minimal `BudgetEnforcer` adapter; this
+ * function performs the 5-step ritual:
+ *
+ *   1. atomic load + lease (delegated to `store.resume`)
+ *   2. fingerprint check (via `requireFingerprint`)
+ *   3. budget rehydrate-or-reserve (via `BudgetEnforcer.rehydrateOrReserve`)
+ *   4. consumer-side event replay (via optional `EventReader`)
+ *   5. lease heartbeat timer that renews the lease until stopped
+ *
+ * The algorithm itself is pure composition — no adapter-specific types leak in.
+ */
+import type { EventReader } from '../../ports/event-reader.js';
+import type { SessionStore } from '../../ports/session-store.js';
+import type { BudgetReservation, Checkpoint, NextAction, SessionSnapshot } from '../../ports/session-store-types.js';
+/** Minimal budget enforcer contract used by resume. Defined locally to avoid
+ * a circular dep with `@methodts/pacta`; the real implementation lives there.
+ */
+export interface BudgetEnforcer {
+    /**
+     * Given the checkpoint's stored reservation (or null for fresh sessions),
+     * decide whether to rehydrate the existing handle or reserve a fresh one.
+     * MUST be idempotent — called exactly once per resume.
+     */
+    rehydrateOrReserve(prior: BudgetReservation | null): Promise<BudgetReservation>;
+}
+/** Bare-minimum pact reference shape. Adapter-neutral. */
+export interface ResumedPact {
+    readonly id: string;
+    readonly version: string;
+    readonly fingerprint: string;
+}
+/** Handle returned to the caller; stopping the heartbeat releases the lease. */
+export interface LeaseHeartbeat {
+    /** Stop renewing. Does NOT release the lease — call `store.releaseLease` for that. */
+    stop(): void;
+    /** Current timer ms-until-next-renew (test introspection). */
+    readonly intervalMs: number;
+}
+export interface PerformResumeArgs {
+    readonly store: SessionStore;
+    readonly sessionId: string;
+    readonly workerId: string;
+    readonly pact: ResumedPact;
+    readonly budget: BudgetEnforcer;
+    readonly eventReader?: EventReader;
+    readonly leaseTtlMs?: number;
+    /**
+     * Override for the heartbeat cadence. Default = `leaseTtlMs / 3`, clamped
+     * between 1s and 10s.
+     */
+    readonly heartbeatIntervalMs?: number;
+    /**
+     * Override timer bindings for tests. Production callers leave this unset.
+     */
+    readonly timers?: TimerBindings;
+}
+export interface TimerBindings {
+    readonly setInterval: (fn: () => void, ms: number) => unknown;
+    readonly clearInterval: (handle: unknown) => void;
+}
+export interface ResumeOutcome {
+    readonly snapshot: SessionSnapshot;
+    readonly checkpoint: Checkpoint | null;
+    readonly fencingToken: string;
+    readonly leaseExpiresAt: string;
+    readonly nextAction: NextAction;
+    readonly freshBudget: BudgetReservation;
+    readonly heartbeat: LeaseHeartbeat;
+}
+/**
+ * Run the 5-step resume algorithm. Rethrows adapter errors untouched so the
+ * typed `SessionStoreError` reaches the caller intact.
+ */
+export declare function performResume(args: PerformResumeArgs): Promise<ResumeOutcome>;
+interface HeartbeatArgs {
+    readonly store: SessionStore;
+    readonly sessionId: string;
+    readonly fencingToken: string;
+    readonly intervalMs: number;
+    readonly leaseTtlMs: number;
+    readonly timers: TimerBindings;
+}
+export declare function startLeaseHeartbeat(args: HeartbeatArgs): LeaseHeartbeat;
+export {};
+//# sourceMappingURL=resume.d.ts.map

package/dist/sessions/session-store/resume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.d.ts","sourceRoot":"","sources":["../../../src/sessions/session-store/resume.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAG5C;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACjF;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,IAAI,IAAI,IAAI,CAAC;IACb,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IAC9D,QAAQ,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACnD;AAOD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;CACpC;AAMD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAsEnF;AAED,UAAU,aAAa;IACrB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,cAAc,CAgBvE"}

package/dist/sessions/session-store/resume.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Adapter-agnostic resume algorithm — PRD-061 §6.3 / S4 §6.
+ *
+ * Callers pass a `SessionStore` plus a minimal `BudgetEnforcer` adapter; this
+ * function performs the 5-step ritual:
+ *
+ *   1. atomic load + lease (delegated to `store.resume`)
+ *   2. fingerprint check (via `requireFingerprint`)
+ *   3. budget rehydrate-or-reserve (via `BudgetEnforcer.rehydrateOrReserve`)
+ *   4. consumer-side event replay (via optional `EventReader`)
+ *   5. lease heartbeat timer that renews the lease until stopped
+ *
+ * The algorithm itself is pure composition — no adapter-specific types leak in.
+ */
+import { SessionStoreError } from '../../ports/session-store-errors.js';
+const DEFAULT_TIMERS = {
+    setInterval: (fn, ms) => setInterval(fn, ms),
+    clearInterval: (handle) => clearInterval(handle),
+};
+function clamp(v, lo, hi) {
+    return Math.min(Math.max(v, lo), hi);
+}
+/**
+ * Run the 5-step resume algorithm. Rethrows adapter errors untouched so the
+ * typed `SessionStoreError` reaches the caller intact.
+ */
+export async function performResume(args) {
+    const leaseTtlMs = args.leaseTtlMs ?? 30_000;
+    // Step 1 & 2: atomic load + lease + fingerprint verification.
+    const rc = await args.store.resume(args.sessionId, args.workerId, {
+        leaseTtlMs,
+        requireFingerprint: true,
+        expectedFingerprint: args.pact.fingerprint,
+    });
+    // Belt-and-suspenders fingerprint check — implementations that do not
+    // honour `expectedFingerprint` still get caught here.
+    if (rc.snapshot.pactRef.fingerprint !== args.pact.fingerprint) {
+        // Best-effort lease release; swallow errors so the original failure wins.
+        await args.store.releaseLease(args.sessionId, rc.fencingToken).catch(() => undefined);
+        throw new SessionStoreError('FINGERPRINT_MISMATCH', `Pact fingerprint drift: stored=${rc.snapshot.pactRef.fingerprint} current=${args.pact.fingerprint}`, { sessionId: args.sessionId, retryable: false });
+    }
+    // Step 3: budget rehydrate-or-reserve.
+    const freshBudget = await args.budget.rehydrateOrReserve(rc.checkpoint?.pendingBudget ?? null);
+    // Step 4: replay events to re-registered consumers (NOT to the agent).
+    if (args.eventReader && rc.checkpoint) {
+        const cursor = rc.checkpoint.eventCursor;
+        // `EventReader` in this codebase offers `readRange`; if available, use it.
+        const reader = args.eventReader;
+        if (typeof reader.replay === 'function') {
+            await reader.replay({
+                filter: { sessionId: args.sessionId },
+                sinceSequence: cursor.sequence,
+            });
+        }
+        // Absence of `replay` is a documented soft path — see PRD-061 R-5. The
+        // caller is expected to coordinate replay through its own bus when the
+        // reader lacks seek.
+    }
+    // Step 5: start the lease heartbeat.
+    const heartbeatMs = clamp(args.heartbeatIntervalMs ?? Math.floor(leaseTtlMs / 3), 1_000, 10_000);
+    const heartbeat = startLeaseHeartbeat({
+        store: args.store,
+        sessionId: args.sessionId,
+        fencingToken: rc.fencingToken,
+        intervalMs: heartbeatMs,
+        leaseTtlMs,
+        timers: args.timers ?? DEFAULT_TIMERS,
+    });
+    return {
+        snapshot: rc.snapshot,
+        checkpoint: rc.checkpoint,
+        fencingToken: rc.fencingToken,
+        leaseExpiresAt: rc.leaseExpiresAt,
+        nextAction: rc.checkpoint?.nextAction ?? { kind: 'await-prompt' },
+        freshBudget,
+        heartbeat,
+    };
+}
+export function startLeaseHeartbeat(args) {
+    const handle = args.timers.setInterval(() => {
+        args.store
+            .renewLease(args.sessionId, args.fencingToken, args.leaseTtlMs)
+            .catch(() => {
+            // Best-effort renewal. If the lease was lost (FENCED), the next
+            // `appendCheckpoint` will surface the error. No throw from a timer.
+        });
+    }, args.intervalMs);
+    return {
+        stop() {
+            args.timers.clearInterval(handle);
+        },
+        intervalMs: args.intervalMs,
+    };
+}
+//# sourceMappingURL=resume.js.map

package/dist/sessions/session-store/resume.js.map

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

package/dist/sessions/session-store/resume.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for the adapter-agnostic resume algorithm.
+ */
+export {};
+//# sourceMappingURL=resume.test.d.ts.map

package/dist/sessions/session-store/resume.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.test.d.ts","sourceRoot":"","sources":["../../../src/sessions/session-store/resume.test.ts"],"names":[],"mappings":"AACA;;GAEG"}

package/dist/sessions/session-store/resume.test.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for the adapter-agnostic resume algorithm.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { performResume } from './resume.js';
+import { createInMemorySessionStore } from './in-memory-session-store.js';
+import { isSessionStoreError } from '../../ports/session-store-errors.js';
+function snap(fingerprint = 'sha256:same') {
+    return {
+        schemaVersion: 1,
+        sessionId: 'ses_1',
+        scopeId: 'app_test',
+        pactRef: { id: 'p', version: '1.0.0', fingerprint },
+        status: 'paused',
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        latestCheckpointSequence: null,
+        depth: 0,
+    };
+}
+function fakeBudget() {
+    const bucket = {
+        calls: 0,
+        last: null,
+        rehydrateOrReserve(prior) {
+            bucket.calls += 1;
+            bucket.last = prior;
+            const fresh = {
+                handle: 'rsv_fresh',
+                expiresAt: new Date(Date.now() + 60_000).toISOString(),
+                amount: { usd: 0.01, tokens: 1000 },
+                issuer: 'ctx.llm',
+            };
+            return Promise.resolve(fresh);
+        },
+    };
+    return bucket;
+}
+function fakeTimers() {
+    let started = 0;
+    let cleared = 0;
+    const bindings = {
+        get started() { return started; },
+        get cleared() { return cleared; },
+        setInterval: (_fn, _ms) => {
+            started += 1;
+            return { id: started };
+        },
+        clearInterval: (_handle) => {
+            cleared += 1;
+        },
+    };
+    return bindings;
+}
+describe('performResume — 5-step algorithm', () => {
+    it('acquires a lease, rehydrates budget, returns fencing token', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(snap());
+        const timers = fakeTimers();
+        const budget = fakeBudget();
+        const out = await performResume({
+            store,
+            sessionId: 'ses_1',
+            workerId: 'worker-a',
+            pact: { id: 'p', version: '1.0.0', fingerprint: 'sha256:same' },
+            budget,
+            timers,
+        });
+        assert.ok(out.fencingToken.length > 0);
+        assert.equal(budget.calls, 1);
+        assert.equal(out.freshBudget.handle, 'rsv_fresh');
+        assert.equal(out.nextAction.kind, 'await-prompt'); // no checkpoint → default
+        assert.equal(timers.started, 1);
+        out.heartbeat.stop();
+        assert.equal(timers.cleared, 1);
+    });
+    it('raises FINGERPRINT_MISMATCH when pacts have drifted', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(snap('sha256:original'));
+        const budget = fakeBudget();
+        const timers = fakeTimers();
+        await assert.rejects(() => performResume({
+            store,
+            sessionId: 'ses_1',
+            workerId: 'worker-a',
+            pact: { id: 'p', version: '1.0.0', fingerprint: 'sha256:drifted' },
+            budget,
+            timers,
+        }), (err) => isSessionStoreError(err) && err.code === 'FINGERPRINT_MISMATCH' && !err.retryable);
+    });
+    it('is idempotent: duplicate resume returns the same fencing token (G-RESUME-IDEMPOTENT)', async () => {
+        const store = createInMemorySessionStore();
+        await store.create(snap());
+        const budget = fakeBudget();
+        const timers = fakeTimers();
+        const first = await performResume({
+            store,
+            sessionId: 'ses_1',
+            workerId: 'worker-a',
+            pact: { id: 'p', version: '1.0.0', fingerprint: 'sha256:same' },
+            budget,
+            timers,
+        });
+        const second = await performResume({
+            store,
+            sessionId: 'ses_1',
+            workerId: 'worker-a',
+            pact: { id: 'p', version: '1.0.0', fingerprint: 'sha256:same' },
+            budget,
+            timers,
+        });
+        assert.equal(first.fencingToken, second.fencingToken);
+        first.heartbeat.stop();
+        second.heartbeat.stop();
+    });
+});
+//# sourceMappingURL=resume.test.js.map

package/dist/sessions/session-store/resume.test.js.map

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

package/dist/sessions/spawn-queue.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SpawnQueue — enforces a minimum gap between PTY session spawns.
+ *
+ * Problem: concurrent spawns cause API rate-limit contention and resource
+ * spikes (PRD 012 observation). The bridge HTTP handler already staggers
+ * batch spawns with setTimeout, but individual bridge_spawn calls from
+ * different orchestrators can still fire simultaneously.
+ *
+ * Solution: all spawn requests pass through SpawnQueue.enqueue(), which
+ * ensures at least MIN_SPAWN_GAP_MS between actual PTY process launches.
+ * The queue is FIFO and serializes execution.
+ */
+export interface SpawnQueueOptions {
+    /** Minimum milliseconds between consecutive spawns. */
+    minGapMs?: number;
+}
+export declare class SpawnQueue {
+    private readonly minGapMs;
+    private lastSpawnAt;
+    private queue;
+    private processing;
+    constructor(options?: SpawnQueueOptions);
+    enqueue<T>(execute: () => Promise<T>): Promise<T>;
+    get pending(): number;
+    get lastSpawnTime(): number;
+    private drain;
+}
+//# sourceMappingURL=spawn-queue.d.ts.map

package/dist/sessions/spawn-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-queue.d.ts","sourceRoot":"","sources":["../../src/sessions/spawn-queue.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,KAAK,CAIL;IACR,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,CAAC,EAAE,iBAAiB;IAIvC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAWjD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,aAAa,IAAI,MAAM,CAE1B;YAEa,KAAK;CAyBpB"}