@classytic/repo-core 0.4.0 → 0.4.2

package/dist/_virtual/_rolldown/runtime.mjs

@@ -0,0 +1,7 @@
+//#region \0rolldown/runtime.js
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require !== "undefined" ? require : a)[b] }) : x)(function(x) {
+	if (typeof require !== "undefined") return require.apply(this, arguments);
+	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
+});
+//#endregion
+export { __require };

package/dist/lock/index.d.mts

@@ -0,0 +1,132 @@
+//#region src/lock/index.d.ts
+/**
+ * Distributed lock contract for the @classytic ecosystem.
+ *
+ * Coordinates exclusive access to a *named resource* across multiple
+ * processes / replicas. The canonical use case: cron leader election.
+ * Multi-pod deployments fire every scheduled tick on every replica;
+ * without coordination the same sweep runs N times. A lock per cron
+ * name lets exactly one replica win each cycle.
+ *
+ * Distinct from `leasePlugin` (mongokit / sqlitekit) — that one
+ * leases existing **rows** (work-queue items) to workers. This
+ * adapter leases **names** (no underlying row required), so it
+ * doubles as singleton-flag, election-leader, and rate-limit
+ * coordination primitive.
+ *
+ * ## Why this lives in repo-core
+ *
+ * The contract is driver-free: any K-V or row store with conditional
+ * upsert can implement it. Mongokit ships a Mongo-backed adapter
+ * (`@classytic/mongokit/lock`); sqlitekit ships a SQLite-backed one
+ * (`@classytic/sqlitekit/lock`); future kits (pgkit, prismakit) wire
+ * their own. Hosts pick the adapter that matches their primary store
+ * and treat the lock as an implementation detail of "we already have
+ * a database, use it for coordination too."
+ *
+ * ## Lease semantics
+ *
+ * `tryAcquire(name, holderId, leaseMs)` returns `true` when `holderId`
+ * now holds the lock — either because it was free, the prior lease
+ * expired, or the same holder is extending. `false` means another
+ * holder owns an unexpired lease.
+ *
+ * `release(name, holderId)` releases the lock if held by this holder.
+ * Returns `true` on actual release, `false` when the holder didn't
+ * own it. Idempotent.
+ *
+ * Crashed leaders are reclaimed when their lease expires — adapters
+ * MUST treat `expiresAt < now` as "free for the taking" inside the
+ * atomic acquire path. Hosts size `leaseMs` based on cron interval
+ * (typically 80–95%); too long delays failover, too short risks the
+ * lease lapsing while the leader is still working.
+ *
+ * ## Sync-or-async
+ *
+ * Methods may return `Promise` or sync values; consumers `await`
+ * either way. Memory adapter is sync; SQL/Mongo adapters are async.
+ *
+ * ## Why one file, not a barrel
+ *
+ * Types + the in-memory reference adapter + the instance-id helper
+ * total under 200 LOC and have no internal seams worth a deep
+ * subpath. A barrel would re-export from siblings (memory-adapter,
+ * instance-id, types) and pull every sibling into the consumer
+ * graph — `sideEffects: false` lets modern bundlers tree-shake, but
+ * single-file is the cheaper guarantee.
+ */
+interface LockAdapter {
+  /**
+   * Try to acquire (or extend) a named lock for `holderId`, valid
+   * for `leaseMs` milliseconds.
+   *
+   * Same `holderId` calling twice extends the lease — idempotent.
+   * Adapters MUST atomically check "free OR mine" and update in a
+   * single round-trip; a read-then-write split is racy.
+   */
+  tryAcquire(name: string, holderId: string, leaseMs: number): Promise<boolean> | boolean;
+  /**
+   * Release the lock if held by `holderId`. Returns `true` on actual
+   * release, `false` when the lock isn't held by this holder. Safe
+   * to call without ever having acquired (returns `false`).
+   */
+  release(name: string, holderId: string): Promise<boolean> | boolean;
+  /**
+   * Optional: introspect a lock without trying to acquire it. Useful
+   * for diagnostics ("which replica holds X?") and tests. Returns
+   * `null` when the lock is free or expired.
+   *
+   * Not in the hot path — adapters that can't implement cheaply may
+   * omit it. Consumers must check existence: `adapter.inspect?.(name)`.
+   */
+  inspect?(name: string): Promise<LockState | null> | LockState | null;
+}
+/** Snapshot of a lock's current holder. */
+interface LockState {
+  /** The lock name (mirrored back for convenience). */
+  name: string;
+  /** Holder identifier. Free-form — typically `hostname.pid.uuid`. */
+  holder: string;
+  /** When the current lease expires. UTC. */
+  expiresAt: Date;
+  /** When the current holder first acquired (or last extended) the lock. */
+  acquiredAt: Date;
+}
+/** Adapter-construction options that every backend shares. */
+interface BaseLockAdapterOptions {
+  /**
+   * Default lease length in milliseconds, applied when a caller passes
+   * `leaseMs <= 0` to `tryAcquire`. Most callers pass an explicit
+   * value sized to their cron interval; the default is a safety net.
+   */
+  defaultLeaseMs?: number;
+}
+/**
+ * Reference in-memory `LockAdapter` — single-process only.
+ *
+ * Useful for tests + single-pod deployments that want the same API
+ * as the production adapter without setting up a database. NOT a
+ * coordination primitive — there's no shared state across processes,
+ * so two processes each construct their own `Map` and both think
+ * they hold every lock. For real multi-replica safety use
+ * `@classytic/mongokit/lock`, `@classytic/sqlitekit/lock`, or a
+ * future kit-specific implementation.
+ *
+ * The atomic check-and-set inside `tryAcquire` is genuine — Node's
+ * single-threaded event loop guarantees a synchronous read-then-write
+ * is atomic relative to other JS, the same guarantee a real adapter
+ * gets from its database's atomic upsert.
+ */
+declare function createMemoryLockAdapter(options?: BaseLockAdapterOptions): LockAdapter;
+/**
+ * Returns a stable instance id for this process, generating it once
+ * on first call and caching for the process lifetime. Idempotent.
+ */
+declare function getInstanceId(): string;
+/**
+ * Test helper — overrides the cached id. Call between tests that
+ * simulate multiple replicas in one process. Pass `null` to reset.
+ */
+declare function setInstanceIdForTesting(id: string | null): void;
+//#endregion
+export { BaseLockAdapterOptions, LockAdapter, LockState, createMemoryLockAdapter, getInstanceId, setInstanceIdForTesting };

