@githolon/dsl 0.108.7 → 0.110.0

package/src/read.ts

@@ -172,6 +172,56 @@ export function readFrameworkDeclaredRows<
   return z.array(row).parse(readFrameworkDeclared(query.id, args));
 }
 
+/**
+ * Typed framework foreign read. This is the attested twin of
+ * {@link readFrameworkDeclaredRows}: the aggregate declaration remains the
+ * only field/type source, while the ordinary foreign-read lane captures the
+ * source kernel's proof on the authored intent.
+ *
+ * Framework laws use this when an admitted local transition copies a typed
+ * value from another sovereign workspace. The peer may cache and relay the
+ * attestation, but neither it nor a generated application client decodes or
+ * vouches for the returned rows.
+ */
+export function readFrameworkAttestedRows<
+  const Id extends string,
+  F extends Record<string, Field>,
+>(
+  query: QueryDecl,
+  aggregate: AggregateHandle<Id, F>,
+  args: Record<string, string>,
+  from: string,
+): Array<ReadModelRow<F>> {
+  if (query.returns !== aggregate.id) {
+    throw new Error(
+      `framework attested read '${query.id}' returns '${query.returns}', not '${aggregate.id}'`,
+    );
+  }
+  const fields = aggregate.fields as Record<string, Field>;
+  const shape = Object.fromEntries(
+    Object.entries(fields).map(([name, field]) => [name, field.zod.optional()]),
+  ) as ProjectionShape<F>;
+  const data = z.object(shape).strip() as z.ZodType<ReadModelRow<F>>;
+  const envelope = z.object({ data: z.unknown() }).passthrough();
+  const row = z.union([envelope, z.unknown()])
+    .transform((value) => {
+      const wrapped = envelope.safeParse(value);
+      const projected = wrapped.success ? wrapped.data.data : value;
+      if (projected === null || typeof projected !== "object" || Array.isArray(projected)) {
+        return projected;
+      }
+      const lifted = { ...(projected as Record<string, unknown>) };
+      for (const name in fields) {
+        if (fields[name]?.kind !== "bool") continue;
+        if (lifted[name] === "true") lifted[name] = true;
+        else if (lifted[name] === "false") lifted[name] = false;
+      }
+      return lifted;
+    })
+    .pipe(data);
+  return z.array(row).parse(read(query, args, { from }));
+}
+
 function readForeign<T = unknown>(query: QueryDecl | { id: string }, args: Record<string, string>, from: string): T {
   // ── THE FOREIGN (attested cross-workspace) LANE (slice B — attested_reads_design.md §4.1).
   // The port answers the `{rows, attestation}` wrapper: at AUTHOR the kernel verified the

package/src/relation.ts

@@ -99,7 +99,10 @@ export interface RelationDecl {
 
 /** Stage 1 of the builder: id + the two endpoints. */
 class RelationSourceStep<Id extends string> {
-  constructor(private readonly id: Id) {}
+  private readonly id: Id;
+  constructor(id: Id) {
+    this.id = id;
+  }
   /** Declare the SOURCE → TARGET endpoints (aggregate TYPE ids). */
   endpoints(source: string, target: string): RelationProposesStep<Id> {
     return new RelationProposesStep(this.id, source, target);

package/src/relation_schema.ts

@@ -198,9 +198,11 @@ export function mergeRelationTypeDeclarations(
           // Framework-owned declarations can cross the published-CLI/package bundle boundary as
           // distinct object identities. The private brand plus byte-identical definition identifies
           // that one canonical concept; tenant-authored collisions remain a loud hard failure.
+          // A tenant may also re-export the framework's own fragment (e.g. `workspaceOperatorRelations`,
+          // which a business birth composes too): one side branded and byte-identical is that same concept.
           const repeatedFrameworkDeclaration =
-            (first as RelationTypeDecl & { businessBirthInternal?: boolean }).businessBirthInternal === true &&
-            (declaration as RelationTypeDecl & { businessBirthInternal?: boolean }).businessBirthInternal === true &&
+            ((first as RelationTypeDecl & { businessBirthInternal?: boolean }).businessBirthInternal === true ||
+              (declaration as RelationTypeDecl & { businessBirthInternal?: boolean }).businessBirthInternal === true) &&
             JSON.stringify(existing) === JSON.stringify(definition);
           if (repeatedFrameworkDeclaration) continue;
           throw new Error(
@@ -398,6 +400,17 @@ export function relationType(type: string, caps?: Partial<RelationCaps>): Relati
     relation(name: string, opts?: { rewrite?: Rewrite; allow?: AllowedSubject[] }): RelationTypeBuilder {
       requireName(name, "relation");
       if (relations.has(name)) throw new Error(`relationType("${type}"): relation "${name}" declared twice`);
+      // Law is compiled without a type check, so an option this builder does not know would otherwise
+      // vanish silently — a declared intent the compiled law never carries.
+      for (const option of Object.keys(opts ?? {})) {
+        if (option === "rewrite" || option === "allow") continue;
+        throw new Error(
+          option === "seededFromParent"
+            ? `relationType("${type}"): relation "${name}" cannot be seeded from the parent; only the framework's own ` +
+              `operator relation is carried at birth (identity_target_model.md D19)`
+            : `relationType("${type}"): relation "${name}" has unknown option "${option}"`,
+        );
+      }
       const allowed = opts?.allow ?? [];
       validateAllowed(type, name, allowed);
       relations.set(name, { rewrite: opts?.rewrite ?? null, allowed });

package/src/report.ts

@@ -60,14 +60,14 @@ import {
 
 /**
  * The declarative query AST a `.select` produces. Mirrors the Rust
- * `engine_host::query_port::QueryAst` (tagged union). The HOST resolves this; the
+ * `deterministic_rquickjs::query_port::QueryAst` (tagged union). The HOST resolves this; the
  * author only constructs it via the fluent `SelectBuilder`.
  *
  * Two variants now:
  *   * `touchedBy` — the original provenance predicate (escape-hatch / disclosure).
  *   * `entityGraph` — the PRIMARY path: a typed entity-graph query Nomos compiles
  *     into sealed SQL. Carries the certified relation chain + filters + optional
- *     touchedBy + agg. Mirrors `engine_host::query_port::QueryAst::EntityGraph`.
+ *     touchedBy + agg. Mirrors `deterministic_rquickjs::query_port::QueryAst::EntityGraph`.
  */
 export type QueryAst =
   | {

package/src/sqlite_computation_bundle.ts

@@ -0,0 +1,78 @@
+/** Diagnostic only: execute real declarations through the existing sealed engine.
+ * This is not an installed law asset or an alternative tenant compiler. */
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+import { build } from "esbuild";
+import type { collectEngineRouting } from "./engine_entry.js";
+
+export async function sqliteComputationBundle(
+  sources: ReadonlyMap<string, string>,
+  routing: ReturnType<typeof collectEngineRouting>
+) {
+  const src = dirname(fileURLToPath(import.meta.url));
+  const zod = dirname(
+    createRequire(import.meta.url).resolve("zod/package.json")
+  );
+  const domains = [
+    ...new Set([
+      ...Object.values(routing.derivedOf ?? {}).flat(),
+      ...Object.values(routing.combinedOf ?? {}).flat(),
+    ]),
+  ].sort();
+  if (domains.length === 0) return null;
+  const result = await build({
+    stdin: {
+      contents: [
+        `import {registerEngine} from ${JSON.stringify(
+          join(src, "engine_entry.ts")
+        )};`,
+        ...["core", "registries"].map(
+          (n, i) =>
+            `import * as seed${i} from ${JSON.stringify(
+              join(zod, "v4/core", n + ".js")
+            )};`
+        ),
+        "registerEngine({domains:{",
+        ...domains.map((d) => {
+          const s = sources.get(d);
+          if (!s) throw Error(`missing computation domain ${d}`);
+          return s;
+        }),
+        `},routing:${JSON.stringify(routing)},seeds:[seed0,seed1]});`,
+      ].join("\n"),
+      loader: "ts",
+      resolveDir: resolve(src, ".."),
+    },
+    bundle: true,
+    write: false,
+    format: "iife",
+    target: "es2020",
+    platform: "neutral",
+    charset: "utf8",
+    minify: true,
+    metafile: true,
+    define: { __nmsRuntimeLaw: "true" },
+    alias: {
+      zod: join(src, "runtime_zod.ts"),
+      "zod/v4": join(zod, "v4/index.js"),
+    },
+  });
+  const javascript = result.outputFiles[0]!.text;
+  return {
+    kind: "diagnostic-sealed-computations",
+    javascript,
+    sha256: createHash("sha256").update(javascript).digest("hex"),
+    domains,
+    inputs: Object.keys(result.metafile!.inputs)
+      .filter((p) => p !== "<stdin>")
+      .map((p) => ({
+        path: resolve(p),
+        sha256: createHash("sha256")
+          .update(readFileSync(resolve(p)))
+          .digest("hex"),
+      })),
+  };
+}

package/src/sqlite_computed.ts

@@ -0,0 +1,102 @@
+/** Fixed read declarations lower to SQL. Arbitrary function bodies remain in
+ * the existing sealed engine. No derived copies or invalidation queue. */
+import type { LawGraph } from "./law_graph.js";
+import type { SqliteLayout } from "./sqlite_layout.js";
+import { scalarSlot } from "./sqlite_reads.js";
+export interface SqliteComputedPlan {
+  sid: string;
+  name: string;
+  kind: "derived" | "combined" | "temporalEnum";
+  via: string | null;
+  relatedType: string | null;
+  temporal: {
+    id: string;
+    of: string;
+    source_field: string;
+    missing: string;
+    initial: string;
+    transitions: { after_millis: number; value: string }[];
+    expression: string;
+  } | null;
+}
+const quote = (s: string) => `'${s.replaceAll("'", "''")}'`;
+export function planSqliteComputations(
+  nodes: ReadonlyMap<string, LawGraph["nodes"][number]>,
+  aggregateId: string,
+  layout: Pick<SqliteLayout, "table" | "wireType" | "fields">
+) {
+  const plans: SqliteComputedPlan[] = [],
+    refusals: { sid: string; reason: string }[] = [];
+  for (const read of nodes.values()) {
+    if (
+      read.kind !== "read" ||
+      read.of.id !== aggregateId ||
+      (read.readKind !== "derived" &&
+        read.readKind !== "combined" &&
+        read.readKind !== "temporalEnum")
+    )
+      continue;
+    try {
+      if (read.predicate) throw Error("computed read predicate not supported");
+      if (layout.fields.some((f) => f.name === read.entity.label))
+        throw Error("computed output shadows an authored field");
+      const p: SqliteComputedPlan = {
+        sid: read.entity.sid,
+        name: read.entity.label,
+        kind: read.readKind,
+        via: null,
+        relatedType: null,
+        temporal: null,
+      };
+      if (read.readKind === "temporalEnum") {
+        const path = read.source.authoredPath.split(".");
+        const f = layout.fields.find((f) => f.name === path[0]);
+        if (!f || path.length !== 1 || scalarSlot(f, []).kind !== "integer")
+          throw Error("temporal source requires a mapped scalar timestamp");
+        const source = scalarSlot(f, []).sql;
+        const transitions = read.transitions.map((t) => {
+          if (!Number.isSafeInteger(t.afterMillis) || t.afterMillis < 0)
+            throw Error("invalid temporal threshold");
+          return { after_millis: t.afterMillis, value: t.value };
+        });
+        // ?1 is the captured clock. Guard subtraction against signed-i64
+        // underflow; no REAL promotion or ambient SQLite wall clock.
+        const cases = [...transitions].reverse().map((t) => {
+          const safe = -(1n << 63n) + BigInt(t.after_millis);
+          const condition =
+            t.after_millis === 0
+              ? "1"
+              : `(?1>=${safe} AND (${source})<=?1-${t.after_millis})`;
+          return `WHEN ${condition} THEN ${quote(t.value)}`;
+        });
+        p.temporal = {
+          id: p.name,
+          of: layout.wireType,
+          source_field: path[0]!,
+          missing: read.missing,
+          initial: read.initial,
+          transitions,
+          expression: `CASE WHEN (${source}) IS NULL THEN ${quote(
+            read.missing
+          )} ${cases.join(" ")} ELSE ${quote(read.initial)} END`,
+        };
+      } else if (read.readKind === "combined") {
+        const path = read.via.authoredPath.split(".");
+        const f = layout.fields.find((f) => f.name === path[0]);
+        if (!f || path.length !== 1 || scalarSlot(f, []).kind !== "string")
+          throw Error(
+            "combined join requires a mapped direct string reference"
+          );
+        const related = nodes.get(read.reads.id);
+        if (related?.kind !== "aggregate")
+          throw Error("combined related aggregate unavailable");
+        p.via = path[0]!;
+        p.relatedType = related.wireType;
+      }
+      plans.push(p);
+    } catch (error) {
+      refusals.push({ sid: read.entity.sid, reason: (error as Error).message });
+    }
+  }
+  return { plans: plans.sort((a, b) => a.sid.localeCompare(b.sid)), refusals };
+}

package/src/sqlite_counts.ts

@@ -0,0 +1,154 @@
+/** Maintained count plans. Predicates stay typed Rust values, never SQL WHERE
+ * fragments. A replacement reads only the old/new scalar inputs by primary key.
+ */
+import type { LawGraph, LawStructuralRef } from "./law_graph.js";
+import type { SqliteLayout } from "./sqlite_layout.js";
+import { scalarSlot } from "./sqlite_reads.js";
+
+type Nodes = ReadonlyMap<string, LawGraph["nodes"][number]>;
+// Existing projection::CountPred serde representation; not a new predicate VM.
+export type SqliteCountPredicate =
+  | { Eq: { field: string; value: string } }
+  | { Ne: { field: string; value: string } }
+  | { And: SqliteCountPredicate[] }
+  | { Or: SqliteCountPredicate[] };
+export interface SqliteCountPlan {
+  sid: string;
+  name: string;
+  groupBy: string[] | null;
+  groupColumn: number | null;
+  predicate: SqliteCountPredicate | null;
+}
+export interface SqliteCountSnapshot {
+  sql: string;
+  columns: number;
+  fields: { name: string; kind: "string" | "integer"; column: number }[];
+}
+export function planSqliteCounts(
+  nodes: Nodes,
+  aggregateId: string,
+  layout: Pick<SqliteLayout, "table" | "wireType" | "fields">
+) {
+  const plans: SqliteCountPlan[] = [];
+  const refusals: { sid: string; reason: string }[] = [];
+  const inputs = new Map<string, { kind: "string" | "integer"; sql: string }>();
+  const groups = new Map<string, string>();
+  for (const read of nodes.values()) {
+    if (
+      read.kind !== "read" ||
+      read.readKind !== "count" ||
+      read.of.id !== aggregateId
+    )
+      continue;
+    try {
+      const local = new Map<
+        string,
+        { kind: "string" | "integer"; sql: string }
+      >();
+      function predicate(
+        ref: LawStructuralRef<"predicate">,
+        active = new Set<string>()
+      ): SqliteCountPredicate {
+        if (active.has(ref.id)) throw Error("recursive count predicate");
+        const node = nodes.get(ref.id);
+        if (node?.kind !== "structural" || node.structuralKind !== "predicate")
+          throw Error("missing count predicate node");
+        const e = node.expression;
+        if (e.kind === "and" || e.kind === "or") {
+          const clauses = e.terms.map((t) =>
+            predicate(t, new Set(active).add(ref.id))
+          );
+          return e.kind === "and" ? { And: clauses } : { Or: clauses };
+        }
+        if (e.kind !== "eq" && e.kind !== "ne")
+          throw Error("unsupported count predicate");
+        const path = e.field.authoredPath.split(".");
+        if (path.length !== 1)
+          throw Error("count predicates require an own-aggregate scalar field");
+        const slot = layout.fields.find((f) => f.name === path[0]);
+        if (!slot) throw Error("unmapped count predicate field");
+        const scalar = scalarSlot(slot, []);
+        // CountPred currently handles Str/Int only. Do not pretend the DSL's
+        // boolean support is correct until the shared old/new evaluator agrees.
+        if (scalar.kind !== "string" && scalar.kind !== "integer")
+          throw Error(
+            "shared count predicate evaluator does not support this scalar kind"
+          );
+        if (
+          scalar.kind === "integer" &&
+          (!/^-?\d+$/.test(e.value) ||
+            BigInt(e.value) < -(1n << 63n) ||
+            BigInt(e.value) >= 1n << 63n)
+        )
+          throw Error("count predicate integer outside i64");
+        local.set(path[0]!, { kind: scalar.kind, sql: scalar.sql });
+        const clause = { field: path[0]!, value: e.value };
+        return e.kind === "eq" ? { Eq: clause } : { Ne: clause };
+      }
+      const pred = read.predicate ? predicate(read.predicate) : null;
+      const path = read.groupBy?.authoredPath.split(".") ?? null;
+      let groupSql: string | undefined;
+      if (path) {
+        const slot = layout.fields.find((f) => f.name === path[0]);
+        if (!slot) throw Error("unmapped count group field");
+        const scalar = scalarSlot(slot, path.slice(1));
+        if (scalar.kind !== "string")
+          throw Error("count group keys must be strings");
+        groupSql = scalar.sql;
+      }
+      // A refused read contributes no inputs to supported maintenance plans.
+      for (const [name, value] of local) inputs.set(name, value);
+      if (groupSql !== undefined) groups.set(read.entity.sid, groupSql);
+      plans.push({
+        sid: read.entity.sid,
+        name: read.entity.label,
+        groupBy: path,
+        groupColumn: null,
+        predicate: pred,
+      });
+    } catch (error) {
+      refusals.push({ sid: read.entity.sid, reason: (error as Error).message });
+    }
+  }
+  plans.sort((a, b) => a.sid.localeCompare(b.sid));
+  if (!plans.length) return { plans, refusals, snapshot: null };
+  // c0 is not used; one constant permits predicate-free, ungrouped counts too.
+  const expressions = ["1"];
+  const fields = [...inputs]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, value]) => {
+      const column = expressions.length;
+      expressions.push(value.sql);
+      return { name, kind: value.kind, column };
+    });
+  const groupColumns = new Map<string, number>();
+  for (const plan of plans) {
+    const sql = groups.get(plan.sid);
+    if (sql === undefined) continue;
+    let column = groupColumns.get(sql);
+    if (column === undefined) {
+      column = expressions.length;
+      expressions.push(sql);
+      groupColumns.set(sql, column);
+    }
+    plan.groupColumn = column;
+  }
+  if (expressions.length > 2000)
+    throw Error("count snapshot exceeds 2000-column SQLite target");
+  const type = layout.fields.find((f) => f.name === "__type")!;
+  const archive = layout.fields.find((f) => f.name === "__archived")!;
+  const literal = `'${layout.wireType.replaceAll("'", "''")}'`;
+  return {
+    plans,
+    refusals,
+    snapshot: {
+      sql: `SELECT ${expressions.join(",")} FROM ${
+        layout.table
+      } WHERE id=?1 AND c${type.presence}=2 AND c${
+        type.value.column
+      }=${literal} AND COALESCE(c${archive.value.column},0)<>1`,
+      columns: expressions.length,
+      fields,
+    } satisfies SqliteCountSnapshot,
+  };
+}