Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 33 additions & 14 deletions .agents/skills/layerfs-js-sdk/references/methods/project.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ project.init(project, folder, { timeout, on_progress })
project.list(store?, { page_size, page_pos })
project.get(project)
project.export(project, destination, { branch, on_progress })
project.remove(project)
project.delete(project)
project.remove_file(project, path)
```

## `project.init`
Expand Down Expand Up @@ -119,23 +120,41 @@ The project's record: its Store, the Store's kind and machine.
{"project":"shop/api","store":"shop","name":"api","kind":"sqlite","machine":"native","created":1793574061265}
```

## `project.remove`
## `project.delete`

`project.remove(project)`
`project.delete(project)`

Removes one project from its Store. Its Branches, Commits and `main` go with
it; there is no undo. The live result:
Retires one project in its Store and removes its home entry (spec §4). The
project disappears from `project.list` and `project.get`; its Layers,
Branches, Commits and stored content stay until a later `store.compact`, and
the Store stays addressable. The live result:

```json
{"stack":"3104401f11fb…","packs_kept":true,"project":"shop/api"}
{"kind":"Removed","project":"shop/api","deleted_ms":1793574061265,"home_entry_removed":true}
```

`packs_kept: true`: the project's records are gone, but its stored content
stays in the Store file. Removing a project from a PostgreSQL Store is
`Unsupported` in this build. While a Sandbox of the project is recorded it is
refused `InUse`; `detail.related` lists each as `{ kind: "sandbox", name }`
(close them first). To delete a whole Store with every project in it, use
`store.remove`.
The Store marker is the commit point. If the home entry cannot be removed the
call still succeeds with `home_entry_removed: false` and keeps a durable
intent, so the same call retried from the same home reuses `deleted_ms` and
finishes the entry. A mount of the project is refused `MountsActive`, another
user or operation `Busy`/`Unresolved`.

An agent working on a project never needs `remove`; it is for whoever owns the
home.
## `project.remove_file`

`project.remove_file(project, path)`

Hides one absolute project path from every node at or below its marker
frontier (spec §4.3). It writes a marker only; no bytes are freed. The path is
normalized (one leading `/` stripped) and must be a canonical absolute POSIX
path. The live result:

```json
{"kind":"Removed","project":"shop/api","path":"docs/old.md","frontier_serial":42,"removed_ms":1793574061265}
```

`kind` is `UpToDate` when no project node is above this path's marker
frontier. Later reads and stats of the path are refused `Removed`; a Commit
after the frontier that writes the path again is visible.

An agent working on a project never needs `delete` or `remove_file`; they are
for whoever owns the home.
203 changes: 203 additions & 0 deletions .github/workflows/store-ext4.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,203 @@
# Store lane: the Store suites, on a filesystem that carries SQLite's locks.
#
# A Store opens only on a directory that is private, owned by the test user and
# on a local filesystem whose locks reach every opener: ext4, xfs or btrfs on
# Linux (engine/crates/layerfs-store-service/src/kernel_guard.rs). The Store
# suites keep their Stores in TMPDIR and in $CARGO_TARGET_DIR/tmp, so both must
# be on such a filesystem, and an overlay checkout or a tmpfs /tmp is refused.
# tools/ci/test_store_ext4.sh refuses any other directory before cargo starts
# and points TMPDIR, CARGO_TARGET_DIR and CARGO_HOME at the one it is given;
# this lane only provides that directory. See
# docs/architecture/engine/store/testing.md.
#
# It adds no test selection of its own: every target it runs is already in the
# push or nightly lane chosen by tools/ci_tests.py. It runs them under the
# environment contract their guard requires.
#
# Reports only, like the other lanes (AGENTS.md §4): never a required check.
# The runner's /mnt is a separate ext4 data disk while /tmp is tmpfs, so the
# prepare step asserts the filesystem: a runner image whose /mnt is not ext4
# fails there, with its own message, instead of as a guard refusal inside a
# suite.
name: store-ext4

on:
push:
branches: [main]
paths:
- "core/**"
- "engine/**"
- "control/**"
- "api/crates/**"
- "!api/crates/layerfs-node/**"
- "Cargo.*"
- ".config/**"
- "tools/ci/**"
- ".cargo/**"
- ".github/workflows/store-ext4.yml"
- "!**/*.md"
pull_request:
# off for pull requests into layerfs_v2_0_0, like the other lanes
branches-ignore: [layerfs_v2_0_0]
paths:
- "core/**"
- "engine/**"
- "control/**"
- "api/crates/**"
- "!api/crates/layerfs-node/**"
- "Cargo.*"
- ".config/**"
- "tools/ci/**"
- ".cargo/**"
- ".github/workflows/store-ext4.yml"
- "!**/*.md"
schedule:
# After nightly.yml's 04:23 UTC run; the two lanes never share runner time.
- cron: "47 4 * * *"
workflow_dispatch:

