@company-semantics/contracts 23.0.0 → 25.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '0294f47290c0' as const;
-export const SPEC_HASH_FULL = '0294f47290c059e23186e9b25f6e0a476e304947f9ead66491ef4c29118e0609' as const;
+export const SPEC_HASH = 'ca30049e5670' as const;
+export const SPEC_HASH_FULL = 'ca30049e56707141ae807a8c218d97947e9aeade592540d5e2609eb985f43480' as const;

package/src/api/generated.ts

@@ -3697,25 +3697,62 @@ export interface components {
         SetMemberManagerResponse: {
             success: boolean;
             memberId: string;
-            managerUserId: string | null;
+            manager: ({
+                /** @constant */
+                kind: "member";
+                /** Format: uuid */
+                userId: string;
+            } | {
+                /** @constant */
+                kind: "open-role";
+                /** Format: uuid */
+                openRoleId: string;
+            }) | null;
             relationshipType: string;
             message: string;
         };
         SetMemberManagerRequest: {
-            /** Format: uuid */
-            managerUserId: string;
+            manager: {
+                /** @constant */
+                kind: "member";
+                /** Format: uuid */
+                userId: string;
+            } | {
+                /** @constant */
+                kind: "open-role";
+                /** Format: uuid */
+                openRoleId: string;
+            };
         };
         BulkReparentReportingResponse: {
             /** @constant */
             success: true;
             movedCount: number;
-            /** Format: uuid */
-            toManagerId: string;
+            toManager: {
+                /** @constant */
+                kind: "member";
+                /** Format: uuid */
+                userId: string;
+            } | {
+                /** @constant */
+                kind: "open-role";
+                /** Format: uuid */
+                openRoleId: string;
+            };
         };
         BulkReparentReportingRequest: {
             memberIds: string[];
-            /** Format: uuid */
-            toManagerId: string;
+            toManager: {
+                /** @constant */
+                kind: "member";
+                /** Format: uuid */
+                userId: string;
+            } | {
+                /** @constant */
+                kind: "open-role";
+                /** Format: uuid */
+                openRoleId: string;
+            };
             idempotencyKey: string;
         };
         SubmitInteractiveTaskResponse: {
@@ -4856,10 +4893,28 @@ export interface components {
                 }[];
             }[];
             edges: {
-                /** Format: uuid */
-                reportUserId: string;
-                /** Format: uuid */
-                managerUserId: string;
+                report: {
+                    /** @constant */
+                    kind: "member";
+                    /** Format: uuid */
+                    userId: string;
+                } | {
+                    /** @constant */
+                    kind: "open-role";
+                    /** Format: uuid */
+                    openRoleId: string;
+                };
+                manager: {
+                    /** @constant */
+                    kind: "member";
+                    /** Format: uuid */
+                    userId: string;
+                } | {
+                    /** @constant */
+                    kind: "open-role";
+                    /** Format: uuid */
+                    openRoleId: string;
+                };
                 /** @enum {string} */
                 relationshipType: "solid" | "dotted";
             }[];
@@ -4869,7 +4924,17 @@ export interface components {
                 /** Format: uuid */
                 unitId: string;
                 title: string | null;
-                reportsToUserId: string | null;
+                reportsTo: ({
+                    /** @constant */
+                    kind: "member";
+                    /** Format: uuid */
+                    userId: string;
+                } | {
+                    /** @constant */
+                    kind: "open-role";
+                    /** Format: uuid */
+                    openRoleId: string;
+                }) | null;
             }[];
         };
         /** @description Polling snapshot of a generic ingestion operation. */
