@gate-forge/witness 0.0.0-stage → 0.9.0

package/dist/witness/task.js

@@ -0,0 +1,201 @@
+/**
+ * Engine task-delivery driver: the
+ * `engine-task` counterpart of the HTTP and browser drivers. It
+ * produces the delivery the case declares, then reads the queue back
+ * until every produced job settles, sampling each transition on the
+ * way.
+ *
+ * Both halves are engine-owned on purpose: the engine grades a
+ * background job's attempts, terminal state and idempotency from state
+ * IT produced and read, never from what the suite says happened.
+ */
+import { MAX_QUEUE_FIELD_CHARS, MAX_QUEUE_SAMPLES, TERMINAL_QUEUE_JOB_STATES, } from '@gate-forge/core';
+/** Blocking task-driver failure (always a diagnostic, never proof). */
+export class TaskDriverError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TaskDriverError';
+    }
+}
+/** Unsafe fixture-key segments (no prototype-chain traversal). */
+const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'prototype', 'constructor']);
+/**
+ * Resolves one declared input value against the sealed lease subjects.
+ *
+ * Args:
+ *   raw: the compiled InputValue.
+ *   subjects: the lease's fixture subjects.
+ *   what: field name for diagnostics.
+ *
+ * Returns:
+ *   unknown: the resolved value.
+ *
+ * @throws TaskDriverError the value uses an unsupported source or does not resolve.
+ */
+function resolveDeclaredValue(raw, subjects, what) {
+    if (raw.from === 'literal')
+        return raw.value ?? null;
+    if (raw.from === 'fixture') {
+        if (typeof raw.key !== 'string')
+            throw new TaskDriverError(`${what} fixture reference has no key`);
+        const segments = raw.key.split('.');
+        if (segments.some((segment) => segment.length === 0 || FORBIDDEN_SEGMENTS.has(segment))) {
+            throw new TaskDriverError(`${what} fixture key is forbidden`);
+        }
+        let current = subjects;
+        for (const segment of segments) {
+            if (typeof current !== 'object' || current === null || Array.isArray(current)) {
+                throw new TaskDriverError(`${what} fixture key '${raw.key}' does not resolve`);
+            }
+            if (!Object.prototype.hasOwnProperty.call(current, segment)) {
+                throw new TaskDriverError(`${what} fixture key '${raw.key}' does not resolve`);
+            }
+            current = current[segment];
+        }
+        return current ?? null;
+    }
+    throw new TaskDriverError(`${what} uses an unsupported value source '${raw.from}'`);
+}
+/**
+ * Resolves one delivery-identity field: a queue identity must be a
+ * bounded non-empty string, or the engine cannot recognize its own job.
+ *
+ * Args:
+ *   raw: the compiled InputValue.
+ *   subjects: the lease's fixture subjects.
+ *   what: field name for diagnostics.
+ *
+ * Returns:
+ *   string: the resolved identity.
+ *
+ * @throws TaskDriverError the value is not a bounded non-empty string.
+ */
+function resolveIdentity(raw, subjects, what) {
+    const resolved = resolveDeclaredValue(raw, subjects, what);
+    if (typeof resolved !== 'string' || resolved.length === 0) {
+        throw new TaskDriverError(`${what} must resolve to a non-empty string`);
+    }
+    if (resolved.length > MAX_QUEUE_FIELD_CHARS) {
+        throw new TaskDriverError(`${what} exceeds the ${String(MAX_QUEUE_FIELD_CHARS)}-character queue bound`);
+    }
+    return resolved;
+}
+/**
+ * Sleeps for the observer's sampling interval (a bounded read wait, not
+ * open-ended polling: the loop is bounded by the terminal timeout).
+ */
+function delay(ms) {
+    return new Promise((resolveDelay) => {
+        setTimeout(resolveDelay, ms);
+    });
+}
+/**
+ * Produces the declared deliveries and reads the queue back until every
+ * produced job reaches a terminal state (or the bound expires).
+ *
+ * The idempotency key is the SAME for every delivery of one case —
+ * that is what makes a duplicate-key case a duplicate — while each
+ * delivery gets its own identity, so the engine can tell its own jobs
+ * apart.
+ *
+ * Args:
+ *   action: the compiled `deliver` action.
+ *   attemptBound: the declared attempt bound (from the case's `attempts` rule).
+ *   subjects: the lease's fixture subjects.
+ *   channel: the engine's queue channel.
+ *   pollIntervalMs: transition-sampling interval.
+ *   terminalTimeoutMs: bound on waiting for settlement.
+ *
+ * Returns:
+ *   TaskDeliveryResult: the sealed observation plus delivered values.
+ *
+ * @throws TaskDriverError on an undeclared queue, an illegal identity,
+ *   an unbounded observation, or an over-long sample timeline.
+ */
+export async function driveTaskDelivery(input) {
+    const { action, channel, pollIntervalMs, terminalTimeoutMs } = input;
+    const observer = channel.observer;
+    const queue = observer.queueFor(action.resourceId);
+    const deliveryBase = resolveIdentity(action.deliveryId, input.subjects, 'deliveryId');
+    const idempotencyKey = resolveIdentity(action.idempotencyKey, input.subjects, 'idempotencyKey');
+    const payloadRaw = resolveDeclaredValue(action.payload, input.subjects, 'payload');
+    const payload = payloadRaw !== null && typeof payloadRaw === 'object' && !Array.isArray(payloadRaw)
+        ? payloadRaw
+        : { value: payloadRaw };
+    if (!Number.isInteger(input.attemptBound) || input.attemptBound < 1) {
+        throw new TaskDriverError("the case declares no 'attempts' rule, so the engine cannot stamp an attempt bound");
+    }
+    const deliveryIds = Array.from({ length: action.count }, (_unused, index) => `${deliveryBase}#${String(index + 1)}`);
+    const pending = [];
+    const produced = [];
+    for (const deliveryId of deliveryIds) {
+        const delivery = channel.deliverer.enqueue({
+            queue,
+            deliveryId,
+            idempotencyKey,
+            payload,
+            maxAttempts: input.attemptBound,
+        });
+        // A serial schedule waits for each receipt before producing the
+        // next delivery; a concurrent one produces them all and awaits.
+        if (action.schedule === 'serial')
+            produced.push(await delivery);
+        else
+            pending.push(delivery);
+    }
+    const receipts = [...produced, ...(await Promise.all(pending))];
+    const startedAt = Date.now();
+    const samples = [];
+    const jobIds = receipts.map((receipt) => receipt.jobId);
+    let settled = false;
+    while (!settled && Date.now() - startedAt < terminalTimeoutMs) {
+        settled = true;
+        for (const jobId of jobIds) {
+            const job = await observer.readJob(queue, jobId);
+            if (job === null) {
+                throw new TaskDriverError(`produced job '${jobId}' vanished from queue '${queue}' before it settled`);
+            }
+            // Every sample is sealed, not only changed ones: a queue that
+            // hands the SAME job out again (a lost-worker reclaim) is exactly
+            // the transition a "changed only" filter would hide. The record is
+            // bounded by MAX_QUEUE_SAMPLES, over which the engine fails
+            // closed rather than truncating a timeline.
+            samples.push({
+                jobId: job.jobId,
+                state: job.state,
+                attemptsMade: job.attemptsMade,
+                failedReason: job.failedReason,
+                atMs: Math.max(0, Date.now() - startedAt),
+            });
+            if (samples.length > MAX_QUEUE_SAMPLES) {
+                throw new TaskDriverError(`the delivery produced more than ${String(MAX_QUEUE_SAMPLES)} observations — the timeline is unbounded (fail closed)`);
+            }
+            if (!TERMINAL_QUEUE_JOB_STATES.has(job.state))
+                settled = false;
+        }
+        if (!settled)
+            await delay(pollIntervalMs);
+    }
+    const listed = await observer.listJobs(queue);
+    if (!listed.complete) {
+        throw new TaskDriverError(`queue '${queue}' holds more jobs than the engine's bounded list read allows (fail closed)`);
+    }
+    const producedIds = new Set(deliveryIds);
+    const jobs = listed.jobs.filter((job) => (job.deliveryId !== null && producedIds.has(job.deliveryId)) || job.idempotencyKey === idempotencyKey);
+    const waitedMs = Math.max(0, Date.now() - startedAt);
+    const complete = settled && jobs.length === deliveryIds.length;
+    return {
+        observation: { kind: observer.kind, queue, deliveryIds, jobs, samples, complete, waitedMs },
+        submittedValues: {
+            resourceId: action.resourceId,
+            queue,
+            payload,
+            deliveryId: deliveryBase,
+            idempotencyKey,
+            count: action.count,
+            schedule: action.schedule,
+            maxAttempts: input.attemptBound,
+        },
+    };
+}
+//# sourceMappingURL=task.js.map

