From e6335c541a1b767cce7fad12836a18c3000685db Mon Sep 17 00:00:00 2001 From: root Date: Thu, 5 Nov 2026 08:45:45 -0800 Subject: [PATCH 1/6] feat(api): let build-native.mjs enable the PostgreSQL and TLS features The addon build script accepted only --debug, so an addon with PostgreSQL Stores or https buckets could not be built through it. It now takes an explicit opt-in list, `--features postgresql,tls`, and passes it on to `cargo build -p layerfs-node`. Only those two names are accepted; with no flag the build is unchanged (no features), and anything else is still the usage error. Co-Authored-By: Claude Sonnet 5.5 --- api/scripts/build-native.mjs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) 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); From 54b522eae32c2c45b6cf393fc45f98d26857c81e Mon Sep 17 00:00:00 2001 From: Mola-maker Date: Thu, 5 Nov 2026 23:14:33 -0800 Subject: [PATCH 2/6] fix(node): make npm pack refuse a package without its addon `files` lists layerfs.node, and npm silently leaves a listed file out when it does not exist: packing without a prior `build:native` gave a tarball of 7 files, exit 0, that cannot load. A prepack script now stops with a message naming the build command. Co-Authored-By: Claude Sonnet 5.5 --- api/node/package.json | 1 + 1 file changed, 1 insertion(+) 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", From 7d9d51af3a2d93eaecab5b918a2f86501ca0e4ba Mon Sep 17 00:00:00 2001 From: Mola-maker Date: Thu, 5 Nov 2026 23:14:52 -0800 Subject: [PATCH 3/6] docs(api): state how to package and install the three artifacts Every documented command was run from a checkout; none said how to get the Node tarball, the wheel or the command onto another machine. api/README.md now has the pack and install steps for each, the opt-in PostgreSQL/TLS builds and what they need (OpenSSL headers, patchelf), and that `npm pack` refuses without the addon. The Python guide says `maturin build` is a debug wheel. Also corrected: the stale `engine/crates/layerfs-python` path, the "Linux wheels NOT_RUN" claims now that a Linux x64 wheel was built and installed, and the doctor test command, whose cold build overruns the 100 s limit unless built first with --no-run. Co-Authored-By: Claude Sonnet 5.5 --- api/README.md | 34 ++++++++++++++++++++++ api/python/README.md | 7 +++++ docs/architecture/api/front-ends/README.md | 4 ++- docs/architecture/api/front-ends/node.md | 2 +- docs/versioned/2.0.0/limitations.md | 5 +++- docs/versioned/2.0.0/quickstart.md | 8 +++-- docs/versioned/2.0.0/sdk.md | 10 ++++--- 7 files changed, 61 insertions(+), 9 deletions(-) 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/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/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/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 From dcbd6e29e6b52bc5c949e50a1a76b1014a58ea84 Mon Sep 17 00:00:00 2001 From: Mola-maker Date: Thu, 5 Nov 2026 23:16:48 -0800 Subject: [PATCH 4/6] docs(general): record the 2.0.0 artifact qualification on Linux x64 Pins the source, toolchain, sha256 and contents of the Node tarball, the Python wheel and the layerfs command (release profile, default and PostgreSQL builds), and records what ran from the installed files outside a checkout: sqlite and PostgreSQL operations, the missing-addon refusal, the shipped typings and licence, the documented setup commands, and how firecracker and ssh respond. Lists what did not run and the owner decisions (PostgreSQL/TLS in published artifacts, glibc floor, publication, CI). Co-Authored-By: Claude Sonnet 5.5 --- docs/general/artifact-qualification-2.0.0.md | 181 +++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/general/artifact-qualification-2.0.0.md 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..5a05ca4d53 --- /dev/null +++ b/docs/general/artifact-qualification-2.0.0.md @@ -0,0 +1,181 @@ +# 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. + +## Source and tools + +| Item | Value | +| --- | --- | +| Source | `ce9cd4144` = baseline `d4304741` (`layerfs_v2_0_0`) plus four open PRs (scope, cli, python, node); local integration branch, never pushed | +| 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`, `ssh`; `apple-container`, `lima`, `firecracker` are refused "runs on macOS hosts only" | 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) + +`connect/SUPPORT.json` lists `firecracker` and `ssh` for macOS, Linux and +Windows hosts. A search of `support.rs`, `lib.rs` and `layerfs-control/src/machine` for a +switch that disables either finds none. Through +every installed client (Node, Python, command) on this Linux host: + +- `machine.create fc1 firecracker`: `InvalidInput` "a firecracker machine + names its lima --nested host"; with `--host nolima --nested`: `InvalidInput` + "only a lima machine is nested". Both are argument checks: the platform is + accepted as a value, so it is selectable at the API level. +- `machine.create l1 lima`: `Unsupported`, "lima runs on macOS hosts only". +- `machine.connect box1 127.0.0.1 --user root` (ssh): `Unsupported`, "no sealed + Linux bundle at …/linux-x86_64"; it reaches the ssh adapter and stops on the + missing bundle, not on a disabled platform. + +A real firecracker or ssh machine was not created (no Lima, no bundle, no +host). Issue #7's "disabled as selectable" is not enforced at this source. + +## 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` stay in `SUPPORT.json` and are accepted by + `machine.create` and `machine.connect` (above). +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. From e51087b30853e58a95efd0c2c53e2033f5baa9ed Mon Sep 17 00:00:00 2001 From: Mola-maker Date: Fri, 6 Nov 2026 07:25:03 -0800 Subject: [PATCH 5/6] docs(general): correct the Firecracker and SSH finding of the artifact report The report said both platforms stayed selectable. That held for the tree the artifacts were built from (d4304741 plus four PRs) but not for the current base, which contains the policy of layerfs-project#7 (b919f50ea, #577). Replace the section with what a command built from the current base does (not ready, Unsupported before any effect), drop the gap, and state in the Source row that the artifacts predate that upstream change. Co-Authored-By: Claude Sonnet 5.5 --- docs/general/artifact-qualification-2.0.0.md | 36 ++++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/general/artifact-qualification-2.0.0.md b/docs/general/artifact-qualification-2.0.0.md index 5a05ca4d53..23b350a691 100644 --- a/docs/general/artifact-qualification-2.0.0.md +++ b/docs/general/artifact-qualification-2.0.0.md @@ -11,7 +11,7 @@ repeated. Anything not listed as RAN was not run. | Item | Value | | --- | --- | -| Source | `ce9cd4144` = baseline `d4304741` (`layerfs_v2_0_0`) plus four open PRs (scope, cli, python, node); local integration branch, never pushed | +| 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`) | @@ -56,7 +56,7 @@ Derived from the manifests and from what ran. | 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`, `ssh`; `apple-container`, `lima`, `firecracker` are refused "runs on macOS hosts only" | none: no Sandbox was created (needs the daemon and the sealed Linux bundle) | +| 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) @@ -134,22 +134,22 @@ checked docs. ## Machines and `firecracker` / `ssh` (F13) -`connect/SUPPORT.json` lists `firecracker` and `ssh` for macOS, Linux and -Windows hosts. A search of `support.rs`, `lib.rs` and `layerfs-control/src/machine` for a -switch that disables either finds none. Through -every installed client (Node, Python, command) on this Linux host: +**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. -- `machine.create fc1 firecracker`: `InvalidInput` "a firecracker machine - names its lima --nested host"; with `--host nolima --nested`: `InvalidInput` - "only a lima machine is nested". Both are argument checks: the platform is - accepted as a value, so it is selectable at the API level. -- `machine.create l1 lima`: `Unsupported`, "lima runs on macOS hosts only". -- `machine.connect box1 127.0.0.1 --user root` (ssh): `Unsupported`, "no sealed - Linux bundle at …/linux-x86_64"; it reaches the ssh adapter and stops on the - missing bundle, not on a disabled platform. +Checked on a debug `layerfs` command built from the current base (`02133596a`), in an empty Disposable home: -A real firecracker or ssh machine was not created (no Lima, no bundle, no -host). Issue #7's "disabled as selectable" is not enforced at this source. +- `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 @@ -174,8 +174,8 @@ host only. 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` stay in `SUPPORT.json` and are accepted by - `machine.create` and `machine.connect` (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. From 9d7c5c91d64c2a38b4abe81a0d04dd2a993f5c4d Mon Sep 17 00:00:00 2001 From: Mola-maker Date: Fri, 6 Nov 2026 07:52:03 -0800 Subject: [PATCH 6/6] docs(general): repeat the artifact qualification on the current base The first run used artifacts built before #577 and later upstream changes. Rebuild the default and PostgreSQL artifacts from the current base and record the identity, hashes and results: Node 24 and 22, Python 3.10 to 3.14, the command alone, the Firecracker/SSH policy on the installed command, and the PostgreSQL and default builds against a port nothing listens on. The real PostgreSQL server run could not be repeated because the Docker engine did not answer; say so. The older sections stay as history. Co-Authored-By: Claude Sonnet 5.5 --- docs/general/artifact-qualification-2.0.0.md | 51 ++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/general/artifact-qualification-2.0.0.md b/docs/general/artifact-qualification-2.0.0.md index 23b350a691..0d8d3a0e07 100644 --- a/docs/general/artifact-qualification-2.0.0.md +++ b/docs/general/artifact-qualification-2.0.0.md @@ -7,6 +7,57 @@ 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 |