@earendil-works/pi-durable 0.87.0 → 0.99.0

package/README.md

@@ -2,12 +2,83 @@
 
 Durable conversation, task, and document runtime for Pi.
 
-This package contains the Pico runtime. Its current public API provides the durable record contracts and detached in-memory storage implementation:
+This package contains the Pico runtime. Its current public API provides durable record contracts and memory, JSONL, and SQLite storage implementations:
 
 ```ts
 import { MemoryStorage, ROOT_CONVERSATION_ID } from "@earendil-works/pi-durable";
 ```
 
+The root export is runtime-neutral. Storage implementations also have explicit subpaths:
+
+```ts
+import { MemoryStorage } from "@earendil-works/pi-durable/storage/memory";
+```
+
+Node applications can open file-backed JSONL or SQLite storage through Node-only subpaths:
+
+```ts
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { openNodeJsonlStorage } from "@earendil-works/pi-durable/storage/jsonl/node";
+import { openNodeSqliteStorage } from "@earendil-works/pi-durable/storage/sqlite/node";
+
+const jsonl = await openNodeJsonlStorage("./session", BACKGROUND_CONTEXT);
+const sqlite = await openNodeSqliteStorage("./session.sqlite");
+```
+
+The portable JSONL core accepts the `FileSystem` capability exported from `@earendil-works/pi-durable/env`. Its `fsync` option defaults to `false`; enabling it flushes affected sidecars before appending the main commit marker. One `JsonlStorage` owner must serialize writes to a storage directory; cross-process locking and ID allocation are not supported.
+
+The portable SQLite core, minimal database facade, and ordered schema migrations are exported from `@earendil-works/pi-durable/storage/sqlite`. Adapters for synchronous SQLite environments such as Bun and Cloudflare Durable Objects can implement that facade without importing Node APIs. Remote asynchronous APIs such as Cloudflare D1 cannot implement this synchronous facade; they require a dedicated `Storage` backend.
+
+The Node adapter uses WAL mode with `synchronous = NORMAL` and checkpoints the WAL on close. Acknowledged commits survive process crashes, but the newest commits may be lost after a power or host failure. One `SqliteStorage` owner must serialize writes to a database file; cross-process ID allocation is not supported.
+
+## Storage conformance
+
+Storage adapters can register the runner-independent conformance cases through the testing entry. The convenience adapter accepts Vitest/Jest-compatible runner functions without importing either package:
+
+```ts
+import { registerStorageConformance } from "@earendil-works/pi-durable/testing";
+import { describe, expect, it } from "vitest";
+
+registerStorageConformance({ describe, expect, it }, "Some Custom Storage", async (use) => {
+	const storage = await openCustomStorage();
+	try {
+		await use(storage);
+	} finally {
+		await closeStorage(storage);
+	}
+});
+```
+
+The provider must call and await `use` exactly once with isolated storage. Other runners can use `createStorageConformance` with their own `StorageConformanceAssertions` implementation.
+
+## Storage benchmarks
+
+From this package directory:
+
+```sh
+npm run bench:storage
+npm run bench:storage:memory
+```
+
+The timing suite runs shared deterministic workloads against the built-in memory, JSONL, and SQLite adapters. Third-party adapters can import the same seeds and workload definitions from `@earendil-works/pi-durable/testing` and use their platform's timing runner:
+
+```ts
+import {
+	seedStorageBenchmark,
+	seedStorageWriteBenchmark,
+	STORAGE_READ_BENCHMARKS,
+	STORAGE_WRITE_BENCHMARKS,
+} from "@earendil-works/pi-durable/testing";
+
+const dataset = await seedStorageBenchmark(readStorage);
+await STORAGE_READ_BENCHMARKS[0].run(readStorage, dataset);
+
+await seedStorageWriteBenchmark(freshWriteStorage);
+await STORAGE_WRITE_BENCHMARKS[0].run(freshWriteStorage);
+```
+
+Read scenarios reuse one seeded store; each write sample requires a fresh seeded store. The workloads cover representative commits, indexed reads, pagination, fork traversal, document replay, historical reads, and persistent-backend reopen. The footprint suite measures each built-in adapter in a separate process at 1k and 10k scales and reports heap, RSS, external memory, file counts, and on-disk JSONL/SQLite size. These synthetic workloads are baselines for regression analysis, not production capacity limits or CI pass/fail thresholds.
+
 The normative design and implementation sequence are in:
 
 - [`docs/pico-v5.md`](docs/pico-v5.md)

package/dist/documents.d.ts

