@ayepi/work 0.1.0 → 0.2.0

package/README.md

@@ -15,7 +15,7 @@ pnpm add @ayepi/work
 ```ts
 import { defineWork, createWork } from '@ayepi/work'
 
-const add = defineWork('add', (i: { a: number; b: number }) => i.a + i.b)
+const add = defineWork('add', (i: { a: number; b: number }, ctx) => ctx.result(i.a + i.b))
 const w = createWork({ work: [add] as const })
 
 const sum = await w.enqueue(add({ a: 1, b: 2 })).result() // 3, typed as number
@@ -24,11 +24,20 @@ await w.stop()
 
 Bare `import` has **no side effects** — the default instance does not auto-start.
 
+## Handlers return a `WorkResult`
+
+A handler **returns a `WorkResult`** describing what it produced:
+
+- **`ctx.result(value, opts?)`** — contribute a value (its own `.result()` and the group). `opts`: `{ final }` locks the group result; `{ append }` accumulates.
+- **`ctx.queue(items, opts?)`** — run sub-work (built `Work`s and/or nested results) in the same group; the work **delegates** (its `.result()` is `void`).
+- **`ctx.void()`** — contribute nothing.
+- **`.next(works, condition?, opts?)`** — a native dependency: queue `works` once the prior items satisfy `condition` (default `'all-success'`).
+
+Each work then carries two inferred types — its *awaited-alone* result `S` (`.result()`) and its *group* contribution `G` (`.group()` / awaiting the handle). So `enqueue(root).group()` resolves to a **precise union from the workflow structure**, not the whole registry.
+
 ## Type safety
 
-`defineWork(name, handler, opts?)` returns a **callable builder** typed by its input and
-output. Pass a `const` tuple of builders to `createWork`, and both `enqueue` forms are
-checked:
+`defineWork(name, handler, opts?)` returns a **callable builder** typed by its input and the `WorkResult` it returns. Pass a `const` tuple to `createWork`, and both `enqueue` forms are checked:
 
 ```ts
 w.enqueue(add({ a: 1, b: 2 }))      // instance form
@@ -36,24 +45,27 @@ w.enqueue('add', { a: 1, b: 2 })    // name form (name ∈ registry, input typed
 add({ a: 1 })                       // ✗ type error: missing `b`
 ```
 
-Awaiting a handle resolves to the **group result** — the union of the registry's non-void
-outputs (`GroupResult<Defs>`). `.result()` resolves this item's own output; `.group()` is
-the explicit group form.
+## Groups & workflows
 
-## Groups & context
-
-A handler receives a `ctx`. `ctx.queue(child(input))` queues child work **into the same
-group** (so awaiting the group waits for the children); `ctx.setResult(value)` records the
-group's result.
+`ctx.queue` composes sub-work into the same group; a returned tree is a workflow whose group
+type is the precise union of its parts. `.next` adds native dependencies, and `ctx.result`
+(with `final`/`append`) shapes the group's value (default: **last contributor to finish**).
 
 ```ts
