@githolon/dsl 0.101.2 → 0.101.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.101.2",
+  "version": "0.101.3",
   "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/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,
     };
   });