/**
 * Factory audit events domain — the append-only "who did what, when" trail
 * behind the software factory.
 *
 * Rows are append-only: there is no update/delete API, and the table is the
 * local source of truth even when the WorkOS Audit Logs mirror is unavailable.
 * Tenancy is org-first, like `work_items`: `actor_id` records who acted but
 * never scopes reads.
 *
 * The actions the trail holds are listed in `./actions.ts`.
 *
 * Agent events carry `actor_type = 'agent'` with `actor_id = 'agent:<threadId>'`
 * and `metadata.startedBy = <userId>` chaining accountability back to the human
 * whose message drove the run. Rule-driven events carry `actor_type = 'system'`.
 */
import { FactoryStorageDomain } from '@mastra/core/storage';
import type { CollectionSchema } from '@mastra/core/storage';
import type { AuditActorType } from './actors.js';
/** What an audit event acted on (WorkOS Audit Logs target shape). */
export interface AuditTarget {
    /** Target kind, e.g. 'work_item', 'worktree', 'issue', 'pull_request'. */
    type: string;
    /** Stable identifier of the target (row id, branch name, issue number...). */
    id: string;
    /** Human-readable label (work-item title, branch name...). */
    name?: string;
}
export type { AuditActorType } from './actors.js';
/** Display name and avatar of a human actor, stamped at record time because MastraAuthStudio cannot resolve users by id. */
export interface AuditActorProfileInput {
    name?: string;
    avatarUrl?: string;
}
export declare const ACTOR_PROFILE_METADATA_KEY = "__actorProfile";
export declare function auditAgentName(modeId: string): string;
export declare function auditActorProfile(user: {
    name?: string;
    email?: string;
    avatarUrl?: string;
} | undefined): AuditActorProfileInput | undefined;
/** Request context captured alongside the event. */
export interface AuditContext {
    /** Client IP (first hop of `x-forwarded-for`) when available. */
    location?: string;
    /** Request `user-agent` header when available. */
    userAgent?: string;
}
/** One persisted audit event. */
export interface AuditEventRow {
    id: string;
    /** Owning WorkOS organization id — the trail is org-wide. */
    orgId: string;
    /** WorkOS user id of whoever performed the action, or `agent:<threadId>`. */
    actorId: string;
    /** Whether a human or an agent (inside a run) performed the action. */
    actorType: AuditActorType;
    /** Dot-namespaced action, e.g. 'factory.work_item.stage_moved'. */
    action: string;
    /** What was acted on. */
    targets: AuditTarget[];
    /** Bounded event summary — never full payloads, never secrets. */
    metadata: Record<string, unknown>;
    /** Factory project the event is scoped to; null for org-level events. */
    factoryProjectId: string | null;
    /** Project-repository link affected by a repository-specific action. */
    projectRepositoryId: string | null;
    /** Request context (`x-forwarded-for` / `user-agent`). */
    context: AuditContext;
    occurredAt: Date;
}
export interface RecordAuditEventInput<Action extends string = string> {
    idempotencyKey?: string;
    orgId: string;
    actorId: string;
    /** Who performed the action; defaults to 'human'. */
    actorType?: AuditActorType;
    actorProfile?: AuditActorProfileInput;
    action: Action;
    targets: AuditTarget[];
    metadata?: Record<string, unknown>;
    factoryProjectId?: string;
    projectRepositoryId?: string;
    context?: AuditContext;
    occurredAt?: Date;
}
/** A fully-normalized event ready to persist (id assigned on insert). */
export type AuditEventInsert = Omit<AuditEventRow, 'id'>;
export interface ListAuditEventsInput {
    orgId: string;
    factoryProjectId?: string;
    /** Restrict to these actions (exact match). */
    actions?: string[];
    actorId?: string;
    /** Opaque cursor from a previous page (`nextCursor`). */
    before?: string;
    limit?: number;
}
export interface AuditEventPage {
    events: AuditEventRow[];
    /** Pass back as `before` to fetch the next (older) page; absent at the end. */
    nextCursor?: string;
}
/** Truncate oversized metadata rather than dropping the whole event. */
export declare function boundAuditMetadata(metadata: Record<string, unknown> | undefined): Record<string, unknown>;
/** Normalize a requested page size to a finite integer in `[1, MAX_PAGE_SIZE]`. */
export declare function clampAuditLimit(limit: number | undefined): number;
/** Encode the `(occurredAt, id)` keyset cursor of a row. */
export declare function encodeAuditCursor(row: AuditEventRow): string;
/** Decode a cursor back into its `(occurredAt, id)` parts, or `undefined`. */
export declare function decodeAuditCursor(cursor: string): {
    occurredAt: Date;
    id: string;
} | undefined;
export declare const AUDIT_EVENTS_SCHEMA: CollectionSchema;
/**
 * Audit event storage, written once against the generic `FactoryStorageOps`
 * surface. `record()` normalizes inputs (defaults, metadata bounding);
 * `list()` is keyset-paginated on `(occurred_at, id)` newest-first.
 */
export declare class AuditStorage extends FactoryStorageDomain {
    #private;
    constructor();
    init(): Promise<void>;
    dangerouslyClearAll(): Promise<void>;
    /** Append one audit event. Throws on failure — swallow-on-failure lives in the caller. */
    record(input: RecordAuditEventInput): Promise<AuditEventRow>;
    recordOnce(input: RecordAuditEventInput): Promise<{
        event: AuditEventRow;
        created: boolean;
    }>;
    /** List an org's audit events newest-first with keyset pagination. */
    list(input: ListAuditEventsInput): Promise<AuditEventPage>;
}
//# sourceMappingURL=base.d.ts.map