@classytic/repo-core 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to `@classytic/repo-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.0] - 2026-07-15
+
+### Added — `StandardRepo.transition?()` contract (state-machine CAS with history)
+
+- **`TransitionMachine`** — the canonical structural contract for the state
+  machine (`{ name, assertTransition }`). Primitives'
+  `defineStateMachine()` output and mongokit's local `TransitionMachine`
+  are structurally identical by design; nobody imports anybody (same
+  policy as `ClaimTransition`).
+- **`TransitionArgs`** — `{ from, to, field?, set?, push?, where?, by?,
+  note?, history?, at? }`.
+- **`StandardRepo.transition?(id, machine, args, options)`** — OPTIONAL
+  member declaring the state-machine-backed CAS transition mongokit 3.22
+  ships as a class primitive: legality pre-flight via the machine (which
+  throws the domain's typed error), CAS via `claim`, `$push`ed status
+  history, and accurate race-loss diagnosis (machine error from the row's
+  CURRENT state / 404 `TRANSITION_TARGET_MISSING` / 409
+  `TRANSITION_RACE_LOST`). Unlike `claim`/`claimVersion` it THROWS rather
+  than returning `null` — it owns the error liturgy domain packages used
+  to copy-paste. Promote to required once sqlitekit implements it.
+
+### Added — `./usage` subpath (period-bucketed counter contract)
+
+- **`UsageStore`** — driver-agnostic interface for atomic period-bucketed counters: `increment(bucket, amount)` + `summary(actor, period)`. The storage seam under platform accounting (quotas, plan enforcement, usage-based billing). One cell = `(actor, period, kind)`; one write = atomic upsert; one read = all counters for an actor-period pair. Kits ship adapters (`@classytic/mongokit/usage`, `@classytic/sqlitekit/usage`, …) without depending on arc; `@classytic/arc/usage` consumes this contract structurally.
+- **`UsageBucket`** — `{ actor, period, kind }` tuple. `kind` is dot-namespaced: `api.requests`, `ai.tokens.input`, `storage.egress.bytes`.
+- **`usagePeriod(date?)`** — canonical UTC calendar-month key (`"2026-07"`). Monthly is the billing-native granularity.
+- **`createMemoryUsageStore()`** — in-process reference implementation for tests and single-instance apps. Returns `UsageStore & { clear() }`. Multi-replica deployments need a shared adapter.
+
+### Added — `runUsageStoreContract` in `./testing`
+
+- **`runUsageStoreContract(harness)`** — cross-kit conformance suite. Kits import once and pass their adapter; all canonical scenarios run automatically. Same pattern as `runLockAdapterConformance`. `UsageConformanceHarness` is exported from `./testing` for harness typing.
+
 ## [0.10.0] - 2026-07-13
 
 ### Added — `ValidationErrorMeta.path` + `.meta` (field-scoped validation errors)

package/dist/repository/index.d.mts

@@ -6,8 +6,8 @@ import { ArchiveOptions, ArchivePort, ArchiveProgress, ArchiveResult, ArchiveSin
 import { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase, RepositoryBaseOptions } from "./base.mjs";
 import { AggregateOpsSupport, RepoCapabilities } from "./capabilities.mjs";
-import { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, CursorOptions, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, UpdateManyResult, WatchOptions, WriteOptions } from "./types.mjs";
+import { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, CursorOptions, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, TransitionArgs, TransitionMachine, UpdateManyResult, WatchOptions, WriteOptions } from "./types.mjs";
 import { DistributionConfig, DistributionMissHandler, createDistributionGuard, filterReferencesKey } from "./distribution.mjs";
 import { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey } from "./options.mjs";
 import { PurgePort, WritingPurgeStrategy, runChunkedPurge } from "./purge.mjs";
-export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, createDistributionGuard, filterReferencesKey, nestDottedKeys, nestDottedKeysAll, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };
+export { type AggCacheOptions, type AggDateBucket, type AggDateBucketInterval, type AggDateBucketUnit, type AggExecutionHints, type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type AggTopN, type AggTopNTies, type AggregateOpsSupport, type ArchiveOptions, type ArchivePort, type ArchiveProgress, type ArchiveResult, type ArchiveSink, type BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ChangeEvent, type ClaimTransition, type ClaimVersionTransition, type CursorOptions, type DeleteManyResult, type DeleteOptions, type DeleteResult, type DistributionConfig, type DistributionMissHandler, type FilterInput, type FindAllOptions, type FindOneAndUpdateOptions, type InferDoc, type KeysetAggPaginationResult, type LookupPopulateOptions, type LookupPopulateResult, type LookupRow, type LookupSpec, type MinimalRepo, PLUGIN_ORDER_CONSTRAINTS, type PaginationParams, type Plugin, type PluginFunction, type PluginType, type PurgePort, type QueryOptions, type RepoCapabilities, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, type RetryPolicy, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type TenantPurgeOptions, type TenantPurgeProgress, type TenantPurgeResult, type TenantPurgeStrategy, type TransitionArgs, type TransitionMachine, type UpdateInput, type UpdateManyResult, type WatchOptions, type WriteOptions, type WritingPurgeStrategy, createDistributionGuard, filterReferencesKey, nestDottedKeys, nestDottedKeysAll, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry };

package/dist/repository/types.d.mts

@@ -342,6 +342,46 @@ interface ClaimTransition {
    */
   where?: Record<string, unknown>;
 }
+/**
+ * Structural contract for the state machine consumed by
+ * `StandardRepo.transition()` — the CANONICAL shape; mongokit's
+ * `TransitionMachine` and primitives' `StateMachine` (from
+ * `@classytic/primitives/state-machine`, whose `defineStateMachine()`
+ * satisfies it as-is) are structurally identical by design. Neither
+ * repo-core nor the kits import primitives — compatibility is
+ * structural, same policy as `ClaimTransition` above.
+ *
+ * `assertTransition` MUST throw (the domain's typed error, via the
+ * machine's own error factory) when `from → to` is illegal. Kits never
+ * invent their own transition-error vocabulary — the machine owns it.
+ */
+interface TransitionMachine {
+  /** Aggregate name — surfaces in race/missing error messages. */
+  readonly name: string;
+  assertTransition(entityId: string, from: string, to: string): void;
+}
+/**
+ * Args for `StandardRepo.transition()` — the state-machine-backed CAS
+ * with status history. See the method JSDoc for semantics.
+ */
+interface TransitionArgs {
+  from: string | readonly string[];
+  to: string;
+  /** State field (dotted paths allowed on kits that support them). Default `'status'`. */
+  field?: string;
+  /** Set-payload applied alongside the state write (field-shape). */
+  set?: Record<string, unknown>;
+  /** Kit-specific extra append entries merged beside the history append. */
+  push?: Record<string, unknown>;
+  /** Additional CAS guards, AND-merged into the match (same as `ClaimTransition.where`). */
+  where?: Record<string, unknown>;
+  by?: string;
+  note?: string;
+  /** History field name (default `'statusHistory'`), or `false` to skip the append. */
+  history?: string | false;
+  /** Timestamp for the history entry — default `now`. */
+  at?: Date;
+}
 /**
  * Transition spec for `StandardRepo.claimVersion()` — optimistic-
  * concurrency CAS via a version stamp. Sibling to `ClaimTransition`;
@@ -1410,6 +1450,27 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    *   same shape and compile down to flat column writes.
    */
   claimVersion(id: string, transition: ClaimVersionTransition, update: Record<string, unknown>, options?: WriteOptions): Promise<TDoc | null>;
+  /**
+   * State-machine-backed CAS transition with status history — the
+   * canonical domain-verb shape (mongokit 3.22 `Repository.transition`).
+   * One call: machine legality pre-flight (the machine throws the
+   * DOMAIN's typed error), CAS via `claim`, appended history entry
+   * (`{ status: to, occurredAt, by?, note? }` onto `args.history` /
+   * `statusHistory`), and accurate race-loss diagnosis — on CAS miss
+   * the kit re-reads the row and throws the machine's error from the
+   * row's CURRENT state, a 404-shaped `TRANSITION_TARGET_MISSING`
+   * error when the row vanished, or a 409 `TRANSITION_RACE_LOST`
+   * when the move is still legal (caller may re-read and retry).
+   *
+   * Unlike `claim`/`claimVersion`, this method THROWS instead of
+   * returning `null` — it exists precisely to own the error liturgy
+   * that every domain package copy-pasted around `claim`.
+   *
+   * **Optional (for now).** Mongokit ≥3.22 ships it; promote to
+   * required once sqlitekit implements it (SQL kits compile the
+   * history append to their JSON-array/audit-table strategy).
+   */
+  transition?(id: string, machine: TransitionMachine, args: TransitionArgs, options?: WriteOptions): Promise<TDoc>;
   /**
    * Classify an error from a write as a unique-constraint violation.
    * Arc's idempotency + outbox adapters need this to distinguish
@@ -1750,4 +1811,4 @@ interface CursorOptions {
   [key: string]: unknown;
 }
 //#endregion
-export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, CursorOptions, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, UpdateManyResult, WatchOptions, WriteOptions };
+export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ChangeEvent, ClaimTransition, ClaimVersionTransition, CursorOptions, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, TenantPurgeOptions, TenantPurgeProgress, TenantPurgeResult, TenantPurgeStrategy, TransitionArgs, TransitionMachine, UpdateManyResult, WatchOptions, WriteOptions };

package/dist/testing/index.d.mts

@@ -2,4 +2,5 @@ import { AggregateOpsSupport } from "../repository/capabilities.mjs";
 import { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness } from "./types.mjs";
 import { runStandardRepoConformance } from "./conformance.mjs";
 import { LockConformanceHarness, runLockAdapterConformance } from "./lock-conformance.mjs";
-export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type LockConformanceHarness, runLockAdapterConformance, runStandardRepoConformance };
+import { UsageConformanceHarness, runUsageStoreContract } from "./usage-conformance.mjs";
+export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type LockConformanceHarness, type UsageConformanceHarness, runLockAdapterConformance, runStandardRepoConformance, runUsageStoreContract };

package/dist/testing/index.mjs

@@ -1,3 +1,4 @@
 import { runStandardRepoConformance } from "./conformance.mjs";
 import { runLockAdapterConformance } from "./lock-conformance.mjs";
-export { runLockAdapterConformance, runStandardRepoConformance };
+import { runUsageStoreContract } from "./usage-conformance.mjs";
+export { runLockAdapterConformance, runStandardRepoConformance, runUsageStoreContract };

package/dist/testing/usage-conformance.d.mts

@@ -0,0 +1,18 @@
+import { UsageStore } from "../usage/index.mjs";
+//#region src/testing/usage-conformance.d.ts
+interface UsageConformanceHarness {
+  /**
+   * Construct the store under test. May be async (SQL migrations,
+   * index creation). The same instance is shared by every test —
+   * `beforeEach` clears residual counters.
+   */
+  createStore(): UsageStore | Promise<UsageStore>;
+  /**
+   * Wipe every counter between tests. Mongo: `deleteMany({})`.
+   * SQL: `DELETE FROM kit_usage`. Memory: `clear()`.
+   */
+  beforeEach?(store: UsageStore): void | Promise<void>;
+}
+declare function runUsageStoreContract(harness: UsageConformanceHarness): void;
+//#endregion
+export { UsageConformanceHarness, runUsageStoreContract };

package/dist/testing/usage-conformance.mjs

@@ -0,0 +1,101 @@
+import { beforeEach, describe, expect, it } from "vitest";
+//#region src/testing/usage-conformance.ts
+/**
+* `runUsageStoreContract` — cross-kit usage-store contract suite.
+*
+* Wires a kit-specific harness to the canonical scenarios every
+* `UsageStore` implementation must pass — so "swap mongokit/usage for
+* sqlitekit/usage" is a provable claim and drift shows up here before
+* it ships. Written ONCE here; kits import it instead of hand-writing
+* conformance (same shape as `runLockAdapterConformance`).
+*
+* ## Usage from a kit
+*
+*     import { runUsageStoreContract } from '@classytic/repo-core/testing';
+*     import { createMongoUsageStore } from '../../src/usage/index.js';
+*
+*     describe('mongokit/usage conformance', () => {
+*       runUsageStoreContract({
+*         createStore: () => createMongoUsageStore({ connection }),
+*         async beforeEach() { await clearCounters(); },
+*       });
+*     });
+*/
+function runUsageStoreContract(harness) {
+	describe("UsageStore contract", () => {
+		let store;
+		beforeEach(async () => {
+			store = await harness.createStore();
+			await harness.beforeEach?.(store);
+		});
+		it("accumulates increments per (actor, period, kind)", async () => {
+			const bucket = {
+				actor: "org-1",
+				period: "2026-07",
+				kind: "api.requests"
+			};
+			await store.increment(bucket, 1);
+			await store.increment(bucket, 2);
+			await store.increment({
+				...bucket,
+				kind: "ai.tokens.input"
+			}, 500);
+			expect(await store.summary("org-1", "2026-07")).toEqual({
+				"api.requests": 3,
+				"ai.tokens.input": 500
+			});
+		});
+		it("treats a missing bucket as 0 (first increment creates it)", async () => {
+			await store.increment({
+				actor: "a",
+				period: "2026-07",
+				kind: "k"
+			}, 7);
+			expect(await store.summary("a", "2026-07")).toEqual({ k: 7 });
+		});
+		it("isolates actors and periods", async () => {
+			await store.increment({
+				actor: "org-1",
+				period: "2026-06",
+				kind: "k"
+			}, 5);
+			await store.increment({
+				actor: "org-1",
+				period: "2026-07",
+				kind: "k"
+			}, 7);
+			await store.increment({
+				actor: "org-2",
+				period: "2026-07",
+				kind: "k"
+			}, 11);
+			expect(await store.summary("org-1", "2026-06")).toEqual({ k: 5 });
+			expect(await store.summary("org-1", "2026-07")).toEqual({ k: 7 });
+			expect(await store.summary("org-2", "2026-07")).toEqual({ k: 11 });
+		});
+		it("dotted kind names round-trip exactly (no path nesting)", async () => {
+			await store.increment({
+				actor: "a",
+				period: "2026-07",
+				kind: "storage.egress.bytes"
+			}, 42);
+			const summary = await store.summary("a", "2026-07");
+			expect(summary["storage.egress.bytes"]).toBe(42);
+			expect(Object.keys(summary)).toEqual(["storage.egress.bytes"]);
+		});
+		it("returns {} for unknown actors/periods (never throws)", async () => {
+			expect(await store.summary("nobody", "2099-01")).toEqual({});
+		});
+		it("increment is atomic per bucket under concurrency", async () => {
+			const bucket = {
+				actor: "org-c",
+				period: "2026-07",
+				kind: "api.requests"
+			};
+			await Promise.all(Array.from({ length: 50 }, () => store.increment(bucket, 1)));
+			expect((await store.summary("org-c", "2026-07"))["api.requests"]).toBe(50);
+		});
+	});
+}
+//#endregion
+export { runUsageStoreContract };

package/dist/usage/index.d.mts

@@ -0,0 +1,77 @@
+//#region src/usage/index.d.ts
+/**
+ * Usage-counter contract for the @classytic ecosystem.
+ *
+ * Period-bucketed counters per actor — the storage seam under
+ * platform accounting (quotas, plan enforcement, usage-based
+ * billing). One cell = `(actor, period, kind)`; one write op =
+ * atomic increment; one read op = all counters for an actor-period.
+ *
+ * ## Why this lives in repo-core
+ *
+ * Same reasoning as `./lock`: the contract is driver-free — any
+ * store with an atomic increment-upsert implements it (Mongo `$inc`
+ * upsert, SQL `ON CONFLICT ... DO UPDATE SET n = n + ?`, Redis
+ * `HINCRBY`). Kits ship their adapters (`@classytic/mongokit/usage`,
+ * `@classytic/sqlitekit/usage`, ...) WITHOUT depending on arc;
+ * `@classytic/arc/usage`'s `usagePlugin` consumes the contract
+ * structurally (its local `UsageStore` mirrors this shape the same
+ * way its `ScheduleLockLike` mirrors `LockAdapter`) so arc's
+ * repo-core peer floor never bumps for it.
+ *
+ * Distinct from itemized event/usage RECORD stores (e.g.
+ * `@classytic/arc-ai/usage`'s per-run records): this contract holds
+ * AGGREGATES only. Itemized layers sink into it; they don't replace it.
+ *
+ * ## Semantics
+ *
+ * - `increment` MUST be atomic per bucket (concurrent writers never
+ *   lose counts) and MUST treat a missing bucket as `0`.
+ * - `summary` returns `{}` (never throws) for unknown actors/periods.
+ * - `period` keys are opaque strings to the store; `usagePeriod()`
+ *   is the ecosystem's canonical key (UTC calendar month, `2026-07`).
+ *   Stores wanting finer windows shard internally without changing
+ *   the contract.
+ * - Sync-or-async: memory adapter is sync; DB adapters async;
+ *   consumers `await` either way.
+ *
+ * ## Why one file, not a barrel
+ *
+ * Contract + reference memory adapter + the period helper are under
+ * 100 LOC with no internal seams — same single-file rule as `./lock`.
+ */
+/** One counter cell: (actor, period, kind). */
+interface UsageBucket {
+  /** Who consumed — org / user / client id, or a host-chosen fallback key. */
+  actor: string;
+  /** Aggregation period key — canonically `usagePeriod()`'s `YYYY-MM`. */
+  period: string;
+  /** Namespaced counter, dot-separated: `api.requests`, `ai.tokens.input`, `storage.egress.bytes`. */
+  kind: string;
+}
+/** Period-bucketed usage counters. See module header for semantics. */
+interface UsageStore {
+  /** Store name for diagnostics (e.g. 'memory', 'mongo', 'redis'). */
+  readonly name: string;
+  /** Atomically add `amount` to the bucket's counter, creating it at 0. */
+  increment(bucket: UsageBucket, amount: number): Promise<void> | void;
+  /** Every counter for an actor in a period: `{ 'api.requests': 40231, ... }`. */
+  summary(actor: string, period: string): Promise<Record<string, number>>;
+  /** Optional cleanup hook (connections, timers). */
+  close?(): Promise<void>;
+}
+/**
+ * Canonical period key for a date — calendar month, UTC: `2026-07`.
+ * Monthly is the billing-native granularity.
+ */
+declare function usagePeriod(date?: Date): string;
+/**
+ * In-memory reference implementation — tests and single-instance
+ * apps. Counters are per-process; multi-replica deployments need a
+ * shared adapter (kit- or Redis-backed).
+ */
+declare function createMemoryUsageStore(): UsageStore & {
+  clear(): void;
+};
+//#endregion
+export { UsageBucket, UsageStore, createMemoryUsageStore, usagePeriod };

package/dist/usage/index.mjs

@@ -0,0 +1,36 @@
+//#region src/usage/index.ts
+/**
+* Canonical period key for a date — calendar month, UTC: `2026-07`.
+* Monthly is the billing-native granularity.
+*/
+function usagePeriod(date = /* @__PURE__ */ new Date()) {
+	return `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, "0")}`;
+}
+/**
+* In-memory reference implementation — tests and single-instance
+* apps. Counters are per-process; multi-replica deployments need a
+* shared adapter (kit- or Redis-backed).
+*/
+function createMemoryUsageStore() {
+	/** actor → period → kind → count */
+	const counters = /* @__PURE__ */ new Map();
+	return {
+		name: "memory",
+		increment(bucket, amount) {
+			const periods = counters.get(bucket.actor) ?? /* @__PURE__ */ new Map();
+			const kinds = periods.get(bucket.period) ?? /* @__PURE__ */ new Map();
+			kinds.set(bucket.kind, (kinds.get(bucket.kind) ?? 0) + amount);
+			periods.set(bucket.period, kinds);
+			counters.set(bucket.actor, periods);
+		},
+		async summary(actor, period) {
+			const kinds = counters.get(actor)?.get(period);
+			return kinds ? Object.fromEntries(kinds) : {};
+		},
+		clear() {
+			counters.clear();
+		}
+	};
+}
+//#endregion
+export { createMemoryUsageStore, usagePeriod };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.10.0",
-  "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
+  "version": "0.12.0",
+  "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design — no plugins ship here; each kit owns its own.",
   "type": "module",
   "sideEffects": false,
   "files": [
@@ -94,6 +94,10 @@
       "types": "./dist/lock/index.d.mts",
       "default": "./dist/lock/index.mjs"
     },
+    "./usage": {
+      "types": "./dist/usage/index.d.mts",
+      "default": "./dist/usage/index.mjs"
+    },
     "./package.json": "./package.json",
     "./sync": {
       "types": "./dist/sync/index.d.mts",