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

package/src/precondition.ts

@@ -0,0 +1,371 @@
+/**
+ * The bracket that owns the append, the precondition value it takes, and the two
+ * functions that make a decision inside it writable.
+ *
+ * ## What the bracket is for, and why no condition reaches the caller
+ *
+ * `transact(precondition)(body)` evaluates a guard, hands its output to the body
+ * as a service, and appends whatever the body produced under the union of every
+ * read EITHER of them performed. A caller writes no condition, no union, no floor
+ * and no `min`.
+ *
+ * That is not an ergonomic preference. Owning the append does not make a wrong
+ * condition a type error — it makes one UNWRITABLE, which is the stronger
+ * guarantee: a returned condition is a condition a caller can decline to use, and
+ * a decision that looks guarded and is not is the exact failure this seam exists
+ * to close. It is what Axon Framework 5 does, where the condition is married to
+ * the events at prepare-commit and the caller never holds one.
+ *
+ * One thing is deliberately NOT borrowed from that prior art. There, an append
+ * with no prior read leaves the condition unset and the append unguarded, so the
+ * method name reads as unconditional while the behaviour is not. `NoReadsRecorded`
+ * closes that door here and must not be lost.
+ *
+ * ⚠ 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
+ * before, its reads are not part of what it protects — the ledger does not exist
+ * yet, so its hops are lost and the write is guarded only by the business read.
+ * The check would look exactly as it does now and would guard nothing.
+ *
+ * ## Why the precondition's output crosses as a SERVICE
+ *
+ * A body that needs authorisation names the tag in its requirement channel, so
+ * `transact` must provide it, so the body CANNOT BE RUN without a precondition.
+ * That is a PRESENCE check, and presence is the one direction the type system can
+ * decide here — `Exclude<R, Id>` in the return type is where it is spent. The
+ * alternative, a curried parameter, buys nothing equivalent: a body is free to
+ * ignore a parameter.
+ *
+ * ## Composition is a combinator, not a list
+ *
+ * `transact` takes exactly ONE precondition. A variadic argument asserts
+ * INDEPENDENCE, and the interesting case is DEPENDENT — *may act for this
+ * organisation*, then *may sign in that organisation* — which a flat list cannot
+ * express and which is the very shape this change exists for. A dependent pair
+ * needs nothing anyway: a precondition is an ordinary `Effect` evaluated inside
+ * the open ledger, so two compose with `Effect.gen` and both sets of reads land in
+ * the same condition. An INDEPENDENT set wants a combinator over a RECORD,
+ * evaluated SEQUENTIALLY — fail-fast is the point, and concurrent reads are
+ * precisely the case where the earliest-head reduction stops being redundant. That
+ * combinator is purely additive and is not shipped here.
+ *
+ * ## Conflict retry goes OUTSIDE the bracket, never inside
+ *
+ * `retryOnConflict(transact(p)(body))`, never a retry within the body. The bracket
+ * takes an opaque `Effect`, so no type can express that rule and the lint gate is
+ * what enforces it: in the source repository, `biome-plugins/noRetryInBracket.grit`
+ * owns why and `test/retryInBracket.test.ts` executes it.
+ *
+ * ## ⚠⚠ THE ONE MISTAKE NOTHING CATCHES: a view read inside a bracket
+ *
+ * **A projection read, a raw SQL read, or any read that does not fold through
+ * `modelAtHead`, performed inside a bracket, contributes NO HOP.** Its query is
+ * absent from the derived union and its head is absent from the floor, so the
+ * decision rests on data the condition does not guard — and the bracket looks
+ * guarded, which is the exact failure this seam exists to close, wearing the fix's
+ * own name.
+ *
+ * **Nothing will tell you — not here and not in your own tree.** Not the type
+ * system: a requirement channel is ADDITIVE, so it can demand a capability's
+ * presence and never its absence. Not `NoReadsRecorded`: that fires on an EMPTY
+ * bracket and never on an under-populated one, so a bracket holding one genuine fold
+ * beside a view read passes it. And not a lint rule — one was written for exactly
+ * this, kept for a while and deleted, because a syntactic gate has no call graph and
+ * no types, so it could only name a receiver by convention, and because a lint
+ * plugin runs only where its own config is and so never travels with the library.
+ * `biome-plugins/README.md` in the source repository records the test that rule
+ * failed.
+ *
+ * So this is a rule a reader keeps, and knowing it is the guarantee: **inside a
+ * bracket, read through `modelAtHead`. If a read must
+ * consult a materialised view, do it OUTSIDE the bracket** — where it is ordinary
+ * code, because its answer is then not part of what the append is guarded on.
+ * ADR-0014's *decision read* rule is the test for which one a given read is.
+ */
+import type { AppendConditionFailed, DcbEvent, Position } from '@kairos-es/core'
+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'
+import {
+  deriveLayeredCondition,
+  makeReadLedger,
+  NoReadsRecorded,
+  ReadLedger,
+  type TaglessSliceInLedger,
+} from './readLedger'
+import type { Serializer } from './Serializer'
+import type { Uuid } from './Uuid'
+
+/**
+ * A named, reusable guard plus the tag its output is handed across.
+ *
+ * A VALUE and not a function of the command, deliberately: the point of the seam
+ * is that a guard is written once, centrally, and referenced by however many
+ * commands need it. A command supplies its own arguments when it BUILDS the value
+ * (`mayActFor(userId, orgId, verb)`), and what `transact` receives is the built
+ * thing.
+ *
+ * `Service` is fully generic and the library never reads it. Every consumer-side
+ * authorisation shape — a plain resolved identifier, a branded proof, a gate with
+ * a private minting closure — is application code this genericity accommodates
+ * without the library knowing anything about it. That is a requirement rather than
+ * an incidental property: hard-coding it would foreclose a consumer's later
+ * choice, and it costs nothing to keep.
+ *
+ * ⚠ `evaluate` is an `Effect`, so it is a FIELD OF AN OBJECT LITERAL and its
+ * expression is evaluated when the `Precondition` VALUE is built — before the
+ * bracket opens and before any cheap check inside it runs. Anything a builder does
+ * eagerly there (parsing an argument, resolving an identifier) happens outside the
+ * ordering guarantee above, and a throw there is an uncatchable defect on the very
+ * path meant to deny the input cheaply. Wrap such work in `Effect.suspend`.
+ */
+export interface Precondition<Id, Service, E, R> {
+  readonly tag: Context.Tag<Id, Service>
+  readonly evaluate: Effect.Effect<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 — 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
+ * reader first expects. Forced through anyway, being outside a bracket is a DEFECT
+ * rather than an error-channel value: it is not a data-dependent outcome a caller
+ * could handle, and the events produced would be dropped with nothing to append them.
+ *
+ * It is also what makes the nesting refusal liveable. A command runner inside a
+ * bracket is refused at the store, and this is the function a builder reaches for
+ * instead — one identifier away. A refusal is only affordable when the fix is that
+ * close.
+ *
+ * `modelAtHead` and NOT `buildDecisionModel`: this function must not derive a
+ * condition at all. The bracket owns that, and owning it in ONE place is what
+ * stops a caller appending under the last hop's condition alone.
+ *
+ * ## Bracket-only is a REQUIREMENT, so `tsc` refuses it rather than a run
+ *
+ * `ReadLedger` is named in the requirement channel and `transact` is the only thing
+ * that provides it, so a program that calls this outside a bracket cannot be RUN,
+ * and `tsc` is what says so — nothing has to execute for a caller to be told.
+ *
+ * ⚠ Measured, because the obvious stronger reading is wrong: the call site itself
+ * COMPILES. A bare `decideOnly(d, cmd)` outside a bracket is fine, and so is an
+ * exported helper over it; the requirement just propagates, as any unmet requirement
+ * does. What fails is the DISCHARGE — `Effect.provide`, `runPromise`, an annotation
+ * asking for `R = never` — possibly in another file. That is still a static refusal
+ * and it is the whole gain over the runtime defect this replaced. It is not a
+ * squiggle under the mistake.
+ *
+ * That is a PRESENCE check, and presence is the direction the type system can
+ * decide here — the same direction `transact`'s `Exclude<R, Id>` already spends on
+ * the precondition's output. ADR-0014's 2026-08-29 amendment carries the rule that
+ * follows: look for a presence check before reaching for a defect. This function
+ * shipped a defect first, and the check was available all along.
+ *
+ * ⚠ Two lines carry it and their JOBS differ. The RETURN ANNOTATION is the surface a
+ * consumer is judged against, and what the discharge above meets. The
+ * `yield* ReadLedger` keeps the requirement in the INFERRED type, so it survives the
+ * annotation being edited, and it dies at run time for the audience no type reaches
+ * — a JavaScript consumer runs no compile step — rather than handing back events
+ * with no bracket to append them. Nothing here READS the ledger; `modelAtHead` does
+ * the recording, ambiently, through `Effect.serviceOption`.
+ *
+ * ⚠ Do not try to write down which check catches which deletion. It was tried twice
+ * and was wrong twice, and `test/appendOwnership.test.ts` in the source repository
+ * says why the second failure means there should be no third attempt. Plant the
+ * mutation instead.
+ */
+export 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>
+> =>
+  Effect.gen(function* () {
+    yield* ReadLedger
+
+    const { state } = yield* modelAtHead(decider.projections(command))
+    return yield* decider.decide(state, command)
+  })
+
+/**
+ * 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
+ * deliberate.
+ *
+ * It covers three cases and no others: deliberate narrowing, a genuinely
+ * unconditional creation, and a second append inside one bracket. The `reason` is
+ * ceremony on purpose, and ADR-0014 decision 6 owns why a hatch has to cost more
+ * than the safe path — that argument is a DECISION and belongs to the record that
+ * took it, so it is not restated here. How biome turns a required argument into a
+ * review signal is the source repository's `biome-plugins/unsafeAppendReported.grit`.
+ *
+ * ⚠ It BYPASSES the derived condition rather than composing with it. A caller who
+ * genuinely needs *the union, minus one event type* must restate the whole
+ * condition here. If that turns up in practice, a composing override is the
+ * additive answer and this hatch is not it.
+ *
+ * `Effect.mapInputContext` over
+ * `Context.omit(AppendIsOwned)` is what lets it through the store's ownership
+ * refusal — the one route, and `AppendIsOwned.ts` owns why removing the marker is
+ * the shape rather than a second tag or a sanctioning flag.
+ */
+export const unsafeAppend = (
+  events: Arr.NonEmptyReadonlyArray<DcbEvent>,
+  // Required by the signature and never read, which IS the mechanism: the value a
+  // caller has to write is what a reviewer sees in the diff, and `tsc` refuses the
+  // call that omits it. A lint rule asserting the same arity existed and was
+  // deleted, on the ground that the type already refuses it — which made that
+  // ground load-bearing, so `test/appendOwnership.test.ts` in the source repository
+  // pins it. Reading the value here would give it a second job and a second place to
+  // be wrong.
+  //
+  // NOT `_reason`, though it is unused. This name SHIPS — it is what a consumer's
+  // editor offers and what the published `.d.ts` carries — and a leading underscore
+  // is this ecosystem's way of saying "ignore me", which is the opposite of what a
+  // required argument whose whole purpose is to be read by a human should say.
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: unread on purpose; this name ships in the .d.ts and an underscore would tell a consumer to ignore it
+  reason: string,
+): Effect.Effect<Position, AppendConditionFailed, DcbEventStore> =>
+  Effect.flatMap(DcbEventStore, (store) =>
+    // ⛔ DO NOT SIMPLIFY THIS. The annotation reads as "map an empty context to an
+    // empty context", and the types say nothing else — but `Context.omit` runs
+    // against the RUNTIME context, which inside a bracket holds `AppendIsOwned`,
+    // and removing it is the entire reason this function can append at all. That
+    // marker is deliberately absent from every signature (it is read through
+    // `Effect.serviceOption`, which is what keeps it out of `append`'s requirement
+    // channel), so nothing here will fail to compile if this is deleted — what
+    // catches it is `test/appendOwnership.test.ts` in the source repository, not the
+    // type checker.
+    Effect.mapInputContext(
+      store.append(events),
+      (context: Context.Context<never>) => Context.omit(AppendIsOwned)(context),
+    ),
+  )
+
+/**
+ * Open a bracket over ONE decision: evaluate the precondition inside it, hand its
+ * output to the body under the precondition's tag, and append what the body
+ * produced under the union of every read either of them performed.
+ *
+ * Curried so the precondition reads as the thing the command DECLARES and the body
+ * reads as the thing it DOES.
+ *
+ * The ownership marker is provided ALONGSIDE the ledger and to the body only, so
+ * any append inside the body — a nested bracket, a command runner, a raw
+ * `store.append` — is refused at the store as a defect, while the bracket's own
+ * closing append below runs outside that scope and is unaffected. That is why the
+ * refusal is on APPENDING rather than on opening a bracket: a command runner
+ * 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, 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
+  > =>
+    Effect.gen(function* () {
+      const store = yield* DcbEventStore
+      const ledger = yield* makeReadLedger
+
+      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.
+        const proof = yield* precondition.evaluate
+        return yield* body.pipe(Effect.provideService(precondition.tag, proof))
+      }).pipe(
+        // ONE layer, not two provisions, and it is the ANNOTATION above that makes
+        // that mandatory rather than tidy.
+        //
+        // TypeScript does not simplify a deferred conditional over an unresolved
+        // type variable, so `Exclude<Exclude<X, A>, B>` and
+        // `Exclude<X, A | B>` are unrelated types while `X` is still a parameter,
+        // and every provision here adds one level of nesting the annotation has to
+        // mirror EXACTLY. Both halves measured, each as a `TS2719` at the return
+        // annotation: two chained provisions refuse the flat
+        // `Exclude<PR, ReadLedger | AppendIsOwned>`, and even with this merge the
+        // flat `Exclude<R, Id | ReadLedger | AppendIsOwned>` is refused too,
+        // because the precondition's own tag is provided separately and further in.
+        // So `PR` is flat and `R` is one deep, and that asymmetry is the pipeline
+        // showing through rather than a slip.
+        //
+        // Merging says what is true anyway, which is why it is the fix rather than
+        // a cast: the ledger and the ownership marker have one lifetime and one
+        // meaning between them, and that meaning is *you are inside a bracket*.
+        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 as DecisionResult<O>
+      }
+
+      const condition = deriveLayeredCondition(yield* ledger.hops)
+      if (condition === undefined) {
+        return yield* new NoReadsRecorded()
+      }
+
+      return (yield* store.append(output, condition)) as DecisionResult<O>
+    })