@@ -0,0 +1,66 @@
+import { type JsonValue } from "@earendil-works/chord";
+import type { Op } from "@earendil-works/chord/delta";
+import type { CheckpointInfo, CommonDocDefinition, ConversationDocFamilyToken, ConversationDocToken, DocumentAddress, DocumentCreate, DocumentId, DocumentRecord, DocumentSemantics, JsonObject, LatestConversationSemantics, RewindableConversationDocFamilyToken, RewindableConversationDocToken, RewindableConversationSemantics, SessionDocFamilyToken, SessionDocToken, StoredDocument, TaskDocFamilyToken, TaskDocToken } from "./types.ts";
+type FamilyInput<T extends JsonObject, I extends JsonValue> = Omit<CommonDocDefinition<T>, "initial"> & {
+    readonly family: true;
+    initial(seed: I): T;
+};
+/** Define a Session-scoped singleton document. */
+export declare function defineDoc<T extends JsonObject>(definition: CommonDocDefinition<T> & {
+    readonly scope: "session";
+}): SessionDocToken<T>;
+/** Define a latest-only conversation singleton document. */
+export declare function defineDoc<T extends JsonObject>(definition: CommonDocDefinition<T> & LatestConversationSemantics): ConversationDocToken<T>;
+/** Define a rewindable conversation singleton document. */
+export declare function defineDoc<T extends JsonObject>(definition: CommonDocDefinition<T> & RewindableConversationSemantics): RewindableConversationDocToken<T>;
+/** Define a task-scoped singleton document. */
+export declare function defineDoc<T extends JsonObject>(definition: CommonDocDefinition<T> & {
+    readonly scope: "task";
+}): TaskDocToken<T>;
+/** Define a Session-scoped document family. */
+export declare function defineDocFamily<T extends JsonObject, I extends JsonValue>(definition: FamilyInput<T, I> & {
+    readonly scope: "session";
+}): SessionDocFamilyToken<T, I>;
+/** Define a latest-only conversation document family. */
+export declare function defineDocFamily<T extends JsonObject, I extends JsonValue>(definition: FamilyInput<T, I> & LatestConversationSemantics): ConversationDocFamilyToken<T, I>;
+/** Define a rewindable conversation document family. */
+export declare function defineDocFamily<T extends JsonObject, I extends JsonValue>(definition: FamilyInput<T, I> & RewindableConversationSemantics): RewindableConversationDocFamilyToken<T, I>;
+/** Define a task-scoped document family. */
+export declare function defineDocFamily<T extends JsonObject, I extends JsonValue>(definition: FamilyInput<T, I> & {
+    readonly scope: "task";
+}): TaskDocFamilyToken<T, I>;
+/** Erased definition shape used by the Session after overload resolution. */
+export type AnyDocDefinition = DocumentSemantics & {
+    readonly kind: string;
+    readonly version: number;
+    readonly family?: true;
+    initial(seed?: JsonValue): JsonObject;
+    migrate?(value: JsonObject, fromVersion: number): JsonObject;
+    checkpointWhen?(value: Readonly<JsonObject>, ops: readonly Op[], info: CheckpointInfo): boolean;
+};
+/** Erased singleton or family token. */
+export type AnyDocToken = {
+    readonly definition: AnyDocDefinition;
+};
+/** Logical address plus its string identity for maps. */
+export type ResolvedAddress = {
+    readonly address: DocumentAddress;
+    readonly id: string;
+    readonly nextArgument: number;
+};
+/** Resolve an overloaded argument list and return the index after the owner and family key. */
+export declare function resolveAddress(definition: AnyDocDefinition, args: readonly unknown[]): ResolvedAddress;
+/** Stable string identity of one logical address. */
+export declare function addressId(address: DocumentAddress): string;
+/** Build the storage create record for a new incarnation at an address. */
+export declare function documentCreate(definition: AnyDocDefinition, address: DocumentAddress, id: DocumentId): DocumentCreate;
+/** Reject typed access whose token disagrees with the persisted scope, history, or fork semantics. */
+export declare function checkRecordScope(definition: AnyDocDefinition, record: DocumentCreate | DocumentRecord): void;
+/** Reject typed access to a stored version the supplied definition cannot use. */
+export declare function checkRecordVersion(definition: AnyDocDefinition, record: DocumentCreate | DocumentRecord, version: number): void;
+/** Validate and materialize a detached stored value for typed access. */
+export declare function materializeDocument(definition: AnyDocDefinition, stored: StoredDocument): JsonObject;
+/** Validate and materialize one detached value before its first persisted incarnation. */
+export declare function materializeDocumentValue(definition: AnyDocDefinition, record: DocumentCreate | DocumentRecord, version: number, value: JsonObject): JsonObject;
+export {};
+//# sourceMappingURL=documents.d.ts.map

package/dist/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"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"}

package/dist/documents.js

@@ -0,0 +1,98 @@
+import { copyJson } from "@earendil-works/chord";
+import { idFromNumber } from "./ids.js";
+export function defineDoc(definition) {
+    validateDefinition(definition);
+    return { definition };
+}
+export function defineDocFamily(definition) {
+    validateDefinition(definition);
+    return { definition };
+}
+function validateDefinition(definition) {
+    if (!Number.isSafeInteger(definition.version) || definition.version < 1) {
+        throw new TypeError(`Document ${definition.kind} version must be a positive integer`);
+    }
+}
+/** Resolve an overloaded argument list and return the index after the owner and family key. */
+export function resolveAddress(definition, args) {
+    let index = 0;
+    let scope;
+    switch (definition.scope) {
+        case "session":
+            scope = { kind: "session" };
+            break;
+        case "conversation":
+            scope = { kind: "conversation", conversationId: ownerId(args[index++], definition) };
+            break;
+        case "task":
+            scope = { kind: "task", taskId: ownerId(args[index++], definition) };
+            break;
+    }
+    const key = definition.family === true ? args[index++] : undefined;
+    const address = key === undefined ? { kind: definition.kind, scope } : { kind: definition.kind, scope, key };
+    return { address, id: addressId(address), nextArgument: index };
+}
+function ownerId(value, definition) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+        throw new TypeError(`Document ${definition.kind} requires a ${definition.scope} ID`);
+    }
+    return idFromNumber(value);
+}
+/** Stable string identity of one logical address. */
+export function addressId(address) {
+    const owner = address.scope.kind === "session"
+        ? null
+        : address.scope.kind === "conversation"
+            ? address.scope.conversationId
+            : address.scope.taskId;
+    return JSON.stringify([address.kind, address.scope.kind, owner, address.key ?? null]);
+}
+/** Build the storage create record for a new incarnation at an address. */
+export function documentCreate(definition, address, id) {
+    const key = address.key === undefined ? {} : { key: address.key };
+    switch (address.scope.kind) {
+        case "session":
+            return { id, kind: address.kind, ...key, scope: address.scope };
+        case "task":
+            return { id, kind: address.kind, ...key, scope: address.scope };
+        case "conversation":
+            return {
+                id,
+                kind: address.kind,
+                ...key,
+                scope: address.scope,
+                history: definition.history,
+                fork: definition.fork,
+            };
+    }
+}
+/** Reject typed access whose token disagrees with the persisted scope, history, or fork semantics. */
+export function checkRecordScope(definition, record) {
+    if (record.scope.kind !== definition.scope ||
+        (record.scope.kind === "conversation" &&
+            (record.history !== definition.history || record.fork !== definition.fork))) {
+        throw new TypeError(`Document ${record.id} (${record.kind}) does not match the supplied definition semantics`);
+    }
+}
+/** Reject typed access to a stored version the supplied definition cannot use. */
+export function checkRecordVersion(definition, record, version) {
+    if (version > definition.version) {
+        throw new Error(`Document ${record.id} (${record.kind}) has newer version ${version} than ${definition.version}`);
+    }
+    if (version < definition.version && definition.migrate === undefined) {
+        throw new Error(`Document ${record.id} (${record.kind}) requires migration from version ${version}`);
+    }
+}
+/** Validate and materialize a detached stored value for typed access. */
+export function materializeDocument(definition, stored) {
+    return materializeDocumentValue(definition, stored.record, stored.version, stored.value);
+}
+/** Validate and materialize one detached value before its first persisted incarnation. */
+export function materializeDocumentValue(definition, record, version, value) {
+    checkRecordScope(definition, record);
+    checkRecordVersion(definition, record, version);
+    if (version === definition.version)
+        return value;
+    return copyJson(definition.migrate(value, version));
+}
+//# sourceMappingURL=documents.js.map

