@reticlehq/server 3.8.2 → 3.10.0

package/dist/language/flows/recording/tape/recordings.js

@@ -28,6 +28,16 @@ export const AMBIENT_RECORDING = '__ambient__';
 export const ambientRecordingOf = (session) => session === undefined ? AMBIENT_RECORDING : `${AMBIENT_RECORDING}:${session}`;
 /** Whether a recording is an ambient tape: the daemon's own, never one somebody opened. */
 export const isAmbient = (name) => AMBIENT_RECORDING === name || name.startsWith(`${AMBIENT_RECORDING}:`);
+/**
+ * Whether a step, or one of its sub-steps, declared a consequence.
+ * ponytail: the same test as `carriesAnAssertion` in memory/journal/drive-flow.ts, which this
+ * directory may not import. Move both into core if a third caller needs it.
+ */
+const isChecked = (step) => {
+    const subs = Array.isArray(step.args['steps']) ? step.args['steps'] : [];
+    return (step.expect !== undefined ||
+        subs.some((sub) => 'object' === typeof sub && null !== sub && 'expect' in sub));
+};
 /**
  * How long a journey the ambient tape will hold.
  *
@@ -36,24 +46,49 @@ export const isAmbient = (name) => AMBIENT_RECORDING === name || name.startsWith
  * 400-step regression test: the longest saved flow in the corpus is a small fraction of this.
  */
 const AMBIENT_STEP_CAP = 400;
