@north-light/sdk 0.3.422 → 0.3.424

package/README.md

@@ -44,9 +44,13 @@ const client = new Crouter({
 });
 ```
 
-## Runtime version
+## Runtime compatibility
 
-The SDK talks only to a runtime at or above its own version (`SDK_VERSION`), and has no compatibility mode for older ones: its types, such as `RunObject.activity`, describe what a runtime at its release sends. Every runtime answer carries a `Crouter-Runtime-Version` header. When that version is older than the SDK, or the header is missing (every runtime released before this rule shipped), the call throws `RuntimeVersionError` before the SDK reads the response: `code` is `runtime_version_unsupported`, `status` is 426, `retryable` is false, and `sdkVersion` and `runtimeVersion` name both versions. The SDK also sends its own version on every request except `/healthz` as `Crouter-Minimum-Runtime-Version`; the hosting router and a runtime at this release or later refuse an older runtime with the same 426 *before* any handler runs, so nothing is accepted and no `Idempotency-Key` is recorded (a retry after the roll is a first send). Upgrade the runtime first, then the SDK.
+Compatibility between the SDK and a runtime is a **contract level** (`MAJOR.MINOR`), not the package version. The SDK exports it as `CONTRACT_LEVEL` and its manifest carries it as `crouterContract`. The level changes only when the `/v1` surface changes in a way the release check can see or an author declared, so most releases leave it alone.
+
+Every runtime answer carries `Crouter-Contract` (the levels it serves) and `Crouter-Runtime-Version`. The SDK sends the level it needs on every request except `/healthz` as `Crouter-Required-Contract`. A runtime satisfies it when it serves the same major and a minor at or above the required one. When it does not, or it names no level on a successful answer, the call throws `RuntimeVersionError` before the SDK reads the response: `code` is `runtime_version_unsupported`, `status` is 426, `retryable` is false, and `requiredContract` and `runtimeContract` name both levels (`sdkVersion` and `runtimeVersion` stay for logging). The hosting router and the runtime refuse the same way *before* any handler runs, so nothing is accepted and no `Idempotency-Key` is recorded (a retry after the roll is a first send). Fix it by rolling the runtime forward, or by pinning an SDK whose `crouterContract` the runtime serves.
+
+**`@latest` always works against production.** Every SDK release is published to the `next` dist-tag first; `latest` moves only once production serves the SDK's contract level. `next` may need a newer runtime than production runs. From this contract's first release the SDK also tolerates values it does not know: an unknown run event `type` is passed through to your listener untouched, and an unknown run `status` ends a wait or watch and reports the raw status.
 
 Pin `@north-light/sdk` to an exact version. One release is one version set: `@north-light/sdk@X` depends on exactly `@north-light/api@X` and `@north-light/identity@X`, so the pin fixes all three.
 
@@ -56,7 +60,7 @@ import { RuntimeVersionError } from '@north-light/sdk';
 try {
   await client.runs.get(runId);
 } catch (error) {
-  if (error instanceof RuntimeVersionError) console.error(`runtime ${error.runtimeVersion ?? '(unnamed)'} is older than SDK ${error.sdkVersion}`);
+  if (error instanceof RuntimeVersionError) console.error(`runtime serves contract ${error.runtimeContract ?? '(unnamed)'}, this SDK needs ${error.requiredContract}`);
   else throw error;
 }
 ```

package/dist/client.js

@@ -1,4 +1,4 @@
-import { APIError, CrtrClient, MINIMUM_RUNTIME_VERSION_HEADER, RUNTIME_VERSION_HEADER, compareReleaseVersions, routes, } from '@north-light/api';
+import { APIError, CrtrClient, CONTRACT_HEADER, CONTRACT_LEVEL, MINIMUM_RUNTIME_VERSION_HEADER, REQUIRED_CONTRACT_HEADER, RUNTIME_VERSION_HEADER, contractSatisfies, routes, } from '@north-light/api';
 import { APIConnectionError, APIUserAbortError, AuthenticationError, CrouterError, mapError } from './errors.js';
 import { Bash } from './resources/bash.js';
 import { Canvas } from './resources/canvas.js';
@@ -20,7 +20,7 @@ import { Memory } from './resources/memory.js';
 import { Uploads } from './resources/uploads.js';
 import { deadline, heldReadOptions, withinDeadline } from './resources/request.js';
 import { resolveJsonSchema } from './schema.js';
