@smthrs/kernel 0.0.0-stage → 1.0.0-rc.4

package/CHANGELOG.md

@@ -0,0 +1,206 @@
+# @smthrs/kernel
+
+## [Unreleased]
+
+### Added
+
+- `FileSystem.confined(fileSystem, root)` returns a filesystem view whose every
+  path operation is one descriptor-relative, no-follow request against `root`,
+  pinned by canonical path and `device:inode` identity, without a grant check.
+  Engine machinery uses it so its own writes cannot be redirected by a symlink
+  swap. It refuses a plain path-based host with `PermissionDenied`, returns an
+  isolated volume or the guarded `FileSystem.layer` service for the same root
+  as it is, and refuses operations that are not one atomic request.
+  `isConfinable` and `requireConfinable` check a host at composition time.
+- `@smthrs/kernel/Rooted` binds unguarded `FileSystem`, `Path` and
+  `ChildProcessSpawner` services to one root directory. `Rooted.spawner` keeps
+  a contained spawner's containment mark. It replaces the TUI's private copy.
+
+### Changed
+
+- `ChildProcessSpawner.layer` and `Path.layer` now require `Workspace`. A
+  command with no or a relative `cwd` runs in `Workspace.root`, and relative
+  paths resolve there, instead of in `process.cwd()`. The grant check sees the
+  resolved directory.
+
+### Fixed
+
+- `HttpClient.layer` honors a caller's explicit `RequestInit { redirect: "manual" }`
+  by returning one authorized hop. Callers can own their redirect loop and hop
+  limit without a second loop following redirects underneath them. Default
+  redirect following and authorization on every hop are preserved.
+- `HttpClient.layer` forces `RequestInit { redirect: "manual" }` below its
+  guard, so composing it over a plain `FetchHttpClient.layer`, which follows
+  redirects by default, can no longer fetch a redirect target without a grant
+  check.
+- `JournalGrantStore` no longer tells an operator to compact a full policy
+  journal. Replay never reads a checkpoint, so compaction broke every later
+  construction; the message now says to start a new `policyRunId`.
+- The internal `@slop` review markers no longer ship in the published
+  declarations. Every export they marked already carries its prose.
+
+## [1.0.0-rc.0] - 2026-08-31
+
+### Changed
+
+- **`HttpTransport` is gone; network access is Effect's own `HttpClient`**
+  (maintainer directive, 2026-08-10). `@smthrs/kernel/HttpTransport` — the
+  raw one-hop port — is deleted, and `HttpClient` is now middleware over
+  `effect/unstable/http`'s `HttpClient` tag rather than a kernel-owned service
+  projected off that port. The kernel declares no HTTP interface, no HTTP tag,
+  and no `executeModel` method: it re-exports Effect's tag and `make`, and adds
+  `layer`, a `TransportError`-reporting `makeNoop` / `layerNoop` stub, and the
+  `toHttpClientError` / `fromHttpClientError` projection.
+  - A `model:call` check is requested with the new `ModelCall` context
+    reference, set by `HttpClient.withModelCall(modelId)` around the request,
+    in place of the removed `executeModel` method.
+  - Permission failures now ride in `HttpClientError`, the channel Effect's tag
+    fixes: reason `TransportError`, `description` the one-line rendering, and
+    `cause` the structured `PermissionRequired` / `PermissionDenied` /
+    `GrantStoreError`. `HttpClient.fromHttpClientError` reads it back.
+  - **Redirects.** The old port existed so a redirect could not bypass
+    enforcement. The invariant is preserved with Effect alone: host bundles
+    provide a client that never follows a redirect on its own (fetch with
+    `RequestInit { redirect: "manual" }`, Undici with no redirect interceptor),
+    and the decorator composes Effect's own `HttpClient.followRedirects`
+    _above_ the guard, so each hop re-enters the guarded `postprocess` and is
+    authorized independently.
+  - `HostServices` slot 5 is now Effect's `HttpClient` tag and its
+    `HostServiceIds` entry changes from `@smthrs/kernel/HttpTransport` to
+    `effect/HttpClient`. **This changes step-key identity**: every cached step
+    that named the network slot is invalidated, which is the intent.
+
+- **One tag per protected service** (maintainer directive, 2026-08-10).
+  Enforcement is now middleware over the service's _own_ tag —
+  `Layer.effect(Tag, Effect.gen(function*() { const raw = yield* Tag; … }))`
+  composed over the platform layer with `Layer.provide` — instead of a widened
+  redeclaration of the interface behind a second tag plus an
+  `as unknown as` cast to force the guarded implementation back onto the raw
+  one. Those widened service-interface casts are gone; narrow casts remain for
+  the atomic filesystem extension, process and journal identities, and
+  validated immutable snapshots.
+  - `FileSystem` and `ChildProcessSpawner` no longer export a kernel
+    interface, tag, `make`, `makeNoop`, or `layerNoop` for the service itself;
+    Effect's are the ones to use. `FileSystem` keeps `canonicalResource` and
+    `layer`; `ChildProcessSpawner` keeps `layer` plus a `NotFound`-reporting
+    `makeNoop` / `layerNoop` stub, and re-exports Effect's tag and `make`.
+  - `Jj` no longer redeclares `@smthrs/jj`'s interface. It re-exports that
+    package's tag, `make`, `makeNoop`, and `layerNoop`, and adds `layer`.
+  - `HostServices` collapses to one closed list: `ProtectedHostService` and
+    `ProtectedHostServiceTags` are gone. `HostServiceIds` is unchanged — the
+    service identities did not change, only the plumbing.
+- Permission failures on Effect-owned services are projected into the native
+  `PlatformError` channel by the new `Permission.toPlatformError`: the reason
+  is the normalized `PermissionDenied` system-error tag, `description` is the
+  one-line rendering of the failure, and `cause` carries the structured
+  `PermissionRequired` / `PermissionDenied` / `GrantStoreError`.
+  `Permission.fromPlatformError` reads it back, so the attended surface and
+  unattended reporting lose nothing.
+- `Capability` and `Permission` moved to the new leaf package
+  `@smthrs/capability` and are re-exported from the root barrel unchanged;
+  only the deep imports move (`@smthrs/kernel/Capability` →
+  `@smthrs/capability/Capability`, same for `Permission`). The split exists
+  so `@smthrs/jj` can
+  declare the permission failures its guarded interface adds without depending
+  on the kernel that already depends on it. Every schema id is frozen and
+  unchanged (`@smthrs/kernel/Capability`, `@smthrs/kernel/PermissionDenied`, …)
+  because they round-trip through the grant journal.
+- Attended suspension on a `Deferred`, unattended fail-fast, and terminal
+  denial keep their existing `GrantStore` behavior.
+- **HTTP capability resources now make non-`https` schemes explicit.** GET and
+  HEAD use `net:get` and every other method uses `net:post`. An `https:` URL
+  uses its lowercased host as the resource; every other scheme uses
+  `<scheme>//<lowercased host>`. `model:call` follows the same rule before
+  appending `/<model id>`, so a grant for an HTTPS host no longer admits a
+  cleartext downgrade.
+- **The 1,024-envelope ceiling now covers the construction envelope.**
+  `GrantStore.make` refuses a new construction envelope, rather than persisting
+  it, once the replayed signatures already fill the ceiling — the bound
+  `grantEnvelope` has always applied at reply time. A durable history can
+  therefore never outgrow what a later construction will replay.
+  `JournalGrantStore` reports an already-grown history with a message naming
+  the policy run and both signature counts, the way it already reports an
+  oversized replayed rule set, instead of the bare
+  `envelopeSignatures exceed 1024 entries`.
+
+### Added
+
+- Added `ContainedSpawner`, process middleware that applies the
+  `SIGTERM`-then-`SIGKILL` deadline to every command and records each child in
+  `ProcessLedger` until its spawn scope closes.
+- Added `ProcessLedger` with durable and in-memory layers, the
+  `SpawnedEventType`, `ExitedEventType`, `ReapedEventType`, and
+  `SkippedEventType` wire constants, and replay of process records abandoned
+  by a dead host incarnation.
+- Added the atomic-host filesystem extension:
+  `withAtomicFileSystem` installs a descriptor-relative, no-follow executor,
+  `withIsolatedFileSystem` attests a whole isolated browser or test volume, and
+  guarded filesystem operations fail closed when a host declares neither.
+- Added `canonicalEnvelopePatterns` and `envelopeSignature` so envelope
+  approvals have one deduplicated, order-independent durable identity.
+- Added `CommandLine`, which renders an `effect/unstable/process` `Command` back
+  to a POSIX command line. One renderer, two callers: the `proc:spawn`
+  capability resource and the interpreter or remote sandbox that executes the
+  line, so a grant and the thing it authorizes cannot drift apart. `shell: true`
+  keeps shell syntax verbatim, while a custom shell path is named explicitly in
+  the rendered invocation and therefore in the permission resource.
+- Added `ChildProcessSpawner`, the permission decorator over Effect's own
+  spawner. The check is suspended inside `spawn`, so building a `Command` or a
+  stream neither asks permission nor starts a process; the derived helpers
+  (`exitCode`, `string`, `lines`, `stream*`) are rebuilt from the guarded
+  `spawn` so none can route around it; and `layer` double-publishes onto
+  Effect's tag, so a `Command` run as a plain `Effect` is checked too.
+- Absorbed the dissolved `@smthrs/host`: `HostError`, the
+  closed `HostServices` list, the shared contract suite (now
+  `@smthrs/kernel/test/contract`), and the deterministic `TestHost` bundle
+  (`@smthrs/kernel/test/TestHost`, Node-only) live here.
+
+### Fixed
+
+- A spawn whose ledger record fails is now signalled and removed from
+  `ProcessLedger.live` before the failed spawn returns.
+- `withIsolatedFileSystem` refuses a filesystem that already carries a
+  descriptor-relative executor instead of silently replacing it with a
+  path-delegating one.
+- Replayed remembered rules are deduplicated, and a policy journal past the
+  1,024-rule ceiling now fails with the policy run id and the configured,
+  replayed, and total rule counts.
+- Made capability sets, grant inputs/results, Host request descriptions, and
+  byte buffers immutable snapshots rather than aliases to caller-owned state.
+- Added finite GrantStore policy, envelope, pending-request, metadata, event,
+  and identity limits with field-specific typed failures.
+- Added complete Host conformance matrices, observable child liveness, exact
+  refused-operation codes, and clean packed-consumer coverage for the public
+  test contract.
+
+### Removed
+
+- Removed the `Pty` decorator, and with it the `flows/host/Pty` slot from the
+  closed list, `PtyError` from `HostError`, and the `@smthrs/pty` package from
+  the workspace. The contract had no production consumer and its Node
+  implementation was piped stdio, not a pseudo-terminal. Interactive-terminal
+  support belongs to a higher-level harness extension, not the closed Host
+  surface — see D13 in `docs/pages/design-decisions.md` and
+  `docs/specs/Concepts/No Pty In Core.md`.
+- Removed the `Shell` decorator and the raw `Shell` port. Process execution is
+  `effect/unstable/process`; the closed list's third slot now holds Effect's own
+  tag and its id is `effect/process/ChildProcessSpawner`. That id change is
+  deliberate and invalidates cached steps that ran a command: the service
+  really is different, so the step really is different.
+- Removed `ShellError`, `ShellErrorCode`, and `shellError` from `HostError`. A
+  spawn fails with `PlatformError`, like the rest of `effect`'s platform
+  surface.
+
+## [0.1.0] - 2026-08-05
+
+### Added
+
+- Added the effect-aware capability model, monotone attenuation, journaled grant store, and mandatory decoration of the original Host and Effect service tags.
+- Added tier-preserving grant validation, canonical filesystem confinement, single-hop HTTP transport enforcement, browser-bundle coverage, and dual ESM/CJS package artifacts.
+
+### Fixed
+
+- Switched Host integration to its current public service subpaths and made the browser root entrypoint Node-free.
+- Corrected configured-policy last-match-wins evaluation, journaled one-call grants, and resumed every pending waiter covered by run grants.
+- Added plan-digest-bound run and remembered envelopes, same-run grant replay, trusted journal envelope validation, and duplicate-free resume.
+- Preserved grant-store lifecycle failures in the typed stable-code channel and emitted identity-safe non-bundled CJS modules.

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,155 @@
-# Temporary Holding Version
+# @smthrs/kernel
 
