Skip to content

Let a plugin require cluster-serialized writes: export getLockScope - #60

Merged
kriszyp merged 6 commits into
mainfrom
feat/export-lock-scope
Nov 20, 2026
Merged

kriszyp merged 6 commits into
mainfrom
feat/export-lock-scope

Conversation

@kriszyp

@kriszyp kriszyp commented Nov 20, 2026 •

Copy link
Copy Markdown
Member
Dawson bolts a latch gauge to the packing bench; the raccoon keeps his topic signs boxed while it reads each camp alone.

⊙ Problem

Sinks run only on the node that takes the write. At the default lockScope: node, two nodes can rescope one memory at once, and summary-tree can keep serving its text in a partition it left. summary-tree's README requires lockScope: cluster but cannot check it: agent-memory exports no way to read the setting (HarperFast/summary-tree#3).

💡 Solution

  • getLockScope() returns the running plugin's 'node' or 'cluster', read live, or undefined while none runs (or it is 0.1.5 or earlier).
  • A plugin checks it at startup and refuses to start without cluster; the README shows how.
  • summary-tree can replace its README requirement with that check. It should keep its orphan sweep: even at cluster, lock recovery after a crash can let two writes commit.

🤔 Ship as 0.2.0, with the dated changelog heading?

The task asked for a minor bump, so merging this cuts 0.2.0, including other PRs' Unreleased entries. summary-tree's peer range >=0.1.5 <0.2.0 rejects 0.2.0, so it needs a release that raises its floor to use getLockScope. An additive 0.1.6 would avoid that.

🤔 Keep the LockScope type export?

It is the getter's return type, so TypeScript callers can name it. No caller imports the public type by name, and one review round asked to drop it. Kept.

⚖️ Alternatives

Rejected: replicated sink calls, Harper's record-lock flag, a registration option
  • Call sinks for writes replicated from other nodes, flagged as replicated: rejected.
    • A replicated write is already committed, so the call cannot share the memory's transaction. That breaks the sink contract.
    • At node, replication keeps the last write, so sinks would also see writes that lose. The race needs one order, not every write.
  • Read Harper's replication.recordLocks: having record locks on does not mean agent-memory takes them. lockScope defaults to node, and the harper-eye deployment runs that way.
  • A requires: 'cluster' option on registerMemorySink: a running 0.1.5 plugin would ignore it.

🤔 The README's in-sink check throws, aborting the write

A sink that throws aborts every memory write while the scope is wrong, which fails closed. A sink could instead skip the call and mark its derived state stale. The README warns against using only the sink check across apps.

🔧 Changes

✅ Verification

Unit 526, integration 83, summary-tree 14/14 against this build; one claim not testable here

Refs HarperFast/summary-tree#3

🤖 Generated by Claude Opus 5.5 (Anthropic); posted via @kriszyp.

Related PRs: none found
Complexity: medium

🤖 Generated with Claude Code

https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd

Deferred findings

Origin — the dispatch brief this PR was written from

Let agent-memory sinks rely on cluster lock scope: export lockScope, or call sinks for replicated writes

Dispatch: task proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a · queued by unknown · ran by claude/opus/high · worker kzyp-xps-1

Review-Coverage: authored=claude; ran=cursor-composer,codex,gemini,cursor-grok; late=cursor-grok:adjudicated; adjudicated=domain; declined=muse; rounds=6; full=2 @ 5408840

Review-Attention: read ~3m (decisions: sink-fail-closed, current-setting-vs-lock-taken, do-less-alternative, release-in-feature-pr) @ 5408840

kriszyp and others added 6 commits November 19, 2026 22:48
A sink runs only on the node that takes the write, so a plugin whose sink-derived
state needs writes to one memory serialized across nodes (summary-tree) could only
document lockScope: cluster. getLockScope() reports the running plugin's setting,
live, through the cross-app runtime; undefined while none runs in the domain or the
running plugin is 0.1.5 or earlier. Bumps the version to 0.2.0.

Refs HarperFast/summary-tree#3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd
Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
…orrect the docs

Routes through foreignRuntime so the version-skew warning applies, warns once when
the running plugin predates lockScope, documents that the sink check catches only a
downgrade, and guards withdraw in the README example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd
Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
…elog 0.2.0

The cluster lock-scope suite now runs memory-consumer beside the plugin, so a
distinct copy reads a non-default scope end to end. Drops the unused LockScope type
re-export.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd
Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
…; warn an unscoped copy

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd
Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
… correct the recovery advice

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd
Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
…eparate copies

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017xoBA8Da4eMNT6TffbkJNd
Dispatch-Task: proposal-kriszyp-xr-summary-tree-3-agent-memory-ckewn072js-906c4a
@kriszyp
kriszyp marked this pull request as ready for review November 20, 2026 15:19
@kriszyp
kriszyp merged commit 5fdfffe into main Nov 20, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant