@schema-weaver/pg-connector 0.0.0-stage → 2.0.1

package/dist/types/audit/sanitize.d.ts

@@ -0,0 +1,78 @@
+export interface SafeDbError {
+    code: string;
+    severity?: string;
+    /** Sanitised, operator-useful message. Never contains row data or topology. */
+    message: string;
+    /** Optional curated hint, only for codes on a safe allow-list. */
+    hint?: string;
+    retryable?: boolean;
+}
+/** Connection parameters whose values must never leave the process. */
+export interface SanitizeTopology {
+    host?: string;
+    port?: number;
+    user?: string;
+    database?: string;
+    project?: string;
+}
+export interface SanitizeOptions {
+    /** Literal/comment redactor. Defaults to `redactSqlLiterals`. */
+    redactSql?: (s: string) => string;
+    /** Exact connection strings to scrub, when the caller knows them. */
+    topology?: SanitizeTopology;
+}
+/**
+ * SQLSTATE codes for which operator-useful detail text is surfaced.
+ *
+ * These are all class-22/23 (integrity), class-28 (auth), class-40 (transaction
+ * rollback), class-42 (syntax/access), class-53/55 (resource) and 57 (cancel)
+ * codes whose text is structural. Anything NOT listed here yields `code` +
+ * `severity` + a generic message only.
+ */
+export declare const PG_DETAIL_ALLOWLIST: ReadonlySet<string>;
+/**
+ * Our own one-line description for each SQLSTATE we recognise.
+ *
+ * These are strings written here, not derived from PostgreSQL output, so they
+ * cannot carry row data. Codes that are absent get a generic message that names
+ * only the SQLSTATE.
+ */
+export declare const PG_CURATED_MESSAGES: Readonly<Record<string, string>>;
+/**
+ * Our own hints. Never the server's `hint` field — that is attacker-influenced
+ * free text in the general case and is not on any allow-list.
+ */
+export declare const PG_CURATED_HINTS: Readonly<Record<string, string>>;
+/** Codes where retrying the identical request can succeed. */
+export declare const PG_RETRYABLE_CODES: ReadonlySet<string>;
+/**
+ * Replacement text for `PoolError` codes. The originals interpolate host, port,
+ * user and database name, so they are never forwarded verbatim.
+ */
+export declare const POOL_ERROR_MESSAGES: Readonly<Record<string, string>>;
+/**
+ * Remove hostnames, usernames, database names, URLs, absolute paths and email
+ * addresses from text that is about to leave the process.
+ */
+export declare function scrubTopology(text: string, topology?: SanitizeTopology): string;
+/** True when `code` may contribute detail text and a curated hint. */
+export declare function isDetailAllowed(code: string): boolean;
+/**
+ * Convert an arbitrary thrown value into a wire-safe error description.
+ *
+ * Never throws. Never returns row data, credentials, hostnames, usernames,
+ * database names or filesystem paths.
+ */
+export declare function sanitizePgError(err: unknown, opts?: SanitizeOptions): SafeDbError;
+/**
+ * Sanitise a free-text reason that came from our own permission layer. Those
+ * strings can embed a parser error, and a parser error embeds the SQL that
+ * failed to parse — so identifiers and literals are both redacted here.
+ */
+export declare function sanitizeReason(reason: string, opts?: SanitizeOptions): string;
+/**
+ * Sanitise a message that arrived as a bare string (e.g. a migration
+ * statement's recorded error) rather than as an error object.
+ */
+export declare function sanitizeErrorText(text: string | undefined | null, opts?: SanitizeOptions): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/types/audit/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../../src/audit/sanitize.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAClC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAKD;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAkBlD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuChE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkB7D,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAWjD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQhE,CAAC;AAuCF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAuB/E;AAUD,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAgCD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE,eAAoB,GAAG,WAAW,CA4BrF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,eAAoB,GAAG,MAAM,CAGjF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAC/B,IAAI,GAAE,eAAoB,GACzB,MAAM,CAER"}

package/dist/types/audit/sink.d.ts

