@telorun/sdk 0.75.0 → 0.79.0

package/dist/cancellation.d.ts

@@ -1,3 +1,4 @@
+import type { DurableRunHandle } from "./durable-run.js";
 import type { ResourceHandle } from "./resource-instance.js";
 /**
  * Cooperative invocation cancellation — the standard source/token split.
@@ -66,6 +67,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;
 }
 /**
  * The ONE way to build a context derived from another. A fresh object literal
@@ -77,7 +121,12 @@ export interface InvokeContext {
  */
 export declare function deriveContext(base: InvokeContext, overrides: Partial<InvokeContext>): InvokeContext;
 /** 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 {
     /** The resource the span is attributed to (an inbound transport's listener,

package/dist/cancellation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../src/cancellation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../src/cancellation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;yDACqD;IACrD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B;2CACuC;IACvC,WAAW,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACxE,kEAAkE;IAClE,gBAAgB,IAAI,IAAI,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC;sCACkC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;IACzC;;4CAEwC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;mFAC+E;IAC/E,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;2CAGuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAEnG;AAED,qEAAqE;AACrE;;;;2DAI2D;AAC3D,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEhF,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B;0DACsD;IACtD,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;kDAC8C;IAC9C,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,qEAAqE;IACrE,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC;4EACwE;IACxE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,uCAAuC;IACvC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;mEAG+D;IAC/D,OAAO,IAAI,IAAI,CAAC;CACjB;AAiFD,wBAAgB,wBAAwB,IAAI,kBAAkB,CAE7D;AAMD;2EAC2E;AAC3E,eAAO,MAAM,eAAe,EAAE,iBAU7B,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,EAAE,aAAiD,CAAC;AAEtF,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAMzD"}

package/dist/contract-errors.d.ts

@@ -22,7 +22,14 @@ export declare const ERR_OUTPUT_INVALID = "ERR_OUTPUT_INVALID";
  *  data, the contract itself is unusable, and enforcement must fail rather than
  *  quietly switch itself off. */
 export declare const ERR_CONTRACT_UNRESOLVABLE = "ERR_CONTRACT_UNRESOLVABLE";
