@deftai/directive-core 0.104.0 → 0.105.0

package/dist/product-first-done-gate/evaluate.js

@@ -10,19 +10,126 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, isAbsolute, relative, resolve } from "node:path";
 import { emitAcceptanceStampFromPlan } from "../intake/clause-derivation.js";
-import { evaluateLiteralAcceptanceFromPlan, runLiteralAcceptanceCommands, } from "../literal-acceptance/index.js";
+import { appendLiteralAcceptanceAdvisory, evaluateLiteralAcceptanceFromPlan, isNoopRefusalReason, runLiteralAcceptanceCommands, stripLiteralAcceptanceAdvisory, } from "../literal-acceptance/index.js";
 import { ENV_RUN_SUMMARY_PATH, RunSummaryEmitter, } from "../run-summary/index.js";
 import { maybeBankOnAcPass } from "../session/ac-pass-banking.js";
+import { resolveAcReuse, resolveScopeIdForAcReuse, snapshotFromReuseFields, } from "../session/ac-pass-reuse.js";
+import { hashProductState } from "../session/product-state-hash.js";
+import { resolveVerifyAcSessionId, writeVerifyAcSessionCache, } from "../session/verify-ac-session-cache.js";
 import { formatClauseWalkMessage, walkAcceptanceClauses, } from "../verify-ac/clauses.js";
 import { emitVerifyAcAttempts, evaluateProductOracleIntegrity, mergeOracleVerdict, } from "../verify-ac/evaluate.js";
 import { readPlanAcceptance, validatePlanAcceptance } from "./acceptance.js";
-import { formatSoftEmptyMessage, isEmptyAcResolution, projectHasSuiteFloor, } from "./empty-resolution.js";
+import { clauseWalkBlocks, formatAcceptanceVerdict, resolveAcceptanceVerdict, } from "./acceptance-resolver.js";
+import { formatSoftEmptyMessage, formatTranscriptEmptyMessage, isEmptyAcResolution, projectHasSuiteFloor, } from "./empty-resolution.js";
 function asRecord(value) {
     if (typeof value === "object" && value !== null && !Array.isArray(value)) {
         return value;
     }
     return null;
 }
+function tryReuseVerifyAc(plan, acceptance, options, projectRoot) {
+    const mode = options.reuseMode ?? "auto";
+    if (mode === "never")
+        return null;
+    const reuse = resolveAcReuse({
+        projectRoot,
+        plan,
+        scopeId: options.bankScopeId,
+        sessionId: options.sessionId,
+        env: options.env,
+        productPaths: options.productPaths,
+        allowCache: mode === "auto",
+        allowBank: true,
+    });
+    if (reuse.kind === "miss")
+        return null;
+    if (reuse.kind === "cache") {
+        const snap = reuse.cache.snapshot;
+        const cachedAcceptance = readPlanAcceptance({ acceptance: snap.acceptance });
+        return {
+            ok: snap.ok,
+            code: snap.code,
+            message: options.quiet
+                ? ""
+                : snap.message.includes("served_from=")
+                    ? snap.message
+                    : `${snap.message} served_from=cache`,
+            commands: snap.commands,
+            runs: snap.runs,
+            rejected: snap.rejected,
+            sourceRung: acceptance.source_rung,
+            noneStated: acceptance.none_stated,
+            acceptance: cachedAcceptance.commands.length > 0 ? cachedAcceptance : acceptance,
+            resolution: "verified-pass",
+            resolvedCommandCount: snap.resolvedCommandCount,
+            servedFrom: "cache",
+        };
+    }
+    const commandCount = acceptance.commands.length;
+    if (commandCount === 0)
+        return null;
+    return {
+        ok: true,
+        code: 0,
+        message: options.quiet
+            ? ""
+            : `verify:ac passed (#3284) served_from=bank [rung=${acceptance.source_rung}]`,
+        commands: acceptance.commands.map((c) => ({
+            command: c.command,
+            cwd: c.cwd ?? null,
+            expectedStdout: c.expectedStdout ?? null,
+            expectedExitCode: c.expectedExitCode ?? 0,
+            source: "explicit",
+            sourceSpan: "plan.acceptance.commands",
+        })),
+        runs: [],
+        sourceRung: acceptance.source_rung,
+        noneStated: acceptance.none_stated,
+        acceptance,
+        resolution: "verified-pass",
+        resolvedCommandCount: commandCount,
+        servedFrom: "bank",
+    };
+}
+function persistVerifyAcSessionCache(result, options, projectRoot, plan) {
+    if (!result.ok || result.resolution !== "verified-pass")
+        return;
+    const sessionId = resolveVerifyAcSessionId(options.env, options.sessionId);
+    const resolvedScope = resolveScopeIdForAcReuse(plan, options.bankScopeId);
+    if (sessionId === null || resolvedScope === null)
+        return;
+    const hashed = hashProductState({
+        projectRoot,
+        plan,
+        productPaths: options.productPaths,
+    });
+    if (!hashed.complete)
+        return;
+    try {
+        writeVerifyAcSessionCache({
+            projectRoot,
+            sessionId,
+            scopeId: resolvedScope,
+            productStateHash: hashed.digest,
+            snapshot: snapshotFromReuseFields({
+                ok: result.ok,
+                code: result.code === 2 ? 2 : result.code === 1 ? 1 : 0,
+                message: result.message,
+                commands: result.commands,
+                runs: result.runs,
+                rejected: result.rejected,
+                sourceRung: result.sourceRung,
+                noneStated: result.noneStated,
+                acceptance: result.acceptance,
+                resolution: result.resolution,
+                resolvedCommandCount: result.resolvedCommandCount,
+            }),
+        });
+    }
+    catch {
+        // fail-open: missing cache must not fail a green run
+    }
+}
 /**
  * Evaluate product AC from an in-memory plan.
  */
