@nacre.work/api 0.1.0 → 0.2.0

package/dist/adapters.d.ts

@@ -1,4 +1,4 @@
-import { aclTags, buildFilter, VectorStore, type Metadata } from '@nacre.work/core';
+import { aclTags, buildFilter, VectorStore, type CacheStore, type Metadata } from '@nacre.work/core';
 import type { Pool } from 'pg';
 import { type Reranker } from './rerank.js';
 import type { Reindex, ReindexOutcome, ReindexStatus, AuditEvent, AuditQuery, AuditReader, AuditRecord, AuditSink, Documents, GrantInput, GrantRecord, Grants, Ingest, IngestOutcome, IngestRequest, Job, Jobs, Layer, LayerOutcome, DocumentView, Layers, Page, PageResult, Workspace, WorkspaceOutcome, Workspaces, SearchHit, SearchOptions, SearchService } from './server.js';
@@ -25,6 +25,16 @@ export declare class PostgresDocuments implements Documents {
      */
     private readonly payload;
     private readonly role?;
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    private readonly 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.
+     */
+    private readonly presign?;
     constructor(pool: Pool, 
     /**
      * What writes metadata into the payload of a document's points.
@@ -33,7 +43,19 @@ export declare class PostgresDocuments implements Documents {
      * has no business searching, and a port that could would let a later change
      * reach the index without a plan.
      */
-    payload: DocumentMetadataWriter, role?: string | undefined);
+    payload: DocumentMetadataWriter, role?: string | undefined, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache?: PrincipalsCache | undefined, 
+    /**
+     * 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?: {
+        url(key: string): string;
+    } | undefined);
     /**
      * Undefined for absent, for another organization's, and for one this caller
      * has no grant reaching — one answer for all three.
@@ -72,6 +94,8 @@ export interface DocumentMetadataWriter {
 }
 export interface SearchDeps {
     readonly pool: Pool;
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    readonly principalsCache?: PrincipalsCache;
     readonly vectors: VectorStore;
     /**
      * The query embedder for a given provider.
@@ -232,14 +256,29 @@ export { aclTags };
  */
 export interface IngestDeps {
     readonly pool: Pool;
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    readonly principalsCache?: PrincipalsCache;
     /**
      * What takes a document out of results. Narrower than `VectorStore` on
      * purpose: the delete path has no business searching, and a port that could
      * would let a later change reach the index without a plan.
      */
     readonly tombstone: DocumentTombstone;
+    /**
+     * Where document bytes go, when a deployment has object storage.
+     *
+     * Absent is the supported default and not a degraded mode: bytes then live in
+     * `documents.source_ref`, which is what every deployment did before this. The
+     * difference is what a Postgres dump weighs — with this set it holds
+     * references, without it, every document in full.
+     */
+    readonly objects?: ObjectStore;
     readonly role?: string;
 }
+export interface ObjectStore {
+    put(key: string, body: Uint8Array, contentType?: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
 export interface DocumentTombstone {
     tombstone(collection: string, documentId: string): Promise<void>;
 }
@@ -264,9 +303,43 @@ export declare class NacreIngest implements Ingest {
 export declare class PostgresJobs implements Jobs {
     private readonly pool;
     private readonly role?;
-    constructor(pool: Pool, role?: string | undefined);
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    private readonly principalsCache?;
+    constructor(pool: Pool, role?: string | undefined, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache?: PrincipalsCache | undefined);
     read(auth: AuthContext, jobId: string): Promise<Job | undefined>;
 }
+/**
+ * Where the effective-principals cache is consulted, and the only place.
+ *
+ * `NACRE_ACL_CACHE_TTL` was validated at startup and read by nothing: the cache
+ * in `packages/core/authz/cache.ts` was written, tested and never called, so
+ * every request recomputed the transitive group closure. `docs/authz.md` went
+ * further and described the cache as the reason T11 is satisfied *more strongly*
+ * than specified — a claim about a code path that did not run.
+ *
+ * The safety of caching a permission input at all rests on one property, and it
+ * is structural rather than temporal: **the key carries
+ * `organizations.groups_version`**, which database triggers bump on every change
+ * to `groups`, `group_members` and `grants`. A revoked grant is not served
+ * stale, it is not served at all — the next request composes a different key.
+ * Checked against a running database rather than read: create a group, add a
+ * member, remove one, grant, revoke, delete the group; the version moved for
+ * every one.
+ *
+ * So the TTL is a memory bound. It is not what makes revocation take effect,
+ * and lowering it does not make anything safer.
+ *
+ * Absent cache means compute it. That is the pre-existing behaviour and it is
+ * the slow direction, never the permissive one — which is also why
+ * `cachedEffectivePrincipals` may swallow a Redis failure without touching
+ * invariant I3: the fallback computes the same answer from the same rows.
+ */
+export interface PrincipalsCache {
+    readonly store: CacheStore;
+    readonly ttlSeconds: number;
+}
 export declare class PostgresLayers implements Layers {
     private readonly pool;
     /**
@@ -282,6 +355,8 @@ export declare class PostgresLayers implements Layers {
      */
     private readonly vectors;
     private readonly role?;
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    private readonly principalsCache?;
     constructor(pool: Pool, 
     /**
      * Only to ask which named vectors the organization's collection has.
@@ -296,7 +371,9 @@ export declare class PostgresLayers implements Layers {
      */
     vectors: {
         vectorsOf(collection: string): Promise<Record<string, number>>;
-    }, role?: string | undefined);
+    }, role?: string | undefined, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache?: PrincipalsCache | undefined);
     private get scope();
     /**
      * The layers this caller may read.
@@ -331,7 +408,11 @@ export declare class PostgresLayers implements Layers {
 export declare class PostgresWorkspaces implements Workspaces {
     private readonly pool;
     private readonly role?;
-    constructor(pool: Pool, role?: string | undefined);
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    private readonly principalsCache?;
+    constructor(pool: Pool, role?: string | undefined, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache?: PrincipalsCache | undefined);
     private get scope();
     /**
      * The workspaces this caller can reach, newest last, cursor-paged.
@@ -374,7 +455,11 @@ export declare class PostgresWorkspaces implements Workspaces {
 export declare class PostgresGrants implements Grants {
     private readonly pool;
     private readonly role?;
-    constructor(pool: Pool, role?: string | undefined);
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    private readonly principalsCache?;
+    constructor(pool: Pool, role?: string | undefined, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache?: PrincipalsCache | undefined);
     private get scope();
     /**
      * Every grant in the organization, for a caller who may administer it.
@@ -440,7 +525,11 @@ export declare class PostgresGrants implements Grants {
 export declare class PostgresAuditReader implements AuditReader {
     private readonly pool;
     private readonly role?;
-    constructor(pool: Pool, role?: string | undefined);
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    private readonly principalsCache?;
+    constructor(pool: Pool, role?: string | undefined, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache?: PrincipalsCache | undefined);
     /**
      * Actions that record a substantive access to a document's contents.
      *
@@ -488,9 +577,13 @@ export declare class PostgresReindex implements Reindex {
     private readonly pool;
     private readonly vectors;
     private readonly role?;
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    private readonly principalsCache?;
     constructor(pool: Pool, vectors: {
         vectorsOf(collection: string): Promise<Record<string, number>>;
-    }, role?: string | undefined);
+    }, role?: string | undefined, 
+    /** See `principalsFor`. Absent means recompute the closure every time. */
+    principalsCache?: PrincipalsCache | undefined);
     private get scope();
     start(auth: AuthContext, layerId: string, providerId: string): Promise<ReindexOutcome | undefined>;
     status(auth: AuthContext, layerId: string): Promise<ReindexStatus | undefined>;

package/dist/adapters.d.ts.map

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

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 { aclTags, buildFilter, cachedEffectivePrincipals, documentKey, effectivePrincipals, fromStateJson, loadGrants, loadGroupsVersion, loadScopeTree, PostgresGroupGraph, referenceAllows, reindexProgress, resolve, 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 = 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 = 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,8 +171,7 @@ 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');
@@ -583,8 +607,7 @@ 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');
@@ -605,9 +628,29 @@ 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');
+            // 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 +683,7 @@ export class NacreIngest {
                 layerId,
                 request.externalId,
                 sourceType,
-                source,
+                sourceRef,
                 request.title ?? null,
                 `sha256:${hash}`,
                 JSON.stringify(request.metadata),
@@ -667,8 +710,7 @@ 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');
@@ -727,9 +769,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 +786,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 = 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 +819,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 +845,7 @@ export class PostgresLayers {
     pool;
     vectors;
     role;
+    principalsCache;
     constructor(pool, 
     /**
      * Only to ask which named vectors the organization's collection has.
@@ -797,10 +858,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 +879,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 = 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
@@ -861,13 +925,13 @@ export class PostgresLayers {
         }, 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 +1058,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 +1090,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.
             //
@@ -1114,13 +1182,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 +1215,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,7 +1249,7 @@ export class PostgresGrants {
      */
     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);
             const plan = resolve(context, 'admin');
             if (plan.kind === 'none')
                 return { items: [], nextCursor: null };
@@ -1215,7 +1287,7 @@ 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')) {
@@ -1274,7 +1346,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 +1390,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.
@@ -1426,10 +1502,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 +1520,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 = 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 +1635,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 = 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