@classytic/repo-core 0.1.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/repository/index.d.mts

@@ -1,5 +1,6 @@
 import { LookupPopulateOptions, LookupPopulateResult, LookupRow, LookupSpec } from "../lookup/types.mjs";
+import { UpdateInput } from "../update/types.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, 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 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 UpdateManyResult, type WriteOptions, validatePluginOrder };
+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 };

package/dist/repository/types.d.mts

@@ -1,6 +1,7 @@
 import { Filter } from "../filter/types.mjs";
 import { OffsetPaginationResult } from "../pagination/types.mjs";
 import { LookupPopulateOptions, LookupPopulateResult } from "../lookup/types.mjs";
+import { UpdateInput } from "../update/types.mjs";
 
 //#region src/repository/types.d.ts
 /**
@@ -286,7 +287,17 @@ interface AggResult<TRow extends AggRow = AggRow> {
  * - **Raw** — neither; kit returns all matching docs (may be large).
  */
 interface PaginationParams<TDoc = unknown> {
-  filters?: Partial<TDoc> & Record<string, unknown>;
+  /**
+   * Predicate narrowing the rows that feed into the list query. Accepts
+   * the portable Filter IR (`and(eq(...), gt(...))`) OR a flat kit-native
+   * record (`{ status: 'active', age: { $gt: 18 } }`). Every kit's
+   * `getAll` compiler handles both forms.
+   *
+   * The `Partial<TDoc>` intersection preserves the old "typed flat record"
+   * DX for callers that pass a POJO — they still get autocomplete on
+   * known document fields while the union branch allows the Filter IR.
+   */
+  filters?: (Partial<TDoc> & Record<string, unknown>) | Filter;
   sort?: string | Record<string, 1 | -1>;
   page?: number;
   limit?: number;
@@ -373,8 +384,26 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
    * Required for arc's outbox, distributed-lock, and workflow-semaphore
    * patterns. Kits without atomic CAS should simulate it inside a
    * transaction — arc's stores assume single-round-trip semantics.
+   *
+   * **Update argument forms** (see {@link UpdateInput}):
+   *
+   *   1. `UpdateSpec` — portable IR built via `update({ set, unset, inc,
+   *      setOnInsert })`. Every kit compiles this to its native shape.
+   *      **Prefer this for portable code** (arc's infrastructure stores,
+   *      plugins targeting multiple backends).
+   *   2. `Record<string, unknown>` — kit-native raw record. mongokit
+   *      treats this as a Mongo operator document (`$set`, `$inc`,
+   *      `$unset`, ...). SQL kits treat it as flat column overwrites. Use
+   *      for kit-specific fast paths.
+   *   3. `Record<string, unknown>[]` — Mongo aggregation pipeline. Only
+   *      mongokit executes this; SQL kits throw `UnsupportedOperationError`.
+   *      Use for the rare cases where you need `$ifNull` / `$cond` /
+   *      `$toLower` to preserve invariants atomically (e.g. outbox's
+   *      `firstFailedAt`).
+   *
+   * Kits dispatch via `isUpdateSpec(update)` from `@classytic/repo-core/update`.
    */
-  findOneAndUpdate?(filter: FilterInput, update: Record<string, unknown> | Record<string, unknown>[], options?: FindOneAndUpdateOptions): Promise<TDoc | null>;
+  findOneAndUpdate?(filter: FilterInput, update: UpdateInput, options?: FindOneAndUpdateOptions): Promise<TDoc | null>;
   /**
    * Classify an error from a write as a unique-constraint violation.
    * Arc's idempotency + outbox adapters need this to distinguish
@@ -397,14 +426,38 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
   findAll?(filter?: FilterInput, options?: QueryOptions): Promise<TDoc[]>;
   getOrCreate?(filter: FilterInput, data: Partial<TDoc>, options?: WriteOptions): Promise<TDoc | null>;
   createMany?(items: Partial<TDoc>[], options?: WriteOptions): Promise<TDoc[]>;
-  updateMany?(filter: FilterInput, data: Record<string, unknown>, options?: WriteOptions): Promise<UpdateManyResult>;
-  deleteMany?(filter: FilterInput, options?: DeleteOptions): Promise<DeleteManyResult>;
   /**
-   * Heterogeneous bulk write. Kits dispatch each op against the
-   * appropriate driver primitive inside a single transaction; see each
-   * kit's docs for the exact semantics of `upsert` and operator-shaped
-   * update values (mongokit honors `$set` etc., SQL kits treat `update`
-   * as a flat column overwrite).
+   * Apply the same update to every matching document. Required — every
+   * `StandardRepo` kit must implement bulk update; arc's outbox,
+   * idempotency, and cleanup stores depend on it. `data` accepts the
+   * same three forms as {@link findOneAndUpdate}: portable `UpdateSpec`,
+   * kit-native raw record, or Mongo aggregation pipeline (mongokit-only).
+   *
+   * **Promoted from optional to required in repo-core 0.2.0** — sqlitekit
+   * and mongokit both ship this as a class primitive. Third-party kits
+   * that previously omitted it now need to implement. Kits that lack a
+   * native bulk-update primitive should fan out in a transaction.
+   */
+  updateMany(filter: FilterInput, data: UpdateInput, options?: WriteOptions): Promise<UpdateManyResult>;
+  /**
+   * Delete every document matching the filter. Required — symmetrically
+   * with `updateMany`. Pass `{ mode: 'hard' }` to bypass soft-delete
+   * interception; kits without soft-delete accept and ignore the flag.
+   *
+   * **Promoted from optional to required in repo-core 0.2.0.**
+   */
+  deleteMany(filter: FilterInput, options?: DeleteOptions): Promise<DeleteManyResult>;
+  /**
+   * Heterogeneous bulk write. Stays optional — kits dispatch each op
+   * against the appropriate driver primitive inside a single transaction;
+   * see each kit's docs for the exact semantics of `upsert` and
+   * operator-shaped update values (mongokit honors `$set` etc., SQL kits
+   * treat `update` as a flat column overwrite).
+   *
+   * Kept optional because the mongoose-shaped `BulkWriteOperation` has no
+   * clean SQL analogue beyond "loop and dispatch" — forcing every kit to
+   * implement it would push kits to ship a thin wrapper around updateMany
+   * / deleteMany that offers nothing over calling them directly.
    */
   bulkWrite?(operations: readonly BulkWriteOperation<TDoc>[]): Promise<BulkWriteResult>;
   /**
@@ -467,4 +520,4 @@ interface StandardRepo<TDoc> extends MinimalRepo<TDoc> {
   withTransaction?<T>(fn: (txRepo: StandardRepo<TDoc>) => Promise<T>, options?: Record<string, unknown>): Promise<T>;
 }
 //#endregion
-export { AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, BulkWriteOperation, BulkWriteResult, DeleteManyResult, DeleteOptions, DeleteResult, FindOneAndUpdateOptions, InferDoc, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions };
+export { AggMeasure, AggPaginationRequest, AggRequest, AggResult, AggRow, BulkWriteOperation, BulkWriteResult, DeleteManyResult, DeleteOptions, DeleteResult, FilterInput, FindOneAndUpdateOptions, InferDoc, MinimalRepo, PaginationParams, QueryOptions, RepositorySession, StandardRepo, UpdateManyResult, WriteOptions };

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 };