@intentic/extension-api 1.311.0 → 1.312.0

package/README.md

@@ -14,14 +14,15 @@ flowchart LR
 - There is no ambient global. The host hands `IntenticApi` to `activate(api, context)`, and everything registered
   returns a `Disposable`. A manifest's `server` bundle gets `ExtensionServerApi` in a Node process shared by every
   enabled extension, and reaches daemon routes only as far as `permissions.daemon` allows.
-- This package is the one exception to the repo's no-legacy rule. It is published to npm, `extensionApiVersion` moves
+- This package is published to npm, and its API only grows within a major. `extensionApiVersion` moves
   with every surface change (additive is a minor), and a manifest's `engines.intentic` range is matched against it at
   load, failing closed. The editor's `surface-guard.test.ts` fails when the surface moves without a new entry in
   `src/surface.json`.
 - Helpers every extension needs live here too: sandbox-scoped module state (`sandboxRef`, cleared on every sandbox
   switch), background polling for rail badges, `sandboxLedger` (whose writes reject rather than overwrite a file they
-  could not read), SSE and ndjson stream reading, and the payload for
-  `api.workspace.openDiff`.
+  could not read), `sandboxDocument` (a file of the extension's own read through the `conversions` its shape has had,
+  and written with what a newer version of the extension put in it kept), SSE and ndjson stream reading, and the
+  payload for `api.workspace.openDiff`.
 - Contribution points: `agent`, `automationTemplates`, `bin`, `capabilities`, `commands`, `documents`,
   `environment`, `files`, `listener`, `processes`, `settings`, `viewers` and `views`, plus the manifest's top-level
   fields, all read off `CONTRIBUTION_POINTS` in

package/dist/background.d.ts

