@undefineds.co/xpod 0.4.11 → 0.4.12

package/dist/api/handlers/AdminHandler.js

@@ -16,6 +16,7 @@ exports.isAdminMutationAllowed = isAdminMutationAllowed;
 exports.createAdminServicesCapabilities = createAdminServicesCapabilities;
 exports.readDurableAdminEnvironment = readDurableAdminEnvironment;
 exports.writeDurableAdminEnvironmentPatch = writeDurableAdminEnvironmentPatch;
+exports.describeUnservedPublicRoute = describeUnservedPublicRoute;
 exports.registerAdminRoutes = registerAdminRoutes;
 const node_crypto_1 = require("node:crypto");
 const fs_1 = __importDefault(require("fs"));
@@ -23,6 +24,7 @@ const path_1 = __importDefault(require("path"));
 const fs_2 = require("fs");
 const readline_1 = require("readline");
 const runtime_1 = require("../../runtime");
+const log_file_1 = require("../../logging/log-file");
 const GatewayAdminProxyAuth_1 = require("../../runtime/GatewayAdminProxyAuth");
 const CONFIG_DIR = path_1.default.resolve(runtime_1.PACKAGE_ROOT, 'config');
 function getEnvFilePath() {
@@ -345,6 +347,29 @@ function parseJsonBody(req) {
         req.on('error', reject);
     });
 }
