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

package/dist/dts-esm/deserialiseThenDecode.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The two-step every decode in this package performs, in one implementation:
+ * deserialise the wire bytes through the `Serializer` its caller already holds,
+ * then `Schema.decodeUnknownEffect` the result, each half's failure wrapped as the
+ * `CodecError` whose `reason` says WHICH half failed.
+ *
+ * **What it is the single home of.** The two `reason` strings `'deserialise'`
+ * and `'decode'`, and their ORDER. Why those strings are observable surface —
+ * fixed rather than cosmetic, because an application quarantines an event,
+ * alerts or fails a command off them — is argued in `decode.ts`'s module doc and
+ * is not restated here. What this module adds is that the argument had TWO
+ * implementations standing behind it: the slice stage (`decodeEvents`) and the
+ * general/registry path (`makeRegistry`'s `decode`) each wrote the pair out, in
+ * one package, and only the slice copy was pinned by a test. A reworded `reason`
+ * on the registry path would have been caught by nothing. Sharing the step
+ * DELETES that drift channel rather than alarming it, which is why this exists
+ * as a function and not as a second test.
+ *
+ * **The order is contract, not accident.** Deserialise has to run first because
+ * `Schema.decodeUnknownEffect` has nothing to read until it has, and the observable
+ * consequence is that the two reasons PARTITION the causes an operator acts on:
+ * rotten bytes are always `'deserialise'` and never `'decode'`, so a storage or
+ * producer problem never arrives dressed as schema drift. Swapping the labels
+ * would not break a decode; it would send every incident to the wrong team.
+ *
+ * **Why a `Serializer` VALUE rather than reading the tag here.** The two callers
+ * acquire it at deliberately different moments and this step must not flatten
+ * that. `decodeEvents` reads it ONCE when the stream starts (`Stream.unwrap`), so
+ * a backlog of a million events does not re-read context per event; the
+ * registry's `decode` is a per-event `Effect` and yields it inside its own
+ * `Effect.gen`. Taking the resolved service preserves both, and keeps
+ * `Serializer` off this signature's `R`, so the requirement stays declared where
+ * the acquisition actually happens — which is where a reader goes looking for it.
+ *
+ * **Why the LOOKUP is not folded in**, though both callers do one immediately
+ * before calling this: the two paths disagree about what a miss MEANS, and the
+ * disagreement is deliberate. The slice path fails `CodecError` with
+ * `no schema for event type '<type>'` — a caller named the type and the record it
+ * supplied has no entry for it, so the wiring is wrong. The registry path fails
+ * `UnknownEventType` — the type arrived off the WIRE and the registry does not
+ * know it, which is ADR-0005 decode-totality and the one fault a rolling
+ * deployment is EXPECTED to meet. `errors.ts` argues why those two sentences stay
+ * greppable apart. Folding the lookup in would mean a per-caller miss
+ * constructor: a second seam, bought to share the one thing the two paths
+ * genuinely do not have in common.
+ *
+ * `R` is the SCHEMA's requirement, propagated untouched — an ADR-0004 decryption
+ * transform reaches the caller's `R` through here with no cast. The three
+ * parameters are positional because their types are mutually unassignable, so a
+ * transposed call is a compile error rather than a silent inversion.
+ *
+ * PACKAGE-INTERNAL: exported to its two callers and no further, deliberately
+ * absent from `index.ts`. It is a shared step, not a capability on offer — a
+ * consumer holding bytes and a `Schema` wants `decodeSlices` or a `Registry`,
+ * both of which do the lookup this one refuses to.
+ */
+import type { Context } from 'effect';
+import { Effect, Schema } from 'effect';
+import { CodecError } from './errors.js';
+import type { Serializer } from './Serializer.js';
+export declare const deserialiseThenDecode: <R>(serializer: Context.Service.Shape<typeof Serializer>, schema: Schema.Decoder<unknown, R>, bytes: Uint8Array) => Effect.Effect<unknown, CodecError, R>;
+//# sourceMappingURL=deserialiseThenDecode.d.ts.map

package/dist/dts-esm/deserialiseThenDecode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deserialiseThenDecode.d.ts","sourceRoot":"","sources":["../../src/deserialiseThenDecode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C,eAAO,MAAM,qBAAqB,GAAI,CAAC,EACrC,YAAY,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,EACpD,QAAQ,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAClC,OAAO,UAAU,KAChB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC,CAUpC,CAAA"}

package/dist/dts-esm/errors.d.ts

@@ -0,0 +1,80 @@
+declare const CodecError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CodecError";
+} & Readonly<A>;
+/** A serialisation or `Schema` decode/encode failure on the codec path. */
+export declare class CodecError extends CodecError_base<{
+    readonly reason: string;
+    readonly cause?: unknown;
+}> {
+    /**
+     * `reason` again, as the `Error` field that says why — so the fault renders
+     * ITSELF.
+     *
+     * `Data.TaggedError` sets `name` to the tag and leaves `message` empty, so
+     * without this a `CodecError` stringifies to `'CodecError'`, and the sentence
+     * naming the schema, the event type or the missing key that failed reaches a log
+     * line only where the code doing the logging knows to reach in for `reason`.
+     * Filled, `Error.prototype.toString` yields `'CodecError: <reason>'`, which is
+     * what `Cause.pretty` (it reads `message` off anything `instanceof Error`) and the
+     * read side's projection supervisor both report — neither of them holding a table
+     * of this class's fields to keep in step with it.
+     *
+     * This class is on the package's PUBLISHED surface, so be exact about what the
+     * field moves. Everything that renders the error for a HUMAN: `String(err)`,
+     * `Cause.pretty` and therefore a failed fibre's `cause` annotation on every
+     * shipped logger, and an unhandled failure's report. Nothing that renders it for
+     * a MACHINE: `Data.Error` overrides `YieldableError`'s `toJSON` with
+     * `{ ...plainArgs, ...this }` — own enumerables plus the constructor args, and a
+     * prototype accessor is neither — so `JSON.stringify(err)` still emits the same
+     * `reason`/`_tag` and a structured log of a raw `CodecError` keeps its shape.
+     *
+     * A GETTER rather than a second field, so `reason` stays the single declaration.
+     * It is visible because `Data.TaggedError`'s constructor is
+     * `super(args?.message, …)` followed by copying the args' own enumerable keys
+     * onto the instance (verified against `effect@4`'s `internal/core.ts`): the
+     * args above carry no `message`, so nothing shadows this prototype accessor
+     * with an own property.
+     */
+    get message(): string;
+}
+declare const UnknownEventType_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "UnknownEventType";
+} & Readonly<A>;
+/** A wire event whose runtime type string is outside the registry's known set. */
+export declare class UnknownEventType extends UnknownEventType_base<{
+    readonly type: string;
+}> {
+    /**
+     * The offending type, in a sentence saying what the registry did with it — so the
+     * fault renders ITSELF, exactly as `CodecError` above does.
+     *
+     * `Data.TaggedError` sets `name` to the tag and leaves `message` empty, so without
+     * this a decode that met an unregistered type stringifies to `'UnknownEventType'`
+     * — the one datum that makes the failure actionable, the type string itself,
+     * reaching a log line only where the logging code knows to reach in for `type`.
+     * Filled, `Error.prototype.toString` yields the tag followed by
+     * `event type 'nope.v1' is not in the registry`, which is what `Cause.pretty`
+     * prints and what an operator greps for. It matters here in particular because
+     * this class is the home of ADR-0005 decode-totality: a wire event outside the
+     * registered set is the expected consequence of a deployment reading a log a newer
+     * writer has extended, and the first question is always WHICH type — which the tag
+     * alone cannot answer.
+     *
+     * The wording deliberately differs from `CodecError`'s. That one says there is no
+     * schema for a type, and is raised on the TYPED path, where a caller named the
+     * type and the schema map it supplied has no entry for it. This one is the general
+     * (registry) path, where the type arrived off the WIRE and the registry is what
+     * does not know it. Distinct sentences keep the two greppable apart, which a
+     * shared phrasing would cost for nothing.
+     *
+     * A GETTER rather than a second field, so `type` stays the single declaration.
+     * What filling this field reaches, what it deliberately leaves untouched, and why
+     * a prototype accessor is visible at all are argued once on `CodecError` above and
+     * not restated here — it is the same package, the same published surface and the
+     * same mechanism, and two copies of that paragraph would be two things to keep in
+     * step. The read side's four getters point at one home for the identical reason.
+     */
+    get message(): string;
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/dts-esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";;;AAgBA,2EAA2E;AAC3E,qBAAa,UAAW,SAAQ,gBAA+B;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC;IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;;;;AAED,kFAAkF;AAClF,qBAAa,gBAAiB,SAAQ,sBAAqC;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB,CAAC;IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF"}

