@tea-agent/loop-agent 0.15.0 → 0.16.1-beta.0

package/dist/worker/delivery/verification-bundle.js

@@ -0,0 +1,510 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { controllerIdentitiesMatch } from "../loop-agent/loop-agent-client.js";
+import { readVerifiedOutcome } from "../outcomes/store.js";
+import { getTaskPoolRoot, readFeatureTaskPoolStates } from "../pool/run-store.js";
+import { workflowSchema } from "../task-spec/workflow-routing.js";
+import { gitTransactionRecordSchema, transactionRecordPath } from "./git-transaction.js";
+/**
+ * Feature Verification Bundle v1 — a hash-bound aggregate of completed typed
+ * `backend-test` / `frontend-test` Task Outcome Envelopes that lets
+ * `feature verify-final` and Delivery consume direct typed test evidence
+ * without requiring a legacy `qa-execute` aggregate.
+ *
+ * The bundle is fail-closed on every drift dimension required by the W3.3
+ * contract: outcome hash/tamper, feature/task/workflow identity, controller
+ * identity, and Delivery HEAD. It never moves Git HEAD and never writes the
+ * worktree; persistence only writes the Feature evidence directory.
+ */
+export const VERIFICATION_BUNDLE_SCHEMA_VERSION = 1;
+const TYPED_VERIFICATION_WORKFLOWS = ["backend-test", "frontend-test"];
+const bundleOutcomeSchema = z
+    .object({
+    featureId: z.string().min(1),
+    taskId: z.string().min(1),
+    workflow: z.enum(TYPED_VERIFICATION_WORKFLOWS),
+    workerRunId: z.string().min(1),
+    harnessTaskId: z.string().min(1).optional(),
+    outcomePath: z.string().min(1),
+    outcomeSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    acceptanceCoverage: z.array(z.string().min(1)),
+    artifacts: z.array(z.object({ path: z.string().min(1), sha256: z.string().regex(/^[a-f0-9]{64}$/), kind: z.string().min(1).optional() }).strict()),
+    integrationStatus: z.object({ mock: z.boolean(), real: z.boolean() }).strict(),
+    outcomeStatus: z.enum(["succeeded", "failed"]),
+    controllerIdentity: z
+        .object({
+        packageName: z.string().min(1),
+        packageVersion: z.string().min(1),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+const bundleControllerIdentitySchema = z
+    .object({
+    packageName: z.string().min(1),
+    packageVersion: z.string().min(1),
+})
+    .strict()
+    .optional();
+const bundleAcceptanceItemSchema = z
+    .object({
+    acId: z.string().min(1),
+    status: z.enum(["covered", "partial", "blocked", "missing"]),
+})
+    .strict();
+export const featureVerificationBundleV1Schema = z
+    .object({
+    schemaVersion: z.literal(VERIFICATION_BUNDLE_SCHEMA_VERSION),
+    featureId: z.string().min(1),
+    controllerIdentity: bundleControllerIdentitySchema,
+    headSha: z.string().regex(/^[a-f0-9]{40}$/),
+    backendTests: z.array(bundleOutcomeSchema),
+    frontendTests: z.array(bundleOutcomeSchema),
+    acceptance: z.array(bundleAcceptanceItemSchema),
+    bundleSha256: z.string().regex(/^[a-f0-9]{64}$/),
+})
+    .strict();
+/**
+ * Pure projection that aggregates completed `backend-test` / `frontend-test`
+ * outcomes into a hash-bound Feature Verification Bundle v1.
+ *
+ * Fail-closed guarantees:
+ *  - only typed verification workflows (`backend-test`, `frontend-test`) are accepted;
+ *  - only `outcomeStatus === "succeeded"` outcomes contribute;
+ *  - every contributing outcome's `identity.featureId` must equal the bundle featureId;
+ *  - controller identity is asserted across outcome ↔ run ↔ input (all-present-or-all-absent
+ *    tolerance is preserved for legacy packets that never recorded an identity);
+ *  - required acceptance (`priority === "must"`) must be fully covered by the typed
+ *    evidence union, otherwise the projection throws (fail closed — no silent
+ *    downgrade to a partial bundle).
+ *
+ * The function never touches the filesystem; persistence is delegated to
+ * {@link writeFeatureVerificationBundle}.
+ */
+export function buildFeatureVerificationBundle(input) {
+    const implementationTaskIds = input.implementationTaskIds ?? new Set();
+    const backendTests = [];
+    const frontendTests = [];
+    for (const run of input.runs) {
+        if (run.featureId !== input.featureId) {
+            throw new Error(`verification bundle run featureId mismatch: ${run.workerRunId}`);
+        }
+        if (run.status !== "succeeded") {
+            throw new Error(`verification bundle requires a succeeded run: ${run.workerRunId}`);
+        }
+        const workflow = run.workflow;
+        if (!workflow || !isTypedVerificationWorkflow(workflow)) {
+            // Non-typed runs (e.g. agent-dag, qa-execute) are simply ignored by the
+            // typed bundle — they belong to the legacy aggregate path.
+            continue;
+        }
+        const spec = input.specs.get(run.taskId);
+        const outcome = input.outcomes.get(run.workerRunId);
+        if (!spec || !outcome) {
+            throw new Error(`verification bundle is missing spec or outcome for run: ${run.workerRunId}`);
+        }
+        if (!isTypedVerificationWorkflow(outcome.identity.workflow)) {
+            throw new Error(`verification bundle outcome workflow is not a typed test: ${run.workerRunId}`);
+        }
+        if (spec.feature_id !== input.featureId || spec.execution?.workflow !== workflow || outcome.identity.workflow !== workflow) {
+            throw new Error(`verification bundle TaskSpec workflow identity mismatch: ${run.workerRunId}`);
+        }
+        if (outcome.identity.featureId !== input.featureId) {
+            throw new Error(`verification bundle outcome featureId mismatch: ${run.workerRunId}`);
+        }
+        if (outcome.identity.taskId !== run.taskId) {
+            throw new Error(`verification bundle outcome taskId mismatch: ${run.workerRunId}`);
+        }
+        if (outcome.identity.workerRunId !== run.workerRunId) {
+            throw new Error(`verification bundle outcome workerRunId mismatch: ${run.workerRunId}`);
+        }
+        if (outcome.outcomeStatus !== "succeeded") {
+            throw new Error(`verification bundle requires a succeeded outcome: ${run.workerRunId}`);
+        }
+        assertControllerIdentityTriple(outcome.controllerIdentity, run.controllerIdentity, input.controllerIdentity, run.workerRunId);
+        const bundleOutcome = {
+            featureId: outcome.identity.featureId,
+            taskId: outcome.identity.taskId,
+            workflow: outcome.identity.workflow,
+            workerRunId: outcome.identity.workerRunId,
+            ...(outcome.identity.harnessTaskId
+                ? { harnessTaskId: outcome.identity.harnessTaskId }
+                : {}),
+            outcomePath: run.outcomePath ?? "",
+            outcomeSha256: run.outcomeSha256 ?? "",
+            acceptanceCoverage: outcome.acceptanceCoverage,
+            artifacts: outcome.artifacts,
+            integrationStatus: outcome.integrationStatus,
+            outcomeStatus: outcome.outcomeStatus,
+            ...(outcome.controllerIdentity
+                ? {
+                    controllerIdentity: {
+                        packageName: outcome.controllerIdentity.packageName,
+                        packageVersion: outcome.controllerIdentity.packageVersion,
+                    },
+                }
+                : {}),
+        };
+        if (workflow === "backend-test")
+            backendTests.push(bundleOutcome);
+        else
+            frontendTests.push(bundleOutcome);
+    }
+    backendTests.sort(byTaskId);
+    frontendTests.sort(byTaskId);
+    const acceptanceItems = input.acceptance.map((item) => projectBundleAcceptance(item, backendTests, frontendTests, implementationTaskIds, input.featureId));
+    // Fail closed: a required AC that is not fully covered by typed evidence
+    // must never silently produce a bundle. Non-required ACs may remain partial
+    // or missing for informational reporting without blocking the bundle.
+    const requiredGaps = acceptanceItems.filter((item) => item.priority === "must" && item.status !== "covered");
+    if (requiredGaps.length > 0) {
+        throw new Error(`verification bundle does not cover required acceptance: ${requiredGaps
+            .map((item) => item.acId)
+            .join(", ")}`);
+    }
+    const bundle = {
+        schemaVersion: VERIFICATION_BUNDLE_SCHEMA_VERSION,
+        featureId: input.featureId,
+        ...(input.controllerIdentity
+            ? {
+                controllerIdentity: {
+                    packageName: input.controllerIdentity.packageName,
+                    packageVersion: input.controllerIdentity.packageVersion,
+                },
+            }
+            : { controllerIdentity: undefined }),
+        headSha: input.headSha,
+        backendTests,
+        frontendTests,
+        acceptance: acceptanceItems.map(({ acId, status }) => ({ acId, status })),
+        bundleSha256: "",
+    };
+    bundle.bundleSha256 = computeBundleSha256(bundle);
+    return featureVerificationBundleV1Schema.parse(bundle);
+}
+function projectBundleAcceptance(item, backendTests, frontendTests, implementationTaskIds, expectedFeatureId) {
+    const implRefs = item.verification.implementation_task_refs ?? [];
+    const verRefs = item.verification.verification_task_refs ?? [];
+    const requiredEvidence = item.verification.required_evidence ?? [];
+    const integration = item.verification.integration;
+    const allTests = [...backendTests, ...frontendTests];
+    const coveredAcIds = new Set(allTests.flatMap((entry) => entry.acceptanceCoverage));
+    // 1. implementation refs must all be present (Done).
+    const implDone = implRefs.length > 0
+        ? implRefs.every((id) => implementationTaskIds.has(id))
+        : true;
+    // 2. verification refs must each have a succeeded typed outcome.
+    const verEnvelopes = verRefs.length
+        ? verRefs
+            .map((taskId) => allTests.find((entry) => entry.taskId === taskId))
+            .filter((value) => Boolean(value))
+        : [];
+    const verSucceeded = verRefs.length === 0 ||
+        (verEnvelopes.length === verRefs.length &&
+            verEnvelopes.every((entry) => entry.outcomeStatus === "succeeded"));
+    if (!implDone) {
+        return { acId: item.id, status: implRefs.length ? "partial" : "missing", priority: item.priority };
+    }
+    if (verRefs.length > 0 && !verSucceeded) {
+        return {
+            acId: item.id,
+            status: verEnvelopes.length === 0 ? "missing" : "partial",
+            priority: item.priority,
+        };
+    }
+    // 3. identity consistency: every contributing typed outcome must belong to
+    //    the bundle Feature. A cross-Feature outcome is a fail-closed signal.
+    const crossFeature = verEnvelopes.some((entry) => entry.featureId !== expectedFeatureId);
+    if (crossFeature) {
+        return { acId: item.id, status: "missing", priority: item.priority };
+    }
+    // 4. required evidence kinds must each appear on at least one envelope.
+    if (requiredEvidence.some((kind) => !verEnvelopes.some((entry) => evidenceKindPresent(entry, kind)))) {
+        return { acId: item.id, status: "partial", priority: item.priority };
+    }
+    // 5. real-required integration demands real evidence on every verification envelope.
+    if (integration === "real-required") {
+        if (verRefs.length === 0) {
+            return { acId: item.id, status: "missing", priority: item.priority };
+        }
+        const realOk = verEnvelopes.every((entry) => entry.integrationStatus.real === true);
+        if (!realOk) {
+            return { acId: item.id, status: "partial", priority: item.priority };
+        }
+    }
+    // 6. AC must be referenced by at least one typed outcome's acceptanceCoverage
+    //    so a stray verification run cannot satisfy an unrelated AC.
+    if (!coveredAcIds.has(item.id)) {
+        return { acId: item.id, status: "missing", priority: item.priority };
+    }
+    return { acId: item.id, status: "covered", priority: item.priority };
+}
+function evidenceKindPresent(entry, kind) {
+    return entry.artifacts.some((artifact) => artifact.kind === kind);
+}
+function isTypedVerificationWorkflow(workflow) {
+    return TYPED_VERIFICATION_WORKFLOWS.includes(workflow);
+}
+function byTaskId(a, b) {
+    return a.taskId.localeCompare(b.taskId);
+}
+/**
+ * Canonical SHA-256 of the bundle, computed over a stable JSON serialization
+ * (sorted keys, no whitespace) that excludes the `bundleSha256` field itself.
+ * Any byte-level tamper therefore invalidates the stored hash.
+ */
+export function computeBundleSha256(bundle) {
+    const canonical = {
+        schemaVersion: bundle.schemaVersion,
+        featureId: bundle.featureId,
+        ...(bundle.controllerIdentity
+            ? { controllerIdentity: bundle.controllerIdentity }
+            : {}),
+        headSha: bundle.headSha,
+        backendTests: bundle.backendTests,
+        frontendTests: bundle.frontendTests,
+        acceptance: bundle.acceptance,
+    };
+    return createHash("sha256")
+        .update(JSON.stringify(canonical, stableKeyReplacer))
+        .digest("hex");
+}
+function stableKeyReplacer(_key, value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return Object.keys(value)
+            .sort()
+            .reduce((acc, key) => {
+            acc[key] = value[key];
+            return acc;
+        }, {});
+    }
+    return value;
+}
+/**
+ * Assert the controller identity triple (outcome ↔ Task Pool run ↔ input) is
+ * consistent. All-absent is tolerated for legacy packets that never recorded
+ * an identity; any present/absent or present/present-mismatch is fail-closed.
+ */
+export function assertControllerIdentityTriple(outcomeIdentity, runIdentity, inputIdentity, label) {
+    if (!outcomeIdentity && !runIdentity && !inputIdentity)
+        return;
+    if (!outcomeIdentity || !runIdentity || !inputIdentity) {
+        throw new Error(`controller identity mismatch in verification bundle: ${label}`);
+    }
+    if (outcomeIdentity.packageName !== runIdentity.packageName ||
+        outcomeIdentity.packageVersion !== runIdentity.packageVersion ||
+        !controllerIdentitiesMatch(runIdentity, inputIdentity)) {
+        throw new Error(`controller identity mismatch in verification bundle: ${label}`);
+    }
+}
+/** Resolve the evidence-directory path for a Feature Verification Bundle. */
+export function bundleEvidencePath(repoRoot, featureId) {
+    return path.join(getTaskPoolRoot(repoRoot), "evidence", featureId, "feature-verification-bundle.json");
+}
+/**
+ * Persist a built bundle atomically under the Feature evidence directory. The
+ * stored bytes are validated against {@link featureVerificationBundleV1Schema}
+ * and the canonical hash is reasserted before the rename. Never moves HEAD and
+ * never writes outside the evidence directory.
+ */
+export async function writeFeatureVerificationBundle(repoRoot, bundle) {
+    const parsed = featureVerificationBundleV1Schema.parse(bundle);
+    const recomputed = computeBundleSha256(parsed);
+    if (recomputed !== parsed.bundleSha256) {
+        throw new Error("verification bundle hash does not match its canonical bytes");
+    }
+    const canonicalRepoRoot = await realpath(repoRoot);
+    const evidenceDir = path.join(getTaskPoolRoot(canonicalRepoRoot), "evidence", parsed.featureId);
+    const target = path.join(evidenceDir, "feature-verification-bundle.json");
+    await mkdir(evidenceDir, { recursive: true });
+    const payload = `${JSON.stringify(parsed, null, 2)}\n`;
+    const temp = path.join(evidenceDir, `.feature-verification-bundle.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temp, payload, "utf-8");
+        await rename(temp, target);
+    }
+    finally {
+        await unlink(temp).catch(() => { });
+    }
+    return {
+        path: path.relative(canonicalRepoRoot, target).replace(/\\/g, "/"),
+        sha256: parsed.bundleSha256,
+    };
+}
+/**
+ * Read and verify a Feature Verification Bundle by hashed ref. Returns
+ * `undefined` on any path-containment, hash, or schema failure so callers
+ * naturally fail the Delivery/Closeout gate closed.
+ */
+export async function readVerifiedBundle(input) {
+    if (!input.ref?.path || !input.ref?.sha256)
+        return undefined;
+    const repoRoot = await realpath(input.repoRoot);
+    const candidate = path.resolve(repoRoot, input.ref.path);
+    const relative = path.relative(repoRoot, candidate);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = await readFile(candidate, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = featureVerificationBundleV1Schema.parse(JSON.parse(raw));
+    }
+    catch {
+        return undefined;
+    }
+    if (computeBundleSha256(parsed) !== parsed.bundleSha256)
+        return undefined;
+    if (parsed.bundleSha256 !== input.ref.sha256)
+        return undefined;
+    return parsed;
+}
+/**
+ * Verify that every outcome referenced by a persisted bundle still resolves to
+ * its hash-anchored bytes on disk. Used by Delivery/Closeout to detect outcome
+ * tamper or drift after the bundle was written.
+ */
+export async function verifyBundleOutcomes(repoRoot, bundle) {
+    for (const outcome of [...bundle.backendTests, ...bundle.frontendTests]) {
+        const verified = await readVerifiedOutcome({
+            repoRoot,
+            workerRunId: outcome.workerRunId,
+            outcomePath: outcome.outcomePath,
+            outcomeSha256: outcome.outcomeSha256,
+        });
+        if (!verified)
+            return false;
+        if (verified.identity.featureId !== bundle.featureId)
+            return false;
+        if (verified.identity.taskId !== outcome.taskId)
+            return false;
+        if (verified.identity.workflow !== outcome.workflow)
+            return false;
+        if (verified.outcomeStatus !== "succeeded")
+            return false;
+        if (JSON.stringify(verified.artifacts) !== JSON.stringify(outcome.artifacts))
+            return false;
+        if (!await verifyArtifactRefs(repoRoot, outcome.artifacts))
+            return false;
+    }
+    return true;
+}
+/** Rebind a persisted bundle to the current Feature Packet TaskSpec contracts. */
+export function verifyBundleTaskSpecBindings(bundle, specs) {
+    const taskIds = new Set();
+    for (const outcome of [...bundle.backendTests, ...bundle.frontendTests]) {
+        if (taskIds.has(outcome.taskId))
+            return false;
+        taskIds.add(outcome.taskId);
+        const spec = specs.get(outcome.taskId);
+        if (!spec ||
+            spec.feature_id !== bundle.featureId ||
+            spec.type !== "qa-execute" ||
+            spec.execution?.workflow !== outcome.workflow)
+            return false;
+    }
+    return true;
+}
+/**
+ * Delivery and Closeout revalidate that each bundle outcome still names the
+ * current canonical Done state for its Feature task. This prevents a
+ * historical successful run from remaining deliverable after a retry or state
+ * transition selected a different run.
+ */
+export async function verifyBundleCurrentStateBindings(repoRoot, bundle) {
+    try {
+        const states = await readFeatureTaskPoolStates(repoRoot, bundle.featureId);
+        const taskIds = new Set();
+        for (const outcome of [...bundle.backendTests, ...bundle.frontendTests]) {
+            if (taskIds.has(outcome.taskId))
+                return false;
+            taskIds.add(outcome.taskId);
+            const state = states[outcome.taskId];
+            if (state?.featureId !== bundle.featureId ||
+                state.status !== "Done" ||
+                state.workerRunId !== outcome.workerRunId)
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function verifyArtifactRefs(repoRoot, artifacts) {
+    let canonicalRepoRoot;
+    try {
+        canonicalRepoRoot = await realpath(repoRoot);
+    }
+    catch {
+        return false;
+    }
+    for (const artifact of artifacts) {
+        if (path.isAbsolute(artifact.path))
+            return false;
+        const lexical = path.resolve(canonicalRepoRoot, artifact.path);
+        let resolved;
+        let content;
+        try {
+            resolved = await realpath(lexical);
+            content = await readFile(resolved);
+        }
+        catch {
+            return false;
+        }
+        const relative = path.relative(canonicalRepoRoot, resolved);
+        if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+            return false;
+        if (createHash("sha256").update(content).digest("hex") !== artifact.sha256)
+            return false;
+    }
+    return true;
+}
+/** Assert the clean-HEAD invariant required before building/consuming a bundle. */
+export async function assertBundleCleanHead(repoRoot, featureId, expectedHeadSha, deps = {}) {
+    const record = await (deps.readGitRecord ?? readGitRecord)(repoRoot, featureId);
+    if (!record) {
+        throw new Error("Feature Git transaction record is missing or invalid");
+    }
+    const git = deps.git ?? defaultGit;
+    const branch = await git(repoRoot, ["branch", "--show-current"]);
+    const headSha = await git(repoRoot, ["rev-parse", "HEAD"]);
+    const status = await git(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]);
+    if (branch !== record.branch) {
+        throw new Error(`verification bundle requires the recorded Feature branch: ${record.branch}`);
+    }
+    if (headSha !== record.lastCheckpoint) {
+        throw new Error("verification bundle requires the HEAD at the recorded last checkpoint");
+    }
+    if (headSha !== expectedHeadSha) {
+        throw new Error("verification bundle headSha does not match the Delivery HEAD");
+    }
+    if (status.trim()) {
+        throw new Error(`verification bundle requires a clean worktree:\n${status.trim()}`);
+    }
+}
+async function readGitRecord(repoRoot, featureId) {
+    try {
+        return gitTransactionRecordSchema.parse(JSON.parse(await readFile(transactionRecordPath(repoRoot, featureId), "utf-8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function defaultGit(repoRoot, args) {
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const execFileAsync = promisify(execFile);
+    return (await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8" })).stdout.trim();
+}
+// Re-export the workflow schema so consumers can validate typed workflows.
+export { workflowSchema };