@githolon/dsl 0.108.6 → 0.110.0

package/src/sqlite_layout.ts

@@ -0,0 +1,823 @@
+/** Experimental, disposable SQLite projection plan. NOT law or custody.
+ * One traversal emits access offsets, DDL and compatibility costs. Only opted-in
+ * experiments consume this; unsupported shapes fail, never silently become JSON.
+ */
+import { createHash } from "node:crypto";
+import type { LawGraph, LawValueTypeRef } from "./law_graph.js";
+import {
+  planSqliteComputations,
+  type SqliteComputedPlan,
+} from "./sqlite_computed.js";
+import {
+  planSqliteCounts,
+  type SqliteCountPlan,
+  type SqliteCountSnapshot,
+} from "./sqlite_counts.js";
+import {
+  inspectSqliteReads,
+  planSqliteQueries,
+  type SqliteQueryPlan,
+} from "./sqlite_reads.js";
+
+export interface SqliteColumn {
+  name: string;
+  type: "TEXT" | "INTEGER" | "BLOB";
+}
+export interface SqliteSlot {
+  name: string;
+  sid: string;
+  presence: number; // 0 absent, 1 explicit null, 2 value
+  required: boolean;
+  nullable: boolean;
+  metadata: number[]; // physical, logical, replica, author, contested, schema
+  value: SqliteValue;
+  surfaced?: SqliteValue;
+}
+export interface SqliteValue {
+  kind:
+    | "string"
+    | "integer"
+    | "boolean"
+    | "number"
+    | "null"
+    | "object"
+    | "map"
+    | "set"
+    | "list"
+    | "nominal-map"
+    | "union"
+    | "reference"
+    | "versioned-reference";
+  column?: number;
+  typeName?: string;
+  members?: SqliteSlot[];
+  table?: string;
+  columns?: SqliteColumn[];
+  element?: SqliteSlot;
+  variants?: { label: string; value: SqliteValue }[];
+  literal?: string | number | boolean | null;
+}
+export interface SqliteLayout {
+  version: 2;
+  aggregateSid: string;
+  wireType: string;
+  table: string;
+  columns: SqliteColumn[];
+  fields: SqliteSlot[];
+  indexColumn: number;
+  spatialIndexes: { sid: string; name: string; path: string[] }[];
+  queryReads: SqliteQueryPlan[];
+  queryRefusals: { sid: string; reason: string }[];
+  countReads: SqliteCountPlan[];
+  countRefusals: { sid: string; reason: string }[];
+  countSnapshot: SqliteCountSnapshot | null;
+  computedReads: SqliteComputedPlan[];
+  computedRefusals: { sid: string; reason: string }[];
+  ddl: string;
+  fingerprint: string;
+  budget: {
+    columnLimit: number;
+    tables: { name: string; columns: number }[];
+    maxColumns: number;
+    totalColumns: number;
+    indexes: number;
+    queryIndexes: { name: string; keyColumns: number; parameters: number }[];
+    computedSubstrate: {
+      declarations: number;
+      sqlTemporalReads: number;
+      sealedEngineReads: number;
+      storedColumns: 0;
+      queueTables: 0;
+    };
+    countSubstrate: {
+      declarations: number;
+      tables: { name: string; columns: number }[];
+      snapshotColumns: number;
+      snapshotParameters: number;
+    };
+    // Shared once per database, not multiplied by aggregate or declaration.
+    spatialSubstrate: {
+      declarations: number;
+      tables: { name: string; columns: number }[];
+    };
+    statementsPerPage: number;
+    maxJoinTables: number;
+    maxResultColumns: number;
+    maxInsertParameters: number;
+    warnings: string[];
+  };
+}
+
+export function planSqliteLayout(
+  closure: readonly LawGraph[],
+  aggregateSid: string,
+  indexFieldSid: string,
+  options: { columnLimit?: number; warnColumns?: number } = {}
+): SqliteLayout {
+  return planWithNodes(
+    new Map(
+      closure.flatMap((g) => g.nodes.map((n) => [n.entity.id, n] as const))
+    ),
+    aggregateSid,
+    indexFieldSid,
+    options
+  );
+}
+
+// Reuse the graph index for whole-package inspection. The private field probe is
+// diagnostics only; it is never emitted as an executable full-aggregate layout.
+function planWithNodes(
+  nodes: ReadonlyMap<string, LawGraph["nodes"][number]>,
+  aggregateSid: string,
+  indexFieldSid: string,
+  options: { columnLimit?: number; warnColumns?: number } = {},
+  onlyFieldSid?: string
+): SqliteLayout {
+  const columnLimit = options.columnLimit ?? 2000;
+  // Target compatibility, not SQLITE_MAX_COLUMN's theoretical configurable ceiling.
+  if (!Number.isInteger(columnLimit) || columnLimit < 1 || columnLimit > 2000)
+    throw new Error("SQLite experimental target column limit must be 1..2000");
+  const aggregate = [...nodes.values()].find(
+    (n) => n.kind === "aggregate" && n.entity.sid === aggregateSid
+  );
+  if (aggregate?.kind !== "aggregate")
+    throw new Error(`unknown aggregate SID ${aggregateSid}`);
+  const identifier = (sid: string) => {
+    if (!/^[a-f0-9]+$/i.test(sid))
+      throw new Error(`unsafe stable identity ${sid}`);
+    return sid.toLowerCase();
+  };
+  const table = `a_${identifier(aggregateSid)}`;
+  const spatialIndexes = [...nodes.values()]
+    .flatMap((n) => {
+      if (
+        n.kind !== "read" ||
+        n.readKind !== "spatial" ||
+        n.of.id !== aggregate.entity.id
+      )
+        return [];
+      if (n.predicate)
+        throw new Error(
+          `spatial ${n.entity.label}: filtered index mapping is not supported`
+        );
+      return [
+        {
+          sid: n.entity.sid,
+          name: n.entity.label,
+          path: n.geometry.authoredPath.split("."),
+        },
+      ];
+    })
+    .sort((a, b) => a.sid.localeCompare(b.sid));
+  const tables: { name: string; columns: SqliteColumn[]; child: boolean }[] =
+    [];
+  const rootColumns: SqliteColumn[] = [{ name: "id", type: "TEXT" }];
+  tables.push({ name: table, columns: rootColumns, child: false });
+  const column = (columns: SqliteColumn[], type: SqliteColumn["type"]) => {
+    const offset = columns.length;
+    columns.push({ name: `c${offset}`, type });
+    // Stop expansion promptly; do not build a million-column graph just to report it.
+    if (columns.length > columnLimit)
+      throw new Error(
+        `SQLite layout ${aggregate.entity.label}: table exceeds ${columnLimit} columns (including metadata/presence)`
+      );
+    return offset;
+  };
+  const slot = (
+    name: string,
+    sid: string,
+    columns: SqliteColumn[],
+    required: boolean,
+    nullable: boolean,
+    driven: boolean,
+    build: () => SqliteValue
+  ): SqliteSlot => ({
+    name,
+    sid,
+    required,
+    nullable,
+    presence: column(columns, "INTEGER"),
+    metadata: driven
+      ? (["BLOB", "INTEGER", "BLOB", "TEXT", "INTEGER", "TEXT"] as const).map(
+          (t) => column(columns, t)
+        )
+      : [],
+    value: (() => {
+      try {
+        return build();
+      } catch (error) {
+        throw new Error(`${name}: ${(error as Error).message}`);
+      }
+    })(),
+  });
+  // Each finite schema path owns a table. Instance ancestry is a length-prefixed
+  // parent key, not a JSON path; nested lists/maps never expand root row width.
+  function collection(
+    kind: SqliteValue["kind"],
+    build: (c: SqliteColumn[]) => SqliteSlot
+  ): SqliteValue {
+    const name = `${table}_n${tables.length}`;
+    const columns: SqliteColumn[] = [
+      { name: "id", type: "TEXT" },
+      { name: "key", type: "TEXT" },
+      { name: "parent", type: "TEXT" },
+    ];
+    tables.push({ name, columns, child: true });
+    return { kind, table: name, columns, element: build(columns) };
+  }
+  const isNullable = (ref: LawValueTypeRef): boolean => {
+    const n = nodes.get(ref.id);
+    return (
+      n?.kind === "structural" &&
+      n.structuralKind === "value-type" &&
+      (n.expression.kind === "nullable" ||
+        (n.expression.kind === "default" && isNullable(n.expression.value)))
+    );
+  };
+  function value(
+    ref: LawValueTypeRef,
+    columns: SqliteColumn[],
+    active: Set<string>,
+    nominalName?: string
+  ): SqliteValue {
+    if (active.has(ref.id))
+      throw new Error(
+        "SQLite layout: recursive shape requires a separate mapping experiment"
+      );
+    const next = new Set(active).add(ref.id);
+    const node = nodes.get(ref.id);
+    if (node?.kind === "type") {
+      if (node.form === "geometry") {
+        // Geometry's public encoder emits Int for integral coordinates, Double
+        // otherwise. A tagged numeric leaf retains both (not coercion to REAL).
+        const coords = (c: SqliteColumn[], depth: number): SqliteValue =>
+          collection("list", (inner) =>
+            slot("element", node.entity.id, inner, true, false, false, () =>
+              depth === 1
+                ? {
+                    kind: "number",
+                    column: column(inner, "BLOB"),
+                    typeName: "geometry-number",
+                  }
+                : coords(inner, depth - 1)
+            )
+          );
+        return {
+          kind: "object",
+          typeName: node.entity.label,
+          members: [
+            slot("type", node.entity.id, columns, true, false, false, () => ({
+              kind: "string",
+              column: column(columns, "TEXT"),
+              literal: node.geometry!,
+            })),
+            slot(
+              "coordinates",
+              node.entity.id,
+              columns,
+              true,
+              false,
+              false,
+              () =>
+                coords(
+                  columns,
+                  node.geometry === "Point"
+                    ? 1
+                    : node.geometry === "Polygon"
+                    ? 3
+                    : 2
+                )
+            ),
+          ],
+        };
+      }
+      if (node.form === "sum")
+        return {
+          kind: "union",
+          typeName: node.entity.label,
+          column: column(columns, "INTEGER"),
+          variants: node.variants.map((r) => {
+            const arm = nodes.get(r.id);
+            if (
+              arm?.kind !== "structural" ||
+              arm.structuralKind !== "value-variant" ||
+              arm.label === undefined
+            )
+              throw new Error("missing nominal arm");
+            const target = nodes.get(arm.value.id);
+            const body =
+              target?.kind === "type"
+                ? {
+                    kind: "object" as const,
+                    typeName: node.entity.label,
+                    members: [
+                      slot(
+                        "value",
+                        arm.entity.id,
+                        columns,
+                        true,
+                        false,
+                        false,
+                        () => value(arm.value, columns, next)
+                      ),
+                    ],
+                  }
+                : value(arm.value, columns, next, node.entity.label);
+            return { label: arm.label, value: body };
+          }),
+        };
+      return {
+        kind: "object",
+        typeName: node.entity.label,
+        members: node.fields.map((r) => {
+          const f = nodes.get(r.id);
+          if (f?.kind !== "field")
+            throw new Error(`missing type member ${r.id}`);
+          return slot(
+            f.entity.label,
+            f.entity.sid,
+            columns,
+            f.required,
+            f.nullable,
+            false,
+            () => value(f.value, columns, next)
+          );
+        }),
+      };
+    }
+    if (node?.kind !== "structural" || node.structuralKind !== "value-type")
+      throw new Error(`missing value type ${ref.id}`);
+    const e = node.expression;
+    switch (e.kind) {
+      case "default":
+      case "nullable":
+        return value(e.value, columns, next);
+      case "string":
+      case "enum":
+        return { kind: "string", column: column(columns, "TEXT") };
+      case "integer":
+        return { kind: "integer", column: column(columns, "INTEGER") };
+      case "boolean":
+        return { kind: "boolean", column: column(columns, "INTEGER") };
+      // IEEE bits retain negative zero; no text decode, no SQLite numeric coercion.
+      case "number":
+        return { kind: "number", column: column(columns, "BLOB") };
+      case "null":
+        return { kind: "null" };
+      case "literal": {
+        if (typeof e.value === "string")
+          return {
+            kind: "string",
+            column: column(columns, "TEXT"),
+            literal: e.value,
+          };
+        if (typeof e.value === "boolean")
+          return { kind: "boolean", column: column(columns, "INTEGER") };
+        throw new Error("SQLite layout: unsupported literal representation");
+      }
+      case "record": {
+        const typeName =
+          e.semantic?.kind === "value-object" ? e.semantic.name : nominalName;
+        const reference =
+          e.semantic?.kind === "address-reference" ||
+          e.semantic?.kind === "versioned-reference";
+        if (typeName === undefined && !reference)
+          throw new Error(
+            "SQLite layout: anonymous record needs an explicit nominal storage mapping"
+          );
+        const result: SqliteValue = {
+          kind: reference
+            ? e.semantic!.kind === "versioned-reference"
+              ? "versioned-reference"
+              : "reference"
+            : "object",
+          ...(typeName === undefined ? {} : { typeName }),
+          members: e.fields.map((r) => {
+            const f = nodes.get(r.id);
+            if (f?.kind !== "structural" || f.structuralKind !== "value-field")
+              throw new Error(`missing record member ${r.id}`);
+            return slot(
+              f.name,
+              f.entity.id,
+              columns,
+              f.required,
+              isNullable(f.value),
+              false,
+              () => value(f.value, columns, next)
+            );
+          }),
+        };
+        if (e.semantic?.kind === "value-object" && e.semantic.geometry) {
+          const mark = (s: SqliteValue) => {
+            if (s.kind === "number") s.typeName = "geometry-number";
+            s.members?.forEach((m) => mark(m.value));
+            if (s.element) mark(s.element.value);
+          };
+          mark(result);
+        }
+        return result;
+      }
+      case "list":
+      case "map": {
+        const child = e.kind === "list" ? e.element : e.value;
+        return collection(e.kind === "list" ? "list" : "nominal-map", (c) =>
+          slot("element", ref.id, c, true, isNullable(child), false, () =>
+            value(child, c, next)
+          )
+        );
+      }
+      case "sum": {
+        // Descriptor-lowered named sums carry authored `type` fields in their
+        // structural arms, unlike nominal LawTypeNode variants. Preserve both.
+        if (e.semantic?.kind !== "value-object")
+          throw new Error("unsupported anonymous union storage");
+        const name = e.semantic.name;
+        return {
+          kind: "union",
+          typeName: name,
+          column: column(columns, "INTEGER"),
+          variants: e.variants.map((r) => {
+            const arm = nodes.get(r.id);
+            if (
+              arm?.kind !== "structural" ||
+              arm.structuralKind !== "value-variant"
+            )
+              throw new Error("missing sum arm");
+            const body = value(arm.value, columns, next, name);
+            const discriminator = body.members?.find((s) => s.name === "type")
+              ?.value.literal;
+            if (typeof discriminator !== "string")
+              throw new Error("named union has no literal discriminator");
+            return { label: discriminator, value: body };
+          }),
+        };
+      }
+      default:
+        throw new Error(
+          `SQLite layout: unsupported ${e.kind}; no JSON fallback`
+        );
+    }
+  }
+  const fields = [
+    slot("__type", "builtin:type", rootColumns, true, false, true, () => ({
+      kind: "string",
+      column: column(rootColumns, "TEXT"),
+    })),
+  ];
+  for (const r of aggregate.fields) {
+    const f = nodes.get(r.id);
+    if (f?.kind !== "field") throw new Error(`missing aggregate field ${r.id}`);
+    if (onlyFieldSid !== undefined && f.entity.sid !== onlyFieldSid) continue;
+    if (
+      // Explicit top-level null is a different kernel Value representation;
+      // this slice only models null inside nominal records.
+      f.encrypted ||
+      f.blindIndexed ||
+      f.mergeDrivers.some(
+        (d) =>
+          d.kind !== "Lww" &&
+          d.kind !== "FirstWriterWins" &&
+          d.kind !== "FirstWriterCandidates" &&
+          d.kind !== "MapOf" &&
+          d.kind !== "AddWins" &&
+          d.kind !== "Surfaced"
+      )
+    ) {
+      throw new Error(
+        `SQLite layout: unsupported storage/driver on ${f.entity.label} ` +
+          `(kind=${f.storageKind}; drivers=${f.mergeDrivers
+            .map((d) => d.kind)
+            .join("/")}; ` +
+          `nullable=${f.nullable}; encrypted=${f.encrypted}; blindIndexed=${f.blindIndexed})`
+      );
+    }
+    fields.push(
+      slot(
+        f.entity.label,
+        f.entity.sid,
+        rootColumns,
+        f.required,
+        f.nullable,
+        true,
+        () => {
+          if (f.storageKind === "set" || f.storageKind === "map") {
+            const type = nodes.get(f.value.id);
+            if (
+              type?.kind !== "structural" ||
+              type.structuralKind !== "value-type"
+            )
+              throw new Error("missing collection value type");
+            const e = type.expression;
+            const child =
+              e.kind === "list"
+                ? e.element
+                : e.kind === "map"
+                ? e.value
+                : undefined;
+            if (!child) throw new Error("unsupported collection shape");
+            if (
+              f.storageKind === "map" &&
+              !["string", "int", "bool", "json"].includes(f.mapValueKind ?? "")
+            )
+              throw new Error("unsupported driven map value kind");
+            return collection(f.storageKind, (columns) =>
+              slot(
+                "element",
+                f.entity.sid,
+                columns,
+                true,
+                false,
+                f.storageKind === "map",
+                () => value(child, columns, new Set())
+              )
+            );
+          }
+          if (
+            // storedFieldValue lowers ordinary ID references to string. Atomic
+            // address/versioned refs retain their structural shape and still
+            // pass through value(), which refuses an unsupported mapping.
+            !["string", "int", "bool", "enum", "json", "ref"].includes(
+              f.storageKind ?? ""
+            )
+          )
+            throw new Error(`unsupported field storage kind ${f.storageKind}`);
+          return value(f.value, rootColumns, new Set());
+        }
+      )
+    );
+    if (f.mergeDrivers.some((d) => d.kind === "Surfaced")) {
+      fields.at(-1)!.surfaced = collection("list", (columns) => {
+        // observation stamp + principal + authored law + schema are independent
+        // of outer Field provenance. Six dedicated columns, never a winner-only view.
+        const s = slot(
+          "observation",
+          f.entity.sid,
+          columns,
+          true,
+          f.nullable,
+          true,
+          () => value(f.value, columns, new Set())
+        );
+        columns[s.metadata[4]!]!.type = "TEXT"; // authored_under, not was_contested
+        return s;
+      });
+    }
+  }
+  const indexed = fields.find((f) => f.sid === indexFieldSid);
+  const hasReads = [...nodes.values()].some(
+    (n) =>
+      n.kind === "read" &&
+      (n.of.id === aggregate.entity.id ||
+        (n.readKind === "combined" && n.reads.id === aggregate.entity.id))
+  );
+  if (hasReads && onlyFieldSid === undefined) {
+    // Kernel archive metadata is retained, never translated to a tenant field.
+    fields.push(
+      slot(
+        "__archived",
+        "builtin:archived",
+        rootColumns,
+        false,
+        false,
+        true,
+        () => ({ kind: "integer", column: column(rootColumns, "INTEGER") })
+      )
+    );
+    for (const index of spatialIndexes) {
+      let members = fields;
+      let shape: SqliteValue | undefined;
+      for (const name of index.path) {
+        const member = members.find((f) => f.name === name);
+        if (!member)
+          throw new Error(
+            `spatial ${index.name}: unmapped path ${index.path.join(".")}`
+          );
+        shape = member.value;
+        members = shape.members ?? [];
+      }
+      if (
+        shape?.kind !== "object" ||
+        !shape.members?.some((m) => m.name === "coordinates")
+      )
+        throw new Error(
+          `spatial ${index.name}: path does not resolve to mapped geometry`
+        );
+    }
+  }
+  if (
+    !indexed ||
+    indexed.value.kind !== "string" ||
+    indexed.value.column === undefined
+  )
+    throw new Error("experimental page index requires a string field SID");
+  const indexColumn = indexed.value.column;
+  const queries =
+    onlyFieldSid === undefined
+      ? planSqliteQueries(nodes, aggregate.entity.id, {
+          table,
+          wireType: aggregate.wireType,
+          fields,
+        })
+      : { plans: [], refusals: [] };
+  const maintained =
+    onlyFieldSid === undefined
+      ? planSqliteCounts(nodes, aggregate.entity.id, {
+          table,
+          wireType: aggregate.wireType,
+          fields,
+        })
+      : { plans: [], refusals: [], snapshot: null };
+  const computed =
+    onlyFieldSid === undefined
+      ? planSqliteComputations(nodes, aggregate.entity.id, {
+          table,
+          wireType: aggregate.wireType,
+          fields,
+        })
+      : { plans: [], refusals: [] };
+  const ddl =
+    tables
+      .map(
+        (t) =>
+          `CREATE TABLE ${t.name} (${t.columns
+            .map((c) => `${c.name} ${c.type}`)
+            .join(",")}, PRIMARY KEY(${
+            t.child ? "id,parent,key" : "id"
+          })) WITHOUT ROWID;`
+      )
+      .join("\n") +
+    `\nCREATE INDEX ${table}_page ON ${table}(c${indexColumn},id) WHERE c${indexed.presence}=2;` +
+    queries.plans.map((q) => "\n" + q.ddl).join("");
+  const counts = tables.map((t) => ({
+    name: t.name,
+    columns: t.columns.length,
+  }));
+  const maxColumns = Math.max(...counts.map((t) => t.columns));
+  const result = {
+    version: 2 as const,
+    aggregateSid,
+    wireType: aggregate.wireType,
+    table,
+    columns: rootColumns,
+    fields,
+    indexColumn,
+    spatialIndexes,
+    queryReads: queries.plans,
+    queryRefusals: queries.refusals,
+    countReads: maintained.plans,
+    countRefusals: maintained.refusals,
+    countSnapshot: maintained.snapshot,
+    computedReads: computed.plans,
+    computedRefusals: computed.refusals,
+    ddl,
+    budget: {
+      columnLimit,
+      tables: counts,
+      maxColumns,
+      totalColumns: counts.reduce((sum, t) => sum + t.columns, 0),
+      indexes: 1 + queries.plans.length,
+      computedSubstrate: {
+        declarations: computed.plans.length,
+        sqlTemporalReads: computed.plans.filter((p) => p.temporal).length,
+        sealedEngineReads: computed.plans.filter((p) => !p.temporal).length,
+        storedColumns: 0 as const,
+        queueTables: 0 as const,
+      },
+      queryIndexes: queries.plans.map((q) => ({
+        name: q.index,
+        keyColumns: q.keys.length + 1,
+        parameters: q.keys.length + 2,
+      })),
+      countSubstrate: {
+        declarations: maintained.plans.length,
+        tables: maintained.plans.length
+          ? [{ name: "flat_counts", columns: 3 }]
+          : [],
+        snapshotColumns: maintained.snapshot?.columns ?? 0,
+        snapshotParameters: maintained.snapshot ? 1 : 0,
+      },
+      spatialSubstrate: {
+        declarations: spatialIndexes.length,
+        tables: spatialIndexes.length
+          ? [
+              { name: "spatial_rtree", columns: 5 },
+              { name: "spatial_rowid", columns: 3 },
+            ]
+          : [],
+      },
+      statementsPerPage: tables.length,
+      maxJoinTables: tables.length > 1 ? 2 : 1,
+      maxResultColumns: maxColumns,
+      maxInsertParameters: maxColumns,
+      warnings:
+        maxColumns > (options.warnColumns ?? 256)
+          ? [
+              "Wide table: benchmark prepare, read and write costs; 256 is an advisory threshold, not a measured performance guarantee.",
+            ]
+          : [],
+    },
+  };
+  return {
+    ...result,
+    fingerprint: createHash("sha256")
+      .update(JSON.stringify(result))
+      .digest("hex"),
+  };
+}
+
+/** A report of the REAL compiler closure. No graph serialization, law emission,
+ * tenant-specific name switches, or successful-looking budgets for blocked types.
+ * The single builtin-type index is a diagnostic probe, NOT tenant query planning.
+ */
+export function inspectSqliteLayouts(closure: readonly LawGraph[]) {
+  const nodes = new Map(
+    closure.flatMap((g) => g.nodes.map((n) => [n.entity.id, n] as const))
+  );
+  const domains = new Map<string, string[]>();
+  for (const g of closure)
+    for (const n of g.nodes)
+      if (n.kind === "aggregate") {
+        const owners = domains.get(n.entity.sid) ?? [];
+        if (!owners.includes(g.domain.entity.label))
+          owners.push(g.domain.entity.label);
+        domains.set(n.entity.sid, owners);
+      }
+  const aggregates = [...nodes.values()]
+    .filter((n) => n.kind === "aggregate")
+    .map((a) => {
+      const base = {
+        sid: a.entity.sid,
+        label: a.entity.label,
+        wireType: a.wireType,
+        domains: domains.get(a.entity.sid)!.sort(),
+        fields: a.fields.length,
+      };
+      try {
+        const layout = planWithNodes(nodes, a.entity.sid, "builtin:type");
+        return { ...base, status: "planned" as const, layout };
+      } catch (error) {
+        const fieldRefusals: { field: string; sid: string; reason: string }[] =
+          [];
+        let supportedFields = 0;
+        for (const r of a.fields) {
+          const f = nodes.get(r.id);
+          if (f?.kind !== "field") throw new Error(`missing field ${r.id}`);
+          try {
+            planWithNodes(
+              nodes,
+              a.entity.sid,
+              "builtin:type",
+              {},
+              f.entity.sid
+            );
+            supportedFields++;
+          } catch (e) {
+            fieldRefusals.push({
+              field: f.entity.label,
+              sid: f.entity.sid,
+              reason: (e as Error).message,
+            });
+          }
+        }
+        return {
+          ...base,
+          status: "blocked" as const,
+          reason: (error as Error).message,
+          supportedFields,
+          fieldRefusals,
+        };
+      }
+    })
+    .sort((a, b) => a.wireType.localeCompare(b.wireType));
+  const planned = aggregates.filter((a) => a.status === "planned");
+  return {
+    version: 1,
+    kind: "experimental-sqlite-layout-inspection",
+    indexPolicy:
+      "builtin type / id, declared query expression indexes, maintained count totals and spatial indexes; see per-read coverage and runtime gates",
+    summary: {
+      domains: closure.length,
+      uniqueAggregates: aggregates.length,
+      planned: planned.length,
+      blocked: aggregates.length - planned.length,
+      maxPlannedColumns: Math.max(
+        0,
+        ...planned.map((a) => a.layout.budget.maxColumns)
+      ),
+      maxPlannedTables: Math.max(
+        0,
+        ...planned.map((a) => a.layout.budget.tables.length)
+      ),
+      allSupported: planned.length === aggregates.length,
+      spatialIndexes: planned.reduce(
+        (n, a) => n + a.layout.spatialIndexes.length,
+        0
+      ),
+    },
+    aggregates,
+    readCoverage: inspectSqliteReads(
+      nodes,
+      planned.map((a) => a.layout)
+    ),
+  };
+}