@githolon/dsl 0.15.0 → 0.16.1

package/src/flow_gate.ts

@@ -0,0 +1,208 @@
+// NOMOS — the domain security model as a STATIC information-flow gate
+// (architecture/security_model.md). A domain's security is a property of its
+// compiled law; this pass makes leaky law UNREPRESENTABLE — the compiler refuses a
+// domain that could ever emit a secret through one of the offer kernel's finite
+// public sinks (refusal/ref transition, captured read, read group/key/where,
+// public field, outbound offer). The irreducible remainder — flows the author
+// INTENDS — is forced into an explicit, audited `declassify(reason)` (a later slice).
+//
+// v1 (this file): the two CONFIDENTIALITY rules that never have a legitimate
+// exception, so they hard-refuse with no `declassify` escape, and both read only
+// canonical manifest IR (no plan-AST interpreter needed — the captured-read-private
+// constraint already severed the plan from foreign secrets):
+//   Rule 1 — no encrypt-then-index   (an .encrypted() field used as a group/key/where/value)
+//   Rule 2 — no private read on chain (a captured read returning a requires(cap) type)
+// Integrity (who may WRITE) is gated natively at admission by `.requires(relation)`;
+// the integrity-flow dual + rule 4 (secret-correlated refusal) + `declassify` + the
+// `nomosFlowGate` era key are the next slices.
+import type { CanonicalManifest } from "./manifest.js";
+import type { CanonicalPred } from "./predicate.js";
+
+/** A read projection, read structurally — every read kind (query / count / sum / extremum /
+ *  ordered) carries its target type (`of`, or a string `returns`) and the fields it observes
+ *  (`key` / `by` / `valueField` / `where`). Loose by design — one walk over all read shapes. */
+type Projection = {
+  readonly id?: string;
+  readonly queryId?: string;
+  readonly of?: string;
+  readonly returns?: unknown;
+  readonly key?: readonly string[];
+  readonly by?: string;
+  readonly valueField?: string;
+  readonly where?: CanonicalPred;
+};
+
+/** The raw module bits rule 4 needs that the canonical manifest strips (the executable
+ *  invariant `.reads` + the declassify waivers). Read structurally — no coupling to DomainModule. */
+type FlowModule = {
+  readonly aggregates?: readonly {
+    readonly id: string;
+    readonly hasInvariant?: boolean;
+    readonly invariantDeclassify?: string;
+    readonly encryptedFields?: readonly string[];
+    readonly fields?: Record<string, unknown>;
+  }[];
+  readonly workspaceInvariants?: readonly {
+    readonly id: string;
+    readonly on: string;
+    readonly declassify?: string;
+    readonly reads: (ctx: { intent: Record<string, unknown>; principal?: string }) => readonly { readonly aggregate: string }[];
+  }[];
+  readonly impureCapabilities?: readonly {
+    readonly name?: string;
+    readonly capability?: string;
+    readonly endpoint?: string;
+    readonly declassify?: string;
+    readonly aggregate: { readonly id: string };
+  }[];
+};
+
+/** A typed flow-gate violation — the message names the field, the sink, and the rule. */
+export class FlowGateError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FlowGateError";
+  }
+}
+
+/** The set of field names a `where` predicate OBSERVES (a filter on a value is observing it). */
+function predFields(p: CanonicalPred | undefined): string[] {
+  if (!p) return [];
+  if (p.kind === "eq" || p.kind === "ne") return [p.field];
+  return p.clauses.flatMap(predFields);
+}
+
+/**
+ * Run the static information-flow gate over a domain's canonical manifest. Throws a
+ * {@link FlowGateError} on the first violation (a typed compile error). Pure over
+ * manifest IR — no side effects, no AST.
+ */
+export function assertFlowGate(m: CanonicalManifest, mod?: FlowModule): void {
+  // ── RULE 1 — NO ENCRYPT-THEN-INDEX ──────────────────────────────────────────
+  // A field that is .encrypted() (operator-blind ciphertext) MUST NOT appear in any
+  // read's group-by / key / value / where over its own type: grouping/indexing/
+  // filtering/summing BY a value observes it, so the encryption is defeated and the
+  // ciphertext-size + membership metadata leaks. Pure manifest-shape check.
+  const encByType = new Map<string, Set<string>>();
+  for (const a of m.aggregates) {
+    if (a.encryptedFields && a.encryptedFields.length > 0) encByType.set(a.id, new Set(a.encryptedFields));
+  }
+  if (encByType.size > 0) {
+    const typeOf = (p: Projection): string | undefined =>
+      p.of ?? (typeof p.returns === "string" ? p.returns : undefined);
+    const fieldsOf = (p: Projection): (string | undefined)[] =>
+      [...(p.key ?? []), p.by, p.valueField, ...predFields(p.where)];
+    const reads: { list: readonly Projection[]; sink: string }[] = [
+      { list: (m.queries ?? []) as unknown as Projection[], sink: "a query key" },
+      { list: (m.counts ?? []) as unknown as Projection[], sink: "a count group / where" },
+      { list: (m.sums ?? []) as unknown as Projection[], sink: "a sum group / value / where" },
+      { list: [...(m.mins ?? []), ...(m.maxes ?? [])] as unknown as Projection[], sink: "an extremum group / value / where" },
+      { list: (m.orderedReads ?? []) as unknown as Projection[], sink: "an ordered-read key / where" },
+    ];
+    for (const { list, sink } of reads) {
+      for (const p of list) {
+        const type = typeOf(p);
+        if (type === undefined) continue;
+        const enc = encByType.get(type);
+        if (!enc) continue;
+        for (const f of fieldsOf(p)) {
+          if (f !== undefined && enc.has(f)) {
+            throw new FlowGateError(
+              `[nomosFlowGate rule 1 — no encrypt-then-index] '${type}.${f}' is .encrypted() but is used as ${sink} ` +
+                `('${p.id ?? p.queryId ?? "?"}'). Grouping / indexing / filtering / summing BY a value observes it — the ` +
+                `encryption is defeated and the ciphertext-size + membership metadata leaks. Encrypt the field OR index a ` +
+                `plaintext one, never both.`,
+            );
+          }
+        }
+      }
+    }
+  }
+
+  // ── RULE 2 — NO PRIVATE READ RESULT ON THE CHAIN ────────────────────────────
+  // A captured read (`.reads(Q)` on the write path) whose Q returns a private type
+  // would write its PLAINTEXT result onto the intent on main — public, signed,
+  // replay-verified — bypassing the read gate AND the encryption envelope. Private
+  // data may only leave via the gated read path (query/qbyid), never a captured read.
+  const privateTypes = new Set(m.aggregates.filter((a) => a.requiresRead !== undefined).map((a) => a.id));
+  if (privateTypes.size > 0) {
+    for (const d of m.directives) {
+      for (const cr of (d.capturedReads ?? []) as { queryId: string; returns: string }[]) {
+        if (privateTypes.has(cr.returns)) {
+          throw new FlowGateError(
+            `[nomosFlowGate rule 2 — no private read on the chain] directive '${d.id}': captured read '${cr.queryId}' ` +
+              `returns the PRIVATE type '${cr.returns}'. A .reads() of a requires(cap) query writes its plaintext result ` +
+              `onto the intent on main as public, signed, replay-verified data — bypassing the read gate. Private data may ` +
+              `only leave via the gated read path (query / qbyid), never a captured read.`,
+          );
+        }
+      }
+    }
+  }
+
+  // ── RULE 4 — NO SECRET-CORRELATED REFUSAL (abort-cohort, Send Prop 4) ────────
+  // A refusal is a PUBLIC ref transition (refs/heads/{refused,parked}/<offer>). If the
+  // DECISION to refuse depends on a secret, the refusal leaks it. Conservative + declared-
+  // set based (no predicate-body analysis): an invariant that READS a private aggregate may
+  // correlate its refusal with that secret. This FLAGS (require declassify) rather than
+  // hard-refusing, because a secret-gated refusal is often INTENDED (the overdraft case).
+  if (mod && privateTypes.size > 0) {
+    // 4a — an aggregate `invariant` over a private aggregate with a plaintext field.
+    for (const a of mod.aggregates ?? []) {
+      if (!a.hasInvariant || !privateTypes.has(a.id) || a.invariantDeclassify) continue;
+      const enc = new Set(a.encryptedFields ?? []);
+      const hasPlaintext = Object.keys(a.fields ?? {}).some((f) => !enc.has(f));
+      if (!hasPlaintext) continue; // fully-encrypted: the invariant reads only ciphertext — can't leak this way
+      throw new FlowGateError(
+        `[nomosFlowGate rule 4 — no secret-correlated refusal] aggregate '${a.id}' is private (requires a read cap) and ` +
+          `declares an invariant over plaintext field(s) — its refusal is a public ref transition that can correlate with ` +
+          `the secret. If that leak is intended, acknowledge it once: ` +
+          `aggregate('${a.id}', fields, { invariant, invariantDeclassify: "<why a refusal reveals this>" }).`,
+      );
+    }
+    // 4b — a `workspaceInvariant` whose DECLARED reads touch a private aggregate (in this domain).
+    for (const wi of mod.workspaceInvariants ?? []) {
+      if (wi.declassify) continue;
+      let refs: readonly { readonly aggregate: string }[];
+      try {
+        refs = wi.reads({ intent: new Proxy({}, { get: () => "" }) as Record<string, unknown>, principal: "" }) ?? [];
+      } catch {
+        continue; // the read-set can't be resolved on a probe intent — skip (no false refusal; conservative on availability)
+      }
+      for (const r of refs) {
+        const short = r.aggregate.includes(".") ? r.aggregate.slice(r.aggregate.lastIndexOf(".") + 1) : r.aggregate;
+        if (privateTypes.has(short)) {
+          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. ` +
+              `If intended (e.g. an overdraft refusal reveals balance < amount), acknowledge it once: ` +
+              `workspaceInvariant('${wi.id}').on(...).reads(...).declassify("<why a refusal reveals this>").assert(...).`,
+          );
+        }
+      }
+    }
+  }
+
+  // ── RULE 5 — NO PRIVATE BYTES IN AN OUTBOUND OFFER (Send's external send) ────
+  // The outbox (refs/heads/outbox/<offer>) POSTs a capability's obligation to its endpoint —
+  // a DIFFERENT observer set (the external adapter). If the capability's task aggregate is
+  // private (requires a read cap) or encrypted, those bytes cross the confidentiality boundary.
+  // Refuse unless declassified. CURRENTLY VACUOUS BY CONSTRUCTION (capability task aggregates are
+  // public, and rule 2 severs the plan from foreign secrets — so nothing private reaches the
+  // outbox), but this ARMS the fifth and last sink so the static analysis is provably complete:
+  // it fires the moment a private/encrypted capability becomes expressible.
+  if (mod && privateTypes.size > 0) {
+    for (const cap of mod.impureCapabilities ?? []) {
+      if (!cap.endpoint || cap.declassify) continue;
+      if (privateTypes.has(cap.aggregate.id)) {
+        const name = cap.name ?? cap.capability ?? cap.aggregate.id;
+        throw new FlowGateError(
+          `[nomosFlowGate rule 5 — no private bytes in an outbound offer] capability '${name}' POSTs its obligation to ` +
+            `'${cap.endpoint}', but its task aggregate '${cap.aggregate.id}' is PRIVATE — the outbound bytes cross to a ` +
+            `different observer set (the external adapter). If that send is intended, acknowledge it once: ` +
+            `capability('${name}', { request, endpoint, declassify: "<why these bytes may leave the workspace>" }).`,
+        );
+      }
+    }
+  }
+}

package/src/framework/capability.ts

@@ -84,6 +84,22 @@ export interface CapabilityDecl<
 > extends ImpureCapability<string, RequestShape<Req>, Req & Rec> {
   /** The capability name — the `CapabilityBinding` slot the executor must hold. */
   readonly name: string;
+  /**
+   * THE CAPABILITY ENDPOINT (outbox / `capability_offers_https.md`): the HTTPS URL
+   * the obligation is offered to. Sealed into the law (the `nomosCapabilities` key);
+   * the bailiff reads it from `declared_capabilities` and POSTs each requested
+   * obligation there ("a capability is a holon at a URL"). Omitted ⇒ obligations
+   * rest at `requested` with nowhere to go (the deploy notice says so).
+   */
+  readonly endpoint?: string;
+  /**
+   * THE DECLASSIFY WAIVER (nomosFlowGate rule 5 — no private bytes in an outbound offer): present
+   * iff the author acknowledged that this capability POSTs data derived from a private/encrypted
+   * source to its endpoint — a DIFFERENT observer set (the external adapter, Send's external send).
+   * Rides the `nomosFlowGate` era key (replay-verified audit surface). Absent on an emitting
+   * capability over a private task aggregate ⇒ the flow gate refuses to compile.
+   */
+  readonly declassify?: string;
   /** The request fields' zod object (what `oblige<Pascal>`'s params validate as). */
   readonly requestSchema: z.ZodObject<RequestShape<Req>>;
   /**
@@ -112,7 +128,7 @@ export function capability<
   const Name extends string,
   Req extends Record<string, Field>,
   Rec extends Record<string, Field> = Record<never, Field>,
->(name: Name, spec: { request: Req; receipt?: Rec }): CapabilityDecl<Req, Rec> {
+>(name: Name, spec: { request: Req; receipt?: Rec; endpoint?: string; declassify?: string }): CapabilityDecl<Req, Rec> {
   if (!CAPABILITY_NAME_RE.test(name)) {
     throw new Error(
       `capability('${name}'): the name must match ${CAPABILITY_NAME_RE} (lowercase, dot-namespaced — e.g. 'llm.complete'); it doubles as the CapabilityBinding slot the executor must hold`,
@@ -204,6 +220,8 @@ export function capability<
     aggregate: taskAggregate,
     instanceId: impureCapabilityInstanceId,
     name,
+    ...(spec.endpoint !== undefined ? { endpoint: spec.endpoint } : {}),
+    ...(spec.declassify !== undefined ? { declassify: spec.declassify } : {}),
     requestSchema: z.object(requestShape),
     receiptSchema: z.object(receiptShape),
     encodeResult: (values) => JSON.stringify(z.object(receiptShape).parse(values)),

package/src/framework/encryption_scope.ts

@@ -40,7 +40,15 @@ import { directive } from "../directive.js";
 import { set, withMarker, type PlannedOp } from "../ops.js";
 import { query } from "../query.js";
 
-const CAP_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+// A SCOPE is the read cap (relation), OPTIONALLY object-qualified for a PER-RECORD scope:
+//   `<relation>`              — workspace-wide (≡ `workspace:self#<relation>`; the era rule "no `#` ⇒
+//                               workspace:self" keeps every pre-feature chain byte-identical), or
+//   `<type>:<id>#<relation>`  — per-record (the roster = Expand(<type>:<id>#<relation>), the §6 grain).
+// The object half mirrors the relation-tuple OBJECT_RE; the relation half is a cap name. `#` is in neither
+// char class, so the split is unambiguous. The kernel parses the same way (executor `parse_scope_object`).
+const REL_PART = "[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}";
+const OBJ_PART = "[A-Za-z0-9][A-Za-z0-9_.-]*:[A-Za-z0-9][A-Za-z0-9_.:/-]*";
+const CAP_RE = new RegExp(`^(?:${OBJ_PART}#)?${REL_PART}$`);
 const B64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
 
 /** Deterministic ids — the scope head + a per-member wrap, both replay-stable. */

package/src/framework/genesis.ts

@@ -81,7 +81,11 @@ export const seedGenesis = directive("seedGenesis")
   .payload(
     z.object({
       principal: z.string().min(1),
-      workspaceId: z.string().min(1),
+      // EMPTY ⇒ a CONTROL-PLANE genesis: records the founding principal (arming the kernel's genesis
+      // bootstrap clause for the founding admin grant) WITHOUT a self-id, so the workspace stays
+      // UNWARRANTED (host-stamped authorship, like root) — deploys/governance/child births keep working
+      // unsigned. NON-EMPTY ⇒ a TENANT (signed-author) self-id (the source binding author signatures cover).
+      workspaceId: z.string(),
       bornAt: z.string().min(1),
     }),
   )

package/src/framework/relations.ts

@@ -46,6 +46,7 @@ import { Lww, MapOf } from "../drivers.js";
 import { directive } from "../directive.js";
 import { set, setEntry, withMarker, type PlannedOp } from "../ops.js";
 import { query } from "../query.js";
+import { endorsementOf, type AttributionPrincipal, type EndorsedAuthority } from "../principal_evidence.js";
 
 /** Tuple subject lifecycle — the same vocabulary the kernel read drops a non-active leaf by. */
 export const RELATION_STATUSES = ["active", "revoked"] as const;
@@ -126,8 +127,15 @@ function compact(obj: Record<string, unknown>): RelationSubjectLeaf {
 interface WriteTupleInput {
   object: string;
   relation: string;
-  subject: string;
-  grantedBy: string;
+  /**
+   * THE AUTHORITY SINK (the endorse model — security_model.md): who is granted the relation. A plain
+   * subject string (`user:<id>` from the payload) OR `ctx.principal().asAuthoritySubject(reason)` — an
+   * un-endorsed identity (`asAttribution()`) cannot be a subject (it won't typecheck), so identity
+   * never SILENTLY decides a grant.
+   */
+  subject: string | EndorsedAuthority<string>;
+  /** ATTRIBUTION (free): who recorded the grant. A plain string OR `ctx.principal().asAttribution()`. */
+  grantedBy: string | AttributionPrincipal;
   grantedAt: string;
 }
 
@@ -141,19 +149,30 @@ function lowerTuple(
   },
 ): PlannedOp[] {
   const rt = instance(RelationTuple, relationTupleInstanceId(p.object, p.relation));
+  // MATERIALISE PrincipalEvidence subjects/grantedBy → the raw principal (the endorse model). The
+  // subject's endorsement is recorded on the setEntry op so the discovery harvest lifts it into
+  // nomosFlowGate.endorse; grantedBy is free attribution (materialised, not gated).
+  //
+  // The captured authoring principal IS already a wire-form subject (`user:<uid>` / `key:<hash>`, the
+  // host-stamped actor — the SAME form the write gate parses via `Subject::parse`), so an endorsed
+  // authority subject lowers to that leaf verbatim and the gate's `engine.check` matches it.
+  const subjectE = endorsementOf(p.subject);
+  const subjectRaw = subjectE ? subjectE.principal : (p.subject as string);
+  const grantedByRaw = endorsementOf(p.grantedBy)?.principal ?? (p.grantedBy as string);
   const leaf = compact({
     status: p.status,
-    grantedBy: p.grantedBy,
+    grantedBy: grantedByRaw,
     grantedAt: p.grantedAt,
     revokedBy: p.revokedBy,
     revokedAt: p.revokedAt,
   });
+  const subjectEntry = setEntry(rt, "subjects", subjectRaw, JSON.stringify(leaf));
   return [
     // upsert the aggregate head (first relate creates it); without this the referential
     // gate would reject a setEntry on an absent id.
     withMarker(set(rt, "object", p.object), "ensures"),
     set(rt, "relation", p.relation),
-    setEntry(rt, "subjects", p.subject, JSON.stringify(leaf)),
+    subjectE ? { ...subjectEntry, endorsement: { facet: subjectE.facet, reason: subjectE.reason } } : subjectEntry,
   ];
 }
 

package/src/framework/repair.ts

@@ -10,7 +10,7 @@
  *
  * ── Why this module exists ──────────────────────────────────────────────────
  * "Nomos is powerful enough to define its own repair surface as a Nomos domain"
- * (Jack 2026-06-05, TARGET_repair.dot). The dogfood proof: repair intents go through
+ * (Jack 2026-06-05, REPAIR.dot). The dogfood proof: repair intents go through
  * THE ONE GATE — no bespoke crate, no AssumeVerified, no 2nd write path. This is Stage
  * 2 (the `revert` directive); supersede / upcast / drain are later stages.
  *
@@ -36,7 +36,7 @@
  *
  * ── Scope (Stage 2 only — do NOT add supersede / upcast / drain here) ──────
  * supersede needs policy-control event shapes; upcast is an on-read migration;
- * drain is a re-dispatch. All are later stages (TARGET_repair.dot build order §2-5).
+ * drain is a re-dispatch. All are later stages (REPAIR.dot build order §2-5).
  */
 import { z } from "zod";
 import { aggregate, instance } from "../aggregate.js";

package/src/framework/signing_identity.ts

@@ -67,7 +67,7 @@ const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256
  *    bootstrap chicken-and-egg. The forge surface a bare `relateSubject` would open is closed by
  *    DOMAIN PLACEMENT: this directive is composed into the CONTROL-PLANE governance law (domain
  *    `workspaces`/`nomos`), which the open session lane structurally refuses
- *    (`cloud/holon-host/src/engine.mjs` — only the birth door + the secret-gated `/author` + admin
+ *    (`adapter/engine.mjs` — only the birth door + the secret-gated `/author` + admin
  *    lanes author it), so no tenant can forge a signer for another principal.
  *
  * THE ORDER IS THE CONTRACT (verified, zero gate change): `enrollSigner` (E, unsigned/pre-warrant) →

package/src/framework/workspace_invariant.ts

@@ -99,6 +99,14 @@ export interface WorkspaceInvariantDecl {
   readonly reads: WorkspaceInvariantReads;
   /** The executable predicate — ships in the engine bundle, NOT the manifest. */
   readonly assert: WorkspaceInvariantAssert;
+  /**
+   * THE DECLASSIFY WAIVER (nomosFlowGate rule 4 — architecture/security_model.md): present iff
+   * the author acknowledged that this invariant's refusal MAY correlate with a secret it reads
+   * (a `requires`/`owned` aggregate). The reason is hashed into the `nomosFlowGate` era key (so
+   * it is replay-verified + the entire audit surface). Absent ⇒ the flow gate refuses to compile
+   * a secret-correlated refusal.
+   */
+  readonly declassify?: string;
   /** Brand so a plain object is never mistaken for a declaration. */
   readonly __isWorkspaceInvariant: true;
 }
@@ -112,22 +120,35 @@ export function workspaceInvariant(id: string): {
   on(directiveId: string): {
     reads(reads: WorkspaceInvariantReads): {
       assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl;
+      /** Acknowledge an intended secret-correlated refusal (nomosFlowGate rule 4). The reason
+       *  rides the `nomosFlowGate` era key; then chain `.assert(...)` as usual. */
+      declassify(reason: string): { assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl };
     };
   };
 } {
+  const finish = (directiveId: string, reads: WorkspaceInvariantReads, declassify: string | undefined) => ({
+    assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl {
+      return {
+        id,
+        on: directiveId,
+        reads,
+        assert,
+        ...(declassify !== undefined ? { declassify } : {}),
+        __isWorkspaceInvariant: true as const,
+      };
+    },
+  });
   return {
     on(directiveId: string) {
       return {
         reads(reads: WorkspaceInvariantReads) {
           return {
-            assert(assert: WorkspaceInvariantAssert): WorkspaceInvariantDecl {
-              return {
-                id,
-                on: directiveId,
-                reads,
-                assert,
-                __isWorkspaceInvariant: true,
-              };
+            assert: finish(directiveId, reads, undefined).assert,
+            declassify(reason: string) {
+              if (typeof reason !== "string" || reason.trim().length === 0) {
+                throw new Error(`workspaceInvariant('${id}').declassify(reason) needs a non-empty human reason — it is the audit record for an intended secret-correlated refusal.`);
+              }
+              return finish(directiveId, reads, reason);
             },
           };
         },