neotoma 0.25.0 → 0.26.0

package/dist/actions.js

@@ -1,3 +1,4 @@
+import { preflightStructuredStoreAdmission, } from "./services/store_admission.js";
 import express from "express";
 import cookieParser from "cookie-parser";
 import cors from "cors";
@@ -35,14 +36,14 @@ import { OwnedEntityNotFoundError, SOURCES_STORAGE_BUCKET } from "./services/sco
 import { invalidEntityIdRelationshipRefusal, relationshipRefusalFromError, unresolvedRelationshipRefusal, } from "./services/store_relationships.js";
 import { CursorError } from "./services/entity_cursor.js";
 import { assertNoShadowedRoutes } from "./services/route_shadowing.js";
-import { StorePolicyUnavailableError } from "./services/instance_policy.js";
+import { StorePolicyDeniedError, StorePolicyUnavailableError } from "./services/instance_policy.js";
 import { AgentCapabilityError, contextFromAgentIdentity, enforceAgentCapability, } from "./services/agent_capabilities.js";
-import { assertGuestWriteAllowed, AccessPolicyError, } from "./services/access_policy.js";
+import { AccessPolicyError } from "./services/access_policy.js";
 import { hashGuestAccessToken } from "./services/guest_access_token.js";
 import { subscriptionWithinGuestScope } from "./services/subscriptions/guest_scope.js";
 import { IssueTransportError, IssueValidationError } from "./services/issues/errors.js";
 import { externalActorFromCallerInput } from "./services/issues/external_actor_builder.js";
-import { getCurrentAAuthAdmission, getCurrentAgentIdentity, getCurrentAttribution, getCurrentExternalActor, getRequestContext, runWithAuthenticatedPrincipal, runWithExternalActor, runWithRequestContext, } from "./services/request_context.js";
+import { getCurrentAAuthAdmission, getCurrentAgentIdentity, getCurrentAttribution, getCurrentExternalActor, runWithAuthenticatedPrincipal, runWithExternalActor, runWithRequestContext, } from "./services/request_context.js";
 import { assertCanWriteProtectedBatch } from "./services/protected_entity_types.js";
 import { redactMemberAttribution } from "./services/attribution_redaction.js";
 import { createAgentIdentity as buildAgentIdentity, getAgentIdentityFromRequest, normaliseClientName, } from "./crypto/agent_identity.js";
@@ -74,7 +75,8 @@ import { getDb } from "./repositories/db/connection.js";
 import { getMcpAuthToken } from "./crypto/mcp_auth_token.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, 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, StoreRequestSchema, UpdateSchemaIncrementalRequestSchema, } from "./shared/action_schemas.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 { retrieveEntityByIdentifierWithFallback } from "./shared/action_handlers/entity_identifier_handler.js";
@@ -92,6 +94,7 @@ import { buildComplianceScorecard } from "./services/compliance/scorecard.js";
 import { getAgent, listAgentRecords, listAgents } from "./services/agents_directory.js";
 import { computeEntitySnapshotAtTime } from "./services/entity_snapshot_at_time.js";
 import { isProductionEnvironment } from "./shared/environment.js";
+import { isLoopbackHost, resolveBindHostFromEnv } from "./shared/bind_host.js";
 // Set to true during startHTTPServer() when resolveSandboxMode() returns
 // "local_sandbox". Read by getAuthenticatedUserId() to substitute the
 // per-install fingerprinted sandbox principal for the shared nil UUID fallback.
