neotoma 0.26.0 → 0.28.0

package/dist/actions.js

@@ -1,4 +1,4 @@
-import { preflightStructuredStoreAdmission, } from "./services/store_admission.js";
+import { assertCurrentAgentMayStoreEntityTypes, assertStoreEntityTypesNamed, InvalidEntityTypeError, preflightStructuredStoreAdmission, } from "./services/store_admission.js";
 import express from "express";
 import cookieParser from "cookie-parser";
 import cors from "cors";
@@ -38,6 +38,7 @@ import { CursorError } from "./services/entity_cursor.js";
 import { assertNoShadowedRoutes } from "./services/route_shadowing.js";
 import { StorePolicyDeniedError, StorePolicyUnavailableError } from "./services/instance_policy.js";
 import { AgentCapabilityError, contextFromAgentIdentity, enforceAgentCapability, } from "./services/agent_capabilities.js";
+import { ISSUE_THREAD_ENTITY_TYPES, assertCurrentAgentMay, assertCurrentAgentMayLink, assertCurrentAgentMayOnEntities, assetEntityTypeForMimeType, } from "./services/mutation_capability.js";
 import { AccessPolicyError } from "./services/access_policy.js";
 import { hashGuestAccessToken } from "./services/guest_access_token.js";
 import { subscriptionWithinGuestScope } from "./services/subscriptions/guest_scope.js";
@@ -45,6 +46,7 @@ import { IssueTransportError, IssueValidationError } from "./services/issues/err
 import { externalActorFromCallerInput } from "./services/issues/external_actor_builder.js";
 import { getCurrentAAuthAdmission, getCurrentAgentIdentity, getCurrentAttribution, getCurrentExternalActor, runWithAuthenticatedPrincipal, runWithExternalActor, runWithRequestContext, } from "./services/request_context.js";
 import { assertCanWriteProtectedBatch } from "./services/protected_entity_types.js";
+import { createMcpLookupReceiptObserver, observeMcpLookupResponse, } from "./services/mcp_lookup_timing.js";
 import { redactMemberAttribution } from "./services/attribution_redaction.js";
 import { createAgentIdentity as buildAgentIdentity, getAgentIdentityFromRequest, normaliseClientName, } from "./crypto/agent_identity.js";
 import { initServerKeys } from "./services/encryption_service.js";
@@ -73,12 +75,14 @@ import { getSandboxTermsResponse } from "./services/sandbox/terms.js";
 import { resolveSandboxReportTransport } from "./services/sandbox/transport.js";
 import { getDb } from "./repositories/db/connection.js";
 import { getMcpAuthToken } from "./crypto/mcp_auth_token.js";
+import { announceBearerHandoverStatus, matchConfiguredBearer, recordPreviousBearerUse, } from "./services/bearer_slots.js";
 import { isOauthKeyCredentialValid, normalizeOauthNextPath, OAuthKeySessionStore, } from "./services/oauth_key_gate.js";
 import { buildGoogleAuthorizeUrl, createGoogleSigninNonce, consumeGoogleSigninNonce, exchangeGoogleAuthorizationCode, getSharedGraphUserId, GoogleIdTokenError, isGoogleSigninEnabled, verifyGoogleIdToken, } from "./services/google_oidc.js";
 import { AnalyzeSchemaCandidatesRequestSchema, AuditUndeclaredFragmentsRequestSchema, CorrectEntityRequestSchema, PatchArrayItemRequestSchema, CreateInterpretationRequestSchema, CreateRelationshipsRequestSchema, CreateRelationshipRequestSchema, DeleteEntityRequestSchema, DeleteRelationshipRequestSchema, IssuesBulkEntityIdsRequestSchema, IssuesAddMessageRequestSchema, IssuesGetStatusRequestSchema, IssuesSubmitRequestSchema, IssuesSyncRequestSchema, EntitiesQueryRequestSchema, EntitySnapshotRequestSchema, FieldProvenanceRequestSchema, GetSchemaRecommendationsRequestSchema, ListObservationsRequestSchema, ListRelationshipsRequestSchema, MergeEntitiesRequestSchema, SplitEntityRequestSchema, ObservationsQueryRequestSchema, RegisterSchemaRequestSchema, RelationshipSnapshotRequestSchema, RestoreEntityRequestSchema, RestoreRelationshipRequestSchema, RetrieveEntityByIdentifierSchema, RetrieveGraphNeighborhoodSchema, RetrieveRelatedEntitiesSchema, RELATIONSHIP_ENTITY_ID_FORMAT_HINT, RELATIONSHIP_ENTITY_ID_FORMAT_ISSUE_CODE, ObservationSourceSchema, StoreRequestSchema, UpdateSchemaIncrementalRequestSchema, } from "./shared/action_schemas.js";
 import { DEFAULT_OBSERVATION_SOURCE } from "./services/observation_insert.js";
 import { getMimeTypeFromExtension } from "./services/file_text_extraction.js";
 import { queryEntitiesWithCount } from "./shared/action_handlers/entity_handlers.js";