+/**
+ * Why a coordinated public domain cannot be served, or `null` when nothing
+ * rules it out.
+ *
+ * A domain issued in tunnel mode is published by the configured tunnel, so a
+ * node that reports tunnel mode with no provider has a route that nothing
+ * serves. This is the one reachability fact the runtime can establish locally;
+ * everything else about a domain can only be confirmed from outside.
+ */
+function describeUnservedPublicRoute(ddnsManager) {
+    let status;
+    try {
+        status = ddnsManager?.getStatus();
+    }
+    catch {
+        // An unreadable DDNS state must not turn into a reachability claim.
+        return null;
+    }
+    if (!status || status.mode !== 'tunnel' || (status.tunnelProvider && status.tunnelProvider !== 'none')) {
+        return null;
+    }
+    return '域名由隧道模式协调，但当前没有配置任何隧道提供商，公网入口无法提供服务。';
+}
 function registerAdminRoutes(server, options = {}) {
     const logger = console;
     // GET /api/admin/status - Get xpod status
@@ -554,20 +579,9 @@ function registerAdminRoutes(server, options = {}) {
             const url = new URL(req.url || '', `http://${req.headers.host}`);
             const lines = parseInt(url.searchParams.get('lines') || '100', 10);
             const env = readEnvFile(getEnvFilePath());
-            // Try common log file locations
-            const logPaths = [
-                path_1.default.resolve(process.cwd(), 'logs', 'combined.log'),
-                path_1.default.resolve(process.cwd(), 'logs', 'error.log'),
-                path_1.default.resolve(process.cwd(), 'xpod.log'),
-                path_1.default.resolve(process.cwd(), 'combined.log'),
-            ];
-            let logPath = null;
-            for (const p of logPaths) {
-                if (fs_1.default.existsSync(p)) {
-                    logPath = p;
-                    break;
-                }
-            }
+            // The runtime writes one rotating file per day; resolve it through the
+            // same definition the writers use instead of guessing file names here.
+            const logPath = (0, log_file_1.resolveCurrentLogFile)();
             if (!logPath) {
                 sendJson(res, 404, { error: 'No log file found' });
                 return;
@@ -659,7 +673,20 @@ function registerAdminRoutes(server, options = {}) {
                 });
                 return;
             }
-            // Domain name: we can only do best-effort.
+            // A domain cannot be verified from inside this process. What the runtime
+            // does know is whether the tunnel that publishes the domain runs at all,
+            // and returning `pass` from an address lookup alone contradicted that
+            // state: this endpoint used to call a dead public route reachable.
+            const unserved = describeUnservedPublicRoute(options.ddnsManager);
+            if (unserved) {
+                sendJson(res, 200, {
+                    status: 'fail',
+                    ipv4: ip,
+                    baseUrl,
+                    detail: unserved,
+                });
+                return;
+            }
             if (!ip) {
                 sendJson(res, 200, {
                     status: 'unknown',
@@ -670,10 +697,10 @@ function registerAdminRoutes(server, options = {}) {
                 return;
             }
             sendJson(res, 200, {
-                status: 'pass',
+                status: 'unknown',
                 ipv4: ip,
                 baseUrl,
-                detail: '已配置域名，默认可直连（仍需确保端口映射/防火墙放行）。',
+                detail: '已配置域名，但本机无法验证公网可达性；请从外部网络访问该地址确认。',
             });
         }
         catch (error) {
@@ -681,7 +708,9 @@ function registerAdminRoutes(server, options = {}) {
             sendJson(res, 500, { error: 'Failed to detect public ip' });
         }
     };
-    // Routes bypass general authentication and enforce the admin policy in each handler.
+    // Admin routes skip MultiAuthenticator (`public: true`) but enforce the admin
+    // policy themselves: loopback clients, or XPOD_ADMIN_TOKEN / signed gateway
+    // proxy headers for everything else.
     server.get('/api/admin/status', statusHandler, { public: true });
     server.get('/api/admin/config', getConfigHandler, { public: true });
     server.get('/api/admin/public-ip', ipv4Handler, { public: true });

package/dist/api/handlers/AiConfigHandler.d.ts

@@ -1,6 +1,7 @@
 import type { ApiServer } from '../ApiServer';
 import type { SolidAuthContext } from '../auth/AuthContext';
 import type { PodLookupRepository } from '../../identity/drizzle/PodLookupRepository';
+import { EmbeddingModelPolicy } from '../../ai/service/EmbeddingModelPolicy';
 export type AiConfigModelAssignment = 'chatModel' | 'ocrModel' | 'readerModel' | 'embeddingModel' | 'indexerModel' | 'rerankerModel';
 export interface AiConfigPolicy {
     schemaVersion: '1.0';
@@ -93,5 +94,10 @@ export interface AiConfigHandlerOptions {
     store: AiConfigPolicyStore;
     capabilities?: () => AiConfigCapabilities;
     lifecycle?: AiConfigLifecycleService;
+    /**
+     * Deployment policy for embedding assignments. Local runtimes allow any model;
+     * Cloud runtimes only accept models the ai-gateway catalog provides.
+     */
+    embeddingModelPolicy?: EmbeddingModelPolicy;
 }
 export declare function registerAiConfigRoutes(server: ApiServer, options: AiConfigHandlerOptions): void;

package/dist/api/handlers/AiConfigHandler.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerAiConfigRoutes = registerAiConfigRoutes;
 const readBoundedJsonBody_1 = require("../http/readBoundedJsonBody");
 const GatewayPrincipal_1 = require("../ai-gateway/auth/GatewayPrincipal");
+const EmbeddingModelPolicy_1 = require("../../ai/service/EmbeddingModelPolicy");
 function registerAiConfigRoutes(server, options) {
     server.get('/api/ai/config', async (request, response) => {
         const owner = await resolveOwner(request, response, options);
@@ -34,6 +35,15 @@ function registerAiConfigRoutes(server, options) {
             sendJson(response, 400, { error: 'Invalid AI Config update' });
             return;
         }
+        const rejected = rejectedEmbeddingAssignment(patch, options.embeddingModelPolicy);
+        if (rejected) {
+            sendJson(response, 400, {
+                error: EmbeddingModelPolicy_1.EMBEDDING_MODEL_NOT_ALLOWED,
+                message: 'This deployment only allows embedding models provided by the AI gateway',
+                ...rejected,
+            });
+            return;
+        }
         try {
             const config = await options.store.update({ ...owner, patch });
             sendJson(response, 200, {
@@ -94,6 +104,24 @@ async function resolveOwner(request, response, options) {
     }
     return { webId, podUrl, auth: request.auth };
 }
+/**
+ * Returns the offending assignment when the deployment policy rejects it, so the
+ * caller can answer with a stable error instead of a generic 400.
+ */
+function rejectedEmbeddingAssignment(patch, policy) {
+    if (!policy?.isEnforced() || !('models' in patch)) {
+        return undefined;
+    }
+    const assignment = patch.models?.embeddingModel;
+    if (assignment === undefined || assignment === null) {
+        return undefined;
+    }
+    const ref = (0, EmbeddingModelPolicy_1.parseEmbeddingModelRef)(assignment);
+    if (ref && policy.isAllowed(ref)) {
+        return undefined;
+    }
+    return ref ?? { model: assignment };
+}
 function parsePolicyPatch(value) {
     if (!isRecord(value))
         return undefined;

package/dist/api/handlers/AiGatewayManagementHandler.js

@@ -9,6 +9,7 @@ const models_1 = require("../ai-gateway/models");
 const AiConnectionsServiceAccess_1 = require("../ai-gateway/service-access/AiConnectionsServiceAccess");
 const AiClientConfigurationService_1 = require("../service/AiClientConfigurationService");
 const errors_1 = require("../ai-gateway/errors");
+const EmbeddingModelPolicy_1 = require("../../ai/service/EmbeddingModelPolicy");
 const provider_http_transport_1 = require("../service/provider-http-transport");
 const logger = (0, global_logger_factory_1.getLoggerFor)('AiGatewayManagementHandler');
 function registerAiGatewayManagementRoutes(server, options) {
@@ -1240,6 +1241,20 @@ function normalizeStringList(value) {
 }
 function sendCustomModelsError(response, error) {
     const message = error instanceof Error ? error.message : String(error);
+    if (message === 'provider_not_available_in_deployment') {
+        sendJson(response, 403, {
+            error: 'provider_not_available_in_deployment',
+            message: 'This deployment only offers the providers it provides',
+        });
+        return;
+    }
+    if ((0, EmbeddingModelPolicy_1.isEmbeddingModelNotAllowedError)(error)) {
+        sendJson(response, 403, {
+            error: EmbeddingModelPolicy_1.EMBEDDING_MODEL_NOT_ALLOWED,
+            message: 'This deployment only allows embedding models provided by the AI gateway',
+        });
+        return;
+    }
     if (message === 'models_credential_not_found') {
         sendJson(response, 404, { error: 'Provider credential not found for current identity' });
         return;
@@ -1275,6 +1290,20 @@ function sendCredentialPoolError(response, error) {
         return;
     }
     const message = error instanceof Error ? error.message : String(error);
+    if (message === 'provider_endpoint_not_configurable_in_cloud') {
+        sendJson(response, 403, {
+            error: 'provider_endpoint_not_configurable_in_cloud',
+            message: 'This deployment provides the provider endpoint; it cannot be set from a connection',
+        });
+        return;
+    }
+    if (message === 'provider_not_available_in_deployment') {
+        sendJson(response, 403, {
+            error: 'provider_not_available_in_deployment',
+            message: 'This deployment only offers the providers it provides',
+        });
+        return;
+    }
     if (message === 'local_session_reauth_required' || message === 'local_session_missing_refresh_token'
         || message === 'local_session_refresh_failed') {
         sendJson(response, message === 'local_session_refresh_failed' ? 502 : 409, { error: message });
@@ -1326,6 +1355,13 @@ function sendLegacyProviderConnectError(response, error) {
         return;
     }
     const message = error instanceof Error ? error.message : String(error);
+    if (message === 'provider_endpoint_not_configurable_in_cloud') {
+        sendJson(response, 403, {
+            error: 'provider_endpoint_not_configurable_in_cloud',
+            message: 'This deployment provides the provider endpoint; it cannot be set from a connection',
+        });
+        return;
+    }
     if (/^OAuth refresh failed: (?:invalid_grant|invalid_token)$/u.test(message)) {
         sendJson(response, 409, { error: 'oauth_session_reauth_required' });
         return;

package/dist/api/runs/RdfRunContextRetriever.d.ts

@@ -22,6 +22,13 @@ export interface RdfRunContextRetrieverOptions<TContext = StoreContext> {
     failOpen?: boolean;
     textWeight?: number;
     vectorWeight?: number;
+    /**
+     * Minimum vector similarity for the vector-only fallback. The fused query
+     * implicitly filters by "the text side matched"; a vector-only retry has no
+     * such filter, so without a floor every prompt would return its nearest (and
+     * possibly unrelated) chunks.
+     */
+    vectorFallbackThreshold?: number;
     vectorProvider?: string;
     vectorModel?: string;
     vectorModelVersion?: string;
@@ -44,6 +51,13 @@ export declare class RdfRunContextRetriever<TContext = StoreContext> implements
     private readonly options;
     constructor(options: RdfRunContextRetrieverOptions<TContext>);
     retrieve(input: RunContextRetrievalInput<TContext>): Promise<RunRetrievedContext | undefined>;
+    /**
+     * Retrieval is semantic first: the fused query joins text and vector hits, so a
+     * prompt the text index cannot match (CJK tokenisation, a paraphrase) would drop
+     * its vector hits and return nothing. Retry with the vector side alone when the
+     * fused query came back empty.
+     */
+    private vectorOnlyQuery;
     private buildDefaultQuery;
     private searchScope;
     private cacheScope;

package/dist/api/runs/RdfRunContextRetriever.js

@@ -4,6 +4,8 @@ exports.RdfRunContextRetriever = void 0;
 const n3_1 = require("n3");
 const RdfAccessScope_1 = require("../../storage/rdf/RdfAccessScope");
 const { literal } = n3_1.DataFactory;
+/** Cosine similarity floor for the vector-only fallback. */
+const DEFAULT_VECTOR_FALLBACK_THRESHOLD = 0.3;
 /**
  * Product-level Run context retriever backed by SolidRdfEngine/PostgresRdfEngine.
  *
@@ -26,7 +28,10 @@ class RdfRunContextRetriever {
                 ? await this.options.buildQuery(input, embedding)
                 : this.buildDefaultQuery(input, embedding);
             const result = await this.options.rdfEngine.query(this.withAccessScope(query, input));
-            const items = result.bindings
+            const rows = result.bindings.length > 0 || !query.vectorSearch?.length
+                ? result
+                : await this.options.rdfEngine.query(this.withAccessScope(this.vectorOnlyQuery(query), input));
+            const items = rows.bindings
                 .map((row) => this.bindingToContextItem(row))
                 .filter((item) => item !== undefined)
                 .slice(0, this.options.limit ?? 8);
@@ -37,7 +42,7 @@ class RdfRunContextRetriever {
                 query: prompt,
                 items,
                 generatedAt: Math.floor(Date.now() / 1000),
-                plan: result.metrics.plan,
+                plan: rows.metrics.plan,
             };
         }
         catch (error) {
@@ -47,6 +52,26 @@ class RdfRunContextRetriever {
             throw error;
         }
     }
+    /**
+     * Retrieval is semantic first: the fused query joins text and vector hits, so a
+     * prompt the text index cannot match (CJK tokenisation, a paraphrase) would drop
+     * its vector hits and return nothing. Retry with the vector side alone when the
+     * fused query came back empty.
+     */
+    vectorOnlyQuery(query) {
+        const threshold = this.options.vectorFallbackThreshold ?? DEFAULT_VECTOR_FALLBACK_THRESHOLD;
+        return {
+            ...query,
+            textSearch: undefined,
+            // The fusion score references the text score, which is unbound here.
+            binds: undefined,
+            orderBy: [{ variable: 'vectorScore', direction: 'desc' }],
+            vectorSearch: query.vectorSearch?.map((pattern) => ({
+                ...pattern,
+                threshold: pattern.threshold ?? threshold,
+            })),
+        };
+    }
     buildDefaultQuery(input, embedding) {
         const limit = this.options.limit ?? 8;
         const scope = this.searchScope(input);
@@ -111,6 +136,9 @@ class RdfRunContextRetriever {
                     heading: 'vectorHeading',
                     score: 'vectorScore',
                     distance: 'vectorDistance',
+                    workspace: 'vectorWorkspace',
+                    localPath: 'vectorLocalPath',
+                    contentType: 'vectorContentType',
                     sourceKey: 'sourceKey',
                     retrievalPoint: 'retrievalPointKey',
                     provider: 'vectorProvider',
@@ -146,11 +174,17 @@ class RdfRunContextRetriever {
             ];
             query.select = [
                 ...(query.select ?? []),
+                // The vector pattern binds its own source variable; a vector-only row has
+                // no text source, so it must be projected to map the row at all.
+                'vectorSource',
                 'vectorChunk',
                 'vectorContent',
                 'vectorHeading',
                 'vectorScore',
                 'vectorDistance',
+                'vectorWorkspace',
+                'vectorLocalPath',
+                'vectorContentType',
                 'vectorProvider',
                 'vectorModel',
                 'vectorModelVersion',
@@ -205,7 +239,9 @@ class RdfRunContextRetriever {
     }
     bindingToContextItem(row) {
         const text = termValue(row.textContent) || termValue(row.vectorContent);
-        const source = termValue(row.source);
+        // The vector pattern binds its own source variable, so a vector-only row has
+        // no `source` binding at all.
+        const source = termValue(row.source) || termValue(row.vectorSource);
         if (!text || !source) {
             return undefined;
         }
@@ -243,8 +279,8 @@ class RdfRunContextRetriever {
             source,
             text,
             score: fusionScore ?? textScore ?? vectorScore,
-            workspace: termValue(row.workspace),
-            localPath: termValue(row.localPath),
+            workspace: termValue(row.workspace) || termValue(row.vectorWorkspace),
+            localPath: termValue(row.localPath) || termValue(row.vectorLocalPath),
             heading,
             metadata,
         };

package/dist/api/runtime.js

@@ -5,6 +5,7 @@ exports.startApiService = startApiService;
 const awilix_1 = require("awilix");
 const global_logger_factory_1 = require("global-logger-factory");
 const ConfigurableLoggerFactory_1 = require("../logging/ConfigurableLoggerFactory");
+const log_file_1 = require("../logging/log-file");
 const container_1 = require("./container");
 const routes_1 = require("./container/routes");
 const OpenAuthMiddleware_1 = require("./middleware/OpenAuthMiddleware");
@@ -18,7 +19,7 @@ function ensureTrailingSlash(url) {
 }
 function initApiLogger() {
     const loggerFactory = new ConfigurableLoggerFactory_1.ConfigurableLoggerFactory(process.env.CSS_LOGGING_LEVEL || 'info', {
-        fileName: './logs/xpod-%DATE%.log',
+        fileName: (0, log_file_1.resolveLogFilePattern)(),
         showLocation: true,
     });
     (0, global_logger_factory_1.setGlobalLoggerFactory)(loggerFactory);

package/dist/cli/commands/secret.d.ts

@@ -20,6 +20,7 @@ export interface SecretPlan {
     resourceKind: string;
     service: string;
     provider: string;
+    providerUri: string;
     kind: string;
     subject: string;
     resourceUrl: string;

package/dist/cli/commands/secret.js

@@ -80,18 +80,34 @@ function localId(input) {
         .join('-')
         .replace(/[^a-zA-Z0-9_.-]+/g, '-');
 }
+/**
+ * models 0.2.57 dropped `secretType` and turned `providerId` into the `provider`
+ * relation, so a credential's classification lives in attributes and its id
+ * stays a pure layout key. The CLI keeps its `kind` vocabulary as the operator
+ * facing word and maps it onto the schema's `authMode`.
+ */
+const AUTH_MODE_BY_KIND = {
+    'api-key': 'apiKey',
+    'tunnel-token': 'apiKey',
+};
+/** The provider document a credential points at, as the shared relation. */
+function providerRelation(provider) {
+    return models_1.aiProviderResource.buildId({ id: provider });
+}
 function buildSecretPlan(podRoot, input) {
     const service = input.service ?? 'ai';
     const storage = (0, models_1.createPodStorage)();
+    const authMode = AUTH_MODE_BY_KIND[input.kind];
     const validation = storage.validate({
         schemaUri: models_1.credentialDescriptor.uri,
         operation: 'upsert',
         match: {
-            service,
-            providerId: input.provider,
-            secretType: input.kind,
+            id: localId(input),
         },
         set: {
+            service,
+            provider: providerRelation(input.provider),
+            ...(authMode ? { authMode } : {}),
             status: 'active',
         },
     });
@@ -105,6 +121,9 @@ function buildSecretPlan(podRoot, input) {
         resourceKind: models_1.credentialDescriptor.resourceKind,
         service,
         provider: input.provider,
+        // The relation is stored as `<provider>.ttl` and emitted as the absolute
+        // provider document IRI, which is the shape the Pod adapters write.
+        providerUri: models_1.aiProviderResource.buildIri(podRoot, { id: input.provider }),
         kind: input.kind,
         subject: resourceUrl,
         resourceUrl: resourceUrl.replace(/#.*$/u, ''),
@@ -114,10 +133,9 @@ function buildSecretPlan(podRoot, input) {
 function buildSecretUpsertSparql(plan, input) {
     const subject = `<${plan.subject}>`;
     const fields = models_1.credentialDescriptor.fields;
+    const authMode = AUTH_MODE_BY_KIND[plan.kind];
     const values = {
         service: plan.service,
-        providerId: plan.provider,
-        secretType: plan.kind,
         status: input.status ?? (input.revoke ? 'revoked' : 'active'),
     };
     if (input.label)
@@ -137,8 +155,8 @@ function buildSecretUpsertSparql(plan, input) {
     const insertTriples = [
         `${subject} a <${models_1.credentialDescriptor.class}>`,
         `${subject} <${fields.service.predicate}> ${escapeSparqlLiteral(values.service)}`,
-        `${subject} <${fields.providerId.predicate}> ${escapeSparqlLiteral(values.providerId)}`,
-        `${subject} <${fields.secretType.predicate}> ${escapeSparqlLiteral(values.secretType)}`,
+        `${subject} <${fields.provider.predicate}> <${plan.providerUri}>`,
+        ...(authMode ? [`${subject} <${fields.authMode.predicate}> ${escapeSparqlLiteral(authMode)}`] : []),
         `${subject} <${fields.status.predicate}> ${escapeSparqlLiteral(values.status)}`,
     ];
     if (values.label) {

package/dist/components/components.jsonld

@@ -144,6 +144,8 @@
     "undefineds:dist/edge/reachability/ManagedClientFetch.jsonld",
     "undefineds:dist/edge/reachability/ManagedClientP2PSmoke.jsonld",
     "undefineds:dist/edge/reachability/P2PRealnetAcceptance.jsonld",
-    "undefineds:dist/notifications/device-notification-protocol.jsonld"
+    "undefineds:dist/notifications/device-notification-protocol.jsonld",
+    "undefineds:dist/notifications/NotificationChannelSweeper.jsonld",
+    "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld"
   ]
 }

package/dist/components/context.jsonld

@@ -1076,6 +1076,9 @@
           "options_resourceSuffix": {
             "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler_options_resourceSuffix"
           },
+          "emitter": {
+            "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler_emitter"
+          },
           "queryEngine": {
             "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler_queryEngine"
           },
@@ -2893,6 +2896,9 @@
         "@context": {
           "providerRegistry": {
             "@id": "undefineds:dist/ai/service/EmbeddingServiceImpl.jsonld#EmbeddingServiceImpl_providerRegistry"
+          },
+          "options_policy": {
+            "@id": "undefineds:dist/ai/service/EmbeddingServiceImpl.jsonld#EmbeddingServiceImpl_options_policy"
           }
         }
       },
@@ -2904,7 +2910,11 @@
       "CredentialReaderImpl": {
         "@id": "undefineds:dist/ai/service/CredentialReaderImpl.jsonld#CredentialReaderImpl",
         "@prefix": true,
-        "@context": {}
+        "@context": {
+          "options_secretDecoder": {
+            "@id": "undefineds:dist/ai/service/CredentialReaderImpl.jsonld#CredentialReaderImpl_options_secretDecoder"
+          }
+        }
       },
       "CloudflareTunnelProvider": {
         "@id": "undefineds:dist/tunnel/CloudflareTunnelProvider.jsonld#CloudflareTunnelProvider",
@@ -4237,6 +4247,48 @@
         "@id": "undefineds:dist/notifications/device-notification-protocol.jsonld#ParseClientFrameOptions",
         "@prefix": true,
         "@context": {}
+      },
+      "NotificationChannelSweeper": {
+        "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper",
+        "@prefix": true,
+        "@context": {
+          "baseUrl": {
+            "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_baseUrl"
+          },
+          "intervalMinutes": {
+            "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_intervalMinutes"
+          },
+          "storage": {
+            "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_storage"
+          },
+          "socketMap": {
+            "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_socketMap"
+          },
+          "channelIndex": {
+            "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_channelIndex"
+          },
+          "es": {
+            "@id": "undefineds:dist/notifications/NotificationChannelSweeper.jsonld#NotificationChannelSweeper_intervalMinutes"
+          }
+        }
+      },
+      "ReclaimingWebSocket2023Storer": {
+        "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer",
+        "@prefix": true,
+        "@context": {
+          "cleanupTimer": {
+            "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer_cleanupTimer"
+          },
+          "storage": {
+            "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer_storage"
+          },
+          "socketMap": {
+            "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer_socketMap"
+          },
+          "er": {
+            "@id": "undefineds:dist/notifications/ReclaimingWebSocket2023Storer.jsonld#ReclaimingWebSocket2023Storer_cleanupTimer"
+          }
+        }
       }
     }
   ]

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;