permissions:
contents: read

concurrency:
group: store-ext4-${{ github.ref }}
cancel-in-progress: true

env:
CARGO_TERM_COLOR: always
CARGO_INCREMENTAL: "0"
# CI needs no debugger: smaller objects, much shorter links.
CARGO_PROFILE_TEST_DEBUG: "0"
# Link the test binaries with mold instead of GNU ld, as ci.yml's test job
# does. Scoped to this target, so the repository's aarch64 rustflags
# (.cargo/config.toml) stay.
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS: "-C link-arg=-fuse-ld=mold"
# The harness requires this and validates it before cargo starts. /mnt is the
# runner's ext4 data disk; never /tmp, which is tmpfs there.
LAYERFS_TEST_TMPDIR: /mnt/layerfs-store-tests

jobs:
quick:
name: store ext4 (--quick)
# The push lane: one or two targets per suite, across the four suites.
if: github.event_name == 'push' || github.event_name == 'pull_request'
runs-on: ubuntu-24.04
timeout-minutes: 60
steps:
- uses: actions/checkout@v7.0.1
- run: rustup toolchain install 1.85.1 --profile minimal
- name: Install mold
run: |
sudo apt-get update -qq
sudo apt-get install -y -qq --no-install-recommends mold
mold --version
- name: Prepare the ext4 test directory
run: |
# /mnt belongs to root on the runner image and the tests run as the
# runner, so hand the directory over before the harness probes it.
sudo mkdir -p "$LAYERFS_TEST_TMPDIR"
sudo chown "$(id -u):$(id -g)" "$LAYERFS_TEST_TMPDIR"
fs="$(findmnt -n -o FSTYPE --target "$LAYERFS_TEST_TMPDIR")"
echo "LAYERFS_TEST_TMPDIR=$LAYERFS_TEST_TMPDIR ($fs)"
df -h "$LAYERFS_TEST_TMPDIR"
case "$fs" in
ext4|xfs|btrfs) ;;
*)
echo "::error title=unsupported filesystem::$LAYERFS_TEST_TMPDIR is on $fs; the Store guard admits only ext4, xfs or btrfs"
exit 1
;;
esac
# No Swatinem/rust-cache here: the harness moves CARGO_HOME and
# CARGO_TARGET_DIR onto LAYERFS_TEST_TMPDIR, so the checkout-scoped cache
# the other lanes restore is never read. The cold build is the price of
# running the suites where their guard admits them.
- name: Run the Store suites (--quick)
run: tools/ci/test_store_ext4.sh --quick

