@githolon/dsl 0.1.0

package/src/derived.ts

@@ -0,0 +1,138 @@
+// 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.
+
+/**
+ * `derived(id)` builder — an ENGINE-PROJECTED, PURE read field (read-engine: derived
+ * read fields).
+ *
+ * READ-CLOSURE, the projection half. A {@link query} declares a NAMED, INDEXED set read;
+ * a {@link count} declares a NAMED, MAINTAINED tally; a `derived` declares a NAMED, PURE
+ * FUNCTION of ONE aggregate's folded fields (e.g. `SupportSession.isTerminal =
+ * state ∈ {terminal states}`). The kernel ledger stays PURE user-intents — a derived
+ * value is NEVER stamped into an op/event; it is computed BY THE ENGINE during the
+ * projection projection and stored ONLY in the read model, so on a re-fold it is always
+ * re-derivable.
+ *
+ * It mirrors {@link count} at every turn: additive, omit-when-empty, identity-bearing in
+ * the CONTRACT sense (the field's NAME/type are part of the read schema), 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`/`count`'s `.of`. The fn
+ * BODY (`.as(...)`) is executable behaviour — it ships in the engine bundle and is NOT
+ * hashed into the domain identity (the same rule directives' `.plan` bodies follow).
+ *
+ * The TYPE-STATE: `derived(id)` yields a {@link TypelessDerived} whose ONLY method is
+ * `.of(...)`; the {@link DerivedOf} builder (carrying `.as(...)`) is produced solely by
+ * `.of(...)`; the finished {@link DerivedDecl} only by `.as(...)`. So a derived field
+ * with no `of`-type, or no fn body, cannot be CONSTRUCTED — "every derived field names
+ * the aggregate it derives from AND carries a pure fn" is a type-level property, before
+ * any runtime check.
+ */
+import type { z } from "zod";
+import type { AggregateHandle } from "./aggregate.js";
+
+/**
+ * The pure derive function: maps ONE aggregate's folded fields (a plain JSON object — the
+ * projection's projected `data` for that aggregate) to the derived value. MUST be pure
+ * (no ports, no I/O): it runs in the sealed engine over the host-fed `priorState` and its
+ * result is stored verbatim into the read model. The value is any JSON-serialisable scalar
+ * / object the read schema can decode (the smallest-first target is a `boolean`).
+ */
+export type DeriveFn = (aggregate: Record<string, unknown>) => unknown;
+
+/**
+ * A FINISHED derived-field declaration (the read engine's input shape, mirroring {@link
+ * CountDecl}): an id (the stored projection field name), the aggregate TYPE it derives
+ * from (`of`), and the pure `fn` body.
+ */
+export interface DerivedDecl {
+  /** The derived field's NAME — the key the read model stores it under. */
+  readonly id: string;
+  /** The aggregate TYPE id the field is derived from, e.g. `SupportSessionAggregate`. */
+  readonly of: string;
+  /** The JSON value schema the engine-projected field returns. */
+  readonly returns: z.ZodTypeAny;
+  /** The pure fn computing the value from the aggregate's folded fields. */
+  readonly fn: DeriveFn;
+}
+
+/**
+ * The {@link DerivedOf} BUILDER: it has named its `of`-type, so `.as(...)` (which fixes
+ * the pure fn and yields the finished {@link DerivedDecl}) is available. This is the ONLY
+ * shape carrying `.as` — see {@link TypelessDerived}.
+ */
+export interface DerivedOf {
+  readonly id: string;
+  /** The aggregate TYPE id the field derives from. */
+  readonly of: string;
+  /**
+   * Declare the projected value schema. A derived field without a return schema is not a
+   * read contract, because the read model/Dart surface would have to guess.
+   */
+  returns(schema: z.ZodTypeAny): DerivedReturns;
+}
+
+/**
+ * The {@link DerivedReturns} BUILDER: it has named its `of`-type AND value schema, so
+ * `.as(...)` can fix the executable body and yield the finished declaration.
+ */
+export interface DerivedReturns {
+  readonly id: string;
+  /** The aggregate TYPE id the field derives from. */
+  readonly of: string;
+  /** The JSON value schema the engine-projected field returns. */
+  readonly returns: z.ZodTypeAny;
+  /**
+   * Fix the PURE derive fn, producing the finished declaration. The fn receives the
+   * aggregate's folded fields and returns the derived value.
+   */
+  as(fn: DeriveFn): DerivedDecl;
+}
+
+/**
+ * The INITIAL, un-typed derived field — its ONLY method is `.of(...)`. It deliberately
+ * has NO `.as` and is not a {@link DerivedDecl}, so `derived("d").as(...)` (skipping the
+ * `of`-type) is a COMPILE error and a type-less derived field cannot be constructed. THIS
+ * is the type-level "every derived field names the aggregate it derives from" property.
+ */
+export interface TypelessDerived {
+  readonly id: string;
+  /**
+   * Declare the aggregate TYPE this field is derived from. Takes a typed HANDLE (never
+   * the string id) — a typo'd handle is a compile error, the same convention as
+   * `count`'s `.of(...)`. Returns the {@link DerivedOf} builder (the only shape exposing
+   * `.as`).
+   */
+  of(aggregate: AggregateHandle): DerivedOf;
+}
+
+/**
+ * Begin a derived-field declaration. Returns a {@link TypelessDerived}: until `.of(...)`
+ * is called, neither `.as` nor a usable declaration exists — the derived-from type is NOT
+ * optional, it is a prerequisite for the field to take any further shape.
+ */
+export function derived<const Id extends string>(id: Id): TypelessDerived {
+  return {
+    id,
+    of(aggregate: AggregateHandle): DerivedOf {
+      const ofType = aggregate.id;
+      return {
+        id,
+        of: ofType,
+        returns(schema: z.ZodTypeAny): DerivedReturns {
+          return {
+            id,
+            of: ofType,
+            returns: schema,
+            as(fn: DeriveFn): DerivedDecl {
+              return { id, of: ofType, returns: schema, fn };
+            },
+          };
+        },
+      };
+    },
+  };
+}

