@githolon/dsl 0.54.2 → 0.55.1

package/dart/lib/nomos_client.dart

@@ -26,6 +26,9 @@ library;
 export 'src/wire.dart';
 export 'src/driver.dart';
 export 'src/offer.dart';
+// THE TRI-STATE SLOT — NomosSlot<T> (Omitted / ExplicitNull / Present) for `nullable`/`clearable`
+// declared fields (architecture/null_semantics.md); generated code references it, never redefines it.
+export 'src/null_slot.dart';
 // homeNameOf(subject) — the canonical home-workspace name (parity with @githolon/client + the law side).
 export 'src/home.dart';
 export 'src/subscriptions.dart';

package/dart/lib/src/null_slot.dart

@@ -0,0 +1,128 @@
+// 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 TRI-STATE SLOT for a `nullable`-declared field (architecture/null_semantics.md).
+///
+/// JSON's one `null` collapses three DIFFERENT domain meanings the DSL names apart —
+/// OMISSION (not supplied / inherit), EXPLICIT CLEARING/EMPTY (a chosen `null`), and a
+/// PRESENT value. A plain `T?` cannot hold all three (its `null` is ambiguous). A field the
+/// domain declared `t.nullable(...)` / `t.clearable(...)` generates as a `NomosSlot<T>` so the
+/// call site MUST handle each case — the app-edge footgun (collapsing to `Object?`/`any`) is
+/// unrepresentable.
+///
+///  - [NomosSlot.omitted] — the field never folded / was not supplied. On a payload it is
+///    OMITTED from the wire JSON entirely (the plan never sees it).
+///  - [NomosSlot.explicitNull] — an explicit domain `null` (the `explicit-empty` semantic, or a
+///    `clearable` clear). On a payload it writes a real JSON `null`.
+///  - [NomosSlot.of] — a present [value]. On a payload it writes the value.
+///
+/// This is the DECODE contract on read models too: an ABSENT key decodes to [omitted], an
+/// explicit JSON `null` to [explicitNull], a value to `NomosSlot.of(value)` — the three are
+/// NEVER collapsed.
+sealed class NomosSlot<T> {
+  const NomosSlot();
+
+  /// The field was not supplied / has not folded — omitted from the wire entirely.
+  const factory NomosSlot.omitted() = _Omitted<T>;
+
+  /// An explicit domain `null` (the `explicit-empty` value, or a `clearable` clear) — writes a
+  /// real JSON `null` on the wire.
+  const factory NomosSlot.explicitNull() = _ExplicitNull<T>;
+
+  /// A present [value].
+  const factory NomosSlot.of(T value) = _Present<T>;
+
+  /// DECODE a projection/read-model json map entry into a slot: the key ABSENT ⇒ [omitted], an
+  /// explicit `null` ⇒ [explicitNull], any other value ⇒ `NomosSlot.of(decode(raw))`. The
+  /// [decode] callback turns the raw json leaf into the typed [T] (identity for a scalar; a
+  /// `VoClass.fromProjected` for a value object).
+  static NomosSlot<T> decode<T>(
+    Map<String, Object?> data,
+    String key,
+    T Function(Object value) decode,
+  ) {
+    if (!data.containsKey(key)) return NomosSlot<T>.omitted();
+    final raw = data[key];
+    if (raw == null) return NomosSlot<T>.explicitNull();
+    return NomosSlot<T>.of(decode(raw));
+  }
+
+  /// True when the field carries a present value.
+  bool get isPresent => this is _Present<T>;
+
+  /// True for the explicit-`null` case (a chosen clear/empty — distinct from omission).
+  bool get isExplicitNull => this is _ExplicitNull<T>;
+
+  /// True when the field was not supplied / has not folded.
+  bool get isOmitted => this is _Omitted<T>;
+
+  /// The present value, or `null` for both omission AND explicit-null. LOSSY on purpose — use
+  /// [when] to keep the three cases distinct; reach for this only when omitted≡null is fine.
+  T? get valueOrNull => switch (this) {
+        _Present<T>(:final value) => value,
+        _ => null,
+      };
+
+  /// Exhaustive handling of the three cases — the point of the slot (no case can be forgotten).
+  R when<R>({
+    required R Function() omitted,
+    required R Function() explicitNull,
+    required R Function(T value) present,
+  }) =>
+      switch (this) {
+        _Omitted<T>() => omitted(),
+        _ExplicitNull<T>() => explicitNull(),
+        _Present<T>(:final value) => present(value),
+      };
+
+  /// Serialise INTO a payload json map at [key]: [omitted] writes NOTHING (the key is absent),
+  /// [explicitNull] writes a real `null`, [NomosSlot.of] writes `encode(value)`. The [encode]
+  /// callback turns the typed value into its wire json leaf (identity for a scalar; `.toJson()`
+  /// for a value object).
+  void writeTo(
+    Map<String, Object?> data,
+    String key,
+    Object? Function(T value) encode,
+  ) {
+    switch (this) {
+      case _Omitted<T>():
+        break; // omitted ⇒ absent from the wire (the plan never sees the field)
+      case _ExplicitNull<T>():
+        data[key] = null;
+      case _Present<T>(:final value):
+        data[key] = encode(value);
+    }
+  }
+
+  @override
+  bool operator ==(Object other) =>
+      other is NomosSlot<T> &&
+      other.runtimeType == runtimeType &&
+      other.valueOrNull == valueOrNull;
+
+  @override
+  int get hashCode => Object.hash(runtimeType, valueOrNull);
+}
+
+final class _Omitted<T> extends NomosSlot<T> {
+  const _Omitted();
+  @override
+  String toString() => 'NomosSlot.omitted()';
+}
+
+final class _ExplicitNull<T> extends NomosSlot<T> {
+  const _ExplicitNull();
+  @override
+  String toString() => 'NomosSlot.explicitNull()';
+}
+
+final class _Present<T> extends NomosSlot<T> {
+  const _Present(this.value);
+  final T value;
+  @override
+  String toString() => 'NomosSlot.of($value)';
+}

