@githolon/dsl 0.70.2 → 0.72.0

package/src/idof_lint.ts

@@ -0,0 +1,144 @@
+// 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 PAYLOAD-REF idOf LINT (`architecture/dart_codegen_parity.md` P2 — ref ergonomics). A
+ * `t.ref(Target)` / `t.foreignRef(Target)` field on the AGGREGATE/read-model side already
+ * generates a TYPED id class (`SiteId`, `codegen_dart.ts`). Nothing enforced the payload SIDE
+ * carried the matching brand — a directive author can write `siteId: z.string()` in the
+ * payload and never discover `idOf(Site)` exists, so the generated Dart payload class carries a
+ * raw `String` while the read model carries `SiteId`: an asymmetry that forces manual
+ * `.value` unwrap/rewrap at the UI boundary and lets a mistyped id compile silently.
+ *
+ * THIS PASS closes that gap at COMPILE time: for every directive, plan-PROBE it (reusing the
+ * exact primitive the proof generator's own discovery legs use — `probePlanOps` /
+ * `synthesizePayload`, `codegen_proof.ts` — NOT a new AST interpreter) and, for every emitted
+ * field op that targets a ref-kind field, check whether the op's value is traceable to a
+ * TOP-LEVEL payload field whose zod schema is a bare (unbranded) string. If so: REFUSE, naming
+ * the directive, the payload field, the ref field, and its target aggregate, with the fix.
+ *
+ * SCOPE (deliberately narrow — a narrower lint with zero false positives beats a broad one with
+ * false refusals, per the authoring guidance):
+ *   - Only DIRECT, first-order plans: `create(Agg).set("ref", payload.path)` /
+ *     `setEntry(instance(Agg,...), "ref", key, payload.path)` — i.e. shapes the plan-probe
+ *     mechanism already observes as ONE emitted op whose `value` is byte-identical to a
+ *     TOP-LEVEL synthesized payload field's sample value. A value that is transformed,
+ *     concatenated, or nested more than one level deep inside the payload does NOT match
+ *     (no false positive — it simply isn't flagged; this is intentionally NOT full dataflow
+ *     analysis over the plan body).
+ *   - Only fires when the payload field's own sampled value round-trips EXACTLY into the op
+ *     (relies on `synthesizePayload`'s per-field-distinguishable string samples,
+ *     `"sample-<field>"` — the same discriminator the proof generator's own subject/grant-field
+ *     resolution already trusts, see `resolveGrantSubjectFields`).
+ *   - A directive whose plan can't be probed (unsynthesizable payload, or the plan throws under
+ *     the synthesized sample) is SKIPPED — best-effort, matching every other plan-probe
+ *     consumer in `codegen_proof.ts` (never a false refusal from an exotic shape).
+ *   - `idOf(Agg)` AND `brandedId(Name)` both satisfy the lint (either brand types the Dart/TS
+ *     side); only a truly BARE `z.string()` (through `.optional()`/`.default()`/`.nullable()`)
+ *     refuses.
+ *
+ * NOT era-gated: this is a pure Dart/TS-codegen build-time guard (like the domain-contracts
+ * circular-import guard in `compile_package_main.ts`) — it has no wire/manifest/kernel effect,
+ * changes no hash, and never touches already-deployed law. It only judges whether `nomos-compile`
+ * accepts a directive's SOURCE shape, exactly the same posture as that circular-dependency guard.
+ * A domain already using `idOf`/`brandedId` (or one with no ref-fed payload field at all) compiles
+ * exactly as before; only a directive whose payload feeds a ref field with a provably-bare string
+ * newly refuses — which is the intended fail-closed behaviour, not an accidental regression.
+ */
+import type { z } from "zod";
+
+import type { Directive } from "./directive.js";
+import type { FieldOp } from "./ops.js";
+import { probePlanOps } from "./codegen_proof.js";
+import { zodKind, zodDef, zodObjectShape } from "./codegen_ts.js";
+import { idOfMetaOf, brandedIdMetaOf } from "./value_object.js";
+
+/** A typed idOf-lint violation — the message names the directive, field, ref, and target. */
+export class IdOfLintError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IdOfLintError";
+  }
+}
+
+/** Short, lower-camel/PascalCase-preserving stem of an aggregate id (`inventory.EstateSite` → `EstateSite`),
+ *  matching the same "identity is the tail segment" convention `directive.ts`'s `shortName` uses. */
+function shortAggName(aggregateId: string): string {
+  return aggregateId.includes(".") ? aggregateId.slice(aggregateId.lastIndexOf(".") + 1) : aggregateId;
+}
+
+/** Peel `.optional()`/`.default()`/`.nullable()` to the innermost schema (mirrors `idOfMetaOf`/
+ *  `brandedIdMetaOf`'s own peeling, so a wrapped bare string is still caught). */
+function isBareString(zt: z.ZodTypeAny): boolean {
+  let cur: z.ZodTypeAny | undefined = zt;
+  for (let hops = 0; cur !== undefined && hops < 16; hops++) {
+    if (idOfMetaOf(cur) !== undefined || brandedIdMetaOf(cur) !== undefined) return false;
+    const kind = zodKind(cur);
+    if (kind === "string") return true;
+    if (kind !== "optional" && kind !== "default" && kind !== "nullable") return false;
+    cur = zodDef(cur).innerType;
+  }
+  return false;
+}
+
+/** Resolve a ref-kind field op's TARGET aggregate id (`t.ref` → `refAggregateId`/thunk; `t.foreignRef` →
+ *  `foreignRef.targetAggregateId`). `undefined` when neither meta is present (an exotic/hand-built field). */
+function refTargetOf(op: FieldOp): string | undefined {
+  const f = op.targetField as
+    | { refAggregateId?: string; foreignRef?: { targetAggregateId?: string } }
+    | undefined;
+  if (f === undefined) return undefined;
+  return f.refAggregateId ?? f.foreignRef?.targetAggregateId;
+}
+
+/**
+ * Run the idOf lint over one directive: plan-probe it and refuse on the first payload-fed
+ * ref-field mismatch. Throws {@link IdOfLintError}; a directive the prober can't run through
+ * (unsynthesizable payload / plan throws) is silently skipped — best-effort, no false refusal.
+ */
+export function assertIdOfLintForDirective(dir: Directive<unknown>, where: string): void {
+  const probed = probePlanOps(dir, where);
+  if (probed === undefined) return;
+  let shape: Record<string, z.ZodTypeAny>;
+  try {
+    shape = zodObjectShape(dir.payloadSchema as z.ZodTypeAny);
+  } catch {
+    return;
+  }
+  // Reverse index: sampled STRING value → the top-level payload field name(s) that produced it.
+  // `synthesizePayload` gives every string-kind field a DISTINCT `"sample-<field>"` value (or a
+  // schema-constrained fallback), so an exact match is unambiguous in practice.
+  const byValue = new Map<string, string>();
+  for (const [name, value] of Object.entries(probed.synth.value)) {
+    if (typeof value === "string") byValue.set(value, name);
+  }
+  for (const op of probed.ops) {
+    if (op.kind !== "set" && op.kind !== "setEntry") continue;
+    if (typeof op.value !== "string") continue;
+    const targetAgg = refTargetOf(op);
+    if (targetAgg === undefined) continue; // not a ref-kind field (or one the DSL can't name a target for)
+    const payloadField = byValue.get(op.value);
+    if (payloadField === undefined) continue; // not traceable to a top-level payload field — no verdict
+    const fieldSchema = shape[payloadField];
+    if (fieldSchema === undefined || !isBareString(fieldSchema)) continue; // already idOf/brandedId — fine
+    const onAgg = shortAggName(op.aggregateType ?? op.aggregateId);
+    const targetName = shortAggName(targetAgg);
+    throw new IdOfLintError(
+      `directive '${dir.id}': payload field '${payloadField}' feeds ref field '${onAgg}.${op.field}' ` +
+        `(-> ${targetName}) but is a plain z.string() — wrap it as idOf(${targetName}) so the generated ` +
+        `Dart/TS carry the typed id, matching the read model. (dart_codegen_parity.md P2)`,
+    );
+  }
+}
+
+/** Run the idOf lint over every directive in a domain. `domain` names the module for the probe's
+ *  error-context strings (`synthesizePayload`'s `where`). Throws on the FIRST violation. */
+export function assertIdOfLint(directives: readonly Directive<unknown>[], domain: string): void {
+  for (const dir of directives) {
+    assertIdOfLintForDirective(dir, `${domain}/${dir.id}`);
+  }
+}

