@reticlehq/server 2.0.0

package/dist/events/ring-buffer.d.ts

@@ -0,0 +1,32 @@
+import { type ReticleEvent } from '@reticlehq/core';
+interface RingBufferOptions {
+    maxEvents?: number;
+    maxAgeMs?: number;
+    maxBytes?: number;
+}
+/**
+ * Bounded, time-aware event store per session. The single data structure that powers
+ * observe()/wait_for()/assert() — it lets us look both backward (recent buffer) and
+ * forward (await new events). See plan/02-architecture.md.
+ *
+ * `now` is injected so the buffer is deterministically testable (engineering standard:
+ * inject the clock, never call Date.now() inside logic).
+ */
+export declare class RingBuffer {
+    #private;
+    constructor(options?: RingBufferOptions);
+    push(event: ReticleEvent, now: number): void;
+    /** Events at or after a given timestamp cursor. */
+    since(cursor: number): ReticleEvent[];
+    /** Events within the last `windowMs`, relative to `now`. */
+    window(windowMs: number, now: number): ReticleEvent[];
+    /** Snapshot of buffer health for the agent — total events held and cumulative drops since connect. */
+    bufferHealth(): {
+        total: number;
+        dropped: number;
+    };
+    /** Reset the drop counter and return the count that was cleared (for per-observe accounting). */
+    resetDropped(): number;
+}
+export {};
+//# sourceMappingURL=ring-buffer.d.ts.map

package/dist/events/ring-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["../../src/events/ring-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE1E,UAAU,iBAAiB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;;gBAST,OAAO,GAAE,iBAAsB;IAM3C,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAQ5C,mDAAmD;IACnD,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE;IAIrC,4DAA4D;IAC5D,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE;IAgCrD,sGAAsG;IACtG,YAAY,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAIlD,iGAAiG;IACjG,YAAY,IAAI,MAAM;CAKvB"}

package/dist/events/ring-buffer.js

