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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairos-es/codec",
-  "version": "0.0.0",
+  "version": "1.0.0-alpha.1",
   "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": "^0.0.0"
+    "@kairos-es/core": "^1.0.0-alpha.1"
   },
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",

package/src/decider.ts

@@ -66,6 +66,7 @@ import { Effect } from 'effect'
 import { buildDecisionModel, type RequirementOf } from './decisionModel'
 import type { CodecError } from './errors'
 import type { SliceProjection } from './projection'
+import type { TaglessSliceInLedger } from './readLedger'
 import type { Serializer } from './Serializer'
 import type { Uuid } from './Uuid'
 
@@ -193,8 +194,15 @@ export const decider = <
  * (`buildDecisionModel`) and produce (`toEvent`) sides, `Uuid` through produce,
  * the slices' `RequirementOf<P>` through decode, and `R` through produce. (For a
  * def whose `Schema` carries a requirement, `RequirementOf<P>` and `R` are the
- * same tag.) Any `decide` failure, a decode `CodecError`, or an
- * `AppendConditionFailed` propagates on the error channel unchanged.
+ * same tag.) Any `decide` failure, a decode `CodecError`, an
+ * `AppendConditionFailed`, or the read's own `TaglessSliceInLedger` propagates on
+ * the error channel unchanged.
+ *
+ * ⚠ INSIDE a bracket this function is REFUSED, as a defect, at the store's shared
+ * append decorator, and `decideOnly` is what a body reaches for instead.
+ * `index.ts` states that pair, why each refuses exactly where the other is the
+ * answer, and why neither can be expressed over the other. Read it before
+ * changing either signature; this file does not restate the argument.
  */
 export const runDecider = <
   P extends Record<string, SliceProjection>,
@@ -206,7 +214,7 @@ export const runDecider = <
   command: Command,
 ): Effect.Effect<
   Position,
