@wildo-ai/saas-models 1.0.1 → 1.1.0

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

@@ -4,10 +4,15 @@
  * Reusable operation schemas for bulk actions and common operations
  */
 import { z } from 'zod';
-import { CoreResourceOperation, ResourceTypeSchema } from './resources.shared.core.definitions.js';
+import { CoreResourceOperation, OPERATIONS_WITHOUT_REQUEST_BODY, ResourceTypeSchema, } from './resources.shared.core.definitions.js';
 import { RelationshipContextPolicySchema } from './context-policy.shared.schemas.js';
-import { ChildLifecycleMode, ChildOperationsConfigSchema, ResourceRelationshipDiscriminatorSchema, } from './child-operations.shared.schemas.js';
+import { ChildLifecycleMode, ChildLifecycleStrategy, ChildOperationsConfigSchema, ResourceRelationshipDiscriminatorSchema, } from './child-operations.shared.schemas.js';
 import { RelationshipDisplayConfigSchema } from './relationship-display.shared.schemas.js';
+/**
+ * @wildo_source:part:start saas.models.resource-operation-display-risk facet:layer:shared facet:family:resource-config
+ *
+ * Operation bar risk level and UI density (summary vs detail).
+ */
 export var ResourceOperationRiskLevel;
 (function (ResourceOperationRiskLevel) {
     ResourceOperationRiskLevel["LOW"] = "low";
@@ -15,6 +20,48 @@ export var ResourceOperationRiskLevel;
     ResourceOperationRiskLevel["HIGH"] = "high";
     ResourceOperationRiskLevel["CRITICAL"] = "critical";
 })(ResourceOperationRiskLevel || (ResourceOperationRiskLevel = {}));
+/**
+ * The **frontend surface** of a resource operation — whether (and how) the
+ * operation is presented in the UI. This is a per-app, per-operation DISPLAY
+ * axis, orthogonal to authorization (roles remain the only security authority).
+ *
+ * Three mutually-exclusive surfaces:
+ *
+ * - `ADDRESSABLE` — the operation has a **URL-routable** view (a deep-linkable
+ *   page that lives in the navigation area; row-click resolves a route). Has an
+ *   action button.
+ * - `EMBEDDED` — the operation has a view that is **not URL-addressable**: it has
+ *   no route of its own and is rendered **within a host**, however that host
+ *   surfaces it — as an overlay/drill-in when invoked standalone, or inline when
+ *   embedded in a composite view or a nested relationship view. Has an action
+ *   button. (This is what `notAddressable()` produces.) Named for the host
+ *   relationship, NOT one presentation: do not assume it always renders as an overlay.
+ * - `API_ONLY` — the operation is **headless**: callable from frontend code as a
+ *   typed API, but has NO rendered interface at all (no page, no embedded view, no
+ *   action button). For operations driven by the system / a workflow / signup rather
+ *   than a user form (e.g. auto-created profiles, engine-authored state).
+ *
+ * `ADDRESSABLE` vs `EMBEDDED` is the URL-routability axis (both have a real view);
+ * `API_ONLY` is the has-no-interface axis. The button-visibility axis
+ * (`ActionVisibility`) is a further orthogonal refinement that only applies to the
+ * two view surfaces.
+ *
+ * Authored on the frontend preset per operation via `addressable()` /
+ * `notAddressable()` / `apiOnly()`; an operation may also declare a
+ * `defaultFrontendPosture` so the framework defaults its surface when no app
+ * preset surfaces it.
+ *
+ * Imported from `@wildo-ai/saas-models`.
+ */
+export var ResourceOperationFrontendSurface;
+(function (ResourceOperationFrontendSurface) {
+    /** URL-routable view (deep-linkable page in the navigation area). */
+    ResourceOperationFrontendSurface["ADDRESSABLE"] = "addressable";
+    /** Non-addressable view rendered within a host — overlay/drill-in when standalone, inline when embedded in a composite or nested relationship view. */
+    ResourceOperationFrontendSurface["EMBEDDED"] = "embedded";
+    /** Headless — callable from code as an API, with no rendered interface at all. */
+    ResourceOperationFrontendSurface["API_ONLY"] = "api_only";
+})(ResourceOperationFrontendSurface || (ResourceOperationFrontendSurface = {}));
 /**
  * Display mode for resource operation action bars — controls operation bar density.
  * SUMMARY = compact row actions (icon-only, in list/table rows).
@@ -29,6 +76,12 @@ export var ResourceOperationDisplayMode;
     /** In a full read/detail view — can show inline labels */
     ResourceOperationDisplayMode["DETAIL"] = "detail";
 })(ResourceOperationDisplayMode || (ResourceOperationDisplayMode = {}));
+/** @wildo_source:part:end saas.models.resource-operation-display-risk */
+/**
+ * @wildo_source:part:start saas.models.resource-primary-scope facet:layer:shared facet:family:resource-config
+ *
+ * Primary execution scope (org, user self, app, anonymous) + anonymous transposition policy.
+ */
 export var ResourcePrimaryScope;
 (function (ResourcePrimaryScope) {
     ResourcePrimaryScope["USER_SELF"] = "user_self";
@@ -51,6 +104,7 @@ export var ResourceTranspositionPolicy;
     /** Skip transposition entirely — anonymous records are not carried over. */
     ResourceTranspositionPolicy["DISCARD"] = "DISCARD";
 })(ResourceTranspositionPolicy || (ResourceTranspositionPolicy = {}));
