@githolon/dsl 0.1.0

package/src/wire.ts

@@ -0,0 +1,149 @@
+// 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 kernel's wire shapes — byte-compatible with serde_json's externally-tagged
+ * enum encoding. These types mirror `nomos2/kernel/src/lib.rs` EXACTLY; the shape
+ * was discovered empirically (see FINDINGS.md) by serializing real kernel values.
+ *
+ * serde externally-tags enums:
+ *   - unit variant      -> bare string:  Driver::Lww            => "Lww"
+ *   - newtype variant   -> {Tag: inner}: Value::Int(10)         => {"Int":10}
+ *   - struct variant    -> {Tag: {..}}:  Op::SetEntry{key,value}=> {"SetEntry":{"key":..,"value":..}}
+ *   - newtype struct     -> transparent:  ReplicaId(7)           => 7
+ */
+
+/** `ReplicaId(pub u64)` serializes as a bare number. */
+export type WireReplicaId = number;
+
+/** `Hlc { physical: u64, logical: u32, replica: ReplicaId }`. */
+export interface WireHlc {
+  physical: number;
+  logical: number;
+  replica: WireReplicaId;
+}
+
+/** `Value = Str | Int | Set | Map | Evidence`. (Map only appears in *state*, never in an
+ * Op input here.) `Evidence` is the content-addressed EvidenceRef (evidence.md §1/§9.2):
+ * a struct-bearing newtype variant `{Evidence: {hash, media_type, byte_length,
+ * storage_class}}`, mirroring serde's externally-tagged encoding of
+ * `Value::Evidence(EvidenceRef)`. The field names are the kernel's SNAKE_CASE serde
+ * fields (`media_type`/`byte_length`/`storage_class`), and `storage_class` is the serde
+ * unit-variant bare string `"Git" | "External"`. */
+export type WireValue =
+  | { Str: string }
+  | { Int: number }
+  | { Set: string[] }
+  | { Map: Record<string, WireField> }
+  | { Evidence: WireEvidenceRef };
+
+/** `EvidenceRef { hash: ContentHash, media_type, byte_length, storage_class }` — the
+ * kernel serde shape. `ContentHash(String)` serializes transparently as a bare string
+ * (a newtype struct), and `StorageClass` as a bare unit-variant string. */
+export interface WireEvidenceRef {
+  hash: string;
+  media_type: string;
+  byte_length: number;
+  storage_class: "Git" | "External";
+}
+
+/** `Field { value: Value, stamp: Hlc }` — only used when reading state back. */
+export interface WireField {
+  value: WireValue;
+  stamp: WireHlc;
+}
+
+/** `Op = Set(Value) | AddToSet(BTreeSet<String>) | SetEntry { key, value }`. */
+export type WireOp =
+  | { Set: WireValue }
+  | { AddToSet: string[] }
+  | { SetEntry: { key: string; value: WireValue } };
+
+/** `FieldOp { field: FieldId, op: Op }`. */
+export interface WireFieldOp {
+  field: string;
+  op: WireOp;
+}
+
+/**
+ * `RefMode = Create | Mutate | Ensure | Archive` — the referential intent of an
+ * event's touch on its aggregate (serde unit-variant: a bare string). The DSL's
+ * `.creates`/`.mutates`/`.ensures`/`.archives` markers lower to these; the
+ * kernel's referential guard enforces them at write time. `serde(default)` is
+ * `Ensure`, so older unmarked wire stays permissive.
+ */
+export type WireRefMode = "Create" | "Mutate" | "Ensure" | "Archive";
+
+/**
+ * `Event { aggregate: AggregateId, marker: RefMode, ops: Vec<FieldOp> }` — one
+ * aggregate's mutations (the *where* + the field-ops) plus its referential
+ * marker. A directive that touches N aggregates emits N events (kernel
+ * #56, aggregate identity). `marker` is `serde(default)` = "Ensure".
+ */
+export interface WireEvent {
+  aggregate: string;
+  marker: WireRefMode;
+  ops: WireFieldOp[];
+}
+
+/**
+ * `Intent { id: IntentId, hlc: Hlc, strikes: Vec<IntentId>, events: Vec<Event> }`
+ * — one intent = one commit = the atomic unit. Carries the encoded event bundle: many
+ * per-aggregate events, all sharing the intent's HLC, all-or-nothing. This is the
+ * blob written as `intent.json`.
+ *
+ * `id` identifies the commit; `strikes` lists intent ids this intent retracts
+ * (the strike-out / revert hatch). Both are `serde(default)` on the kernel, so
+ * older wire payloads still deserialize.
+ *
+ * `reads` is the captured READ FOOTPRINT: the O(1) DSL-defined queries the plan read to justify
+ * this write, with their results, all taken at this intent's `hlc`. Replay serves each read from
+ * this record (never a live re-query) — determinism; and the gate can re-check a result against the
+ * projection at `hlc` to detect a stale premise — read/write conflict detection. OMITTED when empty
+ * so a read-free intent is byte-identical to before reads existed (`serde(default)`).
+ */
+export interface WireIntent {
+  id: string;
+  hlc: WireHlc;
+  strikes: string[];
+  events: WireEvent[];
+  reads?: WireRead[];
+}
+
+/**
+ * One captured O(1) DSL-query read on the write path (`aggregate_lifecycle_and_relations.md`). The
+ * plan reads through a declared, INDEXED query (never a scan); the engine records what was read and
+ * what came back, so the write's premise is committed, replayable, and auditable.
+ */
+export interface WireRead {
+  /** The O(1) DSL-defined query id (a managed index — e.g. the `t.hasMany` inverse). */
+  queryId: string;
+  /** The index key args the query was read with (key field -> value). */
+  args: Record<string, string>;
+  /** The captured result. Replay returns this verbatim; the gate may re-verify it against `hlc`. */
+  result: unknown;
+}
+
+/**
+ * `Driver` — the kernel's externally-tagged serde encoding (`nomos2/kernel/src/lib.rs`).
+ * Unit variants → bare strings; `MapOf` → `{ MapOf: <inner> }`. This mirrors the kernel
+ * variants the DSL `encodeDriver` emits: the four originals plus the structural CRDT unit
+ * drivers `RemoveWins` / `Counter` / `LastPosition` (each a real `merge_field` arm).
+ * (`NumericMax`/`NumericMin`/`ImmutableAfterCreate`/`OrderedList` are kernel variants no
+ * DSL driver encodes to yet — added here only as the DSL gains a constant for them.)
+ */
+export type WireDriver =
+  | "Lww"
+  | "AddWins"
+  | "Conflict"
+  | "RemoveWins"
+  | "Counter"
+  | "LastPosition"
+  | { MapOf: WireDriver };
+
+/** `Schema = BTreeMap<FieldId, Driver>` — a plain object, field -> Driver. */
+export type WireSchema = Record<string, WireDriver>;