@@ -1,3 +1,4 @@
+import { type Conversion, type Granularity } from "@intentic/sandbox-contract/documents";
 import type { Ref } from "vue";
 import type { Disposable, IntenticApi } from "./api.js";
 export interface SandboxPoll<T> {
@@ -20,4 +21,33 @@ export interface SandboxLedger {
     replace(entries: Readonly<Record<string, string>>): Promise<boolean>;
 }
 export declare const sandboxLedger: (host: () => IntenticApi, path: string) => SandboxLedger;
+export declare const conversions: {
+    readonly at: <const Path extends string, const Inner extends Conversion>(path: Path, inner: Inner) => import("@intentic/sandbox-contract/documents").AtConversion<Path, Inner>;
+    readonly drop: <const Key extends string>(key: Key) => import("@intentic/sandbox-contract/documents").DropConversion<Key>;
+    readonly dropAll: <const Keys extends readonly string[]>(keys: Keys) => { readonly [I in keyof Keys]: import("@intentic/sandbox-contract/documents").DropConversion<Keys[I] & string>; };
+    readonly fold: <const From extends string, const Into extends string, Out>(describe: string, shape: {
+        readonly from: readonly From[];
+        readonly into: Into;
+        readonly applies: (value: import("@intentic/sandbox-contract/documents").JsonObject) => boolean;
+        readonly convert: (fields: Readonly<Partial<Record<From, unknown>>>, whole: import("@intentic/sandbox-contract/documents").JsonObject) => Out;
+    }) => import("@intentic/sandbox-contract/documents").FoldConversion<From, Into, Out>;
+    readonly mapValue: <const Key extends string, const Mapping extends Readonly<Record<string, unknown>>>(key: Key, mapping: Mapping) => import("@intentic/sandbox-contract/documents").MapValueConversion<Key, Mapping>;
+    readonly nested: <const Path extends string, const History extends readonly Conversion[], const Entries extends boolean = false>(path: Path, history: History, entries?: Entries) => { readonly [I in keyof History]: History[I] extends import("@intentic/sandbox-contract/documents").RetireEntriesConversion<unknown> ? import("@intentic/sandbox-contract/documents").AtConversion<Path, History[I]> : import("@intentic/sandbox-contract/documents").AtConversion<Entries extends true ? `${Path}.*` : Path, History[I]>; };
+    readonly pinDefault: <const Key extends string, const Value>(key: Key, value: Value) => import("@intentic/sandbox-contract/documents").PinDefaultConversion<Key, Value>;
+    readonly rename: <const From extends string, const To extends string>(from: From, to: To) => import("@intentic/sandbox-contract/documents").RenameConversion<From, To>;
+    readonly retireEntries: <Retired>(describe: string, isRetired: (entry: unknown) => entry is Retired) => import("@intentic/sandbox-contract/documents").RetireEntriesConversion<Retired>;
+    readonly retype: <const Key extends string, In, Out>(key: Key, guard: (value: unknown) => value is In, convert: (value: In) => Out, describe?: string) => import("@intentic/sandbox-contract/documents").RetypeConversion<Key, In, Out>;
+    readonly transform: <In extends import("@intentic/sandbox-contract/documents").JsonObject, Out extends import("@intentic/sandbox-contract/documents").JsonObject>(describe: string, applies: (value: import("@intentic/sandbox-contract/documents").JsonObject) => value is In, convert: (value: In) => Out) => import("@intentic/sandbox-contract/documents").TransformConversion<In, Out>;
+};
+export interface SandboxDocument<T> {
+    read(): Promise<T>;
+    update(change: (current: T) => T): Promise<boolean>;
+}
+export interface SandboxDocumentOptions<T> {
+    readonly parse: (raw: unknown) => T | undefined;
+    readonly fallback: () => T;
+    readonly history?: readonly Conversion[];
+    readonly granularity?: Granularity;
+}
+export declare const sandboxDocument: <T>(host: () => IntenticApi, path: string, options: SandboxDocumentOptions<T>) => SandboxDocument<T>;
 //# sourceMappingURL=background.d.ts.map

package/dist/background.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"background.d.ts","sourceRoot":"","sources":["../src/background.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAOxD,MAAM,WAAW,WAAW,CAAC,CAAC;IAE1B,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAEvB,KAAK,IAAI,UAAU,CAAC;IAEpB,OAAO,IAAI,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IAEjC,QAAQ,CAAC,IAAI,EAAE,MAAM,WAAW,CAAC;IAEjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE1B,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAE7D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAE7B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC;CAC5C;AAqFD,eAAO,MAAM,WAAW,GAAI,CAAC,WAAW,kBAAkB,CAAC,CAAC,CAAC,KAAG,WAAW,CAAC,CAAC,CAsC5E,CAAC;AAKF,MAAM,WAAW,aAAa;IAE1B,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAElD,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAElE,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE;AAKD,eAAO,MAAM,aAAa,SAAU,MAAM,WAAW,QAAQ,MAAM,KAAG,aA8CrE,CAAC"}
+{"version":3,"file":"background.d.ts","sourceRoot":"","sources":["../src/background.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,KAAK,UAAU,EAKf,KAAK,WAAW,EAQnB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAOxD,MAAM,WAAW,WAAW,CAAC,CAAC;IAE1B,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAEvB,KAAK,IAAI,UAAU,CAAC;IAEpB,OAAO,IAAI,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IAEjC,QAAQ,CAAC,IAAI,EAAE,MAAM,WAAW,CAAC;IAEjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE1B,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAE7D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAE7B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC;CAC5C;AAqFD,eAAO,MAAM,WAAW,GAAI,CAAC,WAAW,kBAAkB,CAAC,CAAC,CAAC,KAAG,WAAW,CAAC,CAAC,CAsC5E,CAAC;AAKF,MAAM,WAAW,aAAa;IAE1B,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAElD,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAElE,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE;AAKD,eAAO,MAAM,aAAa,SAAU,MAAM,WAAW,QAAQ,MAAM,KAAG,aA8CrE,CAAC;AAKF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;CAA+G,CAAC;AAMxI,MAAM,WAAW,eAAe,CAAC,CAAC;IAE9B,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAGnB,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC;IAErC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAE3B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAEzC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACtC;AAED,eAAO,MAAM,eAAe,GAAI,CAAC,QAAQ,MAAM,WAAW,QAAQ,MAAM,WAAW,sBAAsB,CAAC,CAAC,CAAC,KAAG,eAAe,CAAC,CAAC,CA+C/H,CAAC"}

package/dist/background.js

@@ -1,3 +1,4 @@
+import { at, carryUnknown, convertDocument, drop, dropAll, fold, mapValue, nested, pinDefault, rename, retireEntries, retype, transform, } from "@intentic/sandbox-contract/documents";
 import { sandboxRef, sandboxScopeGuard } from "./scope.js";
 const WAKE_MS = 400;
 const scheduledReads = [];
@@ -142,4 +143,50 @@ export const sandboxLedger = (host, path) => {
         replace: async (entries) => settle(() => entries),
     };
 };
+export const conversions = { at, drop, dropAll, fold, mapValue, nested, pinDefault, rename, retireEntries, retype, transform };
+export const sandboxDocument = (host, path, options) => {
+    const convert = (raw) => convertDocument(options.history ?? [], options.granularity ?? `object`, raw).value;
+    const readRaw = async () => {
+        const answer = await host().sandbox.rpc.workspace.file({ path });
+        if (!answer.present) {
+            return undefined;
+        }
+        return convert(JSON.parse(answer.content));
+    };
+    const read = async () => {
+        try {
+            const raw = await readRaw();
+            return (raw === undefined ? undefined : options.parse(raw)) ?? options.fallback();
+        }
+        catch {
+            return options.fallback();
+        }
+    };
+    let queue = Promise.resolve();
+    const update = (change) => {
+        const run = async () => {
+            const current = sandboxScopeGuard();
+            const raw = await readRaw();
+            const parsed = raw === undefined ? undefined : options.parse(raw);
+            if (raw !== undefined && parsed === undefined) {
+                throw new Error(`${path} holds what this version of the extension cannot read; it is left as it is`);
+            }
+            const before = parsed ?? options.fallback();
+            const after = change(before);
+            if (after === before) {
+                return true;
+            }
+            if (!current()) {
+                return false;
+            }
+            const written = raw === undefined ? after : carryUnknown(raw, parsed, after);
+            await host().workspace.write(path, `${JSON.stringify(written, undefined, 2)}\n`);
+            return true;
+        };
+        const next = queue.then(run, run);
+        queue = next.catch(() => undefined);
+        return next;
+    };
+    return { read, update };
+};
 //# sourceMappingURL=background.js.map

package/dist/background.js.map

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

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const extensionApiVersion = "2.18.0";
+export declare const extensionApiVersion = "2.19.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AA+GA,eAAO,MAAM,mBAAmB,WAAW,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAmHA,eAAO,MAAM,mBAAmB,WAAW,CAAC"}

