@company-semantics/contracts 87.0.0 → 88.0.1

package/src/org/authority-schemas.ts

@@ -0,0 +1,242 @@
+/**
+ * Authority & Delegation Schemas
+ *
+ * Authority axes (mechanism × locality × mutability), unit owners, pending
+ * owners and delegations.
+ *
+ * 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";
+
+// ---------------------------------------------------------------------------
+// Authority & Delegation vocabulary
+//
+// The API expresses authority as orthogonal axes (mechanism × locality ×
+// mutability) instead of a single overloaded `source` enum, so future
+// combinations like inherited-delegated or hris-delegated compose by
+// construction rather than forcing each consumer to add a new switch case.
+// The engine's internal AuthoritySource enum stays narrower than the wire
+// shape — it's debug/audit vocabulary, not API vocabulary.
+// ---------------------------------------------------------------------------
+
+/**
+ * Engine-internal authority source. Used by the projection storage layer for
+ * debugging and drift records; not part of the public API response shape.
+ * `manual_membership` was removed when the legacy `l{N}_unit_owner` track was
+ * canonicalized onto delegations.
+ */
+export const AuthoritySourceSchema = z.enum([
+  "structural",
+  "delegated",
+  "org_admin",
+]);
+export type AuthoritySource = z.infer<typeof AuthoritySourceSchema>;
+
+export const AuthorityOriginSchema = z.enum([
+  "topology",
+  "delegation",
+  "administrative_override",
+]);
+export type AuthorityOrigin = z.infer<typeof AuthorityOriginSchema>;
+
+export const AuthorityConfidenceSchema = z.enum(["authoritative", "inferred"]);
+export type AuthorityConfidence = z.infer<typeof AuthorityConfidenceSchema>;
+
+/** How the authority arose. */
+export const AuthorityMechanismSchema = z.enum([
+  "structural",
+  "delegated",
+  "rbac",
+]);
+export type AuthorityMechanism = z.infer<typeof AuthorityMechanismSchema>;
+
+/** Whether the grant lives on the target unit or is inherited from an ancestor. */
+export const AuthorityLocalitySchema = z.enum(["local", "inherited"]);
+export type AuthorityLocality = z.infer<typeof AuthorityLocalitySchema>;
+
+/**
+ * Whether the user can change this authority from this surface.
+ *  - `derived`: change the upstream source instead (the org chart, RBAC roles).
+ *  - `user_managed`: removable from this UI.
+ *
+ * Consumed by {@link OwnerAuthoritySchema} and by the per-unit
+ * `WorkspaceMemberUnitDesignationEntrySchema` in `./schemas`.
+ */
+export const AuthorityMutabilitySchema = z.enum(["derived", "user_managed"]);
+export type AuthorityMutability = z.infer<typeof AuthorityMutabilitySchema>;
+
+export const OwnerAuthoritySchema = z.object({
+  mechanism: AuthorityMechanismSchema,
+  locality: AuthorityLocalitySchema,
+  mutability: AuthorityMutabilitySchema,
+  derivedFromUnitId: z.string().uuid(),
+  derivedFromUnitName: z.string().min(1).optional(),
+  /**
+   * True when this authority derives from the org ROOT unit — i.e. the holder
+   * is a CEO (a unit owner of the org root, observed locally on the root
+   * or as inherited authority on a descendant). Lets consumers classify CEO
+   * without a separate org-tree lookup, the same way `mechanism === 'rbac'`
+   * identifies an org admin. Omitted (falsy) for non-root derivations.
+   */
+  derivedFromRoot: z.boolean().optional(),
+  derivedFromUserId: z.string().uuid().nullable().optional(),
+  /**
+   * Human-readable reason this authority applies, built at serialize time from
+   * the strategy's derivation metadata. Foundation for trust UI, debugging,
+   * AI explainability, governance reports, and audits.
+   */
+  explanation: z.string(),
+  /**
+   * Strategy-specific structured metadata, preserved verbatim for tooling that
+   * needs more than the explanation string (drift detection, audits).
+   */
+  derivationMetadata: z.record(z.string(), z.unknown()).optional(),
+  /**
+   * `org_unit_delegations.id` when `mechanism === 'delegated'`. Surfaced
+   * separately so the UI doesn't need to inspect derivationMetadata to render
+   * the revoke action.
+   */
+  delegationId: z.string().uuid().optional(),
+  /**
+   * Delegation expiry as an ISO-8601 timestamp when `mechanism === 'delegated'`
+   * and the delegation is time-boxed; `null` for a permanent delegation; omitted
+   * for non-delegated mechanisms. Expired delegations never reach this surface —
+   * the projection read filters `expires_at > now()` — so a present value is
+   * always in the future.
+   */
+  expiresAt: IsoDateTime.nullable().optional(),
+});
+export type OwnerAuthority = z.infer<typeof OwnerAuthoritySchema>;
+
+export const OrgUnitOwnerSchema = z.object({
+  userId: z.string().uuid(),
+  fullName: z.string().min(1),
+  jobTitle: z.string().nullable(),
+  avatarUrl: z.string().nullable(),
+  /** All authority grants this user holds for the unit. At least one entry. */
+  authorities: z.array(OwnerAuthoritySchema).min(1),
+});
+export type OrgUnitOwner = z.infer<typeof OrgUnitOwnerSchema>;
+
+/**
+ * A lead the structure review chose who is NOT YET an owner, because they have
+ * no account to grant to. Mirrors one `staged` row of the backend's lead → owner
+ * bridge ledger (ADR-BE-734): the grant is minted the moment the person links an
+ * account, attributed to the reviewer who decided it. Person-keyed on purpose —
+ * an owner is user-keyed and this person has no user.
+ *
+ * DISPLAY ONLY. Never an authorization input: a pending owner holds nothing
+ * until the grant exists, and consumers must not derive a capability from it.
+ */
+export const PendingUnitOwnerSchema = z.object({
+  personId: z.string().uuid(),
+  fullName: z.string().min(1),
+  jobTitle: z.string().nullable(),
+  /** When the reviewer decided it — the answer's time, not the row's. */
+  decidedAt: IsoDateTime,
+  /** Why it is pending. One reason today; a closed enum so a second is a decision. */
+  reason: z.enum(["no_account"]),
+});
+export type PendingUnitOwner = z.infer<typeof PendingUnitOwnerSchema>;
+
+/**
+ * "No lead for now" (ADR-BE-733): the latest `unit_head` review answer for the
+ * unit was an explicit clear, and no later answer superseded it. Distinct from
+ * "never had one" — an absence a person recorded, not a default. Display only.
+ */
+export const UnitLeadClearedSchema = z.object({
+  decidedAt: IsoDateTime,
+});
+export type UnitLeadCleared = z.infer<typeof UnitLeadClearedSchema>;
+
+/**
+ * Contract-level invariant: each owner list contains each userId at most once.
+ * Duplicate userIds are a serializer bug, not a presentation concern, so we
+ * fail Zod parse at the API boundary on both server and client.
+ */
+const uniqueByUserId = (arr: ReadonlyArray<{ userId: string }>): boolean =>
+  new Set(arr.map((o) => o.userId)).size === arr.length;
+const uniqueByPersonId = (arr: ReadonlyArray<{ personId: string }>): boolean =>
+  new Set(arr.map((o) => o.personId)).size === arr.length;
+
+export const OrgUnitOwnersResponseSchema = z.object({
+  owners: z
+    .array(OrgUnitOwnerSchema)
+    .refine(uniqueByUserId, { message: "duplicate userId in owners" }),
+  inherited: z
+    .array(OrgUnitOwnerSchema)
+    .refine(uniqueByUserId, { message: "duplicate userId in inherited" })
+    .optional(),
+  /**
+   * Leads chosen in the structure review who become owners once they have an
+   * account. Always present (`[]` when none) — the server knows, so the client
+   * never has to guess between "none" and "not asked".
+   */
+  pending: z
+    .array(PendingUnitOwnerSchema)
+    .refine(uniqueByPersonId, { message: "duplicate personId in pending" }),
+  /** The recorded "no lead for now", or null when no such answer stands. */
+  leadCleared: UnitLeadClearedSchema.nullable(),
+});
+export type OrgUnitOwnersResponse = z.infer<typeof OrgUnitOwnersResponseSchema>;
+
+export const DelegationSchema = z.object({
+  id: z.string().uuid(),
+  orgId: z.string().uuid(),
+  unitId: z.string().uuid(),
+  userId: z.string().uuid(),
+  grantedBy: z.string().uuid().nullable(),
+  grantedAt: z.string(),
+  revokedAt: z.string().nullable(),
+  status: z.enum(["active", "revoked"]),
+  note: z.string().nullable(),
+  /**
+   * ISO-8601 timestamp at which the delegation stops conferring authority, or
+   * `null` for a permanent delegation. Enforcement is read-time (the projection
+   * read filters `expires_at > now()`); the row itself stays `status='active'`
+   * until explicitly revoked.
+   */
+  expiresAt: z.string().nullable(),
+});
+export type Delegation = z.infer<typeof DelegationSchema>;
+
+export const CreateDelegationRequestSchema = z.object({
+  userId: z.string().uuid(),
+  note: z.string().max(2000).optional(),
+  /**
+   * Optional ISO-8601 expiry. Omitted or `null` ⇒ a permanent delegation. The
+   * UI captures a date and sends end-of-day in the user's timezone.
+   */
+  expiresAt: IsoDateTime.nullable().optional(),
+  /**
+   * When true, the granted user is emailed a notification (carrying `note` as
+   * the message). Not persisted — it only gates the side-effect email. Omitted
+   * is treated as false; left without a default so the inferred request type
+   * keeps `notify` optional rather than forcing every caller to pass it.
+   */
+  notify: z.boolean().optional(),
+});
+export type CreateDelegationRequest = z.infer<
+  typeof CreateDelegationRequestSchema
+>;
+
+/**
+ * Change a delegation's expiry without revoking it: extend, shorten, or clear
+ * (set `expiresAt: null` to make it permanent). Used by the inline expiry edit
+ * on an existing delegate row.
+ */
+export const UpdateDelegationRequestSchema = z.object({
+  expiresAt: IsoDateTime.nullable(),
+});
+export type UpdateDelegationRequest = z.infer<
+  typeof UpdateDelegationRequestSchema
+>;
+
+export const DelegationListResponseSchema = z.object({
+  delegations: z.array(DelegationSchema),
+});
+export type DelegationListResponse = z.infer<
+  typeof DelegationListResponseSchema
+>;

