footprintjs 10.1.0 → 10.2.0

package/dist/esm/lib/errors/terminalFailure.d.ts

@@ -0,0 +1,29 @@
+import type { AttemptCategory } from '../attempt/types.js';
+/** Safe context for the failure that escaped a native run; never the exception itself. */
+export interface TerminalFailureContext {
+    readonly category: AttemptCategory;
+    /** Absent when no native stage owns this failure (for example input admission or run retention). */
+    readonly stage?: {
+        readonly runId: string;
+        readonly runtimeStageId: string;
+    };
+}
+/**
+ * @internal One execution chain's failure ownership, not an error history.
+ * Sequential frames share it; forks and subflows do not. Only an explicitly
+ * selected escaping rejection may transfer ownership to its parent chain.
+ * Raw identity lives in a private slot and is released when the leg settles.
+ */
+export declare class NativeFailureState {
+    #private;
+    get result(): TerminalFailureContext | undefined;
+    capture(error: unknown, category: AttemptCategory, stage: NonNullable<TerminalFailureContext['stage']>): void;
+    /** A runner already classified this exact native failure before it was served. */
+    owns(error: unknown): boolean;
+    adopt(child: NativeFailureState, error: unknown): void;
+    /** Publish at the run event boundary; keep ownership until executor settlement. */
+    announce(error: unknown): TerminalFailureContext;
+    finish(error: unknown): void;
+    /** Success or pause has no terminal failure. Also closes contained branch ownership. */
+    complete(): void;
+}

package/dist/esm/lib/errors/terminalFailure.js

