@githolon/dsl 0.1.0

package/src/sum.ts

@@ -0,0 +1,194 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * `sum(id, field)` builder — the NUMERIC AGGREGATION sibling of `count`.
+ *
+ * A `sum` declares a NAMED, MAINTAINED running total of an `int`-kind field across
+ * every aggregate of the `of`-type (optionally filtered by a `.where(pred)` predicate
+ * and partitioned by a `.by(field)` group-by). The result is ONE number per group,
+ * maintained incrementally as the workspace folds — NEVER a `SUM(*)` scan (the same
+ * O(1) perf invariant as `count`).
+ *
+ * The TYPE-STATE mirrors `count.ts` exactly:
+ *   `sum(id, field)` → `TypelessSum` (only `.of` available)
+ *   `.of(agg)`       → `Sum` builder (`.where`, `.by` available; grand-total usable)
+ *   `.where(p)`      → `Sum` with predicate baked in (`.by` still available)
+ *   `.by(k)`         → `SumDecl` (finished, grouped declaration)
+ *
+ * Both a bare `Sum` (grand-total) and a grouped `SumDecl` satisfy `AnySum` — what
+ * `DomainModule.sums` accepts. `finishSum` normalizes either to a `SumDecl`.
+ *
+ * VALIDATION RULE (manifest-load, not type-level): the `sumField` parameter MUST be
+ * an `int`-kind field of the `of`-aggregate. The DSL type system cannot enforce this
+ * at the `sum(id, sumField)` call site (the aggregate is not yet known), but
+ * `AggregateSchemas::parse` (readmodel/src/manifest.rs) performs a no-fallback reject
+ * if the field is absent or non-int on the declared aggregate.
+ *
+ * ORDER-SENSITIVE GUARDRAIL: sum exposes NO `.first`/`.take`/`.orderBy`. Same
+ * rationale as `count.ts`. Assert the absence; do NOT add dead methods (LAW 3).
+ *
+ * SUM-OF-0 AMBIGUITY (documented, acceptable for Slice 1): a group whose running
+ * total reaches 0 is pruned from the `sums` table and reads as 0 — indistinguishable
+ * from an absent group. A future `exists` primitive (Slice 2) handles the distinction.
+ */
+import type { AggregateHandle } from "./aggregate.js";
+import type { Field } from "./fields.js";
+import { type Predicate, type CanonicalPred, predBuilder, canonicalizePred } from "./predicate.js";
+
+/**
+ * A FINISHED sum declaration (the read-engine's input shape, analogous to
+ * {@link CountDecl}): an id, the aggregate TYPE it tallies, the FIELD being summed,
+ * the OPTIONAL predicate, and the OPTIONAL group-by field.
+ */
+export interface SumDecl {
+  readonly id: string;
+  /** The aggregate TYPE id the sum tallies, e.g. `ListingAggregate`. */
+  readonly of: string;
+  /**
+   * The `int`-kind field being summed, e.g. `"quantity"` or `"itemValue"`. MUST
+   * be an `int`-kind field of the `of`-aggregate (validated at manifest-load).
+   */
+  readonly sumField: string;
+  /**
+   * The optional predicate: ONLY aggregates satisfying this predicate contribute
+   * to the sum. ABSENT ⇒ every aggregate of the `of`-type is summed.
+   */
+  readonly where?: CanonicalPred;
+  /**
+   * The group-by field name. ABSENT ⇒ a grand total across all (matching)
+   * aggregates of the `of`-type (one synthetic group).
+   */
+  readonly by?: string;
+}
+
+/**
+ * The `Sum` BUILDER: it has named its `of`-type (and summed field), so `.where(...)`
+ * and `.by(...)` are available. The `F` type parameter carries the `of`-aggregate's
+ * field map so `.where(p => p.field("status").eq("active"))` is keyof-checked.
+ */
+export interface Sum<F extends Record<string, Field> = Record<string, Field>> {
+  readonly id: string;
+  /** The aggregate TYPE id the sum tallies. */
+  readonly of: string;
+  /** The `int`-kind field being summed. */
+  readonly sumField: string;
+  /**
+   * Attach an optional PREDICATE: only aggregates satisfying the predicate contribute
+   * to the sum. Returns a new `Sum` with the predicate baked in; `.by(...)` is still
+   * available.
+   */
+  where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): Sum<F>;
+  /**
+   * Partition the sum by a GROUP-BY field. Every distinct value of `groupField`
+   * maintains its own running total. Returns a finished `SumDecl`.
+   */
+  by(groupField: string): SumDecl;
+}
+
+/**
+ * The INITIAL, un-typed sum — its ONLY method is `.of(...)`. A `sum(id, field)`
+ * without `.of(...)` cannot be used as a declaration: the aggregate type is not
+ * optional.
+ */
+export interface TypelessSum {
+  readonly id: string;
+  /** The `int`-kind field to sum. */
+  readonly sumField: string;
+  /**
+   * Declare the aggregate TYPE whose `sumField` values are summed. Takes a typed
+   * HANDLE (never a string id). Returns the `Sum` builder (the only shape exposing
+   * `.where` and `.by`), which is already a usable grand-total sum.
+   */
+  of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): Sum<F>;
+}
+
+/**
+ * Either form a domain may declare in `DomainModule.sums`. `Sum<any>` for the same
+ * reason as `AnyCount = CountDecl | Count<any>`: `Sum<F>` is invariant in `F`
+ * (the `where` method), so `Sum<SpecificFields>` is not assignable to
+ * `Sum<Record<string,Field>>`. The consumer only accesses `id`/`of`/`sumField`/`by`
+ * string fields and the `_where` slot — it never calls `.where(fn)` — so `any` is safe.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnySum = SumDecl | Sum<any>;
+
+/** Narrow: a `Sum` builder exposes a `by` METHOD; a `SumDecl` does not. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isSumBuilder(s: AnySum): s is Sum<any> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return typeof (s as Sum<any>).by === "function";
+}
+
+/**
+ * Normalize an `AnySum` to a finished `SumDecl`. The grand-total builder (bare
+ * `.of(...)`) becomes `{id, of, sumField}` (no `by`); a grouped `.by(...)` result is
+ * already a `SumDecl` and passes through. A `.where(pred)` result transfers the
+ * canonical predicate.
+ */
+export function finishSum(s: AnySum): SumDecl {
+  if (isSumBuilder(s)) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const b = s as any;
+    const w: CanonicalPred | undefined = b._where;
+    return {
+      id: b.id,
+      of: b.of,
+      sumField: b.sumField,
+      ...(w !== undefined ? { where: w } : {}),
+    };
+  }
+  return s;
+}
+
+/** Internal factory so `.where(...)` can return a new Sum without duplicating impl. */
+function makeSum<F extends Record<string, Field>>(
+  id: string,
+  ofType: string,
+  sumField: string,
+  where: CanonicalPred | undefined,
+): Sum<F> {
+  // Same exactOptionalPropertyTypes pattern as makeCount: spread `_where` only when
+  // defined so the key is absent (not `undefined`) in the predicate-free case.
+  const s = {
+    id,
+    of: ofType,
+    sumField,
+    ...(where !== undefined ? { _where: where } : {}),
+    where(fn: (p: ReturnType<typeof predBuilder<F>>) => Predicate<F>): Sum<F> {
+      const pred = fn(predBuilder<F>());
+      const canonical = canonicalizePred(pred as Predicate<Record<string, Field>>);
+      return makeSum<F>(id, ofType, sumField, canonical);
+    },
+    by(groupField: string): SumDecl {
+      return {
+        id,
+        of: ofType,
+        sumField,
+        ...(where !== undefined ? { where } : {}),
+        by: groupField,
+      };
+    },
+  } as unknown as Sum<F>;
+  return s;
+}
+
+/**
+ * Begin a sum declaration. `id` is the sum's canonical name (e.g.
+ * `"totalItemValuePerSite"`); `sumField` is the `int`-kind field on the `of`-aggregate
+ * whose values are accumulated. Returns a `TypelessSum`: until `.of(aggregate)` is
+ * called, the aggregate type is unknown and no usable declaration exists.
+ */
+export function sum(id: string, sumField: string): TypelessSum {
+  return {
+    id,
+    sumField,
+    of<F extends Record<string, Field>>(aggregate: AggregateHandle<string, F>): Sum<F> {
+      return makeSum<F>(id, aggregate.id, sumField, undefined);
+    },
+  };
+}