@wildo-ai/saas-models 1.1.4 → 1.1.5

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

@@ -20,6 +20,53 @@ export var ResourceOperationRiskLevel;
     ResourceOperationRiskLevel["HIGH"] = "high";
     ResourceOperationRiskLevel["CRITICAL"] = "critical";
 })(ResourceOperationRiskLevel || (ResourceOperationRiskLevel = {}));
+/**
+ * Can this operation's effect be UNDONE by a later operation?
+ *
+ * ## Why this is not `riskLevel`, and what the conflation cost
+ *
+ * Risk answers *how much does this matter*. Reversibility answers *can I take it back*. They are
+ * independent, and the framework had only the first — so the danger zone, which is the one surface
+ * that exists to mark the point of no return, derived its membership from risk alone:
+ * `isRiskyOperation(riskLevel) ? DANGER_ZONE : PRIMARY`.
+ *
+ * Measured 2026-09-19 over the framework's own resource definitions: 150 operation variants declare HIGH or CRITICAL,
+ * and the owning verbs are **48 DELETE — and then 29 UPDATE_MANY, 14 CREATE, 9 UPDATE**, plus
+ * `RESTORE`, `APPROVE`, `GRANT_OWNERSHIP`, `VERIFY_DOMAIN`, `CLAIM_DOMAIN` and `GENERATE_TOKEN`.
+ * So a CREATE sat under a red button in a section headed "Danger Zone", and so did `RESTORE` —
+ * an operation whose entire purpose is to UNDO a deletion.
+ *
+ * What a reader met on Administration → Entitlements was the pane's primary verb, **Edit**, rendered
+ * as a red destructive button beneath "This action may cause significant disruption and be difficult
+ * to reverse" — a sentence two of the three buttons beside it also carried, so it described none of
+ * them. When everything is red, nothing is.
+ *
+ * ## The default is DERIVED, so almost nothing has to be authored
+ *
+ * `resolveOperationReversibility` reads this declaration when present and otherwise derives it from
+ * `resourceOperationLike`: a DELETE-like operation is irreversible, everything else is reversible.
+ * That covers the 53 DELETE / DELETE_MANY variants without touching them, and leaves an explicit
+ * declaration for the handful of custom verbs whose name does not carry the answer — rotating a
+ * secret, purging a queue, resetting a ledger.
+ *
+ * Declaring it is cheap and REVERSIBLE is never wrong to omit: the danger zone is now conjunctive
+ * (risky AND irreversible), so an un-annotated custom verb keeps its red *variant* from its risk
+ * level and simply stops being filed under a heading that promises permanence.
+ */
+export var ResourceOperationReversibility;
+(function (ResourceOperationReversibility) {
+    /**
+     * A later operation can restore the prior state — update it back, re-enable it, restore it from
+     * the deletion window. The act may still be serious; serious is what `riskLevel` is for.
+     */
+    ResourceOperationReversibility["REVERSIBLE"] = "reversible";
+    /**
+     * Nothing in the product can undo it: the row is purged, the secret is replaced and the old one is
+     * gone, the ledger is reset with no backup. This is what a danger zone exists to mark, and the
+     * only thing that belongs in one.
+     */
+    ResourceOperationReversibility["IRREVERSIBLE"] = "irreversible";
+})(ResourceOperationReversibility || (ResourceOperationReversibility = {}));
 /**
  * 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
@@ -310,12 +357,52 @@ export var ResourceOperation_ServiceRuntimeMode;
 export var ResourceOperation_CustomServiceImplementationMode;
 (function (ResourceOperation_CustomServiceImplementationMode) {
     ResourceOperation_CustomServiceImplementationMode["OVERRIDE_ALL"] = "override_all";
+    /**
+     * Runs OUTSIDE any database transaction, after preflight and before the transactional core (#535).
+     *
+     * The one phase that may perform an external effect whose outcome must feed the core write — a payment provider
+     * call, for example — because the transactional core's callback can be retried by the database driver and must
+     * never repeat such an effect. Single-owner; requires `transactionalCore: true`; refused inside a caller-owned
+     * transaction. It returns either a patch merged into the core input plus a continuation the core phases read, or
+     * `ALREADY_COMPLETED`, which skips core persistence, managed post-commit effects and token consumption, applies the
+     * synchronous terminal result transforms, and answers the stored state.
+     */
+    ResourceOperation_CustomServiceImplementationMode["BEFORE_TRANSACTIONAL_CORE"] = "before_transactional_core";
     ResourceOperation_CustomServiceImplementationMode["PREFIX_CORE_OPERARTIONS"] = "prefix_core_operations";
     ResourceOperation_CustomServiceImplementationMode["POSTFIX_CORE_OPERARTIONS"] = "postfix_core_operations";
     ResourceOperation_CustomServiceImplementationMode["REPLACE_CORE_OPERARTIONS"] = "between_core_operations";
     ResourceOperation_CustomServiceImplementationMode["AFTER_USER_NOTIFICATIONS"] = "after_user_notifications";
     ResourceOperation_CustomServiceImplementationMode["AT_THE_END"] = "at_the_end";
 })(ResourceOperation_CustomServiceImplementationMode || (ResourceOperation_CustomServiceImplementationMode = {}));