@@ -0,0 +1,278 @@
+import { LocalAuditWriter } from './local-writer';
+import { CloudAuditWriter } from './cloud-writer';
+import { AuditActor, AuditEvent, AuditFilter, AuditQueryResult, AuditSinkHealth } from './types';
+import { type ResolvedDbIdentity } from './context';
+/**
+ * Fields the sink fills in itself; a caller supplies only the facts it knows.
+ *
+ * `resolved_db_alias`/`resolved_database` are deliberately NOT part of what a
+ * caller may supply: they are stamped by the sink from the per-request resolved
+ * context (`withResolvedDatabase`), so a call site cannot record the frame's
+ * claimed database and call it resolved.
+ */
+export type PendingEvent = Omit<AuditEvent, 'id' | 'ts' | 'agent_id' | 'seq' | 'chain_id' | 'prev_hash' | 'mac' | 'hash' | 'actor' | 'resolved_db_alias' | 'resolved_database'> & {
+    id?: string;
+    /**
+     * `user` (default) for cloud-asserted principals, `local` for a host-local
+     * operator, `system` for agent records. An absent value stays `user`, so
+     * every pre-existing call site keeps its meaning.
+     */
+    actor?: AuditActor;
+};
+export interface AuditSinkOptions {
+    agentId: string;
+    localWriter: LocalAuditWriter;
+    cloudWriter: CloudAuditWriter;
+    bufferSize?: number;
+    /**
+     * Hard cap on **queued** records. Past it the **oldest** are dropped, because
+     * an unbounded queue under sustained write pressure is unbounded memory in the
+     * daemon — the same defect class `CloudClient.maxQueueItems` closes (finding
+     * M-07). Default 4096.
+     *
+     * Only records that carry no authorization decision are ever queued (see
+     * {@link AuditSink}), so this bounds the sink's own memory no matter how much
+     * decision traffic arrives. It is clamped to at least `bufferSize`.
+     */
+    maxQueueItems?: number;
+    /**
+     * Called whenever queued records are dropped instead of written. Mirrors
+     * `CloudClient.onDrop`: the counter in {@link AuditSink.getHealth} is the
+     * marker, and an owner with a durable log elsewhere can record the loss.
+     * Never allowed to throw into the write path.
+     */
+    onDrop?: (drop: AuditDrop) => void;
+    /** Directory holding `audit.key`. Defaults to the agent home. */
+    keyDir?: string;
+    /** Explicit HMAC key (32-byte Buffer, or 64 hex chars). Overrides `keyDir`. */
+    key?: Buffer | string;
+    /** Upper bound on records scanned by `query()`. Default 200000. */
+    maxScanRecords?: number;
+}
+/** Why a queued record was dropped instead of written. */
+export type AuditDropReason = 'queue_overflow';
+export interface AuditDrop {
+    /** How many records were dropped in this event. */
+    count: number;
+    reason: AuditDropReason;
+    /** Queue depth after the drop. */
+    queueDepth: number;
+    /** The hard cap that was hit. */
+    maxQueueItems: number;
+}
+/**
+ * The audit sink: builds keyed, sequenced records, appends them locally and
+ * mirrors them to the cloud.
+ *
+ * Chain integrity rules:
+ *   - every record is MAC'd with the installation key and stamped with a
+ *     monotonically increasing `seq`
+ *   - `{seq, last_hash}` is anchored in `head.json` at every durable commit
+ *   - the head is recovered on first append (from `head.json` plus the tail of
+ *     the newest log file), so a restart continues the chain instead of
+ *     restarting it (finding H-13)
+ *   - a tail that does not verify is a loud, exposed failure — never a silent
+ *     new chain in the same file
+ *
+ * Buffer pressure (findings M-04, M-07): every write is serialised through one
+ * FIFO write lane, which is what keeps `seq`/`prev_hash` coherent. Records split
+ * by how they reach that lane:
+ *   - **never queued** — `logSync()` (an awaited record) and any record carrying
+ *     an authorization decision (`allow`/`deny`). They take the write lane
+ *     directly, so no amount of pressure can drop one, reject one, or make its
+ *     caller wait for queue space. This is the guaranteed path.
+ *   - **queued** — fire-and-forget `log()` records with no authorization
+ *     decision (manual-approval lifecycle telemetry). The queue is hard-capped
+ *     at `maxQueueItems`; past it the **oldest** are dropped and counted, so
+ *     sustained pressure cannot grow the heap without bound.
+ *
+ * A full queue is therefore not an error and never rejects a caller; the loss is
+ * counted (`getHealth().dropped`), logged, persisted as an `audit_overflow`
+ * record and handed to `onDrop`.
+ *
+ * Every record also carries the **resolved** database identity
+ * (`resolved_db_alias`, `resolved_database`), taken from the per-request context
+ * established by `withResolvedDatabase` and never from the caller. With
+ * no context established the value is the fail-closed `'unresolved'`.
+ */
+export declare class AuditSink {
+    private readonly opts;
+    private queue;
+    private draining;
+    private pendingFlush;
+    /**
+     * FIFO serialisation for every record write. Admission order is chain order;
+     * a lane slot is held only for the duration of one append.
+     */
+    private writeLane;
+    /** Records admitted but not yet written, queued or straight through. */
+    private pending;
+    private overflowPending;
+    private overflowTotal;
+    /** Drops since the last `audit_overflow` record was written. */
+    private overflowDropped;
+    private dropped;
+    private chainInit;
+    private auditKey;
+    private seq;
+    private lastHash;
+    private head;
+    /**
+     * Oldest sequence number still on disk. Rotation evicts the oldest archives,
+     * so verification starts here instead of at the genesis hash. Monotonic: it is
+     * a promise about what the log retains.
+     */
+    private retainedFromSeq;
+    /** Highest sequence number already anchored in the floor file. */
+    private floorSeq;
+    private floorErrorReported;
+    private chainError;
+    private chainErrorReported;
+    private eventsWritten;
+    private eventsFailed;
+    private writeErrorReported;
+    constructor(opts: AuditSinkOptions);
+    /** Chain identity, once established. */
+    get chainId(): string | null;
+    /**
+     * Attribute every audit record written inside `fn` to a resolved database.
+     *
+     * A thin delegate to the module-level context store, exposed here because the
+     * sink is where the contract lives: `log()`/`logSync()` read the identity from
+     * that store, so this method is the only supported way to supply one. It does
+     * not depend on sink instance state, which is what lets a caller that holds a
+     * hand-rolled sink in a test still get the same record shape.
+     */
+    withResolvedDatabase<T>(identity: ResolvedDbIdentity, fn: () => T): T;
+    /** Sequence number of the newest record this instance has written. */
+    get currentSeq(): number;
+    /**
+     * Fire-and-forget append. The record is written and committed by the next
+     * group commit; it is not guaranteed durable when this returns.
+     *
+     * A record that carries an authorization decision (`allow`/`deny`) bypasses
+     * the bounded queue and takes the write lane directly: a decision is never
+     * droppable and never waits for queue space. Everything else is queued and is
+     * subject to the `maxQueueItems` drop-oldest policy.
+     */
+    log(partial: PendingEvent): void;
+    /**
+     * Awaited append. Resolves only once the record (and the chain head that
+     * anchors it) is fsync'd. A write failure rejects — audit loss is never
+     * swallowed on this path.
+     *
+     * Never queued: buffer pressure can neither reject this call nor drop the
+     * record (finding M-04). The caller waits for its own append, never for queue
+     * room, so the wait is bounded by one write rather than by the backlog.
+     */
+    logSync(partial: PendingEvent): Promise<void>;
+    flush(): Promise<void>;
+    /**
+     * Filters the log and verifies the chain in the same streaming pass, so a full
+     * history is never materialised (finding M-06).
+     */
+    query(filter: AuditFilter): Promise<AuditQueryResult>;
+    /**
+     * The strongest claim about where the chain ends: this process's head plus the
+     * monotonic floor, which a second process (or a restored backup) may have moved
+     * further than the in-memory head.
+     */
+    private currentAnchor;
+    getHealth(): AuditSinkHealth;
+    /**
+     * Establishes the key and recovers the chain head. Idempotent; the promise is
+     * memoised so concurrent appends share one recovery.
+     */
+    private ensureChain;
+    private initChain;
+    private establishKey;
+    /**
+     * Validates the tail record against the key. Returns a problem description,
+     * or null when the tail is a legitimate continuation point.
+     */
+    private inspectTail;
+    /**
+     * Refuses to continue on a chain that does not verify. Throwing here is the
+     * point: the alternative — starting a fresh chain in the same file — would
+     * silently erase the evidence of the damage.
+     */
+    private failChain;
+    private reportChainError;
+    private onDurableCommit;
+    private persistHead;
+    private reportFloorError;
+    private buildEvent;
+    private record;
+    private buildVerifier;
+    /**
+     * Serialises every record write. This is what keeps `seq`, `prev_hash` and the
+     * anchored head consistent, and it is FIFO, so records enter the chain in
+     * admission order.
+     *
+     * A lane slot is held for the duration of one append only, which is what lets
+     * a decision record overtake queued telemetry instead of waiting behind it.
+     */
+    private runInWriteLane;
+    /**
+     * Records an admission: takes a slot in the outstanding-work count and, if
+     * the high-water mark is already exceeded, books an overflow admission. Every
+     * entry point (queued or straight through) goes through here, so the reported
+     * count describes the real backlog rather than one particular lane.
+     */
+    private admit;
+    /**
+     * The guaranteed path: straight to the write lane, never queued.
+     *
+     * Nothing here can be dropped or rejected for buffer pressure, and the caller
+     * never waits for queue room — only for its own append.
+     */
+    private writeThrough;
+    /**
+     * Queues a fire-and-forget, non-decision record.
+     *
+     * A full queue is *not* an error and never rejects the caller for pressure:
+     * the **oldest** entries are dropped to make room (drop-oldest, matching
+     * `CloudClient.maxQueueItems`, finding M-07) and every drop is counted,
+     * logged, persisted and handed to `onDrop`. Rejecting in-flight callers
+     * instead turned buffer pressure into a global query-kill switch and dropped
+     * the denial records that matter most (finding M-04).
+     *
+     * Only records that carry no authorization decision reach here — see
+     * {@link AuditSink.log} — so the eviction can never touch an allow/deny.
+     */
+    private enqueueQueued;
+    /**
+     * Single serial worker for the queue.
+     *
+     * Work queued while the worker is shutting down must not be lost: the queue is
+     * re-checked immediately after `draining` is cleared, with no `await` in
+     * between, so an entry can never be stranded with nobody left to run it.
+     */
+    private drain;
+    /**
+     * Releases a waiting `flush()` once nothing is outstanding — no queued entry,
+     * no write in flight. Straight-through records call this as they settle, so a
+     * flush cannot return while a decision record is still being written.
+     */
+    private settleIfIdle;
+    /**
+     * Writes the queue-pressure record: how many records were admitted above the
+     * high-water mark, and how many were dropped outright. Both numbers are read
+     * before they are reset (the previous code reset first, so the record always
+     * reported the wrong number).
+     */
+    private reportOverflowIfDue;
+    /**
+     * Counts a drop, says so out loud, and hands it to the `onDrop` marker hook —
+     * the same contract as `CloudClient.onDrop`. Audit loss is counted and
+     * reported, never discarded quietly.
+     */
+    private reportDrop;
+    /**
+     * Complains once per distinct failure so audit loss is never silent. The
+     * writer already announced a persistence failure, so this stays quiet rather
+     * than printing the same problem twice.
+     */
+    private reportWriteError;
+}
+//# sourceMappingURL=sink.d.ts.map

