@jarenjs/app 0.75.0 → 0.83.3

package/README.md

@@ -1,5 +1,7 @@
 # @jarenjs/app
 
+Collection, search, formula and run resources are injected and disposed by their host. Follow the [combined public composition](../../docs/ADOPTION-EVIDENCE.md) for bounded observations, page ownership and explicit platform/manual qualifications.
+
 Applications as JSON documents. This package rebuilds [hyperapp](https://github.com/jorgebucaran/hyperapp)'s dispatch loop on the Jaren suite and pushes its philosophy — *everything is data* — the rest of the way: hyperapp made effects and subscriptions data but kept actions and views as JavaScript functions; here **the whole application is one JSON value**:
 
 | Slot | Written as | Compiled by |
@@ -259,13 +261,30 @@ Every subpath a consumer can import, derived from the manifest by
 <!--fact:exports.app-->
 | Import | Kind | Declarations |
 |---|---|---|
+| `@jarenjs/app/search` | JavaScript | declared |
 | `@jarenjs/app` | JavaScript | declared |
 | `@jarenjs/app/schemas/jaren-app.authoring.schema.json` | schema | — |
 | `@jarenjs/app/schemas/jaren-app.draft-07.schema.json` | schema | — |
 | `@jarenjs/app/schemas/jaren-app.schema.json` | schema | — |
 | `@jarenjs/app/package.json` | metadata | — |
+| `@jarenjs/app/formula` | JavaScript | declared |
 <!--/fact-->
 
 ## Development
 
 Unit tests live in `test/app/` at the repository root (`npm run test:app`). See [ROADMAP](../../docs/ROADMAP.md) for what's next: dirty-path-pruned re-rendering and time-travel tooling over the action log.
+
+`createApp` forwards the renderer's `safe`, `onUnsafe` and `hydrate` options.
+Optional `capabilities: { effects, subs, widgets, eventFields }` arrays grant
+specific host registry names; with safe mode or explicit grants, omitted lists
+are empty. See [APP-FORMAT §8.2.1](docs/APP-FORMAT.md#821-dom-profiles-and-host-capability-grants)
+for the disposal and trust contract. Safe mode is a display policy and removes
+DOM event bindings and widgets.
+
+`createArrayRangeProvider` and `createCollectionCoordinator` provide injected collection coordination and complete snapshot output; see [the provider contract](docs/COLLECTION-PROVIDER.md).
+
+`@jarenjs/app/search` owns an injected worker and a private resident index; see [search ownership](docs/SEARCH.md) for cancellation, progress and drained disposal.
+
+## Terminating formula workers
+
+`@jarenjs/app/formula` exports `createFormulaResource`, an injected worker lifecycle with bounded admission, generation fencing, hard termination and draining disposal. Hosts supply actual terminating isolates; same-thread helpers have no hard deadline. See the [formula resource contract](../json/docs/FORMULA-FORMAT.md#batches-and-isolation).

package/dist/types/app.d.ts

@@ -41,6 +41,26 @@ export type AppOptions = {
      * `node.ownerDocument`).
      */
     document?: any;
+    /**
+     * - Adopt existing DOM on the first frame.
+     */
+    hydrate?: boolean;
+    /**
+     * - Forward the inert view render profile. In
+     * this mode host capabilities default to empty allow-lists.
+     */
+    safe?: boolean;
+    onUnsafe?: import('@jarenjs/view').DomRendererOptions['onUnsafe'];
+    /**
+     * Restrict the host registry names the document may access. Omitted
+     * lists grant nothing when this option or `safe` is enabled.
+     */
+    capabilities?: {
+        effects?: string[];
+        subs?: string[];
+        widgets?: string[];
+        eventFields?: string[];
+    };
     /**
      * Effect handlers by name. A handler function may carry an optional
      * `dispose()` member, called exactly once by `app.destroy()` (a

package/dist/types/collection.d.ts

@@ -0,0 +1,73 @@
+export { createArrayRangeProvider } from '@jarenjs/core/range';
+/**
+ * Coordinate an injected provider with finite pages, bytes, requests and prefetch. The host owns
+ * provider construction; by default coordinator disposal also drains the provider.
+ * @param {any} provider @param {any} [options]
+ */
+export declare function createCollectionCoordinator(provider: any, options?: any): {
+    provider: any;
+    requestRange: (range: any, signal: any) => Promise<{
+        state: string;
+        reason: string;
+    } | {
+        state: string;
+    }>;
+    reset: (identity?: {}) => void;
+    stats: () => {
+        pages: number;
+        rows: any;
+        bytes: any;
+        inFlight: number;
+        outputs: number;
+    };
+    pinKeys(keys?: any[]): {
+        state: string;
+        reason: string;
+    } | {
+        reason?: undefined;
+        state: string;
+    };
+    observation(): {
+        state: string;
+        query: any;
+        snapshot: any;
+        generation: number;
+        total: {
+            kind: string;
+        };
+        loadedRows: number;
+        loadedBytes: number;
+    };
+    subscribe(fn: any): () => boolean;
+    rowAt(index: any): any;
+    keyAt(index: any): any;
+    indexOf(key: any): any;
+    logicalCount(): any;
+    next(signal: any): Promise<{
+        state: string;
+    } | {
+        state: string;
+        start: number;
+        end: number;
+        continuation: null;
+        total: {
+            kind: string;
+        };
+    }>;
+    /** @param {any} sink @param {any} [options] */
+    output(sink: any, { selection, signal, pageRows }?: any): Promise<{
+        state: string;
+        reason: string;
+    } | {
+        reason?: undefined;
+        state: string;
+        rows: number;
+        error?: undefined;
+    } | {
+        rows?: undefined;
+        state: string;
+        reason: string;
+        error: unknown;
+    }>;
+    dispose(): Promise<void>;
+};

package/dist/types/formula.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A host supplies actual worker/isolate termination. terminate() MUST stop execution
+ * and settle request(), including on cancellation. No same-thread deadline is offered.
+ * @param {{workerFactory:()=>{request:(message:any)=>Promise<any>,terminate:()=>Promise<any>},timeoutMs?:number,maxInFlight?:number}} options
+ */
+export declare function createFormulaResource(options: {
+    workerFactory: () => {
+        request: (message: any) => Promise<any>;
+        terminate: () => Promise<any>;
+    };
+    timeoutMs?: number;
+    maxInFlight?: number;
+}): {
+    /** Run one bounded batch in an isolate; replies must echo version/generation/revision. */
+    run(payload: any, { revision, signal }?: {
+        revision?: string | undefined;
+        signal?: undefined;
+    }): Promise<{
+        state: string;
+        reason: string;
+    }> | null;
+    /** All admitted work, including terminating requests, counts until drained. */
+    stats(): {
+        pending: number;
+        generation: number;
+        disposed: boolean;
+    };
+    /** Stop admission, terminate every worker and await settlement. Idempotent. */
+    dispose(): any;
+};

package/dist/types/index.d.ts

@@ -12,3 +12,5 @@ export { createTransactionLog } from './diagnostics.js';
 export { createSplitterWidget } from './splitter.js';
 export { createDocStore, encodeShare, decodeShare } from './docstore.js';
 export { AppCompileError, AppRuntimeError, HostValueError, toError, APP_CODES } from './errors.js';
+export { createArrayRangeProvider, createCollectionCoordinator } from './collection.js';
+export { createRunObservation } from './runs.js';

package/dist/types/runs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The injected readPage may invoke a public contract operation. One page is in
+ * flight at a time; only current summary/cursor enters app state. No event log
+ * or worker resources accumulate here. `wake` can wait for a notification or a
+ * bounded poll; after a lost notification the next page resumes the durable cursor.
+ * @param {{ readPage: (input: any, context: { signal: AbortSignal }) => any,
+ * wake: (signal: AbortSignal) => any, pageSize?: number, maxBytes?: number }} options
+ */
+export declare function createRunObservation(options: {
+    readPage: (input: any, context: {
+        signal: AbortSignal;
+    }) => any;
+    wake: (signal: AbortSignal) => any;
+    pageSize?: number;
+    maxBytes?: number;
+}): {
+    (props: {
+        runId: string;
+        id: number;
+        cursor?: number;
+        update: string;
+        error: string;
+    }, dispatch: (name: string, payload: any) => void): () => void;
+    /** Detach every observer; this never calls a run's cancel operation. */
+    dispose: () => void;
+};

package/dist/types/search.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Own one worker and one published index. Worker request/reply envelopes carry
+ * version, requestId, generation and sourceRevision; build replies carry snapshots.
+ * dispose() on the injected worker must settle every request, including aborted ones.
+ * @param {import('@jarenjs/core/search').LexicalDefinition} definition
+ * @param {{workerFactory:()=>{request:(message:any, options:any)=>Promise<any>, dispose:()=>any},
+ * maxInFlight?:number, onProgress?:(progress:any)=>void}} options
+ */
+export declare function createSearchResource(definition: import('@jarenjs/core/search').LexicalDefinition, options: {
+    workerFactory: () => {
+        request: (message: any, options: any) => Promise<any>;
+        dispose: () => any;
+    };
+    maxInFlight?: number;
+    onProgress?: (progress: any) => void;
+}): {
+    /** @param {any[]} documents @param {{generation:number, sourceRevision:string, requestId:string}} identity @param {AbortSignal} [signal] */
+    build(documents: any[], identity: {
+        generation: number;
+        sourceRevision: string;
+        requestId: string;
+    }, signal?: AbortSignal): Promise<{
+        generation: number;
+        sourceRevision: string;
+        requestId: string;
+        state: any;
+        reason: any;
+    } | {
+        generation: number;
+        sourceRevision: string;
+        requestId: string;
+        state: string;
+        documents: number;
+    }>;
+    /** @param {string} text @param {any} [options] */
+    search(text: string, options?: any): {
+        state: any;
+        reason?: any;
+        generation: number;
+        sourceRevision: string;
+        identity: any;
+    };
+    stats(): {
+        documents: number;
+        vocabulary: number;
+        postings: number;
+        tokens: number;
+        sourceBytes: number;
+        indexBytes: number;
+        tombstones: number;
+        fieldLengths: any[];
+        generation: number;
+        sourceRevision: string;
+        disposed: boolean;
+        workers: number;
+        pending: number;
+    };
+    /** Stop admission, fence callbacks, terminate the worker and drain its requests. */
+    dispose(): any;
+};

package/docs/APP-FORMAT.md

@@ -510,6 +510,33 @@ once), and renderer destruction — widgets unmount exactly once, the
 container is left empty, and scheduled render flushes become exact
 no-ops.
 
+### 8.2.1 DOM profiles and host capability grants
+
+`createApp` forwards `safe`, `onUnsafe` and `hydrate` to its DOM renderer
+(VIEW-FORMAT §6/§8). `capabilities` optionally grants names from the host's
+`effects`, `subs`, `widgets` and `eventFields` registries:
+
+```js
+const app = createApp(doc, {
+  node, safe: true, onUnsafe: report,
+  effects: { load },
+  capabilities: { effects: ['load'] },
+});
+```
+
+When `safe: true` or `capabilities` is supplied, omitted grant lists are empty.
+Unknown or inherited registry names are refused at construction. Only granted
+effects belong to this app's disposal lifecycle. Without either option, the
+existing registered capabilities remain available. Safe mode still removes
+DOM event bindings and widgets; a widget grant does not override that display
+policy. A trusted interactive app can use explicit grants without `safe`.
+
+The action vocabulary is local to the app document. Effect/subscription/widget
+registries and custom event fields are host boundaries. These controls bound
+named host access, not CPU, memory, native navigation or network loads; they
+are not a browser security sandbox. Hosted documents still require a deliberate
+trust policy.
+
 ### 8.3 Transaction observers and diagnostics
 
 `app.observe(fn)` delivers one bounded JSON record per settled

package/docs/COLLECTION-PROVIDER.md

@@ -0,0 +1,166 @@
+# Structural collection providers
+
+A provider is a host-injected service. Presentation code consumes its shape;
+storage code never imports app or components. Rows, cursors and handles stay
+private to the provider. App state carries JSON intent and bounded observations.
+
+## Database adapter
+
+```js
+import { createDbRangeProvider } from '@jarenjs/linq/db';
+
+const provider = await createDbRangeProvider(store, 'Row', {
+  orderBy: '$it.rank'
+}, { keys: ['id'], maxRows: 256, maxBytes: 262144 });
+try {
+  const reply = await provider.request({
+    generation: 1, requestId: 'first', query: provider.query,
+    snapshot: provider.snapshot, range: { start: 0, end: 20 },
+    credits: { pages: 1, rows: 20, bytes: 65536, work: 20 }
+  }, signal);
+  // Publish only if all echoed identities still match current intent.
+  consume(reply);
+} finally { await provider.dispose(); }
+```
+
+`handle.range(spec, options)` is the same adapter. Open the root store with
+committed capture enabled; create the provider from that root, outside a scoped
+transaction. The adapter currently supports captured hybrid entity roots.
+Adopted physical capture and physical keyset paging remain refused.
+
+`keys` names distinct stable logical key members. Compound keys are canonical
+JSON tuples; single keys are strings. Keys must exist and be unique in returned
+rows. A load spec supplies filter/order; the provider owns take/skip/after and
+serves root rows without includes. The spec is cloned on construction.
+
+## Identities and outcomes
+
+Query identity includes source, entity, filter/sort, keys, schema version and
+profile. `source` defaults to a host UUID; custom `query`/`source` strings must
+uniquely identify that source configuration and provider lifetime. Snapshot
+identity is the source epoch, incremented by committed capture or a changed
+database data-version detected at request time. It is not a durable MVCC token.
+External writers are detected on the next request, not polled continuously.
+
+Request generation fences superseded client work; it is never a source snapshot.
+Every reply echoes generation, requestId, query and snapshot. The latest admitted
+request supersedes earlier replies, including requests within the same generation.
+Callers must also fence publication against their current intent.
+
+A request supplies a half-open `range: { start, end }` or opaque `continuation`,
+and nonnegative safe-integer page/row/byte/work credits. Cancellation is the second
+argument, an injected `AbortSignal`, never a JSON member. Outcomes are:
+
+| State | Meaning |
+|---|---|
+| `ready` | Stable keys, frozen rows, echoed identities, continuation and total are available. |
+| `invalidated` | Query, snapshot, continuation or request identity became stale; start from current source identity. |
+| `budget-exhausted` | Admission or result exceeds finite credits; nothing may be published as complete. |
+| `error` | Invalid input, unsupported seek, cancellation, disposal or source failure. |
+| `loading` | Reserved structural state; this promise-based adapter resolves terminal outcomes. |
+
+`total` is `{ kind: 'known', value }` or `{ kind: 'unknown' }`; loaded row count
+never means logical total. Sequential mode offers continuation, live resets and
+unknown total, with no index/key seek or complete export. A nonzero initial index
+refuses `reason: 'unsupported-seek'` without scanning. Full pages use an unknown
+continuation sentinel; a later empty page proves exhaustion, without a hidden
+lookahead row. Continuations are private, bounded and may expire by eviction.
+
+Opt-in `resident: true` first reads one complete source, bounded by `maxRows` and
+`maxBytes`, then offers index seek and exact total (`seekIndex: false` and
+`exactTotal: false` can withhold them). Oversize initialization fails and cleans up.
+It never presents a truncated source as complete. A source reset discards the
+resident rows and the next request must requalify the complete bounded source.
+That request must reserve at least `maxRows + 1 + requestedLength` work credits
+before the refill starts; otherwise it returns `budget-exhausted` without reading.
+
+## Resources, events and lifecycle
+
+Defaults are 256 source/page rows, 262144 bytes, 4 retained continuation handles,
+2 in-flight requests and 8 subscriptions. All bounds are positive safe integers.
+Per-request `used` reports pages, returned rows/bytes and consumed root work,
+including a row consumed at a byte boundary and any resident refill plus slice.
+The provider conservatively reserves array punctuation for the full requested
+length before reading; a near-limit partial page can therefore refuse early.
+`stats()` separately reports source reads/rows/bytes, resident storage, retained
+handles, pending requests and subscriptions. SQL visited rows and internal database
+allocations are unavailable; these credits measure admitted application work.
+Source bytes count consumed root payloads, including an item refused at the byte
+boundary. `page(..., { lookahead: false })` exposes these counts as `work: { rows,
+bytes }`; default pages preserve their existing shape and one-row lookahead.
+
+`subscribe(fn)` returns an unsubscribe function. Events carry monotone revision,
+query/snapshot and explicit `type: 'reset'`, with source capture qualification.
+These events do not imply incremental keyed maintenance. Keyed insert/update/
+delete/move events are reserved for sources that independently prove them.
+
+`dispose()` stops admission, unsubscribes, cancels and drains pending requests,
+clears rows/handles and fences late callbacks. It is idempotent. A provider must
+be disposed before closing its store.
+
+One host coordinator owns finite prefetch, request and page/byte credits; one
+component owns DOM/cell/pin and measurement credits. Selection is stable-key or
+query/snapshot-scoped intent with exclusions. The authoritative mutation rechecks
+membership and revision. Focus/scroll restoration carries key, offset and query
+identity, plus a declared fallback when the key disappears. Complete print/export
+requires a separate bounded stream over a declared complete snapshot; mounted
+rows cannot prove completeness. Sequential mode declares `completeExport: false`; bounded resident mode supplies the complete snapshot stream described below.
+
+## App coordinator and resident arrays
+
+`createArrayRangeProvider(rows, options)` creates an immutable resident source copy
+and key index. This full source remains resident, and `stats().rows/bytes` reports
+it honestly. `keyOf` defaults to the string form of `row.id`. Query/source identities
+default to a new host UUID; `runtime`, `source`, `query` and `snapshot` can be
+injected. Explicit query identities must distinguish source, ordering/filter and
+relevant profile/schema versions. `replace(rows,newSnapshot)` requires a new source
+identity, increments event revision and resets cursors. Return values are copied
+so consumers cannot mutate the source snapshot. `indexOf(key)` uses the resident
+index. `seekIndex:false` and `exactTotal:false` exercise restricted capabilities.
+
+`createCollectionCoordinator(provider, options)` privately owns cancellation,
+generation/request fencing and caches. Defaults: 64 rows/page, 4 cached pages,
+256 cached rows, 262144 cached bytes, 2 in-flight requests, 256 work credits/request,
+one simultaneous output (`maxOutputs`), eight subscribers (`maxSubscriptions`),
+and zero prefetch pages. `prefetchPages` is finite, below the page limit and clamped
+to row credits. `requestRange({start,end},signal)` refuses oversized ranges before
+source work. Every response must echo all four identities and fit row/byte/work
+credits before it can publish. A provider that ignores cancellation still cannot
+replace current rows. Source events need a monotone integer revision; this
+coordinator treats keyed events conservatively as reset rather than claiming
+incremental maintenance. `reset` fences old work and clears cached resources.
+
+`observation()` and `subscribe` expose JSON query/snapshot/generation, status,
+logical total and bounded loaded row/byte counts. `rowAt`, `keyAt` and `indexOf`
+access private cache rows. `logicalCount()` returns the known total, or the loaded
+frontier plus a continuation sentinel; it never manufactures a known total.
+`next(signal)` requests the next sequential page. A sequential source refuses
+arbitrary jumps as `unsupported-seek` without scanning. `pinKeys(keys)` protects
+editor pages within existing page/row/byte limits; an impossible admission returns
+`budget-exhausted / pinned-page-credits`. `stats()` separately reports cache pages,
+rows/bytes, in-flight requests and outputs. By default async `dispose` drains both
+the coordinator and provider; `disposeProvider:false` retains host ownership.
+
+## Transactional export and print sinks
+
+Complete sources expose `export({query,snapshot,pageRows,pageBytes},signal)` as an
+async iterable. Each page is `{state:'ready',query,snapshot,rows,keys}`; the terminal
+record is `{state:'complete',query,snapshot,total}`. The terminal count proves how
+many source rows were read, independently of selection. A missing terminal record,
+changed identity, byte/row overflow, cancellation or missing selected key/range
+endpoint is an incomplete output and must not be reported as success.
+
+The coordinator's `output(sink,{selection,signal,pageRows})` awaits `begin(identity)`,
+serial `write(rows)` calls and finally `commit({query,snapshot,rows})`. Any failure
+calls `abort(error)` and returns `error / incomplete-export`. The sink must stage
+work privately and make it visible only at commit. It supplies its own finite
+spool or streaming storage; building a whole output array is not implicitly
+bounded. Backpressure is the awaited `write` promise. The same sink contract
+supports printing a completed snapshot artifact. Disposal cancels and drains
+outstanding output before clearing resources.
+
+Arrays support complete output at their immutable snapshot. SQLite resident mode
+also supports complete output over its already qualified bounded source; it checks
+source data-version before and after export, and refuses a changed/unloaded epoch.
+Sequential database mode continues to refuse complete export. The website download
+sink has a finite spool, so an oversized output fails before creating a download.

package/docs/SEARCH.md

@@ -0,0 +1,41 @@
+# Search resource ownership
+
+`createSearchResource` from `@jarenjs/app/search` owns one private resident index
+and an injected worker. JSON application state holds search intent, progress,
+result IDs and observations. It never holds index handles, worker objects,
+controllers or cached source rows.
+
+```js
+import { createSearchResource } from '@jarenjs/app/search';
+// workerFactory is the host's injected service; dispose must settle its requests.
+const resource = createSearchResource({ version: 1, fields: ['title', 'sku'] }, {
+  workerFactory, maxInFlight: 2, onProgress: progress => publishProgress(progress),
+});
+await resource.build(rows, { generation: 1, requestId: 'build-1', sourceRevision: 'catalog-1' });
+const result = resource.search('gren tea', { limit: 20 });
+await resource.dispose();
+```
+
+The factory supplies `{request(message, {signal, onProgress}), dispose()}`.
+Build messages have `version: 1`, `operation: 'build'`, the lexical definition,
+projected string documents, and all three identities. Transport admission checks
+document/field/source and temporary credits before handing text to the worker.
+The host worker runs the public core engine and responds with matching identities,
+`state: 'complete'` and a serialized `snapshot`. Progress carries those same
+identities plus nonnegative integer `work`. A host can use Web Workers or a server
+worker; no worker constructor or runtime is imported by this capability.
+
+An incomplete or corrupt snapshot never publishes. Switching builds aborts older
+requests, fences late replies and retains finite in-flight admission credits.
+Cancelled and superseded progress is ignored. Worker errors are explicit outcomes.
+`dispose()` stops admission, aborts requests, closes the worker, drains settlements,
+and releases all index/source references. The worker's disposal contract must
+settle outstanding requests; a worker ignoring termination cannot prove drained
+teardown. Enforce a host memory ceiling in addition to the core's logical credits.
+
+For query/collection composition use the injected query provider and the existing
+collection coordinator. Search resources do not create another application
+scheduler, evaluator, catalog or range cache.
+
+Build generations must increase strictly, including retries after a failed worker
+request. Progress is fenced by identity and never regresses within a request.

package/docs/TASKS.md

@@ -254,3 +254,28 @@ above validates against the shipped
 A pattern that needed a schema extension would be a format change; this
 one is proof the existing vocabulary already carries request identity
 and staleness rejection.
+
+## Observe an existing durable run
+
+`createRunObservation({ readPage, wake, pageSize?, maxBytes? })` is an app
+subscription factory, used as `subs: { run: observation }`. The subscription
+props name `runId`, attempt `id`, saved `cursor` and `update`/`error` actions.
+`readPage({ id, after, limit }, { signal })` reads one bounded public event page;
+`wake(signal)` waits for the next notification or the host's bounded poll.
+Only one page is outstanding and only current status, summary, revision and
+cursor enter app state. The update action must guard the attempt ID and reject
+older revisions, as for task completion. No accumulated event log enters state.
+
+The cleanup returned by a subscription and `observation.dispose()` detach
+observers. They do not cancel the durable run. Lost notifications recover through
+the saved revision cursor; missing history emits `reset: true` and a fresh
+summary. Malformed/oversized pages and read failures emit only
+`{ code: "run-observation-failed" }`, never exception text or provider credentials.
+The host projection decides which domain summary fields are public.
+
+`createRunPageHandler({ page, authorize, maxPage? })` from `@jarenjs/contract/app`
+is an ordinary read handler that checks current authority before touching durable
+history. Inject `createDbRunStore(...).page` into it, expose it through a compiled
+read operation, and have `readPage` invoke that operation through any public
+contract client. Explicit cancellation is a separate authorized command; navigation
+only removes the subscription.

package/package.json

@@ -1,18 +1,26 @@
 {
   "name": "@jarenjs/app",
   "private": false,
-  "version": "0.75.0",
+  "version": "0.83.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
   "sideEffects": false,
   "exports": {
+    "./search": {
+      "types": "./dist/types/search.d.ts",
+      "default": "./src/search.js"
+    },
     ".": {
       "types": "./dist/types/index.d.ts",
       "default": "./src/index.js"
     },
     "./schemas/*": "./schemas/*",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./formula": {
+      "types": "./dist/types/formula.d.ts",
+      "default": "./src/formula.js"
+    }
   },
   "files": [
     "dist/types/",
@@ -50,8 +58,8 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.75.0",
-    "@jarenjs/json": "^0.75.0",
-    "@jarenjs/view": "^0.75.0"
+    "@jarenjs/core": "^0.83.3",
+    "@jarenjs/json": "^0.83.3",
+    "@jarenjs/view": "^0.83.3"
   }
 }

package/src/app.js

@@ -46,6 +46,13 @@ import { AppCompileError, AppRuntimeError, toError, safeErrorMessage } from './e
  *   app (drive it via `getVnode`/`subscribe`).
  * @property {any} [document] - The DOM document (defaults to
  *   `node.ownerDocument`).
+ * @property {boolean} [hydrate] - Adopt existing DOM on the first frame.
+ * @property {boolean} [safe] - Forward the inert view render profile. In
+ *   this mode host capabilities default to empty allow-lists.
+ * @property {import('@jarenjs/view').DomRendererOptions['onUnsafe']} [onUnsafe]
+ * @property {{ effects?: string[], subs?: string[], widgets?: string[], eventFields?: string[] }} [capabilities]
+ *   Restrict the host registry names the document may access. Omitted
+ *   lists grant nothing when this option or `safe` is enabled.
  * @property {Record<string, (props: any, dispatch: Dispatch) => void>} [effects]
  *   Effect handlers by name. A handler function may carry an optional
  *   `dispose()` member, called exactly once by `app.destroy()` (a
@@ -211,9 +218,21 @@ export function createApp(appDoc, options = {}) {
   const actions = compileActions(appDoc.actions, queryOptions);
   const subs = compileSubs(appDoc.subs, queryOptions);
 
-  const effectHandlers = options.effects ?? {};
-  const subHandlers = options.subs ?? {};
-  const eventExtractors = options.eventFields ?? {};
+  const grant = (kind) => {
+    const registry = options[kind] ?? {};
+    if (!options.safe && options.capabilities === undefined) return registry;
+    const names = options.capabilities?.[kind] ?? [];
+    if (!Array.isArray(names) || names.some((name) => typeof name !== 'string'))
+      throw new TypeError(`createApp: capabilities.${kind} must be a list of names`);
+    return Object.fromEntries(names.map((name) => {
+      if (!Object.hasOwn(registry, name)) throw new TypeError(`createApp: unknown ${kind} capability '${name}'`);
+      return [name, registry[name]];
+    }));
+  };
+  const effectHandlers = grant('effects');
+  const subHandlers = grant('subs');
+  const eventExtractors = grant('eventFields');
+  const widgets = grant('widgets');
   const onError = options.onError ?? ((err) => { throw err; });
   const schedule = options.schedule ?? ((flush) => queueMicrotask(flush));
   const afterRender = options.afterRender ?? null;
@@ -1225,7 +1244,10 @@ export function createApp(appDoc, options = {}) {
         renderer = createDomRenderer(options.node, {
           document: options.document,
           onEvent: handleBinding,
-          widgets: options.widgets,
+          widgets,
+          safe: options.safe,
+          hydrate: options.hydrate,
+          onUnsafe: options.onUnsafe,
           // terminal-cleanup provenance: a widget unmount that throws
           // during renderer teardown — deferred teardown after an
           // app.destroy() from inside a hook included — is a CLEANUP

package/src/collection.js

@@ -0,0 +1,192 @@
+//@ts-check
+/** Injected range coordination. Rows and handles remain private; observations contain JSON only. */
+import { deepFreeze } from '@jarenjs/core/object';
+import { rangeBytes as bytesOf, rangeIdentity as identityOf, validRangeCredits as validCredits, validLogicalRange as validRange } from '@jarenjs/core/range';
+export { createArrayRangeProvider } from '@jarenjs/core/range';
+
+/**
+ * Coordinate an injected provider with finite pages, bytes, requests and prefetch. The host owns
+ * provider construction; by default coordinator disposal also drains the provider.
+ * @param {any} provider @param {any} [options]
+ */
+export function createCollectionCoordinator(provider, options = {}) {
+  const bounds = { pageRows: 64, maxPages: 4, maxRows: 256, maxBytes: 262144, maxInFlight: 2, maxOutputs: 1, maxSubscriptions: 8, prefetchPages: 0, work: 256, ...options };
+  for (const name of ['pageRows', 'maxPages', 'maxRows', 'maxBytes', 'maxInFlight', 'maxOutputs', 'maxSubscriptions', 'work'])
+    if (!Number.isSafeInteger(bounds[name]) || bounds[name] <= 0) throw new RangeError(`Invalid ${name}`);
+  if (!Number.isSafeInteger(bounds.prefetchPages) || bounds.prefetchPages < 0 || bounds.prefetchPages >= bounds.maxPages
+    || bounds.pageRows > bounds.maxRows) throw new RangeError('Invalid prefetch credits');
+  let query = provider.query, snapshot = provider.snapshot, generation = 1, ticket = 0, disposed = false, revision = -1;
+  let observation = { state: 'loading', query, snapshot, generation, total: { kind: 'unknown' }, loadedRows: 0, loadedBytes: 0 };
+  let cursor = null, frontier = 0, exhausted = false;
+  const pages = new Map(), pending = new Map(), subscribers = new Set(), outputs = new Set();
+  let pinnedKeys = new Set();
+  function stats() { return { pages: pages.size, rows: [...pages.values()].reduce((n, p) => n + p.rows.length, 0),
+    bytes: [...pages.values()].reduce((n, p) => n + p.bytes, 0), inFlight: pending.size, outputs: outputs.size }; }
+  function publish(change) {
+    if (disposed) return;
+    const cost = stats(); observation = { ...observation, ...change, query, snapshot, generation, loadedRows: cost.rows, loadedBytes: cost.bytes };
+    for (const key of Object.keys(observation)) if (observation[key] === undefined) delete observation[key];
+    for (const fn of subscribers) { try { fn(structuredClone(observation)); } catch (error) { options.onError?.(error); } }
+    try { options.onChange?.(structuredClone(observation)); } catch (error) { options.onError?.(error); }
+  }
+  function cancel() { for (const controller of pending.keys()) controller.abort(); }
+  function reset(identity = {}) {
+    generation++; ticket++; cancel(); pages.clear(); cursor = null; frontier = 0; exhausted = false;
+    query = identity.query ?? provider.query; snapshot = identity.snapshot ?? provider.snapshot;
+    publish({ state: 'invalidated', total: { kind: 'unknown' } });
+  }
+  const unsubscribe = provider.subscribe?.((event) => {
+    if (disposed || event.query !== query || !Number.isSafeInteger(event.revision) || event.revision <= revision) return;
+    revision = event.revision;
+    // A patch shape alone does not prove incremental maintenance; reset safely at the source epoch.
+    reset(event);
+  });
+  async function load(start, continuation, current, signal) {
+    const request = { generation, requestId: String(current), query, snapshot,
+      ...(continuation ? { continuation } : { range: { start, end: start + bounds.pageRows } }),
+      credits: { pages: 1, rows: bounds.pageRows, bytes: bounds.maxBytes, work: bounds.work } };
+    const identity = identityOf(request);
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted) abort();
+    const run = async () => {
+      try {
+        const response = await provider.request(request, controller.signal);
+        if (disposed || current !== ticket || request.generation !== generation || controller.signal.aborted)
+          return { state: 'invalidated', reason: 'superseded' };
+        if (Object.keys(identity).some((key) => response?.[key] !== identity[key])) {
+          publish({ state: 'invalidated', reason: 'identity-mismatch' });
+          return { state: 'invalidated', reason: 'identity-mismatch' };
+        }
+        if (response.state !== 'ready') { publish({ state: response.state, reason: response.reason }); return response; }
+        const bytes = bytesOf(response.rows);
+        if (!Array.isArray(response.rows) || !Array.isArray(response.keys) || response.rows.length !== response.keys.length
+          || response.rows.length > bounds.pageRows || bytes > bounds.maxBytes || new Set(response.keys).size !== response.keys.length
+          || !response.keys.every((key) => typeof key === 'string') || !validCredits(response.used)
+          || Object.keys(request.credits).some((key) => response.used[key] > request.credits[key])
+          || response.used.bytes !== bytes || response.used.rows !== response.rows.length
+          || !['known', 'unknown'].includes(response.total?.kind)
+          || (response.total.kind === 'known' && (!Number.isSafeInteger(response.total.value) || response.total.value < start + response.rows.length)))
+          { publish({ state: 'error', reason: 'invalid-response' }); return { state: 'error', reason: 'invalid-response' }; }
+        pages.delete(start);
+        while (pages.size && (pages.size >= bounds.maxPages || stats().rows + response.rows.length > bounds.maxRows || stats().bytes + bytes > bounds.maxBytes)) {
+          const evict = [...pages].find(([, page]) => !page.keys.some((key) => pinnedKeys.has(key)));
+          if (!evict) { publish({state:'budget-exhausted',reason:'pinned-page-credits'}); return {state:'budget-exhausted',reason:'pinned-page-credits'}; }
+          pages.delete(evict[0]);
+        }
+        pages.set(start, { rows: deepFreeze(structuredClone(response.rows)), keys: response.keys.slice(), bytes });
+        if (start >= frontier) { frontier = start + response.rows.length; cursor = response.continuation; exhausted = !cursor; }
+        publish({ state: 'ready', reason: undefined, total: response.total });
+        return { state: 'ready', start, end: start + response.rows.length, continuation: response.continuation, total: response.total };
+      }
+      catch (error) {
+        if (disposed || current !== ticket) return { state: 'invalidated', reason: 'superseded' };
+        publish({ state: 'error', reason: 'source-failure' }); return { state: 'error', reason: 'source-failure', error };
+      }
+    };
+    const promise = Promise.resolve().then(run).finally(() => { pending.delete(controller); signal?.removeEventListener('abort', abort); });
+    pending.set(controller, promise); return promise;
+  }
+  async function requestRange(range, signal) {
+    if (disposed) return { state: 'error', reason: 'disposed' };
+    if (!validRange(range)) return { state: 'error', reason: 'invalid-range' };
+    if (signal?.aborted) return { state: 'error', reason: 'cancelled' };
+    const first = provider.capabilities.seekIndex ? Math.floor(range.start / bounds.pageRows) * bounds.pageRows : range.start;
+    if (!provider.capabilities.seekIndex && first !== 0 && !(first === frontier && cursor))
+      return { state: 'error', reason: 'unsupported-seek' };
+    const count = Math.ceil((range.end - first) / bounds.pageRows);
+    if (count > bounds.maxPages || count * bounds.pageRows > bounds.maxRows) return { state: 'budget-exhausted', reason: 'page-credits' };
+    cancel(); const current = ++ticket;
+    if (pending.size >= bounds.maxInFlight) return { state: 'budget-exhausted', reason: 'in-flight' };
+    publish({ state: 'loading', reason: undefined });
+    let result = { state: 'ready' };
+    const admitted = Math.min(Math.floor(bounds.maxRows / bounds.pageRows), bounds.maxPages, count + (provider.capabilities.seekIndex ? bounds.prefetchPages : 0));
+    for (let page = 0; page < admitted; page++) {
+      const start = first + page * bounds.pageRows;
+      result = await load(start, provider.capabilities.seekIndex ? null : start === 0 ? null : cursor, current, signal);
+      if (result.state !== 'ready' || current !== ticket || disposed) return result;
+      if (result.end - result.start < bounds.pageRows || !result.continuation) break;
+    }
+    if (count === 0) publish({ state: 'ready' });
+    return result;
+  }
+  const coordinator = {
+    provider, requestRange, reset, stats,
+    pinKeys(keys = []) {
+      if (!Array.isArray(keys) || keys.length > bounds.maxRows || !keys.every((key) => typeof key === 'string'))
+        return {state:'budget-exhausted',reason:'pin-credits'};
+      pinnedKeys = new Set(keys); return {state:'ready'};
+    },
+    observation() { return structuredClone(observation); },
+    subscribe(fn) { if (disposed) throw new Error('Coordinator disposed');
+      if (subscribers.size >= bounds.maxSubscriptions) throw new RangeError('Subscription credits');
+      subscribers.add(fn); return () => subscribers.delete(fn); },
+    rowAt(index) { for (const [start, page] of pages) if (index >= start && index < start + page.rows.length) return page.rows[index - start]; },
+    keyAt(index) { for (const [start, page] of pages) if (index >= start && index < start + page.rows.length) return page.keys[index - start]; return null; },
+    indexOf(key) {
+      for (const [start, page] of pages) { const i = page.keys.indexOf(key); if (i >= 0) return start + i; }
+      return provider.capabilities.seekKey ? provider.indexOf?.(key) ?? -1 : -1;
+    },
+    logicalCount() { return observation.total.kind === 'known' ? observation.total.value : frontier + (exhausted ? 0 : 1); },
+    async next(signal) { if (exhausted) return {state:'ready',start:frontier,end:frontier,continuation:null,total:observation.total}; return requestRange({ start: frontier, end: frontier + bounds.pageRows }, signal); },
+    /** @param {any} sink @param {any} [options] */
+    async output(sink, { selection, signal, pageRows = bounds.pageRows } = {}) {
+      if (disposed || !provider.capabilities.completeExport || typeof provider.export !== 'function')
+        return { state: 'error', reason: disposed ? 'disposed' : 'unsupported-export' };
+      if (outputs.size >= bounds.maxOutputs) return {state:'budget-exhausted',reason:'output-credits'};
+      if (selection && (selection.mode === 'all' || selection.ranges?.length) && (selection.query !== query || selection.snapshot !== snapshot))
+        return { state: 'invalidated', reason: 'selection-snapshot' };
+      const controller = new AbortController(), abort = () => controller.abort();
+      signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) abort();
+      const identity = { query, snapshot }, wanted = new Set(selection?.keys ?? []), excluded = new Set(selection?.exclusions ?? []);
+      const ranges = (selection?.ranges ?? []).map((range) => ({ ...range, open: false, found: 0 }));
+      let read = 0, written = 0, completed = false;
+      const operation = Promise.resolve().then(async () => {
+        try {
+          await sink.begin?.(identity);
+          for await (const page of provider.export({ ...identity, pageRows, pageBytes: bounds.maxBytes }, controller.signal)) {
+            if (disposed || controller.signal.aborted || query !== identity.query || snapshot !== identity.snapshot
+              || page.query !== identity.query || page.snapshot !== identity.snapshot || completed) throw new Error('Incomplete snapshot export');
+            if (page.state === 'complete') { if (page.total !== read) throw new Error('Incomplete snapshot total'); completed = true; continue; }
+            if (page.state !== 'ready' || page.rows.length !== page.keys.length || page.rows.length > pageRows || bytesOf(page.rows) > bounds.maxBytes)
+              throw new Error('Invalid export page');
+            const output = [];
+            for (let i = 0; i < page.rows.length; i++) {
+              const key = page.keys[i]; let inRange = false;
+              for (const range of ranges) {
+                const endpoint = key === range.fromKey || key === range.toKey;
+                inRange ||= range.open || endpoint;
+                if (endpoint) { range.found++; range.open = !range.open; if (range.fromKey === range.toKey) { range.open = false; range.found++; } }
+              }
+              const selected = !selection || (selection.mode === 'all' && !excluded.has(key)) || wanted.has(key) || inRange;
+              wanted.delete(key); read++;
+              if (selected) { output.push(page.rows[i]); written++; }
+            }
+            if (output.length) await sink.write(output);
+          }
+          if (!completed || wanted.size || ranges.some((range) => range.found !== 2)) throw new Error('Incomplete selection export');
+          if (disposed || controller.signal.aborted || query !== identity.query || snapshot !== identity.snapshot) throw new Error('Incomplete snapshot export');
+          await sink.commit({ ...identity, rows: written }); return { state: 'complete', rows: written };
+        }
+        catch (error) { await sink.abort?.(error); return { state: 'error', reason: 'incomplete-export', error }; }
+      });
+      outputs.add({ controller, operation });
+      try { return await operation; }
+      finally { signal?.removeEventListener('abort', abort); for (const item of outputs) if (item.operation === operation) outputs.delete(item); }
+    },
+    async dispose() {
+      let failure, failed = false;
+      if (!disposed) {
+        disposed = true; ticket++; cancel(); subscribers.clear();
+        try { unsubscribe?.(); } catch (error) { failure = error; failed = true; }
+        for (const item of outputs) item.controller.abort();
+      }
+      await Promise.allSettled([...pending.values(), ...[...outputs].map((item) => item.operation)]);
+      pages.clear(); cursor = null; pinnedKeys.clear();
+      if (options.disposeProvider !== false) { try { await provider.dispose(); } catch (error) { if (!failed) { failure = error; failed = true; } } }
+      if (failed) throw failure;
+    },
+  };
+  return coordinator;
+}

package/src/formula.js

@@ -0,0 +1,70 @@
+//@ts-check
+/** Own terminating formula workers; generation fences prevent stale publication. */
+import { cloneJson, deepFreeze } from '@jarenjs/core/object';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+
+/**
+ * A host supplies actual worker/isolate termination. terminate() MUST stop execution
+ * and settle request(), including on cancellation. No same-thread deadline is offered.
+ * @param {{workerFactory:()=>{request:(message:any)=>Promise<any>,terminate:()=>Promise<any>},timeoutMs?:number,maxInFlight?:number}} options
+ */
+export function createFormulaResource(options) {
+  const timeoutMs = options?.timeoutMs ?? 1000;
+  const maxInFlight = options?.maxInFlight ?? 2;
+  if (typeof options?.workerFactory !== 'function' || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647
+    || !Number.isSafeInteger(maxInFlight) || maxInFlight < 1) throw new TypeError('Invalid terminating formula worker capability');
+  let generation = 0, disposed = false, teardown = null;
+  const pending = new Set();
+  return {
+    /** Run one bounded batch in an isolate; replies must echo version/generation/revision. */
+    run(payload, { revision = '', signal = undefined } = {}) {
+      if (disposed || signal?.aborted) return Promise.resolve({ state: 'error', reason: disposed ? 'disposed' : 'cancelled' });
+      if (pending.size >= maxInFlight) return Promise.resolve({ state: 'error', reason: 'in-flight' });
+      canonicalizeJson(payload);
+      if (typeof revision !== 'string') throw new TypeError('revision must be a string');
+      const message = deepFreeze(cloneJson({ version: 1, generation: ++generation, revision, payload }));
+      for (const active of pending) active.stop('superseded');
+      let worker, request, termination, reason = null, timer;
+      let stopped;
+      const stopPromise = new Promise((resolve) => { stopped = resolve; });
+      const terminate = () => termination ??= Promise.resolve().then(() => worker?.terminate());
+      const entry = { promise: null, stop(why) { reason ??= why; stopped(); } };
+      const abort = () => entry.stop('cancelled');
+      signal?.addEventListener('abort', abort, { once: true });
+      pending.add(entry);
+      entry.promise = (async () => {
+        try {
+          worker = options.workerFactory();
+          if (typeof worker?.request !== 'function' || typeof worker?.terminate !== 'function') throw new TypeError('Invalid formula worker');
+          request = Promise.resolve().then(() => worker.request(message));
+          timer = setTimeout(() => entry.stop('deadline'), timeoutMs);
+          const reply = await Promise.race([request, stopPromise]);
+          if (reason !== null) return { state: 'error', reason, generation: message.generation, revision };
+          if (disposed || generation !== message.generation) return { state: 'invalidated', reason: 'superseded', generation: message.generation, revision };
+          if (reply?.version !== 1 || reply.generation !== message.generation || reply.revision !== revision)
+            return { state: 'invalidated', reason: 'worker-identity', generation: message.generation, revision };
+          canonicalizeJson(reply.result);
+          return deepFreeze(cloneJson({ state: 'complete', generation: message.generation, revision, result: reply.result }));
+        }
+        catch { return { state: 'error', reason: reason ?? 'worker-failed', generation: message.generation, revision }; }
+        finally {
+          clearTimeout(timer);
+          signal?.removeEventListener('abort', abort);
+          try { await terminate(); }
+          finally { await Promise.allSettled([request]); pending.delete(entry); }
+        }
+      })();
+      return entry.promise;
+    },
+    /** All admitted work, including terminating requests, counts until drained. */
+    stats() { return { pending: pending.size, generation, disposed }; },
+    /** Stop admission, terminate every worker and await settlement. Idempotent. */
+    dispose() {
+      if (teardown) return teardown;
+      disposed = true; generation++;
+      for (const entry of pending) entry.stop('disposed');
+      teardown = Promise.allSettled([...pending].map((entry) => entry.promise)).then(() => undefined);
+      return teardown;
+    },
+  };
+}

package/src/index.js

@@ -14,3 +14,5 @@ export { createTransactionLog } from './diagnostics.js';
 export { createSplitterWidget } from './splitter.js';
 export { createDocStore, encodeShare, decodeShare } from './docstore.js';
 export { AppCompileError, AppRuntimeError, HostValueError, toError, APP_CODES } from './errors.js';
+export { createArrayRangeProvider, createCollectionCoordinator } from './collection.js';
+export { createRunObservation } from './runs.js';

package/src/runs.js

@@ -0,0 +1,63 @@
+//@ts-check
+/** Resumable bounded observation as an app subscription, independent of run cancellation. */
+import { isJsonValue } from '@jarenjs/core/object';
+
+/**
+ * The injected readPage may invoke a public contract operation. One page is in
+ * flight at a time; only current summary/cursor enters app state. No event log
+ * or worker resources accumulate here. `wake` can wait for a notification or a
+ * bounded poll; after a lost notification the next page resumes the durable cursor.
+ * @param {{ readPage: (input: any, context: { signal: AbortSignal }) => any,
+ * wake: (signal: AbortSignal) => any, pageSize?: number, maxBytes?: number }} options
+ */
+export function createRunObservation(options) {
+  if (!options || typeof options.readPage !== 'function' || typeof options.wake !== 'function') throw new TypeError('run observation needs readPage and wake capabilities');
+  const { readPage, wake, pageSize = 128, maxBytes = 262144 } = options;
+  if (!Number.isSafeInteger(pageSize) || pageSize < 1 || !Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new TypeError('observation limits must be positive finite integers');
+  /** @type {Set<AbortController>} */
+  const observers = new Set();
+  let disposed = false;
+  /** @param {{ runId: string, id: number, cursor?: number, update: string, error: string }} props @param {(name: string, payload: any) => void} dispatch */
+  function observe(props, dispatch) {
+    if (!props || typeof props.runId !== 'string' || !props.runId || typeof props.update !== 'string' || typeof props.error !== 'string'
+      || !Number.isSafeInteger(props.cursor ?? 0) || (props.cursor ?? 0) < 0) throw new TypeError('run observation needs runId, revision cursor and update/error actions');
+    const controller = new AbortController();
+    const { signal } = controller;
+    if (disposed) { controller.abort(); return () => {}; }
+    observers.add(controller);
+    let cursor = props.cursor ?? 0;
+    const stop = () => { controller.abort(); observers.delete(controller); };
+    const poll = async () => {
+      try {
+        while (!signal.aborted) {
+          const page = await readPage({ id: props.runId, after: cursor, limit: pageSize }, { signal });
+          if (signal.aborted) return;
+          if (!isJsonValue(page) || new TextEncoder().encode(JSON.stringify(page)).byteLength > maxBytes
+            || typeof page.status !== 'string' || !Object.hasOwn(page, 'summary')
+            || !['page', 'reset-required'].includes(page.state) || !Array.isArray(page.events) || page.events.length > pageSize
+            || !Number.isSafeInteger(page.cursor) || page.cursor < cursor || !Number.isSafeInteger(page.revision) || page.revision < page.cursor
+            || (page.more === true && page.cursor === cursor)) throw new TypeError('invalid run observation page');
+          let seen = cursor;
+          for (const event of page.events) {
+            if (event.runId !== props.runId || !Number.isSafeInteger(event.revision) || event.revision <= seen || event.revision > page.cursor)
+              throw new TypeError('invalid run event revision');
+            seen = event.revision;
+          }
+          cursor = page.cursor;
+          dispatch(props.update, { id: props.id, runId: props.runId, cursor, revision: page.revision,
+            status: page.status, summary: page.summary, reset: page.state === 'reset-required' });
+          if (page.more !== true) await wake(signal);
+        }
+      }
+      catch {
+        if (!signal.aborted) dispatch(props.error, { id: props.id, runId: props.runId, cursor, error: { code: 'run-observation-failed' } });
+      }
+      finally { observers.delete(controller); }
+    };
+    void poll();
+    return stop;
+  }
+  /** Detach every observer; this never calls a run's cancel operation. */
+  observe.dispose = () => { disposed = true; for (const observer of observers) observer.abort(); observers.clear(); };
+  return observe;
+}

package/src/search.js

@@ -0,0 +1,101 @@
+//@ts-check
+/** Private index ownership over an injected, draining worker capability. */
+import { compileLexical } from '@jarenjs/core/search';
+import { utf8ByteLength } from '@jarenjs/core/string';
+
+/**
+ * Own one worker and one published index. Worker request/reply envelopes carry
+ * version, requestId, generation and sourceRevision; build replies carry snapshots.
+ * dispose() on the injected worker must settle every request, including aborted ones.
+ * @param {import('@jarenjs/core/search').LexicalDefinition} definition
+ * @param {{workerFactory:()=>{request:(message:any, options:any)=>Promise<any>, dispose:()=>any},
+ * maxInFlight?:number, onProgress?:(progress:any)=>void}} options
+ */
+export function createSearchResource(definition, options) {
+  const compiled = compileLexical(definition), maxInFlight = options?.maxInFlight ?? 2;
+  if (typeof options?.workerFactory !== 'function' || !Number.isSafeInteger(maxInFlight) || maxInFlight < 1)
+    throw new TypeError('Invalid search worker capability');
+  const fields = [...new Set(['id', ...compiled.config.fields])];
+  let worker = null, index = compiled.create(), disposed = false, ticket = 0, generation = -1, teardown = null;
+  const pending = new Map();
+  return {
+    /** @param {any[]} documents @param {{generation:number, sourceRevision:string, requestId:string}} identity @param {AbortSignal} [signal] */
+    build(documents, identity, signal) {
+      identity = { ...identity };
+      const refuse = (state, reason) => ({ ...identity, state, reason });
+      if (disposed) return Promise.resolve(refuse('error', 'disposed'));
+      if (signal?.aborted) return Promise.resolve(refuse('error', 'cancelled'));
+      if (!identity || !Number.isSafeInteger(identity.generation) || identity.generation < 0
+        || typeof identity.sourceRevision !== 'string' || typeof identity.requestId !== 'string')
+        return Promise.resolve(refuse('error', 'invalid-identity'));
+      if (identity.generation <= generation) return Promise.resolve(refuse('invalidated', 'stale-generation'));
+      if (pending.size >= maxInFlight) return Promise.resolve(refuse('budget-exhausted', 'in-flight'));
+      if (!Array.isArray(documents)) return Promise.resolve(refuse('error', 'invalid-documents'));
+      if (documents.length > compiled.config.limits.maxDocuments) return Promise.resolve(refuse('budget-exhausted', 'documents'));
+      const projected = []; let bytes = 0;
+      for (const document of documents) {
+        const row = {};
+        for (const field of fields) {
+          const value = document && Object.hasOwn(document, field) ? document[field] ?? '' : '';
+          if (typeof value !== 'string' || (field === 'id' && !value)) return Promise.resolve(refuse('error', 'invalid-documents'));
+          if (value.length > compiled.config.limits.maxFieldBytes) return Promise.resolve(refuse('budget-exhausted', 'field-bytes'));
+          const length = utf8ByteLength(value);
+          if (length > compiled.config.limits.maxFieldBytes) return Promise.resolve(refuse('budget-exhausted', 'field-bytes'));
+          bytes += length;
+          if (bytes > compiled.config.limits.maxSourceBytes || bytes * 4 + projected.length * 128 > compiled.config.limits.maxTemporaryBytes)
+            return Promise.resolve(refuse('budget-exhausted', 'source-bytes'));
+          Object.defineProperty(row, field, { value, enumerable: true });
+        }
+        projected.push(row);
+      }
+      for (const controller of pending.keys()) controller.abort();
+      generation = identity.generation; const mine = ++ticket, controller = new AbortController();
+      const abort = () => controller.abort(signal.reason);
+      signal?.addEventListener('abort', abort, { once: true });
+      let lastWork = -1;
+      const run = async () => {
+        try {
+          worker ??= options.workerFactory();
+          if (typeof worker?.request !== 'function' || typeof worker?.dispose !== 'function') throw new TypeError('Invalid search worker');
+          const reply = await worker.request({ version: 1, operation: 'build', definition: compiled.config, ...identity, documents: projected }, {
+            signal: controller.signal,
+            onProgress(progress) {
+              if (!disposed && !controller.signal.aborted && mine === ticket && progress?.version === 1
+                && ['generation', 'requestId', 'sourceRevision'].every((key) => progress[key] === identity[key])
+                && Number.isSafeInteger(progress.work) && progress.work >= 0 && progress.work >= lastWork) {
+                lastWork = progress.work; options.onProgress?.({ ...identity, work: progress.work });
+              }
+            },
+          });
+          if (disposed) return refuse('error', 'disposed');
+          if (mine !== ticket) return refuse('invalidated', 'superseded');
+          if (controller.signal.aborted) return refuse('error', 'cancelled');
+          if (reply?.version !== 1 || !['generation', 'requestId', 'sourceRevision'].every((key) => reply[key] === identity[key]))
+            return refuse('invalidated', 'worker-identity');
+          if (reply.state !== 'complete') return refuse(['error', 'budget-exhausted'].includes(reply.state) ? reply.state : 'error', reply.reason ?? 'incomplete-worker');
+          const candidate = compiled.create();
+          const loaded = candidate.restore(reply.snapshot, identity);
+          if (loaded.state !== 'complete') { candidate.dispose(); return refuse(loaded.state, loaded.reason); }
+          const old = index; index = candidate; old.dispose();
+          return { ...identity, state: 'complete', documents: index.stats().documents };
+        }
+        catch (error) { return refuse('error', disposed ? 'disposed' : controller.signal.aborted ? 'cancelled' : String(error?.message ?? error)); }
+      };
+      const promise = run().finally(() => { pending.delete(controller); signal?.removeEventListener('abort', abort); });
+      pending.set(controller, promise); return promise;
+    },
+    /** @param {string} text @param {any} [options] */
+    search(text, options) { return index.search(text, options); },
+    stats() { return { ...index.stats(), workers: worker ? 1 : 0, pending: pending.size }; },
+    /** Stop admission, fence callbacks, terminate the worker and drain its requests. */
+    dispose() {
+      if (teardown) return teardown;
+      disposed = true; ticket++; for (const controller of pending.keys()) controller.abort(); index.dispose();
+      teardown = (async () => {
+        try { await worker?.dispose(); }
+        finally { await Promise.allSettled(pending.values()); worker = null; }
+      })();
+      return teardown;
+    },
+  };
+}