core: localfs-contract-doc by fizzy-macos[bot] · Pull Request #872 · fizzyedit/fizzy

fizzy-macos · 2026-10-26T19:58:36Z

Part of fizzyedit/work#298

Goal

Make the opening contract text of core/LocalFs.zig (and the same stale claim in core/FileTable.zig) match the code: listings are pending, not synchronous.

What changed and why

Comment-only. LocalFs now says reads and listings run on the Io pool and land via pump/wake; FileTable only waits inline_wait_ns so small folders still answer at once. Follow-up of PR #811 (linux/codex F1).

How it was verified

No behaviour change, so no test can fail without it. scripts/check-fmt.sh and the build gates run by agent-finish.

Not done / follow-ups

None.

Changes (2 files, +12/-8)

 core/FileTable.zig |  5 +++--
 core/LocalFs.zig   | 15 +++++++++------
 2 files changed, 12 insertions(+), 8 deletions(-)

Gates: 6 of 6 passed

`scripts/check-fmt.sh` (exit 0)

check-fmt: listing tracked files
check-fmt: checking 535 files

`scripts/zb build --summary all` (exit 0)

... (earlier output omitted)
|     +- compile lib tree-sitter debug native (reused)
|     +- compile lib freetype debug native (reused)
|     +- compile lib tree-sitter debug native (reused)
|     +- options (reused)
|     +- options (reused)
|     +- translate-c dvui-c cached
|     |  +- compile exe translate-c debug native (+21 more reused dependencies)
|     +- options cached
|     +- options cached
+- install text cached
|  +- compile lib text debug native cached 77ms MaxRSS:31M
|     +- WriteFile plugin_root.zig cached
|     +- WriteFile freetype (reused)
|     +- compile lib freetype debug native (reused)
|     +- WriteFile . (reused)
|     +- compile lib tree-sitter debug native (reused)
|     +- compile lib freetype debug native (reused)
|     +- compile lib tree-sitter debug native (reused)
|     +- options (reused)
|     +- translate-c dvui-c (+1 more reused dependencies)
|     +- options (reused)
|     +- options (reused)
+- install markdown cached
|  +- compile lib markdown debug native cached 78ms MaxRSS:31M
|     +- WriteFile plugin_root.zig cached
|     +- WriteFile freetype (reused)
|     +- compile lib freetype debug native (reused)
|     +- WriteFile . (reused)
|     +- compile lib tree-sitter debug native (reused)
|     +- compile lib freetype debug native (reused)
|     +- compile lib tree-sitter debug native (reused)
|     +- options (reused)
|     +- translate-c dvui-c (+1 more reused dependencies)
|     +- options (reused)
|     +- options (reused)
|     +- translate-c (reused)
+- install image cached
   +- compile lib image debug native cached 77ms MaxRSS:31M
      +- WriteFile plugin_root.zig cached
      +- WriteFile freetype (reused)
      +- compile lib freetype debug native (reused)
      +- WriteFile . (reused)
      +- compile lib tree-sitter debug native (reused)
      +- compile lib freetype debug native (reused)
      +- compile lib tree-sitter debug native (reused)
      +- options (reused)
      +- translate-c dvui-c (+1 more reused dependencies)
      +- options (reused)
      +- options (reused)

`scripts/zb build test --summary all` (exit 0)

