Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
175 commits
Select commit Hold shift + click to select a range
f4659a1
feat(gc): schema, markers and logical removals (layerfs-project#42, #…
mengmengmengqiang Nov 15, 2026
6620be3
feat(gc): admission and reachability/closure (layerfs-project#43, #48)
mengmengmengqiang Nov 15, 2026
7c99e7d
feat(gc): SQLite and PostgreSQL compaction (layerfs-project#49, #50)
mengmengmengqiang Nov 15, 2026
c551cdd
feat(gc): report/status, API/SDK/CLI, qualification (layerfs-project#…
mengmengmengqiang Nov 15, 2026
d0ee8fc
chore(gc): rebase onto upstream expected-base publish (#692/#693)
mengmengmengqiang Nov 16, 2026
d03c31b
test(publish): keep upstream publish_expected_base coverage
mengmengmengqiang Nov 16, 2026
d26ae54
fix(publish): keep UpToDate/NoChanges behind the stale-base guard (#693)
mengmengmengqiang Nov 16, 2026
88c8a3d
base-snap: main tree 329a20be as common ancestor for fix711 merges
mengmengmengqiang Nov 16, 2026
91635f5
fix711-contract: exported tree as merge branch
mengmengmengqiang Nov 16, 2026
707e123
fix711-pg: exported tree as merge branch
mengmengmengqiang Nov 16, 2026
86ce13a
fix711-life: exported tree as merge branch
mengmengmengqiang Nov 16, 2026
2a502ca
fix711-rm: exported tree as merge branch
mengmengmengqiang Nov 16, 2026
301c56f
fix711-sqlite: exported tree as merge branch
mengmengmengqiang Nov 16, 2026
c8dede7
fix711-api: exported tree as merge branch
mengmengmengqiang Nov 16, 2026
96fabe7
fix711-perf: exported tree as merge branch
mengmengmengqiang Nov 16, 2026
a36f7a4
fix711-hyg: exported tree as merge branch
mengmengmengqiang Nov 16, 2026
6f2f4c1
integ: anchor base-snap (main 329a20be) behind PR head #711
Nov 16, 2026
8b92316
merge fix711-contract: GC history contract fixes (T2/T3)
Nov 16, 2026
d58005f
merge fix711-pg: PostgreSQL advisory locks, compaction and ownership …
Nov 16, 2026
bca8597
merge fix711-life: Store lifecycle, admission and compaction fixes
Nov 16, 2026
7d31384
merge fix711-rm: Branch, project and path removal fixes
Nov 16, 2026
2788f8f
merge fix711-sqlite: SQLite compaction lifecycle, report and repair f…
Nov 16, 2026
5f46293
merge fix711-api: Store API, MCP and report fixes
Nov 16, 2026
efa91bd
merge fix711-perf: object admission and compaction performance fixes
Nov 16, 2026
ed886a7
merge fix711-hyg: documentation and workspace hygiene
Nov 16, 2026
47a1e00
fixup(integ): drop duplicate pg replica test helper and unused db_err…
Nov 16, 2026
3523db4
fixup(tests): align default suites with the merged fixes
Nov 16, 2026
2386c35
fixup(tests): use a catalog-width Store scope id in the PG uncertain-…
Nov 16, 2026
636d15a
merge layerfs_v2_0_0 e7d99bc1e: #712 monitoring over the GC branch
Nov 16, 2026
ab24dbc
fix711-spec: exported tree as merge branch
Nov 16, 2026
6a0537f
fix711-bench: exported tree as merge branch
Nov 16, 2026
78920e4
fix711-pgtest: exported tree as merge branch
Nov 16, 2026
79e6bcc
fix711-perf2: exported tree as merge branch
Nov 16, 2026
564217c
merge fix711-spec: #42 decisions, runbook and T12.3a/docs references
Nov 16, 2026
b0e62a0
merge fix711-bench: capacity bench example, fixtures and CI script
Nov 16, 2026
c8b70d6
merge fix711-pgtest: PostgreSQL acceptance, doctor and attribution te…
Nov 16, 2026
261f124
merge fix711-perf2: object admission, compaction and export performance
Nov 16, 2026
7223b8d
refactor(gc): split SQLite/PostgreSQL compaction into phase modules
Nov 16, 2026
11c1896
fix(cli): honor LAYERFS_TEST_TMPDIR in process-kill tests and expect …
mengmengmengqiang Nov 16, 2026
4f9b3f0
impl-freshcopy: exported tree as merge branch
Nov 16, 2026
8cba10f
fix711-none: exported tree as merge branch
Nov 16, 2026
f2ed578
fix711-report2: exported tree as merge branch
Nov 16, 2026
14beddb
fix711-conc: exported tree as merge branch
Nov 16, 2026
ab6079d
fix711-remote: exported tree as merge branch
Nov 16, 2026
09f750a
fix711-docs: exported tree as merge branch
Nov 16, 2026
8e94b4d
fix711-bench3: exported tree as merge branch
Nov 16, 2026
0028527
fix711-install: exported tree as merge branch
Nov 16, 2026
0b41b16
merge impl-freshcopy: fresh-copy SQLite rebuild (D2) and the 10 GB ca…
Nov 16, 2026
687612b
merge fix711-none: rollback-only none compaction (D3)
Nov 16, 2026
1cb3751
merge fix711-report2: report semantics (canonical logicalDiscarded, s…
Nov 16, 2026
f52e932
merge fix711-conc: admission on open descriptions and epoch-row remov…
Nov 16, 2026
ec1c018
merge fix711-remote: local-only SQLite compaction (D5) and markBytes …
Nov 16, 2026
0f5b1b4
merge fix711-docs: A8 section 11 report amendment and the 82-call docs
Nov 16, 2026
b315ac9
merge fix711-bench3: fixture shape, cold-cache method and 3-run variance
Nov 16, 2026
c80de3b
merge fix711-install: install-only lane prototype and the G7 deferred…
Nov 16, 2026
2c84702
fixup(docs): runbook names D5 with the other SQLite deviations
Nov 16, 2026
db5f7ac
fixup(fmt): rustfmt the fresh-copy build and matrix report text
Nov 16, 2026
15a872a
fixup(boundary): move the report/receipt unit checks out of product s…
Nov 16, 2026
5e73795
merge layerfs_v2_0_0 4a8efe63b3: machine.space, per-exec cgroups and …
Nov 16, 2026
6daca0b
fixup(docs): keep the machine.space manual rows and the 83-call counts
Nov 16, 2026
89fdbde
fixup(docs): the SDK inventory and the calls module name 83 calls
Nov 16, 2026
e824e8a
test(pg): count live Branches after soft removal in the concurrent-re…
mengmengmengqiang Nov 16, 2026
5be3f41
fix711-docs4: exported tree as merge branch
Nov 16, 2026
8b2cf77
fix711-clippy4: exported tree as merge branch
Nov 16, 2026
a9b1042
fix711-opencost4: exported tree as merge branch
Nov 16, 2026
cf6e107
merge fix711-docs4: the SDK/skills inventory and the versioned refere…
Nov 16, 2026
dcacc2d
merge fix711-clippy4: workspace clippy warnings under -D warnings
Nov 16, 2026
9ab2869
merge fix711-opencost4: postgresql_open_cost takes a URL or keyword c…
Nov 16, 2026
5411baa
fixr1-42: exported tree as merge branch
Nov 16, 2026
b798a38
fixr1-43: exported tree as merge branch
Nov 16, 2026
6a29ecb
fixr1-44: exported tree as merge branch
Nov 16, 2026
0ec9742
fixr1-45: exported tree as merge branch
Nov 16, 2026
b4d67c9
fixr1-47: exported tree as merge branch
Nov 16, 2026
3a62729
fixr1-48: exported tree as merge branch
Nov 16, 2026
ff43842
fixr1-49: exported tree as merge branch
Nov 16, 2026
6d05e2f
fixr1-50: exported tree as merge branch
Nov 16, 2026
bb360f4
fixr1-51: exported tree as merge branch
Nov 16, 2026
4317fa8
fixr1-52: exported tree as merge branch
Nov 16, 2026
f5720d8
fixr1-pginit: exported tree as merge branch
Nov 16, 2026
cab2479
merge fixr1-42: capacity classification, §10 predicate, PG kept_node …
Nov 16, 2026
da8e19d
merge fixr1-43: the retire intent is visible inside the marker transa…
Nov 16, 2026
bf7fb3d
merge fixr1-44: §4.4 name comment, universal §4.2 statement guard, A9…
Nov 16, 2026
f2a5b87
merge fixr1-45: project-delete lane, admission signature and worker_p…
Nov 16, 2026
f273066
merge fixr1-47: resolve remove_file against the Store tree, symlink p…
Nov 16, 2026
e9ac198
merge fixr1-48: cap wire, PG mark snapshot, stamp/root cleanup, post-…
Nov 16, 2026
b1534fc
merge fixr1-49: settle keeps the op record until artifacts are gone
Nov 16, 2026
c75c2fc
merge fixr1-50: PostgreSQL compaction batching, F50-2..11
Nov 16, 2026
0f03b42
merge fixr1-51: name machine.space, rebuild call tables, store.status…
Nov 16, 2026
e2c1a99
merge fixr1-52: regenerate T12.3a report (8/30/16/6), cover AC-44/AC-…
Nov 16, 2026
b42ab42
merge fixr1-pginit: Phase C must not delete a live Init's working rows
Nov 16, 2026
06e965a
cargo fmt --all (merge reflow)
Nov 16, 2026
e629a52
fix(integration): split objects.rs impls under the boundary; pginit u…
Nov 16, 2026
43e72cf
test(pg): park Phase C on the batched signature delete, not the commi…
Nov 16, 2026
270998c
fixr2-43: exported tree as merge branch
Nov 17, 2026
e238710
fixr2-44: exported tree as merge branch
Nov 17, 2026
8f20720
fixr2-45: exported tree as merge branch
Nov 17, 2026
6d36cc2
fixr2-46: exported tree as merge branch
Nov 17, 2026
98e45d4
fixr2-47: exported tree as merge branch
Nov 17, 2026
1b7aae1
fixr2-49: exported tree as merge branch
Nov 17, 2026
5de0eaf
fixr2-50: exported tree as merge branch
Nov 17, 2026
ec6620a
fixr2-51: exported tree as merge branch
Nov 17, 2026
31faeb4
fixr2-52: exported tree as merge branch
Nov 17, 2026
5868fb3
merge fixr2-43: name Unknown GC detail and see live Init/merge
Nov 17, 2026
ebcf856
merge fixr2-44: #44/#45 round-2 read fence, retired backup heads, inl…
Nov 17, 2026
11f05dc
merge fixr2-45: project.delete round-2 refusals, inventory and 2.0 ma…
Nov 17, 2026
df5d31a
merge fixr2-46: mark and prune unreachable history in one write trans…
Nov 17, 2026
837e04a
merge fixr2-47: only-symlink strictness, lenient marker existence, pr…
Nov 17, 2026
157f62c
merge fixr2-49: sqlite compaction settle/install round-2
Nov 17, 2026
a956794
merge fixr2-50: PG compact cleanup/op/run and A8 columns; lost-COMMIT…
Nov 17, 2026
06621c7
merge fixr2-51: regenerate node typings, python stubs and coverage fr…
Nov 17, 2026
aaeed8f
merge fixr2-52: matrix/report/receipts/CI round-2 (F52R2-1..4, F48R2-1)
Nov 17, 2026
3b1aa01
fixup(#45): carry the fresh-call flag in Finish, keeping mark_and_fin…
Nov 17, 2026
ae0a4c4
merge the layerfs_v2_0_0 base dd4a2cc40f (#720/#725/#726)
Nov 17, 2026
d5cc150
fixup(#52): regenerate the T12.3a report from the merged test sources
Nov 17, 2026
61212f2
fixr3-43: exported tree as merge branch
Nov 17, 2026
05bf7e0
fixr3-44: exported tree as merge branch
Nov 17, 2026
a9cb4c3
fixr3-45: exported tree as merge branch
Nov 17, 2026
671eef2
fixr3-46: exported tree as merge branch
Nov 17, 2026
fe0f790
fixr3-49: exported tree as merge branch
Nov 17, 2026
ad56401
fixr3-51: exported tree as merge branch
Nov 17, 2026
d3b967d
fixr3-52: exported tree as merge branch
Nov 17, 2026
fee2ebc
merge fixr3-43: name the Store listing and shared-intent Unknown deta…
Nov 17, 2026
5ef2ce0
merge fixr3-44: qualify the one-statement PostgreSQL catalogue reads,…
Nov 17, 2026
636469b
merge fixr3-45: stale sidecar, marked retry, listing refusals, worker…
Nov 17, 2026
87418c8
merge fixr3-46: retract unreachable logical totals in remove_unreacha…
Nov 17, 2026
30da917
merge fixr3-49: returned-op marker, BusyOp detail, returned-run statu…
Nov 17, 2026
eddf753
merge fixr3-51: store.compact reports an in-process call as Busy; PG …
Nov 17, 2026
02dca44
merge fixr3-52: restore the frozen GC spec, correct round-3 docs and …
Nov 17, 2026
719b5b1
fixup(#51/#52): keep the frozen spec byte-identical to ed14ed53b; rec…
Nov 17, 2026
3dc3453
fix(integration): move the Round-3 source unit tests into test targets
Nov 17, 2026
a536f92
docs(#42): count A11 in the decisions header and the sign-off request
Nov 17, 2026
0242ff8
docs(#42): fix round-4 findings in gc-42 decisions (A11 test path, A8…
Nov 17, 2026
355ff7d
fix(#43): round-4 unknown/add/init fixes
Nov 17, 2026
21b4015
fix(#49): verify keeps quick_check separate; mmap the attached sealed…
Nov 17, 2026
3a747da
fix(#50): PG status/sync/physical_after round-4 fixes
Nov 17, 2026
057e1ff
docs(#52): round-4 matrix/receipts/CI fixes
Nov 17, 2026
dfdd055
merge fixr4-42: docs(#42): fix round-4 findings in gc-42 decisions (A…
Nov 17, 2026
3370046
merge fixr4-43: fix(#43): round-4 unknown/add/init fixes
Nov 17, 2026
bc811e9
merge fixr4-49: fix(#49): verify keeps quick_check separate; mmap the…
Nov 17, 2026
19679fd
merge fixr4-50: fix(#50): PG status/sync/physical_after round-4 fixes
Nov 17, 2026
7b58d4e
merge fixr4-52: docs(#52): round-4 matrix/receipts/CI fixes
Nov 17, 2026
b41ebab
merge the layerfs_v2_0_0 base 57423382f7 (#727)
Nov 17, 2026
6efec40
fix(integration): move the Round-4 source unit tests into test targets
Nov 17, 2026
983cbb4
fix(integration): clippy format_collect in fixr4-50's PostgreSQL stat…
Nov 17, 2026
66ff210
fix(integration): regenerate the T12.3a report on the merged tree
Nov 17, 2026
b357463
fix(integration): keep fixr4-49's source-window check a runtime asser…
Nov 17, 2026
f48dd2c
docs(#42): round-5 findings — A12 rebuild-intent reading, store.push …
Nov 17, 2026
bc4f5c8
fix(#43): round-5 — name the project on init and delete Unknown refusals
Nov 17, 2026
b2d0757
fix(#49): make a Store replacement between seal and install a Conflict
Nov 17, 2026
d88d4b3
fix(#50): round-5 — legacy standby list, reader holder, Phase M statu…
Nov 17, 2026
1494a9e
fix(mcp): round-5 — admin profile lists 76 tools, not 82
Nov 17, 2026
780421d
docs(#52): round-5 — seven gc_op columns, receipt vintage in §13/AC-5…
Nov 17, 2026
dba16b1
merge fixr5-42: round-5 decisions, A12, store.push, seven gc_op colum…
Nov 17, 2026
cca723a
merge fixr5-43: round-5 unknown/init and delete refusals
Nov 17, 2026
9385374
merge fixr5-49: Store replacement between seal and install is Conflict
Nov 17, 2026
5654607
merge fixr5-50: round-5 standby, holder, status and A8
Nov 17, 2026
d05fe29
merge fixr5-51: MCP admin profile tool count test
Nov 17, 2026
c363288
merge fixr5-52: round-5 seven columns, receipt vintage and quick-lane…
Nov 17, 2026
c072973
fixup(boundary): keep the project-delete module under the 999-line limit
Nov 17, 2026
7702bb2
fixup(report): regenerate the T12.3a report on the merged Round-5 tree
Nov 17, 2026
52823ff
docs(#42): round-6 — the GC Busy list names store.pull and backup.res…
Nov 17, 2026
a920b98
fix(#43): round-6 — a retained Uncertain history cause keeps the Init…
Nov 17, 2026
b971061
fix(#50): round-6 — standby tokens parse without spacing, and a prova…
Nov 17, 2026
ca5a952
fix(#41): round-6 — an installed leftover answers its recorded Rebuil…
Nov 17, 2026
91dd691
merge fixr6-42: round-6 docs for the Busy list and the mark's Store op
Nov 17, 2026
e61da64
merge fixr6-43: round-6 Init Uncertain history cause keeps Unknown
Nov 17, 2026
e5fdf82
merge fixr6-50: round-6 standby spacing and dead intent owner
Nov 17, 2026
fbd0749
merge fixr6-41: round-6 installed leftover answers its recorded report
Nov 17, 2026
e958654
merge base layerfs_v2_0_0 39a25138: home family, machine platforms, d…
Nov 17, 2026
b78c076
fixup(integration): format the R6 trees, hold the Init acquisition un…
Nov 17, 2026
b28e74a
test(node): coverage.mjs renames an argument of a call that has one
Nov 17, 2026
99d90eb
fix(gc-bench): json_host() stops doubling the quotes json_string() ad…
Nov 17, 2026
fbf9864
merge fixr6-benchjson: gc_bench host JSON quotes and its two example …
Nov 17, 2026
c91c8f0
test(cli): the process-kill arms answer the recorded Rebuild report
Nov 17, 2026
53dac04
test(api): a scoped fork composes an absent in-namespace Branch and t…
Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
23 changes: 13 additions & 10 deletions .agents/skills/layerfs-js-sdk/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -285,20 +285,23 @@ For Rust projects, follow the [Cargo workflow](references/rules/cargo.md).

## Calls

61 calls in nine families. Each family's page has arguments, results, refusals
85 calls in twelve families. Each family's page has arguments, results, refusals
and examples.

| Family | Calls |
| --- | --- |
| [project](references/methods/project.md) | `init(project, folder, { timeout, on_progress })`, `list(store?, { page_size, page_pos })`, `get(project)`, `export(project, destination, { branch, on_progress })`, `remove(project)` |
| [branch](references/methods/branch.md) | `list(project)`, `get(project, branch)`, `fork(project, name, from_branch, from_commit?)`, `merge(project, name, a, b, { message, units })`, `publish(project, branch, commit?)`, `diff(project, from_branch, to_branch, { paths_only, page_size, page_pos, cursor })` |
| [commit](references/methods/commit.md) | `list(project, branch)`, `get(project, branch, commit)`, `diff(project, from_commit, to_commit, { paths_only, … })` |
| [file](references/methods/file.md) | reads `read`, `stat`, `list`, `glob`, `grep`, `blame`, `diff`; writes `write`, `edit`, `rm`, `mkdir`, `mv`, `cp`, `apply` |
| [sandbox](references/methods/sandbox.md) | `create(project, name, machine?, { image })`, `list(project?, { page_size, page_pos })`, `get(name, { page_size, page_pos })`, `close(name, { force })` |
| [workspace](references/methods/workspace.md) | `mount(sandbox, branch, { name })`, `exec(ws, command, { message, stream, stdout, stderr })`, `commit(ws, { message, force })`, `unmount(ws, { discard, force })`, `status(ws)` |
| [machine](references/methods/machine.md) | `list`, `platforms`, `get`, `status`, `start`, `stop`, `create`, `remove`, `update` |
| [store](references/methods/store.md) | `list`, `get`, `status`, `create`, `connect`, `push`, `pull`, `remove`, `disconnect` |
| [backup](references/methods/backup.md) | `connect`, `disconnect`, `list`, `create`, `restore` |
| home (admin) | `init()`, `get()`: create or convert this home, and read the bundle and daemon this build would use; no skill page yet, see `docs/architecture/api/sdk/home.md` in the repository |
| [project](references/methods/project.md) | `init(project, folder, { timeout, on_progress })`, `list(store?, { page_size, page_pos })`, `get(project)`, `stats(project, branch?, commit?)`, `export(project, destination, { branch, on_progress })`, `delete(project)`, `remove_file(project, path)` |
| [branch](references/methods/branch.md) | `list(project, { page_size, page_pos, page })`, `get(project, branch)`, `commits(project, branch, { page, page_size, at_commit, include_storage })`, `get_commit(project, branch, commit)`, `fork(project, name, from_branch, from_commit?)`, `merge(project, name, a, b, { message, units })`, `publish(project, branch, commit?)`, `diff(project, from_branch, to_branch, { paths_only, page_size, page_pos, cursor, page, from_commit, to_commit, path_prefix, include_attribution, continuation })`, `remove(project, branch)` |
| [commit](references/methods/commit.md) | `list(project, branch, { page_size, page_pos })`, `get(project, branch, commit)`, `diff(project, from_commit, to_commit, { paths_only, page_size, page_pos, cursor })` |
| [file](references/methods/file.md) | reads `read(project, branch, path, commit?, { start_line, end_line })`, `stat(project, branch, path, commit?)`, `list(project, branch, path, commit?, { page_size, page, page_pos })`, `glob(project, branch, path, pattern, commit?, { page_size, page, page_pos })`, `grep(project, branch, path, pattern, commit?, { page_size, page, page_pos })`, `revision(project, branch, path, { at_commit, traversal, page, page_size, continuation })`, `blame(project, branch, path, commit?, { from_line, line_count })`, `diff(project, left_branch, left_path, right_branch, right_path, { left_commit, right_commit, include_attribution, allow_missing, page, page_size })`; writes `write(project, branch, path, content, { message, mode })`, `edit(project, branch, path, { old, new, message })`, `rm(project, branch, path, { message })`, `mkdir(project, branch, path, { message, mode })`, `mv(project, branch, from_path, to_path, { message })`, `cp(project, branch, from_path, to_path, { message })`, `apply(project, branch, changes, { message })` |
| [sandbox](references/methods/sandbox.md) | `create(project, name, machine?, { image, on_progress })`, `list(project?, { page_size, page_pos })`, `get(name, { page_size, page_pos })`, `close(name, { force })`, `files(sandbox, path?, { depth, cursor, limit, offset, length })` |
| [workspace](references/methods/workspace.md) | `mount(sandbox, branch, { name })`, `exec(ws, command, { message, stream, stdout, stderr, exec_id, on_progress })`, `exec_cancel(ws, exec_id, { grace_ms })`, `commit(ws, { message, force })`, `unmount(ws, { discard, force })`, `status(ws)` |
| [machine](references/methods/machine.md) | `list()`, `platforms()`, `get(name)`, `images(name)`, `load(name, image, { on_progress })`, `prune(name, image?, { unused })`, `status(name)`, `stats(machine)`, `space(machine)`, `files(machine, path?, { depth, cursor, limit, offset, length })`, `start(name, { on_progress })`, `stop(name, { force })`, `create(name, platform, { cpus, memory, disk, image, os_image, on_progress })`, `remove(name)`, `update(name, { cpus, memory, image, docker, wsl, daemon })` |
| [store](references/methods/store.md) | `list()`, `get(name)`, `status(name)`, `stats(name)`, `create(name)`, `connect(name, url, { password, synchronous_commit })`, `attach(name, machine, { url, password })`, `detach(name, machine)`, `push(name, machine, { on_progress })`, `pull(name, { on_progress })`, `remove(name)`, `compact(name)`, `disconnect(name)` |
| [backup](references/methods/backup.md) | `connect(name, url, { key, region, part_size })`, `disconnect(name)`, `list(bucket?)`, `create(store, bucket, file?, { on_progress })`, `restore(store, bucket, file?, { on_progress })` |
| [logs](references/methods/logs.md) | `list({ op, project, client, tag, outcome, since, cursor, limit })`, `reset()`, `machine(machine, { cursor, before, limit })`, `sandbox(sandbox, { cursor, before, limit })` |
| [doctor](references/methods/doctor.md) | `fix(id)` |

One top-level function is outside the families: `doctor({ home })` (shell
`layerfs doctor [--text]`) reports what is wrong in the home as `{ ok,
Expand Down
72 changes: 67 additions & 5 deletions .agents/skills/layerfs-js-sdk/references/methods/branch.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,15 @@
> command in a private home on 2026-11-02; ids are shortened.

```js
branch.list(project, { page_size, page_pos })
branch.list(project, { page_size, page_pos, page })
branch.get(project, branch)
branch.commits(project, branch, { page, page_size, at_commit, include_storage })
branch.get_commit(project, branch, commit)
branch.fork(project, name, from_branch, from_commit?)
branch.merge(project, name, a, b, { message, units })
branch.publish(project, branch, commit?)
branch.diff(project, from_branch, to_branch, { paths_only, page_size, page_pos, cursor })
branch.publish(project, branch, commit?, { expected_base, expected_head, force })
branch.diff(project, from_branch, to_branch, { paths_only, page_size, page_pos, cursor, page, from_commit, to_commit, path_prefix, include_attribution, continuation })
branch.remove(project, branch)
```

`main` is not a Branch: it is the project's published line of Layers. It shows
Expand All @@ -19,7 +22,7 @@ in `branch.list`, you can read it and fork from it, and it changes only through

## `branch.list` and `branch.get`

`branch.list(project, { page_size, page_pos })`, `branch.get(project, branch)`
`branch.list(project, { page_size, page_pos, page })`, `branch.get(project, branch)`

```bash
layerfs branch list shop/api --text
Expand All @@ -36,6 +39,46 @@ Layer underneath; `head` is the newest Commit, `null` before the first one.
`branch.get` returns one item, or `NoSuchBranch` (`no Branch <name>`;
`NotFound` before `88b033cfa9`).

## `branch.commits`

`branch.commits(project, branch, { page, page_size, at_commit, include_storage })`

Saved side-Branch Commits, or `main`'s publication Layers, newest first from
an immutable start. `page` and `page_size` number the pages; `at_commit` (a
full saved id) starts from another point; `include_storage` adds each row's
`new_canonical`, `new_stored` and `new_metadata` (`null` for a main Layer,
which performs no Save).

```json
{"branch":"work","at_commit":{"id":"12ad2061f04f…","kind":"Commit","branch":"work","root":"f55fa9660a73…"},
"items":[{"id":"12ad2061f04f…","parent":"12c7ef811a49…","base":"3275838904b6…",
"time":1793574061147,"via":"fs","message":"add retries","message_truncated":false,
"details_omitted":true}],
"page":1,"page_size":50,"has_more":false,"scan":{"complete":true,"examined":1,"reason":null}}
```

Each item carries a full `ref: { id, kind, branch, root }`; `branch.get_commit`
answers the rest. A side Branch follows its first-parent chain; `main` follows
publication Layer parents, and a Layer's `time` is `null` with
`time_status: "unavailable"` (its `source_time` is the source Commit's own
time). A side Branch with no Commit has no rows.

## `branch.get_commit`

`branch.get_commit(project, branch, commit)`

Full details of one saved Commit or `main` publication Layer admitted by the
Branch. `commit` is the complete id: no prefix matching (unlike `commit.get`).

The answer keeps the recorded metadata and adds typed `ref`, `parent_ref`,
`second_parent_ref`, `base_layer`, `source_commit_ref`, `source_time` and
`time_status`; a relationship that does not apply is null. For a publication,
`parent` is the previous Layer and `source_commit` what was published. `main`
admits its Layer lineage; a side Branch admits its first-parent and base
lineage and its own recorded Commits, displaced ones included. The context
lookup visits at most 10,000 records, and the whole answer, merge-unit
reports included, must fit 48 KiB: either limit is `Capacity`.

## `branch.fork`

`branch.fork(project, name, from_branch, from_commit?)`
Expand Down Expand Up @@ -185,5 +228,24 @@ result is the same shape as [`commit.diff`](commit.md#commitdiff):
layerfs branch diff shop/api main work --paths-only
```

`paths_only` leaves out each item's `hunks` (they come back `null`). Resume a
`paths_only` leaves out each item's `hunks` (they come back `null`). `page`,
`page_size` and `page_pos` page the items; `from_commit` and `to_commit` pin
the compared versions; `path_prefix` keeps one subtree; `include_attribution`
adds each path's last writers; `continuation` resumes a saved query. Resume a
long diff with `cursor: next_cursor`. Refused under a folder scope.

## `branch.remove`

`branch.remove(project, branch)`

Retires one Branch in its Store. Its row is hidden from listings and name
resolution; fork, merge, publish and mount of it are refused, and its Commits
and objects stay until a later `store.compact`. `main` is `ReservedName`.

```json
{"kind":"Removed","project":"shop/api","branch":"work","removed_ms":1793574061147}
```

A repeat is `NoSuchBranch` (only `project.delete` is retry-idempotent); a
concurrent remove is `Busy` with phase `"retire"`. `MountsActive` while a
mount of the Branch is live.
32 changes: 32 additions & 0 deletions .agents/skills/layerfs-js-sdk/references/methods/doctor.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# doctor calls

> **Status:** Current general guide for LayerFS 2.0 (#533). Part of the
> `layerfs-js-sdk` skill. `doctor` is the report function, outside the table;
> `doctor.fix` is the family's one call. A folder scope refuses it.

```js
doctor.fix(id)
```

`layerfs doctor` reports what is wrong in the home as
`{ ok, findings: [{ severity, entity: { kind, name }, message, fix }] }`, each
finding naming the call that fixes it. It changes nothing and starts no
machine. `doctor.fix(id)` removes the one leftover `id` names.

## `doctor.fix`

`doctor.fix(id)`: `id` is a leftover's `<machine>:<kind>:<name>` from the
report; it never holds a path. One attempt: nothing is retried, and nothing
but the one entry is removed. The kinds are `run-folder`, `empty-root`,
`init-copy`, `backup-staging`, `image-tmp` and `image-part`.

```json
{"id":"native:run-folder:web","machine":"native","kind":"run-folder",
"path":"/Users/me/.layerfs/machine/native/run/web","removed":true,"bytes":11833344}
```

`bytes` is what the removed files held, `null` for a folder copy and an image
temporary. Errors: `NotFound` (no leftover has that id now), `InUse` (the
kind's guard does not hold; nothing removed), `InvalidInput` (a kind that is
only reported, a missing `id`, a folder scope), `Unavailable` (the machine is
stopped), `Unknown` (the worker's answer was lost), `Failed`.
40 changes: 35 additions & 5 deletions .agents/skills/layerfs-js-sdk/references/methods/file.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,12 @@
// reads: the Branch's head, or the Commit given
file.read(project, branch, path, commit?, { start_line, end_line })
file.stat(project, branch, path, commit?)
file.list(project, branch, path, commit?, { page_size, page_pos })
file.glob(project, branch, path, pattern, commit?, { page_size, page_pos })
file.grep(project, branch, path, pattern, commit?, { page_size, page_pos })
file.blame(project, branch, path, commit?, { from_line })
file.diff(project, left_branch, left_path, right_branch, right_path, { left_commit, right_commit })
file.list(project, branch, path, commit?, { page_size, page, page_pos })
file.glob(project, branch, path, pattern, commit?, { page_size, page, page_pos })
file.grep(project, branch, path, pattern, commit?, { page_size, page, page_pos })
file.revision(project, branch, path, { at_commit, traversal, page, page_size, continuation })
file.blame(project, branch, path, commit?, { from_line, line_count })
file.diff(project, left_branch, left_path, right_branch, right_path, { left_commit, right_commit, include_attribution, allow_missing, page, page_size })

// writes: one Commit on the Branch's head each
file.write(project, branch, path, content, { message, mode })
Expand Down Expand Up @@ -166,6 +167,35 @@ over. It searches everything under `path`, `node_modules` included, so keep
"skipped":0,"has_more":false,"next_page_pos":null}
```

## `file.revision`

Saved changes to one literal path, deletions and metadata-only changes
included; no rename or copy ancestry is inferred.

```js
const rev = await layerfs.file.revision(P, "work", "/src/index.js", { page_size: 20 });
console.log(rev.items.map((c) => `${c.kind} ${c.ref.id.slice(0, 12)}`).join("\n"));
```

```json
{"kind":"ok","at":{"id":"12ad2061f04f…","kind":"Commit","branch":"work","root":"f55fa9660a73…"},
"path":"/src/index.js","traversal":"provenance",
"items":[{"candidate_index":0,"ref":{"id":"12ad2061f04f…","kind":"Commit","branch":"work","root":"f55fa9660a73…"},
"compared_to":{"id":"12c7ef811a49…","kind":"Commit","branch":"work","root":"0a12a8d94231…"},
"kind":"Modified","changes":{"content":true,"metadata":true,"identity":false,"attribution":null},
"message":"add retries","recorded_at":1793574061147,"time_status":"recorded"}],
"page":1,"page_size":20,"has_more":false,"end_of_query":true,"continuation":null,
"scan":{"complete":true,"candidates_examined":1,"reasons":[]}}
```

`traversal` is `provenance` (default: a Commit's first parent or base Layer,
a Layer's source Commit or parent Layer, as blame walks) or `branch` (a side
Branch's first parents, or `main`'s Layers in publication order). `at_commit`
pins a full Commit or Layer id; reuse the first answer's `at.id`. A path that
never existed answers an exhausted empty list. The request admits 10,000
visited records and 64 MiB of content comparison; past either it answers a
partial page with `scan.complete: false`, never a silent cap.

## `file.blame`

The Commit of each line, from `from_line` (default 1).
Expand Down
63 changes: 63 additions & 0 deletions .agents/skills/layerfs-js-sdk/references/methods/logs.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# logs calls

> **Status:** Current general guide for LayerFS 2.0 (#533). Part of the
> `layerfs-js-sdk` skill. An agent working on a project rarely needs this
> family; it belongs to whoever watches a run. A folder scope refuses every
> `logs` call.

```js
logs.list({ op, project, client, tag, outcome, since, cursor, limit })
logs.reset()
logs.machine(machine, { cursor, before, limit })
logs.sandbox(sandbox, { cursor, before, limit })
```

`logs.list` reads the home's call log (`trace/calls.jsonl`, then
`trace/calls.1.jsonl`); `logs.machine` and `logs.sandbox` read a machine's
worker log and a Sandbox's `daemon.log`. A call-log line is
`{ v, at, ms, client, argv, outcome, kind?, commit?, layer?, tag? }`, where
`at` is when the call started (ms since the epoch) and `ms` its duration.

## `logs.list`

`logs.list({ op, project, client, tag, outcome, since, cursor, limit })`: the
calls made against this home, newest first. Every option given must match:
`op` is `family` or `family.call`; `project` matches the lines' `argv`;
`client` is `cli`, `node`, `python` or `rust`; `tag` is an exact tag or a
prefix ending in `:`; `outcome` is `ok` or a refusal code; `since` keeps lines
at or after a time (ms). `limit` is 1 to 1000 (default 100), and `cursor` is a
previous answer's `next`.

Returns `{ lines, next?, has_more, skipped }`; `skipped` counts torn lines
that do not parse, which are never answered. Errors: `InvalidInput` (a bad
option, `limit` out of range, a malformed or stale cursor), `Failed` (a log
file cannot be read).

## `logs.reset`

`logs.reset()`: clears the call log, truncating `trace/calls.jsonl` in place
and removing `trace/calls.1.jsonl`. Returns `{ kind: "Reset", removed }`, the
lines both files held. A cursor from before the reset is stale afterwards.
Error: `Failed`.

## `logs.machine`

`logs.machine(machine, { cursor, before, limit })`: one window of a machine's
`log/worker.log`, with `worker.1.log`. `limit` is 1 to 1000 (default 200);
`cursor` reads the lines after another answer's `cursor`, `before` the lines
before another answer's `before` (not with `cursor`).

Returns `{ lines, cursor, before?, has_more }`: `lines` are oldest first, each
`{ text }`, or `{ text, continued: true }` for a piece of a longer line.
`cursor` is always text; pass it back to read what was written since. One call
reads at most 64 KiB, so an answer may hold fewer than `limit` lines with
`has_more` true. Errors: `InvalidInput` (both options, `limit` out of range, a
malformed or stale cursor), `Unsupported` (`native` has no worker),
`NotFound`, `Unavailable`, `Busy`, `Failed`.

## `logs.sandbox`

`logs.sandbox(sandbox, { cursor, before, limit })`: the same, over a
Sandbox's `daemon.log` in its run folder. Options, result and rules are
`logs.machine`'s. Errors add `NoSuchSandbox` and `Unsupported` (a retired
docker Sandbox record).
Loading