package/dart/test/null_slot_test.dart

@@ -0,0 +1,51 @@
+import 'package:nomos_client/nomos_client.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('NomosSlot tri-state', () {
+    test('decode distinguishes omitted / explicit-null / present', () {
+      final present = NomosSlot.decode<String>({'x': 'hi'}, 'x', (v) => v as String);
+      final explicit = NomosSlot.decode<String>({'x': null}, 'x', (v) => v as String);
+      final omitted = NomosSlot.decode<String>(<String, Object?>{}, 'x', (v) => v as String);
+
+      expect(present.isPresent, isTrue);
+      expect(present.valueOrNull, 'hi');
+      expect(explicit.isExplicitNull, isTrue);
+      expect(explicit.valueOrNull, isNull);
+      expect(omitted.isOmitted, isTrue);
+      // The three NEVER collapse: explicit-null and omitted are distinct despite both valueOrNull==null.
+      expect(explicit == omitted, isFalse);
+    });
+
+    test('writeTo omits, writes real null, or writes value', () {
+      final data = <String, Object?>{};
+      const NomosSlot<String>.omitted().writeTo(data, 'a', (v) => v);
+      expect(data.containsKey('a'), isFalse); // omitted ⇒ absent
+
+      const NomosSlot<String>.explicitNull().writeTo(data, 'b', (v) => v);
+      expect(data.containsKey('b'), isTrue);
+      expect(data['b'], isNull); // explicit ⇒ real json null
+
+      const NomosSlot.of('v').writeTo(data, 'c', (v) => v);
+      expect(data['c'], 'v');
+    });
+
+    test('when() forces exhaustive handling', () {
+      String tag(NomosSlot<int> s) => s.when(
+            omitted: () => 'omitted',
+            explicitNull: () => 'null',
+            present: (v) => 'present:$v',
+          );
+      expect(tag(const NomosSlot.omitted()), 'omitted');
+      expect(tag(const NomosSlot.explicitNull()), 'null');
+      expect(tag(const NomosSlot.of(7)), 'present:7');
+    });
+
+    test('encode callback lowers a value object on writeTo', () {
+      final data = <String, Object?>{};
+      NomosSlot.of(const {'lat': 1, 'lng': 2})
+          .writeTo(data, 'loc', (v) => v);
+      expect(data['loc'], {'lat': 1, 'lng': 2});
+    });
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.54.2",
+  "version": "0.55.1",
   "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",

package/src/authoring.ts

