@fungi.computer/watchdog 0.0.0-stage → 0.0.1

package/docs/api/index.md

@@ -0,0 +1,421 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/watchdog**](README.md)
+
+---
+
+[@fungi.computer/watchdog](README.md) / index
+
+# index
+
+## Classes
+
+### WatchdogError
+
+Typed failures owned by the generic Watchdog engine.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new WatchdogError(failureKind, cause?): WatchdogError;
+```
+
+###### Parameters
+
+| Parameter     | Type                                                                                                                                                                          | Description                                                                                                                                |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `failureKind` | \| `"store_unavailable"` \| `"store_invalid"` \| `"claim_unavailable"` \| `"execution_failed"` \| `"settlement_rejected"` \| `"wake_unavailable"` \| `"liveness_unavailable"` | -                                                                                                                                          |
+| `cause?`      | `unknown`                                                                                                                                                                     | The original thrown value, kept for server-side diagnosis only. `cause` is already the closed category above, so this is a separate field. |
+
+###### Returns
+
+[`WatchdogError`](#watchdogerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### \_tag
+
+```ts
+readonly _tag: "WatchdogError";
+```
+
+##### cause
+
+```ts
+readonly cause:
+  | "store_unavailable"
+  | "store_invalid"
+  | "claim_unavailable"
+  | "execution_failed"
+  | "settlement_rejected"
+  | "wake_unavailable"
+  | "liveness_unavailable";
+```
+
+###### Overrides
+
+```ts
+Error.cause;
+```
+
+##### underlying?
+
+```ts
+readonly optional underlying?: unknown;
+```
+
+## Type Aliases
+
+### WatchdogExecutor
+
+```ts
+type WatchdogExecutor = (job, signal) => Promise<WatchdogExecutionDecision>;
+```
+
+Promise host executor for one generic running job.
+
+#### Parameters
+
+| Parameter | Type                                                 |
+| --------- | ---------------------------------------------------- |
+| `job`     | [`WatchdogRunningJob`](effect.md#watchdogrunningjob) |
+| `signal`  | `AbortSignal`                                        |
+
+#### Returns
+
+`Promise`\<[`WatchdogExecutionDecision`](effect.md#watchdogexecutiondecision)\>
+
+---
+
+### WatchdogOptions
+
+```ts
+type WatchdogOptions = Readonly<{
+  concurrentLane?: string;
+  owner: WatchdogSqliteOwner;
+  isAlive: (job) => Promise<boolean>;
+  execute: WatchdogExecutor;
+  wake: Readonly<{
+    recompute: () => Promise<void>;
+  }>;
+  project?: WatchdogQueueProjector;
+}>;
+```
+
+Options for constructing the Promise facade.
+
+---
+
+### WatchdogRuntime
+
+```ts
+type WatchdogRuntime = Readonly<{
+  hasPendingWork: () => Promise<boolean>;
+  ingest: (job) => Promise<WatchdogIngestResult>;
+  read: (jobId) => Promise<WatchdogReadResult>;
+  readQueueHead: (queue) => Promise<WatchdogQueueHead>;
+  tick: () => Promise<WatchdogTickResult>;
+  cancel: (input) => Promise<WatchdogCancellationResult>;
+  failLane: (input) => Promise<WatchdogLaneFailureResult>;
+  purge: (queue) => Promise<void>;
+  transactional: WatchdogTransactionalProjection;
+}>;
+```
+
+Promise facade over the canonical Effect runtime.
+
+---
+
+### ConcurrentWatchdogRuntime
+
+```ts
+type ConcurrentWatchdogRuntime = WatchdogRuntime &
+  Readonly<{
+    tickConcurrent: () => Promise<WatchdogTickResult>;
+  }>;
+```
+
+Promise runtime with the construction-time concurrent lane.
+
+---
+
+### WatchdogApi
+
+```ts
+type WatchdogApi = Readonly<{
+  make: {
+    (options): Promise<ConcurrentWatchdogRuntime>;
+    (options): Promise<
+      Readonly<{
+        hasPendingWork: () => Promise<boolean>;
+        ingest: (job) => Promise<WatchdogIngestResult>;
+        read: (jobId) => Promise<WatchdogReadResult>;
+        readQueueHead: (queue) => Promise<WatchdogQueueHead>;
+        tick: () => Promise<WatchdogTickResult>;
+        cancel: (input) => Promise<WatchdogCancellationResult>;
+        failLane: (input) => Promise<WatchdogLaneFailureResult>;
+        purge: (queue) => Promise<void>;
+        transactional: WatchdogTransactionalProjection;
+      }>
+    >;
+  };
+}>;
+```
+
+Factory for the Promise facade.
+
+## Variables
+
+### Watchdog
+
+```ts
+const Watchdog: WatchdogApi;
+```
+
+Promise facade over the canonical Effect-owned runtime.
+
+## References
+
+### WatchdogCancellationIntentSchema
+
+Re-exports
+[WatchdogCancellationIntentSchema](effect.md#watchdogcancellationintentschema)
+
+---
+
+### WatchdogCancellationResultSchema
+
+Re-exports
+[WatchdogCancellationResultSchema](effect.md#watchdogcancellationresultschema)
+
+---
+
+### WatchdogExecutionDecisionSchema
+
+Re-exports
+[WatchdogExecutionDecisionSchema](effect.md#watchdogexecutiondecisionschema)
+
+---
+
+### WatchdogIngestResultSchema
+
+Re-exports [WatchdogIngestResultSchema](effect.md#watchdogingestresultschema)
+
+---
+
+### WatchdogQueuedJobSchema
+
+Re-exports [WatchdogQueuedJobSchema](effect.md#watchdogqueuedjobschema)
+
+---
+
+### WatchdogQueueHeadSchema
+
+Re-exports [WatchdogQueueHeadSchema](effect.md#watchdogqueueheadschema)
+
+---
+
+### WatchdogReadResultSchema
+
+Re-exports [WatchdogReadResultSchema](effect.md#watchdogreadresultschema)
+
+---
+
+### WatchdogRunningJobSchema
+
+Re-exports [WatchdogRunningJobSchema](effect.md#watchdogrunningjobschema)
+
+---
+
+### WatchdogSettledJobSchema
+
+Re-exports [WatchdogSettledJobSchema](effect.md#watchdogsettledjobschema)
+
+---
+
+### WatchdogStoredJobSchema
+
+Re-exports [WatchdogStoredJobSchema](effect.md#watchdogstoredjobschema)
+
+---
+
+### EffectWatchdogOptions
+
+Re-exports [EffectWatchdogOptions](effect.md#effectwatchdogoptions)
+
+---
+
+### EffectWatchdogExecutor
+
+Re-exports [EffectWatchdogExecutor](effect.md#effectwatchdogexecutor)
+
+---
+
+### WatchdogCancellationDecision
+
+Re-exports
+[WatchdogCancellationDecision](effect.md#watchdogcancellationdecision)
+
+---
+
+### WatchdogCancellationIntent
+
+Re-exports [WatchdogCancellationIntent](effect.md#watchdogcancellationintent)
+
+---
+
+### WatchdogCancellationResult
+
+Re-exports [WatchdogCancellationResult](effect.md#watchdogcancellationresult)
+
+---
+
+### WatchdogExecutionDecision
+
+Re-exports [WatchdogExecutionDecision](effect.md#watchdogexecutiondecision)
+
+---
+
+### WatchdogIngestResult
+
+Re-exports [WatchdogIngestResult](effect.md#watchdogingestresult)
+
+---
+
+### WatchdogLivenessUnknown
+
+Re-exports [WatchdogLivenessUnknown](effect.md#watchdoglivenessunknown)
+
+---
+
+### WatchdogLaneFailure
+
+Re-exports [WatchdogLaneFailure](effect.md#watchdoglanefailure)
+
+---
+
+### WatchdogLaneFailureResult
+
+Re-exports [WatchdogLaneFailureResult](effect.md#watchdoglanefailureresult)
+
+---
+
+### WatchdogQueuedJob
+
+Re-exports [WatchdogQueuedJob](effect.md#watchdogqueuedjob)
+
+---
+
+### WatchdogQueueHead
+
+Re-exports [WatchdogQueueHead](effect.md#watchdogqueuehead)
+
+---
+
+### WatchdogQueueProjector
+
+Re-exports [WatchdogQueueProjector](effect.md#watchdogqueueprojector)
+
+---
+
+### WatchdogQueueTransition
+
+Re-exports [WatchdogQueueTransition](effect.md#watchdogqueuetransition)
+
+---
+
+### WatchdogReadResult
+
+Re-exports [WatchdogReadResult](effect.md#watchdogreadresult)
+
+---
+
+### WatchdogRunningJob
+
+Re-exports [WatchdogRunningJob](effect.md#watchdogrunningjob)
+
+---
+
+### WatchdogRuntimeEffect
+
+Re-exports [WatchdogRuntimeEffect](effect.md#watchdogruntimeeffect)
+
+---
+
+### ConcurrentWatchdogRuntimeEffect
+
+Re-exports
+[ConcurrentWatchdogRuntimeEffect](effect.md#concurrentwatchdogruntimeeffect)
+
+---
+
+### WatchdogSettledJob
+
+Re-exports [WatchdogSettledJob](effect.md#watchdogsettledjob)
+
+---
+
+### WatchdogSqliteCursor
+
+Re-exports [WatchdogSqliteCursor](effect.md#watchdogsqlitecursor)
+
+---
+
+### WatchdogSqliteOwner
+
+Re-exports [WatchdogSqliteOwner](effect.md#watchdogsqliteowner)
+
+---
+
+### WatchdogSqliteValue
+
+Re-exports [WatchdogSqliteValue](effect.md#watchdogsqlitevalue)
+
+---
+
+### WatchdogSqliteRow
+
+Re-exports [WatchdogSqliteRow](effect.md#watchdogsqliterow)
+
+---
+
+### WatchdogStoredJob
+
+Re-exports [WatchdogStoredJob](effect.md#watchdogstoredjob)
+
+---
+
+### WatchdogTickResult
+
+Re-exports [WatchdogTickResult](effect.md#watchdogtickresult)
+
+---
+
+### WatchdogTransactionalProjection
+
+Re-exports
+[WatchdogTransactionalProjection](effect.md#watchdogtransactionalprojection)
+
+---
+
+### watchdogSqliteValueSchema
+
+Re-exports [watchdogSqliteValueSchema](effect.md#watchdogsqlitevalueschema)
+
+---
+
+### watchdogSqliteRowSchema
+
+Re-exports [watchdogSqliteRowSchema](effect.md#watchdogsqliterowschema)

package/docs/api/node-sqlite.md

@@ -0,0 +1,57 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/watchdog**](README.md)
+
+---
+
+[@fungi.computer/watchdog](README.md) / node-sqlite
+
+# node-sqlite
+
+## Type Aliases
+
+### NodeSqliteCursor
+
+```ts
+type NodeSqliteCursor = WatchdogSqliteCursor &
+  Readonly<{
+    one: () => WatchdogSqliteRow;
+  }>;
+```
+
+Materialized Node SQLite rows, including the exact-one native operation.
+
+---
+
+### NodeSqliteOwner
+
+```ts
+type NodeSqliteOwner = Omit<WatchdogSqliteOwner, "sql"> &
+  Readonly<{
+    sql: Readonly<{
+      exec: (statement, ...bindings) => NodeSqliteCursor;
+    }>;
+  }>;
+```
+
+Concrete Node adapter; generic Watchdog owners need only toArray().
+
+## Functions
+
+### fromNodeSqlite()
+
+```ts
+function fromNodeSqlite(database): NodeSqliteOwner;
+```
+
+Adapt a caller-owned Node SQLite database; the caller retains its lifetime.
+
+#### Parameters
+
+| Parameter  | Type           |
+| ---------- | -------------- |
+| `database` | `DatabaseSync` |
+
+#### Returns
+
+[`NodeSqliteOwner`](#nodesqliteowner)

package/docs/api/postgres.md

@@ -0,0 +1,102 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/watchdog**](README.md)
+
+---
+
+[@fungi.computer/watchdog](README.md) / postgres
+
+# postgres
+
+## Type Aliases
+
+### PostgresWatchdog
+
+```ts
+type PostgresWatchdog = AsyncWatchdogRuntime &
+  Readonly<{
+    enqueue: (client, job) => Promise<void>;
+  }>;
+```
+
+PostgreSQL runtime with admission joined to the caller's checked-out client.
+
+---
+
+### PostgresPurgeStatement
+
+```ts
+type PostgresPurgeStatement = Readonly<{
+  text: string;
+  values: readonly (string | number | null)[];
+}>;
+```
+
+Parameterized queue purge joined to a producer's existing PostgreSQL
+transaction.
+
+## Variables
+
+### watchdogPostgresSchema
+
+```ts
+const watchdogPostgresSchema: readonly string[];
+```
+
+Package-owned schema statements, to run through the deployment migration owner.
+
+## Functions
+
+### createPostgresWatchdog()
+
+```ts
+function createPostgresWatchdog(options): PostgresWatchdog;
+```
+
+Open the shared Effect engine on a migrated PostgreSQL database.
+
+#### Parameters
+
+| Parameter | Type                                                                                                                                                                                                                                        |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` | `Readonly`\<\{ `execute`: [`WatchdogExecutor`](index.md#watchdogexecutor); `wake`: `Readonly`\<\{ `recompute`: () => `Promise`\<`void`\>; \}\>; `now?`: () => `number`; \}\> & `Readonly`\<\{ `database`: `Pick`\<`Pool`, `"query"`\>; \}\> |
+
+#### Returns
+
+[`PostgresWatchdog`](#postgreswatchdog)
+
+---
+
+### purgePostgresQueues()
+
+```ts
+function purgePostgresQueues(source): readonly Readonly<{
+  text: string;
+  values: readonly (string | number | null)[];
+}>[];
+```
+
+Purge every attempt in the queues yielded by trusted producer SQL.
+
+#### Parameters
+
+| Parameter | Type                                                |
+| --------- | --------------------------------------------------- |
+| `source`  | [`PostgresPurgeStatement`](#postgrespurgestatement) |
+
+#### Returns
+
+readonly `Readonly`\<\{ `text`: `string`; `values`: readonly (`string` \|
+`number` \| `null`)[]; \}\>[]
+
+## References
+
+### AsyncWatchdogOptions
+
+Re-exports [AsyncWatchdogOptions](d1.md#asyncwatchdogoptions)
+
+---
+
+### AsyncWatchdogRuntime
+
+Re-exports [AsyncWatchdogRuntime](d1.md#asyncwatchdogruntime)

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@fungi.computer/watchdog",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "author": "Levi <levi@technomancy.dev>",
+  "description": "Payload-blind durable work scheduling and settlement core",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./effect": {
+      "types": "./dist/effect.d.ts",
+      "import": "./dist/effect.js"
+    },
+    "./d1": {
+      "types": "./dist/d1.d.ts",
+      "import": "./dist/d1.js"
+    },
+    "./postgres": {
+      "types": "./dist/postgres.d.ts",
+      "import": "./dist/postgres.js"
+    },
+    "./node-sqlite": {
+      "types": "./dist/node-sqlite.d.ts",
+      "import": "./dist/node-sqlite.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/api",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@fungi.computer/cairn": "0.0.1",
+    "effect": "4.0.2",
+    "@cloudflare/workers-types": "5.20260828.1",
+    "pg": "8.23.0",
+    "@types/pg": "8.23.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "botanical": {
+    "role": "package",
+    "operations": {
+      "lint": "required",
+      "typecheck": "required",
+      "build": "required",
+      "test": "required",
+      "docs": "required",
+      "pack": "required",
+      "smoke": "required",
+      "stranger": "required"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/watchdog.git"
+  },
+  "scripts": {
+    "lint": "eslint src test --max-warnings=0 && ../../node_modules/.bin/oxlint --config ../../oxlint.config.ts --deny-warnings src test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "clean": "node --input-type=module --eval \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+    "test": "vitest run",
+    "docs": "tsx ../../tooling/repository/src/docs/cli.ts check --root ../..",
+    "docs:write": "tsx ../../tooling/repository/src/docs/cli.ts write --root ../..",
+    "pack": "mkdir -p ../../.botanical/watchdog-pack && pnpm pack --pack-destination ../../.botanical/watchdog-pack",
+    "smoke": "node --input-type=module -e \"import('./dist/index.js').then(({Watchdog}) => { if (!Watchdog) process.exit(1); })\"",
+    "stranger": "tsx ../../tooling/repository/src/artifacts/cli.ts --repo-root ../.. .",
+    "format:check": "node ../../tooling/repository/scripts/format-package-check.mjs",
+    "lint:anti-slop": "node ../../tooling/repository/scripts/lint-package-anti-slop.mjs"
+  }
 }