@classytic/repo-core 0.2.0 → 0.4.0

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.
  *
@@ -58,5 +69,45 @@ declare function isFieldUpdateAllowed(fieldName: string, options?: SchemaBuilder
  * walking the rules themselves.
  */
 declare function validateUpdateBody(body?: Record<string, unknown>, options?: SchemaBuilderOptions): ValidationResult;
+/**
+ * Merge constraint-style `fieldRules` into a generated schema bag in place.
+ *
+ * Operates on the three slots that carry property maps — `createBody`,
+ * `updateBody`, `response`. `listQuery` and `params` are skipped (their
+ * constraint vocabulary is owned by the kit's query parser).
+ *
+ * Existing constraints on a property always win — the merge only fills in
+ * gaps. Kits that already walk `fieldRules` during base-schema assembly
+ * can call this helper for free (the checks are no-ops when constraints
+ * already exist).
+ *
+ * Schema slot type is intentionally loose (`Record<string, unknown> | null
+ * | undefined`) so adapters can pass either an `OpenApiSchemas`-shaped bag
+ * or a kit-native bag without coercion.
+ */
+declare function mergeFieldRuleConstraints(schemas: Record<string, unknown> | null | undefined, schemaOptions?: SchemaBuilderOptions): void;
+/**
+ * Widen a JSON Schema property to also accept `null`.
+ *
+ * Handles the three ways a property can be typed:
+ *   - `type: 'string'`     → `type: ['string', 'null']`
+ *   - `type: [...]`        → append `'null'` if missing
+ *   - `anyOf: [...]`       → append `{ type: 'null' }` branch if missing
+ *
+ * **Enum interaction:** when the widened prop also carries `enum: [...]`,
+ * `null` is appended to the enum list too. AJV's `enum` keyword rejects
+ * values not in the list regardless of the widened `type`, so
+ * `{ type: ['string','null'], enum: ['a','b'] }` alone would still reject
+ * `null`. The fix is `enum: ['a','b', null]`. (The `anyOf` branch dodges
+ * this entirely — each branch scopes its own enum.)
+ *
+ * No-op when the schema already admits null (don't double-wrap) or has
+ * no `type` / `anyOf` anchor to widen (e.g. Mixed — already accepts null).
+ *
+ * Mutates in place — callers already treat the slot schema as owned.
+ * Exported so adapters that walk `fieldRules` inline can reuse the same
+ * widening logic.
+ */
+declare function applyNullable(prop: Record<string, unknown>): void;
 //#endregion
-export { applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody };
+export { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody };

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);
@@ -106,5 +126,96 @@ function validateUpdateBody(body = {}, options = {}) {
 		violations
 	};
 }
