@smthrs/platform-node 0.0.0-stage → 1.0.0-rc.4

package/CHANGELOG.md

@@ -0,0 +1,211 @@
+# @smthrs/platform-node
+
+## [Unreleased]
+
+### Fixed
+
+- Atomic glob preserves dot-class text inside an outer character class and
+  recognizes dot segments only when they occupy the whole path segment.
+
+- Atomic glob refuses unsupported POSIX classes after literal character-class
+  members, including exclusions.
+
+- Atomic glob character classes stay active when another path segment contains
+  a literal closing bracket. Globstar exclusions remove descendants even when
+  their names also match a later directory anchor, while retaining the original
+  anchor consistently across selectors and absolute or relative exclusions.
+  Unclosed brackets in an earlier segment no longer bypass unsupported-extglob
+  validation. A leading literal `]` inside a character class no longer causes
+  valid class members to be mistaken for unsupported extglob syntax.
+- Atomic glob validates unsupported syntax separately in every expanded brace
+  alternative, so a literal bracket in one alternative cannot hide an extglob
+  exclusion in another.
+- Atomic glob selection and exclusion require an explicit dot for each hidden
+  path segment. A pattern such as `.hidden/*` no longer matches `.hidden/.secret`,
+  and `**/.wanted` cannot traverse an unmentioned hidden directory. Wildcard
+  selectors also skip those directories before opening or listing them.
+- Atomic glob patterns treat `/` as a path separator inside bracket expressions,
+  preserving literal bracket names. Absolute selectors and exclusions outside
+  the glob root no longer alias an in-root path sharing the root's name prefix.
+- A `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` that names a missing or unusable
+  helper is refused with the variable's name and the same install hint as a
+  missing helper, instead of a bare `ENOENT`.
+- `AtomicFileSystem.stat` now reports `birthtime` on Linux. CPython carries the
+  creation time on `os.stat_result` only on macOS and the BSDs, so the helper
+  answered `Option.none` on Linux while `@effect/platform-node` answered the
+  instant it read through `statx`. The helper now reads `statx` itself, through
+  the C library already mapped into the process, and still answers
+  `Option.none` on any host that has no creation time to give.
+
+## [1.0.0-rc.0] - 2026-09-01
+
+### Added
+
+- Added `AtomicFileSystem`, the descriptor-relative filesystem `NodeHost` puts
+  in its filesystem slot. Every operation pins the workspace root, walks each
+  component with `O_NOFOLLOW`, and performs the final syscall relative to a
+  pinned parent descriptor, so a symlink swapped in after authorization cannot
+  redirect it. **It is a new host prerequisite**: a POSIX host with CPython 3 at
+  `/usr/bin/python3` whose `os` module supports `dir_fd` for `open`, `mkdir`,
+  `readlink`, `rename`, `rmdir`, `stat`, and `unlink`. The layer builds without
+  one and then fails every guarded filesystem call closed with
+  `PermissionDenied`; `AtomicFileSystem.layerWith({ executable })` points it at
+  an interpreter installed elsewhere. Windows is unsupported. `open`, `stream`,
+  `sink`, `watch`, `copy`, `copyFile`, `link`, `symlink`, `access`, `chmod`,
+  `chown`, `truncate`, `utimes`, and the `makeTemp*` family are refused under the
+  capability decorator rather than reverting to a path-based call.
+- Added `ProcessReaper`, which kills the process groups a crashed incarnation of
+  the same host abandoned, and `HostLiveness`, which answers whether a recorded
+  run owner is still running on this host.
+- Added `NodeHost.layerAt` and `NodeHost.layerContainedAt`, the two layers with
+  `Jj` bound to one absolute repository root rather than the process working
+  directory, and `NodeHost.layerContained`, which turns on process containment.
+- Added `AtomicFileSystem.Options.concurrency` and
+  `AtomicFileSystem.Options.timeoutMs`, with `defaultConcurrency`
+  (`os.availableParallelism()`) and `defaultTimeoutMs` (300000). Each operation
+  is one CPython fork, so without a ceiling an unbounded fan-out started one
+  interpreter per entry; without a timeout a helper that never answered held the
+  fiber until the run itself was interrupted.
+- Added `ProcessReaper.StartTime`, `ProcessReaper.SystemOptions`,
+  `ProcessReaper.posixSystemWith`, `ProcessReaper.defaultPsExecutable`, and
+  `System.refuseTarget`.
+- Added `NodeHost.ContainedOptions`.
+
+### Changed
+
+- Extracted the package from the dissolved `@smthrs/host`. `NodeHost` moved here
+  unchanged in behaviour; `NodeJj` had already moved to `@smthrs/jj` and is
+  composed from there.
+- `AtomicFileSystem.stat` now reports the raw `st_mode`, file-type bits
+  included, matching `@effect/platform-node`. It previously masked the value
+  down to its permission bits, so `mode & S_IFMT` answered zero through the
+  atomic path and correctly through the raw one.
+- Atomic system errors now carry `syscall`, which `@effect/platform-node` sets
+  on every system error it reports. It names the operation's own syscall,
+  narrowed where an operation has two (`remove` reports `unlink` or `rmdir`),
+  rather than whichever of that operation's calls raised.
+- `AtomicFileSystem.glob` now implements the grammar rather than translating it
+  into a regular expression: brace alternation, trailing-slash directory-only
+  matching, `**` spanning zero segments, the dotfile rule, subtree-pruning
+  exclusions, and absolute excludes rewritten against the glob root all now
+  agree with `node:fs.glob`. Matching is linear in the candidate's length, so a
+  pattern of repeated `*x` fragments no longer costs exponential backtracking. A
+  pattern past 4096 characters or 64 brace alternatives is a `BadArgument`; a
+  character class that opens and never closes is literal text, and `[]]` is a
+  class holding one bracket rather than an error.
+- `AtomicFileSystem.glob` now refuses the three constructs it does not implement,
+  in an exclude as well as in the pattern: extglob (`+(a|b)`), POSIX classes
+  (`[[:digit:]]`), and brace ranges (`{1..3}`) are a
+  `BadArgument`. They were read as ordinary characters, which does not fail, it
+  answers a different question: `exclude: ["+(private|secret)/**"]` excluded
+  nothing and the caller received every file under the directories it had just
+  forbidden.
+- Backslashes now follow Node's POSIX glob behavior: absolute selectors and
+  every exclusion drop them while leaving following wildcard magic active;
+  relative selectors containing one return no matches.
+- `AtomicFileSystem.glob` now enforces the 64-alternative brace bound before it
+  expands anything. The bound was checked as each expanded pattern was appended,
+  so a pattern of many brace groups exhausted the interpreter's recursion limit
+  before the first one existed: `"{,a}"` repeated 1024 times, which is exactly
+  the 4096-character pattern ceiling, answered `PermissionDenied` with
+  "descriptor-relative filesystem isolation failed closed: maximum recursion
+  depth exceeded" instead of the documented `BadArgument`. Caller input inside
+  the contract now reports as caller input.
+- `AtomicFileSystem.glob` now applies an exclusion that names the glob ROOT
+  before it walks. The root is the one directory the walk never lists, so
+  nothing applied the rule to it: `exclude: ["."]`, `[""]`, and the absolute
+  root in either spelling dropped the root's own entry and then returned every
+  path below it, charging the entry and response ceilings for a tree the caller
+  had forbidden. All four now answer with nothing and walk nothing.
+- `AtomicFileSystem.glob` now reads a one-member positive character class as the
+  literal it is, so `[.]` is a `.` path segment rather than a name no directory
+  holds. As the LAST segment it names whatever the segments before it addressed,
+  under the rule a trailing `**` already followed, with one addition: a `**`
+  immediately before it addresses nothing, so `**/[.]` names nothing while
+  `**/deep/[.]` names the directory. Anywhere else, and in an exclusion, it
+  names nothing.
+- `AtomicFileSystem.glob` no longer names a non-directory anchor from a trailing
+  `**` reached through a wildcard. `*/**` returned every top-level FILE as well
+  as the directories, `t*.txt/**` returned `top.txt`, and `**/mid.txt/**`
+  returned `nested/mid.txt`, where `node:fs.glob` returns only directories,
+  nothing, and nothing. A trailing `**` names its anchor when the anchor is a
+  directory, or when every segment before it is literal, which is the shortcut
+  the native globber takes when it can address the path directly.
+- `AtomicFileSystem.glob` now reads a character class as a class when it looks
+  for the extglob syntax it refuses. `[!(]*` is a negated class holding one
+  paren, and `node:fs.glob` answers it with real matches; it was refused as
+  `BadArgument` because the scan saw `!` followed by `(`.
+- `AtomicFileSystem.glob` exclusions now prune the walk instead of filtering
+  its result. An excluded directory was listed in full first, so its names were
+  counted against the 100000-entry ceiling and charged against the response
+  ceiling: a glob whose answer was two paths could fail `BadResource` because of
+  a directory the caller had excluded.
+- `AtomicFileSystem.glob` matching is case-sensitive on every host, and says so
+  in the documentation. `node:fs.glob` passes `nocase: isMacOS || isWindows`
+  with `nocaseMagicOnly: true`, so the same pattern means different things on
+  macOS and on Linux, and a magic segment means something different from a
+  literal one on macOS. One host-independent rule is pinned instead, alongside
+  the exclusion's trailing-`**` answer, which Node itself gives differently
+  depending on the selecting pattern's shape.
+- `AtomicFileSystem.Options.timeoutMs` now refuses a value above 2147483647.
+  `setTimeout` clamps a longer delay to one millisecond, so asking for a longer
+  backstop produced no backstop at all: every operation failed instantly with
+  "atomic helper did not answer within 2147483648 ms".
+- `ProcessReaper` now requires its own process group to be printed as decimal
+  digits and nothing else. `Number.parseInt` reads a PREFIX, so a `ps` answering
+  `"2147483646 x"` produced a number that is not this host's group: the
+  own-group comparison passed on a false identity, and because the answer was
+  not `null` the `own-group-unknown` refusal that reports an unmade comparison
+  never fired either, leaving a `SIGKILL` authorized by a guard that never ran.
+- `AtomicFileSystem.remove(path, { force: true })` now succeeds for a path whose
+  ancestors do not exist, as `fs.rm` does. Recursive removal walks iteratively
+  with an explicit descriptor stack, bounded at 512 levels and 100000 entries,
+  counted as each directory is read, so a hostile wide directory is refused
+  rather than allocated whole.
+- `AtomicFileSystem` reads every option except `executable` once, when the layer
+  is built, so a mutated options object cannot change a ceiling under a running
+  host. The concurrency ceiling is one semaphore per layer.
+- `NodeHost.layerContained` and `layerContainedAt` no longer accept
+  `ContainedSpawner.Options.platform`. A caller-supplied `"win32"` used to win
+  the option spread on a POSIX host, recording `pgid: null` for a child that
+  really did lead a group; the reaper then refused that record as `no-group` and
+  the orphan outlived every incarnation.
+- `ProcessReaper` refuses a record it cannot verify instead of signalling it. An
+  absent, unanswerable, or unparseable `ps` used to read as "no refusal" and a
+  recycled process group was `SIGKILL`ed on the strength of a record the host
+  could not check. `System.startedAtMs` now returns a tagged `StartTime`, the
+  probe runs from an absolute `/bin/ps` with `LC_ALL=C`, an empty-ish
+  environment, and a finite timeout, and the new `identity-unverified` refusal
+  keeps the record for an incarnation that can answer. A nonzero `ps` exit is
+  confirmed against the kernel before a record is retired as `process-gone`,
+  because it is also how a `ps` that rejected the column answers about a live
+  pid.
+- `ProcessReaper` refuses a record with the new `own-group-unknown` when it could
+  not read its OWN process group. That comparison is what stops the sweep
+  signalling the shell this host runs in, and it is read from `ps` like the start
+  time, so it can go unanswered on its own; the record is kept for an incarnation
+  that can make the comparison rather than signalled on a guard that did not run.
+- `ProcessReaper` validates a durable record's numbers before signalling them.
+  `pgid: 0` reached `process.kill(-0, "SIGKILL")`, which signals this host's own
+  process group; POSIX now requires a safe `pgid` above 1 equal to `pid`, and
+  Windows requires `pgid: null`, with the check repeated inside each `killTree`.
+- Windows records now reach `taskkill` through `reap`. They carry `pgid: null`,
+  which was refused as `no-group` before `killTree` was consulted, so
+  `windowsSystem` was unreachable and every Windows orphan was retired
+  unsignalled. Windows remains outside the 1.0.0-rc.0 support contract and this
+  path is unsupported best-effort.
+- Moved the package's published documentation into `docs/` and `docs/Manifest.ts`.
+  `docs/pages/api/platform-node.md` is generated from package sources and said,
+  until now, that the package "adds no implementation of its own".
+
+### Removed
+
+- `NodeHttpTransport` is gone. An outgoing request is Effect's `HttpClient`,
+  and `NodeHost.layer` now provides `@effect/platform-node`'s
+  `NodeHttpClient.layerUndici` directly. Undici installs no redirect
+  interceptor, so every hop stays a separate request `@smthrs/kernel` can
+  authorize. `NodeHost` re-exports `NodeHttpClient` for selective wiring.
+- `NodeShell` is gone. Process execution is Effect's `ChildProcessSpawner`, and
+  `NodeHost.layer` now provides `@effect/platform-node`'s implementation of it
+  directly. The wrapper's one extra feature, `timeoutMs`, is `Effect.timeout`
+  around any effect.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# @smthrs/platform-node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+**Documentation:** https://platform-node.smithers.sh
+
+The Node.js Host bundle for Smithers. One layer, `NodeHost.layer`, provides the
+five services a program runs its side effects through: a filesystem, a path
+helper, a child-process spawner, a [Jujutsu](https://jj-vcs.github.io/jj/)
+adapter, and an HTTP client.
+
+`@effect/platform-node` already ships Node implementations of most of those, and
+this package uses them where they fit. Three guarantees are not ones a
+general-purpose adapter makes, so this package implements them itself:
+
+- **A filesystem a symlink cannot redirect.** `AtomicFileSystem` opens the
+  workspace root once, walks each component with `O_NOFOLLOW`, and performs the
+  final syscall relative to a pinned directory descriptor, so a path swapped
+  between the permission check and the operation cannot redirect it.
+- **Child processes a crashed host does not leave behind.**
+  `NodeHost.layerContained` gives every child a `SIGTERM`-then-`SIGKILL`
+  deadline and a durable ledger record, and sweeps the records a previous
+  incarnation abandoned while the layer is built.
+- **An honest answer about whether a run's owner is still alive.**
+  `HostLiveness.isAlive` is the probe a durable engine consults before it takes
+  a run some other process recorded itself as owning. Ambiguity resolves toward
+  alive, because stranding a run is cheaper than running it twice.
+
+## Availability
+
+`@smthrs/platform-node` is not on npm at 1.0.0-rc.0. Its source lives in the
+[smithers repository](https://github.com/smithersai/smithers), and the
+[installation page](https://platform-node.smithers.sh/installation/) covers how
+to depend on it from a checkout and the `effect` version it pins.
+
+On POSIX, filesystem confinement requires Node.js 26.4.0 or later and the
+`smithers-jj-export` native helper. From a source checkout, build it with:
+
+```sh
+cargo build --locked --release -p smithers-ffi --bin smithers-jj-export
+```
+
+Install the Rust toolchain `rust-toolchain.toml` pins with `rustup toolchain install`
+if needed. The host finds `target/release/smithers-jj-export`
+automatically. Packaged installs supply a platform helper; an operator-managed
+installation can set `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` to its absolute path.
+A missing helper refuses confined operations, including MCP flow discovery.
+
+## Run a command through the host
+
+```ts
+import { NodeHost } from "@smthrs/platform-node"
+import { Effect } from "effect"
+import * as ChildProcess from "effect/unstable/process/ChildProcess"
+import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
+
+const program = Effect.gen(function*() {
+  const spawner = yield* ChildProcessSpawner
+  return yield* spawner.string(ChildProcess.make("git", ["status", "--short"]))
+})
+
+Effect.runPromise(Effect.provide(program, NodeHost.layer))
+```
+
+`ChildProcess` and `ChildProcessSpawner` are Effect's own tags. The same layer
+also provided the `FileSystem`, `Path`, `Jj`, and `HttpClient` that program did
+not ask for.
+
+## Layers
+
+| Layer                              | What it adds                                                      |
+| ---------------------------------- | ----------------------------------------------------------------- |
+| `NodeHost.layer`                   | the five tags, with `Jj` bound to the process working directory   |
+| `NodeHost.layerAt(root)`           | the same, with `Jj` pinned to one absolute repository root        |
+| `NodeHost.layerContained(options)` | process containment: kill deadlines, ledger records, a reap sweep |
+| `NodeHost.layerContainedAt(...)`   | both, which is what the flow engine's `NodeRuntime` composes      |
+
+The contained layers require a `ProcessLedger`, because the durable half of
+containment is only as good as the journal underneath it. `ProcessLedger.layer`
+inherits a crashed incarnation's processes; `ProcessLedger.layerMemory` contains
+this one and nothing more.
+
+```ts
+import { ProcessLedger } from "@smthrs/kernel"
+import { NodeHost } from "@smthrs/platform-node"
+import { Layer } from "effect"
+
+const host = Layer.provide(
+  NodeHost.layerContained({ graceMs: 2000 }),
+  ProcessLedger.layer({ hostId: "engine-1", ownerPid: process.pid })
+)
+```
+
+The contained spawner prepares a supervisor and records its identity before
+activating the target. On POSIX `handle.pid` names that owner, while
+`exitCode` and `isRunning` describe the target. Natural target exit still
+cleans up its owned group, including children holding output open. Use the
+handle's `kill` for signal delivery; cleanup failure retains the ledger record.
+`ScopedProcess` supplies this lifetime policy for transient commands without a
+durable ledger, and exposes the separate native `Handle.targetPid` for diagnostics.
+
+Complete host bundles require jj 0.39.0 or newer. Construction probes the binary through its selected runner; a contained host records and retires this probe in its process ledger and can fail with `JjError` (`not_installed` or `unsupported_version`). Repository commands use the selected process runner.
+
+## Modules
+
+The barrel exports four namespaces: `NodeHost`, `HostLiveness`,
+`ProcessReaper`, and `ScopedProcess`. `AtomicFileSystem` is deliberately not among them; it is reached
+as `NodeHost.AtomicFileSystem` or through the
+`@smthrs/platform-node/AtomicFileSystem` subpath.
+
+| Module             | What it provides                                                                                                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `NodeHost`         | the complete closed Host bundle, plus re-exports of `AtomicFileSystem`, `ProcessReaper`, `NodeCrypto`, and Effect's raw `NodeFileSystem`, spawner, and `HttpClient`                  |
+| `AtomicFileSystem` | the descriptor-relative, no-follow filesystem layer and its options, ceilings, and glob grammar                                                                                      |
+| `HostLiveness`     | whether a recorded run owner is still alive: `isAlive`, `Owner`, `Options`                                                                                                           |
+| `ProcessReaper`    | live containment and restart reconciliation: `layerSpawner`, `SpawnerOptions`, `processLifecycle`, `reap`, `layer`, `System`, `Refusal`, `posixSystem`, `windowsSystem`, `systemFor` |
+| `ScopedProcess`    | transient scoped commands with the same lifecycle: `Options`, `Handle`, `spawn`, `Status`, `status`                                                                                  |
+
+`NodeCrypto` is re-exported for a different reason than the rest: `Crypto` is not
+a Host service, so it is not in the closed list, but every durable composition
+needs one and a program that already depends on this package for its host should
+not need a second dependency for the digest.
+
+## What the bundle does not provide
+
+**There is no shell service.** Running a command is Effect's `ChildProcess` and
+`ChildProcessSpawner`, so a wall-clock budget is `Effect.timeout` around the
+effect and cancellation is fiber interruption, not an `AbortSignal`.
+
+**There is no HTTP service.** An outgoing request is Effect's `HttpClient`,
+provided here as `NodeHttpClient.layerUndici`. Undici installs no redirect
+interceptor, so every hop stays a separate, checkable request.
+
+Both are what lets [`@smthrs/kernel`](https://kernel.smithers.sh) check
+`proc:spawn` against the rendered command line before any process starts, and
+`net:get` / `net:post` against the host of every URL a request reaches,
+redirect targets included. Wrap the bundle in its `HostServices.layer` to get
+that permission-aware projection.
+
+## Where this sits
+
+[`@smthrs/flows`](https://flows.smithers.sh) is the durable flow engine: flows,
+actions, the journal, and the runtime that replays a crashed run from where it
+stopped. It deliberately re-exports no `@smthrs/platform-*` package, for the
+same reason `effect`'s own index does not re-export `@effect/platform-node`:
+the program that runs picks its platform. So a Node program installs
+`@smthrs/flows` for the engine and this package for the machine underneath it,
+and its `NodeRuntime` composes `NodeHost.layerContainedAt` plus
+`HostLiveness.isAlive` from one options object.
+
+## Read next
+
+The documentation site covers the rest: [the host bundle](https://platform-node.smithers.sh/concepts/host-bundle/), [the descriptor-relative filesystem](https://platform-node.smithers.sh/concepts/descriptor-relative-filesystem/)
+and everything it refuses, [process containment](https://platform-node.smithers.sh/concepts/process-containment/)
+and every guard checked before a reap, the [API reference](https://platform-node.smithers.sh/reference/api/), and
+[troubleshooting](https://platform-node.smithers.sh/troubleshooting/).
+
+For a different runtime, the sibling bundles are
+[`@smthrs/platform-bun`](https://platform-bun.smithers.sh) and
+[`@smthrs/platform-browser`](https://platform-browser.smithers.sh).
+
+The host exports `implementationIds` for its five service slots. Its rooted
+factories reject invalid roots before constructing a layer, using the host's
+own error with code `invalid_repository_root`.
+
+The atomic filesystem supports descriptor-based `chmod` and `chown` on regular files so replacements can preserve permissions and ownership. Symlinks, hard-linked files, directories, and special files are refused by this boundary.

package/bin/linux-x64/smithers-jj-export

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/bin/linux-x64/smithers-jj-export
+size: 53554360 bytes
+sha256: 082aad5f9ca4c16a4bf1ad78225e1c0e1677141913c3a5601c586f8a8a5fdb08

package/dist/cjs/AtomicFileSystem.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Descriptor-relative filesystem operations through the packaged Rust helper.
+ * The helper pins the workspace root and walks each component with O_NOFOLLOW.
+ * Requests and responses are length-framed, size-limited, and cancellable.
+ * @since 0.1.0
+ */
+import { FileSystem, Layer } from "effect";
+export { AtomicHelperError, AtomicHelperErrorCode } from "./internal/AtomicHelperError.ts";
+/**
+ * The legacy system installation path, used after package and checkout paths.
+ * Helper selection never consults `PATH` or the process working directory.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const defaultExecutable = "/usr/local/bin/smithers-jj-export";
+/**
+ * Byte ceilings for the helper protocol. Every one of them is a contract, not
+ * a tuning knob: without them a large file, a large directory tree, or a
+ * malfunctioning helper makes the host allocate until it dies.
+ *
+ * - `content` bounds the bytes a single `readFile`/`writeFile` may carry.
+ * - `request` bounds the framed request; an over-limit request is refused
+ *   before an helper is even started.
+ * - `response` bounds the framed response, and is what a directory listing is
+ *   charged against as it is built. It bounds the REJECTION envelope too, so a
+ *   ceiling small enough to cut one off degrades that operation's typed reason
+ *   to the fail-closed one.
+ * - `stderr` bounds the diagnostic text retained from a failing helper.
+ * - `batchEntry` bounds one batch member's encoded success or failure envelope.
+ * - `batchSize` bounds the number of operations in one batch, at most 128.
+ *
+ * All except `batchSize` count bytes. The two ceilings that decide whether the host
+ * survives a wide fan-out are {@link Options.concurrency}, which bounds how
+ * many helpers run at once, and {@link Options.timeoutMs}, which bounds
+ * how long any one of them may take.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Limits {
+    readonly content: number;
+    readonly request: number;
+    readonly response: number;
+    readonly stderr: number;
+    /** Maximum operations in one helper invocation, at most 128. */
+    readonly batchSize: number;
+    /** Maximum encoded result bytes for one batch member. */
+    readonly batchEntry: number;
+}
+/**
+ * 16 MiB of file content, 24 MiB of framed request and response (base64
+ * expands 16 MiB to 22369624 bytes, which has to fit), and 64 KiB of retained
+ * helper diagnostics.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const defaultLimits: Limits;
+/**
+ * The default number of helper processes that may run at once:
+ * `os.availableParallelism()`.
+ *
+ * @since 1.0.0-rc.0
+ * @category constants
+ */
+export declare const defaultConcurrency: number;
+/**
+ * How long one helper may run before it is killed and the operation fails
+ * closed: five minutes.
+ *
+ * It is a backstop, not a latency budget. A read at the content ceiling over a
+ * slow disk has to fit under it, so it is generous; what it bounds is a helper
+ * that will never answer at all.
+ *
+ * @since 1.0.0-rc.0
+ * @category constants
+ */
+export declare const defaultTimeoutMs = 300000;
+/**
+ * The deliberate seam for a POSIX host that installs the native helper somewhere other
+ * than {@link defaultExecutable}, or that needs different ceilings. It is
+ * configuration, never discovery: the executable is validated as an absolute,
+ * executable regular file outside the confined workspace on every request, and
+ * every other field is read ONCE, when the layer is built.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Options {
+    readonly executable?: string | undefined;
+    readonly limits?: Partial<Limits> | undefined;
+    /**
+     * How many helper processes may run at once. Default
+     * {@link defaultConcurrency}.
+     *
+     * Each ordinary operation or batch starts one helper, so an unbounded
+     * `Effect.forEach` over a directory would start
+     * one helper per entry. This ceiling is what keeps a wide fan-out from
+     * pinning every core; it is a contract, not a tuning knob.
+     */
+    readonly concurrency?: number | undefined;
+    /**
+     * How long one helper may run before it is killed and the operation fails
+     * closed, in milliseconds. Default {@link defaultTimeoutMs}.
+     */
+    readonly timeoutMs?: number | undefined;
+}
+/**
+ * Process-local helper starts, for cost counters and local measurements.
+ * Includes helpers later cancelled or refused; rejected preflight starts none.
+ *
+ * @since 1.0.0
+ * @category metrics
+ */
+export declare const helperSpawns: () => number;
+/**
+ * The helper this process would start for an atomic operation, resolved exactly
+ * as an operation resolves it: `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY`, then the
+ * packaged and checkout locations. Nothing is spawned. Throws an {@link AtomicHelperError} whose
+ * message names what was searched and how to install the helper when none is
+ * usable, so a diagnostic can report it before any operation needs it.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare const resolveHelper: () => string;
+/**
+ * A Node filesystem layer carrying the kernel's atomic host extension, built
+ * against an explicitly configured helper, byte limits, process ceiling,
+ * and helper timeout.
+ *
+ * Every field of {@link Options} except `executable` is read once, here. The
+ * concurrency ceiling is one semaphore for the whole layer rather than one per
+ * request, which is the only arrangement that bounds anything.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export declare const layerWith: (options: Options) => Layer.Layer<FileSystem.FileSystem>;
+/** A Node filesystem layer carrying the kernel's atomic host extension.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+export declare const layer: Layer.Layer<FileSystem.FileSystem>;
+//# sourceMappingURL=AtomicFileSystem.d.ts.map

package/dist/cjs/AtomicFileSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AtomicFileSystem.d.ts","sourceRoot":"","sources":["../../src/AtomicFileSystem.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAU,UAAU,EAAE,KAAK,EAAoC,MAAM,QAAQ,CAAA;AAapF,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AAE1F;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,sCAAsC,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,MAO3B,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAA+B,CAAA;AAEhE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,SAAU,CAAA;AAEvC;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IAC7C;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAgBD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,QAAO,MAA6B,CAAA;AAqJ7D;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,QAAO,MAA0C,CAAA;AAuB3E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,OAAO,KAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAuD7E,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,CAAiB,CAAA"}