@classytic/mongokit 3.20.0 → 3.22.0

package/dist/{mongooseToJsonSchema-D2CyAMIC.d.mts → mongooseToJsonSchema-ChFKfZts.d.mts}

@@ -1,4 +1,4 @@
-import { C as FieldPreset, gt as UserContext } from "./types-DNFMofHy.mjs";
+import { C as FieldPreset, gt as UserContext } from "./types-BnRqAJVa.mjs";
 import mongoose, { Schema } from "mongoose";
 import { CacheAdapter } from "@classytic/repo-core/cache";
 import { CrudSchemas, SchemaBuilderOptions } from "@classytic/repo-core/schema";
@@ -249,6 +249,35 @@ interface LoggerConfig {
  */
 declare function configureLogger(config: Partial<LoggerConfig> | false): void;
 //#endregion
+//#region src/utils/to-plain.d.ts
+/**
+ * Convert a hydrated Mongoose (sub)document to a plain object — the
+ * spread-safety primitive for domain verbs that rebuild embedded lines.
+ *
+ * **The footgun this closes:** spreading a hydrated subdocument
+ * (`{ ...line, consumedQuantity: x }`) spreads its Mongoose INTERNAL
+ * properties (`$__`, `_doc`, ...), not its schema fields. The rebuilt
+ * object then casts to garbage on write — required fields land
+ * `undefined`, and because `findOneAndUpdate` does not run validators
+ * by default, the corrupt lines persist silently. This has bitten every
+ * package that maps over embedded arrays (`components`, `operations`,
+ * `revisions`) to produce an updated copy.
+ *
+ * Rule of thumb: **any `{ ...subdoc }` in a repository verb goes
+ * through `toPlain` first.**
+ *
+ * ```ts
+ * const updated = lines.map((line) => ({
+ *   ...toPlain(line),
+ *   reservedQuantity: reserved.get(line.itemSku) ?? 0,
+ * }));
+ * ```
+ *
+ * Non-documents pass through unchanged, so it is safe to apply
+ * defensively over values that may or may not be hydrated.
+ */
+declare function toPlain<T>(value: T): T;
+//#endregion
 //#region src/utils/memory-cache.d.ts
 /**
  * Creates an in-memory cache adapter
@@ -295,4 +324,4 @@ declare function buildCrudSchemasFromMongooseSchema(mongooseSchema: Schema, opti
  */
 declare function buildCrudSchemasFromModel(mongooseModel: mongoose.Model<unknown>, options?: SchemaBuilderOptions): CrudSchemasFramework;
 //#endregion
-export { IdType as a, isObjectIdInstance as c, filterResponseData as d, getFieldsForUser as f, parseDuplicateKeyError as g, isDuplicateKeyError as h, configureLogger as i, isValidIdForType as l, createError as m, buildCrudSchemasFromMongooseSchema as n, getSchemaIdType as o, getMongooseProjection as p, createMemoryCache as r, idVariants as s, buildCrudSchemasFromModel as t, createFieldPreset as u };
+export { parseDuplicateKeyError as _, configureLogger as a, idVariants as c, createFieldPreset as d, filterResponseData as f, isDuplicateKeyError as g, createError as h, toPlain as i, isObjectIdInstance as l, getMongooseProjection as m, buildCrudSchemasFromMongooseSchema as n, IdType as o, getFieldsForUser as p, createMemoryCache as r, getSchemaIdType as s, buildCrudSchemasFromModel as t, isValidIdForType as u };

package/dist/{multi-tenant.plugin-CTsWz0XK.d.mts → multi-tenant.plugin-CFzMOuZP.d.mts}

@@ -1,4 +1,4 @@
-import { B as ObjectId, G as Plugin, Q as RepositoryContext } from "./types-DNFMofHy.mjs";
+import { B as ObjectId, G as Plugin, Q as RepositoryContext } from "./types-BnRqAJVa.mjs";
 import mongoose from "mongoose";
 import { CacheAdapter as CacheAdapter$1, CacheOptions, RepositoryCacheHandle, RepositoryCachePluginOptions, cachePlugin } from "@classytic/repo-core/cache";
 import { TenantConfig } from "@classytic/repo-core/tenant";

package/dist/pagination/PaginationEngine.d.mts

@@ -1,2 +1,2 @@
-import { t as PaginationEngine } from "../PaginationEngine-DYpOD2wY.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-CYRTLW6s.mjs";
 export { PaginationEngine };

package/dist/plugins/index.d.mts

@@ -1,6 +1,6 @@
-import { G as Plugin } from "../types-DNFMofHy.mjs";
-import { C as AuditTrailMethods, E as auditTrailPlugin, S as AuditQueryResult, T as AuditTrailQuery, _ as RepositoryCachePluginOptions, a as DateSequentialIdOptions, b as AuditOperation, c as SequentialIdOptions, d as getNextSequence, f as prefixedId, g as RepositoryCacheHandle, h as CacheOptions, i as CustomIdOptions, l as customIdPlugin, m as CacheAdapter, o as IdGenerator, p as sequentialId, r as multiTenantPlugin, s as PrefixedIdOptions, t as MultiTenantOptions, u as dateSequentialId, v as cachePlugin, w as AuditTrailOptions, x as AuditQueryOptions, y as AuditEntry } from "../multi-tenant.plugin-CTsWz0XK.mjs";
-import { C as LeasePluginOptions, D as elasticSearchPlugin, E as ElasticSearchOptions, M as auditLogPlugin, N as AggregateHelpersMethods, O as cascadePlugin, P as aggregateHelpersPlugin, S as LeaseMethods, T as fieldFilterPlugin, _ as observabilityPlugin, a as uniqueField, b as MethodRegistryRepository, c as TenantContext, d as SubdocumentMethods, f as subdocumentPlugin, g as OperationMetric, h as ObservabilityOptions, i as requireField, j as batchOperationsPlugin, k as BatchOperationsMethods, l as TenantStore, m as softDeletePlugin, n as blockIf, o as validationChainPlugin, p as SoftDeleteMethods, r as immutableField, s as timestampPlugin, t as autoInject, u as createTenantContext, v as MongoOperationsMethods, w as leasePlugin, x as methodRegistryPlugin, y as mongoOperationsPlugin } from "../validation-chain.plugin-buy3uvyk.mjs";
+import { G as Plugin } from "../types-BnRqAJVa.mjs";
+import { C as AuditTrailMethods, E as auditTrailPlugin, S as AuditQueryResult, T as AuditTrailQuery, _ as RepositoryCachePluginOptions, a as DateSequentialIdOptions, b as AuditOperation, c as SequentialIdOptions, d as getNextSequence, f as prefixedId, g as RepositoryCacheHandle, h as CacheOptions, i as CustomIdOptions, l as customIdPlugin, m as CacheAdapter, o as IdGenerator, p as sequentialId, r as multiTenantPlugin, s as PrefixedIdOptions, t as MultiTenantOptions, u as dateSequentialId, v as cachePlugin, w as AuditTrailOptions, x as AuditQueryOptions, y as AuditEntry } from "../multi-tenant.plugin-CFzMOuZP.mjs";
+import { A as fieldFilterPlugin, C as MongoOperationsMethods, D as LeaseMethods, E as methodRegistryPlugin, I as batchOperationsPlugin, L as auditLogPlugin, M as elasticSearchPlugin, N as cascadePlugin, O as LeasePluginOptions, P as BatchOperationsMethods, R as AggregateHelpersMethods, S as observabilityPlugin, T as MethodRegistryRepository, _ as immutableStatesPlugin, a as uniqueField, b as ObservabilityOptions, c as TenantContext, d as SubdocumentMethods, f as subdocumentPlugin, g as ImmutableStatesPluginOptions, h as ImmutableClaimView, i as requireField, j as ElasticSearchOptions, k as leasePlugin, l as TenantStore, m as softDeletePlugin, n as blockIf, o as validationChainPlugin, p as SoftDeleteMethods, r as immutableField, s as timestampPlugin, t as autoInject, u as createTenantContext, v as AppendOnlyPluginOptions, w as mongoOperationsPlugin, x as OperationMetric, y as appendOnlyPlugin, z as aggregateHelpersPlugin } from "../validation-chain.plugin-DDQeEyk5.mjs";
 import { ChangeLogStore } from "@classytic/repo-core/sync";
 //#region src/plugins/change-log.plugin.d.ts
 interface ChangeLogPluginOptions {
@@ -15,4 +15,4 @@ interface ChangeLogPluginOptions {
 }
 declare function changeLogPlugin(options: ChangeLogPluginOptions): Plugin;
 //#endregion
-export { type AggregateHelpersMethods, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type CacheAdapter, type CacheOptions, type ChangeLogPluginOptions, type CustomIdOptions, type DateSequentialIdOptions, type ElasticSearchOptions, type IdGenerator, type LeaseMethods, type LeasePluginOptions, type MethodRegistryRepository, type MongoOperationsMethods, type MultiTenantOptions, type ObservabilityOptions, type OperationMetric, type PrefixedIdOptions, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type SequentialIdOptions, type SoftDeleteMethods, type SubdocumentMethods, type TenantContext, type TenantStore, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, changeLogPlugin, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };
+export { type AggregateHelpersMethods, type AppendOnlyPluginOptions, type AuditEntry, type AuditOperation, type AuditQueryOptions, type AuditQueryResult, type AuditTrailMethods, type AuditTrailOptions, AuditTrailQuery, type BatchOperationsMethods, type CacheAdapter, type CacheOptions, type ChangeLogPluginOptions, type CustomIdOptions, type DateSequentialIdOptions, type ElasticSearchOptions, type IdGenerator, type ImmutableClaimView, type ImmutableStatesPluginOptions, type LeaseMethods, type LeasePluginOptions, type MethodRegistryRepository, type MongoOperationsMethods, type MultiTenantOptions, type ObservabilityOptions, type OperationMetric, type PrefixedIdOptions, type RepositoryCacheHandle, type RepositoryCachePluginOptions, type SequentialIdOptions, type SoftDeleteMethods, type SubdocumentMethods, type TenantContext, type TenantStore, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, changeLogPlugin, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, immutableStatesPlugin, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };

package/dist/plugins/index.mjs

@@ -1,5 +1,5 @@
-import { a as methodRegistryPlugin, c as getNextSequence, d as cachePlugin, f as batchOperationsPlugin, h as auditLogPlugin, i as multiTenantPlugin, l as prefixedId, m as auditTrailPlugin, n as softDeletePlugin, o as customIdPlugin, p as AuditTrailQuery, s as dateSequentialId, t as timestampPlugin, u as sequentialId } from "../timestamp.plugin-nG9Z1JEk.mjs";
-import { a as uniqueField, c as subdocumentPlugin, d as leasePlugin, f as fieldFilterPlugin, h as aggregateHelpersPlugin, i as requireField, l as observabilityPlugin, m as cascadePlugin, n as blockIf, o as validationChainPlugin, p as elasticSearchPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as mongoOperationsPlugin } from "../validation-chain.plugin-Dn_wZYLA.mjs";
+import { a as methodRegistryPlugin, c as getNextSequence, d as cachePlugin, f as batchOperationsPlugin, h as auditLogPlugin, i as multiTenantPlugin, l as prefixedId, m as auditTrailPlugin, n as softDeletePlugin, o as customIdPlugin, p as AuditTrailQuery, s as dateSequentialId, t as timestampPlugin, u as sequentialId } from "../timestamp.plugin-Ch0O6DPX.mjs";
+import { _ as aggregateHelpersPlugin, a as uniqueField, c as subdocumentPlugin, d as observabilityPlugin, f as mongoOperationsPlugin, g as cascadePlugin, h as elasticSearchPlugin, i as requireField, l as immutableStatesPlugin, m as fieldFilterPlugin, n as blockIf, o as validationChainPlugin, p as leasePlugin, r as immutableField, s as createTenantContext, t as autoInject, u as appendOnlyPlugin } from "../validation-chain.plugin-RxOzGuQy.mjs";
 //#region src/plugins/change-log.plugin.ts
 const PLUGIN_NAME = "changeLog";
 function isSkipped(context) {
@@ -70,4 +70,4 @@ function changeLogPlugin(options) {
 	};
 }
 //#endregion
-export { AuditTrailQuery, aggregateHelpersPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, changeLogPlugin, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };
+export { AuditTrailQuery, aggregateHelpersPlugin, appendOnlyPlugin, auditLogPlugin, auditTrailPlugin, autoInject, batchOperationsPlugin, blockIf, cachePlugin, cascadePlugin, changeLogPlugin, createTenantContext, customIdPlugin, dateSequentialId, elasticSearchPlugin, fieldFilterPlugin, getNextSequence, immutableField, immutableStatesPlugin, leasePlugin, methodRegistryPlugin, mongoOperationsPlugin, multiTenantPlugin, observabilityPlugin, prefixedId, requireField, sequentialId, softDeletePlugin, subdocumentPlugin, timestampPlugin, uniqueField, validationChainPlugin };

package/dist/testkit/index.d.mts

@@ -1,4 +1,4 @@
-import { a as Repository, n as CreateRepositoryConfig } from "../create-repository-0TkQhcv-.mjs";
+import { a as Repository, n as CreateRepositoryConfig } from "../create-repository-DXa3nMG6.mjs";
 import { Connection, Model, Schema } from "mongoose";
 import { MongoMemoryReplSet, MongoMemoryServer } from "mongodb-memory-server";
 //#region src/testkit/index.d.ts

package/dist/testkit/index.mjs

@@ -1,4 +1,4 @@
-import { t as createRepository } from "../create-repository-CJATiAKX.mjs";
+import { t as createRepository } from "../create-repository-BFVYm48p.mjs";
 import { createConnection } from "mongoose";
 //#region src/testkit/index.ts
 function idempotentStop(server) {

package/dist/{timestamp.plugin-nG9Z1JEk.mjs → timestamp.plugin-Ch0O6DPX.mjs}

@@ -1,4 +1,4 @@
-import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-dbbgOGjK.mjs";
+import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-CaDAJY98.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
 import { throwIfAborted, withRetry } from "@classytic/repo-core/repository";

package/dist/{types-DNFMofHy.d.mts → types-BnRqAJVa.d.mts}

@@ -1101,6 +1101,14 @@ interface SessionOptions {
    * ```
    */
   bypassTenant?: boolean;
+  /**
+   * Per-call escape hatch for `appendOnlyPlugin` — deliberate
+   * maintenance on an immutable-facts collection (backfill repair,
+   * migration). Audited via `after:append-only-bypass`; grep for this
+   * flag the same way you grep `bypassTenant` / `mode: 'hard'`. NOT a
+   * substitute for access control — gate it at the host layer.
+   */
+  bypassAppendOnly?: boolean;
   /** Extensible — plugins can read custom fields from options */
   [key: string]: unknown;
 }

package/dist/usage/index.d.mts

@@ -0,0 +1,23 @@
+import { Connection } from "mongoose";
+import { UsageStore } from "@classytic/repo-core/usage";
+//#region src/usage/index.d.ts
+/** Adapter-construction options. */
+interface MongoUsageStoreOptions {
+  /**
+   * Mongoose connection. Defaults to `mongoose.connection` (the
+   * default global connection). Apps using a named connection pass
+   * it explicitly.
+   */
+  connection?: Connection;
+  /** Collection name. Default `usage_counters`. */
+  collectionName?: string;
+  /** Override the Mongoose model name. Default `MongoUsageCounter`. */
+  modelName?: string;
+}
+/**
+ * Build a Mongo-backed usage store. Idempotent — the underlying model
+ * is registered once per `(connection, modelName)` pair.
+ */
+declare function createMongoUsageStore(options?: MongoUsageStoreOptions): UsageStore;
+//#endregion
+export { MongoUsageStoreOptions, createMongoUsageStore };

package/dist/usage/index.mjs

@@ -0,0 +1,67 @@
+import { n as isDuplicateKeyError } from "../error-BuByZwKU.mjs";
+import mongoose, { Schema } from "mongoose";
+//#region src/usage/index.ts
+/**
+* Build a Mongo-backed usage store. Idempotent — the underlying model
+* is registered once per `(connection, modelName)` pair.
+*/
+function createMongoUsageStore(options = {}) {
+	const { connection, collectionName = "usage_counters", modelName = "MongoUsageCounter" } = options;
+	const model = getOrCreateModel(connection ?? mongoose, modelName, collectionName);
+	return {
+		name: "mongo",
+		async increment(bucket, amount) {
+			const filter = {
+				actor: bucket.actor,
+				period: bucket.period,
+				kind: bucket.kind
+			};
+			try {
+				await model.updateOne(filter, { $inc: { count: amount } }, { upsert: true });
+			} catch (err) {
+				if (!isDuplicateKeyError(err)) throw err;
+				await model.updateOne(filter, { $inc: { count: amount } }, { upsert: true });
+			}
+		},
+		async summary(actor, period) {
+			const rows = await model.find({
+				actor,
+				period
+			}).select("kind count").lean();
+			const out = {};
+			for (const row of rows) out[row.kind] = row.count;
+			return out;
+		}
+	};
+}
+function getOrCreateModel(conn, modelName, collectionName) {
+	const existing = "models" in conn ? conn.models[modelName] : void 0;
+	if (existing) return existing;
+	const schema = new Schema({
+		actor: {
+			type: String,
+			required: true
+		},
+		period: {
+			type: String,
+			required: true
+		},
+		kind: {
+			type: String,
+			required: true
+		},
+		count: {
+			type: Number,
+			required: true,
+			default: 0
+		}
+	}, { versionKey: false });
+	schema.index({
+		actor: 1,
+		period: 1,
+		kind: 1
+	}, { unique: true });
+	return conn.model(modelName, schema, collectionName);
+}
+//#endregion
+export { createMongoUsageStore };

package/dist/utils/index.d.mts

@@ -1,2 +1,2 @@
-import { a as IdType, c as isObjectIdInstance, d as filterResponseData, f as getFieldsForUser, i as configureLogger, l as isValidIdForType, m as createError, n as buildCrudSchemasFromMongooseSchema, o as getSchemaIdType, p as getMongooseProjection, r as createMemoryCache, t as buildCrudSchemasFromModel, u as createFieldPreset } from "../mongooseToJsonSchema-D2CyAMIC.mjs";
-export { type IdType, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType };
+import { a as configureLogger, d as createFieldPreset, f as filterResponseData, h as createError, i as toPlain, l as isObjectIdInstance, m as getMongooseProjection, n as buildCrudSchemasFromMongooseSchema, o as IdType, p as getFieldsForUser, r as createMemoryCache, s as getSchemaIdType, t as buildCrudSchemasFromModel, u as isValidIdForType } from "../mongooseToJsonSchema-ChFKfZts.mjs";
+export { type IdType, buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, toPlain };

package/dist/utils/index.mjs

@@ -2,5 +2,6 @@ import { i as isValidIdForType, r as isObjectIdInstance, t as getSchemaIdType }
 import { t as configureLogger } from "../logger-K7dPmu2U.mjs";
 import { t as createError } from "../error-BuByZwKU.mjs";
 import { i as getMongooseProjection, n as filterResponseData, r as getFieldsForUser, t as createFieldPreset } from "../field-selection-FSQFLpsU.mjs";
-import { n as buildCrudSchemasFromMongooseSchema, r as createMemoryCache, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-khdzVo8x.mjs";
-export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType };
+import { n as toPlain, t as createMemoryCache } from "../memory-cache-D3wyN_2w.mjs";
+import { n as buildCrudSchemasFromMongooseSchema, t as buildCrudSchemasFromModel } from "../mongooseToJsonSchema-CVnrKFDq.mjs";
+export { buildCrudSchemasFromModel, buildCrudSchemasFromMongooseSchema, configureLogger, createError, createFieldPreset, createMemoryCache, filterResponseData, getFieldsForUser, getMongooseProjection, getSchemaIdType, isObjectIdInstance, isValidIdForType, toPlain };

package/dist/{validation-chain.plugin-buy3uvyk.d.mts → validation-chain.plugin-DDQeEyk5.d.mts}

@@ -1,4 +1,4 @@
-import { B as ObjectId, C as FieldPreset, G as Plugin, J as PopulateSpec, Q as RepositoryContext, _t as ValidationChainOptions, et as RepositoryInstance, it as SelectSpec, j as Logger, l as CascadeOptions, st as SoftDeleteOptions, ut as SortSpec, vt as ValidatorDefinition } from "./types-DNFMofHy.mjs";
+import { B as ObjectId, C as FieldPreset, G as Plugin, J as PopulateSpec, Q as RepositoryContext, _t as ValidationChainOptions, et as RepositoryInstance, it as SelectSpec, j as Logger, l as CascadeOptions, st as SoftDeleteOptions, ut as SortSpec, vt as ValidatorDefinition } from "./types-BnRqAJVa.mjs";
 import { BulkWriteResult } from "@classytic/repo-core/repository";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
@@ -517,6 +517,67 @@ interface ObservabilityOptions {
 }
 declare function observabilityPlugin(options: ObservabilityOptions): Plugin;
 //#endregion
+//#region src/plugins/append-only.plugin.d.ts
+interface AppendOnlyPluginOptions {
+  /**
+   * Mutating ops to permit besides `create` / `createMany`. Use for a
+   * domain's ONE legitimate mutation path (e.g. GDPR `deleteMany`) —
+   * every allowed op still flows through the rest of the plugin stack
+   * (tenant scope, audit) as usual.
+   */
+  allow?: readonly string[] | undefined;
+  /**
+   * Hook priority for the fence. Default `HOOK_PRIORITY.POLICY` (100).
+   * Ledger repos that want the append-only refusal to win over other
+   * policy errors (e.g. a missing-tenant throw) register BELOW policy —
+   * flow's StockEvent uses `50` so the violation always reads
+   * "append-only", never "missing organizationId".
+   */
+  priority?: number | undefined;
+}
+declare function appendOnlyPlugin(options?: AppendOnlyPluginOptions): Plugin;
+//#endregion
+//#region src/plugins/immutable-states.plugin.d.ts
+/** The slice of a `before:claim` context `allowClaim` predicates see. */
+interface ImmutableClaimView {
+  id: unknown;
+  transition: {
+    from?: unknown | readonly unknown[];
+    to?: unknown;
+    field?: string;
+    where?: Record<string, unknown>;
+  };
+  /** Operator-form patch (`{ $set: {...}, ... }`). */
+  data: Record<string, unknown> | undefined;
+}
+interface ImmutableStatesPluginOptions {
+  /** States in which the document is frozen (e.g. `['posted']`). */
+  states: readonly string[];
+  /** State field on the doc — dotted paths supported. Default `'state'`. */
+  field?: string | undefined;
+  /**
+   * Context flag the OWNING ENGINE's verbs set to pass the guard
+   * (private handshake — see module doc). Default `'_immutableInternal'`.
+   */
+  internalFlag?: string | undefined;
+  /** Tenant field used to scope state lookups (mirrors the repo's scope). */
+  tenantField?: string | undefined;
+  /**
+   * Exempt specific claim shapes that legitimately touch frozen rows
+   * (audit-trail stamps like ledger's reverse-mark). Return `true` to
+   * allow. Runs only after the claim was determined to reach a frozen
+   * state — keep the predicate a strict fingerprint.
+   */
+  allowClaim?: ((view: ImmutableClaimView) => boolean) | undefined;
+  /** Domain error to throw. Default: 403 `IMMUTABLE_STATE_VIOLATION`. */
+  errorFactory?: ((ctx: {
+    id: unknown;
+    operation: string;
+    state?: string | undefined;
+  }) => Error) | undefined;
+}
+declare function immutableStatesPlugin(options: ImmutableStatesPluginOptions): Plugin;
+//#endregion
 //#region src/plugins/soft-delete.plugin.d.ts
 /**
  * Soft delete plugin
@@ -759,4 +820,4 @@ declare function immutableField(field: string): ValidatorDefinition;
  */
 declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
 //#endregion
-export { BulkWriteResult as A, LeasePluginOptions as C, elasticSearchPlugin as D, ElasticSearchOptions as E, auditLogPlugin as M, AggregateHelpersMethods as N, cascadePlugin as O, aggregateHelpersPlugin as P, LeaseMethods as S, fieldFilterPlugin as T, observabilityPlugin as _, uniqueField as a, MethodRegistryRepository as b, TenantContext as c, SubdocumentMethods as d, subdocumentPlugin as f, OperationMetric as g, ObservabilityOptions as h, requireField as i, batchOperationsPlugin as j, BatchOperationsMethods as k, TenantStore as l, softDeletePlugin as m, blockIf as n, validationChainPlugin as o, SoftDeleteMethods as p, immutableField as r, timestampPlugin as s, autoInject as t, createTenantContext as u, MongoOperationsMethods as v, leasePlugin as w, methodRegistryPlugin as x, mongoOperationsPlugin as y };
+export { fieldFilterPlugin as A, MongoOperationsMethods as C, LeaseMethods as D, methodRegistryPlugin as E, BulkWriteResult as F, batchOperationsPlugin as I, auditLogPlugin as L, elasticSearchPlugin as M, cascadePlugin as N, LeasePluginOptions as O, BatchOperationsMethods as P, AggregateHelpersMethods as R, observabilityPlugin as S, MethodRegistryRepository as T, immutableStatesPlugin as _, uniqueField as a, ObservabilityOptions as b, TenantContext as c, SubdocumentMethods as d, subdocumentPlugin as f, ImmutableStatesPluginOptions as g, ImmutableClaimView as h, requireField as i, ElasticSearchOptions as j, leasePlugin as k, TenantStore as l, softDeletePlugin as m, blockIf as n, validationChainPlugin as o, SoftDeleteMethods as p, immutableField as r, timestampPlugin as s, autoInject as t, createTenantContext as u, AppendOnlyPluginOptions as v, mongoOperationsPlugin as w, OperationMetric as x, appendOnlyPlugin as y, aggregateHelpersPlugin as z };

package/dist/{validation-chain.plugin-Dn_wZYLA.mjs → validation-chain.plugin-RxOzGuQy.mjs}

@@ -1,9 +1,10 @@
-import { s as ALL_OPERATIONS } from "./Repository-dbbgOGjK.mjs";
+import { l as OP_REGISTRY, s as ALL_OPERATIONS } from "./Repository-CaDAJY98.mjs";
 import { _ as upsert } from "./update-1Lq9OMD2.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
 import { r as getFieldsForUser } from "./field-selection-FSQFLpsU.mjs";
 import mongoose from "mongoose";
+import { HOOK_PRIORITY } from "@classytic/repo-core/hooks";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/plugins/aggregate-helpers.plugin.ts
 /**
@@ -782,6 +783,224 @@ function observabilityPlugin(options) {
 	};
 }
 //#endregion
+//#region src/plugins/append-only.plugin.ts
+/**
+* Append-Only Plugin
+*
+* Turns a repository into an immutable-facts ledger: inserts land,
+* everything else is refused at POLICY priority. The enforcement
+* layer for event-sourced planes — flow's `StockEvent`,
+* manufacturing's `ProductionEvent`, audit sinks, outbox archives —
+* where a mutable row would silently corrupt the audit/time-travel
+* story that the whole collection exists to provide.
+*
+* Grep-proof by construction: hand-fenced `update()`/`delete()`
+* overrides only cover the verbs someone remembered to override; this
+* plugin derives coverage from `OP_REGISTRY`, so every mutating op —
+* including `claim`, `claimVersion`, `restore`, `bulkWrite`, and any
+* op added to the registry later — is refused automatically.
+*
+* Allowed by default: `create`, `createMany` (appends). `getOrCreate`
+* is registry-classified as a read and stays available — it can only
+* INSERT or return the existing row, never mutate one, which is
+* append-safe by definition (idempotency stores rely on it).
+* Refused by default: `update`, `findOneAndUpdate`, `updateMany`,
+* `delete`, `deleteMany`, `restore`, `claim`, `claimVersion`,
+* `bulkWrite` (wholesale — mixed insert/update batches are ambiguous;
+* append via `createMany` instead). Composed methods from other
+* plugins (`incrementIfBelow`, lease ops) decompose into these
+* registry ops internally, so the fence catches them too.
+*
+* TTL indexes are unaffected (server-side GC never touches the repo
+* layer) — TTL-expiring an idempotency ledger still works. Raw
+* `Model.*` driver calls bypass every plugin, this one included —
+* the org-wide "never drop to Model.deleteOne" rule is what covers
+* that hole, same as for tenant scope.
+*
+* **Escape hatches** (both audited via `after:append-only-bypass`):
+*   - Plugin-level `allow` — ops the DOMAIN legitimately needs, wired
+*     once at construction (e.g. `allow: ['deleteMany']` for a
+*     GDPR-erasure path the host gates behind admin roles).
+*   - Per-call `bypassAppendOnly: true` — deliberate one-off
+*     maintenance (backfill repair, migration), grep-auditable at the
+*     call site.
+*
+* `skipPlugins` is deliberately IGNORED — same policy as tenant scope
+* and soft delete: integrity fences don't have a convenience bypass.
+*
+* @example
+* const events = new Repository(StockEventModel, [
+*   multiTenantPlugin({ ... }),
+*   appendOnlyPlugin(),
+* ]);
+* await events.create({ ... });            // OK
+* await events.update(id, { ... });        // throws 405 APPEND_ONLY_VIOLATION
+* await events.deleteMany({ ... }, { bypassAppendOnly: true }); // audited bypass
+*/
+const ALWAYS_ALLOWED = /* @__PURE__ */ new Set(["create", "createMany"]);
+function appendOnlyPlugin(options = {}) {
+	const allowed = /* @__PURE__ */ new Set([...ALWAYS_ALLOWED, ...options.allow ?? []]);
+	return {
+		name: "appendOnly",
+		apply(repo) {
+			const modelName = repo.Model?.modelName ?? "model";
+			for (const [op, meta] of Object.entries(OP_REGISTRY)) {
+				if (!meta.mutates || allowed.has(op)) continue;
+				repo.on(`before:${op}`, (context) => {
+					if (context.bypassAppendOnly === true) {
+						repo.emit("after:append-only-bypass", {
+							operation: op,
+							context
+						});
+						return;
+					}
+					throw createError(405, `${modelName} is append-only: '${op}' is not permitted. Rows on this collection are immutable facts (event ledger). Append a compensating row instead; for deliberate maintenance pass bypassAppendOnly: true (audited via 'after:append-only-bypass').`, {
+						code: "APPEND_ONLY_VIOLATION",
+						meta: {
+							operation: op,
+							model: modelName
+						}
+					});
+				}, { priority: options.priority ?? HOOK_PRIORITY.POLICY });
+			}
+		}
+	};
+}
+//#endregion
+//#region src/plugins/immutable-states.plugin.ts
+/** Ops this plugin has an explicit strategy for (see module doc). */
+const STRATEGY_OPS = /* @__PURE__ */ new Set([
+	"create",
+	"createMany",
+	"update",
+	"delete",
+	"claimVersion",
+	"restore",
+	"findOneAndUpdate",
+	"updateMany",
+	"deleteMany",
+	"bulkWrite",
+	"claim"
+]);
+function immutableStatesPlugin(options) {
+	const field = options.field ?? "state";
+	const internalFlag = options.internalFlag ?? "_immutableInternal";
+	const frozen = new Set(options.states);
+	const throwViolation = (ctx) => {
+		if (options.errorFactory) throw options.errorFactory(ctx);
+		throw createError(403, `Document ${String(ctx.id)} is in immutable state${ctx.state !== void 0 ? ` '${ctx.state}'` : ""} — '${ctx.operation}' is not permitted. Frozen rows change only through the owning engine's transition verbs.`, {
+			code: "IMMUTABLE_STATE_VIOLATION",
+			meta: { ...ctx }
+		});
+	};
+	return {
+		name: "immutableStates",
+		apply(repo) {
+			const unhandled = Object.entries(OP_REGISTRY).filter(([op, meta]) => meta.mutates && !STRATEGY_OPS.has(op)).map(([op]) => op);
+			if (unhandled.length > 0) throw createError(500, `immutableStatesPlugin has no strategy for mutating op(s): ${unhandled.join(", ")}. Mongokit added write ops this plugin predates — extend the plugin before using it.`, {
+				code: "IMMUTABLE_STATES_UNHANDLED_OPS",
+				meta: { unhandled }
+			});
+			const Model = repo.Model;
+			const getState = (doc) => field.split(".").reduce((acc, key) => acc?.[key], doc);
+			const scoped = (base, ctx) => {
+				const q = { ...base };
+				if (options.tenantField && ctx.query && options.tenantField in ctx.query) q[options.tenantField] = ctx.query[options.tenantField];
+				return q;
+			};
+			/** Raw-Model read — never re-enters the repo hook pipeline. */
+			const readStateById = async (ctx) => {
+				if (ctx.id === void 0 || ctx.id === null) return void 0;
+				const doc = await Model.findOne(scoped({ _id: ctx.id }, ctx)).select({ [field]: 1 }).lean();
+				return doc ? getState(doc) : void 0;
+			};
+			const guardById = (op) => async (ctx) => {
+				if (ctx[internalFlag]) return;
+				const state = await readStateById(ctx);
+				if (state !== void 0 && frozen.has(state)) throwViolation({
+					id: ctx.id,
+					operation: op,
+					state
+				});
+			};
+			for (const op of [
+				"update",
+				"delete",
+				"claimVersion",
+				"restore"
+			]) repo.on(`before:${op}`, guardById(op));
+			repo.on("before:findOneAndUpdate", async (ctx) => {
+				if (ctx[internalFlag]) return;
+				const filter = ctx.query ?? {};
+				const doc = await Model.findOne(filter).select({
+					[field]: 1,
+					_id: 1
+				}).lean();
+				if (!doc) return;
+				const state = getState(doc);
+				if (state !== void 0 && frozen.has(state)) throwViolation({
+					id: doc._id,
+					operation: "findOneAndUpdate",
+					state
+				});
+			});
+			const guardMany = (op) => async (ctx) => {
+				if (ctx[internalFlag]) return;
+				const filter = ctx.query ?? {};
+				const hit = await Model.exists({ $and: [filter, { [field]: { $in: [...frozen] } }] });
+				if (hit) throwViolation({
+					id: hit._id,
+					operation: op,
+					state: void 0
+				});
+			};
+			repo.on("before:updateMany", guardMany("updateMany"));
+			repo.on("before:deleteMany", guardMany("deleteMany"));
+			repo.on("before:bulkWrite", (ctx) => {
+				if (ctx[internalFlag]) return;
+				throwViolation({
+					id: void 0,
+					operation: "bulkWrite",
+					state: void 0
+				});
+			});
+			repo.on("before:claim", async (rawCtx) => {
+				const ctx = rawCtx;
+				if (ctx[internalFlag]) return;
+				const t = ctx.transition;
+				if (!t) return;
+				if ((t.field ?? "status") === field) {
+					const fromSpec = t.from;
+					if (!(Array.isArray(fromSpec) ? fromSpec.some((f) => frozen.has(String(f))) : frozen.has(String(fromSpec)))) return;
+					if (options.allowClaim?.({
+						id: ctx.id,
+						transition: t,
+						data: ctx.data
+					})) return;
+					throwViolation({
+						id: ctx.id,
+						operation: "claim",
+						state: void 0
+					});
+				}
+				const state = await readStateById(ctx);
+				if (state !== void 0 && frozen.has(state)) {
+					if (options.allowClaim?.({
+						id: ctx.id,
+						transition: t,
+						data: ctx.data
+					})) return;
+					throwViolation({
+						id: ctx.id,
+						operation: "claim",
+						state
+					});
+				}
+			});
+		}
+	};
+}
+//#endregion
 //#region src/plugins/subdocument.plugin.ts
 /**
 * Subdocument plugin for managing nested arrays
@@ -1053,4 +1272,4 @@ function uniqueField(field, errorMessage) {
 	};
 }
 //#endregion
-export { uniqueField as a, subdocumentPlugin as c, leasePlugin as d, fieldFilterPlugin as f, aggregateHelpersPlugin as h, requireField as i, observabilityPlugin as l, cascadePlugin as m, blockIf as n, validationChainPlugin as o, elasticSearchPlugin as p, immutableField as r, createTenantContext as s, autoInject as t, mongoOperationsPlugin as u };
+export { aggregateHelpersPlugin as _, uniqueField as a, subdocumentPlugin as c, observabilityPlugin as d, mongoOperationsPlugin as f, cascadePlugin as g, elasticSearchPlugin as h, requireField as i, immutableStatesPlugin as l, fieldFilterPlugin as m, blockIf as n, validationChainPlugin as o, leasePlugin as p, immutableField as r, createTenantContext as s, autoInject as t, appendOnlyPlugin as u };