@githolon/dsl 0.14.0 → 0.16.0

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

@@ -8,12 +8,12 @@
 /**
  * framework/capability.ts — `capability()`: THE MARKETPLACE DECLARATION
  * (`architecture/capability_marketplace.md` §4, ruling M2 — the framework-hidden
- * lane). ONE call declares a typed Order→Receipt capability interface; the dev
- * sees a typed order call and a typed task row, and the framework supplies
+ * lane). ONE call declares a typed Obligation→Receipt capability interface; the dev
+ * sees a typed obligation call and a typed task row, and the framework supplies
  * everything else through the SHIPPED `impureCapability()` quartet — so the gate
- * law (`check_order_receipt`), the kernel recognizer, codegen, and the stable-id
+ * law (`check_obligation_receipt`), the kernel recognizer, codegen, and the stable-id
  * lockfile all see a perfectly ordinary impure capability. Hidden means *not
- * hand-rolled*, never *not auditable*: the Order and Receipt facts ride the
+ * hand-rolled*, never *not auditable*: the Obligation and Receipt facts ride the
  * ledger verbatim.
  *
  * ```ts
@@ -22,7 +22,7 @@
  *   receipt: { tokensIn: t.int(), tokensOut: t.int() },
  * });
  * // derived, deterministically from the name:
- * //   aggregate  LlmCompleteTask        order      orderLlmComplete
+ * //   aggregate  LlmCompleteTask        obligation obligeLlmComplete
  * //   complete   completeLlmComplete    fail/block/deadLetter likewise
  * //   capability "llm.complete"         (the CapabilityBinding the executor must hold)
  * ```
@@ -84,7 +84,23 @@ export interface CapabilityDecl<
 > extends ImpureCapability<string, RequestShape<Req>, Req & Rec> {
   /** The capability name — the `CapabilityBinding` slot the executor must hold. */
   readonly name: string;
-  /** The request fields' zod object (what `order<Pascal>`'s params validate as). */
+  /**
+   * 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>>;
   /**
    * THE EXECUTOR'S SCAN LANE — a declared, indexed query over the task
@@ -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`,
@@ -127,7 +143,7 @@ export function capability<
     for (const k of Object.keys(fields)) {
       if (reserved.has(k)) {
         throw new Error(
-          `capability('${name}'): ${side} field '${k}' shadows the reserved Order→Receipt envelope — rename it (the envelope is framework law: ${[...reserved].join(", ")})`,
+          `capability('${name}'): ${side} field '${k}' shadows the reserved Obligation→Receipt envelope — rename it (the envelope is framework law: ${[...reserved].join(", ")})`,
         );
       }
     }
@@ -135,7 +151,7 @@ export function capability<
   for (const k of Object.keys(receipt)) {
     if (k in spec.request) {
       throw new Error(
-        `capability('${name}'): '${k}' is declared on BOTH request and receipt — a field has one writer (the order writes requests, the complete Receipt writes receipts); split or rename it`,
+        `capability('${name}'): '${k}' is declared on BOTH request and receipt — a field has one writer (the obligation writes requests, the complete Receipt writes receipts); split or rename it`,
       );
     }
   }
@@ -144,7 +160,7 @@ export function capability<
   const aggregateId = `${pascal}Task`;
 
   // Receipt fields fold only when the complete Receipt lands — auto-`.optional()`
-  // so a freshly-ordered task decodes on the generated read type (the same
+  // so a freshly-obligated task decodes on the generated read type (the same
   // read-decode discipline the envelope's own optionals follow).
   const receiptFields = Object.fromEntries(
     Object.entries(receipt).map(([k, f]) => [k, f.optional()]),
@@ -162,7 +178,7 @@ export function capability<
 
   const quartet = impureCapability({
     aggregateId,
-    orderDirectiveId: `order${pascal}`,
+    obligationDirectiveId: `oblige${pascal}`,
     completeDirectiveId: `complete${pascal}`,
     failDirectiveId: `fail${pascal}`,
     blockDirectiveId: `block${pascal}`,
@@ -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),
     }),
   )