package/dist/documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../src/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAkB,MAAM,uBAAuB,CAAC;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAmDxC,MAAM,UAAU,SAAS,CAAuB,UAA4B;IAC3E,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC/B,OAAO,EAAE,UAAU,EAAE,CAAC;AACvB,CAAC;AAkBD,MAAM,UAAU,eAAe,CAC9B,UAAqC;IAErC,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC/B,OAAO,EAAE,UAAU,EAAE,CAAC;AACvB,CAAC;AAeD,SAAS,kBAAkB,CAAC,UAA4B;IACvD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QACzE,MAAM,IAAI,SAAS,CAAC,YAAY,UAAU,CAAC,IAAI,qCAAqC,CAAC,CAAC;IACvF,CAAC;AACF,CAAC;AASD,+FAA+F;AAC/F,MAAM,UAAU,cAAc,CAAC,UAA4B,EAAE,IAAwB;IACpF,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAA+B,CAAC;IACpC,QAAQ,UAAU,CAAC,KAAK,EAAE,CAAC;QAC1B,KAAK,SAAS;YACb,KAAK,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;YAC5B,MAAM;QACP,KAAK,cAAc;YAClB,KAAK,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,cAAc,EAAE,OAAO,CAAiB,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC;YACrG,MAAM;QACP,KAAK,MAAM;YACV,KAAK,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAS,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC;YAC7E,MAAM;IACR,CAAC;IACD,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,EAAE,CAAY,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/E,MAAM,OAAO,GACZ,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAC9F,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;AACjE,CAAC;AAED,SAAS,OAAO,CAAuB,KAAc,EAAE,UAA4B;IAClF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,SAAS,CAAC,YAAY,UAAU,CAAC,IAAI,eAAe,UAAU,CAAC,KAAK,KAAK,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,YAAY,CAAI,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,SAAS,CAAC,OAAwB;IACjD,MAAM,KAAK,GACV,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS;QAC/B,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,cAAc;YACtC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc;YAC9B,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;IAC1B,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC;AACvF,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,UAA4B,EAAE,OAAwB,EAAE,EAAc;IACpG,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;IAClE,QAAQ,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAC5B,KAAK,SAAS;YACb,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QACjE,KAAK,MAAM;YACV,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QACjE,KAAK,cAAc;YAClB,OAAO;gBACN,EAAE;gBACF,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,GAAG,GAAG;gBACN,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,OAAO,EAAE,UAAU,CAAC,OAAQ;gBAC5B,IAAI,EAAE,UAAU,CAAC,IAAK;aACJ,CAAC;IACtB,CAAC;AACF,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,gBAAgB,CAAC,UAA4B,EAAE,MAAuC;IACrG,IACC,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,KAAK;QACtC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,cAAc;YACpC,CAAC,MAAM,CAAC,OAAO,KAAK,UAAU,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,IAAI,CAAC,CAAC,EAC3E,CAAC;QACF,MAAM,IAAI,SAAS,CAAC,YAAY,MAAM,CAAC,EAAE,KAAK,MAAM,CAAC,IAAI,oDAAoD,CAAC,CAAC;IAChH,CAAC;AACF,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,kBAAkB,CACjC,UAA4B,EAC5B,MAAuC,EACvC,OAAe;IAEf,IAAI,OAAO,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,YAAY,MAAM,CAAC,EAAE,KAAK,MAAM,CAAC,IAAI,uBAAuB,OAAO,SAAS,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;IACnH,CAAC;IACD,IAAI,OAAO,GAAG,UAAU,CAAC,OAAO,IAAI,UAAU,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,YAAY,MAAM,CAAC,EAAE,KAAK,MAAM,CAAC,IAAI,qCAAqC,OAAO,EAAE,CAAC,CAAC;IACtG,CAAC;AACF,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,mBAAmB,CAAC,UAA4B,EAAE,MAAsB;IACvF,OAAO,wBAAwB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1F,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,wBAAwB,CACvC,UAA4B,EAC5B,MAAuC,EACvC,OAAe,EACf,KAAiB;IAEjB,gBAAgB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACrC,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,IAAI,OAAO,KAAK,UAAU,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IACjD,OAAO,QAAQ,CAAC,UAAU,CAAC,OAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAe,CAAC;AACpE,CAAC","sourcesContent":["import { copyJson, type JsonValue } from \"@earendil-works/chord\";\nimport type { Op } from \"@earendil-works/chord/delta\";\nimport { idFromNumber } from \"./ids.ts\";\nimport type {\n\tCheckpointInfo,\n\tCommonDocDefinition,\n\tConversationDocFamilyToken,\n\tConversationDocToken,\n\tConversationId,\n\tDocDefinition,\n\tDocFamilyDefinition,\n\tDocFamilyToken,\n\tDocToken,\n\tDocumentAddress,\n\tDocumentCreate,\n\tDocumentId,\n\tDocumentRecord,\n\tDocumentSemantics,\n\tId,\n\tJsonObject,\n\tLatestConversationSemantics,\n\tRewindableConversationDocFamilyToken,\n\tRewindableConversationDocToken,\n\tRewindableConversationSemantics,\n\tSessionDocFamilyToken,\n\tSessionDocToken,\n\tStoredDocument,\n\tTaskDocFamilyToken,\n\tTaskDocToken,\n\tTaskId,\n} from \"./types.ts\";\n\ntype FamilyInput<T extends JsonObject, I extends JsonValue> = Omit<CommonDocDefinition<T>, \"initial\"> & {\n\treadonly family: true;\n\tinitial(seed: I): T;\n};\n\n/** Define a Session-scoped singleton document. */\nexport function defineDoc<T extends JsonObject>(\n\tdefinition: CommonDocDefinition<T> & { readonly scope: \"session\" },\n): SessionDocToken<T>;\n/** Define a latest-only conversation singleton document. */\nexport function defineDoc<T extends JsonObject>(\n\tdefinition: CommonDocDefinition<T> & LatestConversationSemantics,\n): ConversationDocToken<T>;\n/** Define a rewindable conversation singleton document. */\nexport function defineDoc<T extends JsonObject>(\n\tdefinition: CommonDocDefinition<T> & RewindableConversationSemantics,\n): RewindableConversationDocToken<T>;\n/** Define a task-scoped singleton document. */\nexport function defineDoc<T extends JsonObject>(\n\tdefinition: CommonDocDefinition<T> & { readonly scope: \"task\" },\n): TaskDocToken<T>;\nexport function defineDoc<T extends JsonObject>(definition: DocDefinition<T>): DocToken<T, DocDefinition<T>> {\n\tvalidateDefinition(definition);\n\treturn { definition };\n}\n\n/** Define a Session-scoped document family. */\nexport function defineDocFamily<T extends JsonObject, I extends JsonValue>(\n\tdefinition: FamilyInput<T, I> & { readonly scope: \"session\" },\n): SessionDocFamilyToken<T, I>;\n/** Define a latest-only conversation document family. */\nexport function defineDocFamily<T extends JsonObject, I extends JsonValue>(\n\tdefinition: FamilyInput<T, I> & LatestConversationSemantics,\n): ConversationDocFamilyToken<T, I>;\n/** Define a rewindable conversation document family. */\nexport function defineDocFamily<T extends JsonObject, I extends JsonValue>(\n\tdefinition: FamilyInput<T, I> & RewindableConversationSemantics,\n): RewindableConversationDocFamilyToken<T, I>;\n/** Define a task-scoped document family. */\nexport function defineDocFamily<T extends JsonObject, I extends JsonValue>(\n\tdefinition: FamilyInput<T, I> & { readonly scope: \"task\" },\n): TaskDocFamilyToken<T, I>;\nexport function defineDocFamily<T extends JsonObject, I extends JsonValue>(\n\tdefinition: DocFamilyDefinition<T, I>,\n): DocFamilyToken<T, I, DocFamilyDefinition<T, I>> {\n\tvalidateDefinition(definition);\n\treturn { definition };\n}\n\n/** Erased definition shape used by the Session after overload resolution. */\nexport type AnyDocDefinition = DocumentSemantics & {\n\treadonly kind: string;\n\treadonly version: number;\n\treadonly family?: true;\n\tinitial(seed?: JsonValue): JsonObject;\n\tmigrate?(value: JsonObject, fromVersion: number): JsonObject;\n\tcheckpointWhen?(value: Readonly<JsonObject>, ops: readonly Op[], info: CheckpointInfo): boolean;\n};\n\n/** Erased singleton or family token. */\nexport type AnyDocToken = { readonly definition: AnyDocDefinition };\n\nfunction validateDefinition(definition: AnyDocDefinition): void {\n\tif (!Number.isSafeInteger(definition.version) || definition.version < 1) {\n\t\tthrow new TypeError(`Document ${definition.kind} version must be a positive integer`);\n\t}\n}\n\n/** Logical address plus its string identity for maps. */\nexport type ResolvedAddress = {\n\treadonly address: DocumentAddress;\n\treadonly id: string;\n\treadonly nextArgument: number;\n};\n\n/** Resolve an overloaded argument list and return the index after the owner and family key. */\nexport function resolveAddress(definition: AnyDocDefinition, args: readonly unknown[]): ResolvedAddress {\n\tlet index = 0;\n\tlet scope: DocumentAddress[\"scope\"];\n\tswitch (definition.scope) {\n\t\tcase \"session\":\n\t\t\tscope = { kind: \"session\" };\n\t\t\tbreak;\n\t\tcase \"conversation\":\n\t\t\tscope = { kind: \"conversation\", conversationId: ownerId<ConversationId>(args[index++], definition) };\n\t\t\tbreak;\n\t\tcase \"task\":\n\t\t\tscope = { kind: \"task\", taskId: ownerId<TaskId>(args[index++], definition) };\n\t\t\tbreak;\n\t}\n\tconst key = definition.family === true ? (args[index++] as string) : undefined;\n\tconst address: DocumentAddress =\n\t\tkey === undefined ? { kind: definition.kind, scope } : { kind: definition.kind, scope, key };\n\treturn { address, id: addressId(address), nextArgument: index };\n}\n\nfunction ownerId<I extends Id<string>>(value: unknown, definition: AnyDocDefinition): I {\n\tif (typeof value !== \"number\" || !Number.isSafeInteger(value)) {\n\t\tthrow new TypeError(`Document ${definition.kind} requires a ${definition.scope} ID`);\n\t}\n\treturn idFromNumber<I>(value);\n}\n\n/** Stable string identity of one logical address. */\nexport function addressId(address: DocumentAddress): string {\n\tconst owner =\n\t\taddress.scope.kind === \"session\"\n\t\t\t? null\n\t\t\t: address.scope.kind === \"conversation\"\n\t\t\t\t? address.scope.conversationId\n\t\t\t\t: address.scope.taskId;\n\treturn JSON.stringify([address.kind, address.scope.kind, owner, address.key ?? null]);\n}\n\n/** Build the storage create record for a new incarnation at an address. */\nexport function documentCreate(definition: AnyDocDefinition, address: DocumentAddress, id: DocumentId): DocumentCreate {\n\tconst key = address.key === undefined ? {} : { key: address.key };\n\tswitch (address.scope.kind) {\n\t\tcase \"session\":\n\t\t\treturn { id, kind: address.kind, ...key, scope: address.scope };\n\t\tcase \"task\":\n\t\t\treturn { id, kind: address.kind, ...key, scope: address.scope };\n\t\tcase \"conversation\":\n\t\t\treturn {\n\t\t\t\tid,\n\t\t\t\tkind: address.kind,\n\t\t\t\t...key,\n\t\t\t\tscope: address.scope,\n\t\t\t\thistory: definition.history!,\n\t\t\t\tfork: definition.fork!,\n\t\t\t} as DocumentCreate;\n\t}\n}\n\n/** Reject typed access whose token disagrees with the persisted scope, history, or fork semantics. */\nexport function checkRecordScope(definition: AnyDocDefinition, record: DocumentCreate | DocumentRecord): void {\n\tif (\n\t\trecord.scope.kind !== definition.scope ||\n\t\t(record.scope.kind === \"conversation\" &&\n\t\t\t(record.history !== definition.history || record.fork !== definition.fork))\n\t) {\n\t\tthrow new TypeError(`Document ${record.id} (${record.kind}) does not match the supplied definition semantics`);\n\t}\n}\n\n/** Reject typed access to a stored version the supplied definition cannot use. */\nexport function checkRecordVersion(\n\tdefinition: AnyDocDefinition,\n\trecord: DocumentCreate | DocumentRecord,\n\tversion: number,\n): void {\n\tif (version > definition.version) {\n\t\tthrow new Error(`Document ${record.id} (${record.kind}) has newer version ${version} than ${definition.version}`);\n\t}\n\tif (version < definition.version && definition.migrate === undefined) {\n\t\tthrow new Error(`Document ${record.id} (${record.kind}) requires migration from version ${version}`);\n\t}\n}\n\n/** Validate and materialize a detached stored value for typed access. */\nexport function materializeDocument(definition: AnyDocDefinition, stored: StoredDocument): JsonObject {\n\treturn materializeDocumentValue(definition, stored.record, stored.version, stored.value);\n}\n\n/** Validate and materialize one detached value before its first persisted incarnation. */\nexport function materializeDocumentValue(\n\tdefinition: AnyDocDefinition,\n\trecord: DocumentCreate | DocumentRecord,\n\tversion: number,\n\tvalue: JsonObject,\n): JsonObject {\n\tcheckRecordScope(definition, record);\n\tcheckRecordVersion(definition, record, version);\n\tif (version === definition.version) return value;\n\treturn copyJson(definition.migrate!(value, version)) as JsonObject;\n}\n"]}