package/src/directive.ts

@@ -0,0 +1,306 @@
+// 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.
+
+/**
+ * `directive(id)` builder. A directive declares:
+ *  - a referential marker against an aggregate handle (.creates/.mutates/.ensures/.archives),
+ *  - a payload schema (Zod — the single source of truth + inference),
+ *  - a `plan((payload, ctx) => ops)` that returns declarative ops.
+ *
+ * The marker takes a typed HANDLE, never the string id — a typo'd handle is a
+ * compile error. The four markers are the referential relationships from
+ * contract §1 (creates/mutates/ensures/archives).
+ */
+import type { z } from "zod";
+import type { AggregateHandle } from "./aggregate.js";
+import type { PlannedOp } from "./ops.js";
+import type { Ports } from "./ctx.js";
+import type { CertifiedReadDecl } from "./certified_read.js";
+import type { RelationDecl } from "./relation.js";
+
+export type ReferentialMarker = "creates" | "mutates" | "ensures" | "archives";
+
+/**
+ * A pure, replay-stable derivation of the authz SCOPE an authored intent targets,
+ * from its payload — e.g. `(p) => ["site", p.siteId]`. It MUST be a pure function
+ * of the payload (no clock, no IO): the executor re-derives the same scope on
+ * replay, and `admit`'s authz gate folds the permission projection strictly-before
+ * the intent's HLC against exactly this scope.
+ */
+export type ScopeFrom<P> = (payload: P) => string[];
+
+export interface Directive<P = unknown> {
+  readonly id: string;
+  readonly marker: ReferentialMarker;
+  readonly aggregateId: string;
+  readonly payloadSchema: z.ZodType<P>;
+  readonly plan: (payload: P, ctx: Ports) => PlannedOp[];
+  /**
+   * Human-readable description of what this directive does — the SINGLE source of
+   * the hover-doc text codegen emits onto each generated payload class + ctor (so
+   * the frontend dev sees the intent's meaning at the call site). `undefined` ⇒ the
+   * directive declares no prose and codegen synthesises a sensible default from the
+   * directive id. Purely additive (a directive that never calls `.doc()` is
+   * byte-identical in the canonical manifest to before `description` existed).
+   */
+  readonly description?: string;
+  /**
+   * The capability an actor must hold to author this directive (the DECLARATIVE
+   * authz pre-condition). `undefined` ⇒ the directive declares no requirement and
+   * the gate's authz slot stays inert for it. When set, the kernel threads this
+   * into `Authored.required_caps` so `admit`'s authz step flips to `Enforce` once a
+   * `RoleCatalogue` is supplied. Defaults to the directive `id` (a directive's name
+   * IS its capability — the same convention the `RoleCatalogue` keys caps by).
+   */
+  readonly requiresCapability?: string;
+  /**
+   * Pure payload→scope derivation feeding `admit`'s `target` (see {@link ScopeFrom}).
+   * `undefined` ⇒ root scope. Authz checks the actor holds `requiresCapability` at
+   * a scope COVERING this target.
+   */
+  readonly scopeFrom?: ScopeFrom<P>;
+  /**
+   * The directive's DECLARED read boundary: the ref types its `plan` may READ (the
+   * "IR for law boundaries" decision — the boundary is part of the domain identity).
+   * Deduped + SORTED. Defaults to `[]` (declares no reads). The gate-side enforcement
+   * (read ⊆ declared) is a SEPARATE later step; here it only DECLARES.
+   */
+  readonly declaredReads: string[];
+  /**
+   * The directive's DECLARED emit boundary: the event types its `plan` may EMIT,
+   * each with an optional `max` bound. Part of the domain identity. Defaults to `{}`
+   * (declares no emits). Gate-side enforcement (emitted ⊆ declared) is a later step.
+   */
+  readonly declaredEmits: Record<string, { max?: number }>;
+  /**
+   * The directive's DECLARED CertifiedReads (survival Constraint 5; `certified_read.md`
+   * §"Tenant authoring"): the profiled, named write-path reads its `decide()` consults — the
+   * `reads:{ name: q.someProfiledRead(args) }` shape, keyed by the LOCAL binding name. Each
+   * value is a profile-conforming {@link CertifiedReadDecl} (compiled through SQL-profile-v0 at
+   * `certifiedRead(...).sql(...)`, so an under-specified read is refused at COMPILE). The
+   * declared `query_id`s LAND IN THE CERTIFIED MANIFEST (`manifest.ts`), so the ONE write-path
+   * gate (`executor::admit` step 5.6) DERIVES the expected declared-read set and REFUSES any
+   * admit where a declared read produced no witness (the vacuous-pass close). Defaults to `{}`
+   * (declares no write-path reads) — OMITTED ENTIRELY from the manifest when empty, so a
+   * read-free directive's canonical manifest is byte-identical to before this existed.
+   */
+  readonly declaredCertifiedReads: Record<string, CertifiedReadDecl>;
+  /**
+   * The directive's DECLARED cross-workspace relations (`cross_workspace.md` §2): the relations
+   * a cross-workspace PR proposing THIS directive is adjudicated against. The TARGET domain
+   * declares what it WILL ACCEPT — the source/target endpoints, the bounded evidence read it
+   * discloses, and that an invariant guards it. Each lands in the manifest IR keyed by its
+   * `proposes` directive, which the gate (`executor::admit` step 5.5) resolves to verify the
+   * carried evidence + evaluate the invariant against the target's OWN law + state. Defaults to
+   * `[]` (declares no relation) — OMITTED ENTIRELY from the manifest when empty, so a
+   * relation-free directive's canonical manifest is byte-identical to before this existed.
+   */
+  readonly declaredRelations: RelationDecl[];
+  /**
+   * The directive's DECLARED required HOST CAPABILITIES — the capability PORTS the HOST must
+   * PROVIDE for this directive to run (`TARGET_deps.dot` cluster_ports / `TARGET_flow.dot`
+   * cluster_ports, invariant 3). This is the HOST/PORT axis — "can this host PHYSICALLY do
+   * this?" — checked ONCE at policy LOAD against what the loading host ADVERTISES, FAIL-CLOSED
+   * (`required ⊆ provided`). It is DISTINCT from the AUTHZ axis {@link requiresCapability}
+   * ("may this ACTOR?", checked per-actor at admit): the two never conflate — a directive may
+   * require a host port AND an actor capability, and they are checked at different doors against
+   * different facts. The port id space is an OPEN SET (the framework fixes no list, e.g.
+   * `engine-verdict` / `blob-store` / `transcription`). Deduped + SORTED (the SET is the
+   * contract; order is incidental). Defaults to `[]` (declares no host requirement) — OMITTED
+   * ENTIRELY from the manifest when empty, so a host-capability-free directive's canonical
+   * manifest is byte-identical to before this existed (the pinned #136 hashes stay UNCHANGED).
+   */
+  readonly declaredHostCapabilities: string[];
+}
+
+/**
+ * The finished directive plus the chainable `.requires(...)` declaration. Domain
+ * devs DECLARE their authz pre-condition here rather than re-implementing it inside
+ * each `plan` — the kernel resolves it WITHIN the one shared `admit` gate.
+ */
+export interface RequirableDirective<P> extends Directive<P> {
+  /**
+   * Declare the authz pre-condition: the `capability` the actor must hold (defaults
+   * to the directive id) at the scope `scopeFrom(payload)` derives (defaults to root).
+   * Returns a new `Directive` carrying `requiresCapability` + `scopeFrom`.
+   */
+  requires(capability?: string, scopeFrom?: ScopeFrom<P>): RequirableDirective<P>;
+  /**
+   * Declare the directive's READ boundary: the ref types its `plan` may read. Callable
+   * MULTIPLE times to accumulate; results are deduped + sorted on the directive's
+   * `declaredReads`. Purely additive — a directive that never calls this declares no
+   * reads (`[]`) and is byte-identical in the canonical manifest to before this existed.
+   * Returns a NEW requirable directive (non-destructive).
+   */
+  reads(...refTypes: string[]): RequirableDirective<P>;
+  /**
+   * Declare ONE entry of the directive's EMIT boundary: an `eventType` its `plan` may
+   * emit, with an optional `max` count bound. Callable MULTIPLE times to accumulate
+   * distinct event types on `declaredEmits` (a repeated event type's later opts win).
+   * Purely additive — a directive that never calls this declares no emits (`{}`).
+   * Returns a NEW requirable directive (non-destructive).
+   */
+  emits(eventType: string, opts?: { max?: number }): RequirableDirective<P>;
+  /**
+   * Declare the directive's human-readable DESCRIPTION (the hover-doc text codegen
+   * emits onto the generated payload class). Purely additive + non-destructive —
+   * returns a NEW requirable directive carrying `description`. A directive that never
+   * calls this declares no prose (codegen falls back to a default derived from the id).
+   */
+  doc(description: string): RequirableDirective<P>;
+  /**
+   * Declare the directive's CertifiedReads (survival Constraint 5; `certified_read.md`
+   * §"Tenant authoring") — the profiled, named write-path reads its `decide()` consults, the
+   * `reads:{ name: q.someProfiledRead(args) }` shape. Each value is a {@link CertifiedReadDecl}
+   * (built via `certifiedRead("id").sql("…", {multiRow,uniqueTieBreakers})`, which refuses an
+   * under-specified read at COMPILE through SQL-profile-v0). The declared `query_id`s LAND IN
+   * THE CERTIFIED MANIFEST, so the ONE write-path gate DERIVES the required-read set and refuses
+   * any admit where a declared read produced no witness (the vacuous-pass close). Callable
+   * multiple times to accumulate (a repeated local name's later decl wins). Purely additive +
+   * non-destructive — a directive that never calls this declares no write-path reads (`{}`) and
+   * is byte-identical in the manifest to before this existed. Returns a NEW requirable directive.
+   */
+  readsCertified(reads: Record<string, CertifiedReadDecl>): RequirableDirective<P>;
+  /**
+   * Declare a cross-workspace relation (`cross_workspace.md` §2) this directive (the TARGET of a
+   * cross-workspace PR's `proposes`) is adjudicated against — built via
+   * `relation("Id").endpoints(src,tgt).proposes(directive, evidenceRead)`. The TARGET domain
+   * declares what it WILL ACCEPT; the gate resolves it from the certified manifest and verifies
+   * the carried evidence + evaluates the invariant against the target's OWN law + state
+   * (sovereignty, XWI4). Callable multiple times to accumulate. Purely additive + non-destructive
+   * — a directive that never calls this declares no relation (`[]`) and is byte-identical in the
+   * manifest to before this existed. Returns a NEW requirable directive.
+   */
+  declaresRelation(rel: RelationDecl): RequirableDirective<P>;
+  /**
+   * Declare ONE or more required HOST CAPABILITY ports (the HOST/PORT axis, invariant 3) — the
+   * capability PORTS the loading host must PROVIDE for this directive to run, checked at policy
+   * LOAD (`required ⊆ provided`, fail-closed), DISTINCT from the AUTHZ `.requires(...)` axis
+   * ("may this actor?"). The port id space is an OPEN SET (e.g. `"engine-verdict"`). Callable
+   * MULTIPLE times to accumulate; results are deduped + sorted on `declaredHostCapabilities`.
+   * Purely additive + non-destructive — a directive that never calls this declares no host
+   * requirement (`[]`) and is byte-identical in the canonical manifest to before this existed.
+   * Returns a NEW requirable directive.
+   */
+  requiresHostCapability(...portIds: string[]): RequirableDirective<P>;
+}
+
+/** Stage 1: id + a referential marker (which fixes the target aggregate). */
+class DirectiveMarkerStep<Id extends string> {
+  constructor(private readonly id: Id) {}
+  creates(agg: AggregateHandle): DirectivePayloadStep<Id> {
+    return new DirectivePayloadStep(this.id, "creates", agg.id);
+  }
+  mutates(agg: AggregateHandle): DirectivePayloadStep<Id> {
+    return new DirectivePayloadStep(this.id, "mutates", agg.id);
+  }
+  ensures(agg: AggregateHandle): DirectivePayloadStep<Id> {
+    return new DirectivePayloadStep(this.id, "ensures", agg.id);
+  }
+  archives(agg: AggregateHandle): DirectivePayloadStep<Id> {
+    return new DirectivePayloadStep(this.id, "archives", agg.id);
+  }
+}
+
+/** Stage 2: attach a Zod payload schema (drives `plan`'s payload type). */
+class DirectivePayloadStep<Id extends string> {
+  constructor(
+    private readonly id: Id,
+    private readonly marker: ReferentialMarker,
+    private readonly aggregateId: string,
+  ) {}
+  payload<S extends z.ZodTypeAny>(schema: S): DirectivePlanStep<Id, z.infer<S>> {
+    return new DirectivePlanStep(
+      this.id,
+      this.marker,
+      this.aggregateId,
+      schema as z.ZodType<z.infer<S>>,
+    );
+  }
+}
+
+/** Stage 3: define `plan`, producing the finished Directive. */
+class DirectivePlanStep<Id extends string, P> {
+  constructor(
+    private readonly id: Id,
+    private readonly marker: ReferentialMarker,
+    private readonly aggregateId: string,
+    private readonly payloadSchema: z.ZodType<P>,
+  ) {}
+  plan(fn: (payload: P, ctx: Ports) => PlannedOp[]): RequirableDirective<P> {
+    return makeRequirable({
+      id: this.id,
+      marker: this.marker,
+      aggregateId: this.aggregateId,
+      payloadSchema: this.payloadSchema,
+      plan: fn,
+      declaredReads: [],
+      declaredEmits: {},
+      declaredCertifiedReads: {},
+      declaredRelations: [],
+      declaredHostCapabilities: [],
+    });
+  }
+}
+
+/**
+ * Wrap a `Directive` with the chainable `.requires(...)` declaration. `.requires`
+ * is non-destructive: it returns a NEW requirable directive carrying the resolved
+ * `requiresCapability` (defaulting to the directive id) + `scopeFrom`, so the
+ * declaration site reads `directive(id)…plan(fn).requires("cap", p => […])`.
+ */
+function makeRequirable<P>(base: Directive<P>): RequirableDirective<P> {
+  return {
+    ...base,
+    requires(capability?: string, scopeFrom?: ScopeFrom<P>): RequirableDirective<P> {
+      return makeRequirable({
+        ...base,
+        requiresCapability: capability ?? base.id,
+        ...(scopeFrom !== undefined ? { scopeFrom } : {}),
+      });
+    },
+    reads(...refTypes: string[]): RequirableDirective<P> {
+      // Accumulate onto any prior reads, dedup, sort — order is incidental to the
+      // declared boundary; only the SET of read ref types is the contract.
+      const merged = [...new Set([...base.declaredReads, ...refTypes])].sort();
+      return makeRequirable({ ...base, declaredReads: merged });
+    },
+    emits(eventType: string, opts?: { max?: number }): RequirableDirective<P> {
+      // Accumulate one event type onto any prior emits; a `max` bound is recorded only
+      // when supplied (so `{}` vs `{max}` is a real contract difference).
+      const merged: Record<string, { max?: number }> = { ...base.declaredEmits };
+      merged[eventType] = opts?.max !== undefined ? { max: opts.max } : {};
+      return makeRequirable({ ...base, declaredEmits: merged });
+    },
+    doc(description: string): RequirableDirective<P> {
+      return makeRequirable({ ...base, description });
+    },
+    readsCertified(reads: Record<string, CertifiedReadDecl>): RequirableDirective<P> {
+      // Accumulate onto any prior declared CertifiedReads (a repeated local name's later decl
+      // wins) — additive, non-destructive. The local binding NAME (the key) is what `decide`
+      // reads via `reads.<name>`; the decl's `queryId` is the manifest-landed identity.
+      const merged: Record<string, CertifiedReadDecl> = { ...base.declaredCertifiedReads, ...reads };
+      return makeRequirable({ ...base, declaredCertifiedReads: merged });
+    },
+    declaresRelation(rel: RelationDecl): RequirableDirective<P> {
+      // Accumulate onto any prior relations — additive, non-destructive. A relation lands in
+      // the manifest keyed by its `proposes` directive (cross_workspace.md §3.2.1).
+      return makeRequirable({ ...base, declaredRelations: [...base.declaredRelations, rel] });
+    },
+    requiresHostCapability(...portIds: string[]): RequirableDirective<P> {
+      // Accumulate onto any prior host-capability ports, dedup, sort — order is incidental to
+      // the HOST/PORT contract; only the SET of required port ids matters. DISTINCT symbol from
+      // the AUTHZ `requiresCapability` (the two axes never conflate).
+      const merged = [...new Set([...base.declaredHostCapabilities, ...portIds])].sort();
+      return makeRequirable({ ...base, declaredHostCapabilities: merged });
+    },
+  };
+}
+
+export function directive<const Id extends string>(id: Id): DirectiveMarkerStep<Id> {
+  return new DirectiveMarkerStep(id);
+}

