docs(skills): document markDirty in swamp-extension-datastore#1226
Merged
docs(skills): document markDirty in swamp-extension-datastore#1226
Conversation
Pick up the markDirty() addition from #1225 in the skill that guides authors building custom datastore providers. api.md now describes the full three-method interface and when markDirty is load-bearing versus when a no-op is correct; examples.md's sync service returns a no-op markDirty with a comment pointing at the fast-path pattern in design/datastores.md. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
There was a problem hiding this comment.
Code Review
Docs-only PR that adds markDirty() documentation to the swamp-extension-datastore skill references, keeping guidance for extension authors in sync with the core interface change from #1225.
Blocking Issues
None.
Suggestions
- Minor signature discrepancy: The documented interface shows
markDirty(): Promise<void>while the actualDatastoreSyncServiceinsrc/domain/datastore/datastore_sync_service.ts:61declaresmarkDirty(options?: DatastoreSyncOptions): Promise<void>. Theoptionsparam (carryingAbortSignal) is omitted from the docs. This is consistent with howpullChangedandpushChangedare already simplified in the same interface block (they also omitoptions?and thenumber | voidreturn type), so this appears to be a deliberate choice to keep extension-author guidance simple. Worth noting but not blocking since the pattern is already established.
Looks good — accurate description of the markDirty contract, consistent with existing doc style, and the no-op example in examples.md correctly demonstrates the unconditional-walk case.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Pick up the `markDirty()` addition from #1225 in the skill that guides
authors building custom datastore providers.
plus a section describing when it's load-bearing (fast-path implementations
that cache a clean/dirty watermark) versus when a no-op is correct (sync
services that unconditionally walk the cache).
no-op `markDirty` with a comment pointing at the fast-path pattern in
`design/datastores.md`.
No code changes, docs only — keeps guidance for extension authors in
lock-step with the core interface change that already shipped.
Test Plan
🤖 Generated with Claude Code