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

package/src/readLedger.ts

@@ -0,0 +1,394 @@
+/**
+ * The ambient read ledger: the hops a bracket walked, and the single derivation
+ * that turns them into one `AppendCondition`.
+ *
+ * ## The gap this closes, and why the fix has to be ambient
+ *
+ * A decision model whose second query cannot be written until an earlier read has
+ * been folded — the identifier it needs is data that fold produced — guards its
+ * append on only the LAST read if it reaches for `buildDecisionModel` there. The
+ * append then succeeds on a premise that is no longer true, and nothing warns: it
+ * compiles, it runs, and it is silent. Two things must both change for the
+ * condition to be sound, and fixing either alone still lets the stale write
+ * through. Keeping the union of queries but taking the last head misses, because
+ * the invalidating event lands in the window between the two heads. Keeping the
+ * earliest head but taking the last query misses, because the invalidating event
+ * fails that query's TYPE arm before its tag arm is reached — which is why adding
+ * a tag to the last query cannot recover it.
+ *
+ * The ledger is an OPTIONAL AMBIENT SERVICE rather than a scope object a caller
+ * threads, and that is the whole design. A scope object's guarantee is "every read
+ * through this object", which is not "every read": `modelAtHead` stays exported
+ * and stays in scope inside the bracket, so a read that reached for the familiar
+ * name — or that happened inside a helper the body merely called — drops a hop
+ * silently. Here `modelAtHead` ITSELF records, so a read is recorded whatever
+ * symbol performed it and at whatever call depth. `Effect.serviceOption` is what
+ * makes that additive: it reads the service if present and adds NOTHING to the
+ * requirement channel, so `modelAtHead`'s published signature is untouched and no
+ * existing caller provides anything.
+ *
+ * ## Why the query is recorded eagerly and the head only on completion
+ *
+ * A `Hop` is `{ query, head? }` and the two halves are recorded at different
+ * moments: the query before a single event is streamed, the head once the fold has
+ * run to completion. So a read that opened and never finished widens the guard
+ * without contributing a floor, and both halves fail safe.
+ *
+ * The laziness is deliberate protection rather than an accident of where the line
+ * sits. Recording the head at read-return is available and MUST NOT be done: a
+ * read that failed part-way folded only a PREFIX, and a head recorded for it is a
+ * claim the hop did not earn — the floor would sit above events that read never
+ * folded, and nothing would refuse an append those events invalidate.
+ *
+ * ## An invalidated ledger must REFUSE to derive, never derive narrowly
+ *
+ * Nothing here evicts a hop, so there is no eviction policy to specify — but the
+ * rule is stated now because the moment a bound is added, and an unbounded walk on
+ * a large log will want one, the tempting implementation is to drop the oldest hop
+ * and carry on. A ledger that has lost hops must become a poison value and refuse
+ * to produce a condition at all. Deriving from a PARTIAL set is worse than
+ * refusing, because it looks like it worked: an emptied ledger produces a NARROWER
+ * condition and a silent success, which is the original hazard wearing a fix's
+ * name. The valve is coarsen, then poison. Never forget.
+ *
+ * ## What is deliberately NOT exported from the package
+ *
+ * `deriveLayeredCondition` is PACKAGE-internal and reaches no entry point. Two
+ * traps stay reachable for a caller who assembles a condition by hand, both
+ * demonstrated: concatenating query items drops a wildcard hop, an empty item list
+ * being absorbing under OR while an empty concatenation contributes nothing; and a
+ * MAXIMUM over heads reads as naturally as a minimum, two reducers of identical
+ * signature where "the position I read at" argues just as fluently for the later
+ * one. Offering the derivation as a public step would put both back within reach
+ * of the callers the bracket exists to protect.
+ */
+import type {
+  AnyProjection,
+  AppendCondition,
+  Position,
+  Query,
+} from '@kairos-es/core'
+import {
+  composeProjections,
+  ORIGIN,
+  servableQueryFault,
+  unionQueries,
+} from '@kairos-es/core'
+import { Context, Data, Effect, Layer, Option, Ref } from 'effect'
+
+/**
+ * One recorded read: the query it rode, and the head it observed.
+ *
+ * `head` is a genuinely OPTIONAL key and not `Position | undefined`, because
+ * `exactOptionalPropertyTypes` is on and the absent case must be an absent key.
+ * Absent means the read did not complete, which the derivation below treats as
+ * the widest possible floor.
+ */
+export interface Hop {
+  readonly query: Query
+  readonly head?: Position
+}
+
+/**
+ * The ambient ledger, present only inside a bracket.
+ *
+ * ⚠ A RECORDING path reads it with `Effect.serviceOption` and never
+ * `yield* ReadLedger`: its absence is the normal case there, and costing the
+ * requirement channel nothing is exactly what makes this change additive.
+ * `modelAtHead` is that path and is why the rule exists.
+ *
+ * A BRACKET-ONLY function is the opposite case and yields the tag deliberately.
+ * `decideOnly` does, and naming the requirement is what turns *"call me inside a
+ * bracket"* from a runtime defect into a compile error — presence being the one
+ * direction the type system can decide here. So the test is what the function
+ * means outside a bracket: nothing (record ambiently), or nothing sensible
+ * (require it).
+ *
+ * Recording is two-phase, and `record`'s own doc below owns why and what shape the
+ * second phase takes.
+ */
+export class ReadLedger extends Context.Tag('@kairos-es/codec/ReadLedger')<
+  ReadLedger,
+  {
+    /**
+     * File a query, and hand back the effect that will fill in its head.
+     *
+     * Two phases and not one `record(hop)`, which is what the eager/lazy split
+     * above needs: a one-shot recorder cannot express a hop whose head never
+     * arrives, and that is the case the whole fail-safe direction turns on.
+     *
+     * The second phase comes back as a CLOSURE rather than as a slot number the
+     * caller carries to a second method. The closure holds its own slot, so
+     * nothing threads an index through the reader, nothing looks the service up a
+     * second time to spend it, and there is no slot value for a caller to hold
+     * wrongly.
+     */
+    readonly record: (query: Query) => Effect.Effect<CloseHop>
+    readonly hops: Effect.Effect<ReadonlyArray<Hop>>
+  }
+>() {}
+
+/**
+ * Fill in a recorded hop's head. Never called if the read does not complete.
+ *
+ * On the package's public surface because it is already ON it: `record` returns
+ * one, `ReadLedger` is exported, so a consumer holding the tag holds this type and
+ * could not name it. `Hop` was exported and this was not — the same interface, two
+ * treatments.
+ */
+export type CloseHop = (head: Position) => Effect.Effect<void>
+
+/**
+ * Raised when a bracket closes having recorded no read at all.
+ *
+ * On the ERROR channel and deliberately split from the nested-append DEFECT,
+ * because the two are different mistakes. An empty bracket can arise from a
+ * data-dependent branch that produces events without reading — a genuinely
+ * unconditional creation, written inside a bracket by mistake — where a nested
+ * append is always a wiring fault. An error-channel value lets a caller decide
+ * which it is.
+ *
+ * Its job is narrower than it looks, and the narrowing is worth stating because
+ * the wider reading is the tempting one. Once a bracket's guard is itself a fold,
+ * a body that reads nothing still has a hop, so this cannot fire — it is the guard
+ * against an unguarded UNCONDITIONAL bracket, not against an unguarded bracket. A
+ * bracket that looks guarded and is not is NOT what this catches and never was,
+ * and nothing else catches it either — `precondition.ts` owns that gap and the
+ * rule a reader has to keep in its place. A refusal taken BEFORE reading is not
+ * this case either: it short-circuits and surfaces as the refusal.
+ */
+export class NoReadsRecorded extends Data.TaggedError('NoReadsRecorded')<
+  Record<never, never>
+> {
+  /**
+   * The sentence, as the `Error` field that says why — so the fault renders
+   * ITSELF, exactly as this package's other two errors do (`errors.ts` owns the
+   * argument for the mechanism and it is not restated here).
+   *
+   * A getter over a constant rather than a constructor field, because there is no
+   * datum to vary: every raise of this error means one thing.
+   */
+  override get message(): string {
+    return (
+      'the bracket closed having recorded no read, so there is no append condition ' +
+      'to derive. A decision that reads nothing is unconditional — say so with the ' +
+      'escape hatch, which takes a reason, rather than by opening a bracket.'
+    )
+  }
+}
+
+/**
+ * Raised when recording a hop would leave the bracket's accumulated union
+ * unservable.
+ *
+ * The store refuses a multi-item query in which any item is tagless, and it
+ * refuses it by THROWING inside the append decorator, which becomes a defect:
+ * uncatchable, one call and one layer away from the `build()` that chose no tags.
+ * A slice built without tags defaults to none, so it is perfectly servable alone
+ * and kills the append the moment it is unioned. This moves that failure onto the
+ * error channel, to the read that caused it, naming the record entry to fix.
+ *
+ * It refuses an unservable UNION and not every tagless hop, which is the easy
+ * mistake to make in the other direction: one tagless slice read on its own is
+ * servable and must keep working. Two cases reach it — a tagless hop unioned with
+ * another, and a single hop whose own RECORD holds two tagless slices, which
+ * composes to a multi-item query with no second hop needed.
+ */
+export class TaglessSliceInLedger extends Data.TaggedError(
+  'TaglessSliceInLedger',
+)<{ readonly sliceKey: string }> {
+  /** The offending slice and the remedy, in one sentence. */
+  override get message(): string {
+    return (
+      `slice '${this.sliceKey}' was built with no tags, and this bracket now reads ` +
+      'more than one slice. A layered append condition unions every query it ' +
+      'recorded, and the store refuses a multi-item query if any item is tagless. ' +
+      'Pass `build({ tags: [...] })` for this slice.'
+    )
+  }
+}
+
+/**
+ * The ONE derivation: the union of every query walked, at the earliest head
+ * observed. Package-internal, for the reason the module doc gives.
+ *
+ * The union goes through core's own `unionQueries` — the merge
+ * `composeProjections` folds a record through, reached without one — and never a
+ * spread of `items`, because a wildcard hop (`items: []`) is ABSORBING under OR
+ * while a spread of an empty list contributes nothing, so hand-rolling the union
+ * narrows a match-everything hop to its sibling, silently and in the unsafe
+ * direction. A
+ * repeated or overlapping hop is harmless because this derives ONCE from a merged
+ * set and matching is idempotent over an OR; that property belongs to deriving
+ * once and would be lost by a refactor to per-hop evaluation.
+ *
+ * ## When any hop is headless the floor is `ORIGIN`, and the alternative is unsound
+ *
+ * The earliest head that actually ARRIVED is refused, and is named here as refused
+ * rather than merely not chosen, because it is what a reader writes by accident
+ * when told to take the earliest head. With one headless hop among completed hops
+ * the union looks right and the floor betrays it, sitting already above the
+ * invalidating event.
+ *
+ * `ORIGIN`'s cost is measured rather than described: it refuses every append to
+ * any identity that already has history, so it is not a conservative default but a
+ * hard stop. It is affordable only because conflict retry wraps the bracket from
+ * OUTSIDE and re-reads, which is the rule the whole shape depends on.
+ */
+export const deriveLayeredCondition = (
+  hops: ReadonlyArray<Hop>,
+): AppendCondition | undefined => {
+  if (hops.length === 0) {
+    return undefined
+  }
+  const merged = unionQueries(hops.map((hop) => hop.query))
+
+  const arrived = hops.flatMap((hop) =>
+    hop.head === undefined ? [] : [hop.head],
+  )
+  // A headless hop widens the guard to the whole log. Unioning its query is the
+  // half that is not in dispute; the floor is where the two readings diverge.
+  const after =
+    arrived.length === hops.length
+      ? arrived.reduce((a, b) => (b < a ? b : a))
+      : ORIGIN
+
+  return { failIfEventsMatch: merged, after }
+}
+
+/**
+ * A fresh ledger and the `Layer` providing it: a `Ref` of hops behind the two-phase
+ * `record` the service declares.
+ *
+ * The hops effect is handed back beside the layer because the bracket reads them
+ * AFTER the body has run and the layer is out of scope, which is the same moment it
+ * stops being able to reach the service.
+ */
+export const makeReadLedger: Effect.Effect<{
+  readonly layer: Layer.Layer<ReadLedger>
+  readonly hops: Effect.Effect<ReadonlyArray<Hop>>
+}> = Effect.gen(function* () {
+  const ref = yield* Ref.make<ReadonlyArray<Hop>>([])
+  return {
+    layer: Layer.succeed(ReadLedger, {
+      record: (query: Query) =>
+        Ref.modify(ref, (hops) => [
+          // The close effect closes over the slot this hop just took, so the slot
+          // never becomes a value anything else has to carry or interpret.
+          (head: Position) =>
+            Ref.update(ref, (current) =>
+              current.map((hop, index) =>
+                index === hops.length ? { query: hop.query, head } : hop,
+              ),
+            ),
+          [...hops, { query }],
+        ]),
+      hops: Ref.get(ref),
+    }),
+    // The same effect the service exposes, reachable AFTER the layer is out of
+    // scope — which is exactly when the bracket derives.
+    hops: Ref.get(ref),
+  }
+})
+
+/**
+ * Run `f` against the ambient ledger, or answer `absent` when there is none.
+ *
+ * "Outside a bracket this is a no-op" is ONE fact stated once, rather than one
+ * per consumer free to drift from the others. Every ambient lookup in this module
+ * goes through here, which is also what keeps `Effect.serviceOption` — the reason
+ * nothing enters the requirement channel — from being a detail each caller has to
+ * remember.
+ */
+const withLedger = <A, E = never>(
+  absent: A,
+  f: (ledger: Context.Tag.Service<ReadLedger>) => Effect.Effect<A, E>,
+): Effect.Effect<A, E> =>
+  Effect.flatMap(Effect.serviceOption(ReadLedger), (ledger) =>
+    Option.isNone(ledger) ? Effect.succeed(absent) : f(ledger.value),
+  )
+
+/** A close effect that does nothing: what a read outside a bracket gets back. */
+const NO_CLOSE: CloseHop = () => Effect.void
+
+/**
+ * File a query into the ambient ledger if there is one, and hand back the effect
+ * that completes it. Outside a bracket the whole thing is a no-op, and the caller
+ * still writes one line rather than a conditional.
+ */
+export const recordQuery = (query: Query): Effect.Effect<CloseHop> =>
+  withLedger(NO_CLOSE, (ledger) => ledger.record(query))
+
+/** The tagless slice keys in a record, in declaration order. */
+const taglessKeys = (
+  projections: Record<string, AnyProjection>,
+): ReadonlyArray<string> =>
+  Object.entries(projections)
+    .filter(([, projection]) =>
+      projection.query.items.some((item) => item.tags.length === 0),
+    )
+    .map(([key]) => key)
+
+/** Would recording this record's query leave the accumulated union unservable? */
+const unionWouldBeUnservable = (
+  existing: ReadonlyArray<Hop>,
+  incoming: Query,
+): boolean =>
+  servableQueryFault(
+    unionQueries([...existing.map((h) => h.query), incoming]),
+  ) !== undefined
+
+/**
+ * Refuse a read that would leave the bracket's accumulated union unservable,
+ * BEFORE the read is paid for.
+ *
+ * Servability is answerable from the queries alone, so the check runs when a hop is
+ * recorded rather than at append time — the eager half of the eager/lazy split doing
+ * one more job. Outside a bracket nothing is unioned and nothing is unservable, so
+ * the ordinary single-hop caller is untaxed.
+ *
+ * It judges the PROSPECTIVE UNION and asks core for the verdict, which is what makes
+ * both failing shapes one case rather than two. An earlier version tested each
+ * recorded query separately and treated a FIRST hop as unconditionally fine — but a
+ * hop is a RECORD, and a record of two tagless slices composes to a multi-item query
+ * that is unservable on its own. That read died at the store, uncatchably, on the
+ * exact path this error exists to keep off the defect channel. A grammar with two
+ * homes drifts at the shapes neither author had in mind, so there is one home and it
+ * is `servableQueryFault`'s.
+ *
+ * Where the OFFENDING slice is THIS record's the ledger can name its key; where it
+ * belongs to an earlier hop it can only say so, a recorded hop keeping its query
+ * rather than the key it was composed from. That asymmetry is diagnostic-only and is
+ * why the message is built from a key that may be a placeholder.
+ */
+export const assertServableAddition = (
+  projections: Record<string, AnyProjection>,
+): Effect.Effect<void, TaglessSliceInLedger> =>
+  withLedger<void, TaglessSliceInLedger>(undefined, (ledger) =>
+    Effect.flatMap(ledger.hops, (existing) => {
+      const incoming = composeProjections(projections).query
+      if (!unionWouldBeUnservable(existing, incoming)) {
+        return Effect.void
+      }
+      // The offending key where the tagless slice is THIS record's, and a
+      // placeholder where it belongs to an earlier hop — a recorded hop keeps its
+      // query rather than the key it was composed from.
+      const offending = taglessKeys(projections)[0] ?? '<an earlier hop>'
+      return new TaglessSliceInLedger({ sliceKey: offending })
+    }),
+  )
+
+/**
+ * The condition the ambient ledger derives right now, or `None` outside a bracket.
+ *
+ * This is what makes `buildDecisionModel` correct inside a bracket: the call whose
+ * current behaviour is the hazard derives from every hop the bracket walked rather
+ * than from its own single read.
+ */
+export const ambientLayeredCondition: Effect.Effect<
+  Option.Option<AppendCondition>
+> = withLedger(Option.none<AppendCondition>(), (ledger) =>
+  Effect.map(ledger.hops, (hops) =>
+    Option.fromNullable(deriveLayeredCondition(hops)),
+  ),
+)