@velum-labs/routekit-eval-setup 1.3.2 → 1.5.0

package/dist/adapters/authoring-responses-request.d.ts

@@ -0,0 +1,5 @@
+import { type EvalAuthoringCompletion } from "../project-authoring.js";
+/** Capacity belongs to a named review, never to arbitrary generated input. */
+export declare const evalAuthoringRequestByteLimit: (input: Pick<EvalAuthoringCompletion, "reviewInputVersion" | "foundryRole" | "schemaName">) => number;
+/** The same wire representation is used for sizing and transport. */
+export declare const evalAuthoringResponsesRequestBody: (input: EvalAuthoringCompletion) => string;

package/dist/adapters/authoring-responses-request.js

@@ -0,0 +1,38 @@
+import { EVAL_AUTHORING_REQUEST_BYTES, EVAL_AUTHORING_REVIEW_REQUEST_BYTES } from "../project-authoring.js";
+/** Capacity belongs to a named review, never to arbitrary generated input. */
+export const evalAuthoringRequestByteLimit = (input) => {
+    if (input.reviewInputVersion === undefined)
+        return EVAL_AUTHORING_REQUEST_BYTES;
+    if (input.reviewInputVersion !== 2 ||
+        !((input.foundryRole === "quality-reviewer" &&
+            input.schemaName === "routekit_repository_generation_quality_review_v1") ||
+            (input.foundryRole === "independent-evidence-review" &&
+                input.schemaName === "routekit_foundry_independent_evidence_review_v1")))
+        throw new Error("expanded input capacity requires a versioned complete evidence review");
+    return EVAL_AUTHORING_REVIEW_REQUEST_BYTES;
+};
+/** The same wire representation is used for sizing and transport. */
+export const evalAuthoringResponsesRequestBody = (input) => JSON.stringify({
+    model: input.model,
+    instructions: input.instructions,
+    input: [
+        {
+            type: "message",
+            role: "user",
+            content: [{ type: "input_text", text: input.input }]
+        }
+    ],
+    text: {
+        format: {
+            type: "json_schema",
+            name: input.schemaName,
+            schema: input.jsonSchema,
+            strict: true
+        }
+    },
+    stream: true,
+    ...(input.reasoningEffort === undefined
+        ? {}
+        : { reasoning: { effort: input.reasoningEffort } }),
+    max_output_tokens: input.maximumOutputTokens
+});

package/dist/adapters/evaluation-evidence-freshness.d.ts

@@ -0,0 +1,7 @@
+import { Effect, FileSystem, Path } from "effect";
+import { EvalEvaluationEvidenceFreshnessError } from "../errors.js";
+import type { EvalEvidenceSource } from "../project-contracts.js";
+export declare function assertCurrentEvaluationEvidence(input: {
+    readonly repositoryRoot: string;
+    readonly evidenceSources: readonly EvalEvidenceSource[];
+}): Effect.Effect<void, EvalEvaluationEvidenceFreshnessError, FileSystem.FileSystem | Path.Path>;

