/**
 * Narrative Report Types -- P4-AIR-01 / P4-AIR-03
 *
 * Core type surface for AI-generated audit narrative reports. Every AI-
 * authored section is signed with an AiProvenance record and sealed into
 * the tamper-evident audit chain before the report is returned to the
 * caller.
 *
 * Pack-binding primacy: NarrativeReport.frameworks lists the compliance
 * pack IDs that scoped the report. Every NarrativeSection.framework value
 * MUST appear in that list. Events not bound to those packs MUST NOT
 * appear in any section.
 *
 * Spec: P4-AIR-01 AC 5-6, P4-AIR-03 AC 7-9
 *
 * @connexum/ai-governance
 */
export type ISO8601 = string;
/**
 * Stable reference to a single event in the tamper-evident audit chain.
 * The sectionSignature validator checks that every event ID cited in prose
 * actually exists in the event batch handed to the generator.
 */
export interface AuditChainRef {
    /** Chain entry ID or GovernanceEvent.id */
    eventId: string;
    /** Event type (e.g. 'action:denied', 'approval:decided') */
    eventType: string;
    /** ISO-8601 timestamp of the event */
    eventTimestamp: ISO8601;
    /** Human-readable summary for the rendered report */
    summary?: string;
}
/**
 * A human reviewer whose decision is cited in the report section.
 */
export interface ReviewerIdentity {
    /** Opaque reviewer ID (never PII in rendered output) */
    reviewerId: string;
    /** Role label (e.g. 'HIPAA Privacy Officer', 'SOC 2 Reviewer') */
    role: string;
    /** ISO-8601 timestamp of their decision */
    decidedAt: ISO8601;
}
/**
 * Cryptographic signature for one AI-authored NarrativeSection.
 *
 * signatureHash = SHA-256(sectionId + promptTemplateHash + inputChunkHashes.join(','))
 *
 * This value is recorded in the audit chain as part of the
 * report:ai-section-generated event so operators and auditors can detect
 * tampering in saved-off report copies (AC 9).
 */
export interface SectionSignature {
    sectionId: string;
    /** SHA-256(sectionId + promptTemplateHash + inputChunkHashes.join(',')) */
    signatureHash: string;
    /**
     * Set once sealProvenanceToChain() completes. Points to the chain entry
     * that sealed this section's signature.
     */
    chainAnchorRef?: AuditChainRef;
}
/**
 * Complete provenance record for every AI-authored section in a
 * NarrativeReport. Sealed into the audit chain before the report is
 * returned. renderNarrativeReport() refuses to render without this field.
 */
export interface AiProvenance {
    /** e.g. 'anthropic' | 'openai' | 'google' | 'azure' | 'aws' | 'self-hosted' */
    modelProvider: string;
    /** e.g. 'claude-3-5-sonnet-20241022' */
    modelId: string;
    /** Model version string from the provider response */
    modelVersion: string;
    /** SHA-256 of the prompt template text used for generation */
    promptTemplateHash: string;
    /** SHA-256 of each serialised input event batch (one entry per section) */
    inputChunkHashes: string[];
    /** Temperature passed to the LLM (0-2) */
    temperature: number;
    /** ISO-8601 generation timestamp */
    generatedAt: ISO8601;
    /** SDK / adapter version string */
    sdkVersion: string;
    /** One SectionSignature per NarrativeSection */
    sectionSignatures: SectionSignature[];
}
/**
 * A single AI-authored section scoped to one compliance framework.
 * Every factual claim in `prose` must be backed by a cited event in
 * `citedEvents`. The citation validator enforces this before the section
 * enters the rendered artefact.
 */
export interface NarrativeSection {
    /**
     * Compliance framework this section addresses.
     * Must be one of NarrativeReport.frameworks.
     */
    framework: string;
    /**
     * Stable section identifier. Used in watermark tags and chain sealing.
     * Format: <framework>-<eventCategory>-<shortId>
     * Example: 'soc2-approvals-a1b2c3'
     */
    anchor: string;
    /** AI-generated prose. May not contain invented event IDs. */
    prose: string;
    /** Events cited by ID within `prose`. Validated before rendering. */
    citedEvents: AuditChainRef[];
    /** Human reviewers whose decisions appear in the section */
    citedReviewers: ReviewerIdentity[];
    /** ID of the prompt template used to generate this section */
    promptTemplateId: string;
}
/**
 * Full AI-generated audit narrative report.
 *
 * Returned by AuditNarrativeGenerator.generate(). The report is NOT
 * considered final until provenance is sealed into the audit chain via
 * sealProvenanceToChain(). renderNarrativeReport() enforces this.
 */