package/dist/entries.d.ts

@@ -0,0 +1,13 @@
+import type { JsonValue } from "@earendil-works/chord";
+import type { Entry } from "./types.ts";
+/** Define a typed entry kind whose `is()` guard narrows by `EntryRecord.kind`. */
+export declare function defineEntry<D extends JsonValue = never>(kind: string): Entry<D>;
+/** User input: `model` is `[UserMessage]`. Written by submissions. */
+export declare const UserEntry: Entry<never>;
+/** Provider result with any stop reason: `model` is `[AssistantMessage]`. Written by generation. */
+export declare const AssistantEntry: Entry<never>;
+/** Positional prompt and tool change: `model` is `[SystemMessage]` with empty `content`. */
+export declare const SystemEntry: Entry<never>;
+/** Tool result: `model` is `[ToolResultMessage]`. Written by tool tasks. */
+export declare const ToolResultEntry: Entry<never>;
+//# sourceMappingURL=entries.d.ts.map

package/dist/entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../src/entries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAA2B,MAAM,YAAY,CAAC;AAEjE,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,GAAG,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAM/E;AAED,sEAAsE;AACtE,eAAO,MAAM,SAAS,cAAyB,CAAC;AAChD,oGAAoG;AACpG,eAAO,MAAM,cAAc,cAA8B,CAAC;AAC1D,4FAA4F;AAC5F,eAAO,MAAM,WAAW,cAA2B,CAAC;AACpD,4EAA4E;AAC5E,eAAO,MAAM,eAAe,cAAgC,CAAC"}