package/dist/dts-esm/event.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Event definitions: a tagged `Schema` built through `event(type, fields,
+ * tagsFor)`. Each def is a `Schema.Codec<Payload, Wire, R, R>` plus its branded versioned
+ * `type` (ADR-0005) captured *beside* the payload, and a required `tagsFor`
+ * mapper deriving the event's tags from its decoded payload (ADR-0006).
+ *
+ * The single `EventType` brand is applied once, here, so no consumer ever casts
+ * a type string: `def.type` is already assignable to core's `EventType`. The
+ * payload `A`, wire encoding `I`, and requirement `R` are inferred from the
+ * `Schema.Struct` of `fields` — including any requirement a field's `Schema`
+ * transform carries (e.g. an application `Encrypted(...)` field contributes its
+ * `CipherKey` to `R`).
+ *
+ * `tagsFor` is the only way to tag an event: `toEvent` derives the wire tags by
+ * calling it, and there is no `tags` option to override them. Its
+ * `NonEmptyReadonlyArray<Tag>` return makes "every event carries at least one
+ * tag" a compile-time guarantee (returning `[]` is a type error at the def
+ * site), and its input being only this event's payload guarantees `tag ⊆ event
+ * data` structurally. An event with no natural business identity returns an
+ * explicit app-defined `system:<name>` tag, never an empty array.
+ *
+ * A mapper must be a *pure* function of its payload and key off fields in their
+ * schema-canonical form (normalising in the mapper to match a field's schema),
+ * so the tag it derives is stable under the schema round-trip: a later retag
+ * re-derives tags from decoded history, and `tagsFor(decode(encode(p)))` must
+ * equal `tagsFor(p)` for that to be sound. Plain scalar fields satisfy this
+ * trivially; a field whose schema canonicalises on decode (trim, lowercase,
+ * normalise) needs the mapper to apply the same normalisation (ADR-0006).
+ */
+import type { EventType, Tag } from '@kairos-es/core';
+import type { Array as Arr } from 'effect';
+import { Schema } from 'effect';
+/**
+ * A tag mapper: derives an event's tags from its decoded payload, returning at
+ * least one `Tag`. Named so a standalone mapper can be typed and shared (e.g.
+ * across two versioned defs of one logical event) and so the signature is
+ * written once, not per use site.
+ */
+export type TagsFor<A> = (payload: A) => Arr.NonEmptyReadonlyArray<Tag>;
+/**
+ * An event definition: its branded `type`, the `Schema` mapping its typed
+ * payload `A` to its wire encoding `I` (requiring `R`), and the `tagsFor` mapper
+ * that derives the event's tags from a decoded payload.
+ *
+ * `R` is ONE requirement for both directions, which is why the schema is a
+ * `Schema.Codec<A, I, R, R>` rather than leaving decoding and encoding services
+ * apart. A def is decoded on the read path and encoded by `toEvent`, so a
+ * consumer providing a def's services provides them for both; an application
+ * encryption transform needs its key either way. A struct whose two directions
+ * differ still fits, the codec being covariant in both, and `R` is then their
+ * union.
+ *
+ * `tagsFor` CONSUMES an `A`, so `EventDef` is invariant in `A` whatever the
+ * schema's own variance, and is therefore not declared `out A`.
+ */
+export interface EventDef<A = unknown, I = unknown, R = never> {
+    readonly type: EventType;
+    readonly schema: Schema.Codec<A, I, R, R>;
+    readonly tagsFor: TagsFor<A>;
+}
+/**
+ * The heterogeneous bound for arrays/records of mixed defs, where the precise
+ * `A`/`I` differ per element. `tagsFor` erases to `(a: any) => …`, which is
+ * harmless: only the write path (`toEvent`) calls it, and the registry/decode
+ * path never does (stored events already carry tags).
+ */
+export type EventDefAny = EventDef<any, any, unknown>;
+/**
+ * Define an event from a versioned `type` literal, its payload `fields`, and its
+ * required `tagsFor` mapper. Builds `Schema.Struct(fields)` and brands the type
+ * literal *once* (the single sanctioned cast). The returned def is typed so
+ * `def.type` is a branded literal assignable to core's `EventType` with no
+ * consumer cast, `A`/`I`/`R` are inferred from the struct, and `tagsFor`
+ * receives the def's decoded payload type.
+ */
+export declare const event: <const Type extends string, Fields extends Schema.Struct.Fields>(type: Type, fields: Fields, tagsFor: TagsFor<Schema.Struct.Type<Fields>>) => {
+    readonly type: Type & EventType;
+    readonly schema: Schema.Struct<Fields>;
+    readonly tagsFor: TagsFor<Schema.Struct.Type<Fields>>;
+};
+//# sourceMappingURL=event.d.ts.map

package/dist/dts-esm/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,KAAK,EAAE,KAAK,IAAI,GAAG,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;;GAKG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,GAAG,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAA;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,KAAK;IAC3D,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACzC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAC7B;AAED;;;;;GAKG;AAEH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAChB,KAAK,CAAC,IAAI,SAAS,MAAM,EACzB,MAAM,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,EAEnC,MAAM,IAAI,EACV,QAAQ,MAAM,EACd,SAAS,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAC3C;IACD,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAA;CAStD,CAAA"}

package/dist/dts-esm/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @kairos-es/codec — the schema-first codec seam, mapping typed domain events
+ * to and from the store's opaque wire bytes, with an application-owned
+ * encryption seam (ADR-0004).
+ *
+ * Two entry points:
+ * - The *typed slice path* (primary): `event(type, fields, tagsFor)` defines a
+ *   tagged `Schema` plus a required mapper deriving the event's tags from its
+ *   payload (ADR-0006); `projection(init).on(def, fold)...build()` composes the
+ *   specific defs a decision model consumes, inferring its state and requirement
+ *   `R`; `modelAtHead(slices)` reads, decodes through each def's `Schema`, and folds
+ *   purely, and `buildDecisionModel(slices)` adds the `AppendCondition` to it. A handler for an un-imported event is a compile error, and
+ *   a mistyped type cannot silently match nothing.
+ * - The *general path* (minimal): `makeRegistry(defs)` decodes an arbitrary wire
+ *   event by its runtime type string; an unknown type is a typed
+ *   `UnknownEventType` (ADR-0005 decode-totality). The payload stays `unknown`
+ *   on this path: the type is discovered at runtime, so no def was named to
+ *   narrow it (see `registry.ts`).
+ *
+ * `toEvent(def, payload, { uuid?, occurredAt?, metadata? })` produces a wire
+ * event (encode -> serialise, tags derived from `def.tagsFor`, clock + uuid from
+ * services, metadata from the call or the optional ambient `MetadataSource`).
+ * Serialisation is a pluggable `Serializer` (JSON
+ * default). Encryption, when needed, is an *application*-authored `Schema`
+ * transform on a payload field; the codec only propagates its requirement and
+ * error channels — it owns no cipher and imports no `node:crypto`.
+ *
+ * `Decider` + `runDecider(decider, command)` close that path into the write
+ * side's whole command cycle: build the decision model, decide, append under the
+ * read's own condition. They live HERE, beside the `buildDecisionModel` they
+ * drive, rather than in `@kairos-es/testing` where they began — that package
+ * peers `@effect/vitest`, and a production command handler must not name it (see
+ * `decider.ts` for the full argument). `decider(projections, decide)` builds one
+ * with all four type arguments inferred, so a command's slice record and its
+ * 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
+ * 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                  |
+ *
+ * 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
+ * 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
+ * read returned — which is a stronger currency claim than a maintained view's
+ * checkpoint can make. `buildDecisionModel` is expressed over it, so the write
+ * path's decision model and a read-time materialisation share one body rather
+ * than two that could drift (see `decisionModel.ts` for both arguments).
+ *
+ * `decodeSlices(slices)` is the decode stage `modelAtHead` folds through,
+ * exported because the read side needs the *same* decode over a live
+ * `subscribe` stream. Exposing it keeps that single implementation shared
+ * rather than reimplemented downstream. It is deliberately ONE symbol taking
+ * the slice record, not a merge-then-decode pair: the pair had exactly one
+ * legal composition, and its only degree of freedom was to decode against a
+ * 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';
+export { type EventDef, type EventDefAny, event, type TagsFor } from './event.js';
+export { MetadataSource } from './MetadataSource.js';
+export { decideOnly, type Precondition, transact, unsafeAppend, } from './precondition.js';
+export { type ProjectionBuilder, projection, type SliceProjection, } from './projection.js';
+export { type CloseHop, type Hop, NoReadsRecorded, ReadLedger, TaglessSliceInLedger, } from './readLedger.js';
+export { makeRegistry, type Registry } from './registry.js';
+export { Serializer, SerializerDefault } from './Serializer.js';
+export { toEvent } from './toEvent.js';
+export { Uuid, UuidLive, UuidTest } from './Uuid.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsHG;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,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjD,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-esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/dts-esm/precondition.d.ts

@@ -0,0 +1,244 @@
+/**
+ * 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 } 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';
+import { NoReadsRecorded, ReadLedger, type TaglessSliceInLedger } from './readLedger.js';
+import type { Serializer } from './Serializer.js';
+import type { Uuid } from './Uuid.js';
+/**
+ * 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.Key<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 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
+ * 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.updateContext` 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 declare const unsafeAppend: (events: Arr.NonEmptyReadonlyArray<DcbEvent>, reason: string) => Effect.Effect<Position, AppendConditionFailed, DcbEventStore>;
+/**
+ * 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 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-esm/precondition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precondition.d.ts","sourceRoot":"","sources":["../../src/precondition.ts"],"names":[],"mappings":"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"}