@sshkeda/task 0.0.0-stage → 1.0.0

package/src/shared/resolve-task-options.ts

@@ -0,0 +1,20 @@
+import type { Duration } from "effect";
+
+export const TASK_OPTION_NAMES = [
+  "timeout",
+  "cleanup",
+] as const satisfies readonly (keyof Parameters<typeof resolveTaskOptions>[0])[];
+
+export const resolveTaskOptions = (options: {
+  readonly timeout?: Duration.Input;
+  readonly cleanup?: Duration.Input;
+}) =>
+  Object.freeze({
+    timeout: options.timeout ?? null,
+    cleanup: options.cleanup ?? null,
+    unknownOptionNames: Object.freeze(
+      Object.keys(options).filter(
+        (optionName) => !TASK_OPTION_NAMES.some((knownName) => knownName === optionName),
+      ),
+    ),
+  });

package/src/shared/rpc.ts

@@ -0,0 +1,161 @@
+import { LogLevel, Schema } from "effect";
+import { Rpc, RpcGroup } from "effect/rpc";
+import { Transferable } from "effect/workers";
+
+import { PrintableError } from "../lib/errors/index.ts";
+import { ProcessIdentity } from "./claim-processes-to-report.ts";
+import { SCRIPT_LOADERS } from "./find-bun-loader-for-script.ts";
+import { RunMarker } from "./run-marker.ts";
+import { AwaitedTasksFailure, TaskRequestFailure } from "./task-errors.ts";
+
+export const StandardInputRead = Schema.TaggedUnion({
+  Chunks: { chunks: Schema.NonEmptyArray(Schema.Uint8Array) },
+  Ended: {},
+  Failed: { reason: Schema.String },
+});
+
+export const StartTaskFiber = Schema.Struct({
+  taskName: Schema.String,
+  taskFilePath: Schema.String,
+  taskPackageDirectoryPath: Schema.String,
+  cleanupMilliseconds: Schema.Finite,
+  traceId: Schema.String,
+  spanId: Schema.String,
+  standardInput: Schema.Struct({ isTerminal: Schema.Boolean, rootTaskName: Schema.String }),
+});
+
+export const TaskFiberResult = Schema.TaggedUnion({
+  Returned: {
+    value: Schema.optional(Schema.Json),
+    elapsedMilliseconds: Schema.Finite,
+  },
+  Failed: {
+    failures: Schema.NonEmptyArray(PrintableError),
+    details: Schema.optional(Schema.String),
+    failedCommandExitCode: Schema.optional(Schema.Int),
+  },
+  AwaitedTasksFailed: { failure: AwaitedTasksFailure },
+  CleanupFailed: {
+    failures: Schema.NonEmptyArray(PrintableError),
+    details: Schema.optional(Schema.String),
+  },
+  Interrupted: {},
+});
+
+const TaskFiberFailure = Schema.Union([
+  TaskFiberResult.cases.Failed,
+  TaskFiberResult.cases.AwaitedTasksFailed,
+]);
+
+export const StandardErrorLine = Schema.Struct({
+  logLevel: Schema.Literals(LogLevel.values),
+  text: Schema.String,
+});
+
+export const TASK_EVENT_FIELDS = {
+  TraceWriteFailed: { reason: Schema.String },
+  StandardErrorLineRequested: StandardErrorLine.fields,
+  TaskFiberLoading: { taskName: Schema.String },
+  TaskFiberStarted: { taskName: Schema.String },
+  TaskFiberReceivedAwaitedFailure: { taskName: Schema.String, awaitedTaskName: Schema.String },
+  TaskFiberFailedBeforeCleanup: { taskName: Schema.String, failure: TaskFiberFailure },
+  TaskFiberProcessLeaderExited: {
+    taskName: Schema.String,
+    processId: Schema.Int,
+    latestMemberStartTime: Schema.NullOr(Schema.String),
+  },
+  TaskFiberServed: { taskName: Schema.String, value: Schema.optional(Schema.Json) },
+  TaskFiberStartedCleanUp: { taskName: Schema.String },
+  TaskFiberEnded: {
+    taskName: Schema.String,
+    result: TaskFiberResult,
+    logs: Schema.Array(Schema.String),
+  },
+};
+
+export const TaskEvent = Schema.TaggedUnion(TASK_EVENT_FIELDS);
+
+export const StartedProcess = Schema.Struct({
+  taskName: Schema.String,
+  processId: Schema.Int,
+  startTime: Schema.NullOr(Schema.String),
+});
+
+export const ProcessReportsToClaim = Schema.Struct({
+  taskName: Schema.String,
+  processes: Schema.Array(ProcessIdentity),
+});
+
+export const TaskWorkerRpcs = RpcGroup.make(
+  Rpc.make("StartTaskFiber", { payload: StartTaskFiber }),
+  Rpc.make("StopTaskFiber", { payload: { taskName: Schema.String } }),
+  Rpc.make("AnswerIfResponsive"),
+  Rpc.make("ExitWorker"),
+);
+
+export const MainThreadRpcs = RpcGroup.make(
+  Rpc.make("ReportTaskEvent", { payload: TaskEvent }),
+  Rpc.make("RequestTask", {
+    payload: { taskName: Schema.String, dependencyTaskName: Schema.String },
+    success: Schema.Struct({ value: Schema.optionalKey(Schema.Json) }),
+    error: TaskRequestFailure,
+  }),
+  Rpc.make("ReadStandardInput", {
+    payload: { taskName: Schema.String },
+    success: StandardInputRead,
+  }),
+  Rpc.make("RecordStartedProcess", { payload: StartedProcess }),
+  Rpc.make("ClaimProcessReports", {
+    payload: ProcessReportsToClaim,
+    success: Schema.Array(ProcessIdentity),
+  }),
+);
+
+export const WorkerInitialMessage = Schema.Struct({ mainThreadPort: Transferable.MessagePort });
+
+const RequestIdentifier = Schema.Union([Schema.String, Schema.Finite]);
+
+export const MessageFromMainThreadRpcClient = Schema.Union([
+  Schema.TaggedStruct("Request", {
+    id: RequestIdentifier,
+    tag: Schema.String,
+    payload: Schema.Unknown,
+    headers: Schema.Array(Schema.mutable(Schema.Tuple([Schema.String, Schema.String]))),
+  }),
+  Schema.TaggedStruct("Ack", { requestId: RequestIdentifier }),
+  Schema.TaggedStruct("Interrupt", { requestId: RequestIdentifier }),
+  Schema.TaggedStruct("Eof", {}),
+]);
+
+export const MessageFromMainThreadRpcServer = Schema.Union([
+  Schema.TaggedStruct("Exit", {
+    requestId: RequestIdentifier,
+    exit: Schema.Union([
+      Schema.TaggedStruct("Success", { value: Schema.Unknown }),
+      Schema.TaggedStruct("Failure", {
+        cause: Schema.Array(
+          Schema.Union([
+            Schema.TaggedStruct("Fail", { error: Schema.Unknown }),
+            Schema.TaggedStruct("Die", { defect: Schema.Unknown }),
+            Schema.TaggedStruct("Interrupt", {
+              fiberId: Schema.UndefinedOr(Schema.NullOr(Schema.Finite)),
+            }),
+          ]),
+        ),
+      }),
+    ]),
+  }),
+  Schema.TaggedStruct("Defect", { defect: Schema.Unknown }),
+]);
+
+export const WorkerData = Schema.Struct({
+  workerId: Schema.Int,
+  traceFilePath: Schema.String,
+  projectDirectoryPath: Schema.String,
+  rewrittenFiles: Schema.Record(
+    Schema.String,
+    Schema.Struct({ contents: Schema.String, loader: Schema.Literals(SCRIPT_LOADERS) }),
+  ),
+  taskLogHold: Schema.instanceOf(Int32Array<SharedArrayBuffer>),
+  runMarker: Schema.NullOr(RunMarker),
+});

package/src/shared/run-in-child-fiber-and-join.ts

@@ -0,0 +1,16 @@
+import { Effect, Fiber } from "effect";
+
+export const runInChildFiberAndJoin = <Success, Failure, Services>(
+  effect: Effect.Effect<Success, Failure, Services>,
+) =>
+  Effect.uninterruptibleMask((restore) =>
+    Effect.flatMap(
+      Effect.forkChild(restore(effect), { startImmediately: true, uninterruptible: true }),
+      (childFiber) =>
+        Effect.interruptible(Fiber.join(childFiber)).pipe(
+          Effect.onInterrupt(() =>
+            Effect.andThen(Fiber.interrupt(childFiber), Fiber.join(childFiber)),
+          ),
+        ),
+    ),
+  );

package/src/shared/run-marker.ts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+
+export const RunMarker = Schema.Struct({
+  fileDescriptor: Schema.Int,
+  token: Schema.String,
+  environmentValue: Schema.String,
+});

package/src/shared/save-standard-stream-flags.ts

@@ -0,0 +1,57 @@
+import { dlopen, FFIType } from "bun:ffi";
+
+import { Effect } from "effect";
+
+const F_GETFL = 3;
+const F_SETFL = 4;
+const STANDARD_INPUT_FILE_DESCRIPTOR = 0;
+const STANDARD_OUTPUT_FILE_DESCRIPTOR = 1;
+const STANDARD_ERROR_FILE_DESCRIPTOR = 2;
+const STANDARD_STREAM_FILE_DESCRIPTORS = [
+  STANDARD_INPUT_FILE_DESCRIPTOR,
+  STANDARD_OUTPUT_FILE_DESCRIPTOR,
+  STANDARD_ERROR_FILE_DESCRIPTOR,
+] as const;
+const FILE_CONTROL = {
+  args: [FFIType.i32, FFIType.i32, FFIType.i32],
+  returns: FFIType.i32,
+} as const;
+
+const loadFileControl = () => {
+  if (process.platform === "darwin") {
+    const library = dlopen("/usr/lib/libSystem.B.dylib", { __fcntl: FILE_CONTROL });
+    return {
+      fileControl: library.symbols.__fcntl,
+      close: () => {
+        library.close();
+      },
+    };
+  }
+  const library = dlopen("libc.so.6", { fcntl: FILE_CONTROL });
+  return {
+    fileControl: library.symbols.fcntl,
+    close: () => {
+      library.close();
+    },
+  };
+};
+
+export const saveStandardStreamFlags = Effect.acquireRelease(
+  Effect.sync(loadFileControl),
+  (library) =>
+    Effect.sync(() => {
+      library.close();
+    }),
+).pipe(
+  Effect.map(({ fileControl }) => {
+    const savedFlags = STANDARD_STREAM_FILE_DESCRIPTORS.map((fileDescriptor) => ({
+      fileDescriptor,
+      flags: fileControl(fileDescriptor, F_GETFL, 0),
+    }));
+    return Effect.sync(() => {
+      for (const { fileDescriptor, flags } of savedFlags) {
+        fileControl(fileDescriptor, F_SETFL, flags);
+      }
+    });
+  }),
+);

