@wildo-ai/saas-models 1.1.4 → 1.1.5

package/dist/esm/organizations/organization-units.shared.schemas.js

@@ -17,6 +17,7 @@
  */
 import { z } from 'zod';
 import { ErrorCustomMessageReference } from '../errors/errors.custom-message-ref.shared.definitions.js';
+import { ExternalIdentitySource } from '../security/authentications/authentication.shared.schemas.js';
 // ===============================
 // ORGANIZATION UNIT ENUMS
 // ===============================
@@ -93,11 +94,20 @@ export var OrganizationUnit_PermissionInheritanceType;
  * under the same parent can each find nothing and each succeed. The compound index closes that
  * window at the database.
  *
- * ⚠️ The index is a **MongoDB-only** guarantee today. The SQL planner records uniqueness as intent
- * and leaves enforcement migration-owned, so the application guard in the unit custom
- * implementation is KEPT as the cross-adapter backstop rather than deleted as redundant. The two
- * raise the same {@link ErrorCustomMessageReference.ORGANIZATION_UNIT_CODE_EXISTS} so a client sees
- * one code for one condition, whichever layer catches it.
+ * BOTH adapters enforce it. This said the index was a "MongoDB-only guarantee today" because the SQL
+ * planner only records uniqueness as intent — true of the PLANNER, and stale about the system:
+ * enforcement is migration-owned and the migrations exist, so a PostgreSQL-backed application really
+ * does carry
+ * `create unique index … ("organizationId", "parentUnitId", "code") nulls not distinct where "code"
+ * is not null` (read from `wonder-crm`'s initial schema, 2026-09-20). Corrected rather than deleted
+ * because the reasoning is what a reader needs: the plan is INTENT, the migration is ENFORCEMENT, and
+ * a resource change is not finished until every PostgreSQL-backed surface has one
+ * (`.claude/rules/engine-resource-changes-owe-migrations.md`).
+ *
+ * The application guard in the unit custom implementation is KEPT anyway — not as a cross-adapter
+ * backstop now, but because it raises the same
+ * {@link ErrorCustomMessageReference.ORGANIZATION_UNIT_CODE_EXISTS} the index maps to, so a client
+ * sees one code for one condition whichever layer catches it first.
  */
 export const OrganizationUnitSchema = z.object({
     _id: z.string().min(1).isPrimaryKey().isSummaryField(),
@@ -124,6 +134,56 @@ export const OrganizationUnitSchema = z.object({
      */
     code: z.string().min(1).max(20).optional(),
     type: z.enum(OrganizationUnitType).optional().isDBIndexed().isSummaryField(),
+    /**
+     * Which external system ASSERTS this unit — present only on a unit a directory created.
+     *
+     * Set to {@link ExternalIdentitySource.SCIM} by `POST /scim/v2/Groups` and by nothing else. It is the
+     * ownership marker the SCIM Groups path keys on, and it has two jobs:
+     *
+     * 1. **`/Groups` reads and mutates ONLY units carrying it.** A hand-made unit answers 404 there.
+     *    Entra locates a group by `displayName` before creating it, so exposing every unit would let a
+     *    directory adopt a hand-authored "Sales" unit by name and start rewriting its membership —
+     *    name-matching into an authorization axis, which `scim-organization-unit-mapping.shared.ts`
+     *    refuses for the department path for the same reason.
+     * 2. **The department path never removes an assignment on such a unit** — see
+     *    `resolveScimOrganizationUnitReconciliation`. Without that, every `/Users` push in an
+     *    organization using the department mapping would delete the memberships `/Groups` made, and a
+     *    directory that only sends membership DELTAS would never restore them.
+     *
+     * Why this is NOT derived from {@link OrganizationUnitSchema.shape.externalId}: Okta creates a group
+     * with `schemas`, `displayName` and `members` only, so a unit can be directory-owned and carry no
+     * `externalId` at all. Ownership and the directory's own identifier are two facts.
+     *
+     * `.excludeFromCreate()` / `.excludeFromUpdate()`: never client-settable. An organization admin who
+     * could set it would hand a unit's membership to the directory; one who could clear it would strand
+     * a group the directory still believes it manages.
+     *
+     * `.isSummaryField()`: the admin screen lists units through their SUMMARY projection, and this is
+     * the one fact that explains why a rename there does not stick (#1392) — so it travels with the
+     * row, like `status`, rather than only on the full read.
+     */
+    externalSource: z.enum(ExternalIdentitySource).optional().isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),
+    /**
+     * The DIRECTORY's own identifier for the group this unit represents (SCIM `externalId`).
+     *
+     * Client-owned by the protocol: the provisioning client issues it and the service provider stores
+     * it, while the SCIM resource `id` is this unit's `_id`. `UserIdentityLink.providerUserId` is the
+     * same idea one resource over.
+     *
+     * Unique PER ORGANIZATION and sparse — most units have no directory group. Planned as the composite
+     * `[organizationId, externalId]` on both adapters; on PostgreSQL the index is PARTIAL
+     * (`where "externalId" is not null`), and that predicate, not `nulls not distinct`, is what lets any
+     * number of group-less units coexist (measured on PostgreSQL 17.11, 2026-09-20).
+     *
+     * ⚠️ NEVER write an explicit `null` here. The MongoDB index is a partial filter on
+     * `{ externalId: { $exists: true } }`, and `$exists: true` matches a stored `null` — so the SECOND
+     * unit in an organization to be "cleared" with `null` collides, while PostgreSQL accepts it. An
+     * absent value must be an absent key. The SCIM Groups controller therefore never clears it.
+     *
+     * `.excludeFromCreate()` / `.excludeFromUpdate()` for the same reason as `externalSource`: only the
+     * directory, through the trusted SCIM door, states it.
+     */
+    externalId: z.string().min(1).max(255).optional().isUnique({ scope: 'organization', sparse: true }).excludeFromCreate().excludeFromUpdate(),
     createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
     updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
 }).businessKeySet(['organizationId', 'parentUnitId', 'code'], {

package/dist/esm/organizations/organization-units.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"organization-units.shared.schemas.js","sourceRoot":"","sources":["../../../../src/organizations/organization-units.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Organization Unit Shared Schemas\n * \n * Hierarchical organizational structures for enterprise access control.\n * Supports nested organizational units with downward-only permission-inheritance rules.\n *\n * Units ARE an authorization axis (WS-C, shipped 2026-08-01): a member's per-unit role is emitted\n * into `initiatorRoles` as a narrowed grant, and for resources that opt into unit narrowing it admits\n * the member at the operation gate and confines their rows to the units that grant covers —\n * propagating to descendants where {@link OrganizationUnit_PermissionInheritanceType.INHERIT_DOWN}\n * says so. A unit is a NARROWING dimension inside `ResourcePrimaryScope.ORGANIZATIONS`, never a scope\n * of its own (decision D-C1), so tenant isolation is unchanged.\n *\n * Narrowing is strictly opt-in per resource and ADDITIVE: an organization-wide role that already\n * satisfies an operation is never confined. See\n * `.claude/plans/tenant-teardown-and-organization-units-domain.md` (WS-C).\n */\n\nimport { z } from 'zod';\n\nimport { ErrorCustomMessageReference } from '../errors/errors.custom-message-ref.shared.definitions';\n\n// ===============================\n// ORGANIZATION UNIT ENUMS\n// ===============================\n\n/**\n * Organization unit type enum\n */\nexport enum OrganizationUnitType {\n  COMPANY = 'company',\n  DIVISION = 'division',\n  DEPARTMENT = 'department',\n  TEAM = 'team',\n  SUBTEAM = 'subteam',\n  PROJECT_GROUP = 'project_group',\n  GEOGRAPHIC = 'geographic',\n  FUNCTIONAL = 'functional',\n  CUSTOM = 'custom'\n}\n\nexport enum OrganizationUnitStatus {\n  ACTIVE = 'active',\n  INACTIVE = 'inactive',\n  ARCHIVED = 'archived',\n  SUSPENDED = 'suspended'\n}\n\n/**\n * Direction in which a role held at one unit propagates across that unit's hierarchy edges.\n *\n * DOWNWARD ONLY, BY DESIGN. Only two directions exist, and that is a deliberate security\n * constraint rather than an unfinished vocabulary. A role granted at a unit may widen to that\n * unit's DESCENDANTS (the intuitive \"a division manager manages its teams\") or to nothing at all.\n *\n * `INHERIT_UP` and `BOTH_DIRECTIONS` were REMOVED (2026-07-31, decision D-C2). Upward propagation\n * means a role held at a leaf confers authority over its ANCESTORS — a team lead acquiring\n * division-wide authority by virtue of sitting inside it. That is privilege escalation along the\n * org chart, and it is the exact shape the role-ceiling gate\n * (`assertRequestedRolesWithinCallerCeiling`) exists to prevent on every other role-granting\n * surface; offering it as a one-field toggle here would have re-opened it structurally.\n *\n * If upward VISIBILITY is genuinely needed (\"a division head sees rolled-up team data\"), model it\n * as a reporting/aggregation concern — a read projection over the subtree — NOT as role\n * propagation. The two are different semantics and merging them costs the fail-closed guarantee.\n *\n * ENFORCED since 2026-08-01 (WS-C phase 3). The authorization gate expands a unit-scoped grant across\n * this edge before stamping it on the execution context, so the value governs how far the grant\n * actually reaches on every narrowed resource — read and write alike. The expansion is a PREFIX test\n * over the materialized `path`, never a recursive walk.\n *\n * ⚠️ Enforcement reads this field literally: an ABSENT value is treated as `NO_INHERITANCE`, which\n * deliberately differs from the write-time default below. A row reaching an authorization decision\n * without the field bypassed the schema that would have supplied that default, and a grant must never\n * widen on data the authorizer cannot vouch for.\n *\n * ⚠️ A grant at a ROOT unit with downward inheritance reaches the entire chart — functionally\n * organization-wide access assembled from one narrow grant. That is sound under the additive model but\n * must stay legible, which is why the access record reports directly-held and inherited units\n * separately (decision D-C4, watch item 4).\n *\n * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — least-privilege by construction: the\n * vocabulary cannot express an upward privilege grant.\n */\nexport enum OrganizationUnit_PermissionInheritanceType {\n  /** A role held at this unit also applies to its descendant units. */\n  INHERIT_DOWN = 'inherit_down',\n  /** A role held at this unit applies to this unit only; the node is isolated for permission purposes. */\n  NO_INHERITANCE = 'no_inheritance',\n}\n\n\n/**\n * A node of an organization's tree.\n *\n * **Business key — `code` is unique among siblings.** Declared here rather than only in the\n * application guard because the guard is a read-then-write: two concurrent CREATEs of the same code\n * under the same parent can each find nothing and each succeed. The compound index closes that\n * window at the database.\n *\n * ⚠️ The index is a **MongoDB-only** guarantee today. The SQL planner records uniqueness as intent\n * and leaves enforcement migration-owned, so the application guard in the unit custom\n * implementation is KEPT as the cross-adapter backstop rather than deleted as redundant. The two\n * raise the same {@link ErrorCustomMessageReference.ORGANIZATION_UNIT_CODE_EXISTS} so a client sees\n * one code for one condition, whichever layer catches it.\n */\nexport const OrganizationUnitSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n  /**\n   * The parent node of this unit; absent on a root that hangs directly under the organization.\n   *\n   * `.excludeFromUpdate()` (plan decision D-B2): re-parenting is owned exclusively by the MOVE\n   * operation. A reparent has a subtree-wide side effect — every descendant's materialized\n   * {@link OrganizationUnitSchema.shape.path} has to be rewritten — and it must be refused when the\n   * destination sits inside the moved node's own subtree. Generic UPDATE performs neither, so\n   * allowing it here would silently produce a tree whose paths describe a shape that no longer\n   * exists, or a detached cycle. One operation, one authority.\n   */\n  parentUnitId: z.string().optional().isDBIndexed().isForeignKey().excludeFromUpdate(),\n  status: z.enum(OrganizationUnitStatus).default(OrganizationUnitStatus.ACTIVE).isDBIndexed().isSummaryField(),\n  inheritanceType: z.enum(OrganizationUnit_PermissionInheritanceType).default(OrganizationUnit_PermissionInheritanceType.INHERIT_DOWN).isDBIndexed(),\n  \n  path: z.string().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n  \n  // Unit Identity\n  name: z.string().min(1).max(100).isDBIndexed().isSummaryField(),\n  /**\n   * Short human-assigned handle for the unit, unique among its siblings — see the\n   * {@link OrganizationUnitSchema} business key below for the exact scope and why it is optional.\n   */\n  code: z.string().min(1).max(20).optional(),\n  type: z.enum(OrganizationUnitType).optional().isDBIndexed().isSummaryField(),\n\n  createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n}).businessKeySet(\n  ['organizationId', 'parentUnitId', 'code'],\n  {\n    // A row with no `code` has no key at all, so it must sit OUTSIDE the constraint: any number of\n    // code-less siblings under one parent is legitimate. `parentUnitId` is deliberately NOT listed\n    // — an absent parent means \"root\", which is a real position in the tree, so roots must still\n    // collide with each other. Listing it would exclude every root from the index and quietly lose\n    // uniqueness for exactly the nodes an org chart starts with.\n    skipRowsMissing: ['code'],\n    conflictMessageReference: ErrorCustomMessageReference.ORGANIZATION_UNIT_CODE_EXISTS,\n  },\n);\nexport type OrganizationUnit = z.infer<typeof OrganizationUnitSchema>;\n\n// RECURSIVE type - keep explicit interface\nexport interface OrganizationUnitTreeNode {\n  unit: OrganizationUnit;\n  children: OrganizationUnitTreeNode[];\n}\n\nexport const OrganizationUnitTreeNodeSchema: z.ZodType<OrganizationUnitTreeNode> = z.object({\n  unit: OrganizationUnitSchema,\n  children: z.array(z.lazy(() => OrganizationUnitTreeNodeSchema)).default([]),\n});\n\n"]}
+{"version":3,"file":"organization-units.shared.schemas.js","sourceRoot":"","sources":["../../../../src/organizations/organization-units.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Organization Unit Shared Schemas\n * \n * Hierarchical organizational structures for enterprise access control.\n * Supports nested organizational units with downward-only permission-inheritance rules.\n *\n * Units ARE an authorization axis (WS-C, shipped 2026-08-01): a member's per-unit role is emitted\n * into `initiatorRoles` as a narrowed grant, and for resources that opt into unit narrowing it admits\n * the member at the operation gate and confines their rows to the units that grant covers —\n * propagating to descendants where {@link OrganizationUnit_PermissionInheritanceType.INHERIT_DOWN}\n * says so. A unit is a NARROWING dimension inside `ResourcePrimaryScope.ORGANIZATIONS`, never a scope\n * of its own (decision D-C1), so tenant isolation is unchanged.\n *\n * Narrowing is strictly opt-in per resource and ADDITIVE: an organization-wide role that already\n * satisfies an operation is never confined. See\n * `.claude/plans/tenant-teardown-and-organization-units-domain.md` (WS-C).\n */\n\nimport { z } from 'zod';\n\nimport { ErrorCustomMessageReference } from '../errors/errors.custom-message-ref.shared.definitions';\nimport { ExternalIdentitySource } from '../security/authentications/authentication.shared.schemas';\n\n// ===============================\n// ORGANIZATION UNIT ENUMS\n// ===============================\n\n/**\n * Organization unit type enum\n */\nexport enum OrganizationUnitType {\n  COMPANY = 'company',\n  DIVISION = 'division',\n  DEPARTMENT = 'department',\n  TEAM = 'team',\n  SUBTEAM = 'subteam',\n  PROJECT_GROUP = 'project_group',\n  GEOGRAPHIC = 'geographic',\n  FUNCTIONAL = 'functional',\n  CUSTOM = 'custom'\n}\n\nexport enum OrganizationUnitStatus {\n  ACTIVE = 'active',\n  INACTIVE = 'inactive',\n  ARCHIVED = 'archived',\n  SUSPENDED = 'suspended'\n}\n\n/**\n * Direction in which a role held at one unit propagates across that unit's hierarchy edges.\n *\n * DOWNWARD ONLY, BY DESIGN. Only two directions exist, and that is a deliberate security\n * constraint rather than an unfinished vocabulary. A role granted at a unit may widen to that\n * unit's DESCENDANTS (the intuitive \"a division manager manages its teams\") or to nothing at all.\n *\n * `INHERIT_UP` and `BOTH_DIRECTIONS` were REMOVED (2026-07-31, decision D-C2). Upward propagation\n * means a role held at a leaf confers authority over its ANCESTORS — a team lead acquiring\n * division-wide authority by virtue of sitting inside it. That is privilege escalation along the\n * org chart, and it is the exact shape the role-ceiling gate\n * (`assertRequestedRolesWithinCallerCeiling`) exists to prevent on every other role-granting\n * surface; offering it as a one-field toggle here would have re-opened it structurally.\n *\n * If upward VISIBILITY is genuinely needed (\"a division head sees rolled-up team data\"), model it\n * as a reporting/aggregation concern — a read projection over the subtree — NOT as role\n * propagation. The two are different semantics and merging them costs the fail-closed guarantee.\n *\n * ENFORCED since 2026-08-01 (WS-C phase 3). The authorization gate expands a unit-scoped grant across\n * this edge before stamping it on the execution context, so the value governs how far the grant\n * actually reaches on every narrowed resource — read and write alike. The expansion is a PREFIX test\n * over the materialized `path`, never a recursive walk.\n *\n * ⚠️ Enforcement reads this field literally: an ABSENT value is treated as `NO_INHERITANCE`, which\n * deliberately differs from the write-time default below. A row reaching an authorization decision\n * without the field bypassed the schema that would have supplied that default, and a grant must never\n * widen on data the authorizer cannot vouch for.\n *\n * ⚠️ A grant at a ROOT unit with downward inheritance reaches the entire chart — functionally\n * organization-wide access assembled from one narrow grant. That is sound under the additive model but\n * must stay legible, which is why the access record reports directly-held and inherited units\n * separately (decision D-C4, watch item 4).\n *\n * assurance-control: WILDO.ACCESS.LEAST_PRIVILEGE — least-privilege by construction: the\n * vocabulary cannot express an upward privilege grant.\n */\nexport enum OrganizationUnit_PermissionInheritanceType {\n  /** A role held at this unit also applies to its descendant units. */\n  INHERIT_DOWN = 'inherit_down',\n  /** A role held at this unit applies to this unit only; the node is isolated for permission purposes. */\n  NO_INHERITANCE = 'no_inheritance',\n}\n\n\n/**\n * A node of an organization's tree.\n *\n * **Business key — `code` is unique among siblings.** Declared here rather than only in the\n * application guard because the guard is a read-then-write: two concurrent CREATEs of the same code\n * under the same parent can each find nothing and each succeed. The compound index closes that\n * window at the database.\n *\n * BOTH adapters enforce it. This said the index was a \"MongoDB-only guarantee today\" because the SQL\n * planner only records uniqueness as intent — true of the PLANNER, and stale about the system:\n * enforcement is migration-owned and the migrations exist, so a PostgreSQL-backed application really\n * does carry\n * `create unique index … (\"organizationId\", \"parentUnitId\", \"code\") nulls not distinct where \"code\"\n * is not null` (read from `wonder-crm`'s initial schema, 2026-09-20). Corrected rather than deleted\n * because the reasoning is what a reader needs: the plan is INTENT, the migration is ENFORCEMENT, and\n * a resource change is not finished until every PostgreSQL-backed surface has one\n * (`.claude/rules/engine-resource-changes-owe-migrations.md`).\n *\n * The application guard in the unit custom implementation is KEPT anyway — not as a cross-adapter\n * backstop now, but because it raises the same\n * {@link ErrorCustomMessageReference.ORGANIZATION_UNIT_CODE_EXISTS} the index maps to, so a client\n * sees one code for one condition whichever layer catches it first.\n */\nexport const OrganizationUnitSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n  /**\n   * The parent node of this unit; absent on a root that hangs directly under the organization.\n   *\n   * `.excludeFromUpdate()` (plan decision D-B2): re-parenting is owned exclusively by the MOVE\n   * operation. A reparent has a subtree-wide side effect — every descendant's materialized\n   * {@link OrganizationUnitSchema.shape.path} has to be rewritten — and it must be refused when the\n   * destination sits inside the moved node's own subtree. Generic UPDATE performs neither, so\n   * allowing it here would silently produce a tree whose paths describe a shape that no longer\n   * exists, or a detached cycle. One operation, one authority.\n   */\n  parentUnitId: z.string().optional().isDBIndexed().isForeignKey().excludeFromUpdate(),\n  status: z.enum(OrganizationUnitStatus).default(OrganizationUnitStatus.ACTIVE).isDBIndexed().isSummaryField(),\n  inheritanceType: z.enum(OrganizationUnit_PermissionInheritanceType).default(OrganizationUnit_PermissionInheritanceType.INHERIT_DOWN).isDBIndexed(),\n  \n  path: z.string().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n  \n  // Unit Identity\n  name: z.string().min(1).max(100).isDBIndexed().isSummaryField(),\n  /**\n   * Short human-assigned handle for the unit, unique among its siblings — see the\n   * {@link OrganizationUnitSchema} business key below for the exact scope and why it is optional.\n   */\n  code: z.string().min(1).max(20).optional(),\n  type: z.enum(OrganizationUnitType).optional().isDBIndexed().isSummaryField(),\n\n  /**\n   * Which external system ASSERTS this unit — present only on a unit a directory created.\n   *\n   * Set to {@link ExternalIdentitySource.SCIM} by `POST /scim/v2/Groups` and by nothing else. It is the\n   * ownership marker the SCIM Groups path keys on, and it has two jobs:\n   *\n   * 1. **`/Groups` reads and mutates ONLY units carrying it.** A hand-made unit answers 404 there.\n   *    Entra locates a group by `displayName` before creating it, so exposing every unit would let a\n   *    directory adopt a hand-authored \"Sales\" unit by name and start rewriting its membership —\n   *    name-matching into an authorization axis, which `scim-organization-unit-mapping.shared.ts`\n   *    refuses for the department path for the same reason.\n   * 2. **The department path never removes an assignment on such a unit** — see\n   *    `resolveScimOrganizationUnitReconciliation`. Without that, every `/Users` push in an\n   *    organization using the department mapping would delete the memberships `/Groups` made, and a\n   *    directory that only sends membership DELTAS would never restore them.\n   *\n   * Why this is NOT derived from {@link OrganizationUnitSchema.shape.externalId}: Okta creates a group\n   * with `schemas`, `displayName` and `members` only, so a unit can be directory-owned and carry no\n   * `externalId` at all. Ownership and the directory's own identifier are two facts.\n   *\n   * `.excludeFromCreate()` / `.excludeFromUpdate()`: never client-settable. An organization admin who\n   * could set it would hand a unit's membership to the directory; one who could clear it would strand\n   * a group the directory still believes it manages.\n   *\n   * `.isSummaryField()`: the admin screen lists units through their SUMMARY projection, and this is\n   * the one fact that explains why a rename there does not stick (#1392) — so it travels with the\n   * row, like `status`, rather than only on the full read.\n   */\n  externalSource: z.enum(ExternalIdentitySource).optional().isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),\n  /**\n   * The DIRECTORY's own identifier for the group this unit represents (SCIM `externalId`).\n   *\n   * Client-owned by the protocol: the provisioning client issues it and the service provider stores\n   * it, while the SCIM resource `id` is this unit's `_id`. `UserIdentityLink.providerUserId` is the\n   * same idea one resource over.\n   *\n   * Unique PER ORGANIZATION and sparse — most units have no directory group. Planned as the composite\n   * `[organizationId, externalId]` on both adapters; on PostgreSQL the index is PARTIAL\n   * (`where \"externalId\" is not null`), and that predicate, not `nulls not distinct`, is what lets any\n   * number of group-less units coexist (measured on PostgreSQL 17.11, 2026-09-20).\n   *\n   * ⚠️ NEVER write an explicit `null` here. The MongoDB index is a partial filter on\n   * `{ externalId: { $exists: true } }`, and `$exists: true` matches a stored `null` — so the SECOND\n   * unit in an organization to be \"cleared\" with `null` collides, while PostgreSQL accepts it. An\n   * absent value must be an absent key. The SCIM Groups controller therefore never clears it.\n   *\n   * `.excludeFromCreate()` / `.excludeFromUpdate()` for the same reason as `externalSource`: only the\n   * directory, through the trusted SCIM door, states it.\n   */\n  externalId: z.string().min(1).max(255).optional().isUnique({ scope: 'organization', sparse: true }).excludeFromCreate().excludeFromUpdate(),\n\n  createdAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n}).businessKeySet(\n  ['organizationId', 'parentUnitId', 'code'],\n  {\n    // A row with no `code` has no key at all, so it must sit OUTSIDE the constraint: any number of\n    // code-less siblings under one parent is legitimate. `parentUnitId` is deliberately NOT listed\n    // — an absent parent means \"root\", which is a real position in the tree, so roots must still\n    // collide with each other. Listing it would exclude every root from the index and quietly lose\n    // uniqueness for exactly the nodes an org chart starts with.\n    skipRowsMissing: ['code'],\n    conflictMessageReference: ErrorCustomMessageReference.ORGANIZATION_UNIT_CODE_EXISTS,\n  },\n);\nexport type OrganizationUnit = z.infer<typeof OrganizationUnitSchema>;\n\n// RECURSIVE type - keep explicit interface\nexport interface OrganizationUnitTreeNode {\n  unit: OrganizationUnit;\n  children: OrganizationUnitTreeNode[];\n}\n\nexport const OrganizationUnitTreeNodeSchema: z.ZodType<OrganizationUnitTreeNode> = z.object({\n  unit: OrganizationUnitSchema,\n  children: z.array(z.lazy(() => OrganizationUnitTreeNodeSchema)).default([]),\n});\n\n"]}

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

@@ -9,23 +9,67 @@ import { OrganizationStatus } from './organizations.shared.schemas';
 import { CoreResourceOperation } from '../resources/resources.shared.core.definitions';
 import { ResourceRelationship } from '../resources/resources.shared.schemas';
 /**
- * Tenant LIFECYCLE transitions — the operations that own `Organization.status`.
+ * Tenant LIFECYCLE transitions — the guarded transitions of a tenant's state and identity.
  *
  * Renamed from `Organization_AppAdmin_Operations` on 2026-08-01. The old name described the
  * AUDIENCE of the two members it happened to hold (`ACTIVATE`/`SUSPEND` are super-admin-only) and
  * stopped being true the moment an ORG_ADMIN-facing member joined it. The members share a
  * *concern*, not an audience: each is a guarded transition of the tenant state machine, declared
- * `resourceOperationLike: UPDATE`, gated by an `enabledCondition` on the current status, and the
- * sole authority for the `status` field that generic UPDATE may not write. The frontend already
+ * `resourceOperationLike: UPDATE`, gated by an `enabledCondition` on the tenant's current state, and
+ * the sole authority for a field that generic UPDATE may not write. The frontend already
  * called this concept by its right name — `organizationLifecycleOpViews` in the presets.
  *
- * `status` is `.excludeFromUpdate()`, so every transition here declares `authoritativeFields`
- * naming the fields its prefix owns; without that the repository's strict re-parse silently strips
- * the write and the operation answers success having changed nothing.
+ * Every member's field is `.excludeFromUpdate()`, so each declares `authoritativeFields` naming the
+ * fields its prefix owns; without that the repository's strict re-parse silently strips the write and
+ * the operation answers success having changed nothing.
+ *
+ * ## Which field each member owns
+ *
+ * Four members own `status`. {@link PROMOTE_TO_OWNER_ORGANIZATION} owns `type`, and it is why this
+ * doc no longer says "the operations that own `Organization.status`" (it did until #1054, when the
+ * first non-`status` member arrived). The generalisation is not a convenience: the paragraph above
+ * already described the shared concern without naming `status` once, and every clause of it holds of
+ * a type transition — guarded, `UPDATE`-like, conditioned on the tenant's current state, and the sole
+ * authority for an `.excludeFromUpdate()` field.
+ *
+ * A second enum was the alternative and is not available: `customOperation` on a resource
+ * configuration takes ONE `EnumLikeType`, so two enums would mean two resources.
  */
 export declare enum Organization_Lifecycle_Operations {
     ACTIVATE = "activate",
     SUSPEND = "suspend",
+    /**
+     * Re-type an existing organization as the one that OWNS the application — the paired mutation path
+     * for the otherwise-immutable `Organization.type` (#1054).
+     *
+     * ## Why it has to exist at all
+     *
+     * `type` is creation-time identity, so an application that adds `ownsApplication` to its declaration
+     * AFTER it has been running has no way to say which of its existing organizations is the owner: the
+     * bootstrap that would have typed one has already run, and nothing else may write `type`. Without
+     * this door the marker would only ever work on applications created after it — the immutability
+     * construct shipped with no way past it that `.claude/rules/design-philosophy.md` names.
+     *
+     * ## Why it is NOT cross-tenant
+     *
+     * The promoter must be a MEMBER of the target organization holding `APP_ADMIN_SUPER_ADMIN`, which
+     * the bootstrap administrator is. The crossing rule on this resource is "cross the boundary for
+     * actions a later action can undo", and promotion has no inverse: there is no demotion door, and
+     * building one would mean an application could be left with no owner organization at all. A crossed
+     * version would need that inverse, or a two-person rule, and neither is built.
+     *
+     * ## What it refuses, and why each refusal rather than a reconciliation
+     *
+     * The target type's `userTypes` must COVER the source type's, every existing membership role must be
+     * in the target type's `availableOrgRoles`, and a SCIM binding may not be lost. Those are the
+     * dependent policy surfaces a type carries — `userTypes` are granted on join and revoked on leave,
+     * and suspend/activate/restore re-derive them across three resources — so a promotion that changed
+     * any of them would owe a revoke-and-regrant reconciliation across every member, in one transaction,
+     * on a door used once in an application's life. Refusing instead keeps the operation honest about
+     * what it does: it changes the tenant's IDENTITY and touches nobody's authority. The refusal names
+     * the first mismatch, so the remedy is to widen the target type rather than to guess.
+     */
+    PROMOTE_TO_OWNER_ORGANIZATION = "promoteToOwnerOrganization",
     /**
      * Mark the tenant for deletion — the SOFT-DELETE half of tenant teardown.
      *
@@ -48,7 +92,7 @@ type OrganizationCoreOperations = CoreResourceOperation.READ | CoreResourceOpera
 export declare const organizationResourceConfiguration_InitializationFactory: (resourcesRelationships: ResourceRelationship[]) => import("..").ResourceConfiguration<typeof Organization_Lifecycle_Operations, OrganizationCoreOperations, z.ZodObject<{
     _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     name: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
-    type: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;
+    type: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     slug: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
     status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof OrganizationStatus>>>>>;
     platformAccessApprovalRequired: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>;

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

@@ -1 +1 @@
-{"version":3,"file":"organizations.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/organizations/organizations.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,kBAAkB,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAAoD,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAW/H;;;;;;;;;;;;;;GAcG;AACH,oBAAY,iCAAiC;IAC3C,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB;;;;;;;OAOG;IACH,gBAAgB,qBAAqB;IACrC;;;;;;OAMG;IACH,OAAO,YAAY;CACpB;AAQD,KAAK,0BAA0B,GAC3B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAKjC,eAAO,MAAM,uDAAuD,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;kBA+pBpH,CAAC"}
+{"version":3,"file":"organizations.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/organizations/organizations.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,kBAAkB,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAAoD,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAW/H;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,oBAAY,iCAAiC;IAC3C,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,6BAA6B,+BAA+B;IAC5D;;;;;;;OAOG;IACH,gBAAgB,qBAAqB;IACrC;;;;;;OAMG;IACH,OAAO,YAAY;CACpB;AAQD,KAAK,0BAA0B,GAC3B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAKjC,eAAO,MAAM,uDAAuD,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;kBAqwBpH,CAAC"}

package/dist/esm/organizations/organizations.shared.resources-config.schemas.js

@@ -15,24 +15,68 @@ import { createResourceConfiguration_Initialization } from '../resources/resourc
 import { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas.js';
 import { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas.js';
 /**
- * Tenant LIFECYCLE transitions — the operations that own `Organization.status`.
+ * Tenant LIFECYCLE transitions — the guarded transitions of a tenant's state and identity.
  *
  * Renamed from `Organization_AppAdmin_Operations` on 2026-08-01. The old name described the
  * AUDIENCE of the two members it happened to hold (`ACTIVATE`/`SUSPEND` are super-admin-only) and
  * stopped being true the moment an ORG_ADMIN-facing member joined it. The members share a
  * *concern*, not an audience: each is a guarded transition of the tenant state machine, declared
- * `resourceOperationLike: UPDATE`, gated by an `enabledCondition` on the current status, and the
- * sole authority for the `status` field that generic UPDATE may not write. The frontend already
+ * `resourceOperationLike: UPDATE`, gated by an `enabledCondition` on the tenant's current state, and
+ * the sole authority for a field that generic UPDATE may not write. The frontend already
  * called this concept by its right name — `organizationLifecycleOpViews` in the presets.
  *
- * `status` is `.excludeFromUpdate()`, so every transition here declares `authoritativeFields`
- * naming the fields its prefix owns; without that the repository's strict re-parse silently strips
- * the write and the operation answers success having changed nothing.
+ * Every member's field is `.excludeFromUpdate()`, so each declares `authoritativeFields` naming the
+ * fields its prefix owns; without that the repository's strict re-parse silently strips the write and
+ * the operation answers success having changed nothing.
+ *
+ * ## Which field each member owns
+ *
+ * Four members own `status`. {@link PROMOTE_TO_OWNER_ORGANIZATION} owns `type`, and it is why this
+ * doc no longer says "the operations that own `Organization.status`" (it did until #1054, when the
+ * first non-`status` member arrived). The generalisation is not a convenience: the paragraph above
+ * already described the shared concern without naming `status` once, and every clause of it holds of
+ * a type transition — guarded, `UPDATE`-like, conditioned on the tenant's current state, and the sole
+ * authority for an `.excludeFromUpdate()` field.
+ *
+ * A second enum was the alternative and is not available: `customOperation` on a resource
+ * configuration takes ONE `EnumLikeType`, so two enums would mean two resources.
  */
 export var Organization_Lifecycle_Operations;
 (function (Organization_Lifecycle_Operations) {
     Organization_Lifecycle_Operations["ACTIVATE"] = "activate";
     Organization_Lifecycle_Operations["SUSPEND"] = "suspend";
+    /**
+     * Re-type an existing organization as the one that OWNS the application — the paired mutation path
+     * for the otherwise-immutable `Organization.type` (#1054).
+     *
+     * ## Why it has to exist at all
+     *
+     * `type` is creation-time identity, so an application that adds `ownsApplication` to its declaration
+     * AFTER it has been running has no way to say which of its existing organizations is the owner: the
+     * bootstrap that would have typed one has already run, and nothing else may write `type`. Without
+     * this door the marker would only ever work on applications created after it — the immutability
+     * construct shipped with no way past it that `.claude/rules/design-philosophy.md` names.
+     *
+     * ## Why it is NOT cross-tenant
+     *
+     * The promoter must be a MEMBER of the target organization holding `APP_ADMIN_SUPER_ADMIN`, which
+     * the bootstrap administrator is. The crossing rule on this resource is "cross the boundary for
+     * actions a later action can undo", and promotion has no inverse: there is no demotion door, and
+     * building one would mean an application could be left with no owner organization at all. A crossed
+     * version would need that inverse, or a two-person rule, and neither is built.
+     *
+     * ## What it refuses, and why each refusal rather than a reconciliation
+     *
+     * The target type's `userTypes` must COVER the source type's, every existing membership role must be
+     * in the target type's `availableOrgRoles`, and a SCIM binding may not be lost. Those are the
+     * dependent policy surfaces a type carries — `userTypes` are granted on join and revoked on leave,
+     * and suspend/activate/restore re-derive them across three resources — so a promotion that changed
+     * any of them would owe a revoke-and-regrant reconciliation across every member, in one transaction,
+     * on a door used once in an application's life. Refusing instead keeps the operation honest about
+     * what it does: it changes the tenant's IDENTITY and touches nobody's authority. The refusal names
+     * the first mismatch, so the remedy is to widen the target type rather than to guess.
+     */
+    Organization_Lifecycle_Operations["PROMOTE_TO_OWNER_ORGANIZATION"] = "promoteToOwnerOrganization";
     /**
      * Mark the tenant for deletion — the SOFT-DELETE half of tenant teardown.
      *
@@ -106,6 +150,7 @@ export const organizationResourceConfiguration_InitializationFactory = (resource
      * | `activate` | ✅ | `SUSPENDED` confers no authority and is the only state ACTIVATE runs from. Recuperative. |
      * | `requestDeletion: admin` | ✅ | The operator takedown path — but the REVERSIBLE one: mark + notify + window, undone by `restore`. |
      * | `delete: admin` | ❌ | Irreversible, whole-tenant, cascading, skips the window. See its own block for the full decision. |
+     * | `promoteToOwnerOrganization` | ❌ | Irreversible by construction — there is no demotion door, and building one would let an application be left with no owner organization. The promoter is a super-administrator who is a MEMBER of the target, which the bootstrap administrator is. |
      * | everything else | ❌ | No demonstrated operator need. Absence of a use case is a reason to stay shut. |
      *
      * The organising principle: **cross the boundary for actions a later action can undo.** Every
@@ -702,7 +747,106 @@ export const organizationResourceConfiguration_InitializationFactory = (resource
                     channel: CoreUserNotificationChannel.EMAIL,
                 }
             ]
-        }
+        },
+        /**
+         * Promote this organization to the one that OWNS the application (#1054).
+         *
+         * The paired mutation path for `Organization.type`, which is creation-time identity. The field's
+         * own JSDoc has reserved exactly this since it was written: *"a future type transition must be a
+         * dedicated migration operation that reconciles every dependent member and policy surface"*. This
+         * is that operation, narrowed to the one transition the framework needs and refusing rather than
+         * reconciling — see the enum member's JSDoc for why refusing is the honest shape here.
+         *
+         * ## ⚠️ NOT cross-tenant, and this is the one place on this resource where that is a DESIGN
+         * decision rather than an omission
+         *
+         * The banner at the top of this configuration records the rule: **cross the boundary for actions a
+         * later action can undo.** `restore`, `activate` and `requestDeletion: admin` are crossed because
+         * each is reversible. Promotion is not: there is no demotion operation, deliberately, because an
+         * application whose owner organization can be un-typed is one that can be left with no owner at
+         * all — and `type` being immutable means nothing could then repair it.
+         *
+         * So the promoter is a super-administrator who is a MEMBER of the target organization. On the
+         * application this exists for, that is exactly who is available: the bootstrap administrator is a
+         * member of the organization the platform seeded for them, and that organization is the one being
+         * promoted. Opening the crossing would need a `demote` door or a two-person rule first.
+         *
+         * ## Why a `justification` is required
+         *
+         * It is the whole control on an irreversible act, in the same shape as
+         * `organizationMembers.grantOwnership`. It is RECORDED — on the `ORGANIZATION_TYPE_ASSIGNED` event
+         * this operation emits, beside the type it replaced — because a required request field that
+         * nothing stores is a promise nobody keeps (#593, where `grantOwnership`'s justification was
+         * validated and then dropped for months).
+         *
+         * ## Why no `enabledCondition` on "no owner exists yet"
+         *
+         * `enabledCondition` receives the CURRENT OBJECT — this organization — and the question "does the
+         * application already have an owner organization?" is about a different row. The refusal therefore
+         * lives in the custom implementation, which answers `409 APPLICATION_OWNER_ORGANIZATION_EXISTS`.
+         * The condition here covers what the current object CAN answer: only an ACTIVE tenant may be
+         * promoted, because a suspended or marked one confers no authority and promoting it would make the
+         * organization that operates the application one nobody can act through.
+         *
+         * assurance-control: WILDO.ACCESS.ADMINISTRATIVE_CONTINUITY — names the organization that operates
+         * the application, under justification and audit, on a door that cannot be reached from outside
+         * the tenant.
+         * assurance-control: WILDO.AUDIT.SECURITY_EVENT — an authentication-relevant tenant attribute
+         * changes, and the record names who changed it and why.
+         */
+        [Organization_Lifecycle_Operations.PROMOTE_TO_OWNER_ORGANIZATION]: {
+            variants: [
+                {
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    // Platform tier, and UNCROSSED — no `admitsCrossTenantPlatformAdministration`. The caller
+                    // must hold this key AND be a member of the target organization, which is what the two
+                    // tenant gates (`validateParentScopeAccess`, `authorizeOrganizations`) enforce on this
+                    // resource independently of the role table. See the JSDoc above for why the crossing stays
+                    // shut.
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    riskLevel: ResourceOperationRiskLevel.CRITICAL,
+                    resourceOperationLike: CoreResourceOperation.UPDATE,
+                    requestDto: z.object({
+                        justification: z.string().min(1).max(1000),
+                    }),
+                    // Irreversible and it re-points everything the application owns as an operator. A hijacked
+                    // session must not reach it on the strength of a login that happened at some earlier point.
+                    //
+                    // assurance-control: WILDO.IDENTITY.STEP_UP_AUTHENTICATION — re-authentication before a
+                    // high-impact action.
+                    requiresStepUpAuthentication: true,
+                    // Only an ACTIVE tenant. Every other status either confers no authority
+                    // (`ORGANIZATION_STATUSES_WITHOUT_AUTHORITY`) or is terminal, and an owner organization
+                    // nobody can act through is not an owner. Enforced on the frontend (the action renders
+                    // disabled) AND the backend (`services-registry-handler` throws
+                    // `SERVICE_RESOURCE_OPERATION_DISABLED` → 403). Keep in sync with the resource spec's
+                    // PROMOTE_TO_OWNER_ORGANIZATION error scenarios.
+                    enabledCondition: ({ currentObject }) => currentObject.status === OrganizationStatus.ACTIVE,
+                    // NO `haveBulkOperation` — same reasoning as every other member here, and stronger: at most
+                    // one organization may ever be promoted, so a multi-row selector is meaningless.
+                }
+            ],
+            /*
+             * NO `userNotifications`, and the reason is the UNCROSSED design rather than an omission.
+             *
+             * A first draft declared an email to `ORGANIZATION_ADMINISTRATIVE`, reasoning that the tenant
+             * should learn it now operates the application. Running it proved that wrong twice over.
+             *
+             * Mechanically: the declaration named a template nobody had authored, and the engine's lifecycle
+             * check said so at every boot — *"the operation still succeeds, but its notification is silently
+             * never delivered"*. A declared notification with no template is worse than none; it is a promise
+             * the running system reports as unkept.
+             *
+             * And on the merits, the audience is wrong. `organizationMembers.grantOwnership` notifies because
+             * it CROSSES: an operator outside the tenant changes who owns it, and the difference between a
+             * legitimate repair and a quiet self-grant is only visible to the tenant if it is told. Promotion
+             * is deliberately uncrossed — the caller is a super-administrator who is a MEMBER of the very
+             * organization being promoted — so there is no outsider to disclose and nobody the email would
+             * inform who was not already the actor. The audit row, which names the actor and their
+             * justification, is the record this act owes.
+             */
+        },
     },
 });
 //# sourceMappingURL=organizations.shared.resources-config.schemas.js.map