package/dist/adapters/evaluation-evidence-freshness.js

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { Effect, FileSystem, Path } from "effect";
+import { EvalEvaluationEvidenceFreshnessError } from "../errors.js";
+import { assertEvaluationEvidenceSources, compileEvaluationEvidence } from "../evaluation-evidence.js";
+import { EVAL_AUTHORING_EVIDENCE_BLOCK_BYTES } from "../evaluation-authoring-policy.js";
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+const pathIsWithin = (paths, root, candidate) => {
+    const relative = paths.relative(root, candidate);
+    return (relative === "" ||
+        (relative !== ".." &&
+            !relative.startsWith(`..${paths.sep}`) &&
+            !paths.isAbsolute(relative)));
+};
+const freshnessError = (detail, cause) => new EvalEvaluationEvidenceFreshnessError({
+    detail,
+    ...(cause === undefined ? {} : { cause })
+});
+export function assertCurrentEvaluationEvidence(input) {
+    return Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const paths = yield* Path.Path;
+        yield* Effect.try({
+            try: () => assertEvaluationEvidenceSources(input.evidenceSources),
+            catch: (cause) => freshnessError("evaluation evidence metadata failed validation", cause)
+        });
+        const root = yield* fs
+            .realPath(input.repositoryRoot)
+            .pipe(Effect.mapError((cause) => freshnessError("evaluation repository root is unavailable", cause)));
+        for (const source of input.evidenceSources) {
+            const unresolved = paths.resolve(root, source.path);
+            const info = yield* Effect.tryPromise({
+                try: () => lstat(unresolved),
+                catch: (cause) => freshnessError(`evaluation evidence source is unavailable: ${source.path}`, cause)
+            });
+            if (!info.isFile() || info.isSymbolicLink()) {
+                return yield* freshnessError(`evaluation evidence source must remain a regular non-symlink file: ${source.path}`);
+            }
+            const canonical = yield* fs
+                .realPath(unresolved)
+                .pipe(Effect.mapError((cause) => freshnessError(`evaluation evidence source cannot be resolved safely: ${source.path}`, cause)));
+            if (!pathIsWithin(paths, root, canonical)) {
+                return yield* freshnessError(`evaluation evidence source escapes the repository: ${source.path}`);
+            }
+            const content = yield* fs
+                .readFileString(canonical)
+                .pipe(Effect.mapError((cause) => freshnessError(`evaluation evidence source is unavailable: ${source.path}`, cause)));
+            if (sha256(content) !== source.sourceDigest) {
+                return yield* freshnessError(`evaluation evidence source changed after authoring: ${source.path}`);
+            }
+            if (source.sourceBytes !== undefined &&
+                Buffer.byteLength(content, "utf8") !== source.sourceBytes) {
+                return yield* freshnessError(`evaluation evidence source byte metadata changed after authoring: ${source.path}`);
+            }
+            const current = yield* Effect.try({
+                try: () => compileEvaluationEvidence({
+                    sources: [{ path: source.path, content }],
+                    maximumBlockBytes: EVAL_AUTHORING_EVIDENCE_BLOCK_BYTES
+                })[0],
+                catch: (cause) => freshnessError(`evaluation evidence source could not be recompiled: ${source.path}`, cause)
+            });
+            if (source.sourceBlockCount !== undefined &&
+                current.sourceBlockCount !== source.sourceBlockCount) {
+                return yield* freshnessError(`evaluation evidence source block metadata changed after authoring: ${source.path}`);
+            }
+            const currentByOrdinal = new Map(current.blocks.map((block) => [block.ordinal, block]));
+            for (const block of source.blocks) {
+                const currentBlock = currentByOrdinal.get(block.ordinal);
+                if (currentBlock === undefined ||
+                    JSON.stringify(currentBlock) !== JSON.stringify(block)) {
+                    return yield* freshnessError(`evaluation evidence block changed after authoring: ${block.id}`);
+                }
+            }
+        }
+    });
+}

package/dist/adapters/git-task-history.d.ts

