@githolon/dsl 0.1.0

package/src/report.ts

@@ -0,0 +1,401 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * `report(id).version(n).select(...).render(...)` — the DECLARATIVE report DSL.
+ *
+ * The product principle: a report author writes ONLY a declarative query + a
+ * render and stays CARELESS about determinism. There is ZERO determinism code in
+ * an authored report:
+ *
+ *   * `.select(a => a.touchedBy(actor, { within: days(30) }))` builds a declarative
+ *     `QueryAst` (NO scan, NO projection access in the author's code). The HOST
+ *     resolves it against the provenance index @ a pinned source commit and feeds
+ *     the answer rows back — the author never touches the index.
+ *   * `.render(rows => csv(rows))` is a PURE function from the fed rows to bytes.
+ *     It runs INSIDE the sealed engine over the host-fed `queryRows` (the
+ *     query-port seal), so its output is deterministic by construction.
+ *
+ * The author writes no commit-walk, no ORDER BY, no digest, no replay. All of that
+ * hard engineering is front-loaded into Nomos (the provenance index + the captured
+ * query port + the in-engine render runner).
+ *
+ * ── Scope (smallest-first proof) ──
+ * Only the `touchedBy(actor, within)` predicate is modelled. Generalising adds
+ * predicate builders (geo/derived/taxonomy) to `SelectBuilder` — each one more
+ * `QueryAst` variant the host resolver answers; the author DSL is unchanged.
+ */
+
+/** A time window in milliseconds — `days(30)` etc. (author-friendly, no clock). */
+export function days(n: number): number {
+  return n * 24 * 60 * 60 * 1000;
+}
+export function hours(n: number): number {
+  return n * 60 * 60 * 1000;
+}
+
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field, FieldValue } from "./fields.js";
+import {
+  buildRelationRegistry,
+  certifyTraversal,
+  type CertifyContext,
+  type RefEdge,
+} from "./query/relations.js";
+import {
+  type EntityGraphQuery,
+  type Filter,
+  type TouchedBy as CompiledTouchedBy,
+} from "./query/compile.js";
+
+/**
+ * The declarative query AST a `.select` produces. Mirrors the Rust
+ * `engine_host::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`.
+ */
+export type QueryAst =
+  | {
+      kind: "touchedBy";
+      actor: string;
+      withinMillis: number;
+    }
+  | ({
+      kind: "entityGraph";
+    } & EntityGraphQuery);
+
+/**
+ * The select surface handed to the author's `select` lambda. Each method is a
+ * declarative predicate that RETURNS a `QueryAst` — it does NOT execute anything.
+ */
+export interface SelectBuilder {
+  /**
+   * `a.touchedBy(actor, { within })` — every aggregate `actor` touched within the
+   * window ending at the report's source commit. Answered from the provenance
+   * index (the commit-walk author signature + intent HLC), NOT an in-VM scan.
+   */
+  touchedBy(actor: string, opts: { within: number }): QueryAst;
+}
+
+const SELECT: SelectBuilder = {
+  touchedBy(actor, opts) {
+    return { kind: "touchedBy", actor, withinMillis: opts.within };
+  },
+};
+
+/** A row the host feeds the render — the report-author-visible provenance touch. */
+export interface QueryRow {
+  actor: string;
+  aggregateId: string;
+  physical: number;
+  logical: number;
+  replica: number;
+  commitOid: string;
+}
+
+/** A fully-declared report: an id, a version, a query, and a render. */
+export interface Report {
+  readonly id: string;
+  readonly version: number;
+  /** The declarative query AST (resolved by the host, never the VM). */
+  readonly query: QueryAst;
+  /** The pure render: fed rows → artifact bytes (runs in the sealed engine). */
+  render(rows: QueryRow[]): string;
+  readonly __isReport: true;
+}
+
+/** Fluent builder: `report(id).version(n).select(...).render(...)`. */
+class ReportBuilder {
+  constructor(
+    private readonly id: string,
+    private readonly _version: number = 1,
+  ) {}
+
+  version(n: number): ReportBuilder {
+    return new ReportBuilder(this.id, n);
+  }
+
+  /** Declare the query. The lambda receives the declarative `SelectBuilder`. */
+  select(fn: (a: SelectBuilder) => QueryAst): ReportWithQuery {
+    return new ReportWithQuery(this.id, this._version, fn(SELECT));
+  }
+}
+
+class ReportWithQuery {
+  constructor(
+    private readonly id: string,
+    private readonly version: number,
+    private readonly query: QueryAst,
+  ) {}
+
+  /** Declare the render. Returns the finished, immutable `Report`. */
+  render(fn: (rows: QueryRow[]) => string): Report {
+    return {
+      id: this.id,
+      version: this.version,
+      query: this.query,
+      render: fn,
+      __isReport: true,
+    };
+  }
+}
+
+/** Declare a report. The id literal IS the wire id (minify-safe string data). */
+export function report(id: string): ReportBuilder {
+  return new ReportBuilder(id);
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// The SEALED-SQL report surface — the ESCAPE HATCH (#130).
+//
+// The declarative `report(...).select(...)` paved road above covers
+// existence/traversal/touchedBy/count. A report whose query needs aggregation
+// (`SUM`/`GROUP BY`), per-row arithmetic, or per-group rollups exceeds those
+// primitives — so its author writes RAW SQL instead, run through the SAME sealed
+// connection (`readmodel::SealedRead`: read-only + immutable + the authorizer
+// deny-list + a forced total ORDER BY). The safety is ENVIRONMENTAL, not
+// linguistic: the seal refuses every nondeterministic/mutating op regardless of
+// the SQL text. The author is still CARELESS about determinism — the seal +
+// capture + re-derive are the engine's job; the author writes only SQL + a render.
+//
+// `asOf`: a report that depends on "now" (e.g. straight-line depreciation =
+// `cost * (1 − age/usefulLife)` where `age = asOf − placedInServiceAt`) MUST NOT
+// read the wall clock — the seal denies `datetime('now')` precisely so a report
+// cannot be nondeterministic. Instead the host resolves `asOf` from the PINNED
+// `source_commit` (the ledger tip's HLC physical time) and BAKES it as a SQL
+// literal — exactly how the entity-graph compiler bakes the `touchedBy` window
+// floor (`pv.physical >= {floor}`). The author declares they need `asOf` via a
+// `{asOf}` placeholder in the SQL; the host substitutes the pinned epoch-ms. The
+// report is then a pure function of `(sqlText, source_commit)` → re-derivable.
+// ───────────────────────────────────────────────────────────────────────────
+
+/** A row the host feeds a sealed-SQL report's render: column name → cell text.
+ * The cells are the canonical text rendering of the sealed result (the same
+ * preimage the `result_digest` is taken over), so the render is deterministic. */
+export type SqlRow = Record<string, string>;
+
+/** A fully-declared sealed-SQL report: id, version, raw SQL (with an optional
+ * `{asOf}` placeholder the host resolves from the source commit), and a render. */
+export interface SqlReport {
+  readonly id: string;
+  readonly version: number;
+  /** The raw SQL. May contain a single `{asOf}` token → the host bakes the pinned
+   * epoch-ms (resolved from `source_commit`, never the wall clock). */
+  readonly sql: string;
+  /** Whether the SQL depends on `{asOf}` (declared, so the host knows to resolve it). */
+  readonly needsAsOf: boolean;
+  /** The pure render: host-fed sealed rows → artifact bytes (runs in the engine). */
+  render(rows: SqlRow[]): string;
+  readonly __isSqlReport: true;
+}
+
+class SqlReportBuilder {
+  constructor(
+    private readonly id: string,
+    private readonly _version: number = 1,
+  ) {}
+
+  version(n: number): SqlReportBuilder {
+    return new SqlReportBuilder(this.id, n);
+  }
+
+  /** Declare the raw SQL. A `{asOf}` token is resolved host-side from the pinned
+   * source commit (deterministic), never the wall clock. */
+  sql(text: string): SqlReportWithQuery {
+    return new SqlReportWithQuery(this.id, this._version, text);
+  }
+}
+
+class SqlReportWithQuery {
+  constructor(
+    private readonly id: string,
+    private readonly version: number,
+    private readonly sqlText: string,
+  ) {}
+
+  render(fn: (rows: SqlRow[]) => string): SqlReport {
+    return {
+      id: this.id,
+      version: this.version,
+      sql: this.sqlText,
+      needsAsOf: this.sqlText.includes("{asOf}"),
+      render: fn,
+      __isSqlReport: true,
+    };
+  }
+}
+
+/** Declare a sealed-SQL (escape-hatch) report. The author writes raw SQL run
+ * through the sealed connection; determinism is the engine's job. */
+export function sqlReport(id: string): SqlReportBuilder {
+  return new SqlReportBuilder(id);
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// The TYPED entity-graph query surface — the PRIMARY path.
+//
+//   from(Child, ALL)
+//     .traverse((c) => c.ref("parentId", Parent))    // .ref is ref-kind-ONLY typed
+//     .where((p) => p.field("kind").eq("primary"))   // field/value keyof-checked
+//     .touchedBy(ACTOR, { within: days(30) })
+//     .count() | .select()
+//
+// `.ref(K, Target)`: `K` is constrained to the CURRENT aggregate's ref-kind fields
+// only (a non-ref or unknown key is a COMPILE error); `Target` is the target handle
+// so the chain's field typing follows the traversal. `.where(...).field(K)` is
+// `keyof`-checked and `.eq(v)` is value-type-checked (mirrors `ops.ts:53`).
+// ───────────────────────────────────────────────────────────────────────────
+
+/** The keys of a field map whose field is a (same-workspace) ref — the ONLY keys
+ * `.ref` accepts. A renamed/retyped/non-ref key is not in this set → compile error. */
+type RefKeys<F extends Record<string, Field>> = {
+  [K in keyof F]: F[K] extends Field<unknown, "ref"> ? K : never;
+}[keyof F] &
+  string;
+
+/** Scalar (string/enum/ref/json) field keys — the only ones `.where(...).eq` filters
+ * (the EAV needle is the JSON-wrapped scalar; non-scalar projection is denied). */
+type ScalarKeys<F extends Record<string, Field>> = {
+  [K in keyof F]: F[K] extends Field<unknown, "string" | "enum" | "ref" | "json">
+    ? K
+    : never;
+}[keyof F] &
+  string;
+
+/** The `where` lambda surface: pick a scalar field, then `.eq(value)`. */
+interface WhereBuilder<F extends Record<string, Field>> {
+  field<K extends ScalarKeys<F>>(
+    key: K,
+  ): { eq(value: FieldValue<F[K]>): { __field: K; __value: FieldValue<F[K]> } };
+}
+
+function whereBuilder<F extends Record<string, Field>>(): WhereBuilder<F> {
+  return {
+    field<K extends ScalarKeys<F>>(key: K) {
+      return {
+        eq: (value: FieldValue<F[K]>) => ({ __field: key, __value: value }),
+      };
+    },
+  };
+}
+
+/** The `traverse` lambda surface: `.ref(K, Target)` — ref-kind-only key + target. */
+interface TraverseBuilder<F extends Record<string, Field>> {
+  ref<K extends RefKeys<F>, TId extends string, TF extends Record<string, Field>>(
+    key: K,
+    target: AggregateHandle<TId, TF>,
+  ): { __field: K; __target: AggregateHandle<TId, TF> };
+}
+
+function traverseBuilder<F extends Record<string, Field>>(): TraverseBuilder<F> {
+  return {
+    ref(key, target) {
+      return { __field: key, __target: target } as any;
+    },
+  };
+}
+
+/**
+ * The typed entity-graph builder. `F` is the field map of the CURRENT (head)
+ * aggregate in the chain — `.traverse` switches it to the target's field map, so
+ * `.where` after a traverse type-checks against the TRAVERSED aggregate.
+ */
+export class EntityGraphBuilder<F extends Record<string, Field>> {
+  constructor(
+    private readonly ctx: CertifyContext,
+    private readonly root: string,
+    /** Resolved traversal chain (certified eagerly so a bad hop fails fast). */
+    private readonly traversals: readonly RefEdge[],
+    private readonly filters: readonly Filter[],
+    /** alias index of the current head aggregate (0 = root). */
+    private readonly headAlias: number,
+    private readonly touched?: CompiledTouchedBy,
+  ) {}
+
+  /** Traverse a ref relation to the target aggregate. The head type switches to the
+   * target's field map. The hop is CERTIFIED now (cycle/cross-ws/exists/ref guards). */
+  traverse<TId extends string, TF extends Record<string, Field>>(
+    fn: (b: TraverseBuilder<F>) => { __field: RefKeys<F>; __target: AggregateHandle<TId, TF> },
+  ): EntityGraphBuilder<TF> {
+    const sel = fn(traverseBuilder<F>());
+    const hops = [...this.traversals.map((t) => t.field), sel.__field];
+    // Re-certify the whole chain from the root (cycle/depth/exists guards live here).
+    const certified = certifyTraversal(this.ctx, this.root, hops);
+    return new EntityGraphBuilder<TF>(
+      this.ctx,
+      this.root,
+      certified,
+      this.filters,
+      this.headAlias + 1,
+      this.touched,
+    );
+  }
+
+  /** A scalar equality filter on the CURRENT head aggregate. */
+  where(
+    fn: (b: WhereBuilder<F>) => { __field: ScalarKeys<F>; __value: unknown },
+  ): EntityGraphBuilder<F> {
+    const sel = fn(whereBuilder<F>());
+    const filter: Filter = {
+      kind: "eq",
+      aliasIndex: this.headAlias,
+      field: sel.__field,
+      value: String(sel.__value),
+    };
+    return new EntityGraphBuilder<F>(
+      this.ctx,
+      this.root,
+      this.traversals,
+      [...this.filters, filter],
+      this.headAlias,
+      this.touched,
+    );
+  }
+
+  /** A `touchedBy(actor, within)` provenance constraint on the ROOT identity. */
+  touchedBy(actor: string, opts: { within: number }): EntityGraphBuilder<F> {
+    return new EntityGraphBuilder<F>(
+      this.ctx,
+      this.root,
+      this.traversals,
+      this.filters,
+      this.headAlias,
+      { actor, withinMillis: opts.within },
+    );
+  }
+
+  /** Finish as a `select`-shaped query AST (root identities). */
+  build(): QueryAst & { kind: "entityGraph" } {
+    return {
+      kind: "entityGraph",
+      root: this.root,
+      traversals: this.traversals,
+      filters: this.filters,
+      ...(this.touched ? { touchedBy: this.touched } : {}),
+    };
+  }
+
+  /** Finish as a COUNT aggregation. */
+  count(): QueryAst & { kind: "entityGraph" } {
+    return { ...this.build(), agg: { op: "count" } };
+  }
+}
+
+/** Begin a typed entity-graph query rooted at `root`. `handles` is the registered
+ * aggregate universe used to derive the relation graph + certify traversals. */
+export function from<Id extends string, F extends Record<string, Field>>(
+  root: AggregateHandle<Id, F>,
+  handles: readonly AggregateHandle[],
+): EntityGraphBuilder<F> {
+  const ctx = buildRelationRegistry(handles);
+  return new EntityGraphBuilder<F>(ctx, root.id, [], [], 0, undefined);
+}

package/src/spatial.ts

@@ -0,0 +1,115 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * `spatial(id)` builder — the GEOSPATIAL read KIND of Nomos's read-side closure
+ * (the keystone of `docs/placement_and_spatial_reads.md`).
+ *
+ * READ-CLOSURE, the spatial half. A `query` declares a NAMED, INDEXED set read keyed on
+ * scalar fields (B-tree); a `count` declares a NAMED, MAINTAINED tally; a `spatial`
+ * declares a NAMED, MAINTAINED **bounding-box index** over an aggregate's **GeoJSON
+ * geometry field**, backed by SQLite **R\*Tree**. So "every aggregate whose geometry
+ * intersects this bbox" is an R\*Tree probe (`WHERE minX<=? AND maxX>=? AND …`), NEVER an
+ * in-VM scan that decodes every aggregate's geometry. The representation (GeoJSON) is kept
+ * as the index SOURCE — the index is derived from it, deterministic + rebuildable from the
+ * fold like every other managed read (the geometry field's bounding box is a pure function
+ * of the folded state @ tip).
+ *
+ * This module adds ONLY the DECLARATION + its TYPE-STATE; the read engine
+ * (`nomos_readmodel`) maintains the R\*Tree side table from the declaration shipped in the
+ * runtime manifest. It mirrors `query.ts`/`count.ts` at every turn: additive,
+ * omit-when-empty, identity-bearing (a spatial a domain declares is carried into the
+ * canonical manifest + becomes part of the domain IDENTITY; a domain that declares NONE is
+ * byte-identical to before this existed), and TYPED — `.of(...)` takes an aggregate HANDLE
+ * (never a string id), so a typo'd aggregate type is a COMPILE error.
+ *
+ * The TYPE-STATE: `spatial(id)` yields a {@link TypelessSpatial} whose ONLY method is
+ * `.of(...)`; the {@link OfSpatial} builder (carrying `.on(...)`) is produced solely by
+ * `.of(...)`; and the finished {@link SpatialDecl} is produced solely by `.on(...)`. So a
+ * spatial with no `of`-type or no geometry field cannot be CONSTRUCTED — "every spatial
+ * index names the type AND the geometry field it indexes" is a type-level property, before
+ * any runtime check (the same discipline as `query`'s mandatory `.key(...)`).
+ */
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+
+type StringKeyOf<T> = Extract<keyof T, string>;
+
+/**
+ * A FINISHED spatial-index declaration (the read-engine's input shape, mirroring {@link
+ * QueryDecl}/{@link CountDecl}): an id, the aggregate TYPE it indexes (`of`), and the name
+ * of the aggregate's GeoJSON geometry field (`on`) whose bounding box is indexed.
+ */
+export interface SpatialDecl {
+  readonly id: string;
+  /** The aggregate TYPE id the spatial index covers, e.g. `TrackableAsset`. */
+  readonly of: string;
+  /**
+   * The aggregate's GeoJSON GEOMETRY field name — the SOURCE of the bounding box the
+   * R\*Tree indexes (e.g. `geoPosition`). The engine reads this field per aggregate,
+   * computes its `[minLng,minLat,maxLng,maxLat]` bbox, and upserts the R\*Tree row.
+   */
+  readonly on: string;
+}
+
+/**
+ * The {@link OfSpatial} BUILDER: it has named its `of`-type, so `.on(field)` (the geometry-
+ * field step) is available. It carries `id` + `of`; `.on(...)` fixes the geometry field and
+ * yields the finished {@link SpatialDecl}. The `F` type parameter carries the `of`-
+ * aggregate's field map so `.on("geoPosition")` is `keyof`-checked against the aggregate's
+ * declared fields — a typo'd geometry field is a COMPILE error.
+ */
+export interface OfSpatial<F extends Record<string, Field> = Record<string, Field>> {
+  readonly id: string;
+  /** The aggregate TYPE id the spatial index covers. */
+  readonly of: string;
+  /**
+   * Fix the GeoJSON GEOMETRY field this index is built over, producing the finished
+   * declaration. `field` is `keyof`-checked against the `of`-aggregate's fields — a
+   * typo'd field is a compile error (the same convention as `count`'s `.by(...)` is
+   * a field of the type / `query`'s key fields).
+   */
+  on(field: StringKeyOf<F>): SpatialDecl;
+}
+
+/**
+ * The INITIAL, un-typed spatial — its ONLY method is `.of(...)`. It deliberately has NO
+ * `.on`, and is not an {@link OfSpatial}/{@link SpatialDecl}, so `spatial("s").on(...)`
+ * (skipping the `of`-type) is a COMPILE error and a type-less spatial cannot be
+ * constructed. THIS is the type-level "every spatial names the type it indexes" property.
+ */
+export interface TypelessSpatial {
+  readonly id: string;
+  /**
+   * Declare the aggregate TYPE this spatial index covers. Takes a typed HANDLE (never the
+   * string id) — a typo'd handle is a compile error, the same convention as `query`'s
+   * `.returns(...)` / `count`'s `.of(...)`. Returns the {@link OfSpatial} builder (the
+   * only shape exposing `.on`).
+   */
+  of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): OfSpatial<F>;
+}
+
+/**
+ * Begin a spatial-index declaration. Returns a {@link TypelessSpatial}: until `.of(...)`
+ * is called, neither `.on` nor a finished `SpatialDecl` exists — the indexed type is NOT
+ * optional, it is a prerequisite; and until `.on(...)` is called the geometry field is a
+ * prerequisite too. So an under-specified spatial index is INEXPRESSIBLE at the type level.
+ */
+export function spatial<const Id extends string>(id: Id): TypelessSpatial {
+  return {
+    id,
+    of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): OfSpatial<F> {
+      return {
+        id,
+        of: aggregate.id,
+        on(field: StringKeyOf<F>): SpatialDecl {
+          return { id, of: aggregate.id, on: field };
+        },
+      };
+    },
+  };
+}