@jini-ai/platform 0.3.0 → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# @jini-ai/platform
+
+## 0.5.1 — 2026-10-04
+
+- `./secrets` exports the canonical site-key names (`SiteKeyHandle`, `FixedSiteKeyKeyring`, `UnusableSiteKeyError`, `SiteKeyFileAlreadyExistsError`, `parseSiteKeyHex`, `fingerprintSiteKeyHex`, `inspectSiteKeyMaterial`, `revealSiteKeyMaterial`, `generateFileSiteKey`, `deriveFromSiteKey`, `deriveSigningSecretFromSiteKey` and the matching types). Every `RootKey*` name stays exported as a `@deprecated` alias of the same binding, to be removed on or after 2026-11-01. Additive: no behavior or signature change.
+
+## 0.5.0 — 2026-10-02
+
+### BREAKING
+
+- Use canonical core ports and platform ./net and ./fs/file-lock. Analytics and trash moved to their domain packages; credential scope and durable filesystem contracts changed.
+- Distribution includes runtime output, release documentation and required assets only. Process records and per-job neutrality checks are no longer part of the package surface.
+
+## Unreleased
+
+### Compilation fixes
+
+- Omit an absent guarded HTTP abort signal to satisfy the canonical request contract.
+- Import the mail adapter's HTTP port from core primitives and type the key-rotation test
+  fake against `KeyringPort`, preserving its assertions and behavior.
+
+### Breaking domain extraction
+
+- Remove `./analytics` and the analytics root namespace; import the standalone `@jini-ai/analytics` package.
+- Remove `./trash` and the trash root namespace; import `@jini-ai/cms/trash`.
+- Move both capabilities' behavior tests with their source; platform retains only generic OS/transport capabilities.
+
+
+### Shared platform primitives
+
+- BREAKING: HTTP primitive types now come from `@jini-ai/core/primitives`; guarded HTTP exports
+  `GuardedClock` with `nowMs()` and `timeoutSignal({ timeoutMs })`. Mail uses the kernel clock.
+  Analytics primitive declarations also come from core. Add core as a regular dependency.
+- BREAKING: address classifiers move from asset-cache.ts to `./net`; `isPrivateAddress` and
+  `expandIpv6` take `{ address }`. The root IP-classifier export points to the canonical module.
+- Add `./fs/file-lock` async/sync token-and-inode-owned locks sharing one stale decision.
+  Durable JSON retains its lock budgets, user copy, read/quarantine behavior and JSON bytes.
+- BREAKING: the synchronous atomic filesystem seam owns descriptors and exposes open/sync/close/
+  lstat as well as existing mode/rename/remove effects. Add file and directory fsync and owned-temp
+  failure cleanup; move `tempName` into argument two as an optional token factory with the native pid.UUID default. Add async file/JSON
+  writers, secret-mode verification, optional symlink refusal, and sidecar newline/parent support.
+  Durable JSON delegates to the canonical writer, retains its temp layout/new-file mode, and gains
+  exclusive temp creation, cleanup on failure, and directory fsync.
+- Add exported `defaultPlatformMessages` with host replacement seams. Egress refusal and invalid
+  root-key recovery warnings use neutral defaults. Keyring source-permission flags and derivation
+  formats are unchanged. Tests and builds are deferred by the owner.
+
+- Security defaults: purpose-gated mail validates runtime modes at composition; only explicit local mode bypasses readiness. Root-key adapters require an injected environment reader and explicit fallback/generation booleans. Fresh inspection/reveal also require that reader. Existing wire derivation is unchanged.
+
+- Guarded HTTP restores per-socket inactivity timeouts. Requests accept explicit
+  `idleTimeoutMs`, with `timeoutMs` retained as its legacy alias and the historical
+  `connectTimeoutMs` policy ceiling applied per socket. Optional `totalDeadlineMs`
+  bounds DNS, all redirects and decoded body reads independently; it is off by default.
+  Idle failures retain `Error("request timed out after …ms")`; explicit deadline failures
+  use `FetchTimeoutError`. Slow but progressing transfers are no longer cut off by
+  an implicit total deadline. Verification is deferred by owner directive.
+
+### Integration finish pass
+
+- Complete Node runtime metadata for every export, the filesystem barrel, and additive root
+  namespaces for `./http/guarded`, `./mail`, `./mail/smtp`, `./fs`, `./fs/guarded-reader`,
+  `./fs/durable-json`, `./analytics`, `./trash`, `./secrets`, `./secrets/credential-sets`,
+  and `./secrets/testing`. No version change or dependency addition.
+- BREAKING (new extraction APIs): native factories and transport/memory constructors take `{}`;
+  keyring `activeKey`, mailer `capabilities`, clock/random methods and durable JSON `read` take
+  `{}`. SMTP transport `sendMail` takes `{ mail }`; the native nodemailer payload remains
+  behind `NativeSmtpTransport`. Analytics/trash policy errors take `{ message }` and optional
+  `{ cause }`. Existing legacy root functions retain their compatibility signatures.
+- Reconcile the export-map contract test and remove application names from analytics fixtures.
+  Verification of this finish pass is deferred by owner directive.
+
+- Add privacy analytics ingest with required HKDF context and privacy policy, injectable hash/hook seams, and a recent-hit memory sink.
+- Add trash write/sweep orchestration with required retention/entity policy, reentrant transaction ports, host scheduler, record-store adapter, and optional follow-ups in arg 2.
+- Add `./fs` with mode-preserving atomic file/JSON writes, narrow env-text transforms, and strict lexical containment; keep all existing filesystem exports unchanged.
+
+- Add guarded outbound HTTP with injected DNS, pinned transport, clock, policy, and required user agent. Reuse existing address validation and timeout errors. Preserve redirect refusal and response-byte contracts.
+- Add mail contracts, a purpose/readiness gate, delivery capability checks, and an optional SMTP subpath over a host-supplied transport/module; no new dependency.
+- Add contained and bounded file readers with caller-owned deny rules/limits, and durable JSON file operations with injectable filesystem, time, liveness, sleep, randomness, and notices.
+- Convert the unpublished secrets surface to required-object/optional-object signatures; preserve pinned derivation, AAD, ciphertext, and envelope bytes.
+
+## 0.4.0
+
+### Minor Changes
+
+- Add `./secrets` with AES-256-GCM sealing, root-key ports, explicit env/file and fixed-key
+  adapters, HKDF helpers, and root-key validation, status, reveal, and exclusive generation.
+  Env names, key paths, and HKDF salts are caller-supplied, with no defaults. New seals require
+  AAD; opening historical ciphertext without AAD remains supported. The ciphertext envelope
+  and derivation labels are preserved and covered by pinned vectors.
+- Add `./secrets/credential-sets` with generic vendor credential records, repository contracts,
+  the stable v1 AAD builder, and a memory repository. Add `./secrets/testing` with ephemeral and
+  fixed root-key adapters and the memory repository. Existing exports and dependencies are unchanged.
+
+## 0.1.2
+
+### Patch Changes
+
+- Add top-level `main`/`types` fields alongside the existing `exports` map. A consumer on
+  TypeScript's classic `moduleResolution: "node"` (node10) — which ignores `package.json#exports`
+  entirely — could not resolve this package's types at all (`TS2307: Cannot find module`) even
+  after the previous exports-map fix restored `require()` at runtime; type resolution and runtime
+  resolution are separate algorithms. Verified against a real external consumer (whose
+  tsconfig uses this legacy resolution mode): adding these two fields, with its tsconfig completely
+  unchanged, made the error disappear. Also fixes absolute-path `require()` (distinct from a bare
+  specifier, which already worked) for the same reason — `main` was previously absent.
+
+  Purely additive: every modern resolver (Node's own runtime `exports` resolution, TypeScript's
+  `bundler`/`node16`/`nodenext`) prefers `exports` over `main`/`types` when both are present, so
+  this changes nothing for a consumer already on a modern resolver.
+
+## 0.1.1
+
+### Patch Changes
+
+- Add a `"default"` export condition to every published package's `exports` map — every one of
+  them lacked it, which meant `require()` failed with `ERR_PACKAGE_PATH_NOT_EXPORTED` for any
+  CommonJS consumer (found via a real external integration attempt; Node needs `require(esm)`
+  support, i.e. Node >=22.12, for this to resolve).
+
+  `@jini-ai/agent-runtime`:
+
+  - **New**: `RuntimeBuildOptions.permissionMode` (`'bypass' | 'restricted'`) lets a caller opt a
+    run OUT of the auto-approve-every-permission-prompt flag every def with one
+    (`bypassPermissions` / `--yolo` / `--dangerously-skip-permissions`) previously pushed
+    unconditionally, with no way to turn it off. Omitting it keeps today's default (bypass)
+    behavior unchanged.
+  - **New**: `ClaudeStreamEvent`, `CopilotStreamEvent`, and `QoderEvent` are now real exported
+    discriminated unions instead of `Record<string, unknown>` — a real external consumer guessed a
+    nonexistent field name (`event.text` instead of the actual `event.delta`) against the old
+    untyped sink and silently lost every streamed token with no compile or runtime error.
+  - Fixed a doc/implementation mismatch in `claude-stream.ts`: the module doc claimed `tool_result`
+    events carry `{ tool_use_id, content, is_error }`; the actual emitted shape is
+    `{ toolUseId, content, isError }`.
+
+  `@jini-ai/daemon`: `AgentExecutorRunInput.permissionMode` forwards the new
+  `RuntimeBuildOptions.permissionMode` through to `buildArgs`, so a host can actually reach the new
+  opt-out from the daemon's real run-input surface, not just from `@jini-ai/agent-runtime` in
+  isolation.
+
+  `@jini-ai/agentic`: `setAtPointer` no longer throws on a malformed (e.g. missing leading `/`)
+  `updateDataModel` path — degrades to a no-op like its sibling `getAtPointer`, matching this
+  package's own "a bad binding must not crash the renderer" contract. That path is agent-authored
+  wire data with no error boundary above it in any host, so the uncaught throw could unmount an
+  entire chat UI from ~40 bytes of malformed input.
+
+  `@jini-ai/chat-react`: a local (client-resolved) A2UI button action is no longer a silent no-op —
+  `A2uiSurfaceCard` now surfaces the resolved value. New `ExtEventErrorBoundary` confines a
+  `kind: 'ext'` event group's renderer to its own card instead of letting a render/effect-phase
+  throw from agent-controlled content unmount the whole chat root (there was no error boundary
+  anywhere in this package or its hosts before this).

