@kairos-es/core 1.0.0-alpha.0 → 1.0.0-alpha.1

package/src/Query.ts

@@ -99,20 +99,50 @@ export const matchesSequenced = (
  * engine" behaviour.
  */
 export const assertServableQuery = (query: Query): void => {
+  const fault = servableQueryFault(query)
+  if (fault !== undefined) {
+    throw new Error(fault)
+  }
+}
+
+/**
+ * The servable grammar as a TOTAL function: the reason `query` cannot be served,
+ * or `undefined` when it can.
+ *
+ * The same rule as `assertServableQuery` above and NOT a second statement of it —
+ * that function is this one plus a throw, so the grammar is defined once and the
+ * two differ only in DISPOSITION. A store boundary wants the defect, because a
+ * non-servable query there is a programming error with no recovery; a caller that
+ * can still act on the answer wants a value, and the codec's read ledger is one:
+ * it asks whether a hop it is about to record would make the accumulated union
+ * unservable, and refuses on the error channel BEFORE the read is paid for.
+ *
+ * The alternative was for that caller to re-derive the rule, and it was tried:
+ * the codec's own copy tested each recorded query separately, which silently
+ * admitted a FIRST hop composed of two tagless slices — a multi-item query, and
+ * unservable, dying at the store one layer away. A grammar with two homes drifts
+ * at exactly the shapes neither author had in mind. The shape here is the read
+ * side's own (`projectionWiringFault` returns `string | undefined` for the same
+ * reason), so a fault is one exit route and one return type.
+ */
+export const servableQueryFault = (query: Query): string | undefined => {
   const { items } = query
   // Wildcard and single-item queries are always servable.
   if (items.length <= 1) {
-    return
+    return undefined
   }
   // A multi-item query is servable only if every item is tagged; a tagless
   // (type-only) item mixed with tagged items cannot ride a single index.
-  const hasTaglessItem = items.some((item) => item.tags.length === 0)
-  if (hasTaglessItem) {
-    throw new Error(
-      'assertServableQuery: a multi-item query must have every item carry at ' +
-        'least one tag; a type-only item mixed with tagged items is not servable',
-    )
-  }
+  // The `assertServableQuery:` prefix is part of the MESSAGE and not something the
+  // throw adds, so both dispositions emit byte-identical text. It names the rule in
+  // the vocabulary a store rejects in, which is what lets the read side's wiring gate
+  // report a violation in the same words a store would — an author who meets it in
+  // both places meets it once. Building it here is also what stops a second caller
+  // re-deriving the prefix to match.
+  return items.some((item) => item.tags.length === 0)
+    ? 'assertServableQuery: a multi-item query must have every item carry at ' +
+        'least one tag; a type-only item mixed with tagged items is not servable'
+    : undefined
 }
 
 /**

package/src/index.ts

@@ -4,11 +4,15 @@
  *
  * Exposes the domain types (`DcbEvent`, `SequencedEvent`, `Position`, `Tag`,
  * `EventType`), the selection language (`Query`, `QueryItem`, the pure match
- * predicate + smart constructors, and the servable-shape dispatch every engine
- * compiles its plans through), the `AppendCondition`, tagged errors, the
- * `DcbEventStore` contract, the in-memory layer, the shared subscribe machine
+ * predicate + smart constructors, the servable grammar in both its dispositions —
+ * `assertServableQuery`'s throw and `servableQueryFault`'s total `string |
+ * undefined` — and the servable-shape dispatch every engine compiles its plans
+ * through), the `AppendCondition`, tagged errors, the
+ * `DcbEventStore` contract, `AppendIsOwned` and the refusal every engine's `append`
+ * inherits from it, the in-memory layer, the shared subscribe machine
  * every engine's `subscribe` is built from (`SubscribeMachine.ts`), the pure
- * projection primitives (`Projection`, `DecodedEvent`, `composeProjections`), and
+ * projection primitives (`Projection`, `DecodedEvent`, `composeProjections` and the
+ * `unionQueries` its query merge is reachable through without a record), and
  * `retryOnConflict`.
  *
  * Core keeps only the *pure* fold: projections fold an already-`DecodedEvent`
@@ -23,6 +27,7 @@
  * write-only consumer depend on a package it uses nothing else of (ADR-0008).
  */
 export * from './AppendCondition'
+export * from './AppendIsOwned'
 export * from './ContractStore'
 export * from './DcbEventStore'
 export * from './Event'