@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/resources/utils/shared-persistence-collection.utils.js

@@ -0,0 +1,284 @@
+import { CoreResourceType } from '../resources.shared.core.definitions.js';
+/**
+ * Resource types that deliberately project onto ANOTHER resource type's
+ * persistence collection — THE authority for "which configs address the same
+ * physical rows?".
+ *
+ * ## What this expresses
+ *
+ * A `USER_SELF*` resource is not a different record set; it is a different DOOR
+ * onto the SAME record set, with its own operations, roles and scoping. The
+ * `USERS` door is the admin surface (list every user, delete a user); the
+ * `USER_SELF` door is the self surface (read/update MY row). They intentionally
+ * share `UserSchema` and they intentionally share storage — the persistence
+ * layer builds a SEPARATE model per resource config over ONE collection.
+ *
+ * Anything not listed here stores under its own resource type.
+ *
+ * ## Why it is a single named authority
+ *
+ * This mapping had already been copied twice inside the backend (the
+ * zod→mongoose model builder, which is what actually creates and reads the
+ * collection, and the aggregation collection resolver — whose earlier
+ * divergence made every aggregation query a non-existent collection and return
+ * zero rows). It now has a third consumer of a completely different kind:
+ * {@link findSharedPersistenceCollectionRetentionIncoherences}, a boot-time
+ * coherence guard. A per-resource config factory structurally cannot see this
+ * relationship — it validates ONE config at a time — so the fact has to live
+ * where every layer can read it, and it has to live exactly once.
+ *
+ * ## The alias belongs to the RESOURCE, not to the storage adapter
+ *
+ * Every persistence path resolves through this map, and each adapter has
+ * exactly ONE composition point that does so: MongoDB's model builder and its
+ * aggregation resolver, and — on the SQL side — the single
+ * `resolveTableNameForResource` helper that the hybrid planner, the PostgreSQL
+ * repository and the boot-time table verifier all call.
+ *
+ * This was NOT always true, and the way it failed is the reason to keep it
+ * true: PostgreSQL used to derive its table name straight from
+ * `resourceIdentifier`, so `USER_SELF` planned, wrote and verified a `userself`
+ * table while `USERS` used `users`. An adapter choice must never silently
+ * change WHICH RECORDS a resource addresses — that is not a storage detail, it
+ * is the "two doors, one record set" contract itself. On the SQL side the
+ * resolved name is additionally normalised into a SQL identifier; casing is an
+ * adapter concern, the alias is not.
+ *
+ * The one thing a shared resolver still cannot see is an alias group whose
+ * members are pointed at DIFFERENT adapters — each config is individually
+ * valid, and only the pair is wrong. That is what
+ * {@link findSharedPersistenceCollectionAdapterIncoherences} fails closed on.
+ */
+export const RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES = {
+    [CoreResourceType.USER_SELF]: CoreResourceType.USERS,
+    [CoreResourceType.USER_SELF_PROFILES]: CoreResourceType.USER_PROFILES,
+    [CoreResourceType.USER_SELF_PREFERENCES]: CoreResourceType.USER_PREFERENCES,
+};
+/**
+ * The persistence collection a resource type's rows live in — its alias target
+ * when it declares one, otherwise the resource type itself.
+ *
+ * @param resourceType - the resource type whose storage location is wanted.
+ * @returns the collection name, as a plain string.
+ */
+export function resolveSharedPersistenceCollectionName(resourceType) {
+    return RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES[resourceType] ?? resourceType;
+}
+/**
+ * Registry-ASSEMBLY guardrail: every resource config that resolves to the SAME
+ * persistence collection must resolve to the SAME persistence adapter.
+ *
+ * ## Why the shared resolver cannot cover this on its own
+ *
+ * {@link resolveSharedPersistenceCollectionName} makes the alias
+ * adapter-independent: whichever database a resource lands in, it addresses the
+ * aliased NAME. That is necessary and not sufficient. A name is only an address
+ * WITHIN one database, so pointing `USERS` at PostgreSQL while `USER_SELF`
+ * inherits MongoDB yields two stores that both believe they own the same rows.
+ * Nothing downstream can detect it: each config is individually valid, each
+ * repository is correctly built, and every per-resource check passes.
+ *
+ * ## The failure it prevents
+ *
+ * The doors silently stop sharing records. The admin door lists users the self
+ * door cannot read; a self-service update writes to a row the admin door will
+ * never see; and — because retention is enforced against ROWS — an erasure
+ * performed through one door leaves the other door's copy completely
+ * untouched, which is the same compliance-grade lie that
+ * {@link findSharedPersistenceCollectionRetentionIncoherences} exists to
+ * prevent, arrived at from a different direction.
+ *
+ * The table name is not the only thing that follows from the adapter. Id FORMAT
+ * does too — the PostgreSQL repository validates ids as UUIDs while Mongo
+ * expects ObjectIds, each resolved from its OWN resource's adapter — so a split
+ * group would also reject through one door the very ids the other door mints.
+ * Anything keyed on "this resource's adapter" inherits this invariant.
+ *
+ * ## Why this is permanent, not a capability gate
+ *
+ * Unlike adapter gaps that close when the missing support is implemented, this
+ * one has no future in which it becomes valid: two databases cannot hold one
+ * set of rows. It is deliberately NOT a ban on aliased resources using
+ * PostgreSQL — an alias group that agrees on PostgreSQL resolves to one shared
+ * table, and whether that table was actually provisioned is a separate,
+ * already-enforced question (the boot-time table verifier).
+ *
+ * Resources inherit the application default when they declare nothing, so the
+ * caller supplies the resolved default rather than this function guessing it.
+ *
+ * Pure and side-effect free: it reports, the caller throws.
+ *
+ * @param resourceConfigurations - every assembled resource config, keyed by resource type.
+ * @param defaultPersistenceAdapter - the adapter a config with no declaration inherits.
+ * @returns one entry per incoherent collection; empty when the registry is coherent.
+ */
+export function findSharedPersistenceCollectionAdapterIncoherences(resourceConfigurations, defaultPersistenceAdapter) {
+    const adaptersByCollection = new Map();
+    for (const [resourceTypeKey, resourceConfig] of Object.entries(resourceConfigurations)) {
+        // Same reasoning as the retention guard: prefer the config's OWN identifier so a mis-keyed
+        // registry entry is diagnosed against the name its author actually wrote.
+        const resourceType = (resourceConfig?.resourceIdentifier ?? resourceTypeKey);
+        const collectionName = resolveSharedPersistenceCollectionName(resourceType);
+        const entry = {
+            resourceType,
+            adapter: resourceConfig?.persistenceAdapter ?? defaultPersistenceAdapter,
+        };
+        const existing = adaptersByCollection.get(collectionName);
+        if (existing) {
+            existing.push(entry);
+        }
+        else {
+            adaptersByCollection.set(collectionName, [entry]);
+        }
+    }
+    const incoherences = [];
+    for (const [collectionName, adapters] of adaptersByCollection) {
+        if (adapters.length < 2) {
+            continue;
+        }
+        if (new Set(adapters.map((entry) => entry.adapter)).size < 2) {
+            continue;
+        }
+        const declared = adapters
+            .map((entry) => `'${String(entry.resourceType)}' → ${entry.adapter}`)
+            .join(', ');
+        incoherences.push({
+            collectionName,
+            adapters,
+            message: `Resource configs [${declared}] all address the '${collectionName}' persistence collection but ` +
+                `resolve to DIFFERENT persistence adapters. These configs are separate doors onto ONE set of ` +
+                `rows, and a collection name only addresses rows within a single database, so this splits them ` +
+                `across two stores that each believe they own the records: the admin door lists rows the self ` +
+                `door cannot read, a self-service write lands where the admin door will never see it, and an ` +
+                `erasure performed through one door leaves the other door's copy fully intact. Give every ` +
+                `config listed above the same persistenceAdapter (a resource sharing a collection cannot pick ` +
+                `its database alone), or stop sharing the collection.`,
+        });
+    }
+    return incoherences;
+}
+/**
+ * Canonical comparison key for a resource's retention POSTURE.
+ *
+ * Compares the WHOLE resolved policy, not just `mode`. `ResourceRetentionPolicy` carries a single
+ * axis today, so `mode` alone would be exhaustive — but this guard exists precisely because config
+ * checks that look sufficient go quietly wrong later, and a second axis (a disposal clock, a
+ * jurisdiction) added to the policy would otherwise escape the comparison with no compile-time
+ * signal. Two configs over one collection must agree on ALL of it.
+ *
+ * Key order is normalised so authoring order cannot masquerade as a disagreement. `undefined` gets
+ * its own key rather than being skipped: "rows of this resource are hard-deleted" is a positive
+ * claim, and the in-vs-out asymmetry is what produces both failure modes documented below.
+ */
+function buildRetentionPostureKey(retentionPolicy) {
+    if (retentionPolicy === undefined || retentionPolicy === null) {
+        return 'NOT_GOVERNED';
+    }
+    const entries = Object.entries(retentionPolicy)
+        .filter(([, value]) => value !== undefined)
+        .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));
+    return entries.length === 0 ? 'NOT_GOVERNED' : JSON.stringify(entries);
+}
+/**
+ * Registry-ASSEMBLY guardrail: every resource config that resolves to the SAME
+ * persistence collection must declare the SAME retention posture.
+ *
+ * ## Why a config that passes every per-resource check can still be broken
+ *
+ * `retentionPolicy` is validated PER RESOURCE CONFIG by the config factory: it
+ * checks that resource's operations, its field treatments, its system-access
+ * grants. It cannot check what a SIBLING config declares, because a factory
+ * invocation never sees one. But retention is enforced against ROWS, and two
+ * configs can own the same rows (see
+ * {@link RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES}). So a pair that
+ * disagrees produces a config where every individual resource is valid and the
+ * COLLECTION is not.
+ *
+ * ## The two concrete failure modes
+ *
+ * **1. Fail-open erasure.** The retention hide filter (rows marked `RETAINED`
+ * are invisible) and the immutability freeze are injected per resource config,
+ * in `buildContextualFilter`. A row erased through the governed door stays
+ * fully READABLE and UPDATABLE through the ungoverned one. For the
+ * `USERS`/`USER_SELF` pair that ungoverned door exposes READ + UPDATE to
+ * `APP_USER` — i.e. the erased subject can still read and edit their own
+ * "erased" record. The row is erased only from the door that was opted in,
+ * which is a compliance-grade lie about the record.
+ *
+ * **2. Unique-index collision — a hard functional abort.** A retention-governed
+ * config scopes each unique index to NON-retained rows (a partial filter on the
+ * retention marker), precisely so scrubbed rows leave the index and cannot
+ * collide on the shared mask value. An ungoverned config over the same
+ * collection emits a PLAIN unique index on the same field. The FIRST erasure
+ * succeeds; the SECOND writes the same mask value, hits the plain index, and
+ * fails E11000 — inside the erasure transaction, so the whole erasure rolls
+ * back. The capability is silently single-use.
+ *
+ * Both modes are invisible until a real erasure runs, which is why this is a
+ * BOOT-time guard and not a test: the point is that a config which passes at
+ * boot must actually be able to perform an erasure.
+ *
+ * ## Why "one opted in, one not" is a disagreement, not a default
+ *
+ * An absent `retentionPolicy` is a positive statement — "rows of this resource
+ * are hard-deleted" — not an unset value the governed sibling can supply. Both
+ * failure modes above are produced by exactly that asymmetry, so `undefined`
+ * participates in the comparison as its own posture rather than being skipped.
+ *
+ * Pure and side-effect free: it reports, the caller throws. That keeps the
+ * shared-collection fact and its invariant in the layer both persistence and
+ * validation can import, while the registry owns the error shape.
+ *
+ * @param resourceConfigurations - every assembled resource config, keyed by resource type.
+ * @returns one entry per incoherent collection; empty when the registry is coherent.
+ */
+export function findSharedPersistenceCollectionRetentionIncoherences(resourceConfigurations) {
+    const posturesByCollection = new Map();
+    for (const [resourceTypeKey, resourceConfig] of Object.entries(resourceConfigurations)) {
+        // Prefer the config's OWN identifier over the map key: the registry keys by resource type, but a
+        // host that mis-keyed an entry would otherwise be diagnosed against a name it never authored.
+        const resourceType = (resourceConfig?.resourceIdentifier ?? resourceTypeKey);
+        const collectionName = resolveSharedPersistenceCollectionName(resourceType);
+        const posture = {
+            resourceType,
+            mode: resourceConfig?.retentionPolicy?.mode,
+            postureKey: buildRetentionPostureKey(resourceConfig?.retentionPolicy),
+        };
+        const existing = posturesByCollection.get(collectionName);
+        if (existing) {
+            existing.push(posture);
+        }
+        else {
+            posturesByCollection.set(collectionName, [posture]);
+        }
+    }
+    const incoherences = [];
+    for (const [collectionName, postures] of posturesByCollection) {
+        if (postures.length < 2) {
+            continue;
+        }
+        const distinctPostures = new Set(postures.map((posture) => posture.postureKey));
+        if (distinctPostures.size < 2) {
+            continue;
+        }
+        const declared = postures
+            .map((posture) => `'${String(posture.resourceType)}' → ${posture.mode ?? 'NOT retention-governed'}`)
+            .join(', ');
+        incoherences.push({
+            collectionName,
+            postures,
+            message: `Resource configs [${declared}] all store in the '${collectionName}' collection but declare ` +
+                `DIFFERENT retention postures. They are separate models over ONE set of rows, and retention is ` +
+                `enforced per resource config, so this ships two defects that only appear when a real erasure ` +
+                `runs: (1) FAIL-OPEN ERASURE — the retention hide filter and the immutability freeze are absent ` +
+                `on the ungoverned door, leaving an erased row readable and updatable there; (2) UNIQUE-INDEX ` +
+                `COLLISION — the governed config scopes its unique indexes to non-retained rows while the ` +
+                `ungoverned one emits plain unique indexes on the same collection, so the SECOND erased row ` +
+                `collides (E11000) and the erasure transaction rolls back. Declare the SAME retentionPolicy on ` +
+                `every config listed above (a resource sharing a collection cannot opt in or out alone), or ` +
+                `stop sharing the collection.`,
+        });
+    }
+    return incoherences;
+}
+//# sourceMappingURL=shared-persistence-collection.utils.js.map

