@stigmer/server 3.24.0 → 3.26.0

package/dist/store/postgres/store.d.ts

@@ -1,6 +1,7 @@
 import type { DescMessage, MessageShape } from "@bufbuild/protobuf";
 import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
-import type { AuditRecord, BootstrapStateStore, OAuthGrantStore, PendingOAuthStateStore, RawResourceDocument, ScheduleRunRecord, SearchIndexEntry, SearchIndexQuery, SearchIndexQueryResult, SignalDedupeStore, Store, WorkflowExecutionEventRecord } from "../interface.js";
+import type { AuditRecord, BootstrapStateStore, OAuthGrantStore, PendingOAuthStateStore, RawResourceDocument, ScheduleRunRecord, SearchIndexEntry, SearchIndexQuery, SearchIndexQueryResult, SignalDedupeStore, Store, StoreOpenOptions, WorkflowExecutionEventRecord } from "../interface.js";
+import type { ListIndexDeclaration, ListIndexQuery, ListIndexRow } from "../list-index.js";
 import type { StoreLogger } from "../logger.js";
 export declare class PostgresStore implements Store {
     readonly bootstrapState: BootstrapStateStore;
@@ -9,18 +10,23 @@ export declare class PostgresStore implements Store {
     readonly pendingOAuthStates: PendingOAuthStateStore;
     private pool;
     private readonly logger;
+    private readonly listIndexes;
     private constructor();
     /**
      * Connects to databaseUrl, runs migrations (advisory-locked, so
-     * concurrent boots serialize), and returns the ready store. Any failure
-     * here is a loud boot throw — never a degraded server (the same posture
-     * as SqliteStore.open; the composition root does not catch it).
+     * concurrent boots serialize), reconciles the list index (derives the
+     * facts of every unproven row of a declared kind; compare-and-set, so
+     * replicas opening together cannot conflict), and returns the ready
+     * store. Any failure here is a loud boot throw — never a degraded server
+     * (the same posture as SqliteStore.open; the composition root does not
+     * catch it).
      */
-    static open(databaseUrl: string, logger?: StoreLogger): Promise<PostgresStore>;
+    static open(databaseUrl: string, logger?: StoreLogger, options?: StoreOpenOptions): Promise<PostgresStore>;
     saveResource<Desc extends DescMessage>(kind: ApiResourceKind, id: string, schema: Desc, msg: MessageShape<Desc>): Promise<void>;
     getResource<Desc extends DescMessage>(kind: ApiResourceKind, id: string, schema: Desc): Promise<MessageShape<Desc>>;
     updateResource<Desc extends DescMessage>(kind: ApiResourceKind, id: string, schema: Desc, modify: (msg: MessageShape<Desc>) => void): Promise<MessageShape<Desc>>;
     listResources(kind: ApiResourceKind): Promise<Uint8Array[]>;
+    queryResources<K extends string>(declaration: ListIndexDeclaration<K>, query: ListIndexQuery<K>): Promise<ListIndexRow[]>;
     deleteResource(kind: ApiResourceKind, id: string): Promise<void>;
     findByField<Desc extends DescMessage>(kind: ApiResourceKind, fieldPath: string, value: string, schema: Desc): Promise<MessageShape<Desc>>;
     findAllByField(kind: ApiResourceKind, fieldPath: string, value: string): Promise<Uint8Array[]>;
@@ -29,6 +35,21 @@ export declare class PostgresStore implements Store {
     replaceResourceDataIfUnchanged(kind: ApiResourceKind, id: string, expectedData: Uint8Array, newData: Uint8Array): Promise<boolean>;
     deleteResourcesByKind(kind: ApiResourceKind): Promise<number>;
     deleteResourcesByIdPrefix(kind: ApiResourceKind, idPrefix: string): Promise<number>;
+    /**
+     * An unproven row's facts, derived from its bytes, and the row repaired
+     * when those bytes are still the stored ones — the compare-and-set on
+     * `data` means a newer write is never overwritten, and two replicas
+     * repairing one row write the same facts. Undefined when the bytes do
+     * not decode; the row stays unproven and is skipped, as a lane skips it.
+     */
+    private deriveAndRepair;
+    /**
+     * Derives every unproven row of each declared kind, in id-keyed batches,
+     * and stamps every other kind's unstamped rows (they carry no facts), so
+     * the unproven set is empty when the server starts serving. Reads stay
+     * exact without it; it keeps them cheap.
+     */
+    private reconcileListIndexes;
     saveAudit<Desc extends DescMessage>(kind: ApiResourceKind, resourceId: string, schema: Desc, msg: MessageShape<Desc>, versionHash: string, tag: string): Promise<void>;
     getAuditByHash<Desc extends DescMessage>(kind: ApiResourceKind, resourceId: string, versionHash: string, schema: Desc): Promise<MessageShape<Desc>>;
     getAuditByTag<Desc extends DescMessage>(kind: ApiResourceKind, resourceId: string, tag: string, schema: Desc): Promise<MessageShape<Desc>>;

package/dist/store/postgres/store.d.ts.map

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

package/dist/store/postgres/store.js

@@ -36,6 +36,7 @@
 import { fromBinary, toBinary } from "@bufbuild/protobuf";
 import pg from "pg";
 import { AuditNotFoundError, DELIVERED_SIGNAL_DEDUPE_TTL_MS, PENDING_OAUTH_STATE_TTL_MS, ResourceNotFoundError, } from "../interface.js";
+import { ListIndexRegistry, assertListIndexLimit, listIndexFactsOf, matchesListIndexQuery, mergeListIndexRows, sameListKeyRows, } from "../list-index.js";
 import { NOOP_STORE_LOGGER } from "../logger.js";
 import { apiResourceKindName, filterRowsByLabel, scanForFieldMatch, } from "../proto-fields.js";
 import { rfc3339Seconds } from "../rfc3339.js";
@@ -48,6 +49,46 @@ import { normalizeTsRankScore, renderTsQueryExpression } from "./tsquery.js";
  * silently returns wrong membership).
  */
 const TEXT_SEARCH_CONFIG = "english";
+/**
+ * The one upsert every resource write goes through: the row, its
+ * `updated_at`, and the list index's facts stamped with the SAME `now()`
+ * (constant within a transaction), so a later writer that bumps
+ * `updated_at` without knowing the index leaves the row unproven. An
+ * undeclared kind writes NULL facts and is stamped all the same, which
+ * keeps it out of the unproven partial index.
+ */
+const UPSERT_RESOURCE_SQL = `
+  INSERT INTO resources
+    (kind, id, data, updated_at, list_org, list_created_at, list_index_revision, list_indexed_at)
+  VALUES ($1, $2, $3, now(), $4, $5, $6, now())
+  ON CONFLICT (kind, id) DO UPDATE SET
+    data = excluded.data,
+    updated_at = excluded.updated_at,
+    list_org = excluded.list_org,
+    list_created_at = excluded.list_created_at,
+    list_index_revision = excluded.list_index_revision,
+    list_indexed_at = excluded.list_indexed_at`;
+/**
+ * The rows of kind `$1` whose facts are not proven current under revision
+ * `$2` (list-index.ts), each arm one index range that fetches a row only
+ * when it matches: the stamp arm repeats the partial index's predicate
+ * verbatim (the only form the planner matches it in), the revision arms
+ * are three ranges of the revision index. A single OR over the revision
+ * is answered, without statistics, by visiting every heap row of the kind
+ * (measured), which grows with the kind; these arms are empty in steady
+ * state. They overlap (an unstamped row has no revision either), so the
+ * caller keeps one row per id.
+ */
+const UNPROVEN_ROWS_SQL = `
+  SELECT id, data FROM resources WHERE kind = $1 AND list_indexed_at IS DISTINCT FROM updated_at
+  UNION ALL
+  SELECT id, data FROM resources WHERE kind = $1 AND list_index_revision IS NULL
+  UNION ALL
+  SELECT id, data FROM resources WHERE kind = $1 AND list_index_revision < $2
+  UNION ALL
+  SELECT id, data FROM resources WHERE kind = $1 AND list_index_revision > $2`;
+/** How many unproven rows the reconciliation at open decodes per round trip. */
+const RECONCILE_BATCH = 500;
 export class PostgresStore {
     bootstrapState;
     signalDedupe;
@@ -55,9 +96,11 @@ export class PostgresStore {
     pendingOAuthStates;
     pool;
     logger;
-    constructor(pool, logger) {
+    listIndexes;
+    constructor(pool, logger, listIndexes) {
         this.pool = pool;
         this.logger = logger;
+        this.listIndexes = listIndexes;
         this.bootstrapState = new PostgresBootstrapStateStore(() => this.open());
         this.signalDedupe = new PostgresSignalDedupeStore(() => this.open(), logger);
         this.oauthGrants = new PostgresOAuthGrantStore(() => this.open());
@@ -65,11 +108,15 @@ export class PostgresStore {
     }
     /**
      * Connects to databaseUrl, runs migrations (advisory-locked, so
-     * concurrent boots serialize), and returns the ready store. Any failure
-     * here is a loud boot throw — never a degraded server (the same posture
-     * as SqliteStore.open; the composition root does not catch it).
+     * concurrent boots serialize), reconciles the list index (derives the
+     * facts of every unproven row of a declared kind; compare-and-set, so
+     * replicas opening together cannot conflict), and returns the ready
+     * store. Any failure here is a loud boot throw — never a degraded server
+     * (the same posture as SqliteStore.open; the composition root does not
+     * catch it).
      */
-    static async open(databaseUrl, logger = NOOP_STORE_LOGGER) {
+    static async open(databaseUrl, logger = NOOP_STORE_LOGGER, options = {}) {
+        const listIndexes = new ListIndexRegistry(options.listIndexes ?? []);
         const pool = new pg.Pool({ connectionString: databaseUrl });
         // An idle pooled connection dropping (server restart, network blip)
         // emits 'error' on the pool; without a listener that is a process
@@ -91,15 +138,45 @@ export class PostgresStore {
             throw error;
         }
         client.release();
-        return new PostgresStore(pool, logger);
+        const store = new PostgresStore(pool, logger, listIndexes);
+        try {
+            await store.reconcileListIndexes();
+        }
+        catch (error) {
+            await store.close();
+            throw error;
+        }
+        return store;
     }
     // ---------------------------------------------------------------------------
     // Resource operations
     // ---------------------------------------------------------------------------
     async saveResource(kind, id, schema, msg) {
-        const data = toBinary(schema, msg);
-        await this.open().query(`INSERT INTO resources (kind, id, data, updated_at) VALUES ($1, $2, $3, now())
-       ON CONFLICT (kind, id) DO UPDATE SET data = excluded.data, updated_at = now()`, [apiResourceKindName(kind), id, Buffer.from(data)]);
+        const data = Buffer.from(toBinary(schema, msg));
+        const kindName = apiResourceKindName(kind);
+        const facts = this.listIndexes.factsOf(kind, msg);
+        if (facts === undefined) {
+            await this.open().query(UPSERT_RESOURCE_SQL, [
+                kindName,
+                id,
+                data,
+                null,
+                null,
+                null,
+            ]);
+            return;
+        }
+        await this.withTransaction(async (client) => {
+            await client.query(UPSERT_RESOURCE_SQL, [
+                kindName,
+                id,
+                data,
+                facts.org,
+                facts.createdAt,
+                facts.revision,
+            ]);
+            await replaceListKeys(client, kindName, id, facts);
+        });
     }
     async getResource(kind, id, schema) {
         const kindName = apiResourceKindName(kind);
@@ -116,15 +193,34 @@ export class PostgresStore {
         // per-resource atomicity contract. `modify` is synchronous by contract
         // (interface.ts), so no caller I/O can extend the lock's hold time.
         return this.withTransaction(async (client) => {
-            const result = await client.query(`SELECT data FROM resources WHERE kind = $1 AND id = $2 FOR UPDATE`, [kindName, id]);
+            const result = await client.query(`SELECT data, list_indexed_at IS NOT DISTINCT FROM updated_at AS stamped, list_index_revision
+         FROM resources WHERE kind = $1 AND id = $2 FOR UPDATE`, [kindName, id]);
             const row = result.rows[0];
             if (row === undefined) {
                 throw new ResourceNotFoundError(`${kindName}/${id}`);
             }
             const msg = fromBinary(schema, row.data);
+            const before = this.listIndexes.factsOf(kind, msg);
             modify(msg);
+            const after = this.listIndexes.factsOf(kind, msg);
             const data = toBinary(schema, msg);
-            await client.query(`UPDATE resources SET data = $3, updated_at = now() WHERE kind = $1 AND id = $2`, [kindName, id, Buffer.from(data)]);
+            await client.query(`UPDATE resources SET data = $3, updated_at = now(),
+           list_org = $4, list_created_at = $5, list_index_revision = $6, list_indexed_at = now()
+         WHERE kind = $1 AND id = $2`, [
+                kindName,
+                id,
+                Buffer.from(data),
+                after?.org ?? null,
+                after?.createdAt ?? null,
+                after?.revision ?? null,
+            ]);
+            if (after !== undefined &&
+                (!row.stamped ||
+                    row.list_index_revision !== after.revision ||
+                    before === undefined ||
+                    !sameListKeyRows(before, after))) {
+                await replaceListKeys(client, kindName, id, after);
+            }
             return msg;
         });
     }
@@ -132,8 +228,53 @@ export class PostgresStore {
         const result = await this.open().query(`SELECT data FROM resources WHERE kind = $1`, [apiResourceKindName(kind)]);
         return result.rows.map((row) => row.data);
     }
+    async queryResources(declaration, query) {
+        this.listIndexes.require(declaration);
+        assertListIndexLimit(query.limit);
+        if (query.anyKey !== undefined && query.anyKey.length === 0) {
+            return [];
+        }
+        const kindName = apiResourceKindName(declaration.kind);
+        // A key read is driven from the key table, ordered by that index's own
+        // columns, so the plan is one index range whatever the planner's
+        // statistics say (a freshly written table has none); several keys are
+        // one such read each, merged below. Without a key the organization
+        // index is the range.
+        const provenRows = [];
+        const reads = query.anyKey === undefined
+            ? [provenReadSql(kindName, declaration.revision, query, undefined)]
+            : query.anyKey.map((key) => provenReadSql(kindName, declaration.revision, query, key));
+        for (const read of reads) {
+            const result = await this.open().query(read.sql, read.params);
+            for (const row of result.rows) {
+                provenRows.push({
+                    id: row.id,
+                    data: row.data,
+                    cursor: { createdAt: row.created_at, id: row.id },
+                });
+            }
+        }
+        const unproven = await this.open().query(UNPROVEN_ROWS_SQL, [
+            kindName,
+            declaration.revision,
+        ]);
+        const unprovenRows = [];
+        for (const row of oneRowPerId(unproven.rows)) {
+            const facts = await this.deriveAndRepair(declaration, row.id, row.data);
+            if (facts !== undefined && matchesListIndexQuery(row.id, facts, query)) {
+                unprovenRows.push({
+                    id: row.id,
+                    data: row.data,
+                    cursor: { createdAt: facts.createdAt, id: row.id },
+                });
+            }
+        }
+        return mergeListIndexRows(provenRows, unprovenRows, query.limit);
+    }
     async deleteResource(kind, id) {
-        await this.open().query(`DELETE FROM resources WHERE kind = $1 AND id = $2`, [apiResourceKindName(kind), id]);
+        const kindName = apiResourceKindName(kind);
+        await this.open().query(`DELETE FROM resources WHERE kind = $1 AND id = $2`, [kindName, id]);
+        await this.open().query(`DELETE FROM resource_list_keys WHERE kind = $1 AND id = $2`, [kindName, id]);
     }
     async findByField(kind, fieldPath, value, schema) {
         const kindName = apiResourceKindName(kind);
@@ -168,26 +309,156 @@ export class PostgresStore {
     async replaceResourceDataIfUnchanged(kind, id, expectedData, newData) {
         // BYTEA equality in the WHERE clause makes the compare-and-swap one
         // atomic statement: zero rows changed means the row moved on (or was
-        // deleted) since the read — a lost swap, never an upsert.
-        const result = await this.open().query(`UPDATE resources SET data = $1, updated_at = now() WHERE kind = $2 AND id = $3 AND data = $4`, [
-            Buffer.from(newData),
-            apiResourceKindName(kind),
-            id,
-            Buffer.from(expectedData),
-        ]);
-        return result.rowCount === 1;
+        // deleted) since the read — a lost swap, never an upsert. The new bytes'
+        // list facts ride the same statement; bytes a declared kind's schema
+        // cannot decode leave the row unproven (stamp NULL), for a read to skip.
+        const kindName = apiResourceKindName(kind);
+        const declaration = this.listIndexes.declarationOf(kind);
+        const facts = declaration === undefined
+            ? undefined
+            : factsOfBytes(declaration, newData);
+        const swap = async (client) => {
+            const result = await client.query(`UPDATE resources SET data = $1, updated_at = now(),
+           list_org = $5, list_created_at = $6, list_index_revision = $7,
+           list_indexed_at = CASE WHEN $8::boolean THEN now() ELSE NULL END
+         WHERE kind = $2 AND id = $3 AND data = $4`, [
+                Buffer.from(newData),
+                kindName,
+                id,
+                Buffer.from(expectedData),
+                facts?.org ?? null,
+                facts?.createdAt ?? null,
+                facts?.revision ?? null,
+                declaration === undefined || facts !== undefined,
+            ]);
+            return result.rowCount === 1;
+        };
+        if (facts === undefined) {
+            return swap(this.open());
+        }
+        return this.withTransaction(async (client) => {
+            const swapped = await swap(client);
+            if (swapped) {
+                await replaceListKeys(client, kindName, id, facts);
+            }
+            return swapped;
+        });
     }
     async deleteResourcesByKind(kind) {
-        const result = await this.open().query(`DELETE FROM resources WHERE kind = $1`, [apiResourceKindName(kind)]);
+        const kindName = apiResourceKindName(kind);
+        const result = await this.open().query(`DELETE FROM resources WHERE kind = $1`, [kindName]);
+        await this.open().query(`DELETE FROM resource_list_keys WHERE kind = $1`, [
+            kindName,
+        ]);
         return result.rowCount ?? 0;
     }
     async deleteResourcesByIdPrefix(kind, idPrefix) {
         // LIKE with the wildcard characters of the PREFIX escaped — sqlite's
         // GLOB has no LIKE-metacharacter hazard, this port must not either.
-        const result = await this.open().query(`DELETE FROM resources WHERE kind = $1 AND id LIKE $2 ESCAPE '\\'`, [apiResourceKindName(kind), `${escapeLikePattern(idPrefix)}%`]);
+        const params = [
+            apiResourceKindName(kind),
+            `${escapeLikePattern(idPrefix)}%`,
+        ];
+        const result = await this.open().query(`DELETE FROM resources WHERE kind = $1 AND id LIKE $2 ESCAPE '\\'`, params);
+        await this.open().query(`DELETE FROM resource_list_keys WHERE kind = $1 AND id LIKE $2 ESCAPE '\\'`, params);
         return result.rowCount ?? 0;
     }
     // ---------------------------------------------------------------------------
+    // The list index's repair (list-index.ts)
+    // ---------------------------------------------------------------------------
+    /**
+     * An unproven row's facts, derived from its bytes, and the row repaired
+     * when those bytes are still the stored ones — the compare-and-set on
+     * `data` means a newer write is never overwritten, and two replicas
+     * repairing one row write the same facts. Undefined when the bytes do
+     * not decode; the row stays unproven and is skipped, as a lane skips it.
+     */
+    async deriveAndRepair(declaration, id, data) {
+        const kindName = apiResourceKindName(declaration.kind);
+        const facts = factsOfBytes(declaration, data);
+        if (facts === undefined) {
+            this.logger.warn("list index: an unproven row does not decode, skipping", {
+                kind: kindName,
+                id,
+            });
+            return undefined;
+        }
+        try {
+            await this.withTransaction(async (client) => {
+                const result = await client.query(`UPDATE resources SET list_org = $4, list_created_at = $5,
+             list_index_revision = $6, list_indexed_at = updated_at
+           WHERE kind = $1 AND id = $2 AND data = $3`, [
+                    kindName,
+                    id,
+                    Buffer.from(data),
+                    facts.org,
+                    facts.createdAt,
+                    facts.revision,
+                ]);
+                if (result.rowCount === 1) {
+                    await replaceListKeys(client, kindName, id, facts);
+                }
+            });
+        }
+        catch (error) {
+            // The facts are right whether or not they were written back; a
+            // failed repair only leaves the row for the next read to repair.
+            this.logger.warn("list index: repairing a row failed", {
+                kind: kindName,
+                id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        return facts;
+    }
+    /**
+     * Derives every unproven row of each declared kind, in id-keyed batches,
+     * and stamps every other kind's unstamped rows (they carry no facts), so
+     * the unproven set is empty when the server starts serving. Reads stay
+     * exact without it; it keeps them cheap.
+     */
+    async reconcileListIndexes() {
+        const declarations = this.listIndexes.declarations();
+        let reconciled = false;
+        for (const declaration of declarations) {
+            const kindName = apiResourceKindName(declaration.kind);
+            let after = "";
+            let derived = 0;
+            for (;;) {
+                const batch = await this.open().query(`SELECT id, data FROM (${UNPROVEN_ROWS_SQL}) unproven WHERE id > $3
+           ORDER BY id LIMIT $4`, [kindName, declaration.revision, after, RECONCILE_BATCH]);
+                // Duplicates from overlapping arms sit side by side in id order and
+                // the next batch starts after the last id, so none is repaired twice
+                // across batches and the count still ends the loop.
+                const rows = batch.rows;
+                for (const row of oneRowPerId(rows)) {
+                    if ((await this.deriveAndRepair(declaration, row.id, row.data)) !==
+                        undefined) {
+                        derived += 1;
+                    }
+                    after = row.id;
+                }
+                if (rows.length < RECONCILE_BATCH) {
+                    break;
+                }
+            }
+            if (derived > 0) {
+                this.logger.info("list index reconciled", {
+                    kind: kindName,
+                    rows: derived,
+                });
+                reconciled = true;
+            }
+        }
+        if (reconciled) {
+            // Every derived row's list columns changed at once; the planner's
+            // statistics for them are refreshed before the first read plans.
+            await this.open().query(`ANALYZE resources, resource_list_keys`);
+        }
+        await this.open().query(`UPDATE resources SET list_indexed_at = updated_at
+       WHERE list_indexed_at IS DISTINCT FROM updated_at AND NOT (kind = ANY($1::text[]))`, [declarations.map((d) => apiResourceKindName(d.kind))]);
+    }
+    // ---------------------------------------------------------------------------
     // Audit operations
     // ---------------------------------------------------------------------------
     async saveAudit(kind, resourceId, schema, msg, versionHash, tag) {
@@ -858,6 +1129,90 @@ class PostgresPendingOAuthStateStore {
         return result.rowCount ?? 0;
     }
 }
+/**
+ * A row's key rows made equal to its facts: one row per key the row
+ * names, the creation instant copied in so a parent's rows are one index
+ * range. Runs on the caller's transaction, beside the row write it
+ * belongs to.
+ */
+async function replaceListKeys(client, kindName, id, facts) {
+    await client.query(`DELETE FROM resource_list_keys WHERE kind = $1 AND id = $2`, [kindName, id]);
+    if (facts.keys.length === 0) {
+        return;
+    }
+    const params = [kindName, id, facts.createdAt];
+    const tuples = facts.keys.map((entry) => {
+        params.push(entry.key, entry.value);
+        return `($1, $2, $${params.length - 1}, $${params.length}, $3)`;
+    });
+    await client.query(`INSERT INTO resource_list_keys (kind, id, key, value, created_at) VALUES ${tuples.join(", ")}`, params);
+}
+/**
+ * One proven read of `queryResources`: through one key's index range when
+ * `key` is given (the key table drives, its copied creation instant is the
+ * order), else through the organization index. Only rows whose facts are
+ * proven current are returned; the unproven arm answers for the rest.
+ */
+function provenReadSql(kindName, revision, query, key) {
+    const params = [kindName, revision];
+    const param = (value) => {
+        params.push(value);
+        return `$${params.length}`;
+    };
+    const created = key === undefined ? "r.list_created_at" : "k.created_at";
+    const id = key === undefined ? `r.id COLLATE "C"` : `k.id COLLATE "C"`;
+    const where = [
+        `r.list_indexed_at = r.updated_at`,
+        `r.list_index_revision = $2`,
+    ];
+    let from = `resources r`;
+    if (key === undefined) {
+        where.unshift(`r.kind = $1`);
+    }
+    else {
+        // The row behind each key is fetched by primary key and nothing else:
+        // `OFFSET 0` keeps the subquery from being flattened, so a planner
+        // without statistics cannot reach it through the revision index
+        // instead (measured: a scan of the kind per key row).
+        from = `resource_list_keys k CROSS JOIN LATERAL (
+        SELECT id, data, updated_at, list_indexed_at, list_index_revision, list_org
+        FROM resources WHERE kind = k.kind AND id = k.id OFFSET 0
+      ) r`;
+        where.unshift(`k.kind = $1`, `k.key = ${param(key.name)}`, `k.value = ${param(key.value)}`);
+    }
+    if (query.org !== undefined && query.org !== "") {
+        where.push(`r.list_org = ${param(query.org)}`);
+    }
+    if (query.createdAtOrAfter !== undefined) {
+        where.push(`(${created} >= ${param(query.createdAtOrAfter)} OR ${created} = '')`);
+    }
+    if (query.after !== undefined) {
+        const afterCreated = param(query.after.createdAt);
+        const afterId = param(query.after.id);
+        where.push(`(${created} < ${afterCreated} OR (${created} = ${afterCreated} AND ${id} < ${afterId}))`);
+    }
+    const limit = query.limit === undefined ? "" : ` LIMIT ${param(query.limit)}`;
+    return {
+        sql: `SELECT r.id, r.data, ${created} AS created_at FROM ${from}
+          WHERE ${where.join(" AND ")}
+          ORDER BY ${created} DESC, ${id} DESC${limit}`,
+        params,
+    };
+}
+/** Keeps the first row per id; the unproven arms overlap. */
+function oneRowPerId(rows) {
+    const seen = new Set();
+    return rows.filter((row) => seen.has(row.id) ? false : (seen.add(row.id), true));
+}
+/** A declared kind's facts from stored bytes; undefined when they do not decode. */
+function factsOfBytes(declaration, data) {
+    try {
+        return listIndexFactsOf(declaration, fromBinary(declaration.schema, data));
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Escapes LIKE metacharacters so a prefix matches literally. */
 function escapeLikePattern(value) {
     return value