@company-semantics/contracts 86.1.0 → 88.0.0

package/src/org/org-governance-schemas.ts

@@ -0,0 +1,198 @@
+/**
+ * Org Governance Response Schemas
+ *
+ * Org domains, deletion eligibility, ownership transfer, system events and the
+ * org AI-usage report.
+ *
+ * Split out of `./schemas.ts`, which re-exports this module unchanged — import
+ * from `./schemas` (or the `./org` entry), not from this file directly.
+ */
+import { z } from "zod";
+import { IsoDateTime } from "../api/primitives";
+import { MoneyMicrosSchema } from "../billing/vocabulary";
+import { AI_FEATURES } from "../usage/features";
+
+// ---------------------------------------------------------------------------
+// OrgDomain sub-schema
+// ---------------------------------------------------------------------------
+
+const OrgDomainSchema = z.object({
+  id: z.string(),
+  orgId: z.string(),
+  domain: z.string(),
+  status: z.enum(["pending", "verified"]),
+  verificationMethod: z.enum(["dns_txt", "email", "idp"]),
+  verificationToken: z.string().optional(),
+  verifiedAt: z.string().nullable(),
+  createdAt: z.string(),
+  verifiedBy: z
+    .object({ id: z.string(), name: z.string(), email: z.string() })
+    .optional(),
+});
+
+// ---------------------------------------------------------------------------
+// GET /api/workspace/domains/:id/verify (single domain)
+// POST /api/workspace/domains/:id/verify (returns verified OrgDomain)
+// ---------------------------------------------------------------------------
+
+export const DomainResponseSchema = OrgDomainSchema;
+
+export type DomainResponse = z.infer<typeof DomainResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /api/workspace/domains
+// ---------------------------------------------------------------------------
+
+export const DomainListResponseSchema = z.array(OrgDomainSchema);
+
+export type DomainListResponse = z.infer<typeof DomainListResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /api/org/deletion-eligibility
+// ---------------------------------------------------------------------------
+
+const MemberClassificationSchema = z.object({
+  userId: z.string(),
+  email: z.string(),
+  suggestedFate: z.enum(["REMOVE_FROM_ORG", "DELETE_ACCOUNT", "BLOCKED"]),
+  reason: z.string(),
+});
+
+export const OrgDeletionStatusSchema = z.object({
+  orgId: z.string(),
+  eligible: z.boolean(),
+  isPersonalOrg: z.boolean(),
+  ownerStatus: z.string().optional(),
+  deletionRequestedAt: z.string().optional(),
+  classifications: z.array(MemberClassificationSchema),
+});
+
+export type OrgDeletionStatus = z.infer<typeof OrgDeletionStatusSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /api/org/transfer-ownership (initiate)
+// ---------------------------------------------------------------------------
+
+export const OwnershipTransferResponseSchema = z.object({
+  transferId: z.string(),
+  expiresAt: z.string(),
+  message: z.string(),
+});
+
+export type OwnershipTransferResponse = z.infer<
+  typeof OwnershipTransferResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// POST /api/org/transfer-ownership/preview
+// ---------------------------------------------------------------------------
+
+export const OwnershipTransferPreviewSchema = z.object({
+  workspaceName: z.string(),
+  initiatorName: z.string(),
+  initiatorEmail: z.string(),
+  note: z.string().optional(),
+  expiresAt: z.string(),
+  token: z.string(),
+});
+
+export type OwnershipTransferPreview = z.infer<
+  typeof OwnershipTransferPreviewSchema
+>;
+
+// ---------------------------------------------------------------------------
+// GET /api/org/system-events
+// ---------------------------------------------------------------------------
+
+const OrgSystemEventSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  payload: z.unknown(),
+  createdAt: z.string(),
+});
+
+export const OrgSystemEventsListSchema = z.object({
+  events: z.array(OrgSystemEventSchema),
+});
+
+export type OrgSystemEventsList = z.infer<typeof OrgSystemEventsListSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /api/org/system-events/:id/acknowledge
+// ---------------------------------------------------------------------------
+
+export const AcknowledgeSystemEventResponseSchema = z.object({
+  success: z.literal(true),
+});
+
+export type AcknowledgeSystemEventResponse = z.infer<
+  typeof AcknowledgeSystemEventResponseSchema
+>;
+
+// ---------------------------------------------------------------------------
+// GET /api/orgs/:orgId/ai-usage
+//
+// INV-USAGE-LEDGER: every request, token and dollar here is read from the
+// settled billing ledger (`billing_usage_events`) — one row per billed provider
+// call, whatever feature made it. A `request` is one settled billable provider
+// invocation (retries and fallbacks are separate requests), every amount is
+// the customer charge in integer micro-USD, and `tokens` is input + output +
+// cache read + cache write (reasoning is a subset of output, never added).
+// `chatRuns` alone comes from runtime telemetry: duration and failure
+// diagnostics for chat turns, carrying no money.
+// ---------------------------------------------------------------------------
+
+const OrgAiUsageTotalsSchema = z.object({
+  requests: z.number().int().min(0),
+  tokens: z.number().int().min(0),
+  customerChargeMicros: MoneyMicrosSchema,
+});
+
+const OrgChatRunProfileSchema = z.object({
+  profile: z.string(),
+  executions: z.number().int().min(0),
+  percentOfTotal: z.number(),
+  avgDurationMs: z.number(),
+  failureRate: z.number(),
+});
+
+export const OrgUsageResponseSchema = z.object({
+  /** The org's billing window: `start`/`end` in UTC, days bucketed in `timezone`. */
+  period: z.object({
+    start: IsoDateTime,
+    end: IsoDateTime,
+    timezone: z.string(),
+  }),
+  summary: OrgAiUsageTotalsSchema,
+  daily: z.array(
+    z.object({
+      date: z.string(),
+      requests: z.number().int().min(0),
+      customerChargeMicros: MoneyMicrosSchema,
+    }),
+  ),
+  byFeature: z.array(
+    OrgAiUsageTotalsSchema.extend({ feature: z.enum(AI_FEATURES) }),
+  ),
+  byModel: z.array(
+    OrgAiUsageTotalsSchema.extend({
+      provider: z.string(),
+      modelId: z.string(),
+    }),
+  ),
+  /** Attributed usage only: system work (no user) counts in the totals, not here. */
+  byUser: z.array(
+    OrgAiUsageTotalsSchema.extend({
+      userId: z.string(),
+      email: z.string().nullable(),
+    }),
+  ),
+  chatRuns: z.object({
+    executions: z.number().int().min(0),
+    avgDurationMs: z.number(),
+    failureRate: z.number(),
+    byProfile: z.array(OrgChatRunProfileSchema),
+  }),
+});
+
+export type OrgUsageResponse = z.infer<typeof OrgUsageResponseSchema>;

