@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

package/dist/domain/describe/chunk-ZVXBGP7Y.js

@@ -0,0 +1,424 @@
+// src/build/spec/domain/model/ManifestGrammar.ts
+function resolveLocalizedText(value, preferred, canonical2) {
+  if (value == null) return null;
+  if (typeof value === "string") return value;
+  if (Object.prototype.hasOwnProperty.call(value, preferred)) {
+    return value[preferred];
+  }
+  if (canonical2 && Object.prototype.hasOwnProperty.call(value, canonical2)) {
+    return value[canonical2];
+  }
+  const firstKey = Object.keys(value)[0];
+  return firstKey !== void 0 ? value[firstKey] : null;
+}
+var INPUT_RULE_KEYWORDS = ["dependentRequired", "anyOf", "if", "then", "else"];
+
+// src/build/spec/domain/service/RootRefChain.ts
+function lookupLocalRef(root, ref) {
+  if (typeof ref !== "string" || !ref.startsWith("#/")) return void 0;
+  let value = root;
+  try {
+    for (const key of decodeURIComponent(ref.slice(2)).split("/").map((key2) => key2.replace(/~1/g, "/").replace(/~0/g, "~"))) value = value && typeof value === "object" && Object.hasOwn(value, key) ? value[key] : void 0;
+  } catch {
+    return void 0;
+  }
+  return value && typeof value === "object" ? value : void 0;
+}
+function rootRefChain(input) {
+  const chain = [];
+  for (let schema = input; schema !== void 0; schema = lookupLocalRef(input, schema.$ref)) {
+    if (chain.includes(schema)) return void 0;
+    chain.push(schema);
+    if (schema.$ref === void 0) return chain;
+  }
+  return void 0;
+}
+
+// src/build/spec/domain/service/McpToolNaming.ts
+function mcpToolNameSegment(name) {
+  return name.toLowerCase().replace(/-/g, "_");
+}
+function toolTitle(name) {
+  const words = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_.\s]+/g, " ").trim().toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+var viewAnnotations = { readOnlyHint: true, destructiveHint: false };
+function procedureAnnotations(p) {
+  const readOnlyHint = p.mcp?.readOnlyHint ?? false;
+  return { readOnlyHint, destructiveHint: !readOnlyHint && ("ref" in p.handler || overwrites(p.handler.sql.stmts)), ...p.mcp };
+}
+var overwrites = (node) => !!node && typeof node === "object" && ("DeleteStmt" in node || "UpdateStmt" in node || node.onConflictClause?.action === "ONCONFLICT_UPDATE" || Object.values(node).some(overwrites));
+function mcpTools(plan, surface, locale = "en") {
+  const text = (t) => resolveLocalizedText(t, locale, "en") ?? void 0;
+  const tools = /* @__PURE__ */ new Map();
+  const add = (tool) => {
+    const prior = tools.get(tool.name);
+    if (prior && (prior.kind !== tool.kind || prior.source !== tool.source)) throw new TypeError(`MCP tool '${tool.name}' comes from both '${prior.source}' and '${tool.source}'.`);
+    tools.set(tool.name, tool);
+  };
+  for (const t of Object.values(plan.triggers)) {
+    if (t.source.kind !== "mcp" || t.source.surface !== surface) continue;
+    const p = plan.procedures[t.procedure];
+    const title = text(p.title);
+    add({
+      name: mcpToolNameSegment(t.procedure),
+      kind: "procedure",
+      source: t.procedure,
+      title: title ?? toolTitle(t.procedure),
+      description: text(p.description) ?? title ?? t.procedure,
+      inputSchema: p.input,
+      // structuredContent must be an object
+      ...p.output.type === "object" ? { outputSchema: p.output } : {},
+      annotations: procedureAnnotations(p),
+      requires: p.requires
+    });
+  }
+  for (const [name, v] of Object.entries(plan.views)) {
+    if (v.surface !== surface) continue;
+    const chain = (v.input ? rootRefChain(v.input) ?? [v.input] : []).reverse();
+    const props = Object.assign({}, ...chain.map((s) => s.properties ?? {}));
+    const required = [...new Set(chain.flatMap((s) => s.required ?? []))];
+    if ("limit" in props || "cursor" in props) throw new TypeError(`View '${name}' declares an input named limit or cursor; the MCP tool reserves both for paging.`);
+    const rules = chain.map((s) => Object.fromEntries(INPUT_RULE_KEYWORDS.flatMap((k) => s[k] === void 0 ? [] : [[k, s[k]]]))).filter((r) => Object.keys(r).length);
+    const defs = v.input ? referencedDefs(v.input, props) : {};
+    const title = text(v.title);
+    add({
+      name: mcpToolNameSegment(name),
+      kind: "view",
+      source: name,
+      title: title ?? toolTitle(name),
+      description: text(v.description) ?? title ?? name,
+      inputSchema: {
+        type: "object",
+        properties: { ...props, limit: { type: "integer", minimum: 1, maximum: 500 }, cursor: { type: "string" } },
+        ...required.length ? { required } : {},
+        ...rules.length > 1 ? { allOf: rules } : rules[0],
+        ...Object.keys(defs).length ? { $defs: defs } : {}
+      },
+      annotations: viewAnnotations,
+      requires: v.requires
+    });
+  }
+  return [...tools.values()];
+}
+function referencedDefs(root, node, found = {}) {
+  if (!node || typeof node !== "object") return found;
+  const ref = node.$ref, [head, segment] = typeof ref === "string" && ref.startsWith("#/") ? decoded(ref.slice(2)).split("/") : [];
+  const key = head === "$defs" ? segment?.replace(/~1/g, "/").replace(/~0/g, "~") : void 0;
+  if (key !== void 0 && !Object.hasOwn(found, key) && root.$defs && Object.hasOwn(root.$defs, key)) {
+    found[key] = root.$defs[key];
+    referencedDefs(root, found[key], found);
+  }
+  for (const child of Object.values(node)) referencedDefs(root, child, found);
+  return found;
+}
+var decoded = (pointer) => {
+  try {
+    return decodeURIComponent(pointer);
+  } catch {
+    return "";
+  }
+};
+
+// src/build/spec/domain/service/PlanFingerprint.ts
+function canonical(v) {
+  if (Array.isArray(v)) return `[${v.map(canonical).join(",")}]`;
+  if (v && typeof v === "object")
+    return `{${Object.keys(v).sort().filter((k) => v[k] !== void 0).map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(",")}}`;
+  return JSON.stringify(v) ?? "null";
+}
+
+// src/domain/generated-tools.ts
+var publishingTransitions = [["publish", ["draft"], "published"], ["unpublish", ["published", "archived"], "draft"], ["archive", ["draft", "published"], "archived"]];
+var publishingInput = { type: "object", properties: { id: { type: "string", minLength: 1 }, expectedVersion: { type: "integer", minimum: 1 } }, required: ["id", "expectedVersion"], additionalProperties: false };
+function mediaDefinitions() {
+  const define = (name, description, inputSchema, action, readOnlyHint = false) => ({ name, description, inputSchema, action, annotations: { readOnlyHint, destructiveHint: action === "delete", openWorldHint: true } });
+  const string = { type: "string" };
+  const texts = { alt: { type: "string", maxLength: 1e3 }, caption: { type: "string", maxLength: 1e3 } };
+  const input = (properties, required = []) => ({ type: "object", properties, required, additionalProperties: false });
+  return [
+    define("get_media_upload_policy", "Read declared image purpose MIME slots and byte caps before preparing variants or requesting an upload. Optimization runs locally, never in the host.", input({}), "policy", true),
+    define("create_media_upload", "Create short-lived PUT capabilities for image variants. Read site media purpose policy first; optimize images locally. Obtain attachment bytes yourself, then PUT each variant with its requiredHeaders and call commit_media_upload. Never store upload URLs as published images or ask the user to run terminal commands.", input({ filename: { type: "string", maxLength: 255 }, purpose: string, variants: { type: "array", minItems: 1, items: input({ mimeType: string, byteSize: { type: "integer", minimum: 1 }, role: { type: "string", enum: ["primary", "alternate", "fallback"] } }, ["mimeType", "byteSize", "role"]) }, ...texts }, ["filename", "purpose", "variants"]), "create"),
+    define("commit_media_upload", "Verify all uploaded variants and commit one permanent media asset. Store the returned asset id in fields referencing media_assets.id, never a temporary upload URL. Unknown or expired upload groups require a new create_media_upload.", input({ uploadGroupId: string, ...texts }, ["uploadGroupId"]), "commit"),
+    define("list_media_assets", "List committed image assets, newest first, with their permanent variants and alt/caption. Search matches id, alt or caption; reuse only a returned cursor.", input({ limit: { type: "integer", minimum: 1, maximum: 500 }, cursor: string, search: string }), "list", true),
+    define("get_media_asset", "Read one committed media asset and its permanent variant URLs.", input({ id: string }, ["id"]), "get", true),
+    define("update_media_asset", "Update committed asset alt or caption; omitted fields remain unchanged and empty strings clear text.", input({ id: string, ...texts }, ["id"]), "update"),
+    define("delete_media_asset", "Delete an asset's objects and library record. Check application references first. A partial failure can be retried using the same id.", input({ id: string }, ["id"]), "delete")
+  ];
+}
+
+// src/domain/describe/targets.ts
+function inspectSql(value) {
+  const schemas = /* @__PURE__ */ new Set(), readSchemas = /* @__PURE__ */ new Set();
+  const writes = [];
+  let readOnly = true;
+  const walk = (v) => {
+    if (!v || typeof v !== "object") return;
+    const n = v;
+    if (n.RangeVar?.mantle === "table") {
+      schemas.add(n.RangeVar.relname.toLowerCase());
+      readSchemas.add(n.RangeVar.relname.toLowerCase());
+    }
+    for (const kind of ["InsertStmt", "UpdateStmt", "DeleteStmt"]) if (n[kind]) {
+      readOnly = false;
+      if (n[kind].relation?.relname) writes.push({ schema: n[kind].relation.relname.toLowerCase(), operation: kind === "InsertStmt" ? "create" : kind === "UpdateStmt" ? "update" : "delete" });
+      if (n[kind].relation?.relname) {
+        schemas.add(n[kind].relation.relname.toLowerCase());
+        if (kind !== "InsertStmt") readSchemas.add(n[kind].relation.relname.toLowerCase());
+      }
+    }
+    Object.values(n).forEach(walk);
+  };
+  walk(value);
+  return { schemas: [...schemas].sort(), readSchemas: [...readSchemas].sort(), readOnly, writes };
+}
+function mergeRestrict(policies, conjunctive) {
+  return Object.fromEntries([...new Set(policies.flatMap((p) => Object.keys(p)))].sort().map((schema) => {
+    const rows = policies.map((p) => p[schema] ?? { terms: [] });
+    const terms = [...new Map(rows.flatMap((p) => p.terms).map((t) => [canonical(t), t])).values()].filter((t) => conjunctive || rows.every((p) => p.terms.some((v) => canonical(v) === canonical(t))));
+    const owner = rows.find((p) => p.owner)?.owner;
+    return [schema, { ...owner && (conjunctive || rows.every((p) => p.owner === owner)) ? { owner } : {}, terms }];
+  }));
+}
+function inspectBehavior(plan, ir, opaque, requires, restrict, writes) {
+  const inspected = inspectSql(ir);
+  if (writes) {
+    inspected.writes = [...writes];
+    inspected.schemas.push(...writes.map((w) => w.schema));
+    inspected.readSchemas.push(...writes.filter((w) => w.operation !== "create").map((w) => w.schema));
+  }
+  const dependencies = [], policies = [restrict ?? {}];
+  const procedures = /* @__PURE__ */ new Set(), hooks = /* @__PURE__ */ new Set();
+  const visit = (name) => {
+    if (procedures.has(name)) return;
+    procedures.add(name);
+    const p = plan.procedures[name];
+    if (!p) throw new TypeError(`Unknown dependency '${name}'.`);
+    dependencies.push({ procedure: name, declaration: p });
+    policies.push(p.restrict ?? {});
+    opaque ||= "ref" in p.handler;
+    const g = inspectSql("sql" in p.handler ? p.handler.sql.stmts : void 0);
+    inspected.schemas.push(...g.schemas);
+    inspected.readSchemas.push(...g.readSchemas);
+    inspected.writes.push(...g.writes);
+    inspected.readOnly &&= g.readOnly;
+    if (p.requires?.guard) visit(p.requires.guard.procedure);
+  };
+  if (requires?.guard) visit(requires.guard.procedure);
+  for (; ; ) {
+    const before = hooks.size;
+    for (const [id, t] of Object.entries(plan.triggers).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+      if (t.source.kind !== "lifecycle" || hooks.has(id)) continue;
+      const source = t.source;
+      if (!opaque && !inspected.writes.some((w) => w.schema === source.schema.toLowerCase() && source.on.some((on) => on.endsWith(`_${w.operation}`)))) continue;
+      hooks.add(id);
+      dependencies.push({ trigger: id, source });
+      visit(t.procedure);
+    }
+    if (hooks.size === before) break;
+  }
+  const related = (names) => {
+    const all = new Set(opaque ? Object.keys(plan.schemas) : names);
+    for (const name of all) {
+      const parent = plan.schemas[name]?.translates?.parent.toLowerCase();
+      if (parent) all.add(parent);
+    }
+    return [...all].sort();
+  };
+  return {
+    ...inspected,
+    schemas: related(inspected.schemas),
+    readSchemas: related(inspected.readSchemas),
+    opaque,
+    restrict: mergeRestrict(policies, true),
+    dependencies
+  };
+}
+var objectInput = { type: "object", properties: {} };
+var pathTemplate = (path) => path.replace(/\{([^}]+)\}/g, ":$1");
+var adminRoutes = [
+  "GET /me",
+  "GET /site",
+  "GET /collections",
+  "GET /views-manifest",
+  "GET /operations",
+  "GET /webmcp",
+  "POST /webmcp/:tool",
+  "GET /bootstrap",
+  "GET /views/:name/export",
+  "GET /views/:name",
+  "GET /view-batch",
+  "GET /developer/views/:name",
+  "POST /operations/:name",
+  "GET /developer-console",
+  "GET /collections/:name/statistics",
+  "GET /entries",
+  "GET /entries/export",
+  "GET /entries/:id",
+  "POST /entries",
+  "PATCH /entries/:id",
+  "POST /entries/:id/publish",
+  "POST /entries/:id/unpublish",
+  "POST /entries/:id/archive",
+  "DELETE /entries/:id",
+  "GET /site-settings",
+  "PATCH /site-settings",
+  "POST /media/uploads",
+  "POST /media/uploads/:groupId/commit",
+  "GET /media",
+  "GET /media/:id",
+  "PATCH /media/:id",
+  "DELETE /media/:id",
+  "GET /admin",
+  "GET /members",
+  "PATCH /admin/:id/role",
+  "POST /admin/invitations",
+  "DELETE /admin/invitations/:id"
+];
+function targetDefinitions(plan) {
+  const out = [];
+  const tools = [...mcpTools(plan, "public"), ...mcpTools(plan, "admin")];
+  for (const [kind, entries] of [["view", plan.views], ["procedure", plan.procedures]]) {
+    for (const [name, p] of Object.entries(entries).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+      const view = kind === "view" ? plan.views[name] : void 0;
+      const proc = kind === "procedure" ? plan.procedures[name] : void 0;
+      const ir = view?.stmts ?? (proc && "sql" in proc.handler ? proc.handler.sql.stmts : void 0);
+      const inspected = inspectBehavior(plan, ir, !!proc && "ref" in proc.handler, p.requires, p.restrict);
+      const tool = tools.find((t) => t.kind === kind && t.source === name);
+      const title = resolveLocalizedText(p.title, "en", "en") ?? name;
+      const triggers = Object.entries(plan.triggers).filter(([, t]) => kind === "procedure" && t.procedure === name).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([id, t]) => ({ id, source: t.source }));
+      const surfaces = [.../* @__PURE__ */ new Set([
+        ...view ? [view.surface, "admin", ...view.surface === "public" ? ["rest"] : []] : [],
+        ...triggers.map((t) => t.source.kind === "mcp" ? t.source.surface : t.source.kind === "http" ? "rest" : t.source.kind)
+      ])].sort();
+      if (!surfaces.length) surfaces.push("internal");
+      out.push({
+        id: `${kind}:${name}`,
+        name: tool?.name ?? mcpToolNameSegment(name),
+        kind,
+        surface: view?.surface ?? (surfaces.includes("public") || surfaces.includes("rest") ? "public" : surfaces.includes("admin") ? "admin" : "internal"),
+        surfaces,
+        triggers,
+        title,
+        description: resolveLocalizedText(p.description, "en", "en") ?? title,
+        inputSchema: tool?.inputSchema ?? view?.input ?? proc?.input ?? objectInput,
+        annotations: tool?.annotations ?? {},
+        requires: p.requires,
+        restrict: inspected.restrict,
+        schemas: inspected.schemas,
+        readSchemas: inspected.readSchemas,
+        readOnly: !inspected.opaque && inspected.readOnly,
+        opaque: inspected.opaque,
+        trustedOnly: !!proc?.trustedOnly,
+        variants: [],
+        behavior: { declaration: p, dependencies: inspected.dependencies }
+      });
+    }
+  }
+  const addRoute = (id, dependencies, inputSchema = objectInput) => {
+    const admin = id.startsWith("admin:");
+    out.push({
+      id,
+      name: id.replace(/[^a-zA-Z0-9_-]/g, "_"),
+      title: id,
+      description: id,
+      kind: admin ? "admin" : "rest",
+      surface: admin ? "admin" : "public",
+      surfaces: [admin ? "admin" : "rest"],
+      triggers: dependencies.flatMap((d) => d.triggers),
+      inputSchema,
+      annotations: {},
+      requires: admin ? { auth: { all: ["ctx.admin"] } } : dependencies[0]?.requires,
+      restrict: mergeRestrict(dependencies.map((d) => d.restrict), false),
+      schemas: [...new Set(dependencies.flatMap((d) => d.schemas))].sort(),
+      readSchemas: [...new Set(dependencies.flatMap((d) => d.readSchemas))].sort(),
+      readOnly: dependencies.length > 0 && dependencies.every((d) => d.readOnly) && (!admin || id.startsWith("admin:GET ") || id === "admin:POST /operations/:name" || id === "admin:POST /webmcp/:tool"),
+      opaque: dependencies.some((d) => d.opaque),
+      trustedOnly: dependencies.some((d) => d.trustedOnly),
+      variants: dependencies,
+      behavior: dependencies.map((d) => ({ id: d.id, behavior: d.behavior, surfaces: d.surfaces, triggers: d.triggers, input: d.inputSchema, requires: d.requires, restrict: d.restrict, trustedOnly: d.trustedOnly }))
+    });
+  };
+  const declarations = [...out];
+  const adminOperations = new Set(mcpTools(plan, "admin").filter((t) => t.kind === "procedure").map((t) => `procedure:${t.source}`));
+  for (const d of declarations) if (d.kind === "view" && d.surfaces.includes("public")) addRoute(`rest:GET /api/views/${d.id.slice(5)}`, [d], d.inputSchema);
+  for (const [, t] of Object.entries(plan.triggers).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) if (t.source.kind === "http") {
+    const d = declarations.find((d2) => d2.id === `procedure:${t.procedure}`);
+    addRoute(`rest:${t.source.method} ${pathTemplate(t.source.path)}`, [d], d.inputSchema);
+  }
+  const generated = [];
+  for (const [schema, s] of Object.entries(plan.schemas).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) if (s.publishing) for (const [verb, from, to] of publishingTransitions) {
+    addRoute(`procedure:${s.name}.${verb}`, [], publishingInput);
+    const d = out.at(-1);
+    const inspected = inspectBehavior(plan, void 0, false, void 0, void 0, [{ schema, operation: verb === "publish" ? "publish" : "update" }]);
+    Object.assign(d, {
+      kind: "procedure",
+      name: mcpToolNameSegment(`${verb}_${s.name}`),
+      surface: "admin",
+      surfaces: ["admin"],
+      requires: { auth: { all: ["ctx.admin"] } },
+      schemas: [.../* @__PURE__ */ new Set([schema, ...inspected.schemas])].sort(),
+      readSchemas: [.../* @__PURE__ */ new Set([schema, ...inspected.readSchemas])].sort(),
+      opaque: inspected.opaque,
+      behavior: { schema, verb, from, to, dependencies: inspected.dependencies }
+    });
+    generated.push(d);
+  }
+  for (const tool of mediaDefinitions()) {
+    addRoute(`admin:tool:${tool.name}`, [], tool.inputSchema);
+    const d = out.at(-1);
+    Object.assign(d, { name: tool.name, readOnly: tool.annotations.readOnlyHint, opaque: !tool.annotations.readOnlyHint, annotations: tool.annotations, behavior: { tool, schemas: plan.schemas } });
+    generated.push(d);
+  }
+  for (const route of adminRoutes) {
+    const deps = route.includes("/views/:") || route === "GET /view-batch" ? declarations.filter((d2) => d2.kind === "view" && (route.includes("/developer/") || plan.views[d2.id.slice(5)]?.surface === "admin")) : route.includes("/operations/:") ? declarations.filter((d2) => adminOperations.has(d2.id)) : route === "POST /webmcp/:tool" ? declarations.filter((d2) => mcpTools(plan, "admin").some((t) => `${t.kind}:${t.source}` === d2.id)).concat(generated) : [];
+    const generic = route.includes("/entries") || route.includes("/statistics") || route === "GET /bootstrap";
+    addRoute(`admin:${route}`, deps, deps.length && route !== "GET /view-batch" ? { ...objectInput, anyOf: deps.map((d2) => ({ type: "object", properties: { [route.includes("/webmcp/") ? "tool" : "name"]: { type: "string", const: route.includes("/webmcp/") ? d2.name : d2.id.slice(d2.kind === "view" ? 5 : 10) } } })) } : objectInput);
+    const d = out.at(-1);
+    if (generic) {
+      const operation = route === "POST /entries" ? "create" : route === "DELETE /entries/:id" ? "delete" : route.startsWith("GET ") ? void 0 : route.endsWith("/publish") ? "publish" : "update";
+      const inspected = inspectBehavior(plan, void 0, false, void 0, void 0, operation ? Object.keys(plan.schemas).map((schema) => ({ schema, operation })) : []);
+      d.schemas = Object.keys(plan.schemas).sort();
+      d.readSchemas = d.schemas;
+      d.opaque = inspected.opaque;
+      d.behavior = { schemas: plan.schemas, dependencies: inspected.dependencies };
+    }
+  }
+  return [...new Map(out.map((d) => [d.id, d])).values()].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+
+// src/domain/describe/target-hash.ts
+async function hash(value) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical(value)));
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function hashDefinition(plan, d) {
+  return hash({
+    id: d.id,
+    surfaces: d.surfaces,
+    triggers: d.triggers,
+    behavior: d.behavior,
+    input: d.inputSchema,
+    requires: d.requires,
+    restrict: d.restrict,
+    dialect: plan.dialect,
+    schemas: Object.fromEntries(d.schemas.map((name) => [name, plan.schemas[name]])),
+    userFields: plan.access?.userFields,
+    readOnly: d.readOnly,
+    opaque: d.opaque,
+    trustedOnly: d.trustedOnly
+  });
+}
+async function targetHash(plan, targetId) {
+  const target = targetDefinitions(plan).find((d) => d.id === targetId);
+  if (!target) throw new TypeError(`Unknown target '${targetId}'.`);
+  return hashDefinition(plan, target);
+}
+
+export {
+  canonical,
+  targetDefinitions,
+  hash,
+  hashDefinition,
+  targetHash
+};

