@wildo-ai/saas-models 1.0.1 → 1.1.0

package/dist/esm/resources/utils/required-fk-fillability.validation.js

@@ -0,0 +1,186 @@
+import { isOptional, isExcludedFromCreate, getObjectShape, isDiscriminatedUnion, getZodDefArrayProperty, isZodTypeAny, } from '@wildo-ai/zod-decorators';
+import { ResourceRelationshipAccessScopeStrategy, RelationshipNature, } from '../resources.shared.schemas.js';
+import { CoreResourceOperation } from '../resources.shared.core.definitions.js';
+/**
+ * Registry-level guardrail: a REQUIRED composition-parent foreign key must be
+ * **user-fillable on CREATE**.
+ *
+ * ## Why this exists
+ *
+ * A resource whose structural (COMPOSITION) parent relationship is
+ * `OPTIONAL_CONTEXT` (or `STANDALONE`) can be created WITHOUT that parent in the
+ * URL — e.g. a todo created from the org-wide collection rather than from inside
+ * a specific list. In that mode the parent FK is NOT seeded from routing context,
+ * so the create form must let the user supply it through a resource-reference
+ * picker. If the FK is also REQUIRED, the create is impossible unless that picker
+ * can actually be rendered and populated. Two ways it silently can't:
+ *
+ * - the FK field is `excludeFromCreate` → there is no form control at all; or
+ * - the FK's target resource exposes no `LIST`/`SEARCH` operation → the picker
+ *   has no operation to load its options from.
+ *
+ * Either way the org-wide create form is dead on arrival. This validator surfaces
+ * that at registry-assembly time instead of as a confusing client-side validation
+ * failure with no visible error (the exact symptom of the 2026-06-27
+ * `todoListId`-create bug — see `selectMatchingRoutePath` routing fix and
+ * `.claude/plans/todos-required-fk-optional-context-create.md`).
+ *
+ * ## Why it is restricted to `COMPOSITION` parents
+ *
+ * `REFERENCE` foreign keys (`assignedToUserId`, `createdByUserId`,
+ * `postedByUserId`, …) are NOT user-picked structural parents — they are
+ * cross-references that are typically seeded by the backend (author/creator) or
+ * are optional. The framework has no schema-level "user fills this vs the backend
+ * sets this" marker, so including REFERENCE FKs here would false-positive on
+ * backend-set required FKs. Limiting to `COMPOSITION` isolates the genuine
+ * "a child belongs to a parent the user must choose" case.
+ *
+ * ## Fail-open by construction
+ *
+ * Every ambiguity skips the relationship rather than flagging it: a missing
+ * `foreignKeyField`, an FK column that is not actually present on the resource's
+ * own schema (e.g. an inbound FK reference where another resource holds the key),
+ * an FK whose requiredness cannot be determined, or an unknown target resource.
+ * This keeps the guardrail noise-free and safe to run across every app registry.
+ */
+export var ForeignKeyFillabilityViolationKind;
+(function (ForeignKeyFillabilityViolationKind) {
+    /** The required FK is `excludeFromCreate` yet the parent is not guaranteed in context — no way to supply it. */
+    ForeignKeyFillabilityViolationKind["EXCLUDED_FROM_CREATE"] = "required-composition-fk-excluded-from-create";
+    /** The required FK needs a picker (parent is `OPTIONAL_CONTEXT`/`STANDALONE`) but its target exposes no LIST/SEARCH op to populate one. */
+    ForeignKeyFillabilityViolationKind["TARGET_NOT_SEARCHABLE"] = "required-composition-fk-target-not-searchable";
+})(ForeignKeyFillabilityViolationKind || (ForeignKeyFillabilityViolationKind = {}));
+/**
+ * Severity a consumer should apply to a violation. `EXCLUDED_FROM_CREATE` is a
+ * genuinely impossible-to-create config (no context, no control) → `FAIL` so the
+ * backend crashes loud at boot rather than shipping a dead create form.
+ * `TARGET_NOT_SEARCHABLE` degrades the picker but a custom create surface might
+ * still supply the FK → `WARN`.
+ */
+export var ForeignKeyFillabilityViolationSeverity;
+(function (ForeignKeyFillabilityViolationSeverity) {
+    ForeignKeyFillabilityViolationSeverity["FAIL"] = "fail";
+    ForeignKeyFillabilityViolationSeverity["WARN"] = "warn";
+})(ForeignKeyFillabilityViolationSeverity || (ForeignKeyFillabilityViolationSeverity = {}));
+const VIOLATION_SEVERITY = {
+    [ForeignKeyFillabilityViolationKind.EXCLUDED_FROM_CREATE]: ForeignKeyFillabilityViolationSeverity.FAIL,
+    [ForeignKeyFillabilityViolationKind.TARGET_NOT_SEARCHABLE]: ForeignKeyFillabilityViolationSeverity.WARN,
+};
+/**
+ * Resolve a field schema by name from a resource's `mainSchema`, transparently
+ * handling discriminated-union (polymorphic / schema-family) resources where a
+ * plain `getObjectShape` returns `null`. The FK lives in the family's common
+ * base, so it is present on every variant — the first variant that carries it
+ * wins. Returns `undefined` when the field is genuinely absent (fail-open).
+ */
+export function findForeignKeyFieldSchema(mainSchema, foreignKeyField) {
+    const directShape = getObjectShape(mainSchema);
+    if (directShape && directShape[foreignKeyField]) {
+        return directShape[foreignKeyField];
+    }
+    if (isDiscriminatedUnion(mainSchema)) {
+        const options = getZodDefArrayProperty(mainSchema, 'options') ?? [];
+        for (const option of options) {
+            if (!isZodTypeAny(option)) {
+                continue;
+            }
+            const optionShape = getObjectShape(option);
+            if (optionShape && optionShape[foreignKeyField]) {
+                return optionShape[foreignKeyField];
+            }
+        }
+    }
+    return undefined;
+}
+/** True when the resource exposes an operation a reference picker can load options from (LIST or SEARCH, core or `resourceOperationLike`). */
+function hasPickerCapableOperation(resource) {
+    return resource.operations.some((operation) => {
+        const core = operation.resourceOperationLike ?? operation.operationIdentifier;
+        return (operation.operationIdentifier === CoreResourceOperation.LIST ||
+            operation.operationIdentifier === CoreResourceOperation.SEARCH ||
+            core === CoreResourceOperation.LIST ||
+            core === CoreResourceOperation.SEARCH);
+    });
+}
+/**
+ * Validate that every required COMPOSITION-parent foreign key in the registry is
+ * user-fillable on CREATE. Returns the list of violations (empty when clean);
+ * the caller decides how to surface them (warn vs fail). Pure and side-effect
+ * free.
+ *
+ * @param resourceConfigurations - the registry's `resourceConfigurations` map
+ *   (`resourceType → configuration`).
+ */
+export function validateRequiredForeignKeyFillability(resourceConfigurations) {
+    const violations = [];
+    for (const resource of Object.values(resourceConfigurations)) {
+        const parentRelationships = resource.resourceRelationships?.parentRelationships ?? [];
+        for (const relationship of parentRelationships) {
+            // Only structural (COMPOSITION) parents are user-picked — REFERENCE FKs are
+            // backend-set / optional and would false-positive.
+            if (relationship.nature !== RelationshipNature.COMPOSITION) {
+                continue;
+            }
+            // Primary scope and REQUIRES_CONTEXT parents are ALWAYS present in the URL,
+            // so the FK is always seeded from context — never needs a picker.
+            if (relationship.isPrimaryScope) {
+                continue;
+            }
+            if (relationship.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.REQUIRES_CONTEXT) {
+                continue;
+            }
+            const foreignKeyField = relationship.foreignKeyField;
+            if (!foreignKeyField) {
+                continue;
+            }
+            // The FK must actually be a column on THIS resource's own schema. If it is
+            // not (e.g. an inbound FK reference where another resource holds the key),
+            // skip — fail-open.
+            const fkFieldSchema = findForeignKeyFieldSchema(resource.mainSchema, foreignKeyField);
+            if (!fkFieldSchema) {
+                continue;
+            }
+            // Optional FK → leaving it empty on org-wide create is valid; not a problem.
+            if (isOptional(fkFieldSchema)) {
+                continue;
+            }
+            const parentResourceType = relationship.resourceType1;
+            if (isExcludedFromCreate(fkFieldSchema)) {
+                violations.push({
+                    kind: ForeignKeyFillabilityViolationKind.EXCLUDED_FROM_CREATE,
+                    severity: VIOLATION_SEVERITY[ForeignKeyFillabilityViolationKind.EXCLUDED_FROM_CREATE],
+                    resourceType: resource.resourceIdentifier,
+                    foreignKeyField,
+                    parentResourceType,
+                    message: `Resource '${resource.resourceIdentifier}' requires foreign key '${foreignKeyField}' ` +
+                        `(composition parent '${parentResourceType}', accessScopeStrategy='${relationship.accessScopeStrategy ?? 'unset'}'), ` +
+                        `but the field is excludeFromCreate AND the parent is not guaranteed in routing context. ` +
+                        `The create form can neither seed it from context nor offer a picker → org-wide create is impossible. ` +
+                        `Make the parent REQUIRES_CONTEXT (create always nested under the parent), or drop excludeFromCreate so a picker can render.`,
+                });
+                continue;
+            }
+            const parentResource = resourceConfigurations[parentResourceType];
+            if (!parentResource) {
+                // Unknown target (partial registry / cross-package boundary) → fail-open.
+                continue;
+            }
+            if (!hasPickerCapableOperation(parentResource)) {
+                violations.push({
+                    kind: ForeignKeyFillabilityViolationKind.TARGET_NOT_SEARCHABLE,
+                    severity: VIOLATION_SEVERITY[ForeignKeyFillabilityViolationKind.TARGET_NOT_SEARCHABLE],
+                    resourceType: resource.resourceIdentifier,
+                    foreignKeyField,
+                    parentResourceType,
+                    message: `Resource '${resource.resourceIdentifier}' requires foreign key '${foreignKeyField}' ` +
+                        `(composition parent '${parentResourceType}', accessScopeStrategy='${relationship.accessScopeStrategy ?? 'unset'}'), ` +
+                        `which must be chosen via a reference picker on org-wide create — but target '${parentResourceType}' ` +
+                        `exposes no LIST or SEARCH operation, so the picker cannot load options. ` +
+                        `Add a LIST/SEARCH operation to '${parentResourceType}', or make the parent REQUIRES_CONTEXT.`,
+                });
+            }
+        }
+    }
+    return violations;
+}
+//# sourceMappingURL=required-fk-fillability.validation.js.map

