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.
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
21 changes: 16 additions & 5 deletions api/crates/layerfs-api/tests/calls_table.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
//! The call table and its dispatcher (#533 step 2): 77 calls in ten
//! The call table and its dispatcher (#533 step 2): 76 calls in ten
//! families, arguments checked before any effect, one test per family that
//! a valid call reaches its family function and a wrong one is refused.
use layerfs_api::{families, json, keys, size, Call, Kind};
Expand Down Expand Up @@ -51,9 +51,9 @@ fn code(name: &str, args: SdkValue) -> String {
}

#[test]
fn the_table_has_ten_families_and_77_calls() {
fn the_table_has_ten_families_and_76_calls() {
let all: Vec<&Call> = layerfs_api::calls();
assert_eq!(all.len(), 77);
assert_eq!(all.len(), 76);
// each family holds only its own calls, and has at least one
for family in families() {
assert!(!family.calls().is_empty(), "{}", family.name);
Expand All @@ -66,7 +66,7 @@ fn the_table_has_ten_families_and_77_calls() {
let mut names: Vec<_> = all.iter().map(|c| c.name()).collect();
names.sort();
names.dedup();
assert_eq!(names.len(), 77, "call names are unique");
assert_eq!(names.len(), 76, "call names are unique");
// an optional positional is only ever followed by optional ones (D7)
for c in &all {
let first_optional = c.args.iter().position(|a| a.optional);
Expand All @@ -75,7 +75,7 @@ fn the_table_has_ten_families_and_77_calls() {
}
}
let counts: Vec<usize> = families().iter().map(|f| f.calls().len()).collect();
assert_eq!(counts, [8, 9, 3, 15, 4, 6, 12, 13, 5, 2]);
assert_eq!(counts, [7, 9, 3, 15, 4, 6, 12, 13, 5, 2]);
}

#[test]
Expand All @@ -98,6 +98,17 @@ fn unknown_calls_and_arguments_are_refused_before_any_effect() {
.starts_with("InvalidInput"));
}

#[test]
fn project_remove_is_retired() {
// spec 4: the hard delete leaves the table; a caller gets `InvalidInput`
// naming it, never a silent hard delete
assert!(layerfs_api::find("project.remove").is_none());
assert_eq!(
code("project.remove", map(&[("project", t("shop/api"))])),
"InvalidInput: no call named `project.remove`"
);
}

#[test]
fn project_family() {
assert!(code("project.get", map(&[("project", t("api"))]))
Expand Down
27 changes: 27 additions & 0 deletions api/crates/layerfs-api/tests/gc_calls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -246,6 +246,33 @@ fn project_delete_reports_removal_and_retires_the_entry() {
let _ = std::fs::remove_dir_all(folder);
}

/// A project name a `project.delete` retired is still held: a second
/// `project.init` is `NameTaken` with the `deleted` holder, refused before
/// the folder is scanned.
#[test]
fn project_init_after_delete_is_nametaken_deleted() {
let (home, folder) = project();
ok(&home, "project.delete", &[p()]);
let refusal = layerfs_api::call(
Some(&home),
"project.init",
map(&[
("project", t("shop/api")),
("folder", t(&folder.display().to_string())),
]),
&mut |_| {},
)
.unwrap_err();
assert_eq!(refusal.code, "NameTaken", "{}", refusal.message);
let holder = refusal.detail.get("holder").expect("holder detail");
assert_eq!(holder.get_text("kind"), Some("project"), "{refusal:?}");
assert_eq!(holder.get_text("name"), Some("api"));
assert_eq!(holder.get_text("state"), Some("deleted"));
assert_eq!(refusal.detail.get_text("source"), Some("store"));
std::fs::remove_dir_all(home).unwrap();
let _ = std::fs::remove_dir_all(folder);
}

#[test]
fn store_compact_refuses_an_unknown_store_and_reports_a_run() {
let home = tempdir("compact-none");
Expand Down
25 changes: 15 additions & 10 deletions api/crates/layerfs-api/tests/project_export.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1283,7 +1283,7 @@ fn shared_store_lease_and_concurrent_remove_admission() {
// 2. During an in-flight `project.export`:
// - same-Store `file.read` and a second concurrent `project.export` succeed;
// - exclusive Store operations (`store.remove`, `store.push`) are refused `InUse`;
// - `project.remove` drops the catalog stack while packs stay (`packs_kept: true`),
// - `project.delete` retires the Stack (its marker keeps packs/objects),
// leaving the in-flight pinned export intact while refusing later exports.
let first_dest = area.join("first");
let second_dest = area.join("second");
Expand Down Expand Up @@ -1336,10 +1336,14 @@ fn shared_store_lease_and_concurrent_remove_admission() {
.unwrap_err();
assert_eq!(push_code, "InUse", "{push_msg}");

// `project.remove` drops the LayerStack while keeping packs/objects;
// the already-pinned export continues without corruption.
let removed = ok(&home, "project.remove", &[("project", t("shop/app"))]);
assert_eq!(removed.get("packs_kept"), Some(&SdkValue::Bool(true)));
// `project.delete` retires the LayerStack and removes the home
// entry; the already-pinned export continues without corruption.
let removed = ok(&home, "project.delete", &[("project", t("shop/app"))]);
assert_eq!(removed.get_text("kind"), Some("Removed"));
assert_eq!(
removed.get("home_entry_removed"),
Some(&SdkValue::Bool(true))
);
}
},
)
Expand All @@ -1350,7 +1354,7 @@ fn shared_store_lease_and_concurrent_remove_admission() {
assert_same_tree(&source, &second_dest);
let _ = std::fs::remove_file(&other_lease);

// After `project.remove`, a new export is refused `NoSuchProject`
// After `project.delete`, a new export is refused `NoSuchProject`
let after_rm_dest = area.join("after-rm");
let (code, _) = call(
&home,
Expand All @@ -1364,12 +1368,13 @@ fn shared_store_lease_and_concurrent_remove_admission() {
assert_eq!(code, "NoSuchProject");
assert!(!after_rm_dest.exists());

// Re-init `shop/app` and verify Store-level `Busy` and `Unresolved` admission
// Re-init a new project (`shop/app` stays a retired name) and verify
// Store-level `Busy` and `Unresolved` admission.
ok(
&home,
"project.init",
&[
("project", t("shop/app")),
("project", t("shop/app2")),
("folder", t(&source.display().to_string())),
],
);
Expand All @@ -1394,7 +1399,7 @@ fn shared_store_lease_and_concurrent_remove_admission() {
&home,
"project.export",
&[
("project", t("shop/app")),
("project", t("shop/app2")),
("destination", t(&busy_dest.display().to_string())),
],
)
Expand All @@ -1419,7 +1424,7 @@ fn shared_store_lease_and_concurrent_remove_admission() {
&home,
"project.export",
&[
("project", t("shop/app")),
("project", t("shop/app2")),
("destination", t(&busy_dest.display().to_string())),
],
)
Expand Down
Loading
Loading