@ai-matrx/alchemy 0.5.1 → 0.6.1

package/dist/declare.js

@@ -0,0 +1,614 @@
+// src/declare/keys.ts
+var DECLARATION_NAME_RE = /^[a-z][a-z0-9_]*$/;
+var SURFACE_NAME_RE = /^[a-z][a-z0-9-]*\/[a-z0-9-/]+$/;
+var QUALIFIED_VALUE_KEY_RE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)?$/;
+function parseQualifiedValueKey(key) {
+  if (!QUALIFIED_VALUE_KEY_RE.test(key)) return null;
+  const dot = key.indexOf(".");
+  if (dot === -1) return { itemType: "", name: key };
+  return { itemType: key.slice(0, dot), name: key.slice(dot + 1) };
+}
+function qualifyValueKey(itemType, name) {
+  return itemType ? `${itemType}.${name}` : name;
+}
+function surfaceClientOf(surfaceName) {
+  return surfaceName.split("/")[0] ?? "";
+}
+
+// src/declare/hash.ts
+function canonicalJson(value) {
+  if (value === void 0) return "null";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+  const record = value;
+  return `{${Object.keys(record).filter((key) => record[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+}
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function sha256Hex(input) {
+  const bytes = new TextEncoder().encode(input);
+  const bitLength = bytes.length * 8;
+  const padded = new Uint8Array(bytes.length + 9 + 63 >> 6 << 6);
+  padded.set(bytes);
+  padded[bytes.length] = 128;
+  const view = new DataView(padded.buffer);
+  view.setUint32(padded.length - 8, Math.floor(bitLength / 4294967296));
+  view.setUint32(padded.length - 4, bitLength >>> 0);
+  const h = new Uint32Array([
+    1779033703,
+    3144134277,
+    1013904242,
+    2773480762,
+    1359893119,
+    2600822924,
+    528734635,
+    1541459225
+  ]);
+  const w = new Uint32Array(64);
+  for (let offset = 0; offset < padded.length; offset += 64) {
+    for (let i = 0; i < 16; i += 1) w[i] = view.getUint32(offset + i * 4);
+    for (let i = 16; i < 64; i += 1) {
+      const a2 = w[i - 15];
+      const b2 = w[i - 2];
+      const s0 = (a2 >>> 7 | a2 << 25) ^ (a2 >>> 18 | a2 << 14) ^ a2 >>> 3;
+      const s1 = (b2 >>> 17 | b2 << 15) ^ (b2 >>> 19 | b2 << 13) ^ b2 >>> 10;
+      w[i] = w[i - 16] + s0 + w[i - 7] + s1 >>> 0;
+    }
+    let a = h[0], b = h[1], c = h[2], d = h[3], e = h[4], f = h[5], g = h[6], hh = h[7];
+    for (let i = 0; i < 64; i += 1) {
+      const S1 = (e >>> 6 | e << 26) ^ (e >>> 11 | e << 21) ^ (e >>> 25 | e << 7);
+      const ch = e & f ^ ~e & g;
+      const t1 = hh + S1 + ch + K[i] + w[i] >>> 0;
+      const S0 = (a >>> 2 | a << 30) ^ (a >>> 13 | a << 19) ^ (a >>> 22 | a << 10);
+      const maj = a & b ^ a & c ^ b & c;
+      const t2 = S0 + maj >>> 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = d + t1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = t1 + t2 >>> 0;
+    }
+    h[0] = h[0] + a >>> 0;
+    h[1] = h[1] + b >>> 0;
+    h[2] = h[2] + c >>> 0;
+    h[3] = h[3] + d >>> 0;
+    h[4] = h[4] + e >>> 0;
+    h[5] = h[5] + f >>> 0;
+    h[6] = h[6] + g >>> 0;
+    h[7] = h[7] + hh >>> 0;
+  }
+  return Array.from(h, (word) => word.toString(16).padStart(8, "0")).join("");
+}
+function declarationHash(declaration) {
+  return sha256Hex(canonicalJson(declaration));
+}
+
+// src/declare/validate.ts
+var VALUE_TYPES = ["string", "number", "boolean", "object", "array", "document"];
+var WRITE_MODES = ["draft", "entity", "ui", "stream"];
+var APPLY_POLICIES = ["manual", "ask", "auto", "queued"];
+var STREAM_OPS = ["replace", "insert_before", "insert_after", "prepend", "append", "patch"];
+var EXECUTION_MODES = ["python-stream", "nextjs-stream", "browser-realtime", "local-runtime"];
+var READINESS = ["verified", "partial", "stub"];
+var LIVE_SLOTS = ["selection", "on-demand", "errors", "requests"];
+var CLASSIFICATIONS = ["ordinary", "secret", "credential"];
+var STRUCTURED = /* @__PURE__ */ new Set(["object", "array"]);
+function has(list, value) {
+  return typeof value === "string" && list.includes(value);
+}
+function validateDeclarations(declarations, options = {}) {
+  const issues = [];
+  const seenSurfaces = /* @__PURE__ */ new Set();
+  const labelsByClient = /* @__PURE__ */ new Map();
+  for (const d of declarations) {
+    const s = d.surfaceName;
+    const push = (path, sentence, remedy, severity) => issues.push({ surfaceName: s, path, sentence, remedy, ...severity ? { severity } : {} });
+    if (seenSurfaces.has(s)) {
+      push("surfaceName", `Duplicate manifest surfaceName: "${s}" appears more than once.`, "Keep one declaration per surface.");
+    }
+    seenSurfaces.add(s);
+    if (!SURFACE_NAME_RE.test(s)) {
+      push("surfaceName", `Surface "${s}" doesn't match the "<client>/<local>" convention.`, "Rename it to <client>/<local>.");
+    }
+    const prefix = surfaceClientOf(s);
+    if (d.client !== prefix) {
+      push("client", `Surface "${s}" declares client "${String(d.client)}" but its name prefix is "${prefix}" \u2014 they must match.`, `Set client: "${prefix}".`);
+    }
+    if (!has(EXECUTION_MODES, d.executionMode)) {
+      push("executionMode", `Surface "${s}" has invalid executionMode "${String(d.executionMode)}".`, `Use one of ${EXECUTION_MODES.join(" | ")}.`);
+    }
+    if (typeof d.description !== "string") {
+      push("description", `Surface "${s}" has no description.`, 'Add one sentence on what the surface is ("" only where the live row is empty).');
+    }
+    const label = d.label?.trim();
+    if (!label) {
+      push("label", `Surface "${s}" has no canonical label \u2014 label is required.`, "Add the ONE canonical human display name.");
+    } else {
+      const clientLabels = labelsByClient.get(prefix) ?? /* @__PURE__ */ new Map();
+      const clash = clientLabels.get(label.toLowerCase());
+      if (clash && clash !== s) {
+        push("label", `Canonical label "${label}" is used by both "${clash}" and "${s}" \u2014 labels must be unique per client.`, "Give one of them a distinct label.");
+      }
+      clientLabels.set(label.toLowerCase(), s);
+      labelsByClient.set(prefix, clientLabels);
+    }
+    if (!has(READINESS, d.readiness)) {
+      push("readiness", `Surface "${s}" has invalid readiness "${String(d.readiness)}" (expected verified | partial | stub).`, "Set a valid readiness.");
+    } else if (d.readiness !== "verified" && !d.readinessNote?.trim()) {
+      push("readinessNote", `Surface "${s}" is readiness "${d.readiness}" but has no readinessNote \u2014 say what's missing.`, "Add a one-line readinessNote.");
+    }
+    const groupKeys = /* @__PURE__ */ new Set();
+    for (const g of d.groups ?? []) {
+      groupKeys.add(g.key);
+      const reserved = g.key === "general" || g.key === "baseline" || g.key.startsWith("inherited:");
+      if (reserved) continue;
+      if (!DECLARATION_NAME_RE.test(g.key)) push(`groups/${g.key}`, `Surface "${s}" group "${g.key}" doesn't match /^[a-z][a-z0-9_]*$/.`, "Rename the group key to lower_snake_case.");
+      if (g.sortOrder < 0 || g.sortOrder > 899) push(`groups/${g.key}/sortOrder`, `Surface "${s}" group "${g.key}" sortOrder ${g.sortOrder} is outside the curated band 0\u2013899.`, "Use a sortOrder between 0 and 899.");
+      if (!g.label?.trim()) push(`groups/${g.key}/label`, `Surface "${s}" group "${g.key}" has no canonical label.`, "Add a label.");
+    }
+    const seenNamespaces = /* @__PURE__ */ new Set();
+    for (const ns of d.configNamespaces ?? []) {
+      if (seenNamespaces.has(ns.namespace)) push(`configNamespaces/${ns.namespace}`, `Surface "${s}" declares duplicate config namespace "${ns.namespace}".`, "Remove the duplicate.");
+      seenNamespaces.add(ns.namespace);
+      if (options.knownNamespaces && !options.knownNamespaces.has(ns.namespace)) {
+        push(`configNamespaces/${ns.namespace}`, `Surface "${s}" references config namespace "${ns.namespace}" which is not registered.`, "Register the namespace first, or remove the reference.");
+      }
+    }
+    if (d.values.length === 0) {
+      push("values", `Surface "${s}" declares no values.`, "Declare at least one value.");
+      continue;
+    }
+    const seenValues = /* @__PURE__ */ new Set();
+    for (const v of d.values) {
+      const at = `values/${v.name}`;
+      if (seenValues.has(v.name)) push(at, `Surface "${s}" declares duplicate value "${v.name}".`, "Remove the duplicate.");
+      seenValues.add(v.name);
+      if (!DECLARATION_NAME_RE.test(v.name)) push(at, `Surface "${s}" value "${v.name}" doesn't match /^[a-z][a-z0-9_]*$/ \u2014 the DB CHECK constraint will reject this.`, "Rename it to lower_snake_case.");
+      if (!has(VALUE_TYPES, v.valueType)) push(`${at}/valueType`, `Surface "${s}" value "${v.name}" has invalid valueType "${String(v.valueType)}".`, `Use one of ${VALUE_TYPES.join(" | ")}.`);
+      if (typeof v.typicalCharCount !== "number" || v.typicalCharCount < 0) push(`${at}/typicalCharCount`, `Surface "${s}" value "${v.name}" has invalid typicalCharCount.`, "Use a non-negative number.");
+      if (v.sortOrder !== void 0 && (typeof v.sortOrder !== "number" || v.sortOrder < 0)) push(`${at}/sortOrder`, `Surface "${s}" value "${v.name}" has invalid sortOrder.`, "Use a non-negative number.");
+      if (v.groupKey && !groupKeys.has(v.groupKey)) push(`${at}/group`, `Surface "${s}" value "${v.name}" resolved to groupKey "${v.groupKey}" which is missing from the resolved groups list \u2014 registry group synthesis is broken.`, "Fix the registry resolution.");
+      if (v.liveSlot !== void 0 && !has(LIVE_SLOTS, v.liveSlot)) push(`${at}/liveSlot`, `Surface "${s}" value "${v.name}" has invalid liveSlot "${String(v.liveSlot)}".`, `Use one of ${LIVE_SLOTS.join(" | ")}.`);
+      if (v.role !== void 0 && v.role !== "data" && v.role !== "request") push(`${at}/role`, `Surface "${s}" value "${v.name}" has invalid role "${String(v.role)}".`, "Use data | request.");
+      if (v.sensitivity?.classification !== void 0 && !has(CLASSIFICATIONS, v.sensitivity.classification)) push(`${at}/sensitivity/classification`, `Surface "${s}" value "${v.name}" has invalid classification "${String(v.sensitivity.classification)}".`, `Use one of ${CLASSIFICATIONS.join(" | ")}.`);
+    }
+    for (const slot of d.liveSlots ?? []) {
+      if (!has(LIVE_SLOTS, slot)) push("liveSlots", `Surface "${s}" declares unknown live slot "${String(slot)}".`, `Use one of ${LIVE_SLOTS.join(" | ")}.`);
+    }
+    const itemTypeNames = /* @__PURE__ */ new Set();
+    for (const item of d.itemTypes ?? []) {
+      const at = `itemTypes/${item.name}`;
+      if (itemTypeNames.has(item.name)) push(at, `Surface "${s}" declares duplicate item type "${item.name}".`, "Remove the duplicate.");
+      itemTypeNames.add(item.name);
+      if (!DECLARATION_NAME_RE.test(item.name)) push(at, `Surface "${s}" item type "${item.name}" doesn't match /^[a-z][a-z0-9_]*$/.`, "Rename it to lower_snake_case.");
+      if (!item.label?.trim() || !item.description?.trim()) push(at, `Surface "${s}" item type "${item.name}" needs a label and a description.`, "Add both.");
+      const itemValues = new Set(item.values.map((v) => v.name));
+      if (item.identity.length === 0) push(`${at}/identity`, `Surface "${s}" item type "${item.name}" has an empty identity.`, "Name the value(s) that identify one item.");
+      for (const key of item.identity) {
+        if (!itemValues.has(key)) push(`${at}/identity`, `Surface "${s}" item type "${item.name}" identity names "${key}", which is not one of its values.`, "Declare it as an item value.");
+      }
+      for (const t of item.writeTargets ?? []) {
+        if (t.updatesValue && !itemValues.has(t.updatesValue)) push(`${at}/writeTargets/${t.name}`, `Surface "${s}" item type "${item.name}" write target "${t.name}" updatesValue "${t.updatesValue}" which is not an item value.`, "Point it at a declared item value.");
+      }
+    }
+    const seenTargets = /* @__PURE__ */ new Set();
+    const structuredWithoutKind = [];
+    for (const w of d.writeTargets ?? []) {
+      const at = `writeTargets/${w.name}`;
+      if (seenTargets.has(w.name)) push(at, `Surface "${s}" declares duplicate write target "${w.name}".`, "Remove the duplicate.");
+      seenTargets.add(w.name);
+      if (!DECLARATION_NAME_RE.test(w.name)) push(at, `Surface "${s}" write target "${w.name}" doesn't match /^[a-z][a-z0-9_]*$/.`, "Rename it to lower_snake_case.");
+      if (!w.label?.trim() || !w.description?.trim()) push(at, `Surface "${s}" write target "${w.name}" needs a label and a description.`, "Add both.");
+      if (!has(VALUE_TYPES, w.valueType)) push(`${at}/valueType`, `Surface "${s}" write target "${w.name}" has invalid valueType "${String(w.valueType)}".`, `Use one of ${VALUE_TYPES.join(" | ")}.`);
+      if (!has(WRITE_MODES, w.mode)) push(`${at}/mode`, `Surface "${s}" write target "${w.name}" has invalid mode "${String(w.mode)}".`, `Use one of ${WRITE_MODES.join(" | ")}.`);
+      if (w.applyPolicy !== void 0 && !has(APPLY_POLICIES, w.applyPolicy)) push(`${at}/applyPolicy`, `Surface "${s}" write target "${w.name}" has invalid applyPolicy "${String(w.applyPolicy)}".`, `Use one of ${APPLY_POLICIES.join(" | ")}.`);
+      if (w.itemType !== void 0 && !itemTypeNames.has(w.itemType)) push(`${at}/itemType`, `Surface "${s}" write target "${w.name}" names item type "${w.itemType}", which the surface does not declare.`, "Declare the item type or drop itemType.");
+      const readTwinDeclared = w.updatesValue ? seenValues.has(w.updatesValue) : false;
+      if (w.updatesValue && !w.itemType && !readTwinDeclared) push(`${at}/updatesValue`, `Surface "${s}" write target "${w.name}" updatesValue "${w.updatesValue}" which is not a declared value.`, "Point updatesValue at a declared value.");
+      if (w.patchable && !w.updatesValue) push(`${at}/patchable`, `Surface "${s}" write target "${w.name}" is patchable but declares no updatesValue \u2014 an anchored edit has nothing to read.`, "Declare the read twin in updatesValue.");
+      if (w.patchable && w.valueType !== "string" && w.valueType !== "document") push(`${at}/patchable`, `Surface "${s}" write target "${w.name}" is patchable but valueType is "${w.valueType}" (patching is for "string" | "document").`, "Drop patchable or change the value type.");
+      if (w.mode === "stream") {
+        if (!w.streamOps || w.streamOps.length === 0) push(`${at}/streamOps`, `Surface "${s}" write target "${w.name}" is a stream target with no streamOps.`, "List the ops it services.");
+        if (!w.updatesValue) push(`${at}/updatesValue`, `Surface "${s}" write target "${w.name}" is a stream target with no read twin.`, "Declare updatesValue.");
+      } else if (w.streamOps !== void 0) {
+        push(`${at}/streamOps`, `Surface "${s}" write target "${w.name}" lists streamOps but its mode is "${w.mode}".`, 'streamOps belong only to mode "stream".');
+      }
+      for (const op of w.streamOps ?? []) {
+        if (!has(STREAM_OPS, op)) push(`${at}/streamOps`, `Surface "${s}" write target "${w.name}" lists unknown stream op "${String(op)}".`, `Use ${STREAM_OPS.join(" | ")}.`);
+      }
+      if (w.group && !groupKeys.has(w.group)) push(`${at}/group`, `Surface "${s}" write target "${w.name}" references undeclared group "${w.group}".`, "Declare the group or drop it.");
+      if (w.valueKind !== void 0) {
+        if (typeof w.valueKind !== "string" || !w.valueKind.trim()) {
+          push(`${at}/valueKind`, `Surface "${s}" write target "${w.name}" has an empty valueKind.`, "Name a registered kind slug or omit the field.");
+        } else if (options.isKnownKind && !options.isKnownKind(w.valueKind)) {
+          push(`${at}/valueKind`, `Surface "${s}" write target "${w.name}" declares valueKind "${w.valueKind}", which is not a registered active kind.`, "Name a registered kind slug, or register the kind first; never inline a JSON schema.");
+        }
+      } else if (STRUCTURED.has(w.valueType)) {
+        structuredWithoutKind.push(w.name);
+      }
+    }
+    for (const name of structuredWithoutKind) {
+      push(`writeTargets/${name}/valueKind`, `Surface "${s}" structured write target "${name}" declares no valueKind.`, "Name a registered kind slug (the value contract ratchet).", "advisory");
+    }
+    if (!d.skipBaselineValues && options.baselineNames) {
+      const missing = options.baselineNames.filter((name) => !seenValues.has(name));
+      if (missing.length > 0) {
+        push("values", `Surface "${s}" is missing baseline value(s): ${missing.join(", ")}.`, "The registry injects baselines automatically; opt out only with skipBaselineValues.");
+      }
+    }
+  }
+  for (const extension of options.extensions ?? []) {
+    if (!extension.validate) continue;
+    for (const d of declarations) issues.push(...extension.validate(d, { all: declarations }));
+  }
+  return issues;
+}
+function validateLoadedValues(declaration, loaded, options = {}) {
+  const declared = new Set(declaration.values.map((v) => v.name));
+  const ignore = new Set(options.ignore ?? []);
+  const issues = [];
+  for (const key of Object.keys(loaded)) {
+    if (key === "__item" || declared.has(key) || ignore.has(key)) continue;
+    issues.push({
+      surfaceName: declaration.surfaceName,
+      path: `values/${key}`,
+      sentence: `Surface "${declaration.surfaceName}" loaded a value "${key}" it never declared.`,
+      remedy: `Declare "${key}" in the surface's values, or stop emitting it.`
+    });
+  }
+  const item = loaded.__item;
+  if (item && typeof item === "object") {
+    const type = declaration.itemTypes?.find((t) => t.name === item.itemType);
+    if (!type) {
+      issues.push({
+        surfaceName: declaration.surfaceName,
+        path: "__item/itemType",
+        sentence: `Surface "${declaration.surfaceName}" loaded an item of type "${String(item.itemType)}" it never declared.`,
+        remedy: "Declare the item type, or stop emitting the item."
+      });
+    } else if (item.values && typeof item.values === "object") {
+      const itemDeclared = new Set(type.values.map((v) => v.name));
+      for (const key of Object.keys(item.values)) {
+        if (itemDeclared.has(key)) continue;
+        issues.push({
+          surfaceName: declaration.surfaceName,
+          path: `__item/${type.name}.${key}`,
+          sentence: `Surface "${declaration.surfaceName}" loaded item value "${type.name}.${key}" it never declared.`,
+          remedy: `Declare "${key}" on item type "${type.name}".`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function findOrphanRows(rowNames, declaredNames, retired = []) {
+  const owned = new Set(declaredNames);
+  const archived = new Set(retired);
+  return rowNames.filter((name) => !owned.has(name) && !archived.has(name)).sort();
+}
+
+// src/declare/registry.ts
+var RESERVED_GROUP_KEYS = {
+  general: "general",
+  baseline: "baseline",
+  inheritedPrefix: "inherited:"
+};
+var GENERAL_GROUP_ORDER = 850;
+var INHERITED_GROUP_ORDER_BASE = 9e3;
+var BASELINE_GROUP_ORDER = 9900;
+var DEFAULT_MAX_INHERITANCE_DEPTH = 3;
+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
+  };
+}
+function createDeclarationRegistry(options = {}) {
+  const baselineValues = options.baselineValues ?? [];
+  const baselineNames = new Set(baselineValues.map((v) => v.name));
+  const reservedValues = new Set(options.reservedValueNames ?? []);
+  const reservedTargets = new Set(options.reservedWriteTargetNames ?? []);
+  const maxDepth = options.maxInheritanceDepth ?? DEFAULT_MAX_INHERITANCE_DEPTH;
+  const declarations = [];
+  const index = /* @__PURE__ */ new Map();
+  const extensionList = [];
+  let resolvedCache = null;
+  let resolvedIndex = /* @__PURE__ */ new Map();
+  function ancestry(surfaceName) {
+    const chain = [];
+    const seen = /* @__PURE__ */ new Set([surfaceName]);
+    let current = index.get(surfaceName)?.inheritsFrom;
+    while (current) {
+      if (seen.has(current)) {
+        throw new Error(
+          `[surfaces] inheritsFrom CYCLE detected at "${current}" (from "${surfaceName}"). Fix the manifest chain: ${[...seen].join(" \u2192 ")} \u2192 ${current}`
+        );
+      }
+      const parent = index.get(current);
+      if (!parent) {
+        throw new Error(
+          `[surfaces] "${surfaceName}" inheritsFrom unknown surface "${current}" \u2014 the parent must be a registered declaration`
+        );
+      }
+      seen.add(current);
+      chain.unshift(current);
+      if (chain.length > maxDepth) {
+        throw new Error(
+          `[surfaces] inheritance chain for "${surfaceName}" exceeds depth ${maxDepth}: ` + chain.join(" \u2192 ")
+        );
+      }
+      current = parent.inheritsFrom;
+    }
+    return chain;
+  }
+  function groupKeyFor(value, provenance) {
+    if (provenance.kind === "own" && value.group) return value.group;
+    if (baselineNames.has(value.name)) return RESERVED_GROUP_KEYS.baseline;
+    if (provenance.kind === "inherited") return `${RESERVED_GROUP_KEYS.inheritedPrefix}${provenance.from}`;
+    if (provenance.kind === "baseline") return RESERVED_GROUP_KEYS.baseline;
+    return RESERVED_GROUP_KEYS.general;
+  }
+  function resolve(declaration) {
+    const chain = ancestry(declaration.surfaceName);
+    const lineage = [
+      ...chain.map((name) => {
+        const layer = index.get(name);
+        if (!layer) throw new Error(`[surfaces] missing inherited declaration "${name}"`);
+        return { layer, from: name };
+      }),
+      { layer: declaration, from: null }
+    ];
+    const curatedKeys = /* @__PURE__ */ new Set();
+    for (const group of declaration.groups ?? []) {
+      if (group.key === RESERVED_GROUP_KEYS.general || group.key === RESERVED_GROUP_KEYS.baseline || group.key.startsWith(RESERVED_GROUP_KEYS.inheritedPrefix)) {
+        throw new Error(
+          `[surfaces] "${declaration.surfaceName}" declares reserved group key "${group.key}" \u2014 general/baseline/inherited:* are synthesized by the registry`
+        );
+      }
+      if (curatedKeys.has(group.key)) {
+        throw new Error(`[surfaces] "${declaration.surfaceName}" declares duplicate group key "${group.key}"`);
+      }
+      curatedKeys.add(group.key);
+    }
+    for (const value of declaration.values) {
+      if (reservedValues.has(value.name)) {
+        throw new Error(
+          `[surfaces] "${declaration.surfaceName}" declares value "${value.name}" \u2014 that name is written by the platform; choose another name`
+        );
+      }
+      if (value.group && !curatedKeys.has(value.group)) {
+        throw new Error(
+          `[surfaces] "${declaration.surfaceName}" value "${value.name}" references undeclared group "${value.group}" \u2014 declare it in the manifest's \`groups\``
+        );
+      }
+    }
+    for (const target of declaration.writeTargets ?? []) {
+      if (reservedTargets.has(target.name)) {
+        throw new Error(
+          `[surfaces] "${declaration.surfaceName}" declares write target "${target.name}" \u2014 that name is written by the platform; choose another name`
+        );
+      }
+    }
+    const valuesByName = /* @__PURE__ */ new Map();
+    const inheritedLists = /* @__PURE__ */ new Map();
+    const coreLists = [
+      { field: "configNamespaces", identity: (entry) => entry.namespace },
+      {
+        field: "evidenceSources",
+        identity: (entry) => `${entry.kind}:${entry.idValue}`
+      }
+    ];
+    const lists = [...coreLists, ...extensionList.flatMap((extension) => extension.inheritedLists ?? [])];
+    for (const { layer, from } of lineage) {
+      for (const value of layer.values) {
+        const provenance = from ? { kind: "inherited", from } : { kind: "own" };
+        valuesByName.set(value.name, {
+          ...value,
+          provenance,
+          groupKey: groupKeyFor(value, provenance),
+          resolvedSensitivity: resolveSensitivity(value)
+        });
+      }
+      for (const list of lists) {
+        const entries = layer[list.field];
+        if (!Array.isArray(entries)) continue;
+        const byIdentity = inheritedLists.get(list.field) ?? /* @__PURE__ */ new Map();
+        for (const entry of entries) byIdentity.set(list.identity(entry), entry);
+        inheritedLists.set(list.field, byIdentity);
+      }
+    }
+    if (!declaration.skipBaselineValues) {
+      for (const baseline of baselineValues) {
+        if (valuesByName.has(baseline.name)) continue;
+        valuesByName.set(baseline.name, {
+          ...baseline,
+          provenance: { kind: "baseline" },
+          groupKey: RESERVED_GROUP_KEYS.baseline,
+          resolvedSensitivity: resolveSensitivity(baseline)
+        });
+      }
+    }
+    const usedGroupKeys = new Set(Array.from(valuesByName.values(), (value) => value.groupKey));
+    const groups = [...declaration.groups ?? []];
+    if (usedGroupKeys.has(RESERVED_GROUP_KEYS.general)) {
+      groups.push({ key: RESERVED_GROUP_KEYS.general, label: "General", sortOrder: GENERAL_GROUP_ORDER });
+    }
+    for (let i = chain.length - 1, distance = 0; i >= 0; i -= 1, distance += 1) {
+      const parentName = chain[i];
+      const key = `${RESERVED_GROUP_KEYS.inheritedPrefix}${parentName}`;
+      if (!usedGroupKeys.has(key)) continue;
+      const parentLabel = index.get(parentName)?.label ?? parentName;
+      groups.push({
+        key,
+        label: `Inherited from ${parentLabel}`,
+        sortOrder: INHERITED_GROUP_ORDER_BASE + distance * 10
+      });
+    }
+    if (usedGroupKeys.has(RESERVED_GROUP_KEYS.baseline)) {
+      groups.push({ key: RESERVED_GROUP_KEYS.baseline, label: "Generic baselines", sortOrder: BASELINE_GROUP_ORDER });
+    }
+    groups.sort((a, b) => a.sortOrder - b.sortOrder);
+    const groupOrder = new Map(groups.map((group) => [group.key, group.sortOrder]));
+    const values = Array.from(valuesByName.values()).sort((a, b) => {
+      const ga = groupOrder.get(a.groupKey) ?? GENERAL_GROUP_ORDER;
+      const gb = groupOrder.get(b.groupKey) ?? GENERAL_GROUP_ORDER;
+      if (ga !== gb) return ga - gb;
+      return (a.sortOrder ?? 1e3) - (b.sortOrder ?? 1e3);
+    });
+    const merged = {};
+    for (const [field, byIdentity] of inheritedLists) {
+      if (byIdentity.size > 0) merged[field] = Array.from(byIdentity.values());
+    }
+    return {
+      ...declaration,
+      values,
+      groups,
+      ...merged,
+      contentHash: declarationHash(declaration)
+    };
+  }
+  function resolvedAll() {
+    if (!resolvedCache) {
+      resolvedCache = declarations.map(resolve);
+      resolvedIndex = new Map(resolvedCache.map((entry) => [entry.surfaceName, entry]));
+    }
+    return resolvedCache;
+  }
+  const registry = {
+    register(declaration) {
+      if (index.has(declaration.surfaceName)) {
+        throw new Error(`[surfaces] "${declaration.surfaceName}" is declared twice \u2014 one surface, one declaration`);
+      }
+      declarations.push(declaration);
+      index.set(declaration.surfaceName, declaration);
+      resolvedCache = null;
+    },
+    registerExtension(extension) {
+      if (extensionList.some((existing) => existing.key === extension.key)) {
+        throw new Error(`[surfaces] declaration extension "${extension.key}" is registered twice`);
+      }
+      extensionList.push(extension);
+      resolvedCache = null;
+    },
+    extensions: () => extensionList,
+    raw: () => declarations,
+    getRaw: (surfaceName) => index.get(surfaceName),
+    ancestry,
+    children: (surfaceName) => declarations.filter((d) => d.inheritsFrom === surfaceName).map((d) => d.surfaceName),
+    all: () => resolvedAll(),
+    get(surfaceName) {
+      resolvedAll();
+      return resolvedIndex.get(surfaceName);
+    },
+    validate: (validateOptions) => validateDeclarations(resolvedAll(), {
+      ...validateOptions,
+      extensions: [...validateOptions?.extensions ?? [], ...extensionList],
+      baselineNames: validateOptions?.baselineNames ?? [...baselineNames]
+    })
+  };
+  return registry;
+}
+export {
+  APPLY_POLICIES,
+  BASELINE_GROUP_ORDER,
+  CLASSIFICATIONS,
+  DECLARATION_NAME_RE,
+  DEFAULT_MAX_INHERITANCE_DEPTH,
+  DEFAULT_SENSITIVITY,
+  EXECUTION_MODES,
+  GENERAL_GROUP_ORDER,
+  INHERITED_GROUP_ORDER_BASE,
+  LIVE_SLOTS,
+  QUALIFIED_VALUE_KEY_RE,
+  READINESS,
+  RESERVED_GROUP_KEYS,
+  STREAM_OPS,
+  SURFACE_NAME_RE,
+  VALUE_TYPES,
+  WRITE_MODES,
+  canonicalJson,
+  createDeclarationRegistry,
+  declarationHash,
+  findOrphanRows,
+  parseQualifiedValueKey,
+  qualifyValueKey,
+  resolveSensitivity,
+  sha256Hex,
+  surfaceClientOf,
+  validateDeclarations,
+  validateLoadedValues
+};
+//# sourceMappingURL=declare.js.map