@shardflux/sdk 0.11.0 → 0.12.0

package/dist/progress.js

@@ -1,3 +1,55 @@
+const DURABILITY_STATES = new Set(['pending', 'durable', 'lost']);
+/**
+ * The durable copy of a suspend or fork operation (0.12.0+): `result.durability` camelCased, or null when the result has
+ * none (the suspend was stored durably before it completed, or another kind).
+ */
+export function durabilityOf(op) {
+    const d = op.result?.durability;
+    if (typeof d !== 'object' || d === null)
+        return null;
+    const r = d;
+    if (typeof r.state !== 'string' || !DURABILITY_STATES.has(r.state))
+        return null;
+    return {
+        state: r.state,
+        checkpointId: str(r.checkpoint_id),
+        generationId: str(r.generation_id),
+        localCommitAt: str(r.local_commit_at),
+        durableBy: str(r.durable_by),
+        durableAt: str(r.durable_at),
+        localCommitToDurableMs: num(r.local_commit_to_durable_ms),
+        overdueAt: str(r.overdue_at),
+        reason: str(r.reason),
+    };
+}
+/** A resume operation's `result.lost_suspend` camelCased (0.12.0+), or null. */
+export function lostSuspendOf(op) {
+    const l = op.result?.lost_suspend;
+    if (typeof l !== 'object' || l === null)
+        return null;
+    const r = l;
+    const checkpointId = str(r.checkpoint_id);
+    if (!checkpointId)
+        return null;
+    return {
+        checkpointId,
+        generationId: str(r.generation_id),
+        reason: str(r.reason),
+        suspendedAt: str(r.suspended_at),
+        restoredCheckpointId: str(r.restored_checkpoint_id),
+        stateAsOf: str(r.state_as_of),
+    };
+}
+/**
+ * Whether a suspend or fork operation's capture is in durable storage (0.12.0+): `result.durable`, else `true` for a
+ * succeeded suspend or fork whose result predates the field, else null.
+ */
+export function isDurable(op) {
+    const v = op.result?.durable;
+    if (typeof v === 'boolean')
+        return v;
+    return op.state === 'succeeded' && (op.kind === 'suspend' || op.kind === 'fork') ? true : null;
+}
 /** Calls every listener; a listener that throws never breaks the SDK call. */
 export function emitTo(listeners, event) {
     for (const l of listeners) {
@@ -31,9 +83,9 @@ function diffMs(from, to) {
 const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
 const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
 /**
- * When a start waiting in `capacity_pending` gives up: the operation's `error.details.deadline_at` (RFC 3339). A start no
- * host admits by then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or
- * from an API that does not report it.
+ * The deadline of a start in `capacity_pending`: the operation's `error.details.deadline_at` (RFC 3339). A start still
+ * queued then fails with `capacity_unavailable` (retryable; nothing was started). Null in any other state, or from an
+ * API that does not report it.
  */
 export function capacityDeadlineOf(op) {
     if (op.state !== 'capacity_pending')
@@ -66,6 +118,10 @@ export function serverTiming(op) {
         // Unknown (null) unless the result says so: a result without the field is never read as "not restored".
         memoryRestored: typeof r.memory_restored === 'boolean' ? r.memory_restored : null,
         coldBootReason: str(r.cold_boot_reason),
+        durable: typeof r.durable === 'boolean' ? r.durable : null,
+        suspendPath: str(r.suspend_path),
+        durability: durabilityOf(op),
+        lostSuspend: lostSuspendOf(op),
         bootToReadyMs: num(r.boot_to_ready_ms),
         hostTimingsMs,
     };
@@ -76,6 +132,8 @@ function outcomeOf(err) {
         return 'failed';
     if (name === 'OperationTimeoutError')
         return 'timed_out';
+    if (name === 'DurabilityLostError')
+        return 'failed';
     return 'error';
 }
 /** Why a request failed, in one short phrase (for retry records). */
@@ -131,7 +189,7 @@ export class Trace {
     }
     /**
      * Enters a sequential phase (closing the current one). The same phase and reason again is not a new phase.
-     * `deadlineAt`: when a `capacity_pending` start gives up (added to the event only).
+     * `deadlineAt`: the deadline of a `capacity_pending` start (added to the event only).
      */
     phase(phase, reason = null, deadlineAt = null) {
         if (this.#timing)
@@ -218,14 +276,14 @@ export async function traced(trace, fn) {
 }
 const fmt = (ms) => (ms === null ? '?' : ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(2)} s`);
 /**
- * A human-readable account of a timing, for logs and bug reports:
+ * A human-readable account of a timing, for logs and bug reports. A resume in production:
  *
- *   open 34.18 s, succeeded (workspace <id>, operation <id>)
- *     client: request 20.01 s (held) → capacity_pending 13.52 s (no_ready_host) → running 590 ms → view 42 ms ∥ token 61 ms
- *     server: queued 33.40 s, ran 620 ms, total 34.02 s; start warm, boot to ready 79 ms
- *     outside the server: 161 ms
- *     retries: 1 (POST /v1/workspaces/open, HTTP 503 unavailable, after 200 ms)
+ *   resume 413 ms, succeeded (workspace <id>, operation <id>)
+ *     client: request 218 ms → queued 195 ms
+ *     server: queued 51 ms, ran 290 ms, total 341 ms; resume from local_cache, boot to ready 211 ms, host disk 0 ms, load 6 ms, ready 62 ms, total 211 ms, after_restore 36 ms
+ *     outside the server: 72 ms
  *
+ * A call that retried a request adds `retries: <n> (<request>, <cause>, after <delay>)`.
  * A resume that booted the workspace instead of restoring its memory (0.11.0+) says so in the server line:
  * `resume from cold_boot: processes restarted (runtime_changed)`.
  */
@@ -249,6 +307,9 @@ export function formatTiming(t) {
         const how = [
             s.startPath ? `start ${s.startPath}${s.warmFallback ? ` (warm fallback: ${s.warmFallback})` : ''}` : null,
             s.resumePath ? `resume from ${s.resumePath}${s.memoryRestored === false ? `: processes restarted${s.coldBootReason ? ` (${s.coldBootReason})` : ''}` : ''}` : null,
+            s.lostSuspend ? `restored ${s.lostSuspend.restoredCheckpointId ?? 'no checkpoint'} (latest suspend ${s.lostSuspend.checkpointId} ${s.lostSuspend.reason ?? 'lost'})` : null,
+            s.suspendPath === 'local_commit' ? 'sealed on host' : null,
+            s.durability?.state === 'durable' ? `durable${s.durability.localCommitToDurableMs !== null ? ` ${fmt(s.durability.localCommitToDurableMs)} later` : ''}` : s.durability ? `durable copy ${s.durability.state}` : null,
             s.bootToReadyMs !== null ? `boot to ready ${fmt(s.bootToReadyMs)}` : null,
             s.hostTimingsMs ? `host ${Object.entries(s.hostTimingsMs).map(([k, v]) => `${k} ${fmt(v)}`).join(', ')}` : null,
         ].filter(Boolean);

package/dist/tar.d.ts

@@ -1,5 +1,5 @@
 /**
- * A small tar writer for build uploads of folders (contracts §24.2: uncompressed ustar/pax, extracted by the host's
+ * A small tar writer for build uploads of folders (uncompressed ustar/pax, extracted by the host's
  * static tool). Pure: no Node imports, so the browser bundle can carry it.
  *
  * The bytes equal CPython's `tarfile.open(mode="w", format=tarfile.PAX_FORMAT)` with every member added by hand (the

package/dist/tar.js

@@ -1,5 +1,5 @@
 /**
- * A small tar writer for build uploads of folders (contracts §24.2: uncompressed ustar/pax, extracted by the host's
+ * A small tar writer for build uploads of folders (uncompressed ustar/pax, extracted by the host's
  * static tool). Pure: no Node imports, so the browser bundle can carry it.
  *
  * The bytes equal CPython's `tarfile.open(mode="w", format=tarfile.PAX_FORMAT)` with every member added by hand (the

package/dist/template-file.d.ts

@@ -22,7 +22,7 @@ export declare class TemplateFileError extends Error {
     readonly path: string | undefined;
     constructor(message: string, path?: string);
 }
-/** Largest single upload (contracts §24.2: 5 GiB, one presigned PUT). */
+/** Largest single upload (5 GiB, one presigned PUT). */
 export declare const UPLOAD_BYTES_MAX = 5368709120;
 /** Most entries a folder tar may have (the host's extraction limit, §24.2). */
 export declare const TAR_ENTRIES_MAX = 200000;

package/dist/template-file.js

@@ -33,7 +33,7 @@ export class TemplateFileError extends Error {
         this.path = path;
     }
 }
-/** Largest single upload (contracts §24.2: 5 GiB, one presigned PUT). */
+/** Largest single upload (5 GiB, one presigned PUT). */
 export const UPLOAD_BYTES_MAX = 5_368_709_120;
 /** Most entries a folder tar may have (the host's extraction limit, §24.2). */
 export const TAR_ENTRIES_MAX = 200_000;

package/dist/templates.d.ts

@@ -1,5 +1,5 @@
 /**
- * Template registry, custom template builds (recipe v1 Dockerfiles and recipe v2, contracts §24.1), build uploads
+ * Template registry, custom template builds (recipe v1 Dockerfiles and recipe v2), build uploads
  * (§24.2), recipe export, version test instances, package search, the version file tree and diff, and template dev
  * mode (drafts and test instances) over the application API (/v1). Registry and build types are written by hand and
  * checked against the generated contract in type-checks.ts; the Templates v2 and template editor types alias the
@@ -15,7 +15,7 @@ import type { YamlParser } from './template-file.js';
 import type { ToolName } from './tokens.js';
 import { Workspace } from './workspace.js';
 type S = components['schemas'];
-/** Recipe v2 (contracts §24.1): the `recipe` of a build, the export's `recipe` and the document of template.yaml. */
+/** Recipe v2: the `recipe` of a build, the export's `recipe` and the document of template.yaml. */
 export type TemplateRecipeV2 = S['TemplateRecipeV2'];
 /** One `build.files[]` entry: an upload (`upload: "sha256:<hex>"`), or in template.yaml a local path (`from`). */
 export type TemplateRecipeV2File = NonNullable<TemplateRecipeV2['build']['files']>[number];
@@ -40,7 +40,7 @@ export type TemplateVersionRecipe = S['TemplateVersionRecipe'];
 export type TemplatePackage = S['TemplatePackage'];
 export type TemplatePackagePage = S['TemplatePackagePage'];
 export type TemplatePackageEcosystem = 'apt' | 'pip' | 'npm';
-/** The languages a base offers a recipe v2 (contracts §24.6 `GET …/template-languages`): the language table for its platform base. */
+/** The languages a base offers a recipe v2 (`GET …/template-languages`): the language table for its platform base. */
 export type TemplateLanguages = S['TemplateLanguages'];
 export type TemplateLanguage = TemplateLanguages['data'][number];
 export type CreateVersionTestInstanceBody = S['CreateVersionTestInstanceBody'];
@@ -52,18 +52,18 @@ export type TemplateBuildRecipeV2 = Extract<NonNullable<S['TemplateBuild']['reci
 }>;
 /** Start commands and services of a workspace's version (§24.4); null when it has none. */
 export type WorkspaceStartup = S['WorkspaceStartup'];
-/** Manifest v2 `defaults` of a version (contracts §19.7). */
+/** Manifest v2 `defaults` of a version. */
 export type TemplateDefaults = S['TemplateDefaults'];
 /** How a version was produced: a recipe build, a saved workspace (or draft publish), or git (reserved). */
 export type TemplateSource = S['TemplateSource'];
 /** The version's file list state (the tree and diff routes read it). */
 export type TemplateFilesSummary = S['TemplateFilesSummary'];
-/** Storage of a template version (contracts §19.13). */
+/** Storage of a template version. */
 export type TemplateStorage = S['TemplateStorage'];
 export type TemplateStorageWarning = S['TemplateStorageWarning'];
 /** Template storage of an organization (counts toward retained_state_gib). */
 export type OrgTemplateStorage = S['OrgTemplateStorage'];
-/** One inode path of a template version (contracts §19.10). */
+/** One inode path of a template version. */
 export type TemplateFileEntry = S['TemplateFileEntry'];
 /** One directory level of a version's tree (keyset-paginated). */
 export type TemplateFilePage = S['TemplateFilePage'];
@@ -72,7 +72,7 @@ export type TemplateDiffEntry = S['TemplateDiffEntry'];
 export type TemplateDiffChange = TemplateDiffEntry['change'];
 /** One page of a version diff; the first page (no cursor) carries `summary`. */
 export type TemplateDiffPage = S['TemplateDiffPage'];
-/** The live draft of an organization template (contracts §19.9). */
+/** The live draft of an organization template. */
 export type TemplateDraft = S['TemplateDraft'];
 /** A disk-only capture of the draft (a test instance or a publish starts from one). */
 export type DraftState = S['DraftState'];
@@ -164,7 +164,7 @@ export interface TemplateVersion {
         rootfs_sha256: string | null;
     } | null;
     defaults: TemplateDefaults;
-    /** What a workspace of this version gets when it opens (0.7.0; contracts §24.3). `defaults` equals `settings.defaults`. */
+    /** What a workspace of this version gets when it opens (0.7.0). `defaults` equals `settings.defaults`. */
     settings: TemplateSettings;
     /** The file list the tree and diff read (`loaded` when files() and diff() can answer). */
     files: TemplateFilesSummary;
@@ -199,7 +199,7 @@ export interface TemplateSummary {
     created_at: string;
     archived_at: string | null;
     shadowed_by_organization_template: boolean;
-    /** Mutable template-level defaults (contracts §20.5, §20.7): the size of a start without caps.memory_mib, and the idle policy of a workspace that sets none. */
+    /** Mutable template-level defaults: the size of a start without caps.memory_mib, and the idle policy of a workspace that sets none. */
     defaults: {
         memory_mib: number | null;
         idle_policy: string | null;
@@ -347,7 +347,7 @@ export interface TemplateBuild {
     };
     publishable: boolean;
     builder_availability: BuilderAvailability;
-    /** `recipe` (Dockerfile dialect) or `workspace` (save-as-template, draft publish; contracts §19.8). */
+    /** `recipe` (Dockerfile dialect) or `workspace` (save-as-template, draft publish). */
     source_kind: 'recipe' | 'workspace';
     source_workspace_id: string | null;
     /** The captured checkpoint (null until the capture operation succeeded). */
@@ -385,7 +385,7 @@ export interface CreateTemplateBuildParams {
     displayName?: string;
     /**
      * Recipe v1 (a Dockerfile) or recipe v2 (0.7.0; `schema: "shardflux.template-recipe.v2"`: languages, packages,
-     * uploaded files, steps, auto network and settings; contracts §24.1). Recipe v2 files reference uploads
+     * uploaded files, steps, auto network and settings). Recipe v2 files reference uploads
      * (`templates.uploads.put()`); `buildFromFile()` / `buildFromRecipe()` upload local `from` paths for you.
      */
     recipe: TemplateRecipe | TemplateRecipeV2;
@@ -411,7 +411,7 @@ export interface WaitForBuildOptions {
     /** Backoff used when the server does not hold the poll (default 1 s doubling to 10 s). */
     pollIntervalMs?: number;
     maxPollIntervalMs?: number;
-    /** Ask the server to hold each poll until the build changes (`Prefer: wait`, contracts §3; default true). */
+    /** Ask the server to hold each poll until the build changes (`Prefer: wait`; default true). */
     serverWait?: boolean;
     signal?: AbortSignal;
     /** Called with each build view the wait observes whose state or registration changed (0.7.0), the settled one included. */
@@ -429,7 +429,7 @@ export interface SaveAsTemplateResponse {
     operation: Operation | null;
     build: TemplateBuild;
 }
-/** Save-as-template (contracts §19.8): everything in the workspace, minus the sf-scrub.v1 list, becomes one new org layer. */
+/** Save-as-template: everything in the workspace, minus the sf-scrub.v1 list, becomes one new org layer. */
 export interface SaveAsTemplateParams {
     /** Organization template to save into (created when absent; platform slugs are refused with platform_template_slug). */
     templateSlug: string;
@@ -440,7 +440,7 @@ export interface SaveAsTemplateParams {
     /** Defaults of the new version (default: the source version's, else persistent). */
     defaults?: TemplateDefaultsInput;
     /**
-     * Settings of the new version (0.7.0; contracts §24.3): each field given replaces that field of the source version's
+     * Settings of the new version (0.7.0): each field given replaces that field of the source version's
      * settings, each field left out is carried forward. `settings.defaults` together with `defaults` is 422 invalid_settings.
      */
     settings?: TemplateSettingsInput;
@@ -536,7 +536,7 @@ export interface DraftOpened {
     operation: Operation | null;
 }
 /**
- * Template dev mode for one organization template (contracts §19.9): the single live draft (a layered, persistent
+ * Template dev mode for one organization template: the single live draft (a layered, persistent
  * workspace on the draft base), its captured states, disposable test instances (session workspaces on a copy of a
  * state) and publishing the draft as the next version. Mutations need build access (owners/admins, API keys with a
  * tool permission); others get 403 forbidden with details.reason template_dev_mode_role.
@@ -654,7 +654,7 @@ export declare class TemplateUploadError extends Error {
     constructor(sha256: string, status: number, code: string | null, detail?: string);
 }
 /**
- * Build uploads (contracts §24.2): files and folders a recipe v2 copies into the template, stored once per
+ * Build uploads: files and folders a recipe v2 copies into the template, stored once per
  * organization and content (SHA-256). Needs build access (API keys with a tool permission). Uploads count toward the
  * organization's template storage while they exist; one nothing references is deleted 7 days later.
  */
@@ -795,7 +795,7 @@ export interface CreateVersionTestInstanceParams {
     idempotencyKey?: string;
 }
 /**
- * Test instances of a version (contracts §24.6): a session workspace on a registered version of the organization's
+ * Test instances of a version: a session workspace on a registered version of the organization's
  * template, published or not, so a build can be tried before it is published. Owners, admins and API keys with a
  * tool permission (403 template_dev_mode_role otherwise).
  */
@@ -805,7 +805,7 @@ export declare class TemplateVersionTestInstancesApi {
     /** Opens one (202; waits until ready unless `wait: false`). It ends with close() or when idle. */
     create(slug: string, version: number, params?: CreateVersionTestInstanceParams): Promise<Workspace>;
 }
-/** Package names for the editor's pickers (contracts §24.6): apt (a base's index), pip (names only) and npm. */
+/** Package names for the editor's pickers: apt (a base's index), pip (names only) and npm. */
 export declare class TemplatePackagesApi {
     #private;
     constructor(ctx: () => ClientContext);
@@ -848,7 +848,7 @@ export declare class TemplatesApi {
         organizationId?: string;
     }): Promise<TemplateLanguages>;
     /**
-     * Node only: builds a template from template.yaml (or a .json file with the same document; contracts §24.1). The
+     * Node only: builds a template from template.yaml (or a .json file with the same document). The
      * file is recipe v2; each `build.files[]` entry may name a local `from` path (relative to the file): folders are
      * packed as the reproducible tar, files are sent as they are, both uploaded unless the organization already has
      * them, and the build is created (and awaited with `wait`). YAML needs the optional `yaml` package or `parseYaml`.
@@ -885,7 +885,7 @@ export declare class TemplatesApi {
         owner?: TemplateOwner;
     }): Promise<TemplateDetail | null>;
     /**
-     * One directory level of a version's file tree (contracts §19.10), sorted by name bytes. 409 conflict with
+     * One directory level of a version's file tree, sorted by name bytes. 409 conflict with
      * details.reason file_list_unavailable (no file list) or file_list_indexing (retryable); 404 path_not_found or
      * version_not_found; 422 invalid_path. File contents are not served: open a draft or test instance for that.
      */
@@ -901,7 +901,7 @@ export declare class TemplatesApi {
     diff(slug: string, params: TemplateDiffParams): Promise<TemplateDiffPage>;
     /** Every diff entry, following next_cursor. */
     diffAll(slug: string, params: Omit<TemplateDiffParams, 'cursor'>): AsyncGenerator<TemplateDiffEntry>;
-    /** Dev mode of one organization template: its draft, states, test instances and publish (contracts §19.9). */
+    /** Dev mode of one organization template: its draft, states, test instances and publish. */
     draft(slug: string, params?: {
         organizationId?: string;
     }): TemplateDraftApi;

package/dist/templates.js

@@ -53,7 +53,7 @@ async function openedWorkspace(ctx, res, p) {
     return { workspace: new Workspace(ctx, view, wrap), operation };
 }
 /**
- * Template dev mode for one organization template (contracts §19.9): the single live draft (a layered, persistent
+ * Template dev mode for one organization template: the single live draft (a layered, persistent
  * workspace on the draft base), its captured states, disposable test instances (session workspaces on a copy of a
  * state) and publishing the draft as the next version. Mutations need build access (owners/admins, API keys with a
  * tool permission); others get 403 forbidden with details.reason template_dev_mode_role.
@@ -369,7 +369,7 @@ async function sendUpload(ctx, meta, body, organizationId, signal) {
     return { upload: again.body.upload, ref, uploaded: true };
 }
 /**
- * Build uploads (contracts §24.2): files and folders a recipe v2 copies into the template, stored once per
+ * Build uploads: files and folders a recipe v2 copies into the template, stored once per
  * organization and content (SHA-256). Needs build access (API keys with a tool permission). Uploads count toward the
  * organization's template storage while they exist; one nothing references is deleted 7 days later.
  */
@@ -458,7 +458,7 @@ function uploadLocal(ctx, src, organizationId, signal) {
     return sendUpload(ctx, { sha256: src.sha256, size: src.size, kind: src.kind }, { open: () => fileBody(src.uploadPath), replayable: true }, organizationId, signal);
 }
 const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
-// ---- recipe export, version test instances, package search (contracts §24.6) --------------------------------------------
+// ---- recipe export, version test instances, package search --------------------------------------------
 export class TemplateVersionsApi {
     #ctx;
     constructor(ctx) {
@@ -475,7 +475,7 @@ export class TemplateVersionsApi {
     }
 }
 /**
- * Test instances of a version (contracts §24.6): a session workspace on a registered version of the organization's
+ * Test instances of a version: a session workspace on a registered version of the organization's
  * template, published or not, so a build can be tried before it is published. Owners, admins and API keys with a
  * tool permission (403 template_dev_mode_role otherwise).
  */
@@ -504,7 +504,7 @@ export class TemplateVersionTestInstancesApi {
         return (await openedWorkspace(ctx, res, params)).workspace;
     }
 }
-/** Package names for the editor's pickers (contracts §24.6): apt (a base's index), pip (names only) and npm. */
+/** Package names for the editor's pickers: apt (a base's index), pip (names only) and npm. */
 export class TemplatePackagesApi {
     #ctx;
     constructor(ctx) {
@@ -574,7 +574,7 @@ export class TemplatesApi {
         return this.#organization;
     }
     /**
-     * Node only: builds a template from template.yaml (or a .json file with the same document; contracts §24.1). The
+     * Node only: builds a template from template.yaml (or a .json file with the same document). The
      * file is recipe v2; each `build.files[]` entry may name a local `from` path (relative to the file): folders are
      * packed as the reproducible tar, files are sent as they are, both uploaded unless the organization already has
      * them, and the build is created (and awaited with `wait`). YAML needs the optional `yaml` package or `parseYaml`.
@@ -705,7 +705,7 @@ export class TemplatesApi {
         }
     }
     /**
-     * One directory level of a version's file tree (contracts §19.10), sorted by name bytes. 409 conflict with
+     * One directory level of a version's file tree, sorted by name bytes. 409 conflict with
      * details.reason file_list_unavailable (no file list) or file_list_indexing (retryable); 404 path_not_found or
      * version_not_found; 422 invalid_path. File contents are not served: open a draft or test instance for that.
      */
@@ -741,7 +741,7 @@ export class TemplatesApi {
             cursor = page.next_cursor ?? undefined;
         } while (cursor !== undefined);
     }
-    /** Dev mode of one organization template: its draft, states, test instances and publish (contracts §19.9). */
+    /** Dev mode of one organization template: its draft, states, test instances and publish. */
     draft(slug, params = {}) {
         return new TemplateDraftApi(this.#ctx, slug, params.organizationId);
     }

package/dist/tools.d.ts

@@ -49,7 +49,7 @@ export declare function validateArgs(schema: JsonSchema, value: unknown, path?:
 export interface WorkspaceToolsOptions {
     /**
      * Tool permissions to expose (default: the tools of the workspace's last token, else all). A file-first workspace
-     * (`workspace.mode`, contracts §29) gets only the `exec` and `files` tools: `exec` runs each command as an execution
+     * (`workspace.mode`) gets only the `exec` and `files` tools: `exec` runs each command as an execution
      * (a fresh VM on the workspace's files; the result adds `execution_id`, `state`, `changed` and `tree_revision`), and
      * the process, terminal, git and browser tools are not offered because nothing runs between executions.
      */
@@ -70,7 +70,7 @@ export interface WorkspaceToolsOptions {
      * Send `workspace.hint()` when a tool call starts, without waiting for it (default true; 0.9.0+), so a parked
      * workspace is being restored while the call is prepared. Pass false when you call `workspace.hint()` yourself
      * earlier (e.g. when the model starts streaming a tool call). `read_file`, `list_files` and `search_files` never send
-     * it: a sleeping workspace serves them from its disk without waking (contracts §26.4), and the hint would wake a
+     * it: a sleeping workspace serves them from its disk without waking, and the hint would wake a
      * suspended workspace (or restore a hibernated one) that the read does not need.
      */
     hint?: boolean;
@@ -81,7 +81,7 @@ export interface WorkspaceToolsOptions {
     mode?: WorkspaceMode;
     /**
      * File-first workspaces: called with the execution id before the `exec` tool sends its execution (0.9.0+). An
-     * execution cannot be canceled, so a caller that stops waiting (an aborted signal) can still fetch its result later
+     * execution runs to completion, so a caller that stops waiting (an aborted signal) can still fetch its result later
      * with `workspace.executions.get(id)`.
      */
     onExecution?: (executionId: string) => void;

package/dist/tools.js

@@ -83,11 +83,11 @@ export function validateArgs(schema, value, path = '$') {
     return issues;
 }
 const ALL = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
-/** The tool permissions whose tools work on a file-first workspace (contracts §29.8): files and executions. */
+/** The tool permissions whose tools work on a file-first workspace: files and executions. */
 const FILE_FIRST_TOOLS = ['exec', 'files'];
 /** Changed paths returned to the model per execution (the rest is flagged `changed_truncated`). */
 const MAX_CHANGED_LISTED = 200;
-/** Tools served from a sleeping workspace's disk without waking it (contracts §26.4): the runner sends no hint. */
+/** Tools served from a sleeping workspace's disk without waking it: the runner sends no hint. */
 const DISK_READS = new Set(['read_file', 'list_files', 'search_files']);
 const obj = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
 const path = (description = 'Absolute path inside the workspace, e.g. /home/user/project/main.py') => ({ type: 'string', minLength: 1, maxLength: 4096, description });
@@ -107,7 +107,7 @@ export function workspaceTools(workspace, opts = {}) {
     });
     const max = opts.maxOutputBytes ?? 65_536;
     const prefix = opts.prefix ?? '';
-    // A file-first workspace (contracts §29) has files and executions only: no processes, terminals, version control or
+    // A file-first workspace has files and executions only: no processes, terminals, version control or
     // browser between calls, so those tools are not offered, and exec runs each command as an execution.
     const fileFirst = (opts.mode ?? workspace.mode) === 'file_first';
     const allowed = new Set((opts.tools ?? workspace.grantedTools ?? ALL).filter((t) => !fileFirst || FILE_FIRST_TOOLS.includes(t)));
@@ -436,7 +436,7 @@ export function workspaceTools(workspace, opts = {}) {
             const issues = validateArgs(d.parameters, args);
             if (issues.length > 0)
                 throw new ToolArgumentError(`${prefix}${d.name}`, issues);
-            // Fire and forget: a parked workspace starts restoring while this call is prepared (contracts §26.6). Not for
+            // Fire and forget: a parked workspace starts restoring while this call is prepared. Not for
             // the reads a sleeping workspace serves from its disk (§26.4): the hint would wake it for nothing.
             if (opts.hint !== false && !DISK_READS.has(d.name)) {
                 workspace

package/dist/version-check.d.ts

@@ -1,5 +1,5 @@
 /**
- * Client version check (contracts §30.4; 0.9.0+). `GET /v1/client-versions` (unauthenticated) lists every published
+ * Client version check (0.9.0+). `GET /v1/client-versions` (unauthenticated) lists every published
  * client with its `latest` and `minimum_supported` version.
  *
  *   const s = await checkClientVersion();            // @shardflux/sdk at SDK_VERSION

package/dist/volumes.d.ts

@@ -1,5 +1,5 @@
 /**
- * Shared volumes over the application API (/v1, contracts §15). Types come from
+ * Shared volumes over the application API (/v1). Types come from
  * the generated OpenAPI document (schemas `Volume` and `VolumeAttachment`).
  *
  * A volume is persistent shared storage (EFS-backed) owned by a project. It is