package/src/org/org-unit-api-schemas.ts

@@ -0,0 +1,226 @@
+/**
+ * Org Unit API Schemas
+ *
+ * Unit relationships and level config, the org-unit response envelopes, open-role
+ * and unit-permission request/response schemas, and their inferred types.
+ *
+ * Split out of `./schemas.ts`, which re-exports this module unchanged — import
+ * from `./schemas` (or the `./org` entry), not from this file directly.
+ */
+import { z } from "zod";
+import { ORG_UNIT_ABSOLUTE_MAX_DEPTH } from "./org-depth";
+import {
+  MissingAtNextLevelSchema,
+  OpenRoleSchema,
+  OrgUnitMembershipSchema,
+  OrgUnitRelationshipRoleSchema,
+  OrgUnitRelationshipTypeSchema,
+  OrgUnitSchema,
+  OrgUnitTreeNodeSchema,
+  UnitMembershipRoleSchema,
+} from "./org-unit-schemas";
+
+export const OrgUnitRelationshipSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  fromUnit: z.string().uuid(),
+  toUnit: z.string().uuid(),
+  type: OrgUnitRelationshipTypeSchema,
+  role: OrgUnitRelationshipRoleSchema,
+  contextKey: z.string().nullable(),
+  metadata: z.record(z.string(), z.unknown()),
+  createdAt: z.string(),
+});
+
+export const OrgLevelIconSchema = z.enum([
+  "city",
+  "buildings",
+  "users-four",
+  "users-three",
+  "users",
+]);
+
+export const OrgLevelConfigSchema = z.object({
+  orgId: z.string().uuid(),
+  depth: z.number().int().min(1).max(ORG_UNIT_ABSOLUTE_MAX_DEPTH),
+  label: z.string().min(1).nullable(),
+  labelPlural: z.string().min(1).nullable(),
+  icon: OrgLevelIconSchema.nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+// --- Response schemas (request schemas live in backend per ADR-CONT-044) ---
+
+export const OrgUnitResponseSchema = z.object({ unit: OrgUnitSchema });
+
+export const OrgUnitTreeResponseSchema = z.object({
+  nodes: z.array(OrgUnitTreeNodeSchema),
+  levelConfig: z.array(OrgLevelConfigSchema),
+});
+
+export const OrgUnitChildrenResponseSchema = z.object({
+  parentId: z.string().uuid(),
+  children: z.array(OrgUnitTreeNodeSchema),
+});
+
+export const OrgUnitAncestorsResponseSchema = z.object({
+  unitId: z.string().uuid(),
+  ancestors: z.array(OrgUnitSchema),
+});
+
+export const OrgUnitDescendantsResponseSchema = z.object({
+  rootId: z.string().uuid(),
+  descendants: z.array(OrgUnitSchema),
+});
+
+export const OrgUnitRelationshipsResponseSchema = z.object({
+  unitId: z.string().uuid(),
+  incoming: z.array(OrgUnitRelationshipSchema),
+  outgoing: z.array(OrgUnitRelationshipSchema),
+});
+
+export const OrgLevelConfigResponseSchema = z.object({
+  entries: z.array(OrgLevelConfigSchema),
+});
+
+export const OrgUnitMembershipResponseSchema = z.object({
+  membership: OrgUnitMembershipSchema,
+});
+
+export const OrgUnitMembershipListResponseSchema = z.object({
+  unitId: z.string().uuid(),
+  memberships: z.array(OrgUnitMembershipSchema),
+});
+
+// ---------------------------------------------------------------------------
+// Open roles (PRD open-roles)
+// Request schemas are colocated here (a narrow deviation from ADR-CONT-044, as
+// with UpdateOrgUnitRequest) so the app's add-role form and the backend
+// validate against one published shape.
+// ---------------------------------------------------------------------------
+
+export const OpenRoleResponseSchema = z.object({ openRole: OpenRoleSchema });
+
+export const OpenRoleListResponseSchema = z.object({
+  unitId: z.string().uuid(),
+  openRoles: z.array(OpenRoleSchema),
+});
+
+/** ISO calendar date (YYYY-MM-DD) — version-agnostic vs `z.string().date()`. */
+const IsoDateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, {
+  message: "must be an ISO date (YYYY-MM-DD)",
+});
+
+export const CreateOpenRoleRequestSchema = z.object({
+  title: z.string().min(1).max(255).nullable().optional(),
+  targetStartDate: IsoDateSchema.nullable().optional(),
+});
+
+/** Only the non-terminal client transitions are accepted; `fill` is its own
+ * endpoint and `open` is the seeded initial state, never set by the client. */
+export const UpdateOpenRoleStatusRequestSchema = z.object({
+  status: z.enum(["hiring", "closed"]),
+});
+
+/**
+ * Fill an open role by seating an existing org member (`userId`) or inviting a
+ * new person by email. Exactly one branch — a discriminated union keyed on `mode`.
+ */
+export const FillOpenRoleRequestSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("existing"), userId: z.string().uuid() }),
+  z.object({
+    mode: z.literal("invite"),
+    email: z.string().email(),
+    role: z.enum(["admin", "member"]),
+  }),
+]);
+
+/**
+ * Effective manager of an org unit — a user whose membership (direct or
+ * inherited from an ancestor) grants the `orgUnit.{id}.manage` capability.
+ *
+ * Direct grants have `inheritedFromUnitId === unitId`. For inherited grants,
+ * `inheritedFromUnitId` identifies the ancestor whose membership propagates
+ * authority down the subtree (ltree `path @>` containment).
+ */
+export const OrgUnitPermissionsEntrySchema = z.object({
+  userId: z.string().uuid(),
+  membershipRole: UnitMembershipRoleSchema,
+  inheritedFromUnitId: z.string().uuid(),
+  inheritedFromUnitName: z.string().min(1),
+});
+
+export const ListOrgUnitPermissionsResponseSchema = z.object({
+  unitId: z.string().uuid(),
+  entries: z.array(OrgUnitPermissionsEntrySchema),
+});
+
+// ---------------------------------------------------------------------------
+// PATCH /api/org-units/:unitId (PRD-00526)
+// Request schema colocated with the response schema so the app can import
+// the same shape backend validates against. This is a narrow deviation from
+// ADR-CONT-044 (request schemas normally live in backend) because the
+// partial-update + at-least-one-field refinement is the published promise
+// consumers must satisfy.
+// ---------------------------------------------------------------------------
+
+export const UpdateOrgUnitRequestSchema = z
+  .object({
+    name: z.string().min(1).max(255).optional(),
+    description: z.string().max(2000).nullable().optional(),
+  })
+  .refine((v) => v.name !== undefined || v.description !== undefined, {
+    message: "at least one of name or description must be provided",
+  });
+
+export const UpdateOrgUnitResponseSchema = z.object({ unit: OrgUnitSchema });
+
+// --- Inferred types ---
+
+export type OrgUnit = z.infer<typeof OrgUnitSchema>;
+export type OrgUnitTreeNode = z.infer<typeof OrgUnitTreeNodeSchema>;
+export type OrgUnitMembership = z.infer<typeof OrgUnitMembershipSchema>;
+export type OrgUnitRelationship = z.infer<typeof OrgUnitRelationshipSchema>;
+export type OrgLevelConfig = z.infer<typeof OrgLevelConfigSchema>;
+export type OrgLevelIcon = z.infer<typeof OrgLevelIconSchema>;
+export type OrgUnitResponse = z.infer<typeof OrgUnitResponseSchema>;
+export type OrgUnitTreeResponse = z.infer<typeof OrgUnitTreeResponseSchema>;
+export type MissingAtNextLevel = z.infer<typeof MissingAtNextLevelSchema>;
+export type OrgUnitChildrenResponse = z.infer<
+  typeof OrgUnitChildrenResponseSchema
+>;
+export type OrgUnitAncestorsResponse = z.infer<
+  typeof OrgUnitAncestorsResponseSchema
+>;
+export type OrgUnitDescendantsResponse = z.infer<
+  typeof OrgUnitDescendantsResponseSchema
+>;
+export type OrgUnitRelationshipsResponse = z.infer<
+  typeof OrgUnitRelationshipsResponseSchema
+>;
+export type OrgLevelConfigResponse = z.infer<
+  typeof OrgLevelConfigResponseSchema
+>;
+export type OrgUnitMembershipResponse = z.infer<
+  typeof OrgUnitMembershipResponseSchema
+>;
+export type OrgUnitMembershipListResponse = z.infer<
+  typeof OrgUnitMembershipListResponseSchema
+>;
+export type OpenRole = z.infer<typeof OpenRoleSchema>;
+export type OpenRoleResponse = z.infer<typeof OpenRoleResponseSchema>;
+export type OpenRoleListResponse = z.infer<typeof OpenRoleListResponseSchema>;
+export type CreateOpenRoleRequest = z.infer<typeof CreateOpenRoleRequestSchema>;
+export type UpdateOpenRoleStatusRequest = z.infer<
+  typeof UpdateOpenRoleStatusRequestSchema
+>;
+export type FillOpenRoleRequest = z.infer<typeof FillOpenRoleRequestSchema>;
+export type OrgUnitPermissionsEntry = z.infer<
+  typeof OrgUnitPermissionsEntrySchema
+>;
+export type ListOrgUnitPermissionsResponse = z.infer<
+  typeof ListOrgUnitPermissionsResponseSchema
+>;
+export type UpdateOrgUnitRequest = z.infer<typeof UpdateOrgUnitRequestSchema>;
+export type UpdateOrgUnitResponse = z.infer<typeof UpdateOrgUnitResponseSchema>;

