@gate-forge/pack-playwright 0.4.0 → 0.6.0

package/dist/witness/server.js

@@ -28,6 +28,8 @@
  * | `GET /ledger-attestation`         | run token + verifier key (supervisor)   |
  * | `POST /runs/expected-set`         | run token + verifier key (supervisor)   |
  * | `POST /runs/server-e2e-declarations` | run token + verifier key (supervisor)|
+  * | `POST /runs/observe-declarations` | run token + verifier key (supervisor)   |
+  * | `POST /observe/finalize`      | run token + verifier key (supervisor)   |
  * | `POST /witness/server-persistence` | run token + verifier key (supervisor;  |
  * |                                   | the drain forwards intents — the suite |
  * |                                   | can only WRITE spool lines)            |
@@ -88,6 +90,15 @@
  *   outbox) that can never honestly appear in a UI. Probes run ONLY in
  *   this trusted process; missing adapter/probe/declaration and replayed
  *   sequences resolve to typed failures, never to satisfaction.
+  * - `POST /runs/observe-declarations` — SUPERVISOR ONLY: registers the
+  *   `observed-e2e` obligations BEFORE the run (same bind-once contract
+  *   as the server-e2e set).
+  * - `POST /observe/finalize` — SUPERVISOR ONLY: resolves one OPEN
+  *   session's observe-declared claims against its own proxied traffic
+  *   plus independent adapter reads; stamps witnessed
+  *   `persistence.observed` records (`channel: 'observe'`) for whatever
+  *   resolves. Non-resolutions are typed notes — never satisfaction,
+  *   never a run failure.
  * - `POST /witness/http-observation` — consumes one engine-observed
  *   proxied exchange for an http:* claim. Phase 1: the caller must hold
  *   a valid OPEN session and the exchange must have been observed
@@ -114,16 +125,18 @@ import { createServer, request } from 'node:http';
 import { createHash, randomUUID } from 'node:crypto';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { ATTESTATION_VERSION, attestationMac, enumerationDigestOf, recordIdOf, } from '@gate-forge/core';
+import { ATTESTATION_VERSION, attestationMac, behaviorActionDigestOf, BehaviorCatalogSchema, BEHAVIOR_CASE_KIND, enumerationDigestOf, interpretObservedPath, pathMatchesShape, recordIdOf, resolveHttpRoute, } from '@gate-forge/core';
 import { canonicalOf } from '../json.js';
-import { DEFAULT_REQUEST_TIMEOUT_MS, KNOWN_RECORD_KINDS, LOOPBACK_HOSTNAME, PERSISTENCE_KIND, RUN_HEADER, VERIFIER_HEADER, } from '../constants.js';
+import { DEFAULT_REQUEST_TIMEOUT_MS, KNOWN_RECORD_KINDS, LOOPBACK_HOSTNAME, OBSERVED_KIND, PERSISTENCE_KIND, RUN_HEADER, VERIFIER_HEADER, } from '../constants.js';
 import { loadAdapters, makeAdapterContext } from './adapter-registry.js';
 import { AttestationError, assertLoopback, envFingerprintMismatch, probeEnvFingerprint, } from './env-attestation.js';
 import { hostResolverRules, pinnedLoopbackIps, pinnedGet } from './loopback-pins.js';
 import { loadClassifications, toClassificationView } from './classifications.js';
 import { EngineBrowserError, EngineBrowserManager, driveEngineAction, readEngineVisible, } from './browser.js';
 import { SURFACE_DESCRIPTOR_VERSION, validateSurface, } from '../surface.js';
-import { SERVER_CHANNEL, SERVER_E2E_TEST_KIND } from '../constants.js';
+import { validateScopeSnapshot } from './behavior.js';
+import { BEHAVIOR_BODY_LIMIT_BYTES, BehaviorDriverError, driveBehaviorRequest } from './behavior-request.js';
+import { OBSERVE_CHANNEL, OBSERVED_E2E_TEST_KIND, SERVER_CHANNEL, SERVER_E2E_TEST_KIND } from '../constants.js';
 const MAX_BODY_BYTES = 1024 * 1024;
 const OBLIGATION_ID_PATTERN = /^[^:]+:.+$/;
 /**
@@ -133,6 +146,16 @@ const OBLIGATION_ID_PATTERN = /^[^:]+:.+$/;
  * streams to the browser unbuffered — the snapshot is a tap, not a gate.
  */
 const OBSERVED_BODY_SNAPSHOT_BYTES = 16384;
