@sshkeda/task 0.0.0-stage → 1.0.0

package/src/lib/task/internal/make-tasks.ts

@@ -0,0 +1,82 @@
+import { Effect, Effectable } from "effect";
+import type { FileSystem, Path, Scope, Stdio, Terminal } from "effect";
+import type { Digest, SecureRandom } from "effect/crypto";
+import type { HttpClient } from "effect/http";
+import type { ChildProcessSpawner } from "effect/process";
+
+import { recordTaskMade } from "../../../shared/record-tasks-made.ts";
+import { resolveTaskOptions } from "../../../shared/resolve-task-options.ts";
+import type { TaskRequestFailure } from "../../../shared/task-errors.ts";
+import { TASK_PACKAGE } from "../../../shared/task-package.ts";
+import type { TaskResult } from "../../../shared/task-results.ts";
+import { Tasks } from "../../../shared/task-services.ts";
+import type { Served, Serving } from "../../../shared/task-services.ts";
+import { trustTaskResult } from "./trust-task-results.ts";
+
+const TYPE_ID = Symbol.for(`~${TASK_PACKAGE.name}/Task`);
+
+export class Task<
+  Success = unknown,
+  Services extends Effect.Services<Task["body"]> =
+    | ChildProcessSpawner.ChildProcessSpawner
+    | Digest.Digest
+    | FileSystem.FileSystem
+    | HttpClient.HttpClient
+    | Path.Path
+    | Scope.Scope
+    | SecureRandom.SecureRandom
+    | Serving
+    | Stdio.Stdio
+    | Tasks
+    | Terminal.Terminal,
+> extends Effectable.Class<Success, typeof TaskRequestFailure.Type, Tasks> {
+  public readonly [TYPE_ID] = TYPE_ID;
+
+  public readonly name: string;
+
+  public readonly body: Effect.Effect<unknown, { readonly _tag: string }, Services>;
+
+  public readonly options: ReturnType<typeof resolveTaskOptions>;
+
+  public constructor(
+    name: string,
+    body: Effect.Effect<unknown, { readonly _tag: string }, Services>,
+    options: ReturnType<typeof resolveTaskOptions>,
+  ) {
+    super();
+    this.name = name;
+    this.body = body;
+    this.options = options;
+    recordTaskMade(this);
+  }
+
+  public asEffect() {
+    return Tasks.use((tasks) => tasks.requestResult(this)).pipe(
+      Effect.flatMap((taskResult) => trustTaskResult<Success>(taskResult)),
+    );
+  }
+}
+
+export const make = <
+  BodySuccess,
+  Failure extends { readonly _tag: string },
+  Services extends Effect.Services<Task["body"]>,
+>(
+  name: string,
+  body: Effect.Effect<BodySuccess, Failure, Services> &
+    NoInfer<
+      Effect.Effect<
+        [Serving extends Services ? Extract<BodySuccess, Served<unknown>> : true] extends [never]
+          ? "serves one value and returns another"
+          : BodySuccess extends Served<infer Success>
+            ? Served<Success extends void ? Success : typeof TaskResult.Type>
+            : BodySuccess extends void
+              ? BodySuccess
+              : typeof TaskResult.Type,
+        Failure,
+        Services
+      >
+    >,
+  options: Parameters<typeof resolveTaskOptions>[0] = {},
+): Task<BodySuccess extends Served<infer Success> ? Success : BodySuccess, Services> =>
+  new Task(name, body, resolveTaskOptions(options));

package/src/lib/task/internal/run-command.ts

