audit-tools 0.30.4 → 0.30.5

package/dist/audit/contracts/schemaEnforcedEmit.d.ts

@@ -0,0 +1,75 @@
+import type { z } from "zod";
+import { type BrokeredRepairDispatch, type BrokerDispatchInput, type RepairContract, type RepairOutcome, type RepairPatcher } from "audit-tools/shared";
+import type { FreshSessionProvider, OutputConstraintCapability, OutputConstraintMode } from "audit-tools/shared";
+/**
+ * Build a {@link RepairContract} from a worker-facing zod schema. The zod schema
+ * is the ONE canonical validator (re-run after every repair stage). Errors on a
+ * field that is `optional()` in the schema map to `required: false`, so O3's
+ * stage-1 coercion is allowed to clear them by dropping the optional sub-object;
+ * everything else is `required: true`.
+ *
+ * Coercion here is intentionally a NO-OP (the schema-of-record owns no
+ * deterministic drop/backfill policy beyond zod's own parse): O3 will fall
+ * straight to its bounded LLM patch / re-dispatch stages when a REQUIRED error
+ * remains. A contract that wants deterministic coercion supplies its own.
+ */
+export declare function buildWorkerRepairContract(contractId: string, schema: z.ZodTypeAny): RepairContract;
+/** Inputs for one schema-enforced emit. */
+export interface SchemaEnforcedEmitInput {
+    /** Stable contract id (e.g. 'audit_results'). */
+    contractId: string;
+    /** The canonical worker-facing zod schema to enforce. */
+    schema: z.ZodTypeAny;
+    /** The raw worker payload emitted by the backend. */
+    payload: unknown;
+    /**
+     * The dispatching provider. Its discovered {@link OutputConstraintCapability} is
+     * READ here (never recomputed) to decide whether the emit had any structural
+     * guarantee. A provider whose descriptor is absent is treated as `none`.
+     */
+    provider: Pick<FreshSessionProvider, "outputConstraint">;
+    /** The shared F4 broker — the SOLE route for any repair LLM touch. */
+    broker: BrokeredRepairDispatch;
+    /**
+     * The broker dispatch context (provider/session/host) for the repair slot,
+     * minus the `slots` array (the emit path supplies its own single repair slot).
+     * The broker's admission decision gates whether the bounded LLM patch runs at
+     * all — an over-budget / cooled-down pool means no LLM touch.
+     */
+    brokerContext: Omit<BrokerDispatchInput, "slots">;
+    /** Artifacts dir for O3 friction capture (best-effort). */
+    artifactsDir: string;
+    /** Per-run id for friction capture keying. */
+    runId: string;
+    /** Which orchestrator is emitting (friction record `tool` field). */
+    tool?: "audit-code" | "remediate-code";
+    /**
+     * Bounded errors-only LLM patch (O3 stage-2). The PATCH ITSELF is the caller's
+     * provider call, but it is invoked from inside `runEmitValidateRepair` only
+     * after the broker has admitted the repair slot (see {@link enforceSchemaAtEmit}).
+     * Omit to skip stage-2 (coercion + re-dispatch only).
+     */
+    patcher?: RepairPatcher;
+    /** 1-based current attempt counter (default 1). */
+    attempt?: number;
+}
+/** The single result of a schema-enforced emit. */
+export interface SchemaEnforcedEmitResult {
+    /** The constraint mode actually in force for this emit (read from the provider). */
+    mode: OutputConstraintMode;
+    /** The O3 repair outcome (status, repaired payload, warnings, re-dispatch signal). */
+    repair: RepairOutcome;
+}
+/** Resolve the emit's constraint mode from the provider descriptor (absent ⟹ none). */
+export declare function resolveEmitConstraint(provider: Pick<FreshSessionProvider, "outputConstraint">): OutputConstraintCapability;
+/**
+ * Enforce the canonical worker schema at emit time, degrading through the O3
+ * emit-validate-repair seam when there is no structural guarantee or the payload
+ * fails to validate. The stage-2 LLM patch is gated by F4's broker: a single
+ * repair slot is offered to `broker.broker`, and the bounded patcher only runs if
+ * the broker admits it. A refused/cooled-down broker means no LLM touch — O3 then
+ * falls to its deterministic coercion + re-dispatch signal. The seam NEVER spawns
+ * a dispatch itself.
+ */
+export declare function enforceSchemaAtEmit(input: SchemaEnforcedEmitInput): Promise<SchemaEnforcedEmitResult>;
+//# sourceMappingURL=schemaEnforcedEmit.d.ts.map