export interface NarrativeReport {
    /** Stable report identifier (UUIDv4) */
    reportId: string;
    tenantId: string;
    contractId: string;
    window: {
        start: ISO8601;
        end: ISO8601;
    };
    /**
     * Pack IDs that scoped this report.
     * Events not bound to these packs were excluded from generation.
     */
    frameworks: string[];
    /** Target audience that shaped the narrative register */
    audience: 'auditor' | 'regulator' | 'board' | 'operator';
    sections: NarrativeSection[];
    /**
     * AI provenance record. Set after generation; must be present before
     * renderNarrativeReport() is called.
     */
    provenance?: AiProvenance;
    metadata: {
        /** Total events read from the audit chain for this window + tenant */
        totalEventsRead: number;
        /** Events that appeared in at least one section's citedEvents */
        totalEventsCited: number;
        /** Total tokens consumed across all LLM calls */
        tokensUsed: number;
        /** ISO-8601 timestamp when generation completed */
        generatedAt: ISO8601;
    };
}
export type AuditEventCategory = 'agent-tool-use' | 'approval-decision' | 'policy-violation' | 'enforcement-event';
/**
 * Read-only interface over the tamper-evident audit chain.
 * The AuditNarrativeGenerator takes this dependency so the actual storage
 * backend (in-memory, PostgreSQL, JSONL) remains an implementation detail.
 */
export interface AuditChainReader {
    /**
     * Return all events whose timestamp falls within [windowStart, windowEnd]
     * and whose orgId matches tenantId (when provided).
     *
     * Implementations MUST support the packBinding filter: only events whose
     * packBinding array intersects with `frameworks` are returned when
     * `frameworks` is non-empty.
     */
    getEventsInWindow(params: {
        tenantId: string;
        windowStart: ISO8601;
        windowEnd: ISO8601;
        frameworks?: string[];
    }): Promise<AuditChainEvent[]>;
}
/**
 * A single event as returned by AuditChainReader.
 * This is a normalised view used by the generator; storage-layer types
 * (AuditChainEntry, GovernanceEvent) are mapped to this before use.
 */
export interface AuditChainEvent {
    /** Stable event ID */
    id: string;
    /** Governance event type (e.g. 'action:denied', 'approval:decided') */
    type: string;
    /** Compliance pack IDs this event is bound to */
    packBinding: string[];
    /** ISO-8601 timestamp */
    timestamp: ISO8601;
    /** Agent that generated the event */
    agentName?: string;
    /** Tool involved (for tool-use events) */
    toolName?: string;
    /** Decision (ALLOW/DENY/REQUIRE_APPROVAL) */
    decision?: string;
    /** Human-readable reason */
    reason?: string;
    /** Arbitrary metadata */
    metadata?: Record<string, unknown>;
}
/**
 * Minimal write interface for appending to the audit chain.
 * Accepts AuditChainEntry shape from packages/governance-server/src/db.ts.
 */
export interface AuditChainWriter {
    appendAuditChain(entry: {
        id: string;
        orgId: string;
        previousHash: string;
        currentHash: string;
        entryData: Record<string, unknown>;
        timestamp: string;
    }): Promise<void>;
    getLatestChainHash(orgId?: string): Promise<string | undefined>;
}
/**
 * Thrown when the LLM produces a factual claim referencing an event ID
 * that was not present in the input event batch. Thrown before any output
 * is returned (fail-closed).
 */
export declare class UncitedClaimError extends Error {
    readonly inventedIds: string[];
    readonly sectionAnchor: string;
    constructor(inventedIds: string[], sectionAnchor: string);
}
/**
 * Thrown when the audit chain does not contain the required event types
 * for a report to be generated. Raised before the LLM call is made.
 */
export declare class MissingEvidenceError extends Error {
    readonly missingEventTypes: string[];
    readonly framework: string;
    constructor(missingEventTypes: string[], framework: string);
}
/**
 * Thrown when renderNarrativeReport() is called on a report whose
 * provenance has not been sealed into the audit chain.
 */
export declare class MissingProvenanceError extends Error {
    readonly reportId: string;
    constructor(reportId: string);
}
/**
 * Thrown by AuditNarrativeGenerator.generate() when the underlying audit
 * chain fails integrity verification before narrative generation begins.
 *
 * A report generated from a tampered chain is a false attestation. Fail-closed
 * is the only correct policy.
 *
 * The HTTP route catches this and returns HTTP 409 with:
 *   { "error": "chain_tamper_detected", "detail": { firstBadEventId, ... } }
 *
 * Spec: P1-TAMPER-C
 */
declare const CHAIN_TAMPER_BRAND: unique symbol;
export declare class ChainTamperDetectedError extends Error {
    readonly firstBadEventId: string;
    readonly expectedHash: string;
    readonly observedHash: string;
    readonly brokenAt: number;
    readonly [CHAIN_TAMPER_BRAND]: true;
    static readonly brand: symbol;
    static [Symbol.hasInstance](candidate: unknown): boolean;
    constructor(detail: {
        firstBadEventId: string;
        expectedHash: string;
        observedHash: string;
        brokenAt?: number;
    });
}
export {};
//# sourceMappingURL=narrative-types.d.ts.map