Summary

• Problem: plugin dedupe consumers need an atomic state-store claim primitive instead of lookup-plus-register races.
• Why it matters: channel/tool plugins can avoid double-processing without owning SQLite details or crossing plugin isolation boundaries.
• What changed: added registerIfAbsent(key, value, opts?) to PluginStateKeyedStore, backed by a BEGIN IMMEDIATE SQLite transaction and INSERT OR IGNORE, with tests for duplicate, expiry, isolation, eviction, limits, and parallel claims.
• What did NOT change (scope boundary): did not touch BlueBubbles or Feishu consumers; existing register upsert semantics remain unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

N/A

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
• Target test or file: src/plugin-state/plugin-state-store.test.ts, src/plugin-state/plugin-state-store.runtime.test.ts, src/plugin-state/plugin-state-store.e2e.test.ts
• Scenario the test should lock in: first claim wins, live duplicate returns false without overwriting, expired row can be claimed again, plugin/namespace isolation, eviction/row caps, and practical same-process parallel claim safety.
• Why this is the smallest reliable guardrail: the state-store seam owns validation and SQLite transaction behavior directly.

User-visible / Behavior Changes

Bundled plugins can now call api.runtime.state.openKeyedStore(...).registerIfAbsent(...) for atomic keyed-store dedupe claims.

Diagram (if applicable)

Before:
plugin -> lookup(key) -> register(key) -> race window

After:
plugin -> registerIfAbsent(key, value) -> true if claimed, false if live row exists

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS local worktree
• Runtime/container: Node/OpenClaw repo scripts
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): isolated OpenClaw test state fixtures

Steps

1. Add registerIfAbsent to the state-store type and implementation.
2. Exercise first insert, duplicate, expired insert, isolation, limits, and runtime proxy tests.
3. Run focused format, tests, type checks, SDK API baseline check, and diff whitespace check.

Expected

• registerIfAbsent returns true only when the claim is inserted and false for an existing live key without mutating it.

Actual

• Focused tests and type checks passed.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What I personally verified:

• pnpm exec oxfmt --check --threads=1 src/plugin-state/plugin-state-store.ts src/plugin-state/plugin-state-store.sqlite.ts src/plugin-state/plugin-state-store.types.ts src/plugin-state/plugin-state-store.test.ts src/plugin-state/plugin-state-store.e2e.test.ts src/plugin-state/plugin-state-store.runtime.test.ts docs/plugins/sdk-runtime.md CHANGELOG.md
• pnpm test src/plugin-state/plugin-state-store.test.ts src/plugin-state/plugin-state-store.runtime.test.ts src/plugin-state/plugin-state-store.e2e.test.ts -- --reporter=verbose
• pnpm test src/plugin-state/plugin-state-store.permissions.test.ts -- --reporter=verbose
• pnpm tsgo:core
• pnpm tsgo:core:test
• pnpm plugin-sdk:api:check
• git diff --check

Edge cases checked:

• Duplicate live key does not overwrite value, createdAt, or TTL.
• Expired key can be inserted again.
• Plugin and namespace isolation remain intact.
• Namespace eviction and per-plugin row cap behavior remain intact.
• Parallel same-process claim attempts produce one winner.

What I did not verify:

• Full pnpm check:changed/full suite; this PR used targeted local proof for the touched state-store seam.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: claim logic could diverge from existing register validation/limits.
  • Mitigation: shared register parameter preparation plus direct state-store tests for validation-adjacent behavior, isolation, TTL, eviction, row cap, and runtime exposure.