@classytic/repo-core 0.3.0 → 0.4.1

package/dist/plugins/tenant-helpers.mjs

@@ -0,0 +1,84 @@
+//#region src/plugins/tenant-helpers.ts
+/**
+* True when the op's policy target already has `tenantField` set by
+* the caller. Used to decide whether the plugin can safely skip
+* injecting a tenant scope rather than throwing on a missing context.
+*
+* - `data`       — `context.data[tenantField]` is present
+* - `dataArray`  — every row in `context.dataArray` has `tenantField`
+* - `query`      — `context.query[tenantField]` is present
+* - `filters`    — `context.filters[tenantField]` is present
+* - `operations` — every bulkWrite sub-op's filter/document has `tenantField`
+* - `none`       — unreachable (the hook isn't registered for these ops)
+*
+* For multi-row targets (`dataArray`, `operations`) we require EVERY
+* row to be stamped. Partial stamping is ambiguous (we have no
+* resolver value to fill in the gaps) and is safer to treat as "not
+* stamped" so the caller either stamps all rows or supplies a
+* context/resolver.
+*/
+function payloadHasTenantField(context, policyKey, tenantField) {
+	switch (policyKey) {
+		case "data": return context.data?.[tenantField] != null;
+		case "dataArray": {
+			const arr = context.dataArray;
+			if (!Array.isArray(arr) || arr.length === 0) return false;
+			return arr.every((row) => row && row[tenantField] != null);
+		}
+		case "query": return context.query?.[tenantField] != null;
+		case "filters": return context.filters?.[tenantField] != null;
+		case "operations": {
+			const ops = context.operations;
+			if (!Array.isArray(ops) || ops.length === 0) return false;
+			return ops.every((subOp) => {
+				for (const key of [
+					"updateOne",
+					"updateMany",
+					"deleteOne",
+					"deleteMany",
+					"replaceOne"
+				]) {
+					const body = subOp[key];
+					if (body) return body["filter"]?.[tenantField] != null;
+				}
+				const ins = subOp["insertOne"];
+				if (ins) return ins["document"]?.[tenantField] != null;
+				return false;
+			});
+		}
+		default: return false;
+	}
+}
+/**
+* Build a `skipWhen`-compatible callback that bypasses tenant scoping
+* when the caller's role is in `adminRoles`. Composable with any
+* kit's multi-tenant plugin shape.
+*
+* The factory does an exact-match `Set.has` check — case-sensitive,
+* no fuzzy matching. Lowercase your role vocabulary upstream.
+*
+* @example
+* ```ts
+* multiTenantPlugin({
+*   resolveTenantId: ctx => ctx.organizationId,
+*   skipWhen: adminBypass({ adminRoles: ['superadmin', 'support'] }),
+* });
+* ```
+*
+* @param options.roleField  Context key holding the role string (default: `'role'`)
+* @param options.adminRoles Roles that bypass tenant scope. Frozen on
+*   factory construction so callers can't mutate the list afterward
+*   and silently change bypass semantics across plugin instances
+*   sharing the array reference.
+* @returns A `skipWhen`-compatible callback `(ctx, op) → boolean`.
+*/
+function adminBypass(options) {
+	const { roleField = "role", adminRoles } = options;
+	const allowed = new Set(adminRoles);
+	return function skipWhenAdmin(context) {
+		const role = context[roleField];
+		return typeof role === "string" && allowed.has(role);
+	};
+}
+//#endregion
+export { adminBypass, payloadHasTenantField };

package/dist/query-parser/index.d.mts

@@ -1,4 +1,5 @@
 import { BracketOperator, ParsedPopulate, ParsedQuery, ParsedSelect, ParsedSort, ParsedSortDirection, QueryParserInput, QueryParserOptions } from "./types.mjs";
 import { coerceList, coerceValue } from "./coerce.mjs";
 import { parseUrl } from "./parse-url.mjs";
-export { type BracketOperator, type ParsedPopulate, type ParsedQuery, type ParsedSelect, type ParsedSort, type ParsedSortDirection, type QueryParserInput, type QueryParserOptions, coerceList, coerceValue, parseUrl };
+import { STANDARD_RESERVED_PARAMS, isControlParam } from "./reserved.mjs";
+export { type BracketOperator, type ParsedPopulate, type ParsedQuery, type ParsedSelect, type ParsedSort, type ParsedSortDirection, type QueryParserInput, type QueryParserOptions, STANDARD_RESERVED_PARAMS, coerceList, coerceValue, isControlParam, parseUrl };

