@dogfood-lab/schemas 1.3.1 → 1.4.0

package/README.md

@@ -70,7 +70,7 @@ import recordSchema from '@dogfood-lab/schemas/json/dogfood-record.schema.json'
 | | Constraint |
 |---|---|
 | JSON Schema dialect | 2020-12 |
-| Node | ≥ 20 |
+| Node | ≥ 22 |
 | `$id` form | `https://github.com/dogfood-lab/testing-os/packages/schemas/src/json/<name>.schema.json` |
 
 `$id` is a contract field. Changes that consumers should treat as contract changes bump the monorepo's lockstep version.

package/dist/enums.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Contract enums — the single source of truth for the three FULL-SET enums
+ * that the contract JSON schemas declare identically across multiple files.
+ *
+ * F1-CONTRACTS-002 (Wave 4, MED). Three full-set enums are hand-maintained as
+ * identical literal arrays across the contract schema JSON documents:
+ *
+ *   - product_surface  ["cli","desktop","web","api","mcp-server",
+ *                        "npm-package","plugin","library"]   — 7 files
+ *   - execution_mode   ["bot","human","mixed"]               — 7 files
+ *   - evidence-kind    ["log","screenshot","recording",
+ *                        "transcript","artifact","other"]    — 4 files
+ *
+ * `stageC-cross-contract-enum-seal.test.ts` DETECTS drift between those JSON
+ * copies, but nothing EXPORTS the sets as importable values. A consumer that
+ * wants to render the surface picker, validate a CLI `--surface` flag, or
+ * iterate the evidence kinds had to hand-copy the array — a fresh drift source
+ * the seal cannot see.
+ *
+ * These constants are the value consumers import (NOT a hand-copied literal),
+ * mirroring `SUPPORTED_SCHEMA_VERSIONS` in `src/schema-versions.ts`:
+ *   - downstream packages import the set instead of re-typing it;
+ *   - the seal test asserts each JSON-schema enum EQUALS the matching constant,
+ *     converting drift-detect into single-source ENFORCEMENT — a JSON enum that
+ *     diverges from the constant here goes RED.
+ *
+ * SCOPE — FULL-SET enums only. `doctrine.transfer_scope` is a DELIBERATE
+ * 3-value subset (["surface_archetype","execution_mode","org_wide"]) of the
+ * 5-value `transfer_scope` carried by finding/recommendation/pattern, and is
+ * intentionally NOT exported here as a sealed full-set enum — the seal must
+ * leave it alone.
+ *
+ * `as const` keeps the literal element types and freezes member order, so the
+ * arrays double as `readonly` tuples for `typeof PRODUCT_SURFACES[number]`
+ * union derivation downstream.
+ */
+/**
+ * The full set of product surfaces a tested artifact can target. Order matches
+ * the contract JSON enums byte-for-byte (the seal asserts sorted-set identity,
+ * but consumers that render a picker get a stable, intentional order).
+ */
+export declare const PRODUCT_SURFACES: readonly ["cli", "desktop", "web", "api", "mcp-server", "npm-package", "plugin", "library"];
+/** How the work under test was executed. */
+export declare const EXECUTION_MODES: readonly ["bot", "human", "mixed"];
+/** The kinds of evidence a record may carry. */
+export declare const EVIDENCE_KINDS: readonly ["log", "screenshot", "recording", "transcript", "artifact", "other"];
+/** Union of the eight product surfaces. */
+export type ProductSurface = (typeof PRODUCT_SURFACES)[number];
+/** Union of the three execution modes. */
+export type ExecutionMode = (typeof EXECUTION_MODES)[number];
+/** Union of the six evidence kinds. */
+export type EvidenceKind = (typeof EVIDENCE_KINDS)[number];
+//# sourceMappingURL=enums.d.ts.map

package/dist/enums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../src/enums.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6FASnB,CAAC;AAEX,4CAA4C;AAC5C,eAAO,MAAM,eAAe,oCAAqC,CAAC;AAElE,gDAAgD;AAChD,eAAO,MAAM,cAAc,gFAOjB,CAAC;AAEX,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC/D,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7D,uCAAuC;AACvC,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/enums.js