package/dist/version.js

@@ -1,2 +1,2 @@
-export const extensionApiVersion = "2.18.0";
+export const extensionApiVersion = "2.19.0";
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AA+GA,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAmHA,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/extension-api",
-  "version": "1.311.0",
+  "version": "1.312.0",
   "description": "The versioned public API intentic extensions compile against, manifest schema, detection facts and the host API",
   "license": "MIT",
   "type": "module",
@@ -42,8 +42,8 @@
     }
   },
   "dependencies": {
-    "@intentic/sandbox-contract": "1.311.0",
-    "@orpc/contract": "1.14.13",
+    "@intentic/sandbox-contract": "1.312.0",
+    "@orpc/contract": "1.15.4",
     "tslib": "2.8.1"
   },
   "peerDependencies": {
@@ -51,9 +51,9 @@
   },
   "devDependencies": {
     "@intentic/tsconfig": "0.0.0",
-    "@types/node": "24.13.2",
+    "@types/node": "24.13.6",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "vue": "3.5.40"
+    "vue": "3.5.43"
   },
   "scripts": {
     "build": "tsgo",

package/src/background.ts

@@ -1,3 +1,20 @@
+import {
+    at,
+    carryUnknown,
+    type Conversion,
+    convertDocument,
+    drop,
+    dropAll,
+    fold,
+    type Granularity,
+    mapValue,
+    nested,
+    pinDefault,
+    rename,
+    retireEntries,
+    retype,
+    transform,
+} from "@intentic/sandbox-contract/documents";
 import type { Ref } from "vue";
 import type { Disposable, IntenticApi } from "./api.js";
 import { sandboxRef, sandboxScopeGuard } from "./scope.js";
@@ -215,3 +232,79 @@ export const sandboxLedger = (host: () => IntenticApi, path: string): SandboxLed
         replace: async (entries) => settle(() => entries),
     };
 };
