@wildo-ai/saas-models 1.0.1 → 1.1.1

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

@@ -5,6 +5,7 @@
  * Related data moved to separate relational models.
  */
 import { z } from 'zod';
+import { ErrorCustomMessageReference } from '../errors/errors.custom-message-ref.shared.definitions.js';
 import { OrganizationProfileSchema } from './organization-profile.shared.schemas.js';
 import { OrganizationPreferencesSchema } from './organization-preferences.shared.schemas.js';
 import { OrganizationNotificationsSchema } from './organization-notifications.shared.schemas.js';
@@ -17,26 +18,247 @@ export var OrganizationStatus;
     OrganizationStatus["TRIAL"] = "TRIAL";
     OrganizationStatus["TRIAL_EXPIRED"] = "TRIAL_EXPIRED";
     OrganizationStatus["CANCELLED"] = "CANCELLED";
+    /**
+     * Marked for deletion and inside its retention window — NOT removed.
+     *
+     * Written by the `request_deletion` lifecycle operation, cleared by `restore`, and consumed by
+     * the `organization-purge` batch once {@link Organization.purgeScheduledAt} has elapsed. A row
+     * in this state is authorization-dead (see
+     * {@link isAuthorityConferringOrganizationStatus}) and data-alive.
+     */
     OrganizationStatus["DELETED"] = "DELETED";
 })(OrganizationStatus || (OrganizationStatus = {}));