package/dist/domain/describe/index.d.ts

@@ -0,0 +1,58 @@
+import type { RuntimePlan } from "../../build/compiler.js";
+import type { PlanRestrict } from "../../build/spec/domain/model/RuntimePlan.js";
+import type { UserFieldSpec } from "../../build/spec/domain/model/UserFields.js";
+import { type TargetDefinition } from "./targets.js";
+export { targetHash } from "./target-hash.js";
+export interface DescribeTarget {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: import("../../build/compiler.js").JsonSchema;
+    annotations: import("../../build/spec/domain/model/ManifestGrammar.js").ProcedureMcpAnnotations;
+    _meta: {
+        surfaces: string[];
+        triggers: TargetDefinition["triggers"];
+        id: string;
+        targetHash: string;
+        readOnly: boolean;
+        scope: PlanRestrict;
+        restrict: PlanRestrict;
+        opaque: boolean;
+        unscopedReads: boolean;
+        trustedOnly: boolean;
+        variants: {
+            id: string;
+            scope: PlanRestrict;
+            restrict: PlanRestrict;
+            requires: Requirements;
+            inputSchema: DescribeTarget["inputSchema"];
+            readOnly: boolean;
+            trustedOnly: boolean;
+            opaque: boolean;
+            unscopedReads: boolean;
+        }[];
+        requires: Requirements;
+    };
+}
+interface Requirements {
+    all: readonly (string | {
+        readonly "ctx.auth.scope": string;
+    })[];
+    guard?: string;
+}
+export interface AppDescription {
+    schemaVersion: 1;
+    access: Readonly<Record<string, UserFieldSpec>>;
+    targets: DescribeTarget[];
+}
+/** A report of sealed declarations; no SQL or row values leave this function. */
+export declare function describeApp(plan: RuntimePlan): Promise<AppDescription>;
+export interface AppChange {
+    id: string;
+    field: string;
+    direction: "widened" | "narrowed" | "changed";
+    before?: unknown;
+    after?: unknown;
+}
+/** Report widening on any reachable surface or dispatcher variant. */
+export declare function diffApp(a: AppDescription, b: AppDescription): AppChange[];

