@wildo-ai/saas-models 1.0.1 → 1.1.1

package/dist/esm/resources/resources.shared.utils.js

@@ -5,11 +5,13 @@
  * consumers. This includes ID helpers plus runtime relationship activation
  * evaluation.
  */
-import { ChildOperationsConfigSchema, ChildLifecycleMode, } from './child-operations.shared.schemas.js';
+import { ChildOperationsConfigSchema, ChildLifecycleMode, ChildLifecycleStrategy, } from './child-operations.shared.schemas.js';
+import { HTTP_API_RESOURCE_ID_CHARSET } from '../http-api-binding/http-api-binding-id.shared.utils.js';
 import { ResourcesConfigNamingUtils } from './utils/resources-config-naming.utils.js';
 import { CoreResourceOperation } from './resources.shared.core.definitions.js';
-import { RelationshipDtoModel, RelationshipLifecycleModel, RelationshipHandlingContractSchema, RelationshipHandlingReadSettingsSchema, RelationshipMutationModel, RelationshipNature, ResourceRelationshipBulkAction, ResourceRelationshipBulkOperationIdentifierPrefix, RelationshipReadModel, ResourceIdFormat, isOneToOneCardinality, } from './resources.shared.schemas.js';
+import { RelationshipDtoModel, RelationshipLifecycleModel, RelationshipHandlingContractSchema, RelationshipHandlingReadSettingsSchema, RelationshipPersistenceContractSchema, RelationshipMutationModel, RelationshipNature, ResourceRelationshipBulkAction, ResourceRelationshipBulkOperationIdentifierPrefix, RelationshipReadModel, ResourceParentResourceRequirement, ResourceIdFormat, isOneToOneCardinality, isArrayCardinality, PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE, } from './resources.shared.schemas.js';
 import { ErrorType } from '../errors/errors.shared.schemas.js';
+import { getDiscriminatedPolymorphicForeignKey, getZodObjectShape, isForeignKeyField } from '@wildo-ai/zod-decorators';
 /**
  * Database-agnostic Resource ID utilities
  *
@@ -17,6 +19,13 @@ import { ErrorType } from '../errors/errors.shared.schemas.js';
  * Used across the entire stack for ID validation and format detection.
  */
 export class Resources_SharedUtils {
+    static GENERATED_FILE_REGENERATE_OPERATION_PREFIX = 'pdfTemplates:regenerate:';
+    /**
+     * Namespace for the derived export companion of a LIST/SEARCH operation. Prefixed, like its
+     * sibling above, so a derived identifier can never collide with an authored custom operation and a
+     * reader can tell at a glance that nobody wrote it by hand.
+     */
+    static GENERATED_COLLECTION_EXPORT_OPERATION_PREFIX = 'collectionExport:';
     static createConfigurationError(message) {
         const error = new Error(message);
         error.type = ErrorType.CONFIGURATION;
@@ -37,6 +46,7 @@ export class Resources_SharedUtils {
             Object.values(RelationshipNature).includes(candidate.nature) &&
             candidate.natureCalculationMode === 'explicit' &&
             RelationshipHandlingContractSchema.safeParse(candidate.handling).success &&
+            RelationshipPersistenceContractSchema.safeParse(candidate.persistence).success &&
             (candidate.childOperations === undefined ||
                 ChildOperationsConfigSchema.safeParse(candidate.childOperations).success));
     }
@@ -150,10 +160,47 @@ export class Resources_SharedUtils {
                 return Resources_SharedUtils.isObjectId(id);
             case ResourceIdFormat.UUID:
                 return Resources_SharedUtils.isUUID(id);
+            case ResourceIdFormat.HTTP_API_SYNTHESIZED:
+                return Resources_SharedUtils.isHttpApiSynthesizedId(id);
+            case ResourceIdFormat.INTROSPECTION_SYNTHESIZED:
+                return Resources_SharedUtils.isIntrospectionSynthesizedId(id);
             default:
                 return false;
         }
     }
