Lab #2861: Conformance: behavioural round-trip suite for DatastoreSyncService in packages/testing

Background (read this first)

swamp is about to rework its datastore layer. The design proposal is design/enablers/datastore-commit-log.md on the datastore-rework branch. It is not merged; §2 of it is a write-path inventory.

How the datastore works today.

Repositories write files into the repo's .swamp/ directory, or into the datastore cache dir for a custom datastore. They then call a mark hook, markDirty(relPath?), which reaches DatastoreSyncService (src/domain/datastore/datastore_sync_service.ts, interface at :168, the eight-rule markDirty contract at :199-257).
A caller then flushes, through one of four paths:
- acquireModelLocks().flush (src/cli/repo_context.ts:1723);
- the global coordinator flushDatastoreSync (src/cli/mod.ts:2251);
- pushManagedConfigChanges (src/cli/managed_config_sync.ts:45/153);
- serve's pushChangedToRemote (src/serve/handlers/shared.ts:83-97) under the sync gate.
The S3 and GCS sync implementations live in swamp-extensions, not here. They own the dirty set, the .datastore-sync-state.json sidecar, _index shards and _meta.json.
A filesystem datastore has no sync service at all (repo_context.ts:1170-1178).
Each repo has a SQLite catalog, .swamp/data/_catalog.db, that DataQueryService reads.
Serve runs pollers that pull peers' changes: Config, AccessData, RuntimeData.

What changes. The refactor lands on main in phases:

Phase 1: a UnitOfWork port with a legacy adapter, so repositories stage writes instead of calling the hook directly.
Phase 2: libswamp use cases own the unit of work, and CLI commands and serve stop calling markDirty/pushChanged themselves.
Later phases: a new commit-log engine behind an opt-in format.

Phases 1 and 2 must not change any behaviour.

Why this issue exists. Before any of that lands, this repo's own tests have to pin today's behaviour, so a dropped mark, a lost delete or a missed catalog refresh fails a test instead of reaching users. An audit in September 2026 found:

no in-memory remote to test sync against;
no test that every file a repository changes gets marked, and several real unmarked paths;
no two-repo propagation test;
no ratchet on the write seams Phase 1 will move;
the sync-service conformance suite only checks method shapes.

This issue is one of a set. The tracking issue is listed under Related. End-to-end CLI tests for the same risks are in swamp-club/swamp-uat #481-#485, #487, #490 and #492.

Rules (from AGENTS.md)

Unit tests are in-process only: no subprocesses, no process-global mutation; use withMockedEnv.
Integration tests in integration/ wire real components on a temp filesystem and must not spawn the CLI.
Registry-registered test types use a per-run name built with crypto.randomUUID(), or invalidateType in a finally.
No fixed sleeps (use waitFor from @swamp-club/swamp-testing), no wall-clock assertions, and Deno.utime for mtimes.
Use @std/path for paths and assertPathEquals for path comparisons, since tests run on Windows too.
New files need the AGPLv3 header (deno run license-headers).
Pin today's behaviour, including known gaps. When today's behaviour is a bug, assert it as it is, with a comment naming the bug. Prefer an explicit pinned list checked with assertPinnedSet, so a later fix forces the test to be updated on purpose. Do not fix production code in these issues unless the issue says so.

Goal

Turn the sync-service conformance suite into a behavioural contract, so any sync implementation is held to the same rules. That covers this repo's in-memory remote, the S3 and GCS extensions in swamp-extensions, third-party datastores, and the Phase 1 legacy adapter. Today the suite only checks that the methods exist.

Current state

packages/testing/datastore_conformance.ts:
- assertDatastoreExportConformance (:68) checks shape;
- assertLockConformance (:216) and assertLockTimeoutConformance (:377) test real behaviour;
- assertVerifierConformance (:434);
- assertSyncServiceConformance (:491) only checks the methods exist, calls markDirty/pull/push once, and checks return types and the capabilities() shape.
The suite does not test the eight-rule markDirty contract (src/domain/datastore/datastore_sync_service.ts:199-257), round-trips, delete propagation, or preparePush/commitPush (:379/:405).
Who runs it:
- here: in-memory stubs only (packages/testing/datastore_conformance_test.ts:155-177);
- swamp-extensions: the S3 and GCS extensions consume the package.

Work

Add assertSyncServiceRoundTripConformance(factory) to packages/testing/datastore_conformance.ts.

factory returns two service instances bound to two separate cache dirs on one backend, plus a cleanup.
Cases:
1. Write a file in cache 1, mark it and push. Pull on instance 2: the file is identical.
2. Delete the file in cache 1, mark it (absent on disk means delete) and push. Pull on instance 2: the file is gone.
3. A bare mark followed by push uploads every changed file.
4. A push that fails, via an injected transport failure if the factory offers one, leaves the path dirty, and the next push uploads it. Skip this case when the factory has no failure hook, and report it as skipped.
5. preparePush does not clear dirty state; commitPush applies the change and clears it; a second commitPush with nothing prepared does nothing.
6. Pull with nothing new returns 0 (or void, per the interface) and changes no local file.
7. Relative paths use forward slashes on every OS.
Run it against the in-memory remote from the fake-remote issue in packages/testing/datastore_conformance_test.ts.
Document it in the package README and changelog, so the S3 and GCS extensions adopt it in swamp-extensions. Adopting it there is a follow-up in that repo; note it on the tracking issue.

Done when

The new suite exists, is exported, is documented, and passes against the in-memory remote.

Dependencies

Blocked by: swamp-club#2854
Blocks: nothing
Full dependency graph and waves: swamp-club#2865.

Tracking issue: swamp-club#2865 (https://swamp-club.com/lab/2865).
Adoption by the S3/GCS extensions is a follow-up in swamp-extensions.