package/dist/query-parser/index.mjs

@@ -1,3 +1,4 @@
 import { coerceList, coerceValue } from "./coerce.mjs";
+import { STANDARD_RESERVED_PARAMS, isControlParam } from "./reserved.mjs";
 import { parseUrl } from "./parse-url.mjs";
-export { coerceList, coerceValue, parseUrl };
+export { STANDARD_RESERVED_PARAMS, coerceList, coerceValue, isControlParam, parseUrl };

package/dist/query-parser/parse-url.mjs

@@ -1,21 +1,21 @@
 import { TRUE, and, between, contains, endsWith, eq, gt, gte, iEq, in_, isNotNull, isNull, like, lt, lte, ne, nin, regex, startsWith } from "../filter/builders.mjs";
 import { coerceList, coerceValue } from "./coerce.mjs";
+import { isControlParam } from "./reserved.mjs";
 //#region src/query-parser/parse-url.ts
 const DEFAULT_LIMIT = 20;
 const DEFAULT_MAX_LIMIT = 200;
 const DEFAULT_MAX_DEPTH = 10;
 const DEFAULT_MAX_REGEX = 500;
 const DEFAULT_MAX_SEARCH = 200;
-/** Reserved top-level URL keys the parser handles specially. */
-const RESERVED_KEYS = new Set([
-	"page",
-	"limit",
-	"after",
-	"sort",
-	"select",
-	"populate",
-	"search"
-]);
+/**
+* Hard cap on URL parameter KEY length. Param keys land in regex-based
+* bracket parsing (`/^([^[\]]+)\[([^\]]+)\]$/` and friends); without a
+* length bound, a hostile caller can submit a 1MB key and force the
+* parser to scan the entire string for every regex try. Keys that
+* exceed this cap are silently skipped — legitimate URL params don't
+* approach this bound.
+*/
+const MAX_PARAM_KEY_LENGTH = 256;
 const ALL_OPERATORS = new Set([
 	"eq",
 	"ne",
@@ -134,6 +134,7 @@ function parseSelect(raw) {
 function parsePopulate(params) {
 	const byField = /* @__PURE__ */ new Map();
 	for (const [key, value] of params.entries()) {
+		if (key.length > MAX_PARAM_KEY_LENGTH) continue;
 		if (!key.startsWith("populate[")) continue;
 		const match = /^populate\[([^\]]+)\](?:\[([^\]]+)\](?:\[([^\]]+)\])?)?$/.exec(key);
 		if (!match) continue;
@@ -163,7 +164,8 @@ function parseFilters(params, ctx) {
 	const leaves = [];
 	const fieldGroups = /* @__PURE__ */ new Map();
 	for (const [key, rawValue] of params.entries()) {
-		if (RESERVED_KEYS.has(key) || key.startsWith("populate[")) continue;
+		if (key.length > MAX_PARAM_KEY_LENGTH) continue;
+		if (isControlParam(key) || key.startsWith("populate[")) continue;
 		const bracket = /^([^[\]]+)\[([^\]]+)\]$/.exec(key);
 		let field;
 		let op;

package/dist/query-parser/reserved.d.mts

@@ -0,0 +1,43 @@
+//#region src/query-parser/reserved.d.ts
+/**
+ * URL parameter keys reserved by the framework — never parsed as
+ * filter predicates. Two categories:
+ *
+ * 1. **Pagination / list-control params** — `page`, `limit`, `after`,
+ *    `sort`, `select`, `populate`, `search`. Universal across kits;
+ *    every backend agrees on their meaning.
+ *
+ * 2. **Resource-dispatch verbs** — `_count`, `_distinct`, `_exists`.
+ *    Arc-style frameworks pick the repo method from these URL keys
+ *    (list vs count vs distinct vs exists).
+ *
+ * **Why an explicit allowlist, not a `_*` namespace.** MongoDB's `_id`
+ * (and every kit's analog) is a legitimate filter field; user-defined
+ * `_internal`, `_meta`, `_v` fields are common in real schemas. A
+ * blanket `key.startsWith('_')` rule silently drops filters on these.
+ * Adding a new dispatch verb here is a deliberate ecosystem-wide
+ * change — small, audited, and only needed every few major versions.
+ */
+/**
+ * Reserved top-level URL keys handled outside the filter pipeline.
+ * Pagination + sort + select + populate + search + resource-dispatch
+ * verbs (`_count`, `_distinct`, `_exists`).
+ */
+declare const STANDARD_RESERVED_PARAMS: ReadonlySet<string>;
+/**
+ * True when `key` is a framework-reserved URL parameter and should be
+ * skipped during filter parsing.
+ *
+ * Use in any URL-parser implementation that decides "is this a filter
+ * predicate or a control flag?":
+ *
+ * ```ts
+ * for (const [key, value] of params.entries()) {
+ *   if (isControlParam(key)) continue;  // skip page, limit, _count, ...
+ *   // … parse as filter predicate
+ * }
+ * ```
+ */
+declare function isControlParam(key: string): boolean;
+//#endregion
+export { STANDARD_RESERVED_PARAMS, isControlParam };

package/dist/query-parser/reserved.mjs

@@ -0,0 +1,56 @@
+//#region src/query-parser/reserved.ts
+/**
+* URL parameter keys reserved by the framework — never parsed as
+* filter predicates. Two categories:
+*
+* 1. **Pagination / list-control params** — `page`, `limit`, `after`,
+*    `sort`, `select`, `populate`, `search`. Universal across kits;
+*    every backend agrees on their meaning.
+*
+* 2. **Resource-dispatch verbs** — `_count`, `_distinct`, `_exists`.
+*    Arc-style frameworks pick the repo method from these URL keys
+*    (list vs count vs distinct vs exists).
+*
+* **Why an explicit allowlist, not a `_*` namespace.** MongoDB's `_id`
+* (and every kit's analog) is a legitimate filter field; user-defined
+* `_internal`, `_meta`, `_v` fields are common in real schemas. A
+* blanket `key.startsWith('_')` rule silently drops filters on these.
+* Adding a new dispatch verb here is a deliberate ecosystem-wide
+* change — small, audited, and only needed every few major versions.
+*/
+/**
+* Reserved top-level URL keys handled outside the filter pipeline.
+* Pagination + sort + select + populate + search + resource-dispatch
+* verbs (`_count`, `_distinct`, `_exists`).
+*/
+const STANDARD_RESERVED_PARAMS = new Set([
+	"page",
+	"limit",
+	"after",
+	"sort",
+	"select",
+	"populate",
+	"search",
+	"_count",
+	"_distinct",
+	"_exists"
+]);
+/**
+* True when `key` is a framework-reserved URL parameter and should be
+* skipped during filter parsing.
+*
+* Use in any URL-parser implementation that decides "is this a filter
+* predicate or a control flag?":
+*
+* ```ts
+* for (const [key, value] of params.entries()) {
+*   if (isControlParam(key)) continue;  // skip page, limit, _count, ...
+*   // … parse as filter predicate
+* }
+* ```
+*/
+function isControlParam(key) {
+	return STANDARD_RESERVED_PARAMS.has(key);
+}
+//#endregion
+export { STANDARD_RESERVED_PARAMS, isControlParam };

package/dist/repository/agg-output.d.mts

@@ -0,0 +1,63 @@
+//#region src/repository/agg-output.d.ts
+/**
+ * Cross-kit AggResult row-shape normalization.
+ *
+ * When an `AggRequest` includes `lookups` and `groupBy` references a
+ * joined-alias path (e.g. `'department.code'`), the row that lands in
+ * `AggResult.rows` carries the joined data as a NESTED object:
+ *
+ *   ```ts
+ *   { status: 'pending', department: { code: 'ENG' }, count: 3 }
+ *   ```
+ *
+ * Same convention `lookupPopulate` uses. Mongokit's `$project` with
+ * dotted-key output naturally nests; sqlitekit gets flat-dotted keys
+ * from Drizzle's SELECT alias map and runs results through
+ * `nestDottedKeys` before returning.
+ *
+ * **Why nested over flat-dotted?**
+ *   - Matches `lookupPopulate` precedent (single convention across
+ *     all read primitives).
+ *   - JSON-clean: `{ department: { code: 'ENG' } }` round-trips
+ *     identically through `JSON.stringify` / `parse`.
+ *   - Cleaner consumer code: `row.department.code` vs
+ *     `row['department.code']`.
+ *   - BSON allows nested but disallows literal `.` in field names —
+ *     the only shape that works in mongo without BSON workarounds.
+ *
+ * **Out of scope**:
+ *   - Multi-level dotted paths (`'a.b.c'`) — kits don't emit these
+ *     today (single-level joins only). The helper handles them
+ *     correctly by recursive descent so future depth is supported.
+ *   - Conflicting flat + nested keys on the same row (e.g. both
+ *     `department` and `department.code`). The flat-dotted side wins;
+ *     a top-level `department` value gets overwritten when a
+ *     `department.<x>` partner key is processed. In practice this
+ *     never happens — kits emit one or the other per groupBy key.
+ */
+/**
+ * Walk a row's top-level keys, splitting any that contain `.` into
+ * nested objects. Keys without `.` pass through unchanged. Mutates a
+ * fresh output object — the input is not modified.
+ *
+ * @example
+ * ```ts
+ * nestDottedKeys({ status: 'pending', 'department.code': 'ENG', count: 3 })
+ * // → { status: 'pending', department: { code: 'ENG' }, count: 3 }
+ * ```
+ *
+ * Multi-level paths (`a.b.c`) recurse:
+ *
+ * ```ts
+ * nestDottedKeys({ 'a.b.c': 1 })
+ * // → { a: { b: { c: 1 } } }
+ * ```
+ */
+declare function nestDottedKeys<T extends Record<string, unknown>>(row: T): Record<string, unknown>;
+/**
+ * Convenience wrapper for an array of rows. Returns a new array of
+ * normalized rows; the input is not modified.
+ */
+declare function nestDottedKeysAll<T extends Record<string, unknown>>(rows: readonly T[]): Record<string, unknown>[];
+//#endregion
+export { nestDottedKeys, nestDottedKeysAll };

package/dist/repository/agg-output.mjs

@@ -0,0 +1,89 @@
+//#region src/repository/agg-output.ts
+/**
+* Cross-kit AggResult row-shape normalization.
+*
+* When an `AggRequest` includes `lookups` and `groupBy` references a
+* joined-alias path (e.g. `'department.code'`), the row that lands in
+* `AggResult.rows` carries the joined data as a NESTED object:
+*
+*   ```ts
+*   { status: 'pending', department: { code: 'ENG' }, count: 3 }
+*   ```
+*
+* Same convention `lookupPopulate` uses. Mongokit's `$project` with
+* dotted-key output naturally nests; sqlitekit gets flat-dotted keys
+* from Drizzle's SELECT alias map and runs results through
+* `nestDottedKeys` before returning.
+*
+* **Why nested over flat-dotted?**
+*   - Matches `lookupPopulate` precedent (single convention across
+*     all read primitives).
+*   - JSON-clean: `{ department: { code: 'ENG' } }` round-trips
+*     identically through `JSON.stringify` / `parse`.
+*   - Cleaner consumer code: `row.department.code` vs
+*     `row['department.code']`.
+*   - BSON allows nested but disallows literal `.` in field names —
+*     the only shape that works in mongo without BSON workarounds.
+*
+* **Out of scope**:
+*   - Multi-level dotted paths (`'a.b.c'`) — kits don't emit these
+*     today (single-level joins only). The helper handles them
+*     correctly by recursive descent so future depth is supported.
+*   - Conflicting flat + nested keys on the same row (e.g. both
+*     `department` and `department.code`). The flat-dotted side wins;
+*     a top-level `department` value gets overwritten when a
+*     `department.<x>` partner key is processed. In practice this
+*     never happens — kits emit one or the other per groupBy key.
+*/
+/**
+* Walk a row's top-level keys, splitting any that contain `.` into
+* nested objects. Keys without `.` pass through unchanged. Mutates a
+* fresh output object — the input is not modified.
+*
+* @example
+* ```ts
+* nestDottedKeys({ status: 'pending', 'department.code': 'ENG', count: 3 })
+* // → { status: 'pending', department: { code: 'ENG' }, count: 3 }
+* ```
+*
+* Multi-level paths (`a.b.c`) recurse:
+*
+* ```ts
+* nestDottedKeys({ 'a.b.c': 1 })
+* // → { a: { b: { c: 1 } } }
+* ```
+*/
+function nestDottedKeys(row) {
+	const out = {};
+	for (const [key, value] of Object.entries(row)) {
+		if (key.indexOf(".") < 0) {
+			out[key] = value;
+			continue;
+		}
+		setDeep(out, key.split("."), value);
+	}
+	return out;
+}
+/**
+* Convenience wrapper for an array of rows. Returns a new array of
+* normalized rows; the input is not modified.
+*/
+function nestDottedKeysAll(rows) {
+	return rows.map((r) => nestDottedKeys(r));
+}
+function setDeep(target, path, value) {
+	let cursor = target;
+	for (let i = 0; i < path.length - 1; i++) {
+		const segment = path[i];
+		const existing = cursor[segment];
+		if (existing && typeof existing === "object" && !Array.isArray(existing)) cursor = existing;
+		else {
+			const next = {};
+			cursor[segment] = next;
+			cursor = next;
+		}
+	}
+	cursor[path[path.length - 1]] = value;
+}
+//#endregion
+export { nestDottedKeys, nestDottedKeysAll };

package/dist/repository/index.d.mts

@@ -1,6 +1,8 @@
 import { LookupPopulateOptions, LookupPopulateResult, LookupRow, LookupSpec } from "../lookup/types.mjs";
 import { UpdateInput } from "../update/types.mjs";
+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 { AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, BulkWriteOperation, BulkWriteResult, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindOneAndUpdateOptions, InferDoc, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions } from "./types.mjs";
-export { type AggMeasure, type AggPaginationRequest, type AggRequest, type AggResult, type AggRow, type BulkWriteOperation, type BulkWriteResult, type DeleteManyResult, type DeleteOptions, type DeleteResult, type FilterInput, type FindOneAndUpdateOptions, type InferDoc, 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, type StandardRepo, type UpdateInput, type UpdateManyResult, type WriteOptions, validatePluginOrder };
+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 };

package/dist/repository/index.mjs

@@ -1,3 +1,5 @@
+import { nestDottedKeys, nestDottedKeysAll } from "./agg-output.mjs";
 import { PLUGIN_ORDER_CONSTRAINTS, validatePluginOrder } from "./plugin-types.mjs";
 import { RepositoryBase } from "./base.mjs";
-export { PLUGIN_ORDER_CONSTRAINTS, RepositoryBase, validatePluginOrder };
+import { STANDARD_REPO_OPTION_KEYS } from "./options.mjs";
+export { PLUGIN_ORDER_CONSTRAINTS, RepositoryBase, STANDARD_REPO_OPTION_KEYS, nestDottedKeys, nestDottedKeysAll, validatePluginOrder };

package/dist/repository/options.d.mts

@@ -0,0 +1,62 @@
+//#region src/repository/options.d.ts
+/**
+ * Canonical option keys forwarded into every `MinimalRepo` /
+ * `StandardRepo` method call.
+ *
+ * The options bag is the cross-cutting plumbing every kit's plugin
+ * layer reads from: multi-tenant scope, audit attribution, transaction
+ * threading, observability correlation. Hosts (and arc-style
+ * frameworks) extract these from the request context once and forward
+ * them into every repo call so plugins don't need request-context
+ * access of their own.
+ *
+ * Without a single agreed-on set, drift is inevitable: one host
+ * forwards `userId`, another forwards `actorId`, a third forgets
+ * `requestId` entirely — and audit logs lose attribution silently.
+ * `STANDARD_REPO_OPTION_KEYS` is the contract every kit and every
+ * arc-style framework agrees on. Adding a key here is a deliberate
+ * ecosystem-wide commitment.
+ *
+ * Kits implementing custom plugins (commission, supplier-performance,
+ * pos, ...) can declare their own canonical sets via mongokit's
+ * `createOptionsExtractor<TCtx>` — that pattern stays domain-local and
+ * doesn't pollute the cross-kit contract.
+ */
+/**
+ * The canonical keys every kit's plugin layer reads from the options
+ * bag, and every framework auto-threads from request context.
+ *
+ * - `organizationId` — multi-tenant scope. Tenant plugins
+ *   (mongokit's `multiTenantPlugin`, sqlitekit's tenant filter) read
+ *   it to stamp on write + filter on read. Cast handling (e.g.
+ *   `ObjectId` coercion) is plugin-local — pass the raw scope id.
+ * - `userId` — actor id for audit attribution. Audit-log / audit-
+ *   trail plugins read it for the `who` column.
+ * - `user` — denormalized actor object, when the audit log wants
+ *   richer payload than a bare id (display name, role snapshot, ...).
+ * - `session` — driver-specific transaction handle. Mongoose
+ *   `ClientSession`, better-sqlite3 transaction fn, Prisma
+ *   transaction client. Opaque to repo-core — kits narrow at the
+ *   boundary.
+ * - `requestId` — request correlation id for trace stitching across
+ *   logs, events, and downstream service calls.
+ *
+ * Frameworks should treat this set as the canonical forward list:
+ * peel matching keys off the request context, drop them into the
+ * options bag, and let kit plugins read what they implement. Unknown
+ * ctx keys do NOT forward — the bag stays narrow.
+ */
+declare const STANDARD_REPO_OPTION_KEYS: readonly ["organizationId", "userId", "user", "session", "requestId"];
+/**
+ * Type-level union of canonical option keys. Use to constrain
+ * framework helpers that thread request context into repo options:
+ *
+ * ```ts
+ * function pickStandardOptions(ctx: Record<string, unknown>): Partial<
+ *   Record<StandardRepoOptionKey, unknown>
+ * > { ... }
+ * ```
+ */
+type StandardRepoOptionKey = (typeof STANDARD_REPO_OPTION_KEYS)[number];
+//#endregion
+export { STANDARD_REPO_OPTION_KEYS, StandardRepoOptionKey };

package/dist/repository/options.mjs

@@ -0,0 +1,57 @@
+//#region src/repository/options.ts
+/**
+* Canonical option keys forwarded into every `MinimalRepo` /
+* `StandardRepo` method call.
+*
+* The options bag is the cross-cutting plumbing every kit's plugin
+* layer reads from: multi-tenant scope, audit attribution, transaction
+* threading, observability correlation. Hosts (and arc-style
+* frameworks) extract these from the request context once and forward
+* them into every repo call so plugins don't need request-context
+* access of their own.
+*
+* Without a single agreed-on set, drift is inevitable: one host
+* forwards `userId`, another forwards `actorId`, a third forgets
+* `requestId` entirely — and audit logs lose attribution silently.
+* `STANDARD_REPO_OPTION_KEYS` is the contract every kit and every
+* arc-style framework agrees on. Adding a key here is a deliberate
+* ecosystem-wide commitment.
+*
+* Kits implementing custom plugins (commission, supplier-performance,
+* pos, ...) can declare their own canonical sets via mongokit's
+* `createOptionsExtractor<TCtx>` — that pattern stays domain-local and
+* doesn't pollute the cross-kit contract.
+*/
+/**
+* The canonical keys every kit's plugin layer reads from the options
+* bag, and every framework auto-threads from request context.
+*
+* - `organizationId` — multi-tenant scope. Tenant plugins
+*   (mongokit's `multiTenantPlugin`, sqlitekit's tenant filter) read
+*   it to stamp on write + filter on read. Cast handling (e.g.
+*   `ObjectId` coercion) is plugin-local — pass the raw scope id.
+* - `userId` — actor id for audit attribution. Audit-log / audit-
+*   trail plugins read it for the `who` column.
+* - `user` — denormalized actor object, when the audit log wants
+*   richer payload than a bare id (display name, role snapshot, ...).
+* - `session` — driver-specific transaction handle. Mongoose
+*   `ClientSession`, better-sqlite3 transaction fn, Prisma
+*   transaction client. Opaque to repo-core — kits narrow at the
+*   boundary.
+* - `requestId` — request correlation id for trace stitching across
+*   logs, events, and downstream service calls.
+*
+* Frameworks should treat this set as the canonical forward list:
+* peel matching keys off the request context, drop them into the
+* options bag, and let kit plugins read what they implement. Unknown
+* ctx keys do NOT forward — the bag stays narrow.
+*/
+const STANDARD_REPO_OPTION_KEYS = [
+	"organizationId",
+	"userId",
+	"user",
+	"session",
+	"requestId"
+];
+//#endregion
+export { STANDARD_REPO_OPTION_KEYS };