+import { EXACT_IDENTITY_REQUEST_MESSAGE, exactIdentityRequested, readExactIdentity, } from "./shared/action_handlers/exact_identity_read.js";
 import { retrieveEntityByIdentifierWithFallback } from "./shared/action_handlers/entity_identifier_handler.js";
 import { prepareEntitySnapshotWithEmbedding, upsertEntitySnapshotWithEmbedding, } from "./services/entity_snapshot_embedding.js";
 import { isNeotomaEntityId } from "./shared/neotoma_entity_id.js";
@@ -108,6 +112,9 @@ export function getResolvedServerMode() {
     return _resolvedServerMode;
 }
 export const app = express();
+const mcpLookupReceiptObserver = createMcpLookupReceiptObserver();
+if (mcpLookupReceiptObserver)
+    app.use(mcpLookupReceiptObserver);
 // Trust proxy headers (required for express-rate-limit when X-Forwarded-For is present)
 app.set("trust proxy", true);
 // Configure CSP to allow CDN scripts for the uploader and API connects
@@ -230,7 +237,10 @@ app.use(express.json({
         req.rawBody = Buffer.from(buf);
     },
 }));
-app.use(morgan("dev"));
+app.use(morgan("dev", {
+    // Suppress identity-bearing URLs independently of route spelling or method.
+    skip: (req) => exactIdentityRequested(req.query),
+}));
 app.use(cookieParser());
 app.use(unknownFieldsGuard);
 // Sandbox-mode response header. Stamped on every response so clients can
