@githolon/dsl 0.15.0 → 0.16.0

package/src/index.ts

@@ -32,7 +32,21 @@ export {
   type FieldKind,
   type EvidenceRefValue,
   evidenceRefSchema,
+  // FIELD FACETS (the endorse model — security_model.md): authority/standing/attribution gate
+  // set() acceptance of PrincipalEvidence; secret/public are the confidentiality lattice.
+  authorityField,
+  standingField,
+  attributionField,
+  secretField,
+  publicField,
 } from "./fields.js";
+export {
+  type PrincipalEvidence,
+  type AttributionPrincipal,
+  type EndorsedAuthority,
+  type EndorsedStanding,
+  type FieldFacet,
+} from "./principal_evidence.js";
 export {
   Lww,
   LwwCausal,
@@ -410,6 +424,16 @@ export {
   type InvariantVerdict,
 } from "./relation.js";
 export { generateDartDomain, type DomainModule } from "./codegen_dart.js";
+// SHAPE COMPATIBILITY (#72) — the structural contract a client negotiates with a workspace
+// by, instead of the law hash. Pure + deterministic; the editor/CI mirror imports these.
+export {
+  domainInterface,
+  compatible,
+  type DomainInterface,
+  type CompatVerdict,
+  type DirectivePayloadShape,
+  type AggregateReadShape,
+} from "./shape_compat.js";
 // The OPTIONAL Graphviz `.dot` ER-diagram emitter (off-by-default presentation projection,
 // turned on by the `--emit-dot` compiler flag). Pure `DomainModule -> string`, deterministic;
 // NOT part of the domain identity. Barrel-safe (no node:* imports), so the engine bundle can

package/src/manifest.ts

@@ -39,6 +39,7 @@ import { finishExtremum, type AnyExtremum } from "./extremum.js";
 import { existsAsCount, type AnyExists } from "./exists.js";
 import type { OrderedReadDecl } from "./ordered_read.js";
 import type { CanonicalPred } from "./predicate.js";
+import { assertFlowGate } from "./flow_gate.js";
 import type { DerivedDecl } from "./derived.js";
 import type { CombinedDecl } from "./combined.js";
 import type { CertifiedReadDecl } from "./certified_read.js";
@@ -1055,22 +1056,10 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
     }))
     .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 
-  // E2E ENCRYPTION — critical #5 (e2e_encryption.md §5), the captured-read seal, COMPILE
-  // half. A captured read (`read()` on the write path) of a PRIVATE query would record its
-  // plaintext result onto the intent as PUBLIC, signed, replay-verified chain data —
-  // bypassing the read gate AND the encryption envelope. Forbid it: a `requires(cap)`
-  // query can NEVER be a captured read. (The one gate re-asserts this at admission/replay
-  // via `cap_for_query`, so a hand-crafted raw intent is refused on every peer too.)
-  const privateTypes = new Set(aggregates.filter((a) => a.requiresRead !== undefined).map((a) => a.id));
-  for (const d of directives) {
-    for (const cr of d.capturedReads ?? []) {
-      if (privateTypes.has(cr.returns)) {
-        throw new Error(
-          `directive '${d.id}': captured read '${cr.queryId}' returns the PRIVATE type '${cr.returns}' — a .reads() of a requires(cap) query would write its plaintext onto the chain as public data. Private data may only leave via the gated read path (query/qbyid), never a captured read.`,
-        );
-      }
-    }
-  }
+  // THE INFORMATION-FLOW GATE (architecture/security_model.md): rule 2 (no private
+  // captured read on the chain) + rule 1 (no encrypt-then-index) are enforced as ONE
+  // pass over the assembled canonical manifest, just before return (see assertFlowGate).
+  // E2E ENCRYPTION — critical #5 (e2e_encryption.md §5): the captured-read seal is rule 2.
 
   // exists_ entries are COUNT declarations in the IR — merge them into `counts` so the
   // Rust engine sees them as ordinary counts (the marker lives only in the DSL/codegen
@@ -1081,7 +1070,7 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
   // Omit-when-empty: a domain declaring NO query / NO count / NO sum contributes neither
   // key, so its canonical manifest is byte-identical to before the read-closure layer
   // existed. `sums` follows the same omit-when-empty discipline as `counts`.