@@ -99,6 +99,10 @@ export interface AggregateRef<F extends Record<string, Field> = Record<string, F
     key: string,
     value: UntypedFields<F> extends true ? unknown : MapValueOf<F[K]>,
   ): this;
+  /** EXPLICIT-CLEAR a `t.clearable(...)`/`t.nullable(...)` field (`architecture/null_semantics.md`) —
+   *  writes json `null` (lowered to a plain `Set`). The fluent sibling of the `clear(handle, "field")`
+   *  op; never hand-write `.set("field", null)`. */
+  clear(field: string): 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). */
@@ -152,6 +156,21 @@ class Ref implements AggregateRef {
     this.emit(rel, "set", { value: target.__id });
     return this;
   }
+  clear(field: string): this {
+    // EXPLICIT-CLEAR: write json null on a clearable/nullable field. The field must declare a
+    // null-admitting semantic (the encode-path guard refuses a null on a forbid field regardless).
+    const f = (this.handle.fields as Record<string, Field>)[field] as
+      | { isClearable?: true; nullSemantic?: string }
+      | undefined;
+    if (f !== undefined && f.isClearable !== true && f.nullSemantic !== "nullable") {
+      throw new Error(
+        `.clear('${field}'): '${field}' is not a clearable/nullable field — declare it t.clearable(...) ` +
+          `or t.nullable(..., { reason }) before clearing it.`,
+      );
+    }
+    this.emit(field, "set", { value: null });
+    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).

package/src/build_package.ts

@@ -60,6 +60,7 @@ import {
   synthesizeBirthQuotaInvariants,
 } from "./birth_meter.js";
 import { withBirthMeterExports } from "./birth_meter_ensure.js";
+import { withClearDirectives } from "./clear_directive.js";
 import { withAttestedReadExports, isTrustSourceDecl, type TrustSourceDecl } from "./attested.js";
 import type { RelationTypeDecl } from "./relation_schema.js";
 import { domainHash, emitManifestBytes } from "./manifest.js";