@@ -0,0 +1,194 @@
+import { Cause, Deferred, Effect, Exit, Fiber, Redacted, Scope, Stream } from "effect";
+import type { PlatformError } from "effect/PlatformError";
+import * as PlatformErrors from "effect/PlatformError";
+import { ChildProcess } from "effect/process";
+
+import { environmentEveryCommandSees } from "../../../shared/read-environment-config.ts";
+import { CauseWithoutFailure } from "../../../shared/report-errors.ts";
+import { failureValuesOfCause } from "../../../shared/select-cause-reasons.ts";
+import {
+  isStandardInputClosedByCommand,
+  makeStandardInputRunner,
+} from "../../../shared/standard-input-streams.ts";
+import { Tasks } from "../../../shared/task-services.ts";
+import {
+  CapturedCommandFailed,
+  CommandFailed,
+  CommandNotStarted,
+  CommandStandardInputFailed,
+} from "../../errors/index.ts";
+import { trustOutputModeName } from "./trust-output-mode-names.ts";
+
+const logAndCapture = (output: Stream.Stream<Uint8Array, PlatformError>) =>
+  Effect.suspend(() => {
+    const texts: string[] = [];
+    return Stream.decodeText(output).pipe(
+      Stream.tap((text) =>
+        Effect.sync(() => {
+          texts.push(text);
+        }),
+      ),
+      Stream.splitLines,
+      Stream.runForEachArray((lines) => Effect.log(lines.join("\n"))),
+      Effect.map(() => texts.join("")),
+    );
+  });
+
+const OUTPUT_MODES = {
+  logged: {
+    readOutput: logAndCapture,
+    returnOutput: (standardOutput: string) => standardOutput,
+    makeFailure: (failure: ConstructorParameters<typeof CommandFailed>[0]) =>
+      new CommandFailed(failure),
+  },
+  secret: {
+    readOutput: (output: Stream.Stream<Uint8Array, PlatformError>) =>
+      Stream.mkString(Stream.decodeText(output)),
+    returnOutput: (standardOutput: string) => Redacted.make(standardOutput),
+    makeFailure: (failure: ConstructorParameters<typeof CommandFailed>[0]) =>
+      new CapturedCommandFailed({
+        command: failure.command,
+        code: failure.code,
+        standardOutput: Redacted.make(failure.standardOutput),
+        standardError: Redacted.make(failure.standardError),
+      }),
+  },
+};
+
+const outputModes: {
+  readonly [Output in keyof typeof OUTPUT_MODES]: {
+    readonly readOutput: (typeof OUTPUT_MODES)["logged"]["readOutput"];
+    readonly returnOutput: (
+      standardOutput: string,
+    ) => ReturnType<(typeof OUTPUT_MODES)[Output]["returnOutput"]>;
+    readonly makeFailure: (
+      failure: ConstructorParameters<typeof CommandFailed>[0],
+    ) => ReturnType<(typeof OUTPUT_MODES)[Output]["makeFailure"]>;
+  };
+} = OUTPUT_MODES;
+
+export const exec = <Secret extends boolean = false>(
+  name: string,
+  commandArguments: readonly string[],
+  ...[commandOptions = {}]: [Secret] extends [true]
+    ? [
+        commandOptions: {
+          readonly cwd?: string;
+          readonly env?: Readonly<Record<string, Redacted.Redacted | string>>;
+          readonly stdin?: Stream.Stream<Uint8Array, PlatformError>;
+          readonly secret: Secret;
+        },
+      ]
+    : [
+        commandOptions?: {
+          readonly cwd?: string;
+          readonly env?: Readonly<Record<string, Redacted.Redacted | string>>;
+          readonly stdin?: Stream.Stream<Uint8Array, PlatformError>;
+          readonly secret?: Secret;
+        },
+      ]
+) =>
+  Tasks.use(() =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const outputMode = outputModes[yield* trustOutputModeName(commandOptions.secret)];
+        const command = name.slice(name.lastIndexOf("/") + 1);
+        const outputScope = yield* Scope.fork(yield* Effect.scope);
+        const commandReleased = yield* Deferred.make<void>();
+        const child = yield* ChildProcess.make(name, commandArguments, {
+          ...(commandOptions.cwd === undefined ? {} : { cwd: commandOptions.cwd }),
+          env: { ...(yield* environmentEveryCommandSees), ...commandOptions.env },
+          stdin: commandOptions.stdin === undefined ? "ignore" : "pipe",
+          stderr: "pipe",
+        }).pipe(Effect.mapError((failure) => new CommandNotStarted({ command, cause: failure })));
+        const standardInput = makeStandardInputRunner();
+        const standardInputFiber = yield* Effect.forkScoped(
+          commandOptions.stdin === undefined
+            ? Effect.void
+            : standardInput.run(Stream.run(commandOptions.stdin, child.stdin)),
+        );
+        const readUntilCommandReleased = (output: Stream.Stream<Uint8Array, PlatformError>) =>
+          outputMode.readOutput(output.pipe(Stream.interruptWhen(Deferred.await(commandReleased))));
+        const outputFiber = yield* Effect.forkIn(
+          Effect.all(
+            [readUntilCommandReleased(child.stdout), readUntilCommandReleased(child.stderr)],
+            { concurrency: "unbounded" },
+          ),
+          outputScope,
+        );
+        yield* Scope.addFinalizer(
+          outputScope,
+          Deferred.done(commandReleased, Exit.void).pipe(Effect.andThen(Fiber.await(outputFiber))),
+        );
+        const describeStandardInputFailures = (standardInputExit: Exit.Exit<unknown, unknown>) => {
+          if (Exit.isSuccess(standardInputExit)) {
+            return [];
+          }
+          if (Cause.hasInterruptsOnly(standardInputExit.cause)) {
+            return standardInput.interruptedItself()
+              ? [new CauseWithoutFailure({ details: Cause.pretty(standardInputExit.cause) })]
+              : [];
+          }
+          return failureValuesOfCause(standardInputExit.cause).filter(
+            (failureValue) =>
+              !(
+                PlatformErrors.isPlatformError(failureValue) &&
+                isStandardInputClosedByCommand(failureValue)
+              ),
+          );
+        };
+        const exitBeforeStandardInputFailed = yield* Effect.raceFirst(
+          Effect.raceFirst(
+            Effect.exit(child.exitCode),
+            Fiber.await(standardInputFiber).pipe(
+              Effect.flatMap((standardInputExit) =>
+                describeStandardInputFailures(standardInputExit).length > 0
+                  ? Effect.succeed(null)
+                  : Effect.never,
+              ),
+            ),
+          ),
+          Fiber.join(outputFiber).pipe(Effect.andThen(Effect.never)),
+        );
+        const exitCodeExit =
+          exitBeforeStandardInputFailed ??
+          (yield* child.kill().pipe(Effect.andThen(Effect.exit(child.exitCode))));
+        yield* Fiber.interrupt(standardInputFiber);
+        const standardInputFailures = Cause.fromReasons(
+          describeStandardInputFailures(yield* Fiber.await(standardInputFiber)).map(
+            (failureValue) =>
+              Cause.makeFailReason(
+                new CommandStandardInputFailed({ command, cause: failureValue }),
+              ),
+          ),
+        );
+        const standardInputFailed = standardInputFailures.reasons.length > 0;
+        if (Exit.isFailure(exitCodeExit)) {
+          return yield* standardInputFailed
+            ? Effect.failCause(standardInputFailures)
+            : Effect.failCause(exitCodeExit.cause);
+        }
+        if (exitCodeExit.value === 0) {
+          if (standardInputFailed) {
+            return yield* Effect.failCause(standardInputFailures);
+          }
+          const [standardOutput] = yield* Fiber.join(outputFiber);
+          return outputMode.returnOutput(standardOutput);
+        }
+        const [standardOutput, standardError] = yield* Fiber.join(outputFiber);
+        return yield* Effect.failCause(
+          Cause.combine(
+            Cause.fail(
+              outputMode.makeFailure({
+                command,
+                code: exitCodeExit.value,
+                standardOutput,
+                standardError,
+              }),
+            ),
+            standardInputFailures,
+          ),
+        );
+      }),
+    ),
+  );

