@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/resources/child-operations.shared.schemas.d.ts

@@ -11,7 +11,7 @@
  * - Labels are handled by the i18n mechanism (not configured here)
  */
 import { z } from 'zod';
-import { DataMode } from './resources-config.shared.schemas.js';
+import { DataMode } from './resources-config.shared.schemas';
 /**
  * Execution mode for lifecycle operations on children.
  * Determines whether child operations happen synchronously or asynchronously.
@@ -22,6 +22,23 @@ export declare enum ChildLifecycleMode {
     /** Asynchronous execution via queue - eventual consistency, better performance */
     LAZY = "lazy"
 }
+/**
+ * What happens to a child when its parent is deleted — the STRATEGY axis, ORTHOGONAL to
+ * `ChildLifecycleMode` (which is the sync/async TIMING axis). Kept separate deliberately: strategy
+ * (delete vs scrub-and-keep) and timing (immediate vs lazy) are independent concerns.
+ */
+export declare enum ChildLifecycleStrategy {
+    /** Hard-delete the child row — the default; today's cascade behavior. */
+    DELETE = "delete",
+    /**
+     * Impersonalize-and-retain the child: scrub its personal fields IN PLACE (per each field's
+     * `.impersonalizeWith()` treatment) and KEEP the row, flipping `retentionStatus` to RETAINED — for a
+     * retention-governed child that must survive its parent's erasure for a legal/audit obligation
+     * (GDPR Art.17(3)(b)). Requires the child to opt into `retentionPolicy` + support UPDATE_MANY.
+     * ⚠️ NOT the anonymous-user concept — reuse of that mechanism, never its name.
+     */
+    IMPERSONALIZE_AND_RETAIN = "impersonalize_and_retain"
+}
 /**
  * Nested mutation operations allowed for children via parent request.
  * This is a convenience enum for quick configuration; the full schema
@@ -35,33 +52,112 @@ export declare enum ChildNestedMutationMode {
     /** Children can be created, updated, or deleted via parent */
     FULL = "full"
 }
-export { CascadeDirection } from './resources.shared.core.definitions.js';
+export { CascadeDirection } from './resources.shared.core.definitions';
 /**
  * Configuration for lifecycle cascade when parent is deleted.
  *
- * NOTE: This is the only lifecycle operation supported at engine level.
- * For complex onUpdate/onCreate lifecycle behaviors, use custom service implementations.
+ * NOTE: `onParentDelete` (this) and `onParentCreate` (eager composition-child
+ * seeding, below) are the engine-level lifecycle operations. `onParentUpdate`
+ * is not modelled; for that, use a custom service implementation.
  */
 export declare const ChildLifecycleOnDeleteConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     mode: z.ZodDefault<z.ZodEnum<typeof ChildLifecycleMode>>;
