repo-contract 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.3.2](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.3.1...repo-contract-v0.3.2) (2026-09-04)
+
+
+### Features
+
+* validate and transform check output with a Standard Schema ([d53cb17](https://github.com/MaverickCER/repo-contract/commit/d53cb17a9e3a3f939cd403226ab5256be0de79ac))
+* validate and transform check output with a Standard Schema ([fbb7925](https://github.com/MaverickCER/repo-contract/commit/fbb79259f4a6cede1da64a0abd7e1f1541e1d505))
+
+
+### Bug Fixes
+
+* address CodeRabbit findings and close mutation-testing gaps in Standard Schema support ([53baf87](https://github.com/MaverickCER/repo-contract/commit/53baf877d367fd17dbe1ec2f312ab9ed790e6ae6))
+* **api-contract:** don't classify a required property on a brand-new container as breaking ([27ad5d5](https://github.com/MaverickCER/repo-contract/commit/27ad5d5c57811d90393b00f48ae8a8bbd413407b))
+* **test:** harden isRuntimeAvailable against spawnSync throwing under load ([60c76b6](https://github.com/MaverickCER/repo-contract/commit/60c76b642dfd6187888f02d31639e68468e77b17))
+
+## [0.3.1](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.3.0...repo-contract-v0.3.1) (2026-09-03)
+
+
+### Bug Fixes
+
+* correct the release runbook that shipped types-less tarballs ([f56ea34](https://github.com/MaverickCER/repo-contract/commit/f56ea342606cfc92a09943ea5eb787936e7b7ba9))
+* published tarball missing types; simplify CI matrix ([7ec8fd9](https://github.com/MaverickCER/repo-contract/commit/7ec8fd946bd584098255c5d2ab3f07b98b55ba1f))
+
 ## [0.3.0](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.2.1...repo-contract-v0.3.0) (2026-09-03)
 
 

package/README.md

@@ -529,6 +529,50 @@ Provides trimmed text passthrough and always succeeds.
 
 The sibling mistake -- reading `result.output.value` when the format _was_ requested but the parse itself failed (`result.output.success === false`, so `result.output` has `error`, not `value`) -- similarly rejects with [`PolicyReadFailedParseValueError`](docs/api-report/repo-contract.api.md) instead of a generic `PolicyThrewError`. Check `result.output.success` before reading `.value` to handle a parse failure explicitly rather than hitting either error.
 
+#### Validating parsed output with a schema
+
+`output.schema` accepts any object implementing [Standard Schema](https://standardschema.dev) --
+Zod, Valibot, ArkType, and others already do. repo-contract does not install or depend on any of
+them; it hand-vendors the (pure-type, zero-runtime-code) `StandardSchemaV1` interface itself (see
+[ADR 0012](specs/decisions/0012-hand-vendored-standard-schema-support-for-optional-output-validation.md)). Bring whichever schema
+library your own repo already uses -- `npm install zod` (or `valibot`, or `arktype`) is your call,
+not repo-contract's. The smallest possible example, using a hand-written object satisfying the
+interface directly rather than any particular library:
+
+```ts
+output: {
+  format: "json",
+  schema: {
+    "~standard": {
+      version: 1,
+      vendor: "example",
+      validate: (value) => {
+        const errorCount =
+          value !== null && typeof value === "object"
+            ? (value as { errorCount?: unknown }).errorCount
+            : undefined
+        return typeof errorCount === "number"
+          ? { value: { errorCount } }
+          : { issues: [{ message: "errorCount must be a number", path: ["errorCount"] }] }
+      },
+    },
+  },
+}
+```
+
+A successful validation _replaces_ `result.output.value` with the schema's own (possibly
+transformed or coerced) output -- one of the most useful aspects of Standard Schema, not just a
+boolean check: a schema can normalize, default, or reshape its input, and the policy receives that
+result, not the raw parsed value. A failing validation becomes a normal `ParsedOutputFailure` --
+indistinguishable in shape from a malformed-JSON parse failure, joining every issue's own path and
+message into `result.output.error` (e.g. `Schema validation failed: errorCount: errorCount must be
+a number`). `result.output.value`'s declared TypeScript type stays `unknown` regardless -- narrow
+or cast it yourself, same as without a schema.
+
+`schema["~standard"].validate()` itself throwing or rejecting (rather than returning a `Result`) is
+different from a failed validation -- it means the schema is broken, not the check's output, so it
+rejects `runRepoContract()` with `StandardSchemaValidateThrewError` instead of becoming evidence.
+
 ### `dependsOn`
 
 By default, every check runs independently and in parallel.
@@ -1001,6 +1045,8 @@ A **policy throwing** is different. A synchronous throw or rejected promise from
 
 Two specific mistakes get their own error instead of a plain `PolicyThrewError`, both naming the check: reading `result.output.value` (or `.success`/`.error`/`.format`) on a check that never configured `output` throws `PolicyReadUnrequestedOutputError`, telling you to add `output: { format: "json" }` (or `"yaml"`/`"text"`); reading `result.output.value` on a check whose requested parse actually failed throws `PolicyReadFailedParseValueError`, telling you to check `result.output.success` first -- see [`output`](#output).
 
+A **schema throwing** (`output.schema["~standard"].validate()` itself throwing or rejecting, rather than returning a `Result` -- see [Validating parsed output with a schema](#validating-parsed-output-with-a-schema)) is treated the same as a throwing policy: `StandardSchemaValidateThrewError`, or an `AggregateError` when multiple checks' schemas throw in the same run. A schema _returning_ failure `issues`, by contrast, is not an error at all -- it becomes an ordinary parser-error-shaped `result.output`, exactly like the **Parser errors** case above.
+
 ## Status and versioning
 
 repo-contract is pre-1.0.

package/dist/.dts/config/define-repo-contract.d.ts

@@ -0,0 +1,36 @@
+import type { CheckSchema, RepoContractConfig, ValidatedCheckSchema } from "../types.js";
+/**
+ * Identity function whose only job is type inference: authoring a config
+ * through `defineRepoContract` lets each check's `output` (present or
+ * absent, and which format) flow into that same check's `policy` parameter
+ * type, without the consumer writing any type annotations themselves. It
+ * also statically validates every check's `dependsOn` against its sibling
+ * check ids (see `ValidatedCheckSchema`) -- a typo'd or self-referencing id
+ * fails to compile here rather than only failing at runtime. Performs no
+ * other validation and no cloning -- `runRepoContract` validates whatever
+ * config it is ultimately given, whether or not it passed through this
+ * function first.
+ *
+ * `const TChecks` (TypeScript 5.0's `const` type parameter modifier) keeps
+ * each check's own configuration -- notably whether `output` is present at
+ * all -- from being widened during inference; without it, TypeScript's
+ * inference for a `Record` of heterogeneous generic entries does not
+ * reliably preserve that per-check shape once a callback property
+ * (`policy`) is also present. See `InferParsedValue` in types.ts for the
+ * related limitation this does not fully solve.
+ *
+ * `TChecks` is inferred from the plain, unwrapped `RepoContractConfig<TChecks>`
+ * position -- the `ValidatedCheckSchema<TChecks>` constraint on `checks` is
+ * intersected in afterward, computed from that already-inferred `TChecks`,
+ * rather than substituted in its place. Inferring `TChecks` directly from a
+ * mapped/conditional type over itself (as `ValidatedCheckSchema` is) loses
+ * the contextual typing every check's `policy` callback otherwise gets --
+ * another real, confirmed TypeScript inference limitation, distinct from
+ * the `output`-to-`policy` one above.
+ * @param config - the config to type-check and return unchanged.
+ * @returns the same `config` object, untouched and uncloned.
+ */
+export declare function defineRepoContract<const TChecks extends CheckSchema>(config: RepoContractConfig<TChecks> & {
+    readonly checks: ValidatedCheckSchema<TChecks>;
+}): RepoContractConfig<TChecks>;
+//# sourceMappingURL=define-repo-contract.d.ts.map

package/dist/.dts/config/define-repo-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-repo-contract.d.ts","sourceRoot":"","sources":["../../../src/config/define-repo-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,OAAO,SAAS,WAAW,EAClE,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAA;CAAE,GACvF,kBAAkB,CAAC,OAAO,CAAC,CAE7B"}

package/dist/.dts/config/tokenize-command.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Splits a `run` string into argv (executable + arguments) without invoking
+ * a shell -- no shell operator is ever executed, no glob is ever expanded by
+ * this package, no environment variable is ever substituted. The result is
+ * deterministic: the same input string always produces the same argv array.
+ *
+ * Quoting: `'...'` and `"..."` group whitespace into a single argument and
+ * are themselves stripped from the resulting token. `\` escapes the next
+ * character (and is itself stripped) when unquoted or inside a double-quoted
+ * span; inside single quotes it is a literal character, exactly as in every
+ * POSIX shell -- so a Windows path in single quotes survives intact.
+ * Unquoted whitespace (space, tab) separates tokens.
+ *
+ * Rejected outright (throws `InvalidCheckConfigError`, checkId identifies
+ * which check's `run` was invalid): any *unquoted* occurrence of a true
+ * shell/multi-command operator -- `;`, `&`, `|`, a backtick, `$(`, `<`, `>`,
+ * or a literal newline. A string containing one of these almost always
+ * reflects a mistaken assumption that shell interpretation is happening;
+ * the fix is either `run: [...]` (array form, bypasses tokenization
+ * entirely) or explicit `shell: true`.
+ *
+ * Deliberately NOT rejected: glob characters (`*`, `?`, `~`, `[`, `]`, `{`,
+ * `}`) and a bare `$`. These are common, legitimate literal argv content --
+ * many CLI tools (eslint, prettier, tsc) accept and internally expand glob
+ * patterns themselves, e.g. `eslint "src/**\/*.ts"` -- and since no shell is
+ * ever invoked here, they carry zero shell-injection risk regardless of
+ * where they appear in the string.
+ * @param run - the command string to tokenize.
+ * @param checkId - identifies which check's `run` was invalid, used in the thrown error message.
+ * @returns the tokenized argv (executable followed by its arguments).
+ */
+export declare function tokenizeRunString(run: string, checkId: string): readonly string[];
+//# sourceMappingURL=tokenize-command.d.ts.map

package/dist/.dts/config/tokenize-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenize-command.d.ts","sourceRoot":"","sources":["../../../src/config/tokenize-command.ts"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAwHjF"}

package/dist/.dts/config/validate-config.d.ts

@@ -0,0 +1,32 @@
+import type { RepoContractConfig } from "../types.js";
+/**
+ * Validates a `RepoContractConfig` structurally and throws before any
+ * process spawns. A config with zero checks is valid (an empty `checks`
+ * object vacuously satisfies "every check passed"); everything else here is
+ * a genuine structural problem. Runtime checks are deliberately defensive
+ * about field types rather than trusting the compile-time type, since a
+ * config can arrive from plain JavaScript or a widened/cast value.
+ * @param config - the config to validate; throws if structurally invalid.
+ */
+export declare function validateRepoContractConfig(config: RepoContractConfig): void;
+/**
+ * Whole-graph properties that can't be checked per-check in isolation --
+ * run once, after every check's own `dependsOn` shape has already been
+ * validated by `validateDependsOn` above, so this can walk every
+ * `dependsOn` array without re-checking its shape.
+ *
+ * Declaration order in the `checks` object doubles as the required topological order (see
+ * `CheckDefinition.dependsOn`'s own doc comment): every `dependsOn` id must name a check declared
+ * earlier* than the check declaring it. This single backward-reference check subsumes what used
+ * to be two separate passes (an unknown-id check, then a DFS cycle detector) -- a cycle is no
+ * longer expressible at all once every edge is required to point backward, so there is nothing
+ * left for a separate cycle detector to catch. `isolated` needs no validation-time edge computation
+ * here: its own implied positional edges (see `run-checks.ts`'s `dependencyIndexesFor`) always
+ * point backward (to earlier-declared checks) or are pointed at by later-declared checks, by
+ * construction, so they can never introduce a cycle either.
+ * @param checks - the full check map, keyed by check id, in declaration order.
+ */
+export declare function validateDependencyGraph(checks: Record<string, {
+    dependsOn?: readonly string[];
+}>): void;
+//# sourceMappingURL=validate-config.d.ts.map

package/dist/.dts/config/validate-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-config.d.ts","sourceRoot":"","sources":["../../../src/config/validate-config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAgB,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAKnE;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAuE3E;AA2VD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,GACxD,IAAI,CAoBN"}

package/dist/.dts/errors.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Error hierarchy for repo-contract. Every concrete error carries a stable
+ * `code` string for programmatic handling, and never embeds raw
+ * stdout/stderr/env values in its message -- only check ids and field names
+ * (see SECURITY.md).
+ *
+ * Three distinct failure classes are kept deliberately separate (see
+ * specs/architecture.md):
+ *   - Structural config problems throw synchronously, before any process
+ *     spawns (`InvalidRepoContractConfigError`, `InvalidCheckConfigError`).
+ *   - Anything only discoverable by attempting execution becomes evidence,
+ *     never a throw (a bad `cwd`, a missing binary -- recorded as
+ *     `status: "spawn_error"` on that check's `CheckEvidence`).
+ *   - A policy function throwing or rejecting is a bug in consumer code, not
+ *     a check failing its contract -- it propagates as a rejected
+ *     `runRepoContract()` promise (`PolicyThrewError`), never silently
+ *     turned into a failed verdict entry.
+ */
+export declare abstract class RepoContractError extends Error {
+    /** Stable, machine-readable identifier for this error's specific failure mode. */
+    abstract readonly code: string;
+}
+/** The top-level `RepoContractConfig` itself is structurally invalid -- e.g. `checks` is not an object, or `concurrency` is not a positive integer. (A `checks` object with zero entries is deliberately valid: the run produces an empty, passing `Verdict`.) Thrown synchronously by `runRepoContract`, before anything spawns -- not by `defineRepoContract`, which performs no runtime validation of its own (see its own doc comment). */
+export declare class InvalidRepoContractConfigError extends RepoContractError {
+    /** Always `"REPO_CONTRACT_INVALID_CONFIG"`. */
+    readonly code = "REPO_CONTRACT_INVALID_CONFIG";
+    constructor(reason: string);
+}
+/** One check's `CheckDefinition` is structurally invalid -- e.g. an empty `run`, a `run` string containing an unquoted shell operator without `shell: true`, or a missing `policy`. Thrown synchronously, before that check (or any other) spawns. */
+export declare class InvalidCheckConfigError extends RepoContractError {
+    /** Always `"REPO_CONTRACT_INVALID_CHECK_CONFIG"`. */
+    readonly code = "REPO_CONTRACT_INVALID_CHECK_CONFIG";
+    /** The id of the check whose configuration was invalid. */
+    readonly checkId: string;
+    constructor(checkId: string, reason: string);
+}
+/**
+ * `RunRepoContractOptions.checks` (a partial-run request) names a check id that doesn't exist in
+ * the configured `checks`. Unlike a `dependsOn` id (already validated to exist by
+ * `validateRepoContractConfig` before any run starts), `options.checks` is only ever checked once
+ * `runChecks` actually resolves it -- there is no earlier structural-validation pass for it.
+ */
+export declare class UnknownCheckIdError extends RepoContractError {
+    /** Always `"REPO_CONTRACT_UNKNOWN_CHECK_ID"`. */
+    readonly code = "REPO_CONTRACT_UNKNOWN_CHECK_ID";
+    /** The unrecognized check id named in `options.checks`. */
+    readonly checkId: string;
+    constructor(checkId: string);
+}
+/**
+ * A check's `dependsOn` names a check declared *later* in the same `checks` object.
+ * `dependsOn` may only reference a check declared earlier -- see `CheckDefinition.dependsOn`'s own
+ * doc comment. Declaration order doubles as the required topological order, so this is the only
+ * way an invalid dependency graph can arise; a real cycle is structurally impossible once every
+ * edge points backward. Thrown synchronously, before any check spawns.
+ */
+export declare class DependencyDeclaredLaterError extends RepoContractError {
+    /** Always `"REPO_CONTRACT_DEPENDENCY_DECLARED_LATER"`. */
+    readonly code = "REPO_CONTRACT_DEPENDENCY_DECLARED_LATER";
+    /** The id of the check whose `dependsOn` names a later-declared check. */
+    readonly checkId: string;
+    /** The later-declared check id named in `checkId`'s `dependsOn`. */
+    readonly dependencyId: string;
+    constructor(checkId: string, dependencyId: string);
+}
+/** A check requested `output: { format: "yaml" }` but the optional `yaml` peer dependency is not installed. Thrown when that check's output is parsed, not at config-validation time (parsing only happens after the process has already run). */
+export declare class ParserDependencyMissingError extends RepoContractError {
+    /** Always `"REPO_CONTRACT_PARSER_DEPENDENCY_MISSING"`. */
+    readonly code = "REPO_CONTRACT_PARSER_DEPENDENCY_MISSING";
+    /** The id of the check whose output could not be parsed. */
+    readonly checkId: string;
+    /** The output format that was requested but whose optional peer dependency is missing. */
+    readonly format: OutputFormatForError;
+    constructor(checkId: string, format: OutputFormatForError, cause: unknown);
+}
+type OutputFormatForError = "yaml";
+/**
+ * A check's `output.schema["~standard"].validate()` threw synchronously, or returned a `Promise`
+ * that rejected, instead of returning a `Result`. This is a bug in the consumer-supplied schema
+ * object, not malformed check output -- the same distinction `PolicyThrewError` below draws for a
+ * throwing policy: a schema *returning* failure `issues` becomes an ordinary
+ * `ParsedOutputFailure` (reported as data, exactly like a malformed-JSON/YAML parse failure), but
+ * a schema *throwing* means the validator itself is broken, so it propagates as a rejected
+ * `runRepoContract()` promise instead. The original thrown/rejected value is preserved verbatim
+ * via the native `Error` `cause` chain.
+ */
+export declare class StandardSchemaValidateThrewError extends RepoContractError {
+    /** Always `"REPO_CONTRACT_STANDARD_SCHEMA_VALIDATE_THREW"`. */
+    readonly code = "REPO_CONTRACT_STANDARD_SCHEMA_VALIDATE_THREW";
+    /** The id of the check whose `output.schema` threw during validation. */
+    readonly checkId: string;
+    constructor(checkId: string, cause: unknown);
+}
+/**
+ * A check's `policy` function threw synchronously, or returned a `Promise`
+ * that later rejected. Both failure modes are wrapped identically. The
+ * original thrown/rejected value is preserved verbatim via the native
+ * `Error` `cause` chain -- never stringified, summarized, or discarded --
+ * so a consumer catching this can still inspect exactly what their own
+ * policy code did wrong.
+ *
+ * A policy throwing never stops any other check's policy from running --
+ * every configured check's policy is invoked exactly once regardless of
+ * what any other policy does. If more than one policy fails this way in the
+ * same run, `runRepoContract()` rejects with a native `AggregateError` whose
+ * `errors` array holds one error per failing check -- `PolicyThrewError`,
+ * or one of its two narrower siblings below (`PolicyReadUnrequestedOutputError`,
+ * `PolicyReadFailedParseValueError`) when the failure matches one of their
+ * more specific shapes -- rather than surfacing only the first one found.
+ */
+export declare class PolicyThrewError extends RepoContractError {
+    /** Always `"REPO_CONTRACT_POLICY_THREW"`. */
+    readonly code = "REPO_CONTRACT_POLICY_THREW";
+    /** The id of the check whose policy threw or rejected. */
+    readonly checkId: string;
+    constructor(checkId: string, cause: unknown);
+}
+/**
+ * A narrower `runPolicies` throws instead of `PolicyThrewError` when the
+ * thrown `TypeError`'s own message shows it came from reading a
+ * `result.output` property (`.success`, `.value`, `.error`, or `.format`),
+ * and this check's `CheckEvidence.output` really is `undefined` -- which
+ * happens only when its config never requested `output: { format: ... }` in
+ * the first place (see `CheckEvidence.output` in types.ts). Detected from
+ * the `TypeError`'s exact V8-produced message ("Cannot read properties of
+ * undefined (reading '...')") cross-checked against that `undefined` fact,
+ * so it is thrown only for a policy that plausibly hit this exact mistake --
+ * any other `TypeError`, or a check that did request a format, still becomes
+ * a plain `PolicyThrewError`. This is best-effort inference from the
+ * `TypeError`'s message text, not a verified trace back to `result.output`
+ * itself -- V8's message carries only the property name, so an unrelated
+ * bug that happens to read the same property name off some other
+ * `undefined` value can still be misclassified this way (see
+ * `unrequestedOutputProperty` in run-policies.ts). `cause` still holds the
+ * original `TypeError` verbatim, exactly as `PolicyThrewError` guarantees
+ * for every other policy failure, so the true cause remains recoverable
+ * either way.
+ */
+export declare class PolicyReadUnrequestedOutputError extends RepoContractError {
+    /** Always `"REPO_CONTRACT_POLICY_READ_UNREQUESTED_OUTPUT"`. */
+    readonly code = "REPO_CONTRACT_POLICY_READ_UNREQUESTED_OUTPUT";
+    /** The id of the check whose policy read `result.output` without requesting a format. */
+    readonly checkId: string;
+    constructor(checkId: string, property: string, cause: unknown);
+}
+/**
+ * `PolicyThrewError`'s other special case, alongside
+ * `PolicyReadUnrequestedOutputError`: this check *did* request
+ * `output: { format: ... }`, but that parse itself failed
+ * (`result.output.success === false` -- see `ParsedOutputFailure` in types.ts, which
+ * has no `value` field, only `error`), and the policy read a property off
+ * `result.output.value` anyway without checking `.success` first. Detected the same
+ * way `runPolicies` detects the sibling case -- a thrown `TypeError` whose own
+ * message shows a property read off `undefined` -- cross-checked against this
+ * check's own evidence having `output.success === false`, so a genuinely unrelated
+ * `TypeError`, or a check whose parse actually succeeded, still becomes a plain
+ * `PolicyThrewError`. Unlike `PolicyReadUnrequestedOutputError`, the read property
+ * isn't restricted to a known list here -- `result.output.value`'s shape is whatever
+ * the external tool printed, entirely unknown to repo-contract -- so this match is
+ * necessarily a little broader. `cause` still holds the original `TypeError`
+ * verbatim; the message never repeats `result.output.error`'s own text, which may
+ * contain raw stdout content (see SECURITY.md).
+ */
+export declare class PolicyReadFailedParseValueError extends RepoContractError {
+    /** Always `"REPO_CONTRACT_POLICY_READ_FAILED_PARSE_VALUE"`. */
+    readonly code = "REPO_CONTRACT_POLICY_READ_FAILED_PARSE_VALUE";
+    /** The id of the check whose policy read `result.output.value` after a failed parse. */
+    readonly checkId: string;
+    constructor(checkId: string, property: string, cause: unknown);
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/.dts/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,iBAAkB,SAAQ,KAAK;IACnD,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAC/B;AAED,+aAA+a;AAC/a,qBAAa,8BAA+B,SAAQ,iBAAiB;IACnE,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,kCAAiC;gBAElC,MAAM,EAAE,MAAM;CAI3B;AAED,sPAAsP;AACtP,qBAAa,uBAAwB,SAAQ,iBAAiB;IAC5D,qDAAqD;IACrD,QAAQ,CAAC,IAAI,wCAAuC;IACpD,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,iBAAiB;IACxD,iDAAiD;IACjD,QAAQ,CAAC,IAAI,oCAAmC;IAChD,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM;CAO5B;AAED;;;;;;GAMG;AACH,qBAAa,4BAA6B,SAAQ,iBAAiB;IACjE,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,6CAA4C;IACzD,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;gBAEjB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAUlD;AAED,kPAAkP;AAClP,qBAAa,4BAA6B,SAAQ,iBAAiB;IACjE,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,6CAA4C;IACzD,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;gBAEzB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,OAAO;CAU1E;AAMD,KAAK,oBAAoB,GAAG,MAAM,CAAA;AAElC;;;;;;;;;GASG;AACH,qBAAa,gCAAiC,SAAQ,iBAAiB;IACrE,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,kDAAiD;IAC9D,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAQ5C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAiB,SAAQ,iBAAiB;IACrD,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,gCAA+B;IAC5C,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAK5C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gCAAiC,SAAQ,iBAAiB;IACrE,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,kDAAiD;IAC9D,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAY9D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,+BAAgC,SAAQ,iBAAiB;IACpE,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,kDAAiD;IAC9D,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAU9D"}

package/dist/.dts/evidence/build-evidence.d.ts

@@ -0,0 +1,26 @@
+import type { CheckExecutionEntry } from "../execution/run-checks.js";
+import type { CheckDefinition, CheckEvidence, Evidence } from "../types.js";
+/** One check's id, its original definition, and its final evidence (parsed output attached, if requested) -- the parsed-output counterpart to `CheckExecutionEntry`, consumed directly by the policy phase so it never needs to look a check up by id either. */
+export type ParsedCheckEntry = readonly [string, CheckDefinition, CheckEvidence];
+interface BuiltEvidence {
+    readonly evidence: Evidence;
+    readonly entries: readonly ParsedCheckEntry[];
+}
+/**
+ * Attaches parsed output (if requested) to every check's raw execution
+ * evidence and assembles the versioned, immutable `Evidence` object for the
+ * run as a whole. Also returns the same information as a flat entries array
+ * (see `ParsedCheckEntry`) for the policy phase to consume directly -- by
+ * the time this function returns, every check's evidence -- including every
+ * sibling check's -- is fully assembled; nothing here is generated lazily
+ * or streamed, which is what makes it safe for a policy to read the full
+ * `evidence` object, not just its own check's `result` (see
+ * specs/architecture.md).
+ * @param results - each check's id, definition, and raw execution evidence from the run phase
+ * @param startedAt - when the overall run began, recorded on the assembled `Evidence`
+ * @param completedAt - when the overall run finished, used with `startedAt` to compute the assembled `Evidence`'s `durationMs`
+ * @returns the assembled `Evidence` for the whole run, plus the same checks as a flat `ParsedCheckEntry` array for the policy phase
+ */
+export declare function buildEvidence(results: readonly CheckExecutionEntry[], startedAt: Date, completedAt: Date): Promise<BuiltEvidence>;
+export {};
+//# sourceMappingURL=build-evidence.d.ts.map

package/dist/.dts/evidence/build-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-evidence.d.ts","sourceRoot":"","sources":["../../../src/evidence/build-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAGrE,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3E,iQAAiQ;AACjQ,MAAM,MAAM,gBAAgB,GAAG,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,aAAa,CAAC,CAAA;AAIhF,UAAU,aAAa;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC9C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,SAAS,EAAE,IAAI,EACf,WAAW,EAAE,IAAI,GAChB,OAAO,CAAC,aAAa,CAAC,CAgExB"}

package/dist/.dts/execution/abort-signals.d.ts

@@ -0,0 +1,29 @@
+/** The composed signal, and a `dispose` to release any resources this composition holds once it's no longer needed. */
+interface ComposedSignal {
+    readonly signal: AbortSignal;
+    readonly dispose: () => void;
+}
+/**
+ * Combines multiple signals into one that aborts as soon as any input does.
+ * Prefers the native `AbortSignal.any()` where available; falls back to a
+ * manual composition for engines without it. `AbortSignal.any` landed in
+ * Node 20.3.0 -- genuinely newer than this package's `engines.node >=20.0.0`
+ * floor, so the fallback is live code for a real gap (a 20.0-20.2 patch
+ * release), not dead code kept out of caution.
+ *
+ * The native path's `dispose` is a no-op -- `AbortSignal.any` manages its own
+ * source-signal listeners internally and doesn't leak them. The manual
+ * fallback's `dispose` removes the "abort" listeners it added to each input
+ * `signal`; without calling it, a long-lived input (like a whole run's shared
+ * `AbortSignal`, composed fresh for every check the run spawns) would
+ * accumulate one permanent, never-removed listener per composed signal for
+ * the rest of its own lifetime, regardless of whether that particular
+ * composition ever actually needed to abort. Callers should call `dispose()`
+ * once the composed signal is no longer needed, whether or not it ever
+ * aborted.
+ * @param signals - the signals to combine; the composed signal aborts as soon as any one of them does
+ * @returns the composed signal (aborting with that input's abort reason as soon as any signal in `signals` aborts), and a `dispose` to release this composition's own resources
+ */
+export declare function composeSignals(signals: readonly AbortSignal[]): ComposedSignal;
+export {};
+//# sourceMappingURL=abort-signals.d.ts.map

package/dist/.dts/execution/abort-signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-signals.d.ts","sourceRoot":"","sources":["../../../src/execution/abort-signals.ts"],"names":[],"mappings":"AAAA,uHAAuH;AACvH,UAAU,cAAc;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,cAAc,CA4B9E"}

package/dist/.dts/execution/concurrency-pool.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Runs `worker` over `items` with at most `concurrency` invocations in
+ * flight at once, preserving each result at its original index regardless
+ * of completion order. Has no knowledge of aborting, killing, or check
+ * evidence -- a pure, reusable bounded-parallelism primitive; abort-
+ * awareness lives entirely in the caller's `worker` function (see
+ * spawn-check.ts).
+ * @param items - the items to process, each passed to `worker` along with its index
+ * @param concurrency - the maximum number of `worker` calls allowed in flight at once
+ * @param worker - the async function run per item; its resolved value becomes that item's result
+ * @returns the results, one per item, in the same order as `items` regardless of completion order
+ */
+export declare function runWithConcurrency<T, R>(items: readonly T[], concurrency: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=concurrency-pool.d.ts.map

package/dist/.dts/execution/concurrency-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency-pool.d.ts","sourceRoot":"","sources":["../../../src/execution/concurrency-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,EAAE,CAAC,CA+Cd"}

package/dist/.dts/execution/dependency-scheduler.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Runs `worker` over `items` with at most `concurrency` invocations in
+ * flight at once, like `concurrency-pool.ts`'s `runWithConcurrency`, but
+ * additionally respecting a dependency graph: an item whose
+ * `dependencyIndexes` are non-empty is not started until every one of
+ * those indexes has settled. Has no knowledge of checks, evidence, or
+ * abort semantics -- a pure, reusable bounded-parallelism-plus-ordering
+ * primitive, kept in its own file rather than folded into
+ * `concurrency-pool.ts` so that file's simpler, more heavily-used flat
+ * primitive stays untouched.
+ *
+ * A reactive, event-driven scheduler (conceptually Kahn's algorithm run
+ * incrementally): a completing item immediately re-evaluates and unblocks
+ * its own dependents, with no artificial "wave" boundary -- a wave/layer
+ * design was considered and rejected because it would stall a dependent
+ * whose single dependency finished early behind an unrelated slow item
+ * sharing its layer, a real regression for a diamond or fan-out shape.
+ *
+ * The caller is responsible for ensuring `dependencyIndexes` describes an
+ * acyclic graph (see `validate-config.ts`'s cycle detection) -- this
+ * function's own stall guard below exists only as defense in depth against
+ * that invariant being violated, not as the primary means of catching it.
+ * @param items - the items to process, each passed to `worker` and `dependencyIndexes` along with its index
+ * @param concurrency - the maximum number of `worker` calls allowed in flight at once
+ * @param dependencyIndexes - given an item and its index, returns the indexes into `items` that must settle first
+ * @param worker - the async function run per item once its dependencies have settled; its resolved value becomes that item's result
+ * @returns the results, one per item, in the same order as `items` regardless of completion order
+ */
+export declare function runWithConcurrencyGraph<T, R>(items: readonly T[], concurrency: number, dependencyIndexes: (item: T, index: number) => readonly number[], worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=dependency-scheduler.d.ts.map

package/dist/.dts/execution/dependency-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-scheduler.d.ts","sourceRoot":"","sources":["../../../src/execution/dependency-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAChD,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,iBAAiB,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,EAChE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,EAAE,CAAC,CAsLd"}

package/dist/.dts/execution/process-tree.d.ts

@@ -0,0 +1,59 @@
+import type { SyncSpawner } from "../types.js";
+/**
+ * Whether a check's process should be spawned with `detached: true`. On
+ * POSIX this makes the spawned process the leader of a new process group
+ * (sharing its own pid as the group id), which is what lets `killTree`
+ * target the whole group rather than just the immediate child. On Windows,
+ * process groups work differently and `detached: true` would instead launch
+ * the process in its own console window -- not what's wanted here, since
+ * Windows cleanup goes through `taskkill /t` instead (see `killTree`).
+ * @returns true on POSIX (spawn as its own process group leader, killable via `killTree`); false on Windows
+ */
+export declare function shouldSpawnDetached(): boolean;
+/**
+ * Best-effort termination of an entire process tree rooted at `pid`, not
+ * just the immediate process -- necessary because a check's command is
+ * often itself a wrapper (`npm run test` spawns `npm`, which spawns the
+ * actual test runner), and killing only the wrapper would orphan its
+ * descendants. `spawn`'s own `timeout`/`signal` options only ever affect the
+ * directly spawned process, never its descendants, which is why this exists
+ * as a separate utility rather than relying on those.
+ *
+ * On POSIX, sends `signal` to the whole process group via the negative-pid
+ * convention (requires the process to have been spawned with
+ * `detached: true`, see `shouldSpawnDetached`) -- no process spawning
+ * required, a single syscall via `process.kill`. On Windows, process groups
+ * don't work the same way, so this shells out to `taskkill /pid <pid> /t
+ * /f` -- the same technique the `tree-kill` package uses internally -- which
+ * walks the system process table for descendants of `pid` regardless of how
+ * it was spawned; that requires a synchronous spawn, which -- like every
+ * other process-spawning capability in this package -- is a trusted
+ * capability the caller supplies (`killProcessTree`, threaded from
+ * `RepoContractConfig.killProcessTree`), never imported internally (see
+ * specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md).
+ * When `killProcessTree` is omitted on Windows, this function is a
+ * documented no-op -- the caller (`spawn-check.ts`) falls back to
+ * terminating just the tracked child process handle directly, which needs
+ * no spawn at all.
+ *
+ * Swallows the expected best-effort-cleanup failures, but not every failure: a
+ * process that has already exited (POSIX `ESRCH`, or `taskkill`'s "not found"
+ * case) is a no-op, and a POSIX `EPERM` permission error is swallowed the same
+ * way -- by the time cleanup runs the process may well have exited on its own,
+ * and a failed cleanup should not crash the run. Any *other* failure is
+ * rethrown: an unexpected POSIX errno, or (on Windows) a JS-level spawn failure
+ * of `taskkill` itself (`result.error`, e.g. the tool missing from PATH), which
+ * would otherwise silently leave an orphaned process tree behind.
+ *
+ * On Windows this always runs `taskkill` with `/f` regardless of which `signal` was requested --
+ * not a partial implementation of POSIX's cooperative-SIGTERM-then-SIGKILL escalation, but a
+ * reflection of a real platform difference: Windows has no signal-delivery mechanism for an
+ * arbitrary process tree by pid at all (this is also why Node's own `ChildProcess.kill()` treats
+ * every signal identically on Windows, per Node's own child_process documentation), so there is no
+ * more-cooperative alternative to fall back to here the way there is on POSIX.
+ * @param pid - the pid of the tree's root process (the process group id on POSIX, since it was spawned detached)
+ * @param signal - the POSIX signal to send (on Windows, ignored -- see doc comment above)
+ * @param killProcessTree - the consumer-supplied synchronous spawner used only on Windows; a no-op there when omitted (see doc comment above)
+ */
+export declare function killTree(pid: number, signal: NodeJS.Signals, killProcessTree?: SyncSpawner): void;
+//# sourceMappingURL=process-tree.d.ts.map

package/dist/.dts/execution/process-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-tree.d.ts","sourceRoot":"","sources":["../../../src/execution/process-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,WAAW,GAAG,IAAI,CAoDjG"}

package/dist/.dts/execution/run-checks.d.ts

@@ -0,0 +1,31 @@
+import type { CheckDefinition, CheckEvidence, CheckSchema, RunRepoContractOptions } from "../types.js";
+import type { ExecutionCapability } from "./spawn-check.js";
+/**
+ * One check's id, its original definition, and its raw execution evidence,
+ * threaded together as a triple rather than three separately-keyed maps --
+ * every later stage (parsing, policy evaluation) consumes this directly
+ * instead of re-looking a check up by id, which under `noUncheckedIndexedAccess`
+ * would otherwise force handling an "undefined" case that can't actually
+ * happen (every checkId here comes from the same `Object.entries(checks)`
+ * that produced it).
+ */
+export type CheckExecutionEntry = readonly [string, CheckDefinition, CheckEvidence];
+export declare const SELF_TERMINATE_DELAY_MS: number;
+/**
+ * Executes every resolved check with at most `concurrency` running at once,
+ * returning each check's raw evidence keyed by check id. For a full run
+ * (`options.checks` omitted), every configured check id is resolved and
+ * therefore appears in the result exactly once, regardless of whether it
+ * ever actually spawned (see spawnCheck's documentation for the pre-aborted
+ * case). When `options.checks` restricts execution to a subset, only the
+ * requested ids and their transitive `dependsOn` are resolved (see
+ * `resolveCheckDependencies` above) -- every other configured check id is
+ * simply absent from the result, not present with some placeholder value.
+ * @param checks - the full set of configured checks, keyed by id
+ * @param concurrency - the maximum number of checks to run in parallel at once
+ * @param execution - the run's trusted execution capabilities (`spawn`, `env`, resolved global `shell` default), forwarded to every `spawnCheck` call
+ * @param options - run options; `options.checks` restricts execution to those ids (plus their dependencies), `options.signal` cancels the whole run
+ * @returns each executed check's id, definition, and raw evidence, one entry per resolved check regardless of whether it actually spawned
+ */
+export declare function runChecks(checks: CheckSchema, concurrency: number, execution: ExecutionCapability, options?: RunRepoContractOptions): Promise<readonly CheckExecutionEntry[]>;
+//# sourceMappingURL=run-checks.d.ts.map

package/dist/.dts/execution/run-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-checks.d.ts","sourceRoot":"","sources":["../../../src/execution/run-checks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,WAAW,EACX,sBAAsB,EACvB,MAAM,aAAa,CAAA;AAIpB,OAAO,KAAK,EAAqB,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAG9E;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,aAAa,CAAC,CAAA;AAYnF,eAAO,MAAM,uBAAuB,QAAgC,CAAA;AAoJpE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,mBAAmB,EAC9B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAkJzC"}