package/dist/lock/index.mjs

@@ -0,0 +1,162 @@
+import { __require } from "../_virtual/_rolldown/runtime.mjs";
+import { randomUUID } from "node:crypto";
+//#region src/lock/index.ts
+/**
+* Distributed lock contract for the @classytic ecosystem.
+*
+* Coordinates exclusive access to a *named resource* across multiple
+* processes / replicas. The canonical use case: cron leader election.
+* Multi-pod deployments fire every scheduled tick on every replica;
+* without coordination the same sweep runs N times. A lock per cron
+* name lets exactly one replica win each cycle.
+*
+* Distinct from `leasePlugin` (mongokit / sqlitekit) — that one
+* leases existing **rows** (work-queue items) to workers. This
+* adapter leases **names** (no underlying row required), so it
+* doubles as singleton-flag, election-leader, and rate-limit
+* coordination primitive.
+*
+* ## Why this lives in repo-core
+*
+* The contract is driver-free: any K-V or row store with conditional
+* upsert can implement it. Mongokit ships a Mongo-backed adapter
+* (`@classytic/mongokit/lock`); sqlitekit ships a SQLite-backed one
+* (`@classytic/sqlitekit/lock`); future kits (pgkit, prismakit) wire
+* their own. Hosts pick the adapter that matches their primary store
+* and treat the lock as an implementation detail of "we already have
+* a database, use it for coordination too."
+*
+* ## Lease semantics
+*
+* `tryAcquire(name, holderId, leaseMs)` returns `true` when `holderId`
+* now holds the lock — either because it was free, the prior lease
+* expired, or the same holder is extending. `false` means another
+* holder owns an unexpired lease.
+*
+* `release(name, holderId)` releases the lock if held by this holder.
+* Returns `true` on actual release, `false` when the holder didn't
+* own it. Idempotent.
+*
+* Crashed leaders are reclaimed when their lease expires — adapters
+* MUST treat `expiresAt < now` as "free for the taking" inside the
+* atomic acquire path. Hosts size `leaseMs` based on cron interval
+* (typically 80–95%); too long delays failover, too short risks the
+* lease lapsing while the leader is still working.
+*
+* ## Sync-or-async
+*
+* Methods may return `Promise` or sync values; consumers `await`
+* either way. Memory adapter is sync; SQL/Mongo adapters are async.
+*
+* ## Why one file, not a barrel
+*
+* Types + the in-memory reference adapter + the instance-id helper
+* total under 200 LOC and have no internal seams worth a deep
+* subpath. A barrel would re-export from siblings (memory-adapter,
+* instance-id, types) and pull every sibling into the consumer
+* graph — `sideEffects: false` lets modern bundlers tree-shake, but
+* single-file is the cheaper guarantee.
+*/
+/**
+* Reference in-memory `LockAdapter` — single-process only.
+*
+* Useful for tests + single-pod deployments that want the same API
+* as the production adapter without setting up a database. NOT a
+* coordination primitive — there's no shared state across processes,
+* so two processes each construct their own `Map` and both think
+* they hold every lock. For real multi-replica safety use
+* `@classytic/mongokit/lock`, `@classytic/sqlitekit/lock`, or a
+* future kit-specific implementation.
+*
+* The atomic check-and-set inside `tryAcquire` is genuine — Node's
+* single-threaded event loop guarantees a synchronous read-then-write
+* is atomic relative to other JS, the same guarantee a real adapter
+* gets from its database's atomic upsert.
+*/
+function createMemoryLockAdapter(options = {}) {
+	const { defaultLeaseMs = 3e4 } = options;
+	const store = /* @__PURE__ */ new Map();
+	function readLive(name, now) {
+		const entry = store.get(name);
+		if (!entry) return void 0;
+		if (entry.expiresAt <= now) {
+			store.delete(name);
+			return;
+		}
+		return entry;
+	}
+	return {
+		tryAcquire(name, holderId, leaseMs) {
+			const ms = leaseMs > 0 ? leaseMs : defaultLeaseMs;
+			const now = Date.now();
+			const live = readLive(name, now);
+			if (live && live.holder !== holderId) return false;
+			store.set(name, {
+				holder: holderId,
+				expiresAt: now + ms,
+				acquiredAt: live ? live.acquiredAt : now
+			});
+			return true;
+		},
+		release(name, holderId) {
+			const live = readLive(name, Date.now());
+			if (!live || live.holder !== holderId) return false;
+			store.delete(name);
+			return true;
+		},
+		inspect(name) {
+			const live = readLive(name, Date.now());
+			if (!live) return null;
+			return {
+				name,
+				holder: live.holder,
+				expiresAt: new Date(live.expiresAt),
+				acquiredAt: new Date(live.acquiredAt)
+			};
+		}
+	};
+}
+/**
+* Process-wide instance id helper.
+*
+* Lock holders need a stable identifier per process that's unique
+* across replicas. The standard recipe is `hostname.pid.shortuuid`:
+*
+*   - `hostname`: distinguishes containers on the same host.
+*   - `pid`: distinguishes worker processes on the same container.
+*   - short uuid: distinguishes restarts on the same host with
+*     pid-reuse (rare but possible after fast crash-loop).
+*
+* Edge runtimes (Cloudflare Workers, Vercel Edge) lack `os.hostname()`
+* and `process.pid` — the helper falls back to a uuid-only id, which
+* is still unique per worker isolate.
+*/
+let cachedInstanceId = null;
+/**
+* Returns a stable instance id for this process, generating it once
+* on first call and caching for the process lifetime. Idempotent.
+*/
+function getInstanceId() {
+	if (cachedInstanceId) return cachedInstanceId;
+	cachedInstanceId = buildInstanceId();
+	return cachedInstanceId;
+}
+function buildInstanceId() {
+	const shortUuid = randomUUID().slice(0, 8);
+	let hostname = "unknown";
+	let pid = "edge";
+	try {
+		hostname = __require("node:os").hostname();
+		pid = typeof process !== "undefined" && process.pid ? process.pid : "edge";
+	} catch {}
+	return `${hostname}.${pid}.${shortUuid}`;
+}
+/**
+* Test helper — overrides the cached id. Call between tests that
+* simulate multiple replicas in one process. Pass `null` to reset.
+*/
+function setInstanceIdForTesting(id) {
+	cachedInstanceId = id;
+}
+//#endregion
+export { createMemoryLockAdapter, getInstanceId, setInstanceIdForTesting };

