@githolon/dsl 0.1.0

package/src/compose.ts

@@ -0,0 +1,317 @@
+// 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.
+
+/**
+ * #137 — the OpenUSD-shaped COMPOSED IR (the "stage").
+ *
+ * A Nomos domain is a STAGE composed from ordered LAYERS
+ * (prelude → tenant → customer → jurisdiction → policy). Unlike USD's
+ * "strongest opinion wins", composition here is TYPED and MONOTONIC: a stronger
+ * (later) layer may only TIGHTEN the law — narrow a scope, add a required
+ * capability — unless an explicit `authority` widens it. The flattened stage's
+ * canonical hash is the domain identity (extends #136: the canonical-manifest
+ * hash; this module reuses `canonicalJson` for byte-stable hashing).
+ *
+ * This is the MODEL of USD composition (typed monotonic merge), NOT the USD
+ * library. Layers/prims here are SYNTHETIC framework units — no tenant/business
+ * domain is named or imported.
+ *
+ * Fail-closed: any rule a merge cannot satisfy is surfaced as a typed
+ * `CompositionViolation`, never silently coerced.
+ */
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./manifest.js";
+
+/**
+ * A composable law unit (modelled on a directive/role). The typed-rule fields:
+ *  - `requires`: capability ids that MUST hold; a stronger layer may only ADD.
+ *  - `scope`: a `/`-segmented path (e.g. `site/s1`); a stronger layer may only
+ *    NARROW (equal or more specific) without authority.
+ *  - `payload`: an optional artifact reference that MUST be `certified`.
+ */
+export interface PrimDecl {
+  readonly requires: string[];
+  /** A `/`-segmented scope path; broader = shorter ANCESTOR prefix. */
+  readonly scope: string;
+  readonly payload?: { artifactHash: string; certified: boolean };
+}
+
+/** A composition layer: a stage path + its prims keyed by prim path. */
+export interface Layer {
+  readonly path: string;
+  readonly prims: Record<string, PrimDecl>;
+}
+
+/** Options for composition — `authority` permits explicit widening / removal. */
+export interface ComposeOptions {
+  /** When true, scope-WIDEN and requires-REMOVE are explicitly permitted. */
+  readonly authority?: boolean;
+  /**
+   * The USD VARIANT selection (LIVRPS — Variants sit above References, below Local).
+   * Maps a layer's variant SET name → the chosen variant NAME within it. An explicit
+   * input to `flattenUsd`/`usdHash` (NOT baked into the document): the composed law is
+   * a function of `(doc, selection)`, so a different selection yields a different
+   * commit-pinned composed identity. A set with NO entry here contributes its declared
+   * DEFAULT variant if one exists (the `*` key, see `usd.ts`), else NOTHING. A selection
+   * naming an unknown set or variant fails closed (`variant-unresolved`).
+   */
+  readonly variantSelection?: Record<string, string>;
+}
+
+/** The typed composition rules that can be violated. */
+export type ViolationRule =
+  | "requires-remove"
+  | "scope-widen"
+  | "uncertified-payload"
+  // The USD REFERENCE arc (composed in `usd.ts`): a reference cycle, or a
+  // reference to a layer path not present in the document, both fail closed.
+  | "reference-cycle"
+  | "reference-unresolved"
+  // The USD VARIANT arc (composed in `usd.ts`): a selection naming a variant set
+  // not declared on the layer, or a variant not present within a declared set,
+  // both fail closed (an explicit selection that cannot be resolved is never a no-op).
+  | "variant-unresolved";
+
+/**
+ * A typed, descriptive composition failure. Thrown (fail-closed) when a merge
+ * cannot satisfy a typed rule. Never produced by silent coercion.
+ */
+export class CompositionViolation extends Error {
+  readonly rule: ViolationRule;
+  readonly primPath: string;
+  readonly detail: string;
+  constructor(rule: ViolationRule, primPath: string, detail: string) {
+    super(`composition ${rule} at ${primPath}: ${detail}`);
+    this.name = "CompositionViolation";
+    this.rule = rule;
+    this.primPath = primPath;
+    this.detail = detail;
+  }
+}
+
+/** One flattened prim in the effective stage (canonical: requires SORTED). */
+export interface FlatPrim {
+  readonly requires: string[];
+  readonly scope: string;
+  readonly payload?: { artifactHash: string; certified: boolean };
+}
+
+/** The effective composed manifest: prims SORTED by path. */
+export interface Composed {
+  readonly prims: Record<string, FlatPrim>;
+}
+
+/** Split a `/`-segmented path into non-empty segments. */
+function segments(path: string): string[] {
+  return path.split("/").filter((s) => s.length > 0);
+}
+
+/**
+ * `covers(a, b)`: `a` covers `b` iff `a`'s segments are a PREFIX of `b`'s.
+ * So `site` covers `site/s1`; equal paths cover each other (a path covers itself).
+ */
+export function covers(a: string, b: string): boolean {
+  const sa = segments(a);
+  const sb = segments(b);
+  if (sa.length > sb.length) return false;
+  for (let i = 0; i < sa.length; i++) {
+    if (sa[i] !== sb[i]) return false;
+  }
+  return true;
+}
+
+/** WIDEN(base, over): `over.scope` covers `base.scope` AND they differ. */
+function isWiden(base: string, over: string): boolean {
+  return base !== over && covers(over, base);
+}
+
+/** NARROW(base, over): `base.scope` covers `over.scope` (equal counts as allowed). */
+function isNarrowOrEqual(base: string, over: string): boolean {
+  return covers(base, over);
+}
+
+/**
+ * The TYPED requires+scope monotonic-merge rule — the single, reusable rule core
+ * (#137) shared by `PrimDecl` composition AND the unified USD directive-prim merge
+ * (`usd.ts`). It operates on the rule-bearing fields ONLY (capability set + optional
+ * scope path), so it can fold a directive prim that has NO static scope (the DSL
+ * today emits none): a `scope` of `undefined` on BOTH sides simply skips the scope
+ * rule; a present-vs-absent scope is treated as introducing a scope (a NARROW from
+ * "root", always allowed) or as REMOVING one (a WIDEN, authority-gated). Returns the
+ * merged `{ requires (sorted union), scope? }`, or throws a typed `CompositionViolation`.
+ *
+ * This is a STRENGTHENING, not a loosening: the existing `string`-scope rules are
+ * preserved byte-for-byte (compose.test's 7 still pass); the only additions are the
+ * previously-unreachable optional-scope cases, each held to the SAME monotonic law.
+ */
+export function mergeRequiresScope(
+  primPath: string,
+  base: { requires: readonly string[]; scope?: string },
+  over: { requires: readonly string[]; scope?: string },
+  opts: ComposeOptions,
+): { requires: string[]; scope?: string } {
+  const authority = opts.authority === true;
+
+  // requires: every base capability MUST remain (⊆ override). The override may
+  // ADD caps. A silent removal is a VIOLATION unless authority.
+  const overSet = new Set(over.requires);
+  if (!authority) {
+    for (const cap of base.requires) {
+      if (!overSet.has(cap)) {
+        throw new CompositionViolation(
+          "requires-remove",
+          primPath,
+          `override drops base capability "${cap}"`,
+        );
+      }
+    }
+  }
+
+  // scope: monotonic NARROW-or-equal wins; WIDEN / REMOVE / disjoint are
+  // authority-gated VIOLATIONS. Absent scope = "root" (the broadest), so:
+  //  - both absent          → no scope rule, stays absent.
+  //  - base absent, over set → over INTRODUCES a scope = NARROW from root → ok.
+  //  - base set, over absent → over REMOVES the scope = WIDEN to root → authority.
+  //  - both set             → the existing string-path NARROW/WIDEN/disjoint rules.
+  let effectiveScope: string | undefined;
+  if (base.scope === undefined && over.scope === undefined) {
+    effectiveScope = undefined;
+  } else if (base.scope === undefined) {
+    // Introducing a scope tightens the (root) law — always allowed.
+    effectiveScope = over.scope;
+  } else if (over.scope === undefined) {
+    // Removing the base scope WIDENS to root — authority required.
+    if (!authority) {
+      throw new CompositionViolation(
+        "scope-widen",
+        primPath,
+        `override removes base scope "${base.scope}" (widens to root)`,
+      );
+    }
+    effectiveScope = undefined;
+  } else {
+    if (!isNarrowOrEqual(base.scope, over.scope)) {
+      if (isWiden(base.scope, over.scope)) {
+        if (!authority) {
+          throw new CompositionViolation(
+            "scope-widen",
+            primPath,
+            `override widens scope from "${base.scope}" to "${over.scope}"`,
+          );
+        }
+      } else {
+        // Disjoint scopes (neither covers the other) cannot tighten the law.
+        throw new CompositionViolation(
+          "scope-widen",
+          primPath,
+          `override scope "${over.scope}" is disjoint from base "${base.scope}"`,
+        );
+      }
+    }
+    effectiveScope = over.scope;
+  }
+
+  // Flattened requires = union of base + override (sorted).
+  const merged = new Set<string>(base.requires);
+  for (const cap of over.requires) merged.add(cap);
+  const requires = [...merged].sort();
+
+  return effectiveScope !== undefined
+    ? { requires, scope: effectiveScope }
+    : { requires };
+}
+
+/**
+ * Validate a prim's payload rule in isolation: a present payload MUST be
+ * `certified: true`. This is NEVER gated by authority — an uncertified artifact
+ * is always refused.
+ */
+function assertPayloadCertified(primPath: string, prim: PrimDecl): void {
+  if (prim.payload !== undefined && prim.payload.certified !== true) {
+    throw new CompositionViolation(
+      "uncertified-payload",
+      primPath,
+      `payload artifact ${prim.payload.artifactHash} is not certified`,
+    );
+  }
+}
+
+/**
+ * Merge a stronger `over` prim onto a `base` prim per the TYPED rules.
+ * Returns the flattened effective prim, or throws a `CompositionViolation`.
+ */
+function mergePrim(
+  primPath: string,
+  base: PrimDecl,
+  over: PrimDecl,
+  opts: ComposeOptions,
+): FlatPrim {
+  // Apply the shared typed requires+scope rule core. A `PrimDecl` always carries a
+  // (required, string) scope, so the merged result always carries a string scope.
+  const { requires, scope } = mergeRequiresScope(primPath, base, over, opts);
+  const effectiveScope = scope ?? over.scope;
+
+  const flat: FlatPrim = over.payload !== undefined
+    ? { requires, scope: effectiveScope, payload: { ...over.payload } }
+    : { requires, scope: effectiveScope };
+  return flat;
+}
+
+/** Canonicalize a standalone prim into a flattened prim (requires SORTED). */
+function flatFromPrim(prim: PrimDecl): FlatPrim {
+  const requires = [...prim.requires].sort();
+  return prim.payload !== undefined
+    ? { requires, scope: prim.scope, payload: { ...prim.payload } }
+    : { requires, scope: prim.scope };
+}
+
+/**
+ * Fold the layers in given (strength) order into the effective composed stage.
+ * For each prim path present in a later layer that also exists earlier, MERGE
+ * per the typed rules. Payload certification is enforced for EVERY contributing
+ * prim. Throws `CompositionViolation` (fail-closed) on any rule it cannot satisfy.
+ */
+export function compose(layers: Layer[], opts: ComposeOptions = {}): Composed {
+  const acc = new Map<string, FlatPrim>();
+
+  for (const layer of layers) {
+    for (const primPath of Object.keys(layer.prims)) {
+      const prim = layer.prims[primPath]!;
+      // Payload certification is always enforced, base or override.
+      assertPayloadCertified(primPath, prim);
+
+      const existing = acc.get(primPath);
+      if (existing === undefined) {
+        acc.set(primPath, flatFromPrim(prim));
+      } else {
+        const base: PrimDecl = existing.payload !== undefined
+          ? { requires: existing.requires, scope: existing.scope, payload: existing.payload }
+          : { requires: existing.requires, scope: existing.scope };
+        acc.set(primPath, mergePrim(primPath, base, prim, opts));
+      }
+    }
+  }
+
+  // Emit prims SORTED by path for a canonical structure.
+  const prims: Record<string, FlatPrim> = {};
+  for (const primPath of [...acc.keys()].sort()) {
+    prims[primPath] = acc.get(primPath)!;
+  }
+  return { prims };
+}
+
+/** Returns the effective composed manifest (canonical structure). */
+export function flatten(layers: Layer[], opts: ComposeOptions = {}): Composed {
+  return compose(layers, opts);
+}
+
+/** The composed stage's content-hash identity: sha256 hex of `canonicalJson(flatten(...))`. */
+export function composedHash(layers: Layer[], opts: ComposeOptions = {}): string {
+  return createHash("sha256")
+    .update(canonicalJson(flatten(layers, opts)), "utf8")
+    .digest("hex");
+}

