@kairos-es/codec 1.0.0-alpha.1 → 1.0.0-alpha.2

package/src/decision.ts

@@ -0,0 +1,174 @@
+/**
+ * `Unchanged`: a decision's answer when there is nothing to do because the work
+ * is already done, and the two types that let a decision say so without costing
+ * any existing caller its `Position`.
+ *
+ * ## Why a decision needs a third answer
+ *
+ * A decision had two answers: a non-empty batch of events to append, or a
+ * failure. The idempotent case fitted neither. A webhook redelivered after its
+ * first delivery was recorded, or a recorder re-running after a conflict whose
+ * winning write already closed the item, has nothing to append — and nothing
+ * WRONG has happened, so a failure is the wrong channel: a caller would have to
+ * tell "already done" from a genuine refusal by matching a tag, and a retry
+ * policy keyed on the error channel would retry a success. An empty batch is not
+ * the answer either. `append` refuses one as a defect, and the `Decider`'s
+ * `NonEmptyReadonlyArray` bound is what makes that refusal unreachable from a
+ * decision, a guarantee `decider.ts` calls load-bearing. So "already done" gets a
+ * value of its own, and it is a SUCCESS: an idempotent skip is never retried.
+ *
+ * ## Why it is recognised by a type id, and never by `instanceof` or a `_tag`
+ *
+ * This package ships dual ESM/CJS, so one consumer's graph can hold two copies of
+ * this module and therefore two distinct `Unchanged` classes. Under `instanceof`,
+ * a value built by one copy fails the other's check, and the runner would treat
+ * "already done" as a batch and hand it to `append` — the same single point of
+ * silent failure `@kairos-es/core` argues against, in its contract store, for
+ * `AppendConditionFailed`. That error falls back on its `_tag`, and a tag is
+ * enough there because the error channel is the library's own. A DECISION's
+ * success channel is not: an application's own union may well carry a member
+ * tagged `'Unchanged'`, and a runner that skipped on the bare tag would swallow
+ * that value and append nothing, silently. `Symbol.for` gives an identity that is
+ * shared across both builds (the global symbol registry is per runtime, not per
+ * module copy) and that no application value carries by accident. `isUnchanged`
+ * is the one test, and every runner in this package uses it.
+ *
+ * ## Why the widening is a defaulted type parameter, not a second entry point
+ *
+ * `Decider` gains a fifth type parameter `O`, defaulting to the non-empty batch.
+ * A second entry point would have meant a second `Decider`, a second runner, a
+ * second `transact` and a second `decideOnly` — against a surface whose whole
+ * argument is that `runDecider` and `decideOnly` are ONE pair.
+ *
+ * ## Why `DecisionResult` is shaped as it is, and why `decider` is overloaded
+ *
+ * The promise is that a decider or body that cannot answer `Unchanged` keeps
+ * exactly the `Position` result it had. Two kinds of success make that harder
+ * than it looks, and both were measured against call shapes that compiled
+ * before the widening.
+ *
+ * - An UNTYPED success. `any` satisfies every question a conditional can ask of
+ *   it: `Unchanged extends any` holds, and `any extends Unchanged` takes BOTH
+ *   branches. So a decision nobody typed would read as one that can answer
+ *   `Unchanged`, and its caller's `(position: Position) => …` would stop
+ *   compiling. `DecisionResult` therefore checks for `any` FIRST, and answers
+ *   `Position`.
+ * - A GENERIC success. In a wrapper generic in the success type
+ *   (`<A extends NonEmptyReadonlyArray<DcbEvent>, …>`), a conditional over `A`
+ *   stays DEFERRED, and a deferred conditional is `Position` only if the checker
+ *   can see that it must be. It can for one shape and not for the other:
+ *   `Unchanged extends O ? …` is related through the union of its two branches,
+ *   which admits `Unchanged`; `O extends Unchanged ? …`, DISTRIBUTIVE over `O`,
+ *   is related through itself instantiated at `O`'s bound — and at a bound of
+ *   the non-empty batch that is `Position`. So `DecisionResult` is written the
+ *   second way, and `runDecider` and `transact` keep ONE signature each, which
+ *   is what lets `body.pipe(transact(p))` still infer its error and requirement
+ *   channels; an overloaded step would lose both to `unknown`.
+ *
+ * `decider(…)` cannot be served by a conditional at all. Its `O` is derived from
+ * the SUCCESS of an effect type variable, and `Effect.Effect.Success` of a type
+ * variable is itself deferred, so a wrapper that copies `decider`'s own generics
+ * would get a `Decider` whose `O` nothing can resolve, and a runner result that
+ * is not `Position`. So `decider` is declared TWICE, which asks the question by
+ * ASSIGNABILITY instead: FIRST for an effect whose success is the non-empty
+ * batch, returning a `Decider` with the default `O`, and only then for any
+ * `DecisionOutput`, returning one whose `O` is `DecisionOutput`. A type
+ * variable bounded by the batch fits the first, and so does `any`; a `decide`
+ * with a branch answering `Unchanged` does not, and falls through to the second.
+ * Keep that ORDER: the checker takes the first declaration that fits, so
+ * swapped, every decider would be widened.
+ *
+ * Neither reaches a type QUERY. `ReturnType<typeof runDecider>` reads `O` at its
+ * bound, which admits `Unchanged`, so its success is widened; instantiated
+ * (`typeof runDecider<P, Command, E, R>`), `O` takes its default and the answer
+ * is `Position` again. `ReturnType<typeof decider<…>>` reads the LAST
+ * declaration, so it is the widened `Decider` whatever effect type it is given;
+ * a decider VALUE is typed by the declaration that fitted it.
+ *
+ * `DecisionOutput` still refuses a possibly-empty array — a `DcbEvent[]` from a
+ * `filter`, say — at compile time, because a plain array is neither non-empty nor
+ * `Unchanged`. The widening adds an answer; it removes no guarantee.
+ */
+import type { DcbEvent, Position } from '@kairos-es/core'
+import { type Array as Arr, Data, Predicate } from 'effect'
+
+/**
+ * The type id `isUnchanged` recognises. `Symbol.for`, so both halves of the dual
+ * build — and any two copies of this package in one graph — agree on it.
+ */
+export const UnchangedTypeId: unique symbol = Symbol.for(
+  '@kairos-es/codec/Unchanged',
+)
+
+/** The type of `UnchangedTypeId`. */
+export type UnchangedTypeId = typeof UnchangedTypeId
+
+/**
+ * "Nothing to do: this work is already done." A runner that receives it appends
+ * nothing and returns it in place of a `Position`.
+ *
+ * `reason` is for a human reading a trace or a test failure, and nothing in the
+ * library reads it. A `Data.TaggedClass`, so two values with the same reason are
+ * `Equal` and a test can compare them structurally.
+ *
+ * ⚠ Test for it with `isUnchanged`, never with `instanceof` or `_tag` — the
+ * module documentation says why each of those is wrong.
+ */
+export class Unchanged extends Data.TaggedClass('Unchanged')<{
+  readonly reason?: string
+}> {
+  readonly [UnchangedTypeId]: UnchangedTypeId = UnchangedTypeId
+}
+
+/**
+ * Whether `u` is an `Unchanged`, by its type id. Total over `unknown`, and
+ * realm-safe across the dual ESM/CJS build. An application value that merely
+ * carries `_tag: 'Unchanged'` answers `false`, deliberately.
+ */
+export const isUnchanged = (u: unknown): u is Unchanged =>
+  Predicate.hasProperty(u, UnchangedTypeId)
+
+/**
+ * The constructors a `decide` step reaches for. One member today; it is a
+ * namespace object rather than a bare function so the call site reads as what it
+ * is, `Decision.unchanged('already dispatched')`.
+ */
+export const Decision: {
+  readonly unchanged: (reason?: string) => Unchanged
+} = {
+  unchanged: (reason) => new Unchanged(reason === undefined ? {} : { reason }),
+}
+
+/**
+ * Everything a decision may succeed with: a non-empty batch of events to
+ * append, or `Unchanged`. A plain, possibly-empty array is NOT a member, which is
+ * what keeps an empty batch unreachable from a decision.
+ */
+export type DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent> | Unchanged
+
+/**
+ * What a runner returns for a decision that succeeds with `O`: `Position` unless
+ * `O` admits `Unchanged`, and `Position | Unchanged` when it does.
+ *
+ * Asked of each member of `O` — DISTRIBUTIVE — so a union `O` answers
+ * `Position | Unchanged` exactly when one of its members is `Unchanged`, a batch
+ * answers `Position` with no `| never` residue, and an `O` that is a type
+ * variable bounded by the batch is seen to be `Position`, which is what a
+ * wrapper generic in its success type needs. `O` that can ONLY be `Unchanged`
+ * answers `Unchanged`, the precise result and assignable wherever
+ * `Position | Unchanged` is expected.
+ *
+ * Two members are checked BEFORE the distribution, and both answer `Position`,
+ * the result each had before `Unchanged` existed. `any`, because a distributive
+ * conditional over `any` takes both branches and would widen every untyped
+ * decision. And `never` — a body that only ever fails — because distributing
+ * over `never` answers `never`, which a variable once typed with a `Position`
+ * result would no longer accept. The module documentation owns the rest.
+ */
+export type DecisionResult<O> = 0 extends 1 & O
+  ? Position
+  : [O] extends [never]
+    ? Position
+    : O extends Unchanged
+      ? Unchanged
+      : Position

