@telorun/analyzer 0.62.1 → 0.64.0

package/dist/validate-zone-slots.js

@@ -1,5 +1,36 @@
+/**
+ * Static validation of the two execution-zone annotations themselves — the
+ * strict half of the accessor split, mirroring `validate-ref-slots.ts`.
+ *
+ * `readProvidesZone` / `readRequiresZone` are deliberately lenient: they return
+ * `undefined` for anything they cannot read. Without this pass that leniency is
+ * silent in the worst possible direction, because the two annotations fail in
+ * OPPOSITE ways:
+ *
+ *  - an unreadable **requires** annotation drops the requirement entirely, so a
+ *    safety constraint the author wrote is never enforced — and the resource
+ *    then throws `ERR_ZONE_REQUIRED` / `ERR_ZONE_ANNOTATION_MISSING` at
+ *    dispatch. That is exactly the silent-non-enforcement `ZONE_PROVIDER_UNRESOLVED`
+ *    exists to prevent, reached by a different route.
+ *  - an unreadable **provides** annotation drops the discharge, so the pass
+ *    reports `ZONE_REQUIREMENT_UNSATISFIED` on manifests that are correct.
+ *
+ * A third shape is worse than either: a `key` the analyzer skips but the kernel
+ * accepts (a pointer with no leading `/` — the kernel's walk splits on `/` and
+ * drops empty segments, so it resolves) makes the two halves disagree about what
+ * the manifest MEANS, which is the one outcome neither severity can express.
+ *
+ * Scoping follows `X_TELO_REF_UNRESOLVED`: reported only for definitions in the
+ * entry's own modules — a published dependency's slot is not the consumer's to
+ * fix.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import { ZONE_ATTRIBUTES, zoneAttributeNames } from "@telorun/sdk";
+import { distance } from "./levenshtein.js";
 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
  *  pointer must name at least one segment. */
