Skip to content
Merged
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
2 changes: 1 addition & 1 deletion .agents/skills/layerfs-js-sdk/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -285,7 +285,7 @@ For Rust projects, follow the [Cargo workflow](references/rules/cargo.md).

## Calls

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

| Family | Calls |
Expand Down
12 changes: 5 additions & 7 deletions .agents/skills/layerfs-js-sdk/references/methods/store.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,11 @@
```js
store.list()
store.get(name)
store.status(name)
store.status(name, { machine })
store.stats(name)
store.create(name)
store.connect(name, url, { password, synchronous_commit })
store.attach(name, machine, { url, password })
store.detach(name, machine)
store.update(name, { machine, url, password, synchronous_commit, clear })
store.push(name, machine, { on_progress })
store.pull(name, { on_progress })
store.remove(name)
Expand All @@ -25,7 +24,7 @@ store.disconnect(name)

A Store holds projects and all their history. The verb says the kind:
`create` makes a sqlite Store (one file, on one machine at a time; it starts on
`native`); `connect` attaches a PostgreSQL database. Every sqlite Store is
`native`); `connect` connects a PostgreSQL database. Every sqlite Store is
Disposable (WAL, `synchronous=OFF`), the only allowed profile.

## Reads
Expand Down Expand Up @@ -80,9 +79,8 @@ Store on another machine is read through its worker; a stopped worker is
| Call | What it does | Notes |
| --- | --- | --- |
| `create(name)` | An empty sqlite Store on `native` | Live result: the record above, with `projects: []`. `Exists` for a taken name |
| `connect(name, url, …)` | Attaches a PostgreSQL database | `url` is `postgresql://<user>@<host>:<port>/<database>[?sslmode=…]` without a password (one in the user part or in any query parameter whose name contains `password` is `InvalidInput`); `password` is a reference, `env:LAYERFS_<NAME>` or `file:/path`. `synchronous_commit` defaults to `local`. The same database under a second name is `Exists` |
| `attach(name, machine, …)` | Lets a machine run Sandboxes of a PostgreSQL Store | Checks from that machine that it reaches the database and its role may write; `url` and `password` replace the Store's for that machine, either alone. `InvalidInput` for sqlite; `Unsupported` when the platform runs no PostgreSQL Sandboxes; `Unavailable` (not reached, machine stopped); `Denied` (login or privilege); `Conflict` while the Store is disconnected or reconnected |
| `detach(name, machine)` | Stops a machine running Sandboxes of a PostgreSQL Store | Dials nothing; detaching `native` is allowed. `InvalidInput` (sqlite, or not attached there); `InUse` while a Sandbox of the Store is recorded on the machine |
| `connect(name, url, …)` | Connects a PostgreSQL database | `url` is `postgresql://<user>@<host>:<port>/<database>[?sslmode=…]` without a password (one in the user part or in any query parameter whose name contains `password` is `InvalidInput`); `password` is a reference, `env:LAYERFS_<NAME>` or `file:/path`. `synchronous_commit` defaults to `local`. The same database under a second name is `Exists` |
| `update(name, …)` | Changes a PostgreSQL Store's connection, or one machine's own | Without `machine`: sets the Store's `url`, `password` reference and `synchronous_commit`; a new URL or password must reach the same Store. With `machine`: `url` and/or `password` become that machine's own connection, checked from the machine first; `clear: true` removes it. A PostgreSQL Store's Sandboxes run on every supported machine with no step before `sandbox.create`. `InvalidInput` for sqlite or nothing to update; `Unsupported` when the platform runs no PostgreSQL Sandboxes; `Unavailable` (not reached, machine stopped, another Store's database); `Denied` (login or privilege); `Conflict` while the Store is disconnected or reconnected |
| `push(name, machine, …)` | Sends a sqlite Store's file from `native` to `machine` | `InvalidInput` unless the Store is on `native` (pull it first). Progress `{ phase, done, total }` on `on_progress` / `--progress`: `done` and `total` are bytes during `send`, null in the other phases (`check`, `snapshot`, `verify`, `install`, `record`, `retire`). `InUse` while the Store is held (Sandbox records, processes with it open; `detail.related` lists them as `{ kind, name }`); `Capacity` when the target has less free disk than the Store plus a headroom of 1 GiB (or a tenth of the Store), checked before anything changes; `Unavailable` naming `layerfs machine start <m>` for a stopped machine; while it runs, Store calls and operations on it are `Busy`, from the caller's process too. An uncertain push whose process is gone (it ended during install or record, or a step's answer was lost) leaves every later call `Unresolved`, naming `store status` and the push that clears it: a new `push` (or `pull`) first deletes the copy on the machine the record does not name, then runs. A push whose `retire` did not finish leaves the Store in use on `machine` and `last_transfer.retired: false`; the next `pull` deletes the old copy first |
| `pull(name, …)` | Brings a sqlite Store's file from its machine to `native` | `InvalidInput` when it is already on `native`; otherwise as `push`. Between two machines: `pull`, then `push` |
| `remove(name)` | Deletes a sqlite Store with every project in it | Returns `{ removed }`. `NotFound` for an unknown name (live); `Unavailable` for a Store whose machine is unknown; `Busy` while a live process pushes, pulls or removes it. It clears an `Unresolved` Store. Backups stay |
Expand Down
4 changes: 2 additions & 2 deletions 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 twelve families of functions, 85 calls in all:
library's call table as twelve families of functions, 84 calls in all:

| Family | Calls |
| --- | --- |
Expand All @@ -22,7 +22,7 @@ library's call table as twelve families of functions, 85 calls in all:
| [`sandbox`](../docs/architecture/api/sdk/sandbox.md) | `create`, `list`, `get`, `close`, `files` |
| [`workspace`](../docs/architecture/api/sdk/workspace.md) | `mount`, `exec`, `exec_cancel`, `commit`, `unmount`, `status` |
| [`machine`](../docs/architecture/api/sdk/machine.md) | `list`, `platforms`, `get`, `images`, `load`, `prune`, `status`, `stats`, `space`, `files`, `start`, `stop`, `create`, `remove`, `update` |
| [`store`](../docs/architecture/api/sdk/store.md) | `list`, `get`, `status`, `stats`, `create`, `connect`, `attach`, `detach`, `push`, `pull`, `remove`, `compact`, `disconnect` |
| [`store`](../docs/architecture/api/sdk/store.md) | `list`, `get`, `status`, `stats`, `create`, `connect`, `update`, `push`, `pull`, `remove`, `compact`, `disconnect` |
| [`backup`](../docs/architecture/api/sdk/backup.md) | `connect`, `disconnect`, `list`, `create`, `restore` |
| [`logs`](../docs/architecture/api/sdk/logs.md) | `list`, `reset`, `machine`, `sandbox` |
| [`doctor`](../docs/architecture/api/sdk/doctor.md) | `fix` |
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 @@ -79,7 +79,7 @@ pub use layerfs_sandbox::{
BoundWorkspace, MountFailure, MountedWorkspace, Unmounted, WorkspaceApi,
};

/// The twelve families, in the order help lists them: 85 calls, the same
/// The twelve families, in the order help lists them: 84 calls, the same
/// from the `layerfs` binary, Node and Python.
pub fn families() -> Families {
&[
Expand Down
32 changes: 0 additions & 32 deletions api/crates/layerfs-api/src/store/attach.rs

This file was deleted.

4 changes: 2 additions & 2 deletions api/crates/layerfs-api/src/store/connect.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
//! `store.connect`: attach a PostgreSQL database as a Store.
//! `store.connect`: connect a PostgreSQL database as a Store.
use crate::calls::table::Kind::{Name, Text};
use crate::calls::table::{a, call, opt, Call};
use crate::calls::Context;
Expand All @@ -13,7 +13,7 @@ pub(crate) const CALL: Call = call(
"connect",
&[a("name", Name), a("url", Text)],
&[opt("password", Text), opt("synchronous_commit", Text)],
"attach a PostgreSQL database as a Store",
"connect a PostgreSQL database as a Store",
run,
);

Expand Down
24 changes: 0 additions & 24 deletions api/crates/layerfs-api/src/store/detach.rs

This file was deleted.

11 changes: 5 additions & 6 deletions api/crates/layerfs-api/src/store/mod.rs
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
//! The `store` family: 13 calls, one file each (H1: push and pull replace
//! move; attach and detach supersede #536 C4).
mod attach;
//! The `store` family: 12 calls, one file each (H1: push and pull replace
//! move; a PostgreSQL Store runs on every machine, #536 C4, and `update`
//! gives one its own connection, H9).
mod compact;
mod connect;
mod create;
mod detach;
mod disconnect;
mod get;
mod list;
Expand All @@ -13,6 +12,7 @@ mod push;
mod remove;
mod stats;
mod status;
mod update;

use crate::calls::Calls;

Expand All @@ -25,8 +25,7 @@ pub(crate) fn calls() -> Calls {
stats::CALL,
create::CALL,
connect::CALL,
attach::CALL,
detach::CALL,
update::CALL,
push::CALL,
pull::CALL,
remove::CALL,
Expand Down
18 changes: 12 additions & 6 deletions api/crates/layerfs-api/src/store/status.rs
Original file line number Diff line number Diff line change
@@ -1,23 +1,29 @@
//! `store.status`: a Store's live state.
//! `store.status`: a Store's live state, and on request the check of one
//! machine's connection to it.
use crate::calls::table::Kind::Name;
use crate::calls::table::{a, call, Call};
use crate::calls::table::{a, call, opt, Call};
use crate::calls::Context;
use layerfs_bridge::control::SdkValue;
use layerfs_home::names::StoreName;
use layerfs_home::names::{MachineName, StoreName};
use layerfs_home::outcome::Outcome;

/// Its table entry.
pub(crate) const CALL: Call = call(
"store",
"status",
&[a("name", Name)],
&[],
"a Store's live state",
&[opt("machine", Name)],
"a Store's live state; with a machine, whether it reaches a PostgreSQL Store",
run,
);

/// Runs `store.status`.
fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome {
let name = StoreName::parse(args.get_text("name").unwrap_or(""))?;
layerfs_store::sqlite::family::status(&context.home, &name)
let machine = args
.get_text("machine")
.map(MachineName::parse)
.transpose()?;
let (home, events) = context.parts();
layerfs_control::store::status(home, events, &name, machine.as_ref())
}
43 changes: 43 additions & 0 deletions api/crates/layerfs-api/src/store/update.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
//! `store.update`: change a PostgreSQL Store's connection, or the one a
//! machine alone dials.
use crate::calls::table::Kind::{Bool, Name, Text};
use crate::calls::table::{a, call, opt, Call};
use crate::calls::Context;
use layerfs_bridge::control::SdkValue;
use layerfs_control::store::StoreUpdate;
use layerfs_home::names::{MachineName, StoreName};
use layerfs_home::outcome::Outcome;

/// Its table entry.
pub(crate) const CALL: Call = call(
"store",
"update",
&[a("name", Name)],
&[
opt("machine", Name),
opt("url", Text),
opt("password", Text),
opt("synchronous_commit", Text),
opt("clear", Bool),
],
"change a PostgreSQL Store's connection, or the one a machine alone dials",
run,
);

/// Runs `store.update`.
fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome {
let text = |name: &str| args.get_text(name).map(str::to_owned);
let request = StoreUpdate {
name: StoreName::parse(args.get_text("name").unwrap_or(""))?,
machine: args
.get_text("machine")
.map(MachineName::parse)
.transpose()?,
url: text("url"),
password: text("password"),
synchronous_commit: text("synchronous_commit"),
clear: args.get_bool("clear"),
};
let (home, events) = context.parts();
layerfs_control::store::update(home, events, &request)
}
10 changes: 5 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): 85 calls in twelve
//! The call table and its dispatcher (#533 step 2): 84 calls in twelve
//! 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_twelve_families_and_85_calls() {
fn the_table_has_twelve_families_and_84_calls() {
let all: Vec<&Call> = layerfs_api::calls();
assert_eq!(all.len(), 85);
assert_eq!(all.len(), 84);
// 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_twelve_families_and_85_calls() {
let mut names: Vec<_> = all.iter().map(|c| c.name()).collect();
names.sort();
names.dedup();
assert_eq!(names.len(), 85, "call names are unique");
assert_eq!(names.len(), 84, "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_twelve_families_and_85_calls() {
}
}
let counts: Vec<usize> = families().iter().map(|f| f.calls().len()).collect();
assert_eq!(counts, [2, 7, 9, 3, 15, 5, 6, 15, 13, 5, 4, 1]);
assert_eq!(counts, [2, 7, 9, 3, 15, 5, 6, 15, 12, 5, 4, 1]);
}

#[test]
Expand Down
Loading