package/dist/repository/index.d.mts

@@ -4,5 +4,5 @@ import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, Plugin, PluginFunction, PluginType, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase, RepositoryBaseOptions } from "./base.mjs";
 import { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey } from "./options.mjs";
-import { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions } from "./types.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 BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ClaimTransition, type ClaimVersionTransition, type DeleteManyResult, type DeleteOptions, type DeleteResult, type FilterInput, 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 QueryOptions, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type UpdateInput, type UpdateManyResult, type WriteOptions, nestDottedKeys, nestDottedKeysAll, validatePluginOrder };
+import { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions } from "./types.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 BulkCreateResult, type BulkWriteOperation, type BulkWriteResult, type ClaimTransition, type ClaimVersionTransition, type DeleteManyResult, type DeleteOptions, type DeleteResult, 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 QueryOptions, RepositoryBase, type RepositoryBaseOptions, type RepositorySession, STANDARD_REPO_OPTION_KEYS, type StandardRepo, type StandardRepoOptionKey, type UpdateInput, type UpdateManyResult, type WriteOptions, nestDottedKeys, nestDottedKeysAll, validatePluginOrder };

package/dist/repository/types.d.mts

@@ -59,6 +59,26 @@ interface WriteOptions extends QueryOptions {
   /** Upsert on update/replace. */
   upsert?: boolean;
 }
