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

package/dist/dts/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../src/decision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,KAAK,KAAK,IAAI,GAAG,EAAmB,MAAM,QAAQ,CAAA;AAE3D;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,MAEpC,CAAA;AAED,qCAAqC;AACrC,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAA;;;;AAEpD;;;;;;;;;;GAUG;AACH,qBAAa,SAAU,SAAQ,eAA8B;IAC3D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB,CAAC;IACA,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,eAAe,CAAkB;CAC9D;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,SACH,CAAA;AAE3C;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,SAAS,CAAA;CAGnD,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;AAE5E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAC3C,QAAQ,GACR,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACjB,QAAQ,GACR,CAAC,SAAS,SAAS,GACjB,SAAS,GACT,QAAQ,CAAA"}

package/dist/dts/index.d.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
@@ -100,6 +117,7 @@
  * record other than the one the query came from (see `decode.ts`).
  */
 export { type Decider, decider, runDecider } from './decider.js';
+export { Decision, type DecisionOutput, type DecisionResult, isUnchanged, Unchanged, UnchangedTypeId, } from './decision.js';
 export { buildDecisionModel, modelAtHead, type RequirementOf, } from './decisionModel.js';
 export { decodeSlices } from './decode.js';
 export { CodecError, UnknownEventType } from './errors.js';

package/dist/dts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoGG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AACvD,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AAC9E,OAAO,EACL,UAAU,EACV,KAAK,YAAY,EACjB,QAAQ,EACR,YAAY,GACb,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,KAAK,iBAAiB,EACtB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,GAAG,EACR,eAAe,EACf,UAAU,EACV,oBAAoB,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqHG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EACL,QAAQ,EACR,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,WAAW,EACX,SAAS,EACT,eAAe,GAChB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AACvD,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AAC9E,OAAO,EACL,UAAU,EACV,KAAK,YAAY,EACjB,QAAQ,EACR,YAAY,GACb,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,KAAK,iBAAiB,EACtB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,GAAG,EACR,eAAe,EACf,UAAU,EACV,oBAAoB,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA"}

package/dist/dts/precondition.d.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,7 @@ import { AppendIsOwned, DcbEventStore } from '@kairos-es/core';
 import type { Array as Arr } from 'effect';
 import { Context, Effect } from 'effect';
 import type { Decider } from './decider.js';
+import { type DecisionOutput, type DecisionResult } from './decision.js';
 import { type RequirementOf } from './decisionModel.js';
 import type { CodecError } from './errors.js';
 import type { SliceProjection } from './projection.js';
