@telorun/analyzer 0.62.1 → 0.63.0

package/src/validate-zone-slots.ts

@@ -26,10 +26,11 @@
  *
  * Browser-safe: no Node built-ins.
  */
-import type { ResourceManifest } from "@telorun/sdk";
+import { ZONE_ATTRIBUTES, zoneAttributeNames, type ResourceManifest } from "@telorun/sdk";
+import { distance } from "./levenshtein.js";
 
 export interface ZoneSlotIssue {
-  code: "ZONE_ANNOTATION_INVALID";
+  code: "ZONE_ANNOTATION_INVALID" | "ZONE_ATTRIBUTE_UNKNOWN" | "ZONE_ATTRIBUTE_INCOMPLETE";
   manifest: ResourceManifest;
   /** Schema path of the annotated slot. */
   path: string;
@@ -38,6 +39,7 @@ export interface ZoneSlotIssue {
 
 const PROVIDES = "x-telo-provides-zone";
 const REQUIRES = "x-telo-requires-zone";
+const VIOLATES = "x-telo-violates-zone";
 
 /** A self-relative JSON Pointer, the only correlation-key spelling both halves
  *  read identically. `""` (whole document) is meaningless as a key, so a
@@ -53,6 +55,107 @@ function describe(value: unknown): string {
   return typeof value;
 }
 
+/** The closest declared attribute name within an edit-distance threshold, or
+ *  undefined. Mirrors `suggestValueType`: case-sensitive, and silent on a tie,
+ *  because a coin-flip suggestion is worse than none. */
+function suggestAttribute(name: string): string | undefined {
+  if (!name) return undefined;
+  const threshold = Math.min(3, Math.floor(name.length / 3));
+  if (threshold < 1) return undefined;
+  let best: string | undefined;
+  let bestDist = threshold + 1;
+  let tied = false;
+  for (const candidate of ZONE_ATTRIBUTES.keys()) {
+    const d = distance(name, candidate);
+    if (d < bestDist) {
+      best = candidate;
+      bestDist = d;
+      tied = false;
+    } else if (d === bestDist) {
+      tied = true;
+    }
+  }
+  return !best || bestDist > threshold || tied ? undefined : best;
+}
+
+/**
+ * The attributes half of the object form.
+ *
+ * The composed `additionalProperties: false` schema would already reject an
+ * unknown name; the dedicated code earns its place by NAMING the valid ones and
+ * suggesting a spelling, instead of reporting a schema violation on a key the
+ * author believed was real — the same standing `X_TELO_TYPE_UNKNOWN` has over
+ * the value-type vocabulary it is modelled on.
+ */
+function checkAttributes(
+  obj: Record<string, unknown>,
+  definition: ResourceManifest,
+  path: string,
+  issues: ZoneSlotIssue[],
+  annotation: string = PROVIDES,
+): void {
+  const declared = new Set<string>();
+
+  for (const [name, value] of Object.entries(obj)) {
+    if (name === "key") continue;
+    const entry = ZONE_ATTRIBUTES.get(name);
+    if (!entry) {
+      const suggestion = suggestAttribute(name);
+      issues.push({
+        code: "ZONE_ATTRIBUTE_UNKNOWN",
+        manifest: definition,
+        path,
+        message:
+          `${annotation} at '${path}' declares '${name}', which is not a zone attribute. ` +
+          (suggestion ? `Did you mean '${suggestion}'? ` : "") +
+          `The vocabulary is closed: ${zoneAttributeNames().join(", ")}. An attribute ` +
+          `states a property of everything executed inside this zone, and every reader ` +
+          `of one is core — a name outside the set would be read by nothing.`,
+      });
+      continue;
+    }
+    // Each value is the REASON, and it is required by being the value itself
+    // rather than a sibling of a boolean. That is also what makes a type check
+    // possible at all: there is no `true` to accept, so `atomic: true` is caught
+    // here rather than reading as a valid declaration with nothing to say.
+    if (typeof value !== "string" || !value) {
+      issues.push({
+        code: "ZONE_ANNOTATION_INVALID",
+        manifest: definition,
+        path,
+        message:
+          `${annotation} at '${path}' declares '${name}' as ${describe(value)}. Every zone ` +
+          `attribute's value is the author's REASON — a non-empty sentence, quoted verbatim ` +
+          `by the diagnostics that enforce it (${entry.description}).`,
+      });
+      continue;
+    }
+    declared.add(name);
+  }
+
+  // The completeness rule is about what a region PROMISES: declaring `atomic`
+  // without `noSuspend` is an incomplete promise. A VIOLATION is not a promise —
+  // breaking one guarantee implies nothing about breaking another — so the rule
+  // does not apply there.
+  if (annotation !== PROVIDES) return;
+  // `requires:` lives in the vocabulary entry rather than as a hardcoded pair of
+  // names here, so the completeness rule sits beside the thing it constrains.
+  for (const name of declared) {
+    for (const dependency of ZONE_ATTRIBUTES.get(name)!.requires) {
+      if (declared.has(dependency)) continue;
+      issues.push({
+        code: "ZONE_ATTRIBUTE_INCOMPLETE",
+        manifest: definition,
+        path,
+        message:
+          `${PROVIDES} at '${path}' declares '${name}' without '${dependency}', which it ` +
+          `requires. ${ZONE_ATTRIBUTES.get(dependency)!.description} Declare it with its own ` +
+          `reason — a generic message is exactly what the required reason exists to prevent.`,
+      });
+    }
+  }
+}
+
 function checkProvides(
   raw: unknown,
   definition: ResourceManifest,
@@ -61,16 +164,38 @@ function checkProvides(
 ): void {
   if (raw === true) return;
   if (isPointer(raw)) return;
+
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const obj = raw as Record<string, unknown>;
+    // `key` keeps the meaning it has in the scalar spelling; only its absence is
+    // legitimate here (an uncorrelated zone that still declares attributes).
+    if (obj.key !== undefined && !isPointer(obj.key)) {
+      issues.push({
+        code: "ZONE_ANNOTATION_INVALID",
+        manifest: definition,
+        path,
+        message:
+          `${PROVIDES} at '${path}' declares the correlation key ${describe(obj.key)}, which ` +
+          `is not a self-relative JSON Pointer. Write '/connection'. A bare field name is ` +
+          `read as a pointer by the runtime but skipped by the checker, so the two halves ` +
+          `would disagree about what this manifest means.`,
+      });
+    }
+    checkAttributes(obj, definition, path, issues);
+    return;
+  }
+
   issues.push({
     code: "ZONE_ANNOTATION_INVALID",
     manifest: definition,
     path,
     message:
       `${PROVIDES} at '${path}' is ${describe(raw)}. It takes 'true' (the zone is ` +
-      `uncorrelated) or a self-relative JSON Pointer naming this kind's own field ` +
+      `uncorrelated), a self-relative JSON Pointer naming this kind's own field ` +
       `whose resolved reference the zone carries as its correlation payload ` +
-      `(e.g. '/connection'). It never names the zone — the zone a slot provides ` +
-      `is always the declaring kind.`,
+      `(e.g. '/connection'), or an object carrying that pointer as 'key' beside the ` +
+      `zone attributes this region declares (${zoneAttributeNames().join(", ")}). It ` +
+      `never names the zone — the zone a slot provides is always the declaring kind.`,
   });
 }
 
@@ -129,17 +254,74 @@ function checkRequires(
     fail(`${REQUIRES} at '${path}' declares a non-string 'reason'.`);
   }
 
+  // `attributes` is the GUARANTEE half — what the satisfying zone must declare,
+  // as opposed to which kind it is. It is a list of NAMES with no reasons: the
+  // reason belongs to whoever makes the promise, and a requirer restating it
+  // would be a second sentence to keep in step with the one that is enforced.
+  if (obj.attributes !== undefined) {
+    if (!Array.isArray(obj.attributes) || obj.attributes.length === 0) {
+      fail(
+        `${REQUIRES} at '${path}' declares 'attributes' as ${describe(obj.attributes)}. It ` +
+          `takes a non-empty list of zone attribute names; omit it to require the kind alone.`,
+      );
+    } else {
+      for (const name of obj.attributes) {
+        if (typeof name === "string" && ZONE_ATTRIBUTES.has(name)) continue;
+        const suggestion = typeof name === "string" ? suggestAttribute(name) : undefined;
+        issues.push({
+          code: "ZONE_ATTRIBUTE_UNKNOWN",
+          manifest: definition,
+          path,
+          message:
+            `${REQUIRES} at '${path}' requires '${String(name)}', which is not a zone ` +
+            `attribute. ` +
+            (suggestion ? `Did you mean '${suggestion}'? ` : "") +
+            `The vocabulary is closed: ${zoneAttributeNames().join(", ")}.`,
+        });
+      }
+    }
+  }
+
   for (const key of Object.keys(obj)) {
-    if (key === "zone" || key === "key" || key === "reason") {
+    if (key === "zone" || key === "key" || key === "reason" || key === "attributes") {
       continue;
     }
     fail(
       `${REQUIRES} at '${path}' declares an unknown property '${key}'. The object form takes ` +
-        `'zone', 'key' and 'reason'.`,
+        `'zone', 'key', 'reason' and 'attributes'.`,
     );
   }
 }
 
+/**
+ * The third annotation: what this kind cannot honour.
+ *
+ * Only the object form, because a violation without a reason is exactly the
+ * shape the vocabulary refuses everywhere else — the diagnostic that fires on it
+ * prints the region's promise and this resource's rebuttal side by side, and one
+ * of the two would otherwise be a generated sentence.
+ */
+function checkViolates(
+  raw: unknown,
+  definition: ResourceManifest,
+  path: string,
+  issues: ZoneSlotIssue[],
+): void {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    issues.push({
+      code: "ZONE_ANNOTATION_INVALID",
+      manifest: definition,
+      path,
+      message:
+        `${VIOLATES} at '${path}' is ${describe(raw)}. It takes a map of zone attribute ` +
+        `names to the reason this kind cannot honour each — ` +
+        `\`noSuspend: this waits for a delivery that may be days away\`.`,
+    });
+    return;
+  }
+  checkAttributes(raw as Record<string, unknown>, definition, path, issues, VIOLATES);
+}
+
 /** Walk a definition schema, reporting every zone annotation it cannot read.
  *  Pure-schema walk, so it needs a visited guard for cyclic `$defs`. */
 function walkSchema(
@@ -159,8 +341,10 @@ function walkSchema(
   const obj = node as Record<string, unknown>;
   if (obj[PROVIDES] !== undefined) checkProvides(obj[PROVIDES], definition, path, issues);
   if (obj[REQUIRES] !== undefined) checkRequires(obj[REQUIRES], definition, path, issues);
+  if (obj[VIOLATES] !== undefined) checkViolates(obj[VIOLATES], definition, path, issues);
   for (const [key, value] of Object.entries(obj)) {
-    if (key === PROVIDES || key === REQUIRES || key === "examples" || key === "default") continue;
+    if (key === PROVIDES || key === REQUIRES || key === VIOLATES) continue;
+    if (key === "examples" || key === "default") continue;
     walkSchema(value, path ? `${path}.${key}` : key, visited, definition, issues);
   }
 }

package/src/validate-zone-violations.ts

@@ -0,0 +1,190 @@
+/**
+ * `ZONE_ATTRIBUTE_VIOLATED` — a resource inside a region whose guarantee it
+ * declares it cannot honour.
+ *
+ * The third leg of the zone-attribute mechanism, and the one that makes the
+ * other two enforceable. `x-telo-provides-zone` says what a region guarantees
+ * about its contents and `x-telo-requires-zone` says what a resource needs of
+ * the region around it — but neither says *this resource breaks that
+ * guarantee*, so until now an attribute could be declared, resolved and read
+ * with nothing able to report the one thing it exists to prevent.
+ *
+ * **Generic over the whole vocabulary, and it names no kind.** The rule is one
+ * sentence — *a region declaring attribute A must not contain a resource
+ * declaring it violates A* — and it is run once per attribute in
+ * `sdk/zone-attributes/`. So `noSuspend` (a parking kind inside a lease) and any
+ * attribute added later are covered by the same traversal, and `modules/durable`
+ * stays outside the analyzer's surface exactly as the topology-driven constraint
+ * requires.
+ *
+ * **Both sentences are their authors' own.** The diagnostic prints the region's
+ * declared reason and the violating kind's declared reason side by side, because
+ * the useful message is the collision between two written claims — "this
+ * transaction holds a connection a parked run would lose" against "this waits
+ * for a delivery that may be days away" — and neither half is anything the
+ * analyzer could generate.
+ *
+ * **Enforced at runtime, warned early**, like every other containment rule: the
+ * walk under-approximates (an edge the call graph cannot see is invisible here),
+ * and the runtime check in the violating controller is the real enforcement. It
+ * is an ERROR rather than a warning nonetheless: where the walk *can* see the
+ * path, the placement is decidably wrong — the region's promise and the
+ * resource's rebuttal are both declarations, so nothing about the runtime can
+ * reconcile them.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import {
+  SUSPENDING_BACKOFF_MS,
+  ZONE_ATTRIBUTES,
+  retryBackoffMs,
+  type ResourceManifest,
+} from "@telorun/sdk";
+import type { CallGraph } from "./call-graph.js";
+import { findZoneRegions, type DefinitionLookup } from "./resolve-zone-containment.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+import { readViolatesZone } from "./zone-slot.js";
+
+const SOURCE = "telo";
+
+export interface ZoneViolationArgs {
+  graph: CallGraph;
+  resolveDef: DefinitionLookup;
+  /** Only report against modules the entry owns — a published dependency's
+   *  placement is not the consumer's to fix. */
+  reportModules: ReadonlySet<string>;
+}
+
+export function validateZoneViolations(args: ZoneViolationArgs): AnalysisDiagnostic[] {
+  const { graph, resolveDef, reportModules } = args;
+  const diagnostics: AnalysisDiagnostic[] = [];
+  const reported = new Set<string>();
+
+  // What each kind in the graph declares it cannot honour, resolved once. A
+  // graph holds many instances of few kinds, and this is a schema read.
+  const violationsOf = new Map<string, Record<string, string>>();
+  const violations = (kind: string, module?: string): Record<string, string> => {
+    const key = `${module ?? ""}\0${kind}`;
+    let found = violationsOf.get(key);
+    if (!found) {
+      const def = resolveDef(kind, module);
+      found = readViolatesZone(def?.schema as Record<string, any> | undefined);
+      violationsOf.set(key, found);
+    }
+    return found;
+  };
+
+  for (const attribute of ZONE_ATTRIBUTES.keys()) {
+    for (const region of findZoneRegions(graph, resolveDef, attribute)) {
+      for (const contained of region.contents.values()) {
+        // The one step-level rule, and it is separate because it is a property
+        // of the STEP rather than of its target: a retry whose backoff is long
+        // enough to park suspends the run from inside a region that promised
+        // nothing in it would. Only `noSuspend` has such a rule, because only
+        // `noSuspend` is broken by waiting.
+        if (attribute === "noSuspend" && contained.node.type === "step") {
+          const ownerNode = graph.nodes.get(contained.node.owner);
+          const owner = ownerNode?.type === "resource" ? ownerNode : undefined;
+          if (
+            owner &&
+            owned(owner.manifest, reportModules) &&
+            suspendingBackoff(contained.node.step.retry)
+          ) {
+            const dedupe = `retry\0${contained.node.id}`;
+            if (!reported.has(dedupe)) {
+              reported.add(dedupe);
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "ZONE_ATTRIBUTE_VIOLATED",
+                source: SOURCE,
+                message:
+                  `Step '${contained.node.name ?? contained.node.path}' declares a retry ` +
+                  `whose last backoff reaches ${SUSPENDING_BACKOFF_MS}ms, at which point a ` +
+                  `re-attempt waits by PARKING the run rather than by sleeping — but it is ` +
+                  `inside a ${region.provider.kind} ` +
+                  `'${region.provider.name}' region that declares 'noSuspend' ` +
+                  `(${region.reason}). Shorten the backoff, or move the retry outside the ` +
+                  `region so it re-attempts the region as a whole.`,
+                data: {
+                  resource: { kind: owner.kind, name: owner.name },
+                  filePath: (owner.manifest.metadata as { source?: string } | undefined)?.source,
+                  path: contained.node.path,
+                },
+              });
+            }
+          }
+        }
+        // A step node is a dispatch site, not a resource — whatever it reaches
+        // is in `contents` in its own right, so judging the step too would
+        // report one placement twice.
+        if (contained.node.type !== "resource") continue;
+        const manifest = contained.node.manifest;
+        const module = (manifest.metadata as { module?: string } | undefined)?.module;
+        const rebuttal = violations(contained.node.kind, module)[attribute];
+        if (!rebuttal) continue;
+        if (!owned(manifest, reportModules)) continue;
+
+        const dedupe = `${region.provider.id}\0${region.slot}\0${contained.node.id}\0${attribute}`;
+        if (reported.has(dedupe)) continue;
+        reported.add(dedupe);
+
+        const path = [`${region.provider.name}.${region.slot}`, ...contained.via].join(" → ");
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "ZONE_ATTRIBUTE_VIOLATED",
+          source: SOURCE,
+          message:
+            `${contained.node.kind} '${contained.node.name}' is inside a ` +
+            `${region.provider.kind} '${region.provider.name}' region that declares ` +
+            `'${attribute}' (${region.reason}), but ${contained.node.kind} cannot honour ` +
+            `it: ${rebuttal}. Reached by ${path}. Move it outside the region, or use a ` +
+            `region that does not make that promise.`,
+          data: {
+            resource: { kind: contained.node.kind, name: contained.node.name },
+            filePath: (manifest.metadata as { source?: string } | undefined)?.source,
+          },
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+/**
+ * Does this declared retry policy back off far enough to park?
+ *
+ * EXACT, not an estimate, and it is the runtime's own arithmetic
+ * (`retryBackoffMs`) rather than a second copy of it — a static rule that
+ * re-derives what it describes drifts from the behaviour the first time either
+ * side gains a knob. It is exact for a second reason too: the runtime branches
+ * on the UN-JITTERED backoff, so there is no coin flip for this to
+ * approximate. The last attempt has the largest backoff, so it decides.
+ *
+ * Only a STATICALLY KNOWN policy is judged — the `LIVE_VALUE_RETRIED` posture,
+ * and for its reason: a CEL budget says nothing, and guessing would report a
+ * conflict against a manifest that may never wait that long. An unreadable
+ * policy is left to the runtime check, which sees the real number.
+ */
+function suspendingBackoff(raw: unknown): boolean {
+  if (!raw || typeof raw !== "object") return false;
+  const policy = raw as Record<string, unknown>;
+  if (!Object.values(policy).every(isStaticValue)) return false;
+  const attempts = policy.attempts;
+  if (typeof attempts !== "number" || attempts <= 0) return false;
+  return retryBackoffMs(policy as never, attempts - 1) >= SUSPENDING_BACKOFF_MS;
+}
+
+/** A CEL leaf reaches here as a compiled value or a tagged sentinel, and either
+ *  way the policy is not statically known. Refusing the whole policy rather than
+ *  the one field is the conservative direction: `maxDelay` alone decides the
+ *  answer, so reading around an unresolved one would report a bound the manifest
+ *  may never reach. */
+function isStaticValue(value: unknown): boolean {
+  return value === undefined || typeof value === "number" || typeof value === "string";
+}
+
+function owned(manifest: ResourceManifest, reportModules: ReadonlySet<string>): boolean {
+  const module = (manifest.metadata as { module?: string } | undefined)?.module;
+  return !module || reportModules.size === 0 || reportModules.has(module);
+}

package/src/value-type-keyword.ts

@@ -63,7 +63,11 @@ export const ANNOTATION_KEYWORDS = [
   "x-telo-provides-zone",
   "x-telo-ref",
   "x-telo-requires-zone",
+  "x-telo-resource-rules",
   "x-telo-schema-from",
+  "x-telo-schema-map",
+  "x-telo-schema-projection",
+  "x-telo-schema-projection-from",
   "x-telo-scope",
   "x-telo-step-context",
   "x-telo-topology-role",

package/src/zone-slot.ts

@@ -10,6 +10,13 @@
  *
  *   x-telo-provides-zone: true            # uncorrelated — the zone is the kind
  *   x-telo-provides-zone: /connection     # correlation-key pointer (own field)
+ *   x-telo-provides-zone:                 # correlation key + zone attributes
+ *     key: /connection
+ *     atomic: a rollback erases writes a journal recorded as done
+ *     noSuspend: the transaction holds a connection a parked run would lose
+ *
+ *   x-telo-violates-zone:                 # what this kind cannot honour
+ *     noSuspend: this waits for a delivery that may be days away
  *
  *   x-telo-requires-zone: Self.Transaction        # uncorrelated string form
  *   x-telo-requires-zone:                          # object form
@@ -18,8 +25,11 @@
  *     reason: the statement would execute outside any transaction
  */
 
+import { ZONE_ATTRIBUTES, type ZoneAttributes } from "@telorun/sdk";
+
 const PROVIDES = "x-telo-provides-zone";
 const REQUIRES = "x-telo-requires-zone";
+const VIOLATES = "x-telo-violates-zone";
 
 /** A body slot that establishes the declaring kind's zone when dispatched
  *  through. The zone's identity is always the declaring kind — the annotation
@@ -29,6 +39,16 @@ export interface ProvidesZoneSlot {
    *  reference the zone carries as its correlation payload. Absent =
    *  uncorrelated (`true`). */
   key?: string;
+  /** What this zone declares about everything executed inside it, keyed by the
+   *  closed vocabulary's bare names with the author's REASON as each value (see
+   *  `sdk/zone-attributes/`). Empty for the two scalar spellings, which say
+   *  nothing about their contents.
+   *
+   *  Read here and interpreted nowhere in this file: an attribute's meaning is
+   *  entirely its consumer's — the containment walk, the step engine's collapse
+   *  rule, the parking kinds — exactly as `readRefSlot` hands back `use` without
+   *  acting on it. */
+  attributes: ZoneAttributes;
 }
 
 /** A field declaring that its resource must be reached through a zone. */
@@ -43,6 +63,22 @@ export interface RequiresZoneSlot {
   key: string[];
   /** The runtime consequence, quoted after the path in diagnostics. */
   reason?: string;
+  /**
+   * Zone attributes the satisfying zone must DECLARE — what it must guarantee,
+   * as opposed to which kind it is.
+   *
+   * The two are different questions and the kind test alone cannot answer the
+   * second. A kind may extend the required abstract, and so satisfy every kind
+   * check, while its body slot omits the attribute the requirer actually depends
+   * on — a durable workflow whose body does not declare `replayed` is a zone the
+   * durable checks never look inside, and a run parking there parks against
+   * nothing. Naming the attribute is what makes the requirement say what it
+   * means.
+   *
+   * Names come from the closed vocabulary (`sdk/zone-attributes/`), so the
+   * analyzer reads its own words here and no module's kind is named.
+   */
+  attributes: string[];
 }
 
 /** A self-relative JSON Pointer — the only correlation-key spelling the
@@ -59,9 +95,36 @@ function isPointer(value: unknown): value is string {
  *  none or the value is malformed (`validate-zone-slots` reports those). */
 export function readProvidesZone(node: Record<string, any> | undefined): ProvidesZoneSlot | undefined {
   const raw = node?.[PROVIDES];
-  if (raw === true) return {};
-  if (isPointer(raw)) return { key: raw };
-  return undefined;
+  if (raw === true) return { attributes: {} };
+  if (isPointer(raw)) return { key: raw, attributes: {} };
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+
+  const obj = raw as Record<string, unknown>;
+  // A `key` that is present but unreadable makes the object form MEAN something
+  // different to the two halves — the correlation the author wrote is dropped
+  // here while the kernel's walk still resolves a bare name — so the whole
+  // annotation is refused rather than read as uncorrelated. Absent `key` is the
+  // legitimate uncorrelated case.
+  if (obj.key !== undefined && !isPointer(obj.key)) return undefined;
+
+  const attributes: Record<string, string> = {};
+  for (const [name, value] of Object.entries(obj)) {
+    if (name === "key") continue;
+    // Unknown names and wrong-shaped values are reported by
+    // `validate-zone-slots`; skipped here so a typo degrades to an attribute
+    // this zone does not declare rather than to a consumer reading a name that
+    // means nothing to it.
+    if (!ZONE_ATTRIBUTES.has(name) || typeof value !== "string" || !value) continue;
+    attributes[name] = value;
+  }
+  return { ...(isPointer(obj.key) ? { key: obj.key } : {}), attributes: attributes as ZoneAttributes };
+}
+
+/** The attributes the zone a slot provides declares, or an empty record when the
+ *  node provides no zone. The shape every containment consumer wants, so none of
+ *  them repeats the `readProvidesZone(...)?.attributes ?? {}` dance. */
+export function providedZoneAttributes(node: Record<string, any> | undefined): ZoneAttributes {
+  return readProvidesZone(node)?.attributes ?? {};
 }
 
 /** True when the node carries `x-telo-provides-zone` in any shape, valid or not
@@ -74,17 +137,63 @@ export function hasProvidesZone(node: Record<string, any> | undefined): boolean
  *  none or the value is malformed (`validate-zone-slots` reports those). */
 export function readRequiresZone(node: Record<string, any> | undefined): RequiresZoneSlot | undefined {
   const raw = node?.[REQUIRES];
-  if (typeof raw === "string" && raw) return { zone: raw, key: [] };
+  if (typeof raw === "string" && raw) return { zone: raw, key: [], attributes: [] };
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
   const obj = raw as Record<string, unknown>;
   if (typeof obj.zone !== "string" || !obj.zone) return undefined;
   // One filter for both spellings — see `isPointer`.
   const key = (Array.isArray(obj.key) ? obj.key : [obj.key]).filter(isPointer);
-  const slot: RequiresZoneSlot = { zone: obj.zone, key };
+  // Unknown names are dropped here and reported by `validate-zone-slots`, the
+  // lenient-reader / strict-validator split this file has throughout: a typo
+  // degrades to a guarantee this requirement does not ask for, never to a
+  // consumer matching against a name that means nothing.
+  const attributes = (Array.isArray(obj.attributes) ? obj.attributes : []).filter(
+    (a): a is string => typeof a === "string" && ZONE_ATTRIBUTES.has(a),
+  );
+  const slot: RequiresZoneSlot = { zone: obj.zone, key, attributes };
   if (typeof obj.reason === "string") slot.reason = obj.reason;
   return slot;
 }
 
+/**
+ * What this kind CANNOT honour about a region it is placed inside.
+ *
+ * The third relation, and the one the other two cannot express. `provides`
+ * declares what a region guarantees about its contents; `requires` declares what
+ * a resource needs of the region around it. Neither says *this resource breaks
+ * that guarantee* — and without it a zone attribute has a promise and no way to
+ * name what falsifies it: `noSuspend` would be enforced only when a parking kind
+ * happened to reach its runtime check, and `Durable.Sleep` would be
+ * indistinguishable from `Durable.Value`, which needs the same journal and parks
+ * nothing.
+ *
+ * Declared at the kind's SCHEMA ROOT, because it is a property of the kind
+ * rather than of one of its slots — a kind that suspends suspends however it is
+ * configured.
+ *
+ * Values are the author's REASON, exactly as on `provides`: a diagnostic prints
+ * the region's promise and this resource's rebuttal side by side, and both are
+ * their own authors' words.
+ */
+export function readViolatesZone(node: Record<string, any> | undefined): ZoneAttributes {
+  const raw = node?.[VIOLATES];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  const out: Record<string, string> = {};
+  for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
+    // Lenient, like every reader here: `validate-zone-slots` reports a typo, and
+    // dropping it degrades to a violation nobody declared rather than to a
+    // consumer matching a name that means nothing.
+    if (!ZONE_ATTRIBUTES.has(name) || typeof value !== "string" || !value) continue;
+    out[name] = value;
+  }
+  return out as ZoneAttributes;
+}
+
+/** True when the node carries `x-telo-violates-zone` in any shape, valid or not. */
+export function hasViolatesZone(node: Record<string, any> | undefined): boolean {
+  return node?.[VIOLATES] !== undefined;
+}
+
 /** True when the node carries `x-telo-requires-zone` in any shape. */
 export function hasRequiresZone(node: Record<string, any> | undefined): boolean {
   return node?.[REQUIRES] !== undefined;