@@ -9018,7 +9083,17 @@ export interface operations {
         requestBody: {
             content: {
                 "application/json": {
-                    userId: string | null;
+                    manager: ({
+                        /** @constant */
+                        kind: "member";
+                        /** Format: uuid */
+                        userId: string;
+                    } | {
+                        /** @constant */
+                        kind: "open-role";
+                        /** Format: uuid */
+                        openRoleId: string;
+                    }) | null;
                 };
             };
         };

package/src/email/registry.ts

@@ -112,6 +112,24 @@ export const EMAIL_KINDS = {
     plainTextRequired: true,
     htmlSupported: true,
   },
+  "companyMd.access_requested": {
+    kind: "companyMd.access_requested",
+    subject: "Someone requested access to a document",
+    plainTextRequired: true,
+    htmlSupported: true,
+  },
+  "companyMd.access_request_approved": {
+    kind: "companyMd.access_request_approved",
+    subject: "Your access request was approved",
+    plainTextRequired: true,
+    htmlSupported: true,
+  },
+  "companyMd.access_request_denied": {
+    kind: "companyMd.access_request_denied",
+    subject: "Your access request was reviewed",
+    plainTextRequired: true,
+    htmlSupported: true,
+  },
 } as const satisfies Record<EmailKind, EmailKindDefinition>;
 
 // =============================================================================

package/src/email/types.ts

@@ -32,7 +32,10 @@ export type EmailKind =
   | "org.ownership_transfer_completed"
   | "security.alert" // future
   | "chat.shared"
-  | "share.granted";
+  | "share.granted"
+  | "companyMd.access_requested"
+  | "companyMd.access_request_approved"
+  | "companyMd.access_request_denied";
 
 // =============================================================================
 // Email Payloads
@@ -128,6 +131,37 @@ export interface EmailPayloads {
     /** Optional message from the granter, included in the email only (not persisted) */
     message?: string;
   };
+  /** Sent to the doc owner(s) when an actor requests access (ADR-BE-338). */
+  "companyMd.access_requested": {
+    /** Display name of the requester */
+    requesterName: string;
+    /** Title of the company.md node access is requested for */
+    docTitle: string;
+    /** Optional message from the requester (email only) */
+    message?: string;
+    /** Deep-link that opens the doc's ShareDialog scrolled to the pending request */
+    reviewUrl: string;
+  };
+  /** Sent to the requester when an owner approves (ADR-BE-338). */
+  "companyMd.access_request_approved": {
+    /** Display name of the owner who approved */
+    approverName: string;
+    /** Title of the company.md node */
+    docTitle: string;
+    /** Access level granted */
+    accessLevel: "editor" | "commenter" | "viewer";
+    /** Full URL to view the node */
+    docUrl: string;
+  };
+  /** Sent to the requester when an owner denies (ADR-BE-338). */
+  "companyMd.access_request_denied": {
+    /** Display name of the owner who denied */
+    approverName: string;
+    /** Title of the company.md node */
+    docTitle: string;
+    /** Optional reason from the owner (email only) */
+    reason?: string;
+  };
 }
 
 // =============================================================================

package/src/identity/README.md

@@ -49,6 +49,8 @@ TypeScript types and functions for user identity and display name resolution.
 - `MeResponse` _(type)_
 - `MeResponseSchema` — Full identity context returned by GET /api/me.
 - `NameSource` _(type)_ — Source of the user's name data.
+- `OrgChartActorRef` _(type)_
+- `OrgChartActorRefSchema`
 - `PeopleOrgChartEdge` _(type)_
 - `PeopleOrgChartEdgeSchema`
 - `PeopleOrgChartNode` _(type)_

package/src/identity/index.ts

