Skip to content
Watchdog0.1.0
API reference

effect

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/watchdog/effect";

Exports

Section titled “Exports”
Kind Export Description
type alias WatchdogQueuedJob Generic durable work waiting for execution.
type alias WatchdogSettledJob Generic durable work with a terminal outcome.
type alias WatchdogSettledRecord One bounded terminal-job recovery record with its durable ordering cursor.
type alias WatchdogRunningJob Generic durable work held by Watchdog’s private claim.
type alias WatchdogStoredJob Any publicly readable lifecycle state for a generic job.
type alias WatchdogExecutionDecision Terminal decision returned by the host executor.
type alias WatchdogCancellationIntent Owner-issued durable cancellation intent.
type alias WatchdogCancellationDecision Result of recording an owner cancellation in its surrounding transaction.
type alias WatchdogTransactionalProjection Narrow synchronous seam for owner-atomic queue inspection, ingest, and cancellation.
type alias WatchdogReadResult Result of reading one generic job and its cancellation state.
type alias WatchdogQueueHead Current queued or running job for one queue, excluding terminal history.
type alias WatchdogQueueTransition One queue’s state after a durable transition.
type alias WatchdogQueueProjector 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.
type alias WatchdogIngestResult Result of idempotent durable ingest.
type alias WatchdogCancellationResult Result of recording a cancellation through the asynchronous runtime.
type alias EffectWatchdogExecutor Effect-native host executor for one generic running job.
type alias WatchdogSqliteValue Parsed native SQLite scalar shared by the durable storage adapters.
type alias WatchdogSqliteRow Parsed scalar record; query-specific columns require their owner schema.
type alias WatchdogSqliteCursor Structural result cursor required by Watchdog’s SQLite implementation.
type alias WatchdogSqliteOwner Native owner-local SQLite capability consumed by Watchdog.
type alias EffectWatchdogOptions Effect-native construction inputs for the deep SQLite Watchdog.
type alias WatchdogLivenessUnknown 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.
type alias WatchdogTickResult Result of one bounded deep tick.
type alias WatchdogLaneFailure Owner-issued terminal lane refusal; reason is an owner code, at most 200 characters.
type alias WatchdogLaneFailureResult One bounded refusal batch; call again only while more is true.
type alias WatchdogRuntimeEffect Effect-native Watchdog runtime surface.
type alias ConcurrentWatchdogRuntimeEffect Runtime configured with one independent host lane at construction.
constant WatchdogQueuedJobSchema The public queued-job grammar. Payload is deliberately uninterpreted.
constant WatchdogSettledJobSchema The public terminal-job grammar.
constant WatchdogRunningJobSchema The public running-job grammar. Private claim data is deliberately absent.
constant WatchdogStoredJobSchema The complete public job lifecycle grammar.
constant WatchdogExecutionDecisionSchema Terminal decisions returned by the execution adapter.
constant WatchdogCancellationIntentSchema Durable cancellation requested by the enclosing owner.
constant WatchdogReadResultSchema Results returned by public job inspection.
constant WatchdogQueueHeadSchema Bounded current-work projection for one generic queue.
constant WatchdogIngestResultSchema Results returned by idempotent public ingest.
constant WatchdogCancellationResultSchema Results returned by durable cancellation recording.
constant watchdogSqliteValueSchema Scalar grammar shared by native SQLite adapters and their storage owners.
constant watchdogSqliteRowSchema A native row is a scalar record; each query owner decodes its own projection.
function makeRuntime()

WatchdogQueuedJobtype alias

Section titled “WatchdogQueuedJob”
Signature
type WatchdogQueuedJob = Schema.Schema.Type<typeof WatchdogQueuedJobSchema>;

Generic durable work waiting for execution.

WatchdogSettledJobtype alias

Section titled “WatchdogSettledJob”
Signature
type WatchdogSettledJob = Schema.Schema.Type<typeof WatchdogSettledJobSchema>;

Generic durable work with a terminal outcome.

WatchdogSettledRecordtype alias

Section titled “WatchdogSettledRecord”
Signature
type WatchdogSettledRecord = Readonly<{
  sequence: number;
  job: WatchdogSettledJob;
}>;

One bounded terminal-job recovery record with its durable ordering cursor.

WatchdogRunningJobtype alias

Section titled “WatchdogRunningJob”
Signature
type WatchdogRunningJob = Schema.Schema.Type<typeof WatchdogRunningJobSchema>;

Generic durable work held by Watchdog’s private claim.

WatchdogStoredJobtype alias

Section titled “WatchdogStoredJob”
Signature
type WatchdogStoredJob = Schema.Schema.Type<typeof WatchdogStoredJobSchema>;

Any publicly readable lifecycle state for a generic job.

WatchdogExecutionDecisiontype alias

Section titled “WatchdogExecutionDecision”
Signature
type WatchdogExecutionDecision = Schema.Schema.Type<
  typeof WatchdogExecutionDecisionSchema
>;

Terminal decision returned by the host executor.

WatchdogCancellationIntenttype alias

Section titled “WatchdogCancellationIntent”
Signature
type WatchdogCancellationIntent = Schema.Schema.Type<
  typeof WatchdogCancellationIntentSchema
>;

Owner-issued durable cancellation intent.

WatchdogCancellationDecisiontype alias

Section titled “WatchdogCancellationDecision”
Signature
type WatchdogCancellationDecision =
  | Readonly<{
      status: "recorded" | "replayed";
      intent: WatchdogCancellationIntent;
    }>
  | Readonly<{
      status: "conflict" | "missing";
    }>;

Result of recording an owner cancellation in its surrounding transaction.

WatchdogTransactionalProjectiontype alias

Section titled “WatchdogTransactionalProjection”
Signature
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.

WatchdogReadResulttype alias

Section titled “WatchdogReadResult”
Signature
type WatchdogReadResult = Schema.Schema.Type<typeof WatchdogReadResultSchema>;

Result of reading one generic job and its cancellation state.

WatchdogQueueHeadtype alias

Section titled “WatchdogQueueHead”
Signature
type WatchdogQueueHead = Schema.Schema.Type<typeof WatchdogQueueHeadSchema>;

Current queued or running job for one queue, excluding terminal history.

WatchdogQueueTransitiontype alias

Section titled “WatchdogQueueTransition”
Signature
type WatchdogQueueTransition = Readonly<{
  queue: string;
  head: WatchdogQueueHead;
  settled?: WatchdogSettledJob;
}>;

One queue’s state after a durable transition.

WatchdogQueueProjectortype alias

Section titled “WatchdogQueueProjector”
Signature
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

Section titled “Parameters”
Parameter Type
transition WatchdogQueueTransition

Returns

Section titled “Returns”

void

WatchdogIngestResulttype alias

Section titled “WatchdogIngestResult”
Signature
type WatchdogIngestResult = Schema.Schema.Type<
  typeof WatchdogIngestResultSchema
>;

Result of idempotent durable ingest.

WatchdogCancellationResulttype alias

Section titled “WatchdogCancellationResult”
Signature
type WatchdogCancellationResult = Schema.Schema.Type<
  typeof WatchdogCancellationResultSchema
>;

Result of recording a cancellation through the asynchronous runtime.

EffectWatchdogExecutortype alias

Section titled “EffectWatchdogExecutor”
Signature
type EffectWatchdogExecutor = Readonly<{
  execute: (job) => Effect.Effect<WatchdogExecutionDecision, WatchdogError>;
}>;

Effect-native host executor for one generic running job.

WatchdogSqliteValuetype alias

Section titled “WatchdogSqliteValue”
Signature
type WatchdogSqliteValue = Schema.Schema.Type<typeof watchdogSqliteValueSchema>;

Parsed native SQLite scalar shared by the durable storage adapters.

WatchdogSqliteRowtype alias

Section titled “WatchdogSqliteRow”
Signature
type WatchdogSqliteRow = Schema.Schema.Type<typeof watchdogSqliteRowSchema>;

Parsed scalar record; query-specific columns require their owner schema.

WatchdogSqliteCursortype alias

Section titled “WatchdogSqliteCursor”
Signature
type WatchdogSqliteCursor = Readonly<{
  toArray: () => readonly WatchdogSqliteRow[];
}>;

Structural result cursor required by Watchdog’s SQLite implementation.

WatchdogSqliteOwnertype alias

Section titled “WatchdogSqliteOwner”
Signature
type WatchdogSqliteOwner = Readonly<{
  sql: Readonly<{
    exec: (statement, ...bindings) => WatchdogSqliteCursor;
  }>;
  transactionSync: <A>(operation) => A;
}>;

Native owner-local SQLite capability consumed by Watchdog.

EffectWatchdogOptionstype alias

Section titled “EffectWatchdogOptions”
Signature
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.

WatchdogLivenessUnknowntype alias

Section titled “WatchdogLivenessUnknown”
Signature
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.

WatchdogTickResulttype alias