package/src/shared/select-cause-reasons.ts

@@ -0,0 +1,14 @@
+import { Cause } from "effect";
+
+export const failuresOfCause = <Failure>(cause: Cause.Cause<Failure>) =>
+  Cause.fromReasons(cause.reasons.filter((reason) => !Cause.isInterruptReason(reason)));
+
+export const failureValuesOfReason = <Failure>(reason: Cause.Reason<Failure>) => {
+  if (Cause.isFailReason(reason)) {
+    return [reason.error];
+  }
+  return Cause.isDieReason(reason) ? [reason.defect] : [];
+};
+
+export const failureValuesOfCause = <Failure>(cause: Cause.Cause<Failure>) =>
+  cause.reasons.flatMap(failureValuesOfReason);

package/src/shared/signal-run-called-twice.ts

@@ -0,0 +1,11 @@
+import { Deferred } from "effect";
+
+const makeRunCallDeferred = () =>
+  Deferred.makeUnsafe<{
+    readonly rootTaskName: string;
+    readonly stack: string | undefined;
+  }>();
+
+export const runningRootTaskDeferred = makeRunCallDeferred();
+
+export const laterRunCallDeferred = makeRunCallDeferred();

package/src/shared/standard-input-streams.ts

@@ -0,0 +1,41 @@
+import { Cause, Deferred, Effect, Exit } from "effect";
+import type { PlatformError } from "effect";
+
+import { runInChildFiberAndJoin } from "./run-in-child-fiber-and-join.ts";
+
+const failuresOfStandardInputClosedByCommand = new WeakSet<PlatformError.PlatformError>();
+
+export const markStandardInputClosedByCommand = (failure: PlatformError.PlatformError) => {
+  failuresOfStandardInputClosedByCommand.add(failure);
+  return failure;
+};
+
+export const isStandardInputClosedByCommand = (failure: PlatformError.PlatformError) =>
+  failuresOfStandardInputClosedByCommand.has(failure);
+
+export const makeStandardInputRunner = () => {
+  const interruptedItselfDeferred = Deferred.makeUnsafe<void>();
+  return {
+    run: <Success, Failure, Services>(
+      standardInputRun: Effect.Effect<Success, Failure, Services>,
+    ) =>
+      Effect.withFiber((runningFiber) =>
+        runInChildFiberAndJoin(
+          Effect.onExit(standardInputRun, (standardInputExit) =>
+            Effect.sync(() => {
+              const interruptedByItsOwnFibers =
+                Exit.isFailure(standardInputExit) &&
+                Cause.hasInterruptsOnly(standardInputExit.cause) &&
+                standardInputExit.cause.reasons.some(
+                  (reason) => Cause.isInterruptReason(reason) && reason.fiberId !== runningFiber.id,
+                );
+              if (interruptedByItsOwnFibers) {
+                Deferred.doneUnsafe(interruptedItselfDeferred, Exit.void);
+              }
+            }),
+          ),
+        ),
+      ),
+    interruptedItself: () => Deferred.isDoneUnsafe(interruptedItselfDeferred),
+  };
+};