@@ -15,20 +46,133 @@ function describe(value) {
         return "null";
     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) {
+    if (!name)
+        return undefined;
+    const threshold = Math.min(3, Math.floor(name.length / 3));
+    if (threshold < 1)
+        return undefined;
+    let best;
+    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, definition, path, issues, annotation = PROVIDES) {
+    const declared = new Set();
+    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, definition, path, issues) {
     if (raw === true)
         return;
     if (isPointer(raw))
         return;
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        const obj = raw;
+        // `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.`,
     });
 }
 function checkRequires(raw, definition, path, issues) {
@@ -72,13 +216,61 @@ function checkRequires(raw, definition, path, issues) {
     if (obj.reason !== undefined && typeof obj.reason !== "string") {
         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, definition, path, issues) {
+    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, 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`. */
@@ -97,8 +289,12 @@ function walkSchema(node, path, visited, definition, issues) {
         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")
+        if (key === PROVIDES || key === REQUIRES || key === VIOLATES)
+            continue;
+        if (key === "examples" || key === "default")
             continue;
         walkSchema(value, path ? `${path}.${key}` : key, visited, definition, issues);
     }

package/dist/validate-zone-violations.d.ts

@@ -0,0 +1,12 @@
+import type { CallGraph } from "./call-graph.js";
+import { type DefinitionLookup } from "./resolve-zone-containment.js";
+import { type AnalysisDiagnostic } from "./types.js";
+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 declare function validateZoneViolations(args: ZoneViolationArgs): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-zone-violations.d.ts.map

package/dist/validate-zone-violations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-zone-violations.d.ts","sourceRoot":"","sources":["../src/validate-zone-violations.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACvF,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKzE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,gBAAgB,CAAC;IAC7B;kDAC8C;IAC9C,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,iBAAiB,GAAG,kBAAkB,EAAE,CA8FpF"}

package/dist/validate-zone-violations.js

@@ -0,0 +1,169 @@
+/**
+ * `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, } from "@telorun/sdk";
+import { findZoneRegions } from "./resolve-zone-containment.js";
+import { DiagnosticSeverity } from "./types.js";
+import { readViolatesZone } from "./zone-slot.js";
+const SOURCE = "telo";
+export function validateZoneViolations(args) {
+    const { graph, resolveDef, reportModules } = args;
+    const diagnostics = [];
+    const reported = new Set();
+    // 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();
+    const violations = (kind, module) => {
+        const key = `${module ?? ""}\0${kind}`;
+        let found = violationsOf.get(key);
+        if (!found) {
+            const def = resolveDef(kind, module);
+            found = readViolatesZone(def?.schema);
+            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?.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?.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?.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) {
+    if (!raw || typeof raw !== "object")
+        return false;
+    const policy = raw;
+    if (!Object.values(policy).every(isStaticValue))
+        return false;
+    const attempts = policy.attempts;
+    if (typeof attempts !== "number" || attempts <= 0)
+        return false;
+    return retryBackoffMs(policy, 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) {
+    return value === undefined || typeof value === "number" || typeof value === "string";
+}
+function owned(manifest, reportModules) {
+    const module = manifest.metadata?.module;
+    return !module || reportModules.size === 0 || reportModules.has(module);
+}

package/dist/value-type-keyword.d.ts

@@ -28,7 +28,7 @@ import type { KeywordDefinition } from "ajv";
  *
  * `x-telo-type` is deliberately absent — it is the one that emits code.
  */
-export declare const ANNOTATION_KEYWORDS: readonly ["x-telo-bindings-from", "x-telo-catches-for", "x-telo-context", "x-telo-context-collection-from", "x-telo-context-element-from", "x-telo-context-from", "x-telo-context-from-ref-kind", "x-telo-context-from-root", "x-telo-context-ref-from", "x-telo-error-context", "x-telo-eval", "x-telo-inline", "x-telo-outcome-list", "x-telo-provides-zone", "x-telo-ref", "x-telo-requires-zone", "x-telo-schema-from", "x-telo-scope", "x-telo-step-context", "x-telo-topology-role", "x-telo-value-schema-from", "x-telo-widget"];
+export declare const ANNOTATION_KEYWORDS: readonly ["x-telo-bindings-from", "x-telo-catches-for", "x-telo-context", "x-telo-context-collection-from", "x-telo-context-element-from", "x-telo-context-from", "x-telo-context-from-ref-kind", "x-telo-context-from-root", "x-telo-context-ref-from", "x-telo-error-context", "x-telo-eval", "x-telo-inline", "x-telo-outcome-list", "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", "x-telo-value-schema-from", "x-telo-widget"];
 /**
  * The `x-telo-type` keyword.
  *

package/dist/value-type-keyword.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value-type-keyword.d.ts","sourceRoot":"","sources":["../src/value-type-keyword.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;+EAqB+E;AAG/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,KAAK,CAAC;AAiB7C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,ygBAuBtB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CA+BpD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IACxC,UAAU,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;CACzD,GAAG,IAAI,CAGP"}
+{"version":3,"file":"value-type-keyword.d.ts","sourceRoot":"","sources":["../src/value-type-keyword.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;+EAqB+E;AAG/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,KAAK,CAAC;AAiB7C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,onBA2BtB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CA+BpD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IACxC,UAAU,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;CACzD,GAAG,IAAI,CAGP"}

package/dist/value-type-keyword.js

@@ -48,7 +48,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/dist/zone-slot.d.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
@@ -17,6 +24,7 @@
  *     key: [/connection, /transaction/connection]  # ordered, first hit wins
  *     reason: the statement would execute outside any transaction
  */
+import { type ZoneAttributes } from "@telorun/sdk";
 /** A body slot that establishes the declaring kind's zone when dispatched
  *  through. The zone's identity is always the declaring kind — the annotation
  *  never names one, so provision-on-behalf-of is unrepresentable. */
@@ -25,6 +33,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. */
 export interface RequiresZoneSlot {
@@ -38,16 +56,59 @@ 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[];
 }
 /** Reads a schema node's provides-zone declaration, or undefined when it has
  *  none or the value is malformed (`validate-zone-slots` reports those). */
 export declare function readProvidesZone(node: Record<string, any> | undefined): ProvidesZoneSlot | undefined;
+/** 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 declare function providedZoneAttributes(node: Record<string, any> | undefined): ZoneAttributes;
 /** True when the node carries `x-telo-provides-zone` in any shape, valid or not
  *  — the recognition test validation needs before it judges the value. */
 export declare function hasProvidesZone(node: Record<string, any> | undefined): boolean;
 /** Reads a schema node's requires-zone declaration, or undefined when it has
  *  none or the value is malformed (`validate-zone-slots` reports those). */
 export declare function readRequiresZone(node: Record<string, any> | undefined): RequiresZoneSlot | undefined;
+/**
+ * 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 declare function readViolatesZone(node: Record<string, any> | undefined): ZoneAttributes;
+/** True when the node carries `x-telo-violates-zone` in any shape, valid or not. */
+export declare function hasViolatesZone(node: Record<string, any> | undefined): boolean;
 /** True when the node carries `x-telo-requires-zone` in any shape. */
 export declare function hasRequiresZone(node: Record<string, any> | undefined): boolean;
 /**

package/dist/zone-slot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zone-slot.d.ts","sourceRoot":"","sources":["../src/zone-slot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH;;qEAEqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B;;iCAE6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B;;2EAEuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb;;gCAE4B;IAC5B,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAYD;4EAC4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAKpG;AAED;0EAC0E;AAC1E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED;4EAC4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAWpG;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACxC,IAAI,CAaN"}
+{"version":3,"file":"zone-slot.d.ts","sourceRoot":"","sources":["../src/zone-slot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAMpE;;qEAEqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B;;iCAE6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;wBAQoB;IACpB,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B;;2EAEuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb;;gCAE4B;IAC5B,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;OAcG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAYD;4EAC4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAyBpG;AAED;;wEAEwE;AACxE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,cAAc,CAE5F;AAED;0EAC0E;AAC1E,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED;4EAC4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAkBpG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,cAAc,CAYtF;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GACxC,IAAI,CAaN"}