@@ -0,0 +1,63 @@
+/**
+ * Contract enums — the single source of truth for the three FULL-SET enums
+ * that the contract JSON schemas declare identically across multiple files.
+ *
+ * F1-CONTRACTS-002 (Wave 4, MED). Three full-set enums are hand-maintained as
+ * identical literal arrays across the contract schema JSON documents:
+ *
+ *   - product_surface  ["cli","desktop","web","api","mcp-server",
+ *                        "npm-package","plugin","library"]   — 7 files
+ *   - execution_mode   ["bot","human","mixed"]               — 7 files
+ *   - evidence-kind    ["log","screenshot","recording",
+ *                        "transcript","artifact","other"]    — 4 files
+ *
+ * `stageC-cross-contract-enum-seal.test.ts` DETECTS drift between those JSON
+ * copies, but nothing EXPORTS the sets as importable values. A consumer that
+ * wants to render the surface picker, validate a CLI `--surface` flag, or
+ * iterate the evidence kinds had to hand-copy the array — a fresh drift source
+ * the seal cannot see.
+ *
+ * These constants are the value consumers import (NOT a hand-copied literal),
+ * mirroring `SUPPORTED_SCHEMA_VERSIONS` in `src/schema-versions.ts`:
+ *   - downstream packages import the set instead of re-typing it;
+ *   - the seal test asserts each JSON-schema enum EQUALS the matching constant,
+ *     converting drift-detect into single-source ENFORCEMENT — a JSON enum that
+ *     diverges from the constant here goes RED.
+ *
+ * SCOPE — FULL-SET enums only. `doctrine.transfer_scope` is a DELIBERATE
+ * 3-value subset (["surface_archetype","execution_mode","org_wide"]) of the
+ * 5-value `transfer_scope` carried by finding/recommendation/pattern, and is
+ * intentionally NOT exported here as a sealed full-set enum — the seal must
+ * leave it alone.
+ *
+ * `as const` keeps the literal element types and freezes member order, so the
+ * arrays double as `readonly` tuples for `typeof PRODUCT_SURFACES[number]`
+ * union derivation downstream.
+ */
+/**
+ * The full set of product surfaces a tested artifact can target. Order matches
+ * the contract JSON enums byte-for-byte (the seal asserts sorted-set identity,
+ * but consumers that render a picker get a stable, intentional order).
+ */
+export const PRODUCT_SURFACES = [
+    'cli',
+    'desktop',
+    'web',
+    'api',
+    'mcp-server',
+    'npm-package',
+    'plugin',
+    'library',
+];
+/** How the work under test was executed. */
+export const EXECUTION_MODES = ['bot', 'human', 'mixed'];
+/** The kinds of evidence a record may carry. */
+export const EVIDENCE_KINDS = [
+    'log',
+    'screenshot',
+    'recording',
+    'transcript',
+    'artifact',
+    'other',
+];
+//# sourceMappingURL=enums.js.map

package/dist/enums.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../src/enums.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK;IACL,SAAS;IACT,KAAK;IACL,KAAK;IACL,YAAY;IACZ,aAAa;IACb,QAAQ;IACR,SAAS;CACD,CAAC;AAEX,4CAA4C;AAC5C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAElE,gDAAgD;AAChD,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,KAAK;IACL,YAAY;IACZ,WAAW;IACX,YAAY;IACZ,UAAU;IACV,OAAO;CACC,CAAC"}

package/dist/index.d.ts

@@ -28,5 +28,19 @@ export declare const allSchemas: {
     readonly scenario: JsonSchema;
 };
 export type SchemaName = keyof typeof allSchemas;
