@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/resources/utils/composition-cascade-deletability.validation.d.ts

@@ -0,0 +1,134 @@
+import { ResourceRelationship } from '../resources.shared.schemas';
+import { ResourceType, CoreResourceOperation } from '../resources.shared.core.definitions';
+import { ChildLifecycleStrategy } from '../child-operations.shared.schemas';
+import type { ErasureRetentionMode } from '../../compliance/privacy/impersonalization.shared.schemas';
+/**
+ * Registry-level guardrail for the composition `onParentDelete` lifecycle — the
+ * DELETE-side counterpart to `validateCompositionSeedability`.
+ *
+ * A composition relationship that OPTS IN to the delete cascade
+ * (`childOperations.lifecycle.onParentDelete.enabled = true`) must actually be
+ * cascade-deletable, or the runtime cascade throws `ErrorType.CONFIGURATION`
+ * INSIDE the parent's delete transaction and ROLLS BACK the parent delete. Two
+ * things must hold on the child, checked here with the exact predicate the
+ * runtime uses (`supportsOperation`: the op has a default variant):
+ *
+ *  1. **Discovery** — `deleteChildrenImmediate` loads the children before
+ *     deleting them: a 1:1 child via READ, a 1:many child via LIST. Missing that
+ *     op → `CONFIGURATION` throw.
+ *  2. **Teardown** — it then removes them via DELETE_MANY (preferred) or a
+ *     per-row DELETE loop. Missing BOTH → `CONFIGURATION` throw. (DELETE strategy.)
+ *
+ * ## Two teardown strategies (`onParentDelete.strategy`)
+ *
+ * DELETE (default) hard-deletes the child, so it needs the DELETE/DELETE_MANY
+ * teardown op above. IMPERSONALIZE_AND_RETAIN instead scrubs the child's personal
+ * fields IN PLACE and KEEPS the row (retain-for-audit, GDPR Art. 17(3)(b)), via the
+ * trusted `updateManyAsSystem` writer — so it needs NO delete op. It instead needs
+ * the child to be retention-governed (`retentionPolicy`,
+ * which the resource factory guarantees also carries the UPDATE_MANY scrub grant +
+ * the `retentionStatus` marker). Discovery (point 1) is shared by both strategies.
+ *
+ * ## Why this is separate from (and dual to) seedability
+ *
+ * `onParentCreate` (seed) and `onParentDelete` (cascade) are orthogonal DDD axes
+ * (created-with vs dies-with). The seed resolves the child's CREATE through the
+ * SERVICE tier (rejects REPOSITORY_ONLY); the cascade deletes through the
+ * REPOSITORY tier (variant-agnostic). So the two guards check different ops on
+ * different resolution paths and neither implies the other — a child can be
+ * seedable but not cascade-deletable (exactly the gap that shipped for the
+ * lifecycle / guidance / progression / preferences / notifications adopters).
+ *
+ * ## Unreachable edges are NOT violations (parent-reachability skip)
+ *
+ * The cascade runs ONLY from the PARENT's DELETE / DELETE_MANY post-op logic. If
+ * the parent can reach neither, the edge is structurally unreachable — dormant,
+ * never fired — and is intentionally skipped (e.g. `USER_SELF` exposes only
+ * READ/UPDATE, so `USER_SELF → USER_SELF_PREFERENCES/PROFILES` never cascades;
+ * real user deletion runs through `USERS`, whose profile/preferences children DO
+ * carry DELETE). This skip is self-correcting: the day the parent gains a delete
+ * path, its dormant edges become reachable and this guard fires.
+ *
+ * "Can reach" means {@link canFireDeleteCascade}, not `supportsOperation` — a
+ * CUSTOM operation borrowing the verb through `resourceOperationLike` fires the
+ * cascade exactly as a core DELETE does. Reading only the core verb made this
+ * skip unsound; `user_self | delete_account` (removed 2026-08-01) was the live
+ * case, and its two edges reported clean here while throwing at runtime.
+ *
+ * ## Fail-closed, fail-open on ambiguity
+ *
+ * A genuine violation (a reachable adopter missing a discovery/teardown op) is a
+ * boot-time throw. When the edge cannot be classified (parent absent from the
+ * map) the check skips (fail-open) so it never false-positives or blocks
+ * startup. Pure and side-effect free.
+ */
+/** Structural subset of a built resource configuration this validator needs. */
+export interface CompositionCascadeDeletabilityResourceInput {
+    resourceIdentifier: ResourceType;
+    /**
+     * Flattened per-variant operations — read exactly like the runtime
+     * `supportsOperation` (`op.operationIdentifier === verb && op.isOperationDefault`).
+     *
+     * `resourceOperationLike` is carried because a CUSTOM operation borrowing a core verb reaches the
+     * same repository primitive as the core operation, and so fires the same cascade — see
+     * {@link canFireDeleteCascade}. A child's teardown capability is still read through
+     * {@link supportsOperation} (the runtime `supportsOperation` the cascade itself calls), so the
+     * extra field matters only on the PARENT side.
+     */
+    operations: ReadonlyArray<{
+        operationIdentifier: string;
+        isOperationDefault?: boolean;
+        resourceOperationLike?: CoreResourceOperation;
+    }>;
+    /**
+     * Resolved retention policy, present (and normalized to opted-in) IFF this resource is
+     * retention-governed (`retentionPolicy`). Only such resources carry the
+     * factory-injected `retentionStatus` marker AND the derived UPDATE_MANY scrub grant, so only they
+     * can be the CHILD of an `IMPERSONALIZE_AND_RETAIN` onParentDelete edge. Absent = not
+     * retention-governed → an `IMPERSONALIZE_AND_RETAIN` edge toward it is a violation.
+     */
+    retentionPolicy?: {
+        mode?: ErasureRetentionMode;
+    };
+    resourceRelationships?: {
+        parentRelationships?: ResourceRelationship[];
+    };
+}
+export interface CompositionCascadeDeletabilityViolation {
+    childResourceType: ResourceType;
+    parentResourceType: ResourceType;
+    cardinality: 'one-to-one' | 'one-to-many';
+    /** The teardown strategy the edge declared: DELETE (hard-delete) or IMPERSONALIZE_AND_RETAIN (scrub+keep). */
+    strategy: ChildLifecycleStrategy;
+    /** The discovery op the cascade needs but the child lacks (READ for 1:1, LIST for 1:many), if any. Shared by both strategies. */
+    missingDiscoveryOp?: CoreResourceOperation;
+    /** DELETE strategy only: true when the child supports neither DELETE nor DELETE_MANY. */
+    missingTeardownOp: boolean;
+    /**
+     * IMPERSONALIZE_AND_RETAIN strategy only: true when the child is NOT retention-governed
+     * (no `retentionPolicy` → no `retentionStatus` marker + no derived
+     * UPDATE_MANY scrub grant to flip it with).
+     */
+    missingRetentionGovernance?: boolean;
+    /**
+     * IMPERSONALIZE_AND_RETAIN strategy only: true when the edge declares `mode: LAZY`, which v1 cannot
+     * execute (there is no async retain-and-scrub) and which would otherwise throw on the first erasure.
+     */
+    unsupportedLazyRetainMode?: boolean;
+    message: string;
+}
+/**
+ * Validate that every composition relationship which opted into
+ * `onParentDelete.enabled` is actually cascade-deletable (its child has the
+ * cardinality-appropriate discovery op + a DELETE/DELETE_MANY teardown op),
+ * unless the edge is structurally unreachable because the parent cannot fire the
+ * cascade. Returns the list of violations (empty when clean); the caller throws
+ * on any (fail-closed).
+ *
+ * @param resourceConfigurations - the registry's `resourceConfigurations` map
+ *   (`resourceType → built configuration`). Each entry is the CHILD in its
+ *   `parentRelationships`; parents are looked up in the same map for the
+ *   reachability skip.
+ */
+export declare function validateCompositionCascadeDeletability(resourceConfigurations: Record<string, CompositionCascadeDeletabilityResourceInput>): CompositionCascadeDeletabilityViolation[];
+//# sourceMappingURL=composition-cascade-deletability.validation.d.ts.map