package/README.md

@@ -6,7 +6,7 @@ This is the Node-only substrate a daemon host needs to spawn and supervise child
 for a port to come up, resolve a user's installed toolchains, manage terminal (PTY) sessions, and
 store blobs — all without depending on `@jini-ai/daemon` or any product code. Ported mostly
 verbatim from Open Design's own `packages/platform` plus several generic daemon-support files
-that were split out of OD's monolithic daemon (see `source-map.md` for the full per-file trail).
+that were split out of OD's monolithic daemon (see the archived provenance ledger for the full per-file trail).
 
 ## Install
 
@@ -85,4 +85,123 @@ ESM only — ships `"type": "module"` with no CommonJS `require` build.
 
 ## Provenance
 
-See [source-map.md](./source-map.md) for per-file provenance and scope decisions. Apache-2.0.
+See the archived provenance ledger for per-file provenance and scope decisions. Apache-2.0.
+# Additional subpaths
+
+The package also exposes `./http/guarded`, `./mail`, `./mail/smtp`,
+`./fs/guarded-reader`, `./fs/durable-json`, and `./secrets`. New APIs take a required
+object followed by an optional object. Application identity and policy values belong to the caller.
+
+```ts
+import { createHttpClient, createNodeGuardedHttpPorts, guardedFetch } from "@jini-ai/platform/http/guarded";
+
+const client = createHttpClient({
+  ...createNodeGuardedHttpPorts({}),
+  userAgent: "MyApplication/1.0",
+  policy: {
+    allowedSchemes: ["https"], denyPrivateAddresses: true, devHostAllowlist: [],
+    maxRedirects: 3, connectTimeoutMs: 5000,
+    maxResponseBytes: 1_000_000, maxDecompressedBytes: 1_000_000,
+  },
+});
+const response = await guardedFetch(
+  { client, url: "https://provider.example/metadata", timeoutMs: 5000 },
+  { redirect: "error" },
+);
+```
+
+`guardedFetch` returns a native Response, refuses truncated bodies, and defaults to redirect
+refusal. SDKs with positional fetch callbacks can adapt them at the host boundary. The HTTP
+transport pins the vetted IP while preserving authority and TLS SNI; every followed GET redirect
+is checked again. The `rateLimit` policy field is reserved metadata and does not implement pacing.
+
+Mail sends put message, idempotency key, workspace, and source context in argument one, with
+lane/purpose/timeout in argument two. `wrapMailerWithPurposeGate` requires an inner mailer,
+runtime mode, and a readiness port. Unknown or absent lanes require a durable path in production.
+The SMTP subpath accepts a transport and clock; its nodemailer factory accepts the host's module
+as a structural port. Core loads no mail vendor and adds no mail dependency.
+
+The guarded reader requires root, deny rules, all read/traversal limits, and a filesystem port.
+The durable JSON factory requires file path, filesystem/time/sleep/liveness/random/reporting ports,
+and host notices. It preserves atomic replacement and corrupt-file states; parent-directory
+persistence and the inherited simultaneous stale-lock-break race remain filesystem/locking limits.
+
+See [API.md](./API.md) for the source/export mapping and host wiring,
+and [the secrets guide](./src/secrets/README.md) for ciphertext-compatible object signatures.
+
+## Integrated extraction APIs
+
+All exports declare a Node runtime. The root exposes `filesystem`, `guardedHttp`, `mail`,
+`smtp`, `secrets`, and `credentialSets` namespaces; the dedicated subpaths
+remain available. `./fs` now also exports guarded readers and durable JSON helpers. Legacy root
+functions keep their existing signatures for consumers already using them.
+
+New factories/functions/methods accept a required object and, where needed, a second optional
+object. No-input operations take `{}`: `createNodeGuardedHttpPorts({})`,
+`createNodeGuardedReaderFilesystem({})`, `createNodeDurableJsonPorts({})`,
+`new FetchHttpTransportAdapter({})`, `new InMemoryTrashRepo({})`,
+`new InMemoryVendorCredentialSetRepo({})`, `keyring.activeKey({})`,
+`mailer.capabilities({})`, `clock.nowMs({})`, `clock.nowIso({})`, `random.token({})`,
+and `file.read({})`. SMTP ports receive `sendMail({ mail })`; `NodemailerPort` exposes the
+vendor-shaped `NativeSmtpTransport` so the factory adapts the payload once. Policy errors use
+`new AnalyticsPiiRejectedError({ message }, { cause })` and
+`new TrashAdapterMissingError({ message }, { cause })`.
+
+| Subpath | API and required host ports/policy |
+| --- | --- |
+| `@jini-ai/analytics` (separate package) | `ingestHit({ input, deps }, { hooks, hash })`, `normalizeIngestContext({ input, dailySalt }, { hash })`, `deriveDailySalt({ rootKeySeed, workspaceId, utcDate, saltContext })`. The host supplies sink/config, host resolution, HKDF context, and privacy bounds. `LocalBufferSink({}, { initialHits })` is process-local. |
+| `@jini-ai/cms/trash` (separate package) | `createTrashService({ repo, adapters, transaction, idGen, entityPolicy }, { retentionDays, ...optional })`, `createTrashSweep({ repo, adapters, transaction, entityPolicy })`, and `startTrashSweeper({ sweep, clock, scheduler, leaseOwner }, optional)`. The host owns authorization, transactions, retention, scheduling, and adapters; follow-up hooks are in argument two. |
+| `./fs` | `writeFileAtomic({ filePath, content, fs, tempName })`, `writeJsonFileAtomic({ filePath, data, fs, tempName })`, `upsertEnvLine({ source, key, value })`, `readEnvLine({ source, key })`, `resolvePathWithin({ root, segment })`. Atomic writes preserve existing modes and require filesystem/temp-name ports. |
+
+The extraction mappings, caller counts, remaining ownership needs, and serial verification
+commands are recorded in [the integration handoff](./integration-platform-report.md).
+
+## Design decisions
+
+- [Unknown mail purposes take the restrictive delivery lane](docs/decisions/DR-001-purpose-scoped-mail.md).
+- [Outbound HTTP inherits guards from one injected client](docs/decisions/DR-002-guarded-egress.md).
+
+## Shared kernel and filesystem/network primitives
+
+HTTP request/response/redirect/client contracts and `Clock`, `UUID`, `ISODateTime`, and JSON
+contracts come from `@jini-ai/core/primitives`. Guarded construction uses `GuardedClock`, which
+adds `timeoutSignal({ timeoutMs })` to `nowMs()`. SMTP acceptance time uses `nowIso({ clock })`.
+Mail adapter kits use that same core `HttpClientPort`; guarded requests omit `signal` when
+neither caller cancellation nor a total deadline supplies one.
+Socket idle budgets and optional total deadlines retain their existing behavior.
+
+`@jini-ai/platform/net` publishes `isPrivateAddress({ address })`, `expandIpv6({ address })`,
+`isLoopbackApiHost({ hostname })`, `isBlockedExternalApiHostname({ hostname })`, and
+`isLoopbackHostname({ hostname })`. Resolved-peer SSRF classification fails closed and blocks
+loopback, including compatible/mapped IPv6. Provider hostname policy deliberately allows loopback
+and requires DNS/connection-time checks separately. The daemon hostname predicate retains its
+narrower policy. The IP classifier no longer lives in asset-cache.ts.
+
+`@jini-ai/platform/fs` publishes `writeFileAtomic` / `writeJsonFileAtomic` and their `Async`
+counterparts. Synchronous calls take `{ filePath, content, fs }` (JSON uses `data`),
+where `fs` comes from `createNodeAtomicFilesystem({})`. Async calls take `{ filePath, content }` and accept a native `fs/promises` seam in the optional object. Both preserve existing
+permissions, default new files to 0600, create a sibling exclusively, flush file bytes before rename,
+flush the directory after rename, and clean owned temps on failure. The optional object
+accepts `tempName`; omitting it uses
+`${process.pid}.${randomUUID()}`. Options include `mode`, `defaultMode`, `refuseSymlink`,
+`verifyOwnerOnly`, and `platform`; async calls also support `createParent`, and async JSON supports
+`trailingNewline` for runtime-state files. Secret stores pass `{ mode: 0o600, verifyOwnerOnly: true }`;
+POSIX permission verification fails closed. Directory fsync failures surface after replacement.
+
+`@jini-ai/platform/fs/file-lock` publishes `withFileLock({ lockPath, run }, options)` and
+`withFileLockSync(...)`. Defaults are 15 seconds to wait, 10 seconds stale, and 10ms polling;
+options accept `timeoutMs`, `staleMs`, `pollMs`, and the kernel `clock`, plus filesystem/liveness/
+sleep seams. Run receives an ownership handle with `assertHeld({})`. Age or dead local-owner
+liveness permits stealing only after inode/device, contents and mtime remain unchanged. Unknown or
+foreign-owner pids do not authorize death-based stealing. `staleMs: Infinity` disables age stealing.
+The documented final check-to-unlink race remains; use a stale budget longer than the operation.
+Durable JSON passes its existing 5s/30s/10ms values, legacy token/temp format, and timeout copy.
+
+`defaultPlatformMessages` is exported from the root, guarded HTTP, and secrets entries. Hosts can
+supply a replacement `PlatformMessages` object to `EgressRefusedError`, `EnvOrFileKeyring`, or the
+lock/atomic-writer options. Explicit `callerSafeMessage` still takes precedence for an egress refusal.
+Credential records retain the required `workspaceId` field: it binds existing repository rows and
+AES-GCM AAD. Renaming that persisted field requires a host adapter migration as well as a type edit.
+Analytics is available from the standalone `@jini-ai/analytics` package; soft-delete and purge
+services are available from `@jini-ai/cms/trash`. Their platform subpaths and root namespaces
+have been removed.