@@ -1762,6 +1772,7 @@ app.all("/mcp", async (req, res) => {
         const authHeader = (req.headers["authorization"] || req.headers["Authorization"]);
         let connectionIdHeader = (req.headers["x-connection-id"] || req.headers["X-Connection-Id"]);
         let bearerValidated = false;
+        let primaryBearerValidated = false;
         // Development connection identities are assigned by this gate, not by the
         // client. A client-sent value is honoured only where the gate would assign
         // the same identity itself: a local caller in development mode. Anywhere
@@ -1805,7 +1816,21 @@ app.all("/mcp", async (req, res) => {
             }
             if (authHeader?.startsWith("Bearer ") && process.env.NEOTOMA_BEARER_TOKEN) {
                 const token = authHeader.slice(7).trim();
-                if (safeCompareTokens(token, process.env.NEOTOMA_BEARER_TOKEN)) {
+                // Either configured slot (primary, or the retiring bearer while its
+                // handover window is open) takes the SAME branch: same principal,
+                // same grants. See src/services/bearer_slots.ts.
+                const slot = matchConfiguredBearer(token);
+                if (slot) {
+                    primaryBearerValidated = slot === "primary";
+                    if (slot === "previous") {
+                        recordPreviousBearerUse({
+                            surface: "mcp",
+                            method: req.method,
+                            path: req.path,
+                            userAgent: req.headers["user-agent"],
+                            clientName: req.headers["x-client-name"],
+                        });
+                    }
                     setGateConnectionIdHeader(req, "dev-local");
                     connectionIdHeader = "dev-local";
                     bearerValidated = true;
@@ -1966,6 +1991,8 @@ app.all("/mcp", async (req, res) => {
             return res.status(shaped.status).json(shaped.body);
         }
         // Legacy session path (2025-11-25 and earlier). Unchanged by #2070.
+        // A qualified lookup can disconnect while stale-session recovery is still pending.
+        const mcpLookupTiming = primaryBearerValidated ? observeMcpLookupResponse(req, res) : undefined;
         // Get or create transport
         let transport = sessionId ? mcpTransports.get(sessionId) : undefined;
         let serverInstance = sessionId
@@ -2103,6 +2130,7 @@ app.all("/mcp", async (req, res) => {
             // The gate's resolved connection id: the MCP server reads this, never
             // the request's X-Connection-Id header.
             mcpConnectionId: connectionIdHeader ?? null,
+            mcpLookupTiming,
         }, () => transport.handleRequest(req, res, req.body));
     }
     catch (error) {
@@ -2173,13 +2201,18 @@ function redactSensitiveFields(obj) {
     }
     return redacted;
 }
+function redactEntityReadInput(value) {
+    return exactIdentityRequested(value)
+        ? { read_mode: "exact_identity" }
+        : redactSensitiveFields(value);
+}
 function logDebug(event, req, extra) {
     const safe = {
         method: req.method,
         path: req.path,
-        query: redactSensitiveFields(req.query),
+        query: redactEntityReadInput(req.query),
         headers: redactHeaders(req.headers),
-        body: redactSensitiveFields(req.body),
+        body: redactEntityReadInput(req.body),
         ...(extra ? redactSensitiveFields(extra) : {}),
     };
     // eslint-disable-next-line no-console
@@ -2189,9 +2222,9 @@ function logWarn(event, req, extra) {
     const safe = {
         method: req.method,
         path: req.path,
-        query: redactSensitiveFields(req.query),
+        query: redactEntityReadInput(req.query),
         headers: redactHeaders(req.headers),
-        body: redactSensitiveFields(req.body),
+        body: redactEntityReadInput(req.body),
         ...(extra ? redactSensitiveFields(extra) : {}),
     };
     // eslint-disable-next-line no-console
@@ -2219,9 +2252,9 @@ function logError(event, req, error, extra) {
     const payload = {
         method: req.method,
         path: req.path,
-        query: redactSensitiveFields(req.query),
+        query: redactEntityReadInput(req.query),
         headers: redactHeaders(req.headers),
-        body: redactSensitiveFields(req.body),
+        body: redactEntityReadInput(req.body),
         error: error instanceof Error
             ? {
                 name: error.name,
@@ -3825,10 +3858,22 @@ app.use(async (req, res, next) => {
         }
         if (headerAuth.startsWith("Bearer ") && process.env.NEOTOMA_BEARER_TOKEN) {
             const token = headerAuth.slice(7).trim();
-            if (safeCompareTokens(token, process.env.NEOTOMA_BEARER_TOKEN)) {
+            // Either configured slot takes the SAME branch: same principal, same
+            // grants. See src/services/bearer_slots.ts.
+            const slot = matchConfiguredBearer(token);
+            if (slot) {
+                if (slot === "previous") {
+                    recordPreviousBearerUse({
+                        surface: "rest",
+                        method: req.method,
+                        path: req.path,
+                        userAgent: req.headers["user-agent"],
+                        clientName: req.headers["x-client-name"],
+                    });
+                }
                 const devUser = await ensureLocalDevUser();
                 stampUserPrincipal(req, devUser.id);
-                logger.info(`[Auth] ${req.method} ${req.path} auth_method=bearer_env user_id=${devUser.id}`);
+                logger.info(`[Auth] ${req.method} ${req.path} auth_method=${slot === "previous" ? "bearer_env_previous" : "bearer_env"} user_id=${devUser.id}`);
                 return next();
             }
         }
@@ -4267,6 +4312,18 @@ function handleApiError(req, res, error, defaultMessage, errorCode = "DB_QUERY_F
 // (POST body, or query-string params coerced by coerceEntitiesQueryParams).
 // REQUIRES AUTHENTICATION - all queries filtered by authenticated user_id.
 async function runEntitiesQuery(req, res, rawInput) {
+    if (exactIdentityRequested(rawInput)) {
+        try {
+            const userId = await getAuthenticatedUserId(req);
+            const exact_identity = await readExactIdentity(rawInput, userId);
+            if (!exact_identity)
+                return sendError(res, 400, "VALIDATION_ERROR", EXACT_IDENTITY_REQUEST_MESSAGE);
+            return res.set("Cache-Control", "no-store").json({ exact_identity });
+        }
+        catch (error) {
+            return handleApiError(req, res, error, "Could not verify exact identity");
+        }
+    }
     const parsed = EntitiesQueryRequestSchema.safeParse(rawInput);
     if (!parsed.success) {
         logWarn("ValidationError:entities_query", req, {
@@ -4389,6 +4446,8 @@ function coerceEntitiesQueryParams(query) {
 // `GET /entities?entity_type=...&search=...` no longer hit a 404 and silently
 // degrade. REQUIRES AUTHENTICATION - identical user scoping to the POST path.
 app.get("/entities", async (req, res) => {
+    if (exactIdentityRequested(req.query))
+        return sendError(res, 400, "VALIDATION_ERROR", "Exact identity requires POST /entities/query.");
     return runEntitiesQuery(req, res, coerceEntitiesQueryParams(req.query));
 });
 // POST /api/entities/query - Query entities with filters
@@ -4594,26 +4653,10 @@ app.get("/entities/:id/html", async (req, res) => {
         if (etag)
             res.setHeader("ETag", etag);
         res.setHeader("Content-Type", "text/html; charset=utf-8");
-        // SECURITY (Phase 2, stored XSS in publish_rendered_page): html_body is
-        // author-supplied and served verbatim, and the GLOBAL CSP allows
-        // 'unsafe-inline' scripts — so an injected <script> in a rendered page would
-        // execute in this origin (a page minted with a guest access_token is viewable
-        // unauthenticated). Rendered pages are static CONTENT, never applications:
-        // they never need to run script. Override the global policy for THIS response
-        // with a strict, self-contained CSP that blocks all script execution (inline
-        // and external) and sandboxes the document, neutralizing stored XSS regardless
-        // of html_body contents. Inline <style> from the template is still allowed.
-        res.setHeader("Content-Security-Policy", [
-            "default-src 'none'",
-            "script-src 'none'",
-            "style-src 'unsafe-inline'",
-            "img-src 'self' data:",
-            "font-src 'self' data:",
-            "base-uri 'none'",
-            "form-action 'none'",
-            "frame-ancestors 'self'",
-            "sandbox allow-same-origin",
-        ].join("; "));
+        // Author scripts stay blocked. Opted-in copy blocks permit only the fixed
+        // renderer-owned helper, confined to an opaque-origin sandbox.
+        const { renderedPageContentSecurityPolicy } = await import("./services/rendered_page/copy_controls.js");
+        res.setHeader("Content-Security-Policy", renderedPageContentSecurityPolicy(htmlBody));
         res.setHeader("X-Content-Type-Options", "nosniff");
         return res.send(html);
     }
@@ -4671,6 +4714,10 @@ app.post("/entities/:id/batch_correct", async (req, res) => {
         if (error instanceof Error && error.message.includes("Not authenticated")) {
             return sendError(res, 401, "AUTH_REQUIRED", error.message);
         }
+        // Capability denial: same 403 `capability_denied` envelope as /correct.
+        if (error instanceof AgentCapabilityError) {
+            return handleApiError(req, res, error, "Failed to apply batch correction", "DB_QUERY_FAILED", "AgentCapabilityRejection:entity_batch_correct");
+        }
         logError("APIError:entity_batch_correct", req, error);
         const message = error instanceof Error ? error.message : "Failed to apply batch correction";
         return sendError(res, 500, "DB_QUERY_FAILED", message);
@@ -4911,7 +4958,42 @@ app.get("/schemas", async (req, res) => {
         // restricted WHICH entity types appear; it never corrected the version, so
         // it could not compensate. `userId` is already required above, so scoping
         // here changes no caller's authorization, only the accuracy of the version.
-        const allSchemas = await schemaRegistry.listEntityTypes(keyword, userId);
+        const catalog = await schemaRegistry.listEntityTypesResult(keyword, userId);
+        const allSchemas = catalog.entity_types;
+        const summary = req.query.summary === "true";
+        if (summary) {
+            const selected = filterEntityType
+                ? allSchemas.filter((schema) => schema.entity_type === filterEntityType)
+                : allSchemas;
+            const sorted = [...selected].sort((a, b) => a.entity_type.localeCompare(b.entity_type));
+            const page = sorted.slice(offset, offset + limit);
+            const reasons = [...catalog.registry_coverage.reasons];
+            if (filterEntityType)
+                reasons.push("filtered");
+            if (offset !== 0 || page.length !== sorted.length)
+                reasons.push("paginated");
+            const complete = catalog.registry_coverage.state === "complete" && reasons.length === 0;
+            return res.json({
+                schemas: page.map(({ entity_type, schema_version, field_names, planning, planning_error }) => ({
+                    entity_type,
+                    schema_version,
+                    field_count: field_names.length,
+                    ...(planning ? { planning } : {}),
+                    ...(planning_error ? { planning_error } : {}),
+                })),
+                total: sorted.length,
+                limit,
+                offset,
+                registry_coverage: {
+                    ...catalog.registry_coverage,
+                    state: complete ? "complete" : "unknown",
+                    reasons: [...new Set(reasons)].sort(),
+                    returned_count: page.length,
+                    exhausted: complete,
+                    scope: { ...catalog.registry_coverage.scope, entity_type: filterEntityType || null },
+                },
+            });
+        }
         // Filter to only show global schemas (user_id is null) or user-specific schemas for this user
         // Also fetch metadata (including icons) for each schema
         const { data: dbSchemas, error: dbError } = await db
@@ -4942,6 +5024,16 @@ app.get("/schemas", async (req, res) => {
         const paginatedSchemas = sortedSchemas.slice(offset, offset + limit);
         return res.json({
             schemas: paginatedSchemas,
+            registry_coverage: {
+                ...catalog.registry_coverage,
+                state: "unknown",
+                exhausted: false,
+                returned_count: paginatedSchemas.length,
+                reasons: [
+                    ...new Set([...catalog.registry_coverage.reasons, "legacy_filtered_view"]),
+                ].sort(),
+                scope: { ...catalog.registry_coverage.scope, entity_type: filterEntityType || null },
+            },
             total: productionSchemas.length,
             limit,
             offset,
@@ -6097,6 +6189,10 @@ app.post("/interpretations/create", async (req, res) => {
     }
     try {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
+        // Same per-type `store` capability scope `/store` applies, before any
+        // source lookup or write. No-op without an agent identity.
+        const { assertInterpretationStoreCapability, runInterpretation } = await import("./services/interpretation.js");
+        await assertInterpretationStoreCapability(userId, parsed.data.entities);
         const { data: source, error: sourceError } = await db
             .from("sources")
             .select("id")
@@ -6108,7 +6204,6 @@ app.post("/interpretations/create", async (req, res) => {
         if (!source) {
             return sendError(res, 404, "SOURCE_NOT_FOUND", "Source not found for authenticated user");
         }
-        const { runInterpretation } = await import("./services/interpretation.js");
         const interpretationResult = await runInterpretation({
             userId,
             sourceId: parsed.data.source_id,
@@ -6190,6 +6285,14 @@ app.post("/interpretations/create", async (req, res) => {
         });
     }
     catch (error) {
+        // Capability denial: same 403 `capability_denied` envelope as `/store`.
+        if (error instanceof AgentCapabilityError) {
+            return handleApiError(req, res, error, "Failed to create interpretation", "INTERPRETATION_CREATE_FAILED", "AgentCapabilityRejection:interpretations_create");
+        }
+        if (error instanceof InvalidEntityTypeError) {
+            logWarn("InvalidEntityTypeError:interpretations_create", req, { code: error.code });
+            return sendError(res, 400, error.code, error.message, { hint: error.hint });
+        }
         logError("APIError:interpretations_create", req, error);
         const message = error instanceof Error ? error.message : "Failed to create interpretation";
         return sendError(res, 500, "INTERPRETATION_CREATE_FAILED", message);
@@ -6302,6 +6405,9 @@ app.post("/observations/create", async (req, res) => {
                 .status(403)
                 .json(buildErrorEnvelope("FORBIDDEN", "user_id does not match authenticated user."));
         }
+        // Same per-type `store` capability scope `/store` applies, before the
+        // entity is resolved or created. No-op without an agent identity.
+        assertCurrentAgentMayStoreEntityTypes([entity_type]);
         const { resolveEntity } = await import("./services/entity_resolution.js");
         const { createObservation } = await import("./services/observation_storage.js");
         const { getSnapshot, recomputeSnapshot } = await import("./services/snapshot_computation.js");
@@ -6333,6 +6439,10 @@ app.post("/observations/create", async (req, res) => {
         });
     }
     catch (error) {
+        // Capability denial: same 403 `capability_denied` envelope as `/store`.
+        if (error instanceof AgentCapabilityError) {
+            return handleApiError(req, res, error, "Failed to create observation", "DB_QUERY_FAILED", "AgentCapabilityRejection:observations_create");
+        }
         logError("APIError:observations_create", req, error);
         const message = error instanceof Error ? error.message : "Failed to create observation";
         return res.status(500).json(buildErrorEnvelope("DB_QUERY_FAILED", message));
@@ -7619,6 +7729,9 @@ export async function storeUnstructuredForApi(params) {
             observations_created: 0,
         };
     }
+    // Agent grants: an upload is recorded under its asset type (the type the
+    // MCP leg writes for the same bytes). Checked before the source is stored.
+    assertCurrentAgentMay("store", [assetEntityTypeForMimeType(mimeType)], { guestCapable: true });
     if (storageMode === "reference") {
         if (!filePath) {
             throw new Error("filePath is required for reference storage mode");
@@ -7693,9 +7806,24 @@ async function handleStorePost(req, res) {
         const { assertConditionalStoreRequest } = await import("./services/store_condition_request.js");
         assertConditionalStoreRequest(parsed.data);
         const hasEntities = Boolean(parsed.data.entities?.length);
+        // Every entity must name its type as a non-empty string, for every caller
+        // kind, before either leg of the request writes anything.
+        if (hasEntities)
+            assertStoreEntityTypesNamed(parsed.data.entities);
         const hasFileContent = Boolean(parsed.data.file_content && parsed.data.mime_type);
         const hasFilePath = Boolean(parsed.data.file_path);
         const hasUnstructured = hasFileContent || hasFilePath;
+        // Agent grants on the file leg, before either leg writes, so a combined
+        // entities-and-file call refused on the file writes no entities either.
+        if (hasUnstructured && parsed.data.commit !== false) {
+            const uploadMime = parsed.data.mime_type ||
+                (parsed.data.file_path
+                    ? getMimeTypeFromExtension(path.extname(parsed.data.file_path).toLowerCase())
+                    : undefined);
+            assertCurrentAgentMay("store", [assetEntityTypeForMimeType(uploadMime)], {
+                guestCapable: true,
+            });
+        }
         if (hasEntities && hasUnstructured && parsed.data.commit !== false) {
             const { claimCombinedStoreKeys } = await import("./services/store_combined_admission.js");
             await claimCombinedStoreKeys({
@@ -7863,6 +7991,10 @@ async function handleStorePost(req, res) {
             logWarn("AgentGrantPinConflict:store", req, { code: error.code });
             return sendError(res, 409, error.code, error.message, { field: error.field });
         }
+        if (error instanceof InvalidEntityTypeError) {
+            logWarn("InvalidEntityTypeError:store", req, { code: error.code });
+            return sendError(res, 400, error.code, error.message, { hint: error.hint });
+        }
         if (errCode === "ERR_FORBIDDEN_ENTITY_TYPE" || errCode === "ERR_PLURAL_ENTITY_TYPE") {
             const message = error instanceof Error ? error.message : String(error);
             logWarn("EntityTypeGuardError:store", req, { code: errCode, message });
@@ -8083,6 +8215,10 @@ app.post("/sync/webhook", express.raw({ type: "application/json", limit: "2mb" }
         if (msg === "INVALID_JSON" || msg.startsWith("VALIDATION_ERROR")) {
             return sendError(res, 400, "VALIDATION_ERROR", msg);
         }
+        if (msg.startsWith("REMOTE_ENTITY_TYPE_REFUSED")) {
+            const { SYNC_ENTITY_TYPE_REFUSED_ERROR_CODE } = await import("./services/sync/remote_snapshot_admission.js");
+            return sendError(res, 403, SYNC_ENTITY_TYPE_REFUSED_ERROR_CODE, msg);
+        }
         logError("APIError:sync_webhook", req, err);
         return sendError(res, 500, "SYNC_WEBHOOK_FAILED", msg);
     }
@@ -8159,6 +8295,9 @@ app.post("/peers", express.json(), async (req, res) => {
         return res.status(201).json(out);
     }
     catch (error) {
+        if (error instanceof AgentCapabilityError) {
+            return handleApiError(req, res, error, "Failed to add peer");
+        }
         logError("APIError:peers_add", req, error);
         const message = error instanceof Error ? error.message : "Failed to add peer";
         if (message.includes("Maximum peers")) {
@@ -8167,8 +8306,11 @@ app.post("/peers", express.json(), async (req, res) => {
         return sendError(res, 500, "PEER_ADD_FAILED", message);
     }
 });
-// POST /peers/resolve_sync_conflict — stub (use `correct` today). Registered
-// before `/peers/:peer_id` so `resolve_sync_conflict` is not captured as a peer_id.
+// POST /peers/resolve_sync_conflict — resolve a replication conflict. `prefer_remote`
+// and `manual` write correction-tier values, so they run the same `correct` capability
+// gate as `/correct`; `prefer_remote` applies the differing fields as one correction
+// transaction and reports applied and withheld fields. Registered before
+// `/peers/:peer_id` so `resolve_sync_conflict` is not captured as a peer_id.
 app.post("/peers/resolve_sync_conflict", express.json(), async (req, res) => {
     const schema = z.object({
         entity_id: z.string().min(1),
@@ -8199,6 +8341,14 @@ app.post("/peers/resolve_sync_conflict", express.json(), async (req, res) => {
         return res.json(result);
     }
     catch (error) {
+        // A capability or protected-type refusal is the caller's authorization,
+        // not a server fault: 403 with the envelope `/correct` returns.
+        if (error instanceof AgentCapabilityError) {
+            logWarn("AgentCapabilityRejection:peers_resolve", req, error.toErrorEnvelope());
+            return res
+                .status(403)
+                .json(buildErrorEnvelope(error.code, error.message, error.toErrorEnvelope()));
+        }
         logError("APIError:peers_resolve", req, error);
         const message = error instanceof Error ? error.message : "resolve failed";
         return sendError(res, 500, "PEER_RESOLVE_FAILED", message);
@@ -8225,11 +8375,16 @@ app.get("/peers/:peer_id", async (req, res) => {
 app.delete("/peers/:peer_id", async (req, res) => {
     try {
         const userId = await getAuthenticatedUserId(req);
+        // Agent grants: removing a peer corrects its peer_config.
+        assertCurrentAgentMay("correct", ["peer_config"]);
         const { removePeerForUser } = await import("./services/sync/peer_ops.js");
         await removePeerForUser({ userId, peer_id: req.params.peer_id });
         return res.json({ success: true });
     }
     catch (error) {
+        if (error instanceof AgentCapabilityError) {
+            return handleApiError(req, res, error, "Failed to remove peer");
+        }
         logError("APIError:peers_remove", req, error);
         const message = error instanceof Error ? error.message : "Failed to remove peer";
         if (message.includes("not found")) {
@@ -8245,11 +8400,17 @@ app.post("/peers/:peer_id/sync", express.json(), async (req, res) => {
         const bodySchema = z.object({ limit: z.number().int().positive().max(500).optional() });
         const bodyParsed = bodySchema.safeParse(req.body ?? {});
         const limit = bodyParsed.success ? bodyParsed.data.limit : undefined;
+        // Agent grants: a sync run sends local data to the peer and advances the
+        // peer_config watermark; pulled rows are still checked per type by store.
+        assertCurrentAgentMay("correct", ["peer_config"]);
         const { syncPeerFull } = await import("./services/sync/full_sync.js");
         const result = await syncPeerFull({ userId, peer_id: req.params.peer_id, limit });
         return res.json(result);
     }
     catch (error) {
+        if (error instanceof AgentCapabilityError) {
+            return handleApiError(req, res, error, "sync_peer failed");
+        }
         logError("APIError:peers_sync", req, error);
         const message = error instanceof Error ? error.message : "sync_peer failed";
         return sendError(res, 500, "PEER_SYNC_FAILED", message);
@@ -8350,6 +8511,8 @@ app.post("/entities/merge", async (req, res) => {
         if (providedUserId && providedUserId !== authenticatedUserId) {
             return sendError(res, 403, "FORBIDDEN", "user_id does not match authenticated user.");
         }
+        // Agent grants: `merge` on both entities' stored types, before any write.
+        await assertCurrentAgentMayOnEntities("merge", user_id, [from_entity_id, to_entity_id]);
         const { mergeEntities } = await import("./services/entity_merge.js");
         const result = await mergeEntities({
             fromEntityId: from_entity_id,
@@ -8361,6 +8524,9 @@ app.post("/entities/merge", async (req, res) => {
         return res.json(result);
     }
     catch (error) {
+        if (error instanceof AgentCapabilityError) {
+            return handleApiError(req, res, error, "Failed to merge entities");
+        }
         const { EntityNotFoundError, EntityAlreadyMergedError } = await import("./services/entity_merge.js");
         if (error instanceof EntityNotFoundError) {
             return sendError(res, 404, "RESOURCE_NOT_FOUND", error.message);
@@ -8390,6 +8556,9 @@ app.post("/entities/split", async (req, res) => {
             return sendError(res, 403, "FORBIDDEN", "user_id does not match authenticated user.");
         }
         const userId = providedUserId || authenticatedUserId;
+        // Agent grants: `split` on the source's stored type, the new entity's
+        // type and, when the split targets an existing entity, its stored type.
+        await assertCurrentAgentMayOnEntities("split", userId, [parsed.data.source_entity_id, parsed.data.new_entity.target_entity_id ?? ""], [parsed.data.new_entity.entity_type]);
         const { splitEntity } = await import("./services/entity_split.js");
         const result = await splitEntity({
             sourceEntityId: parsed.data.source_entity_id,
@@ -8407,6 +8576,9 @@ app.post("/entities/split", async (req, res) => {
         return res.json(result);
     }
     catch (error) {
+        if (error instanceof AgentCapabilityError) {
+            return handleApiError(req, res, error, "Failed to split entity");
+        }
         const { EntityNotFoundError, EntityAlreadyMergedError, SplitPredicateMatchedNothingError, SplitPredicateMatchedAllError, IdempotencyMismatchError, } = await import("./services/entity_split.js");
         if (error instanceof EntityNotFoundError) {
             return sendError(res, 404, "RESOURCE_NOT_FOUND", error.message);
@@ -8479,12 +8651,14 @@ app.post("/get_entity_snapshot", async (req, res) => {
     }
     // Materialization is derived state. Validate owned current authority before
     // serving its row, including restrictive corruption acquisition failures.
+    // The check reads the entity's lifecycle authority rows, not its whole
+    // observation history (#2792).
     try {
-        const { isEntityDeleted } = await import("./services/deletion.js");
+        const { isOwnedEntityHiddenAfterCutover } = await import("./services/current_state_reads.js");
         const { hasRecordedEntityLifecycleCutover } = await import("./services/entity_lifecycle_storage.js");
         const { getDb } = await import("./repositories/db/connection.js");
         if ((await hasRecordedEntityLifecycleCutover(await getDb())) &&
-            (await isEntityDeleted(entity_id, userId)))
+            (await isOwnedEntityHiddenAfterCutover(entity_id, userId)))
             return sendError(res, 404, "RESOURCE_NOT_FOUND", "Entity not found");
     }
     catch (err) {
@@ -9177,6 +9351,9 @@ app.post("/delete_entity", async (req, res) => {
     try {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
         const { entity_id, entity_type, reason } = parsed.data;
+        // Agent grants: `delete` on the stored type (and the type the request
+        // names), before the deletion observation is written.
+        await assertCurrentAgentMayOnEntities("delete", userId, [entity_id], [entity_type]);
         const { softDeleteEntity } = await import("./services/deletion.js");
         const result = await softDeleteEntity(entity_id, entity_type, userId, reason);
         if (!result.success) {
@@ -9199,6 +9376,8 @@ app.post("/issues/bulk_close", async (req, res) => {
     }
     try {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
+        // Agent grants: closing corrects the issue (and its GitHub state).
+        await assertCurrentAgentMayOnEntities("correct", userId, parsed.data.entity_ids, ["issue"]);
         const { bulkCloseIssues } = await import("./services/issues/inspector_bulk.js");
         const { results } = await bulkCloseIssues(userId, parsed.data.entity_ids);
         logDebug("Success:issues_bulk_close", req, { count: results.length });
@@ -9217,6 +9396,8 @@ app.post("/issues/bulk_remove", async (req, res) => {
     }
     try {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
+        // Agent grants: removal closes and soft-deletes the issue.
+        await assertCurrentAgentMayOnEntities("delete", userId, parsed.data.entity_ids, ["issue"]);
         const { bulkRemoveIssues } = await import("./services/issues/inspector_bulk.js");
         const { results } = await bulkRemoveIssues(userId, parsed.data.entity_ids);
         logDebug("Success:issues_bulk_remove", req, { count: results.length });
@@ -9239,6 +9420,15 @@ const handleIssuesAddMessageHttp = async (req, res) => {
         const userId = principal.kind === "guest"
             ? (await resolveGuestScopedEntityAccess(principal, parsed.data.entity_id?.trim() || "", "issue")).userId
             : await getAuthenticatedUserId(req, parsed.data.user_id);
+        // Agent grants on the owner path: a thread message is an issue-thread
+        // write (and a GitHub comment). The in-process operations layer below does
+        // not carry the caller's grant, so the check runs here, before anything is
+        // written. The guest path stays scoped by its guest access token.
+        if (principal.kind !== "guest") {
+            assertCurrentAgentMay("store", ISSUE_THREAD_ENTITY_TYPES, { guestCapable: true });
+            // Edges from the issue to entities the caller names.
+            await assertCurrentAgentMayLink(userId, "issue", "REFERS_TO", parsed.data.entity_ids_to_link ?? [], { guestCapable: true });
+        }
         const { createOperations } = await import("./core/operations.js");
         const { NeotomaServer } = await import("./server.js");
         const { addIssueMessage, appendGuestIssueMessage } = await import("./services/issues/issue_operations.js");
@@ -9311,6 +9501,16 @@ const handleIssuesSubmitHttp = async (req, res) => {
                 ? ((await resolveGuestUserId(req, principal)) ??
                     (await getAuthenticatedUserId(req, parsed.data.user_id)))
                 : await getAuthenticatedUserId(req, parsed.data.user_id);
+        // Agent grants on the owner path: it writes an issue thread under the
+        // owner and may open a GitHub issue. The in-process operations layer below
+        // does not carry the caller's grant, so the check runs here, before
+        // anything is written. The guest path stays under access policy, as for
+        // any guest.
+        if (!(principal.kind === "guest" || guestSubmitPayload)) {
+            assertCurrentAgentMay("store", ISSUE_THREAD_ENTITY_TYPES, { guestCapable: true });
+            // Edges from the new issue to entities the caller names.
+            await assertCurrentAgentMayLink(userId, "issue", "REFERS_TO", [...(parsed.data.entity_ids_to_link ?? []), parsed.data.conversation_turn_id ?? ""], { guestCapable: true });
+        }
         const { createOperations } = await import("./core/operations.js");
         const { NeotomaServer } = await import("./server.js");
         const { submitIssue, submitGuestIssue } = await import("./services/issues/issue_operations.js");
@@ -9434,6 +9634,10 @@ const handleIssuesSyncHttp = async (req, res) => {
     }
     try {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
+        // Agent grants: a sync stores new issue threads, corrects existing ones
+        // and can push local issues to GitHub.
+        assertCurrentAgentMay("store", ISSUE_THREAD_ENTITY_TYPES);
+        assertCurrentAgentMay("correct", ISSUE_THREAD_ENTITY_TYPES);
         const { createOperations } = await import("./core/operations.js");
         const { NeotomaServer } = await import("./server.js");
         const { syncIssuesFromGitHub } = await import("./services/issues/sync_issues_from_github.js");
@@ -9480,6 +9684,9 @@ app.post("/restore_entity", async (req, res) => {
     try {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
         const { entity_id, entity_type, reason } = parsed.data;
+        // Agent grants: `restore` on the stored type (and the type the request
+        // names), before the restoration observation is written.
+        await assertCurrentAgentMayOnEntities("restore", userId, [entity_id], [entity_type]);
         const { restoreEntity } = await import("./services/deletion.js");
         const result = await restoreEntity(entity_id, entity_type, userId, reason);
         if (!result.success) {
@@ -9744,12 +9951,14 @@ app.post("/update_schema_incremental", async (req, res) => {
     }
     try {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
-        const { entity_type, fields_to_add, fields_to_remove, canonical_name_fields, schema_version, 
+        const { entity_type, fields_to_add, fields_to_remove, canonical_name_fields, planning, schema_version, 
         // #2374: no local `= false` default. `user_specific` stays
         // `undefined` when the caller omitted it, so `updateSchemaIncremental`
         // can defer to whichever scope its own read resolved instead of being
         // told "global" by a default this route manufactured.
         user_specific, activate = true, migrate_existing = false, force = false, } = parsed.data;
+        // Agent grants: `register_schema` on the entity type, before any write.
+        assertCurrentAgentMay("register_schema", [entity_type]);
         const { schemaRegistry, loadCodeDefinedSchemaEntry } = await import("./services/schema_registry.js");
         // #2454 / #2374 REST parity with the MCP handler: the existence guard
         // resolves the SAME row `updateSchemaIncremental` will read —
@@ -9818,6 +10027,7 @@ app.post("/update_schema_incremental", async (req, res) => {
                 // re-key (the MCP server handler had it, but this Express route — which
                 // the CLI offline transport uses — did not).
                 canonical_name_fields,
+                planning,
                 schema_version,
                 user_specific,
                 // #2374: pass userId unconditionally — same reasoning as the MCP
@@ -10032,6 +10242,8 @@ app.post("/register_schema", async (req, res) => {
     try {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
         const { entity_type, schema_definition, reducer_config, schema_version = "1.0", user_specific = false, activate = false, force = false, } = parsed.data;
+        // Agent grants: `register_schema` on the entity type, before any write.
+        assertCurrentAgentMay("register_schema", [entity_type]);
         const { schemaRegistry } = await import("./services/schema_registry.js");
         // R2 back-compat: existing HTTP/CLI callers may register schemas
         // without declaring canonical_name_fields or identity_opt_out (e.g. the
@@ -10582,6 +10794,8 @@ app.post("/unsubscribe", guestWriteRateLimit, async (req, res) => {
                 return sendError(res, 403, "FORBIDDEN", "Guest access token does not grant access to this subscription");
             }
         }
+        // Agent grants: unsubscribing corrects the subscription (active=false).
+        assertCurrentAgentMay("correct", ["subscription"], { guestCapable: true });
         await unsubscribeUser({ userId, subscription_id: parsed.data.subscription_id });
         return res.json({ success: true });
     }
@@ -11279,6 +11493,10 @@ export async function startHTTPServer() {
         }
         throw err;
     }
+    // Report the bearer handover slot (NEOTOMA_BEARER_TOKEN_PREVIOUS) at boot,
+    // so a misconfigured slot is loud at startup rather than at the first
+    // consumer's 401. Fail-closed parsing lives in services/bearer_slots.ts.
+    announceBearerHandoverStatus();
     // Initialize encryption service
     await initServerKeys();
     // Seed the built-in schema registry from ENTITY_SCHEMAS (issue #1968).