@ai-matrx/alchemy 0.5.1 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.6.1 — 2026-09-26
+
+`/checks` adds `renderSurfaceSyncStatements(plan)` (one statement per surface and table, so a caller can EXPLAIN each in a read-only transaction and prove the plan against a live schema with no write); `renderSurfaceSyncSql` joins them. With `schema.valueContract`, write-target rows also carry `patchable`, `approval_comparison`, `stream_ops` and `destination`, and value sensitivity is resolved with its defaults from the declaration itself.
+
+### Consumer action
+
+None required.
+
+## 0.6.0 — 2026-09-26
+
+Adds Declare (Matrx Alchemy ALC-14): what a screen holds moves into the package.
+
+- `/declare` — the declaration types (`SurfaceDeclaration`, `DeclaredValue`, `WriteTarget`, `ItemType`, `Sensitivity`, live slots), `createDeclarationRegistry` (inheritance, baseline injection, provenance, group synthesis — the app registry's behaviour, ported), `validateDeclarations` (the surface checks), `validateLoadedValues` (a loaded value the surface never declared is an issue), `findOrphanRows`, qualified item keys (`table_row.status`), and `declarationHash` (SHA-256 of canonical JSON). Framework-neutral: no React, no agents. Agent fields are extension slots (`DeclarationExtension`).
+- `/declare/host` — host-binding types only (`MountedSurface`, `ItemAnchor`, `InternalResolvedItem`).
+- `/declare/schema.json` — the JSON Schema, generated from the types (`pnpm generate:schema`; `check:package` fails when stale). Server-side clients (SMS, voice) validate their JSON declarations against it.
+- `/checks` — the ONE surface sync: `planSurfaceSync` (rows for every mirror table) and `renderSurfaceSyncSql`. Governance columns (`organization_id`, `visibility`) are insert-only; a conflict never rewrites them. `description`, `execution_mode` and `client_name` are now owned by the declaration. Columns from the ALC-14 migration are emitted only when the caller passes `schema`.
+
+### Consumer action
+
+None required for existing entries. A host that declares surfaces imports the types, registry and validation from `@ai-matrx/alchemy/declare` and runs every sync through `@ai-matrx/alchemy/checks`; its declarations must carry `client`, `executionMode` and `description`, and value sensitivity nests under `sensitivity`.
+
 ## 0.5.1
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/dist/checks.cjs

@@ -0,0 +1,249 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/checks.ts
+var checks_exports = {};
+__export(checks_exports, {
+  GOVERNANCE_COLUMNS: () => GOVERNANCE_COLUMNS,
+  conflictUpdateColumns: () => conflictUpdateColumns,
+  planColumns: () => planColumns,
+  planSurfaceSync: () => planSurfaceSync,
+  renderSurfaceSyncSql: () => renderSurfaceSyncSql,
+  renderSurfaceSyncStatements: () => renderSurfaceSyncStatements,
+  sqlLiteral: () => sqlLiteral
+});
+module.exports = __toCommonJS(checks_exports);
+
+// src/declare/keys.ts
+function surfaceClientOf(surfaceName) {
+  return surfaceName.split("/")[0] ?? "";
+}
+
+// src/declare/registry.ts
+var DEFAULT_SENSITIVITY = Object.freeze({
+  exportable: true,
+  classification: "ordinary",
+  includedByDefault: true
+});
+function resolveSensitivity(value) {
+  return {
+    exportable: value.sensitivity?.exportable ?? DEFAULT_SENSITIVITY.exportable,
+    classification: value.sensitivity?.classification ?? DEFAULT_SENSITIVITY.classification,
+    includedByDefault: value.sensitivity?.includedByDefault ?? DEFAULT_SENSITIVITY.includedByDefault
+  };
+}
+
+// src/checks/sync.ts
+var GOVERNANCE_COLUMNS = ["organization_id", "visibility"];
+function childKey(schema) {
+  return schema?.itemType ? ["surface_name", "item_type", "name"] : ["surface_name", "name"];
+}
+function planSurfaceSync(declarations, options) {
+  const { organizationId, syncedFrom, schema } = options;
+  const syncedBy = options.syncedBy ?? null;
+  const provenance = { synced_by: syncedBy, synced_from: syncedFrom };
+  const governance = { organization_id: organizationId, visibility: "public" };
+  const surfaces = [];
+  const values = [];
+  const targets = [];
+  const itemTypes = [];
+  const extensionTables = /* @__PURE__ */ new Map();
+  for (const d of declarations) {
+    const urlPattern = d.urlPattern?.trim() || options.resolveUrlPattern?.(d) || null;
+    const intro = d.intro?.trim() || null;
+    const parent = d.inheritsFrom ?? null;
+    const client = surfaceClientOf(d.surfaceName);
+    const owned = {
+      client_name: client,
+      execution_mode: d.executionMode,
+      description: d.description,
+      label: d.label,
+      value_groups: d.groups ?? [],
+      readiness: d.readiness,
+      readiness_note: d.readinessNote?.trim() || null,
+      ...schema?.contentHash ? { content_hash: d.contentHash } : {}
+    };
+    const claimed = {
+      ...d.overlayId ? { overlay_id: d.overlayId } : {},
+      ...urlPattern ? { url_pattern: urlPattern } : {},
+      ...intro ? { intro } : {},
+      ...parent ? { parent_surface_name: parent } : {}
+    };
+    surfaces.push({
+      name: d.surfaceName,
+      insert: {
+        name: d.surfaceName,
+        ...owned,
+        overlay_id: d.overlayId ?? null,
+        url_pattern: urlPattern,
+        intro,
+        parent_surface_name: parent
+      },
+      update: { ...owned, ...claimed }
+    });
+    for (const v of d.values) {
+      values.push({
+        ...governance,
+        surface_name: d.surfaceName,
+        ...schema?.itemType ? { item_type: "" } : {},
+        name: v.name,
+        label: v.label,
+        description: v.description,
+        value_type: v.valueType,
+        always_available: v.alwaysAvailable,
+        typical_char_count: v.typicalCharCount,
+        sort_order: v.sortOrder ?? 1e3,
+        auto_context: v.autoContext ?? true,
+        group_key: v.groupKey ?? v.group ?? "general",
+        ...schema?.valueContract ? {
+          exportable: resolveSensitivity(v).exportable,
+          classification: resolveSensitivity(v).classification,
+          included_by_default: resolveSensitivity(v).includedByDefault,
+          kind_key: v.valueKind ?? null,
+          live_slot: v.liveSlot ?? null,
+          role: v.role ?? "data"
+        } : {},
+        ...provenance
+      });
+    }
+    for (const t of d.writeTargets ?? []) {
+      targets.push({
+        ...governance,
+        surface_name: d.surfaceName,
+        ...schema?.itemType ? { item_type: t.itemType ?? "" } : {},
+        name: t.name,
+        label: t.label,
+        description: t.description,
+        value_type: t.valueType,
+        mode: t.mode,
+        updates_value: t.updatesValue ?? null,
+        group_key: t.group ?? "general",
+        sort_order: t.sortOrder ?? 1e3,
+        apply_policy: t.applyPolicy ?? "manual",
+        kind_key: t.valueKind ?? null,
+        ...schema?.valueContract ? {
+          patchable: t.patchable ?? false,
+          approval_comparison: t.approvalComparison ?? null,
+          stream_ops: t.streamOps ? [...t.streamOps] : null,
+          destination: t.destination ?? false
+        } : {},
+        ...provenance
+      });
+    }
+    if (schema?.itemType) {
+      for (const [position, item] of (d.itemTypes ?? []).entries()) {
+        itemTypes.push({
+          ...governance,
+          surface_name: d.surfaceName,
+          name: item.name,
+          label: item.label,
+          description: item.description,
+          identity: [...item.identity],
+          levels: item.levels ? [...item.levels] : null,
+          entity_type: item.entityType ?? null,
+          sort_order: position,
+          ...provenance
+        });
+        for (const v of item.values) {
+          values.push({
+            ...governance,
+            surface_name: d.surfaceName,
+            item_type: item.name,
+            name: v.name,
+            label: v.label,
+            description: v.description,
+            value_type: v.valueType,
+            always_available: v.alwaysAvailable,
+            typical_char_count: v.typicalCharCount,
+            sort_order: v.sortOrder ?? 1e3,
+            auto_context: v.autoContext ?? true,
+            group_key: v.group ?? "general",
+            ...provenance
+          });
+        }
+      }
+    }
+    for (const extension of options.extensions ?? []) {
+      for (const entry of extension.toRows?.(d) ?? []) {
+        const plan = extensionTables.get(entry.table) ?? {
+          table: entry.table,
+          conflict: entry.conflict,
+          insertOnly: GOVERNANCE_COLUMNS,
+          rows: []
+        };
+        plan.rows.push({ ...governance, ...entry.row, ...provenance });
+        extensionTables.set(entry.table, plan);
+      }
+    }
+  }
+  const tables = [
+    { table: "ui.ui_surface_value", conflict: childKey(schema), insertOnly: GOVERNANCE_COLUMNS, rows: values },
+    { table: "ui.ui_surface_write_target", conflict: childKey(schema), insertOnly: GOVERNANCE_COLUMNS, rows: targets },
+    ...schema?.itemType ? [{ table: "ui.ui_surface_item_type", conflict: ["surface_name", "name"], insertOnly: GOVERNANCE_COLUMNS, rows: itemTypes }] : [],
+    ...extensionTables.values()
+  ];
+  return { surfaces, tables: tables.filter((table) => table.rows.length > 0) };
+}
+function planColumns(table) {
+  const columns = [];
+  for (const row of table.rows) for (const key of Object.keys(row)) if (!columns.includes(key)) columns.push(key);
+  return columns;
+}
+function conflictUpdateColumns(table) {
+  return planColumns(table).filter((c) => !table.conflict.includes(c) && !table.insertOnly.includes(c));
+}
+function sqlLiteral(value) {
+  if (value === null || value === void 0) return "NULL";
+  if (typeof value === "boolean" || typeof value === "number") return String(value);
+  if (typeof value === "string") return `'${value.replace(/'/g, "''")}'`;
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+    return `ARRAY[${value.map((entry) => sqlLiteral(entry)).join(", ")}]::text[]`;
+  }
+  return `'${JSON.stringify(value).replace(/'/g, "''")}'::jsonb`;
+}
+function renderSurfaceSyncStatements(plan) {
+  const statements = [];
+  if (plan.surfaces.length > 0) {
+    const insertColumns = Object.keys(plan.surfaces[0].insert);
+    statements.push(
+      `INSERT INTO ui.ui_surface (${insertColumns.join(", ")}) VALUES
+${plan.surfaces.map((s) => `(${insertColumns.map((c) => sqlLiteral(s.insert[c])).join(", ")})`).join(",\n")}
+ON CONFLICT (name) DO NOTHING`
+    );
+    for (const s of plan.surfaces) {
+      statements.push(
+        `UPDATE ui.ui_surface SET ${Object.entries(s.update).map(([c, v]) => `${c} = ${sqlLiteral(v)}`).join(", ")}, updated_at = now() WHERE name = ${sqlLiteral(s.name)}`
+      );
+    }
+  }
+  for (const table of plan.tables) {
+    const columns = planColumns(table);
+    const sets = conflictUpdateColumns(table).map((c) => `${c} = EXCLUDED.${c}`);
+    statements.push(
+      `INSERT INTO ${table.table} (${columns.join(", ")}) VALUES
+${table.rows.map((row) => `(${columns.map((c) => sqlLiteral(row[c])).join(", ")})`).join(",\n")}
+ON CONFLICT (${table.conflict.join(", ")}) DO UPDATE SET ${[...sets, "updated_at = now()"].join(", ")}`
+    );
+  }
+  return statements;
+}
+function renderSurfaceSyncSql(plan) {
+  return renderSurfaceSyncStatements(plan).map((statement) => `${statement};`).join("\n\n");
+}
+//# sourceMappingURL=checks.cjs.map