@@ -0,0 +1,67 @@
+import { Effect } from "effect";
+import { RepositoryFoundryError } from "../errors.js";
+export type GitTreeSnapshotV1 = {
+    readonly root: string;
+    readonly requestedRef: string;
+    readonly commit: string;
+    readonly tree: string;
+    readonly files: readonly string[];
+};
+export declare const captureGitTreeSnapshotV1: (input: {
+    readonly repositoryRoot: string;
+    readonly requestedRef: string;
+}) => Effect.Effect<{
+    root: string;
+    requestedRef: string;
+    commit: string;
+    tree: string;
+    files: string[];
+}, RepositoryFoundryError, never>;
+export declare const readGitTreeFileV1: (input: {
+    readonly snapshot: GitTreeSnapshotV1;
+    readonly path: string;
+}) => Effect.Effect<string, RepositoryFoundryError, never>;
+export declare const readGitChangeEpisodesV1: (input: {
+    readonly snapshot: GitTreeSnapshotV1;
+    readonly maximumEpisodes?: number;
+}) => Effect.Effect<{
+    occurredAt: string;
+    subject: string;
+    body: string;
+    changedPaths: {
+        readonly kind: "protocol" | "schema" | "test" | "documentation" | "implementation" | "operational" | "other";
+        readonly path: string;
+        readonly status: "added" | "modified" | "deleted" | "renamed" | "copied";
+        readonly previousPath?: string | undefined;
+    }[];
+    testPaths: string[];
+    implementationPaths: string[];
+    protocolPaths: string[];
+    behaviorChanging: boolean;
+    seedEligible: boolean;
+    parentCommit?: string | undefined;
+    id: string;
+    commit: string;
+}[], RepositoryFoundryError, never>;
+export declare const readGitChangeEpisodeV1: (input: {
+    readonly repositoryRoot: string;
+    readonly commit: string;
+}) => Effect.Effect<{
+    occurredAt: string;
+    subject: string;
+    body: string;
+    changedPaths: {
+        readonly kind: "protocol" | "schema" | "test" | "documentation" | "implementation" | "operational" | "other";
+        readonly path: string;
+        readonly status: "added" | "modified" | "deleted" | "renamed" | "copied";
+        readonly previousPath?: string | undefined;
+    }[];
+    testPaths: string[];
+    implementationPaths: string[];
+    protocolPaths: string[];
+    behaviorChanging: boolean;
+    seedEligible: boolean;
+    parentCommit?: string | undefined;
+    id: string;
+    commit: string;
+}, RepositoryFoundryError, never>;

package/dist/adapters/git-task-history.js

