@nacre.work/core 0.0.0 → 0.1.0

package/dist/passwords.js

@@ -0,0 +1,234 @@
+import { randomBytes, scrypt as scryptCallback, timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+/**
+ * Password hashing, with scrypt from the standard library.
+ *
+ * Argon2id is the first choice in every current guideline and it is not
+ * available here without a dependency — either a native module built by
+ * node-gyp, or one shipping prebuilt binaries for every platform an operator
+ * might self-host on. Both are things every operator of a security product
+ * inherits, and the second is a supply chain that ships machine code.
+ *
+ * scrypt is the documented alternative in the same guidelines, it is memory-
+ * hard, and it is in `node:crypto`. The parameters below are OWASP's minimum
+ * for it. This is a deliberate second choice rather than an oversight, and the
+ * encoding carries its parameters so that moving to Argon2id later is a new
+ * prefix and a rehash on next login rather than a migration that invalidates
+ * every password.
+ *
+ * ## Why the cost is a constant and not configuration
+ *
+ * A tunable would let an operator turn it down, and the only reason anyone ever
+ * does is that logins felt slow. The cost is the entire defence: it is what
+ * makes a stolen `password_hash` column expensive rather than a wordlist away
+ * from plaintext.
+ */
+// promisify picks the overload without options, and the options are the whole
+// point here — the cost parameters live in them.
+const scrypt = promisify(scryptCallback);
+/** OWASP's minimum for scrypt: N=2^17, r=8, p=1. */
+const N = 131_072;
+const R = 8;
+const P = 1;
+const KEY_BYTES = 64;
+const SALT_BYTES = 32;
+/**
+ * 128 * N * r is 134 MB, and Node's default `maxmem` is 32 MB — without this
+ * every call fails with an error about memory rather than a wrong password,
+ * which is a confusing way to find out. The headroom is for the internal
+ * allocations on top of the working set.
+ */
+const MAX_MEM = 256 * 1024 * 1024;
+/* ─────────────────────── the gate, and why there is one ───────────────────────
+ *
+ * `crypto.scrypt` is asynchronous in the sense that it does not block the event
+ * loop — it runs on libuv's thread pool. That pool has four threads by default,
+ * and it is not the crypto pool: `dns.lookup`, `fs`, and zlib are on it too.
+ *
+ * So four concurrent sign-in attempts occupy the whole pool for the duration of
+ * a deliberately expensive hash, and the fifth thing to want a thread waits.
+ * When that thing is `getaddrinfo` for Postgres, the request path stops on a
+ * name lookup — which looks like a database problem, on a dashboard, at the
+ * exact moment somebody is spraying the login endpoint. Each call also holds
+ * 134 MB while it runs, so the unbounded version is 134 MB times however many
+ * requests arrive at once.
+ *
+ * The rate limiter does not cover this. It counts per email address, and an
+ * attacker rotating addresses never repeats one; it counts in Redis, so it
+ * fails open by design; and it runs per request while this is about how many
+ * run *at the same time*, which is a different quantity. A limit of ten per
+ * fifteen minutes still permits every attempt to arrive in the same second.
+ *
+ * ─── the numbers ───
+ *
+ * Two concurrent hashes, so half the default pool stays free for the DNS and
+ * file I/O the rest of the process needs. Read from UV_THREADPOOL_SIZE where an
+ * operator has raised it, because the point is a fraction of the pool rather
+ * than the number two.
+ *
+ * The queue is bounded as well, and that bound is the load-shedding one: a
+ * queue is cheap in memory — a waiting request holds no scrypt buffer — but an
+ * unbounded one converts a flood into unbounded latency for the legitimate
+ * user, who ends up behind ten thousand guesses. Past the bound the call is
+ * refused immediately and the caller answers 503, which is the honest response
+ * to "this process cannot verify a password right now".
+ *
+ * Refusing is not an oracle. It depends on how loaded the process is and not at
+ * all on whether the account exists, and it is returned identically to the
+ * caller whether the address matched a user or not.
+ */
+const poolSize = Number(process.env.UV_THREADPOOL_SIZE ?? 4);
+const MAX_CONCURRENT = Math.max(1, Math.floor((Number.isFinite(poolSize) ? poolSize : 4) / 2));
+const MAX_QUEUED = 64;
+/** Raised when the process is already verifying as many passwords as it will. */
+export class TooBusy extends Error {
+    constructor() {
+        super('too many passwords are being verified at once');
+        this.name = 'TooBusy';
+    }
+}
+let active = 0;
+const waiting = [];
+async function gated(work) {
+    if (active >= MAX_CONCURRENT) {
+        if (waiting.length >= MAX_QUEUED)
+            throw new TooBusy();
+        // Waits to be *handed* a permit, and does not increment on waking.
+        //
+        // The obvious version releases the permit, wakes a waiter, and lets it take
+        // a slot on its own — which leaves a window between the release and the
+        // waiter's turn where an arriving call sees a free slot and takes it too.
+        // As it happens that window is not reachable from a single Node event loop:
+        // the waiter's continuation is queued as a microtask at the moment of the
+        // release, so it runs before anything that could have arrived afterwards.
+        // Tried to reproduce it and could not.
+        //
+        // Handing the permit over regardless, because "correct, given the current
+        // microtask ordering of the runtime" is a bad thing for a bound to depend
+        // on, and this version does not depend on it at all: the count never
+        // changes when a permit changes owner, so there is no window to reason
+        // about. It is also shorter.
+        await new Promise((resolve) => waiting.push(resolve));
+    }
+    else {
+        active++;
+    }
+    try {
+        return await work();
+    }
+    finally {
+        // Hand the permit over rather than release it. `active` is unchanged when
+        // there is a waiter, because the slot never becomes free — it changes
+        // owner. One waiter per completion, so a queue drains at the rate work
+        // finishes and never all at once.
+        const next = waiting.shift();
+        if (next === undefined)
+            active--;
+        else
+            next();
+    }
+}
+/** For a metric and for tests. Not a decision anything makes. */
+export const hashingLoad = () => ({
+    active,
+    queued: waiting.length,
+    limit: MAX_CONCURRENT,
+});
+/**
+ * `scrypt$N$r$p$salt$hash`, base64url, parameters first.
+ *
+ * Self-describing on purpose. A bare hash cannot be verified after the cost is
+ * raised, so raising it means invalidating every password in the database;
+ * carrying the parameters means old hashes keep verifying and get rewritten as
+ * people sign in.
+ */
+export async function hashPassword(password) {
+    const salt = randomBytes(SALT_BYTES);
+    const key = await gated(() => scrypt(password.normalize('NFKC'), salt, KEY_BYTES, {
+        N,
+        r: R,
+        p: P,
+        maxmem: MAX_MEM,
+    }));
+    return `scrypt$${N}$${R}$${P}$${salt.toString('base64url')}$${key.toString('base64url')}`;
+}
+function parse(encoded) {
+    const parts = encoded.split('$');
+    if (parts.length !== 6 || parts[0] !== 'scrypt')
+        return undefined;
+    const n = Number(parts[1]);
+    const r = Number(parts[2]);
+    const p = Number(parts[3]);
+    if (!Number.isInteger(n) || !Number.isInteger(r) || !Number.isInteger(p))
+        return undefined;
+    // A stored record could otherwise ask for a work factor large enough to hang
+    // the process, which turns one poisoned row into an outage.
+    if (n < 1024 || n > 1 << 22 || r < 1 || r > 32 || p < 1 || p > 16)
+        return undefined;
+    try {
+        return {
+            n,
+            r,
+            p,
+            salt: Buffer.from(parts[4], 'base64url'),
+            key: Buffer.from(parts[5], 'base64url'),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Verify, in time that does not depend on whether the password was right.
+ *
+ * A malformed or absent hash answers false rather than throwing: the caller
+ * turns every failure into the same refusal, and an exception on one of them
+ * would be a way to tell them apart from the outside.
+ */
+export async function verifyPassword(password, encoded) {
+    const parsed = parse(encoded);
+    if (parsed === undefined)
+        return false;
+    const key = await gated(() => scrypt(password.normalize('NFKC'), parsed.salt, parsed.key.length, {
+        N: parsed.n,
+        r: parsed.r,
+        p: parsed.p,
+        maxmem: MAX_MEM,
+    }));
+    if (key.length !== parsed.key.length)
+        return false;
+    return timingSafeEqual(key, parsed.key);
+}
+/**
+ * Whether a stored hash was made with parameters weaker than the current ones.
+ *
+ * The caller rehashes on a successful sign-in, which is the only moment the
+ * plaintext exists. Without this, raising the cost protects nobody who already
+ * has an account.
+ */
+export function needsRehash(encoded) {
+    const parsed = parse(encoded);
+    if (parsed === undefined)
+        return true;
+    return parsed.n < N || parsed.r < R || parsed.p < P;
+}
+/**
+ * Spend the same work as a real verification, and fail.
+ *
+ * For the case where no user matched. Returning early there makes the response
+ * time say whether an address has an account — the enumeration oracle that
+ * makes a careful 404 elsewhere pointless. This burns a scrypt call against a
+ * fixed hash so the two paths cost the same.
+ *
+ * It is not exact, and cannot be: a database round trip that finds nothing is
+ * shorter than one that finds a row. It removes the difference that matters,
+ * which is the one measured in hundreds of milliseconds rather than in tenths
+ * of one.
+ */
+let decoy;
+export async function spendVerificationTime(password) {
+    decoy ??= await hashPassword(randomBytes(32).toString('base64url'));
+    await verifyPassword(password, decoy);
+    return false;
+}
+//# sourceMappingURL=passwords.js.map

package/dist/passwords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"passwords.js","sourceRoot":"","sources":["../passwords.ts"],"names":[],"mappings":"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"}

package/dist/redis.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A very small Redis client.
+ *
+ * Written rather than installed, for the same reason `metrics.ts` was: the
+ * commands needed here are five, RESP2 is a text protocol that fits on a page,
+ * and a dependency in a self-hosted security product is something every
+ * operator inherits. The alternative was pulling a client with its own
+ * transitive tree to run `INCR`.
+ *
+ * `NACRE_REDIS_URL` has been required configuration and Redis has been in every
+ * Compose profile — with the API waiting on its healthcheck — since before
+ * anything connected to it. That is what this closes: a service every
+ * deployment had to run, for nothing.
+ *
+ * Not a general-purpose client. No pub/sub, no cluster, no pipelining beyond
+ * what the callers here need, no reconnect backoff worth the name. When
+ * something needs more than this, replace it rather than growing it.
+ */
+export interface RedisOptions {
+    readonly url: string;
+    /** How long to wait for a reply before giving up on the connection. */
+    readonly timeoutMs?: number;
+}
+type Reply = string | number | null | Reply[];
+export declare class RedisError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class Redis {
+    #private;
+    constructor(options: RedisOptions);
+    /** One command. Reconnects once if the connection went away between calls. */
+    command(...parts: string[]): Promise<Reply>;
+    /**
+     * Several commands written together, answered in order.
+     *
+     * Not a transaction — no MULTI. The callers here want one round trip, not
+     * atomicity across commands, and saying so is better than implying more.
+     */
+    pipeline(...commands: readonly (readonly string[])[]): Promise<Reply[]>;
+    ping(): Promise<boolean>;
+    close(): void;
+}
+export {};
+//# sourceMappingURL=redis.d.ts.map

package/dist/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../redis.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,KAAK,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK,EAAE,CAAA;AAW7C,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,qBAAa,KAAK;;gBAUJ,OAAO,EAAE,YAAY;IAiHjC,8EAA8E;IACxE,OAAO,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;IAWjD;;;;;OAKG;IACG,QAAQ,CAAC,GAAG,QAAQ,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IA6BvE,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAQ9B,KAAK,IAAI,IAAI;CAId"}

package/dist/redis.js

@@ -0,0 +1,234 @@
+import { connect } from 'node:net';
+import { once } from 'node:events';
+const CRLF = '\r\n';
+/** RESP2 is length-prefixed, so a command is its parts with their byte lengths. */
+function encode(parts) {
+    let out = `*${parts.length}${CRLF}`;
+    for (const p of parts)
+        out += `$${Buffer.byteLength(p)}${CRLF}${p}${CRLF}`;
+    return out;
+}
+export class RedisError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'RedisError';
+    }
+}
+export class Redis {
+    #url;
+    #timeoutMs;
+    #socket;
+    #buffer = Buffer.alloc(0);
+    /** One resolver per in-flight command, in the order they were sent. */
+    #pending = [];
+    #connecting;
+    constructor(options) {
+        this.#url = new URL(options.url);
+        this.#timeoutMs = options.timeoutMs ?? 2000;
+    }
+    async #connectOnce() {
+        const socket = connect({
+            host: this.#url.hostname,
+            port: Number(this.#url.port || 6379),
+        });
+        socket.setNoDelay(true);
+        // A connect deadline, which `#timeoutMs` alone did not give: that guards
+        // replies, and a reply cannot time out on a connection that never opened.
+        //
+        // A restarted Redis refuses immediately and fails open in milliseconds,
+        // which is the case the fail-open was designed against. A *partitioned* one
+        // — a firewall dropping packets, a node that vanished — blackholes the SYN,
+        // and Linux retries it for around 127 seconds. Every rate-limited request
+        // blocked for that long before being allowed through, so the documented
+        // "a cache outage must not become an outage" turned into one anyway.
+        socket.setTimeout(this.#timeoutMs, () => {
+            socket.destroy(new RedisError(`redis did not accept a connection within ${this.#timeoutMs}ms`));
+        });
+        socket.on('data', (chunk) => {
+            this.#buffer = Buffer.concat([this.#buffer, chunk]);
+            this.#drain();
+        });
+        const fail = (cause) => {
+            // Everything in flight is lost with the connection. Rejecting rather than
+            // hanging is what lets the callers fall back on their own terms.
+            const pending = this.#pending;
+            this.#pending = [];
+            this.#socket = undefined;
+            this.#buffer = Buffer.alloc(0);
+            for (const p of pending)
+                p.reject(new RedisError('the redis connection closed', { cause }));
+        };
+        socket.on('error', fail);
+        // Guarded on identity: without it a late `close` from a socket that has
+        // already been replaced clears `#socket` and rejects the commands in flight
+        // on the *new* connection.
+        socket.on('close', () => {
+            if (this.#socket === socket || this.#socket === undefined)
+                fail(undefined);
+        });
+        await once(socket, 'connect');
+        // The deadline was for connecting. Replies have their own, per command.
+        socket.setTimeout(0);
+        this.#socket = socket;
+        // Auth and database come from the URL, so a deployment configures them in
+        // one place rather than in three.
+        const password = decodeURIComponent(this.#url.password);
+        const username = decodeURIComponent(this.#url.username);
+        if (password !== '') {
+            await this.#send(username === '' ? ['AUTH', password] : ['AUTH', username, password]);
+        }
+        const db = this.#url.pathname.replace(/^\//, '');
+        if (db !== '' && db !== '0')
+            await this.#send(['SELECT', db]);
+    }
+    async #ensure() {
+        if (this.#socket !== undefined)
+            return;
+        // One connect attempt shared by every caller that arrives while it runs.
+        this.#connecting ??= this.#connectOnce().finally(() => {
+            this.#connecting = undefined;
+        });
+        await this.#connecting;
+    }
+    /**
+     * Parse whatever complete replies are in the buffer and hand them to the
+     * waiting callers, in order. RESP2 answers in the order it was asked, which
+     * is what makes a queue of resolvers correct without request ids.
+     */
+    #drain() {
+        for (;;) {
+            const parsed = parse(this.#buffer, 0);
+            if (parsed === undefined)
+                return;
+            this.#buffer = this.#buffer.subarray(parsed.next);
+            const waiter = this.#pending.shift();
+            if (waiter === undefined)
+                continue;
+            if (parsed.error !== undefined)
+                waiter.reject(new RedisError(parsed.error));
+            else
+                waiter.resolve(parsed.value);
+        }
+    }
+    #send(parts) {
+        const socket = this.#socket;
+        if (socket === undefined)
+            return Promise.reject(new RedisError('not connected'));
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new RedisError(`redis did not answer ${parts[0]} within ${this.#timeoutMs}ms`));
+            }, this.#timeoutMs);
+            this.#pending.push({
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            socket.write(encode(parts));
+        });
+    }
+    /** One command. Reconnects once if the connection went away between calls. */
+    async command(...parts) {
+        await this.#ensure();
+        try {
+            return await this.#send(parts);
+        }
+        catch (error) {
+            if (!(error instanceof RedisError) || this.#socket !== undefined)
+                throw error;
+            await this.#ensure();
+            return this.#send(parts);
+        }
+    }
+    /**
+     * Several commands written together, answered in order.
+     *
+     * Not a transaction — no MULTI. The callers here want one round trip, not
+     * atomicity across commands, and saying so is better than implying more.
+     */
+    async pipeline(...commands) {
+        await this.#ensure();
+        const socket = this.#socket;
+        if (socket === undefined)
+            throw new RedisError('not connected');
+        const replies = commands.map((parts) => new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new RedisError(`redis did not answer ${parts[0]} in time`)), this.#timeoutMs);
+            this.#pending.push({
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+        }));
+        socket.write(commands.map(encode).join(''));
+        return Promise.all(replies);
+    }
+    async ping() {
+        try {
+            return (await this.command('PING')) === 'PONG';
+        }
+        catch {
+            return false;
+        }
+    }
+    close() {
+        this.#socket?.destroy();
+        this.#socket = undefined;
+    }
+}
+/** One RESP2 value, or undefined when the buffer does not hold a whole one. */
+function parse(buffer, at) {
+    if (at >= buffer.length)
+        return undefined;
+    const end = buffer.indexOf('\r\n', at);
+    if (end === -1)
+        return undefined;
+    const kind = String.fromCharCode(buffer[at]);
+    const body = buffer.toString('utf8', at + 1, end);
+    const after = end + 2;
+    switch (kind) {
+        case '+':
+            return { value: body, next: after };
+        case '-':
+            return { value: null, next: after, error: body };
+        case ':':
+            return { value: Number(body), next: after };
+        case '$': {
+            const length = Number(body);
+            if (length === -1)
+                return { value: null, next: after };
+            const stop = after + length;
+            if (buffer.length < stop + 2)
+                return undefined;
+            return { value: buffer.toString('utf8', after, stop), next: stop + 2 };
+        }
+        case '*': {
+            const count = Number(body);
+            if (count === -1)
+                return { value: null, next: after };
+            const items = [];
+            let cursor = after;
+            for (let i = 0; i < count; i++) {
+                const item = parse(buffer, cursor);
+                if (item === undefined)
+                    return undefined;
+                // An error inside an array belongs to that element; the callers here
+                // never send commands that can produce one, so it becomes a null.
+                items.push(item.error === undefined ? item.value : null);
+                cursor = item.next;
+            }
+            return { value: items, next: cursor };
+        }
+        default:
+            return { value: null, next: after, error: `unrecognised reply type ${kind}` };
+    }
+}
+//# sourceMappingURL=redis.js.map