package/src/lib/task/internal/run-root-task.ts

@@ -0,0 +1,263 @@
+import { isatty } from "node:tty";
+
+import * as BunCrypto from "@effect/platform-bun/BunCrypto";
+import * as BunServices from "@effect/platform-bun/BunServices";
+import {
+  Deferred,
+  Duration,
+  Effect,
+  Exit,
+  Fiber,
+  flow,
+  Layer,
+  LogLevel,
+  Option,
+  Queue,
+  Runtime,
+  Schema,
+  Stdio,
+  Stream,
+} from "effect";
+import type { Cause } from "effect";
+import type { PlatformError } from "effect/PlatformError";
+
+import { readStackAbove } from "../../../shared/find-user-locations-in-stack-traces.ts";
+import { formatFailureLines } from "../../../shared/format-error-lines.ts";
+import {
+  isImportingTaskModule,
+  isInsideTaskBody,
+  isInsideTaskWorkerThread,
+} from "../../../shared/mark-task-worker-thread-contexts.ts";
+import {
+  printLine,
+  StandardErrorWriteFailed,
+  standardErrorClosedDeferred,
+  standardErrorLinesDeferred,
+  standardErrorWriteFailedDeferred,
+} from "../../../shared/print-to-standard-error.ts";
+import { bunWatchModeFlag } from "../../../shared/read-environment-config.ts";
+import type { StandardErrorLine } from "../../../shared/rpc.ts";
+import { saveStandardStreamFlags } from "../../../shared/save-standard-stream-flags.ts";
+import {
+  laterRunCallDeferred,
+  runningRootTaskDeferred,
+} from "../../../shared/signal-run-called-twice.ts";
+import {
+  exitCodeAfterStopSignal,
+  listenToSignals,
+  STOP_SIGNALS,
+} from "../../../shared/stop-signals.ts";
+import {
+  Exited,
+  RunCalledDuringImport,
+  RunCalledInBunWatchMode,
+  RunCalledInStandaloneExecutable,
+  RunCalledInTaskBody,
+} from "../../../shared/task-errors.ts";
+import type { Task } from "./make-tasks.ts";
+
+const STANDARD_ERROR_FILE_DESCRIPTOR = 2;
+
+const READER_WAIT_AFTER_A_STOP_SIGNAL = Duration.seconds(1);
+
+class StandardErrorNotRead extends Schema.TaggedError<StandardErrorNotRead>()(
+  "StandardErrorNotRead",
+  { waitedMilliseconds: Schema.Finite },
+) {
+  public override get message() {
+    return `nobody read the last lines on standard error within ${this.waitedMilliseconds}ms after a stop signal, so task exited without them`;
+  }
+
+  public override get [Runtime.errorReported]() {
+    return false;
+  }
+}
+
+const findErrnoCode = flow(
+  Schema.decodeUnknownOption(Schema.Struct({ cause: Schema.Struct({ code: Schema.String }) })),
+  Option.map((reason) => reason.cause.code),
+  Option.getOrNull,
+);
+
+const readerHasGone = (errnoCode: string | null) =>
+  errnoCode === "EPIPE" || (errnoCode === "EIO" && isatty(STANDARD_ERROR_FILE_DESCRIPTOR));
+
+const recordWriteFailure = (failure: PlatformError) =>
+  Effect.sync(() => {
+    const errnoCode = findErrnoCode(failure.reason);
+    if (readerHasGone(errnoCode)) {
+      return Deferred.doneUnsafe(standardErrorClosedDeferred, Exit.void);
+    }
+    return Deferred.doneUnsafe(
+      standardErrorWriteFailedDeferred,
+      Exit.succeed(new StandardErrorWriteFailed({ errnoCode, reason: failure.message })),
+    );
+  });
+
+const writeLines = (
+  stdio: Stdio.Stdio,
+  lines: Queue.Queue<typeof StandardErrorLine.Type, Cause.Done>,
+  minimumLogLevel: LogLevel.LogLevel,
+) =>
+  Stream.fromQueue(lines).pipe(
+    Stream.filter((line) => LogLevel.isGreaterThanOrEqualTo(line.logLevel, minimumLogLevel)),
+    Stream.map((line) => line.text),
+    Stream.run(stdio.stderr()),
+    Effect.catchTag("PlatformError", (error) =>
+      recordWriteFailure(error).pipe(Effect.andThen(Queue.end(lines))),
+    ),
+    Effect.asVoid,
+  );
+
+const exitCodeAfterWriting = <Ended extends NodeJS.Signals | number>(ended: Ended) =>
+  Effect.gen(function* () {
+    if (Deferred.isDoneUnsafe(standardErrorWriteFailedDeferred)) {
+      return yield* yield* Deferred.await(standardErrorWriteFailedDeferred);
+    }
+    const readerLeftAfterTheRun = ended === 0 && Deferred.isDoneUnsafe(standardErrorClosedDeferred);
+    return readerLeftAfterTheRun ? exitCodeAfterStopSignal("SIGPIPE") : ended;
+  });
+
+const printLinesDuring = <Ended extends NodeJS.Signals | number, Failure, Services>(
+  program: Effect.Effect<Ended, Failure, Services>,
+  minimumLogLevel: LogLevel.LogLevel,
+) =>
+  Effect.gen(function* () {
+    const stdio = yield* Stdio.Stdio;
+    const stopSignals = yield* listenToSignals(STOP_SIGNALS);
+    const lines = yield* Queue.unbounded<typeof StandardErrorLine.Type, Cause.Done>();
+    yield* Deferred.succeed(standardErrorLinesDeferred, lines);
+    const writer = yield* writeLines(stdio, lines, minimumLogLevel).pipe(
+      Effect.interruptible,
+      Effect.forkScoped,
+    );
+    const ended = yield* program;
+    yield* Queue.end(lines);
+    const linesWritten = Fiber.join(writer);
+    yield* Effect.raceFirst(
+      linesWritten,
+      Queue.take(stopSignals).pipe(
+        Effect.andThen(
+          linesWritten.pipe(
+            Effect.timeoutOrElse({
+              duration: READER_WAIT_AFTER_A_STOP_SIGNAL,
+              orElse: () =>
+                Effect.fail(
+                  new StandardErrorNotRead({
+                    waitedMilliseconds: Duration.toMillis(READER_WAIT_AFTER_A_STOP_SIGNAL),
+                  }),
+                ),
+            }),
+          ),
+        ),
+      ),
+    );
+    return yield* exitCodeAfterWriting(ended);
+  }).pipe(Effect.scoped);
+
+const restoreStandardStreamFlagsAfter = <Ended, Failure, Services>(
+  program: Effect.Effect<Ended, Failure, Services>,
+) =>
+  Effect.gen(function* () {
+    const restoreStandardStreamFlags = yield* saveStandardStreamFlags;
+    return yield* program.pipe(Effect.tap(() => restoreStandardStreamFlags));
+  }).pipe(Effect.scoped);
+
+const MINIMUM_LOG_LEVEL_OF_LOG_OPTION = {
+  info: "Info",
+  error: "Error",
+} as const satisfies Record<string, LogLevel.LogLevel>;
+
+const runMain = Runtime.makeRunMain(({ fiber, teardown }) => {
+  fiber.addObserver((taskExit) => {
+    teardown(taskExit, (exitCode) => {
+      process.exit(exitCode);
+    });
+  });
+});
+
+export const main = (
+  rootTask: Task,
+  options: { readonly log?: keyof typeof MINIMUM_LOG_LEVEL_OF_LOG_OPTION } = {},
+) => {
+  if (isInsideTaskWorkerThread()) {
+    const isCalledWhileImportingTaskModule = !isInsideTaskBody() && isImportingTaskModule();
+    if (isCalledWhileImportingTaskModule) {
+      throw new RunCalledDuringImport();
+    }
+    throw new RunCalledInTaskBody({ rootTaskName: rootTask.name });
+  }
+  const runCall = Exit.succeed({
+    rootTaskName: rootTask.name,
+    stack: readStackAbove(main),
+  });
+  const isFirstRunCall = Deferred.doneUnsafe(runningRootTaskDeferred, runCall);
+  if (!isFirstRunCall) {
+    Deferred.doneUnsafe(laterRunCallDeferred, runCall);
+    return;
+  }
+  runMain(
+    Effect.gen(function* () {
+      const signals = yield* listenToSignals(STOP_SIGNALS);
+      if (Bun.isStandaloneExecutable) {
+        yield* printLine(
+          "Error",
+          formatFailureLines(
+            new RunCalledInStandaloneExecutable({ rootTaskName: rootTask.name }),
+            null,
+          ),
+        );
+        return 1;
+      }
+      const watchModeFlag = yield* bunWatchModeFlag;
+      if (Option.isSome(watchModeFlag)) {
+        yield* printLine(
+          "Error",
+          formatFailureLines(new RunCalledInBunWatchMode({ flag: watchModeFlag.value }), null),
+        );
+        return 1;
+      }
+      const supervision = yield* Effect.promise(() => import("../../supervise-the-run/index.ts"));
+      const supervisorProcessId = yield* supervision.readSupervisorProcessId;
+      const superviseThisRun =
+        supervisorProcessId === null && (yield* supervision.isRootTaskFileThere);
+      if (superviseThisRun) {
+        return yield* supervision.superviseRun(signals);
+      }
+      if (supervisorProcessId !== null) {
+        yield* supervision.reportReady;
+      }
+      const mainThread = yield* Effect.promise(() => import("../../main-thread/index.ts"));
+      return yield* mainThread.runRootTaskFiber.pipe(
+        Effect.provide(mainThread.MainThreadLive(rootTask, signals, supervisorProcessId)),
+        mainThread.exitCodeOfTheRun,
+        Effect.provide(mainThread.StopStateLive),
+      );
+    }).pipe(
+      Effect.catchTags({
+        RootTaskFileNotChecked: (failure) =>
+          printLine("Error", formatFailureLines(failure, null)).pipe(Effect.as(1)),
+        SupervisorSocketNotOpened: (failure) =>
+          printLine("Error", formatFailureLines(failure, null)).pipe(Effect.as(1)),
+      }),
+      Effect.scoped,
+      (program) =>
+        printLinesDuring(program, MINIMUM_LOG_LEVEL_OF_LOG_OPTION[options.log ?? "info"]),
+      Effect.provide(Layer.mergeAll(BunServices.layer, BunCrypto.layerSecureRandom)),
+      restoreStandardStreamFlagsAfter,
+      Effect.uninterruptible,
+      Effect.flatMap((ended) =>
+        typeof ended === "number"
+          ? Effect.void.pipe(
+              Effect.filterOrFail(
+                () => ended === 0,
+                () => new Exited({ code: ended }),
+              ),
+            )
+          : Effect.sync(() => process.kill(process.pid, ended)).pipe(
+              Effect.andThen(Effect.fail(new Exited({ code: 1 }))),
+            ),
+      ),
+    ),
+  );
+};