+/** @wildo_source:part:start saas.backend.custom-operation.transactional-core facet:layer:shared facet:family:resource-operation */
+/**
+ * Who delivers an operation occurrence's post-commit effects: its resource-operation audit row and its notifications
+ * (resource-room broadcast and configured notifications).
+ *
+ * The framework delivers them after commit on a best-effort basis: a crash between the commit and the effects loses
+ * them. An operation whose effects must survive that crash declares `IMPLEMENTATION_OUTBOX` on its custom
+ * implementation. The implementation then writes the effects to its own outbox inside the operation's transaction, and
+ * the framework does not deliver them itself, so each is delivered once, by the outbox (#535).
+ *
+ * Reserved for engine-owned writers whose outbox an engine relay delivers. There is no application-facing delivery
+ * surface: an application declaring `IMPLEMENTATION_OUTBOX` would suppress its own audit rows and notifications with
+ * nothing to deliver them.
+ */
+export var ResourceOperation_PostCommitEffectOwnership;
+(function (ResourceOperation_PostCommitEffectOwnership) {
+    /** The framework emits the audit row and dispatches notifications after commit. The default. */
+    ResourceOperation_PostCommitEffectOwnership["FRAMEWORK"] = "framework";
+    /**
+     * The custom implementation owns them: it captures their inputs inside the transactional core and enqueues them in
+     * that same transaction. The framework suppresses its own emission for the occurrence. Resource post-operation hooks
+     * still run and are told the ownership, so a hook whose work the outbox owns can stand down.
+     *
+     * Requires `transactionalCore: true`, because the enqueue must commit with the change. Refused for an operation that
+     * generates a consumable token, because a replayed notification would need the token's secret persisted.
+     */
+    ResourceOperation_PostCommitEffectOwnership["IMPLEMENTATION_OUTBOX"] = "implementation_outbox";
+})(ResourceOperation_PostCommitEffectOwnership || (ResourceOperation_PostCommitEffectOwnership = {}));
+/** @wildo_source:part:end saas.backend.custom-operation.transactional-core */
 export var ResourceParentResourceRequirement;
 (function (ResourceParentResourceRequirement) {
     ResourceParentResourceRequirement["MANDATORY"] = "mandatory";
@@ -759,10 +846,9 @@ export const ScopeMembershipSchema = z.union([z.literal(true), ScopeMembershipSt
  * 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.
+ * Both membership and role refinements are enforced by the backend. `requiredRoles` resolves
+ * against the live application role definitions in the declared scope; unknown held roles do not
+ * confer authority. Frontend visibility decisions are not an authorization substitute.
  */
 export const ReferenceScopeConstraintSchema = z.object({
     /**
@@ -1085,6 +1171,29 @@ export const OUTPUT_ENVELOPE_OPERATIONS = [
 export function isOutputEnvelopeOperation(operationIdentifier) {
     return OUTPUT_ENVELOPE_OPERATIONS.includes(operationIdentifier);
 }
+/**
+ * Does this operation answer with an ARRAY OF ROWS, each validated against the row schema?
+ *
+ * The literal bulk verbs (`CREATE_MANY`, `UPDATE_MANY`) do, and so does a BULK VARIANT of `CREATE`
+ * or `UPDATE` — `haveBulkOperation: true` mints the bulk route as a variant of the single verb, so
+ * its effective verb reads `UPDATE` and only `isBulkOperation` separates it (the same axis issue
+ * #404 added for DELETE). The response DTO builder already declares exactly this — a bulk
+ * create/update's `responseDto` is the per-item row schema — but the three places that VALIDATE
+ * the response each re-derived the rule from the verb alone: the service's output parse, the
+ * controller serializer, and the frontend client. So a bulk "Unassign" of two todos wrote both rows
+ * and then answered a degraded body, which the client refused. They all ask this now.
+ *
+ * Only an array is read per item: a one-row bulk selection travels the single-row path and answers
+ * one row, which the same row schema accepts as it stands.
+ */
+export function respondsWithPerItemRowArray(operation) {
+    const effectiveOperation = operation.resourceOperationLike ?? operation.operationIdentifier;
+    if (effectiveOperation === CoreResourceOperation.CREATE_MANY || effectiveOperation === CoreResourceOperation.UPDATE_MANY) {
+        return true;
+    }
+    return operation.isBulkOperation === true
+        && (effectiveOperation === CoreResourceOperation.CREATE || effectiveOperation === CoreResourceOperation.UPDATE);
+}
 /**
  * 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
@@ -1115,18 +1224,86 @@ export function isOutputEnvelopeOperation(operationIdentifier) {
  * Keep this switch in lockstep with {@link getDefaultResponseSchemaForOperation} and
  * {@link OUTPUT_ENVELOPE_OPERATIONS}.
  */
-export function composeDefaultOperationResponse(operationIdentifier, serviceOutput) {
+export function composeDefaultOperationResponse(operationIdentifier, serviceOutput, isBulkOperation = false) {
     switch (operationIdentifier) {
         case CoreResourceOperation.DELETE:
-            return { id: serviceOutput };
+            /**
+             * A BULK DELETE variant lands HERE, not on `DELETE_MANY` (issue #404).
+             *
+             * `haveBulkOperation: true` mints the bulk route as a VARIANT of DELETE, so its
+             * `operationIdentifier` IS `DELETE` and only `isBulkOperation` distinguishes it. The DTO
+             * builder already knows that — `resources-config-operations.dtos-builder.utils.ts` returns
+             * `DefaultBulkDeleteResponseSchema` for `isBulkOperation && (DELETE | DELETE_MANY)` — so this
+             * switch keying on the NAME alone composed `{ id }` for a response the operation had declared
+             * as `{ deletedIds, deletedCount }`, and output validation refused it with
+             * `expected array at "deletedIds"` AFTER the rows were already deleted.
+             *
+             * That is precisely the lockstep this function's own contract demands ("Keep this switch in
+             * lockstep with `getDefaultResponseSchemaForOperation`"), broken on the one axis the name
+             * cannot express.
+             */
+            return isBulkOperation ? composeBulkDeleteEnvelope(serviceOutput) : { id: serviceOutput };
         case CoreResourceOperation.DELETE_MANY:
-            return Array.isArray(serviceOutput)
-                ? { deletedIds: serviceOutput, deletedCount: serviceOutput.length }
-                : serviceOutput;
+            return composeBulkDeleteEnvelope(serviceOutput);
         default:
             return serviceOutput;
     }
 }
+/**
+ * Lift a delete's raw repository output into `DefaultBulkDeleteResponseSchema`.
+ *
+ * The repository returns `string[]` from `deleteMany` and a bare `string` from `delete` (`''` when
+ * nothing matched). A bulk variant can produce EITHER: the controller normalises a single-element
+ * `_ids` selector to a scalar before the service sees it, so a bulk delete naming one row reaches
+ * the singular path and returns a string. Both must become the same declared envelope, or the
+ * response shape would depend on how many rows the caller happened to name.
+ *
+ * A non-array, non-string output is passed through unchanged so a genuinely malformed value still
+ * fails validation loudly rather than being coerced into a plausible-looking empty envelope.
+ */
+function composeBulkDeleteEnvelope(serviceOutput) {
+    if (Array.isArray(serviceOutput)) {
+        return { deletedIds: serviceOutput, deletedCount: serviceOutput.length };
+    }
+    if (typeof serviceOutput === 'string') {
+        // `''` is the repository's "nothing matched", which is an EMPTY result and not a deleted id.
+        const deletedIds = serviceOutput.length > 0 ? [serviceOutput] : [];
+        return { deletedIds, deletedCount: deletedIds.length };
+    }
+    return serviceOutput;
+}
+/**
+ * Marker key identifying a DEGRADED operation response.
+ *
+ * Deliberately a fixed, namespaced key rather than a class or a symbol: this value crosses the
+ * service → controller → serializer boundary and is JSON-encoded on the way to a webhook delivery
+ * log, so it has to survive `JSON.parse(JSON.stringify(...))` and a structural type guard.
+ */
+export const DEGRADED_OPERATION_RESPONSE_MARKER = '__wildoDegradedResponse';
+/** Structural guard — see {@link DEGRADED_OPERATION_RESPONSE_MARKER} for why it is not a class. */
+export function isDegradedOperationResponse(value) {
+    return (!!value
+        && typeof value === 'object'
+        && value[DEGRADED_OPERATION_RESPONSE_MARKER] === true);
+}
+/**
+ * Build the degraded response for a committed write whose description failed.
+ *
+ * `resourceId` is recovered best-effort from the raw row: absent it, the caller still learns the
+ * write succeeded, which is the load-bearing half. Only `_id`/`id` are read — see the safety
+ * property on {@link DegradedOperationResponse}.
+ */
+export function composeDegradedOperationResponse(serviceOutput) {
+    const row = (serviceOutput && typeof serviceOutput === 'object' && !Array.isArray(serviceOutput))
+        ? serviceOutput
+        : undefined;
+    const candidate = row?._id ?? row?.id;
+    return {
+        [DEGRADED_OPERATION_RESPONSE_MARKER]: true,
+        ...(typeof candidate === 'string' && candidate.length > 0 ? { resourceId: candidate } : {}),
+        reason: 'response_description_failed',
+    };
+}
 // Utility to determine if operation should have request DTO
 export function operationShouldHaveRequestDto(operation) {
     return !OPERATIONS_WITHOUT_REQUEST_BODY.includes(operation);
@@ -1321,4 +1498,27 @@ export function forwardedLabel(descriptor) {
         .isSummaryField()
         .isHidden({ display: true });
 }
+/**
+ * The default is derived from the EFFECTIVE verb — `resourceOperationLike`, else the operation's own
+ * identifier — and a delete of one row or of many is irreversible.
+ *
+ * It read `resourceOperationLike === DELETE` alone, while this file said the default "covers the 53
+ * DELETE / DELETE_MANY variants". A literal core DELETE carries no `resourceOperationLike` (the
+ * factory copies it from the variant, where a core operation has none), so the plain Delete of every
+ * resource derived REVERSIBLE — and the danger zone, which admits what is risky AND irreversible,
+ * never received it. A delete-many-like custom verb (a purge) was missed the same way, and a
+ * confirmation told a purge nothing about permanence.
+ */
+export function resolveOperationReversibility(variant) {
+    if (variant.reversibility)
+        return variant.reversibility;
+    const effective = variant.resourceOperationLike ?? variant.operationIdentifier;
+    return effective === CoreResourceOperation.DELETE || effective === CoreResourceOperation.DELETE_MANY
+        ? ResourceOperationReversibility.IRREVERSIBLE
+        : ResourceOperationReversibility.REVERSIBLE;
+}
+/** True when nothing in the product can undo this operation. See {@link resolveOperationReversibility}. */
+export function isIrreversibleOperation(variant) {
+    return resolveOperationReversibility(variant) === ResourceOperationReversibility.IRREVERSIBLE;
+}
 //# sourceMappingURL=resources.shared.schemas.js.map