@gate-forge/core 0.7.1 → 0.9.0

package/dist/schemas/queue-observer.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Queue-observer schemas: the OWNER
+ * declaration that binds a task resource to the queue the engine
+ * reads, plus the SEALED observation vocabulary the engine's own
+ * bounded reads are graded against. One schema, parsed by the CLI at
+ * config time AND by the witness when it opens the channel from its
+ * own environment, so a typo is a config error (never a silent
+ * default) and the two sides can never disagree about what was
+ * declared.
+ *
+ * Connection material never carries a secret inline: the URL form names
+ * an environment variable the witness process resolves privately, and
+ * the value is never sealed into a record, a report, or argv.
+ */
+import { z } from 'zod';
+/**
+ * The SEALED observation vocabulary. The witness reads the queue and
+ * seals what it read; the grader re-derives every task verdict from
+ * these fields alone. A suite-submitted "the job succeeded" cannot
+ * produce this shape — only the engine's own bounded reads can.
+ *
+ * Normalized states are library-independent on purpose: every
+ * implementation maps its backend's own vocabulary onto these seven,
+ * and an unrecognized backend state is a hard failure (fail closed),
+ * never a silent mapping.
+ */
+/** Normalized job states an observer may report. */
+export declare const QUEUE_JOB_STATES: readonly ["waiting", "delayed", "prioritized", "active", "completed", "failed", "paused"];
+/** Inferred normalized job state. */
+export type QueueJobState = (typeof QUEUE_JOB_STATES)[number];
+/** States a delivery may never leave while the engine waits. */
+export declare const TERMINAL_QUEUE_JOB_STATES: ReadonlySet<QueueJobState>;
+/** Hard bound on one observed field value (over it, fail closed). */
+export declare const MAX_QUEUE_FIELD_CHARS = 512;
+/** Default bound for one bounded list read. */
+export declare const DEFAULT_QUEUE_LIST_LIMIT = 200;
+/** Hard bound for one bounded list read (over it, fail closed). */
+export declare const MAX_QUEUE_LIST_LIMIT = 1000;
+/**
+ * Hard bound on the sealed observations of one delivery. One sample per
+ * polling tick, so a default 200 ms sampling interval and a 30 s settle
+ * bound sit well inside it; a longer wait fails closed rather than
+ * truncating the timeline a stall claim reads.
+ */
+export declare const MAX_QUEUE_SAMPLES = 2048;
+/** One engine-read job observation (bounded fields only). */
+export declare const QueueJobObservationSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    deliveryId: z.ZodNullable<z.ZodString>;
+    idempotencyKey: z.ZodNullable<z.ZodString>;
+    state: z.ZodEnum<{
+        active: "active";
+        failed: "failed";
+        waiting: "waiting";
+        delayed: "delayed";
+        prioritized: "prioritized";
+        completed: "completed";
+        paused: "paused";
+    }>;
+    attemptsMade: z.ZodNumber;
+    maxAttempts: z.ZodNullable<z.ZodNumber>;
+    failedReason: z.ZodNullable<z.ZodString>;
+    processedAt: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+/** Inferred job-observation shape. */
+export type QueueJobObservation = z.infer<typeof QueueJobObservationSchema>;
+/**
+ * One sampled observation of a job with the engine's own elapsed time.
+ * Samples are NOT deduplicated: a queue that hands the same job out a
+ * second time (a lost-worker reclaim) is exactly the transition a
+ * "changed only" filter would hide. The record stays bounded by
+ * {@link MAX_QUEUE_SAMPLES}, over which the engine fails closed.
+ */
+export declare const QueueJobSampleSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    state: z.ZodEnum<{
+        active: "active";
+        failed: "failed";
+        waiting: "waiting";
+        delayed: "delayed";
+        prioritized: "prioritized";
+        completed: "completed";
+        paused: "paused";
+    }>;
+    attemptsMade: z.ZodNumber;
+    failedReason: z.ZodNullable<z.ZodString>;
+    atMs: z.ZodNumber;
+}, z.core.$strict>;
+/** Inferred job-sample shape. */
+export type QueueJobSample = z.infer<typeof QueueJobSampleSchema>;
+/**
+ * The engine's sealed read of one delivery's jobs. `complete:false`
+ * means the engine stopped waiting before every job settled: that can
+ * never satisfy a task rule, and it is sealed as a diagnostic rather
+ * than a partial proof.
+ */
+export declare const QueueObservationSchema: z.ZodObject<{
+    kind: z.ZodString;
+    queue: z.ZodString;
+    deliveryIds: z.ZodArray<z.ZodString>;
+    jobs: z.ZodArray<z.ZodObject<{
+        jobId: z.ZodString;
+        deliveryId: z.ZodNullable<z.ZodString>;
+        idempotencyKey: z.ZodNullable<z.ZodString>;
+        state: z.ZodEnum<{
+            active: "active";
+            failed: "failed";
+            waiting: "waiting";
+            delayed: "delayed";
+            prioritized: "prioritized";
+            completed: "completed";
+            paused: "paused";
+        }>;
+        attemptsMade: z.ZodNumber;
+        maxAttempts: z.ZodNullable<z.ZodNumber>;
+        failedReason: z.ZodNullable<z.ZodString>;
+        processedAt: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>;
+    samples: z.ZodArray<z.ZodObject<{
+        jobId: z.ZodString;
+        state: z.ZodEnum<{
+            active: "active";
+            failed: "failed";
+            waiting: "waiting";
+            delayed: "delayed";
+            prioritized: "prioritized";
+            completed: "completed";
+            paused: "paused";
+        }>;
+        attemptsMade: z.ZodNumber;
+        failedReason: z.ZodNullable<z.ZodString>;
+        atMs: z.ZodNumber;
+    }, z.core.$strict>>;
+    complete: z.ZodBoolean;
+    waitedMs: z.ZodNumber;
+}, z.core.$strict>;
+/** Inferred queue-observation shape. */
+export type QueueObservation = z.infer<typeof QueueObservationSchema>;
+/** One approved queue binding: task resource id → queue name. */
+export declare const QueueBindingSchema: z.ZodObject<{
+    name: z.ZodString;
+    taskResourceId: z.ZodString;
+}, z.core.$strict>;
+/** Inferred queue-binding shape. */
+export type QueueBinding = z.infer<typeof QueueBindingSchema>;
+/** Redis connection material: host/port, or an env var holding the URL. */
+export declare const QueueConnectionSchema: z.ZodUnion<readonly [z.ZodObject<{
+    host: z.ZodString;
+    port: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    urlEnv: z.ZodString;
+}, z.core.$strict>]>;
+/** Inferred queue-connection shape. */
+export type QueueConnection = z.infer<typeof QueueConnectionSchema>;
+/** The `.gateforge.yml` `queueObserver` block (also the witness env JSON). */
+export declare const QueueObserverConfigSchema: z.ZodObject<{
+    kind: z.ZodString;
+    connection: z.ZodUnion<readonly [z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        urlEnv: z.ZodString;
+    }, z.core.$strict>]>;
+    queues: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        taskResourceId: z.ZodString;
+    }, z.core.$strict>>;
+    pollIntervalMs: z.ZodOptional<z.ZodNumber>;
+    terminalTimeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** Inferred queue-observer configuration. */
+export type QueueObserverConfig = z.infer<typeof QueueObserverConfigSchema>;
+/** Environment variable naming the queue observer (built-in or module). */
+export declare const QUEUE_OBSERVER_ENV = "GATEFORGE_QUEUE_OBSERVER";
+/** Environment variable carrying the JSON queue-observer configuration. */
+export declare const QUEUE_OBSERVER_CONFIG_ENV = "GATEFORGE_QUEUE_OBSERVER_CONFIG";
+/** Default observer poll interval (transition sampling). */
+export declare const DEFAULT_QUEUE_POLL_INTERVAL_MS = 200;
+/** Default bound on waiting for every job of a delivery to settle. */
+export declare const DEFAULT_QUEUE_TERMINAL_TIMEOUT_MS = 30000;
+/**
+ * Parses a queue-observer configuration, failing closed with a message
+ * naming every illegal field.
+ *
+ * Args:
+ *   raw: the JSON text (witness env form).
+ *
+ * Returns:
+ *   QueueObserverConfig: the validated configuration.
+ *
+ * Throws:
+ *   Error: malformed JSON or an illegal field (fail closed).
+ */
+export declare function parseQueueObserverConfigJson(raw: string): QueueObserverConfig;
+//# sourceMappingURL=queue-observer.d.ts.map