+    /**
+     * Lexical shape of an `HTTP_API`-backed resource's synthesized id — the codec charset law.
+     *
+     * Deliberately NOT consulted by {@link detectIdFormat} / {@link isValidResourceId}: every
+     * ObjectId and UUID also matches this charset, so lexical detection cannot distinguish the
+     * formats, and widening the generic validators would silently relax id validation for every
+     * PLATFORM-backed resource. This predicate participates only where the resource is already
+     * known to be HTTP_API-backed (`ResourceIdBackendService.getFormatForResource` resolves that
+     * from the registry). Canonicality (one row, one id) is enforced by the codec's decode, not
+     * here — this is shape admission, not decode.
+     */
+    static isHttpApiSynthesizedId(id) {
+        if (typeof id !== 'string')
+            return false;
+        return HTTP_API_RESOURCE_ID_CHARSET.test(id);
+    }
+    /**
+     * Lexical shape of an `INTROSPECTION`-backed resource's id.
+     *
+     * The SAME charset law as its HTTP-API sibling — URL-unreserved characters — reused rather than
+     * restated so the two cannot drift into disagreeing about what a URL-safe key is. The predicates
+     * stay separate because the FORMATS are separate: a caller asks "is this a valid id for THIS
+     * resource", and answering through the sibling's name would make the next reader think an
+     * introspected row had been through the HTTP-API codec.
+     *
+     * Carries the same exclusion: not consulted by {@link isValidResourceId}, so no platform-backed
+     * row is loosened by its existence.
+     */
+    static isIntrospectionSynthesizedId(id) {
+        if (typeof id !== 'string')
+            return false;
+        return HTTP_API_RESOURCE_ID_CHARSET.test(id);
+    }
     /**
      * Asserts that a value is a valid resource ID, throwing an error if not
      * @param id - Value to validate
@@ -179,13 +226,45 @@ export class Resources_SharedUtils {
      * Resolve the relationship identifier field used to expose nested/context
      * object names to framework consumers.
      *
-     * Priority:
-     * 1. explicit `foreignKeyField`
-     * 2. related resource default field identifier from `allResourceFieldIdentifiers`
-     * 3. fallback to naming convention from the related resource type
+     * Naming follows the FK-anchor / FK-target distinction:
+     *
+     *   - `foreignKeyField` lives on `resourceType2` (the FK-anchor side) and
+     *     semantically identifies `resourceType1` (the FK-target side).
+     *     `'assignedToUserId'` on a `tasks` row identifies the assigned-to user;
+     *     `'userId'` on an `organizationMembers` row identifies the user it
+     *     belongs to.
+     *
+     *   - When the caller is naming the **FK-target side** (i.e.
+     *     `relatedResourceType === resourceType1`), the FK is the semantic name
+     *     carrier — e.g. `'assignedToUser'` falls out of `'assignedToUserId'`.
+     *     Using the FK preserves multi-edge differentiation when several FKs
+     *     point to the same parent type (createdBy / assignedTo / reviewer all
+     *     resolve to distinct field names).
+     *
+     *   - When the caller is naming the **FK-anchor side** (i.e.
+     *     `relatedResourceType === resourceType2`), the FK is *not* a name for
+     *     this side — it names the OTHER side. Using it produces a wrong
+     *     parent-flavoured name on the child field (e.g. `userId` would yield
+     *     `'users'` instead of `'organizationMembers'`). The correct name is
+     *     derived from the related resource type itself.
+     *
+     *   - Self-references (`resourceType1 === resourceType2`) always use the FK
+     *     for semantic differentiation (`parentDocumentId` → `'parentDocument'`
+     *     vs `childDocumentId` → `'childDocument'`).
+     *
+     * Population (`fetchChildResourcesWithPolicy` /
+     * `populateForContext`) keys child collections directly off
+     * `resourceType2` with optional singularization for 1:1 — which is
+     * structurally equivalent to the FK-anchor-side branch below. Keeping the
+     * two sites aligned is what unblocks context-mode response fields like
+     * `organizationMembers`, `userSelfProfile`, `userSelfPreference` from being
+     * silently Zod-stripped on the way out the controller.
      */
     static resolveRelationshipObjectIdentity(relationship, relatedResourceType, cardinality, allResourceFieldIdentifiers) {
-        const relationshipIdentifierField = relationship.foreignKeyField
+        const isSelfReference = relationship.resourceType1 === relationship.resourceType2;
+        const isNamingFkTargetSide = relatedResourceType === relationship.resourceType1;
+        const useForeignKeyForNaming = isSelfReference || isNamingFkTargetSide;
+        const relationshipIdentifierField = (useForeignKeyForNaming && relationship.foreignKeyField)
             || allResourceFieldIdentifiers[relatedResourceType]
             || ResourcesConfigNamingUtils.toResourceFieldIdentifier(relatedResourceType);
         return {
@@ -194,7 +273,7 @@ export class Resources_SharedUtils {
             objectFieldName: isOneToOneCardinality(cardinality)
                 ? ResourcesConfigNamingUtils.extractBaseName(relationshipIdentifierField)
                 : ResourcesConfigNamingUtils.toResourceName(relationshipIdentifierField),
-            isExplicit: Boolean(relationship.foreignKeyField),
+            isExplicit: useForeignKeyForNaming && Boolean(relationship.foreignKeyField),
         };
     }
     /**
@@ -227,6 +306,359 @@ export class Resources_SharedUtils {
         }
         return undefined;
     }
+    /**
+     * Resolve which resource a foreign-key relationship REFERENCES (the target),
+     * vs which resource HOLDS the FK column (the holder).
+     *
+     * The registry's `fieldIdentifierToResourceType` must map a foreign-key field
+     * to the resource it **references** (`assignedToUserId → users`,
+     * `createdByUserId → users`) so reference pickers, FK display links, and
+     * `resolveResourceTypeForForeignKey` all resolve the referenced resource — NOT
+     * the resource that stores the column.
+     *
+     * `resourceType1` / `resourceType2` order is author-declaration dependent and
+     * is therefore NOT a reliable target signal: a child-first declaration like
+     * `createResourcesRelationship(TODOS, USERS, MANY, ONE, { foreignKeyField:
+     * 'assignedToUserId' })` stores `rt1 = todos` (the HOLDER), `rt2 = users` (the
+     * target). Mapping the FK to `resourceType1` (the historical behavior) yields
+     * `assignedToUserId → todos`, which sends a user-reference picker to search
+     * todos and links FK values to the wrong resource.
+     *
+     * Ground truth = **schema membership**: the FK column is declared on exactly
+     * one of the two resources (the holder); the other side is the referenced
+     * target. The loop that builds the map only processes explicit
+     * `foreignKeyField`s, which are always real columns on their holder's schema,
+     * so membership resolves every real case (N:1, 1:N, 1:1) regardless of
+     * declaration order. `allResourceFieldIdentifiers` standard-id equality is a
+     * belt-and-suspenders fallback for callers that cannot introspect schemas.
+     *
+     * @param relationship the FK relationship (must carry `foreignKeyField`)
+     * @param context.allResourceFieldIdentifiers resourceType → its standard id field
+     * @param context.schemaDeclaresField `(resourceType, field) => true` iff the
+     *        resource's OWN main schema declares `field` as a column (it HOLDS the FK)
+     */
+    static resolveForeignKeyReferencedResourceType(relationship, context) {
+        const rt1 = relationship.resourceType1;
+        const rt2 = relationship.resourceType2;
+        const fk = relationship.foreignKeyField;
+        if (fk) {
+            const rt1Holds = context.schemaDeclaresField(rt1, fk);
+            const rt2Holds = context.schemaDeclaresField(rt2, fk);
+            if (rt1Holds && !rt2Holds)
+                return { holderResourceType: rt1, referencedResourceType: rt2 };
+            if (rt2Holds && !rt1Holds)
+                return { holderResourceType: rt2, referencedResourceType: rt1 };
+            // Fallback — the FK equals a side's standard id (a standard FK pointing at it).
+            if (context.allResourceFieldIdentifiers[rt2] === fk)
+                return { holderResourceType: rt1, referencedResourceType: rt2 };
+            if (context.allResourceFieldIdentifiers[rt1] === fk)
+                return { holderResourceType: rt2, referencedResourceType: rt1 };
+        }
+        // Last resort (no fk / genuinely ambiguous): preserve the legacy rt1 target.
+        return { holderResourceType: rt2, referencedResourceType: rt1 };
+    }
+    /**
+     * Build the registry's `fieldIdentifierToResourceType` reverse map — THE ONE
+     * implementation.
+     *
+     * This logic existed as two hand-kept copies (the backend registry service
+     * and the frontend resources repository) plus was about to grow a third for
+     * the app-creation FK-resolution verification check — exactly the
+     * security-predicate-drift shape `two-buildcontextualfilter-implementations`
+     * records. Every consumer now routes through here; a semantic change to FK
+     * resolution lands once.
+     *
+     * Semantics (unchanged from the two copies it replaces):
+     * 1. Seed from standard field identifiers (`userId → USERS`), tracking
+     *    identifiers SHARED by several resource types (USERS / USER_SELF).
+     * 2. Enrich with every relationship's explicit `foreignKeyField`, mapped to
+     *    the resource it REFERENCES (resolved structurally via schema
+     *    membership — declaration-order independent, see
+     *    {@link resolveForeignKeyReferencedResourceType}). Shared-identifier
+     *    convergence and per-record discriminated polymorphic FKs are tolerated;
+     *    a genuine same-name-different-target clash is reported through
+     *    `onForeignKeyCollision` (log, never throw — an authoring slip must not
+     *    crash registry boot) and the FIRST mapping is kept.
+     * 3. Canonical-priority pass for shared identifiers
+     *    (`coreResourceShared_FieldIdentifierPriority`), so the winner is policy,
+     *    not iteration order.
+     */
+    static buildFieldIdentifierToResourceTypeMap(input) {
+        const fieldIdentifierToResourceType = {};
+        const sharedFieldIdentifiers = new Map();
+        for (const [resourceType, fieldIdentifier] of Object.entries(input.allResourceFieldIdentifiers)) {
+            const existing = fieldIdentifierToResourceType[fieldIdentifier];
+            if (existing && existing !== resourceType) {
+                if (!sharedFieldIdentifiers.has(fieldIdentifier)) {
+                    sharedFieldIdentifiers.set(fieldIdentifier, new Set([existing]));
+                }
+                sharedFieldIdentifiers.get(fieldIdentifier).add(resourceType);
+            }
+            fieldIdentifierToResourceType[fieldIdentifier] = resourceType;
+        }
+        const schemaDeclaresField = (resourceType, fieldName) => {
+            const schema = input.getMainSchema(resourceType);
+            if (!schema)
+                return false;
+            return Object.prototype.hasOwnProperty.call(getZodObjectShape(schema) ?? {}, fieldName);
+        };
+        for (const rel of input.allResourceRelationships) {
+            if (!rel.foreignKeyField)
+                continue;
+            const { referencedResourceType, holderResourceType } = Resources_SharedUtils.resolveForeignKeyReferencedResourceType(rel, { allResourceFieldIdentifiers: input.allResourceFieldIdentifiers, schemaDeclaresField });
+            const existingType = fieldIdentifierToResourceType[rel.foreignKeyField];
+            if (existingType && existingType !== referencedResourceType) {
+                const sharedTypes = sharedFieldIdentifiers.get(rel.foreignKeyField);
+                if (sharedTypes && (sharedTypes.has(referencedResourceType) || sharedTypes.has(existingType))) {
+                    continue;
+                }
+                const holderSchema = input.getMainSchema(holderResourceType);
+                const holderFkSchema = holderSchema ? (getZodObjectShape(holderSchema) ?? {})[rel.foreignKeyField] : undefined;
+                if (holderFkSchema && getDiscriminatedPolymorphicForeignKey(holderFkSchema)) {
+                    continue;
+                }
+                input.onForeignKeyCollision?.({ foreignKeyField: rel.foreignKeyField, existingType, referencedResourceType });
+                continue;
+            }
+            fieldIdentifierToResourceType[rel.foreignKeyField] = referencedResourceType;
+        }
+        for (const [fieldId, canonicalType] of Object.entries(input.fieldIdentifierPriority)) {
+            if (sharedFieldIdentifiers.has(fieldId)) {
+                fieldIdentifierToResourceType[fieldId] = canonicalType;
+            }
+        }
+        return fieldIdentifierToResourceType;
+    }
+    /**
+     * The FK-resolution SWEEP: every schema field carrying `.isForeignKey()` that
+     * the map above cannot resolve to a resource type.
+     *
+     * This is the exact eager check the frontend registry runs at
+     * initialization (where an unresolved field is `frontend_fk_resolution_failed`
+     * and, in development, refuses the whole app). Exposed here so the
+     * app-creation verification lane can run the SAME sweep headless — after a
+     * compose or a coding mutation — instead of the defect surfacing in the
+     * builder's browser (wonder-crm, 2026-08-27: three composed resources carried
+     * a decorated `createdByUserId` with no relationship edge; typecheck and the
+     * backend boot were both green).
+     */
+    static collectUnresolvableForeignKeyFields(input) {
+        const unresolved = [];
+        for (const [resourceType, schema] of Object.entries(input.mainSchemasByResourceType)) {
+            if (!schema)
+                continue;
+            const shape = getZodObjectShape(schema);
+            if (!shape)
+                continue;
+            for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+                if (!isForeignKeyField(fieldSchema))
+                    continue;
+                if (!input.fieldIdentifierToResourceType[fieldName]) {
+                    unresolved.push({ resourceType, fieldName });
+                }
+            }
+        }
+        return unresolved;
+    }
+    /**
+     * Resolve which side of a foreign-key relationship HOLDS the FK column, from
+     * cardinality topology alone — no registry / schema access required.
+     *
+     * The FK column physically lives on the collection side of a 1:N / N:1
+     * relationship: each of the "many" rows carries one reference to its "one"
+     * counterpart. Declaration order is an authoring convenience — parent-first
+     * `(ORGANIZATIONS, TODOS, ONE, MANY)` and child-first
+     * `(TODOS, USERS, MANY, ONE, { foreignKeyField: 'assignedToUserId' })` are
+     * both valid — so positional `resourceType2` reads are NOT a holder signal
+     * (see {@link resolveForeignKeyReferencedResourceType}, the schema-membership
+     * variant of the same invariant used where registry schemas are available).
+     *
+     * Resolution rules:
+     * - self-reference (`resourceType1 === resourceType2`) → the resource holds
+     *   its own FK (tree parent ids, self-referencing junction arrays);
+     * - exactly one collection side (`MANY` / `ONE_OR_MANY`) → that side holds;
+     * - 1:1 (no collection side) → `resourceType2`, per the parent-first child
+     *   convention (`resourceType1` = parent, `resourceType2` = child carrying
+     *   the unique FK — e.g. context-addressed composition singletons);
+     * - both sides collections (M:N) only carries a `foreignKeyField`
+     *   self-referentially (guarded at declaration time), which the
+     *   self-reference rule already covers; the defensive fallback stays
+     *   `resourceType2`.
+     */
+    static resolveForeignKeyHolderResourceType(relationship) {
+        if (relationship.resourceType1 === relationship.resourceType2) {
+            return relationship.resourceType1;
+        }
+        const side1IsCollection = isArrayCardinality(relationship.cardinality1);
+        const side2IsCollection = isArrayCardinality(relationship.cardinality2);
+        if (side1IsCollection && !side2IsCollection) {
+            return relationship.resourceType1;
+        }
+        if (side2IsCollection && !side1IsCollection) {
+            return relationship.resourceType2;
+        }
+        return relationship.resourceType2;
+    }
+    /**
+     * Collect the candidate referenced resource types for a SHARED foreign-key
+     * field on a given holder — every resource the holder's `foreignKeyField` can
+     * point at, gathered from the registered relationships.
+     *
+     * Used to enumerate the branches of a per-record discriminated polymorphic FK
+     * (e.g. referrals' `referrerBillingAccountId` → [`userBillingAccounts`,
+     * `organizationBillingAccounts`]). The holder DECLARES the FK column, so the
+     * referenced side of each matching relationship is the side that is NOT the
+     * holder.
+     */
+    static getForeignKeyCandidateReferencedTypes(foreignKeyField, holderResourceType, relationships) {
+        const referenced = [];
+        for (const rel of relationships) {
+            if (rel.foreignKeyField !== foreignKeyField)
+                continue;
+            if (rel.resourceType1 === holderResourceType)
+                referenced.push(rel.resourceType2);
+            else if (rel.resourceType2 === holderResourceType)
+                referenced.push(rel.resourceType1);
+        }
+        return referenced;
+    }
+    /**
+     * Resolve the concrete branch a per-record DISCRIMINATED polymorphic FK points
+     * at, for a specific holder record.
+     *
+     * A flat resource (e.g. `referrals`) may hold ONE shared FK column
+     * (`referrerBillingAccountId`) that targets a polymorphic branch GROUP
+     * (`billingAccounts` → `userBillingAccounts` | `organizationBillingAccounts`).
+     * Which branch a given record points at is decided by a sibling discriminator
+     * field on the SAME record (`referrerScopeType`).
+     *
+     * Resolution rides the scope axis the polymorphic system is already built on
+     * — there is NO bespoke value→target map:
+     *  1. Read the discriminator value off the record.
+     *  2. Find the {@link PolymorphicFkVariant} whose `discriminatorValue` matches —
+     *     this yields the variant's scope-root `parentResourceType` (e.g.
+     *     `'organizations'`).
+     *  3. Return the candidate branch whose `resourcePrimaryScope`, mapped back to
+     *     its scope root via `PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE`, equals that
+     *     `parentResourceType`.
+     *
+     * Returns `undefined` (caller degrades to the registry's non-authoritative
+     * representative) when the discriminator value is absent/unknown or no
+     * candidate branch matches the variant's scope.
+     *
+     * @param context.record the holder record (must carry the discriminator field)
+     * @param context.discriminatorField sibling field naming the branch selector
+     * @param context.variants the FK's polymorphic variants (each with `discriminatorValue`)
+     * @param context.candidateReferencedTypes branches from
+     *        {@link getForeignKeyCandidateReferencedTypes}
+     * @param context.getResourcePrimaryScope `(rt) => its primary scope` (registry lookup)
+     */
+    static resolveDiscriminatedPolymorphicForeignKeyTarget(context) {
+        const rawValue = context.record[context.discriminatorField];
+        if (rawValue === undefined || rawValue === null)
+            return undefined;
+        const discriminatorValue = String(rawValue);
+        const variant = context.variants.find(v => v.discriminatorValue === discriminatorValue);
+        if (!variant)
+            return undefined;
+        return context.candidateReferencedTypes.find(referencedType => {
+            const scope = context.getResourcePrimaryScope(referencedType);
+            if (scope === undefined)
+                return false;
+            return PRIMARY_SCOPE_TO_CORE_RESOURCE_TYPE[scope] === variant.parentResourceType;
+        });
+    }
+    /**
+     * Stable key for {@link ManyToManyScopeJunctionMap}: a `(target, scope)` pair.
+     * Uses a `|` separator, which cannot appear in resource-type identifiers, so
+     * `(a, b|c)` and `(a|b, c)` can never collide.
+     */
+    static manyToManyScopeJunctionKey(targetResourceType, scopeResourceType) {
+        return `${targetResourceType}|${scopeResourceType}`;
+    }
+    /**
+     * Derive the {@link ManyToManyScopeJunctionMap} from the registered
+     * relationships — the registry signal that powers inference-based scope-required
+     * reference search (see `.claude/plans/fk-filter-reference-search.md`).
+     *
+     * For every MANY-to-MANY relationship (one carrying a `jointResourceType` whose
+     * two sides are the PEERS, not the junction itself), both orderings are
+     * recorded: either peer may be the search TARGET with the other as the SCOPE.
+     * The junction's per-peer FK columns are resolved by convention as each peer's
+     * `resourceFieldIdentifier` (e.g. `organizationMembers` carries `userId` /
+     * `organizationId`).
+     *
+     * Robust to being called on raw OR post-expansion relationships: synthetic
+     * `peer → junction` edges (which also carry `jointResourceType`) are excluded
+     * because one of their sides IS the junction.
+     *
+     * Q4 (fail-closed): if two DISTINCT junctions relate the same `(target, scope)`
+     * pair, throws a configuration error — a scope-required search cannot
+     * deterministically choose a junction. No such case exists in core today
+     * (`organizations ↔ users via organizationMembers` is the only M:N).
+     *
+     * @param relationships the registered relationships (compiled or raw)
+     * @param allResourceFieldIdentifiers `resourceType → its standard id field`
+     */
+    static buildManyToManyScopeJunctionMap(relationships, allResourceFieldIdentifiers) {
+        const map = new Map();
+        const record = (target, scope, junction, targetFk, scopeFk) => {
+            const key = this.manyToManyScopeJunctionKey(target, scope);
+            const existing = map.get(key);
+            if (existing && existing.junctionResourceType !== junction) {
+                throw this.createConfigurationError(`Ambiguous M:N scope junction for target '${target}' scoped by '${scope}': both ` +
+                    `'${existing.junctionResourceType}' and '${junction}' join them. A scope-required ` +
+                    `reference search cannot deterministically choose a junction — declare a single M:N ` +
+                    `between these resources.`);
+            }
+            map.set(key, { junctionResourceType: junction, targetFkField: targetFk, scopeFkField: scopeFk });
+        };
+        for (const rel of relationships) {
+            const junction = rel.jointResourceType;
+            if (!junction)
+                continue; // only M:N relationships carry a junction
+            const peerA = rel.resourceType1;
+            const peerB = rel.resourceType2;
+            if (peerA === junction || peerB === junction)
+                continue; // skip synthetic peer→junction edges
+            if (peerA === peerB)
+                continue; // self-ref M:N is modeled explicitly, not here
+            const peerAFk = allResourceFieldIdentifiers[peerA];
+            const peerBFk = allResourceFieldIdentifiers[peerB];
+            if (!peerAFk || !peerBFk)
+                continue; // junction FK columns unresolvable → skip defensively
+            record(peerA, peerB, junction, peerAFk, peerBFk);
+            record(peerB, peerA, junction, peerBFk, peerAFk);
+        }
+        return map;
+    }
+    /**
+     * Resolve the M:N scope junction to use for a **scope-required reference
+     * search** of `targetResourceType`, given the scope parameters available in
+     * the current context (e.g. a people-picker on a task filter has the caller's
+     * `organizationId` injected by the app scope).
+     *
+     * Returns the junction for the first `(target, scope)` entry whose
+     * `scopeFkField` is present in `availableContextFields` — i.e. "search this
+     * target scoped through the junction to the scope the caller is already in".
+     * Returns `undefined` when the target has no M:N junction reachable from the
+     * available context, meaning the picker should do a plain unscoped target
+     * search. This is the registry-inference that drives scope-required reference
+     * search on the frontend (see `.claude/plans/fk-filter-reference-search.md`) —
+     * no per-field declaration needed.
+     */
+    static findScopeJunctionForTargetInContext(manyToManyScopeJunctions, targetResourceType, availableContextFields) {
+        for (const [key, junction] of manyToManyScopeJunctions) {
+            const separatorIndex = key.indexOf('|');
+            const entryTarget = separatorIndex === -1 ? key : key.slice(0, separatorIndex);
+            if (entryTarget !== targetResourceType)
+                continue;
+            if (availableContextFields.has(junction.scopeFkField)) {
+                return junction;
+            }
+        }
+        return undefined;
+    }
     /**
      * Build the generated custom-operation identifier used to expose explicit bulk
      * relationship actions at the resource-operation layer.
@@ -277,6 +709,36 @@ export class Resources_SharedUtils {
         }
         return undefined;
     }
+    static buildGeneratedFileRegenerateOperationIdentifier(fieldName) {
+        if (!fieldName.trim()) {
+            throw Resources_SharedUtils.createConfigurationError('Generated file regenerate operation requires a non-empty fieldName');
+        }
+        return `${Resources_SharedUtils.GENERATED_FILE_REGENERATE_OPERATION_PREFIX}${fieldName}`;
+    }
+    static parseGeneratedFileRegenerateOperationIdentifier(operationIdentifier) {
+        if (!operationIdentifier.startsWith(Resources_SharedUtils.GENERATED_FILE_REGENERATE_OPERATION_PREFIX)) {
+            return undefined;
+        }
+        const fieldName = operationIdentifier.slice(Resources_SharedUtils.GENERATED_FILE_REGENERATE_OPERATION_PREFIX.length);
+        return fieldName.trim() ? { fieldName } : undefined;
+    }
+    /**
+     * Identifier of the export companion of `sourceOperationIdentifier`
+     * (e.g. `collectionExport:list`, `collectionExport:mySearchVariant`).
+     */
+    static buildGeneratedCollectionExportOperationIdentifier(sourceOperationIdentifier) {
+        if (!sourceOperationIdentifier.trim()) {
+            throw Resources_SharedUtils.createConfigurationError('Generated collection export operation requires a non-empty source operation identifier');
+        }
+        return `${Resources_SharedUtils.GENERATED_COLLECTION_EXPORT_OPERATION_PREFIX}${sourceOperationIdentifier}`;
+    }
+    static parseGeneratedCollectionExportOperationIdentifier(operationIdentifier) {
+        if (!operationIdentifier.startsWith(Resources_SharedUtils.GENERATED_COLLECTION_EXPORT_OPERATION_PREFIX)) {
+            return undefined;
+        }
+        const sourceOperationIdentifier = operationIdentifier.slice(Resources_SharedUtils.GENERATED_COLLECTION_EXPORT_OPERATION_PREFIX.length);
+        return sourceOperationIdentifier.trim() ? { sourceOperationIdentifier } : undefined;
+    }
     /**
      * Resolve the FK field identity for a relationship.
      *
@@ -428,7 +890,7 @@ export class Resources_SharedUtils {
      * where the framework derives the deeper internal handling contract and the
      * effective low-level `childOperations` shape consumed today.
      */