@@ -126,7 +142,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
@@ -176,7 +193,7 @@ export interface Precondition<Id, Service, E, R> {
  * says why the second failure means there should be no third attempt. Plant the
  * mutation instead.
  */
-export declare const decideOnly: <P extends Record<string, SliceProjection>, Command, E, R>(decider: Decider<P, Command, E, R>, command: Command) => Effect.Effect<Arr.NonEmptyReadonlyArray<DcbEvent>, E | CodecError | TaglessSliceInLedger, ReadLedger | DcbEventStore | Serializer | Uuid | R | RequirementOf<P>>;
+export declare const decideOnly: <P extends Record<string, SliceProjection>, Command, E, R, O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>>(decider: Decider<P, Command, E, R, O>, command: Command) => Effect.Effect<O, E | CodecError | TaglessSliceInLedger, ReadLedger | DcbEventStore | Serializer | Uuid | R | RequirementOf<P>>;
 /**
  * The sanctioned exception to the nesting refusal: append these events under NO
  * condition, and say in the identifier and in a required `reason` why that is
@@ -216,6 +233,12 @@ export declare const unsafeAppend: (events: Arr.NonEmptyReadonlyArray<DcbEvent>,
  * 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 declare const transact: <Id, Service, PE, PR>(precondition: Precondition<Id, Service, PE, PR>) => <E, R>(body: Effect.Effect<Arr.NonEmptyReadonlyArray<DcbEvent>, E, R>) => Effect.Effect<Position, E | PE | NoReadsRecorded | AppendConditionFailed, Exclude<Exclude<R, Id>, ReadLedger | AppendIsOwned> | Exclude<PR, ReadLedger | AppendIsOwned> | DcbEventStore>;
+export declare const transact: <Id, Service, PE, PR>(precondition: Precondition<Id, Service, PE, PR>) => <E, R, O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>>(body: Effect.Effect<O, E, R>) => Effect.Effect<DecisionResult<O>, E | PE | NoReadsRecorded | AppendConditionFailed, Exclude<Exclude<R, Id>, ReadLedger | AppendIsOwned> | Exclude<PR, ReadLedger | AppendIsOwned> | DcbEventStore>;
 //# sourceMappingURL=precondition.d.ts.map

package/dist/dts/precondition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"precondition.d.ts","sourceRoot":"","sources":["../../src/precondition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAChF,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC9D,OAAO,KAAK,EAAE,KAAK,IAAI,GAAG,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,EAAS,MAAM,QAAQ,CAAA;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAGL,eAAe,EACf,UAAU,EACV,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAElC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAC7C,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,UAAU,GACrB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,OAAO,EACP,CAAC,EACD,CAAC,EAED,SAAS,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,EAClC,SAAS,OAAO,KACf,MAAM,CAAC,MAAM,CACd,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EACnC,CAAC,GAAG,UAAU,GAAG,oBAAoB,EACrC,UAAU,GAAG,aAAa,GAAG,UAAU,GAAG,IAAI,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAOnE,CAAA;AAEJ;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EAc3C,QAAQ,MAAM,KACb,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,qBAAqB,EAAE,aAAa,CAe5D,CAAA;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,QAAQ,GAClB,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,cAAc,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,MACpE,CAAC,EAAE,CAAC,EACH,MAAM,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7D,MAAM,CAAC,MAAM,CACd,QAAQ,EACR,CAAC,GAAG,EAAE,GAAG,eAAe,GAAG,qBAAqB,EAC9C,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC,GACnD,OAAO,CAAC,EAAE,EAAE,UAAU,GAAG,aAAa,CAAC,GACvC,aAAa,CA6Cb,CAAA"}
+{"version":3,"file":"precondition.d.ts","sourceRoot":"","sources":["../../src/precondition.ts"],"names":[],"mappings":"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"}

package/dist/esm/decider.js

@@ -52,76 +52,37 @@
  * boundary, and decode may fail with `CodecError`. All surface on the error
  * channel, so a caller handles all three the same way — and
  * `@kairos-es/testing`'s `.thenError(tag)` can assert any of them.
+ *
+ * `decide` may also answer `Unchanged` — "already done, nothing to append" — but
+ * only where its type says so: `Decider`'s fifth type parameter `O` defaults to
+ * the non-empty batch, and `runDecider` returns `DecisionResult<O>`, which is
+ * plain `Position` unless `O` admits `Unchanged`. So a decider that cannot say
+ * "already done" keeps exactly the result type it always had — an untyped one
+ * and one built in a wrapper generic in its success type included — and one
+ * that can makes its caller handle `Position | Unchanged`. `runDecider` returns an
+ * `Unchanged` without calling `append`, so `append`'s refusal of an empty batch
+ * is untouched and never met. `decision.ts` owns why it is a success rather than
+ * an error or an empty batch, and why it is recognised by a type id.
  */
 import { DcbEventStore } from '@kairos-es/core';
 import { Effect } from 'effect';
+import { isUnchanged } from "./decision.js";
 import { buildDecisionModel } from "./decisionModel.js";
-/**
- * Build a `Decider` with all four of its type arguments INFERRED: the slice
- * record `P` from what `projections` returns, the error union `E` and the extra
- * requirement `R` from what `decide` returns. The command type is the one thing
- * a caller still writes, once, as the annotation on the `projections` parameter
- * — `Command` occurs only in parameter positions, so nothing else could supply
- * it, and it is domain information (the command this decision is parametrised
- * by) rather than plumbing.
- *
- * It adds no capability: the interface stays directly inhabitable and this
- * returns exactly the object literal a caller would have written. What it
- * changes is what an author must SPELL. An object literal annotated
- * `Decider<P, Command, E>` has to state the whole slice record — a
- * `ReturnType<typeof someProjection>` per key, a slice's state type being
- * inferred by `projection().on().build()` and so having no name to write — plus
- * the union of every error its decide branches can fail with. Dropping the
- * annotation instead is not open to the author: without it `decide`'s `state`
- * and `command` parameters have no contextual type and are implicitly `any`. So
- * the cost landed hardest on the worked example, where some thirty lines of type
- * plumbing sat between the reader and the three decisions that file exists to
- * teach.
- *
- * `Eff` captures decide's WHOLE return type as one type parameter instead of
- * inferring `E` and `R` from an `Effect<…, E, Serializer | Uuid | R>` shaped
- * target, and that is the part that had to be got right rather than merely
- * written down. A real `decide` returns a UNION of effects — one `Effect.fail`
- * per rule it enforces, plus the produce path — and TypeScript infers a type
- * parameter from a union source by choosing one constituent's candidate, not by
- * unioning them. Against the shaped target `E` therefore came out as whichever
- * branch won, and every other branch was then rejected against it. Inference to
- * a NAKED type variable takes the union whole, which is why `Eff` is the
- * parameter and `Effect.Effect.Error` / `Effect.Effect.Context` recover the two
- * channels afterwards: those do distribute across a union of effects.
- *
- * The constraint on `Eff` is load-bearing twice over. It is what still refuses a
- * `decide` that could produce an EMPTY batch, the one guarantee the shaped
- * target used to give and the one `append` relies on. It is also what
- * contextually types the produce path's `(event) => [event]` as a one-element
- * TUPLE; unconstrained, that widens to `DcbEvent[]`, which is not a
- * `NonEmptyReadonlyArray` and would fail at the call site.
- *
- * The single `as` is narrow and unavoidable: the declared return is a
- * conditional over an unresolved `Eff`, so while `Eff` is still a type variable
- * the checker cannot relate `(…) => Eff` to `(…) => Effect<…,
- * Effect.Error<Eff>, …>`. The value is the two functions it was handed, so
- * there is nothing for the cast to be wrong about.
- *
- * `R` excludes `Serializer | Uuid` because that is what `R` MEANS on `Decider`:
- * the interface writes decide's requirement as `Serializer | Uuid | R`, so `R`
- * is what the produce side needs BEYOND the codec's own two services. Leaving
- * them in would state the same requirement twice and make an ordinary decider
- * read as though it carried an extra one, though the set `runDecider` ends up
- * asking for is identical either way. The exclusion cannot swallow a caller's
- * own service by accident: a `Context.Tag`'s requirement type carries its key as
- * a literal `Id` field, so only a tag declared under `@kairos-es/codec/Uuid` or
- * `@kairos-es/codec/Serializer` matches — and a tag under that key IS that
- * service, context being keyed by the same string at runtime.
- */
-export const decider = (projections, decide) => ({
-  projections,
-  decide
-});
+export function decider(projections, decide) {
+  return {
+    projections,
+    decide
+  };
+}
 /**
  * Run the full DCB command cycle for a decider against the ambient
  * `DcbEventStore`: build the decision model (real read + decode + fold), decide,
- * and append under the read's append condition. Returns the last new position.
+ * and append under the read's append condition. Returns the last new position —
+ * or, when `decide` answered `Unchanged`, that `Unchanged`, having appended
+ * nothing. The result type is `DecisionResult<O>`, so it is plain `Position` for
+ * every decider that cannot answer `Unchanged`, including one whose `O` is still
+ * a type variable bounded by the batch. ONE signature, deliberately:
+ * `decision.ts` says why that alias, and not an overload, is what carries it.
  *
  * The requirement is `DcbEventStore | Serializer | Uuid | R |
  * RequirementOf<P>`: `Serializer` enters through both the decode
@@ -144,7 +105,14 @@ export const runDecider = (decider, command) => Effect.gen(function* () {
     state,
     appendCondition
   } = yield* buildDecisionModel(decider.projections(command));
-  const newEvents = yield* decider.decide(state, command);
-  return yield* store.append(newEvents, appendCondition);
+  const output = yield* decider.decide(state, command);
+  // "Already done" never reaches `append`: an empty batch stays a defect there,
+  // and this is not one. The two casts restate `DecisionResult<O>`, which the
+  // checker cannot relate to either branch while `O` is still a type variable;
+  // the branch taken is exactly the one the conditional selects.
+  if (isUnchanged(output)) {
+    return output;
+  }
+  return yield* store.append(output, appendCondition);
 });
 //# sourceMappingURL=decider.js.map

package/dist/esm/decider.js.map

@@ -1 +1 @@
-{"version":3,"file":"decider.js","names":["DcbEventStore","Effect","buildDecisionModel","decider","projections","decide","runDecider","command","gen","store","state","appendCondition","newEvents","append"],"sources":["../../src/decider.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DA,SAASA,aAAa,QAAQ,iBAAiB;AAE/C,SAASC,MAAM,QAAQ,QAAQ;AAC/B,SAASC,kBAAkB,QAA4B,oBAAiB;AAuCxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,OAAO,MAAMC,OAAO,GAAGA,CASrBC,WAAoC,EACpCC,MAA2D,MAO1D;EAAED,WAAW;EAAEC;AAAM,CAAE,CAKvB;AAEH;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAMC,UAAU,GAAGA,CAMxBH,OAAkC,EAClCI,OAAgB,KAMhBN,MAAM,CAACO,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOT,aAAa;EAClC,MAAM;IAAEU,KAAK;IAAEC;EAAe,CAAE,GAAG,OAAOT,kBAAkB,CAC1DC,OAAO,CAACC,WAAW,CAACG,OAAO,CAAC,CAC7B;EACD,MAAMK,SAAS,GAAG,OAAOT,OAAO,CAACE,MAAM,CAACK,KAAK,EAAEH,OAAO,CAAC;EACvD,OAAO,OAAOE,KAAK,CAACI,MAAM,CAACD,SAAS,EAAED,eAAe,CAAC;AACxD,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"decider.js","names":["DcbEventStore","Effect","isUnchanged","buildDecisionModel","decider","projections","decide","runDecider","command","gen","store","state","appendCondition","output","append"],"sources":["../../src/decider.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,SAASA,aAAa,QAAQ,iBAAiB;AAE/C,SAASC,MAAM,QAAQ,QAAQ;AAC/B,SAGEC,WAAW,QACN,eAAY;AACnB,SAASC,kBAAkB,QAA4B,oBAAiB;AAoJxE,OAAM,SAAUC,OAAOA,CACrBC,WAAoC,EACpCC,MAGoD;EAEpD,OAAO;IAAED,WAAW;IAAEC;EAAM,CAM3B;AACH;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMC,UAAU,GAAGA,CAOxBH,OAAqC,EACrCI,OAAgB,KAMhBP,MAAM,CAACQ,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOV,aAAa;EAClC,MAAM;IAAEW,KAAK;IAAEC;EAAe,CAAE,GAAG,OAAOT,kBAAkB,CAC1DC,OAAO,CAACC,WAAW,CAACG,OAAO,CAAC,CAC7B;EACD,MAAMK,MAAM,GAAmB,OAAOT,OAAO,CAACE,MAAM,CAACK,KAAK,EAAEH,OAAO,CAAC;EACpE;EACA;EACA;EACA;EACA,IAAIN,WAAW,CAACW,MAAM,CAAC,EAAE;IACvB,OAAOA,MAA2B;EACpC;EACA,OAAQ,OAAOH,KAAK,CAACI,MAAM,CAACD,MAAM,EAAED,eAAe,CAAC;AACtD,CAAC,CAAC","ignoreList":[]}

package/dist/esm/decision.js

@@ -0,0 +1,37 @@
+import { 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 = /*#__PURE__*/Symbol.for('@kairos-es/codec/Unchanged');
+/**
+ * "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 /*#__PURE__*/Data.TaggedClass('Unchanged') {
+  [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 => 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 = {
+  unchanged: reason => new Unchanged(reason === undefined ? {} : {
+    reason
+  })
+};
+//# sourceMappingURL=decision.js.map

package/dist/esm/decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.js","names":["Data","Predicate","UnchangedTypeId","Symbol","for","Unchanged","TaggedClass","isUnchanged","u","hasProperty","Decision","unchanged","reason","undefined"],"sources":["../../src/decision.ts"],"sourcesContent":[null],"mappings":"AA4FA,SAA4BA,IAAI,EAAEC,SAAS,QAAQ,QAAQ;AAE3D;;;;AAIA,OAAO,MAAMC,eAAe,gBAAkBC,MAAM,CAACC,GAAG,CACtD,4BAA4B,CAC7B;AAKD;;;;;;;;;;;AAWA,OAAM,MAAOC,SAAU,sBAAQL,IAAI,CAACM,WAAW,CAAC,WAAW,CAEzD;EACS,CAACJ,eAAe,IAAqBA,eAAe;;AAG/D;;;;;AAKA,OAAO,MAAMK,WAAW,GAAIC,CAAU,IACpCP,SAAS,CAACQ,WAAW,CAACD,CAAC,EAAEN,eAAe,CAAC;AAE3C;;;;;AAKA,OAAO,MAAMQ,QAAQ,GAEjB;EACFC,SAAS,EAAGC,MAAM,IAAK,IAAIP,SAAS,CAACO,MAAM,KAAKC,SAAS,GAAG,EAAE,GAAG;IAAED;EAAM,CAAE;CAC5E","ignoreList":[]}

package/dist/esm/index.js

@@ -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
@@ -100,6 +117,7 @@
  * record other than the one the query came from (see `decode.ts`).
  */
 export { decider, runDecider } from "./decider.js";
+export { Decision, isUnchanged, Unchanged, UnchangedTypeId } from "./decision.js";
 export { buildDecisionModel, modelAtHead } from "./decisionModel.js";
 export { decodeSlices } from "./decode.js";
 export { CodecError, UnknownEventType } from "./errors.js";

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["decider","runDecider","buildDecisionModel","modelAtHead","decodeSlices","CodecError","UnknownEventType","event","decideOnly","transact","unsafeAppend","projection","NoReadsRecorded","ReadLedger","TaglessSliceInLedger","makeRegistry","Serializer","SerializerDefault","toEvent","Uuid","UuidLive","UuidTest"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGA,SAAuBA,OAAO,EAAEC,UAAU,QAAQ,cAAW;AAC7D,SACEC,kBAAkB,EAClBC,WAAW,QAEN,oBAAiB;AACxB,SAASC,YAAY,QAAQ,aAAU;AACvC,SAASC,UAAU,EAAEC,gBAAgB,QAAQ,aAAU;AACvD,SAA0CC,KAAK,QAAsB,YAAS;AAC9E,SACEC,UAAU,EAEVC,QAAQ,EACRC,YAAY,QACP,mBAAgB;AACvB,SAEEC,UAAU,QAEL,iBAAc;AACrB,SAGEC,eAAe,EACfC,UAAU,EACVC,oBAAoB,QACf,iBAAc;AACrB,SAASC,YAAY,QAAuB,eAAY;AACxD,SAASC,UAAU,EAAEC,iBAAiB,QAAQ,iBAAc;AAC5D,SAASC,OAAO,QAAQ,cAAW;AACnC,SAASC,IAAI,EAAEC,QAAQ,EAAEC,QAAQ,QAAQ,WAAQ","ignoreList":[]}
+{"version":3,"file":"index.js","names":["decider","runDecider","Decision","isUnchanged","Unchanged","UnchangedTypeId","buildDecisionModel","modelAtHead","decodeSlices","CodecError","UnknownEventType","event","decideOnly","transact","unsafeAppend","projection","NoReadsRecorded","ReadLedger","TaglessSliceInLedger","makeRegistry","Serializer","SerializerDefault","toEvent","Uuid","UuidLive","UuidTest"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuHA,SAAuBA,OAAO,EAAEC,UAAU,QAAQ,cAAW;AAC7D,SACEC,QAAQ,EAGRC,WAAW,EACXC,SAAS,EACTC,eAAe,QACV,eAAY;AACnB,SACEC,kBAAkB,EAClBC,WAAW,QAEN,oBAAiB;AACxB,SAASC,YAAY,QAAQ,aAAU;AACvC,SAASC,UAAU,EAAEC,gBAAgB,QAAQ,aAAU;AACvD,SAA0CC,KAAK,QAAsB,YAAS;AAC9E,SACEC,UAAU,EAEVC,QAAQ,EACRC,YAAY,QACP,mBAAgB;AACvB,SAEEC,UAAU,QAEL,iBAAc;AACrB,SAGEC,eAAe,EACfC,UAAU,EACVC,oBAAoB,QACf,iBAAc;AACrB,SAASC,YAAY,QAAuB,eAAY;AACxD,SAASC,UAAU,EAAEC,iBAAiB,QAAQ,iBAAc;AAC5D,SAASC,OAAO,QAAQ,cAAW;AACnC,SAASC,IAAI,EAAEC,QAAQ,EAAEC,QAAQ,QAAQ,WAAQ","ignoreList":[]}

package/dist/esm/precondition.js

@@ -1,10 +1,12 @@
 import { AppendIsOwned, DcbEventStore } from '@kairos-es/core';
 import { Context, Effect, Layer } from 'effect';
+import { isUnchanged } from "./decision.js";
 import { modelAtHead } from "./decisionModel.js";
 import { deriveLayeredCondition, makeReadLedger, NoReadsRecorded, ReadLedger } from "./readLedger.js";
 /**
  * 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
@@ -124,11 +126,17 @@ Effect.mapInputContext(store.append(events), context => Context.omit(AppendIsOwn
  * 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 = precondition => body => Effect.gen(function* () {
   const store = yield* DcbEventStore;
   const ledger = yield* makeReadLedger;
-  const events = yield* Effect.gen(function* () {
+  const output = 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.
@@ -156,10 +164,19 @@ export const transact = precondition => body => Effect.gen(function* () {
   Effect.provide(Layer.merge(ledger.layer, Layer.succeed(AppendIsOwned, {
     by: '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;
+  }
   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);
 });
 //# sourceMappingURL=precondition.js.map

package/dist/esm/precondition.js.map

@@ -1 +1 @@
-{"version":3,"file":"precondition.js","names":["AppendIsOwned","DcbEventStore","Context","Effect","Layer","modelAtHead","deriveLayeredCondition","makeReadLedger","NoReadsRecorded","ReadLedger","decideOnly","decider","command","gen","state","projections","decide","unsafeAppend","events","reason","flatMap","store","mapInputContext","append","context","omit","transact","precondition","body","ledger","proof","evaluate","pipe","provideService","tag","provide","merge","layer","succeed","by","condition","hops","undefined"],"sources":["../../src/precondition.ts"],"sourcesContent":[null],"mappings":"AAyFA,SAASA,aAAa,EAAEC,aAAa,QAAQ,iBAAiB;AAE9D,SAASC,OAAO,EAAEC,MAAM,EAAEC,KAAK,QAAQ,QAAQ;AAE/C,SAASC,WAAW,QAA4B,oBAAiB;AAGjE,SACEC,sBAAsB,EACtBC,cAAc,EACdC,eAAe,EACfC,UAAU,QAEL,iBAAc;AAgCrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,OAAO,MAAMC,UAAU,GAAGA,CAMxBC,OAAkC,EAClCC,OAAgB,KAMhBT,MAAM,CAACU,GAAG,CAAC,aAAS;EAClB,OAAOJ,UAAU;EAEjB,MAAM;IAAEK;EAAK,CAAE,GAAG,OAAOT,WAAW,CAACM,OAAO,CAACI,WAAW,CAACH,OAAO,CAAC,CAAC;EAClE,OAAO,OAAOD,OAAO,CAACK,MAAM,CAACF,KAAK,EAAEF,OAAO,CAAC;AAC9C,CAAC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMK,YAAY,GAAGA,CAC1BC,MAA2C;AAC3C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACAC,MAAc,KAEdhB,MAAM,CAACiB,OAAO,CAACnB,aAAa,EAAGoB,KAAK;AAClC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACAlB,MAAM,CAACmB,eAAe,CACpBD,KAAK,CAACE,MAAM,CAACL,MAAM,CAAC,EACnBM,OAA+B,IAAKtB,OAAO,CAACuB,IAAI,CAACzB,aAAa,CAAC,CAACwB,OAAO,CAAC,CAC1E,CACF;AAEH;;;;;;;;;;;;;;;;;AAiBA,OAAO,MAAME,QAAQ,GACGC,YAA+C,IAEnEC,IAA8D,IAQ9DzB,MAAM,CAACU,GAAG,CAAC,aAAS;EAClB,MAAMQ,KAAK,GAAG,OAAOpB,aAAa;EAClC,MAAM4B,MAAM,GAAG,OAAOtB,cAAc;EAEpC,MAAMW,MAAM,GAAG,OAAOf,MAAM,CAACU,GAAG,CAAC,aAAS;IACxC;IACA;IACA;IACA,MAAMiB,KAAK,GAAG,OAAOH,YAAY,CAACI,QAAQ;IAC1C,OAAO,OAAOH,IAAI,CAACI,IAAI,CAAC7B,MAAM,CAAC8B,cAAc,CAACN,YAAY,CAACO,GAAG,EAAEJ,KAAK,CAAC,CAAC;EACzE,CAAC,CAAC,CAACE,IAAI;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA7B,MAAM,CAACgC,OAAO,CACZ/B,KAAK,CAACgC,KAAK,CACTP,MAAM,CAACQ,KAAK,EACZjC,KAAK,CAACkC,OAAO,CAACtC,aAAa,EAAE;IAAEuC,EAAE,EAAE;EAAU,CAAE,CAAC,CACjD,CACF,CACF;EAED,MAAMC,SAAS,GAAGlC,sBAAsB,CAAC,OAAOuB,MAAM,CAACY,IAAI,CAAC;EAC5D,IAAID,SAAS,KAAKE,SAAS,EAAE;IAC3B,OAAO,OAAO,IAAIlC,eAAe,EAAE;EACrC;EAEA,OAAO,OAAOa,KAAK,CAACE,MAAM,CAACL,MAAM,EAAEsB,SAAS,CAAC;AAC/C,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"precondition.js","names":["AppendIsOwned","DcbEventStore","Context","Effect","Layer","isUnchanged","modelAtHead","deriveLayeredCondition","makeReadLedger","NoReadsRecorded","ReadLedger","decideOnly","decider","command","gen","state","projections","decide","unsafeAppend","events","reason","flatMap","store","mapInputContext","append","context","omit","transact","precondition","body","ledger","output","proof","evaluate","pipe","provideService","tag","provide","merge","layer","succeed","by","condition","hops","undefined"],"sources":["../../src/precondition.ts"],"sourcesContent":[null],"mappings":"AAwGA,SAASA,aAAa,EAAEC,aAAa,QAAQ,iBAAiB;AAE9D,SAASC,OAAO,EAAEC,MAAM,EAAEC,KAAK,QAAQ,QAAQ;AAE/C,SAGEC,WAAW,QACN,eAAY;AACnB,SAASC,WAAW,QAA4B,oBAAiB;AAGjE,SACEC,sBAAsB,EACtBC,cAAc,EACdC,eAAe,EACfC,UAAU,QAEL,iBAAc;AAgCrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,OAAO,MAAMC,UAAU,GAAGA,CAOxBC,OAAqC,EACrCC,OAAgB,KAMhBV,MAAM,CAACW,GAAG,CAAC,aAAS;EAClB,OAAOJ,UAAU;EAEjB,MAAM;IAAEK;EAAK,CAAE,GAAG,OAAOT,WAAW,CAACM,OAAO,CAACI,WAAW,CAACH,OAAO,CAAC,CAAC;EAClE,OAAO,OAAOD,OAAO,CAACK,MAAM,CAACF,KAAK,EAAEF,OAAO,CAAC;AAC9C,CAAC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMK,YAAY,GAAGA,CAC1BC,MAA2C;AAC3C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACAC,MAAc,KAEdjB,MAAM,CAACkB,OAAO,CAACpB,aAAa,EAAGqB,KAAK;AAClC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACAnB,MAAM,CAACoB,eAAe,CACpBD,KAAK,CAACE,MAAM,CAACL,MAAM,CAAC,EACnBM,OAA+B,IAAKvB,OAAO,CAACwB,IAAI,CAAC1B,aAAa,CAAC,CAACyB,OAAO,CAAC,CAC1E,CACF;AAEH;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAME,QAAQ,GACGC,YAA+C,IAEnEC,IAA4B,IAQ5B1B,MAAM,CAACW,GAAG,CAAC,aAAS;EAClB,MAAMQ,KAAK,GAAG,OAAOrB,aAAa;EAClC,MAAM6B,MAAM,GAAG,OAAOtB,cAAc;EAEpC,MAAMuB,MAAM,GAAmB,OAAO5B,MAAM,CAACW,GAAG,CAAC,aAAS;IACxD;IACA;IACA;IACA,MAAMkB,KAAK,GAAG,OAAOJ,YAAY,CAACK,QAAQ;IAC1C,OAAO,OAAOJ,IAAI,CAACK,IAAI,CAAC/B,MAAM,CAACgC,cAAc,CAACP,YAAY,CAACQ,GAAG,EAAEJ,KAAK,CAAC,CAAC;EACzE,CAAC,CAAC,CAACE,IAAI;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA/B,MAAM,CAACkC,OAAO,CACZjC,KAAK,CAACkC,KAAK,CACTR,MAAM,CAACS,KAAK,EACZnC,KAAK,CAACoC,OAAO,CAACxC,aAAa,EAAE;IAAEyC,EAAE,EAAE;EAAU,CAAE,CAAC,CACjD,CACF,CACF;EAED;EACA;EACA;EACA;EACA;EACA;EACA,IAAIpC,WAAW,CAAC0B,MAAM,CAAC,EAAE;IACvB,OAAOA,MAA2B;EACpC;EAEA,MAAMW,SAAS,GAAGnC,sBAAsB,CAAC,OAAOuB,MAAM,CAACa,IAAI,CAAC;EAC5D,IAAID,SAAS,KAAKE,SAAS,EAAE;IAC3B,OAAO,OAAO,IAAInC,eAAe,EAAE;EACrC;EAEA,OAAQ,OAAOa,KAAK,CAACE,MAAM,CAACO,MAAM,EAAEW,SAAS,CAAC;AAChD,CAAC,CAAC","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairos-es/codec",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.3",
   "description": "Schema-first codec with encryption seam for kairos-es",
   "license": "BSD-3-Clause",
   "repository": {
@@ -12,7 +12,7 @@
   "homepage": "https://github.com/neverbland/kairos-es",
   "peerDependencies": {
     "effect": "^3.22.0",
-    "@kairos-es/core": "^1.0.0-alpha.1"
+    "@kairos-es/core": "^1.0.0-alpha.3"
   },
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",

package/src/decider.ts

@@ -52,17 +52,32 @@
  * boundary, and decode may fail with `CodecError`. All surface on the error
  * channel, so a caller handles all three the same way — and
  * `@kairos-es/testing`'s `.thenError(tag)` can assert any of them.
+ *
+ * `decide` may also answer `Unchanged` — "already done, nothing to append" — but
+ * only where its type says so: `Decider`'s fifth type parameter `O` defaults to
+ * the non-empty batch, and `runDecider` returns `DecisionResult<O>`, which is
+ * plain `Position` unless `O` admits `Unchanged`. So a decider that cannot say
+ * "already done" keeps exactly the result type it always had — an untyped one
+ * and one built in a wrapper generic in its success type included — and one
+ * that can makes its caller handle `Position | Unchanged`. `runDecider` returns an
+ * `Unchanged` without calling `append`, so `append`'s refusal of an empty batch
+ * is untouched and never met. `decision.ts` owns why it is a success rather than
+ * an error or an empty batch, and why it is recognised by a type id.
  */
 
 import type {
   AppendConditionFailed,
   CompositeState,
   DcbEvent,
-  Position,
 } from '@kairos-es/core'
 import { DcbEventStore } from '@kairos-es/core'
 import type { Array as Arr } from 'effect'
 import { Effect } from 'effect'
+import {
+  type DecisionOutput,
+  type DecisionResult,
+  isUnchanged,
+} from './decision'
 import { buildDecisionModel, type RequirementOf } from './decisionModel'
 import type { CodecError } from './errors'
 import type { SliceProjection } from './projection'
@@ -84,22 +99,26 @@ import type { Uuid } from './Uuid'
  * schema-backed, state-erased bound for a heterogeneous record); the
  * precise per-key state is recovered by core's shared `CompositeState`. The
  * requirement `R` is the union carried by the record's slices' schemas.
+ *
+ * `O` is what `decide` may succeed with. It defaults to the non-empty batch, and
+ * a decider that can answer "already done" widens it to `DecisionOutput`
+ * (`NonEmptyReadonlyArray<DcbEvent> | Unchanged`). It is LAST and DEFAULTED so
+ * that every `Decider<P, Command, E, R>` already written means exactly what it
+ * meant. Its bound is `DecisionOutput`, which still excludes a possibly-empty
+ * array — the widening adds an answer and removes no guarantee.
  */
 export interface Decider<
   P extends Record<string, SliceProjection>,
   Command,
   E = never,
   R = never,
+  O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>,
 > {
   readonly projections: (command: Command) => P
   readonly decide: (
     state: CompositeState<P>,
     command: Command,
-  ) => Effect.Effect<
-    Arr.NonEmptyReadonlyArray<DcbEvent>,
-    E,
-    Serializer | Uuid | R
-  >
+  ) => Effect.Effect<O, E, Serializer | Uuid | R>
 }
 
 /**
@@ -149,6 +168,22 @@ export interface Decider<
  * Effect.Error<Eff>, …>`. The value is the two functions it was handed, so
  * there is nothing for the cast to be wrong about.
  *
+ * The success channel is how a decider opts into `Unchanged` without writing a
+ * fifth type argument, and it is why this function is declared TWICE. The first
+ * declaration bounds `Eff` by the non-empty batch and returns a `Decider` with
+ * the DEFAULT `O`; the second bounds it by `DecisionOutput` and returns one whose
+ * `O` is `DecisionOutput`. A `decide` with a branch returning
+ * `Decision.unchanged(…)` fails the first bound and lands on the second, and one
+ * with no such branch keeps the default. Either way `O` is one of the two a
+ * caller ever writes, never the inferred success type passed through: inference
+ * is more precise than anyone writes — the produce path's one-element tuple, say
+ * — and a `Decider<…, readonly [DcbEvent]>` would not be the
+ * `Decider<P, Command, E, R>` its caller spells, though it behaves identically.
+ * Asking by ASSIGNABILITY rather than by a conditional over `Eff`'s success is
+ * what keeps an untyped (`any`) success, and a success that is a type variable
+ * bounded by the batch, on the default; `decision.ts` owns that argument, and
+ * the one type query the pair cannot answer as before.
+ *
  * `R` excludes `Serializer | Uuid` because that is what `R` MEANS on `Decider`:
  * the interface writes decide's requirement as `Serializer | Uuid | R`, so `R`
  * is what the produce side needs BEYOND the codec's own two services. Leaving
@@ -160,7 +195,7 @@ export interface Decider<
  * `@kairos-es/codec/Serializer` matches — and a tag under that key IS that
  * service, context being keyed by the same string at runtime.
  */
-export const decider = <
+export function decider<
   P extends Record<string, SliceProjection>,
   Command,
   Eff extends Effect.Effect<
@@ -176,18 +211,46 @@ export const decider = <
   Command,
   Effect.Effect.Error<Eff>,
   Exclude<Effect.Effect.Context<Eff>, Serializer | Uuid>
-> =>
-  ({ projections, decide }) as Decider<
+>
+export function decider<
+  P extends Record<string, SliceProjection>,
+  Command,
+  Eff extends Effect.Effect<DecisionOutput, unknown, unknown>,
+>(
+  projections: (command: Command) => P,
+  decide: (state: CompositeState<P>, command: Command) => Eff,
+): Decider<
+  P,
+  Command,
+  Effect.Effect.Error<Eff>,
+  Exclude<Effect.Effect.Context<Eff>, Serializer | Uuid>,
+  DecisionOutput
+>
+export function decider<P extends Record<string, SliceProjection>, Command>(
+  projections: (command: Command) => P,
+  decide: (
+    state: CompositeState<P>,
+    command: Command,
+  ) => Effect.Effect<DecisionOutput, unknown, unknown>,
+): Decider<P, Command, unknown, unknown, DecisionOutput> {
+  return { projections, decide } as Decider<
     P,
     Command,
-    Effect.Effect.Error<Eff>,
-    Exclude<Effect.Effect.Context<Eff>, Serializer | Uuid>
+    unknown,
+    unknown,
+    DecisionOutput
   >
+}
 
 /**
  * Run the full DCB command cycle for a decider against the ambient
  * `DcbEventStore`: build the decision model (real read + decode + fold), decide,
- * and append under the read's append condition. Returns the last new position.
+ * and append under the read's append condition. Returns the last new position —
+ * or, when `decide` answered `Unchanged`, that `Unchanged`, having appended
+ * nothing. The result type is `DecisionResult<O>`, so it is plain `Position` for
+ * every decider that cannot answer `Unchanged`, including one whose `O` is still
+ * a type variable bounded by the batch. ONE signature, deliberately:
+ * `decision.ts` says why that alias, and not an overload, is what carries it.
  *
  * The requirement is `DcbEventStore | Serializer | Uuid | R |
  * RequirementOf<P>`: `Serializer` enters through both the decode
@@ -209,11 +272,12 @@ export const runDecider = <
   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<
-  Position,
+  DecisionResult<O>,
   E | CodecError | AppendConditionFailed | TaglessSliceInLedger,
   DcbEventStore | Serializer | Uuid | R | RequirementOf<P>
 > =>
@@ -222,6 +286,13 @@ export const runDecider = <
     const { state, appendCondition } = yield* buildDecisionModel(
       decider.projections(command),
     )
-    const newEvents = yield* decider.decide(state, command)
-    return yield* store.append(newEvents, appendCondition)
+    const output: DecisionOutput = yield* decider.decide(state, command)
+    // "Already done" never reaches `append`: an empty batch stays a defect there,
+    // and this is not one. The two casts restate `DecisionResult<O>`, which the
+    // checker cannot relate to either branch while `O` is still a type variable;
+    // the branch taken is exactly the one the conditional selects.
+    if (isUnchanged(output)) {
+      return output as DecisionResult<O>
+    }
+    return (yield* store.append(output, appendCondition)) as DecisionResult<O>
   })