@@ -455,21 +458,25 @@ function isInternalSeedRequest(req) {
 // available so a single abusive client does not starve others. Operators
 // can tune with NEOTOMA_WRITE_RATE_LIMIT_PER_MIN.
 const WRITE_RATE_LIMIT_PER_MIN = Math.max(1, Number.parseInt(process.env.NEOTOMA_WRITE_RATE_LIMIT_PER_MIN || "", 10) || 120);
-const writeRateLimit = rateLimit({
-    windowMs: 60 * 1000,
-    max: WRITE_RATE_LIMIT_PER_MIN,
-    keyGenerator: (req) => {
-        const userId = req.authenticatedUserId || "";
-        if (userId)
-            return `u:${userId}`;
-        // Use the library-provided IPv6-safe key helper; keying directly on
-        // req.ip lets IPv6 callers rotate the low-64 bits to bypass limits.
-        return `ip:${ipKeyGenerator(req.ip || "")}`;
-    },
-    skip: isInternalSeedRequest,
-    message: "Write rate limit exceeded, please slow down",
-    ...rateLimitOptions,
-});
+/** Build the shared write limiter; exported so its limiting effect is testable without a listener. */
+export function createWriteRateLimit(max = WRITE_RATE_LIMIT_PER_MIN) {
+    return rateLimit({
+        windowMs: 60 * 1000,
+        max,
+        keyGenerator: (req) => {
+            const userId = req.authenticatedUserId || "";
+            if (userId)
+                return `u:${userId}`;
+            // Use the library-provided IPv6-safe key helper; keying directly on
+            // req.ip lets IPv6 callers rotate the low-64 bits to bypass limits.
+            return `ip:${ipKeyGenerator(req.ip || "")}`;
+        },
+        skip: isInternalSeedRequest,
+        message: "Write rate limit exceeded, please slow down",
+        ...rateLimitOptions,
+    });
+}
+const writeRateLimit = createWriteRateLimit();
 // SECURITY: guest-capable write routes (issue submission / thread append,
 // subscribe / unsubscribe) should not share the broader `/store` bucket.
 // Key by cryptographic guest identity first, then scoped guest token, then IP.
@@ -4163,6 +4170,13 @@ function handleApiError(req, res, error, defaultMessage, errorCode = "DB_QUERY_F
             .status(error.statusCode)
             .json(buildErrorEnvelope(error.code, error.message, error.toErrorEnvelope()));
     }
+    if (error instanceof StorePolicyDeniedError) {
+        logWarn(logContext || "StorePolicyDenied", req, {
+            denied_count: error.denied.length,
+            reason_codes: [...new Set(error.denied.map((denial) => denial.reason_code))].sort(),
+        });
+        return res.status(400).json({ error: error.toErrorEnvelope() });
+    }
     if (error instanceof StorePolicyUnavailableError) {
         // 503, not 400: the write was refused because the instance could not read
         // its own policy, which is a service-side fault the caller can retry — not
@@ -4266,7 +4280,12 @@ async function runEntitiesQuery(req, res, rawInput) {
         // the request for access control.
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
         const { entity_type, entity_types, search, limit, offset, cursor, sort_by, sort_order, published, published_after, published_before, include_snapshots, include_merged, updated_since, created_since, identity_basis, snapshot_filters, exclude_bookkeeping, } = parsed.data;
-        const { entities, total, applied_search_strategies, search_mode, next_cursor } = await queryEntitiesWithCount({
+        const { entities, total, applied_search_strategies, search_mode, next_cursor, read_contract } = await queryEntitiesWithCount({
+            readRequest: {
+                raw: (req.method === "GET" ? req.query : rawInput),
+                surface: req.method === "GET" ? "http_get" : "http_post",
+                consumed: [...Object.keys(parsed.data), "query", "search_query"],
+            },
             userId,
             entityType: entity_type,
             entityTypes: entity_types,
@@ -4292,6 +4311,7 @@ async function runEntitiesQuery(req, res, rawInput) {
             total,
             limit,
             offset,
+            read_contract,
             ...(applied_search_strategies ? { applied_search_strategies } : {}),
             search_mode,
             ...(next_cursor ? { next_cursor } : {}),
@@ -6259,9 +6279,9 @@ app.post("/observations/create", async (req, res) => {
         entity_identifier: z.string(),
         fields: z.record(z.unknown()),
         source_priority: z.number().optional().default(100),
-        observation_source: z
-            .enum(["sensor", "llm_summary", "workflow_state", "human", "import", "sync"])
-            .optional(),
+        // Shared enum (#2241): an inline copy here had drifted from the store
+        // schema's once already; reuse the single source instead.
+        observation_source: ObservationSourceSchema.optional(),
         source_peer_id: z.string().min(1).optional(),
         user_id: z.string().uuid(),
     });
@@ -6357,143 +6377,53 @@ async function completeInterpretationRun(params) {
     })
         .eq("id", params.interpretationId);
 }
+/**
+ * Structured store entry point.
+ *
+ * A committing store is a write: once it starts it runs to completion and is
+ * not cancelled by the caller's abort signal, and a second call for the same
+ * idempotency key waits for the first (#2144). See `runKeyedStoreWrite`.
+ * Plan mode (`commit: false`) writes nothing and the conditional path is its
+ * own atomic transaction, so both run as before.
+ */
 export async function storeStructuredForApi(params) {
-    const { userId, entities, sourcePriority, observationSource, sourcePeerId, idempotencyKey, originalFilename, relationships, interpretation, interpretationSourceId, commit: commitInput, strict: strictInput, } = params;
+    if (params.commit === false || params.expectedEntityAbsent === true) {
+        return storeStructuredForApiUnguarded(params);
+    }
+    const { runKeyedStoreWrite } = await import("./services/store_write_state.js");
+    return runKeyedStoreWrite(params.userId, params.idempotencyKey, () => storeStructuredForApiUnguarded(params));
+}
+async function storeStructuredForApiUnguarded(params) {
+    const { userId, entities, sourcePriority, observationSource, sourcePeerId, idempotencyKey, originalFilename, relationships, interpretation, interpretationSourceId, commit: commitInput, strict: strictInput, dataOrigins, } = params;
     const commit = commitInput !== false;
     const strict = strictInput === true;
-    // Access policy: when the caller is a guest (AAuth-verified but not admitted
-    // via a grant), check per-entity-type access policies. If the policy allows
-    // guest writes, the request proceeds without requiring an agent_grant.
-    const requestContext = getRequestContext();
-    const agentIdentity = getCurrentAgentIdentity();
-    const admission = getCurrentAAuthAdmission();
-    const isAAuthVerified = agentIdentity?.thumbprint != null;
-    const isGuest = isAAuthVerified && (!admission || !admission.admitted);
-    if (isGuest && !requestContext?.bypassGuestStoreAccessPolicy) {
-        const entityTypes = entities
-            .map((entity) => entity?.entity_type)
-            .filter((t) => typeof t === "string" && t.length > 0);
-        const guestId = {
-            thumbprint: agentIdentity.thumbprint,
-            sub: agentIdentity.sub,
-            iss: agentIdentity.iss,
-        };
-        await assertGuestWriteAllowed(entityTypes, guestId);
-    }
-    // usage_digest store-seam redaction guard (server-side backstop).
-    // Scope: strictly usage_digest entities only — no impact on any other entity type.
-    // For each incoming usage_digest entity, scan free-text fields `notes` and
-    // `friction_notes` via the pure redactUsageDigestEntity helper, and write the
-    // redacted copies back onto the entity object so the raw input is never persisted.
-    // This is a redact-and-store (scan) approach, not hard-reject, so a digest is
-    // never silently dropped on a client-side redaction miss.
-    //
-    // NOTE: Single telemetry sink today — entity_type === "usage_digest" is the only
-    // branch. If a second redacted-free-text entity_type appears, lift these field
-    // names into schema metadata (redact_free_text_fields) rather than adding another
-    // branch here.
-    {
-        const hasUsageDigest = entities.some((e) => e?.entity_type === "usage_digest");
-        if (hasUsageDigest) {
-            const { redactUsageDigestEntity } = await import("./services/feedback/usage_digest_redaction.js");
-            for (const entityData of entities) {
-                const ed = entityData;
-                if (ed.entity_type !== "usage_digest")
-                    continue;
-                const result = redactUsageDigestEntity(ed);
-                if (result.applied) {
-                    logger.warn(`[STORE] usage_digest server-side redaction applied: ${result.hits} hit(s) in free-text fields.`);
-                }
-            }
-        }
-    }
-    // Capability scoping: when the caller is an AAuth-verified agent covered
-    // by the capability registry, gate store_structured by entity_type here
-    // before any writes touch the DB. Guests who passed access policy above
-    // skip grant-based capability enforcement. Unknown / anonymous callers
-    // fall through (attribution_policy still gates their writes downstream).
-    const capabilityCtx = contextFromAgentIdentity(getCurrentAgentIdentity());
-    if (capabilityCtx && !isGuest) {
-        const entityTypes = entities
-            .map((entity) => entity?.entity_type)
-            .filter((t) => typeof t === "string" && t.length > 0);
-        enforceAgentCapability("store", entityTypes, capabilityCtx);
-        const relationshipOp = Array.isArray(relationships) && relationships.length > 0;
-        if (relationshipOp) {
-            enforceAgentCapability("create_relationship", entityTypes, capabilityCtx);
-        }
-    }
-    // Relationship-type validation, UP FRONT and BEFORE any entity is persisted
-    // (#1972 / G25).
-    //
-    // This closes the more damaging half of the closed-vocabulary defect. The
-    // relationships leg further down catches per edge and downgrades to
-    // logger.warn, so a store carrying an edge the substrate would not accept
-    // returned SUCCESS with the edge silently absent — a caller believed it had
-    // written a graph it had not written, and nothing in the response said
-    // otherwise. Validating here means an unacceptable type is a refusal the
-    // caller sees, and no entities are written that would have been orphaned by
-    // the edge that was going to fail anyway.
-    if (commit && Array.isArray(relationships) && relationships.length > 0) {
-        const { relationshipsService } = await import("./services/relationships.js");
-        const seen = new Set();
-        for (const rel of relationships) {
-            const type = rel?.relationship_type;
-            if (typeof type !== "string" || seen.has(type))
-                continue;
-            seen.add(type);
-            await relationshipsService.assertRegisteredType(type, userId);
-        }
-    }
-    // Protected-entity-types guard: governance state (`agent_grant`, etc.)
-    // is gated by an explicit capability on the admitted grant. Mirrors
-    // the same check made deep in `createObservation` so callers see a
-    // structured `capability_denied` envelope before any writes.
-    {
-        const entityTypes = entities
-            .map((entity) => entity?.entity_type)
-            .filter((t) => typeof t === "string" && t.length > 0);
-        assertCanWriteProtectedBatch({
-            entity_types: entityTypes,
-            op: "store",
-            identity: getCurrentAgentIdentity(),
-            admission: getCurrentAAuthAdmission(),
-        });
-    }
-    // A key thumbprint may be pinned by agent_grants under one owner only.
-    // Checked before any write so a refused pin persists nothing; the same
-    // check runs again at the observation insert.
-    if (entities.some((entity) => entity?.entity_type === "agent_grant")) {
-        const { assertGrantWriteKeepsPinUnique } = await import("./services/agent_grants.js");
-        for (const entity of entities) {
-            if (entity?.entity_type !== "agent_grant")
-                continue;
-            await assertGrantWriteKeepsPinUnique({
-                userId,
-                entityType: "agent_grant",
-                fields: entity,
-            });
-        }
-    }
+    await preflightStructuredStoreAdmission(params);
     const { resolveEntityWithTrace, CanonicalNameUnresolvedError, MergeRefusedError } = await import("./services/entity_resolution.js");
-    const { detectFlatPackedRows, FlatPackedRowsError } = await import("./services/flat_packed_detection.js");
     // R4: lazy import so the structured-store handler can attach required
     // identity-field hints when resolving fails under a reject policy.
     const registryModule = await import("./services/schema_registry.js");
     const deriveRequiredIdentityFields = registryModule.deriveRequiredIdentityFields;
-    // Reject flat-packed rows (whole tables smuggled into a single entity as
-    // `<prefix>_<index>_<suffix>` keys). These cannot produce per-row snapshots
-    // and are almost always a caller bug. The caller should split into one
-    // entity per row and retry.
-    for (const entityData of entities) {
-        const detection = detectFlatPackedRows(entityData);
-        if (detection.detected) {
-            throw new FlatPackedRowsError(detection);
-        }
+    if (params.expectedEntityAbsent === true) {
+        const { storeConditionalStructured } = await import("./services/store_conditional.js");
+        return storeConditionalStructured({
+            userId,
+            entities,
+            sourcePriority,
+            observationSource,
+            idempotencyKey,
+            originalFilename,
+            strict,
+            dataOrigin: dataOrigins?.[0],
+        });
     }
     // Compute hash of incoming content before querying so we can detect
-    // idempotency-key reuse with different content (issue #186).
-    const incomingJsonContent = JSON.stringify(entities, (key, value) => {
+    // idempotency-key reuse with different content (issue #186). Each entity's
+    // effective data_origin (#2242) is part of the stored payload, so a replay
+    // with a different origin is a mismatch rather than a silent drop; with no
+    // origin the stored JSON is unchanged.
+    const { entitiesWithStoredDataOrigins } = await import("./services/provenance_data_origin.js");
+    const storedEntities = entitiesWithStoredDataOrigins(entities, dataOrigins);
+    const incomingJsonContent = JSON.stringify(storedEntities, (key, value) => {
         if (typeof value === "bigint") {
             return Number(value);
         }
@@ -6501,9 +6431,14 @@ export async function storeStructuredForApi(params) {
     });
     const { computeContentHash: _computeContentHash } = await import("./services/raw_storage.js");
     const incomingContentHash = _computeContentHash(Buffer.from(incomingJsonContent, "utf-8"));
+    if (commit) {
+        const { assertLegacyStoreKeyMode } = await import("./services/store_condition_keys.js");
+        const { getDb } = await import("./repositories/db/connection.js");
+        await assertLegacyStoreKeyMode(await getDb(), userId, idempotencyKey);
+    }
     const { data: existingSource, error: existingSourceError } = await db
         .from("sources")
-        .select("id, content_hash")
+        .select("id, content_hash, provenance")
         .eq("user_id", userId)
         .eq("idempotency_key", idempotencyKey)
         .maybeSingle();
@@ -6523,6 +6458,51 @@ export async function storeStructuredForApi(params) {
                     "To update an entity, omit the idempotency_key or use a new one.";
             throw mismatchErr;
         }
+    }
+    // A recorded key is not a finished write (#2144): the source row is created
+    // before any observation, so a loop that stopped part way leaves a key that
+    // looks done. `resumeIncompleteWrite` is true when the earlier attempt did
+    // not finish; the replay branch below is then skipped and the ordinary write
+    // path runs again over the same source. That is safe because observation ids
+    // are deterministic (source, entity, fields), so entities already written
+    // resolve to their existing observation and only the missing ones are added.
+    let resumeIncompleteWrite = false;
+    if (existingSource && commit) {
+        const storeWriteState = await import("./services/store_write_state.js");
+        const recordedState = storeWriteState.readStoreWriteState(existingSource.provenance);
+        const incomplete = recordedState === "in_progress" ||
+            (recordedState === undefined &&
+                storeWriteState.legacyWriteLooksIncomplete({
+                    entities,
+                    observationCount: (await (await import("./services/observation_storage.js")).listObservationsForSource(existingSource.id, userId)).length,
+                    observationsOnKeyedSource: !interpretation?.source_id && !interpretationSourceId,
+                }));
+        if (incomplete) {
+            if (interpretation) {
+                // A resumed write would open a fresh interpretation run, whose id is
+                // part of each observation id, so the entities already written would
+                // be written a second time. Report the incomplete write instead.
+                // Count where the interrupted attempt wrote its observations: the
+                // interpretation's own source when it names one (same resolution as
+                // `observationSourceId` below and the MCP path), else the keyed source.
+                const summary = await storeWriteState.summarizeUnfinishedStore({
+                    userId,
+                    sourceId: interpretation.source_id ?? interpretationSourceId ?? existingSource.id,
+                    entities: entities,
+                });
+                const incompleteErr = new Error(`ERR_STORE_WRITE_INCOMPLETE: idempotency_key "${idempotencyKey}" belongs to a store ` +
+                    `that did not finish writing (${summary.entities_written} of ` +
+                    `${summary.entities_requested} entities have an observation). It cannot be resumed ` +
+                    "under the same key because the request carries an interpretation.");
+                incompleteErr.code = "ERR_STORE_WRITE_INCOMPLETE";
+                incompleteErr.hint = storeWriteState.incompleteStoreHint(summary);
+                incompleteErr.details = { ...summary };
+                throw incompleteErr;
+            }
+            resumeIncompleteWrite = true;
+        }
+    }
+    if (existingSource && !resumeIncompleteWrite) {
         const { listObservationsForSource } = await import("./services/observation_storage.js");
         const existingObs = await listObservationsForSource(existingSource.id, userId);
         // Issue #1860 (mirrors the #1840 MCP-path fix in src/server.ts): on a
@@ -6598,24 +6578,39 @@ export async function storeStructuredForApi(params) {
             return entry?.schema_definition ?? null;
         });
     }
+    const { preflightStructuredStoreOwnership } = await import("./services/store_ownership_admission.js");
+    if (commit)
+        await preflightStructuredStoreOwnership(params);
     const { createObservation } = await import("./services/observation_storage.js");
     const jsonContent = incomingJsonContent;
     const filenameForStorage = originalFilename?.trim() || undefined;
-    const storageResult = await storeRawContent({
-        userId,
-        fileBuffer: Buffer.from(jsonContent, "utf-8"),
-        mimeType: "application/json",
-        originalFilename: filenameForStorage,
-        idempotencyKey,
-        provenance: {
-            upload_method: "api_store",
-            client: "api",
-            source_priority: sourcePriority,
-        },
-    });
+    // Plan mode (`commit: false`, CLI `--plan`/`--dry-run`) must be genuinely
+    // side-effect-free: no `sources` row, no raw-storage upload. storeRawContent
+    // persists both, so it must not run at all when not committing. Everything
+    // storageResult feeds below — resolvedInterpretationSourceId,
+    // observationSourceId, and interpretationId — is consumed exclusively
+    // inside `if (commit)` blocks further down (observation creation, event
+    // emission, auto-linking), so a null placeholder here is never written to
+    // a row; pass 1 entity resolution (resolveEntityWithTrace, below) takes no
+    // source id at all.
+    const storageResult = commit
+        ? await storeRawContent({
+            userId,
+            fileBuffer: Buffer.from(jsonContent, "utf-8"),
+            mimeType: "application/json",
+            originalFilename: filenameForStorage,
+            idempotencyKey,
+            provenance: {
+                upload_method: "api_store",
+                client: "api",
+                source_priority: sourcePriority,
+                ...(await import("./services/store_write_state.js")).inProgressStoreWriteProvenance(),
+            },
+        })
+        : null;
     const resolvedInterpretationSourceId = interpretation?.source_id ??
         interpretationSourceId ??
-        (interpretation?.source_ref === "structured" ? storageResult.sourceId : undefined);
+        (interpretation?.source_ref === "structured" ? storageResult?.sourceId : undefined);
     const interpretationId = commit && interpretation && resolvedInterpretationSourceId
         ? await createInterpretationRunForSource({
             userId,
@@ -6623,7 +6618,7 @@ export async function storeStructuredForApi(params) {
             interpretationConfig: interpretation.interpretation_config,
         })
         : null;
-    const observationSourceId = resolvedInterpretationSourceId ?? storageResult.sourceId;
+    const observationSourceId = resolvedInterpretationSourceId ?? storageResult?.sourceId;
     // v0.5.1: structured guidance for the v0.5.0 breaking change where callers
     // nested fields under `attributes`. If resolution failed and the only
     // observed top-level keys are `attributes` (plus optionally `entity_type`),
@@ -6644,6 +6639,11 @@ export async function storeStructuredForApi(params) {
     }
     const resolved = [];
     const issues = [];
+    // One fresh set per resolution pass when resuming (#2144): an entity an
+    // earlier payload of this request already resolved to is a collision between
+    // two payloads, not this write's own row, so a later payload landing on it is
+    // judged by the ordinary strict / collision rules.
+    const resumeClaimedEntityIds = resumeIncompleteWrite ? new Set() : undefined;
     for (let observation_index = 0; observation_index < entities.length; observation_index++) {
         const entityData = entities[observation_index];
         let entity_type = entityData.entity_type;
@@ -6690,7 +6690,12 @@ export async function storeStructuredForApi(params) {
                 commit,
                 strict: effectiveStrict,
                 targetId,
+                // Resuming this key's own interrupted write: entity rows it created
+                // are not merge targets (#2144).
+                resumeSourceId: resumeIncompleteWrite ? existingSource?.id : undefined,
+                resumeClaimedEntityIds,
             });
+            resumeClaimedEntityIds?.add(result.entityId);
             resolved.push({
                 observation_index,
                 entity_type,
@@ -6947,6 +6952,15 @@ export async function storeStructuredForApi(params) {
         let observation_id = null;
         let snapshotAfter = null;
         if (commit) {
+            // Invariant: storageResult is only ever null when `commit` is false
+            // (plan mode skips storeRawContent entirely — see above). Reaching this
+            // branch with a null observationSourceId would mean an observation is
+            // about to be written with no traceable source, which is worse than
+            // failing loudly here.
+            if (observationSourceId === undefined) {
+                throw new Error("Internal invariant violated: commit=true but no source id was resolved " +
+                    "(storeRawContent should have run under commit mode).");
+            }
             const { data: priorSnapRow } = await db
                 .from("entity_snapshots")
                 .select("snapshot")
@@ -6970,6 +6984,7 @@ export async function storeStructuredForApi(params) {
                 user_id: userId,
                 identity_basis: r.trace.identity_basis,
                 identity_rule: r.trace.identity_rule,
+                data_origin: dataOrigins?.[r.observation_index],
             });
             observation_id = obsData.id;
             try {
@@ -6986,7 +7001,7 @@ export async function storeStructuredForApi(params) {
             const obsRow = obsData;
             const emitTs = obsRow.observed_at ?? new Date().toISOString();
             const obsSourceLabel = observationSource === undefined || observationSource === null
-                ? "llm_summary"
+                ? DEFAULT_OBSERVATION_SOURCE
                 : String(observationSource);
             emitObservationCreated({
                 user_id: userId,
@@ -7154,6 +7169,14 @@ export async function storeStructuredForApi(params) {
             }
         }
     }
+    // Every observation (and the request's relationships) is written. Record
+    // that on the keyed source so a replay of this key knows the write finished
+    // (#2144). Before this point a replay resumes the write instead of reporting
+    // whatever happened to land.
+    if (commit && storageResult) {
+        const { markStoreWriteComplete } = await import("./services/store_write_state.js");
+        await markStoreWriteComplete(storageResult.sourceId, userId);
+    }
     // R3: aggregate non-fatal resolver warnings across the batch so callers
     // (agents, Inspector, CI) can audit identity quality without walking every
     // entity.trace. PII-free by construction — see ResolverWarning shape.
@@ -7385,6 +7408,20 @@ export async function storeStructuredForApi(params) {
             }
         }
     }
+    // #2241: OBSERVATION_SOURCE_OMITTED — the request did not say what kind of
+    // write this was, so every observation was stored as `unspecified`. Judged
+    // on the raw request value (an explicit `unspecified` does not warn) and
+    // emitted once per request, because observation_source is request-scoped.
+    {
+        const { buildObservationSourceOmittedWarning } = await import("./services/observation_source_warning.js");
+        const firstStored = [...resolved].sort((a, b) => a.observation_index - b.observation_index)[0];
+        const obsSourceWarn = buildObservationSourceOmittedWarning({
+            rawObservationSource: observationSource,
+            firstStored,
+        });
+        if (obsSourceWarn)
+            schemaStoreWarnings.push(obsSourceWarn);
+    }
     // #1963: surface auto-link edge retractions on the store response so a
     // retraction — and especially a retraction *failure* — is never silent. A
     // failure means a stale reference-field edge may still be live despite the
@@ -7511,7 +7548,7 @@ export async function storeStructuredForApi(params) {
         success: true,
         replayed: false,
         commit,
-        source_id: commit ? storageResult.sourceId : null,
+        source_id: commit && storageResult ? storageResult.sourceId : null,
         ...(interpretationId
             ? { interpretation_id: interpretationId, interpretation_source_id: observationSourceId }
             : {}),
@@ -7546,14 +7583,42 @@ export async function storeStructuredForApi(params) {
 // target here today. An instance with enforcement: "enforced" still accepts
 // arbitrary raw file content through this path. See the "Known scope
 // boundary" section in src/services/instance_policy.ts's docblock.
-async function storeUnstructuredForApi(params) {
-    const { fileContent, fileBuffer, filePath, mimeType, idempotencyKey, originalFilename, sourceType, userId, storageMode = "inline", } = params;
+export async function storeUnstructuredForApi(params) {
+    const { fileContent, fileBuffer, filePath, mimeType, idempotencyKey, originalFilename, sourceType, userId, storageMode = "inline", commit = true, } = params;
     // decodeFileContent rejects non-base64 instead of letting Node discard the
     // invalid characters and store corrupted bytes (#2325).
     const resolvedFileBuffer = fileBuffer ?? (fileContent !== undefined ? decodeFileContent(fileContent) : undefined);
     if (!resolvedFileBuffer && storageMode !== "reference") {
         throw new Error("fileContent or fileBuffer is required for inline storage");
     }
+    if (!commit) {
+        // Nothing to persist in plan mode: no bytes uploaded, no `sources` row,
+        // no reference row. `content_hash` is still safe (and useful) to report
+        // since it's a pure function of the caller's own bytes/path, computed
+        // without touching storage or the database.
+        if (storageMode === "reference") {
+            if (!filePath) {
+                throw new Error("filePath is required for reference storage mode");
+            }
+            return {
+                commit: false,
+                source_id: null,
+                storage_mode: "reference",
+                reference_path: filePath,
+                mime_type: mimeType,
+            };
+        }
+        const { computeContentHash } = await import("./services/raw_storage.js");
+        return {
+            commit: false,
+            source_id: null,
+            content_hash: computeContentHash(resolvedFileBuffer),
+            file_size: resolvedFileBuffer.length,
+            deduplicated: false,
+            entities_created: 0,
+            observations_created: 0,
+        };
+    }
     if (storageMode === "reference") {
         if (!filePath) {
             throw new Error("filePath is required for reference storage mode");
@@ -7613,12 +7678,41 @@ async function handleStorePost(req, res) {
         });
         return sendStoreValidationError(res, parsed.error.issues);
     }
+    let storeDataOrigins;
+    // #2242: peel the reserved per-entity `data_origin` key off every entity and
+    // resolve each entity's effective origin (entity → request → none) before
+    // anything else reads the entities, so no downstream path sees it as a field.
+    if (parsed.data.entities?.length) {
+        const { splitEntityDataOrigins } = await import("./services/provenance_data_origin.js");
+        const split = splitEntityDataOrigins(parsed.data.entities, parsed.data.data_origin);
+        parsed.data.entities = split.entities;
+        storeDataOrigins = split.origins;
+    }
     try {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
+        const { assertConditionalStoreRequest } = await import("./services/store_condition_request.js");
+        assertConditionalStoreRequest(parsed.data);
         const hasEntities = Boolean(parsed.data.entities?.length);
         const hasFileContent = Boolean(parsed.data.file_content && parsed.data.mime_type);
         const hasFilePath = Boolean(parsed.data.file_path);
         const hasUnstructured = hasFileContent || hasFilePath;
+        if (hasEntities && hasUnstructured && parsed.data.commit !== false) {
+            const { claimCombinedStoreKeys } = await import("./services/store_combined_admission.js");
+            await claimCombinedStoreKeys({
+                userId,
+                entities: parsed.data.entities,
+                sourcePriority: parsed.data.source_priority,
+                idempotencyKey: parsed.data.idempotency_key,
+                relationships: parsed.data.relationships,
+                interpretation: parsed.data.interpretation,
+                sourcePeerId: parsed.data.source_peer_id,
+                strict: parsed.data.strict,
+            }, {
+                key: parsed.data.file_idempotency_key,
+                content: parsed.data.file_content,
+                filePath: parsed.data.file_path,
+            });
+        }
         let structuredResult;
         let unstructuredResult;
         const storeUnstructuredFromRequest = async () => {
@@ -7679,6 +7773,7 @@ async function handleStorePost(req, res) {
                 originalFilename,
                 sourceType: parsed.data.source_type,
                 storageMode: parsed.data.source_storage,
+                commit: parsed.data.commit,
             });
         };
         if (hasUnstructured && parsed.data.interpretation?.source_ref === "unstructured") {
@@ -7695,6 +7790,7 @@ async function handleStorePost(req, res) {
             const doStore = () => storeStructuredForApi({
                 userId,
                 entities: parsed.data.entities,
+                expectedEntityAbsent: parsed.data.expected_entity_absent,
                 sourcePriority: parsed.data.source_priority ?? 100,
                 observationSource: parsed.data.observation_source,
                 sourcePeerId: parsed.data.source_peer_id,
@@ -7709,6 +7805,7 @@ async function handleStorePost(req, res) {
                     : undefined,
                 commit: parsed.data.commit,
                 strict: parsed.data.strict,
+                dataOrigins: storeDataOrigins,
             });
             // A request body can only claim an external actor; verified tiers are
             // assigned by server-side verification paths, never taken from input.
@@ -7753,6 +7850,15 @@ async function handleStorePost(req, res) {
             return sendError(res, 400, error.code, error.message, error.details);
         }
         const errCode = error && typeof error === "object" ? error.code : undefined;
+        const { StoreConditionError } = await import("./services/store_condition_keys.js");
+        if (error instanceof StoreConditionError) {
+            const status = error.code === "VALIDATION_ERROR"
+                ? 400
+                : error.code === "STORE_RECEIPT_UNCERTAIN" || error.code === "STORE_CONDITIONAL_FAILED"
+                    ? 503
+                    : 409;
+            return res.status(status).json({ error: error.toErrorEnvelope() });
+        }
         if (isGrantPinConflict(error)) {
             logWarn("AgentGrantPinConflict:store", req, { code: error.code });
             return sendError(res, 409, error.code, error.message, { field: error.field });
@@ -7779,6 +7885,16 @@ async function handleStorePost(req, res) {
             logWarn("IdempotencyCollision:store", req, { message });
             return sendError(res, 409, "ERR_IDEMPOTENCY_COLLISION", message);
         }
+        if (error && typeof error === "object" && errCode === "ERR_STORE_WRITE_INCOMPLETE") {
+            const message = error instanceof Error ? error.message : String(error);
+            const hint = error.hint;
+            logWarn("StoreWriteIncomplete:store", req, { message });
+            const incompleteDetails = error.details;
+            return sendError(res, 409, "ERR_STORE_WRITE_INCOMPLETE", message, {
+                ...(hint ? { hint } : {}),
+                ...(incompleteDetails ?? {}),
+            });
+        }
         if (error && typeof error === "object" && errCode === "ERR_STORE_POLICY_DENIED") {
             const err = error;
             // Log counts and reason codes only. The denied entities' field values are
@@ -7867,6 +7983,16 @@ async function handleStorePost(req, res) {
                 hint: error.hint,
             });
         }
+        // A capability refusal is the caller's authorization, not a server fault:
+        // 403 with the same envelope `handleApiError` gives every other route.
+        // Falling through made a denied edge (or entity type) read as a retryable
+        // 500 DB_QUERY_FAILED.
+        if (error instanceof AgentCapabilityError) {
+            logWarn("AgentCapabilityRejection:store", req, error.toErrorEnvelope());
+            return res
+                .status(403)
+                .json(buildErrorEnvelope(error.code, error.message, error.toErrorEnvelope()));
+        }
         logError("APIError:store", req, error);
         const message = error instanceof Error ? error.message : "Failed to store payload";
         return sendError(res, 500, "DB_QUERY_FAILED", message);
@@ -8318,7 +8444,7 @@ app.post("/get_entity_snapshot", async (req, res) => {
         });
         return sendValidationError(res, parsed.error.issues);
     }
-    const { entity_id, at, at_ingested } = parsed.data;
+    const { entity_id, at, at_ingested, include_cleared_fields } = parsed.data;
     let userId;
     try {
         userId = await getAuthenticatedUserId(req);
@@ -8330,22 +8456,42 @@ app.post("/get_entity_snapshot", async (req, res) => {
     // helper so the offline path honours them with the same semantics as the MCP
     // path in server.ts. Without cutoffs, fall through to the fast materialized
     // entity_snapshots table read.
-    if (at || at_ingested) {
+    if (at || at_ingested || include_cleared_fields) {
         try {
-            const result = await computeEntitySnapshotAtTime(entity_id, userId, at, at_ingested);
+            const result = await computeEntitySnapshotAtTime(entity_id, userId, at, at_ingested, {
+                includeClearedFields: include_cleared_fields,
+            });
+            if (include_cleared_fields && !at && !at_ingested) {
+                const { isEntityDeleted } = await import("./services/deletion.js");
+                if (result && (await isEntityDeleted(result.entity_id, userId)))
+                    return sendError(res, 404, "RESOURCE_NOT_FOUND", "Entity not found");
+            }
             if (result === null) {
                 return sendError(res, 404, "RESOURCE_NOT_FOUND", "Entity not found");
             }
             logDebug("Success:get_entity_snapshot:at_time", req, { entity_id, at, at_ingested });
-            return res.json(result);
+            return res.json(await withSnapshotDataOrigins(result, userId));
         }
         catch (err) {
             logError("Error:get_entity_snapshot:at_time", req, err);
             return sendError(res, 500, "DB_QUERY_FAILED", err.message);
         }
     }
-    // Fast path: no cutoffs — read the materialized snapshot directly, scoped to
-    // the authenticated user.
+    // Materialization is derived state. Validate owned current authority before
+    // serving its row, including restrictive corruption acquisition failures.
+    try {
+        const { isEntityDeleted } = await import("./services/deletion.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)))
+            return sendError(res, 404, "RESOURCE_NOT_FOUND", "Entity not found");
+    }
+    catch (err) {
+        logError("Error:get_entity_snapshot:authority", req, err);
+        return sendError(res, 500, "DB_QUERY_FAILED", "Entity lifecycle authority acquisition failed");
+    }
+    // No cutoffs: return the existing owned materialized factual snapshot.
     const { data, error } = await db
         .from("entity_snapshots")
         .select("*")
@@ -8360,8 +8506,23 @@ app.post("/get_entity_snapshot", async (req, res) => {
         return sendError(res, 500, "DB_QUERY_FAILED", error.message);
     }
     logDebug("Success:get_entity_snapshot", req, { entity_id });
-    return res.json(data);
+    return res.json(await withSnapshotDataOrigins(data, userId));
 });
+/**
+ * #2242: attach `data_origins` (observation_id → caller-claimed origin) for the
+ * observations a snapshot's field provenance cites. The key is omitted when no
+ * cited observation carries an origin, so pre-#2242 responses are unchanged.
+ * Mirrors MCP `retrieve_entity_snapshot`.
+ */
+async function withSnapshotDataOrigins(snapshot, userId) {
+    if (!snapshot || typeof snapshot !== "object")
+        return snapshot;
+    const { collectSnapshotDataOrigins } = await import("./services/provenance_data_origin.js");
+    const dataOrigins = await collectSnapshotDataOrigins(snapshot.provenance, userId);
+    if (Object.keys(dataOrigins).length === 0)
+        return snapshot;
+    return { ...snapshot, data_origins: dataOrigins };
+}
 // List observations for entity
 app.post("/list_observations", async (req, res) => {
     const parsed = ListObservationsRequestSchema.safeParse(req.body);
@@ -8505,6 +8666,14 @@ app.post("/create_relationship", async (req, res) => {
                     "same store call referenced by index, then link it.",
             });
         }
+        // Relationship-type + endpoint-type capability refusal, raised inside
+        // relationshipsService.createRelationship (the shared edge-write gate).
+        if (error instanceof AgentCapabilityError) {
+            logWarn("AgentCapabilityRejection:create_relationship", req, error.toErrorEnvelope());
+            return res
+                .status(403)
+                .json(buildErrorEnvelope(error.code, error.message, error.toErrorEnvelope()));
+        }
         logError("RelationshipCreationError:create_relationship", req, error);
         return sendError(res, 500, "DB_QUERY_FAILED", error instanceof Error ? error.message : "Failed to create relationship");
     }
@@ -8540,11 +8709,19 @@ app.post("/create_relationships", async (req, res) => {
                 });
             }
             catch (error) {
-                errors.push({
+                const item = {
                     index,
                     relationship,
                     error: error instanceof Error ? error.message : String(error),
-                });
+                };
+                // Batch semantics stay HTTP 200 so successful siblings are retained,
+                // but a capability denial must keep the same machine-actionable repair
+                // contract as the single-item endpoint. Agents rely on code/op/hint;
+                // reducing this to error.message turns a recoverable refusal opaque.
+                if (error instanceof AgentCapabilityError) {
+                    Object.assign(item, error.toErrorEnvelope());
+                }
+                errors.push(item);
             }
         }
         logDebug("Success:create_relationships", req, {
@@ -9350,6 +9527,15 @@ app.post("/delete_relationship", async (req, res) => {
                     "one of the returned types.",
             });
         }
+        // Tombstoning a live edge changes the same relationship state that the
+        // create/restore capability governs. Enforce the admitted grant after the
+        // discovery guard (so a missing edge stays not-found) and before writing
+        // the deletion observation.
+        const { enforceCurrentAgentRelationshipWrites } = await import("./services/relationship_write_capability.js");
+        await enforceCurrentAgentRelationshipWrites({
+            userId,
+            relationships: [{ relationship_type, source_entity_id, target_entity_id }],
+        });
         const { softDeleteRelationship } = await import("./services/deletion.js");
         // Construct relationship key
         const relationshipKey = `${relationship_type}:${source_entity_id}:${target_entity_id}`;
@@ -9910,6 +10096,27 @@ app.post("/register_schema", async (req, res) => {
     }
 });
 // POST /correct - Create correction observation to override field value
+app.post("/corrections/transaction", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.body?.user_id);
+        const { applyCorrectionTransaction, CorrectionTransactionError } = await import("./services/correction_transaction.js");
+        try {
+            return res.json(await applyCorrectionTransaction({ ...req.body, user_id: userId }));
+        }
+        catch (error) {
+            if (error instanceof CorrectionTransactionError) {
+                const status = error.code === "VALIDATION_ERROR" ? 400 : error.code === "RESOURCE_NOT_FOUND" ? 404 : 409;
+                return sendError(res, status, error.code, error.message, {
+                    hint: "Read current entity snapshots and resolve conflicts; retry an uncertain request with exactly the original payload and key.",
+                });
+            }
+            throw error;
+        }
+    }
+    catch (error) {
+        return handleApiError(req, res, error, "Correction transaction failed and was rolled back.");
+    }
+});
 app.post("/correct", async (req, res) => {
     const parsed = CorrectEntityRequestSchema.safeParse(req.body);
     if (!parsed.success) {
@@ -9920,7 +10127,7 @@ app.post("/correct", async (req, res) => {
     }
     try {
         const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
-        const { entity_id, entity_type, field, value, idempotency_key } = parsed.data;
+        const { entity_id, entity_type, field, value, idempotency_key, expected_version, overwrite } = parsed.data;
         const correctCtx = contextFromAgentIdentity(getCurrentAgentIdentity());
         if (correctCtx) {
             enforceAgentCapability("correct", [entity_type], correctCtx);
@@ -9937,9 +10144,9 @@ app.post("/correct", async (req, res) => {
         // propagates (it is NOT coerced to "declared field" — product principle
         // 10.2); a missing schema throws CorrectionSchemaNotFoundError, surfaced as
         // ERR_NO_SCHEMA_FOR_ENTITY_TYPE. Both reach the catch below.
-        const { createCorrection, resolveCorrectionSchema, buildCorrectionResponse } = await import("./services/correction.js");
+        const { createCorrection, createCorrectionWithVersionPrecondition, resolveCorrectionSchema, buildCorrectionResponse, } = await import("./services/correction.js");
         const { schemaVersion: correctionSchemaVersion, isUnknownField } = await resolveCorrectionSchema(entity_type, field, userId);
-        const result = await createCorrection({
+        const correctionParams = {
             entity_id,
             entity_type,
             field,
@@ -9947,7 +10154,14 @@ app.post("/correct", async (req, res) => {
             schema_version: correctionSchemaVersion,
             user_id: userId,
             idempotency_key,
-        });
+        };
+        const result = typeof expected_version === "string"
+            ? await createCorrectionWithVersionPrecondition({
+                ...correctionParams,
+                expected_version,
+                overwrite,
+            })
+            : await createCorrection(correctionParams);
         if (isUnknownField) {
             try {
                 const { storeFragment } = await import("./services/raw_fragments.js");
@@ -9978,8 +10192,10 @@ app.post("/correct", async (req, res) => {
                 entity_id,
                 entity_type,
                 field,
-                value,
+                value: result.value,
                 isUnknownField,
+                replayed: result.replayed,
+                entity_version: result.entity_version,
             }),
         });
     }
@@ -9988,13 +10204,43 @@ app.post("/correct", async (req, res) => {
         // (ERR_NO_SCHEMA_FOR_ENTITY_TYPE), not an internal failure. A schema-registry
         // IO failure is NOT swallowed here — it falls through to the generic 500
         // handler below instead of being coerced into a "declared field" outcome.
-        const { CorrectionSchemaNotFoundError } = await import("./services/correction.js");
+        const { CorrectionSchemaNotFoundError, CorrectionEntityTypeMismatchError, CorrectionIdempotencyMismatchError, FieldVersionConflictError, } = await import("./services/correction.js");
         if (error instanceof CorrectionSchemaNotFoundError) {
             logWarn("ValidationError:correct", req, { code: error.code });
             return res
                 .status(400)
                 .json(buildErrorEnvelope(error.code, error.message, { entity_type: error.entityType }));
         }
+        if (error instanceof CorrectionEntityTypeMismatchError) {
+            logWarn("ValidationError:correct", req, { code: error.code });
+            return res.status(400).json(buildErrorEnvelope(error.code, error.message, {
+                entity_id: error.entityId,
+                supplied_entity_type: error.suppliedEntityType,
+                stored_entity_type: error.storedEntityType,
+            }));
+        }
+        if (error instanceof CorrectionIdempotencyMismatchError) {
+            return res.status(400).json(buildErrorEnvelope(error.code, error.message, {
+                idempotency_key: error.idempotencyKey,
+                hint: "Use a new idempotency_key for a distinct correction payload.",
+            }));
+        }
+        // Waxwing ADR: stale expected_version on /correct. Nothing was written —
+        // the precondition check runs before createCorrection. Flat standard
+        // envelope (error_code/message/details), matching the OpenAPI contract
+        // and the sibling ERR_ARRAY_ITEM_CONFLICT 409 on /patch_array_item — NOT
+        // wrapped under an `error` key (that shape is reserved for envelopes
+        // like entity_owner_conflict that predate the standard envelope).
+        if (error instanceof FieldVersionConflictError) {
+            logWarn("VersionConflict:correct", req, { code: error.code, field: error.field });
+            return res.status(409).json(buildErrorEnvelope(error.code, error.message, {
+                entity_id: error.entityId,
+                field: error.field,
+                stored_version: error.storedVersion,
+                expected_version: error.expectedVersion,
+                hint: "Re-read the entity snapshot and retry with its current entity_version as expected_version.",
+            }));
+        }
         // Instance store-policy denial (#1975) — same envelope as /store, so a
         // caller handling one handles both.
         const { StorePolicyDeniedError } = await import("./services/instance_policy.js");
@@ -10008,6 +10254,131 @@ app.post("/correct", async (req, res) => {
         return handleApiError(req, res, error, "Failed to create correction", "DB_QUERY_FAILED", "APIError:correct");
     }
 });
+// POST /patch_array_item - Atomically patch one item of a structured array
+// field by key (Waxwing ADR, ent_4b41bb83a4faf4428a73bfc8). Sibling of
+// /correct; see openapi.yaml for the full contract.
+app.post("/patch_array_item", writeRateLimit, async (req, res) => {
+    const parsed = PatchArrayItemRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+        logWarn("ValidationError:patch_array_item", req, { issues: parsed.error.issues });
+        return sendValidationError(res, parsed.error.issues);
+    }
+    try {
+        const userId = await getAuthenticatedUserId(req, parsed.data.user_id);
+        const { entity_id, entity_type, field, key_field, key_value, item, expected_item_version, expected_item_absent, } = parsed.data;
+        // Resolve the authoritative entity type under the authenticated user
+        // before capability/protected-type checks. The request's entity_type is a
+        // consistency assertion, never an authorization input.
+        const { loadArrayItemPatchTarget } = await import("./services/array_item_patch.js");
+        const target = await loadArrayItemPatchTarget({
+            entityId: entity_id,
+            userId,
+            suppliedEntityType: entity_type,
+        });
+        const correctCtx = contextFromAgentIdentity(getCurrentAgentIdentity());
+        if (correctCtx) {
+            enforceAgentCapability("correct", [target.entity_type], correctCtx);
+        }
+        assertCanWriteProtectedBatch({
+            entity_types: [target.entity_type],
+            op: "correct",
+            identity: getCurrentAgentIdentity(),
+            admission: getCurrentAAuthAdmission(),
+        });
+        const { patchArrayItem } = await import("./services/array_item_patch.js");
+        const result = await patchArrayItem({
+            entity_id,
+            entity_type,
+            user_id: userId,
+            field,
+            key_field,
+            key_value,
+            item,
+            expected_item_version,
+            expected_item_absent,
+            idempotency_key: parsed.data.idempotency_key,
+        });
+        if (result.status === "conflict") {
+            logWarn("VersionConflict:patch_array_item", req, { entity_id, field, key_field });
+            return res.status(409).json(buildErrorEnvelope("ERR_ARRAY_ITEM_CONFLICT", `Stale expected_item_version for ${entity_type}.${field}[${key_field}=${JSON.stringify(key_value)}]`, {
+                entity_id,
+                entity_type,
+                field,
+                key_field,
+                key_value,
+                current_item: result.conflict?.current_item ?? null,
+                current_item_version: result.conflict?.current_item_version ?? null,
+                expected_item_version: result.conflict?.expected_item_version ?? null,
+                expected_item_absent: expected_item_absent ?? false,
+                hint: "Re-apply the intended change to current_item and retry with current_item_version as expected_item_version.",
+            }));
+        }
+        return res.json({
+            success: true,
+            entity_id: result.entity_id,
+            entity_type: result.entity_type,
+            field: result.field,
+            key_field: result.key_field,
+            key_value: result.key_value,
+            observation_id: result.observation_id,
+            item: result.item,
+            item_version: result.item_version,
+            array_length: result.array_length,
+            snapshot: result.snapshot,
+            replayed: result.replayed ?? false,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("Entity not found")) {
+            return sendError(res, 404, "RESOURCE_NOT_FOUND", error.message);
+        }
+        const { CorrectionIdempotencyMismatchError } = await import("./services/correction.js");
+        if (error instanceof CorrectionIdempotencyMismatchError) {
+            return res.status(400).json(buildErrorEnvelope(error.code, error.message, {
+                idempotency_key: error.idempotencyKey,
+                hint: "Use a new idempotency_key for a distinct patch payload.",
+            }));
+        }
+        if (error instanceof EntityOwnerConflictError) {
+            return res.status(409).json({ error: error.toErrorEnvelope() });
+        }
+        {
+            const { ArrayItemKeyFieldMismatchError, ArrayItemPolicyRequiredError, ArrayItemEntityTypeMismatchError, } = await import("./services/array_item_patch.js");
+            if (error instanceof ArrayItemKeyFieldMismatchError ||
+                error instanceof ArrayItemPolicyRequiredError ||
+                error instanceof ArrayItemEntityTypeMismatchError) {
+                logWarn("KeyFieldMismatch:patch_array_item", req, {
+                    code: error.code,
+                });
+                return res
+                    .status(error.statusCode)
+                    .json(buildErrorEnvelope(error.code, error.message, error.toErrorEnvelope()));
+            }
+        }
+        // Instance store-policy denial (#1975) — patchArrayItem() writes through
+        // createCorrection exactly like /correct, so it can be refused by the
+        // same instance-level write policy. Same envelope shape as /correct and
+        // /store, so a caller handling one handles all three.
+        const { StorePolicyDeniedError } = await import("./services/instance_policy.js");
+        if (error instanceof StorePolicyDeniedError) {
+            logWarn("StorePolicyDenied:patch_array_item", req, {
+                denied_count: error.denied.length,
+                reason_codes: [...new Set(error.denied.map((d) => d.reason_code))].sort(),
+            });
+            return res.status(400).json({ error: error.toErrorEnvelope() });
+        }
+        if (error instanceof StorePolicyUnavailableError) {
+            logError("StorePolicyUnavailable:patch_array_item", req, error, {
+                code: error.code,
+                cause: error.cause_message,
+            });
+            return res
+                .status(503)
+                .json(buildErrorEnvelope(error.code, error.message, error.toErrorEnvelope()));
+        }
+        return handleApiError(req, res, error, "Failed to patch array item", "DB_QUERY_FAILED", "APIError:patch_array_item");
+    }
+});
 // POST /get_authenticated_user - Get authenticated user ID
 // FU-2026-05-003: GET /conversations/:conversation_id/turn-index — Inspector
 // per-turn anchor sections and turn timeline sidebar.
@@ -10823,14 +11194,12 @@ function assertRouteTableIsReachable() {
  * loopback while the socket was actually open on all interfaces).
  */
 export function resolveHttpBindHost(env = process.env) {
-    const raw = (env.NEOTOMA_HTTP_HOST || "").trim();
-    return raw.length > 0 ? raw : "127.0.0.1";
-}
-/** True when the given bind host resolves to a loopback-only address. */
-export function isLoopbackHost(host) {
-    const normalized = host.trim().toLowerCase();
-    return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";
+    return resolveBindHostFromEnv("NEOTOMA_HTTP_HOST", env);
 }
+// Re-exported so existing importers of `isLoopbackHost` from this module keep
+// working; the implementation lives in `./shared/bind_host.ts`, which the
+// standalone MCP WebSocket bridge also uses.
+export { isLoopbackHost };
 /**
  * Try to bind on a port/host; resolves with server and port, or rejects on
  * error (e.g. EADDRINUSE).