-  return {
+  const manifest: CanonicalManifest = {
     domain: mod.name,
     aggregates,
     directives,
@@ -1109,6 +1098,11 @@ export function domainManifest(mod: DomainModule): CanonicalManifest {
       ...(mod.workspaceTypes !== undefined ? { workspaceTypes: mod.workspaceTypes } : {}),
     }),
   };
+  // THE STATIC INFORMATION-FLOW GATE — leaky law is unrepresentable (a typed compile
+  // error naming the field, the sink, and the rule). Rules 1/2/5 read the manifest IR;
+  // rule 4 also needs the raw module (the executable invariant reads + declassify waivers).
+  assertFlowGate(manifest, mod as never);
+  return manifest;
 }
 
 /** Recursively sort object keys; arrays are already in sorted/stable order. */

package/src/ops.ts

@@ -17,6 +17,13 @@
  */
 import type { AggregateHandle, BoundAggregate } from "./aggregate.js";
 import type { Field, FieldValue } from "./fields.js";
+import {
+  endorsementOf,
+  type AttributionPrincipal,
+  type EndorsedAuthority,
+  type EndorsedStanding,
+  type PrincipalFacet,
+} from "./principal_evidence.js";
 
 /**
  * A FIELD op, retaining the source aggregate id + field for deterministic wire encoding.
@@ -41,6 +48,13 @@ export interface FieldOp {
   readonly value?: unknown;
   readonly items?: readonly string[];
   readonly entryKey?: string;
+  /**
+   * THE PRINCIPAL-FLOW ENDORSEMENT (security_model.md — the endorse model): present iff this op's
+   * value came from a PrincipalEvidence conversion. The raw principal is materialised into `value`;
+   * this records the facet + endorsement reason so the discovery harvest can lift it into the
+   * manifest `principalFlows`, and the runtime witness can emit the observed flow. Internal.
+   */
+  readonly endorsement?: { readonly facet: PrincipalFacet; readonly reason: string | null };
 }
 
 export type PlannedEventMarker = "creates" | "mutates" | "ensures" | "archives";
@@ -84,6 +98,20 @@ type Target<Id extends string = string, F extends Record<string, Field> = Record
 
 type Fields<A> = A extends Target<string, infer F> ? F : never;
 
+/**
+ * What `set()` ACCEPTS for a field, given its facet (security_model.md — the endorse model).
+ * A plain (un-faceted) field accepts its ordinary value. A faceted field ALSO accepts the matching
+ * PrincipalEvidence conversion — and ONLY that one, so writing un-endorsed identity (or the wrong
+ * endorsement) into an authority/standing sink does not typecheck. The read/wire type is unchanged.
+ */
+type AcceptedValue<F> = F extends { readonly facet: "authority" }
+  ? FieldValue<F> | EndorsedAuthority<FieldValue<F>>
+  : F extends { readonly facet: "standing" }
+    ? FieldValue<F> | EndorsedStanding<FieldValue<F>>
+    : F extends { readonly facet: "attribution" }
+      ? FieldValue<F> | AttributionPrincipal
+      : FieldValue<F>;
+
 /** Resolve a target's `{aggregateId, aggregateType}` — bound → instance id + type. */
 function addressOf(agg: Target): { aggregateId: string; aggregateType?: string } {
   if ((agg as BoundAggregate).__isBoundAggregate === true) {
@@ -110,7 +138,7 @@ export function set<
     (Fields<A>[K] extends { kind: "set" }
       ? `TYPE ERROR: '${K}' is a set field — set() would OVERWRITE the merge; use addToSet(handle, "${K}", values)`
       : K),
-  value: FieldValue<Fields<A>[K]>,
+  value: AcceptedValue<Fields<A>[K]>,
 ): FieldOp {
   const f = (agg as { fields?: Record<string, { kind?: string }> }).fields?.[field];
   if (f?.kind === "set") {
@@ -119,6 +147,19 @@ export function set<
         `(concurrent adds would be lost). Use addToSet(handle, '${field}', values) — the additive write.`,
     );
   }
+  // MATERIALISE PrincipalEvidence: the typed value may be an evidence conversion (an opaque token).
+  // Store the RAW principal in the op, and record the endorsement so the harvest + runtime witness
+  // see the flow (security_model.md). A plain value passes through untouched.
+  const endorsement = endorsementOf(value);
+  if (endorsement) {
+    return {
+      ...addressOf(agg),
+      field,
+      kind: "set",
+      value: endorsement.principal,
+      endorsement: { facet: endorsement.facet, reason: endorsement.reason },
+    };
+  }
   return { ...addressOf(agg), field, kind: "set", value };
 }
 