package/src/drivers.ts

@@ -0,0 +1,95 @@
+// 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.
+
+/**
+ * Merge-driver palette. A domain dev tags each field with a Driver; the kernel
+ * owns the actual merge algebra. EVERY driver in this palette encodes to a kernel
+ * merge arm today — `RemoveWins`/`Counter`/`LastPosition` each have a real
+ * `merge_field` arm in `nomos2/kernel/src/lib.rs` (2P-set union, PN-counter
+ * per-replica MAX, LWW-by-HLC position), so they encode like the rest. The
+ * PALETTE_ONLY mechanism + throw remain for any FUTURE driver added to this
+ * palette ahead of its kernel merge arm — never silently emit an unsupported wire driver.
+ */
+import type { WireDriver } from "./wire.js";
+
+/**
+ * Drivers the kernel implements today — each has a real `merge_field` arm in
+ * `nomos2/kernel/src/lib.rs`. `MapOf` is the composition primitive; the unit
+ * drivers encode to the kernel's serde unit-variant strings.
+ */
+export type KernelDriverKind =
+  | "Lww"
+  | "AddWins"
+  | "MapOf"
+  | "Conflict"
+  | "RemoveWins"
+  | "Counter"
+  | "LastPosition";
+/**
+ * Drivers in the design palette the kernel does not yet merge. Currently EMPTY —
+ * every palette driver encodes. Kept as a (never-)union so a future palette
+ * addition that outruns its kernel merge arm has a typed home + the throw below.
+ */
+export type PaletteOnlyKind = never;
+
+export type DriverKind = KernelDriverKind | PaletteOnlyKind;
+
+export interface Driver {
+  readonly kind: DriverKind;
+  /** Only present for MapOf. */
+  readonly inner?: Driver;
+}
+
+export const Lww: Driver = { kind: "Lww" };
+export const AddWins: Driver = { kind: "AddWins" };
+export const Conflict: Driver = { kind: "Conflict" };
+export const MapOf = (inner: Driver): Driver => ({ kind: "MapOf", inner });
+
+// Structural CRDT drivers — each encodes to its kernel `merge_field` arm
+// (`kernel/src/lib.rs`): LastPosition = LWW-by-HLC over a position value,
+// RemoveWins = 2P-set union(adds)−union(removes), Counter = PN-counter
+// per-replica MAX. Authorable against the full vocabulary AND encodable.
+export const LastPosition: Driver = { kind: "LastPosition" };
+export const RemoveWins: Driver = { kind: "RemoveWins" };
+export const Counter: Driver = { kind: "Counter" };
+
+// Drivers in the palette the kernel does NOT yet merge — currently NONE. A future
+// palette driver added ahead of its `merge_field` arm goes here; `encodeDriver`
+// throws for it rather than emit a wire driver the kernel can't merge.
+const PALETTE_ONLY: ReadonlySet<DriverKind> = new Set<DriverKind>([]);
+
+/** Encode one Driver to its kernel wire shape, or throw if not yet in the kernel. */
+export function encodeDriver(d: Driver): WireDriver {
+  switch (d.kind) {
+    case "Lww":
+      return "Lww";
+    case "AddWins":
+      return "AddWins";
+    case "Conflict":
+      return "Conflict";
+    // ── structural CRDT drivers (kernel `merge_field` arms) ──
+    case "RemoveWins":
+      return "RemoveWins";
+    case "Counter":
+      return "Counter";
+    case "LastPosition":
+      return "LastPosition";
+    case "MapOf":
+      if (!d.inner) throw new Error("MapOf driver is missing its inner driver");
+      return { MapOf: encodeDriver(d.inner) };
+    default:
+      if (PALETTE_ONLY.has(d.kind)) {
+        throw new Error(
+          `Driver '${d.kind}' is in the Nomos palette but not yet in the kernel — ` +
+            `cannot encode. Implement its merge_field arm in nomos2/kernel first, ` +
+            `or pick one of: Lww, AddWins, MapOf, Conflict, RemoveWins, Counter, ` +
+            `LastPosition.`,
+        );
+      }
+      throw new Error(`Unknown driver kind '${(d as Driver).kind}'`);
+  }
+}

