/**
 * Docs Audit Trail — unified immutable append-only audit log for all doc mutations.
 *
 * Every doc mutation (add, update, remove, supersede, publish, publish-pr,
 * sync, import) appends one line to `.cleo/audit/docs-audit.jsonl`. Each
 * entry carries an HMAC-SHA256 checkpoint chaining it to all prior entries,
 * forming a tamper-evident immutable log.
 *
 * The audit log is the canonical source of truth for:
 *   - `cleo docs audit --slug <slug>`  — per-slug operation history
 *   - `cleo docs audit --verify`       — chain integrity + cross-reference check
 *
 * Retention: entries are kept indefinitely (aligned with CLEO's 10-snapshot
 * backup rotation). Archival (compaction of old entries) is NOT performed
 * automatically — the audit log is deliberately append-only.
 *
 * @task T11182 (Saga T10516 — docs audit trail)
 */
/** Project-root-relative path to the unified docs audit log. */
export declare const DOCS_AUDIT_FILE = ".cleo/audit/docs-audit.jsonl";
/** All doc mutation operations tracked by the audit trail. */
export type DocsAuditOp = 'docs.add' | 'docs.update' | 'docs.remove' | 'docs.supersede' | 'docs.publish' | 'docs.publish-pr' | 'docs.sync' | 'docs.import';
/** A single immutable audit log entry. */
export interface DocsAuditEntry {
    /** Operation discriminator. */
    readonly op: DocsAuditOp;
    /** ISO 8601 timestamp of the mutation. */
    readonly ts: string;
    /** Identity that performed the operation (agent name, 'human', or 'system'). */
    readonly actor: string;
    /** Slug affected, when applicable. */
    readonly slug?: string;
    /** DocKind/type classification, when applicable. */
    readonly type?: string;
    /** New attachment ID created or affected. */
    readonly attachmentId?: string;
    /** SHA-256 of the content after mutation. */
    readonly sha256?: string;
    /** Previous SHA-256 (for updates), when applicable. */
    readonly previousSha256?: string;
    /** Owner entity ID affected. */
    readonly ownerId?: string;
    /** Human-readable summary of what changed. */
    readonly summary: string;
    /**
     * HMAC-SHA256 checkpoint chaining this entry to ALL prior entries.
     * Computed as HMAC-SHA256(secret, prevCheckpoint || serialized_entry_without_checkpoint).
     */
    readonly checkpoint: string;
}
/** Parameters for writing an audit entry. */
export interface WriteAuditEntryParams {
    op: DocsAuditOp;
    actor?: string;
    slug?: string;
    type?: string;
    attachmentId?: string;
    sha256?: string;
    previousSha256?: string;
    ownerId?: string;
    summary: string;
}
/** Result of reading the audit log. */
export interface AuditLogReadResult {
    /** All entries in chronological order. */
    readonly entries: DocsAuditEntry[];
    /** Whether the checkpoint chain is fully intact. */
    readonly chainIntact: boolean;
    /** Index of the first entry where the chain broke (-1 if intact). */
    readonly chainBrokenAt: number;
}
/** Result of a full audit verification. */
export interface AuditVerifyResult {
    /** Whether the audit log is fully consistent. */
    readonly consistent: boolean;
    /** Number of audit entries examined. */
    readonly entriesExamined: number;
    /** Whether the checkpoint chain is intact. */
    readonly chainIntact: boolean;
    /** Findings — inconsistencies detected. */
    readonly findings: AuditFinding[];
}
/** A single finding from audit verification. */
export interface AuditFinding {
    readonly severity: 'error' | 'warning';
    readonly message: string;
    readonly entryIndex?: number;
    readonly slug?: string;
}
/**
 * Append an immutable audit log entry for a doc mutation.
 *
 * This is the single write surface for the docs audit trail. Every doc
 * mutation MUST call this after successfully completing its write.
 *
 * The entry is written as a single JSON line appended to the audit log.
 * A checkpoint is computed that chains this entry to all prior entries.
 *
 * Best-effort: failures to write the audit log are swallowed — the
 * mutation itself already succeeded and audit drift is non-fatal.
 *
 * @param projectRoot - Absolute project root path.
 * @param params - Entry parameters.
 */
export declare function writeAuditEntry(projectRoot: string, params: WriteAuditEntryParams): void;
/**
 * Read the full audit log and verify the checkpoint chain.
 *
 * @param projectRoot - Absolute project root path.
 * @param slug - Optional filter: only return entries for this slug.
 * @returns The audit log read result with chain integrity status.
 */
export declare function readAuditLog(projectRoot: string, slug?: string): AuditLogReadResult;
/**
 * Full audit verification — checks checkpoint chain integrity and
 * cross-references against the attachment store.
 *
 * @param projectRoot - Absolute project root path.
 * @returns Verification result with findings.
 */
export declare function verifyAuditTrail(projectRoot: string): AuditVerifyResult;
/**
 * Count audit entries for a specific slug.
 *
 * @param projectRoot - Absolute project root path.
 * @param slug - Slug to count entries for.
 * @returns Number of audit entries referencing this slug.
 */
export declare function countAuditEntriesForSlug(projectRoot: string, slug: string): number;
//# sourceMappingURL=docs-audit.d.ts.map