@intentic/extension-api 1.310.0 → 1.312.0

package/README.md

@@ -1,196 +1,40 @@
-# @intentic/extension-api
+# extension-api
 
-The one SDK an extension programs against: the extension-author contract for the intentic app.
+The versioned public API an intentic extension compiles against: `IntenticApi` for its browser half, `ExtensionServerApi` for its backend half, and the helpers both halves share.
 
-One of the packages an extension may depend on, with `@intentic/extension-manifest`,
-`@intentic/extension-ui` and `@intentic/sandbox-contract`. Published to npm; it must stay free of app
-internals. See the extension system in [ARCHITECTURE.md](../../ARCHITECTURE.md) for how the host loads and
-gates extensions.
-
-It **does** name `@intentic/sandbox-contract` types, and that is deliberate: `api.sandbox.rpc` (and the backend's
-`api.daemon.rpc`) is the daemon's own contract as a typed client, which is the whole reason an extension no longer has to build a URL to reach
-it. The dependency is type-only, so nothing of the contract lands in an extension's runtime. This used to be
-forbidden: the contract imported the manifest schema from here, so depending back would have closed a cycle.
-`@intentic/extension-manifest` exists to break exactly that, and its README has the reasoning.
-
-## What's here
-
-- **[api.ts](src/api.ts)**: `IntenticApi`, the host surface delivered to `activate(api, context)`. There is
-  no ambient global; everything an extension registers is a `Disposable` pushed onto
-  `context.subscriptions`, so deactivation unwinds it. `api.sandbox.rpc` is the typed daemon client, gated by
-  the manifest's `permissions.sandbox` allowlist exactly as the older `request`/`json` doors are.
-- **The manifest schema lives in [@intentic/extension-manifest](../extension-manifest)**, not here: it is what
-  an extension *declares*, and the daemon needs it without needing any of this package. The manifest is the
-  **approval + gating surface**: the install dialog shows exactly the declared contribution points, and the host
-  refuses any runtime registration (view, command, viewer, setting, process…) the approved manifest never
-  declared. Contribution points: `views`, `files`, `viewers`, `documents`, `commands`, `settings`,
-  `processes`, `agent`, `environment`, `capabilities`, `listener`, `automationTemplates`, `bin`, plus the
-  `permissions.sandbox` route allowlist. That list is not prose to be kept in sync by hand:
-  `surface-guard.test.ts` reads it back out of this file and fails when it stops matching the schema.
-  Every one of those points carries its own description, generated out to
-  [an authoring schema](https://intentic.dev/intentic-extension.schema.json); point a manifest's `$schema` at
-  it and an editor completes the fields, explains what each does, and marks a key nothing declares.
-  A `listener` owns both halves of its public vocabulary: labelled event types for daemon validation and the
-  source/filter/starter wording a generic automation editor renders. Installing a listener therefore adds a
-  configurable automation source without an app release or a second provider table.
-  `automationTemplates` is the other half of that bargain: the starting points for a pack's own service:
-  trigger, prompt, guard, setup instructions: declared by whoever knows the service rather than written into
-  the automations surface. Both fold into one catalogue the daemon serves (`GET /automations/catalog`), which
-  is also what `POST /automations` validates against, so the editor cannot offer a trigger the daemon refuses.
-  Identity is derived, never declared: `extensionIdOf(manifest) = ${publisher}.${name}`.
-- **[facts.ts](src/facts.ts)**: the stable **detection** vocabulary (`RepoFacts`, `CapabilityFacts`) a
-  view's `detect()` reads to decide when to activate. This is *not* the data plane.
-- **[server.ts](src/server.ts)**: `ExtensionServerApi`, the BACKEND half's surface. A manifest `server`
-  bundle exports `activateServer(api, context)` and runs in the daemon's backend host (one separate
-  supervised process shared by every enabled backend); `api.routes.mount` serves the extension's own
-  `/x/<id>/…` namespace, `api.daemon.rpc` reaches the daemon's routes under the manifest's
-  `permissions.daemon` allowlist, and workspace files are plain `node:fs` under `api.workspaceRoot`: full
-  trust, so paths rather than a file service. The extension's own namespace needs no `permissions.sandbox`
-  entry on the UI side: its backend is its own.
-
-Three surfaces, at three different grains, and the grain is what picks one. A **view** activates per *repo*
-off the facts (`rail`, `directory`, `sandbox`). A **viewer** takes over a *file extension*. A **document**
-answers per *directory*: `detect(path)` marks the rows it can explain in the Workspace tree, and the host
-opens the provider's component as a tab beside the code. A monorepo is one repo with fifty-five documented
-packages, which is exactly the case a per-repo `detect()` cannot express. An offer that is EVIDENCE about the
-directory rather than an affordance every directory of its kind has says so (`evidence: true`), and the tree
-keeps its icon on the row instead of revealing it on hover: the difference between a reader seeing which
-packages have a page and a reader having to go looking for one.
-- **[scope.ts](src/scope.ts)**, `sandboxRef` (with `sandboxShallowRef` and `sandboxValue`) and
-  `sandboxScopeGuard`: how an extension keeps state that belongs to ONE sandbox. See "Where state lives" below;
-  this is the rule most easily got wrong, because getting it wrong looks fine until somebody switches sandbox.
-- **[background.ts](src/background.ts)**, `sandboxPoll` and `sandboxLedger`: the work an extension does while
-  none of it is on screen. A tile that badges has to be filled by something, and what has already been seen has
-  to be written down somewhere; both were hand-written in six extensions before they were here.
-- **[stream.ts](src/stream.ts)**, **[version.ts](src/version.ts)**: SSE/ndjson helpers and the host API
-  version (`engines.intentic` is checked against it before activation).
-
-Version 2 makes listener contributions self-describing (`events` + `automation`); version 1 listeners only
-declared bare event ids and cannot describe a generic editor. Version 2.1 adds the backend half: the
-manifest `server` bundle and `permissions.daemon`, additively: a 2.0 manifest is a 2.1 manifest that ships
-no backend.
-
-## The data plane
-
-An extension talks to the daemon through `api.sandbox.rpc`, the daemon's own contract as a typed client: a call
-names a procedure (`api.sandbox.rpc.ci.runs()`), its input is checked at build time, and its answer arrives parsed
-by the procedure's output schema, so there is no path to spell and no parse to write. Auth is injected host-side;
-the bundle never sees a token. **Its reach is not unrestricted:** the host resolves each call to the method and
-path it will send and matches that against the manifest's `permissions.sandbox` allowlist, the same gate
-`request`/`json` pass through, and an undeclared route throws before anything is sent.
-
-`request(path)` stays for what the contract does not carry: bytes (`/workspace/raw`), uploads, an extension's own
-`/x/<id>/` backend. `json(path)` stays in the published surface for extensions built against it; every extension
-in this repository calls a contract route through `rpc` (the `contract-paths` check holds them to it).
-
-A backend reaches the daemon the same way, through `api.daemon.rpc`: the same typed client, built by the daemon's
-backend host and handed to `activateServer`, so a server bundle carries no client of its own. It presents the
-extension's minted grant, and the host refuses a call before sending it unless the manifest's `permissions.daemon`
-covers the method and path it resolves to: the verdict the daemon's grant reaches for the same call through
-`api.daemon.request`, which stays for bytes (`/workspace/raw`), as `json` does for backends built against it.
-
-The in-repo, compiled-together design means a wire change is a compiler error fixed atomically, so there is no
-separate "stable data API" to promote. `facts.ts` stays the stable surface only for *detection*.
-
-## Where state lives
-
-Three tiers, and the tier decides what happens when the user points the browser at a **different sandbox**.
-Everything an extension holds is about one workspace, so a switch has to leave nothing of the last one behind.
-
-- **Cached reads**: `useQuery` in a view, or `api.sandbox.fetch(query)` from outside one. Key them with
-  `api.sandbox.key(...)` and the switch is handled by construction: the key carries the active sandbox id, so
-  the next box is a different cache entry. Use the *same* key for a view's query and for the badge poll that
-  warms it, and the poll's answer becomes the view's first paint.
-- **State inside a mounted component**: an ordinary `ref` in a `.vue` file. Nothing to do; it dies with the
-  component.
-- **Module state owned by `activate()`**: the badge counts, presence maps and poll results that must survive
-  the view being unmounted, because a badge you only see after opening the view is pointless. Declare it with
-  `sandboxRef(() => initial)` and the host empties it on every switch. There is no subscription to remember
-  and no teardown to write; `dispose` is there for state that owns an object URL or anything else the garbage
-  collector will not take back. A value replaced whole rather than edited in place (a map, an object with its
-  own methods) goes in `sandboxShallowRef` instead, the same lifetime without the deep proxy.
-
-For anything asynchronous in that third tier, take a `sandboxScopeGuard()` **before** the await and ask it
-**after**: a poll issued against the last sandbox otherwise resolves a moment later and writes its answer
-into the new one, which is the same wrong badge with a harder repro. It matters twice over for a call that
-WRITES: acknowledging what a badge has shown, in the wrong workspace's tree, is bookkeeping no later poll
-corrects.
-
-## Keeping a tile current while nothing is mounted
-
-Most of that third tier exists to feed a rail badge, so `sandboxPoll` covers the whole shape and you should not
-need `sandboxRef` directly for one:
-
-```ts
-const { state: unseen, start } = sandboxPoll<readonly Finding[]>({
-    host,                       // your hostSlot's accessor — nothing is bound until activate()
-    everyMs: 10 * 60_000,       // a backstop here: the file binding below is what actually refreshes this
-    initial: () => [],
-    read: async (api) => findings(await api.sandbox.fetch(query())),
-});
+```mermaid
+flowchart LR
+    web["Editor<br/>extension host"] -- "activate(api, context)" --> view["Extension bundle<br/>views · commands"]
+    backend["Daemon<br/>backend host"] -- "activateServer(api)" --> server["Server bundle<br/>routes under /x/id"]
+    sdk(["extension-api<br/>types · helpers"]) -.-> view
+    sdk -.-> server
+    loader["Daemon loader"] -- "engines.intentic<br/>vs extensionApiVersion" --> sdk
 ```
 
-`start()` returns the `Disposable` to push onto `context.subscriptions`; `refresh()` reads off-cycle for the
-moments that should not wait out the interval. The five rules a hand-written version has to remember: never
-reject, skip an unreachable daemon, discard an answer that outlived its sandbox, keep the last good value on
-failure, stop the clock on disposal, are the poll's, not yours. Pass `immediate: false` if there is nothing
-worth asking until something else tells you what to ask about, and read `previous` in `read` if a round
-accumulates onto what you already hold rather than replacing it.
-
-**If the answer lives in a file, the write is the feed and the interval is only a backstop.** `start()`
-subscribes to your own `contributes.files` paths being written (`api.workspace.onDidChangeFiles`), so a
-declaration you already made is what moves the tile, within a frame of the file changing rather than at the next
-tick. Nothing to opt into: declare the paths your views derive from and the badge over them reacts; declare none
-and the poll is the timer it always was. Bursts coalesce, so a run writing a file per story costs one read, and a
-reconnect wakes it too, because a frame pushed while the stream was down is a frame nobody resends. Pick
-`everyMs` accordingly: minutes for a file-backed badge (it is covering a dropped event, not carrying the news),
-and the honest cadence of the source for anything behind somebody else's API, where nothing can push at all.
-All polls in a window share one background-read lane, so aligned extension clocks and reconnect wakes cannot
-turn into parallel request bursts. Repeated triggers coalesce while waiting; one that lands during the read gets
-one trailing pass, so serialization does not trade load for a missed update.
-
-What the tile SAYS stays yours: `badge()` is the judgement each surface exists to make, and no two of them
-agree about tone or wording.
-
-It says it on two channels, and which one you reach for is the only rule the host enforces. `count`/`mark`
-is what the reader is OWED, and it wears the chip: a number, a tone, something to go and do. `running` is
-what is HAPPENING, a sentence like `2 running`, and it draws as a turning mark in the tile's own corner with
-no plate and no tone. Fill both when both are true — a red branch with its fix already re-running is the
-ordinary case, not the exotic one — and the tile says so without either claim evicting the other. Either
-channel seats the tile: the rail has always shown live work, and a run in flight that had to fail before
-earning a tile would be invisible for exactly as long as watching it was worth anything. A running mark needs
-no read marker and no ledger, which is the other half of why it is a separate channel: it goes out by itself
-when the work ends.
-
-`sandboxLedger(host, path)` is the other half: the JSON file recording what the owner has already seen, as
-`key → mark`, where the mark is what makes an entry stale. Compare marks (a chore's evidence digest, a story's
-verdict) and the same key with new evidence is news again; ignore them and it is a plain presence ledger. It
-reads a missing or mangled file as "nothing acknowledged", writes nothing when nothing moved, and holds the
-scope guard across its own read-then-write so an acknowledgement cannot land in the wrong workspace's tree.
-
-This is not advice. `sandboxScope.guard.test.ts` in the app walks each extension's UI entry through its own
-imports and refuses module-level `ref`/`shallowRef`/`reactive`, any reassignable module binding, and any
-repeating clock in what it reaches, because the failure it prevents was found in six extensions at once: a
-rail tile reading `21` under a workspace that had two.
-
-## Authoring an extension
-
-`activate(api, context)` registers contributions and returns; `deactivate` is optional. A UI extension also
-ships a prebuilt single-file ESM `entry` bundle (built with `vue` and `@intentic/extension-api` external).
-The five UI extensions under [`_extensions/`](../../_extensions) are the working templates; start from one.
+- 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 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), `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
+  [extension-manifest](../extension-manifest/src/points/index.ts).
+- `./protocol` exports only the version and the engines matcher, for the daemon, which cannot load the Vue-dependent
+  barrel.
 
 ## Key files
 