package/dist/witness/task.js.map

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

package/dist/witness/twin-shapes.d.ts

@@ -0,0 +1,51 @@
+import { type TwinShape, type TwinShapeOptions } from '@gate-forge/core';
+/** The switch that turns twin shape recording on for a run. */
+export declare const TWIN_SHAPES_ON = "on";
+/** The recorded shape options one run's proxy uses. */
+export interface TwinShapePlan extends TwinShapeOptions {
+    /** Owner-declared query keys whose values a shape may carry. */
+    readonly queryKeys: readonly string[];
+}
+/**
+ * Parses the twin-shape options for one run.
+ *
+ * Parsed fail-closed on the SWITCH and lenient on the inventory: a run
+ * that asked for twin shapes and misconfigured the allowlist is a
+ * configuration error the owner must see, while a missing inventory
+ * only costs the shapes their route templates.
+ *
+ * Args:
+ *   shapes: the `GATEFORGE_TWIN_SHAPES` value (`'on'` switches on).
+ *   queryKeys: comma-separated owner allowlist.
+ *   inventoryPath: absolute path to the engine-written route inventory.
+ *
+ * Returns:
+ *   TwinShapePlan | null: the plan, or null for the byte-identical
+ *   no-twin-shapes path.
+ *
+ * @throws Error: when the switch is malformed or an allowlist entry is empty.
+ */
+export declare function parseTwinShapePlan(input: {
+    shapes: string | undefined;
+    queryKeys: string | undefined;
+    inventoryPath: string | undefined;
+}): TwinShapePlan | null;
+/**
+ * Computes one request's twin shape, deduplicated per session.
+ *
+ * A test that loads the same list three times recorded it three times;
+ * the comparison only ever asks "did this twin ever make this request",
+ * so an already-recorded shape is not appended again. The result is a
+ * small, stable list an owner can read.
+ *
+ * Args:
+ *   recorded: the session's shapes so far (mutated in place).
+ *   method: the request method the proxy saw.
+ *   url: the request target (path plus query), never stored.
+ *   plan: this run's shape options.
+ *
+ * Returns:
+ *   void: appends to `recorded` when the shape is new.
+ */
+export declare function recordTwinShape(recorded: TwinShape[], method: string, url: string, plan: TwinShapePlan): void;
+//# sourceMappingURL=twin-shapes.d.ts.map