package/dist/checks.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/checks.ts","../src/declare/keys.ts","../src/declare/registry.ts","../src/checks/sync.ts"],"sourcesContent":["/**\n * `@ai-matrx/alchemy/checks` — the ONE surface sync (CONTRACT §2.7): the row plan\n * every sync path executes, and its SQL rendering. Pure; no database client.\n */\nexport {\n  GOVERNANCE_COLUMNS,\n  conflictUpdateColumns,\n  planColumns,\n  planSurfaceSync,\n  renderSurfaceSyncSql,\n  renderSurfaceSyncStatements,\n  sqlLiteral,\n  type SurfaceRowPlan,\n  type SurfaceSyncPlan,\n  type SurfaceSyncPlanOptions,\n  type SyncSchema,\n  type SyncTablePlan,\n} from \"./checks/sync\";\n","import type { QualifiedValueKey } from \"./types\";\n\n/** Every value, write-target, item-type and group name (the DB CHECK rule). */\nexport const DECLARATION_NAME_RE = /^[a-z][a-z0-9_]*$/;\n\n/** \"<client>/<local>\" — the surface naming convention. */\nexport const SURFACE_NAME_RE = /^[a-z][a-z0-9-]*\\/[a-z0-9-/]+$/;\n\n/** A bare screen value (`status`) or an item value (`table_row.status`). */\nexport const QUALIFIED_VALUE_KEY_RE = /^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)?$/;\n\nexport interface ParsedValueKey {\n  /** \"\" for a screen-level value. */\n  itemType: string;\n  name: string;\n}\n\n/** Split a qualified key; null when it is not a valid bare or qualified key. */\nexport function parseQualifiedValueKey(key: string): ParsedValueKey | null {\n  if (!QUALIFIED_VALUE_KEY_RE.test(key)) return null;\n  const dot = key.indexOf(\".\");\n  if (dot === -1) return { itemType: \"\", name: key };\n  return { itemType: key.slice(0, dot), name: key.slice(dot + 1) };\n}\n\nexport function qualifyValueKey(itemType: string, name: string): QualifiedValueKey {\n  return itemType ? `${itemType}.${name}` : name;\n}\n\n/** The client that owns a surface: its name prefix. */\nexport function surfaceClientOf(surfaceName: string): string {\n  return surfaceName.split(\"/\")[0] ?? \"\";\n}\n","/**\n * The declaration registry: inheritance, baseline injection, provenance and\n * group synthesis (CONTRACT §2.1 `DeclarationRegistry`). Ported verbatim in\n * behaviour from matrx-frontend `features/surfaces/manifests/registry.ts`\n * (ALC-14); the app now supplies its declarations and baselines.\n *\n * Guards are LOUD by design: an unknown parent, a cycle, a chain deeper than\n * the limit, a reserved or duplicate group key, a value naming an undeclared\n * group, or a reserved platform name throws on resolution — a build fails\n * instead of silently dropping values.\n */\nimport { declarationHash } from \"./hash\";\nimport type {\n  DeclarationExtension,\n  DeclarationIssue,\n  DeclaredValue,\n  ResolvedSurfaceDeclaration,\n  ResolvedValue,\n  Sensitivity,\n  SurfaceDeclaration,\n  ValueGroup,\n  ValueProvenance,\n} from \"./types\";\nimport { validateDeclarations, type ValidateOptions } from \"./validate\";\n\nexport const RESERVED_GROUP_KEYS = {\n  general: \"general\",\n  baseline: \"baseline\",\n  inheritedPrefix: \"inherited:\",\n} as const;\n\n/** Group sortOrder bands. Curated groups author 0–899; the rest is reserved. */\nexport const GENERAL_GROUP_ORDER = 850;\nexport const INHERITED_GROUP_ORDER_BASE = 9000;\nexport const BASELINE_GROUP_ORDER = 9900;\nexport const DEFAULT_MAX_INHERITANCE_DEPTH = 3;\n\nexport const DEFAULT_SENSITIVITY: Sensitivity = Object.freeze({\n  exportable: true,\n  classification: \"ordinary\",\n  includedByDefault: true,\n});\n\nexport function resolveSensitivity(value: Pick<DeclaredValue, \"sensitivity\">): Sensitivity {\n  return {\n    exportable: value.sensitivity?.exportable ?? DEFAULT_SENSITIVITY.exportable,\n    classification: value.sensitivity?.classification ?? DEFAULT_SENSITIVITY.classification,\n    includedByDefault: value.sensitivity?.includedByDefault ?? DEFAULT_SENSITIVITY.includedByDefault,\n  };\n}\n\nexport type Resolved<D extends SurfaceDeclaration> = Omit<D, \"values\" | \"groups\"> & {\n  values: readonly (D[\"values\"][number] & ResolvedValue)[];\n  groups: readonly ValueGroup[];\n  contentHash: string;\n};\n\nexport interface DeclarationRegistryOptions {\n  /** Generic values injected into every declaration unless `skipBaselineValues`. */\n  baselineValues?: readonly DeclaredValue[];\n  /** Value names only the platform writes; a declaration claiming one is refused. */\n  reservedValueNames?: readonly string[];\n  /** Write-target names only the platform writes. */\n  reservedWriteTargetNames?: readonly string[];\n  maxInheritanceDepth?: number;\n}\n\nexport interface DeclarationRegistry<D extends SurfaceDeclaration> {\n  /** Refuses a second declaration of the same surfaceName. */\n  register(declaration: D): void;\n  registerExtension(extension: DeclarationExtension<D>): void;\n  extensions(): readonly DeclarationExtension<D>[];\n  /** Declarations exactly as authored (inheritance unresolved, no baselines). */\n  raw(): readonly D[];\n  getRaw(surfaceName: string): D | undefined;\n  /** Parent chain, ROOT FIRST. Unknown surfaces return []. */\n  ancestry(surfaceName: string): string[];\n  /** Direct children (declarations naming it in `inheritsFrom`), in declaration order. */\n  children(surfaceName: string): string[];\n  /** Inheritance + baseline + groups resolved; provenance kept. */\n  all(): readonly Resolved<D>[];\n  get(surfaceName: string): Resolved<D> | undefined;\n  validate(options?: ValidateOptions): readonly DeclarationIssue[];\n}\n\nexport function createDeclarationRegistry<D extends SurfaceDeclaration>(\n  options: DeclarationRegistryOptions = {},\n): DeclarationRegistry<D> {\n  const baselineValues = options.baselineValues ?? [];\n  const baselineNames = new Set(baselineValues.map((v) => v.name));\n  const reservedValues = new Set(options.reservedValueNames ?? []);\n  const reservedTargets = new Set(options.reservedWriteTargetNames ?? []);\n  const maxDepth = options.maxInheritanceDepth ?? DEFAULT_MAX_INHERITANCE_DEPTH;\n  const declarations: D[] = [];\n  const index = new Map<string, D>();\n  const extensionList: DeclarationExtension<D>[] = [];\n  let resolvedCache: Resolved<D>[] | null = null;\n  let resolvedIndex = new Map<string, Resolved<D>>();\n\n  function ancestry(surfaceName: string): string[] {\n    const chain: string[] = [];\n    const seen = new Set<string>([surfaceName]);\n    let current = index.get(surfaceName)?.inheritsFrom;\n    while (current) {\n      if (seen.has(current)) {\n        throw new Error(\n          `[surfaces] inheritsFrom CYCLE detected at \"${current}\" (from \"${surfaceName}\"). ` +\n            `Fix the manifest chain: ${[...seen].join(\" → \")} → ${current}`,\n        );\n      }\n      const parent = index.get(current);\n      if (!parent) {\n        throw new Error(\n          `[surfaces] \"${surfaceName}\" inheritsFrom unknown surface \"${current}\" — ` +\n            `the parent must be a registered declaration`,\n        );\n      }\n      seen.add(current);\n      chain.unshift(current);\n      if (chain.length > maxDepth) {\n        throw new Error(\n          `[surfaces] inheritance chain for \"${surfaceName}\" exceeds depth ${maxDepth}: ` + chain.join(\" → \"),\n        );\n      }\n      current = parent.inheritsFrom;\n    }\n    return chain;\n  }\n\n  function groupKeyFor(value: DeclaredValue, provenance: ValueProvenance): string {\n    if (provenance.kind === \"own\" && value.group) return value.group;\n    if (baselineNames.has(value.name)) return RESERVED_GROUP_KEYS.baseline;\n    if (provenance.kind === \"inherited\") return `${RESERVED_GROUP_KEYS.inheritedPrefix}${provenance.from}`;\n    if (provenance.kind === \"baseline\") return RESERVED_GROUP_KEYS.baseline;\n    return RESERVED_GROUP_KEYS.general;\n  }\n\n  function resolve(declaration: D): Resolved<D> {\n    const chain = ancestry(declaration.surfaceName);\n    const lineage: { layer: D; from: string | null }[] = [\n      ...chain.map((name) => {\n        const layer = index.get(name);\n        if (!layer) throw new Error(`[surfaces] missing inherited declaration \"${name}\"`);\n        return { layer, from: name };\n      }),\n      { layer: declaration, from: null },\n    ];\n\n    const curatedKeys = new Set<string>();\n    for (const group of declaration.groups ?? []) {\n      if (\n        group.key === RESERVED_GROUP_KEYS.general ||\n        group.key === RESERVED_GROUP_KEYS.baseline ||\n        group.key.startsWith(RESERVED_GROUP_KEYS.inheritedPrefix)\n      ) {\n        throw new Error(\n          `[surfaces] \"${declaration.surfaceName}\" declares reserved group key \"${group.key}\" — ` +\n            `general/baseline/inherited:* are synthesized by the registry`,\n        );\n      }\n      if (curatedKeys.has(group.key)) {\n        throw new Error(`[surfaces] \"${declaration.surfaceName}\" declares duplicate group key \"${group.key}\"`);\n      }\n      curatedKeys.add(group.key);\n    }\n    for (const value of declaration.values) {\n      if (reservedValues.has(value.name)) {\n        throw new Error(\n          `[surfaces] \"${declaration.surfaceName}\" declares value \"${value.name}\" — that name is written by the platform; choose another name`,\n        );\n      }\n      if (value.group && !curatedKeys.has(value.group)) {\n        throw new Error(\n          `[surfaces] \"${declaration.surfaceName}\" value \"${value.name}\" references undeclared ` +\n            `group \"${value.group}\" — declare it in the manifest's \\`groups\\``,\n        );\n      }\n    }\n    for (const target of declaration.writeTargets ?? []) {\n      if (reservedTargets.has(target.name)) {\n        throw new Error(\n          `[surfaces] \"${declaration.surfaceName}\" declares write target \"${target.name}\" — that name is written by the platform; choose another name`,\n        );\n      }\n    }\n\n    const valuesByName = new Map<string, D[\"values\"][number] & ResolvedValue>();\n    const inheritedLists = new Map<string, Map<string, unknown>>();\n    const coreLists: { field: string; identity(entry: unknown): string }[] = [\n      { field: \"configNamespaces\", identity: (entry) => (entry as { namespace: string }).namespace },\n      {\n        field: \"evidenceSources\",\n        identity: (entry) => `${(entry as { kind: string }).kind}:${(entry as { idValue: string }).idValue}`,\n      },\n    ];\n    const lists = [...coreLists, ...extensionList.flatMap((extension) => extension.inheritedLists ?? [])];\n    for (const { layer, from } of lineage) {\n      for (const value of layer.values) {\n        const provenance: ValueProvenance = from ? { kind: \"inherited\", from } : { kind: \"own\" };\n        valuesByName.set(value.name, {\n          ...value,\n          provenance,\n          groupKey: groupKeyFor(value, provenance),\n          resolvedSensitivity: resolveSensitivity(value),\n        });\n      }\n      for (const list of lists) {\n        const entries = (layer as unknown as Record<string, unknown>)[list.field];\n        if (!Array.isArray(entries)) continue;\n        const byIdentity = inheritedLists.get(list.field) ?? new Map<string, unknown>();\n        for (const entry of entries) byIdentity.set(list.identity(entry), entry);\n        inheritedLists.set(list.field, byIdentity);\n      }\n    }\n\n    if (!declaration.skipBaselineValues) {\n      for (const baseline of baselineValues) {\n        if (valuesByName.has(baseline.name)) continue;\n        valuesByName.set(baseline.name, {\n          ...baseline,\n          provenance: { kind: \"baseline\" },\n          groupKey: RESERVED_GROUP_KEYS.baseline,\n          resolvedSensitivity: resolveSensitivity(baseline),\n        } as D[\"values\"][number] & ResolvedValue);\n      }\n    }\n\n    const usedGroupKeys = new Set(Array.from(valuesByName.values(), (value) => value.groupKey));\n    const groups: ValueGroup[] = [...(declaration.groups ?? [])];\n    if (usedGroupKeys.has(RESERVED_GROUP_KEYS.general)) {\n      groups.push({ key: RESERVED_GROUP_KEYS.general, label: \"General\", sortOrder: GENERAL_GROUP_ORDER });\n    }\n    for (let i = chain.length - 1, distance = 0; i >= 0; i -= 1, distance += 1) {\n      const parentName = chain[i]!;\n      const key = `${RESERVED_GROUP_KEYS.inheritedPrefix}${parentName}`;\n      if (!usedGroupKeys.has(key)) continue;\n      const parentLabel = index.get(parentName)?.label ?? parentName;\n      groups.push({\n        key,\n        label: `Inherited from ${parentLabel}`,\n        sortOrder: INHERITED_GROUP_ORDER_BASE + distance * 10,\n      });\n    }\n    if (usedGroupKeys.has(RESERVED_GROUP_KEYS.baseline)) {\n      groups.push({ key: RESERVED_GROUP_KEYS.baseline, label: \"Generic baselines\", sortOrder: BASELINE_GROUP_ORDER });\n    }\n    groups.sort((a, b) => a.sortOrder - b.sortOrder);\n\n    const groupOrder = new Map(groups.map((group) => [group.key, group.sortOrder] as const));\n    const values = Array.from(valuesByName.values()).sort((a, b) => {\n      const ga = groupOrder.get(a.groupKey) ?? GENERAL_GROUP_ORDER;\n      const gb = groupOrder.get(b.groupKey) ?? GENERAL_GROUP_ORDER;\n      if (ga !== gb) return ga - gb;\n      return (a.sortOrder ?? 1000) - (b.sortOrder ?? 1000);\n    });\n\n    const merged: Record<string, unknown> = {};\n    for (const [field, byIdentity] of inheritedLists) {\n      if (byIdentity.size > 0) merged[field] = Array.from(byIdentity.values());\n    }\n    return {\n      ...declaration,\n      values,\n      groups,\n      ...merged,\n      contentHash: declarationHash(declaration),\n    } as Resolved<D>;\n  }\n\n  function resolvedAll(): Resolved<D>[] {\n    if (!resolvedCache) {\n      resolvedCache = declarations.map(resolve);\n      resolvedIndex = new Map(resolvedCache.map((entry) => [entry.surfaceName, entry] as const));\n    }\n    return resolvedCache;\n  }\n\n  const registry: DeclarationRegistry<D> = {\n    register(declaration) {\n      if (index.has(declaration.surfaceName)) {\n        throw new Error(`[surfaces] \"${declaration.surfaceName}\" is declared twice — one surface, one declaration`);\n      }\n      declarations.push(declaration);\n      index.set(declaration.surfaceName, declaration);\n      resolvedCache = null;\n    },\n    registerExtension(extension) {\n      if (extensionList.some((existing) => existing.key === extension.key)) {\n        throw new Error(`[surfaces] declaration extension \"${extension.key}\" is registered twice`);\n      }\n      extensionList.push(extension);\n      resolvedCache = null;\n    },\n    extensions: () => extensionList,\n    raw: () => declarations,\n    getRaw: (surfaceName) => index.get(surfaceName),\n    ancestry,\n    children: (surfaceName) =>\n      declarations.filter((d) => d.inheritsFrom === surfaceName).map((d) => d.surfaceName),\n    all: () => resolvedAll(),\n    get(surfaceName) {\n      resolvedAll();\n      return resolvedIndex.get(surfaceName);\n    },\n    validate: (validateOptions) =>\n      validateDeclarations(resolvedAll() as unknown as readonly ResolvedSurfaceDeclaration[], {\n        ...validateOptions,\n        extensions: [...(validateOptions?.extensions ?? []), ...(extensionList as DeclarationExtension[])],\n        baselineNames: validateOptions?.baselineNames ?? [...baselineNames],\n      }),\n  };\n  return registry;\n}\n","/**\n * THE ONE SYNC (CONTRACT §2.7 \"One sync path\", chair ruling B1).\n *\n * `planSurfaceSync` maps resolved declarations onto the `ui` mirror rows; every\n * sync path (the SQL emitter and the admin sync service) executes this plan and\n * builds no rows of its own. Governance columns (`organization_id`,\n * `visibility`) are INSERT-ONLY (chair ruling N5): a conflict never rewrites them.\n *\n * Schema generations: the columns added by the ALC-14 migration (item_type,\n * sensitivity, live slots, content_hash) are emitted only when the caller says\n * that migration is live (`schema`), so no emitter ever writes a column — or\n * upserts against a key — the database does not have yet.\n */\nimport { resolveSensitivity, type Resolved } from \"../declare/registry\";\nimport { surfaceClientOf } from \"../declare/keys\";\nimport type { DeclarationExtension, Json, SurfaceDeclaration } from \"../declare/types\";\n\nexport const GOVERNANCE_COLUMNS = [\"organization_id\", \"visibility\"] as const;\n\nexport interface SyncSchema {\n  /** `ui_surface_value/write_target.item_type` exists and the conflict key includes it (re-key step 1). */\n  itemType?: boolean;\n  /** Sensitivity, kind, live slot and role columns exist on `ui_surface_value`. */\n  valueContract?: boolean;\n  /** `ui_surface.content_hash` exists. */\n  contentHash?: boolean;\n}\n\nexport interface SurfaceSyncPlanOptions<D extends SurfaceDeclaration> {\n  organizationId: string;\n  syncedFrom: string;\n  syncedBy?: string | null;\n  /** The address the host derives for a declaration without `urlPattern`. */\n  resolveUrlPattern?: (declaration: Resolved<D>) => string | undefined;\n  extensions?: readonly DeclarationExtension<D>[];\n  schema?: SyncSchema;\n}\n\nexport interface SurfaceRowPlan {\n  name: string;\n  /** Written only when the row does not exist yet. */\n  insert: Record<string, Json>;\n  /** Written on every sync (code owns these columns). */\n  update: Record<string, Json>;\n}\n\nexport interface SyncTablePlan {\n  table: string;\n  /** The ON CONFLICT target (a unique index or primary key on exactly these columns). */\n  conflict: readonly string[];\n  /** Columns set on insert and never on conflict. */\n  insertOnly: readonly string[];\n  rows: Record<string, Json>[];\n}\n\nexport interface SurfaceSyncPlan {\n  surfaces: SurfaceRowPlan[];\n  tables: SyncTablePlan[];\n}\n\nfunction childKey(schema: SyncSchema | undefined): readonly string[] {\n  return schema?.itemType ? [\"surface_name\", \"item_type\", \"name\"] : [\"surface_name\", \"name\"];\n}\n\nexport function planSurfaceSync<D extends SurfaceDeclaration>(\n  declarations: readonly Resolved<D>[],\n  options: SurfaceSyncPlanOptions<D>,\n): SurfaceSyncPlan {\n  const { organizationId, syncedFrom, schema } = options;\n  const syncedBy = options.syncedBy ?? null;\n  const provenance = { synced_by: syncedBy, synced_from: syncedFrom };\n  const governance = { organization_id: organizationId, visibility: \"public\" };\n  const surfaces: SurfaceRowPlan[] = [];\n  const values: Record<string, Json>[] = [];\n  const targets: Record<string, Json>[] = [];\n  const itemTypes: Record<string, Json>[] = [];\n  const extensionTables = new Map<string, SyncTablePlan>();\n\n  for (const d of declarations) {\n    const urlPattern = d.urlPattern?.trim() || options.resolveUrlPattern?.(d) || null;\n    const intro = d.intro?.trim() || null;\n    const parent = d.inheritsFrom ?? null;\n    const client = surfaceClientOf(d.surfaceName);\n    const owned: Record<string, Json> = {\n      client_name: client,\n      execution_mode: d.executionMode,\n      description: d.description,\n      label: d.label,\n      value_groups: (d.groups ?? []) as unknown as Json,\n      readiness: d.readiness,\n      readiness_note: d.readinessNote?.trim() || null,\n      ...(schema?.contentHash ? { content_hash: d.contentHash } : {}),\n    };\n    // A declaration that does not claim these never clears a DB-authored value.\n    const claimed: Record<string, Json> = {\n      ...(d.overlayId ? { overlay_id: d.overlayId } : {}),\n      ...(urlPattern ? { url_pattern: urlPattern } : {}),\n      ...(intro ? { intro } : {}),\n      ...(parent ? { parent_surface_name: parent } : {}),\n    };\n    surfaces.push({\n      name: d.surfaceName,\n      insert: {\n        name: d.surfaceName,\n        ...owned,\n        overlay_id: d.overlayId ?? null,\n        url_pattern: urlPattern,\n        intro,\n        parent_surface_name: parent,\n      },\n      update: { ...owned, ...claimed },\n    });\n\n    for (const v of d.values) {\n      values.push({\n        ...governance,\n        surface_name: d.surfaceName,\n        ...(schema?.itemType ? { item_type: \"\" } : {}),\n        name: v.name,\n        label: v.label,\n        description: v.description,\n        value_type: v.valueType,\n        always_available: v.alwaysAvailable,\n        typical_char_count: v.typicalCharCount,\n        sort_order: v.sortOrder ?? 1000,\n        auto_context: v.autoContext ?? true,\n        group_key: v.groupKey ?? v.group ?? \"general\",\n        ...(schema?.valueContract\n          ? {\n              exportable: resolveSensitivity(v).exportable,\n              classification: resolveSensitivity(v).classification,\n              included_by_default: resolveSensitivity(v).includedByDefault,\n              kind_key: v.valueKind ?? null,\n              live_slot: v.liveSlot ?? null,\n              role: v.role ?? \"data\",\n            }\n          : {}),\n        ...provenance,\n      });\n    }\n\n    for (const t of d.writeTargets ?? []) {\n      targets.push({\n        ...governance,\n        surface_name: d.surfaceName,\n        ...(schema?.itemType ? { item_type: t.itemType ?? \"\" } : {}),\n        name: t.name,\n        label: t.label,\n        description: t.description,\n        value_type: t.valueType,\n        mode: t.mode,\n        updates_value: t.updatesValue ?? null,\n        group_key: t.group ?? \"general\",\n        sort_order: t.sortOrder ?? 1000,\n        apply_policy: t.applyPolicy ?? \"manual\",\n        kind_key: t.valueKind ?? null,\n        ...(schema?.valueContract\n          ? {\n              patchable: t.patchable ?? false,\n              approval_comparison: t.approvalComparison ?? null,\n              stream_ops: t.streamOps ? [...t.streamOps] : null,\n              destination: t.destination ?? false,\n            }\n          : {}),\n        ...provenance,\n      });\n    }\n\n    if (schema?.itemType) {\n      for (const [position, item] of (d.itemTypes ?? []).entries()) {\n        itemTypes.push({\n          ...governance,\n          surface_name: d.surfaceName,\n          name: item.name,\n          label: item.label,\n          description: item.description,\n          identity: [...item.identity],\n          levels: item.levels ? [...item.levels] : null,\n          entity_type: item.entityType ?? null,\n          sort_order: position,\n          ...provenance,\n        });\n        for (const v of item.values) {\n          values.push({\n            ...governance,\n            surface_name: d.surfaceName,\n            item_type: item.name,\n            name: v.name,\n            label: v.label,\n            description: v.description,\n            value_type: v.valueType,\n            always_available: v.alwaysAvailable,\n            typical_char_count: v.typicalCharCount,\n            sort_order: v.sortOrder ?? 1000,\n            auto_context: v.autoContext ?? true,\n            group_key: v.group ?? \"general\",\n            ...provenance,\n          });\n        }\n      }\n    }\n\n    for (const extension of options.extensions ?? []) {\n      for (const entry of extension.toRows?.(d as unknown as D) ?? []) {\n        const plan = extensionTables.get(entry.table) ?? {\n          table: entry.table,\n          conflict: entry.conflict,\n          insertOnly: GOVERNANCE_COLUMNS,\n          rows: [],\n        };\n        plan.rows.push({ ...governance, ...entry.row, ...provenance });\n        extensionTables.set(entry.table, plan);\n      }\n    }\n  }\n\n  const tables: SyncTablePlan[] = [\n    { table: \"ui.ui_surface_value\", conflict: childKey(schema), insertOnly: GOVERNANCE_COLUMNS, rows: values },\n    { table: \"ui.ui_surface_write_target\", conflict: childKey(schema), insertOnly: GOVERNANCE_COLUMNS, rows: targets },\n    ...(schema?.itemType\n      ? [{ table: \"ui.ui_surface_item_type\", conflict: [\"surface_name\", \"name\"], insertOnly: GOVERNANCE_COLUMNS, rows: itemTypes }]\n      : []),\n    ...extensionTables.values(),\n  ];\n  return { surfaces, tables: tables.filter((table) => table.rows.length > 0) };\n}\n\n/** Every column a table's rows carry, in first-seen order. */\nexport function planColumns(table: SyncTablePlan): string[] {\n  const columns: string[] = [];\n  for (const row of table.rows) for (const key of Object.keys(row)) if (!columns.includes(key)) columns.push(key);\n  return columns;\n}\n\n/** Columns a conflict rewrites: everything except the key and the insert-only set. */\nexport function conflictUpdateColumns(table: SyncTablePlan): string[] {\n  return planColumns(table).filter((c) => !table.conflict.includes(c) && !table.insertOnly.includes(c));\n}\n\nexport function sqlLiteral(value: Json | undefined): string {\n  if (value === null || value === undefined) return \"NULL\";\n  if (typeof value === \"boolean\" || typeof value === \"number\") return String(value);\n  if (typeof value === \"string\") return `'${value.replace(/'/g, \"''\")}'`;\n  if (Array.isArray(value) && value.every((entry) => typeof entry === \"string\")) {\n    return `ARRAY[${value.map((entry) => sqlLiteral(entry)).join(\", \")}]::text[]`;\n  }\n  return `'${JSON.stringify(value).replace(/'/g, \"''\")}'::jsonb`;\n}\n\n/**\n * The plan as SQL statements, one per entry: surface insert, one UPDATE per\n * surface, one upsert per table. Callers may run them, or EXPLAIN each one in a\n * read-only transaction to prove the plan against a live schema with no write.\n */\nexport function renderSurfaceSyncStatements(plan: SurfaceSyncPlan): string[] {\n  const statements: string[] = [];\n  if (plan.surfaces.length > 0) {\n    const insertColumns = Object.keys(plan.surfaces[0]!.insert);\n    statements.push(\n      `INSERT INTO ui.ui_surface (${insertColumns.join(\", \")}) VALUES\\n${plan.surfaces\n        .map((s) => `(${insertColumns.map((c) => sqlLiteral(s.insert[c])).join(\", \")})`)\n        .join(\",\\n\")}\\nON CONFLICT (name) DO NOTHING`,\n    );\n    for (const s of plan.surfaces) {\n      statements.push(\n        `UPDATE ui.ui_surface SET ${Object.entries(s.update)\n          .map(([c, v]) => `${c} = ${sqlLiteral(v)}`)\n          .join(\", \")}, updated_at = now() WHERE name = ${sqlLiteral(s.name)}`,\n      );\n    }\n  }\n  for (const table of plan.tables) {\n    const columns = planColumns(table);\n    const sets = conflictUpdateColumns(table).map((c) => `${c} = EXCLUDED.${c}`);\n    statements.push(\n      `INSERT INTO ${table.table} (${columns.join(\", \")}) VALUES\\n${table.rows\n        .map((row) => `(${columns.map((c) => sqlLiteral(row[c])).join(\", \")})`)\n        .join(\",\\n\")}\\nON CONFLICT (${table.conflict.join(\", \")}) DO UPDATE SET ${[...sets, \"updated_at = now()\"].join(\", \")}`,\n    );\n  }\n  return statements;\n}\n\n/** The plan as one SQL script (governance columns insert-only). */\nexport function renderSurfaceSyncSql(plan: SurfaceSyncPlan): string {\n  return renderSurfaceSyncStatements(plan)\n    .map((statement) => `${statement};`)\n    .join(\"\\n\\n\");\n}\n"],"mappings":"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","names":[]}