-const root = defineWork('root', (i: { ids: string[] }, ctx) => {
-  for (const id of i.ids) ctx.queue(process({ id }))
-  ctx.setResult({ queued: i.ids.length })
-})
-const out = await w.enqueue(root({ ids: ['a', 'b'] })) // resolves after both children settle
+const fetch = defineWork('fetch', (i: { id: string }, ctx) => ctx.result(load(i.id)))
+const report = defineWork('report', (_i, ctx) => ctx.result(summary()))
+const root = defineWork('root', (i: { ids: string[] }, ctx) =>
+  ctx.queue(i.ids.map((id) => fetch({ id }))).next([report({})], 'all-success'),
+)
+const out = await w.enqueue(root({ ids: ['a', 'b'] })) // typed: fetch's | report's output
 ```
 
+Per-work `ctx`: `id`, `groupId`, `attempt`, `parent` (who queued it), `dependents` (ids it
+depended on). A handler must **return** every `ctx.queue`/`result`/`void` it creates — an
+un-returned one throws (opt out with `strictReturn: false`). Set `deadline`/`timeout` to make
+an item that doesn't start+finish in time go terminal with an `'expired'` event. `setIdGenerator`
+overrides how work ids are minted.
+
 ## Instance options, retries, delay
 
 `delay`, `retry`, `priority`, and `group` are **per-instance options** — passed at queue
@@ -199,7 +211,7 @@ This package ships dense, machine-oriented reference docs written for **AI codin
 - [`ayepi-work-ports.md`](./ayepi-work-ports.md)
 - [`ayepi-work.md`](./ayepi-work.md)
 
-They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/work) and are **not** shipped in the npm tarball.
+They ship with this package and also live in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/work).
 
 ## License
 

package/ayepi-work-deps-schedule.md

@@ -0,0 +1,312 @@
+<!--
+ayepi-work-deps-schedule.md — reference for `@ayepi/work` (dependencies & scheduling), written for coding agents.
+
+Copy this file into any project that depends on `@ayepi/work` (e.g. into your repo's
+`docs/` or `.claude/` directory) and reference it from your agents and slash commands.
+It documents the public API, the patterns the package expects, and how it works under the
+hood, with copy-pasteable examples. Keep it in sync with the installed package version.
+-->
+
+# `@ayepi/work` — dependencies & scheduling
+
+Part of the `@ayepi/work` doc set. See [`ayepi-work.md`](./ayepi-work.md) for the core
+API and [`ayepi-work-ports.md`](./ayepi-work-ports.md) for ports/codec. All durations are
+**milliseconds**.
+
+---
+
+## Dependencies (fan-in gates)
+
+A dependency is **itself a work item** — you enqueue it like anything else, often
+alongside the works it waits `on`. It lives on the durable queue (so it survives a crash),
+and its handler is **non-blocking**: each run reads the watched items' states and either
+fires (queues its dependents, once) or **re-queues itself** with a small delay to check
+again later. It never holds a worker slot waiting, so a backlog of dependencies can't
+starve other work.
+
+> **Prefer the native `.next` chain** ([below](#native-dependencies--next)) when you're
+> building a workflow inside a handler — `ctx.queue([a, b]).next([c], 'all-success')` is the
+> ergonomic form and widens the group type by `c`'s contribution. Reach for `dependency(...)`
+> directly when you want to enqueue a standalone gate (e.g. alongside works at the top level).
+
+### `dependency(opts)`
+
+```ts
+function dependency(opts: DependencyOptions): Work<DEPENDENCY_TYPE, void, void>
+
+interface DependencyOptions {
+  readonly on: readonly (string | Work)[]   // works (or their ids) to wait on
+  readonly queue: readonly Work[]            // works to queue (into the same group) once satisfied
+  readonly config?: DependencyCondition      // when to fire (default 'all-success')
+  readonly poll?: number                     // re-check interval ms (default 1000)
+  readonly timeout?: number                  // give up (dead-letter) after this long (ms)
+}
+```
+
+The built-in type name is exported as `DEPENDENCY_TYPE` (`'@work/dependency'`). Every work
+system **auto-registers** the dependency handler — you never define it yourself.
+
+### `DependencyCondition`
+
+JSON-serializable, so the dependency evaluates identically on any instance:
+
+```ts
+type DependencyCondition =
+  | 'all-done'                                   // every watched item reached a terminal state
+  | 'all-success'                                // every watched item succeeded
+  | { readonly count: number; readonly of?: 'done' | 'success' } // ≥ count reached the state ('done' default)
+```
+
+Terminal states are `success`, `failed`, `dead`. `'done'` means any terminal state;
+`'success'` means specifically succeeded.
+
+### `conditionMet(condition, states)`
+
+The pure evaluator, exported for testing/inspection. A **missing** state counts as
+"not yet done":
+
+```ts
+function conditionMet(condition: DependencyCondition, states: readonly (WorkState | undefined)[]): boolean
+```
+
+```ts
+import { conditionMet } from '@ayepi/work'
+
+conditionMet('all-done', [stSuccess, stDead])                  // true
+conditionMet('all-success', [stSuccess, stDead])               // false
+conditionMet({ count: 2 }, [stSuccess, stFailed, undefined])   // true
+conditionMet({ count: 2, of: 'success' }, [stSuccess, stDead]) // false
+```
+
+### Example: a dependency-gated finalizer
+
+Enqueue the dependency alongside the works it waits on. Awaiting the dependency's handle
+resolves once its queued dependents (in the same group) finish:
+
+```ts
+import { defineWork, createWork, dependency } from '@ayepi/work'
+
+const stepA = defineWork('stepA', (_i, ctx) => ctx.result('a'))
+const stepB = defineWork('stepB', (_i, ctx) => ctx.result('b'))
+const finalize = defineWork('finalize', (_i, ctx) => ctx.void()) // runs once both steps succeed
+
+const w = createWork({ work: [stepA, stepB, finalize] as const })
+
+const a = stepA({}) // ids assigned at build time
+const b = stepB({})
+w.enqueue(a)
+w.enqueue(b)
+const gate = w.enqueue(dependency({
+  on: [a, b],                  // accepts Work instances or string ids
+  queue: [finalize({})],       // queued into the gate's group once satisfied
+  config: 'all-success',
+  poll: 10,
+}))
+await gate // settles after the queued finalize() completes
+```
+
+You can also queue everything together inside a handler — **return** the result so it runs
+(and so the group type reflects it):
+
+```ts
+const root = defineWork('root', (_i, ctx) => {
+  const a = stepA(), b = stepB()
+  return ctx.queue([a, b, dependency({ on: [a, b], queue: [finalize()], config: 'all-success' })])
+})
+```
+
+But the **native `.next` chain** says the same thing more directly (and types the group):
+
+```ts
+const root = defineWork('root', (_i, ctx) =>
+  ctx.queue([stepA(), stepB()]).next([finalize()], 'all-success'),
+)
+```
+
+### Timeouts
+
+With `timeout`, the dependency records an absolute deadline (`Date.now() + timeout`) at
+build time. If the condition never holds, the dependency **dead-letters** past the deadline
+(it does not retry — `DEP_RETRY_ATTEMPTS = 1`), and its dependents are never queued.
+
+```ts
+w.enqueue(dependency({ on: ['never-runs'], queue: [after({})], config: 'all-success', poll: 10, timeout: 30 }))
+// after ~30ms the dependency dead-letters; `after` never runs
+```
+
+### How dependencies work under the hood
+
+- **Fire-once.** Before queueing dependents, the handler does
+  `ctx.claim('dep:<key>:fired')` (a `Store.setIfNotExists`). The `key` is stable across the
+  dependency's self-re-queues and redeliveries, so dependents queue **exactly once** across
+  a multi-pod fleet.
+- **Non-blocking re-queue.** When not yet satisfied, the handler queues a fresh copy of
+  itself (same `key`, fresh queue id) with `{ delay: poll }`, so it never blocks a slot.
+- **Remembered terminal statuses.** The input carries a `resolved` map of terminal statuses
+  already observed, carried forward across self-re-queues. This lets the dependency skip
+  re-reading settled works **and** avoid mistaking a since-evicted state (results expire
+  after 24 h) for a failure.
+- It reads watched states via `ctx.states(ids)`, which reads from the shared store
+  (cross-instance).
+
+Exported dependency symbols: `dependency`, `conditionMet`, `DEPENDENCY_TYPE`, and the
+`DependencyOptions` type.
+
+---
+
+## Native dependencies — `.next`
+
+A `WorkResult` (what a handler returns) has a **`.next`** method — the ergonomic, typed form
+of a fan-in `dependency`. It queues the next works once the works the prior result queued
+satisfy a condition, and **widens the group type** by what those next works contribute:
+
+```ts
+next<Ns>(next: Ns, condition?: DependencyCondition, options?: WorkInstanceOptions): WorkResult<S, G | GroupOf<Ns>>
+```
+
+```ts
+const fetch = defineWork('fetch', (i: { id: string }, ctx) => ctx.result(load(i.id)))   // string
+const report = defineWork('report', (_i, ctx) => ctx.result(makeReport()))              // Report
+const flow = defineWork('flow', (i: { ids: string[] }, ctx) =>
+  ctx.queue(i.ids.map((id) => fetch({ id })))      // run all fetches in the group …
+    .next([report({})], 'all-success'),            // … then report once they all succeed
+)
+// enqueue(flow(...)).group()  →  string | Report   (the structural union)
+```
+
+- The method is **`.next`**, *not* `.then` — a `then` member would make the `WorkResult` a
+  *thenable*, and the engine's `Promise.resolve(...)` of the handler's return would try to
+  adopt/await it.
+- `condition` defaults to `'all-success'` and accepts the full `DependencyCondition` above.
+- `.next` **chains**: `ctx.queue([a]).next([b], cond).next([c], cond2)` runs `c` after `b`'s
+  cohort satisfies `cond2`. Each link is a real `dependency` work under the hood (so it's
+  durable and fires exactly once), with the prior link's queued works as its `on` set.
+- Works queued by a fired `.next` (or `dependency`) see `ctx.dependents` = the ids that gate
+  was waiting `on`; works queued by `ctx.queue` see `ctx.parent` = the queuing work's id.
+- `options` is the usual `WorkInstanceOptions` (e.g. `{ priority }`) applied to the next
+  works. A `.next` you build but **don't return** trips strict-return (see
+  [the handler contract](./ayepi-work.md#the-handler-contract--returning-a-workresult)).
+
+---
+
+## Scheduling
+
+Register a recurring schedule with `w.schedule(config)`. It fires on either a **5-field
+cron expression** or a **next-time function**, and returns a cancel function. One instance
+fires per occurrence (a `setIfNotExists` lease keyed by the fire time), so a cron never
+double-fires across a fleet.
+
+### `ScheduleConfig`
+
+```ts
+interface ScheduleConfig {
+  readonly name: string                                  // unique; also the firing-lease key
+  readonly cron?: string                                 // 5-field cron — mutually exclusive with `next`
+  readonly next?: (now: number) => number | Date | void  // compute next fire time; void to stop
+  readonly run: () => Work | void                        // produce the work to enqueue (or enqueue yourself + return void)
+}
+
+// w.schedule(config: ScheduleConfig): () => void   // returns a cancel function
+```
+
+### Example: cron + fn schedules
+
+```ts
+// cron: every day at 03:00 (local time)
+const cancelNightly = w.schedule({ name: 'nightly', cron: '0 3 * * *', run: () => report({}) })
+
+// fn: every 60 seconds
+const cancelTick = w.schedule({ name: 'tick', next: (now) => now + 60_000, run: () => poll({}) })
+
+cancelNightly() // stop the schedule
+```
+
+`run` returns a `Work` to enqueue it, or does its own enqueueing and returns `void`. A
+`next` that returns `undefined`/`null` stops the schedule.
+
+### The cron parser — `parseCron` / `nextAfter`
+
+The dependency-free 5-field cron parser is exported for direct use:
+
+```ts
+function parseCron(expr: string): CronFields            // throws on malformed expressions
+function nextAfter(expr: string, fromMs: number): number | undefined  // next match strictly after fromMs
+```
+
+Format is `min hour dom mon dow`:
+
+| Field | Range | Notes |
+|---|---|---|
+| minute | 0–59 | |
+| hour | 0–23 | |
+| day of month | 1–31 | |
+| month | 1–12 | |
+| day of week | 0–6 | 0 = Sunday |
+
+Each field supports `*`, a number, an `a-b` range, a `<range>/<step>` step, and
+comma-lists (e.g. `*/15`, `1-5`, `0,30`). When **both** day-of-month and day-of-week are
+restricted (not `*`), standard cron **OR** semantics apply (matches either).
+
+```ts
+import { parseCron, nextAfter } from '@ayepi/work'
+
+parseCron('*/15 0 * * 1-5')             // ok
+parseCron('* * * *')                     // throws: expected 5 fields
+nextAfter('* * * * *', Date.now())       // top of the next minute (epoch ms)
+nextAfter('0 0 30 2 *', Date.now())      // undefined — Feb 30 never matches within ~a year
+```
+
+Notes & constraints:
+- **Minute-granular.** Cron's resolution is one minute; `nextAfter` returns the top of a
+  matching minute.
+- **Local time.** Matching uses local `Date` getters (`getHours`, `getDay`, …), not UTC.
+- **Bounded scan.** `nextAfter` scans at most ~1 year (`366 * 24 * 60` minutes) forward;
+  a never-matching expression returns `undefined`.
+
+### One-off scheduling — `runAt` & handler-thrown `WorkDelayError`
+
+`w.schedule` is for **recurring** work. For a **one-off** future run, enqueue with an absolute
+time instead — `enqueue(work, { runAt })` (epoch ms). `runAt` is an alternative to `delay` and
+wins over it.
+
+```ts
+// run once, far in the future
+w.enqueue(report({ day }), { runAt: Date.parse('2030-01-01T03:00:00Z') })
+```
+
+A running handler can also **defer its own item** to a later time by throwing `WorkDelayError`
+— a **reschedule, not a retry**, so the `attempt` count is unchanged and a handler can defer
+indefinitely (poll-style "not ready yet, try me later"):
+
+```ts
+import { WorkDelayError } from '@ayepi/work'
+
+const poll = defineWork('poll', async (input, ctx) => {
+  if (!(await upstreamReady())) throw new WorkDelayError({ delay: 5 * 60_000 }) // re-run in 5 min, same attempt
+  return ctx.result(await doWork(input))
+})
+```
+
+`WorkDelayError`'s `when` takes `{ runAt }` (absolute, wins) or `{ delay }` (relative ms).
+The deferral re-enqueues the item at the resolved time and emits a `deferred` event. See
+[`ayepi-work.md` → Deferral & scheduling](./ayepi-work.md#deferral--scheduling) for details.
+
+**Far-future works on any backend.** Both `runAt` and a `WorkDelayError` deferral resolve to a
+`startAt`. A backend that can't honor a long single delay (e.g. SQS caps `DelaySeconds` at
+15 min) hands the item back early; the engine re-checks `startAt` on pop and **re-defers**
+until it's actually due, so an item scheduled arbitrarily far out still fires at the right time
+(see [`ayepi-work-ports.md` → Early-arrival re-defer](./ayepi-work-ports.md#early-arrival-re-defer-far-future-scheduling)).
+
+### How scheduling works under the hood
+
+A ~1 s tick (`SCHED_TICK = 1000`) checks whether the next fire time has arrived. When it
+has, the instance tries to claim a `setIfNotExists` lease at
+`<prefix>sched:<name>:<second-bucket>` (TTL `SCHED_LEASE_TTL = 90_000`). The instance that
+wins the lease calls `run()` and enqueues the result; the next fire time is then recomputed.
+Because the lease is keyed by the fire's second-bucket, exactly one instance fires per
+occurrence across the fleet.
+
+---
+
+See also: [`ayepi-work.md`](./ayepi-work.md) (core API, groups, retries, "how it works")
+and [`ayepi-work-ports.md`](./ayepi-work-ports.md) (ports, custom backends, JSON codec).