+/**
+ * Organization statuses under which a membership STOPS conferring authority.
+ *
+ * ## Why this exists as a named authority
+ *
+ * Until 2026-08-01 `OrganizationStatus` had **zero backend readers**: the execution-context
+ * creator built `initiatorRoles` straight from ACTIVE membership rows without ever looking at the
+ * organization, so no status value affected anything. That made tenant soft-delete impossible to
+ * express — a tenant marked for purge would have kept handing out `ORG_ADMIN` for its whole
+ * retention window, which is the original hazard with a longer fuse rather than a fix.
+ *
+ * The set is declared here, beside the enum it partitions, rather than inline at the consumer, so
+ * that adding a future non-operational status is one edit in the place a reader is already
+ * looking. Consumers call {@link isAuthorityConferringOrganizationStatus}; they must not test
+ * `status === DELETED` inline.
+ *
+ * ## Why these three
+ *
+ * - `DELETED` — marked for purge. The whole point of the soft-delete phase.
+ * - `SUSPENDED` — an administratively halted tenant. Membership must not survive the halt.
+ * - `CANCELLED` — a terminated subscription/tenant. Terminal, like `DELETED`.
+ *
+ * `TRIAL_EXPIRED` is deliberately NOT here: an expired trial still needs its administrators to
+ * sign in and pay, so revoking their authority would make the tenant unrecoverable by its owner.
+ * `ACTIVE` and `TRIAL` are the operational states.
+ *
+ * ⚠️ Fail-CLOSED direction: an unresolvable organization is treated as non-conferring by the
+ * consumer, so a missing row can never widen authority.
+ *
+ * assurance-control: WILDO.ACCESS.LIFECYCLE — access rights are removed when the
+ * scope granting them stops being operational, without waiting for the data to be destroyed.
+ */
+export const ORGANIZATION_STATUSES_WITHOUT_AUTHORITY = new Set([
+    OrganizationStatus.DELETED,
+    OrganizationStatus.SUSPENDED,
+    OrganizationStatus.CANCELLED,
+]);
+/**
+ * True when a membership in an organization of this status still confers its roles.
+ *
+ * The single authority behind the execution-context membership gate. See
+ * {@link ORGANIZATION_STATUSES_WITHOUT_AUTHORITY} for the rationale and the deliberate
+ * `TRIAL_EXPIRED` exclusion.
+ */
+export function isAuthorityConferringOrganizationStatus(status) {
+    if (status === undefined)
+        return false;
+    return !ORGANIZATION_STATUSES_WITHOUT_AUTHORITY.has(status);
+}
 export const OrganizationSchema = z.object({
     _id: z.string().min(1).isPrimaryKey().isSummaryField(),
     name: z.string().min(1).max(100).isDBIndexed().isSummaryField(),
-    /** Org type from config (e.g. 'seller', 'corporate_buyer'). Validated against organizationTypes at creation. */
-    type: z.string().optional().isSummaryField(),
+    /**
+     * Org type from config (for example `seller` or `corporate_buyer`).
+     *
+     * The type selects role policy, membership-derived user-type grants, and
+     * authentication overrides. A generic patch cannot migrate those dependent
+     * invariants atomically, so the value is creation-time identity. A future
+     * type transition must be a dedicated migration operation that reconciles
+     * every dependent member and policy surface.
+     */
+    type: z.string().optional().isSummaryField().excludeFromUpdate(),
+    /**
+     * The tenant's URL-safe identity.
+     *
+     * `.isUnique()` since 2026-08-01, and it closes a real hole rather than restating a known rule:
+     * uniqueness was promised by the resource specification's 409 and enforced by NOTHING — no index
+     * and no application guard — so two organizations could take the same slug. Because the field is
+     * also `.excludeFromUpdate()` (creation-time identity, not an editable label), such a collision
+     * could never be resolved through the API afterwards. It has to be refused at creation.
+     *
+     * Uniqueness is collection-wide, which IS per-application: an application's organizations live in
+     * that application's own database, and the schema carries no `applicationId` to scope by.
+     *
+     * ⚠️ MongoDB-only today. The SQL planner records uniqueness as intent and leaves enforcement
+     * migration-owned, so on a SQL adapter this is a declaration rather than a guarantee.
+     */
     slug: z.string()
         .min(1)
         .max(50)
         .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
         .isDBIndexed()
+        .isUnique({ conflictMessageReference: ErrorCustomMessageReference.ORGANIZATION_SLUG_EXISTS })
         .isSummaryField()
         .excludeFromUpdate(),
-    status: z.enum(OrganizationStatus).default(OrganizationStatus.ACTIVE).isDBIndexed().isSummaryField(),
+    /**
+     * Tenant lifecycle and access posture.
+     *
+     * `.excludeFromUpdate()` since 2026-08-01, and that exclusion is the whole point of the field.
+     * Before it, generic UPDATE carried `status` and the DEFAULT variant of that operation is gated
+     * to `ORG_ADMIN` — while SUSPEND / ACTIVATE are `APP_ADMIN_SUPER_ADMIN`-only and gated by an
+     * `enabledCondition` on the current status. So the org admin of a SUSPENDED tenant could
+     * `PUT /organizations/{id}` with `{"status":"ACTIVE"}` and lift the platform's suspension on
+     * their own organization: the control was defeatable by exactly the party it exists to control.
+     * The configuration had claimed otherwise for a long time — both UPDATE variants carried a
+     * `// status manually excluded for this variant` comment that nothing implemented.
+     *
+     * Lifecycle transitions belong to the dedicated verbs, which own the state machine, the reason,
+     * and the audit trail. This mirrors `OrganizationMemberSchema.status`, whose JSDoc has always
+     * described the same rule for the same reason.
+     *
+     * KNOWN CONSEQUENCE, ACCEPTED: the platform apps-manager's `upsertEntity` re-asserts
+     * `status: ACTIVE` on its update branch when reconciling an existing organization. That write is
+     * now dropped. This is the intended outcome — a provisioning re-run silently returning a
+     * suspended tenant to ACTIVE is the same defect from the other direction. A path that must set
+     * the status goes through the transition operations or a trusted `updateAsSystem`, not a generic
+     * field patch.
+     *
+     * assurance-control: WILDO.ACCESS.SCOPE_CONFINEMENT — a tenant may not lift a platform-imposed
+     * restriction on itself.
+     */
+    status: z.enum(OrganizationStatus).default(OrganizationStatus.ACTIVE).isDBIndexed().isSummaryField().excludeFromUpdate(),
+    /**
+     * Does a platform operator need THIS tenant's approval before an elevation becomes usable?
+     *
+     * The Customer Lockbox posture, and opt-in per tenant exactly as Microsoft and Google ship it. A
+     * tenant that has not staffed an approver must not thereby become unable to receive support, so
+     * the default is `false`: elevations still require a request, a justification, a 4-hour ceiling and
+     * an audit trail — they simply do not wait for a human in the tenant.
+     *
+     * Turning it ON is the strongest available posture and is what regulated buyers ask for by name.
+     *
+     * ⚠️ It does NOT make the tenant unreachable when it has no administrator. A tenant with no
+     * administratively usable owner cannot approve anything, and requiring approval from it would make
+     * its own repair impossible — see `PlatformAccessGrantAutoApprovalReason.TENANT_CANNOT_APPROVE`,
+     * which is measured with the owner floor's own predicate rather than assumed.
+     *
+     * assurance-control: WILDO.ACCESS.CROSS_TENANT_ADMINISTRATION — customer-approved operator access.
+     */
+    platformAccessApprovalRequired: z.boolean().default(false).isAuditEvidence(),
     // Basic timestamps (lifecycle audit is in separate collection)
     createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),
     updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
-    // Soft delete support
-    deletedAt: z.date().optional().isDBIndexed().excludeFromCreate()
+    // Tenant teardown — soft-delete marks (WS-A)
+    /**
+     * When the tenant was MARKED for deletion — the start of its retention window.
+     *
+     * Written by the `request_deletion` lifecycle operation together with `status: DELETED`, and
+     * cleared by `restore`. Both fields move together: `status` is the authorization-relevant half
+     * (it is what {@link isAuthorityConferringOrganizationStatus} reads) and this is the evidence
+     * half.
+     *
+     * ## Why this is not called `deletedAt`
+     *
+     * It replaced a field of that name on 2026-08-01, and the rename is not cosmetic in two separate
+     * ways.
+     *
+     * First, `deletedAt` is RESERVED framework vocabulary: it appears in
+     * `createOrUpdateMandatoryDiscardFields`, so the runtime strips it from every create and update
+     * payload on every resource. A lifecycle operation could therefore never write it — the value
+     * would be discarded and the operation would answer success having recorded nothing, which is
+     * the exact silent-no-op class this workstream exists to remove. No `authoritativeFields`
+     * declaration rescues it; the discard happens regardless.
+     *
+     * Second, the two names mean different things. `deletedAt` answers "when was this row deleted",
+     * and the row is emphatically NOT deleted — it is fully present and restorable for the whole
+     * retention window. Reusing the name would have made every reader who trusts the framework's
+     * vocabulary wrong about the state of the tenant in front of them.
+     *
+     * The predecessor field had zero readers and zero writers in the entire repository, so nothing
+     * observable was lost by replacing it.
+     *
+     * Never a user-facing value on a live organization — it only ever renders as an empty "—", so it
+     * stays hidden from every auto-rendered display/edit surface via `.isHidden()`. An admin/audit
+     * surface that needs to inspect marked rows must opt it back in explicitly.
+     *
+     * ⚠️ This is NOT the purge predicate. Purge eligibility is {@link purgeScheduledAt} — see the
+     * reasoning there.
+     *
+     * ## Why `.nullish()` and not `.optional()`
+     *
+     * `restore` CLEARS this field, and clearing means writing `null` — `undefined` merely omits the
+     * key and leaves the stale mark in place. `preserveServerInjectedFields` copies the authored
+     * value verbatim past the strict re-parse (`hasOwnProperty` + assign), so the `null` genuinely
+     * reaches persistence. With `.optional()` alone the row would then be UNREADABLE: the main schema
+     * rejects `null` for a `z.date()`, so every subsequent read of a restored tenant would throw on
+     * output projection. Verified by probing the real schema rather than assumed.
+     */
+    deletionRequestedAt: z.date().nullish().isDBIndexed().excludeFromCreate().excludeFromUpdate().isHidden(),
+    /**
+     * Serialization token for the organization-owner floor. Never read for meaning — only WRITTEN, to
+     * make concurrent owner-reducing operations conflict with each other.
+     *
+     * ## Why a stored field is the fix rather than a better check
+     *
+     * The floor is a check-then-act on a COUNT: it measures the usable-owner population, then the
+     * caller writes. Under snapshot isolation that is textbook WRITE SKEW — two transactions each
+     * remove a DIFFERENT owner, each observes the other still present, and both commit, producing a
+     * tenant with zero owners that neither was individually permitted to create. No amount of
+     * additional checking closes it, because each transaction's view is internally consistent; a
+     * re-measure after the write cannot see the other transaction's uncommitted row either.
+     *
+     * The standard remedy is to give the two transactions something to collide ON. Every owner-reducing
+     * operation bumps this token on the tenant's own row inside its transaction, so two of them touch
+     * the same document and the storage engine aborts the loser. Verified as a race in
+     * `organization-owner-floor-hostile.mongo.integration.test.ts` (H-2).
+     *
+     * Rejected alternatives: bumping `updatedAt` (semantically wrong — a membership change is not a
+     * modification of the organization, and it would corrupt every "recently changed tenants" surface);
+     * a separate lock collection (a new resource, a new registration, and a second thing to keep
+     * consistent with the floor); an application-level mutex (does not survive multiple processes,
+     * which is exactly the deployment this must work in).
+     *
+     * `.nullish()` because existing tenants predate it and a tenant that has never had an
+     * owner-reducing write legitimately has no token. Absent and zero mean the same thing.
+     */
+    ownerFloorSerializationToken: z.number().int().nullish().excludeFromCreate().excludeFromUpdate().isBackendOnly().isHidden(),
+    /**
+     * When the `organization-purge` batch becomes allowed to destroy this tenant.
+     *
+     * ## Why this is stored rather than derived from `deletionRequestedAt` + a configured window
+     *
+     * The retention window is a PROMISE made to the tenant at the moment of the mark ("your data is
+     * recoverable until <date>"). Deriving eligibility as `deletionRequestedAt < now - window`
+     * re-evaluates that promise against whatever the configuration says at PURGE time, so lowering
+     * the window would retroactively shorten — or immediately expire — every tenant already inside
+     * one. Pinning the deadline at mark time makes the commitment immutable, which is the property
+     * a data-retention commitment has to have, and it makes a per-tenant legal hold expressible
+     * later by moving one field rather than by special-casing the batch predicate.
+     *
+     * The `FILES` soft-delete precedent derives its cutoff instead. That is defensible there — an
+     * orphaned upload is nobody's commitment — and is precisely why the two should not share one
+     * mechanism.
+     *
+     * Server-owned: written only by the lifecycle operations that own the state machine, never by a
+     * client patch.
+     *
+     * `.nullish()` for the same reason as {@link deletionRequestedAt} — `restore` clears it, and a
+     * persisted `null` has to survive the next read.
+     */
+    purgeScheduledAt: z.date().nullish().isDBIndexed().excludeFromCreate().excludeFromUpdate().isHidden()
 });
 /**
  * Organization Context - Core organization with frequently accessed related data
@@ -55,4 +277,4 @@ export const OrganizationContextSchema = OrganizationSchema.extend({
     preferences: OrganizationPreferencesSchema.optional(),
     notifications: OrganizationNotificationsSchema.optional()
 });
-//# sourceMappingURL=organizations.shared.schemas.js.map
+//# sourceMappingURL=organizations.shared.schemas.js.map

package/dist/esm/organizations/organizations.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"organizations.shared.schemas.js","sourceRoot":"","sources":["../../../src/organizations/organizations.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,yBAAyB,EAAE,MAAM,uCAAuC,CAAC;AAClF,OAAO,EAAE,6BAA6B,EAAE,MAAM,2CAA2C,CAAC;AAC1F,OAAO,EAAE,+BAA+B,EAAE,MAAM,6CAA6C,CAAC;AAC9F,OAAO,EAAE,gCAAgC,EAAE,MAAM,2CAA2C,CAAC;AAC7F,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AAKjF,MAAM,CAAN,IAAY,kBAOX;AAPD,WAAY,kBAAkB;IAC5B,uCAAiB,CAAA;IACjB,6CAAuB,CAAA;IACvB,qCAAe,CAAA;IACf,qDAA+B,CAAA;IAC/B,6CAAuB,CAAA;IACvB,yCAAmB,CAAA;AACrB,CAAC,EAPW,kBAAkB,KAAlB,kBAAkB,QAO7B;AAID,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE;IACtD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;IAC/D,gHAAgH;IAChH,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,cAAc,EAAE;IAC5C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;SACb,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,KAAK,CAAC,4BAA4B,CAAC;SACnC,WAAW,EAAE;SACb,cAAc,EAAE;SAChB,iBAAiB,EAAE;IACtB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;IAEpG,+DAA+D;IAC/D,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IACpH,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IAEnG,sBAAsB;IACtB,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,CAAC,iBAAiB,EAAE;CACjE,CAAC,CAAC;AAKH;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,kBAAkB,CAAC,MAAM,CAAC;IACjE,kEAAkE;IAClE,YAAY,EAAE,gCAAgC;IAC9C,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,wBAAwB,CAAC;IAE1C,gDAAgD;IAChD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,6BAA6B;IACjE,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAE3B,yDAAyD;IACzD,OAAO,EAAE,yBAAyB,CAAC,QAAQ,EAAE;IAC7C,WAAW,EAAE,6BAA6B,CAAC,QAAQ,EAAE;IACrD,aAAa,EAAE,+BAA+B,CAAC,QAAQ,EAAE;CAC1D,CAAC,CAAC"}
+{"version":3,"file":"organizations.shared.schemas.js","sourceRoot":"","sources":["../../../../src/organizations/organizations.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Core Organization Shared Schemas\n *\n * Lean organization schema optimized for frequent fetching.\n * Related data moved to separate relational models.\n */\n\nimport { z } from 'zod';\nimport { ErrorCustomMessageReference } from '../errors/errors.custom-message-ref.shared.definitions';\nimport { OrganizationProfileSchema } from './organization-profile.shared.schemas';\nimport { OrganizationPreferencesSchema } from './organization-preferences.shared.schemas';\nimport { OrganizationNotificationsSchema } from './organization-notifications.shared.schemas';\nimport { ScopeFeaturesWithOverridesSchema } from '../features/scope-features.shared.schemas';\nimport { OrganizationMemberSchema } from './organization-members.shared.schemas';\n\n\n\n\nexport enum OrganizationStatus {\n  ACTIVE = 'ACTIVE',\n  SUSPENDED = 'SUSPENDED',\n  TRIAL = 'TRIAL',\n  TRIAL_EXPIRED = 'TRIAL_EXPIRED',\n  CANCELLED = 'CANCELLED',\n  /**\n   * Marked for deletion and inside its retention window — NOT removed.\n   *\n   * Written by the `request_deletion` lifecycle operation, cleared by `restore`, and consumed by\n   * the `organization-purge` batch once {@link Organization.purgeScheduledAt} has elapsed. A row\n   * in this state is authorization-dead (see\n   * {@link isAuthorityConferringOrganizationStatus}) and data-alive.\n   */\n  DELETED = 'DELETED'\n}\n\n/**\n * Organization statuses under which a membership STOPS conferring authority.\n *\n * ## Why this exists as a named authority\n *\n * Until 2026-08-01 `OrganizationStatus` had **zero backend readers**: the execution-context\n * creator built `initiatorRoles` straight from ACTIVE membership rows without ever looking at the\n * organization, so no status value affected anything. That made tenant soft-delete impossible to\n * express — a tenant marked for purge would have kept handing out `ORG_ADMIN` for its whole\n * retention window, which is the original hazard with a longer fuse rather than a fix.\n *\n * The set is declared here, beside the enum it partitions, rather than inline at the consumer, so\n * that adding a future non-operational status is one edit in the place a reader is already\n * looking. Consumers call {@link isAuthorityConferringOrganizationStatus}; they must not test\n * `status === DELETED` inline.\n *\n * ## Why these three\n *\n * - `DELETED` — marked for purge. The whole point of the soft-delete phase.\n * - `SUSPENDED` — an administratively halted tenant. Membership must not survive the halt.\n * - `CANCELLED` — a terminated subscription/tenant. Terminal, like `DELETED`.\n *\n * `TRIAL_EXPIRED` is deliberately NOT here: an expired trial still needs its administrators to\n * sign in and pay, so revoking their authority would make the tenant unrecoverable by its owner.\n * `ACTIVE` and `TRIAL` are the operational states.\n *\n * ⚠️ Fail-CLOSED direction: an unresolvable organization is treated as non-conferring by the\n * consumer, so a missing row can never widen authority.\n *\n * assurance-control: WILDO.ACCESS.LIFECYCLE — access rights are removed when the\n * scope granting them stops being operational, without waiting for the data to be destroyed.\n */\nexport const ORGANIZATION_STATUSES_WITHOUT_AUTHORITY: ReadonlySet<OrganizationStatus> = new Set([\n  OrganizationStatus.DELETED,\n  OrganizationStatus.SUSPENDED,\n  OrganizationStatus.CANCELLED,\n]);\n\n/**\n * True when a membership in an organization of this status still confers its roles.\n *\n * The single authority behind the execution-context membership gate. See\n * {@link ORGANIZATION_STATUSES_WITHOUT_AUTHORITY} for the rationale and the deliberate\n * `TRIAL_EXPIRED` exclusion.\n */\nexport function isAuthorityConferringOrganizationStatus(status: OrganizationStatus | undefined): boolean {\n  if (status === undefined) return false;\n  return !ORGANIZATION_STATUSES_WITHOUT_AUTHORITY.has(status);\n}\n\n\n\nexport const OrganizationSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n  name: z.string().min(1).max(100).isDBIndexed().isSummaryField(),\n  /**\n   * Org type from config (for example `seller` or `corporate_buyer`).\n   *\n   * The type selects role policy, membership-derived user-type grants, and\n   * authentication overrides. A generic patch cannot migrate those dependent\n   * invariants atomically, so the value is creation-time identity. A future\n   * type transition must be a dedicated migration operation that reconciles\n   * every dependent member and policy surface.\n   */\n  type: z.string().optional().isSummaryField().excludeFromUpdate(),\n  /**\n   * The tenant's URL-safe identity.\n   *\n   * `.isUnique()` since 2026-08-01, and it closes a real hole rather than restating a known rule:\n   * uniqueness was promised by the resource specification's 409 and enforced by NOTHING — no index\n   * and no application guard — so two organizations could take the same slug. Because the field is\n   * also `.excludeFromUpdate()` (creation-time identity, not an editable label), such a collision\n   * could never be resolved through the API afterwards. It has to be refused at creation.\n   *\n   * Uniqueness is collection-wide, which IS per-application: an application's organizations live in\n   * that application's own database, and the schema carries no `applicationId` to scope by.\n   *\n   * ⚠️ MongoDB-only today. The SQL planner records uniqueness as intent and leaves enforcement\n   * migration-owned, so on a SQL adapter this is a declaration rather than a guarantee.\n   */\n  slug: z.string()\n    .min(1)\n    .max(50)\n    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)\n    .isDBIndexed()\n    .isUnique({ conflictMessageReference: ErrorCustomMessageReference.ORGANIZATION_SLUG_EXISTS })\n    .isSummaryField()\n    .excludeFromUpdate(),\n  /**\n   * Tenant lifecycle and access posture.\n   *\n   * `.excludeFromUpdate()` since 2026-08-01, and that exclusion is the whole point of the field.\n   * Before it, generic UPDATE carried `status` and the DEFAULT variant of that operation is gated\n   * to `ORG_ADMIN` — while SUSPEND / ACTIVATE are `APP_ADMIN_SUPER_ADMIN`-only and gated by an\n   * `enabledCondition` on the current status. So the org admin of a SUSPENDED tenant could\n   * `PUT /organizations/{id}` with `{\"status\":\"ACTIVE\"}` and lift the platform's suspension on\n   * their own organization: the control was defeatable by exactly the party it exists to control.\n   * The configuration had claimed otherwise for a long time — both UPDATE variants carried a\n   * `// status manually excluded for this variant` comment that nothing implemented.\n   *\n   * Lifecycle transitions belong to the dedicated verbs, which own the state machine, the reason,\n   * and the audit trail. This mirrors `OrganizationMemberSchema.status`, whose JSDoc has always\n   * described the same rule for the same reason.\n   *\n   * KNOWN CONSEQUENCE, ACCEPTED: the platform apps-manager's `upsertEntity` re-asserts\n   * `status: ACTIVE` on its update branch when reconciling an existing organization. That write is\n   * now dropped. This is the intended outcome — a provisioning re-run silently returning a\n   * suspended tenant to ACTIVE is the same defect from the other direction. A path that must set\n   * the status goes through the transition operations or a trusted `updateAsSystem`, not a generic\n   * field patch.\n   *\n   * assurance-control: WILDO.ACCESS.SCOPE_CONFINEMENT — a tenant may not lift a platform-imposed\n   * restriction on itself.\n   */\n  status: z.enum(OrganizationStatus).default(OrganizationStatus.ACTIVE).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * Does a platform operator need THIS tenant's approval before an elevation becomes usable?\n   *\n   * The Customer Lockbox posture, and opt-in per tenant exactly as Microsoft and Google ship it. A\n   * tenant that has not staffed an approver must not thereby become unable to receive support, so\n   * the default is `false`: elevations still require a request, a justification, a 4-hour ceiling and\n   * an audit trail — they simply do not wait for a human in the tenant.\n   *\n   * Turning it ON is the strongest available posture and is what regulated buyers ask for by name.\n   *\n   * ⚠️ It does NOT make the tenant unreachable when it has no administrator. A tenant with no\n   * administratively usable owner cannot approve anything, and requiring approval from it would make\n   * its own repair impossible — see `PlatformAccessGrantAutoApprovalReason.TENANT_CANNOT_APPROVE`,\n   * which is measured with the owner floor's own predicate rather than assumed.\n   *\n   * assurance-control: WILDO.ACCESS.CROSS_TENANT_ADMINISTRATION — customer-approved operator access.\n   */\n  platformAccessApprovalRequired: z.boolean().default(false).isAuditEvidence(),\n\n  // Basic timestamps (lifecycle audit is in separate collection)\n  createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n\n  // Tenant teardown — soft-delete marks (WS-A)\n  /**\n   * When the tenant was MARKED for deletion — the start of its retention window.\n   *\n   * Written by the `request_deletion` lifecycle operation together with `status: DELETED`, and\n   * cleared by `restore`. Both fields move together: `status` is the authorization-relevant half\n   * (it is what {@link isAuthorityConferringOrganizationStatus} reads) and this is the evidence\n   * half.\n   *\n   * ## Why this is not called `deletedAt`\n   *\n   * It replaced a field of that name on 2026-08-01, and the rename is not cosmetic in two separate\n   * ways.\n   *\n   * First, `deletedAt` is RESERVED framework vocabulary: it appears in\n   * `createOrUpdateMandatoryDiscardFields`, so the runtime strips it from every create and update\n   * payload on every resource. A lifecycle operation could therefore never write it — the value\n   * would be discarded and the operation would answer success having recorded nothing, which is\n   * the exact silent-no-op class this workstream exists to remove. No `authoritativeFields`\n   * declaration rescues it; the discard happens regardless.\n   *\n   * Second, the two names mean different things. `deletedAt` answers \"when was this row deleted\",\n   * and the row is emphatically NOT deleted — it is fully present and restorable for the whole\n   * retention window. Reusing the name would have made every reader who trusts the framework's\n   * vocabulary wrong about the state of the tenant in front of them.\n   *\n   * The predecessor field had zero readers and zero writers in the entire repository, so nothing\n   * observable was lost by replacing it.\n   *\n   * Never a user-facing value on a live organization — it only ever renders as an empty \"—\", so it\n   * stays hidden from every auto-rendered display/edit surface via `.isHidden()`. An admin/audit\n   * surface that needs to inspect marked rows must opt it back in explicitly.\n   *\n   * ⚠️ This is NOT the purge predicate. Purge eligibility is {@link purgeScheduledAt} — see the\n   * reasoning there.\n   *\n   * ## Why `.nullish()` and not `.optional()`\n   *\n   * `restore` CLEARS this field, and clearing means writing `null` — `undefined` merely omits the\n   * key and leaves the stale mark in place. `preserveServerInjectedFields` copies the authored\n   * value verbatim past the strict re-parse (`hasOwnProperty` + assign), so the `null` genuinely\n   * reaches persistence. With `.optional()` alone the row would then be UNREADABLE: the main schema\n   * rejects `null` for a `z.date()`, so every subsequent read of a restored tenant would throw on\n   * output projection. Verified by probing the real schema rather than assumed.\n   */\n  deletionRequestedAt: z.date().nullish().isDBIndexed().excludeFromCreate().excludeFromUpdate().isHidden(),\n  /**\n   * Serialization token for the organization-owner floor. Never read for meaning — only WRITTEN, to\n   * make concurrent owner-reducing operations conflict with each other.\n   *\n   * ## Why a stored field is the fix rather than a better check\n   *\n   * The floor is a check-then-act on a COUNT: it measures the usable-owner population, then the\n   * caller writes. Under snapshot isolation that is textbook WRITE SKEW — two transactions each\n   * remove a DIFFERENT owner, each observes the other still present, and both commit, producing a\n   * tenant with zero owners that neither was individually permitted to create. No amount of\n   * additional checking closes it, because each transaction's view is internally consistent; a\n   * re-measure after the write cannot see the other transaction's uncommitted row either.\n   *\n   * The standard remedy is to give the two transactions something to collide ON. Every owner-reducing\n   * operation bumps this token on the tenant's own row inside its transaction, so two of them touch\n   * the same document and the storage engine aborts the loser. Verified as a race in\n   * `organization-owner-floor-hostile.mongo.integration.test.ts` (H-2).\n   *\n   * Rejected alternatives: bumping `updatedAt` (semantically wrong — a membership change is not a\n   * modification of the organization, and it would corrupt every \"recently changed tenants\" surface);\n   * a separate lock collection (a new resource, a new registration, and a second thing to keep\n   * consistent with the floor); an application-level mutex (does not survive multiple processes,\n   * which is exactly the deployment this must work in).\n   *\n   * `.nullish()` because existing tenants predate it and a tenant that has never had an\n   * owner-reducing write legitimately has no token. Absent and zero mean the same thing.\n   */\n  ownerFloorSerializationToken: z.number().int().nullish().excludeFromCreate().excludeFromUpdate().isBackendOnly().isHidden(),\n\n  /**\n   * When the `organization-purge` batch becomes allowed to destroy this tenant.\n   *\n   * ## Why this is stored rather than derived from `deletionRequestedAt` + a configured window\n   *\n   * The retention window is a PROMISE made to the tenant at the moment of the mark (\"your data is\n   * recoverable until <date>\"). Deriving eligibility as `deletionRequestedAt < now - window`\n   * re-evaluates that promise against whatever the configuration says at PURGE time, so lowering\n   * the window would retroactively shorten — or immediately expire — every tenant already inside\n   * one. Pinning the deadline at mark time makes the commitment immutable, which is the property\n   * a data-retention commitment has to have, and it makes a per-tenant legal hold expressible\n   * later by moving one field rather than by special-casing the batch predicate.\n   *\n   * The `FILES` soft-delete precedent derives its cutoff instead. That is defensible there — an\n   * orphaned upload is nobody's commitment — and is precisely why the two should not share one\n   * mechanism.\n   *\n   * Server-owned: written only by the lifecycle operations that own the state machine, never by a\n   * client patch.\n   *\n   * `.nullish()` for the same reason as {@link deletionRequestedAt} — `restore` clears it, and a\n   * persisted `null` has to survive the next read.\n   */\n  purgeScheduledAt: z.date().nullish().isDBIndexed().excludeFromCreate().excludeFromUpdate().isHidden()\n});\n\n\nexport type Organization = z.infer<typeof OrganizationSchema>;\n\n/**\n * Organization Context - Core organization with frequently accessed related data\n *\n * Lifecycle audit information is now tracked through auditable events\n */\nexport const OrganizationContextSchema = OrganizationSchema.extend({\n  // Scope features (stored separately from billing, scope-agnostic)\n  planFeatures: ScopeFeaturesWithOverridesSchema,\n  members: z.array(OrganizationMemberSchema),\n\n  // Basic display info (most frequently accessed)\n  displayName: z.string().optional(), // Can be different from name\n  logoUrl: z.url().optional(),\n\n  // Extended related data (optional - populated as needed)\n  profile: OrganizationProfileSchema.optional(),\n  preferences: OrganizationPreferencesSchema.optional(),\n  notifications: OrganizationNotificationsSchema.optional()\n});\n\n\nexport type OrganizationContext = z.infer<typeof OrganizationContextSchema>;\n"]}

