Atomic MongoDB Session Coordinator for n8n

This self-hosted n8n community node provides the three atomic operations needed by a session coordinator:

• Acquire Turn obtains a conditional, session-scoped MongoDB lease, creates an idempotent TURN_RECEIVED event, allocates a monotonic turn sequence, and returns bounded state/context.
• Commit Turn validates the owner, live lease, and expected state version before applying a whitelisted canonical-state patch and idempotent event append.
• Release Turn deletes only the lease belonging to the supplied owner and turn.

It uses the MongoDB credential already stored in n8n. Its MongoDB driver is installed inside the package by the Community Nodes installer; the node never writes a connection string, password, or other credential value into a workflow or its output.

Version 0.1.2 deliberately defers loading the MongoDB driver until a workflow execution starts. This keeps Community Nodes class discovery independent of the driver and the host's n8n-workflow module resolution.

Important compatibility note

This package is for self-hosted n8n only. It deliberately uses the MongoDB driver for conditional findOneAndUpdate and references n8n's existing mongoDb credential type. Those two requirements make it ineligible for n8n Cloud verification. It can still be installed from the Community Nodes page of a self-hosted n8n instance.

Install

In the self-hosted n8n instance, open Settings → Community Nodes, select Install, and enter:

n8n-nodes-atomic-mongodb-session-coordinator

Restart n8n if the instance requests it. Add Atomic MongoDB Session Coordinator to a workflow and select the existing MongoDB credential (for this project: Xuan Thanh Mongo DB).

Workflow contract

All operations produce a success or error output. Expected storage failures use a structured, safe error envelope:

{
  "ok": false,
  "error": {
    "code": "lease_busy",
    "retryable": true,
    "safe_message": "This session is being processed. Please retry shortly."
  }
}

No error output contains a MongoDB URI, password, driver stack trace, or raw customer message.

Acquire Turn

Required fields: sessionId, ownerExecutionId, and a stable correlationId. The recommended owner value is ={{ $execution.id }}. deadlineAtMs is an epoch-millisecond deadline; zero uses a 55-second maximum from node start. The default lease is 65 seconds.

turnReceivedPayload is written only to the conversation-event collection. Do not put raw customer text in operational events.

On success the result contains the owned lease, turn_id, turn_seq, canonical state, bounded recent dialogue/events, the rolling summary, and the two most recently updated search runs.

Commit Turn

Pass the turnId, turnSeq, state version, and correlation ID returned by Acquire Turn. statePatch accepts only these top-level canonical state fields:

active_flow, pending_question, constraints, ranking_profile,
provenance, focus, last_result_set_id

Use { "noop": true } when no canonical state field changed. The node blocks unsafe update operators, unknown state fields, invalid JSON, impossible budget ranges, a stale lease, and an unexpected state version.

events must have stable event_id values. If Core omits STATE_COMMITTED, the node adds evt-<turnId>-state-committed with the committed state version. A retry of a completed commit returns the original state version and event IDs rather than applying the patch twice.

searchRunPatch is optional and must include query_fingerprint. summaryCandidate is optional and must contain a summary string of at most 2,000 characters.

When MongoDB transactions are available, state, summary/search updates, and events commit in one transaction. On a deployment without transactions, the node uses stable event IDs, a conditional state-version update, and an embedded commit receipt to preserve idempotency.

Release Turn

Pass sessionId, ownerExecutionId, turnId, and the deadline. The release filter includes all three ownership values, so a stale execution cannot unlock a newer turn.

Required collections and indexes

This node expects the v3 collections and indexes described in V3_MONGODB_BOOTSTRAP.md:

• agent_session_state_v3
• agent_conversation_events_v1
• agent_search_runs_v1
• agent_dialogue_summaries_v1
• agent_session_locks_v1
• agent_operational_events_v1

The unique session_id lease index and unique event_id index are mandatory for correctness. The node extends state/event/search/summary TTL fields by seven days and uses fourteen days for its operational events.

Safety boundaries

• The package cannot be used on n8n Cloud or submitted as a Cloud-verified node.
• It intentionally does not create collections or indexes.
• It does not edit v2 data or workflows.
• It has no HTTP endpoint and does not require a separate adapter service.
• Do not enable a production v3 ingress until the Session Coordinator's concurrency, expiry, idempotent-commit, and workflow tests pass.

Development checks

npm run build
npm test
npm run lint
npm pack --dry-run