package/src/org/org-unit-schemas.ts

@@ -0,0 +1,223 @@
+/**
+ * Org Unit Schemas
+ *
+ * The canonical org-unit model (ADR-BE-120): unit vocabulary enums, the unit and
+ * tree-node shapes, memberships and open roles.
+ *
+ * Split out of `./schemas.ts`, which re-exports this module unchanged — import
+ * from `./schemas` (or the `./org` entry), not from this file directly.
+ */
+import { z } from "zod";
+import {
+  ORG_UNIT_ABSOLUTE_MAX_DEPTH,
+  UNIT_OWNER_MEMBERSHIP_ROLES,
+} from "./org-depth";
+
+// ---------------------------------------------------------------------------
+// OrgUnit canonical model (ADR-BE-120)
+// ---------------------------------------------------------------------------
+
+export const OrgUnitClassificationSchema = z.enum([
+  "execution_unit",
+  "org_container",
+  "leadership",
+  "custom",
+]);
+
+export const OrgUnitSyncModeSchema = z.enum([
+  "manual_only",
+  "synced_readonly",
+  "synced_with_overrides",
+]);
+
+export const OrgUnitVisibilitySchema = z.enum([
+  "public",
+  "private",
+  "restricted",
+]);
+
+export const OrgUnitRelationshipTypeSchema = z.enum([
+  "collaborates_with",
+  "reports_to",
+  "depends_on",
+  "custom",
+]);
+
+export const OrgUnitRelationshipRoleSchema = z.enum([
+  "owner",
+  "participant",
+  "supporting",
+]);
+
+/**
+ * Positional slot a member holds in the org-unit tree. ORTHOGONAL to the
+ * `OrgChartRole` policy vocabulary (this is an INPUT to authority resolution,
+ * not the derived policy role). Level is encoded in the value (l1…l20, one
+ * per depth up to `ORG_UNIT_ABSOLUTE_MAX_DEPTH`).
+ */
+export const UnitMembershipRoleSchema = z.enum([
+  "member",
+  ...UNIT_OWNER_MEMBERSHIP_ROLES,
+]);
+
+export type UnitMembershipRole = z.infer<typeof UnitMembershipRoleSchema>;
+
+export const OrgUnitMembershipStatusSchema = z.enum([
+  "active",
+  "pending",
+  "removed",
+]);
+
+export const OrgUnitMembershipSourceSchema = z.enum([
+  "manual",
+  "google_groups",
+  "scim",
+  "hris",
+]);
+
+/**
+ * Hiring lifecycle of an open role. See `OpenRoleStatus` in `./org-units` for
+ * the transition rules. Only `open` and `hiring` are "active" (render a card
+ * and count toward `openRoleCount`); `filled`/`closed` are terminal.
+ */
+export const OpenRoleStatusSchema = z.enum([
+  "open",
+  "hiring",
+  "filled",
+  "closed",
+]);
+
+export const OrgUnitErrorCodeSchema = z.enum([
+  "CYCLE_BLOCKED",
+  "DEPTH_EXCEEDED",
+  "TARGET_ARCHIVED",
+  "ROOT_HAS_NO_PARENT",
+  "PARENT_ARCHIVED",
+  "SLUG_TAKEN",
+  "CROSS_ORG_REPARENT",
+  "ORDERKEY_CONFLICT",
+  "SIBLING_NOT_FOUND",
+  "SIBLINGS_DIFFERENT_PARENT",
+]);
+
+export const OrgUnitSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  parentId: z.string().uuid().nullable(),
+  slug: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().nullable(),
+  typeTag: z.string().min(1),
+  classification: OrgUnitClassificationSchema.nullable(),
+  orderKey: z.string().min(1),
+  path: z.string().min(1),
+  syncMode: OrgUnitSyncModeSchema,
+  visibilityDefault: OrgUnitVisibilitySchema.nullable(),
+  metadata: z.record(z.string(), z.unknown()),
+  archivedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+/**
+ * Active users home directly at this unit who have no level-(depth+1) home
+ * assignment within its subtree. The settings UI surfaces this as a
+ * synthetic "[child level label] assignment missing" row above the
+ * children list at every level. `null` for leaf-level units (no children
+ * configured below them) where the concept is meaningless.
+ */
+export const MissingAtNextLevelSchema = z.object({
+  count: z.number().int().min(0),
+  userIds: z.array(z.string().uuid()),
+});
+
+export const OrgUnitTreeNodeSchema = OrgUnitSchema.extend({
+  depth: z.number().int().min(1).max(ORG_UNIT_ABSOLUTE_MAX_DEPTH),
+  hasChildren: z.boolean(),
+  /**
+   * WHAT it counts is the `.describe()` below — the single field-level
+   * description, which reaches `openapi/backend.yaml` and the generated API
+   * types. This comment carries only WHY, so the two cannot drift into
+   * disagreeing.
+   *
+   * Why accounts: it is the right population for anything that needs an account
+   * to act on — the share dialog's fanout, the unit-scoped members table. It is
+   * backed by `home_assignments`, whose `user_id` is NOT NULL, so an accountless
+   * person structurally cannot appear in it. Deliberately NOT redefined and NOT
+   * deprecated; {@link placedPeopleCount} answers the headcount question, and the
+   * two legitimately disagree (ADR-CONTRACTS-150, ADR-BE-657).
+   */
+  memberCount: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      "Accounts with a home assignment, rolled up over this unit's subtree. Legitimately 0 for a fully staffed department in an HRIS-imported org, where almost nobody has signed in — use placedPeopleCount for headcount.",
+    ),
+  /** Drives the "(N + M open)" count split in the people surfaces. */
+  openRoleCount: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      "Active open roles (`open` + `hiring`) rolled up over this unit's subtree. Vacant seats only — an HRIS-imported seat is `lifecycle_owner='import:hris'` and is counted by neither this nor memberCount.",
+    ),
+  /**
+   * Predicate: `placement_role='canonical'`, `status <> 'ended'`, keyed by
+   * `positions.unit_id`. Placement and home are independent graphs
+   * (ADR-CTRL-159), so a person seated here may be homed elsewhere and vice
+   * versa. The `positions.status` non-filter stated in the `.describe()` below
+   * is deliberate and load-bearing — the backend pins it with a test whose name
+   * says so (ADR-BE-657).
+   */
+  placedPeopleCount: z
+    .number()
+    .int()
+    .min(0)
+    .describe(
+      "Distinct people holding a live canonical seat in this unit's subtree, whether or not they have an account. Deliberately does NOT filter positions.status: an occupied `closed` seat still draws a card on the org chart, so a filter here would disagree with it.",
+    ),
+  missingAtNextLevel: MissingAtNextLevelSchema.nullable(),
+});
+
+export const OrgUnitMembershipSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  unitId: z.string().uuid(),
+  userId: z.string().uuid(),
+  membershipRole: UnitMembershipRoleSchema,
+  status: OrgUnitMembershipStatusSchema,
+  source: OrgUnitMembershipSourceSchema,
+  sourceRef: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+/**
+ * An open role — a persisted placeholder for the person who will sit in a unit.
+ * Carries unit membership (a seat) but never authority. `title` and
+ * `targetStartDate` are optional planning attributes. On `fill`, `filledByUserId`
+ * points at the seated user and a real `org_unit_membership` is created; the row
+ * is kept as staffing history. `targetStartDate` is an ISO date (YYYY-MM-DD).
+ */
+export const OpenRoleSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  unitId: z.string().uuid(),
+  title: z.string().nullable(),
+  targetStartDate: z.string().nullable(),
+  status: OpenRoleStatusSchema,
+  filledByUserId: z.string().uuid().nullable(),
+  // The open role's own reporting edge (ADR-BE-291): defaults to its creator's
+  // seat, editable/clearable. Drives chart placement now that the unit-head
+  // anchor is retired (ADR-BE-292). Null → unmanaged (Unassigned bucket).
+  //
+  // The manager POSITION, not a user (ADR-CONTRACTS-131). The retired
+  // user-keyed flattening was a lie in two directions: an open-role manager
+  // already surfaced as null because it had no user to collapse to, and
+  // post-HRIS every open role reporting to an imported (accountless) manager
+  // would read null too.
+  reportsToPositionId: z.string().uuid().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});

