@noorm/broccolidb 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BroccoliDB contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# @noorm/broccolidb
+
+Portable, dependency-free in-memory tables with explicit file-backed durability.
+
+BroccoliDB is an embeddable TypeScript database kernel for applications that
+want a fast table hot path without SQLite, Kysely, a native addon, or a server
+process. Records live in memory for reads and indexes; the kernel persists
+mutations through a micro-batched, checksum-linked write-ahead log (WAL),
+periodic JSON checkpoints, and an optional content-addressable storage (CAS)
+vault for large blobs.
+
+> BroccoliDB is a table-first embedded library, not a SQL engine or a remote
+> database service. Its public contracts are TypeScript interfaces and
+> deterministic file formats.
+
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ES2022-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-0-2ea44f)](#portability-and-boundaries)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+## Table of contents
+
+- [At a glance](#at-a-glance)
+- [Quick start](#quick-start)
+- [How durability works](#how-durability-works)
+- [Public surface](#public-surface)
+- [Storage layout](#storage-layout)
+- [Portability and boundaries](#portability-and-boundaries)
+- [Documentation](#documentation)
+- [Development and verification](#development-and-verification)
+- [Compatibility policy](#compatibility-policy)
+- [License](#license)
+
+## At a glance
+
+| Capability | What it provides |
+|---|---|
+| In-memory tables | Typed records, CRUD, bulk writes, TTL expiration, snapshots, and reactive change events |
+| Indexes | Equality, sorted/range, composite, and prefix indexes |
+| Queries | Operator filters, boolean clauses, ordering, pagination, a fluent builder, and deterministic natural-language parsing |
+| Aggregation | `sum`, `avg`, `min`, `max`, `count`, `stddev`, grouping, `having`, and grand totals |
+| Durability | Micro-batched WAL frames, checksum validation, checkpoint rotation, replay, and rollback |
+| Blob storage | SHA-256 addressed files, optional Brotli compression, read verification, quarantine, and garbage collection |
+| Coordination | Re-entrant async mutex and kernel-level transaction boundary |
+| Portability | ESM package, Node built-ins only at runtime, no SQLite or native ABI |
+
+## Quick start
+
+```bash
+npm install @noorm/broccolidb
+```
+
+```ts
+import { BroccoliDatabaseKernel } from "@noorm/broccolidb"
+
+type User = {
+  id: string
+  name: string
+  team: string
+  active: boolean
+}
+
+const db = new BroccoliDatabaseKernel({ workspaceRoot: "./state" })
+await db.start()
+
+const users = db.getTable<User>("users")
+users.createIndex("team")
+users.createIndex("active")
+
+await db.transaction(async () => {
+  users.put("user-1", { id: "user-1", name: "Ada", team: "platform", active: true })
+  users.put("user-2", { id: "user-2", name: "Grace", team: "platform", active: false })
+})
+
+const activePlatformUsers = users.query({
+  where: { team: "platform", active: true },
+})
+
+console.log(activePlatformUsers)
+console.log(await db.health())
+
+await db.checkpoint("after-initial-users")
+await db.stop()
+```
+
+The package is ESM-only. The `workspaceRoot` directory is created on demand;
+the kernel stores its durable state below `workspaceRoot/.broccolidb/`.
+
+## How durability works
+
+```mermaid
+flowchart LR
+    A[Table mutation] --> B[In-memory table and indexes]
+    B --> C[WAL frame]
+    C --> D[Micro-batched flush]
+    D --> E[.broccolidb/wal.log]
+    B --> F[Checkpoint]
+    F --> G[checkpoint.db]
+    F --> H[checkpoints/id.json]
+    E --> I[Startup replay]
+    G --> I
+    I --> B
+```
+
+A mutation updates the in-memory table immediately and schedules a WAL frame.
+Call `flush()`, use `transaction()`, call `checkpoint()`, or shut down with
+`stop()` when the application needs the buffered frames written before it
+continues. On the next `start()`, BroccoliDB loads the latest base checkpoint
+and replays the remaining WAL frames.
+
+For a stable restore point, use:
+
+```ts
+const checkpoint = await db.checkpoint("before-import")
+// ... perform work ...
+await db.rollback(checkpoint.checkpointId)
+```
+
+The checkpoint record contains a timestamp, frame index, record counts, and a
+SHA-256 hash of the serialized table snapshot. See the [operations guide](docs/OPERATIONS.md)
+for backup, corruption, and multi-process guidance.
+
+## Public surface
+
+The package entry point re-exports the contracts and implementations needed by
+an embedding application:
+
+| Area | Primary exports | Source |
+|---|---|---|
+| Kernel | `BroccoliDatabaseKernel`, `broccolidb`, `DatabaseKernelOptions` | `src/broccolidb-kernel.ts` |
+| Tables and contracts | `IDbTable`, `DbQueryOptions`, `DbPutOptions`, index/query/change types | `src/broccolidb.contracts.ts` |
+| Queries | `BroccoliNaturalQueryParser`, `IFluentQueryBuilder` | `src/broccolidb-natural-query.ts` and contracts |
+| Aggregation | `DbAggregateQuery`, `DbAggregateResult`, aggregate metrics | `src/broccolidb-aggregation.ts` and contracts |
+| WAL | `BroccoliWriteAheadLog`, `WalIntegrityError`, `WalFrame` | `src/broccolidb-wal.ts` |
+| CAS | `BroccoliCASStorageService`, `StorageIntegrityError` | `src/broccolidb-cas.ts` |
+| Locking | `ReentrantAsyncMutex`, `DatabaseLockError`, `DeadlockTimeoutError` | `src/broccolidb-mutex.ts` |
+| Prompt compression | `TokenCompressionService`, `tokenCompressionService` | `src/TokenCompressionService.ts` |
+
+The detailed signatures and examples live in the [API reference](docs/API.md).
+
+## Storage layout
+
+```text
+<workspaceRoot>/
+└── .broccolidb/
+    ├── wal.log                  # append-only JSONL mutation journal
+    ├── wal.log.old              # previous journal after checkpoint rotation
+    ├── checkpoint.db            # latest atomic base snapshot
+    ├── checkpoints/<id>.json    # named checkpoint history
+    └── cas/
+        ├── blobs/<00-ff>/<sha>  # content-addressed payloads
+        └── corrupt/             # quarantined payloads and manifest.jsonl
+```
+
+Treat this directory as application state. Back it up only while the kernel is
+stopped or after an explicit `flush()`/`checkpoint()`. Do not edit WAL or
+checkpoint files by hand; a malformed WAL frame raises `WalIntegrityError`.
+
+## Portability and boundaries
+
+BroccoliDB intentionally has:
+
+- zero production dependencies in `package.json`;
+- no SQLite, `better-sqlite3`, Kysely, native modules, or Electron ABI coupling;
+- no network service, daemon, or background process;
+- ordinary JSON, JSONL, SHA-256, Brotli, and filesystem primitives;
+- a Node.js `>=18` engine requirement.
+
+BroccoliDB does not provide SQL parsing, migrations, a cross-process lock, a
+replicated log, or provider-specific billing/token accounting. The prompt token
+compressor uses a four-characters-per-token estimate as a budget signal, not as
+an API provider billing measurement.
+
+## Documentation
+
+The documentation follows a layered path: **Concepts → How it works →
+Reference → Operations → Decisions**.
+
+- [Documentation map](docs/README.md) — choose a reading path by role.
+- [Brief](docs/BRIEF.md) — problem, solution, guarantees, and fit.
+- [Architecture](docs/ARCHITECTURE.md) — layers, lifecycle, files, and failure model.
+- [API reference](docs/API.md) — public types, methods, and query examples.
+- [Operations guide](docs/OPERATIONS.md) — durability, backup, recovery, health, and GC.
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — symptom → cause → action runbooks.
+- [Glossary](docs/GLOSSARY.md) — canonical vocabulary.
+- [Design philosophy](docs/PHILOSOPHY.md) — principles and rejected alternatives.
+- [Architecture decisions](docs/adr/README.md) — durable decisions and their consequences.
+- [Contributing](docs/CONTRIBUTING.md) — source map, workflow, and contract checklist.
+- [Release notes](docs/RELEASE_NOTES.md) — supported package history.
+
+## Development and verification
+
+```bash
+npm install
+npm run build
+npm test
+npm run docs:check
+npm run check
+npm pack --dry-run
+```
+
+`npm test` builds the package and runs the TypeScript tests under `test/`.
+`npm run docs:check` verifies the documentation map and required relative
+links. `npm run check` is the release-oriented local gate.
+
+## Compatibility policy
+
+The standalone package is the supported BroccoliDB implementation. The removed
+in-repository SQLite implementation is not a compatibility target. New code
+should import `@noorm/broccolidb` from the package entry point and should not
+recreate a private table/WAL implementation inside an application.
+
+Changes to exported types, on-disk formats, WAL replay, checkpoint structure, or
+CAS integrity behavior require an API/operations documentation update and an
+entry in the ADR or release notes.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/TokenCompressionService.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Minimal message shape accepted by the prompt compressor.
+ * The generic keeps provider-specific message metadata intact while the
+ * compressor only rewrites textual content.
+ */
+export interface TokenCompressionMessage {
+    role?: string;
+    content?: unknown;
+}
+export interface TokenCompressionRequest<T extends TokenCompressionMessage = TokenCompressionMessage> {
+    systemPrompt?: string;
+    messages: readonly T[];
+    requestedModel?: string;
+}
+export interface TokenCompressionResult<T extends TokenCompressionMessage = TokenCompressionMessage> {
+    compactedSystemPrompt?: string;
+    compactedMessages: T[];
+    originalEstimatedTokens: number;
+    compactedEstimatedTokens: number;
+    tokensSaved: number;
+    compressionRatioPct: number;
+    promptSha256: string;
+    /** The requested model is echoed without routing or model substitution. */
+    recommendedModel: string;
+    cachedL1: boolean;
+}
+/**
+ * BroccoliDB implementation of GALXAI's deterministic prompt compression
+ * strategy. It is deliberately lossless at the semantic level: only line
+ * endings, repeated whitespace, and empty-line runs are normalized. Structured
+ * provider blocks remain structured so tool calls, images, and signatures are
+ * never serialized into plain text by the optimization pass.
+ */
+export declare class TokenCompressionService {
+    private static instance;
+    private static readonly MAX_L1_ENTRIES;
+    private readonly l1Cache;
+    private constructor();
+    static getInstance(): TokenCompressionService;
+    /**
+     * Estimates tokens with the same fast four-characters-per-token heuristic as
+     * the source strategy. This is a budget signal, not provider billing data.
+     */
+    static estimateTokens(text: string): number;
+    /**
+     * Compacts a prompt at the request boundary and reuses exact L1 results by
+     * SHA-256 of the unmodified prompt payload.
+     */
+    compactPrompt<T extends TokenCompressionMessage>(input: TokenCompressionRequest<T>): TokenCompressionResult<T>;
+    /** Clears the process-local cache. Intended for lifecycle cleanup and tests. */
+    clear(): void;
+    private estimatePromptTokens;
+    private serializeContent;
+    private normalizeContent;
+    private normalizeText;
+    private copyMessages;
+}
+export declare const tokenCompressionService: TokenCompressionService;
+//# sourceMappingURL=TokenCompressionService.d.ts.map

package/dist/TokenCompressionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TokenCompressionService.d.ts","sourceRoot":"","sources":["../src/TokenCompressionService.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,uBAAuB,GAAG,uBAAuB;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,uBAAuB,GAAG,uBAAuB;IACjG,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iBAAiB,EAAE,CAAC,EAAE,CAAC;IACvB,uBAAuB,EAAE,MAAM,CAAC;IAChC,wBAAwB,EAAE,MAAM,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAID;;;;;;GAMG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAsC;IAC7D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAS;IAE/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IAEtE,OAAO;WAEO,WAAW,IAAI,uBAAuB;IAOpD;;;OAGG;WACW,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAKlD;;;OAGG;IACI,aAAa,CAAC,CAAC,SAAS,uBAAuB,EACpD,KAAK,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAChC,sBAAsB,CAAC,CAAC,CAAC;IAwD5B,gFAAgF;IACzE,KAAK,IAAI,IAAI;IAIpB,OAAO,CAAC,oBAAoB;IAW5B,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,gBAAgB;IAoDxB,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,YAAY;CAarB;AAED,eAAO,MAAM,uBAAuB,yBAAwC,CAAC"}

package/dist/TokenCompressionService.js

@@ -0,0 +1,179 @@
+// [LAYER: CORE]
+// @classification PURE
+import { createHash } from 'node:crypto';
+/**
+ * BroccoliDB implementation of GALXAI's deterministic prompt compression
+ * strategy. It is deliberately lossless at the semantic level: only line
+ * endings, repeated whitespace, and empty-line runs are normalized. Structured
+ * provider blocks remain structured so tool calls, images, and signatures are
+ * never serialized into plain text by the optimization pass.
+ */
+export class TokenCompressionService {
+    static instance;
+    static MAX_L1_ENTRIES = 1_000;
+    l1Cache = new Map();
+    constructor() { }
+    static getInstance() {
+        if (!TokenCompressionService.instance) {
+            TokenCompressionService.instance = new TokenCompressionService();
+        }
+        return TokenCompressionService.instance;
+    }
+    /**
+     * Estimates tokens with the same fast four-characters-per-token heuristic as
+     * the source strategy. This is a budget signal, not provider billing data.
+     */
+    static estimateTokens(text) {
+        if (!text)
+            return 0;
+        return Math.max(1, Math.ceil(text.length / 4));
+    }
+    /**
+     * Compacts a prompt at the request boundary and reuses exact L1 results by
+     * SHA-256 of the unmodified prompt payload.
+     */
+    compactPrompt(input) {
+        const rawPayload = JSON.stringify({
+            systemPrompt: input.systemPrompt ?? null,
+            messages: input.messages,
+        });
+        const promptSha256 = createHash('sha256').update(rawPayload ?? '').digest('hex');
+        const cached = this.l1Cache.get(promptSha256);
+        if (cached) {
+            return {
+                ...cached,
+                compactedMessages: this.copyMessages(cached.compactedMessages),
+                recommendedModel: input.requestedModel ?? 'unknown',
+                cachedL1: true,
+            };
+        }
+        const compactedSystemPrompt = input.systemPrompt === undefined
+            ? undefined
+            : this.normalizeText(input.systemPrompt, 'system');
+        const compactedMessages = input.messages.map((message) => ({
+            ...message,
+            content: this.normalizeContent(message.content, message.role),
+        }));
+        const originalEstimatedTokens = this.estimatePromptTokens(input.systemPrompt, input.messages);
+        const compactedEstimatedTokens = this.estimatePromptTokens(compactedSystemPrompt, compactedMessages);
+        const tokensSaved = Math.max(0, originalEstimatedTokens - compactedEstimatedTokens);
+        const compressionRatioPct = originalEstimatedTokens > 0
+            ? Number(((tokensSaved / originalEstimatedTokens) * 100).toFixed(2))
+            : 0;
+        const result = {
+            compactedSystemPrompt,
+            compactedMessages,
+            originalEstimatedTokens,
+            compactedEstimatedTokens,
+            tokensSaved,
+            compressionRatioPct,
+            promptSha256,
+            recommendedModel: input.requestedModel ?? 'unknown',
+            cachedL1: false,
+        };
+        this.l1Cache.set(promptSha256, {
+            ...result,
+            compactedMessages: this.copyMessages(compactedMessages),
+        });
+        if (this.l1Cache.size > TokenCompressionService.MAX_L1_ENTRIES) {
+            const firstKey = this.l1Cache.keys().next().value;
+            if (firstKey)
+                this.l1Cache.delete(firstKey);
+        }
+        return result;
+    }
+    /** Clears the process-local cache. Intended for lifecycle cleanup and tests. */
+    clear() {
+        this.l1Cache.clear();
+    }
+    estimatePromptTokens(systemPrompt, messages) {
+        let total = TokenCompressionService.estimateTokens(systemPrompt ?? '');
+        for (const message of messages) {
+            total += TokenCompressionService.estimateTokens(this.serializeContent(message.content));
+        }
+        return total;
+    }
+    serializeContent(content) {
+        if (typeof content === 'string')
+            return content;
+        if (content === undefined || content === null)
+            return '';
+        try {
+            return JSON.stringify(content) ?? '';
+        }
+        catch {
+            return String(content);
+        }
+    }
+    normalizeContent(content, role) {
+        if (typeof content === 'string') {
+            return this.normalizeText(content, role);
+        }
+        if (!Array.isArray(content))
+            return content;
+        let changed = false;
+        const normalized = content.map((block) => {
+            if (!block || typeof block !== 'object')
+                return block;
+            const record = block;
+            if (record.type === 'text' && typeof record.text === 'string') {
+                const text = this.normalizeText(record.text, role);
+                if (text !== record.text)
+                    changed = true;
+                return text === record.text ? block : { ...record, text };
+            }
+            if (record.type === 'thinking' && typeof record.thinking === 'string') {
+                // Provider thought signatures cover the reasoning payload. Rewriting a
+                // signed block would leave the signature attached to different bytes
+                // and can make the next request invalid. Unsigned blocks are safe to
+                // normalize because they do not carry that provider contract.
+                if (record.signature !== undefined)
+                    return block;
+                const thinking = this.normalizeText(record.thinking, role);
+                if (thinking !== record.thinking)
+                    changed = true;
+                return thinking === record.thinking ? block : { ...record, thinking };
+            }
+            if (record.type === 'tool_result') {
+                if (typeof record.content === 'string') {
+                    const text = this.normalizeText(record.content, role);
+                    if (text !== record.content)
+                        changed = true;
+                    return text === record.content ? block : { ...record, content: text };
+                }
+                if (Array.isArray(record.content)) {
+                    const nested = this.normalizeContent(record.content, role);
+                    if (nested !== record.content) {
+                        changed = true;
+                        return { ...record, content: nested };
+                    }
+                }
+            }
+            return block;
+        });
+        return changed ? normalized : content;
+    }
+    normalizeText(text, role) {
+        const normalized = text.replace(/\r\n/g, '\n');
+        if (role === 'system') {
+            return normalized.replace(/[ \t]+/g, ' ').trim();
+        }
+        return normalized
+            .replace(/\n{3,}/g, '\n\n')
+            .replace(/[ \t]{2,}/g, ' ')
+            .trim();
+    }
+    copyMessages(messages) {
+        return messages.map((message) => {
+            const content = message.content;
+            if (!Array.isArray(content))
+                return { ...message };
+            return {
+                ...message,
+                content: content.map((block) => (block && typeof block === 'object' ? { ...block } : block)),
+            };
+        });
+    }
+}
+export const tokenCompressionService = TokenCompressionService.getInstance();
+//# sourceMappingURL=TokenCompressionService.js.map

package/dist/TokenCompressionService.js.map

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

package/dist/broccolidb-aggregation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * GALXAI: BroccoliDB Statistical Aggregation & Group-By Engine (Zenith Tier)
+ * Single-pass streaming grouping, statistical accumulators (SUM, AVG, MIN, MAX, COUNT, STDDEV),
+ * and HAVING predicate filters over BroccoliDbTable records.
+ */
+import type { DbAggregateQuery, DbAggregateResult } from "./broccolidb.contracts.js";
+export declare class BroccoliAggregateEngine {
+    /**
+     * Executes an aggregation query across candidate records.
+     */
+    static execute<T extends Record<string, unknown>>(tableName: string, records: readonly T[], query: DbAggregateQuery): DbAggregateResult;
+    private static finalizeMetric;
+}
+//# sourceMappingURL=broccolidb-aggregation.d.ts.map

package/dist/broccolidb-aggregation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broccolidb-aggregation.d.ts","sourceRoot":"","sources":["../src/broccolidb-aggregation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,gBAAgB,EAChB,iBAAiB,EAElB,MAAM,2BAA2B,CAAC;AAkBnC,qBAAa,uBAAuB;IAClC;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,KAAK,EAAE,gBAAgB,GACtB,iBAAiB;IA6IpB,OAAO,CAAC,MAAM,CAAC,cAAc;CA6B9B"}

package/dist/broccolidb-aggregation.js

@@ -0,0 +1,158 @@
+/**
+ * GALXAI: BroccoliDB Statistical Aggregation & Group-By Engine (Zenith Tier)
+ * Single-pass streaming grouping, statistical accumulators (SUM, AVG, MIN, MAX, COUNT, STDDEV),
+ * and HAVING predicate filters over BroccoliDbTable records.
+ */
+export class BroccoliAggregateEngine {
+    /**
+     * Executes an aggregation query across candidate records.
+     */
+    static execute(tableName, records, query) {
+        const startTime = performance.now();
+        const groupMap = new Map();
+        const grandTotalsAccumulator = {};
+        for (const [metricKey, metricDef] of Object.entries(query.metrics)) {
+            grandTotalsAccumulator[metricKey] = {
+                metric: metricDef.metric,
+                field: metricDef.field,
+                sum: 0,
+                min: Number.POSITIVE_INFINITY,
+                max: Number.NEGATIVE_INFINITY,
+                values: [],
+            };
+        }
+        for (const record of records) {
+            const groupKeyObj = {};
+            let compositeKey = "";
+            if (query.groupBy && query.groupBy.length > 0) {
+                for (const f of query.groupBy) {
+                    const v = record[f];
+                    groupKeyObj[f] = v;
+                    compositeKey += `${f}:${JSON.stringify(v)}|`;
+                }
+            }
+            else {
+                compositeKey = "__root__";
+            }
+            let group = groupMap.get(compositeKey);
+            if (!group) {
+                group = {
+                    keys: groupKeyObj,
+                    count: 0,
+                    metricData: {},
+                };
+                for (const [metricKey, metricDef] of Object.entries(query.metrics)) {
+                    group.metricData[metricKey] = {
+                        metric: metricDef.metric,
+                        field: metricDef.field,
+                        sum: 0,
+                        min: Number.POSITIVE_INFINITY,
+                        max: Number.NEGATIVE_INFINITY,
+                        values: [],
+                    };
+                }
+                groupMap.set(compositeKey, group);
+            }
+            group.count++;
+            for (const [metricKey, metricDef] of Object.entries(query.metrics)) {
+                const acc = group.metricData[metricKey];
+                const grandAcc = grandTotalsAccumulator[metricKey];
+                const val = metricDef.field ? Number(record[metricDef.field]) : 1;
+                const isValidNum = typeof val === "number" && !Number.isNaN(val);
+                if (isValidNum) {
+                    acc.sum += val;
+                    grandAcc.sum += val;
+                    if (val < acc.min)
+                        acc.min = val;
+                    if (val > acc.max)
+                        acc.max = val;
+                    if (val < grandAcc.min)
+                        grandAcc.min = val;
+                    if (val > grandAcc.max)
+                        grandAcc.max = val;
+                    if (metricDef.metric === "stddev") {
+                        acc.values.push(val);
+                        grandAcc.values.push(val);
+                    }
+                }
+            }
+        }
+        let groups = [];
+        for (const group of groupMap.values()) {
+            const finalizedMetrics = {};
+            for (const [metricKey, acc] of Object.entries(group.metricData)) {
+                finalizedMetrics[metricKey] = this.finalizeMetric(acc.metric, acc.sum, acc.min, acc.max, acc.values, group.count);
+            }
+            groups.push({
+                keys: group.keys,
+                metrics: finalizedMetrics,
+                recordCount: group.count,
+            });
+        }
+        if (query.having) {
+            groups = groups.filter((g) => {
+                for (const [k, expected] of Object.entries(query.having)) {
+                    const val = k === "count" || k === "_count" ? g.recordCount : g.metrics[k];
+                    if (expected !== null && typeof expected === "object") {
+                        const expObj = expected;
+                        if (expObj.$gt !== undefined && (val === undefined || val <= expObj.$gt))
+                            return false;
+                        if (expObj.$gte !== undefined && (val === undefined || val < expObj.$gte))
+                            return false;
+                        if (expObj.$lt !== undefined && (val === undefined || val >= expObj.$lt))
+                            return false;
+                        if (expObj.$lte !== undefined && (val === undefined || val > expObj.$lte))
+                            return false;
+                        if (expObj.$eq !== undefined && val !== expObj.$eq)
+                            return false;
+                        if (expObj.$ne !== undefined && val === expObj.$ne)
+                            return false;
+                    }
+                    else if (val !== expected) {
+                        return false;
+                    }
+                }
+                return true;
+            });
+        }
+        if (query.limit !== undefined && query.limit > 0) {
+            groups = groups.slice(0, query.limit);
+        }
+        const grandTotals = {};
+        for (const [metricKey, acc] of Object.entries(grandTotalsAccumulator)) {
+            grandTotals[metricKey] = this.finalizeMetric(acc.metric, acc.sum, acc.min, acc.max, acc.values, records.length);
+        }
+        const executionTimeMicros = Math.round((performance.now() - startTime) * 1000);
+        return {
+            table: tableName,
+            totalRecordsEvaluated: records.length,
+            groups,
+            grandTotals,
+            executionTimeMicros,
+        };
+    }
+    static finalizeMetric(metric, sum, min, max, values, count) {
+        switch (metric) {
+            case "count":
+                return count;
+            case "sum":
+                return sum;
+            case "avg":
+                return count > 0 ? Math.round((sum / count) * 10000) / 10000 : 0;
+            case "min":
+                return min !== Number.POSITIVE_INFINITY ? min : 0;
+            case "max":
+                return max !== Number.NEGATIVE_INFINITY ? max : 0;
+            case "stddev": {
+                if (values.length <= 1)
+                    return 0;
+                const mean = sum / values.length;
+                const variance = values.reduce((acc, v) => acc + Math.pow(v - mean, 2), 0) / values.length;
+                return Math.round(Math.sqrt(variance) * 10000) / 10000;
+            }
+            default:
+                return sum;
+        }
+    }
+}
+//# sourceMappingURL=broccolidb-aggregation.js.map