Section titled “WatchdogTickResult”
Signature
type WatchdogTickResult =
  | Readonly<{
      status: "busy";
    }>
  | Readonly<{
      status: "no_ready";
    }>
  | WatchdogLivenessUnknown
  | Readonly<{
      status: "settled";
      job: WatchdogSettledJob;
    }>;

Result of one bounded deep tick.

WatchdogLaneFailuretype alias

Section titled “WatchdogLaneFailure”
Signature
type WatchdogLaneFailure = Readonly<{
  lane: string;
  reason: string;
}>;

Owner-issued terminal lane refusal; reason is an owner code, at most 200 characters.

WatchdogLaneFailureResulttype alias

Section titled “WatchdogLaneFailureResult”
Signature
type WatchdogLaneFailureResult = Readonly<{
  settled: number;
  more: boolean;
}>;

One bounded refusal batch; call again only while more is true.

WatchdogRuntimeEffecttype alias

Section titled “WatchdogRuntimeEffect”
Signature
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.

ConcurrentWatchdogRuntimeEffecttype alias

Section titled “ConcurrentWatchdogRuntimeEffect”
Signature
type ConcurrentWatchdogRuntimeEffect = WatchdogRuntimeEffect &
  Readonly<{
    tickConcurrent: () => Effect.Effect<WatchdogTickResult, WatchdogError>;
  }>;

Runtime configured with one independent host lane at construction.

WatchdogQueuedJobSchemaconstant

Section titled “WatchdogQueuedJobSchema”
Signature
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.

WatchdogSettledJobSchemaconstant

Section titled “WatchdogSettledJobSchema”
Signature
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.

WatchdogRunningJobSchemaconstant

Section titled “WatchdogRunningJobSchema”
Signature
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.

WatchdogStoredJobSchemaconstant

Section titled “WatchdogStoredJobSchema”
Signature
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.

WatchdogExecutionDecisionSchemaconstant

Section titled “WatchdogExecutionDecisionSchema”
Signature
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.

WatchdogCancellationIntentSchemaconstant

Section titled “WatchdogCancellationIntentSchema”
Signature
const WatchdogCancellationIntentSchema: Struct<{
  jobId: String;
  cancellationId: String;
  onlyIfQueued: optional<Boolean>;
}>;

Durable cancellation requested by the enclosing owner.

WatchdogReadResultSchemaconstant

Section titled “WatchdogReadResultSchema”
Signature
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.

WatchdogQueueHeadSchemaconstant

Section titled “WatchdogQueueHeadSchema”
Signature
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.

WatchdogIngestResultSchemaconstant

Section titled “WatchdogIngestResultSchema”
Signature
const WatchdogIngestResultSchema: Union<
  readonly [
    Struct<{
      status: Literal<"queued">;
    }>,
    Struct<{
      status: Literal<"duplicate">;
    }>,
  ]
>;

Results returned by idempotent public ingest.

WatchdogCancellationResultSchemaconstant

Section titled “WatchdogCancellationResultSchema”
Signature
const WatchdogCancellationResultSchema: Union<
  readonly [
    Struct<{
      status: Literals<readonly ["recorded", "replayed"]>;
    }>,
    Struct<{
      status: Literals<readonly ["conflict", "missing"]>;
    }>,
  ]
>;

Results returned by durable cancellation recording.

watchdogSqliteValueSchemaconstant

Section titled “watchdogSqliteValueSchema”
Signature
const watchdogSqliteValueSchema: Union<
  readonly [instanceOf<ArrayBuffer, unknown>, String, Number, Null]
>;

Scalar grammar shared by native SQLite adapters and their storage owners.

watchdogSqliteRowSchemaconstant

Section titled “watchdogSqliteRowSchema”
Signature
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.

makeRuntime()function

Section titled “makeRuntime()”

Call Signature

Section titled “Call Signature”
Signature
function makeRuntime(
  options,
): Effect<ConcurrentWatchdogRuntimeEffect, WatchdogError>;

Construct two private single-flight slots over the same owner and job table.

Parameters

Section titled “Parameters”
Parameter Type
options Readonly<{ concurrentLane?: string; owner: WatchdogSqliteOwner; isAlive: (job) => Effect<boolean, WatchdogError>; executor: EffectWatchdogExecutor; wake: Readonly<{ recompute: () => Effect.Effect<void, WatchdogError>; }>; project?: WatchdogQueueProjector; }> & object

Returns

Section titled “Returns”

Effect<ConcurrentWatchdogRuntimeEffect, WatchdogError>

Call Signature

Section titled “Call Signature”
Signature
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

Section titled “Parameters”
Parameter Type
options EffectWatchdogOptions

Returns

Section titled “Returns”

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>