@gate-forge/witness 0.0.0-stage → 0.8.0

package/dist/client/witness-client.d.ts

@@ -0,0 +1,193 @@
+import type { BehaviorExecuteRequest, BehaviorExecuteResponse, BehaviorPrincipalRequest, BehaviorPrincipalResponse, BrowserActionRequest, BrowserActionResponse, BrowserSurfaceRequest, BrowserVisibleRequest, BrowserVisibleResponse, IntervalCloseResponse, IntervalOpenResponse, PersistenceRequest, PersistenceResponse, PreObservationRequest, PreObservationResponse, RecordsRequest, RecordsResponse, SessionIdentityRequest, SessionIdentityResponse, SessionResolveRequest, SessionResolveResponse } from '../witness/types.js';
+/** A witness call that failed (status + single-cause diagnostic). */
+export declare class WitnessRequestError extends Error {
+    readonly status: number;
+    readonly detail: string | null;
+    constructor(status: number, message: string, detail?: string | null);
+}
+/**
+ * Resolves the witness base URL: env first, then the spawned-witness
+ * file in the run-state dir (written by the reporter when it auto-spawns
+ * a witness without `--witness-url`).
+ *
+ * Returns:
+ *   string: the witness base URL.
+ *
+ * Throws:
+ *   Error: with the exact setup step required when no witness is wired.
+ */
+export declare function resolveWitnessUrl(): string;
+/**
+ * The fixture's witness transport.
+ *
+ * Args:
+ *   url: witness base URL (default: resolved from env/state file).
+ *   token: run token (default: GATEFORGE_RUN_TOKEN).
+ *   timeoutMs: per-call timeout.
+ */
+export declare class WitnessClient {
+    readonly url: string;
+    readonly token: string;
+    readonly timeoutMs: number;
+    constructor(url?: string, token?: string | undefined, timeoutMs?: number);
+    /** POST /records (pin #7; Phase 1: requires the supervisor-issued session credential). */
+    postRecords(request: RecordsRequest): Promise<RecordsResponse>;
+    /**
+     * POST /sessions/resolve (Phase 1, worker side): asks for the OPEN
+     * session bound to the exact (workerIndex, testId) pair.
+     *
+     * Deliberately the ONLY session-lifecycle call on the suite-side
+     * client (enforcement-review fix 3): open and close live on the
+     * supervisor channel (`SupervisorClient`, verifier-key authenticated)
+     * and are dispatched by the trusted CLI's spool drain — the tested
+     * suite has NO reachable path to mint, seal, or re-seal a session,
+     * and with it no path to forge the execution record supervision
+     * grades. Resolve only ever answers for a session the supervisor
+     * already opened; it cannot create or extend one.
+     *
+     * Returns:
+     *   SessionResolveResponse when an open session answers; null when the
+     *   witness answers 404 (not yet opened, or sealed).
+     */
+    resolveSession(request: SessionResolveRequest): Promise<SessionResolveResponse | null>;
+    /**
+     * POST /sessions/identity (plan Phase 4b item 3b): registers the login
+     * of the tenant this test just created, for THIS session only.
+     *
+     * It changes who the engine reads as — nothing else: the engine still
+     * performs every read, a wrong tenant makes the row unfound (fail
+     * closed), and the credential never reaches a record, the run state, a
+     * log or a report. The call carries the session credential, so it can
+     * only ever register for the session the caller is running under.
+     */
+    registerSessionIdentity(request: SessionIdentityRequest): Promise<SessionIdentityResponse>;
+    /**
+     * POST /sessions/intervals/open (Phase 1): marks the start of a
+     * UI-action observation interval on the witness's monotonic clock.
+     * Proxy exchanges completing inside the interval are the session's
+     * browser evidence; everything outside (setup traffic) is never
+     * credited.
+     */
+    beginActionInterval(request: {
+        sessionId: string;
+        sessionToken: string;
+        operation: string;
+    }): Promise<IntervalOpenResponse>;
+    /**
+     * POST /sessions/intervals/close (Phase 1): seals the interval. A
+     * closed interval can never be stretched later (409 on re-close).
+     */
+    endActionInterval(request: {
+        sessionId: string;
+        sessionToken: string;
+        intervalId: string;
+    }): Promise<IntervalCloseResponse>;
+    /**
+     * POST /witness/pre-observation (audit round 4): engine-side id-set
+     * snapshot BEFORE a claimed create; pass the returned
+     * `observationId` to `verifyPersistence` so the issued record carries
+     * `before: {entityAbsent}`. Phase 1: requires the supervisor-issued
+     * session credential — the snapshot belongs to the open test session.
+     */
+    preObserve(request: PreObservationRequest): Promise<PreObservationResponse>;
+    /**
+     * POST /witness/http-observation (ADR 0004 D7, plan §8 / D1):
+     * consumes one witness-observed HTTP exchange matching (method, path)
+     * and issues witnessed `http.request` records for the declaring
+     * test's claimed obligations. Phase 1: the caller must hold a valid
+     * OPEN session and only an exchange observed through THAT session's
+     * proxy prefix within one of its recorded action intervals can be
+     * consumed — the claim set may be given as `claimIds`, or as the
+     * singular legacy `claimId`/`obligationId` pair (folded in by the
+     * server; a split assignment with distinct values is refused with 400).
+     */
+    observeHttp(request: {
+        claimIds?: string[];
+        claimId?: string;
+        obligationId?: string;
+        testId: string;
+        method: string;
+        path: string;
+        expectedStatus?: number;
+        sessionId: string;
+        sessionToken: string;
+    }): Promise<{
+        recordId: string;
+        runId: string;
+        trust: string;
+        status: number;
+        records: Array<{
+            recordId: string;
+            obligationId: string;
+        }>;
+    }>;
+    /**
+     * POST /witness/persistence and record adapter wall time.
+     *
+     * Args:
+     *   request: persistence observation bound to a supervised test session.
+     *
+     * Returns:
+     *   Promise<PersistenceResponse>: the engine-side adapter result.
+     */
+    verifyPersistence(request: PersistenceRequest & {
+        testId: string;
+        claimId: string;
+        sessionId: string;
+        sessionToken: string;
+    }): Promise<PersistenceResponse>;
+    /**
+     * POST /browser/surface (plan Phase 1 item 4): registers the
+     * consumer-declared surface descriptor + the app base the ENGINE must
+     * drive for this session. Validated engine-side (structure, loopback,
+     * fingerprint); selectors are locators only.
+     */
+    registerBrowserSurface(request: BrowserSurfaceRequest): Promise<{
+        registered: true;
+    }>;
+    /**
+     * POST /browser/action (plan Phase 1 item 4): the ENGINE performs one
+     * constrained surface operation on its own page and returns its own
+     * observation (observed entity id, entered + rendered fields, app
+     * status, pre-observation id, issued record ids). Test code supplies
+     * intent only — it never touches the engine page.
+     */
+    browserAction(request: BrowserActionRequest): Promise<BrowserActionResponse>;
+    /**
+     * POST /browser/visible (plan Phase 1 item 4): the ENGINE re-reads
+     * the rendered result for the engine-observed entity and returns the
+     * rendered fields.
+     */
+    browserVisible(request: BrowserVisibleRequest): Promise<BrowserVisibleResponse>;
+    /**
+     * POST /behavior/execute (plan 2026-09-19 Phase 6): asks the ENGINE to
+     * execute one approved behavior case. The call carries ONLY the
+     * allowed case id plus the session credential — actor material,
+     * expectations, and subjects resolve engine-side and are never
+     * readable or overridable here.
+     */
+    proveCase(request: BehaviorExecuteRequest): Promise<BehaviorExecuteResponse>;
+    /**
+     * POST /behavior/principal (plan 2026-09-19 Phase 6): asks the ENGINE
+     * to drive the prepared execution's principal operation and seal the
+     * case record. Same credential-only boundary as `proveCase`.
+     */
+    drivePrincipal(request: BehaviorPrincipalRequest): Promise<BehaviorPrincipalResponse>;
+    /** GET /records — the issued ledger for this run. */
+    listRecords(): Promise<{
+        records: IssuedLedgerRecord[];
+    }>;
+    private request;
+}
+/** One witness-issued ledger record as seen by the ledger endpoint. */
+export interface IssuedLedgerRecord {
+    recordId: string;
+    runId: string;
+    trust: 'witnessed' | 'claimed';
+    obligationId: string;
+    kind: string;
+    testId: string;
+    payload: unknown;
+    issuedAt?: string;
+}
+//# sourceMappingURL=witness-client.d.ts.map

