@company-semantics/contracts 15.1.0 → 17.0.0

package/src/org/index.ts

@@ -141,8 +141,9 @@ export {
   WorkspaceOverviewSchema,
   WorkspaceMembersResponseSchema,
   WorkspaceMemberDetailSchema,
-  WorkspaceMemberManagesEntrySchema,
+  WorkspaceMemberUnitDesignationEntrySchema,
   OrgUnitDesignationSchema,
+  HomeUnitRoleSchema,
   RoleCatalogEntrySchema,
   RoleCatalogResponseSchema,
   WorkspaceAuthConfigSchema,
@@ -168,8 +169,9 @@ export type {
   WorkspaceAccessResponse,
   WorkspaceOverview as WorkspaceOverviewDto,
   WorkspaceMembersResponse,
-  WorkspaceMemberManagesEntry,
+  WorkspaceMemberUnitDesignationEntry,
   OrgUnitDesignation,
+  HomeUnitRole,
   WorkspaceAuthConfig as WorkspaceAuthConfigDto,
   WorkspaceAuditEvent as WorkspaceAuditEventDto,
   WorkspaceResolvePathResponse,

package/src/org/schemas.ts

@@ -28,7 +28,7 @@ const WorkspaceMemberUnitSummarySchema = z.object({
 /**
  * Designation a member holds over a unit they manage (ADR-CTRL-112).
  *
- * Precedence, highest-first: whole_org > admin > leader > delegate > member.
+ * Precedence, highest-first: whole_org > admin > unit_owner > delegate > member.
  * The org-wide designations (`whole_org`, `admin`) anchor to the org root
  * unit. This vocabulary is DISPLAY-ONLY — it summarizes management reach for
  * UI surfaces and is NEVER an authorization input (authority resolution uses
@@ -37,19 +37,19 @@ const WorkspaceMemberUnitSummarySchema = z.object({
 export const OrgUnitDesignationSchema = z.enum([
   "whole_org",
   "admin",
-  "leader",
+  "unit_owner",
   "delegate",
   "member",
 ]);
 export type OrgUnitDesignation = z.infer<typeof OrgUnitDesignationSchema>;
 
-export const WorkspaceMemberManagesEntrySchema = z.object({
+export const WorkspaceMemberUnitDesignationEntrySchema = z.object({
   unitId: z.string(),
   unitName: z.string(),
   designation: OrgUnitDesignationSchema,
 });
-export type WorkspaceMemberManagesEntry = z.infer<
-  typeof WorkspaceMemberManagesEntrySchema
+export type WorkspaceMemberUnitDesignationEntry = z.infer<
+  typeof WorkspaceMemberUnitDesignationEntrySchema
 >;
 
 const WorkspaceMemberSchema = z.object({
@@ -87,11 +87,13 @@ const WorkspaceMemberSchema = z.object({
   /** OrgUnit memberships for this member, capped at a small number server-side. */
   unitMemberships: z.array(WorkspaceMemberUnitSummarySchema),
   /**
-   * Per-unit org-chart designations the member holds where they manage
-   * (ADR-CTRL-112). Display-only summary of management reach; never an
-   * authorization input. Empty array when the member manages nothing.
+   * Per-unit org-chart designations the member holds (ADR-CTRL-112). Carries
+   * BOTH management-reach entries (whole_org/admin/unit_owner/delegate) and
+   * plain contributor entries (`member`); consumers split by designation.
+   * Display-only summary; never an authorization input. Empty array when the
+   * member holds no per-unit designation.
    */
-  manages: z.array(WorkspaceMemberManagesEntrySchema),
+  unitDesignations: z.array(WorkspaceMemberUnitDesignationEntrySchema),
   /** True when server truncated `unitMemberships`; detail endpoint returns the full list. */
   unitMembershipsTruncated: z.boolean(),
   /** Invite lifecycle status. `null` for members without an invite record. */
@@ -595,6 +597,15 @@ export type ScopeCheckBatchResponse = z.infer<
 // Invite sub-schema
 // ---------------------------------------------------------------------------
 
+/**
+ * Role the invitee takes in their home unit on acceptance. `unit_owner` is a
+ * deferred structural-leadership grant applied at accept time. Source of truth
+ * for the hand-mirrored `OrgInvite`/`CreateInviteRequest` interface unions in
+ * `org/types.ts` (enforced by the `schema-type-mirror` guard).
+ */
+export const HomeUnitRoleSchema = z.enum(["member", "unit_owner"]);
+export type HomeUnitRole = z.infer<typeof HomeUnitRoleSchema>;
+
 const OrgInviteSchema = z.object({
   id: z.string(),
   orgId: z.string(),
@@ -605,9 +616,10 @@ const OrgInviteSchema = z.object({
   // Home unit the invitee is placed in on acceptance (users.primary_unit_id).
   // Optional/nullable: legacy invites predate this field.
   homeUnitId: z.string().uuid().optional(),
-  // Role the invitee takes in homeUnitId on acceptance ('leader' is a deferred
-  // structural-leadership grant). Optional/'member' for legacy + unit-less invites.
-  homeUnitRole: z.enum(["member", "leader"]).optional(),
+  // Role the invitee takes in homeUnitId on acceptance ('unit_owner' is a
+  // deferred structural-leadership grant). Optional/'member' for legacy +
+  // unit-less invites.
+  homeUnitRole: HomeUnitRoleSchema.optional(),
   createdAt: z.string(),
   expiresAt: z.string(),
   acceptedAt: z.string().optional(),

package/src/org/types.ts

@@ -420,11 +420,11 @@ export interface OrgInvite {
   homeUnitId?: string;
   /**
    * Role the invitee takes in `homeUnitId` on acceptance — a plain team member,
-   * or a structural leader of that unit (a *deferred* leadership grant applied
+   * or a unit owner of that unit (a *deferred* leadership grant applied
    * at acceptance time). Distinct from the org-level {@link role}. Optional:
    * legacy invites and unit-less invites have none (treated as `member`).
    */
-  homeUnitRole?: "member" | "leader";
+  homeUnitRole?: "member" | "unit_owner";
   createdAt: string;
   expiresAt: string;
   acceptedAt?: string;
@@ -444,12 +444,12 @@ export interface CreateInviteRequest {
   homeUnitId?: string;
   /**
    * Role the invitee takes in `homeUnitId` on acceptance: a plain team member
-   * (default), or a structural leader of that unit. `leader` is a *deferred*
+   * (default), or a unit owner of that unit. `unit_owner` is a *deferred*
    * grant — the invite is sent now and the leadership is assigned when the
    * invitee accepts. Only meaningful when `homeUnitId` is set; the backend
-   * rejects `leader` without a home unit. Optional/`member` for older callers.
+   * rejects `unit_owner` without a home unit. Optional/`member` for older callers.
    */
-  homeUnitRole?: "member" | "leader";
+  homeUnitRole?: "member" | "unit_owner";
 }
 
 /**

package/src/permissions/orgchart-roles.ts

@@ -24,7 +24,7 @@ import { z } from "zod";
 
 export const ORG_CHART_ROLES = [
   "owner",
-  "leader",
+  "unit_owner",
   "delegate",
   "admin",
 ] as const;
@@ -44,7 +44,7 @@ export const OrgChartRoleSchema = z.enum(ORG_CHART_ROLES);
  */
 export const ORG_CHART_ROLE_LABELS: Record<OrgChartRole, string> = {
   owner: "CEO",
-  leader: "Unit owner",
+  unit_owner: "Unit owner",
   delegate: "Delegate",
   admin: "Admin",
 };

package/src/ralph/README.md

@@ -12,31 +12,44 @@ TypeScript types for Ralph, an autonomous AI coding loop with graduated trust le
 - PRD `passes` field is the only field Ralph should modify during execution
 - Orchestration, prompts, and trust logic live in company-semantics-control, not here
 
-## Public API
+<!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
 
-### PRD Types
+## Public API
 
-- `RalphPRDCategory` — Category of feature item (`functional`, `architectural`, `integration`, `polish`)
-- `RalphPRDPriority` — Priority level (`high`, `medium`, `low`)
-- `RalphPRDItem` — Single feature item in a PRD
-- `RalphPRD` — Complete PRD document
+- `AllowedRepo` _(type)_
+- `REPO_PRECEDENCE`
+- `RalphAcceptanceCriteria` _(type)_
+- `RalphAgentContract` _(type)_
+- `RalphCapabilities` _(type)_
+- `RalphCommitPolicy` _(type)_
+- `RalphExecutionPolicy` _(type)_
+- `RalphFailurePolicy` _(type)_
+- `RalphFeatureGroup` _(type)_
+- `RalphInteractionFlow` _(type)_
+- `RalphIteration` _(type)_
+- `RalphMeta` _(type)_
+- `RalphMode` _(type)_
+- `RalphPRD` _(type)_
+- `RalphPRDCategory` _(type)_
+- `RalphPRDItem` _(type)_
+- `RalphPRDPriority` _(type)_
+- `RalphProgress` _(type)_
+- `RalphReferenceImplementation` _(type)_
+- `RalphScope` _(type)_
+- `RalphSuccessCriteria` _(type)_
+
+<!-- END GENERATED: readme-public-api -->
+
+<!-- BEGIN GENERATED: readme-dependencies — derived from code by `pnpm readme-api`. Do not edit. -->
 
-### Progress Types
+## Dependencies
 
-- `RalphIteration` — Record of a single iteration
-- `RalphMode` — Operation mode (`hitl`, `afk`)
-- `RalphProgress` — Complete session progress state
+**Internal domains:**
 
-### Trust Types
+_None._
 
-- `RalphTrustLevel` — Trust level (0-3)
-- `RalphRunResult` — Run outcome (`success`, `failure`)
-- `RalphCIStatus` — CI status (`green`, `red`, `skipped`)
-- `RalphTrustLog` — Run outcome record for audit
-- `RalphTrustPolicy` — Trust policy configuration
-- `RalphDemotionReason` — Reasons for automatic demotion
+**External packages:**
 
-## Dependencies
+_None._
 
-**Imports from:** (none — leaf module)
-**Imported by:** company-semantics-control
+<!-- END GENERATED: readme-dependencies -->

package/src/rate-limit/README.md

@@ -49,3 +49,27 @@ This is the canonical semantic across all Company Semantics repos.
 
 - PRD-00012: Foundational rate limiting implementation
 - PRD-00013: Contracts integration (this promotion)
+
+<!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
+
+## Public API
+
+- `RateLimitConfig` _(type)_
+- `RateLimitResult` _(type)_
+- `RateLimitTier`
+
+<!-- END GENERATED: readme-public-api -->
+
+<!-- BEGIN GENERATED: readme-dependencies — derived from code by `pnpm readme-api`. Do not edit. -->
+
+## Dependencies
+
+**Internal domains:**
+
+_None._
+
+**External packages:**
+
+_None._
+
+<!-- END GENERATED: readme-dependencies -->

package/src/system/README.md

@@ -18,28 +18,46 @@ Defines the semantic contract between backend (producer) and site (renderer).
 - No render hints in contracts — renderers decide presentation independently
 - `layer` metadata is semantic grouping, not layout instruction
 
+<!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
+
 ## Public API
 
-### Source model (layer-based)
+- `AggregatedCapabilities` _(type)_
+- `CapabilityInvariants` _(type)_
+- `CapabilityManifest` _(type)_
+- `DiagramEdge` _(type)_
+- `DiagramEdgeRelation` _(type)_
+- `DiagramMode` _(type)_
+- `DiagramNode` _(type)_
+- `DiagramNodeKind` _(type)_
+- `DiagramSnapshot` _(type)_
+- `DiagramSpec` _(type)_
+- `EdgeDirection` _(type)_
+- `FeatureStatus` _(type)_
+- `FlowStage` _(type)_
+- `PipelinePhase` _(type)_
+- `RepoCapability` _(type)_
+- `RepoId` _(type)_
+- `SystemCapability` _(type)_
+- `SystemCapabilityManifest` _(type)_
+- `SystemLayer` _(type)_
+
+<!-- END GENERATED: readme-public-api -->
+
+<!-- BEGIN GENERATED: readme-dependencies — derived from code by `pnpm readme-api`. Do not edit. -->
+
+## Dependencies
 
-- `FeatureStatus` — 'prod' | 'experimental' | 'disabled'
-- `SystemCapability` — individual feature definition
-- `SystemLayer` — logical layer grouping
-- `SystemCapabilityManifest` — full manifest structure (YAML representation)
+**Internal domains:**
 
-### Diagram graph
+_None._
 
-- `DiagramNodeKind` — 'layer' | 'feature' | 'artifact'
-- `DiagramEdgeRelation` — 'contains' | 'flows_to' | 'depends_on'
-- `DiagramNode` — semantic node with optional layer grouping
-- `DiagramEdge` — semantic relationship between nodes
-- `DiagramSpec` — complete graph that crosses system boundaries
+**External packages:**
 
-## Dependencies
+_None._
 
-**Imports from:** (none — leaf module)
-**Imported by:** company-semantics (backend), company-semantics-site
+<!-- END GENERATED: readme-dependencies -->
 
 ## Specification
 
-See [LIVING_ASCII_DIAGRAM_SPEC.md](../docs/LIVING_ASCII_DIAGRAM_SPEC.md) for the canonical system definition.
+See [LIVING_ASCII_DIAGRAM_SPEC.md](../../docs/LIVING_ASCII_DIAGRAM_SPEC.md) for the canonical system definition.