@executablemd/runtime 0.6.0 → 0.8.0

package/types/files.d.ts

@@ -0,0 +1,299 @@
+/**
+ * `API.Files` — the document filesystem boundary.
+ *
+ * A document names files with a path relative to the contextual working
+ * directory, and every one of those operations arrives here. What is on the
+ * other side is a provider's choice: `xmd run` installs a host adapter that
+ * resolves those paths in the caller's own filesystem, and `xmd workflow`
+ * installs one that resolves them in a logical filesystem owned by a database
+ * transaction. Neither is named in the components that call this Api, which is
+ * what lets one document mean the same thing under both.
+ *
+ * The operations are **semantic**, not primitive. `writeTextFile` is a whole
+ * replacement — admission, resolution, target classification, parent creation,
+ * and commit — rather than a sequence a caller assembles, because assembling it
+ * from outside is what would let a path admitted by one provider be used by
+ * another. `API.Fs` remains the low-level host surface a host adapter is built
+ * on; it is not this boundary.
+ *
+ * `checkFilePath` is the one exception, and it is deliberately weak: pure path
+ * arithmetic, no filesystem access, and nothing usable comes back — no path, no
+ * handle, no authority token. `<File>`'s write form calls it to decide whether
+ * its children may expand at all, and the later `writeTextFile` repeats the
+ * same admission from the same authored path. A check that was skipped,
+ * replaced, or answered by another provider therefore authorizes nothing.
+ *
+ * ## Two kinds of failure
+ *
+ * An ordinary filesystem condition — missing, a directory, permission denied,
+ * no space — comes back as `Err(FilesError)` carrying frozen structural data.
+ * The consumer reads that data and selects a sentence from a fixed vocabulary;
+ * no message, errno code, resolved path, temporary path, or symlink target
+ * crosses this boundary. Cancellation is neither of these: it is not caught and
+ * never becomes a Result.
+ *
+ * A provider that is absent, that refuses an operation, or that breaks its own
+ * contract is not a filesystem condition. Those **throw**, with fixed
+ * diagnostics and no cause, and they end the execution rather than becoming
+ * something a document renders. A run whose Files provider is missing must not
+ * quietly reach the host instead.
+ *
+ * ## Why the data is structural
+ *
+ * Both the failures and the write outcome carry a plain frozen object under a
+ * stable `type` tag, and every consumer recognizes them by parsing that tag
+ * rather than with `instanceof`. Two copies of this package can be loaded at
+ * once — a repository component resolving its own runtime beside the engine's —
+ * and `instanceof` answers false across them, which would turn a provider
+ * failure into an unrecognized throw exactly when it matters most.
+ */
+import { type Api } from "@effectionx/context-api";
+import type { Operation, Result } from "effection";
+/** The stable discriminant on ordinary filesystem failure data. */
+export declare const FILES_ERROR = "executablemd.runtime.files-error/v1";
+/** The stable discriminant on infrastructure failure data. */
+export declare const FILES_FATAL = "executablemd.runtime.files-fatal/v1";
+/** The stable discriminant on a successful write's outcome data. */
+export declare const FILES_WRITE_SUCCESS = "executablemd.runtime.files-write-success/v1";
+/**
+ * The vocabulary an ordinary failure is reported in.
+ *
+ * A provider maps whatever its platform produced onto one of these before
+ * returning. An unmapped condition becomes `operation-failed`, which is a real
+ * answer rather than a placeholder: the consumer has a sentence for it, and the
+ * unmapped value itself never crosses the boundary.
+ */
+export type FilesReason = "empty-path" | "absolute-path" | "lexical-escape" | "resolved-escape" | "missing" | "directory" | "special-file" | "not-directory" | "permission-denied" | "read-only" | "too-many-symlinks" | "path-too-long" | "no-space" | "quota-exhausted" | "cross-device" | "busy" | "too-many-open-files" | "directory-not-empty" | "invalid-pattern" | "operation-failed";
+/** The operations whose failure carries no commit outcome. */
+export type FilesOperation = "check-file-path" | "read" | "glob" | "temporary-directory";
+/** Where a non-write operation stopped. */
+export type FilesPhase = "lexical" | "resolution" | "target" | "access" | "pattern" | "traversal" | "acquire";
+/** Where a write stopped, which is what decides what may be said about the target. */
+export type FileWritePhase = "lexical" | "resolution" | "target" | "parents" | "temporary" | "commit" | "cleanup" | "transaction";
+/**
+ * What is known about the target afterwards.
+ *
+ * `commit-unknown` is an answer rather than a missing one: a commit that threw
+ * may have run or not, and no provider can tell which from where it stands.
+ * What still holds in that case is that the target is one complete version.
+ */
+export type FileWriteTarget = "unchanged" | "commit-unknown" | "committed" | "rolled-back";
+export interface FilesFailureData {
+    readonly type: typeof FILES_ERROR;
+    readonly operation: FilesOperation;
+    readonly phase: FilesPhase;
+    readonly reason: FilesReason;
+}
+export interface FileWriteFailureData {
+    readonly type: typeof FILES_ERROR;
+    readonly operation: "write";
+    readonly phase: FileWritePhase;
+    readonly reason?: FilesReason;
+    readonly cleanup?: FilesReason;
+    readonly target: FileWriteTarget;
+}
+export type FilesErrorData = FilesFailureData | FileWriteFailureData;
+/**
+ * The message every ordinary failure carries.
+ *
+ * Constant on purpose. A message is the part of an Error that gets printed by
+ * accident, and there is nothing safe to put in this one: the authored path
+ * belongs to the consumer that wrote it, and everything else belongs to the
+ * platform.
+ */
+export declare const FILES_ERROR_MESSAGE = "Files operation failed";
+/** An ordinary filesystem failure. What it means is in `data`, never in the message. */
+export declare class FilesError extends Error {
+    readonly data: FilesErrorData;
+    constructor(data: FilesErrorData);
+}
+export interface FileWriteSuccess {
+    readonly type: typeof FILES_WRITE_SUCCESS;
+    readonly publication: "host-committed" | "transaction-staged";
+}
+export interface FilePathInput {
+    readonly cwd: string;
+    readonly path: string;
+}
+export interface FileWriteInput extends FilePathInput {
+    readonly content: string;
+}
+export interface GlobInput {
+    readonly cwd: string;
+    readonly include: string[];
+    readonly exclude: string[];
+}
+export interface FilesHandler {
+    /**
+     * Whether this authored path is admissible at all, decided from the path and
+     * `cwd` alone. No filesystem access, and nothing usable comes back.
+     */
+    checkFilePath(input: FilePathInput): Operation<Result<void>>;
+    readTextFile(input: FilePathInput): Operation<Result<string>>;
+    writeTextFile(input: FileWriteInput): Operation<Result<FileWriteSuccess>>;
+    /** Sorted, deduplicated, POSIX-separated paths of the regular files that match. */
+    globFiles(input: GlobInput): Operation<Result<string[]>>;
+    /**
+     * A directory that lives as long as the acquiring scope. A resource, so the
+     * caller holds it by acquisition rather than by remembering to remove it.
+     */
+    temporaryDirectory(): Operation<Result<string>>;
+}
+/** The operations a provider may refuse outright rather than fail at. */
+export type FilesDeniableOperation = "temporary-directory";
+/**
+ * Which contract a provider broke.
+ *
+ * `authority` — the identity authorizing access is stale, foreign, or gone.
+ * `savepoint` — a nested transaction could not be rolled back or released.
+ * `protocol` — a handler threw, or returned data no consumer can trust.
+ * `teardown` — cleanup failed while the scope was already unwinding.
+ */
+export type FilesInvariantCategory = "authority" | "savepoint" | "protocol" | "teardown";
+/**
+ * Infrastructure failure data.
+ *
+ * Three kinds, each with fixed fields and nothing derived from the condition
+ * that produced it. A category is control data for a consumer deciding what to
+ * fence, not text: no diagnostic interpolates it.
+ */
+export type FilesFatalData = {
+    readonly type: typeof FILES_FATAL;
+    readonly kind: "provider-unavailable";
+} | {
+    readonly type: typeof FILES_FATAL;
+    readonly kind: "operation-denied";
+    readonly operation: FilesDeniableOperation;
+} | {
+    readonly type: typeof FILES_FATAL;
+    readonly kind: "invariant";
+    readonly category: FilesInvariantCategory;
+};
+export declare const FILES_PROVIDER_UNAVAILABLE_MESSAGE = "Files provider is not installed";
+export declare const FILES_OPERATION_DENIED_MESSAGE = "Files provider does not support temporary-directory";
+export declare const FILES_INVARIANT_MESSAGE = "Files provider invariant failed";
+/** No Files provider is installed, and there is no host to fall back to. */
+export declare class FilesProviderUnavailableError extends Error {
+    readonly data: FilesFatalData;
+    constructor();
+}
+/** The installed provider does not implement this operation at all. */
+export declare class FilesOperationDeniedError extends Error {
+    readonly data: FilesFatalData;
+    constructor(operation: FilesDeniableOperation);
+}
+/** A provider broke its own contract. */
+export declare class FilesInvariantError extends Error {
+    readonly data: FilesFatalData;
+    constructor(category: FilesInvariantCategory);
+}
+/** An infrastructure failure, recognized structurally rather than by class. */
+export interface FilesFatalFailure extends Error {
+    readonly data: FilesFatalData;
+}
+/**
+ * The vocabularies, for a provider that reads a failure back out of storage.
+ *
+ * A transaction-bound provider retains what it refused rather than a serialized
+ * error, so restoring one means turning stored text back into the vocabulary.
+ * Parsing it here is what keeps one list of reasons and phases: a provider that
+ * declared its own copy would be a second list to keep in agreement with this.
+ */
+export declare function parseFilesReason(value: unknown): FilesReason | undefined;
+export declare function parseFilesPhase(value: unknown): FilesPhase | undefined;
+export declare function parseFileWritePhase(value: unknown): FileWritePhase | undefined;
+/**
+ * The infrastructure failure data this Error carries, if it carries valid data.
+ *
+ * Every field is checked, the member count with them, and that the object is
+ * frozen: extra keys are not the shape this contract describes, and a mutable
+ * one is not the shape a constructor here produces. Accepting either would let
+ * a provider smuggle a path or a message through under a recognized tag.
+ */
+export declare function parseFilesFatal(error: unknown): FilesFatalData | undefined;
+/**
+ * Whether this failure satisfies the whole public infrastructure-failure
+ * contract, not merely the tag.
+ *
+ * Recognition decides two different things at once, and the second is why this
+ * is stricter than `parseFilesFatal`. A recognized failure is **rethrown by
+ * identity** — the object that was thrown is the object a fail-stop records —
+ * so recognizing one is a decision to let that exact object travel onward. An
+ * Error that carries the right data but also a raw platform message, or a cause
+ * chain holding an errno and a path, would then carry all of that past the
+ * boundary the reason vocabulary exists to hold.
+ *
+ * So the whole object has to match what a constructor here produces: the fixed
+ * name and diagnostic for its kind, frozen structural data with exactly the
+ * fields the kind describes, no cause, and no other enumerable member — string
+ * or symbol. Anything else is a candidate that fails the contract, and
+ * `invokeFiles` replaces it with a fresh invariant rather than preserving it.
+ *
+ * Structural throughout, so a failure constructed by a separately loaded copy
+ * of this package is recognized on exactly the same terms as one constructed
+ * here — `instanceof` answers false across two copies, which is the case this
+ * has to survive. That is also why the `name` is checked rather than the class:
+ * a second copy's constructor is a different function producing the same name.
+ */
+export declare function isFilesFatal(error: unknown): error is FilesFatalFailure;
+/**
+ * The infrastructure failure this one is, by identity.
+ *
+ * The original object comes back rather than a replacement, because a fail-stop
+ * that records "the first error" has to record the one that was thrown.
+ */
+export declare function asFilesFatal(error: unknown): FilesFatalFailure | undefined;
+/** Build an ordinary non-write failure. */
+export declare function filesFailure(input: {
+    operation: FilesOperation;
+    phase: FilesPhase;
+    reason: FilesReason;
+}): FilesError;
+/**
+ * Build a write failure, refusing any combination a consumer could not read.
+ *
+ * A write's report is the only place a document learns what became of a file it
+ * asked to replace, so an invalid combination is a provider bug rather than a
+ * value to pass along and interpret later.
+ */
+export declare function fileWriteFailure(input: {
+    phase: FileWritePhase;
+    reason?: FilesReason;
+    cleanup?: FilesReason;
+}): FilesError;
+/**
+ * The non-write failure data this error carries, if it carries valid data.
+ *
+ * Malformed data is not fatal here — the consumer already has a sentence for
+ * "the operation failed" and nothing about a target is at stake — so this
+ * simply declines to recognize it.
+ */
+export declare function parseFilesFailure(error: unknown): FilesFailureData | undefined;
+/**
+ * The write failure data this error carries, if it carries valid data.
+ *
+ * Unlike a non-write failure, malformed data here has no safe reading: every
+ * sentence a consumer could print makes a claim about whether the file was
+ * replaced. A caller treats `undefined` from a write as a protocol invariant
+ * rather than inventing a commit state.
+ */
+export declare function parseFileWriteFailure(error: unknown): FileWriteFailureData | undefined;
+/** A successful write's outcome. */
+export declare function fileWriteSuccess(publication: FileWriteSuccess["publication"]): FileWriteSuccess;
+/**
+ * The write outcome this value is, if it is a valid one.
+ *
+ * A malformed success is as untrustworthy as a malformed failure: a provider
+ * that cannot describe what it did may not have done it, so a caller treats
+ * `undefined` here as a protocol invariant too.
+ */
+export declare function parseFileWriteSuccess(value: unknown): FileWriteSuccess | undefined;
+/**
+ * The document filesystem Api.
+ *
+ * The terminal handler throws for every operation, including `checkFilePath`.
+ * A default that reached the host would make an uninstalled provider
+ * indistinguishable from an installed one, and the whole point of the boundary
+ * is that a workflow run cannot silently touch the caller's filesystem.
+ */
+export declare const Files: Api<FilesHandler>;