package/dist/entries.js

@@ -0,0 +1,18 @@
+/** Define a typed entry kind whose `is()` guard narrows by `EntryRecord.kind`. */
+export function defineEntry(kind) {
+    if (typeof kind !== "string" || kind.length === 0)
+        throw new TypeError("Entry kind must be a non-empty string");
+    return {
+        kind,
+        is: (entry) => entry !== undefined && entry.kind === kind,
+    };
+}
+/** User input: `model` is `[UserMessage]`. Written by submissions. */
+export const UserEntry = defineEntry("pi.user");
+/** Provider result with any stop reason: `model` is `[AssistantMessage]`. Written by generation. */
+export const AssistantEntry = defineEntry("pi.assistant");
+/** Positional prompt and tool change: `model` is `[SystemMessage]` with empty `content`. */
+export const SystemEntry = defineEntry("pi.system");
+/** Tool result: `model` is `[ToolResultMessage]`. Written by tool tasks. */
+export const ToolResultEntry = defineEntry("pi.tool-result");
+//# sourceMappingURL=entries.js.map

package/dist/entries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.js","sourceRoot":"","sources":["../src/entries.ts"],"names":[],"mappings":"AAGA,kFAAkF;AAClF,MAAM,UAAU,WAAW,CAA8B,IAAY;IACpE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,uCAAuC,CAAC,CAAC;IAChH,OAAO;QACN,IAAI;QACJ,EAAE,EAAE,CAAC,KAA8B,EAA0B,EAAE,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI;KAC1G,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;AAChD,oGAAoG;AACpG,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC,cAAc,CAAC,CAAC;AAC1D,4FAA4F;AAC5F,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;AACpD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC,gBAAgB,CAAC,CAAC","sourcesContent":["import type { JsonValue } from \"@earendil-works/chord\";\nimport type { Entry, EntryRecord, TypedEntry } from \"./types.ts\";\n\n/** Define a typed entry kind whose `is()` guard narrows by `EntryRecord.kind`. */\nexport function defineEntry<D extends JsonValue = never>(kind: string): Entry<D> {\n\tif (typeof kind !== \"string\" || kind.length === 0) throw new TypeError(\"Entry kind must be a non-empty string\");\n\treturn {\n\t\tkind,\n\t\tis: (entry: EntryRecord | undefined): entry is TypedEntry<D> => entry !== undefined && entry.kind === kind,\n\t};\n}\n\n/** User input: `model` is `[UserMessage]`. Written by submissions. */\nexport const UserEntry = defineEntry(\"pi.user\");\n/** Provider result with any stop reason: `model` is `[AssistantMessage]`. Written by generation. */\nexport const AssistantEntry = defineEntry(\"pi.assistant\");\n/** Positional prompt and tool change: `model` is `[SystemMessage]` with empty `content`. */\nexport const SystemEntry = defineEntry(\"pi.system\");\n/** Tool result: `model` is `[ToolResultMessage]`. Written by tool tasks. */\nexport const ToolResultEntry = defineEntry(\"pi.tool-result\");\n"]}

package/dist/env/index.d.ts

