@dogfood-lab/schemas 1.4.0 → 1.5.0

package/README.md

@@ -75,6 +75,24 @@ import recordSchema from '@dogfood-lab/schemas/json/dogfood-record.schema.json'
 
 `$id` is a contract field. Changes that consumers should treat as contract changes bump the monorepo's lockstep version.
 
+## Schema versioning
+
+Payloads that carry a `schema_version` are gated by **MAJOR range**, not exact match. The accepted ranges live in one place — `SUPPORTED_SCHEMA_VERSIONS` (`src/schema-versions.ts`), which `@dogfood-lab/verify` imports to drive the gate and to stamp the persisted record's `schema_version`:
+
+| Field | Meaning |
+|---|---|
+| `current` | the version this build emits for the contract |
+| `minMajor` | lowest MAJOR accepted (inclusive) |
+| `maxMajor` | highest MAJOR accepted (inclusive) |
+
+The gate compares the payload's MAJOR against `[minMajor, maxMajor]`:
+
+- **MAJOR inside the range** (any patch/minor) → **accepted**.
+- **MAJOR above `maxMajor`** → rejected `CONTRACT_SCHEMA_TOO_NEW` — the payload was emitted against a newer contract than this build understands. **Operator action: upgrade testing-os.**
+- **MAJOR below `minMajor`** → rejected `CONTRACT_SCHEMA_TOO_OLD` — the payload predates the supported contract. **Operator action: re-emit against the current contract.**
+
+The contracts that carry `schema_version` are `record`, `recordSubmission`, `finding`, `pattern`, `recommendation`, `doctrine`, and the `agentOutput` swarm envelope. **`policy` and `scenario` deliberately carry no `schema_version`** and are exempt from the gate — the gate only fires on payloads that declare one. See the [error code reference](https://dogfood-lab.github.io/testing-os/handbook/error-codes/) for how the `CONTRACT_SCHEMA_TOO_*` rejections surface to a consumer.
+
 ## Docs
 
 📖 Full handbook: **<https://dogfood-lab.github.io/testing-os/handbook/>**

package/dist/index.d.ts

@@ -43,4 +43,5 @@ export declare function _loadSchemaForTests(filename: string, dirOverride?: stri
 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';
+export { EXAMPLE_PAYLOADS, type Submission, type Record, type Finding, type ScenarioResult, type StepResult, type ScenarioEvidence, type Ref, type Source, type Timing, type CiCheck, type CiCheckKind, type CiCheckStatus, type Verdict, type StepStatus, type RecordOverallVerdict, type Verification, type ProvenanceRemediation, type FindingStatus, type JourneyStage, type IssueKind, type RootCauseKind, type RemediationKind, type TransferScope, type FindingEvidence, type FindingEvidenceKind, type FixRef, type FixRefKind, type FindingDerived, type FindingReview, type ReviewAction, type RejectReason, type FindingLineage, type FindingInvalidation, } from './payload-types.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":"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"}
+{"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;AAMpB,OAAO,EACL,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,GAAG,EACR,KAAK,MAAM,EACX,KAAK,MAAM,EACX,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -85,4 +85,9 @@ export function _loadSchemaForTests(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';
+// FT-h — hand-authored TypeScript interfaces for the contract payload SHAPES,
+// so TS consumers get compile-time safety on the envelope (the schema OBJECTS
+// + validatePayload only catch shape errors at runtime). Kept in sync with the
+// JSON schemas; each interface carries a `Mirrors:` pointer to its source.
+export { EXAMPLE_PAYLOADS, } from './payload-types.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;;;;;;;;;;;;;;;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"}
+{"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;AAEpB,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,2EAA2E;AAC3E,OAAO,EACL,gBAAgB,GAkCjB,MAAM,oBAAoB,CAAC"}

package/dist/payload-types.d.ts

@@ -0,0 +1,401 @@
+/**
+ * Hand-authored TypeScript interfaces for the contract payload shapes.
+ *
+ * FT-h (Wave, HIGH, consumability). The package exports the JSON-schema
+ * OBJECTS, the three full-set enum unions, and `validatePayload`, but no
+ * TypeScript interface for the actual payload SHAPES. A TS consumer that
+ * builds a submission, reads a persisted record, or constructs a finding got
+ * zero compile-time safety on the envelope — `validatePayload` only catches
+ * the mistake at runtime, after the bad object already flowed through typed
+ * code as `unknown`/`any`.
+ *
+ * These interfaces give consumers a typed shape to assert against at author
+ * time. They are HAND-MAINTAINED to mirror the JSON schemas — there is no
+ * codegen step — so each interface and nested type carries a `Mirrors:`
+ * pointer to its source schema, and the {@link EXAMPLE_PAYLOADS} consts at the
+ * bottom are `satisfies`-checked so `tsc --build` (which CI runs via
+ * `npm run verify` → `npm run build`) goes RED the moment an interface drifts
+ * from a representative payload. The companion vitest
+ * (`test/payload-types.test.ts`) closes the other half of the loop: it pushes
+ * those same examples through `validatePayload` and asserts the JSON schema
+ * AGREES they are valid. Interface drift in EITHER direction is caught.
+ *
+ * Reused enum unions: enum-typed fields reference the exported
+ * {@link ProductSurface} / {@link ExecutionMode} / {@link EvidenceKind} unions
+ * rather than re-typing the literals, so those fields stay sealed to the same
+ * single source the cross-contract enum seal enforces on the JSON side.
+ *
+ * SCOPE — the four payloads FT-h names: {@link Submission},
+ * {@link ScenarioResult}, {@link Record}, {@link Finding}. The other four
+ * contract schemas (pattern, recommendation, doctrine, policy) are out of
+ * scope for this slice and intentionally not modelled here; add them the same
+ * way (interface + `Mirrors:` pointer + a `satisfies` example) when a consumer
+ * needs them.
+ */
+import type { ProductSurface, ExecutionMode, EvidenceKind } from './enums.js';
+/** Scenario- and run-level verdict. Mirrors the `verdict` / `overall_verdict` enum. */
+export type Verdict = 'pass' | 'fail' | 'blocked' | 'partial';
+/** Per-step status. Mirrors `scenario_results[].step_results[].status`. */
+export type StepStatus = 'pass' | 'fail' | 'blocked' | 'skip' | 'partial';
+/** Machine CI check kind. Mirrors `ci_checks[].kind`. */
+export type CiCheckKind = 'test' | 'coverage' | 'lint' | 'security' | 'build' | 'other';
+/** Machine CI check status. Mirrors `ci_checks[].status`. */
+export type CiCheckStatus = 'pass' | 'fail' | 'skip';
+/** Git ref of the work under test. Mirrors the `ref` object. */
+export interface Ref {
+    /** Branch name, if applicable. */
+    branch?: string;
+    /** 40-char lowercase-hex commit SHA. Schema pattern: `^[0-9a-f]{40}$`. */
+    commit_sha: string;
+    /** Release version tag if applicable. */
+    version?: string;
+}
+/** SCM provider that ran the workflow. Mirrors the `source.provider` enum. */
+export type SourceProvider = 'github' | 'gitlab';
+/** SCM provenance of the run. Mirrors the `source` object. */
+export interface Source {
+    /** SCM provider — 'github' (GitHub Actions) or 'gitlab' (GitLab CI). */
+    provider: SourceProvider;
+    /** Workflow filename that produced the submission (e.g. a GitHub Actions YAML or '.gitlab-ci.yml'). */
+    workflow: string;
+    /** Provider-native run ID: a GitHub Actions run ID or a GitLab pipeline/job ID. */
+    provider_run_id: string;
+    /** Run attempt number. Schema default is 1. */
+    attempt?: number;
+    /** URL to the provider run. Schema format: uri. */
+    run_url: string;
+    /** Username that triggered the workflow. */
+    actor?: string;
+}
+/** Wall-clock timing of the run. Mirrors the `timing` object. */
+export interface Timing {
+    /** ISO-8601 date-time the run started. */
+    started_at: string;
+    /** ISO-8601 date-time the run finished. */
+    finished_at: string;
+    /** Duration in milliseconds. */
+    duration_ms?: number;
+}
+/** A machine-evaluated CI result. Mirrors a `ci_checks[]` element. */
+export interface CiCheck {
+    id: string;
+    kind: CiCheckKind;
+    status: CiCheckStatus;
+    /** Numeric result (test count, coverage %, etc.). */
+    value?: number;
+    /** Policy threshold if applicable. */
+    threshold?: number;
+}
+/** A single per-step execution result. Mirrors `scenario_results[].step_results[]`. */
+export interface StepResult {
+    /** Must match a step.id from the scenario definition. Pattern: `^[a-z0-9][a-z0-9-]*$`. */
+    step_id: string;
+    status: StepStatus;
+    notes?: string;
+}
+/** A piece of evidence attached to a scenario result. Mirrors `scenario_results[].evidence[]`. */
+export interface ScenarioEvidence {
+    /** Evidence kind — reuses the sealed full-set {@link EvidenceKind} union. */
+    kind: EvidenceKind;
+    /** Evidence URL. Schema format: uri. */
+    url: string;
+    description?: string;
+    /** ISO-8601 date-time when this evidence URL becomes unavailable. */
+    expires_at?: string;
+}
+/**
+ * One scenario's dogfood evidence.
+ *
+ * Mirrors the `scenario_results[]` item shape shared by the submission and the
+ * persisted record. `product_surface` / `execution_mode` reuse the sealed
+ * full-set enum unions.
+ */
+export interface ScenarioResult {
+    /** Stable ID matching a scenario definition in the source repo. */
+    scenario_id: string;
+    scenario_name?: string;
+    /** Semver. Schema pattern: `^\d+\.\d+\.\d+$`. */
+    scenario_version?: string;
+    product_surface: ProductSurface;
+    execution_mode: ExecutionMode;
+    /** Human attester ID. Verifier enforces presence when execution_mode is human or mixed. */
+    attested_by?: string;
+    verdict: Verdict;
+    /** Required when verdict is blocked. Verifier enforces. */
+    blocking_reason?: string;
+    /** Per-step execution results. Schema minItems: 1. */
+    step_results: StepResult[];
+    evidence?: ScenarioEvidence[];
+    notes?: string;
+}
+/**
+ * Source-authored dogfood submission payload — what a consumer repo emits via
+ * `repository_dispatch`. Carries NO verifier-owned fields (no `verification`,
+ * no `policy_version`); `overall_verdict` is a flat {@link Verdict} the source
+ * PROPOSES (the verifier may confirm or downgrade, never upgrade).
+ *
+ * Mirrors: dogfood-record-submission.schema.json.
+ */
+export interface Submission {
+    /** Semver of the submission schema. Schema pattern: `^\d+\.\d+\.\d+$`. */
+    schema_version: string;
+    /** Unique run identifier. Schema pattern: `^[A-Za-z0-9_-]+$` (filesystem-path-safe). */
+    run_id: string;
+    /** Full org/repo name. Schema pattern: `^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$`. */
+    repo: string;
+    ref: Ref;
+    source: Source;
+    timing: Timing;
+    /** Optional — not all dogfood runs include CI. */
+    ci_checks?: CiCheck[];
+    /** Dogfood evidence. Schema minItems: 1. */
+    scenario_results: ScenarioResult[];
+    /** Source-proposed verdict (flat). */
+    overall_verdict: Verdict;
+    notes?: string;
+}
+/**
+ * The persisted record's `overall_verdict` object. Unlike the submission's
+ * flat verdict, the record nests proposed-vs-verified to record the verifier's
+ * decision. Mirrors `overall_verdict` in dogfood-record.schema.json.
+ */
+export interface RecordOverallVerdict {
+    /** Verdict as proposed by the source repo. */
+    proposed: Verdict;
+    /** Final verdict after central verification. */
+    verified: Verdict;
+    /** True if verifier downgraded the proposed verdict. Schema default: false. */
+    downgraded?: boolean;
+    /** Machine-readable reasons if verifier downgraded. */
+    downgrade_reasons?: string[];
+}
+/**
+ * Provenance-remediation metadata — present when a record's provenance could
+ * not be auto-confirmed but was manually stub-verified. Mirrors
+ * `verification.provenance_remediation` in dogfood-record.schema.json.
+ */
+export interface ProvenanceRemediation {
+    status?: 'stub_verified';
+    /** Schema maxLength: 500. */
+    note?: string;
+    remediated_at: string;
+    /** Tri-state: the original boolean, or null when it was never evaluated. */
+    original_provenance_confirmed?: boolean | null;
+}
+/**
+ * Tamper-evident hash-chain metadata stamped by the persist layer when a record
+ * is written. Mirrors the OPTIONAL `integrity` object in
+ * dogfood-record.schema.json — records persisted before the integrity chain
+ * existed have no integrity block, so the field is optional on {@link Record}.
+ * The digest is computed over the record with this block removed (you cannot
+ * hash the digest into itself).
+ */
+export interface RecordIntegrity {
+    /** Lowercase sha256 hex (64 chars) of the canonicalized record without the integrity block. Schema pattern: `^[0-9a-f]{64}$`. */
+    submission_digest: string;
+    /** The previous entry's submission_digest, or 64 zeros (genesis) for the first entry. Schema pattern: `^[0-9a-f]{64}$`. */
+    prev_digest: string;
+    /** Monotonic chain position, starting at 0. Schema minimum: 0. */
+    seq: number;
+}
+/**
+ * Verifier-owned verification block. Mirrors `verification` in
+ * dogfood-record.schema.json. Never authored by source repos.
+ */
+export interface Verification {
+    /** Final outcome. No pending state in persisted records. */
+    status: 'accepted' | 'rejected';
+    verified_at: string;
+    /** True if the provider API (GitHub Actions or GitLab CI, per source.provider) confirmed the source run exists and matches claims. */
+    provenance_confirmed: boolean;
+    /** True if submission passed JSON Schema validation. */
+    schema_valid: boolean;
+    /** True if record satisfies all applicable policy rules. */
+    policy_valid: boolean;
+    /** Machine-readable rejection reasons. Empty/absent if accepted. */
+    rejection_reasons?: string[];
+    provenance_remediation?: ProvenanceRemediation;
+}
+/**
+ * Canonical persisted record written by the central verifier — all
+ * source-authored fields plus verifier-owned ones (`policy_version`,
+ * `verification`, and the nested {@link RecordOverallVerdict}). Never authored
+ * by source repos.
+ *
+ * Mirrors: dogfood-record.schema.json.
+ *
+ * Named `Record` to match the schema title; this shadows the TS global
+ * `Record<K, V>` utility type WITHIN modules that import it, which is the
+ * intended contract-first naming. Modules needing the utility can alias on
+ * import (`import type { Record as DogfoodRecord }`).
+ */
+export interface Record {
+    /** Semver of the persisted record schema. */
+    schema_version: string;
+    /** Semver of the policy this record was evaluated against. Set by verifier. */
+    policy_version: string;
+    run_id: string;
+    repo: string;
+    ref: Ref;
+    source: Source;
+    timing: Timing;
+    ci_checks?: CiCheck[];
+    scenario_results: ScenarioResult[];
+    overall_verdict: RecordOverallVerdict;
+    verification: Verification;
+    notes?: string;
+    /** Tamper-evident hash-chain metadata stamped at persist. Optional — absent on pre-chain records. */
+    integrity?: RecordIntegrity;
+}
+/** Finding lifecycle status. Mirrors `status`. */
+export type FindingStatus = 'candidate' | 'reviewed' | 'accepted' | 'rejected';
+/** Where in the product experience the lesson was observed. Mirrors `journey_stage`. */
+export type JourneyStage = 'install' | 'setup' | 'first_run' | 'core_loop' | 'export' | 'publish' | 'recovery' | 'integration' | 'verification' | 'rollout';
+/** What visibly went wrong. Mirrors `issue_kind`. */
+export type IssueKind = 'entrypoint_truth' | 'interface_assumption' | 'docs_drift' | 'schema_mismatch' | 'build_output_mismatch' | 'flag_contract_mismatch' | 'evidence_insufficiency' | 'evidence_overconstraint' | 'policy_mismatch' | 'freshness_miscalibration' | 'read_after_write_timing' | 'provenance_gap' | 'execution_mode_mismatch' | 'surface_misclassification' | 'ux_discoverability' | 'verification_gap' | 'dispatch_format' | 'concurrency_conflict' | 'process_lifecycle';
+/** Why it actually happened. Mirrors `root_cause_kind`. */
+export type RootCauseKind = 'contract_drift' | 'docs_code_drift' | 'surface_misclassification' | 'missing_precondition' | 'policy_overconstraint' | 'policy_underconstraint' | 'build_config_error' | 'interface_assumption_error' | 'timing_race' | 'tooling_gap' | 'human_process_gap' | 'schema_alignment_failure' | 'dispatch_encoding_error' | 'process_model_mismatch';
+/** What kind of fix resolved it. Mirrors `remediation_kind`. */
+export type RemediationKind = 'docs_change' | 'scenario_change' | 'policy_calibration' | 'schema_fix' | 'build_config_fix' | 'entrypoint_fix' | 'verification_fix' | 'classification_fix' | 'retry_logic' | 'evidence_requirement_change' | 'workflow_change' | 'dispatch_fix' | 'process_fix';
+/**
+ * How far the lesson should travel. Mirrors the finding `transfer_scope` enum
+ * (the FULL 5-value set — NOT the deliberate 3-value doctrine subset).
+ */
+export type TransferScope = 'repo_local' | 'surface_local' | 'surface_archetype' | 'execution_mode' | 'org_wide';
+/** Type of evidence supporting a finding. Mirrors `evidence[].evidence_kind`. */
+export type FindingEvidenceKind = 'record' | 'scenario_result' | 'ci_check' | 'policy' | 'artifact' | 'doc' | 'rejection';
+/** A structured evidence binding on a finding. Mirrors `evidence[]`. */
+export interface FindingEvidence {
+    evidence_kind: FindingEvidenceKind;
+    /** Run ID of the source record. */
+    record_id?: string;
+    /** Scenario ID if evidence is from a scenario result. */
+    scenario_id?: string;
+    /** Path or URL to an artifact. */
+    artifact_ref?: string;
+    /** Path to the policy file. */
+    policy_ref?: string;
+    /** Path to a documentation file. */
+    doc_ref?: string;
+    /** Schema maxLength: 500. */
+    note?: string;
+}
+/** Type of fix reference. Mirrors `fix_refs[].ref_kind`. */
+export type FixRefKind = 'commit' | 'pr' | 'doc' | 'policy_change' | 'scenario_change' | 'workflow_change';
+/** A link to a concrete repair action. Mirrors `fix_refs[]`. */
+export interface FixRef {
+    ref_kind: FixRefKind;
+    /** Commit SHA, PR URL, file path, etc. */
+    ref: string;
+    /** Schema maxLength: 500. */
+    note?: string;
+}
+/** Derivation metadata — present when a finding was machine-generated. Mirrors `derived`. */
+export interface FindingDerived {
+    method: 'deterministic_rule';
+    /** Pattern: `^rule-[a-z0-9][a-z0-9-]*$`. */
+    rule_id: string;
+    derived_at: string;
+    /** Schema minLength: 10, maxLength: 1000. */
+    rationale: string;
+}
+/** The most recent review action taken on a finding. Mirrors `review.last_action`. */
+export type ReviewAction = 'review' | 'accept' | 'reject' | 'edit' | 'merge' | 'reopen' | 'invalidate' | 'supersede';
+/** Structured reject reason. Mirrors `review.reject_reason`. */
+export type RejectReason = 'insufficient_evidence' | 'duplicate' | 'classification_error' | 'not_portable' | 'noise' | 'source_truth_changed' | 'merged_into_canonical';
+/** Current state of the most recent review action. Mirrors `review`. */
+export interface FindingReview {
+    reviewed_by?: string;
+    reviewed_at?: string;
+    /** Schema maxLength: 1000. */
+    decision_reason?: string;
+    /** Schema maxLength: 2000. */
+    review_notes?: string;
+    last_action?: ReviewAction;
+    /**
+     * Structured reject reason. The schema's `allOf` makes this REQUIRED when
+     * `status` is `rejected` — that conditional cannot be expressed in a plain
+     * interface, so callers building a rejected finding must populate it (the
+     * runtime `validatePayload` check is what enforces the conditional).
+     */
+    reject_reason?: RejectReason;
+}
+/** Merge and supersession lineage. Mirrors `lineage`. */
+export interface FindingLineage {
+    /** Finding IDs merged into this canonical finding. */
+    merged_from?: string[];
+    /** Finding ID that supersedes this one. */
+    superseded_by?: string;
+}
+/** Invalidation metadata — present when an accepted finding is no longer trustworthy. Mirrors `invalidation`. */
+export interface FindingInvalidation {
+    is_invalidated: boolean;
+    invalidated_at: string;
+    /** Review event ID that triggered the invalidation. */
+    invalidated_by?: string;
+    /** Schema minLength: 5, maxLength: 1000. */
+    reason: string;
+}
+/**
+ * A reviewed, evidence-backed lesson extracted from one or more dogfood runs —
+ * the smallest durable unit of reusable learning. `product_surface` /
+ * `execution_mode` reuse the sealed full-set enum unions.
+ *
+ * Mirrors: dogfood-finding.schema.json. The schema additionally enforces an
+ * `allOf` conditional (status `rejected` ⇒ `review.reject_reason` required)
+ * that is not expressible here; rely on `validatePayload('finding', …)` for it.
+ */
+export interface Finding {
+    /** Semver of the finding schema. */
+    schema_version: string;
+    /** Stable slug. Pattern: `^dfind-[a-z0-9][a-z0-9-]*$`. */
+    finding_id: string;
+    /** Schema minLength: 10, maxLength: 200. */
+    title: string;
+    status: FindingStatus;
+    /** Full org/repo. Pattern: `^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$`. */
+    repo: string;
+    product_surface: ProductSurface;
+    execution_mode?: ExecutionMode;
+    journey_stage: JourneyStage;
+    issue_kind: IssueKind;
+    root_cause_kind: RootCauseKind;
+    remediation_kind: RemediationKind;
+    transfer_scope: TransferScope;
+    /** Schema minLength: 20, maxLength: 1000. */
+    summary: string;
+    /** Portable rule derived from this finding. Schema maxLength: 500. */
+    doctrine_statement?: string;
+    /** Schema maxLength: 2000. */
+    notes?: string;
+    /** Run IDs of the source records. Schema minItems: 1. */
+    source_record_ids: string[];
+    /** Scenario IDs relevant to this finding. */
+    scenario_ids?: string[];
+    /** Structured evidence binding. Schema minItems: 1 — a finding with no evidence is invalid. */
+    evidence: FindingEvidence[];
+    fix_refs?: FixRef[];
+    created_at?: string;
+    updated_at?: string;
+    derived?: FindingDerived;
+    review?: FindingReview;
+    lineage?: FindingLineage;
+    invalidation?: FindingInvalidation;
+}
+/**
+ * Representative valid payloads, one per modelled interface. Exported so the
+ * companion vitest can push them through `validatePayload` and assert the JSON
+ * schema agrees — the runtime half of the FT-h drift seal. Consumers may also
+ * import these as ready-made fixtures.
+ *
+ * The `as const` example bodies above are `satisfies`-checked against their
+ * interfaces; here we widen to the interface types so the exported shape is the
+ * interface (not a frozen literal) for downstream reuse.
+ */
+export declare const EXAMPLE_PAYLOADS: {
+    submission: Submission;
+    scenarioResult: ScenarioResult;
+    record: Record;
+    finding: Finding;
+};
+//# sourceMappingURL=payload-types.d.ts.map

package/dist/payload-types.d.ts.map

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

package/dist/payload-types.js

@@ -0,0 +1,161 @@
+/**
+ * Hand-authored TypeScript interfaces for the contract payload shapes.
+ *
+ * FT-h (Wave, HIGH, consumability). The package exports the JSON-schema
+ * OBJECTS, the three full-set enum unions, and `validatePayload`, but no
+ * TypeScript interface for the actual payload SHAPES. A TS consumer that
+ * builds a submission, reads a persisted record, or constructs a finding got
+ * zero compile-time safety on the envelope — `validatePayload` only catches
+ * the mistake at runtime, after the bad object already flowed through typed
+ * code as `unknown`/`any`.
+ *
+ * These interfaces give consumers a typed shape to assert against at author
+ * time. They are HAND-MAINTAINED to mirror the JSON schemas — there is no
+ * codegen step — so each interface and nested type carries a `Mirrors:`
+ * pointer to its source schema, and the {@link EXAMPLE_PAYLOADS} consts at the
+ * bottom are `satisfies`-checked so `tsc --build` (which CI runs via
+ * `npm run verify` → `npm run build`) goes RED the moment an interface drifts
+ * from a representative payload. The companion vitest
+ * (`test/payload-types.test.ts`) closes the other half of the loop: it pushes
+ * those same examples through `validatePayload` and asserts the JSON schema
+ * AGREES they are valid. Interface drift in EITHER direction is caught.
+ *
+ * Reused enum unions: enum-typed fields reference the exported
+ * {@link ProductSurface} / {@link ExecutionMode} / {@link EvidenceKind} unions
+ * rather than re-typing the literals, so those fields stay sealed to the same
+ * single source the cross-contract enum seal enforces on the JSON side.
+ *
+ * SCOPE — the four payloads FT-h names: {@link Submission},
+ * {@link ScenarioResult}, {@link Record}, {@link Finding}. The other four
+ * contract schemas (pattern, recommendation, doctrine, policy) are out of
+ * scope for this slice and intentionally not modelled here; add them the same
+ * way (interface + `Mirrors:` pointer + a `satisfies` example) when a consumer
+ * needs them.
+ */
+// ---------------------------------------------------------------------------
+// Representative example payloads — the load-bearing compile-time seal.
+//
+// Each const is `satisfies`-checked against its interface. `tsc --build` (run
+// by CI via `npm run verify` → `npm run build`) compiles this `src/` file, so
+// any field that an interface declares but a representative payload cannot fill
+// — or any interface field that drifts in type from the JSON schema's intent —
+// turns the build RED here, at author time, not at a downstream consumer.
+//
+// `satisfies` (not a type annotation) keeps each const's literal type narrow
+// AND asserts assignability to the interface, so an EXTRA property that the
+// interface forbids is also a compile error. The companion vitest pushes these
+// same values through `validatePayload` so the JSON schema independently agrees
+// they are valid — drift on either side is caught.
+//
+// Values mirror the representative payloads already proven valid in
+// test/validate.test.ts, so they share that file's known-good provenance.
+// ---------------------------------------------------------------------------
+const EXAMPLE_SUBMISSION = {
+    schema_version: '1.0.0',
+    run_id: 'run-01H8Y4ZC9XJWQ5N6',
+    repo: 'dogfood-lab/testing-os',
+    ref: { commit_sha: 'a'.repeat(40), branch: 'main' },
+    source: {
+        provider: 'github',
+        workflow: 'dogfood.yml',
+        provider_run_id: '12345',
+        run_url: 'https://github.com/dogfood-lab/testing-os/actions/runs/12345',
+    },
+    timing: {
+        started_at: '2026-04-26T18:00:00Z',
+        finished_at: '2026-04-26T18:05:00Z',
+    },
+    scenario_results: [
+        {
+            scenario_id: 'cli-resolve-and-list',
+            product_surface: 'cli',
+            execution_mode: 'bot',
+            verdict: 'pass',
+            step_results: [{ step_id: 'install', status: 'pass' }],
+        },
+    ],
+    overall_verdict: 'pass',
+};
+const EXAMPLE_SCENARIO_RESULT = {
+    scenario_id: 'cli-resolve-and-list',
+    scenario_name: 'Resolve loadout and list its packages',
+    scenario_version: '1.0.0',
+    product_surface: 'cli',
+    execution_mode: 'mixed',
+    attested_by: 'human-attester-01',
+    verdict: 'partial',
+    step_results: [
+        { step_id: 'install', status: 'pass' },
+        { step_id: 'resolve', status: 'partial', notes: 'slow but completed' },
+    ],
+    evidence: [
+        { kind: 'log', url: 'https://example.com/run.log' },
+    ],
+};
+const EXAMPLE_RECORD = {
+    schema_version: '1.0.0',
+    policy_version: '1.0.0',
+    run_id: 'run-01H8Y4ZC9XJWQ5N6',
+    repo: 'dogfood-lab/testing-os',
+    ref: { commit_sha: 'b'.repeat(40) },
+    source: {
+        provider: 'github',
+        workflow: 'dogfood.yml',
+        provider_run_id: '12345',
+        run_url: 'https://github.com/dogfood-lab/testing-os/actions/runs/12345',
+    },
+    timing: {
+        started_at: '2026-04-26T18:00:00Z',
+        finished_at: '2026-04-26T18:05:00Z',
+    },
+    scenario_results: [
+        {
+            scenario_id: 'cli-resolve-and-list',
+            product_surface: 'cli',
+            execution_mode: 'bot',
+            verdict: 'pass',
+            step_results: [{ step_id: 'install', status: 'pass' }],
+        },
+    ],
+    overall_verdict: { proposed: 'pass', verified: 'pass' },
+    verification: {
+        status: 'accepted',
+        verified_at: '2026-04-26T18:06:00Z',
+        provenance_confirmed: true,
+        schema_valid: true,
+        policy_valid: true,
+    },
+};
+const EXAMPLE_FINDING = {
+    schema_version: '1.0.0',
+    finding_id: 'dfind-testing-os-schemas-payload-types',
+    title: 'Schemas package shipped no payload interfaces',
+    status: 'accepted',
+    repo: 'dogfood-lab/testing-os',
+    product_surface: 'npm-package',
+    journey_stage: 'verification',
+    issue_kind: 'schema_mismatch',
+    root_cause_kind: 'tooling_gap',
+    remediation_kind: 'schema_fix',
+    transfer_scope: 'org_wide',
+    summary: 'TS consumers of @dogfood-lab/schemas got no compile-time safety on the payload envelope; only validatePayload caught shape errors, at runtime.',
+    source_record_ids: ['testing-os-fth-001'],
+    evidence: [{ evidence_kind: 'doc', doc_ref: 'packages/schemas/src/payload-types.ts' }],
+};
+/**
+ * Representative valid payloads, one per modelled interface. Exported so the
+ * companion vitest can push them through `validatePayload` and assert the JSON
+ * schema agrees — the runtime half of the FT-h drift seal. Consumers may also
+ * import these as ready-made fixtures.
+ *
+ * The `as const` example bodies above are `satisfies`-checked against their
+ * interfaces; here we widen to the interface types so the exported shape is the
+ * interface (not a frozen literal) for downstream reuse.
+ */
+export const EXAMPLE_PAYLOADS = {
+    submission: EXAMPLE_SUBMISSION,
+    scenarioResult: EXAMPLE_SCENARIO_RESULT,
+    record: EXAMPLE_RECORD,
+    finding: EXAMPLE_FINDING,
+};
+//# sourceMappingURL=payload-types.js.map

package/dist/payload-types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/schemas",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "JSON schemas for the testing-os contract spine — record, finding, pattern, recommendation, doctrine, policy, scenario, submission.",
   "type": "module",
   "main": "dist/index.js",

package/src/json/dogfood-record-submission.schema.json

@@ -26,7 +26,8 @@
     "run_id": {
       "type": "string",
       "minLength": 1,
-      "description": "Unique dogfood run identifier. ULID recommended for sortability."
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "description": "Unique dogfood run identifier. ULID recommended for sortability. Charset is constrained because run_id becomes a filesystem path segment in the persisted record path; this mirrors the persist-time guard."
     },
 
     "repo": {
@@ -59,16 +60,16 @@
       "properties": {
         "provider": {
           "type": "string",
-          "enum": ["github"],
-          "description": "SCM provider. GitHub-only for now."
+          "enum": ["github", "gitlab"],
+          "description": "SCM provider that ran the workflow. 'github' (GitHub Actions) or 'gitlab' (GitLab CI). The verifier selects a provider-specific provenance adapter to confirm the run."
         },
         "workflow": {
           "type": "string",
-          "description": "Workflow filename that produced this submission."
+          "description": "Workflow filename that produced this submission (e.g. a GitHub Actions workflow YAML or '.gitlab-ci.yml')."
         },
         "provider_run_id": {
           "type": "string",
-          "description": "GitHub Actions run ID (provider-native)."
+          "description": "Provider-native run identifier. For 'github' this is the GitHub Actions run ID; for 'gitlab' this is the GitLab pipeline ID (or job ID when run_url points at a job)."
         },
         "attempt": {
           "type": "integer",

package/src/json/dogfood-record.schema.json

@@ -34,7 +34,8 @@
     "run_id": {
       "type": "string",
       "minLength": 1,
-      "description": "Unique dogfood run identifier. Carried from submission."
+      "pattern": "^[A-Za-z0-9_-]+$",
+      "description": "Unique dogfood run identifier. Carried from submission. Charset is constrained because run_id becomes a filesystem path segment in the persisted record path; this mirrors the persist-time guard."
     },
 
     "repo": {
@@ -67,16 +68,16 @@
       "properties": {
         "provider": {
           "type": "string",
-          "enum": ["github"],
-          "description": "SCM provider. GitHub-only for now."
+          "enum": ["github", "gitlab"],
+          "description": "SCM provider that ran the workflow. 'github' (GitHub Actions) or 'gitlab' (GitLab CI). Carried verbatim from the submission."
         },
         "workflow": {
           "type": "string",
-          "description": "Workflow filename that produced the submission."
+          "description": "Workflow filename that produced the submission (e.g. a GitHub Actions workflow YAML or '.gitlab-ci.yml')."
         },
         "provider_run_id": {
           "type": "string",
-          "description": "GitHub Actions run ID (provider-native)."
+          "description": "Provider-native run identifier. For 'github' this is the GitHub Actions run ID; for 'gitlab' this is the GitLab pipeline ID (or job ID when run_url points at a job)."
         },
         "attempt": {
           "type": "integer",
@@ -266,7 +267,7 @@
         },
         "provenance_confirmed": {
           "type": "boolean",
-          "description": "True if GitHub API confirmed the source run exists and matches claims."
+          "description": "True if the provider API (GitHub Actions or GitLab CI, selected by source.provider) confirmed the source run exists and matches the claimed repo, commit, and finished state."
         },
         "schema_valid": {
           "type": "boolean",
@@ -298,6 +299,34 @@
     "notes": {
       "type": "string",
       "description": "Freeform summary from the source."
+    },
+
+    "integrity": {
+      "type": "object",
+      "title": "Integrity Chain Entry",
+      "description": "Tamper-evident hash-chain metadata stamped by the persist layer when this record is written. Optional and backward-compatible: records persisted before the integrity chain existed have no integrity block and remain valid. The digest is computed over the record WITH this block removed (you cannot hash the digest into itself), so it is stable regardless of the integrity block's contents.",
+      "additionalProperties": false,
+      "required": ["submission_digest", "prev_digest", "seq"],
+      "properties": {
+        "submission_digest": {
+          "type": "string",
+          "title": "Submission Digest",
+          "description": "Lowercase sha256 hex (64 chars) of the canonicalized record with the integrity block removed. Recomputed by the chain verifier to detect tampering.",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "prev_digest": {
+          "type": "string",
+          "title": "Previous Digest",
+          "description": "The submission_digest of the previous record in the append-only chain, or 64 zeros (the genesis digest) for the first entry. Links this record to its predecessor.",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "seq": {
+          "type": "integer",
+          "title": "Chain Sequence Number",
+          "description": "Monotonic position of this record in the append-only chain, starting at 0 for the genesis entry.",
+          "minimum": 0
+        }
+      }
     }
   }
 }