-export declare const AMBIENT_CONTRACT_ERROR_CODES: readonly ["ERR_INPUT_INVALID", "ERR_OUTPUT_INVALID", "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 declare const ERR_SCHEMA_PROJECTION_UNRESOLVED = "ERR_SCHEMA_PROJECTION_UNRESOLVED";
+export declare const AMBIENT_CONTRACT_ERROR_CODES: readonly ["ERR_INPUT_INVALID", "ERR_OUTPUT_INVALID", "ERR_CONTRACT_UNRESOLVABLE", "ERR_SCHEMA_PROJECTION_UNRESOLVED"];
 export type AmbientContractErrorCode = (typeof AMBIENT_CONTRACT_ERROR_CODES)[number];
 /** True when a code is raised by the kernel's contract enforcement rather than
  *  declared by a kind. Callers use it to accept the code in a `catches:` entry

package/dist/contract-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-errors.d.ts","sourceRoot":"","sources":["../src/contract-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD;;;iCAGiC;AACjC,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAErE,eAAO,MAAM,4BAA4B,mFAI/B,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AAIrF;;6DAE6D;AAC7D,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE"}
+{"version":3,"file":"contract-errors.d.ts","sourceRoot":"","sources":["../src/contract-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD;;;iCAGiC;AACjC,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAErE;;;;;gEAKgE;AAChE,eAAO,MAAM,gCAAgC,qCAAqC,CAAC;AAEnF,eAAO,MAAM,4BAA4B,uHAK/B,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AAIrF;;6DAE6D;AAC7D,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE"}

package/dist/contract-errors.js

@@ -22,10 +22,18 @@ export const ERR_OUTPUT_INVALID = "ERR_OUTPUT_INVALID";
  *  data, the contract itself is unusable, and enforcement must fail rather than
  *  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,
 ];
 const AMBIENT = new Set(AMBIENT_CONTRACT_ERROR_CODES);
 /** True when a code is raised by the kernel's contract enforcement rather than

package/dist/durable-run.d.ts

@@ -0,0 +1,310 @@
+/**
+ * The durable-execution replay seam — `kernel/specs/durable-execution.md`.
+ *
+ * Durable execution is **journal plus deterministic replay**, and Telo can have
+ * it because of a property that fell out of `Run.Sequence`'s design: control
+ * flow is a finite, DECLARED set of CEL expressions over run state, not
+ * arbitrary code. So replay is re-running the step list while returning recorded
+ * values instead of computing them. No continuation capture.
+ *
+ * **What is shared is this narrow seam, not a portable engine vocabulary.** The
+ * temptation is to abstract durable execution itself — one surface every backend
+ * implements — and it fails the same way twice: the abstraction becomes the
+ * union of every engine's lifecycle model (identity policy, schedule overlap,
+ * cancel-versus-terminate, deployment pinning), and each backend still loses the
+ * half of its own model that did not generalize. Portability is close to
+ * worthless here — in-flight runs do not migrate between engines, the
+ * configuration shares nothing, and nobody switches durable engines twice.
+ *
+ * The real constraint is that **the step engine must not fork**. It lives in
+ * this package, which is symlinked into every controller bundle rather than
+ * inlined, so there is exactly one implementation however many backends exist.
+ * What still needs a seam is the other half — *whether and where a step
+ * executes* — and that is all this file is.
+ *
+ * **The kernel is a pure conduit**: it carries the handle on `InvokeContext` and
+ * never calls it, which is why the contract lives here rather than in the kernel
+ * — the split logging already makes between `Logger` / `RecordBuffer` and the
+ * `Telo.LogSink` abstract. The consequence is stated rather than implied: unlike
+ * `zones`, this member does NOT cross the ABI, so a second runtime threads a
+ * handle it owns.
+ */
+import type { InvokeContext, ZoneEntry } from "./cancellation.js";
+import type { OpenZoneAttributes, ZoneAttributes } from "./zone-attribute.js";
+/**
+ * WHERE a step's target is declared, as opposed to which live object it is.
+ *
+ * This is the part of `step()` that nothing may move later, and it is what keeps
+ * the seam from being theatre. A target arrives at the engine as a **live
+ * instance** — Phase-5 injection has already replaced the `!ref` sentinel — and
+ * instance identity is process-local by construction (`ResourceHandle.ref` is
+ * declaration-site *diagnostics*, and there is deliberately no reverse
+ * handle→instance mapping). A backend asked to execute a step somewhere else
+ * would therefore have nothing to resolve, which would make the remote half
+ * unreachable and reduce `step(path, target, inputs)` to lookup-plus-record
+ * under a longer name.
+ *
+ * The three forms follow the three ways a resource is declared, and each is
+ * derivable identically by the analyzer and at runtime. The ENCODING — how one
+ * is written into bytes that cross a process boundary — is deliberately not
+ * fixed here: nothing in this slice sends one anywhere, and a normative format
+ * frozen with no consumer is the failure the sequencing rule exists to prevent.
+ */
+export interface DurableTarget {
+    /** Canonical `<module>.<Kind>` of the target. */
+    readonly kind: string;
+    /** The target's `metadata.name`. Names are dot-free by the reference
+     *  grammar's load-bearing invariant, so `(module, name)` is unambiguous. */
+    readonly name: string;
+    /** Source of the module that DECLARED the target, when known — the half that
+     *  disambiguates two libraries each declaring a `store`. */
+    readonly module?: string;
+    /**
+     * The target is declared inside a `with:` scope.
+     *
+     * Separate from {@link scope} because the two are known at different places: a
+     * step engine can see THAT its target came from a scope — it resolved the name
+     * there — while the tuple identifying which scope RUN needs the step path the
+     * scope was opened at, which a scope handle is built without. Recording only
+     * the tuple would make an underivable scope indistinguishable from a
+     * module-level target, and that is the one difference that must not be lost:
+     * a scoped instance encoded as module-level resolves, at the far end, to a
+     * DIFFERENT resource that merely shares its name.
+     */
+    readonly scoped?: true;
+    /** A `with:`-scoped instance: the scope run is what makes it distinct, and
+     *  inside a durable run a scope run is opened by a step at a determined path,
+     *  so the tuple stays deterministic. */
+    readonly scope?: {
+        readonly owner: string;
+        readonly site: string;
+        readonly stepPath: string;
+    };
+    /** An inline declaration: anonymous in the manifest, not anonymous in the
+     *  graph — the call graph already gives one its own node. */
+    readonly pointer?: string;
+}
+/** Why a decision was recorded. Carried for diagnostics and for a backend that
+ *  wants to render a run; the engine's own behaviour does not branch on it. */
+export type DurableDecisionKind = "inputs" | "predicate" | "condition" | "collection" | "switch" | "value";
+/**
+ * The three operations a backend implements, and the middle one is the whole
+ * design.
+ *
+ * A fourth member is a **question, not an operation** ({@link writesInside}).
+ */
+export interface DurableRunHandle {
+    /** This run's identity, as the backend minted or accepted it. */
+    readonly runId: string;
+    /**
+     * Hand over an effect to be performed: the backend decides **whether**
+     * (replay returns the recorded result) and **where** (in process now, or
+     * shipped elsewhere and awaited).
+     *
+     * `execute` performs the in-process dispatch. Passing it is NOT the
+     * lookup-plus-record decomposition this seam rejects — there the CALLER
+     * performed the effect between two halves of one operation, which silently
+     * fixed the step engine and the resource graph in one process. Here the
+     * backend decides; `execute` is merely the local capability it may choose to
+     * use, and a relocating backend ignores it and ships `target` instead.
+     *
+     * Wherever a step ends up running, the executing side MUST dispatch through
+     * its kernel's invocation chokepoint, so the invocation contract, tracing,
+     * zones and observed state hold identically. A backend may move WHERE a step
+     * executes; it may not move it outside the runtime's dispatch.
+     */
+    step(path: string, target: DurableTarget | undefined, inputs: unknown, execute: () => Promise<unknown>): Promise<unknown>;
+    /**
+     * Record a control-flow decision on first execution and return it verbatim on
+     * replay — a resolved input set, a branch predicate, a loop condition, an
+     * iteration collection.
+     *
+     * **This is the load-bearing half.** The tempting claim — "a run's entire
+     * mutable state is the `steps` map" — is FALSE: the CEL scope a step's inputs
+     * and a branch's predicate evaluate against also carries `resources.<name>`
+     * snapshots, `resources.<name>.status` (a live reading, republished on every
+     * dispatch BY DESIGN), provider values, variables and secrets. Re-evaluating
+     * any of those in a fresh process against freshly-created resources can yield
+     * a different answer, and the sharpest case is silent: an iteration whose
+     * collection comes from a resource read returns a different order on resume,
+     * index N now names a different element, and the journal hands back the
+     * recorded result for that path — with the same target, so no mismatch is
+     * detectable. Wrong results, no error.
+     *
+     * Recording the value rather than a digest is deliberate. Digest-and-detect is
+     * equally closed for DETECTION and much cheaper, and it is wrong: observed
+     * state is *defined* as a live reading, so a run would fail on every resume
+     * where the world had moved, which it usually has. That is not durability; it
+     * is fragility with good error messages.
+     *
+     * Replay is then a pure function of `(journal, manifest)` — a CLOSURE
+     * property, and closure is what makes this survive an ambient value source
+     * added years from now without anyone re-auditing a list.
+     */
+    decide<T>(path: string, kind: DurableDecisionKind, compute: () => T): Promise<T>;
+    /**
+     * Suspend the run until a time or a token.
+     *
+     * **A park is recorded, not merely thrown.** `where` is what makes it
+     * recoverable: the step path is where a resume re-enters and where a delivery
+     * writes its payload, so a backend that took only `until` could wake a run
+     * without knowing what it was waiting at. The parking resource's name rides
+     * along for diagnostics, since "run 41 is parked" is not an operator's answer.
+     *
+     * Called through {@link parkRun}, never directly — the latch that catches a
+     * swallowed suspension is set there, so a backend cannot forget it.
+     */
+    park(where: {
+        readonly path: string;
+        readonly resource: string;
+    }, until: {
+        readonly at?: number;
+        readonly token?: string;
+    }): Promise<never>;
+    /**
+     * Does this handle's own recording land inside the given zone's atomicity?
+     *
+     * A question, not an operation — and it is what lets the step engine stop
+     * collapsing an `atomic` zone when collapsing would be pessimistic. A
+     * collapsed atomic zone is at-least-once (the whole zone re-runs on resume,
+     * because a crash between COMMIT and the journal write leaves work done and
+     * unrecorded) and that is unavoidable ONLY while the journal is somewhere
+     * else. When the journal writes into the very transaction whose effects it
+     * records, COMMIT is atomic over both and the window closes.
+     *
+     * So the collapse rule reads the attribute correctly rather than overriding
+     * it: `atomic` says *effects inside are discarded together*, and collapse
+     * follows only when the journal's own writes are NOT among them.
+     *
+     * Every backend that cannot answer yes returns false and behaves exactly as it
+     * would have without the question existing.
+     */
+    writesInside(zone: ZoneEntry): boolean;
+    /**
+     * Told when a region was collapsed to one entry, and why.
+     *
+     * Optional, and a NOTIFICATION rather than a question: the collapse decision
+     * is the step engine's, and the handle is being informed so it can report.
+     * That reporting is a conformance requirement rather than a nicety — whether a
+     * deployment got exactly-once or at-least-once turns on whether the journal's
+     * writes land inside the transaction's atomicity, which is a runtime
+     * coincidence the manifest cannot show. A durability feature whose guarantee
+     * is decided invisibly has to say which way it resolved.
+     */
+    noteZoneMode?(info: ZoneJournalingMode): void;
+}
+/**
+ * How one region resolved, at the moment it resolved.
+ *
+ * Both outcomes are reported, not only the collapsed one, and that is the point:
+ * `perStep` is the exactly-once regime and it is reached by an ATTESTATION made
+ * at runtime, so an operator asking "did this deployment get exactly-once"
+ * needs the affirmative answer as much as the negative. One field to filter on
+ * (`mode`) rather than the presence or absence of a record.
+ */
+export interface ZoneJournalingMode {
+    /** The providing kind — `Sql.Transaction`, `Idempotency.Once`. */
+    readonly zone: string;
+    readonly attribute: "atomic" | "idempotent";
+    /** `collapsed`: the region records one entry and re-runs whole on resume.
+     *  `perStep`: each step is recorded, and a rollback discards the records with
+     *  the effects they describe. */
+    readonly mode: "collapsed" | "perStep";
+    /** The author's own sentence from the attribute, so the reason an operator
+     *  reads is the manifest's rather than a generic one. */
+    readonly reason: string;
+    /** Why `perStep` was reached. Only `writesInside` today — the handle attested
+     *  that its own records land inside this zone's atomicity — and named rather
+     *  than implied, so a second attestation route is additive. */
+    readonly attestation?: "writesInside";
+}
+/**
+ * Compose a step path — the journal's key, and the reason journaling lives in
+ * the step engine at all.
+ *
+ * A step path is the only naturally deterministic key available, and it survives
+ * CONCURRENCY where a per-run call ordinal would not: two branches of a
+ * concurrent fan-out interleave their dispatches, so an ordinal would number
+ * them differently on every run while their paths stay fixed. It is also what
+ * makes each branch of a fan-out an independently resumable subtree.
+ *
+ * Segments are joined with `/`; a repetition (a loop turn, an iteration element)
+ * qualifies its segment with `[index]`. Both are properties of the WRITTEN
+ * structure plus the run's own decisions, never of wall-clock order.
+ */
+export declare function stepPath(...segments: (string | number)[]): string;
+/** True when a run handle is ambient — the test the step engine makes before it
+ *  journals anything, so a non-durable sequence pays nothing. */
+export declare function durableHandleOf(ctx: InvokeContext | undefined): DurableRunHandle | undefined;
+/**
+ * What the step engine consults before journaling anything — the collapse rule,
+ * read off the ambient zone stack.
+ *
+ * > A region collapses to one entry when **re-running it is safe** — because its
+ * > effects are discarded together, or because re-running is a no-op.
+ *
+ * The rule has no fields in it, at either end. It used to be a caller-side
+ * `checkpoint: collapse` plus a callee-side `requireCheckpoints:` veto, which
+ * was wrong four ways at once: a boolean where every neighbouring annotation
+ * carries a reason; the opposite polarity from *everything journaled by
+ * default*, so forgetting to veto was silent; a veto available only on
+ * `Run.Sequence`, leaving a collapsed script or imported invocable unprotected;
+ * and a contradiction check to reconcile it with atomicity. Underneath all four,
+ * collapse was sold as a cost lever while being a CORRECTNESS decision — it
+ * silently converts exactly-once into at-least-once.
+ *
+ * A region with a property is a zone, so it is declared the way every other
+ * region property is. Nothing collapses a sequence because nothing wrapped it.
+ */
+export declare function collapsesJournalEntries(zones: readonly {
+    kind: string;
+    attributes: ZoneAttributes;
+    entry: ZoneEntry;
+}[], handle: DurableRunHandle): {
+    collapsed: boolean;
+    resolutions: ZoneJournalingMode[];
+};
+/** The zone-reading half of a step context — declared here so both the leaf and
+ *  the engine read the collapse rule through one signature. */
+export interface ZoneReadingContext {
+    zoneAttributes?(ctx?: InvokeContext): readonly OpenZoneAttributes[];
+}
+/**
+ * Should the step engine record nothing of its own right here?
+ *
+ * True inside a collapsed region, where per-step entries would describe work
+ * that is about to happen again — the region re-runs whole on resume, which is
+ * exactly what its author's attribute claims is safe.
+ *
+ * A host with no zone machinery reads as "no zone open", which journals MORE
+ * rather than less: the safe direction, since an unjournaled effect re-executes
+ * silently while a redundant entry costs a write.
+ */
+export declare function journalingSuppressed(ctx: ZoneReadingContext, invokeCtx: InvokeContext | undefined, handle: DurableRunHandle): boolean;
+/**
+ * Reject a value that cannot survive being recorded and read back.
+ *
+ * **`JSON.stringify` is not the test, and believing it was left the gate open.**
+ * A live handle has no enumerable state, so `JSON.stringify(stream)` returns
+ * `{}` and throws nothing — the one case the spec names first would have been
+ * recorded as an empty object and replayed as one, which is silent corruption
+ * rather than the loud failure §6 requires. The static half is deliberately only
+ * a warning ("the runtime is the gate"), so a gate that cannot see the case
+ * leaves it unenforced end to end.
+ *
+ * So a live value is detected STRUCTURALLY, by the value-type vocabulary's own
+ * binding table: an entry declaring `live: true` names a binding, and the host's
+ * table maps that binding to the constructor an assertion tests against. No type
+ * name is written here, so a live type added later is covered by its entry
+ * alone — the same reason the static rule reads the `live` field rather than
+ * naming `Telo.Stream`.
+ *
+ * Lives in the SDK rather than in a backend because it is a property of the
+ * CONTRACT (spec §6), not of one journal: a backend that skipped it would be
+ * non-conforming in a way nothing else could catch.
+ */
+export declare function assertJournalable(value: unknown, where: {
+    run: string;
+    path: string;
+}): void;
+//# sourceMappingURL=durable-run.d.ts.map

package/dist/durable-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-run.d.ts","sourceRoot":"","sources":["../src/durable-run.ts"],"names":[],"mappings":"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"}