@wildo-ai/saas-models 1.1.8 → 1.1.10

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":"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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, scrub-and-keep, or refuse) 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   * Refuse the parent's delete while any child row still names it: the RESTRICT posture. Nothing is\n   * torn down. The children are not the parent's to remove, so whoever deletes the parent must first\n   * move or remove them (an org-unit subtree, the financial records a billing account maps back to\n   * its provider customer).\n   *\n   * The service tier enforces it BEFORE the parent delete writes anything, on a single DELETE and on\n   * DELETE_MANY alike, and refuses with 409 `RESOURCE_HAS_DEPENDENTS`, whose context names every\n   * blocking edge. A DELETE cascade whose depth budget reaches such an edge refuses in that frame the\n   * same way, so a cascade cannot delete a row that a direct delete of it would be refused.\n   *\n   * `mode` and `maxDepth` do not apply: there is no teardown to time or to recurse into. Existence is\n   * probed with one repository READ on the edge's foreign key, so the child must declare READ; boot\n   * refuses the edge otherwise (`validateCompositionCascadeDeletability`). A retention-governed child is\n   * probed a SECOND time for impersonalized-and-retained rows, which the first read cannot see: they still\n   * name the parent, so they still block, and the refusal names the edge without the hidden row's id (#1168). On a self-edge (a tree) the probe\n   * instead scans the FK children with the framework's internal scan read and excludes every row the same\n   * operation deletes, the deleted row itself included; READ stays the only operation boot requires.\n   *\n   * The check reads the DELETED resource's own edges. A cascade that removes rows through the raw\n   * repository consults their edges only when its depth budget reaches them, which is why a tenant\n   * purge (ORGANIZATIONS → ORGANIZATION_UNITS at `maxDepth: 1`) still removes a whole org chart. A\n   * subject erasure scrubs its subject in place rather than deleting it, so it meets the refusal only\n   * below a dependent it deletes, where it refuses like a cascade frame\n   * (`SubjectErasureDisposition.RESTRICTED_BY_DECLARATION`). On a self-edge, rows deleted by the same\n   * operation are not counted as blocking children, so a subtree deleted together is admitted.\n   */\n  REFUSE_WHILE_CHILDREN_EXIST = 'refuse_while_children_exist',\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  /**\n   * Whether this edge governs the parent's delete: the cascade fires, or, for\n   * `REFUSE_WHILE_CHILDREN_EXIST`, the delete is refused while children exist. See `strategy`.\n   */\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: hard-delete the child rows\n   * - IMPERSONALIZE_AND_RETAIN: scrub-and-keep (retention-governed children — see `ChildLifecycleStrategy`)\n   * - REFUSE_WHILE_CHILDREN_EXIST: tears nothing down — the parent's delete is refused while children\n   *   exist, and `mode` / `maxDepth` do not apply.\n   *\n   * ⚠️ v1: `IMPERSONALIZE_AND_RETAIN` is supported only with `mode: IMMEDIATE` (async impersonalization\n   * is pending).\n   *\n   * ## OPTIONAL WITH NO SCHEMA DEFAULT, deliberately (#1279)\n   *\n   * This carried `.default(ChildLifecycleStrategy.DELETE)` until 2026-09-17, and that default is what\n   * produced #1279. A schema default makes SILENCE and a DECISION indistinguishable after parse: every\n   * edge came back carrying `strategy: 'delete'` as an own property whether or not a human had ever\n   * considered the question, and no consumer could tell the two apart.\n   *\n   * That mattered because this field has TWO readers asking DIFFERENT questions:\n   *\n   * | reader | question | what absence means |\n   * |---|---|---|\n   * | the delete cascade | the parent row is being DELETED — what happens to the children? | DELETE, and that is the right default: a composition child whose parent is gone has no owner |\n   * | subject erasure | the subject demanded ERASURE — the parent row is SCRUBBED AND KEPT, so what happens to the children? | **nothing — the author has not answered**, and the child's own `retentionPolicy` is the declaration that speaks to erasure |\n   *\n   * With the default in place the erasure read a manufactured `DELETE` as the author's erasure answer\n   * and deleted rows whose own resource declared `retentionPolicy: RETAIN_AND_IMPERSONALIZE` — a\n   * declaration the config factory refuses unless it is paired with a `dataSubjectPolicy`, i.e. the most\n   * deliberate statement in the privacy surface. Measured 2026-09-17 across `engine/`, `platform/` and\n   * `examples/`: of 79 authored `onParentDelete` blocks, 57 were silent, and **28 of 28** edges where a\n   * retain-declaring resource was nevertheless erased by DELETE reached that outcome through this\n   * default. Not one author had written `strategy: DELETE` for such a resource.\n   *\n   * So absence is now INFORMATION, and each reader supplies its own meaning:\n   * - a cascade reader calls {@link resolveChildLifecycleTeardownStrategy}, the ONE named source of the\n   *   `DELETE`-on-absence rule, instead of re-deriving `?? DELETE` at each site;\n   * - the erasure reader (`classifySubjectErasureDisposition`) reads this field RAW, so it can tell an\n   *   authored `DELETE` — which genuinely contradicts a retain policy and is refused — from silence,\n   *   which simply lets the child's `retentionPolicy` answer.\n   *\n   * Do NOT reintroduce a default here to \"simplify\" a call site. The default is not missing; it has\n   * been moved to the reader that is entitled to it.\n   */\n  strategy: z.enum(ChildLifecycleStrategy).optional(),\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 * The teardown strategy a DELETE CASCADE must apply to an edge — the ONE named source of the\n * \"silence means DELETE\" rule (#1279).\n *\n * `strategy` deliberately carries no schema default (see its JSDoc above), so absence reaches every\n * consumer intact. For the cascade, absence resolving to `DELETE` is correct and always was: a\n * composition child whose parent row is being removed has no owner left, and hard-delete is what the\n * engine has always done. This function exists so that rule lives in ONE place instead of being\n * re-derived as `?? ChildLifecycleStrategy.DELETE` at each cascade site — five such sites existed when\n * the default was removed, and a sixth that forgot would have silently changed a cascade's behaviour.\n *\n * ⚠️ **Subject erasure must NOT call this.** An erasure does not delete the parent; it scrubs the row\n * and keeps it, so \"the parent is gone\" — the premise that makes `DELETE` the right answer here — is\n * false there. `classifySubjectErasureDisposition` reads `strategy` raw precisely so it can distinguish\n * an authored `DELETE` from an unanswered question, which is the whole of #1279.\n *\n * @param onParentDelete - the authored teardown block, or undefined when the edge declares none.\n * @returns the strategy the cascade applies, or undefined when the edge declares no teardown at all\n *          (a caller with no block has nothing to tear down, and must not be handed a `DELETE`).\n */\nexport function resolveChildLifecycleTeardownStrategy(\n  onParentDelete: { readonly strategy?: ChildLifecycleStrategy } | undefined | null,\n): ChildLifecycleStrategy | undefined {\n  if (!onParentDelete) return undefined;\n  return onParentDelete.strategy ?? ChildLifecycleStrategy.DELETE;\n}\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"]}
+{"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, scrub-and-keep, or refuse) 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   * Refuse the parent's delete while any child row still names it: the RESTRICT posture. Nothing is\n   * torn down. The children are not the parent's to remove, so whoever deletes the parent must first\n   * move or remove them (an org-unit subtree, the financial records a billing account maps back to\n   * its provider customer).\n   *\n   * The service tier enforces it BEFORE the parent delete writes anything, on a single DELETE and on\n   * DELETE_MANY alike, and refuses with 409 `RESOURCE_HAS_DEPENDENTS`, whose context names every\n   * blocking edge. A DELETE cascade whose depth budget reaches such an edge refuses in that frame the\n   * same way, so a cascade cannot delete a row that a direct delete of it would be refused.\n   *\n   * `mode` and `maxDepth` do not apply: there is no teardown to time or to recurse into. Existence is\n   * probed with one repository READ on the edge's foreign key, so the child must declare READ; boot\n   * refuses the edge otherwise (`validateCompositionCascadeDeletability`). A retention-governed child is\n   * probed a SECOND time for impersonalized-and-retained rows, which the first read cannot see: they still\n   * name the parent, so they still block, and the refusal names the edge without the hidden row's id (#1168). On a self-edge (a tree) the probe\n   * instead scans the FK children with the framework's internal scan read and excludes every row the same\n   * operation deletes, the deleted row itself included; READ stays the only operation boot requires.\n   *\n   * The check reads the DELETED resource's own edges. A cascade that removes rows through the raw\n   * repository consults their edges only when its depth budget reaches them, which is why a tenant\n   * purge (ORGANIZATIONS → ORGANIZATION_UNITS at `maxDepth: 1`) still removes a whole org chart. A\n   * subject erasure scrubs its subject in place rather than deleting it, so it meets the refusal only\n   * below a dependent it deletes, where it refuses like a cascade frame\n   * (`SubjectErasureDisposition.RESTRICTED_BY_DECLARATION`). On a self-edge, rows deleted by the same\n   * operation are not counted as blocking children, so a subtree deleted together is admitted.\n   */\n  REFUSE_WHILE_CHILDREN_EXIST = 'refuse_while_children_exist',\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  /**\n   * Whether this edge governs the parent's delete: the cascade fires, or, for\n   * `REFUSE_WHILE_CHILDREN_EXIST`, the delete is refused while children exist. See `strategy`.\n   */\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: hard-delete the child rows\n   * - IMPERSONALIZE_AND_RETAIN: scrub-and-keep (retention-governed children — see `ChildLifecycleStrategy`)\n   * - REFUSE_WHILE_CHILDREN_EXIST: tears nothing down — the parent's delete is refused while children\n   *   exist, and `mode` / `maxDepth` do not apply.\n   *\n   * ⚠️ v1: `IMPERSONALIZE_AND_RETAIN` is supported only with `mode: IMMEDIATE` (async impersonalization\n   * is pending).\n   *\n   * ## OPTIONAL WITH NO SCHEMA DEFAULT, deliberately (#1279)\n   *\n   * This carried `.default(ChildLifecycleStrategy.DELETE)` until 2026-09-17, and that default is what\n   * produced #1279. A schema default makes SILENCE and a DECISION indistinguishable after parse: every\n   * edge came back carrying `strategy: 'delete'` as an own property whether or not a human had ever\n   * considered the question, and no consumer could tell the two apart.\n   *\n   * That mattered because this field has TWO readers asking DIFFERENT questions:\n   *\n   * | reader | question | what absence means |\n   * |---|---|---|\n   * | the delete cascade | the parent row is being DELETED — what happens to the children? | DELETE, and that is the right default: a composition child whose parent is gone has no owner |\n   * | subject erasure | the subject demanded ERASURE — the parent row is SCRUBBED AND KEPT, so what happens to the children? | **nothing — the author has not answered**, and the child's own `retentionPolicy` is the declaration that speaks to erasure |\n   *\n   * With the default in place the erasure read a manufactured `DELETE` as the author's erasure answer\n   * and deleted rows whose own resource declared `retentionPolicy: RETAIN_AND_IMPERSONALIZE` — a\n   * declaration the config factory refuses unless it is paired with a `dataSubjectPolicy`, i.e. the most\n   * deliberate statement in the privacy surface. Measured 2026-09-17 across `engine/`, `platform/` and\n   * `examples/`: of 79 authored `onParentDelete` blocks, 57 were silent, and **28 of 28** edges where a\n   * retain-declaring resource was nevertheless erased by DELETE reached that outcome through this\n   * default. Not one author had written `strategy: DELETE` for such a resource.\n   *\n   * So absence is now INFORMATION, and each reader supplies its own meaning:\n   * - a cascade reader calls {@link resolveChildLifecycleTeardownStrategy}, the ONE named source of the\n   *   `DELETE`-on-absence rule, instead of re-deriving `?? DELETE` at each site;\n   * - the erasure reader (`classifySubjectErasureDisposition`) reads this field RAW, so it can tell an\n   *   authored `DELETE` — which genuinely contradicts a retain policy and is refused — from silence,\n   *   which simply lets the child's `retentionPolicy` answer.\n   *\n   * Do NOT reintroduce a default here to \"simplify\" a call site. The default is not missing; it has\n   * been moved to the reader that is entitled to it.\n   */\n  strategy: z.enum(ChildLifecycleStrategy).optional(),\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 * The teardown strategy a DELETE CASCADE must apply to an edge — the ONE named source of the\n * \"silence means DELETE\" rule (#1279).\n *\n * `strategy` deliberately carries no schema default (see its JSDoc above), so absence reaches every\n * consumer intact. For the cascade, absence resolving to `DELETE` is correct and always was: a\n * composition child whose parent row is being removed has no owner left, and hard-delete is what the\n * engine has always done. This function exists so that rule lives in ONE place instead of being\n * re-derived as `?? ChildLifecycleStrategy.DELETE` at each cascade site — five such sites existed when\n * the default was removed, and a sixth that forgot would have silently changed a cascade's behaviour.\n *\n * ⚠️ **Subject erasure must NOT call this.** An erasure does not delete the parent; it scrubs the row\n * and keeps it, so \"the parent is gone\" — the premise that makes `DELETE` the right answer here — is\n * false there. `classifySubjectErasureDisposition` reads `strategy` raw precisely so it can distinguish\n * an authored `DELETE` from an unanswered question, which is the whole of #1279.\n *\n * @param onParentDelete - the authored teardown block, or undefined when the edge declares none.\n * @returns the strategy the cascade applies, or undefined when the edge declares no teardown at all\n *          (a caller with no block has nothing to tear down, and must not be handed a `DELETE`).\n */\nexport function resolveChildLifecycleTeardownStrategy(\n  onParentDelete: { readonly strategy?: ChildLifecycleStrategy } | undefined | null,\n): ChildLifecycleStrategy | undefined {\n  if (!onParentDelete) return undefined;\n  return onParentDelete.strategy ?? ChildLifecycleStrategy.DELETE;\n}\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/collection-query-parameters.shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection-query-parameters.shared.d.ts","sourceRoot":"","sources":["../../../../src/resources/collection-query-parameters.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B;IACtC,2BAA2B;;IAE3B,0DAA0D;;IAE1D,gFAAgF;;IAEhF,kDAAkD;;IAElD,iFAAiF;;CAEzE,CAAC"}
+{"version":3,"file":"collection-query-parameters.shared.d.ts","sourceRoot":"","sources":["../../../src/resources/collection-query-parameters.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B;IACtC,2BAA2B;;IAE3B,0DAA0D;;IAE1D,gFAAgF;;IAEhF,kDAAkD;;IAElD,iFAAiF;;CAEzE,CAAC"}

package/dist/esm/resources/collection-query-parameters.shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"collection-query-parameters.shared.js","sourceRoot":"","sources":["../../../../src/resources/collection-query-parameters.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,2BAA2B;IAC3B,IAAI,EAAE,MAAM;IACZ,0DAA0D;IAC1D,KAAK,EAAE,OAAO;IACd,gFAAgF;IAChF,IAAI,EAAE,MAAM;IACZ,kDAAkD;IAClD,MAAM,EAAE,GAAG;IACX,iFAAiF;IACjF,WAAW,EAAE,aAAa;CAClB,CAAC","sourcesContent":["/**\n * Query-string parameter names every LIST and SEARCH operation understands.\n *\n * One named source for the collection wire vocabulary: the resource controller\n * reads these names off the request, the OpenAPI generator declares them as\n * parameters, and the technical documentation projects them into the REST\n * conventions page. Filter fields are per-resource and are not listed here;\n * date-range filters use bracket notation (`createdAt[startDate]=<ISO>`).\n */\nexport const COLLECTION_QUERY_PARAMETERS = {\n  /** 1-based page number. */\n  page: 'page',\n  /** Items per page, bounded by the operation's ceiling. */\n  limit: 'limit',\n  /** Comma-separated `field:asc` / `field:desc` pairs, highest priority first. */\n  sort: 'sort',\n  /** Free-text search term on SEARCH operations. */\n  search: 'q',\n  /** Accepted alias of `search` for callers that post a structured search body. */\n  searchAlias: 'searchQuery',\n} as const;\n"]}
+{"version":3,"file":"collection-query-parameters.shared.js","sourceRoot":"","sources":["../../../src/resources/collection-query-parameters.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,2BAA2B;IAC3B,IAAI,EAAE,MAAM;IACZ,0DAA0D;IAC1D,KAAK,EAAE,OAAO;IACd,gFAAgF;IAChF,IAAI,EAAE,MAAM;IACZ,kDAAkD;IAClD,MAAM,EAAE,GAAG;IACX,iFAAiF;IACjF,WAAW,EAAE,aAAa;CAClB,CAAC","sourcesContent":["/**\n * Query-string parameter names every LIST and SEARCH operation understands.\n *\n * One named source for the collection wire vocabulary: the resource controller\n * reads these names off the request, the OpenAPI generator declares them as\n * parameters, and the technical documentation projects them into the REST\n * conventions page. Filter fields are per-resource and are not listed here;\n * date-range filters use bracket notation (`createdAt[startDate]=<ISO>`).\n */\nexport const COLLECTION_QUERY_PARAMETERS = {\n  /** 1-based page number. */\n  page: 'page',\n  /** Items per page, bounded by the operation's ceiling. */\n  limit: 'limit',\n  /** Comma-separated `field:asc` / `field:desc` pairs, highest priority first. */\n  sort: 'sort',\n  /** Free-text search term on SEARCH operations. */\n  search: 'q',\n  /** Accepted alias of `search` for callers that post a structured search body. */\n  searchAlias: 'searchQuery',\n} as const;\n"]}

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;IAClD,qGAAqG;IACrG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;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;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;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,CAOtD,CAAC;AAMF,eAAO,MAAM,qCAAqC;;;;;;iBAMhD,CAAC;AACH,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAExG,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;iBAU1C,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;IAClD,qGAAqG;IACrG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;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;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;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,CAOtD,CAAC;AAMF,eAAO,MAAM,qCAAqC;;;;;;iBAMhD,CAAC;AACH,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAExG,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;iBAU1C,CAAC"}

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;AAqID,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;IAC9D,KAAK,EAAE,EAAE;CACV,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;IACnE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;CACnD,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,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAClD,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  /** Override the 1:many child cap for this operation. See {@link RelationshipContextPolicy.limit}. */\n  limit?: number;\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   * The most rows a 1:MANY child relationship embeds in a context response — the NEWEST, by the\n   * child's own list sort (its first declared `sortFields` entry, else `createdAt` descending).\n   * Ignored for parents and for 1:1 children, which embed one row by construction.\n   *\n   * A context read used to embed EVERY child row — measured 2026-09-10, an organization context read\n   * serialised all 143 of its audit rows (#583) — so the cost of declaring a child on the context\n   * surface grew with the tenant's history. The cap makes that cost bounded by construction.\n   *\n   * The embedded array cannot say it was truncated: it is a convenience projection of the graph, not\n   * a listing. A consumer that needs the complete set pages the child resource's own LIST.\n   * Maximum 100, the repository's own page ceiling.\n   * @default 20\n   */\n  limit?: number;\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  limit: 20,\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  limit: z.number().int().min(1).max(100).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  limit: z.number().int().min(1).max(100).optional(),\n  operationOverrides: z.partialRecord(\n    z.enum(CoreResourceOperation),\n    ContextPolicy_OperationOverrideSchema\n  ).optional(),\n});\n"]}
+{"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;AAqID,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;IAC9D,KAAK,EAAE,EAAE;CACV,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;IACnE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;CACnD,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,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAClD,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  /** Override the 1:many child cap for this operation. See {@link RelationshipContextPolicy.limit}. */\n  limit?: number;\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   * The most rows a 1:MANY child relationship embeds in a context response — the NEWEST, by the\n   * child's own list sort (its first declared `sortFields` entry, else `createdAt` descending).\n   * Ignored for parents and for 1:1 children, which embed one row by construction.\n   *\n   * A context read used to embed EVERY child row — measured 2026-09-10, an organization context read\n   * serialised all 143 of its audit rows (#583) — so the cost of declaring a child on the context\n   * surface grew with the tenant's history. The cap makes that cost bounded by construction.\n   *\n   * The embedded array cannot say it was truncated: it is a convenience projection of the graph, not\n   * a listing. A consumer that needs the complete set pages the child resource's own LIST.\n   * Maximum 100, the repository's own page ceiling.\n   * @default 20\n   */\n  limit?: number;\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  limit: 20,\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  limit: z.number().int().min(1).max(100).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  limit: z.number().int().min(1).max(100).optional(),\n  operationOverrides: z.partialRecord(\n    z.enum(CoreResourceOperation),\n    ContextPolicy_OperationOverrideSchema\n  ).optional(),\n});\n"]}

package/dist/esm/resources/embedded-resource-mark.shared.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedded-resource-mark.shared.utils.d.ts","sourceRoot":"","sources":["../../../../src/resources/embedded-resource-mark.shared.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,8BAA8B,CAAC;AAExE,iGAAiG;AACjG,wBAAgB,0BAA0B,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAEvH"}
+{"version":3,"file":"embedded-resource-mark.shared.utils.d.ts","sourceRoot":"","sources":["../../../src/resources/embedded-resource-mark.shared.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,8BAA8B,CAAC;AAExE,iGAAiG;AACjG,wBAAgB,0BAA0B,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAEvH"}

package/dist/esm/resources/embedded-resource-mark.shared.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"embedded-resource-mark.shared.utils.js","sourceRoot":"","sources":["../../../../src/resources/embedded-resource-mark.shared.utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,2BAA2B,CAAC;AAExE,iGAAiG;AACjG,MAAM,UAAU,0BAA0B,CAA+B,MAAe,EAAE,YAAoB;IAC5G,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,4BAA4B,CAAC,EAAE,YAAY,EAAE,CAAY,CAAC;AAClF,CAAC","sourcesContent":["import type { z } from 'zod';\n\n/**\n * The JSON-Schema key that names the resource an embedded record belongs to (#1625).\n *\n * A response often carries whole records of ANOTHER resource: a context read embeds its related\n * records under a relationship-derived name (`todos`, `user`), and an aggregate response such as the\n * billing state embeds products, prices and promotions. Their fields are that other resource's, so\n * the response's own resource has no documentation for them.\n *\n * Carried as schema metadata, so `z.toJSONSchema` writes it beside the embedded schema. The API\n * reference's projector reads it, describes the record's fields from that resource's own\n * specification, and removes it: it is an input to documentation, not published API. Metadata\n * only, so it changes nothing a parse accepts.\n *\n * The value is a projected resource type, not a polymorphic base: a record that is one variant or\n * another depending on the caller's scope has no single resource to name.\n */\nexport const EMBEDDED_RESOURCE_SCHEMA_KEY = 'x-wildo-embedded-resource';\n\n/** `schema`, marked as a record of `resourceType` (see {@link EMBEDDED_RESOURCE_SCHEMA_KEY}). */\nexport function markEmbeddedResourceSchema<TSchema extends z.ZodTypeAny>(schema: TSchema, resourceType: string): TSchema {\n  return schema.meta({ [EMBEDDED_RESOURCE_SCHEMA_KEY]: resourceType }) as TSchema;\n}\n"]}
+{"version":3,"file":"embedded-resource-mark.shared.utils.js","sourceRoot":"","sources":["../../../src/resources/embedded-resource-mark.shared.utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,2BAA2B,CAAC;AAExE,iGAAiG;AACjG,MAAM,UAAU,0BAA0B,CAA+B,MAAe,EAAE,YAAoB;IAC5G,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,4BAA4B,CAAC,EAAE,YAAY,EAAE,CAAY,CAAC;AAClF,CAAC","sourcesContent":["import type { z } from 'zod';\n\n/**\n * The JSON-Schema key that names the resource an embedded record belongs to (#1625).\n *\n * A response often carries whole records of ANOTHER resource: a context read embeds its related\n * records under a relationship-derived name (`todos`, `user`), and an aggregate response such as the\n * billing state embeds products, prices and promotions. Their fields are that other resource's, so\n * the response's own resource has no documentation for them.\n *\n * Carried as schema metadata, so `z.toJSONSchema` writes it beside the embedded schema. The API\n * reference's projector reads it, describes the record's fields from that resource's own\n * specification, and removes it: it is an input to documentation, not published API. Metadata\n * only, so it changes nothing a parse accepts.\n *\n * The value is a projected resource type, not a polymorphic base: a record that is one variant or\n * another depending on the caller's scope has no single resource to name.\n */\nexport const EMBEDDED_RESOURCE_SCHEMA_KEY = 'x-wildo-embedded-resource';\n\n/** `schema`, marked as a record of `resourceType` (see {@link EMBEDDED_RESOURCE_SCHEMA_KEY}). */\nexport function markEmbeddedResourceSchema<TSchema extends z.ZodTypeAny>(schema: TSchema, resourceType: string): TSchema {\n  return schema.meta({ [EMBEDDED_RESOURCE_SCHEMA_KEY]: resourceType }) as TSchema;\n}\n"]}

package/dist/esm/resources/relationship-display.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-display.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/resources/relationship-display.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAiC,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAY9F;;;;;;;;;;;;;;;GAeG;AACH,oBAAY,aAAa;IACvB;;;OAGG;IACH,UAAU,eAAe;IACzB;;;;OAIG;IACH,OAAO,YAAY;IACnB;;;OAGG;IACH,KAAK,UAAU;IACf;;;OAGG;IACH,OAAO,YAAY;IACnB,qEAAqE;IACrE,IAAI,SAAS;CACd;AAOD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2CAA2C;;;;;;;;;;;;;kBAwC7C,CAAC;AACZ,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2CAA2C,CAAC,CAAC;AAOhH;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC;;;kBAoBtC,CAAC;AACZ,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAOlG;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oCAAoC;;kBA4BtC,CAAC;AACZ,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAOlG;;;GAGG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;kBAajC,CAAC;AACZ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC"}
+{"version":3,"file":"relationship-display.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/resources/relationship-display.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAiC,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAY9F;;;;;;;;;;;;;;;GAeG;AACH,oBAAY,aAAa;IACvB;;;OAGG;IACH,UAAU,eAAe;IACzB;;;;OAIG;IACH,OAAO,YAAY;IACnB;;;OAGG;IACH,KAAK,UAAU;IACf;;;OAGG;IACH,OAAO,YAAY;IACnB,qEAAqE;IACrE,IAAI,SAAS;CACd;AAOD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2CAA2C;;;;;;;;;;;;;kBAwC7C,CAAC;AACZ,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2CAA2C,CAAC,CAAC;AAOhH;;;;;;;GAOG;AACH,eAAO,MAAM,oCAAoC;;;kBAoBtC,CAAC;AACZ,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAOlG;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oCAAoC;;kBA4BtC,CAAC;AACZ,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oCAAoC,CAAC,CAAC;AAOlG;;;GAGG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;kBAajC,CAAC;AACZ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC"}

package/dist/esm/resources/relationship-display.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"relationship-display.shared.schemas.js","sourceRoot":"","sources":["../../../../src/resources/relationship-display.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC9F,OAAO,EACL,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,8CAA8C,CAAC;AAItD,mEAAmE;AACnE,6DAA6D;AAC7D,mEAAmE;AAEnE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAN,IAAY,aAwBX;AAxBD,WAAY,aAAa;IACvB;;;OAGG;IACH,0CAAyB,CAAA;IACzB;;;;OAIG;IACH,oCAAmB,CAAA;IACnB;;;OAGG;IACH,gCAAe,CAAA;IACf;;;OAGG;IACH,oCAAmB,CAAA;IACnB,qEAAqE;IACrE,8BAAa,CAAA;AACf,CAAC,EAxBW,aAAa,KAAb,aAAa,QAwBxB;AAGD,mEAAmE;AACnE,wCAAwC;AACxC,mEAAmE;AAEnE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,2CAA2C,GAAG,CAAC,CAAC,MAAM,CAAC;IAClE;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,EAAE,2BAA2B,CAAC,sBAAsB,CAAC,CAAC,QAAQ,EAAE;IAE1E;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAEhD;;;;;OAKG;IACH,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE;IAE9C;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,QAAQ,EAAE;CAC5D,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,mEAAmE;AACnE,iCAAiC;AACjC,mEAAmE;AAEnE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3D;;;;OAIG;IACH,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAEtC;;;;;;;;;;OAUG;IACH,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE;CAChD,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,mEAAmE;AACnE,iCAAiC;AACjC,mEAAmE;AAEnE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3D;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACzC,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,mEAAmE;AACnE,uCAAuC;AACvC,mEAAmE;AAEnE;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,qEAAqE;IACrE,kBAAkB,EAAE,2CAA2C,CAAC,QAAQ,EAAE;IAC1E,mEAAmE;IACnE,WAAW,EAAE,oCAAoC,CAAC,QAAQ,EAAE;IAC5D;;;;;;OAMG;IACH,WAAW,EAAE,oCAAoC,CAAC,QAAQ,EAAE;CAC7D,CAAC,CAAC,MAAM,EAAE,CAAC","sourcesContent":["/**\n * Relationship Display Configuration\n *\n * How resource relationships are presented in frontend views.\n *\n * This file intentionally stays on the FRONTEND/UI plane:\n * - read composition in the CHILD's view (`inChildView`)\n * - narrow workflow hints for frontend interaction (`interaction`)\n *\n * It is separate from:\n * - shared semantic meaning (`RelationshipNature`)\n * - backend/nested handling (`childOperations`)\n * - navigation shell zoning, which lives in config/frontend/navigation.shared.schemas\n *\n * NOTE (2026-08-20): view COMPOSITION was removed from this file. A parent no\n * longer configures how its children appear inside its own view — the view\n * places them (`RelatedResourceSections` / `EmbedRelatedResourceList`), or the\n * framework composes owned children with no parameters at all. What remains here\n * is relationship SEMANTICS: navigating an edge, presenting the parent inside the\n * child, and workflow hints. See\n * `.claude/plans/children-display-template-owned-composition.md`.\n *\n * Key concepts:\n * - `inParentNavigation`: How parent-owned navigation to those children is orchestrated\n * - `inChildView`: How the parent reference appears in the child's detail view (breadcrumb, badge, etc.)\n *\n * Uses navigation types (TransitionConfig) as building blocks for relationship-level\n * transition overrides, but the display config itself belongs to the resource domain.\n *\n * @see createResourcesRelationship() display option\n */\n\nimport { z } from 'zod';\nimport { DisplayDirection, SectionMode, ViewportBreakpoint } from '@wildo-ai/zod-decorators';\nimport { CascadeDirection, CoreResourceOperation } from './resources.shared.core.definitions';\nimport {\n  TransitionConfigSchema,\n  viewportDiscriminatedSchema,\n} from '../config/frontend/navigation.shared.schemas';\n\n\n\n// ════════════════════════════════════════════════════════════════\n// ParentDisplay — How parent reference renders in child view\n// ════════════════════════════════════════════════════════════════\n\n/**\n * How the parent reference appears in the child's detail view.\n *\n * Controls the structural element in the child's view that references the parent\n * resource. This is NOT about the FK field rendering (which is handled by\n * `ForeignKeyUIDisplayParams.mode` via `.foreignKeyUI()`).\n *\n * Values align with framework behavior:\n * - `breadcrumb`: Rendered via BreadcrumbCompound as a breadcrumb segment.\n * - `context`: Framework's context bar / header link — parent in the contextual header area.\n * - `summary`: Matches ForeignKeyDisplayMode.SUMMARY — compact card with key parent fields\n *   (same rendering pattern as FK summary view).\n * - `badge`: Compact badge/chip in header area.\n *\n * Replaces the old `RelationshipDisplayMode` enum (link/badge/inline/none).\n */\nexport enum ParentDisplay {\n  /**\n   * Parent as breadcrumb segment. Rendered via BreadcrumbCompound.\n   * Example: \"Projects > Alpha\" with parent as a clickable segment.\n   */\n  BREADCRUMB = 'breadcrumb',\n  /**\n   * Parent in the framework's context bar / header link area.\n   * Matches framework's contextual parent reference (header link, context bar).\n   * Default for most relationships.\n   */\n  CONTEXT = 'context',\n  /**\n   * Compact badge/chip in header area showing parent identity.\n   * Matches framework's badge display. Less prominent than context/breadcrumb.\n   */\n  BADGE = 'badge',\n  /**\n   * Inline summary card. Matches ForeignKeyDisplayMode.SUMMARY — compact card\n   * with key parent fields (same rendering as FK summary view).\n   */\n  SUMMARY = 'summary',\n  /** Don't show any parent reference. The child appears standalone. */\n  NONE = 'none',\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// RelationshipDisplayInParentNavigation\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Parent-owned navigation behavior for a relationship surface.\n *\n * This subtree answers navigation questions that do NOT belong to embedded\n * composition itself:\n * - when a header or \"View all\" action should navigate\n * - which transition should be used\n * - how ancestor zones should be populated while cascading\n * - how deep relationship-owned navigation may grow before escalation\n *\n * Keeping these settings on the relationship preserves the semantic distinction\n * between navigating to a child (an edge concern, here) and COMPOSING one into a\n * view (the view's concern — a template places it; see `RelatedResourceSections`).\n */\nexport const RelationshipDisplayInParentNavigationSchema = z.object({\n  /**\n   * Navigation transition override for this relationship.\n   * When undefined, the relationship stays embed-first and callers decide\n   * whether any separate navigation affordance should exist.\n   *\n   * Old field mapping:\n   * - `intent: 'inline'` → no `transition`\n   * - `intent: 'detail'` → `transition: NavigationTransition.SPLIT`\n   * - `intent: 'drill'` → `transition: NavigationTransition.PUSH`\n   * - `intent: 'companion'` → `transition: { transition: NavigationTransition.SPLIT, persistent: true }`\n   * - `intent: 'inspect'` → `transition: { transition: NavigationTransition.OVERLAY, ephemeral: true }`\n   *\n   * New v3 transitions available at the relationship level:\n   * - `NavigationTransition.INPLACE`: edit/create child inline within the parent view\n   *   (element transforms without zone or stack change)\n   * - `NavigationTransition.PROMOTE`: open child at primary scope, escaping current context\n   */\n  transition: viewportDiscriminatedSchema(TransitionConfigSchema).optional(),\n\n  /**\n   * Override global `maxDepth` for this relationship's navigation chain.\n   * When the push stack reaches this depth, the framework escalates to overlay.\n   */\n  maxDepth: z.number().int().positive().optional(),\n\n  /**\n   * For self-referencing relationships (e.g. Category → Category):\n   * which direction to traverse when fetching data.\n   * - `CascadeDirection.FORWARD`: declaring resource is the ancestor (parent → child)\n   * - `CascadeDirection.BACKWARD`: related resource is the ancestor (child → parent)\n   */\n  direction: z.enum(CascadeDirection).optional(),\n\n  /**\n   * Override which operation to show in the ancestor zone when cascading.\n   * When a child is placed in SECONDARY or COMPANION, ancestor zones are auto-populated.\n   * Defaults: 1:N → LIST, 1:1 → READ, M:N → LIST. Use this to force LIST or READ.\n   */\n  ancestorOperation: z.enum(CoreResourceOperation).optional(),\n}).strict();\nexport type RelationshipDisplayInParentNavigation = z.infer<typeof RelationshipDisplayInParentNavigationSchema>;\n\n\n// ════════════════════════════════════════════════════════════════\n// RelationshipDisplayInChildView\n// ════════════════════════════════════════════════════════════════\n\n/**\n * How the parent reference appears in the child's detail view.\n *\n * Controls a structural element in the child's view header/context area.\n * This is separate from FK field rendering (`ForeignKeyUIDisplayParams`):\n * - FK params control the FK FIELD widget (raw ID, resolved label, summary card)\n * - This controls a dedicated PARENT REFERENCE element (breadcrumb, badge, card)\n */\nexport const RelationshipDisplayInChildViewSchema = z.object({\n  /**\n   * Whether the parent display element is clickable.\n   * When `true` (default for required relationships), clicking the parent reference\n   * triggers a `read` transition to the parent resource from the current zone.\n   */\n  showParentLink: z.boolean().optional(),\n\n  /**\n   * How the parent reference renders structurally in the child's view header.\n   * - `ParentDisplay.BREADCRUMB`: breadcrumb segment (BreadcrumbCompound)\n   * - `ParentDisplay.CONTEXT` (default): framework context bar / header link\n   * - `ParentDisplay.BADGE`: compact chip in header area\n   * - `ParentDisplay.SUMMARY`: compact card (matches ForeignKeyDisplayMode.SUMMARY)\n   * - `ParentDisplay.NONE`: hidden — no parent reference shown\n   *\n   * Replaces old `displayMode` field (renamed to avoid collision with other\n   * `displayMode` fields throughout the codebase, and to clarify the scope).\n   */\n  parentDisplay: z.enum(ParentDisplay).optional(),\n}).strict();\nexport type RelationshipDisplayInChildView = z.infer<typeof RelationshipDisplayInChildViewSchema>;\n\n\n// ════════════════════════════════════════════════════════════════\n// RelationshipDisplayInteraction\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Narrow frontend interaction hints for relationship surfaces.\n *\n * These settings are intentionally NOT part of the shared relationship meaning:\n * - they do not change `RelationshipNature`\n * - they do not change backend mutation/lifecycle semantics\n * - they only influence how the frontend may orchestrate an interaction\n *\n * Important distinction:\n * - `COMPOSITION` already owns aggregate/nested creation semantics\n * - `REFERENCE` may optionally offer \"create related resource, then set reference\"\n * - `ASSOCIATION` may optionally offer \"create peer resource, then link/replace\"\n *\n * So \"quick create\" is a workflow capability layered on top of relationship\n * semantics, not a fourth relationship nature.\n */\nexport const RelationshipDisplayInteractionSchema = z.object({\n  /**\n   * Whether the frontend may offer a \"quick create\" affordance on top of the\n   * relationship surface.\n   *\n   * Semantic meaning by relationship nature:\n   * - `REFERENCE`: create an independent related resource, then complete the\n   *   reference action (`set` / future selector confirmation). The parent does\n   *   not aggregate-manage the child.\n   * - `ASSOCIATION`: create an independent peer resource, then complete the\n   *   association action (`link` / `replace`). The parent manages membership,\n   *   not the peer lifecycle.\n   * - `COMPOSITION`: this hint is generally redundant and should normally be\n   *   ignored, because composition already owns native nested creation through\n   *   aggregate semantics.\n   *\n   * Framework policy:\n   * - Missing value means ENABLED.\n   * - Consumers should treat `undefined` as `true`.\n   * - Disabling this only removes the shortcut affordance; it does not change\n   *   what the relationship means.\n   *\n   * Why default `true`:\n   * - for `REFERENCE`, \"create then set\" is usually a useful workflow shortcut\n   * - for `ASSOCIATION`, \"create then link\" is usually a useful workflow shortcut\n   * - the semantic distinction still stays visible in the follow-up action\n   */\n  allowQuickCreate: z.boolean().optional(),\n}).strict();\nexport type RelationshipDisplayInteraction = z.infer<typeof RelationshipDisplayInteractionSchema>;\n\n\n// ════════════════════════════════════════════════════════════════\n// RelationshipDisplayConfig — Combined\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Combined frontend relationship presentation configuration.\n * Passed as the `display` option in `createResourcesRelationship()`.\n */\nexport const RelationshipDisplayConfigSchema = z.object({\n  /** How parent-owned navigation to those children is orchestrated. */\n  inParentNavigation: RelationshipDisplayInParentNavigationSchema.optional(),\n  /** How the parent reference appears in the child's detail view. */\n  inChildView: RelationshipDisplayInChildViewSchema.optional(),\n  /**\n   * Narrow interaction/workflow hints for frontend relationship surfaces.\n   *\n   * This is where UI capabilities such as `allowQuickCreate` belong. Keep these\n   * hints separate from `RelationshipNature` so frontend shortcuts do not blur\n   * backend/shared semantics.\n   */\n  interaction: RelationshipDisplayInteractionSchema.optional(),\n}).strict();\nexport type RelationshipDisplayConfig = z.infer<typeof RelationshipDisplayConfigSchema>;\n"]}
+{"version":3,"file":"relationship-display.shared.schemas.js","sourceRoot":"","sources":["../../../src/resources/relationship-display.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAC9F,OAAO,EACL,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,8CAA8C,CAAC;AAItD,mEAAmE;AACnE,6DAA6D;AAC7D,mEAAmE;AAEnE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAN,IAAY,aAwBX;AAxBD,WAAY,aAAa;IACvB;;;OAGG;IACH,0CAAyB,CAAA;IACzB;;;;OAIG;IACH,oCAAmB,CAAA;IACnB;;;OAGG;IACH,gCAAe,CAAA;IACf;;;OAGG;IACH,oCAAmB,CAAA;IACnB,qEAAqE;IACrE,8BAAa,CAAA;AACf,CAAC,EAxBW,aAAa,KAAb,aAAa,QAwBxB;AAGD,mEAAmE;AACnE,wCAAwC;AACxC,mEAAmE;AAEnE;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,2CAA2C,GAAG,CAAC,CAAC,MAAM,CAAC;IAClE;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,EAAE,2BAA2B,CAAC,sBAAsB,CAAC,CAAC,QAAQ,EAAE;IAE1E;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAEhD;;;;;OAKG;IACH,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE;IAE9C;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC,QAAQ,EAAE;CAC5D,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,mEAAmE;AACnE,iCAAiC;AACjC,mEAAmE;AAEnE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3D;;;;OAIG;IACH,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAEtC;;;;;;;;;;OAUG;IACH,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE;CAChD,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,mEAAmE;AACnE,iCAAiC;AACjC,mEAAmE;AAEnE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3D;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACzC,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,mEAAmE;AACnE,uCAAuC;AACvC,mEAAmE;AAEnE;;;GAGG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,MAAM,CAAC;IACtD,qEAAqE;IACrE,kBAAkB,EAAE,2CAA2C,CAAC,QAAQ,EAAE;IAC1E,mEAAmE;IACnE,WAAW,EAAE,oCAAoC,CAAC,QAAQ,EAAE;IAC5D;;;;;;OAMG;IACH,WAAW,EAAE,oCAAoC,CAAC,QAAQ,EAAE;CAC7D,CAAC,CAAC,MAAM,EAAE,CAAC","sourcesContent":["/**\n * Relationship Display Configuration\n *\n * How resource relationships are presented in frontend views.\n *\n * This file intentionally stays on the FRONTEND/UI plane:\n * - read composition in the CHILD's view (`inChildView`)\n * - narrow workflow hints for frontend interaction (`interaction`)\n *\n * It is separate from:\n * - shared semantic meaning (`RelationshipNature`)\n * - backend/nested handling (`childOperations`)\n * - navigation shell zoning, which lives in config/frontend/navigation.shared.schemas\n *\n * NOTE (2026-08-20): view COMPOSITION was removed from this file. A parent no\n * longer configures how its children appear inside its own view — the view\n * places them (`RelatedResourceSections` / `EmbedRelatedResourceList`), or the\n * framework composes owned children with no parameters at all. What remains here\n * is relationship SEMANTICS: navigating an edge, presenting the parent inside the\n * child, and workflow hints. See\n * `.claude/plans/children-display-template-owned-composition.md`.\n *\n * Key concepts:\n * - `inParentNavigation`: How parent-owned navigation to those children is orchestrated\n * - `inChildView`: How the parent reference appears in the child's detail view (breadcrumb, badge, etc.)\n *\n * Uses navigation types (TransitionConfig) as building blocks for relationship-level\n * transition overrides, but the display config itself belongs to the resource domain.\n *\n * @see createResourcesRelationship() display option\n */\n\nimport { z } from 'zod';\nimport { DisplayDirection, SectionMode, ViewportBreakpoint } from '@wildo-ai/zod-decorators';\nimport { CascadeDirection, CoreResourceOperation } from './resources.shared.core.definitions';\nimport {\n  TransitionConfigSchema,\n  viewportDiscriminatedSchema,\n} from '../config/frontend/navigation.shared.schemas';\n\n\n\n// ════════════════════════════════════════════════════════════════\n// ParentDisplay — How parent reference renders in child view\n// ════════════════════════════════════════════════════════════════\n\n/**\n * How the parent reference appears in the child's detail view.\n *\n * Controls the structural element in the child's view that references the parent\n * resource. This is NOT about the FK field rendering (which is handled by\n * `ForeignKeyUIDisplayParams.mode` via `.foreignKeyUI()`).\n *\n * Values align with framework behavior:\n * - `breadcrumb`: Rendered via BreadcrumbCompound as a breadcrumb segment.\n * - `context`: Framework's context bar / header link — parent in the contextual header area.\n * - `summary`: Matches ForeignKeyDisplayMode.SUMMARY — compact card with key parent fields\n *   (same rendering pattern as FK summary view).\n * - `badge`: Compact badge/chip in header area.\n *\n * Replaces the old `RelationshipDisplayMode` enum (link/badge/inline/none).\n */\nexport enum ParentDisplay {\n  /**\n   * Parent as breadcrumb segment. Rendered via BreadcrumbCompound.\n   * Example: \"Projects > Alpha\" with parent as a clickable segment.\n   */\n  BREADCRUMB = 'breadcrumb',\n  /**\n   * Parent in the framework's context bar / header link area.\n   * Matches framework's contextual parent reference (header link, context bar).\n   * Default for most relationships.\n   */\n  CONTEXT = 'context',\n  /**\n   * Compact badge/chip in header area showing parent identity.\n   * Matches framework's badge display. Less prominent than context/breadcrumb.\n   */\n  BADGE = 'badge',\n  /**\n   * Inline summary card. Matches ForeignKeyDisplayMode.SUMMARY — compact card\n   * with key parent fields (same rendering as FK summary view).\n   */\n  SUMMARY = 'summary',\n  /** Don't show any parent reference. The child appears standalone. */\n  NONE = 'none',\n}\n\n\n// ════════════════════════════════════════════════════════════════\n// RelationshipDisplayInParentNavigation\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Parent-owned navigation behavior for a relationship surface.\n *\n * This subtree answers navigation questions that do NOT belong to embedded\n * composition itself:\n * - when a header or \"View all\" action should navigate\n * - which transition should be used\n * - how ancestor zones should be populated while cascading\n * - how deep relationship-owned navigation may grow before escalation\n *\n * Keeping these settings on the relationship preserves the semantic distinction\n * between navigating to a child (an edge concern, here) and COMPOSING one into a\n * view (the view's concern — a template places it; see `RelatedResourceSections`).\n */\nexport const RelationshipDisplayInParentNavigationSchema = z.object({\n  /**\n   * Navigation transition override for this relationship.\n   * When undefined, the relationship stays embed-first and callers decide\n   * whether any separate navigation affordance should exist.\n   *\n   * Old field mapping:\n   * - `intent: 'inline'` → no `transition`\n   * - `intent: 'detail'` → `transition: NavigationTransition.SPLIT`\n   * - `intent: 'drill'` → `transition: NavigationTransition.PUSH`\n   * - `intent: 'companion'` → `transition: { transition: NavigationTransition.SPLIT, persistent: true }`\n   * - `intent: 'inspect'` → `transition: { transition: NavigationTransition.OVERLAY, ephemeral: true }`\n   *\n   * New v3 transitions available at the relationship level:\n   * - `NavigationTransition.INPLACE`: edit/create child inline within the parent view\n   *   (element transforms without zone or stack change)\n   * - `NavigationTransition.PROMOTE`: open child at primary scope, escaping current context\n   */\n  transition: viewportDiscriminatedSchema(TransitionConfigSchema).optional(),\n\n  /**\n   * Override global `maxDepth` for this relationship's navigation chain.\n   * When the push stack reaches this depth, the framework escalates to overlay.\n   */\n  maxDepth: z.number().int().positive().optional(),\n\n  /**\n   * For self-referencing relationships (e.g. Category → Category):\n   * which direction to traverse when fetching data.\n   * - `CascadeDirection.FORWARD`: declaring resource is the ancestor (parent → child)\n   * - `CascadeDirection.BACKWARD`: related resource is the ancestor (child → parent)\n   */\n  direction: z.enum(CascadeDirection).optional(),\n\n  /**\n   * Override which operation to show in the ancestor zone when cascading.\n   * When a child is placed in SECONDARY or COMPANION, ancestor zones are auto-populated.\n   * Defaults: 1:N → LIST, 1:1 → READ, M:N → LIST. Use this to force LIST or READ.\n   */\n  ancestorOperation: z.enum(CoreResourceOperation).optional(),\n}).strict();\nexport type RelationshipDisplayInParentNavigation = z.infer<typeof RelationshipDisplayInParentNavigationSchema>;\n\n\n// ════════════════════════════════════════════════════════════════\n// RelationshipDisplayInChildView\n// ════════════════════════════════════════════════════════════════\n\n/**\n * How the parent reference appears in the child's detail view.\n *\n * Controls a structural element in the child's view header/context area.\n * This is separate from FK field rendering (`ForeignKeyUIDisplayParams`):\n * - FK params control the FK FIELD widget (raw ID, resolved label, summary card)\n * - This controls a dedicated PARENT REFERENCE element (breadcrumb, badge, card)\n */\nexport const RelationshipDisplayInChildViewSchema = z.object({\n  /**\n   * Whether the parent display element is clickable.\n   * When `true` (default for required relationships), clicking the parent reference\n   * triggers a `read` transition to the parent resource from the current zone.\n   */\n  showParentLink: z.boolean().optional(),\n\n  /**\n   * How the parent reference renders structurally in the child's view header.\n   * - `ParentDisplay.BREADCRUMB`: breadcrumb segment (BreadcrumbCompound)\n   * - `ParentDisplay.CONTEXT` (default): framework context bar / header link\n   * - `ParentDisplay.BADGE`: compact chip in header area\n   * - `ParentDisplay.SUMMARY`: compact card (matches ForeignKeyDisplayMode.SUMMARY)\n   * - `ParentDisplay.NONE`: hidden — no parent reference shown\n   *\n   * Replaces old `displayMode` field (renamed to avoid collision with other\n   * `displayMode` fields throughout the codebase, and to clarify the scope).\n   */\n  parentDisplay: z.enum(ParentDisplay).optional(),\n}).strict();\nexport type RelationshipDisplayInChildView = z.infer<typeof RelationshipDisplayInChildViewSchema>;\n\n\n// ════════════════════════════════════════════════════════════════\n// RelationshipDisplayInteraction\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Narrow frontend interaction hints for relationship surfaces.\n *\n * These settings are intentionally NOT part of the shared relationship meaning:\n * - they do not change `RelationshipNature`\n * - they do not change backend mutation/lifecycle semantics\n * - they only influence how the frontend may orchestrate an interaction\n *\n * Important distinction:\n * - `COMPOSITION` already owns aggregate/nested creation semantics\n * - `REFERENCE` may optionally offer \"create related resource, then set reference\"\n * - `ASSOCIATION` may optionally offer \"create peer resource, then link/replace\"\n *\n * So \"quick create\" is a workflow capability layered on top of relationship\n * semantics, not a fourth relationship nature.\n */\nexport const RelationshipDisplayInteractionSchema = z.object({\n  /**\n   * Whether the frontend may offer a \"quick create\" affordance on top of the\n   * relationship surface.\n   *\n   * Semantic meaning by relationship nature:\n   * - `REFERENCE`: create an independent related resource, then complete the\n   *   reference action (`set` / future selector confirmation). The parent does\n   *   not aggregate-manage the child.\n   * - `ASSOCIATION`: create an independent peer resource, then complete the\n   *   association action (`link` / `replace`). The parent manages membership,\n   *   not the peer lifecycle.\n   * - `COMPOSITION`: this hint is generally redundant and should normally be\n   *   ignored, because composition already owns native nested creation through\n   *   aggregate semantics.\n   *\n   * Framework policy:\n   * - Missing value means ENABLED.\n   * - Consumers should treat `undefined` as `true`.\n   * - Disabling this only removes the shortcut affordance; it does not change\n   *   what the relationship means.\n   *\n   * Why default `true`:\n   * - for `REFERENCE`, \"create then set\" is usually a useful workflow shortcut\n   * - for `ASSOCIATION`, \"create then link\" is usually a useful workflow shortcut\n   * - the semantic distinction still stays visible in the follow-up action\n   */\n  allowQuickCreate: z.boolean().optional(),\n}).strict();\nexport type RelationshipDisplayInteraction = z.infer<typeof RelationshipDisplayInteractionSchema>;\n\n\n// ════════════════════════════════════════════════════════════════\n// RelationshipDisplayConfig — Combined\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Combined frontend relationship presentation configuration.\n * Passed as the `display` option in `createResourcesRelationship()`.\n */\nexport const RelationshipDisplayConfigSchema = z.object({\n  /** How parent-owned navigation to those children is orchestrated. */\n  inParentNavigation: RelationshipDisplayInParentNavigationSchema.optional(),\n  /** How the parent reference appears in the child's detail view. */\n  inChildView: RelationshipDisplayInChildViewSchema.optional(),\n  /**\n   * Narrow interaction/workflow hints for frontend relationship surfaces.\n   *\n   * This is where UI capabilities such as `allowQuickCreate` belong. Keep these\n   * hints separate from `RelationshipNature` so frontend shortcuts do not blur\n   * backend/shared semantics.\n   */\n  interaction: RelationshipDisplayInteractionSchema.optional(),\n}).strict();\nexport type RelationshipDisplayConfig = z.infer<typeof RelationshipDisplayConfigSchema>;\n"]}

package/dist/esm/resources/resource-status-lifecycle.example.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Illustrative status lifecycle on a resource, for the app-facing `resource-status-lifecycle` skill.
+ *
+ * TIER B (framework-owned illustrative sample): the reference applications show transitions
+ * (`todo-lists` ARCHIVE / RESTORE) but not the whole pattern — their status field stays freely
+ * editable through UPDATE and nothing freezes a terminal state — so anchoring them would teach a
+ * lifecycle anyone can bypass. Typed against the real factory, and pinned by a contract test that
+ * builds the configuration, so a sample the factory refuses fails CI.
+ */
+import { z } from 'zod';
+import { CoreResourceOperation } from './resources.shared.core.definitions';
+import { type ResourceRelationship } from './resources.shared.schemas';
+/**
+ * @wildo_source:part:start example.resource.status-lifecycle.quote facet:kind:usage-example facet:audience:app-developer
+ *
+ * A quote moves DRAFT → SENT → ACCEPTED or DECLINED. `z_money`, `CurrencySchema`, `CurrencyAllowed` and
+ * `DocumentSequenceScope` import from `@wildo-ai/zod-decorators`; everything else below from
+ * `@wildo-ai/saas-models` (and `zod`). The schema lives in `<resource>.schemas.ts`, the rest in
+ * `<resource>.resources-config.ts`.
+ *
+ * Four things make it a lifecycle rather than a field anyone edits:
+ * 1. `status` is `.excludeFromUpdate()`, so the generic UPDATE cannot move it at all.
+ * 2. Each transition is its own operation, `resourceOperationLike: UPDATE` with an empty
+ *    `requestDto`: the target state is the server's decision, never the caller's.
+ * 3. `enabledCondition` says which state the transition starts from. The engine enforces it on the
+ *    backend (and the UI hides the action), so SEND on an accepted quote is refused.
+ * 4. `basicPrefixOperation` returns ONLY the new state and its timestamp (spreading the current row
+ *    would write every field back, overwriting a concurrent edit), and `authoritativeFields` names
+ *    them. A key the prefix introduces is kept on the ordinary HTTP path anyway; the declaration is
+ *    what keeps it when a caller reaches the service with that key already in its payload (an MCP
+ *    tool, another service), where the strict re-parse would otherwise strip it.
+ * And UPDATE itself is enabled only while the quote is a DRAFT: SENT is LOCKED (no edits, yet ACCEPT and
+ * DECLINE still move it on) and ACCEPTED and DECLINED are FINAL (nothing moves them again).
+ *
+ * It is also a COMMERCIAL DOCUMENT, and these fields make it one:
+ * - `number` is allocated by the server at create, consecutive per organization and year (`Q-2026-00042`); a client
+ *   never sends it, and the decorator makes it unique and server-only;
+ * - `currency` is the quote's one currency; every amount on it is a fiat `z_money()` in that currency;
+ * - `lines` are an array on the quote, so they freeze with it: the UPDATE that edits them is refused once it is SENT;
+ * - `total` is the server's: excluded from create and update, computed by a prefix on CREATE and UPDATE with
+ *   `authoritativeFields: ['total']` from the lines and `discountPercent` (see the computed-total recipe), never typed
+ *   by a person.
+ *
+ * Concurrency: the starting-state check runs before the write and is not a compare-and-swap. Two
+ * transitions from the same state arriving at the same moment (ACCEPT and DECLINE on one SENT quote)
+ * can both pass it, and the last write wins. Sequential calls are refused correctly. Closing the
+ * concurrent case is the engine's work (a transition whose write is conditional on its starting state),
+ * not something an application can declare today.
+ */
+export declare enum Quote_Status {
+    DRAFT = "DRAFT",
+    SENT = "SENT",
+    ACCEPTED = "ACCEPTED",
+    DECLINED = "DECLINED"
+}
+export declare const Quote_Schema: z.ZodObject<{
+    _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    organizationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
+    number: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    title: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    currency: z.ZodUnion<[z.ZodEnum<typeof import("@wildo-ai/zod-decorators").AvailableCurrency>, z.ZodString]>;
+    lines: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        quantity: z.ZodNumber;
+        unitPrice: import("@wildo-ai/zod-decorators").DecoratedMoneySchema;
+    }, z.core.$strip>>>;
+    discountPercent: z.ZodDefault<z.ZodNumber>;
+    total: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<import("@wildo-ai/zod-decorators").DecoratedMoneySchema>>>>;
+    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof Quote_Status>>>>>;
+    sentAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
+    decidedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
+}, z.core.$strip>;
+/** In `<module>.relationships.ts`: the organization the quote belongs to (its primary scope). */
+export declare const quote_ResourceRelationships: ResourceRelationship[];
+export declare enum Quote_Operations {
+    SEND = "send",
+    ACCEPT = "accept",
+    DECLINE = "decline"
+}
+type Quote_CoreOperations = CoreResourceOperation.READ | CoreResourceOperation.LIST | CoreResourceOperation.CREATE | CoreResourceOperation.UPDATE;
+export declare const quote_ResourceConfiguration_InitializationFactory: (resourcesRelationships: ResourceRelationship[]) => import("./resources-config.shared.schemas").ResourceConfiguration<typeof Quote_Operations, Quote_CoreOperations, z.ZodObject<{
+    _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    organizationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
+    number: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    title: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    currency: z.ZodUnion<[z.ZodEnum<typeof import("@wildo-ai/zod-decorators").AvailableCurrency>, z.ZodString]>;
+    lines: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        quantity: z.ZodNumber;
+        unitPrice: import("@wildo-ai/zod-decorators").DecoratedMoneySchema;
+    }, z.core.$strip>>>;
+    discountPercent: z.ZodDefault<z.ZodNumber>;
+    total: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<import("@wildo-ai/zod-decorators").DecoratedMoneySchema>>>>;
+    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof Quote_Status>>>>>;
+    sentAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
+    decidedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
+}, z.core.$strip>>;
+export {};
+/** @wildo_source:part:end example.resource.status-lifecycle.quote */
+//# sourceMappingURL=resource-status-lifecycle.example.d.ts.map

package/dist/esm/resources/resource-status-lifecycle.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-status-lifecycle.example.d.ts","sourceRoot":"","sources":["../../../src/resources/resource-status-lifecycle.example.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAE,qBAAqB,EAAoB,MAAM,qCAAqC,CAAC;AAC9F,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,oBAAY,YAAY;IACtB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,QAAQ,aAAa;CACtB;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;iBAgBvB,CAAC;AAEH,iGAAiG;AACjG,eAAO,MAAM,2BAA2B,EAAE,oBAAoB,EAM7D,CAAC;AAEF,oBAAY,gBAAgB;IAC1B,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AAED,KAAK,oBAAoB,GAAG,qBAAqB,CAAC,IAAI,GAAG,qBAAqB,CAAC,IAAI,GAAG,qBAAqB,CAAC,MAAM,GAAG,qBAAqB,CAAC,MAAM,CAAC;AAElJ,eAAO,MAAM,iDAAiD,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;kBAmE5G,CAAC;;AACL,qEAAqE"}