-    static resolveRelationshipSemantics(relationship) {
+    static resolveRelationshipSemantics(relationship, allResourceFieldIdentifiers) {
         const resolvedNature = this.resolveRelationshipNature(relationship);
         const parsedChildOperations = relationship.childOperations
             ? ChildOperationsConfigSchema.parse(relationship.childOperations)
@@ -443,11 +905,13 @@ export class Resources_SharedUtils {
             explicitRead,
         });
         const handling = this.deriveRelationshipHandlingContract(resolvedNature.nature, parsedChildOperations, resolvedReadCalculation.model);
+        const persistence = this.deriveRelationshipPersistenceContract(relationship, allResourceFieldIdentifiers);
         return {
             nature: resolvedNature.nature,
             natureCalculationMode: resolvedNature.source,
             readCalculationMode: resolvedReadCalculation.source,
             handling,
+            persistence,
             childOperations: parsedChildOperations,
         };
     }
@@ -495,14 +959,29 @@ export class Resources_SharedUtils {
         }
         return semantics.childOperations?.lifecycle?.onParentDelete;
     }
+    /**
+     * Resolve the effective lifecycle-on-parent-create projection — the eager
+     * composition-child seeding policy. Mirror of
+     * {@link resolveRelationshipLifecycleOnParentDeleteConfig}: `lifecycleModelMode`
+     * is the semantic gate (INDEPENDENT / aggregation → no eager seed), and the
+     * detailed create policy comes from the operational
+     * `childOperations.lifecycle.onParentCreate` projection.
+     */
+    static resolveRelationshipLifecycleOnParentCreateConfig(relationship) {
+        const semantics = this.requireResolvedRelationshipSemantics(relationship);
+        if (semantics.handling.lifecycleModelMode === RelationshipLifecycleModel.INDEPENDENT) {
+            return undefined;
+        }
+        return semantics.childOperations?.lifecycle?.onParentCreate;
+    }
     /**
      * Compile the developer-authored declaration into the runtime relationship
      * shape used by the framework.
      */