package/dist/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.js","sourceRoot":"","sources":["../redis.ts"],"names":[],"mappings":"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"}

package/dist/reindex.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The state of a layer's move to a different embedding model.
+ *
+ * Shared between the API, which starts one and reports on it, and the worker,
+ * which does the work — so the shape is defined once rather than agreed twice.
+ *
+ * ## What is built, and what is not
+ *
+ * `docs/architecture.md` specifies six steps. Four are here: add the new named
+ * vector, reindex existing documents in bounded batches, switch `vector_name`
+ * atomically, keep search available throughout.
+ *
+ * Two are not, and are named rather than quietly skipped:
+ *
+ * - **The Recall@10 gate.** Step 4 checks the new index against "the layer's
+ *   reference query set" before switching. There is no reference query set
+ *   anywhere in this product — not a table, not an endpoint, not a
+ *   configuration file — so building the gate would mean inventing the surface
+ *   it reads from, and a gate that checks against an empty set is a gate that
+ *   passes. Until it exists, a switch is a decision the operator makes by
+ *   starting the reindex, and `docs/architecture.md` says so.
+ * - **Dropping the old vector after a rollback window.** Step 6. The old vector
+ *   stays. It costs storage and it is what makes a rollback a one-statement
+ *   change, which is worth more than the space while this path is new.
+ */
+/** What `layers.reindex_state` holds. The migration's check constraint enforces it. */
+export interface ReindexState {
+    readonly status: 'running' | 'complete' | 'failed';
+    /**
+     * Which half of the migration is happening.
+     *
+     * `copying` is org-wide and cheap per point: the organization's collection is
+     * rebuilt with room for the new model and every point moves across carrying
+     * the vectors it already had. **No embeddings are computed.** It exists
+     * because a named vector cannot be added to a live Qdrant collection, so the
+     * only way to get one is to create a collection that already has it.
+     *
+     * `embedding` is per layer and is the expensive half: chunk text is embedded
+     * with the new model into the slot the copy created.
+     *
+     * The split is the whole point of the design. The cheap half happens once for
+     * the organization; the expensive half happens per layer, whenever the
+     * operator wants, with search running normally throughout.
+     */
+    readonly phase: 'copying' | 'embedding';
+    /**
+     * The named vector being written. Also the answer to "reindexed onto what",
+     * which is why it is required in every state including `failed` — a failed
+     * reindex leaves points behind and the name is how they are found.
+     */
+    readonly shadowVector: string;
+    /** The provider whose model produces it. */
+    readonly providerId: string;
+    readonly startedAt: string;
+    readonly finishedAt?: string;
+    /** Documents that had no shadow vector when the reindex began. */
+    readonly total: number;
+    /** Documents that have one now. Can exceed nothing; see `progress`. */
+    readonly done: number;
+    readonly failed: number;
+    readonly error?: string;
+}
+/**
+ * How far along, as a ratio, for `nacre_reindex_progress_ratio`.
+ *
+ * Clamped at 1 rather than allowed past it. `total` is counted once when the
+ * reindex starts and documents ingested afterwards are picked up by the same
+ * pass, so `done` legitimately overshoots — and a progress gauge reading 1.4
+ * makes an operator think the number is broken rather than that more work
+ * arrived. A reindex that is complete reads 1 whatever the counts say.
+ *
+ * Zero documents is 1, not 0. An empty layer is finished, and a gauge that sits
+ * at zero forever for a layer with nothing in it is the stuck-alert shape.
+ */
+export declare function reindexProgress(state: ReindexState): number;
+/** The JSON shape stored in the column. Snake case, like every other jsonb here. */
+export declare function toStateJson(state: ReindexState): Record<string, unknown>;
+/**
+ * Read it back, or `undefined` for a column that holds nothing usable.
+ *
+ * Undefined rather than a thrown error or a default: a layer with no reindex
+ * and a layer whose state cannot be parsed both mean "there is nothing to
+ * report", and the caller has no different action to take. The check constraint
+ * added in `0013` is what makes the second case not happen.
+ */
+export declare function fromStateJson(raw: unknown): ReindexState | undefined;
+//# sourceMappingURL=reindex.d.ts.map

package/dist/reindex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reindex.d.ts","sourceRoot":"","sources":["../reindex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,uFAAuF;AACvF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAA;IAClD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,WAAW,CAAA;IACvC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAQ3D;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAaxE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAsBpE"}