@executablemd/runtime 0.7.0 → 0.8.1

package/esm/test/stubs.js

@@ -19,7 +19,25 @@
  * });
  * ```
  */
+import { Stdio } from "@effectionx/process";
 import { API } from "../apis.js";
+import { SERVICE_HOSTNAME } from "../service.js";
+/** Install a provider-neutral scoped service attachment stub. */
+export function* useStubService(endpoint) {
+    if (endpoint.hostname !== SERVICE_HOSTNAME) {
+        throw new Error("stub service endpoint must use 127.0.0.1");
+    }
+    if (!Number.isInteger(endpoint.port) || endpoint.port < 1 || endpoint.port > 65_535) {
+        throw new Error("stub service endpoint port must be an integer from 1 through 65535");
+    }
+    const exact = Object.freeze({ hostname: SERVICE_HOSTNAME, port: endpoint.port });
+    yield* API.Service.around({
+        // deno-lint-ignore require-yield
+        *start() {
+            return { endpoint: exact };
+        },
+    });
+}
 /**
  * Install an in-memory filesystem stub.
  *
@@ -57,15 +75,20 @@ export function* useStubFs(files) {
  *
  * 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 function* useEchoExec() {
     yield* API.Process.around({
         *exec([options], _next) {
             const script = (options.command[2] ?? "").trim();
-            if (script.startsWith("echo ")) {
-                return { exitCode: 0, stdout: script.slice(5) + "\n", stderr: "" };
-            }
-            return { exitCode: 0, stdout: script + "\n", stderr: "" };
+            const text = script.startsWith("echo ") ? script.slice(5) + "\n" : script + "\n";
+            yield* Stdio.operations.stdout(encoder.encode(text));
+            return retained(options, { exitCode: 0, stdout: text, stderr: "" });
         },
     });
 }
@@ -76,8 +99,17 @@ export function* useEchoExec() {
  */
 export function* useFailingExec(exitCode, stderr = "command failed") {
     yield* API.Process.around({
-        *exec(_args, _next) {
-            return { exitCode, stdout: "", stderr };
+        *exec([options], _next) {
+            yield* Stdio.operations.stderr(encoder.encode(stderr));
+            return retained(options, { exitCode, stdout: "", stderr });
         },
     });
 }
+const encoder = new TextEncoder();
+/** What the caller asked to keep, so a stub cannot retain more than a call would. */
+function retained(options, outcome) {
+    if (options.retain === false) {
+        return { exitCode: outcome.exitCode, stdout: undefined, stderr: undefined };
+    }
+    return outcome;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/runtime",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Runtime host APIs for executable.md documents.",
   "homepage": "https://executable.md",
   "repository": {
@@ -20,6 +20,12 @@
         "default": "./esm/mod.js"
       }
     },
+    "./files": {
+      "import": {
+        "types": "./types/files.d.ts",
+        "default": "./esm/files.js"
+      }
+    },
     "./test": {
       "import": {
         "types": "./types/test/mod.d.ts",
@@ -30,11 +36,11 @@
   "scripts": {},
   "dependencies": {
     "@effectionx/context-api": "0.6.0",
-    "@effectionx/fetch": "0.2.0",
+    "@effectionx/fetch": "0.2.1",
     "@effectionx/fs": "0.3.0",
-    "@effectionx/node": "0.2.4",
     "@effectionx/process": "0.8.1",
-    "effection": "4.1.0-alpha.10"
+    "effection": "4.1.0",
+    "@effectionx/node": "0.2.4"
   },
   "_generatedBy": "dnt@dev"
 }

package/types/apis.d.ts

@@ -1,7 +1,8 @@
 /**
  * Runtime Context APIs — platform I/O operations with pluggable middleware.
  *
- * Five domain-specific context APIs built on `@effectionx/context-api`.
+ * Five host-backed domain APIs plus the provider-neutral Service Api, built on
+ * `@effectionx/context-api`.
  * Each API provides default Node.js implementations. Use `.around()` to
  * install middleware (mocking, instrumentation, sandboxing) scoped to the
  * current Effection scope.
@@ -25,14 +26,19 @@
  * });
  * ```
  *
- * ## Why four separate APIs?
+ * ## Why separate APIs?
  *
  * - **Process** — subprocess lifecycle has its own cancellation semantics
  *   (killing processes on scope teardown). Middleware targets exec only.