package/src/shared/stop-signals.ts

@@ -0,0 +1,41 @@
+import { Duration, Effect, Queue, Record } from "effect";
+
+export const STOP_SIGNAL_NUMBERS = { SIGHUP: 1, SIGINT: 2, SIGTERM: 15 } as const;
+
+export const STOP_SIGNALS = Record.keys(STOP_SIGNAL_NUMBERS);
+
+export const STOP_GRACE_PERIOD = Duration.fromInputUnsafe("5 seconds");
+
+export const STOP_REASON_NUMBERS = { ...STOP_SIGNAL_NUMBERS, SIGPIPE: 13 } as const;
+
+export const STOP_REASONS = Record.keys(STOP_REASON_NUMBERS);
+
+const SHELL_EXIT_CODE_BASE_FOR_SIGNALS = 128;
+
+export const exitCodeAfterStopSignal = (signal: (typeof STOP_REASONS)[number]) =>
+  SHELL_EXIT_CODE_BASE_FOR_SIGNALS + STOP_REASON_NUMBERS[signal];
+
+export const listenToSignals = <Signal extends NodeJS.Signals>(signals: readonly Signal[]) =>
+  Effect.gen(function* () {
+    const received = yield* Queue.unbounded<Signal>();
+    yield* Effect.acquireRelease(
+      Effect.sync(() =>
+        signals.map((signal) => {
+          const offer = () => {
+            Queue.offerUnsafe(received, signal);
+          };
+          process.on(signal, offer);
+          return () => {
+            process.off(signal, offer);
+          };
+        }),
+      ),
+      (removeListeners) =>
+        Effect.sync(() => {
+          for (const remove of removeListeners) {
+            remove();
+          }
+        }),
+    );
+    return received;
+  });

package/src/shared/task-errors.ts