package/src/emits_guard.ts

@@ -0,0 +1,123 @@
+// 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 PURE runtime enforcement primitive for the declared EMIT boundary (#138).
+ *
+ * `directive.ts` lets a directive DECLARE its emit boundary — `emits(eventType,
+ * {max?})` — recording it on `declaredEmits` and (via `manifest.ts` / `usd.ts`)
+ * folding it into the domain identity. That declaration is, today, DECORATIVE: the
+ * comment in `directive.ts` says "Gate-side enforcement (emitted ⊆ declared) is a
+ * later step." This module supplies the missing enforcement PRIMITIVE — the pure
+ * function the gate / `executeDirectiveToIntent` will call once the (gated) flip is enabled.
+ *
+ * It is PURE: no clock, no IO, no global state. Given a directive's declared emit
+ * set and the event types its `plan` actually emitted, it either returns (the
+ * emission is within the boundary) or throws a typed {@link EmitBoundaryError}. It
+ * does NOT invent an event registry, does NOT touch the wire/kernel shapes, and is
+ * NOT wired into any live dispatch path here — wiring it in is the later, Jack-gated
+ * step (it re-bakes the pinned `r1_nomos.wasm` or plumbs the declared set through the
+ * engine host; see the increment's report).
+ *
+ * The boundary has two clauses, BOTH fail-closed:
+ *  - UNDECLARED: an emitted event type NOT present in `declared` is refused — the
+ *    plan emitted something its contract never promised (emitted ⊆ declared).
+ *  - OVER-MAX: an emitted type present in `declared` with a `max` bound, emitted MORE
+ *    than `max` times, is refused. A declared type with NO `max` is unbounded in count
+ *    (it is still bounded in KIND by the undeclared clause).
+ */
+
+/** One declared emit clause: an optional `max` count bound (absent ⇒ unbounded count). */
+export type DeclaredEmit = { max?: number };
+
+/** A directive's declared emit boundary: event type → its clause. */
+export type DeclaredEmits = Record<string, DeclaredEmit>;
+
+/** Which boundary clause an emission violated. */
+export type EmitBoundaryRule =
+  /** An emitted event type is NOT in the declared set (emitted ⊄ declared). */
+  | "undeclared"
+  /** A declared type's emitted count exceeded its declared `max`. */
+  | "over-max";
+
+/** A typed, fail-closed emit-boundary violation. Pure — carries only the offending
+ * event type + (for `over-max`) the counts, never IO state. */
+export class EmitBoundaryError extends Error {
+  readonly rule: EmitBoundaryRule;
+  /** The offending event type. */
+  readonly eventType: string;
+  /** The number of times `eventType` was emitted. */
+  readonly emitted: number;
+  /** The declared `max` for `eventType` — only meaningful for `over-max`. */
+  readonly max?: number;
+  constructor(rule: EmitBoundaryRule, eventType: string, emitted: number, max?: number) {
+    super(
+      rule === "undeclared"
+        ? `emit boundary: event type "${eventType}" was emitted but is not declared`
+        : `emit boundary: event type "${eventType}" emitted ${emitted} times exceeds ` +
+          `declared max ${max}`,
+    );
+    this.name = "EmitBoundaryError";
+    this.rule = rule;
+    this.eventType = eventType;
+    this.emitted = emitted;
+    if (max !== undefined) this.max = max;
+  }
+}
+
+/**
+ * Assert an emission is WITHIN a directive's declared emit boundary (the primitive
+ * the gate / `executeDirectiveToIntent` will call once the flip is live). PURE: no IO, no clock,
+ * no global state — a function of `(declared, emitted)` alone.
+ *
+ *  - Throws `EmitBoundaryError("undeclared", t)` for the FIRST emitted type `t` not
+ *    present in `declared` (emitted ⊆ declared).
+ *  - Throws `EmitBoundaryError("over-max", t, count, max)` for the FIRST declared type
+ *    `t` whose emitted COUNT exceeds its declared `max`. A clause with no `max` is
+ *    count-unbounded.
+ *  - Returns (void) when every emitted type is declared and within its `max`. Empty
+ *    `emitted` is always within any `declared` (including empty).
+ *
+ * The undeclared check runs FIRST (in `emitted` order): an undeclared type is the
+ * stronger violation (the plan emitted a KIND it never promised), so it is reported
+ * before any over-count of a declared type.
+ */
+export function assertEmitsWithinDeclared(
+  declared: DeclaredEmits,
+  emitted: string[],
+): void {
+  // Count each emitted type once, in first-seen order, so reporting is deterministic.
+  const counts = new Map<string, number>();
+  const order: string[] = [];
+  for (const eventType of emitted) {
+    const prior = counts.get(eventType);
+    if (prior === undefined) {
+      counts.set(eventType, 1);
+      order.push(eventType);
+    } else {
+      counts.set(eventType, prior + 1);
+    }
+  }
+
+  // Clause 1 (stronger): every emitted KIND must be declared.
+  for (const eventType of order) {
+    if (!Object.prototype.hasOwnProperty.call(declared, eventType)) {
+      throw new EmitBoundaryError("undeclared", eventType, counts.get(eventType)!);
+    }
+  }
+
+  // Clause 2: a declared type with a `max` must not be emitted more than `max` times.
+  for (const eventType of order) {
+    const max = declared[eventType]!.max;
+    if (max !== undefined) {
+      const count = counts.get(eventType)!;
+      if (count > max) {
+        throw new EmitBoundaryError("over-max", eventType, count, max);
+      }
+    }
+  }
+}