-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).
+
+This package declares `effect` as an exact
+`4.0.0-rc.115` peer dependency. Keep the application on that version so
+all Smithers packages share one Effect runtime.
+
+**Documentation:** https://kernel.smithers.sh
+
+A capability kernel for [Effect](https://effect.website) hosts. It puts a
+permission check in front of every side effect a program can reach: the five
+service tags a host provides, `FileSystem`, `Path`, `ChildProcessSpawner`,
+`HttpClient`, and `Jj`, are decorated in place, so each operation is named as a
+capability, checked against a grant store, and refused with a typed error when
+nobody authorized it.
+
+Decorating in place is the point. A protected second service only guards the
+callers who agreed to use it, and the first dependency that reaches for the
+ordinary `FileSystem` tag walks straight past it. Once this layer is composed,
+the guarded implementation is what the tag resolves to, so there is no
+unguarded one left to reach for. Code that calls `fs.readFileString` is checked
+without ever mentioning permission.
+
+## Install
+
+`@smthrs/kernel` 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://kernel.smithers.sh/installation/) covers how to
+depend on it from a checkout, the import forms, and the two test helpers.
+
+It needs Node.js 26.4.0 or later and `effect` 4.0.0-rc.115. It carries no
+platform implementations of its own, so a composition that reaches a real
+machine also adds a bundle such as
+[`@smthrs/platform-node`](https://platform-node.smithers.sh).
+
+## Refuse an operation nobody authorized
+
+This program composes the kernel over the deterministic host from
+`@smthrs/testing/TestHost`. Add `"@smthrs/testing": "workspace:*"` to the
+consuming package's devDependencies before running it. The policy allows reads
+under the workspace and says nothing about writes:
+
+```ts
+import { Capability, GrantStore, HostServices, Permission, Workspace } from "@smthrs/kernel"
+import * as TestHost from "@smthrs/testing/TestHost"
+import { Effect, FileSystem, Layer } from "effect"
+
+const rules = [
+  new Permission.Rule({
+    effect: "allow",
+    pattern: new Capability.CapabilityPattern({ action: "fs:read", resource: "/workspace/**" })
+  })
+]
+
+const guarded = HostServices.layer.pipe(
+  Layer.provide(Layer.orDie(GrantStore.layer({ attended: false, rules }))),
+  Layer.provideMerge(TestHost.layer({ files: { "/workspace/README.md": "# hello" } })),
+  Layer.provide(Workspace.layer("/workspace"))
+)
+
+/** Ordinary Effect code. Nothing here knows a kernel exists. */
+const program = Effect.gen(function*() {
+  const fs = yield* FileSystem.FileSystem
+  const readme = yield* fs.readFileString("/workspace/README.md")
+  yield* fs.writeFileString("/workspace/out.txt", readme)
+})
+
+Effect.runPromise(program.pipe(Effect.provide(guarded), Effect.scoped))
+```
+
+The read returns `"# hello"`. The write never reaches the filesystem. Effect
+fixes that method's error channel to `PlatformError`, so the kernel projects
+its refusal into one and keeps the structured original on the cause, where
+`Permission.fromPlatformError` reads it back as a `PermissionRequired` naming
+`fs:write` on `/workspace/out.txt`.
+
+`permission_required`, not `permission_denied`: no rule matched, silence is not
+consent, and this store has nobody to ask. Build the store with
+`attended: true` instead and the same write parks on a request an operator can
+answer, then resumes the operation it was authorized for. The
+[quickstart](https://kernel.smithers.sh/quickstart/) runs both halves.
+
+## What a yes or no answer leaves open
+
+- **Confinement.** A path is authorized as a canonical resource and the
+  operation runs through a pinned directory descriptor, so a symlink or a
+  rename between the decision and the call cannot redirect it. A host that
+  cannot address the real filesystem attests whole-volume isolation instead; a
+  path-only adapter is unsupported and fails closed.
+- **Containment.** A cancelled run signals its children, escalates to
+  `SIGKILL` on a deadline, and records each child in a durable ledger, so a
+  host that dies leaves orphan records its successor can reap.
+- **A ceiling that only narrows.** `CapabilitySet.attenuate` bounds what a
+  fiber may ask for, and no public operation widens it again.
+- **Grants that outlive the process.** A decision is written to a journal
+  before it takes effect, so a permission a person chose to remember is still
+  in force after a restart.
+
+## Public API
+
+The root entry point exports these namespaces, and each is also importable from
+`@smthrs/kernel/<Module>`. Every export, with its signature and its bounds, is
+on the [API reference](https://kernel.smithers.sh/reference/api/).
+
+| Namespace             | What it is                                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `Capability`          | The vocabulary a decision is made in: actions, exact capabilities, patterns, matching, and effect tiers.     |
+| `Permission`          | The typed failure contract, plus policy rules and their evaluation.                                          |
+| `CapabilitySet`       | The authority ceiling. `attenuate` narrows it; no public operation widens it again.                          |
+| `GrantStore`          | The service that decides: check a capability, park a request, reply to it, and the bounds every value obeys. |
+| `JournalGrantStore`   | A grant store that replays and persists its decisions through `Journal`.                                     |
+| `GrantEvent`          | The durable grant vocabulary: once, remembered, run, denied, and envelope grants, with their schema.         |
+| `HostServices`        | The closed list of five host slots, and the aggregate layer that decorates all of them in place.             |
+| `FileSystem`          | The guarded filesystem, its canonical resources, and the confinement a host attaches at its boundary.        |
+| `HttpClient`          | The guarded HTTP client: `net:get`, `net:post`, `model:call`, and every redirect hop rechecked.              |
+| `ChildProcessSpawner` | The guarded spawner over Effect's own tag.                                                                   |
+| `ContainedSpawner`    | A `SIGTERM`-then-`SIGKILL` deadline on every child, and a ledger entry released when its scope closes.       |
+| `ProcessConfinement`  | Host confinement for approved processes, derived conservatively from effective grants and ceilings.          |
+| `ProcessLedger`       | The durable record of spawned processes, and the `orphans` a dead host leaves its successor to reap.         |
+| `CommandLine`         | The one renderer shared by the `proc:spawn` capability resource and the interpreters that run the line.      |
+| `Jj`                  | The guarded [Jujutsu](https://jj-vcs.github.io) repository port over `@smthrs/jj`'s own tag.                 |
+| `Path`                | Effect's `Path`, passed through unchecked by decision.                                                       |
+| `Workspace`           | The root that filesystem capability resources are resolved against.                                          |
+
+`ChildProcessEnvironment` builds a replacement environment from bootstrap names plus explicit declarations, withholding credential-shaped ambient values.
+
+`Capability` and `Permission` are re-exports; their modules live in
+[`@smthrs/capability`](https://capability.smithers.sh).
+
+Two test helpers ship in the package's export map, not as dev-only files:
+`@smthrs/kernel/test/TestGrantStore` for allow, deny, and scripted grant-store
+doubles and `@smthrs/kernel/test/contract` for `runHostContract`, the behavioral
+contract every host bundle must satisfy (`test/HostContract` is an alias).
+The contract is Node-only. The
+deterministic host bundle lives at `@smthrs/testing/TestHost` so the kernel does
+not depend back on a platform implementation.
+
+## Documentation
+
+- [Overview](https://kernel.smithers.sh)
+- [Quickstart](https://kernel.smithers.sh/quickstart/)
+- [Guard a host bundle](https://kernel.smithers.sh/guides/guard-a-host-bundle/)
+- [Write a capability policy](https://kernel.smithers.sh/guides/write-a-capability-policy/)
+- [Decoration in place](https://kernel.smithers.sh/concepts/decoration-in-place/)
+- [API reference](https://kernel.smithers.sh/reference/api/)
+- [Troubleshooting](https://kernel.smithers.sh/troubleshooting/), which lists
+  every refusal this package raises, what it means, and what to change.
+
+`@smthrs/kernel` is one package of the Smithers durable flow engine, which
+ships whole as [`@smthrs/flows`](https://flows.smithers.sh).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/cjs/CapabilitySet.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The shared monotone authority implementation used by declarations and guards.
+ * @since 1.0.0
+ */
+export * from "@smthrs/capability/CapabilitySet";
+//# sourceMappingURL=CapabilitySet.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CapabilitySet.d.ts","sourceRoot":"","sources":["../../src/CapabilitySet.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,kCAAkC,CAAA"}

package/dist/cjs/CapabilitySet.js

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var CapabilitySet_exports = {};
+module.exports = __toCommonJS(CapabilitySet_exports);
+__reExport(CapabilitySet_exports, require("@smthrs/capability/CapabilitySet"), module.exports);
+//# sourceMappingURL=CapabilitySet.js.map

package/dist/cjs/CapabilitySet.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/CapabilitySet.ts"],
+  "sourcesContent": ["/**\n * The shared monotone authority implementation used by declarations and guards.\n * @since 1.0.0\n */\n\nexport * from \"@smthrs/capability/CapabilitySet\"\n"],
+  "mappings": ";;;;;;;;;;;;;;;AAAA;AAAA;AAKA,kCAAc,6CALd;",
+  "names": []
+}

package/dist/cjs/ChildProcessEnvironment.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Least-authority environment construction for child processes.
+ *
+ * @since 1.0.0-rc.0
+ */
+/**
+ * Credential-bearing field names shared with the model request boundary.
+ *
+ * `token`, `key` (optionally followed by a separated `id`), and `pat` are
+ * anchored to complete or separator-delimited suffixes so names such as
+ * `TOKEN_COUNT` and `KEYBOARD` remain ordinary diagnostics. Keeping this rule
+ * below the model and process layers gives request validation and child
+ * spawning one definition of a sensitive name.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const credentialNamePattern: RegExp;
+/**
+ * Reports whether a field name conventionally carries credentials.
+ *
+ * @category predicates
+ * @since 1.0.0-rc.0
+ */
+export declare const isCredentialName: (name: string) => boolean;
+/**
+ * Ambient variables a child may inherit for executable lookup, identity,
+ * locale, terminal behavior, temporary files, and its shell.
+ *
+ * Locale category variables are admitted separately by their `LC_` prefix.
+ *
+ * @category constants
+ * @since 1.0.0-rc.0
+ */
+export declare const inheritedNames: ReadonlyArray<string>;
+/**
+ * Reports whether a variable belongs to the bootstrap set {@link make}
+ * inherits: one of {@link inheritedNames} or a locale `LC_` category,
+ * compared case-insensitively.
+ *
+ * @category predicates
+ * @since 1.0.0-rc.1
+ */
+export declare const isInheritedName: (name: string) => boolean;
+/**
+ * Selects the bootstrap allowlist from an ambient environment and overlays
+ * caller-declared names.
+ *
+ * Sensitive-looking ambient names are withheld even if a future bootstrap
+ * list grows to include one. A caller declaration is applied last because it
+ * is the explicit authority for that child; an `undefined` declaration
+ * removes an inherited name. The returned null-prototype record is always
+ * suitable as a replacement environment and never asks the spawner to merge
+ * the rest of the host process environment.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const make: (ambient: Readonly<Record<string, string | undefined>>, declared?: Readonly<Record<string, string | undefined>>) => Record<string, string>;
+//# sourceMappingURL=ChildProcessEnvironment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ChildProcessEnvironment.d.ts","sourceRoot":"","sources":["../../src/ChildProcessEnvironment.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,QACoR,CAAA;AAEtT;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,OAA2C,CAAA;AAE3F;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,MAAM,CAQ/C,CAAA;AAIF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,OAG9C,CAAA;AASD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,IAAI,GACf,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACrD,WAAU,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAM,KAC1D,MAAM,CAAC,MAAM,EAAE,MAAM,CAUvB,CAAA"}

package/dist/cjs/ChildProcessEnvironment.js

@@ -0,0 +1,61 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ChildProcessEnvironment_exports = {};
+__export(ChildProcessEnvironment_exports, {
+  credentialNamePattern: () => credentialNamePattern,
+  inheritedNames: () => inheritedNames,
+  isCredentialName: () => isCredentialName,
+  isInheritedName: () => isInheritedName,
+  make: () => make
+});
+module.exports = __toCommonJS(ChildProcessEnvironment_exports);
+const credentialNamePattern = /authorization|api[-_]?key|access[-_]?token|refresh[-_]?token|id[-_]?token|auth[-_]?token|api[-_]?token|session[-_]?token|bearer|(?:^|[-_])token$|(?:^|[-_])key(?:[-_]id)?$|(?:^|[-_])pat$|secret|credential|password|passphrase|passwd|signature|x-amz-signature|cookie|set[-_]?cookie|chatgpt[-_]?account[-_]?id/i;
+const isCredentialName = (name) => credentialNamePattern.test(name);
+const inheritedNames = Object.freeze([
+  "PATH",
+  "HOME",
+  "USER",
+  "LANG",
+  "TERM",
+  "TMPDIR",
+  "SHELL"
+]);
+const inherited = new Set(inheritedNames);
+const isInheritedName = (name) => {
+  const canonical = name.toUpperCase();
+  return inherited.has(canonical) || canonical.startsWith("LC_");
+};
+const remove = (environment, name) => {
+  const canonical = name.toUpperCase();
+  for (const present of Object.keys(environment)) {
+    if (present.toUpperCase() === canonical) delete environment[present];
+  }
+};
+const make = (ambient, declared = {}) => {
+  const environment = /* @__PURE__ */ Object.create(null);
+  for (const [name, value] of Object.entries(ambient)) {
+    if (value !== void 0 && isInheritedName(name) && !isCredentialName(name)) environment[name] = value;
+  }
+  for (const [name, value] of Object.entries(declared)) {
+    remove(environment, name);
+    if (value !== void 0) environment[name] = value;
+  }
+  return environment;
+};
+//# sourceMappingURL=ChildProcessEnvironment.js.map

package/dist/cjs/ChildProcessEnvironment.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/ChildProcessEnvironment.ts"],
+  "sourcesContent": ["/**\n * Least-authority environment construction for child processes.\n *\n * @since 1.0.0-rc.0\n */\n\n/**\n * Credential-bearing field names shared with the model request boundary.\n *\n * `token`, `key` (optionally followed by a separated `id`), and `pat` are\n * anchored to complete or separator-delimited suffixes so names such as\n * `TOKEN_COUNT` and `KEYBOARD` remain ordinary diagnostics. Keeping this rule\n * below the model and process layers gives request validation and child\n * spawning one definition of a sensitive name.\n *\n * @category constants\n * @since 1.0.0-rc.0\n */\nexport const credentialNamePattern =\n  /authorization|api[-_]?key|access[-_]?token|refresh[-_]?token|id[-_]?token|auth[-_]?token|api[-_]?token|session[-_]?token|bearer|(?:^|[-_])token$|(?:^|[-_])key(?:[-_]id)?$|(?:^|[-_])pat$|secret|credential|password|passphrase|passwd|signature|x-amz-signature|cookie|set[-_]?cookie|chatgpt[-_]?account[-_]?id/i\n\n/**\n * Reports whether a field name conventionally carries credentials.\n *\n * @category predicates\n * @since 1.0.0-rc.0\n */\nexport const isCredentialName = (name: string): boolean => credentialNamePattern.test(name)\n\n/**\n * Ambient variables a child may inherit for executable lookup, identity,\n * locale, terminal behavior, temporary files, and its shell.\n *\n * Locale category variables are admitted separately by their `LC_` prefix.\n *\n * @category constants\n * @since 1.0.0-rc.0\n */\nexport const inheritedNames: ReadonlyArray<string> = Object.freeze([\n  \"PATH\",\n  \"HOME\",\n  \"USER\",\n  \"LANG\",\n  \"TERM\",\n  \"TMPDIR\",\n  \"SHELL\"\n])\n\nconst inherited = new Set(inheritedNames)\n\n/**\n * Reports whether a variable belongs to the bootstrap set {@link make}\n * inherits: one of {@link inheritedNames} or a locale `LC_` category,\n * compared case-insensitively.\n *\n * @category predicates\n * @since 1.0.0-rc.1\n */\nexport const isInheritedName = (name: string): boolean => {\n  const canonical = name.toUpperCase()\n  return inherited.has(canonical) || canonical.startsWith(\"LC_\")\n}\n\nconst remove = (environment: Record<string, string>, name: string): void => {\n  const canonical = name.toUpperCase()\n  for (const present of Object.keys(environment)) {\n    if (present.toUpperCase() === canonical) delete environment[present]\n  }\n}\n\n/**\n * Selects the bootstrap allowlist from an ambient environment and overlays\n * caller-declared names.\n *\n * Sensitive-looking ambient names are withheld even if a future bootstrap\n * list grows to include one. A caller declaration is applied last because it\n * is the explicit authority for that child; an `undefined` declaration\n * removes an inherited name. The returned null-prototype record is always\n * suitable as a replacement environment and never asks the spawner to merge\n * the rest of the host process environment.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const make = (\n  ambient: Readonly<Record<string, string | undefined>>,\n  declared: Readonly<Record<string, string | undefined>> = {}\n): Record<string, string> => {\n  const environment = Object.create(null) as Record<string, string>\n  for (const [name, value] of Object.entries(ambient)) {\n    if (value !== undefined && isInheritedName(name) && !isCredentialName(name)) environment[name] = value\n  }\n  for (const [name, value] of Object.entries(declared)) {\n    remove(environment, name)\n    if (value !== undefined) environment[name] = value\n  }\n  return environment\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBO,MAAM,wBACX;AAQK,MAAM,mBAAmB,CAAC,SAA0B,sBAAsB,KAAK,IAAI;AAWnF,MAAM,iBAAwC,OAAO,OAAO;AAAA,EACjE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAED,MAAM,YAAY,IAAI,IAAI,cAAc;AAUjC,MAAM,kBAAkB,CAAC,SAA0B;AACxD,QAAM,YAAY,KAAK,YAAY;AACnC,SAAO,UAAU,IAAI,SAAS,KAAK,UAAU,WAAW,KAAK;AAC/D;AAEA,MAAM,SAAS,CAAC,aAAqC,SAAuB;AAC1E,QAAM,YAAY,KAAK,YAAY;AACnC,aAAW,WAAW,OAAO,KAAK,WAAW,GAAG;AAC9C,QAAI,QAAQ,YAAY,MAAM,UAAW,QAAO,YAAY,OAAO;AAAA,EACrE;AACF;AAgBO,MAAM,OAAO,CAClB,SACA,WAAyD,CAAC,MAC/B;AAC3B,QAAM,cAAc,uBAAO,OAAO,IAAI;AACtC,aAAW,CAAC,MAAM,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AACnD,QAAI,UAAU,UAAa,gBAAgB,IAAI,KAAK,CAAC,iBAAiB,IAAI,EAAG,aAAY,IAAI,IAAI;AAAA,EACnG;AACA,aAAW,CAAC,MAAM,KAAK,KAAK,OAAO,QAAQ,QAAQ,GAAG;AACpD,WAAO,aAAa,IAAI;AACxB,QAAI,UAAU,OAAW,aAAY,IAAI,IAAI;AAAA,EAC/C;AACA,SAAO;AACT;",
+  "names": []
+}