@undefineds.co/xpod 0.4.10 → 0.4.12

package/dist/http/SubgraphSparqlHttpHandler.d.ts

@@ -1,6 +1,6 @@
 import { HttpHandler } from '@solid/community-server';
 import type { HttpHandlerInput, HttpRequest, HttpResponse } from '@solid/community-server';
-import type { CredentialsExtractor, PermissionReader, Authorizer } from '@solid/community-server';
+import type { ActivityEmitter, CredentialsExtractor, PermissionReader, Authorizer } from '@solid/community-server';
 import { SubgraphQueryEngine } from '../storage/sparql/SubgraphQueryEngine';
 import { MixDataAccessor } from '../storage/accessors/MixDataAccessor';
 interface SubgraphSparqlHttpHandlerOptions {
@@ -41,9 +41,10 @@ export declare class SubgraphSparqlHttpHandler extends HttpHandler {
     private readonly usageRepo?;
     private readonly defaultBandwidthLimit?;
     private readonly updateAuthority?;
+    private readonly emitter?;
     private readonly generator;
     private static readonly XSD_STRING;
-    constructor(queryEngine: SubgraphQueryEngine, credentialsExtractor: CredentialsExtractor, permissionReader: PermissionReader, authorizer: Authorizer, options?: SubgraphSparqlHttpHandlerOptions, updateAuthority?: MixDataAccessor);
+    constructor(queryEngine: SubgraphQueryEngine, credentialsExtractor: CredentialsExtractor, permissionReader: PermissionReader, authorizer: Authorizer, options?: SubgraphSparqlHttpHandlerOptions, updateAuthority?: MixDataAccessor, emitter?: ActivityEmitter);
     canHandle({ request }: HttpHandlerInput): Promise<void>;
     handle({ request, response }: HttpHandlerInput): Promise<void>;
     /**
@@ -60,6 +61,55 @@ export declare class SubgraphSparqlHttpHandler extends HttpHandler {
     private executeAsk;
     private executeConstruct;
     private executeUpdate;
+    /**
+     * Turns the write targets of an update access plan into the activities that should be emitted.
+     *
+     * Only documents actually written by the update (the plan's `writeTargets`) are considered:
+     * one activity per document, never per quad and never for an untouched resource.
+     */
+    private resolvePendingActivities;
+    /**
+     * Maps the SPARQL update operation applied to one document to the ActivityStream term the
+     * CSS notification generators understand (`MonitoringStore` only forwards `as:Add|Create|Delete|Remove|Update`).
+     *
+     * Mapping (the closest faithful term for each operation):
+     * - `CREATE [SILENT] GRAPH`                      -> `as:Create` when the document did not exist yet;
+     *                                                   a `CREATE` on an existing graph is a silent no-op -> nothing.
+     * - `INSERT DATA` / `INSERT … WHERE` / `LOAD` /
+     *   `ADD` / `COPY` target                        -> `as:Create` when the document did not exist yet, else `as:Update`
+     *                                                   (same `exists ? Update : Create` rule CSS uses for PUT).
+     * - `DELETE DATA` / `DELETE WHERE` /
+     *   `INSERT … DELETE … WHERE`                    -> `as:Update` (partial removal; the document itself survives).
+     * - `CLEAR GRAPH` / `DROP GRAPH` / `MOVE` source -> `as:Update`: every triple is gone, but
+     `MixDataAccessor.executeSparqlUpdate` rewrites the graph into an *empty* document instead of
+     removing the resource, so a re-read returns 200-empty rather than 404. That observable result
+     equals a `DELETE DATA` which removes every triple, which maps to `Update`. `as:Delete` is
+     therefore deliberately unused: it becomes correct only once an accessor actually removes the
+     document (a re-read would then be 404).
+     * - delete-only update on a missing document     -> nothing (SPARQL no-op).
+     * - `as:Add` / `as:Remove` are deliberately not used: those describe container membership changes
+     *   (`DataAccessorBasedStore.addContainerActivity`), and the sidecar writes document graphs only.
+     */
+    private resolveActivity;
+    /**
+     * Checks whether the document already exists before the update is applied.
+     *
+     * Uses the same accessor that performs the write, so the answer describes the storage the
+     * activity is about. Returns `undefined` when the answer cannot be determined; callers then
+     * fall back to the conservative `Update`/`Delete` terms instead of `Create`.
+     */
+    private documentExistedBefore;
+    /**
+     * Emits the resolved activities on the injected {@link ActivityEmitter}.
+     *
+     * Mirrors `MonitoringStore.emitChanged`
+     * (node_modules/@solid/community-server/dist/storage/MonitoringStore.js:36-45): for every changed resource
+     * one `changed` event plus the ActivityStream-typed event, with the same metadata shape
+     * `DataAccessorBasedStore.addActivityMetadata` produces (an `urn:npm:solid:community-server:activity:` quad).
+     * `ListeningActivityHandler` (dist/server/notifications/ListeningActivityHandler.js:25) subscribes to `changed`
+     * and derives the notification state by re-reading the store, so no ETag has to be carried here.
+     */
+    private emitActivities;
     private sendPayload;
     private streamWithLimit;
     private resolveUsageContext;
@@ -79,6 +129,13 @@ export declare class SubgraphSparqlHttpHandler extends HttpHandler {
     private inspectPatterns;
     private assertGraphInScope;
     private assertGraphTermInScope;
+    /**
+     * Registers a graph as written by the update and records which kind of change applies to it.
+     *
+     * Several operations can target the same graph in one request; the flags are accumulated so the graph
+     * still yields at most one activity. This is also the only place write targets are created, which keeps
+     * notification coverage tied to the same plan that drives authorization.
+     */
     private addWriteTarget;
     private readLoadDocument;
     private rewriteLoadUpdate;

package/dist/http/SubgraphSparqlHttpHandler.js

@@ -19,7 +19,7 @@ const ALLOWED_METHODS = ['GET', 'POST', 'OPTIONS'];
 const MODEL_COLLECTION_SUFFIX = '/settings/providers/-/sparql';
 const SETTINGS_COLLECTION_SUFFIX = '/settings/-/sparql';
 class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
-    constructor(queryEngine, credentialsExtractor, permissionReader, authorizer, options = {}, updateAuthority) {
+    constructor(queryEngine, credentialsExtractor, permissionReader, authorizer, options = {}, updateAuthority, emitter) {
         super();
         this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
         this.generator = new sparqljs_1.Generator();
@@ -30,6 +30,7 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
         this.sidecarPath = options.sidecarPath ?? '/-/sparql';
         this.defaultBandwidthLimit = this.normalizeLimit(options.defaultAccountBandwidthLimitBps);
         this.updateAuthority = updateAuthority;
+        this.emitter = emitter;
         // Identity DB is used for pod lookup (to resolve accountId/podId from URL)
         if (options.identityDbUrl) {
             const db = (0, db_1.getIdentityDatabase)(options.identityDbUrl);
@@ -335,6 +336,13 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
                     : this.rewriteDefaultGraphUpdates(parsed, queryRequest.baseUrl);
         this.logger.verbose(`[SubgraphSPARQL] Rewritten Query: ${rewritten}`);
         const skippedSilentAuthorityLoad = Boolean(this.updateAuthority && loadDocumentPlan?.silent && !nativeOptions?.loadDocument);
+        // A LOAD that resolved to an empty document rewrites to `INSERT DATA { GRAPH <g> { } }`,
+        // which cannot create or change anything, so it must not notify either.
+        const emptyAuthorityLoad = Boolean(this.updateAuthority && loadDocumentPlan && nativeOptions?.loadDocument?.body.trim().length === 0);
+        const emitActivities = Boolean(this.emitter) && !emptyAuthorityLoad;
+        // Existence has to be captured before the write because the activity term depends on it
+        // (`Create` for a document the update brings into existence, `Update` otherwise).
+        const pendingActivities = emitActivities ? await this.resolvePendingActivities(accessPlan) : [];
         if (!skippedSilentAuthorityLoad) {
             if (this.updateAuthority) {
                 await this.updateAuthority.executeSparqlUpdate(rewritten, queryRequest.baseUrl, readAccessScope);
@@ -342,12 +350,115 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
             else {
                 await this.engine.queryVoid(rewritten, queryRequest.baseUrl, readAccessScope, nativeOptions);
             }
+            // Only a successful write notifies; a throwing write skips this line entirely.
+            this.emitActivities(pendingActivities);
         }
         await this.refreshUsage(queryRequest.baseUrl);
         response.statusCode = 204;
         response.setHeader('Cache-Control', 'no-store');
         response.end();
     }
+    /**
+     * Turns the write targets of an update access plan into the activities that should be emitted.
+     *
+     * Only documents actually written by the update (the plan's `writeTargets`) are considered:
+     * one activity per document, never per quad and never for an untouched resource.
+     */
+    async resolvePendingActivities(plan) {
+        const pending = [];
+        for (const [graph, effect] of plan.targetEffects) {
+            const documentUrl = this.resourceUrlForGraphValue(graph);
+            const existedBefore = await this.documentExistedBefore(documentUrl);
+            const activity = this.resolveActivity(effect, existedBefore);
+            if (activity) {
+                pending.push({ identifier: { path: documentUrl }, activity });
+            }
+        }
+        return pending;
+    }
+    /**
+     * Maps the SPARQL update operation applied to one document to the ActivityStream term the
+     * CSS notification generators understand (`MonitoringStore` only forwards `as:Add|Create|Delete|Remove|Update`).
+     *
+     * Mapping (the closest faithful term for each operation):
+     * - `CREATE [SILENT] GRAPH`                      -> `as:Create` when the document did not exist yet;
+     *                                                   a `CREATE` on an existing graph is a silent no-op -> nothing.
+     * - `INSERT DATA` / `INSERT … WHERE` / `LOAD` /
+     *   `ADD` / `COPY` target                        -> `as:Create` when the document did not exist yet, else `as:Update`
+     *                                                   (same `exists ? Update : Create` rule CSS uses for PUT).
+     * - `DELETE DATA` / `DELETE WHERE` /
+     *   `INSERT … DELETE … WHERE`                    -> `as:Update` (partial removal; the document itself survives).
+     * - `CLEAR GRAPH` / `DROP GRAPH` / `MOVE` source -> `as:Update`: every triple is gone, but
+     `MixDataAccessor.executeSparqlUpdate` rewrites the graph into an *empty* document instead of
+     removing the resource, so a re-read returns 200-empty rather than 404. That observable result
+     equals a `DELETE DATA` which removes every triple, which maps to `Update`. `as:Delete` is
+     therefore deliberately unused: it becomes correct only once an accessor actually removes the
+     document (a re-read would then be 404).
+     * - delete-only update on a missing document     -> nothing (SPARQL no-op).
+     * - `as:Add` / `as:Remove` are deliberately not used: those describe container membership changes
+     *   (`DataAccessorBasedStore.addContainerActivity`), and the sidecar writes document graphs only.
+     */
+    resolveActivity(effect, existedBefore) {
+        if (effect.createdGraph) {
+            return existedBefore === true ? undefined : community_server_2.AS.terms.Create;
+        }
+        if (!effect.addedData && existedBefore === false) {
+            // DELETE/CLEAR/DROP against a document that does not exist changes nothing.
+            return undefined;
+        }
+        if (!effect.addedData && effect.removedAllData) {
+            // CLEAR/DROP/MOVE-source: the document survives as an empty document, so this is an update.
+            return community_server_2.AS.terms.Update;
+        }
+        if (existedBefore === false) {
+            return community_server_2.AS.terms.Create;
+        }
+        return community_server_2.AS.terms.Update;
+    }
+    /**
+     * Checks whether the document already exists before the update is applied.
+     *
+     * Uses the same accessor that performs the write, so the answer describes the storage the
+     * activity is about. Returns `undefined` when the answer cannot be determined; callers then
+     * fall back to the conservative `Update`/`Delete` terms instead of `Create`.
+     */
+    async documentExistedBefore(documentUrl) {
+        if (!this.updateAuthority) {
+            return undefined;
+        }
+        try {
+            await this.updateAuthority.getMetadata({ path: documentUrl });
+            return true;
+        }
+        catch (error) {
+            if (community_server_2.NotFoundHttpError.isInstance(error)) {
+                return false;
+            }
+            this.logger.debug(`Could not determine pre-update existence of ${documentUrl}: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }
+    }
+    /**
+     * Emits the resolved activities on the injected {@link ActivityEmitter}.
+     *
+     * Mirrors `MonitoringStore.emitChanged`
+     * (node_modules/@solid/community-server/dist/storage/MonitoringStore.js:36-45): for every changed resource
+     * one `changed` event plus the ActivityStream-typed event, with the same metadata shape
+     * `DataAccessorBasedStore.addActivityMetadata` produces (an `urn:npm:solid:community-server:activity:` quad).
+     * `ListeningActivityHandler` (dist/server/notifications/ListeningActivityHandler.js:25) subscribes to `changed`
+     * and derives the notification state by re-reading the store, so no ETag has to be carried here.
+     */
+    emitActivities(activities) {
+        if (!this.emitter || activities.length === 0) {
+            return;
+        }
+        for (const { identifier, activity } of activities) {
+            const metadata = new community_server_2.RepresentationMetadata(identifier, { [community_server_2.SOLID_AS.activity]: activity });
+            this.emitter.emit('changed', identifier, activity, metadata);
+            this.emitter.emit(activity.value, identifier, metadata);
+            this.logger.debug(`[SubgraphSPARQL] Emitted ${activity.value} activity for ${identifier.path}`);
+        }
+    }
     async sendPayload(response, payload, contentType, context, statusCode = 200) {
         const buffer = typeof payload === 'string' ? Buffer.from(payload, 'utf8') : payload;
         const limit = context ? await this.resolveBandwidthLimit(context) : undefined;
@@ -514,6 +625,7 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
             needsReadScope: false,
             readTargets: new Set(),
             writeTargets: new Map(),
+            targetEffects: new Map(),
             loadDocuments: [],
             clearGraphs: [],
             graphCopies: [],
@@ -533,7 +645,7 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
                     ? this.assertGraphTermInScope(operation.destination, basePath)
                     : basePath;
                 plan.readTargets.add(sourceUri);
-                this.addWriteTarget(plan, targetGraph ?? basePath, [policy_engine_1.PERMISSIONS.Append]);
+                this.addWriteTarget(plan, targetGraph ?? basePath, [policy_engine_1.PERMISSIONS.Append], { addedData: true });
                 plan.loadDocuments.push({
                     sourceUri,
                     targetGraph: targetGraph ?? basePath,
@@ -548,7 +660,7 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
                 plan.hasDelete = true;
                 plan.needsReadScope = true;
                 const graph = this.assertGraphInScope(operation.graph, basePath) ?? basePath;
-                this.addWriteTarget(plan, graph, [policy_engine_1.PERMISSIONS.Delete]);
+                this.addWriteTarget(plan, graph, [policy_engine_1.PERMISSIONS.Delete], { removedAllData: true });
                 plan.clearGraphs.push(graph);
                 continue;
             }
@@ -561,17 +673,23 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
                 plan.hasInsert = true;
                 plan.needsReadScope = true;
                 plan.readTargets.add(sourceGraph);
+                // A self copy/add/move is reduced by `rewriteGraphCopyUpdate` to `CREATE SILENT GRAPH <targetGraph>`,
+                // so such a target is only (possibly) created and never cleared or re-filled.
+                const selfCopy = sourceGraph === targetGraph;
+                const targetEffect = selfCopy
+                    ? { createdGraph: true }
+                    : { removedAllData: true, addedData: true };
                 if (operation.type === 'add') {
-                    this.addWriteTarget(plan, targetGraph, [policy_engine_1.PERMISSIONS.Append]);
+                    this.addWriteTarget(plan, targetGraph, [policy_engine_1.PERMISSIONS.Append], selfCopy ? targetEffect : { addedData: true });
                 }
                 else if (operation.type === 'copy') {
                     plan.hasDelete = true;
-                    this.addWriteTarget(plan, targetGraph, [policy_engine_1.PERMISSIONS.Delete, policy_engine_1.PERMISSIONS.Append]);
+                    this.addWriteTarget(plan, targetGraph, [policy_engine_1.PERMISSIONS.Delete, policy_engine_1.PERMISSIONS.Append], targetEffect);
                 }
                 else {
                     plan.hasDelete = true;
-                    this.addWriteTarget(plan, targetGraph, [policy_engine_1.PERMISSIONS.Delete, policy_engine_1.PERMISSIONS.Append]);
-                    this.addWriteTarget(plan, sourceGraph, [policy_engine_1.PERMISSIONS.Delete]);
+                    this.addWriteTarget(plan, targetGraph, [policy_engine_1.PERMISSIONS.Delete, policy_engine_1.PERMISSIONS.Append], targetEffect);
+                    this.addWriteTarget(plan, sourceGraph, [policy_engine_1.PERMISSIONS.Delete], selfCopy ? {} : { removedAllData: true });
                 }
                 plan.graphCopies.push({ operation: operation.type, sourceGraph, targetGraph });
                 continue;
@@ -579,7 +697,7 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
             if (this.isCreateGraphOperation(operation)) {
                 plan.hasInsert = true;
                 const graph = this.assertGraphInScope(operation.graph, basePath) ?? basePath;
-                this.addWriteTarget(plan, graph, [policy_engine_1.PERMISSIONS.Append]);
+                this.addWriteTarget(plan, graph, [policy_engine_1.PERMISSIONS.Append], { createdGraph: true });
                 continue;
             }
             if (!this.isInsertDeleteOperation(operation)) {
@@ -600,7 +718,7 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
                 this.assertGraphInScope(operation.graph, basePath);
             }
             if (operation.updateType === 'insert' || operation.updateType === 'insertdelete') {
-                this.inspectQuads(operation.insert ?? [], basePath, defaultGraph, plan, [policy_engine_1.PERMISSIONS.Append]);
+                this.inspectQuads(operation.insert ?? [], basePath, defaultGraph, plan, [policy_engine_1.PERMISSIONS.Append], { addedData: true });
             }
             if (operation.updateType === 'delete' || operation.updateType === 'insertdelete' || operation.updateType === 'deletewhere') {
                 this.inspectQuads(operation.delete ?? [], basePath, defaultGraph, plan, [policy_engine_1.PERMISSIONS.Delete]);
@@ -622,16 +740,16 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
         }
         return plan;
     }
-    inspectQuads(quads, basePath, defaultGraph, plan, modes) {
+    inspectQuads(quads, basePath, defaultGraph, plan, modes, effect = {}) {
         for (const quad of quads) {
             if (quad.type === 'graph') {
                 const graph = this.assertGraphTermInScope(quad.name, basePath);
                 if (graph) {
-                    this.addWriteTarget(plan, graph, modes);
+                    this.addWriteTarget(plan, graph, modes, effect);
                 }
             }
             else {
-                this.addWriteTarget(plan, defaultGraph, modes);
+                this.addWriteTarget(plan, defaultGraph, modes, effect);
             }
         }
     }
@@ -681,12 +799,26 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
         }
         throw new community_server_2.BadRequestHttpError('Unsupported graph target in SPARQL update.');
     }
-    addWriteTarget(plan, graph, modes) {
+    /**
+     * Registers a graph as written by the update and records which kind of change applies to it.
+     *
+     * Several operations can target the same graph in one request; the flags are accumulated so the graph
+     * still yields at most one activity. This is also the only place write targets are created, which keeps
+     * notification coverage tied to the same plan that drives authorization.
+     */
+    addWriteTarget(plan, graph, modes, effect = {}) {
         const existing = plan.writeTargets.get(graph) ?? new Set();
         for (const mode of modes) {
             existing.add(mode);
         }
         plan.writeTargets.set(graph, existing);
+        const merged = plan.targetEffects.get(graph) ?? { addedData: false, removedAllData: false, createdGraph: false };
+        for (const key of Object.keys(effect)) {
+            if (effect[key]) {
+                merged[key] = true;
+            }
+        }
+        plan.targetEffects.set(graph, merged);
     }
     async readLoadDocument(plan, basePath, accessScope) {
         const quads = await this.engine.constructGraph(plan.sourceUri, basePath, accessScope);

package/dist/http/SubgraphSparqlHttpHandler.jsonld

@@ -25,6 +25,20 @@
             ]
           }
         },
+        {
+          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler_emitter",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              {
+                "@type": "ParameterRangeWildcard"
+              },
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          }
+        },
         {
           "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler_queryEngine",
           "range": "undefineds:dist/storage/sparql/SubgraphQueryEngine.jsonld#SubgraphQueryEngine"
@@ -162,6 +176,10 @@
           "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_updateAuthority",
           "memberFieldName": "updateAuthority"
         },
+        {
+          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_emitter",
+          "memberFieldName": "emitter"
+        },
         {
           "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_generator",
           "memberFieldName": "generator"
@@ -214,6 +232,22 @@
           "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_executeUpdate",
           "memberFieldName": "executeUpdate"
         },
+        {
+          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_resolvePendingActivities",
+          "memberFieldName": "resolvePendingActivities"
+        },
+        {
+          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_resolveActivity",
+          "memberFieldName": "resolveActivity"
+        },
+        {
+          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_documentExistedBefore",
+          "memberFieldName": "documentExistedBefore"
+        },
+        {
+          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_emitActivities",
+          "memberFieldName": "emitActivities"
+        },
         {
           "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_sendPayload",
           "memberFieldName": "sendPayload"
@@ -459,6 +493,9 @@
         },
         {
           "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler_updateAuthority"
+        },
+        {
+          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler_emitter"
         }
       ]
     }

package/dist/identity/drizzle/AccountRoleRepository.d.ts

@@ -4,16 +4,44 @@ export interface AccountRoleContext {
     webId?: string;
     roles: string[];
 }
+export interface AccountRoleRepositoryOptions {
+    /**
+     * CSS 文件存储时代的账户目录（`.internal/accounts/data`）。
+     * 仅在迁移期兜底读取；默认按进程 CWD 惰性解析，桌面/集群部署应显式注入。
+     */
+    legacyAccountDataDir?: string;
+}
 export declare class AccountRoleRepository {
     private readonly db;
     private readonly logger;
-    constructor(db: IdentityDatabase);
+    private readonly legacyAccountDataDir?;
+    constructor(db: IdentityDatabase, options?: AccountRoleRepositoryOptions);
     findByAccountId(accountId: string): Promise<AccountRoleContext | undefined>;
     findByWebId(webId: string): Promise<AccountRoleContext | undefined>;
     findByWebIdLoose(webId: string): Promise<AccountRoleContext | undefined>;
     listAccounts(): Promise<AccountRoleContext[]>;
     addRoles(accountId: string, roles: string[]): Promise<void>;
-    private getAccountById;
+    /**
+     * 按主键直查 identity_store 中的 account 行；表不存在时返回 undefined（由调用方走兜底）。
+     */
+    private getIdentityStoreAccount;
+    /**
+     * 按 CSS 行契约（webIdLink.accountId、pod.accountId、owner.podId）下推查询账户的 WebID。
+     */
+    private findWebIdsForAccount;
+    /**
+     * WebID → accountId 的下推解析：webIdLink 优先，其次 account 行内嵌 webId 字段，
+     * 最后 owner→pod 链路。全部 miss 返回 undefined（调用方再走全量兜底）。
+     */
+    private findAccountIdByWebId;
+    /**
+     * owner→pod 链路里把 owner 行的 podId 与 pod 行的 id 对齐。
+     */
+    private ownerPodJoin;
+    /**
+     * legacy 来源：internal_kv 与文件账户（迁移期兜底），不含 identity_store。
+     */
+    private loadLegacyAccounts;
     private loadAllAccounts;
     private loadIdentityStoreAccounts;
     private loadInternalKvAccounts;