@ai-matrx/alchemy 0.5.1 → 0.6.0

package/dist/checks.d.ts

@@ -0,0 +1,253 @@
+/**
+ * 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: surface inserts, per-surface updates, and one upsert per table. */
+declare function renderSurfaceSyncSql(plan: SurfaceSyncPlan): string;
+
+export { GOVERNANCE_COLUMNS, type SurfaceRowPlan, type SurfaceSyncPlan, type SurfaceSyncPlanOptions, type SyncSchema, type SyncTablePlan, conflictUpdateColumns, planColumns, planSurfaceSync, renderSurfaceSyncSql, sqlLiteral };

package/dist/checks.js

@@ -0,0 +1,205 @@
+// src/declare/keys.ts
+function surfaceClientOf(surfaceName) {
+  return surfaceName.split("/")[0] ?? "";
+}
+
+// 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: v.resolvedSensitivity.exportable,
+          classification: v.resolvedSensitivity.classification,
+          included_by_default: v.resolvedSensitivity.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,
+        ...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 renderSurfaceSyncSql(plan) {
+  const out = [];
+  if (plan.surfaces.length > 0) {
+    const insertColumns = Object.keys(plan.surfaces[0].insert);
+    out.push("-- Register declared surfaces. Existing ui_client rows are required; this sync never creates clients.");
+    out.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;`
+    );
+    out.push("", "-- Mirror declared surface metadata (code-owned columns only)");
+    out.push(
+      plan.surfaces.map(
+        (s) => `UPDATE ui.ui_surface SET ${Object.entries(s.update).map(([c, v]) => `${c} = ${sqlLiteral(v)}`).join(", ")}, updated_at = now() WHERE name = ${sqlLiteral(s.name)};`
+      ).join("\n")
+    );
+  }
+  for (const table of plan.tables) {
+    const columns = planColumns(table);
+    const sets = conflictUpdateColumns(table).map((c) => `${c} = EXCLUDED.${c}`);
+    out.push("", `-- Upsert ${table.table} (governance columns insert-only)`);
+    out.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 out.join("\n");
+}
+export {
+  GOVERNANCE_COLUMNS,
+  conflictUpdateColumns,
+  planColumns,
+  planSurfaceSync,
+  renderSurfaceSyncSql,
+  sqlLiteral
+};
+//# sourceMappingURL=checks.js.map

package/dist/checks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/declare/keys.ts","../src/checks/sync.ts"],"sourcesContent":["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 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 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: v.resolvedSensitivity.exportable,\n              classification: v.resolvedSensitivity.classification,\n              included_by_default: v.resolvedSensitivity.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        ...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/** The plan as SQL: surface inserts, per-surface updates, and one upsert per table. */\nexport function renderSurfaceSyncSql(plan: SurfaceSyncPlan): string {\n  const out: string[] = [];\n  if (plan.surfaces.length > 0) {\n    const insertColumns = Object.keys(plan.surfaces[0]!.insert);\n    out.push(\"-- Register declared surfaces. Existing ui_client rows are required; this sync never creates clients.\");\n    out.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    out.push(\"\", \"-- Mirror declared surface metadata (code-owned columns only)\");\n    out.push(\n      plan.surfaces\n        .map(\n          (s) =>\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        .join(\"\\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    out.push(\"\", `-- Upsert ${table.table} (governance columns insert-only)`);\n    out.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 out.join(\"\\n\");\n}\n"],"mappings":"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","names":[]}