@@ -31,26 +138,34 @@ export function evaluateVerifyAcFromPlan(plan, options = {}) {
     const optionsWithScope = {
         ...options,
         oracleScopeKey: options.oracleScopeKey?.trim() || planId || null,
+        bankScopeId: options.bankScopeId?.trim() || planId || options.bankScopeId,
         observedAcceptance: options.observedAcceptance !== undefined ? options.observedAcceptance : plan.acceptance,
     };
     const acceptance = readPlanAcceptance(plan);
     const schemaErrors = validatePlanAcceptance(plan.acceptance ?? acceptance);
     // Only hard-fail schema when an explicit plan.acceptance object exists.
     if (plan.acceptance !== undefined && schemaErrors.length > 0) {
+        const noop = schemaErrors.some((error) => isNoopRefusalReason(error));
         return applyOracle({
             ok: false,
-            code: 2,
-            message: `verify:ac config error (#3284): ${schemaErrors.join("; ")}`,
+            code: noop ? 1 : 2,
+            message: noop
+                ? `verify:ac rejected-noop (#3396): ${schemaErrors.join("; ")}`
+                : `verify:ac config error (#3284): ${schemaErrors.join("; ")}`,
             commands: [],
             runs: [],
             sourceRung: acceptance.source_rung,
             noneStated: acceptance.none_stated,
             acceptance,
-            resolution: "config",
+            resolution: noop ? "rejected-noop" : "config",
             resolvedCommandCount: 0,
-        }, optionsWithScope);
+        }, optionsWithScope, plan);
     }
     const projectRoot = resolve(optionsWithScope.projectRoot ?? process.cwd());
+    const reused = tryReuseVerifyAc(plan, acceptance, optionsWithScope, projectRoot);
+    if (reused !== null) {
+        return applyOracle(reused, optionsWithScope, plan);
+    }
     // Prefer shared literal-acceptance path so safety / promotion rules stay one place.
     // Empty plan.acceptance.commands still consults the #3267 rejected ledger
     // (Greptile P1: rejected stated AC must never soft-pass).
@@ -66,12 +181,12 @@ export function evaluateVerifyAcFromPlan(plan, options = {}) {
             (optionsWithScope.checkIntegrated === true ? false : undefined),
         quiet: optionsWithScope.quiet,
     });