full-postgresql:
name: store ext4 (--full, PostgreSQL 17)
# The scheduled and manual lane: every Store suite, with the PostgreSQL
# cases on. A manual dispatch runs this job only, which is the full sweep.
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
runs-on: ubuntu-24.04
timeout-minutes: 120
env:
# A libpq connection string, not a URL (testing.md). A service
# container's published port is 127.0.0.1 on the runner. The server is
# scratch -- each PostgreSQL test creates and drops its own schema -- and
# lives only for this job. Setting this adds `--features postgresql` to
# every suite in the harness.
LAYERFS_TEST_POSTGRES_URL: host=127.0.0.1 port=5432 user=postgres dbname=postgres sslmode=disable
# The full-mode doctor calls amcheck's verify_heapam and bt_index_check;
# the step below creates it in this database. The physical doctor's two
# extra servers (an amcheck-free database and a physical standby) are
# not available in this job; see testing.md. Set so the diagnostic test
# asserts relation coverage is Pass instead of only printing it.
LAYERFS_TEST_EXPECT_AMCHECK: "1"
services:
postgres:
# PostgreSQL 17 is the supported version for these cases: the schema
# needs 16 or newer for STORAGE PLAIN, and the suites are qualified on
# 17.x (docs/architecture/engine/store/testing.md).
image: postgres:17
env:
POSTGRES_USER: postgres
POSTGRES_DB: postgres
# Trust authentication: a throwaway server, reachable from this job's
# steps only, and the tests create and drop their own schemas.
POSTGRES_HOST_AUTH_METHOD: trust
ports:
- 5432:5432
options: >-
--health-cmd "pg_isready --username=postgres --dbname=postgres"
--health-interval 5s
--health-timeout 5s
--health-retries 20
steps:
- uses: actions/checkout@v7.0.1
- run: rustup toolchain install 1.85.1 --profile minimal
- name: Install mold
run: |
sudo apt-get update -qq
sudo apt-get install -y -qq --no-install-recommends mold
mold --version
- name: Prepare the ext4 test directory
run: |
sudo mkdir -p "$LAYERFS_TEST_TMPDIR"
sudo chown "$(id -u):$(id -g)" "$LAYERFS_TEST_TMPDIR"
fs="$(findmnt -n -o FSTYPE --target "$LAYERFS_TEST_TMPDIR")"
echo "LAYERFS_TEST_TMPDIR=$LAYERFS_TEST_TMPDIR ($fs)"
df -h "$LAYERFS_TEST_TMPDIR"
case "$fs" in
ext4|xfs|btrfs) ;;
*)
echo "::error title=unsupported filesystem::$LAYERFS_TEST_TMPDIR is on $fs; the Store guard admits only ext4, xfs or btrfs"
exit 1
;;
esac
# The service health check gates this job on the server answering. The
# engine never installs extensions: a full-mode audit calls amcheck's
# verify_heapam and bt_index_check and reports every relation as
# Unknown when the extension is absent, while the compaction suite
# asserts a clean full audit. A fresh cluster therefore needs these
# contrib extensions before any suite connects (T-G14). The server is
# scratch, and this is the one database every suite reaches.
- name: Create the PostgreSQL extensions
run: |
set -euo pipefail
# The runner image does not ship psql; the distro client reaches the
# PostgreSQL 17 service container.
sudo apt-get update -qq
sudo apt-get install -y -qq --no-install-recommends postgresql-client
psql --version
psql "$LAYERFS_TEST_POSTGRES_URL" -X -v ON_ERROR_STOP=1 <<'SQL'
CREATE EXTENSION IF NOT EXISTS amcheck;
CREATE EXTENSION IF NOT EXISTS pgstattuple;
SQL
# Fail here, with a readable list, rather than as five Unknown
# relation checks inside a compaction suite.
psql "$LAYERFS_TEST_POSTGRES_URL" -X -A -t -v ON_ERROR_STOP=1 \
-c "SELECT extname FROM pg_catalog.pg_extension WHERE extname IN ('amcheck','pgstattuple') ORDER BY extname"
# The suites own their schemas; the harness reports the mode it took.
- name: Run the Store suites (--full)
run: tools/ci/test_store_ext4.sh --full
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ CLI package `@layerfs/cli` (in [`cli/`](cli)), the Python package (in
the private stdio MCP server [`mcp/`](mcp) (`@layerfs/mcp`: one generated tool
per call, `work` and `admin` profiles). The design is in
[docs/architecture/api](../docs/architecture/api/README.md). The package is the
library's call table as ten families of functions, 73 calls in all:
library's call table as ten families of functions, 76 calls in all:

| Family | Calls |
| --- | --- |
Expand Down
2 changes: 1 addition & 1 deletion api/crates/layerfs-api/src/calls/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
//! table's shape, argument checks, folder scope, result keys and the one
//! dispatcher with its call log line (`render`, #659); moved back from
//! `layerfs-control` by layerfs-project#107.
//! The 70 entries in ten families live beside it, one folder per family and
//! The 76 entries in ten families live beside it, one folder per family and
//! one file per call; each function here that needs them takes that list.
mod check;
mod context;
Expand Down
2 changes: 1 addition & 1 deletion api/crates/layerfs-api/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ pub use layerfs_sandbox::{
BoundWorkspace, MountFailure, MountedWorkspace, Unmounted, WorkspaceApi,
};

/// The ten families, in the order help lists them: 77 calls, the same
/// The ten families, in the order help lists them: 76 calls, the same
/// from the `layerfs` binary, Node and Python.
pub fn families() -> Families {
&[
Expand Down
4 changes: 1 addition & 3 deletions api/crates/layerfs-api/src/project/mod.rs
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
//! The `project` family: 8 calls, one file each.
//! The `project` family: 7 calls, one file each.
mod delete;
mod export;
mod get;
mod init;
mod list;
mod remove;
mod remove_file;
mod stats;

Expand All @@ -20,6 +19,5 @@ pub(crate) fn calls() -> Calls {
export::CALL,
delete::CALL,
remove_file::CALL,
remove::CALL,
]
}
24 changes: 0 additions & 24 deletions api/crates/layerfs-api/src/project/remove.rs

This file was deleted.

1 change: 0 additions & 1 deletion api/crates/layerfs-api/tests/calls_scope.rs
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,6 @@ fn a_scope_refuses_every_call_it_does_not_cover() {
let uncovered: &[(&str, &[(&str, SdkValue)])] = &[
("store.remove", &[("name", t("shop"))]),
("store.list", &[]),
("project.remove", &[("project", t("shop/api"))]),
(
"branch.remove",
&[("project", t("shop/api")), ("branch", t("main"))],
Expand Down
Loading
Loading