@@ -0,0 +1,171 @@
+import { execFile } from "node:child_process";
+import { realpath } from "node:fs/promises";
+import { promisify } from "node:util";
+import { Effect } from "effect";
+import { RepositoryFoundryError } from "../errors.js";
+const execFilePromise = promisify(execFile);
+const MAX_GIT_OUTPUT_BYTES = 32 * 1024 * 1024;
+const DEFAULT_HISTORY_EPISODES = 200;
+const failure = (operation, detail, cause) => new RepositoryFoundryError({
+    operation,
+    detail,
+    ...(cause === undefined ? {} : { cause })
+});
+const git = (root, args, operation) => Effect.tryPromise({
+    try: async () => {
+        const output = (await execFilePromise("git", ["-C", root, ...args], {
+            encoding: "utf8",
+            maxBuffer: MAX_GIT_OUTPUT_BYTES,
+            windowsHide: true
+        }));
+        return output.stdout;
+    },
+    catch: (cause) => failure(operation, `git ${args.join(" ")} failed`, cause)
+});
+const pathKind = (path) => {
+    const lower = path.toLowerCase();
+    const base = lower.split("/").at(-1) ?? lower;
+    if (/(?:^|[._-])(?:test|spec)(?:[._-]|$)/u.test(base) ||
+        /(^|\/)(?:test|tests|__tests__)(\/|$)/u.test(lower)) {
+        return "test";
+    }
+    if (/(^|\/)(?:docs?|examples?)(\/|$)/u.test(lower) ||
+        /(^|\/)readme(?:\.[^/]*)?$/u.test(lower) ||
+        /\.(?:md|mdx)$/u.test(lower)) {
+        return "documentation";
+    }
+    if (/schema/u.test(base))
+        return "schema";
+    if (/(?:protocol|contracts?)/u.test(base) ||
+        /(^|\/)(?:protocols?|contracts?)(\/|$)/u.test(lower)) {
+        return "protocol";
+    }
+    if (/(^|\/)(?:\.github|deploy|infra|scripts?|docker)(\/|$)/u.test(lower) ||
+        /(?:dockerfile|compose\.ya?ml)$/u.test(base)) {
+        return "operational";
+    }
+    if (/\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|swift|rb|php|cs|cpp|cc|c|h)$/u.test(lower)) {
+        return "implementation";
+    }
+    return "other";
+};
+const changedStatus = (raw) => {
+    const code = raw[0];
+    if (code === "A")
+        return "added";
+    if (code === "D")
+        return "deleted";
+    if (code === "R")
+        return "renamed";
+    if (code === "C")
+        return "copied";
+    return "modified";
+};
+const parseChangedPaths = (value) => {
+    const tokens = value.split("\0").filter((token) => token.length > 0);
+    const paths = [];
+    for (let index = 0; index < tokens.length;) {
+        const rawStatus = tokens[index++];
+        if (rawStatus === undefined)
+            break;
+        const status = changedStatus(rawStatus);
+        if (status === "renamed" || status === "copied") {
+            const previousPath = tokens[index++];
+            const path = tokens[index++];
+            if (previousPath === undefined || path === undefined)
+                break;
+            paths.push({
+                path,
+                previousPath,
+                status,
+                kind: pathKind(path)
+            });
+            continue;
+        }
+        const path = tokens[index++];
+        if (path === undefined)
+            break;
+        paths.push({ path, status, kind: pathKind(path) });
+    }
+    return paths;
+};
+const metadata = (value) => {
+    const [commit = "", parents = "", occurredAt = "", subject = "", ...body] = value.split("\0");
+    const parentCommit = parents.split(/\s+/u).filter(Boolean)[0];
+    return {
+        commit,
+        parentCount: parents.split(/\s+/u).filter(Boolean).length,
+        ...(parentCommit === undefined ? {} : { parentCommit }),
+        occurredAt,
+        subject,
+        body: body.join("\0").trim()
+    };
+};
+export const captureGitTreeSnapshotV1 = Effect.fn("RepositoryFoundry.captureGitTreeSnapshot")(function* (input) {
+    const root = yield* Effect.tryPromise({
+        try: () => realpath(input.repositoryRoot),
+        catch: (cause) => failure("resolve-repository", `failed to resolve ${JSON.stringify(input.repositoryRoot)}`, cause)
+    });
+    const requestedRef = input.requestedRef.trim();
+    if (requestedRef.length === 0) {
+        return yield* failure("resolve-repository", "requested Git ref must not be empty");
+    }
+    const commit = (yield* git(root, ["rev-parse", "--verify", `${requestedRef}^{commit}`], "read-git-tree")).trim();
+    const tree = (yield* git(root, ["rev-parse", "--verify", `${requestedRef}^{tree}`], "read-git-tree")).trim();
+    const files = (yield* git(root, ["ls-tree", "-r", "--name-only", "-z", tree], "read-git-tree"))
+        .split("\0")
+        .filter((path) => path.length > 0)
+        .sort();
+    return { root, requestedRef, commit, tree, files };
+});
+export const readGitTreeFileV1 = Effect.fn("RepositoryFoundry.readGitTreeFile")(function* (input) {
+    if (!input.snapshot.files.includes(input.path) ||
+        input.path.startsWith("/") ||
+        input.path.split("/").includes("..") ||
+        input.path.includes("\0")) {
+        return yield* failure("read-git-tree", `path is not in the frozen Git tree: ${JSON.stringify(input.path)}`);
+    }
+    return yield* git(input.snapshot.root, ["show", `${input.snapshot.tree}:${input.path}`], "read-git-tree");
+});
+export const readGitChangeEpisodesV1 = Effect.fn("RepositoryFoundry.readGitChangeEpisodes")(function* (input) {
+    const maximumEpisodes = Math.max(1, Math.min(input.maximumEpisodes ?? DEFAULT_HISTORY_EPISODES, 1_000));
+    const commits = (yield* git(input.snapshot.root, [
+        "rev-list",
+        "--reverse",
+        "--no-merges",
+        `--max-count=${String(maximumEpisodes)}`,
+        input.snapshot.commit
+    ], "read-git-history"))
+        .split(/\r?\n/u)
+        .filter(Boolean);
+    return yield* Effect.forEach(commits, (commit) => readGitChangeEpisodeV1({
+        repositoryRoot: input.snapshot.root,
+        commit
+    }));
+});
+export const readGitChangeEpisodeV1 = Effect.fn("RepositoryFoundry.readGitChangeEpisode")(function* (input) {
+    const info = metadata(yield* git(input.repositoryRoot, ["show", "-s", "--format=%H%x00%P%x00%cI%x00%s%x00%b", input.commit], "read-git-history"));
+    const changedPaths = parseChangedPaths(yield* git(input.repositoryRoot, ["diff-tree", "--root", "--no-commit-id", "--name-status", "-r", "-z", "-M", input.commit], "read-git-history"));
+    const testPaths = changedPaths.filter((path) => path.kind === "test").map((path) => path.path);
+    const implementationPaths = changedPaths
+        .filter((path) => path.kind === "implementation")
+        .map((path) => path.path);
+    const protocolPaths = changedPaths
+        .filter((path) => path.kind === "protocol" || path.kind === "schema")
+        .map((path) => path.path);
+    const behaviorChanging = implementationPaths.length > 0 || protocolPaths.length > 0;
+    return {
+        id: `git-${info.commit}`,
+        commit: info.commit,
+        ...(info.parentCommit === undefined ? {} : { parentCommit: info.parentCommit }),
+        occurredAt: info.occurredAt,
+        subject: info.subject,
+        body: info.body,
+        changedPaths,
+        testPaths,
+        implementationPaths,
+        protocolPaths,
+        behaviorChanging,
+        seedEligible: behaviorChanging && testPaths.length > 0 && info.parentCount === 1
+    };
+});