-import { SDK_VERSION } from './version.js';
+import { LEGACY_FLOOR, SDK_VERSION } from './version.js';
 const LOCAL_SOCKET_FETCH = Symbol.for('@north-light/api/local-socket-fetch');
 const DEFAULT_TIMEOUT_MS = 30_000;
 const POLL_WAIT_SECONDS = 25;
@@ -515,38 +515,43 @@ function isNodeRuntime() {
     return typeof process !== 'undefined' && process.versions?.node !== undefined;
 }
 /**
- * Latest only (P2): the SDK accepts a runtime at or above its own release (`SDK_VERSION`) and nothing older, so its
- * types never describe a field an older runtime does not send. Every runtime response names its release in
- * `Crouter-Runtime-Version`; a successful answer from an older runtime, or one that names no release (every runtime
- * before the header existed), is replaced by a 426 `runtime_version_unsupported` envelope before anything reads it,
- * which the client raises as `RuntimeVersionError`. A refusal without the header passes through unchanged: it can come
- * from a router or proxy in front of the runtime, and it carries no runtime data. `/healthz`, the unversioned
- * substrate probe the cold-start wait polls, is exempt.
+ * The contract gate. The SDK sends the one contract level it needs (`Crouter-Required-Contract`) and the frozen
+ * legacy floor (`Crouter-Minimum-Runtime-Version`, which a runtime from before the contract level refuses on). Every
+ * runtime answer lists the levels it serves in `Crouter-Contract`:
+ * - present and satisfying (same major, served minor at or above the required one): the answer passes;
+ * - present and not satisfying: replaced by a 426 `runtime_version_unsupported` envelope before anything reads it,
+ *   which the client raises as `RuntimeVersionError`;
+ * - absent on a refusal (not ok): passes through unchanged, since it can come from a router or proxy and carries no
+ *   runtime data;
+ * - absent on a success: a runtime from before the contract level, so the same 426.
+ * `/healthz`, the unversioned substrate probe the cold-start wait polls, is exempt.
  */
 function requireCurrentRuntime(inner) {
     const checked = async (input, init) => {
         const url = new URL(input instanceof Request ? input.url : String(input), 'http://localhost');
-        // Say which runtime this SDK accepts, so the router in front of a hosted runtime, or the runtime itself, refuses
-        // an older one before any handler runs. `/healthz` is exempt from both checks.
+        // Say which contract this SDK needs, so the router in front of a hosted runtime, or the runtime itself, refuses an
+        // incompatible one before any handler runs. `/healthz` is exempt from both checks.
         let sentInit = init;
         if (url.pathname !== '/healthz') {
             const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
-            headers.set(MINIMUM_RUNTIME_VERSION_HEADER, SDK_VERSION);
+            headers.set(MINIMUM_RUNTIME_VERSION_HEADER, LEGACY_FLOOR);
+            headers.set(REQUIRED_CONTRACT_HEADER, CONTRACT_LEVEL);
             sentInit = { ...init, headers };
         }
         const response = await (inner ?? globalThis.fetch)(input, sentInit);
         if (url.pathname === '/healthz')
             return response;
-        const runtimeVersion = response.headers.get(RUNTIME_VERSION_HEADER);
-        if (runtimeVersion === null ? !response.ok : compareReleaseVersions(runtimeVersion, SDK_VERSION) >= 0)
+        const served = response.headers.get(CONTRACT_HEADER);
+        if (served === null ? !response.ok : contractSatisfies(CONTRACT_LEVEL, served))
             return response;
         await response.body?.cancel();
-        const message = runtimeVersion === null
-            ? `The runtime did not name its version, so it predates the runtime version header; @north-light/sdk ${SDK_VERSION} requires a runtime at ${SDK_VERSION} or later. Upgrade the runtime, or pin @north-light/sdk to the runtime's release.`
-            : `The runtime is ${runtimeVersion}; @north-light/sdk ${SDK_VERSION} requires a runtime at ${SDK_VERSION} or later. Upgrade the runtime, or pin @north-light/sdk to ${runtimeVersion}.`;
+        const runtimeVersion = response.headers.get(RUNTIME_VERSION_HEADER);
+        const message = served === null
+            ? `The runtime did not name its contract level, so it predates the contract header; @north-light/sdk ${SDK_VERSION} requires contract ${CONTRACT_LEVEL} or later. Upgrade the runtime, or pin @north-light/sdk to an older release that matches it.`
+            : `The runtime serves contract ${served}; @north-light/sdk ${SDK_VERSION} requires contract ${CONTRACT_LEVEL} or later within the same major. Upgrade the runtime, or pin @north-light/sdk to a release whose crouterContract the runtime serves.`;
         return new Response(JSON.stringify({ error: {
                 code: 'runtime_version_unsupported', message, type: 'invalid_request_error', retryable: false,
-                details: { sdk_version: SDK_VERSION, runtime_version: runtimeVersion },
+                details: { sdk_version: SDK_VERSION, runtime_version: runtimeVersion, required_contract: CONTRACT_LEVEL, runtime_contract: served },
             } }), { status: 426, headers: { 'content-type': 'application/json' } });
     };
     if (inner !== undefined && inner[LOCAL_SOCKET_FETCH] === true) {

package/dist/errors.d.ts

@@ -6,12 +6,16 @@ export declare class CrouterError extends APIError {
     readonly code: SdkErrorCode;
     constructor(message: string, code?: SdkErrorCode);
 }
-/** The runtime is older than this SDK (or names no version at all), so the SDK's types do not describe what it
- *  sends. Raised before the SDK reads the response; never retryable. Upgrade the runtime (or pin the SDK to the
+/** The runtime does not serve the contract level this SDK requires (or names no level at all), so the SDK's types do not
+ *  describe what it sends. Raised before the SDK reads the response; never retryable. Upgrade the runtime (or pin the SDK to the
  *  runtime's release). `code` is `runtime_version_unsupported`, `status` 426. */
 export declare class RuntimeVersionError extends APIError {
-    /** The oldest runtime this SDK accepts: its own release version. */
+    /** The legacy minimum-runtime release the SDK sent (or the SDK's own release when the SDK raised this itself). */
     get sdkVersion(): string;
+    /** The contract level the SDK requires (`Crouter-Required-Contract`), or `null` for a refusal that is not about the contract. */
+    get requiredContract(): string | null;
+    /** The contract levels the runtime serves (`Crouter-Contract`), or `null` when it named none. */
+    get runtimeContract(): string | null;
     /** The version the runtime named in `Crouter-Runtime-Version`, or `null` when it sent none (a runtime from before the header existed). */
     get runtimeVersion(): string | null;
 }
@@ -19,6 +23,8 @@ export declare class RuntimeVersionError extends APIError {
 export interface RuntimeVersionDetails {
     sdk_version: string;
     runtime_version: string | null;
+    required_contract?: string;
+    runtime_contract?: string | null;
 }
 /** The daemon rejected the request: HTTP 400. */
 export declare class BadRequestError extends APIError {

package/dist/errors.js

@@ -7,12 +7,16 @@ export class CrouterError extends APIError {
         this.name = 'CrouterError';
     }
 }
-/** The runtime is older than this SDK (or names no version at all), so the SDK's types do not describe what it
- *  sends. Raised before the SDK reads the response; never retryable. Upgrade the runtime (or pin the SDK to the
+/** The runtime does not serve the contract level this SDK requires (or names no level at all), so the SDK's types do not
+ *  describe what it sends. Raised before the SDK reads the response; never retryable. Upgrade the runtime (or pin the SDK to the
  *  runtime's release). `code` is `runtime_version_unsupported`, `status` 426. */
 export class RuntimeVersionError extends APIError {
-    /** The oldest runtime this SDK accepts: its own release version. */
+    /** The legacy minimum-runtime release the SDK sent (or the SDK's own release when the SDK raised this itself). */
     get sdkVersion() { return this.details.sdk_version; }
+    /** The contract level the SDK requires (`Crouter-Required-Contract`), or `null` for a refusal that is not about the contract. */
+    get requiredContract() { return this.details.required_contract ?? null; }
+    /** The contract levels the runtime serves (`Crouter-Contract`), or `null` when it named none. */
+    get runtimeContract() { return this.details.runtime_contract ?? null; }
     /** The version the runtime named in `Crouter-Runtime-Version`, or `null` when it sent none (a runtime from before the header existed). */
     get runtimeVersion() { return this.details.runtime_version; }
 }

package/dist/resources/run-watcher.d.ts

@@ -18,6 +18,15 @@ export type RunEnded = {
     runId: string;
     ended: 'gone';
     run: null;
+}
+/** The run is no longer `running` but its `status` is one this SDK does not know (a runtime newer than the SDK added
+ *  it). It is treated as at rest; `status` is the raw value and `run` the whole answer. */
+ | {
+    userId: string;
+    runId: string;
+    ended: 'unknown';
+    status: string;
+    run: RunObject;
 };
 /** One live-progress reading `RunWatcher` hands to `onActivity`: a `running` run's `activity` and the `runs.get` answer it came from. */
 export interface RunActivityEvent {

package/dist/resources/run-watcher.js

@@ -1,7 +1,7 @@
 import { APIError, CrouterError } from '../errors.js';
 import { Follower, troubleResult } from './follower.js';
 const defaultActivityWait = 2;
-const restingStatuses = new Set(['settled', 'idle', 'waiting_on_user']);
+const knownResting = new Set(['settled', 'idle', 'waiting_on_user']);
 /**
  * Follows an app's background runs until each comes to rest (`settled`, `idle`, `waiting_on_user`, or deleted),
  * and hands each ending to `onEnded` at least once. Build it with `oauth.watchRuns(...)`, then `start()`.
@@ -90,7 +90,9 @@ export class RunWatcher {
                 }
                 return troubleResult(this.follower, error, run);
             }
-            if (!restingStatuses.has(current.status)) {
+            // Only `running` keeps the loop going. Any other status, including one a newer runtime added that this SDK does
+            // not know, is at rest: looping on it would spin forever.
+            if (current.status === 'running') {
                 plain = false;
                 this.resting.delete(run.runId);
                 this.progress(run, current);
@@ -105,7 +107,10 @@ export class RunWatcher {
                 this.resting.add(run.runId);
                 return 'park';
             }
-            return this.deliver(run, key, { userId: run.userId, runId: run.runId, ended: current.status, run: current });
+            const status = current.status;
+            return this.deliver(run, key, knownResting.has(status)
+                ? { userId: run.userId, runId: run.runId, ended: status, run: current }
+                : { userId: run.userId, runId: run.runId, ended: 'unknown', status, run: current });
         }
     }
     /** Hand a running run's activity to `onActivity` once per distinct value, without blocking the follow loop. */

package/dist/resources/runs.d.ts

@@ -187,8 +187,8 @@ export declare class Runs {
     stream(params: RunStartParams, options?: RequestOptions & {
         idempotencyKey?: string;
     }): RunStream;
-    /** Long-polls `runs.get` until the run is `settled`, `waiting_on_user`, or `idle`, and returns that response
-     *  unchanged (`result` is not parsed). Aborting `signal` rejects with its reason and leaves the run as it is. */
+    /** Long-polls `runs.get` until the run is no longer `running` (`settled`, `waiting_on_user`, `idle`, or a status a
+     *  newer runtime added, which counts as at rest), and returns that response unchanged (`result` is not parsed). Aborting `signal` rejects with its reason and leaves the run as it is. */
     wait(runId: string, options?: RequestOptions): Promise<RunObject>;
     /** Start a run with `output_schema` and wait for it to settle; resolves with the outcome and `output_parsed`
      *  typed to the schema. `onQuestion` answers each open question once; without it, a question rejects with

package/dist/resources/runs.js

@@ -133,15 +133,15 @@ export class Runs {
             return this.openEvents(run.run_id, after, signal);
         }, 0, controller.signal);
     }
-    /** Long-polls `runs.get` until the run is `settled`, `waiting_on_user`, or `idle`, and returns that response
-     *  unchanged (`result` is not parsed). Aborting `signal` rejects with its reason and leaves the run as it is. */
+    /** Long-polls `runs.get` until the run is no longer `running` (`settled`, `waiting_on_user`, `idle`, or a status a
+     *  newer runtime added, which counts as at rest), and returns that response unchanged (`result` is not parsed). Aborting `signal` rejects with its reason and leaves the run as it is. */
     async wait(runId, options = {}) {
         // One deadline for the whole wait: every poll shares it instead of restarting `budgetMs`.
         const bounded = deadline(options) ?? options;
         return abortable(bounded.signal, async () => {
             for (;;) {
                 const result = await this.get(runId, { ...bounded, wait: 25 });
-                if (result.status === 'settled' || result.status === 'waiting_on_user' || result.status === 'idle')
+                if (result.status !== 'running')
                     return result;
             }
         });
@@ -170,6 +170,9 @@ export class Runs {
             if (current.status === 'idle') {
                 throw new APIError(0, 'run_idle', 'the run stopped without settling; send runs.message or runs.cancel', undefined, undefined, { retryable: false, run_id: run.run_id });
             }
+            if (current.status !== 'waiting_on_user') {
+                throw new APIError(0, 'run_status_unknown', `the run came to rest with a status this SDK does not know (${String(current.status)}); upgrade @north-light/sdk`, undefined, undefined, { retryable: false, run_id: run.run_id });
+            }
             const open = current.pending_question_ids.filter((id) => !answered.has(id));
             if (!onQuestion) {
                 const questionId = open[0] ?? current.pending_question_ids[0];

package/dist/testing/cloud.d.ts

@@ -77,6 +77,13 @@ export interface FakeCloudOptions {
     runtimeClientId?: string;
     /** The runtime's release; default `SDK_VERSION`. An older one refuses this SDK with 426. */
     runtimeVersion?: string;
+    /** The contract levels the runtime serves, one per major (default `[CONTRACT_LEVEL]`). A request whose
+     *  `Crouter-Required-Contract` no served level satisfies is refused 426 by the runtime. */
+    contract?: string | readonly string[];
+    /** The level the router in front of the runtime has recorded for it (default: the same as `contract`). `null` models
+     *  an unknown level: the router forwards and only the runtime enforces. A request the recorded level does not satisfy
+     *  is refused 426 by the router (origin `router`, no `Crouter-Contract` header) before it reaches the runtime. */
+    routedContract?: string | readonly string[] | null;
     /** Idle close of a run's event stream. Default 60 000 ms. */
     streamIdleMs?: number;
     /** Discovery's `account_app_uri_template`; default `<issuer>/account/apps/{client_id}`, null omits it. */
@@ -263,7 +270,12 @@ export declare class FakeCloud {
     private state;
     private runtimeUrlFor;
     private isRuntimeOrigin;
+    private servedContract;
     private headers;
+    /** The ingress refusals, in the order production applies them, before routing, body parsing, call logging or any
+     *  interceptor: the router's contract check against the level it recorded, then the runtime's legacy version check,
+     *  then the runtime's contract check. `null` when the request may proceed. */
+    private ingressRefusal;
     private route;
     private runIntercepts;
     private directory;

package/dist/testing/cloud.js

@@ -1,6 +1,6 @@
 // FakeCloud: a fake crouter directory and runtime behind one `fetch`, for testing an app's real `OAuth2Client` and
 // `Crouter`. Routing, the call logs, intercepts, users and every runtime operation an app may call.
-import { RUNTIME_VERSION_HEADER, minimumRuntimeRefusal, MINIMUM_RUNTIME_VERSION_HEADER } from '@north-light/api';
+import { CONTRACT_HEADER, CONTRACT_LEVEL, REQUIRED_CONTRACT_HEADER, RUNTIME_VERSION_HEADER, contractRefusal, minimumRuntimeRefusal, MINIMUM_RUNTIME_VERSION_HEADER } from '@north-light/api';
 import { covers } from '@north-light/identity';
 import { createHash } from 'node:crypto';
 import { posix } from 'node:path';
@@ -416,7 +416,37 @@ export class FakeCloud {
             return true;
         return [...this.users.keys()].some((id) => new URL(option(id)).origin === origin);
     }
-    headers() { return { [RUNTIME_VERSION_HEADER]: this.options.runtimeVersion ?? SDK_VERSION }; }
+    servedContract() {
+        const option = this.options.contract ?? CONTRACT_LEVEL;
+        return typeof option === 'string' ? option : option.join(', ');
+    }
+    headers() {
+        return { [RUNTIME_VERSION_HEADER]: this.options.runtimeVersion ?? SDK_VERSION, [CONTRACT_HEADER]: this.servedContract() };
+    }
+    /** The ingress refusals, in the order production applies them, before routing, body parsing, call logging or any
+     *  interceptor: the router's contract check against the level it recorded, then the runtime's legacy version check,
+     *  then the runtime's contract check. `null` when the request may proceed. */
+    ingressRefusal(request) {
+        const required = request.headers.get(REQUIRED_CONTRACT_HEADER) ?? undefined;
+        const legacy = request.headers.get(MINIMUM_RUNTIME_VERSION_HEADER) ?? undefined;
+        const runtimeVersion = this.options.runtimeVersion ?? SDK_VERSION;
+        const refusalResponse = (refusal, origin) => {
+            const error = fakeError({ status: refusal.status, code: refusal.code, message: refusal.message, ...(refusal.status === 426 ? { details: refusal.details } : { param: refusal.param }), origin, retryable: false });
+            return jsonAnswer(envelopeBody(error), error.status, origin === 'runtime' ? this.headers() : {});
+        };
+        const routed = this.options.routedContract === undefined ? this.servedContract() : this.options.routedContract;
+        if (routed !== null) {
+            const refusal = contractRefusal(required, typeof routed === 'string' ? routed : routed.join(', '), { legacyMinimum: legacy, runtimeVersion: null });
+            if (refusal !== null)
+                return refusalResponse(refusal, 'router');
+        }
+        const legacyRefusal = minimumRuntimeRefusal(legacy, runtimeVersion);
+        if (legacyRefusal !== null) {
+            return refusalResponse(legacyRefusal, 'runtime');
+        }
+        const refusal = contractRefusal(required, this.servedContract(), { legacyMinimum: legacy, runtimeVersion });
+        return refusal === null ? null : refusalResponse(refusal, 'runtime');
+    }
     async route(input, init) {
         const request = new Request(input, init);
         const signal = init?.signal ?? (input instanceof Request ? input.signal : null);
@@ -551,6 +581,9 @@ export class FakeCloud {
     }
     // ---- runtime -----------------------------------------------------------------------------------------------------
     async runtime(url, request, signal, claims, sub) {
+        const refused = this.ingressRefusal(request);
+        if (refused !== null)
+            return refused;
         const route = ROUTES.find(([method, pattern]) => method === request.method && pattern.test(url.pathname));
         if (!route)
             return jsonAnswer(envelopeBody(fakeError({ status: 404, code: 'not_found', message: 'unknown operation' })), 404, this.headers());
@@ -589,13 +622,6 @@ export class FakeCloud {
                 return fail(fakeError({ status: scripted, code: scripted >= 500 ? 'server_error' : 'invalid_request', message: `scripted ${scripted}`, retryable: false }));
             return fail(scripted);
         }
-        const minimum = minimumRuntimeRefusal(request.headers.get(MINIMUM_RUNTIME_VERSION_HEADER) ?? undefined, this.options.runtimeVersion ?? SDK_VERSION);
-        if (minimum) {
-            const error = fakeError({ status: minimum.status, code: minimum.code, message: minimum.message, ...(minimum.status === 426 ? { details: minimum.details } : { param: minimum.param }), origin: minimum.status === 426 ? 'router' : 'runtime', retryable: false });
-            call.status = error.status;
-            // A router refusal names no runtime release.
-            return error.status === 426 ? jsonAnswer(envelopeBody(error), 426, {}) : fail(error);
-        }
         try {
             if (!user?.refreshToken || claims === null)
                 throw refuse(401, 'unauthorized', 'a directory access token is required');

package/dist/version.d.ts

@@ -1,2 +1,5 @@
-/** 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.422";
+/** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
+export declare const SDK_VERSION = "0.3.424";
+/** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the
+ *  contract level existed (which only knows this header) refuses this SDK, while every later runtime accepts it. */
+export declare const LEGACY_FLOOR = "0.3.423";

package/dist/version.js

@@ -1,3 +1,8 @@
-// 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.422';
+// SDK_VERSION is written by scripts/release-version.mjs on every release; do not edit by hand.
+/** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
+export const SDK_VERSION = '0.3.424';
+// LEGACY_FLOOR is written once by `scripts/contract.mjs release`, at the first release that carries the contract level
+// (the `0.0.0` placeholder is replaced there and never again); do not edit by hand.
+/** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the
+ *  contract level existed (which only knows this header) refuses this SDK, while every later runtime accepts it. */
+export const LEGACY_FLOOR = '0.3.423';

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.422",
+  "version": "0.3.424",
+  "crouterContract": "1.0",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,11 +37,12 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "tsc -p tsconfig.json && chmod 755 dist/keygen-cli.js"
+    "build": "tsc -p tsconfig.json && chmod 755 dist/keygen-cli.js",
+    "prepublishOnly": "node -e \"if (process.env.npm_config_tag !== 'next') { console.error('@north-light/sdk publishes only with --tag next; scripts/promote-sdk.mjs is the only mover of latest.'); process.exit(1); }\""
   },
   "dependencies": {
-    "@north-light/api": "0.3.422",
-    "@north-light/identity": "0.3.422",
+    "@north-light/api": "0.3.424",
+    "@north-light/identity": "0.3.424",
     "jose": "^6.2.1"
   },
   "peerDependencies": {