@x12i/countex 1.2.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/README.md +80 -18
  2. package/dist/backup/manifest.d.ts +70 -0
  3. package/dist/backup/manifest.d.ts.map +1 -0
  4. package/dist/backup/manifest.js +131 -0
  5. package/dist/backup/manifest.js.map +1 -0
  6. package/dist/backup/snapshot-encoding.d.ts +8 -0
  7. package/dist/backup/snapshot-encoding.d.ts.map +1 -0
  8. package/dist/backup/snapshot-encoding.js +27 -0
  9. package/dist/backup/snapshot-encoding.js.map +1 -0
  10. package/dist/cli.js +16 -0
  11. package/dist/cli.js.map +1 -1
  12. package/dist/core/countex.d.ts +79 -1
  13. package/dist/core/countex.d.ts.map +1 -1
  14. package/dist/core/countex.js +254 -49
  15. package/dist/core/countex.js.map +1 -1
  16. package/dist/core/extraction.d.ts +1 -5
  17. package/dist/core/extraction.d.ts.map +1 -1
  18. package/dist/core/extraction.js.map +1 -1
  19. package/dist/core/mapping.d.ts +5 -0
  20. package/dist/core/mapping.d.ts.map +1 -1
  21. package/dist/core/mapping.js +27 -0
  22. package/dist/core/mapping.js.map +1 -1
  23. package/dist/index.d.ts +5 -2
  24. package/dist/index.d.ts.map +1 -1
  25. package/dist/index.js +15 -1
  26. package/dist/index.js.map +1 -1
  27. package/dist/query/formatter.d.ts +2 -2
  28. package/dist/query/formatter.d.ts.map +1 -1
  29. package/dist/query/formatter.js +9 -6
  30. package/dist/query/formatter.js.map +1 -1
  31. package/dist/query/planner.d.ts +15 -1
  32. package/dist/query/planner.d.ts.map +1 -1
  33. package/dist/query/planner.js +152 -3
  34. package/dist/query/planner.js.map +1 -1
  35. package/dist/simulation/context.d.ts +5 -0
  36. package/dist/simulation/context.d.ts.map +1 -0
  37. package/dist/simulation/context.js +56 -0
  38. package/dist/simulation/context.js.map +1 -0
  39. package/dist/simulation/events.d.ts +3 -0
  40. package/dist/simulation/events.d.ts.map +1 -0
  41. package/dist/simulation/events.js +67 -0
  42. package/dist/simulation/events.js.map +1 -0
  43. package/dist/simulation/index.d.ts +7 -0
  44. package/dist/simulation/index.d.ts.map +1 -0
  45. package/dist/simulation/index.js +16 -0
  46. package/dist/simulation/index.js.map +1 -0
  47. package/dist/simulation/prng.d.ts +4 -0
  48. package/dist/simulation/prng.d.ts.map +1 -0
  49. package/dist/simulation/prng.js +18 -0
  50. package/dist/simulation/prng.js.map +1 -0
  51. package/dist/simulation/resource-estimate.d.ts +6 -0
  52. package/dist/simulation/resource-estimate.d.ts.map +1 -0
  53. package/dist/simulation/resource-estimate.js +11 -0
  54. package/dist/simulation/resource-estimate.js.map +1 -0
  55. package/dist/simulation/simulator.d.ts +15 -0
  56. package/dist/simulation/simulator.d.ts.map +1 -0
  57. package/dist/simulation/simulator.js +67 -0
  58. package/dist/simulation/simulator.js.map +1 -0
  59. package/dist/simulation/tracker.d.ts +8 -0
  60. package/dist/simulation/tracker.d.ts.map +1 -0
  61. package/dist/simulation/tracker.js +18 -0
  62. package/dist/simulation/tracker.js.map +1 -0
  63. package/dist/simulation/types.d.ts +49 -0
  64. package/dist/simulation/types.d.ts.map +1 -0
  65. package/dist/simulation/types.js +21 -0
  66. package/dist/simulation/types.js.map +1 -0
  67. package/dist/storage/coverage.d.ts +13 -0
  68. package/dist/storage/coverage.d.ts.map +1 -0
  69. package/dist/storage/coverage.js +37 -0
  70. package/dist/storage/coverage.js.map +1 -0
  71. package/dist/storage/memory.d.ts +23 -5
  72. package/dist/storage/memory.d.ts.map +1 -1
  73. package/dist/storage/memory.js +162 -3
  74. package/dist/storage/memory.js.map +1 -1
  75. package/dist/storage/mongo.d.ts +5 -0
  76. package/dist/storage/mongo.d.ts.map +1 -1
  77. package/dist/storage/mongo.js +68 -1
  78. package/dist/storage/mongo.js.map +1 -1
  79. package/dist/storage/redis.d.ts +40 -11
  80. package/dist/storage/redis.d.ts.map +1 -1
  81. package/dist/storage/redis.js +202 -44
  82. package/dist/storage/redis.js.map +1 -1
  83. package/dist/types/index.d.ts +165 -7
  84. package/dist/types/index.d.ts.map +1 -1
  85. package/docs/DEPLOYMENT.md +125 -3
  86. package/docs/countex_gap_analysis_complete_checklist.md +1340 -0
  87. package/docs/guides/README.md +5 -0
  88. package/docs/guides/adapter-mongo.md +12 -0
  89. package/docs/guides/adapter-redis.md +46 -4
  90. package/docs/guides/backup-export.md +106 -10
  91. package/docs/guides/cli.md +8 -0
  92. package/docs/guides/counter-maps.md +14 -0
  93. package/docs/guides/insights-overview.md +6 -0
  94. package/docs/guides/measures.md +4 -0
  95. package/docs/guides/preview.md +92 -0
  96. package/docs/guides/querying.md +70 -0
  97. package/docs/guides/simulation-profiles.md +33 -0
  98. package/docs/guides/simulation-resource-estimation.md +30 -0
  99. package/docs/guides/simulation.md +36 -0
  100. package/docs/internals/README.md +1 -0
  101. package/docs/internals/internal-dimension-hash.md +34 -0
  102. package/docs/internals/internal-storage-mongo.md +24 -4
  103. package/docs/internals/internal-storage-redis.md +41 -9
  104. package/docs/use-cases/README.md +56 -0
  105. package/docs/use-cases/audit-security-log-counts.md +550 -0
  106. package/docs/use-cases/llm-cost-and-token-metering.md +255 -0
  107. package/docs/use-cases/multi-tenant-isolation.md +203 -0
  108. package/docs/use-cases/ops-dashboard-daily-rollups.md +255 -0
  109. package/docs/use-cases/processing-workflow-activity.md +165 -0
  110. package/docs/use-cases/product-feature-usage.md +240 -0
  111. package/docs/use-cases/webhook-idempotent-ingestion.md +188 -0
  112. package/package.json +18 -2
