@telorun/sdk 0.77.0 → 0.80.0

package/dist/zone-attribute.js

@@ -0,0 +1,130 @@
+/**
+ * Zone attributes — what an `x-telo-provides-zone` object form declares about
+ * the region a body slot establishes, and the single accessor every surface
+ * reads that vocabulary through (the `value-type.ts` precedent, itself the
+ * `ref-slot.ts` one).
+ *
+ * A body slot that CONSTRAINS its contents is a body slot that already
+ * ESTABLISHES a zone — a transaction, a lease, an idempotency claim, a durable
+ * run are all of them — so the constraints are attributes on the annotation
+ * rather than a second annotation family that would have to restate the zone's
+ * location, its `extends` resolution and its runtime open call.
+ *
+ * THE VOCABULARY IS DATA; THE MEANING IS THE CONSUMER'S. Entries live at
+ * `sdk/zone-attributes/*.json` (see the README there) and are copied in by the
+ * root `prepare`. Both kernels read the identical files, because `noSuspend` is
+ * what stops a run parking inside a lease wherever that run executes. An entry
+ * declares a name, a value schema and its `requires:` dependencies, and no code:
+ * there is nothing per entry to implement.
+ *
+ * THE SET IS CLOSED. `x-telo-ref`'s `use` is a closed set on the same annotation
+ * family and nothing has needed to extend it; capabilities and value types are
+ * closed. The argument for openness inverts on inspection — `metadata.categories`
+ * is open precisely because NOTHING BRANCHES ON IT, while every zone attribute
+ * exists to be branched on and every reader is core. And a third-party attribute
+ * could only ever be HALF an attribute: a module cannot contribute an analyzer
+ * pass, so it would get a runtime reader here and no static check, while the
+ * failure directions that justify validating this vocabulary at all — an unread
+ * `noSuspend`, an unread `atomic` — are exactly the ones only a static check
+ * catches.
+ *
+ * THE REGISTRY IS IN THE SDK for the reasons the value-type one is: it is
+ * dependency-free and Node-built-in-free (so the browser-side analyzer can read
+ * it), and it is the only placement a module controller can reach.
+ */
+import { ZONE_ATTRIBUTE_ENTRY_FILES } from "./zone-attributes/entries/index.js";
+class ZoneAttributeEntryError extends Error {
+    constructor(file, detail) {
+        super(`Invalid zone-attribute entry '${file}': ${detail}`);
+        this.name = "ZoneAttributeEntryError";
+    }
+}
+const ENTRY_KEYS = ["name", "value", "requires", "description", "$comment"];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(file, node, key) {
+    const value = node[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ZoneAttributeEntryError(file, `'${key}' must be a non-empty string`);
+    }
+    return value;
+}
+/**
+ * Read one entry file's parsed data.
+ *
+ * Reading is STRICT and the vocabulary is closed at every level, for the reason
+ * the value-type reader is: a malformed or typo'd entry's only other outcome is
+ * an attribute that quietly is not in the vocabulary — which reads to an author
+ * as "unknown name", pointing at their manifest instead of at the entry.
+ */
+export function parseZoneAttributeEntry(file, data) {
+    if (!isPlainObject(data))
+        throw new ZoneAttributeEntryError(file, "an entry must be a mapping");
+    for (const key of Object.keys(data)) {
+        if (!ENTRY_KEYS.includes(key)) {
+            throw new ZoneAttributeEntryError(file, `an entry has no key '${key}'. Known keys: ${ENTRY_KEYS.join(", ")}.`);
+        }
+    }
+    const name = requireString(file, data, "name");
+    // Bare names, checked here rather than left to convention: a qualified one
+    // would be a key nothing resolves, and the closed set has nothing to qualify
+    // against.
+    if (!/^[a-z][A-Za-z0-9]*$/.test(name)) {
+        throw new ZoneAttributeEntryError(file, `'name' must be a bare camelCase word — the annotation position already implies ` +
+            `the namespace, and a closed set has no second namespace to qualify against`);
+    }
+    if (!isPlainObject(data.value)) {
+        throw new ZoneAttributeEntryError(file, "'value' must be a JSON Schema mapping");
+    }
+    const requires = data.requires === undefined ? [] : data.requires;
+    if (!Array.isArray(requires) || requires.some((r) => typeof r !== "string" || !r)) {
+        throw new ZoneAttributeEntryError(file, "'requires' must be a sequence of attribute names");
+    }
+    if (requires.includes(name)) {
+        throw new ZoneAttributeEntryError(file, `'requires' names '${name}' itself`);
+    }
+    return {
+        name,
+        value: data.value,
+        requires: requires,
+        description: requireString(file, data, "description"),
+    };
+}
+function buildRegistry() {
+    const registry = new Map();
+    for (const [file, data] of ZONE_ATTRIBUTE_ENTRY_FILES) {
+        const entry = parseZoneAttributeEntry(file, data);
+        if (registry.has(entry.name)) {
+            throw new ZoneAttributeEntryError(file, `'${entry.name}' is already declared by another entry`);
+        }
+        registry.set(entry.name, entry);
+    }
+    // A `requires:` naming an attribute no entry declares would compile to a
+    // `dependentRequired` clause nothing can ever satisfy, so every declaration of
+    // the depending attribute would be rejected with no way to fix it. Checked
+    // after the whole set is read, since entries are order-independent.
+    for (const entry of registry.values()) {
+        for (const dependency of entry.requires) {
+            if (!registry.has(dependency)) {
+                throw new ZoneAttributeEntryError(`${entry.name}.json`, `'requires' names '${dependency}', which no entry declares`);
+            }
+        }
+    }
+    // Defence in depth against the packaging mistake, whose failure is
+    // indistinguishable from an author's typo: every declared attribute becomes an
+    // unknown name, reported against manifests that are correct.
+    if (registry.size === 0) {
+        throw new Error("The zone-attribute vocabulary is empty. `sdk/zone-attributes/*.json` did not reach " +
+            "this build — check the file allowlist of whatever packaged it. Continuing would " +
+            "report every declared attribute as an unknown name, while enforcing none of them.");
+    }
+    return registry;
+}
+/** Every declared zone attribute, keyed by its bare name. */
+export const ZONE_ATTRIBUTES = buildRegistry();
+/** The declared names, in entry order — what a diagnostic listing the closed
+ *  vocabulary prints. */
+export function zoneAttributeNames() {
+    return [...ZONE_ATTRIBUTES.keys()];
+}

