@gate-forge/witness 0.0.0-stage → 0.8.0

package/dist/constants.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Shared constants of the Playwright evidence pack (pin #7, plan §5.3).
+ *
+ * These names are the wire contract between the fixture (test process),
+ * the reporter (runner process), and the witness service (engine
+ * process). They are also the documented env surface of `gateforge
+ * test-gates` (packages/cli/README.md "test-gates protocol") — the CLI
+ * already exports GATEFORGE_RUN_ID / GATEFORGE_RUN_TOKEN /
+ * GATEFORGE_STATE_DIR / GATEFORGE_OBLIGATIONS / GATEFORGE_WITNESS_URL;
+ * the pack augments the target/attestation/adapter surface below.
+ */
+/** Claim annotation type: `{type: 'gateforge', description: '<obligation id>'}`. */
+export declare const CLAIM_ANNOTATION_TYPE = "gateforge";
+/** Per-run auth header on every witness call (pin #7). */
+export declare const RUN_HEADER = "x-gateforge-run";
+/**
+ * Verifier auth header on the witness attestation surface
+ * (`GET /ledger-attestation` and the manifest MAC). Carries the
+ * verifier key — a secret the orchestrator shares with the witness and
+ * the evaluating CLI but NEVER with the tested suite (the suite's run
+ * token authorizes evidence submission; it must not authorize
+ * attestation, or a hostile suite could certify its own fabrications).
+ */
+export declare const VERIFIER_HEADER = "x-gateforge-verifier";
+/** Marker header the SUT (or its attestation proxy) must present. */
+export declare const ENV_FINGERPRINT_HEADER = "x-gateforge-env-fingerprint";
+/** Marker header the SUT (or its attestation proxy) may present. */
+export declare const ATTESTATION_SCOPE_HEADER = "x-gateforge-attestation-scope";
+/** Evidence kinds the witness /records endpoint accepts (plan §5.3). */
+export declare const UI_ACTION_KIND = "ui.action";
+export declare const UI_VISIBLE_RESULT_KIND = "ui.visible-result";
+export declare const PERSISTENCE_KIND = "persistence.entity";
+/**
+ * Observe-channel persistence kind (Phase 2): issued ONLY by the
+ * witness's observe finalize (engine-side proxy capture + adapter
+ * read) — never suite-submittable (`/records` rejects it like every
+ * persistence kind) and never engine-driven.
+ */
+export declare const OBSERVED_KIND = "persistence.observed";
+export declare const KNOWN_RECORD_KINDS: readonly string[];
+/** Persistence kinds are ONLY issued by the witness (engine-side adapter reads). */
+export declare const KNOWN_PERSISTENCE_KINDS: readonly string[];
+/** Env the CLI test-gates suite already receives (documented contract). */
+export declare const ENV_RUN_ID = "GATEFORGE_RUN_ID";
+export declare const ENV_RUN_TOKEN = "GATEFORGE_RUN_TOKEN";
+export declare const ENV_STATE_DIR = "GATEFORGE_STATE_DIR";
+export declare const ENV_OBLIGATIONS = "GATEFORGE_OBLIGATIONS";
+export declare const ENV_WITNESS_URL = "GATEFORGE_WITNESS_URL";
+/** Pack-extended env surface (documented in this package's README). */
+export declare const ENV_APP_BASE_URL = "GATEFORGE_APP_BASE_URL";
+export declare const ENV_TARGET_BASE_URL = "GATEFORGE_TARGET_BASE_URL";
+export declare const ENV_TARGET_FINGERPRINT = "GATEFORGE_TARGET_FINGERPRINT";
+export declare const ENV_ADAPTERS_DIR = "GATEFORGE_ADAPTERS_DIR";
+export declare const ENV_CLASSIFICATIONS = "GATEFORGE_CLASSIFICATIONS";
+export declare const ENV_ADAPTER_BASE_URL = "GATEFORGE_ADAPTER_BASE_URL";
+/**
+ * Timing-chaos surface (E63): the SEEDED release plan the observation
+ * proxy applies to proxied app responses. Set by
+ * `gateforge test-gates --chaos <seed>` on the SPAWNED witness only —
+ * absent means the byte-identical no-chaos path. The seed is the switch;
+ * the other two only tune its bounds.
+ */
+export declare const ENV_CHAOS_SEED = "GATEFORGE_CHAOS_SEED";
+/** Upper bound of every applied chaos delay, in whole milliseconds. */
+export declare const ENV_CHAOS_MAX_DELAY_MS = "GATEFORGE_CHAOS_MAX_DELAY_MS";
+/** Whether a later response may be released before an earlier one. */
+export declare const ENV_CHAOS_REORDER = "GATEFORGE_CHAOS_REORDER";
+/**
+ * Twin path coverage (E64): the observation-only shape recording a run
+ * turns on with `enforcement.twinPaths`. Set by the orchestrating CLI
+ * on the SPAWNED witness only; absent means no proxy wiring, no
+ * recorded shape and a byte-identical run.
+ */
+export declare const ENV_TWIN_SHAPES = "GATEFORGE_TWIN_SHAPES";
+/**
+ * Owner-declared query keys whose VALUES a recorded twin shape may
+ * carry (`enforcement.twinQueryKeys`). Absent or empty = keys only, so
+ * a non-allowlisted value can never reach a report or the state
+ * directory.
+ */
+export declare const ENV_TWIN_QUERY_KEYS = "GATEFORGE_TWIN_QUERY_KEYS";
+/**
+ * Absolute path to the engine-written route inventory the shapes
+ * resolve against (so a shape names a route template, never a concrete
+ * id). Absent = the identifier-blind fallback, never a raw path.
+ */
+export declare const ENV_TWIN_INVENTORY = "GATEFORGE_TWIN_INVENTORY";
+/** Observation proxy target (loopback base URL the proxy forwards to). */
+export declare const ENV_PROXY_TARGET = "GATEFORGE_PROXY_TARGET";
+/**
+ * Observation-proxy mount prefix (e.g. `/api`): the browser-facing path
+ * prefix a frontend dev proxy adds before backend routes. The proxy
+ * strips it before forwarding and before recording observations, so
+ * records match backend-derived obligation identities.
+ */
+export declare const ENV_MOUNT_PATH = "GATEFORGE_MOUNT_PATH";
+/**
+ * Verifier key for the witness attestation surface. Environment ONLY —
+ * never argv (a process's cmdline is world-readable via /proc), and
+ * never exported to the tested suite. Same variable the orchestrating
+ * CLI reads (`gateforge test-gates`).
+ */
+export declare const ENV_WITNESS_VERIFIER_KEY = "GATEFORGE_WITNESS_VERIFIER_KEY";
+/**
+ * Operator-provided trusted fixture/actor provider (plan 2026-09-25
+ * Phase 2): an absolute path to a `fixture-provider.mjs` module (or the
+ * directory holding it) whose default export implements the
+ * `FixtureProvider` interface. It is the ONLY source of case fixtures
+ * and actor credentials, so it is read engine-side here and never
+ * travels to the suite. Absent (the default) strong behavior cases
+ * block with a typed cause instead of falling back to suite-supplied
+ * fixtures.
+ */
+export declare const ENV_FIXTURE_PROVIDER = "GATEFORGE_FIXTURE_PROVIDER";
+/** Opt-in reporter exit-code semantics (standalone runs only). */
+export declare const ENV_REPORTER_FAIL_RUN = "GATEFORGE_REPORTER_FAIL_RUN";
+/**
+ * Absolute path of the runner-outcomes document the gateforge reporter
+ * writes for trusted runner supervision (plan Phase 4 item 4, ADR 0005
+ * D2): per-instance outcomes, attempts, expected failures, and the
+ * run-level fixture/teardown outcome. Set by the supervised adapter
+ * (`test-gates --changed`); when absent the reporter writes nothing —
+ * supervision then fails closed on the missing outcomes file.
+ */
+export declare const ENV_OUTCOMES_FILE = "GATEFORGE_OUTCOMES_FILE";
+/**
+ * Run-state file (written by the orchestrating CLI) carrying the mapped
+ * obligation claims for sidecar/native-mapped tests, keyed by
+ * `<file>#<titlePath.join('>')>` (the reconciliation key). The reporter
+ * carries these claims on the session-open path (Phase 4 claim
+ * injection) so their evidence lands on the right claims; native
+ * annotations keep working unchanged.
+ */
+export declare const CLAIM_INJECTIONS_FILE = "claim-injections.json";
+/** Run-state file carrying the sealed supervision execution result. */
+export declare const EXECUTION_RESULT_FILE = "execution-result.json";
+/**
+ * Run-state spool directory (enforcement-review fix 3): the runner-side
+ * reporter writes test lifecycle events (testBegin/testEnd with outcome)
+ * as NUL-safe JSON lines under `<stateDir>/spool/<runId>/`; the trusted
+ * CLI drains them and performs the witness supervisor calls (session
+ * open/close) with credentials that exist ONLY in the CLI process. The
+ * runner child holds no supervisor rights.
+ */
+export declare const SPOOL_DIR_NAME = "spool";
+/** The spool's event file (JSON lines; consumed by the CLI drain loop). */
+export declare const SPOOL_EVENTS_FILE = "events.jsonl";
+/**
+ * The spool's persistence-claim-intent file (JSON lines; same NUL-safe
+ * line protocol as `events.jsonl`): the supervised (UNTRUSTED) test
+ * process reports claim INTENTS here — {entity, operation, phase, intent,
+ * key, claimId, testId, sequence}. The suite can only write intents; it
+ * can NEVER stamp evidence. The trusted CLI's spool drain forwards each
+ * intent to the witness over the verifier-key supervisor surface, where
+ * the resource's adapter SERVER PROBE runs (witness-side) and — only
+ * then — a witnessed `persistence.entity` record stamped
+ * `channel: 'server'` may be issued.
+ */
+export declare const SPOOL_INTENTS_FILE = "persistence-intents.jsonl";
+/**
+ * Payload discriminant the witness stamps on server-probed persistence
+ * records (core's verdict engine keys the server-witnessed channel off
+ * this + {@link SERVER_E2E_TEST_KIND}).
+ */
+export declare const SERVER_CHANNEL = "server";
+/** The mapping kind that unlocks the server-witnessed channel. */
+export declare const SERVER_E2E_TEST_KIND = "server-e2e";
+/**
+ * Payload discriminant the witness stamps on observe-finalized
+ * persistence records (Observe channel, Phase 2: core's verdict engine
+ * keys the observe branch off this channel on `persistence.observed`
+ * records).
+ */
+export declare const OBSERVE_CHANNEL = "observe";
+/** The mapping kind that unlocks the Observe channel. */
+export declare const OBSERVED_E2E_TEST_KIND = "observed-e2e";
+/** Run-state file carrying the authenticated gate receipt. */
+export declare const GATE_RECEIPT_FILE = "receipt.json";
+/** Run-state diagnostics report (plan §3.5; never witness evidence). */
+export declare const DIAGNOSTICS_REPORT_FILE = "diagnostics.json";
+/** Witness file inside the state dir carrying the spawned URL. */
+export declare const WITNESS_URL_FILE = "witness-url.json";
+/** Default per-witness-call timeout (pin #7: 5s). */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 5000;
+/** The loopback hostname the witness, proxy, and fixture servers bind. */
+export declare const LOOPBACK_HOSTNAME = "127.0.0.1";
+/** Loopback-equivalent hostnames the witness accepts as attestation subjects. */
+export declare const LOOPBACK_HOSTS: Record<string, true>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

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

package/dist/constants.js

@@ -0,0 +1,197 @@
+/**
+ * Shared constants of the Playwright evidence pack (pin #7, plan §5.3).
+ *
+ * These names are the wire contract between the fixture (test process),
+ * the reporter (runner process), and the witness service (engine
+ * process). They are also the documented env surface of `gateforge
+ * test-gates` (packages/cli/README.md "test-gates protocol") — the CLI
+ * already exports GATEFORGE_RUN_ID / GATEFORGE_RUN_TOKEN /
+ * GATEFORGE_STATE_DIR / GATEFORGE_OBLIGATIONS / GATEFORGE_WITNESS_URL;
+ * the pack augments the target/attestation/adapter surface below.
+ */
+/** Claim annotation type: `{type: 'gateforge', description: '<obligation id>'}`. */
+export const CLAIM_ANNOTATION_TYPE = 'gateforge';
+/** Per-run auth header on every witness call (pin #7). */
+export const RUN_HEADER = 'x-gateforge-run';
+/**
+ * Verifier auth header on the witness attestation surface
+ * (`GET /ledger-attestation` and the manifest MAC). Carries the
+ * verifier key — a secret the orchestrator shares with the witness and
+ * the evaluating CLI but NEVER with the tested suite (the suite's run
+ * token authorizes evidence submission; it must not authorize
+ * attestation, or a hostile suite could certify its own fabrications).
+ */
+export const VERIFIER_HEADER = 'x-gateforge-verifier';
+/** Marker header the SUT (or its attestation proxy) must present. */
+export const ENV_FINGERPRINT_HEADER = 'x-gateforge-env-fingerprint';
+/** Marker header the SUT (or its attestation proxy) may present. */
+export const ATTESTATION_SCOPE_HEADER = 'x-gateforge-attestation-scope';
+/** Evidence kinds the witness /records endpoint accepts (plan §5.3). */
+export const UI_ACTION_KIND = 'ui.action';
+export const UI_VISIBLE_RESULT_KIND = 'ui.visible-result';
+export const PERSISTENCE_KIND = 'persistence.entity';
+/**
+ * Observe-channel persistence kind (Phase 2): issued ONLY by the
+ * witness's observe finalize (engine-side proxy capture + adapter
+ * read) — never suite-submittable (`/records` rejects it like every
+ * persistence kind) and never engine-driven.
+ */
+export const OBSERVED_KIND = 'persistence.observed';
+export const KNOWN_RECORD_KINDS = [
+    UI_ACTION_KIND,
+    UI_VISIBLE_RESULT_KIND,
+];
+/** Persistence kinds are ONLY issued by the witness (engine-side adapter reads). */
+export const KNOWN_PERSISTENCE_KINDS = [PERSISTENCE_KIND, OBSERVED_KIND];
+/** Env the CLI test-gates suite already receives (documented contract). */
+export const ENV_RUN_ID = 'GATEFORGE_RUN_ID';
+export const ENV_RUN_TOKEN = 'GATEFORGE_RUN_TOKEN';
+export const ENV_STATE_DIR = 'GATEFORGE_STATE_DIR';
+export const ENV_OBLIGATIONS = 'GATEFORGE_OBLIGATIONS';
+export const ENV_WITNESS_URL = 'GATEFORGE_WITNESS_URL';
+/** Pack-extended env surface (documented in this package's README). */
+export const ENV_APP_BASE_URL = 'GATEFORGE_APP_BASE_URL';
+export const ENV_TARGET_BASE_URL = 'GATEFORGE_TARGET_BASE_URL';
+export const ENV_TARGET_FINGERPRINT = 'GATEFORGE_TARGET_FINGERPRINT';
+export const ENV_ADAPTERS_DIR = 'GATEFORGE_ADAPTERS_DIR';
+export const ENV_CLASSIFICATIONS = 'GATEFORGE_CLASSIFICATIONS';
+export const ENV_ADAPTER_BASE_URL = 'GATEFORGE_ADAPTER_BASE_URL';
+/**
+ * Timing-chaos surface (E63): the SEEDED release plan the observation
+ * proxy applies to proxied app responses. Set by
+ * `gateforge test-gates --chaos <seed>` on the SPAWNED witness only —
+ * absent means the byte-identical no-chaos path. The seed is the switch;
+ * the other two only tune its bounds.
+ */
+export const ENV_CHAOS_SEED = 'GATEFORGE_CHAOS_SEED';
+/** Upper bound of every applied chaos delay, in whole milliseconds. */
+export const ENV_CHAOS_MAX_DELAY_MS = 'GATEFORGE_CHAOS_MAX_DELAY_MS';
+/** Whether a later response may be released before an earlier one. */
+export const ENV_CHAOS_REORDER = 'GATEFORGE_CHAOS_REORDER';
+/**
+ * Twin path coverage (E64): the observation-only shape recording a run
+ * turns on with `enforcement.twinPaths`. Set by the orchestrating CLI
+ * on the SPAWNED witness only; absent means no proxy wiring, no
+ * recorded shape and a byte-identical run.
+ */
+export const ENV_TWIN_SHAPES = 'GATEFORGE_TWIN_SHAPES';
+/**
+ * Owner-declared query keys whose VALUES a recorded twin shape may
+ * carry (`enforcement.twinQueryKeys`). Absent or empty = keys only, so
+ * a non-allowlisted value can never reach a report or the state
+ * directory.
+ */
+export const ENV_TWIN_QUERY_KEYS = 'GATEFORGE_TWIN_QUERY_KEYS';
+/**
+ * Absolute path to the engine-written route inventory the shapes
+ * resolve against (so a shape names a route template, never a concrete
+ * id). Absent = the identifier-blind fallback, never a raw path.
+ */
+export const ENV_TWIN_INVENTORY = 'GATEFORGE_TWIN_INVENTORY';
+/** Observation proxy target (loopback base URL the proxy forwards to). */
+export const ENV_PROXY_TARGET = 'GATEFORGE_PROXY_TARGET';
+/**
+ * Observation-proxy mount prefix (e.g. `/api`): the browser-facing path
+ * prefix a frontend dev proxy adds before backend routes. The proxy
+ * strips it before forwarding and before recording observations, so
+ * records match backend-derived obligation identities.
+ */
+export const ENV_MOUNT_PATH = 'GATEFORGE_MOUNT_PATH';
+/**
+ * Verifier key for the witness attestation surface. Environment ONLY —
+ * never argv (a process's cmdline is world-readable via /proc), and
+ * never exported to the tested suite. Same variable the orchestrating
+ * CLI reads (`gateforge test-gates`).
+ */
+export const ENV_WITNESS_VERIFIER_KEY = 'GATEFORGE_WITNESS_VERIFIER_KEY';
+/**
+ * Operator-provided trusted fixture/actor provider (plan 2026-09-25
+ * Phase 2): an absolute path to a `fixture-provider.mjs` module (or the
+ * directory holding it) whose default export implements the
+ * `FixtureProvider` interface. It is the ONLY source of case fixtures
+ * and actor credentials, so it is read engine-side here and never
+ * travels to the suite. Absent (the default) strong behavior cases
+ * block with a typed cause instead of falling back to suite-supplied
+ * fixtures.
+ */
+export const ENV_FIXTURE_PROVIDER = 'GATEFORGE_FIXTURE_PROVIDER';
+/** Opt-in reporter exit-code semantics (standalone runs only). */
+export const ENV_REPORTER_FAIL_RUN = 'GATEFORGE_REPORTER_FAIL_RUN';
+/**
+ * Absolute path of the runner-outcomes document the gateforge reporter
+ * writes for trusted runner supervision (plan Phase 4 item 4, ADR 0005
+ * D2): per-instance outcomes, attempts, expected failures, and the
+ * run-level fixture/teardown outcome. Set by the supervised adapter
+ * (`test-gates --changed`); when absent the reporter writes nothing —
+ * supervision then fails closed on the missing outcomes file.
+ */
+export const ENV_OUTCOMES_FILE = 'GATEFORGE_OUTCOMES_FILE';
+/**
+ * Run-state file (written by the orchestrating CLI) carrying the mapped
+ * obligation claims for sidecar/native-mapped tests, keyed by
+ * `<file>#<titlePath.join('>')>` (the reconciliation key). The reporter
+ * carries these claims on the session-open path (Phase 4 claim
+ * injection) so their evidence lands on the right claims; native
+ * annotations keep working unchanged.
+ */
+export const CLAIM_INJECTIONS_FILE = 'claim-injections.json';
+/** Run-state file carrying the sealed supervision execution result. */
+export const EXECUTION_RESULT_FILE = 'execution-result.json';
+/**
+ * Run-state spool directory (enforcement-review fix 3): the runner-side
+ * reporter writes test lifecycle events (testBegin/testEnd with outcome)
+ * as NUL-safe JSON lines under `<stateDir>/spool/<runId>/`; the trusted
+ * CLI drains them and performs the witness supervisor calls (session
+ * open/close) with credentials that exist ONLY in the CLI process. The
+ * runner child holds no supervisor rights.
+ */
+export const SPOOL_DIR_NAME = 'spool';
+/** The spool's event file (JSON lines; consumed by the CLI drain loop). */
+export const SPOOL_EVENTS_FILE = 'events.jsonl';
+/**
+ * The spool's persistence-claim-intent file (JSON lines; same NUL-safe
+ * line protocol as `events.jsonl`): the supervised (UNTRUSTED) test
+ * process reports claim INTENTS here — {entity, operation, phase, intent,
+ * key, claimId, testId, sequence}. The suite can only write intents; it
+ * can NEVER stamp evidence. The trusted CLI's spool drain forwards each
+ * intent to the witness over the verifier-key supervisor surface, where
+ * the resource's adapter SERVER PROBE runs (witness-side) and — only
+ * then — a witnessed `persistence.entity` record stamped
+ * `channel: 'server'` may be issued.
+ */
+export const SPOOL_INTENTS_FILE = 'persistence-intents.jsonl';
+/**
+ * Payload discriminant the witness stamps on server-probed persistence
+ * records (core's verdict engine keys the server-witnessed channel off
+ * this + {@link SERVER_E2E_TEST_KIND}).
+ */
+export const SERVER_CHANNEL = 'server';
+/** The mapping kind that unlocks the server-witnessed channel. */
+export const SERVER_E2E_TEST_KIND = 'server-e2e';
+/**
+ * Payload discriminant the witness stamps on observe-finalized
+ * persistence records (Observe channel, Phase 2: core's verdict engine
+ * keys the observe branch off this channel on `persistence.observed`
+ * records).
+ */
+export const OBSERVE_CHANNEL = 'observe';
+/** The mapping kind that unlocks the Observe channel. */
+export const OBSERVED_E2E_TEST_KIND = 'observed-e2e';
+/** Run-state file carrying the authenticated gate receipt. */
+export const GATE_RECEIPT_FILE = 'receipt.json';
+/** Run-state diagnostics report (plan §3.5; never witness evidence). */
+export const DIAGNOSTICS_REPORT_FILE = 'diagnostics.json';
+/** Witness file inside the state dir carrying the spawned URL. */
+export const WITNESS_URL_FILE = 'witness-url.json';
+/** Default per-witness-call timeout (pin #7: 5s). */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 5000;
+/** The loopback hostname the witness, proxy, and fixture servers bind. */
+export const LOOPBACK_HOSTNAME = '127.0.0.1';
+/** Loopback-equivalent hostnames the witness accepts as attestation subjects. */
+export const LOOPBACK_HOSTS = {
+    localhost: true,
+    '[::1]': true,
+    '::1': true,
+    '127.0.0.1': true,
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@gate-forge/witness` — the runner-neutral gateforge witness.
+ *
+ * Phase 0 of plan 2026-09-25 lands the runner-adapter contract and its
+ * conformance suite here, so the contract lives with the witness it
+ * serves rather than inside a package named after one runner. Later
+ * phases move the witness service itself (`witness/`), the per-test
+ * session client, and the non-Playwright runner adapters into this
+ * package; `@gate-forge/pack-playwright` re-exports them so existing
+ * imports keep working.
+ */
+export * from './adapter/index.js';
+export * from './witness/chaos.js';
+export * from './witness/twin-shapes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,cAAc,oBAAoB,CAAC;AAInC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * `@gate-forge/witness` — the runner-neutral gateforge witness.
+ *
+ * Phase 0 of plan 2026-09-25 lands the runner-adapter contract and its
+ * conformance suite here, so the contract lives with the witness it
+ * serves rather than inside a package named after one runner. Later
+ * phases move the witness service itself (`witness/`), the per-test
+ * session client, and the non-Playwright runner adapters into this
+ * package; `@gate-forge/pack-playwright` re-exports them so existing
+ * imports keep working.
+ */
+export * from './adapter/index.js';
+// The seeded timing-chaos plan (E63). Exported so a run's schedule can
+// be recomputed from (seed, session, route key, k) without replaying
+// the whole suite - that is what makes a finding reproducible.
+export * from './witness/chaos.js';
+// The observation-only twin shape plan (E64). Exported so a caller can
+// compute a run's own shapes from the same vocabulary the proxy records.
+export * from './witness/twin-shapes.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,cAAc,oBAAoB,CAAC;AACnC,uEAAuE;AACvE,qEAAqE;AACrE,+DAA+D;AAC/D,cAAc,oBAAoB,CAAC;AACnC,uEAAuE;AACvE,yEAAyE;AACzE,cAAc,0BAA0B,CAAC"}

package/dist/json.d.ts

@@ -0,0 +1,16 @@
+/**
+ * GF-canonical-JSON serialization for witness/reporter payloads.
+ *
+ * All hashes, state artifacts, and comparisons in the pack must go
+ * through the pin-#1 canonical form. The frozen core `canonicalJson`
+ * requires a compile-time `JsonValue`; wire payloads and adapter
+ * responses arrive as `unknown`, so this module re-checks with the core
+ * `isJsonValue` guard and renders the canonical form (or throws — a
+ * non-JSON payload is a contract violation, never a silent truncation).
+ */
+import { isJsonValue } from '@gate-forge/core';
+/** Throws unless the value is JSON-representable, then canonicalizes it. */
+export declare function canonicalOf(value: unknown): string;
+/** JSON-representable check for wire payloads before hashing. */
+export { isJsonValue };
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAiB,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE9D,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKlD;AAED,iEAAiE;AACjE,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/json.js

@@ -0,0 +1,21 @@
+/**
+ * GF-canonical-JSON serialization for witness/reporter payloads.
+ *
+ * All hashes, state artifacts, and comparisons in the pack must go
+ * through the pin-#1 canonical form. The frozen core `canonicalJson`
+ * requires a compile-time `JsonValue`; wire payloads and adapter
+ * responses arrive as `unknown`, so this module re-checks with the core
+ * `isJsonValue` guard and renders the canonical form (or throws — a
+ * non-JSON payload is a contract violation, never a silent truncation).
+ */
+import { canonicalJson, isJsonValue } from '@gate-forge/core';
+/** Throws unless the value is JSON-representable, then canonicalizes it. */
+export function canonicalOf(value) {
+    if (!isJsonValue(value)) {
+        throw new TypeError('value is not GF-canonical-JSON-representable');
+    }
+    return canonicalJson(value);
+}
+/** JSON-representable check for wire payloads before hashing. */
+export { isJsonValue };
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE9D,4EAA4E;AAC5E,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,iEAAiE;AACjE,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/queue/bullmq.d.ts

@@ -0,0 +1,28 @@
+import { type QueueObserverConfig } from '@gate-forge/core';
+import { type QueueChannel } from './observer.js';
+/** The queue job payload key carrying the engine's delivery identity. */
+export declare const DELIVERY_ID_KEY = "gateforgeDeliveryId";
+/** The queue job payload key carrying the engine's idempotency key. */
+export declare const IDEMPOTENCY_KEY_KEY = "gateforgeIdempotencyKey";
+/** The BullMQ job name every engine-produced delivery carries. */
+export declare const BULLMQ_DELIVERY_JOB_NAME = "gateforge-delivery";
+/** The BullMQ connection material (host/port, or a Redis URL). */
+export type BullmqConnection = {
+    host: string;
+    port: number;
+} | {
+    url: string;
+};
+/**
+ * Opens the BullMQ channel over one connection. One `Queue` handle per
+ * declared queue; every handle is closed exactly once.
+ *
+ * Args:
+ *   config: the validated engine-owned configuration.
+ *   connection: host/port or URL connection material.
+ *
+ * Returns:
+ *   QueueChannel: the opened observer + deliverer.
+ */
+export declare function createBullmqChannel(config: QueueObserverConfig, connection: BullmqConnection): QueueChannel;
+//# sourceMappingURL=bullmq.d.ts.map

package/dist/queue/bullmq.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bullmq.d.ts","sourceRoot":"","sources":["../../src/queue/bullmq.ts"],"names":[],"mappings":"AAeA,OAAO,EAOL,KAAK,mBAAmB,EACzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAGL,KAAK,YAAY,EAKlB,MAAM,eAAe,CAAC;AAevB,yEAAyE;AACzE,eAAO,MAAM,eAAe,wBAAwB,CAAC;AAErD,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,4BAA4B,CAAC;AAmB7D,kEAAkE;AAClE,eAAO,MAAM,wBAAwB,uBAAuB,CAAC;AAE7D,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAwDhF;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,EAAE,UAAU,EAAE,gBAAgB,GAAG,YAAY,CA2G3G"}