@gate-forge/witness 0.0.0-stage → 0.9.0

package/dist/witness/types.d.ts

@@ -0,0 +1,1094 @@
+/**
+ * Witness-side data shapes (pin #7 wire + adapter contract, pin #8).
+ */
+import type { Server } from 'node:http';
+import type { EvidenceRecord, TracedSession, TrustTier, TwinShape } from '@gate-forge/core';
+import type { ChaosOptions } from './chaos.js';
+import type { TwinShapePlan } from './twin-shapes.js';
+/**
+ * Supervisor-issued session credential (plan Phase 1, work item 2): the
+ * trusted supervisor (the Playwright reporter process) opens one session
+ * per started test and the worker-side fixture RESOLVES it by the exact
+ * (workerIndex, testId) pair. The session token is issued by the witness,
+ * never derivable by the suite: submissions without a valid OPEN session
+ * are rejected fail-closed, so a suite-supplied testId or annotation
+ * alone cannot mint records for an arbitrary session.
+ */
+export interface SessionCredential {
+    /** Witness-issued session id (UUID). */
+    sessionId: string;
+    /** Per-session secret; required on every submission. */
+    sessionToken: string;
+    /** The supervisor-registered testId (records are forced onto it). */
+    testId: string;
+    /** The worker the session is bound to. */
+    workerIndex: number;
+    /**
+     * The session's DEDICATED observation-proxy origin (its own loopback
+     * port), when the run wires an observation proxy: the worker's browser
+     * uses this origin for the whole test, so every request on it —
+     * absolute paths included — is attributed to THIS session. Null when
+     * no observation proxy is active (nothing to attribute).
+     */
+    proxyUrl: string | null;
+    /**
+     * The supervisor-registered obligation claims for this test (Phase 4
+     * claim injection): the merged native-annotation + sidecar-mapping
+     * claims the orchestrating CLI resolved from the tracked mappings and
+     * the supervisor carried on the session-open path. Declarations only —
+     * they route evidence onto obligation identities and never satisfy
+     * anything by themselves; every record is still forced onto the
+     * supervisor-registered session/test identity and graded from
+     * witnessed evidence. Empty/absent for runs without mappings.
+     */
+    claims?: string[];
+}
+/**
+ * `POST /records` body (pin #7, Phase 1 extension): a test-side primitive
+ * submitting UI-observed evidence. `claimId` is the claimed obligation id —
+ * the annotation's `<resourceId>:<contract>` — and `testId` binds the record
+ * to the test that produced the claim. Phase 1: `sessionId` +
+ * `sessionToken` carry the supervisor-issued session credential; the
+ * witness rejects submissions without a valid OPEN session and forces the
+ * record's testId onto the session's supervisor-registered value.
+ */
+export interface RecordsRequest {
+    claimId: string;
+    kind: string;
+    payload: unknown;
+    testId: string;
+    sessionId: string;
+    sessionToken: string;
+}
+/** `POST /records` response (pin #7, minimal wire contract). */
+export interface RecordsResponse {
+    recordId: string;
+    trust: TrustTier;
+    runId: string;
+}
+/**
+ * `POST /witness/persistence` body (pin #7): the fixture asks the
+ * engine-side witness to run the resource's reviewed adapter (GET-only)
+ * for one entity. The issued record carries the ENGINE OBSERVATION
+ * (`found`, adapter-normalized `fields`, and a `before` link when a
+ * pre-observation was consumed) — expectations NEVER come from the
+ * suite (audit round 5).
+ *
+ * `preObservationId` references a witness-issued pre-observation (`POST
+ * /witness/pre-observation`): an id-set snapshot for create
+ * postconditions (`before: {entityAbsent}`), or an entity-fields
+ * snapshot for update postconditions (`before: {found, fields}`).
+ */
+export interface PersistenceRequest {
+    resourceId: string;
+    entityId: unknown;
+    preObservationId?: string;
+    /** Closed UI-action interval whose post-state this persistence read binds to. */
+    anchorId?: string;
+}
+/**
+ * `POST /witness/pre-observation` body: an engine-side snapshot taken
+ * BEFORE a claimed action. With `entityId` the witness snapshots that
+ * entity's observed fields (update postconditions); without it, the
+ * resource's observed id set (create postconditions). Phase 1: requires
+ * the supervisor-issued session credential.
+ */
+export interface PreObservationRequest {
+    resourceId: string;
+    testId: string;
+    claimId: string;
+    entityId?: unknown;
+    sessionId: string;
+    sessionToken: string;
+}
+/** `POST /witness/pre-observation` response. */
+export interface PreObservationResponse {
+    observationId: string;
+    observed: number;
+}
+/** `POST /witness/persistence` response (pin #7). */
+export interface PersistenceResponse {
+    recordId: string;
+    runId: string;
+    verdictRelevant: {
+        found: boolean;
+        fieldsMatch: boolean;
+        mismatches?: string[];
+    };
+}
+/**
+ * `POST /runs/server-e2e-declarations` body (SUPERVISOR ONLY): the
+ * obligation ids the trusted mapping layer declared kind `server-e2e`.
+ * Registration is a PRE-run fact (like the expected set): bound once,
+ * identical re-registration idempotent, any change or late registration
+ * refused — the witness never stamps `channel: 'server'` records for
+ * obligations outside this set, so the suite cannot steer an intent onto
+ * a browser-kind obligation and a bearer of an intent can never
+ * self-verify.
+ */
+export interface ServerE2eDeclarationsRequest {
+    obligations: readonly string[];
+}
+/** `POST /runs/server-e2e-declarations` response. */
+export interface ServerE2eDeclarationsResponse {
+    bound: true;
+    count: number;
+    obligations: string[];
+}
+/**
+ * `POST /runs/observe-declarations` body (SUPERVISOR ONLY): the
+ * obligation ids the trusted mapping layer declared kind `observed-e2e`
+ * (Observe channel, Phase 2). Registration is a PRE-run fact like the
+ * server-e2e set: bound once, identical re-registration idempotent, any
+ * change or late registration refused — the witness never stamps
+ * `channel: 'observe'` records for obligations outside this set, so a
+ * suite-driven test can never steer observe evidence onto an
+ * engine-kind obligation.
+ */
+export interface ObserveDeclarationsRequest {
+    obligations: readonly string[];
+}
+/** `POST /runs/observe-declarations` response. */
+export interface ObserveDeclarationsResponse {
+    bound: true;
+    count: number;
+    obligations: string[];
+}
+/**
+ * `POST /observe/finalize` body (SUPERVISOR ONLY — the drain calls it
+ * after a passed test, before sealing the session): resolve one
+ * session's observe-eligible claims against the session's own proxied
+ * traffic plus independent adapter reads, and stamp witnessed
+ * `persistence.observed` records for whatever resolves.
+ *
+ * The session must still be OPEN (finalize runs before seal; a sealed
+ * session is refused) so no record is ever injected after the test
+ * ended. Ambiguity, missing traffic, unparsable bodies, and adapter
+ * trouble resolve to typed NOTES in the response — never to
+ * satisfaction, never to a run failure.
+ */
+export interface ObserveFinalizeRequest {
+    sessionId: string;
+}
+/** One obligation the finalize resolved into a witnessed record. */
+export interface ObserveFinalizedObligation {
+    /** Obligation id the record was issued under. */
+    obligationId: string;
+    /** The issued witnessed record id. */
+    recordId: string;
+    /** The CRUD operation the binding proved. */
+    operation: 'create' | 'read' | 'update' | 'delete';
+    /** The witness-resolved entity id (scalar or column-keyed object). */
+    entityId: unknown;
+}
+/** `POST /observe/finalize` response. */
+export interface ObserveFinalizeResponse {
+    finalized: ObserveFinalizedObligation[];
+    /** Typed non-satisfaction notes (missing traffic, ambiguity, …). */
+    notes: string[];
+}
+/**
+ * `POST /witness/server-persistence` body (SUPERVISOR ONLY — the drain
+ * forwards it with the verifier key; the suite can only write intent
+ * spool lines, never call this): one persistence claim intent, already
+ * drained from the runner-side intents spool.
+ *
+ * - create: `pre` (expect-absent) BEFORE the mutation stores a witness
+ *   pre-observation; `post` (expect-present) probes, consumes it, and
+ *   stamps `before: {entityAbsent}` into the record — the same shape the
+ *   browser path grades.
+ * - update: `pre` (expect-present) snapshots the entity's fields;
+ *   `post` consumes it into `before: {found, fields}` (the update delta
+ *   grades against the classification's updateableFields in the engine).
+ * - read: `post` (expect-present) only. delete: `post` (expect-absent
+ *   for hard; expect-present for archive states) only.
+ *
+ * `sequence` is strictly increasing per claimId; a replayed or
+ * out-of-order line resolves to a typed failure (fail closed), so no
+ * bearer of an intent can re-drive a stale observation.
+ */
+export interface ServerPersistenceIntentRequest {
+    resourceId: string;
+    /** Obligation id `<resourceId>:persistence:<op>` the intent serves. */
+    claimId: string;
+    operation: 'create' | 'read' | 'update' | 'delete';
+    phase: 'pre' | 'post';
+    intent: 'expect-present' | 'expect-absent';
+    /** The entity key: scalar for single-column PKs, column-keyed object for composite. */
+    key: unknown;
+    /** Strictly increasing per claimId (replay → typed failure). */
+    sequence: number;
+    /** The claiming test's id (diagnostic attribution; the claim join key). */
+    testId: string;
+}
+/** `POST /witness/server-persistence` response for a `pre` intent. */
+export interface ServerPreObservationResponse {
+    resolved: 'pre';
+    found: boolean;
+}
+/** `POST /witness/server-persistence` response for a `post` intent. */
+export interface ServerPersistenceResponse {
+    recordId: string;
+    runId: string;
+    trust: TrustTier;
+    channel: 'server';
+    verdictRelevant: {
+        found: boolean;
+    };
+}
+/** `POST /sessions/open` body (Phase 1; Phase 4 adds claim injection). */
+export interface SessionOpenRequest {
+    /** The test's runner-assigned id (same id the reporter writes to claims.json). */
+    testId: string;
+    /** The worker the test runs on (binds worker → session). */
+    workerIndex: number;
+    /**
+     * Supervisor-carried identity of the started test (enforcement-review
+     * fix 2a/3): repo-relative file + title path + project, as drained from
+     * the runner's lifecycle spool. When an expected set is registered,
+     * THIS identity decides membership — a test outside the registered set
+     * is refused. Optional only for runs without a registered expected set.
+     */
+    file?: string;
+    titlePath?: readonly string[];
+    project?: string | null;
+    /**
+     * Phase 4 claim injection: the mapped obligation claims this test must
+     * land its evidence on (resolved from the sidecar/native mappings by
+     * the orchestrating CLI and carried by the supervisor on the
+     * session-open path). Obligation-id-shaped, deduplicated by the
+     * witness; empty/absent for annotation-claimed tests, which keep
+     * working unchanged. Claims remain DECLARATIONS: they never satisfy
+     * anything by themselves.
+     */
+    claims?: readonly string[];
+}
+/** `POST /sessions/open` response: the session binding (runId, sessionId, testId, worker). */
+export interface SessionOpenResponse extends SessionCredential {
+    /** Witness-monotonic tick at open (the session clock origin). */
+    openedTick: number;
+}
+/** `POST /sessions/close` body: the supervisor seals the session with the observed outcome. */
+export interface SessionCloseRequest {
+    sessionId: string;
+    /** The observed test outcome (e.g. 'passed' | 'failed'); recorded, never graded here. */
+    outcome?: string;
+}
+/** `POST /sessions/close` response. */
+export interface SessionCloseResponse {
+    sealed: true;
+}
+/**
+ * `POST /sessions/release` body: the supervisor releases a session's
+ * WORKER SLOT before the runner's outcome for that test has arrived.
+ *
+ * The supervisor calls it on the WORKER's own lifecycle end (the end
+ * the worker spools as soon as the test itself is finished), so the
+ * next test that same worker runs opens its session immediately instead
+ * of queueing behind a main-process event that may still be seconds
+ * away. Nothing is credited: the session stops accepting submissions,
+ * its proxy dies, and only the runner's later `POST /sessions/close`
+ * records the outcome — an outcome that never arrives leaves the
+ * session without one, which grades not-passed.
+ */
+export interface SessionReleaseRequest {
+    sessionId: string;
+}
+/** `POST /sessions/release` response. */
+export interface SessionReleaseResponse {
+    released: true;
+}
+/** `POST /sessions/resolve` body: the worker proves WHICH open session it runs under. */
+export interface SessionResolveRequest {
+    testId: string;
+    workerIndex: number;
+}
+/** `POST /sessions/resolve` response (a resolvable credential, proxy prefix included). */
+export interface SessionResolveResponse extends SessionCredential {
+    openedTick: number;
+}
+/** `POST /sessions/intervals/open` body: the fixture marks a UI-action observation interval. */
+export interface IntervalOpenRequest {
+    sessionId: string;
+    sessionToken: string;
+    /** The UI operation the interval covers ('create' | 'read' | 'update' | 'delete'). */
+    operation: string;
+}
+/** `POST /sessions/intervals/open` response. */
+export interface IntervalOpenResponse {
+    intervalId: string;
+    startTick: number;
+}
+/** `POST /sessions/intervals/close` body. */
+export interface IntervalCloseRequest {
+    sessionId: string;
+    sessionToken: string;
+    intervalId: string;
+}
+/** `POST /sessions/intervals/close` response. */
+export interface IntervalCloseResponse {
+    startTick: number;
+    endTick: number;
+}
+/**
+ * `POST /browser/surface` body (plan Phase 1 item 4): the worker-side
+ * fixture registers the consumer-declared surface descriptor for one
+ * open session. The descriptor's selectors are locators only — the
+ * engine verifies every outcome itself. The driven ORIGIN is never part
+ * of this body (a present `appBaseUrl` is rejected): the engine drives
+ * exactly the provisioned attested subject from trusted witness
+ * configuration. Requires the supervisor-issued session credential on
+ * an OPEN session; the record's testId is forced onto the session's
+ * value.
+ */
+export interface BrowserSurfaceRequest {
+    sessionId: string;
+    sessionToken: string;
+    testId: string;
+    /** The consumer-declared surface descriptor (validated engine-side). */
+    surface: unknown;
+}
+/**
+ * `POST /browser/action` body: perform ONE constrained surface
+ * operation on the session's engine-owned page and issue
+ * engine-observed records for it.
+ */
+export interface BrowserActionRequest {
+    sessionId: string;
+    sessionToken: string;
+    testId: string;
+    /** Obligation ids to issue the engine-observed records under. */
+    claimIds: string[];
+    /** The constrained operation to perform. */
+    operation: 'create' | 'read' | 'update' | 'delete';
+    /** Entered input (create/update); target entity (read/update/delete). */
+    fields?: Record<string, string>;
+    entityId?: string;
+}
+/** `POST /browser/action` response: the engine's own observation. */
+export interface BrowserActionResponse {
+    /** Entity id OBSERVED from the rendered list (never declared). */
+    entityId: string;
+    /** The exact input values the engine typed. */
+    enteredFields: Record<string, string>;
+    /** The rendered fields the engine read back. */
+    renderedFields: Record<string, string>;
+    /** The app response status the engine captured for the mutation. */
+    appStatus: number;
+    /** Engine-side pre-observation id (create/update; consumed by persistence verify). */
+    preObservationId: string | null;
+    /** Closed UI-action interval used to bind the observed action and persistence read. */
+    anchorId: string;
+    /** Record ids the engine issued for this action (per claim). */
+    recordIds: string[];
+}
+/**
+ * `POST /browser/visible` body: re-read the rendered result for the
+ * engine-observed entity on the session's engine page and issue
+ * engine-observed visible-result records.
+ */
+export interface BrowserVisibleRequest {
+    sessionId: string;
+    sessionToken: string;
+    testId: string;
+    /** Obligation ids to issue the engine-observed records under. */
+    claimIds: string[];
+    /** The engine-observed entity id (must match the action's). */
+    entityId: string;
+    /** The original action (decides row vs form readback). */
+    operation: 'create' | 'read' | 'update' | 'delete';
+    /** Optional for legacy clients; new fixture receipts bind visible reads to one action. */
+    anchorId?: string;
+}
+/** `POST /browser/visible` response. */
+export interface BrowserVisibleResponse {
+    entityId: string;
+    /** The rendered fields the engine read. */
+    fields: Record<string, string>;
+    /** Record ids the engine issued (per claim). */
+    recordIds: string[];
+}
+/**
+ * Witness-held session state (plan Phase 1). Created only by
+ * `POST /sessions/open` (the trusted supervisor, verifier-key
+ * authenticated — enforcement-review fix 3); sealed by
+ * `POST /sessions/close` (same authority). Sealed sessions answer no
+ * submission, no interval, and no resolve call.
+ */
+export interface TestSession {
+    /** Witness-issued session id (UUID). */
+    sessionId: string;
+    /** Per-session secret required on every submission. */
+    token: string;
+    /** The supervisor-registered testId (every record is forced onto it). */
+    testId: string;
+    /** The worker the session is bound to (one OPEN session per worker). */
+    workerIndex: number;
+    /**
+     * `open` accepts submissions; `sealed` and `outcome-pending` reject
+     * everything (fail closed). `outcome-pending` is a RELEASED session:
+     * the worker's own lifecycle end unbound its worker slot (so the
+     * worker's next test opens its session without waiting for the
+     * runner's main process), but the session's OUTCOME is still owed by
+     * the runner's reporter and is recorded by the later close.
+     */
+    status: 'open' | 'sealed' | 'outcome-pending';
+    /** Witness-monotonic tick at open. */
+    openedTick: number;
+    /** Witness-monotonic tick at seal (null while open). */
+    sealedTick: number | null;
+    /** The outcome the supervisor observed at close (recorded, never graded). */
+    outcome: string | null;
+    /**
+     * UI-action observation intervals keyed by intervalId. End ticks are
+     * null while the interval is open. Exchanges are consumable as this
+     * session's evidence only when their tick falls inside one of these
+     * intervals — setup traffic outside every interval is never credited.
+     */
+    intervals: Map<string, {
+        startTick: number;
+        endTick: number | null;
+        operation: string;
+    }>;
+    /**
+     * The session's dedicated observation-proxy origin when the run wires
+     * an observation proxy; null otherwise.
+     */
+    proxyUrl: string | null;
+    /** The dedicated proxy server (closed when the session seals). */
+    proxyServer: Server | null;
+    /**
+     * Phase 4 claim injection: the mapped obligation claims the supervisor
+     * registered at open (sorted, deduplicated, obligation-id-shaped;
+     * empty for annotation-only tests). Echoed in the session view so the
+     * supervisor writes claims.json from what the witness registered.
+     */
+    claims: string[];
+    /**
+     * The registered expected-set identity this session was minted for
+     * (enforcement-review fix 2a/2b); null when the run has no registered
+     * expected set. Groups the execution trace by expected test.
+     */
+    registered: {
+        testId: string | null;
+        project: string | null;
+        file: string;
+        titlePath: string[];
+    } | null;
+    /**
+     * Witness-side activity bound to this session: a monotonically
+     * increasing count of everything the witness itself observed under
+     * the session — ledger records issued with the session credential,
+     * recorded UI-action intervals, consumed engine-observed exchanges,
+     * and pre-observations. Diagnostic corroboration only (execution
+     * authority is the supervisor-observed trusted lifecycle).
+     */
+    activity: number;
+    /**
+     * Engine-browser surface registration (plan Phase 1 item 4): the
+     * validated consumer descriptor the engine drives for this session.
+     * The driven ORIGIN is never stored here — it resolves from trusted
+     * witness configuration (`targetBaseUrl`) on every call, so a
+     * suite-named frontend can never become the engine target.
+     */
+    engineSurface: {
+        surface: Record<string, unknown>;
+    } | null;
+    /**
+     * Twin path coverage (E64): true when the supervisor marked this
+     * session OBSERVATION-ONLY (it is a raw twin). Such a session's
+     * requests are recorded as shapes and nothing else: every submission
+     * from it is refused, so it can issue no record, no attestation and
+     * satisfy nothing. Never true for a session with claims.
+     */
+    observationOnly: boolean;
+    /**
+     * The request shapes this session's proxied traffic exercised, in
+     * first-seen order. Computed at record time from the method and
+     * target, so no raw URL and no non-allowlisted query value is ever
+     * stored. Empty in every run that did not ask for twin shapes.
+     */
+    twinShapes: TwinShape[];
+}
+/** One test's recorded twin shapes, as the supervisor read surface returns them. */
+export interface TwinShapeReport {
+    /**
+     * The registered identity of the test these shapes belong to: the
+     * join key both sides speak (project, file, titlePath). Null only when
+     * the run registered no expected set, in which case the caller has no
+     * honest way to name the test and should say so.
+     */
+    identity: {
+        file: string;
+        titlePath: string[];
+        project: string | null;
+    } | null;
+    /** The runner-assigned test id the session ran under (diagnostic). */
+    testId: string;
+    /** True when this session was marked observation-only (a raw twin). */
+    observationOnly: boolean;
+    /** The shapes it exercised, in first-seen order. */
+    shapes: readonly TwinShape[];
+}
+/** `GET /runs/twin-shapes` response (SUPERVISOR ONLY). */
+export interface TwinShapesResponse {
+    /** True when this run recorded twin shapes at all. */
+    enabled: boolean;
+    /** Per test id, sorted; empty when the run recorded nothing. */
+    twins: readonly TwinShapeReport[];
+}
+/**
+ * One expected test registered by the supervisor BEFORE the run
+ * (enforcement-review fix 2a). Identity is (project, file, titlePath);
+ * `testId` is diagnostic (runner-assigned ids are not stable across
+ * enumeration and execution).
+ */
+export interface ExpectedTestRegistration {
+    /** The runner-assigned test id, when enumeration bound one. */
+    testId?: string | null;
+    /** Runner project, or null when the runner reports none. */
+    project: string | null;
+    /** Repo-relative posix file (the identity join key). */
+    file: string;
+    /** Full title path (the identity join key). */
+    titlePath: readonly string[];
+    /**
+     * Twin path coverage (E64): the supervisor marked this test as the RAW
+     * twin of a witnessed one. Absent/false = an ordinary session.
+     *
+     * The mark travels with the REGISTRATION rather than as a list of
+     * runner test ids, because a runner-assigned id is not the id the test
+     * runs under: Playwright hashes the test's file path relative to the
+     * config it loaded, so an id enumerated from the repository's own
+     * config is not the id a supervised run opens the session with. The
+     * identity (project, file, titlePath) is what both sides speak.
+     */
+    observationOnly?: boolean;
+}
+/** `POST /runs/expected-set` body (SUPERVISOR ONLY). */
+export interface ExpectedSetRequest {
+    /** The expected tests, fixed before the run. */
+    tests: readonly ExpectedTestRegistration[];
+}
+/** `POST /runs/expected-set` response. */
+export interface ExpectedSetResponse {
+    /** The set is bound to this run. */
+    bound: true;
+    /** Domain-separated digest over the registered set. */
+    enumerationDigest: string;
+    /** Number of registered expected tests. */
+    count: number;
+}
+/** `GET /runs/execution-trace` response (SUPERVISOR ONLY; fix 2b). */
+export interface ExecutionTraceResponse {
+    /** The digest of the registered expected set (null when none). */
+    enumerationDigest: string | null;
+    /** Per expected test, every session the witness recorded. */
+    tests: Array<{
+        testId: string | null;
+        project: string | null;
+        file: string;
+        titlePath: string[];
+        sessions: TracedSession[];
+    }>;
+}
+/** Witness runtime configuration (env-derived by the bin, explicit in tests). */
+export interface WitnessOptions {
+    /**
+     * ADR 0004 D7 (plan §8 / D1): when set, the witness also starts a
+     * loopback reverse proxy forwarding to this base URL and records
+     * every forwarded request as an engine observation (the runtime HTTP
+     * evidence channel). Transport-only: the observation proves the
+     * witness observed an HTTP exchange; test attribution is
+     * suite-claimed. Must be loopback.
+     */
+    proxyTarget?: string;
+    /**
+     * Timing chaos (E63): the seeded release plan the observation proxy
+     * applies to proxied app RESPONSES. Null/absent is the
+     * byte-identical no-chaos path; a set plan changes timing only —
+     * bytes, status, headers and evidence semantics never move.
+     */
+    chaos?: ChaosOptions | null;
+    /**
+     * Twin path coverage (E64): the observation-only shape recording the
+     * proxy keeps for every request, so the CLI can compare a raw test
+     * with its witnessed twin by request shape. Null/absent is the
+     * byte-identical path: no shape is computed and none is stored. A
+     * shape is never evidence — it cannot issue a record, satisfy an
+     * obligation, or enter an attestation.
+     */
+    twinShapes?: TwinShapePlan | null;
+    /**
+     * Observation-proxy mount prefix (with `proxyTarget`; e.g. `/api`).
+     *
+     * WHY this is an explicit deployment-topology declaration (same
+     * philosophy as `urlBuilders[].base`): in a real deployment the
+     * browser reaches the backend THROUGH the frontend — a dev proxy or
+     * edge serves `/api/ops/...` while the backend route is `/ops/...`.
+     * Whether such a prefix exists is a property of the deployment the
+     * engine cannot derive from source, and guessing wrong would silently
+     * mismatch obligation identities. When set, the observation proxy
+     * forwards the STRIPPED path to the proxy target AND records the
+     * STRIPPED path in observation records, so observations match the
+     * backend-derived obligation identities the suite claims
+     * (`evidence.http.observe({path: '/ops/x'})`). Requests outside the
+     * prefix pass through and are recorded unstripped. Absent/null strips
+     * nothing — forwarding and recording stay byte-identical to an
+     * unmounted proxy.
+     */
+    mountPath?: string | null;
+    /** Run manifest identity (pin #4). */
+    runId: string;
+    /** Per-run token; every call must carry `x-gateforge-run: <token>`. */
+    token: string;
+    /**
+     * Verifier key for the attestation surface (authenticated
+     * `POST /run-context` binding, `GET /ledger-attestation`, and the
+     * manifest v2 `attestation` envelope): shared by the orchestrator
+     * with the witness and the evaluating CLI, NEVER with the tested
+     * suite. When absent the witness serves no attestation and its
+     * manifest append stays unauthenticated (downstream evaluation fails
+     * closed for witnessed records). Environment ONLY (see
+     * `witness/bin.ts`) — never argv, stdout, state files, or suite env.
+     */
+    verifierKey?: string | null;
+    /** Run-state dir; the witness appends its issued recordIds to manifest.json at shutdown. */
+    stateDir?: string | null;
+    /** Directory of reviewed `.mjs` adapters (default `.gateforge/adapters`). */
+    adaptersDir?: string | null;
+    /**
+     * Operator-issued credential the witness presents on its OWN engine-side
+     * adapter reads (GF-10 mediation; dogfood deployment, 2026-09-05/07).
+     *
+     * WHY: adapters perform GET-only reads of the app's own collection
+     * routes to observe persisted state, and those routes authenticate —
+     * an unauthenticated loopback read is a 401, so the engine could not
+     * observe state at all. The credential is issued by the DEPLOYMENT
+     * OPERATOR to the WITNESS ONLY (env `GATEFORGE_ADAPTER_READ_AUTHORIZATION`
+     * or `--adapter-read-authorization`), never to the tested suite, and is
+     * a read-only service principal of the same trust class as the verifier
+     * key. When unset, adapter reads stay unauthenticated (previous
+     * behavior) and protected collections simply fail closed with 401/409.
+     */
+    adapterReadAuthorization?: string | null;
+    /** Classifications document path (YAML) for the primaryKey map + adapter aliases. */
+    classificationsPath?: string | null;
+    /**
+     * Attestation subject (the SUT the UI drives). MUST be loopback
+     * (GF-10); the witness probes its env-fingerprint marker at startup
+     * when `targetFingerprint` is set (GF-13 minimal v1 attestation).
+     */
+    targetBaseUrl?: string | null;
+    /** Expected `x-gateforge-env-fingerprint` marker at the attestation subject. */
+    targetFingerprint?: string | null;
+    /** Default base for adapter reads; a per-adapter `baseUrl` wins. */
+    adapterBaseUrl?: string | null;
+    /** Per-witness-call timeout (pin #7 default 5s). */
+    requestTimeoutMs?: number;
+    /**
+     * Completion-barrier deadline for async behavior effects (Phase 5):
+     * `awaitBarrier` observers get this long to report a real checkpoint.
+     * Default 30s. A timeout is failure, never success.
+     */
+    barrierTimeoutMs?: number;
+    /** Injected clock for `issuedAt` (ISO-8601); default = system now. */
+    now?: () => string;
+    /** Host to bind; default `127.0.0.1` (loopback). */
+    host?: string;
+    /**
+     * Engine-browser launcher override (programmatic use only — never
+     * env-derived): the executable the engine drives stays engine code
+     * regardless of which Chromium launches. Tests inject a failing
+     * launcher to prove the fail-closed path (E16); production leaves it
+     * unset for the pinned Chromium.
+     */
+    engineBrowserLauncher?: import('./browser.js').EngineBrowserLauncher;
+    /**
+     * Trusted fixture/actor provider (plan 2026-09-19 §4.5, Phase 4):
+     * injected by the trusted controller harness (engine-owned bundle),
+     * never by suite code. Null (default) means strong behavior cases
+     * block with a missing-provider cause — suite-supplied fixtures are
+     * never a fallback.
+     */
+    fixtureProvider?: import('./fixture-provider.js').FixtureProvider | null;
+    /**
+     * Engine-owned queue channel: the
+     * witness's own read of a background queue plus the write side that
+     * produces the deliveries it grades. Null (default) means the
+     * repository declares no `queueObserver`, so every `engine-task` case
+     * blocks with a naming cause — never a suite-supplied substitute.
+     */
+    queueChannel?: import('../queue/observer.js').QueueChannel | null;
+}
+/**
+ * The normalized adapter module contract (pin #8).
+ *
+ * `probeServer` (optional; the server-witnessed persistence channel) is
+ * the adapter's server-side probe: the witness executes it ONLY in the
+ * witness process (trusted side) against the app's own database/state —
+ * for backend-only tables (a transactional outbox) that can never
+ * honestly appear in a UI. Contract:
+ *
+ * ```js
+ * export default {
+ *   ...,
+ *   async probeServer(ctx, subject) {
+ *     const row = await db.query('select * from outbox where id = $1', [subject]);
+ *     return { found: row !== undefined, fields: row ?? null };
+ *   },
+ * };
+ * ```
+ *
+ * `subject` is the entity key EXACTLY as the persistence intent declared
+ * it (scalar for single-column primary keys, column-keyed object for
+ * composite keys); the return MUST be
+ * `{found: boolean, fields: Record<string, unknown> | null}`. A throw or
+ * a malformed shape resolves the intent as a typed
+ * SERVER_PROBE_UNAVAILABLE failure — never to satisfaction (fail
+ * closed). Adapters without the export simply cannot serve the server
+ * channel; the browser path is unaffected.
+ */
+export interface EvidenceAdapter {
+    /** GET-only transport. Returns the raw entity body, or null when absent. */
+    read: (ctx: AdapterContext, id: unknown) => Promise<unknown> | unknown;
+    /**
+     * Optional GET-only listing of the resource's entities (raw bodies).
+     * Powers engine-side pre-observations for create postconditions; when
+     * absent the witness refuses pre-observations for the resource.
+     */
+    list?: (ctx: AdapterContext) => Promise<unknown[]> | unknown[];
+    /** Enables entity-scoped create absence checks without a collection list. */
+    identity?: 'natural-key';
+    /** Declares normalized fields the adapter projects for persistence evidence. */
+    fields?: readonly string[];
+    /**
+     * Declares fields the SERVER computes on its own (a derived label, a
+     * server-side normalization, a counter). The engine skips the
+     * exact-value echo for exactly these keys and REPORTS the skip — a
+     * server-changed field is a declared fact about the app, never a
+     * silently ignored mismatch. Absent on every hand-written adapter
+     * that does not declare one (the previous behavior, unchanged).
+     */
+    volatileFields?: readonly string[];
+    /** Projects the raw body onto {entityId, fields} — stamped from the RESPONSE. */
+    normalize: (body: unknown) => {
+        entityId: unknown;
+        fields: unknown;
+    };
+    /** Removal semantics the adapter's resource uses. */
+    deletion: 'hard' | 'archive';
+    /** Fingerprint the adapter's target environment must present. */
+    environmentFingerprint: string;
+    /** Optional base override for THIS adapter's reads. */
+    baseUrl?: string;
+    /**
+     * Optional SERVER PROBE, executed witness-side only (see the interface
+     * doc): observes the app database directly and reports the entity's
+     * presence + observed column state.
+     */
+    probeServer?: (ctx: AdapterContext, subject: unknown) => Promise<ServerProbeResult> | ServerProbeResult;
+    /**
+     * Optional OBSERVE binding (Observe channel, Phase 2): declares which
+     * proxied HTTP exchanges count as mutations of this resource when a
+     * suite-driven browser test runs. Each declared operation names the
+     * method + backend-facing path template; `{id}` marks the single
+     * segment carrying the entity id (required on read/update/delete,
+     * forbidden on create — a create id comes from the response the
+     * witness proxied, verified against the list-diff). Only
+     * declared operations are observe-eligible; anything else grades
+     * typed-missing. Observe additionally requires `list` (before-
+     * snapshots); an adapter without it can serve no observe obligation.
+     */
+    observe?: ObserveBinding;
+    /**
+     * Optional TRUSTED scope observation (plan 2026-09-19 §4.4, Phase 4):
+     * observes an independently controlled state source (read-only
+     * database credentials, a trusted state sidecar, or equivalent
+     * owner-provisioned observer outside candidate code) for one approved
+     * scope key within one fixture namespace. Reading only the
+     * candidate's own GET handler is insufficient for the protected
+     * profile. Adapters lacking this method still serve legacy proofs;
+     * they cannot satisfy strong contracts requiring scoped observation.
+     */
+    snapshotScope?: (ctx: AdapterContext, input: SnapshotScopeInput) => Promise<ScopeSnapshot> | ScopeSnapshot;
+    /**
+     * Optional completion-barrier observer (plan 2026-09-19 §4.4): waits
+     * for a real completion/queue checkpoint for an engine-issued
+     * operation. An observer, not a state maker: it must not sleep-then-
+     * true, mutate state, or return true on timeout.
+     */
+    awaitBarrier?: (ctx: AdapterContext, input: BarrierInput) => Promise<{
+        complete: boolean;
+        checkpoint: string;
+    }> | {
+        complete: boolean;
+        checkpoint: string;
+    };
+}
+/**
+ * One observe-eligible mutation shape: the HTTP method (uppercase) and
+ * the backend-facing path template. `{id}` matches exactly one non-
+ * empty path segment and binds the entity id for read/update/delete.
+ * A read may instead declare `collection`, naming its entities in the
+ * returned rows instead of in the path.
+ */
+export interface ObserveMutation {
+    /** Concrete uppercase HTTP method, e.g. `'POST'`. */
+    method: string;
+    /** Backend-facing absolute path, e.g. `'/api/v2/accounts/{id}'`. */
+    path: string;
+    /**
+     * Optional COLLECTION read declaration (read + GET only): the
+     * entities this operation names come from the returned rows of the
+     * response the witness proxied, resolved against the witness's own
+     * session-open snapshot. Forbidden on create/update/delete and on
+     * any read whose path carries `{id}`; absent, the read keeps binding
+     * `{id}` from the path exactly as before.
+     */
+    collection?: ObserveCollection;
+}
+/**
+ * The COLLECTION shape of an observe read: the response the real UI
+ * rendered lists its entities, so the entity ids come from the rows
+ * themselves rather than from a path template. `rowsKey` names the
+ * object property holding the row array; omitting it declares that the
+ * response ROOT is the row array. `idKey` names the row property
+ * carrying the entity id — the only field the witness reads out of a
+ * returned row.
+ *
+ * Declared, never inferred: an adapter whose read binding carries no
+ * `collection` keeps the by-`{id}` behavior unchanged.
+ */
+export interface ObserveCollection {
+    /** Property holding the row array; absent = the root is the array. */
+    rowsKey?: string;
+    /** Row property carrying the entity id. */
+    idKey: string;
+}
+/** Per-operation observe bindings for one resource adapter. */
+export interface ObserveBinding {
+    create?: ObserveMutation;
+    read?: ObserveMutation;
+    update?: ObserveMutation;
+    delete?: ObserveMutation;
+}
+/** The shape an adapter `probeServer` must return (validated witness-side). */
+export interface ServerProbeResult {
+    /** Whether the probed entity exists in the engine-observed state. */
+    found: boolean;
+    /** The observed column state when found (null when absent). */
+    fields: Record<string, unknown> | null;
+}
+/** `POST /runs/behavior-catalog` request (supervisor only, one-time bind). */
+export interface BehaviorCatalogRequest {
+    /** Compiled behavior catalog (validated against the core schema). */
+    catalog: unknown;
+    /**
+     * Allowed case/test assignments: testId → required case ids the
+     * supervisor permits that test to execute. Every case id must exist
+     * in the catalog; every id must belong to an obligation the mapping
+     * already claims (checked by the supervisor before sending).
+     */
+    assignments: Record<string, string[]>;
+    /**
+     * Complete route inventory for principal attribution (resourceId,
+     * method, canonicalPath per route, sorted). The grader re-resolves
+     * every attempt against this exact set — never a claim or payload.
+     */
+    routes: unknown;
+    /**
+     * Authority profile digest the witness seals into every case record
+     * (engine bundle binding, provisioned by the trusted controller).
+     */
+    authorityProfileDigest: string;
+}
+/** `POST /runs/behavior-catalog` response. */
+export interface BehaviorCatalogResponse {
+    bound: true;
+    caseCount: number;
+    assignmentCount: number;
+    routeCount: number;
+}
+/** `POST /behavior/execute` request: exactly these keys, nothing else. */
+export interface BehaviorExecuteRequest {
+    sessionId: string;
+    sessionToken: string;
+    caseId: string;
+}
+/**
+ * `POST /behavior/execute` response: a REDACTED result reference. Actor
+ * credential material, fixture subjects, and expectations never appear
+ * here — the worker may name an allowed case but can never read or
+ * override actor credentials, expectations, before-state, or origin.
+ */
+export interface BehaviorExecuteResponse {
+    caseId: string;
+    executionId: string;
+    /** Isolated fixture namespace for this execution. */
+    namespace: string;
+    /** Authoritative before checkpoint (empty until the principal runs). */
+    beforeCheckpoint: string | null;
+    /** Lifecycle state after this call. */
+    state: string;
+}
+/** `POST /behavior/principal` request: drive the principal operation. */
+export interface BehaviorPrincipalRequest {
+    sessionId: string;
+    sessionToken: string;
+    executionId: string;
+}
+/**
+ * `POST /behavior/principal` response: redacted seal reference. The
+ * witness-owned driver executed, the barrier resolved, after-state was
+ * observed, and the `behavior.case` record(s) were issued — grading
+ * happens core-side, never here.
+ */
+export interface BehaviorPrincipalResponse {
+    caseId: string;
+    executionId: string;
+    recordIds: string[];
+    state: string;
+}
+/** Witness-side lifecycle state of one required-case execution. */
+export type CaseExecutionState = 'fixture-prepared' | 'before-snapshot-complete' | 'principal-executing' | 'principal-captured' | 'barrier-reached' | 'after-snapshot-complete' | 'sealed' | 'failed';
+/** One entity inside a trusted scope snapshot. */
+export interface SnapshotEntity {
+    /**
+     * Entity identity: scalar for single-column keys, complete
+     * column-keyed object for composite keys (matching core identity
+     * behavior). Unknown identity blocks the case.
+     */
+    entityId: unknown;
+    /** Projected field map (exactly the declared scope fields). */
+    fields: Record<string, unknown>;
+}
+/**
+ * Strict trusted scope snapshot (plan 2026-09-19 §4.4): data, never a
+ * verdict. `complete:false`, pagination not exhausted, omitted declared
+ * fields, unknown identity, inconsistent checkpoints, or size-limit
+ * truncation blocks the case — the harness never silently samples.
+ */
+export interface ScopeSnapshot {
+    /** Approved snapshot scope key. */
+    scope: string;
+    /** Fixture namespace actually observed (must equal the case lease). */
+    fixtureNamespace: string;
+    /** False when collection is partial for any reason. */
+    complete: boolean;
+    /** Authoritative checkpoint (before/after comparison + barriers). */
+    checkpoint: string;
+    /** Entities in canonical order (duplicate identity rejected). */
+    entities: SnapshotEntity[];
+    /** True when pagination was exhausted (absent = unknown = incomplete). */
+    exhausted?: boolean;
+    /** Total size when the scope enforces a limit (truncation blocks). */
+    totalSize?: number;
+}
+/** Input to an adapter `snapshotScope` observation. */
+export interface SnapshotScopeInput {
+    /** Approved snapshot scope key. */
+    scope: string;
+    /** Fixture namespace to observe (never the whole database). */
+    fixtureNamespace: string;
+}
+/** Input to an adapter `awaitBarrier` observation. */
+export interface BarrierInput {
+    /** Approved snapshot scope key. */
+    scope: string;
+    /** Fixture namespace to observe. */
+    fixtureNamespace: string;
+    /** Engine-issued operation id awaiting completion. */
+    operationId: string;
+    /** Hard deadline in milliseconds (timeout is failure, not success). */
+    deadlineMs: number;
+}
+/** The transport handed to `read` (GET-only, engine-mediated). */
+/**
+ * A per-session adapter identity (plan 2026-09-25 Phase 4b item 3b):
+ * the credential one OPEN session registered for ITSELF through
+ * `POST /sessions/identity`, so an adapter read that must happen inside a
+ * tenant the test just created can run as that tenant.
+ *
+ * It changes WHO the engine reads as — nothing else. The engine still
+ * performs every read; a wrong tenant simply makes the row unfound
+ * (the app answers 403/404 and the entity grades absent), so the failure
+ * mode is a closed door, never an open verdict. The values live in
+ * witness memory for the length of the session and are never written to
+ * a record, the run state, a log or a report.
+ */
+export interface SessionIdentity {
+    /** The adapter seat this identity serves (must be a declared seat). */
+    readonly seat: string;
+    /**
+     * The seat's credential VALUES, keyed by the same witness environment
+     * variable names the seat declares (`auth.seats.<seat>.credentials`
+     * maps login field to env var). Every variable the seat declares must
+     * be present: a partial identity fails closed instead of silently
+     * completing itself from the process-global seat.
+     */
+    readonly values: Readonly<Record<string, string>>;
+}
+/** `POST /sessions/identity` request (session-authenticated). */
+export interface SessionIdentityRequest extends SessionIdentity {
+    /** The session the identity belongs to (its own, never another's). */
+    sessionId: string;
+    /** The session's witness-issued secret; authorizes this call alone. */
+    sessionToken: string;
+}
+/**
+ * `POST /sessions/identity` response. It echoes the SEAT NAME only — the
+ * credential itself never leaves the witness process.
+ */
+export interface SessionIdentityResponse {
+    registered: true;
+    seat: string;
+}
+/** The transport handed to `read` (GET-only, engine-mediated). */
+export interface AdapterContext {
+    /**
+     * The supervisor-opened session this read runs under, when the caller
+     * is a test session (absent for engine-driven and probe reads). It is
+     * what a {@link SessionIdentity} is scoped to.
+     */
+    sessionId?: string;
+    /**
+     * The identity THAT session registered for itself, or null. Present
+     * only while the read belongs to the registering session.
+     */
+    sessionIdentity?: SessionIdentity | null;
+    /** The resolved read base for this adapter. */
+    baseUrl: string;
+    /** The resource this adapter serves. */
+    resourceId: string;
+    /**
+     * The ONLY outbound primitive available to adapters: a GET returning
+     * a minimal response view (status + JSON/text body + headers).
+     */
+    get: (path: string) => Promise<{
+        status: number;
+        json(): Promise<unknown>;
+        text(): Promise<string>;
+        headers: Headers;
+    }>;
+    /**
+     * Headers adapters MUST attach to any direct fetch they perform
+     * instead of `get` (dogfood, 2026-09-05): carries the operator-issued
+     * engine read credential (`WitnessOptions.adapterReadAuthorization`)
+     * so engine-side GET-only state observation can authenticate against
+     * the app's own collection routes. Never suite-supplied, never
+     * attached to browser traffic.
+     */
+    headers?: Record<string, string>;
+}
+/** Full witness-issued record (superset of the pinned wire response). */
+export type IssuedRecord = EvidenceRecord;
+/** Result of spawning/attaching a witness service. */
+export interface WitnessHandle {
+    /** Base URL (loopback, OS-assigned port). */
+    url: string;
+    /** Stop the server; appends issued recordIds to the run manifest (pin #4/#7). */
+    proxyUrl: string | null;
+    stop: () => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map