package/dist/asset-cache.d.ts

@@ -16,28 +16,6 @@ export declare class AssetCacheError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
-/** Expand an IPv6 literal (with `::` compression and/or an embedded dotted
- *  IPv4 tail) into its eight 16-bit groups, or null if it does not parse.
- *  Node's URL parser normalizes mapped literals to hex (`::ffff:127.0.0.1` →
- *  `::ffff:7f00:1`), so a string regex can't reliably spot the mapped range —
- *  we have to canonicalize.
- *
- *  Exported (previously module-private) so its parse-failure guards are
- *  directly unit-testable: `isPrivateAddress`'s only real call site gates
- *  every call behind `net.isIP(addr) === 6`, and Node's `isIP` already fully
- *  validates IPv6 syntax (including embedded-IPv4-tail octet ranges) before
- *  returning 6 — empirically re-verified this session by fuzzing ~10k
- *  `isIP`-accepted v6 literals through this function's guards with zero
- *  hits — so none of these guards are reachable through that path. They stay
- *  as real defense-in-depth (fail closed with `null` rather than trust a
- *  platform primitive never changing behavior), matching this file's
- *  "exported for direct unit testing" precedent (see `readBodyCapped`'s
- *  abort parameter). */
-export declare function expandIpv6(addr: string): number[] | null;
-/** True for any address an external CDN must never resolve to: loopback,
- *  link-local, private, CGNAT, ULA, multicast, or unspecified. An unparseable
- *  input is treated as unsafe. */
-export declare function isPrivateAddress(addr: string): boolean;
 /** Cheap up-front rejection: enforce http(s), no embedded credentials, no
  *  localhost, and no *literal* private IP. This is NOT the DNS-rebinding guard
  *  (that is `createValidatingLookup`, applied at connection time) — it only

package/dist/asset-cache.js

@@ -25,6 +25,7 @@ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { isIP } from 'node:net';
 import path from 'node:path';
 import { Agent } from 'undici';
+import { isPrivateAddress } from './net/address.js';
 /** Media extensions we are willing to cache + proxy. Anything else (HTML,
  *  CSS, JS, fonts) is intentionally left alone so this surface never becomes a
  *  general-purpose open proxy. */