+
+// The vocabulary an extension's stored file evolves by, the same the daemon's own stores use: each a guarded, pure
+// rewrite of the raw JSON, a no-op on a file already past it, so a file from any earlier version of the extension reads
+// as today's shape. One namespace rather than ten loose names, since `rename` and `drop` are an author's words too.
+export const conversions = { at, drop, dropAll, fold, mapValue, nested, pinDefault, rename, retireEntries, retype, transform } as const;
+
+// A file an extension keeps under the workspace (its own record, cache or settings), read through the conversions its
+// shape has had, and written with everything a NEWER version of the extension put in it kept in place, so switching an
+// extension back never deletes what the later version recorded. A file that exists but cannot be read is left alone:
+// `update` rejects rather than writing its fallback over it.
+export interface SandboxDocument<T> {
+    // Today's value: the file converted and parsed; the fallback when it is absent or this version cannot read it.
+    read(): Promise<T>;
+    // Read-change-write, serialized through this handle. Returning `current` unchanged writes nothing; `false` means only
+    // that the sandbox changed mid-write, and nothing was written.
+    update(change: (current: T) => T): Promise<boolean>;
+}
+
+export interface SandboxDocumentOptions<T> {
+    // Today's shape, or undefined for a file this version cannot read.
+    readonly parse: (raw: unknown) => T | undefined;
+    readonly fallback: () => T;
+    // Append-only: a conversion is never edited or removed once shipped, only followed by another.
+    readonly history?: readonly Conversion[];
+    // Where the conversions apply: the document, each entry of a top-level array, or each value of an object keyed by id.
+    readonly granularity?: Granularity;
+}
+
+export const sandboxDocument = <T>(host: () => IntenticApi, path: string, options: SandboxDocumentOptions<T>): SandboxDocument<T> => {
+    const convert = (raw: unknown): unknown => convertDocument(options.history ?? [], options.granularity ?? `object`, raw).value;
+    // Absent is undefined; present but unreadable throws, so no caller mistakes it for absent.
+    const readRaw = async (): Promise<unknown> => {
+        // Through the contract's own read, which throws for a refused or unreachable read where `readJson` answers absent.
+        const answer = await host().sandbox.rpc.workspace.file({ path });
+        if (!answer.present) {
+            return undefined;
+        }
+        return convert(JSON.parse(answer.content));
+    };
+    const read = async (): Promise<T> => {
+        try {
+            const raw = await readRaw();
+            return (raw === undefined ? undefined : options.parse(raw)) ?? options.fallback();
+        } catch {
+            // silent-catch: a file this version cannot read reads as the fallback, the contract `read` states.
+            return options.fallback();
+        }
+    };
+    let queue: Promise<unknown> = Promise.resolve();
+    const update = (change: (current: T) => T): Promise<boolean> => {
+        const run = async (): Promise<boolean> => {
+            const current = sandboxScopeGuard();
+            const raw = await readRaw();
+            const parsed = raw === undefined ? undefined : options.parse(raw);
+            if (raw !== undefined && parsed === undefined) {
+                throw new Error(`${path} holds what this version of the extension cannot read; it is left as it is`);
+            }
+            const before = parsed ?? options.fallback();
+            const after = change(before);
+            if (after === before) {
+                return true;
+            }
+            if (!current()) {
+                return false;
+            }
+            const written = raw === undefined ? after : carryUnknown(raw, parsed, after);
+            await host().workspace.write(path, `${JSON.stringify(written, undefined, 2)}\n`);
+            return true;
+        };
+        const next = queue.then(run, run);
+        // silent-catch: the queue only orders the next update behind this one; this one's caller still gets its rejection
+        queue = next.catch(() => undefined);
+        return next;
+    };
+    return { read, update };
+};