package/dist/esm/resources/utils/composition-cascade-deletability.validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition-cascade-deletability.validation.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/composition-cascade-deletability.validation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EAGrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC3F,OAAO,EAAsB,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAChG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2DAA2D,CAAC;AAEtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,gFAAgF;AAChF,MAAM,WAAW,2CAA2C;IAC1D,kBAAkB,EAAE,YAAY,CAAC;IACjC;;;;;;;;;OASG;IACH,UAAU,EAAE,aAAa,CAAC;QACxB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;KAC/C,CAAC,CAAC;IACH;;;;;;OAMG;IACH,eAAe,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAC;IAClD,qBAAqB,CAAC,EAAE;QACtB,mBAAmB,CAAC,EAAE,oBAAoB,EAAE,CAAC;KAC9C,CAAC;CACH;AAED,MAAM,WAAW,uCAAuC;IACtD,iBAAiB,EAAE,YAAY,CAAC;IAChC,kBAAkB,EAAE,YAAY,CAAC;IACjC,WAAW,EAAE,YAAY,GAAG,aAAa,CAAC;IAC1C,8GAA8G;IAC9G,QAAQ,EAAE,sBAAsB,CAAC;IACjC,iIAAiI;IACjI,kBAAkB,CAAC,EAAE,qBAAqB,CAAC;IAC3C,yFAAyF;IACzF,iBAAiB,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC;;;OAGG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAoDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sCAAsC,CACpD,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,2CAA2C,CAAC,GAClF,uCAAuC,EAAE,CA6H3C"}

package/dist/esm/resources/utils/composition-cascade-deletability.validation.js

@@ -0,0 +1,167 @@
+import { RelationshipNature, isOneToOneCardinality, } from '../resources.shared.schemas.js';
+import { CoreResourceOperation } from '../resources.shared.core.definitions.js';
+import { ChildLifecycleMode, ChildLifecycleStrategy } from '../child-operations.shared.schemas.js';
+/** Runtime-truthful `supportsOperation`: a default variant for the verb exists. */
+function supportsOperation(resource, verb) {
+    return (resource?.operations?.some((op) => op.operationIdentifier === verb && op.isOperationDefault === true) ?? false);
+}
+/**
+ * Whether this resource can reach the DELETE post-op logic that fires an `onParentDelete` cascade.
+ *
+ * NOT the same question as `supportsOperation(resource, DELETE)`. A CUSTOM operation declaring
+ * `resourceOperationLike: DELETE` carries its own `operationIdentifier`, so `supportsOperation`
+ * says no — yet it reaches `_doDelete` all the same: the service resolves the core verb through
+ * `getCoreResourceOperationFromOperation` (which falls back to `resourceOperationLike`) and calls
+ * the repository by OPERATION PATH, and the repository's operations map is built from EVERY
+ * configured operation, custom ones included. The `coreOperations` gate on the public
+ * `RepositoryResourceBackendService.delete()` convenience method is simply not on that path.
+ *
+ * Reading only the core verb made the parent-reachability skip below unsound, and it cost real
+ * damage: `user_self | delete_account` (removed 2026-08-01) declared no core DELETE, so this guard
+ * cleared its two `onParentDelete` edges as dormant — while at runtime the custom op fired the
+ * cascade into `USER_SELF_PROFILES` / `USER_SELF_PREFERENCES`, neither of which declares a
+ * teardown op. The cascade threw `ErrorType.CONFIGURATION` inside the delete transaction, so the
+ * delete rolled back for any user who had one of those rows and committed for any user who had
+ * neither. A boot guard that cannot see custom delete-like ops cannot protect that edge.
+ *
+ * `DELETE_MANY` is included for the same reason: `deleteMany` is the cascade's preferred teardown
+ * path and a custom op may borrow it just as readily.
+ */
+function canFireDeleteCascade(resource) {
+    if (!resource?.operations)
+        return false;
+    return resource.operations.some((op) => {
+        if (op.isOperationDefault !== true)
+            return false;
+        // A core operation carries the verb as its own identifier; a custom one borrows it.
+        const effectiveVerb = op.operationIdentifier === CoreResourceOperation.DELETE
+            || op.operationIdentifier === CoreResourceOperation.DELETE_MANY
+            ? op.operationIdentifier
+            : op.resourceOperationLike;
+        return effectiveVerb === CoreResourceOperation.DELETE
+            || effectiveVerb === CoreResourceOperation.DELETE_MANY;
+    });
+}
+/**
+ * Validate that every composition relationship which opted into
+ * `onParentDelete.enabled` is actually cascade-deletable (its child has the
+ * cardinality-appropriate discovery op + a DELETE/DELETE_MANY teardown op),
+ * unless the edge is structurally unreachable because the parent cannot fire the
+ * cascade. Returns the list of violations (empty when clean); the caller throws
+ * on any (fail-closed).
+ *
+ * @param resourceConfigurations - the registry's `resourceConfigurations` map
+ *   (`resourceType → built configuration`). Each entry is the CHILD in its
+ *   `parentRelationships`; parents are looked up in the same map for the
+ *   reachability skip.
+ */
+export function validateCompositionCascadeDeletability(resourceConfigurations) {
+    const violations = [];
+    for (const child of Object.values(resourceConfigurations)) {
+        const parentRelationships = child.resourceRelationships?.parentRelationships ?? [];
+        for (const relationship of parentRelationships) {
+            if (relationship.nature !== RelationshipNature.COMPOSITION) {
+                continue;
+            }
+            // Only an ENABLED onParentDelete cascade must be cascade-deletable. A
+            // composition WITHOUT it leaves orphans by design choice — not this guard's
+            // concern.
+            const onParentDelete = relationship.childOperations?.lifecycle?.onParentDelete;
+            if (onParentDelete?.enabled !== true) {
+                continue;
+            }
+            // Parent-reachability skip: the cascade fires from the parent's DELETE / DELETE_MANY post-op
+            // logic. A parent that can reach neither can never trigger this edge → dormant, not a
+            // violation. Self-correcting: the day the parent gains a delete path, this stops skipping and
+            // the guard fires.
+            //
+            // Reachability is `canFireDeleteCascade`, NOT `supportsOperation` — a CUSTOM op borrowing the
+            // verb via `resourceOperationLike` fires the cascade too, and reading only the core verb is
+            // what let `user_self | delete_account` cascade into two teardown-less children while this
+            // guard reported clean. See the function's JSDoc.
+            const parent = resourceConfigurations[relationship.resourceType1];
+            if (!parent) {
+                continue; // fail-open: parent not in this map, cannot classify
+            }
+            if (!canFireDeleteCascade(parent)) {
+                continue; // structurally unreachable edge — no core AND no delete-like custom op
+            }
+            // Discovery op depends on cardinality: 1:1 discovered via READ, 1:many via LIST. SHARED by both
+            // teardown strategies — impersonalizeChildrenImmediate reads the same way before scrubbing.
+            const oneToOne = isOneToOneCardinality(relationship.cardinality2);
+            const discoveryOp = oneToOne ? CoreResourceOperation.READ : CoreResourceOperation.LIST;
+            const hasDiscovery = supportsOperation(child, discoveryOp);
+            // The teardown STRATEGY decides what the child needs beyond discovery: DELETE (default) needs a
+            // DELETE/DELETE_MANY op; IMPERSONALIZE_AND_RETAIN needs the child to be retention-governed.
+            const strategy = onParentDelete.strategy ?? ChildLifecycleStrategy.DELETE;
+            if (strategy === ChildLifecycleStrategy.IMPERSONALIZE_AND_RETAIN) {
+                // Retain-and-scrub teardown (via updateManyAsSystem), NOT a hard delete. The child must be
+                // retention-governed: only `retentionPolicy` injects the retentionStatus
+                // marker AND derives the UPDATE_MANY scrub grant. A non-retention child has nothing to flip →
+                // impersonalizeChildrenImmediate throws CONFIGURATION and rolls back the parent delete.
+                const isRetentionGoverned = child.retentionPolicy?.mode !== undefined;
+                // v1 executes the retain-and-scrub only in IMMEDIATE mode. A LAZY retain edge parses, boots and
+                // passes CI, then throws on the FIRST production erasure — inside the parent transaction, so a
+                // GDPR deletion request fails. Catch the unsupported combination here instead.
+                const isUnsupportedLazyMode = onParentDelete.mode === ChildLifecycleMode.LAZY;
+                if (hasDiscovery && isRetentionGoverned && !isUnsupportedLazyMode) {
+                    continue; // impersonalize-able
+                }
+                const missing = [];
+                if (!hasDiscovery) {
+                    missing.push(`${discoveryOp} (to discover ${oneToOne ? '1:1' : '1:many'} dependents)`);
+                }
+                if (!isRetentionGoverned) {
+                    missing.push('retentionPolicy (either mode — to carry the retentionStatus marker + the UPDATE_MANY retain grant)');
+                }
+                if (isUnsupportedLazyMode) {
+                    missing.push('mode: IMMEDIATE (v1 has no async retain-and-scrub; LAZY would throw on the first erasure)');
+                }
+                violations.push({
+                    childResourceType: child.resourceIdentifier,
+                    parentResourceType: relationship.resourceType1,
+                    cardinality: oneToOne ? 'one-to-one' : 'one-to-many',
+                    strategy,
+                    missingDiscoveryOp: hasDiscovery ? undefined : discoveryOp,
+                    missingTeardownOp: false, // teardown is a scrub, not a delete op
+                    missingRetentionGovernance: !isRetentionGoverned,
+                    unsupportedLazyRetainMode: isUnsupportedLazyMode,
+                    message: `Composition child '${child.resourceIdentifier}' (parent '${relationship.resourceType1}') ` +
+                        `enabled onParentDelete with strategy IMPERSONALIZE_AND_RETAIN but is NOT impersonalize-able: ` +
+                        `missing ${missing.join(' and ')}. The retain-and-scrub cascade (impersonalizeChildrenImmediate) ` +
+                        `would throw ErrorType.CONFIGURATION and roll back the parent delete once a child row exists. ` +
+                        `Opt the child into retentionPolicy (RETAIN_ONLY or RETAIN_AND_IMPERSONALIZE), or use strategy DELETE.`,
+                });
+                continue;
+            }
+            // DELETE strategy (default): teardown op is DELETE_MANY (preferred by the cascade) or a per-row DELETE.
+            const hasTeardown = supportsOperation(child, CoreResourceOperation.DELETE_MANY) ||
+                supportsOperation(child, CoreResourceOperation.DELETE);
+            if (hasDiscovery && hasTeardown) {
+                continue; // cascade-deletable
+            }
+            const missing = [];
+            if (!hasDiscovery) {
+                missing.push(`${discoveryOp} (to discover ${oneToOne ? '1:1' : '1:many'} dependents)`);
+            }
+            if (!hasTeardown) {
+                missing.push('DELETE or DELETE_MANY (to remove the row)');
+            }
+            violations.push({
+                childResourceType: child.resourceIdentifier,
+                parentResourceType: relationship.resourceType1,
+                cardinality: oneToOne ? 'one-to-one' : 'one-to-many',
+                strategy,
+                missingDiscoveryOp: hasDiscovery ? undefined : discoveryOp,
+                missingTeardownOp: !hasTeardown,
+                message: `Composition child '${child.resourceIdentifier}' (parent '${relationship.resourceType1}') ` +
+                    `enabled onParentDelete but is NOT cascade-deletable: missing ${missing.join(' and ')}. ` +
+                    `The delete cascade (deleteChildrenImmediate) would throw ErrorType.CONFIGURATION and roll ` +
+                    `back the parent delete once a child row exists. Add the missing op(s) (a REPOSITORY_ONLY ` +
+                    `DELETE is enough for teardown), or drop onParentDelete.enabled.`,
+            });
+        }
+    }
+    return violations;
+}
+//# sourceMappingURL=composition-cascade-deletability.validation.js.map