package/dist/client/witness-client.d.ts.map

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

package/dist/client/witness-client.js

@@ -0,0 +1,321 @@
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ENV_RUN_ID, ENV_RUN_TOKEN, ENV_STATE_DIR, ENV_WITNESS_URL, RUN_HEADER, WITNESS_URL_FILE, } from '../constants.js';
+/** A witness call that failed (status + single-cause diagnostic). */
+export class WitnessRequestError extends Error {
+    status;
+    detail;
+    constructor(status, message, detail = null) {
+        super(detail === null ? message : `${message}: ${detail}`);
+        this.name = 'WitnessRequestError';
+        this.status = status;
+        this.detail = detail;
+    }
+}
+/**
+ * Appends persistence adapter wall time to the run diagnostics.
+ *
+ * Args:
+ *   durationMs: elapsed wall time for the witness persistence request.
+ *   testId: runner-issued test identity associated with the call.
+ *   stateDir: Gateforge run-state directory, if a supervised run is active.
+ *
+ * Returns:
+ *   void: writes one JSONL row when run diagnostics are available.
+ */
+function recordPersistenceTiming(durationMs, testId, stateDir) {
+    if (stateDir === undefined || stateDir.length === 0)
+        return;
+    const diagnosticsDir = join(stateDir, 'diagnostics');
+    mkdirSync(diagnosticsDir, { recursive: true });
+    appendFileSync(join(diagnosticsDir, 'adapter-timing.jsonl'), `${JSON.stringify({
+        timestamp: new Date().toISOString(),
+        operation: 'verifyPersistence',
+        runId: process.env[ENV_RUN_ID] ?? null,
+        testId,
+        durationMs,
+    })}\n`, 'utf8');
+    if (durationMs > 2_000) {
+        process.stderr.write(`Gateforge witness adapter verifyPersistence took ${durationMs}ms for ${testId}\n`);
+    }
+}
+/**
+ * Resolves the witness base URL: env first, then the spawned-witness
+ * file in the run-state dir (written by the reporter when it auto-spawns
+ * a witness without `--witness-url`).
+ *
+ * Returns:
+ *   string: the witness base URL.
+ *
+ * Throws:
+ *   Error: with the exact setup step required when no witness is wired.
+ */
+export function resolveWitnessUrl() {
+    const fromEnv = process.env[ENV_WITNESS_URL];
+    if (fromEnv !== undefined && fromEnv !== '')
+        return fromEnv;
+    const stateDir = process.env[ENV_STATE_DIR];
+    if (stateDir !== undefined && stateDir !== '') {
+        try {
+            const record = JSON.parse(readFileSync(join(stateDir, WITNESS_URL_FILE), 'utf8'));
+            if (typeof record.url === 'string' && record.url !== '')
+                return record.url;
+        }
+        catch {
+            // fall through to the actionable error
+        }
+    }
+    throw new Error(`no witness service is wired: set ${ENV_WITNESS_URL} (or run under 'gateforge test-gates', ` +
+        'which exports it) so evidence primitives can submit records');
+}
+/**
+ * The fixture's witness transport.
+ *
+ * Args:
+ *   url: witness base URL (default: resolved from env/state file).
+ *   token: run token (default: GATEFORGE_RUN_TOKEN).
+ *   timeoutMs: per-call timeout.
+ */
+export class WitnessClient {
+    url;
+    token;
+    timeoutMs;
+    constructor(url = resolveWitnessUrl(), token = process.env[ENV_RUN_TOKEN], timeoutMs = 5000) {
+        this.url = url;
+        if (token === undefined || token === '') {
+            throw new Error(`${ENV_RUN_TOKEN} is required to talk to the witness service`);
+        }
+        this.token = token;
+        this.timeoutMs = timeoutMs;
+    }
+    /** POST /records (pin #7; Phase 1: requires the supervisor-issued session credential). */
+    async postRecords(request) {
+        const body = await this.request('/records', request);
+        return body;
+    }
+    /**
+     * POST /sessions/resolve (Phase 1, worker side): asks for the OPEN
+     * session bound to the exact (workerIndex, testId) pair.
+     *
+     * Deliberately the ONLY session-lifecycle call on the suite-side
+     * client (enforcement-review fix 3): open and close live on the
+     * supervisor channel (`SupervisorClient`, verifier-key authenticated)
+     * and are dispatched by the trusted CLI's spool drain — the tested
+     * suite has NO reachable path to mint, seal, or re-seal a session,
+     * and with it no path to forge the execution record supervision
+     * grades. Resolve only ever answers for a session the supervisor
+     * already opened; it cannot create or extend one.
+     *
+     * Returns:
+     *   SessionResolveResponse when an open session answers; null when the
+     *   witness answers 404 (not yet opened, or sealed).
+     */
+    async resolveSession(request) {
+        try {
+            return await this.request('/sessions/resolve', request);
+        }
+        catch (error) {
+            if (error instanceof WitnessRequestError && error.status === 404)
+                return null;
+            throw error;
+        }
+    }
+    /**
+     * POST /sessions/identity (plan Phase 4b item 3b): registers the login
+     * of the tenant this test just created, for THIS session only.
+     *
+     * It changes who the engine reads as — nothing else: the engine still
+     * performs every read, a wrong tenant makes the row unfound (fail
+     * closed), and the credential never reaches a record, the run state, a
+     * log or a report. The call carries the session credential, so it can
+     * only ever register for the session the caller is running under.
+     */
+    async registerSessionIdentity(request) {
+        return this.request('/sessions/identity', request);
+    }
+    /**
+     * POST /sessions/intervals/open (Phase 1): marks the start of a
+     * UI-action observation interval on the witness's monotonic clock.
+     * Proxy exchanges completing inside the interval are the session's
+     * browser evidence; everything outside (setup traffic) is never
+     * credited.
+     */
+    async beginActionInterval(request) {
+        return this.request('/sessions/intervals/open', request);
+    }
+    /**
+     * POST /sessions/intervals/close (Phase 1): seals the interval. A
+     * closed interval can never be stretched later (409 on re-close).
+     */
+    async endActionInterval(request) {
+        return this.request('/sessions/intervals/close', request);
+    }
+    /**
+     * POST /witness/pre-observation (audit round 4): engine-side id-set
+     * snapshot BEFORE a claimed create; pass the returned
+     * `observationId` to `verifyPersistence` so the issued record carries
+     * `before: {entityAbsent}`. Phase 1: requires the supervisor-issued
+     * session credential — the snapshot belongs to the open test session.
+     */
+    async preObserve(request) {
+        return this.request('/witness/pre-observation', request);
+    }
+    /**
+     * POST /witness/http-observation (ADR 0004 D7, plan §8 / D1):
+     * consumes one witness-observed HTTP exchange matching (method, path)
+     * and issues witnessed `http.request` records for the declaring
+     * test's claimed obligations. Phase 1: the caller must hold a valid
+     * OPEN session and only an exchange observed through THAT session's
+     * proxy prefix within one of its recorded action intervals can be
+     * consumed — the claim set may be given as `claimIds`, or as the
+     * singular legacy `claimId`/`obligationId` pair (folded in by the
+     * server; a split assignment with distinct values is refused with 400).
+     */
+    async observeHttp(request) {
+        const body = await this.request('/witness/http-observation', request);
+        const records = Array.isArray(body['records'])
+            ? body['records']
+            : // Legacy single-record response shape.
+                [{ recordId: String(body['recordId'] ?? ''), obligationId: String(request.claimId ?? request.obligationId ?? '') }];
+        return {
+            recordId: String(body['recordId'] ?? records[0]?.recordId ?? ''),
+            runId: String(body['runId'] ?? ''),
+            trust: String(body['trust'] ?? ''),
+            status: typeof body['status'] === 'number' ? body['status'] : 0,
+            records,
+        };
+    }
+    /**
+     * POST /witness/persistence and record adapter wall time.
+     *
+     * Args:
+     *   request: persistence observation bound to a supervised test session.
+     *
+     * Returns:
+     *   Promise<PersistenceResponse>: the engine-side adapter result.
+     */
+    async verifyPersistence(request) {
+        const startedAt = performance.now();
+        try {
+            return await this.request('/witness/persistence', request);
+        }
+        finally {
+            recordPersistenceTiming(Math.round(performance.now() - startedAt), request.testId, process.env[ENV_STATE_DIR]);
+        }
+    }
+    /**
+     * POST /browser/surface (plan Phase 1 item 4): registers the
+     * consumer-declared surface descriptor + the app base the ENGINE must
+     * drive for this session. Validated engine-side (structure, loopback,
+     * fingerprint); selectors are locators only.
+     */
+    async registerBrowserSurface(request) {
+        return this.request('/browser/surface', request);
+    }
+    /**
+     * POST /browser/action (plan Phase 1 item 4): the ENGINE performs one
+     * constrained surface operation on its own page and returns its own
+     * observation (observed entity id, entered + rendered fields, app
+     * status, pre-observation id, issued record ids). Test code supplies
+     * intent only — it never touches the engine page.
+     */
+    async browserAction(request) {
+        return this.request('/browser/action', request);
+    }
+    /**
+     * POST /browser/visible (plan Phase 1 item 4): the ENGINE re-reads
+     * the rendered result for the engine-observed entity and returns the
+     * rendered fields.
+     */
+    async browserVisible(request) {
+        return this.request('/browser/visible', request);
+    }
+    /**
+     * POST /behavior/execute (plan 2026-09-19 Phase 6): asks the ENGINE to
+     * execute one approved behavior case. The call carries ONLY the
+     * allowed case id plus the session credential — actor material,
+     * expectations, and subjects resolve engine-side and are never
+     * readable or overridable here.
+     */
+    async proveCase(request) {
+        return this.request('/behavior/execute', request);
+    }
+    /**
+     * POST /behavior/principal (plan 2026-09-19 Phase 6): asks the ENGINE
+     * to drive the prepared execution's principal operation and seal the
+     * case record. Same credential-only boundary as `proveCase`.
+     */
+    async drivePrincipal(request) {
+        return this.request('/behavior/principal', request);
+    }
+    /** GET /records — the issued ledger for this run. */
+    async listRecords() {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await fetch(`${this.url}/records`, {
+                method: 'GET',
+                headers: { [RUN_HEADER]: this.token, accept: 'application/json' },
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            throw new WitnessRequestError(0, `witness call to /records failed: ${error.message}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = null;
+        }
+        if (!response.ok) {
+            const record = isObject(body) ? body : {};
+            throw new WitnessRequestError(response.status, typeof record['error'] === 'string' ? record['error'] : `witness answered HTTP ${response.status}`, typeof record['detail'] === 'string' ? record['detail'] : null);
+        }
+        const records = isObject(body) && Array.isArray(body['records']) ? body['records'] : [];
+        return { records: records };
+    }
+    async request(path, payload) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await fetch(`${this.url}${path}`, {
+                method: 'POST',
+                headers: {
+                    [RUN_HEADER]: this.token,
+                    'content-type': 'application/json',
+                    accept: 'application/json',
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            clearTimeout(timer);
+            throw new WitnessRequestError(0, `witness call to ${path} failed: ${error.message}`);
+        }
+        clearTimeout(timer);
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = null;
+        }
+        if (!response.ok) {
+            const record = isObject(body) ? body : {};
+            throw new WitnessRequestError(response.status, typeof record['error'] === 'string' ? record['error'] : `witness answered HTTP ${response.status}`, typeof record['detail'] === 'string' ? record['detail'] : null);
+        }
+        return body;
+    }
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=witness-client.js.map

package/dist/client/witness-client.js.map

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