package/src/org/ownership-transfer-types.ts

@@ -0,0 +1,51 @@
+/**
+ * Ownership Transfer DTOs (PRD-00153)
+ *
+ * Request, status and acceptance-view shapes for the ownership-transfer UI flows,
+ * plus the acceptance-page responsibility checklist.
+ *
+ * Split out of `./types.ts`, which re-exports this module unchanged — import
+ * from `./types` (or the `./org` entry), not from this file directly.
+ */
+
+// =============================================================================
+// Ownership Transfer DTOs (PRD-00153)
+// Rich types for the transfer UI flows, supplementing OwnershipTransferRequest
+// and OwnershipTransferStatus in `./types`.
+// =============================================================================
+
+/** Request body for initiating ownership transfer (extends existing to include optional note). */
+export interface TransferInitiateRequest {
+  readonly newOwnerEmail: string;
+  readonly note?: string;
+}
+
+/** Response for transfer status queries — extends existing OwnershipTransferStatus. */
+export interface TransferStatusResponse {
+  readonly pending: boolean;
+  readonly newOwnerEmail?: string;
+  readonly note?: string;
+  readonly requestedAt?: string;
+  readonly expiresAt?: string;
+  readonly initiatorName?: string;
+}
+
+/** Read-only view for the transfer acceptance page. */
+export interface TransferAcceptanceView {
+  readonly workspaceName: string;
+  readonly initiatorName: string;
+  readonly initiatorEmail: string;
+  readonly note?: string;
+  readonly expiresAt: string;
+  readonly token: string;
+}
+
+/** Responsibility checklist items shown on the acceptance page. */
+export const TRANSFER_RESPONSIBILITIES = [
+  "You will become the sole owner of this workspace",
+  "You will be responsible for billing and compliance",
+  "The current owner will be downgraded to admin",
+  "This action cannot be undone without a new transfer",
+] as const;
+
+export type TransferResponsibility = (typeof TRANSFER_RESPONSIBILITIES)[number];