@@ -162,6 +163,10 @@ export function composeDomainModule(spec: DomainModuleSpec): DomainModule {
   // ATTESTED READS (slice B): a foreign-read-declaring domain gains the SourceFrontier
   // aggregate + its sanctioning ensure at the same seam (era-safe: others byte-identical).
   merged = withAttestedReadExports(merged);
+  // EXPLICIT-CLEAR LANE (null_semantics.md): every `t.clearable(field)` gains a generated
+  // `clear<Agg><Field>` directive (mutates + one clear op; `.requires` when declared) at the same
+  // seam — manifest-visible, kernel-gated, proof-covered. Clearable-free domains are byte-identical.
+  merged = withClearDirectives(merged);
 
   const byId = new Map<string, AggregateHandle>();
   for (const a of [...aggregatesOf(merged), ...(spec.extraAggregates ?? [])]) byId.set(a.id, a);

package/src/clear_directive.ts

@@ -0,0 +1,103 @@
+// 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 GENERATED CLEAR DIRECTIVE (architecture/null_semantics.md — the explicit-clear lane).
+ *
+ * A `t.clearable(field)` field admits an explicit-clear write (a Set of json `null`). So the framework
+ * MINTS the write lane for it: a real directive `clear<Agg><Field>` per clearable field, injected at
+ * the ONE module-merge seam every plane shares (compose / engine slice / self-describe / compile
+ * openapi) — the SAME precedent as `withBirthMeterExports` (the birth-record sanctioning ensure) and
+ * the secondary-ensure auto-declaration. Because it is a real directive, it is manifest-visible,
+ * kernel-gated, and proof gets the clear leg for free; the generated CLIENT can bind a `clearX()`
+ * method to its id.
+ *
+ * AUTHORITY IS EXPLICIT (the hard requirement): a clear is a WRITE, so a blanket ungated clear on a
+ * field whose sibling writes are `.requires`-gated would be an authz hole. `t.clearable(field, {
+ * requires })` carries the relation onto the generated directive's `.requires(relation)`; absent it,
+ * the lane is ungated BUT `law_check` WARNs when the aggregate has any `.requires`-gated directive
+ * touching it (see `law_check.ts` nullClearAuthorityFindings).
+ *
+ * ERA-SAFE: a domain with NO clearable field gets NO injection (byte-identical). A domain that USES
+ * clearable moves its hash — but it is NEW law by definition (the generated directive's
+ * `requiresRelationGate`/marker is real, certified law). Existing keys are never overwritten.
+ */
+import { z } from "zod";
+import { directive, type Directive, type RequirableDirective } from "./directive.js";
+import { instance, type AggregateHandle } from "./aggregate.js";
+import { clear } from "./ops.js";
+import type { Field } from "./fields.js";
+
+/** Capitalize the first character (the clear-directive id joins `clear` + AggId + Field). */
+function cap(s: string): string {
+  return s.length === 0 ? s : s[0]!.toUpperCase() + s.slice(1);
+}
+
+/**
+ * THE ID CONVENTION (tell the codegen agent — `clearX()` client methods bind to this): a clear
+ * directive is `clear${aggregateId}${Capitalized(field)}`. Aggregate ids are PascalCase, so `Screen`
+ * + `icon` → `clearScreenIcon`.
+ */
+export function clearDirectiveId(aggregateId: string, field: string): string {
+  return `clear${aggregateId}${cap(field)}`;
+}
+
+/**
+ * Build the generated clear directive for one `(aggregate, clearable field)`: marker `mutates(Agg)`,
+ * payload `{ id, clearedAt }` (the timestamp doctrine — `clearedAt` is auto-stamped, so the plan
+ * needn't read it), plan = the one `clear` op. `.requires(relation)` iff the field declared
+ * `clearRequires`.
+ */
+export function makeClearDirective(agg: AggregateHandle, field: string, requires?: string): Directive<unknown> {
+  const built = directive(clearDirectiveId(agg.id, field))
+    .mutates(agg)
+    .payload(z.object({ id: z.string().min(1), clearedAt: z.string() }))
+    .plan((p: { id: string; clearedAt: string }) => [clear(instance(agg, p.id), field as never)])
+    .doc(
+      `Explicitly clears the '${field}' field of a ${agg.id} (writes an explicit null — the declared clearable lane).`,
+    ) as unknown as RequirableDirective<unknown>;
+  return requires !== undefined ? built.requires(requires) : built;
+}
+
+/** The clearable `(field, requires?)` entries of one aggregate handle. */
+function clearableFieldsOf(agg: AggregateHandle): { field: string; requires?: string }[] {
+  const out: { field: string; requires?: string }[] = [];
+  for (const [name, f0] of Object.entries(agg.fields as Record<string, Field>)) {
+    if (f0.isClearable === true) out.push({ field: name, ...(f0.clearRequires !== undefined ? { requires: f0.clearRequires } : {}) });
+  }
+  return out;
+}
+
+/**
+ * Inject a generated {@link makeClearDirective} into a merged module-exports bag for EVERY clearable
+ * field on any aggregate in the bag. A clearable-free bag is returned UNTOUCHED (the era rule). An
+ * existing directive with the same id (a tenant hand-authored clear) is left in place — never
+ * overwritten (the `withBirthMeterExports` courtesy).
+ */
+export function withClearDirectives<M extends Record<string, unknown>>(mod: M): M {
+  const isAgg = (v: unknown): v is AggregateHandle =>
+    v !== null && typeof v === "object" && (v as { __isAggregateHandle?: boolean }).__isAggregateHandle === true;
+  const aggs = Object.values(mod).filter(isAgg);
+  if (aggs.length === 0) return mod;
+
+  // The directive ids already present (tenant-authored) — never re-mint over one.
+  const existingIds = new Set<string>();
+  for (const v of Object.values(mod)) {
+    if (v !== null && typeof v === "object" && typeof (v as Directive<unknown>).plan === "function" && typeof (v as Directive<unknown>).id === "string") {
+      existingIds.add((v as Directive<unknown>).id);
+    }
+  }
+
+  const additions: Record<string, unknown> = {};
+  for (const agg of aggs) {
+    for (const { field, requires } of clearableFieldsOf(agg)) {
+      const id = clearDirectiveId(agg.id, field);
+      if (existingIds.has(id) || id in mod) continue;
+      additions[id] = makeClearDirective(agg, field, requires);
+      existingIds.add(id);
+    }
+  }
+  return Object.keys(additions).length === 0 ? mod : ({ ...mod, ...additions } as M);
+}