-  E | CodecError | AppendConditionFailed,
+  E | CodecError | AppendConditionFailed | TaglessSliceInLedger,
   DcbEventStore | Serializer | Uuid | R | RequirementOf<P>
 > =>
   Effect.gen(function* () {

package/src/decisionModel.ts

@@ -7,11 +7,18 @@
  * `modelAtHead` stops where the fold does, at `{ state, head }` — a
  * materialisation of the record with no table, no checkpoint and no runner.
  * `buildDecisionModel` adds the only part that is genuinely decision-specific:
- * the `AppendCondition` derived from the same query and that same head (the DCB
- * optimistic-concurrency contract). It is core's old
- * `buildDecisionModel(Record<string, AnyProjection>)` surface, moved here
+ * the `AppendCondition` (the DCB optimistic-concurrency contract). It is core's
+ * old `buildDecisionModel(Record<string, AnyProjection>)` surface, moved here
  * because decode needs `Schema` + the `Serializer`.
  *
+ * BOTH exports also record into the ambient read ledger when one is in context,
+ * which is what makes a decision that walks a chain of identifiers guard on every
+ * hop rather than on its last. Recording is `modelAtHead`'s, so it happens
+ * whatever symbol performed the read; outside a bracket there is no ledger,
+ * nothing is recorded and no behaviour changes. `readLedger.ts` owns the whole
+ * argument, including why the recorder is this module rather than a
+ * layered-only entry point of its own.
+ *
  * The fold stays pure and in core; only the decode stage is effectful, and that
  * stage lives in `decode.ts` — `decodeSlices` — so the read side folds a live
  * `subscribe` stream through the *same* decode this module folds a bounded
@@ -32,10 +39,16 @@ import {
   DcbEventStore,
   type Position,
 } from '@kairos-es/core'
-import { Effect, Stream } from 'effect'
+import { Effect, Option, Stream } from 'effect'
 import { decodeSlices } from './decode'
 import type { CodecError } from './errors'
 import type { SliceProjection } from './projection'
+import {
+  ambientLayeredCondition,
+  assertServableAddition,
+  recordQuery,
+  type TaglessSliceInLedger,
+} from './readLedger'
 import type { Serializer } from './Serializer'
 
 /** The union of requirements `R` carried by a record of `SliceProjection`s. */
@@ -66,6 +79,16 @@ export type RequirementOf<T extends Record<string, SliceProjection>> =
  * single fold cannot serve — across many identities, ordered, joined, paginated
  * — and never because it is fresher, because it is not.
  *
+ * ⚠ AND INSIDE A BRACKET IT IS NOT THE FLOOR THE APPEND WILL USE. Everything
+ * above is a statement about THIS read, and it stays true; what changes is that a
+ * bracket guards on the EARLIEST head across every hop it walked, which on any hop
+ * after the first is a strictly lower number than the one returned here. So a
+ * caller who reads `head` inside a bracket and reasons about what the append will
+ * refuse is reasoning from the wrong figure — the guard is wider than this head
+ * says. Nothing here is wrong; the trap is assuming the two are the same number,
+ * and it is named because it is exactly the assumption that holds outside a
+ * bracket and quietly stops holding inside one. `readLedger.ts` owns the floor.
+ *
  * `head` is LOG-GLOBAL: it is the head the store's `read` returned, so it moves
  * for an event no slice here selects. `test/decisionModel.test.ts` pins that
  * behaviour EXPLICITLY, over four appended events one of which the composed query
@@ -93,7 +116,7 @@ export const modelAtHead = <T extends Record<string, SliceProjection>>(
   projections: T,
 ): Effect.Effect<
   { readonly state: CompositeState<T>; readonly head: Position },
-  CodecError,
+  CodecError | TaglessSliceInLedger,
   DcbEventStore | Serializer | RequirementOf<T>
 > =>
   Effect.gen(function* () {
@@ -108,6 +131,21 @@ export const modelAtHead = <T extends Record<string, SliceProjection>>(
     const composite = composeProjections(
       projections as Record<string, AnyProjection>,
     )
+
+    // Both ledger calls below are no-ops outside a bracket and neither touches
+    // the requirement channel; `readLedger.ts` owns why recording happens HERE
+    // rather than at a layered-only entry point of its own.
+    //
+    // Refuse an unservable union BEFORE the read is paid for: the question is
+    // answerable from the queries alone, so a hop that would kill the append two
+    // layers away fails at the read that caused it instead.
+    yield* assertServableAddition(projections as Record<string, AnyProjection>)
+
+    // EAGER: the query is filed before a single event is streamed, so a read that
+    // opens and never completes still widens the guard. What comes back is the
+    // effect that completes the hop; outside a bracket it does nothing.
+    const closeHop = yield* recordQuery(composite.query)
+
     const { events, head } = yield* store.read(composite.query)
 
     const decoded = decode(events)
@@ -118,6 +156,11 @@ export const modelAtHead = <T extends Record<string, SliceProjection>>(
       (acc, event) => composite.evolve(acc, event),
     )) as CompositeState<T>
 
+    // LAZY: only once the fold has run to completion. A read that failed
+    // part-way folded a PREFIX, and a head recorded for it is a claim it did not
+    // earn — so the line below is unreachable on that path, deliberately.
+    yield* closeHop(head)
+
     return { state, head }
   })
 
@@ -134,17 +177,19 @@ export const modelAtHead = <T extends Record<string, SliceProjection>>(
  * of a near-duplicate: `modelAtHead` is the shared part, this function is the
  * condition and nothing else, and each is shorter than the one function was.
  *
- * `composeProjections` therefore runs TWICE for one command — once inside
- * `modelAtHead` for the read, once here for `failIfEventsMatch` — and that is
- * deliberate rather than waste. It is a pure derivation of the record, so the two
- * queries cannot disagree however either call site changes. The alternative,
- * returning the query from `modelAtHead`, would put a third field on a READ-TIME
- * API that no read-time caller wants, to save one pure merge over a handful of
- * slices; a surface paying for a body's convenience is the worse trade.
+ * Outside a bracket `composeProjections` therefore runs twice for one command —
+ * once inside `modelAtHead` for the read, once here for `failIfEventsMatch` — and
+ * that is deliberate rather than waste. It is a pure derivation of the record, so
+ * the two queries cannot disagree however either call site changes. The
+ * alternative, returning the query from `modelAtHead`, would put a third field on
+ * a READ-TIME API that no read-time caller wants, to save one pure merge over a
+ * handful of slices; a surface paying for a body's convenience is the worse
+ * trade. Inside a bracket the second merge is not reached at all: the ledger's
+ * own derivation composes every recorded hop instead.
  *
  * ## How to attribute the read, the decode and the fold — the rule, stated once
  *
- * Because this function is `Effect.map` over `modelAtHead`, prose about the codec
+ * Because this function is expressed OVER `modelAtHead`, prose about the codec
  * splits into two kinds and only one of them may name this symbol:
  *
  * - Naming this function as the ENTRY POINT a caller invokes, or as the path
@@ -168,15 +213,34 @@ export const buildDecisionModel = <T extends Record<string, SliceProjection>>(
     readonly state: CompositeState<T>
     readonly appendCondition: AppendCondition
   },
-  CodecError,
+  CodecError | TaglessSliceInLedger,
   DcbEventStore | Serializer | RequirementOf<T>
 > =>
-  Effect.map(modelAtHead(projections), ({ state, head }) => ({
-    state,
-    appendCondition: {
-      failIfEventsMatch: composeProjections(
-        projections as Record<string, AnyProjection>,
-      ).query,
-      after: head,
-    },
-  }))
+  Effect.gen(function* () {
+    const { state, head } = yield* modelAtHead(projections)
+
+    // INSIDE A BRACKET the condition comes from the ledger — every query the
+    // bracket walked, at the earliest head observed — and not from this one read.
+    // That is the change's whole ergonomic claim: the call whose current
+    // behaviour is the hazard becomes CORRECT inside a bracket, with nothing at
+    // the call site changing beyond entering one. The cost is that one expression
+    // means two things depending on ambient context, and that is the trade taken.
+    //
+    // `modelAtHead` has just recorded a hop, so inside a bracket the derivation
+    // cannot be empty; `None` here means there is no ledger at all.
+    const ambient = yield* ambientLayeredCondition
+    if (Option.isSome(ambient)) {
+      return { state, appendCondition: ambient.value }
+    }
+
+    // OUTSIDE a bracket this is byte-for-byte what shipped.
+    return {
+      state,
+      appendCondition: {
+        failIfEventsMatch: composeProjections(
+          projections as Record<string, AnyProjection>,
+        ).query,
+        after: head,
+      },
+    }
+  })

package/src/index.ts

@@ -34,6 +34,55 @@
  * error union are written once, in the two function bodies, rather than restated
  * as an annotation above them.
  *
+ * `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
+ * precondition's output to the body as a service, and appends what the body
+ * returned under the union of every query either of them read, at the earliest
+ * head observed. No condition reaches the caller. `unsafeAppend(events, reason)`
+ * is the one sanctioned way out. `precondition.ts` owns the argument for the
+ * bracket and everything on it, and `readLedger.ts` for the ledger the seam rests
+ * on — including why the derivation itself is deliberately not on this surface.
+ *
+ * ## ⚠ `runDecider` and `decideOnly` are TWO DISPOSITIONS OF ONE CYCLE
+ *
+ * They are read as a pair or not at all, because each refuses exactly where the
+ * other is the answer:
+ *
+ * |              | outside a bracket                        | inside a bracket                    |
+ * | ------------ | ---------------------------------------- | ----------------------------------- |
+ * | `runDecider` | ✅ the ordinary single-hop case           | ⛔ a DEFECT, refused at the store    |
+ * | `decideOnly` | ⛔ unrunnable, and `tsc` says so          | ✅ the layered case                  |
+ *
+ * ⚠ *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
+ * does. The refusal lands where the context is DISCHARGED — an `Effect.provide`, a
+ * `runPromise`, an annotation asking for `R = never` — which may be another file.
+ * So `pnpm check` catches it without anything running, which is the whole gain over
+ * the runtime defect this replaced; what it does not do is underline the call.
+ *
+ * Neither is expressed over the other, and that is forced rather than chosen: a
+ * definition of `runDecider` as *"`decideOnly`, then append"* would have to call
+ * `decideOnly` outside a bracket, which does not typecheck, and the append it then
+ * made inside one would be refused. The two refusals are the same fact seen from
+ * either side — an append inside a bracket belongs to the bracket — so any
+ * expression of one over the other has to defeat one of them.
+ *
+ * ⚠ The two refusals arrive at DIFFERENT MOMENTS, which is the part a caller acts
+ * on. `runDecider` inside a bracket is refused when it RUNS, at core's shared append
+ * decorator — so the same refusal also meets a raw `store.append` and a runner one
+ * call away in a helper. `decideOnly` outside a bracket is refused by `tsc`, at the
+ * discharge point above, by naming `ReadLedger` in its requirement channel. Why each
+ * was given the instrument it was is a DECISION and belongs to the record that took
+ * it: ADR-0014's `Status`. A lint rule reaches the first case earlier still, while it
+ * is being written; `biome-plugins/README.md` in the source repository owns what a
+ * rule there can and cannot see.
+ *
+ * The remedy is one identifier away in each direction, which is the whole reason a
+ * refusal is affordable at all. `decider.ts` and `precondition.ts` carry the two
+ * halves.
+ *
  * `modelAtHead(slices)` is that same read-decode-fold WITHOUT the
  * `AppendCondition`: `{ state, head }`, one slice record materialised at read
  * time with no table, no checkpoint and no runner, current as of the `head` its
@@ -60,11 +109,24 @@ export {
 export { decodeSlices } from './decode'
 export { CodecError, UnknownEventType } from './errors'
 export { type EventDef, type EventDefAny, event, type TagsFor } from './event'
+export {
+  decideOnly,
+  type Precondition,
+  transact,
+  unsafeAppend,
+} from './precondition'
 export {
   type ProjectionBuilder,
   projection,
   type SliceProjection,
 } from './projection'
+export {
+  type CloseHop,
+  type Hop,
+  NoReadsRecorded,
+  ReadLedger,
+  TaglessSliceInLedger,
+} from './readLedger'
 export { makeRegistry, type Registry } from './registry'
 export { Serializer, SerializerDefault } from './Serializer'
 export { toEvent } from './toEvent'

package/src/precondition.ts

@@ -0,0 +1,333 @@
+/**
+ * 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.
+ *
+ * ## 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 { 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.
+ *
+ * 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,
+>(
+  decider: Decider<P, Command, E, R>,
+  command: Command,
+): Effect.Effect<
+  Arr.NonEmptyReadonlyArray<DcbEvent>,
+  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.
+ */
+export 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
+  > =>
+    Effect.gen(function* () {
+      const store = yield* DcbEventStore
+      const ledger = yield* makeReadLedger
+
+      const events = 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' }),
+          ),
+        ),
+      )
+
+      const condition = deriveLayeredCondition(yield* ledger.hops)
+      if (condition === undefined) {
+        return yield* new NoReadsRecorded()
+      }
+
+      return yield* store.append(events, condition)
+    })