import type { VersionBase, ListVersionsInputBase, ListVersionsOutputBase, VersionedEntityBase } from './domains/versioned.js';
import type { FilesystemDB } from './filesystem-db.js';
import type { StorageOrderBy } from './types.js';
/**
 * Configuration for a filesystem-backed versioned storage domain.
 */
export interface FilesystemVersionedConfig {
    /** The FilesystemDB instance for I/O */
    db: FilesystemDB;
    /** Filename for the entities JSON file (e.g., 'agents.json') */
    entitiesFile: string;
    /** The key name of the parent FK field on versions (e.g., 'agentId') */
    parentIdField: string;
    /** Name for logging/error messages */
    name: string;
    /**
     * Fields that are version metadata (not part of the snapshot config).
     * These are stripped when writing to disk.
     * e.g., ['id', 'agentId', 'versionNumber', 'changedFields', 'changeMessage', 'createdAt']
     */
    versionMetadataFields: string[];
    /** Maximum number of git commits to load per file (default: 50) */
    gitHistoryLimit?: number;
    /** Directory for published entities that should be persisted as one JSON file per entity. */
    perEntityFilesDir?: string;
    /** Return true when an entity should persist as one JSON file instead of inside entitiesFile. */
    shouldPersistToPerEntityFile?: (entity: VersionedEntityBase) => boolean;
    /**
     * Optional snapshot filter applied to per-entity files only.
     * Lets per-entity files (e.g. code-mode JSON) exclude fields that are not
     * user-editable from Studio (such as `model`) while keeping the shared
     * `entitiesFile` snapshot unchanged.
     */
    perEntitySnapshotFilter?: (snapshot: Record<string, unknown>, entity: VersionedEntityBase) => Record<string, unknown>;
}
/**
 * Generic helpers for filesystem-backed versioned storage domains.
 *
 * Versions are kept entirely in memory. Only the published snapshot config
 * (the clean primitive configuration) is persisted to the on-disk JSON file.
 * This means the JSON files are human-readable, Git-friendly, and contain
 * no version metadata like `changedFields` or `changeMessage`.
 *
 * When the storage directory is inside a git repository, committed versions
 * of the JSON file are automatically loaded as read-only version history.
 * Each git commit that touched the file becomes a version record, giving
 * users a full published history in the version panel — powered by git.
 *
 * On-disk format for `agents.json`:
 * ```json
 * {
 *   "my-agent-id": {
 *     "name": "My Agent",
 *     "instructions": "Be helpful",
 *     "model": { "provider": "openai", "name": "gpt-4" }
 *   }
 * }
 * ```
 */
export declare class FilesystemVersionedHelpers<TEntity extends VersionedEntityBase & {
    createdAt: Date;
    updatedAt: Date;
    status: string;
}, TVersion extends VersionBase> {
    readonly db: FilesystemDB;
    readonly entitiesFile: string;
    readonly parentIdField: string;
    readonly name: string;
    readonly versionMetadataFields: string[];
    private readonly gitHistoryLimit;
    private readonly perEntityFilesDir?;
    private readonly shouldPersistToPerEntityFile?;
    private readonly perEntitySnapshotFilter?;
    /**
     * In-memory entity records (thin metadata), keyed by entity ID.
     */
    private entities;
    /**
     * In-memory version records, keyed by version ID.
     * Includes both in-memory/hydrated versions and git-based versions (metadata only).
     */
    private versions;
    /**
     * Whether we've loaded from disk yet.
     */
    private hydrated;
    /**
     * Git history utility instance (shared across all helpers).
     */
    private static gitHistory;
    /**
     * Promise that resolves when git history has been loaded.
     * null means git history loading hasn't been triggered yet.
     */
    private gitHistoryPromise;
    /**
     * The highest version number from git history, per entity ID.
     * Used to assign version numbers to new in-memory versions that continue
     * after the git history.
     */
    private gitVersionCounts;
    constructor(config: FilesystemVersionedConfig);
    private perEntityFilename;
    private entityIdFromPerEntityFilename;
    /**
     * Check if a version ID represents a git-based version.
     */
    static isGitVersion(id: string): boolean;
    /**
     * Hydrate in-memory state from the on-disk JSON file.
     * For each entry on disk, creates an in-memory entity (status: 'published')
     * and a synthetic version with the snapshot config.
     *
     * Also kicks off async git history loading in the background.
     * Version numbers for hydrated entities are assigned as 1 initially,
     * but will be reassigned after git history loads.
     */
    hydrate(): void;
    /**
     * Ensure git history has been loaded before proceeding.
     * Call this in version-related methods to ensure git versions are available.
     */
    private ensureGitHistory;
    /**
     * Load git commit history for the domain's JSON file.
     * Creates read-only version records (metadata + snapshot config) for each
     * commit where an entity existed. Reassigns version numbers for
     * hydrated (current disk) versions to sit on top of git history.
     */
    private loadGitHistory;
    /**
     * Load git-backed versions for a single per-entity file. Each commit that
     * changes the file becomes one version. Returns the running version count
     * for the entity (starting from `startCount`). Used both by the bulk
     * git-history pass and by `listVersions` to lazily discover entities that
     * were deleted on disk but still exist in git history.
     */
    private loadPerEntityGitHistory;
    /**
     * Write the published snapshot config for an entity to disk.
     * Strips all entity metadata and version metadata fields, leaving only
     * the clean primitive configuration.
     */
    private persistToDisk;
    /**
     * Extract the snapshot config from a version, stripping version metadata fields.
     */
    private extractSnapshotConfig;
    getById(id: string): Promise<TEntity | null>;
    createEntity(id: string, entity: TEntity): Promise<TEntity>;
    updateEntity(id: string, updates: Record<string, unknown>): Promise<TEntity>;
    deleteEntity(id: string): Promise<void>;
    listEntities(args: {
        page?: number;
        perPage?: number | false;
        orderBy?: StorageOrderBy;
        filters?: Record<string, unknown>;
        listKey: string;
    }): Promise<Record<string, unknown>>;
    createVersion(input: TVersion): Promise<TVersion>;
    getVersion(id: string): Promise<TVersion | null>;
    getVersionByNumber(entityId: string, versionNumber: number): Promise<TVersion | null>;
    getLatestVersion(entityId: string): Promise<TVersion | null>;
    listVersions(input: ListVersionsInputBase, parentIdField: string): Promise<ListVersionsOutputBase<TVersion>>;
    deleteVersion(id: string): Promise<void>;
    deleteVersionsByParentId(entityId: string): Promise<void>;
    countVersions(entityId: string): Promise<number>;
    /**
     * Lazily discover per-entity git history for an entity that was deleted on
     * disk but still exists in git commits. The bulk git-history pass only walks
     * entities currently on disk or in memory, so without this an entity that has
     * no in-memory versions would surface no git versions (and `gitVersionCounts`
     * would stay 0, letting a recreated entity collide with git version numbers).
     */
    private ensurePerEntityGitHistory;
    getNextVersionNumber(entityId: string): Promise<number>;
    private _getNextVersionNumber;
    dangerouslyClearAll(): Promise<void>;
}
//# sourceMappingURL=filesystem-versioned.d.ts.map