diff --git a/api/README.md b/api/README.md index dcaf8f049b..41f5b0576a 100644 --- a/api/README.md +++ b/api/README.md @@ -64,6 +64,40 @@ nothing else: it does not look in the source tree, and a missing addon is an error that says how to build it. `npm --prefix api run gen:types` regenerates `node/src/index.d.ts` after a change to the call table. +### Package and install + +Each artifact is for the OS, CPU and C library it was built on (a Linux build +needs at least the glibc of its build host). None is published; install the +files you build, here into `$OUT`: + +```bash +npm --prefix api run build:native # node/layerfs.node +(cd api/node && npm pack --pack-destination "$OUT") # layerfs-2.0.0.tgz +npm install "$OUT/layerfs-2.0.0.tgz" # in an empty project + +(cd api/python && maturin build --release --locked -o "$OUT") # layerfs-2.0.0-*.whl +pip install "$OUT"/layerfs-2.0.0-*.whl # in a virtualenv + +cargo +1.85.1 build --release --locked -p layerfs-cli # target/release/layerfs, one file +``` + +`npm pack` fails when `node/layerfs.node` is missing, so a tarball never lacks +its addon. The default addon, wheel and command have no PostgreSQL and no TLS: +a call that needs them is refused `Unsupported` ("this LayerFS build has no +PostgreSQL engine"). Both are opt-in at build time and need the OpenSSL +development files (`libssl-dev`) on the build host: + +```bash +npm --prefix api run build:native -- --features postgresql # or tls, or postgresql,tls +(cd api/python && maturin build --release --locked --features postgresql -o "$OUT") +cargo +1.85.1 build --release --locked -p layerfs-cli --features postgresql +``` + +For such a wheel `maturin` copies `libssl`, `libcrypto` and `libzstd` into it +and needs `patchelf`; the addon and the command load them from the system. +The runs behind these steps are in +[artifact-qualification-2.0.0.md](../docs/general/artifact-qualification-2.0.0.md). + Disposable/WAL/synchronous=OFF only. Durable execution is NOT_RUN — disabled by owner until explicit reauthorization. One attempted operation; no retry or replay. diff --git a/api/node/package.json b/api/node/package.json index 75b2e8ca09..c15cad8cc1 100644 --- a/api/node/package.json +++ b/api/node/package.json @@ -19,6 +19,7 @@ "node": ">=22" }, "scripts": { + "prepack": "node -e \"require('node:fs').existsSync('layerfs.node') || (console.error('layerfs.node is missing: run npm --prefix api run build:native before packing'), process.exit(1))\"", "test": "node --test test/*.mjs" }, "license": "MIT", diff --git a/api/python/README.md b/api/python/README.md index 1843540e71..7b096fb76e 100644 --- a/api/python/README.md +++ b/api/python/README.md @@ -52,6 +52,13 @@ python api/python/tools/gen_stubs.py # --check fails on drift cd api/python && maturin build --locked ``` +That is a debug build. The wheel to install is `maturin build --release +--locked`; add `--features postgresql` (or `tls`) for PostgreSQL Stores, +which needs the OpenSSL development files and `patchelf`. The wheel's +platform tag follows the build host's glibc (`manylinux_2_39` on Ubuntu 26.04). +The steps to install it into an empty virtualenv are in +[api/README.md](../README.md#package-and-install). + For the tests, either install the module in a virtualenv (`maturin develop --locked --offline` puts `_native.abi3.so` beside the package) or build it with Cargo and put it there: diff --git a/api/scripts/build-native.mjs b/api/scripts/build-native.mjs index b89eae9093..e06a81c6bd 100644 --- a/api/scripts/build-native.mjs +++ b/api/scripts/build-native.mjs @@ -8,8 +8,12 @@ import { fileURLToPath } from "node:url"; const root = fileURLToPath(new URL("../../", import.meta.url)); const suffix = { darwin: "dylib", linux: "so" }[process.platform]; if (!suffix) throw new Error(`native addon builds require macOS or Linux, got ${process.platform}`); +const usage = "usage: build-native.mjs [--debug] [--features postgresql,tls]"; const flags = process.argv.slice(2); -if (flags.some((flag) => flag !== "--debug")) throw new Error("usage: build-native.mjs [--debug]"); +const featuresAt = flags.indexOf("--features"); +const features = featuresAt < 0 ? [] : (flags[featuresAt + 1] ?? "").split(","); +if (featuresAt >= 0) flags.splice(featuresAt, 2); +if (flags.some((flag) => flag !== "--debug") || features.some((name) => !["postgresql", "tls"].includes(name))) throw new Error(usage); const profile = flags.includes("--debug") ? "debug" : "release"; const configured = process.env.CARGO_TARGET_DIR; const target = configured ? resolve(root, configured) : join(root, "target"); @@ -19,6 +23,7 @@ if (process.env.CARGO_BUILD_TARGET) throw new Error("build on the actual macOS/L const result = spawnSync("cargo", [ "+1.85.1", "build", "--manifest-path", "Cargo.toml", "--offline", "--locked", ...(profile === "release" ? ["--release"] : []), "-p", "layerfs-node", + ...(features.length ? ["--features", features.join(",")] : []), ], { cwd: root, stdio: "inherit", env: { ...process.env, CARGO_TARGET_DIR: target } }); if (result.error) throw result.error; if (result.status !== 0) process.exit(result.status ?? 1); diff --git a/docs/architecture/api/front-ends/README.md b/docs/architecture/api/front-ends/README.md index 995397b872..fb71fadb86 100644 --- a/docs/architecture/api/front-ends/README.md +++ b/docs/architecture/api/front-ends/README.md @@ -136,7 +136,9 @@ Give each a wall limit of at most 120 s. `{"ok":true,"findings":[]}` and does not create it; a Store record that is not JSON gives `1 error(s), 0 warning(s)` and its fix with `--text`; `doctor --all` is exit 2. Command: - `cargo +1.85.1 test --locked -p layerfs-cli --test doctor`. Needs Unix. + `cargo +1.85.1 test --locked -p layerfs-cli --test doctor`, built first + with `--no-run` (the cold build takes over a minute and would hit the + 100 s limit). Needs Unix. - **Node tests**: `calls.mjs`, `shell.mjs`, `events.mjs`, `close.mjs`, `doctor.mjs`; see [Node](node.md#native-addon-build). Command: `perl -e 'alarm 100; exec @ARGV' npm --prefix api/node test` diff --git a/docs/architecture/api/front-ends/node.md b/docs/architecture/api/front-ends/node.md index 9ae6e81a78..45aba299d0 100644 --- a/docs/architecture/api/front-ends/node.md +++ b/docs/architecture/api/front-ends/node.md @@ -124,7 +124,7 @@ api/crates/layerfs-node (cdylib, napi 2.16, napi4) | Step | What happens | Source | | --- | --- | --- | -| Build | `npm --prefix api run build:native` runs `cargo +1.85.1 build --manifest-path Cargo.toml --offline --locked [--release] -p layerfs-node`; `-- --debug` builds a dev profile | [`build-native.mjs`](../../../../api/scripts/build-native.mjs) | +| Build | `npm --prefix api run build:native` runs `cargo +1.85.1 build --manifest-path Cargo.toml --offline --locked [--release] -p layerfs-node`; `-- --debug` builds a dev profile; `-- --features postgresql,tls` (either name or both, nothing else) passes the opt-in features on, default none | [`build-native.mjs`](../../../../api/scripts/build-native.mjs) | | Host | `darwin` (`.dylib`) or `linux` (`.so`); any other platform, a set `CARGO_BUILD_TARGET`, or a `CARGO_TARGET_DIR` outside the worktree is refused | `build-native.mjs` | | Output | copied to `api/node/layerfs.node` (git-ignored; the package's own addon), or to `LAYERFS_NATIVE_OUTPUT`, through a staged file and a rename | `build-native.mjs` | | Loading | the file `LAYERFS_NATIVE` names, else `layerfs.node` beside the package's `src`; nothing else is looked at. A missing file, or one that does not load, throws one error naming the path, `platform/arch`, the Node version and how to build | [`native.js`](../../../../api/node/src/native.js) | diff --git a/docs/general/artifact-qualification-2.0.0.md b/docs/general/artifact-qualification-2.0.0.md new file mode 100644 index 0000000000..0d8d3a0e07 --- /dev/null +++ b/docs/general/artifact-qualification-2.0.0.md @@ -0,0 +1,232 @@ +# LayerFS 2.0.0 artifact qualification (Linux x64) + +> **Status:** Current general guide; a dated evidence record, not a release receipt. Nothing here was published. + +What was built and installed outside a source checkout on one host, what ran +from the installed files, and what did not run. Issue #39 (parent #30). Raw +logs were kept outside the repository; commands are given so each row can be +repeated. Anything not listed as RAN was not run. + +## Re-run on the current base (2026-11-06) + +The first run (the sections below) used artifacts built from `ce9cd4144`, which is the baseline `d4304741` plus four +PRs and does not contain later upstream changes such as #577. This section repeats the qualification on artifacts built +from the current base. **Where it differs from the sections below, this section governs**; the older sections are kept +as history. + +| Item | Value | +| --- | --- | +| Base | `e20c6a2f7` (`e20c6a2f73f50f73780b76bad28b1ef118c7e5cf`), `origin/layerfs_v2_0_0` after PR #595 (2026-11-06 23:29 +08); contains `b919f50ea` (the Firecracker/SSH policy, #577) | +| Tree built | `6f38f361f16b01b94fdee9982b86fd4acaa7b55f` = the base plus `1f739ac17` (`build-native.mjs --features`) and `6f38f361f` (`prepack`); the documentation commits do not change a build | +| Host and tools | Ubuntu 26.04.1 under WSL2, x86_64, glibc 2.43; rustc/cargo 1.85.1; Node 24.22.2 and 22.23.4; npm 11.19.1; Python 3.14.4, and 3.10.22, 3.11.18, 3.12.16, 3.13.18 from `uv`; maturin 1.16.0; patchelf 0.19.3 | +| Profile | `--release`, `--locked --offline`; PostgreSQL builds in their own target directory with OpenSSL 3.0.15 headers and link stubs from the `rust:1.85.1-bookworm` image (`OPENSSL_DIR`; the host has no `libssl-dev`) | + +| Artifact | sha256 | Bytes | +| --- | --- | --- | +| `layerfs` command, default | `6c6e660ed017bc25e68ff6525bb8b1a89214282bb0b6f6c0d6d6c07507a1e069` | 16,068,632 | +| Python wheel, default (`cp310-abi3-manylinux_2_39_x86_64`) | `9bf7255ae8e93718d7eceec330fc8c464b7d00c0a2039c0a9381b76a0d9a016d` | 6,630,233 | +| Node tarball `layerfs-2.0.0.tgz`, default (8 files) | `d5f01099346e8c8b6aacf2307ac2f9f6d92ac88b3ea671eadc9a1f4a38287186` | 6,555,835 | +| `layerfs` command, `--features postgresql` | `357520342d8e8a77daf2f1ec7f3c237019254056afb7ae46ca576af9ed6571ba` | 18,285,432 | +| Python wheel, `--features postgresql` | `e9bb08a341236aa29f9c2571ad3d1ba53b5db5dc1dddb8344d58332295619ec7` | 10,729,134 | +| Node tarball, `--features postgresql` (8 files) | `a04b50d18f5f7dc257f837cf9c7a99ac088a7f1a20b7235a0596d00d00f68def` | 7,428,344 | + +The three PostgreSQL artifacts differ from the default ones (hash, and the command links `libssl`; the default command +does not). A first attempt of this build silently reused the default files because a step failed (no OpenSSL headers) +and was not checked; it was discarded, and the build script now stops on any failed step and proves the difference. + +| Case | Result | +| --- | --- | +| Hashes still match after the install runs | RAN, `sha256sum -c` OK for the three default artifacts | +| Tarball contents, licence | RAN: 8 files (`LICENSE`, `layerfs.node`, `package.json`, `src/{errors,index,native,values}.js`, `src/index.d.ts`); `license` MIT, `engines.node >=22`, `LICENSE` identical to the repository's | +| Native dependencies, default | RAN: addon and command need only `libgcc_s`, `libm`, `libc`; highest symbol `GLIBC_2.39` in both | +| Node 24.22.2: `npm install `, the example | RAN, install exit 0, one `layerfs.node` on disk (`node_modules/layerfs/`), the 15-line example exits 0 | +| Node 22.23.4 (own toolchain), same tarball | RAN: `JSON.rawJSON` is a function and the `JSON.parse` reviver receives the source text of `9223372036854775807`; install exit 0, the example exits 0 and prints the same as Node 24 (ids masked) | +| Node, addon deleted, decoys planted in the old fallback paths | RAN: `import "layerfs"` is refused with "the LayerFS native addon is missing: (the package's own; this is linux/x64, Node v24.22.2); build it with ..."; no fallback was used | +| Python wheel in clean venvs: 3.14, 3.10, 3.11, 3.12, 3.13 | RAN: install exit 0 in each; the sync and the async example exit 0 and print the same (ids masked); `py.typed` and 5 `.pyi` installed under `site-packages`; `License-Expression: MIT` | +| The command copied alone to an empty directory | RAN: `layerfs 2.0.0`; the 104-line example exits 0 | +| Policy of layerfs-project#7 on the installed default command | RAN: `machine platforms` reports `firecracker` and `ssh` `ready=False` ("permanently disabled by product policy (layerfs-project#7)"); `machine create demo ssh`, `machine create demo firecracker` and `machine connect demo example.invalid` answer `Unsupported`, exit 125; the machine list (`docker`, `native`) and the number of files in the home are the same before and after | +| PostgreSQL command, tarball and wheel install and load | RAN: no missing shared library; the wheel bundles `libssl`, `libcrypto`, `libzstd` in `layerfs.libs/` (the default wheel has none); the tarball has 8 files | +| PostgreSQL builds against a port nothing listens on | RAN, all three front ends: `Unavailable` ("no connection to the server was made"), exit 125 for the command: the engine is present and tries to connect | +| Default builds against the same port | RAN, all three front ends: `Unsupported` ("this LayerFS build has no PostgreSQL engine; build it with --features postgresql"), exit 125, refused before any connection | +| Python without its native module | RAN: the message is `cannot import name '_native' from 'layerfs' (consider renaming ...)`; the clearer error of PR #598 is not in this tree | + +**NOT RUN in this re-run:** the PostgreSQL builds against a **real server**. The throwaway `postgres:17-alpine` +container could not be started: the Docker engine did not answer any command within 20-30 s (the host had about 0.6 GB +of physical memory free). The first run did exercise a real PostgreSQL 17.11 with the PostgreSQL command, addon and +wheel, but on the older tree (`ce9cd4144`), so it is not evidence for the current base. Also not repeated: the +documented setup commands of the section below, the `tls` build, and everything listed under NOT RUN. + +The sections below are the first run (the older tree), kept as history. + +## Source and tools + +| Item | Value | +| --- | --- | +| Source | `ce9cd4144` = baseline `d4304741` (`layerfs_v2_0_0`) plus four then-open PRs (scope, cli, python, node; since merged); local integration branch, never pushed. **Not the current base**: upstream changes made after `d4304741`, for example #577 (the Firecracker/SSH policy), are not in these artifacts, and the qualification was not repeated on a build of the current base | +| Build script and package changes after the builds | `35bec0c97` (`build-native.mjs --features`), `254feec2d` (`prepack`); neither changes Rust code, so the three Rust artifacts are those of this source | +| Host | Ubuntu 26.04.1 under WSL2, Linux 6.6.87.2-microsoft-standard-WSL2, x86_64, glibc 2.43 | +| Toolchain | rustc/cargo 1.85.1 (`4eb161250`), Node v24.22.2, npm 11.19.1, Python 3.14.4, maturin 1.16.0 (`pyproject.toml` asks `>=1.9.6,<2.0`) | +| Profile | `--release` for every artifact below (`CARGO_BUILD_JOBS=3`, `--locked --offline`); build times: addon 2m18s, command 49s, wheel 26s (warm shared target) | +| PostgreSQL builds | `--features postgresql`, own target dir; OpenSSL 3.0.15 headers and link stubs taken from the `rust:1.85.1-bookworm` image (the host has no `libssl-dev`), `patchelf` 0.19.3 for the wheel | + +## Artifacts + +| Artifact | sha256 | Bytes | Cargo features | +| --- | --- | --- | --- | +| Node tarball `layerfs-2.0.0.tgz` | `0511a7c19712f738e78a5dee7d4c131a6840a3571d8374c656e9fe4c4450d5e8` | 6,434,756 | default | +| addon inside it, `layerfs.node` | `14b812066276e74d63456a899fe45bfdfe65f7b0f62a1775f886345bc35054e4` | 15,695,296 | `layerfs-api/machine` | +| Python wheel `layerfs-2.0.0-cp310-abi3-manylinux_2_39_x86_64.whl` | `cfcc8f8a4419a16ef674157358b03bf6a0850a675ec3e5c5bc73129685d55527` | 6,505,248 | `machine` (default) | +| `layerfs` command | `b2face68ab5c9619c39be23f640331d2cef5e654cf2be8d01d39e768b40268bb` | 15,773,832 | `machine` (default) | +| Node tarball, PostgreSQL build | `1732e36b30575ca5445fe4dadfa81e8fbf07796a66a4b26e87c9f24c2e65e3ed` | 7,281,333 | `+postgresql` | +| addon inside it | `7ae927b2b4aecedae0e1c691cd979c073c0922b5412b08a5e03ebe35cb5ce97b` | 17,815,056 | `+postgresql` | +| Python wheel, PostgreSQL build (same name) | `a7cdbe22afa9097b17a037a246566c46f515c7f35591fb369dd983671171391a` | 10,576,475 | `+postgresql` | +| `layerfs` command, PostgreSQL build | `895289a7e79beae88dd456f8bb3e61610a7b42b7ea796c6c1f0e1ce80ac084d5` | 17,901,504 | `+postgresql` | + +Contents. Tarball (8 files): `LICENSE`, `layerfs.node`, `package.json`, +`src/{errors,index,native,values}.js`, `src/index.d.ts`. Wheel: `layerfs/` +(`__init__.py`, `_client.py`, `_errors.py`, `_values.py`, `aio.py`, a `.pyi` +for each, `py.typed`, `_native.abi3.so` sha256 `db836ad5…06e4`) and +`dist-info` (`METADATA`, `WHEEL`, `RECORD`, `licenses/LICENSE`, a CycloneDX +SBOM). The PostgreSQL wheel adds `layerfs.libs/` with `libssl`, `libcrypto` +and `libzstd` copied from the build host. + +Native dependencies (`ldd`): the default addon and command need only +`libgcc_s`, `libm`, `libc`. The PostgreSQL addon and command also need +`libssl.so.3`, `libcrypto.so.3`, `libz.so.1`, `libzstd.so.1` from the system. +`cargo tree` shows that both `postgresql` and `tls` pull `native-tls` and +`openssl-sys`. Every artifact needs `GLIBC_2.39` (`objdump -T`), so none runs +on a host older than that (for example Ubuntu 22.04 or Debian 12); not +checked on such a host. + +## Support statement + +Derived from the manifests and from what ran. + +| Artifact | Declared | Run here | +| --- | --- | --- | +| Node `layerfs` | `engines.node >=22`; `build-native.mjs` builds on macOS or Linux only, any CPU, no `CARGO_BUILD_TARGET`; one addon per package, no per-platform prebuilds | linux/x64, Node 24.22.2 | +| Python `layerfs` | `requires-python >=3.10`, abi3 (one wheel for every CPython 3.10+); wheel tag follows the build host's glibc | cp310-abi3 wheel, Python 3.14.4, linux/x64 | +| `layerfs` command | `publish = false`, no install script; Cargo 1.85.1 | linux/x64 | +| Platforms a Sandbox can use (`connect/SUPPORT.json`, Linux host) | `native` (namespaces and FUSE, root), `docker`, `microsandbox`; `apple-container` and `lima` are refused "runs on macOS hosts only"; `firecracker` and `ssh` are permanently disabled by product policy on the current base (see Machines; the artifacts here predate that policy) | none: no Sandbox was created (needs the daemon and the sealed Linux bundle) | + +Client versus execution route. The three artifacts are clients: they run the +call in the calling process (sqlite on `native`, PostgreSQL over the network) +or send it to a machine's worker. The execution routes are separate and need +the sealed Linux bundle (`tools/linux_bundle.py`), which is in no artifact; its +absence is reported as `Unsupported` with the missing path (seen on +`machine.connect`). + +## Runs from the installed artifacts + +Each in a fresh directory on ext4, `NODE_PATH`, `PYTHONPATH`, `LAYERFS_NATIVE` +and `LAYERFS_HOME` unset, a private mode-0700 home, Disposable profile. + +| Case | Result | +| --- | --- | +| `npm init -y && npm install ` in an empty project | RAN, exit 0, 1 package; the only `layerfs.node` on disk is `node_modules/layerfs/layerfs.node` | +| Node: `store.create`, `project.init`, `branch.fork`, `file.write`, `file.read`, `file.list`, `commit.list`, `doctor`, `close` | RAN, all OK (read back `"hello\n"`, list `README.md, docs`, 1 commit); table has 61 calls | +| Node: refusal `file.read` on a missing Branch | RAN, `LayerFSError` code `NoSuchBranch` | +| Node, F4: addon deleted, copies planted at `/layerfs.node`, `node_modules/crates/layerfs-node/layerfs.node` and `/crates/layerfs-node/layerfs.node` | RAN: `import "layerfs"` throws "the LayerFS native addon is missing: (the package's own; this is linux/x64, Node v24.22.2); build it with …"; no fallback. `LAYERFS_NATIVE=` loads; a junk file gives "could not be loaded … file too short" | +| Node types and licence | RAN: `src/index.d.ts` present (18,348 bytes); `package.json` `license` MIT, `LICENSE` identical to the repository's | +| `python3 -m venv` and `pip install --no-index ` | RAN, exit 0; `pip show -f`: `License-Expression: MIT`, `layerfs/py.typed` and every `.pyi` installed | +| Python: the same eight calls, refusal, `doctor`, `close` | RAN, all OK; the refusal is `LayerFSError` `NoSuchBranch` | +| Python types | RAN: `mypy --strict` on a sample using `layerfs.Result` and `file.write(..., message=)` against the installed stubs: "Success: no issues found" | +| Command copied alone to an empty directory | RAN: `layerfs --version` `layerfs 2.0.0`; `store create`, `project init`, `branch fork`, `file write` (stdin), `file read --text`, `file list --text`, `commit list`, `doctor` all exit 0; the missing-Branch refusal exits 125 with `{"code","message","detail"}` | +| Same checks with the PostgreSQL tarball, wheel and command | see below | +| Python import without the native module | RAN: `import layerfs` with `_native` hidden fails with "cannot import name '_native' from partially initialized module 'layerfs' (most likely due to a circular import)", not a message that names the missing module or the build (a finding; no fix made) | + +## PostgreSQL and TLS + +| Case | Result | +| --- | --- | +| Default tarball, wheel and command pointed at a PostgreSQL Store (`store.connect`, URL, `password: env:…`) | RAN against a reachable server: all three refuse before any connection with `Unsupported`, "this LayerFS build has no PostgreSQL engine; build it with --features postgresql"; Node and Python raise `LayerFSError`, the command exits 125. No crash, nothing created. `detail` is `null` | +| Real server | RAN: a throwaway `postgres:17-alpine` container (server 17.11) on `127.0.0.1:55555`, a separate database per client, removed afterwards (`--rm`; not in `docker ps -a`) | +| PostgreSQL command | RAN: `store connect` (kind `postgresql`), `project init`, `branch fork`, `file write` (stdin), `file read --text` returned `x`, `store status` `reachable: true`; all exit 0 | +| PostgreSQL addon (installed tarball) | RAN: `store.connect`, `project.init`, `branch.fork`, `file.write`, `file.read` (`"x\n"`), `commit.list` (1). Writing straight to `main` is refused `ReadOnly` ("main changes only through publish"), as designed | +| PostgreSQL wheel (installed in a venv) | RAN: the same chain, read back `x`, 1 commit | +| `tls` feature (https buckets) | NOT RUN: not built, no bucket. `build-native.mjs --features tls` is accepted by the script but unbuilt | +| Opt-in path | `feat` commit `35bec0c97`: `build-native.mjs [--debug] [--features postgresql,tls]`; with no flag the build is unchanged. Wrong or missing feature names exit 1 with the usage line (five cases run). The wheel needs no change (`maturin build --features`); the command uses `cargo --features` | + +Owner decision: whether published artifacts include PostgreSQL. Including it +adds an OpenSSL runtime dependency to the addon and the command (a bundled +copy in the wheel), about 2 MB to the addon and the command and 4 MB to the +wheel; the default stays feature-light. + +## Documented setup commands + +Run from the repository root of the pinned commit (a clean checkout, warm +Cargo target), `PATH` with the venv's `maturin`. + +| Command (source) | Result | +| --- | --- | +| `npm --prefix api run build:native` (api/README, quickstart) | OK, exit 0 | +| `… build:native -- --debug` with `LAYERFS_NATIVE_OUTPUT=` | OK, exit 0, 128 s cold | +| `cd api/python && maturin build --locked` (README, sdk, quickstart) | OK, exit 0 (debug wheel; docs now say `--release` for the wheel to install) | +| `cargo +1.85.1 build -p layerfs-cli` (quickstart); `… build --locked -p layerfs-cli` (node.md); `… build -p layerfs-python -p layerfs-cli` (python.md) | OK, exit 0 | +| `cp target/debug/lib_native.so api/python/src/layerfs/_native.abi3.so` (python README) | OK; `liblayerfs_python.so` is not the file name | +| `npm --prefix api run gen:types`; `python3 api/python/tools/gen_stubs.py --check` | OK, no diff | +| `node --test api/node/test/calls.mjs` | 3 pass | +| `npm --prefix api/node test` | 23 pass, 0 fail, 1 skipped (`events.mjs` exec output: `LAYERFS_DAEMON` unset, NOT RUN) | +| `python3 api/python/test/test_calls.py`; `python3 -m unittest discover -s api/python/test` | 7 tests OK (1 skipped); 39 tests OK (1 skipped, daemon) | +| `cargo +1.85.1 test --locked -p layerfs-cli --test doctor` under `alarm 100` | FAILED: exit 142 while compiling (cold test build 75 s plus the dependency build). Built first with `--no-run`, it passes: 2 passed. Fixed in the docs | +| `layerfs help`, `layerfs --version` | OK | + +Missing before this work and added to the docs: any statement of how to pack +and install the three artifacts, that `npm pack` needs the addon, the opt-in +PostgreSQL builds. Fixed: `engine/crates/layerfs-python` path (sdk.md), stale +"Linux wheels NOT_RUN" claims. Fixed in code: `npm pack` without +`layerfs.node` produced a 7-file tarball, exit 0 (npm omits a listed file that +is missing); a `prepack` check now stops it (`254feec2d`). + +Licence: workspace `Cargo.toml` MIT; `api/node/package.json` MIT, `LICENSE` +in the tarball identical to the repository's; wheel `License-Expression: MIT`, +`dist-info/licenses/LICENSE` identical. No Apache-2.0 string remains in the +checked docs. + +## Machines and `firecracker` / `ssh` (F13) + +**Corrected.** An earlier version of this section said both platforms stayed selectable. That was true of the +tree these artifacts were built from (`ce9cd4144`, baseline `d4304741` plus four PRs) and is **not** true of the +current base: the policy of layerfs-project#7 landed in `b919f50ea` ("permanently disable Firecracker and SSH +without removing adapters", #577), which `d4304741` does not contain and `02133596a` and later do. + +Checked on a debug `layerfs` command built from the current base (`02133596a`), in an empty Disposable home: + +- `machine platforms`: `firecracker` and `ssh` are `ready: false`, reason "permanently disabled by product policy + (layerfs-project#7)"; `lima` is `ready: false` ("lima runs on macOS hosts only"). +- `machine create demo ssh`, `machine create demo firecracker` and `machine connect demo example.invalid` each + answer `Unsupported` with that reason and exit 125. The machine list (`docker`, `native`) and the number of files + in the home are the same before and after, so the refusal comes before any effect. +- `machine create demo lima`: `Unsupported`, "lima runs on macOS hosts only". + +Not checked: the same refusals through the Node and Python clients (they run the same call table), and on the +release artifacts of the current base (these artifacts predate the policy). + +## NOT RUN + +macOS (native, arm64, loopback NFS), Lima, Apple Container, Microsandbox, +Firecracker, Windows, Linux aarch64, Docker machine route and every Sandbox, +Workspace and daemon-backed call (`LAYERFS_DAEMON`, no sealed bundle), other +Python versions (3.10 to 3.13) and Node versions (22, 20), hosts with glibc +below 2.39, the `tls` build and any https bucket, `project.export` (#53 not +landed), MCP (shelved), CI (unchanged). Each Linux artifact was run on one +host only. + +## Gaps and owner decisions + +1. PostgreSQL/TLS in published artifacts (above); the refusal text says "build + it with --features postgresql", which an npm or pip user cannot act on. +2. glibc floor: artifacts built here need 2.39. Release builds should come + from the oldest supported host (for example the Bookworm image the bundle + build already uses); the wheel tag would follow. +3. No publication runbook for npm or PyPI, no per-platform prebuilds or + optional dependencies, no macOS or aarch64 artifacts; `release-policy.md` + says nothing about them. Publishing is a separate release action. +4. CI excludes `layerfs-node` and the JS and Python packages (owner decision + 2026-10-23) and builds no artifact; nothing guards the pack and install + steps above. +5. `firecracker` and `ssh`: not a gap on the current base; the policy of layerfs-project#7 landed in `b919f50ea` (#577) + after the source of these artifacts (see Machines). +6. Python missing-native import error is unclear (above); the Node loader + message says "in the LayerFS repository", which does not help an + installed-package user. diff --git a/docs/versioned/2.0.0/limitations.md b/docs/versioned/2.0.0/limitations.md index 76c11043ce..dbfb89d4a1 100644 --- a/docs/versioned/2.0.0/limitations.md +++ b/docs/versioned/2.0.0/limitations.md @@ -106,7 +106,10 @@ step commits. - **One worker serving several Stores** and the guest-to-host send speed. - **Linux.** No Linux host was used. Linux namespaces Sandboxes, Init into `docker` on Linux, the Linux route of the `docker` machine (its worker, - as on macOS: #535 G8) and the Linux wheels (O20) are `NOT_RUN`. + as on macOS: #535 G8) and the Linux arm64 wheel (O20) are `NOT_RUN`. A + Linux x64 wheel, addon and command were built and installed outside the + checkout (sqlite Stores; PostgreSQL Stores only in the opt-in feature build), in + [artifact-qualification-2.0.0.md](../../general/artifact-qualification-2.0.0.md). - **Windows** (O5). `native` on Windows holds only records; its sqlite Stores and Init are meant to live in a WSL worker. Not run. The library does not build for Windows yet: `home/`, `store/`, `worker/`, `start.rs` diff --git a/docs/versioned/2.0.0/quickstart.md b/docs/versioned/2.0.0/quickstart.md index 6888e6a163..39d51c1868 100644 --- a/docs/versioned/2.0.0/quickstart.md +++ b/docs/versioned/2.0.0/quickstart.md @@ -17,8 +17,12 @@ Each example says whether it was run. "Run" means it was run on macOS - **Node.** The `layerfs` package is in `api/node`. Its native addon is built with `npm --prefix api run build:native`. - **Python.** The `layerfs` package is in `api/python`. Its module is built - with `cd api/python && maturin build --locked`; only a macOS arm64 wheel - was built on this branch. + with `cd api/python && maturin build --locked` (a debug wheel; add + `--release` for the one to install). A macOS arm64 wheel and a Linux x64 + wheel were built and installed on this branch; Linux arm64 was not. + [api/README.md](../../../api/README.md#package-and-install) lists the + steps to install the Node tarball, the wheel and the command outside the + checkout. - **A Sandbox** on the `native` machine needs the LayerFS daemon (see [Sandboxes](#4-a-sandbox-a-workspace-and-a-commit)). diff --git a/docs/versioned/2.0.0/sdk.md b/docs/versioned/2.0.0/sdk.md index 9d12a2d8ff..2b54fb4052 100644 --- a/docs/versioned/2.0.0/sdk.md +++ b/docs/versioned/2.0.0/sdk.md @@ -86,7 +86,7 @@ lfs = layerfs.client(home="/data/lfs", scope={"project": "shop/web", "folder": " ``` - Python 3.10 or later (abi3). The native module is `layerfs._native`, - built by PyO3 from `engine/crates/layerfs-python`. + built by PyO3 from `api/crates/layerfs-python`. - Calls are synchronous (O19). `layerfs.aio` has the same families and calls as coroutines; each runs the synchronous call on a thread, and the native call releases the interpreter. Its function options run on the @@ -110,9 +110,11 @@ lfs = layerfs.client(home="/data/lfs", scope={"project": "shop/web", "folder": " - `layerfs.close()` is Node's `close()`: it closes this process's open Stores, dropping their leases, and returns how many. - Build: `cd api/python && maturin build --locked` (maturin 1.9.6 or a - later 1.x, as `pyproject.toml` requires since `2793ee114c`). Only a macOS - arm64 wheel was built on this branch; the Linux x64 and arm64 glibc - wheels (O20) are `NOT_RUN`. + later 1.x, as `pyproject.toml` requires since `2793ee114c`); `--release` + for the wheel to install. A macOS arm64 wheel and a Linux x64 glibc wheel + were built and installed on this branch; the Linux arm64 wheel (O20) is + `NOT_RUN`. The installed artifacts were qualified in + [artifact-qualification-2.0.0.md](../../general/artifact-qualification-2.0.0.md). ```python import asyncio