package/dist/domain/describe/index.js

@@ -0,0 +1,115 @@
+import {
+  canonical,
+  hashDefinition,
+  targetDefinitions,
+  targetHash
+} from "./chunk-ZVXBGP7Y.js";
+
+// src/domain/describe/index.ts
+function requirements(d, surface) {
+  const all = d.requires?.auth?.all ?? [];
+  return {
+    all: surface === "admin" && !all.includes("ctx.admin") ? ["ctx.admin", ...all] : all,
+    ...d.requires?.guard ? { guard: d.requires.guard.procedure } : {}
+  };
+}
+async function describeApp(plan) {
+  const targets = await Promise.all(targetDefinitions(plan).map(async (d) => {
+    const scope = Object.fromEntries(d.schemas.map((name) => {
+      const s = plan.schemas[name];
+      return [name, { ...s.scope ? { owner: s.scope } : {}, terms: s.userScopes ?? [] }];
+    }));
+    return { name: d.name, title: d.title, description: d.description, inputSchema: d.inputSchema, annotations: { ...d.annotations, readOnlyHint: d.readOnly }, _meta: {
+      surfaces: d.surfaces,
+      triggers: d.triggers,
+      id: d.id,
+      targetHash: await hashDefinition(plan, d),
+      readOnly: d.readOnly,
+      scope,
+      restrict: d.restrict,
+      opaque: d.opaque,
+      unscopedReads: d.readSchemas.some((name) => !plan.schemas[name]?.scope && !plan.schemas[name]?.userScopes?.length),
+      trustedOnly: d.trustedOnly,
+      variants: d.variants.map((v) => ({
+        id: v.id,
+        restrict: v.restrict,
+        requires: requirements(v, d.surface),
+        inputSchema: v.inputSchema,
+        readOnly: v.readOnly,
+        trustedOnly: v.trustedOnly,
+        opaque: v.opaque,
+        unscopedReads: v.readSchemas.some((name) => !plan.schemas[name]?.scope && !plan.schemas[name]?.userScopes?.length),
+        scope: Object.fromEntries(v.schemas.map((name) => {
+          const s = plan.schemas[name];
+          return [name, { ...s.scope ? { owner: s.scope } : {}, terms: s.userScopes ?? [] }];
+        }))
+      })),
+      requires: requirements(d, d.surface)
+    } };
+  }));
+  return JSON.parse(canonical({ schemaVersion: 1, access: plan.access?.userFields ?? {}, targets }));
+}
+var securityFlags = ["readOnly", "trustedOnly", "opaque", "unscopedReads"];
+var flagDirection = (field, value) => (field === "readOnly" || field === "trustedOnly" ? !value : value) ? "widened" : "narrowed";
+var inclusion = (before, after) => before.some((t) => !after.includes(t)) ? "widened" : after.some((t) => !before.includes(t)) ? "narrowed" : "changed";
+var exposureDirection = (before, after) => after.some((t) => !before.includes(t) && t !== canonical("internal")) ? "widened" : before.some((t) => !after.includes(t) && t !== canonical("internal")) ? "narrowed" : "changed";
+var combine = (directions) => directions.includes("widened") ? "widened" : directions.length && directions.every((d) => d === "narrowed") ? "narrowed" : "changed";
+var terms = (p) => [...p.owner ? [canonical({ owner: p.owner })] : [], ...p.terms.map(canonical)];
+function policyDirection(before, after, scope) {
+  const directions = [];
+  for (const schema of /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)])) {
+    const x = before[schema], y = after[schema];
+    if (canonical(x) === canonical(y)) continue;
+    directions.push(scope && (!x || !y) ? x ? "narrowed" : "widened" : inclusion(x ? terms(x) : [], y ? terms(y) : []));
+  }
+  return combine(directions);
+}
+function requiresDirection(x, y) {
+  const directions = [];
+  if (canonical(x.all) !== canonical(y.all)) directions.push(inclusion(x.all.map(canonical), y.all.map(canonical)));
+  if (x.guard !== y.guard) directions.push(!y.guard ? "widened" : !x.guard ? "narrowed" : "changed");
+  return combine(directions);
+}
+function diffApp(a, b) {
+  if (a.schemaVersion !== 1 || b.schemaVersion !== 1) throw new TypeError("Unsupported describe schemaVersion.");
+  const changes = [], old = new Map(a.targets.map((t) => [t._meta.id, t])), next = new Map(b.targets.map((t) => [t._meta.id, t]));
+  for (const id of [.../* @__PURE__ */ new Set([...old.keys(), ...next.keys()])].sort()) {
+    const before = old.get(id), after = next.get(id);
+    if (!before || !after) {
+      changes.push({ id, field: "target", direction: before ? "narrowed" : "widened" });
+      continue;
+    }
+    const x = before._meta, y = after._meta, start = changes.length;
+    const record = (field, left, right, direction) => {
+      if (canonical(left) !== canonical(right)) changes.push({ id, field, direction, before: left, after: right });
+    };
+    record("scope", x.scope, y.scope, policyDirection(x.scope, y.scope, true));
+    record("restrict", x.restrict, y.restrict, policyDirection(x.restrict, y.restrict, false));
+    record("requires", x.requires, y.requires, requiresDirection(x.requires, y.requires));
+    for (const field of ["surfaces", "triggers"]) record(field, x[field], y[field], exposureDirection(x[field].map(canonical), y[field].map(canonical)));
+    for (const field of securityFlags) record(field, x[field], y[field], flagDirection(field, y[field]));
+    record("inputSchema", before.inputSchema, after.inputSchema, "changed");
+    const directions = [];
+    const variants = new Map(x.variants.map((v) => [v.id, v])), added = new Map(y.variants.map((v) => [v.id, v]));
+    for (const name of /* @__PURE__ */ new Set([...variants.keys(), ...added.keys()])) {
+      const left = variants.get(name), right = added.get(name);
+      if (canonical(left) === canonical(right)) continue;
+      if (!left || !right) directions.push(left ? "narrowed" : "widened");
+      else {
+        if (canonical(left.scope) !== canonical(right.scope)) directions.push(policyDirection(left.scope, right.scope, true));
+        if (canonical(left.restrict) !== canonical(right.restrict)) directions.push(policyDirection(left.restrict, right.restrict, false));
+        if (canonical(left.requires) !== canonical(right.requires)) directions.push(requiresDirection(left.requires, right.requires));
+        if (canonical(left.inputSchema) !== canonical(right.inputSchema)) directions.push("changed");
+        for (const field of securityFlags) if (left[field] !== right[field]) directions.push(flagDirection(field, right[field]));
+      }
+    }
+    record("variants", x.variants, y.variants, combine(directions));
+    if (changes.length === start && x.targetHash !== y.targetHash) changes.push({ id, field: "behavior", direction: "changed" });
+  }
+  return changes;
+}
+export {
+  describeApp,
+  diffApp,
+  targetHash
+};

