@classytic/mongokit 3.43.1 → 3.44.0

package/dist/lock/index.mjs

@@ -1,5 +1,276 @@
 import mongoose, { Schema } from "mongoose";
-//#region src/lock/index.ts
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+// src/lock/daily-ledger.ts
+/**
+* Mongo-backed daily ledger — one claim row per `(key, civilDate)`.
+*
+* Structurally implements arc's `DailyLedger` (`@classytic/arc` →
+* `createDailyGate` / `ScheduleDefinition.daily`) without importing arc:
+* pass the returned object as `ledger`. Exactly one replica wins
+* `claimDay` for a given key and civil date (unique `_id` + upsert; the
+* loser's upsert hits E11000 and returns `false`). An uncompleted claim
+* older than `info.staleAfterMs` may be re-granted (crash mid-run); a
+* completed day never is.
+*
+*     {
+*       _id: 'cron.digest|2026-10-30',
+*       key: 'cron.digest',
+*       civilDate: '2026-10-30',
+*       claimedAt: 2026-10-30T06:00:01.000Z,   // the gate's clock (info.now)
+*       completed: true,
+*       completedAt: 2026-10-30T06:00:04.000Z,
+*       result: { sent: 12 },
+*     }
+*
+* `civilDate` must be `YYYY-MM-DD` (what arc passes), so the composite
+* `_id` stays unambiguous whatever the key contains.
+*
+* Fencing is per INVOCATION, not per ledger instance: every won claim
+* gets a unique `claimToken` (stored on the row), and completing or
+* releasing only touches the row while it still carries that token. A
+* run that outlived `staleAfterMs` and was re-granted (by another
+* replica, or by this same instance on a later tick) can therefore
+* neither delete nor complete the newer claim, and a retry of its
+* completion stays fenced.
+*
+* - `claim()` returns a handle carrying the token; its `complete()` /
+*   `release()` are fenced by it. Prefer it in host code.
+* - `claimDay` / `completeDay` / `releaseDay` (arc's token-less
+*   `DailyLedger` shape) bind the token to the calling async context:
+*   `completeDay` / `releaseDay` act on the claim that THIS invocation
+*   (the async flow that awaited `claimDay`) won. Called from a flow
+*   that won nothing, they fall back to the instance's claim on the row
+*   only when it holds exactly one, and are otherwise a no-op.
+* - `adminCompleteDay` is the separate, explicit, unfenced manual
+*   completion. Nothing ever falls through to it.
+*/
+const CIVIL_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function rowId(key, civilDate) {
+	if (typeof key !== "string" || key.length === 0) throw new Error("MongoDailyLedger: key must be a non-empty string");
+	if (typeof civilDate !== "string" || !CIVIL_DATE.test(civilDate)) throw new Error(`MongoDailyLedger: civilDate must be YYYY-MM-DD, got "${String(civilDate)}"`);
+	return `${key}|${civilDate}`;
+}
+/**
+* Build a Mongo-backed daily ledger. Idempotent per `(connection,
+* modelName)` like `createMongoLockAdapter`.
+*
+* @example
+* import { createDailyGate } from '@classytic/arc/plugins';
+* import { createMongoDailyLedger } from '@classytic/mongokit/lock';
+*
+* const gate = createDailyGate({
+*   key: 'digest', zone: 'Asia/Dubai', hour: 6, staleAfterMs: 15 * 60_000,
+*   ledger: createMongoDailyLedger({ connection, collectionName: 'app_daily_ledger' }),
+* });
+*/
+function createMongoDailyLedger(options = {}) {
+	const { connection, collectionName = "mongo_daily_ledger", modelName = "MongoDailyLedger", nowFn = () => /* @__PURE__ */ new Date() } = options;
+	const model = getOrCreateLedgerModel(connection ?? mongoose, modelName, collectionName);
+	const sessionOpt = () => {
+		const s = options.session?.();
+		return s ? { session: s } : {};
+	};
+	/**
+	* Token-less (arc-shaped) claims this instance won and has not finished: rowId → tokens. The
+	* fallback for a `completeDay` / `releaseDay` called outside the invocation that claimed.
+	*/
+	const live = /* @__PURE__ */ new Map();
+	const invocation = new AsyncLocalStorage();
+	const slotToken = (slot) => {
+		for (let s = slot; s; s = s.prev) if (s.token !== void 0) return s.token;
+	};
+	const isLive = (id, token) => live.get(id)?.has(token) === true;
+	const forget = (id, token) => {
+		const set = live.get(id);
+		set?.delete(token);
+		if (set?.size === 0) live.delete(id);
+	};
+	/** The token-less caller's claim on the row: its invocation's, else the instance's only one. */
+	const tokenFor = (id) => {
+		const own = slotToken(invocation.getStore()?.get(id));
+		if (own !== void 0) return own;
+		const set = live.get(id);
+		return set?.size === 1 ? [...set][0] : void 0;
+	};
+	const validate = (key, civilDate, info) => {
+		const _id = rowId(key, civilDate);
+		const now = info?.now;
+		if (!(now instanceof Date) || Number.isNaN(now.getTime())) throw new Error("MongoDailyLedger.claimDay: info.now must be a valid Date");
+		const staleAfterMs = info.staleAfterMs;
+		if (staleAfterMs !== void 0 && (typeof staleAfterMs !== "number" || !Number.isFinite(staleAfterMs) || staleAfterMs < 0)) throw new Error("MongoDailyLedger.claimDay: info.staleAfterMs must be a finite number >= 0");
+		return {
+			_id,
+			now,
+			staleAfterMs
+		};
+	};
+	/** Try to win the row; the new claim's token, or `undefined` when not won. */
+	const claimRow = async (key, civilDate, v) => {
+		const { _id, now, staleAfterMs } = v;
+		const claimToken = randomUUID();
+		try {
+			if (staleAfterMs === void 0) {
+				await model.create([{
+					_id,
+					key,
+					civilDate,
+					claimedAt: now,
+					claimToken,
+					completed: false
+				}]);
+				return claimToken;
+			}
+			const res = await model.updateOne({
+				_id,
+				completed: false,
+				claimedAt: { $lt: new Date(now.getTime() - staleAfterMs) }
+			}, {
+				$set: {
+					key,
+					civilDate,
+					claimedAt: now,
+					claimToken,
+					completed: false
+				},
+				$unset: {
+					result: "",
+					completedAt: ""
+				}
+			}, { upsert: true });
+			return res.upsertedCount + res.modifiedCount > 0 ? claimToken : void 0;
+		} catch (err) {
+			if (err?.code === 11e3) return void 0;
+			throw err;
+		}
+	};
+	/** Complete the row while `token` still holds it uncompleted. */
+	const completeRow = async (_id, token, result) => {
+		return (await model.updateOne({
+			_id,
+			claimToken: token,
+			completed: false
+		}, { $set: {
+			completed: true,
+			completedAt: nowFn(),
+			...result !== void 0 ? { result } : {}
+		} }, sessionOpt())).modifiedCount > 0;
+	};
+	/** Delete the row while `token` still holds it uncompleted. */
+	const releaseRow = async (_id, token) => {
+		return (await model.deleteOne({
+			_id,
+			claimToken: token,
+			completed: false
+		}, sessionOpt())).deletedCount > 0;
+	};
+	return {
+		async claimDay(key, civilDate, info) {
+			const v = validate(key, civilDate, info);
+			const outer = invocation.getStore();
+			const scope = /* @__PURE__ */ new Map();
+			if (outer) for (const [id, slot] of outer) {
+				const t = slotToken(slot);
+				if (t === void 0 || isLive(id, t)) scope.set(id, slot);
+			}
+			const slot = { prev: outer?.get(v._id) };
+			scope.set(v._id, slot);
+			invocation.enterWith(scope);
+			const token = await claimRow(key, civilDate, v);
+			if (token === void 0) return false;
+			slot.token = token;
+			const set = live.get(v._id) ?? /* @__PURE__ */ new Set();
+			set.add(token);
+			live.set(v._id, set);
+			return true;
+		},
+		async completeDay(key, civilDate, result) {
+			const _id = rowId(key, civilDate);
+			const token = tokenFor(_id);
+			if (token === void 0) return;
+			await completeRow(_id, token, result);
+			forget(_id, token);
+		},
+		async releaseDay(key, civilDate) {
+			const _id = rowId(key, civilDate);
+			const token = tokenFor(_id);
+			if (token === void 0) return;
+			forget(_id, token);
+			await releaseRow(_id, token);
+		},
+		async claim(key, civilDate, info) {
+			const v = validate(key, civilDate, info);
+			const token = await claimRow(key, civilDate, v);
+			if (token === void 0) return null;
+			return {
+				key,
+				civilDate,
+				token,
+				claimedAt: v.now,
+				complete: (result) => completeRow(v._id, token, result),
+				release: () => releaseRow(v._id, token)
+			};
+		},
+		async adminCompleteDay(key, civilDate, result) {
+			const _id = rowId(key, civilDate);
+			return (await model.updateOne({
+				_id,
+				completed: false
+			}, { $set: {
+				completed: true,
+				completedAt: nowFn(),
+				...result !== void 0 ? { result } : {}
+			} }, sessionOpt())).modifiedCount > 0;
+		},
+		async inspect(key, civilDate) {
+			const doc = await model.findById(rowId(key, civilDate), null, sessionOpt()).lean();
+			if (!doc) return null;
+			const { _id: _ignored, ...row } = doc;
+			return row;
+		}
+	};
+}
+function getOrCreateLedgerModel(conn, modelName, collectionName) {
+	const existing = "models" in conn ? conn.models[modelName] : void 0;
+	if (existing) return existing;
+	const schema = new Schema({
+		_id: {
+			type: String,
+			required: true
+		},
+		key: {
+			type: String,
+			required: true
+		},
+		civilDate: {
+			type: String,
+			required: true
+		},
+		claimedAt: {
+			type: Date,
+			required: true
+		},
+		claimToken: { type: String },
+		completed: {
+			type: Boolean,
+			required: true,
+			default: false
+		},
+		completedAt: { type: Date },
+		result: { type: Schema.Types.Mixed }
+	}, {
+		versionKey: false,
+		timestamps: false,
+		_id: false,
+		minimize: false
+	});
+	schema.index({
+		key: 1,
+		civilDate: -1
+	});
+	return conn.model(modelName, schema, collectionName);
+}
+// src/lock/index.ts
 /**
 * Build a Mongo-backed lock adapter. Idempotent — the underlying
 * model is registered once per `(connection, modelName)` pair, so
@@ -7,27 +278,30 @@ import mongoose, { Schema } from "mongoose";
 * collection (no duplicate-model errors).
 */
 function createMongoLockAdapter(options = {}) {
-	const { connection, collectionName = "mongo_locks", modelName = "MongoLock", defaultLeaseMs = 3e4 } = options;
+	const { connection, collectionName = "mongo_locks", modelName = "MongoLock", defaultLeaseMs = 3e4, nowFn = () => /* @__PURE__ */ new Date() } = options;
 	const model = getOrCreateModel(connection ?? mongoose, modelName, collectionName);
 	return {
 		async tryAcquire(name, holderId, leaseMs) {
 			const ms = leaseMs > 0 ? leaseMs : defaultLeaseMs;
-			const now = /* @__PURE__ */ new Date();
+			const now = nowFn();
 			const expiresAt = new Date(now.getTime() + ms);
 			try {
+				const holder = { $literal: holderId };
 				const result = await model.findOneAndUpdate({
 					_id: name,
 					$or: [{ expiresAt: { $lt: now } }, { holder: holderId }]
-				}, {
-					$set: {
-						holder: holderId,
-						expiresAt
-					},
-					$setOnInsert: { acquiredAt: now }
-				}, {
+				}, [{ $set: {
+					acquiredAt: { $cond: [
+						{ $and: [{ $eq: ["$holder", holder] }, { $ne: [{ $type: "$acquiredAt" }, "missing"] }] },
+						"$acquiredAt",
+						{ $literal: now }
+					] },
+					holder,
+					expiresAt: { $literal: expiresAt }
+				} }], {
 					upsert: true,
 					returnDocument: "after",
-					setDefaultsOnInsert: true
+					updatePipeline: true
 				}).lean();
 				return !!result && result.holder === holderId;
 			} catch (err) {
@@ -35,6 +309,68 @@ function createMongoLockAdapter(options = {}) {
 				throw err;
 			}
 		},
+		async acquire(name, holderId, leaseMs) {
+			const ms = leaseMs > 0 ? leaseMs : defaultLeaseMs;
+			const now = nowFn();
+			const expiresAt = new Date(now.getTime() + ms);
+			const holder = { $literal: holderId };
+			const won = "$__lockWon";
+			const pipeline = [
+				{ $set: { __lockWon: { $or: [{ $lt: ["$expiresAt", { $literal: now }] }, { $eq: ["$holder", holder] }] } } },
+				{ $set: {
+					acquiredAt: { $cond: [
+						won,
+						{ $cond: [
+							{ $and: [{ $eq: ["$holder", holder] }, { $ne: [{ $type: "$acquiredAt" }, "missing"] }] },
+							"$acquiredAt",
+							{ $literal: now }
+						] },
+						"$acquiredAt"
+					] },
+					holder: { $cond: [
+						won,
+						holder,
+						"$holder"
+					] },
+					expiresAt: { $cond: [
+						won,
+						{ $literal: expiresAt },
+						"$expiresAt"
+					] }
+				} },
+				{ $unset: "__lockWon" }
+			];
+			for (let attempt = 0;; attempt++) try {
+				const before = await model.findOneAndUpdate({ _id: name }, pipeline, {
+					upsert: true,
+					returnDocument: "before",
+					updatePipeline: true
+				}).lean();
+				if (!before) return {
+					acquired: true,
+					holder: holderId,
+					acquiredAt: now,
+					expiresAt
+				};
+				const mine = before.holder === holderId;
+				if (mine || before.expiresAt.getTime() < now.getTime()) return {
+					acquired: true,
+					holder: holderId,
+					previousHolder: before.holder,
+					acquiredAt: mine && before.acquiredAt ? before.acquiredAt : now,
+					expiresAt
+				};
+				return {
+					acquired: false,
+					holder: before.holder,
+					acquiredAt: before.acquiredAt,
+					expiresAt: before.expiresAt
+				};
+			} catch (err) {
+				if (err?.code === 11e3 && attempt < 3) continue;
+				throw err;
+			}
+		},
 		async release(name, holderId) {
 			return !!await model.findOneAndDelete({
 				_id: name,
@@ -44,7 +380,7 @@ function createMongoLockAdapter(options = {}) {
 		async inspect(name) {
 			const doc = await model.findById(name).lean();
 			if (!doc) return null;
-			if (doc.expiresAt.getTime() <= Date.now()) return null;
+			if (doc.expiresAt.getTime() <= nowFn().getTime()) return null;
 			return {
 				name,
 				holder: doc.holder,
@@ -88,5 +424,4 @@ function getOrCreateModel(conn, modelName, collectionName) {
 	schema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });
 	return conn.model(modelName, schema, collectionName);
 }
-//#endregion
-export { createMongoLockAdapter };
+export { createMongoDailyLedger, createMongoLockAdapter };

package/dist/{logger-K7dPmu2U.mjs → logger-hbWOlj_X.mjs}

@@ -1,4 +1,4 @@
-//#region src/utils/logger.ts
+// src/utils/logger.ts
 const noop = () => {};
 let current = {
 	warn: console.warn.bind(console),
@@ -22,5 +22,4 @@ function configureLogger(config) {
 function warn(message, ...args) {
 	current.warn(message, ...args);
 }
-//#endregion
 export { warn as n, configureLogger as t };

package/dist/{method-registry.plugin-C63pGn1d.mjs → method-registry.plugin-CGAepsBU.mjs}

@@ -1,5 +1,5 @@
-import { t as createError } from "./error-BuByZwKU.mjs";
-//#region src/plugins/batch-operations.plugin.ts
+import { t as createError } from "./error-DjdmPLWO.mjs";
+// src/plugins/batch-operations.plugin.ts
 /**
 * Batch operations plugin.
 *
@@ -123,8 +123,7 @@ function batchOperationsPlugin() {
 		}
 	};
 }
-//#endregion
-//#region src/plugins/method-registry.plugin.ts
+// src/plugins/method-registry.plugin.ts
 /**
 * Method registry plugin that enables dynamic method registration
 */
@@ -158,5 +157,4 @@ function methodRegistryPlugin() {
 		}
 	};
 }
-//#endregion
 export { batchOperationsPlugin as n, methodRegistryPlugin as t };

package/dist/{model-registry-ClKtWiHa.mjs → model-registry-DrVfJ3Nt.mjs}

@@ -1,5 +1,5 @@
 import mongoose from "mongoose";
-//#region src/model-registry.ts
+// src/model-registry.ts
 /**
 * Model registration — the ONE place `mongoose.models` is touched.
 *
@@ -63,5 +63,4 @@ function defineModel(name, schema, options) {
 	}
 	return target ? target.model(name, schema(), options.collection) : mongoose.model(name, schema(), options.collection);
 }
-//#endregion
 export { defineModel as n, isModelRegistered as r, ModelCollisionError as t };

package/dist/{mongooseToJsonSchema-C3k4ide0.mjs → mongooseToJsonSchema-DMDotz4_.mjs}

@@ -1,7 +1,7 @@
-import { r as isObjectIdInstance } from "./id-resolution-BqDrk0S2.mjs";
+import { r as isObjectIdInstance } from "./id-resolution-Cqh49d9J.mjs";
 import mongoose from "mongoose";
 import { applyFieldRules, collectFieldsToOmit } from "@classytic/repo-core/schema";
-//#region src/utils/mongooseToJsonSchema.ts
+// src/utils/mongooseToJsonSchema.ts
 /**
 * Mongoose → JSON Schema converter.
 *
@@ -600,5 +600,4 @@ function buildJsonSchemaForQuery(_tree, options) {
 	for (const [k, v] of Object.entries(filterable)) if (basePagination.properties) basePagination.properties[k] = v && typeof v === "object" && "type" in v ? v : { type: "string" };
 	return basePagination;
 }
-//#endregion
 export { buildCrudSchemasFromMongooseSchema as n, buildCrudSchemasFromModel as t };

package/dist/{multi-tenant.plugin-B_q9NUHc.d.mts → multi-tenant.plugin-DfeDMiI8.d.mts}

@@ -1,9 +1,8 @@
-import { A as ObjectId } from "./pagination-D6psses0.mjs";
-import { l as Plugin, p as RepositoryContext } from "./repository-MqAP409e.mjs";
+import { A as ObjectId } from "./pagination-DAUg5zOY.mjs";
+import { l as Plugin, p as RepositoryContext } from "./repository-DzVIwhU2.mjs";
 import mongoose, { Connection } from "mongoose";
 import { CacheAdapter as CacheAdapter$1, CacheOptions, RepositoryCacheHandle as RepositoryCacheHandle$1, RepositoryCachePluginOptions, cachePlugin } from "@classytic/repo-core/cache";
 import { TenantConfig } from "@classytic/repo-core/tenant";
-//#region src/plugins/audit-trail.plugin.d.ts
 /**
  * Audit write delivery mode.
  *
@@ -262,8 +261,6 @@ interface AuditTrailMethods {
     operation?: AuditOperation;
   }): Promise<AuditQueryResult>;
 }
-//#endregion
-//#region src/plugins/custom-id.plugin.d.ts
 /**
  * Generator function that produces a unique ID.
  * Receives the full repository context for conditional logic.
@@ -277,6 +274,45 @@ interface CustomIdOptions {
   /** Only generate if the field is missing/empty (default: true) */
   generateOnlyIfEmpty?: boolean;
 }
+/** Options for {@link createSequenceCounter}. */
+interface SequenceCounterOptions {
+  /** Mongoose connection. @default the default `mongoose.connection` */
+  connection?: mongoose.Connection;
+  /**
+   * Collection holding the counters, for hosts with a collection-naming
+   * rule (e.g. an app prefix). @default `'_mongokit_counters'`
+   */
+  collection?: string;
+}
+/**
+ * The atomic counter API bound to one connection + collection. Same
+ * semantics as {@link getNextSequence} / {@link readSequence} /
+ * {@link ensureSequenceAtLeast}, with an optional session on every call.
+ */
+interface SequenceCounter {
+  /** Atomic `$inc` + upsert; returns the value after the increment. */
+  next(counterKey: string, increment?: number, session?: mongoose.ClientSession): Promise<number>;
+  /** Current value, or `null` when the counter was never created. */
+  read(counterKey: string, session?: mongoose.ClientSession): Promise<number | null>;
+  /** Raise to at least `floor` (`$max` + upsert); never lowers. Returns the value after. */
+  ensureAtLeast(counterKey: string, floor: number, session?: mongoose.ClientSession): Promise<number>;
+  /**
+   * Next value of the counter `'<baseKey><sep><civil period>'`, which resets
+   * every civil year / month / day in `timeZone`. See {@link getNextPeriodSequence}.
+   */
+  nextInPeriod(baseKey: string, options: PeriodSequenceOptions): Promise<PeriodSequenceResult>;
+}
+/**
+ * Bind the atomic counter API to a connection and, optionally, a
+ * collection other than `_mongokit_counters`.
+ *
+ * @example
+ * const counters = createSequenceCounter({ connection, collection: 'app_counters' });
+ * await withTransaction(connection, async (session) => {
+ *   const seq = await counters.next('alert.stream', 1, session);
+ * });
+ */
+declare function createSequenceCounter(options?: SequenceCounterOptions): SequenceCounter;
 /**
  * Atomically increment and return the next sequence value for a given key.
  * Uses `findOneAndUpdate` with `upsert` + `$inc` — fully atomic even under
@@ -311,7 +347,7 @@ declare function getNextSequence(counterKey: string, increment?: number, connect
  * Current value of a counter, or `null` when it has never been created.
  * `null` and `0` differ: only a missing counter needs seeding.
  */
-declare function readSequence(counterKey: string, connection?: mongoose.Connection): Promise<number | null>;
+declare function readSequence(counterKey: string, connection?: mongoose.Connection, session?: mongoose.ClientSession): Promise<number | null>;
 /**
  * Raise a counter to at least `floor` — never lowers it. Atomic (`$max` +
  * upsert), so concurrent seeders converge on the highest floor.
@@ -322,7 +358,77 @@ declare function readSequence(counterKey: string, connection?: mongoose.Connecti
  *
  * @returns The counter's value after the raise.
  */
-declare function ensureSequenceAtLeast(counterKey: string, floor: number, connection?: mongoose.Connection): Promise<number>;
+declare function ensureSequenceAtLeast(counterKey: string, floor: number, connection?: mongoose.Connection, session?: mongoose.ClientSession): Promise<number>;
+/** The civil period a period-scoped counter resets on. */
+type SequencePeriod = 'year' | 'month' | 'day';
+/**
+ * The civil period of an instant in an IANA time zone: `'2026'` (year),
+ * `'2026-03'` (month) or `'2026-03-14'` (day). The period suffix every
+ * period-scoped counter key ends with.
+ *
+ * @example
+ * civilPeriodKey(new Date('2026-12-31T21:00:00Z'), 'year', 'Asia/Riyadh'); // '2027'
+ * civilPeriodKey(new Date('2026-12-31T21:00:00Z'), 'year', 'UTC');         // '2026'
+ */
+declare function civilPeriodKey(at: Date, period: SequencePeriod, timeZone: string): string;
+/** Options for {@link periodCounterKey}, {@link getNextPeriodSequence} and `SequenceCounter.nextInPeriod`. */
+interface PeriodSequenceKeyOptions {
+  /** Civil period the counter resets on. */
+  period: SequencePeriod;
+  /** IANA time zone whose civil calendar decides the period (e.g. `'Asia/Riyadh'`, `'UTC'`). */
+  timeZone: string;
+  /**
+   * The instant whose civil date picks the period (e.g. the record's
+   * `reportedAt`, so a backdated record numbers in its own year).
+   * @default now
+   */
+  at?: Date;
+  /**
+   * Joins the base key and the period: `'<base><sep><period>'`.
+   * Pass `'.'` to keep counters an app already created as `occ.occurrence.2026`.
+   * @default ':'
+   */
+  keySeparator?: string;
+}
+/** Options for {@link getNextPeriodSequence} / `SequenceCounter.nextInPeriod`. */
+interface PeriodSequenceOptions extends PeriodSequenceKeyOptions {
+  /** @default 1 */
+  increment?: number;
+  /** Client session: the bump joins the caller's transaction. */
+  session?: mongoose.ClientSession;
+}
+/** A period-scoped counter value plus the period it was issued in. */
+interface PeriodSequenceResult {
+  /** Value after the increment; `1` for the first value of a new period. */
+  seq: number;
+  /** The civil period (`'2026'`, `'2026-03'`, `'2026-03-14'`), for formatting the id. */
+  period: string;
+  /** The counter document's key (`'<base><sep><period>'`), for `read` / `ensureAtLeast`. */
+  counterKey: string;
+}
+/**
+ * The counter key and civil period for a base key at an instant. Use it to
+ * `read` / `ensureAtLeast` the same counter `getNextPeriodSequence` bumps.
+ */
+declare function periodCounterKey(baseKey: string, options: PeriodSequenceKeyOptions): {
+  counterKey: string;
+  period: string;
+};
+/**
+ * Atomically issue the next value of a counter that resets every civil
+ * year / month / day in an IANA time zone. The period is derived from `at`
+ * (default now) in `timeZone`, so every replica agrees on it whatever its
+ * `TZ`, and DST never moves a boundary.
+ *
+ * @example Yearly reference `OC-2026-000123` in Riyadh
+ * const { seq, period } = await getNextPeriodSequence('occ.occurrence', {
+ *   period: 'year', timeZone: 'Asia/Riyadh', at: reportedAt, connection, session,
+ * });
+ * const ref = `OC-${period}-${String(seq).padStart(6, '0')}`;
+ */
+declare function getNextPeriodSequence(baseKey: string, options: PeriodSequenceOptions & {
+  connection?: mongoose.Connection;
+}): Promise<PeriodSequenceResult>;
 interface SequentialIdOptions {
   /** Prefix string (e.g., 'INV', 'ORD') */
   prefix: string;
@@ -337,6 +443,11 @@ interface SequentialIdOptions {
   separator?: string;
   /** Custom counter key override (default: model.modelName) */
   counterKey?: string;
+  /**
+   * Counter collection, same as `createSequenceCounter({ collection })`
+   * (for hosts with a collection-naming rule). @default `'_mongokit_counters'`
+   */
+  counterCollection?: string;
 }
 /**
  * Generator: Simple sequential counter.
@@ -413,6 +524,30 @@ interface DateSequentialIdOptions {
    * stays invisible until one host is configured otherwise.
    */
   timezone?: 'local' | 'utc';
+  /**
+   * IANA time zone whose civil calendar decides the period (e.g.
+   * `'Asia/Riyadh'`). Wins over `timezone`. Read through Intl, so every
+   * replica agrees on the boundary whatever its `TZ`, and DST never moves it.
+   * Invalid zones throw when the generator is built.
+   */
+  timeZone?: string;
+  /**
+   * The instant whose civil date picks the period, e.g.
+   * `(ctx) => ctx.data?.reportedAt` so a backdated record numbers in its own
+   * period. `undefined` / `null` falls back to now; any other non-Date throws.
+   * @default now
+   */
+  at?: (context: RepositoryContext) => Date | undefined | null;
+  /**
+   * Base counter key (the tenant id, under `scope: 'tenant'`, and the period
+   * are appended). @default `model.modelName`
+   */
+  counterKey?: string;
+  /**
+   * Counter collection, same as `createSequenceCounter({ collection })`
+   * (for hosts with a collection-naming rule). @default `'_mongokit_counters'`
+   */
+  counterCollection?: string;
 }
 /**
  * Generator: Date-partitioned sequential counter.
@@ -493,8 +628,6 @@ declare function prefixedId(options: PrefixedIdOptions): IdGenerator;
  * ```
  */
 declare function customIdPlugin(options: CustomIdOptions): Plugin;
-//#endregion
-//#region src/plugins/multi-tenant.plugin.d.ts
 /**
  * Static tenant fields are picked from `@classytic/repo-core/tenant` so the
  * vocabulary (`tenantField`, `contextKey`, `required`, `fieldType`) stays
@@ -653,5 +786,4 @@ declare function adminBypass(options: {
   roleField?: string;
   adminRoles: readonly string[];
 }): (context: RepositoryContext, operation: string) => boolean;
-//#endregion
-export { EnsureAuditTrailReadyOptions as A, AuditQueryOptions as C, AuditTrailOptions as D, AuditTrailMode as E, ensureAuditTrailReady as M, AuditTrailQuery as O, AuditOperation as S, AuditTrailMethods as T, CacheOptions as _, DateSequentialIdOptions as a, cachePlugin as b, SequentialIdOptions as c, ensureSequenceAtLeast as d, getNextSequence as f, CacheAdapter$1 as g, sequentialId as h, CustomIdOptions as i, auditTrailPlugin as j, AuditTrailQueryOptions as k, customIdPlugin as l, readSequence as m, adminBypass as n, IdGenerator as o, prefixedId as p, multiTenantPlugin as r, PrefixedIdOptions as s, MultiTenantOptions as t, dateSequentialId as u, RepositoryCacheHandle$1 as v, AuditQueryResult as w, AuditEntry as x, RepositoryCachePluginOptions as y };
+export { cachePlugin as A, EnsureAuditTrailReadyOptions as B, prefixedId as C, CacheOptions as D, CacheAdapter$1 as E, AuditTrailMethods as F, ensureAuditTrailReady as H, AuditTrailMode as I, AuditTrailOptions as L, AuditOperation as M, AuditQueryOptions as N, RepositoryCacheHandle$1 as O, AuditQueryResult as P, AuditTrailQuery as R, periodCounterKey as S, sequentialId as T, auditTrailPlugin as V, customIdPlugin as _, DateSequentialIdOptions as a, getNextPeriodSequence as b, PeriodSequenceOptions as c, SequenceCounter as d, SequenceCounterOptions as f, createSequenceCounter as g, civilPeriodKey as h, CustomIdOptions as i, AuditEntry as j, RepositoryCachePluginOptions as k, PeriodSequenceResult as l, SequentialIdOptions as m, adminBypass as n, IdGenerator as o, SequencePeriod as p, multiTenantPlugin as r, PeriodSequenceKeyOptions as s, MultiTenantOptions as t, PrefixedIdOptions as u, dateSequentialId as v, readSequence as w, getNextSequence as x, ensureSequenceAtLeast as y, AuditTrailQueryOptions as z };