package/types/host-files.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The host `API.Files` provider — document filesystem access in the caller's
+ * own filesystem.
+ *
+ * This is what `xmd run` installs. A document's relative path is resolved
+ * against the contextual working directory and used as an ordinary host path,
+ * so a document can hand a file to a tool the caller already has. Everything
+ * below is built on the low-level `API.Fs`, which is deliberate: a host that
+ * already wraps `API.Fs` to observe or sandbox the engine's own file access
+ * keeps seeing a document's access on the same terms.
+ *
+ * ## What containment means here
+ *
+ * Access is confined to the contextual directory, judged against the filesystem
+ * as this adapter observes it. An empty path, an absolute path, and a lexical
+ * `..` escape are refused without touching the filesystem at all; a symlink
+ * leading out is refused once resolution can see it.
+ *
+ * That is sound **while the host pathname namespace is stable**, and every
+ * guarantee here is stated on that basis. It is not a sandbox. Another process
+ * can replace a directory, symlink, junction, or reparse point between the
+ * moment this adapter observes a path and the moment it uses one, and nothing
+ * available on the shipped runtimes closes that window without a native
+ * dependency. What is contained is the document's own children — the case a
+ * document controls — because resolution is deferred until after they run.
+ *
+ * ## Writes
+ *
+ * A write goes through a sibling temporary file and a rename. The rename is the
+ * commit point: everything before it can fail or be cancelled with the previous
+ * file untouched, and once it begins the target holds the complete old file or
+ * the complete new one, never a partial write. It is a commit rather than a
+ * transaction — a rename that returned is not undone by a later cancellation.
+ * The temporary also closes the one hole resolution cannot: a dangling symlink
+ * has nothing to resolve, and `rename` replaces the link rather than following
+ * it wherever it points.
+ *
+ * ## What crosses the boundary
+ *
+ * Nothing from a caught platform error. An errno code *selects* a
+ * `FilesReason`, and the reason is all the consumer receives — no message, no
+ * code, no resolved path, no temporary path, and no symlink target. A platform
+ * error names the path it failed on, and for a write that path can be a
+ * temporary the document never chose.
+ */
+import type { Operation } from "effection";
+import type { FilesHandler } from "./files.js";
+/**
+ * A private step a host operation is about to take.
+ *
+ * Test-only. Production entrypoints install the adapter without one, so this is
+ * neither global state nor a capability: an observer can watch, and the point of
+ * watching is to replace part of the tree between an observation and the call
+ * that follows it, which is how the stable-namespace limitation is made
+ * observable rather than merely stated.
+ */
+export interface HostFilesEvent {
+    readonly operation: "read" | "write" | "glob";
+    readonly phase: "target" | "access" | "parents" | "temporary" | "commit" | "cleanup" | "read-dir";
+}
+/** Synchronous, so nothing can run between the observation and the call it precedes. */
+export type HostFilesObserver = (event: HostFilesEvent) => void;
+export interface HostFilesOptions {
+    readonly observe?: HostFilesObserver;
+}
+/**
+ * Build a host provider.
+ *
+ * Exported so a test can drive one operation directly; entrypoints install it
+ * with {@link useHostFiles}.
+ */
+export declare function hostFilesHandler(options?: HostFilesOptions): FilesHandler;
+/**
+ * Install the host provider beneath ordinary middleware.
+ *
+ * `at: "min"` is what lets a host wrap document filesystem access without
+ * replacing it — middleware installed later sees these operations and can
+ * delegate to them.
+ */
+export declare function useHostFiles(options?: HostFilesOptions): Operation<void>;