package/dist/esm/organizations/tenant-teardown-config.shared.schemas.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+/**
+ * Tenant teardown — the operator-tunable half of soft-delete + retention window + purge.
+ *
+ * ## Why this is its own config block
+ *
+ * `LifecycleConfigSchema` already exists and is about the USER lifecycle (activation, engagement,
+ * dormancy detection). Folding tenant teardown into it would merge two unrelated concerns behind
+ * one master switch — and that switch defaults to `enabled: false`, which would make an
+ * organization's retention window silently depend on whether the app opted into user-engagement
+ * tracking. Tenant teardown has no such opt-in: an application that deletes tenants always has a
+ * retention window, so the block is optional only in the sense that its defaults are usually right.
+ *
+ * ## Why every value has a default
+ *
+ * Omitting the block entirely must produce a working, safe configuration — the alternative is an
+ * application that ships without a purge schedule and accumulates marked-but-never-destroyed
+ * tenants, which is the failure mode a retention window is supposed to prevent.
+ */
+export declare const TenantTeardownConfigSchema: z.ZodObject<{
+    retentionWindowDays: z.ZodDefault<z.ZodNumber>;
+    purgeCronSchedule: z.ZodDefault<z.ZodString>;
+    purgeBatchSize: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type TenantTeardownConfig = z.infer<typeof TenantTeardownConfigSchema>;
+/** Defaults applied when an application declares no `tenantTeardown` block at all. */
+export declare const TENANT_TEARDOWN_CONFIG_DEFAULTS: TenantTeardownConfig;
+/**
+ * Resolve the purge deadline for a tenant being marked right now.
+ *
+ * Shared by the lifecycle operation that writes `purgeScheduledAt` and by the tests that pin it,
+ * so the window arithmetic has one home. Takes `markedAt` explicitly rather than reading the clock
+ * so the caller's transaction timestamp and the deadline cannot disagree.
+ */
+export declare function resolveOrganizationPurgeScheduledAt(markedAt: Date, config: TenantTeardownConfig | undefined): Date;
+//# sourceMappingURL=tenant-teardown-config.shared.schemas.d.ts.map

package/dist/esm/organizations/tenant-teardown-config.shared.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-teardown-config.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/organizations/tenant-teardown-config.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,0BAA0B;;;;iBAkCrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,sFAAsF;AACtF,eAAO,MAAM,+BAA+B,EAAE,oBAA2D,CAAC;AAE1G;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,IAAI,EACd,MAAM,EAAE,oBAAoB,GAAG,SAAS,GACvC,IAAI,CAGN"}

package/dist/esm/organizations/tenant-teardown-config.shared.schemas.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+/**
+ * Tenant teardown — the operator-tunable half of soft-delete + retention window + purge.
+ *
+ * ## Why this is its own config block
+ *
+ * `LifecycleConfigSchema` already exists and is about the USER lifecycle (activation, engagement,
+ * dormancy detection). Folding tenant teardown into it would merge two unrelated concerns behind
+ * one master switch — and that switch defaults to `enabled: false`, which would make an
+ * organization's retention window silently depend on whether the app opted into user-engagement
+ * tracking. Tenant teardown has no such opt-in: an application that deletes tenants always has a
+ * retention window, so the block is optional only in the sense that its defaults are usually right.
+ *
+ * ## Why every value has a default
+ *
+ * Omitting the block entirely must produce a working, safe configuration — the alternative is an
+ * application that ships without a purge schedule and accumulates marked-but-never-destroyed
+ * tenants, which is the failure mode a retention window is supposed to prevent.
+ */
+export const TenantTeardownConfigSchema = z.object({
+    /**
+     * How long a marked tenant stays restorable before the purge batch may destroy it.
+     *
+     * Default 30 days. The window is a commitment, not a scheduling hint: the value is read ONCE,
+     * when the tenant is marked, and pinned onto `Organization.purgeScheduledAt`. Lowering this
+     * setting therefore affects only tenants marked afterwards — tenants already inside a window
+     * keep the deadline they were promised. See `Organization.purgeScheduledAt` for why the deadline
+     * is stored rather than recomputed.
+     *
+     * 30 days sits inside the band comparable products use (roughly 20–90 days) and inside the
+     * one-month response period GDPR Art. 12(3) allows for acting on an erasure request, so the
+     * default does not put an application in breach by itself. It is not legal advice: an
+     * application with its own retention obligations must set this deliberately.
+     */
+    retentionWindowDays: z.number().int().positive().default(30),
+    /**
+     * Cron schedule for the engine-owned `organization-purge` batch. Default 03:00 daily.
+     *
+     * Daily rather than hourly on purpose: the window is measured in days, so a finer cadence buys
+     * no promptness that anyone can observe and only multiplies the scans.
+     */
+    purgeCronSchedule: z.string().default('0 3 * * *'),
+    /**
+     * Maximum tenants destroyed per purge run.
+     *
+     * A purge cascades across every child resource of a tenant, so an unbounded run after a mass
+     * offboarding could hold database resources for a long time. Anything not reached this run is
+     * reached by the next one — the deadline has passed, so there is no correctness cost to
+     * spreading the work, and a bounded run keeps one bad batch from becoming an outage.
+     */
+    purgeBatchSize: z.number().int().positive().default(50),
+});
+/** Defaults applied when an application declares no `tenantTeardown` block at all. */
+export const TENANT_TEARDOWN_CONFIG_DEFAULTS = TenantTeardownConfigSchema.parse({});
+/**
+ * Resolve the purge deadline for a tenant being marked right now.
+ *
+ * Shared by the lifecycle operation that writes `purgeScheduledAt` and by the tests that pin it,
+ * so the window arithmetic has one home. Takes `markedAt` explicitly rather than reading the clock
+ * so the caller's transaction timestamp and the deadline cannot disagree.
+ */
+export function resolveOrganizationPurgeScheduledAt(markedAt, config) {
+    const retentionWindowDays = config?.retentionWindowDays ?? TENANT_TEARDOWN_CONFIG_DEFAULTS.retentionWindowDays;
+    return new Date(markedAt.getTime() + retentionWindowDays * 24 * 60 * 60 * 1000);
+}
+//# sourceMappingURL=tenant-teardown-config.shared.schemas.js.map

package/dist/esm/organizations/tenant-teardown-config.shared.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-teardown-config.shared.schemas.js","sourceRoot":"","sources":["../../../../src/organizations/tenant-teardown-config.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD;;;;;;;;;;;;;OAaG;IACH,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IAE5D;;;;;OAKG;IACH,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC;IAElD;;;;;;;OAOG;IACH,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;CACxD,CAAC,CAAC;AAIH,sFAAsF;AACtF,MAAM,CAAC,MAAM,+BAA+B,GAAyB,0BAA0B,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAE1G;;;;;;GAMG;AACH,MAAM,UAAU,mCAAmC,CACjD,QAAc,EACd,MAAwC;IAExC,MAAM,mBAAmB,GAAG,MAAM,EAAE,mBAAmB,IAAI,+BAA+B,CAAC,mBAAmB,CAAC;IAC/G,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;AAClF,CAAC","sourcesContent":["import { z } from 'zod';\n\n/**\n * Tenant teardown — the operator-tunable half of soft-delete + retention window + purge.\n *\n * ## Why this is its own config block\n *\n * `LifecycleConfigSchema` already exists and is about the USER lifecycle (activation, engagement,\n * dormancy detection). Folding tenant teardown into it would merge two unrelated concerns behind\n * one master switch — and that switch defaults to `enabled: false`, which would make an\n * organization's retention window silently depend on whether the app opted into user-engagement\n * tracking. Tenant teardown has no such opt-in: an application that deletes tenants always has a\n * retention window, so the block is optional only in the sense that its defaults are usually right.\n *\n * ## Why every value has a default\n *\n * Omitting the block entirely must produce a working, safe configuration — the alternative is an\n * application that ships without a purge schedule and accumulates marked-but-never-destroyed\n * tenants, which is the failure mode a retention window is supposed to prevent.\n */\nexport const TenantTeardownConfigSchema = z.object({\n  /**\n   * How long a marked tenant stays restorable before the purge batch may destroy it.\n   *\n   * Default 30 days. The window is a commitment, not a scheduling hint: the value is read ONCE,\n   * when the tenant is marked, and pinned onto `Organization.purgeScheduledAt`. Lowering this\n   * setting therefore affects only tenants marked afterwards — tenants already inside a window\n   * keep the deadline they were promised. See `Organization.purgeScheduledAt` for why the deadline\n   * is stored rather than recomputed.\n   *\n   * 30 days sits inside the band comparable products use (roughly 20–90 days) and inside the\n   * one-month response period GDPR Art. 12(3) allows for acting on an erasure request, so the\n   * default does not put an application in breach by itself. It is not legal advice: an\n   * application with its own retention obligations must set this deliberately.\n   */\n  retentionWindowDays: z.number().int().positive().default(30),\n\n  /**\n   * Cron schedule for the engine-owned `organization-purge` batch. Default 03:00 daily.\n   *\n   * Daily rather than hourly on purpose: the window is measured in days, so a finer cadence buys\n   * no promptness that anyone can observe and only multiplies the scans.\n   */\n  purgeCronSchedule: z.string().default('0 3 * * *'),\n\n  /**\n   * Maximum tenants destroyed per purge run.\n   *\n   * A purge cascades across every child resource of a tenant, so an unbounded run after a mass\n   * offboarding could hold database resources for a long time. Anything not reached this run is\n   * reached by the next one — the deadline has passed, so there is no correctness cost to\n   * spreading the work, and a bounded run keeps one bad batch from becoming an outage.\n   */\n  purgeBatchSize: z.number().int().positive().default(50),\n});\n\nexport type TenantTeardownConfig = z.infer<typeof TenantTeardownConfigSchema>;\n\n/** Defaults applied when an application declares no `tenantTeardown` block at all. */\nexport const TENANT_TEARDOWN_CONFIG_DEFAULTS: TenantTeardownConfig = TenantTeardownConfigSchema.parse({});\n\n/**\n * Resolve the purge deadline for a tenant being marked right now.\n *\n * Shared by the lifecycle operation that writes `purgeScheduledAt` and by the tests that pin it,\n * so the window arithmetic has one home. Takes `markedAt` explicitly rather than reading the clock\n * so the caller's transaction timestamp and the deadline cannot disagree.\n */\nexport function resolveOrganizationPurgeScheduledAt(\n  markedAt: Date,\n  config: TenantTeardownConfig | undefined,\n): Date {\n  const retentionWindowDays = config?.retentionWindowDays ?? TENANT_TEARDOWN_CONFIG_DEFAULTS.retentionWindowDays;\n  return new Date(markedAt.getTime() + retentionWindowDays * 24 * 60 * 60 * 1000);\n}\n"]}

package/dist/esm/provider-registration-runtime.exports.d.ts

@@ -0,0 +1,4 @@
+export * from "./external-providers/provider-capability.shared.schemas";
+export * from "./external-providers/provider-metadata.shared.schemas";
+export * from './external-providers/provider-usage-pricing.shared.schemas';
+//# sourceMappingURL=provider-registration-runtime.exports.d.ts.map

package/dist/esm/provider-registration-runtime.exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-registration-runtime.exports.d.ts","sourceRoot":"","sources":["../../../src/provider-registration-runtime.exports.ts"],"names":[],"mappings":"AAAA,cAAc,yDAAyD,CAAC;AACxE,cAAc,uDAAuD,CAAC;AACtE,cAAc,4DAA4D,CAAC"}

package/dist/esm/provider-registration-runtime.exports.js

@@ -0,0 +1,4 @@
+export * from "./external-providers/provider-capability.shared.schemas.js";
+export * from "./external-providers/provider-metadata.shared.schemas.js";
+export * from './external-providers/provider-usage-pricing.shared.schemas.js';
+//# sourceMappingURL=provider-registration-runtime.exports.js.map

package/dist/esm/provider-registration-runtime.exports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-registration-runtime.exports.js","sourceRoot":"","sources":["../../../src/provider-registration-runtime.exports.ts"],"names":[],"mappings":"AAAA,cAAc,yDAAyD,CAAC;AACxE,cAAc,uDAAuD,CAAC;AACtE,cAAc,4DAA4D,CAAC","sourcesContent":["export * from \"./external-providers/provider-capability.shared.schemas\";\nexport * from \"./external-providers/provider-metadata.shared.schemas\";\nexport * from './external-providers/provider-usage-pricing.shared.schemas';\n"]}