+/**
+ * Bounded request-body snapshot the observation proxy keeps per
+ * forwarded exchange (Observe channel, Phase 2): the request body is
+ * already buffered for forwarding, so retaining a capped copy costs one
+ * slice. Bodies beyond the cap are flagged truncated — an observe
+ * finalize can never echo what it cannot see, so oversized intents
+ * grade typed-missing instead of satisfying on a prefix. Binary-safe:
+ * stored raw; the finalize path parses JSON/form text from it.
+ */
+const OBSERVED_REQUEST_BODY_BYTES = 65536;
 /** Fail-closed witness configuration/startup error. */
 export class WitnessStartupError extends Error {
     constructor(message) {
@@ -179,6 +202,19 @@ function normalizeMountPath(raw) {
     }
     return path;
 }
+/**
+ * Lowercases a request content-type header to its media type without
+ * parameters (`'Application/JSON; charset=utf-8'` → `'application/json'`),
+ * or null when absent/unparseable. The Observe finalize path uses it to
+ * decide body parsing (JSON vs form); anything else is ineligible.
+ */
+function contentTypeOf(raw) {
+    const first = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof first !== 'string')
+        return null;
+    const media = first.split(';')[0]?.trim().toLowerCase() ?? '';
+    return media.length > 0 ? media : null;
+}
 /**
  * Strips the declared mount prefix from a proxied request URL (path
  * plus possible query/fragment), returning the backend-facing URL the
@@ -284,6 +320,10 @@ async function startObservedProxy(state, sessionId) {
                         seq: (state.observedSeq += 1),
                         bodySha256: createHash('sha256').update(Buffer.concat(snapshot)).digest('hex'),
                         bodyBytes: totalBytes,
+                        requestBody: body.length === 0 ? null : Buffer.from(body.subarray(0, OBSERVED_REQUEST_BODY_BYTES)),
+                        requestTruncated: body.length > OBSERVED_REQUEST_BODY_BYTES,
+                        requestBytes: body.length,
+                        requestContentType: contentTypeOf(req.headers['content-type']),
                         sessionId,
                         tick: (state.tick += 1),
                     });
@@ -464,6 +504,8 @@ export async function startWitness(options) {
         serverE2eDeclarations: null,
         serverPreObservations: new Map(),
         serverIntentSequences: new Map(),
+        observeDeclarations: null,
+        observeSnapshots: new Map(),
         observed: [],
         observedSeq: 0,
         runContext: null,
@@ -471,6 +513,8 @@ export async function startWitness(options) {
         proxyInFlight: 0,
         expectedTests: new Map(),
         enumerationDigest: null,
+        behaviorCatalog: null,
+        caseExecutions: new Map(),
         tick: 0,
         sessions: new Map(),
         workerSessions: new Map(),
@@ -890,6 +934,14 @@ async function handleBrowserAction(state, res, body) {
                 seq: (state.observedSeq += 1),
                 bodySha256: createHash('sha256').update(exchange.body).digest('hex'),
                 bodyBytes: exchange.body.length,
+                // Engine-captured exchanges carry no request body (the engine
+                // typed the input; entered fields ride the ui.action record) —
+                // they can never serve an observe finalize, which requires the
+                // proxied request bytes.
+                requestBody: null,
+                requestTruncated: false,
+                requestBytes: 0,
+                requestContentType: null,
                 sessionId: session.sessionId,
                 tick: (state.tick += 1),
             });
@@ -1040,10 +1092,30 @@ async function handleRequest(state, req, res) {
             await handleExpectedSet(state, res, req.headers[VERIFIER_HEADER], (await readBody(req)));
             return;
         }
+        if (req.method === 'POST' && path === '/runs/behavior-catalog') {
+            await handleBehaviorCatalog(state, res, req.headers[VERIFIER_HEADER], (await readBody(req)));
+            return;
+        }
+        if (req.method === 'POST' && path === '/behavior/execute') {
+            await handleBehaviorExecute(state, res, (await readBody(req)));
+            return;
+        }
+        if (req.method === 'POST' && path === '/behavior/principal') {
+            await handleBehaviorPrincipal(state, res, (await readBody(req)));
+            return;
+        }
         if (req.method === 'POST' && path === '/runs/server-e2e-declarations') {
             await handleServerE2eDeclarations(state, res, req.headers[VERIFIER_HEADER], (await readBody(req)));
             return;
         }
+        if (req.method === 'POST' && path === '/runs/observe-declarations') {
+            await handleObserveDeclarations(state, res, req.headers[VERIFIER_HEADER], (await readBody(req)));
+            return;
+        }
+        if (req.method === 'POST' && path === '/observe/finalize') {
+            await handleObserveFinalize(state, res, req.headers[VERIFIER_HEADER], (await readBody(req)));
+            return;
+        }
         if (req.method === 'GET' && path === '/runs/execution-trace') {
             requireSupervisor(state, req.headers[VERIFIER_HEADER]);
             sendJson(res, 200, executionTraceOf(state));
@@ -1231,6 +1303,653 @@ async function handleExpectedSet(state, res, verifier, body) {
     state.enumerationDigest = digest;
     sendJson(res, 200, { bound: true, enumerationDigest: digest, count: state.expectedTests.size });
 }
+/**
+ * Binds the compiled behavior catalog plus allowed case/test assignments
+ * (plan 2026-09-19 §4.7, Phase 4): supervisor-only, one-time, before any
+ * session opens. The worker can never register a catalog or assign
+ * itself cases — `/behavior/execute` resolves everything from this
+ * binding.
+ */
+async function handleBehaviorCatalog(state, res, verifier, body) {
+    requireSupervisor(state, verifier);
+    if (!isPlainObject(body) || !('catalog' in body) || !isPlainObject(body['assignments'])) {
+        throw new HttpError(400, 'behavior-catalog body must be {catalog, assignments: {testId: [caseId, ...]}, routes: [...], authorityProfileDigest}');
+    }
+    const parsed = BehaviorCatalogSchema.safeParse(body['catalog']);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const path = issue === undefined ? '' : ` at '${issue.path.map(String).join('.')}':`;
+        throw new HttpError(400, `behavior catalog is invalid${path} ${issue?.message ?? 'unknown schema error'}`);
+    }
+    const catalog = parsed.data;
+    const rawRoutes = body['routes'];
+    if (!Array.isArray(rawRoutes) || rawRoutes.length === 0) {
+        throw new HttpError(400, 'behavior-catalog routes must be the non-empty complete route inventory — principal attribution needs every applicable route (no any-endpoint fallback)');
+    }
+    const routes = [];
+    for (let index = 0; index < rawRoutes.length; index += 1) {
+        const row = rawRoutes[index];
+        if (typeof row !== 'object' ||
+            row === null ||
+            typeof row['resourceId'] !== 'string' ||
+            row['resourceId'].length === 0 ||
+            typeof row['method'] !== 'string' ||
+            row['method'].length === 0 ||
+            typeof row['canonicalPath'] !== 'string' ||
+            row['canonicalPath'].length === 0) {
+            throw new HttpError(400, `behavior-catalog routes[${String(index)}] must be {resourceId, method, canonicalPath}`);
+        }
+        routes.push({
+            resourceId: row['resourceId'],
+            method: row['method'].toUpperCase(),
+            canonicalPath: row['canonicalPath'],
+        });
+    }
+    routes.sort((a, b) => (a.resourceId < b.resourceId ? -1 : a.resourceId > b.resourceId ? 1 : 0));
+    const authorityProfileDigest = body['authorityProfileDigest'];
+    if (typeof authorityProfileDigest !== 'string' || !/^[0-9a-f]{64}$/.test(authorityProfileDigest)) {
+        throw new HttpError(400, 'behavior-catalog authorityProfileDigest must be 64-char lowercase hex');
+    }
+    // Approved surface descriptors (Phase 6): optional map of surface key
+    // to descriptor. Each descriptor is structurally validated NOW —
+    // worker-supplied surfaces are never resolved at drive time.
+    const surfaces = new Map();
+    const rawSurfaces = body['surfaces'];
+    if (rawSurfaces !== undefined) {
+        if (!isPlainObject(rawSurfaces)) {
+            throw new HttpError(400, 'behavior-catalog surfaces must be a map of surface key to descriptor');
+        }
+        for (const [surfaceKey, descriptor] of Object.entries(rawSurfaces)) {
+            if (surfaceKey.length === 0) {
+                throw new HttpError(400, 'behavior-catalog surface keys must be non-empty');
+            }
+            try {
+                surfaces.set(surfaceKey, validateSurface(descriptor));
+            }
+            catch (error) {
+                throw new HttpError(400, `behavior-catalog surface '${surfaceKey}' is invalid: ${error.message}`);
+            }
+        }
+    }
+    const assignments = new Map();
+    for (const [testId, ids] of Object.entries(body['assignments'])) {
+        if (testId.length === 0 || !Array.isArray(ids) || ids.length === 0 || !ids.every((id) => typeof id === 'string')) {
+            throw new HttpError(400, `behavior-catalog assignment for test '${testId}' must be a non-empty array of case ids`);
+        }
+        const resolved = new Set();
+        for (const id of ids) {
+            const found = catalog.cases.find((item) => item.caseId === id);
+            if (found === undefined) {
+                throw new HttpError(400, `behavior-catalog assignment for test '${testId}' names unknown case '${id}' — cases resolve by canonical case id only`);
+            }
+            resolved.add(found.caseId);
+        }
+        assignments.set(testId, resolved);
+    }
+    if (state.behaviorCatalog !== null) {
+        if (state.behaviorCatalog.catalogDigest === catalog.catalogDigest) {
+            const response = {
+                bound: true,
+                caseCount: catalog.cases.length,
+                assignmentCount: assignments.size,
+                routeCount: routes.length,
+            };
+            sendJson(res, 200, response);
+            return;
+        }
+        sendJson(res, 409, {
+            error: 'a behavior catalog is already bound to this run and differs; the catalog is a PRE-run ' +
+                'fact and is never relabeled — start a fresh witness for a new invocation',
+        });
+        return;
+    }
+    if (state.sessions.size > 0) {
+        sendJson(res, 409, {
+            error: 'sessions were already opened on this witness; the behavior catalog must be registered ' +
+                'BEFORE the run — start a fresh witness for a new invocation',
+        });
+        return;
+    }
+    state.behaviorCatalog = { catalog, catalogDigest: catalog.catalogDigest, assignments, routes, authorityProfileDigest, surfaces };
+    const response = {
+        bound: true,
+        caseCount: catalog.cases.length,
+        assignmentCount: assignments.size,
+        routeCount: routes.length,
+    };
+    sendJson(res, 200, response);
+}
+/**
+ * Executes one required behavior case through the witness-owned lifecycle
+ * (plan 2026-09-19 §4.6, Phase 4): the worker names an allowed caseId and
+ * nothing else. Actor credentials, expectations, before-state, and origin
+ * resolve from the supervisor-bound catalog and the trusted fixture
+ * provider — input/actor overrides are request errors, never proof.
+ *
+ * Phase 4 executes fixture preparation plus the authoritative before
+ * snapshot; the principal operation driver lands in Phase 5, so a
+ * successful call leaves the execution at `before-snapshot-complete`
+ * with a redacted reference (no credentials, no subjects).
+ */
+async function handleBehaviorExecute(state, res, body) {
+    if (!isPlainObject(body)) {
+        throw new HttpError(400, 'behavior/execute body must be {sessionId, sessionToken, caseId}');
+    }
+    const keys = Object.keys(body).sort();
+    if (keys.length !== 3 || keys[0] !== 'caseId' || keys[1] !== 'sessionId' || keys[2] !== 'sessionToken') {
+        throw new HttpError(400, 'behavior/execute accepts exactly {sessionId, sessionToken, caseId} — unknown keys are errors; ' +
+            'a worker can name an allowed case but cannot post actor credentials, expectations, or origin');
+    }
+    const caseId = body['caseId'];
+    if (typeof caseId !== 'string' || caseId.length === 0) {
+        throw new HttpError(400, 'behavior/execute requires a non-empty string caseId');
+    }
+    const binding = state.behaviorCatalog;
+    if (binding === null) {
+        throw new HttpError(409, 'no behavior catalog is bound to this run — register POST /runs/behavior-catalog before the run');
+    }
+    const session = requireOpenSession(state, body);
+    const compiled = binding.catalog.cases.find((item) => item.caseId === caseId);
+    if (compiled === undefined) {
+        throw new HttpError(400, `behavior/execute names unknown case '${caseId}' — cases resolve by canonical case id only`);
+    }
+    const allowed = binding.assignments.get(session.testId);
+    if (allowed === undefined || !allowed.has(compiled.caseId)) {
+        throw new HttpError(403, `case '${compiled.definition.id}' is not assigned to test '${session.testId}' — a test executes only its own allowed cases`);
+    }
+    if (state.caseExecutions.has(compiled.caseId)) {
+        throw new HttpError(409, `case '${compiled.definition.id}' was already executed in this run — one execution per required case per run`);
+    }
+    const provider = state.options.fixtureProvider ?? null;
+    if (provider === null) {
+        throw new HttpError(409, 'no trusted fixture provider is configured — strong behavior cases block (suite-supplied fixtures are never a fallback)');
+    }
+    let lease;
+    try {
+        lease = await provider.prepare({
+            recipe: compiled.definition.fixture,
+            runId: state.options.runId,
+            caseId: compiled.caseId,
+        });
+    }
+    catch (error) {
+        throw new HttpError(500, `fixture preparation failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (lease === null ||
+        typeof lease !== 'object' ||
+        typeof lease.namespace !== 'string' ||
+        lease.namespace.length === 0) {
+        try {
+            await provider.release(lease?.leaseId ?? 'unknown');
+        }
+        catch {
+            // Release is best-effort; the preparation failure below is the verdict.
+        }
+        throw new HttpError(500, 'fixture preparation returned a malformed lease (fail closed)');
+    }
+    const executionId = randomUUID();
+    const execution = {
+        executionId,
+        caseId: compiled.caseId,
+        testId: session.testId,
+        sessionId: session.sessionId,
+        state: 'fixture-prepared',
+        lease: lease,
+        beforeSnapshots: [],
+        beforeCheckpoints: {},
+        detail: null,
+    };
+    state.caseExecutions.set(compiled.caseId, execution);
+    const failExecution = (detail) => {
+        execution.state = 'failed';
+        execution.detail = detail;
+        // Namespace cleanup runs on errors without changing the verdict.
+        // Fire-and-forget with a floor: the thrown error carries the failure.
+        void Promise.resolve(provider.release(execution.lease.leaseId)).catch(() => { });
+        return new HttpError(409, detail);
+    };
+    // Authoritative before snapshots over every declared effect scope. Any
+    // incomplete collection fails the execution with a diagnostic fact —
+    // never a satisfying observation.
+    const checkpoints = {};
+    for (const effect of compiled.effects) {
+        const adapter = state.adapters.get(effect.adapter);
+        if (adapter === undefined) {
+            throw failExecution(`observation incomplete: no reviewed adapter '${effect.adapter}' for scope '${effect.scope}' (OBSERVATION_SCOPE_INCOMPLETE)`);
+        }
+        if (typeof adapter.snapshotScope !== 'function') {
+            throw failExecution(`observation incomplete: adapter '${effect.adapter}' cannot observe scope '${effect.scope}' — snapshotScope is unavailable (OBSERVATION_SCOPE_INCOMPLETE)`);
+        }
+        const baseUrl = adapter.baseUrl ?? state.options.adapterBaseUrl ?? state.options.targetBaseUrl ?? '';
+        const ctx = makeAdapterContext(baseUrl, effect.resourceId, () => {
+            throw new Error('snapshot observations must not use the candidate GET transport');
+        }, state.options.adapterReadAuthorization
+            ? { authorization: state.options.adapterReadAuthorization }
+            : undefined);
+        let snapshot;
+        try {
+            snapshot = await adapter.snapshotScope(ctx, { scope: effect.scope, fixtureNamespace: execution.lease.namespace });
+        }
+        catch (error) {
+            throw failExecution(`observation incomplete: scope '${effect.scope}' collection failed: ${error instanceof Error ? error.message : String(error)} (OBSERVATION_SCOPE_INCOMPLETE)`);
+        }
+        const validated = validateScopeSnapshot(snapshot, {
+            scope: effect.scope,
+            fixtureNamespace: execution.lease.namespace,
+            identityFields: effect.identityFields,
+            fields: effect.fields,
+        });
+        if (!validated.ok) {
+            throw failExecution(`observation incomplete: ${validated.detail} (OBSERVATION_SCOPE_INCOMPLETE)`);
+        }
+        checkpoints[effect.scope] = validated.snapshot.checkpoint;
+        execution.beforeSnapshots.push(snapshot);
+    }
+    execution.beforeCheckpoints = checkpoints;
+    execution.state = 'before-snapshot-complete';
+    const firstCheckpoint = Object.values(checkpoints).sort()[0] ?? null;
+    const response = {
+        caseId: compiled.caseId,
+        executionId,
+        namespace: execution.lease.namespace,
+        beforeCheckpoint: firstCheckpoint,
+        state: execution.state,
+    };
+    sendJson(res, 200, response);
+}
+/**
+ * Drives one surface action through the engine-owned browser (plan
+ * 2026-09-19 Phase 6): resolves the surface descriptor from the
+ * supervisor-bound bundle (never a worker object), resolves
+ * subject/fields from the trusted lease, drives with the existing
+ * engine browser drivers, and reads the rendered result back itself.
+ * Error banners, navigation, and state checks are engine observations —
+ * never inferred from test source.
+ */
+async function driveSurfacePrincipal(state, binding, execution, compiled, action, failExecution, session) {
+    const descriptor = binding.surfaces.get(action.surface);
+    if (descriptor === undefined) {
+        throw failExecution(`surface '${action.surface}' has no approved descriptor in the bound bundle — strong cases resolve surfaces from the approved bundle, not worker objects (BEHAVIOR_BINDING_MISMATCH)`);
+    }
+    if (action.files !== undefined && Object.keys(action.files).length > 0) {
+        throw failExecution('surface file inputs need fixture file materialization, unsupported in this profile — declare the upload as an explicit engine-http multipart case or omit files (OBSERVATION_SCOPE_INCOMPLETE)');
+    }
+    const resolveField = (raw, what) => {
+        if (raw.from === 'literal') {
+            if (typeof raw.value !== 'string') {
+                throw failExecution(`surface ${what} literal must be a string (BEHAVIOR_BINDING_MISMATCH)`);
+            }
+            return raw.value;
+        }
+        if (raw.from === 'fixture' && typeof raw.key === 'string') {
+            const segments = raw.key.split('.');
+            let current = execution.lease.subjects;
+            for (const segment of segments) {
+                if (typeof current !== 'object' || current === null || Array.isArray(current)) {
+                    throw failExecution(`surface ${what} fixture key '${raw.key}' does not resolve (BEHAVIOR_BINDING_MISMATCH)`);
+                }
+                if (!Object.prototype.hasOwnProperty.call(current, segment)) {
+                    throw failExecution(`surface ${what} fixture key '${raw.key}' does not resolve (BEHAVIOR_BINDING_MISMATCH)`);
+                }
+                current = current[segment];
+            }
+            if (typeof current !== 'string') {
+                throw failExecution(`surface ${what} fixture key '${raw.key}' is not a string (BEHAVIOR_BINDING_MISMATCH)`);
+            }
+            return current;
+        }
+        throw failExecution(`surface ${what} uses an unsupported value source (BEHAVIOR_BINDING_MISMATCH)`);
+    };
+    let subject;
+    if (action.subject !== undefined) {
+        subject = resolveField(action.subject, 'subject');
+    }
+    const fields = {};
+    for (const [name, raw] of Object.entries(action.fields)) {
+        fields[name] = resolveField(raw, `field '${name}'`);
+    }
+    let appBase;
+    try {
+        appBase = requireTrustedUiBase(state);
+    }
+    catch (error) {
+        throw failExecution(error instanceof Error ? error.message : String(error));
+    }
+    let page;
+    try {
+        page = await state.engineBrowser.pageFor(session.sessionId);
+    }
+    catch (error) {
+        throw failExecution(`engine browser unavailable: ${error instanceof Error ? error.message : String(error)} (OBSERVATION_SCOPE_INCOMPLETE)`);
+    }
+    let observation;
+    try {
+        observation = await driveEngineAction(page, appBase, descriptor, action.operation, {
+            ...(Object.keys(fields).length > 0 ? { fields } : {}),
+            ...(subject !== undefined ? { entityId: subject } : {}),
+        });
+    }
+    catch (error) {
+        throw failExecution(`engine surface ${action.operation} failed: ${error instanceof Error ? error.message : String(error)} (BEHAVIOR_EFFECT_MISMATCH)`);
+    }
+    let visible;
+    try {
+        visible = await readEngineVisible(page, appBase, descriptor, action.operation, observation.entityId);
+    }
+    catch (error) {
+        throw failExecution(`engine visible read failed: ${error instanceof Error ? error.message : String(error)} (OBSERVATION_SCOPE_INCOMPLETE)`);
+    }
+    let url;
+    try {
+        url = page.url();
+    }
+    catch (error) {
+        throw failExecution(`engine page url unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return {
+        operationId: randomUUID(),
+        browserObservation: { url, entityId: observation.entityId, visibleFields: { ...visible } },
+        submittedValues: {
+            surface: action.surface,
+            operation: action.operation,
+            ...(subject !== undefined ? { subject } : {}),
+            fields: { ...fields },
+        },
+    };
+}
+/**
+ * Drives the principal operation of a prepared case (plan 2026-09-19
+ * §4.6, Phase 5): resolves the execution, runs the witness-owned
+ * engine-http request driver for `request` actions, attributes the
+ * captured attempt against the bound route inventory, resolves the
+ * completion barrier, observes after-state, and issues the sealed
+ * `behavior.case` record(s) — one per compiled obligation. Grading
+ * happens core-side, never here.
+ *
+ * `surface` actions need the Phase 6 browser driver; `deliver` and
+ * `sequence` need Phase 8 — all block with an explicit cause.
+ */
+async function handleBehaviorPrincipal(state, res, body) {
+    if (!isPlainObject(body)) {
+        throw new HttpError(400, 'behavior/principal body must be {sessionId, sessionToken, executionId}');
+    }
+    const keys = Object.keys(body).sort();
+    if (keys.length !== 3 || keys[0] !== 'executionId' || keys[1] !== 'sessionId' || keys[2] !== 'sessionToken') {
+        throw new HttpError(400, 'behavior/principal accepts exactly {sessionId, sessionToken, executionId}');
+    }
+    const executionId = body['executionId'];
+    if (typeof executionId !== 'string' || executionId.length === 0) {
+        throw new HttpError(400, 'behavior/principal requires a non-empty string executionId');
+    }
+    const binding = state.behaviorCatalog;
+    if (binding === null) {
+        throw new HttpError(409, 'no behavior catalog is bound to this run');
+    }
+    const session = requireOpenSession(state, body);
+    const execution = [...state.caseExecutions.values()].find((item) => item.executionId === executionId);
+    if (execution === undefined) {
+        throw new HttpError(400, `behavior/principal names unknown execution '${executionId}'`);
+    }
+    if (execution.sessionId !== session.sessionId) {
+        throw new HttpError(403, 'behavior/principal session does not own this execution — executions belong to the session that prepared them');
+    }
+    if (execution.state === 'sealed') {
+        throw new HttpError(409, 'behavior/principal execution is already sealed — one execution per required case per run');
+    }
+    if (execution.state === 'failed') {
+        throw new HttpError(409, `behavior/principal execution failed: ${execution.detail ?? 'unknown failure'}`);
+    }
+    if (execution.state !== 'before-snapshot-complete') {
+        throw new HttpError(409, `behavior/principal execution is in state '${execution.state}', not ready for the principal`);
+    }
+    const compiled = binding.catalog.cases.find((item) => item.caseId === execution.caseId);
+    if (compiled === undefined) {
+        throw new HttpError(409, 'behavior/principal case vanished from the bound catalog (fail closed)');
+    }
+    const failExecution = (detail) => {
+        execution.state = 'failed';
+        execution.detail = detail;
+        const provider = state.options.fixtureProvider ?? null;
+        if (provider !== null) {
+            void Promise.resolve(provider.release(execution.lease.leaseId)).catch(() => { });
+        }
+        return new HttpError(409, detail);
+    };
+    const action = compiled.definition.action;
+    const actorProfile = compiled.definition.actor;
+    const provider = state.options.fixtureProvider ?? null;
+    // The sealed principal evidence: exactly one of the two drivers fills
+    // its half. Request cases seal attempts + request observations;
+    // surface cases seal the browser observation.
+    let attempts = [];
+    let requestObservations = [];
+    let browserObservation = undefined;
+    let submittedValues;
+    let operationId;
+    execution.state = 'principal-executing';
+    if (action.kind === 'request') {
+        const requestAction = action;
+        if (compiled.definition.channel !== 'engine-http') {
+            throw failExecution(`case '${compiled.definition.id}' requires the '${compiled.definition.channel}' channel — the Phase 8 task driver produces that evidence`);
+        }
+        if (provider === null || typeof provider.resolveCredential !== 'function') {
+            throw failExecution('no trusted credential resolver is configured — the principal cannot authenticate engine-side');
+        }
+        const origin = state.options.targetBaseUrl ?? null;
+        if (origin === null || origin === '') {
+            throw failExecution('no approved subject origin is configured for the principal driver');
+        }
+        let driven;
+        try {
+            driven = await driveBehaviorRequest({
+                action: {
+                    kind: 'request',
+                    method: requestAction.method,
+                    pathTemplate: requestAction.pathTemplate,
+                    path: requestAction.path,
+                    query: requestAction.query,
+                    body: requestAction.body,
+                    credentialVariant: requestAction.credentialVariant,
+                    ...(requestAction.signatureProfile !== undefined ? { signatureProfile: requestAction.signatureProfile } : {}),
+                },
+                lease: execution.lease,
+                actorProfile,
+                origin,
+                resolveCredential: (credentialRef) => provider.resolveCredential(credentialRef),
+                timeoutMs: state.options.requestTimeoutMs,
+            });
+        }
+        catch (error) {
+            if (error instanceof BehaviorDriverError) {
+                throw failExecution(`principal driver: ${error.message} (OBSERVATION_SCOPE_INCOMPLETE)`);
+            }
+            throw failExecution(`principal driver failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        execution.state = 'principal-captured';
+        // Attribute the captured attempt against the bound inventory with the
+        // compiled endpoint as expected — the grader re-resolves
+        // independently; a misdirected principal fails here with a diagnostic
+        // instead of sealing evidence for the wrong endpoint.
+        const interpreted = interpretObservedPath(driven.path);
+        if (!interpreted.ok) {
+            throw failExecution(`principal captured a noncanonical path: ${interpreted.reason} (BEHAVIOR_BINDING_MISMATCH)`);
+        }
+        const expectedEndpoint = compiled.endpointResourceId ?? compiled.resourceId;
+        const resolution = resolveHttpRoute(driven.method, interpreted.path, binding.routes, expectedEndpoint);
+        if (resolution.status !== 'match') {
+            const reason = resolution.status === 'ambiguous'
+                ? `ambiguous route attribution for ${driven.method} ${interpreted.path} (BEHAVIOR_BINDING_MISMATCH)`
+                : resolution.status === 'mismatch'
+                    ? `principal reached '${resolution.matched.resourceId}', not the required endpoint '${expectedEndpoint}' (BEHAVIOR_BINDING_MISMATCH)`
+                    : resolution.status === 'nomatch'
+                        ? `principal ${driven.method} ${interpreted.path} matches no inventoried route (BEHAVIOR_BINDING_MISMATCH)`
+                        : resolution.reason;
+            throw failExecution(reason);
+        }
+        operationId = driven.engineRequestId;
+        attempts = [
+            {
+                engineRequestId: driven.engineRequestId,
+                method: driven.method,
+                path: driven.path,
+                endpointResourceId: resolution.matched.resourceId,
+                actorRef: actorProfile,
+                requestDigest: driven.requestDigest,
+                status: driven.status,
+                responseDigest: driven.responseDigest,
+            },
+        ];
+        requestObservations = [
+            {
+                engineRequestId: driven.engineRequestId,
+                method: driven.method,
+                path: driven.path,
+                query: { ...driven.query },
+                body: driven.body,
+                status: driven.status,
+                responseBody: driven.responseBody,
+            },
+        ];
+        submittedValues = { path: driven.path, query: { ...driven.query }, body: driven.body };
+    }
+    else if (action.kind === 'surface') {
+        const surfaceAction = action;
+        const surfaceChannel = compiled.definition.channel;
+        if (surfaceChannel !== 'engine-browser') {
+            throw failExecution(`surface case '${compiled.definition.id}' requires the engine-browser channel — blocked, never satisfied`);
+        }
+        const driven = await driveSurfacePrincipal(state, binding, execution, compiled, surfaceAction, failExecution, session);
+        operationId = driven.operationId;
+        browserObservation = driven.browserObservation;
+        submittedValues = driven.submittedValues;
+        execution.state = 'principal-captured';
+    }
+    else {
+        throw failExecution(`case '${compiled.definition.id}' uses a '${action.kind}' action — the Phase 8 task driver produces that evidence`);
+    }
+    // Completion barrier: immediate effects resolve at once; barrier
+    // effects need a real checkpoint from an adapter observer.
+    const barrierEffects = compiled.effects.filter((effect) => effect.completion === 'barrier');
+    if (barrierEffects.length > 0) {
+        for (const effect of barrierEffects) {
+            const adapter = state.adapters.get(effect.adapter);
+            if (adapter === undefined || typeof adapter.awaitBarrier !== 'function') {
+                throw failExecution(`observation incomplete: no barrier observer for scope '${effect.scope}' (OBSERVATION_SCOPE_INCOMPLETE)`);
+            }
+            const baseUrl = adapter.baseUrl ?? state.options.adapterBaseUrl ?? state.options.targetBaseUrl ?? '';
+            const ctx = makeAdapterContext(baseUrl, effect.resourceId, () => {
+                throw new Error('barrier observations must not use the candidate GET transport');
+            }, state.options.adapterReadAuthorization
+                ? { authorization: state.options.adapterReadAuthorization }
+                : undefined);
+            let barrier;
+            try {
+                barrier = await adapter.awaitBarrier(ctx, {
+                    scope: effect.scope,
+                    fixtureNamespace: execution.lease.namespace,
+                    operationId,
+                    deadlineMs: state.options.barrierTimeoutMs ?? 30_000,
+                });
+            }
+            catch (error) {
+                throw failExecution(`observation incomplete: barrier for scope '${effect.scope}' failed: ${error instanceof Error ? error.message : String(error)} (OBSERVATION_SCOPE_INCOMPLETE)`);
+            }
+            if (barrier === null || typeof barrier !== 'object' || barrier.complete !== true) {
+                throw failExecution(`async effect did not complete before the barrier deadline — premature success is blocked (OBSERVATION_SCOPE_INCOMPLETE)`);
+            }
+        }
+    }
+    execution.state = 'barrier-reached';
+    // Authoritative after snapshots over every declared effect scope.
+    const afterSnapshots = [];
+    const afterCheckpoints = {};
+    for (const effect of compiled.effects) {
+        const adapter = state.adapters.get(effect.adapter);
+        if (adapter === undefined || typeof adapter.snapshotScope !== 'function') {
+            throw failExecution(`observation incomplete: scope '${effect.scope}' lost its observer (OBSERVATION_SCOPE_INCOMPLETE)`);
+        }
+        const baseUrl = adapter.baseUrl ?? state.options.adapterBaseUrl ?? state.options.targetBaseUrl ?? '';
+        const ctx = makeAdapterContext(baseUrl, effect.resourceId, () => {
+            throw new Error('snapshot observations must not use the candidate GET transport');
+        }, state.options.adapterReadAuthorization
+            ? { authorization: state.options.adapterReadAuthorization }
+            : undefined);
+        let snapshot;
+        try {
+            snapshot = await adapter.snapshotScope(ctx, { scope: effect.scope, fixtureNamespace: execution.lease.namespace });
+        }
+        catch (error) {
+            throw failExecution(`observation incomplete: after-scope '${effect.scope}' collection failed: ${error instanceof Error ? error.message : String(error)} (OBSERVATION_SCOPE_INCOMPLETE)`);
+        }
+        const validated = validateScopeSnapshot(snapshot, {
+            scope: effect.scope,
+            fixtureNamespace: execution.lease.namespace,
+            identityFields: effect.identityFields,
+            fields: effect.fields,
+        });
+        if (!validated.ok) {
+            throw failExecution(`observation incomplete: ${validated.detail} (OBSERVATION_SCOPE_INCOMPLETE)`);
+        }
+        afterCheckpoints[effect.scope] = validated.snapshot.checkpoint;
+        afterSnapshots.push(snapshot);
+    }
+    execution.state = 'after-snapshot-complete';
+    // Seal: strip snapshots to the core strict shape (no witness-local
+    // validation extras), then issue one record per compiled obligation.
+    const stripSnapshot = (snapshot) => ({
+        scope: snapshot.scope,
+        fixtureNamespace: snapshot.fixtureNamespace,
+        complete: snapshot.complete,
+        checkpoint: snapshot.checkpoint,
+        entities: snapshot.entities.map((entity) => ({ entityId: entity.entityId, fields: { ...entity.fields } })),
+    });
+    const actorLease = execution.lease.actors[actorProfile];
+    const payload = {
+        payloadVersion: 1,
+        caseId: compiled.caseId,
+        caseSpecDigest: compiled.specDigest,
+        obligationIds: [...compiled.obligationIds],
+        endpointResourceId: compiled.endpointResourceId,
+        operationId,
+        sessionId: session.sessionId,
+        executionId: execution.executionId,
+        fixtureNamespace: execution.lease.namespace,
+        actor: {
+            principalId: typeof actorLease?.principalId === 'string' ? actorLease.principalId : actorProfile,
+            tenantId: typeof actorLease?.tenantId === 'string' || actorLease?.tenantId === null ? (actorLease?.tenantId ?? null) : null,
+            roles: Array.isArray(actorLease?.roles) ? [...actorLease?.roles] : [],
+        },
+        actionDigest: behaviorActionDigestOf(compiled.definition.action),
+        submittedValues: submittedValues,
+        attempts,
+        requestObservations,
+        ...(browserObservation === undefined ? {} : { browserObservation }),
+        fixtureValues: { ...execution.lease.subjects },
+        before: execution.beforeSnapshots.map(stripSnapshot),
+        after: afterSnapshots.map(stripSnapshot),
+        completion: {
+            complete: true,
+            checkpoint: Object.values(afterCheckpoints).sort().join('+') || Object.values(execution.beforeCheckpoints).sort().join('+'),
+        },
+        channel: compiled.definition.channel,
+        authorityProfileDigest: binding.authorityProfileDigest,
+        state: 'sealed',
+    };
+    const recordIds = [];
+    for (const obligationId of compiled.obligationIds) {
+        const issued = issueRecord(state, obligationId, BEHAVIOR_CASE_KIND, session.testId, payload, 'engine-observed');
+        recordIds.push(issued.recordId);
+    }
+    recordIds.sort();
+    execution.state = 'sealed';
+    const response = {
+        caseId: compiled.caseId,
+        executionId: execution.executionId,
+        recordIds,
+        state: execution.state,
+    };
+    sendJson(res, 200, response);
+}
 /**
  * Builds the witness-side execution trace (enforcement-review fix 2b):
  * per registered expected test, every recorded session with its open/
@@ -1405,6 +2124,15 @@ async function handleSessionOpen(state, res, body) {
     await startSessionProxy(state, session);
     state.sessions.set(sessionId, session);
     state.workerSessions.set(workerIndex, sessionId);
+    // Observe before-snapshots (Phase 2): the witness lists the
+    // observe-declared resources ITSELF at open. Total by construction —
+    // a snapshot failure is finalize data, never an open failure.
+    try {
+        await takeObserveSnapshots(state, session);
+    }
+    catch {
+        state.observeSnapshots.delete(sessionId);
+    }
     sendJson(res, 200, sessionView(state, session));
 }
 /** The session view returned to supervisor and worker (the credential). */
@@ -1450,6 +2178,11 @@ async function handleSessionClose(state, res, body) {
         session.sealedTick = (state.tick += 1);
         session.outcome = typeof outcome === 'string' ? outcome : null;
         state.workerSessions.delete(session.workerIndex);
+        // Observe snapshots die with the session: finalize runs BEFORE seal
+        // (the drain finalizes a passed test, then seals), so anything left
+        // here belongs to a test that never finalized — unsealed evidence
+        // must not linger for a later call to consume.
+        state.observeSnapshots.delete(sessionId);
         // The dedicated channel dies with the session: nothing can observe
         // (or submit) through it afterwards. The engine browser context dies
         // too — a sealed session's pages are never driven again.
@@ -1967,6 +2700,492 @@ async function handleServerE2eDeclarations(state, res, verifier, body) {
         obligations: [...obligations].sort(compareStrings),
     });
 }
+/**
+ * `POST /runs/observe-declarations` — SUPERVISOR ONLY: registers the
+ * obligation ids the trusted mapping layer declared kind `observed-e2e`
+ * (Observe channel, Phase 2) BEFORE the run. Same binding contract as
+ * the server-e2e set: bound once, identical re-registration idempotent,
+ * any change or late registration refused — the witness stamps
+ * `channel: 'observe'` records for these obligations only.
+ */
+async function handleObserveDeclarations(state, res, verifier, body) {
+    requireSupervisor(state, verifier);
+    if (!isPlainObject(body) || !Array.isArray(body['obligations'])) {
+        throw new HttpError(400, 'observe declarations body must be {obligations: [...]}');
+    }
+    const obligations = new Set();
+    for (const entry of body['obligations']) {
+        if (typeof entry !== 'string' || !OBLIGATION_ID_PATTERN.test(entry)) {
+            throw new HttpError(400, `observe declarations must be obligation ids '<resourceId>:<contract>' (got '${String(entry)}')`);
+        }
+        obligations.add(entry);
+    }
+    if (state.observeDeclarations !== null) {
+        const identical = state.observeDeclarations.size === obligations.size &&
+            [...obligations].every((id) => state.observeDeclarations?.has(id));
+        if (identical) {
+            sendJson(res, 200, {
+                bound: true,
+                count: state.observeDeclarations.size,
+                obligations: [...state.observeDeclarations].sort(compareStrings),
+            });
+            return;
+        }
+        sendJson(res, 409, {
+            error: 'observe declarations are already bound to this run and differ; the declaration set ' +
+                'is a PRE-run fact and is never relabeled — start a fresh witness for a new invocation',
+        });
+        return;
+    }
+    if (state.ledger.size > 0 || state.sessions.size > 0) {
+        sendJson(res, 409, {
+            error: 'witness already issued evidence or holds open sessions; observe declarations must be ' +
+                'registered BEFORE the run — start a fresh witness for a new invocation',
+        });
+        return;
+    }
+    state.observeDeclarations = obligations;
+    sendJson(res, 200, {
+        bound: true,
+        count: obligations.size,
+        obligations: [...obligations].sort(compareStrings),
+    });
+}
+/** Splits `<resourceId>:<contract>` at the first colon (obligation id grammar). */
+function resourceIdOfObligation(obligationId) {
+    const colon = obligationId.indexOf(':');
+    return colon === -1 ? obligationId : obligationId.slice(0, colon);
+}
+/** The CRUD operation a `persistence:<op>` contract requires; null otherwise. */
+function observeOperation(contract) {
+    if (!contract.startsWith('persistence:'))
+        return null;
+    const operation = contract.slice('persistence:'.length);
+    if (operation === 'create' || operation === 'read' || operation === 'update' || operation === 'delete') {
+        return operation;
+    }
+    return null;
+}
+/**
+ * Takes Observe before-snapshots for one freshly opened session: for
+ * every resource its observe-declared claims name, the witness runs the
+ * resource's adapter `list()` ITSELF and normalizes each body. The
+ * snapshot is the before-state every observe postcondition grades
+ * against — expectations never come from the suite. Per-resource
+ * trouble (no adapter, no list, probe/read/normalize failure) is
+ * stored as an error snapshot: the session still opens and the test
+ * still runs; finalize reports the resource as unobservable instead of
+ * satisfying anything. Total: never throws out of session open.
+ */
+async function takeObserveSnapshots(state, session) {
+    if (state.observeDeclarations === null || state.observeDeclarations.size === 0)
+        return;
+    const resources = new Set();
+    for (const claim of session.claims) {
+        if (state.observeDeclarations.has(claim))
+            resources.add(resourceIdOfObligation(claim));
+    }
+    if (resources.size === 0)
+        return;
+    const perSession = new Map();
+    state.observeSnapshots.set(session.sessionId, perSession);
+    for (const resourceId of [...resources].sort(compareStrings)) {
+        perSession.set(resourceId, await snapshotObserveResource(state, resourceId));
+    }
+    session.activity += 1;
+}
+/** Snapshots one resource's adapter-listed entities (never throws). */
+async function snapshotObserveResource(state, resourceId) {
+    const failure = (adapterName, error) => ({
+        resourceId,
+        adapterName,
+        before: new Map(),
+        error,
+    });
+    let adapterName = resourceId;
+    try {
+        const context = await adapterReadContext(state, resourceId);
+        adapterName = context.adapterName;
+        const adapter = context.adapter;
+        if (typeof adapter.list !== 'function') {
+            return failure(adapterName, `adapter '${adapterName}' exports no list() — Observe needs a before-snapshot, so ` +
+                `resource '${resourceId}' is unobservable until the adapter lists its entities`);
+        }
+        const ctx = observeAdapterContext(state, context.baseUrl, resourceId);
+        return { resourceId, adapterName, before: await observeListEntities(adapterName, adapter, ctx), error: null };
+    }
+    catch (error) {
+        const detail = error instanceof HttpError ? error.message : error.message;
+        return failure(adapterName, detail);
+    }
+}
+/** Builds the GET-only adapter transport for observe snapshots/reads. */
+function observeAdapterContext(state, baseUrl, resourceId) {
+    const headers = state.options.adapterReadAuthorization
+        ? { authorization: state.options.adapterReadAuthorization }
+        : undefined;
+    return makeAdapterContext(baseUrl, resourceId, (path) => adapterGet(baseUrl, state.options.requestTimeoutMs, path, state.options.adapterReadAuthorization), headers);
+}
+/**
+ * Lists + normalizes a resource's entities through its adapter (the
+ * witness's own observation). Throws HttpError (409) on list/normalize
+ * trouble — callers turn it into a typed observe note, never
+ * satisfaction.
+ */
+async function observeListEntities(adapterName, adapter, ctx) {
+    if (typeof adapter.list !== 'function') {
+        throw new HttpError(409, `adapter '${adapterName}' exports no list() — Observe needs entity snapshots`);
+    }
+    let listed;
+    try {
+        listed = await adapter.list(ctx);
+    }
+    catch (error) {
+        throw new HttpError(409, `adapter '${adapterName}' list failed: ${error.message}`);
+    }
+    if (!Array.isArray(listed)) {
+        throw new HttpError(409, `adapter '${adapterName}' list must return an array of entities`);
+    }
+    const out = new Map();
+    for (const raw of listed) {
+        let normalized;
+        try {
+            const candidate = adapter.normalize(raw);
+            if (!isPlainObject(candidate) || !('entityId' in candidate) || !('fields' in candidate)) {
+                throw new Error('normalize must return {entityId, fields}');
+            }
+            normalized = { entityId: candidate['entityId'], fields: candidate['fields'] };
+        }
+        catch (error) {
+            throw new HttpError(409, `adapter '${adapterName}' normalize failed: ${error.message}`);
+        }
+        let key;
+        try {
+            key = canonicalOf(normalized.entityId);
+        }
+        catch {
+            throw new HttpError(409, `adapter '${adapterName}' normalized an entity id with no canonical form`);
+        }
+        out.set(key, normalized);
+    }
+    return out;
+}
+/**
+ * Matches a recorded observed path against an adapter observe path
+ * template. `{id}` binds exactly one non-empty segment; every other
+ * segment must be literally equal (case-sensitive). Matching reuses
+ * core's canonical shape semantics (`{id}` → `{}`).
+ *
+ * Returns `{id}` (null for id-less create templates) on match, null
+ * otherwise.
+ */
+function matchObserveTemplate(observedPath, template) {
+    const segments = template.split('/').filter((segment) => segment.length > 0);
+    const idIndex = segments.indexOf('{id}');
+    const canonical = segments.map((segment) => (segment === '{id}' ? '{}' : segment)).join('/');
+    if (!pathMatchesShape(observedPath, canonical.startsWith('/') ? canonical : `/${canonical}`)) {
+        return null;
+    }
+    if (idIndex === -1)
+        return { id: null };
+    const observedSegments = observedPath.split('/').filter((segment) => segment.length > 0);
+    const id = observedSegments[idIndex];
+    if (id === undefined || id.length === 0)
+        return null;
+    return { id };
+}
+/** Finds a snapshot key for a path id segment (canonical or numeric-string form). */
+function beforeKeyForSegment(before, segment) {
+    try {
+        const canonical = canonicalOf(segment);
+        if (before.has(canonical))
+            return canonical;
+    }
+    catch {
+        return null;
+    }
+    for (const [key, entry] of before) {
+        if (typeof entry.entityId === 'number' && String(entry.entityId) === segment)
+            return key;
+    }
+    return null;
+}
+/**
+ * Parses a proxied request body into echoable fields (Observe channel):
+ * JSON objects and form bodies project their top-level scalar
+ * (string/number/boolean) fields — the witness-observed statement of
+ * what the test sent, graded by echo against the adapter read. Nested
+ * envelopes are not entity fields and are skipped (documented); empty,
+ * truncated, oversized, unparsable, or otherwise-typed bodies are
+ * INELIGIBLE (typed error), never echoed from a prefix or a guess.
+ */
+function parseObserveBody(exchange) {
+    if (exchange.requestBody === null || exchange.requestBytes === 0) {
+        return { error: 'the proxied exchange carried no request body — there is nothing to echo' };
+    }
+    if (exchange.requestTruncated) {
+        return {
+            error: `the request body exceeds the ${String(OBSERVED_REQUEST_BODY_BYTES)}-byte witness snapshot ` +
+                'cap — oversized intents are never echoed from a prefix',
+        };
+    }
+    const contentType = exchange.requestContentType;
+    if (contentType === 'application/json') {
+        let parsed;
+        try {
+            parsed = JSON.parse(exchange.requestBody.toString('utf8'));
+        }
+        catch {
+            return { error: 'the request body is not parseable JSON' };
+        }
+        if (!isPlainObject(parsed)) {
+            return { error: 'the JSON request body is not an object' };
+        }
+        const fields = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                fields[key] = value;
+            }
+        }
+        if (Object.keys(fields).length === 0) {
+            return { error: 'the JSON request body carries no echoable scalar fields' };
+        }
+        return { fields };
+    }
+    if (contentType === 'application/x-www-form-urlencoded') {
+        const fields = {};
+        for (const [key, value] of new URLSearchParams(exchange.requestBody.toString('utf8'))) {
+            fields[key] = value;
+        }
+        if (Object.keys(fields).length === 0) {
+            return { error: 'the form request body carries no fields' };
+        }
+        return { fields };
+    }
+    return {
+        error: `unsupported request content-type '${contentType ?? '<none>'}' — observe echoes JSON and ` +
+            'form bodies only',
+    };
+}
+/**
+ * Reads one entity through its adapter at finalize time (the
+ * witness's own after-observation). Throws HttpError (409) on
+ * adapter/normalize trouble — callers note it, never satisfy on it.
+ */
+async function readObserveEntity(state, resourceId, id) {
+    const { adapterName, adapter, baseUrl } = await adapterReadContext(state, resourceId);
+    const ctx = observeAdapterContext(state, baseUrl, resourceId);
+    let bodyRaw;
+    try {
+        bodyRaw = await adapter.read(ctx, id);
+    }
+    catch (error) {
+        throw new HttpError(409, `adapter '${adapterName}' read failed: ${error.message}`);
+    }
+    const found = bodyRaw !== null && bodyRaw !== undefined;
+    if (!found)
+        return { adapterName, found: false, fields: null, entityId: id };
+    try {
+        const candidate = adapter.normalize(bodyRaw);
+        if (!isPlainObject(candidate) || !('entityId' in candidate) || !('fields' in candidate)) {
+            throw new Error('normalize must return {entityId, fields}');
+        }
+        return { adapterName, found: true, fields: candidate['fields'], entityId: candidate['entityId'] };
+    }
+    catch (error) {
+        throw new HttpError(409, `adapter '${adapterName}' normalize failed: ${error.message}`);
+    }
+}
+/**
+ * `POST /observe/finalize` — SUPERVISOR ONLY: resolves one OPEN
+ * session's observe-declared claims against the session's own proxied
+ * traffic plus independent adapter reads, stamping witnessed
+ * `persistence.observed` records for whatever resolves. The session
+ * must be OPEN (the drain finalizes after a passed test, before seal);
+ * sealed/unknown sessions are refused, so records are never injected
+ * after the test ended. Every non-resolution is a typed NOTE in the
+ * response — never satisfaction, never a run failure (the obligation
+ * stays blocking through verdicts, which is the honest outcome).
+ *
+ * Per obligation (`<resourceId>:persistence:<op>`):
+ * - adapter binding + before-snapshot must exist (else typed note);
+ * - exactly one 2xx session exchange must match the binding (zero →
+ *   missing-traffic note; several → ambiguity note);
+ * - create resolves its id from the list-diff (exactly one new entity);
+ *   read/update/delete bind `{id}` from the path against the snapshot;
+ * - create/update echo the parsed request-body scalars against the
+ *   adapter read (the record carries both; the ENGINE grades the echo);
+ * - the matched exchange is consumed single-use.
+ */
+async function handleObserveFinalize(state, res, verifier, body) {
+    requireSupervisor(state, verifier);
+    if (!isPlainObject(body) || typeof body['sessionId'] !== 'string' || body['sessionId'].length === 0) {
+        throw new HttpError(400, 'observe finalize body must be {sessionId}');
+    }
+    const sessionId = body['sessionId'];
+    const session = state.sessions.get(sessionId);
+    if (session === undefined) {
+        throw new HttpError(400, `session '${sessionId}' is unknown (never opened on this witness)`);
+    }
+    if (session.status !== 'open') {
+        throw new HttpError(409, `session '${sessionId}' is sealed — observe finalizes before seal, never after (records cannot be injected after the test ended)`);
+    }
+    if (state.observeDeclarations === null) {
+        throw new HttpError(409, 'observe declarations are not bound on this witness — register them before the run');
+    }
+    const finalized = [];
+    const notes = [];
+    const claims = session.claims.filter((claim) => state.observeDeclarations?.has(claim));
+    for (const claimId of claims) {
+        const outcome = await finalizeObserveClaim(state, session, claimId);
+        if ('record' in outcome)
+            finalized.push(outcome.record);
+        else
+            notes.push(outcome.note);
+    }
+    const response = { finalized, notes };
+    sendJson(res, 200, response);
+}
+/** Resolves one observe-declared claim (record or typed note, never throws). */
+async function finalizeObserveClaim(state, session, claimId) {
+    const note = (detail) => ({ note: `observe '${claimId}': ${detail}` });
+    const resourceId = resourceIdOfObligation(claimId);
+    const operation = observeOperation(claimId.slice(resourceId.length + 1));
+    if (operation === null) {
+        return note('the Observe channel proves persistence:* contracts only — this claim stays blocking');
+    }
+    let adapterName;
+    let adapter;
+    let adapterBaseUrl;
+    try {
+        const context = await adapterReadContext(state, resourceId);
+        adapterName = context.adapterName;
+        adapter = context.adapter;
+        adapterBaseUrl = context.baseUrl;
+    }
+    catch (error) {
+        return note(error instanceof HttpError ? error.message : error.message);
+    }
+    const binding = adapter.observe?.[operation];
+    if (binding === undefined) {
+        return note(`adapter '${adapterName}' declares no observe binding for '${operation}' — declare it in ` +
+            `'.gateforge/adapters/${adapterName}.mjs' to make this obligation observable`);
+    }
+    const snapshot = state.observeSnapshots.get(session.sessionId)?.get(resourceId);
+    if (snapshot === undefined || snapshot.error !== null) {
+        return note(snapshot?.error !== null && snapshot?.error !== undefined
+            ? `no usable before-snapshot: ${snapshot.error}`
+            : 'no before-snapshot for this session — the session opened before observe declarations bound, or the snapshot failed');
+    }
+    // Bind watermark (plan §11.4, same as http-observation): exchanges
+    // that completed before the trusted context bound predate it.
+    const watermark = state.runContext === null ? 0 : state.observedSeqAtBind;
+    const matches = [];
+    for (const exchange of state.observed) {
+        if (exchange.sessionId !== session.sessionId || exchange.seq <= watermark)
+            continue;
+        if (exchange.method !== binding.method)
+            continue;
+        if (exchange.status < 200 || exchange.status > 299)
+            continue;
+        const matched = matchObserveTemplate(exchange.path, binding.path);
+        if (matched === null)
+            continue;
+        matches.push({ exchange, id: matched.id });
+    }
+    if (matches.length === 0) {
+        return note(`no ${binding.method} ${binding.path} exchange (2xx) for this session through the observation ` +
+            'proxy — drive traffic through the session proxy prefix before claiming the obligation');
+    }
+    if (matches.length > 1) {
+        return note(`${String(matches.length)} matching ${binding.method} ${binding.path} exchanges — ambiguous, ` +
+            'refusing to pick one (seed through untracked channels so the mutation stands alone)');
+    }
+    const matched = matches[0];
+    // Resolve the entity id: create diffs the witness-held lists (the new
+    // id is observed, never declared); read/update/delete bind `{id}`
+    // against the session-open snapshot.
+    let entityIdForRead;
+    let before;
+    if (operation === 'create') {
+        let after;
+        try {
+            const ctx = observeAdapterContext(state, adapterBaseUrl, resourceId);
+            after = await observeListEntities(adapterName, adapter, ctx);
+        }
+        catch (error) {
+            return note(error instanceof HttpError ? error.message : error.message);
+        }
+        const fresh = [...after.keys()].filter((key) => !snapshot.before.has(key));
+        if (fresh.length !== 1) {
+            return note(`expected exactly one new entity after the observed create, found ${String(fresh.length)} — ` +
+                'the creation is ambiguous, so no record is issued');
+        }
+        const created = after.get(fresh[0]);
+        entityIdForRead = created.entityId;
+        before = { entityAbsent: true };
+    }
+    else {
+        if (matched.id === null) {
+            return note('the observe binding carries no {id} segment for a non-create operation');
+        }
+        const beforeKey = beforeKeyForSegment(snapshot.before, matched.id);
+        if (beforeKey === null) {
+            return note(`entity '${matched.id}' was not in the session-open snapshot — observe binds {id} ` +
+                'against witness-held before-state, never against suite-declared ids');
+        }
+        const beforeEntry = snapshot.before.get(beforeKey);
+        entityIdForRead = beforeEntry.entityId;
+        if (operation === 'update')
+            before = { found: true, fields: beforeEntry.fields };
+    }
+    // Echo source (create/update only): the witness-observed request
+    // fields. Read/delete carry no echo — presence/absence grades them.
+    let observedFields = {};
+    if (operation === 'create' || operation === 'update') {
+        const parsed = parseObserveBody(matched.exchange);
+        if ('error' in parsed)
+            return note(parsed.error);
+        observedFields = parsed.fields;
+    }
+    let read;
+    try {
+        read = await readObserveEntity(state, resourceId, entityIdForRead);
+    }
+    catch (error) {
+        return note(error instanceof HttpError ? error.message : error.message);
+    }
+    const payload = {
+        resourceId,
+        entityId: read.entityId,
+        found: read.found,
+        ...(read.found ? { fields: read.fields ?? {} } : {}),
+        ...(before !== undefined ? { before } : {}),
+        observedFields,
+        exchange: {
+            method: matched.exchange.method,
+            path: matched.exchange.path,
+            status: matched.exchange.status,
+            seq: matched.exchange.seq,
+        },
+        sessionId: session.sessionId,
+        channel: OBSERVE_CHANNEL,
+    };
+    // The record binds runId/claimId/testId and rides the same ledger
+    // attestation MAC as every witnessed record. Contents are
+    // witness-produced (proxy capture + adapter read) — `engine-observed`
+    // origin, witnessed trust; the suite-driven-browser distinction rides
+    // `channel: 'observe'`, which the grader keys off explicitly.
+    const issued = issueRecord(state, claimId, OBSERVED_KIND, session.testId, payload, 'engine-observed');
+    // Single-use: the matched exchange can never credit another claim.
+    const consumed = state.observed.indexOf(matched.exchange);
+    if (consumed !== -1)
+        state.observed.splice(consumed, 1);
+    session.activity += 1;
+    return {
+        record: { obligationId: claimId, recordId: issued.recordId, operation, entityId: read.entityId },
+    };
+}
 /**
  * `POST /witness/server-persistence` — SUPERVISOR ONLY (run token +
  * verifier key; the trusted CLI drain forwards intents the supervised
@@ -2469,6 +3688,22 @@ async function stopWitness(state) {
     for (const session of state.sessions.values()) {
         await stopSessionProxy(session);
     }
+    // Phase 4 lifecycle shutdown: release every live fixture lease namespace.
+    // Timeouts/failures release only their own namespace and never flip a
+    // verdict — releases here are best-effort shutdown hygiene.
+    {
+        const provider = state.options.fixtureProvider ?? null;
+        if (provider !== null) {
+            for (const execution of state.caseExecutions.values()) {
+                try {
+                    await provider.release(execution.lease.leaseId);
+                }
+                catch {
+                    // Best-effort: shutdown must complete.
+                }
+            }
+        }
+    }
     await state.engineBrowser.closeAll();
     await new Promise((resolveClose) => {
         state.server.close(() => resolveClose());