@@ -0,0 +1,131 @@
+import type { Context } from "@earendil-works/chord";
+import type { TruncationResult } from "./utils/truncate.ts";
+/** Result of a fallible operation. Expected failures are returned instead of thrown. */
+export type Result<TValue, TError> = {
+    ok: true;
+    value: TValue;
+} | {
+    ok: false;
+    error: TError;
+};
+export declare function ok<TValue, TError>(value: TValue): Result<TValue, TError>;
+export declare function err<TValue, TError>(error: TError): Result<TValue, TError>;
+export declare function getOrThrow<TValue, TError>(result: Result<TValue, TError>): TValue;
+export declare function getOrUndefined<TValue extends object, TError>(result: Result<TValue, TError>): TValue | undefined;
+export declare function toError(error: unknown): Error;
+export type FileKind = "file" | "directory" | "symlink";
+export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not_directory" | "is_directory" | "invalid" | "not_supported" | "unknown";
+export declare class FileError extends Error {
+    code: FileErrorCode;
+    path?: string;
+    constructor(code: FileErrorCode, message: string, path?: string, cause?: Error);
+}
+export type ExecutionErrorCode = "aborted" | "timeout" | "shell_unavailable" | "spawn_error" | "callback_error" | "unknown";
+export declare class ExecutionError extends Error {
+    code: ExecutionErrorCode;
+    constructor(code: ExecutionErrorCode, message: string, cause?: Error);
+}
+export interface FileInfo {
+    name: string;
+    path: string;
+    kind: FileKind;
+    size: number;
+    mtimeMs: number;
+}
+export interface TextLine {
+    text: string;
+    terminated: boolean;
+}
+export interface TextLineReader {
+    readLine(context: Context): Promise<Result<TextLine | undefined, FileError>>;
+    close(context: Context): Promise<void>;
+}
+/** Portable filesystem capability. Operations return failures rather than throwing. */
+export interface FileSystem {
+    cwd: string;
+    absolutePath(path: string, context: Context): Promise<Result<string, FileError>>;
+    joinPath(parts: string[], context: Context): Promise<Result<string, FileError>>;
+    readTextFile(path: string, context: Context): Promise<Result<string, FileError>>;
+    openTextLineReader(path: string, context: Context): Promise<Result<TextLineReader, FileError>>;
+    readTextLines(path: string, options: {
+        maxLines?: number;
+    } | undefined, context: Context): Promise<Result<string[], FileError>>;
+    readBinaryFile(path: string, context: Context): Promise<Result<Uint8Array, FileError>>;
+    writeFile(path: string, content: string | Uint8Array, context: Context): Promise<Result<void, FileError>>;
+    appendFile(path: string, content: string | Uint8Array, context: Context): Promise<Result<void, FileError>>;
+    /** Truncate or extend a file to exactly `size` bytes. */
+    truncateFile(path: string, size: number, context: Context): Promise<Result<void, FileError>>;
+    /** Flush file contents and metadata needed to retrieve them from an open file handle. */
+    flushFile(path: string, context: Context): Promise<Result<void, FileError>>;
+    renameFile(sourcePath: string, destinationPath: string, context: Context): Promise<Result<void, FileError>>;
+    fileInfo(path: string, context: Context): Promise<Result<FileInfo, FileError>>;
+    listDir(path: string, context: Context): Promise<Result<FileInfo[], FileError>>;
+    canonicalPath(path: string, context: Context): Promise<Result<string, FileError>>;
+    exists(path: string, context: Context): Promise<Result<boolean, FileError>>;
+    createDir(path: string, options: {
+        recursive?: boolean;
+    } | undefined, context: Context): Promise<Result<void, FileError>>;
+    remove(path: string, options: {
+        recursive?: boolean;
+        force?: boolean;
+    } | undefined, context: Context): Promise<Result<void, FileError>>;
+    createTempDir(prefix: string | undefined, context: Context): Promise<Result<string, FileError>>;
+    createTempFile(options: {
+        prefix?: string;
+        suffix?: string;
+    } | undefined, context: Context): Promise<Result<string, FileError>>;
+    cleanup(context: Context): Promise<void>;
+}
+export type ShellOutputRetention = "head" | "tail";
+export interface ShellOutputLimits {
+    maxBytes: number;
+    maxLines: number;
+    retain?: ShellOutputRetention;
+}
+export interface ShellOutputCaptureOptions {
+    limits: ShellOutputLimits;
+    spill?: boolean;
+}
+export type ShellOutputTruncation = Omit<TruncationResult, "content">;
+export interface ShellOutputMetadata {
+    truncation: ShellOutputTruncation;
+    spillPath?: string;
+    lastLineBytes?: number;
+}
+export interface ShellOutputView extends ShellOutputMetadata {
+    text: string;
+}
+export type ShellOutputUpdate = {
+    kind: "replace";
+    output: ShellOutputView;
+} | {
+    kind: "append";
+    text: string;
+    metadata: ShellOutputMetadata;
+} | {
+    kind: "slide";
+    drop: number;
+    text: string;
+    metadata: ShellOutputMetadata;
+} | {
+    kind: "metadata";
+    metadata: ShellOutputMetadata;
+};
+export interface ShellExecResult extends ShellOutputMetadata {
+    exitCode: number;
+}
+export interface ShellExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    inheritEnv?: boolean;
+    timeout?: number;
+    capture?: ShellOutputCaptureOptions;
+    onUpdate?: (update: ShellOutputUpdate, context: Context) => void;
+}
+export interface Shell {
+    exec(command: string, options: ShellExecOptions | undefined, context: Context): Promise<Result<ShellExecResult, ExecutionError>>;
+    cleanup(context: Context): Promise<void>;
+}
+export interface ExecutionEnv extends FileSystem, Shell {
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/env/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":"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"}

package/dist/env/index.js

@@ -0,0 +1,45 @@
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}
+export function getOrThrow(result) {
+    if (!result.ok)
+        throw result.error;
+    return result.value;
+}
+export function getOrUndefined(result) {
+    return result.ok ? result.value : undefined;
+}
+export function toError(error) {
+    if (error instanceof Error)
+        return error;
+    if (typeof error === "string")
+        return new Error(error);
+    try {
+        return new Error(JSON.stringify(error));
+    }
+    catch {
+        return new Error(String(error));
+    }
+}
+export class FileError extends Error {
+    code;
+    path;
+    constructor(code, message, path, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "FileError";
+        this.code = code;
+        this.path = path;
+    }
+}
+export class ExecutionError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "ExecutionError";
+        this.code = code;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/env/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,EAAE,CAAiB,KAAa;IAC/C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,GAAG,CAAiB,KAAa;IAChD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,UAAU,CAAiB,MAA8B;IACxE,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,MAAM,CAAC,KAAK,CAAC;IACnC,OAAO,MAAM,CAAC,KAAK,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,cAAc,CAAgC,MAA8B;IAC3F,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAc;IACrC,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;IACvD,IAAI,CAAC;QACJ,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACjC,CAAC;AACF,CAAC;AAcD,MAAM,OAAO,SAAU,SAAQ,KAAK;IAC5B,IAAI,CAAgB;IACpB,IAAI,CAAU;IAErB,YAAY,IAAmB,EAAE,OAAe,EAAE,IAAa,EAAE,KAAa;QAC7E,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD;AAUD,MAAM,OAAO,cAAe,SAAQ,KAAK;IACjC,IAAI,CAAqB;IAEhC,YAAY,IAAwB,EAAE,OAAe,EAAE,KAAa;QACnE,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD","sourcesContent":["import type { Context } from \"@earendil-works/chord\";\nimport type { TruncationResult } from \"./utils/truncate.ts\";\n\n/** Result of a fallible operation. Expected failures are returned instead of thrown. */\nexport type Result<TValue, TError> = { ok: true; value: TValue } | { ok: false; error: TError };\n\nexport function ok<TValue, TError>(value: TValue): Result<TValue, TError> {\n\treturn { ok: true, value };\n}\n\nexport function err<TValue, TError>(error: TError): Result<TValue, TError> {\n\treturn { ok: false, error };\n}\n\nexport function getOrThrow<TValue, TError>(result: Result<TValue, TError>): TValue {\n\tif (!result.ok) throw result.error;\n\treturn result.value;\n}\n\nexport function getOrUndefined<TValue extends object, TError>(result: Result<TValue, TError>): TValue | undefined {\n\treturn result.ok ? result.value : undefined;\n}\n\nexport function toError(error: unknown): Error {\n\tif (error instanceof Error) return error;\n\tif (typeof error === \"string\") return new Error(error);\n\ttry {\n\t\treturn new Error(JSON.stringify(error));\n\t} catch {\n\t\treturn new Error(String(error));\n\t}\n}\n\nexport type FileKind = \"file\" | \"directory\" | \"symlink\";\n\nexport type FileErrorCode =\n\t| \"aborted\"\n\t| \"not_found\"\n\t| \"permission_denied\"\n\t| \"not_directory\"\n\t| \"is_directory\"\n\t| \"invalid\"\n\t| \"not_supported\"\n\t| \"unknown\";\n\nexport class FileError extends Error {\n\tpublic code: FileErrorCode;\n\tpublic path?: string;\n\n\tconstructor(code: FileErrorCode, message: string, path?: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"FileError\";\n\t\tthis.code = code;\n\t\tthis.path = path;\n\t}\n}\n\nexport type ExecutionErrorCode =\n\t| \"aborted\"\n\t| \"timeout\"\n\t| \"shell_unavailable\"\n\t| \"spawn_error\"\n\t| \"callback_error\"\n\t| \"unknown\";\n\nexport class ExecutionError extends Error {\n\tpublic code: ExecutionErrorCode;\n\n\tconstructor(code: ExecutionErrorCode, message: string, cause?: Error) {\n\t\tsuper(message, cause === undefined ? undefined : { cause });\n\t\tthis.name = \"ExecutionError\";\n\t\tthis.code = code;\n\t}\n}\n\nexport interface FileInfo {\n\tname: string;\n\tpath: string;\n\tkind: FileKind;\n\tsize: number;\n\tmtimeMs: number;\n}\n\nexport interface TextLine {\n\ttext: string;\n\tterminated: boolean;\n}\n\nexport interface TextLineReader {\n\treadLine(context: Context): Promise<Result<TextLine | undefined, FileError>>;\n\tclose(context: Context): Promise<void>;\n}\n\n/** Portable filesystem capability. Operations return failures rather than throwing. */\nexport interface FileSystem {\n\tcwd: string;\n\tabsolutePath(path: string, context: Context): Promise<Result<string, FileError>>;\n\tjoinPath(parts: string[], context: Context): Promise<Result<string, FileError>>;\n\treadTextFile(path: string, context: Context): Promise<Result<string, FileError>>;\n\topenTextLineReader(path: string, context: Context): Promise<Result<TextLineReader, FileError>>;\n\treadTextLines(\n\t\tpath: string,\n\t\toptions: { maxLines?: number } | undefined,\n\t\tcontext: Context,\n\t): Promise<Result<string[], FileError>>;\n\treadBinaryFile(path: string, context: Context): Promise<Result<Uint8Array, FileError>>;\n\twriteFile(path: string, content: string | Uint8Array, context: Context): Promise<Result<void, FileError>>;\n\tappendFile(path: string, content: string | Uint8Array, context: Context): Promise<Result<void, FileError>>;\n\t/** Truncate or extend a file to exactly `size` bytes. */\n\ttruncateFile(path: string, size: number, context: Context): Promise<Result<void, FileError>>;\n\t/** Flush file contents and metadata needed to retrieve them from an open file handle. */\n\tflushFile(path: string, context: Context): Promise<Result<void, FileError>>;\n\trenameFile(sourcePath: string, destinationPath: string, context: Context): Promise<Result<void, FileError>>;\n\tfileInfo(path: string, context: Context): Promise<Result<FileInfo, FileError>>;\n\tlistDir(path: string, context: Context): Promise<Result<FileInfo[], FileError>>;\n\tcanonicalPath(path: string, context: Context): Promise<Result<string, FileError>>;\n\texists(path: string, context: Context): Promise<Result<boolean, FileError>>;\n\tcreateDir(\n\t\tpath: string,\n\t\toptions: { recursive?: boolean } | undefined,\n\t\tcontext: Context,\n\t): Promise<Result<void, FileError>>;\n\tremove(\n\t\tpath: string,\n\t\toptions: { recursive?: boolean; force?: boolean } | undefined,\n\t\tcontext: Context,\n\t): Promise<Result<void, FileError>>;\n\tcreateTempDir(prefix: string | undefined, context: Context): Promise<Result<string, FileError>>;\n\tcreateTempFile(\n\t\toptions: { prefix?: string; suffix?: string } | undefined,\n\t\tcontext: Context,\n\t): Promise<Result<string, FileError>>;\n\tcleanup(context: Context): Promise<void>;\n}\n\nexport type ShellOutputRetention = \"head\" | \"tail\";\n\nexport interface ShellOutputLimits {\n\tmaxBytes: number;\n\tmaxLines: number;\n\tretain?: ShellOutputRetention;\n}\n\nexport interface ShellOutputCaptureOptions {\n\tlimits: ShellOutputLimits;\n\tspill?: boolean;\n}\n\nexport type ShellOutputTruncation = Omit<TruncationResult, \"content\">;\n\nexport interface ShellOutputMetadata {\n\ttruncation: ShellOutputTruncation;\n\tspillPath?: string;\n\tlastLineBytes?: number;\n}\n\nexport interface ShellOutputView extends ShellOutputMetadata {\n\ttext: string;\n}\n\nexport type ShellOutputUpdate =\n\t| { kind: \"replace\"; output: ShellOutputView }\n\t| { kind: \"append\"; text: string; metadata: ShellOutputMetadata }\n\t| { kind: \"slide\"; drop: number; text: string; metadata: ShellOutputMetadata }\n\t| { kind: \"metadata\"; metadata: ShellOutputMetadata };\n\nexport interface ShellExecResult extends ShellOutputMetadata {\n\texitCode: number;\n}\n\nexport interface ShellExecOptions {\n\tcwd?: string;\n\tenv?: Record<string, string>;\n\tinheritEnv?: boolean;\n\ttimeout?: number;\n\tcapture?: ShellOutputCaptureOptions;\n\tonUpdate?: (update: ShellOutputUpdate, context: Context) => void;\n}\n\nexport interface Shell {\n\texec(\n\t\tcommand: string,\n\t\toptions: ShellExecOptions | undefined,\n\t\tcontext: Context,\n\t): Promise<Result<ShellExecResult, ExecutionError>>;\n\tcleanup(context: Context): Promise<void>;\n}\n\nexport interface ExecutionEnv extends FileSystem, Shell {}\n"]}