+/**
+ * Options for the optional `findAll` verb.
+ *
+ * `sort` is intentionally `Record<string, unknown>` (not a structured
+ * `SortSpec`) so kits can keep their own driver-shaped sort representation
+ * without forcing repo-core to depend on a particular dialect. Mongokit's
+ * `findAll` accepts `SortSpec | string`; sqlitekit accepts the same shape
+ * cross-walked into ORDER BY. `limit` is the bounded-but-not-paginated
+ * cap that callers reach for when `getAll` would force an unwanted count
+ * round-trip and `findAll` without a limit would over-fetch.
+ *
+ * Both fields are optional; absence means "kit default" (typically:
+ * `sort` defaults to natural order, `limit` defaults to "no limit").
+ */
+interface FindAllOptions extends QueryOptions {
+  /** Sort disambiguating when natural order isn't acceptable. */
+  sort?: Record<string, unknown> | string;
+  /** Cap the result set at the driver level. When omitted, returns all matching docs. */
+  limit?: number;
+}
 /**
  * Delete-operation options.
  *
@@ -1258,7 +1278,7 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
     _id: unknown;
   } | null>;
   distinct?<T = unknown>(field: string, filter?: FilterInput, options?: QueryOptions): Promise<T[]>;
-  findAll?(filter?: FilterInput, options?: QueryOptions): Promise<TDoc[]>;
+  findAll?(filter?: FilterInput, options?: FindAllOptions): Promise<TDoc[]>;
   /**
    * Atomic "look up by filter, insert `data` if missing, return the doc."
    *
@@ -1352,7 +1372,7 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * deliberately nothing else, so behavior stays identical across
    * drivers.
    */