package/src/org/index.ts

@@ -3,6 +3,11 @@
  *
  * Re-exports organization vocabulary types.
  * Import from '@company-semantics/contracts' (root).
+ *
+ * A module this barrel re-exports in full is re-exported with `export *`.
+ * `./types`, `./schemas` and `./org-depth` are listed by name because the
+ * barrel curates them: it omits a few names and re-exports some schema
+ * inferences under a `*Dto` alias.
  */
 
 export type {
@@ -77,183 +82,61 @@ export {
 } from "./types";
 
 // Domain types (Phase 4)
-export type {
-  DomainStatus,
-  DomainVerificationMethod,
-  OrgDomain,
-  Phase4AuditAction,
-} from "./domain";
+export * from "./domain";
 
 // View authorization scopes (Phase 5 - ADR-APP-013)
-export type { AuthorizableView } from "./view-scopes";
-export { VIEW_SCOPE_MAP, getViewScope } from "./view-scopes";
+export * from "./view-scopes";
 
 // Org structure facts: provenance + home/membership separation (ADR-CONTRACTS-066)
-export {
-  FactSourceTierSchema,
-  FACT_SOURCE_TIER_PRECEDENCE,
-  FactProvenanceSchema,
-  HomeAssignmentSchema,
-} from "./structure-facts";
-export type {
-  FactSourceTier,
-  FactProvenance,
-  HomeAssignment,
-} from "./structure-facts";
+export * from "./structure-facts";
 
 // Occupancy: the holds_position relation (M:N, co-occupancy first-class).
 // Vacancy = a position with no active occupancy. (ADR-CONT-083 / ADR-CTRL-182)
-export { OccupancyStatusSchema, OccupancySchema } from "./occupancy";
-export type { OccupancyStatus, Occupancy } from "./occupancy";
+export * from "./occupancy";
 
 // Position: the org seat (planned/open/filled/closed) — a seat, not a person
 // or a title. Carries a FactProvenance envelope. (ADR-CONT-083 / ADR-CTRL-182)
-export { PositionStatusSchema, PositionSchema } from "./positions";
-export type { PositionStatus, Position } from "./positions";
+export * from "./positions";
 
 // Position reporting: the canonical seat -> manager-seat reporting edge. The
 // person hierarchy derives from this composed with occupancy. (ADR-CONT-083 / ADR-CTRL-182)
-export {
-  PositionReportingRelationshipTypeSchema,
-  PositionReportingSchema,
-  ReportingErrorCodeSchema,
-} from "./position-reporting";
-export type {
-  PositionReportingRelationshipType,
-  PositionReporting,
-  ReportingErrorCode,
-} from "./position-reporting";
+export * from "./position-reporting";
 
 // Source authority: per-field ownership — who may WRITE a given entity field.
 // Orthogonal to provenance (who reported). (ADR-CONT-083 / ADR-CTRL-182)
-export { SourceAuthoritySchema } from "./source-authority";
-export type { SourceAuthority } from "./source-authority";
+export * from "./source-authority";
 
 // Sync run summary: the outcome record of one adapter sync run (counts +
 // cursor watermark). A flat report shape, not a structure fact. (ADR-CONT-085)
-export { SyncRunSummarySchema } from "./sync-run";
-export type { SyncRunSummary } from "./sync-run";
+export * from "./sync-run";
 
 // Conflict record: one recorded reconciliation conflict surfaced during a sync.
 // Operational audit record about a sync, not a structure fact. (ADR-CONT-085)
-export { ConflictRecordSchema } from "./conflict-record";
-export type { ConflictRecord } from "./conflict-record";
+export * from "./conflict-record";
 
 // Org reconciliation ledger: the org's STANDING disagreements with the connected
 // HRIS — the open ones only, whether they arose during a sync (runId set) or
 // during app use (runId null). Complements the run-scoped conflicts view; does
 // not replace it. Resolution is a LOCAL decision (`sentToSource` is the literal
 // false). (ADR-BE-564)
-export {
-  OrgDivergenceSchema,
-  OrgReconciliationLedgerSchema,
-  OrgDivergenceResolutionSchema,
-  ResolveOrgDivergenceResultSchema,
-} from "./reconciliation";
-export type {
-  OrgDivergence,
-  OrgReconciliationLedger,
-  OrgDivergenceResolution,
-  ResolveOrgDivergenceResult,
-} from "./reconciliation";
+export * from "./reconciliation";
 
 // Structure findings: standing observations about recorded org data (a
 // custodial-looking reporting line, a pod that looks like its own team), open /
 // resolved by the facts / dismissed as intentional against a content
 // fingerprint. Not questions — corrections go through transformations.
 // (ADR-BE-765)
-export {
-  STRUCTURE_FINDING_KINDS,
-  STRUCTURE_FINDING_STATUSES,
-  StructureFindingKindSchema,
-  StructureFindingStatusSchema,
-  ReportingLineAnomalyReportSchema,
-  ReportingLineAnomalyFactsSchema,
-  SubunitCandidateFactsSchema,
-  StructureFindingDismissalSchema,
-  StructureFindingSchema,
-  StructureFindingListStatusSchema,
-  StructureFindingListResponseSchema,
-  DismissStructureFindingRequestSchema,
-  StructureFindingResponseSchema,
-} from "./structure-findings";
-export type {
-  StructureFindingKind,
-  StructureFindingStatus,
-  ReportingLineAnomalyReport,
-  ReportingLineAnomalyFacts,
-  SubunitCandidateFacts,
-  StructureFindingDismissal,
-  StructureFinding,
-  StructureFindingListStatus,
-  StructureFindingListResponse,
-  DismissStructureFindingRequest,
-  StructureFindingResponse,
-} from "./structure-findings";
+export * from "./structure-findings";
 
 // Org transformation wire vocabulary: intent -> simulation -> preview. The
 // engine turns a TransformationRequest into scored mutation bundles and returns
 // a TransformationPreview the operator confirms before apply. (ADR-CONTRACTS-072)
-export {
-  OrgIntentSchema,
-  FactMutationSchema,
-  TransformationOriginSchema,
-  ProvenanceSchema,
-  ExecutionContextSchema,
-  TransformationRequestSchema,
-  ConstraintViolationSchema,
-  RecommendationSchema,
-  FindingSeveritySchema,
-  FindingSchema,
-  TransformStrategySchema,
-  SelectionRationaleSchema,
-  ReportingEdgeProvenanceSchema,
-  SupersededReportingEdgeSchema,
-  TransformationPreviewSchema,
-} from "./transformation";
-export type {
-  OrgIntent,
-  FactMutation,
-  TransformationOrigin,
-  Provenance,
-  ExecutionContext,
-  TransformationRequest,
-  ConstraintViolation,
-  Recommendation,
-  FindingSeverity,
-  Finding,
-  TransformStrategy,
-  SelectionRationale,
-  ReportingEdgeProvenance,
-  SupersededReportingEdge,
-  TransformationPreview,
-} from "./transformation";
+export * from "./transformation";
 
 // Canonical facts: the adapter-seam ingestion batch. Each fact is keyed by
 // external identity (externalSourceId/externalSourceSystem) and carries a
 // FactProvenance envelope; the reconciler consumes the batch. (ADR-CONT-085 / ADR-CTRL-183)
-export {
-  CanonicalPersonSchema,
-  CanonicalOrgUnitSchema,
-  CanonicalPositionStatusSchema,
-  CanonicalPositionSchema,
-  CanonicalOccupancySchema,
-  CanonicalReportingEdgeSchema,
-  CanonicalUnresolvedManagerResolutionSchema,
-  CanonicalUnresolvedManagerSchema,
-  CanonicalFactsSchema,
-} from "./canonical-facts";
-export type {
-  CanonicalPerson,
-  CanonicalOrgUnit,
-  CanonicalPositionStatus,
-  CanonicalPosition,
-  CanonicalOccupancy,
-  CanonicalReportingEdge,
-  CanonicalUnresolvedManagerResolution,
-  CanonicalUnresolvedManager,
-  CanonicalFacts,
-} from "./canonical-facts";
+export * from "./canonical-facts";
 
 // Org-structure inference: the snapshot the engine reasons over and the
 // proposed desired state it returns. Evidence is TYPED so the validator can
@@ -266,119 +149,26 @@ export type {
 // Apply on an AI proposal makes it human_confirmed without making its origin
 // manual. Precedence runs on `authority` alone, via mayOverrideAuthority.
 // (PRD-00956)
-export {
-  StructureEvidenceSchema,
-  TOPOLOGY_ONLY_EVIDENCE_KINDS,
-  StructureUnitAuthoritySchema,
-  StructureProposalOriginSchema,
-  StructureAcceptedBySchema,
-  StructureAuthoritySchema,
-  StructureProvenanceSchema,
-  mayOverrideAuthority,
-  ProposedOrgUnitSchema,
-  PersonStructureOutcomeSchema,
-  StructureReviewItemSchema,
-  STRUCTURE_REVIEW_ITEM_KINDS,
-  StructureProposalSchema,
-  StructurePersonFactSchema,
-  StructureReportingFactSchema,
-  ExistingUnitFactSchema,
-  ExistingPlacementFactSchema,
-  StructureInferenceSnapshotSchema,
-} from "./structure-inference";
-export type {
-  StructureEvidence,
-  StructureUnitAuthority,
-  StructureProposalOrigin,
-  StructureAcceptedBy,
-  StructureAuthority,
-  StructureProvenance,
-  ProposedOrgUnit,
-  PersonStructureOutcome,
-  StructureReviewItem,
-  StructureProposal,
-  StructurePersonFact,
-  StructureReportingFact,
-  ExistingUnitFact,
-  ExistingPlacementFact,
-  StructureInferenceSnapshot,
-} from "./structure-inference";
+export * from "./structure-inference";
 
 // Canonical OrgUnit tree ordering (PRD-00506)
-export type { TreeOrderableNode } from "./tree-ordering";
-export { orderTreeNodes } from "./tree-ordering";
-export {
-  levelSlugForDepth,
-  slugifyLevelLabel,
-  unitRouteSegments,
-} from "./unit-route";
-export type { UnitRouteLevel } from "./unit-route";
+export * from "./tree-ordering";
+export * from "./unit-route";
 
 // Company.md domain types (PRD-00173)
-export type {
-  CompanyMdVisibility,
-  CompanyMdDiscoverabilityPolicy,
-  CompanyMdClassification,
-  CompanyMdDocLevel,
-  CompanyMdDocKind,
-  CompanyMdNodeType,
-  CompanyMdSource,
-  CompanyMdDependency,
-  CompanyMdNodeIdentity,
-  CompanyMdTreeNode,
-  CompanyMdDocCore,
-  CompanyMdDocCollaborators,
-  CompanyMdDocRelations,
-  CompanyMdDoc,
-  CompanyMdContextBankItem,
-} from "./company-md";
+export * from "./company-md";
 
 // Company.md real-time collaboration wire contract: sync/update-accepted
 // responses, the SSE frame union, the Y.Doc shape constant, and the published
 // size limits. Sequences are ALWAYS decimal strings. (ADR-CONT-102)
-export {
-  COMPANY_MD_COLLAB_TEXT_KEY,
-  COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS,
-  COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES,
-  COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS,
-  COMPANY_MD_COLLAB_PRESENCE_TTL_MS,
-  COMPANY_MD_COLLAB_PRESENCE_HEARTBEAT_MS,
-  CompanyMdCollabSyncLimitsSchema,
-  CompanyMdCollabSyncResponseSchema,
-  CompanyMdCollabUpdateAcceptedSchema,
-  CompanyMdCollabUpdateEventSchema,
-  CompanyMdCollabPresenceEventSchema,
-  CompanyMdCollabResetEventSchema,
-  CompanyMdCollabAccessRevokedEventSchema,
-  CompanyMdCollabConnectedEventSchema,
-  CompanyMdCollabServerDrainEventSchema,
-  CompanyMdCollabSseEventSchema,
-} from "./company-md-collab";
-export type {
-  CompanyMdCollabSyncLimits,
-  CompanyMdCollabSyncResponse,
-  CompanyMdCollabUpdateAccepted,
-  CompanyMdCollabUpdateEvent,
-  CompanyMdCollabPresenceEvent,
-  CompanyMdCollabResetEvent,
-  CompanyMdCollabAccessRevokedEvent,
-  CompanyMdCollabConnectedEvent,
-  CompanyMdCollabServerDrainEvent,
-  CompanyMdCollabSseEvent,
-} from "./company-md-collab";
+export * from "./company-md-collab";
 
 // Sharing and ACL types (PRD-00306). The legacy AccessSource / AccessReason /
 // EffectiveAccess / EvaluationStep / AccessExplanation were removed with
 // CompanyMdAccessEvaluator (ADR-BE-392); ShareState.effectiveAccess now carries
 // the projection EffectiveAccessResponse, and the ONE AccessSource lives in
 // permissions/access-source.
-export type {
-  AccessLevel,
-  SharePolicy,
-  AclEntry,
-  ShareState,
-  PermissionAuditEntry,
-} from "./sharing";
+export * from "./sharing";
 
 // Workspace response schemas (PRD-00445)
 export {
@@ -513,19 +303,7 @@ export type {
 } from "./schemas";
 
 // OrgUnit canonical model (ADR-BE-120)
-export type {
-  OrgUnitClassification,
-  OrgUnitSyncMode,
-  OrgUnitVisibility,
-  OrgUnitRelationshipType,
-  OrgUnitRelationshipRole,
-  OrgUnitMembershipStatus,
-  OrgUnitMembershipSource,
-  OpenRoleStatus,
-  OrgUnitErrorCode,
-  OrgTreeResponse,
-} from "./org-units";
-export { ORG_UNITS_ROUTES } from "./org-units";
+export * from "./org-units";
 export {
   ORG_UNIT_DESIGNED_MAX_DEPTH,
   ORG_UNIT_ABSOLUTE_MAX_DEPTH,
@@ -644,5 +422,4 @@ export type {
 } from "./schemas";
 
 // Why an org stopped being personal (ADR-CONTRACTS-167)
-export type { OrgSharedTransitionTrigger } from "./shared-transition";
-export { ORG_SHARED_TRANSITION_TRIGGERS } from "./shared-transition";
+export * from "./shared-transition";