package/src/index.ts

@@ -34,6 +34,17 @@
  * error union are written once, in the two function bodies, rather than restated
  * as an annotation above them.
  *
+ * A decision may also answer `Unchanged` — "already done, nothing to append" —
+ * built with `Decision.unchanged(reason?)` and recognised ONLY by
+ * `isUnchanged`, by its `UnchangedTypeId`. It is a success, not an error and not
+ * an empty batch: every runner returns it in place of a `Position` and appends
+ * nothing. `Decider`'s fifth type parameter carries the widening and defaults to
+ * the non-empty batch, and each runner's result is `DecisionResult<O>`, so a
+ * decider or body that cannot answer `Unchanged` keeps a plain `Position` — an
+ * untyped one and one generic in its success type included — and its caller is
+ * never asked to handle it. `decision.ts` owns the argument, and the one type
+ * query that does read differently.
+ *
  * `transact(precondition)(body)` is the layered write path, for a decision whose
  * second query cannot be written until an earlier read has been folded. It opens
  * an ambient read ledger, evaluates the precondition inside it, hands that
@@ -54,6 +65,12 @@
  * | `runDecider` | ✅ the ordinary single-hop case           | ⛔ a DEFECT, refused at the store    |
  * | `decideOnly` | ⛔ unrunnable, and `tsc` says so          | ✅ the layered case                  |
  *