+/**
+ * Test-only seam for d1-schemas-B002. Exposes the module-private {@link load}
+ * so the parse-error-context guard can be exercised against a corrupt fixture
+ * without touching the real bundled `src/json` tree. Mirrors the existing
+ * `_resetValidatorCacheForTests` / `_schemasModuleInstanceCount` test exports —
+ * underscore-prefixed, not part of the public API.
+ *
+ * @param filename    schema basename, e.g. `dogfood-record.schema.json`
+ * @param dirOverride optional directory to read from instead of the bundled
+ *                    `jsonDir` (tests point this at a TEST_ROOT temp dir)
+ */
+export declare function _loadSchemaForTests(filename: string, dirOverride?: string): JsonSchema;
 export { compileSchema, validatePayload, createAjv, _resetValidatorCacheForTests, _schemasModuleInstanceCount, type ValidationError, type ValidationResult, } from './validate.js';
+export { SUPPORTED_SCHEMA_VERSIONS, type SupportedSchemaVersion, type SupportedSchemaContract, } from './schema-versions.js';
+export { PRODUCT_SURFACES, EXECUTION_MODES, EVIDENCE_KINDS, type ProductSurface, type ExecutionMode, type EvidenceKind, } from './enums.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,eAAO,MAAM,YAAY,EAAE,UAA+C,CAAC;AAC3E,eAAO,MAAM,sBAAsB,EAAE,UAA0D,CAAC;AAChG,eAAO,MAAM,aAAa,EAAE,UAAgD,CAAC;AAC7E,eAAO,MAAM,aAAa,EAAE,UAAgD,CAAC;AAC7E,eAAO,MAAM,oBAAoB,EAAE,UAAuD,CAAC;AAC3F,eAAO,MAAM,cAAc,EAAE,UAAiD,CAAC;AAC/E,eAAO,MAAM,YAAY,EAAE,UAAuC,CAAC;AACnE,eAAO,MAAM,cAAc,EAAE,UAAyC,CAAC;AAEvE,eAAO,MAAM,UAAU;;;;;;;;;CASb,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAC;AAEjD,OAAO,EACL,aAAa,EACb,eAAe,EACf,SAAS,EACT,4BAA4B,EAC5B,2BAA2B,EAC3B,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6DA,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,eAAO,MAAM,YAAY,EAAE,UAA+C,CAAC;AAC3E,eAAO,MAAM,sBAAsB,EAAE,UAA0D,CAAC;AAChG,eAAO,MAAM,aAAa,EAAE,UAAgD,CAAC;AAC7E,eAAO,MAAM,aAAa,EAAE,UAAgD,CAAC;AAC7E,eAAO,MAAM,oBAAoB,EAAE,UAAuD,CAAC;AAC3F,eAAO,MAAM,cAAc,EAAE,UAAiD,CAAC;AAC/E,eAAO,MAAM,YAAY,EAAE,UAAuC,CAAC;AACnE,eAAO,MAAM,cAAc,EAAE,UAAyC,CAAC;AAEvE,eAAO,MAAM,UAAU;;;;;;;;;CASb,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,CAEtF;AAED,OAAO,EACL,aAAa,EACb,eAAe,EACf,SAAS,EACT,4BAA4B,EAC5B,2BAA2B,EAC3B,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,yBAAyB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -18,9 +18,37 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const here = dirname(fileURLToPath(import.meta.url));
 const jsonDir = resolve(here, '../src/json');