package/types/mod.d.ts

@@ -5,20 +5,32 @@
  * `API` is available for middleware (`.around()`).
  * For normal calls, import operations directly.
  *
- * Six domain APIs:
+ * Seven domain APIs:
  * - `API.Process` — subprocess execution (`exec`)
- * - `API.Fs` — filesystem (`readTextFile`, `stat`, `glob`)
+ * - `API.Fs` — the low-level host filesystem (`readTextFile`, `writeTextFile`,
+ *   `stat`, `glob`, `realpath`, `ensureDir`, `rename`, `remove`)
+ * - `API.Files` — document filesystem access as whole semantic operations,
+ *   with no host default. `useHostFiles()` installs the host provider.
  * - `API.Fetch` — HTTP requests (`fetch`)
- * - `API.Env` — environment variables and platform info (`cwd`, `env`, `platform`)
- * - `API.Compiler` — block compilation (`compile`)
- * - `Config` — shared execution config (`timeout`)
+ * - `API.Env` — the host: variables, platform info, the command that invokes
+ *   this xmd, and eval-block compilation
+ *   (`cwd`, `env`, `platform`, `command`, `compile`)
+ * - `API.Service` — scoped attached service startup (`startService`)
+ * - `Config` — shared execution config (`timeout`, `timeoutExec`, `timeoutFetch`)
  *
  * See `apis.ts` for architecture rationale.
  * See `@executablemd/runtime/test` for composable test stubs.
  */
 export { API } from "./apis.js";
