@githolon/dsl 0.101.2 → 0.101.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.101.2",
+  "version": "0.101.4",
   "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/compile_package_main.ts

@@ -2365,6 +2365,7 @@ async function main(): Promise<void> {
   // Exec the bin DIRECTLY (not via `node`): esbuild's postinstall replaces the
   // JS shim with the platform-native binary, which only an exec can run.
   const esbuildBin = path.join(path.dirname(esbuildPkgJson), esbuildBinRel ?? "bin/esbuild");
+  const esbuildMod = (await import(pathToFileURL(path.join(path.dirname(esbuildPkgJson), "lib", "main.js")).href)) as typeof import("esbuild");
 
   const canonicalizeEngineJavascript = (source: string): string => {
     // esbuild includes module labels derived from the package's install topology in
@@ -2391,7 +2392,6 @@ async function main(): Promise<void> {
     // package as the binary) so a resolve-plugin can stub zod's locale barrel to en-only —
     // the CLI binary has no plugin surface. Same bundle options + minify; deterministic
     // (pinned esbuild version, deterministic minifier).
-    const esbuildMod = (await import(pathToFileURL(path.join(path.dirname(esbuildPkgJson), "lib", "main.js")).href)) as typeof import("esbuild");
     const localeStripToEn = {
       name: "nomos-zod-locales-en-only",
       setup(build: import("esbuild").PluginBuild) {
@@ -2778,7 +2778,13 @@ async function main(): Promise<void> {
   // ── 5. the typed TS client (#10 — the web sibling of codegen_dart), with the
   //       deployed law's content hash baked in (emitted AFTER the package is hashed) ──
   const clientPath = path.join(outDir, `${cfg.name}.client.ts`);
-  writeFileSync(clientPath, generateTsClient(presentationDomainModules, { packageName: cfg.name, domainHash, interface: packageInterface, compat: nomosCompat }), "utf8");
+  const clientSource = generateTsClient(presentationDomainModules, { packageName: cfg.name, domainHash, interface: packageInterface, compat: nomosCompat });
+  try {
+    await esbuildMod.transform(clientSource, { loader: "ts", format: "esm", target: "es2020", logLevel: "silent" });
+  } catch (e) {
+    fail(`generated TypeScript client is not syntactically valid — this is a Nomos codegen bug: ${(e as Error).message}`);
+  }
+  writeFileSync(clientPath, clientSource, "utf8");
 
   // ── 6. the typed Dart frontend (opt-in; the Flutter sibling of step 5, emitted
   //       after the package hash like the TS client) ──

package/src/directive.ts

@@ -64,6 +64,12 @@ export interface PreconditionDescriptor {
   readonly predicate: (row: Record<string, unknown> | undefined) => boolean;
   /** The typed refusal code emitted when the predicate is false. */
   readonly rejectCode: string;
+  /**
+   * Why this precondition may intentionally make a fact about private state observable through its
+   * public refusal. Set by chaining `.declassify(reason)` directly after the precondition marker;
+   * carried onto the synthesized workspace invariant and into the replay-verified flow-gate law.
+   */
+  readonly declassify?: string;
 }
 
 /**
@@ -662,6 +668,43 @@ class DirectivePlanStep<Id extends string, P> {
     });
   }
 
+  /**
+   * Acknowledge that the MOST RECENT write-path precondition may intentionally reveal one fact about
+   * private state through its typed refusal. This is business policy, so it stays beside the condition
+   * it explains; the compiler carries it onto the generated invariant without exposing that internal
+   * invariant to tenant code.
+   */
+  declassify(reason: string): DirectivePlanStep<Id, P> {
+    const trimmed = reason.trim();
+    if (trimmed.length === 0) {
+      throw new Error(
+        `directive('${this.id}').declassify(reason) needs a non-empty human reason — it is the audit record for an intended private-state refusal.`,
+      );
+    }
+    if (this.preconditions.length === 0) {
+      throw new Error(
+        `directive('${this.id}').declassify(reason) must follow .requiresExisting(...), .where(...), or .withId(...).`,
+      );
+    }
+    const last = this.preconditions[this.preconditions.length - 1]!;
+    if (last.declassify !== undefined) {
+      throw new Error(
+        `directive('${this.id}') already declassifies its most recent precondition — declare each policy once, beside its condition.`,
+      );
+    }
+    return new DirectivePlanStep(
+      this.id,
+      this.marker,
+      this.aggregate,
+      this.payloadSchema,
+      this.createOnceIdField,
+      [
+        ...this.preconditions.slice(0, -1),
+        { ...last, declassify: trimmed },
+      ],
+    );
+  }
+
   plan(fn: (payload: P, ctx: Ports) => PlannedOp[]): RequirableDirective<P> {
     return makeRequirable({
       id: this.id,

package/src/flow_gate.ts

@@ -50,6 +50,7 @@ type FlowModule = {
     readonly id: string;
     readonly on: string;
     readonly declassify?: string;
+    readonly __nomosGenerated?: "directive-precondition";
     readonly reads: (ctx: { intent: Record<string, unknown>; principal?: string }) => readonly { readonly aggregate: string }[];
   }[];
   readonly impureCapabilities?: readonly {
@@ -190,6 +191,14 @@ export function assertFlowGate(m: CanonicalManifest, mod?: FlowModule): void {
       for (const r of refs) {
         const short = r.aggregate.includes(".") ? r.aggregate.slice(r.aggregate.lastIndexOf(".") + 1) : r.aggregate;
         if (privateTypes.has(short)) {
+          if (wi.__nomosGenerated === "directive-precondition") {
+            throw new FlowGateError(
+              `[nomosFlowGate rule 4 — no secret-correlated refusal] directive '${wi.on}' checks the PRIVATE aggregate ` +
+                `'${r.aggregate}' before committing. Its refusal can reveal a fact about that record. If that is intended, ` +
+                `keep the policy beside the condition: chain .declassify("<why this refusal may reveal private state>") ` +
+                `immediately after .requiresExisting(...), .where(...), or .withId(...).`,
+            );
+          }
           throw new FlowGateError(
             `[nomosFlowGate rule 4 — no secret-correlated refusal] workspaceInvariant '${wi.id}' (on '${wi.on}') reads the ` +
               `PRIVATE aggregate '${r.aggregate}' — its refusal is a public ref transition that can correlate with that secret. ` +

package/src/framework/workspace_invariant.ts

@@ -150,6 +150,8 @@ export interface WorkspaceInvariantDecl {
    * a secret-correlated refusal.
    */
   readonly declassify?: string;
+  /** Framework-only provenance used to keep compiler errors on the tenant-authored surface. */
+  readonly __nomosGenerated?: "directive-precondition";
   /** Brand so a plain object is never mistaken for a declaration. */
   readonly __isWorkspaceInvariant: true;
 }

package/src/law_check.ts

@@ -907,6 +907,12 @@ function invariantFindings(mod: DomainModule, aggById: ReadonlyMap<string, Aggre
     let intent: Record<string, unknown> = {};
     if (dir !== undefined) {
       const probe = probeDirective(dir, `${domain}/${wi.id}#intent`);
+      // A generated precondition's id selector is fully typed and only runs after payload validation.
+      // If Nomos cannot synthesize this directive's otherwise-valid exotic payload (for example a
+      // branded value object), invoking that selector with our invented `{}` would manufacture a
+      // framework false positive. Hand-authored invariants still get the empty-intent probe because
+      // their reads function may genuinely need to be total independently of a directive schema.
+      if (probe === undefined && wi.__nomosGenerated === "directive-precondition") continue;
       if (probe !== undefined) intent = probe.probePayload;
     }
     const ctx = { intent, principal: "principal:probe", principalVerified: true } as const;
@@ -935,12 +941,17 @@ function invariantFindings(mod: DomainModule, aggById: ReadonlyMap<string, Aggre
       }
     });
     if (threwAt !== undefined) {
+      const generatedPrecondition = wi.__nomosGenerated === "directive-precondition";
       out.push({
         domain,
         directiveId: wi.on,
         level: "warn",
-        what: `workspace invariant '${wi.id}' ${threwAt === "reads" ? "reads()" : "assert()"} THREW on the synthesized sample (${(err as Error)?.message ?? String(err)}) — a predicate bug, or a payload-dependent path the sample hit`,
-        fix: `run it on intent=${samplePayloadText(intent)} snapshots=${samplePayloadText(snapshots)} — if the throw is real, the gate refuses on '${wi.on}'; if the sample's shape never occurs, guard the predicate`,
+        what: generatedPrecondition
+          ? `directive '${wi.on}' precondition THREW on the synthesized payload (${(err as Error)?.message ?? String(err)}) — its id selector or predicate may not handle every valid payload`
+          : `workspace invariant '${wi.id}' ${threwAt === "reads" ? "reads()" : "assert()"} THREW on the synthesized sample (${(err as Error)?.message ?? String(err)}) — a predicate bug, or a payload-dependent path the sample hit`,
+        fix: generatedPrecondition
+          ? `run the directive's .requiresExisting(...), .where(...), or .withId(...) condition on ${samplePayloadText(intent)} — if that payload is valid, make the condition total for it`
+          : `run it on intent=${samplePayloadText(intent)} snapshots=${samplePayloadText(snapshots)} — if the throw is real, the gate refuses on '${wi.on}'; if the sample's shape never occurs, guard the predicate`,
       });
     }
   }

package/src/precondition.ts

@@ -86,6 +86,8 @@ export function synthesizePreconditionInvariants<P>(directive: Directive<P>): Wo
         const row = snapshots[REF_NAME] as Record<string, unknown> | undefined;
         return desc.predicate(row) ? { accept: true } : { reject: desc.rejectCode };
       },
+      ...(desc.declassify !== undefined ? { declassify: desc.declassify } : {}),
+      __nomosGenerated: "directive-precondition" as const,
       __isWorkspaceInvariant: true as const,
     };
   });

package/src/zod_lazy.ts

@@ -26,12 +26,22 @@ export function zodUnwrapLazy(zt: z.ZodTypeAny): z.ZodTypeAny {
 }
 
 const capFirst = (s: string): string => (s.length === 0 ? s : s[0]!.toUpperCase() + s.slice(1));
-const camelize = (s: string): string => s.replace(/[_\s-]+(\w)/g, (_m, c: string) => c.toUpperCase());
+
+/** Turn one structural path component into a valid TS/Dart identifier component.
+ * `*` is the record-value marker, not tenant vocabulary, so name it `Value`. */
+function typeNamePart(segment: string): string {
+  if (segment === "*") return "Value";
+  const words = segment.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  const joined = words.map(capFirst).join("") || "Field";
+  return /^[A-Za-z]/.test(joined) ? joined : `N${joined}`;
+}
 
 /**
  * A PascalCase type name from a payload path (`saveTree.root` → `SaveTreeRoot`), array markers
- * dropped. The SAME base the TS and Dart recursive-type synthesizers use so a recursive type's
- * TS alias and Dart class agree in the common case.
+ * dropped and record wildcards named `Value` (`saveJson.data.*` → `SaveJsonDataValue`). The SAME
+ * base the TS and Dart recursive-type synthesizers use so a recursive type's TS alias and Dart
+ * class agree in the common case. Every segment is sanitized here because schema object keys may
+ * contain punctuation even though generated language identifiers may not.
  */
 export function recursiveTypeBaseName(path: string): string {
   return (
@@ -39,7 +49,7 @@ export function recursiveTypeBaseName(path: string): string {
       .replace(/\[\]/g, "")
       .split(/[.]/)
       .filter(Boolean)
-      .map((s) => capFirst(camelize(s)))
+      .map(typeNamePart)
       .join("") || "Recursive"
   );
 }