@githolon/dsl 0.1.0

package/LICENSE.md

@@ -0,0 +1,36 @@
+# Nomos Pre-Release License (v1)
+
+Copyright © 2026 Captain App Ltd. All rights reserved.
+
+This is a pre-release of Nomos. This license gives you what you need to BUILD
+with it; we keep the rest for now.
+
+## You may
+
+- install and use these packages to author Nomos domains, compile them, and
+  deploy them to Nomos Cloud or any Nomos instance Captain App operates or
+  authorizes;
+- build, run, and ship applications on top of them — including commercial ones;
+- keep everything that's yours: code you write, and everything these tools
+  generate FOR you (scaffolds from `create-holon` / `holon generate`, generated
+  clients, compiled domain packages) carries NO restriction from us — it is
+  yours outright.
+
+## You may not
+
+- redistribute these packages or their source, in whole or in part, outside
+  your team;
+- modify them or build derivative tools, SDKs, or runtimes from their source;
+- offer the Nomos runtime, or anything materially similar, as a hosted service;
+- reverse-engineer the holon wasm runtime.
+
+## The rest
+
+Provided **as is**, with no warranty of any kind; to the maximum extent
+permitted by law, Captain App Ltd accepts no liability arising from your use.
+This license terminates automatically if you breach it.
+
+Want the kernel source, broader rights, or to do something this doesn't cover?
+**Ask: jack@captainapp.co.uk.** The plan is to open Nomos up gradually, with
+the people actually using it — telling us what you're building is how that
+happens faster.