Session-start 'swamp model search --json' in the AGENTS.md template is unfulfillable - wire it to a hook or drop it

Flaky property test: analyzeExpression dot/bracket agreement fails when the generated model name is a CEL keyword

Accept usernames for user subjects in grant files

Docs: enable-managed-config should say to re-run config migrate when its push fails

Docs: grant file reference shows a stale format and omits resources and subjects

Flaky property test: analyzeExpression hyphenated dot access fails when modelName generates a CEL keyword ("in")

extension quality and push crash with IsADirectory when additionalFiles lists a directory

extension push: a required global argument renders with a stray "" ("text": "string""")

Docs: extension publishing reference is stale on bare specifiers, quality output and fmt config (swamp-club#3022)

swamp-extensions: replace bare import specifiers with npm:/jsr: specifiers in first-party extensions

extension push: 'Requested visibility' line prints to stdout without the logger prefix, twice per run

A nested structural swamp that outlives the run that started it keeps skipping that run's lock while the holder writes

Show signal waits to remote clients and the dashboard

Settle expired signal waits from swamp serve

Resume signalled workflow runs automatically under swamp serve

extension push/quality: structured acceptances for agents, a clearer title than For next time, and an optional reason

extension push: the undecided private-entitlement verdict still says the registry may start a trial at publish

seed:collective cannot produce a superseded personal trial or a returned trial, so the UAT cannot cover them

Replayable state fragments: Git-reviewable desired state for resources changed by model methods

extension push: registry metadata and content hash label files relative to the repo dir, so a push with --extensions-dir records ../ paths

registry: store and show declared acceptances sent in contentMetadata.acceptances at confirm (swamp-club#3021)

extension push --dry-run: authentication verdict prints 'Signed in as .' when the credential is an API key with no username

serve --remote-only: step output from workers is never persisted to the run log (history logs always empty)

serve HA: worker enrollment on a replica that lacks the enrollment token's definition may create a second definition (unverified)

serve HA: pull a token's definition on an auth miss so a peer accepts a new token at once

extension push: version-drift check reports 'no previously published version found' when the registry call failed

Search and list output follows directory iteration order in the definition, workflow, vault and output repositories

extension push: accept attestation-backed adversarial-review evidence (lookup by extension and content hash), generated provenance, and carry the evidence to the registry at confirm (design: Lab #3023)

Workflow load errors print the raw Zod issue dump instead of a readable message

Decide a stricter naming rule for workflow step and job names

serve: run scheduled workflows concurrently (per-workflow serialization), and report queue delay

Show expired approval gates as expired, with a Cancel action in the dashboard

digitalocean codegen leaves an orphaned security_secret.ts model file after its endpoint left the spec

extension promote accepts a yanked version and reports it promoted

Docs: doctor install reports a stale or failing autoupdate scheduler

extension push output: double-quoted adjacent interpolations, repo-relative paths, and --json emits three JSON documents

auto-resolve: the Installing line prints the extension's entire multi-line description

s3-datastore/serve: readResource without a version returns an older version; the latest marker is rewritten backwards

Publish agent-facing projections of the manual: /llms.txt, .md pages, and llms-full.txt

Let agent-runner drive more agent CLIs (Kilo Code and others)

s3-datastore: every fast-path miss re-downloads every _index shard, so a busy serve pulls the whole index every poll (~230 GB/day S3 egress)

Feedback: Swamp as an approval-gated control plane for a small fleet

extension safety analyzer's Deno.Command( warning is a plain substring match

Tell timeouts apart from cancels in method-run records, and review the hidden 30 s fallback timer for step-called model methods

Run from a git worktree: definitions from the worktree, state from the shared repo

S3/GCS datastore: a push that fails after uploading drops its recorded deletes, so the retry brings deleted data back

Tests: bring the in-memory remote's default semantics up to @swamp/s3-datastore and @swamp/gcs-datastore 2026.10.01.1

Tell the pushing client when its extension contentMetadata fails validation

Extension datastore: query still returns an item after its delete is pulled

Cancel, reject and supersede of a parent run should settle its suspended nested child runs

Tracking: test baseline required before the datastore refactor (commit-log design)

Tests: serve pollers make a peer's writes, deletes and grants visible with a real catalog (before Phase 5)

datastore setup can overwrite an existing remote config tier when it moves an in-repo tier into an extension datastore

serve: define and supply the collective and owner grant condition variables

No first-class workflow primitive for spawning a permission-scoped agent session

A pulled extension can shadow a built-in type, and removing it leaves serve without the built-in

Decorative animations outside the Lab still repaint on the main thread

s3/gcs datastore: pullChanged overwrites dirty, unpushed cache files

Concurrent first runs in a fresh repo log 'Catalog migration to per-extension-aggregate-v3 failed (database is locked)'

Codegen/DigitalOcean: create-only required fields block list/get/delete in generated DigitalOcean models

Codegen/AWS: create-only required fields block list/get/delete in generated AWS models

End a collective's trial when it begins a paid subscription

A collective that cancels inside its 30-day trial window regains trial access to private extensions

s3-datastore: SWAMP_S3_REQUEST_TIMEOUT_MS does not appear to apply to ListObjectsV2 during pull

s3-datastore: S3Lock.acquire overshoots maxWaitMs by up to a full backoff interval

s3-datastore: a model-scoped pull still lists, walks and indexes the whole namespace

Run the web dashboard locally from the CLI without swamp serve

verify-reviews: adversarial review path guard is a hand-kept list, so new extensions silently skip it

issue-lifecycle skill: prepare-to-ship documents a fast_forward method that does not exist

S3 datastore rejects valid cache paths as traversal on Windows

Relationships

#2861 Conformance: behavioural round-trip suite for DatastoreSyncService in packages/testing