-    // When literal path had nothing executable but plan.acceptance has derived commands,
-    // run them directly with source=explicit semantics.
-    if (base.ok &&
-        base.runs.length === 0 &&
-        acceptance.commands.length > 0 &&
-        (acceptance.source_rung === "derived" || acceptance.source_rung === "project_floor")) {
+    // When the literal ledger produced no runs, execute non-empty plan.acceptance.commands
+    // as source=explicit. The documented key is plan.acceptance.commands (#3284 / #3449);
+    // the #3267 ledger is a parallel store and can be empty while stated commands exist.
+    // Stated was previously excluded, so rung=stated + empty ledger printed "nothing to run".
+    // Do not override a blocking rejected ledger or a config error.
+    if (shouldRunPlanAcceptanceDirectly(base, acceptance)) {
         const runner = optionsWithScope.runner;
         const direct = runLiteralAcceptanceCommands(acceptance.commands.map((c) => ({
             command: c.command,
@@ -85,7 +200,17 @@ export function evaluateVerifyAcFromPlan(plan, options = {}) {
             runner,
             allowTaskStatement: optionsWithScope.allowTaskStatement,
         });
-        return applyOracle(annotate(direct, acceptance, optionsWithScope.quiet), optionsWithScope);
+        // Carry the #3484 demotion forward: the direct path replaces `base`, and the
+        // advisory ledger must stay visible (reported, never blocking) (#3497).
+        const advisory = base.advisoryRejected ?? [];
+        const directWithAdvisory = {
+            ...direct,
+            advisoryRejected: advisory,
+            message: optionsWithScope.quiet === true
+                ? direct.message
+                : appendLiteralAcceptanceAdvisory(direct.message, advisory),
+        };
+        return applyOracle(annotate(directWithAdvisory, acceptance, optionsWithScope.quiet), optionsWithScope, plan);
     }
     // Check composition: mid-story unpromoted capture-only may soft-pass so the
     // framework graph is not deadlocked before agents promote peers.
@@ -94,7 +219,7 @@ export function evaluateVerifyAcFromPlan(plan, options = {}) {
     if (optionsWithScope.checkIntegrated === true && !base.ok && base.runs.length === 0) {
         const hasRejected = (base.rejected?.length ?? 0) > 0;
         if (hasRejected) {
-            return applyOracle(annotate(base, acceptance, optionsWithScope.quiet), optionsWithScope);
+            return applyOracle(annotate(base, acceptance, optionsWithScope.quiet), optionsWithScope, plan);
         }
         const unpromoted = /capture-only|task_statement|no matching agent-promoted/i.test(base.message) ||
             (base.commands.length > 0 && base.commands.every((c) => c.source === "task_statement"));
@@ -122,10 +247,21 @@ export function evaluateVerifyAcFromPlan(plan, options = {}) {
                     rejectedCount: base.rejected?.length ?? 0,
                 }),
                 resolvedCommandCount: base.commands.length,
-            }, optionsWithScope);
+            }, optionsWithScope, plan);
         }
     }
