@telorun/analyzer 0.62.1 → 0.64.0

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;