Bugfix: Acknowledged transactions can be lost when the commitlog rotates or compresses a segment. - #5785
Merged
bfops merged 1 commit intoAug 24, 2026
Conversation
kim
approved these changes
Aug 24, 2026
bfops
enabled auto-merge
August 24, 2026 16:28
bfops
disabled auto-merge
August 24, 2026 16:44
…tes or compresses a segment.
Imagine this sequence:
1. A database has been running long enough that its commitlog passes
`max_segment_size` — 1 GiB by default — and rolls over to a new segment.
2. A client calls a reducer over a v2 WebSocket, which is to say with
confirmed reads on: the strongest durability promise SpacetimeDB makes.
3. The transaction is written into the new segment, `fdatasync`ed, the
durable offset advances, and the acknowledgement is released.
4. A moment later the machine loses power.
The client was told the write was durable, so it should be there on restart,
right? It won't be, and neither will anything else that landed in that
segment.
`fs::create_segment` builds a new segment by writing the header to a temporary
file and renaming it into place:
```rust
let mut tmp = tempfile::Builder::new().make_in(&self.root.0, |tmp_path| {
File::options().read(true).write(true).create_new(true).open(tmp_path)
})?;
header.write(&mut tmp)?;
tmp.as_file_mut().sync_all()?;
let segment = tmp.persist(path)?; // rename(2)
```
The `sync_all` makes the file's *contents* durable. It says nothing about the
`rename`, which is a modification of the enclosing directory, and on *nix a
directory's entries are only durable once the directory itself is `fsync`ed.
Nothing ever `fsync`s the commitlog root.
So the segment file can be on disk, complete and fully synced, with no name
pointing at it. `existing_offsets` finds segments by reading the directory, so
on restart the log simply ends at the previous segment. Every transaction
written into the orphan — each one `fdatasync`ed and acknowledged — is gone,
and the database comes back up reporting no problem at all. That breaks the
contract `Repo::create_segment` states directly above the offending code ("the
`header` **must** have been durably written to the segment") and the one
`spacetimedb-durability` states for the whole layer, that a higher durable
offset implies durability of every offset below it.
`compress_segment_with` has the same hole and a worse blast radius. It renames
a compressed copy over a segment that is *already* durable, and never syncs
the copy's contents either:
```rust
let mut dst = NamedTempFile::new_in(&self.root)?;
let stats = f.compress(&mut src, &mut dst)?;
dst.persist(self.segment_path(offset))?;
```
A crash in that window can leave the segment's name resolving to a truncated
or empty compressed file while the original — holding committed, acknowledged
transactions — has already been unlinked. Rotation can lose a new segment;
compression can lose an old one that was safe until we touched it.
Two things kept this quiet. It needs a crash inside a narrow window at a
segment boundary, and on ext4 with `data=ordered` the next data `fsync`
usually drags the pending rename along with it — which makes the bug look like
correct behaviour on the most common Linux configuration, even though it is a
filesystem accident rather than a guarantee, and does not carry over to XFS,
APFS or btrfs. Beyond that, an `fsync` leaves no trace a test can observe from
outside the process, so no amount of ordinary testing would have noticed the
missing one. The `snapshot` crate, doing the same rename dance a few
directories away, gets it right and has done all along.
Both call sites now go through a single `Fs::persist_durably`, which syncs the
file, renames it, and syncs the root. Making it one method rather than two
fixes is the point: the invariant is easy to forget, and the next segment
installation added to this repo gets it for free. It takes a `SegmentFile`
rather than any path, because it syncs the repository root and nothing else --
installing a file outside that directory has to say so explicitly, rather than
silently syncing the wrong one.
- Add `sync_dir`, mirroring `snapshot`'s `FileOrDirPath::sync_all`, including
its no-op on Windows, where opening a directory as a file is an error.
- Add the missing `sync_all` on the compressed segment's contents, which was
absent independently of the directory problem.
# API and ABI breaking changes
None.
# Expected complexity level and risk
1. Two extra `fsync`s on two cold paths — one per segment rotation, so once
per 1 GiB of log by default, and one per segment compression. Both paths
already `fsync` a file and perform a rename, so the added cost is noise
against what they do anyway.
# Testing
- [x] `cargo test -p spacetimedb-commitlog`: 67 unit + 11 integration tests
pass.
- [x] `cargo clippy -p spacetimedb-commitlog --all-targets` clean.
- [ ] Reviewer: there is deliberately no test for this, for the same reason
the bug survived so long. An `fsync` has no effect that is observable
without a crash, so a test can only assert that the call was made --
a restatement of the line it is testing -- and demonstrating the actual
property needs crash injection (`dm-log-writes`, or an `LD_PRELOAD`
that swallows `fsync`) which this crate has no harness for. What guards
the invariant instead is structural: `.persist(` now appears exactly
once in the crate, inside `persist_durably`, whose doc comment spells
out both failure modes and whose `SegmentFile` parameter keeps the
destination inside the directory it syncs. Please review that funnel
rather than look for a test. The added `sync_all` on the compressed
file's contents rests on review for the same reason.
clockwork-labs-bot
force-pushed
the
kris/commitlog-durable-rename
branch
from
August 24, 2026 16:47
b2084c4 to
7459c34
Compare
bfops
enabled auto-merge
August 24, 2026 16:48
Merged
via the queue into
clockworklabs:master
with commit Aug 24, 2026
ee0892a
61 of 62 checks passed
pull Bot
pushed a commit
to Abaso007/SpacetimeDB
that referenced
this pull request
Sep 9, 2026
) ## Summary - Update automatic migration docs to reflect empty-table removal behavior. - Document accessor/source-name metadata changes and index accessor rename limits. - Add a public MCP reference covering `spacetime mcp`, host-wide vs database-scoped tool shapes, permissions, and common errors. - Align the TypeScript server skill and bundled plugin copy so scheduled procedures point to `onSchedule`. - Fix the TypeScript procedures reference so it no longer claims `spacetimedb.procedure` takes a procedure name argument. - Clarify scheduled interval timing and connection ID availability in reducer context docs. # API and ABI breaking changes n/a # Rollback safety impact n/a # Expected complexity level and risk 1 - docs-only audit updates. ## Audit notes - Baseline: existing open `bot/docs-audit` PR clockworklabs#5723; merged current `origin/master` into `bot/docs-audit` before today's audit pass. - 2026-08-15 commit-impact pass checked new master commits `b1291ee11` / clockworklabs#5751 (C# HTTP timeout clamp), `0948a1b3b` / clockworklabs#5752 (2.8.2 version bump), and `524b4487d` / clockworklabs#5583 (LLM benchmark evals and server skill updates). - Checked the changed server skill guidance from clockworklabs#5583 against public docs for procedures, HTTP, scheduled procedures, views/query-builder views, view primary keys, client visibility filters, schedule tables, defaults, lifecycle connection IDs, and deterministic context guidance. - Checked clockworklabs#5751 against public procedure HTTP docs; the 30-second default and 180-second maximum timeout are already documented. - 2026-08-16 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, SDK APIs, server module APIs, auth, onboarding, deployment, MCP, scheduling, and cross-language examples. - Source PR for the 2026-08-16 correction: clockworklabs#5728 documented TypeScript `onSchedule` registration for scheduled reducers/procedures; the TypeScript server skill still had one stale scheduled-procedure sentence and the plugin skill copy had not been synced. - 2026-08-17 commit-impact pass found no new `origin/master` commits after the 2026-08-16 audit baseline. - 2026-08-17 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, SDK APIs, server module APIs, auth, onboarding, deployment, MCP, scheduling, and cross-language examples. - The 2026-08-17 correction is not from a new master PR; it aligns the TypeScript procedures reference with current TypeScript module examples/tests and the TypeScript server skill. Procedure names come from exported values, not a name argument to `spacetimedb.procedure`. - 2026-08-18 commit-impact pass checked new master commits `053742688` / clockworklabs#5735 (scheduled functions reschedule from intended execution time and skip missed interval ticks) and `e1da590b7` / clockworklabs#5732 (submodule function call separators docs fix). - Source PR for the 2026-08-18 scheduler correction: clockworklabs#5735 changed interval rescheduling semantics; schedule table docs now state that missed interval ticks are skipped and future ticks stay anchored to intended run times. - 2026-08-18 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, SDK APIs, server module APIs, auth, onboarding, deployment, scheduling, lifecycle contexts, and cross-language consistency. - The reducer context reference previously said lifecycle reducers may lack `connectionId`; it now distinguishes `init`/scheduled/no-connection calls from client-connected and client-disconnected reducers. - Unrelated untracked local files were present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. ## Validation - `pnpm --dir docs typecheck` - `pnpm --dir docs build` (passed; emitted existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion) - Previous validations on this PR: `pnpm build`, `node codex-plugin/scripts/check-skills-sync.ts`, `git diff --check -- docs/docs/00200-core-concepts/00200-functions/00400-procedures.md` - 2026-08-22 commit-impact pass checked new master commits `7c888afe8` / clockworklabs#5576 (.NET 10 support and C# LLM benchmark cleanup), `6dee26c6e` / clockworklabs#5764 (2.8.3 version bump), `8e410d284` / clockworklabs#5758 (unused dependency cleanup), `8cb9d652d` / clockworklabs#5716 (standalone-supported smoketests in public CI), `6bbe5f2eb` / clockworklabs#5774 (standalone module HTTP config), `e9f37a173` / clockworklabs#5753 (public CI build-time reduction), and `fb7282411` / clockworklabs#5770 (absent table pages in snapshots). - Checked clockworklabs#5774 against public standalone configuration docs; the new `[module-http]` setting is already documented on `master` and did not need an audit-branch correction. - 2026-08-22 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, auth/onboarding, deployment, procedures/HTTP, schedule tables, views, table accessors, MCP, and cross-language naming consistency. - The 2026-08-22 correction is not from a new master PR; it aligns TypeScript public docs examples with the TypeScript server skill and tables reference: `schema({...})` keys become server `ctx.db` accessors verbatim, so examples now use snake_case keys matching table names instead of camelCase accessors. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-22 validation: `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-08-24 commit-impact pass checked new master commit `310d2e660` / clockworklabs#5517 (websocket liveness checks and idle timeout close behavior). Standalone websocket configuration docs already describe `ping-interval`, `idle-timeout`, `close-handshake-timeout`, and `incoming-queue-length`; no new docs correction was needed. - 2026-08-24 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, auth/onboarding, deployment, MCP, scheduling, views, table accessors, websocket config, and cross-language naming consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master`; no new docs edits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-24 validation: `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-08-25 commit-impact pass checked new master commits `1740adf6e` / clockworklabs#5640 (log level audit), `cfa9636a6` / clockworklabs#5775 (MCP route egress tracking), `ee0892a8d` / clockworklabs#5785 (commitlog rotation/compression durability fix), `36ad4bafa` / clockworklabs#5571 (.NET version and host OS handling), and `2432a84b6` / clockworklabs#5780 (remove Emscripten from linux smoketests). - Source PR for the 2026-08-25 correction: clockworklabs#5571 changed NativeAOT host/version support checks; the CLI reference and CLI help now say NativeAOT is supported on Windows and on Linux with .NET 10, instead of Windows only. - 2026-08-25 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, C#/Rust/TypeScript/C++ server APIs, client SDK APIs, auth/onboarding, deployment, MCP, scheduling, views, table/index accessors, and cross-language consistency. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master` and adding the NativeAOT support wording correction. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-25 validation: `git diff --check`; `cargo test -p spacetimedb-cli dotnet --lib`. - 2026-08-26 commit-impact pass checked new master commits `c0c19366a` / clockworklabs#5761 (TypeScript provider reconnect token retention), `dd804c939` / clockworklabs#5738 (Unity static state reset for generic table handles), `74167cc4e` / clockworklabs#5765 (module host init failure metric cause label), `ea1f39f13` / clockworklabs#5792 (Unity WebGL IEnumerator import), `dca219155` / clockworklabs#5817 (codegen git hash build-script move), and `2f268a89f` / clockworklabs#5819 (docs logo update). - Checked clockworklabs#5761 against TypeScript client/provider connection docs and token persistence examples; provider reconnect behavior and lower-level `DbConnection` responsibilities are already documented. - Checked clockworklabs#5738/clockworklabs#5792 against Unity setup/client docs; the Unity tutorial already notes SDK static state reset with Domain Reloading disabled, and the WebGL IEnumerator fix is an internal import correction with no public docs change needed. - Checked clockworklabs#5765 against public docs/skills; no public metrics reference documents `spacetime_module_host_init_failures_total`, so no docs correction was needed. - 2026-08-26 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, auth/onboarding, deployment, MCP, scheduling, Unity/WebGL, table/index accessors, and cross-language consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master`; no new docs edits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-26 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-08-27 commit-impact pass checked new master commits `79b79e94d` / clockworklabs#5794 (C# connection cleanup/leak fixes), `0a1b68d78` / clockworklabs#5797 (CI build/test-suite cleanup), `6c3572e25` / clockworklabs#5565 (C++ multi-column support for 3+ column queries), `0bc1b0d73` / clockworklabs#5824 (unexpected module host exit metric), and `c1118efbb` / clockworklabs#5809 (commitlog decode error offsets). - Source PR for the 2026-08-27 correction: clockworklabs#5565 added C++ compile coverage for 3+ column multi-column index filters and trailing range filters; the indexes docs now state the generalized prefix/range rule and the C++ range helper include behavior. - Checked clockworklabs#5794 against C# client/Unity docs and skills for connection callbacks, `FrameTick`, token persistence, and disconnect behavior; no public docs correction was needed beyond existing guidance. - Checked clockworklabs#5824 against public docs/skills; no public metrics reference documents the new unexpected module host exit metric, so no docs correction was needed. - 2026-08-27 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, auth/onboarding, deployment, MCP, scheduling, Unity/Unreal ticking, table/index accessors, and cross-language consistency. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master` and adding the C++ multi-column range query wording correction. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-27 validation: `git diff --check`; `node codex-plugin/scripts/check-skills-sync.ts`; `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-08-30 commit-impact pass checked current master commits `9e0d92412` / clockworklabs#5815 (merge-queue workflow reuse), `436b3e57a` / clockworklabs#5825 (procedure metrics attribution), and `69cd1ca3b` / clockworklabs#5833 (2.9.0 version bump). - Checked clockworklabs#5825 against public procedure/docs skill coverage; the change is internal metrics attribution and no public metrics reference documents the affected procedure metric behavior, so no docs correction was needed. - Checked clockworklabs#5833 against public docs and skills for version-specific installation snippets, TypeScript package metadata, C# package references, and tutorial version claims; no high-confidence public docs drift was found. - 2026-08-30 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, auth/onboarding, deployment, MCP, scheduling, views, event tables, table/index accessors, procedure/HTTP APIs, Unity/Godot/Unreal ticking, and cross-language naming consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR description only; no new docs edits or commits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-30 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check`; `pnpm --dir docs typecheck`. - 2026-09-01 commit-impact pass checked new master commits `ffc2e4820` / clockworklabs#5768 (snapshot worker now publishes `Option<TxOffset>`) and `b0661c3cc` / clockworklabs#5850 (public release workflow rejects direct manual invocations). - Checked clockworklabs#5768 against public docs and skills; the changed snapshot worker watch API is internal engine plumbing and no public docs correction was needed. - Checked clockworklabs#5850 against public docs and skills; the direct public release workflow guard is internal release automation behavior and no public docs correction was needed. - 2026-09-01 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, procedures/HTTP, views, indexes, and cross-language naming consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master`; no new docs edits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-01 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check`; `pnpm --dir docs typecheck`. - 2026-09-02 commit-impact pass checked new master commits `f49ceae3a` / clockworklabs#5830 (commitlog fdatasync on segment open), `5f3e26bf2` / clockworklabs#5829 (commitlog write-failure regression test), `c97256c88` / clockworklabs#5857 (CI ubuntu version pinning), `a272e1919` / clockworklabs#5852 (Unity WebGL build coverage), `7c462bb47` / clockworklabs#5731 (rollback safety PR checks), `549489e97` / clockworklabs#5707 (TypeScript SDK routes established websocket errors to `onDisconnect`), and `f08dc302a` / clockworklabs#5836 (C++ auto-increment macro symbol collision fix). - Checked clockworklabs#5707 against TypeScript client reference and troubleshooting docs; `onDisconnect` already documents disconnects due to errors, and troubleshooting already tells users to register `onConnectError`/`onDisconnect` callbacks. - Checked clockworklabs#5836 against C++ server skill/docs for auto-increment macros and range-query include guidance; no public docs correction was needed. - Checked clockworklabs#5852 against Unity client docs and skill guidance for WebGL/ticking; the change adds CI coverage and no public docs correction was needed. - 2026-09-02 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, procedures/HTTP, views, indexes, and cross-language naming consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master`; no new docs edits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-02 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check`; `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-09-03 commit-impact pass checked new master commits `2fc8f8221` / clockworklabs#5849 (RootRoutes for `/v1/mcp`) and `2fe329243` / clockworklabs#5861 (CI runner label update). - Source PR for the 2026-09-03 MCP endpoint correction: clockworklabs#5849 added root-route support for `/v1/mcp`; the public MCP reference now documents direct HTTP MCP endpoints alongside `spacetime mcp`. - Checked clockworklabs#5861 against public docs and skills; the CI runner label change is internal workflow plumbing and no public docs correction was needed. - 2026-09-03 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, procedures/HTTP, views, indexes, and cross-language naming consistency. - Also corrected the TypeScript lifecycle docs to guard nullable `ctx.connectionId`, matching the TypeScript server skill and reducer context reference. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master` and adding the MCP/lifecycle docs corrections. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-03 validation: `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-09-04 commit-impact pass checked new master commits `28071acff` / clockworklabs#5610 (C# generated direct dispatch for reducers, procedures, HTTP handlers, views, and anonymous views), `53772f867` / clockworklabs#5866 (jsonwebtoken 11 upgrade and custom header-field regression coverage), `3663fa112` / clockworklabs#5867 (`spacetime dev` no longer forwards C#-only .NET options to non-C# templates), `0c0365406` / clockworklabs#5868 (2.10.0 version bump), and `baca5cdf7` / clockworklabs#5848 (CI runner caching with sccache). - Source PR for the 2026-09-04 C# snippet correction: clockworklabs#5610 reinforced generated C# module entrypoint dispatch through public static module members; public docs now consistently show `public static partial class Module` in C# module examples. - Checked clockworklabs#5866 against public auth/key-architecture docs and skills; the JWT library upgrade and custom header handling are implementation hardening and no public docs correction was needed. - Checked clockworklabs#5867 against CLI docs and the CLI skill; `spacetime dev`/`init` .NET option wording already describes C# targeting without telling non-C# users to pass C#-only options. - Checked clockworklabs#5868 against install/package snippets and versioned references; no high-confidence public docs drift was found beyond current examples using wildcard or unpinned package versions where appropriate. - 2026-09-04 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, procedures/HTTP, views, indexes, and cross-language consistency. - Also corrected access-permissions view wording so it no longer says views can iterate full tables, and fixed a duplicate C# RLS filter constant in the recursive-rules example. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master` and adding the C# module snippet/view-access corrections. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-04 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check`; `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-09-05 commit-impact pass checked new master commits `9cfb2b7e9` / clockworklabs#5871 (npm release workflow uses GitHub-provided runner) and `3653d2ed4` / clockworklabs#5872 (`update-mirror-latest-version` release workflow uses `ubuntu-latest`). Both are internal release automation changes and no public docs correction was needed. - 2026-09-05 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, procedures/HTTP, views, indexes, and cross-language consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master`; no new docs edits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-05 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check`; `pnpm --dir docs typecheck`. - 2026-09-06 commit-impact pass found no new `origin/master` commits after the 2026-09-05 audit baseline; `bot/docs-audit` was already up to date with current `origin/master` after fetch. - 2026-09-06 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, lifecycle contexts, procedures/HTTP, views, indexes, and cross-language consistency. - The 2026-09-06 correction is not from a new master PR; it aligns lifecycle reducer examples with the nullable/optional connection ID API shape used by the language SDKs and server skills. - Updated the existing open `bot/docs-audit` PR with the lifecycle connection ID example correction. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-06 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check -- docs/docs/00200-core-concepts/00200-functions/00300-reducers/00500-lifecycle.md`; `pnpm --dir docs typecheck`. - 2026-09-08 commit-impact pass found no new `origin/master` commits after the current `bot/docs-audit` branch's merged `origin/master` baseline; `git log HEAD..origin/master` was empty after fetch and merge preflight reported the branch already up to date. - 2026-09-08 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, lifecycle contexts, procedures/HTTP, views, indexes, and cross-language consistency. - The 2026-09-08 correction is not from a new master PR; it aligns current TypeScript docs snippets with the TypeScript server/client skill casing guidance by using camelCase for TypeScript exports, schema keys/accessors, reducer/procedure arguments, and row fields while preserving explicit `name: 'snake_case'` canonical database names where shown. - Updated the existing open `bot/docs-audit` PR with the TypeScript casing correction. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-08 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check -- docs/docs`; TypeScript docs casing scanner for current TypeScript/TSX docs blocks (only external OIDC field names remain snake_case); `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/Browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). --------- Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
rohanranjan0902
pushed a commit
to rohanranjan0902/SpacetimeDB
that referenced
this pull request
Sep 19, 2026
) ## Summary - Update automatic migration docs to reflect empty-table removal behavior. - Document accessor/source-name metadata changes and index accessor rename limits. - Add a public MCP reference covering `spacetime mcp`, host-wide vs database-scoped tool shapes, permissions, and common errors. - Align the TypeScript server skill and bundled plugin copy so scheduled procedures point to `onSchedule`. - Fix the TypeScript procedures reference so it no longer claims `spacetimedb.procedure` takes a procedure name argument. - Clarify scheduled interval timing and connection ID availability in reducer context docs. # API and ABI breaking changes n/a # Rollback safety impact n/a # Expected complexity level and risk 1 - docs-only audit updates. ## Audit notes - Baseline: existing open `bot/docs-audit` PR clockworklabs#5723; merged current `origin/master` into `bot/docs-audit` before today's audit pass. - 2026-08-15 commit-impact pass checked new master commits `b1291ee11` / clockworklabs#5751 (C# HTTP timeout clamp), `0948a1b3b` / clockworklabs#5752 (2.8.2 version bump), and `524b4487d` / clockworklabs#5583 (LLM benchmark evals and server skill updates). - Checked the changed server skill guidance from clockworklabs#5583 against public docs for procedures, HTTP, scheduled procedures, views/query-builder views, view primary keys, client visibility filters, schedule tables, defaults, lifecycle connection IDs, and deterministic context guidance. - Checked clockworklabs#5751 against public procedure HTTP docs; the 30-second default and 180-second maximum timeout are already documented. - 2026-08-16 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, SDK APIs, server module APIs, auth, onboarding, deployment, MCP, scheduling, and cross-language examples. - Source PR for the 2026-08-16 correction: clockworklabs#5728 documented TypeScript `onSchedule` registration for scheduled reducers/procedures; the TypeScript server skill still had one stale scheduled-procedure sentence and the plugin skill copy had not been synced. - 2026-08-17 commit-impact pass found no new `origin/master` commits after the 2026-08-16 audit baseline. - 2026-08-17 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, SDK APIs, server module APIs, auth, onboarding, deployment, MCP, scheduling, and cross-language examples. - The 2026-08-17 correction is not from a new master PR; it aligns the TypeScript procedures reference with current TypeScript module examples/tests and the TypeScript server skill. Procedure names come from exported values, not a name argument to `spacetimedb.procedure`. - 2026-08-18 commit-impact pass checked new master commits `053742688` / clockworklabs#5735 (scheduled functions reschedule from intended execution time and skip missed interval ticks) and `e1da590b7` / clockworklabs#5732 (submodule function call separators docs fix). - Source PR for the 2026-08-18 scheduler correction: clockworklabs#5735 changed interval rescheduling semantics; schedule table docs now state that missed interval ticks are skipped and future ticks stay anchored to intended run times. - 2026-08-18 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, SDK APIs, server module APIs, auth, onboarding, deployment, scheduling, lifecycle contexts, and cross-language consistency. - The reducer context reference previously said lifecycle reducers may lack `connectionId`; it now distinguishes `init`/scheduled/no-connection calls from client-connected and client-disconnected reducers. - Unrelated untracked local files were present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. ## Validation - `pnpm --dir docs typecheck` - `pnpm --dir docs build` (passed; emitted existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion) - Previous validations on this PR: `pnpm build`, `node codex-plugin/scripts/check-skills-sync.ts`, `git diff --check -- docs/docs/00200-core-concepts/00200-functions/00400-procedures.md` - 2026-08-22 commit-impact pass checked new master commits `7c888afe8` / clockworklabs#5576 (.NET 10 support and C# LLM benchmark cleanup), `6dee26c6e` / clockworklabs#5764 (2.8.3 version bump), `8e410d284` / clockworklabs#5758 (unused dependency cleanup), `8cb9d652d` / clockworklabs#5716 (standalone-supported smoketests in public CI), `6bbe5f2eb` / clockworklabs#5774 (standalone module HTTP config), `e9f37a173` / clockworklabs#5753 (public CI build-time reduction), and `fb7282411` / clockworklabs#5770 (absent table pages in snapshots). - Checked clockworklabs#5774 against public standalone configuration docs; the new `[module-http]` setting is already documented on `master` and did not need an audit-branch correction. - 2026-08-22 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, auth/onboarding, deployment, procedures/HTTP, schedule tables, views, table accessors, MCP, and cross-language naming consistency. - The 2026-08-22 correction is not from a new master PR; it aligns TypeScript public docs examples with the TypeScript server skill and tables reference: `schema({...})` keys become server `ctx.db` accessors verbatim, so examples now use snake_case keys matching table names instead of camelCase accessors. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-22 validation: `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-08-24 commit-impact pass checked new master commit `310d2e660` / clockworklabs#5517 (websocket liveness checks and idle timeout close behavior). Standalone websocket configuration docs already describe `ping-interval`, `idle-timeout`, `close-handshake-timeout`, and `incoming-queue-length`; no new docs correction was needed. - 2026-08-24 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, auth/onboarding, deployment, MCP, scheduling, views, table accessors, websocket config, and cross-language naming consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master`; no new docs edits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-24 validation: `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-08-25 commit-impact pass checked new master commits `1740adf6e` / clockworklabs#5640 (log level audit), `cfa9636a6` / clockworklabs#5775 (MCP route egress tracking), `ee0892a8d` / clockworklabs#5785 (commitlog rotation/compression durability fix), `36ad4bafa` / clockworklabs#5571 (.NET version and host OS handling), and `2432a84b6` / clockworklabs#5780 (remove Emscripten from linux smoketests). - Source PR for the 2026-08-25 correction: clockworklabs#5571 changed NativeAOT host/version support checks; the CLI reference and CLI help now say NativeAOT is supported on Windows and on Linux with .NET 10, instead of Windows only. - 2026-08-25 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, C#/Rust/TypeScript/C++ server APIs, client SDK APIs, auth/onboarding, deployment, MCP, scheduling, views, table/index accessors, and cross-language consistency. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master` and adding the NativeAOT support wording correction. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-25 validation: `git diff --check`; `cargo test -p spacetimedb-cli dotnet --lib`. - 2026-08-26 commit-impact pass checked new master commits `c0c19366a` / clockworklabs#5761 (TypeScript provider reconnect token retention), `dd804c939` / clockworklabs#5738 (Unity static state reset for generic table handles), `74167cc4e` / clockworklabs#5765 (module host init failure metric cause label), `ea1f39f13` / clockworklabs#5792 (Unity WebGL IEnumerator import), `dca219155` / clockworklabs#5817 (codegen git hash build-script move), and `2f268a89f` / clockworklabs#5819 (docs logo update). - Checked clockworklabs#5761 against TypeScript client/provider connection docs and token persistence examples; provider reconnect behavior and lower-level `DbConnection` responsibilities are already documented. - Checked clockworklabs#5738/clockworklabs#5792 against Unity setup/client docs; the Unity tutorial already notes SDK static state reset with Domain Reloading disabled, and the WebGL IEnumerator fix is an internal import correction with no public docs change needed. - Checked clockworklabs#5765 against public docs/skills; no public metrics reference documents `spacetime_module_host_init_failures_total`, so no docs correction was needed. - 2026-08-26 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, auth/onboarding, deployment, MCP, scheduling, Unity/WebGL, table/index accessors, and cross-language consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master`; no new docs edits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-26 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-08-27 commit-impact pass checked new master commits `79b79e94d` / clockworklabs#5794 (C# connection cleanup/leak fixes), `0a1b68d78` / clockworklabs#5797 (CI build/test-suite cleanup), `6c3572e25` / clockworklabs#5565 (C++ multi-column support for 3+ column queries), `0bc1b0d73` / clockworklabs#5824 (unexpected module host exit metric), and `c1118efbb` / clockworklabs#5809 (commitlog decode error offsets). - Source PR for the 2026-08-27 correction: clockworklabs#5565 added C++ compile coverage for 3+ column multi-column index filters and trailing range filters; the indexes docs now state the generalized prefix/range rule and the C++ range helper include behavior. - Checked clockworklabs#5794 against C# client/Unity docs and skills for connection callbacks, `FrameTick`, token persistence, and disconnect behavior; no public docs correction was needed beyond existing guidance. - Checked clockworklabs#5824 against public docs/skills; no public metrics reference documents the new unexpected module host exit metric, so no docs correction was needed. - 2026-08-27 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, auth/onboarding, deployment, MCP, scheduling, Unity/Unreal ticking, table/index accessors, and cross-language consistency. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master` and adding the C++ multi-column range query wording correction. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-27 validation: `git diff --check`; `node codex-plugin/scripts/check-skills-sync.ts`; `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-08-30 commit-impact pass checked current master commits `9e0d92412` / clockworklabs#5815 (merge-queue workflow reuse), `436b3e57a` / clockworklabs#5825 (procedure metrics attribution), and `69cd1ca3b` / clockworklabs#5833 (2.9.0 version bump). - Checked clockworklabs#5825 against public procedure/docs skill coverage; the change is internal metrics attribution and no public metrics reference documents the affected procedure metric behavior, so no docs correction was needed. - Checked clockworklabs#5833 against public docs and skills for version-specific installation snippets, TypeScript package metadata, C# package references, and tutorial version claims; no high-confidence public docs drift was found. - 2026-08-30 skills/docs consistency pass compared `skills/*/SKILL.md` against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, auth/onboarding, deployment, MCP, scheduling, views, event tables, table/index accessors, procedure/HTTP APIs, Unity/Godot/Unreal ticking, and cross-language naming consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR description only; no new docs edits or commits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-08-30 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check`; `pnpm --dir docs typecheck`. - 2026-09-01 commit-impact pass checked new master commits `ffc2e4820` / clockworklabs#5768 (snapshot worker now publishes `Option<TxOffset>`) and `b0661c3cc` / clockworklabs#5850 (public release workflow rejects direct manual invocations). - Checked clockworklabs#5768 against public docs and skills; the changed snapshot worker watch API is internal engine plumbing and no public docs correction was needed. - Checked clockworklabs#5850 against public docs and skills; the direct public release workflow guard is internal release automation behavior and no public docs correction was needed. - 2026-09-01 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, procedures/HTTP, views, indexes, and cross-language naming consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master`; no new docs edits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-01 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check`; `pnpm --dir docs typecheck`. - 2026-09-02 commit-impact pass checked new master commits `f49ceae3a` / clockworklabs#5830 (commitlog fdatasync on segment open), `5f3e26bf2` / clockworklabs#5829 (commitlog write-failure regression test), `c97256c88` / clockworklabs#5857 (CI ubuntu version pinning), `a272e1919` / clockworklabs#5852 (Unity WebGL build coverage), `7c462bb47` / clockworklabs#5731 (rollback safety PR checks), `549489e97` / clockworklabs#5707 (TypeScript SDK routes established websocket errors to `onDisconnect`), and `f08dc302a` / clockworklabs#5836 (C++ auto-increment macro symbol collision fix). - Checked clockworklabs#5707 against TypeScript client reference and troubleshooting docs; `onDisconnect` already documents disconnects due to errors, and troubleshooting already tells users to register `onConnectError`/`onDisconnect` callbacks. - Checked clockworklabs#5836 against C++ server skill/docs for auto-increment macros and range-query include guidance; no public docs correction was needed. - Checked clockworklabs#5852 against Unity client docs and skill guidance for WebGL/ticking; the change adds CI coverage and no public docs correction was needed. - 2026-09-02 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, procedures/HTTP, views, indexes, and cross-language naming consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master`; no new docs edits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-02 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check`; `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-09-03 commit-impact pass checked new master commits `2fc8f8221` / clockworklabs#5849 (RootRoutes for `/v1/mcp`) and `2fe329243` / clockworklabs#5861 (CI runner label update). - Source PR for the 2026-09-03 MCP endpoint correction: clockworklabs#5849 added root-route support for `/v1/mcp`; the public MCP reference now documents direct HTTP MCP endpoints alongside `spacetime mcp`. - Checked clockworklabs#5861 against public docs and skills; the CI runner label change is internal workflow plumbing and no public docs correction was needed. - 2026-09-03 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, procedures/HTTP, views, indexes, and cross-language naming consistency. - Also corrected the TypeScript lifecycle docs to guard nullable `ctx.connectionId`, matching the TypeScript server skill and reducer context reference. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master` and adding the MCP/lifecycle docs corrections. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-03 validation: `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-09-04 commit-impact pass checked new master commits `28071acff` / clockworklabs#5610 (C# generated direct dispatch for reducers, procedures, HTTP handlers, views, and anonymous views), `53772f867` / clockworklabs#5866 (jsonwebtoken 11 upgrade and custom header-field regression coverage), `3663fa112` / clockworklabs#5867 (`spacetime dev` no longer forwards C#-only .NET options to non-C# templates), `0c0365406` / clockworklabs#5868 (2.10.0 version bump), and `baca5cdf7` / clockworklabs#5848 (CI runner caching with sccache). - Source PR for the 2026-09-04 C# snippet correction: clockworklabs#5610 reinforced generated C# module entrypoint dispatch through public static module members; public docs now consistently show `public static partial class Module` in C# module examples. - Checked clockworklabs#5866 against public auth/key-architecture docs and skills; the JWT library upgrade and custom header handling are implementation hardening and no public docs correction was needed. - Checked clockworklabs#5867 against CLI docs and the CLI skill; `spacetime dev`/`init` .NET option wording already describes C# targeting without telling non-C# users to pass C#-only options. - Checked clockworklabs#5868 against install/package snippets and versioned references; no high-confidence public docs drift was found beyond current examples using wildcard or unpinned package versions where appropriate. - 2026-09-04 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, procedures/HTTP, views, indexes, and cross-language consistency. - Also corrected access-permissions view wording so it no longer says views can iterate full tables, and fixed a duplicate C# RLS filter constant in the recursive-rules example. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master` and adding the C# module snippet/view-access corrections. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-04 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check`; `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). - 2026-09-05 commit-impact pass checked new master commits `9cfb2b7e9` / clockworklabs#5871 (npm release workflow uses GitHub-provided runner) and `3653d2ed4` / clockworklabs#5872 (`update-mirror-latest-version` release workflow uses `ubuntu-latest`). Both are internal release automation changes and no public docs correction was needed. - 2026-09-05 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, procedures/HTTP, views, indexes, and cross-language consistency. No additional high-confidence mismatch was found. - Updated the existing open `bot/docs-audit` PR by merging current `origin/master`; no new docs edits were added in this run. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-05 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check`; `pnpm --dir docs typecheck`. - 2026-09-06 commit-impact pass found no new `origin/master` commits after the 2026-09-05 audit baseline; `bot/docs-audit` was already up to date with current `origin/master` after fetch. - 2026-09-06 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, lifecycle contexts, procedures/HTTP, views, indexes, and cross-language consistency. - The 2026-09-06 correction is not from a new master PR; it aligns lifecycle reducer examples with the nullable/optional connection ID API shape used by the language SDKs and server skills. - Updated the existing open `bot/docs-audit` PR with the lifecycle connection ID example correction. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-06 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check -- docs/docs/00200-core-concepts/00200-functions/00300-reducers/00500-lifecycle.md`; `pnpm --dir docs typecheck`. - 2026-09-08 commit-impact pass found no new `origin/master` commits after the current `bot/docs-audit` branch's merged `origin/master` baseline; `git log HEAD..origin/master` was empty after fetch and merge preflight reported the branch already up to date. - 2026-09-08 skills/docs consistency pass compared all 11 `skills/*/SKILL.md` files against public docs for CLI flows, TypeScript/C#/Rust/C++ server APIs, client SDK APIs, Unity/Unreal ticking, auth/onboarding, deployment, MCP, scheduling, lifecycle contexts, procedures/HTTP, views, indexes, and cross-language consistency. - The 2026-09-08 correction is not from a new master PR; it aligns current TypeScript docs snippets with the TypeScript server/client skill casing guidance by using camelCase for TypeScript exports, schema keys/accessors, reducer/procedure arguments, and row fields while preserving explicit `name: 'snake_case'` canonical database names where shown. - Updated the existing open `bot/docs-audit` PR with the TypeScript casing correction. - Unrelated untracked local files remained present at repo root (`.openclaw/`, `AGENTS.md`, `HEARTBEAT.md`, `IDENTITY.md`, `SOUL.md`, `TOOLS.md`, `USER.md`) and were left untouched. - 2026-09-08 validation: `node codex-plugin/scripts/check-skills-sync.ts`; `git diff --check -- docs/docs`; TypeScript docs casing scanner for current TypeScript/TSX docs blocks (only external OIDC field names remain snake_case); `pnpm --dir docs typecheck`; `pnpm --dir docs build` (passed; emitted existing Docusaurus update/Browserslist freshness notices and existing llms-txt warning for `/docs/ask-ai/ask-ai` empty-content conversion). --------- Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
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
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.
Imagine this sequence:
max_segment_size— 1 GiB by default — and rolls over to a new segment.confirmed reads on: the strongest durability promise SpacetimeDB makes.
fdatasynced, thedurable offset advances, and the acknowledgement is released.
The client was told the write was durable, so it should be there on restart,
right? It won't be, and neither will anything else that landed in that
segment.
fs::create_segmentbuilds a new segment by writing the header to a temporaryfile and renaming it into place:
The
sync_allmakes the file's contents durable. It says nothing about therename, which is a modification of the enclosing directory, and on *nix adirectory's entries are only durable once the directory itself is
fsynced.Nothing ever
fsyncs the commitlog root.So the segment file can be on disk, complete and fully synced, with no name
pointing at it.
existing_offsetsfinds segments by reading the directory, soon restart the log simply ends at the previous segment. Every transaction
written into the orphan — each one
fdatasynced and acknowledged — is gone,and the database comes back up reporting no problem at all. That breaks the
contract
Repo::create_segmentstates directly above the offending code ("theheadermust have been durably written to the segment") and the onespacetimedb-durabilitystates for the whole layer, that a higher durableoffset implies durability of every offset below it.
compress_segment_withhas the same hole and a worse blast radius. It renamesa compressed copy over a segment that is already durable, and never syncs
the copy's contents either:
A crash in that window can leave the segment's name resolving to a truncated
or empty compressed file while the original — holding committed, acknowledged
transactions — has already been unlinked. Rotation can lose a new segment;
compression can lose an old one that was safe until we touched it.
Two things kept this quiet. It needs a crash inside a narrow window at a
segment boundary, and on ext4 with
data=orderedthe next datafsyncusually drags the pending rename along with it — which makes the bug look like
correct behaviour on the most common Linux configuration, even though it is a
filesystem accident rather than a guarantee, and does not carry over to XFS,
APFS or btrfs. Beyond that, an
fsyncleaves no trace a test can observe fromoutside the process, so no amount of ordinary testing would have noticed the
missing one. The
snapshotcrate, doing the same rename dance a fewdirectories away, gets it right and has done all along.
Both call sites now go through a single
Fs::persist_durably, which syncs thefile, renames it, and syncs the root. Making it one method rather than two
fixes is the point: the invariant is easy to forget, and the next segment
installation added to this repo gets it for free. It takes a
SegmentFilerather than any path, because it syncs the repository root and nothing else --
installing a file outside that directory has to say so explicitly, rather than
silently syncing the wrong one.
sync_dir, mirroringsnapshot'sFileOrDirPath::sync_all, includingits no-op on Windows, where opening a directory as a file is an error.
sync_allon the compressed segment's contents, which wasabsent independently of the directory problem.
API and ABI breaking changes
None.
Expected complexity level and risk
fsyncs on two cold paths — one per segment rotation, so onceper 1 GiB of log by default, and one per segment compression. Both paths
already
fsynca file and perform a rename, so the added cost is noiseagainst what they do anyway.
Testing
cargo test -p spacetimedb-commitlog: 67 unit + 11 integration testspass.
cargo clippy -p spacetimedb-commitlog --all-targetsclean.the bug survived so long. An
fsynchas no effect that is observablewithout a crash, so a test can only assert that the call was made --
a restatement of the line it is testing -- and demonstrating the actual
property needs crash injection (
dm-log-writes, or anLD_PRELOADthat swallows
fsync) which this crate has no harness for. What guardsthe invariant instead is structural:
.persist(now appears exactlyonce in the crate, inside
persist_durably, whose doc comment spellsout both failure modes and whose
SegmentFileparameter keeps thedestination inside the directory it syncs. Please review that funnel
rather than look for a test. The added
sync_allon the compressedfile's contents rests on review for the same reason.