@@ -64,6 +64,7 @@ export type {
 // People Org Chart (GET /api/users/org-chart)
 export {
   ReportingRelationshipTypeSchema,
+  OrgChartActorRefSchema,
   PeopleOrgChartNodeSchema,
   PeopleOrgChartOwnedUnitSchema,
   PeopleOrgChartEdgeSchema,
@@ -72,6 +73,7 @@ export {
 } from "./people-org-chart";
 export type {
   ReportingRelationshipType,
+  OrgChartActorRef,
   PeopleOrgChartNode,
   PeopleOrgChartOwnedUnit,
   PeopleOrgChartEdge,

package/src/identity/org-chart-actor.ts

@@ -0,0 +1,24 @@
+/**
+ * Org-chart actor reference — either endpoint of a reporting edge.
+ *
+ * A node in the people chart that can sit on EITHER side of a reporting edge: a
+ * filled member (keyed by occupant `userId`) OR an unfilled open-role seat
+ * (keyed by its own `openRoleId`). A vacant seat is a first-class reporting
+ * actor — it can be a manager that real people report to (ADR-BE-312), not just
+ * a report. The discriminant lets an edge point at either kind without losing
+ * what the id means. Mirrors the app's `ActorIdentity` shape exactly so the app
+ * consumes this type directly (one common spine across wire + UI).
+ *
+ * Lives in its own zero-dependency module (zod only) so both `people-org-chart`
+ * (which already depends on `org/schemas` for AuthorityMutability) and
+ * `org/schemas` (which needs it for the set-manager request/response) can import
+ * it without forming a module-init cycle.
+ */
+import { z } from "zod";
+
+export const OrgChartActorRefSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("member"), userId: z.string().uuid() }),
+  z.object({ kind: z.literal("open-role"), openRoleId: z.string().uuid() }),
+]);
+
+export type OrgChartActorRef = z.infer<typeof OrgChartActorRefSchema>;

package/src/identity/people-org-chart.ts

@@ -23,6 +23,15 @@ export type ReportingRelationshipType = z.infer<
   typeof ReportingRelationshipTypeSchema
 >;
 
+// Actor reference — either endpoint of a reporting edge (member | open-role).
+// Defined in its own zero-dependency module to avoid a module-init cycle with
+// `org/schemas` (which this file imports AuthorityMutabilitySchema from, and
+// which needs the actor ref for the set-manager request/response). Re-exported
+// here so the existing import site keeps working.
+export { OrgChartActorRefSchema } from "./org-chart-actor";
+export type { OrgChartActorRef } from "./org-chart-actor";
+import { OrgChartActorRefSchema } from "./org-chart-actor";
+
 // ---------------------------------------------------------------------------
 // Node — a person in the chart
 // ---------------------------------------------------------------------------
@@ -68,8 +77,12 @@ export type PeopleOrgChartNode = z.infer<typeof PeopleOrgChartNodeSchema>;
 // ---------------------------------------------------------------------------
 
 export const PeopleOrgChartEdgeSchema = z.object({
-  reportUserId: z.string().uuid(),
-  managerUserId: z.string().uuid(),
+  // Either endpoint may be a member or an open-role seat. An edge whose
+  // `manager` is an open-role seat is "a person reports to a vacant role"
+  // (ADR-BE-312); whose `report` is an open-role seat is "an open role reports
+  // to someone" (ADR-BE-291) — both are now expressible symmetrically.
+  report: OrgChartActorRefSchema,
+  manager: OrgChartActorRefSchema,
   relationshipType: ReportingRelationshipTypeSchema,
 });
 
@@ -79,7 +92,7 @@ export type PeopleOrgChartEdge = z.infer<typeof PeopleOrgChartEdgeSchema>;
 // Open role — a persisted placeholder seat rendered as a dashed "Open role"
 // card in its unit's sibling column. Only active roles (open + hiring) are
 // included; filled/closed roles never appear here. `unitId` seats the card in
-// the right column. `reportsToUserId` is the open role's OWN reporting edge
+// the right column. `reportsTo` is the open role's OWN reporting edge
 // (ADR-BE-291): it defaults to the role's creator and is editable/clearable, so
 // a person-less seat is placed by reporting like everyone else (the chart owns
 // placement, ADR-CTRL-159). Null → the role hangs in its unit's projection-only
@@ -90,7 +103,10 @@ export const PeopleOrgChartOpenRoleSchema = z.object({
   id: z.string().uuid(),
   unitId: z.string().uuid(),
   title: z.string().nullable(),
-  reportsToUserId: z.string().uuid().nullable(),
+  // The open role's OWN reporting edge (ADR-BE-291). An actor ref so an open
+  // role can report to a person OR to another open-role seat (ADR-BE-312). Null
+  // → the role hangs in its unit's projection-only Unassigned bucket.
+  reportsTo: OrgChartActorRefSchema.nullable(),
 });
 
 export type PeopleOrgChartOpenRole = z.infer<