package/dist/adapters/integrated-repository-history.d.ts

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import { RepositoryFoundryError } from "../errors.js";
+import type { RepositoryChangeEpisodeV1 } from "../repository-behavior-protocol.js";
+import { type RepositoryIntegratedHistoryProvenanceV1 } from "../repository-foundry-plan-protocol.js";
+export type IntegratedRepositoryHistoryEpisodeV1 = {
+    readonly episode: RepositoryChangeEpisodeV1;
+    readonly provenance: RepositoryIntegratedHistoryProvenanceV1;
+};
+export declare const discoverIntegratedRepositoryHistoryV1: (input: {
+    readonly repositoryRoot: string;
+    readonly requestedRef: string;
+    readonly requestedTipCommit: string;
+    readonly requestedTipTree: string;
+    readonly integrationCommits: readonly string[];
+}) => Effect.Effect<IntegratedRepositoryHistoryEpisodeV1[], RepositoryFoundryError, never>;
+export declare const validateIntegratedRepositoryHistoryV1: (input: {
+    readonly repositoryRoot: string;
+    readonly referenceCommit: string;
+    readonly initialCommit: string;
+    readonly provenance: RepositoryIntegratedHistoryProvenanceV1;
+}) => Effect.Effect<undefined, RepositoryFoundryError, never>;

package/dist/adapters/integrated-repository-history.js