package/dist/esm/public-runtime/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @wildo_source:part:start saas.public-runtime.contract facet:layer:shared facet:family:bundle-boundary
+ *
+ * @wildo-package-subpath @wildo-ai/saas-models/public-runtime
+ *
+ * Browser-safe, decorator-framework-free atom subset of
+ * `@wildo-ai/saas-models`.
+ *
+ * Why this subpath exists:
+ *   The package's root barrel (`./index.ts`) calls `initZodDecorators()` at
+ *   module load (line 3) and re-exports the entire decorator-framework-bound
+ *   schema graph (~150 schemas, transitively pulls
+ *   `@wildo-ai/external-connectors-models` + `@wildo-ai/zod-decorators` +
+ *   `reflect-metadata`). Browser bundles that need only a handful of stable
+ *   atoms (cross-frontend handoff DTOs, canonical HTTP header keys, locale
+ *   enums) should NOT pay that cost.
+ *
+ *   This subpath exposes that minimal stable surface, sourced from
+ *   side-effect-free atom files (saas-models-public-runtime.md K-1 / K-2 /
+ *   K-4):
+ *
+ *     - Cross-Frontend Handoff + Token Exchange DTO atoms
+ *       (`../security/authentications/cross-frontend-handoff.shared.dto.schemas`):
+ *       `CrossFrontendHandoffErrorCode`, `CrossFrontendHandoffRequestSchema`,
+ *       `CrossFrontendHandoffResponseSchema`, `TokenExchangeRequestSchema`,
+ *       `TokenExchangeResponseSchema`,
+ *       `CrossFrontendHandoffRequest`, `CrossFrontendHandoffResponse`,
+ *       `TokenExchangeRequest`, `TokenExchangeResponse`. The token-exchange
+ *       schemas were added
+ *       in cross-app-jwt-propagation.md Step 5 — every receiver of an
+ *       AUTH_CODE_EXCHANGE token (SaaS app, docs site) is by construction
+ *       a client-bundle target, so the response shape MUST live here too
+ *       (not just in the heavy backend schemas barrel).
+ *     - Frontend-kind enum
+ *       (`../config/app-frontend-type.shared.schemas`): `AppFrontendType`
+ *       — the SAAS_APP / STATIC_WEBSITE / TECH_DOC runtime taxonomy.
+ *       Consumed by website discovery, scaffolding, CSP config, and
+ *       companion services that need to introspect a service's runtime
+ *       kind without booting the full schema graph. The atom file's
+ *       file-level JSDoc is the canonical home for the kind-by-kind
+ *       rationale AND the locked "no native variants" design decision
+ *       — read that file before authoring any AppFrontendType-driven
+ *       conditional.
+ *     - Canonical HTTP header keys (`../requests/header-keys.shared`):
+ *       `WildoHeaderKeys` (already a zero-dep `as const` atom — re-exported
+ *       whole; per K-2 splitting it would itself violate DRY).
+ *     - Locale enums (re-exported transparently from
+ *       `@wildo-ai/presets-components-models/public-runtime`):
+ *       `AvailableLanguage`, `TextDirection`. Consumers see ONE import path
+ *       (`@wildo-ai/saas-models/public-runtime`) — the
+ *       `presets-components-models/public-runtime` subpath is an internal
+ *       seam (saas-models-public-runtime.md K-6).
+ *
+ * @wildo-boundary  (saas-models-public-runtime.md K-3)
+ *   - This file and every file it transitively imports MUST NOT import from:
+ *     `@wildo-ai/zod-decorators`, `@wildo-ai/external-connectors-models`,
+ *     the `@wildo-ai/presets-components-models` ROOT barrel (only the
+ *     `/public-runtime` subpath of that package is allowed), `inversify`,
+ *     `reflect-metadata`, `mongoose`, `axios`, `express`, `socket.io`,
+ *     `pino`, `helmet`, `argon2`, `bcrypt`, `jsonwebtoken`.
+ *   - DO NOT import from this package's ROOT barrel (`../index`) — that
+ *     barrel runs `initZodDecorators()` and pulls the full schema tree.
+ *   - Allowed imports: `zod` (peer dep, browser-safe), files inside
+ *     `./public-runtime/`, the atom files extracted by Steps 1 + 2 of the
+ *     plan, and the
+ *     `@wildo-ai/presets-components-models/public-runtime` subpath.
+ *
+ * @wildo-bundle-budget
+ *   The output of this barrel + transitive imports MUST stay free of:
+ *   `initZodDecorators()` invocation, `reflect-metadata`, the full
+ *   `authentication.shared.dto.schemas.ts` web of types
+ *   (`UserContextSchema`, `SessionType`, `AuthMethod`, `AuthFactorLevel`,
+ *   `AuthSessionPurpose`, `AuthUtils`). The Step 5 vitest boundary test
+ *   snapshots `Object.getOwnPropertyNames(z.ZodType.prototype)` before and
+ *   after importing this module and asserts the prototype is unchanged
+ *   (proof that `initZodDecorators` did NOT run).
+ *
+ * @wildo-dry-contract
+ *   Every atom exposed here lives in EXACTLY one source file. The original
+ *   home (e.g. `authentication.shared.dto.schemas.ts`,
+ *   `localization/language.shared.schemas.ts`) re-exports from the same atom
+ *   so existing root-barrel consumers keep working unchanged. Adding a new
+ *   atom: split it out of its current heavy file FIRST (matching K-2
+ *   protocol), add a re-export at the original home, then add the import
+ *   here. NEVER duplicate a declaration into a `_public-runtime/` folder.
+ */
+export { CrossFrontendHandoffErrorCode, CrossFrontendHandoffRequestSchema, CrossFrontendHandoffResponseSchema, TokenExchangeRequestSchema, TokenExchangeResponseSchema, type CrossFrontendHandoffRequest, type CrossFrontendHandoffResponse, type TokenExchangeRequest, type TokenExchangeResponse, } from '../security/authentications/cross-frontend-handoff.shared.dto.schemas';
+/**
+ * The single same-origin redirect predicate.
+ *
+ * On the bundle-safe seam because the two BROWSER receivers of a post-authentication redirect — the
+ * SaaS app (`saas-frontend-lib`) and the docs site (`saas-technical-doc`) — are client-bundle targets
+ * by construction, while the ISSUER-side schema in this package validates the same value on the
+ * server. All three must reach one predicate or they drift; they already had, in the same direction,
+ * across four hand-written copies. The source atom is import-free, so it adds nothing to the budget.
+ */
+export { isSameOriginRedirectPath } from '../security/authentications/same-origin-redirect-path.shared';
+export { WildoHeaderKeys } from '../requests/header-keys.shared';
+/**
+ * Main API mount prefix (`/api/v1`) — the SINGLE SOURCE OF TRUTH for the path
+ * under which the entire main controllers registry is served. Exposed on the
+ * bundle-safe seam because browser-bound runtimes that call the SaaS backend
+ * (e.g. the docs auth client's token-exchange / cross-frontend-handoff
+ * requests) must prefix their request URLs with the SAME value the backend
+ * mounts and the SaaS-app HTTP client uses. Deriving every consumer from one
+ * symbol is what prevents the prefix-drift class — a mismatched prefix
+ * silently breaks auth (see the refresh-cookie `Path` regression that
+ * motivated the shared symbol). The source atom
+ * (`../requests/manual-controllers-routes-urls`) is import-free, so it adds
+ * nothing to the decorator-free bundle budget.
+ */
+export { MAIN_API_BASE_PATH } from '../requests/manual-controllers-routes-urls';
+export { AppFrontendType } from '../config/app-frontend-type.shared.schemas';
+/**
+ * Canonical Zod-issue rendering. Browser-bound runtimes validate untrusted
+ * input too — MDX frontmatter at build time, API responses at runtime — and
+ * each one previously re-derived its own `path: message` formatter, drifting on
+ * root labels and truncation. The source atom is import-free (the issue shape is
+ * structural, not a `zod` type import), so it adds nothing to the bundle budget.
+ */
+export { ALL_ZOD_ISSUES, DEFAULT_ZOD_ISSUE_RENDER_LIMIT, ZOD_ROOT_ISSUE_PATH_LABEL, formatZodIssue, formatZodIssues, summarizeZodIssues, type FormattableZodIssue, type ZodIssueFormattingOptions, } from '../errors/zod-issue-formatting.shared.utils';
+export { AvailableLanguage, TextDirection, } from '@wildo-ai/presets-components-models/public-runtime';
+/**
+ * Provider metadata atom (provider-registration-refactor §Phase 0.1 +
+ * §Phase 1.g). The schema is built with plain Zod (no decorator
+ * framework) and the type is `z.infer<…>`. Re-exported here so the
+ * browser-bound `@wildo-ai/external-connectors-public/app`,
+ * `@wildo-ai/external-connectors-public/techdoc`, and
+ * `@wildo-ai/external-connectors-public/website` can consume it WITHOUT
+ * pulling the saas-models
+ * root barrel (which would boot `initZodDecorators()`).
+ */
+export { buildProviderDisplayNameLabelKey, ProviderMetadataSchema, type ProviderMetadata, } from '../external-providers/provider-metadata.shared.schemas';
+/**
+ * Frontend-provider bootstrap atoms shared by browser-bound runtimes.
+ *
+ * Safe for `/public-runtime` because the entry/block schemas depend only on
+ * plain Zod plus `ProviderMetadataSchema`; the heavier
+ * `AppConfiguration_FrontendBootstrapResponse` contract stays on the root-barrel
+ * side.
+ */
+export { FrontendProviderEntrySchema, FrontendProvidersBlockSchema, type FrontendProviderEntry, type FrontendProvidersBlock, } from '../external-providers/frontend-provider-entry.shared.schemas';
+/**
+ * Provider capability atoms (provider-registration-refactor §Phase 0.2
+ * + §Phase 1.g). Closed built-in enum + open declaration-merging seam
+ * + computed union type. Pure types and `as const` — no Zod, no
+ * decorators, no side effects. Required by every facet's provider
+ * module shape, so it MUST live on the bundle-safe seam.
+ */
+export { BUILTIN_PROVIDER_CAPABILITY, type BuiltinProviderCapability, type AppCustomProviderCapabilities, type ProviderCapability, } from '../external-providers/provider-capability.shared.schemas';
+export { BUILTIN_PROVIDER_PROTOCOL, type BuiltinProviderProtocol, type ProviderProtocol, } from '../external-providers/provider-protocol.shared.schemas';
+/**
+ * Generic registry composition core (provider-registration-refactor
+ * §Phase 1.e + §Phase 1.g). Used by every facet's `compose<Facet>Providers`
+ * wrapper (backend, frontend-app, frontend-techdoc, frontend-website).
+ * The browser-bound facets need this on the bundle-safe seam; the backend
+ * facet inherits via the same import path for DRY.
+ *
+ * Pure runtime — only TYPE-imports `ProviderCapability` from the atom
+ * above, so the closure stays decorator-free.
+ */
+export { composeProviderRegistry, ProviderCompositionConflictError, type ProviderRegistryFragment, type ComposedProviderRegistry, type ProviderCompositionConflict, } from '../external-providers/compose-provider-registry.shared';
+/** @wildo_source:part:end saas.public-runtime.contract */
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/public-runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/public-runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAEH,OAAO,EACH,6BAA6B,EAC7B,iCAAiC,EACjC,kCAAkC,EAClC,0BAA0B,EAC1B,2BAA2B,EAC3B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC7B,MAAM,uEAAuE,CAAC;AAE/E;;;;;;;;GAQG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,8DAA8D,CAAC;AAExG,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,4CAA4C,CAAC;AAEhF,OAAO,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAE7E;;;;;;GAMG;AACH,OAAO,EACH,cAAc,EACd,8BAA8B,EAC9B,yBAAyB,EACzB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,GACjC,MAAM,6CAA6C,CAAC;AAErD,OAAO,EACH,iBAAiB,EACjB,aAAa,GAChB,MAAM,oDAAoD,CAAC;AAE5D;;;;;;;;;GASG;AACH,OAAO,EACH,gCAAgC,EAChC,sBAAsB,EACtB,KAAK,gBAAgB,GACxB,MAAM,wDAAwD,CAAC;AAEhE;;;;;;;GAOG;AACH,OAAO,EACH,2BAA2B,EAC3B,4BAA4B,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC9B,MAAM,8DAA8D,CAAC;AAEtE;;;;;;GAMG;AACH,OAAO,EACH,2BAA2B,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,6BAA6B,EAClC,KAAK,kBAAkB,GAC1B,MAAM,0DAA0D,CAAC;AAClE,OAAO,EACH,yBAAyB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,GACxB,MAAM,wDAAwD,CAAC;AAEhE;;;;;;;;;GASG;AACH,OAAO,EACH,uBAAuB,EACvB,gCAAgC,EAChC,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,GACnC,MAAM,wDAAwD,CAAC;AAEhE,0DAA0D"}