@@ -0,0 +1,75 @@
+import { RING_BUFFER_DEFAULTS } from '@reticlehq/core';
+/**
+ * Bounded, time-aware event store per session. The single data structure that powers
+ * observe()/wait_for()/assert() — it lets us look both backward (recent buffer) and
+ * forward (await new events). See plan/02-architecture.md.
+ *
+ * `now` is injected so the buffer is deterministically testable (engineering standard:
+ * inject the clock, never call Date.now() inside logic).
+ */
+export class RingBuffer {
+    #maxEvents;
+    #maxAgeMs;
+    #maxBytes;
+    #events = [];
+    #eventBytes = [];
+    #totalBytes = 0;
+    #droppedCount = 0;
+    constructor(options = {}) {
+        this.#maxEvents = options.maxEvents ?? RING_BUFFER_DEFAULTS.MAX_EVENTS;
+        this.#maxAgeMs = options.maxAgeMs ?? RING_BUFFER_DEFAULTS.MAX_AGE_MS;
+        this.#maxBytes = options.maxBytes ?? RING_BUFFER_DEFAULTS.MAX_BYTES;
+    }
+    push(event, now) {
+        this.#events.push(event);
+        const bytes = Buffer.byteLength(JSON.stringify(event), 'utf8');
+        this.#eventBytes.push(bytes);
+        this.#totalBytes += bytes;
+        this.#evict(now);
+    }
+    /** Events at or after a given timestamp cursor. */
+    since(cursor) {
+        return this.#events.slice(this.#lowerBound(cursor));
+    }
+    /** Events within the last `windowMs`, relative to `now`. */
+    window(windowMs, now) {
+        return this.#events.slice(this.#lowerBound(now - windowMs));
+    }
+    #lowerBound(target) {
+        let lo = 0;
+        let hi = this.#events.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if ((this.#events[mid]?.t ?? 0) < target)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return lo;
+    }
+    #evict(now) {
+        const before = this.#events.length;
+        const cutoff = now - this.#maxAgeMs;
+        while (this.#events.length > this.#maxEvents ||
+            (this.#totalBytes > this.#maxBytes && this.#events.length > 0)) {
+            this.#events.shift();
+            this.#totalBytes -= this.#eventBytes.shift() ?? 0;
+        }
+        while ((this.#events[0]?.t ?? cutoff) < cutoff) {
+            this.#events.shift();
+            this.#totalBytes -= this.#eventBytes.shift() ?? 0;
+        }
+        this.#droppedCount += before - this.#events.length;
+    }
+    /** Snapshot of buffer health for the agent — total events held and cumulative drops since connect. */
+    bufferHealth() {
+        return { total: this.#events.length, dropped: this.#droppedCount };
+    }
+    /** Reset the drop counter and return the count that was cleared (for per-observe accounting). */
+    resetDropped() {
+        const n = this.#droppedCount;
+        this.#droppedCount = 0;
+        return n;
+    }
+}
+//# sourceMappingURL=ring-buffer.js.map

package/dist/events/ring-buffer.js.map

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

package/dist/flows/annotate-tools.d.ts

@@ -0,0 +1,16 @@
+import type { ToolDef } from '../tools/tools.js';
+/**
+ * The reticle_annotate tool. A STRUCTURED annotation (the AnnotationSchema
+ * discriminated union) is compiled into the live recording's per-step expect / flow dynamic[] /
+ * flow success, which reticle_flow_save then folds onto disk. Returns the AnnotateResult envelope
+ * with the compiled-predicate confirmation text ("will assert signal diff:shown").
+ *
+ * FIRST CUT: structured annotations only. A free NATURAL-LANGUAGE annotation never compiles — it
+ * fails AnnotationSchema and is returned as UNKNOWN_KIND. NL → predicate compilation is explicitly
+ * FUTURE; no NL parser exists or is faked here.
+ *
+ * No-active-recording and no-step are SAFE, returned as structured codes (never thrown), so an
+ * agent that annotates at the wrong moment gets a clear error rather than a crash.
+ */
+export declare const ANNOTATE_TOOLS: ToolDef[];
+//# sourceMappingURL=annotate-tools.d.ts.map

package/dist/flows/annotate-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotate-tools.d.ts","sourceRoot":"","sources":["../../src/flows/annotate-tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AAI3D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,EAoInC,CAAC"}

package/dist/flows/annotate-tools.js

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import { AnnotationErrorCode, AnnotationSchema } from '@reticlehq/core';
+import { ReticleTool } from '../tools/tool-names.js';
+import { asString } from '../tools/tools-helpers.js';
+import { compileAnnotation } from './annotate.js';
+const DEFAULT_RECORDING = 'default';
+/**
+ * The reticle_annotate tool. A STRUCTURED annotation (the AnnotationSchema
+ * discriminated union) is compiled into the live recording's per-step expect / flow dynamic[] /
+ * flow success, which reticle_flow_save then folds onto disk. Returns the AnnotateResult envelope
+ * with the compiled-predicate confirmation text ("will assert signal diff:shown").
+ *
+ * FIRST CUT: structured annotations only. A free NATURAL-LANGUAGE annotation never compiles — it
+ * fails AnnotationSchema and is returned as UNKNOWN_KIND. NL → predicate compilation is explicitly
+ * FUTURE; no NL parser exists or is faked here.
+ *
+ * No-active-recording and no-step are SAFE, returned as structured codes (never thrown), so an
+ * agent that annotates at the wrong moment gets a clear error rather than a crash.
+ */
+export const ANNOTATE_TOOLS = [
+    {
+        name: ReticleTool.ANNOTATE,
+        description: 'Attach a STRUCTURED annotation to the active recording, compiling it into the flow. kind: ' +
+            'assert-signal { name, dataMatches? } → the last step asserts that signal; assert-visible ' +
+            '{ testid } → the last step asserts that element is present; assert-state ' +
+            '{ statePath, store?, equals? } → the last step asserts a registered store value (the source ' +
+            'of truth no DOM read can reach); mark-dynamic { testid } → the ' +
+            "flow records that region as LLM-dynamic (replay won't assert its content); success-state " +
+            '{ signal | statePath(+store,+equals) | net(+count) | console(+absent) | testid } → the flow golden ' +
+            'end-condition (statePath asserts a registered store value — the source of truth no DOM read can ' +
+            'reach; net asserts a request fired EXACTLY `count` times — catches double-submit; console+absent ' +
+            'asserts a clean console — catches an action that logs an error). Folded onto disk by reticle_flow_save. ' +
+            'Returns { ok:true, target:step|flow, compiled } (e.g. "will assert signal diff:shown") or ' +
+            '{ ok:false, code } (annotate_no_recording | annotate_no_step | annotate_unknown_kind | ' +
+            'annotate_missing_field). FIRST CUT: structured only — a free natural-language string is ' +
+            'rejected (annotate_unknown_kind), never guessed into a predicate. Pass `flow` to target a ' +
+            "named recording (defaults to 'default'); `name` is the assert-signal's SIGNAL name, not the recording.",
+        inputSchema: {
+            // `flow` selects the recording; `name`/`signal`/`testid`/`dataMatches` are the annotation fields.
+            flow: z.string().optional().describe("Named recording to annotate. Defaults to 'default'."),
+            kind: z
+                .string()
+                .describe('Annotation kind: assert-signal | assert-visible | assert-state | mark-dynamic | success-state | intent.'),
+            name: z.string().optional().describe('Signal name for assert-signal annotations.'),
+            text: z
+                .string()
+                .optional()
+                .describe("Business goal for an intent annotation, e.g. 'ship a deploy to production'."),
+            testid: z
+                .string()
+                .optional()
+                .describe('data-testid value for assert-visible / mark-dynamic / success-state annotations.'),
+            signal: z.string().optional().describe('Signal name for success-state annotations.'),
+            statePath: z
+                .string()
+                .optional()
+                .describe("Store dot-path for an assert-state (last step) or success-state (golden end) store-truth assertion (e.g. 'deployments.0.status'). With `store` and optional `equals` — asserts the app's source of truth, not just the DOM."),
+            store: z
+                .string()
+                .optional()
+                .describe('Store name for a statePath assert-state/success-state annotation.'),
+            equals: z
+                .unknown()
+                .optional()
+                .describe('Expected value for statePath: a literal, or a { $gte | $contains | $length }.'),
+            hold: z
+                .boolean()
+                .optional()
+                .describe('Treat statePath as an INVARIANT that must still hold AFTER the action settles (a blast-radius "this unrelated path must not have moved" check), not a condition to wait for. Without it a wait-until-true read passes before an over-reaching side-effect lands.'),
+            dataMatches: z
+                .record(z.unknown())
+                .optional()
+                .describe('Key/value pairs the signal payload must match (assert-signal only).'),
+            net: z
+                .object({
+                method: z.string().optional(),
+                urlContains: z.string().optional(),
+                status: z.number().optional(),
+                count: z.number().int().nonnegative().optional(),
+            })
+                .optional()
+                .describe('Network golden end-condition for success-state: the flow succeeds only when EXACTLY `count` requests match { method?, urlContains?, status? } since the action (omit count = presence). Catches the double-submit / retry-storm regression a presence check passes.'),
+            console: z
+                .object({
+                level: z.string().optional(),
+                absent: z.boolean().optional(),
+            })
+                .optional()
+                .describe('Console golden end-condition for success-state: with absent:true the flow succeeds only when the action logged NO console message at `level` (default "error") — "completed with a clean console". Catches an action that logs a caught error/rejection while the UI still renders fine.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+            annotation: z
+                .unknown()
+                .optional()
+                .describe('Structured annotation: { kind, name, dataMatches? } for assert-signal; { kind, testid } for assert-visible / mark-dynamic; { kind, signal?, testid? } for success-state.'),
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            target: z.string().optional(),
+            compiled: z.string().optional(),
+            code: z.string().optional(),
+        },
+        handler: (deps, args) => {
+            const name = asString(args['flow']) ?? DEFAULT_RECORDING;
+            // Structured boundary: a free NL string / unknown kind fails the schema → UNKNOWN_KIND.
+            const parsed = AnnotationSchema.safeParse(args);
+            if (!parsed.success) {
+                return Promise.resolve({ ok: false, code: AnnotationErrorCode.UNKNOWN_KIND });
+            }
+            const stepCount = deps.recordings.stepCount(name);
+            const compiled = deps.recordings.getCompiled(name) !== undefined;
+            if (stepCount === undefined && !compiled) {
+                return Promise.resolve({ ok: false, code: AnnotationErrorCode.NO_ACTIVE_RECORDING });
+            }
+            const outcome = compileAnnotation(parsed.data, stepCount ?? 0);
+            if (!outcome.result.ok)
+                return Promise.resolve(outcome.result);
+            const patch = outcome.patch;
+            if (patch !== undefined) {
+                if (patch.dynamicAdd !== undefined)
+                    deps.annotations.addDynamic(name, patch.dynamicAdd);
+                if (patch.success !== undefined)
+                    deps.annotations.setSuccess(name, patch.success);
+                if (patch.intent !== undefined)
+                    deps.annotations.setIntent(name, patch.intent);
+                if (patch.stepIndex !== undefined && patch.stepExpect !== undefined) {
+                    deps.annotations.setStepExpect(name, patch.stepIndex, patch.stepExpect);
+                }
+            }
+            return Promise.resolve(outcome.result);
+        },
+    },
+];
+//# sourceMappingURL=annotate-tools.js.map

package/dist/flows/annotate-tools.js.map

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

package/dist/flows/annotate.d.ts

@@ -0,0 +1,22 @@
+import { type Annotation, type AnnotateOutcome } from '@reticlehq/core';
+/**
+ * The PURE compiler at the heart of the annotation facet. A structured annotation +
+ * the current captured-step count → an AnnotateOutcome (a result envelope + the patch to apply to
+ * the AnnotationStore). No IO, no clock, unit-testable in isolation.
+ *
+ *   assert-signal  → step.expect.signal (+ signalData)   on the LAST step (needs ≥1 step)
+ *   assert-visible → step.expect.element.testid          on the LAST step (needs ≥1 step)
+ *   mark-dynamic   → flow.dynamic[] += testid            flow-level, allowed with 0 steps
+ *   success-state  → flow.success = { signal | element } flow-level (signal XOR testid; both → signal)
+ *
+ * FIRST CUT: only the four structured kinds above. Free natural-language annotation → predicate
+ * compilation is explicitly FUTURE — an NL string never reaches here (AnnotationSchema
+ * rejects it upstream; the tool maps that to UNKNOWN_KIND). No NL parser exists or is faked.
+ */
+export declare function compileAnnotation(a: Annotation, stepCount: number): AnnotateOutcome;
+/**
+ * Human-readable confirmation text for the recorder strip / tool result,
+ * e.g. `will assert signal diff:shown`. The leading word is the named COMPILED_PREDICATE_PREFIX.
+ */
+export declare function describeCompiled(a: Annotation): string;
+//# sourceMappingURL=annotate.d.ts.map

package/dist/flows/annotate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotate.d.ts","sourceRoot":"","sources":["../../src/flows/annotate.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,eAAe,EAErB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAuDnF;AAwBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAqCtD"}

package/dist/flows/annotate.js

@@ -0,0 +1,134 @@
+import { AnnotationErrorCode, AnnotationKind, AnnotationTarget, COMPILED_PREDICATE_PREFIX, } from '@reticlehq/core';
+/**
+ * The PURE compiler at the heart of the annotation facet. A structured annotation +
+ * the current captured-step count → an AnnotateOutcome (a result envelope + the patch to apply to
+ * the AnnotationStore). No IO, no clock, unit-testable in isolation.
+ *
+ *   assert-signal  → step.expect.signal (+ signalData)   on the LAST step (needs ≥1 step)
+ *   assert-visible → step.expect.element.testid          on the LAST step (needs ≥1 step)
+ *   mark-dynamic   → flow.dynamic[] += testid            flow-level, allowed with 0 steps
+ *   success-state  → flow.success = { signal | element } flow-level (signal XOR testid; both → signal)
+ *
+ * FIRST CUT: only the four structured kinds above. Free natural-language annotation → predicate
+ * compilation is explicitly FUTURE — an NL string never reaches here (AnnotationSchema
+ * rejects it upstream; the tool maps that to UNKNOWN_KIND). No NL parser exists or is faked.
+ */
+export function compileAnnotation(a, stepCount) {
+    switch (a.kind) {
+        case AnnotationKind.ASSERT_SIGNAL: {
+            if (stepCount === 0)
+                return noStep();
+            const expect = { signal: a.name };
+            if (a.dataMatches !== undefined)
+                expect.signalData = a.dataMatches;
+            return stepPatch(a, stepCount, expect);
+        }
+        case AnnotationKind.ASSERT_VISIBLE: {
+            if (stepCount === 0)
+                return noStep();
+            return stepPatch(a, stepCount, { element: { testid: a.testid } });
+        }
+        case AnnotationKind.ASSERT_STATE: {
+            if (stepCount === 0)
+                return noStep();
+            const state = { path: a.statePath };
+            if (a.store !== undefined)
+                state.store = a.store;
+            if (a.equals !== undefined)
+                state.equals = a.equals;
+            return stepPatch(a, stepCount, { state });
+        }
+        case AnnotationKind.MARK_DYNAMIC:
+            return {
+                result: { ok: true, target: AnnotationTarget.FLOW, compiled: describeCompiled(a) },
+                patch: { dynamicAdd: a.testid },
+            };
+        case AnnotationKind.SUCCESS_STATE: {
+            // Precedence: signal > state > net > console > testid (a consequence end-condition beats a
+            // presence check). None of them → MISSING_FIELD.
+            if (a.signal !== undefined) {
+                return flowSuccess(a, { signal: a.signal });
+            }
+            if (a.statePath !== undefined) {
+                const state = { path: a.statePath };
+                if (a.store !== undefined)
+                    state.store = a.store;
+                if (a.equals !== undefined)
+                    state.equals = a.equals;
+                if (a.hold !== undefined)
+                    state.hold = a.hold;
+                return flowSuccess(a, { state });
+            }
+            if (a.net !== undefined) {
+                return flowSuccess(a, { net: a.net });
+            }
+            if (a.console !== undefined) {
+                return flowSuccess(a, { console: a.console });
+            }
+            if (a.testid !== undefined) {
+                return flowSuccess(a, { element: { testid: a.testid } });
+            }
+            return { result: { ok: false, code: AnnotationErrorCode.MISSING_FIELD } };
+        }
+        case AnnotationKind.INTENT:
+            // Flow-level, allowed with 0 steps (the business goal is declared up front).
+            return {
+                result: { ok: true, target: AnnotationTarget.FLOW, compiled: describeCompiled(a) },
+                patch: { intent: a.text },
+            };
+    }
+}
+function noStep() {
+    return { result: { ok: false, code: AnnotationErrorCode.NO_STEP_TO_ANNOTATE } };
+}
+function stepPatch(a, stepCount, stepExpect) {
+    return {
+        result: {
+            ok: true,
+            target: AnnotationTarget.STEP,
+            compiled: describeCompiled(a),
+        },
+        patch: { stepIndex: stepCount - 1, stepExpect },
+    };
+}
+function flowSuccess(a, success) {
+    return {
+        result: { ok: true, target: AnnotationTarget.FLOW, compiled: describeCompiled(a) },
+        patch: { success },
+    };
+}
+/**
+ * Human-readable confirmation text for the recorder strip / tool result,
+ * e.g. `will assert signal diff:shown`. The leading word is the named COMPILED_PREDICATE_PREFIX.
+ */
+export function describeCompiled(a) {
+    switch (a.kind) {
+        case AnnotationKind.ASSERT_SIGNAL:
+            return `${COMPILED_PREDICATE_PREFIX} assert signal ${a.name}`;
+        case AnnotationKind.ASSERT_VISIBLE:
+            return `${COMPILED_PREDICATE_PREFIX} assert ${a.testid} visible`;
+        case AnnotationKind.ASSERT_STATE:
+            return `${COMPILED_PREDICATE_PREFIX} assert state ${a.statePath}${a.equals !== undefined ? ` == ${JSON.stringify(a.equals)}` : ''}`;
+        case AnnotationKind.MARK_DYNAMIC:
+            return `${COMPILED_PREDICATE_PREFIX} ignore ${a.testid} (dynamic)`;
+        case AnnotationKind.SUCCESS_STATE:
+            if (a.signal !== undefined) {
+                return `${COMPILED_PREDICATE_PREFIX} succeed when signal ${a.signal}`;
+            }
+            if (a.statePath !== undefined) {
+                return `${COMPILED_PREDICATE_PREFIX} succeed when state ${a.statePath}${a.equals !== undefined ? ` == ${JSON.stringify(a.equals)}` : ''}`;
+            }
+            if (a.net !== undefined) {
+                const target = a.net.urlContains ?? a.net.method ?? 'request';
+                return `${COMPILED_PREDICATE_PREFIX} succeed when ${a.net.count !== undefined ? `exactly ${String(a.net.count)} ` : ''}net ${target}`;
+            }
+            if (a.console !== undefined) {
+                const level = a.console.level ?? 'error';
+                return `${COMPILED_PREDICATE_PREFIX} succeed when ${a.console.absent === true ? `no console.${level}` : `console.${level}`}`;
+            }
+            return `${COMPILED_PREDICATE_PREFIX} succeed when ${a.testid ?? ''} visible`;
+        case AnnotationKind.INTENT:
+            return `${COMPILED_PREDICATE_PREFIX} intent: ${a.text}`;
+    }
+}
+//# sourceMappingURL=annotate.js.map

package/dist/flows/annotate.js.map

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

package/dist/flows/annotation-store.d.ts

@@ -0,0 +1,23 @@
+import type { FlowExpect } from '@reticlehq/core';
+export declare class AnnotationStore {
+    #private;
+    /** Testids whose CONTENT must not be asserted at replay (mark-dynamic). Copy, never the live array. */
+    dynamic(name: string): string[];
+    /** The flow's golden end-condition (success-state), or undefined. */
+    success(name: string): FlowExpect | undefined;
+    /** The flow's declared business goal (intent annotation), or undefined. */
+    intent(name: string): string | undefined;
+    /** Per-step expect predicates compiled from assert-* annotations, keyed by step index. */
+    stepExpect(name: string): Map<number, FlowExpect>;
+    /** Append a dynamic testid (mark-dynamic). De-duped so repeated marks stay idempotent. */
+    addDynamic(name: string, testid: string): void;
+    /** Set the flow's success expectation (success-state); a later set overwrites. */
+    setSuccess(name: string, expect: FlowExpect): void;
+    /** Set the flow's declared business goal (intent); a later set overwrites. */
+    setIntent(name: string, text: string): void;
+    /** Set one step's expect (assert-signal / assert-visible); a later set on the same index wins. */
+    setStepExpect(name: string, index: number, expect: FlowExpect): void;
+    /** Drop a recording's annotations (called after reticle_flow_save folds them onto disk). */
+    clear(name: string): void;
+}
+//# sourceMappingURL=annotation-store.d.ts.map

package/dist/flows/annotation-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-store.d.ts","sourceRoot":"","sources":["../../src/flows/annotation-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAkBlD,qBAAa,eAAe;;IAY1B,uGAAuG;IACvG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAI/B,qEAAqE;IACrE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI7C,2EAA2E;IAC3E,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxC,0FAA0F;IAC1F,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC;IAKjD,0FAA0F;IAC1F,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAK9C,kFAAkF;IAClF,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAIlD,8EAA8E;IAC9E,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3C,kGAAkG;IAClG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAIpE,4FAA4F;IAC5F,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;CAG1B"}

package/dist/flows/annotation-store.js

@@ -0,0 +1,51 @@
+export class AnnotationStore {
+    #byName = new Map();
+    #bucket(name) {
+        let bucket = this.#byName.get(name);
+        if (bucket === undefined) {
+            bucket = { dynamic: [], stepExpect: new Map() };
+            this.#byName.set(name, bucket);
+        }
+        return bucket;
+    }
+    /** Testids whose CONTENT must not be asserted at replay (mark-dynamic). Copy, never the live array. */
+    dynamic(name) {
+        return [...(this.#byName.get(name)?.dynamic ?? [])];
+    }
+    /** The flow's golden end-condition (success-state), or undefined. */
+    success(name) {
+        return this.#byName.get(name)?.success;
+    }
+    /** The flow's declared business goal (intent annotation), or undefined. */
+    intent(name) {
+        return this.#byName.get(name)?.intent;
+    }
+    /** Per-step expect predicates compiled from assert-* annotations, keyed by step index. */
+    stepExpect(name) {
+        const source = this.#byName.get(name)?.stepExpect;
+        return source === undefined ? new Map() : new Map(source);
+    }
+    /** Append a dynamic testid (mark-dynamic). De-duped so repeated marks stay idempotent. */
+    addDynamic(name, testid) {
+        const bucket = this.#bucket(name);
+        if (!bucket.dynamic.includes(testid))
+            bucket.dynamic.push(testid);
+    }
+    /** Set the flow's success expectation (success-state); a later set overwrites. */
+    setSuccess(name, expect) {
+        this.#bucket(name).success = expect;
+    }
+    /** Set the flow's declared business goal (intent); a later set overwrites. */
+    setIntent(name, text) {
+        this.#bucket(name).intent = text;
+    }
+    /** Set one step's expect (assert-signal / assert-visible); a later set on the same index wins. */
+    setStepExpect(name, index, expect) {
+        this.#bucket(name).stepExpect.set(index, expect);
+    }
+    /** Drop a recording's annotations (called after reticle_flow_save folds them onto disk). */
+    clear(name) {
+        this.#byName.delete(name);
+    }
+}
+//# sourceMappingURL=annotation-store.js.map

package/dist/flows/annotation-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-store.js","sourceRoot":"","sources":["../../src/flows/annotation-store.ts"],"names":[],"mappings":"AAkBA,MAAM,OAAO,eAAe;IACjB,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAC;IAE3D,OAAO,CAAC,IAAY;QAClB,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;YAChD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,uGAAuG;IACvG,OAAO,CAAC,IAAY;QAClB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,qEAAqE;IACrE,OAAO,CAAC,IAAY;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACzC,CAAC;IAED,2EAA2E;IAC3E,MAAM,CAAC,IAAY;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACxC,CAAC;IAED,0FAA0F;IAC1F,UAAU,CAAC,IAAY;QACrB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;QAClD,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,EAAsB,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAChF,CAAC;IAED,0FAA0F;IAC1F,UAAU,CAAC,IAAY,EAAE,MAAc;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpE,CAAC;IAED,kFAAkF;IAClF,UAAU,CAAC,IAAY,EAAE,MAAkB;QACzC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC;IACtC,CAAC;IAED,8EAA8E;IAC9E,SAAS,CAAC,IAAY,EAAE,IAAY;QAClC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC;IACnC,CAAC;IAED,kGAAkG;IAClG,aAAa,CAAC,IAAY,EAAE,KAAa,EAAE,MAAkB;QAC3D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;IAED,4FAA4F;IAC5F,KAAK,CAAC,IAAY;QAChB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/dist/flows/decision.d.ts

@@ -0,0 +1,13 @@
+import { type FlowFile, type FlowReplayResult, type ReplayDecision, type SuiteVerdict } from '@reticlehq/core';
+export declare function buildDecision(result: FlowReplayResult, flow?: FlowFile): ReplayDecision;
+/**
+ * Aggregate per-flow replays into one suite verdict — the autonomous loop's consolidated answer
+ * after a build: did anything break, and what's the prioritized fix list. Pure: pass the already
+ * decision-annotated replay results + their flows. Passing flows are counted; only failures carry
+ * detail (token-cheap), each with the actionable decision so the agent fixes without re-querying.
+ */
+export declare function buildSuiteVerdict(runs: ReadonlyArray<{
+    replay: FlowReplayResult;
+    flow?: FlowFile;
+}>): SuiteVerdict;
+//# sourceMappingURL=decision.d.ts.map

package/dist/flows/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../src/flows/decision.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,gBAAgB,EAErB,KAAK,cAAc,EAEnB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AA0BzB,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,cAAc,CAyDvF;AAQD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAA;CAAE,CAAC,GACjE,YAAY,CAuBd"}