+ * Both carry `Unchanged` the same way, which is what keeps them one pair:
+ * `runDecider` returns it having appended nothing, and `decideOnly` passes it to
+ * the body unaltered, where `transact` returns it having appended nothing —
+ * and, having no write to guard, without refusing an empty bracket as
+ * `NoReadsRecorded`.
+ *
  * ⚠ *Unrunnable* rather than *unwritable*, and the difference is measured. A bare
  * `decideOnly(d, cmd)` outside a bracket COMPILES, and so does an exported helper
  * over it: its `ReadLedger` requirement simply propagates, as any unmet requirement
@@ -101,6 +118,14 @@
  */
 
 export { type Decider, decider, runDecider } from './decider'
+export {
+  Decision,
+  type DecisionOutput,
+  type DecisionResult,
+  isUnchanged,
+  Unchanged,
+  UnchangedTypeId,
+} from './decision'
 export {
   buildDecisionModel,
   modelAtHead,

package/src/precondition.ts

@@ -24,6 +24,21 @@
  * ⚠ The name says *declare, then do*. It is NOT a database transaction: an append
  * under a condition is not two-phase, and nothing rolls back.
  *
+ * ## A body may answer `Unchanged`, and then there is nothing to guard
+ *
+ * The body's success is a `DecisionOutput`: a non-empty batch, or `Unchanged` —
+ * "already done". On `Unchanged` the bracket appends nothing, derives no
+ * condition and returns the `Unchanged`, and the result type is
+ * `DecisionResult<O>`, so a body that cannot answer it keeps a plain `Position`.
+ * `decideOnly` passes a decider's `Unchanged` through to the body unaltered.
+ *
+ * It is NOT refused as `NoReadsRecorded`, even from a bracket that read nothing,
+ * and that is not a hole in the refusal. `NoReadsRecorded` exists because an
+ * append with no prior read would go out UNGUARDED while looking guarded. An
+ * `Unchanged` appends nothing, so there is no write for a condition to guard and
+ * nothing for the refusal to protect. The same empty bracket returning EVENTS is
+ * still refused, exactly as before. `decision.ts` owns what `Unchanged` is.
+ *
  * ## Order is the design, and it is the one line here that must not move
  *
  * The precondition is evaluated INSIDE the bracket and never before it. Evaluated
@@ -91,6 +106,11 @@ import { AppendIsOwned, DcbEventStore } from '@kairos-es/core'
 import type { Array as Arr } from 'effect'
 import { Context, Effect, Layer } from 'effect'
 import type { Decider } from './decider'
+import {
+  type DecisionOutput,
+  type DecisionResult,
+  isUnchanged,
+} from './decision'
 import { modelAtHead, type RequirementOf } from './decisionModel'
 import type { CodecError } from './errors'
 import type { SliceProjection } from './projection'
@@ -134,7 +154,8 @@ export interface Precondition<Id, Service, E, R> {
 
 /**
  * The DCB command cycle MINUS the append: read the decision model, decode, fold,
- * decide, and RETURN the events for the bracket to append.
+ * decide, and RETURN the events for the bracket to append — or the decider's
+ * `Unchanged`, passed through as it came, for the bracket to append nothing.
  *
  * Bracket-only, and the refusal is STATIC — see the section below for the mechanism
  * and, more importantly, for where the error actually lands, which is not where a
@@ -189,11 +210,12 @@ export const decideOnly = <
   Command,
   E,
   R,
+  O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>,
 >(
-  decider: Decider<P, Command, E, R>,
+  decider: Decider<P, Command, E, R, O>,
   command: Command,
 ): Effect.Effect<
-  Arr.NonEmptyReadonlyArray<DcbEvent>,
+  O,
   E | CodecError | TaglessSliceInLedger,
   ReadLedger | DcbEventStore | Serializer | Uuid | R | RequirementOf<P>
 > =>
@@ -275,13 +297,19 @@ export const unsafeAppend = (
  * appends without opening one, and its events usually match the union the bracket
  * is about to guard on, so the bracket's own close would be refused by a condition
  * its own body invalidated.
+ *
+ * The body may succeed with `Unchanged` (see the module documentation), and the
+ * result is then `DecisionResult<O>`: `Position` for a body that cannot answer
+ * it, `Position | Unchanged` for one that can. `O` is last and defaulted, so an
+ * explicit `<E, R>` written against the narrower signature still means what it
+ * did.
  */
 export const transact =
   <Id, Service, PE, PR>(precondition: Precondition<Id, Service, PE, PR>) =>
-  <E, R>(
-    body: Effect.Effect<Arr.NonEmptyReadonlyArray<DcbEvent>, E, R>,
+  <E, R, O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>>(
+    body: Effect.Effect<O, E, R>,
   ): Effect.Effect<
-    Position,
+    DecisionResult<O>,
     E | PE | NoReadsRecorded | AppendConditionFailed,
     | Exclude<Exclude<R, Id>, ReadLedger | AppendIsOwned>
     | Exclude<PR, ReadLedger | AppendIsOwned>
@@ -291,7 +319,7 @@ export const transact =
       const store = yield* DcbEventStore
       const ledger = yield* makeReadLedger
 
-      const events = yield* Effect.gen(function* () {
+      const output: DecisionOutput = yield* Effect.gen(function* () {
         // ORDER IS THE DESIGN. The precondition runs first and runs HERE, with the
         // ledger already in context, so its reads are hops in the very condition
         // that will guard the body's write.
@@ -324,10 +352,20 @@ export const transact =
         ),
       )
 
+      // "Already done": nothing to append, so no condition to derive and nothing
+      // for `NoReadsRecorded` to protect — that refusal guards a WRITE that would
+      // go out unguarded, and there is none. It must stay BEFORE the derivation,
+      // or an empty bracket answering `Unchanged` would be refused for a write it
+      // never asked for. The casts restate `DecisionResult<O>`, which the checker
+      // cannot relate to either branch while `O` is still a type variable.
+      if (isUnchanged(output)) {
+        return output as DecisionResult<O>
+      }
+
       const condition = deriveLayeredCondition(yield* ledger.hops)
       if (condition === undefined) {
         return yield* new NoReadsRecorded()
       }
 
-      return yield* store.append(events, condition)
+      return (yield* store.append(output, condition)) as DecisionResult<O>
     })