@ai-matrx/chat 0.1.74 → 0.2.0

package/dist/surfaces/types.d.ts

@@ -0,0 +1,961 @@
+/**
+ * Surface Values System — public TypeScript surface.
+ *
+ * A `SurfaceValue` is a named runtime value a UI surface declares it can
+ * supply at execution time. Surfaces register a `SurfaceManifest` in code;
+ * the registry is mirrored into `ui.ui_surface_value` so binding UIs
+ * (agent mapping editors, tool mapping editors, audit views) can pick from
+ * the same list the runtime actually emits.
+ *
+ * The `ValueMapping` discriminated union is the JSONB shape stored in
+ * agent↔surface binding value_mappings (platform.associations edge metadata). A single resolver consumes it for
+ * agent variables and agent context policies.
+ *
+ * See:
+ *   - `features/surfaces/manifests/registry.ts`   (the registry)
+ *   - `features/surfaces/utils/value-mapping-resolver.ts` (the resolver)
+ *   - `features/surfaces/services/manifest-sync.service.ts` (drift + sync)
+ */
+import type { DeclaredValue, ExecutionMode, Sensitivity, SurfaceDeclaration, ValueGroup, ValueType } from "@ai-matrx/alchemy/declare";
+import type { SurfaceExecutorName } from "./executor.js";
+import type { ApplicationScope } from "../agents/types/scope.types.js";
+import type { AnyMandateKey } from "@ai-matrx/agents/mandates";
+import type { components } from "@ai-matrx/agents/generated/api-types";
+/** Logical type of a surface value. Most are stringified for LLMs at runtime. */
+export type SurfaceValueType = ValueType;
+/**
+ * A canonical, surface-authored group of values ("SEO Signals", "Captures").
+ * Groups are the ONLY sanctioned way to organize values — no UI may invent its
+ * own sections. Curated groups author sortOrder 0–899; the registry reserves
+ * `general` (850), `inherited:<parent>` (9000+), and `baseline` (9900), which
+ * manifests may NOT declare. Mirrored to `ui_surface.value_groups` (JSONB) and
+ * per value to `ui_surface_value.group_key`.
+ */
+export interface SurfaceValueGroup extends ValueGroup {
+    /** lower_snake_case, unique within the surface (e.g. `seo_signals`). */
+    key: string;
+    /** The ONE canonical human label for this group. */
+    label: string;
+    /** Display/curation order. Author band 0–899. */
+    sortOrder: number;
+    description?: string;
+}
+/** Reserved group keys synthesized by the registry — undeclarable in manifests. */
+export declare const RESERVED_GROUP_KEYS: {
+    readonly general: "general";
+    readonly baseline: "baseline";
+    readonly inheritedPrefix: "inherited:";
+};
+/** How sensitive a value is (`@ai-matrx/alchemy/declare` `Sensitivity`; every field defaults). */
+export type SurfaceValueSensitivity = Partial<Sensitivity>;
+/** `ui.ui_surface.execution_mode` (ui_surface_execution_mode_check). */
+export type SurfaceExecutionMode = ExecutionMode;
+export interface SurfaceValue extends DeclaredValue {
+    /**
+     * Lower-snake-case key, unique within the surface (e.g. `selection`,
+     * `current_file`, `open_tabs`). Becomes the key in `ApplicationScope`.
+     */
+    name: string;
+    /** Short human label for binding UIs (e.g. "Current selection"). */
+    label: string;
+    /** When this value is populated and what it represents. 1-2 sentences. */
+    description: string;
+    /** Logical type; mostly stringified for LLMs but drives binding UI affordances. */
+    valueType: SurfaceValueType;
+    /**
+     * True when the surface guarantees a value every time it launches an
+     * execution. False for things like `selection` that are commonly undefined.
+     */
+    alwaysAvailable: boolean;
+    /**
+     * Rough average char count after stringification. Used by mapping UIs to
+     * warn when binding to a value that could blow LLM context windows (e.g.
+     * "all open tabs", "full file contents").
+     */
+    typicalCharCount: number;
+    /**
+     * Whether this value is AUTOMATICALLY added to the agent's context when the
+     * surface emits it at launch (true, the default), or only available for
+     * explicit variable/context-policy mapping (false). The point of `false` is
+     * signal-to-noise: a surface can declare 25 values so binding UIs offer
+     * them, while auto-context stays limited to what an agent on this surface
+     * genuinely needs (an id, the content, the cursor) — everything else is
+     * "look it up if you need it". Mirrored to `ui_surface_value.auto_context`.
+     */
+    autoContext?: boolean;
+    /**
+     * Sent on EVERY run from this surface, including a shortcut or binding
+     * launch that maps only its own inputs (which otherwise receives nothing
+     * it did not map — `mapScopeToInstanceWithSurface`, W-31). Default false.
+     * Reserve it for small facts no agent on this surface may run without;
+     * never a body, a selection, or a bundle. Code-only (not mirrored).
+     */
+    alwaysOn?: boolean;
+    /**
+     * Alchemy sensitivity (CONTRACT 2.1 `Sensitivity`). Every field defaults:
+     * exportable true, classification "ordinary", includedByDefault true.
+     */
+    sensitivity?: SurfaceValueSensitivity;
+    /** Optional sort order within the surface; defaults to 1000 in DB. */
+    sortOrder?: number;
+    /**
+     * Key of the `SurfaceValueGroup` this value belongs to. Must reference a key
+     * declared in the manifest's `groups`. Omitted = the implicit `general`
+     * group. Never set to a reserved key (`general`, `baseline`, `inherited:*`).
+     * Mirrored to `ui_surface_value.group_key`.
+     */
+    group?: string;
+    /**
+     * Show this value to the agent up front, up to N chars, instead of as a
+     * "look it up" item. Sent on the rich context envelope's `max_inline_chars`
+     * (the server shows the first N chars; the rest is one paged lookup away).
+     * Omit = the platform default (200), right for almost every value.
+     *
+     * THE CONTEXT BUDGET (Arman, 2026-09-27): give the agent what the page's
+     * likely jobs need up front — a lookup for data we could have sent costs
+     * more than sending it — and nothing it can't use. The worker judges each
+     * number; the sum over the surface's values may not exceed
+     * `PAGE_CONTEXT_BUDGET` (the declaration check refuses it without the
+     * manifest's `contextBudgetApproval`):
+     *  - a focused page (one record, little else): the record up to ~10,000;
+     *  - a record with companions (its comments, folders, notes): the record
+     *    ~7,000 and the companions share the rest;
+     *  - a list page: the condensed visible list (3-6 key fields, the person's
+     *    sort/filter, first ~25 rows) ~4,000;
+     *  - a broad page covering many unrelated things (SEO, dashboards): a
+     *    compact overview bundle (~2,000-3,000) and nothing else inline; the
+     *    agent discovers the rest with lookups and the page's guide.
+     * Put the inlined content in one well-prepared bundle (see
+     * `runtime/context-bundle.ts`) so the core costs the fewest tokens.
+     */
+    inlineUpTo?: number;
+}
+/**
+ * The most a surface may show an agent up front, summed over its values'
+ * `inlineUpTo` (chars). See `SurfaceValue.inlineUpTo`.
+ */
+export declare const PAGE_CONTEXT_BUDGET = 10000;
+/** Where a resolved value came from. Preserved through registry resolution. */
+export type SurfaceValueProvenance = {
+    kind: "own";
+} | {
+    kind: "inherited";
+    from: string;
+} | {
+    kind: "baseline";
+};
+export interface ResolvedSurfaceValue extends SurfaceValue {
+    provenance: SurfaceValueProvenance;
+    /** Always populated after resolution: curated key, `general`, `inherited:<parent>`, or `baseline`. */
+    groupKey: string;
+}
+export interface ResolvedSurfaceManifest extends SurfaceManifest {
+    values: readonly ResolvedSurfaceValue[];
+    /**
+     * Curated groups + synthesized auto groups (`general`, `inherited:<parent>`,
+     * `baseline`), sorted by sortOrder — curated first, inherited next,
+     * baselines last, by construction.
+     */
+    groups: readonly SurfaceValueGroup[];
+}
+/**
+ * Declared in manifests, mirrored to `ui.ui_surface_agent_role` by
+ * manifest sync (same lifecycle as SurfaceValue). A role is somewhere the
+ * surface PLUGS IN an agent: cleanup's `clean` + `custom_slot`, scribe's
+ * `assistant`. The manifest's `defaultAgentId` is the platform default;
+ * users/orgs override via `ui_surface_agent_pref` rows (selection per role,
+ * resolved global → org-by-membership → user).
+ */
+export interface SurfaceAgentRole {
+    /** lower_snake_case, unique per surface (e.g. `clean`, `custom_slot`). */
+    name: string;
+    label: string;
+    description: string;
+    /** `single` = one agent fills it; `multi` = ordered positions (slots). */
+    kind: "single" | "multi";
+    /** Platform default agent id (system-owned UUID). Null = starts empty. */
+    defaultAgentId: string | null;
+    /**
+     * Agent-mandate key (`agent.mandate.mandate_key`) supplying the role's
+     * platform default INSTEAD of `defaultAgentId` — code names the Mandate,
+     * the DB decides the Holder (the NO HARDCODED AGENTS law applied to
+     * surface roles). Mutually exclusive with a non-null `defaultAgentId`
+     * (drift check enforces). A mandate key not yet seeded resolves to an
+     * unfilled role with a loud console error — never a silent fallback —
+     * and binds automatically once the `agent.mandate` row lands.
+     */
+    mandateKey?: AnyMandateKey | null;
+    /** kind="multi" only — max concurrent positions. Defaults to 1. */
+    maxAgents?: number;
+    /** User may slot ANY agent (true, default) vs roster/system agents only. */
+    allowCustom?: boolean;
+    /** Auto-run semantics for agents in this role. Default "user-choice". */
+    autoRun?: "always" | "never" | "user-choice";
+    sortOrder?: number;
+}
+/**
+ * A role AS A MANIFEST DECLARES IT. 🚨 A surface manifest never names an agent
+ * id (Arman, 2026-09-25: nothing works around the mandate system). The role's
+ * platform default is a MANDATE (`mandateKey`) — manifest sync writes the key
+ * to `ui_surface_agent_role.mandate_key` and `resolveSurfaceConfig` resolves
+ * its current Holder, so a rebinding in the mandate console rebinds the role.
+ * `defaultAgentId` is therefore typed `null` here: a raw id in a manifest is a
+ * TYPE ERROR, not a review comment. (Before this, 17 roles carried raw ids that
+ * sync copied into `default_agent_id`, which OUTRANKS the mandate tier in
+ * `resolveSurfaceConfig` — the mandate console could never rebind them.)
+ * Need a new default? Declare a mandate in aidream seeded with that agent.
+ * `scripts/check-hardcoded-agents.ts` enforces the same rule for any id that
+ * reaches a manifest by other means (an imported constant, a cast).
+ */
+export type ManifestAgentRole = Omit<SurfaceAgentRole, "defaultAgentId"> & {
+    defaultAgentId: null;
+};
+/**
+ * A config namespace the surface consumes from `ui.ui_surface_config`
+ * (dictionary, session_defaults, …). Code-only declaration — the handler
+ * (validate/merge/empty) is registered in
+ * `features/surfaces/config/namespace-registry.ts`.
+ */
+export interface SurfaceConfigNamespaceDecl {
+    /** Must exist in the namespace registry. */
+    namespace: string;
+    label: string;
+    description: string;
+}
+/**
+ * A processed-document pointer the surface guarantees it can derive from its
+ * runtime values. The universal launcher turns this declaration into a lazy
+ * `request.context` source before agent-variable mappings run, so document
+ * tools/context do not depend on an agent author manually mapping an id.
+ */
+export interface SurfaceProcessedDocumentEvidenceSource {
+    kind: "processed_document";
+    /** Surface value containing `docproc.processed_documents.id`. */
+    idValue: string;
+    /** Optional surface value containing the originating `files.files.id`. */
+    fileIdValue?: string;
+    /** Optional surface value used as the agent-facing document label. */
+    labelValue?: string;
+    /** Preferred primary text representation; omitted means clean-when-ready. */
+    representation?: "clean" | "raw";
+}
+export type SurfaceEvidenceSource = SurfaceProcessedDocumentEvidenceSource;
+/**
+ * A named field/state the surface declares agents (and agent-result
+ * components) may WRITE into — the write half of the manifest, beside the
+ * read-only `values`. Declared in code and consumed by the surface-writeback
+ * runtime (`features/surfaces/runtime/surface-writeback.ts`): the page
+ * registers a handler per target on its `SurfaceRuntimeProvider`, and any
+ * caller (a kind-component action button, an automated envelope apply) goes
+ * through `applySurfaceWrite(target, value)` — never a bespoke callback.
+ *
+ * Code-only in v1 (like `evidenceSources`): not yet mirrored to the DB.
+ * Mirroring (so server-side agents can see what a surface accepts) is the
+ * planned follow-up once the client seam is proven.
+ */
+export interface SurfaceWriteTarget {
+    /** lower_snake_case, unique within the surface (same regex as values). */
+    name: string;
+    /** The ONE canonical human label ("Node brief"). THE NAMING LAW applies. */
+    label: string;
+    /**
+     * What applying this target DOES — where the value lands, what shape it
+     * must be, and whether the user still has to confirm/save. 1-3 sentences.
+     */
+    description: string;
+    /** Shape of the value a caller must pass. */
+    valueType: SurfaceValueType;
+    /**
+     * THE VALUE CONTRACT — the slug of a registered Kind
+     * (`content_ir.kind_definition`) whose schema describes the value this
+     * target accepts. Not a shape written here: the kind's
+     * `emitted_json_schema` IS the contract, and it is the SAME contract
+     * everywhere the value travels — on the wire (the `apply_surface_write`
+     * inline spec), at the seam (`applySurfaceWrite` validates through
+     * `kindValidator.validate` before approval and before the handler), and in
+     * the DB mirror (`ui.ui_surface_write_target.kind_key`, which aidream's
+     * resolver prints as `kind=<slug>`).
+     *
+     * THE RULE:
+     * - REQUIRED for a structured target (`valueType: "object" | "array"`).
+     *   A structured value with only prose to describe it is a contract an
+     *   agent can only guess at, and the handler's hand-rolled throw is the
+     *   only thing between a malformed value and the page. This is RATCHETED,
+     *   not retroactive: `pnpm check:surface-drift` prints the count of
+     *   structured targets still lacking one (advisory, loud) and ERRORS on
+     *   any target naming a kind the generated registry does not carry. New
+     *   structured targets declare one.
+     * - OPTIONAL for a primitive target (`string`/`number`/`boolean`/
+     *   `document`) — `valueType` already is the contract. Declare one anyway
+     *   when the primitive is constrained (an enum, a pattern, a bounded
+     *   number) and a kind captures that.
+     *
+     * NO INLINE JSON SCHEMAS. The One-Type Law puts kind payload shapes in
+     * `features/content-ir/kinds/generated/kinds.generated.ts` and nowhere
+     * else; a target NAMES a kind, it never re-declares one. Need a shape no
+     * kind carries? Register the kind (see the `shape-system` skill) and name
+     * it here.
+     */
+    valueKind?: string;
+    /**
+     * The declared SurfaceValue this target updates, when there is a 1:1 read
+     * twin — the evidence loop (read the value, write the target). Omit for
+     * pure-action targets with no read twin.
+     */
+    updatesValue?: string;
+    /**
+     * Client approval preview contract: the input replaces the exact text named
+     * by updatesValue (or `comparisonValue`). A string write into a string read
+     * twin is treated as a replacement BY DEFAULT — the person always sees a
+     * before → after, never just the agent's text — and a missing original then
+     * quietly falls back to the plain proposal. Declare `"text-replacement"` to
+     * make the original REQUIRED (a missing one refuses the write). Targets whose
+     * name starts with `append`/`insert` carry a fragment and are never compared.
+     * Code-owned; it does not change
+     * the provider tool schema or database apply policy.
+     */
+    approvalComparison?: "text-replacement";
+    /**
+     * The SurfaceValue holding the exact text this target replaces, when it is
+     * not the `updatesValue` read twin (e.g. the notes editor's twin is the
+     * `current_note` resource reference — an object — while the live editor text
+     * is `content`). Defaults to `updatesValue`.
+     */
+    comparisonValue?: string;
+    /**
+     * This target accepts an ANCHORED EDIT as well as a whole value.
+     *
+     * A patchable target still takes a plain string exactly as before —
+     * patchability only ADDS the option of sending
+     * `{command, old_str, new_str}` (the backend `ctx_patch` vocabulary, safe
+     * subset) instead of re-transmitting the entire text to change part of it.
+     * The patch is resolved against the CURRENT value at the seam
+     * (`resolveSurfaceWritePatch`), so the value contract, the approval card
+     * and the page's own handler all still see one finished string, and the
+     * handler needs no changes to gain this.
+     *
+     * Declare it on long free-text targets (a system prompt, a document body,
+     * a description someone actually writes paragraphs into). Pointless on a
+     * short field — re-sending a name costs nothing and an anchor into eight
+     * words is more fragile than the string it replaces.
+     *
+     * REQUIRES `updatesValue`: the patch is applied to the current text read
+     * from that declared SurfaceValue, and there is nothing to anchor against
+     * without it. A patchable target with no read twin is a manifest defect
+     * (`pnpm check:surface-drift` fails on it).
+     */
+    patchable?: boolean;
+    /**
+     * Where the write lands:
+     * - `"draft"`  — staged into the page's editor/draft state; the USER still
+     *   reviews and saves. The preferred default (additive, reversible).
+     * - `"entity"` — persisted immediately through the page's canonical write
+     *   path (service → DB). Reserve for writes that are safe to land directly.
+     * - `"ui"`     — ephemeral UI state only (selection, view focus); nothing
+     *   is persisted and nothing needs saving.
+     */
+    mode: "draft" | "entity" | "ui";
+    /**
+     * WHO SAVES A `"draft"` WRITE. `"user"` (the default) — it waits in the
+     * page's draft until the person presses Save. `"autosave"` — it lands in an
+     * editor that saves it by itself, exactly like the person's own typing
+     * (notes, documents, diagram source). The agent's tool result follows this,
+     * so it never tells the person "you still need to save" about a change the
+     * page already saved (bench 2026-10-01, note f1284c78-… reached v7 while the
+     * agent said it was unsaved). Ignored for `"entity"` / `"ui"`.
+     */
+    savedBy?: "user" | "autosave";
+    /**
+     * Who may apply this target WITHOUT a human in the loop.
+     *
+     * A user clicking a declared control is always allowed — the click IS the
+     * consent. This axis governs an AGENT-originated write (`origin: "agent"` on
+     * `applySurfaceWrite`), which is the direction that turns "agents can read
+     * the page" into "agents can change the page":
+     *
+     * - `"manual"` (DEFAULT, and deliberately so) — agent-originated writes are
+     *   REFUSED, loudly. The target exists for user-driven controls only. A new
+     *   target starts here: nothing becomes agent-writable by omission.
+     * - `"ask"` — the user is asked, in place, naming the target and what lands.
+     *   Decline is a normal outcome, not an error. This is the right setting for
+     *   almost everything that changes what the user sees.
+     * - `"auto"` — applied immediately. Justify it: appropriate for `ui` mode
+     *   (moving a selection is cheap and visible) and for `draft` mode where the
+     *   user still reviews before saving. An `entity` target on `"auto"` means an
+     *   agent silently writes the database — do not set that without a reason
+     *   written in `description`.
+     */
+    applyPolicy?: "manual" | "ask" | "auto";
+    /**
+     * Arman's recorded approval for a judgment call the rules don't allow on
+     * their own — today: `applyPolicy: "auto"` on a target whose mode is not
+     * `ui`. Format: "Arman <YYYY-MM-DD>: <why>". The declaration check refuses
+     * the call without it. (The approval system, Arman 2026-09-27.)
+     */
+    approval?: string;
+    /** Key of a declared SurfaceValueGroup (same rules as SurfaceValue.group). */
+    group?: string;
+    sortOrder?: number;
+}
+/**
+ * The wire contract for a surface client tool's arguments — the exact JSON
+ * Schema shape aidream's `InlineToolSpec.input_schema` accepts
+ * (`{type:"object", properties, required}`). Generated type, never widened.
+ */
+export type SurfaceClientToolInputSchema = components["schemas"]["CustomToolInputSchema"];
+/**
+ * A client-side tool this surface offers to agents bound to it — the ACTION
+ * half of the 360 loop, beside `writeTargets` (the data-write half). Declared
+ * in code; the page registers one handler per tool via `useSurfaceClientTools`
+ * (`runtime/SurfaceRuntimeContext.tsx`); execution lands through
+ * `executeSurfaceClientTool` (`runtime/surface-client-tools.ts`).
+ *
+ * At launch, every declared+mounted+handled tool is emitted on the request as
+ * a `ToolSpecInline` (`kind:"inline"` — the supported way to offer a
+ * client-delegated tool the server has no registry entry for), so the agent
+ * can call it; the `tool_delegated` event routes back to the page's handler.
+ *
+ * Mirrored to `ui.ui_surface_client_tool` by `manifest-sync.service.ts`, so
+ * server-side agents can see a surface's action vocabulary (the inline specs
+ * themselves are assembled on the client at launch). Code stays truth.
+ */
+export interface SurfaceClientTool {
+    /**
+     * lower_snake_case, unique within the surface (same regex as values). This
+     * is the model-facing tool name — it must also satisfy the server's tool
+     * name rule (`[a-zA-Z0-9_:-]{1,64}`). Prefix with the surface's domain
+     * (e.g. `content_plan_focus_node`) — the tool namespace is global per
+     * conversation, and a collision with a registered/widget tool name is
+     * silently skipped at injection time.
+     */
+    name: string;
+    /** The ONE canonical human label ("Focus node"). THE NAMING LAW applies. */
+    label: string;
+    /**
+     * What the AGENT is told — when to call it, what it does on the page, and
+     * what the result means. This is model-facing prose, not UI copy.
+     */
+    description: string;
+    /** JSON Schema for the tool's arguments — the wire contract. */
+    inputSchema: SurfaceClientToolInputSchema;
+    /**
+     * What calling it does to the page — same meanings as
+     * `SurfaceWriteTarget.mode`: `"ui"` (ephemeral view/selection state),
+     * `"draft"` (staged into editor state; the user still saves), `"entity"`
+     * (persisted immediately through the page's canonical write path).
+     * Omitted = `"ui"` is the safe reading.
+     */
+    mode?: SurfaceWriteTarget["mode"];
+}
+/**
+ * Where a surface stands on the road to "verified correct and complete".
+ * REQUIRED on every manifest — the platform's tracking of the canonicalization
+ * campaign. Mirrored to `ui_surface.readiness`; DB rows with no manifest are
+ * implicitly `unregistered` (never declared in code).
+ *
+ * - `verified` — full completeness audit done: every piece of page data
+ *   declared (fields + natural composites), groups curated, emitter wired and
+ *   live-checked. The end state.
+ * - `partial`  — real manifest + emitter exist but known gaps remain
+ *   (un-audited values, missing groups, or an incomplete emitter).
+ * - `stub`     — placeholder vocabulary; never audited against the page.
+ */
+export type SurfaceReadiness = "verified" | "partial" | "stub";
+/**
+ * A surface manifest IS an `@ai-matrx/alchemy/declare` `SurfaceDeclaration`
+ * plus the agent-owned extension slots (roster mode, roles, client tools),
+ * validated and synced through `features/surfaces/declare/surface-declare.ts`.
+ */
+export interface SurfaceManifest extends SurfaceDeclaration {
+    /** Matches `ui_surface.name`. */
+    surfaceName: string;
+    /**
+     * The client that owns the surface (`ui_surface.client_name`). Always the
+     * `surfaceName` prefix before the first `/`; the checks refuse a mismatch.
+     */
+    client: string;
+    /**
+     * REQUIRED — who runs this page's client-side tools (`ui_surface.executor_name`).
+     * Web-app pages name `MATRX_WEB_APP_EXECUTOR` (`../executor`). The sync
+     * writes it; registry init throws without it.
+     */
+    executor: SurfaceExecutorName;
+    /** `ui_surface.execution_mode`. Backfilled from the live row (ALC-14 S1). */
+    executionMode: SurfaceExecutionMode;
+    /** One sentence on what this surface is (`ui_surface.description`). */
+    description: string;
+    /**
+     * Whether this surface has a bindable roster of agents in the shell's
+     * existing Agents menu. `bound` is the default. `universal` is reserved for
+     * hosts such as Chat where the user may choose any agent: those surfaces
+     * expose no defaults, roles, binding controls, or surface-bound roster.
+     * Code-only; this is a chrome/binding safety boundary, not DB metadata.
+     */
+    agentRosterMode?: "bound" | "universal";
+    /**
+     * What this page's OWN conversation (the main chat, a builder's test run, a
+     * battle column…) never receives about itself — context keys withheld at the
+     * page layer, on top of the page's own values and the screens around it
+     * (common-docs context-delivery RULES.md §0). Default: the shared baseline
+     * `OWN_CONVERSATION_WITHHELD` (`_baseline.manifest.ts`), so every new
+     * conversation-host page inherits it. Person values (user, client,
+     * organization…) are never withheld, whatever is listed. A chat in a window
+     * or panel over the page is not its own conversation and keeps the page.
+     */
+    ownConversationWithholds?: readonly string[];
+    /**
+     * A COMPANION surface: a shell-level pane that sits BESIDE every page (the
+     * canvas column) and is never the page itself. It follows whichever
+     * conversation is beside it — including a page's OWN conversation (the main
+     * /chat), which otherwise receives no surface at all. That conversation gets
+     * the companion's values (as `surface_chain` levels) and its write targets
+     * and client tools, never the owning page's. (2026-10-03: the /chat main
+     * conversation could not read or edit the HTML page open in the canvas.)
+     */
+    companion?: boolean;
+    /**
+     * Every turn requires a mounted live provider to prepare request-specific
+     * evidence. Missing providers and send-while-running inbox delivery fail
+     * closed because neither can attach a fresh context snapshot.
+     */
+    requiresBeforeExecute?: boolean;
+    /**
+     * How an agent reaches the things this surface HOSTS that are not the live
+     * page (a Board's other tiles). One or two plain sentences. It rides in the
+     * injected `apply_surface_write` tool's description while this surface is
+     * mounted, and in the "declares no write target" refusal, so the model that
+     * reaches for a write on something it has not been handed is pointed at the
+     * host's own way in instead of guessing or searching.
+     */
+    otherItemsHint?: string;
+    /**
+     * What an agent is told when the ACTIVE surface is one item this surface
+     * HOSTS (a Board tile that is live). One compact sentence or two: it rides
+     * on the host's first value in the surface chain, right after the live
+     * item's own surface, so the request leads with the item AND with the list
+     * of everything else the host holds and how to reach it.
+     */
+    hostLead?: string;
+    /**
+     * What the person sees while this surface's `beforeExecute` works, shown on
+     * the outgoing message the instant Send is pressed (e.g. "Searching your
+     * study material"). Present tense, no trailing ellipsis. Defaults to
+     * "Preparing your message".
+     */
+    beforeExecuteLabel?: string;
+    /**
+     * Campaign tracking — REQUIRED. See `SurfaceReadiness`. Only flip to
+     * `verified` after the surface-authoring checklist passes end-to-end.
+     */
+    readiness: SurfaceReadiness;
+    /** One line on what is missing (required when readiness != "verified"). */
+    readinessNote?: string;
+    /**
+     * For OVERLAY/WINDOW surfaces (no route of their own): the overlay id from
+     * `features/overlays/catalogue.ts` this surface belongs to.
+     * Identifies the surface's home unambiguously (the overlay twin of
+     * `urlPattern`). Mirrored to `ui_surface.overlay_id`.
+     */
+    overlayId?: string;
+    /**
+     * The ONE canonical human display name for this surface (e.g.
+     * "PDF Extractor"). REQUIRED — this exact string is used byte-identically
+     * everywhere (chrome, windows, admin, binding UIs); free-text overrides are
+     * prohibited. Mirrored to `ui_surface.label` by manifest sync. Derive via
+     * `getSurfaceDisplayLabel` in `features/surfaces/utils/surface-display.ts`.
+     */
+    label: string;
+    /**
+     * Canonical route for this surface (e.g. `/notes`, `/agents/builder`,
+     * `/transcripts/scribe/:sessionId`). Mirrored to `ui_surface.url_pattern`
+     * by manifest sync. When omitted, sync derives a default from the route
+     * map or a simple client/local heuristic.
+     */
+    urlPattern?: string;
+    /**
+     * Parent surface this one inherits from (surface inheritance v1). The child
+     * inherits the parent's values, agent roles, config namespaces, AND agent
+     * bindings (parent binding layers apply weakest — child wins per key in the
+     * launch-time merge). Must name a registered manifest; cycles and chains
+     * deeper than the registry's depth cap throw loudly at registry init.
+     * Mirrored to `ui_surface.parent_surface_name` by manifest sync.
+     */
+    inheritsFrom?: string;
+    /**
+     * The surface's self-introduction to the agent — a single XML-ish context
+     * block (`<surface_intro>…`) explaining what this surface IS, what the user
+     * does here, and how to interpret the values it emits. Written by the
+     * manifest author who understands the surface's purpose; becomes the first
+     * surface-context item the agent sees. Mirrored to `ui_surface.intro`.
+     */
+    intro?: string;
+    /**
+     * Repo-relative path to this surface's runtime GUIDE — a markdown file that
+     * tells an in-app agent how to work on the page: what each value means,
+     * which write target does what (with example values), the rules and the
+     * pitfalls. Convention: `features/surfaces/guides/<slug>.md`, where the slug
+     * is the part of `surfaceName` after the `/`. Manifest sync upserts it as the
+     * platform skill `surface-guide-<slug>` (loadable with the agent `skill`
+     * tool) and appends a pointer to it to the stored `ui_surface.intro`, so the
+     * authored `intro` stays clean. See `utils/surface-guide.ts`.
+     */
+    guide?: string;
+    /**
+     * Arman's recorded approval for a surface whose values' `inlineUpTo` sum
+     * above `PAGE_CONTEXT_BUDGET`: "Arman <YYYY-MM-DD>: <why>". The declaration
+     * check refuses the excess without it.
+     */
+    contextBudgetApproval?: string;
+    /** Flat list of SurfaceValues this surface declares. */
+    values: readonly SurfaceValue[];
+    /**
+     * Canonical value groups this surface curates. Every `SurfaceValue.group`
+     * must reference one of these keys. Reserved keys (`general`, `baseline`,
+     * `inherited:*`) are synthesized by the registry and may not be declared.
+     * Mirrored to `ui_surface.value_groups` by manifest sync.
+     */
+    groups?: readonly SurfaceValueGroup[];
+    /** Agent positions this surface uses. Mirrored to ui_surface_agent_role. */
+    agentRoles?: readonly ManifestAgentRole[];
+    /** Config namespaces this surface consumes (code-only declaration). */
+    configNamespaces?: readonly SurfaceConfigNamespaceDecl[];
+    /**
+     * Declarative inputs to the Document Evidence System. These are launch
+     * contracts, not bindable values and therefore are not mirrored to the DB.
+     * They inherit with the rest of the surface manifest.
+     */
+    evidenceSources?: readonly SurfaceEvidenceSource[];
+    /**
+     * The WRITE half of the surface (read/write manifests v1): named targets
+     * agent results and kind-component actions may write into via the
+     * surface-writeback runtime. Code-only for now (not mirrored to the DB).
+     * A declared target with no registered runtime handler fails LOUDLY at
+     * apply time — never silently.
+     */
+    writeTargets?: readonly SurfaceWriteTarget[];
+    /**
+     * Client-side TOOLS this surface offers to bound agents (the action half of
+     * the 360 loop). Declared+mounted+handled tools are injected as inline
+     * specs at launch and executed on the page via the surface client-tool
+     * runtime (`runtime/surface-client-tools.ts`). A declared tool with no
+     * registered handler is NOT offered to the agent (and a delegated call to
+     * one fails LOUDLY) — never silently. Mirrored to
+     * `ui.ui_surface_client_tool`; a row there means DECLARED, not live.
+     *
+     * Tool names are GLOBAL per conversation, not per surface —
+     * `check:surface-drift` enforces cross-surface uniqueness, because a
+     * collision with an already-present spec is silently skipped at injection.
+     */
+    clientTools?: readonly SurfaceClientTool[];
+    /**
+     * THE BRIEF — the few declared values (at most `SURFACE_BRIEF_MAX_VALUES`,
+     * in this order) that say WHICH record this is and its state at a glance:
+     * a note's title, word count and first line; a task's status and due date.
+     * A host listing many copies of surfaces (the board's item list) shows each
+     * one's brief so an agent knows what every item is before it opens one
+     * (`runtime/surface-brief.ts`). Omitted = the first non-empty declared
+     * values. Code-only (not mirrored to the DB).
+     */
+    briefValues?: readonly string[];
+    /**
+     * Opt out of the automatic generic-baseline injection (`selection`,
+     * `text_before`, `text_after`, `content`, `context`) performed in
+     * `registry.ts`. Set ONLY for a surface that genuinely has no
+     * text/content/selection concept (a metadata-only widget). Almost never
+     * used — the generic baselines are what let an agent author bind to a
+     * universal value on any surface, so dropping them makes a surface invisible
+     * to every generic agent.
+     */
+    skipBaselineValues?: boolean;
+}
+/** Map types v1. Adding a new type is a TS branch + resolver case; no SQL changes. */
+/**
+ * A binding's per-target override of a write target's `applyPolicy`.
+ *
+ * Precedence (weakest → strongest): the SURFACE's per-target default
+ * (`SurfaceWriteTarget.applyPolicy`) → binding layers in the same order value
+ * mappings merge (global → org → user → shortcut). The user controls this
+ * wherever they bind — a shortcut is just the most opinionated binding layer,
+ * never a different system.
+ */
+export type SurfaceWritePolicy = "manual" | "ask" | "auto";
+/** target name → policy override. Stored in the surface_binding payload (v2). */
+export type WritePolicyMap = Record<string, SurfaceWritePolicy>;
+export declare function isSurfaceWritePolicy(v: unknown): v is SurfaceWritePolicy;
+/**
+ * Keep only well-formed `target → policy` entries from an untrusted JSONB
+ * blob; junk entries degrade to absent. The ONE sanitizer for every
+ * WritePolicyMap read path (binding edge payload, shortcut storage).
+ */
+export declare function sanitizeWritePolicyMap(raw: unknown): WritePolicyMap;
+export type ValueMappingType = "surface_value" | "direct_value" | "prompt_user" | "unmapped" | "offered_value";
+/**
+ * One mapping entry. Discriminated by `mapType`. Stored in JSONB so the DB
+ * shape is `Record<string, ValueMapping>`.
+ *
+ * - `surface_value` — bind to a SurfaceValue the surface declares. Resolver
+ *   reads from `ApplicationScope` at launch.
+ * - `direct_value`  — fixed literal scoped to this binding; overrides the
+ *   agent's own default while running here.
+ * - `prompt_user`   — show a one-shot dialog before launch (agent bindings
+ *   only — rejected for tool arg_mappings).
+ * - `unmapped`      — explicit suppression of auto-name-match for this key.
+ * - `offered_value` — the NEUTRAL consume-one-offered-value type used by the
+ *   Mandate consumption map (`agent.mandate_binding.consumption_map` — see
+ *   `features/mandates/provisions.ts`). Not a surface-binding map type:
+ *   the surface resolver refuses it loudly. Legacy persisted `code_value`
+ *   entries normalize to this shape on read (ONE funnel, no second parser).
+ */
+export type ValueMapping = {
+    mapType: "surface_value";
+    /** SurfaceValue.name on the owning surface. */
+    target: string;
+    /** If true, abort execution when the surface fails to supply a value at runtime. */
+    required?: boolean;
+} | {
+    mapType: "direct_value";
+    /** The literal value (string, number, boolean, object, array). */
+    target: unknown;
+    /** Delivery channel — see `offered_value`. A SURFACE binding never sets
+     * it (a surface mapping always feeds the named variable/slot directly);
+     * a MANDATE consumption map does, because the channel is a property of
+     * the TARGET and every source feeding one target must agree on it.
+     * Absent = `variable`, which is the pre-existing behaviour. */
+    deliver?: "variable" | "context";
+} | {
+    mapType: "prompt_user";
+    /** The prompt text shown in the input dialog. */
+    prompt: string;
+    /** Optional pre-filled value. */
+    defaultValue?: unknown;
+    /** If true, the user cannot cancel; submit is the only way out. */
+    required?: boolean;
+    /** Delivery channel — see `direct_value`. */
+    deliver?: "variable" | "context";
+} | {
+    mapType: "unmapped";
+} | {
+    mapType: "offered_value";
+    /** SOURCE offered-value name — renames on delivery when it differs from
+     * the map key. */
+    target: string;
+    required?: boolean;
+    /** Delivery channel: `variable` (immutable, turn-1, prompt-substituted)
+     * or `context` (mutable, context-policy path). Structured kinds may only
+     * ride `context`. Default: `variable`. */
+    deliver?: "variable" | "context";
+    /** REQUIRED (bind-time, server-enforced) for a non-guaranteed offered
+     * value: absence is a decision, never a surprise. */
+    when_absent?: "skip" | "use_default" | "fail";
+    /** Delivered when `when_absent === "use_default"` and the value is absent. */
+    default?: unknown;
+};
+/** Keys are agent variable / context-policy names, or tool arg names. */
+export type ValueMappingMap = Record<string, ValueMapping>;
+/**
+ * The typed `surface_binding` edge payload — the JSONB body of an
+ * agent → surface edge in `platform.associations`, schema-validated by the DB
+ * trigger against `platform.edge_payload_kind` (currently v3).
+ *
+ * Snake_case because this IS the stored shape; the TS-facing camelCase view is
+ * `AgentSurfaceBinding` in bind-agent-to-surface.service.ts.
+ */
+export interface SurfaceBindingPayload {
+    value_mappings: ValueMappingMap;
+    /** v2 — per-write-target applyPolicy overrides. */
+    write_policies?: WritePolicyMap;
+    /**
+     * v3 — THE AUTO-RUN INVERSION (THE-MODEL law 7): when true, triggering this
+     * binding on its surface sends the run immediately instead of stopping at
+     * the input panel. Absent/false = today's behavior (the panel opens and
+     * waits for Run), which is why every pre-v3 binding is unaffected.
+     *
+     * Intent, never a bypass: the launcher refuses to honor `true` when the
+     * mapping did not resolve every required variable for the live page — see
+     * `features/surfaces/utils/binding-auto-run.ts`.
+     */
+    auto_run?: boolean;
+}
+/** Single drift entry for a SurfaceValue not synced between code and DB. */
+export interface SurfaceValueDrift {
+    surfaceName: string;
+    valueName: string;
+    /**
+     * `updated_at` of the DB row, populated ONLY on `db_only` entries — the age
+     * is what separates "dead since a refactor last month" from "a sibling
+     * branch synced this twenty minutes ago", which is the question an admin
+     * has to answer before deleting a stale mirror row (see
+     * `RECENT_ROW_WINDOW_HOURS`). Absent on `manifest_only` (no DB row exists)
+     * and on `diff` (the row is live, so its age decides nothing).
+     */
+    updatedAt?: string;
+    /** `manifest_only` = code has it, DB doesn't. `db_only` = DB has it, code doesn't. `diff` = both have it but fields differ. */
+    kind: "manifest_only" | "db_only" | "diff";
+    /** Field-level diff when `kind === "diff"`. */
+    diff?: Partial<Record<keyof SurfaceValue | "groupKey", {
+        manifest: unknown;
+        db: unknown;
+    }>>;
+}
+/** Single drift entry for a SurfaceAgentRole not synced between code and DB. */
+export interface SurfaceAgentRoleDrift {
+    surfaceName: string;
+    roleName: string;
+    /**
+     * `updated_at` of the DB row, populated ONLY on `db_only` entries — the age
+     * is what separates "dead since a refactor last month" from "a sibling
+     * branch synced this twenty minutes ago", which is the question an admin
+     * has to answer before deleting a stale mirror row (see
+     * `RECENT_ROW_WINDOW_HOURS`). Absent on `manifest_only` (no DB row exists)
+     * and on `diff` (the row is live, so its age decides nothing).
+     */
+    updatedAt?: string;
+    /** `manifest_only` = code has it, DB doesn't. `db_only` = DB has it, code doesn't. `diff` = both have it but fields differ. */
+    kind: "manifest_only" | "db_only" | "diff";
+    /** Field-level diff when `kind === "diff"`. */
+    diff?: Partial<Record<keyof SurfaceAgentRole, {
+        manifest: unknown;
+        db: unknown;
+    }>>;
+}
+/**
+ * Single drift entry for a SurfaceWriteTarget not synced between code and DB.
+ *
+ * The WRITE half of the manifest is mirrored to `ui.ui_surface_write_target`
+ * so server-side agents can see what a surface ACCEPTS. That mirror can go
+ * stale exactly like the value mirror — a branch syncs targets its manifest
+ * declares, the branch never lands, and the rows outlive the code. Reporting
+ * them is what lets an admin decide; the alternative (a global `deleteStale`
+ * sweep) is indiscriminate and deletes rows belonging to unmerged work.
+ */
+export interface SurfaceWriteTargetDrift {
+    surfaceName: string;
+    targetName: string;
+    /**
+     * `updated_at` of the DB row, populated ONLY on `db_only` entries — the age
+     * is what separates "dead since a refactor last month" from "a sibling
+     * branch synced this twenty minutes ago", which is the question an admin
+     * has to answer before deleting a stale mirror row (see
+     * `RECENT_ROW_WINDOW_HOURS`). Absent on `manifest_only` (no DB row exists)
+     * and on `diff` (the row is live, so its age decides nothing).
+     */
+    updatedAt?: string;
+    /** `manifest_only` = code has it, DB doesn't. `db_only` = DB has it, code doesn't. `diff` = both have it but fields differ. */
+    kind: "manifest_only" | "db_only" | "diff";
+    /** Field-level diff when `kind === "diff"`. */
+    diff?: Partial<Record<keyof SurfaceWriteTarget | "groupKey", {
+        manifest: unknown;
+        db: unknown;
+    }>>;
+}
+/** Single drift entry for a SurfaceClientTool not synced between code and DB. */
+export interface SurfaceClientToolDrift {
+    surfaceName: string;
+    toolName: string;
+    /**
+     * `updated_at` of the DB row, populated ONLY on `db_only` entries — the age
+     * is what separates "dead since a refactor last month" from "a sibling
+     * branch synced this twenty minutes ago", which is the question an admin
+     * has to answer before deleting a stale mirror row (see
+     * `RECENT_ROW_WINDOW_HOURS`). Absent on `manifest_only` (no DB row exists)
+     * and on `diff` (the row is live, so its age decides nothing).
+     */
+    updatedAt?: string;
+    /** `manifest_only` = code has it, DB doesn't. `db_only` = DB has it, code doesn't. `diff` = both have it but fields differ. */
+    kind: "manifest_only" | "db_only" | "diff";
+    /** Field-level diff when `kind === "diff"`. */
+    diff?: Partial<Record<keyof SurfaceClientTool, {
+        manifest: unknown;
+        db: unknown;
+    }>>;
+}
+/** A config namespace referenced somewhere but missing a registered handler. */
+export interface UnknownNamespace {
+    namespace: string;
+    /** `manifest` = declared in a manifest's `configNamespaces`. `db` = present on `ui_surface_config` rows. */
+    source: "manifest" | "db";
+    /** Declaring surface (manifest side only — DB rows are reported per distinct namespace). */
+    surfaceName?: string;
+}
+/** Single broken-mapping entry — a JSONB mapping references a target that no longer exists. */
+export interface BrokenMapping {
+    /** The kind of binding whose mapping is broken. */
+    bindingKind: "agent";
+    /** Row id of the binding (binding association id). */
+    bindingId: string;
+    /** Surface this binding is for. */
+    surfaceName: string;
+    /** Variable / slot name whose mapping is broken. */
+    mappingKey: string;
+    /** The bad target. */
+    badTarget: string;
+    /** Snapshot of the offending ValueMapping for the UI. */
+    mapping: ValueMapping;
+}
+/** Single drift entry for `ui_surface.url_pattern` not synced from code. */
+export interface SurfaceUrlPatternDrift {
+    surfaceName: string;
+    kind: "missing_in_db" | "diff";
+    /** Resolved from manifest + route map. */
+    manifest: string;
+    /** Current DB value (null when missing). */
+    db: string | null;
+}
+/** Drift for `ui_surface.label` / `ui_surface.value_groups` vs the resolved manifest. */
+export interface SurfaceLabelDrift {
+    surfaceName: string;
+    kind: "missing_in_db" | "diff";
+    manifest: string;
+    db: string | null;
+}
+export interface SurfaceValueGroupsDrift {
+    surfaceName: string;
+    kind: "missing_in_db" | "diff";
+    manifest: readonly SurfaceValueGroup[];
+    db: unknown;
+}
+export interface SurfaceDriftReport {
+    /** Surface values that exist in code manifests but not in DB. */
+    manifestsMissingInDb: SurfaceValueDrift[];
+    /** Surface values that exist in DB but no longer in any code manifest. */
+    dbValuesNotInManifest: SurfaceValueDrift[];
+    /** Surface values present in both but with diverging field values. */
+    diffs: SurfaceValueDrift[];
+    /** Agent roles that exist in code manifests but not in DB. */
+    roleManifestsMissingInDb: SurfaceAgentRoleDrift[];
+    /** Agent roles that exist in DB but no longer in any code manifest. */
+    dbRolesNotInManifest: SurfaceAgentRoleDrift[];
+    /** Agent roles present in both but with diverging field values. */
+    roleDiffs: SurfaceAgentRoleDrift[];
+    /** Write targets that exist in code manifests but not in DB. */
+    writeTargetManifestsMissingInDb: SurfaceWriteTargetDrift[];
+    /** Write targets that exist in DB but no longer in any code manifest. */
+    dbWriteTargetsNotInManifest: SurfaceWriteTargetDrift[];
+    /** Write targets present in both but with diverging field values. */
+    writeTargetDiffs: SurfaceWriteTargetDrift[];
+    /** Client tools that exist in code manifests but not in DB. */
+    clientToolManifestsMissingInDb: SurfaceClientToolDrift[];
+    /** Client tools that exist in DB but no longer in any code manifest. */
+    dbClientToolsNotInManifest: SurfaceClientToolDrift[];
+    /** Client tools present in both but with diverging field values. */
+    clientToolDiffs: SurfaceClientToolDrift[];
+    /** Config namespaces referenced (manifest or `ui_surface_config`) without a registered handler. */
+    unknownNamespaces: UnknownNamespace[];
+    /** Broken `surface_value` mappings in agent↔surface binding value_mappings (platform.associations edge metadata). */
+    brokenAgentMappings: BrokenMapping[];
+    /** Surfaces whose `ui_surface.url_pattern` differs from code defaults. */
+    urlPatternDrifts: SurfaceUrlPatternDrift[];
+    /** Surfaces whose `ui_surface.label` differs from the canonical manifest label. */
+    surfaceLabelDrifts: SurfaceLabelDrift[];
+    /** Surfaces whose `ui_surface.value_groups` differs from the resolved manifest groups. */
+    valueGroupsDrifts: SurfaceValueGroupsDrift[];
+}
+export declare function isValueMapping(input: unknown): input is ValueMapping;
+export declare function isValueMappingMap(input: unknown): input is ValueMappingMap;
+/**
+ * Convenience type for surface scope payloads: the data a surface assembles
+ * and hands to the launcher. Compatible with `ApplicationScope` (string-keyed,
+ * `unknown` values). Kept as a re-export so consumers in this feature don't
+ * need to import from `features/agents/types/scope.types`.
+ */
+export type SurfaceScopePayload = ApplicationScope;