package/src/count.ts

@@ -0,0 +1,218 @@
+// 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.
+
+/**
+ * `count(id)` builder — the AGGREGATION analogue of the {@link query} primitive
+ * (read-engine step 3).
+ *
+ * READ-CLOSURE, the aggregation half. A `query` declares a NAMED, INDEXED set read
+ * ("every X where field = Y"); a `count` declares a NAMED, MAINTAINED tally ("how many
+ * X, grouped by a key field"). The result of a count is ONE number, so by the perf
+ * invariant it MUST be O(1): a counter the read engine MAINTAINS incrementally as the
+ * workspace folds, NEVER a `COUNT(*)` scan over the counted set. This module adds ONLY
+ * the DECLARATION + its TYPE-STATE; the read engine (`nomos_readmodel`) maintains the
+ * counter table from the declaration shipped in the runtime manifest.
+ *
+ * It mirrors `query.ts` at every turn: additive, omit-when-empty, identity-bearing
+ * (a count a domain declares is carried into the canonical manifest + becomes part of
+ * the domain IDENTITY; a domain that declares NO count 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 same convention as `query`'s `.returns`.
+ *
+ * The TYPE-STATE: `count(id)` yields a {@link TypelessCount} whose ONLY method is
+ * `.of(...)`; the {@link Count} builder (carrying `.where(...)` and `.by(...)`) is
+ * produced solely by `.of(...)`. So a count with no `of`-type cannot be CONSTRUCTED —
+ * "every count names the type it tallies" is a type-level property, before any runtime
+ * check.
+ *
+ * `.where(...)` is OPTIONAL: a predicate filters WHICH aggregates are counted. When
+ * absent, every aggregate of the `of`-type is counted (same as before this existed —
+ * a predicate-free count is byte-identical in the manifest to the legacy form).
+ *
+ * `.by(...)` is OPTIONAL: a {@link Count} (a bare `.of(...)`) is ALREADY a usable
+ * GRAND-TOTAL declaration (one synthetic group); calling `.by(field)` partitions it.
+ * Both a {@link Count} and a grouped {@link CountDecl} satisfy {@link AnyCount}, which
+ * is what `DomainModule.counts` accepts — see {@link finishCount} for the normalization.
+ *
+ * ORDER-SENSITIVE GUARDRAIL: count exposes NO `.first`/`.take`/`.orderBy`. Those
+ * operations are order-sensitive and require a declared `.orderBy` to be constructible
+ * (spec §2.3). The ABSENCE of those methods here is the precondition assertion for
+ * Slice 1 — a red compilecheck the moment Slice 2 lands `first/take` without the guard.
+ * Do NOT add a dead `.orderBy` here — that is loosening (LAW 3); assert the absence.
+ */
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+import { type Predicate, type CanonicalPred, predBuilder, canonicalizePred } from "./predicate.js";
+
+/**
+ * A FINISHED count declaration (the read-engine's input shape, mirroring {@link
+ * QueryDecl}): an id, the aggregate TYPE it tallies (`of`), the OPTIONAL predicate
+ * (`where`) that filters which aggregates are counted, and the OPTIONAL group-by
+ * field (`by`).
+ *   * `where` PRESENT  → only aggregates matching the predicate are counted;
+ *   * `where` ABSENT   → every aggregate of the `of`-type is counted.
+ *   * `by` PRESENT  → maintain one counter per distinct value of that field;
+ *   * `by` ABSENT   → maintain ONE grand-total counter (a single synthetic group).
+ */
+export interface CountDecl {
+  readonly id: string;
+  /** The aggregate TYPE id the count tallies, e.g. `SiteRootAggregate`. */
+  readonly of: string;
+  /**
+   * The optional predicate: ONLY aggregates satisfying this predicate are counted.
+   * ABSENT ⇒ every aggregate of the `of`-type (unfiltered, today's behaviour).
+   * Stored as a {@link CanonicalPred} so the manifest fragment is deterministic.
+   */
+  readonly where?: CanonicalPred;
+  /**
+   * The group-by field name (the count is partitioned by this field's value). ABSENT
+   * ⇒ a grand total over every (matching) aggregate of the `of`-type (one synthetic group).
+   */
+  readonly by?: string;
+}
+
+/**
+ * The {@link Count} BUILDER: it has named its `of`-type, so `.where(...)` (the
+ * predicate step) and `.by(...)` (the grouping step) are available. It carries `id`
+ * + `of` (so a bare `.of(...)` is ALREADY a usable grand-total unfiltered declaration)
+ * and the `.where(...)` and `.by(...)` methods. It is a SIBLING of {@link CountDecl}
+ * (not a subtype) — the `by` method and `CountDecl`'s `by` field share a name but
+ * never coexist on one object; {@link finishCount} normalizes either to a
+ * {@link CountDecl}.
+ *
+ * The `F` type parameter carries the `of`-aggregate's field map so `.where(p =>
+ * p.field("status").eq("approved"))` is `keyof`-checked against the aggregate's
+ * fields and value-type-checked against the field's declared type.
+ */
+export interface Count<F extends Record<string, Field> = Record<string, Field>> {
+  readonly id: string;
+  /** The aggregate TYPE id the count tallies. */
+  readonly of: string;
+  /**
+   * Attach an optional PREDICATE: only aggregates satisfying the predicate are
+   * counted. The lambda receives a {@link PredBuilder} whose `.field(K)` is
+   * `keyof`-checked against the `of`-aggregate's scalar fields and `.eq(v)` /
+   * `.ne(v)` is value-type-checked. Returns a new {@link Count} with the predicate
+   * baked in; further `.by(...)` is still available.
+   */
+  where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): Count<F>;
+  /**
+   * Partition the count by a GROUP-BY field — every distinct value of `field` gets its
+   * own maintained counter. Returns a finished {@link CountDecl}. Omitting `.by` leaves
+   * the count a GRAND TOTAL (this builder already carries `id`/`of`).
+   */
+  by(field: string): CountDecl;
+}
+
+/**
+ * The INITIAL, un-typed count — its ONLY method is `.of(...)`. It deliberately has NO
+ * `.by`, NO `.where`, and is not a {@link Count}/{@link CountDecl}, so
+ * `count("c").by(...)` (skipping the `of`-type) is a COMPILE error and a type-less
+ * count cannot be constructed. THIS is the type-level "every count names the type it
+ * tallies" property.
+ */
+export interface TypelessCount {
+  readonly id: string;
+  /**
+   * Declare the aggregate TYPE this count tallies. Takes a typed HANDLE (never the
+   * string id) — a typo'd handle is a compile error, the same convention as `query`'s
+   * `.returns(...)`. Returns the {@link Count} builder (the only shape exposing `.by`
+   * and `.where`), which is already a usable grand-total unfiltered count.
+   */
+  of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): Count<F>;
+}
+
+/**
+ * Either form a domain may declare in `DomainModule.counts`: a grouped {@link CountDecl}
+ * (the result of `.by(field)`) or a bare {@link Count} grand-total builder (the result
+ * of `.of(...)`). {@link finishCount} normalizes both to a {@link CountDecl}.
+ *
+ * `Count<any>` — same rationale as `AnyDirective = Directive<any>` in `codegen_dart.ts`:
+ * `Count<F>` is invariant in `F` (the `where` method is both a producer and consumer of
+ * `PredBuilder<F>`), so `Count<SpecificFields>` is NOT assignable to
+ * `Count<Record<string,Field>>`. The consumer side (manifest + codegen) accesses only
+ * the `id`/`of`/`by` string fields and the `CanonicalPred`-typed `_where` slot —
+ * it never calls `.where(fn)` — so `any` is safe here.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyCount = CountDecl | Count<any>;
+
+/** Narrow: a {@link Count} builder exposes a `by` METHOD; a {@link CountDecl} does not. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isCountBuilder(c: AnyCount): c is Count<any> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return typeof (c as Count<any>).by === "function";
+}
+
+/**
+ * Normalize an {@link AnyCount} to a finished {@link CountDecl}. A grand-total builder
+ * (bare `.of(...)`) becomes `{id, of}` (no `by`); a grouped `.by(field)` result is
+ * already a `CountDecl` and passes through. A `.where(pred)` result (without `.by`)
+ * carries `where` on the builder object — finishCount transfers it. Lets
+ * `DomainModule.counts` accept either the builder or the finished decl uniformly
+ * (mirrors how a query is always a finished `QueryDecl` because `.key(...)` is
+ * mandatory; for counts `.by(...)` is optional, so this normalizer absorbs the
+ * grand-total builder).
+ */
+export function finishCount(c: AnyCount): CountDecl {
+  if (isCountBuilder(c)) {
+    // The builder carries `id`, `of`, and a `_where` private slot set by `.where()`.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const b = c as any;
+    const w: CanonicalPred | undefined = b._where;
+    return {
+      id: c.id,
+      of: c.of,
+      ...(w !== undefined ? { where: w } : {}),
+    };
+  }
+  return c;
+}
+
+/**
+ * Begin a count declaration. Returns a {@link TypelessCount}: until `.of(...)` is
+ * called, neither `.by`, `.where` nor a usable count exists — the tallied type is NOT
+ * optional, it is a prerequisite for the count to take any further shape.
+ */
+export function count<const Id extends string>(id: Id): TypelessCount {
+  return {
+    id,
+    of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): Count<F> {
+      return makeCount<F>(id, aggregate.id, undefined);
+    },
+  };
+}
+
+/** Internal factory so `.where(...)` can return a new Count without duplicating impl. */
+function makeCount<F extends Record<string, Field>>(
+  id: string,
+  ofType: string,
+  where: CanonicalPred | undefined,
+): Count<F> {
+  // Attach the canonical predicate as a named slot so finishCount can transfer it.
+  // Use a spread to satisfy `exactOptionalPropertyTypes`: when `where` is undefined
+  // we omit the `_where` key entirely rather than writing `_where: undefined`.
+  const c = {
+    id,
+    of: ofType,
+    ...(where !== undefined ? { _where: where } : {}),
+    where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): Count<F> {
+      const pred = fn(predBuilder<F>());
+      const canonical = canonicalizePred(pred as Predicate<Record<string, Field>>);
+      return makeCount<F>(id, ofType, canonical);
+    },
+    by(field: string): CountDecl {
+      return {
+        id,
+        of: ofType,
+        ...(where !== undefined ? { where } : {}),
+        by: field,
+      };
+    },
+  } as unknown as Count<F>;
+  return c;
+}