package/dist/types/audit/sink.d.ts.map

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

package/dist/types/audit/types.d.ts

@@ -0,0 +1,226 @@
+import { Role } from '../protocol/envelope';
+import { PermissionLevel } from '../permissions/types';
+export type AuditAction = 'query' | 'stream_query' | 'migration_run' | 'cancel' | 'introspect' | 'plan_register' | 'manual_approval' | 'audit_overflow';
+export type AuditDecision = 'allow' | 'deny' | 'pending' | 'approved' | 'rejected' | 'expired';
+export type AuditOutcome = 'success' | 'error' | 'cancelled' | 'n/a';
+/**
+ * Who caused a record to exist.
+ *
+ * `user` — a principal asserted by the cloud, with `role` and
+ * `permission_level` as asserted values.
+ * `system` — the agent itself (buffer pressure, lifecycle, internal
+ * conditions). System records MUST NOT carry a principal role.
+ * `local` — initiated by the operator on this host, from `sw-agent db query`
+ * or `sw-agent db test`. A `local` record carries NO cloud-asserted identity:
+ * the `role` field is the agent's own choice of authority for a local shell,
+ * not a role the cloud ever asserted or verified. Without this member such a
+ * record defaulted to `user` and was written as though a cloud principal
+ * holding `role: 'admin'` had performed the action — the false-attestation
+ * pattern audit finding C-03 is about, reintroduced on the local surface.
+ */
+export type AuditActor = 'user' | 'system' | 'local';
+/**
+ * A record's `role` field: a cloud-asserted principal role, or the literal
+ * `system` for agent-generated records. Audit records never invent a
+ * privileged role for the agent itself (audit finding L-06).
+ */
+export type AuditRole = Role | 'system';
+/**
+ * A record's `permission_level`: the effective, locally-resolved level for a
+ * principal, or the literal `unknown` for agent-generated records. There is no
+ * agent-generated permission level, so none is asserted.
+ */
+export type AuditPermissionLevel = PermissionLevel | 'unknown';
+export interface AuditEvent {
+    id: string;
+    ts: string;
+    agent_id: string;
+    /**
+     * The project the FRAME named. This is a caller-asserted string and it is
+     * retained for continuity with the existing record shape — it is NOT evidence
+     * of which database was touched. `resolved_db_alias` is that evidence.
+     */
+    project: string;
+    /**
+     * The `db_alias` the frame carried, exactly as sent.
+     *
+     * Recorded so a record that contradicts itself is legible: an asserted alias
+     * that differs from `resolved_db_alias` is precisely the  condition, and
+     * a verifier needs both halves to see it. Empty when the frame carried none.
+     */
+    db_alias_asserted?: string;
+    /**
+     * `db_alias` of the entry the request actually resolved to, as recorded by the
+     * audit sink from the per-request resolved context (see
+     * `withResolvedDatabase` in `src/audit/context.ts`), never from the frame.
+     *
+     * the trail used to carry `project` only, so a cross-database frame
+     * executing under a false label left no field that could name the database it
+     * really touched. `'unresolved'` is the fail-closed value and is what a
+     * refusal — where nothing was resolved — carries.
+     *
+     * Optional in the type because hand-built fixtures and records written by a
+     * build that predates the field still type-check; every record this build
+     * writes has it, and it is inside the MAC either way
+     * (`canonicalStringify` covers the whole record).
+     */
+    resolved_db_alias?: string;
+    /**
+     * Database **name** of the resolved entry, from the same context as
+     * `resolved_db_alias`. `'unresolved'` when nothing was resolved.
+     */
+    resolved_database?: string;
+    user_id: string;
+    /** `user` for cloud-asserted principals, `local` for a host-local operator, `system` for agent-generated records. */
+    actor: AuditActor;
+    role: AuditRole;
+    action: AuditAction;
+    decision: AuditDecision;
+    outcome: AuditOutcome;
+    statement_fingerprint?: string;
+    statement_preview?: string;
+    permission_level: AuditPermissionLevel;
+    denial_reason?: string;
+    error_code?: string;
+    duration_ms?: number;
+    rows_affected?: number;
+    rows_returned?: number;
+    migration_plan_id?: string;
+    /**
+     * The principal whose in-flight request a `cancel` frame named.
+     *
+     * `user_id` on a cancel record is the CANCELLER, who is frequently not the
+     * owner of the work being interrupted. Without this field the trail attributes
+     * a cross-tenant cancellation to the attacker and says nothing about whose
+     * request it was. Empty when the target carried no envelope.
+     */
+    cancel_target_user_id?: string;
+    /** The TARGET's project, from the target's own frame. */
+    cancel_target_project?: string;
+    /** The TARGET's asserted `db_alias`, from the target's own frame. */
+    cancel_target_db_alias?: string;
+    /**
+     * Monotonic position in the log. Starts at 1 and increments by exactly 1 per
+     * record, across daemon restarts and file rotations. Gaps, regressions and
+     * duplicates are tampering signals.
+     */
+    seq: number;
+    /** Identity of the key that signed this chain. See `AUDIT_KEY_FILENAME`. */
+    chain_id: string;
+    prev_hash: string;
+    /**
+     * `HMAC-SHA256(key, canonical(event without mac/hash) || prev_hash)`, hex.
+     * This is the tamper-evidence control: recomputing the chain requires the
+     * installation key.
+     */
+    mac: string;
+    /**
+     * Legacy alias of {@link AuditEvent.mac}. Kept so existing readers (log
+     * viewer, cloud ingest payload shape) keep working. Always equal to `mac`;
+     * verification fails if the two disagree.
+     */
+    hash: string;
+}
+/**
+ * The anchored head of the audit chain, persisted separately from the log in
+ * `head.json` inside the audit directory.
+ *
+ * Without an expected head there is nothing outside the log to compare against,
+ * so truncation, deletion and rollback are invisible. Verification MUST take the
+ * head from `head.json` (or a copy an operator cannot reach).
+ */
+export interface AuditHead {
+    /** Schema version of the head record. */
+    v: 1;
+    chain_id: string;
+    /** Sequence number of the newest record. 0 means "nothing has been written". */
+    seq: number;
+    /** `mac` of the record at `seq`. Genesis hash when `seq` is 0. */
+    last_hash: string;
+    written_at: string;
+    /**
+     * Oldest sequence number still on disk, i.e. the first record the log can be
+     * verified from. 1 unless rotation has evicted archives.
+     *
+     * The log is retained in a bounded number of files, so eventually the oldest
+     * records are dropped on purpose. Verification must therefore start at this
+     * sequence number, not at the genesis hash: a log that begins *later* than
+     * this is truncated or rolled back, a log that begins at it is complete as
+     * far as the retained window goes.
+     */
+    retained_from_seq?: number;
+}
+export interface AuditFilter {
+    project?: string;
+    user_id?: string;
+    action?: AuditAction;
+    decision?: AuditDecision;
+    outcome?: AuditOutcome;
+    since?: string;
+    until?: string;
+    limit?: number;
+}
+export interface AuditQueryResult {
+    events: AuditEvent[];
+    total: number;
+    chain_intact: boolean;
+    broken_at?: number;
+    /** Machine-readable verification failure reason, when `chain_intact` is false. */
+    chain_reason?: string;
+    /** Human-readable detail for `chain_reason`. */
+    chain_detail?: string;
+    /** Records examined while verifying the chain. */
+    chain_records?: number;
+}
+/** Observability surface for the local audit writer (audit finding C-06). */
+export interface AuditWriterHealth {
+    dir: string;
+    active_path: string;
+    /** True once the directory and file exist and the handle is open. */
+    ready: boolean;
+    /** False if the last append failed. Audit loss must never be silent. */
+    writable: boolean;
+    dir_mode: number | null;
+    file_mode: number | null;
+    /**
+     * Oldest sequence number still on disk, or null when no record is retained.
+     * Advances when rotation evicts the oldest archive.
+     */
+    retained_from_seq: number | null;
+    last_write_at: string | null;
+    last_error: string | null;
+    last_error_at: string | null;
+    error_count: number;
+    events_written: number;
+    events_failed: number;
+    bytes_written: number;
+    rotations: number;
+}
+/** Observability surface for the audit sink (audit findings C-05, C-06, M-04). */
+export interface AuditSinkHealth extends AuditWriterHealth {
+    chain_id: string | null;
+    /** Sequence number of the newest record this process has written. */
+    seq: number;
+    chain_error: string | null;
+    /**
+     * Records waiting in the sink's bounded queue.
+     *
+     * Hard-capped at `AuditSinkOptions.maxQueueItems`: past it the oldest are
+     * dropped. Records that take the write lane directly (`logSync()`, and any
+     * `allow`/`deny`) are held by their caller and are never counted here — that is
+     * what makes the cap a real bound on the sink's own memory.
+     */
+    queue_depth: number;
+    /** Records admitted above the queue high-water mark (`bufferSize`). */
+    overflow_admitted: number;
+    /**
+     * Records actually lost, because the bounded queue overflowed.
+     *
+     * A non-zero value is audit loss and is never silent: the same count is
+     * persisted as an `audit_overflow` record and handed to `onDrop`. It stays 0
+     * for `allow`/`deny` records and for `logSync()` — those are never queued, so no
+     * queue policy can drop them.
+     */
+    dropped: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/audit/types.d.ts.map

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