package/src/principal_evidence.ts

@@ -0,0 +1,112 @@
+// NOMOS — the integrity dual of the information-flow gate (architecture/security_model.md).
+// "Identity may attribute freely. Identity may authorise only when endorsed by declared law."
+//
+// `ctx.principal()` returns opaque PrincipalEvidence — NOT a string. It cannot be compared,
+// concatenated, branched on, or smuggled into a payload (the raw value is held in a module-
+// private registry, unreadable by authors). Its ONLY exits are three typed conversions:
+//
+//   .asAttribution()              → AttributionPrincipal   (free — createdBy/grantedBy/...)
+//   .asAuthoritySubject(reason)   → EndorsedAuthority<T>    (endorsed — a write-up into authority)
+//   .asStandingParty(reason)      → EndorsedStanding<T>     (endorsed — accountability: owedBy/...)
+//
+// Field facets gate `set()` acceptance (authorityField accepts only EndorsedAuthority, etc.), so an
+// un-endorsed flow into an authority sink does not COMPILE — the confused deputy is closed by
+// construction, not by plan-body taint analysis. `requires`/`assert` remain the only place an
+// authority decision may be MADE (evidence can't branch, so `if (principal() === …)` won't typecheck).
+//
+// The `reason` is part of the LAW, not the data: a non-empty human string, harvested into the
+// manifest `principalFlows` + the endorse era key (the audit surface), and witnessed fail-closed at
+// runtime/replay (Slice B).
+
+/** The endorsement facet — which kind of sink the evidence has been converted for. */
+export type PrincipalFacet = "attribution" | "authority" | "standing";
+
+/**
+ * A field's FACET — the integrity/confidentiality role of the sink. The integrity facets
+ * (authority/attribution/standing) gate `set()` acceptance of PrincipalEvidence conversions;
+ * the confidentiality facets (secret/public) mark the read-down lattice. Default (no facet) =
+ * an ordinary field that accepts a plain value.
+ */
+export type FieldFacet = "authority" | "attribution" | "standing" | "secret" | "public";
+
+/** The record behind an evidence-derived value, readable ONLY by the framework (never the author). */
+export interface EndorsementRecord {
+  readonly facet: PrincipalFacet;
+  /** The verified authoring principal (the captured `ctx.principal()` value). */
+  readonly principal: string;
+  /** The static endorsement reason (LAW) — null for free attribution. */
+  readonly reason: string | null;
+}
+
+// The raw principal + endorsement live HERE, module-private — an author holding a converted value
+// has no accessor to them (the brand below is phantom). The framework reads via `endorsementOf`.
+const REGISTRY = new WeakMap<object, EndorsementRecord>();
+
+declare const FACET_BRAND: unique symbol;
+/** A principal converted for ATTRIBUTION — accepted by `attributionField` sinks. Opaque. */
+export interface AttributionPrincipal {
+  readonly [FACET_BRAND]: "attribution";
+}
+/** A principal ENDORSED for an AUTHORITY sink (relation subject/relation/object, token, policy…). Opaque. */
+export interface EndorsedAuthority<T = string> {
+  readonly [FACET_BRAND]: "authority";
+  /** Phantom — carries the sink's value type for `set()` inference; never materialised. */
+  readonly __t?: T;
+}
+/** A principal ENDORSED for a STANDING sink (owedBy/responsible/issuer…). Opaque. */
+export interface EndorsedStanding<T = string> {
+  readonly [FACET_BRAND]: "standing";
+  readonly __t?: T;
+}
+
+/** The opaque identity capability `ctx.principal()` returns. No raw exit — only typed conversions. */
+export interface PrincipalEvidence {
+  /** Free: record WHO acted, into an `attributionField` (createdBy/grantedBy/submittedBy). */
+  asAttribution(): AttributionPrincipal;
+  /** Endorsed write-up into an `authorityField` — `reason` is LAW (a static, non-empty string). */
+  asAuthoritySubject<T = string>(reason: string): EndorsedAuthority<T>;
+  /** Endorsed write-up into a `standingField` (accountability) — `reason` is LAW. */
+  asStandingParty<T = string>(reason: string): EndorsedStanding<T>;
+}
+
+function requireReason(kind: string, reason: unknown): string {
+  if (typeof reason !== "string" || reason.trim().length === 0) {
+    throw new Error(
+      `${kind}(reason) requires a non-empty reason — endorsing identity into an authority sink is a ` +
+        `declared act of law, not data. Pass a static string explaining why this flow is intended.`,
+    );
+  }
+  return reason;
+}
+
+function mint(facet: PrincipalFacet, principal: string, reason: string | null): object {
+  const token = {};
+  REGISTRY.set(token, { facet, principal, reason });
+  return token;
+}
+
+/** Build the opaque evidence capability over a verified principal (the engine wires this into ctx). */
+export function principalEvidence(principal: string): PrincipalEvidence {
+  return {
+    asAttribution: () => mint("attribution", principal, null) as AttributionPrincipal,
+    asAuthoritySubject: <T = string>(reason: string) =>
+      mint("authority", principal, requireReason("asAuthoritySubject", reason)) as EndorsedAuthority<T>,
+    asStandingParty: <T = string>(reason: string) =>
+      mint("standing", principal, requireReason("asStandingParty", reason)) as EndorsedStanding<T>,
+  };
+}
+
+/**
+ * FRAMEWORK-INTERNAL: read the endorsement behind an evidence-derived value — used by the write
+ * path (to materialise the raw principal into the op), the discovery harvest (to record the flow),
+ * and the runtime/replay witness (to emit the observed flow). Returns null for a plain value (a
+ * non-evidence write). Authors cannot call this usefully — the REGISTRY is module-private.
+ */
+export function endorsementOf(value: unknown): EndorsementRecord | null {
+  return typeof value === "object" && value !== null && REGISTRY.has(value) ? (REGISTRY.get(value) ?? null) : null;
+}
+
+/** Is this value an evidence conversion (any facet)? */
+export function isPrincipalEvidenceValue(value: unknown): boolean {
+  return endorsementOf(value) !== null;
+}