package/src/ctx.ts

@@ -0,0 +1,57 @@
+// 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.
+
+/**
+ * The directive `ctx` exposes only kernel-owned ports (contract §0 law 3:
+ * impurity only through injected ports). Stubbed deterministically for now.
+ *
+ *  - ctx.clock -> HLC components (physical, logical, replica)
+ *  - ctx.id    -> IdGenerator (monotonic allocator port)
+ *  - ctx.rng   -> Random port
+ */
+import type { WireHlc } from "./wire.js";
+
+export interface Ports {
+  clock(): WireHlc;
+  id(): string;
+  rng(): number;
+}
+
+/** A deterministic stub set of ports — seeded, replayable. */
+export function deterministicPorts(seed: {
+  physical?: number;
+  logical?: number;
+  replica?: number;
+  idPrefix?: string;
+} = {}): Ports {
+  let physical = seed.physical ?? 1;
+  let logical = seed.logical ?? 0;
+  const replica = seed.replica ?? 0;
+  const idPrefix = seed.idPrefix ?? "id";
+  let idCounter = 0;
+  let rngState = (seed.physical ?? 1) >>> 0 || 1;
+  return {
+    clock(): WireHlc {
+      const h: WireHlc = { physical, logical, replica };
+      // Advance: same physical -> bump logical (mirrors merge.md local-event rule).
+      logical += 1;
+      return h;
+    },
+    id(): string {
+      idCounter += 1;
+      return `${idPrefix}-${idCounter}`;
+    },
+    rng(): number {
+      // xorshift32 — deterministic.
+      rngState ^= rngState << 13;
+      rngState ^= rngState >>> 17;
+      rngState ^= rngState << 5;
+      rngState >>>= 0;
+      return rngState / 0xffffffff;
+    },
+  };
+}