-function load(filename) {
-    const raw = readFileSync(resolve(jsonDir, filename), 'utf8');
-    return JSON.parse(raw);
+/**
+ * Load and parse a bundled JSON schema.
+ *
+ * d1-schemas-B002 — readFileSync + JSON.parse are wrapped so a corrupt or
+ * truncated package-bundled `src/json/*.schema.json` (a packaging defect that
+ * can ship in a tarball) throws a SELF-IDENTIFYING error at module-init instead
+ * of a bare `SyntaxError: Unexpected end of JSON input` that names no file. The
+ * rethrown message names the package and the offending filename so the consumer
+ * knows exactly which of the eight schemas to inspect/re-install — they do not
+ * have to bisect by hand. This is the only structured channel available at
+ * module-init (no CLI renderer / no logStage pipeline exists this early), so the
+ * helpful contract is "a thrown Error whose message carries the recovery handle."
+ *
+ * `dirOverride` exists only for the test seam (`_loadSchemaForTests`); production
+ * callers always read from the real bundled `jsonDir`.
+ */
+function load(filename, dirOverride) {
+    const path = resolve(dirOverride ?? jsonDir, filename);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        throw new Error(`@dogfood-lab/schemas: failed to read bundled schema ${filename} (at ${path}): ${e.message}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`@dogfood-lab/schemas: failed to parse bundled schema ${filename} (at ${path}) as JSON — the package artifact may be corrupt or truncated: ${e.message}`);
+    }
 }
 export const recordSchema = load('dogfood-record.schema.json');
 export const recordSubmissionSchema = load('dogfood-record-submission.schema.json');
@@ -40,5 +68,21 @@ export const allSchemas = {
     policy: policySchema,
     scenario: scenarioSchema,
 };
+/**
+ * Test-only seam for d1-schemas-B002. Exposes the module-private {@link load}
+ * so the parse-error-context guard can be exercised against a corrupt fixture
+ * without touching the real bundled `src/json` tree. Mirrors the existing
+ * `_resetValidatorCacheForTests` / `_schemasModuleInstanceCount` test exports —
+ * underscore-prefixed, not part of the public API.
+ *
+ * @param filename    schema basename, e.g. `dogfood-record.schema.json`
+ * @param dirOverride optional directory to read from instead of the bundled
+ *                    `jsonDir` (tests point this at a TEST_ROOT temp dir)
+ */
+export function _loadSchemaForTests(filename, dirOverride) {
+    return load(filename, dirOverride);
+}
 export { compileSchema, validatePayload, createAjv, _resetValidatorCacheForTests, _schemasModuleInstanceCount, } from './validate.js';
+export { SUPPORTED_SCHEMA_VERSIONS, } from './schema-versions.js';
+export { PRODUCT_SURFACES, EXECUTION_MODES, EVIDENCE_KINDS, } from './enums.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACrD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;AAE7C,SAAS,IAAI,CAAC,QAAgB;IAC5B,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAC;AACvC,CAAC;AAcD,MAAM,CAAC,MAAM,YAAY,GAAe,IAAI,CAAC,4BAA4B,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAe,IAAI,CAAC,uCAAuC,CAAC,CAAC;AAChG,MAAM,CAAC,MAAM,aAAa,GAAe,IAAI,CAAC,6BAA6B,CAAC,CAAC;AAC7E,MAAM,CAAC,MAAM,aAAa,GAAe,IAAI,CAAC,6BAA6B,CAAC,CAAC;AAC7E,MAAM,CAAC,MAAM,oBAAoB,GAAe,IAAI,CAAC,oCAAoC,CAAC,CAAC;AAC3F,MAAM,CAAC,MAAM,cAAc,GAAe,IAAI,CAAC,8BAA8B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,YAAY,GAAe,IAAI,CAAC,oBAAoB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,cAAc,GAAe,IAAI,CAAC,sBAAsB,CAAC,CAAC;AAEvE,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,YAAY;IACpB,gBAAgB,EAAE,sBAAsB;IACxC,OAAO,EAAE,aAAa;IACtB,OAAO,EAAE,aAAa;IACtB,cAAc,EAAE,oBAAoB;IACpC,QAAQ,EAAE,cAAc;IACxB,MAAM,EAAE,YAAY;IACpB,QAAQ,EAAE,cAAc;CAChB,CAAC;AAIX,OAAO,EACL,aAAa,EACb,eAAe,EACf,SAAS,EACT,4BAA4B,EAC5B,2BAA2B,GAG5B,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACrD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,SAAS,IAAI,CAAC,QAAgB,EAAE,WAAoB;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,EAAE,QAAQ,CAAC,CAAC;IACvD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,uDAAuD,QAAQ,QAAQ,IAAI,MACxE,CAAW,CAAC,OACf,EAAE,CACH,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAC;IACvC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,wDAAwD,QAAQ,QAAQ,IAAI,iEACzE,CAAW,CAAC,OACf,EAAE,CACH,CAAC;IACJ,CAAC;AACH,CAAC;AAcD,MAAM,CAAC,MAAM,YAAY,GAAe,IAAI,CAAC,4BAA4B,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAe,IAAI,CAAC,uCAAuC,CAAC,CAAC;AAChG,MAAM,CAAC,MAAM,aAAa,GAAe,IAAI,CAAC,6BAA6B,CAAC,CAAC;AAC7E,MAAM,CAAC,MAAM,aAAa,GAAe,IAAI,CAAC,6BAA6B,CAAC,CAAC;AAC7E,MAAM,CAAC,MAAM,oBAAoB,GAAe,IAAI,CAAC,oCAAoC,CAAC,CAAC;AAC3F,MAAM,CAAC,MAAM,cAAc,GAAe,IAAI,CAAC,8BAA8B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,YAAY,GAAe,IAAI,CAAC,oBAAoB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,cAAc,GAAe,IAAI,CAAC,sBAAsB,CAAC,CAAC;AAEvE,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,YAAY;IACpB,gBAAgB,EAAE,sBAAsB;IACxC,OAAO,EAAE,aAAa;IACtB,OAAO,EAAE,aAAa;IACtB,cAAc,EAAE,oBAAoB;IACpC,QAAQ,EAAE,cAAc;IACxB,MAAM,EAAE,YAAY;IACpB,QAAQ,EAAE,cAAc;CAChB,CAAC;AAIX;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,WAAoB;IACxE,OAAO,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AACrC,CAAC;AAED,OAAO,EACL,aAAa,EACb,eAAe,EACf,SAAS,EACT,4BAA4B,EAC5B,2BAA2B,GAG5B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,yBAAyB,GAG1B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,cAAc,GAIf,MAAM,YAAY,CAAC"}

package/dist/schema-versions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SUPPORTED_SCHEMA_VERSIONS — the single source of truth for which
+ * `schema_version` values this build of testing-os accepts.
+ *
+ * F1-CONTRACTS-001 (Wave 2, HIGH). Every contract schema declares
+ * `schema_version` as a pattern-only string (`^\d+\.\d+\.\d+$`) — it gates
+ * SHAPE, not VALUE. Nothing compared a declared `schema_version` against a
+ * supported set, so a submission declaring `schema_version: '2.0.0'` (or
+ * `99.0.0`) validated clean against the live 1.x schema whenever its shape
+ * happened to fit: a genuinely-incompatible future major was silently
+ * mis-validated instead of cleanly refused.
+ *
+ * This map is the value consumers import (NOT a hand-copied literal):
+ *   - `packages/verify` imports it to drive the `schema_version` VALUE gate
+ *     (`validators/schema-version.js`) and to stamp the persisted record's
+ *     `schema_version` (`record.current`) instead of a hardcoded `'1.0.0'`.
+ *
+ * Per registered contract: the `current` version plus the accepted MAJOR
+ * range `[minMajor, maxMajor]`. The gate compares a payload's MAJOR against
+ * that range — patch/minor deltas inside the range PASS; a major above
+ * `maxMajor` means "this build is too old, upgrade testing-os"; a major below
+ * `minMajor` means "re-emit against the current contract".
+ *
+ * Keys mirror `allSchemas` for the contracts that carry a `schema_version`
+ * field, plus the `agentOutput` swarm envelope. `policy` and `scenario` do
+ * NOT carry a `schema_version` contract field and are intentionally absent —
+ * the gate only fires on payloads that declare a `schema_version`.
+ */
+export interface SupportedSchemaVersion {
+    /** The current/canonical version this build emits for the contract. */
+    current: string;
+    /** Lowest MAJOR this build will accept (inclusive). Below → TOO_OLD. */
+    minMajor: number;
+    /** Highest MAJOR this build will accept (inclusive). Above → TOO_NEW. */
+    maxMajor: number;
+}
+/**
+ * The registered contract keys that carry a `schema_version`. `record` and
+ * `recordSubmission` share the v1 record family; `agentOutput` is the swarm
+ * agent-output envelope (validated separately at collect time, registered
+ * here so a future versioned envelope has one home).
+ */
+export type SupportedSchemaContract = 'record' | 'recordSubmission' | 'finding' | 'pattern' | 'recommendation' | 'doctrine' | 'agentOutput';
+export declare const SUPPORTED_SCHEMA_VERSIONS: Record<SupportedSchemaContract, SupportedSchemaVersion>;
+//# sourceMappingURL=schema-versions.d.ts.map

package/dist/schema-versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-versions.d.ts","sourceRoot":"","sources":["../src/schema-versions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAC/B,QAAQ,GACR,kBAAkB,GAClB,SAAS,GACT,SAAS,GACT,gBAAgB,GAChB,UAAU,GACV,aAAa,CAAC;AAElB,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAC5C,uBAAuB,EACvB,sBAAsB,CASd,CAAC"}

package/dist/schema-versions.js

@@ -0,0 +1,38 @@
+/**
+ * SUPPORTED_SCHEMA_VERSIONS — the single source of truth for which
+ * `schema_version` values this build of testing-os accepts.
+ *
+ * F1-CONTRACTS-001 (Wave 2, HIGH). Every contract schema declares
+ * `schema_version` as a pattern-only string (`^\d+\.\d+\.\d+$`) — it gates
+ * SHAPE, not VALUE. Nothing compared a declared `schema_version` against a
+ * supported set, so a submission declaring `schema_version: '2.0.0'` (or
+ * `99.0.0`) validated clean against the live 1.x schema whenever its shape
+ * happened to fit: a genuinely-incompatible future major was silently
+ * mis-validated instead of cleanly refused.
+ *
+ * This map is the value consumers import (NOT a hand-copied literal):
+ *   - `packages/verify` imports it to drive the `schema_version` VALUE gate
+ *     (`validators/schema-version.js`) and to stamp the persisted record's
+ *     `schema_version` (`record.current`) instead of a hardcoded `'1.0.0'`.
+ *
+ * Per registered contract: the `current` version plus the accepted MAJOR
+ * range `[minMajor, maxMajor]`. The gate compares a payload's MAJOR against
+ * that range — patch/minor deltas inside the range PASS; a major above
+ * `maxMajor` means "this build is too old, upgrade testing-os"; a major below
+ * `minMajor` means "re-emit against the current contract".
+ *
+ * Keys mirror `allSchemas` for the contracts that carry a `schema_version`
+ * field, plus the `agentOutput` swarm envelope. `policy` and `scenario` do
+ * NOT carry a `schema_version` contract field and are intentionally absent —
+ * the gate only fires on payloads that declare a `schema_version`.
+ */
+export const SUPPORTED_SCHEMA_VERSIONS = {
+    record: { current: '1.0.0', minMajor: 1, maxMajor: 1 },
+    recordSubmission: { current: '1.0.0', minMajor: 1, maxMajor: 1 },
+    finding: { current: '1.0.0', minMajor: 1, maxMajor: 1 },
+    pattern: { current: '1.0.0', minMajor: 1, maxMajor: 1 },
+    recommendation: { current: '1.0.0', minMajor: 1, maxMajor: 1 },
+    doctrine: { current: '1.0.0', minMajor: 1, maxMajor: 1 },
+    agentOutput: { current: '1.0.0', minMajor: 1, maxMajor: 1 },
+};
+//# sourceMappingURL=schema-versions.js.map

package/dist/schema-versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-versions.js","sourceRoot":"","sources":["../src/schema-versions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA0BH,MAAM,CAAC,MAAM,yBAAyB,GAGlC;IACF,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE;IACtD,gBAAgB,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE;IAChE,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE;IACvD,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE;IACvD,cAAc,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE;IAC9D,QAAQ,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE;IACxD,WAAW,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE;CACnD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/schemas",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "JSON schemas for the testing-os contract spine — record, finding, pattern, recommendation, doctrine, policy, scenario, submission.",
   "type": "module",
   "main": "dist/index.js",
@@ -33,6 +33,7 @@
     "ajv-formats": "^3.0.1"
   },
   "devDependencies": {
+    "@dogfood-lab/dogfood-swarm": "*",
     "@types/node": "^25.3.5",
     "vitest": "^4.1.6"
   },

package/src/json/agent-output.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dogfood-lab/testing-os/packages/schemas/src/json/agent-output.schema.json",
+  "title": "Swarm Agent Output (canonical envelope)",
+  "description": "JSON contract for agent JSON outputs written to swarms/<run-id>/wave-N/<domain>.json. F-252713-017 (Phase 7 wave 1): collect-time schema-conformance gate. Replaces silent normalization in collect.js with a structured error pointing the agent at the canonical shape. Validates the OUTER envelope ONLY — every agent output regardless of phase has { domain, summary } at minimum; findings[]/features[]/fixes[]/files_changed[] are all independently optional here (additionalProperties:true). This schema does NOT enforce phase-specific inner shape — there is no oneOf/if-then/dependentRequired branch keyed on phase. Phase-specific inner-shape enforcement (audit outputs require findings[], feature outputs require features[], amend outputs require fixes[] + files_changed[]) is performed separately by packages/dogfood-swarm/lib/output-schema.js (validateAuditOutput/validateFeatureOutput/validateAmendOutput), run by commands/collect.js AFTER this envelope gate. The category/severity/feature-category enums in the $defs below mirror AUDIT_CATEGORIES + FEATURE_CATEGORIES + SEVERITY_ENUM in output-schema.js — kept in lockstep (sealed by packages/schemas/test/stageA-agent-output-lockstep.test.ts).",
+  "type": "object",
+  "required": ["domain", "summary"],
+  "additionalProperties": true,
+  "properties": {
+    "domain": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Audit domain that produced this output (e.g. backend, ci-tooling, docs, outputs, pipeline)."
+    },
+    "stage": {
+      "type": "string",
+      "enum": ["A", "B", "C", "D"],
+      "description": "Health-pass stage (audit outputs only). Optional in feature/amend outputs."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One-line summary of what the agent did and what they found."
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" },
+      "description": "Audit-pass findings. Required in audit outputs (Stages A–D)."
+    },
+    "features": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/feature" },
+      "description": "Feature-pass features. Required in feature-pass outputs."
+    },
+    "fixes": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/fix" },
+      "description": "Amend-pass fixes. Required in amend outputs (Phase 7 waves)."
+    },
+    "files_changed": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Files the agent edited. Required in amend outputs."
+    },
+    "skipped": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/skip" },
+      "description": "Findings/features skipped with a reason. Cross-domain dependencies, blocked-on items, etc."
+    },
+    "verification_skipped": {
+      "type": "boolean",
+      "default": false,
+      "description": "Set true when the agent skipped per-agent verification per the parallel-wave serial-final-verify discipline (PROTOCOL.md §Serial final verification). Coordinator runs a single `npm run verify` against the cumulative tree at collect time. False or absent = agent ran its own verify (legacy single-agent waves, manual dispatch)."
+    }
+  },
+  "$defs": {
+    "finding": {
+      "type": "object",
+      "required": ["id", "severity", "category", "description"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "severity": {
+          "type": "string",
+          "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"],
+          "description": "Mirrors SEVERITY_ENUM in packages/dogfood-swarm/lib/output-schema.js."
+        },
+        "category": {
+          "type": "string",
+          "enum": [
+            "bug", "security", "quality", "types", "tests", "docs",
+            "defensive", "observability", "degradation", "future-proofing",
+            "ux", "accessibility",
+            "hygiene", "error_message_quality", "cli_help_quality",
+            "silent_failure", "tests_coverage"
+          ],
+          "description": "Mirrors AUDIT_CATEGORIES in packages/dogfood-swarm/lib/output-schema.js. Extended in Phase 7 wave 2 W2-BACK-002 to absorb 5 historical wave-15/20 reused categories (hygiene, error_message_quality, cli_help_quality, silent_failure, tests_coverage). Underscore form preserved as historical record."
+        },
+        "file": { "type": "string" },
+        "line": { "type": "number" },
+        "symbol": { "type": "string" },
+        "description": { "type": "string", "minLength": 1 },
+        "recommendation": { "type": "string" },
+        "rule_id": { "type": "string" }
+      }
+    },
+    "feature": {
+      "type": "object",
+      "required": ["id", "priority", "category", "description"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "pattern": "^F-[A-Za-z0-9-]+$" },
+        "priority": {
+          "type": "string",
+          "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"]
+        },
+        "category": {
+          "type": "string",
+          "enum": ["missing-feature", "ux", "performance", "integration", "production-readiness"]
+        },
+        "description": { "type": "string", "minLength": 1 },
+        "use_case": { "type": "string" },
+        "evidence_base": { "type": "string" },
+        "scope": { "type": "array", "items": { "type": "string" } },
+        "effort": { "type": "string", "enum": ["small", "medium", "large"] },
+        "cross_ref": { "type": "string" },
+        "recommendation": { "type": "string" }
+      }
+    },
+    "fix": {
+      "type": "object",
+      "required": ["finding_id", "description"],
+      "additionalProperties": true,
+      "properties": {
+        "finding_id": { "type": "string", "minLength": 1 },
+        "file": { "type": "string" },
+        "description": { "type": "string", "minLength": 1 }
+      }
+    },
+    "skip": {
+      "type": "object",
+      "required": ["finding_id", "reason"],
+      "additionalProperties": true,
+      "properties": {
+        "finding_id": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/src/json/policy.schema.json

@@ -103,6 +103,59 @@
     }
   },
 
+  "allOf": [
+    {
+      "$comment": "d1-schemas-003 — additive conditional constraint mirroring the H4 precedent in dogfood-finding.schema.json. enforcement.reason and enforcement.review_after have always carried 'Required if ...' descriptions, but until stage A this was honor-system prose the schema dropped silently — a repo could mark itself `exempt` (opting out of Gate F per policy.schema.json:30) with reason:null/review_after:null and validate clean. The schema now enforces it: a warn-only/exempt mode requires a non-null `reason`; an exempt mode additionally requires a `review_after` date. Note the `not const null` guard — the property type is [string,null], and a literal null would satisfy bare `required`, so the value must be constrained to a real justification.",
+      "if": {
+        "properties": {
+          "enforcement": {
+            "type": "object",
+            "properties": {
+              "mode": { "enum": ["warn-only", "exempt"] }
+            },
+            "required": ["mode"]
+          }
+        },
+        "required": ["enforcement"]
+      },
+      "then": {
+        "properties": {
+          "enforcement": {
+            "required": ["reason"],
+            "properties": {
+              "reason": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "d1-schemas-003 (exempt half) — an exempt repo is fully opted out of Gate F, so it additionally requires a scheduled review date. Same null-guard reasoning as the reason half.",
+      "if": {
+        "properties": {
+          "enforcement": {
+            "type": "object",
+            "properties": {
+              "mode": { "const": "exempt" }
+            },
+            "required": ["mode"]
+          }
+        },
+        "required": ["enforcement"]
+      },
+      "then": {
+        "properties": {
+          "enforcement": {
+            "required": ["review_after"],
+            "properties": {
+              "review_after": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    }
+  ],
+
   "$defs": {
     "surface_policy": {
       "type": "object",

package/src/json/scenario.schema.json

@@ -84,6 +84,17 @@
             "type": "string",
             "description": "What a passing result looks like. Required if verifiable is true."
           }
+        },
+        "$comment": "d1-schemas-NEW — third instance of the d1-schemas-003 family. The `expected` description has always said 'Required if verifiable is true', but until stage A nothing enforced it, so a step could claim verifiable:true with no pass condition and validate clean. A keyed if/then (NOT a dependentRequired, which fires on key presence and would wrongly trip on verifiable:false) requires `expected` only when verifiable === true. Mirrors the H4 precedent in dogfood-finding.schema.json.",
+        "if": {
+          "properties": { "verifiable": { "const": true } },
+          "required": ["verifiable"]
+        },
+        "then": {
+          "required": ["expected"],
+          "properties": {
+            "expected": { "type": "string", "minLength": 1 }
+          }
         }
       }
     },