@gate-forge/witness 0.0.0-stage → 0.8.0

package/dist/witness/adapter-registry.js

@@ -0,0 +1,370 @@
+/**
+ * Adapter loading + registry (pin #8, plan §5.4).
+ *
+ * Reviewed evidence adapters load from `.gateforge/adapters/<name>.mjs`
+ * at WITNESS START (engine-side — the test process never imports them).
+ * Default export contract:
+ *
+ * ```js
+ * export default {
+ *   read: async (ctx, id) => body | null,   // GET-only; ctx.get(path) is the transport
+ *   normalize: (body) => ({ entityId, fields }), // stamped from the RESPONSE, never caller args
+ *   deletion: 'hard' | 'archive',
+ *   fields: ['id', 'name'],                     // optional normalized field projection
+ *   baseUrl: 'http://…',                    // optional override of the witness's adapter base
+ *   identity: 'natural-key',                  // optional entity-scoped create absence proof
+ *   list: async (ctx) => bodies,            // optional: powers create pre-observations + Observe snapshots
+ *   observe: {                              // optional: Observe-channel mutation bindings (Phase 2)
+ *     create: { method: 'POST', path: '/api/v2/accounts' },
+ *     update: { method: 'PATCH', path: '/api/v2/accounts/{id}' },
+ *   },
+ *   probeServer: async (ctx, subject) => ({ found, fields }), // optional: the
+ *                          // SERVER-WITNESSED persistence channel probe — executed
+ *                          // ONLY in this trusted witness process
+ * };
+ * ```
+ *
+ * The registry loads fail-closed: a missing/invalid module, a missing
+ * `read`/`normalize`/`deletion`/`environmentFingerprint`, an unknown
+ * deletion value, or a duplicate name aborts witness startup with an
+ * actionable diagnostic naming the file. The registry is frozen after
+ * load — there is no registration path a test could reach (invariant 6,
+ * GF-11 "registration path does not exist").
+ */
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Loads every `.mjs` adapter in `dir` into a frozen registry.
+ *
+ * Args:
+ *   dir: the configured adapters directory (absolute).
+ *
+ * Returns:
+ *   Map<string, EvidenceAdapter>: keyed by the file basename sans `.mjs`.
+ *
+ * Throws:
+ *   AdapterRegistryError: fail-closed load problems — unreadable dir,
+ *     unimportable module, or a module missing any contract member.
+ */
+export async function loadAdapters(dir) {
+    const registry = new Map();
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            // No adapters directory at all: the registry stays empty; the
+            // witness then answers 400 for every persistence request (a run
+            // with persistence obligations and no adapters is misconfigured).
+            return registry;
+        }
+        throw new AdapterRegistryError(`cannot read adapters directory '${dir}': ${error.message}`);
+    }
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith('.mjs'))
+            continue;
+        const name = entry.slice(0, -'.mjs'.length);
+        if (registry.has(name)) {
+            throw new AdapterRegistryError(`duplicate adapter '${name}' (multiple '${entry}' files is a config error)`);
+        }
+        const module = await importAdapter(dir, entry, name);
+        const adapter = validateAdapter(module, name);
+        registry.set(name, adapter);
+    }
+    return Object.freeze(registry);
+}
+/** Imports one adapter module; import errors carry an actionable message. */
+async function importAdapter(dir, entry, name) {
+    try {
+        const loaded = (await import(pathToFileURL(join(dir, entry)).href));
+        return loaded.default;
+    }
+    catch (error) {
+        throw new AdapterRegistryError(`adapter '${name}' (${join(dir, entry)}) could not be imported: ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Validates one adapter module against the pin-#8 contract.
+ *
+ * Args:
+ *   module: the default export of the adapter file.
+ *   name: adapter name, used in diagnostics.
+ *
+ * Returns:
+ *   EvidenceAdapter: the validated adapter.
+ *
+ * Throws:
+ *   AdapterRegistryError: when any required member is missing or shaped
+ *   wrong. Optional `baseUrl`, `identity`, and `fields` refine read and
+ *   create-proof capabilities without changing adapters that omit them.
+ */
+export function validateAdapter(module, name) {
+    if (typeof module !== 'object' || module === null) {
+        throw new AdapterRegistryError(`adapter '${name}' must default-export an object {read, normalize, deletion, environmentFingerprint}`);
+    }
+    const adapter = module;
+    const problems = [];
+    if (typeof adapter['read'] !== 'function')
+        problems.push('read must be an async function (ctx, id)');
+    if (typeof adapter['normalize'] !== 'function')
+        problems.push('normalize must be a function (body) => {entityId, fields}');
+    if (adapter['deletion'] !== 'hard' && adapter['deletion'] !== 'archive') {
+        problems.push("deletion must be 'hard' or 'archive'");
+    }
+    if (typeof adapter['environmentFingerprint'] !== 'string') {
+        problems.push('environmentFingerprint must be a string');
+    }
+    if (adapter['baseUrl'] !== undefined &&
+        (typeof adapter['baseUrl'] !== 'string' || adapter['baseUrl'].length === 0)) {
+        problems.push('baseUrl must be a non-empty string when present');
+    }
+    if (adapter['identity'] !== undefined && adapter['identity'] !== 'natural-key') {
+        problems.push("identity must be 'natural-key' when present");
+    }
+    if (adapter['list'] !== undefined && typeof adapter['list'] !== 'function') {
+        problems.push('list must be a function (ctx) => entity[] when present');
+    }
+    if (adapter['fields'] !== undefined &&
+        (!Array.isArray(adapter['fields']) ||
+            adapter['fields'].some((field) => typeof field !== 'string' || field.length === 0) ||
+            new Set(adapter['fields']).size !== adapter['fields'].length)) {
+        problems.push('fields must be an array of unique non-empty field names when present');
+    }
+    if (adapter['volatileFields'] !== undefined &&
+        (!Array.isArray(adapter['volatileFields']) ||
+            adapter['volatileFields'].some((field) => typeof field !== 'string' || field.length === 0) ||
+            new Set(adapter['volatileFields']).size !== adapter['volatileFields'].length)) {
+        problems.push('volatileFields must be an array of unique non-empty field names when present');
+    }
+    // Server probe (server-witnessed persistence channel): OPTIONAL — an
+    // adapter without it simply cannot serve the channel and every server
+    // intent for the resource resolves to a typed
+    // SERVER_PROBE_UNAVAILABLE failure. A PRESENT but malformed export is
+    // a contract violation caught here at load, fail-closed, not at
+    // intent time.
+    if (adapter['probeServer'] !== undefined && typeof adapter['probeServer'] !== 'function') {
+        problems.push('probeServer must be an async function (ctx, subject) => {found, fields} when present');
+    }
+    // Observe binding (Observe channel, Phase 2): OPTIONAL — an adapter
+    // without it serves no observe obligation. Present-but-malformed is a
+    // load-time contract violation (fail closed), validated by
+    // validateObserveBinding below.
+    if (adapter['observe'] !== undefined) {
+        const observeProblem = validateObserveBinding(adapter['observe']);
+        if (observeProblem !== null)
+            problems.push(observeProblem);
+    }
+    // Trusted scope/barrier observation (plan 2026-09-19 §4.4, Phase 4):
+    // OPTIONAL — adapters lacking these methods still serve legacy proofs
+    // but cannot satisfy strong contracts requiring scoped observation.
+    // Present-but-not-a-function is a load-time violation (fail closed).
+    if (adapter['snapshotScope'] !== undefined && typeof adapter['snapshotScope'] !== 'function') {
+        problems.push('snapshotScope must be an async function (ctx, {scope, fixtureNamespace}) => ScopeSnapshot when present');
+    }
+    if (adapter['awaitBarrier'] !== undefined && typeof adapter['awaitBarrier'] !== 'function') {
+        problems.push('awaitBarrier must be an async function (ctx, {scope, fixtureNamespace, operationId, deadlineMs}) when present');
+    }
+    if (problems.length > 0) {
+        throw new AdapterRegistryError(`adapter '${name}' violates the adapter contract: ${problems.join('; ')}`);
+    }
+    return {
+        read: adapter['read'],
+        normalize: adapter['normalize'],
+        deletion: adapter['deletion'],
+        environmentFingerprint: adapter['environmentFingerprint'],
+        ...(adapter['identity'] !== undefined ? { identity: 'natural-key' } : {}),
+        baseUrl: adapter['baseUrl'],
+        ...(adapter['fields'] !== undefined
+            ? { fields: [...adapter['fields']] }
+            : {}),
+        ...(adapter['volatileFields'] !== undefined
+            ? { volatileFields: [...adapter['volatileFields']] }
+            : {}),
+        ...(adapter['list'] !== undefined
+            ? { list: adapter['list'] }
+            : {}),
+        ...(adapter['probeServer'] !== undefined
+            ? { probeServer: adapter['probeServer'] }
+            : {}),
+        ...(adapter['observe'] !== undefined
+            ? { observe: adapter['observe'] }
+            : {}),
+        ...(adapter['snapshotScope'] !== undefined
+            ? { snapshotScope: adapter['snapshotScope'] }
+            : {}),
+        ...(adapter['awaitBarrier'] !== undefined
+            ? { awaitBarrier: adapter['awaitBarrier'] }
+            : {}),
+    };
+}
+/** Fail-closed adapter-loading error (witness startup aborts). */
+export class AdapterRegistryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AdapterRegistryError';
+    }
+}
+/** Concrete HTTP methods an observe binding may name (uppercase). */
+const OBSERVE_METHODS = new Set([
+    'GET',
+    'HEAD',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'OPTIONS',
+]);
+/** Observe-eligible operations (the CRUD verbs the grader knows). */
+const OBSERVE_OPERATIONS = ['create', 'read', 'update', 'delete'];
+/**
+ * Validates one adapter's optional `observe` binding (Observe channel,
+ * Phase 2): a plain object with per-operation `{method, path}`
+ * entries. Method must be a concrete uppercase verb; path must be an
+ * absolute backend-facing path whose only template segment is `{id}` —
+ * required on read/update/delete (the entity-id carrier), forbidden on
+ * create (create ids come from the adapter list-diff, never from a
+ * path guess).
+ *
+ * Args:
+ *   value: the adapter's `observe` export.
+ *
+ * Returns:
+ *   string | null: the contract-violation description, or null when valid.
+ */
+export function validateObserveBinding(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return 'observe must be an object {create?/read?/update?/delete?: {method, path}} when present';
+    }
+    const binding = value;
+    for (const key of Object.keys(binding)) {
+        if (!OBSERVE_OPERATIONS.includes(key)) {
+            return `observe carries unknown operation '${key}' (allowed: ${OBSERVE_OPERATIONS.join(', ')})`;
+        }
+    }
+    for (const operation of OBSERVE_OPERATIONS) {
+        const entry = binding[operation];
+        if (entry === undefined)
+            continue;
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            return `observe.${operation} must be {method, path}`;
+        }
+        const { method, path } = entry;
+        if (typeof method !== 'string' || !OBSERVE_METHODS.has(method)) {
+            return (`observe.${operation}.method must be a concrete uppercase HTTP verb ` +
+                `(${[...OBSERVE_METHODS].sort().join(', ')})`);
+        }
+        if (typeof path !== 'string' || !path.startsWith('/')) {
+            return `observe.${operation}.path must be an absolute backend-facing path starting with '/'`;
+        }
+        if (path.includes('//') || /[\s?#]/.test(path)) {
+            return `observe.${operation}.path must be a plain path template (no duplicate slashes, query, fragment, or whitespace)`;
+        }
+        const segments = path.split('/').filter((segment) => segment.length > 0);
+        const idSegments = segments.filter((segment) => segment === '{id}').length;
+        const braced = segments.filter((segment) => segment.startsWith('{') || segment.endsWith('}'));
+        if (braced.length !== idSegments) {
+            return `observe.${operation}.path may template only the '{id}' segment (got '${path}')`;
+        }
+        if (operation === 'create' && idSegments > 0) {
+            return `observe.create.path must not template '{id}' (create ids come from the adapter list-diff, got '${path}')`;
+        }
+        // Optional COLLECTION read shape (declared, never inferred): a
+        // real UI renders a LIST, so a read may name its entities in the
+        // returned rows instead of in the path. Only a read may declare
+        // it, only over GET, and never alongside the `{id}` template the
+        // by-id reader binds — every shape violation fails here, at load.
+        const collection = entry['collection'];
+        const declaresCollection = collection !== undefined;
+        if (declaresCollection) {
+            const problem = validateObserveCollection(collection, operation, method, path);
+            if (problem !== null)
+                return problem;
+        }
+        if (operation !== 'create' && idSegments !== 1 && !declaresCollection) {
+            return `observe.${operation}.path must carry exactly one '{id}' segment binding the entity id (got '${path}')`;
+        }
+    }
+    return null;
+}
+/**
+ * Validates one operation's optional `collection` declaration: the
+ * response shape whose ROWS name the entities an observe read credits.
+ * A collection read must be a `read` over `GET` on a path that carries
+ * no `{id}` template (the by-id reader owns that), and must declare the
+ * row `idKey`; `rowsKey` is optional and its absence declares that the
+ * response root is the row array. Every failure is a load-time
+ * contract violation — an adapter can never quietly fall back to
+ * inferring a collection from an arbitrary response body.
+ *
+ * Args:
+ *   value: the operation entry's `collection` export.
+ *   operation: the observe operation the declaration sits on.
+ *   method: the operation's already-validated HTTP method.
+ *   path: the operation's already-validated path template.
+ *
+ * Returns:
+ *   string | null: the contract-violation description, or null when valid.
+ */
+export function validateObserveCollection(value, operation, method, path) {
+    if (operation !== 'read') {
+        return (`observe.${operation}.collection is not supported — only a read renders a collection ` +
+            `(${operation} ids come from the list-diff or the '{id}' path segment)`);
+    }
+    if (method !== 'GET') {
+        return `observe.read.collection requires method 'GET' (got '${method}') — a collection is read, never written`;
+    }
+    if (path.split('/').includes('{id}')) {
+        return (`observe.read.collection must not be declared on a path carrying '{id}' (got '${path}') — a ` +
+            'by-id read and a collection read are two shapes, never one');
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return `observe.read.collection must be an object {idKey, rowsKey?}`;
+    }
+    const declaration = value;
+    for (const key of Object.keys(declaration)) {
+        if (key !== 'idKey' && key !== 'rowsKey') {
+            return `observe.read.collection carries unknown key '${key}' (allowed: idKey, rowsKey)`;
+        }
+    }
+    const idKey = declaration['idKey'];
+    if (typeof idKey !== 'string' || idKey.length === 0 || /[\s]/.test(idKey)) {
+        return "observe.read.collection.idKey must be a non-empty property name (the row field carrying the entity id)";
+    }
+    const rowsKey = declaration['rowsKey'];
+    if (rowsKey !== undefined && (typeof rowsKey !== 'string' || rowsKey.length === 0 || /[\s]/.test(rowsKey))) {
+        return ("observe.read.collection.rowsKey must be a non-empty property name when present (omit it when the " +
+            'response root is the row array)');
+    }
+    return null;
+}
+/**
+ * The transport the witness hands to adapter `read` calls (GET-only).
+ *
+ * Args:
+ *   baseUrl: the resolved read base.
+ *   resourceId: the resource this adapter serves.
+ *   get: the mediated GET primitive.
+ *   headers: engine-side read headers, when the run issues one.
+ *   session: the test session the read belongs to and the identity THAT
+ *     session registered (plan Phase 4b item 3b). Omitted for
+ *     engine-driven, probe and supervisor reads — those are not a test
+ *     session's read and must never inherit one.
+ *
+ * Returns:
+ *   AdapterContext: the frozen read context.
+ */
+export function makeAdapterContext(baseUrl, resourceId, get, headers, session) {
+    return Object.freeze({
+        baseUrl,
+        resourceId,
+        get,
+        ...(session !== undefined
+            ? { sessionId: session.sessionId, sessionIdentity: session.sessionIdentity }
+            : {}),
+        ...(headers ? { headers } : {}),
+    });
+}
+//# sourceMappingURL=adapter-registry.js.map

package/dist/witness/adapter-registry.js.map

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

package/dist/witness/behavior-request.d.ts

@@ -0,0 +1,80 @@
+import type { CredentialMaterial, FixtureLease } from './fixture-provider.js';
+/** Proof-input bound (request and response bodies alike). */
+export declare const BEHAVIOR_BODY_LIMIT_BYTES: number;
+/** Typed driver failure (always a blocking diagnostic, never proof). */
+export declare class BehaviorDriverError extends Error {
+    constructor(message: string);
+}
+/** Approved request action shape (subset used by the Phase 5 driver). */
+export interface BehaviorRequestAction {
+    kind: 'request';
+    method: string;
+    pathTemplate: string;
+    path: Record<string, {
+        from: string;
+        value?: unknown;
+        key?: string;
+    }>;
+    query: Record<string, {
+        from: string;
+        value?: unknown;
+        key?: string;
+    }>;
+    body: {
+        encoding: string;
+        fields?: Record<string, {
+            from: string;
+            value?: unknown;
+            key?: string;
+        }>;
+        fixture?: string;
+    };
+    credentialVariant: 'valid' | 'missing' | 'corrupted';
+    signatureProfile?: string;
+}
+/** What the driver observed (headers excluded — they carry secrets). */
+export interface DrivenRequest {
+    engineRequestId: string;
+    method: string;
+    path: string;
+    query: Record<string, unknown>;
+    /** Submitted body as observed (parsed JSON or form map). */
+    body: unknown;
+    status: number | null;
+    /** Response body as observed (parsed JSON or text). */
+    responseBody: unknown;
+    requestDigest: string;
+    responseDigest: string | null;
+}
+export interface DriveBehaviorRequestInput {
+    /** Approved request action from the bound catalog. */
+    action: BehaviorRequestAction;
+    /** Trusted lease (subjects + actors resolve here). */
+    lease: FixtureLease;
+    /** Actor profile key from the case definition. */
+    actorProfile: string;
+    /** Approved subject origin (the app under test; loopback only). */
+    origin: string;
+    /** Resolve engine-side credential material (never suite-visible). */
+    resolveCredential: (credentialRef: string) => Promise<CredentialMaterial | null> | CredentialMaterial | null;
+    /** Fetch timeout in milliseconds. */
+    timeoutMs: number;
+}
+/**
+ * Drives one approved request and captures the bounded observation.
+ *
+ * Args:
+ *   input: action, lease, actor profile, origin, credential resolver,
+ *   and timeout.
+ *
+ * Returns:
+ *   DrivenRequest: method/path/query/body/status/response plus
+ *   identity digests (headers never leave the driver).
+ *
+ * Throws:
+ *   BehaviorDriverError: unsupported encoding, unresolvable value,
+ *   non-loopback origin, timeout, over-limit body, or transport
+ *   failure — always a blocking diagnostic, never proof.
+ */
+export declare function driveBehaviorRequest(input: DriveBehaviorRequestInput): Promise<DrivenRequest>;
+//# sourceMappingURL=behavior-request.d.ts.map

package/dist/witness/behavior-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior-request.d.ts","sourceRoot":"","sources":["../../src/witness/behavior-request.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE9E,6DAA6D;AAC7D,eAAO,MAAM,yBAAyB,QAAa,CAAC;AAEpD,wEAAwE;AACxE,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,OAAO,CAAC;YAAC,GAAG,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvH,iBAAiB,EAAE,OAAO,GAAG,SAAS,GAAG,WAAW,CAAC;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,4DAA4D;IAC5D,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uDAAuD;IACvD,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAiID,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,MAAM,EAAE,qBAAqB,CAAC;IAC9B,sDAAsD;IACtD,KAAK,EAAE,YAAY,CAAC;IACpB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,iBAAiB,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,kBAAkB,GAAG,IAAI,CAAC;IAC7G,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,aAAa,CAAC,CAkLnG"}