-- [src/api.ts](src/api.ts): the handle an extension is given; the centre of this package.
-- [src/facts.ts](src/facts.ts): the public facts a view's `detect()` answers from.
-- [src/engines.ts](src/engines.ts): how `engines.intentic` is matched against the version below, for the host
-  and the daemon alike.
-- [src/route.ts](src/route.ts): the query rules a view with internal navigation uses.
-- [src/scope.ts](src/scope.ts): module state that belongs to one sandbox, and the guard for work in flight
-  across a switch.
-- [src/version.ts](src/version.ts) and [src/surface.json](src/surface.json): the protocol version, and what
-  each version of it promised.
-
-The manifest schema and the `permissions.sandbox` matcher are **not here**: they moved to
-[@intentic/extension-manifest](../extension-manifest), which exists so the daemon can read a manifest without
-depending on the browser-facing API.
+- [src/api.ts](src/api.ts) — `IntenticApi`, `ExtensionContext` and the module shape a bundle exports.
+- [src/server.ts](src/server.ts) — `ExtensionServerApi`, the backend half.
+- [src/version.ts](src/version.ts) — `extensionApiVersion` and what each version added.
+- [src/surface.json](src/surface.json) — the recorded public surface, per version.
+- [src/scope.ts](src/scope.ts) — module state that belongs to one sandbox.
+- [src/background.ts](src/background.ts) — `sandboxPoll` and `sandboxLedger` for work done off screen.

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;AAIF,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,aA6BrE,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 = [];
@@ -107,13 +108,25 @@ export const sandboxPoll = (options) => {
 };
 const sameEntries = (left, right) => Object.keys(left).length === Object.keys(right).length && Object.entries(left).every(([key, mark]) => right[key] === mark);
 export const sandboxLedger = (host, path) => {
-    const read = async () => {
-        const parsed = await host().workspace.readJson(path);
-        return Object.fromEntries(Object.entries(parsed ?? {}).filter((entry) => typeof entry[1] === `string`));
+    const marksOf = (parsed) => typeof parsed === `object` && parsed !== null && !Array.isArray(parsed)
+        ? Object.fromEntries(Object.entries(parsed).filter((entry) => typeof entry[1] === `string`))
+        : {};
+    const read = async () => marksOf(await host().workspace.readJson(path));
+    const readToWrite = async () => {
+        const answer = await host().sandbox.rpc.workspace.file({ path });
+        if (!answer.present) {
+            return {};
+        }
+        try {
+            return marksOf(JSON.parse(answer.content));
+        }
+        catch {
+            return {};
+        }
     };
     const settle = async (next) => {
         const current = sandboxScopeGuard();
-        const seen = await read();
+        const seen = await readToWrite();
         const wanted = next(seen);
         if (sameEntries(seen, wanted)) {
             return true;
@@ -130,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.310.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.310.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";
@@ -154,7 +171,8 @@ export const sandboxPoll = <T>(options: SandboxPollOptions<T>): SandboxPoll<T> =
 };
 
 // Key → mark map of what the owner has already seen, stored as JSON under `.intentic`. Missing or unparseable reads as
-// nothing acknowledged; a write's `false` return means only that the sandbox scope moved mid-write.
+// nothing acknowledged; a write's `false` return means only that the sandbox scope moved mid-write, and a write over a
+// ledger that could not be read at all (refused, unreachable) rejects rather than dropping every acknowledgement in it.
 export interface SandboxLedger {
     // Everything acknowledged so far. Absent, unparseable or not-an-object all read as nothing.
     read(): Promise<Readonly<Record<string, string>>>;
@@ -168,17 +186,34 @@ const sameEntries = (left: Readonly<Record<string, string>>, right: Readonly<Rec
     Object.keys(left).length === Object.keys(right).length && Object.entries(left).every(([key, mark]) => right[key] === mark);
 
 export const sandboxLedger = (host: () => IntenticApi, path: string): SandboxLedger => {
-    const read = async (): Promise<Readonly<Record<string, string>>> => {
-        const parsed = await host().workspace.readJson<Record<string, unknown>>(path);
-        // Non-string values are dropped, not coerced: a mark is always a string.
-        return Object.fromEntries(Object.entries(parsed ?? {}).filter((entry): entry is [string, string] => typeof entry[1] === `string`));
+    // Non-string values are dropped, not coerced: a mark is always a string.
+    const marksOf = (parsed: unknown): Readonly<Record<string, string>> =>
+        typeof parsed === `object` && parsed !== null && !Array.isArray(parsed)
+            ? Object.fromEntries(Object.entries(parsed).filter((entry): entry is [string, string] => typeof entry[1] === `string`))
+            : {};
+
+    const read = async (): Promise<Readonly<Record<string, string>>> => marksOf(await host().workspace.readJson<Record<string, unknown>>(path));
+
+    // Through the contract's own read, which throws for a refused or unreachable read where `readJson` answers absent:
+    // a write computed from that absence would drop every acknowledgement the file really holds.
+    const readToWrite = async (): Promise<Readonly<Record<string, string>>> => {
+        const answer = await host().sandbox.rpc.workspace.file({ path });
+        if (!answer.present) {
+            return {};
+        }
+        try {
+            return marksOf(JSON.parse(answer.content));
+        } catch {
+            // silent-catch: an unparseable ledger holds nothing acknowledged, the contract `read` states.
+            return {};
+        }
     };
 
     // One writer for both mark and replace; the scope guard lives here, not at the call site, since a sandbox switch
     // mid-write would file the acknowledgement into the workspace the owner just left.
     const settle = async (next: (seen: Readonly<Record<string, string>>) => Readonly<Record<string, string>>): Promise<boolean> => {
         const current = sandboxScopeGuard();
-        const seen = await read();
+        const seen = await readToWrite();
         const wanted = next(seen);
         // Already saying it: nothing to write, and the caller's fold stays correct.
         if (sameEntries(seen, wanted)) {
@@ -197,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";