+/** How many ended pages keep their unchecked steps for a successor. See takeAmbient. */
+const CARRY_CAP = 32;
 export class RecordingStore {
     byHarness;
+    successorOf;
     #active = new Map();
     #compiled = new Map();
-    /** The ambient tape the last step went on: the one a refuted claim is taken off. */
-    #lastAmbient;
     /** A navigation came after the last captured step — see markNavigated. */
     #navigatedSinceStep = false;
     /** Tabs with network mocks installed now, keyed by session ('' for none named). See markMocked. */
     #mocked = new Set();
-    /** `byHarness`: whether the step being captured was driven by the Harness, which tapes its own. */
-    constructor(byHarness = () => false) {
+    /**
+     * Steps a tab took after its last check, kept when the APP loaded a new page, by the session that
+     * ended. The page that loaded takes them when its own tape opens. See takeAmbient.
+     */
+    #carried = new Map();
+    /**
+     * `byHarness`: whether the step being captured was driven by the Harness, which tapes its own.
+     * `successorOf`: the session that the same tab connected as after a page load, if any.
+     */
+    constructor(byHarness = () => false, successorOf = () => undefined) {
         this.byHarness = byHarness;
+        this.successorOf = successorOf;
+    }
+    /** The carried steps that this session continues, taken. */
+    #takeCarried(session) {
+        if (session === undefined) {
+            return [];
+        }
+        for (const [ended, steps] of this.#carried) {
+            // A leased tab comes back from a page load with its own id; any other tab with a new one.
+            if (ended === session || this.successorOf(ended) === session) {
+                this.#carried.delete(ended);
+                return steps;
+            }
+        }
+        return [];
     }
     start(name, cursor, startPath, session, document) {
         const openedOver = new Map();
-        for (const [outer, rec] of this.#targets(session))
+        for (const [outer, rec] of this.#targets(session)) {
             openedOver.set(outer, rec.steps.length);
+        }
         this.#active.set(name, {
             cursor,
             steps: [],
@@ -96,15 +131,17 @@ export class RecordingStore {
      * they are, so the journey it belongs to is not auto-saved as a flow (#1459).
      */
     markMocked(session, active) {
-        if (active)
+        if (active) {
             this.#mocked.add(session ?? '');
-        else
+        }
+        else {
             this.#mocked.delete(session ?? '');
+        }
     }
     /**
      * `forAmbient` is the step as the ambient tape keeps it, when that differs: a journey's refuted
-     * claims come off the ambient tape (see `unassertLast`), and a recording somebody opened keeps
-     * every claim they declared, held or not.
+     * claims stay off the ambient tape, and a recording somebody opened keeps every claim they
+     * declared, held or not. See captureVerdictedAct.
      */
     capture(step, route, session, forAmbient) {
         this.#navigatedSinceStep = false;
@@ -113,28 +150,30 @@ export class RecordingStore {
         if (!this.#active.has(ambient)) {
             this.#active.set(ambient, {
                 cursor: 0,
-                steps: [],
+                steps: this.#takeCarried(session),
                 openedOver: new Map(),
                 ...(session === undefined ? {} : { session }),
             });
         }
-        this.#lastAmbient = ambient;
         for (const [name, rec] of this.#targets(session)) {
             // Another tab's tape is that tab's journey, whatever else this step belongs to.
-            if (isAmbient(name) && name !== ambient)
+            if (isAmbient(name) && name !== ambient) {
                 continue;
+            }
             // The ambient tape is opened by the system and closed by nobody, so it is the one recording
             // with no human deciding when it has seen enough. Bounded here rather than left to grow for
             // the length of a daemon's life. Appending STOPS at the cap instead of dropping the oldest: a
             // flow replays from its FIRST step, so a tape missing its beginning is not a shorter journey,
             // it is a different one that starts in a state nothing established. A recording somebody
             // opened on purpose is not capped — they said when it starts and they say when it stops.
-            if (isAmbient(name) && rec.steps.length >= AMBIENT_STEP_CAP)
+            if (isAmbient(name) && rec.steps.length >= AMBIENT_STEP_CAP) {
                 continue;
+            }
             // The Harness saves its own recordings. Taping its steps too saved every drive twice: once as
             // the Harness's flow and again, at session end, as a `drive-*` copy with a guessed name.
-            if (isAmbient(name) && this.byHarness())
+            if (isAmbient(name) && this.byHarness()) {
                 continue;
+            }
             // A step nobody marked ended where the next one began.
             const previous = rec.steps.at(-1);
             if (previous !== undefined && previous.endPage === undefined && step.page !== undefined) {
@@ -161,26 +200,33 @@ export class RecordingStore {
      * the proof. What the step already declared is kept; the new check joins it under `allOf`.
      */
     attachExpect(expect, session) {
-        if (this.#navigatedSinceStep)
+        if (this.#navigatedSinceStep) {
             return;
+        }
         const mocked = this.#mocked.has(session ?? '');
         for (const [name, rec] of this.#targets(session)) {
-            if (isAmbient(name) && name !== ambientRecordingOf(session))
+            if (isAmbient(name) && name !== ambientRecordingOf(session)) {
                 continue;
+            }
             const last = rec.steps.at(-1);
-            if (last === undefined)
+            if (last === undefined) {
                 continue;
+            }
             // A proof read while mocks are active rests on mocked responses even when the act before it
             // ran unmocked, so the ambient step it joins is marked too (#1459).
-            if (mocked && isAmbient(name))
+            if (mocked && isAmbient(name)) {
                 last.mocked = true;
+            }
             const held = last.expect;
-            last.expect =
-                held === undefined
-                    ? expect
-                    : PredicateKind.ALL_OF === held.kind
-                        ? { ...held, predicates: [...held.predicates, expect] }
-                        : { kind: PredicateKind.ALL_OF, predicates: [held, expect] };
+            if (held === undefined) {
+                last.expect = expect;
+            }
+            else if (PredicateKind.ALL_OF === held.kind) {
+                last.expect = { ...held, predicates: [...held.predicates, expect] };
+            }
+            else {
+                last.expect = { kind: PredicateKind.ALL_OF, predicates: [held, expect] };
+            }
         }
     }
     /**
@@ -191,24 +237,6 @@ export class RecordingStore {
     markNavigated() {
         this.#navigatedSinceStep = true;
     }
-    /**
-     * Take the expectation off the ambient tape's last step, because the verdict on it came back no.
-     *
-     * A step is captured at dispatch, before anything is judged, so a claim that turned out false is
-     * already on the tape as that step's `expect`. Cut into a journey it becomes a flow that is red for
-     * ever, on an expectation nobody but the agent's wrong guess made. The failure is not lost: it is
-     * filed as a capsule, the artifact built for "this should hold and does not". The ACTION stays,
-     * since the steps after it ran on the page it produced. A recording somebody opened deliberately
-     * is left as they drove it.
-     */
-    unassertLast() {
-        const tape = this.#lastAmbient === undefined ? undefined : this.#active.get(this.#lastAmbient);
-        const last = tape?.steps.at(-1);
-        if (tape === undefined || last === undefined || last.expect === undefined)
-            return;
-        const { expect: _dropped, ...kept } = last;
-        tape.steps[tape.steps.length - 1] = kept;
-    }
     /**
      * The page the step just captured ended on, once its action settled.
      *
@@ -216,14 +244,17 @@ export class RecordingStore {
      * previous step's own answer alone.
      */
     markEnded(page, session) {
-        if (page === undefined)
+        if (page === undefined) {
             return;
+        }
         for (const [name, rec] of this.#targets(session)) {
-            if (isAmbient(name) && name !== ambientRecordingOf(session))
+            if (isAmbient(name) && name !== ambientRecordingOf(session)) {
                 continue;
+            }
             const last = rec.steps.at(-1);
-            if (last !== undefined && last.endPage === undefined)
+            if (last !== undefined && last.endPage === undefined) {
                 last.endPage = page;
+            }
         }
     }
     /**
@@ -241,14 +272,16 @@ export class RecordingStore {
     stop(name) {
         const rec = this.#active.get(name);
         this.#active.delete(name);
-        if (rec === undefined)
+        if (rec === undefined) {
             return undefined;
+        }
         for (const [outer, mark] of rec.openedOver) {
             const parent = this.#active.get(outer);
             // Gone already, or somehow shorter than when we started: leave it exactly as it is rather
             // than splice a range that no longer means what it meant.
-            if (parent === undefined || parent.steps.length < mark)
+            if (parent === undefined || parent.steps.length < mark) {
                 continue;
+            }
             parent.steps.splice(mark, parent.steps.length - mark, {
                 tool: INVOKE_TOOL,
                 args: { flow: name },
@@ -268,9 +301,39 @@ export class RecordingStore {
         // One tab's tape is that tab's: the list names what somebody opened, and the plain tape as before.
         return [...this.#active.keys()].filter((name) => !name.startsWith(`${AMBIENT_RECORDING}:`));
     }
-    /** The ambient tape of one tab (or of steps no tab named), taken: what its session end saves. */
+    /**
+     * The ambient tape of one tab (or of steps no tab named), taken: what its session end saves.
+     *
+     * A session also ends when the app itself loads a page (a form post on a server-rendered app), and
+     * the journey goes on in the page that loaded. A tape with no check is not saved, so the next
+     * page's tape starts with a copy of it: a fill and the submit that proves it are then one flow, not
+     * a fill that is dropped and a submit on an empty form. When Reticle navigated away, the agent
+     * started a new journey, and nothing is carried.
+     * ponytail: only a tape with NO check is carried; unchecked steps after a check stay behind.
+     * ponytail: kept for the last CARRY_CAP ended pages; a tab that never loads a successor drops them.
+     */
     takeAmbient(session) {
-        return this.stop(ambientRecordingOf(session));
+        const tape = this.stop(ambientRecordingOf(session));
+        const unchecked = tape !== undefined && !tape.steps.some(isChecked);
+        if (tape === undefined || session === undefined || this.#navigatedSinceStep || !unchecked) {
+            return tape;
+        }
+        // The next page may already have a tape: its step was recorded before this session ended.
+        const next = this.successorOf(session);
+        const nextTape = next === undefined ? undefined : this.#active.get(ambientRecordingOf(next));
+        if (nextTape !== undefined) {
+            nextTape.steps.unshift(...tape.steps);
+            return tape;
+        }
+        this.#carried.set(session, [...tape.steps]);
+        while (this.#carried.size > CARRY_CAP) {
+            const oldest = this.#carried.keys().next().value;
+            if (oldest === undefined) {
+                break;
+            }
+            this.#carried.delete(oldest);
+        }
+        return tape;
     }
     /**
      * Names of recordings that have been STOPPED and compiled.

package/dist/language/flows/replay.d.ts

@@ -1,4 +1,4 @@
-import { pathOf, type Predicate, type ReticleEvent } from '@reticlehq/core';
+import { type Predicate, type ReticleEvent } from '@reticlehq/core';
 import { type CommandResult } from '@reticlehq/core';
 import type { RecordedStep, CompiledProgram } from './recording/tape/recordings.js';
 import type { Session } from '../../portal/session/session.js';
@@ -13,6 +13,15 @@ export declare function ambiguousTestidNote(value: string): string;
  * replay engines (replayProgram + flow-replay's step runner) so element extraction — the core of anchor
  * resolution — can't drift between them.
  */
+/**
+ * The refs of a role query's matches that have NO accessible name, in page order.
+ *
+ * A role query without a name returns every control of the role, named ones included. A nameless
+ * anchor's recorded position (`nth` of `of`) counts only the nameless ones — an icon-only edit
+ * button is the 2nd nameless button of its row, not the 5th button — so the named ones are dropped
+ * before the position is read.
+ */
+export declare function namelessRefs(result: CommandResult): string[];
 export declare function queryRefs(result: CommandResult): string[];
 /**
  * A destructive-action confirmation is one-shot and must never persist into a recording.
@@ -29,12 +38,16 @@ export declare function queryRefs(result: CommandResult): string[];
  */
 export declare function replayActionArgs(value: unknown, confirmDangerous?: boolean, field?: string): Record<string, unknown>;
 /**
- * The pathname of a session's live url, or undefined when it has none yet.
+ * The page a session's live url is on, as a NAVIGABLE path: pathname + query + hash, with
+ * Reticle's own params dropped. Undefined when the session has no url yet.
  *
- * Pathname rather than the whole url, because that is what `startPath` is compared against and what
- * a hash-routed app makes meaningless in the document location — see routeOfEvent.
+ * Every recorded page comes from here: a step's page, the route a tape is cut on, and the
+ * `startPath` and route `requires` of a saved flow. The pathname alone dropped the query, so a
+ * journey leased on `/?showModal=login` saved `startPath: "/"`, and its replay asserted "the modal
+ * is absent" on a page where the modal never opens. Under a hash router it dropped the hash too,
+ * which made every page `/` (#1411).
  */
-export { pathOf };
+export declare function pageOf(url: string | undefined): string | undefined;
 /**
  * Did the app send a write request in this window? A step that did is saved `writes: true`, so a
  * replay does not repeat it unasked. The dev server's own traffic is not the app's.
@@ -55,21 +68,31 @@ export declare const UNKEPT_EXPECT: string;
  */
 export declare function captureAct(recordings: {
     active: () => string[];
-    capture: (step: RecordedStep, route?: string, session?: string) => void;
+    capture: (step: RecordedStep, route?: string, session?: string, forAmbient?: RecordedStep) => void;
 }, args: Record<string, unknown>, res: unknown, 
 /** Where this step ran, so the ambient tape can be cut into journeys. See RecordedStep.route. */
 route?: string, 
 /** The session that acted: only recordings it started take the step. */
 session?: string, 
 /** The act's window sent a write request; see `wroteIn`. */
-wrote?: boolean): void;
+wrote?: boolean, 
+/** The act as the ambient tape keeps it, when that differs. See RecordingStore.capture. */
+ambientArgs?: Record<string, unknown>): void;
 /**
- * Capture an act_and_wait once its verdict is known, keeping `until` as the step's expectation only
- * on a yes. Recorded before the verdict, a step kept an `until` that came back `no` or `no-fault` —
- * a regression test asserting something never once observed to hold because of the action. The
- * action itself is always recorded: it happened, and replay needs it to reach the next step.
+ * Capture an act_and_wait once its verdict is known.
+ *
+ * The rule act_sequence keeps (#988). A recording somebody opened keeps every claim the agent
+ * declared, held or not: dropping a refuted one saved a flow that replayed green on the defect it
+ * had caught. The ambient tape keeps a claim only if the action made it hold (`held`), so a flow cut
+ * from it never replays a claim that was never once true because of the action. The action is
+ * always recorded: replay needs it to reach the next step.
+ *
+ * Keyed on `held`, not on `verified: yes`. A claim the action made hold under an `unknown` or a
+ * contradicted verdict is still what the agent proved about the page, and dropping it left the
+ * replay with no check at all. One function decides both tapes: a second rule that took the claim off the tape
+ * after the fact ran before this capture, so it took the PREVIOUS step's claim, which had passed.
  */
-export declare function captureVerdictedAct(recordings: Parameters<typeof captureAct>[0], args: Record<string, unknown>, res: unknown, route: string | undefined, verified: string | undefined, session?: string, 
+export declare function captureVerdictedAct(recordings: Parameters<typeof captureAct>[0], args: Record<string, unknown>, res: unknown, route: string | undefined, held: boolean, session?: string, 
 /** The act's window sent a write request; see `wroteIn`. */
 wrote?: boolean): void;
 /** Fold a PASSING standalone assertion into the step it proved. See RecordingStore.attachExpect. */
@@ -124,3 +147,4 @@ via?: readonly {
     flow: string;
     step: number;
 }[]): Promise<ReplayStepResult[]>;
+export {};