@loomwork/ui-hydration 0.0.0-stage → 0.1.1

package/dist/plan.js.map

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

package/dist/projection.d.ts

@@ -0,0 +1,122 @@
+import type { Projection, ProjectionRuntime } from "@loomwork/projection-runtime";
+import type { Audience, Finding } from "@loomwork/ui-core";
+export declare const HYDRATION_PROJECTION_ID = "loom-ui.hydration";
+/**
+ * Bump when the MEANING of `values`/`status` changes; the compiler pins this into every blueprint.
+ * 1.1.0: a status may be `empty` (loom ADR 0100), and the fold DROPS the handle's value with it.
+ */
+export declare const HYDRATION_PROJECTION_VERSION = "1.1.0";
+export declare const HYDRATION_SET_EVENT = "LOOM_UI_HYDRATION_SET";
+/**
+ * `empty`: delivered, and the upstream has no such row — "no data", never an error (loom ADR
+ * 0100). It never carries a value: the fold drops `values[handle]` on it.
+ */
+export type HandleState = "pending" | "ready" | "stale" | "error" | "empty";
+export interface HandleStatus {
+    readonly state: HandleState;
+    readonly seq: number;
+    readonly finding?: Finding;
+}
+export interface HydrationState {
+    readonly values: Record<string, unknown>;
+    readonly status: Record<string, HandleStatus>;
+}
+export declare function isReservedHandle(handle: string): boolean;
+export declare function hydrationProjection(): Projection<HydrationState>;
+export interface HandleSlice {
+    readonly value: unknown;
+    readonly status: HandleStatus | undefined;
+}
+/**
+ * What a store's state belongs to. Isolation is by (experience, principal, audience); two viewers
+ * of one experience must not share a store — `values` holds whatever the viewer's own principal chain
+ * was allowed to read, so a shared store is a cross-viewer data leak, not a cache win.
+ * Omit `principalId` only where there is genuinely one viewer (a single-user CLI, a test).
+ */
+export interface HydrationScope {
+    readonly experienceId: string;
+    readonly principalId?: string;
+    /**
+     * The audience the store's surface is drawn for (`@loomwork/ui-core` `Audience`). A broadcast
+     * surface and a viewer surface of the same principal are DIFFERENT scopes: a broadcast bind
+     * removes the handles it withholds, and that must never erase the personal surface's values.
+     * The controller refuses a store whose audience differs from its own ({@link HydrationAudienceMismatchError}).
+     */
+    readonly audience?: Audience;
+}
+/** A controller and its store disagree about the audience (one broadcast, the other not). */
+export declare class HydrationAudienceMismatchError extends Error {
+    readonly controllerBroadcast: boolean;
+    readonly code: "hydration-audience-mismatch";
+    constructor(controllerBroadcast: boolean);
+}
+/** An `experienceId` or `principalId` contains NUL, the separator of the broadcast scope key. */
+export declare class HydrationScopeError extends Error {
+    readonly field: "experienceId" | "principalId";
+    readonly code: "hydration-scope-invalid";
+    constructor(field: "experienceId" | "principalId");
+}
+export declare class HydrationStore {
+    private readonly runtime;
+    readonly scope: HydrationScope;
+    /** Open token streams by handle (see {@link append}). A replace/remove/empty ends the handle's. */
+    private readonly streams;
+    /**
+     * Installed by the controller that fronts this store: a refusal for a handle that may not take
+     * chunks (restricted for the viewer, unbound, not a streaming widget). Absent on a bare store.
+     */
+    private appendGuard;
+    private seq;
+    private emitSeq;
+    /** The projection state key: the scope, flattened. Derived — never passed in. */
+    readonly executionId: string;
+    /**
+     * Isolation is by (experience, principal); two viewers of one experience must not share a
+     * store. The projection is keyed by `executionId`, so a per-viewer store is what keeps one
+     * viewer's values out of another's widgets even on a SHARED `ProjectionRuntime`.
+     */
+    constructor(runtime: ProjectionRuntime, scope: HydrationScope, opts?: {
+        register?: boolean;
+    });
+    state(): HydrationState;
+    status(handle: string): HandleStatus | undefined;
+    value(handle: string): unknown;
+    handles(): string[];
+    setStatus(handle: string, status: Omit<HandleStatus, "seq">): void;
+    setValue(handle: string, value: unknown, status: Omit<HandleStatus, "seq">): void;
+    remove(handle: string): void;
+    /**
+     * Gate every {@link append} through `guard` (a refusal finding, or undefined to allow). A
+     * `HydrationController` installs one over the store it fronts, so a producer cannot write a
+     * viewer-restricted handle's text into the projected store behind the controller's back. A bare
+     * store (no controller) has no viewer and no experience to gate against and stays ungated.
+     */
+    guardAppend(guard: ((handle: string) => Finding | undefined) | undefined): void;
+    /**
+     * Append one chunk of a token stream (`StreamingText`) to a handle. The handle's value is the
+     * accumulated string — widgets and the value contract are unchanged — and its status is
+     * `pending` while the stream is open and `ready` once a chunk carries `done`.
+     *
+     * ORDERING with a whole-value writer (`setValue`/`remove`, e.g. the controller superseding a
+     * load): they are synchronous and the last writer wins. A replace ENDS the stream; the
+     * producer's next chunk then refuses (`stream-gap`, `seq` no longer 0) rather than corrupt the
+     * replacement, and a producer that wants to stream again starts a new stream at `seq` 0, which
+     * replaces the value. The contract itself (idempotence, gap, close, bounds) is core's
+     * `appendChunk`. A refusal emits nothing; a duplicate is `applied: false` and emits nothing.
+     */
+    append(handle: string, chunk: unknown): {
+        ok: true;
+        applied: boolean;
+    } | {
+        ok: false;
+        finding: Finding;
+    };
+    /** Whole-state subscription: fires on ANY handle's value or status change. For a surface that renders the full projection (e.g. a terminal `watch` loop) rather than one widget's slice. */
+    runtimeSubscribe(listener: (state: HydrationState) => void): () => void;
+    /** Slice-scoped: fires only when THIS handle's status seq or value changes. Change-only, like loom's subscribe. */
+    subscribe(handle: string, listener: (slice: HandleSlice) => void): () => void;
+    private assertValidHandle;
+    private stamp;
+    private emit;
+}
+//# sourceMappingURL=projection.d.ts.map