@@ -0,0 +1,224 @@
+import { Duration, Effect, Option, Runtime, Schema } from "effect";
+
+import {
+  AwaitedTaskFailed,
+  REPORTED_FAILURE_FIELDS,
+  SettledTasksFailed,
+  TaskNotMadeAtTopLevel,
+  TaskWaitsOnItself,
+} from "../lib/errors/index.ts";
+import { attributeFailures, joinMessages } from "./attribute-reported-failures.ts";
+import { TASK_ERROR_FIELDS, UNATTRIBUTED_FAILURE_FIELDS } from "./error-fields.ts";
+import {
+  findConstructingLocation,
+  findLocationInFile,
+  findUserLocationInStack,
+} from "./find-user-locations-in-stack-traces.ts";
+import { relativeToWorkingDirectory } from "./format-error-lines.ts";
+import { ErrorStack, describeCauseMessage } from "./report-errors.ts";
+import { TASK_PACKAGE } from "./task-package.ts";
+
+export class TaskModuleImportFailed extends Schema.TaggedError<TaskModuleImportFailed>()(
+  "TaskModuleImportFailed",
+  { ...TASK_ERROR_FIELDS, filePath: Schema.String, cause: Schema.Defect() },
+) {
+  public get location() {
+    return Option.match(Schema.decodeUnknownOption(ErrorStack)(this.cause), {
+      onSome: (withStack) =>
+        findLocationInFile(withStack.stack, this.filePath) ??
+        findUserLocationInStack(withStack.stack) ??
+        this.filePath,
+      onNone: () => this.filePath,
+    });
+  }
+  public override get message() {
+    return `could not import task module because ${describeCauseMessage(this.cause)}`;
+  }
+}
+
+export class TaskTimedOut extends Schema.TaggedError<TaskTimedOut>()("TaskTimedOut", {
+  ...TASK_ERROR_FIELDS,
+  taskName: Schema.String,
+  timeoutMilliseconds: Schema.Finite,
+}) {
+  public override get message() {
+    return `timed out after ${Duration.format(Duration.millis(this.timeoutMilliseconds))}`;
+  }
+}
+
+export class TaskSetupTimedOut extends Schema.TaggedError<TaskSetupTimedOut>()(
+  "TaskSetupTimedOut",
+  {
+    ...TASK_ERROR_FIELDS,
+    taskName: Schema.String,
+    limitMilliseconds: Schema.Finite,
+    unfinishedStep: Schema.String,
+  },
+) {
+  public override get message() {
+    return `setup timed out after ${Duration.format(Duration.millis(this.limitMilliseconds))} while ${this.unfinishedStep}`;
+  }
+}
+
+export class StandardInputReadOutsideRootTask extends Schema.TaggedError<StandardInputReadOutsideRootTask>()(
+  "StandardInputReadOutsideRootTask",
+  { ...TASK_ERROR_FIELDS, taskName: Schema.String, rootTaskName: Schema.String },
+) {
+  public override get message() {
+    return `read standard input, which only the root task "${this.rootTaskName}" can read`;
+  }
+}
+
+export class ConfigKeyNotSet extends Schema.TaggedError<ConfigKeyNotSet>()("ConfigKeyNotSet", {
+  ...TASK_ERROR_FIELDS,
+  configKey: Schema.String,
+  environmentConfigVariable: Schema.NullOr(Schema.String),
+}) {
+  public override get message() {
+    return `configuration key ${this.configKey} is not set${this.environmentConfigVariable === null ? "" : `: the environment has no ${this.environmentConfigVariable}`}`;
+  }
+}
+
+export class TaskBodyFailed extends Schema.TaggedError<TaskBodyFailed>()("TaskBodyFailed", {
+  ...REPORTED_FAILURE_FIELDS,
+  ...TASK_ERROR_FIELDS,
+  failedCommandExitCode: Schema.optional(Schema.Int),
+}) {
+  public get reportedErrors() {
+    return attributeFailures(this, (failureMessage) => `its body failed with ${failureMessage}`);
+  }
+  public override get message() {
+    return joinMessages(this.reportedErrors);
+  }
+}
+
+export class ServedTaskFailed extends Schema.TaggedError<ServedTaskFailed>()("ServedTaskFailed", {
+  ...REPORTED_FAILURE_FIELDS,
+  ...TASK_ERROR_FIELDS,
+}) {
+  public get reportedErrors() {
+    return attributeFailures(
+      this,
+      (failureMessage) => `its body failed after serving with ${failureMessage}`,
+    );
+  }
+  public override get message() {
+    return joinMessages(this.reportedErrors);
+  }
+}
+
+export class Exited extends Schema.TaggedError<Exited>()("Exited", { code: Schema.Int }) {
+  public override get [Runtime.errorExitCode]() {
+    return this.code;
+  }
+
+  public override get [Runtime.errorReported]() {
+    return false;
+  }
+}
+
+export class RunCalledTwice extends Schema.TaggedError<RunCalledTwice>()("RunCalledTwice", {
+  ...TASK_ERROR_FIELDS,
+  ...UNATTRIBUTED_FAILURE_FIELDS,
+  runningRootTaskName: Schema.String,
+  runningRootTaskLocation: Schema.UndefinedOr(Schema.String),
+  laterRootTaskName: Schema.String,
+  location: Schema.UndefinedOr(Schema.String).pipe(
+    Schema.withConstructorDefault(Effect.sync(findConstructingLocation)),
+  ),
+}) {
+  public override get message() {
+    const startedAt =
+      this.runningRootTaskLocation === undefined
+        ? ""
+        : `, started at ${relativeToWorkingDirectory(this.runningRootTaskLocation)}`;
+    return `Task.main() was called again with "${this.laterRootTaskName}" while it runs "${this.runningRootTaskName}"${startedAt}`;
+  }
+}
+
+export class RunCalledDuringImport extends Schema.TaggedError<RunCalledDuringImport>()(
+  "RunCalledDuringImport",
+  {
+    ...TASK_ERROR_FIELDS,
+    ...UNATTRIBUTED_FAILURE_FIELDS,
+    location: Schema.UndefinedOr(Schema.String).pipe(
+      Schema.withConstructorDefault(Effect.sync(findConstructingLocation)),
+    ),
+  },
+) {
+  public override get message() {
+    return "Task.main() ran while Task imported this file";
+  }
+}
+
+export class RunCalledInTaskBody extends Schema.TaggedError<RunCalledInTaskBody>()(
+  "RunCalledInTaskBody",
+  {
+    ...TASK_ERROR_FIELDS,
+    rootTaskName: Schema.String,
+    location: Schema.UndefinedOr(Schema.String).pipe(
+      Schema.withConstructorDefault(Effect.sync(findConstructingLocation)),
+    ),
+  },
+) {
+  public override get message() {
+    return `Task.main() was called with "${this.rootTaskName}" inside a task body`;
+  }
+}
+
+export const TaskRequestRefusal = Schema.Union([TaskWaitsOnItself, TaskNotMadeAtTopLevel]);
+
+export const TaskRequestFailure = Schema.Union([AwaitedTaskFailed, TaskRequestRefusal]);
+
+export class TaskCleanupFailed extends Schema.TaggedError<TaskCleanupFailed>()(
+  "TaskCleanupFailed",
+  { ...REPORTED_FAILURE_FIELDS, ...TASK_ERROR_FIELDS },
+) {
+  public get reportedErrors() {
+    return attributeFailures(this, (failureMessage) => `its cleanup failed with ${failureMessage}`);
+  }
+  public override get message() {
+    return joinMessages(this.reportedErrors);
+  }
+}
+
+export const isAwaitedTaskFailed = Schema.is(AwaitedTaskFailed);
+
+export const AwaitedTasksFailure = Schema.Union([AwaitedTaskFailed, SettledTasksFailed]);
+
+export const isAwaitedTasksFailure = Schema.is(AwaitedTasksFailure);
+
+export class RootTaskFileNotChecked extends Schema.TaggedError<RootTaskFileNotChecked>()(
+  "RootTaskFileNotChecked",
+  {
+    ...TASK_ERROR_FIELDS,
+    ...UNATTRIBUTED_FAILURE_FIELDS,
+    filePath: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  public get location() {
+    return this.filePath;
+  }
+  public override get message() {
+    return `could not check whether the root task file exists because ${describeCauseMessage(this.cause)}`;
+  }
+}
+
+export class RunCalledInStandaloneExecutable extends Schema.TaggedError<RunCalledInStandaloneExecutable>()(
+  "RunCalledInStandaloneExecutable",
+  { ...TASK_ERROR_FIELDS, ...UNATTRIBUTED_FAILURE_FIELDS, rootTaskName: Schema.String },
+) {
+  public override get message() {
+    return `Task.main() was called with "${this.rootTaskName}" inside a bun build --compile binary, which holds only its bundle, not the task source files ${TASK_PACKAGE.name} scans and re-imports in worker threads`;
+  }
+}
+
+export class RunCalledInBunWatchMode extends Schema.TaggedError<RunCalledInBunWatchMode>()(
+  "RunCalledInBunWatchMode",
+  { ...TASK_ERROR_FIELDS, ...UNATTRIBUTED_FAILURE_FIELDS, flag: Schema.String },
+) {
+  public override get message() {
+    return `${TASK_PACKAGE.name} doesn't run under bun ${this.flag}`;
+  }
+}

package/src/shared/task-package.ts

@@ -0,0 +1,5 @@
+export const TASK_PACKAGE = {
+  name: "@sshkeda/task",
+  version: "1.0.0",
+  engines: { bun: ">=1.4.4" },
+} as const;

package/src/shared/task-results.ts

@@ -0,0 +1,55 @@
+import { Array as Arrays, Effect, Predicate, Redacted, Schema } from "effect";
+
+export const REDACTED_TASK_RESULT_KEY = "~@sshkeda/task/Redacted";
+
+export const TaskResult = Schema.Tree(
+  Schema.Union([
+    Schema.Null,
+    Schema.Finite,
+    Schema.Boolean,
+    Schema.String,
+    Schema.Redacted(Schema.String),
+  ]),
+);
+
+export const holdsRedactedTaskResultKey = (root: Schema.JsonArray | Schema.JsonObject) => {
+  const pendingBranches = [root];
+  for (const branch of pendingBranches) {
+    if (Object.hasOwn(branch, REDACTED_TASK_RESULT_KEY)) {
+      return true;
+    }
+    const children = Arrays.isArray<Schema.JsonArray | Schema.JsonObject>(branch)
+      ? branch
+      : Object.values(branch);
+    for (const child of children) {
+      const isBranch = child !== null && typeof child === "object";
+      if (isBranch) {
+        pendingBranches.push(child);
+      }
+    }
+  }
+  return false;
+};
+
+export const reviveRedactedTaskResults = (
+  value: Schema.Json,
+): Effect.Effect<typeof TaskResult.Type> => {
+  const isLeaf = value === null || typeof value !== "object";
+  if (isLeaf) {
+    return Effect.succeed(value);
+  }
+  return Effect.gen(function* () {
+    if (Arrays.isArray<Schema.JsonArray | Schema.JsonObject>(value)) {
+      return yield* Effect.forEach(value, reviveRedactedTaskResults);
+    }
+    const tagged = value[REDACTED_TASK_RESULT_KEY];
+    if (Predicate.isString(tagged)) {
+      return Redacted.make(tagged);
+    }
+    return Object.fromEntries(
+      yield* Effect.forEach(Object.entries(value), ([key, child]) =>
+        Effect.map(reviveRedactedTaskResults(child), (revived) => [key, revived] as const),
+      ),
+    );
+  });
+};

package/src/shared/task-services.ts

@@ -0,0 +1,30 @@
+import { Context } from "effect";
+import type { Effect, Schema } from "effect";
+
+import type { TaskResultNotJson } from "../lib/errors/index.ts";
+import type { Task } from "../lib/task/index.ts";
+import type { TaskRequestFailure } from "./task-errors.ts";
+import { TASK_PACKAGE } from "./task-package.ts";
+
+export class Tasks extends Context.Service<
+  Tasks,
+  {
+    readonly requestResult: (
+      task: Task,
+    ) => Effect.Effect<Schema.Json | undefined, typeof TaskRequestFailure.Type>;
+  }
+>()(`${TASK_PACKAGE.name}/Tasks`) {}
+
+export class Served<Success> {
+  protected readonly servedValue: Success | undefined = undefined;
+  private constructor() {}
+}
+
+export class Serving extends Context.Service<
+  Serving,
+  {
+    readonly serve: <Success>(
+      servedValue: Success,
+    ) => Effect.Effect<Served<Success>, TaskResultNotJson>;
+  }
+>()(`${TASK_PACKAGE.name}/Serving`) {}