package/compile_package.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// 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.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+// `nomos-compile` / `holon-compile` — the thin launcher: resolve `tsx` (the
+// caller's, else the DSL's own dependency) and run `src/compile_package_main.ts`
+// under it (the main dynamically imports the caller's TS domain modules, which
+// needs the tsx ESM loader). tsx is a regular dependency of @githolon/dsl, so a bare
+// `npx holon compile` / `npx nomos-compile` works with zero devDependency setup.
+// Resolution goes through Node's resolver (createRequire), NOT node_modules/.bin
+// paths — hoisted/workspace installs put the bin shims elsewhere.
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DSL_DIR = path.dirname(fileURLToPath(import.meta.url));
+const MAIN = path.join(DSL_DIR, "src", "compile_package_main.ts");
+
+/** Resolve a dependency's package dir from `fromDir`, walking Node's resolver. */
+function resolvePkgDir(name, fromDir) {
+  try {
+    const req = createRequire(pathToFileURL(path.join(fromDir, "noop.js")));
+    return path.dirname(req.resolve(`${name}/package.json`));
+  } catch {
+    return undefined;
+  }
+}
+
+const tsxDir = resolvePkgDir("tsx", process.cwd()) ?? resolvePkgDir("tsx", DSL_DIR);
+if (!tsxDir) {
+  console.error("nomos-compile: tsx not found — reinstall @githolon/dsl (tsx is one of its dependencies)");
+  process.exit(1);
+}
+const tsxPkg = JSON.parse(readFileSync(path.join(tsxDir, "package.json"), "utf8"));
+const tsxBinRel = typeof tsxPkg.bin === "string" ? tsxPkg.bin : tsxPkg.bin?.tsx;
+const tsxCli = path.join(tsxDir, tsxBinRel ?? "dist/cli.mjs");
+
+try {
+  execFileSync(process.execPath, [tsxCli, MAIN, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  });
+} catch (e) {
+  process.exit(e.status ?? 1);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@githolon/dsl",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Captain-App/nomos2.git",
+    "directory": "dsl"
+  },
+  "main": "src/index.ts",
+  "bin": {
+    "nomos-compile": "./compile_package.mjs",
+    "holon-compile": "./compile_package.mjs"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./manifest": "./src/manifest.ts",
+    "./compose": "./src/compose.ts",
+    "./usd": "./src/usd.ts",
+    "./engine-entry": "./src/engine_entry.ts",
+    "./build-package": "./src/build_package.ts",
+    "./compile-engine": "./src/compile_engine.ts",
+    "./codegen-dart": "./src/codegen_dart.ts",
+    "./codegen-dot": "./src/codegen_dot.ts",
+    "./codegen-provider": "./src/codegen_provider_dart.ts",
+    "./framework/identity": "./src/framework/identity.ts",
+    "./framework/disclosure": "./src/framework/disclosure.ts",
+    "./framework/bootstrap": "./src/framework/bootstrap.ts",
+    "./framework/domain_lifecycle": "./src/framework/domain_lifecycle.ts",
+    "./framework/sync_lifecycle": "./src/framework/sync_lifecycle.ts",
+    "./framework/repair": "./src/framework/repair.ts",
+    "./framework/workspaces": "./src/framework/workspaces.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "compile_package.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "esbuild": "0.24.2",
+    "tsx": "^4.19.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}

package/src/aggregate.ts

@@ -0,0 +1,167 @@
+// 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.
+
+/**
+ * `aggregate(id, fields)` -> a typed handle.
+ *
+ * The stable string id is declared ONCE, here, at the declaration site. That
+ * literal IS the wire id (it's string DATA, so it's minify-safe — never a
+ * renamed symbol). Everywhere else you reference the returned handle, never the
+ * string: a typo'd handle is a compile error.
+ */
+import type { Field } from "./fields.js";
+
+/**
+ * A pure, replay-stable predicate over one aggregate's PROJECTED snapshot —
+ * evaluated BY THE ENGINE after each event-apply. Returns a TYPED verdict.
+ * PURE over the snapshot (no clock, no IO, no live reads); runs in the sealed engine.
+ * PRESENCE ONLY is hashed in the manifest (like a directive `plan`); the body ships
+ * in the engine bundle, never in the ledger.
+ */
+export type AggregateInvariantVerdict = { accept: true } | { reject: string };
+export type AggregateInvariantFn = (snapshot: Record<string, unknown>) => AggregateInvariantVerdict;
+
+/**
+ * An aggregate has two genuinely different kinds of member, and the DSL keeps them
+ * APART so no downstream layer ever has to re-derive the distinction:
+ *
+ *   • STORED FIELDS  (`fields`)  — real data with a leaf kind (string/int/ref/enum/…).
+ *     The engine projects, decodes, hashes and wires these. Every manifest / wire /
+ *     codegen / projection consumer iterates `fields` and is GUARANTEED never to meet
+ *     a virtual kind — so none of them special-case anything.
+ *   • VIRTUAL INVERSES (`hasMany`) — `t.hasMany(Child).via("backref")` relations. NOT
+ *     stored: they derive the inverse read index (`Child by backref`) and the `.add`
+ *     back-ref write. Consumed ONLY by the two layers that own the 1:N read side
+ *     (`hasManyIndexes`) and the `.add` authoring dispatch.
+ *
+ * The dev still declares both inline in one object (easy to model); `aggregate()`
+ * partitions them here, ONCE — the only place that knows `hasMany` is virtual.
+ */
+type IsHasMany<Fld> = Fld extends Field<unknown, "hasMany"> ? true : false;
+/** The STORED subset of a declared field record — everything except virtual `t.hasMany`. */
+export type StoredFields<F extends Record<string, Field>> = {
+  [K in keyof F as IsHasMany<F[K]> extends true ? never : K]: F[K];
+};
+/** The VIRTUAL `t.hasMany` inverse subset of a declared field record. */
+export type HasManyFields<F extends Record<string, Field>> = {
+  [K in keyof F as IsHasMany<F[K]> extends true ? K : never]: F[K];
+};
+
+/** Runtime partition of a declared field record into stored fields + virtual `hasMany` inverses. */
+function partitionFields(fields: Record<string, Field>): {
+  stored: Record<string, Field>;
+  hasMany: Record<string, Field>;
+} {
+  const stored: Record<string, Field> = {};
+  const hasMany: Record<string, Field> = {};
+  for (const [name, field] of Object.entries(fields)) {
+    if (field.kind === "hasMany") hasMany[name] = field;
+    else stored[name] = field;
+  }
+  return { stored, hasMany };
+}
+
+export interface AggregateHandle<
+  Id extends string = string,
+  F extends Record<string, Field> = Record<string, Field>,
+> {
+  /** The wire id — the literal you passed in. */
+  readonly id: Id;
+  /** STORED fields only — real data; `keyof` is what op helpers check field names against. */
+  readonly fields: StoredFields<F>;
+  /** VIRTUAL `t.hasMany` inverses — empty object when the aggregate declares none. */
+  readonly hasMany: HasManyFields<F>;
+  /** Brand so a plain string is never accepted where a handle is required. */
+  readonly __isAggregateHandle: true;
+  /** Presence-only flag (hashed); OMITTED ENTIRELY when no invariant is declared. */
+  readonly hasInvariant?: true;
+  /** The executable body — ships in the engine bundle, NOT the manifest. */
+  readonly invariant?: AggregateInvariantFn;
+  /**
+   * The LAW-DECLARED instance CAP (Jack's ruling: instance limits are DOMAIN POLICY,
+   * never a fabric id-shape special case). `cap: 1` = at most one instance per
+   * workspace — the admission gate refuses an over-cap Create with a clear message.
+   * Carried in the canonical manifest (hash-bearing); OMITTED when uncapped so
+   * cap-free domains hash byte-identically to before this key existed.
+   */
+  readonly cap?: number;
+}
+
+export function aggregate<const Id extends string, F extends Record<string, Field>>(
+  id: Id,
+  fields: F,
+  opts?: { invariant?: AggregateInvariantFn; cap?: number },
+): AggregateHandle<Id, F> {
+  const { stored, hasMany } = partitionFields(fields);
+  if (opts?.cap !== undefined && (!Number.isInteger(opts.cap) || opts.cap < 1)) {
+    throw new Error(`aggregate '${id}': cap must be a positive integer (got ${opts.cap})`);
+  }
+  return {
+    id,
+    fields: stored as StoredFields<F>,
+    hasMany: hasMany as HasManyFields<F>,
+    __isAggregateHandle: true,
+    ...(opts?.invariant !== undefined
+      ? { hasInvariant: true as const, invariant: opts.invariant }
+      : {}),
+    ...(opts?.cap !== undefined ? { cap: opts.cap } : {}),
+  };
+}
+
+/**
+ * A bound aggregate reference — a handle pinned to a concrete INSTANCE id.
+ *
+ * #105 (instance binding): an `AggregateHandle.id` is the aggregate TYPE literal
+ * (e.g. `Thing`), correct only for one-per-workspace aggregates. Every
+ * multi-instance aggregate (Thing, Node, Container, …) needs a per-instance
+ * address. `instance(Thing, "thing-a")` returns a `BoundAggregate` carrying BOTH
+ * the runtime instance `id` AND the static `type` (+ the handle's `fields`, so op
+ * helpers keep their `keyof`-checked field/value typing). Op helpers accept either
+ * a bare handle (unbound → `aggregateId = type`, the legacy one-per-workspace
+ * shape) or a bound ref (→ `aggregateId = instanceId`, `aggregateType = type`).
+ */
+export interface BoundAggregate<
+  Id extends string = string,
+  F extends Record<string, Field> = Record<string, Field>,
+> {
+  /** The concrete instance id — what reaches `WireEvent.aggregate`. */
+  readonly id: string;
+  /** The aggregate TYPE (the handle's static id) — surfaced to `view()` via `__type`. */
+  readonly type: Id;
+  /** The STORED field map, carried through so op helpers keep field-name/value typing.
+   *  (Op-helper typing infers off the `F` param, so virtual `hasMany` is never settable.) */
+  readonly fields: StoredFields<F>;
+  /** Brand: a bound ref is distinct from a bare handle. */
+  readonly __isBoundAggregate: true;
+}
+
+/**
+ * Bind an aggregate handle to a concrete instance id. ADDITIVE: the handle itself
+ * is unchanged; `instance(h, id)` is the opt-in per-instance address. Op helpers
+ * (`set`/`addToSet`/`setEntry`) accept the returned ref and lower it to a
+ * `PlannedOp` carrying the instance id AND the aggregate type.
+ */
+export function instance<Id extends string, F extends Record<string, Field>>(
+  handle: AggregateHandle<Id, F>,
+  id: string,
+): BoundAggregate<Id, F> {
+  return { id, type: handle.id, fields: handle.fields, __isBoundAggregate: true };
+}
+
+/**
+ * A name-only handle for a FORWARD / CIRCULAR `t.ref` target — an aggregate referenced
+ * before its `const` is declared (e.g. `Estate.headquartersSiteId -> Site` while
+ * `Site.estateId -> Estate`). `t.ref` reads only the target's wire `.id`, so a
+ * fields-less, relation-less stand-in is a faithful, minify-safe forward declaration.
+ *
+ * Use this instead of hand-building `{ id, fields: {}, hasMany: {}, __isAggregateHandle }`
+ * so the handle shape stays in exactly ONE place — add a member to `AggregateHandle`
+ * and every forward ref keeps compiling for free.
+ */
+export function forwardRef<const Id extends string>(id: Id): AggregateHandle<Id, Record<string, never>> {
+  return { id, fields: {}, hasMany: {}, __isAggregateHandle: true };
+}

package/src/authoring.ts

@@ -0,0 +1,119 @@
+// 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}.  If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * THE AGGREGATE AUTHORING SURFACE — Nomos owns every birth; the dev talks DDD (Jack 2026-06-08).
+ *
+ * This is LIBRARY code (`@githolon/dsl`). It uses exactly ONE host capability — `nomos.mint(typeTag)` (a
+ * captured-entropy id) — and does everything else itself: it turns `create()` / `.set` / `.add` /
+ * `.relate` into ordinary `PlannedOp`s (the same shape the typed `set`/`addToSet`/`setEntry` produce),
+ * which `executeDirectiveToIntent` groups into kernel events. The engine never records wire events directly.
+ *
+ *     const child = create(Child).set("name", p.name);
+ *     parent.add("children", child);          // ← writes child.parent = parent.id (ONE event, on the child)
+ *
+ * `.add` DISPATCHES on the declared field kind: a `t.hasMany(Child).via("parent")` field writes the
+ * child's back-reference (the cheap N:1 — parent untouched, no growing set); a bounded `t.set(...)` field
+ * does an `AddToSet` on the aggregate itself. A dev therefore cannot build a write-amplifying parent
+ * collection — see `docs/aggregate_lifecycle_and_relations.md`.
+ *
+ * Ops are collected in a per-dispatch SINK (library-side state, invisible to the engine); `executeDirectiveToIntent`
+ * resets it before the plan and drains it after, merging the authored ops with whatever the plan returns.
+ * So a `.plan` that fluently authors and `return []`s still emits its events — the recorded ops are real.
+ */
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+import type { FieldOp, PlannedOp } from "./ops.js";
+
+// ── the per-dispatch authoring sink — library state the engine never sees (NOT a side channel out of
+//    the sandbox; it is internal to the directive runtime, drained synchronously by `executeDirectiveToIntent`). ──
+let sink: PlannedOp[] = [];
+/** Clear the sink before a plan runs (called by `executeDirectiveToIntent`). */
+export function __resetAuthoring(): void {
+  sink = [];
+}
+/** Take + clear the ops authored via the fluent surface during a plan (called by `executeDirectiveToIntent`). */
+export function __drainAuthoring(): PlannedOp[] {
+  const s = sink;
+  sink = [];
+  return s;
+}
+
+interface NomosMint {
+  mint(typeTag: string): string;
+}
+/** The ONE host capability this surface uses — a captured, typed, guaranteed-unique id. */
+function mint(typeTag: string): string {
+  return (globalThis as unknown as { nomos: NomosMint }).nomos.mint(typeTag);
+}
+
+/** A reference to an aggregate the dev HOLDS — minted-new (`create`) or bound-to-existing (`existing`). */
+export interface AggregateRef {
+  readonly __type: string;
+  readonly __id: string;
+  /** Set a scalar field (Lww). */
+  set(field: string, value: unknown): this;
+  /** Set one entry of a map field (per-key Lww). */
+  setEntry(field: string, key: string, value: unknown): this;
+  /** Add to a collection: a `t.hasMany` relation → writes the child's back-ref; a `t.set` → AddToSet on self. */
+  add(field: string, value: unknown): this;
+  /** Relate to another aggregate by reference (writes the ref field on THIS aggregate). */
+  relate(rel: string, target: AggregateRef): this;
+}
+
+class Ref implements AggregateRef {
+  constructor(
+    private readonly handle: AggregateHandle,
+    readonly __id: string,
+    private readonly birth: boolean,
+  ) {}
+  get __type(): string {
+    return this.handle.id;
+  }
+  /** Emit a field op TARGETING THIS aggregate, marked `creates` iff this ref is a birth. */
+  private emit(field: string, kind: FieldOp["kind"], extra: Partial<FieldOp>): void {
+    const op: FieldOp = { aggregateId: this.__id, aggregateType: this.__type, field, kind, ...extra };
+    sink.push(this.birth ? { ...op, marker: "creates" } : op);
+  }
+  set(field: string, value: unknown): this {
+    this.emit(field, "set", { value });
+    return this;
+  }
+  setEntry(field: string, key: string, value: unknown): this {
+    this.emit(field, "setEntry", { entryKey: key, value });
+    return this;
+  }
+  relate(rel: string, target: AggregateRef): this {
+    this.emit(rel, "set", { value: target.__id });
+    return this;
+  }
+  add(field: string, value: unknown): this {
+    // `.add` resolves the named member across the aggregate's two member kinds: a virtual
+    // `t.hasMany` relation (write the child's back-ref) vs a stored `t.set` field (AddToSet).
+    // The two collections are kept apart by `aggregate()`, so this is the ONE place that bridges them.
+    const rel = (this.handle.hasMany as Record<string, Field>)[field];
+    if (rel !== undefined) {
+      // RELATION: write the back-reference ON THE CHILD (the cheap N:1). The op lands in the CHILD's
+      // bucket with the CHILD's birth-marker — this aggregate (the parent) is never touched.
+      const child = value as Ref;
+      child.emit(rel.viaField!, "set", { value: this.__id });
+    } else {
+      // BOUNDED INTRINSIC SET: AddToSet on this aggregate itself.
+      const v = value instanceof Ref ? value.__id : String(value);
+      this.emit(field, "addToSet", { items: [v] });
+    }
+    return this;
+  }
+}
+
+/** Ask Nomos to CREATE a new aggregate of the handle's type → a fluent reference (id minted, no choice). */
+export function create(agg: AggregateHandle): AggregateRef {
+  return new Ref(agg, mint(agg.id), true);
+}
+
+/** A reference to an EXISTING aggregate the dev already holds an id for (e.g. from the payload / a read). */
+export function existing(agg: AggregateHandle, id: string): AggregateRef {
+  return new Ref(agg, id, false);
+}