package/dist/zone-attributes/entries/atomic.json

@@ -0,0 +1,7 @@
+{
+    "$comment": "Distinct from `idempotent`, and the exactly-once machinery reads the difference literally: per-step journaling is safe inside a transaction PRECISELY because a rollback erases the journal's own entries too. A region that rolls nothing back has no such property, so it declares `idempotent` instead — borrowing this name there would let a journal's attestation relax collapse and record entries for effects that will re-run.",
+    "name": "atomic",
+    "requires": ["noSuspend"],
+    "value": { "type": "string", "minLength": 1 },
+    "description": "Effects inside are discarded together on failure, so a consumer recording them individually would record work a rollback erases."
+}

package/dist/zone-attributes/entries/idempotent.json

@@ -0,0 +1,6 @@
+{
+    "$comment": "Worn by a provider that ENFORCES the property (Idempotency.Once, whose claim makes it true) and by one that merely ASSERTS it on the author's word (Durable.Idempotent). Which one an author reaches for is a cost decision, visible in the manifest as a different kind rather than as a flag on one.",
+    "name": "idempotent",
+    "value": { "type": "string", "minLength": 1 },
+    "description": "Re-executing the zone is observably a no-op — the same writes land, or land once. Nothing is discarded, so unlike an atomic region there is no rollback for a consumer's own records to participate in."
+}

package/dist/zone-attributes/entries/index.d.ts

@@ -0,0 +1,3 @@
+/** Every zone-attribute entry file, in the order the registry reads them. */
+export declare const ZONE_ATTRIBUTE_ENTRY_FILES: ReadonlyArray<readonly [file: string, data: unknown]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/zone-attributes/entries/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/zone-attributes/entries/index.ts"],"names":[],"mappings":"AAOA,6EAA6E;AAC7E,eAAO,MAAM,0BAA0B,EAAE,aAAa,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAK5F,CAAC"}

package/dist/zone-attributes/entries/index.js

@@ -0,0 +1,13 @@
+// GENERATED by scripts/copy-zone-attribute-entries.mjs — do not edit, and do not commit.
+// Source: sdk/zone-attributes/*.json (lexically ordered).
+import e0 from "./atomic.json" with { type: "json" };
+import e1 from "./idempotent.json" with { type: "json" };
+import e2 from "./no-suspend.json" with { type: "json" };
+import e3 from "./replayed.json" with { type: "json" };
+/** Every zone-attribute entry file, in the order the registry reads them. */
+export const ZONE_ATTRIBUTE_ENTRY_FILES = [
+    ["atomic.json", e0],
+    ["idempotent.json", e1],
+    ["no-suspend.json", e2],
+    ["replayed.json", e3],
+];

package/dist/zone-attributes/entries/no-suspend.json

@@ -0,0 +1,6 @@
+{
+    "$comment": "The clearest case for the reason-as-value design: one name is worn by a transaction holding a connection, a lease that lapses unrenewed, an idempotency claim, and later a deadline scope whose bound would elapse while parked. Four providers, four different reasons, one attribute — without the prose the pressure would be to invent `connectionHeld`, `leaseHeld` and `deadlineBound` as separate entries.",
+    "name": "noSuspend",
+    "value": { "type": "string", "minLength": 1 },
+    "description": "The zone holds something bounded that cannot outlive the current process — a connection, a lease, a claim — so execution inside it must not park and resume elsewhere."
+}

package/dist/zone-attributes/entries/replayed.json