+/**
+* Merge constraint-style `fieldRules` into a generated schema bag in place.
+*
+* Operates on the three slots that carry property maps — `createBody`,
+* `updateBody`, `response`. `listQuery` and `params` are skipped (their
+* constraint vocabulary is owned by the kit's query parser).
+*
+* Existing constraints on a property always win — the merge only fills in
+* gaps. Kits that already walk `fieldRules` during base-schema assembly
+* can call this helper for free (the checks are no-ops when constraints
+* already exist).
+*
+* Schema slot type is intentionally loose (`Record<string, unknown> | null
+* | undefined`) so adapters can pass either an `OpenApiSchemas`-shaped bag
+* or a kit-native bag without coercion.
+*/
+function mergeFieldRuleConstraints(schemas, schemaOptions) {
+	if (!schemas || typeof schemas !== "object") return;
+	const rules = schemaOptions?.fieldRules;
+	if (!rules || Object.keys(rules).length === 0) return;
+	for (const slot of [
+		"createBody",
+		"updateBody",
+		"response"
+	]) {
+		const slotSchema = schemas[slot];
+		if (!slotSchema || typeof slotSchema !== "object") continue;
+		const properties = slotSchema["properties"];
+		if (!properties) continue;
+		for (const [field, rule] of Object.entries(rules)) {
+			const prop = properties[field];
+			if (!prop || typeof prop !== "object") continue;
+			if (rule.minLength != null && prop["minLength"] == null) prop["minLength"] = rule.minLength;
+			if (rule.maxLength != null && prop["maxLength"] == null) prop["maxLength"] = rule.maxLength;
+			if (rule.min != null && prop["minimum"] == null) prop["minimum"] = rule.min;
+			if (rule.max != null && prop["maximum"] == null) prop["maximum"] = rule.max;
+			if (rule.pattern != null && prop["pattern"] == null) prop["pattern"] = rule.pattern;
+			if (rule.enum != null && prop["enum"] == null) prop["enum"] = rule.enum;
+			if (rule.description != null && prop["description"] == null) prop["description"] = rule.description;
+			if (rule.nullable === true) applyNullable(prop);
+		}
+	}
+}
+/**
+* Widen a JSON Schema property to also accept `null`.
+*
+* Handles the three ways a property can be typed:
+*   - `type: 'string'`     → `type: ['string', 'null']`
+*   - `type: [...]`        → append `'null'` if missing
+*   - `anyOf: [...]`       → append `{ type: 'null' }` branch if missing
+*
+* **Enum interaction:** when the widened prop also carries `enum: [...]`,
+* `null` is appended to the enum list too. AJV's `enum` keyword rejects
+* values not in the list regardless of the widened `type`, so
+* `{ type: ['string','null'], enum: ['a','b'] }` alone would still reject
+* `null`. The fix is `enum: ['a','b', null]`. (The `anyOf` branch dodges
+* this entirely — each branch scopes its own enum.)
+*
+* No-op when the schema already admits null (don't double-wrap) or has
+* no `type` / `anyOf` anchor to widen (e.g. Mixed — already accepts null).
+*
+* Mutates in place — callers already treat the slot schema as owned.
+* Exported so adapters that walk `fieldRules` inline can reuse the same
+* widening logic.
+*/
+function applyNullable(prop) {
+	if (Array.isArray(prop["anyOf"])) {
+		if (!prop["anyOf"].some((b) => b !== null && typeof b === "object" && (b["type"] === "null" || b["const"] === null))) prop["anyOf"].push({ type: "null" });
+		return;
+	}
+	if (Array.isArray(prop["type"])) {
+		if (!prop["type"].includes("null")) prop["type"].push("null");
+		widenEnumToIncludeNull(prop);
+		return;
+	}
+	if (typeof prop["type"] === "string") {
+		prop["type"] = [prop["type"], "null"];
+		widenEnumToIncludeNull(prop);
+		return;
+	}
+}
+/**
+* Append `null` to `enum` when present. Required because AJV's `enum`
+* keyword is independent of `type` — a value must appear in the enum
+* array verbatim even if the widened type says null is allowed.
+*/
+function widenEnumToIncludeNull(prop) {
+	if (!Array.isArray(prop["enum"])) return;
+	if (prop["enum"].includes(null)) return;
+	prop["enum"] = [...prop["enum"], null];
+}
 //#endregion
-export { applyFieldRules, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, validateUpdateBody };
+export { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody };

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 { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody } from "./field-rules.mjs";
+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, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, 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 { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, mergeFieldRuleConstraints, validateUpdateBody } from "./field-rules.mjs";
+import { isSchemaGenerator } from "./generator.mjs";
+export { applyFieldRules, applyNullable, collectFieldsToOmit, getImmutableFields, getSystemManagedFields, isFieldUpdateAllowed, isSchemaGenerator, mergeFieldRuleConstraints, validateUpdateBody };

package/dist/schema/types.d.mts

@@ -26,6 +26,37 @@ 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;
+  /** String minimum length — JSON Schema `minLength`. */
+  minLength?: number;
+  /** String maximum length — JSON Schema `maxLength`. */
+  maxLength?: number;
+  /** Number minimum — JSON Schema `minimum`. */
+  min?: number;
+  /** Number maximum — JSON Schema `maximum`. */
+  max?: number;
+  /** Regex pattern — JSON Schema `pattern`. */
+  pattern?: string;
+  /** Allowed values — JSON Schema `enum`. */
+  enum?: ReadonlyArray<string | number>;
+  /**
+   * Widen the property type to also accept `null`. Implemented as a
+   * draft-07 type tuple (`type: ['string','null']`) or anyOf branch
+   * (`anyOf: [..., { type: 'null' }]`). Existing nullability is
+   * preserved — never double-widens.
+   */
+  nullable?: boolean;
+  /** Human-readable description — JSON Schema `description`. */
+  description?: string;
 }
 /** Map of field name → FieldRule. */
 interface FieldRules {
@@ -56,9 +87,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 +101,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 +127,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 +174,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 };