- * - **Fs** — reading, writing, and inspecting files form a cohesive file-IO
- *   surface used together for component resolution, replay guards, and the
- *   `<File>` component. Middleware installed here sees a document's own file
- *   access on the same terms as the engine's.
+ * - **Fs** — the low-level host file surface: reading, writing, and inspecting
+ *   paths the engine itself resolves, for component lookup, replay guards, and
+ *   the root document. It is the host adapter's own dependency, not the
+ *   boundary a document's paths cross.
+ * - **Files** — document filesystem access, in whole semantic operations
+ *   (`files.ts`). `<File>`, `<Glob>`, and `<TempDir>` speak only this Api, so
+ *   the same document means the same thing whether its paths resolve in the
+ *   caller's filesystem or in a run-owned logical one. Its terminal handler
+ *   throws: an uninstalled provider must not silently reach the host.
  * - **Fetch** — HTTP has distinct timeout/body/abort semantics. Merging
  *   with Fs or Process would blur cancellation boundaries.
  * - **Env** — the host itself: metadata (env vars, platform) plus the two
@@ -41,6 +47,8 @@
  *   use `.around()` to mock platform/env for deterministic replay; an
  *   entrypoint installs its `command` and `compile` with `{ at: "min" }` so
  *   ordinary middleware can wrap them.
+ * - **Service** — scoped service attachment. Its terminal handler requires an
+ *   explicit host provider and never detects or imports a runtime.
  *
  * ## Middleware
  *
@@ -59,10 +67,13 @@
  * ## Test stubs
  *
  * Common stubs are provided by `@executablemd/runtime/test`:
- * `useStubFs(files)`, `useEchoExec()`, `useFailingExec(code, stderr)`.
+ * `useStubFs(files)`, `useEchoExec()`, `useFailingExec(code, stderr)`,
+ * `useStubService(endpoint)`.
  */
 import { type Api } from "@effectionx/context-api";
 import type { Operation } from "effection";
+import { Files } from "./files.js";
+import { Service } from "./service.js";
 /**
  * Result of a `stat` call.
  *
@@ -95,17 +106,34 @@ export interface RuntimeFetchResponse {
     /** Read the response body as text. */
     text(): Operation<string>;
 }
