@executablemd/durable-streams 0.8.1 → 0.9.1

package/esm/combinators.js

@@ -97,6 +97,7 @@ function* runDurableChild(childWorkflow, childId, parentCtx) {
             if (unaligned) {
                 const failure = new TerminalDivergenceError(unaligned.coroutineId, unaligned.cursor, unaligned.totalYields, {
                     message: `Divergence: coroutine ${childId} was cancelled before retained history was exhausted`,
+                    unconsumed: unaligned.entry,
                 });
                 rememberDurabilityFailure(childCtx, failure);
                 throw failure;
@@ -125,7 +126,7 @@ function* runDurableChild(childWorkflow, childId, parentCtx) {
         const unaligned = replayIndex.firstUnaligned(childId);
         if (unaligned) {
             suppressClose = true;
-            const failure = new EarlyReturnDivergenceError(unaligned.coroutineId, unaligned.cursor, unaligned.totalYields);
+            const failure = new EarlyReturnDivergenceError(unaligned.coroutineId, unaligned.cursor, unaligned.totalYields, unaligned.entry);
             rememberDurabilityFailure(childCtx, failure);
             throw failure;
         }
@@ -146,7 +147,7 @@ function* runDurableChild(childWorkflow, childId, parentCtx) {
         const unaligned = replayIndex.firstUnaligned(childId);
         if (unaligned) {
             suppressClose = true;
-            const failure = new TerminalDivergenceError(unaligned.coroutineId, unaligned.cursor, unaligned.totalYields, { cause: primary });
+            const failure = new TerminalDivergenceError(unaligned.coroutineId, unaligned.cursor, unaligned.totalYields, { cause: primary, unconsumed: unaligned.entry });
             rememberDurabilityFailure(childCtx, failure);
             throw failure;
         }

package/esm/effect.js

@@ -28,6 +28,7 @@ import { defaultLiveDurableOperationCoordinator, } from "./live-coordinator.js";
 import { ReplayGuard } from "./replay-guard.js";
 import { consumable, observeEvent } from "./retained.js";
 import { protocolToEffection, serializeError } from "./serialize.js";
+import { advanceDurablePosition } from "./position.js";
 /** Effection void-ok result, used for no-op teardowns. */
 const VOID_OK = {
     ok: true,
@@ -43,6 +44,7 @@ const VOID_OK = {
  */
 function checkReplay(desc, resolve, routine, ctx) {
     const entry = ctx.replayIndex.peekYield(ctx.coroutineId);
+    let abandoned;
     // ── REPLAY PATH ──
     // Use a labeled block so that divergence decisions of type "run-live"
     // can break out to fall through to the live execution path.
@@ -74,6 +76,7 @@ function checkReplay(desc, resolve, routine, ctx) {
                 }
                 // decision.type === "run-live"
                 ctx.replayIndex.disableReplay(ctx.coroutineId);
+                abandoned = entry;
                 break replay;
             }
             // Description matches — now check replay guards before replaying.
@@ -98,6 +101,7 @@ function checkReplay(desc, resolve, routine, ctx) {
             const outcome = ReplayGuard.invoke(routine.scope, "decide", [yieldEvent]);
             if (outcome.outcome === "error") {
                 ctx.replayIndex.consumeYield(ctx.coroutineId);
+                advanceDurablePosition(ctx);
                 const error = outcome.error ??
                     new StaleInputError(`Stale input detected for ${desc.type}("${desc.name}")`, {
                         coroutineId: ctx.coroutineId,
@@ -109,6 +113,7 @@ function checkReplay(desc, resolve, routine, ctx) {
             }
             // All guards approved — consume the entry and advance cursor
             ctx.replayIndex.consumeYield(ctx.coroutineId);
+            advanceDurablePosition(ctx);
             // Feed stored result synchronously, as a fresh mutable copy: the
             // authoritative result stays frozen so policy cannot rewrite it, while a
             // document that resumes on a restored binding still writes to what it
@@ -136,7 +141,15 @@ function checkReplay(desc, resolve, routine, ctx) {
             break replay;
         }
     } // end replay block
-    return { path: "live" };
+    return {
+        path: "live",
+        abandoned: {
+            ...(abandoned === undefined ? {} : { entry: abandoned }),
+            // The index's own account, not this call's: it stays true for every
+            // operation after the one that diverged.
+            steppedOver: ctx.replayIndex.abandonedHistory(ctx.coroutineId),
+        },
+    };
 }
 /**
  * Creates a DurableEffect using a callback-based executor.
@@ -187,6 +200,9 @@ export function createDurableEffect(desc, execute) {
                 routine.scope.run(function* () {
                     try {
                         yield* appendDurableEvent(ctx, event);
+                        // After the append commits, not before: a position counts what the
+                        // journal holds, so an append that failed must not move it.
+                        advanceDurablePosition(ctx);
                         resolve(protocolToEffection(result));
                     }
                     catch (err) {
@@ -292,7 +308,8 @@ export function createDurableOperation(desc, execute, options = {}) {
                             result: published,
                         };
                         yield* appendDurableEvent(ctx, event);
-                    }, activateFailure, getJournalProvenance(ctx.stream));
+                        advanceDurablePosition(ctx);
+                    }, activateFailure, getJournalProvenance(ctx.stream), replay.abandoned);
                     resolve(protocolToEffection(result));
                 }
                 catch (err) {

package/esm/errors.js

@@ -1,6 +1,66 @@
 /**
  * Error types for the durable execution protocol.
  */
+/**
+ * The description field an authored source position occupies.
+ *
+ * A durable effect's identity is its `type` and `name` and nothing else, so a
+ * position travels beside them under this stable namespaced field. It is
+ * stored, filtered diagnostic data: never compared during divergence
+ * detection, never part of admission.
+ */
+export const SOURCE_POSITION_FIELD = "executablemd.source-position";
+/**
+ * Render one effect description for a divergence diagnostic.
+ *
+ * The identity renders as `type("name")`. When the description retains the
+ * exact normalized source shape under `SOURCE_POSITION_FIELD` — an optional
+ * non-empty `path`, an integer `offset` of at least 0, integer `line` and
+ * `column` of at least 1, and no other member — its human spelling,
+ * `path:line:column` or `line:column` without a path, never the offset, is
+ * appended as ` at …`. Anything else renders nothing at all: formatting a
+ * diagnostic must not introduce a new failure.
+ */
+export function describeEffect(description) {
+    return `${description.type}("${description.name}")${renderedSource(description)}`;
+}
+const SOURCE_MEMBERS = ["path", "offset", "line", "column"];
+function renderedSource(description) {
+    const field = description[SOURCE_POSITION_FIELD];
+    if (field === null || typeof field !== "object" || Array.isArray(field)) {
+        return "";
+    }
+    if (Object.keys(field).some((member) => !SOURCE_MEMBERS.includes(member))) {
+        return "";
+    }
+    const { path, offset, line, column } = field;
+    if (!isCoordinate(offset, 0) || !isCoordinate(line, 1) || !isCoordinate(column, 1)) {
+        return "";
+    }
+    if (path === undefined) {
+        return ` at ${line}:${column}`;
+    }
+    if (typeof path !== "string" || path === "") {
+        return "";
+    }
+    return ` at ${path}:${line}:${column}`;
+}
+function isCoordinate(value, least) {
+    return typeof value === "number" && Number.isInteger(value) && value >= least;
+}
+/**
+ * The terminal-divergence message, naming the first retained entry the
+ * terminating subtree did not reach when one was selected.
+ */
+function withUnreached(message, unconsumed) {
+    if (unconsumed === undefined) {
+        return message;
+    }
+    if (unconsumed.type === "close") {
+        return `${message}; first unreached entry is the Close of coroutine ${unconsumed.coroutineId}`;
+    }
+    return `${message}; first unreached entry is ${describeEffect(unconsumed.description)}`;
+}
 /**
  * Raised when a durable event cannot be persisted.
  *
@@ -53,8 +113,7 @@ export class DivergenceError extends Error {
     constructor(coroutineId, position, expected, actual, message) {
         super(message ??
             `Divergence at ${coroutineId}[${position}]: ` +
-                `expected ${expected.type}("${expected.name}"), ` +
-                `got ${actual.type}("${actual.name}")`);
+                `expected ${describeEffect(expected)}, got ${describeEffect(actual)}`);
         this.coroutineId = coroutineId;
         this.position = position;
         this.expected = expected;
@@ -71,13 +130,16 @@ export class TerminalDivergenceError extends Error {
     coroutineId;
     consumedCount;
     totalCount;
+    /** The first retained entry the terminating subtree did not reach. */
+    unconsumed;
     constructor(coroutineId, consumedCount, totalCount, options = {}) {
-        super(options.message ??
+        super(withUnreached(options.message ??
             `Divergence: workflow ${coroutineId} terminated after ${consumedCount} yields, ` +
-                `but journal has ${totalCount} yield entries`, { cause: options.cause });
+                `but journal has ${totalCount} yield entries`, options.unconsumed), { cause: options.cause });
         this.coroutineId = coroutineId;
         this.consumedCount = consumedCount;
         this.totalCount = totalCount;
+        this.unconsumed = options.unconsumed;
     }
 }
 /**
@@ -86,10 +148,11 @@ export class TerminalDivergenceError extends Error {
  */
 export class EarlyReturnDivergenceError extends TerminalDivergenceError {
     name = "EarlyReturnDivergenceError";
-    constructor(coroutineId, consumedCount, totalCount) {
+    constructor(coroutineId, consumedCount, totalCount, unconsumed) {
         super(coroutineId, consumedCount, totalCount, {
             message: `Divergence: generator ${coroutineId} returned after ${consumedCount} yields, ` +
                 `but journal has ${totalCount} yield entries`,
+            unconsumed,
         });
     }
 }

package/esm/live-coordinator.js

@@ -1,7 +1,7 @@
 import { serializeError } from "./serialize.js";
 /** The ordinary live path: execute once, publish once, then return the same result. */
 export const defaultLiveDurableOperationCoordinator = {
-    *run(execute, publish, _activateFailure, _journalProvenance) {
+    *run(execute, publish, _activateFailure, _journalProvenance, _abandoned) {
         let result;
         try {
             result = { status: "ok", value: yield* execute() };

package/esm/mod.js

@@ -21,7 +21,7 @@ export { establishJournalProvenance, preserveJournalProvenance } from "./guard.j
 // HTTP-backed stream adapter
 export { useHttpDurableStream } from "./http-stream.js";
 // Errors
-export { ContinuePastCloseDivergenceError, DivergenceError, DurablePersistenceError, EarlyReturnDivergenceError, MalformedDurableEventError, StaleInputError, TerminalDivergenceError, } from "./errors.js";
+export { ContinuePastCloseDivergenceError, describeEffect, DivergenceError, DurablePersistenceError, EarlyReturnDivergenceError, MalformedDurableEventError, SOURCE_POSITION_FIELD, StaleInputError, TerminalDivergenceError, } from "./errors.js";
 // Divergence API — pluggable policy for replay mismatches (DEC-031)
 export { Divergence } from "./divergence.js";
 // ReplayGuard API — pluggable validation for replay staleness detection
@@ -34,6 +34,7 @@ export { deserializeError, effectionToProtocol, protocolToEffection, serializeDu
 export { parseDurableEvent } from "./parse.js";
 // Core effect factories
 export { createDurableEffect, createDurableOperation } from "./effect.js";
+export { durablePosition } from "./position.js";
 // Structured live-operation coordination
 export { defaultLiveDurableOperationCoordinator } from "./live-coordinator.js";
 // Workflow-enabled effects

package/esm/position.js

@@ -0,0 +1,54 @@
+/**
+ * Where a coroutine is in its own durable history.
+ *
+ * A durable operation is identified by what it is and what it is called. Some
+ * operations have no name to give: a wait that a document reaches at one point
+ * in one procedure is that wait *because of where it is*, not because somebody
+ * named it. This is the coordinate such an operation names itself by — the
+ * coroutine it runs in, and how many durable yields that coroutine has already
+ * settled.
+ *
+ * ## Why it is not the replay cursor
+ *
+ * Replay already keeps a cursor per coroutine, and it looks like the same
+ * number. It is not. The cursor advances only while entries are being consumed
+ * from retained history; once a coroutine runs past the end of what was
+ * retained, the cursor stops while the coroutine keeps performing durable work.
+ * A position taken from it would be stable across replays of the retained
+ * prefix and would collide for every operation in the live suffix.
+ *
+ * So the position advances on both — a replayed yield and a committed live one
+ * — which is what makes the index a coroutine reaches at one point in its
+ * procedure the same index it reaches there next time.
+ *
+ * ## Observation, never authority
+ *
+ * A position describes where execution is. It authorizes nothing, proves
+ * nothing about who is executing, and is not durable state: it is derived by
+ * counting what the journal already holds. Anything that must be trusted is
+ * checked by whoever owns the authority to check it.
+ */
+import { DurableContext } from "./context.js";
+/**
+ * The position this coroutine has reached.
+ *
+ * Read before performing a durable operation, it is that operation's
+ * coordinate. Read after, it is the next one's.
+ */
+export function* durablePosition() {
+    const context = yield* DurableContext.expect();
+    return Object.freeze({
+        coroutineId: context.coroutineId,
+        index: context.position ?? 0,
+    });
+}
+/**
+ * Record that this coroutine settled one durable yield.
+ *
+ * Called from both settlement paths, which is the whole point of the field. A
+ * caller outside this package never advances a position: it is a count of what
+ * happened, and only the code that made it happen may say so.
+ */
+export function advanceDurablePosition(context) {
+    context.position = (context.position ?? 0) + 1;
+}

package/esm/replay-index.js

@@ -92,6 +92,25 @@ export class ReplayIndex {
         const cursor = this.cursors.get(coroutineId) ?? 0;
         this.cursors.set(coroutineId, cursor + 1);
     }
+    /**
+     * Whether this coroutine walked away from retained history it never consumed.
+     *
+     * True once replay has been disabled for it while entries it had not reached
+     * are still there — which is what a run-live decision leaves behind. It stays
+     * true for every later operation in that coroutine, because the history is
+     * still unconsumed however far past it execution has gone.
+     *
+     * An effect whose live work reaches a service this journal does not enclose
+     * reads it to decide whether running live here is something it may do at all.
+     * It is the index's own account, so nothing a document supplies takes part.
+     */
+    abandonedHistory(coroutineId) {
+        if (!this.disabled.has(coroutineId)) {
+            return false;
+        }
+        const list = this.yields.get(coroutineId);
+        return list !== undefined && (this.cursors.get(coroutineId) ?? 0) < list.length;
+    }
     /** Returns the current cursor position for this coroutine. */
     getCursor(coroutineId) {
         return this.cursors.get(coroutineId) ?? 0;
@@ -128,7 +147,14 @@ export class ReplayIndex {
         }
         return false;
     }
-    /** Return the first retained coroutine not aligned with the current subtree. */
+    /**
+     * Return the first retained coroutine not aligned with the current subtree.
+     *
+     * `entry` is the first unmatched retained protocol entry itself — the Yield
+     * at the cursor, or for an unclaimed completed child its first Yield when it
+     * has one and otherwise its Close — so a terminal diagnostic can name what
+     * the terminating subtree did not reach, not just where it stopped.
+     */
     firstUnaligned(subtreeId) {
         if (this.disabled.has(subtreeId)) {
             return undefined;
@@ -141,17 +167,23 @@ export class ReplayIndex {
             if (this.disabled.has(coroutineId)) {
                 continue;
             }
-            if (this.closes.has(coroutineId)) {
+            const close = this.closes.get(coroutineId);
+            if (close !== undefined) {
                 if (!this.claimed.has(coroutineId)) {
                     const entries = this.yields.get(coroutineId) ?? [];
-                    return { coroutineId, cursor: 0, totalYields: entries.length };
+                    return {
+                        coroutineId,
+                        cursor: 0,
+                        totalYields: entries.length,
+                        entry: entries[0] ?? close,
+                    };
                 }
                 continue;
             }
             const entries = this.yields.get(coroutineId) ?? [];
             const cursor = this.cursors.get(coroutineId) ?? 0;
             if (cursor < entries.length) {
-                return { coroutineId, cursor, totalYields: entries.length };
+                return { coroutineId, cursor, totalYields: entries.length, entry: entries[cursor] };
             }
         }
         return undefined;

package/esm/run.js

@@ -12,7 +12,7 @@
  *
  * See integration doc §10, protocol spec §4.
  */
-import { useScope } from "effection";
+import { scoped, useScope } from "effection";
 import { DurableContext } from "./context.js";
 import { activeDurabilityFailure, appendDurableEvent } from "./durability.js";
 import { EarlyReturnDivergenceError, TerminalDivergenceError } from "./errors.js";
@@ -138,14 +138,19 @@ export function* durableRun(workflow, options) {
         }
         const unconsumed = unalignedReplay(replayIndex, coroutineId);
         if (unconsumed) {
-            throw new EarlyReturnDivergenceError(unconsumed.coroutineId, unconsumed.cursor, unconsumed.totalYields);
+            throw new EarlyReturnDivergenceError(unconsumed.coroutineId, unconsumed.cursor, unconsumed.totalYields, unconsumed.entry);
         }
         const closeEvent = {
             type: "close",
             coroutineId,
             result: { status: "ok", value: result },
         };
-        yield* appendDurableEvent(ctx, closeEvent);
+        // The append's ordered turn is a resource of the scope it runs in, and
+        // this frame survives a rejected close: the catch below appends the
+        // compensating Close(err) from the same scope, so a turn still held here
+        // would make that append wait forever. A boundary around the attempt
+        // returns the turn as part of the outcome.
+        yield* scoped(() => appendDurableEvent(ctx, closeEvent));
         return result;
     }
     catch (error) {
@@ -156,7 +161,7 @@ export function* durableRun(workflow, options) {
         }
         const unconsumed = unalignedReplay(replayIndex, coroutineId);
         if (unconsumed) {
-            throw new TerminalDivergenceError(unconsumed.coroutineId, unconsumed.cursor, unconsumed.totalYields, { cause: primary });
+            throw new TerminalDivergenceError(unconsumed.coroutineId, unconsumed.cursor, unconsumed.totalYields, { cause: primary, unconsumed: unconsumed.entry });
         }
         const closeEvent = {
             type: "close",
@@ -167,7 +172,7 @@ export function* durableRun(workflow, options) {
             },
         };
         try {
-            yield* appendDurableEvent(ctx, closeEvent);
+            yield* scoped(() => appendDurableEvent(ctx, closeEvent));
         }
         catch (closeError) {
             const closeDurabilityFailure = activeDurabilityFailure(ctx, closeError);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/durable-streams",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "description": "Durable, replayable event streams for executable.md.",
   "homepage": "https://executable.md",
   "repository": {

package/types/context.d.ts

@@ -25,6 +25,13 @@ export interface DurableContext {
     coroutineId: CoroutineId;
     /** Counter for assigning child IDs. */
     childCounter: number;
+    /**
+     * How many durable yields this coroutine has settled.
+     *
+     * Advanced by both settlement paths, so a coroutine running past its retained
+     * history keeps counting where replay left off. See `position.ts`.
+     */
+    position?: number;
     /** Protocol failure shared by the root and every durable child. */
     durability?: DurabilityState;
 }

package/types/errors.d.ts

@@ -1,7 +1,28 @@
 /**
  * Error types for the durable execution protocol.
  */
-import type { CoroutineId, EffectDescription } from "./types.js";
+import type { Close, CoroutineId, EffectDescription, Yield } from "./types.js";
+/**
+ * The description field an authored source position occupies.
+ *
+ * A durable effect's identity is its `type` and `name` and nothing else, so a
+ * position travels beside them under this stable namespaced field. It is
+ * stored, filtered diagnostic data: never compared during divergence
+ * detection, never part of admission.
+ */
+export declare const SOURCE_POSITION_FIELD = "executablemd.source-position";
+/**
+ * Render one effect description for a divergence diagnostic.
+ *
+ * The identity renders as `type("name")`. When the description retains the
+ * exact normalized source shape under `SOURCE_POSITION_FIELD` — an optional
+ * non-empty `path`, an integer `offset` of at least 0, integer `line` and
+ * `column` of at least 1, and no other member — its human spelling,
+ * `path:line:column` or `line:column` without a path, never the offset, is
+ * appended as ` at …`. Anything else renders nothing at all: formatting a
+ * diagnostic must not introduce a new failure.
+ */
+export declare function describeEffect(description: EffectDescription): string;
 /**
  * Raised when a durable event cannot be persisted.
  *
@@ -58,9 +79,12 @@ export declare class TerminalDivergenceError extends Error {
     coroutineId: CoroutineId;
     consumedCount: number;
     totalCount: number;
+    /** The first retained entry the terminating subtree did not reach. */
+    unconsumed?: Yield | Close;
     constructor(coroutineId: CoroutineId, consumedCount: number, totalCount: number, options?: {
         cause?: unknown;
         message?: string;
+        unconsumed?: Yield | Close;
     });
 }
 /**
@@ -69,7 +93,7 @@ export declare class TerminalDivergenceError extends Error {
  */
 export declare class EarlyReturnDivergenceError extends TerminalDivergenceError {
     name: string;
-    constructor(coroutineId: CoroutineId, consumedCount: number, totalCount: number);
+    constructor(coroutineId: CoroutineId, consumedCount: number, totalCount: number, unconsumed?: Yield | Close);
 }
 /**
  * Raised when the journal has a Close event for a coroutine but the

package/types/live-coordinator.d.ts

@@ -1,11 +1,38 @@
 import type { Operation } from "effection";
 import type { JournalProvenance } from "./guard.js";
-import type { Json, Result } from "./types.js";
+import type { EffectDescription, Json, Result } from "./types.js";
 /** Activates the first infrastructure failure for the enclosing durable run. */
 export type ActivateDurabilityFailure = (failure: unknown) => Error;
+/**
+ * What replay left behind at this position, when it left anything.
+ *
+ * Present only when a retained entry was there and divergence policy chose to
+ * run live rather than refuse. It is the engine's own account of the position,
+ * so an effect whose live work reaches outside this journal can decide whether
+ * running live here is something it may do — without asking anything a document
+ * supplies.
+ */
+export interface AbandonedRetainedEntry {
+    readonly description: EffectDescription;
+    readonly result: Result;
+}
+/**
+ * What replay left behind in this coroutine, as the engine sees it.
+ *
+ * `entry` is the retained entry this very operation stepped over, when there
+ * was one. `steppedOver` is the wider fact and the load-bearing one: it stays
+ * true for every operation after the one that diverged, because disabling
+ * replay does not consume the history it walked away from. An effect that reads
+ * only `entry` would be safe at the position that diverged and unguarded at
+ * every position after it.
+ */
+export interface AbandonedRetainedHistory {
+    readonly entry?: AbandonedRetainedEntry;
+    readonly steppedOver: boolean;
+}
 /** Coordinates one live structured durable operation with its publication. */
 export interface LiveDurableOperationCoordinator {
-    run<T extends Json>(execute: () => Operation<T>, publish: (result: Result) => Operation<void>, activateFailure: ActivateDurabilityFailure, journalProvenance: JournalProvenance | undefined): Operation<Result>;
+    run<T extends Json>(execute: () => Operation<T>, publish: (result: Result) => Operation<void>, activateFailure: ActivateDurabilityFailure, journalProvenance: JournalProvenance | undefined, abandoned: AbandonedRetainedHistory): Operation<Result>;
 }
 /** The ordinary live path: execute once, publish once, then return the same result. */
 export declare const defaultLiveDurableOperationCoordinator: LiveDurableOperationCoordinator;

package/types/mod.d.ts

@@ -17,15 +17,18 @@ export { establishJournalProvenance, preserveJournalProvenance } from "./guard.j
 export type { DurableEventGate, JournalProvenance } from "./guard.js";
 export { useHttpDurableStream } from "./http-stream.js";
 export type { HttpDurableStreamHandle, HttpDurableStreamOptions } from "./http-stream.js";
-export { ContinuePastCloseDivergenceError, DivergenceError, DurablePersistenceError, EarlyReturnDivergenceError, MalformedDurableEventError, StaleInputError, TerminalDivergenceError, } from "./errors.js";
+export { ContinuePastCloseDivergenceError, describeEffect, DivergenceError, DurablePersistenceError, EarlyReturnDivergenceError, MalformedDurableEventError, SOURCE_POSITION_FIELD, StaleInputError, TerminalDivergenceError, } from "./errors.js";
 export { Divergence } from "./divergence.js";
 export type { DivergenceDecision, DivergenceInfo, DivergenceKind } from "./divergence.js";
 export { ReplayGuard } from "./replay-guard.js";
 export type { ReplayOutcome, RetainedHistory } from "./replay-guard.js";
+export type { AbandonedRetainedEntry, AbandonedRetainedHistory } from "./live-coordinator.js";
 export { DurableContext } from "./context.js";
 export { deserializeError, effectionToProtocol, protocolToEffection, serializeDurableEvent, serializeError, } from "./serialize.js";
 export { parseDurableEvent } from "./parse.js";
 export { createDurableEffect, createDurableOperation } from "./effect.js";
+export { durablePosition } from "./position.js";
+export type { DurablePosition } from "./position.js";
 export type { Executor } from "./effect.js";
 export { defaultLiveDurableOperationCoordinator } from "./live-coordinator.js";
 export type { ActivateDurabilityFailure, LiveDurableOperationCoordinator, } from "./live-coordinator.js";

package/types/position.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Where a coroutine is in its own durable history.
+ *
+ * A durable operation is identified by what it is and what it is called. Some
+ * operations have no name to give: a wait that a document reaches at one point
+ * in one procedure is that wait *because of where it is*, not because somebody
+ * named it. This is the coordinate such an operation names itself by — the
+ * coroutine it runs in, and how many durable yields that coroutine has already
+ * settled.
+ *
+ * ## Why it is not the replay cursor
+ *
+ * Replay already keeps a cursor per coroutine, and it looks like the same
+ * number. It is not. The cursor advances only while entries are being consumed
+ * from retained history; once a coroutine runs past the end of what was
+ * retained, the cursor stops while the coroutine keeps performing durable work.
+ * A position taken from it would be stable across replays of the retained
+ * prefix and would collide for every operation in the live suffix.
+ *
+ * So the position advances on both — a replayed yield and a committed live one
+ * — which is what makes the index a coroutine reaches at one point in its
+ * procedure the same index it reaches there next time.
+ *
+ * ## Observation, never authority
+ *
+ * A position describes where execution is. It authorizes nothing, proves
+ * nothing about who is executing, and is not durable state: it is derived by
+ * counting what the journal already holds. Anything that must be trusted is
+ * checked by whoever owns the authority to check it.
+ */
+import { type Operation } from "effection";
+import type { CoroutineId } from "./types.js";
+/**
+ * One coroutine's coordinate: which coroutine, and how far along it is.
+ *
+ * The pair rather than the index alone, because two coroutines each reach index
+ * 0, and the two are different places. A child's coordinate is its own — a
+ * child coroutine counts its own yields from zero — and the coroutine id is
+ * what keeps that from colliding with its parent's.
+ */
+export interface DurablePosition {
+    readonly coroutineId: CoroutineId;
+    readonly index: number;
+}
+/**
+ * The position this coroutine has reached.
+ *
+ * Read before performing a durable operation, it is that operation's
+ * coordinate. Read after, it is the next one's.
+ */
+export declare function durablePosition(): Operation<DurablePosition>;
+/**
+ * Record that this coroutine settled one durable yield.
+ *
+ * Called from both settlement paths, which is the whole point of the field. A
+ * caller outside this package never advances a position: it is a count of what
+ * happened, and only the code that made it happen may say so.
+ */
+export declare function advanceDurablePosition(context: {
+    position?: number;
+}): void;

package/types/replay-index.d.ts

@@ -54,6 +54,19 @@ export declare class ReplayIndex {
     peekYield(coroutineId: CoroutineId): YieldEntry | undefined;
     /** Advances the cursor for this coroutine by one position. */
     consumeYield(coroutineId: CoroutineId): void;
+    /**
+     * Whether this coroutine walked away from retained history it never consumed.
+     *
+     * True once replay has been disabled for it while entries it had not reached
+     * are still there — which is what a run-live decision leaves behind. It stays
+     * true for every later operation in that coroutine, because the history is
+     * still unconsumed however far past it execution has gone.
+     *
+     * An effect whose live work reaches a service this journal does not enclose
+     * reads it to decide whether running live here is something it may do at all.
+     * It is the index's own account, so nothing a document supplies takes part.
+     */
+    abandonedHistory(coroutineId: CoroutineId): boolean;
     /** Returns the current cursor position for this coroutine. */
     getCursor(coroutineId: CoroutineId): number;
     /** Returns true if a Close event exists for this coroutine (and replay is not disabled). */
@@ -67,11 +80,19 @@ export declare class ReplayIndex {
      * unconsumed entries belong to child coroutines rather than the root.
      */
     hasAnyUnconsumedYields(): boolean;
-    /** Return the first retained coroutine not aligned with the current subtree. */
+    /**
+     * Return the first retained coroutine not aligned with the current subtree.
+     *
+     * `entry` is the first unmatched retained protocol entry itself — the Yield
+     * at the cursor, or for an unclaimed completed child its first Yield when it
+     * has one and otherwise its Close — so a terminal diagnostic can name what
+     * the terminating subtree did not reach, not just where it stopped.
+     */
     firstUnaligned(subtreeId: CoroutineId): {
         coroutineId: CoroutineId;
         cursor: number;
         totalYields: number;
+        entry: Yield | Close;
     } | undefined;
     /**
      * Returns true if the cursor for this coroutine has been fully consumed