package/dist/esm/resources/utils/shared-persistence-collection.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-persistence-collection.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/shared-persistence-collection.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { CoreResourceType } from '../resources.shared.core.definitions';\nimport type { ResourceType } from '../resources.shared.schemas';\nimport type { PersistenceAdapterType } from '../resources-config.shared.schemas';\nimport { ErasureRetentionMode } from '../../compliance/privacy/impersonalization.shared.schemas';\n\n/**\n * Resource types that deliberately project onto ANOTHER resource type's\n * persistence collection — THE authority for \"which configs address the same\n * physical rows?\".\n *\n * ## What this expresses\n *\n * A `USER_SELF*` resource is not a different record set; it is a different DOOR\n * onto the SAME record set, with its own operations, roles and scoping. The\n * `USERS` door is the admin surface (list every user, delete a user); the\n * `USER_SELF` door is the self surface (read/update MY row). They intentionally\n * share `UserSchema` and they intentionally share storage — the persistence\n * layer builds a SEPARATE model per resource config over ONE collection.\n *\n * Anything not listed here stores under its own resource type.\n *\n * ## Why it is a single named authority\n *\n * This mapping had already been copied twice inside the backend (the\n * zod→mongoose model builder, which is what actually creates and reads the\n * collection, and the aggregation collection resolver — whose earlier\n * divergence made every aggregation query a non-existent collection and return\n * zero rows). It now has a third consumer of a completely different kind:\n * {@link findSharedPersistenceCollectionRetentionIncoherences}, a boot-time\n * coherence guard. A per-resource config factory structurally cannot see this\n * relationship — it validates ONE config at a time — so the fact has to live\n * where every layer can read it, and it has to live exactly once.\n *\n * ## The alias belongs to the RESOURCE, not to the storage adapter\n *\n * Every persistence path resolves through this map, and each adapter has\n * exactly ONE composition point that does so: MongoDB's model builder and its\n * aggregation resolver, and — on the SQL side — the single\n * `resolveTableNameForResource` helper that the hybrid planner, the PostgreSQL\n * repository and the boot-time table verifier all call.\n *\n * This was NOT always true, and the way it failed is the reason to keep it\n * true: PostgreSQL used to derive its table name straight from\n * `resourceIdentifier`, so `USER_SELF` planned, wrote and verified a `userself`\n * table while `USERS` used `users`. An adapter choice must never silently\n * change WHICH RECORDS a resource addresses — that is not a storage detail, it\n * is the \"two doors, one record set\" contract itself. On the SQL side the\n * resolved name is additionally normalised into a SQL identifier; casing is an\n * adapter concern, the alias is not.\n *\n * The one thing a shared resolver still cannot see is an alias group whose\n * members are pointed at DIFFERENT adapters — each config is individually\n * valid, and only the pair is wrong. That is what\n * {@link findSharedPersistenceCollectionAdapterIncoherences} fails closed on.\n */\nexport const RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES: Readonly<Record<string, string>> = {\n  [CoreResourceType.USER_SELF]: CoreResourceType.USERS,\n  [CoreResourceType.USER_SELF_PROFILES]: CoreResourceType.USER_PROFILES,\n  [CoreResourceType.USER_SELF_PREFERENCES]: CoreResourceType.USER_PREFERENCES,\n};\n\n/**\n * The persistence collection a resource type's rows live in — its alias target\n * when it declares one, otherwise the resource type itself.\n *\n * @param resourceType - the resource type whose storage location is wanted.\n * @returns the collection name, as a plain string.\n */\nexport function resolveSharedPersistenceCollectionName(resourceType: ResourceType): string {\n  return RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES[resourceType as string] ?? (resourceType as string);\n}\n\n/** The minimal config shape {@link findSharedPersistenceCollectionAdapterIncoherences} reads. */\nexport interface SharedPersistenceCollectionAdapterCandidate {\n  readonly resourceIdentifier: ResourceType;\n  /** The config's OWN declaration; `undefined` means \"inherit the application default\". */\n  readonly persistenceAdapter?: PersistenceAdapterType | undefined;\n}\n\n/** One collection whose resource configs are pointed at different databases. */\nexport interface SharedPersistenceCollectionAdapterIncoherence {\n  /** The shared collection the disagreeing configs claim to address. */\n  readonly collectionName: string;\n  /** Every resource config addressing that collection, with the adapter it RESOLVED to. */\n  readonly adapters: readonly { resourceType: ResourceType; adapter: PersistenceAdapterType }[];\n  /** Operator-facing explanation naming the consequence and the fix. */\n  readonly message: string;\n}\n\n/**\n * Registry-ASSEMBLY guardrail: every resource config that resolves to the SAME\n * persistence collection must resolve to the SAME persistence adapter.\n *\n * ## Why the shared resolver cannot cover this on its own\n *\n * {@link resolveSharedPersistenceCollectionName} makes the alias\n * adapter-independent: whichever database a resource lands in, it addresses the\n * aliased NAME. That is necessary and not sufficient. A name is only an address\n * WITHIN one database, so pointing `USERS` at PostgreSQL while `USER_SELF`\n * inherits MongoDB yields two stores that both believe they own the same rows.\n * Nothing downstream can detect it: each config is individually valid, each\n * repository is correctly built, and every per-resource check passes.\n *\n * ## The failure it prevents\n *\n * The doors silently stop sharing records. The admin door lists users the self\n * door cannot read; a self-service update writes to a row the admin door will\n * never see; and — because retention is enforced against ROWS — an erasure\n * performed through one door leaves the other door's copy completely\n * untouched, which is the same compliance-grade lie that\n * {@link findSharedPersistenceCollectionRetentionIncoherences} exists to\n * prevent, arrived at from a different direction.\n *\n * The table name is not the only thing that follows from the adapter. Id FORMAT\n * does too — the PostgreSQL repository validates ids as UUIDs while Mongo\n * expects ObjectIds, each resolved from its OWN resource's adapter — so a split\n * group would also reject through one door the very ids the other door mints.\n * Anything keyed on \"this resource's adapter\" inherits this invariant.\n *\n * ## Why this is permanent, not a capability gate\n *\n * Unlike adapter gaps that close when the missing support is implemented, this\n * one has no future in which it becomes valid: two databases cannot hold one\n * set of rows. It is deliberately NOT a ban on aliased resources using\n * PostgreSQL — an alias group that agrees on PostgreSQL resolves to one shared\n * table, and whether that table was actually provisioned is a separate,\n * already-enforced question (the boot-time table verifier).\n *\n * Resources inherit the application default when they declare nothing, so the\n * caller supplies the resolved default rather than this function guessing it.\n *\n * Pure and side-effect free: it reports, the caller throws.\n *\n * @param resourceConfigurations - every assembled resource config, keyed by resource type.\n * @param defaultPersistenceAdapter - the adapter a config with no declaration inherits.\n * @returns one entry per incoherent collection; empty when the registry is coherent.\n */\nexport function findSharedPersistenceCollectionAdapterIncoherences(\n  resourceConfigurations: Record<string, SharedPersistenceCollectionAdapterCandidate>,\n  defaultPersistenceAdapter: PersistenceAdapterType,\n): SharedPersistenceCollectionAdapterIncoherence[] {\n  const adaptersByCollection = new Map<\n    string,\n    { resourceType: ResourceType; adapter: PersistenceAdapterType }[]\n  >();\n\n  for (const [resourceTypeKey, resourceConfig] of Object.entries(resourceConfigurations)) {\n    // Same reasoning as the retention guard: prefer the config's OWN identifier so a mis-keyed\n    // registry entry is diagnosed against the name its author actually wrote.\n    const resourceType = (resourceConfig?.resourceIdentifier ?? resourceTypeKey) as ResourceType;\n    const collectionName = resolveSharedPersistenceCollectionName(resourceType);\n    const entry = {\n      resourceType,\n      adapter: resourceConfig?.persistenceAdapter ?? defaultPersistenceAdapter,\n    };\n\n    const existing = adaptersByCollection.get(collectionName);\n    if (existing) {\n      existing.push(entry);\n    } else {\n      adaptersByCollection.set(collectionName, [entry]);\n    }\n  }\n\n  const incoherences: SharedPersistenceCollectionAdapterIncoherence[] = [];\n\n  for (const [collectionName, adapters] of adaptersByCollection) {\n    if (adapters.length < 2) {\n      continue;\n    }\n    if (new Set(adapters.map((entry) => entry.adapter)).size < 2) {\n      continue;\n    }\n\n    const declared = adapters\n      .map((entry) => `'${String(entry.resourceType)}' → ${entry.adapter}`)\n      .join(', ');\n\n    incoherences.push({\n      collectionName,\n      adapters,\n      message:\n        `Resource configs [${declared}] all address the '${collectionName}' persistence collection but ` +\n        `resolve to DIFFERENT persistence adapters. These configs are separate doors onto ONE set of ` +\n        `rows, and a collection name only addresses rows within a single database, so this splits them ` +\n        `across two stores that each believe they own the records: the admin door lists rows the self ` +\n        `door cannot read, a self-service write lands where the admin door will never see it, and an ` +\n        `erasure performed through one door leaves the other door's copy fully intact. Give every ` +\n        `config listed above the same persistenceAdapter (a resource sharing a collection cannot pick ` +\n        `its database alone), or stop sharing the collection.`,\n    });\n  }\n\n  return incoherences;\n}\n\n/** The minimal config shape {@link findSharedPersistenceCollectionRetentionIncoherences} reads. */\nexport interface SharedPersistenceCollectionRetentionCandidate {\n  readonly resourceIdentifier: ResourceType;\n  readonly retentionPolicy?: { mode?: ErasureRetentionMode } | undefined;\n}\n\n/**\n * Canonical comparison key for a resource's retention POSTURE.\n *\n * Compares the WHOLE resolved policy, not just `mode`. `ResourceRetentionPolicy` carries a single\n * axis today, so `mode` alone would be exhaustive — but this guard exists precisely because config\n * checks that look sufficient go quietly wrong later, and a second axis (a disposal clock, a\n * jurisdiction) added to the policy would otherwise escape the comparison with no compile-time\n * signal. Two configs over one collection must agree on ALL of it.\n *\n * Key order is normalised so authoring order cannot masquerade as a disagreement. `undefined` gets\n * its own key rather than being skipped: \"rows of this resource are hard-deleted\" is a positive\n * claim, and the in-vs-out asymmetry is what produces both failure modes documented below.\n */\nfunction buildRetentionPostureKey(retentionPolicy: { mode?: ErasureRetentionMode } | undefined): string {\n  if (retentionPolicy === undefined || retentionPolicy === null) {\n    return 'NOT_GOVERNED';\n  }\n  const entries = Object.entries(retentionPolicy as Record<string, unknown>)\n    .filter(([, value]) => value !== undefined)\n    .sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey));\n  return entries.length === 0 ? 'NOT_GOVERNED' : JSON.stringify(entries);\n}\n\n/** One collection whose resource configs disagree about retention governance. */\nexport interface SharedPersistenceCollectionRetentionIncoherence {\n  /** The shared collection the disagreeing configs write to. */\n  readonly collectionName: string;\n  /** Every resource config addressing that collection, with the posture it declared. */\n  readonly postures: readonly { resourceType: ResourceType; mode: ErasureRetentionMode | undefined }[];\n  /** Operator-facing explanation naming both failure modes and the fix. */\n  readonly message: string;\n}\n\n/**\n * Registry-ASSEMBLY guardrail: every resource config that resolves to the SAME\n * persistence collection must declare the SAME retention posture.\n *\n * ## Why a config that passes every per-resource check can still be broken\n *\n * `retentionPolicy` is validated PER RESOURCE CONFIG by the config factory: it\n * checks that resource's operations, its field treatments, its system-access\n * grants. It cannot check what a SIBLING config declares, because a factory\n * invocation never sees one. But retention is enforced against ROWS, and two\n * configs can own the same rows (see\n * {@link RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES}). So a pair that\n * disagrees produces a config where every individual resource is valid and the\n * COLLECTION is not.\n *\n * ## The two concrete failure modes\n *\n * **1. Fail-open erasure.** The retention hide filter (rows marked `RETAINED`\n * are invisible) and the immutability freeze are injected per resource config,\n * in `buildContextualFilter`. A row erased through the governed door stays\n * fully READABLE and UPDATABLE through the ungoverned one. For the\n * `USERS`/`USER_SELF` pair that ungoverned door exposes READ + UPDATE to\n * `APP_USER` — i.e. the erased subject can still read and edit their own\n * \"erased\" record. The row is erased only from the door that was opted in,\n * which is a compliance-grade lie about the record.\n *\n * **2. Unique-index collision — a hard functional abort.** A retention-governed\n * config scopes each unique index to NON-retained rows (a partial filter on the\n * retention marker), precisely so scrubbed rows leave the index and cannot\n * collide on the shared mask value. An ungoverned config over the same\n * collection emits a PLAIN unique index on the same field. The FIRST erasure\n * succeeds; the SECOND writes the same mask value, hits the plain index, and\n * fails E11000 — inside the erasure transaction, so the whole erasure rolls\n * back. The capability is silently single-use.\n *\n * Both modes are invisible until a real erasure runs, which is why this is a\n * BOOT-time guard and not a test: the point is that a config which passes at\n * boot must actually be able to perform an erasure.\n *\n * ## Why \"one opted in, one not\" is a disagreement, not a default\n *\n * An absent `retentionPolicy` is a positive statement — \"rows of this resource\n * are hard-deleted\" — not an unset value the governed sibling can supply. Both\n * failure modes above are produced by exactly that asymmetry, so `undefined`\n * participates in the comparison as its own posture rather than being skipped.\n *\n * Pure and side-effect free: it reports, the caller throws. That keeps the\n * shared-collection fact and its invariant in the layer both persistence and\n * validation can import, while the registry owns the error shape.\n *\n * @param resourceConfigurations - every assembled resource config, keyed by resource type.\n * @returns one entry per incoherent collection; empty when the registry is coherent.\n */\nexport function findSharedPersistenceCollectionRetentionIncoherences(\n  resourceConfigurations: Record<string, SharedPersistenceCollectionRetentionCandidate>,\n): SharedPersistenceCollectionRetentionIncoherence[] {\n  const posturesByCollection = new Map<\n    string,\n    { resourceType: ResourceType; mode: ErasureRetentionMode | undefined; postureKey: string }[]\n  >();\n\n  for (const [resourceTypeKey, resourceConfig] of Object.entries(resourceConfigurations)) {\n    // Prefer the config's OWN identifier over the map key: the registry keys by resource type, but a\n    // host that mis-keyed an entry would otherwise be diagnosed against a name it never authored.\n    const resourceType = (resourceConfig?.resourceIdentifier ?? resourceTypeKey) as ResourceType;\n    const collectionName = resolveSharedPersistenceCollectionName(resourceType);\n    const posture = {\n      resourceType,\n      mode: resourceConfig?.retentionPolicy?.mode,\n      postureKey: buildRetentionPostureKey(resourceConfig?.retentionPolicy),\n    };\n\n    const existing = posturesByCollection.get(collectionName);\n    if (existing) {\n      existing.push(posture);\n    } else {\n      posturesByCollection.set(collectionName, [posture]);\n    }\n  }\n\n  const incoherences: SharedPersistenceCollectionRetentionIncoherence[] = [];\n\n  for (const [collectionName, postures] of posturesByCollection) {\n    if (postures.length < 2) {\n      continue;\n    }\n    const distinctPostures = new Set(postures.map((posture) => posture.postureKey));\n    if (distinctPostures.size < 2) {\n      continue;\n    }\n\n    const declared = postures\n      .map((posture) => `'${String(posture.resourceType)}' → ${posture.mode ?? 'NOT retention-governed'}`)\n      .join(', ');\n\n    incoherences.push({\n      collectionName,\n      postures,\n      message:\n        `Resource configs [${declared}] all store in the '${collectionName}' collection but declare ` +\n        `DIFFERENT retention postures. They are separate models over ONE set of rows, and retention is ` +\n        `enforced per resource config, so this ships two defects that only appear when a real erasure ` +\n        `runs: (1) FAIL-OPEN ERASURE — the retention hide filter and the immutability freeze are absent ` +\n        `on the ungoverned door, leaving an erased row readable and updatable there; (2) UNIQUE-INDEX ` +\n        `COLLISION — the governed config scopes its unique indexes to non-retained rows while the ` +\n        `ungoverned one emits plain unique indexes on the same collection, so the SECOND erased row ` +\n        `collides (E11000) and the erasure transaction rolls back. Declare the SAME retentionPolicy on ` +\n        `every config listed above (a resource sharing a collection cannot opt in or out alone), or ` +\n        `stop sharing the collection.`,\n    });\n  }\n\n  return incoherences;\n}\n"]}

package/dist/esm/resources/utils/templatable-file-fields.shared.utils.d.ts

@@ -0,0 +1,25 @@
+import { type FileSchemaMetadata } from '@wildo-ai/zod-decorators';
+import { z } from 'zod';
+export interface StripTemplatableFileFieldsOptions {
+    rebuildObjectSchema?: (schema: z.ZodObject<any>, shape: Record<string, z.ZodTypeAny>) => z.ZodTypeAny;
+}
+export interface TemplatableFileFieldPath {
+    fieldName: string;
+    schema: z.ZodTypeAny;
+    isInsideArray: boolean;
+}
+export declare class IncompatibleTemplatableFileFieldPathError extends Error {
+    readonly fieldName: string;
+    readonly existingMetadata: FileSchemaMetadata | undefined;
+    readonly conflictingMetadata: FileSchemaMetadata | undefined;
+    constructor(fieldName: string, existingMetadata: FileSchemaMetadata | undefined, conflictingMetadata: FileSchemaMetadata | undefined);
+}
+export declare function collectTemplatableFileFieldPaths(schema: z.ZodTypeAny, pathPrefix?: string, isInsideArray?: boolean, activeSchemas?: WeakSet<object>): TemplatableFileFieldPath[];
+/**
+ * Remove generated PDF file fields from request DTO schemas, including nested
+ * structures and union arms. These fields are framework-owned outputs, so they
+ * must never appear in frontend/authored write DTOs even when custom DTOs are
+ * provided by an application.
+ */
+export declare function stripTemplatableFileFieldsRecursively(schema: z.ZodTypeAny, options?: StripTemplatableFileFieldsOptions, activeSchemas?: WeakSet<object>): z.ZodTypeAny;
+//# sourceMappingURL=templatable-file-fields.shared.utils.d.ts.map

package/dist/esm/resources/utils/templatable-file-fields.shared.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templatable-file-fields.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/templatable-file-fields.shared.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAiBL,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,WAAW,iCAAiC;IAChD,mBAAmB,CAAC,EAAE,CACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,KAChC,CAAC,CAAC,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,qBAAa,yCAA0C,SAAQ,KAAK;aAEhD,SAAS,EAAE,MAAM;aACjB,gBAAgB,EAAE,kBAAkB,GAAG,SAAS;aAChD,mBAAmB,EAAE,kBAAkB,GAAG,SAAS;gBAFnD,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,kBAAkB,GAAG,SAAS,EAChD,mBAAmB,EAAE,kBAAkB,GAAG,SAAS;CAOtE;AAED,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,CAAC,CAAC,UAAU,EACpB,UAAU,SAAK,EACf,aAAa,UAAQ,EACrB,aAAa,GAAE,OAAO,CAAC,MAAM,CAAyB,GACrD,wBAAwB,EAAE,CAmG5B;AAmDD;;;;;GAKG;AACH,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,CAAC,CAAC,UAAU,EACpB,OAAO,GAAE,iCAAsC,EAC/C,aAAa,GAAE,OAAO,CAAC,MAAM,CAAyB,GACrD,CAAC,CAAC,UAAU,CA4Md"}