package/dist/audit/contracts/schemaEnforcedEmit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaEnforcedEmit.d.ts","sourceRoot":"","sources":["../../../src/audit/contracts/schemaEnforcedEmit.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,CAAC,UAAU,GACnB,cAAc,CA+BhB;AAED,2CAA2C;AAC3C,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC;IACrB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,QAAQ,EAAE,IAAI,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,CAAC;IACzD,sEAAsE;IACtE,MAAM,EAAE,sBAAsB,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,EAAE,IAAI,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;IAClD,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,IAAI,CAAC,EAAE,YAAY,GAAG,gBAAgB,CAAC;IACvC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,oFAAoF;IACpF,IAAI,EAAE,oBAAoB,CAAC;IAC3B,sFAAsF;IACtF,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,uFAAuF;AACvF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,IAAI,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,GACvD,0BAA0B,CAO5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,wBAAwB,CAAC,CA4CnC"}

package/dist/audit/contracts/schemaEnforcedEmit.js

@@ -0,0 +1,131 @@
+// F3 — schema-enforced worker generation.
+//
+// This is the emit-time half of the F3 ↔ F4 ↔ O3 seam set. At emit, a worker
+// result is enforced against the canonical worker-facing zod schema
+// (`workerSchemas.ts`). The strongest available enforcement is chosen ONCE from
+// the provider's discovered `OutputConstraintCapability` (F3 ↔ F4: the descriptor
+// is read here, never recomputed):
+//
+//   - `forced_tool_call` / `json_schema_constrained` / `structured_output` — the
+//     backend already constrained its output, so the emitted payload is expected
+//     to validate; we still re-run the canonical zod validate as the single
+//     authority (defence-in-depth, no second validator).
+//   - `none` — no structural guarantee from the backend; the payload MUST go
+//     through the O3 emit-validate-repair seam to be salvaged.
+//
+// On capability `none` OR a validation failure under any mode, the payload is
+// degraded through O3's `runEmitValidateRepair`. Its bounded stage-2 LLM patch is
+// routed through F4's shared `BrokeredRepairDispatch` seam — the emit path NEVER
+// spawns a re-dispatch directly; every LLM touch flows through the single gated
+// broker chokepoint (broker-handle edge O3 ↔ F4).
+import { runEmitValidateRepair, } from "audit-tools/shared";
+/**
+ * Build a {@link RepairContract} from a worker-facing zod schema. The zod schema
+ * is the ONE canonical validator (re-run after every repair stage). Errors on a
+ * field that is `optional()` in the schema map to `required: false`, so O3's
+ * stage-1 coercion is allowed to clear them by dropping the optional sub-object;
+ * everything else is `required: true`.
+ *
+ * Coercion here is intentionally a NO-OP (the schema-of-record owns no
+ * deterministic drop/backfill policy beyond zod's own parse): O3 will fall
+ * straight to its bounded LLM patch / re-dispatch stages when a REQUIRED error
+ * remains. A contract that wants deterministic coercion supplies its own.
+ */
+export function buildWorkerRepairContract(contractId, schema) {
+    return {
+        contractId,
+        validate(payload) {
+            const parsed = schema.safeParse(payload);
+            if (parsed.success)
+                return { errors: [] };
+            const errors = parsed.error.issues.map((issue) => ({
+                path: issue.path.join("."),
+                message: issue.message,
+                // A missing required key is reported by zod as `invalid_type` with
+                // `received: "undefined"`; an `unrecognized_keys` issue is a strict()
+                // violation. Both gate escalation. Optional fields never produce a
+                // "Required" issue, so any issue zod emits here sits on a constraint
+                // the worker must satisfy → required.
+                required: true,
+            }));
+            return { errors };
+        },
+        coercion: {
+            coerce(payload) {
+                return {
+                    payload,
+                    drops: [],
+                    backfills: [],
+                    unrecoverableIdentity: false,
+                };
+            },
+        },
+    };
+}
+/** Resolve the emit's constraint mode from the provider descriptor (absent ⟹ none). */
+export function resolveEmitConstraint(provider) {
+    return (provider.outputConstraint ?? {
+        mode: "none",
+        reason: "provider exposes no discovered output-constraint capability",
+    });
+}
+/**
+ * Enforce the canonical worker schema at emit time, degrading through the O3
+ * emit-validate-repair seam when there is no structural guarantee or the payload
+ * fails to validate. The stage-2 LLM patch is gated by F4's broker: a single
+ * repair slot is offered to `broker.broker`, and the bounded patcher only runs if
+ * the broker admits it. A refused/cooled-down broker means no LLM touch — O3 then
+ * falls to its deterministic coercion + re-dispatch signal. The seam NEVER spawns
+ * a dispatch itself.
+ */
+export async function enforceSchemaAtEmit(input) {
+    const constraint = resolveEmitConstraint(input.provider);
+    const contract = buildWorkerRepairContract(input.contractId, input.schema);
+    // Gate the bounded LLM patch through the single F4 broker chokepoint. We offer
+    // exactly one repair slot sized from the payload's byte length; the patcher runs
+    // ONLY if the broker admits the slot. `awaitNextCompletion` passes the raw
+    // patched result straight back to O3's canonical validator (broker-handle edge).
+    let brokeredPatcher;
+    if (input.patcher) {
+        const slotId = `${input.contractId}:repair:${input.runId}`;
+        brokeredPatcher = async (payload, errors) => {
+            const payloadBytes = Buffer.byteLength(safeStringify(payload), "utf8");
+            const decision = input.broker.broker({
+                ...input.brokerContext,
+                slots: [{ slotId, payloadBytes }],
+            });
+            if (decision.admitted < 1 || !decision.admittedSlotIds.includes(slotId)) {
+                // Broker refused (over budget / cooldown) → no LLM touch. Return the
+                // payload unchanged so O3 falls to its deterministic re-dispatch signal.
+                return payload;
+            }
+            const patched = await input.patcher(payload, errors);
+            const { rawResult } = input.broker.awaitNextCompletion({
+                slotId,
+                rawResult: patched,
+            });
+            return rawResult;
+        };
+    }
+    const repair = await runEmitValidateRepair({
+        contract,
+        payload: input.payload,
+        artifactsDir: input.artifactsDir,
+        runId: input.runId,
+        tool: input.tool,
+        // Capability `none` keeps the patcher available (degrade path); a constrained
+        // mode still validates and only patches if the constrained output drifted.
+        patcher: brokeredPatcher,
+        attempt: input.attempt,
+    });
+    return { mode: constraint.mode, repair };
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=schemaEnforcedEmit.js.map

package/dist/audit/contracts/schemaEnforcedEmit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaEnforcedEmit.js","sourceRoot":"","sources":["../../../src/audit/contracts/schemaEnforcedEmit.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,EAAE;AACF,6EAA6E;AAC7E,oEAAoE;AACpE,gFAAgF;AAChF,kFAAkF;AAClF,mCAAmC;AACnC,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,4EAA4E;AAC5E,yDAAyD;AACzD,6EAA6E;AAC7E,+DAA+D;AAC/D,EAAE;AACF,8EAA8E;AAC9E,kFAAkF;AAClF,iFAAiF;AACjF,gFAAgF;AAChF,kDAAkD;AAGlD,OAAO,EACL,qBAAqB,GAQtB,MAAM,oBAAoB,CAAC;AAO5B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CACvC,UAAkB,EAClB,MAAoB;IAEpB,OAAO;QACL,UAAU;QACV,QAAQ,CAAC,OAAgB;YACvB,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;YAC1C,MAAM,MAAM,GAA4B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAC7D,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBACV,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;gBAC1B,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,mEAAmE;gBACnE,sEAAsE;gBACtE,mEAAmE;gBACnE,qEAAqE;gBACrE,sCAAsC;gBACtC,QAAQ,EAAE,IAAI;aACf,CAAC,CACH,CAAC;YACF,OAAO,EAAE,MAAM,EAAE,CAAC;QACpB,CAAC;QACD,QAAQ,EAAE;YACR,MAAM,CAAC,OAAgB;gBACrB,OAAO;oBACL,OAAO;oBACP,KAAK,EAAE,EAAE;oBACT,SAAS,EAAE,EAAE;oBACb,qBAAqB,EAAE,KAAK;iBAC7B,CAAC;YACJ,CAAC;SACF;KACF,CAAC;AACJ,CAAC;AAkDD,uFAAuF;AACvF,MAAM,UAAU,qBAAqB,CACnC,QAAwD;IAExD,OAAO,CACL,QAAQ,CAAC,gBAAgB,IAAI;QAC3B,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,6DAA6D;KACtE,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAA8B;IAE9B,MAAM,UAAU,GAAG,qBAAqB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,yBAAyB,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAE3E,+EAA+E;IAC/E,iFAAiF;IACjF,2EAA2E;IAC3E,iFAAiF;IACjF,IAAI,eAA0C,CAAC;IAC/C,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,GAAG,KAAK,CAAC,UAAU,WAAW,KAAK,CAAC,KAAK,EAAE,CAAC;QAC3D,eAAe,GAAG,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1C,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;YACvE,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;gBACnC,GAAG,KAAK,CAAC,aAAa;gBACtB,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;aAClC,CAAC,CAAC;YACH,IAAI,QAAQ,CAAC,QAAQ,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBACxE,qEAAqE;gBACrE,yEAAyE;gBACzE,OAAO,OAAO,CAAC;YACjB,CAAC;YACD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,OAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACtD,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,mBAAmB,CAAC;gBACrD,MAAM;gBACN,SAAS,EAAE,OAAO;aACnB,CAAC,CAAC;YACH,OAAO,SAAS,CAAC;QACnB,CAAC,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC;QACzC,QAAQ;QACR,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,8EAA8E;QAC9E,2EAA2E;QAC3E,OAAO,EAAE,eAAe;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC,CAAC;IAEH,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;AAC3C,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/audit/contracts/wrapperResponse.d.ts

@@ -103,8 +103,8 @@ export declare const AuditCodeResponseSchema: z.ZodObject<{
             runtime_validation_tasks: z.ZodNullable<z.ZodString>;
             friction_record: z.ZodString;
         }, "strict", z.ZodTypeAny, {
-            current_prompt: string | null;
             session_config: string;
+            current_prompt: string | null;
             runtime_validation_tasks: string | null;
             audit_tasks: string | null;
             incoming_dir: string;
@@ -115,8 +115,8 @@ export declare const AuditCodeResponseSchema: z.ZodObject<{
             current_tasks: string | null;
             friction_record: string;
         }, {
-            current_prompt: string | null;
             session_config: string;
+            current_prompt: string | null;
             runtime_validation_tasks: string | null;
             audit_tasks: string | null;
             incoming_dir: string;
@@ -136,8 +136,8 @@ export declare const AuditCodeResponseSchema: z.ZodObject<{
         repo_root: string;
         artifacts_dir: string;
         artifact_paths: {
-            current_prompt: string | null;
             session_config: string;
+            current_prompt: string | null;
             runtime_validation_tasks: string | null;
             audit_tasks: string | null;
             incoming_dir: string;
@@ -173,8 +173,8 @@ export declare const AuditCodeResponseSchema: z.ZodObject<{
         repo_root: string;
         artifacts_dir: string;
         artifact_paths: {
-            current_prompt: string | null;
             session_config: string;
+            current_prompt: string | null;
             runtime_validation_tasks: string | null;
             audit_tasks: string | null;
             incoming_dir: string;
@@ -230,8 +230,8 @@ export declare const AuditCodeResponseSchema: z.ZodObject<{
         repo_root: string;
         artifacts_dir: string;
         artifact_paths: {
-            current_prompt: string | null;
             session_config: string;
+            current_prompt: string | null;
             runtime_validation_tasks: string | null;
             audit_tasks: string | null;
             incoming_dir: string;
@@ -287,8 +287,8 @@ export declare const AuditCodeResponseSchema: z.ZodObject<{
         repo_root: string;
         artifacts_dir: string;
         artifact_paths: {
-            current_prompt: string | null;
             session_config: string;
+            current_prompt: string | null;
             runtime_validation_tasks: string | null;
             audit_tasks: string | null;
             incoming_dir: string;

package/dist/audit/extractors/analyzers/acquisitionEngine.d.ts

@@ -0,0 +1,140 @@
+import { type AnalyzerSetting, type RunTrackedResult } from "audit-tools/shared";
+import type { ExternalAnalyzerResults, ExternalAnalyzerToolStatus } from "../../types/externalAnalyzer.js";
+/**
+ * F5 — external analyzer acquisition engine.
+ *
+ * On-demand acquisition + ephemeral execution of mature, ecosystem-native
+ * analyzers (eslint, ruff, cargo-clippy, …). Distinct from the in-tree
+ * `LanguageAnalyzer` registry (which enriches the regex floor from a resolved
+ * npm package directory): F5 *runs an external tool as a subprocess* and
+ * normalizes its native output through the EXISTING adapter seam
+ * (`normalizeExternal.ts`) into {@link ExternalAnalyzerResults}, which then
+ * re-enters the graph/risk artifacts through the shared
+ * CCU-analyzer-merge-helper-seam pair.
+ *
+ * Design invariants (all enforced here, never by host discretion):
+ *  - **No baked-in language→tool / OS→runner table.** Ecosystem is detected
+ *    deterministically from repo marker files; the runner (npx/pipx/cargo/bundle)
+ *    is capability-probed at RUNTIME (`--version`) before any tool spawn.
+ *  - **Single subprocess-SPAWN admission chokepoint** (`admitSpawn`): EVERY
+ *    non-DEFAULT candidate is gated on the per-run consent token regardless of
+ *    its `AnalyzerSetting` (auto|ephemeral|permanent) — even a `permanent`,
+ *    pre-installed tool cannot spawn without consent (CE-005). The small
+ *    value-curated DEFAULT set runs without prompting.
+ *  - **Own-vs-acquire boundary.** git-history / secret-scan are OWNED by F6 and
+ *    are rejected at registration — never acquired here.
+ *  - **Run-safety gate written once** (`runSafetyGate`): capability-probe, pin
+ *    version, read-only/sandboxed argv, degrade-to-empty.
+ *  - **Degrade-to-empty + report-skipped-never-silently.** Every candidate
+ *    yields exactly one {@link ExternalAnalyzerToolStatus}; a failure never
+ *    throws and never silently drops the candidate.
+ */
+/** Tool ids OWNED by F6 (git-history mining / secret scanning). Never acquired. */
+export declare const OWNED_TOOL_IDS: Set<string>;
+/** Ecosystem runners F5 knows how to drive. */
+export type EcosystemRunner = "npx" | "pipx" | "cargo" | "bundle";
+/**
+ * One acquirable external analyzer. `defaultRun: true` marks a member of the
+ * small value-curated set that may run without a consent token; everything else
+ * is gated on the per-run consent token at the spawn chokepoint.
+ */
+export interface ExternalAnalyzerCandidate {
+    /** Stable id; also the `analyzers.<id>` session-config key. */
+    id: string;
+    /** Runner that acquires + executes the tool ephemerally. */
+    runner: EcosystemRunner;
+    /** Pinned tool spec, e.g. "eslint@9" / "ruff==0.5.0" (pinned for reproducibility). */
+    spec: string;
+    /**
+     * Build the read-only argv for the tool given the resolved runner argv prefix
+     * and repo root. MUST NOT request fixes/writes — F5 is observe-only.
+     */
+    buildArgv(runnerPrefix: string[], root: string): string[];
+    /**
+     * Parse the tool's stdout into the generic item shape consumed by
+     * `normalizeGenericExternalResults`. Degrades to `[]` on any parse failure.
+     */
+    parse(stdout: string): Array<{
+        id?: string;
+        category?: string;
+        severity?: string;
+        path?: string;
+        line_start?: number;
+        line_end?: number;
+        summary?: string;
+        rule?: string;
+        raw?: unknown;
+        from?: unknown;
+        to?: unknown;
+    }>;
+    /** Whether this ecosystem is present (marker file detection). */
+    detect(root: string): boolean;
+    /** Member of the value-curated DEFAULT set (runs without prompting). */
+    defaultRun: boolean;
+}
+export declare function detectNodeEcosystem(root: string): boolean;
+export declare function detectPythonEcosystem(root: string): boolean;
+export declare function detectRustEcosystem(root: string): boolean;
+export declare function detectRubyEcosystem(root: string): boolean;
+export interface AcquisitionRunner {
+    (argv: string[], cwd: string): RunTrackedResult;
+}
+export interface AcquisitionEngineOptions {
+    /**
+     * Per-run consent token. REQUIRED to spawn any non-DEFAULT candidate (and any
+     * candidate whose setting is ephemeral/permanent). Absent ⇒ only the DEFAULT
+     * set runs; everything else is reported `skipped` with a consent note.
+     */
+    consentToken?: string;
+    /** Per-analyzer settings (auto|ephemeral|permanent|skip|repo). */
+    analyzers?: Record<string, AnalyzerSetting>;
+    /** Injectable command runner; defaults to the shared runTracked. */
+    run?: AcquisitionRunner;
+    /** Injectable logger; defaults to a no-op (degrade quietly to status records). */
+    log?: (...args: unknown[]) => void;
+}
+/**
+ * Single subprocess-SPAWN admission chokepoint. Returns the reason a spawn is
+ * NOT admitted, or `undefined` when admitted. The DEFAULT set is admitted
+ * without a token; EVERY other candidate — including `permanent`/`ephemeral`
+ * pre-installed tools — requires the per-run consent token (CE-005).
+ */
+export declare function admitSpawn(candidate: ExternalAnalyzerCandidate, setting: AnalyzerSetting, consentToken: string | undefined): string | undefined;
+/**
+ * The run-safety gate, written once: capability-probe the runner, then (if the
+ * probe passes) the caller may spawn the pinned, read-only argv. Returns the
+ * probe outcome so a missing runner degrades to an empty result + a status.
+ */
+export declare function runSafetyGate(candidate: ExternalAnalyzerCandidate, run: AcquisitionRunner, root: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface AcquisitionOutcome {
+    results: ExternalAnalyzerResults;
+    status: ExternalAnalyzerToolStatus;
+}
+/**
+ * Acquire + run ONE external analyzer candidate ephemerally, normalizing its
+ * output through the adapter seam. Never throws; always returns exactly one
+ * {@link ExternalAnalyzerToolStatus} alongside the (possibly empty) results.
+ */
+export declare function runExternalAnalyzer(candidate: ExternalAnalyzerCandidate, root: string, options?: AcquisitionEngineOptions): AcquisitionOutcome;
+/**
+ * Register external analyzer candidates, rejecting any whose id is OWNED by F6
+ * (git-history/secret-scan). Returns the accepted candidates; the own-vs-acquire
+ * boundary is enforced HERE so an owned tool can never enter the engine.
+ */
+export declare function registerExternalAnalyzers(candidates: ExternalAnalyzerCandidate[]): ExternalAnalyzerCandidate[];
+export interface RunAllOutcome {
+    results: ExternalAnalyzerResults[];
+    statuses: ExternalAnalyzerToolStatus[];
+}
+/**
+ * Drive the whole registered candidate set through the engine for one repo,
+ * collecting one status per candidate. Owned tools are rejected at registration;
+ * each survivor passes through the spawn-admission chokepoint and run-safety gate.
+ */
+export declare function runAcquisitionEngine(candidates: ExternalAnalyzerCandidate[], root: string, options?: AcquisitionEngineOptions): RunAllOutcome;
+//# sourceMappingURL=acquisitionEngine.d.ts.map

package/dist/audit/extractors/analyzers/acquisitionEngine.d.ts.map

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