+    strategy: z.ZodDefault<z.ZodEnum<typeof ChildLifecycleStrategy>>;
     maxDepth: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 /** Input type - what users provide (defaults are optional) */
 export type ChildLifecycleOnDeleteConfig = z.input<typeof ChildLifecycleOnDeleteConfigSchema>;
 /** Output type - what you get after parsing (all fields present) */
 export type ChildLifecycleOnDeleteConfig_Parsed = z.infer<typeof ChildLifecycleOnDeleteConfigSchema>;
 /**
- * Lifecycle configuration wrapper.
- * Currently only supports onParentDelete.
+ * Context handed to an `onParentCreate.initialData.override` function at seed
+ * time. Kept structurally-typed (no backend `ExecutionContext` import) so this
+ * `_core` shared schema stays backend-free — mirrors the `userIdsSelector`
+ * convention on `UserNotificationDefinition`. The backend seeding handler
+ * populates the concrete values at runtime.
+ */
+export interface CompositionCreateContext {
+    /** The parent row that was just created (the composition "whole"). */
+    parentObject: Record<string, unknown>;
+    /** The resource type of the parent. */
+    parentResourceType: string;
+    /** Initiator identity of the create, when request-triggered. */
+    initiatorIds: {
+        userId?: string;
+        organizationId?: string;
+        applicationId?: string;
+    };
+    /**
+     * The original create input, when the parent-create path threads it (e.g. a
+     * registration payload carrying a profile's first/last name that does not
+     * live on the parent row). Absent for pure-defaults children.
+     */
+    requestInput?: Record<string, unknown>;
+}
+/**
+ * Seed timing for `onParentCreate` — DEDICATED to the create side so it never
+ * borrows `ChildLifecycleMode`, whose `IMMEDIATE` means *atomic / in-transaction*
+ * on the `onParentDelete` cascade. The create seed runs AFTER the parent commits,
+ * so a shared enum would be a footgun (the same token would imply divergent
+ * consistency guarantees on the two hooks).
+ */
+export declare enum CompositionSeedMode {
+    /**
+     * Sync seed in the post-create hook, right after the parent row has committed —
+     * "immediately after", NOT atomic. A failed seed never rolls back the parent;
+     * an absent 1:1 child self-heals via the omit-empty-1:1 context-embed.
+     */
+    POST_COMMIT = "post_commit"
+}
+/**
+ * Configuration for eagerly SEEDING a composition child when its parent is
+ * created — the creation half of the composition lifecycle, symmetric with
+ * {@link ChildLifecycleOnDeleteConfigSchema}.
+ *
+ * Semantics: a `RelationshipNature.COMPOSITION` child is a part that co-exists
+ * with its whole. When `enabled`, the framework auto-creates the child at
+ * parent-create time from the child schema's CREATE-DTO defaults, optionally
+ * overlaid by `initialData.override(ctx)` for children whose seed data is
+ * derived (e.g. a profile's first/last name from the registration payload).
+ *
+ * The seed is written through the trusted-system-write seam
+ * (`SystemAccessBackendService.createAsSystem`), so the child resource MUST
+ * opt into `systemAccessPolicy.create` (fail-closed) — see the composition
+ * `onParentCreate` lifecycle plan.
+ */
+export declare const ChildLifecycleOnCreateConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    mode: z.ZodDefault<z.ZodEnum<typeof CompositionSeedMode>>;
+    maxDepth: z.ZodDefault<z.ZodNumber>;
+    initialData: z.ZodOptional<z.ZodObject<{
+        override: z.ZodOptional<z.ZodCustom<(ctx: CompositionCreateContext) => Record<string, unknown> | undefined, (ctx: CompositionCreateContext) => Record<string, unknown> | undefined>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Input type - what users provide (defaults are optional) */
+export type ChildLifecycleOnCreateConfig = z.input<typeof ChildLifecycleOnCreateConfigSchema>;
+/** Output type - what you get after parsing (all fields present) */
+export type ChildLifecycleOnCreateConfig_Parsed = z.infer<typeof ChildLifecycleOnCreateConfigSchema>;
+/**
+ * Lifecycle configuration wrapper: `onParentDelete` (cascade) + `onParentCreate`
+ * (eager composition-child seeding).
  */
 export declare const ChildLifecycleConfigSchema: z.ZodObject<{
     onParentDelete: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         mode: z.ZodDefault<z.ZodEnum<typeof ChildLifecycleMode>>;
+        strategy: z.ZodDefault<z.ZodEnum<typeof ChildLifecycleStrategy>>;
+        maxDepth: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    onParentCreate: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        mode: z.ZodDefault<z.ZodEnum<typeof CompositionSeedMode>>;
         maxDepth: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+        initialData: z.ZodOptional<z.ZodObject<{
+            override: z.ZodOptional<z.ZodCustom<(ctx: CompositionCreateContext) => Record<string, unknown> | undefined, (ctx: CompositionCreateContext) => Record<string, unknown> | undefined>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /** Input type - what users provide (defaults are optional) */
 export type ChildLifecycleConfig = z.input<typeof ChildLifecycleConfigSchema>;
 /** Output type - what you get after parsing (all fields present) */
@@ -90,7 +186,7 @@ export declare const ChildNestedReadConfigSchema: z.ZodObject<{
     maxItems: z.ZodOptional<z.ZodNumber>;
     sortBy: z.ZodOptional<z.ZodString>;
     maxDepth: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 /** Input type - what users provide (defaults are optional) */
 export type ChildNestedReadConfig = z.input<typeof ChildNestedReadConfigSchema>;
 /** Output type - what you get after parsing (all fields present) */
@@ -118,7 +214,7 @@ export declare const ChildNestedMutationConfigSchema: z.ZodObject<{
     allowUpdate: z.ZodDefault<z.ZodBoolean>;
     allowDelete: z.ZodDefault<z.ZodBoolean>;
     maxDepth: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 /** Input type - what users provide (defaults are optional) */
 export type ChildNestedMutationConfig = z.input<typeof ChildNestedMutationConfigSchema>;
 /** Output type - what you get after parsing (all fields present) */
@@ -134,20 +230,20 @@ export declare const ChildNestedOperationsConfigSchema: z.ZodObject<{
         maxItems: z.ZodOptional<z.ZodNumber>;
         sortBy: z.ZodOptional<z.ZodString>;
         maxDepth: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     onUpdate: z.ZodOptional<z.ZodObject<{
         allowCreate: z.ZodDefault<z.ZodBoolean>;
         allowUpdate: z.ZodDefault<z.ZodBoolean>;
         allowDelete: z.ZodDefault<z.ZodBoolean>;
         maxDepth: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+    }, z.core.$strip>>;
     onCreate: z.ZodOptional<z.ZodObject<{
         allowCreate: z.ZodDefault<z.ZodBoolean>;
         allowUpdate: z.ZodDefault<z.ZodBoolean>;
         allowDelete: z.ZodDefault<z.ZodBoolean>;
         maxDepth: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /** Input type - what users provide (defaults are optional) */
 export type ChildNestedOperationsConfig = z.input<typeof ChildNestedOperationsConfigSchema>;
 /** Output type - what you get after parsing (all fields present) */
@@ -163,9 +259,18 @@ export declare const ChildOperationsConfigSchema: z.ZodObject<{
         onParentDelete: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             mode: z.ZodDefault<z.ZodEnum<typeof ChildLifecycleMode>>;
+            strategy: z.ZodDefault<z.ZodEnum<typeof ChildLifecycleStrategy>>;
+            maxDepth: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        onParentCreate: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            mode: z.ZodDefault<z.ZodEnum<typeof CompositionSeedMode>>;
             maxDepth: z.ZodDefault<z.ZodNumber>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
+            initialData: z.ZodOptional<z.ZodObject<{
+                override: z.ZodOptional<z.ZodCustom<(ctx: CompositionCreateContext) => Record<string, unknown> | undefined, (ctx: CompositionCreateContext) => Record<string, unknown> | undefined>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     nested: z.ZodOptional<z.ZodObject<{
         onRead: z.ZodOptional<z.ZodObject<{
             dataMode: z.ZodEnum<typeof DataMode>;
@@ -174,21 +279,21 @@ export declare const ChildOperationsConfigSchema: z.ZodObject<{
             maxItems: z.ZodOptional<z.ZodNumber>;
             sortBy: z.ZodOptional<z.ZodString>;
             maxDepth: z.ZodDefault<z.ZodNumber>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip>>;
         onUpdate: z.ZodOptional<z.ZodObject<{
             allowCreate: z.ZodDefault<z.ZodBoolean>;
             allowUpdate: z.ZodDefault<z.ZodBoolean>;
             allowDelete: z.ZodDefault<z.ZodBoolean>;
             maxDepth: z.ZodDefault<z.ZodNumber>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
+        }, z.core.$strip>>;
         onCreate: z.ZodOptional<z.ZodObject<{
             allowCreate: z.ZodDefault<z.ZodBoolean>;
             allowUpdate: z.ZodDefault<z.ZodBoolean>;
             allowDelete: z.ZodDefault<z.ZodBoolean>;
             maxDepth: z.ZodDefault<z.ZodNumber>;
-        }, z.core.$strip, core.$ZodObjectExtra>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /** Input type - what users provide (defaults are optional) */
 export type ChildOperationsConfig = z.input<typeof ChildOperationsConfigSchema>;
 /** Output type - what you get after parsing (all fields present) */
@@ -231,6 +336,6 @@ export type ChildOperationsConfig_Parsed = z.infer<typeof ChildOperationsConfigS
 export declare const ResourceRelationshipDiscriminatorSchema: z.ZodObject<{
     discriminatorField: z.ZodString;
     values: z.ZodArray<z.ZodString>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type ResourceRelationshipDiscriminator = z.infer<typeof ResourceRelationshipDiscriminatorSchema>;
 //# sourceMappingURL=child-operations.shared.schemas.d.ts.map

package/dist/esm/resources/child-operations.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"child-operations.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/resources/child-operations.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAO7D;;;GAGG;AACH,oBAAY,kBAAkB;IAC5B,yEAAyE;IACzE,SAAS,cAAc;IACvB,kFAAkF;IAClF,IAAI,SAAS;CACd;AAMD;;;;GAIG;AACH,oBAAY,uBAAuB;IACjC,8CAA8C;IAC9C,WAAW,gBAAgB;IAC3B,oDAAoD;IACpD,aAAa,kBAAkB;IAC/B,8DAA8D;IAC9D,IAAI,SAAS;CACd;AAMD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAMvE;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC;;;;uCAkB7C,CAAC;AAEH,8DAA8D;AAC9D,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAC9F,oEAAoE;AACpE,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAErG;;;GAGG;AACH,eAAO,MAAM,0BAA0B;;;;;;uCAGrC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,oEAAoE;AACpE,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAMrF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B;;;;;;;uCAsDtC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,oEAAoE;AACpE,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAMvF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,+BAA+B;;;;;uCAoB1C,CAAC;AAEH,8DAA8D;AAC9D,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AACxF,oEAAoE;AACpE,MAAM,MAAM,gCAAgC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAM/F;;GAEG;AACH,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;uCAS5C,CAAC;AAEH,8DAA8D;AAC9D,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAC5F,oEAAoE;AACpE,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAMnG;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCActC,CAAC;AAGH,8DAA8D;AAC9D,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,oEAAoE;AACpE,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAMvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,uCAAuC;;;uCASlD,CAAC;AAEH,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uCAAuC,CAAC,CAAC"}
+{"version":3,"file":"child-operations.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/resources/child-operations.shared.schemas.ts"],"names":[],"mappings":"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"}

package/dist/esm/resources/child-operations.shared.schemas.js

@@ -26,6 +26,24 @@ export var ChildLifecycleMode;
     /** Asynchronous execution via queue - eventual consistency, better performance */
     ChildLifecycleMode["LAZY"] = "lazy";
 })(ChildLifecycleMode || (ChildLifecycleMode = {}));
+/**
+ * What happens to a child when its parent is deleted — the STRATEGY axis, ORTHOGONAL to
+ * `ChildLifecycleMode` (which is the sync/async TIMING axis). Kept separate deliberately: strategy
+ * (delete vs scrub-and-keep) and timing (immediate vs lazy) are independent concerns.
+ */
+export var ChildLifecycleStrategy;
+(function (ChildLifecycleStrategy) {
+    /** Hard-delete the child row — the default; today's cascade behavior. */
+    ChildLifecycleStrategy["DELETE"] = "delete";
+    /**
+     * Impersonalize-and-retain the child: scrub its personal fields IN PLACE (per each field's
+     * `.impersonalizeWith()` treatment) and KEEP the row, flipping `retentionStatus` to RETAINED — for a
+     * retention-governed child that must survive its parent's erasure for a legal/audit obligation
+     * (GDPR Art.17(3)(b)). Requires the child to opt into `retentionPolicy` + support UPDATE_MANY.
+     * ⚠️ NOT the anonymous-user concept — reuse of that mechanism, never its name.
+     */
+    ChildLifecycleStrategy["IMPERSONALIZE_AND_RETAIN"] = "impersonalize_and_retain";
+})(ChildLifecycleStrategy || (ChildLifecycleStrategy = {}));
 // =============================================================================
 // NESTED MUTATION MODE (Convenience Enum)
 // =============================================================================
@@ -53,33 +71,151 @@ export { CascadeDirection } from './resources.shared.core.definitions.js';
 /**
  * Configuration for lifecycle cascade when parent is deleted.
  *
- * NOTE: This is the only lifecycle operation supported at engine level.
- * For complex onUpdate/onCreate lifecycle behaviors, use custom service implementations.
+ * NOTE: `onParentDelete` (this) and `onParentCreate` (eager composition-child
+ * seeding, below) are the engine-level lifecycle operations. `onParentUpdate`
+ * is not modelled; for that, use a custom service implementation.
  */
 export const ChildLifecycleOnDeleteConfigSchema = z.object({
-    /** Whether children should be deleted when parent is deleted */
+    /** Whether children are handled when the parent is deleted (the cascade fires — see `strategy` for what it does). */
     enabled: z.boolean().default(false),
     /**
-     * Execution mode:
-     * - IMMEDIATE: Sync deletion in same transaction (consistency guaranteed)
-     * - LAZY: Async deletion via queue (eventual consistency, better performance)
+     * Execution TIMING (orthogonal to `strategy`):
+     * - IMMEDIATE: Sync in same transaction (consistency guaranteed)
+     * - LAZY: Async via queue (eventual consistency, better performance)
      */
     mode: z.enum(ChildLifecycleMode).default(ChildLifecycleMode.IMMEDIATE),
+    /**
+     * What to do with the children — the STRATEGY axis (orthogonal to `mode`):
+     * - DELETE (default): hard-delete the child rows (today's behavior)
+     * - IMPERSONALIZE_AND_RETAIN: scrub-and-keep (retention-governed children — see `ChildLifecycleStrategy`)
+     * ⚠️ v1: `IMPERSONALIZE_AND_RETAIN` is supported only with `mode: IMMEDIATE` (async impersonalization is pending).
+     */
+    strategy: z.enum(ChildLifecycleStrategy).default(ChildLifecycleStrategy.DELETE),
     /**
      * Maximum depth for cascading delete (prevents infinite loops).
      * - 1: Delete direct children only
      * - 2: Delete children and grandchildren
+     *
+     * ⚠️ STRATEGY-DEPENDENT. This budget governs the DELETE cascade's descent. Under
+     * `IMPERSONALIZE_AND_RETAIN` it has no effect on THIS edge: v1 scrubs the direct children only and
+     * never recurses (a retained child is not deleted, so its own children keep a valid parent and are
+     * left alone by design — the whole-subtree scrub belongs to direct subject-erasure, not to a
+     * parent-delete cascade). It still matters on a DELETE edge ABOVE a retain edge: that is the budget
+     * that lets the cascade reach the retain edge at all, and each edge reached applies its OWN strategy.
      * @default 1
      */
     maxDepth: z.number().int().min(1).max(3).default(1),
 });
 /**
- * Lifecycle configuration wrapper.
- * Currently only supports onParentDelete.
+ * Seed timing for `onParentCreate` — DEDICATED to the create side so it never
+ * borrows `ChildLifecycleMode`, whose `IMMEDIATE` means *atomic / in-transaction*
+ * on the `onParentDelete` cascade. The create seed runs AFTER the parent commits,
+ * so a shared enum would be a footgun (the same token would imply divergent
+ * consistency guarantees on the two hooks).
+ */
+export var CompositionSeedMode;
+(function (CompositionSeedMode) {
+    /**
+     * Sync seed in the post-create hook, right after the parent row has committed —
+     * "immediately after", NOT atomic. A failed seed never rolls back the parent;
+     * an absent 1:1 child self-heals via the omit-empty-1:1 context-embed.
+     */
+    CompositionSeedMode["POST_COMMIT"] = "post_commit";
+    // ── Reserved modes: DELIBERATELY not built (this is a design record, not a TODO) ──
+    //
+    // `POST_COMMIT` is the ONLY implemented mode, and it is what every current
+    // eager-seed adopter needs — they are all 1-per-parent settings/state/profile
+    // rows for which post-commit sync + omit-empty-1:1 self-heal is exactly right.
+    // The two modes below are documented here for the record but are intentionally
+    // NOT shipped, and they are comments (not enum values) ON PURPOSE: the type then
+    // cannot offer an unimplemented mode, so no app developer can select one and hit
+    // a runtime surprise.
+    //
+    // Why reserved rather than built (framework-mindset: a mode with no consumer
+    // carries no semantic weight — building it is speculative generality):
+    //
+    //  • ATOMIC — seed INSIDE the parent's transaction (via the nested-`onCreate`
+    //    path) so an absent child can never be observed. NOT built because (a) no
+    //    adopter needs atomicity (the post-commit window is already covered by the
+    //    omit-empty-1:1 read), and (b) the only available implementation route
+    //    BYPASSES Guard-1 (`systemAccessPolicy.create` fail-closed) + Guard-4
+    //    (privileged-write audit) — so shipping it now would add a mode that is
+    //    LESS safe than the default, for zero users. The interesting part (keeping
+    //    the guards while inside the txn) is unsolved and should be the design work
+    //    WHEN a concrete child genuinely requires atomic seeding.
+    //
+    //  • DEFERRED — async seed via a queue, for high-volume children. NOT built
+    //    because no current composition is high-volume (settings rows are one per
+    //    parent). Add it when a real high-volume seed appears, shaped by that need.
+    //
+    // Rule of thumb: implement a new mode only when the FIRST concrete consumer
+    // arrives, so the design is driven by the real requirement rather than a guess.
+})(CompositionSeedMode || (CompositionSeedMode = {}));
+/**
+ * Configuration for eagerly SEEDING a composition child when its parent is
+ * created — the creation half of the composition lifecycle, symmetric with
+ * {@link ChildLifecycleOnDeleteConfigSchema}.
+ *
+ * Semantics: a `RelationshipNature.COMPOSITION` child is a part that co-exists
+ * with its whole. When `enabled`, the framework auto-creates the child at
+ * parent-create time from the child schema's CREATE-DTO defaults, optionally
+ * overlaid by `initialData.override(ctx)` for children whose seed data is
+ * derived (e.g. a profile's first/last name from the registration payload).
+ *
+ * The seed is written through the trusted-system-write seam
+ * (`SystemAccessBackendService.createAsSystem`), so the child resource MUST
+ * opt into `systemAccessPolicy.create` (fail-closed) — see the composition
+ * `onParentCreate` lifecycle plan.
+ */
+export const ChildLifecycleOnCreateConfigSchema = z.object({
+    /** Whether the child is eagerly seeded when the parent is created. */
+    enabled: z.boolean().default(false),
+    /**
+     * Seed timing — see {@link CompositionSeedMode}. `POST_COMMIT` (the only
+     * implemented mode) seeds synchronously AFTER the parent commits; it is NOT
+     * atomic. Deliberately a dedicated enum, not `ChildLifecycleMode` — on the
+     * delete cascade `IMMEDIATE` is atomic/in-transaction, which would be a false
+     * promise here.
+     */
+    mode: z.enum(CompositionSeedMode).default(CompositionSeedMode.POST_COMMIT),
+    /**
+     * Maximum recursion depth when a seeded child is itself a composition parent
+     * (prevents unbounded parent → child → grandchild seeding). The seed re-enters
+     * the create path, so this MUST be honoured by the runtime re-entrancy guard.
+     * @default 1
+     */
+    maxDepth: z.number().int().min(1).max(3).default(1),
+    /**
+     * Optional seed-data strategy. The base seed is always the child's CREATE-DTO
+     * defaults; `override(ctx)` supplies or overlays fields that cannot be
+     * defaulted (e.g. a profile's first/last name derived from
+     * {@link CompositionCreateContext.requestInput}). It returns a partial child
+     * CREATE input, merged over the defaults before the system-create.
+     *
+     * Returning `undefined` DECLINES the seed for this particular parent-create:
+     * the runtime skips the child cleanly (no create attempt, no swallowed
+     * validation failure). This is how an input-derived child opts out when the
+     * required input is absent — e.g. `USER_PROFILES` is seeded from the
+     * registration/SSO/SCIM name payload, but the org-admin INVITE create carries
+     * no name (the invitee supplies it later at acceptance), so the override
+     * returns `undefined` there and the invitation-acceptance flow owns that write.
+     *
+     * Typed via `z.custom` because a runtime function is not JSON-serializable —
+     * mirrors the `userIdsSelector` convention on `UserNotificationDefinition`.
+     */
+    initialData: z.object({
+        override: z.custom((val) => typeof val === 'function').optional(),
+    }).optional(),
+});
+/**
+ * Lifecycle configuration wrapper: `onParentDelete` (cascade) + `onParentCreate`
+ * (eager composition-child seeding).
  */
 export const ChildLifecycleConfigSchema = z.object({
     /** Configuration for deleting children when parent is deleted */
     onParentDelete: ChildLifecycleOnDeleteConfigSchema.optional(),
+    /** Configuration for eagerly seeding a composition child when parent is created */
+    onParentCreate: ChildLifecycleOnCreateConfigSchema.optional(),
 });
 // =============================================================================
 // NESTED READ CONFIGURATION SCHEMA
@@ -216,8 +352,8 @@ export const ChildNestedOperationsConfigSchema = z.object({
 export const ChildOperationsConfigSchema = z.object({
     // --- LIFECYCLE ---
     /**
-     * Automatic side effects on children when parent operations occur.
-     * Currently only onParentDelete is supported.
+     * Automatic side effects on children when parent operations occur:
+     * `onParentDelete` (cascade) and `onParentCreate` (eager composition-child seeding).
      */
     lifecycle: ChildLifecycleConfigSchema.optional(),
     // --- NESTED OPERATIONS ---
@@ -277,4 +413,4 @@ export const ResourceRelationshipDiscriminatorSchema = z.object({
 // =============================================================================
 // FRONTEND DISPLAY CONFIGURATION (on Relationship) — v3 re-exports
 // =============================================================================
-//# sourceMappingURL=child-operations.shared.schemas.js.map
+//# sourceMappingURL=child-operations.shared.schemas.js.map

package/dist/esm/resources/child-operations.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"child-operations.shared.schemas.js","sourceRoot":"","sources":["../../../src/resources/child-operations.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAG7D,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAN,IAAY,kBAKX;AALD,WAAY,kBAAkB;IAC5B,yEAAyE;IACzE,6CAAuB,CAAA;IACvB,kFAAkF;IAClF,mCAAa,CAAA;AACf,CAAC,EALW,kBAAkB,KAAlB,kBAAkB,QAK7B;AAED,gFAAgF;AAChF,0CAA0C;AAC1C,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,CAAN,IAAY,uBAOX;AAPD,WAAY,uBAAuB;IACjC,8CAA8C;IAC9C,sDAA2B,CAAA;IAC3B,oDAAoD;IACpD,0DAA+B,CAAA;IAC/B,8DAA8D;IAC9D,wCAAa,CAAA;AACf,CAAC,EAPW,uBAAuB,KAAvB,uBAAuB,QAOlC;AAED,gFAAgF;AAChF,qDAAqD;AACrD,gFAAgF;AAEhF,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAEvE,gFAAgF;AAChF,kCAAkC;AAClC,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,CAAC,MAAM,CAAC;IACzD,gEAAgE;IAChE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAEnC;;;;OAIG;IACH,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,SAAS,CAAC;IAEtE;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;CACpD,CAAC,CAAC;AAOH;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,iEAAiE;IACjE,cAAc,EAAE,kCAAkC,CAAC,QAAQ,EAAE;CAC9D,CAAC,CAAC;AAOH,gFAAgF;AAChF,mCAAmC;AACnC,gFAAgF;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD;;;;;;;;;OASG;IACH,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;IAE1B;;;;;;;;OAQG;IACH,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAEzC;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAExD;;;;OAIG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAE5C;;;;;OAKG;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE7B;;;;OAIG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;CACpD,CAAC,CAAC;AAOH,gFAAgF;AAChF,uCAAuC;AACvC,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,wDAAwD;IACxD,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAEvC,iEAAiE;IACjE,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAEvC;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAEvC;;;;OAIG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;CACpD,CAAC,CAAC;AAOH,gFAAgF;AAChF,oCAAoC;AACpC,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAC,MAAM,CAAC;IACxD,kDAAkD;IAClD,MAAM,EAAE,2BAA2B,CAAC,QAAQ,EAAE;IAE9C,sDAAsD;IACtD,QAAQ,EAAE,+BAA+B,CAAC,QAAQ,EAAE;IAEpD,4DAA4D;IAC5D,QAAQ,EAAE,+BAA+B,CAAC,QAAQ,EAAE;CACrD,CAAC,CAAC;AAOH,gFAAgF;AAChF,yCAAyC;AACzC,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,oBAAoB;IACpB;;;OAGG;IACH,SAAS,EAAE,0BAA0B,CAAC,QAAQ,EAAE;IAEhD,4BAA4B;IAC5B;;;OAGG;IACH,MAAM,EAAE,iCAAiC,CAAC,QAAQ,EAAE;CACrD,CAAC,CAAC;AAQH,gFAAgF;AAChF,wDAAwD;AACxD,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,MAAM,uCAAuC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9D,sEAAsE;IACtE,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE;IAE9B;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CACnC,CAAC,CAAC;AAIH,gFAAgF;AAChF,mEAAmE;AACnE,gFAAgF"}
+{"version":3,"file":"child-operations.shared.schemas.js","sourceRoot":"","sources":["../../../../src/resources/child-operations.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Child Operations Shared Schemas\n *\n * Defines how child resources are handled in parent operations.\n * Consolidates lifecycle (cascade delete) and nested (aggregated DTOs) configurations\n * onto the ResourceRelationship level.\n *\n * Design Principles:\n * - \"childOperations\" handles BACKEND processing of child resources\n * - \"display\" handles FRONTEND presentation (separate from childOperations)\n * - Labels are handled by the i18n mechanism (not configured here)\n */\n\nimport { z } from 'zod';\nimport { DataMode } from './resources-config.shared.schemas';\nimport { CoreResourceOperation, CascadeDirection } from './resources.shared.core.definitions';\n\n// =============================================================================\n// LIFECYCLE ENUMS\n// =============================================================================\n\n/**\n * Execution mode for lifecycle operations on children.\n * Determines whether child operations happen synchronously or asynchronously.\n */\nexport enum ChildLifecycleMode {\n  /** Synchronous execution in same transaction - consistency guaranteed */\n  IMMEDIATE = 'immediate',\n  /** Asynchronous execution via queue - eventual consistency, better performance */\n  LAZY = 'lazy',\n}\n\n/**\n * What happens to a child when its parent is deleted — the STRATEGY axis, ORTHOGONAL to\n * `ChildLifecycleMode` (which is the sync/async TIMING axis). Kept separate deliberately: strategy\n * (delete vs scrub-and-keep) and timing (immediate vs lazy) are independent concerns.\n */\nexport enum ChildLifecycleStrategy {\n  /** Hard-delete the child row — the default; today's cascade behavior. */\n  DELETE = 'delete',\n  /**\n   * Impersonalize-and-retain the child: scrub its personal fields IN PLACE (per each field's\n   * `.impersonalizeWith()` treatment) and KEEP the row, flipping `retentionStatus` to RETAINED — for a\n   * retention-governed child that must survive its parent's erasure for a legal/audit obligation\n   * (GDPR Art.17(3)(b)). Requires the child to opt into `retentionPolicy` + support UPDATE_MANY.\n   * ⚠️ NOT the anonymous-user concept — reuse of that mechanism, never its name.\n   */\n  IMPERSONALIZE_AND_RETAIN = 'impersonalize_and_retain',\n}\n\n// =============================================================================\n// NESTED MUTATION MODE (Convenience Enum)\n// =============================================================================\n\n/**\n * Nested mutation operations allowed for children via parent request.\n * This is a convenience enum for quick configuration; the full schema\n * uses separate boolean flags (allowCreate, allowUpdate, allowDelete).\n */\nexport enum ChildNestedMutationMode {\n  /** Children can only be created via parent */\n  CREATE_ONLY = 'create_only',\n  /** Children can be created or updated via parent */\n  CREATE_UPDATE = 'create_update',\n  /** Children can be created, updated, or deleted via parent */\n  FULL = 'full',\n}\n\n// =============================================================================\n// DISPLAY ENUMS (Relationship display configuration)\n// =============================================================================\n\nexport { CascadeDirection } from './resources.shared.core.definitions';\n\n// =============================================================================\n// LIFECYCLE CONFIGURATION SCHEMAS\n// =============================================================================\n\n/**\n * Configuration for lifecycle cascade when parent is deleted.\n *\n * NOTE: `onParentDelete` (this) and `onParentCreate` (eager composition-child\n * seeding, below) are the engine-level lifecycle operations. `onParentUpdate`\n * is not modelled; for that, use a custom service implementation.\n */\nexport const ChildLifecycleOnDeleteConfigSchema = z.object({\n  /** Whether children are handled when the parent is deleted (the cascade fires — see `strategy` for what it does). */\n  enabled: z.boolean().default(false),\n\n  /**\n   * Execution TIMING (orthogonal to `strategy`):\n   * - IMMEDIATE: Sync in same transaction (consistency guaranteed)\n   * - LAZY: Async via queue (eventual consistency, better performance)\n   */\n  mode: z.enum(ChildLifecycleMode).default(ChildLifecycleMode.IMMEDIATE),\n\n  /**\n   * What to do with the children — the STRATEGY axis (orthogonal to `mode`):\n   * - DELETE (default): hard-delete the child rows (today's behavior)\n   * - IMPERSONALIZE_AND_RETAIN: scrub-and-keep (retention-governed children — see `ChildLifecycleStrategy`)\n   * ⚠️ v1: `IMPERSONALIZE_AND_RETAIN` is supported only with `mode: IMMEDIATE` (async impersonalization is pending).\n   */\n  strategy: z.enum(ChildLifecycleStrategy).default(ChildLifecycleStrategy.DELETE),\n\n  /**\n   * Maximum depth for cascading delete (prevents infinite loops).\n   * - 1: Delete direct children only\n   * - 2: Delete children and grandchildren\n   *\n   * ⚠️ STRATEGY-DEPENDENT. This budget governs the DELETE cascade's descent. Under\n   * `IMPERSONALIZE_AND_RETAIN` it has no effect on THIS edge: v1 scrubs the direct children only and\n   * never recurses (a retained child is not deleted, so its own children keep a valid parent and are\n   * left alone by design — the whole-subtree scrub belongs to direct subject-erasure, not to a\n   * parent-delete cascade). It still matters on a DELETE edge ABOVE a retain edge: that is the budget\n   * that lets the cascade reach the retain edge at all, and each edge reached applies its OWN strategy.\n   * @default 1\n   */\n  maxDepth: z.number().int().min(1).max(3).default(1),\n});\n\n/** Input type - what users provide (defaults are optional) */\nexport type ChildLifecycleOnDeleteConfig = z.input<typeof ChildLifecycleOnDeleteConfigSchema>;\n/** Output type - what you get after parsing (all fields present) */\nexport type ChildLifecycleOnDeleteConfig_Parsed = z.infer<typeof ChildLifecycleOnDeleteConfigSchema>;\n\n/**\n * Context handed to an `onParentCreate.initialData.override` function at seed\n * time. Kept structurally-typed (no backend `ExecutionContext` import) so this\n * `_core` shared schema stays backend-free — mirrors the `userIdsSelector`\n * convention on `UserNotificationDefinition`. The backend seeding handler\n * populates the concrete values at runtime.\n */\nexport interface CompositionCreateContext {\n  /** The parent row that was just created (the composition \"whole\"). */\n  parentObject: Record<string, unknown>;\n  /** The resource type of the parent. */\n  parentResourceType: string;\n  /** Initiator identity of the create, when request-triggered. */\n  initiatorIds: { userId?: string; organizationId?: string; applicationId?: string };\n  /**\n   * The original create input, when the parent-create path threads it (e.g. a\n   * registration payload carrying a profile's first/last name that does not\n   * live on the parent row). Absent for pure-defaults children.\n   */\n  requestInput?: Record<string, unknown>;\n}\n\n/**\n * Seed timing for `onParentCreate` — DEDICATED to the create side so it never\n * borrows `ChildLifecycleMode`, whose `IMMEDIATE` means *atomic / in-transaction*\n * on the `onParentDelete` cascade. The create seed runs AFTER the parent commits,\n * so a shared enum would be a footgun (the same token would imply divergent\n * consistency guarantees on the two hooks).\n */\nexport enum CompositionSeedMode {\n  /**\n   * Sync seed in the post-create hook, right after the parent row has committed —\n   * \"immediately after\", NOT atomic. A failed seed never rolls back the parent;\n   * an absent 1:1 child self-heals via the omit-empty-1:1 context-embed.\n   */\n  POST_COMMIT = 'post_commit',\n\n  // ── Reserved modes: DELIBERATELY not built (this is a design record, not a TODO) ──\n  //\n  // `POST_COMMIT` is the ONLY implemented mode, and it is what every current\n  // eager-seed adopter needs — they are all 1-per-parent settings/state/profile\n  // rows for which post-commit sync + omit-empty-1:1 self-heal is exactly right.\n  // The two modes below are documented here for the record but are intentionally\n  // NOT shipped, and they are comments (not enum values) ON PURPOSE: the type then\n  // cannot offer an unimplemented mode, so no app developer can select one and hit\n  // a runtime surprise.\n  //\n  // Why reserved rather than built (framework-mindset: a mode with no consumer\n  // carries no semantic weight — building it is speculative generality):\n  //\n  //  • ATOMIC — seed INSIDE the parent's transaction (via the nested-`onCreate`\n  //    path) so an absent child can never be observed. NOT built because (a) no\n  //    adopter needs atomicity (the post-commit window is already covered by the\n  //    omit-empty-1:1 read), and (b) the only available implementation route\n  //    BYPASSES Guard-1 (`systemAccessPolicy.create` fail-closed) + Guard-4\n  //    (privileged-write audit) — so shipping it now would add a mode that is\n  //    LESS safe than the default, for zero users. The interesting part (keeping\n  //    the guards while inside the txn) is unsolved and should be the design work\n  //    WHEN a concrete child genuinely requires atomic seeding.\n  //\n  //  • DEFERRED — async seed via a queue, for high-volume children. NOT built\n  //    because no current composition is high-volume (settings rows are one per\n  //    parent). Add it when a real high-volume seed appears, shaped by that need.\n  //\n  // Rule of thumb: implement a new mode only when the FIRST concrete consumer\n  // arrives, so the design is driven by the real requirement rather than a guess.\n}\n\n/**\n * Configuration for eagerly SEEDING a composition child when its parent is\n * created — the creation half of the composition lifecycle, symmetric with\n * {@link ChildLifecycleOnDeleteConfigSchema}.\n *\n * Semantics: a `RelationshipNature.COMPOSITION` child is a part that co-exists\n * with its whole. When `enabled`, the framework auto-creates the child at\n * parent-create time from the child schema's CREATE-DTO defaults, optionally\n * overlaid by `initialData.override(ctx)` for children whose seed data is\n * derived (e.g. a profile's first/last name from the registration payload).\n *\n * The seed is written through the trusted-system-write seam\n * (`SystemAccessBackendService.createAsSystem`), so the child resource MUST\n * opt into `systemAccessPolicy.create` (fail-closed) — see the composition\n * `onParentCreate` lifecycle plan.\n */\nexport const ChildLifecycleOnCreateConfigSchema = z.object({\n  /** Whether the child is eagerly seeded when the parent is created. */\n  enabled: z.boolean().default(false),\n\n  /**\n   * Seed timing — see {@link CompositionSeedMode}. `POST_COMMIT` (the only\n   * implemented mode) seeds synchronously AFTER the parent commits; it is NOT\n   * atomic. Deliberately a dedicated enum, not `ChildLifecycleMode` — on the\n   * delete cascade `IMMEDIATE` is atomic/in-transaction, which would be a false\n   * promise here.\n   */\n  mode: z.enum(CompositionSeedMode).default(CompositionSeedMode.POST_COMMIT),\n\n  /**\n   * Maximum recursion depth when a seeded child is itself a composition parent\n   * (prevents unbounded parent → child → grandchild seeding). The seed re-enters\n   * the create path, so this MUST be honoured by the runtime re-entrancy guard.\n   * @default 1\n   */\n  maxDepth: z.number().int().min(1).max(3).default(1),\n\n  /**\n   * Optional seed-data strategy. The base seed is always the child's CREATE-DTO\n   * defaults; `override(ctx)` supplies or overlays fields that cannot be\n   * defaulted (e.g. a profile's first/last name derived from\n   * {@link CompositionCreateContext.requestInput}). It returns a partial child\n   * CREATE input, merged over the defaults before the system-create.\n   *\n   * Returning `undefined` DECLINES the seed for this particular parent-create:\n   * the runtime skips the child cleanly (no create attempt, no swallowed\n   * validation failure). This is how an input-derived child opts out when the\n   * required input is absent — e.g. `USER_PROFILES` is seeded from the\n   * registration/SSO/SCIM name payload, but the org-admin INVITE create carries\n   * no name (the invitee supplies it later at acceptance), so the override\n   * returns `undefined` there and the invitation-acceptance flow owns that write.\n   *\n   * Typed via `z.custom` because a runtime function is not JSON-serializable —\n   * mirrors the `userIdsSelector` convention on `UserNotificationDefinition`.\n   */\n  initialData: z.object({\n    override: z.custom<(ctx: CompositionCreateContext) => Record<string, unknown> | undefined>(\n      (val) => typeof val === 'function',\n    ).optional(),\n  }).optional(),\n});\n\n/** Input type - what users provide (defaults are optional) */\nexport type ChildLifecycleOnCreateConfig = z.input<typeof ChildLifecycleOnCreateConfigSchema>;\n/** Output type - what you get after parsing (all fields present) */\nexport type ChildLifecycleOnCreateConfig_Parsed = z.infer<typeof ChildLifecycleOnCreateConfigSchema>;\n\n/**\n * Lifecycle configuration wrapper: `onParentDelete` (cascade) + `onParentCreate`\n * (eager composition-child seeding).\n */\nexport const ChildLifecycleConfigSchema = z.object({\n  /** Configuration for deleting children when parent is deleted */\n  onParentDelete: ChildLifecycleOnDeleteConfigSchema.optional(),\n  /** Configuration for eagerly seeding a composition child when parent is created */\n  onParentCreate: ChildLifecycleOnCreateConfigSchema.optional(),\n});\n\n/** Input type - what users provide (defaults are optional) */\nexport type ChildLifecycleConfig = z.input<typeof ChildLifecycleConfigSchema>;\n/** Output type - what you get after parsing (all fields present) */\nexport type ChildLifecycleConfig_Parsed = z.infer<typeof ChildLifecycleConfigSchema>;\n\n// =============================================================================\n// NESTED READ CONFIGURATION SCHEMA\n// =============================================================================\n\n/**\n * Configuration for nested read operations (related resources in response).\n *\n * IMPORTANT: Uses existing DataMode enum (RAW, SUMMARY, CONTEXT).\n * If this config is not present, related resources are NOT included in responses.\n *\n * WORKS FOR ALL CARDINALITIES:\n * - 1:N (Parent → Children): Returns array of children\n * - 1:1 (Parent ↔ Child): Returns single child object\n * - N:N (Resource ↔ Resource): Returns array via junction table\n * - N:1 (Child → Parent): Returns single parent object (less common, use isSummaryField populate)\n *\n * RELATIONSHIP TO DataMode REQUEST PARAM:\n * - Client can request DataMode.CONTEXT to get full context (parents + children via contextPolicy)\n * - nested.onRead provides a RELATIONSHIP-LEVEL default for always including related resources\n * - They work together: nested.onRead config + DataMode request param\n */\nexport const ChildNestedReadConfigSchema = z.object({\n  /**\n   * Data mode for related resources in READ response.\n   * Uses existing DataMode enum: RAW, SUMMARY, CONTEXT\n   *\n   * - RAW: All stored fields, no population of their FKs\n   * - SUMMARY: Summary fields, populate their isSummaryField({ populate: true }) FKs\n   * - CONTEXT: Full context with their contextPolicy applied (can include grandchildren)\n   *\n   * @required - presence of this config enables nested resources\n   */\n  dataMode: z.enum(DataMode),\n\n  /**\n   * Enable nested resources in LIST/SUMMARY responses.\n   * By default, LIST returns parent summaries only (no nested resources).\n   * Set to true to include nested resources in LIST responses.\n   *\n   * ⚠️ Performance consideration: Enabling this on high-volume lists can be expensive.\n   *\n   * @default false\n   */\n  enabledOnList: z.boolean().default(false),\n\n  /**\n   * Data mode for resources when included in LIST responses.\n   * Only applies when enabledOnList is true.\n   * Typically SUMMARY for performance.\n   *\n   * @default SUMMARY\n   */\n  listDataMode: z.enum(DataMode).default(DataMode.SUMMARY),\n\n  /**\n   * Maximum number of items to include.\n   * - For 1:N and N:N: Limits array size\n   * - For 1:1: Ignored (always returns single object or null)\n   */\n  maxItems: z.number().int().min(0).optional(),\n\n  /**\n   * Sort order for related resources.\n   * Uses standard sort syntax: 'fieldName' or '-fieldName' for descending.\n   * - For 1:N and N:N: Applied to array\n   * - For 1:1: Ignored\n   */\n  sortBy: z.string().optional(),\n\n  /**\n   * Maximum depth for nested traversal (prevents infinite loops).\n   * 0 = no nesting, 1 = direct related only, 2 = related + their related\n   * @default 1\n   */\n  maxDepth: z.number().int().min(0).max(3).default(1),\n});\n\n/** Input type - what users provide (defaults are optional) */\nexport type ChildNestedReadConfig = z.input<typeof ChildNestedReadConfigSchema>;\n/** Output type - what you get after parsing (all fields present) */\nexport type ChildNestedReadConfig_Parsed = z.infer<typeof ChildNestedReadConfigSchema>;\n\n// =============================================================================\n// NESTED MUTATION CONFIGURATION SCHEMA\n// =============================================================================\n\n/**\n * Configuration for nested mutation operations (create/update/delete children via parent).\n *\n * When enabled, the parent's request DTO will include a field for child data:\n * - 1:N relationships: Array field (e.g., `tasks: [...]`)\n * - 1:1 relationships: Object field (e.g., `profile: {...}`)\n *\n * Processing logic:\n * - Children without _id are treated as creates (if allowCreate)\n * - Children with _id are treated as updates (if allowUpdate)\n * - Children listed in `_{field}ToDelete` array are deleted (if allowDelete)\n *\n * Nested field names follow ResourcesConfigNamingUtils conventions:\n * - taskId → task (1:1) or tasks (1:N)\n * - createdByUserId → createdByUser\n *\n * Created/updated children are ALWAYS included in the response.\n */\nexport const ChildNestedMutationConfigSchema = z.object({\n  /** Whether children can be created in parent request */\n  allowCreate: z.boolean().default(false),\n\n  /** Whether existing children can be updated in parent request */\n  allowUpdate: z.boolean().default(false),\n\n  /**\n   * Whether children can be deleted in parent request.\n   * Use separate field `_{nestedField}ToDelete: string[]` to specify IDs to delete.\n   * Example: `_tasksToDelete: ['task-123', 'task-456']`\n   */\n  allowDelete: z.boolean().default(false),\n\n  /**\n   * Maximum depth for nested mutations (prevents infinite loops).\n   * 1 = direct children only, 2 = children can have grandchildren\n   * @default 1\n   */\n  maxDepth: z.number().int().min(0).max(2).default(1),\n});\n\n/** Input type - what users provide (defaults are optional) */\nexport type ChildNestedMutationConfig = z.input<typeof ChildNestedMutationConfigSchema>;\n/** Output type - what you get after parsing (all fields present) */\nexport type ChildNestedMutationConfig_Parsed = z.infer<typeof ChildNestedMutationConfigSchema>;\n\n// =============================================================================\n// NESTED OPERATIONS COMBINED SCHEMA\n// =============================================================================\n\n/**\n * Combined nested operations configuration.\n */\nexport const ChildNestedOperationsConfigSchema = z.object({\n  /** How children appear in parent READ response */\n  onRead: ChildNestedReadConfigSchema.optional(),\n\n  /** What mutations allowed in parent UPDATE request */\n  onUpdate: ChildNestedMutationConfigSchema.optional(),\n\n  /** What child creations allowed in parent CREATE request */\n  onCreate: ChildNestedMutationConfigSchema.optional(),\n});\n\n/** Input type - what users provide (defaults are optional) */\nexport type ChildNestedOperationsConfig = z.input<typeof ChildNestedOperationsConfigSchema>;\n/** Output type - what you get after parsing (all fields present) */\nexport type ChildNestedOperationsConfig_Parsed = z.infer<typeof ChildNestedOperationsConfigSchema>;\n\n// =============================================================================\n// UNIFIED CHILD OPERATIONS CONFIGURATION\n// =============================================================================\n\n/**\n * Complete child operations configuration for a resource relationship.\n * Handles BACKEND concerns: lifecycle cascade and nested DTO aggregation.\n *\n * Frontend display is configured separately via `display` on the relationship.\n */\nexport const ChildOperationsConfigSchema = z.object({\n  // --- LIFECYCLE ---\n  /**\n   * Automatic side effects on children when parent operations occur:\n   * `onParentDelete` (cascade) and `onParentCreate` (eager composition-child seeding).\n   */\n  lifecycle: ChildLifecycleConfigSchema.optional(),\n\n  // --- NESTED OPERATIONS ---\n  /**\n   * Configuration for including children in parent DTOs.\n   * Enables aggregated CRUD operations (create/update parent with children).\n   */\n  nested: ChildNestedOperationsConfigSchema.optional(),\n});\n\n\n/** Input type - what users provide (defaults are optional) */\nexport type ChildOperationsConfig = z.input<typeof ChildOperationsConfigSchema>;\n/** Output type - what you get after parsing (all fields present) */\nexport type ChildOperationsConfig_Parsed = z.infer<typeof ChildOperationsConfigSchema>;\n\n// =============================================================================\n// RELATIONSHIP DISCRIMINATOR (for Discriminated Unions)\n// =============================================================================\n\n/**\n * Static discriminator filter for conditional relationships.\n *\n * When set on a relationship, the relationship only applies when the PARENT\n * resource's `discriminatorField` has a value matching one of the specified `values`.\n *\n * This is the \"simple case\" of conditional relationships — a pure field+values match.\n * For more complex logic (cross-field checks, computed conditions), use the\n * `condition` function on `ResourceRelationship` instead.\n *\n * ## Runtime Evaluation\n *\n * All runtime evaluation sites now delegate to the shared\n * `Resources_SharedUtils.isRelationshipActiveForParent()` helper, which uses\n * `String()` coercion on the field value before matching because this schema\n * defines `values` as `string[]` but the field may be a number or enum at\n * runtime.\n *\n * ## Design Note\n *\n * The discriminator is evaluated against the PARENT resource, never the child.\n * It answers the question: \"Given this parent's current state, should this\n * parent→child relationship be active?\" For example, a TODO with\n * `recurringType = 'ONE_TIME'` should NOT show recurring occurrences.\n *\n * @example Recurring todos have occurrences, one-time todos don't:\n * ```typescript\n * createResourcesRelationship(TODOS, TODOS_RECURRING_OCCURRENCES, ONE, MANY, {\n *   discriminator: {\n *     discriminatorField: 'recurringType',\n *     values: ['RECURRING']\n *   }\n * })\n * ```\n */\nexport const ResourceRelationshipDiscriminatorSchema = z.object({\n  /** The discriminator field name on the parent resource to evaluate */\n  discriminatorField: z.string(),\n\n  /**\n   * Values for which this relationship is active.\n   * Comparison uses `String()` coercion: `values.includes(String(parentResource[discriminatorField]))`.\n   */\n  values: z.array(z.string()).min(1),\n});\n\nexport type ResourceRelationshipDiscriminator = z.infer<typeof ResourceRelationshipDiscriminatorSchema>;\n\n// =============================================================================\n// FRONTEND DISPLAY CONFIGURATION (on Relationship) — v3 re-exports\n// =============================================================================\n\n\n"]}

package/dist/esm/resources/context-policy.shared.schemas.d.ts

@@ -7,7 +7,7 @@
  * Design Principle: "Decorators describe structure. Relationships describe traversal."
  */
 import { z } from 'zod';
-import { CoreResourceOperation } from './resources.shared.core.definitions.js';
+import { CoreResourceOperation } from './resources.shared.core.definitions';
 /**
  * Object mode for relationship data in context.
  * Determines what level of detail is fetched for related resources.
@@ -142,7 +142,7 @@ export declare const ContextPolicy_OperationOverrideSchema: z.ZodObject<{
     depth: z.ZodOptional<z.ZodNumber>;
     objectMode: z.ZodOptional<z.ZodEnum<typeof ContextPolicy_ObjectMode>>;
     accessRightsMode: z.ZodOptional<z.ZodEnum<typeof ContextPolicy_AccessRightsMode>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+}, z.core.$strip>;
 export type ContextPolicy_OperationOverrideType = z.infer<typeof ContextPolicy_OperationOverrideSchema>;
 export declare const RelationshipContextPolicySchema: z.ZodObject<{
     enabled: z.ZodOptional<z.ZodBoolean>;
@@ -154,6 +154,6 @@ export declare const RelationshipContextPolicySchema: z.ZodObject<{
         depth: z.ZodOptional<z.ZodNumber>;
         objectMode: z.ZodOptional<z.ZodEnum<typeof ContextPolicy_ObjectMode>>;
         accessRightsMode: z.ZodOptional<z.ZodEnum<typeof ContextPolicy_AccessRightsMode>>;
-    }, z.core.$strip, core.$ZodObjectExtra>>>;
-}, z.core.$strip, core.$ZodObjectExtra>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 //# sourceMappingURL=context-policy.shared.schemas.d.ts.map

package/dist/esm/resources/context-policy.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-policy.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/resources/context-policy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAM5E;;;GAGG;AACH,oBAAY,wBAAwB;IAClC,oDAAoD;IACpD,IAAI,SAAS;IACb,iEAAiE;IACjE,OAAO,YAAY;IACnB,wDAAwD;IACxD,OAAO,YAAY;CACpB;AAED;;;GAGG;AACH,oBAAY,8BAA8B;IACxC,2DAA2D;IAC3D,GAAG,QAAQ;IACX,qDAAqD;IACrD,aAAa,kBAAkB;IAC/B,sDAAsD;IACtD,cAAc,mBAAmB;CAClC;AAMD;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,8BAA8B,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,wBAAwB,CAAC;IAEtC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,8BAA8B,CAAC;IAElD;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC,MAAM,CACjC,qBAAqB,EACrB,+BAA+B,CAChC,CAAC,CAAC;CACJ;AAMD;;;GAGG;AACH,eAAO,MAAM,mCAAmC,EAAE,QAAQ,CACxD,IAAI,CAAC,yBAAyB,EAAE,oBAAoB,CAAC,CAMtD,CAAC;AAMF,eAAO,MAAM,qCAAqC;;;;;uCAKhD,CAAC;AACH,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAExG,eAAO,MAAM,+BAA+B;;;;;;;;;;;uCAS1C,CAAC"}
+{"version":3,"file":"context-policy.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/resources/context-policy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAM5E;;;GAGG;AACH,oBAAY,wBAAwB;IAClC,oDAAoD;IACpD,IAAI,SAAS;IACb,iEAAiE;IACjE,OAAO,YAAY;IACnB,wDAAwD;IACxD,OAAO,YAAY;CACpB;AAED;;;GAGG;AACH,oBAAY,8BAA8B;IACxC,2DAA2D;IAC3D,GAAG,QAAQ;IACX,qDAAqD;IACrD,aAAa,kBAAkB;IAC/B,sDAAsD;IACtD,cAAc,mBAAmB;CAClC;AAMD;;;GAGG;AACH,MAAM,WAAW,+BAA+B;IAC9C,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,8BAA8B,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,wBAAwB,CAAC;IAEtC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,8BAA8B,CAAC;IAElD;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC,MAAM,CACjC,qBAAqB,EACrB,+BAA+B,CAChC,CAAC,CAAC;CACJ;AAMD;;;GAGG;AACH,eAAO,MAAM,mCAAmC,EAAE,QAAQ,CACxD,IAAI,CAAC,yBAAyB,EAAE,oBAAoB,CAAC,CAMtD,CAAC;AAMF,eAAO,MAAM,qCAAqC;;;;;iBAKhD,CAAC;AACH,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAExG,eAAO,MAAM,+BAA+B;;;;;;;;;;;iBAS1C,CAAC"}

package/dist/esm/resources/context-policy.shared.schemas.js

@@ -66,4 +66,4 @@ export const RelationshipContextPolicySchema = z.object({
     accessRightsMode: z.enum(ContextPolicy_AccessRightsMode).optional(),
     operationOverrides: z.partialRecord(z.enum(CoreResourceOperation), ContextPolicy_OperationOverrideSchema).optional(),
 });
-//# sourceMappingURL=context-policy.shared.schemas.js.map
+//# sourceMappingURL=context-policy.shared.schemas.js.map

package/dist/esm/resources/context-policy.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-policy.shared.schemas.js","sourceRoot":"","sources":["../../../src/resources/context-policy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAE5E,gFAAgF;AAChF,QAAQ;AACR,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAN,IAAY,wBAOX;AAPD,WAAY,wBAAwB;IAClC,oDAAoD;IACpD,yCAAa,CAAA;IACb,iEAAiE;IACjE,+CAAmB,CAAA;IACnB,wDAAwD;IACxD,+CAAmB,CAAA;AACrB,CAAC,EAPW,wBAAwB,KAAxB,wBAAwB,QAOnC;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,8BAOX;AAPD,WAAY,8BAA8B;IACxC,2DAA2D;IAC3D,6CAAW,CAAA;IACX,qDAAqD;IACrD,iEAA+B,CAAA;IAC/B,sDAAsD;IACtD,mEAAiC,CAAA;AACnC,CAAC,EAPW,8BAA8B,KAA9B,8BAA8B,QAOzC;AAmHD,gFAAgF;AAChF,WAAW;AACX,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAE5C;IACF,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,CAAC;IACR,UAAU,EAAE,wBAAwB,CAAC,OAAO;IAC5C,gBAAgB,EAAE,8BAA8B,CAAC,aAAa;CAC/D,CAAC;AAEF,gFAAgF;AAChF,+BAA+B;AAC/B,gFAAgF;AAEhF,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5D,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChD,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,QAAQ,EAAE;IACvD,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC,QAAQ,EAAE;CACpE,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChD,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,QAAQ,EAAE;IACvD,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC,QAAQ,EAAE;IACnE,kBAAkB,EAAE,CAAC,CAAC,aAAa,CACjC,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,EAC7B,qCAAqC,CACtC,CAAC,QAAQ,EAAE;CACb,CAAC,CAAC"}
+{"version":3,"file":"context-policy.shared.schemas.js","sourceRoot":"","sources":["../../../../src/resources/context-policy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAE5E,gFAAgF;AAChF,QAAQ;AACR,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAN,IAAY,wBAOX;AAPD,WAAY,wBAAwB;IAClC,oDAAoD;IACpD,yCAAa,CAAA;IACb,iEAAiE;IACjE,+CAAmB,CAAA;IACnB,wDAAwD;IACxD,+CAAmB,CAAA;AACrB,CAAC,EAPW,wBAAwB,KAAxB,wBAAwB,QAOnC;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,8BAOX;AAPD,WAAY,8BAA8B;IACxC,2DAA2D;IAC3D,6CAAW,CAAA;IACX,qDAAqD;IACrD,iEAA+B,CAAA;IAC/B,sDAAsD;IACtD,mEAAiC,CAAA;AACnC,CAAC,EAPW,8BAA8B,KAA9B,8BAA8B,QAOzC;AAmHD,gFAAgF;AAChF,WAAW;AACX,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAE5C;IACF,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,CAAC;IACR,UAAU,EAAE,wBAAwB,CAAC,OAAO;IAC5C,gBAAgB,EAAE,8BAA8B,CAAC,aAAa;CAC/D,CAAC;AAEF,gFAAgF;AAChF,+BAA+B;AAC/B,gFAAgF;AAEhF,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5D,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChD,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,QAAQ,EAAE;IACvD,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC,QAAQ,EAAE;CACpE,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAChD,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,QAAQ,EAAE;IACvD,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC,QAAQ,EAAE;IACnE,kBAAkB,EAAE,CAAC,CAAC,aAAa,CACjC,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,EAC7B,qCAAqC,CACtC,CAAC,QAAQ,EAAE;CACb,CAAC,CAAC","sourcesContent":["/**\n * Context Policy Shared Schemas\n * \n * Defines how related resources are fetched when traversing relationships.\n * Used by ResourceContextBackendService to determine fetch behavior.\n * \n * Design Principle: \"Decorators describe structure. Relationships describe traversal.\"\n */\n\nimport { z } from 'zod';\nimport { CoreResourceOperation } from './resources.shared.core.definitions';\n\n// =============================================================================\n// ENUMS\n// =============================================================================\n\n/**\n * Object mode for relationship data in context.\n * Determines what level of detail is fetched for related resources.\n */\nexport enum ContextPolicy_ObjectMode {\n  /** Include complete resource object (all fields) */\n  FULL = 'FULL',\n  /** Include only fields marked with isSummaryField() decorator */\n  SUMMARY = 'SUMMARY',\n  /** Include only the ID reference - no database fetch */\n  ID_ONLY = 'ID_ONLY',\n}\n\n/**\n * Access rights mode for context relationships.\n * Determines how user permissions filter related resources.\n */\nexport enum ContextPolicy_AccessRightsMode {\n  /** Include all resources regardless of user permissions */\n  ALL = 'ALL',\n  /** Only include resources user has read access to */\n  USER_FILTERED = 'USER_FILTERED',\n  /** Only include resources user has write access to */\n  WRITE_FILTERED = 'WRITE_FILTERED',\n}\n\n// =============================================================================\n// TYPES\n// =============================================================================\n\n/**\n * Per-operation context policy override.\n * Allows different context behavior for READ vs LIST vs CREATE, etc.\n */\nexport interface ContextPolicy_OperationOverride {\n  /** Override enabled state for this operation */\n  enabled?: boolean;\n  /** Override depth for this operation */\n  depth?: number;\n  /** Override object mode for this operation */\n  objectMode?: ContextPolicy_ObjectMode;\n  /** Override access rights mode for this operation */\n  accessRightsMode?: ContextPolicy_AccessRightsMode;\n}\n\n/**\n * Context policy for a relationship.\n * Defines how related resources are fetched when traversing this relationship.\n * \n * @example Basic usage - uses all defaults\n * ```typescript\n * contextPolicy: {}  // enabled=true, depth=1, objectMode=SUMMARY\n * ```\n * \n * @example Disable context for security (credentials, secrets, API keys)\n * ```typescript\n * contextPolicy: { enabled: false }\n * ```\n * \n * @example Full data on READ, summary on LIST (1:1 profile/preferences)\n * ```typescript\n * contextPolicy: {\n *   objectMode: ContextPolicy_ObjectMode.SUMMARY,\n *   operationOverrides: {\n *     [CoreResourceOperation.READ]: { objectMode: ContextPolicy_ObjectMode.FULL }\n *   }\n * }\n * ```\n * \n * @example Disable on LIST/SEARCH for performance (high-cardinality relationships)\n * ```typescript\n * contextPolicy: {\n *   operationOverrides: {\n *     [CoreResourceOperation.LIST]: { enabled: false },\n *     [CoreResourceOperation.SEARCH]: { enabled: false }\n *   }\n * }\n * ```\n * \n * @example Self-referencing relationships (prevent infinite loops)\n * ```typescript\n * contextPolicy: {\n *   objectMode: ContextPolicy_ObjectMode.ID_ONLY,\n *   depth: 1\n * }\n * ```\n */\nexport interface RelationshipContextPolicy {\n  /**\n   * Whether context fetching is enabled for this relationship.\n   * Set to false to completely skip fetching related resources.\n   * @default true\n   */\n  enabled?: boolean;\n\n  /**\n   * Depth of traversal through this relationship.\n   * - 0: Don't fetch (same as enabled: false)\n   * - 1: Fetch direct relationship only (default)\n   * - 2: Fetch related resource AND its direct relationships\n   * - 3: Maximum allowed depth (use with caution)\n   * \n   * Higher depths have exponential performance implications.\n   * @default 1\n   */\n  depth?: number;\n\n  /**\n   * What data to include from the related resource.\n   * - FULL: Complete resource object (all fields)\n   * - SUMMARY: Only fields marked with isSummaryField() decorator\n   * - ID_ONLY: Just the ID reference, no actual fetch\n   * @default SUMMARY\n   */\n  objectMode?: ContextPolicy_ObjectMode;\n\n  /**\n   * Access rights filtering for the related resource.\n   * Controls whether user permissions affect what's returned.\n   * @default USER_FILTERED\n   */\n  accessRightsMode?: ContextPolicy_AccessRightsMode;\n\n  /**\n   * Per-operation overrides.\n   * Allows different context behavior for specific operations.\n   * Keys are limited to `CoreResourceOperation` values.\n   * \n   * Common patterns:\n   * - Disable on LIST/SEARCH for performance\n   * - Use FULL on READ for detail views\n   * - Disable on CREATE for validation-only\n   */\n  operationOverrides?: Partial<Record<\n    CoreResourceOperation,\n    ContextPolicy_OperationOverride\n  >>;\n}\n\n// =============================================================================\n// DEFAULTS\n// =============================================================================\n\n/**\n * Default context policy when not specified on relationship.\n * Conservative defaults optimized for common use cases.\n */\nexport const DEFAULT_RELATIONSHIP_CONTEXT_POLICY: Required<\n  Omit<RelationshipContextPolicy, 'operationOverrides'>\n> = {\n  enabled: true,\n  depth: 1,\n  objectMode: ContextPolicy_ObjectMode.SUMMARY,\n  accessRightsMode: ContextPolicy_AccessRightsMode.USER_FILTERED,\n};\n\n// =============================================================================\n// ZOD SCHEMAS (for validation)\n// =============================================================================\n\nexport const ContextPolicy_OperationOverrideSchema = z.object({\n  enabled: z.boolean().optional(),\n  depth: z.number().int().min(0).max(3).optional(),\n  objectMode: z.enum(ContextPolicy_ObjectMode).optional(),\n  accessRightsMode: z.enum(ContextPolicy_AccessRightsMode).optional(),\n});\nexport type ContextPolicy_OperationOverrideType = z.infer<typeof ContextPolicy_OperationOverrideSchema>;\n\nexport const RelationshipContextPolicySchema = z.object({\n  enabled: z.boolean().optional(),\n  depth: z.number().int().min(0).max(3).optional(),\n  objectMode: z.enum(ContextPolicy_ObjectMode).optional(),\n  accessRightsMode: z.enum(ContextPolicy_AccessRightsMode).optional(),\n  operationOverrides: z.partialRecord(\n    z.enum(CoreResourceOperation),\n    ContextPolicy_OperationOverrideSchema\n  ).optional(),\n});\n"]}