@@ -103,7 +119,7 @@ export type PeopleOrgChartOpenRole = z.infer<
 //
 // Person-less cards (empty-unit placeholders, ghosts, open roles) no longer
 // anchor under a stored unit-head "tether" (ADR-BE-284, retired by ADR-BE-292).
-// Open roles carry their own `reportsToUserId` edge; placeholders fall back to
+// Open roles carry their own `reportsTo` edge; placeholders fall back to
 // the render-time reporting heuristic.
 
 export const PeopleOrgChartResponseSchema = z.object({

package/src/index.ts

@@ -175,6 +175,7 @@ export type {
 // People Org Chart (GET /api/users/org-chart)
 export {
   ReportingRelationshipTypeSchema,
+  OrgChartActorRefSchema,
   PeopleOrgChartNodeSchema,
   PeopleOrgChartOwnedUnitSchema,
   PeopleOrgChartEdgeSchema,
@@ -183,6 +184,7 @@ export {
 } from "./identity/index";
 export type {
   ReportingRelationshipType,
+  OrgChartActorRef,
   PeopleOrgChartNode,
   PeopleOrgChartOwnedUnit,
   PeopleOrgChartEdge,
@@ -338,6 +340,8 @@ export type {
   TransferMemberEligibility,
   // Company.md domain types (PRD-00173)
   CompanyMdVisibility,
+  CompanyMdDiscoverabilityPolicy,
+  CompanyMdClassification,
   CompanyMdDocLevel,
   CompanyMdDocKind,
   CompanyMdNodeType,

package/src/org/README.md

@@ -57,8 +57,10 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `ChangeMemberRoleRequest` _(type)_ — Request payload for changing a member's role.
 - `ChangeMemberRoleResponse` _(type)_
 - `ChangeMemberRoleResponseSchema`
+- `CompanyMdClassification` _(type)_ — Information classification for a Company.md node — what the document is, for governance, NOT permissions.
 - `CompanyMdContextBankItem` _(type)_ — A context bank item — a company.md doc associated with one or more parent nodes.
 - `CompanyMdDependency` _(type)_
+- `CompanyMdDiscoverabilityPolicy` _(type)_ — Discoverability policy for a Company.md node — who knows it exists, orthogonal to who may read it (authority…
 - `CompanyMdDoc` _(type)_
 - `CompanyMdDocCollaborators` _(type)_
 - `CompanyMdDocCore` _(type)_
@@ -247,7 +249,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `SetActiveOrgResponse` _(type)_
 - `SetActiveOrgResponseSchema`
 - `SetMemberManagerResponse` _(type)_
-- `SetMemberManagerResponseSchema` — Response for setting (PATCH) or clearing (DELETE) a member's solid-line manager — the person-to-person…
+- `SetMemberManagerResponseSchema` — Response for setting (PATCH) or clearing (DELETE) a member's solid-line manager — the reporting edge that the…
 - `SharePolicy` _(type)_ — Document sharing policy. - restricted: Only explicit ACL + owning unit + org admins - orgread: All org…
 - `ShareState` _(type)_ — Complete sharing state for a document.
 - `SourceAuthority` _(type)_
@@ -336,6 +338,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 **Internal domains:**
 
 - `api`
+- `identity`
 - `permissions`
 
 **External packages:**

package/src/org/company-md.ts

@@ -23,6 +23,32 @@
  */
 export type CompanyMdVisibility = "private" | "unit" | "org";
 
+/**
+ * Discoverability policy for a Company.md node — *who knows it exists*, orthogonal
+ * to who may read it (authority resolution). See ADR-CTRL-194 / ADR-BE-338.
+ *
+ * - `org`: every org member knows the node exists; a non-reader sees the locked
+ *   meta-stub (title + owner byline) and may request access.
+ * - `owners`: only readers know it exists; a non-reader gets a no-leak 404.
+ *
+ * A *policy*, not a boolean — intentionally extensible (`unit | partners |
+ * customers`). It also governs retrieval (search, semantic search, suggested
+ * context, citation, agent browsing).
+ */
+export type CompanyMdDiscoverabilityPolicy = "org" | "owners";
+
+/**
+ * Information classification for a Company.md node — *what the document is*, for
+ * governance, NOT permissions (ADR-CTRL-194 / ADR-BE-338). Later drives export
+ * watermarking, share-approval gates, retrieval rules, and audit verbosity
+ * without changing who can read. Named now; enforcement behaviors deferred.
+ */
+export type CompanyMdClassification =
+  | "public"
+  | "internal"
+  | "confidential"
+  | "highly_confidential";
+
 /**
  * @deprecated Since 1.12.0. `CompanyMdDocLevel` is superseded by `CompanyMdDocKind` + `depth`.
  *
@@ -107,6 +133,17 @@ export interface CompanyMdNodeIdentity {
   readonly depth: 1 | 2 | 3 | 4 | 5 | null;
   readonly parentId: string | null;
   readonly visibility: CompanyMdVisibility;
+  /**
+   * Who knows this node exists (orthogonal to who may read it). Governs the
+   * non-reader branch: `org` → locked meta-stub + request-access; `owners` →
+   * no-leak 404. See ADR-CTRL-194 / ADR-BE-338.
+   */
+  readonly discoverabilityPolicy: CompanyMdDiscoverabilityPolicy;
+  /**
+   * Governance classification of the node (not a permission). Drives future
+   * governance behaviors (watermarking, share-approval, retrieval, audit).
+   */
+  readonly classification: CompanyMdClassification;
   /** Owning org_unit. Null for root docs or when the owning unit has been archived. */
   readonly owningUnitId: string | null;
 }
@@ -132,6 +169,21 @@ export interface CompanyMdDocCore extends CompanyMdNodeIdentity {
    * its body (ADR-BE-245). Omitted/`false` on the normal full-content path.
    */
   readonly contentRedacted?: boolean;
+  /**
+   * Read-state of this node for the requesting actor (ADR-CTRL-194 / ADR-BE-338):
+   * - `full`: actor may read; `content` is the real body.
+   * - `redacted_admin`: meta-tier admin meta-view (ADR-BE-245).
+   * - `locked_requestable`: non-reader of an `org`-discoverable node — body is the
+   *   redacted stub and the actor may request access.
+   * Omitted on legacy paths that only set `contentRedacted`.
+   */
+  readonly accessState?: "full" | "redacted_admin" | "locked_requestable";
+  /**
+   * Whether the requesting actor may request access to this node. A *separate*
+   * resolver, intentionally NOT equal to `discoverabilityPolicy` (a direct-link
+   * recipient to an `owners` node may still be allowed to request).
+   */
+  readonly canRequestAccess?: boolean;
 }
 
 export interface CompanyMdDocCollaborators {

package/src/org/index.ts

@@ -163,6 +163,8 @@ export { orderTreeNodes } from "./tree-ordering";
 // Company.md domain types (PRD-00173)
 export type {
   CompanyMdVisibility,
+  CompanyMdDiscoverabilityPolicy,
+  CompanyMdClassification,
   CompanyMdDocLevel,
   CompanyMdDocKind,
   CompanyMdNodeType,

package/src/org/schemas.ts

@@ -13,6 +13,7 @@
 import { z } from "zod";
 import { CursorPageSchema } from "../api/primitives";
 import { OrgChartRoleSchema } from "../permissions/orgchart-roles";
+import { OrgChartActorRefSchema } from "../identity/org-chart-actor";
 
 // ---------------------------------------------------------------------------
 // Sub-schemas
@@ -505,8 +506,10 @@ export type ChangeMemberRoleResponse = z.infer<
 
 /**
  * Response for setting (PATCH) or clearing (DELETE) a member's solid-line
- * manager — the person-to-person reporting edge (`user_reporting`) that the
- * org chart is built from. `managerUserId` is null after a clear.
+ * manager — the reporting edge that the org chart is built from. `manager` is
+ * the actor the member now reports to: a `member` (person→person) OR an
+ * `open-role` seat (person reports to a vacant role — ADR-BE-312); null after a
+ * clear.
  *
  * Distinct from team membership (RBAC scopes) and `primary_unit_id` (home
  * unit): neither of those places a person in the reporting hierarchy.
@@ -515,7 +518,7 @@ export type ChangeMemberRoleResponse = z.infer<
 export const SetMemberManagerResponseSchema = z.object({
   success: z.boolean(),
   memberId: z.string(),
-  managerUserId: z.string().nullable(),
+  manager: OrgChartActorRefSchema.nullable(),
   relationshipType: z.string(),
   message: z.string(),
 });

package/src/permissions/access-request.ts

@@ -0,0 +1,67 @@
+/**
+ * Company.md Access-Request DTOs (ADR-CONTRACTS-071 / ADR-BE-338)
+ *
+ * The request-access workflow: a non-reader of an `org`-discoverable node asks
+ * the owner(s) for access; the first owner to act resolves the request, minting a
+ * normal grant. These are the shared request/response shapes.
+ *
+ * Zod-canonical: schema is the source of truth, the type is inferred.
+ */
+import { z } from "zod";
+import { GrantableAccessLevelSchema } from "./share-api";
+
+/**
+ * Lifecycle status of an access request. A single pending request exists per
+ * (node, actor); the first owner to act transitions it terminally.
+ */
+export const ACCESS_REQUEST_STATUSES = [
+  "pending",
+  "approved",
+  "denied",
+  "withdrawn",
+  "expired",
+] as const;
+export const AccessRequestStatusSchema = z.enum(ACCESS_REQUEST_STATUSES);
+export type AccessRequestStatus = z.infer<typeof AccessRequestStatusSchema>;
+
+/** POST body to create an access request. */
+export const AccessRequestCreateSchema = z.object({
+  /** Optional context the requester sends to the owner(s). */
+  message: z.string().max(2000).optional(),
+});
+export type AccessRequestCreate = z.infer<typeof AccessRequestCreateSchema>;
+
+/** A single actor that requested access (actor-generic; today a user). */
+export const AccessRequestActorSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+export type AccessRequestActor = z.infer<typeof AccessRequestActorSchema>;
+
+/** Full access-request record returned to owners (and the requester). */
+export const AccessRequestSchema = z.object({
+  id: z.string(),
+  requestor: AccessRequestActorSchema,
+  docId: z.string(),
+  status: AccessRequestStatusSchema,
+  message: z.string().nullable(),
+  createdAt: z.string(),
+  resolvedAt: z.string().nullable(),
+});
+export type AccessRequest = z.infer<typeof AccessRequestSchema>;
+
+/**
+ * POST body to approve a request. The owner chooses the granted level (default
+ * `viewer` is applied server-side if the field is omitted by older clients).
+ */
+export const ApproveAccessRequestSchema = z.object({
+  accessLevel: GrantableAccessLevelSchema,
+});
+export type ApproveAccessRequest = z.infer<typeof ApproveAccessRequestSchema>;
+
+/** POST body to deny a request. */
+export const DenyAccessRequestSchema = z.object({
+  /** Optional reason, surfaced to the requester (email only). */
+  reason: z.string().max(2000).optional(),
+});
+export type DenyAccessRequest = z.infer<typeof DenyAccessRequestSchema>;

package/src/permissions/index.ts

@@ -8,4 +8,5 @@ export * from "./access-levels";
 export * from "./orgchart-roles";
 export * from "./access-source";
 export * from "./share-api";
+export * from "./access-request";
 export * from "./permission-introspection";