+/**
+ * What a finished child process reports.
+ *
+ * `stdout` and `stderr` are the text a caller asked to be retained. A caller
+ * that asked for none gets `undefined` rather than an empty string: nothing was
+ * accumulated, and "no output" and "not retained" are different answers.
+ */
+export interface ProcessOutcome {
+    exitCode: number;
+    stdout: string | undefined;
+    stderr: string | undefined;
+}
+export interface ProcessExecOptions {
+    command: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    /**
+     * Retain the child's output in the outcome. Default `true`.
+     *
+     * Retention is the caller's explicit choice, never an inference: a run that
+     * keeps no diagnostic record asks for `false` and the text is forwarded to
+     * whatever is displaying it without ever being accumulated here.
+     */
+    retain?: boolean;
+}
 interface ProcessHandler {
-    exec(options: {
-        command: string[];
-        cwd?: string;
-        env?: Record<string, string>;
-        timeout?: number;
-    }): Operation<{
-        exitCode: number;
-        stdout: string;
-        stderr: string;
-    }>;
+    exec(options: ProcessExecOptions): Operation<ProcessOutcome>;
 }
 interface FsHandler {
     readTextFile(path: string): Operation<string>;
@@ -178,10 +206,35 @@ interface EnvHandler {
 export declare const API: {
     Process: Api<ProcessHandler>;
     Fs: Api<FsHandler>;
+    Files: typeof Files;
     Fetch: Api<FetchHandler>;
     Env: Api<EnvHandler>;
+    Service: typeof Service;
 };
-export declare const exec: typeof API.Process.operations.exec;
+/**
+ * Run a child process.
+ *
+ * A caller that says nothing about retention keeps the output, which is what
+ * every caller with something to read wants and what callers have always had.
+ * Asking for `retain: false` keeps the exit status alone, and the overloads say
+ * so: there is no string to read on that path, and the type refuses to pretend
+ * otherwise. Core, which decides retention per block, calls the Api operation
+ * directly and handles both.
+ */
+export declare function exec(options: ProcessExecOptions & {
+    retain: false;
+}): Operation<{
+    exitCode: number;
+    stdout: undefined;
+    stderr: undefined;
+}>;
+export declare function exec(options: ProcessExecOptions & {
+    retain?: true;
+}): Operation<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
 export declare const readTextFile: typeof API.Fs.operations.readTextFile;
 export declare const stat: typeof API.Fs.operations.stat;
 export declare const glob: typeof API.Fs.operations.glob;
@@ -196,4 +249,24 @@ export declare const cwd: typeof API.Env.operations.cwd;
 export declare const platform: typeof API.Env.operations.platform;
 export declare const command: typeof API.Env.operations.command;
 export declare const compile: typeof API.Env.operations.compile;
+/**
+ * Discard the standard output of subprocesses started in this scope.
+ *
+ * For a caller whose subprocess output is an *answer* rather than something to
+ * show: a command whose stdout is parsed and returned would otherwise also
+ * print itself into whatever the process was rendering. `stderr` is left alone,
+ * because that is where a failing command explains itself and a diagnostic is
+ * worth seeing.
+ *
+ * It lives here because reaching the process Api's stdio directly is host
+ * behavior, and modules held to the runtime-neutral boundary may not import a
+ * host process module of their own.
+ *
+ * Installed at the display boundary, where the host's own writer sits: not
+ * showing something and not knowing it are different, and a caller that asked
+ * for the answer must still be given it. Anything upstream — this adapter's
+ * retention, a document's capture, a run's record — reads the bytes first and
+ * only the host is left out.
+ */
+export declare function useQuietProcessOutput(): Operation<void>;
 export {};

package/types/config.d.ts

@@ -1,24 +1,42 @@
 /**
  * Config Api — shared execution configuration with pluggable middleware.
  *
- * Supplies the contextual timeout in milliseconds. Process, Fetch, and
- * Agent operations read it when a call does not provide an explicit
- * timeout. Override it for a scope with:
+ * Three timeouts, three owners, no defaults:
+ *
+ * - `timeout` is the deadline for the whole run — preparation and execution
+ *   together — and only the outer run boundary consumes it.
+ * - `timeoutExec` is what each exec block gets, and only exec blocks and the
+ *   built-in `timeout` modifier consume it.
+ * - `timeoutFetch` is what each Fetch gets, and only Fetch consumes it.
+ *
+ * `undefined` means no timeout, and it is what every field starts as. An
+ * operation nobody bounded runs until it finishes or the run's own deadline
+ * cancels it; a general "shared timeout" that quietly bounded processes,
+ * requests, prompts, and services alike is what this replaces. Override a
+ * field for a scope with:
  *
  * ```typescript
- * yield* Config.around({ timeout: () => 30_000 }, { at: "min" });
+ * yield* Config.around({ timeoutExec: () => 30_000 }, { at: "min" });
  * ```
+ *
+ * Installing at `min` is what lets a nested override win: a block's own
+ * `timeout=` outranks the value the command line established for the run.
+ * Omitting a field inherits the enclosing value rather than clearing it.
  */
 import { type Api } from "@effectionx/context-api";
 import type { Operation } from "effection";
 export interface ConfigApi {
-    /** Shared timeout in milliseconds. */
-    timeout: number;
+    /** Deadline for the entire run, in milliseconds; undefined for none. */
+    timeout: number | undefined;
+    /** Default timeout for each exec block, in milliseconds; undefined for none. */
+    timeoutExec: number | undefined;
+    /** Default timeout for each Fetch, in milliseconds; undefined for none. */
+    timeoutFetch: number | undefined;
 }
 export declare const Config: Api<ConfigApi>;
-/**
- * The validated contextual timeout. Always a positive, finite number of
- * milliseconds — a middleware-supplied value that is not valid fails loudly
- * here rather than silently disabling or corrupting timeouts downstream.
- */
-export declare const timeout: Operation<number>;
+/** The validated run deadline. Read by the run boundary and nothing else. */
+export declare const timeout: Operation<number | undefined>;
+/** The validated default timeout for an exec block. */
+export declare const timeoutExec: Operation<number | undefined>;
+/** The validated default timeout for a Fetch. */
+export declare const timeoutFetch: Operation<number | undefined>;

package/types/duration.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The duration grammar, in one place.
+ *
+ * Every timeout a caller or a document writes is spelled the same way: the
+ * three CLI options, and the `timeout=` modifier a block declares. A duration
+ * is a positive whole number with a unit — `500ms`, `30s`, `5min`, `20min` —
+ * or bare digits, which are milliseconds.
+ *
+ * Nothing here substitutes a value. An empty, zero, negative, or malformed
+ * duration is refused where it was written, because the alternative is a run
+ * bounded by a number nobody asked for.
+ */
+/** Milliseconds, or `undefined` when `text` is not a duration. */
+export declare function asDuration(text: string): number | undefined;
+/** What a rejected duration says, with `label` naming where it was written. */
+export declare function durationError(label: string, text: string): Error;
+/** Milliseconds. Throws when `text` is not a duration this grammar accepts. */
+export declare function parseDuration(text: string, label: string): number;

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>;