package/dist/domain/describe/target-hash.d.ts

@@ -0,0 +1,8 @@
+import type { RuntimePlan } from "../../build/compiler.js";
+import { type TargetDefinition } from "./targets.js";
+import { canonical } from "../../build/spec/domain/service/PlanFingerprint.js";
+export { canonical };
+export declare function hash(value: unknown): Promise<string>;
+export declare function hashDefinition(plan: RuntimePlan, d: TargetDefinition): Promise<string>;
+/** Opt-in runtime export. No compiler, parser, database or Node API is loaded. */
+export declare function targetHash(plan: RuntimePlan, targetId: string): Promise<string>;

package/dist/domain/describe/target-hash.js

@@ -0,0 +1,12 @@
+import {
+  canonical,
+  hash,
+  hashDefinition,
+  targetHash
+} from "./chunk-ZVXBGP7Y.js";
+export {
+  canonical,
+  hash,
+  hashDefinition,
+  targetHash
+};

package/dist/domain/describe/targets.d.ts

@@ -0,0 +1,40 @@
+import type { RuntimePlan } from "../../build/compiler.js";
+import type { PlanRestrict } from "../../build/spec/domain/model/RuntimePlan.js";
+import { type JsonSchema, type AuthorizationRequirements, type ProcedureMcpAnnotations } from "../../build/spec/domain/model/ManifestGrammar.js";
+export interface TargetDefinition {
+    id: string;
+    name: string;
+    surface: string;
+    surfaces: string[];
+    triggers: {
+        id: string;
+        source: RuntimePlan["triggers"][string]["source"];
+    }[];
+    kind: "view" | "procedure" | "rest" | "admin";
+    title: string;
+    description: string;
+    inputSchema: JsonSchema;
+    annotations: ProcedureMcpAnnotations;
+    requires?: AuthorizationRequirements;
+    restrict: PlanRestrict;
+    schemas: string[];
+    readSchemas: string[];
+    readOnly: boolean;
+    opaque: boolean;
+    trustedOnly: boolean;
+    behavior: unknown;
+    variants: TargetDefinition[];
+}
+/** Walk sealed IR, including nested statements and expanded View dependencies. */
+export declare function inspectSql(value: unknown): {
+    schemas: string[];
+    readSchemas: string[];
+    readOnly: boolean;
+    writes: {
+        schema: string;
+        operation: string;
+    }[];
+};
+/** Built-in Admin API templates, relative to the configured Admin API base. */
+export declare const adminRoutes: readonly ["GET /me", "GET /site", "GET /collections", "GET /views-manifest", "GET /operations", "GET /webmcp", "POST /webmcp/:tool", "GET /bootstrap", "GET /views/:name/export", "GET /views/:name", "GET /view-batch", "GET /developer/views/:name", "POST /operations/:name", "GET /developer-console", "GET /collections/:name/statistics", "GET /entries", "GET /entries/export", "GET /entries/:id", "POST /entries", "PATCH /entries/:id", "POST /entries/:id/publish", "POST /entries/:id/unpublish", "POST /entries/:id/archive", "DELETE /entries/:id", "GET /site-settings", "PATCH /site-settings", "POST /media/uploads", "POST /media/uploads/:groupId/commit", "GET /media", "GET /media/:id", "PATCH /media/:id", "DELETE /media/:id", "GET /admin", "GET /members", "PATCH /admin/:id/role", "POST /admin/invitations", "DELETE /admin/invitations/:id"];
+export declare function targetDefinitions(plan: RuntimePlan): TargetDefinition[];