/**
 * Engine-neutral scalar entity Unit of Work.
 *
 * Hikoutei owns entity lifecycle semantics here rather than delegating to an
 * ORM's dirty tracking. The Unit of Work keeps a request-local identity map and
 * the original snapshot of every managed entity, computes a dirty diff against
 * those snapshots at flush time, and owns the insert/update/delete change plan.
 *
 * The change plan is pure data over the provider-neutral persistence contract,
 * so the same lifecycle works whether SQLite is reached through node:sqlite,
 * MikroORM, or a future Prisma adapter.
 */
import type { ResolvedHikouteiEntityDescriptor } from "../../../api/entity.js";
import type { ScalarEntityDelete, ScalarEntityInsert, ScalarEntityUpdate, ScalarEntityValue } from "../../../../contracts/storage/scalar.js";
/** Lifecycle state of one managed entity inside a Unit of Work. */
export type ScalarManagedEntityState = "new" | "clean" | "removed";
/** One managed entity entry tracked by the Unit of Work. */
interface ManagedEntity {
    readonly descriptor: ResolvedHikouteiEntityDescriptor;
    readonly entity: object;
    snapshot: Readonly<Record<string, ScalarEntityValue>>;
    /** Initial key for a new entity; undefined means it was assigned later. */
    initialPrimaryKey: ScalarEntityValue | undefined;
    state: ScalarManagedEntityState;
}
/** In-memory checkpoint used to restore the common UoW after transaction rollback. */
export interface ScalarEntityUnitOfWorkCheckpoint {
    readonly entries: {
        readonly descriptor: ResolvedHikouteiEntityDescriptor;
        readonly entity: object;
        readonly snapshot: Readonly<Record<string, ScalarEntityValue>>;
        readonly values: Readonly<Record<string, ScalarEntityValue | undefined>>;
        readonly initialPrimaryKey: ScalarEntityValue | undefined;
        readonly state: ScalarManagedEntityState;
    }[];
}
/** Entity/descriptor pair used only for manager rollback identity recovery. */
export interface ScalarManagedEntityReference {
    readonly descriptor: ResolvedHikouteiEntityDescriptor;
    readonly entity: object;
}
/** Discriminated change planned for one managed entity during a flush. */
export type PlannedScalarChange = {
    readonly kind: "insert";
    readonly entry: ManagedEntity;
    readonly row: ScalarEntityInsert;
} | {
    readonly kind: "update";
    readonly entry: ManagedEntity;
    readonly row: ScalarEntityUpdate;
} | {
    readonly kind: "delete";
    readonly entry: ManagedEntity;
    readonly row: ScalarEntityDelete;
};
/** Ordered insert/update/delete plan collected from one flush. */
export interface ScalarEntityFlushPlan {
    readonly changes: readonly PlannedScalarChange[];
}
/**
 * Request-local identity map and change tracker.
 *
 * One `EntityManager.fork()` owns its own Unit of Work so concurrent requests
 * never share identity maps or dirty snapshots.
 */
export declare class ScalarEntityUnitOfWork {
    private readonly entries;
    private readonly recoveryCheckpoints;
    /** Tracks a newly created entity so its first flush emits an insert. */
    manageNew(descriptor: ResolvedHikouteiEntityDescriptor, entity: object): void;
    /** Tracks an entity loaded from storage so mutations diff against its snapshot. */
    manageLoaded(descriptor: ResolvedHikouteiEntityDescriptor, entity: object, snapshot: Readonly<Record<string, ScalarEntityValue>>): void;
    /** Returns whether an entity instance is currently tracked by this Unit of Work. */
    has(entity: object): boolean;
    /** Returns whether the current primary key still matches the tracked identity. */
    isPrimaryKeyStable(entity: object): boolean;
    /** Captures lifecycle state before an outer transaction can roll back. */
    checkpoint(): ScalarEntityUnitOfWorkCheckpoint;
    /** Restores the lifecycle state captured before a failed transaction. */
    restore(checkpoint: ScalarEntityUnitOfWorkCheckpoint): void;
    /** Marks a tracked entity (or registers a new one) for the next flush. */
    persist(descriptor: ResolvedHikouteiEntityDescriptor, entity: object): void;
    /** Marks a tracked entity for removal; cancels an unflushed insert instead. */
    remove(entity: object): boolean;
    /**
     * Builds the insert/update/delete plan from the current identity map.
     *
     * Throws a typed error when a primary key is missing or when a tracked entity
     * mutated its primary key, which is immutable after creation.
     */
    collectFlushPlan(): ScalarEntityFlushPlan;
    /** Resets snapshots and drops committed entries after a successful flush. */
    afterFlush(plan: ScalarEntityFlushPlan): void;
    /** Starts recording entities discovered inside a transaction. */
    beginRecovery(checkpoint: ScalarEntityUnitOfWorkCheckpoint): void;
    /** Stops recording entities for a completed transaction. */
    endRecovery(checkpoint: ScalarEntityUnitOfWorkCheckpoint): void;
    /** Returns the entities currently represented by the Unit of Work. */
    managedEntities(): readonly ScalarManagedEntityReference[];
    /** Drops every managed entity without writing anything. */
    clear(): void;
    private captureRecoveryEntry;
}
/** Reads the declared scalar values from one managed entity instance. */
export declare function readEntityValues(descriptor: ResolvedHikouteiEntityDescriptor, entity: object): Readonly<Record<string, ScalarEntityValue>>;
export {};
//# sourceMappingURL=unitOfWork.d.ts.map