import { BetterSqlite3Database } from '@remnic/core/runtime/better-sqlite';

/**
 * Coding-graph SQLite schema — versioned meta + tables + FTS5 virtual table.
 *
 * Issue #1552 PR1 (Track B, Phase 1). The schema + write pipeline only;
 * traversal, search, dead-code and the openCypher subset land in PR2/PR3.
 *
 * PR2 additive table (`node_attributes`): tracks per-node exclusion flags
 * consumed by `deadCode()` — `is_exported`, `is_route_handler`. Added in
 * PR2 (issue #1552 step 5) as a SEPARATE table rather than ALTER TABLE on
 * `nodes`, so existing v1 databases gain the table via the same
 * `CREATE TABLE IF NOT EXISTS` pass without a schema-version bump or a
 * migration (rule 23 — additive, characterized before moving).
 *
 * Design anchors:
 *   - `packages/remnic-core/src/lcm/schema.ts` (versioning + pragmas) —
 *     copied VERBATIM for the WAL / busy_timeout / synchronous pragmas and
 *     the meta-table version row. Do not invent a new pattern (rule 23/38).
 *   - `packages/remnic-core/src/runtime/better-sqlite.ts` (`openBetterSqlite3`)
 *     — the shared opener; native-binding lifecycle is paid for once there.
 *   - issue://1552 "Design" — node ids hash sorted key material; file
 *     contents are NEVER stored (only spans + content hashes); FTS5 covers
 *     node names; provenance CHECK enforces the four-value enum.
 *
 * Schema versioning:
 *   The schema_version row lives in `meta` (a generic key/value table, not
 *   lcm_meta — independent store, separate version namespace). Fresh DB →
 *   schema_version=1. Upgrade stub: meta v0 → v1 (rule 23, characterize
 *   before moving).
 *
 * Dangling-edge policy (PR1 decision):
 *   When `upsertFileBatch` deletes a file's prior nodes + edges, cross-file
 *   edges whose `dst` was a node owned by the deleted file become dangling.
 *   We DROP them. They are counted in `UpsertResult.droppedDanglingEdges`
 *   so callers can surface the loss. Keeping them with a `dst_unresolved`
 *   marker would leak orphans and bias `traverse()` results — drop is the
 *   conservative choice for a write pipeline whose caller knows the
 *   canonical file set on each batch (rule 11, 40).
 */

declare const CODING_GRAPH_SCHEMA_VERSION = 1;
/**
 * FTS5 rowid derived from a deterministic node id. FTS5 rowids are
 * signed 64-bit integers; we slice the leading 16 hex chars (= 64 bits)
 * of the sha256 id and mask to the int64 positive range so SQLite
 * accepts it. The full 64-bit space is large enough that collisions
 * across distinct node ids are negligible. Contentless FTS5
 * (`content=''`) does NOT store UNINDEXED column values, so the only
 * reliable key into the virtual table is the rowid.
 *
 * Lives in graph-schema (not graph-store) so the schema migration path
 * can rebuild FTS rows from existing `nodes` without importing the
 * store module (which would create a circular dependency — graph-store
 * imports graph-schema).
 */
declare function ftsRowidForNodeId(nodeId: string): bigint;
/**
 * Provenance enum for edges — mirrors #1552's `heuristic|lsp|trace|semantic`
 * whitelist. The CHECK constraint rejects writes outside this set so a
 * buggy resolver can't sneak in unknown values (rule 23).
 */
declare const EDGE_PROVENANCE_VALUES: readonly ["heuristic", "lsp", "trace", "semantic"];
type EdgeProvenance = (typeof EDGE_PROVENANCE_VALUES)[number];
declare function isEdgeProvenance(value: unknown): value is EdgeProvenance;
/**
 * Apply (or upgrade) the coding-graph schema on an already-open SQLite
 * handle. Public so test seams and migration tools can bootstrap an
 * in-memory database without going through {@link openCodingGraphDatabase}.
 *
 * Mirrors `applyLcmSchema` in `packages/remnic-core/src/lcm/schema.ts` —
 * distinct function, same shape, separate version namespace.
 */
declare function applyCodingGraphSchema(db: BetterSqlite3Database): void;
/**
 * Read the schema_version row. Returns 0 when the table is missing or the
 * row has not been written yet — used by the upgrade stub test.
 *
 * Mirrors the LCM helper's tolerance: a missing `meta` table is not an
 * error condition here, it just means the schema has never been applied.
 */
declare function readSchemaVersion(db: BetterSqlite3Database): number;

export { CODING_GRAPH_SCHEMA_VERSION, EDGE_PROVENANCE_VALUES, type EdgeProvenance, applyCodingGraphSchema, ftsRowidForNodeId, isEdgeProvenance, readSchemaVersion };