@@ -75,142 +76,6 @@ export class AssetCacheError extends Error {
         this.status = status;
     }
 }
-/** Expand an IPv6 literal (with `::` compression and/or an embedded dotted
- *  IPv4 tail) into its eight 16-bit groups, or null if it does not parse.
- *  Node's URL parser normalizes mapped literals to hex (`::ffff:127.0.0.1` →
- *  `::ffff:7f00:1`), so a string regex can't reliably spot the mapped range —
- *  we have to canonicalize.
- *
- *  Exported (previously module-private) so its parse-failure guards are
- *  directly unit-testable: `isPrivateAddress`'s only real call site gates
- *  every call behind `net.isIP(addr) === 6`, and Node's `isIP` already fully
- *  validates IPv6 syntax (including embedded-IPv4-tail octet ranges) before
- *  returning 6 — empirically re-verified this session by fuzzing ~10k
- *  `isIP`-accepted v6 literals through this function's guards with zero
- *  hits — so none of these guards are reachable through that path. They stay
- *  as real defense-in-depth (fail closed with `null` rather than trust a
- *  platform primitive never changing behavior), matching this file's
- *  "exported for direct unit testing" precedent (see `readBodyCapped`'s
- *  abort parameter). */
-export function expandIpv6(addr) {
-    // `String#split` always returns a non-empty array, so index 0 is never
-    // `undefined` — the `!` narrows a `noUncheckedIndexedAccess` false
-    // positive, not a real fallback path.
-    let s = addr.toLowerCase().split('%')[0];
-    if (!s.includes(':'))
-        return null;
-    // Fold a trailing dotted IPv4 (`…:1.2.3.4`) into two hex groups.
-    const v4 = /^(.*:)(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(s);
-    if (v4) {
-        // `v4[2]` is the regex's second (mandatory, non-optional) capture group
-        // of a successful match — always defined.
-        const o = v4[2].split('.').map((n) => Number(n));
-        if (o.length !== 4 || o.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
-            return null;
-        // `o` is now a validated 4-element array — indices 0-3 always defined.
-        const hi = (((o[0] << 8) | o[1])).toString(16);
-        const lo = (((o[2] << 8) | o[3])).toString(16);
-        s = `${v4[1]}${hi}:${lo}`;
-    }
-    const halves = s.split('::');
-    if (halves.length > 2)
-        return null;
-    const parse = (p) => p === '' ? [] : p.split(':').map((g) => (/^[0-9a-f]{1,4}$/.test(g) ? parseInt(g, 16) : Number.NaN));
-    // `halves` always has at least one element (split guarantee).
-    const left = parse(halves[0]);
-    let groups;
-    if (halves.length === 1) {
-        groups = left;
-    }
-    else {
-        // `halves.length === 2` here (the `> 2` case already returned above).
-        const right = parse(halves[1]);
-        const fill = 8 - left.length - right.length;
-        if (fill < 1)
-            return null;
-        groups = [...left, ...new Array(fill).fill(0), ...right];
-    }
-    if (groups.length !== 8 || groups.some((g) => Number.isNaN(g) || g < 0 || g > 0xffff))
-        return null;
-    return groups;
-}
-/** True for any address an external CDN must never resolve to: loopback,
- *  link-local, private, CGNAT, ULA, multicast, or unspecified. An unparseable
- *  input is treated as unsafe. */
-export function isPrivateAddress(addr) {
-    const fam = isIP(addr);
-    if (fam === 4) {
-        // `net.isIP(addr) === 4` already guarantees `addr` is a syntactically
-        // valid dotted-quad with four 0-255 decimal octets (no leading-zero
-        // octal ambiguity, no out-of-range component) — empirically re-verified
-        // this session by fuzzing 500k+ candidate strings through `isIP` and
-        // this same re-derivation with zero divergences. `o` is therefore always
-        // a validated 4-element array.
-        const o = addr.split('.').map((n) => Number(n));
-        const a = o[0];
-        const b = o[1];
-        if (a === 0)
-            return true; // "this" network / unspecified
-        if (a === 10)
-            return true; // private
-        if (a === 127)
-            return true; // loopback
-        if (a === 169 && b === 254)
-            return true; // link-local
-        if (a === 172 && b >= 16 && b <= 31)
-            return true; // private
-        if (a === 192 && b === 168)
-            return true; // private
-        if (a === 100 && b >= 64 && b <= 127)
-            return true; // CGNAT
-        if (a >= 224)
-            return true; // multicast + reserved
-        return false;
-    }
-    if (fam === 6) {
-        const groups = expandIpv6(addr);
-        // `net.isIP(addr) === 6` already guarantees `addr` is syntactically valid
-        // IPv6 (Node validates this before classifying the family), and
-        // `expandIpv6` implements the same canonicalization Node's own parser
-        // does, so it never returns `null` for an `isIP`-accepted literal —
-        // empirically re-verified this session by fuzzing ~10k `isIP`-accepted
-        // v6 literals through `expandIpv6` with zero `null` results (see
-        // `expandIpv6`'s doc comment and `source-map.md`'s 2026-07-22 entry).
-        // Kept as a real fail-closed guard (defense-in-depth against a future
-        // change to either parser) rather than asserted away, so it stays
-        // provably-unreachable-but-intentional instead of a forced test.
-        if (!groups)
-            return true; // can't canonicalize a "valid" v6 → refuse
-        // IPv4-mapped (`::ffff:0:0/96`) and the deprecated IPv4-compatible
-        // (`::0:0/96`, excluding :: / ::1) carry an embedded IPv4 — classify it by
-        // its real v4 range so `::ffff:7f00:1` (== 127.0.0.1) is caught.
-        const topZero = groups.slice(0, 5).every((g) => g === 0);
-        if (topZero && (groups[5] === 0xffff || groups[5] === 0)) {
-            // `groups` is a validated 8-element array once non-null — indices 6-7
-            // always defined.
-            const a = groups[6] >> 8;
-            const b = groups[6] & 0xff;
-            const c = groups[7] >> 8;
-            const d = groups[7] & 0xff;
-            if (groups[5] === 0xffff || a !== 0 || b !== 0) {
-                return isPrivateAddress(`${a}.${b}.${c}.${d}`);
-            }
-        }
-        if (groups.every((g) => g === 0))
-            return true; // ::  (unspecified)
-        if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
-            return true; // ::1 loopback
-        const first = groups[0];
-        if ((first & 0xffc0) === 0xfe80)
-            return true; // link-local fe80::/10 (fe80–febf)
-        if ((first & 0xfe00) === 0xfc00)
-            return true; // unique-local fc00::/7
-        if ((first & 0xff00) === 0xff00)
-            return true; // multicast ff00::/8
-        return false;
-    }
-    return true; // not a literal IP — caller must resolve before trusting it
-}
 /** Cheap up-front rejection: enforce http(s), no embedded credentials, no
  *  localhost, and no *literal* private IP. This is NOT the DNS-rebinding guard
  *  (that is `createValidatingLookup`, applied at connection time) — it only
@@ -234,7 +99,7 @@ export function assertSafePublicUrl(raw) {
     if (lowerHost === 'localhost' || lowerHost.endsWith('.localhost')) {
         throw new AssetCacheError(400, 'localhost is not allowed');
     }
-    if (isIP(host) && isPrivateAddress(host)) {
+    if (isIP(host) && isPrivateAddress({ address: host })) {
         throw new AssetCacheError(400, 'url points at a private address');
     }
     return url;
@@ -254,7 +119,7 @@ export function createValidatingLookup(lookupImpl = dnsLookupCb) {
             const list = Array.isArray(address) ? address : [{ address, family }];
             for (const entry of list) {
                 const addr = typeof entry === 'string' ? entry : entry.address;
-                if (isPrivateAddress(addr)) {
+                if (isPrivateAddress({ address: addr })) {
                     return cb(new AssetCacheError(400, 'host resolves to a private address'));
                 }
             }

package/dist/download.js

@@ -130,7 +130,7 @@ function targetFromOptions(options) {
     // `path.resolve` never actually walked upward. Empirically verified this
     // session: a 300k-segment fuzz found ~0.2% of `normalizeSegment`-valid
     // segments (every one starting with literal "..") trip this exact guard —
-    // see source-map.md's 2026-07-22 entry and this file's own test for a
+    // see archived provenance ledger's 2026-07-22 entry and this file's own test for a
     // concrete example (bucket "..evil").
     for (const path of [finalPath, manifestPath, partialPath, lockPath]) {
         if (!pathContains(basePath, path)) {
@@ -473,7 +473,7 @@ async function acquireLock(target) {
     // no trailing fallback throw is needed. Every path out of this loop body is
     // a `return` or a `throw`; V8 still instruments the loop's closing brace as
     // a branch (whether execution "falls off" the loop normally), but that
-    // outcome is structurally impossible here — see source-map.md's
+    // outcome is structurally impossible here — see archived provenance ledger's
     // 2026-07-22 entry.
     for (let attempt = 0;; attempt += 1) {
         try {

package/dist/fs/atomic-write.d.ts

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import { type PlatformMessages } from "../messages.js";
+/** Synchronous seam preserves the original fail-before-rename and permission contract.
+ * Descriptor ownership separates failed exclusive creates from failures after creating a temp. */
+export interface AtomicFilesystemPort {
+    stat(required: {
+        path: string;
+    }): {
+        mode: number;
+    };
+    lstat(required: {
+        path: string;
+    }): {
+        mode: number;
+        isSymbolicLink(): boolean;
+    };
+    open(required: {
+        path: string;
+        flags: "wx" | "r";
+        mode?: number;
+    }): number;
+    write(required: {
+        descriptor: number;
+        content: string;
+    }): void;
+    sync(required: {
+        descriptor: number;
+    }): void;
+    close(required: {
+        descriptor: number;
+    }): void;
+    chmod(required: {
+        path: string;
+        mode: number;
+    }): void;
+    rename(required: {
+        from: string;
+        to: string;
+    }): void;
+    remove(required: {
+        path: string;
+    }): void;
+}
+export type AtomicNativeFilesystem = Pick<typeof fs, "statSync" | "lstatSync" | "openSync" | "writeFileSync" | "fsyncSync" | "closeSync" | "chmodSync" | "renameSync" | "rmSync">;
+export type AtomicAsyncFilesystem = Pick<typeof fsPromises, "stat" | "lstat" | "open" | "chmod" | "rename" | "rm" | "mkdir">;
+export interface AtomicWriteRequired {
+    filePath: string;
+    content: string;
+    fs: AtomicFilesystemPort;
+}
+export interface AtomicWriteOptions {
+    messages?: PlatformMessages;
+    /** Optional collision token; native pid + UUID restores the original default. */
+    tempName?: (required: {
+        filePath: string;
+    }) => string;
+    /** Explicit mode overrides preservation, e.g. secret-bearing files must use 0600. */
+    mode?: number;
+    /** Default for a missing destination; shared durable stores retain their former 0666 create mode. */
+    defaultMode?: number;
+    refuseSymlink?: boolean;
+    /** Verify owner-only permissions before rename on POSIX, as secret stores require. */
+    verifyOwnerOnly?: boolean;
+    platform?: NodeJS.Platform;
+    /** Same-directory legacy temp layout, for stores that expose their temp path publicly. */
+    tempPath?: (required: {
+        filePath: string;
+    }) => string;
+}
+/** Optional adapter wiring: no layout, env key, or application name is selected here. */
+export declare function createNodeAtomicFilesystem(_required: Record<string, never>, { filesystem }?: {
+    filesystem?: AtomicNativeFilesystem;
+}): AtomicFilesystemPort;
+/** Same-directory rename; preserve existing mode exactly, default new files to 0600.
+ * Only ENOENT means absent. Stat/write/chmod failures propagate before any rename.
+ * Flush file bytes before rename so metadata cannot precede content; then flush the parent dir.
+ * A directory-sync failure is reported after replacement, because rename cannot be rolled back safely.
+ */
+export declare function writeFileAtomic(required: AtomicWriteRequired, options?: AtomicWriteOptions): void;
+/** Pretty JSON delegates to the same mode-preserving atomic primitive. */
+export declare function writeJsonFileAtomic(required: Omit<AtomicWriteRequired, "content"> & {
+    data: unknown;
+}, options?: AtomicWriteOptions): void;
+/** Async counterpart with the same ownership, permission and durability guarantees.
+ * Parent creation supports runtime-state and secret stores without another writer implementation. */
+export declare function writeFileAtomicAsync(required: {
+    filePath: string;
+    content: string;
+}, options?: AtomicWriteOptions & {
+    fs?: AtomicAsyncFilesystem;
+    createParent?: boolean;
+}): Promise<void>;
+/** Pretty JSON can retain a state-store's trailing newline without changing its serialization. */
+export declare function writeJsonFileAtomicAsync(required: {
+    filePath: string;
+    data: unknown;
+}, options?: AtomicWriteOptions & {
+    fs?: AtomicAsyncFilesystem;
+    createParent?: boolean;
+    trailingNewline?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=atomic-write.d.ts.map