package/src/index.ts

@@ -93,6 +93,7 @@ export {
   LastPosition,
   RemoveWins,
   Counter,
+  Surfaced,
   encodeDriver,
   type Driver,
   type DriverKind,

package/src/usd_layers.ts

@@ -109,6 +109,8 @@ export function usdaStringArray(items: readonly string[]): string {
 export function driverToken(driver: WireDriver): string {
   if (typeof driver === "string") return driver;
   if ("LwwBy" in driver) return `LwwBy(${driver.LwwBy})`;
+  // `Surfaced(<inner>)` — the user-resolvable posture stays legible in the tree too.
+  if ("Surfaced" in driver) return `Surfaced(${driverToken(driver.Surfaced)})`;
   return `MapOf(${driverToken(driver.MapOf)})`;
 }
 
@@ -117,6 +119,9 @@ export function parseDriverToken(token: string): WireDriver {
   if (token.startsWith("MapOf(") && token.endsWith(")")) {
     return { MapOf: parseDriverToken(token.slice("MapOf(".length, -1)) };
   }
+  if (token.startsWith("Surfaced(") && token.endsWith(")")) {
+    return { Surfaced: parseDriverToken(token.slice("Surfaced(".length, -1)) };
+  }
   // `LwwBy(<principal>)` — the principal is an opaque non-empty string (uids carry
   // hyphens, so it is NOT the bare-identifier shape the unit-driver branch validates).
   if (token.startsWith("LwwBy(") && token.endsWith(")")) {

package/src/wire.ts

@@ -219,7 +219,10 @@ export type WireDriver =
   | "Counter"
   | "LastPosition"
   | { LwwBy: string }
-  | { MapOf: WireDriver };
+  | { MapOf: WireDriver }
+  // `Surfaced(Box<Driver>)` — the user-resolvable third merge posture
+  // (architecture/surfaced_merge_conflict.md): `{ "Surfaced": <inner> }`.
+  | { Surfaced: WireDriver };
 
 /** `Schema = BTreeMap<FieldId, Driver>` — a plain object, field -> Driver. */
 export type WireSchema = Record<string, WireDriver>;