package/dist/witness/twin-shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-shapes.d.ts","sourceRoot":"","sources":["../../src/witness/twin-shapes.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAuC,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAe,MAAM,kBAAkB,CAAC;AAE3H,+DAA+D;AAC/D,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC,uDAAuD;AACvD,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAgCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC,GAAG,aAAa,GAAG,IAAI,CAsBvB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,SAAS,EAAE,EACrB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,GAClB,IAAI,CAKN"}

package/dist/witness/twin-shapes.js

@@ -0,0 +1,127 @@
+/**
+ * Twin path coverage (E64), witness side: what the observation proxy
+ * records about a request when the owner asked to know whether a raw
+ * test and its witnessed twin exercised the same path.
+ *
+ * The reported bug was GREEN. A raw test and its witnessed twin shared
+ * a helper whose parameter defaults sent them down different paths (the
+ * list call carried `?tab=all` in one and `?tab=open` in the other), so
+ * "green three times" proved nothing about the path the witnessed twin
+ * covered and nothing in the run said so.
+ *
+ * What this module fixes is the RECORD, not the verdict. A shape is
+ * computed at request-arrival time from the method and target the proxy
+ * already saw, and only the shape is kept: a method, a route TEMPLATE
+ * and the values of the owner-declared query-key allowlist. The raw URL
+ * is never stored, so there is nothing here to leak — a shape list is
+ * something an owner pastes into a bug.
+ *
+ * Both twins' traffic arrives on the SAME kind of channel: the
+ * dedicated per-session proxy the run already wires. A raw twin issues
+ * no evidence because it never calls the evidence API; the witness
+ * additionally refuses every submission from a session the supervisor
+ * marked observation-only, so "can satisfy nothing" is enforced rather
+ * than assumed.
+ */
+import { readFileSync } from 'node:fs';
+import { compareStrings, twinShapeOf } from '@gate-forge/core';
+/** The switch that turns twin shape recording on for a run. */
+export const TWIN_SHAPES_ON = 'on';
+/**
+ * Reads the route inventory the shapes resolve against.
+ *
+ * The file is the engine's own compiled endpoint list — a shape may
+ * name a route template, never a concrete id — so a run whose file is
+ * missing or unreadable resolves shapes without an inventory (the
+ * identifier-blind fallback), never with a guess.
+ *
+ * Args:
+ *   path: absolute path to the engine-written inventory document.
+ *
+ * Returns:
+ *   RouteInventory | undefined: the templates, or undefined when the
+ *   document is absent/unreadable/not a template list.
+ */
+function readInventory(path) {
+    if (path === undefined || path === '')
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null || !('templates' in parsed))
+        return undefined;
+    const templates = parsed.templates;
+    if (!Array.isArray(templates))
+        return undefined;
+    const names = templates.filter((entry) => typeof entry === 'string' && entry.length > 0);
+    return names.length === 0 ? undefined : { templates: names };
+}
+/**
+ * Parses the twin-shape options for one run.
+ *
+ * Parsed fail-closed on the SWITCH and lenient on the inventory: a run
+ * that asked for twin shapes and misconfigured the allowlist is a
+ * configuration error the owner must see, while a missing inventory
+ * only costs the shapes their route templates.
+ *
+ * Args:
+ *   shapes: the `GATEFORGE_TWIN_SHAPES` value (`'on'` switches on).
+ *   queryKeys: comma-separated owner allowlist.
+ *   inventoryPath: absolute path to the engine-written route inventory.
+ *
+ * Returns:
+ *   TwinShapePlan | null: the plan, or null for the byte-identical
+ *   no-twin-shapes path.
+ *
+ * @throws Error: when the switch is malformed or an allowlist entry is empty.
+ */
+export function parseTwinShapePlan(input) {
+    if (input.shapes === undefined || input.shapes === '')
+        return null;
+    if (input.shapes !== TWIN_SHAPES_ON) {
+        throw new Error(`twin shape recording: GATEFORGE_TWIN_SHAPES must be '${TWIN_SHAPES_ON}' or absent, got ${JSON.stringify(input.shapes)}`);
+    }
+    const queryKeys = input.queryKeys === undefined || input.queryKeys === ''
+        ? []
+        : input.queryKeys.split(',').map((key) => {
+            const trimmed = key.trim();
+            if (trimmed === '') {
+                throw new Error('twin shape recording: GATEFORGE_TWIN_QUERY_KEYS has an empty entry');
+            }
+            return trimmed;
+        });
+    const inventory = readInventory(input.inventoryPath);
+    return {
+        queryKeys: [...queryKeys].sort(compareStrings),
+        ...(inventory === undefined ? {} : { inventory }),
+    };
+}
+/**
+ * Computes one request's twin shape, deduplicated per session.
+ *
+ * A test that loads the same list three times recorded it three times;
+ * the comparison only ever asks "did this twin ever make this request",
+ * so an already-recorded shape is not appended again. The result is a
+ * small, stable list an owner can read.
+ *
+ * Args:
+ *   recorded: the session's shapes so far (mutated in place).
+ *   method: the request method the proxy saw.
+ *   url: the request target (path plus query), never stored.
+ *   plan: this run's shape options.
+ *
+ * Returns:
+ *   void: appends to `recorded` when the shape is new.
+ */
+export function recordTwinShape(recorded, method, url, plan) {
+    const shape = twinShapeOf({ method, url }, plan);
+    const identity = JSON.stringify(shape);
+    if (recorded.some((existing) => JSON.stringify(existing) === identity))
+        return;
+    recorded.push(shape);
+}
+//# sourceMappingURL=twin-shapes.js.map

package/dist/witness/twin-shapes.js.map

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