-export { exec, readTextFile, stat, glob, fetch, cwd, env, platform, compile } from "./apis.js";
-export type { ResponseHeaders, RuntimeFetchResponse, StatResult } from "./apis.js";
-export { findFreePort } from "./find-free-port.js";
-export { Config, timeout } from "./config.js";
+export { exec, readTextFile, writeTextFile, stat, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, useQuietProcessOutput, } from "./apis.js";
+export type { EvalBlock, ResponseHeaders, RuntimeFetchResponse, StatResult } from "./apis.js";
+export { Service, SERVICE_HOSTNAME, SERVICE_READY_PREFIX, ServiceProcessExitBeforeReadyError, ServiceProtocolDuplicateError, ServiceProtocolHostnameMismatchError, ServiceProtocolIncompatibleError, ServiceProtocolMalformedError, ServiceProtocolTokenMismatchError, ServiceProviderError, ServiceStartupTimeoutError, ServiceTeardownError, ServiceUnexpectedExitError, parseServiceReadyRecord, startService, } from "./service.js";
+export type { ServiceEndpoint, ServiceHandler, ServiceAttachment, ServiceStartOptions, } from "./service.js";
+export { Config, timeout, timeoutExec, timeoutFetch } from "./config.js";
 export type { ConfigApi } from "./config.js";