@@ -0,0 +1,175 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { Effect } from "effect";
+import { RepositoryFoundryError } from "../errors.js";
+import { REPOSITORY_INTEGRATED_HISTORY_MAXIMUM_PATHS, validIntegratedHistoryProvenanceV1 } from "../repository-foundry-plan-protocol.js";
+import { readGitChangeEpisodeV1 } from "./git-task-history.js";
+const execFilePromise = promisify(execFile);
+const MAXIMUM_REFS = 64;
+const MAXIMUM_EXTRA_EPISODES = 128;
+const MAXIMUM_INTEGRATION_SNAPSHOTS = 200;
+const MAXIMUM_BLOB_CHECKS = 131_072;
+const objectId = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
+const failure = (detail, cause) => new RepositoryFoundryError({
+    operation: "read-git-history",
+    detail,
+    ...(cause === undefined ? {} : { cause })
+});
+const git = (root, args) => Effect.tryPromise({
+    try: async () => (await execFilePromise("git", ["-C", root, "--literal-pathspecs", ...args], {
+        encoding: "utf8",
+        maxBuffer: 32 * 1024 * 1024,
+        timeout: 15_000,
+        windowsHide: true
+    })).stdout,
+    catch: (cause) => failure("failed to read immutable integrated history Git facts", cause)
+});
+const lines = (text) => text.trim().split(/\r?\n/u).filter(Boolean);
+const behaviorPaths = (episode) => [
+    ...new Set([...episode.implementationPaths, ...episode.protocolPaths, ...episode.testPaths])
+].sort();
+const recoverable = (episode) => episode.seedEligible &&
+    episode.parentCommit !== undefined &&
+    !episode.changedPaths.some(({ status }) => status === "deleted" || status === "renamed" || status === "copied") &&
+    behaviorPaths(episode).length <= REPOSITORY_INTEGRATED_HISTORY_MAXIMUM_PATHS &&
+    !behaviorPaths(episode).some((path) => path.length > 1_024 ||
+        path.includes("\0") ||
+        path.includes("\\") ||
+        path.split("/").some((part) => part === "" || part === "." || part === "..") ||
+        /(^|\/)(?:docs?|examples?)(\/|$)/iu.test(path));
+// Read object IDs, never execute retained code or follow tree symlinks. Missing
+// paths, submodules and symlinks cannot furnish regular-file integration proof.
+const pathBlobs = Effect.fnUntraced(function* (root, commit, paths) {
+    const result = new Map();
+    if (paths.length === 0)
+        return result;
+    const requested = new Set(paths);
+    for (let offset = 0; offset < paths.length; offset += 128) {
+        const output = yield* git(root, [
+            "ls-tree",
+            "-r",
+            "-z",
+            commit,
+            "--",
+            ...paths.slice(offset, offset + 128)
+        ]);
+        for (const entry of output.split("\0")) {
+            const match = /^(100644|100755) blob ([a-f0-9]+)\t([\s\S]+)$/u.exec(entry);
+            if (match !== null && requested.has(match[3]) && objectId.test(match[2])) {
+                result.set(match[3], match[2]);
+            }
+        }
+    }
+    return result;
+});
+export const discoverIntegratedRepositoryHistoryV1 = Effect.fn("RepositoryFoundry.discoverIntegratedRepositoryHistory")(function* (input) {
+    if (!objectId.test(input.requestedTipCommit) || !objectId.test(input.requestedTipTree)) {
+        return yield* failure("integrated history discovery requires an immutable requested tip");
+    }
+    const root = input.repositoryRoot;
+    const tree = (yield* git(root, ["rev-parse", `${input.requestedTipCommit}^{tree}`])).trim();
+    if (tree !== input.requestedTipTree)
+        return yield* failure("requested tip tree does not match Git");
+    const reachable = lines(yield* git(root, [
+        "rev-list",
+        `--max-count=${MAXIMUM_INTEGRATION_SNAPSHOTS}`,
+        input.requestedTipCommit
+    ]));
+    const permitted = new Set([input.requestedTipCommit, ...input.integrationCommits]);
+    const integrations = reachable.filter((commit) => permitted.has(commit));
+    // Recent retained local/remote branch tips are bounded, deterministic input
+    // candidates. A branch name or ancestry by itself never certifies integration.
+    const refs = [
+        ...new Set(lines(yield* git(root, [
+            "for-each-ref",
+            "--sort=refname",
+            "--sort=-committerdate",
+            `--count=${MAXIMUM_REFS}`,
+            "--format=%(objectname)",
+            "refs/heads",
+            "refs/remotes"
+        ])))
+    ].filter((commit) => objectId.test(commit));
+    if (refs.length === 0)
+        return [];
+    const retained = lines(yield* git(root, [
+        "rev-list",
+        "--no-merges",
+        `--max-count=${MAXIMUM_EXTRA_EPISODES}`,
+        ...refs,
+        "--not",
+        input.requestedTipCommit
+    ]));
+    const candidates = [];
+    for (const commit of retained) {
+        const episode = yield* readGitChangeEpisodeV1({ repositoryRoot: root, commit });
+        if (!recoverable(episode))
+            continue;
+        const paths = behaviorPaths(episode);
+        const blobs = yield* pathBlobs(root, commit, paths);
+        if (blobs.size === paths.length)
+            candidates.push({ episode, blobs });
+    }
+    const allPaths = [...new Set(candidates.flatMap(({ episode }) => behaviorPaths(episode)))].sort();
+    const results = [];
+    const certified = new Set();
+    let blobChecks = retained.length * REPOSITORY_INTEGRATED_HISTORY_MAXIMUM_PATHS;
+    for (const integrationCommit of integrations) {
+        if (allPaths.length === 0 || blobChecks + allPaths.length > MAXIMUM_BLOB_CHECKS)
+            break;
+        blobChecks += allPaths.length;
+        const integrated = yield* pathBlobs(root, integrationCommit, allPaths);
+        for (const { episode, blobs } of candidates) {
+            if (certified.has(episode.commit) ||
+                ![...blobs].every(([path, blob]) => integrated.get(path) === blob))
+                continue;
+            certified.add(episode.commit);
+            results.push({
+                episode,
+                provenance: {
+                    method: "integrated-retained-history-v1",
+                    requestedRef: input.requestedRef,
+                    requestedTipCommit: input.requestedTipCommit,
+                    requestedTipTree: input.requestedTipTree,
+                    integrationCommit,
+                    pathBlobs: [...blobs]
+                        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                        .map(([path, blob]) => ({ path, blob }))
+                }
+            });
+        }
+    }
+    return results;
+});
+export const validateIntegratedRepositoryHistoryV1 = Effect.fn("RepositoryFoundry.validateIntegratedRepositoryHistory")(function* (input) {
+    const { provenance: proof, repositoryRoot: root } = input;
+    if (!validIntegratedHistoryProvenanceV1(proof) ||
+        !objectId.test(input.referenceCommit) ||
+        !objectId.test(input.initialCommit)) {
+        return yield* failure("integrated history provenance has invalid identifiers or path proof");
+    }
+    const tree = (yield* git(root, ["rev-parse", `${proof.requestedTipCommit}^{tree}`])).trim();
+    const ancestor = (yield* git(root, [
+        "merge-base",
+        proof.integrationCommit,
+        proof.requestedTipCommit
+    ])).trim();
+    if (tree !== proof.requestedTipTree || ancestor !== proof.integrationCommit) {
+        return yield* failure("integrated history proof does not match the requested reachable snapshot");
+    }
+    const episode = yield* readGitChangeEpisodeV1({
+        repositoryRoot: root,
+        commit: input.referenceCommit
+    });
+    const paths = behaviorPaths(episode);
+    if (!recoverable(episode) ||
+        episode.parentCommit !== input.initialCommit ||
+        JSON.stringify(paths) !== JSON.stringify(proof.pathBlobs.map(({ path }) => path))) {
+        return yield* failure("integrated history proof does not cover the complete eligible historical change");
+    }
+    const reference = yield* pathBlobs(root, input.referenceCommit, paths);
+    const integrated = yield* pathBlobs(root, proof.integrationCommit, paths);
+    if (!proof.pathBlobs.every(({ path, blob }) => reference.get(path) === blob && integrated.get(path) === blob)) {
+        return yield* failure("integrated history path blob proof does not match Git objects");
+    }
+});