-  aggregate?<TRow extends AggRow = AggRow>(req: AggRequest): Promise<AggResult<TRow>>;
+  aggregate?<TRow extends AggRow = AggRow>(req: AggRequest, options?: QueryOptions): Promise<AggResult<TRow>>;
   /**
    * Paginated aggregation. Returns one of two envelope shapes,
    * discriminated by `method`:
@@ -1368,7 +1388,7 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * UI components branch on `result.method` once and render either
    * envelope identically.
    */
-  aggregatePaginate?<TRow extends AggRow = AggRow>(req: AggPaginationRequest): Promise<OffsetPaginationResult<TRow> | KeysetAggPaginationResult<TRow>>;
+  aggregatePaginate?<TRow extends AggRow = AggRow>(req: AggPaginationRequest, options?: QueryOptions): Promise<OffsetPaginationResult<TRow> | KeysetAggPaginationResult<TRow>>;
   /**
    * Paginated join. Compiles the portable `LookupSpec[]` to `$lookup`
    * stages on mongokit or `LEFT JOIN` + `json_object()` / `json_group_array()`
@@ -1407,4 +1427,4 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
   withTransaction?<T>(fn: (txRepo: StandardRepo<TDoc>) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
 }
 //#endregion
-export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions };
+export { AggCacheOptions, AggDateBucket, AggDateBucketInterval, AggDateBucketUnit, AggExecutionHints, AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, AggTopN, AggTopNTies, BulkCreateResult, BulkWriteOperation, BulkWriteResult, ClaimTransition, ClaimVersionTransition, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindAllOptions, FindOneAndUpdateOptions, InferDoc, KeysetAggPaginationResult, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions };

package/dist/testing/index.d.mts

@@ -1,3 +1,4 @@
 import { AggregateOpsSupport, ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness } from "./types.mjs";
 import { runStandardRepoConformance } from "./conformance.mjs";
-export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, runStandardRepoConformance };
+import { LockConformanceHarness, runLockAdapterConformance } from "./lock-conformance.mjs";
+export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type LockConformanceHarness, runLockAdapterConformance, runStandardRepoConformance };

package/dist/testing/index.mjs

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

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

@@ -0,0 +1,25 @@
+import { LockAdapter } from "../lock/index.mjs";
+
+//#region src/testing/lock-conformance.d.ts
+interface LockConformanceHarness {
+  /**
+   * Construct a fresh adapter for each describe block. May be async
+   * (e.g. SQL adapters that need to run a CREATE TABLE migration).
+   * The same adapter instance is shared by every test in the suite —
+   * `beforeEach` is responsible for clearing residual lock state.
+   */
+  createAdapter(): LockAdapter | Promise<LockAdapter>;
+  /**
+   * Wipe every lock between tests. Mongo: drop the collection.
+   * SQLite: `DELETE FROM kit_locks`. Memory: noop (factory returns
+   * a fresh `Map`).
+   *
+   * Required because tests share an adapter and acquire under
+   * conflicting names. A leaked lock from one test breaks the
+   * "first acquire wins" invariant in the next.
+   */
+  beforeEach?(adapter: LockAdapter): void | Promise<void>;
+}
+declare function runLockAdapterConformance(harness: LockConformanceHarness): void;
+//#endregion
+export { LockConformanceHarness, runLockAdapterConformance };

package/dist/testing/lock-conformance.mjs