@@ -0,0 +1,6 @@
+{
+    "$comment": "This attribute, and nothing else, is what makes a zone durable to the static checks. Keying them on the bare `x-telo-provides-zone` annotation would apply DURABLE_NONDETERMINISM and its siblings inside every Sql.Transaction in the ecosystem, since transactions, leases and idempotency claims all provide zones. Keying them on a `Durable.Run` kind would instead put a module's kind into analyzer code.",
+    "name": "replayed",
+    "value": { "type": "string", "minLength": 1 },
+    "description": "Execution inside may be re-run from a record of a previous execution, so it must reach the same decisions on every pass and the values it produces must be serializable."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sdk",
-  "version": "0.77.0",
+  "version": "0.80.0",
   "description": "Telo SDK - Public API for Telo module authors.",
   "keywords": [
     "telo",

package/src/cancellation.ts

@@ -1,4 +1,5 @@
 import { InvokeError } from "./invoke-error.js";
+import type { DurableRunHandle } from "./durable-run.js";
 import type { ResourceHandle } from "./resource-instance.js";
 
 /**
@@ -72,6 +73,49 @@ export interface InvokeContext {
   readonly traceId?: string;
   /** Zones open around this invocation, outermost first. Absent = none. */
   readonly zones?: readonly ZoneEntry[];
+  /**
+   * The durable run this invocation is executing inside, when there is one —
+   * the replay seam the step engine journals through
+   * (`kernel/specs/durable-execution.md`).
+   *
+   * **Its own member, not a `ZoneEntry` payload.** The durable zone IS a real
+   * zone and rides the stack above, but an entry is three identities *because*
+   * that keeps it ABI-serializable and stops any controller reading another
+   * module's open state off the stack. A run handle is a live object with
+   * methods, and hanging it on the entry would trade that property away for
+   * every zone, durable or not. The landed payload rule (provider-private state
+   * lives on an instance injected across the boundary) cannot carry it either —
+   * a nested `Run.Sequence` holds no durable reference, so a sequence two levels
+   * down has no injected instance to read from.
+   *
+   * The consequence, stated rather than implied: unlike {@link zones}, this
+   * member does **not** cross the ABI. The kernel is a pure conduit — it carries
+   * the handle and never calls it — so a second runtime threads a handle it
+   * owns rather than deserializing this one.
+   *
+   * Picked up by every nested dispatch, which is what makes nesting work with no
+   * per-module effort: a nested sequence, in this module or across an import
+   * boundary, journals its steps under the outer step's path, so a crash inside
+   * it resumes inside it.
+   */
+  readonly durable?: DurableRunHandle;
+  /**
+   * The journal path of the step whose dispatch led here, when this invocation
+   * is inside a durable run.
+   *
+   * The other half of carriage, and without it nesting is silently wrong rather
+   * than merely unsupported: a nested step body that started its own paths at
+   * `steps` would record `steps/<name>` for every body in the run, so two nested
+   * bodies with a same-named step share one key. First-writer-wins then hands
+   * the second the first's RESULT — and when both dispatch the same target there
+   * is no mismatch to detect, so the run continues with a value produced for a
+   * different step.
+   *
+   * A nested engine reads this as the base its own step paths hang under, which
+   * is what makes "a crash inside a nested body resumes inside it" true. Absent
+   * at the top of a run, where the base is `steps`.
+   */
+  readonly durablePath?: string;
 }
 
 /**
@@ -87,7 +131,12 @@ export function deriveContext(base: InvokeContext, overrides: Partial<InvokeCont
 }
 
 /** Terminal status of a span — maps to OpenTelemetry span status. */
-export type SpanOutcome = "ok" | "failed" | "rejected" | "cancelled";
+/** How an invocation ended.
+ *
+ *  `parked` is its own outcome and not a flavour of failure: a suspended
+ *  invocation neither succeeded nor failed, and recording it as failed would
+ *  make a trace say the run broke every time it waited. */
+export type SpanOutcome = "ok" | "failed" | "rejected" | "cancelled" | "parked";
 
 /** Options for {@link ResourceContext.openSpan}. */
 export interface OpenSpanOptions {

package/src/contract-errors.ts

@@ -26,10 +26,19 @@ export const ERR_OUTPUT_INVALID = "ERR_OUTPUT_INVALID";
  *  quietly switch itself off. */
 export const ERR_CONTRACT_UNRESOLVABLE = "ERR_CONTRACT_UNRESOLVABLE";
 
+/** A contract slot declaring `x-telo-schema-projection-from` named a declaration
+ *  that could not be projected. The same failure as {@link
+ *  ERR_CONTRACT_UNRESOLVABLE} one level down: the slot promises the shape of a
+ *  referenced declaration, so leaving it unprojected enforces nothing exactly
+ *  where it claims to enforce something. Its own code because the repair is
+ *  different — fix the reference, not the type registration. */
+export const ERR_SCHEMA_PROJECTION_UNRESOLVED = "ERR_SCHEMA_PROJECTION_UNRESOLVED";
+
 export const AMBIENT_CONTRACT_ERROR_CODES = [
   ERR_INPUT_INVALID,
   ERR_OUTPUT_INVALID,
   ERR_CONTRACT_UNRESOLVABLE,
+  ERR_SCHEMA_PROJECTION_UNRESOLVED,
 ] as const;
 
 export type AmbientContractErrorCode = (typeof AMBIENT_CONTRACT_ERROR_CODES)[number];