@north-light/sdk 0.3.414 → 0.3.416

package/dist/testing/cloud.d.ts

@@ -90,6 +90,13 @@ export interface FakeCloudOptions {
      * runtime without the launcher (a developer's Mac): every isolated start is 503 `isolated_unavailable`, retryable.
      */
     isolatedRuns?: 'available' | 'unavailable';
+    /**
+     * The clock every timestamp the fake writes reads, and the idempotency window runs on (default `Date.now`). Use
+     * `manualClock()` to step time. Stream idle, long-poll waits and run-notice retries stay on real timers.
+     */
+    clock?: {
+        now(): number;
+    };
 }
 /** `cloud.runs` and `user.runs`: the runs in start order, and the responder for them. */
 export interface FakeRuns {
@@ -117,6 +124,7 @@ export declare class FakeCloud {
         define(provider: string, definition: FakeProvider): void;
     };
     private readonly options;
+    private readonly clock;
     private readonly users;
     private readonly handles;
     private readonly allRuns;
@@ -155,6 +163,15 @@ export declare class FakeCloud {
         scopes?: FakeScope[];
         dependencies?: Record<string, ProviderDependency>;
     }): Promise<FakeUser>;
+    private activateState;
+    /**
+     * Make `userId`'s grant active with no stored connection, for an app that mints a per-user runtime token through
+     * the directory's `client_credentials` grant. Default scopes: `crtr:llm`, `crtr:act`.
+     */
+    activate(userId: string, options?: {
+        scopes?: FakeScope[];
+        dependencies?: Record<string, ProviderDependency>;
+    }): FakeUser;
     /**
      * A real `Crouter` on `userId`'s runtime with a fresh access token and no refresh: refusals never reach it. For
      * code whose production signature takes a `Crouter`; an app that goes through `OAuth2Client` tests through it.
@@ -186,6 +203,8 @@ export declare class FakeCloud {
     private route;
     private runIntercepts;
     private directory;
+    /** `grant_type=client_credentials` + `sub`: the directory's per-user runtime-token mint. The client assertion is not verified. */
+    private mint;
     private refresh;
     private newRefreshToken;
     private accessToken;

package/dist/testing/cloud.js

@@ -71,6 +71,7 @@ export class FakeCloud {
     runs;
     providers;
     options;
+    clock;
     users = new Map();
     handles = new Map();
     allRuns = [];
@@ -90,16 +91,18 @@ export class FakeCloud {
         if (!options || typeof options.clientId !== 'string' || !options.clientId)
             throw new TypeError('FakeCloud needs a clientId');
         this.options = options;
+        this.clock = options.clock ?? { now: () => Date.now() };
         this.clientId = options.clientId;
         this.issuer = (options.issuer ?? 'https://directory.test').replace(/\/$/, '');
         this.runNotices = new RunNotices(options.runNotice, this.key, {
             issuer: this.issuer, clientId: this.clientId, runtimeId: options.runtimeId ?? 'runtime:test', runtimeClientId: options.runtimeClientId ?? 'runtime-client',
-        }, (userId) => this.users.get(userId)?.active === true);
+        }, (userId) => this.users.get(userId)?.active === true, this.clock);
         this.notices = this.runNotices.records;
         const grantee = `app:${this.clientId}`;
         this.host = {
             grantee,
             streamIdleMs: options.streamIdleMs ?? 60_000,
+            now: () => this.clock.now(),
             grantActive: (userId) => this.users.get(userId)?.active === true,
             appended: (run) => this.runNotices.appended(run),
             streamOpened: (run) => this.runNotices.streamOpened(run),
@@ -186,6 +189,12 @@ export class FakeCloud {
     async connect(store, userId, options = {}) {
         const handle = this.user(userId);
         const state = this.state(userId);
+        this.activateState(state, options);
+        state.refreshToken ??= this.newRefreshToken(userId);
+        await store.save({ userId, runtimeUrl: this.runtimeUrlFor(userId), refreshToken: state.refreshToken, grantId: state.grantId, accessToken: '', accessTokenExpiresAt: 0 });
+        return handle;
+    }
+    activateState(state, options) {
         if (!state.active) {
             state.active = true;
             state.refusal = null;
@@ -200,8 +209,16 @@ export class FakeCloud {
             state.rev++;
             state.wakeHolds();
         }
+    }
+    /**
+     * Make `userId`'s grant active with no stored connection, for an app that mints a per-user runtime token through
+     * the directory's `client_credentials` grant. Default scopes: `crtr:llm`, `crtr:act`.
+     */
+    activate(userId, options = {}) {
+        const handle = this.user(userId);
+        const state = this.state(userId);
+        this.activateState(state, options);
         state.refreshToken ??= this.newRefreshToken(userId);
-        await store.save({ userId, runtimeUrl: this.runtimeUrlFor(userId), refreshToken: state.refreshToken, grantId: state.grantId, accessToken: '', accessTokenExpiresAt: 0 });
         return handle;
     }
     /**
@@ -283,7 +300,7 @@ export class FakeCloud {
         if (!state) {
             state = new UserState(userId, this.clientId, (user) => { for (const run of user.runs)
                 if (!run.deleted)
-                    run.revokeStreams(); });
+                    run.revokeStreams(); }, this.clock);
             this.users.set(userId, state);
         }
         return state;
@@ -343,8 +360,10 @@ export class FakeCloud {
             throw new Error(`FakeCloud: the fake directory does not serve ${request.method} ${url.href}`);
         const params = op === 'directory.token' ? new URLSearchParams(await request.text()) : null;
         const presented = params?.get('refresh_token') ?? '';
-        const owner = op === 'directory.token' ? [...this.users.values()].find((user) => user.refreshToken === presented)?.id ?? this.superseded.get(presented) ?? null : null;
-        const call = { op, userId: owner, answer: 'ok', at: Date.now() };
+        const credentials = params?.get('grant_type') === 'client_credentials';
+        const owner = op === 'directory.token' && credentials ? params.get('sub') || null
+            : op === 'directory.token' ? [...this.users.values()].find((user) => user.refreshToken === presented)?.id ?? this.superseded.get(presented) ?? null : null;
+        const call = { op, userId: owner, answer: 'ok', at: this.clock.now() };
         this.directoryCalls.push(call);
         const scripted = await this.runIntercepts(op, call, signal);
         if (scripted !== undefined) {
@@ -365,7 +384,22 @@ export class FakeCloud {
         }
         if (op === 'directory.jwks')
             return Response.json(await this.key.jwks());
-        return this.refresh(params, presented, call);
+        return credentials ? this.mint(params, call) : this.refresh(params, presented, call);
+    }
+    /** `grant_type=client_credentials` + `sub`: the directory's per-user runtime-token mint. The client assertion is not verified. */
+    mint(params, call) {
+        const sub = params.get('sub');
+        if (!sub) {
+            call.answer = 400;
+            return Response.json({ error: 'unauthorized_client' }, { status: 400 });
+        }
+        const user = this.users.get(sub);
+        const refused = (description, answer) => { call.answer = answer; return Response.json({ error: 'invalid_grant', error_description: description }, { status: 400 }); };
+        if (user?.refusal)
+            return refused(user.refusal, user.refusal);
+        if (!user?.active)
+            return refused('no active grant', 'grant_revoked');
+        return Response.json({ access_token: this.accessToken(user, 600), token_type: 'Bearer', expires_in: 600, runtimeUrl: this.runtimeUrlFor(user.id) });
     }
     refresh(params, presented, call) {
         const refused = (code) => { call.answer = code; return Response.json({ error: 'invalid_grant', error_description: code }, { status: 400 }); };
@@ -388,9 +422,9 @@ export class FakeCloud {
         });
     }
     newRefreshToken(userId) { return `rt-${++this.refreshSerial}-${userId}`; }
-    accessToken(user) {
-        const now = Math.floor(Date.now() / 1000);
-        return unsignedJwt({ sub: user.id, grant: user.grantId, exp: now + 3600, iat: now, rev: user.rev, serial: ++this.tokenSerial });
+    accessToken(user, ttlSeconds = 3600) {
+        const now = Math.floor(this.clock.now() / 1000);
+        return unsignedJwt({ sub: user.id, grant: user.grantId, exp: now + ttlSeconds, iat: now, rev: user.rev, serial: ++this.tokenSerial });
     }
     // ---- runtime -----------------------------------------------------------------------------------------------------
     async runtime(url, request, signal, claims, sub) {
@@ -419,7 +453,7 @@ export class FakeCloud {
         const questionRun = questionId === null ? undefined : user?.runs.find((run) => !run.deleted && run.questions.has(questionId));
         const call = {
             userId: user ? user.id : null, op, runId: runId ?? questionRun?.id ?? null, questionId, method: request.method, path: url.pathname,
-            query: Object.fromEntries(url.searchParams), body, idempotencyKey: request.headers.get('idempotency-key'), status: null, at: Date.now(),
+            query: Object.fromEntries(url.searchParams), body, idempotencyKey: request.headers.get('idempotency-key'), status: null, at: this.clock.now(),
         };
         this.calls.push(call);
         const answer = (status, payload) => { call.status = status; return jsonAnswer(payload, status, this.headers()); };
@@ -685,7 +719,7 @@ export class FakeCloud {
             ...(outputSchema === undefined ? {} : { output_schema: outputSchema }), ...(message === undefined ? {} : { message }),
         }));
         if (key !== null) {
-            const entry = user.idempotency.get(key);
+            const entry = user.idempotent(key);
             if (entry) {
                 if (entry.hash !== hash)
                     throw refuse(409, 'idempotency_conflict', 'key used with a different request');
@@ -713,7 +747,7 @@ export class FakeCloud {
             ...(accepted ? { message: { run_id: run.id, message_id: accepted.message_id, sequence_number: accepted.sequence_number } } : {}),
         };
         if (key !== null)
-            user.idempotency.set(key, { hash, runId: run.id, status: 201, body: structuredClone(response) });
+            user.idempotency.set(key, { hash, runId: run.id, status: 201, body: structuredClone(response), createdAt: this.clock.now() });
         this.respond(run, 'start', accepted ? [accepted] : []);
         return { status: 201, body: response };
     }
@@ -730,7 +764,7 @@ export class FakeCloud {
         const key = this.idempotencyKey(rawKey);
         const hash = sha256Hex(JSON.stringify(['run.message', run.id, text, startTurn]));
         if (key !== null) {
-            const entry = user.idempotency.get(key);
+            const entry = user.idempotent(key);
             if (entry) {
                 if (entry.hash !== hash)
                     throw refuse(409, 'idempotency_conflict', 'key used with a different request');
@@ -745,7 +779,7 @@ export class FakeCloud {
         const accepted = run.accept(text, startTurn, key);
         const response = { run_id: run.id, message_id: accepted.message_id, sequence_number: accepted.sequence_number };
         if (key !== null)
-            user.idempotency.set(key, { hash, runId: run.id, status: 202, body: structuredClone(response) });
+            user.idempotency.set(key, { hash, runId: run.id, status: 202, body: structuredClone(response), createdAt: this.clock.now() });
         if (startTurn)
             this.respond(run, 'message', [accepted]);
         return { status: 202, body: response };

package/dist/testing/conformance/index.d.ts

@@ -0,0 +1,2 @@
+export { IDEMPOTENCY_WINDOW_MS, keyedWriteScenarios } from './keyed-write.js';
+export type { AcceptedMessage, KeyedWriteCaller, KeyedWriteFailure, KeyedWriteScenario, KeyedWriteTarget } from './keyed-write.js';

package/dist/testing/conformance/index.js

@@ -0,0 +1,3 @@
+// `@north-light/sdk/testing/conformance`: executable scenarios that hold a test double of the crouter runtime to the
+// daemon's real behaviour. Framework-agnostic: they assert with `node:assert/strict` and run under any test runner.
+export { IDEMPOTENCY_WINDOW_MS, keyedWriteScenarios } from './keyed-write.js';

package/dist/testing/conformance/keyed-write.d.ts

@@ -0,0 +1,43 @@
+/** How long a kept key replays, in ms. A record of this age or older reads as absent. Equal to the daemon's constant. */
+export declare const IDEMPOTENCY_WINDOW_MS = 86400000;
+/** A message the run accepted, in acceptance order. */
+export interface AcceptedMessage {
+    id: string;
+    text: string;
+}
+/** What a target's `classify` makes of a thrown error. */
+export type KeyedWriteFailure = 'idempotency_conflict' | 'run_settled' | 'other';
+/**
+ * One caller on the target: a person using an app, with keys of their own. The daemon scopes a key to the app (the
+ * grantee), so two callers that must not share keys are different apps there; on a target scoped by person they are
+ * different people. Every write carries an `Idempotency-Key`.
+ */
+export interface KeyedWriteCaller {
+    /** Start a run; returns the run id. */
+    start(key: string, prompt: string): Promise<string>;
+    /** A message that starts a turn; returns the message id. */
+    message(runId: string, key: string, text: string): Promise<string>;
+    /** A message with `start_turn: false`; returns the message id. */
+    note(runId: string, key: string, text: string): Promise<string>;
+    /** Cancel the run. */
+    cancel(runId: string): Promise<void>;
+    /** The messages the run accepted, in order. A start without `message` contributes none. */
+    accepted(runId: string): Promise<AcceptedMessage[]>;
+}
+/** What a runtime double (or the daemon) supplies; the scenarios call nothing else. */
+export interface KeyedWriteTarget {
+    /** A new, independent caller that shares no keys with any other: one the target has never seen, with an active grant. */
+    user(): Promise<KeyedWriteCaller> | KeyedWriteCaller;
+    /** Make every stored key `ms` older: advance the target's clock, or backdate the records. A target on the real clock
+     *  keeps running while a scenario does, so K4 stops a minute short of the window instead of one ms short; a target
+     *  on a manual clock proves the exact boundary in its own test. */
+    age(ms: number): Promise<void> | void;
+    /** Map the target's thrown error. */
+    classify(error: unknown): KeyedWriteFailure;
+}
+export interface KeyedWriteScenario {
+    /** `K1 …`: stable, unique, safe to use as a test title. */
+    name: string;
+    run(target: KeyedWriteTarget): Promise<void>;
+}
+export declare const keyedWriteScenarios: KeyedWriteScenario[];

package/dist/testing/conformance/keyed-write.js

@@ -0,0 +1,124 @@
+// Keyed-write scenarios K1–K8: the idempotent accept of `run.start` and `run.message`, as the daemon defines it
+// (core/runs/operations.ts). Scope is (grantee, key); the two operations share one key space; the request hash
+// covers the operation and its target; a record at least `IDEMPOTENCY_WINDOW_MS` old reads as absent.
+import assert from 'node:assert/strict';
+/** How long a kept key replays, in ms. A record of this age or older reads as absent. Equal to the daemon's constant. */
+export const IDEMPOTENCY_WINDOW_MS = 86_400_000;
+async function failure(target, attempt) {
+    const settled = await Promise.allSettled([attempt]);
+    const [result] = settled;
+    assert.equal(result.status, 'rejected', 'the write was expected to fail but was accepted');
+    return target.classify(result.reason);
+}
+/** How far short of the window K4's first leg stops: more than a real-clock target can run during the scenario. */
+const SHORT_OF_WINDOW_MS = 60_000;
+const ids = (messages) => messages.map((message) => message.id);
+/** A fresh run for a scenario to write to: its own caller and a start key unique to the scenario. */
+async function fresh(target, label) {
+    const caller = await target.user();
+    return { caller, runId: await caller.start(`${label}-start`, `${label} prompt`) };
+}
+export const keyedWriteScenarios = [
+    {
+        name: 'K1 an equal key replays the first answer',
+        async run(target) {
+            const caller = await target.user();
+            const first = await caller.start('k1-start', 'hello');
+            assert.equal(await caller.start('k1-start', 'hello'), first, 'a repeated start returns the same run id');
+            const m1 = await caller.message(first, 'k1-msg', 'one');
+            assert.equal(await caller.message(first, 'k1-msg', 'one'), m1, 'a repeated message returns the same message id');
+            assert.deepEqual(await caller.accepted(first), [{ id: m1, text: 'one' }]);
+        },
+    },
+    {
+        name: 'K2 a key reused with another request is idempotency_conflict',
+        async run(target) {
+            const { caller, runId } = await fresh(target, 'k2');
+            const m1 = await caller.message(runId, 'k2-msg', 'one');
+            assert.equal(await failure(target, caller.message(runId, 'k2-msg', 'other')), 'idempotency_conflict');
+            assert.equal(await failure(target, caller.start('k2-start', 'another prompt')), 'idempotency_conflict');
+            assert.deepEqual(await caller.accepted(runId), [{ id: m1, text: 'one' }], 'the refused write accepted nothing');
+        },
+    },
+    {
+        name: 'K3 concurrent equal-key writes are accepted once',
+        async run(target) {
+            const { caller, runId } = await fresh(target, 'k3');
+            const messages = await Promise.all([1, 2, 3].map(() => caller.message(runId, 'k3-msg', 'same')));
+            assert.equal(new Set(messages).size, 1, 'three concurrent messages return one message id');
+            assert.deepEqual(await caller.accepted(runId), [{ id: messages[0], text: 'same' }]);
+            const starts = await Promise.all([1, 2, 3].map(() => caller.start('k3-concurrent-start', 'same prompt')));
+            assert.equal(new Set(starts).size, 1, 'three concurrent starts return one run id');
+        },
+    },
+    {
+        name: 'K4 a key expires after the window',
+        async run(target) {
+            const { caller, runId } = await fresh(target, 'k4');
+            const m1 = await caller.message(runId, 'k4-msg', 'one');
+            await target.age(IDEMPOTENCY_WINDOW_MS - SHORT_OF_WINDOW_MS);
+            assert.equal(await caller.message(runId, 'k4-msg', 'one'), m1, 'a key short of the window still replays');
+            assert.equal((await caller.accepted(runId)).length, 1);
+            await target.age(SHORT_OF_WINDOW_MS);
+            const m2 = await caller.message(runId, 'k4-msg', 'one');
+            assert.notEqual(m2, m1, 'a key at the window reads as absent: the write is accepted anew');
+            assert.deepEqual(ids(await caller.accepted(runId)), [m1, m2]);
+        },
+    },
+    {
+        name: 'K5 a replay after cancel returns the original; a new write is run_settled',
+        async run(target) {
+            for (const kind of ['message', 'note']) {
+                const { caller, runId } = await fresh(target, `k5-${kind}`);
+                const write = (key) => (kind === 'message' ? caller.message(runId, key, 'text') : caller.note(runId, key, 'text'));
+                const first = await write('k5-key');
+                await caller.cancel(runId);
+                assert.equal(await write('k5-key'), first, `a ${kind} key replays its original after cancel`);
+                assert.equal(await failure(target, write('k5-new')), 'run_settled', `a new ${kind} key on a canceled run`);
+                assert.deepEqual(await caller.accepted(runId), [{ id: first, text: 'text' }], 'nothing new was accepted');
+            }
+        },
+    },
+    {
+        name: 'K6 a key is bound to its operation',
+        async run(target) {
+            const { caller, runId } = await fresh(target, 'k6');
+            assert.equal(await failure(target, caller.message(runId, 'k6-start', 'x')), 'idempotency_conflict', 'a start key presented to message');
+            const m1 = await caller.message(runId, 'k6-msg', 'same text');
+            assert.equal(await failure(target, caller.note(runId, 'k6-msg', 'same text')), 'idempotency_conflict', 'a message key presented to note');
+            const n1 = await caller.note(runId, 'k6-note', 'same text');
+            assert.equal(await failure(target, caller.message(runId, 'k6-note', 'same text')), 'idempotency_conflict', 'a note key presented to message');
+            assert.deepEqual(ids(await caller.accepted(runId)), [m1, n1], 'only the first writes were accepted');
+        },
+    },
+    {
+        name: 'K7 keys are scoped to the grantee',
+        async run(target) {
+            const a = await target.user();
+            const b = await target.user();
+            const runA = await a.start('k7-start', 'a prompt');
+            const m1 = await a.message(runA, 'k7-msg', 'text');
+            const runB = await b.start('k7-start', 'b prompt');
+            assert.notEqual(runB, runA, "B's start under A's key is a new run, not a conflict");
+            const m2 = await b.message(runB, 'k7-msg', 'text');
+            assert.deepEqual(await b.accepted(runB), [{ id: m2, text: 'text' }]);
+            assert.deepEqual(await a.accepted(runA), [{ id: m1, text: 'text' }], "B's writes did not touch A's run");
+        },
+    },
+    {
+        name: 'K8 concurrent notes, and a note against a message, are accepted once',
+        async run(target) {
+            const { caller, runId } = await fresh(target, 'k8');
+            const notes = await Promise.all([1, 2, 3].map(() => caller.note(runId, 'k8-note', 'noted')));
+            assert.equal(new Set(notes).size, 1, 'three concurrent notes return one message id');
+            assert.deepEqual(await caller.accepted(runId), [{ id: notes[0], text: 'noted' }]);
+            const pair = await Promise.allSettled([caller.message(runId, 'k8-pair', 'same'), caller.note(runId, 'k8-pair', 'same')]);
+            const accepted = pair.filter((result) => result.status === 'fulfilled');
+            const refused = pair.filter((result) => result.status === 'rejected');
+            assert.equal(accepted.length, 1, 'exactly one of the pair is accepted');
+            assert.equal(refused.length, 1);
+            assert.equal(target.classify(refused[0].reason), 'idempotency_conflict', 'the other is idempotency_conflict');
+            assert.equal((await caller.accepted(runId)).length, 2, 'the note and one of the pair');
+        },
+    },
+];

package/dist/testing/index.d.ts

@@ -1,4 +1,6 @@
 export { FakeCloud } from './cloud.js';
+export { manualClock } from './clock.js';
+export type { ManualClock } from './clock.js';
 export type { FakeAnswer, FakeCall, FakeCloudOptions, FakeDirectoryCall, FakeDirectoryOp, FakeInterceptOp, FakeOp, FakeProvider, FakeRuns, FakeToolHandler, Intercept, } from './cloud.js';
 export type { FakeRun, FakeRunEnding, FakeRunMessage, FakeRunParams, FakeQuestion } from './run.js';
 export type { FakeNotice, RunNoticeOptions } from './notices.js';

package/dist/testing/index.js

@@ -1,3 +1,4 @@
 // `@north-light/sdk/testing`: a fake crouter cloud (directory + runtime) your real `OAuth2Client` and `Crouter` talk to
 // through `fetch`. Node-only; no test framework. See docs/sdk/testing.md.
 export { FakeCloud } from './cloud.js';
+export { manualClock } from './clock.js';

package/dist/testing/notices.d.ts

@@ -46,6 +46,8 @@ export declare class RunNotices {
     private readonly identity;
     /** Whether the run's person holds an active grant: a revoked grant has no notice target (`runNoticeTarget`). */
     private readonly grantActive;
+    /** Token claims and records read this clock; the outbox's gaps and retries stay on real timers. */
+    private readonly clock;
     private readonly states;
     readonly records: FakeNotice[];
     constructor(options: RunNoticeOptions | undefined, key: SigningKey, identity: {
@@ -55,7 +57,11 @@ export declare class RunNotices {
         runtimeClientId: string;
     }, 
     /** Whether the run's person holds an active grant: a revoked grant has no notice target (`runNoticeTarget`). */
-    grantActive: (userId: string) => boolean);
+    grantActive: (userId: string) => boolean, 
+    /** Token claims and records read this clock; the outbox's gaps and retries stay on real timers. */
+    clock: {
+        now(): number;
+    });
     private state;
     /** An open stream satisfies anything owed; closing it with the log ahead of what it wrote owes a notice. */
     streamOpened(run: FakeRun): (lastWritten: number) => void;

package/dist/testing/notices.js

@@ -36,15 +36,19 @@ export class RunNotices {
     key;
     identity;
     grantActive;
+    clock;
     states = new Map();
     records = [];
     constructor(options, key, identity, 
     /** Whether the run's person holds an active grant: a revoked grant has no notice target (`runNoticeTarget`). */
-    grantActive) {
+    grantActive, 
+    /** Token claims and records read this clock; the outbox's gaps and retries stay on real timers. */
+    clock) {
         this.options = options;
         this.key = key;
         this.identity = identity;
         this.grantActive = grantActive;
+        this.clock = clock;
     }
     state(run) {
         let state = this.states.get(run);
@@ -158,7 +162,7 @@ export class RunNotices {
         const options = this.options;
         for (let remint = false;; remint = true) {
             const token = await this.mint(run);
-            const record = { runId: run.id, userId: run.userId, attempt, remint, latestSequence: latest, claims: decodeJwt(token), status: null, error: null, at: Date.now() };
+            const record = { runId: run.id, userId: run.userId, attempt, remint, latestSequence: latest, claims: decodeJwt(token), status: null, error: null, at: this.clock.now() };
             this.records.push(record);
             let response;
             // Each request is bounded as the daemon's (`RUN_NOTICE_ATTEMPT_TIMEOUT_MS`): a hung handler is a retryable failure.
@@ -194,7 +198,7 @@ export class RunNotices {
         }
     }
     mint(run) {
-        const now = Math.floor(Date.now() / 1000);
+        const now = Math.floor(this.clock.now() / 1000);
         const app = `app:${this.identity.clientId}`;
         return this.key.sign({
             iss: this.identity.issuer, aud: this.options.url, sub: run.userId, grantee: app, client_id: this.identity.runtimeClientId,

package/dist/testing/run.d.ts

@@ -3,6 +3,8 @@ import type { DeclinedResultDTO, RunActivityDTO, RunEvent, RunEventFields, RunEv
 export interface RunHost {
     readonly grantee: string;
     readonly streamIdleMs: number;
+    /** The cloud's clock, in ms: every timestamp the run writes reads it. */
+    now(): number;
     /** Whether the run owner's grant is active now. */
     grantActive(userId: string): boolean;
     /** An event was appended (run-notice outbox). */

package/dist/testing/run.js

@@ -61,7 +61,7 @@ export class FakeRun {
         this.params = params;
         this.idempotencyKey = idempotencyKey;
         this.name = id;
-        this.createdAt = nowIso();
+        this.createdAt = nowIso(this.host.now());
         this.lastActivityAt = this.createdAt;
     }
     // ---- reads ---------------------------------------------------------------------------------------------------
@@ -150,7 +150,7 @@ export class FakeRun {
     setActivity(activity, { at } = {}) {
         this.assertLive();
         this.override = activity;
-        this.lastActivityAt = at === undefined ? nowIso() : new Date(at).toISOString();
+        this.lastActivityAt = at === undefined ? nowIso(this.host.now()) : new Date(at).toISOString();
         this.wake();
     }
     /** The run goes idle without a new turn (it stopped without submitting); undelivered start-turn mail is consumed. */
@@ -162,7 +162,7 @@ export class FakeRun {
         for (const message of this.messages)
             if (message.start_turn)
                 message.delivered = true;
-        this.lastActivityAt = nowIso();
+        this.lastActivityAt = nowIso(this.host.now());
         this.wake();
     }
     /** Record the run's ending and emit `node.settled`. */
@@ -170,7 +170,7 @@ export class FakeRun {
         this.assertLive();
         if (this.outcomeValue)
             throw new Error(`run ${this.id} is already settled`);
-        const settledAt = nowIso();
+        const settledAt = nowIso(this.host.now());
         const base = { node_id: this.id, revision: ++this.outcomeRevision, settled_at: settledAt, structured_result: null, detail: null };
         let outcome;
         this.hasResult = false;
@@ -408,7 +408,7 @@ export class FakeRun {
         });
     }
     append(type, fields, nodeId) {
-        const event = { ...fields, type, run_id: this.id, node_id: nodeId ?? this.id, sequence_number: ++this.sequence, ts: nowIso(), metadata: this.metadata };
+        const event = { ...fields, type, run_id: this.id, node_id: nodeId ?? this.id, sequence_number: ++this.sequence, ts: nowIso(this.host.now()), metadata: this.metadata };
         this.log.push(event);
         this.override = undefined;
         this.lastActivityAt = event.ts;

package/dist/testing/users.d.ts

@@ -1,7 +1,7 @@
 import type { GrantGetDTO, ProviderDependency, SetupState } from '@north-light/api';
 import type { FakeRun } from './run.js';
 /** The directory's reasons for refusing a refresh token (the SDK's refusal table). */
-export type FakeRefusalCode = 'grant_removed' | 'grant_suspended' | 'refresh_token_expired' | 'refresh_token_reused' | 'grant_revoked';
+export type FakeRefusalCode = 'grant_removed' | 'grant_suspended' | 'refresh_token_expired' | 'refresh_token_reused' | 'grant_revoked' | 'runtime_provisioning';
 /** What a run's responder receives. */
 export interface ResponderInput {
     run: FakeRun;
@@ -40,7 +40,8 @@ export interface IdempotencyEntry {
     hash: string;
     runId: string;
     status: number;
-    body: unknown;
+    body: unknown; /** ms on the cloud's clock. */
+    createdAt: number;
 }
 export declare const normalizeScopes: (scopes: readonly FakeScope[]) => GrantGetDTO["resolved_scopes"];
 /** Internal per-user state. */
@@ -48,6 +49,7 @@ export declare class UserState {
     readonly id: string;
     readonly clientId: string;
     private readonly onRevoke;
+    private readonly clock;
     active: boolean;
     rev: number;
     resolvedScopes: GrantGetDTO['resolved_scopes'];
@@ -65,12 +67,16 @@ export declare class UserState {
     readonly memory: Map<string, StoredMemoryDoc>;
     readonly idempotency: Map<string, IdempotencyEntry>;
     readonly holds: Set<Hold>;
-    constructor(id: string, clientId: string, onRevoke: (user: UserState) => void);
+    constructor(id: string, clientId: string, onRevoke: (user: UserState) => void, clock: {
+        now(): number;
+    });
     dto(exp?: number): GrantGetDTO | null;
     version(): string | null;
     /** The scopes the runtime authorizes with: only `always` ones (`activeRecord`, core/grants/mirror.ts). An `ask`
      *  scope is listed on the grant but grants nothing until the person approves it. */
     scopeStrings(): string[];
+    /** The live record under `key`: one at least a window old reads as absent, as on the daemon. */
+    idempotent(key: string): IdempotencyEntry | undefined;
     wakeHolds(): void;
     apply(patch: GrantPatch): void;
     revoke(code: FakeRefusalCode): void;

package/dist/testing/users.js

@@ -1,3 +1,4 @@
+import { IDEMPOTENCY_WINDOW_MS } from './conformance/keyed-write.js';
 import { grantVersion, nowIso } from './wire.js';
 export const normalizeScopes = (scopes) => scopes.map((scope) => (typeof scope === 'string' ? { scope, mode: 'always' } : { scope: scope.scope, mode: scope.mode }));
 /** Internal per-user state. */
@@ -5,6 +6,7 @@ export class UserState {
     id;
     clientId;
     onRevoke;
+    clock;
     active = false;
     rev = 0;
     resolvedScopes = [];
@@ -22,13 +24,14 @@ export class UserState {
     memory = new Map();
     idempotency = new Map();
     holds = new Set();
-    constructor(id, clientId, onRevoke) {
+    constructor(id, clientId, onRevoke, clock) {
         this.id = id;
         this.clientId = clientId;
         this.onRevoke = onRevoke;
+        this.clock = clock;
         this.grantId = `grant-${id.replace(/^user:/, '')}`;
     }
-    dto(exp = Math.floor(Date.now() / 1000) + 3600) {
+    dto(exp = Math.floor(this.clock.now() / 1000) + 3600) {
         if (!this.active)
             return null;
         const body = {
@@ -41,6 +44,11 @@ export class UserState {
     /** The scopes the runtime authorizes with: only `always` ones (`activeRecord`, core/grants/mirror.ts). An `ask`
      *  scope is listed on the grant but grants nothing until the person approves it. */
     scopeStrings() { return this.resolvedScopes.filter((entry) => entry.mode === 'always').map((entry) => entry.scope); }
+    /** The live record under `key`: one at least a window old reads as absent, as on the daemon. */
+    idempotent(key) {
+        const entry = this.idempotency.get(key);
+        return entry && this.clock.now() - entry.createdAt < IDEMPOTENCY_WINDOW_MS ? entry : undefined;
+    }
     wakeHolds() { for (const hold of [...this.holds])
         hold.wake(); }
     apply(patch) {
@@ -59,7 +67,7 @@ export class UserState {
     }
     putMemory(doc) {
         const existing = this.memory.get(doc.name);
-        const now = nowIso();
+        const now = nowIso(this.clock.now());
         this.memory.set(doc.name, {
             name: doc.name, body: doc.body, privacy: doc.privacy ?? 'public', kind: doc.kind ?? 'knowledge',
             created_at: doc.created_at ?? existing?.created_at ?? now, updated_at: doc.updated_at ?? now,

package/dist/types.d.ts

@@ -22,6 +22,14 @@ export interface RequestOptions {
     timeout?: number;
     /** Transient-failure retries for this request. Never applied to `POST` or `PATCH`. */
     maxRetries?: number;
+    /** One overall deadline for this call, in milliseconds from now: it covers every attempt, every retry wait
+     *  (including a server's `Retry-After`) and the response body. `timeout` still bounds each attempt but never
+     *  past the deadline. When the deadline passes, or a retry wait would pass it, the call rejects with
+     *  `DeadlineExceededError` at once instead of sleeping on. */
+    budgetMs?: number;
+    /** The same deadline as an absolute instant (epoch milliseconds), for passing one deadline to several calls.
+     *  With `budgetMs` too, the earlier wins. */
+    deadlineAt?: number;
 }
 /** Options for one outcome poll. */
 export interface NodeOutcomeOptions extends RequestOptions {

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** This SDK's release version. It is also the oldest runtime the SDK accepts: one release is one version set. */
-export declare const SDK_VERSION = "0.3.414";
+export declare const SDK_VERSION = "0.3.416";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Written by scripts/release-version.mjs on every release; do not edit by hand.
 /** This SDK's release version. It is also the oldest runtime the SDK accepts: one release is one version set. */
-export const SDK_VERSION = '0.3.414';
+export const SDK_VERSION = '0.3.416';