@reticlehq/server 2.14.0 → 3.2.0

package/dist/portal/realm/http-witness.js

@@ -0,0 +1,135 @@
+/**
+ * The reference witness: a second vantage point that can look and cannot touch.
+ *
+ * Every channel a `Realm` declares is, in the end, the subject describing itself — the DOM says the
+ * DOM changed, the store says the store changed. That is enough for most questions and useless for
+ * the one that matters most: *did the thing the app claims to have done actually happen out in the
+ * world?* Clicking "Delete account" changes the screen AND drops a row, sends an email, revokes a
+ * session in another tab. Every one of those is invisible to an in-subject observer, and every one
+ * of them is where the expensive bugs live.
+ *
+ * This reads a real HTTP endpoint over the real network, in a different process from the page. No
+ * fixture, no recorded response, no stub in the product path: a witness consulting a canned answer
+ * is the subject describing itself with extra steps, and the evidence would be worth nothing.
+ *
+ * `open-verification` ships the abstraction and requires it be proved twice. This is the second proof.
+ */
+import { BlindSpotKind, CHANNEL_DEFAULTS, ChannelId, CloseCondition, Grade, Independence, Surface, Witness, } from 'open-verification';
+/** How much of a response body to carry into a verdict. The rest is one fetch away. */
+const SUMMARY_CAP = 200;
+export class HttpWitness extends Witness {
+    #url;
+    #fetch;
+    #now;
+    /**
+     * One look per window, shared by `observe` and `coverage`.
+     *
+     * Memoised rather than re-fetched because they are two questions about ONE observation: what did
+     * you see, and what could you not see. Asking twice could answer them about different moments,
+     * and a coverage claim that describes a different instant from the evidence is worse than none.
+     * It also makes the pair order-independent — `coverage` used to depend on `observe` having run
+     * first, which is hidden state, and a caller that asked in the other order was told the witness
+     * saw everything when it had not looked at all.
+     */
+    #looks = new Map();
+    constructor(input) {
+        super();
+        this.#url = input.url;
+        this.#fetch = input.fetch;
+        this.#now = input.now;
+    }
+    identity() {
+        return { surface: Surface.SERVICE, instance: this.#url, epoch: 1 };
+    }
+    /**
+     * `net`, and INDEPENDENT — which is the entire reason asking is worth anything.
+     *
+     * The page's own network channel is actuation-derived: it reports the requests the page made. This
+     * one is the answer read back from outside the page, so it can contradict the app rather than
+     * echo it, and it is graded at `consequence` for exactly that reason.
+     */
+    channels() {
+        return [
+            {
+                id: ChannelId.NET,
+                ...CHANNEL_DEFAULTS[ChannelId.NET],
+                independence: Independence.INDEPENDENT,
+                grade: Grade.CONSEQUENCE,
+            },
+        ];
+    }
+    openWindow(budgetMs) {
+        return {
+            id: `hw-${String(this.#now())}`,
+            openedAt: this.#now(),
+            budgetMs,
+            closes: CloseCondition.BUDGET_EXHAUSTED,
+            subject: this.identity(),
+        };
+    }
+    /**
+     * Look once, at close.
+     *
+     * A failed look returns NOTHING and records why. It must never be reported as "observed nothing":
+     * `witnessDisagreement` reads an empty `observed` with no blind spot as *the witness looked and
+     * the world disagreed with the app*, which would turn this witness's own network error into an
+     * accusation against somebody else's code.
+     */
+    #look(window) {
+        const cached = this.#looks.get(window.id);
+        if (cached !== undefined)
+            return cached;
+        const pending = (async () => {
+            try {
+                const res = await this.#fetch(this.#url);
+                return { body: await res.text(), status: res.status };
+            }
+            catch (error) {
+                const failure = error instanceof Error ? error.message : String(error);
+                return { body: '', status: 0, failure };
+            }
+        })();
+        this.#looks.set(window.id, pending);
+        return pending;
+    }
+    async observe(window) {
+        const seen = await this.#look(window);
+        if (seen.failure !== undefined || 0 === seen.body.length)
+            return [];
+        return [
+            {
+                id: `${window.id}-0`,
+                window: window.id,
+                channel: ChannelId.NET,
+                at: this.#now(),
+                value: seen.body,
+                summary: `${String(seen.status)} from ${this.#url}: ${seen.body.slice(0, SUMMARY_CAP)}`,
+            },
+        ];
+    }
+    /**
+     * An empty `blindSpots` is a POSITIVE claim that nothing was hidden, so it is only ever returned
+     * after a look that actually completed.
+     */
+    async coverage(window) {
+        const failure = (await this.#look(window)).failure;
+        if (failure === undefined) {
+            return { window: window.id, observed: [ChannelId.NET], blindSpots: [] };
+        }
+        return {
+            window: window.id,
+            observed: [],
+            blindSpots: [
+                {
+                    kind: BlindSpotKind.BOUNDARY_UNCROSSABLE,
+                    channel: ChannelId.NET,
+                    detail: `could not reach ${this.#url}: ${failure}`,
+                    // A witness that could not look impeaches every claim it was asked to corroborate — the
+                    // verdict must read `unknown`, never a pass earned by an observer that was not there.
+                    impeaching: true,
+                    remedy: 'check the endpoint is running and reachable from the daemon',
+                },
+            ],
+        };
+    }
+}

package/dist/portal/realm/web-realm.d.ts

@@ -0,0 +1,225 @@
+import { type Action, type ActionReceipt, type Capability, type ChannelDescriptor, ChannelId as ProtocolChannel, type Anomaly, type Coverage, type DeterminismProfile, type Handle, type Observation, Realm, type FixtureRef, type Reversal, type SubjectRef, type Window as ProtocolWindow } from 'open-verification';
+import type { Session } from '../session/session.js';
+/**
+ * An adapter from `Session` to the protocol's `Realm`.
+ *
+ * A realm is a PAIR — half the answers live in the browser, half in the daemon — so it must live
+ * daemon-side; the SDK can never implement this interface, because it cannot photograph itself.
+ * Electron and Tauri run the same SDK and differ only in who owns the pixels, which is why this is
+ * one class and not three.
+ */
+/**
+ * A way to save and restore whatever the subject is holding — a cookie jar, localStorage, a session.
+ *
+ * Optional, because on the web the capability belongs to the CONNECTION rather than to the realm. An
+ * attached session — the user's own browser with the SDK in it, which is the common case — cannot
+ * write a cookie jar from inside the page; httpOnly is the entire point of httpOnly. A DRIVEN page
+ * has a browser context behind it and can.
+ *
+ * The payload is opaque here on purpose: the protocol never reads it, and only whatever wrote it can.
+ */
+export interface FixturePort {
+    capture(): Promise<unknown>;
+    apply(payload: unknown): Promise<void>;
+}
+/**
+ * A way to break the subject on purpose and put it back.
+ *
+ * Optional for the same reason the fixture port is: a driven page can be perturbed and an attached
+ * tab cannot. Declared as what the realm NEEDS rather than imported from whatever provides it.
+ */
+export interface MutationPort {
+    mutate(mutation: {
+        kind: string;
+        target?: string;
+    }): Promise<Reversal>;
+    revert(): Promise<void>;
+}
+export interface WebRealmDeps {
+    readonly session: Session;
+    /** Present only when this connection can actually perturb the page. See `MutationPort`. */
+    readonly mutations?: MutationPort;
+    /** Present only when this connection can actually restore state. See `FixturePort`. */
+    readonly fixtures?: FixturePort;
+    /**
+     * The SESSION's clock, in elapsed milliseconds since it connected — `session.elapsed()`.
+     *
+     * Not wall time, and the distinction is not stylistic. Every event in the buffer is stamped in
+     * this domain, and the buffer is searched BY TIMESTAMP, so a window opened at a wall-clock
+     * instant selects every event ever recorded or none of them depending on which side of 1970 you
+     * are standing on. Writing this file with `Date.now()` produced a window that observed nothing
+     * and reported it as a page that did nothing, which is the most expensive shape of wrong
+     * available here.
+     *
+     * Injected rather than read from the session so the arithmetic stays reproducible in a test.
+     */
+    readonly now: () => number;
+}
+/**
+ * Which protocol channel each observed event belongs to.
+ *
+ * `Record` over the event vocabulary would be better and is not available here without importing
+ * the whole enum, so this reads the event's own prefix -- the convention every event name in this
+ * codebase already follows (`net.request`, `dom.added`, `state.change`). An event whose prefix is
+ * unrecognised is reported on no channel rather than guessed onto one, because a guess here is an
+ * observation attributed to a source that did not produce it.
+ */
+export declare const CHANNEL_OF_PREFIX: Readonly<Record<string, ProtocolChannel>>;
+/**
+ * Prefixes that are deliberately NOT evidence, each with the reason.
+ *
+ * These describe the TOOL rather than the subject: Reticle's own transport overflowing, its SDK
+ * failing, a person pressing pause in the HUD, a flow being recorded. Reporting any of them as
+ * evidence about the application would be the observer contaminating the observation, which is
+ * the confusion this whole protocol exists to prevent.
+ *
+ * Named rather than left to fall through, because "unrecognised" and "deliberately excluded"
+ * were producing identical behaviour and only one of them is a decision. `every-event-is-placed
+ * .test.ts` fails if a new prefix belongs to neither list.
+ */
+export declare const NOT_EVIDENCE: Readonly<Record<string, string>>;
+/**
+ * Application behaviour the protocol has no channel for.
+ *
+ * `download` is the app producing a FILE -- a Blob handed to `URL.createObjectURL` and saved.
+ * It is unambiguously the subject acting, and it is the one artifact class nothing outside the
+ * browser can inspect, because it never crosses the network: there is no request to intercept.
+ *
+ * The protocol's nine channels cannot say it. It is not `net` (its own definition is that no
+ * network is involved), not `storage` (that is cookies and web storage), not `ui`. Mapping it to
+ * the nearest one would be exactly the error `observe()` refuses elsewhere -- an observation
+ * attributed to a source that did not produce it.
+ *
+ * So it is named here rather than mapped or silently dropped, and it is a **gap in the
+ * specification** rather than in this adapter: a tenth channel, for a consequence the subject
+ * emitted that left no trace on any of the nine.
+ */
+export declare const NO_PROTOCOL_CHANNEL: Readonly<Record<string, string>>;
+export declare class WebRealm extends Realm {
+    #private;
+    /**
+     * Break the subject, when something can — and be ABSENT when nothing can.
+     *
+     * The same structural honesty the fixture methods carry: a declared method is always present, so
+     * a realm with no port would answer "yes I can be broken" and then throw. A mutation set that
+     * cannot be applied is not a small mutation set, it is a mutation score that demotes flows for
+     * surviving things that never happened to them.
+     */
+    readonly mutate?: (mutation: {
+        kind: string;
+        target?: string;
+    }) => Promise<Reversal>;
+    /**
+     * Saved state, and putting it back — assigned in the constructor rather than declared as methods,
+     * for the same reason `mutate` is. A realm must not OFFER a fixture it cannot honour: claiming one
+     * you cannot restore produces flows that pass because the PREVIOUS flow left the right state
+     * behind, which is a suite that only works in the order it was written. `applyFixture ===
+     * undefined` is how an optional member says *not offered*.
+     */
+    readonly captureFixture?: () => Promise<FixtureRef>;
+    readonly applyFixture?: (ref: FixtureRef) => Promise<void>;
+    constructor(deps: WebRealmDeps);
+    /**
+     * Identity that dies with the document, and an epoch that moves when the code does.
+     *
+     * `currentDocumentId` is already the thing that changes on a full navigation, and
+     * `currentEditEpoch` already the round of edits — both were built for exactly the reasons the
+     * protocol gives, years before the protocol said so. Mapping them is a rename, which is the
+     * strongest evidence available that the abstraction was not invented for this document.
+     */
+    identity(): SubjectRef;
+    /**
+     * What the page said it can observe, at the grades this specification assigns.
+     *
+     * Read from the handshake rather than assumed. An SDK too old to declare returns UNDEFINED
+     * there, and this reports an empty list — which makes every claim `unknown` and is the correct,
+     * loud answer. Substituting a hopeful default here would be this file quietly restoring the
+     * exact bug the declaration was added to remove.
+     */
+    /**
+     * A browser is the cheapest subject in this table, and saying so is what lets the rest of the
+     * protocol stop assuming every subject is one.
+     *
+     * `replayPrefix: 'free'` is measured, not asserted: re-driving a recorded step costs ~27ms, which
+     * is what makes "fix the break, resume, find the next one" a loop rather than a full re-read.
+     * `time: 'injectable'` because the clock control ships. `actions: 'reversible'` is about the REALM
+     * — a click can be undone by a reload — and not a promise about the app behind it, which is why a
+     * destructive action still needs its own confirmation.
+     */
+    determinism(): DeterminismProfile;
+    channels(): readonly ChannelDescriptor[];
+    capabilities(): readonly Capability[];
+    describe(query?: unknown): Promise<unknown>;
+    protected dispatch(action: Action): Promise<ActionReceipt>;
+    /**
+     * A window that closes when the page goes quiet.
+     *
+     * Quiescence is the right answer HERE and is not the concept — see the specification's note on
+     * why an engine that hard-codes it excludes every asynchronous domain. A document has a frame
+     * loop and a network stack that both eventually stop, which is exactly the condition under
+     * which waiting for silence is meaningful.
+     */
+    openWindow(budgetMs: number): ProtocolWindow;
+    observe(window: ProtocolWindow): Promise<readonly Observation[]>;
+    /**
+     * What could not be seen.
+     *
+     * `impeaching` is left FALSE throughout, deliberately. Whether a blind spot bears on a verdict
+     * depends on which channels the claim reads, and a realm does not see the claim — deciding it
+     * here would be the observer grading the relevance of its own gaps. What a realm CAN do is say
+     * which channel each gap falls on, and the adjudicator matches that against the claim.
+     *
+     * That is a correction. Both halves used to defer: this said the adjudicator would decide, and
+     * the adjudicator filtered on a flag that nothing ever set. Clause 6 was unreachable, and a
+     * window that closed over a request still in flight proved things.
+     */
+    coverage(window: ProtocolWindow): Promise<Coverage>;
+    /**
+     * Did the last settle wait end because the page was throttled?
+     *
+     * Read by the binding as well as by `coverage()`, so that the close condition and the blind
+     * spot agree about the same window rather than each deciding for itself.
+     */
+    settleWasThrottled(): boolean;
+    /**
+     * Two things in the window that cannot both be true.
+     *
+     * This is not new detection. Reticle has found these for a long time -- seventeen kinds of
+     * cross-channel contradiction -- and the specification simply never said whose job it was, so
+     * a binding written from the specification passed an empty array and three planted defects
+     * came back green. The rules were here; nothing was asking for them.
+     *
+     * What crosses from Reticle's registry to the protocol's is deliberately lossy. The protocol
+     * names twelve domain-independent kinds and Reticle has seventeen, because several of ours are
+     * about a browser specifically. A kind with no protocol equivalent is reported with an `x-`
+     * prefix, which the specification allows, rather than being forced into the nearest listed one
+     * -- an anomaly filed under the wrong kind is worse than one filed under an unfamiliar name.
+     *
+     * The TIER is carried across unchanged and that is the load-bearing part: `absence-derived`
+     * may only downgrade a verdict to `unknown`, never force a `no`, because the window's end was
+     * our choice and "I stopped looking" is not "it did not happen".
+     */
+    detect(window: ProtocolWindow, observed: readonly Observation[]): Promise<readonly Anomaly[]>;
+    /**
+     * How a person names a control, turned into a handle `act` will accept.
+     *
+     * The gap that a driver written against this interface fell straight into: it held
+     * `testid=login-submit`, handed it to `act` as a target, and every action was refused --
+     * correctly, because a selector is not a handle, and nothing in the interface bridged the two.
+     *
+     * Several matches are returned, never narrowed. Picking the first plausible one is how a
+     * driver acts on the element beside the one it meant, which this project has measured on a
+     * real dashboard and reported as a clean green.
+     */
+    locate(query: unknown): Promise<readonly Handle[]>;
+    /**
+     * Pixels, and the one place the two surfaces genuinely differ.
+     *
+     * A browser tab is photographed through the debugging protocol; a desktop window has no such
+     * endpoint and is read from its own backing store through the shell. Both arrive here as the
+     * same command, which is why one class serves both — and why capturing a screen REGION was the
+     * wrong answer for desktop: it photographs the glass, so a window behind the editor yields a
+     * picture of the editor, saved as a baseline a later comparison would trust.
+     */
+    photograph(): Promise<Uint8Array>;
+}