package/dist/checks.d.cts

@@ -0,0 +1,259 @@
+/**
+ * Matrx Alchemy — Declare types (CONTRACT §2.1).
+ *
+ * A declaration is plain JSON data (chair ruling N2): no functions, no classes,
+ * no React. Runtime behaviour lives in `MountedSurface` (`/declare/host`) and in
+ * handler registrations, never here. Zero React, zero `@ai-matrx/agents`.
+ */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** Unchanged from `ui_surface_value_type_chk`. */
+type ValueType = "string" | "number" | "boolean" | "object" | "array" | "document";
+type Classification = "ordinary" | "secret" | "credential";
+/** Persisted (CONTRACT §2.7). Projection enforces it before any value leaves. */
+interface Sensitivity {
+    /** false = never leaves through Operate. Default true. */
+    exportable: boolean;
+    /** secret/credential are always excluded; no caller can relax this. Default "ordinary". */
+    classification: Classification;
+    /** Pre-checked in the preparation workspace. Default true. */
+    includedByDefault: boolean;
+}
+interface ValueGroup {
+    key: string;
+    label: string;
+    sortOrder: number;
+    description?: string;
+}
+/** The four runtime slots a capture fills (absorbs page-capture). */
+type LiveSlot = "selection" | "on-demand" | "errors" | "requests";
+interface DeclaredValue {
+    name: string;
+    label: string;
+    description: string;
+    valueType: ValueType;
+    /** Registered content-ir kind key (DB: kind_key). */
+    valueKind?: string;
+    alwaysAvailable: boolean;
+    typicalCharCount: number;
+    autoContext?: boolean;
+    group?: string;
+    sortOrder?: number;
+    sensitivity?: Partial<Sensitivity>;
+    /** Filled at capture time from a live slot instead of the scope. */
+    liveSlot?: LiveSlot;
+    /** "request" values drop out of "Only the data". Default "data". */
+    role?: "data" | "request";
+}
+/** Where a write lands. "stream" = applied live, op by op, into an editable text. */
+type WriteMode = "draft" | "entity" | "ui" | "stream";
+/** Who may apply WITHOUT a click. "queued" = filed for an organization's review. */
+type ApplyPolicy = "manual" | "ask" | "auto" | "queued";
+/** The WidgetHandle text op set, unchanged in meaning. */
+type StreamOp = "replace" | "insert_before" | "insert_after" | "prepend" | "append" | "patch";
+interface WriteTarget {
+    name: string;
+    label: string;
+    description: string;
+    valueType: ValueType;
+    valueKind?: string;
+    /** Read twin (evidence loop). Required when patchable or mode === "stream". */
+    updatesValue?: string;
+    patchable?: boolean;
+    approvalComparison?: "text-replacement";
+    mode: WriteMode;
+    /** Required iff mode === "stream". */
+    streamOps?: readonly StreamOp[];
+    /** Default "manual". Binding overrides may only tighten. */
+    applyPolicy?: ApplyPolicy;
+    destination?: boolean;
+    /** Present when the target writes into an item rather than the screen. */
+    itemType?: string;
+    group?: string;
+    sortOrder?: number;
+}
+/** One kind of thing inside a screen (a row, a message, a code block, a card). */
+interface ItemType {
+    name: string;
+    label: string;
+    description: string;
+    /** Value names that together identify one item. */
+    identity: readonly string[];
+    levels?: readonly string[];
+    entityType?: string;
+    values: readonly DeclaredValue[];
+    writeTargets?: readonly WriteTarget[];
+}
+type Readiness = "verified" | "partial" | "stub";
+/** `ui_surface_execution_mode_check`, unchanged. */
+type ExecutionMode = "python-stream" | "nextjs-stream" | "browser-realtime" | "local-runtime";
+interface ConfigNamespaceDeclaration {
+    namespace: string;
+    label: string;
+    description: string;
+}
+interface EvidenceSourceDeclaration {
+    kind: "processed_document";
+    idValue: string;
+    fileIdValue?: string;
+    labelValue?: string;
+    representation?: "clean" | "raw";
+}
+/**
+ * One screen's declaration. Owning packages add fields (agent roles, client
+ * tools) as EXTENSION SLOTS — by interface extension or declaration merging —
+ * and register a `DeclarationExtension` so validation and the sync cover them.
+ */
+interface SurfaceDeclaration {
+    surfaceName: string;
+    /** REQUIRED. `ui_surface.client_name`; must equal the surfaceName prefix. */
+    client: string;
+    /** REQUIRED. `ui_surface.execution_mode`. */
+    executionMode: ExecutionMode;
+    /** REQUIRED. `ui_surface.description` ("" only where the live row is empty). */
+    description: string;
+    label: string;
+    readiness: Readiness;
+    readinessNote?: string;
+    urlPattern?: string;
+    inheritsFrom?: string;
+    intro?: string;
+    overlayId?: string;
+    values: readonly DeclaredValue[];
+    groups?: readonly ValueGroup[];
+    writeTargets?: readonly WriteTarget[];
+    itemTypes?: readonly ItemType[];
+    liveSlots?: readonly LiveSlot[];
+    configNamespaces?: readonly ConfigNamespaceDeclaration[];
+    evidenceSources?: readonly EvidenceSourceDeclaration[];
+    skipBaselineValues?: boolean;
+}
+interface DeclarationIssue {
+    surfaceName: string;
+    /** "writeTargets/body/updatesValue" */
+    path: string;
+    sentence: string;
+    remedy: string;
+    /** Advisory issues are reported, never fatal (the ratchets). Default "error". */
+    severity?: "error" | "advisory";
+}
+/** A row the sync writes for an extension slot (e.g. agent roles, client tools). */
+interface ExtensionRow {
+    table: string;
+    /** The row's key columns within its table (e.g. ["surface_name", "name"]). */
+    conflict: readonly string[];
+    row: Record<string, Json>;
+}
+interface DeclarationExtension<D extends SurfaceDeclaration = SurfaceDeclaration> {
+    key: string;
+    /** Package or app that owns the slot, shown in check failures. */
+    owner: string;
+    /**
+     * Lists this slot contributes to inheritance: a child inherits its parent's
+     * entries and overrides per identity (child wins).
+     */
+    inheritedLists?: readonly {
+        field: string;
+        identity(entry: unknown): string;
+    }[];
+    validate?(declaration: D, context: ValidationContext): readonly DeclarationIssue[];
+    toRows?(declaration: D): readonly ExtensionRow[];
+}
+interface ValidationContext {
+    /** Every registered declaration, resolved. */
+    all: readonly ResolvedSurfaceDeclaration[];
+}
+type ValueProvenance = {
+    kind: "own";
+} | {
+    kind: "inherited";
+    from: string;
+} | {
+    kind: "baseline";
+};
+type ResolvedValue = DeclaredValue & {
+    provenance: ValueProvenance;
+    groupKey: string;
+    /** Defaults filled. */
+    resolvedSensitivity: Sensitivity;
+};
+interface ResolvedSurfaceDeclaration extends SurfaceDeclaration {
+    contentHash: string;
+    values: readonly ResolvedValue[];
+    groups: readonly ValueGroup[];
+}
+
+type Resolved<D extends SurfaceDeclaration> = Omit<D, "values" | "groups"> & {
+    values: readonly (D["values"][number] & ResolvedValue)[];
+    groups: readonly ValueGroup[];
+    contentHash: string;
+};
+
+/**
+ * THE ONE SYNC (CONTRACT §2.7 "One sync path", chair ruling B1).
+ *
+ * `planSurfaceSync` maps resolved declarations onto the `ui` mirror rows; every
+ * sync path (the SQL emitter and the admin sync service) executes this plan and
+ * builds no rows of its own. Governance columns (`organization_id`,
+ * `visibility`) are INSERT-ONLY (chair ruling N5): a conflict never rewrites them.
+ *
+ * Schema generations: the columns added by the ALC-14 migration (item_type,
+ * sensitivity, live slots, content_hash) are emitted only when the caller says
+ * that migration is live (`schema`), so no emitter ever writes a column — or
+ * upserts against a key — the database does not have yet.
+ */
+
+declare const GOVERNANCE_COLUMNS: readonly ["organization_id", "visibility"];
+interface SyncSchema {
+    /** `ui_surface_value/write_target.item_type` exists and the conflict key includes it (re-key step 1). */
+    itemType?: boolean;
+    /** Sensitivity, kind, live slot and role columns exist on `ui_surface_value`. */
+    valueContract?: boolean;
+    /** `ui_surface.content_hash` exists. */
+    contentHash?: boolean;
+}
+interface SurfaceSyncPlanOptions<D extends SurfaceDeclaration> {
+    organizationId: string;
+    syncedFrom: string;
+    syncedBy?: string | null;
+    /** The address the host derives for a declaration without `urlPattern`. */
+    resolveUrlPattern?: (declaration: Resolved<D>) => string | undefined;
+    extensions?: readonly DeclarationExtension<D>[];
+    schema?: SyncSchema;
+}
+interface SurfaceRowPlan {
+    name: string;
+    /** Written only when the row does not exist yet. */
+    insert: Record<string, Json>;
+    /** Written on every sync (code owns these columns). */
+    update: Record<string, Json>;
+}
+interface SyncTablePlan {
+    table: string;
+    /** The ON CONFLICT target (a unique index or primary key on exactly these columns). */
+    conflict: readonly string[];
+    /** Columns set on insert and never on conflict. */
+    insertOnly: readonly string[];
+    rows: Record<string, Json>[];
+}
+interface SurfaceSyncPlan {
+    surfaces: SurfaceRowPlan[];
+    tables: SyncTablePlan[];
+}
+declare function planSurfaceSync<D extends SurfaceDeclaration>(declarations: readonly Resolved<D>[], options: SurfaceSyncPlanOptions<D>): SurfaceSyncPlan;
+/** Every column a table's rows carry, in first-seen order. */
+declare function planColumns(table: SyncTablePlan): string[];
+/** Columns a conflict rewrites: everything except the key and the insert-only set. */
+declare function conflictUpdateColumns(table: SyncTablePlan): string[];
+declare function sqlLiteral(value: Json | undefined): string;
+/**
+ * The plan as SQL statements, one per entry: surface insert, one UPDATE per
+ * surface, one upsert per table. Callers may run them, or EXPLAIN each one in a
+ * read-only transaction to prove the plan against a live schema with no write.
+ */
+declare function renderSurfaceSyncStatements(plan: SurfaceSyncPlan): string[];
+/** The plan as one SQL script (governance columns insert-only). */
+declare function renderSurfaceSyncSql(plan: SurfaceSyncPlan): string;
+
+export { GOVERNANCE_COLUMNS, type SurfaceRowPlan, type SurfaceSyncPlan, type SurfaceSyncPlanOptions, type SyncSchema, type SyncTablePlan, conflictUpdateColumns, planColumns, planSurfaceSync, renderSurfaceSyncSql, renderSurfaceSyncStatements, sqlLiteral };