package/dist/env/node.d.ts

@@ -0,0 +1,45 @@
+import type { Context } from "@earendil-works/chord";
+import { type ExecutionEnv, ExecutionError, FileError, type FileInfo, type Result, type ShellExecOptions, type ShellExecResult, type TextLineReader } from "./index.ts";
+export declare class NodeExecutionEnv implements ExecutionEnv {
+    cwd: string;
+    private shellPath?;
+    private shellEnv?;
+    private activeChildPids;
+    constructor(options: {
+        cwd: string;
+        shellPath?: string;
+        shellEnv?: NodeJS.ProcessEnv;
+    });
+    absolutePath(path: string, _context: Context): Promise<Result<string, FileError>>;
+    joinPath(parts: string[], _context: Context): Promise<Result<string, FileError>>;
+    exec(command: string, options: ShellExecOptions | undefined, context: Context): Promise<Result<ShellExecResult, ExecutionError>>;
+    openTextLineReader(path: string, context: Context): Promise<Result<TextLineReader, FileError>>;
+    readTextFile(path: string, context: Context): Promise<Result<string, FileError>>;
+    readTextLines(path: string, options: {
+        maxLines?: number;
+    } | undefined, context: Context): Promise<Result<string[], FileError>>;
+    readBinaryFile(path: string, context: Context): Promise<Result<Uint8Array, FileError>>;
+    writeFile(path: string, content: string | Uint8Array, context: Context): Promise<Result<void, FileError>>;
+    appendFile(path: string, content: string | Uint8Array, context: Context): Promise<Result<void, FileError>>;
+    truncateFile(path: string, size: number, context: Context): Promise<Result<void, FileError>>;
+    flushFile(path: string, context: Context): Promise<Result<void, FileError>>;
+    renameFile(sourcePath: string, destinationPath: string, context: Context): Promise<Result<void, FileError>>;
+    fileInfo(path: string, context: Context): Promise<Result<FileInfo, FileError>>;
+    listDir(path: string, context: Context): Promise<Result<FileInfo[], FileError>>;
+    canonicalPath(path: string, context: Context): Promise<Result<string, FileError>>;
+    exists(path: string, context: Context): Promise<Result<boolean, FileError>>;
+    createDir(path: string, options: {
+        recursive?: boolean;
+    } | undefined, context: Context): Promise<Result<void, FileError>>;
+    remove(path: string, options: {
+        recursive?: boolean;
+        force?: boolean;
+    } | undefined, context: Context): Promise<Result<void, FileError>>;
+    createTempDir(prefix: string | undefined, context: Context): Promise<Result<string, FileError>>;
+    createTempFile(options: {
+        prefix?: string;
+        suffix?: string;
+    } | undefined, context: Context): Promise<Result<string, FileError>>;
+    cleanup(_context: Context): Promise<void>;
+}
+//# sourceMappingURL=node.d.ts.map

