/**
 * PII Shield Scanner — Layers 3-5 (PR-5-1)
 *
 * Extends the existing scan.ts Layers 1-2 (tool-surface enumeration + AST
 * analysis) with three additional analysis layers:
 *
 *   Layer 3: CapabilityBundle phiHandling declaration vs reality cross-check
 *   Layer 4: Optional run-trace probe (--deep-scan flag; stubbed in PR-5-1)
 *   Layer 5: Reproducible verification pack — emit pii-shield-evidence.json
 *
 * All layers run locally. No source text leaves the customer's machine.
 * Only structured findings + the evidence pack are emitted.
 *
 * @connexum/ai-governance — PR-5-1
 */
export interface AgentManifestPhiView {
    /** Agent identifier (stable hash or supplied ID). */
    agentId: string;
    /** Relative path to the agent file. */
    filePath: string;
    /**
     * Tools declared in the agent's manifest that carry data_class === "PHI".
     * Populated by Layer 1 (tool-surface enumeration).
     */
    phiTools: string[];
    /**
     * Tools where Layer 2 AST analysis found an ungoverned tool call site
     * (i.e. the call is not wrapped by GovernedToolExecutor and has no
     * PostToolUse STRIP_AND_TAG hook on the call site).
     */
    ungoverned_tool_calls: string[];
    /**
     * The phiHandling value the agent declared in its CapabilityBundle.
     *   'tokenized'      — agent claims it tokenizes PHI via STRIP_AND_TAG
     *   'phi-prohibited' — agent claims it never touches PHI tools
     *   'raw-permitted'  — agent explicitly opts out of PHI handling governance
     *   undefined        — no declaration found
     */
    phiHandling?: 'tokenized' | 'phi-prohibited' | 'raw-permitted';
}
export type Layer3FindingCode = 'DECLARATION_MISMATCH_TOKENIZED_BUT_UNGOVERNED' | 'DECLARATION_FALSE_PHI_PROHIBITED' | 'RAW_PERMITTED_EXPLICIT_OPT_OUT';
export interface Layer3Finding {
    layer: 3;
    code: Layer3FindingCode;
    severity: 'HIGH' | 'INFO';
    agentId: string;
    tool?: string;
    detail: string;
}
export interface Layer4Result {
    layer: 4;
    agentId: string;
    status: 'deferred' | 'passed' | 'failed';
    detail: string;
    /** Only populated when status === 'passed'. */
    inputStrippedAndTaggedObserved?: boolean;
}
export interface EvidenceEntry {
    /** Human-readable label for the auditor. */
    label: string;
    /** The grep one-liner or AST query that was run. */
    query: string;
    /** The output that query produced (may be empty string if nothing found). */
    output: string;
    /** Timestamp the query was run. */
    ran_at: string;
}
export interface PiiShieldEvidencePack {
    schema_version: 'pii-shield-evidence-v1';
    generated_at: string;
    scanner_version: string;
    scanned_dir: string;
    layers_run: number[];
    evidence: EvidenceEntry[];
}
export interface PiiShieldScanResult {
    agentId: string;
    filePath: string;
    layer3Findings: Layer3Finding[];
    layer4Result: Layer4Result | null;
    /** Populated by Layer 5 — written to pii-shield-evidence.json in the dir. */
    evidencePack: PiiShieldEvidencePack | null;
}
export interface PiiShieldScannerOptions {
    /** Root directory being scanned (absolute). */
    dir: string;
    /** When true, Layer 4 run-trace probe is attempted (requires sandbox). */
    deepScan?: boolean;
    /** When provided, evidence pack is written to this path; otherwise <dir>/pii-shield-evidence.json. */
    evidenceOutputPath?: string;
}
/**
 * Run Layer 3 analysis for a single agent manifest view.
 *
 * Cross-checks the agent's declared phiHandling against what Layers 1+2
 * found:
 *   - phiTools (Layer 1): tools with data_class === "PHI"
 *   - ungoverned_tool_calls (Layer 2): PHI tool calls without executor wrapper
 */
export declare function runLayer3(manifest: AgentManifestPhiView): Layer3Finding[];
/**
 * Layer 4: Optional sandbox run-trace probe.
 *
 * In PR-5-1 this is a STUB that returns a deferred status. The full
 * implementation requires the agent sandbox spawner (PR-5-3) to be in place.
 *
 * API contract (what PR-5-3 will implement):
 *   - Spawn agent in an isolated sandbox process
 *   - Send a synthetic PHI-bearing test prompt via the agent's input channel
 *   - Listen for INPUT_STRIPPED_AND_TAGGED audit event on the event bus
 *   - Return passed/failed within a 30-second timeout
 */
export declare function runLayer4(manifest: AgentManifestPhiView, _deepScan: boolean): Promise<Layer4Result>;
/**
 * Build the evidence pack for a single scan session.
 *
 * The evidence pack contains the exact grep one-liners + AST queries run
 * by the scanner, plus their outputs. This is the "show-your-work" artifact
 * for compliance auditors — they can re-run the queries verbatim and compare.
 */
export declare function buildEvidencePack(opts: {
    dir: string;
    manifests: AgentManifestPhiView[];
    layersRun: number[];
}): PiiShieldEvidencePack;
/**
 * Run PII Shield Layers 3-5 for all agent manifests in the scan session.
 *
 * Layer 1 and Layer 2 inputs are already populated in the manifests by
 * the existing scan.ts pipeline.
 *
 * @returns Array of per-agent results + evidence pack path (if written).
 */
export declare function runPiiShieldLayers(manifests: AgentManifestPhiView[], opts: PiiShieldScannerOptions): Promise<{
    results: PiiShieldScanResult[];
    evidencePackPath: string | null;
}>;
//# sourceMappingURL=pii-shield-scanner.d.ts.map