-    static compileRelationshipDeclaration(relationship) {
+    static compileRelationshipDeclaration(relationship, allResourceFieldIdentifiers) {
         return {
             ...relationship,
-            resolvedSemantics: this.resolveRelationshipSemantics(relationship),
+            resolvedSemantics: this.resolveRelationshipSemantics(relationship, allResourceFieldIdentifiers),
         };
     }
     /**
@@ -512,17 +991,37 @@ export class Resources_SharedUtils {
      * relationships from multiple sources before they are stored on registries or
      * resource configurations.
      */
-    static ensureCompiledRelationship(relationship) {
-        const compiledRelationship = this.compileRelationshipDeclaration(relationship);
+    static ensureCompiledRelationship(relationship, allResourceFieldIdentifiers) {
+        const compiledRelationship = this.compileRelationshipDeclaration(relationship, allResourceFieldIdentifiers);
         if ('resolvedSemantics' in relationship &&
             this.hasValidResolvedRelationshipSemantics(relationship.resolvedSemantics) &&
             this.areResolvedRelationshipSemanticsEquivalent(relationship.resolvedSemantics, compiledRelationship.resolvedSemantics)) {
             return relationship;
         }
+        if (!allResourceFieldIdentifiers &&
+            'resolvedSemantics' in relationship &&
+            this.hasValidResolvedRelationshipSemantics(relationship.resolvedSemantics) &&
+            relationship.resolvedSemantics.persistence.foreignKey &&
+            !compiledRelationship.resolvedSemantics.persistence.foreignKey) {
+            return {
+                ...compiledRelationship,
+                resolvedSemantics: {
+                    ...compiledRelationship.resolvedSemantics,
+                    persistence: relationship.resolvedSemantics.persistence,
+                },
+            };
+        }
         return compiledRelationship;
     }
-    static ensureCompiledRelationships(relationships) {
-        return relationships.map((relationship) => this.ensureCompiledRelationship(relationship));
+    static ensureCompiledRelationships(relationships, allResourceFieldIdentifiers) {
+        return relationships.map((relationship) => this.ensureCompiledRelationship(relationship, allResourceFieldIdentifiers));
+    }
+    static ensureCompiledRelationshipBuckets(resourceRelationships, allResourceFieldIdentifiers) {
+        return {
+            parentRelationships: this.ensureCompiledRelationships(resourceRelationships.parentRelationships ?? [], allResourceFieldIdentifiers),
+            childRelationships: this.ensureCompiledRelationships(resourceRelationships.childRelationships ?? [], allResourceFieldIdentifiers),
+            selfRelationships: this.ensureCompiledRelationships(resourceRelationships.selfRelationships ?? [], allResourceFieldIdentifiers),
+        };
     }
     /**
      * Strict runtime reader for already-compiled relationships.
@@ -609,12 +1108,66 @@ export class Resources_SharedUtils {
                 onParentDelete: {
                     enabled: lifecycleOnDelete.enabled,
                     mode: lifecycleOnDelete.mode ?? ChildLifecycleMode.IMMEDIATE,
+                    // Project the teardown STRATEGY too — without it the derived semantic contract cannot
+                    // distinguish a hard-delete cascade from an impersonalize-and-retain one.
+                    strategy: lifecycleOnDelete.strategy ?? ChildLifecycleStrategy.DELETE,
                     maxDepth: lifecycleOnDelete.maxDepth,
                 },
             };
         }
         return baseContract;
     }
+    /**
+     * Derive runtime persistence behavior from the authored relationship topology.
+     *
+     * The declaration remains small: developers author cardinality, parent
+     * requirement, nature, and the FK field when disambiguation is needed. The
+     * framework compiles the persistence consequence here so storage adapters do
+     * not reinterpret relationship meaning independently.
+     *
+     * The contract is expressed from the HOLDER's perspective
+     * ({@link resolveForeignKeyHolderResourceType} — the side whose rows carry
+     * the FK column, resolved from cardinality, never from declaration order):
+     * - `holderResourceType` tells storage adapters WHICH resource the contract
+     *   applies to — an adapter building any other resource of the relationship
+     *   must not materialize or validate this FK there;
+     * - `required` means the holder's FK column is non-nullable (the referenced
+     *   parent is mandatory for every holder row);
+     * - `unique` means at most one holder row per referenced row, which is true
+     *   exactly when the relationship is a genuine 1:1 — BOTH sides
+     *   single-valued. Keying uniqueness off `cardinality2` alone (the previous
+     *   derivation) assumed parent-first declaration order: for child-first
+     *   N:1 references (`(TODOS, USERS, MANY, ONE)`) and self-referencing trees
+     *   (`(UNITS, UNITS, ONE, MANY)`) a single positional cardinality is ONE
+     *   while the relationship is not 1:1, which would emit a bogus unique
+     *   index on a shared FK.
+     */
+    static deriveRelationshipPersistenceContract(relationship, allResourceFieldIdentifiers) {
+        const foreignKeyIdentity = allResourceFieldIdentifiers
+            ? this.tryResolveRelationshipForeignKeyIdentity(relationship, allResourceFieldIdentifiers)
+            : relationship.foreignKeyField
+                ? {
+                    fieldIdentifier: relationship.foreignKeyField,
+                }
+                : undefined;
+        if (!foreignKeyIdentity) {
+            return {};
+        }
+        const isArrayForeignKey = foreignKeyIdentity.fieldIdentifier.endsWith('Ids');
+        const holderResourceType = this.resolveForeignKeyHolderResourceType(relationship);
+        const isTrueOneToOne = isOneToOneCardinality(relationship.cardinality1) &&
+            isOneToOneCardinality(relationship.cardinality2);
+        return {
+            foreignKey: {
+                fieldIdentifier: foreignKeyIdentity.fieldIdentifier,
+                holderResourceType,
+                isArray: isArrayForeignKey,
+                materializeField: true,
+                required: relationship.parentResourceRequirement !== ResourceParentResourceRequirement.OPTIONAL,
+                unique: !isArrayForeignKey && isTrueOneToOne,
+            },
+        };
+    }
     static assertRelationshipSemanticsCoherence(relationship, resolvedNature, childOperations, explicitRead) {
         const legacyReadModel = this.deriveLegacyRelationshipReadModel(resolvedNature, childOperations);
         if (resolvedNature === RelationshipNature.ASSOCIATION && !relationship.jointResourceType) {
@@ -749,4 +1302,4 @@ export class Resources_SharedUtils {
         return relationships.filter((relationship) => this.isRelationshipActiveForParent(relationship, parentResource, options));
     }
 }
-//# sourceMappingURL=resources.shared.utils.js.map
+//# sourceMappingURL=resources.shared.utils.js.map