@@ -0,0 +1,60 @@
+const UNKNOWN = Object.freeze({ category: 'unknown' });
+/**
+ * @internal One execution chain's failure ownership, not an error history.
+ * Sequential frames share it; forks and subflows do not. Only an explicitly
+ * selected escaping rejection may transfer ownership to its parent chain.
+ * Raw identity lives in a private slot and is released when the leg settles.
+ */
+export class NativeFailureState {
+    #pending;
+    #result;
+    #sealed = false;
+    get result() {
+        return this.#result;
+    }
+    capture(error, category, stage) {
+        if (this.#sealed)
+            return;
+        this.#pending = {
+            error,
+            context: Object.freeze({
+                category,
+                stage: Object.freeze({ runId: stage.runId, runtimeStageId: stage.runtimeStageId }),
+            }),
+        };
+    }
+    /** A runner already classified this exact native failure before it was served. */
+    owns(error) {
+        return this.#pending !== undefined && Object.is(this.#pending.error, error);
+    }
+    adopt(child, error) {
+        if (!this.#sealed)
+            this.#pending = child.owns(error) ? child.#pending : undefined;
+        child.complete();
+    }
+    /** Publish at the run event boundary; keep ownership until executor settlement. */
+    announce(error) {
+        if (this.#sealed)
+            return this.#result ?? UNKNOWN;
+        const pending = this.#pending;
+        const context = pending && Object.is(pending.error, error) ? pending.context : UNKNOWN;
+        this.#result = context;
+        return context;
+    }
+    finish(error) {
+        if (this.#sealed)
+            return;
+        this.announce(error);
+        this.#pending = undefined;
+        this.#sealed = true;
+    }
+    /** Success or pause has no terminal failure. Also closes contained branch ownership. */
+    complete() {
+        if (this.#sealed)
+            return;
+        this.#pending = undefined;
+        this.#result = undefined;
+        this.#sealed = true;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidGVybWluYWxGYWlsdXJlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vc3JjL2xpYi9lcnJvcnMvdGVybWluYWxGYWlsdXJlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQVlBLE1BQU0sT0FBTyxHQUEyQixNQUFNLENBQUMsTUFBTSxDQUFDLEVBQUUsUUFBUSxFQUFFLFNBQVMsRUFBRSxDQUFDLENBQUM7QUFFL0U7Ozs7O0dBS0c7QUFDSCxNQUFNLE9BQU8sa0JBQWtCO0lBQzdCLFFBQVEsQ0FBdUQ7SUFDL0QsT0FBTyxDQUEwQjtJQUNqQyxPQUFPLEdBQUcsS0FBSyxDQUFDO0lBRWhCLElBQUksTUFBTTtRQUNSLE9BQU8sSUFBSSxDQUFDLE9BQU8sQ0FBQztJQUN0QixDQUFDO0lBRUQsT0FBTyxDQUFDLEtBQWMsRUFBRSxRQUF5QixFQUFFLEtBQW1EO1FBQ3BHLElBQUksSUFBSSxDQUFDLE9BQU87WUFBRSxPQUFPO1FBQ3pCLElBQUksQ0FBQyxRQUFRLEdBQUc7WUFDZCxLQUFLO1lBQ0wsT0FBTyxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUM7Z0JBQ3JCLFFBQVE7Z0JBQ1IsS0FBSyxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUMsRUFBRSxLQUFLLEVBQUUsS0FBSyxDQUFDLEtBQUssRUFBRSxjQUFjLEVBQUUsS0FBSyxDQUFDLGNBQWMsRUFBRSxDQUFDO2FBQ25GLENBQUM7U0FDSCxDQUFDO0lBQ0osQ0FBQztJQUVELGtGQUFrRjtJQUNsRixJQUFJLENBQUMsS0FBYztRQUNqQixPQUFPLElBQUksQ0FBQyxRQUFRLEtBQUssU0FBUyxJQUFJLE1BQU0sQ0FBQyxFQUFFLENBQUMsSUFBSSxDQUFDLFFBQVEsQ0FBQyxLQUFLLEVBQUUsS0FBSyxDQUFDLENBQUM7SUFDOUUsQ0FBQztJQUVELEtBQUssQ0FBQyxLQUF5QixFQUFFLEtBQWM7UUFDN0MsSUFBSSxDQUFDLElBQUksQ0FBQyxPQUFPO1lBQUUsSUFBSSxDQUFDLFFBQVEsR0FBRyxLQUFLLENBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUM7UUFDbEYsS0FBSyxDQUFDLFFBQVEsRUFBRSxDQUFDO0lBQ25CLENBQUM7SUFFRCxtRkFBbUY7SUFDbkYsUUFBUSxDQUFDLEtBQWM7UUFDckIsSUFBSSxJQUFJLENBQUMsT0FBTztZQUFFLE9BQU8sSUFBSSxDQUFDLE9BQU8sSUFBSSxPQUFPLENBQUM7UUFDakQsTUFBTSxPQUFPLEdBQUcsSUFBSSxDQUFDLFFBQVEsQ0FBQztRQUM5QixNQUFNLE9BQU8sR0FBRyxPQUFPLElBQUksTUFBTSxDQUFDLEVBQUUsQ0FBQyxPQUFPLENBQUMsS0FBSyxFQUFFLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxPQUFPLENBQUMsT0FBTyxDQUFDLENBQUMsQ0FBQyxPQUFPLENBQUM7UUFDdkYsSUFBSSxDQUFDLE9BQU8sR0FBRyxPQUFPLENBQUM7UUFDdkIsT0FBTyxPQUFPLENBQUM7SUFDakIsQ0FBQztJQUVELE1BQU0sQ0FBQyxLQUFjO1FBQ25CLElBQUksSUFBSSxDQUFDLE9BQU87WUFBRSxPQUFPO1FBQ3pCLElBQUksQ0FBQyxRQUFRLENBQUMsS0FBSyxDQUFDLENBQUM7UUFDckIsSUFBSSxDQUFDLFFBQVEsR0FBRyxTQUFTLENBQUM7UUFDMUIsSUFBSSxDQUFDLE9BQU8sR0FBRyxJQUFJLENBQUM7SUFDdEIsQ0FBQztJQUVELHdGQUF3RjtJQUN4RixRQUFRO1FBQ04sSUFBSSxJQUFJLENBQUMsT0FBTztZQUFFLE9BQU87UUFDekIsSUFBSSxDQUFDLFFBQVEsR0FBRyxTQUFTLENBQUM7UUFDMUIsSUFBSSxDQUFDLE9BQU8sR0FBRyxTQUFTLENBQUM7UUFDekIsSUFBSSxDQUFDLE9BQU8sR0FBRyxJQUFJLENBQUM7SUFDdEIsQ0FBQztDQUNGIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHR5cGUgeyBBdHRlbXB0Q2F0ZWdvcnkgfSBmcm9tICcuLi9hdHRlbXB0L3R5cGVzLmpzJztcblxuLyoqIFNhZmUgY29udGV4dCBmb3IgdGhlIGZhaWx1cmUgdGhhdCBlc2NhcGVkIGEgbmF0aXZlIHJ1bjsgbmV2ZXIgdGhlIGV4Y2VwdGlvbiBpdHNlbGYuICovXG5leHBvcnQgaW50ZXJmYWNlIFRlcm1pbmFsRmFpbHVyZUNvbnRleHQge1xuICByZWFkb25seSBjYXRlZ29yeTogQXR0ZW1wdENhdGVnb3J5O1xuICAvKiogQWJzZW50IHdoZW4gbm8gbmF0aXZlIHN0YWdlIG93bnMgdGhpcyBmYWlsdXJlIChmb3IgZXhhbXBsZSBpbnB1dCBhZG1pc3Npb24gb3IgcnVuIHJldGVudGlvbikuICovXG4gIHJlYWRvbmx5IHN0YWdlPzoge1xuICAgIHJlYWRvbmx5IHJ1bklkOiBzdHJpbmc7XG4gICAgcmVhZG9ubHkgcnVudGltZVN0YWdlSWQ6IHN0cmluZztcbiAgfTtcbn1cblxuY29uc3QgVU5LTk9XTjogVGVybWluYWxGYWlsdXJlQ29udGV4dCA9IE9iamVjdC5mcmVlemUoeyBjYXRlZ29yeTogJ3Vua25vd24nIH0pO1xuXG4vKipcbiAqIEBpbnRlcm5hbCBPbmUgZXhlY3V0aW9uIGNoYWluJ3MgZmFpbHVyZSBvd25lcnNoaXAsIG5vdCBhbiBlcnJvciBoaXN0b3J5LlxuICogU2VxdWVudGlhbCBmcmFtZXMgc2hhcmUgaXQ7IGZvcmtzIGFuZCBzdWJmbG93cyBkbyBub3QuIE9ubHkgYW4gZXhwbGljaXRseVxuICogc2VsZWN0ZWQgZXNjYXBpbmcgcmVqZWN0aW9uIG1heSB0cmFuc2ZlciBvd25lcnNoaXAgdG8gaXRzIHBhcmVudCBjaGFpbi5cbiAqIFJhdyBpZGVudGl0eSBsaXZlcyBpbiBhIHByaXZhdGUgc2xvdCBhbmQgaXMgcmVsZWFzZWQgd2hlbiB0aGUgbGVnIHNldHRsZXMuXG4gKi9cbmV4cG9ydCBjbGFzcyBOYXRpdmVGYWlsdXJlU3RhdGUge1xuICAjcGVuZGluZz86IHsgZXJyb3I6IHVua25vd247IGNvbnRleHQ6IFRlcm1pbmFsRmFpbHVyZUNvbnRleHQgfTtcbiAgI3Jlc3VsdD86IFRlcm1pbmFsRmFpbHVyZUNvbnRleHQ7XG4gICNzZWFsZWQgPSBmYWxzZTtcblxuICBnZXQgcmVzdWx0KCk6IFRlcm1pbmFsRmFpbHVyZUNvbnRleHQgfCB1bmRlZmluZWQge1xuICAgIHJldHVybiB0aGlzLiNyZXN1bHQ7XG4gIH1cblxuICBjYXB0dXJlKGVycm9yOiB1bmtub3duLCBjYXRlZ29yeTogQXR0ZW1wdENhdGVnb3J5LCBzdGFnZTogTm9uTnVsbGFibGU8VGVybWluYWxGYWlsdXJlQ29udGV4dFsnc3RhZ2UnXT4pOiB2b2lkIHtcbiAgICBpZiAodGhpcy4jc2VhbGVkKSByZXR1cm47XG4gICAgdGhpcy4jcGVuZGluZyA9IHtcbiAgICAgIGVycm9yLFxuICAgICAgY29udGV4dDogT2JqZWN0LmZyZWV6ZSh7XG4gICAgICAgIGNhdGVnb3J5LFxuICAgICAgICBzdGFnZTogT2JqZWN0LmZyZWV6ZSh7IHJ1bklkOiBzdGFnZS5ydW5JZCwgcnVudGltZVN0YWdlSWQ6IHN0YWdlLnJ1bnRpbWVTdGFnZUlkIH0pLFxuICAgICAgfSksXG4gICAgfTtcbiAgfVxuXG4gIC8qKiBBIHJ1bm5lciBhbHJlYWR5IGNsYXNzaWZpZWQgdGhpcyBleGFjdCBuYXRpdmUgZmFpbHVyZSBiZWZvcmUgaXQgd2FzIHNlcnZlZC4gKi9cbiAgb3ducyhlcnJvcjogdW5rbm93bik6IGJvb2xlYW4ge1xuICAgIHJldHVybiB0aGlzLiNwZW5kaW5nICE9PSB1bmRlZmluZWQgJiYgT2JqZWN0LmlzKHRoaXMuI3BlbmRpbmcuZXJyb3IsIGVycm9yKTtcbiAgfVxuXG4gIGFkb3B0KGNoaWxkOiBOYXRpdmVGYWlsdXJlU3RhdGUsIGVycm9yOiB1bmtub3duKTogdm9pZCB7XG4gICAgaWYgKCF0aGlzLiNzZWFsZWQpIHRoaXMuI3BlbmRpbmcgPSBjaGlsZC5vd25zKGVycm9yKSA/IGNoaWxkLiNwZW5kaW5nIDogdW5kZWZpbmVkO1xuICAgIGNoaWxkLmNvbXBsZXRlKCk7XG4gIH1cblxuICAvKiogUHVibGlzaCBhdCB0aGUgcnVuIGV2ZW50IGJvdW5kYXJ5OyBrZWVwIG93bmVyc2hpcCB1bnRpbCBleGVjdXRvciBzZXR0bGVtZW50LiAqL1xuICBhbm5vdW5jZShlcnJvcjogdW5rbm93bik6IFRlcm1pbmFsRmFpbHVyZUNvbnRleHQge1xuICAgIGlmICh0aGlzLiNzZWFsZWQpIHJldHVybiB0aGlzLiNyZXN1bHQgPz8gVU5LTk9XTjtcbiAgICBjb25zdCBwZW5kaW5nID0gdGhpcy4jcGVuZGluZztcbiAgICBjb25zdCBjb250ZXh0ID0gcGVuZGluZyAmJiBPYmplY3QuaXMocGVuZGluZy5lcnJvciwgZXJyb3IpID8gcGVuZGluZy5jb250ZXh0IDogVU5LTk9XTjtcbiAgICB0aGlzLiNyZXN1bHQgPSBjb250ZXh0O1xuICAgIHJldHVybiBjb250ZXh0O1xuICB9XG5cbiAgZmluaXNoKGVycm9yOiB1bmtub3duKTogdm9pZCB7XG4gICAgaWYgKHRoaXMuI3NlYWxlZCkgcmV0dXJuO1xuICAgIHRoaXMuYW5ub3VuY2UoZXJyb3IpO1xuICAgIHRoaXMuI3BlbmRpbmcgPSB1bmRlZmluZWQ7XG4gICAgdGhpcy4jc2VhbGVkID0gdHJ1ZTtcbiAgfVxuXG4gIC8qKiBTdWNjZXNzIG9yIHBhdXNlIGhhcyBubyB0ZXJtaW5hbCBmYWlsdXJlLiBBbHNvIGNsb3NlcyBjb250YWluZWQgYnJhbmNoIG93bmVyc2hpcC4gKi9cbiAgY29tcGxldGUoKTogdm9pZCB7XG4gICAgaWYgKHRoaXMuI3NlYWxlZCkgcmV0dXJuO1xuICAgIHRoaXMuI3BlbmRpbmcgPSB1bmRlZmluZWQ7XG4gICAgdGhpcy4jcmVzdWx0ID0gdW5kZWZpbmVkO1xuICAgIHRoaXMuI3NlYWxlZCA9IHRydWU7XG4gIH1cbn1cbiJdfQ==

package/dist/esm/lib/memory/StageContext.d.ts

@@ -15,6 +15,7 @@ import type { CommitPhase, EmitSourcePosition, UntrackedSource } from 'foottrace
 import type { EventLog, SharedMemory } from 'foottrace/write';
 import type { AttemptContext, AttemptRecord, AttemptSummary, LateWrite } from '../attempt/types.js';
 import type { StructuredErrorInfo } from '../errors/errorInfo.js';
+import { type TerminalFailureContext, NativeFailureState } from '../errors/terminalFailure.js';
 import { type DiagnosticChannel, DiagnosticCollector } from './DiagnosticCollector.js';
 import type { FlowControlType, StageSnapshot } from './frameTypes.js';
 import type { RedactionVerdict } from './redaction.js';
@@ -27,6 +28,13 @@ import type { RunPolicy } from './runPolicy.js';
  */
 export declare const MAX_CALL_RECORDS = 1000;
 export declare class StageContext {
+    #private;
+    /** @internal Ownership of an escaping failure. Shared only by sequential frames, never serialized. */
+    failureState: NativeFailureState;
+    /** @internal The native frame stamp, independent of mutable recorder event context. */
+    get failureIdentity(): NonNullable<TerminalFailureContext['stage']> | undefined;
+    /** @internal Stamped before observers; never inherited by another frame or persisted. */
+    bindFailureIdentity(runId: string, runtimeStageId: string): void;
     /**
      * The record half of this frame (`RecordFrame.ts`, L3, C3): the heap and,
      * when the run keeps them, the redacted mirror and the log; the address;
@@ -156,6 +164,8 @@ export declare class StageContext {
     private _attempts?;
     /** The attempt series at a glance, stamped once when it ends. */
     private _attemptSummary?;
+    /** Facts collected for this execution only; retry discards deliberately keep them. */
+    private _attention?;
     /**
      * The attempt now running (P1b) — set by `StageRunner` before the scope is built, so the facade can hand it out
      * (`scope.$attempt()`) and fence its own attempt. Absent for a stage the attempt runner does not run.
@@ -485,6 +495,10 @@ export declare class StageContext {
     recordAttempt(record: AttemptRecord): void;
     /** Stamp the series' summary — once, when the runner ends the series. */
     endAttempts(summary: AttemptSummary): void;
+    /** Reset only at the node's execution stamp, never between attempts. */
+    beginAttention(): void;
+    /** Delegate the explicit retained-error fact; attention owns validation of its proof. */
+    markStageFailure(): void;
     /**
      * The crash-safe record (10.1, P6): an attempt that ended is noted in the run's sink AT ONCE, beside this frame's
      * log — so a process killed before the stage commits (mid-retry) still leaves every attempt that ended. The