+/** @wildo_source:part:end saas.models.resource-primary-scope */
 // ============================================================================
 // Primary Scope Field Mappings (Single Source of Truth)
 // ============================================================================
@@ -83,6 +137,29 @@ export const PRIMARY_SCOPE_TO_FIELD_IDENTIFIER = {
  * Derived from PRIMARY_SCOPE_TO_FIELD_IDENTIFIER values.
  */
 export const PRIMARY_SCOPE_FIELD_IDENTIFIERS = Object.values(PRIMARY_SCOPE_TO_FIELD_IDENTIFIER);
+/**
+ * Field identifiers the framework AUTO-POPULATES on a write and therefore omits
+ * from every client-shaped CREATE/UPDATE request DTO — the primary-scope FKs
+ * (`organizationId` / `applicationId` / `userId` / `anonymousUserId`, injected
+ * from the execution context) PLUS the audit FK `createdByUserId` (stamped by
+ * the repository from the initiator). A client is never allowed to author these;
+ * the auto-derivation strips them by NAME (see
+ * `resources-config-operations.dtos-builder.utils.ts` — `applyCreate/UpdateOmissionsToSchema`).
+ *
+ * Single source of truth: the DTO builder consumes this for its omit list, and
+ * `deriveTrustedSystemWritePreservedFields` consumes it to know which
+ * name-stripped fields a TRUSTED in-process system write (via
+ * `SystemAccessBackendService.createAsSystem` / `updateAsSystem`) must re-attach.
+ * Keeping both consumers on one const prevents the two lists from drifting.
+ *
+ * NOTE: intentionally EXCLUDES `_id` / `createdAt` / `updatedAt` / `deletedAt` —
+ * those are timestamp/PK fields handled by `createOrUpdateMandatoryDiscardFields`
+ * (force-removed before validation), never re-attached by a trusted write.
+ */
+export const CONTEXT_AUTO_POPULATED_FIELD_IDENTIFIERS = [
+    'createdByUserId',
+    ...PRIMARY_SCOPE_FIELD_IDENTIFIERS,
+];
 /**
  * Map from field identifier to ResourcePrimaryScope.
  * Built by inverting PRIMARY_SCOPE_TO_FIELD_IDENTIFIER.
@@ -151,6 +228,11 @@ export function getPrimaryScopeFromFieldIdentifier(fieldIdentifier) {
 export function isPrimaryScopeFieldIdentifier(fieldIdentifier) {
     return PRIMARY_SCOPE_FIELD_IDENTIFIERS.includes(fieldIdentifier);
 }
+/**
+ * @wildo_source:part:start saas.models.resource-relationship-cardinality facet:layer:shared facet:family:resource-config
+ *
+ * Cardinality literals plus helpers (`isOneToOneCardinality`, `isArrayCardinality`).
+ */
 export var ResourceRelationshipCardinality;
 (function (ResourceRelationshipCardinality) {
     ResourceRelationshipCardinality["ONE"] = "one";
@@ -192,6 +274,12 @@ export function isArrayCardinality(cardinality) {
     return cardinality === ResourceRelationshipCardinality.MANY ||
         cardinality === ResourceRelationshipCardinality.ONE_OR_MANY;
 }
+/** @wildo_source:part:end saas.models.resource-relationship-cardinality */
+/**
+ * @wildo_source:part:start saas.models.resource-operation-variant-runtime facet:layer:shared facet:family:resource-config
+ *
+ * How an operation variant is invoked and executed (API, cron, repository-only, …).
+ */
 export var ResourceOperationVariantType;
 (function (ResourceOperationVariantType) {
     ResourceOperationVariantType["API_CALL"] = "api_call";
@@ -236,6 +324,12 @@ export var ResourceOperation_OutputPolicy;
     ResourceOperation_OutputPolicy["SUMMARY"] = "summary";
     ResourceOperation_OutputPolicy["CONTEXT"] = "context";
 })(ResourceOperation_OutputPolicy || (ResourceOperation_OutputPolicy = {}));
+/** @wildo_source:part:end saas.models.resource-operation-variant-runtime */
+/**
+ * @wildo_source:part:start saas.models.resource-relationship-access-scope facet:layer:shared facet:family:resource-config
+ *
+ * Route/service access strategy for a relationship (nested vs standalone URLs).
+ */
 /*
  accessScopeStrategy defines how a related resource should be accessed in service, controller, and route generation:
 REQUIRES_CONTEXT: the resource must be accessed within the context of its parent (e.g. nested route, scoped service)
@@ -248,7 +342,10 @@ export var ResourceRelationshipAccessScopeStrategy;
     ResourceRelationshipAccessScopeStrategy["OPTIONAL_CONTEXT"] = "optional_context";
     ResourceRelationshipAccessScopeStrategy["STANDALONE"] = "standalone";
 })(ResourceRelationshipAccessScopeStrategy || (ResourceRelationshipAccessScopeStrategy = {}));
+/** @wildo_source:part:end saas.models.resource-relationship-access-scope */
 /**
+ * @wildo_source:part:start saas.models.relationship-nature-and-models facet:layer:shared facet:family:resource-config
+ *
  * High-level semantic kind of relationship.
  *
  * This is the primary shared meaning. Resolver/runtime layers may later derive
@@ -349,7 +446,10 @@ export var RelationshipReadModel;
     RelationshipReadModel["REFERENCE_ONLY"] = "reference_only";
     RelationshipReadModel["ASSOCIATION_EMBEDDED"] = "association_embedded";
 })(RelationshipReadModel || (RelationshipReadModel = {}));
+/** @wildo_source:part:end saas.models.relationship-nature-and-models */
 /**
+ * @wildo_source:part:start saas.models.relationship-handling-settings facet:layer:shared facet:family:resource-config
+ *
  * Explicit semantic read contract for a relationship.
  *
  * This answers the semantic question "how should this relationship read?" and
@@ -377,12 +477,22 @@ export const RelationshipHandlingMutationSettingsSchema = z.object({
  */
 export const RelationshipHandlingLifecycleOnParentDeleteSettingsSchema = z.object({
     enabled: z.boolean().optional(),
+    /** Execution TIMING of the cascade (IMMEDIATE / LAZY) — orthogonal to `strategy`. */
     mode: z.enum(ChildLifecycleMode).optional(),
+    /**
+     * What the cascade DOES to the child — hard-delete vs impersonalize-and-retain (scrub the personal
+     * fields, keep the row for a legal/audit obligation). Carried on the derived semantic contract so a
+     * consumer reading `handling.lifecycle.onParentDelete` can tell the two apart; omitting it here
+     * would merge two semantically distinct teardowns, which is exactly what splitting this axis from
+     * `mode` exists to prevent.
+     */
+    strategy: z.enum(ChildLifecycleStrategy).optional(),
     maxDepth: z.number().int().min(0).optional(),
 });
 export const RelationshipHandlingLifecycleSettingsSchema = z.object({
     onParentDelete: RelationshipHandlingLifecycleOnParentDeleteSettingsSchema.optional(),
 });
+/** @wildo_source:part:end saas.models.relationship-handling-settings */
 /**
  * Explicit multi-target relationship actions.
  *
@@ -493,6 +603,8 @@ export const ResourceRelationshipBulkActionResultSchema = z.object({
     results: z.array(z.any()),
 });
 /**
+ * @wildo_source:part:start saas.models.relationship-handling-contract facet:layer:shared facet:family:resource-config
+ *
  * Fully resolved relationship handling contract.
  *
  * This describes the engine-facing semantic handling after `nature` has been
@@ -509,10 +621,167 @@ export const RelationshipHandlingContractSchema = z.object({
     mutation: RelationshipHandlingMutationSettingsSchema.optional(),
     lifecycle: RelationshipHandlingLifecycleSettingsSchema.optional(),
 });
+/** @wildo_source:part:end saas.models.relationship-handling-contract */
+export const RelationshipPersistenceForeignKeyContractSchema = z.object({
+    fieldIdentifier: z.string().min(1),
+    /**
+     * The resource that OWNS the FK column (the "holder") — the side whose
+     * documents/rows physically carry `fieldIdentifier`.
+     *
+     * Resolved from cardinality topology (the collection side of a 1:N carries
+     * the FK; 1:1 falls back to the parent-first child convention =
+     * `resourceType2`; self-references hold their own FK). Declaration order is
+     * NOT a holder signal: parent-first `(ORGANIZATIONS, TODOS, ONE, MANY)` and
+     * child-first `(TODOS, USERS, MANY, ONE)` are both valid authoring shapes,
+     * and a positional `resourceType2` read materializes the FK onto the
+     * referenced TARGET of every child-first relationship (e.g. `users` growing
+     * a required `assignedToUserId`/`postedByUserId` column) instead of the
+     * holder. Storage adapters MUST gate FK materialization/validation on
+     * `holderResourceType === <resource under build>`, never on positional
+     * `resourceType1`/`resourceType2` checks.
+     */
+    holderResourceType: ResourceTypeSchema,
+    isArray: z.boolean(),
+    materializeField: z.boolean(),
+    required: z.boolean(),
+    unique: z.boolean(),
+});
+export const RelationshipPersistenceContractSchema = z.object({
+    foreignKey: RelationshipPersistenceForeignKeyContractSchema.optional(),
+});
 export const ResourceRelationshipBaseSchema = z.object({
     resourceType1: ResourceTypeSchema,
     resourceType2: ResourceTypeSchema,
 });
+/**
+ * @wildo_source:part:start saas.models.scope-membership facet:layer:shared facet:family:resource-config
+ *
+ * Write-time scope confinement of a REFERENCE foreign key — the STRUCTURE half.
+ *
+ * A lateral `REFERENCE` FK to a target that is NOT itself tenant-scoped — a `users` id on an
+ * org-scoped row, another `organizations` id — carries no `organizationId` column to compare, so the
+ * ordinary write-integrity tenant check can only confirm the target EXISTS, never that it belongs to
+ * the writer's tenant. That admits a cross-tenant reference (assign a todo to a user from another org).
+ * Declaring `scopeMembership` closes it: the referenced target must have a row in a junction linking it
+ * to the writing row's scope — enforced on CREATE and UPDATE, refused with `404` (identical to the
+ * existing cross-tenant refusal, so nothing leaks).
+ *
+ * **This type carries STRUCTURE ONLY — which junction, and which columns.** It is a fact about the data
+ * shape, uniform across every write. The POLICY half (status / role / field tightening, or disabling)
+ * varies per operation VARIANT and therefore lives on the operation config as `referenceConstraints`
+ * (see {@link ReferenceScopeConstraintSchema}) — beside the caller-side `roles`, where authorization
+ * already lives. Keeping them apart is what stops a relationship from growing its own per-variant
+ * authorization table duplicating the operation/variant structure.
+ *
+ * Fully OPT-IN: a relationship without `scopeMembership` keeps its existing existence-only behavior.
+ */
+export const ScopeMembershipStructureSchema = z.object({
+    /**
+     * The writing row's scope field whose value the target must be a member of. Defaults to the
+     * resource's primary-scope FK (e.g. `organizationId`). Set only when the confining scope is a
+     * non-primary field.
+     */
+    scopeField: z.string().optional(),
+    /**
+     * The junction resource linking scope → target (e.g. `organizationMembers`, `organizationPartnerships`).
+     * Omit to auto-resolve from the registry's `(target, scope)` M:N scope-junction map — which works when
+     * the junction's two sides are DIFFERENT resource types (organizations ↔ users). Name it explicitly for
+     * a SELF-REFERENTIAL junction (organizations ↔ organizations), which the map does not infer.
+     */
+    junction: ResourceTypeSchema.optional(),
+    /**
+     * The junction column holding the SCOPE id (the writer's tenant), e.g. `organizationId`.
+     *
+     * Needed only when convention cannot pick it: for a self-referential junction both columns have the
+     * same resource type, so the guard takes the column NAMED LIKE the writing row's scope field as the
+     * scope side and the other same-typed column as the target side. Set this (with
+     * {@link junctionTargetField}) when the junction names its columns differently
+     * (e.g. `sourceOrganizationId` / `targetOrganizationId`).
+     */
+    junctionScopeField: z.string().optional(),
+    /**
+     * The junction column holding the TARGET id (the referenced row), e.g. `partnerOrganizationId`.
+     * See {@link junctionScopeField} — set both or neither.
+     */
+    junctionTargetField: z.string().optional(),
+});
+/**
+ * Relationship `scopeMembership` value: `true` for the simple case (junction auto-resolved from the
+ * registry's M:N scope-junction map), or a {@link ScopeMembershipStructureSchema} when the junction or
+ * its columns must be named (self-referential junctions, non-primary scope fields).
+ *
+ * Policy — status, roles, junction-field and target-row constraints, or disabling — is NOT here; it is
+ * per-variant and lives on the operation config's `referenceConstraints`.
+ */
+export const ScopeMembershipSchema = z.union([z.literal(true), ScopeMembershipStructureSchema]);
+/**
+ * Write-time scope confinement of a REFERENCE foreign key — the POLICY half, declared PER OPERATION
+ * VARIANT on the operation config (`referenceConstraints`), keyed by foreign-key field.
+ *
+ * The relationship's {@link ScopeMembershipSchema} already guarantees the baseline: the referenced
+ * target must be linked to the writing row's scope through the junction. This type TIGHTENS that
+ * baseline for one variant — the ordinary "assign" accepts any member while a "make reviewer" variant
+ * requires an `ORG_ADMIN`; a plain "share" accepts any partnership while "share with write access"
+ * requires a typed one. It sits beside the operation's own `roles`, which gate the CALLER; these gate
+ * the TARGET.
+ *
+ * Absent for a foreign key ⇒ the relationship's baseline membership applies unchanged. `false` ⇒
+ * enforcement is DISABLED for that foreign key on that variant.
+ *
+ * Note on rigor: the baseline membership check is TENANT ISOLATION and is enforced strictly. The
+ * refinements below are ACCESS MANAGEMENT — `requiredRoles` reuses the shared hierarchy matcher
+ * (`userRolesSatisfyRequiredRoles`), which is deliberately permissive about app-custom roles it cannot
+ * expand rather than fail-closed on them.
+ */
+export const ReferenceScopeConstraintSchema = z.object({
+    /**
+     * Junction-row `status` values that qualify (e.g. `['ACTIVE']`). Omit ⇒ any status qualifies (mere
+     * membership — still refuses a cross-tenant reference). Use to reject e.g. a `SUSPENDED` member.
+     */
+    qualifyingStatuses: z.array(z.string()).optional(),
+    /**
+     * Hierarchy-aware role requirement on the qualifying junction row's `roles` (e.g. the referenced user
+     * must be an `ORG_ADMIN` of the row's organization). Matched with the SAME hierarchy walk the
+     * operation role gate uses — a member holding an ancestor role (e.g. `ORG_OWNER`) satisfies a
+     * requirement of `ORG_ADMIN`. Omit ⇒ no role constraint.
+     */
+    requiredRoles: z.object({
+        scope: z.enum(ResourcePrimaryScope),
+        roles: z.array(z.string()).min(1),
+    }).optional(),
+    /**
+     * Equality constraints on the qualifying JUNCTION row beyond status (e.g. a typed partnership:
+     * `{ partnershipType: 'collaboration' }`). All entries must match. Omit ⇒ no field constraint.
+     */
+    qualifyingFields: z.record(z.string(), z.unknown()).optional(),
+    /**
+     * Equality constraints on the referenced TARGET ROW itself (not the junction) — e.g. the assignee must
+     * be a user of a given type `{ userTypes: 'agent' }`, or a partner org of a given type
+     * `{ type: 'enterprise' }`. Applied to the target row the guard already reads. Omit ⇒ none.
+     */
+    targetConstraints: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * An operation variant's per-foreign-key reference policy: `foreignKeyField → constraint | false`.
+ *
+ * `false` WAIVES the scope-membership requirement for that foreign key on this variant (a break-glass
+ * verb that must write a not-yet-member reference). It waives that and nothing else: the target must
+ * still EXIST, and an ORG-SCOPED target must still share the write's tenant.
+ *
+ * ⚠️ **On an ORG-LESS target the junction IS the tenant signal.** `users` and `organizations` carry no
+ * tenant column to fall back on, so waiving membership there reduces the check to existence and a
+ * cross-tenant id becomes admissible. That is occasionally the intent (an incident override), but it is
+ * never incidental — reach for a narrower policy first (a wider `qualifyingStatuses`, or a second
+ * junction that models the exception) and use `false` only when the variant genuinely means
+ * "any existing row, tenant notwithstanding".
+ */
+export const ReferenceConstraintsSchema = z.record(z.string(), z.union([z.literal(false), ReferenceScopeConstraintSchema]));
+/** @wildo_source:part:end saas.models.scope-membership */
+/**
+ * @wildo_source:part:start saas.models.resource-relationship-schema facet:layer:shared facet:family:resource-config
+ *
+ * Serializable relationship declaration fields validated at registry build.
+ */
 export const ResourceRelationshipSchema = z.object({
     cardinality1: z.enum(ResourceRelationshipCardinality),
     cardinality2: z.enum(ResourceRelationshipCardinality),
@@ -616,7 +885,51 @@ export const ResourceRelationshipSchema = z.object({
      * - M:N self-reference: TODOS → TODOS via junction table uses todoId/targetTodoId (explicit)
      */
     foreignKeyField: z.string().optional(),
+    /**
+     * Scope-via-junction tag (scope-required reference search).
+     *
+     * Set ONLY on the synthetic `S → T` edge the M:N expansion adds so a target
+     * `T` (e.g. `users`) becomes addressable under a scope `S` (e.g.
+     * `organizations`) for SEARCH/LIST — e.g.
+     * `GET /organizations/{organizationId}/users/search`. Names the junction `J`
+     * (e.g. `organizationMembers`) the scope is resolved through. `T` carries NO
+     * real foreign-key column for `S`, so the backend contextual filter scopes via
+     * a junction subquery (`T._id ∈ { J.targetFk : J.scopeFk = S_id }`) and
+     * authorization keys off `S`-membership instead of `T`'s own primary scope.
+     * Absent on every normal relationship.
+     *
+     * NOTE: this is a READ/SEARCH-side tag on a synthetic scope-anchored edge. To constrain a WRITE — a
+     * real reference FK must point at a member of the writer's scope — declare {@link scopeMembership},
+     * NOT this field.
+     */
+    scopeViaJunction: ResourceTypeSchema.optional(),
+    /**
+     * Write-time SCOPE CONFINEMENT for this reference FK — the STRUCTURE half (see
+     * {@link ScopeMembershipSchema}).
+     *
+     * Opt-in and additive: absent ⇒ unchanged existence-only behavior. `scopeMembership: true` requires
+     * the referenced target to be linked to the writing row's scope through the auto-resolved junction;
+     * the object form names the junction / columns when convention cannot (self-referential junctions).
+     * Enforced on CREATE and UPDATE by the adapter-neutral write-integrity authority; a non-member /
+     * cross-tenant reference is refused with `404`, leaking nothing.
+     *
+     * POLICY (status, roles, junction-field / target-row constraints, or disabling) is NOT declared here —
+     * it varies per operation variant and lives on the operation config as `referenceConstraints`
+     * (see {@link ReferenceScopeConstraintSchema}), beside the caller-side `roles`.
+     */
+    scopeMembership: ScopeMembershipSchema.optional(),
+    /**
+     * Restricts which core operations' URLs this relationship contributes to.
+     *
+     * When set, the URL builder emits this parent edge ONLY for the listed core
+     * operations (e.g. `[SEARCH, LIST]`). Used by the scope-via-junction edge so it
+     * produces `/{scope}/{target}/search|list` without leaking onto
+     * READ/CREATE/UPDATE/DELETE routes — a peer-under-scope path is a read-only
+     * access pattern. Absent ⇒ the edge contributes to every operation's URLs.
+     */
+    urlOperationScope: z.array(z.enum(CoreResourceOperation)).optional(),
 });
+/** @wildo_source:part:end saas.models.resource-relationship-declaration */
 // --------------------------------
 // Default Operation Response Patterns
 // --------------------------------
@@ -699,10 +1012,93 @@ export function getDefaultResponseSchemaForOperation(operation, mainSchema) {
             return mainSchema;
     }
 }
+/**
+ * Core operations whose service-layer OUTPUT is validated against their declared RESPONSE
+ * envelope (a framework `Default*ResponseSchema`), NOT against the resource object. For these,
+ * the DTO builder sets `internalDto` to the response envelope (`responseDtoInternal`) instead of
+ * `enhancedMainSchema` — otherwise output validation parses the envelope value against the resource
+ * schema and throws `service_resource_transformation_failed` (HTTP 500).
+ *
+ * ⚠️ KEY ON THE OPERATION'S OWN `operationIdentifier`, NOT `resourceOperationLike` /
+ * `effectiveOperation`. `resourceOperationLike` is a ROUTING / HTTP-verb / authorization hint — a
+ * CUSTOM operation may borrow `DELETE`/`COUNT` semantics for its URL and permissions while returning
+ * its own object shape (via `REPLACE_CORE_OPERATIONS` or a `customResponseDto`, e.g. SIEM
+ * `PURGE_ALL` → `{ purgedCount, … }`). Only
+ * the genuine core operation carries `operationIdentifier === CoreResourceOperation.DELETE` etc.;
+ * custom ops carry a custom identifier. Keying on `operationIdentifier` is what stops the composer
+ * wrapping a custom op's object as `{ id: <object> }`.
+ *
+ * Membership rationale:
+ *  - `DELETE` / `DELETE_MANY` — the service+repository layer returns the deleted id(s) as a bare
+ *    scalar; {@link composeDefaultOperationResponse} lifts that into the envelope.
+ *  - `COUNT` — the service already returns `{ count }`, so no composition is needed, but its
+ *    `internalDto` must still be the `{ count }` envelope rather than the resource object.
+ *
+ * Deliberately EXCLUDED: bulk mutations (`CREATE_MANY` / `UPDATE_MANY`). At runtime they return an
+ * ARRAY of resource items that the transform/serializer validate PER-ITEM against the resource
+ * schema (see the `isBulkOperation` branch in `getDefaultResponseSchemaForOperation` /
+ * `buildEnhancedResponseDto`) — they are object-shaped per item, not a count envelope, so they
+ * must keep `enhancedMainSchema`.
+ *
+ * Keep this set, {@link composeDefaultOperationResponse}, and the `internalDto` routing in the DTO
+ * builder in lockstep.
+ */
+export const OUTPUT_ENVELOPE_OPERATIONS = [
+    CoreResourceOperation.DELETE,
+    CoreResourceOperation.DELETE_MANY,
+    CoreResourceOperation.COUNT,
+];
+/** True when this is a genuine core envelope operation (see {@link OUTPUT_ENVELOPE_OPERATIONS}).
+ * Pass the operation's OWN `operationIdentifier`, never `resourceOperationLike`/`effectiveOperation`
+ * (a custom op borrowing the verb has a custom identifier and returns its own shape). */
+export function isOutputEnvelopeOperation(operationIdentifier) {
+    return OUTPUT_ENVELOPE_OPERATIONS.includes(operationIdentifier);
+}
+/**
+ * Value-level twin of {@link getDefaultResponseSchemaForOperation}: composes an operation's
+ * DECLARED default response value from the raw service/repository output, so the value that flows
+ * into output validation (`transformOutput`) and response serialization matches the declared
+ * schema. This is the single, GENERAL seam for "the runtime returns a lower-level value than the
+ * declared response envelope" — callers invoke it uniformly instead of special-casing operations.
+ *
+ * ⚠️ Pass the operation's OWN `operationIdentifier`, NOT `resourceOperationLike`/`effectiveOperation`
+ * (see {@link OUTPUT_ENVELOPE_OPERATIONS}). And callers MUST skip composition when the operation
+ * declares its own `customResponseDto` (`hasCustomResponseDto`) — that op returns its custom shape
+ * directly, exactly as `buildEnhancedResponseDto` lets a custom `responseDto` win over the default.
+ * Both guards together keep this a true identity for every operation that already returns its final
+ * shape, so ONLY genuine core `DELETE`/`DELETE_MANY` are ever transformed.
+ *
+ * Identity for every operation whose service output already IS its declared shape: `READ` /
+ * `CREATE` / `UPDATE` (resource object), `CREATE_MANY` / `UPDATE_MANY` (array of items, validated
+ * per-item), `COUNT` (`{ count }`), `LIST` / `SEARCH` (`{ data, pagination }`), and every custom
+ * operation (its own DTO value). The only non-identity cases are the core deletes, whose repository
+ * layer returns the deleted id(s) as a bare scalar (`delete(): Promise<string>` — the `_id`, or
+ * `''` when nothing matched; `deleteMany(): Promise<string[]>`):
+ *  - `DELETE`      → `{ id }`                        (`DefaultDeleteResponseSchema`)
+ *  - `DELETE_MANY` → `{ deletedIds, deletedCount }`  (`DefaultBulkDeleteResponseSchema`)
+ *
+ * `DELETE` always wraps as `{ id }`. If a singular `DELETE` is invoked with a filter it delegates to
+ * `deleteMany` and returns a `string[]` (a misuse that should target `DELETE_MANY`); that becomes
+ * `{ id: string[] }` and downstream `internalDto` validation surfaces the anomaly rather than
+ * silently coercing it. Likewise a non-array `DELETE_MANY` output passes through to fail validation.
+ * Keep this switch in lockstep with {@link getDefaultResponseSchemaForOperation} and
+ * {@link OUTPUT_ENVELOPE_OPERATIONS}.
+ */
+export function composeDefaultOperationResponse(operationIdentifier, serviceOutput) {
+    switch (operationIdentifier) {
+        case CoreResourceOperation.DELETE:
+            return { id: serviceOutput };
+        case CoreResourceOperation.DELETE_MANY:
+            return Array.isArray(serviceOutput)
+                ? { deletedIds: serviceOutput, deletedCount: serviceOutput.length }
+                : serviceOutput;
+        default:
+            return serviceOutput;
+    }
+}
 // Utility to determine if operation should have request DTO
 export function operationShouldHaveRequestDto(operation) {
-    const operationsWithoutRequestDto = ['read', 'list', 'delete', 'count'];
-    return !operationsWithoutRequestDto.includes(operation);
+    return !OPERATIONS_WITHOUT_REQUEST_BODY.includes(operation);
 }
 /**
  * Supported ID format types
@@ -713,5 +1109,185 @@ export var ResourceIdFormat;
     ResourceIdFormat["OBJECT_ID"] = "OBJECT_ID";
     /** PostgreSQL UUID - 36 character UUID with dashes */
     ResourceIdFormat["UUID"] = "UUID";
+    /**
+     * The synthesized id of an `HTTP_API`-backed resource: encoded (or charset-safe verbatim) remote
+     * key components, produced ONLY by the codec authority in
+     * `http-api-binding/http-api-binding-id.shared.utils.ts` — never minted. Lexical shape: the
+     * charset law `^[A-Za-z0-9._~-]+$`. Deliberately NOT added to `detectIdFormat` /
+     * `isValidResourceId` (the strict two-format world stays strict for platform-backed rows —
+     * paper A: never loosen a shared validator silently); it participates only where the RESOURCE
+     * is known to be HTTP_API-backed (`ResourceIdBackendService.getFormatForResource`).
+     */
+    ResourceIdFormat["HTTP_API_SYNTHESIZED"] = "HTTP_API_SYNTHESIZED";
+    /**
+     * The synthesized id of an `INTROSPECTION`-backed resource: the key of a row DERIVED from the
+     * application's own structure, never minted and never stored.
+     *
+     * A distinct member from {@link HTTP_API_SYNTHESIZED} even though both admit the same charset,
+     * because they answer different questions and will diverge: an HTTP-API id encodes a REMOTE
+     * entity's key through a codec that can round-trip it, while an introspected id is whatever the
+     * companion behavior's projection already calls the row — a module name, a composed structural
+     * key. Merging them would put one name on two origins, and the next reader could not tell which
+     * validator's rules a given id was admitted under.
+     *
+     * Like its sibling it is deliberately absent from `detectIdFormat` / `isValidResourceId`: the
+     * strict two-format world stays strict for platform-backed rows, and this widening applies only
+     * where the RESOURCE is known to be INTROSPECTION-backed.
+     */
+    ResourceIdFormat["INTROSPECTION_SYNTHESIZED"] = "INTROSPECTION_SYNTHESIZED";
 })(ResourceIdFormat || (ResourceIdFormat = {}));
-//# sourceMappingURL=resources.shared.schemas.js.map
+/** @wildo_source:part:end saas.models.resource-config.forwarded-label */
+/**
+ * Stringify one forwarded field value, locale-aware where a localized
+ * representation exists. Strings pass through verbatim (the canonical
+ * label case — names, emails). `Date`/`number` use `Intl` with the optional
+ * request locale. Enum-value LABEL translation is intentionally NOT done here:
+ * resolving an app's enum labels is a frontend/display concern with no
+ * server-side resolver in this path; forwarded labels are identity/text by
+ * design. The `locale` param is the extension point if that ever changes.
+ */
+function stringifyForwardedValue(value, locale) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (value instanceof Date) {
+        return new Intl.DateTimeFormat(locale).format(value);
+    }
+    if (typeof value === 'number') {
+        return new Intl.NumberFormat(locale).format(value);
+    }
+    return String(value);
+}
+/**
+ * Pure renderer for a {@link LabelRelationDescriptor}: join the descriptor's
+ * `fields` (in declared order, skipping empty values) from a resolved related
+ * row, using `separator`, falling back to `fallback` when the row is absent or
+ * the result is empty. Exported so it is unit-testable independently of the
+ * virtual-field runtime.
+ */
+export function renderForwardedLabel(relatedRow, descriptor, options) {
+    const fallback = descriptor.fallback ?? '';
+    if (!relatedRow) {
+        return fallback;
+    }
+    const separator = descriptor.separator ?? ' ';
+    const rendered = descriptor.fields
+        .map((field) => stringifyForwardedValue(relatedRow[field], options?.locale))
+        .filter((part) => part.trim().length > 0)
+        .join(separator)
+        .trim();
+    return rendered.length > 0 ? rendered : fallback;
+}
+/**
+ * Request-scoped dedup cache for forwarded-label related reads. Keyed by the
+ * `executionContext` object (one per request), so concurrent per-row virtual-field
+ * computations across a single LIST/SEARCH page that resolve the SAME related key
+ * share one in-flight read. This matches the framework's existing batch standard
+ * (`populateListForSummary`: dedup + parallel, one read per UNIQUE key), without a
+ * separate batch pre-pass. The `WeakMap` lets a finished request's cache be GC'd.
+ */
+const labelForwardingRequestCache = new WeakMap();
+function resolveRelatedRowDeduped(executionContext, cacheKey, loader) {
+    // No usable request key (e.g. a direct unit invocation) → resolve uncached.
+    if (executionContext === null || typeof executionContext !== 'object') {
+        return loader();
+    }
+    let perRequest = labelForwardingRequestCache.get(executionContext);
+    if (!perRequest) {
+        perRequest = new Map();
+        labelForwardingRequestCache.set(executionContext, perRequest);
+    }
+    let inFlight = perRequest.get(cacheKey);
+    if (!inFlight) {
+        inFlight = loader();
+        perRequest.set(cacheKey, inFlight);
+    }
+    return inFlight;
+}
+/**
+ * Build a VIRTUAL summary field that labels a row from a related resource per a
+ * {@link LabelRelationDescriptor}. Drop it into a resource's main schema; the
+ * frontend then references the field name in `getFrontendResourceLabel` (a plain,
+ * synchronous field ref — no async resolver).
+ *
+ * The returned field is `isVirtual` (computed, never persisted; excluded from
+ * request DTOs), `isSummaryField` (included in the SUMMARY DTO, so it is present
+ * in LIST/collection rows, not only on READ), and `isHidden({ display: true })`
+ * (it IS the row/title label, so it must never ALSO auto-render as a standalone
+ * card field or table column — `detectSummaryFields` skips display-hidden fields;
+ * the value still reaches the frontend label, which reads the field by name). At
+ * read time the framework's
+ * `VirtualFieldsBackendService` invokes the `calculate` below with the backend
+ * `utils`. `calculate`:
+ *   1. reads the join value from `currentObject[localField]`;
+ *   2. resolves the related row via the related repository's system read
+ *      `findFieldValuesByJoinField` (the read-direction sibling of the search
+ *      join's `findSearchMatchTargetIds`), deduped per request (see
+ *      {@link resolveRelatedRowDeduped});
+ *   3. renders the label via {@link renderForwardedLabel}.
+ * Failure modes (missing value, unavailable repo, absent/empty related row) degrade
+ * to the fallback chain — `descriptor.fallbackField`'s own-field value first, else
+ * `descriptor.fallback`; `calculate` never throws.
+ *
+ * @remarks `dependencies: [localField]` is consumed by the repository DTO builder
+ * (`repository-dto-builder.utils.ts`), which adds the dependency to the read
+ * projection — so `calculate` receives the join value even when `localField` is
+ * not itself a summary field. (On `organizationMembers`, `userId` is independently
+ * a summary field too.)
+ */
+export function forwardedLabel(descriptor) {
+    const joinField = descriptor.relatedJoinField ?? '_id';
+    return z
+        .string()
+        .optional()
+        .isVirtual({
+        dependencies: [descriptor.localField],
+        calculate: async ({ currentObject, executionContext, utils }) => {
+            const row = currentObject;
+            // Fallback chain: prefer an own-field identifier (e.g. an immutable
+            // `userEmail`) over the static string, so an unresolvable related label
+            // degrades to a human value rather than a raw id. Applied on EVERY
+            // non-resolution path (no join value, no repo, missing/empty related row).
+            const resolveFallback = () => {
+                if (descriptor.fallbackField) {
+                    const own = row?.[descriptor.fallbackField];
+                    if (own !== null && own !== undefined && String(own).trim().length > 0) {
+                        return String(own);
+                    }
+                }
+                return descriptor.fallback ?? '';
+            };
+            const rawValue = row?.[descriptor.localField];
+            if (rawValue === null || rawValue === undefined || rawValue === '') {
+                return resolveFallback();
+            }
+            const joinValue = String(rawValue);
+            const relatedRepository = utils?.repositories?.getRepository?.(descriptor.relatedResource);
+            if (!relatedRepository || typeof relatedRepository.findFieldValuesByJoinField !== 'function') {
+                return resolveFallback();
+            }
+            const cacheKey = `${descriptor.relatedResource}|${joinField}|${joinValue}`;
+            const relatedRow = await resolveRelatedRowDeduped(executionContext, cacheKey, async () => {
+                // Fail-safe: a related-read error resolves to "no row" (→ fallback),
+                // never a throw. Resolving (rather than rejecting) also keeps the
+                // per-request dedup cache from storing a rejected promise that would
+                // re-throw for every other row sharing this join value.
+                try {
+                    const rowsByValue = await relatedRepository.findFieldValuesByJoinField(joinField, [joinValue], descriptor.fields);
+                    return rowsByValue.get(joinValue);
+                }
+                catch (error) {
+                    utils?.logger?.warn?.(`[forwardedLabel] related read failed for ${descriptor.relatedResource}.${joinField}=${joinValue}; using fallback`, error);
+                    return undefined;
+                }
+            });
+            // Render the related fields; if nothing renders, run the fallback chain
+            // (own-field → static) — pass an empty static fallback to detect "empty".
+            const rendered = renderForwardedLabel(relatedRow, { ...descriptor, fallback: '' });
+            return rendered.length > 0 ? rendered : resolveFallback();
+        },
+    })
+        .isSummaryField()
+        .isHidden({ display: true });
+}
+//# sourceMappingURL=resources.shared.schemas.js.map