@xandreed/core 0.12.0 → 0.14.0

package/dist/turn/turn.conformance.js

@@ -1,14 +1,37 @@
-import { Context, Deferred, Effect, Fiber, Layer, Option, Ref } from "effect";
+import { LanguageModel } from "effect/ai";
+import { Context, Deferred, Effect, Fiber, Layer, Option, Ref, Stream } from "effect";
 import { ConformanceFailure } from "../conformance.entity.js";
+import { pixelPng, sameUsage } from "../conformance.functions.js";
+import { mediaFromBase64 } from "../domain/media.entity.functions.js";
+import { addUsage, tokenUsage, zeroUsage } from "../domain/token-usage.entity.functions.js";
 import { HarnessError } from "../harness/plugin.entity.js";
 import { IntentMatcher } from "../ports/capability.port.js";
 import { RunContext } from "../ports/run-context.port.js";
 import { Sessions } from "../ports/sessions.port.js";
+import { turnUsageOf } from "../session/session-event.entity.functions.js";
 import { UserMessage } from "./user-message.entity.js";
 const fail = (check) => (message) => Effect.fail(new ConformanceFailure({ check, message })), expect = (check, holds, message) => holds ? Effect.void : fail(check)(message), stored = (session) => session.sessions.read(session.address).pipe(Effect.mapError((error) => new HarnessError({ code: "conformance.session", message: error._tag }))), ofRun = (all, runId) => {
   const turn = Option.flatMap(Option.fromNullishOr(all.find((event) => event.kind === "turn.started" && event.data.runId === runId)), (event) => event.turn);
   return Option.match(turn, { onNone: () => [], onSome: (number) => all.filter((event) => Option.contains(event.turn, number)) });
-}, names = (session, runId) => stored(session).pipe(Effect.map((all) => ofRun(all, runId).map((event) => event.kind)));
+}, names = (session, runId) => stored(session).pipe(Effect.map((all) => ofRun(all, runId).map((event) => event.kind))), billedCall = (index) => ({
+  inputTokens: { total: 100 + index, uncached: 50 + index, cacheRead: 40, cacheWrite: 10 },
+  outputTokens: { total: 20, text: 15, reasoning: 5 }
+}), billingModel = Effect.gen(function* () {
+  const calls = yield* Ref.make(0);
+  return { model: yield* LanguageModel.make({
+    generateText: () => Ref.getAndUpdate(calls, (count) => count + 1).pipe(Effect.map((index) => [
+      { type: "text", text: `answer ${index}` },
+      { type: "finish", reason: "stop", usage: billedCall(index) }
+    ])),
+    streamText: () => Stream.die("the conformance model does not stream")
+  }), calls: Ref.get(calls) };
+}), billedTotal = (count) => Array.from({ length: count }, (_, index) => billedCall(index)).reduce((total, call) => addUsage(total, tokenUsage({
+  inputTokens: call.inputTokens.total,
+  outputTokens: call.outputTokens.total,
+  cacheReadTokens: call.inputTokens.cacheRead,
+  cacheWriteTokens: call.inputTokens.cacheWrite,
+  reasoningTokens: call.outputTokens.reasoning
+})), zeroUsage);
 export const turnConformance = (runner, services = Context.empty()) => {
   const check = (name, id, body) => ({
     name,
@@ -60,6 +83,44 @@ export const turnConformance = (runner, services = Context.empty()) => {
       const kinds = yield* names(session, "run-1");
       yield* expect("tasks-joined", kinds.includes("conformance.task") && kinds.indexOf("conformance.task") < kinds.indexOf("turn.reply"), `the task's event came ${kinds.includes("conformance.task") ? "after the reply" : "never"}`);
     })),
+    check("a model-driven turn returns its usage: what its stored step.usage records sum to", "usage", (turns, session) => Effect.gen(function* () {
+      const billing = yield* billingModel, runs = yield* Ref.make(zeroUsage), during = yield* Ref.make(zeroUsage), result = yield* turns.turn({ ...input(session, "run-1"), services: Context.make(LanguageModel.LanguageModel, billing.model) }, (turn) => Effect.gen(function* () {
+        const policy = {
+          limits: { streaming: !1, maxSteps: 2, requireCompletion: !1 },
+          completion: () => Effect.succeed({ complete: !0, awaiting: [], facts: {} })
+        }, first = yield* turn.run(policy), second = yield* turn.run(policy);
+        yield* Ref.set(runs, addUsage(first.usage, second.usage));
+        yield* Ref.set(during, yield* turn.usage);
+        return { outcome: "completed", reply: Option.some(second.text) };
+      }));
+      yield* expect("usage", sameUsage(yield* Ref.get(during), yield* Ref.get(runs)), `Turn.usage read ${JSON.stringify(yield* Ref.get(during))}, the turn's runs ${JSON.stringify(yield* Ref.get(runs))}`);
+      const all = yield* stored(session), number = Option.flatMap(Option.fromNullishOr(all.find((event) => event.kind === "turn.started" && event.data.runId === "run-1")), (event) => event.turn);
+      yield* expect("usage", Option.isSome(number), "the turn's turn.started was not stored");
+      const total = yield* turnUsageOf(all, Option.getOrElse(number, () => -1)).pipe(Effect.mapError((error) => new ConformanceFailure({ check: "usage", message: error.message })));
+      yield* expect("usage", sameUsage(result.usage, total), `the turn returned ${JSON.stringify(result.usage)}, its stored step.usage records sum to ${JSON.stringify(total)}`);
+      yield* expect("usage", sameUsage(result.usage, yield* Ref.get(runs)), `the turn returned ${JSON.stringify(result.usage)}, its runs ${JSON.stringify(yield* Ref.get(runs))}`);
+      const calls = yield* billing.calls;
+      yield* expect("usage", calls >= 2 && sameUsage(result.usage, billedTotal(calls)), `the turn's usage lost the provider's counts: ${JSON.stringify(result.usage)} for ${calls} model calls, which reported ${JSON.stringify(billedTotal(calls))}`);
+    })),
+    check("the user's attachments are stored with the turn and reach the first request as image parts", "attachments", (turns, session) => Effect.gen(function* () {
+      const image = yield* mediaFromBase64(pixelPng, { name: "pixel.png" }).pipe(Effect.mapError((error) => new ConformanceFailure({ check: "attachments", message: error.message }))), requests = yield* Ref.make([]), model = yield* LanguageModel.make({
+        generateText: (options) => Ref.update(requests, (all) => [...all, options.prompt]).pipe(Effect.as([
+          { type: "text", text: "a pixel" },
+          { type: "finish", reason: "stop", usage: billedCall(0) }
+        ])),
+        streamText: () => Stream.die("the conformance model does not stream")
+      }), userMessage = new UserMessage({ text: "what is this?", attachments: [image] });
+      yield* turns.turn({ turn: { session: session.address, userMessage, runId: "run-1" }, services: Context.make(LanguageModel.LanguageModel, model) }, (turn) => turn.run({
+        limits: { streaming: !1, maxSteps: 1, requireCompletion: !1 },
+        completion: () => Effect.succeed({ complete: !0, awaiting: [], facts: {} })
+      }).pipe(Effect.map((result) => ({ outcome: "completed", reply: Option.some(result.text) }))));
+      const first = (yield* Ref.get(requests))[0];
+      yield* expect("attachments", first !== void 0, "the turn made no request");
+      const files = (first?.content ?? []).flatMap((message) => message.role === "user" ? message.content.flatMap((part) => part.type === "file" ? [part] : []) : []);
+      yield* expect("attachments", files.some((part) => part.mediaType === image.mediaType && part.data === image.data), `the first request carried ${files.length} file parts, none of them the attached ${image.mediaType}`);
+      const started = (yield* stored(session)).find((event) => event.kind === "turn.started" && event.data.runId === "run-1");
+      yield* expect("attachments", JSON.stringify(started?.data.userMessage ?? null).includes(image.fingerprint), "the stored turn.started does not hold the attachment");
+    })),
     check("the host layer is built before the message: it sees only earlier turns", "layer-before-message", (turns, session) => Effect.gen(function* () {
       const seen = yield* Ref.make([]), layer = Layer.effectDiscard(Effect.gen(function* () {
         const run = yield* RunContext, own = (yield* run.memory.entries).filter((entry) => entry.runId === run.runId).length, turn = yield* run.memory.turn;

package/dist/turn/user-message.entity.d.ts

@@ -1,14 +1,24 @@
 import { Schema } from "effect";
 declare const UserMessage_base: Schema.Class<UserMessage, Schema.Struct<{
-    readonly text: Schema.NonEmptyString;
+    readonly text: Schema.String;
+    readonly attachments: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly type: Schema.Literal<"media">;
+        readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+        readonly data: Schema.String;
+        readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+        readonly bytes: Schema.Int;
+        readonly name: Schema.optionalKey<Schema.String>;
+        readonly alt: Schema.optionalKey<Schema.String>;
+    }>>>;
 }>, {}>;
 /**
  * What the user said to start a turn. A prompt is text sent to a model; the
  * user's message is a value of its own, and every field or parameter holding
- * it is named `userMessage`. Attachments may join `text` later.
+ * it is named `userMessage`. It has text, images (`attachments`, at most
+ * `MEDIA_LIMITS.attachments`), or both: the text may be empty only when
+ * there is an image. `Sessions.begin` checks each image's bytes and stores
+ * the message as `normalizeUserMessage` gives it.
  */
 export declare class UserMessage extends UserMessage_base {
 }
-/** A `UserMessage` stored as its plain text, for records that keep a string on the wire. */
-export declare const UserMessageFromString: Schema.decodeTo<typeof UserMessage, Schema.String, never, never>;
 export {};

package/dist/turn/user-message.entity.functions.d.ts

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import { AttachmentRejected } from "../domain/media.entity.js";
+import type { Media } from "../domain/media.entity.js";
+import { UserMessage } from "./user-message.entity.js";
+/** The message's images, in order (none for a text-only message). */
+export declare const attachmentsOf: (message: UserMessage) => ReadonlyArray<Media>;
+/**
+ * The message as one text, for transcripts, digests and ledgers: its text,
+ * then one `mediaLabel` line per image. A text-only message is its text.
+ */
+export declare const userMessageText: (message: UserMessage) => string;
+/** The same message: equal text and the same images (by fingerprint, type, size, name and alt), in order. */
+export declare const sameUserMessage: (left: UserMessage, right: UserMessage) => boolean;
+/**
+ * The message with each image checked again from its own bytes
+ * (`normalizeMedia`: type, size and fingerprint as the bytes give them), and
+ * the images together within `MEDIA_LIMITS.requestChars`. A text-only
+ * message is returned as it is. `Sessions.begin` stores what this returns,
+ * and compares a retried key against it.
+ */
+export declare const normalizeUserMessage: (message: UserMessage) => Effect.Effect<UserMessage, AttachmentRejected>;

package/dist/turn/user-message.entity.functions.js

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import { AttachmentRejected, MEDIA_LIMITS } from "../domain/media.entity.js";
+import { mediaLabel, normalizeMedia } from "../domain/media.entity.functions.js";
+import { UserMessage } from "./user-message.entity.js";
+export const attachmentsOf = (message) => message.attachments ?? [], userMessageText = (message) => [message.text, ...attachmentsOf(message).map(mediaLabel)].filter((line) => line.length > 0).join(`
+`);
+const sameMedia = (left, right) => left.fingerprint === right.fingerprint && left.mediaType === right.mediaType && left.bytes === right.bytes && left.name === right.name && left.alt === right.alt;
+export const sameUserMessage = (left, right) => {
+  const [a, b] = [attachmentsOf(left), attachmentsOf(right)];
+  return left.text === right.text && a.length === b.length && a.every((media, index) => {
+    const other = b[index];
+    return other !== void 0 && sameMedia(media, other);
+  });
+}, normalizeUserMessage = (message) => {
+  const attachments = attachmentsOf(message);
+  if (attachments.length === 0)
+    return Effect.succeed(message);
+  if (attachments.length > MEDIA_LIMITS.attachments)
+    return Effect.fail(new AttachmentRejected({ reason: "TooMany", message: `${attachments.length} attachments, more than ${MEDIA_LIMITS.attachments}` }));
+  return Effect.forEach(attachments, (media, index) => normalizeMedia(media).pipe(Effect.mapError((error) => new AttachmentRejected({ reason: error.reason, index, message: `attachment ${index}: ${error.message}` })))).pipe(Effect.flatMap((normalized) => {
+    const chars = normalized.reduce((sum, media) => sum + media.data.length, 0);
+    return chars > MEDIA_LIMITS.requestChars ? Effect.fail(new AttachmentRejected({ reason: "TooLargeTogether", message: `the attachments take ${chars} base64 characters together, more than ${MEDIA_LIMITS.requestChars}` })) : Effect.succeed(new UserMessage({ text: message.text, attachments: normalized }));
+  }));
+};

package/dist/turn/user-message.entity.js

@@ -1,10 +1,8 @@
-import { Schema, SchemaTransformation } from "effect";
+import { Schema } from "effect";
+import { MEDIA_LIMITS, Media } from "../domain/media.entity.js";
 
-export class UserMessage extends Schema.Class("UserMessage")({
-  text: Schema.NonEmptyString
-}) {
+export class UserMessage extends Schema.Class("UserMessage")(Schema.Struct({
+  text: Schema.String,
+  attachments: Schema.optionalKey(Schema.Array(Media).check(Schema.isMinLength(1), Schema.isMaxLength(MEDIA_LIMITS.attachments)))
+}).check(Schema.makeFilter((message) => message.text.length > 0 || message.attachments !== void 0 ? !0 : "a user message needs text or an attachment"))) {
 }
-export const UserMessageFromString = Schema.String.pipe(Schema.decodeTo(UserMessage, SchemaTransformation.transform({
-  decode: (text) => ({ text }),
-  encode: (userMessage) => userMessage.text
-})));

package/dist/turn/user-message.entity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/util/glob.d.ts

@@ -0,0 +1,30 @@
+import { Result } from "effect";
+/**
+ * Glob patterns over POSIX paths relative to a root, without a file system:
+ * `*` and `?` match within one path segment, `**` (a whole segment) matches
+ * any number of segments, `[abc]`, `[a-z]` and `[!a]` / `[^a]` match one
+ * character, `{a,b}` (nestable) is either alternative, and `\` makes the
+ * next character literal. A `[` with no closing `]` is literal, as is a
+ * `{...}` with no top-level comma. Leading `./` and empty segments are
+ * ignored. A segment matches a name starting with a dot only when `dot` is
+ * set or the pattern segment itself starts with a literal dot; `**` never
+ * crosses such names without `dot`. A pattern whose braces stand for more
+ * than 1024 patterns is refused, never cut short.
+ */
+export interface GlobMatcher {
+    /** Whether this relative path matches the pattern. */
+    readonly matches: (path: string) => boolean;
+    /** Whether the directory at this relative path can hold a match, so a walk should enter it. */
+    readonly descends: (dir: string) => boolean;
+}
+export interface GlobMatchOptions {
+    readonly dot?: boolean;
+}
+/**
+ * Compile a pattern once into a path matcher and the walk's descent test.
+ * Fails, with the reason, when the braces stand for more than 1024 patterns
+ * or a part does not compile.
+ */
+export declare const compileGlob: (pattern: string, options?: GlobMatchOptions) => Result.Result<GlobMatcher, string>;
+/** Whether a relative POSIX path matches the pattern (see `compileGlob`, and when it fails). */
+export declare const globMatcher: (pattern: string, options?: GlobMatchOptions) => Result.Result<(path: string) => boolean, string>;

package/dist/util/glob.js

@@ -0,0 +1,91 @@
+import { Option, Result } from "effect";
+const maxAlternatives = 1024, syntax = new Set(["^", "$", "\\", ".", "*", "+", "?", "(", ")", "[", "]", "{", "}", "|", "/"]), literal = (char) => syntax.has(char) ? `\\${char}` : char, classLiteral = (char) => char === "\\" || char === "]" || char === "[" || char === "^" ? `\\${char}` : char, escapedFlags = (chars) => chars.reduce((state, char) => ({ flags: [...state.flags, state.pending], pending: !state.pending && char === "\\" }), { flags: [], pending: !1 }).flags, firstBrace = (pattern) => {
+  const chars = Array.from(pattern), escaped = escapedFlags(chars), special = (index, char) => chars[index] === char && escaped[index] !== !0, scanFrom = (start) => {
+    const open = chars.findIndex((_, index) => index >= start && special(index, "{"));
+    if (open < 0)
+      return Option.none();
+    const scan = chars.reduce((state, _, index) => {
+      if (index <= open || Option.isSome(state.close))
+        return state;
+      if (special(index, "{"))
+        return { ...state, depth: state.depth + 1 };
+      if (special(index, ",") && state.depth === 0)
+        return { ...state, commas: [...state.commas, index] };
+      if (!special(index, "}"))
+        return state;
+      return state.depth > 0 ? { ...state, depth: state.depth - 1 } : { ...state, close: Option.some(index) };
+    }, { depth: 0, commas: [], close: Option.none() });
+    return Option.match(Option.filter(scan.close, () => scan.commas.length > 0), {
+      onNone: () => scanFrom(open + 1),
+      onSome: (close) => Option.some({ open, close, commas: scan.commas })
+    });
+  };
+  return scanFrom(0);
+}, expandBraces = (pattern) => Option.match(firstBrace(pattern), {
+  onNone: () => [pattern],
+  onSome: ({ open, close, commas }) => {
+    const chars = Array.from(pattern), bounds = [open, ...commas, close], before = chars.slice(0, open).join(""), after = chars.slice(close + 1).join("");
+    return bounds.slice(1).map((end, index) => chars.slice((bounds[index] ?? open) + 1, end).join("")).reduce((all, alternative) => all.length > maxAlternatives ? all : [...all, ...expandBraces(`${before}${alternative}${after}`)].slice(0, maxAlternatives + 1), []);
+  }
+}), codePoint = (member) => member?.char.codePointAt(0) ?? 0, classAt = (chars, open) => {
+  const negated = chars[open + 1] === "!" || chars[open + 1] === "^", first = open + 1 + (negated ? 1 : 0), close = chars.findIndex((char, index) => index > first && char === "]" && chars[index - 1] !== "\\");
+  if (close < 0)
+    return Option.none();
+  const members = chars.slice(first, close).reduce((state, char) => !state.escaping && char === "\\" ? { ...state, escaping: !0 } : { members: [...state.members, { char, escaped: state.escaping }], escaping: !1 }, { members: [], escaping: !1 }).members, isRange = (member, index) => !member.escaped && member.char === "-" && index > 0 && index < members.length - 1;
+  if (members.some((member, index) => isRange(member, index) && codePoint(members[index - 1]) > codePoint(members[index + 1])))
+    return Option.none();
+  const source = members.map((member, index) => isRange(member, index) ? "-" : member.char === "-" ? "\\-" : classLiteral(member.char)).join("");
+  return Option.some({ source: `[${negated ? "^" : ""}${source}]`, close });
+}, segmentPattern = (segment, dot) => {
+  const chars = Array.from(segment), body = chars.reduce((state, char, index) => {
+    if (index < state.next)
+      return state;
+    if (char === "\\")
+      return { source: state.source + literal(chars[index + 1] ?? "\\"), next: index + 2 };
+    if (char === "*")
+      return { source: state.source + "[^/]*", next: index + 1 };
+    if (char === "?")
+      return { source: state.source + "[^/]", next: index + 1 };
+    if (char === "[")
+      return Option.match(classAt(chars, index), {
+        onNone: () => ({ source: state.source + literal(char), next: index + 1 }),
+        onSome: (found) => ({ source: state.source + found.source, next: found.close + 1 })
+      });
+    return { source: state.source + literal(char), next: index + 1 };
+  }, { source: "", next: 0 }), explicitDot = chars[0] === "." || chars[0] === "\\" && chars[1] === ".";
+  return new RegExp(`^${dot || explicitDot ? "" : "(?!\\.)"}${body.source}$`, "u");
+}, segmentsOf = (path) => path.split("/").filter((segment) => segment.length > 0 && segment !== "."), compileOne = (pattern, dot) => segmentsOf(pattern).map((segment) => segment === "**" ? { _tag: "Globstar" } : { _tag: "Name", pattern: segmentPattern(segment, dot) }).filter((segment, index, all) => !(segment._tag === "Globstar" && all[index - 1]?._tag === "Globstar")), matchFrom = (pattern, at, names, from, dot) => {
+  const segment = pattern[at];
+  if (segment === void 0)
+    return from === names.length;
+  const name = names[from];
+  if (segment._tag === "Globstar")
+    return matchFrom(pattern, at + 1, names, from, dot) || name !== void 0 && (dot || !name.startsWith(".")) && matchFrom(pattern, at, names, from + 1, dot);
+  return name !== void 0 && segment.pattern.test(name) && matchFrom(pattern, at + 1, names, from + 1, dot);
+}, prefixFrom = (pattern, at, names, from, dot) => {
+  const segment = pattern[at];
+  if (segment === void 0)
+    return !1;
+  const name = names[from];
+  if (name === void 0)
+    return !0;
+  if (segment._tag === "Globstar")
+    return prefixFrom(pattern, at + 1, names, from, dot) || (dot || !name.startsWith(".")) && prefixFrom(pattern, at, names, from + 1, dot);
+  return segment.pattern.test(name) && prefixFrom(pattern, at + 1, names, from + 1, dot);
+};
+export const compileGlob = (pattern, options) => {
+  const dot = options?.dot ?? !1, expanded = expandBraces(pattern);
+  if (expanded.length > maxAlternatives)
+    return Result.fail(`its braces stand for more than ${maxAlternatives} patterns`);
+  const compiled = Result.try({ try: () => expanded.map((one) => compileOne(one, dot)), catch: (cause) => `it does not compile: ${String(cause)}` });
+  return Result.map(compiled, (all) => ({
+    matches: (path) => {
+      const names = segmentsOf(path);
+      return all.some((segments) => matchFrom(segments, 0, names, 0, dot));
+    },
+    descends: (dir) => {
+      const names = segmentsOf(dir);
+      return all.some((segments) => prefixFrom(segments, 0, names, 0, dot));
+    }
+  }));
+}, globMatcher = (pattern, options) => Result.map(compileGlob(pattern, options), (matcher) => matcher.matches);

package/dist/util/glob.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/workspace/bash.conformance.d.ts

@@ -0,0 +1,37 @@
+import { Effect } from "effect";
+import type { Context, Scope } from "effect";
+import type { ConformanceCheck } from "../conformance.entity.js";
+import type { Bash } from "../ports/bash.port.js";
+type BashShape = Context.Service.Shape<typeof Bash>;
+/** One check's Bash adapter and an empty directory its commands run in. */
+export interface BashFixture {
+    readonly bash: BashShape;
+    /** An absolute directory that exists and is empty. */
+    readonly root: string;
+}
+/**
+ * A Bash backend as the kit opens it, once per check, released with its
+ * scope. The adapter's parent environment must be the process's own plus
+ * `planted`, so the kit can check what a command inherits (a Node adapter
+ * reads `{ ...process.env, ...planted }` where it would read
+ * `process.env`). The shell itself is found the way the adapter always
+ * finds it, not through the command's environment.
+ */
+export interface BashSubject {
+    readonly open: (planted: Readonly<Record<string, string>>) => Effect.Effect<BashFixture, unknown, Scope.Scope>;
+}
+/**
+ * The Bash contract as checks, each with a fresh fixture: a non-zero exit
+ * is a result; stdout and stderr stay apart and arrive as chunks while the
+ * command still runs, with exactly one `BashExit`, last; `stdin` (text or
+ * bytes) is delivered, its end is seen, and a command that ignores a large
+ * one still exits; `env` is set over the parent environment, which is filtered by
+ * `inheritEnv` (the default allowlist keeps `PATH` and `LC_*` but not a
+ * planted secret); a timeout kills the whole process group, a background
+ * child included, and reports `timeout`; `cwd` is honoured and a missing one
+ * fails with `CwdMissing`; a signal is reported; UTF-8 split across writes
+ * arrives whole; interrupting the stream kills the command and what it
+ * started. Each must finish within 30 seconds.
+ */
+export declare const bashConformance: (subject: BashSubject) => ReadonlyArray<ConformanceCheck>;
+export {};

package/dist/workspace/bash.conformance.js

@@ -0,0 +1,120 @@
+import { Deferred, Effect, Fiber, Option, Ref, Stream } from "effect";
+import { check, expect, fail } from "../conformance.functions.js";
+const show = (value) => JSON.stringify(value), quoted = (word) => `'${word.replaceAll("'", "'\\''")}'`, textOf = (events, stream) => events.flatMap((event) => event._tag === "BashChunk" && event.stream === stream ? [event.text] : []).join(""), ended = (result) => show({
+  termination: result.termination,
+  exitCode: Option.getOrNull(result.exitCode),
+  signal: Option.getOrNull(result.signal),
+  stdout: result.stdout,
+  stderr: result.stderr
+}), statusOf = (pidFiles) => pidFiles.map((file) => `pid=$(cat ${quoted(file)} 2>/dev/null) || { echo missing; exit 0; }; if kill -0 "$pid" 2>/dev/null; then case "$(ps -o stat= -p "$pid" 2>/dev/null)" in Z*) echo gone ;; *) echo alive ;; esac; else echo gone; fi`).join("; "), planted = { EFFERENT_KIT_SECRET: "planted-secret", LC_EFFERENT_KIT: "planted-locale", EFFERENT_KIT_OVER: "from the parent" };
+export const bashConformance = (subject) => {
+  const bashCheck = (name, id, body, plant = {}) => check(name, id, () => Effect.timeoutOrElse(Effect.scoped(subject.open(plant).pipe(Effect.flatMap(body))), {
+    duration: "30 seconds",
+    orElse: () => fail(id, "the check did not finish in 30 seconds")
+  })), run = (fixture, command, options = {}) => fixture.bash.exec(command, { ...options, cwd: fixture.root }), allGone = (fixture, pidFiles, polls = 50) => run(fixture, statusOf(pidFiles)).pipe(Effect.flatMap((result) => {
+    const statuses = result.stdout.trim();
+    return statuses.split(`
+`).every((status) => status === "gone") || polls === 0 ? Effect.succeed(statuses) : Effect.sleep("100 millis").pipe(Effect.andThen(allGone(fixture, pidFiles, polls - 1)));
+  })), runUntil = (fixture, command, marker) => Effect.gen(function* () {
+    const events = yield* Ref.make([]), seen = yield* Deferred.make(), fiber = yield* Effect.forkScoped(Stream.runForEach(fixture.bash.stream(command, { cwd: fixture.root }), (event) => Ref.updateAndGet(events, (all) => [...all, event]).pipe(Effect.flatMap((all) => textOf(all, "stdout").includes(marker) ? Deferred.succeed(seen, !0) : Effect.void))).pipe(Effect.ensuring(Deferred.succeed(seen, !1)))), arrived = Option.getOrElse(yield* Deferred.await(seen).pipe(Effect.timeoutOption("10 seconds")), () => !1);
+    return { events, fiber, arrived };
+  });
+  return [
+    bashCheck("a non-zero exit is a result with its code, not an error", "exit-code", (fixture) => Effect.gen(function* () {
+      const failed = yield* run(fixture, "echo bad >&2; exit 3");
+      yield* expect("exit-code", failed.termination === "exit" && Option.getOrNull(failed.exitCode) === 3 && Option.isNone(failed.signal) && failed.stderr === `bad
+`, `a command exiting 3 ended ${ended(failed)}`);
+      const succeeded = yield* run(fixture, "true");
+      yield* expect("exit-code", succeeded.termination === "exit" && Option.getOrNull(succeeded.exitCode) === 0, `true ended ${ended(succeeded)}`);
+    })),
+    bashCheck("stdout and stderr stay apart, chunks carry their stream, and exactly one BashExit comes last", "streams", (fixture) => Effect.gen(function* () {
+      const result = yield* run(fixture, "printf out1; printf err1 >&2; printf out2; printf err2 >&2");
+      yield* expect("streams", result.stdout === "out1out2" && result.stderr === "err1err2", `the command ended ${ended(result)}`);
+      const events = yield* Stream.runCollect(fixture.bash.stream("printf 'one\\n'; printf 'two\\n' >&2; exit 4", { cwd: fixture.root })).pipe(Effect.map((all) => [...all])), exits = events.filter((event) => event._tag === "BashExit"), last = events.at(-1);
+      yield* expect("streams", textOf(events, "stdout") === `one
+` && textOf(events, "stderr") === `two
+`, `the stream's chunks gave stdout ${show(textOf(events, "stdout"))} and stderr ${show(textOf(events, "stderr"))}`);
+      yield* expect("streams", exits.length === 1 && last?._tag === "BashExit" && Option.getOrNull(last.exitCode) === 4, `the stream had ${exits.length} BashExit events and ended with ${show(last?._tag)}`);
+    })),
+    bashCheck("output arrives while the command still runs, before its exit", "streaming", (fixture) => Effect.gen(function* () {
+      yield* Effect.addFinalizer(() => run(fixture, "touch go").pipe(Effect.ignore));
+      const started = yield* runUntil(fixture, "printf first; while [ ! -e go ]; do sleep 0.05; done; printf second", "first");
+      if (!started.arrived)
+        return yield* fail("streaming", "the first output did not arrive while the command ran (is output held until exit?)");
+      yield* run(fixture, "touch go");
+      const joined = yield* Fiber.join(started.fiber).pipe(Effect.timeoutOption("10 seconds"));
+      if (Option.isNone(joined))
+        return yield* fail("streaming", "the command did not end after it was let go");
+      const events = yield* Ref.get(started.events), last = events.at(-1);
+      yield* expect("streaming", textOf(events, "stdout") === "firstsecond" && last?._tag === "BashExit" && Option.getOrNull(last.exitCode) === 0 && events.filter((event) => event._tag === "BashExit").length === 1, `the stream gave ${show(textOf(events, "stdout"))}, ending with ${show(last)}`);
+    })),
+    bashCheck("stdin, text or bytes, is delivered and then closed; without stdin the command reads end-of-file at once", "stdin", (fixture) => Effect.gen(function* () {
+      const input = `line one
+l\xEFne two \u2713
+no newline at the end`, echoed = yield* run(fixture, "cat", { stdin: input });
+      yield* expect("stdin", echoed.stdout === input && Option.getOrNull(echoed.exitCode) === 0, `cat of stdin ended ${ended(echoed)}`);
+      const counted = yield* run(fixture, "wc -c", { stdin: Uint8Array.from([0, 255, 10, 128, 7]) });
+      yield* expect("stdin", counted.stdout.trim() === "5" && Option.getOrNull(counted.exitCode) === 0, `wc -c of five bytes of stdin ended ${ended(counted)}`);
+      const empty = yield* run(fixture, "cat; printf done").pipe(Effect.timeoutOption("10 seconds"));
+      yield* Option.match(empty, {
+        onNone: () => fail("stdin", "cat without stdin did not end in 10 seconds: its input was left open"),
+        onSome: (result) => expect("stdin", result.stdout === "done", `cat without stdin ended ${ended(result)}`)
+      });
+    })),
+    bashCheck("a command that ignores a large stdin and exits still yields its exit", "stdin-ignored", (fixture) => Effect.gen(function* () {
+      const result = yield* run(fixture, "printf ignored", { stdin: "x".repeat(1e6) });
+      yield* expect("stdin-ignored", result.termination === "exit" && Option.getOrNull(result.exitCode) === 0 && result.stdout === "ignored", `the command ended ${ended(result)}`);
+    })),
+    bashCheck("env is set over the parent environment", "env", (fixture) => Effect.gen(function* () {
+      const result = yield* run(fixture, `printf '%s|%s' "$EFFERENT_KIT_VALUE" "$EFFERENT_KIT_OVER"`, {
+        env: { EFFERENT_KIT_VALUE: "v\xE4lue with spaces", EFFERENT_KIT_OVER: "from env" },
+        inheritEnv: !0
+      });
+      yield* expect("env", result.stdout === "v\xE4lue with spaces|from env", `the command saw ${show(result.stdout)}`);
+    }), planted),
+    bashCheck("by default the parent environment passes through an allowlist: PATH and LC_* but not a planted secret; inheritEnv widens or empties it", "inherit-env", (fixture) => Effect.gen(function* () {
+      const probe = 'printf \'%s|%s|%s\' "${EFFERENT_KIT_SECRET-unset}" "${LC_EFFERENT_KIT-unset}" "${PATH:+path}"', settings = [Option.none(), Option.some(!0), Option.some(!1), Option.some(["EFFERENT_KIT_*"])], seen = yield* Effect.forEach(settings, (inheritEnv) => run(fixture, probe, Option.match(inheritEnv, { onNone: () => ({}), onSome: (value) => ({ inheritEnv: value }) })).pipe(Effect.map((result) => result.stdout))), expected = [
+        "unset|planted-locale|path",
+        "planted-secret|planted-locale|path",
+        "unset|unset|",
+        "planted-secret|unset|"
+      ], [byDefault, all, none, listed] = seen;
+      yield* expect("inherit-env", byDefault === expected[0] && all === expected[1], `by default the command saw ${show(byDefault)} and with inheritEnv true ${show(all)}; expected ${show(expected.slice(0, 2))}`);
+      yield* expect("inherit-env", none?.startsWith("unset|unset|") === !0 && listed?.startsWith("planted-secret|unset|") === !0, `with inheritEnv false the command saw ${show(none)}, with an allowlist of EFFERENT_KIT_* ${show(listed)}`);
+    }), planted),
+    bashCheck("a timeout kills the whole process group, a background child too, and reports termination timeout", "timeout", (fixture) => Effect.gen(function* () {
+      const result = yield* run(fixture, "sleep 30 & echo $! > child.pid; printf started; wait", { timeoutMs: 1000 });
+      yield* expect("timeout", result.termination === "timeout" && Option.isNone(result.exitCode) && result.stdout === "started" && result.durationMs < 1e4, `a command past its 1 s timeout ended ${ended(result)} after ${result.durationMs} ms`);
+      const status = yield* allGone(fixture, ["child.pid"]);
+      yield* expect("timeout", status === "gone", `the background child of the timed-out command is ${status}`);
+    })),
+    bashCheck("the command runs in cwd, and a missing cwd or one that is a file fails with CwdMissing", "cwd", (fixture) => Effect.gen(function* () {
+      yield* run(fixture, "printf here > marker.txt; printf x > afile");
+      const marker = yield* fixture.bash.exec(`cat ${quoted(`${fixture.root}/marker.txt`)}`, { cwd: "/" });
+      yield* expect("cwd", marker.stdout === "here", `a file written in cwd reads ${show(marker.stdout)} from its absolute path`);
+      const missing = yield* Effect.flip(fixture.bash.exec("true", { cwd: `${fixture.root}/missing` })), file = yield* Effect.flip(fixture.bash.exec("true", { cwd: `${fixture.root}/afile` }));
+      yield* expect("cwd", missing._tag === "BashError" && missing.reason === "CwdMissing" && file._tag === "BashError" && file.reason === "CwdMissing", `a missing cwd failed with ${show(missing)}, a file as cwd with ${show(file)}`);
+    })),
+    bashCheck("a command killed by a signal reports termination signal and the signal's name", "signal", (fixture) => Effect.gen(function* () {
+      const result = yield* run(fixture, "kill -TERM $$");
+      yield* expect("signal", result.termination === "signal" && Option.getOrNull(result.signal) === "SIGTERM" && Option.isNone(result.exitCode), `kill -TERM $$ ended ${ended(result)}`);
+    })),
+    bashCheck("UTF-8 written in two pieces arrives as whole characters", "utf8", (fixture) => Effect.gen(function* () {
+      const result = yield* run(fixture, "printf '\\303'; sleep 0.2; printf '\\251\\n'; printf '\\342\\234' >&2; sleep 0.2; printf '\\223' >&2");
+      yield* expect("utf8", result.stdout === `\xE9
+` && result.stderr === "\u2713", `a split \xE9 and \u2713 arrived as ${show(result.stdout)} and ${show(result.stderr)}`);
+    })),
+    bashCheck("interrupting the stream kills the command and what it started, and returns", "interrupt", (fixture) => Effect.gen(function* () {
+      const started = yield* runUntil(fixture, "sleep 30 & echo $! > child.pid; echo $$ > shell.pid; printf started; wait", "started");
+      if (!started.arrived)
+        return yield* fail("interrupt", "the command's output did not arrive");
+      const interrupted = yield* Fiber.interrupt(started.fiber).pipe(Effect.timeoutOption("10 seconds"));
+      if (Option.isNone(interrupted))
+        return yield* fail("interrupt", "interrupting the stream did not return in 10 seconds");
+      const status = yield* allGone(fixture, ["shell.pid", "child.pid"]);
+      yield* expect("interrupt", status === `gone
+gone`, `after the interrupt the shell and its child are ${show(status.split(`
+`))}`);
+    }))
+  ];
+};

package/dist/workspace/bash.conformance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/workspace/file-system.conformance.d.ts

@@ -0,0 +1,38 @@
+import { Effect } from "effect";
+import type { Context, Scope } from "effect";
+import type { ConformanceCheck } from "../conformance.entity.js";
+import type { FileSystem } from "../ports/file-system.port.js";
+type Fs = Context.Service.Shape<typeof FileSystem>;
+/** One check's file system: the port, an empty directory to work in, and a way to make links. */
+export interface FileSystemFixture {
+    readonly fs: Fs;
+    /** An absolute directory that exists and is empty; the check works only below it. */
+    readonly root: string;
+    /** Make a symbolic link at `path` to `target`, as `ln -s target path` does (the port has no call for it). */
+    readonly symlink: (target: string, path: string) => Effect.Effect<void, unknown>;
+}
+/**
+ * A FileSystem backend as the kit opens it: each run of `open` gives one
+ * check its fixture, a fresh empty `root` released (and removed) with its
+ * scope: a temporary directory on disk, a new tree in memory.
+ */
+export interface FileSystemSubject {
+    readonly open: Effect.Effect<FileSystemFixture, unknown, Scope.Scope>;
+}
+/**
+ * The FileSystem contract as checks, run against a fresh fixture each:
+ * text and bytes round trips (UTF-8 included); `createParents`;
+ * `readBytes` ranges; `append`; `rename` (over an existing file, of a
+ * directory with what it holds, of a link and not its target, and which
+ * side a failure names); `stat` kinds, sizes and links; `exists`;
+ * `list` sorted by name with each entry's kind; `glob` with `*`, `**`, `?`,
+ * classes, braces, `exclude`, dot entries, `onlyFiles`, `limit` and a
+ * linked directory it must not enter; `mkdir` with and without `recursive`;
+ * `realPath` through links; the `remove` rules, and the path `remove` acts
+ * on (a trailing slash, a linked parent, a last `.` or `..`); and the
+ * `reason` and `path` of every failure. Each must finish within 30 seconds;
+ * none acts outside the fixture's root, even on a backend that gets the
+ * path wrong.
+ */
+export declare const fileSystemConformance: (subject: FileSystemSubject) => ReadonlyArray<ConformanceCheck>;
+export {};