@telorun/analyzer 0.62.0 → 0.63.0

package/dist/validate-schema-projection.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Static validation of the schema-projection annotations themselves — the
+ * strict half of the accessor split, mirroring `validate-ref-slots.ts` and
+ * `validate-zone-slots.ts`.
+ *
+ * `readSchemaProjection` / `readSchemaMap` are deliberately lenient: anything
+ * they cannot read reads as absent. Without this pass that leniency is silent in
+ * the direction that matters — a projection nothing can read does not fail, it
+ * simply stops typing the consumers that were counting on it, so a misspelled
+ * column reaches the database instead of `telo check`. The whole point of the
+ * projection is to move that failure earlier; an unreported malformed
+ * declaration puts it back.
+ *
+ * A map that is merely INCOMPLETE is the same failure per value: a declared type
+ * with no entry projects to nothing, so a column of that type silently vanishes
+ * from every consumer's view of the row.
+ *
+ * Scoping follows `X_TELO_REF_UNRESOLVED`: reported only for definitions in the
+ * entry's own modules — a published dependency's annotation is not the
+ * consumer's to fix.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { ResourceManifest } from "@telorun/sdk";
+export interface SchemaProjectionIssue {
+    code: "SCHEMA_PROJECTION_INVALID" | "SCHEMA_MAP_INCOMPLETE";
+    manifest: ResourceManifest;
+    path: string;
+    message: string;
+}
+export declare function validateSchemaProjection(manifest: ResourceManifest): SchemaProjectionIssue[];
+//# sourceMappingURL=validate-schema-projection.d.ts.map

package/dist/validate-schema-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-schema-projection.d.ts","sourceRoot":"","sources":["../src/validate-schema-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAQrD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,2BAA2B,GAAG,uBAAuB,CAAC;IAC5D,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,qBAAqB,EAAE,CA2G5F"}

package/dist/validate-schema-projection.js

@@ -0,0 +1,110 @@
+import { projectionKeyMap, rawSchemaProjection, readSchemaProjection, schemaProjectionIsMisplaced, } from "./schema-projection.js";
+const PROJECTION = "x-telo-schema-projection";
+function isObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+export function validateSchemaProjection(manifest) {
+    const doc = manifest;
+    const raw = rawSchemaProjection(doc);
+    if (raw === undefined)
+        return [];
+    const misplaced = schemaProjectionIsMisplaced(doc);
+    const base = misplaced ? `schema.${PROJECTION}` : PROJECTION;
+    const issue = (code, path, message) => ({ code, manifest, path, message });
+    const issues = [];
+    // Read from both positions so a misplaced annotation still WORKS, and
+    // reported so it does not stay misplaced. The alternative — reading only the
+    // document — makes the inner spelling silently inert, and the resulting
+    // failure surfaces on a consumer's slot as "this kind declares no projection",
+    // which blames an author who wrote the annotation correctly enough to mean it.
+    if (misplaced) {
+        issues.push(issue("SCHEMA_PROJECTION_INVALID", base, `'${PROJECTION}' belongs on the kind DOCUMENT, beside 'schema:', not inside it — ` +
+            `it describes the whole declaration rather than one field. It is read from here ` +
+            `too, so nothing is broken; move it up a level.`));
+    }
+    if (!isObject(raw)) {
+        return [
+            ...issues,
+            issue("SCHEMA_PROJECTION_INVALID", base, `'${PROJECTION}' must be an object naming the entry collection and the field that keys it.`),
+        ];
+    }
+    const missing = ["entries", "key"].filter((field) => typeof raw[field] !== "string");
+    if (missing.length > 0) {
+        return [
+            ...issues,
+            issue("SCHEMA_PROJECTION_INVALID", base, `'${PROJECTION}' is missing ${missing.map((f) => `'${f}'`).join(" and ")}. ` +
+                `'entries' is a JSON Pointer to the collection, 'key' the entry field whose value ` +
+                `selects an 'x-telo-schema-map' entry.`),
+        ];
+    }
+    const projection = readSchemaProjection(doc);
+    const schema = doc.schema;
+    // An ARRAY-shaped collection has no key to name its entries by, so without
+    // `name` every entry projects to nothing and the whole projection is an object
+    // schema with no properties and `additionalProperties: false` — one that
+    // rejects every value. A keyed map needs no `name`: the map key IS the
+    // identity.
+    if (collectionIsArray(schema, projection.entries) && !projection.nameField) {
+        return [
+            ...issues,
+            issue("SCHEMA_PROJECTION_INVALID", base, `'${PROJECTION}' names '${projection.entries}', which is an array, but declares no ` +
+                `'name'. An array's entries have no key, so 'name' must say which field holds an ` +
+                `entry's identity — without it the projection yields a schema that rejects every value.`),
+        ];
+    }
+    const map = projectionKeyMap(schema, projection);
+    if (!map) {
+        return [
+            ...issues,
+            issue("SCHEMA_PROJECTION_INVALID", base, `'${PROJECTION}' names '${projection.entries}' keyed on '${projection.key}', but that ` +
+                `field carries no 'x-telo-schema-map'. The map declares the JSON Schema each of its ` +
+                `values means, and without it the projection types nothing.`),
+        ];
+    }
+    // An `enum` on the keyed field is the kind's own closed vocabulary, so every
+    // member of it is a value the map has to answer for. Only an enum is checked:
+    // an open string field has no set to be complete against.
+    const keyField = keySchema(schema, projection.entries, projection.key);
+    const values = Array.isArray(keyField?.enum) ? keyField.enum : [];
+    const unmapped = values.filter((value) => typeof value === "string" && !(value in map));
+    if (unmapped.length === 0)
+        return issues;
+    return [
+        ...issues,
+        issue("SCHEMA_MAP_INCOMPLETE", base, `'x-telo-schema-map' has no entry for ${unmapped.map((v) => `'${v}'`).join(", ")}. ` +
+            `An entry declaring an unmapped value projects to nothing, so it disappears from every ` +
+            `consumer's view of the shape.`),
+    ];
+}
+function collectionIsArray(schema, entries) {
+    let node = schema;
+    for (const segment of entries.split("/")) {
+        if (segment === "")
+            continue;
+        if (!isObject(node) || !isObject(node.properties))
+            return false;
+        node = node.properties[segment];
+    }
+    return isObject(node) && isObject(node.items);
+}
+function keySchema(schema, entries, key) {
+    let node = schema;
+    for (const segment of entries.split("/")) {
+        if (segment === "")
+            continue;
+        if (!isObject(node) || !isObject(node.properties))
+            return undefined;
+        node = node.properties[segment];
+    }
+    if (!isObject(node))
+        return undefined;
+    const entry = isObject(node.additionalProperties)
+        ? node.additionalProperties
+        : isObject(node.items)
+            ? node.items
+            : undefined;
+    if (!isObject(entry) || !isObject(entry.properties))
+        return undefined;
+    const field = entry.properties[key];
+    return isObject(field) ? field : undefined;
+}