package/dist/schemas/queue-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-observer.d.ts","sourceRoot":"","sources":["../../src/schemas/queue-observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AAEH,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,2FAQnB,CAAC;AAEX,qCAAqC;AACrC,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,gEAAgE;AAChE,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,aAAa,CAAoC,CAAC;AAEtG,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,+CAA+C;AAC/C,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,6DAA6D;AAC7D,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;kBAmB3B,CAAC;AAEZ,sCAAsC;AACtC,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;kBAatB,CAAC;AAEZ,iCAAiC;AACjC,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAiBxB,CAAC;AAEZ,wCAAwC;AACxC,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,iEAAiE;AACjE,eAAO,MAAM,kBAAkB;;;kBAOpB,CAAC;AAEZ,oCAAoC;AACpC,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB;;;;;oBAKhC,CAAC;AAEH,uCAAuC;AACvC,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,8EAA8E;AAC9E,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;kBAgB3B,CAAC;AAEZ,6CAA6C;AAC7C,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,6BAA6B,CAAC;AAE7D,2EAA2E;AAC3E,eAAO,MAAM,yBAAyB,oCAAoC,CAAC;AAE3E,4DAA4D;AAC5D,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD,sEAAsE;AACtE,eAAO,MAAM,iCAAiC,QAAS,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAe7E"}