package/dist/projection.d.ts.map

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

package/dist/projection.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HydrationStore = exports.HydrationScopeError = exports.HydrationAudienceMismatchError = exports.HYDRATION_SET_EVENT = exports.HYDRATION_PROJECTION_VERSION = exports.HYDRATION_PROJECTION_ID = void 0;
+exports.isReservedHandle = isReservedHandle;
+exports.hydrationProjection = hydrationProjection;
+const browser_1 = require("@loomwork/ui-core/browser");
+// ── One projection, keyed by handle ───────────────────────────────────────────
+// Compiled widgets bind to `values.<handle>` and declare `status.<handle>` as their status
+// channel (core's `hydrationPath`/`hydrationStatusPath`), and the compiler pins
+// HYDRATION_PROJECTION_VERSION into the blueprint (ADR 0095). Hydration is imperative and
+// transient — nothing here is durable or replayed — so the projection is driven by ONE synthetic
+// in-memory event type. `subscribeSelector` gives each handle its own slice, so a value resolving
+// wakes one widget, not the surface.
+exports.HYDRATION_PROJECTION_ID = "loom-ui.hydration";
+/**
+ * Bump when the MEANING of `values`/`status` changes; the compiler pins this into every blueprint.
+ * 1.1.0: a status may be `empty` (loom ADR 0100), and the fold DROPS the handle's value with it.
+ */
+exports.HYDRATION_PROJECTION_VERSION = "1.1.0";
+exports.HYDRATION_SET_EVENT = "LOOM_UI_HYDRATION_SET";
+const RESERVED = new Set(["__proto__", "constructor", "prototype"]);
+function isReservedHandle(handle) {
+    return RESERVED.has(handle);
+}
+// `Object.fromEntries` uses CreateDataProperty for each entry, so a `__proto__` key lands as
+// an own property — never the prototype setter that a plain `out[k] = v` assignment would hit.
+function without(rec, key) {
+    return Object.fromEntries(Object.entries(rec).filter(([k]) => k !== key));
+}
+function hydrationProjection() {
+    return {
+        id: exports.HYDRATION_PROJECTION_ID,
+        version: exports.HYDRATION_PROJECTION_VERSION,
+        initialState: { values: {}, status: {} },
+        handlers: {
+            [exports.HYDRATION_SET_EVENT]: (state, event) => {
+                const p = event.payload;
+                // Defense in depth: `HydrationStore` already refuses reserved handles before emitting,
+                // but this projection is registered on a SHARED runtime — any other holder of that
+                // runtime can call `handleEvent` directly with a forged envelope, bypassing the store.
+                // The fold itself must never write a reserved handle into state.
+                if (isReservedHandle(p.handle))
+                    return state;
+                if (p.kind === "remove") {
+                    if (!Object.hasOwn(state.status, p.handle) && !Object.hasOwn(state.values, p.handle))
+                        return state;
+                    return {
+                        values: without(state.values, p.handle),
+                        status: without(state.status, p.handle),
+                    };
+                }
+                const status = { ...state.status, [p.handle]: p.status };
+                // loom ADR 0100 D1: a producer MUST clear the value beside `empty` — an older reader that
+                // cannot see `empty` would otherwise show an earlier `ready` value as current.
+                if (p.status?.state === "empty")
+                    return {
+                        values: Object.hasOwn(state.values, p.handle)
+                            ? without(state.values, p.handle)
+                            : state.values,
+                        status,
+                    };
+                if (p.kind === "status")
+                    return { values: state.values, status };
+                return { values: { ...state.values, [p.handle]: p.value }, status };
+            },
+        },
+    };
+}
+/** A controller and its store disagree about the audience (one broadcast, the other not). */
+class HydrationAudienceMismatchError extends Error {
+    controllerBroadcast;
+    code = "hydration-audience-mismatch";
+    constructor(controllerBroadcast) {
+        super(controllerBroadcast
+            ? 'HydrationController: a broadcast controller needs a store scoped { audience: "broadcast" }'
+            : "HydrationController: a store scoped to a broadcast audience needs a broadcast controller");
+        this.controllerBroadcast = controllerBroadcast;
+        this.name = "HydrationAudienceMismatchError";
+    }
+}
+exports.HydrationAudienceMismatchError = HydrationAudienceMismatchError;
+/** An `experienceId` or `principalId` contains NUL, the separator of the broadcast scope key. */
+class HydrationScopeError extends Error {
+    field;
+    code = "hydration-scope-invalid";
+    constructor(field) {
+        super(`HydrationStore: ${field} must not contain a NUL character (it separates the broadcast scope key)`);
+        this.field = field;
+        this.name = "HydrationScopeError";
+    }
+}
+exports.HydrationScopeError = HydrationScopeError;
+class HydrationStore {
+    runtime;
+    scope;
+    /** Open token streams by handle (see {@link append}). A replace/remove/empty ends the handle's. */
+    streams = new Map();
+    /**
+     * Installed by the controller that fronts this store: a refusal for a handle that may not take
+     * chunks (restricted for the viewer, unbound, not a streaming widget). Absent on a bare store.
+     */
+    appendGuard;
+    seq = 0; // status seq — monotone per store
+    emitSeq = 0; // envelope sequence — every emit, including remove
+    /** The projection state key: the scope, flattened. Derived — never passed in. */
+    executionId;
+    /**
+     * Isolation is by (experience, principal); two viewers of one experience must not share a
+     * store. The projection is keyed by `executionId`, so a per-viewer store is what keeps one
+     * viewer's values out of another's widgets even on a SHARED `ProjectionRuntime`.
+     */
+    constructor(runtime, scope, opts = {}) {
+        this.runtime = runtime;
+        this.scope = scope;
+        // The key below joins with NUL; an id carrying one could forge another scope's key
+        // (principal "p\0broadcast" would land on the broadcast scope of "p").
+        if (scope.experienceId.includes("\u0000"))
+            throw new HydrationScopeError("experienceId");
+        if (scope.principalId?.includes("\u0000"))
+            throw new HydrationScopeError("principalId");
+        const base = scope.principalId === undefined
+            ? scope.experienceId
+            : `${scope.experienceId}:${scope.principalId}`;
+        // NUL cannot appear in a typed id suffix a principal could forge, so a principal named
+        // "p:broadcast" never lands on the broadcast scope of "p".
+        this.executionId = (0, browser_1.isBroadcast)(scope.audience) ? `${base}\u0000broadcast` : base;
+        if (opts.register !== false)
+            runtime.register(hydrationProjection());
+    }
+    state() {
+        return this.runtime.getState(exports.HYDRATION_PROJECTION_ID, this.executionId);
+    }
+    status(handle) {
+        const s = this.state().status;
+        return Object.hasOwn(s, handle) ? s[handle] : undefined;
+    }
+    value(handle) {
+        const v = this.state().values;
+        return Object.hasOwn(v, handle) ? v[handle] : undefined;
+    }
+    handles() {
+        return Object.keys(this.state().status);
+    }
+    setStatus(handle, status) {
+        this.assertValidHandle(handle);
+        // `empty` drops the value, so a stream continuing onto it would resurrect a value the fold cleared.
+        if (status.state === "empty")
+            this.streams.delete(handle);
+        this.emit({ kind: "status", handle, status: this.stamp(status) });
+    }
+    setValue(handle, value, status) {
+        this.assertValidHandle(handle);
+        // A whole-value replace (a controller load, a supersede) ends the handle's token stream: the
+        // stream's accumulated text is no longer what the handle holds, so a producer's later chunks
+        // are refused (`stream-gap`) instead of being spliced onto the replacement.
+        this.streams.delete(handle);
+        this.emit({ kind: "value", handle, value, status: this.stamp(status) });
+    }
+    remove(handle) {
+        this.assertValidHandle(handle);
+        this.streams.delete(handle);
+        this.emit({ kind: "remove", handle });
+    }
+    /**
+     * Gate every {@link append} through `guard` (a refusal finding, or undefined to allow). A
+     * `HydrationController` installs one over the store it fronts, so a producer cannot write a
+     * viewer-restricted handle's text into the projected store behind the controller's back. A bare
+     * store (no controller) has no viewer and no experience to gate against and stays ungated.
+     */
+    guardAppend(guard) {
+        this.appendGuard = guard;
+    }
+    /**
+     * Append one chunk of a token stream (`StreamingText`) to a handle. The handle's value is the
+     * accumulated string — widgets and the value contract are unchanged — and its status is
+     * `pending` while the stream is open and `ready` once a chunk carries `done`.
+     *
+     * ORDERING with a whole-value writer (`setValue`/`remove`, e.g. the controller superseding a
+     * load): they are synchronous and the last writer wins. A replace ENDS the stream; the
+     * producer's next chunk then refuses (`stream-gap`, `seq` no longer 0) rather than corrupt the
+     * replacement, and a producer that wants to stream again starts a new stream at `seq` 0, which
+     * replaces the value. The contract itself (idempotence, gap, close, bounds) is core's
+     * `appendChunk`. A refusal emits nothing; a duplicate is `applied: false` and emits nothing.
+     */
+    append(handle, chunk) {
+        this.assertValidHandle(handle);
+        const refusal = this.appendGuard?.(handle);
+        if (refusal !== undefined)
+            return { ok: false, finding: refusal };
+        const r = (0, browser_1.appendChunk)(this.streams.get(handle), chunk);
+        if (!r.ok)
+            return r;
+        if (!r.applied)
+            return { ok: true, applied: false };
+        this.streams.set(handle, r.state);
+        this.emit({
+            kind: "value",
+            handle,
+            value: r.state.text,
+            status: this.stamp({ state: r.state.done ? "ready" : "pending" }),
+        });
+        return { ok: true, applied: true };
+    }
+    /** Whole-state subscription: fires on ANY handle's value or status change. For a surface that renders the full projection (e.g. a terminal `watch` loop) rather than one widget's slice. */
+    runtimeSubscribe(listener) {
+        return this.runtime.subscribe(exports.HYDRATION_PROJECTION_ID, this.executionId, listener);
+    }
+    /** Slice-scoped: fires only when THIS handle's status seq or value changes. Change-only, like loom's subscribe. */
+    subscribe(handle, listener) {
+        return this.runtime.subscribeSelector(exports.HYDRATION_PROJECTION_ID, this.executionId, (s) => ({
+            value: Object.hasOwn(s.values, handle) ? s.values[handle] : undefined,
+            status: Object.hasOwn(s.status, handle) ? s.status[handle] : undefined,
+        }), listener, (a, b) => a.status?.seq === b.status?.seq && a.value === b.value);
+    }
+    assertValidHandle(handle) {
+        if (isReservedHandle(handle))
+            throw new Error(`handle "${handle}" is reserved`);
+    }
+    stamp(status) {
+        this.seq += 1;
+        return { ...status, seq: this.seq };
+    }
+    emit(payload) {
+        this.emitSeq += 1;
+        const envelope = {
+            id: `loom-ui-hydration-${this.executionId}-${this.emitSeq}`,
+            workflowId: "loom-ui.hydration",
+            executionId: this.executionId,
+            eventType: exports.HYDRATION_SET_EVENT,
+            sequence: this.emitSeq,
+            timestamp: 0, // transient; never persisted, never compared
+            payload,
+        };
+        this.runtime.handleEvent(envelope);
+    }
+}
+exports.HydrationStore = HydrationStore;
+//# sourceMappingURL=projection.js.map