+export { asDuration, durationError, parseDuration } from "./duration.js";
+export type { ProcessExecOptions, ProcessOutcome } from "./apis.js";
+export { asFilesFatal, FILES_ERROR, FILES_ERROR_MESSAGE, FILES_FATAL, FILES_INVARIANT_MESSAGE, FILES_OPERATION_DENIED_MESSAGE, FILES_PROVIDER_UNAVAILABLE_MESSAGE, FILES_WRITE_SUCCESS, Files, FilesError, FilesInvariantError, FilesOperationDeniedError, FilesProviderUnavailableError, fileWriteFailure, fileWriteSuccess, filesFailure, isFilesFatal, parseFilesPhase, parseFilesReason, parseFileWriteFailure, parseFileWritePhase, parseFileWriteSuccess, parseFilesFailure, parseFilesFatal, } from "./files.js";
+export type { FilePathInput, FilesDeniableOperation, FilesErrorData, FilesFailureData, FilesFatalData, FilesFatalFailure, FilesHandler, FilesInvariantCategory, FilesOperation, FilesPhase, FilesReason, FileWriteFailureData, FileWriteInput, FileWritePhase, FileWriteSuccess, FileWriteTarget, GlobInput, } from "./files.js";
+export { hostFilesHandler, useHostFiles } from "./host-files.js";
+export type { HostFilesEvent, HostFilesObserver, HostFilesOptions } from "./host-files.js";