package/src/wire_encode.ts

@@ -0,0 +1,250 @@
+// 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.
+
+/**
+ * Deterministic directive execution and kernel wire encoding.
+ *
+ *  - `encodeKernelSchema(agg)`  -> the kernel `Schema` JSON (field -> Driver) for one aggregate.
+ *  - `executeDirectiveToIntent(...)` -> a kernel-shaped `Intent` from a directive's
+ *    `plan(payload, ctx)`.
+ *
+ * #56 (aggregate identity): a directive's `plan` produces `PlannedOp`s that each
+ * carry their target `aggregateId`. `executeDirectiveToIntent` groups those ops by aggregate
+ * (in first-seen / authored order) into per-aggregate `Event`s and emits one
+ * `Intent{hlc, events}` — the atomic commit. A single-aggregate directive yields
+ * one event; a multi-aggregate one yields several. Proto/numeric-tag wire is a
+ * LATER coordinated migration — we target the current serde_json shape now.
+ */
+import { encodeDriver } from "./drivers.js";
+import { __resetAuthoring, __drainAuthoring } from "./authoring.js";
+import { __resetReads, __drainReads } from "./read.js";
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field, EvidenceRefValue } from "./fields.js";
+import type { Directive, ReferentialMarker } from "./directive.js";
+import type { PlannedOp, FieldOp } from "./ops.js";
+import type { Ports } from "./ctx.js";
+import type {
+  WireEvent,
+  WireHlc,
+  WireIntent,
+  WireFieldOp,
+  WireOp,
+  WireRefMode,
+  WireSchema,
+  WireValue,
+} from "./wire.js";
+
+/** Map a directive's referential marker onto the kernel `RefMode` wire string. */
+export function encodeRefMode(marker: ReferentialMarker): WireRefMode {
+  switch (marker) {
+    case "creates":
+      return "Create";
+    case "mutates":
+      return "Mutate";
+    case "ensures":
+      return "Ensure";
+    case "archives":
+      return "Archive";
+  }
+}
+
+/** Derive a deterministic intent id from its HLC (replayable across TS/Dart). */
+export function intentIdFromHlc(hlc: WireHlc): string {
+  return `${hlc.physical}.${hlc.logical}.${hlc.replica}`;
+}
+
+/** Encode one aggregate's fields as a kernel `Schema` (field id -> Driver). */
+export function encodeKernelSchema(agg: AggregateHandle): WireSchema {
+  const out: WireSchema = {};
+  // `agg.fields` is STORED fields only (virtual `t.hasMany` inverses live in `agg.hasMany`),
+  // so every member here belongs in the wire schema — there is no virtual kind to skip.
+  for (const [name, field] of Object.entries(agg.fields as Record<string, Field>)) {
+    out[name] = encodeDriver(field.driver);
+  }
+  return out;
+}
+
+/** Map an authored op value onto the kernel `Value` shape, given the field kind. */
+function encodeKernelValue(field: Field | undefined, value: unknown): WireValue {
+  // An `evidence` field encodes as the FIRST-CLASS kernel `Value::Evidence` (NOT a JSON
+  // string): the authored {hash, mediaType, byteLength, storageClass} maps to the
+  // kernel's snake_case serde shape + the `Git`/`External` unit-variant. Checked BEFORE
+  // the scalar fallthroughs (an evidence value is an object, never a Str/Int).
+  if (field?.kind === "evidence") {
+    const v = value as EvidenceRefValue;
+    return {
+      Evidence: {
+        hash: v.hash,
+        media_type: v.mediaType,
+        byte_length: v.byteLength,
+        storage_class: v.storageClass === "external" ? "External" : "Git",
+      },
+    };
+  }
+  // For scalar Set/SetEntry the kernel expects Str or Int. Maps store leaves;
+  // a map's entry value is a leaf scalar.
+  if (typeof value === "number" && Number.isInteger(value)) return { Int: value };
+  if (typeof value === "string") return { Str: value };
+  if (typeof value === "boolean") return { Str: String(value) };
+  // Enum values are strings; refs are id strings — both handled above.
+  // Anything else (object/array as a scalar) is JSON-encoded into a Str leaf.
+  if (field?.kind === "json") return { Str: JSON.stringify(value) };
+  throw new Error(
+    `Cannot encode value ${JSON.stringify(value)} for field '${field?.kind ?? "?"}': ` +
+      `kernel scalars are Str | Int only.`,
+  );
+}
+
+function encodeKernelFieldOp(op: FieldOp, field: Field | undefined): WireFieldOp {
+  let wireOp: WireOp;
+  switch (op.kind) {
+    case "set":
+      wireOp = { Set: encodeKernelValue(field, op.value) };
+      break;
+    case "addToSet":
+      wireOp = { AddToSet: [...(op.items ?? [])] };
+      break;
+    case "setEntry":
+      wireOp = {
+        SetEntry: { key: op.entryKey!, value: encodeKernelValue(field, op.value) },
+      };
+      break;
+  }
+  return { field: op.field, op: wireOp };
+}
+
+/**
+ * Run a directive: validate payload (Zod), call `plan`, group the resulting ops
+ * by aggregate (in first-seen / authored order) into per-aggregate `Event`s, and
+ * emit one kernel `Intent{hlc, events}` — the atomic, all-or-nothing commit (#56).
+ *
+ * A single-aggregate directive yields one event; a directive that touches several
+ * aggregates yields several events. The events keep authored order, so an aggregate created by an earlier
+ * event is visible to later events in the same intent (kernel in-intent apply).
+ *
+ * `agg` is the directive's declared target handle, used to resolve field kinds
+ * when encoding values; ops emitted to sibling aggregates encode by value-kind.
+ */
+export function executeDirectiveToIntent<P>(
+  directive: Directive<P>,
+  agg: AggregateHandle,
+  payload: NoInfer<P>,
+  ctx: Ports,
+): WireIntent {
+  if (directive.aggregateId !== agg.id) {
+    throw new Error(
+      `Directive '${directive.id}' targets aggregate '${directive.aggregateId}' ` +
+        `but was given handle '${agg.id}'.`,
+    );
+  }
+  const parsed = directive.payloadSchema.parse(payload);
+  const hlc = ctx.clock();
+  const marker = encodeRefMode(directive.marker);
+  // THE NOMOS SHAPE: a plan emits events across aggregates via TWO library doors, merged here —
+  //   (1) the fluent authoring surface (`create`/`.set`/`.add`/`.relate`) records ops into the sink;
+  //   (2) the plan may ALSO return explicit `PlannedOp`s (the typed `set`/`addToSet`/`strike` surface).
+  // Reset the sinks, run the plan, then merge authored ops (births/relations) ahead of the returned ops.
+  // The plan may also READ (O(1) DSL queries via `read(...)`) — captured into the footprint below.
+  __resetAuthoring();
+  __resetReads();
+  const returned = directive.plan(parsed, ctx);
+  const planned = [...__drainAuthoring(), ...returned];
+  const reads = __drainReads();
+
+  // Partition the plan output: STRIKE ops route onto the intent's `strikes` channel
+  // (the kernel's strikeout / revert facet, folded by parity); FIELD ops group into
+  // events below. A single plan may emit BOTH (strike X + author replacement ops =
+  // one atomic `replace` intent). Strikes are de-duped, authored order preserved.
+  const strikes: string[] = [];
+  const ops: FieldOp[] = [];
+  for (const op of planned) {
+    if (op.kind === "strike") {
+      if (!strikes.includes(op.target)) strikes.push(op.target);
+    } else {
+      ops.push(op);
+    }
+  }
+
+  // Group ops by aggregate id, preserving first-seen order (authored order).
+  // `aggregateId` is the address: for an unbound op it is the TYPE (legacy
+  // one-per-workspace shape); for an instance-bound op (`instance(h, id)`) it is
+  // the concrete INSTANCE id, with `aggregateType` carrying the TYPE (#105).
+  const order: string[] = [];
+  const byAggregate = new Map<string, WireFieldOp[]>();
+  // Per-bucket aggregate TYPE — only present for instance-bound ops. When set, we
+  // auto-stamp `__type`/`__id` provenance field-ops so `view()` (api.rs
+  // `project_view`) can recover the aggregate's TYPE off a per-instance id.
+  const typeOf = new Map<string, string>();
+  // Whether a bucket is the directive's OWN TARGET aggregate (the `creates`/`mutates`/…
+  // subject) vs an emitted sibling event. The directive's referential marker applies ONLY
+  // to its own target; an event emitted to ANOTHER aggregate is a MUTATE of an existing
+  // aggregate (NEVER a Create — the sibling is not being created here). This is the
+  // per-aggregate marker invariant the kernel id-mint gate now enforces: with the gate
+  // verifying EVERY `Create`, a `creates` directive that also touches a sibling aggregate
+  // (e.g. `createBuilding` adds the building to its parent site's `buildingIds`) must NOT mark the parent-site
+  // event `Create` — only the building. (Previously masked by the `__mintSeed` opt-in
+  // gate; the stronger gate makes the correct per-aggregate marker mandatory.)
+  const ownTarget = new Map<string, boolean>();
+  const explicitMarker = new Map<string, WireRefMode>();
+  const fieldsOf = agg.fields as Record<string, Field>;
+  for (const op of ops) {
+    let bucket = byAggregate.get(op.aggregateId);
+    if (bucket === undefined) {
+      bucket = [];
+      byAggregate.set(op.aggregateId, bucket);
+      order.push(op.aggregateId);
+    }
+    if (op.aggregateType !== undefined) typeOf.set(op.aggregateId, op.aggregateType);
+    if (op.marker !== undefined) {
+      const encoded = encodeRefMode(op.marker);
+      const existing = explicitMarker.get(op.aggregateId);
+      if (existing !== undefined && existing !== encoded) {
+        throw new Error(
+          `Directive '${directive.id}' emits conflicting markers for aggregate ` +
+            `'${op.aggregateId}': ${existing} vs ${encoded}.`,
+        );
+      }
+      explicitMarker.set(op.aggregateId, encoded);
+    }
+    // Field kinds are known for ops targeting the directive's own aggregate — by
+    // TYPE for a bound op (`aggregateType`), else by id for an unbound op. Ops
+    // fanning out to siblings encode by value-kind (the `json` path needs the kind).
+    const isOwnTarget =
+      op.aggregateType !== undefined ? op.aggregateType === agg.id : op.aggregateId === agg.id;
+    // A bucket is the own target if ANY of its ops target the directive's own aggregate.
+    if (isOwnTarget) ownTarget.set(op.aggregateId, true);
+    else if (!ownTarget.has(op.aggregateId)) ownTarget.set(op.aggregateId, false);
+    const field = isOwnTarget ? fieldsOf[op.field] : undefined;
+    bucket.push(encodeKernelFieldOp(op, field));
+  }
+
+  const events: WireEvent[] = order.map((aggregate) => {
+    const ops = byAggregate.get(aggregate)!;
+    const ty = typeOf.get(aggregate);
+    // The directive's marker applies to its OWN target; a FAN-OUT bucket is a Mutate of an
+    // existing sibling aggregate (so the id-mint gate never sees a spurious Create for it).
+    const eventMarker: WireRefMode =
+      explicitMarker.get(aggregate) ?? (ownTarget.get(aggregate) ? marker : "Mutate");
+    if (ty !== undefined) {
+      // Stamp provenance FIRST so the fold carries the TYPE + canonical id the
+      // structured `view()` projects (the same `__type`/`__id` reserved fields the
+      // Rust generic encoder path uses). Lww scalars — re-authoring is idempotent.
+      return {
+        aggregate,
+        marker: eventMarker,
+        ops: [
+          { field: "__type", op: { Set: { Str: ty } } },
+          { field: "__id", op: { Set: { Str: aggregate } } },
+          ...ops,
+        ],
+      };
+    }
+    return { aggregate, marker: eventMarker, ops };
+  });
+  // Attach the captured read footprint — OMITTED when empty so a read-free intent is byte-identical.
+  return { id: intentIdFromHlc(hlc), hlc, strikes, events, ...(reads.length ? { reads } : {}) };
+}