package/src/relation_sugar.ts

@@ -210,10 +210,16 @@ export interface SugaredRelationTypeBuilder extends RelationTypeBuilder {
  * builder; we re-wrap on every chain step so the audience methods survive interleaving with `.relation`.
  */
 export function withAudiences(builder: RelationTypeBuilder): SugaredRelationTypeBuilder {
-  // The builder object is mutated in place by `.relation(...)` (it returns itself), so we can safely
-  // attach methods that delegate to it and re-wrap. We attach to a fresh proxy-like object that forwards
-  // the decl fields by reference (the Map is shared, so reads stay live).
-  const sugared = Object.create(builder) as SugaredRelationTypeBuilder;
+  // Carry the decl's data as OWN enumerable properties (NOT `Object.create(builder)` — a prototype-only
+  // object serializes to `{}`, which collapses the compiler's `discover()` JSON dedup so every sugared
+  // type but the first is dropped). `relations` is the SAME Map reference the underlying builder mutates,
+  // so reads stay live as `.relation(...)`/the audience methods add to it.
+  const sugared = {
+    type: builder.type,
+    relations: builder.relations,
+    ...(builder.caps !== undefined ? { caps: builder.caps } : {}),
+    __isRelationType: true as const,
+  } as SugaredRelationTypeBuilder;
 
   sugared.relation = function (name, opts) {
     builder.relation(name, opts);

package/src/shape_compat.ts

@@ -0,0 +1,208 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact.  If a file isn't this / hosting this / authoring for this
+// / proving this — it's gone.
+//
+// SHAPE COMPATIBILITY (#72) — the structural contract a client and a workspace
+// negotiate by, INSTEAD of the package hash. See architecture/shape_compatibility.md.
+//
+// A client fits a workspace iff the workspace's installed interface SUBTYPES what the
+// client depends on:
+//   • WRITES are CONTRAVARIANT — for every directive the client calls, the workspace
+//     has that directive id and its CURRENT payload schema ACCEPTS the client's
+//     payload: every field the workspace REQUIRES the client always sends, and every
+//     shared field's kind matches. (Extra client fields are ignored — non-strict zod.)
+//   • READS are COVARIANT by STABLE ID (#58) — for every aggregate the client reads,
+//     the workspace has that aggregate SID and every field the client CONSUMES (by
+//     field sid) is present with a compatible kind. The workspace may serve MORE.
+//
+// Identity is by stable id, not name or hash — that is what makes the relation
+// decidable across renames (a renamed aggregate field keeps its sid, so an old client
+// stays read-compatible). Directive/payload identity is the dispatched id + field
+// names (directives are not sid-tracked yet — a payload rename IS a write break, and
+// is reported precisely).
+
+import { z } from "zod";
+import { introspectPayload, type DomainModule, type PayloadFieldSpec } from "./codegen_dart.js";
+import type { StableIds } from "./stable_ids_types.js";
+import type { Field } from "./fields.js";
+
+/** One payload field's normalized shape: its kind + whether the schema makes it optional. */
+export interface PayloadFieldShape {
+  readonly kind: string;
+  readonly optional: boolean;
+}
+/** A directive's payload contract — the field set + types the gate validates against. */
+export interface DirectivePayloadShape {
+  readonly fields: Record<string, PayloadFieldShape>;
+}
+/** An aggregate's read contract — fields keyed by STABLE ID (rename-safe), each carrying
+ *  its current label (for human-readable verdicts) + its read kind. */
+export interface AggregateReadShape {
+  readonly sid: string;
+  readonly label: string;
+  /** keyed by FIELD SID. */
+  readonly fields: Record<string, { kind: string; label: string }>;
+}
+/** A domain's full structural interface — the offer (a workspace's installed law) AND
+ *  the requirement (the law a client was generated from) are the SAME vocabulary. */
+export interface DomainInterface {
+  readonly v: 1;
+  readonly domain: string;
+  readonly domainSid?: string;
+  /** keyed by DIRECTIVE ID (the dispatched name). */
+  readonly directives: Record<string, DirectivePayloadShape>;
+  /** keyed by AGGREGATE SID. */
+  readonly aggregates: Record<string, AggregateReadShape>;
+}
+
+/** The verdict: compatible iff nothing is missing and nothing is type-incompatible.
+ *  `missing` = a depended-on directive/aggregate/field the workspace doesn't expose;
+ *  `incompatible` = present but type-divergent (a payload field kind, a retyped read field). */
+export interface CompatVerdict {
+  readonly ok: boolean;
+  readonly missing: string[];
+  readonly incompatible: string[];
+}
+
+/** Normalize a directive payload field to a language-neutral kind from its introspected
+ *  spec (the SAME `introspectPayload` the Dart/TS clients are generated from, so both
+ *  sides of a comparison speak one vocabulary). */
+function payloadFieldKind(spec: PayloadFieldSpec): string {
+  switch (spec.toJson) {
+    case "enum":
+      return "enum";
+    case "strList":
+      return "set";
+    case "json":
+      return "json";
+    case "scalar":
+    default:
+      switch (spec.dartType) {
+        case "int":
+          return "int";
+        case "double":
+          return "double";
+        case "bool":
+          return "bool";
+        default:
+          return "string";
+      }
+  }
+}
+
+/** The aggregate read kind when no stable-id kind is recorded (pre-#58 fallback): the
+ *  field's own declared kind, with the read-collapsed CRDTs normalized to their scalar. */
+function aggFieldReadKind(f: Field): string {
+  switch (f.kind) {
+    case "counter":
+      return "int";
+    case "position":
+      return "string";
+    default:
+      return f.kind;
+  }
+}
+
+/** Extract a domain's structural interface from its loaded module + (optionally) its
+ *  stable-id surface. Without stable ids (pre-#58) aggregate fields key by NAME and the
+ *  kind comes from the field declaration — a graceful, rename-unaware fallback. */
+export function domainInterface(mod: DomainModule, stableIds?: StableIds): DomainInterface {
+  const enumTypes = new Map<string, string>();
+  // DETERMINISTIC KEY ORDER — directive ids, aggregate sids, and field keys are SORTED, so the
+  // emitted interface is byte-stable and the layered-USD fold (which merges + sorts) reproduces it
+  // byte-identically (the `nomosStableIds`/`nomosReadGate` convention). architecture/shape_compatibility.md.
+  const sortedRec = <T>(entries: Array<[string, T]>): Record<string, T> => {
+    const out: Record<string, T> = {};
+    for (const [k, v] of entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))) out[k] = v;
+    return out;
+  };
+  const directives: Record<string, DirectivePayloadShape> = {};
+  const dirEntries: Array<[string, DirectivePayloadShape]> = [];
+  for (const d of (mod.directives ?? []) as Array<{ id?: unknown; payloadSchema?: unknown }>) {
+    if (!d || typeof d.id !== "string") continue;
+    const fieldEntries: Array<[string, PayloadFieldShape]> = [];
+    const schema = d.payloadSchema;
+    if (schema && typeof schema === "object") {
+      for (const spec of introspectPayload(schema as z.ZodTypeAny, enumTypes)) {
+        fieldEntries.push([spec.name, { kind: payloadFieldKind(spec), optional: !!spec.optional }]);
+      }
+    }
+    dirEntries.push([d.id, { fields: sortedRec(fieldEntries) }]);
+  }
+  Object.assign(directives, sortedRec(dirEntries));
+  const aggregates: Record<string, AggregateReadShape> = {};
+  const aggEntries: Array<[string, AggregateReadShape]> = [];
+  for (const agg of (mod.aggregates ?? []) as Array<{ id: string; fields: Record<string, Field> }>) {
+    const label = agg.id;
+    const sa = stableIds?.aggregates?.[label];
+    const aggSid = sa?.sid ?? label;
+    const fieldEntries: Array<[string, { kind: string; label: string }]> = [];
+    for (const [fname, f] of Object.entries(agg.fields ?? {})) {
+      if (!f || f.kind === "hasMany") continue;
+      const fsid = sa?.fields?.[fname]?.sid ?? fname;
+      const kind = sa?.fields?.[fname]?.kind ?? aggFieldReadKind(f);
+      fieldEntries.push([fsid, { kind, label: fname }]);
+    }
+    aggEntries.push([aggSid, { sid: aggSid, label, fields: sortedRec(fieldEntries) }]);
+  }
+  Object.assign(aggregates, sortedRec(aggEntries));
+  return {
+    v: 1,
+    domain: (mod as { domain?: string; name?: string }).domain ?? (mod as { name?: string }).name ?? "",
+    ...(stableIds?.domain !== undefined ? { domainSid: stableIds.domain } : {}),
+    directives,
+    aggregates,
+  };
+}
+
+/** Decide whether a CLIENT interface is satisfied by a WORKSPACE interface (the offer).
+ *  Pure + deterministic — the SAME relation runs at connect() and (mirrored) at the
+ *  editor/CI. Names the exact directive / aggregate / field at fault, never a hash. */
+export function compatible(client: DomainInterface, workspace: DomainInterface): CompatVerdict {
+  const missing: string[] = [];
+  const incompatible: string[] = [];
+
+  // WRITES — contravariant. The workspace must accept every payload the client sends.
+  for (const [did, cShape] of Object.entries(client.directives)) {
+    const wShape = workspace.directives[did];
+    if (!wShape) {
+      missing.push(`directive '${did}'`);
+      continue;
+    }
+    // Every field the WORKSPACE requires, the client must ALWAYS send (present + required).
+    for (const [f, wf] of Object.entries(wShape.fields)) {
+      if (wf.optional) continue;
+      const cf = cShape.fields[f];
+      if (!cf || cf.optional) {
+        incompatible.push(`directive '${did}': workspace requires field '${f}' the client does not always send`);
+      }
+    }
+    // Every field both sides know must agree on kind (a payload retype is a write break).
+    for (const [f, cf] of Object.entries(cShape.fields)) {
+      const wf = wShape.fields[f];
+      if (wf && wf.kind !== cf.kind) {
+        incompatible.push(`directive '${did}': field '${f}' kind ${cf.kind} ≠ workspace ${wf.kind}`);
+      }
+    }
+  }
+
+  // READS — covariant by stable id. Every field the client consumes must be served compatibly.
+  for (const [sid, cAgg] of Object.entries(client.aggregates)) {
+    const wAgg = workspace.aggregates[sid];
+    if (!wAgg) {
+      missing.push(`aggregate '${cAgg.label}'`);
+      continue;
+    }
+    for (const [fsid, cf] of Object.entries(cAgg.fields)) {
+      const wf = wAgg.fields[fsid];
+      if (!wf) {
+        missing.push(`field '${cAgg.label}.${cf.label}'`);
+      } else if (wf.kind !== cf.kind) {
+        incompatible.push(`field '${cAgg.label}.${cf.label}': read kind ${cf.kind} ≠ workspace ${wf.kind}`);
+      }
+    }
+  }
+
+  return { ok: missing.length === 0 && incompatible.length === 0, missing, incompatible };
+}