package/dist/esm/resources/utils/required-fk-fillability.validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-fk-fillability.validation.js","sourceRoot":"","sources":["../../../../../src/resources/utils/required-fk-fillability.validation.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport {\n  isOptional,\n  isExcludedFromCreate,\n  getObjectShape,\n  isDiscriminatedUnion,\n  getZodDefArrayProperty,\n  isZodTypeAny,\n} from '@wildo-ai/zod-decorators';\nimport {\n  ResourceRelationship,\n  ResourceRelationshipAccessScopeStrategy,\n  RelationshipNature,\n} from '../resources.shared.schemas';\nimport { ResourceType, CoreResourceOperation } from '../resources.shared.core.definitions';\n\n/**\n * Registry-level guardrail: a REQUIRED composition-parent foreign key must be\n * **user-fillable on CREATE**.\n *\n * ## Why this exists\n *\n * A resource whose structural (COMPOSITION) parent relationship is\n * `OPTIONAL_CONTEXT` (or `STANDALONE`) can be created WITHOUT that parent in the\n * URL — e.g. a todo created from the org-wide collection rather than from inside\n * a specific list. In that mode the parent FK is NOT seeded from routing context,\n * so the create form must let the user supply it through a resource-reference\n * picker. If the FK is also REQUIRED, the create is impossible unless that picker\n * can actually be rendered and populated. Two ways it silently can't:\n *\n * - the FK field is `excludeFromCreate` → there is no form control at all; or\n * - the FK's target resource exposes no `LIST`/`SEARCH` operation → the picker\n *   has no operation to load its options from.\n *\n * Either way the org-wide create form is dead on arrival. This validator surfaces\n * that at registry-assembly time instead of as a confusing client-side validation\n * failure with no visible error (the exact symptom of the 2026-06-27\n * `todoListId`-create bug — see `selectMatchingRoutePath` routing fix and\n * `.claude/plans/todos-required-fk-optional-context-create.md`).\n *\n * ## Why it is restricted to `COMPOSITION` parents\n *\n * `REFERENCE` foreign keys (`assignedToUserId`, `createdByUserId`,\n * `postedByUserId`, …) are NOT user-picked structural parents — they are\n * cross-references that are typically seeded by the backend (author/creator) or\n * are optional. The framework has no schema-level \"user fills this vs the backend\n * sets this\" marker, so including REFERENCE FKs here would false-positive on\n * backend-set required FKs. Limiting to `COMPOSITION` isolates the genuine\n * \"a child belongs to a parent the user must choose\" case.\n *\n * ## Fail-open by construction\n *\n * Every ambiguity skips the relationship rather than flagging it: a missing\n * `foreignKeyField`, an FK column that is not actually present on the resource's\n * own schema (e.g. an inbound FK reference where another resource holds the key),\n * an FK whose requiredness cannot be determined, or an unknown target resource.\n * This keeps the guardrail noise-free and safe to run across every app registry.\n */\nexport enum ForeignKeyFillabilityViolationKind {\n  /** The required FK is `excludeFromCreate` yet the parent is not guaranteed in context — no way to supply it. */\n  EXCLUDED_FROM_CREATE = 'required-composition-fk-excluded-from-create',\n  /** The required FK needs a picker (parent is `OPTIONAL_CONTEXT`/`STANDALONE`) but its target exposes no LIST/SEARCH op to populate one. */\n  TARGET_NOT_SEARCHABLE = 'required-composition-fk-target-not-searchable',\n}\n\n/**\n * Severity a consumer should apply to a violation. `EXCLUDED_FROM_CREATE` is a\n * genuinely impossible-to-create config (no context, no control) → `FAIL` so the\n * backend crashes loud at boot rather than shipping a dead create form.\n * `TARGET_NOT_SEARCHABLE` degrades the picker but a custom create surface might\n * still supply the FK → `WARN`.\n */\nexport enum ForeignKeyFillabilityViolationSeverity {\n  FAIL = 'fail',\n  WARN = 'warn',\n}\n\nconst VIOLATION_SEVERITY: Record<ForeignKeyFillabilityViolationKind, ForeignKeyFillabilityViolationSeverity> = {\n  [ForeignKeyFillabilityViolationKind.EXCLUDED_FROM_CREATE]: ForeignKeyFillabilityViolationSeverity.FAIL,\n  [ForeignKeyFillabilityViolationKind.TARGET_NOT_SEARCHABLE]: ForeignKeyFillabilityViolationSeverity.WARN,\n};\n\nexport interface ForeignKeyFillabilityViolation {\n  kind: ForeignKeyFillabilityViolationKind;\n  severity: ForeignKeyFillabilityViolationSeverity;\n  /** The child resource that declares the required FK. */\n  resourceType: ResourceType;\n  /** The FK field on `resourceType` (e.g. `todoListId`). */\n  foreignKeyField: string;\n  /** The FK target / structural parent (e.g. `todoLists`). */\n  parentResourceType: ResourceType;\n  message: string;\n}\n\n/**\n * Structural subset of a resource configuration this validator needs. The real\n * `ResourceConfiguration` (and its frontend/backend variants) satisfy this shape,\n * so callers can pass `registry.resourceConfigurations` directly.\n */\nexport interface ForeignKeyFillabilityResourceInput {\n  resourceIdentifier: ResourceType;\n  mainSchema: z.ZodTypeAny;\n  resourceRelationships: {\n    parentRelationships: ResourceRelationship[];\n  };\n  operations: ReadonlyArray<{\n    operationIdentifier: string | number;\n    resourceOperationLike?: string | number;\n  }>;\n}\n\n/**\n * Resolve a field schema by name from a resource's `mainSchema`, transparently\n * handling discriminated-union (polymorphic / schema-family) resources where a\n * plain `getObjectShape` returns `null`. The FK lives in the family's common\n * base, so it is present on every variant — the first variant that carries it\n * wins. Returns `undefined` when the field is genuinely absent (fail-open).\n */\nexport function findForeignKeyFieldSchema(\n  mainSchema: z.ZodTypeAny,\n  foreignKeyField: string,\n): z.ZodTypeAny | undefined {\n  const directShape = getObjectShape(mainSchema);\n  if (directShape && directShape[foreignKeyField]) {\n    return directShape[foreignKeyField];\n  }\n\n  if (isDiscriminatedUnion(mainSchema)) {\n    const options = getZodDefArrayProperty(mainSchema, 'options') ?? [];\n    for (const option of options) {\n      if (!isZodTypeAny(option)) {\n        continue;\n      }\n      const optionShape = getObjectShape(option);\n      if (optionShape && optionShape[foreignKeyField]) {\n        return optionShape[foreignKeyField];\n      }\n    }\n  }\n\n  return undefined;\n}\n\n/** True when the resource exposes an operation a reference picker can load options from (LIST or SEARCH, core or `resourceOperationLike`). */\nfunction hasPickerCapableOperation(resource: ForeignKeyFillabilityResourceInput): boolean {\n  return resource.operations.some((operation) => {\n    const core = operation.resourceOperationLike ?? operation.operationIdentifier;\n    return (\n      operation.operationIdentifier === CoreResourceOperation.LIST ||\n      operation.operationIdentifier === CoreResourceOperation.SEARCH ||\n      core === CoreResourceOperation.LIST ||\n      core === CoreResourceOperation.SEARCH\n    );\n  });\n}\n\n/**\n * Validate that every required COMPOSITION-parent foreign key in the registry is\n * user-fillable on CREATE. Returns the list of violations (empty when clean);\n * the caller decides how to surface them (warn vs fail). Pure and side-effect\n * free.\n *\n * @param resourceConfigurations - the registry's `resourceConfigurations` map\n *   (`resourceType → configuration`).\n */\nexport function validateRequiredForeignKeyFillability(\n  resourceConfigurations: Record<string, ForeignKeyFillabilityResourceInput>,\n): ForeignKeyFillabilityViolation[] {\n  const violations: ForeignKeyFillabilityViolation[] = [];\n\n  for (const resource of Object.values(resourceConfigurations)) {\n    const parentRelationships = resource.resourceRelationships?.parentRelationships ?? [];\n\n    for (const relationship of parentRelationships) {\n      // Only structural (COMPOSITION) parents are user-picked — REFERENCE FKs are\n      // backend-set / optional and would false-positive.\n      if (relationship.nature !== RelationshipNature.COMPOSITION) {\n        continue;\n      }\n      // Primary scope and REQUIRES_CONTEXT parents are ALWAYS present in the URL,\n      // so the FK is always seeded from context — never needs a picker.\n      if (relationship.isPrimaryScope) {\n        continue;\n      }\n      if (relationship.accessScopeStrategy === ResourceRelationshipAccessScopeStrategy.REQUIRES_CONTEXT) {\n        continue;\n      }\n\n      const foreignKeyField = relationship.foreignKeyField;\n      if (!foreignKeyField) {\n        continue;\n      }\n\n      // The FK must actually be a column on THIS resource's own schema. If it is\n      // not (e.g. an inbound FK reference where another resource holds the key),\n      // skip — fail-open.\n      const fkFieldSchema = findForeignKeyFieldSchema(resource.mainSchema, foreignKeyField);\n      if (!fkFieldSchema) {\n        continue;\n      }\n      // Optional FK → leaving it empty on org-wide create is valid; not a problem.\n      if (isOptional(fkFieldSchema)) {\n        continue;\n      }\n\n      const parentResourceType = relationship.resourceType1;\n\n      if (isExcludedFromCreate(fkFieldSchema)) {\n        violations.push({\n          kind: ForeignKeyFillabilityViolationKind.EXCLUDED_FROM_CREATE,\n          severity: VIOLATION_SEVERITY[ForeignKeyFillabilityViolationKind.EXCLUDED_FROM_CREATE],\n          resourceType: resource.resourceIdentifier,\n          foreignKeyField,\n          parentResourceType,\n          message:\n            `Resource '${resource.resourceIdentifier}' requires foreign key '${foreignKeyField}' ` +\n            `(composition parent '${parentResourceType}', accessScopeStrategy='${relationship.accessScopeStrategy ?? 'unset'}'), ` +\n            `but the field is excludeFromCreate AND the parent is not guaranteed in routing context. ` +\n            `The create form can neither seed it from context nor offer a picker → org-wide create is impossible. ` +\n            `Make the parent REQUIRES_CONTEXT (create always nested under the parent), or drop excludeFromCreate so a picker can render.`,\n        });\n        continue;\n      }\n\n      const parentResource = resourceConfigurations[parentResourceType];\n      if (!parentResource) {\n        // Unknown target (partial registry / cross-package boundary) → fail-open.\n        continue;\n      }\n      if (!hasPickerCapableOperation(parentResource)) {\n        violations.push({\n          kind: ForeignKeyFillabilityViolationKind.TARGET_NOT_SEARCHABLE,\n          severity: VIOLATION_SEVERITY[ForeignKeyFillabilityViolationKind.TARGET_NOT_SEARCHABLE],\n          resourceType: resource.resourceIdentifier,\n          foreignKeyField,\n          parentResourceType,\n          message:\n            `Resource '${resource.resourceIdentifier}' requires foreign key '${foreignKeyField}' ` +\n            `(composition parent '${parentResourceType}', accessScopeStrategy='${relationship.accessScopeStrategy ?? 'unset'}'), ` +\n            `which must be chosen via a reference picker on org-wide create — but target '${parentResourceType}' ` +\n            `exposes no LIST or SEARCH operation, so the picker cannot load options. ` +\n            `Add a LIST/SEARCH operation to '${parentResourceType}', or make the parent REQUIRES_CONTEXT.`,\n        });\n      }\n    }\n  }\n\n  return violations;\n}\n"]}

package/dist/esm/resources/utils/resource-operation-type-guards.utils.d.ts

@@ -2,12 +2,12 @@
  * Type Guard Utilities for Resource Operations
  *
  * These helpers assist TypeScript in narrowing union types more efficiently,
- * reducing the need to check all 7 variants in the union.
+ * reducing the need to check all operation variants in the union.
  *
  * @see TYPING_OPTIMIZATION_PLAN.md
  */
-import { ResourceConfiguration_Operation } from '../resources-config.shared.schemas.js';
-import { ResourceOperationVariantType } from '../resources.shared.schemas.js';
+import { ResourceConfiguration_Operation } from '../resources-config.shared.schemas';
+import { ResourceOperationVariantType } from '../resources.shared.schemas';
 /**
  * Type guard for API_CALL variant
  */
@@ -44,4 +44,108 @@ export declare function isInternalCallOperation<T extends ResourceConfiguration_
 export declare function isRepositoryOnlyOperation<T extends ResourceConfiguration_Operation<any, any, any>>(operation: T): operation is Extract<T, {
     variantType: ResourceOperationVariantType.REPOSITORY_ONLY;
 }>;
+/**
+ * The variant types that carry an HTTP surface — URL templates, methods,
+ * request/response DTOs. THE authority for "is this variant routable?".
+ *
+ * Every site that filters operations by "reachable over HTTP" must read this
+ * set rather than re-listing its members: the list has drifted before, and each
+ * copy is a place a newly-added URL-bearing variant would be silently missed.
+ */
+export declare const URL_BEARING_OPERATION_VARIANT_TYPES: readonly ResourceOperationVariantType[];
+/**
+ * The service layer's NATIVE transport: variants authors declare for operations
+ * that must run through the registry pipeline (ACL, hooks, lifecycle) but are
+ * deliberately NOT exposed over HTTP.
+ */
+export declare const SERVICE_NATIVE_OPERATION_VARIANT_TYPES: readonly ResourceOperationVariantType[];
+/**
+ * THE authority for "which variant types can the SERVICE dispatch layer
+ * resolve?" — i.e. exactly the set
+ * `ResourcesRegistryBackendService.getServiceOperationPathDefault` matches.
+ *
+ * **Why this is a named, exported constant rather than three enum members
+ * spelled out at each call site.** `REPOSITORY_ONLY` is route-less, just like
+ * `INTERNAL_CALL`, and is therefore an extremely natural (wrong) choice for an
+ * operation that should exist "as a capability, without a new HTTP surface".
+ * But it is deliberately EXCLUDED here and served by the separate
+ * `getRepositoryOperationPathDefault` transport — so a `REPOSITORY_ONLY`
+ * operation satisfies any "the op exists" config check and then fails to
+ * resolve the moment a service-layer caller actually invokes it. That is a
+ * latent RUNTIME failure produced by a config that looked correct at boot; it
+ * shipped once already (the `USERS` retention opt-in, caught by a completion
+ * review after the config tests were green).
+ *
+ * Boot-time guards that require an operation to be reachable by a
+ * service-layer caller — notably the `retentionPolicy` guard in
+ * `resources-config.shared.factory.ts`, whose three primitives
+ * (`updateManyAsSystem` / `readRetainedAsSystem` / `listRetainedAsSystem`) all
+ * resolve through `getServiceOperationPathDefault` — MUST read this set. Two
+ * independently-maintained copies of the list is exactly how that class of bug
+ * returns: the guard would accept a variant the resolver rejects.
+ *
+ * NOT the same question as {@link URL_BEARING_OPERATION_VARIANT_TYPES}: a
+ * service-resolvable operation may be route-less (`INTERNAL_CALL`). An
+ * operation that must be BOTH route-less and service-resolvable therefore has
+ * exactly one legal variant type today — `INTERNAL_CALL` — and that
+ * intersection is what a retention capability op needs.
+ */
+export declare const SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES: readonly ResourceOperationVariantType[];
+/**
+ * Composite predicate: is `operation` the DEFAULT, NON-BULK variant for
+ * `operationIdentifier` that the SERVICE dispatch layer can resolve?
+ *
+ * This is the exact admission test applied by
+ * `ResourcesRegistryBackendService.getServiceOperationPathDefault` before it
+ * chooses between the INTERNAL and URL-bearing candidates. Sharing it makes a
+ * boot-time guard and the runtime resolver structurally unable to disagree:
+ * a config the guard accepts is a config the resolver can serve, and adding a
+ * variant type to {@link SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES} updates
+ * both at once.
+ *
+ * Deliberately NOT a TypeScript type predicate: unlike
+ * {@link isDefaultUrlBearingOperation}, callers of this one need a boolean
+ * answer about reachability, not a narrowed operation — and narrowing to a
+ * three-member union would imply a variant shape the callers do not read.
+ *
+ * @param operation - a single resource operation variant to classify.
+ * @param operationIdentifier - the operation identifier to match (e.g. `CoreResourceOperation.UPDATE_MANY`).
+ */
+export declare function isServiceResolvableDefaultOperation<T extends ResourceConfiguration_Operation<any, any, any>>(operation: T, operationIdentifier: string): boolean;
+/**
+ * Composite type guard: is `operation` the DEFAULT, NON-BULK, URL-bearing
+ * variant for `operationIdentifier`?
+ *
+ * Combines the four conditions that together select THE operation a resource
+ * exposes over HTTP for a given identifier:
+ *  1. `operationIdentifier` matches,
+ *  2. it is the operation default (`isOperationDefault === true`),
+ *  3. it is not a bulk operation, and
+ *  4. its variant type is in {@link URL_BEARING_OPERATION_VARIANT_TYPES} — the
+ *     only variants that carry an HTTP surface: URL templates, methods,
+ *     request/response DTOs.
+ *
+ * **Why this is single-sourced — a latent HTTP 500 depends on it.** Two
+ * independent call sites must apply EXACTLY this filter:
+ *  - `ResourcesRegistryBackendService.getOperationPathDefault` resolves the
+ *    URL/DTO routing path and throws `RESOURCES_REGISTRY_OPERATION_PATH_NOT_FOUND`
+ *    (INTERNAL / 500) when nothing matches.
+ *  - The validate-field route mount gate (`findDefaultUrlBearingCreateOperation`)
+ *    decides whether to register a resource's `validate-field` route; that
+ *    route's request handler later calls `getOperationPathDefault(resourceType,
+ *    CREATE)`. The handler is safe ONLY because the gate refuses to mount the
+ *    route for any resource whose CREATE the resolver would reject (e.g. a
+ *    `REPOSITORY_ONLY`-only CREATE such as `CoreResourceType.FILES`).
+ *
+ * Keeping both sites on this one predicate makes their agreement structural:
+ * adding or removing a URL-bearing variant updates both at once, so the gate can
+ * never admit a request the resolver will 500 on. Do NOT inline a copy of this
+ * filter at a call site — call this guard.
+ *
+ * @param operation - a single resource operation variant to classify.
+ * @param operationIdentifier - the operation identifier to match (e.g. `CoreResourceOperation.CREATE`).
+ */
+export declare function isDefaultUrlBearingOperation<T extends ResourceConfiguration_Operation<any, any, any>>(operation: T, operationIdentifier: string): operation is Extract<T, {
+    variantType: ResourceOperationVariantType.API_CALL | ResourceOperationVariantType.API_CALL_WITH_CALLBACK;
+}>;
 //# sourceMappingURL=resource-operation-type-guards.utils.d.ts.map

package/dist/esm/resources/utils/resource-operation-type-guards.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-operation-type-guards.utils.d.ts","sourceRoot":"","sources":["../../../../src/resources/utils/resource-operation-type-guards.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,+BAA+B,EAAE,MAAM,oCAAoC,CAAC;AACrF,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAE3E;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACzF,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,QAAQ,CAAA;CAAE,CAAC,CAEjF;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACrG,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,sBAAsB,CAAA;CAAE,CAAC,CAE/F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACzF,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,QAAQ,CAAA;CAAE,CAAC,CAEjF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC1F,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,SAAS,CAAA;CAAE,CAAC,CAElF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC9F,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,aAAa,CAAA;CAAE,CAAC,CAEtF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAChG,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,eAAe,CAAA;CAAE,CAAC,CAExF"}
+{"version":3,"file":"resource-operation-type-guards.utils.d.ts","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-operation-type-guards.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,+BAA+B,EAAE,MAAM,oCAAoC,CAAC;AACrF,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAE3E;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACzF,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,QAAQ,CAAA;CAAE,CAAC,CAEjF;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACrG,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,sBAAsB,CAAA;CAAE,CAAC,CAE/F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACzF,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,QAAQ,CAAA;CAAE,CAAC,CAEjF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC1F,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,SAAS,CAAA;CAAE,CAAC,CAElF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC9F,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,aAAa,CAAA;CAAE,CAAC,CAEtF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAChG,SAAS,EAAE,CAAC,GACX,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,eAAe,CAAA;CAAE,CAAC,CAExF;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mCAAmC,EAAE,SAAS,4BAA4B,EAGtF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sCAAsC,EAAE,SAAS,4BAA4B,EAEzF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,0CAA0C,EAAE,SAAS,4BAA4B,EAG7F,CAAC;AAcF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mCAAmC,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC1G,SAAS,EAAE,CAAC,EACZ,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAKT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,+BAA+B,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACnG,SAAS,EAAE,CAAC,EACZ,mBAAmB,EAAE,MAAM,GAC1B,SAAS,IAAI,OAAO,CAAC,CAAC,EAAE;IAAE,WAAW,EAAE,4BAA4B,CAAC,QAAQ,GAAG,4BAA4B,CAAC,sBAAsB,CAAA;CAAE,CAAC,CAKvI"}

package/dist/esm/resources/utils/resource-operation-type-guards.utils.js

@@ -2,7 +2,7 @@
  * Type Guard Utilities for Resource Operations
  *
  * These helpers assist TypeScript in narrowing union types more efficiently,
- * reducing the need to check all 7 variants in the union.
+ * reducing the need to check all operation variants in the union.
  *
  * @see TYPING_OPTIMIZATION_PLAN.md
  */
@@ -43,4 +43,135 @@ export function isInternalCallOperation(operation) {
 export function isRepositoryOnlyOperation(operation) {
     return operation.variantType === ResourceOperationVariantType.REPOSITORY_ONLY;
 }
-//# sourceMappingURL=resource-operation-type-guards.utils.js.map
+/**
+ * The variant types that carry an HTTP surface — URL templates, methods,
+ * request/response DTOs. THE authority for "is this variant routable?".
+ *
+ * Every site that filters operations by "reachable over HTTP" must read this
+ * set rather than re-listing its members: the list has drifted before, and each
+ * copy is a place a newly-added URL-bearing variant would be silently missed.
+ */
+export const URL_BEARING_OPERATION_VARIANT_TYPES = [
+    ResourceOperationVariantType.API_CALL,
+    ResourceOperationVariantType.API_CALL_WITH_CALLBACK,
+];
+/**
+ * The service layer's NATIVE transport: variants authors declare for operations
+ * that must run through the registry pipeline (ACL, hooks, lifecycle) but are
+ * deliberately NOT exposed over HTTP.
+ */
+export const SERVICE_NATIVE_OPERATION_VARIANT_TYPES = [
+    ResourceOperationVariantType.INTERNAL_CALL,
+];
+/**
+ * THE authority for "which variant types can the SERVICE dispatch layer
+ * resolve?" — i.e. exactly the set
+ * `ResourcesRegistryBackendService.getServiceOperationPathDefault` matches.
+ *
+ * **Why this is a named, exported constant rather than three enum members
+ * spelled out at each call site.** `REPOSITORY_ONLY` is route-less, just like
+ * `INTERNAL_CALL`, and is therefore an extremely natural (wrong) choice for an
+ * operation that should exist "as a capability, without a new HTTP surface".
+ * But it is deliberately EXCLUDED here and served by the separate
+ * `getRepositoryOperationPathDefault` transport — so a `REPOSITORY_ONLY`
+ * operation satisfies any "the op exists" config check and then fails to
+ * resolve the moment a service-layer caller actually invokes it. That is a
+ * latent RUNTIME failure produced by a config that looked correct at boot; it
+ * shipped once already (the `USERS` retention opt-in, caught by a completion
+ * review after the config tests were green).
+ *
+ * Boot-time guards that require an operation to be reachable by a
+ * service-layer caller — notably the `retentionPolicy` guard in
+ * `resources-config.shared.factory.ts`, whose three primitives
+ * (`updateManyAsSystem` / `readRetainedAsSystem` / `listRetainedAsSystem`) all
+ * resolve through `getServiceOperationPathDefault` — MUST read this set. Two
+ * independently-maintained copies of the list is exactly how that class of bug
+ * returns: the guard would accept a variant the resolver rejects.
+ *
+ * NOT the same question as {@link URL_BEARING_OPERATION_VARIANT_TYPES}: a
+ * service-resolvable operation may be route-less (`INTERNAL_CALL`). An
+ * operation that must be BOTH route-less and service-resolvable therefore has
+ * exactly one legal variant type today — `INTERNAL_CALL` — and that
+ * intersection is what a retention capability op needs.
+ */
+export const SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES = [
+    ...SERVICE_NATIVE_OPERATION_VARIANT_TYPES,
+    ...URL_BEARING_OPERATION_VARIANT_TYPES,
+];
+/**
+ * Is `operation` a BULK variant?
+ *
+ * `isBulkOperation` exists only on some members of the operation discriminated
+ * union (the CronJob variant carries neither the flag nor a bulk notion), so
+ * the `in` narrow is required before the read — see
+ * `.claude/skills/audit-operation-variants`.
+ */
+function isBulkOperationVariant(operation) {
+    return 'isBulkOperation' in operation && operation.isBulkOperation === true;
+}
+/**
+ * Composite predicate: is `operation` the DEFAULT, NON-BULK variant for
+ * `operationIdentifier` that the SERVICE dispatch layer can resolve?
+ *
+ * This is the exact admission test applied by
+ * `ResourcesRegistryBackendService.getServiceOperationPathDefault` before it
+ * chooses between the INTERNAL and URL-bearing candidates. Sharing it makes a
+ * boot-time guard and the runtime resolver structurally unable to disagree:
+ * a config the guard accepts is a config the resolver can serve, and adding a
+ * variant type to {@link SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES} updates
+ * both at once.
+ *
+ * Deliberately NOT a TypeScript type predicate: unlike
+ * {@link isDefaultUrlBearingOperation}, callers of this one need a boolean
+ * answer about reachability, not a narrowed operation — and narrowing to a
+ * three-member union would imply a variant shape the callers do not read.
+ *
+ * @param operation - a single resource operation variant to classify.
+ * @param operationIdentifier - the operation identifier to match (e.g. `CoreResourceOperation.UPDATE_MANY`).
+ */
+export function isServiceResolvableDefaultOperation(operation, operationIdentifier) {
+    return operation.operationIdentifier === operationIdentifier
+        && operation.isOperationDefault === true
+        && !isBulkOperationVariant(operation)
+        && SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES.includes(operation.variantType);
+}
+/**
+ * Composite type guard: is `operation` the DEFAULT, NON-BULK, URL-bearing
+ * variant for `operationIdentifier`?
+ *
+ * Combines the four conditions that together select THE operation a resource
+ * exposes over HTTP for a given identifier:
+ *  1. `operationIdentifier` matches,
+ *  2. it is the operation default (`isOperationDefault === true`),
+ *  3. it is not a bulk operation, and
+ *  4. its variant type is in {@link URL_BEARING_OPERATION_VARIANT_TYPES} — the
+ *     only variants that carry an HTTP surface: URL templates, methods,
+ *     request/response DTOs.
+ *
+ * **Why this is single-sourced — a latent HTTP 500 depends on it.** Two
+ * independent call sites must apply EXACTLY this filter:
+ *  - `ResourcesRegistryBackendService.getOperationPathDefault` resolves the
+ *    URL/DTO routing path and throws `RESOURCES_REGISTRY_OPERATION_PATH_NOT_FOUND`
+ *    (INTERNAL / 500) when nothing matches.
+ *  - The validate-field route mount gate (`findDefaultUrlBearingCreateOperation`)
+ *    decides whether to register a resource's `validate-field` route; that
+ *    route's request handler later calls `getOperationPathDefault(resourceType,
+ *    CREATE)`. The handler is safe ONLY because the gate refuses to mount the
+ *    route for any resource whose CREATE the resolver would reject (e.g. a
+ *    `REPOSITORY_ONLY`-only CREATE such as `CoreResourceType.FILES`).
+ *
+ * Keeping both sites on this one predicate makes their agreement structural:
+ * adding or removing a URL-bearing variant updates both at once, so the gate can
+ * never admit a request the resolver will 500 on. Do NOT inline a copy of this
+ * filter at a call site — call this guard.
+ *
+ * @param operation - a single resource operation variant to classify.
+ * @param operationIdentifier - the operation identifier to match (e.g. `CoreResourceOperation.CREATE`).
+ */
+export function isDefaultUrlBearingOperation(operation, operationIdentifier) {
+    return operation.operationIdentifier === operationIdentifier
+        && operation.isOperationDefault === true
+        && !isBulkOperationVariant(operation)
+        && URL_BEARING_OPERATION_VARIANT_TYPES.includes(operation.variantType);
+}
+//# sourceMappingURL=resource-operation-type-guards.utils.js.map

package/dist/esm/resources/utils/resource-operation-type-guards.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource-operation-type-guards.utils.js","sourceRoot":"","sources":["../../../../src/resources/utils/resource-operation-type-guards.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAE3E;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,QAAQ,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,sBAAsB,CAAC;AACvF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,QAAQ,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,SAAS,CAAC;AAC1E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACrC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,aAAa,CAAC;AAC9E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,eAAe,CAAC;AAChF,CAAC"}
+{"version":3,"file":"resource-operation-type-guards.utils.js","sourceRoot":"","sources":["../../../../../src/resources/utils/resource-operation-type-guards.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAE3E;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,QAAQ,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,sBAAsB,CAAC;AACvF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,QAAQ,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,SAAS,CAAC;AAC1E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACrC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,aAAa,CAAC;AAC9E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,SAAY;IAEZ,OAAO,SAAS,CAAC,WAAW,KAAK,4BAA4B,CAAC,eAAe,CAAC;AAChF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAA4C;IAC1F,4BAA4B,CAAC,QAAQ;IACrC,4BAA4B,CAAC,sBAAsB;CACpD,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAA4C;IAC7F,4BAA4B,CAAC,aAAa;CAC3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,0CAA0C,GAA4C;IACjG,GAAG,sCAAsC;IACzC,GAAG,mCAAmC;CACvC,CAAC;AAEF;;;;;;;GAOG;AACH,SAAS,sBAAsB,CAA2D,SAAY;IACpG,OAAO,iBAAiB,IAAI,SAAS,IAAI,SAAS,CAAC,eAAe,KAAK,IAAI,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,mCAAmC,CACjD,SAAY,EACZ,mBAA2B;IAE3B,OAAO,SAAS,CAAC,mBAAmB,KAAK,mBAAmB;WACvD,SAAS,CAAC,kBAAkB,KAAK,IAAI;WACrC,CAAC,sBAAsB,CAAC,SAAS,CAAC;WAClC,0CAA0C,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;AAClF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,4BAA4B,CAC1C,SAAY,EACZ,mBAA2B;IAE3B,OAAO,SAAS,CAAC,mBAAmB,KAAK,mBAAmB;WACvD,SAAS,CAAC,kBAAkB,KAAK,IAAI;WACrC,CAAC,sBAAsB,CAAC,SAAS,CAAC;WAClC,mCAAmC,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;AAC3E,CAAC","sourcesContent":["/**\n * Type Guard Utilities for Resource Operations\n * \n * These helpers assist TypeScript in narrowing union types more efficiently,\n * reducing the need to check all operation variants in the union.\n * \n * @see TYPING_OPTIMIZATION_PLAN.md\n */\n\nimport { ResourceConfiguration_Operation } from '../resources-config.shared.schemas';\nimport { ResourceOperationVariantType } from '../resources.shared.schemas';\n\n/**\n * Type guard for API_CALL variant\n */\nexport function isApiCallOperation<T extends ResourceConfiguration_Operation<any, any, any>>(\n  operation: T\n): operation is Extract<T, { variantType: ResourceOperationVariantType.API_CALL }> {\n  return operation.variantType === ResourceOperationVariantType.API_CALL;\n}\n\n/**\n * Type guard for API_CALL_WITH_CALLBACK variant\n */\nexport function isApiCallWithCallbackOperation<T extends ResourceConfiguration_Operation<any, any, any>>(\n  operation: T\n): operation is Extract<T, { variantType: ResourceOperationVariantType.API_CALL_WITH_CALLBACK }> {\n  return operation.variantType === ResourceOperationVariantType.API_CALL_WITH_CALLBACK;\n}\n\n/**\n * Type guard for CRON_JOB variant\n */\nexport function isCronJobOperation<T extends ResourceConfiguration_Operation<any, any, any>>(\n  operation: T\n): operation is Extract<T, { variantType: ResourceOperationVariantType.CRON_JOB }> {\n  return operation.variantType === ResourceOperationVariantType.CRON_JOB;\n}\n\n/**\n * Type guard for BATCH_JOB variant\n */\nexport function isBatchJobOperation<T extends ResourceConfiguration_Operation<any, any, any>>(\n  operation: T\n): operation is Extract<T, { variantType: ResourceOperationVariantType.BATCH_JOB }> {\n  return operation.variantType === ResourceOperationVariantType.BATCH_JOB;\n}\n\n/**\n * Type guard for INTERNAL_CALL variant\n */\nexport function isInternalCallOperation<T extends ResourceConfiguration_Operation<any, any, any>>(\n  operation: T\n): operation is Extract<T, { variantType: ResourceOperationVariantType.INTERNAL_CALL }> {\n  return operation.variantType === ResourceOperationVariantType.INTERNAL_CALL;\n}\n\n/**\n * Type guard for REPOSITORY_ONLY variant\n */\nexport function isRepositoryOnlyOperation<T extends ResourceConfiguration_Operation<any, any, any>>(\n  operation: T\n): operation is Extract<T, { variantType: ResourceOperationVariantType.REPOSITORY_ONLY }> {\n  return operation.variantType === ResourceOperationVariantType.REPOSITORY_ONLY;\n}\n\n/**\n * The variant types that carry an HTTP surface — URL templates, methods,\n * request/response DTOs. THE authority for \"is this variant routable?\".\n *\n * Every site that filters operations by \"reachable over HTTP\" must read this\n * set rather than re-listing its members: the list has drifted before, and each\n * copy is a place a newly-added URL-bearing variant would be silently missed.\n */\nexport const URL_BEARING_OPERATION_VARIANT_TYPES: readonly ResourceOperationVariantType[] = [\n  ResourceOperationVariantType.API_CALL,\n  ResourceOperationVariantType.API_CALL_WITH_CALLBACK,\n];\n\n/**\n * The service layer's NATIVE transport: variants authors declare for operations\n * that must run through the registry pipeline (ACL, hooks, lifecycle) but are\n * deliberately NOT exposed over HTTP.\n */\nexport const SERVICE_NATIVE_OPERATION_VARIANT_TYPES: readonly ResourceOperationVariantType[] = [\n  ResourceOperationVariantType.INTERNAL_CALL,\n];\n\n/**\n * THE authority for \"which variant types can the SERVICE dispatch layer\n * resolve?\" — i.e. exactly the set\n * `ResourcesRegistryBackendService.getServiceOperationPathDefault` matches.\n *\n * **Why this is a named, exported constant rather than three enum members\n * spelled out at each call site.** `REPOSITORY_ONLY` is route-less, just like\n * `INTERNAL_CALL`, and is therefore an extremely natural (wrong) choice for an\n * operation that should exist \"as a capability, without a new HTTP surface\".\n * But it is deliberately EXCLUDED here and served by the separate\n * `getRepositoryOperationPathDefault` transport — so a `REPOSITORY_ONLY`\n * operation satisfies any \"the op exists\" config check and then fails to\n * resolve the moment a service-layer caller actually invokes it. That is a\n * latent RUNTIME failure produced by a config that looked correct at boot; it\n * shipped once already (the `USERS` retention opt-in, caught by a completion\n * review after the config tests were green).\n *\n * Boot-time guards that require an operation to be reachable by a\n * service-layer caller — notably the `retentionPolicy` guard in\n * `resources-config.shared.factory.ts`, whose three primitives\n * (`updateManyAsSystem` / `readRetainedAsSystem` / `listRetainedAsSystem`) all\n * resolve through `getServiceOperationPathDefault` — MUST read this set. Two\n * independently-maintained copies of the list is exactly how that class of bug\n * returns: the guard would accept a variant the resolver rejects.\n *\n * NOT the same question as {@link URL_BEARING_OPERATION_VARIANT_TYPES}: a\n * service-resolvable operation may be route-less (`INTERNAL_CALL`). An\n * operation that must be BOTH route-less and service-resolvable therefore has\n * exactly one legal variant type today — `INTERNAL_CALL` — and that\n * intersection is what a retention capability op needs.\n */\nexport const SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES: readonly ResourceOperationVariantType[] = [\n  ...SERVICE_NATIVE_OPERATION_VARIANT_TYPES,\n  ...URL_BEARING_OPERATION_VARIANT_TYPES,\n];\n\n/**\n * Is `operation` a BULK variant?\n *\n * `isBulkOperation` exists only on some members of the operation discriminated\n * union (the CronJob variant carries neither the flag nor a bulk notion), so\n * the `in` narrow is required before the read — see\n * `.claude/skills/audit-operation-variants`.\n */\nfunction isBulkOperationVariant<T extends ResourceConfiguration_Operation<any, any, any>>(operation: T): boolean {\n  return 'isBulkOperation' in operation && operation.isBulkOperation === true;\n}\n\n/**\n * Composite predicate: is `operation` the DEFAULT, NON-BULK variant for\n * `operationIdentifier` that the SERVICE dispatch layer can resolve?\n *\n * This is the exact admission test applied by\n * `ResourcesRegistryBackendService.getServiceOperationPathDefault` before it\n * chooses between the INTERNAL and URL-bearing candidates. Sharing it makes a\n * boot-time guard and the runtime resolver structurally unable to disagree:\n * a config the guard accepts is a config the resolver can serve, and adding a\n * variant type to {@link SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES} updates\n * both at once.\n *\n * Deliberately NOT a TypeScript type predicate: unlike\n * {@link isDefaultUrlBearingOperation}, callers of this one need a boolean\n * answer about reachability, not a narrowed operation — and narrowing to a\n * three-member union would imply a variant shape the callers do not read.\n *\n * @param operation - a single resource operation variant to classify.\n * @param operationIdentifier - the operation identifier to match (e.g. `CoreResourceOperation.UPDATE_MANY`).\n */\nexport function isServiceResolvableDefaultOperation<T extends ResourceConfiguration_Operation<any, any, any>>(\n  operation: T,\n  operationIdentifier: string,\n): boolean {\n  return operation.operationIdentifier === operationIdentifier\n    && operation.isOperationDefault === true\n    && !isBulkOperationVariant(operation)\n    && SERVICE_RESOLVABLE_OPERATION_VARIANT_TYPES.includes(operation.variantType);\n}\n\n/**\n * Composite type guard: is `operation` the DEFAULT, NON-BULK, URL-bearing\n * variant for `operationIdentifier`?\n *\n * Combines the four conditions that together select THE operation a resource\n * exposes over HTTP for a given identifier:\n *  1. `operationIdentifier` matches,\n *  2. it is the operation default (`isOperationDefault === true`),\n *  3. it is not a bulk operation, and\n *  4. its variant type is in {@link URL_BEARING_OPERATION_VARIANT_TYPES} — the\n *     only variants that carry an HTTP surface: URL templates, methods,\n *     request/response DTOs.\n *\n * **Why this is single-sourced — a latent HTTP 500 depends on it.** Two\n * independent call sites must apply EXACTLY this filter:\n *  - `ResourcesRegistryBackendService.getOperationPathDefault` resolves the\n *    URL/DTO routing path and throws `RESOURCES_REGISTRY_OPERATION_PATH_NOT_FOUND`\n *    (INTERNAL / 500) when nothing matches.\n *  - The validate-field route mount gate (`findDefaultUrlBearingCreateOperation`)\n *    decides whether to register a resource's `validate-field` route; that\n *    route's request handler later calls `getOperationPathDefault(resourceType,\n *    CREATE)`. The handler is safe ONLY because the gate refuses to mount the\n *    route for any resource whose CREATE the resolver would reject (e.g. a\n *    `REPOSITORY_ONLY`-only CREATE such as `CoreResourceType.FILES`).\n *\n * Keeping both sites on this one predicate makes their agreement structural:\n * adding or removing a URL-bearing variant updates both at once, so the gate can\n * never admit a request the resolver will 500 on. Do NOT inline a copy of this\n * filter at a call site — call this guard.\n *\n * @param operation - a single resource operation variant to classify.\n * @param operationIdentifier - the operation identifier to match (e.g. `CoreResourceOperation.CREATE`).\n */\nexport function isDefaultUrlBearingOperation<T extends ResourceConfiguration_Operation<any, any, any>>(\n  operation: T,\n  operationIdentifier: string,\n): operation is Extract<T, { variantType: ResourceOperationVariantType.API_CALL | ResourceOperationVariantType.API_CALL_WITH_CALLBACK }> {\n  return operation.operationIdentifier === operationIdentifier\n    && operation.isOperationDefault === true\n    && !isBulkOperationVariant(operation)\n    && URL_BEARING_OPERATION_VARIANT_TYPES.includes(operation.variantType);\n}\n"]}

package/dist/esm/resources/utils/resource-polymorphism.factory.d.ts

@@ -11,11 +11,10 @@
  * @see polymorphic-scope-approach-A-expansion.md — Phase 3
  */
 import { z } from 'zod';
-import type { ResourceConfiguration_InitializationFactory, ResourceConfiguration_Operation_BuilderParameters, ResourceConfiguration_OperationVariant_BuilderParameters, ResourceConfiguration_InheritanceSchemaDefinition, ResourceConfiguration_AutoVariants, CollectionViewFields_Search } from '../resources-config.shared.schemas.js';
-import type { CoreResourceOperation } from '../resources.shared.core.definitions.js';
-import type { PersistenceAdapterType } from '../resources-config.shared.schemas.js';
+import type { ResourceConfiguration_BuilderParameters, ResourceConfiguration_InitializationFactory, ResourceConfiguration_Operation_BuilderParameters, ResourceConfiguration_OperationVariant_BuilderParameters, CollectionViewFields_Search } from '../resources-config.shared.schemas';
+import type { CoreResourceOperation } from '../resources.shared.core.definitions';
 import type { EnumLikeType } from '@wildo-ai/zod-decorators';
-import type { PolymorphicSchemaDeclaration } from './resource-polymorphism.schemas.js';
+import type { PolymorphicSchemaDeclaration } from './resource-polymorphism.schemas';
 /**
  * Distributive Omit — preserves union members individually.
  * Standard `Omit<A | B, K>` collapses to common keys only, losing per-member properties.
@@ -43,11 +42,18 @@ export type PolymorphicOperationVariant<TMainSchema extends z.ZodTypeAny = z.Zod
      * Role mapping per parent resource type.
      * The factory resolves this into standard `roles` for each generated variant.
      *
+     * ⚠️ An EMPTY array is NOT "skip the role check" — it is fail-CLOSED. The
+     * authorization gate evaluates `operationRoles.some(...)`, and `[].some()`
+     * is always `false`, so an empty array denies EVERY caller (403). For the
+     * user-self scope, list the baseline authenticated role (`APP_USER`); role
+     * membership is the floor, while row ownership is enforced separately by the
+     * USER_SELF scope authorizer.
+     *
      * @example
      * polymorphicRole: {
      *   'organizations': ['ORG_OWNER', 'ORG_ADMIN'],
-     *   'users': [],  // user themselves — no role check
-     *        * }
+     *   'users': ['APP_USER'],  // user-self: any authenticated user (ownership checked by scope)
+     * }
      */
     polymorphicRole?: Record<string, string[]>;
     /** Standard roles — used directly or as fallback when polymorphicRole doesn't have the parent */
@@ -60,33 +66,35 @@ export type PolymorphicOperationConfig<TMainSchema extends z.ZodTypeAny = z.ZodA
     variants: PolymorphicOperationVariant<TMainSchema>[];
 };
 /**
- * Shared resource configuration for polymorphic resources.
- * Contains everything that's common across all variants.
+ * Keys the polymorphic factory derives PER VARIANT — the only things a shared config cannot supply.
+ * Everything else is shared, and is now inherited structurally (see {@link PolymorphicResourceConfig}).
+ */
+type PolymorphicPerVariantKeys = 'mainSchema' | 'resourceIdentifier' | 'resourceFieldIdentifier' | 'resourceRelationships' | 'operationsConfiguration';
+/**
+ * Shared resource configuration for polymorphic resources — everything common across all variants.
  *
- * Notable omissions (derived from the polymorphic declaration):
- * - `mainSchema` — derived per variant from the declaration
- * - `resourceIdentifier` — derived per variant
- * - `resourceFieldIdentifier` — derived per variant
- * - `resourceRelationships` — provided at factory call time by the registry
+ * ⚠️ DERIVED FROM `ResourceConfiguration_BuilderParameters`, deliberately. This used to be a
+ * hand-maintained whitelist of forwarded fields, and it silently DROPPED every resource-level
+ * capability axis added after it was written (`isAnonymizable`, `transpositionPolicy`,
+ * `retentionPolicy`). The failure mode was invisible: a polymorphic resource could ASK for a
+ * capability and simply not get it — no type error, no runtime error, the opt-in just evaporated.
+ * Because the type is now an `Omit` of the real parameter surface and the values are spread through,
+ * ANY capability added to the builder parameters is automatically available to polymorphic resources
+ * and forwarded — there is no list left to forget.
+ *
+ * Per-variant keys are omitted (see {@link PolymorphicPerVariantKeys}); `operationsConfiguration` is
+ * re-declared with the `polymorphicRole`-aware variant shape.
+ *
+ * NOTE ON SEMANTICS: a capability declared here applies to EVERY generated variant (that is the point
+ * — e.g. all billing scopes retain identically). A capability that is invalid for one variant's scope
+ * fails loud in that variant's factory call, which is the correct outcome; per-variant capability
+ * overrides are intentionally NOT modelled (no consumer needs them, and they would reintroduce the
+ * "which variant actually got it?" ambiguity this contract removes).
  */
-export interface PolymorphicResourceConfig<TCustomOperationEnum extends EnumLikeType | undefined = undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny> {
-    /** Whether this resource is disabled (default: false) */
-    isDisabled?: boolean;
-    /** Whether this is a system resource (default: false) */
-    isSystemResource?: boolean;
-    /** Persistence adapter type (default: 'mongodb') */
-    persistenceAdapter?: PersistenceAdapterType;
-    /** Core operations enabled for this resource */
-    coreOperations: TCoreOperationEnum[];
-    /** Custom operations enum (if any) */
-    customOperation?: TCustomOperationEnum;
-    /** Operations configuration — supports polymorphicRole on variants */
+export type PolymorphicResourceConfig<TCustomOperationEnum extends EnumLikeType | undefined = undefined, TCoreOperationEnum extends Partial<CoreResourceOperation> | undefined = undefined, TMainSchema extends z.ZodTypeAny = z.ZodAny> = Omit<ResourceConfiguration_BuilderParameters<TCustomOperationEnum, TCoreOperationEnum, TMainSchema>, PolymorphicPerVariantKeys> & {
+    /** Operations configuration — supports `polymorphicRole` on variants. */
     operationsConfiguration: Record<string, PolymorphicOperationConfig<TMainSchema>>;
-    /** Auto-generated operation variants configuration */
-    autoVariants?: ResourceConfiguration_AutoVariants;
-    /** Inheritance schema definition (usually from SchemaFamily) */
-    inheritenceSchemaDefinition?: ResourceConfiguration_InheritanceSchemaDefinition<any, TMainSchema>;
-}
+};
 /**
  * Create N resource configuration factories from a polymorphic declaration.
  *
@@ -111,7 +119,7 @@ export interface PolymorphicResourceConfig<TCustomOperationEnum extends EnumLike
  *           isDefault: true,
  *           polymorphicRole: {
  *             'organizations': [CORE_ORG_ROLES.ORG_OWNER],
- *             'users': [],
+ *             'users': [CORE_APP_ROLES.APP_USER], // never [] — empty is fail-closed (403)
  *           },
  *           riskLevel: ResourceOperationRiskLevel.LOW,
  *         }],