package/src/lib/task/internal/run-task-lists.ts

@@ -0,0 +1,51 @@
+import { Array as Arrays, Effect, Result, Schema } from "effect";
+import type { Types } from "effect";
+
+import { TaskRequestRefusal } from "../../../shared/task-errors.ts";
+import { SettledTasksFailed } from "../../errors/index.ts";
+import { Task } from "./make-tasks.ts";
+
+const tasksIn = (items: readonly (Readonly<Record<string, Task>> | Task)[]) =>
+  items.flatMap((listedItem) =>
+    listedItem instanceof Task ? [listedItem] : Object.values(listedItem),
+  );
+
+export const all = (
+  items: Parameters<typeof tasksIn>[0],
+  options: { readonly concurrency?: Types.Concurrency } = {},
+) => Effect.all(tasksIn(items), { concurrency: options.concurrency ?? "unbounded", discard: true });
+
+const isTaskRequestRefusal = Schema.is(TaskRequestRefusal);
+
+export const allSettled = (
+  items: Parameters<typeof tasksIn>[0],
+  options: { readonly concurrency?: Types.Concurrency } = {},
+) =>
+  Effect.gen(function* () {
+    const settledTasks = [
+      ...new Map(tasksIn(items).map((settledTask) => [settledTask.name, settledTask])).values(),
+    ];
+    const settledResults = yield* Effect.all(settledTasks, {
+      concurrency: options.concurrency ?? "unbounded",
+      mode: "result",
+    });
+    const failedSettledTasks = Arrays.zip(settledTasks, settledResults).flatMap(
+      ([settledTask, settledResult]) =>
+        Result.isFailure(settledResult)
+          ? [{ failedTaskName: settledTask.name, failure: settledResult.failure }]
+          : [],
+    );
+    const failures = failedSettledTasks.map((failedSettledTask) => failedSettledTask.failure);
+    const refusedRequest = failures.find((failure) => isTaskRequestRefusal(failure));
+    if (refusedRequest !== undefined) {
+      return yield* refusedRequest;
+    }
+    if (failures.length > 0) {
+      return yield* new SettledTasksFailed({
+        settledTaskCount: settledTasks.length,
+        failedTaskNames: failedSettledTasks.map(
+          (failedSettledTask) => failedSettledTask.failedTaskName,
+        ),
+      });
+    }
+  });

