@classytic/repo-core 0.2.0 → 0.3.0

package/dist/pagination/types.d.mts

@@ -132,5 +132,69 @@ interface KeysetPaginationResultCore<TDoc> {
  * for the rationale. Defaults to `{}`.
  */
 type KeysetPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> = KeysetPaginationResultCore<TDoc> & TExtra;
+/**
+ * Core fields of an aggregate-paginated result. Don't consume this directly —
+ * use `AggregatePaginationResult<TDoc>` or `AggregatePaginationResult<TDoc, TExtra>`.
+ *
+ * Aggregate pagination produces page-shaped envelopes from arbitrary aggregate
+ * pipelines (mongokit's `aggregatePaginate` / `aggregatePipelinePaginate`,
+ * pgkit's CTE-based windowed counts, etc). The shape mirrors offset because
+ * the math is the same — the discriminant exists so consumers can route
+ * "this came from an aggregate, not a plain find" without inspecting the
+ * pipeline.
+ */
+interface AggregatePaginationResultCore<TDoc> {
+  method: 'aggregate';
+  docs: TDoc[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+/**
+ * Aggregate-paginated result envelope.
+ *
+ * `TExtra` parallels `OffsetPaginationResult` — kits surface deep-pagination
+ * warnings (`warning?: string`), aggregate-specific stats, etc.
+ */
+type AggregatePaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> = AggregatePaginationResultCore<TDoc> & TExtra;
+/**
+ * Union of every pagination *result* shape (server-side, pre-wire).
+ *
+ * What kits return from `getAll` / `aggregatePaginate`. Use this as the
+ * input type to anything that converts repo results into HTTP envelopes —
+ * see {@link toCanonicalList}.
+ */
+type AnyPaginationResult<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResult<TDoc, TExtra> | KeysetPaginationResult<TDoc, TExtra> | AggregatePaginationResult<TDoc, TExtra>;
+/** HTTP success envelope wrapping {@link OffsetPaginationResult}. */
+type OffsetPaginationResponse<TDoc, TExtra extends Record<string, unknown> = {}> = {
+  success: true;
+} & OffsetPaginationResult<TDoc, TExtra>;
+/** HTTP success envelope wrapping {@link KeysetPaginationResult}. */
+type KeysetPaginationResponse<TDoc, TExtra extends Record<string, unknown> = {}> = {
+  success: true;
+} & KeysetPaginationResult<TDoc, TExtra>;
+/** HTTP success envelope wrapping {@link AggregatePaginationResult}. */
+type AggregatePaginationResponse<TDoc, TExtra extends Record<string, unknown> = {}> = {
+  success: true;
+} & AggregatePaginationResult<TDoc, TExtra>;
+/**
+ * Bare list envelope — a successful response that wasn't paginated (raw
+ * array result). No `method` discriminant; consumers branch on the absence
+ * of pagination fields. Most useful when an endpoint sometimes paginates
+ * and sometimes returns a fixed-size list.
+ */
+interface BareListResponse<TDoc> {
+  success: true;
+  docs: TDoc[];
+}
+/**
+ * Union of every wire envelope a paginated/list endpoint can emit. Locked
+ * to `success: true` because errors take a separate envelope shape — a
+ * client-side type guard checks `success` first, then `method`.
+ */
+type PaginatedResponse<TDoc, TExtra extends Record<string, unknown> = {}> = OffsetPaginationResponse<TDoc, TExtra> | KeysetPaginationResponse<TDoc, TExtra> | AggregatePaginationResponse<TDoc, TExtra> | BareListResponse<TDoc>;
 //#endregion
-export { CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, PaginationConfig, SortDirection, SortSpec, ValueType };
+export { AggregatePaginationResponse, AggregatePaginationResult, AggregatePaginationResultCore, AnyPaginationResult, BareListResponse, CursorPayload, DecodedCursor, KeysetPaginationResponse, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResponse, OffsetPaginationResult, OffsetPaginationResultCore, PaginatedResponse, PaginationConfig, SortDirection, SortSpec, ValueType };

package/dist/repository/base.mjs

@@ -15,11 +15,13 @@ var RepositoryBase = class {
 		this.modelName = options.name;
 		this.hooks = new HookEngine(options.hooks ?? "async");
 		const plugins = options.plugins ?? [];
+		for (let i = 0; i < plugins.length; i++) assertValidPlugin(plugins[i], this.modelName, i);
 		validatePluginOrder(plugins, this.modelName, options.pluginOrderChecks ?? "warn", options.onPluginOrderWarning);
 		for (const plugin of plugins) this.use(plugin);
 	}
 	/** Install a plugin (object with `apply(repo)` or a plain function). */
 	use(plugin) {
+		assertValidPlugin(plugin, this.modelName);
 		if (typeof plugin === "function") plugin(this);
 		else plugin.apply(this);
 		return this;
@@ -107,5 +109,24 @@ var RepositoryBase = class {
 		return context["_cachedResult"];
 	}
 };
+/**
+* Reject malformed plugin entries before they reach `use()`.
+*
+* Caught the field-reported `new Repository(Model, ['organizationId'], ...)`
+* crash where a tenant-field string array landed in the plugins slot and
+* blew up with `TypeError: plugin.apply is not a function` deep inside the
+* constructor. Validating shape up front turns that into a single, action-
+* able error pointing at the offending index.
+*/
+function assertValidPlugin(plugin, repoName, index) {
+	const where = typeof index === "number" ? `plugin at index ${index}` : "plugin";
+	if (plugin === null || plugin === void 0) throw new TypeError(`[repo-core] Repository "${repoName}": ${where} is ${plugin === null ? "null" : "undefined"}. Expected a function \`(repo) => void\` or an object \`{ name, apply(repo) }\`.`);
+	if (typeof plugin === "function") return;
+	if (typeof plugin !== "object") {
+		const detail = typeof plugin === "string" ? `'${plugin}'` : "";
+		throw new TypeError(`[repo-core] Repository "${repoName}": ${where} has wrong type. Expected a function or { name, apply(repo) } object — got ${typeof plugin} ${detail}. Common cause: \`new Repository(Model, [tenantField], opts)\` — second argument must be a plugins array.`);
+	}
+	if (typeof plugin.apply !== "function") throw new TypeError(`[repo-core] Repository "${repoName}": ${where} is an object but missing \`apply(repo)\`. Expected \`{ name: string, apply: (repo) => void }\`.`);
+}
 //#endregion
 export { RepositoryBase };

package/dist/schema/field-rules.d.mts

@@ -4,17 +4,28 @@ import { JsonSchema, SchemaBuilderOptions, ValidationResult } from "./types.mjs"
 /**
  * Collect the set of fields that must NOT appear in a generated schema.
  *
- * Combines four sources in priority order:
- *   1. Always-hidden system fields (`createdAt`, `updatedAt`, `__v`).
- *   2. `fieldRules[field].systemManaged` → hidden from both create & update.
- *   3. For update schemas: `fieldRules[field].immutable` /
- *      `immutableAfterCreate` → hidden from update only.
- *   4. `options.create.omitFields` / `options.update.omitFields` — explicit
- *      caller-provided omit list for the matching purpose.
+ * Three purposes have three different policies:
+ *
+ *   - `'create'` / `'update'` (request-body schemas):
+ *     1. Always-hidden system fields (`createdAt`, `updatedAt`, `__v`).
+ *     2. `fieldRules[field].systemManaged` → hidden from both.
+ *     3. `'update'` only: `fieldRules[field].immutable` /
+ *        `immutableAfterCreate` → hidden from update.
+ *     4. `options.create.omitFields` / `options.update.omitFields` —
+ *        explicit caller-provided omit list for the matching purpose.
+ *
+ *   - `'response'` (response-shape schema):
+ *     1. `fieldRules[field].hidden: true` ONLY — passwords, secrets,
+ *        internal scoring. Server-set fields (`createdAt`, `updatedAt`,
+ *        `_id`, systemManaged, immutable / readonly) ARE returned to
+ *        clients and so ARE included in the response shape.
+ *     2. `options.response?.omitFields` — explicit caller-provided omit
+ *        list when the host wants to strip extra fields from responses
+ *        without marking them `hidden` globally.
  *
  * Returns a fresh `Set<string>` so callers can freely mutate.
  */
-declare function collectFieldsToOmit(options: SchemaBuilderOptions, purpose: 'create' | 'update'): Set<string>;
+declare function collectFieldsToOmit(options: SchemaBuilderOptions, purpose: 'create' | 'update' | 'response'): Set<string>;
 /**
  * Apply omissions + `optional` overrides to a built JSON Schema in place.
  *

package/dist/schema/field-rules.mjs

@@ -2,23 +2,43 @@
 /**
 * Collect the set of fields that must NOT appear in a generated schema.
 *
-* Combines four sources in priority order:
-*   1. Always-hidden system fields (`createdAt`, `updatedAt`, `__v`).
-*   2. `fieldRules[field].systemManaged` → hidden from both create & update.
-*   3. For update schemas: `fieldRules[field].immutable` /
-*      `immutableAfterCreate` → hidden from update only.
-*   4. `options.create.omitFields` / `options.update.omitFields` — explicit
-*      caller-provided omit list for the matching purpose.
+* Three purposes have three different policies:
+*
+*   - `'create'` / `'update'` (request-body schemas):
+*     1. Always-hidden system fields (`createdAt`, `updatedAt`, `__v`).
+*     2. `fieldRules[field].systemManaged` → hidden from both.
+*     3. `'update'` only: `fieldRules[field].immutable` /
+*        `immutableAfterCreate` → hidden from update.
+*     4. `options.create.omitFields` / `options.update.omitFields` —
+*        explicit caller-provided omit list for the matching purpose.
+*
+*   - `'response'` (response-shape schema):
+*     1. `fieldRules[field].hidden: true` ONLY — passwords, secrets,
+*        internal scoring. Server-set fields (`createdAt`, `updatedAt`,
+*        `_id`, systemManaged, immutable / readonly) ARE returned to
+*        clients and so ARE included in the response shape.
+*     2. `options.response?.omitFields` — explicit caller-provided omit
+*        list when the host wants to strip extra fields from responses
+*        without marking them `hidden` globally.
 *
 * Returns a fresh `Set<string>` so callers can freely mutate.
 */
 function collectFieldsToOmit(options, purpose) {
+	const rules = options?.fieldRules ?? {};
+	const globalExcludes = options?.excludeFields ?? [];
+	if (purpose === "response") {
+		const result = new Set(globalExcludes);
+		for (const [field, rule] of Object.entries(rules)) if (rule.hidden) result.add(field);
+		const explicit = options?.response?.omitFields;
+		if (explicit) for (const f of explicit) result.add(f);
+		return result;
+	}
 	const result = new Set([
 		"createdAt",
 		"updatedAt",
-		"__v"
+		"__v",
+		...globalExcludes
 	]);
-	const rules = options?.fieldRules ?? {};
 	for (const [field, rule] of Object.entries(rules)) {
 		if (rule.systemManaged) result.add(field);
 		if (purpose === "update" && (rule.immutable || rule.immutableAfterCreate)) result.add(field);

package/dist/schema/generator.d.mts

@@ -0,0 +1,72 @@
+import { CrudSchemas, SchemaBuilderOptions } from "./types.mjs";
+
+//#region src/schema/generator.d.ts
+/**
+ * Resource-level context threaded into the generator at boot. Lets the
+ * generator shape output to per-resource config (idField pattern,
+ * resource name for OpenAPI titles).
+ *
+ * All fields optional — generators that ignore the context still produce
+ * valid schemas; arc applies safety-net normalization downstream.
+ */
+interface SchemaGeneratorContext {
+  /**
+   * The `idField` configured on the resource. Defaults to `'_id'` for
+   * Mongoose-shaped kits, `'id'` for SQL kits. Generators emit the
+   * matching `params.properties[idField]` so route-param validation
+   * matches the actual lookup field.
+   */
+  idField?: string;
+  /** Resource name (for OpenAPI titles, generator log messages). */
+  resourceName?: string;
+}
+/**
+ * Canonical generator contract. Functions that produce CRUD JSON schemas
+ * for a kit satisfy this shape — `mongokit/buildCrudSchemasFromModel`,
+ * `sqlitekit/buildCrudSchemasFromTable`, etc.
+ *
+ * The return type is intentionally widened to `CrudSchemas | Record<string,
+ * unknown>` so kits that emit additional vendor-specific schema fields
+ * (`x-ref`, `x-foreign-key`, OpenAPI extensions) flow through without
+ * type erosion. Arc's adapter post-processes via `mergeFieldRuleConstraints`
+ * so portable `fieldRules` constraints (`minLength`/`maxLength`/`min`/
+ * `max`/`pattern`/`enum`/`description`/`nullable`) apply uniformly across
+ * kit outputs.
+ *
+ * @typeParam TModel - The kit's native model / table type. `Model<unknown>`
+ *   for Mongoose kits, a Drizzle `Table` for SQL kits, etc. Widened to
+ *   `unknown` by default so adapters that don't care about model typing
+ *   (or cross-kit utilities) pass any model through.
+ *
+ * @example mongokit conformance (one-line `satisfies`)
+ * ```ts
+ * import type { SchemaGenerator } from '@classytic/repo-core/schema';
+ *
+ * export const buildCrudSchemasFromModel = ((model, options, ctx) => {
+ *   // ... existing impl
+ * }) satisfies SchemaGenerator<Model<unknown>>;
+ * ```
+ *
+ * @example arc adapter typing
+ * ```ts
+ * import type { SchemaGenerator } from '@classytic/repo-core/schema';
+ *
+ * interface MongooseAdapterOptions<TDoc> {
+ *   schemaGenerator?: SchemaGenerator<Model<unknown>>;
+ * }
+ * ```
+ */
+type SchemaGenerator<TModel = unknown> = (model: TModel, options?: SchemaBuilderOptions, context?: SchemaGeneratorContext) => CrudSchemas | Record<string, unknown>;
+/**
+ * Runtime predicate — true when `value` matches the generator shape.
+ *
+ * Conservative: only checks `typeof value === 'function'` and arity.
+ * Doesn't invoke the function with a sentinel argument because doing so
+ * could trigger expensive schema introspection on a single test call.
+ * The structural-typing alignment (`satisfies SchemaGenerator<...>`) is
+ * the primary contract enforcement; this guard is for runtime hosts that
+ * accept either a generator or a config-bag.
+ */
+declare function isSchemaGenerator(value: unknown): value is SchemaGenerator;
+//#endregion
+export { SchemaGenerator, SchemaGeneratorContext, isSchemaGenerator };

package/dist/schema/generator.mjs

@@ -0,0 +1,16 @@
+//#region src/schema/generator.ts
+/**
+* Runtime predicate — true when `value` matches the generator shape.
+*
+* Conservative: only checks `typeof value === 'function'` and arity.
+* Doesn't invoke the function with a sentinel argument because doing so
+* could trigger expensive schema introspection on a single test call.
+* The structural-typing alignment (`satisfies SchemaGenerator<...>`) is
+* the primary contract enforcement; this guard is for runtime hosts that
+* accept either a generator or a config-bag.
+*/
+function isSchemaGenerator(value) {
+	return typeof value === "function" && value.length >= 1 && value.length <= 3;
+}
+//#endregion
+export { isSchemaGenerator };

package/dist/schema/index.d.mts

@@ -1,3 +1,4 @@
 import { CrudSchemas, FieldRule, FieldRules, JsonSchema, SchemaBuilderOptions, ValidationResult } from "./types.mjs";
 import { applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody } from "./field-rules.mjs";
-export { type CrudSchemas, type FieldRule, type FieldRules, type JsonSchema, type SchemaBuilderOptions, type ValidationResult, applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody };
+import { SchemaGenerator, SchemaGeneratorContext, isSchemaGenerator } from "./generator.mjs";
+export { type CrudSchemas, type FieldRule, type FieldRules, type JsonSchema, type SchemaBuilderOptions, type SchemaGenerator, type SchemaGeneratorContext, type ValidationResult, applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, validateUpdateBody };

package/dist/schema/index.mjs

@@ -1,2 +1,3 @@
 import { applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody } from "./field-rules.mjs";
-export { applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody };
+import { isSchemaGenerator } from "./generator.mjs";
+export { applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, validateUpdateBody };

package/dist/schema/types.d.mts

@@ -26,6 +26,16 @@ interface FieldRule {
   systemManaged?: boolean;
   /** Remove from `required[]` in the generated schema. DB-level constraints unaffected. */
   optional?: boolean;
+  /**
+   * Strip the field from the response shape. Use for passwords, secrets,
+   * internal scoring — anything the server stores but should never echo.
+   *
+   * Distinct from `systemManaged` (which only affects request bodies):
+   * `hidden` is a *response* concern and lives at the schema-builder
+   * boundary so kits, OpenAPI tooling, and arc's response serializer
+   * narrow on the same flag.
+   */
+  hidden?: boolean;
 }
 /** Map of field name → FieldRule. */
 interface FieldRules {
@@ -56,9 +66,10 @@ interface JsonSchema {
   [key: `x-${string}`]: unknown;
 }
 /**
- * CRUD schema bundle — the four JSON Schemas every HTTP endpoint needs:
- * body validation on POST / PATCH, route-param validation on id routes, and
- * query-string validation on list endpoints.
+ * CRUD schema bundle — the JSON Schemas every HTTP endpoint needs:
+ * body validation on POST / PATCH, route-param validation on id routes,
+ * query-string validation on list endpoints, and (optionally) response-shape
+ * documentation for OpenAPI / strict reply serialization.
  */
 interface CrudSchemas {
   /** JSON Schema for create request body (POST). */
@@ -69,6 +80,23 @@ interface CrudSchemas {
   params: JsonSchema;
   /** JSON Schema for list/query parameters. */
   listQuery: JsonSchema;
+  /**
+   * JSON Schema for response shape (optional).
+   *
+   * Includes every field a client receives — server-set fields
+   * (`createdAt`, `updatedAt`, `_id`, immutable / readonly fields) ARE
+   * returned to clients and so ARE included in the response shape, in
+   * contrast to `createBody` / `updateBody` which exclude them. Only
+   * `fieldRules[field].hidden: true` excludes a field from responses
+   * (passwords, secrets, internal scoring).
+   *
+   * Set `additionalProperties: true` so virtuals and computed fields
+   * pass through without being stripped by AJV's strict serialization.
+   *
+   * Optional — kits that don't ship a response builder leave it unset
+   * and arc treats response validation as opt-out for that resource.
+   */
+  response?: JsonSchema;
 }
 /**
  * Options consumed by every kit's schema builder. Fields are additive:
@@ -78,6 +106,18 @@ interface CrudSchemas {
 interface SchemaBuilderOptions {
   /** Field rules for create/update schemas. */
   fieldRules?: FieldRules;
+  /**
+   * Global field exclusion — fields listed here are dropped from EVERY
+   * generated schema (create / update / response). Shortcut for setting
+   * `create.omitFields`, `update.omitFields`, AND `response.omitFields`
+   * to the same list. Use for fields that should never appear in any
+   * HTTP-facing schema (e.g. internal-only columns, framework-private
+   * fields).
+   *
+   * Per-purpose overrides still apply on top — a field listed here AND
+   * in `create.omitFields` is dropped once.
+   */
+  excludeFields?: string[];
   /**
    * When `true`, emit `"additionalProperties": false` on create/update/query
    * schemas. Default `false` so generators stay permissive by default;
@@ -113,6 +153,19 @@ interface SchemaBuilderOptions {
       type: string;
     } | unknown>;
   };
+  /**
+   * Response-schema overrides.
+   *
+   * Response shape includes server-set fields (`createdAt`, `updatedAt`,
+   * `_id`, immutable / readonly / systemManaged fields) since those ARE
+   * returned to clients. Only `fieldRules[field].hidden: true` fields are
+   * stripped automatically. Use `omitFields` to drop additional fields
+   * from responses without marking them globally hidden (e.g. internal
+   * scoring you want kept in update bodies but stripped from list reads).
+   */
+  response?: {
+    /** Extra fields to omit from the response shape. */omitFields?: string[];
+  };
   /**
    * Emit OpenAPI vendor extensions (`x-*` keywords like `x-ref` for populated
    * foreign-key fields).

package/dist/tenant/index.d.mts

@@ -0,0 +1,3 @@
+import { ResolvedTenantConfig, TenantConfig, TenantFieldType, TenantStrategy } from "./types.mjs";
+import { DEFAULT_TENANT_CONFIG, resolveTenantConfig } from "./resolve.mjs";
+export { DEFAULT_TENANT_CONFIG, type ResolvedTenantConfig, type TenantConfig, type TenantFieldType, type TenantStrategy, resolveTenantConfig };

package/dist/tenant/index.mjs

@@ -0,0 +1,2 @@
+import { DEFAULT_TENANT_CONFIG, resolveTenantConfig } from "./resolve.mjs";
+export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };

package/dist/tenant/resolve.d.mts

@@ -0,0 +1,27 @@
+import { ResolvedTenantConfig, TenantConfig } from "./types.mjs";
+
+//#region src/tenant/resolve.d.ts
+/**
+ * Sensible defaults for a freshly-built package (field strategy).
+ *
+ * `fieldType: 'objectId'` is the recommended default for new Mongo-shaped
+ * kits because it enables `$lookup` / `.populate()`. Existing kits that
+ * historically defaulted to `'string'` (mongokit pre-3.x) keep their own
+ * runtime default — `Pick<TenantConfig, 'fieldType'>` extension preserves
+ * type-level alignment without forcing a runtime default change.
+ */
+declare const DEFAULT_TENANT_CONFIG: Required<Pick<TenantConfig, 'strategy' | 'enabled' | 'tenantField' | 'fieldType' | 'ref' | 'contextKey' | 'required'>>;
+/**
+ * Resolve a possibly-partial {@link TenantConfig} against the defaults.
+ *
+ * - `false` → `enabled: false`, `strategy: 'none'`, `required: false`.
+ * - `true` / `undefined` → default field strategy.
+ * - Object with `strategy: 'custom'` → `resolve` is required; throws
+ *   otherwise so the misconfiguration surfaces at boot, not runtime.
+ * - Object with `strategy: 'none'` → `enabled: false` (preserves
+ *   user-supplied `tenantField` / `fieldType` / `ref` so the doc field
+ *   stays correctly typed even with scoping off).
+ */
+declare function resolveTenantConfig(config?: TenantConfig | boolean): ResolvedTenantConfig;
+//#endregion
+export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };

package/dist/tenant/resolve.mjs

@@ -0,0 +1,69 @@
+//#region src/tenant/resolve.ts
+/**
+* Sensible defaults for a freshly-built package (field strategy).
+*
+* `fieldType: 'objectId'` is the recommended default for new Mongo-shaped
+* kits because it enables `$lookup` / `.populate()`. Existing kits that
+* historically defaulted to `'string'` (mongokit pre-3.x) keep their own
+* runtime default — `Pick<TenantConfig, 'fieldType'>` extension preserves
+* type-level alignment without forcing a runtime default change.
+*/
+const DEFAULT_TENANT_CONFIG = {
+	strategy: "field",
+	enabled: true,
+	tenantField: "organizationId",
+	fieldType: "objectId",
+	ref: "organization",
+	contextKey: "organizationId",
+	required: true
+};
+/**
+* Resolve a possibly-partial {@link TenantConfig} against the defaults.
+*
+* - `false` → `enabled: false`, `strategy: 'none'`, `required: false`.
+* - `true` / `undefined` → default field strategy.
+* - Object with `strategy: 'custom'` → `resolve` is required; throws
+*   otherwise so the misconfiguration surfaces at boot, not runtime.
+* - Object with `strategy: 'none'` → `enabled: false` (preserves
+*   user-supplied `tenantField` / `fieldType` / `ref` so the doc field
+*   stays correctly typed even with scoping off).
+*/
+function resolveTenantConfig(config) {
+	if (config === false) return {
+		...DEFAULT_TENANT_CONFIG,
+		strategy: "none",
+		enabled: false,
+		required: false
+	};
+	if (config === true || config === void 0) return { ...DEFAULT_TENANT_CONFIG };
+	const strategy = config.strategy ?? (config.enabled === false ? "none" : "field");
+	const contextKey = config.contextKey ?? config.tenantField ?? DEFAULT_TENANT_CONFIG.contextKey;
+	if (strategy === "none") return {
+		...DEFAULT_TENANT_CONFIG,
+		...config,
+		contextKey,
+		strategy: "none",
+		enabled: false,
+		required: false
+	};
+	if (strategy === "custom") {
+		if (typeof config.resolve !== "function") throw new Error("[repo-core] TenantConfig.strategy 'custom' requires a 'resolve' function");
+		return {
+			...DEFAULT_TENANT_CONFIG,
+			...config,
+			contextKey,
+			strategy: "custom",
+			enabled: config.enabled ?? true,
+			resolve: config.resolve
+		};
+	}
+	return {
+		...DEFAULT_TENANT_CONFIG,
+		...config,
+		contextKey,
+		strategy: "field",
+		enabled: config.enabled ?? true
+	};
+}
+//#endregion
+export { DEFAULT_TENANT_CONFIG, resolveTenantConfig };

package/dist/tenant/types.d.mts

@@ -0,0 +1,142 @@
+//#region src/tenant/types.d.ts
+/**
+ * Tenant scope configuration — canonical static contract for the org.
+ *
+ * **`@classytic/repo-core/tenant` is the single source of truth.** Every
+ * multi-tenant-capable package (`@classytic/mongokit`, `@classytic/sqlitekit`,
+ * future kits, arc presets, services) consumes {@link TenantConfig} for its
+ * static fields and extends with kit-specific runtime callbacks via
+ * `Pick<TenantConfig, ...>` to lock the field vocabulary by structural typing.
+ *
+ * Three strategies are supported:
+ * - `'field'` (default) — filter every query by a scalar field on documents.
+ *   The common case; used by `multiTenantPlugin` in mongokit and sqlitekit.
+ * - `'none'` — disable scoping entirely (single-tenant app). Equivalent to
+ *   `enabled: false`; `strategy: 'none'` is the explicit form.
+ * - `'custom'` — caller supplies a `resolve(ctx)` function that returns the
+ *   filter shape to inject. **The escape hatch for custom systems** —
+ *   covers multi-field composite tenants, context-derived filters
+ *   (region + partner id), non-scalar scope keys, or any tenancy model that
+ *   doesn't fit the simple `field === id` pattern.
+ *
+ * **Why this layer is static-only.** Runtime callbacks (`skipWhen(ctx, op)`,
+ * `resolveContext()`, `resolveTenantId(ctx)`) genuinely differ across kits
+ * because their `RepositoryContext` shapes differ — mongokit's resolver
+ * returns just an id, sqlitekit's takes a richer context object. Each kit
+ * extends `TenantConfig` with its own runtime-callback fields. Hosts who
+ * need a single config object can compose: pass the static `TenantConfig`
+ * through {@link resolveTenantConfig} once, then forward the resolved
+ * static fields into each kit's runtime options alongside the kit-specific
+ * callbacks.
+ */
+/**
+ * Storage / cast strategy for the tenant identifier on documents.
+ *
+ * - `'objectId'` (recommended for new packages) — `Schema.Types.ObjectId`
+ *   with `ref`. Enables `$lookup`, `.populate()`, QueryParser `?lookup=...`
+ *   on Mongo-shaped kits. SQL kits typically ignore this and rely on
+ *   schema-defined column types instead.
+ * - `'string'` — plain string. Use when the host auth system issues UUIDs
+ *   or slugs rather than ObjectIds.
+ */
+type TenantFieldType = 'objectId' | 'string';
+/** Scope resolution strategy. */
+type TenantStrategy = 'field' | 'none' | 'custom';
+interface TenantConfig {
+  /**
+   * Scope strategy. Omit for the common `'field'` case — explicit `'none'`
+   * / `'custom'` lets packages collapse what used to live in a separate
+   * `ScopeConfig` type.
+   *
+   * @default 'field'
+   */
+  strategy?: TenantStrategy;
+  /**
+   * Whether tenant scoping is active. When `false`, the package runs in
+   * single-tenant mode — no filter injection, no tenant field on documents.
+   * Equivalent to `strategy: 'none'`.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Document / column field name that stores the tenant id. Used when
+   * `strategy === 'field'`.
+   *
+   * @default 'organizationId'
+   */
+  tenantField?: string;
+  /**
+   * How to store / cast the tenant id.
+   *
+   * @default 'objectId'
+   */
+  fieldType?: TenantFieldType;
+  /**
+   * Mongoose ref for `'objectId'` types. Ignored by SQL kits and when
+   * `fieldType === 'string'`.
+   *
+   * @default 'organization'
+   */
+  ref?: string;
+  /**
+   * Which key on the repository context to read the tenant id from.
+   *
+   * Defaults cascade: if omitted, falls back to the caller's `tenantField`
+   * (if supplied), else to `'organizationId'`. Rationale: when a host renames
+   * `tenantField` to e.g. `'branchId'`, their context almost always carries
+   * the value under the same key — mirroring `tenantField` is the
+   * least-surprise behavior. Override explicitly if the context key diverges
+   * from the document field (e.g. `tenantField: 'branchId'`,
+   * `contextKey: 'organizationId'`).
+   *
+   * @default tenantField ?? 'organizationId'
+   */
+  contextKey?: string;
+  /**
+   * Whether the field is required. When `false`, the package permits
+   * unscoped / cross-tenant reads (typically only for admin paths).
+   *
+   * @default true
+   */
+  required?: boolean;
+  /**
+   * Custom resolver — called when `strategy === 'custom'` to produce the
+   * filter object injected into queries. Packages pass the request /
+   * repository context; the resolver returns the filter shape.
+   *
+   * Use for tenancy models that don't fit the simple `field === id`
+   * pattern: multi-field composites, context-derived filters
+   * (region + partner id), hash-derived shards, etc.
+   *
+   * @example
+   * ```ts
+   * {
+   *   strategy: 'custom',
+   *   resolve: (ctx) => ({
+   *     organizationId: ctx.organizationId,
+   *     region: ctx.region,
+   *     partnerId: ctx.partnerId,
+   *   }),
+   * }
+   * ```
+   */
+  resolve?: (ctx: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Resolved shape returned by `resolveTenantConfig`. Always includes the
+ * field defaults (so packages can inspect field names even when
+ * `enabled: false`) and threads `resolve` when `strategy === 'custom'`.
+ */
+type ResolvedTenantConfig = {
+  strategy: TenantStrategy;
+  enabled: boolean;
+  tenantField: string;
+  fieldType: TenantFieldType;
+  ref: string;
+  contextKey: string;
+  required: boolean;
+  resolve?: TenantConfig['resolve'];
+};
+//#endregion
+export { ResolvedTenantConfig, TenantConfig, TenantFieldType, TenantStrategy };