@nacre.work/api 0.1.0 → 0.3.0

package/dist/adapters.js

@@ -1,4 +1,4 @@
-import { aclTags, buildFilter, effectivePrincipals, fromStateJson, loadGrants, loadScopeTree, PostgresGroupGraph, referenceAllows, reindexProgress, resolve, toStateJson, VectorStore, vectorName, withOrg, } from '@nacre.work/core';
+import { buildFilter, cachedEffectivePrincipals, documentKey, effectivePrincipals, fromStateJson, loadGrants, loadGroupsVersion, loadScopeTree, PostgresGroupGraph, referenceAllows, reindexProgress, activeResolver, admitIngest, toStateJson, VectorStore, vectorName, withOrg, } from '@nacre.work/core';
 import { createHash } from 'node:crypto';
 import { encodeCursor, pageOf } from './pagination.js';
 import { applyRanking } from './rerank.js';
@@ -6,6 +6,8 @@ export class PostgresDocuments {
     pool;
     payload;
     role;
+    principalsCache;
+    presign;
     constructor(pool, 
     /**
      * What writes metadata into the payload of a document's points.
@@ -14,10 +16,22 @@ export class PostgresDocuments {
      * has no business searching, and a port that could would let a later change
      * reach the index without a plan.
      */
-    payload, role) {
+    payload, role, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache, 
+    /**
+     * Where a `source_url` comes from, when a deployment has object storage.
+     *
+     * Absent leaves the field off the response entirely, which is what every
+     * deployment without a bucket should see: a document whose bytes are in
+     * `documents.source_ref` has nothing to link to.
+     */
+    presign) {
         this.pool = pool;
         this.payload = payload;
         this.role = role;
+        this.principalsCache = principalsCache;
+        this.presign = presign;
     }
     /**
      * Undefined for absent, for another organization's, and for one this caller
@@ -39,11 +53,11 @@ export class PostgresDocuments {
             // The plan first. Reading the row and then checking is the same
             // information leak with extra steps if the check is ever forgotten,
             // and the layer a document sits in is what the grant is on.
-            const plan = resolve(await contextFor(client, auth), 'read');
+            const plan = activeResolver().resolve(await contextFor(client, auth, this.principalsCache), 'read');
             if (plan.kind === 'none')
                 return undefined;
             const { rows } = await client.query(`SELECT d.id, d.title, d.layer_id, l.slug AS layer, d.status, d.chunk_count,
-                  d.updated_at, d.metadata
+                  d.updated_at, d.metadata, d.source_type, d.source_ref
              FROM documents d
              JOIN layers l ON l.id = d.layer_id AND l.org_id = d.org_id
             WHERE d.org_id = $1 AND d.id = $2 AND d.deleted_at IS NULL`, [orgId, documentId]);
@@ -71,6 +85,17 @@ export class PostgresDocuments {
                 // tag has no way to tell a successful write from a dropped one — and
                 // this field was dropped by the handler for as long as it existed.
                 metadata: (row.metadata ?? {}),
+                // Minted here and nowhere earlier: everything above this line is the
+                // permission check, so a link exists only for a caller who has just
+                // been found to hold `read` on this document. `write` alone does not
+                // reach here — rule 6 — and neither does a denied document.
+                //
+                // Only for `s3`. An `inline` document has no object, and a `url` one
+                // is somebody else's address that this system has no business
+                // signing.
+                ...(this.presign !== undefined && row.source_type === 's3' && row.source_ref !== null
+                    ? { source_url: this.presign.url(row.source_ref) }
+                    : {}),
             };
         }, this.role === undefined ? {} : { role: this.role });
     }
@@ -102,7 +127,7 @@ export class PostgresDocuments {
             const collection = orgs[0]?.vector_collection;
             if (collection === undefined)
                 return false;
-            const plan = resolve(await contextFor(client, auth), 'write');
+            const plan = activeResolver().resolve(await contextFor(client, auth, this.principalsCache), 'write');
             if (plan.kind === 'none')
                 return false;
             const { rows } = await client.query(`SELECT layer_id FROM documents
@@ -146,11 +171,10 @@ export class NacreSearchService {
             const collection = orgs[0]?.vector_collection;
             if (collection === undefined)
                 return undefined;
-            const graph = await PostgresGroupGraph.load(client, auth.orgId);
-            const principals = effectivePrincipals(auth.principal, graph);
+            const principals = await principalsFor(client, auth, this.deps.principalsCache);
             const grants = await loadGrants(client, auth.orgId, principals);
             const tree = await loadScopeTree(client, auth.orgId, grants.filter((g) => g.scope.type === 'document').map((g) => g.scope.id));
-            const plan = resolve({ orgId: auth.orgId, role: auth.role, principals, grants, tree }, 'read');
+            const plan = activeResolver().resolve({ orgId: auth.orgId, role: auth.role, principals, grants, tree }, 'read');
             // Every live layer with the model it is on. Small — an installation
             // runs tens of layers per organization, not thousands — and it is what
             // decides how many branches the query has.
@@ -495,6 +519,10 @@ export class PostgresAudit {
                 event.requestId,
             ]);
         }, this.role === undefined ? {} : { role: this.role });
+        // Forwarding to a module's sinks is deliberately *not* here. It is
+        // `withAuditSinks`, applied to whatever port a surface was handed, because
+        // a sink wants every recorded event and not every event this adapter
+        // happened to record.
     }
 }
 /**
@@ -569,7 +597,6 @@ export class HttpEmbedder {
         });
     }
 }
-export { aclTags };
 export class NacreIngest {
     deps;
     constructor(deps) {
@@ -583,11 +610,10 @@ export class NacreIngest {
     }
     /** The layers this caller may write to, by slug. */
     async writableLayer(client, auth, layerSlug) {
-        const graph = await PostgresGroupGraph.load(client, auth.orgId);
-        const principals = effectivePrincipals(auth.principal, graph);
+        const principals = await principalsFor(client, auth, this.deps.principalsCache);
         const grants = await loadGrants(client, auth.orgId, principals);
         const tree = await loadScopeTree(client, auth.orgId, grants.filter((g) => g.scope.type === 'document').map((g) => g.scope.id));
-        const plan = resolve({ orgId: auth.orgId, role: auth.role, principals, grants, tree }, 'write');
+        const plan = activeResolver().resolve({ orgId: auth.orgId, role: auth.role, principals, grants, tree }, 'write');
         if (plan.kind === 'none')
             return undefined;
         const { rows } = await client.query(`SELECT id FROM layers WHERE org_id = $1 AND slug = $2 AND deleted_at IS NULL`, [auth.orgId, layerSlug]);
@@ -605,9 +631,46 @@ export class NacreIngest {
             const layerId = await this.writableLayer(client, auth, request.layer);
             if (layerId === undefined)
                 return undefined;
-            const source = request.content !== undefined ? request.content : request.url;
-            const sourceType = request.content !== undefined ? 'inline' : 'url';
+            const inline = request.content !== undefined;
+            const source = inline ? request.content : request.url;
             const hash = createHash('sha256').update(source, 'utf8').digest('hex');
+            // A module's ingest gate, after write is established and before anything
+            // is stored, so a refusal leaves neither a row nor an object behind. No
+            // gate registered is the open core admitting every document a caller may
+            // write, which is what it did before this point existed. A refusal
+            // becomes the handler's 4xx; it is not `undefined`, because that would
+            // read as "unwritable" and hide the layer the caller just wrote against.
+            const refusal = await admitIngest({
+                orgId: auth.orgId,
+                layerId,
+                principal: auth.principal,
+                role: auth.role,
+                externalId: request.externalId,
+                bytes: new TextEncoder().encode(source).byteLength,
+            });
+            if (refusal !== undefined) {
+                return { refused: true, status: refusal.status, reason: refusal.reason };
+            }
+            // Bytes to object storage before the row, never after.
+            //
+            // The reverse fails unrecoverably, which is the same argument the
+            // delete path is ordered by: a row that names an object which was never
+            // written is a document the worker fails on every attempt, forever,
+            // with the API having answered `queued`. A PUT with no row is a stray
+            // object at a deterministic key that the next ingest overwrites.
+            //
+            // Only for inline content. A `url` document is a reference already, and
+            // copying somebody else's URL into our bucket at ingest time would be
+            // a fetch on the request path — which is exactly what the worker does
+            // later, with a timeout and a sandbox.
+            let sourceType = inline ? 'inline' : 'url';
+            let sourceRef = source;
+            if (inline && this.deps.objects !== undefined) {
+                const key = documentKey(auth.orgId, layerId, request.externalId);
+                await this.deps.objects.put(key, new TextEncoder().encode(source), 'text/plain');
+                sourceType = 's3';
+                sourceRef = key;
+            }
             const { rows } = await client.query(`INSERT INTO documents
              (org_id, layer_id, external_id, source_type, source_ref, title, content_hash, metadata, status)
            VALUES ($1,$2,$3,$4,$5,$6,$7,$8,'pending')
@@ -640,7 +703,7 @@ export class NacreIngest {
                 layerId,
                 request.externalId,
                 sourceType,
-                source,
+                sourceRef,
                 request.title ?? null,
                 `sha256:${hash}`,
                 JSON.stringify(request.metadata),
@@ -667,11 +730,10 @@ export class NacreIngest {
             const collection = orgs[0]?.vector_collection;
             if (collection === undefined)
                 return false;
-            const graph = await PostgresGroupGraph.load(client, auth.orgId);
-            const principals = effectivePrincipals(auth.principal, graph);
+            const principals = await principalsFor(client, auth, this.deps.principalsCache);
             const grants = await loadGrants(client, auth.orgId, principals);
             const tree = await loadScopeTree(client, auth.orgId, [documentId]);
-            const plan = resolve({ orgId: auth.orgId, role: auth.role, principals, grants, tree }, 'write');
+            const plan = activeResolver().resolve({ orgId: auth.orgId, role: auth.role, principals, grants, tree }, 'write');
             if (plan.kind === 'none')
                 return false;
             const { rows } = await client.query(`SELECT layer_id FROM documents
@@ -727,9 +789,13 @@ export class NacreIngest {
 export class PostgresJobs {
     pool;
     role;
-    constructor(pool, role) {
+    principalsCache;
+    constructor(pool, role, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache) {
         this.pool = pool;
         this.role = role;
+        this.principalsCache = principalsCache;
     }
     async read(auth, jobId) {
         const orgId = auth.orgId;
@@ -740,7 +806,7 @@ export class PostgresJobs {
             // different projection — and needs the same check. The status and the
             // error string are both facts about a document the caller may not be
             // allowed to know exists.
-            const plan = resolve(await contextFor(client, auth), 'read');
+            const plan = activeResolver().resolve(await contextFor(client, auth, this.principalsCache), 'read');
             if (plan.kind === 'none')
                 return undefined;
             const { rows } = await client.query(`SELECT id, status, error, chunk_count, layer_id FROM documents
@@ -773,10 +839,24 @@ export class PostgresJobs {
         }, this.role === undefined ? {} : { role: this.role });
     }
 }
+async function principalsFor(client, auth, cache) {
+    if (cache === undefined) {
+        return effectivePrincipals(auth.principal, await PostgresGroupGraph.load(client, auth.orgId));
+    }
+    // In the same transaction as the grants that follow, so the key and the grant
+    // set describe one instant. Read separately, there is a window where the
+    // version says "fresh" about a set loaded before a change.
+    const groupsVersion = await loadGroupsVersion(client, auth.orgId);
+    return cachedEffectivePrincipals({
+        orgId: auth.orgId,
+        principal: auth.principal,
+        groupsVersion,
+        ttlSeconds: cache.ttlSeconds,
+    }, cache.store, () => PostgresGroupGraph.load(client, auth.orgId));
+}
 /** The per-request permission context, loaded once and asked several questions. */
-async function contextFor(client, auth) {
-    const graph = await PostgresGroupGraph.load(client, auth.orgId);
-    const principals = effectivePrincipals(auth.principal, graph);
+async function contextFor(client, auth, cache) {
+    const principals = await principalsFor(client, auth, cache);
     const grants = await loadGrants(client, auth.orgId, principals);
     const tree = await loadScopeTree(client, auth.orgId, grants.filter((g) => g.scope.type === 'document').map((g) => g.scope.id));
     return { orgId: auth.orgId, role: auth.role, principals, grants, tree };
@@ -785,6 +865,7 @@ export class PostgresLayers {
     pool;
     vectors;
     role;
+    principalsCache;
     constructor(pool, 
     /**
      * Only to ask which named vectors the organization's collection has.
@@ -797,10 +878,13 @@ export class PostgresLayers {
      * answered 202 and the row says `pending`. Checking here is what turns that
      * into a collection rebuild instead.
      */
-    vectors, role) {
+    vectors, role, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache) {
         this.pool = pool;
         this.vectors = vectors;
         this.role = role;
+        this.principalsCache = principalsCache;
     }
     get scope() {
         return this.role === undefined ? {} : { role: this.role };
@@ -815,7 +899,7 @@ export class PostgresLayers {
      */
     async list(auth, page) {
         return withOrg(this.pool, auth.orgId, async (client) => {
-            const plan = resolve(await contextFor(client, auth), 'read');
+            const plan = activeResolver().resolve(await contextFor(client, auth, this.principalsCache), 'read');
             if (plan.kind === 'none')
                 return { items: [], nextCursor: null };
             // The count comes from the same statement. It is what a catalog is
@@ -829,7 +913,12 @@ export class PostgresLayers {
             // grants exist — a commercial module — this becomes a number that
             // discloses more than the caller can reach, and it has to be recomputed
             // per caller or dropped.
+            // `created_at::text` beside `created_at`, and the cursor is built from
+            // it. See `Position.createdAt` — a timestamp that has been through a
+            // JavaScript `Date` is truncated to milliseconds, and a truncated bound
+            // matches the row it came from all over again.
             const projection = `l.id, l.slug, l.name, l.workspace_id, l.description, l.created_at,
+              l.created_at::text AS created_at_text,
               (SELECT count(*) FROM documents d
                 WHERE d.layer_id = l.id AND d.deleted_at IS NULL) AS document_count`;
             // Ordered by (created_at, id) rather than by slug, because that is the
@@ -857,17 +946,20 @@ export class PostgresLayers {
                 documentCount: Number(r.document_count),
                 createdAt: r.created_at.toISOString(),
             }));
-            return pageOf(layers, page, (l) => ({ createdAt: l.createdAt, id: l.id }));
+            return pageOf(layers, page, (l, i) => ({
+                createdAt: rows[i].created_at_text,
+                id: l.id,
+            }));
         }, this.scope);
     }
     async update(auth, layerId, input) {
-        return updateLayer(this.pool, auth, layerId, input, this.role);
+        return updateLayer(this.pool, auth, layerId, input, this.role, this.principalsCache);
     }
     async create(auth, input) {
         if (!/^[0-9a-f-]{36}$/i.test(input.workspaceId))
             return { kind: 'denied' };
         return withOrg(this.pool, auth.orgId, async (client) => {
-            const context = await contextFor(client, auth);
+            const context = await contextFor(client, auth, this.principalsCache);
             // `referenceAllows` and not `resolve`: the question is "may they
             // administer this one workspace", which is what the reference answers
             // directly. Reading it out of a flattened plan would mean inferring a
@@ -994,9 +1086,13 @@ export class PostgresLayers {
 export class PostgresWorkspaces {
     pool;
     role;
-    constructor(pool, role) {
+    principalsCache;
+    constructor(pool, role, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache) {
         this.pool = pool;
         this.role = role;
+        this.principalsCache = principalsCache;
     }
     get scope() {
         return this.role === undefined ? {} : { role: this.role };
@@ -1022,7 +1118,7 @@ export class PostgresWorkspaces {
      */
     async list(auth, page) {
         return withOrg(this.pool, auth.orgId, async (client) => {
-            const context = await contextFor(client, auth);
+            const context = await contextFor(client, auth, this.principalsCache);
             // No early return on `plan.kind === 'none'`, and that is the whole
             // point of this endpoint.
             //
@@ -1033,13 +1129,28 @@ export class PostgresWorkspaces {
             // administer, and therefore unable to create the first layer in it,
             // which is the deadlock this endpoint was added to break. It was
             // written that way first and caught by running it.
-            const plan = resolve(context, 'read');
-            const { rows } = await client.query(`SELECT w.id, w.slug, w.name, w.created_at,
+            const plan = activeResolver().resolve(context, 'read');
+            // Seek and limit in SQL.
+            //
+            // Neither was here: the statement fetched every workspace in the
+            // organization, ignored `page.after` entirely, and handed the whole
+            // list to `pageOf` — which then answered "there is another page"
+            // because the list was at least as long as the limit. So
+            // `GET /v1/workspaces` returned the same complete list on every page
+            // and never terminated, and a client following `next_cursor` looped
+            // forever. Found by a test that walked the listing one item at a time.
+            const after = page?.after;
+            const seek = after === undefined ? '' : ' AND (w.created_at, w.id) > ($2::timestamptz, $3::uuid)';
+            // One extra, because the filter below removes rows the caller may not
+            // reach: without it a page whose last row is filtered out would report
+            // itself as the end of the collection.
+            const cap = page === undefined ? '' : ` LIMIT ${page.limit + 1}`;
+            const { rows } = await client.query(`SELECT w.id, w.slug, w.name, w.created_at, w.created_at::text AS created_at_text,
                   (SELECT array_agg(l.id) FROM layers l
                     WHERE l.workspace_id = w.id AND l.deleted_at IS NULL) AS layer_ids
              FROM workspaces w
-            WHERE w.org_id = $1 AND w.deleted_at IS NULL
-            ORDER BY w.created_at, w.id`, [auth.orgId]);
+            WHERE w.org_id = $1 AND w.deleted_at IS NULL${seek}
+            ORDER BY w.created_at, w.id${cap}`, after === undefined ? [auth.orgId] : [auth.orgId, after.createdAt, after.id]);
             const reachable = rows.filter((w) => {
                 if (plan.kind === 'all')
                     return true;
@@ -1052,14 +1163,28 @@ export class PostgresWorkspaces {
                 // for a workspace with nothing in it yet.
                 return referenceAllows(context, { type: 'workspace', id: w.id }, 'read');
             });
-            const items = reachable.map((w) => ({
+            const fetched = page === undefined ? rows : rows.slice(0, page.limit);
+            const items = reachable
+                .filter((w) => fetched.some((f) => f.id === w.id))
+                .map((w) => ({
                 id: w.id,
                 slug: w.slug,
                 name: w.name,
                 layerCount: (w.layer_ids ?? []).length,
                 createdAt: w.created_at.toISOString(),
             }));
-            return pageOf(items, page, (w) => ({ createdAt: w.createdAt, id: w.id }));
+            // From the last row **fetched**, not the last returned — the same rule
+            // the grant listing follows and for the same reason: the filter above
+            // removes rows the caller may not reach, and a cursor taken from a
+            // survivor would skip everything the filter dropped after it.
+            //
+            // Which makes a short page normal here rather than a signal, and
+            // `next_cursor` the only thing that says whether more exist.
+            const lastFetched = fetched[fetched.length - 1];
+            const nextCursor = page !== undefined && rows.length > page.limit && lastFetched !== undefined
+                ? encodeCursor({ createdAt: lastFetched.created_at_text, id: lastFetched.id })
+                : null;
+            return { items, nextCursor };
         }, this.scope);
     }
     /**
@@ -1114,13 +1239,13 @@ export class PostgresWorkspaces {
  * description is built from, so an agent's picture of what a layer holds
  * changes with it. That is the reason it is editable at all.
  */
-async function updateLayer(pool, auth, layerId, input, role) {
+async function updateLayer(pool, auth, layerId, input, role, principalsCache) {
     if (!/^[0-9a-f-]{36}$/i.test(layerId))
         return false;
     if (input.name === undefined && input.description === undefined)
         return false;
     return withOrg(pool, auth.orgId, async (client) => {
-        const context = await contextFor(client, auth);
+        const context = await contextFor(client, auth, principalsCache);
         // The layer's workspace, before anything is decided — the grant is on the
         // workspace, so there is nothing to ask until we know which one.
         const { rows } = await client.query(`SELECT workspace_id FROM layers
@@ -1147,9 +1272,13 @@ async function updateLayer(pool, auth, layerId, input, role) {
 export class PostgresGrants {
     pool;
     role;
-    constructor(pool, role) {
+    principalsCache;
+    constructor(pool, role, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache) {
         this.pool = pool;
         this.role = role;
+        this.principalsCache = principalsCache;
     }
     get scope() {
         return this.role === undefined ? {} : { role: this.role };
@@ -1177,15 +1306,15 @@ export class PostgresGrants {
      */
     async list(auth, page) {
         return withOrg(this.pool, auth.orgId, async (client) => {
-            const context = await contextFor(client, auth);
-            const plan = resolve(context, 'admin');
+            const context = await contextFor(client, auth, this.principalsCache);
+            const plan = activeResolver().resolve(context, 'admin');
             if (plan.kind === 'none')
                 return { items: [], nextCursor: null };
             const after = page?.after;
             const seek = after === undefined ? '' : ' AND (created_at, id) > ($2::timestamptz, $3::uuid)';
             const cap = page === undefined ? '' : ` LIMIT ${page.limit}`;
             const { rows } = await client.query(`SELECT id, principal_type, principal_id, scope_type, scope_id, permission, effect, source,
-                  created_at
+                  created_at, created_at::text AS created_at_text
              FROM grants WHERE org_id = $1${seek} ORDER BY created_at, id${cap}`, after === undefined ? [auth.orgId] : [auth.orgId, after.createdAt, after.id]);
             const visible = rows
                 .filter((r) => referenceAllows(context, { type: r.scope_type, id: r.scope_id }, 'admin'))
@@ -1205,7 +1334,7 @@ export class PostgresGrants {
             // it — a page of grants silently missing from an administrator's view.
             const lastFetched = rows[rows.length - 1];
             const nextCursor = page !== undefined && rows.length >= page.limit && lastFetched !== undefined
-                ? encodeCursor({ createdAt: lastFetched.created_at.toISOString(), id: lastFetched.id })
+                ? encodeCursor({ createdAt: lastFetched.created_at_text, id: lastFetched.id })
                 : null;
             return { items: visible, nextCursor };
         }, this.scope);
@@ -1215,12 +1344,39 @@ export class PostgresGrants {
             return undefined;
         }
         return withOrg(this.pool, auth.orgId, async (client) => {
-            const context = await contextFor(client, auth);
+            const context = await contextFor(client, auth, this.principalsCache);
             // Admin on the scope being granted, not admin in general. Otherwise
             // anyone holding admin on one layer could grant themselves another.
             if (!referenceAllows(context, { type: input.scopeType, id: input.scopeId }, 'admin')) {
                 return undefined;
             }
+            // And the scope has to exist in this organization, which the check
+            // above does not establish. `referenceAllows` returns `true` for
+            // `org_admin` on its third line — rule 3, admin on every scope
+            // implicitly — and it returns *before* the scope is placed, so an
+            // administrator naming any uuid at all passed.
+            //
+            // Not a leak, and the reason is worth stating rather than assumed: a
+            // grant on a scope that is not here becomes `should: layer_id = X`
+            // beside an unconditional `must: org_id = <this tenant>`, and points
+            // carrying layer X belong to another tenant and live in another
+            // collection. The second line of defence holds. What got written was a
+            // row that permits nothing and points at nothing.
+            //
+            // It still has to be refused. An administrator reading `/v1/grants`
+            // sees a grant they cannot explain on an id they cannot look up, and
+            // `404` stops meaning what invariant 4 says it means — "no permission"
+            // and "no such object" are one answer, which requires that naming a
+            // nonexistent object *reaches* that answer rather than succeeding.
+            //
+            // Written out per table rather than assembled, so the table name can
+            // never come from a caller-supplied string. `scopeType` is a checked
+            // union already; this makes it structural.
+            const exists = await client.query(input.scopeType === 'workspace'
+                ? `SELECT 1 FROM workspaces WHERE org_id = $1 AND id = $2 AND deleted_at IS NULL`
+                : `SELECT 1 FROM layers WHERE org_id = $1 AND id = $2 AND deleted_at IS NULL`, [auth.orgId, input.scopeId]);
+            if (exists.rowCount !== 1)
+                return undefined;
             const { rows } = await client.query(`INSERT INTO grants
              (org_id, principal_type, principal_id, scope_type, scope_id, permission, effect, source)
            VALUES ($1,$2,$3,$4,$5,$6,'allow','api')
@@ -1274,7 +1430,7 @@ export class PostgresGrants {
             // because the object is a grant rather than a document.
             if (row === undefined)
                 return false;
-            const context = await contextFor(client, auth);
+            const context = await contextFor(client, auth, this.principalsCache);
             const scope = {
                 type: row.scope_type,
                 id: row.scope_id,
@@ -1318,9 +1474,13 @@ export class PostgresGrants {
 export class PostgresAuditReader {
     pool;
     role;
-    constructor(pool, role) {
+    principalsCache;
+    constructor(pool, role, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache) {
         this.pool = pool;
         this.role = role;
+        this.principalsCache = principalsCache;
     }
     /**
      * Actions that record a substantive access to a document's contents.
@@ -1370,7 +1530,8 @@ export class PostgresAuditReader {
             // without a second query and without a count — a count over a
             // retention window is the expensive thing this endpoint must not do on
             // every request.
-            const { rows } = await client.query(`SELECT id::text, occurred_at, actor_type, actor_id, actor_label, action,
+            const { rows } = await client.query(`SELECT id::text, occurred_at, occurred_at::text AS occurred_at_text,
+                  actor_type, actor_id, actor_label, action,
                   surface, client, target, result, detail, request_id
              FROM audit_events
             WHERE ${where.join(' AND ')}
@@ -1390,9 +1551,19 @@ export class PostgresAuditReader {
                 detail: r.detail ?? {},
                 requestId: r.request_id,
             }));
+            // From the row rather than from the mapped record, because the record
+            // carries an ISO string and this cursor needs full precision.
+            //
+            // This one **skips** rather than repeats, and that is the same bug seen
+            // from the other side: the ordering is descending, so a bound truncated
+            // downwards excludes the row it came from *and* everything between the
+            // truncated value and the real one. On a listing that would lose a page
+            // of layers; on the access log it silently loses events, in the one
+            // place the product promises a precise answer.
+            const lastRow = rows[Math.min(page.limit, rows.length) - 1];
             const last = items[items.length - 1];
-            const nextCursor = rows.length > page.limit && last !== undefined
-                ? encodeCursor({ createdAt: last.occurredAt, id: last.id })
+            const nextCursor = rows.length > page.limit && last !== undefined && lastRow !== undefined
+                ? encodeCursor({ createdAt: lastRow.occurred_at_text, id: last.id })
                 : null;
             return { items, nextCursor };
         }, this.scopeFor());
@@ -1426,10 +1597,14 @@ export class PostgresReindex {
     pool;
     vectors;
     role;
-    constructor(pool, vectors, role) {
+    principalsCache;
+    constructor(pool, vectors, role, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache) {
         this.pool = pool;
         this.vectors = vectors;
         this.role = role;
+        this.principalsCache = principalsCache;
     }
     get scope() {
         return this.role === undefined ? {} : { role: this.role };
@@ -1440,7 +1615,7 @@ export class PostgresReindex {
             // vector in the layer and changes which model answers every future
             // query — `read` is nowhere near enough, and `write` is about putting
             // documents in rather than about the layer itself.
-            const plan = resolve(await contextFor(client, auth), 'admin');
+            const plan = activeResolver().resolve(await contextFor(client, auth, this.principalsCache), 'admin');
             if (plan.kind === 'none')
                 return undefined;
             // Locked for the whole decision. Two starts arriving together would
@@ -1555,7 +1730,7 @@ export class PostgresReindex {
             // being migrated is not an administrative fact — it explains why a
             // result set moved — and hiding it from someone who can already read
             // the layer buys nothing.
-            const plan = resolve(await contextFor(client, auth), 'read');
+            const plan = activeResolver().resolve(await contextFor(client, auth, this.principalsCache), 'read');
             if (plan.kind === 'none')
                 return undefined;
             const { rows } = await client.query(`SELECT id, vector_name, reindex_state FROM layers
@@ -1606,7 +1781,87 @@ export class PostgresReindex {
             failed: state.failed,
             progress: reindexProgress(live),
             error: state.error ?? null,
+            check: state.check ?? null,
         };
     }
 }
+/**
+ * The reference query set behind the reindex recall gate.
+ *
+ * `admin` on the layer for both operations, and that is a decision rather than
+ * a copy of the reindex adapter above. Reading the set reveals which documents
+ * an operator considers the canonical answers to a query, which is a statement
+ * about the layer's contents; rule 7 makes `admin` the permission that implies
+ * being allowed to see them, and rule 6 means `write` does not.
+ */
+export class PostgresReferenceQueries {
+    pool;
+    role;
+    principalsCache;
+    constructor(pool, role, principalsCache) {
+        this.pool = pool;
+        this.role = role;
+        this.principalsCache = principalsCache;
+    }
+    get scope() {
+        return this.role === undefined ? {} : { role: this.role };
+    }
+    /**
+     * The layer, if this caller may administer it.
+     *
+     * `undefined` for a layer that is not there and for one they may not touch —
+     * one answer, which the handler turns into `404`. Deleted layers are not
+     * there: a reference set on a deleted layer describes nothing.
+     */
+    async administrable(client, auth, layerId) {
+        const plan = activeResolver().resolve(await contextFor(client, auth, this.principalsCache), 'admin');
+        if (plan.kind === 'none')
+            return false;
+        if (plan.kind === 'scoped' && !plan.layers.includes(layerId))
+            return false;
+        const { rows } = await client.query('SELECT id FROM layers WHERE org_id = $1 AND id = $2 AND deleted_at IS NULL', [auth.orgId, layerId]);
+        return rows.length > 0;
+    }
+    async list(auth, layerId) {
+        return withOrg(this.pool, auth.orgId, async (client) => {
+            if (!(await this.administrable(client, auth, layerId)))
+                return undefined;
+            const { rows } = await client.query(`SELECT id, query, expected FROM reference_queries
+            WHERE org_id = $1 AND layer_id = $2 ORDER BY ordinal`, [auth.orgId, layerId]);
+            return rows.map((r) => ({ id: r.id, query: r.query, expected: r.expected }));
+        }, this.scope);
+    }
+    async replace(auth, layerId, queries) {
+        return withOrg(this.pool, auth.orgId, async (client) => {
+            if (!(await this.administrable(client, auth, layerId)))
+                return undefined;
+            // Delete then insert, in the transaction `withOrg` already opened. A
+            // set is one statement about the layer, so there is no moment at which
+            // half of the old one and half of the new one are both in the table —
+            // which matters because the worker reads this to decide whether a layer
+            // has a gate at all.
+            await client.query('DELETE FROM reference_queries WHERE org_id = $1 AND layer_id = $2', [
+                auth.orgId,
+                layerId,
+            ]);
+            const inserted = [];
+            for (const [ordinal, q] of queries.entries()) {
+                const { rows } = await client.query(`INSERT INTO reference_queries (org_id, layer_id, query, expected, ordinal)
+             VALUES ($1, $2, $3, $4, $5) RETURNING id`, [auth.orgId, layerId, q.query, [...q.expected], ordinal]);
+                inserted.push({
+                    id: rows[0]?.id,
+                    query: q.query,
+                    expected: [...q.expected],
+                });
+            }
+            // The external ids are deliberately **not** validated against
+            // `documents` here. A reference set is often written before the
+            // documents it names are ingested, and refusing it then would make the
+            // gate impossible to set up on a new layer. The check resolves them
+            // when it runs, and an entry that resolves to nothing fails the reindex
+            // by name — which is the moment it actually matters.
+            return inserted;
+        }, this.scope);
+    }
+}
 //# sourceMappingURL=adapters.js.map