package/dist/validate-step-inputs.d.ts

@@ -20,7 +20,8 @@ export interface StepInputIssue {
  * CEL leaves are replaced by schema-shaped placeholders first (`substituteCelFields`),
  * so an expression is never a false positive — only structural disagreement is
  * reported. Nothing is hardcoded about `Run.Sequence`: the invoke field comes
- * from `x-telo-step-context`, and the paired inputs field from whichever sibling
+ * from the step slot (the shared grammar, or the legacy `x-telo-step-context`),
+ * and the paired inputs field from whichever sibling
  * property carries `x-telo-topology-role: inputs`.
  */
 export declare function collectStepInputIssues(manifest: Record<string, any>, defSchema: Record<string, any>, allManifests: Record<string, any>[], defs: DefinitionRegistry, aliases: AliasResolver, scopes: ModuleScopes, 

package/dist/validate-step-inputs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-step-inputs.d.ts","sourceRoot":"","sources":["../src/validate-step-inputs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAqBnE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;iFAC6E;IAC7E,IAAI,CAAC,EAAE,4BAA4B,GAAG,oBAAoB,CAAC;CAC5D;AAGD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,YAAY;AACpB;;mEAEmE;AACnE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAChC,cAAc,EAAE,CAsJlB"}
+{"version":3,"file":"validate-step-inputs.d.ts","sourceRoot":"","sources":["../src/validate-step-inputs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAsBnE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;iFAC6E;IAC7E,IAAI,CAAC,EAAE,4BAA4B,GAAG,oBAAoB,CAAC;CAC5D;AAGD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,YAAY;AACpB;;mEAEmE;AACnE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAChC,cAAc,EAAE,CAsJlB"}

package/dist/validate-step-inputs.js

@@ -4,6 +4,7 @@ import { plainChainOf } from "@telorun/templating";
 import { isLiveSlot, valueTypeOf } from "@telorun/sdk";
 import { manifestFragmentOf } from "./manifest-schemas.js";
 import { analyzerContractScope, containerOf, gatherPropertySchemas, missingRequired, resolveLocalRef, walkStepArray, } from "./analyzer.js";
+import { readStepSlot } from "./step-slot.js";
 /**
  * Validate every step's `inputs:` against the invoked target's declared input
  * contract — the static half of what the kernel enforces at dispatch.
@@ -16,7 +17,8 @@ import { analyzerContractScope, containerOf, gatherPropertySchemas, missingRequi
  * CEL leaves are replaced by schema-shaped placeholders first (`substituteCelFields`),
  * so an expression is never a false positive — only structural disagreement is
  * reported. Nothing is hardcoded about `Run.Sequence`: the invoke field comes
- * from `x-telo-step-context`, and the paired inputs field from whichever sibling
+ * from the step slot (the shared grammar, or the legacy `x-telo-step-context`),
+ * and the paired inputs field from whichever sibling
  * property carries `x-telo-topology-role: inputs`.
  */
 export function collectStepInputIssues(manifest, defSchema, allManifests, defs, aliases, scopes, 
@@ -31,8 +33,8 @@ stepContext) {
     const contractScope = analyzerContractScope(defs, aliases, scopes, allManifests);
     const readingModule = manifest.metadata?.module;
     for (const [fieldName, fieldSchema] of Object.entries(props)) {
-        const stepCtx = fieldSchema["x-telo-step-context"];
-        if (!stepCtx?.invoke)
+        const stepCtx = readStepSlot(fieldSchema);
+        if (!stepCtx)
             continue;
         const steps = manifest[fieldName];
         if (!Array.isArray(steps))

package/dist/validate-throws-coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-throws-coverage.d.ts","sourceRoot":"","sources":["../src/validate-throws-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAOnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA+ezE,oDAAoD;AACpD,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,WAAW,EAChB,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAa,EACvD,WAAW,GAAE,GAAG,CAAC,MAAM,CAAa,GACnC,kBAAkB,EAAE,CAkDtB"}
+{"version":3,"file":"validate-throws-coverage.d.ts","sourceRoot":"","sources":["../src/validate-throws-coverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAOnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAsfzE,oDAAoD;AACpD,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,WAAW,EAChB,eAAe,GAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAa,EACvD,WAAW,GAAE,GAAG,CAAC,MAAM,CAAa,GACnC,kBAAkB,EAAE,CAkDtB"}

package/dist/validate-throws-coverage.js

@@ -4,6 +4,7 @@ import { scopeResolverForModule } from "./alias-resolver.js";
 import { createResolveCtx, resolveThrowsUnion, } from "./resolve-throws-union.js";
 import { DiagnosticSeverity } from "./types.js";
 import { extractAccessChains, validateChainAgainstSchema } from "./validate-cel-context.js";
+import { isStepSlot } from "./step-slot.js";
 const SOURCE = "telo-analyzer";
 const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
 /** Walk `definition.schema` and `data` in tandem, invoking `onOutcome` each
@@ -366,9 +367,11 @@ function checkCelChainAgainstDataSchema(entry, dataSchema, resource, filePath, e
     return diagnostics;
 }
 /** Rule 8 extension: `inherit: true` only makes sense on a definition whose
- *  schema contains at least one `x-telo-step-context` array — the annotation
- *  that drives the resolver's generic step traversal. A definition with
- *  `inherit: true` and no such array has no invocables to inherit from. */
+ *  schema declares at least one STEP BODY — an array whose items point at the
+ *  shared grammar, or, for a module published before that fragment existed, one
+ *  carrying the legacy `x-telo-step-context` annotation. That is what drives the
+ *  resolver's generic step traversal; a definition with `inherit: true` and no
+ *  such array has no invocables to inherit from. */
 function validateThrowsDeclarations(manifests) {
     const diagnostics = [];
     for (const m of manifests) {
@@ -386,7 +389,10 @@ function validateThrowsDeclarations(manifests) {
                     severity: DiagnosticSeverity.Error,
                     code: "INHERIT_WITHOUT_STEP_CONTEXT",
                     source: SOURCE,
-                    message: `Telo.Definition '${name}' declares throws.inherit: true but its schema has no field annotated with x-telo-step-context. inherit is only meaningful on definitions that drive invocables via step arrays.`,
+                    message: `Telo.Definition '${name}' declares throws.inherit: true but its schema declares no step ` +
+                        `body. inherit is only meaningful on a definition that drives invocables through steps — ` +
+                        `give an array field 'items: { $ref: "telo://manifest#/$defs/Step" }' (the legacy ` +
+                        `x-telo-step-context annotation is also recognised).`,
                     data: { resource: { kind: m.kind, name }, filePath, path: "throws.inherit" },
                 });
             }
@@ -397,7 +403,7 @@ function validateThrowsDeclarations(manifests) {
 function schemaHasStepContext(schema) {
     if (!schema || typeof schema !== "object")
         return false;
-    if ("x-telo-step-context" in schema)
+    if (isStepSlot(schema))
         return true;
     const props = schema.properties;
     if (props && typeof props === "object") {

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

@@ -26,9 +26,9 @@
  *
  * Browser-safe: no Node built-ins.
  */
-import type { ResourceManifest } from "@telorun/sdk";
+import { type ResourceManifest } from "@telorun/sdk";
 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;

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

@@ -1 +1 @@
-{"version":3,"file":"validate-zone-slots.d.ts","sourceRoot":"","sources":["../src/validate-zone-slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,yBAAyB,CAAC;IAChC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAmID,iFAAiF;AACjF,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,gBAAgB,GAAG,aAAa,EAAE,CAM1F"}
+{"version":3,"file":"validate-zone-slots.d.ts","sourceRoot":"","sources":["../src/validate-zone-slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAuC,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG1F,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,yBAAyB,GAAG,wBAAwB,GAAG,2BAA2B,CAAC;IACzF,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AA0TD,iFAAiF;AACjF,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,gBAAgB,GAAG,aAAa,EAAE,CAM1F"}

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"}