package/dist/env/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/env/node.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EACN,KAAK,YAAY,EACjB,cAAc,EAEd,SAAS,EACT,KAAK,QAAQ,EAGb,KAAK,MAAM,EACX,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAEpB,KAAK,cAAc,EAEnB,MAAM,YAAY,CAAC;AAkZpB,qBAAa,gBAAiB,YAAW,YAAY;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,CAAoB;IACrC,OAAO,CAAC,eAAe,CAAqB;IAE5C,YAAY,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;KAAE,EAIrF;IAEK,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAEtF;IAEK,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAErF;IAEK,IAAI,CACT,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,cAAc,CAAC,CAAC,CA2OlD;IAEK,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC,CAenG;IAEK,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAUrF;IAEK,aAAa,CAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,EAC1C,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,CAAC,CAgBtC;IAEK,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAU3F;IAEK,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAc9G;IAEK,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAe/G;IAEK,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAmBjG;IAEK,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAgBhF;IAEK,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAWhH;IAEK,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CASnF;IAEK,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAC,CAuBpF;IAEK,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAStF;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAKhF;IAEK,SAAS,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,EAC5C,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAUlC;IAEK,MAAM,CACX,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,EAC7D,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAUlC;IAEK,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CASpG;IAEK,cAAc,CACnB,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,EACzD,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAUpC;IAEK,OAAO,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9C;CACD"}