/**
 * Internal Hikoutei runtime core: the `Hikoutei` contract, its
 * single-instance close state machine, and the option validators shared by
 * the public `createTypedSheets()` entry (root package) and the sync service
 * bootstrap (`@hikoutei/sync-engine`).
 *
 * P8-D2 phase 2: this cluster moved out of `src/api/Hikoutei.ts` so the sync
 * engine never imports the root package. The public entry keeps its lazy
 * composition wiring; concrete runtime construction stays adapter-free here
 * (the provider arrives port-typed via `ScalarEntityPersistenceProvider`).
 */
import type { ScalarEntityPersistenceProvider } from "../../contracts/storage/scalar.js";
import type { GoogleSheetsApiProviderOptions } from "../../contracts/sheets/googleSheetsApi.js";
import type { EntityManager } from "./EntityManager.js";
import { type HikouteiDescriptorFile, type HikouteiEntity, type ResolvedHikouteiEntityDescriptor } from "./entity.js";
/**
 * Application-settable Google Sheets provider options for a sync-enabled
 * runtime (the `HIKOUTEI_SYNC_SPREADSHEET_URL` path).
 *
 * This is a strict subset of the internal provider contract: the test-only
 * injection hooks (`transport`, `now`, `sleep`) are NOT part of the public
 * surface. `onRequest` receives redacted per-request telemetry events (never
 * ids, payloads, or URLs); it fires only while the sync worker/polling makes
 * real Google API calls, so a local-only runtime never emits it. Timeouts are
 * validated fail-closed by the sync-service bootstrap. The
 * `HIKOUTEI_SYNC_RATE_LIMIT_INTERVAL_MS` env override, when set, wins over
 * `rateLimitIntervalMs`.
 */
export type HikouteiProviderOptions = Omit<GoogleSheetsApiProviderOptions, "transport" | "now" | "sleep">;
/** Options for opening the local Hikoutei runtime. */
export interface CreateTypedSheetsOptions {
    /**
     * SQLite database path, URI, or `:memory:`.
     *
     * Defaults to the `HIKOUTEI_DB_PATH` environment variable when it is set to
     * a non-empty value, otherwise `./hikoutei.sqlite`.
     */
    readonly dbName?: string;
    /**
     * Entity tokens produced by `defineTypedSheetsEntity()`.
     *
     * Defaults to the entities registered by `defineTypedSheetsEntity()` at the
     * time of the call, in registration order.
     */
    readonly entities?: readonly HikouteiEntity[];
    /**
     * File-form entity descriptors (e.g. from `infer --emit desc.json`).
     *
     * Each entry runs through the same `defineTypedSheetsEntity` builder as
     * code-registered entities, so file-registered tokens are
     * indistinguishable at runtime (CRUD, sync projection, adoption). The
     * built tokens are appended after `entities`; name/table collisions
     * across both lists are rejected by the shared registry validation.
     * Pass `entities: []` alongside this list to isolate from the ambient
     * `defineTypedSheetsEntity()` registration default.
     */
    readonly descriptors?: readonly HikouteiDescriptorFile[];
    /**
     * Optional Google Sheets provider tuning/telemetry for the SYNC path only.
     * When `HIKOUTEI_SYNC_SPREADSHEET_URL` is absent this field is inert (a
     * local-only runtime constructs no provider), preserving byte-identical
     * local behavior. See {@link HikouteiProviderOptions}.
     */
    readonly providerOptions?: HikouteiProviderOptions;
}
/**
 * Root object for the local entity runtime.
 *
 * Use `hikoutei.em.fork()` to obtain a request-local manager. Sheet delivery
 * and User_Input polling belong to the internal sync service, not this object.
 */
export interface Hikoutei {
    /** Root entity manager; call `fork()` before request or job-local work. */
    readonly em: EntityManager;
    close(): Promise<void>;
}
/**
 * Internal construction hook used by the sync service to attach shutdown work
 * without adding worker methods to the public `Hikoutei` contract.
 */
export declare function createInternalHikoutei(provider: ScalarEntityPersistenceProvider, descriptors: ReadonlyMap<string, ResolvedHikouteiEntityDescriptor>, beforeClose?: () => Promise<void>): Hikoutei;
/**
 * Resolves the default SQLite path for a factory call that omits `dbName`.
 *
 * Prefers the `HIKOUTEI_DB_PATH` environment variable when it is set to a
 * non-empty string, otherwise falls back to `./hikoutei.sqlite`. The `env`
 * parameter defaults to `process.env` and exists so tests can exercise the
 * precedence without mutating the process environment.
 */
export declare function resolveDefaultDbPath(env?: Readonly<Record<string, string | undefined>>): string;
/**
 * Validates the public factory options before any runtime is constructed.
 *
 * Fields are optional; each one is validated only when it is provided. The
 * registry/env defaults are applied afterwards by `createTypedSheets()`.
 */
export declare function validateTypedSheetsOptions(options: CreateTypedSheetsOptions): void;
/**
 * Builds entity tokens for file-form descriptors after re-validating them.
 *
 * `validateTypedSheetsOptions` checks the array shape only; this step runs
 * every entry through `parseDescriptorFile` (version + header envelope +
 * the builder's own scalar rules) and then the shared builder, so
 * file-registered tokens take the exact same path as code-registered ones.
 * Plain JSON values (e.g. `JSON.parse` output) are accepted as well as
 * already-typed descriptors.
 */
export declare function tokensFromDescriptorFiles(descriptors: readonly unknown[]): HikouteiEntity[];
/**
 * Merges code-registered tokens with file-form descriptors for a factory.
 *
 * `explicitEntities` is the `entities` option (or its registry default,
 * resolved by the caller); descriptor-built tokens are appended after it.
 */
export declare function mergeEntitiesAndDescriptors(explicitEntities: readonly HikouteiEntity[], descriptors: readonly unknown[] | undefined): HikouteiEntity[];
//# sourceMappingURL=hikouteiCore.d.ts.map