package/dist/projection.js.map

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

package/dist/provider.d.ts

@@ -0,0 +1,152 @@
+import { type TaintedValue } from "@loomwork/classify";
+import type { TransientInvokeOptions } from "@loomwork/effect-runtime";
+import { type Shape } from "@loomwork/plugin-sandbox";
+import { type ContentRefTable, type ContractRegistry, type Finding, type ProviderSpec } from "@loomwork/ui-core";
+import { type ContentRefParamGate } from "./contentRefs";
+import { type DataProviderRegistry } from "./dataProvider";
+import type { TransientInvoker } from "./invoker";
+import { type ArgumentHook, type LoadParams } from "./params";
+import { type ReshapeFailureKind, type ReshaperRegistry } from "./reshape";
+import type { HandleLoadResult } from "./scheduler";
+export interface DriftRecord {
+    /**
+     * `input`: a step's input-schema pin moved — a pin move `remapOperation` can repair. `output`:
+     * the reshaping no longer works for the tool's output — the reshaped value fails its shape pin
+     * or value contract, OR the reshaping itself failed on it (`reshapeFailure`) — which only a
+     * re-authored binding (a planner) can repair.
+     */
+    readonly kind: "input" | "output";
+    readonly handle: string;
+    /**
+     * The step that drifted. Input drift: the step whose schema pin drifted (always present).
+     * Output drift: the terminal step whose output was reshaped, set only when the graph has
+     * exactly one terminal — with several terminals the raw sample is a record keyed by stepId, not
+     * one step's output, so no single step identity applies.
+     */
+    readonly stepId?: string;
+    readonly toolName?: string;
+    /**
+     * Input drift only, and ONLY for a step whose kind is not MCP: that kind (`step.kind`), so a
+     * repairer knows `toolName` is a target of that kind, not an MCP tool. Absent for MCP — a record
+     * for an MCP step is exactly what it was before kinds existed.
+     */
+    readonly providerKind?: string;
+    readonly expected: string;
+    readonly observed: string;
+    /**
+     * Output drift under `outputCheck: "contract"` only: the kind whose value contract the reshaped
+     * value failed. `expected` is then `contract:<kind>` and `observed` the value's shape hash.
+     */
+    readonly contractKind?: string;
+    /**
+     * Output drift only, set when the RESHAPING ITSELF failed on the tool's output — and only when
+     * the output demonstrably caused it (`reshapeFailureKind`): the failure's finding code
+     * (`reshape-<channel>` / `reshape-failed`). `expected` is then `reshape` and `observed` that
+     * same code, and there is no reshaped value, so `observedShape` is absent — the raw output
+     * (`observedRawShape`, `observedSample`) is what a repair is authored against. Infrastructure
+     * and transient failures (a `wallClock` limit, an untyped throw, a denial, a missing script or
+     * reshaper, an abort) record no drift. The handle's status stays `error` (not `stale`) and the
+     * public finding is unchanged; the drift is reported for repair (`onDrift`).
+     */
+    readonly reshapeFailure?: string;
+    /** Beside `reshapeFailure`: WHY, typed — so a consumer can exclude a kind without parsing findings. */
+    readonly reshapeFailureKind?: ReshapeFailureKind;
+    /**
+     * Output drift only: the structural shape loom's `shapeOf` saw of the RESHAPED value — the one
+     * that failed the check, so it explains the mismatch. Absent when the value could not be walked,
+     * and on a `reshapeFailure` (there is no reshaped value).
+     */
+    readonly observedShape?: Shape;
+    /**
+     * Output drift only: the structural shape of the RAW terminal output the reshaping was applied
+     * to. A planner re-authors a `reshaping.scriptRef`, which is a path into the RAW output — so
+     * without this a record carrying no sample gives it nothing to author a path against.
+     * Absent when the raw value could not be walked.
+     */
+    readonly observedRawShape?: Shape;
+    /**
+     * Output drift only, and ONLY when `ExecuteOptions.captureSample` is set: the RAW terminal
+     * output (the single terminal step's output, or the stepId-keyed record when there are several)
+     * — NOT the reshaped value, because the planner consumes a sample as a capability's
+     * `sampleOutput`, which is raw by contract and is what a `path` is authored against. ALWAYS
+     * wrapped as untrusted content (ADR 0085): it is tool-authored and will be shown to a model.
+     */
+    readonly observedSample?: TaintedValue<unknown>;
+}
+export type ProviderOutcome = 
+/** `drift` only when an input drift was proceeded past (`inputDrift: "report-and-proceed"`). */
+{
+    ok: true;
+    value: unknown;
+    findings: Finding[];
+    drift?: DriftRecord[];
+} | {
+    ok: false;
+    finding: Finding;
+    drift: DriftRecord[];
+    findings: Finding[];
+};
+/** What a load does on an input-schema drift: go stale (`report`), or record it and retry once with the observed pin. */
+export type InputDriftMode = "report" | "report-and-proceed";
+export interface ExecuteOptions {
+    readonly invoker: TransientInvoker;
+    readonly signal?: AbortSignal;
+    readonly principal?: TransientInvokeOptions["principal"];
+    /** Parallel steps per wave. Default 4. */
+    readonly concurrency?: number;
+    /** Attach the RAW terminal output to an output-drift record as a tainted sample. Default false. */
+    readonly captureSample?: boolean;
+    /**
+     * The kinds the handle's bound nodes resolve to on the surface being hydrated (core's
+     * `handleKinds`). Read only when the spec's `outputCheck` is `"contract"` — which REFUSES to run
+     * without them: a contract check over no kinds would pass every value.
+     */
+    readonly kinds?: readonly string[];
+    /**
+     * The host's value contracts for kinds outside the framework's (`SemanticCatalog.valueContracts`).
+     * A `"contract"` provider feeding a kind with neither contract is REFUSED (`output-contract-missing`).
+     */
+    readonly contracts?: ContractRegistry;
+    /**
+     * Per-load params: applied only to arguments a step declares `overridable`, never to a
+     * `{{steps.…}}` template. A param no step declares is ignored with a `param-not-overridable` warn.
+     */
+    readonly params?: LoadParams;
+    /** The instant relative-time tokens resolve against (epoch ms). Default: `Date.now()`, read once. */
+    readonly now?: number;
+    /** The host's last word on each step's arguments (after params, tokens, templates). */
+    readonly argumentHook?: ArgumentHook;
+    /**
+     * The marked content-reference argument paths per tool (`toolKey`; core `contentRefPaths`, the
+     * planner's `contentRefArgsFrom`). A step whose tool is listed is refused (`media-arg-literal`, the
+     * call not made) when a marked argument holds a literal. Absent = nothing is marked.
+     */
+    readonly contentRefArgs?: ContentRefTable;
+    /** Who the load runs for, as the gate's `principalId` (the controller's `principal.id`, serve's `principalId`). */
+    readonly principalId?: string;
+    /** The host's gate on a param that fills a marked argument; absent = every such param is refused. */
+    readonly acceptContentRefParam?: ContentRefParamGate;
+    /** On an input-schema drift. Default `"report"`. */
+    readonly inputDrift?: InputDriftMode;
+    /** Where `reshaping.engine: "Named"` looks its reshaper up. */
+    readonly reshapers?: ReshaperRegistry;
+    /**
+     * The data-provider kinds this host composed (`defineDataProviders`). Default: MCP only, which is
+     * every step of an experience written before kinds existed. A step naming a kind not in here
+     * fails the whole provider as `provider-kind-unregistered`, before any step runs.
+     */
+    readonly providers?: DataProviderRegistry;
+}
+/** The PUBLIC code of a step refused by the content-reference guard (literal, unproven ref, or a param the gate refused). */
+export declare const CONTENT_REF_REFUSED = "content-ref-refused";
+export declare function executeProvider(spec: ProviderSpec, opts: ExecuteOptions): Promise<ProviderOutcome>;
+/**
+ * What an outcome publishes — the ONE mapping both the in-process controller and `serveHandle`
+ * use, so split and in-process hydration cannot disagree: a value is `ready` (carrying the first
+ * warning, e.g. a proceeded drift); an `upstream-empty` failure is `empty` — checked FIRST, and
+ * carrying no value (loom ADR 0100: a producer MUST clear the value beside `empty`); a failure
+ * with drift is `stale` — unless its only drift is a failed reshaping (`reshapeFailure`), which
+ * stays `error` as it always was — and any other failure `error`.
+ */
+export declare function outcomeResult(outcome: ProviderOutcome): HandleLoadResult;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

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