package/src/lib/task/internal/trust-output-mode-names.ts

@@ -0,0 +1,18 @@
+import { Schema } from "effect";
+
+import { dieOnInvariantFailure } from "../../../shared/invariant-errors.ts";
+
+export const trustOutputModeName = <Secret extends boolean>(secret: Secret | undefined) => {
+  const outputModeName = secret === true ? "secret" : "logged";
+  return Schema.decodeUnknownEffect(
+    Schema.declare(
+      (candidate): candidate is Secret extends true ? "secret" : "logged" =>
+        candidate === outputModeName,
+    ),
+  )(outputModeName).pipe(
+    dieOnInvariantFailure(
+      "Task.exec",
+      "the output mode named by the secret option matches the secret option's type",
+    ),
+  );
+};

package/src/lib/task/internal/trust-task-results.ts

@@ -0,0 +1,35 @@
+import { Effect, Schema } from "effect";
+
+import { InternalInvariantBroken } from "../../../shared/invariant-errors.ts";
+import {
+  holdsRedactedTaskResultKey,
+  reviveRedactedTaskResults,
+  TaskResult,
+} from "../../../shared/task-results.ts";
+
+export const trustTaskResult = <Success>(taskResult: Schema.Json | undefined) => {
+  const isBranch = taskResult !== null && typeof taskResult === "object";
+  const holdsRedacted = isBranch && holdsRedactedTaskResultKey(taskResult);
+  return (
+    holdsRedacted
+      ? reviveRedactedTaskResults(taskResult)
+      : Effect.succeed<typeof TaskResult.Type | undefined>(taskResult)
+  ).pipe(
+    Effect.flatMap((revived) =>
+      Schema.decodeUnknownEffect(
+        Schema.declare((candidate): candidate is Success =>
+          Schema.is(Schema.UndefinedOr(Schema.Union([Schema.Json, TaskResult])))(candidate),
+        ),
+      )(revived),
+    ),
+    Effect.catchTag("SchemaError", (cause) =>
+      Effect.die(
+        new InternalInvariantBroken({
+          area: "task results",
+          invariant: "a task's result is the JSON or Redacted strings its body returned",
+          cause,
+        }),
+      ),
+    ),
+  );
+};

package/src/lib/task/internal/use-task-services.ts

@@ -0,0 +1,4 @@
+import { Serving } from "../../../shared/task-services.ts";
+
+export const serve = <Success>(servedValue: Success) =>
+  Serving.use((serving) => serving.serve(servedValue));

package/src/lib/worker-thread/index.ts

@@ -0,0 +1,3 @@
+import { startWorkerThread } from "./internal/start-worker-thread.ts";
+
+startWorkerThread();