@telorun/analyzer 0.62.1 → 0.64.0

package/dist/zone-slot.js

@@ -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,8 +24,10 @@
  *     key: [/connection, /transaction/connection]  # ordered, first hit wins
  *     reason: the statement would execute outside any transaction
  */
+import { ZONE_ATTRIBUTES } from "@telorun/sdk";
 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 the
  *  analyzer and the kernel read identically. Applied to BOTH the scalar and the
  *  list form: the kernel's walk splits on `/` and drops empty segments, so a
@@ -33,10 +42,38 @@ function isPointer(value) {
 export function readProvidesZone(node) {
     const raw = node?.[PROVIDES];
     if (raw === true)
-        return {};
+        return { attributes: {} };
     if (isPointer(raw))
-        return { key: raw };
-    return undefined;
+        return { key: raw, attributes: {} };
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const obj = raw;
+    // 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 = {};
+    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 };
+}
+/** 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) {
+    return readProvidesZone(node)?.attributes ?? {};
 }
 /** 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. */
@@ -48,7 +85,7 @@ export function hasProvidesZone(node) {
 export function readRequiresZone(node) {
     const raw = node?.[REQUIRES];
     if (typeof raw === "string" && raw)
-        return { zone: raw, key: [] };
+        return { zone: raw, key: [], attributes: [] };
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return undefined;
     const obj = raw;
@@ -56,11 +93,55 @@ export function readRequiresZone(node) {
         return undefined;
     // One filter for both spellings — see `isPointer`.
     const key = (Array.isArray(obj.key) ? obj.key : [obj.key]).filter(isPointer);
-    const slot = { 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) => typeof a === "string" && ZONE_ATTRIBUTES.has(a));
+    const slot = { 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) {
+    const raw = node?.[VIOLATES];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        // 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;
+}
+/** True when the node carries `x-telo-violates-zone` in any shape, valid or not. */
+export function hasViolatesZone(node) {
+    return node?.[VIOLATES] !== undefined;
+}
 /** True when the node carries `x-telo-requires-zone` in any shape. */
 export function hasRequiresZone(node) {
     return node?.[REQUIRES] !== undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.62.1",
+  "version": "0.64.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -49,7 +49,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.77.0"
+    "@telorun/sdk": "0.80.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/analysis-registry.ts

@@ -1,6 +1,7 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { AliasResolver } from "./alias-resolver.js";
 import { KERNEL_BUILTINS } from "./builtins.js";
+import { ManifestAnalysis } from "./manifest-analysis.js";
 import { DefinitionRegistry } from "./definition-registry.js";
 import { computeSuggestKind, computeValidUserFacingKinds } from "./kind-suggest.js";
 import { visitManifest as runVisitManifest, type ManifestVisitor } from "./manifest-visitor.js";
@@ -174,6 +175,12 @@ export class AnalysisRegistry {
   ): Record<string, unknown> | undefined {
     const def = this.resolveDefinition(kind);
     if (!def) return undefined;
+    // A KIND-level query: there is no instance, so a DECLARATION-derived slot
+    // (`x-telo-schema-projection-from`) has no reference to project from and is
+    // left as the kind declared it. That is the honest answer here — the
+    // projected shape is a property of one instance, not of the kind — and it is
+    // why passing no manifest cannot silently drop a projection: the per-resource
+    // analysis pass is what resolves and reports them.
     return resolveContract(direction, undefined, def, {
       resolveDefinition: this.scopedDefResolver(),
       typeManifestsFor: () => [],
@@ -236,6 +243,42 @@ export class AnalysisRegistry {
     });
   }
 
+  /**
+   * Resolves an `x-telo-schema-from` annotation to the schema node it derives,
+   * in the scope of the kind that DECLARED it — anchors are alias-qualified, and
+   * the declaring definition's module is where those aliases mean something.
+   *
+   * The seam an IDE walks a schema through: a slot shaped entirely by this
+   * annotation (an `Http.Api` route's `request:`) carries no `properties` of its
+   * own, so a walker that only reads `properties` finds nothing there and
+   * silently offers no keys and no hover — a whole field of the standard library
+   * looking like an unknown one.
+   */
+  resolveSchemaFrom(schemaFrom: string, declaringKind: string): Record<string, any> | undefined {
+    const def = this.resolveDefinition(declaringKind);
+    const ownerModule = (def?.metadata as { module?: string } | undefined)?.module;
+    const scope = (ownerModule ? this.aliasesByModule.get(ownerModule) : undefined) ?? this.aliases;
+    return this.defs.resolveSchemaFromNode(schemaFrom, scope);
+  }
+
+  /**
+   * The queries that need this registry AND a manifest set: what CEL sees at a
+   * site, where a binding was declared, what a reference's contract is.
+   *
+   * The seam an IDE reaches all of them through, and one object rather than a
+   * factory per question — each answer has to be the one the analysis pass
+   * computed, or a completion list stops being a claim about what `telo check`
+   * accepts. Built per analysis, not per keystroke: the indices behind it are a
+   * function of the whole manifest set.
+   */
+  analysisOf(manifests: ResourceManifest[]): ManifestAnalysis {
+    return new ManifestAnalysis(manifests, {
+      defs: this.defs,
+      aliases: this.aliases,
+      aliasesByModule: this.aliasesByModule,
+    });
+  }
+
   /**
    * Returns the built-in kernel definitions. The underlying DefinitionRegistry already
    * seeds these on construction; this method exposes them so callers (e.g. the kernel's