package/src/surface.json

@@ -1609,5 +1609,117 @@
             "request",
             "rpc"
         ]
+    },
+    "2.19.0": {
+        "manifest": [
+            "$schema",
+            "art",
+            "category",
+            "contributes",
+            "engines",
+            "entry",
+            "icon",
+            "logo",
+            "name",
+            "permissions",
+            "publisher",
+            "server",
+            "version"
+        ],
+        "contributes": [
+            "agent",
+            "automationTemplates",
+            "bin",
+            "capabilities",
+            "commands",
+            "documents",
+            "environment",
+            "files",
+            "listener",
+            "processes",
+            "settings",
+            "viewers",
+            "views"
+        ],
+        "api": [
+            "apiVersion",
+            "audience",
+            "chat",
+            "commands",
+            "documents",
+            "href",
+            "models",
+            "navigate",
+            "processes",
+            "route",
+            "sandbox",
+            "settings",
+            "terminal",
+            "theme",
+            "viewers",
+            "views",
+            "workspace"
+        ],
+        "listener": [
+            "automation",
+            "events",
+            "provider"
+        ],
+        "sandboxApi": [
+            "fetch",
+            "json",
+            "key",
+            "origin",
+            "previewAddress",
+            "reachable",
+            "request",
+            "role",
+            "rpc"
+        ],
+        "moduleExports": [
+            "conversions",
+            "extensionApiVersion",
+            "flattenQuery",
+            "hostSlot",
+            "mergeQuery",
+            "readDaemonStream",
+            "resetSandboxScope",
+            "sandboxDocument",
+            "sandboxLedger",
+            "sandboxPoll",
+            "sandboxRef",
+            "sandboxScopeGuard",
+            "sandboxShallowRef",
+            "sandboxValue",
+            "satisfiesEngines"
+        ],
+        "workspaceApi": [
+            "capabilities",
+            "file",
+            "fillDiff",
+            "inProject",
+            "onDidChange",
+            "onDidChangeFiles",
+            "onDidChangeProject",
+            "onDidChangeRefs",
+            "onDidChangeRepos",
+            "openDiff",
+            "project",
+            "readJson",
+            "repos",
+            "setProject",
+            "write"
+        ],
+        "chatApi": [
+            "composeLoop",
+            "composeWorkflow",
+            "openAgent",
+            "openSession"
+        ],
+        "daemonApi": [
+            "json",
+            "request",
+            "rpc"
+        ]
     }
 }

package/src/version.ts

@@ -1,6 +1,6 @@
 // The extension API's protocol version, the value `engines.intentic` ranges are matched against at load, and
 // the value the host reports as IntenticApi.apiVersion. Bumped ONLY with the published package: additive
-// surface = minor, breaking = major. This package is the one deliberate exception to the repo's no-legacy rule.
+// surface = minor, breaking = major; published, so its surface only grows within a major.
 //
 // 1.0.0 rather than 0.5.0, and the reason is the drift that forced that bump. While the major was 0 the caret
 // matcher treats the MINOR as breaking (engines.ts), so every addition invalidated every declared range, which
@@ -109,4 +109,8 @@
 // server.ts): the backend half was the one surface no recorded grain could see.
 // 2.18.0 adds `api.workspace.onDidChangeRepos`: the repository set moving (a clone, a scaffold, a delete). `repos()` is
 // narrowed to the open project, so a view listing every repository (the Projects dashboard) could only poll. Additive.
-export const extensionApiVersion = "2.18.0";
+// 2.19.0 adds `sandboxDocument` and the `conversions` vocabulary: a file an extension keeps, read through the
+// conversions its shape has had and written with what a newer version of the extension put in it kept in place, the
+// evolution the daemon's own stores got (the daemon's store/evolution/conversions.ts). Until now an extension that changed the
+// shape of its own file had two choices, a hand-written tolerant reader or a reset for everyone who updated. Additive.
+export const extensionApiVersion = "2.19.0";