@@ -0,0 +1,167 @@
+import { beforeEach, describe, expect, it } from "vitest";
+//#region src/testing/lock-conformance.ts
+/**
+* `runLockAdapterConformance` — cross-kit lock-adapter contract suite.
+*
+* Wires a kit-specific `LockConformanceHarness` to a canonical set of
+* scenarios that every `LockAdapter` implementation should pass. The
+* goal is parity: "swap mongokit/lock for sqlitekit/lock" must be a
+* provable claim, and behavior drift between backends shows up here
+* before it ships.
+*
+* Mirrors `runStandardRepoConformance` in shape — vitest is imported
+* at top of file (this subpath is test-only) and the harness gives
+* the kit one chance to construct the adapter, then handles cleanup
+* between scenarios.
+*
+* ## Usage from a kit
+*
+*     import { runLockAdapterConformance } from '@classytic/repo-core/testing';
+*     import { createMongoLockAdapter } from '../../src/lock/index.js';
+*
+*     describe('mongokit/lock conformance', () => {
+*       runLockAdapterConformance({
+*         createAdapter: () => createMongoLockAdapter({ collectionName: 'lock_conformance' }),
+*         async beforeEach() { await clearLocks(); },
+*       });
+*     });
+*/
+const A = "replica-A";
+const B = "replica-B";
+function runLockAdapterConformance(harness) {
+	describe("LockAdapter contract", () => {
+		let adapter;
+		beforeEach(async () => {
+			adapter = await harness.createAdapter();
+			await harness.beforeEach?.(adapter);
+		});
+		describe("tryAcquire", () => {
+			it("first acquire wins on a free lock", async () => {
+				expect(await adapter.tryAcquire("cron.outbox", A, 5e3)).toBe(true);
+			});
+			it("second acquire by a different holder fails while the first is live", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				expect(await adapter.tryAcquire("cron.outbox", B, 5e3)).toBe(false);
+			});
+			it("same holder may extend (idempotent re-acquire)", async () => {
+				expect(await adapter.tryAcquire("cron.outbox", A, 5e3)).toBe(true);
+				expect(await adapter.tryAcquire("cron.outbox", A, 5e3)).toBe(true);
+			});
+			it("expired lease is reclaimable by another holder", async () => {
+				expect(await adapter.tryAcquire("cron.outbox", A, 1)).toBe(true);
+				await sleep(10);
+				expect(await adapter.tryAcquire("cron.outbox", B, 5e3)).toBe(true);
+				expect(await adapter.tryAcquire("cron.outbox", A, 5e3)).toBe(false);
+			});
+			it("different lock names are independent", async () => {
+				expect(await adapter.tryAcquire("lock.one", A, 5e3)).toBe(true);
+				expect(await adapter.tryAcquire("lock.two", A, 5e3)).toBe(true);
+				expect(await adapter.tryAcquire("lock.one", B, 5e3)).toBe(false);
+			});
+			it("parallel acquires resolve to exactly one winner", async () => {
+				expect((await Promise.all([adapter.tryAcquire("shared.name", A, 5e3), adapter.tryAcquire("shared.name", B, 5e3)])).filter((r) => r === true)).toHaveLength(1);
+			});
+		});
+		describe("release", () => {
+			it("the holder can release their own lock", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				expect(await adapter.release("cron.outbox", A)).toBe(true);
+			});
+			it("a non-holder cannot release", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				expect(await adapter.release("cron.outbox", B)).toBe(false);
+			});
+			it("release on an unheld lock returns false (idempotent)", async () => {
+				expect(await adapter.release("never.acquired", A)).toBe(false);
+			});
+			it("after release, another holder can acquire", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				await adapter.release("cron.outbox", A);
+				expect(await adapter.tryAcquire("cron.outbox", B, 5e3)).toBe(true);
+			});
+			it("repeated release by the same holder returns false on the second call", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				expect(await adapter.release("cron.outbox", A)).toBe(true);
+				expect(await adapter.release("cron.outbox", A)).toBe(false);
+			});
+		});
+		describe("inspect", () => {
+			it("reports the current holder for a live lock", async () => {
+				if (!adapter.inspect) return;
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				const state = await adapter.inspect("cron.outbox");
+				expect(state).toBeTruthy();
+				expect(state?.name).toBe("cron.outbox");
+				expect(state?.holder).toBe(A);
+				expect(state?.expiresAt).toBeInstanceOf(Date);
+				expect(state?.acquiredAt).toBeInstanceOf(Date);
+			});
+			it("returns null for a never-acquired lock", async () => {
+				if (!adapter.inspect) return;
+				expect(await adapter.inspect("never.acquired")).toBeNull();
+			});
+			it("returns null for an expired lock (treats expired as absent)", async () => {
+				if (!adapter.inspect) return;
+				await adapter.tryAcquire("cron.outbox", A, 1);
+				await sleep(10);
+				expect(await adapter.inspect("cron.outbox")).toBeNull();
+			});
+			it("preserves acquiredAt across same-holder extensions", async () => {
+				if (!adapter.inspect) return;
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				const original = (await adapter.inspect("cron.outbox"))?.acquiredAt;
+				await sleep(5);
+				await adapter.tryAcquire("cron.outbox", A, 5e3);
+				const extended = (await adapter.inspect("cron.outbox"))?.acquiredAt;
+				expect(extended?.getTime()).toBe(original?.getTime());
+			});
+		});
+		describe("post-steal semantics", () => {
+			it("the original holder cannot release after a steal", async () => {
+				await adapter.tryAcquire("cron.outbox", A, 1);
+				await sleep(10);
+				await adapter.tryAcquire("cron.outbox", B, 5e3);
+				expect(await adapter.release("cron.outbox", A)).toBe(false);
+				if (adapter.inspect) expect((await adapter.inspect("cron.outbox"))?.holder).toBe(B);
+			});
+		});
+		describe("stress", () => {
+			it("50 concurrent holders against one name → exactly one winner", async () => {
+				const holders = Array.from({ length: 50 }, (_, i) => `replica-${i}`);
+				expect((await Promise.all(holders.map((h) => adapter.tryAcquire("contended", h, 5e3)))).filter((r) => r === true)).toHaveLength(1);
+			});
+			it("100 sequential acquire/release cycles leave no residue", async () => {
+				for (let i = 0; i < 100; i++) {
+					expect(await adapter.tryAcquire("cycled", A, 5e3)).toBe(true);
+					expect(await adapter.release("cycled", A)).toBe(true);
+				}
+				expect(await adapter.tryAcquire("cycled", B, 5e3)).toBe(true);
+			});
+			it("100 same-holder extensions preserve the original acquiredAt", async () => {
+				if (!adapter.inspect) return;
+				await adapter.tryAcquire("extended", A, 5e3);
+				const original = (await adapter.inspect("extended"))?.acquiredAt;
+				expect(original).toBeTruthy();
+				for (let i = 0; i < 100; i++) await adapter.tryAcquire("extended", A, 5e3);
+				const final = (await adapter.inspect("extended"))?.acquiredAt;
+				expect(final?.getTime()).toBe(original?.getTime());
+			});
+			it("ownership churn: A → B → C → A handovers each succeed atomically", async () => {
+				for (const holder of [
+					A,
+					B,
+					"replica-C",
+					A
+				]) {
+					expect(await adapter.tryAcquire("churn", holder, 5e3)).toBe(true);
+					expect(await adapter.release("churn", holder)).toBe(true);
+				}
+			});
+		});
+	});
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+//#endregion
+export { runLockAdapterConformance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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,
@@ -86,6 +86,10 @@
       "types": "./dist/plugins/index.d.mts",
       "default": "./dist/plugins/index.mjs"
     },
+    "./lock": {
+      "types": "./dist/lock/index.d.mts",
+      "default": "./dist/lock/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "keywords": [