-    return applyOracle(annotate(base, acceptance, optionsWithScope.quiet), optionsWithScope);
+    return applyOracle(annotate(base, acceptance, optionsWithScope.quiet), optionsWithScope, plan);
+}
+function shouldRunPlanAcceptanceDirectly(base, acceptance) {
+    if (acceptance.commands.length === 0)
+        return false;
+    if (base.runs.length > 0)
+        return false;
+    if (base.code === 2)
+        return false;
+    if ((base.rejected?.length ?? 0) > 0)
+        return false;
+    return true;
 }
 function classifyResolution(input) {
     if (input.resolution !== undefined) {
@@ -158,6 +294,17 @@ function applyEmptyFloorPolicy(result, options) {
     }
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
     const suiteFloor = options.hasSuiteFloor ?? projectHasSuiteFloor(projectRoot);
+    const skippedPrompts = result.transcriptPromptSkipped ?? 0;
+    if (suiteFloor && skippedPrompts > 0) {
+        return {
+            ...result,
+            ok: false,
+            code: 1,
+            message: options.quiet === true ? "" : formatTranscriptEmptyMessage(result.acceptance),
+            resolution: "fail",
+            resolvedCommandCount: 0,
+        };
+    }
     if (suiteFloor) {
         return {
             ...result,
@@ -185,6 +332,8 @@ function acceptanceOutcomeOf(result) {
         return "fail";
     if (result.resolution === "config")
         return "config-error";
+    if (result.resolution === "rejected-noop")
+        return "rejected-noop";
     return "soft-missing";
 }
 function emitAcceptanceObservedStamp(options, projectRoot) {
@@ -208,9 +357,9 @@ function emitAcceptanceOutcome(result, options, projectRoot) {
     try {
         const emitter = new RunSummaryEmitter({
             projectRoot,
-            sessionId: (typeof options.env.DEFT_SESSION_ID === "string" && options.env.DEFT_SESSION_ID.trim()) ||
-                "verify-ac",
+            sessionId: options.sessionId,
             env: options.env,
+            component: "verify-ac",
         });
         emitter.emitAcceptance({
             resolved_command_count: result.resolvedCommandCount,
@@ -222,6 +371,7 @@ function emitAcceptanceOutcome(result, options, projectRoot) {
                 id: row.id,
                 outcome: row.outcome,
             })),
+            served_from: result.servedFrom ?? "executed",
         });
     }
     catch {
@@ -239,8 +389,14 @@ function emitAcceptanceTelemetry(result, options, projectRoot) {
  */
 export function emitVerifyAcTerminalOutcome(input) {
     emitAcceptanceOutcome({
-        ok: input.outcome !== "config-error" && input.outcome !== "fail",
-        code: input.outcome === "config-error" ? 2 : input.outcome === "fail" ? 1 : 0,
+        ok: input.outcome !== "config-error" &&
+            input.outcome !== "fail" &&
+            input.outcome !== "rejected-noop",
+        code: input.outcome === "config-error"
+            ? 2
+            : input.outcome === "fail" || input.outcome === "rejected-noop"
+                ? 1
+                : 0,
         message: "",
         commands: [],
         runs: [],
@@ -257,11 +413,13 @@ export function emitVerifyAcTerminalOutcome(input) {
                 ? "skipped"
                 : input.outcome === "fail"
                     ? "fail"
-                    : input.outcome === "soft_empty"
-                        ? "soft_empty"
-                        : input.outcome === "verified-pass"
-                            ? "verified-pass"
-                            : "empty-pass",
+                    : input.outcome === "rejected-noop"
+                        ? "rejected-noop"
+                        : input.outcome === "soft_empty"
+                            ? "soft_empty"
+                            : input.outcome === "verified-pass"
+                                ? "verified-pass"
+                                : "empty-pass",
         resolvedCommandCount: 0,
     }, { projectRoot: input.projectRoot, env: input.env }, resolve(input.projectRoot));
 }
@@ -273,7 +431,16 @@ function applyClauseWalk(result, options) {
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
     const report = walkAcceptanceClauses(clauses, projectRoot);
     const message = options.quiet ? result.message : formatClauseWalkMessage(report, result.message);
-    const ok = result.ok && report.ok;
+    // #3497: a clause the static walk cannot decide is evidence of nothing. It blocks
+    // only when nothing else verified the product; a green executable acceptance run
+    // already is the product-first oracle. Failed clauses still block unconditionally.
+    const blocked = clauseWalkBlocks({
+        failed: report.failed.length,
+        verified: report.verified.length,
+        walked: report.clauses.length,
+        hasGreenExecutableRun: result.ok && result.runs.length > 0 && result.runs.every((run) => run.ok),
+    });
+    const ok = result.ok && !blocked;
     return {
         ...result,
         ok,
@@ -288,9 +455,49 @@ function applyClauseWalk(result, options) {
         clauseWalked: true,
     };
 }
-function applyOracle(result, options) {
+function applyRejectedNoop(result) {
+    if (result.resolution === "rejected-noop") {
+        return result;
+    }
+    const rejected = result.rejected ?? [];
+    const fromLedger = rejected.some((row) => isNoopRefusalReason(row.reason));
+    const fromRuns = result.runs.some((row) => !row.ok && isNoopRefusalReason(row.detail.replace(/^refused:\s*/i, "")));
+    // #3484 / #3497: the advisory block quotes refusal reasons that were deliberately
+    // demoted because the plan states structured acceptance commands. Sniffing the
+    // rendered message resurrected them as a blocking no-op verdict — verify:ac
+    // refused while its own output said "do NOT block". Read the blocking ledgers,
+    // and inspect only the non-advisory part of the message.
+    const fromMessage = isNoopRefusalReason(stripLiteralAcceptanceAdvisory(result.message));
+    if (!fromLedger && !fromRuns && !fromMessage) {
+        return result;
+    }
+    return {
+        ...result,
+        ok: false,
+        code: result.code === 2 ? 2 : 1,
+        resolution: "rejected-noop",
+    };
+}
+/**
+ * Make the rendered message agree with the verdict (#3497).
+ *
+ * `annotate` stamps "verify:ac passed" from the sub-gate result, but later stages
+ * (clause walk, no-op ledger, oracle integrity) can still flip `ok`. The old output
+ * left the stale "passed" lead in place, so scope:complete printed four passing lines
+ * and then refused. Re-label the lead and name the deciding predicate.
+ */
+function labelVerdict(result) {
+    const verdict = resolveAcceptanceVerdict(result);
+    if (verdict.ok) {
+        return result.message;
+    }
+    const relabelled = result.message.replace(/verify:ac passed \(#3284\)/g, "verify:ac FAILED (#3284)");
+    const line = formatAcceptanceVerdict(verdict);
+    return relabelled.length > 0 ? `${relabelled}\n${line}` : line;
+}
+function applyOracle(result, options, plan = {}) {
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
-    const walked = applyClauseWalk(result, options);
+    const walked = applyClauseWalk(applyRejectedNoop(result), options);
     const gated = walked.clauseWalked === true ? walked : applyEmptyFloorPolicy(walked, options);
     // Emit/read disk only when the caller supplied env (CLI passes process.env).
     // Tests stay isolated unless they opt in with env or runSummaryText.
@@ -310,14 +517,23 @@ function applyOracle(result, options) {
             env: options.env,
         });
         next = mergeOracleVerdict(gated, verdict);
-        if (!verdict.ok && next.resolution !== "soft_empty" && next.resolution !== "config") {
+        if (!verdict.ok &&
+            next.resolution !== "soft_empty" &&
+            next.resolution !== "config" &&
+            next.resolution !== "rejected-noop") {
             next = { ...next, resolution: "fail" };
         }
     }
+    const stamped = {
+        ...next,
+        message: options.quiet === true ? next.message : labelVerdict(next),
+        servedFrom: next.servedFrom ?? "executed",
+    };
+    persistVerifyAcSessionCache(stamped, options, projectRoot, plan);
     if (options.skipAcceptanceEmit !== true) {
-        emitAcceptanceTelemetry(next, options, projectRoot);
+        emitAcceptanceTelemetry(stamped, options, projectRoot);
     }
-    return next;
+    return stamped;
 }
 function annotate(result, acceptance, quiet) {
     const prefix = result.ok
@@ -353,6 +569,7 @@ function annotate(result, acceptance, quiet) {
             rejectedCount: result.rejected?.length ?? 0,
         }),
         resolvedCommandCount: result.runs.length > 0 ? result.runs.length : commandCount,
+        servedFrom: "executed",
     };
 }
 /**
@@ -435,11 +652,17 @@ function maybeAttachAcPassBank(result, plan, xbriefPath, options) {
             .replace(/\.xbrief\.json$/i, "")
             .replace(/\.vbrief\.json$/i, "");
     try {
+        const hashed = hashProductState({
+            projectRoot,
+            plan,
+            productPaths: options.productPaths,
+        });
         const banked = maybeBankOnAcPass({
             projectRoot,
             scopeId,
             executableRuns: result.runs.length,
             quiet: options.quiet,
+            productStateHash: hashed.complete ? hashed.digest : null,
         });
         if (options.quiet || banked.notes.length === 0) {
             return result;

package/dist/product-first-done-gate/index.d.ts

@@ -4,7 +4,9 @@
  * acceptance.commands schema, verify:ac evaluation, check-mode composition
  * (AC-first, hygiene advisory under pressure, rapid=AC-only).
  */
+export type { AcServedFrom } from "../session/verify-ac-session-cache.js";
 export { attachPlanAcceptance, buildAcceptanceFromIntakeCapture, readPlanAcceptance, stampAcceptanceFromLiteralCapture, validatePlanAcceptance, } from "./acceptance.js";
+export { type AcceptanceGateProfileOptions, type AcceptancePredicate, type AcceptanceReaderProfile, type AcceptanceReading, type AcceptanceVerdict, clauseWalkBlocks, formatAcceptanceVerdict, resolveAcceptanceGateProfile, resolveAcceptanceVerdict, resolvedAcceptanceCommandCount, } from "./acceptance-resolver.js";
 export { applyProductFirstGateMode, isHygieneGate, isProductAcGate, type ProductFirstCheckModeResolution, type ResolveProductFirstCheckModeInput, resolveProductFirstCheckMode, } from "./check-mode.js";
 export { EMPTY_AC_CAUSE, EMPTY_AC_OUTCOME, EMPTY_AC_REMEDY, formatSoftEmptyMessage, isEmptyAcResolution, isSoftEmptyAcText, projectHasSuiteFloor, type VerifyAcResolution, } from "./empty-resolution.js";
 export { type EvaluateVerifyAcOptions, emitVerifyAcTerminalOutcome, evaluateVerifyAcFromPath, evaluateVerifyAcFromPlan, isVerifyAcRequiredAtCeremonyDepth, resolveOracleScopeKey, type VerifyAcResult, } from "./evaluate.js";

package/dist/product-first-done-gate/index.js

@@ -5,6 +5,7 @@
  * (AC-first, hygiene advisory under pressure, rapid=AC-only).
  */
 export { attachPlanAcceptance, buildAcceptanceFromIntakeCapture, readPlanAcceptance, stampAcceptanceFromLiteralCapture, validatePlanAcceptance, } from "./acceptance.js";
+export { clauseWalkBlocks, formatAcceptanceVerdict, resolveAcceptanceGateProfile, resolveAcceptanceVerdict, resolvedAcceptanceCommandCount, } from "./acceptance-resolver.js";
 export { applyProductFirstGateMode, isHygieneGate, isProductAcGate, resolveProductFirstCheckMode, } from "./check-mode.js";
 export { EMPTY_AC_CAUSE, EMPTY_AC_OUTCOME, EMPTY_AC_REMEDY, formatSoftEmptyMessage, isEmptyAcResolution, isSoftEmptyAcText, projectHasSuiteFloor, } from "./empty-resolution.js";
 export { emitVerifyAcTerminalOutcome, evaluateVerifyAcFromPath, evaluateVerifyAcFromPlan, isVerifyAcRequiredAtCeremonyDepth, resolveOracleScopeKey, } from "./evaluate.js";

package/dist/release/build-dist.d.ts

@@ -1,7 +1,104 @@
+import { lstatSync } from "node:fs";
+/**
+ * Shared "not product source" core (#3487) plus the coverage artifacts only the
+ * release archive names. Scratch and agent worktrees are never shippable
+ * framework content (#2953). The archive set is git-tracked files (#3490); this
+ * denylist is defence in depth, including for a tracked path under a core name.
+ *
+ * Callers may still widen this per run via `extraExcludes` / `--exclude-extra`.
+ */
 export declare const DEFAULT_EXCLUDES: Set<string>;
 export declare const DEFAULT_EXCLUDED_PATH_PREFIXES: readonly ["history/archive", "vbrief/completed", "vbrief/cancelled"];
+/**
+ * Generated outputs that may be packed even when untracked. Empty by default:
+ * the release archive is a source distribution, so extra outputs must be named
+ * explicitly (#3490).
+ */
+export declare const DEFAULT_GENERATED_ALLOWLIST: readonly string[];
 export declare const ARCHIVE_ROOT = "deft";
 export declare const CONTENT_PREFIX = "content/";
+/** Raised when the resolved archive set contains an untracked surprise (#3490). */
+export declare class UntrackedArchiveEntryError extends Error {
+    readonly paths: readonly string[];
+    constructor(paths: readonly string[]);
+}
+export type ArchiveSourceEntry = {
+    absPath: string | Buffer;
+    archiveRel: string;
+    archiveRelBytes: Buffer;
+};
+/** Private-use mark so archiver's string `name` can carry raw member bytes. */
+export declare const ARCHIVE_BINARY_NAME_MARK = "\uF000";
+export declare function flattenContentPrefixBytes(relBytes: Buffer): Buffer;
+export declare function isValidUtf8Buffer(buf: Buffer): boolean;
+export declare function archiveMemberBytes(archiveRelBytes: Buffer): Buffer;
+/** Archiver `file()`/`append` name: UTF-8 text, or marked latin1 of raw bytes. */
+export declare function archiverEntryName(memberBytes: Buffer): string;
+/** Original `ls-files -z` segment bytes plus the display/skip string. */
+export type GitLsFilesPath = {
+    readonly relPosix: string;
+    readonly bytes: Buffer;
+};
+export type ArchiveFsLookup = {
+    realpathSync: (path: string | Buffer, options?: {
+        encoding?: BufferEncoding | "buffer" | null;
+    }) => string | Buffer;
+    lstatSync: (path: string | Buffer) => ReturnType<typeof lstatSync>;
+};
+/** `-z` stdout is a NUL-separated byte stream; never UTF-8-decode it whole. */
+export declare const GIT_LS_FILES_Z_ENCODING: null;
+export type GitLsFilesZSpawn = (command: string, args: readonly string[], options: {
+    encoding: null;
+    timeout?: number;
+    maxBuffer?: number;
+    stdio?: readonly ["ignore", "pipe", "pipe"];
+}) => {
+    status: number | null;
+    stdout?: Buffer | string | null;
+    stderr?: Buffer | string | null;
+    error?: Error | null;
+    signal?: NodeJS.Signals | null;
+};
+/** Decode one `ls-files -z` segment; keep non-UTF-8 bytes as latin1. */
+export declare function decodeGitLsFilesPath(segment: Buffer): string;
+/** Split a raw `git ls-files -z` Buffer on 0x00, keeping original path bytes. */
+export declare function splitGitLsFilesZRecords(stdout: Buffer): GitLsFilesPath[];
+/** Split a raw `git ls-files -z` Buffer on 0x00, then decode each path. */
+export declare function splitGitLsFilesZ(stdout: Buffer): string[];
+/**
+ * Return `git ls-files -z` paths with original bytes. Fail closed when git
+ * cannot enumerate tracked files -- a walk would pack host-local untracked
+ * state (#3490).
+ */
+export declare function listGitTrackedPathRecords(root: string, spawn?: GitLsFilesZSpawn): GitLsFilesPath[];
+/** Return `git ls-files -z` paths in POSIX form. */
+export declare function listGitTrackedFiles(root: string, spawn?: GitLsFilesZSpawn): string[];
+/**
+ * Fail closed when any resolved archive path is untracked and not on the
+ * generated-output allowlist (#3490).
+ */
+export declare function assertArchiveEntriesTrackedOrGenerated(root: string, rels: readonly string[], generatedAllowlist?: readonly string[], spawn?: GitLsFilesZSpawn): void;
+export type ResolveArchiveEntriesOptions = {
+    readonly extraExcludes?: readonly string[];
+    readonly excludedPrefixes?: readonly string[];
+    readonly generatedAllowlist?: readonly string[];
+    readonly spawn?: GitLsFilesZSpawn;
+    readonly fs?: ArchiveFsLookup;
+};
+/** Join canonical root bytes with original git path bytes; convert POSIX `/` to OS sep. */
+export declare function joinRootAndRelBytes(rootBytes: Buffer, relBytes: Buffer): Buffer;
+/**
+ * String path when the `-z` segment is valid UTF-8; otherwise a Buffer that
+ * keeps the original filename bytes for fs lookup (#3490 residual).
+ */
+export declare function fsLookupPath(root: string, relPosix: string, bytes: Buffer, rootBytes?: Buffer): string | Buffer | null;
+/** Resolve a POSIX rel path under root, or null if it escapes (#3490 review). */
+export declare function containedAbsPath(root: string, relPosix: string): string | null;
+/**
+ * Derive the archive file set from git-tracked paths plus an explicit
+ * generated-output allowlist. The basename denylist remains defence in depth.
+ */
+export declare function resolveArchiveEntries(root: string, options?: ResolveArchiveEntriesOptions): ArchiveSourceEntry[];
 export declare function iterSourceFiles(root: string, excludes?: ReadonlySet<string>, excludedPrefixes?: readonly string[]): Array<{
     absPath: string;
     archiveRel: string;
@@ -16,8 +113,12 @@ export type BuildProgress = {
 };
 export type BuildArchiveOptions = {
     readonly extraExcludes?: readonly string[];
+    /** Untracked generated outputs that may be packed (#3490). */
+    readonly generatedAllowlist?: readonly string[];
     /** Progress sink; default silent so unit tests stay quiet (#2953). */
     readonly onProgress?: (p: BuildProgress) => void;
+    readonly spawn?: GitLsFilesZSpawn;
+    readonly fs?: ArchiveFsLookup;
 };
 /**
  * Emit human-readable stage progress for long release packaging runs (#2953).