package/dist/esm/resources/utils/composition-cascade-deletability.validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition-cascade-deletability.validation.js","sourceRoot":"","sources":["../../../../../src/resources/utils/composition-cascade-deletability.validation.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  ResourceRelationship,\n  RelationshipNature,\n  isOneToOneCardinality,\n} from '../resources.shared.schemas';\nimport { ResourceType, CoreResourceOperation } from '../resources.shared.core.definitions';\nimport { ChildLifecycleMode, ChildLifecycleStrategy } from '../child-operations.shared.schemas';\nimport type { ErasureRetentionMode } from '../../compliance/privacy/impersonalization.shared.schemas';\n\n/**\n * Registry-level guardrail for the composition `onParentDelete` lifecycle — the\n * DELETE-side counterpart to `validateCompositionSeedability`.\n *\n * A composition relationship that OPTS IN to the delete cascade\n * (`childOperations.lifecycle.onParentDelete.enabled = true`) must actually be\n * cascade-deletable, or the runtime cascade throws `ErrorType.CONFIGURATION`\n * INSIDE the parent's delete transaction and ROLLS BACK the parent delete. Two\n * things must hold on the child, checked here with the exact predicate the\n * runtime uses (`supportsOperation`: the op has a default variant):\n *\n *  1. **Discovery** — `deleteChildrenImmediate` loads the children before\n *     deleting them: a 1:1 child via READ, a 1:many child via LIST. Missing that\n *     op → `CONFIGURATION` throw.\n *  2. **Teardown** — it then removes them via DELETE_MANY (preferred) or a\n *     per-row DELETE loop. Missing BOTH → `CONFIGURATION` throw. (DELETE strategy.)\n *\n * ## Two teardown strategies (`onParentDelete.strategy`)\n *\n * DELETE (default) hard-deletes the child, so it needs the DELETE/DELETE_MANY\n * teardown op above. IMPERSONALIZE_AND_RETAIN instead scrubs the child's personal\n * fields IN PLACE and KEEPS the row (retain-for-audit, GDPR Art. 17(3)(b)), via the\n * trusted `updateManyAsSystem` writer — so it needs NO delete op. It instead needs\n * the child to be retention-governed (`retentionPolicy`,\n * which the resource factory guarantees also carries the UPDATE_MANY scrub grant +\n * the `retentionStatus` marker). Discovery (point 1) is shared by both strategies.\n *\n * ## Why this is separate from (and dual to) seedability\n *\n * `onParentCreate` (seed) and `onParentDelete` (cascade) are orthogonal DDD axes\n * (created-with vs dies-with). The seed resolves the child's CREATE through the\n * SERVICE tier (rejects REPOSITORY_ONLY); the cascade deletes through the\n * REPOSITORY tier (variant-agnostic). So the two guards check different ops on\n * different resolution paths and neither implies the other — a child can be\n * seedable but not cascade-deletable (exactly the gap that shipped for the\n * lifecycle / guidance / progression / preferences / notifications adopters).\n *\n * ## Unreachable edges are NOT violations (parent-reachability skip)\n *\n * The cascade runs ONLY from the PARENT's DELETE / DELETE_MANY post-op logic. If\n * the parent can reach neither, the edge is structurally unreachable — dormant,\n * never fired — and is intentionally skipped (e.g. `USER_SELF` exposes only\n * READ/UPDATE, so `USER_SELF → USER_SELF_PREFERENCES/PROFILES` never cascades;\n * real user deletion runs through `USERS`, whose profile/preferences children DO\n * carry DELETE). This skip is self-correcting: the day the parent gains a delete\n * path, its dormant edges become reachable and this guard fires.\n *\n * \"Can reach\" means {@link canFireDeleteCascade}, not `supportsOperation` — a\n * CUSTOM operation borrowing the verb through `resourceOperationLike` fires the\n * cascade exactly as a core DELETE does. Reading only the core verb made this\n * skip unsound; `user_self | delete_account` (removed 2026-08-01) was the live\n * case, and its two edges reported clean here while throwing at runtime.\n *\n * ## Fail-closed, fail-open on ambiguity\n *\n * A genuine violation (a reachable adopter missing a discovery/teardown op) is a\n * boot-time throw. When the edge cannot be classified (parent absent from the\n * map) the check skips (fail-open) so it never false-positives or blocks\n * startup. Pure and side-effect free.\n */\n\n/** Structural subset of a built resource configuration this validator needs. */\nexport interface CompositionCascadeDeletabilityResourceInput {\n  resourceIdentifier: ResourceType;\n  /**\n   * Flattened per-variant operations — read exactly like the runtime\n   * `supportsOperation` (`op.operationIdentifier === verb && op.isOperationDefault`).\n   *\n   * `resourceOperationLike` is carried because a CUSTOM operation borrowing a core verb reaches the\n   * same repository primitive as the core operation, and so fires the same cascade — see\n   * {@link canFireDeleteCascade}. A child's teardown capability is still read through\n   * {@link supportsOperation} (the runtime `supportsOperation` the cascade itself calls), so the\n   * extra field matters only on the PARENT side.\n   */\n  operations: ReadonlyArray<{\n    operationIdentifier: string;\n    isOperationDefault?: boolean;\n    resourceOperationLike?: CoreResourceOperation;\n  }>;\n  /**\n   * Resolved retention policy, present (and normalized to opted-in) IFF this resource is\n   * retention-governed (`retentionPolicy`). Only such resources carry the\n   * factory-injected `retentionStatus` marker AND the derived UPDATE_MANY scrub grant, so only they\n   * can be the CHILD of an `IMPERSONALIZE_AND_RETAIN` onParentDelete edge. Absent = not\n   * retention-governed → an `IMPERSONALIZE_AND_RETAIN` edge toward it is a violation.\n   */\n  retentionPolicy?: { mode?: ErasureRetentionMode };\n  resourceRelationships?: {\n    parentRelationships?: ResourceRelationship[];\n  };\n}\n\nexport interface CompositionCascadeDeletabilityViolation {\n  childResourceType: ResourceType;\n  parentResourceType: ResourceType;\n  cardinality: 'one-to-one' | 'one-to-many';\n  /** The teardown strategy the edge declared: DELETE (hard-delete) or IMPERSONALIZE_AND_RETAIN (scrub+keep). */\n  strategy: ChildLifecycleStrategy;\n  /** The discovery op the cascade needs but the child lacks (READ for 1:1, LIST for 1:many), if any. Shared by both strategies. */\n  missingDiscoveryOp?: CoreResourceOperation;\n  /** DELETE strategy only: true when the child supports neither DELETE nor DELETE_MANY. */\n  missingTeardownOp: boolean;\n  /**\n   * IMPERSONALIZE_AND_RETAIN strategy only: true when the child is NOT retention-governed\n   * (no `retentionPolicy` → no `retentionStatus` marker + no derived\n   * UPDATE_MANY scrub grant to flip it with).\n   */\n  missingRetentionGovernance?: boolean;\n  /**\n   * IMPERSONALIZE_AND_RETAIN strategy only: true when the edge declares `mode: LAZY`, which v1 cannot\n   * execute (there is no async retain-and-scrub) and which would otherwise throw on the first erasure.\n   */\n  unsupportedLazyRetainMode?: boolean;\n  message: string;\n}\n\n/** Runtime-truthful `supportsOperation`: a default variant for the verb exists. */\nfunction supportsOperation(\n  resource: CompositionCascadeDeletabilityResourceInput | undefined,\n  verb: CoreResourceOperation,\n): boolean {\n  return (\n    resource?.operations?.some(\n      (op) => op.operationIdentifier === verb && op.isOperationDefault === true,\n    ) ?? false\n  );\n}\n\n/**\n * Whether this resource can reach the DELETE post-op logic that fires an `onParentDelete` cascade.\n *\n * NOT the same question as `supportsOperation(resource, DELETE)`. A CUSTOM operation declaring\n * `resourceOperationLike: DELETE` carries its own `operationIdentifier`, so `supportsOperation`\n * says no — yet it reaches `_doDelete` all the same: the service resolves the core verb through\n * `getCoreResourceOperationFromOperation` (which falls back to `resourceOperationLike`) and calls\n * the repository by OPERATION PATH, and the repository's operations map is built from EVERY\n * configured operation, custom ones included. The `coreOperations` gate on the public\n * `RepositoryResourceBackendService.delete()` convenience method is simply not on that path.\n *\n * Reading only the core verb made the parent-reachability skip below unsound, and it cost real\n * damage: `user_self | delete_account` (removed 2026-08-01) declared no core DELETE, so this guard\n * cleared its two `onParentDelete` edges as dormant — while at runtime the custom op fired the\n * cascade into `USER_SELF_PROFILES` / `USER_SELF_PREFERENCES`, neither of which declares a\n * teardown op. The cascade threw `ErrorType.CONFIGURATION` inside the delete transaction, so the\n * delete rolled back for any user who had one of those rows and committed for any user who had\n * neither. A boot guard that cannot see custom delete-like ops cannot protect that edge.\n *\n * `DELETE_MANY` is included for the same reason: `deleteMany` is the cascade's preferred teardown\n * path and a custom op may borrow it just as readily.\n */\nfunction canFireDeleteCascade(\n  resource: CompositionCascadeDeletabilityResourceInput | undefined,\n): boolean {\n  if (!resource?.operations) return false;\n  return resource.operations.some((op) => {\n    if (op.isOperationDefault !== true) return false;\n    // A core operation carries the verb as its own identifier; a custom one borrows it.\n    const effectiveVerb = op.operationIdentifier === CoreResourceOperation.DELETE\n      || op.operationIdentifier === CoreResourceOperation.DELETE_MANY\n      ? (op.operationIdentifier as CoreResourceOperation)\n      : op.resourceOperationLike;\n    return effectiveVerb === CoreResourceOperation.DELETE\n      || effectiveVerb === CoreResourceOperation.DELETE_MANY;\n  });\n}\n\n/**\n * Validate that every composition relationship which opted into\n * `onParentDelete.enabled` is actually cascade-deletable (its child has the\n * cardinality-appropriate discovery op + a DELETE/DELETE_MANY teardown op),\n * unless the edge is structurally unreachable because the parent cannot fire the\n * cascade. Returns the list of violations (empty when clean); the caller throws\n * on any (fail-closed).\n *\n * @param resourceConfigurations - the registry's `resourceConfigurations` map\n *   (`resourceType → built configuration`). Each entry is the CHILD in its\n *   `parentRelationships`; parents are looked up in the same map for the\n *   reachability skip.\n */\nexport function validateCompositionCascadeDeletability(\n  resourceConfigurations: Record<string, CompositionCascadeDeletabilityResourceInput>,\n): CompositionCascadeDeletabilityViolation[] {\n  const violations: CompositionCascadeDeletabilityViolation[] = [];\n\n  for (const child of Object.values(resourceConfigurations)) {\n    const parentRelationships = child.resourceRelationships?.parentRelationships ?? [];\n\n    for (const relationship of parentRelationships) {\n      if (relationship.nature !== RelationshipNature.COMPOSITION) {\n        continue;\n      }\n\n      // Only an ENABLED onParentDelete cascade must be cascade-deletable. A\n      // composition WITHOUT it leaves orphans by design choice — not this guard's\n      // concern.\n      const onParentDelete = relationship.childOperations?.lifecycle?.onParentDelete;\n      if (onParentDelete?.enabled !== true) {\n        continue;\n      }\n\n      // Parent-reachability skip: the cascade fires from the parent's DELETE / DELETE_MANY post-op\n      // logic. A parent that can reach neither can never trigger this edge → dormant, not a\n      // violation. Self-correcting: the day the parent gains a delete path, this stops skipping and\n      // the guard fires.\n      //\n      // Reachability is `canFireDeleteCascade`, NOT `supportsOperation` — a CUSTOM op borrowing the\n      // verb via `resourceOperationLike` fires the cascade too, and reading only the core verb is\n      // what let `user_self | delete_account` cascade into two teardown-less children while this\n      // guard reported clean. See the function's JSDoc.\n      const parent = resourceConfigurations[relationship.resourceType1];\n      if (!parent) {\n        continue; // fail-open: parent not in this map, cannot classify\n      }\n      if (!canFireDeleteCascade(parent)) {\n        continue; // structurally unreachable edge — no core AND no delete-like custom op\n      }\n\n      // Discovery op depends on cardinality: 1:1 discovered via READ, 1:many via LIST. SHARED by both\n      // teardown strategies — impersonalizeChildrenImmediate reads the same way before scrubbing.\n      const oneToOne = isOneToOneCardinality(relationship.cardinality2);\n      const discoveryOp = oneToOne ? CoreResourceOperation.READ : CoreResourceOperation.LIST;\n      const hasDiscovery = supportsOperation(child, discoveryOp);\n\n      // The teardown STRATEGY decides what the child needs beyond discovery: DELETE (default) needs a\n      // DELETE/DELETE_MANY op; IMPERSONALIZE_AND_RETAIN needs the child to be retention-governed.\n      const strategy = onParentDelete.strategy ?? ChildLifecycleStrategy.DELETE;\n\n      if (strategy === ChildLifecycleStrategy.IMPERSONALIZE_AND_RETAIN) {\n        // Retain-and-scrub teardown (via updateManyAsSystem), NOT a hard delete. The child must be\n        // retention-governed: only `retentionPolicy` injects the retentionStatus\n        // marker AND derives the UPDATE_MANY scrub grant. A non-retention child has nothing to flip →\n        // impersonalizeChildrenImmediate throws CONFIGURATION and rolls back the parent delete.\n        const isRetentionGoverned = child.retentionPolicy?.mode !== undefined;\n        // v1 executes the retain-and-scrub only in IMMEDIATE mode. A LAZY retain edge parses, boots and\n        // passes CI, then throws on the FIRST production erasure — inside the parent transaction, so a\n        // GDPR deletion request fails. Catch the unsupported combination here instead.\n        const isUnsupportedLazyMode = onParentDelete.mode === ChildLifecycleMode.LAZY;\n        if (hasDiscovery && isRetentionGoverned && !isUnsupportedLazyMode) {\n          continue; // impersonalize-able\n        }\n\n        const missing: string[] = [];\n        if (!hasDiscovery) {\n          missing.push(`${discoveryOp} (to discover ${oneToOne ? '1:1' : '1:many'} dependents)`);\n        }\n        if (!isRetentionGoverned) {\n          missing.push('retentionPolicy (either mode — to carry the retentionStatus marker + the UPDATE_MANY retain grant)');\n        }\n        if (isUnsupportedLazyMode) {\n          missing.push('mode: IMMEDIATE (v1 has no async retain-and-scrub; LAZY would throw on the first erasure)');\n        }\n\n        violations.push({\n          childResourceType: child.resourceIdentifier,\n          parentResourceType: relationship.resourceType1,\n          cardinality: oneToOne ? 'one-to-one' : 'one-to-many',\n          strategy,\n          missingDiscoveryOp: hasDiscovery ? undefined : discoveryOp,\n          missingTeardownOp: false, // teardown is a scrub, not a delete op\n          missingRetentionGovernance: !isRetentionGoverned,\n          unsupportedLazyRetainMode: isUnsupportedLazyMode,\n          message:\n            `Composition child '${child.resourceIdentifier}' (parent '${relationship.resourceType1}') ` +\n            `enabled onParentDelete with strategy IMPERSONALIZE_AND_RETAIN but is NOT impersonalize-able: ` +\n            `missing ${missing.join(' and ')}. The retain-and-scrub cascade (impersonalizeChildrenImmediate) ` +\n            `would throw ErrorType.CONFIGURATION and roll back the parent delete once a child row exists. ` +\n            `Opt the child into retentionPolicy (RETAIN_ONLY or RETAIN_AND_IMPERSONALIZE), or use strategy DELETE.`,\n        });\n        continue;\n      }\n\n      // DELETE strategy (default): teardown op is DELETE_MANY (preferred by the cascade) or a per-row DELETE.\n      const hasTeardown =\n        supportsOperation(child, CoreResourceOperation.DELETE_MANY) ||\n        supportsOperation(child, CoreResourceOperation.DELETE);\n\n      if (hasDiscovery && hasTeardown) {\n        continue; // cascade-deletable\n      }\n\n      const missing: string[] = [];\n      if (!hasDiscovery) {\n        missing.push(`${discoveryOp} (to discover ${oneToOne ? '1:1' : '1:many'} dependents)`);\n      }\n      if (!hasTeardown) {\n        missing.push('DELETE or DELETE_MANY (to remove the row)');\n      }\n\n      violations.push({\n        childResourceType: child.resourceIdentifier,\n        parentResourceType: relationship.resourceType1,\n        cardinality: oneToOne ? 'one-to-one' : 'one-to-many',\n        strategy,\n        missingDiscoveryOp: hasDiscovery ? undefined : discoveryOp,\n        missingTeardownOp: !hasTeardown,\n        message:\n          `Composition child '${child.resourceIdentifier}' (parent '${relationship.resourceType1}') ` +\n          `enabled onParentDelete but is NOT cascade-deletable: missing ${missing.join(' and ')}. ` +\n          `The delete cascade (deleteChildrenImmediate) would throw ErrorType.CONFIGURATION and roll ` +\n          `back the parent delete once a child row exists. Add the missing op(s) (a REPOSITORY_ONLY ` +\n          `DELETE is enough for teardown), or drop onParentDelete.enabled.`,\n      });\n    }\n  }\n\n  return violations;\n}\n"]}

package/dist/esm/resources/utils/composition-seedability.validation.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { ResourceRelationship } from '../resources.shared.schemas';
+import { ResourceType } from '../resources.shared.core.definitions';
+/**
+ * Registry-level guardrail for the composition `onParentCreate` lifecycle:
+ * a composition relationship that OPTS IN to eager seeding
+ * (`childOperations.lifecycle.onParentCreate.enabled = true`) must actually be
+ * seedable — the child creatable with nothing but its parent FK (its CREATE-DTO
+ * defaults fill the rest), OR an `onParentCreate.initialData.override` must
+ * supply the non-defaulted fields.
+ *
+ * ## Why `onParentCreate` is OPT-IN (not mandatory for every composition)
+ *
+ * `RelationshipNature.COMPOSITION` means the part **dies with** its whole and
+ * cannot exist independently — it does NOT mean the part is always created WITH
+ * the whole. Those two axes are orthogonal (DDD): an org's `preferences` row is
+ * an always-present part (eager), while a todo's `checklist items` are an
+ * on-demand part (still composition — they die with the todo — but created as
+ * needed). Forcing every composition to eager-seed would fabricate rows for
+ * on-demand children. So eager seeding is declared per relationship via
+ * `onParentCreate.enabled`, and this guard validates only the ADOPTERS.
+ *
+ * ## Fail-closed (safe by construction)
+ *
+ * The guard fires only when a relationship enabled `onParentCreate` but the child
+ * cannot be seeded (not default-materializable AND no override) — a genuine
+ * misconfiguration whose runtime seed would silently no-op. That is a boot-time
+ * `throw`, not a warning. Because it targets only enabled adopters (a small,
+ * deliberately-chosen set), it never crash-loops on the dozens of on-demand
+ * compositions that legitimately do not seed.
+ *
+ * The probe itself is wrapped so an exotic child schema `buildCreateRequestDto`
+ * cannot shape skips silently (fail-open on the probe), never blocking startup.
+ * Pure and side-effect free.
+ */
+/** Structural subset of a resource configuration this validator needs. */
+export interface CompositionSeedabilityResourceInput {
+    resourceIdentifier: ResourceType;
+    mainSchema: z.ZodTypeAny;
+    resourceRelationships: {
+        parentRelationships: ResourceRelationship[];
+    };
+}
+export interface CompositionSeedabilityViolation {
+    childResourceType: ResourceType;
+    parentResourceType: ResourceType;
+    foreignKeyField: string;
+    /** Required, non-defaulted CREATE-DTO fields the default seed cannot supply. */
+    missingFields: string[];
+    message: string;
+}
+/**
+ * Validate that every composition relationship which opted into
+ * `onParentCreate.enabled` is actually seedable (default-materializable from its
+ * CREATE DTO + FK, or carries an override). Returns the list of violations
+ * (empty when clean); the caller throws on any (fail-closed).
+ *
+ * @param resourceConfigurations - the registry's `resourceConfigurations` map
+ *   (`resourceType → configuration`). Each entry is the CHILD in its
+ *   `parentRelationships`, so `mainSchema` is exactly the schema to probe.
+ */
+export declare function validateCompositionSeedability(resourceConfigurations: Record<string, CompositionSeedabilityResourceInput>): CompositionSeedabilityViolation[];
+//# sourceMappingURL=composition-seedability.validation.d.ts.map

package/dist/esm/resources/utils/composition-seedability.validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition-seedability.validation.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/composition-seedability.validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,oBAAoB,EAErB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAGpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,mCAAmC;IAClD,kBAAkB,EAAE,YAAY,CAAC;IACjC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC;IACzB,qBAAqB,EAAE;QACrB,mBAAmB,EAAE,oBAAoB,EAAE,CAAC;KAC7C,CAAC;CACH;AAED,MAAM,WAAW,+BAA+B;IAC9C,iBAAiB,EAAE,YAAY,CAAC;IAChC,kBAAkB,EAAE,YAAY,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,mCAAmC,CAAC,GAC1E,+BAA+B,EAAE,CAoEnC"}

package/dist/esm/resources/utils/composition-seedability.validation.js

@@ -0,0 +1,75 @@
+import { RelationshipNature, } from '../resources.shared.schemas.js';
+import { buildCreateRequestDto } from '../resources-config.shared.factory.js';
+// Arbitrary 24-hex probe id for the FK slot; never persisted — only the parse
+// success/failure matters.
+const SEEDABILITY_PROBE_FK_VALUE = '000000000000000000000000';
+/**
+ * Validate that every composition relationship which opted into
+ * `onParentCreate.enabled` is actually seedable (default-materializable from its
+ * CREATE DTO + FK, or carries an override). Returns the list of violations
+ * (empty when clean); the caller throws on any (fail-closed).
+ *
+ * @param resourceConfigurations - the registry's `resourceConfigurations` map
+ *   (`resourceType → configuration`). Each entry is the CHILD in its
+ *   `parentRelationships`, so `mainSchema` is exactly the schema to probe.
+ */
+export function validateCompositionSeedability(resourceConfigurations) {
+    const violations = [];
+    for (const resource of Object.values(resourceConfigurations)) {
+        const parentRelationships = resource.resourceRelationships?.parentRelationships ?? [];
+        for (const relationship of parentRelationships) {
+            if (relationship.nature !== RelationshipNature.COMPOSITION) {
+                continue;
+            }
+            // Only an ENABLED onParentCreate is a seeding adopter that must be seedable.
+            // A composition WITHOUT it is a legitimate on-demand child (cascade-deletes
+            // with its parent, created on demand) — not this guard's concern.
+            const onParentCreate = relationship.childOperations?.lifecycle?.onParentCreate;
+            if (onParentCreate?.enabled !== true) {
+                continue;
+            }
+            const foreignKeyField = relationship.foreignKeyField;
+            if (!foreignKeyField) {
+                continue; // fail-open: an enabled seed with no FK can't be probed here
+            }
+            // An override supplies any non-defaulted field → seedable by construction.
+            const hasOverride = typeof onParentCreate.initialData?.override === 'function';
+            if (hasOverride) {
+                continue;
+            }
+            // Probe: is the child default-materializable from its CREATE DTO + the FK?
+            // buildCreateRequestDto already strips PK / SYSTEM_MANAGED / excludeFromCreate
+            // / virtual / primary-scope FKs; we inject the relationship FK explicitly to
+            // cover non-scope parent FKs that stay required.
+            let missingFields;
+            try {
+                const createDto = buildCreateRequestDto(resource.mainSchema);
+                const probe = createDto.safeParse({ [foreignKeyField]: SEEDABILITY_PROBE_FK_VALUE });
+                if (probe.success) {
+                    continue; // seedable
+                }
+                missingFields = [
+                    ...new Set(probe.error.issues
+                        .map((issue) => issue.path.map(String).join('.'))
+                        .filter((path) => path.length > 0)),
+                ];
+            }
+            catch {
+                // Fail-open — a probe edge case must never block startup or false-positive.
+                continue;
+            }
+            violations.push({
+                childResourceType: resource.resourceIdentifier,
+                parentResourceType: relationship.resourceType1,
+                foreignKeyField,
+                missingFields,
+                message: `Composition child '${resource.resourceIdentifier}' (parent '${relationship.resourceType1}') ` +
+                    `enabled onParentCreate seeding but is NOT seedable: its CREATE DTO requires non-defaulted ` +
+                    `field(s) [${missingFields.join(', ')}] and no onParentCreate.initialData.override is declared. ` +
+                    `The seed would fail (and be swallowed) at runtime. Add field defaults / an override, or drop onParentCreate.enabled.`,
+            });
+        }
+    }
+    return violations;
+}
+//# sourceMappingURL=composition-seedability.validation.js.map

package/dist/esm/resources/utils/composition-seedability.validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition-seedability.validation.js","sourceRoot":"","sources":["../../../../../src/resources/utils/composition-seedability.validation.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAqD3E,8EAA8E;AAC9E,2BAA2B;AAC3B,MAAM,0BAA0B,GAAG,0BAA0B,CAAC;AAE9D;;;;;;;;;GASG;AACH,MAAM,UAAU,8BAA8B,CAC5C,sBAA2E;IAE3E,MAAM,UAAU,GAAsC,EAAE,CAAC;IAEzD,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAAC,EAAE,CAAC;QAC7D,MAAM,mBAAmB,GAAG,QAAQ,CAAC,qBAAqB,EAAE,mBAAmB,IAAI,EAAE,CAAC;QAEtF,KAAK,MAAM,YAAY,IAAI,mBAAmB,EAAE,CAAC;YAC/C,IAAI,YAAY,CAAC,MAAM,KAAK,kBAAkB,CAAC,WAAW,EAAE,CAAC;gBAC3D,SAAS;YACX,CAAC;YAED,6EAA6E;YAC7E,4EAA4E;YAC5E,kEAAkE;YAClE,MAAM,cAAc,GAAG,YAAY,CAAC,eAAe,EAAE,SAAS,EAAE,cAAc,CAAC;YAC/E,IAAI,cAAc,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrC,SAAS;YACX,CAAC;YAED,MAAM,eAAe,GAAG,YAAY,CAAC,eAAe,CAAC;YACrD,IAAI,CAAC,eAAe,EAAE,CAAC;gBACrB,SAAS,CAAC,6DAA6D;YACzE,CAAC;YAED,2EAA2E;YAC3E,MAAM,WAAW,GAAG,OAAO,cAAc,CAAC,WAAW,EAAE,QAAQ,KAAK,UAAU,CAAC;YAC/E,IAAI,WAAW,EAAE,CAAC;gBAChB,SAAS;YACX,CAAC;YAED,2EAA2E;YAC3E,+EAA+E;YAC/E,6EAA6E;YAC7E,iDAAiD;YACjD,IAAI,aAAuB,CAAC;YAC5B,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,qBAAqB,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;gBAC7D,MAAM,KAAK,GAAG,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,eAAe,CAAC,EAAE,0BAA0B,EAAE,CAAC,CAAC;gBACrF,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;oBAClB,SAAS,CAAC,WAAW;gBACvB,CAAC;gBACD,aAAa,GAAG;oBACd,GAAG,IAAI,GAAG,CACR,KAAK,CAAC,KAAK,CAAC,MAAM;yBACf,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;yBAChD,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CACrD;iBACF,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,4EAA4E;gBAC5E,SAAS;YACX,CAAC;YAED,UAAU,CAAC,IAAI,CAAC;gBACd,iBAAiB,EAAE,QAAQ,CAAC,kBAAkB;gBAC9C,kBAAkB,EAAE,YAAY,CAAC,aAAa;gBAC9C,eAAe;gBACf,aAAa;gBACb,OAAO,EACL,sBAAsB,QAAQ,CAAC,kBAAkB,cAAc,YAAY,CAAC,aAAa,KAAK;oBAC9F,4FAA4F;oBAC5F,aAAa,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,4DAA4D;oBACjG,sHAAsH;aACzH,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC","sourcesContent":["import { z } from 'zod';\nimport {\n  ResourceRelationship,\n  RelationshipNature,\n} from '../resources.shared.schemas';\nimport { ResourceType } from '../resources.shared.core.definitions';\nimport { buildCreateRequestDto } from '../resources-config.shared.factory';\n\n/**\n * Registry-level guardrail for the composition `onParentCreate` lifecycle:\n * a composition relationship that OPTS IN to eager seeding\n * (`childOperations.lifecycle.onParentCreate.enabled = true`) must actually be\n * seedable — the child creatable with nothing but its parent FK (its CREATE-DTO\n * defaults fill the rest), OR an `onParentCreate.initialData.override` must\n * supply the non-defaulted fields.\n *\n * ## Why `onParentCreate` is OPT-IN (not mandatory for every composition)\n *\n * `RelationshipNature.COMPOSITION` means the part **dies with** its whole and\n * cannot exist independently — it does NOT mean the part is always created WITH\n * the whole. Those two axes are orthogonal (DDD): an org's `preferences` row is\n * an always-present part (eager), while a todo's `checklist items` are an\n * on-demand part (still composition — they die with the todo — but created as\n * needed). Forcing every composition to eager-seed would fabricate rows for\n * on-demand children. So eager seeding is declared per relationship via\n * `onParentCreate.enabled`, and this guard validates only the ADOPTERS.\n *\n * ## Fail-closed (safe by construction)\n *\n * The guard fires only when a relationship enabled `onParentCreate` but the child\n * cannot be seeded (not default-materializable AND no override) — a genuine\n * misconfiguration whose runtime seed would silently no-op. That is a boot-time\n * `throw`, not a warning. Because it targets only enabled adopters (a small,\n * deliberately-chosen set), it never crash-loops on the dozens of on-demand\n * compositions that legitimately do not seed.\n *\n * The probe itself is wrapped so an exotic child schema `buildCreateRequestDto`\n * cannot shape skips silently (fail-open on the probe), never blocking startup.\n * Pure and side-effect free.\n */\n\n/** Structural subset of a resource configuration this validator needs. */\nexport interface CompositionSeedabilityResourceInput {\n  resourceIdentifier: ResourceType;\n  mainSchema: z.ZodTypeAny;\n  resourceRelationships: {\n    parentRelationships: ResourceRelationship[];\n  };\n}\n\nexport interface CompositionSeedabilityViolation {\n  childResourceType: ResourceType;\n  parentResourceType: ResourceType;\n  foreignKeyField: string;\n  /** Required, non-defaulted CREATE-DTO fields the default seed cannot supply. */\n  missingFields: string[];\n  message: string;\n}\n\n// Arbitrary 24-hex probe id for the FK slot; never persisted — only the parse\n// success/failure matters.\nconst SEEDABILITY_PROBE_FK_VALUE = '000000000000000000000000';\n\n/**\n * Validate that every composition relationship which opted into\n * `onParentCreate.enabled` is actually seedable (default-materializable from its\n * CREATE DTO + FK, or carries an override). Returns the list of violations\n * (empty when clean); the caller throws on any (fail-closed).\n *\n * @param resourceConfigurations - the registry's `resourceConfigurations` map\n *   (`resourceType → configuration`). Each entry is the CHILD in its\n *   `parentRelationships`, so `mainSchema` is exactly the schema to probe.\n */\nexport function validateCompositionSeedability(\n  resourceConfigurations: Record<string, CompositionSeedabilityResourceInput>,\n): CompositionSeedabilityViolation[] {\n  const violations: CompositionSeedabilityViolation[] = [];\n\n  for (const resource of Object.values(resourceConfigurations)) {\n    const parentRelationships = resource.resourceRelationships?.parentRelationships ?? [];\n\n    for (const relationship of parentRelationships) {\n      if (relationship.nature !== RelationshipNature.COMPOSITION) {\n        continue;\n      }\n\n      // Only an ENABLED onParentCreate is a seeding adopter that must be seedable.\n      // A composition WITHOUT it is a legitimate on-demand child (cascade-deletes\n      // with its parent, created on demand) — not this guard's concern.\n      const onParentCreate = relationship.childOperations?.lifecycle?.onParentCreate;\n      if (onParentCreate?.enabled !== true) {\n        continue;\n      }\n\n      const foreignKeyField = relationship.foreignKeyField;\n      if (!foreignKeyField) {\n        continue; // fail-open: an enabled seed with no FK can't be probed here\n      }\n\n      // An override supplies any non-defaulted field → seedable by construction.\n      const hasOverride = typeof onParentCreate.initialData?.override === 'function';\n      if (hasOverride) {\n        continue;\n      }\n\n      // Probe: is the child default-materializable from its CREATE DTO + the FK?\n      // buildCreateRequestDto already strips PK / SYSTEM_MANAGED / excludeFromCreate\n      // / virtual / primary-scope FKs; we inject the relationship FK explicitly to\n      // cover non-scope parent FKs that stay required.\n      let missingFields: string[];\n      try {\n        const createDto = buildCreateRequestDto(resource.mainSchema);\n        const probe = createDto.safeParse({ [foreignKeyField]: SEEDABILITY_PROBE_FK_VALUE });\n        if (probe.success) {\n          continue; // seedable\n        }\n        missingFields = [\n          ...new Set(\n            probe.error.issues\n              .map((issue) => issue.path.map(String).join('.'))\n              .filter((path): path is string => path.length > 0),\n          ),\n        ];\n      } catch {\n        // Fail-open — a probe edge case must never block startup or false-positive.\n        continue;\n      }\n\n      violations.push({\n        childResourceType: resource.resourceIdentifier,\n        parentResourceType: relationship.resourceType1,\n        foreignKeyField,\n        missingFields,\n        message:\n          `Composition child '${resource.resourceIdentifier}' (parent '${relationship.resourceType1}') ` +\n          `enabled onParentCreate seeding but is NOT seedable: its CREATE DTO requires non-defaulted ` +\n          `field(s) [${missingFields.join(', ')}] and no onParentCreate.initialData.override is declared. ` +\n          `The seed would fail (and be swallowed) at runtime. Add field defaults / an override, or drop onParentCreate.enabled.`,\n      });\n    }\n  }\n\n  return violations;\n}\n"]}

package/dist/esm/resources/utils/context-addressed-composition-singleton.shared.utils.d.ts

@@ -0,0 +1,10 @@
+import type { ResourceConfiguration_ResourceRelationships } from '../resources-config.shared.schemas';
+import { type ResourceRelationship, type ResourceType } from '../resources.shared.schemas';
+export interface ContextAddressedCompositionSingletonRelationshipCandidate {
+    relationship: ResourceRelationship;
+    parentResourceType: ResourceType;
+    foreignKeyField: string;
+}
+export declare function isContextAddressedCompositionSingletonRelationship(relationship: ResourceRelationship): boolean;
+export declare function getContextAddressedCompositionSingletonRelationshipCandidates(resourceRelationships: ResourceConfiguration_ResourceRelationships): ContextAddressedCompositionSingletonRelationshipCandidate[];
+//# sourceMappingURL=context-addressed-composition-singleton.shared.utils.d.ts.map

package/dist/esm/resources/utils/context-addressed-composition-singleton.shared.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-addressed-composition-singleton.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/context-addressed-composition-singleton.shared.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2CAA2C,EAAE,MAAM,oCAAoC,CAAC;AACtG,OAAO,EAKL,KAAK,oBAAoB,EACzB,KAAK,YAAY,EAClB,MAAM,6BAA6B,CAAC;AAGrC,MAAM,WAAW,yDAAyD;IACxE,YAAY,EAAE,oBAAoB,CAAC;IACnC,kBAAkB,EAAE,YAAY,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,kDAAkD,CAChE,YAAY,EAAE,oBAAoB,GACjC,OAAO,CAeT;AAED,wBAAgB,6DAA6D,CAC3E,qBAAqB,EAAE,2CAA2C,GACjE,yDAAyD,EAAE,CAQ7D"}

package/dist/esm/resources/utils/context-addressed-composition-singleton.shared.utils.js

@@ -0,0 +1,25 @@
+import { RelationshipNature, ResourceRelationshipAccessScopeStrategy, ResourceRelationshipCardinality, isOneToOneCardinality, } from '../resources.shared.schemas.js';
+import { Resources_SharedUtils } from '../resources.shared.utils.js';
+export function isContextAddressedCompositionSingletonRelationship(relationship) {
+    // Context-addressed singleton mutation means a required owner context uniquely
+    // selects the child row. Optional or collection-side parents must not be
+    // promoted into this identity contract.
+    if (relationship.nature !== RelationshipNature.COMPOSITION
+        || relationship.cardinality1 !== ResourceRelationshipCardinality.ONE
+        || !isOneToOneCardinality(relationship.cardinality2)
+        || relationship.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.STANDALONE) {
+        return false;
+    }
+    const semantics = Resources_SharedUtils.getResolvedRelationshipSemantics(relationship);
+    return Boolean(semantics.persistence.foreignKey?.fieldIdentifier);
+}
+export function getContextAddressedCompositionSingletonRelationshipCandidates(resourceRelationships) {
+    return resourceRelationships.parentRelationships
+        .filter(isContextAddressedCompositionSingletonRelationship)
+        .map((relationship) => ({
+        relationship,
+        parentResourceType: relationship.resourceType1,
+        foreignKeyField: Resources_SharedUtils.getResolvedRelationshipSemantics(relationship).persistence.foreignKey.fieldIdentifier,
+    }));
+}
+//# sourceMappingURL=context-addressed-composition-singleton.shared.utils.js.map

package/dist/esm/resources/utils/context-addressed-composition-singleton.shared.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-addressed-composition-singleton.shared.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/context-addressed-composition-singleton.shared.utils.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAClB,uCAAuC,EACvC,+BAA+B,EAC/B,qBAAqB,GAGtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAQlE,MAAM,UAAU,kDAAkD,CAChE,YAAkC;IAElC,+EAA+E;IAC/E,yEAAyE;IACzE,wCAAwC;IACxC,IACE,YAAY,CAAC,MAAM,KAAK,kBAAkB,CAAC,WAAW;WACnD,YAAY,CAAC,YAAY,KAAK,+BAA+B,CAAC,GAAG;WACjE,CAAC,qBAAqB,CAAC,YAAY,CAAC,YAAY,CAAC;WACjD,YAAY,CAAC,mBAAmB,KAAK,uCAAuC,CAAC,UAAU,EAC1F,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,qBAAqB,CAAC,gCAAgC,CAAC,YAAY,CAAC,CAAC;IACvF,OAAO,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,6DAA6D,CAC3E,qBAAkE;IAElE,OAAO,qBAAqB,CAAC,mBAAmB;SAC7C,MAAM,CAAC,kDAAkD,CAAC;SAC1D,GAAG,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QACtB,YAAY;QACZ,kBAAkB,EAAE,YAAY,CAAC,aAAa;QAC9C,eAAe,EAAE,qBAAqB,CAAC,gCAAgC,CAAC,YAAY,CAAC,CAAC,WAAW,CAAC,UAAW,CAAC,eAAe;KAC9H,CAAC,CAAC,CAAC;AACR,CAAC","sourcesContent":["import type { ResourceConfiguration_ResourceRelationships } from '../resources-config.shared.schemas';\nimport {\n  RelationshipNature,\n  ResourceRelationshipAccessScopeStrategy,\n  ResourceRelationshipCardinality,\n  isOneToOneCardinality,\n  type ResourceRelationship,\n  type ResourceType,\n} from '../resources.shared.schemas';\nimport { Resources_SharedUtils } from '../resources.shared.utils';\n\nexport interface ContextAddressedCompositionSingletonRelationshipCandidate {\n  relationship: ResourceRelationship;\n  parentResourceType: ResourceType;\n  foreignKeyField: string;\n}\n\nexport function isContextAddressedCompositionSingletonRelationship(\n  relationship: ResourceRelationship,\n): boolean {\n  // Context-addressed singleton mutation means a required owner context uniquely\n  // selects the child row. Optional or collection-side parents must not be\n  // promoted into this identity contract.\n  if (\n    relationship.nature !== RelationshipNature.COMPOSITION\n    || relationship.cardinality1 !== ResourceRelationshipCardinality.ONE\n    || !isOneToOneCardinality(relationship.cardinality2)\n    || relationship.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.STANDALONE\n  ) {\n    return false;\n  }\n\n  const semantics = Resources_SharedUtils.getResolvedRelationshipSemantics(relationship);\n  return Boolean(semantics.persistence.foreignKey?.fieldIdentifier);\n}\n\nexport function getContextAddressedCompositionSingletonRelationshipCandidates(\n  resourceRelationships: ResourceConfiguration_ResourceRelationships,\n): ContextAddressedCompositionSingletonRelationshipCandidate[] {\n  return resourceRelationships.parentRelationships\n    .filter(isContextAddressedCompositionSingletonRelationship)\n    .map((relationship) => ({\n      relationship,\n      parentResourceType: relationship.resourceType1,\n      foreignKeyField: Resources_SharedUtils.getResolvedRelationshipSemantics(relationship).persistence.foreignKey!.fieldIdentifier,\n    }));\n}\n"]}