@fungi.computer/watchdog 0.0.0-stage → 0.0.1

package/docs/api/effect.md

@@ -0,0 +1,875 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/watchdog**](README.md)
+
+---
+
+[@fungi.computer/watchdog](README.md) / effect
+
+# effect
+
+## Type Aliases
+
+### WatchdogQueuedJob
+
+```ts
+type WatchdogQueuedJob = Schema.Schema.Type<typeof WatchdogQueuedJobSchema>;
+```
+
+Generic durable work waiting for execution.
+
+---
+
+### WatchdogSettledJob
+
+```ts
+type WatchdogSettledJob = Schema.Schema.Type<typeof WatchdogSettledJobSchema>;
+```
+
+Generic durable work with a terminal outcome.
+
+---
+
+### WatchdogSettledRecord
+
+```ts
+type WatchdogSettledRecord = Readonly<{
+  sequence: number;
+  job: WatchdogSettledJob;
+}>;
+```
+
+One bounded terminal-job recovery record with its durable ordering cursor.
+
+---
+
+### WatchdogRunningJob
+
+```ts
+type WatchdogRunningJob = Schema.Schema.Type<typeof WatchdogRunningJobSchema>;
+```
+
+Generic durable work held by Watchdog's private claim.
+
+---
+
+### WatchdogStoredJob
+
+```ts
+type WatchdogStoredJob = Schema.Schema.Type<typeof WatchdogStoredJobSchema>;
+```
+
+Any publicly readable lifecycle state for a generic job.
+
+---
+
+### WatchdogExecutionDecision
+
+```ts
+type WatchdogExecutionDecision = Schema.Schema.Type<
+  typeof WatchdogExecutionDecisionSchema
+>;
+```
+
+Terminal decision returned by the host executor.
+
+---
+
+### WatchdogCancellationIntent
+
+```ts
+type WatchdogCancellationIntent = Schema.Schema.Type<
+  typeof WatchdogCancellationIntentSchema
+>;
+```
+
+Owner-issued durable cancellation intent.
+
+---
+
+### WatchdogCancellationDecision
+
+```ts
+type WatchdogCancellationDecision =
+  | Readonly<{
+      status: "recorded" | "replayed";
+      intent: WatchdogCancellationIntent;
+    }>
+  | Readonly<{
+      status: "conflict" | "missing";
+    }>;
+```
+
+Result of recording an owner cancellation in its surrounding transaction.
+
+---
+
+### WatchdogTransactionalProjection
+
+```ts
+type WatchdogTransactionalProjection = Readonly<{
+  readQueueHead: (queue) => WatchdogQueueHead;
+  readLatestSettledJob: (queue) => WatchdogSettledJob | undefined;
+  enqueueAcceptedJob: (job) => void;
+  recordCancellationIntent: (intent) => WatchdogCancellationDecision;
+}>;
+```
+
+Narrow synchronous seam for owner-atomic queue inspection, ingest, and
+cancellation.
+
+---
+
+### WatchdogReadResult
+
+```ts
+type WatchdogReadResult = Schema.Schema.Type<typeof WatchdogReadResultSchema>;
+```
+
+Result of reading one generic job and its cancellation state.
+
+---
+
+### WatchdogQueueHead
+
+```ts
+type WatchdogQueueHead = Schema.Schema.Type<typeof WatchdogQueueHeadSchema>;
+```
+
+Current queued or running job for one queue, excluding terminal history.
+
+---
+
+### WatchdogQueueTransition
+
+```ts
+type WatchdogQueueTransition = Readonly<{
+  queue: string;
+  head: WatchdogQueueHead;
+  settled?: WatchdogSettledJob;
+}>;
+```
+
+One queue's state after a durable transition.
+
+---
+
+### WatchdogQueueProjector
+
+```ts
+type WatchdogQueueProjector = (transition) => void;
+```
+
+Owner projection written inside the same SQLite transaction as every queue
+transition: ingest, claim, cancellation, settlement, recovery and purge. It must
+be a deterministic owner-local write. A throw fails the transition exactly like
+any other storage failure.
+
+#### Parameters
+
+| Parameter    | Type                                                  |
+| ------------ | ----------------------------------------------------- |
+| `transition` | [`WatchdogQueueTransition`](#watchdogqueuetransition) |
+
+#### Returns
+
+`void`
+
+---
+
+### WatchdogIngestResult
+
+```ts
+type WatchdogIngestResult = Schema.Schema.Type<
+  typeof WatchdogIngestResultSchema
+>;
+```
+
+Result of idempotent durable ingest.
+
+---
+
+### WatchdogCancellationResult
+
+```ts
+type WatchdogCancellationResult = Schema.Schema.Type<
+  typeof WatchdogCancellationResultSchema
+>;
+```
+
+Result of recording a cancellation through the asynchronous runtime.
+
+---
+
+### EffectWatchdogExecutor
+
+```ts
+type EffectWatchdogExecutor = Readonly<{
+  execute: (job) => Effect.Effect<WatchdogExecutionDecision, WatchdogError>;
+}>;
+```
+
+Effect-native host executor for one generic running job.
+
+---
+
+### WatchdogSqliteValue
+
+```ts
+type WatchdogSqliteValue = Schema.Schema.Type<typeof watchdogSqliteValueSchema>;
+```
+
+Parsed native SQLite scalar shared by the durable storage adapters.
+
+---
+
+### WatchdogSqliteRow
+
+```ts
+type WatchdogSqliteRow = Schema.Schema.Type<typeof watchdogSqliteRowSchema>;
+```
+
+Parsed scalar record; query-specific columns require their owner schema.
+
+---
+
+### WatchdogSqliteCursor
+
+```ts
+type WatchdogSqliteCursor = Readonly<{
+  toArray: () => readonly WatchdogSqliteRow[];
+}>;
+```
+
+Structural result cursor required by Watchdog's SQLite implementation.
+
+---
+
+### WatchdogSqliteOwner
+
+```ts
+type WatchdogSqliteOwner = Readonly<{
+  sql: Readonly<{
+    exec: (statement, ...bindings) => WatchdogSqliteCursor;
+  }>;
+  transactionSync: <A>(operation) => A;
+}>;
+```
+
+Native owner-local SQLite capability consumed by Watchdog.
+
+---
+
+### EffectWatchdogOptions
+
+```ts
+type EffectWatchdogOptions = Readonly<{
+  concurrentLane?: string;
+  owner: WatchdogSqliteOwner;
+  isAlive: (job) => Effect.Effect<boolean, WatchdogError>;
+  executor: EffectWatchdogExecutor;
+  wake: Readonly<{
+    recompute: () => Effect.Effect<void, WatchdogError>;
+  }>;
+  project?: WatchdogQueueProjector;
+}>;
+```
+
+Effect-native construction inputs for the deep SQLite Watchdog.
+
+---
+
+### WatchdogLivenessUnknown
+
+```ts
+type WatchdogLivenessUnknown = Readonly<{
+  status: "liveness_unknown";
+  jobId: string;
+  reason: WatchdogError["cause"];
+}>;
+```
+
+A running job's liveness probe failed. The job is left exactly as it was:
+Watchdog neither treats it as alive nor fabricates a disappearance.
+
+---
+
+### WatchdogTickResult
+
+```ts
+type WatchdogTickResult =
+  | Readonly<{
+      status: "busy";
+    }>
+  | Readonly<{
+      status: "no_ready";
+    }>
+  | WatchdogLivenessUnknown
+  | Readonly<{
+      status: "settled";
+      job: WatchdogSettledJob;
+    }>;
+```
+
+Result of one bounded deep tick.
+
+---
+
+### WatchdogLaneFailure
+
+```ts
+type WatchdogLaneFailure = Readonly<{
+  lane: string;
+  reason: string;
+}>;
+```
+
+Owner-issued terminal lane refusal; reason is an owner code, at most 200
+characters.
+
+---
+
+### WatchdogLaneFailureResult
+
+```ts
+type WatchdogLaneFailureResult = Readonly<{
+  settled: number;
+  more: boolean;
+}>;
+```
+
+One bounded refusal batch; call again only while more is true.
+
+---
+
+### WatchdogRuntimeEffect
+
+```ts
+type WatchdogRuntimeEffect = Readonly<{
+  hasPendingWork: Effect.Effect<boolean, WatchdogError>;
+  ingest: (job) => Effect.Effect<WatchdogIngestResult, WatchdogError>;
+  read: (jobId) => Effect.Effect<WatchdogReadResult, WatchdogError>;
+  readQueueHead: (queue) => Effect.Effect<WatchdogQueueHead, WatchdogError>;
+  readSettled: (
+    limit,
+    afterSequence?,
+  ) => Effect.Effect<readonly WatchdogSettledRecord[], WatchdogError>;
+  tick: () => Effect.Effect<WatchdogTickResult, WatchdogError>;
+  cancel: (input) => Effect.Effect<WatchdogCancellationResult, WatchdogError>;
+  failLane: (input) => Effect.Effect<WatchdogLaneFailureResult, WatchdogError>;
+  purge: (queue) => Effect.Effect<void, WatchdogError>;
+  transactional: WatchdogTransactionalProjection;
+}>;
+```
+
+Effect-native Watchdog runtime surface.
+
+---
+
+### ConcurrentWatchdogRuntimeEffect
+
+```ts
+type ConcurrentWatchdogRuntimeEffect = WatchdogRuntimeEffect &
+  Readonly<{
+    tickConcurrent: () => Effect.Effect<WatchdogTickResult, WatchdogError>;
+  }>;
+```
+
+Runtime configured with one independent host lane at construction.
+
+## Variables
+
+### WatchdogQueuedJobSchema
+
+```ts
+const WatchdogQueuedJobSchema: Struct<{
+  jobId: String;
+  queue: String;
+  lane: String;
+  priority: Int;
+  payload: Unknown;
+  recovery: optional<
+    Struct<{
+      maxRecoveries: Int;
+    }>
+  >;
+  state: Literal<"queued">;
+}>;
+```
+
+The public queued-job grammar. Payload is deliberately uninterpreted.
+
+---
+
+### WatchdogSettledJobSchema
+
+```ts
+const WatchdogSettledJobSchema: Struct<{
+  jobId: String;
+  queue: String;
+  lane: String;
+  priority: Int;
+  payload: Unknown;
+  recovery: optional<
+    Struct<{
+      maxRecoveries: Int;
+    }>
+  >;
+  state: Literal<"settled">;
+  outcome: Literals<
+    readonly [
+      "completed",
+      "failed",
+      "cancelled",
+      "outcome_unknown",
+      "interrupted",
+    ]
+  >;
+  failureReason: optionalKey<String>;
+}>;
+```
+
+The public terminal-job grammar.
+
+---
+
+### WatchdogRunningJobSchema
+
+```ts
+const WatchdogRunningJobSchema: Struct<{
+  jobId: String;
+  queue: String;
+  lane: String;
+  priority: Int;
+  payload: Unknown;
+  recovery: optional<
+    Struct<{
+      maxRecoveries: Int;
+    }>
+  >;
+  state: Literal<"running">;
+}>;
+```
+
+The public running-job grammar. Private claim data is deliberately absent.
+
+---
+
+### WatchdogStoredJobSchema
+
+```ts
+const WatchdogStoredJobSchema: Union<
+  readonly [
+    Struct<{
+      jobId: String;
+      queue: String;
+      lane: String;
+      priority: Int;
+      payload: Unknown;
+      recovery: optional<
+        Struct<{
+          maxRecoveries: Int;
+        }>
+      >;
+      state: Literal<"queued">;
+    }>,
+    Struct<{
+      jobId: String;
+      queue: String;
+      lane: String;
+      priority: Int;
+      payload: Unknown;
+      recovery: optional<
+        Struct<{
+          maxRecoveries: Int;
+        }>
+      >;
+      state: Literal<"running">;
+    }>,
+    Struct<{
+      jobId: String;
+      queue: String;
+      lane: String;
+      priority: Int;
+      payload: Unknown;
+      recovery: optional<
+        Struct<{
+          maxRecoveries: Int;
+        }>
+      >;
+      state: Literal<"settled">;
+      outcome: Literals<
+        readonly [
+          "completed",
+          "failed",
+          "cancelled",
+          "outcome_unknown",
+          "interrupted",
+        ]
+      >;
+      failureReason: optionalKey<String>;
+    }>,
+  ]
+>;
+```
+
+The complete public job lifecycle grammar.
+
+---
+
+### WatchdogExecutionDecisionSchema
+
+```ts
+const WatchdogExecutionDecisionSchema: Union<
+  readonly [
+    Struct<{
+      kind: Literal<"completed">;
+    }>,
+    Struct<{
+      kind: Literal<"failed">;
+      reason: optionalKey<String>;
+    }>,
+    Struct<{
+      kind: Literal<"cancelled">;
+    }>,
+    Struct<{
+      kind: Literal<"outcome_unknown">;
+    }>,
+  ]
+>;
+```
+
+Terminal decisions returned by the execution adapter.
+
+---
+
+### WatchdogCancellationIntentSchema
+
+```ts
+const WatchdogCancellationIntentSchema: Struct<{
+  jobId: String;
+  cancellationId: String;
+  onlyIfQueued: optional<Boolean>;
+}>;
+```
+
+Durable cancellation requested by the enclosing owner.
+
+---
+
+### WatchdogReadResultSchema
+
+```ts
+const WatchdogReadResultSchema: Union<readonly [Struct<{
+  status: Literal<"found">;
+  job: Union<readonly [Struct<{
+     jobId: String;
+     queue: String;
+     lane: String;
+     priority: Int;
+     payload: Unknown;
+     recovery: optional<Struct<{
+        maxRecoveries: ...;
+     }>>;
+     state: Literal<"queued">;
+   }>, Struct<{
+     jobId: String;
+     queue: String;
+     lane: String;
+     priority: Int;
+     payload: Unknown;
+     recovery: optional<Struct<{
+        maxRecoveries: ...;
+     }>>;
+     state: Literal<"running">;
+   }>, Struct<{
+     jobId: String;
+     queue: String;
+     lane: String;
+     priority: Int;
+     payload: Unknown;
+     recovery: optional<Struct<{
+        maxRecoveries: ...;
+     }>>;
+     state: Literal<"settled">;
+     outcome: Literals<readonly ["completed", "failed", "cancelled", "outcome_unknown", "interrupted"]>;
+     failureReason: optionalKey<String>;
+  }>]>;
+  cancellation: Union<readonly [Struct<{
+     status: Literal<"absent">;
+   }>, Struct<{
+     status: Literal<"present">;
+     cancellation: Struct<{
+        jobId: String;
+        cancellationId: String;
+        onlyIfQueued: optional<...>;
+     }>;
+  }>]>;
+}>, Struct<{
+  status: Literal<"missing">;
+}>]>;
+```
+
+Results returned by public job inspection.
+
+---
+
+### WatchdogQueueHeadSchema
+
+```ts
+const WatchdogQueueHeadSchema: Union<
+  readonly [
+    Struct<{
+      state: Literal<"idle">;
+    }>,
+    Struct<{
+      state: Literals<readonly ["queued", "running"]>;
+      jobId: String;
+      cancellationRequested: Boolean;
+    }>,
+  ]
+>;
+```
+
+Bounded current-work projection for one generic queue.
+
+---
+
+### WatchdogIngestResultSchema
+
+```ts
+const WatchdogIngestResultSchema: Union<
+  readonly [
+    Struct<{
+      status: Literal<"queued">;
+    }>,
+    Struct<{
+      status: Literal<"duplicate">;
+    }>,
+  ]
+>;
+```
+
+Results returned by idempotent public ingest.
+
+---
+
+### WatchdogCancellationResultSchema
+
+```ts
+const WatchdogCancellationResultSchema: Union<
+  readonly [
+    Struct<{
+      status: Literals<readonly ["recorded", "replayed"]>;
+    }>,
+    Struct<{
+      status: Literals<readonly ["conflict", "missing"]>;
+    }>,
+  ]
+>;
+```
+
+Results returned by durable cancellation recording.
+
+---
+
+### watchdogSqliteValueSchema
+
+```ts
+const watchdogSqliteValueSchema: Union<
+  readonly [instanceOf<ArrayBuffer, unknown>, String, Number, Null]
+>;
+```
+
+Scalar grammar shared by native SQLite adapters and their storage owners.
+
+---
+
+### watchdogSqliteRowSchema
+
+```ts
+const watchdogSqliteRowSchema: $Record<
+  String,
+  Union<readonly [instanceOf<ArrayBuffer, unknown>, String, Number, Null]>
+>;
+```
+
+A native row is a scalar record; each query owner decodes its own projection.
+
+## Functions
+
+### makeRuntime()
+
+#### Call Signature
+
+```ts
+function makeRuntime(
+  options,
+): Effect<ConcurrentWatchdogRuntimeEffect, WatchdogError>;
+```
+
+Construct two private single-flight slots over the same owner and job table.
+
+##### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `concurrentLane?`: `string`; `owner`: [`WatchdogSqliteOwner`](#watchdogsqliteowner); `isAlive`: (`job`) => `Effect`\<`boolean`, [`WatchdogError`](index.md#watchdogerror)\>; `executor`: [`EffectWatchdogExecutor`](#effectwatchdogexecutor); `wake`: `Readonly`\<\{ `recompute`: () => `Effect.Effect`\<`void`, [`WatchdogError`](index.md#watchdogerror)\>; \}\>; `project?`: [`WatchdogQueueProjector`](#watchdogqueueprojector); \}\> & `object` |
+
+##### Returns
+
+`Effect`\<[`ConcurrentWatchdogRuntimeEffect`](#concurrentwatchdogruntimeeffect),
+[`WatchdogError`](index.md#watchdogerror)\>
+
+#### Call Signature
+
+```ts
+function makeRuntime(options): Effect<Readonly<{
+  hasPendingWork: Effect<boolean, WatchdogError>;
+  ingest: (job) => Effect<
+     | {
+     status: "queued";
+   }
+     | {
+     status: "duplicate";
+  }, WatchdogError>;
+  read: (jobId) => Effect<
+     | {
+     status: "found";
+     job:   | {
+        jobId: string;
+        queue: string;
+        lane: string;
+        priority: number;
+        payload: unknown;
+        recovery?: {
+           maxRecoveries: ...;
+        };
+        state: "queued";
+      }
+        | {
+        jobId: string;
+        queue: string;
+        lane: string;
+        priority: number;
+        payload: unknown;
+        recovery?: {
+           maxRecoveries: ...;
+        };
+        state: "running";
+      }
+        | {
+        jobId: string;
+        queue: string;
+        lane: string;
+        priority: number;
+        payload: unknown;
+        recovery?: {
+           maxRecoveries: ...;
+        };
+        state: "settled";
+        outcome: "failed" | "completed" | "interrupted" | "cancelled" | "outcome_unknown";
+        failureReason?: string;
+      };
+     cancellation:   | {
+        status: "absent";
+      }
+        | {
+        status: "present";
+        cancellation: {
+           jobId: string;
+           cancellationId: string;
+           onlyIfQueued?: ... | ... | ...;
+        };
+      };
+   }
+     | {
+     status: "missing";
+  }, WatchdogError>;
+  readQueueHead: (queue) => Effect<
+     | {
+     state: "idle";
+   }
+     | {
+     state: "running" | "queued";
+     jobId: string;
+     cancellationRequested: boolean;
+  }, WatchdogError>;
+  readSettled: (limit, afterSequence?) => Effect<readonly Readonly<{
+     sequence: number;
+     job: {
+        jobId: string;
+        queue: string;
+        lane: string;
+        priority: number;
+        payload: unknown;
+        recovery?: {
+           maxRecoveries: ...;
+        };
+        state: "settled";
+        outcome: "failed" | "completed" | "interrupted" | "cancelled" | "outcome_unknown";
+        failureReason?: string;
+     };
+  }>[], WatchdogError>;
+  tick: () => Effect<WatchdogTickResult, WatchdogError>;
+  cancel: (input) => Effect<
+     | {
+     status: "replayed" | "recorded";
+   }
+     | {
+     status: "missing" | "conflict";
+  }, WatchdogError>;
+  failLane: (input) => Effect<Readonly<{
+     settled: number;
+     more: boolean;
+  }>, WatchdogError>;
+  purge: (queue) => Effect<void, WatchdogError>;
+  transactional: WatchdogTransactionalProjection;
+}>, WatchdogError>;
+```
+
+Construct a serial owner-local runtime.
+
+##### Parameters
+
+| Parameter | Type                                              |
+| --------- | ------------------------------------------------- |
+| `options` | [`EffectWatchdogOptions`](#effectwatchdogoptions) |
+
+##### Returns
+
+`Effect`\<`Readonly`\<\{ `hasPendingWork`: `Effect`\<`boolean`,
+[`WatchdogError`](index.md#watchdogerror)\>; `ingest`: (`job`) => `Effect`\< \|
+\{ `status`: `"queued"`; \} \| \{ `status`: `"duplicate"`; \},
+[`WatchdogError`](index.md#watchdogerror)\>; `read`: (`jobId`) => `Effect`\< \|
+\{ `status`: `"found"`; `job`: \| \{ `jobId`: `string`; `queue`: `string`;
+`lane`: `string`; `priority`: `number`; `payload`: `unknown`; `recovery?`: \{
+`maxRecoveries`: ...; \}; `state`: `"queued"`; \} \| \{ `jobId`: `string`;
+`queue`: `string`; `lane`: `string`; `priority`: `number`; `payload`: `unknown`;
+`recovery?`: \{ `maxRecoveries`: ...; \}; `state`: `"running"`; \} \| \{
+`jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`: `number`;
+`payload`: `unknown`; `recovery?`: \{ `maxRecoveries`: ...; \}; `state`:
+`"settled"`; `outcome`: `"failed"` \| `"completed"` \| `"interrupted"` \|
+`"cancelled"` \| `"outcome_unknown"`; `failureReason?`: `string`; \};
+`cancellation`: \| \{ `status`: `"absent"`; \} \| \{ `status`: `"present"`;
+`cancellation`: \{ `jobId`: `string`; `cancellationId`: `string`;
+`onlyIfQueued?`: ... \| ... \| ...; \}; \}; \} \| \{ `status`: `"missing"`; \},
+[`WatchdogError`](index.md#watchdogerror)\>; `readQueueHead`: (`queue`) =>
+`Effect`\< \| \{ `state`: `"idle"`; \} \| \{ `state`: `"running"` \| `"queued"`;
+`jobId`: `string`; `cancellationRequested`: `boolean`; \},
+[`WatchdogError`](index.md#watchdogerror)\>; `readSettled`: (`limit`,
+`afterSequence?`) => `Effect`\<readonly `Readonly`\<\{ `sequence`: `number`;
+`job`: \{ `jobId`: `string`; `queue`: `string`; `lane`: `string`; `priority`:
+`number`; `payload`: `unknown`; `recovery?`: \{ `maxRecoveries`: ...; \};
+`state`: `"settled"`; `outcome`: `"failed"` \| `"completed"` \| `"interrupted"`
+\| `"cancelled"` \| `"outcome_unknown"`; `failureReason?`: `string`; \}; \}\>[],
+[`WatchdogError`](index.md#watchdogerror)\>; `tick`: () =>
+`Effect`\<[`WatchdogTickResult`](#watchdogtickresult),
+[`WatchdogError`](index.md#watchdogerror)\>; `cancel`: (`input`) => `Effect`\<
+\| \{ `status`: `"replayed"` \| `"recorded"`; \} \| \{ `status`: `"missing"` \|
+`"conflict"`; \}, [`WatchdogError`](index.md#watchdogerror)\>; `failLane`:
+(`input`) => `Effect`\<`Readonly`\<\{ `settled`: `number`; `more`: `boolean`;
+\}\>, [`WatchdogError`](index.md#watchdogerror)\>; `purge`: (`queue`) =>
+`Effect`\<`void`, [`WatchdogError`](index.md#watchdogerror)\>; `transactional`:
+[`WatchdogTransactionalProjection`](#watchdogtransactionalprojection); \}\>,
+[`WatchdogError`](index.md#watchdogerror)\>