... (earlier output omitted)
      +- WriteFile freetype cached
      +- compile lib freetype debug native cached 264ms MaxRSS:31M
      +- WriteFile . cached
      +- compile lib tree-sitter debug native cached 178ms MaxRSS:30M
      +- compile lib freetype debug native (reused)
      +- compile lib tree-sitter debug native (reused)
      +- translate-c dvui-c cached
      |  +- compile exe translate-c debug native cached 88ms MaxRSS:31M
      |     +- options cached
      |     +- options cached
      |     +- options cached
      |     +- run exe generate-def (aarch64.zig) cached
      |     |  +- compile exe generate-def debug native cached 182ms MaxRSS:31M
      |     +- run exe generate-def (amdgcn.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (arm.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (bpf.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (common.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (hexagon.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (loongarch.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (mips.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (neon.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (nvptx.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (powerpc.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (riscv.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (s390x.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (ve.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (wasm.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (x86_64.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (x86.zig) cached
      |     |  +- compile exe generate-def debug native (reused)
      |     +- run exe generate-def (xcore.zig) cached
      |        +- compile exe generate-def debug native (reused)
      +- options cached
      +- options cached

`scripts/zb build test-integration --summary all` (exit 0)

... (earlier output omitted)
|     +- options (reused)
|     +- options (reused)
+- run test fizzy-glass-tests 6 pass (6 total) 260ms MaxRSS:3M
|  +- compile test fizzy-glass-tests debug native success 4s MaxRSS:316M
|     +- WriteFile freetype (reused)
|     +- compile lib freetype debug native (reused)
|     +- WriteFile . (reused)
|     +- compile lib tree-sitter debug native (reused)
|     +- compile lib freetype debug native (reused)
|     +- compile lib tree-sitter debug native (reused)
|     +- translate-c dvui-c (+1 more reused dependencies)
|     +- options (reused)
|     +- options (reused)
+- run test fizzy-plugin-loader-tests 2 pass (2 total) 183ms MaxRSS:3M
|  +- compile test fizzy-plugin-loader-tests debug native success 6s MaxRSS:367M
|     +- WriteFile freetype (reused)
|     +- compile lib freetype debug native (reused)
|     +- WriteFile . (reused)
|     +- compile lib tree-sitter debug native (reused)
|     +- compile lib freetype debug native (reused)
|     +- compile lib tree-sitter debug native (reused)
|     +- translate-c dvui-c (+1 more reused dependencies)
|     +- options (reused)
|     +- options (reused)
+- run test fizzy-text-plugin-tests 101 pass (101 total) 1s MaxRSS:24M
|  +- compile test fizzy-text-plugin-tests debug native success 10s MaxRSS:730M
|     +- options (reused)
|     +- WriteFile freetype (reused)
|     +- compile lib freetype debug native (reused)
|     +- WriteFile . (reused)
|     +- compile lib tree-sitter debug native (reused)
|     +- compile lib freetype debug native (reused)
|     +- compile lib tree-sitter debug native (reused)
|     +- translate-c dvui-c (+1 more reused dependencies)
|     +- options (reused)
|     +- options (reused)
+- run test fizzy-workbench-plugin-tests 1 pass (1 total) 183ms MaxRSS:3M
   +- compile test fizzy-workbench-plugin-tests debug native success 10s MaxRSS:314M
      +- options (reused)
      +- options (reused)
      +- WriteFile freetype (reused)
      +- compile lib freetype debug native (reused)
      +- WriteFile . (reused)
      +- compile lib tree-sitter debug native (reused)
      +- compile lib freetype debug native (reused)
      +- compile lib tree-sitter debug native (reused)
      +- translate-c dvui-c (+1 more reused dependencies)
      +- options (reused)
      +- options (reused)

`scripts/zb build check-web --summary all` (exit 0)

... (earlier output omitted)
|  |     +- run exe generate-def (amdgcn.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (arm.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (bpf.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (common.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (hexagon.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (loongarch.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (mips.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (neon.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (nvptx.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (powerpc.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (riscv.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (s390x.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (ve.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (wasm.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (x86_64.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (x86.zig) cached
|  |     |  +- compile exe generate-def debug native (reused)
|  |     +- run exe generate-def (xcore.zig) cached
|  |        +- compile exe generate-def debug native (reused)
|  +- options cached
|  +- options success
|  +- options cached
|  +- options cached
|  +- options cached
|  +- options cached
|  +- options cached
|  +- options cached
|  +- options cached
|  +- options cached
|  +- translate-c success 73ms MaxRSS:31M
+- compile obj rehome-fixture-web debug wasm32-freestanding success 407ms MaxRSS:170M
   +- translate-c dvui-c (+1 more reused dependencies)
   +- options (reused)
   +- options (reused)

`scripts/zb build test-sdk-version --summary all` (exit 0)

... (earlier output omitted)
   +- WriteFile . cached
   +- compile lib tree-sitter debug native cached 43ms MaxRSS:30M
   +- compile lib freetype debug native (reused)
   +- compile lib tree-sitter debug native (reused)
   +- options cached
   +- options cached
   +- translate-c dvui-c cached
   |  +- compile exe translate-c debug native cached 41ms MaxRSS:31M
   |     +- options cached
   |     +- options cached
   |     +- options cached
   |     +- run exe generate-def (aarch64.zig) cached
   |     |  +- compile exe generate-def debug native cached 45ms MaxRSS:31M
   |     +- run exe generate-def (amdgcn.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (arm.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (bpf.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (common.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (hexagon.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (loongarch.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (mips.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (neon.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (nvptx.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (powerpc.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (riscv.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (s390x.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (ve.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (wasm.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (x86_64.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (x86.zig) cached
   |     |  +- compile exe generate-def debug native (reused)
   |     +- run exe generate-def (xcore.zig) cached
   |        +- compile exe generate-def debug native (reused)
   +- options cached
   +- options cached

The opening comments of LocalFs and FileTable promised synchronous listings that complete in the start call. Listings and reads run on the Io pool; callers handle a pending (null) listing and rely on wake/pump. Comment-only. Agent-Team: macos Worker: claude Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

fizzy-pm · 2026-10-26T20:00:05Z

PM note: how this PR will be handled

What it is for: core: localfs-contract-doc
Issue #298: docs: LocalFs opening comment says listings are synchronous
Done when (from the issue): draft PR with the comment matching the code; then stop.

Rules that apply: none special.
Reviews needed: 1, from any other team or kind.
Needs the maintainer's explicit yes before merge: no

Things to watch (checked by rule):

the body names its work issue (Part of fizzyedit/work#N)
size within 800 lines outside tests and docs (20)
a gates section with what was run

What happens next:

Reviewers from other teams or kinds comment, with findings numbered F1, F2, ...
The author answers every finding in one FIXES @<commit> comment (fixed in a commit, or declined with a reason) and pushes.
Reviewers re-review the new commit on their own.
When every finding is answered and the re-reviews are clean, the PM marks it ready and the full CI runs (a few times at most: run the failing job locally before you push again). Only when CI passes does the PM look, and the PM gives the final okay.

A living status comment below is kept current. Nothing here is a merge decision.

fizzy-pm · 2026-10-26T20:00:06Z

Where this PR stands

Stage: Done: approved
Next: Waiting for the merge queue

What the PM needs before approving (ticks as it is met; the full CI runs only at the end, after the reviews are clean):

The body names its basis (Part of fizzyedit/work#N or a plan step)
Within the size limit: 20 of 800 lines outside tests and docs
The body shows which gates the author ran
No open findings at this commit
Every earlier finding was answered in a FIXES comment
Clean reviews at this commit from 1 kind: linux/agy (has 1)
Marked ready, which starts the full CI (the PM does this the moment the items above are met)
The full CI passes at this commit (CI is green)
The PM's final okay (pm-approval)

Reviews at the current commit (7a7fad5):

Reviewer	Verdict	Findings
linux/agy	clean	none

Updated 2026-10-26 23:13 UTC by the PM. This comment is edited in place.

fizzy-linux Bot added reviewing:linux-agy a linux/agy review is running and removed reviewing:linux-agy a linux/agy review is running labels Oct 26, 2026

fizzy-pm Bot marked this pull request as ready for review October 26, 2026 20:33

fizzy-pm Bot added this pull request to the merge queue Oct 26, 2026

Merged via the queue into main with commit e295633 Oct 26, 2026
14 checks passed

fizzy-pm Bot deleted the core/localfs-contract-doc branch October 26, 2026 23:12

fizzy-macos Bot mentioned this pull request Oct 26, 2026

core: localfs-sync-doc #887

Merged

Navigation Menu

Repository navigation

core: localfs-contract-doc - #872

core: localfs-contract-doc#872
fizzy-pm[bot] merged 1 commit into
mainfrom
core/localfs-contract-doc

fizzy-macos Bot commented Oct 26, 2026 •

edited

Loading

Uh oh!

fizzy-pm Bot commented Oct 26, 2026

Uh oh!

fizzy-pm Bot commented Oct 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

Conversation

fizzy-macos Bot commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Goal

What changed and why

How it was verified

Not done / follow-ups

scripts/check-fmt.sh (exit 0)

scripts/zb build --summary all (exit 0)

scripts/zb build test --summary all (exit 0)

scripts/zb build test-integration --summary all (exit 0)

scripts/zb build check-web --summary all (exit 0)

scripts/zb build test-sdk-version --summary all (exit 0)

Uh oh!

fizzy-pm Bot commented Oct 26, 2026

PM note: how this PR will be handled

Uh oh!

fizzy-pm Bot commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Where this PR stands

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

fizzy-macos Bot commented Oct 26, 2026 •

edited

Loading

`scripts/check-fmt.sh` (exit 0)

`scripts/zb build --summary all` (exit 0)

`scripts/zb build test --summary all` (exit 0)

`scripts/zb build test-integration --summary all` (exit 0)

`scripts/zb build check-web --summary all` (exit 0)

`scripts/zb build test-sdk-version --summary all` (exit 0)

fizzy-pm Bot commented Oct 26, 2026 •

edited

Loading