@@ -0,0 +1,550 @@
1
+ # Technical playbook: Audit and security style logs
2
+
3
+ You operate a pipeline that ingests **audit or security events** (cloud audit APIs, IdP logs, workspace governance feeds). You must maintain **aggregate counters** — who touched what, under which operation and sensitivity labels — with **deduplicated delivery** and **tenant isolation**.
4
+
5
+ This document specifies **exactly** how to implement that with `@x12i/countex`, from event schema to production wiring.
6
+
7
+ ---
8
+
9
+ ## 1. Problem statement and constraints
10
+
11
+ ### 1.1 What you need operationally
12
+
13
+ - Count activity **per tenant** (`scope`).
14
+ - Break down by **actor** and optionally **target resource** (`subjects`).
15
+ - Treat each **classification label** as its own counted category (`metrics`, fan-out).
16
+ - Slice by **operation**, **situation** (internal/external), **resource type** (`dimensions`).
17
+ - Bucket by calendar **`day` / `week` / `month`** for SOC-style reporting.
18
+ - Tolerate **at-least-once** delivery without double-counting (idempotency).
19
+ - Answer aggregate questions: **total increment volume**, **totals in a situation**, **how many distinct actors/resources had activity** in a slice, and optionally **deduped logical event counts** (§10).
20
+
21
+ ### 1.2 What Countex guarantees vs. what you must supply
22
+
23
+ | Responsibility | Owner |
24
+ |----------------|--------|
25
+ | Sparse counter increments, atomic durable merge | Countex + `DurableStorage` |
26
+ | Hot read path | Optional `CacheStorage` |
27
+ | Event schema normalization before ingest | Your ingress adapter |
28
+ | Mapping vendor JSON → Countex paths | Your `CounterMap` |
29
+ | Reverse-mapping numeric ids in dashboards | Your app or BI layer |
30
+
31
+ ### 1.3 Non-goals for this playbook
32
+
33
+ - Full-text search of raw logs — use a log store; Countex holds **aggregates** only.
34
+ - Per-event replay audit trail — Countex cells do not preserve event ids after aggregation (unless you add parallel storage).
35
+
36
+ ---
37
+
38
+ ## 2. Mapping domain JSON → Countex primitives
39
+
40
+ | Primitive | Source in canonical JSON | Storage note |
41
+ |-----------|--------------------------|--------------|
42
+ | **scope** | `$.tenant.id` string | Becomes `scopeId`. |
43
+ | **eventTime** | `$.event.createdAt` ISO-8601 | Drives **UTC** bucket keys only. |
44
+ | **subject type `actor`** | `$.actor.id` | Dictionary-encoded subject id. |
45
+ | **subject type `resource`** | `$.resource.id` optional | Omit row when path missing and `required: false`. |
46
+ | **metrics** | each element of `$.labels[*]` | Each label string → dictionary metric id. |
47
+ | **dimension `operation`** | `$.event.operation` | Literal string on cell. |
48
+ | **dimension `situation`** | `$.event.situation` | Literal string on cell. |
49
+ | **dimension `resourceType`** | `$.resource.type` | Literal string on cell. |
50
+ | **delta** | constant `1` | One audit occurrence per fan-out tuple. |
51
+ | **idempotency key** | `$.event.id` | Passed to cache `markEventSeen` as `audit_actor_label:<id>`. |
52
+
53
+ ---
54
+
55
+ ## 3. Canonical event contract
56
+
57
+ ### 3.1 Example payload (normative shape)
58
+
59
+ ```json
60
+ {
61
+ "tenant": { "id": "org_abc" },
62
+ "event": {
63
+ "id": "audit_evt_901",
64
+ "createdAt": "2026-05-08T14:33:00.000Z",
65
+ "operation": "FileDownloaded",
66
+ "situation": "external"
67
+ },
68
+ "actor": { "id": "user_42", "type": "user" },
69
+ "resource": { "id": "doc_99", "type": "document" },
70
+ "labels": ["PII", "Financial"]
71
+ }
72
+ ```
73
+
74
+ ### 3.2 Required-field matrix
75
+
76
+ | Path | Required for ingest | If missing |
77
+ |------|---------------------|------------|
78
+ | `$.tenant.id` | Yes | Entire event **skipped** for this map (`skipped: true` from extraction). |
79
+ | `$.event.createdAt` | Yes | Skipped (invalid/missing time). |
80
+ | `$.actor.id` | Yes (`required: true`) | Skipped. |
81
+ | `$.resource.id` | No | Subject type `resource` omitted from fan-out only. |
82
+ | `$.labels[*]` | At least one scalar after wildcard | Skipped if `metrics.required: true` and none extracted. |
83
+ | `$.event.operation` | No | Dimension omitted or `null` handling per `MappingOptions` (default skips optional missing dims). |
84
+ | `$.event.id` | Required for dedupe when idempotency enabled | Warning logged; dedupe may not apply — **fix upstream**. |
85
+
86
+ ### 3.3 Invariants you should enforce upstream
87
+
88
+ 1. **`event.id`** globally unique per tenant (or globally if `scope` does not partition uniqueness).
89
+ 2. **`createdAt`** always UTC ISO with `Z` offset or unambiguous offset — parsing uses `new Date(value)`.
90
+ 3. **`labels`** bounded cardinality (_enum-like values); avoid raw URLs or unique tokens as labels.
91
+
92
+ ---
93
+
94
+ ## 4. Counter map (exact literal)
95
+
96
+ Create a module, e.g. `src/countex/maps/auditActorLabelMap.ts`:
97
+
98
+ ```ts
99
+ import type { CounterMap } from "@x12i/countex";
100
+
101
+ export const auditActorLabelMap: CounterMap = {
102
+ counterId: "audit_actor_label",
103
+
104
+ scope: { path: "$.tenant.id" },
105
+ eventTime: { path: "$.event.createdAt" },
106
+
107
+ subjects: [
108
+ { type: "actor", path: "$.actor.id", required: true },
109
+ { type: "resource", path: "$.resource.id", required: false },
110
+ ],
111
+
112
+ metrics: [{ path: "$.labels[*]", required: true }],
113
+
114
+ dimensions: [
115
+ { name: "operation", path: "$.event.operation" },
116
+ { name: "situation", path: "$.event.situation" },
117
+ { name: "resourceType", path: "$.resource.type" },
118
+ ],
119
+
120
+ delta: { default: 1 },
121
+ timeframes: ["day", "week", "month"],
122
+
123
+ idempotency: {
124
+ enabled: true,
125
+ eventIdPath: "$.event.id",
126
+ ttlSeconds: 172800,
127
+ },
128
+ };
129
+ ```
130
+
131
+ ### 4.1 Field-by-field rationale
132
+
133
+ - **`counterId`**: stable product identifier; appears in every Mongo document and Redis hash namespace.
134
+ - **`subjects`**: two independent extractors → Countex emits **separate** increments for actor-only and resource-only subjects when both exist.
135
+ - **`metrics` with `[*]`**: each label is one **metric source key** (string). Dictionary allocates **one numeric `metricId` per distinct label string per scope**.
136
+ - **`dimensions`**: stored as-is on the cell; participate in `dimensionsHash` with canonical ordering inside the engine.
137
+ - **`idempotency.ttlSeconds: 172800`**: 48h Redis TTL on dedupe keys — **must exceed maximum replay lag** of your bus; increase if vendors replay slower.
138
+
139
+ ---
140
+
141
+ ## 5. Fan-out arithmetic (capacity planning)
142
+
143
+ For one event, raw increments before buffer merge:
144
+
145
+ ```
146
+ R = |subject fan-out| × |metric fan-out| × |timeframes|
147
+ ```
148
+
149
+ Worked example for §3.1:
150
+
151
+ - Subjects: `actor` + `resource` → **2**
152
+ - Metrics: `PII`, `Financial` → **2**
153
+ - Timeframes: `day`, `week`, `month` → **3**
154
+
155
+ **R = 2 × 2 × 3 = 12** `PendingDelta` rows **minimum** (more if buffer merges same cell later).
156
+
157
+ **Action:** multiply `R` by peak events/sec to size flush thresholds and Mongo write throughput.
158
+
159
+ ---
160
+
161
+ ## 6. Implementation steps
162
+
163
+ ### Step 6.1 — Install dependencies
164
+
165
+ ```bash
166
+ npm install @x12i/countex mongodb ioredis
167
+ ```
168
+
169
+ Your service **owns** MongoDB and Redis clients (Countex does not connect or disconnect for you).
170
+
171
+ ### Step 6.2 — Environment variables (production)
172
+
173
+ | Variable | Purpose |
174
+ |----------|---------|
175
+ | `MONGO_URI` | Connection string for `MongoClient`. |
176
+ | `REDIS_URL` | Connection string for `ioredis`. |
177
+
178
+ Never embed secrets in maps or repo.
179
+
180
+ ### Step 6.3 — Construct Mongo durable
181
+
182
+ File `src/countex/createAuditCountex.ts` (pattern):
183
+
184
+ ```ts
185
+ import { MongoClient } from "mongodb";
186
+ import IORedis from "ioredis";
187
+ import { createCountex } from "@x12i/countex";
188
+ import { MongoDurable } from "@x12i/countex/adapters/mongo";
189
+ import { RedisCache } from "@x12i/countex/adapters/redis";
190
+ import { auditActorLabelMap } from "./maps/auditActorLabelMap.js";
191
+
192
+ export async function createAuditCountex() {
193
+ const mongo = new MongoClient(process.env.MONGO_URI!);
194
+ await mongo.connect();
195
+
196
+ const redis = new IORedis(process.env.REDIS_URL!);
197
+
198
+ const durable = new MongoDurable({
199
+ client: mongo,
200
+ dbResolver: ({ scope }) => `countex_${scope}`,
201
+ // cellsCollection / dictCollection defaults: countex_cells, countex_dict
202
+ });
203
+
204
+ const cache = new RedisCache({
205
+ client: redis,
206
+ keyPrefix: "countex",
207
+ ttlSeconds: 92 * 24 * 3600,
208
+ });
209
+
210
+ const countex = createCountex({
211
+ maps: [auditActorLabelMap],
212
+ durable,
213
+ cache,
214
+ flush: {
215
+ everyMs: 60_000,
216
+ maxBufferedCells: 100_000,
217
+ maxBufferedEvents: 50_000,
218
+ flushOnShutdown: true,
219
+ onOverflow: "block",
220
+ },
221
+ cardinality: {
222
+ maxDimensionValuesPerName: 10_000,
223
+ maxSubjectsPerScope: 10_000_000,
224
+ onLimit: "overflow",
225
+ overflowValue: "__OTHER__",
226
+ highCardinalityWarnings: true,
227
+ },
228
+ });
229
+
230
+ await countex.init();
231
+
232
+ countex.on("duplicate", ({ scopeId, eventId }) => {
233
+ // structured log: delivery replay
234
+ });
235
+ countex.on("dropped", ({ reason }) => {
236
+ // cardinality / extraction drops
237
+ });
238
+ countex.on("flush_error", ({ error }) => {
239
+ // alert on durable failure
240
+ });
241
+
242
+ return { countex, mongo, redis };
243
+ }
244
+ ```
245
+
246
+ **Exact lifecycle rules:**
247
+
248
+ 1. Call **`await countex.init()`** once after construction (invokes `durable.init` / `cache.init`).
249
+ 2. On SIGTERM: **`await countex.shutdown()`** then `mongo.close()`, `redis.quit()`.
250
+
251
+ ### Step 6.4 — Ingress handler (exact control flow)
252
+
253
+ For each decoded JSON object `event: unknown`:
254
+
255
+ 1. **`await countex.ingest(event)`** — asynchronous; may call `resolveIds` (Mongo) and `markEventSeen` (Redis) during the call.
256
+ 2. Do **not** assume counts are persisted until **`await countex.flush()`** completes **or** periodic flush runs.
257
+
258
+ Minimal handler:
259
+
260
+ ```ts
261
+ async function onAuditMessage(raw: string, countex: import("@x12i/countex").Countex) {
262
+ const event = JSON.parse(raw) as unknown;
263
+ await countex.ingest(event);
264
+ }
265
+ ```
266
+
267
+ For synchronous durability at end of batch job:
268
+
269
+ ```ts
270
+ await countex.ingestBatch(batch);
271
+ await countex.flush();
272
+ ```
273
+
274
+ ### Step 6.5 — Cardinality policy (when to tune)
275
+
276
+ If `operation` or `resourceType` can explode (free-form strings), keep `maxDimensionValuesPerName` tight and **`onLimit: "overflow"`** so ingestion continues. Subscribe to `cardinality_warning` and fix mappings.
277
+
278
+ ---
279
+
280
+ ## 7. Query specifications
281
+
282
+ ### 7.1 SOC table — top actor × label × operation
283
+
284
+ ```ts
285
+ const result = await countex.query({
286
+ scope: "org_abc",
287
+ counterId: "audit_actor_label",
288
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
289
+ groupBy: ["subject", "metric", "dim:operation"],
290
+ format: "table",
291
+ orderBy: "-count",
292
+ limit: 200,
293
+ });
294
+ ```
295
+
296
+ ### 7.2 Interpreting `result.rows`
297
+
298
+ Each row is a `QueryRow`:
299
+
300
+ - **`row.keys.subject`** — **numeric** dictionary id for `(subjectType, subjectSourceKey)` **when `groupBy` includes `"subject"`** without `subjectType` disambiguation. Because you have **two** subject types, you **must** also group by **`subjectType`** for unambiguous dashboards:
301
+
302
+ ```ts
303
+ groupBy: ["subjectType", "subject", "metric", "dim:operation"],
304
+ ```
305
+
306
+ - **`row.keys.metric`** — numeric metric id (label string hashed via dictionary).
307
+ - **`row.keys["dim:operation"]`** — **literal string** from JSON (human-readable).
308
+ - **`row.count`** — aggregated integer count.
309
+
310
+ ### 7.3 Filtering by metric id
311
+
312
+ In current adapters (`MongoDurable`, `MemoryDurable`, `RedisCache`), the **`metrics`** filter on `QuerySpec` is applied using **numeric dictionary ids** only (strings that are not parseable as finite numbers do not constrain the server-side read).
313
+
314
+ **Exactly what to do:**
315
+
316
+ 1. Run a small probe query with `format: "cells"` and `limit`, or read `metricId` from Mongo `countex_dict`, to learn `metricId` for `"PII"` / `"Financial"`.
317
+ 2. Pass those integers:
318
+
319
+ ```ts
320
+ metrics: [41, 42],
321
+ ```
322
+
323
+ Or omit `metrics` and narrow using **`groupBy: ["metric"]`** plus **`limit`** / sorting in application code.
324
+
325
+ ### 7.4 Raw cells for debugging
326
+
327
+ ```ts
328
+ const cells = await countex.query({
329
+ scope: "org_abc",
330
+ counterId: "audit_actor_label",
331
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
332
+ format: "cells",
333
+ limit: 50,
334
+ });
335
+ ```
336
+
337
+ Inspect `CounterCell` objects for full identity tuples (`subjectType`, numeric ids, `dimensions` object).
338
+
339
+ ---
340
+
341
+ ## 8. Verification checklist
342
+
343
+ | Step | Command / action | Expected |
344
+ |------|------------------|----------|
345
+ | Map validates | App boot | No `MappingError` throw. |
346
+ | First ingest | Ingest §3.1 payload, `flush()` | Mongo `countex_cells` documents appear under DB `countex_org_abc`. |
347
+ | Dedupe | Ingest same payload twice | Second ingest emits `duplicate`; counts unchanged. |
348
+ | Query | §7.1 query | `rows.length > 0`, `source` cache or merged/durable. |
349
+ | Grand total | §10.2 | Single row; `total` equals sum of underlying cell counts for the day. |
350
+ | Distinct actors | §10.4 | `rows.length` matches manual expectation for synthetic fixtures. |
351
+ | Logical events | §10.6 (optional second map) | `audit_logical_events` total tracks deduped ingest 1:1. |
352
+
353
+ ---
354
+
355
+ ## 9. Failure modes
356
+
357
+ | Symptom | Likely cause | Mitigation |
358
+ |---------|--------------|------------|
359
+ | Always `duplicate`, zero counts | Wrong `event.id` constant | Fix producer uniqueness. |
360
+ | No rows, no errors | Missing labels | Relax `metrics.required` or normalize payload. |
361
+ | Exploding Mongo size | High-cardinality dimension | Lower limits; map values to enums; `onLimit: "overflow"`. |
362
+ | Slow ingest | `resolveIds` round-trips | Batch with `ingestBatch`; scale Mongo; reduce fan-out (fewer timeframes). |
363
+
364
+ ---
365
+
366
+ ## 10. Analytics: event volume, rollups, and “unique entities”
367
+
368
+ Countex stores **sparse counter cells**, not a raw event store. An **audit log line** that fans out into many increments is **not** the same as one counter unit. This section spells out **exact queries** for common SOC / compliance questions.
369
+
370
+ ### 10.1 Vocabulary
371
+
372
+ | Question | What Countex actually aggregates |
373
+ |----------|----------------------------------|
374
+ | “How much activity?” | Sum of **`count`** over matching cells (may be **>** logical event count if the map fans out). |
375
+ | “How many audit **events**?” | Needs a **1:1 map** from deduped ingest → increments (§10.6) or an external event ledger. |
376
+ | “How many **distinct** actors?” | Count **grouped rows** where each row is one **subject id** after filters (§10.4). This is “distinct actors **with non-zero activity** in the window,” not set cardinality over infinite theoretical actors. |
377
+
378
+ ### 10.2 Total increment volume (grand rollup)
379
+
380
+ **Use case:** total counter mass for the tenant/day across **all** entities and labels in this counter family.
381
+
382
+ **Exactly:**
383
+
384
+ ```ts
385
+ const volume = await countex.query({
386
+ scope: "org_abc",
387
+ counterId: "audit_actor_label",
388
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
389
+ format: "table",
390
+ });
391
+ ```
392
+
393
+ With **no `groupBy`**, the formatter merges all matching cells into **one row**; **`volume.rows[0].count`** (and **`volume.total`**) equal the sum of all merged **`count`** fields.
394
+
395
+ **Interpretation:** this is **total increments**, e.g. actor×resource×label×timeframe fan-out from §5. Do **not** label this “number of audit records” unless your map is 1:1 per record.
396
+
397
+ ### 10.3 Activity restricted by situation (dimension filter)
398
+
399
+ **Use case:** all increments where **`situation === "external"`** (or internal).
400
+
401
+ **Exactly:**
402
+
403
+ ```ts
404
+ const externalOnly = await countex.query({
405
+ scope: "org_abc",
406
+ counterId: "audit_actor_label",
407
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
408
+ dimensions: { situation: ["external"] },
409
+ format: "table",
410
+ });
411
+ ```
412
+
413
+ Dimension filters are **equality on stored dimension literals** (`dimensions.situation` in Mongo). Values must match ingest normalization (see `normalizeDimensionValue` / map `options`).
414
+
415
+ ### 10.4 Unique actors with external activity (“distinct entities” pattern)
416
+
417
+ **Use case:** count **how many different actor ids** had any qualifying increment **in external situations** for that day.
418
+
419
+ Countex does not expose SQL **`COUNT(DISTINCT …)`**. **Exactly what to do:** group so **each row is one actor**, then count rows.
420
+
421
+ ```ts
422
+ const byActor = await countex.query({
423
+ scope: "org_abc",
424
+ counterId: "audit_actor_label",
425
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
426
+ dimensions: { situation: ["external"] },
427
+ subject: { type: "actor" },
428
+ groupBy: ["subjectType", "subject"],
429
+ format: "table",
430
+ // omit limit to include every actor with data in range
431
+ });
432
+ const uniqueActorCount = byActor.rows.length;
433
+ ```
434
+
435
+ **Semantics:**
436
+
437
+ - **`subject: { type: "actor" }`** drops resource-side cells at read time (`subjectType` filter in storage layer).
438
+ - **`groupBy`** merges all metrics / labels / operations into **one row per actor** for that slice (single aggregated **`count`** per actor).
439
+ - **`uniqueActorCount`** = cardinality of actors **with activity**, not “actors in directory.”
440
+
441
+ **If you must cap memory:** use **`limit`** for “top K actors by volume,” **not** for exact distinct cardinality — then **`rows.length ≤ limit`** and you under-count entities.
442
+
443
+ ### 10.5 Unique resources touched (same pattern)
444
+
445
+ **Use case:** distinct **resource** ids with activity in a situation slice.
446
+
447
+ ```ts
448
+ const byResource = await countex.query({
449
+ scope: "org_abc",
450
+ counterId: "audit_actor_label",
451
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
452
+ dimensions: { situation: ["external"] },
453
+ subject: { type: "resource" },
454
+ groupBy: ["subjectType", "subject"],
455
+ format: "table",
456
+ });
457
+ const uniqueResourceCount = byResource.rows.length;
458
+ ```
459
+
460
+ ### 10.6 Logical audit **event** count (1 increment per deduped message)
461
+
462
+ **Use case:** “How many audit **events** did we ingest?” — aligned with idempotent delivery, **not** with label×subject fan-out.
463
+
464
+ **Exactly what to do:**
465
+
466
+ 1. Register a **second** map with **one increment per logical event**: single timeframe bucket family, **one metric value per event**, **one subject** you care about for attribution (often **actor**).
467
+
468
+ 2. In your ingress adapter, **inject** a stable low-cardinality field Countex can read (required because metrics cannot be omitted):
469
+
470
+ ```ts
471
+ function normalizeAuditEvent(raw: unknown) {
472
+ const e = raw as Record<string, unknown>;
473
+ const ev = (e["event"] ?? {}) as Record<string, unknown>;
474
+ ev["__cxUnit"] = "audit_event";
475
+ e["event"] = ev;
476
+ return e;
477
+ }
478
+ ```
479
+
480
+ 3. Add map `audit_logical_events` to the **same** `createCountex({ maps: [auditActorLabelMap, auditLogicalEventsMap] })` and reuse the **same** idempotency path (`event.id`).
481
+
482
+ ```ts
483
+ export const auditLogicalEventsMap: CounterMap = {
484
+ counterId: "audit_logical_events",
485
+ scope: { path: "$.tenant.id" },
486
+ eventTime: { path: "$.event.createdAt" },
487
+ subjects: [{ type: "actor", path: "$.actor.id", required: true }],
488
+ metrics: [{ path: "$.event.__cxUnit", required: true }],
489
+ dimensions: [
490
+ { name: "situation", path: "$.event.situation" },
491
+ ],
492
+ delta: { default: 1 },
493
+ timeframes: ["day"],
494
+ idempotency: {
495
+ enabled: true,
496
+ eventIdPath: "$.event.id",
497
+ ttlSeconds: 172800,
498
+ },
499
+ };
500
+ ```
501
+
502
+ **Fan-out:** 1 × 1 × 1 = **one durable increment per deduped audit message per day bucket**.
503
+
504
+ **Query total events for the day:**
505
+
506
+ ```ts
507
+ const events = await countex.query({
508
+ scope: "org_abc",
509
+ counterId: "audit_logical_events",
510
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
511
+ format: "table",
512
+ });
513
+ const auditEventTotal = events.rows[0]?.count ?? 0;
514
+ ```
515
+
516
+ **External-only event count:**
517
+
518
+ ```ts
519
+ const externalEvents = await countex.query({
520
+ scope: "org_abc",
521
+ counterId: "audit_logical_events",
522
+ timeframe: { type: "day", from: "2026-05-08", to: "2026-05-08" },
523
+ dimensions: { situation: ["external"] },
524
+ format: "table",
525
+ });
526
+ ```
527
+
528
+ ### 10.7 Cross-entity summaries
529
+
530
+ | Goal | `groupBy` | Notes |
531
+ |------|-----------|--------|
532
+ | Volume by label (metric) | `["metric"]` | Each row = one sensitivity label bucket. |
533
+ | Volume by operation | `["dim:operation"]` | Literal dimension. |
534
+ | Volume by actor **and** situation | `["subjectType", "subject", "dim:situation"]` | Multi-dimensional slice; still sparse. |
535
+ | Compare actor vs resource totals | `["subjectType"]` | One row per subject **type** with merged ids (two rows: `actor`, `resource`). |
536
+
537
+ ### 10.8 `result.total` vs `rows.length`
538
+
539
+ For **`format: "table"`**, **`result.total`** is the **sum of `row.count`** over **returned** rows after **`limit`** (`sumRowCounts` in `src/query/formatter.ts`). It is **not** “number of distinct entities.” Use **`rows.length`** for distinct-row cardinality under your **`groupBy`** when every row represents one entity.
540
+
541
+ ---
542
+
543
+ ## 11. References
544
+
545
+ - Idempotency: [`docs/guides/idempotency.md`](../guides/idempotency.md)
546
+ - Cardinality: [`docs/guides/cardinality.md`](../guides/cardinality.md)
547
+ - Types: `QuerySpec`, `QueryRow`, `CounterMap` in `@x12i/countex` type exports
548
+ - Dedupe key implementation: `src/core/countex.ts` (`markEventSeen` namespace)
549
+ - Redis layout: header comment in `src/storage/redis.ts`
550
+ - Query totals / grouping: `src/query/formatter.ts` (`sumRowCounts`, `bucketCells`)