package/dist/adapters/repository-command-diagnostic.d.ts

@@ -0,0 +1,8 @@
+export type RepositoryCommandDiagnosticV1 = Readonly<{
+    text: string;
+    truncated: boolean;
+}>;
+export declare function sanitizeRepositoryCommandOutputV1(source: string): string;
+export declare function sanitizeRepositoryCommandDiagnosticV1(stdout: string, stderr: string, inputTruncated?: boolean): RepositoryCommandDiagnosticV1 | undefined;
+export declare function encodeRepositoryCommandDiagnosticV1(diagnostic: string): string;
+export declare function decodeRepositoryCommandDiagnosticV1(encoded: string): string | undefined;

package/dist/adapters/repository-command-diagnostic.js

@@ -0,0 +1,46 @@
+const COMMAND_DIAGNOSTIC_LIMIT = 3_072;
+const REDACTED = "[redacted]";
+const redactSensitiveQueryParameters = (value) => value.replace(/([?&](?:access_token|api[_-]?key|auth|authorization|client_secret|credential|key|password|secret|signature|token)=)[^&#\s]*/giu, `$1${REDACTED}`);
+export function sanitizeRepositoryCommandOutputV1(source) {
+    return (redactSensitiveQueryParameters(source)
+        .replace(/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/gu, REDACTED)
+        .replace(/((?:https?|ssh):\/\/)[^/\s@]+@/giu, `$1${REDACTED}@`)
+        .replace(/\b(?:github_pat_[A-Za-z0-9_]{20,}|gh[pousr]_[A-Za-z0-9]{20,})\b/gu, REDACTED)
+        .replace(/\b(?:sk|pplx)-[A-Za-z0-9_-]{20,}\b|\bhf_[A-Za-z0-9]{20,}\b|\bnpm_[A-Za-z0-9]{20,}\b|\bxox[baprs]-[A-Za-z0-9-]{20,}\b/gu, REDACTED)
+        .replace(/\bAKIA[0-9A-Z]{16}\b/gu, REDACTED)
+        .replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/gu, REDACTED)
+        .replace(/(\bBearer\s+)[^\s"',;]+/giu, `$1${REDACTED}`)
+        .replace(/(\bAuthorization\b\s*[:=]\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,;]+)/giu, `$1${REDACTED}`)
+        .replace(/(\b(?:api[_-]?key|auth|client[_-]?secret|credential|password|passwd|secret|token)\b\s*[:=]\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,;]+)/giu, `$1${REDACTED}`)
+        // Compiler and package-manager output commonly includes ANSI styling.
+        // Persist plain text so the same bounded output is readable in JSON,
+        // HTML, and OpenTelemetry log backends.
+        .replace(/\u001B(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007]*(?:\u0007|\u001B\\))/gu, ""));
+}
+export function sanitizeRepositoryCommandDiagnosticV1(stdout, stderr, inputTruncated = false) {
+    const source = [stderr, stdout]
+        .map((value) => value.trim())
+        .filter(Boolean)
+        .join("\n");
+    if (source.length === 0)
+        return undefined;
+    const redacted = sanitizeRepositoryCommandOutputV1(source);
+    const truncated = inputTruncated || redacted.length > COMMAND_DIAGNOSTIC_LIMIT;
+    const text = redacted.slice(0, COMMAND_DIAGNOSTIC_LIMIT).trimEnd();
+    return text.length === 0 ? undefined : { text, truncated };
+}
+export function encodeRepositoryCommandDiagnosticV1(diagnostic) {
+    return Buffer.from(diagnostic, "utf8").toString("base64url");
+}
+export function decodeRepositoryCommandDiagnosticV1(encoded) {
+    try {
+        const bytes = Buffer.from(encoded, "base64url");
+        if (bytes.toString("base64url") !== encoded)
+            return undefined;
+        const decoded = bytes.toString("utf8");
+        return decoded.length > 0 && decoded.length <= COMMAND_DIAGNOSTIC_LIMIT ? decoded : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/adapters/repository-command-evidence.d.ts

@@ -0,0 +1,13 @@
+import type { RepositoryCommandInvocationResultV1, RepositoryCommandResultV1 } from "../repository-execution-protocol.js";
+/** Process completion and evidence completeness are prerequisites, not grades. */
+export declare const repositoryCommandExecutionIncompleteV1: (result: RepositoryCommandInvocationResultV1) => boolean;
+type RepositoryCommandTestEvidenceV1 = {
+    readonly outcome: "pass" | "fail" | "unknown";
+    readonly detail: string;
+    /** A repair hint only. This never turns an unclassified error into a semantic failure. */
+    readonly inconclusiveReason?: "unattributed-test-failure";
+};
+export declare const repositoryCommandTestEvidenceV1: (result: RepositoryCommandResultV1 | undefined, recipeId: string) => RepositoryCommandTestEvidenceV1;
+/** A diagnostic probe uses the same evidence rules as admission, never exit status alone. */
+export declare const repositoryCommandProbeOutcomeV1: (results: readonly RepositoryCommandResultV1[]) => "completed" | "scientific_rejection" | "environment_blocked";
+export {};