@ai-matrx/alchemy 0.13.0 → 0.14.0

package/dist/surface.d.cts

@@ -1,3 +1,5 @@
+import { Json as Json$2 } from '@ai-matrx/kit/transfer-json';
+
 /**
  * Matrx Alchemy — Declare types (CONTRACT §2.1).
  *
@@ -5,8 +7,8 @@
  * no React. Runtime behaviour lives in `MountedSurface` (`/declare/host`) and in
  * handler registrations, never here. Zero React, zero `@ai-matrx/agents`.
  */
-type Json$2 = null | boolean | number | string | Json$2[] | {
-    [key: string]: Json$2;
+type Json$1 = null | boolean | number | string | Json$1[] | {
+    [key: string]: Json$1;
 };
 /** Unchanged from `ui_surface_value_type_chk`. */
 type ValueType = "string" | "number" | "boolean" | "object" | "array" | "document";
@@ -136,6 +138,8 @@ interface SurfaceDeclaration {
     configNamespaces?: readonly ConfigNamespaceDeclaration[];
     evidenceSources?: readonly EvidenceSourceDeclaration[];
     skipBaselineValues?: boolean;
+    /** Opt out of the host's baseline item types (`baselineItemTypes`, e.g. `TABLE_ROW_ITEM_TYPE`). */
+    skipBaselineItemTypes?: boolean;
 }
 type ValueProvenance = {
     kind: "own";
@@ -161,6 +165,37 @@ interface ResolvedSurfaceDeclaration extends SurfaceDeclaration {
  * The qualified key "<itemType>.<name>" names an item value; a bare name is a screen value.
  */
 type QualifiedValueKey = string;
+/** Live slot payloads (page-capture's shapes, kept). */
+interface LiveValues {
+    selection?: {
+        choices: Record<string, Json$1>;
+        text: string | null;
+    };
+    "on-demand"?: readonly OnDemandSection[];
+    errors?: readonly string[];
+    requests?: readonly RecentRequest[];
+}
+interface OnDemandSection {
+    id: string;
+    title: string;
+    description?: string;
+    role: "data" | "request";
+    brief?: Json$1;
+    load(signal: AbortSignal): Promise<Json$1>;
+}
+interface RecentRequest {
+    method: string;
+    path: string;
+    status: string;
+    httpStatus?: number;
+    durationMs?: number;
+    requestId?: string;
+    client?: string;
+    requestBody?: Json$1;
+    requestBodyNote?: string;
+    errorSentence?: string;
+    timestamp: number;
+}
 /** RAW-FREE. What leaves the package about a clicked item. */
 interface ResolvedItem {
     itemType: string;
@@ -254,7 +289,7 @@ type ActionResult<T = unknown> = {
 /** `POST /actions/run` (aidream) — the request. */
 interface ServerActionRunRequest {
     name: string;
-    input: Json$2;
+    input: Json$1;
     by: ActionCaller;
     surface_name?: string;
     policy?: ActionPolicy;
@@ -263,8 +298,8 @@ interface ServerActionRunRequest {
 interface ServerActionRunResponse {
     status: "applied" | "proposed" | "refused";
     message: string;
-    receipts: Json$2[];
-    proposal?: Json$2;
+    receipts: Json$1[];
+    proposal?: Json$1;
 }
 /** A mandate run request: by alias (an Action's `target`) or by key. */
 type MandateRunRequest = ({
@@ -274,7 +309,7 @@ type MandateRunRequest = ({
     key: string;
     alias?: never;
 }) & {
-    variables: Record<string, Json$2>;
+    variables: Record<string, Json$1>;
     userInput?: string;
     by: ActionCaller;
     policy: ActionPolicy;
@@ -402,14 +437,6 @@ interface ClickTarget {
     host?: unknown;
 }
 
-/**
- * Framework-neutral transfer contracts (Alchemy Operate, CONTRACT §2.3). All data crossing this boundary is JSON.
- * Moved from `@ai-matrx/kit/content-transfer` in ALC-16; the format-adapter contract lives in `./contract`.
- */
-type Json$1 = null | boolean | number | string | Json$1[] | {
-    [key: string]: Json$1;
-};
-
 /**
  * Operate — the format and delivery contract (Matrx Alchemy CONTRACT §2.3, ALC-16).
  *
@@ -439,7 +466,7 @@ type Receipt = {
     sentence: string;
     warning?: string;
     fix?: string; /** What the handler produced (e.g. the created record). */
-    result?: Json$1;
+    result?: Json$2;
 } | {
     status: "queued";
     to: WriteTargetRef;
@@ -944,6 +971,127 @@ interface ServerPort {
 
 type SurfaceActionPorts = Pick<AlchemyHostPorts, "diagnostics" | "serverActions" | "mandates" | "pageActions" | "overlay" | "approvals" | "door">;
 
+/**
+ * LIVE VALUES — what a mounted page holds right now (ALC-18, LIST.md D3).
+ *
+ * A page publishes ONE live capture while it is mounted: its title and route, what it is OF
+ * (`identity`), the exact choices the person made (`selection`), its data sections, the errors on
+ * screen and its recent requests. Descendants that hold state the page does not (a grid's rows, a
+ * compare view) contribute sections. Every reader — the page's Alchemy menu, the admin debug
+ * context, an agent through `SurfacePort.getValue` — reads the SAME capture through this store, at
+ * read time, from the live getters. There is no second capture path.
+ *
+ * The four declared live slots (`LiveSlot`: selection, on-demand, errors, requests) are views of
+ * the capture (`liveSlotsOf`), and a surface's named value reads through `liveValueOf`.
+ *
+ * Framework-neutral: no React, no DOM. A host hook subscribes with `subscribe` + `version`
+ * (`useSyncExternalStore`). The most recent publication wins (a dialog over a page, a page over
+ * the shell's default).
+ */
+
+type LiveCaptureKind = "table-page" | "record" | "dialog" | "admin-page";
+/** A chosen thing, by name and id. Either may be null (not chosen / not loaded). */
+interface LiveNamed {
+    id: string | null;
+    name: string | null;
+}
+type LiveCaptureValue = LiveNamed | string | number | boolean | null;
+interface LiveSection {
+    /** Stable id, unique within one capture. */
+    id: string;
+    /** What the person calls this part of the page. */
+    title: string;
+    description?: string;
+    /** `data` survives "Only the data"; `request` does not. */
+    role: "data" | "request";
+    value: unknown;
+    /** The one-line brief (counts, a sentence). */
+    brief?: unknown;
+    /** A section too big to hold on the page: `value` is the honest stub and `load` reads it on use. */
+    load?: () => Promise<unknown>;
+}
+interface LiveRequest {
+    method: string;
+    path: string;
+    status: string;
+    httpStatus?: number;
+    durationMs?: number;
+    requestId?: string;
+    /** Which client door (supabase-rest, supabase-rpc, aidream, next-api …). */
+    client?: string;
+    /** The JSON request body, credentials redacted. */
+    requestBody?: unknown;
+    requestBodyNote?: string;
+    /** A failed request's own sentence from the server, verbatim. */
+    errorSentence?: string;
+    timestamp: number;
+}
+interface LiveCapture {
+    /** The declared surface these are live values of. Absent/null = the page declares no surface yet. */
+    surfaceName?: string | null;
+    kind: LiveCaptureKind;
+    title: string;
+    route: string;
+    url?: string;
+    /** What this page is OF (table, record, dialog subject …), names and ids. */
+    identity: Record<string, LiveCaptureValue>;
+    /** The exact choices the person made on the page, in order. */
+    selection: Record<string, LiveCaptureValue>;
+    sections: LiveSection[];
+    /** The error sentences on screen, verbatim. */
+    errors: string[];
+    requests: LiveRequest[];
+}
+interface LiveContribution {
+    owner: string;
+    sections: LiveSection[];
+    /** Names a descendant knows and the page does not. */
+    identity?: Record<string, LiveCaptureValue>;
+}
+/** What a reader shows before anyone uses the capture: no section value is walked. */
+interface LiveOutline {
+    surfaceName: string | null;
+    kind: LiveCaptureKind;
+    title: string;
+    loadable: Array<Pick<LiveSection, "id" | "title">>;
+}
+/**
+ * The page's capture plus its descendants' contributions. A descendant fills a name the page left
+ * empty and never overrides one; a section id claimed twice throws, naming both owners.
+ */
+declare function mergeLiveCapture(base: LiveCapture, contributions: readonly LiveContribution[]): LiveCapture;
+/** The four declared live slots (`LiveSlot`) as views of one capture. */
+declare function liveSlotsOf(capture: LiveCapture): LiveValues;
+/**
+ * One named live value of a capture, or `undefined` when the capture holds none by that name.
+ * Slot names (`selection`, `errors`, `requests`, `on-demand`) read the slot; `title`, `route`,
+ * `url`, `kind` and `identity` read the page; any other name reads an identity or selection entry,
+ * then a held section's value (a section that must be loaded answers its stub).
+ */
+declare function liveValueOf(capture: LiveCapture, name: string): unknown;
+interface LiveValuesStore {
+    /** A page's live capture, read at read time. Returns its unpublish. The most recent wins. */
+    publish(read: () => LiveCapture): () => void;
+    /** A descendant's sections (and names). Returns its removal. */
+    contribute(owner: string, read: () => LiveSection[] | Omit<LiveContribution, "owner">): () => void;
+    /** Say a getter's answer changed (readers re-render). */
+    touch(): void;
+    /** Whether any page is publishing right now. */
+    has(): boolean;
+    /** The live capture: the latest publication merged with every contribution. */
+    read(): LiveCapture | null;
+    /** The outline without building section values (safe in render). */
+    outline(): LiveOutline | null;
+    /** The live capture of ONE surface, when the publishing page is that surface. */
+    readFor(surfaceName: string): LiveCapture | null;
+    subscribe(listener: () => void): () => void;
+    /** Bumps on every publish / contribute / touch. */
+    version(): number;
+}
+declare function createLiveValues(): LiveValuesStore;
+/** THE live-values store of this JS realm: every host page publishes here, every reader reads here. */
+declare const liveValues: LiveValuesStore;
+
 /**
  * `createSurfacePort` — the one SurfacePort runtime (Applets CONTRACTS §6 + Amendment 2.1).
  *
@@ -1000,6 +1148,12 @@ interface CreateSurfacePortOptions {
      * `action_unhandled`, so a page Action can never wait for an answer that cannot come.
      */
     emit(stream: string, payload: unknown): boolean;
+    /**
+     * The page's live values (ALC-18): `getValue(name)` on a value nobody set reads the mounted
+     * surface's live capture (`liveValueOf`) — only while a page publishing THAT surface is mounted.
+     * Usually `liveValues` from `@ai-matrx/alchemy/surface`.
+     */
+    live?: LiveValuesStore;
     /** Values seeded at mount; a value already set is never overwritten. */
     seedValues?: () => Promise<Record<string, unknown>>;
     /** The surface to read when nothing is mounted yet (e.g. the Applet's own `applets/<id>`). */
@@ -1063,4 +1217,56 @@ interface SurfaceClient {
     };
 }
 
-export { APPLET_SURFACE_PREFIX, type ActionCaller, type ActionContext, type ActionInfo, type ActionResult, type CreateSurfacePortOptions, type MandateRunRef, PAGE_ACTION_STREAM, type PageActionEvent, type PendingPageActions, type ReadSurfaceChainOptions, type SurfaceClient, type SurfacePort, type SurfacePortHandle, type SurfacePortRunPorts, type SurfaceReadAnswer, type SurfaceReadChain, createSurfacePort, readSurfaceChain, surfaceActionVisible, valueStream };
+/**
+ * `@ai-matrx/alchemy/declare/host` — HOST-BINDING types only (CONTRACT §2.1, §2.6).
+ * Never imported by providers (`/declare`, `/actions`, `/menu`, `/operate` see only
+ * the raw-free `ResolvedItem`). Types only: no runtime code.
+ */
+
+/** Raw item reads: consumed only by projection and the write handler that owns the target. */
+interface InternalResolvedItem extends ResolvedItem {
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+}
+
+/**
+ * ITEM SOURCES — the one path from "the person pointed at this" to a declared item (ALC-18, D4).
+ *
+ * A mounted container (a canonical table, a message list) registers ONE source under its own id.
+ * When a menu opens on an anchor inside it, the host asks `itemSources.resolve(containerId, target)`
+ * and gets back the declared item — `itemType`, `identity`, `level`, `readOnly`, `readValues` — plus
+ * the opaque `host` data the container's owner attached (the menu rows it builds for that item). The
+ * package never reads `host`; it never crosses into a model.
+ *
+ * A container that answers an item type no surface declares is a defect the host's guard names;
+ * the canonical table answers `TABLE_ROW_ITEM_TYPE` (`@ai-matrx/alchemy/declare`), which every
+ * surface carries as a baseline.
+ */
+
+/** What was pointed at inside a container, in the container's own words. */
+interface ItemTarget {
+    containerId: string;
+    /** The level aimed at (a table: selection | cell | column | row | table). */
+    level: string;
+    /** The item's id within the container (a table's row id). */
+    itemId?: string;
+    /** A sub-part of the item (a table's column id). */
+    partId?: string;
+}
+/** A resolved item, plus the container owner's opaque data for it. */
+interface ItemHit<H = unknown> {
+    item: InternalResolvedItem;
+    host?: H;
+}
+type ItemSource<H = unknown> = (target: ItemTarget) => ItemHit<H> | null;
+interface ItemSourceRegistry {
+    /** One source per mounted container. A re-register replaces; the returned removal removes only its own. */
+    register<H>(containerId: string, source: ItemSource<H>): () => void;
+    /** The item at the target, or null when no container answers it. A throwing source answers null. */
+    resolve<H = unknown>(target: ItemTarget): ItemHit<H> | null;
+    has(containerId: string): boolean;
+}
+declare function createItemSources(onError?: (error: unknown, target: ItemTarget) => void): ItemSourceRegistry;
+/** THE item-source registry of this JS realm. */
+declare const itemSources: ItemSourceRegistry;
+
+export { APPLET_SURFACE_PREFIX, type ActionCaller, type ActionContext, type ActionInfo, type ActionResult, type CreateSurfacePortOptions, type ItemHit, type ItemSource, type ItemSourceRegistry, type ItemTarget, type LiveCapture, type LiveCaptureKind, type LiveCaptureValue, type LiveContribution, type LiveNamed, type LiveOutline, type LiveRequest, type LiveSection, type LiveValuesStore, type MandateRunRef, PAGE_ACTION_STREAM, type PageActionEvent, type PendingPageActions, type ReadSurfaceChainOptions, type SurfaceClient, type SurfacePort, type SurfacePortHandle, type SurfacePortRunPorts, type SurfaceReadAnswer, type SurfaceReadChain, createItemSources, createLiveValues, createSurfacePort, itemSources, liveSlotsOf, liveValueOf, liveValues, mergeLiveCapture, readSurfaceChain, surfaceActionVisible, valueStream };

package/dist/surface.d.ts

@@ -1,3 +1,5 @@
+import { Json as Json$2 } from '@ai-matrx/kit/transfer-json';
+
 /**
  * Matrx Alchemy — Declare types (CONTRACT §2.1).
  *
@@ -5,8 +7,8 @@
  * no React. Runtime behaviour lives in `MountedSurface` (`/declare/host`) and in
  * handler registrations, never here. Zero React, zero `@ai-matrx/agents`.
  */
-type Json$2 = null | boolean | number | string | Json$2[] | {
-    [key: string]: Json$2;
+type Json$1 = null | boolean | number | string | Json$1[] | {
+    [key: string]: Json$1;
 };
 /** Unchanged from `ui_surface_value_type_chk`. */
 type ValueType = "string" | "number" | "boolean" | "object" | "array" | "document";
@@ -136,6 +138,8 @@ interface SurfaceDeclaration {
     configNamespaces?: readonly ConfigNamespaceDeclaration[];
     evidenceSources?: readonly EvidenceSourceDeclaration[];
     skipBaselineValues?: boolean;
+    /** Opt out of the host's baseline item types (`baselineItemTypes`, e.g. `TABLE_ROW_ITEM_TYPE`). */
+    skipBaselineItemTypes?: boolean;
 }
 type ValueProvenance = {
     kind: "own";
@@ -161,6 +165,37 @@ interface ResolvedSurfaceDeclaration extends SurfaceDeclaration {
  * The qualified key "<itemType>.<name>" names an item value; a bare name is a screen value.
  */
 type QualifiedValueKey = string;
+/** Live slot payloads (page-capture's shapes, kept). */
+interface LiveValues {
+    selection?: {
+        choices: Record<string, Json$1>;
+        text: string | null;
+    };
+    "on-demand"?: readonly OnDemandSection[];
+    errors?: readonly string[];
+    requests?: readonly RecentRequest[];
+}
+interface OnDemandSection {
+    id: string;
+    title: string;
+    description?: string;
+    role: "data" | "request";
+    brief?: Json$1;
+    load(signal: AbortSignal): Promise<Json$1>;
+}
+interface RecentRequest {
+    method: string;
+    path: string;
+    status: string;
+    httpStatus?: number;
+    durationMs?: number;
+    requestId?: string;
+    client?: string;
+    requestBody?: Json$1;
+    requestBodyNote?: string;
+    errorSentence?: string;
+    timestamp: number;
+}
 /** RAW-FREE. What leaves the package about a clicked item. */
 interface ResolvedItem {
     itemType: string;
@@ -254,7 +289,7 @@ type ActionResult<T = unknown> = {
 /** `POST /actions/run` (aidream) — the request. */
 interface ServerActionRunRequest {
     name: string;
-    input: Json$2;
+    input: Json$1;
     by: ActionCaller;
     surface_name?: string;
     policy?: ActionPolicy;
@@ -263,8 +298,8 @@ interface ServerActionRunRequest {
 interface ServerActionRunResponse {
     status: "applied" | "proposed" | "refused";
     message: string;
-    receipts: Json$2[];
-    proposal?: Json$2;
+    receipts: Json$1[];
+    proposal?: Json$1;
 }
 /** A mandate run request: by alias (an Action's `target`) or by key. */
 type MandateRunRequest = ({
@@ -274,7 +309,7 @@ type MandateRunRequest = ({
     key: string;
     alias?: never;
 }) & {
-    variables: Record<string, Json$2>;
+    variables: Record<string, Json$1>;
     userInput?: string;
     by: ActionCaller;
     policy: ActionPolicy;
@@ -402,14 +437,6 @@ interface ClickTarget {
     host?: unknown;
 }
 
-/**
- * Framework-neutral transfer contracts (Alchemy Operate, CONTRACT §2.3). All data crossing this boundary is JSON.
- * Moved from `@ai-matrx/kit/content-transfer` in ALC-16; the format-adapter contract lives in `./contract`.
- */
-type Json$1 = null | boolean | number | string | Json$1[] | {
-    [key: string]: Json$1;
-};
-
 /**
  * Operate — the format and delivery contract (Matrx Alchemy CONTRACT §2.3, ALC-16).
  *
@@ -439,7 +466,7 @@ type Receipt = {
     sentence: string;
     warning?: string;
     fix?: string; /** What the handler produced (e.g. the created record). */
-    result?: Json$1;
+    result?: Json$2;
 } | {
     status: "queued";
     to: WriteTargetRef;
@@ -944,6 +971,127 @@ interface ServerPort {
 
 type SurfaceActionPorts = Pick<AlchemyHostPorts, "diagnostics" | "serverActions" | "mandates" | "pageActions" | "overlay" | "approvals" | "door">;
 
+/**
+ * LIVE VALUES — what a mounted page holds right now (ALC-18, LIST.md D3).
+ *
+ * A page publishes ONE live capture while it is mounted: its title and route, what it is OF
+ * (`identity`), the exact choices the person made (`selection`), its data sections, the errors on
+ * screen and its recent requests. Descendants that hold state the page does not (a grid's rows, a
+ * compare view) contribute sections. Every reader — the page's Alchemy menu, the admin debug
+ * context, an agent through `SurfacePort.getValue` — reads the SAME capture through this store, at
+ * read time, from the live getters. There is no second capture path.
+ *
+ * The four declared live slots (`LiveSlot`: selection, on-demand, errors, requests) are views of
+ * the capture (`liveSlotsOf`), and a surface's named value reads through `liveValueOf`.
+ *
+ * Framework-neutral: no React, no DOM. A host hook subscribes with `subscribe` + `version`
+ * (`useSyncExternalStore`). The most recent publication wins (a dialog over a page, a page over
+ * the shell's default).
+ */
+
+type LiveCaptureKind = "table-page" | "record" | "dialog" | "admin-page";
+/** A chosen thing, by name and id. Either may be null (not chosen / not loaded). */
+interface LiveNamed {
+    id: string | null;
+    name: string | null;
+}
+type LiveCaptureValue = LiveNamed | string | number | boolean | null;
+interface LiveSection {
+    /** Stable id, unique within one capture. */
+    id: string;
+    /** What the person calls this part of the page. */
+    title: string;
+    description?: string;
+    /** `data` survives "Only the data"; `request` does not. */
+    role: "data" | "request";
+    value: unknown;
+    /** The one-line brief (counts, a sentence). */
+    brief?: unknown;
+    /** A section too big to hold on the page: `value` is the honest stub and `load` reads it on use. */
+    load?: () => Promise<unknown>;
+}
+interface LiveRequest {
+    method: string;
+    path: string;
+    status: string;
+    httpStatus?: number;
+    durationMs?: number;
+    requestId?: string;
+    /** Which client door (supabase-rest, supabase-rpc, aidream, next-api …). */
+    client?: string;
+    /** The JSON request body, credentials redacted. */
+    requestBody?: unknown;
+    requestBodyNote?: string;
+    /** A failed request's own sentence from the server, verbatim. */
+    errorSentence?: string;
+    timestamp: number;
+}
+interface LiveCapture {
+    /** The declared surface these are live values of. Absent/null = the page declares no surface yet. */
+    surfaceName?: string | null;
+    kind: LiveCaptureKind;
+    title: string;
+    route: string;
+    url?: string;
+    /** What this page is OF (table, record, dialog subject …), names and ids. */
+    identity: Record<string, LiveCaptureValue>;
+    /** The exact choices the person made on the page, in order. */
+    selection: Record<string, LiveCaptureValue>;
+    sections: LiveSection[];
+    /** The error sentences on screen, verbatim. */
+    errors: string[];
+    requests: LiveRequest[];
+}
+interface LiveContribution {
+    owner: string;
+    sections: LiveSection[];
+    /** Names a descendant knows and the page does not. */
+    identity?: Record<string, LiveCaptureValue>;
+}
+/** What a reader shows before anyone uses the capture: no section value is walked. */
+interface LiveOutline {
+    surfaceName: string | null;
+    kind: LiveCaptureKind;
+    title: string;
+    loadable: Array<Pick<LiveSection, "id" | "title">>;
+}
+/**
+ * The page's capture plus its descendants' contributions. A descendant fills a name the page left
+ * empty and never overrides one; a section id claimed twice throws, naming both owners.
+ */
+declare function mergeLiveCapture(base: LiveCapture, contributions: readonly LiveContribution[]): LiveCapture;
+/** The four declared live slots (`LiveSlot`) as views of one capture. */
+declare function liveSlotsOf(capture: LiveCapture): LiveValues;
+/**
+ * One named live value of a capture, or `undefined` when the capture holds none by that name.
+ * Slot names (`selection`, `errors`, `requests`, `on-demand`) read the slot; `title`, `route`,
+ * `url`, `kind` and `identity` read the page; any other name reads an identity or selection entry,
+ * then a held section's value (a section that must be loaded answers its stub).
+ */
+declare function liveValueOf(capture: LiveCapture, name: string): unknown;
+interface LiveValuesStore {
+    /** A page's live capture, read at read time. Returns its unpublish. The most recent wins. */
+    publish(read: () => LiveCapture): () => void;
+    /** A descendant's sections (and names). Returns its removal. */
+    contribute(owner: string, read: () => LiveSection[] | Omit<LiveContribution, "owner">): () => void;
+    /** Say a getter's answer changed (readers re-render). */
+    touch(): void;
+    /** Whether any page is publishing right now. */
+    has(): boolean;
+    /** The live capture: the latest publication merged with every contribution. */
+    read(): LiveCapture | null;
+    /** The outline without building section values (safe in render). */
+    outline(): LiveOutline | null;
+    /** The live capture of ONE surface, when the publishing page is that surface. */
+    readFor(surfaceName: string): LiveCapture | null;
+    subscribe(listener: () => void): () => void;
+    /** Bumps on every publish / contribute / touch. */
+    version(): number;
+}
+declare function createLiveValues(): LiveValuesStore;
+/** THE live-values store of this JS realm: every host page publishes here, every reader reads here. */
+declare const liveValues: LiveValuesStore;
+
 /**
  * `createSurfacePort` — the one SurfacePort runtime (Applets CONTRACTS §6 + Amendment 2.1).
  *
@@ -1000,6 +1148,12 @@ interface CreateSurfacePortOptions {
      * `action_unhandled`, so a page Action can never wait for an answer that cannot come.
      */
     emit(stream: string, payload: unknown): boolean;
+    /**
+     * The page's live values (ALC-18): `getValue(name)` on a value nobody set reads the mounted
+     * surface's live capture (`liveValueOf`) — only while a page publishing THAT surface is mounted.
+     * Usually `liveValues` from `@ai-matrx/alchemy/surface`.
+     */
+    live?: LiveValuesStore;
     /** Values seeded at mount; a value already set is never overwritten. */
     seedValues?: () => Promise<Record<string, unknown>>;
     /** The surface to read when nothing is mounted yet (e.g. the Applet's own `applets/<id>`). */
@@ -1063,4 +1217,56 @@ interface SurfaceClient {
     };
 }
 
-export { APPLET_SURFACE_PREFIX, type ActionCaller, type ActionContext, type ActionInfo, type ActionResult, type CreateSurfacePortOptions, type MandateRunRef, PAGE_ACTION_STREAM, type PageActionEvent, type PendingPageActions, type ReadSurfaceChainOptions, type SurfaceClient, type SurfacePort, type SurfacePortHandle, type SurfacePortRunPorts, type SurfaceReadAnswer, type SurfaceReadChain, createSurfacePort, readSurfaceChain, surfaceActionVisible, valueStream };
+/**
+ * `@ai-matrx/alchemy/declare/host` — HOST-BINDING types only (CONTRACT §2.1, §2.6).
+ * Never imported by providers (`/declare`, `/actions`, `/menu`, `/operate` see only
+ * the raw-free `ResolvedItem`). Types only: no runtime code.
+ */
+
+/** Raw item reads: consumed only by projection and the write handler that owns the target. */
+interface InternalResolvedItem extends ResolvedItem {
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+}
+
+/**
+ * ITEM SOURCES — the one path from "the person pointed at this" to a declared item (ALC-18, D4).
+ *
+ * A mounted container (a canonical table, a message list) registers ONE source under its own id.
+ * When a menu opens on an anchor inside it, the host asks `itemSources.resolve(containerId, target)`
+ * and gets back the declared item — `itemType`, `identity`, `level`, `readOnly`, `readValues` — plus
+ * the opaque `host` data the container's owner attached (the menu rows it builds for that item). The
+ * package never reads `host`; it never crosses into a model.
+ *
+ * A container that answers an item type no surface declares is a defect the host's guard names;
+ * the canonical table answers `TABLE_ROW_ITEM_TYPE` (`@ai-matrx/alchemy/declare`), which every
+ * surface carries as a baseline.
+ */
+
+/** What was pointed at inside a container, in the container's own words. */
+interface ItemTarget {
+    containerId: string;
+    /** The level aimed at (a table: selection | cell | column | row | table). */
+    level: string;
+    /** The item's id within the container (a table's row id). */
+    itemId?: string;
+    /** A sub-part of the item (a table's column id). */
+    partId?: string;
+}
+/** A resolved item, plus the container owner's opaque data for it. */
+interface ItemHit<H = unknown> {
+    item: InternalResolvedItem;
+    host?: H;
+}
+type ItemSource<H = unknown> = (target: ItemTarget) => ItemHit<H> | null;
+interface ItemSourceRegistry {
+    /** One source per mounted container. A re-register replaces; the returned removal removes only its own. */
+    register<H>(containerId: string, source: ItemSource<H>): () => void;
+    /** The item at the target, or null when no container answers it. A throwing source answers null. */
+    resolve<H = unknown>(target: ItemTarget): ItemHit<H> | null;
+    has(containerId: string): boolean;
+}
+declare function createItemSources(onError?: (error: unknown, target: ItemTarget) => void): ItemSourceRegistry;
+/** THE item-source registry of this JS realm. */
+declare const itemSources: ItemSourceRegistry;
+
+export { APPLET_SURFACE_PREFIX, type ActionCaller, type ActionContext, type ActionInfo, type ActionResult, type CreateSurfacePortOptions, type ItemHit, type ItemSource, type ItemSourceRegistry, type ItemTarget, type LiveCapture, type LiveCaptureKind, type LiveCaptureValue, type LiveContribution, type LiveNamed, type LiveOutline, type LiveRequest, type LiveSection, type LiveValuesStore, type MandateRunRef, PAGE_ACTION_STREAM, type PageActionEvent, type PendingPageActions, type ReadSurfaceChainOptions, type SurfaceClient, type SurfacePort, type SurfacePortHandle, type SurfacePortRunPorts, type SurfaceReadAnswer, type SurfaceReadChain, createItemSources, createLiveValues, createSurfacePort, itemSources, liveSlotsOf, liveValueOf, liveValues, mergeLiveCapture, readSurfaceChain, surfaceActionVisible, valueStream };