@undefineds.co/xpod 0.4.11 → 0.4.12

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/EdgeNodeRepository.d.ts

@@ -153,18 +153,6 @@ export declare class EdgeNodeRepository {
      * Remove a center node from the cluster.
      */
     removeCenterNode(nodeId: string): Promise<boolean>;
-    /**
-     * List nodes owned by a specific account
-     */
-    listNodesByAccount(accountId: string): Promise<Array<{
-        nodeId: string;
-        displayName?: string;
-        capabilities: Record<string, unknown> | null;
-        stringCapabilities: string[] | null;
-        accessMode: string | null;
-        lastSeen: Date | null;
-        connectivityStatus: string | null;
-    }>>;
     /**
      * Delete a node
      */

package/dist/identity/drizzle/EdgeNodeRepository.js

@@ -39,7 +39,7 @@ class EdgeNodeRepository {
                 createdAt: createdAt?.toISOString(),
                 updatedAt: updatedAt?.toISOString(),
                 lastSeen: lastSeen?.toISOString(),
-                metadata: typeof row.metadata === 'string' ? JSON.parse(row.metadata) : (row.metadata ?? null),
+                metadata: parseJsonRecord(row.metadata),
             };
         });
     }
@@ -77,7 +77,7 @@ class EdgeNodeRepository {
             displayName: row.display_name == null ? undefined : String(row.display_name),
             tokenHash: String(row.token_hash ?? ''),
             nodeType: (['center', 'edge', 'sp'].includes(row.node_type) ? row.node_type : 'edge'),
-            metadata: typeof row.metadata === 'string' ? JSON.parse(row.metadata) : (row.metadata ?? null),
+            metadata: parseJsonRecord(row.metadata),
         };
     }
     async updateNodeHeartbeat(nodeId, metadata, timestamp) {
@@ -166,7 +166,7 @@ class EdgeNodeRepository {
         const row = result.rows[0];
         return {
             nodeId: String(row.id),
-            metadata: typeof row.metadata === 'string' ? JSON.parse(row.metadata) : (row.metadata ?? null),
+            metadata: parseJsonRecord(row.metadata),
             lastSeen: (0, db_1.fromDbTimestamp)(row.last_seen),
         };
     }
@@ -327,7 +327,7 @@ class EdgeNodeRepository {
         await this.ready;
         const token = (0, node_crypto_1.randomBytes)(32).toString('base64url');
         const tokenHash = (0, node_crypto_1.createHash)('sha256').update(token).digest('hex');
-        const now = Math.floor(Date.now() / 1000); // Unix timestamp for SQLite compatibility
+        const now = (0, db_1.toDbTimestamp)(this.db, new Date());
         // Use upsert pattern: INSERT ... ON CONFLICT UPDATE
         await (0, db_1.executeStatement)(this.db, (0, drizzle_orm_1.sql) `
       INSERT INTO cluster_node (
@@ -352,7 +352,7 @@ class EdgeNodeRepository {
      */
     async updateCenterNodeHeartbeat(nodeId, internalIp, internalPort, timestamp) {
         await this.ready;
-        const ts = Math.floor(timestamp.getTime() / 1000); // Unix timestamp for SQLite compatibility
+        const ts = (0, db_1.toDbTimestamp)(this.db, timestamp);
         await (0, db_1.executeStatement)(this.db, (0, drizzle_orm_1.sql) `
       UPDATE cluster_node
       SET internal_ip = ${internalIp},
@@ -457,14 +457,6 @@ class EdgeNodeRepository {
         return true;
     }
     // ============ Account-based Node Methods ============
-    /**
-     * List nodes owned by a specific account
-     */
-    async listNodesByAccount(accountId) {
-        await this.ready;
-        void accountId;
-        return [];
-    }
     /**
      * Delete a node
      */

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { SolidRdfDataAccessor } from './storage/accessors/SolidRdfDataAccessor';
 import { MixDataAccessor } from './storage/accessors/MixDataAccessor';
 export type { LocalRdfAuthorityJournal, LocalRdfIndexAccessor, } from './storage/accessors/MixDataAccessor';
 import { ConfigurableLoggerFactory } from './logging/ConfigurableLoggerFactory';
+import { LOG_FILE_PATTERN, resolveCurrentLogFile, resolveLogFilePattern } from './logging/log-file';
 import { SubgraphQueryEngine } from './storage/sparql/SubgraphQueryEngine';
 export type { SparqlEngine } from './storage/sparql/SubgraphQueryEngine';
 export type { RdfEngineLike, RdfEngineStorageStats, RdfDerivedIndexRefreshResult, RdfIndexStats, RdfIndexSpaceObject, RdfIndexMetrics, RdfIndexPutOptions, RdfPatternQuery, RdfQuadIndexOptions, RdfQuadIndexScanResult, RdfTextIndexLike, RdfTextIndexOptions, RdfTextIndexSyncLike, RdfVectorIndexLike, RdfVectorIndexOptions, RdfVectorIndexSyncLike, RdfShadowBackfillOptions, RdfShadowBackfillResult, RdfShadowDiff, RdfShadowScanResult, RdfSourceInput, RdfSourceScope, } from './storage/rdf/types';
@@ -124,6 +125,6 @@ export type { OwnedWebIdEntry, PodOwnershipResolver, PodOwnershipTarget, CssPodO
 export type { TunnelProvider, TunnelConfig, TunnelSetupOptions, TunnelStatus, } from './tunnel/TunnelProvider';
 export type { SubdomainRegistration, ConnectivityResult, SubdomainServiceOptions, } from './subdomain/SubdomainService';
 export { AppStaticAssetHandler } from './http/AppStaticAssetHandler';
-export { RepresentationPartialConvertingStore, MinioDataAccessor, SolidRdfDataAccessor, MixDataAccessor, ConfigurableLoggerFactory, SparqlUpdateResourceStore, SubgraphQueryEngine, SubgraphSparqlHttpHandler, InternalPodDataHttpHandler, QuotaAdminHttpHandler, ClusterIngressRouter, ClusterWebSocketConfigurator, EdgeNodeDirectDebugHttpHandler, EdgeNodeProxyHttpHandler, RouterHttpHandler, RouterHttpRoute, TracingHandler, EdgeNodeCertificateHttpHandler, TerminalHttpHandler, DeviceNotificationHub, DeviceNotificationResourceListener, DeviceNotificationWebSocketServer, DeviceNotificationTicketHandler, registerDeviceNotificationRuntime, ReservedSuffixIdentifierGenerator, DrizzleIndexedStorage, LoginMethodGuardStorage, ValidatingIdentityProviderHttpHandler, PostgresKeyValueStorage, RedisKeyValueStorage, SqliteKeyValueStorage, BaseKeyValueStorage, DrizzleQuotaService, NoopQuotaService, HttpEntitlementProvider, NoopEntitlementProvider, PerAccountQuotaStrategy, TencentDnsProvider, EdgeNodeDnsCoordinator, Dns01CertificateProvisioner, SimpleEdgeNodeTunnelManager, NoopEdgeNodeTunnelManager, FrpTunnelManager, EdgeNodeHealthProbeService, EdgeNodeAgent, EdgeNodeAgentInitializer, EdgeNodeCertificateService, AcmeCertificateManager, EdgeNodeModeDetector, ClusterIdentifierStrategy, UsageTrackingStore, CenterNodeRegistrationService, PodRoutingHttpHandler, ReactAppViewHandler, QuintStore, SqliteQuintStore, PgQuintStore, RdfTermDictionary, RdfQuadIndex, Rdf3xIndex, RdfTextIndex, RdfVectorIndex, PostgresRdfTextIndex, PostgresRdfVectorIndex, SolidRdfEngine, LocalQleverNativeSparqlClient, QleverSparqlEngine, RdfQuerySparqlEngine, PostgresRdfEngine, VectorStore, SqliteVectorStore, PostgresVectorStore, VectorHttpHandler, ProviderRegistry, ProviderRegistryImpl, EmbeddingService, EmbeddingServiceImpl, CredentialReader, CredentialReaderImpl, CloudflareTunnelProvider, LocalTunnelProvider, NgrokTunnelProvider, SubdomainService, MultiDomainIdentifierStrategy, SubdomainPodIdentifierStrategy, DisabledOidcHandler, DisabledIdentityProviderHandler, AutoDetectOidcHandler, AutoDetectIdentityProviderHandler, LoopbackClientIdAdapterFactory, RememberedClientGrantStore, RememberedConsentHandler, RememberedClientPromptFactory, SessionBoundIdentityProviderFactory, ScopedPickWebIdHandler, ConfiguredLoopbackDPoPWebIdExtractor, AccountStorageBindingsHandler, CssPodOwnershipResolver, UrlAwareRedisLocker, ProvisionPodCreator, ProvisionPodStore, ProvisionCodeCodec, LocalPodProvisioningService, SqliteSolidFsSyncJournal, RootedSolidFsSyncJournal, LocalRdfAuthorityRecoveryInitializer, ObservableResourceStore, RdfSearchReconciliationIntentSink, };
+export { RepresentationPartialConvertingStore, MinioDataAccessor, SolidRdfDataAccessor, MixDataAccessor, ConfigurableLoggerFactory, resolveLogFilePattern, resolveCurrentLogFile, LOG_FILE_PATTERN, SparqlUpdateResourceStore, SubgraphQueryEngine, SubgraphSparqlHttpHandler, InternalPodDataHttpHandler, QuotaAdminHttpHandler, ClusterIngressRouter, ClusterWebSocketConfigurator, EdgeNodeDirectDebugHttpHandler, EdgeNodeProxyHttpHandler, RouterHttpHandler, RouterHttpRoute, TracingHandler, EdgeNodeCertificateHttpHandler, TerminalHttpHandler, DeviceNotificationHub, DeviceNotificationResourceListener, DeviceNotificationWebSocketServer, DeviceNotificationTicketHandler, registerDeviceNotificationRuntime, ReservedSuffixIdentifierGenerator, DrizzleIndexedStorage, LoginMethodGuardStorage, ValidatingIdentityProviderHttpHandler, PostgresKeyValueStorage, RedisKeyValueStorage, SqliteKeyValueStorage, BaseKeyValueStorage, DrizzleQuotaService, NoopQuotaService, HttpEntitlementProvider, NoopEntitlementProvider, PerAccountQuotaStrategy, TencentDnsProvider, EdgeNodeDnsCoordinator, Dns01CertificateProvisioner, SimpleEdgeNodeTunnelManager, NoopEdgeNodeTunnelManager, FrpTunnelManager, EdgeNodeHealthProbeService, EdgeNodeAgent, EdgeNodeAgentInitializer, EdgeNodeCertificateService, AcmeCertificateManager, EdgeNodeModeDetector, ClusterIdentifierStrategy, UsageTrackingStore, CenterNodeRegistrationService, PodRoutingHttpHandler, ReactAppViewHandler, QuintStore, SqliteQuintStore, PgQuintStore, RdfTermDictionary, RdfQuadIndex, Rdf3xIndex, RdfTextIndex, RdfVectorIndex, PostgresRdfTextIndex, PostgresRdfVectorIndex, SolidRdfEngine, LocalQleverNativeSparqlClient, QleverSparqlEngine, RdfQuerySparqlEngine, PostgresRdfEngine, VectorStore, SqliteVectorStore, PostgresVectorStore, VectorHttpHandler, ProviderRegistry, ProviderRegistryImpl, EmbeddingService, EmbeddingServiceImpl, CredentialReader, CredentialReaderImpl, CloudflareTunnelProvider, LocalTunnelProvider, NgrokTunnelProvider, SubdomainService, MultiDomainIdentifierStrategy, SubdomainPodIdentifierStrategy, DisabledOidcHandler, DisabledIdentityProviderHandler, AutoDetectOidcHandler, AutoDetectIdentityProviderHandler, LoopbackClientIdAdapterFactory, RememberedClientGrantStore, RememberedConsentHandler, RememberedClientPromptFactory, SessionBoundIdentityProviderFactory, ScopedPickWebIdHandler, ConfiguredLoopbackDPoPWebIdExtractor, AccountStorageBindingsHandler, CssPodOwnershipResolver, UrlAwareRedisLocker, ProvisionPodCreator, ProvisionPodStore, ProvisionCodeCodec, LocalPodProvisioningService, SqliteSolidFsSyncJournal, RootedSolidFsSyncJournal, LocalRdfAuthorityRecoveryInitializer, ObservableResourceStore, RdfSearchReconciliationIntentSink, };
 export type { ResourceChangeEvent, ResourceChangeListener, ResourceChangeRecorder, } from './storage/ObservableResourceStore';
 export { RdfHandlebarsTemplateEngine } from './util/templates/RdfHandlebarsTemplateEngine';

package/dist/index.js

@@ -14,9 +14,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EdgeNodeModeDetector = exports.AcmeCertificateManager = exports.EdgeNodeCertificateService = exports.EdgeNodeAgentInitializer = exports.EdgeNodeAgent = exports.EdgeNodeHealthProbeService = exports.FrpTunnelManager = exports.NoopEdgeNodeTunnelManager = exports.SimpleEdgeNodeTunnelManager = exports.Dns01CertificateProvisioner = exports.EdgeNodeDnsCoordinator = exports.TencentDnsProvider = exports.PerAccountQuotaStrategy = exports.NoopEntitlementProvider = exports.HttpEntitlementProvider = exports.NoopQuotaService = exports.DrizzleQuotaService = exports.BaseKeyValueStorage = exports.SqliteKeyValueStorage = exports.RedisKeyValueStorage = exports.PostgresKeyValueStorage = exports.ValidatingIdentityProviderHttpHandler = exports.LoginMethodGuardStorage = exports.DrizzleIndexedStorage = exports.ReservedSuffixIdentifierGenerator = exports.registerDeviceNotificationRuntime = exports.DeviceNotificationTicketHandler = exports.DeviceNotificationWebSocketServer = exports.DeviceNotificationResourceListener = exports.DeviceNotificationHub = exports.TerminalHttpHandler = exports.EdgeNodeCertificateHttpHandler = exports.TracingHandler = exports.RouterHttpRoute = exports.RouterHttpHandler = exports.EdgeNodeProxyHttpHandler = exports.EdgeNodeDirectDebugHttpHandler = exports.ClusterWebSocketConfigurator = exports.ClusterIngressRouter = exports.QuotaAdminHttpHandler = exports.InternalPodDataHttpHandler = exports.SubgraphSparqlHttpHandler = exports.SubgraphQueryEngine = exports.SparqlUpdateResourceStore = exports.ConfigurableLoggerFactory = exports.MixDataAccessor = exports.SolidRdfDataAccessor = exports.MinioDataAccessor = exports.RepresentationPartialConvertingStore = exports.AppStaticAssetHandler = void 0;
-exports.UrlAwareRedisLocker = exports.CssPodOwnershipResolver = exports.AccountStorageBindingsHandler = exports.ConfiguredLoopbackDPoPWebIdExtractor = exports.ScopedPickWebIdHandler = exports.SessionBoundIdentityProviderFactory = exports.RememberedClientPromptFactory = exports.RememberedConsentHandler = exports.RememberedClientGrantStore = exports.LoopbackClientIdAdapterFactory = exports.AutoDetectIdentityProviderHandler = exports.AutoDetectOidcHandler = exports.DisabledIdentityProviderHandler = exports.DisabledOidcHandler = exports.SubdomainPodIdentifierStrategy = exports.MultiDomainIdentifierStrategy = exports.SubdomainService = exports.NgrokTunnelProvider = exports.LocalTunnelProvider = exports.CloudflareTunnelProvider = exports.CredentialReaderImpl = exports.CredentialReader = exports.EmbeddingServiceImpl = exports.EmbeddingService = exports.ProviderRegistryImpl = exports.ProviderRegistry = exports.VectorHttpHandler = exports.PostgresVectorStore = exports.SqliteVectorStore = exports.VectorStore = exports.PostgresRdfEngine = exports.RdfQuerySparqlEngine = exports.QleverSparqlEngine = exports.LocalQleverNativeSparqlClient = exports.SolidRdfEngine = exports.PostgresRdfVectorIndex = exports.PostgresRdfTextIndex = exports.RdfVectorIndex = exports.RdfTextIndex = exports.Rdf3xIndex = exports.RdfQuadIndex = exports.RdfTermDictionary = exports.PgQuintStore = exports.SqliteQuintStore = exports.QuintStore = exports.ReactAppViewHandler = exports.PodRoutingHttpHandler = exports.CenterNodeRegistrationService = exports.UsageTrackingStore = exports.ClusterIdentifierStrategy = void 0;
-exports.RdfHandlebarsTemplateEngine = exports.RdfSearchReconciliationIntentSink = exports.ObservableResourceStore = exports.LocalRdfAuthorityRecoveryInitializer = exports.RootedSolidFsSyncJournal = exports.SqliteSolidFsSyncJournal = exports.LocalPodProvisioningService = exports.ProvisionCodeCodec = exports.ProvisionPodStore = exports.ProvisionPodCreator = void 0;
+exports.EdgeNodeAgentInitializer = exports.EdgeNodeAgent = exports.EdgeNodeHealthProbeService = exports.FrpTunnelManager = exports.NoopEdgeNodeTunnelManager = exports.SimpleEdgeNodeTunnelManager = exports.Dns01CertificateProvisioner = exports.EdgeNodeDnsCoordinator = exports.TencentDnsProvider = exports.PerAccountQuotaStrategy = exports.NoopEntitlementProvider = exports.HttpEntitlementProvider = exports.NoopQuotaService = exports.DrizzleQuotaService = exports.BaseKeyValueStorage = exports.SqliteKeyValueStorage = exports.RedisKeyValueStorage = exports.PostgresKeyValueStorage = exports.ValidatingIdentityProviderHttpHandler = exports.LoginMethodGuardStorage = exports.DrizzleIndexedStorage = exports.ReservedSuffixIdentifierGenerator = exports.registerDeviceNotificationRuntime = exports.DeviceNotificationTicketHandler = exports.DeviceNotificationWebSocketServer = exports.DeviceNotificationResourceListener = exports.DeviceNotificationHub = exports.TerminalHttpHandler = exports.EdgeNodeCertificateHttpHandler = exports.TracingHandler = exports.RouterHttpRoute = exports.RouterHttpHandler = exports.EdgeNodeProxyHttpHandler = exports.EdgeNodeDirectDebugHttpHandler = exports.ClusterWebSocketConfigurator = exports.ClusterIngressRouter = exports.QuotaAdminHttpHandler = exports.InternalPodDataHttpHandler = exports.SubgraphSparqlHttpHandler = exports.SubgraphQueryEngine = exports.SparqlUpdateResourceStore = exports.LOG_FILE_PATTERN = exports.resolveCurrentLogFile = exports.resolveLogFilePattern = exports.ConfigurableLoggerFactory = exports.MixDataAccessor = exports.SolidRdfDataAccessor = exports.MinioDataAccessor = exports.RepresentationPartialConvertingStore = exports.AppStaticAssetHandler = void 0;
+exports.ConfiguredLoopbackDPoPWebIdExtractor = exports.ScopedPickWebIdHandler = exports.SessionBoundIdentityProviderFactory = exports.RememberedClientPromptFactory = exports.RememberedConsentHandler = exports.RememberedClientGrantStore = exports.LoopbackClientIdAdapterFactory = exports.AutoDetectIdentityProviderHandler = exports.AutoDetectOidcHandler = exports.DisabledIdentityProviderHandler = exports.DisabledOidcHandler = exports.SubdomainPodIdentifierStrategy = exports.MultiDomainIdentifierStrategy = exports.SubdomainService = exports.NgrokTunnelProvider = exports.LocalTunnelProvider = exports.CloudflareTunnelProvider = exports.CredentialReaderImpl = exports.CredentialReader = exports.EmbeddingServiceImpl = exports.EmbeddingService = exports.ProviderRegistryImpl = exports.ProviderRegistry = exports.VectorHttpHandler = exports.PostgresVectorStore = exports.SqliteVectorStore = exports.VectorStore = exports.PostgresRdfEngine = exports.RdfQuerySparqlEngine = exports.QleverSparqlEngine = exports.LocalQleverNativeSparqlClient = exports.SolidRdfEngine = exports.PostgresRdfVectorIndex = exports.PostgresRdfTextIndex = exports.RdfVectorIndex = exports.RdfTextIndex = exports.Rdf3xIndex = exports.RdfQuadIndex = exports.RdfTermDictionary = exports.PgQuintStore = exports.SqliteQuintStore = exports.QuintStore = exports.ReactAppViewHandler = exports.PodRoutingHttpHandler = exports.CenterNodeRegistrationService = exports.UsageTrackingStore = exports.ClusterIdentifierStrategy = exports.EdgeNodeModeDetector = exports.AcmeCertificateManager = exports.EdgeNodeCertificateService = void 0;
+exports.RdfHandlebarsTemplateEngine = exports.RdfSearchReconciliationIntentSink = exports.ObservableResourceStore = exports.LocalRdfAuthorityRecoveryInitializer = exports.RootedSolidFsSyncJournal = exports.SqliteSolidFsSyncJournal = exports.LocalPodProvisioningService = exports.ProvisionCodeCodec = exports.ProvisionPodStore = exports.ProvisionPodCreator = exports.UrlAwareRedisLocker = exports.CssPodOwnershipResolver = exports.AccountStorageBindingsHandler = void 0;
 require("./runtime/configure-drizzle-solid");
 const RepresentationPartialConvertingStore_1 = require("./storage/RepresentationPartialConvertingStore");
 Object.defineProperty(exports, "RepresentationPartialConvertingStore", { enumerable: true, get: function () { return RepresentationPartialConvertingStore_1.RepresentationPartialConvertingStore; } });
@@ -28,6 +28,10 @@ const MixDataAccessor_1 = require("./storage/accessors/MixDataAccessor");
 Object.defineProperty(exports, "MixDataAccessor", { enumerable: true, get: function () { return MixDataAccessor_1.MixDataAccessor; } });
 const ConfigurableLoggerFactory_1 = require("./logging/ConfigurableLoggerFactory");
 Object.defineProperty(exports, "ConfigurableLoggerFactory", { enumerable: true, get: function () { return ConfigurableLoggerFactory_1.ConfigurableLoggerFactory; } });
+const log_file_1 = require("./logging/log-file");
+Object.defineProperty(exports, "LOG_FILE_PATTERN", { enumerable: true, get: function () { return log_file_1.LOG_FILE_PATTERN; } });
+Object.defineProperty(exports, "resolveCurrentLogFile", { enumerable: true, get: function () { return log_file_1.resolveCurrentLogFile; } });
+Object.defineProperty(exports, "resolveLogFilePattern", { enumerable: true, get: function () { return log_file_1.resolveLogFilePattern; } });
 const SubgraphQueryEngine_1 = require("./storage/sparql/SubgraphQueryEngine");
 Object.defineProperty(exports, "SubgraphQueryEngine", { enumerable: true, get: function () { return SubgraphQueryEngine_1.SubgraphQueryEngine; } });
 __exportStar(require("./document"), exports);

package/dist/logging/log-file.d.ts

@@ -0,0 +1,17 @@
+/** Directory, relative to the runtime working directory. */
+export declare const LOG_DIRECTORY = "logs";
+/** File name template; the rotating transport substitutes `%DATE%`. */
+export declare const LOG_FILE_NAME_PATTERN = "xpod-%DATE%.log";
+/** Both segments, for callers that join them onto a working directory themselves. */
+export declare const LOG_FILE_PATTERN = "logs/xpod-%DATE%.log";
+/** Absolute path template handed to the logging transport. */
+export declare function resolveLogFilePattern(cwd?: string): string;
+/**
+ * The log file currently being appended to, or `null` when the runtime has not
+ * written one yet.
+ *
+ * Daily rotation produces one file per date and size rotation keeps older
+ * segments as `.log.N` next to it, so the live file is identified by
+ * modification time rather than by name.
+ */
+export declare function resolveCurrentLogFile(cwd?: string): string | null;

package/dist/logging/log-file.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOG_FILE_PATTERN = exports.LOG_FILE_NAME_PATTERN = exports.LOG_DIRECTORY = void 0;
+exports.resolveLogFilePattern = resolveLogFilePattern;
+exports.resolveCurrentLogFile = resolveCurrentLogFile;
+/**
+ * Canonical location of the runtime log file.
+ *
+ * Every writer (main entry, runtime bootstrap, API service) and every reader
+ * (admin diagnostics) resolves the path through this module. When the reader
+ * guessed its own file names instead, the Logs page reported "no log file"
+ * while the runtime kept writing to one.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/** Directory, relative to the runtime working directory. */
+exports.LOG_DIRECTORY = 'logs';
+/** File name template; the rotating transport substitutes `%DATE%`. */
+exports.LOG_FILE_NAME_PATTERN = 'xpod-%DATE%.log';
+/** Both segments, for callers that join them onto a working directory themselves. */
+exports.LOG_FILE_PATTERN = `${exports.LOG_DIRECTORY}/${exports.LOG_FILE_NAME_PATTERN}`;
+/** Concrete files the template produces, including rotated siblings such as `xpod-2026-09-13.log.2`. */
+const CONCRETE_LOG_FILE_NAME = /^xpod-.*\.log(\.\d+)?$/;
+/** Absolute path template handed to the logging transport. */
+function resolveLogFilePattern(cwd = process.cwd()) {
+    return node_path_1.default.join(cwd, exports.LOG_DIRECTORY, exports.LOG_FILE_NAME_PATTERN);
+}
+/**
+ * The log file currently being appended to, or `null` when the runtime has not
+ * written one yet.
+ *
+ * Daily rotation produces one file per date and size rotation keeps older
+ * segments as `.log.N` next to it, so the live file is identified by
+ * modification time rather than by name.
+ */
+function resolveCurrentLogFile(cwd = process.cwd()) {
+    const directory = node_path_1.default.join(cwd, exports.LOG_DIRECTORY);
+    let names;
+    try {
+        names = node_fs_1.default.readdirSync(directory);
+    }
+    catch {
+        return null;
+    }
+    let newest = null;
+    for (const name of names) {
+        if (!CONCRETE_LOG_FILE_NAME.test(name))
+            continue;
+        const file = node_path_1.default.join(directory, name);
+        let mtimeMs;
+        try {
+            const stats = node_fs_1.default.statSync(file);
+            if (!stats.isFile())
+                continue;
+            mtimeMs = stats.mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (!newest || mtimeMs > newest.mtimeMs) {
+            newest = { file, mtimeMs };
+        }
+    }
+    return newest?.file ?? null;
+}
+//# sourceMappingURL=log-file.js.map

package/dist/main.js

@@ -17,6 +17,7 @@ const css_process_1 = require("./runtime/css-process");
 const oidc_issuer_1 = require("./runtime/oidc-issuer");
 const AuthMode_1 = require("./authorization/AuthMode");
 const ConfigurableLoggerFactory_1 = require("./logging/ConfigurableLoggerFactory");
+const log_file_1 = require("./logging/log-file");
 const supervisor_1 = require("./supervisor");
 const js_runtime_1 = require("./runtime/js-runtime");
 const database_url_1 = require("./runtime/database-url");
@@ -27,7 +28,7 @@ const EXIT_INTERNAL_ERROR = 50;
 let logger = (0, global_logger_factory_1.getLoggerFor)('Main');
 function initLogger() {
     const loggerFactory = new ConfigurableLoggerFactory_1.ConfigurableLoggerFactory(process.env.CSS_LOGGING_LEVEL || 'info', {
-        fileName: path_1.default.join(process.cwd(), 'logs/xpod-%DATE%.log'),
+        fileName: (0, log_file_1.resolveLogFilePattern)(),
         showLocation: true,
     });
     (0, global_logger_factory_1.setGlobalLoggerFactory)(loggerFactory);

package/dist/notifications/NotificationChannelSweeper.d.ts

@@ -0,0 +1,50 @@
+import type { Finalizable, KeyValueStorage, NotificationChannelStorage, WebSocketMap } from '@solid/community-server';
+import { Initializer } from '@solid/community-server';
+/** 默认清扫间隔（分钟）。同时是“新建但尚未连上 socket”的通道的宽限期。 */
+export declare const NOTIFICATION_CHANNEL_SWEEP_INTERVAL_MINUTES = 5;
+/**
+ * 回收没有活动 socket 的通知通道。
+ *
+ * 背景：CSS 的 `WebSocket2023Storer` 只在 socket 关闭时把它从内存 map 中移除，通道记录留在
+ * `SubscriptionStorage` 里直到 `endAt` 过期（默认 2 周）；客户端 DELETE 失败、页面崩溃、
+ * 进程被强杀等情况都会留下再也无人使用、也无人回收的通道。`ReclaimingWebSocket2023Storer`
+ * 覆盖了正常关闭的路径，本组件负责其余部分：
+ *
+ * 1. 启动时清扫一次：进程刚起来，内存 map 必然为空，任何持久化的通道都不可能还有活动 socket；
+ * 2. 之后每 {@link NOTIFICATION_CHANNEL_SWEEP_INTERVAL_MINUTES} 分钟清扫一次：无 socket 的通道
+ *    需要连续两次被判定为孤儿才删除，避免误删“刚 POST 出来、socket 还在握手”的通道。
+ *
+ * 只回收本实例 `baseUrl` 下的通道：通道 id 由本实例的订阅路由生成，Cloud 集群中共享
+ * `internal_kv` 的其他节点（若存在）的通道由各自实例负责，这里不做跨实例删除。
+ * 与 socket 归属相关的限制（同一个 baseUrl 被多个 CSS 进程共享时无法判断通道是否在别的进程里存活）
+ * 见 `docs/COMPONENTS.md`。
+ */
+export declare class NotificationChannelSweeper extends Initializer implements Finalizable {
+    protected readonly logger: import("global-logger-factory").Logger<unknown>;
+    private readonly channelStorage;
+    private readonly channelIndex;
+    private readonly socketMap;
+    private readonly baseUrl;
+    private readonly intervalMs;
+    /** 见过一次、但当时没有活动 socket 的通道 id；下一次仍是孤儿才回收。 */
+    private readonly awaitingSecondLook;
+    private timer?;
+    private sweeping;
+    constructor(storage: NotificationChannelStorage, channelIndex: KeyValueStorage<string, unknown>, socketMap: WebSocketMap, baseUrl: string, intervalMinutes?: number);
+    /**
+     * CSS 启动序列的一部分（在 HTTP server 开始监听之前执行）：先做一次启动清扫，再挂上有界的周期任务。
+     *
+     * 实测同一次 CSS 启动里本方法会被调用两次（配置图里只出现一次）。这里做成幂等：重复调用既不重复清扫，
+     * 也不重复注册定时器——两个定时器会让“连续两次判定”退化成相隔几百毫秒的两次判定，等于没有宽限期。
+     */
+    handle(): Promise<void>;
+    finalize(): Promise<void>;
+    /**
+     * 执行一次清扫，返回被回收的通道数量。
+     *
+     * @param initial - 启动清扫：内存中还没有任何 socket，因此无 socket 的通道一律视为孤儿。
+     */
+    sweep(initial?: boolean): Promise<number>;
+    /** 枚举本实例 baseUrl 下的通道记录。topic 索引行（值是 id 数组）不是通道，跳过。 */
+    private listOwnedChannels;
+}