package/types/service.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Provider-neutral attached-service lifecycle.
+ *
+ * The shared runtime owns the XMD service handshake shape and validation. A
+ * runtime-named host adapter supplies process startup through `API.Service`
+ * middleware.
+ */
+import { type Api, type Operations } from "@effectionx/context-api";
+import type { Operation } from "effection";
+export declare const SERVICE_READY_PREFIX = "XMD_SERVICE_READY:";
+export declare const SERVICE_HOSTNAME = "127.0.0.1";
+export interface ServiceEndpoint {
+    readonly hostname: string;
+    readonly port: number;
+}
+export interface ServiceStartOptions {
+    readonly command: string;
+    readonly cwd?: string;
+    readonly startupTimeout?: number;
+}
+export interface ServiceAttachment {
+    readonly endpoint: Readonly<ServiceEndpoint>;
+}
+export interface ServiceHandler {
+    start(options: ServiceStartOptions): Operation<ServiceAttachment>;
+}
+export declare class ServiceProviderError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceProtocolMalformedError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceProtocolIncompatibleError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceProtocolTokenMismatchError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceProtocolHostnameMismatchError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceProtocolDuplicateError extends Error {
+    name: string;
+    constructor();
+}
+export declare class ServiceStartupTimeoutError extends Error {
+    name: string;
+    constructor(timeout: number);
+}
+interface ServiceExitStatus {
+    readonly code?: number;
+    readonly signal?: string;
+}
+export declare class ServiceProcessExitBeforeReadyError extends Error {
+    name: string;
+    constructor(status: ServiceExitStatus);
+}
+export declare class ServiceUnexpectedExitError extends Error {
+    name: string;
+    constructor(status: ServiceExitStatus);
+}
+export declare class ServiceTeardownError extends Error {
+    name: string;
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/** Parse and authenticate one prefix-stripped v1 handshake payload. */
+export declare function parseServiceReadyRecord(payload: string, expectedToken: string): ServiceEndpoint;
+export declare const Service: Api<ServiceHandler>;
+export declare const startService: Operations<ServiceHandler>["start"];
+export {};

package/types/test/mod.d.ts

@@ -6,5 +6,6 @@
  * - `useStubFs(files)` — in-memory filesystem
  * - `useEchoExec()` — simple echo-based exec
  * - `useFailingExec(exitCode, stderr)` — always-failing exec
+ * - `useStubService(endpoint)` — scoped provider-neutral service attachment
  */
-export { useStubFs, useEchoExec, useFailingExec } from "./stubs.js";
+export { useStubFs, useEchoExec, useFailingExec, useStubService } from "./stubs.js";

package/types/test/stubs.d.ts

@@ -20,12 +20,18 @@
  * ```
  */
 import type { Operation } from "effection";
+import type { ServiceEndpoint } from "../service.js";
+/** Install a provider-neutral scoped service attachment stub. */
+export declare function useStubService(endpoint: ServiceEndpoint): Operation<void>;
 /**
  * Install an in-memory filesystem stub.
  *
  * - `readTextFile` returns content from the `files` map; throws ENOENT for missing keys.
  * - `stat` returns `{ exists: true, isFile: true }` for keys in the map.
  * - `glob` throws (not stubbed). Install `API.Fs.around()` directly if needed.
+ * - the writing half — `writeTextFile`, `ensureDir`, `rename`, `remove`, and
+ *   `realpath` — is not stubbed and reaches the real filesystem. A test that
+ *   exercises a document writing files wants a real temporary directory.
  *
  * The `files` object is captured **by reference** — mutating it between
  * operations changes what `readTextFile`/`stat` see. This is useful for
@@ -37,6 +43,12 @@ export declare function useStubFs(files: Record<string, string>): Operation<void
  *
  * Recognizes `bash -c "echo ..."` and returns the echo'd text as stdout.
  * All other commands return the script text as stdout with exit code 0.
+ *
+ * It answers like a real child: the text is written to the stdio chain as it
+ * "arrives", so whatever encloses the call sees it the way it would see a
+ * child's, and it is retained in the outcome only when the caller asked
+ * for retention. A stub that always returned strings would let a document
+ * render output the contract says was already displayed.
  */
 export declare function useEchoExec(): Operation<void>;
 /**

package/esm/find-free-port.js

@@ -1,33 +0,0 @@
-/**
- * findFreePort — find an available TCP port using the OS.
- */
-import { race } from "effection";
-import { once } from "@effectionx/node";
-import { createServer } from "node:net";
-/**
- * Find an available TCP port by binding to port 0 and reading the
- * OS-assigned port number.
- */
-export function* findFreePort() {
-    const server = createServer();
-    const listening = once(server, "listening");
-    const error = once(server, "error");
-    server.listen(0);
-    try {
-        const rethrowError = {
-            *[Symbol.iterator]() {
-                const [err] = yield* error;
-                throw err;
-            },
-        };
-        yield* race([listening, rethrowError]);
-        const addr = server.address();
-        if (!addr || typeof addr !== "object") {
-            throw new Error("findFreePort: unexpected address format");
-        }
-        return addr.port;
-    }
-    finally {
-        server.close();
-    }
-}

package/types/find-free-port.d.ts

@@ -1,9 +0,0 @@
-/**
- * findFreePort — find an available TCP port using the OS.
- */
-import type { Operation } from "effection";
-/**
- * Find an available TCP port by binding to port 0 and reading the
- * OS-assigned port number.
- */
-export declare function findFreePort(): Operation<number>;