package/dist/schemas/queue-observer.js

@@ -0,0 +1,190 @@
+/**
+ * Queue-observer schemas: the OWNER
+ * declaration that binds a task resource to the queue the engine
+ * reads, plus the SEALED observation vocabulary the engine's own
+ * bounded reads are graded against. One schema, parsed by the CLI at
+ * config time AND by the witness when it opens the channel from its
+ * own environment, so a typo is a config error (never a silent
+ * default) and the two sides can never disagree about what was
+ * declared.
+ *
+ * Connection material never carries a secret inline: the URL form names
+ * an environment variable the witness process resolves privately, and
+ * the value is never sealed into a record, a report, or argv.
+ */
+import { z } from 'zod';
+/**
+ * The SEALED observation vocabulary. The witness reads the queue and
+ * seals what it read; the grader re-derives every task verdict from
+ * these fields alone. A suite-submitted "the job succeeded" cannot
+ * produce this shape — only the engine's own bounded reads can.
+ *
+ * Normalized states are library-independent on purpose: every
+ * implementation maps its backend's own vocabulary onto these seven,
+ * and an unrecognized backend state is a hard failure (fail closed),
+ * never a silent mapping.
+ */
+/** Normalized job states an observer may report. */
+export const QUEUE_JOB_STATES = [
+    'waiting',
+    'delayed',
+    'prioritized',
+    'active',
+    'completed',
+    'failed',
+    'paused',
+];
+/** States a delivery may never leave while the engine waits. */
+export const TERMINAL_QUEUE_JOB_STATES = new Set(['completed', 'failed']);
+/** Hard bound on one observed field value (over it, fail closed). */
+export const MAX_QUEUE_FIELD_CHARS = 512;
+/** Default bound for one bounded list read. */
+export const DEFAULT_QUEUE_LIST_LIMIT = 200;
+/** Hard bound for one bounded list read (over it, fail closed). */
+export const MAX_QUEUE_LIST_LIMIT = 1000;
+/**
+ * Hard bound on the sealed observations of one delivery. One sample per
+ * polling tick, so a default 200 ms sampling interval and a 30 s settle
+ * bound sit well inside it; a longer wait fails closed rather than
+ * truncating the timeline a stall claim reads.
+ */
+export const MAX_QUEUE_SAMPLES = 2048;
+/** One engine-read job observation (bounded fields only). */
+export const QueueJobObservationSchema = z
+    .object({
+    /** Queue-native job id. */
+    jobId: z.string().min(1),
+    /** Delivery identity the engine stamped, or null when the job carries none. */
+    deliveryId: z.string().min(1).nullable(),
+    /** Idempotency key the engine stamped, or null when the job carries none. */
+    idempotencyKey: z.string().min(1).nullable(),
+    /** Normalized state. */
+    state: z.enum(QUEUE_JOB_STATES),
+    /** Attempts the queue has made for this job. */
+    attemptsMade: z.number().int().min(0),
+    /** Declared attempt bound, or null when the queue declares none. */
+    maxAttempts: z.number().int().min(1).nullable(),
+    /** Bounded failure reason (never a raw stack). */
+    failedReason: z.string().min(1).nullable(),
+    /** Engine-observed processing timestamp (ms) or null. */
+    processedAt: z.number().int().min(0).nullable(),
+})
+    .strict();
+/**
+ * One sampled observation of a job with the engine's own elapsed time.
+ * Samples are NOT deduplicated: a queue that hands the same job out a
+ * second time (a lost-worker reclaim) is exactly the transition a
+ * "changed only" filter would hide. The record stays bounded by
+ * {@link MAX_QUEUE_SAMPLES}, over which the engine fails closed.
+ */
+export const QueueJobSampleSchema = z
+    .object({
+    /** Queue-native job id. */
+    jobId: z.string().min(1),
+    /** Normalized state at sampling time. */
+    state: z.enum(QUEUE_JOB_STATES),
+    /** Attempts made at sampling time. */
+    attemptsMade: z.number().int().min(0),
+    /** Bounded failure reason at sampling time (null when unset). */
+    failedReason: z.string().min(1).nullable(),
+    /** Engine-side elapsed milliseconds since the delivery was produced. */
+    atMs: z.number().int().min(0),
+})
+    .strict();
+/**
+ * The engine's sealed read of one delivery's jobs. `complete:false`
+ * means the engine stopped waiting before every job settled: that can
+ * never satisfy a task rule, and it is sealed as a diagnostic rather
+ * than a partial proof.
+ */
+export const QueueObservationSchema = z
+    .object({
+    /** Observer implementation kind (`bullmq` or a declared module). */
+    kind: z.string().min(1),
+    /** The queue the engine read. */
+    queue: z.string().min(1),
+    /** Engine-stamped delivery identities, in production order. */
+    deliveryIds: z.array(z.string().min(1)).min(1),
+    /** Final engine read of every produced job. */
+    jobs: z.array(QueueJobObservationSchema).min(1),
+    /** Every distinct transition the engine sampled, in order. */
+    samples: z.array(QueueJobSampleSchema),
+    /** True when every job reached a terminal state before the bound. */
+    complete: z.boolean(),
+    /** Engine-side elapsed milliseconds spent waiting for settlement. */
+    waitedMs: z.number().int().min(0),
+})
+    .strict();
+/** One approved queue binding: task resource id → queue name. */
+export const QueueBindingSchema = z
+    .object({
+    /** Queue name as the backend knows it. */
+    name: z.string().min(1),
+    /** Task resource id the owner maps this queue to. */
+    taskResourceId: z.string().min(1),
+})
+    .strict();
+/** Redis connection material: host/port, or an env var holding the URL. */
+export const QueueConnectionSchema = z.union([
+    z
+        .object({ host: z.string().min(1), port: z.number().int().min(1).max(65_535) })
+        .strict(),
+    z.object({ urlEnv: z.string().min(1) }).strict(),
+]);
+/** The `.gateforge.yml` `queueObserver` block (also the witness env JSON). */
+export const QueueObserverConfigSchema = z
+    .object({
+    /**
+     * `bullmq` (the built-in implementation) or a module path whose
+     * default export is a `(spec) => QueueChannel` factory.
+     */
+    kind: z.string().min(1),
+    /** Connection material (no inline secret). */
+    connection: QueueConnectionSchema,
+    /** Approved queue bindings; an unknown task resource id fails closed. */
+    queues: z.array(QueueBindingSchema).min(1),
+    /** Transition-sampling interval in ms (default 200). */
+    pollIntervalMs: z.number().int().min(10).max(10_000).optional(),
+    /** Bound on waiting for every job of a delivery to settle. */
+    terminalTimeoutMs: z.number().int().min(1_000).max(600_000).optional(),
+})
+    .strict();
+/** Environment variable naming the queue observer (built-in or module). */
+export const QUEUE_OBSERVER_ENV = 'GATEFORGE_QUEUE_OBSERVER';
+/** Environment variable carrying the JSON queue-observer configuration. */
+export const QUEUE_OBSERVER_CONFIG_ENV = 'GATEFORGE_QUEUE_OBSERVER_CONFIG';
+/** Default observer poll interval (transition sampling). */
+export const DEFAULT_QUEUE_POLL_INTERVAL_MS = 200;
+/** Default bound on waiting for every job of a delivery to settle. */
+export const DEFAULT_QUEUE_TERMINAL_TIMEOUT_MS = 30_000;
+/**
+ * Parses a queue-observer configuration, failing closed with a message
+ * naming every illegal field.
+ *
+ * Args:
+ *   raw: the JSON text (witness env form).
+ *
+ * Returns:
+ *   QueueObserverConfig: the validated configuration.
+ *
+ * Throws:
+ *   Error: malformed JSON or an illegal field (fail closed).
+ */
+export function parseQueueObserverConfigJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${QUEUE_OBSERVER_CONFIG_ENV} is not valid JSON (fail closed)`);
+    }
+    const result = QueueObserverConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const detail = result.error.issues
+            .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+            .join('; ');
+        throw new Error(`${QUEUE_OBSERVER_CONFIG_ENV} is not a valid queue-observer configuration: ${detail} (fail closed)`);
+    }
+    return result.data;
+}
+//# sourceMappingURL=queue-observer.js.map

package/dist/schemas/queue-observer.js.map

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

package/dist/schemas/run-record.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Run record schema (plan 2026-09-29, re-seal design rule 1): what a
+ * COMPLETE whole-suite supervised run leaves behind when it did NOT
+ * seal a gate receipt — the consumer's 563-tests-562-passed case.
+ *
+ * A gate receipt is a VERDICT: it is issued only for a clean run, and a
+ * run with one failing test issues none (it also clears the old one).
+ * Without a run record the exact case a test-only re-seal exists for
+ * could never re-seal. A run record binds exactly the material a
+ * receipt binds — execution result, evidence attestation, candidate
+ * tree, input snapshot, approved policy, engine bundle, execution
+ * boundary, catalog, per-test outcomes — and carries NO verdict at all.
+ *
+ * It is a DIFFERENT envelope, not a weaker receipt: its own domain tag
+ * (`gateforge.run-record.v1`), its own file (`run-record.json`), its own
+ * strict schema, and no field any receipt consumer reads. `check`,
+ * pre-commit and the broker therefore never see it: a run record alone
+ * leaves `check --require-e2e` exactly as blocked as it was. Only the
+ * test-only re-seal path reads it, and only as a PARENT to recompute
+ * from, never as proof on its own.
+ */
+import { z } from 'zod';
+/**
+ * The run record. Unsigned fields first, `mac` last; the signed body is
+ * exactly `{domain, ...everything except mac}`.
+ */
+export declare const RunRecordSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    recordVersion: z.ZodLiteral<1>;
+    recordId: z.ZodString;
+    verifierKeyId: z.ZodOptional<z.ZodString>;
+    runId: z.ZodString;
+    invocationId: z.ZodString;
+    inputDigest: z.ZodString;
+    gitSha: z.ZodNullable<z.ZodString>;
+    parentSha: z.ZodNullable<z.ZodString>;
+    trustedPolicyDigest: z.ZodString;
+    approvedPolicyDigest: z.ZodString;
+    invocation: z.ZodString;
+    selectionDigest: z.ZodString;
+    catalogDigest: z.ZodString;
+    executionResultDigest: z.ZodString;
+    testOutcomesDigest: z.ZodString;
+    plannedTests: z.ZodNumber;
+    passedTests: z.ZodNumber;
+    evidenceAttestationDigest: z.ZodNullable<z.ZodString>;
+    candidateTreeId: z.ZodNullable<z.ZodString>;
+    engineBundleDigest: z.ZodString;
+    executionBoundaryDigest: z.ZodString;
+    issuedAt: z.ZodString;
+    mac: z.ZodString;
+}, z.core.$strict>;
+/** Inferred run-record shape. */
+export type RunRecord = z.infer<typeof RunRecordSchema>;
+/** The unsigned run-record body (everything the MAC covers). */
+export type RunRecordBody = Omit<RunRecord, 'mac'>;
+//# sourceMappingURL=run-record.d.ts.map

package/dist/schemas/run-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-record.d.ts","sourceRoot":"","sources":["../../src/schemas/run-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;kBA6ExB,CAAC;AAEL,iCAAiC;AACjC,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,gEAAgE;AAChE,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC"}

package/dist/schemas/run-record.js

@@ -0,0 +1,108 @@
+/**
+ * Run record schema (plan 2026-09-29, re-seal design rule 1): what a
+ * COMPLETE whole-suite supervised run leaves behind when it did NOT
+ * seal a gate receipt — the consumer's 563-tests-562-passed case.
+ *
+ * A gate receipt is a VERDICT: it is issued only for a clean run, and a
+ * run with one failing test issues none (it also clears the old one).
+ * Without a run record the exact case a test-only re-seal exists for
+ * could never re-seal. A run record binds exactly the material a
+ * receipt binds — execution result, evidence attestation, candidate
+ * tree, input snapshot, approved policy, engine bundle, execution
+ * boundary, catalog, per-test outcomes — and carries NO verdict at all.
+ *
+ * It is a DIFFERENT envelope, not a weaker receipt: its own domain tag
+ * (`gateforge.run-record.v1`), its own file (`run-record.json`), its own
+ * strict schema, and no field any receipt consumer reads. `check`,
+ * pre-commit and the broker therefore never see it: a run record alone
+ * leaves `check --require-e2e` exactly as blocked as it was. Only the
+ * test-only re-seal path reads it, and only as a PARENT to recompute
+ * from, never as proof on its own.
+ */
+import { z } from 'zod';
+import { SchemaVersionField } from './common.js';
+/** Hex pattern shared by every digest field. */
+const HEX64 = /^[0-9a-f]{64}$/;
+/**
+ * The run record. Unsigned fields first, `mac` last; the signed body is
+ * exactly `{domain, ...everything except mac}`.
+ */
+export const RunRecordSchema = z
+    .object({
+    schemaVersion: SchemaVersionField,
+    /** Envelope version; only `1` exists today. */
+    recordVersion: z.literal(1),
+    /** Record identity (UUID). */
+    recordId: z.string().uuid(),
+    /** Non-secret verifier-key id used for safe key-ring rotation. */
+    verifierKeyId: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/).optional(),
+    /** Run manifest identity of the run that produced the record. */
+    runId: z.string().uuid(),
+    /** Fresh trusted invocation identity of that run. */
+    invocationId: z.string().uuid(),
+    /** 64-hex digest of the canonical input snapshot the run tested. */
+    inputDigest: z.string().regex(HEX64, 'inputDigest must be 64-char lowercase hex'),
+    /** Candidate HEAD sha, or null when unavailable (base identity). */
+    gitSha: z
+        .string()
+        .regex(/^[0-9a-f]{40}$/, 'gitSha must be a 40-char lowercase sha1 hex')
+        .nullable(),
+    /** Parent commit sha, or null when unavailable (parent identity). */
+    parentSha: z
+        .string()
+        .regex(/^[0-9a-f]{40}$/, 'parentSha must be a 40-char lowercase sha1 hex')
+        .nullable(),
+    /** 64-hex trusted policy/config revision digest (ADR 0005 D6). */
+    trustedPolicyDigest: z.string().regex(HEX64, 'trustedPolicyDigest must be 64-char lowercase hex'),
+    /** 64-hex owner-approved policy revision the run was pinned to. */
+    approvedPolicyDigest: z.string().regex(HEX64, 'approvedPolicyDigest must be 64-char lowercase hex'),
+    /** Normalized invocation that produced the record (e.g. `test-gates --changed`). */
+    invocation: z.string().min(1),
+    /** 64-hex selection digest (the expected test set, fixed pre-run). */
+    selectionDigest: z.string().regex(HEX64, 'selectionDigest must be 64-char lowercase hex'),
+    /** 64-hex digest of the catalog the selection was planned from. */
+    catalogDigest: z.string().regex(HEX64, 'catalogDigest must be 64-char lowercase hex'),
+    /** 64-hex digest of the supervision execution result (ADR 0005 D2). */
+    executionResultDigest: z.string().regex(HEX64, 'executionResultDigest must be 64-char lowercase hex'),
+    /**
+     * 64-hex digest over the run's per-test outcomes. It is recomputed
+     * from the execution result the record names, so the record can
+     * never claim a cleaner run than the one that happened.
+     */
+    testOutcomesDigest: z.string().regex(HEX64, 'testOutcomesDigest must be 64-char lowercase hex'),
+    /** How many tests the whole-suite run planned. */
+    plannedTests: z.number().int().min(0),
+    /** How many of them the run reported as passed. */
+    passedTests: z.number().int().min(0),
+    /**
+     * 64-hex digest of the v2 evidence attestation envelope that run
+     * sealed, or null when it carried none. It binds no verdict: the
+     * attestation is evidence, and the gate grading is what the record
+     * deliberately omits.
+     */
+    evidenceAttestationDigest: z.string().regex(HEX64, 'evidenceAttestationDigest must be 64-char lowercase hex').nullable(),
+    /** Immutable Git tree actually tested (40-char sha1, or null). */
+    candidateTreeId: z
+        .string()
+        .regex(/^[0-9a-f]{40}$/, 'candidateTreeId must be a 40-char lowercase sha1 hex')
+        .nullable(),
+    /** 64-hex digest binding the approved engine/policy bundle version. */
+    engineBundleDigest: z.string().regex(HEX64, 'engineBundleDigest must be 64-char lowercase hex'),
+    /** 64-hex digest binding the controller-issued execution-profile record. */
+    executionBoundaryDigest: z.string().regex(HEX64, 'executionBoundaryDigest must be 64-char lowercase hex'),
+    /** Issuance instant (ISO-8601). */
+    issuedAt: z.string().datetime(),
+    /** HMAC-SHA256 over the record body, domain `gateforge.run-record.v1`. */
+    mac: z.string().regex(HEX64, 'mac must be a 64-char lowercase hex HMAC'),
+})
+    .strict()
+    .superRefine((record, ctx) => {
+    if (record.passedTests > record.plannedTests) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['passedTests'],
+            message: 'passedTests cannot exceed plannedTests',
+        });
+    }
+});
+//# sourceMappingURL=run-record.js.map

package/dist/schemas/run-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-record.js","sourceRoot":"","sources":["../../src/schemas/run-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,gDAAgD;AAChD,MAAM,KAAK,GAAG,gBAAgB,CAAC;AAE/B;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,CAAC;IACN,aAAa,EAAE,kBAAkB;IACjC,+CAA+C;IAC/C,aAAa,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3B,8BAA8B;IAC9B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IAC3B,kEAAkE;IAClE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC,QAAQ,EAAE;IAC/E,iEAAiE;IACjE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IACxB,qDAAqD;IACrD,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE;IAC/B,oEAAoE;IACpE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,2CAA2C,CAAC;IACjF,oEAAoE;IACpE,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,KAAK,CAAC,gBAAgB,EAAE,6CAA6C,CAAC;SACtE,QAAQ,EAAE;IACb,qEAAqE;IACrE,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,KAAK,CAAC,gBAAgB,EAAE,gDAAgD,CAAC;SACzE,QAAQ,EAAE;IACb,kEAAkE;IAClE,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,mDAAmD,CAAC;IACjG,mEAAmE;IACnE,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,oDAAoD,CAAC;IACnG,oFAAoF;IACpF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,sEAAsE;IACtE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,+CAA+C,CAAC;IACzF,mEAAmE;IACnE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,6CAA6C,CAAC;IACrF,uEAAuE;IACvE,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,qDAAqD,CAAC;IACrG;;;;OAIG;IACH,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,kDAAkD,CAAC;IAC/F,kDAAkD;IAClD,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrC,mDAAmD;IACnD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACpC;;;;;OAKG;IACH,yBAAyB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,yDAAyD,CAAC,CAAC,QAAQ,EAAE;IACxH,kEAAkE;IAClE,eAAe,EAAE,CAAC;SACf,MAAM,EAAE;SACR,KAAK,CAAC,gBAAgB,EAAE,sDAAsD,CAAC;SAC/E,QAAQ,EAAE;IACb,uEAAuE;IACvE,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,kDAAkD,CAAC;IAC/F,4EAA4E;IAC5E,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,uDAAuD,CAAC;IACzG,mCAAmC;IACnC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,0EAA0E;IAC1E,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,0CAA0C,CAAC;CACzE,CAAC;KACD,MAAM,EAAE;KACR,WAAW,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;IAC3B,IAAI,MAAM,CAAC,WAAW,GAAG,MAAM,CAAC,YAAY,EAAE,CAAC;QAC7C,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,aAAa,CAAC;YACrB,OAAO,EAAE,wCAAwC;SAClD,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/schemas/runtime-config.d.ts

@@ -30,6 +30,27 @@ export declare const SERVICE_URL_PLACEHOLDER = "${service:<id>:url}";
 export declare const DEFAULT_PREPARE_TIMEOUT_SECONDS = 600;
 /** Default budget for one service readiness probe, in seconds. */
 export declare const DEFAULT_READY_TIMEOUT_SECONDS = 60;
+/**
+ * One managed-run recipe step (managed-run plan (2026-09-29), Part B): the app-owned
+ * lifecycle command Gateforge sequences for `gateforge run`. Commands
+ * are argv lists (never a shell string), each step carries its own
+ * timeout, and a step may be retried a bounded number of times.
+ */
+export declare const RecipeStepSchema: z.ZodObject<{
+    commands: z.ZodArray<z.ZodArray<z.ZodString>>;
+    timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    retries: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** Inferred recipe step shape. */
+export type RecipeStep = z.infer<typeof RecipeStepSchema>;
+/** Default wall-clock budget for one managed-run recipe step, in seconds. */
+export declare const DEFAULT_RECIPE_STEP_TIMEOUT_SECONDS = 600;
+/**
+ * Environment file a recipe may load, as a PATH only. An entry carrying
+ * a value (`NAME=value`) is rejected: the recipe never holds secret
+ * material, and `gateforge run` never prints the values it loads.
+ */
+export declare const RecipeEnvFileSchema: z.ZodString;
 /**
  * One service readiness probe: a log line matching `log` (regex source
  * over the captured stdout+stderr) OR an `http` GET returning 2xx.
@@ -79,9 +100,55 @@ export declare const RuntimeConfigSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     prepare: z.ZodOptional<z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
+        commands: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+        runTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
+        runRetries: z.ZodOptional<z.ZodNumber>;
         reuse: z.ZodOptional<z.ZodArray<z.ZodString>>;
         timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+        preflight: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            command: z.ZodString;
+            timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    health: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        tcp: z.ZodOptional<z.ZodString>;
+        http: z.ZodOptional<z.ZodString>;
+        command: z.ZodOptional<z.ZodString>;
+        logAbsent: z.ZodOptional<z.ZodObject<{
+            command: z.ZodString;
+            pattern: z.ZodString;
+        }, z.core.$strict>>;
+        tls: z.ZodOptional<z.ZodBoolean>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    services_up: z.ZodOptional<z.ZodObject<{
+        commands: z.ZodArray<z.ZodArray<z.ZodString>>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+        retries: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    services_down: z.ZodOptional<z.ZodObject<{
+        commands: z.ZodArray<z.ZodArray<z.ZodString>>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+        retries: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    reset: z.ZodOptional<z.ZodObject<{
+        commands: z.ZodArray<z.ZodArray<z.ZodString>>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+        retries: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    seed: z.ZodOptional<z.ZodObject<{
+        commands: z.ZodArray<z.ZodArray<z.ZodString>>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+        retries: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    healthcheck: z.ZodOptional<z.ZodObject<{
+        commands: z.ZodArray<z.ZodArray<z.ZodString>>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+        retries: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
+    env_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
     services: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         command: z.ZodString;