@company-semantics/contracts 88.0.0 → 88.1.0

package/src/mcp/tool-descriptor.ts

@@ -0,0 +1,244 @@
+import type { ResourceType } from "./resources";
+
+/**
+ * @deprecated Use ToolDomain instead. ToolCategory is too coarse —
+ * 'data' conflates discovery, ingestion, and coverage.
+ */
+export type ToolCategory =
+  "system" | "data" | "connections" | "automation" | "developer";
+
+/**
+ * Tool domain taxonomy.
+ *
+ * Each value maps to a distinct domain boundary in the system architecture.
+ * Replaces ToolCategory which was too coarse for resource flow reasoning.
+ *
+ * - organization: Org settings, membership, billing queries
+ * - identity: User profile, auth state, preferences
+ * - integrations: OAuth connections, provider management
+ * - ingestion: Data import, sync jobs, source configuration
+ * - discovery: Search, exploration, content queries
+ * - knowledge: Fingerprints, embeddings, knowledge graph
+ * - system: Health, status, runtime diagnostics
+ */
+export type ToolDomain =
+  | "organization"
+  | "identity"
+  | "integrations"
+  | "ingestion"
+  | "discovery"
+  | "knowledge"
+  | "system";
+
+/**
+ * Tool visibility levels.
+ * Controls who can see the tool in discovery.
+ */
+export type ToolVisibility = "user" | "admin";
+
+/**
+ * How the tool can be invoked.
+ * - manual: User must explicitly request
+ * - assistant: AI can invoke proactively
+ * - hybrid: Both manual and assistant invocation
+ */
+export type ToolInvocationMode = "manual" | "assistant" | "hybrid";
+
+/**
+ * Tool effect classification.
+ * Effect classification is orthogonal to requiresConfirmation and requiresApproval.
+ * - effectClass: "Does this tool mutate state?"
+ * - requiresConfirmation: "Does the user need to approve before execution?"
+ * - requiresApproval: "Does this need cross-principal authorization?"
+ * An effectful tool may auto-execute (requiresConfirmation: false) for low-risk operations.
+ * An effectful tool may require approval without confirmation.
+ */
+export type ToolEffectClass = "pure" | "effectful";
+
+/**
+ * Tool intent classification.
+ *
+ * Classifies what the tool does to the system:
+ * - read: Pure data retrieval (no side effects)
+ * - mutate: State change (creates, updates, deletes)
+ * - analysis: Computation over data without mutation (aggregation, scoring)
+ *
+ * Note: 'control' was removed — system-level operations (health, status,
+ * runtime) use 'read' intent in the 'system' domain. Control is a domain
+ * classification, not an intent.
+ *
+ * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
+ * Enforced in backend tool registration, typed here for documentation.
+ */
+export type ToolIntent = "read" | "mutate" | "analysis";
+
+/**
+ * Tool lifecycle stability classification.
+ *
+ * - experimental: May change or be removed without notice
+ * - stable: Production-ready with backward compatibility guarantees
+ * - deprecated: Scheduled for removal, consumers should migrate
+ */
+export type ToolStability = "experimental" | "stable" | "deprecated";
+
+/**
+ * Tool computational complexity classification.
+ *
+ * Classifies the cost and latency profile of a tool invocation:
+ * - trivial: Sub-100ms, in-memory or single DB lookup
+ * - moderate: 100ms-5s, may involve external API calls
+ * - heavy: 5s+, batch processing, large data transfers, long-running ops
+ */
+export type ToolComplexity = "trivial" | "moderate" | "heavy";
+
+/**
+ * Integration provider tag for tools.
+ *
+ * Known values correspond to registered OAuth providers.
+ * Extensible via (string & {}) — new integrations do not require
+ * a contracts release, but known values get autocomplete.
+ */
+export type ToolIntegration = "slack" | "google" | "zoom" | (string & {});
+
+/**
+ * Complete tool descriptor for discovery and invocation.
+ *
+ * Discovery uses: id, name, description, category
+ * Invocation uses: id, requiresConfirmation, invocationMode, effectClass
+ */
+// @vocabulary-exempt reason: MCPToolDescriptor is a single cohesive descriptor consumed by multiple repos; splitting would break consumers
+export interface MCPToolDescriptor {
+  /** Unique identifier (matches MCP tool name, e.g., 'cs_help') */
+  id: string;
+  /** Human-readable name for display */
+  name: string;
+  /** User-facing description (what it does, not how) */
+  description: string;
+  /** Grouping category for UI organization */
+  category: ToolCategory;
+  /** Whether user confirmation is required before execution */
+  requiresConfirmation: boolean;
+  /**
+   * Whether this tool causes durable state change.
+   * Effectful = any tool that can cause durable state change (DB writes, external API calls, background job enqueue).
+   * Pure = read-only operations, URL generation, status queries.
+   *
+   * Orthogonal to requiresConfirmation — an effectful tool may auto-execute
+   * for low-risk operations, and a pure tool never needs confirmation.
+   * The bridge enforces: effectful tools must return previewResponse()
+   * with ExecutionIntent, never direct side effects.
+   */
+  effectClass: ToolEffectClass;
+  /** How the tool can be triggered */
+  invocationMode: ToolInvocationMode;
+  /** Who can see this tool */
+  visibility: ToolVisibility;
+
+  // --- New fields (PRD-00265) ---
+
+  /** Domain taxonomy classification. Replaces category for routing and grouping. */
+  domain: ToolDomain;
+  /**
+   * Integration providers this tool interacts with.
+   * Empty or omitted for tools that don't touch external integrations.
+   */
+  integrations?: ToolIntegration[];
+  /**
+   * User-impact risk classification.
+   * - none: Read-only, no side effects
+   * - low: Reversible mutation (can be undone)
+   * - moderate: User-visible side effect (notification sent, state changed)
+   * - high: Destructive or irreversible (data deletion, external action)
+   *
+   * INVARIANT: intent 'mutate' + risk 'high' → requiresConfirmation must be true.
+   */
+  risk: "none" | "low" | "moderate" | "high";
+  /** What the tool does to the system (read, mutate, analysis). */
+  intent: ToolIntent;
+  /** Lifecycle stability classification. */
+  stability: ToolStability;
+  /** Computational complexity and latency profile. */
+  complexity: ToolComplexity;
+  /**
+   * Input schema version number.
+   * Disambiguates input schema versioning from tool behavior versioning.
+   * Increment when the tool's input schema changes shape.
+   */
+  schemaVersion: number;
+  /**
+   * Authorization scopes required to invoke this tool.
+   * References scope strings from trust/scopes.ts.
+   * Omit for tools with no specific scope requirements.
+   */
+  scopes?: string[];
+  /**
+   * Resource types this tool produces (creates or outputs).
+   * Used for capability graph derivation — enables workflow ordering
+   * via resource flow instead of explicit `requires` fields.
+   */
+  produces?: ResourceType[];
+  /**
+   * Resource types this tool consumes (requires as input).
+   * Used for capability graph derivation — a tool that consumes
+   * 'integration.connection' can only run after a tool that produces it.
+   */
+  consumes?: ResourceType[];
+  /**
+   * Mutation-capability gate (ADR-BE-241). When present, the tool is locked
+   * unless the viewer's resolved capabilities permit it — the SINGLE source of
+   * truth consumed by BOTH the backend execution gate and the frontend tool-lock
+   * UI (replacing the previously triplicated ACTION_TOOL_GATES / FIELD_GATES /
+   * ACTION_GATES maps).
+   * - kind 'field': `path` addresses a FieldCapability in CapabilitiesResponse
+   *   (e.g. 'org.name', 'profile.fullName'); locked unless state === 'editable'.
+   * - kind 'action': `path` addresses an ActionCapability under `.actions`
+   *   (e.g. 'members.invite', 'orgAdmins.manage'); locked unless 'allowed'.
+   * Absent ⇒ ungated (gating is additive).
+   */
+  capabilityGate?: { kind: "field" | "action"; path: string };
+}
+
+/**
+ * Edge in the capability graph connecting two tools via a resource.
+ * A tool that produces a resource connects to tools that consume it.
+ *
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
+ */
+export interface CapabilityGraphEdge {
+  /** Tool ID that produces the resource */
+  from: string;
+  /** Tool ID that consumes the resource */
+  to: string;
+  /** Resource type flowing between tools */
+  resource: ResourceType;
+  /** Resource domain (extracted from resource namespace prefix, e.g., 'slack' from 'slack.channel') */
+  domain?: string;
+}
+
+/**
+ * Named workflow derived from capability graph paths.
+ * Represents a common multi-tool sequence (e.g., "Connect Slack → Ingest → Query").
+ *
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
+ */
+export interface ToolWorkflow {
+  /** Workflow name (e.g., "Slack Onboarding") */
+  name: string;
+  /** Human-readable description of the workflow */
+  description: string;
+  /** Ordered list of tool IDs in this workflow */
+  steps: string[];
+}
+
+/**
+ * Capability graph derived from tool resource flow metadata.
+ * Built from produces/consumes fields on MCPToolDescriptor.
+ *
+ * @see capability-graph.ts for buildCapabilityGraph() implementation
+ */
+export interface CapabilityGraph {
+  /** Resource flow edges between tools */
+  edges: CapabilityGraphEdge[];
+  /** Named workflows derived from graph paths */
+  workflows: ToolWorkflow[];
+}

package/src/org/README.md

@@ -17,8 +17,10 @@ Shared type vocabulary for organization ownership, type classification, and tran
 ## Public API
 
 - `AcceptInviteRequest` _(type)_ — Request payload for accepting an organization invite.
+- `AccessLevel` _(type)_ — Document access level.
 - `AcknowledgeSystemEventResponse` _(type)_
 - `AcknowledgeSystemEventResponseSchema`
+- `AclEntry` _(type)_
 - `ActionCapability` _(type)_
 - `ActionCapabilitySchema` — An action's gate: allowed, or blocked with the scope that would unlock it.
 - `AuthMethodConfig` _(type)_ — Authentication method configuration.
@@ -34,6 +36,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `AuthorityOriginSchema`
 - `AuthoritySource` _(type)_
 - `AuthoritySourceSchema` — Engine-internal authority source.
+- `AuthorizableView` _(type)_ — Type for views that can be checked against VIEWSCOPEMAP.
 - `BATCH_INVITE_PERSONS_MAX` — Cap on one batch.
 - `BATCH_INVITE_SKIP_REASONS` — Why one person in a batch did not receive an invite. - `already-member` — holds an account in this org…
 - `BatchInviteRequest` _(type)_
@@ -42,11 +45,74 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `BatchInviteResponseSchema`
 - `BatchInviteSkipReason` _(type)_
 - `BatchInviteSkipReasonSchema`
+- `COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES` — Cap on the MATERIALIZED document text, in UTF-8 bytes of the expanded result.
+- `COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS` — Cap on ONE presence position blob (`anchor` or `head`), in base64 chars.
+- `COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS` — Cap on ONE encoded update, measured on the base64 payload as it is sent.
+- `COMPANY_MD_COLLAB_PRESENCE_HEARTBEAT_MS` — The cadence clients must re-POST presence at.
+- `COMPANY_MD_COLLAB_PRESENCE_TTL_MS` — How long the server keeps a presence entry alive with no fresh signal.
+- `COMPANY_MD_COLLAB_TEXT_KEY` — The Y.Doc root key holding the document body — a CONTRACT, not a detail.
+- `CanonicalFacts` _(type)_
+- `CanonicalFactsSchema` — The full normalized batch an external-source adapter emits in one pass: every person, org unit, position…
+- `CanonicalOccupancy` _(type)_
+- `CanonicalOccupancySchema` — An occupancy (a person holds a seat) as reported by an external source.
+- `CanonicalOrgUnit` _(type)_
+- `CanonicalOrgUnitSchema` — An org unit as reported by an external source.
+- `CanonicalPerson` _(type)_
+- `CanonicalPersonSchema` — A person as reported by an external source, keyed by external identity.
+- `CanonicalPosition` _(type)_
+- `CanonicalPositionSchema` — A position (seat) as reported by an external source, placed in a unit by external reference…
+- `CanonicalPositionStatus` _(type)_
+- `CanonicalPositionStatusSchema` — Seat-existence as the SOURCE reported it.
+- `CanonicalReportingEdge` _(type)_
+- `CanonicalReportingEdgeSchema` — A reporting edge (a seat reports to a manager seat) as reported by an external source.
+- `CanonicalUnresolvedManager` _(type)_
+- `CanonicalUnresolvedManagerResolution` _(type)_
+- `CanonicalUnresolvedManagerResolutionSchema` — Why a supervisory reference could not be resolved to a seat in this batch.
+- `CanonicalUnresolvedManagerSchema` — A supervisory reference the source reported that we could NOT resolve to a seat in this batch.
 - `CapabilitiesResponse` _(type)_
 - `CapabilitiesResponseSchema` — The single validated capability surface the UI reads.
 - `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.
+- `CompanyMdCollabAccessRevokedEvent` _(type)_
+- `CompanyMdCollabAccessRevokedEventSchema` — `event: access-revoked` — the actor's read grant went away mid-stream.
+- `CompanyMdCollabConnectedEvent` _(type)_
+- `CompanyMdCollabConnectedEventSchema` — `event: connected` — the stream is open.
+- `CompanyMdCollabPresenceEvent` _(type)_
+- `CompanyMdCollabPresenceEventSchema` — `event: collab-presence` — one participant's presence signal, either live or replayed from the roster right…
+- `CompanyMdCollabResetEvent` _(type)_
+- `CompanyMdCollabResetEventSchema` — `event: collab-reset` — the client's cursor was unusable (a superseded generation, older than what compaction…
+- `CompanyMdCollabServerDrainEvent` _(type)_
+- `CompanyMdCollabServerDrainEventSchema` — `event: server_drain` — the server is shutting the stream down deliberately (a rolling restart, not a…
+- `CompanyMdCollabSseEvent` _(type)_
+- `CompanyMdCollabSseEventSchema` — Every frame the collaboration stream emits, discriminated on the `type` the client stamps from the SSE…
+- `CompanyMdCollabSyncLimits` _(type)_
+- `CompanyMdCollabSyncLimitsSchema` — Protocol limits the client needs BEFORE it sends anything.
+- `CompanyMdCollabSyncResponse` _(type)_
+- `CompanyMdCollabSyncResponseSchema` — `GET /collab/sync` response body — merged collaboration state plus the cursor the stream resumes from.
+- `CompanyMdCollabUpdateAccepted` _(type)_
+- `CompanyMdCollabUpdateAcceptedSchema` — `POST /collab/updates` response body.
+- `CompanyMdCollabUpdateEvent` _(type)_
+- `CompanyMdCollabUpdateEventSchema` — `event: collab-update` — one durable collaboration update.
+- `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)_
+- `CompanyMdDocKind` _(type)_ — Structural discriminator for a Company.md document. - `'root'`: the single org-wide doc (one per org). -…
+- `CompanyMdDocLevel` _(type)_
+- `CompanyMdDocRelations` _(type)_
+- `CompanyMdNodeIdentity` _(type)_
+- `CompanyMdNodeType` _(type)_ — Semantic node type used by the Company.md tree.
+- `CompanyMdSource` _(type)_
+- `CompanyMdTreeNode` _(type)_
+- `CompanyMdVisibility` _(type)_ — Visibility band for a Company.md document — the canonical AUTH `entity_visibility` vocabulary (, backend ). -…
+- `ConflictRecord` _(type)_
+- `ConflictRecordSchema`
+- `ConstraintViolation` _(type)_
+- `ConstraintViolationSchema` — One constraint the transformation engine evaluated and found violated.
 - `CreateDelegationRequest` _(type)_
 - `CreateDelegationRequestSchema`
 - `CreateInviteBatchRequest` _(type)_
@@ -60,15 +126,38 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `DelegationListResponse` _(type)_
 - `DelegationListResponseSchema`
 - `DelegationSchema`
+- `DismissStructureFindingRequest` _(type)_
+- `DismissStructureFindingRequestSchema`
 - `DomainListResponse` _(type)_
 - `DomainListResponseSchema`
 - `DomainResponse` _(type)_
 - `DomainResponseSchema`
+- `DomainStatus` _(type)_ — Status of a domain claim within an organization. - 'pending': Domain claimed but not yet verified -…
+- `DomainVerificationMethod` _(type)_ — Method used to verify domain ownership. - 'dnstxt': DNS TXT record verification (primary method) - 'email'…
+- `ExecutionContext` _(type)_
+- `ExecutionContextSchema` — ExecutionContext — the RUN in which an intent was produced or applied.
 - `ExecutionScope` _(type)_ — Execution scope determines whose identity is used when executing actions. - 'self': Actions execute under the…
+- `ExistingPlacementFact` _(type)_
+- `ExistingPlacementFactSchema` — Where a person already sits, and on whose authority they sit there.
+- `ExistingUnitFact` _(type)_
+- `ExistingUnitFactSchema` — An org unit that already exists, with the license the engine has over it.
+- `FACT_SOURCE_TIER_PRECEDENCE` — Truth hierarchy, highest precedence first.
+- `FactMutation` _(type)_
+- `FactMutationSchema` — A single atomic fact change the engine applies to the live org graph.
+- `FactProvenance` _(type)_
+- `FactProvenanceSchema` — Provenance envelope attached to a structural fact (reporting edge, org unit, membership, home assignment).
+- `FactSourceTier` _(type)_
+- `FactSourceTierSchema` — The precedence axis for a fact.
 - `FieldCapability` _(type)_
 - `FieldCapabilitySchema` — A mutable field's gate: editable, or locked with attribution (sso vs rbac).
 - `FillOpenRoleRequest` _(type)_
 - `FillOpenRoleRequestSchema` — Fill an open role by seating an existing org member (`userId`) or inviting a new person by email.
+- `Finding` _(type)_
+- `FindingSchema` — A single diagnostic the system emits about the org graph — the GENERAL model of which {@link…
+- `FindingSeverity` _(type)_
+- `FindingSeveritySchema` — Severity of a {@link FindingSchema}.
+- `HomeAssignment` _(type)_
+- `HomeAssignmentSchema` — A person's single structural home unit — at most one per person per org.
 - `HomeUnitRole` _(type)_
 - `HomeUnitRoleSchema` — Role the invitee takes in their home unit on acceptance.
 - `IDENTITY_TRUST_LEVEL_LABELS`
@@ -105,8 +194,14 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `MemberRecentAction` _(type)_ — Recent audit action attached to a member-detail response.
 - `MissingAtNextLevel` _(type)_
 - `MissingAtNextLevelSchema` — Active users home directly at this unit who have no level-(depth+1) home assignment within its subtree.
+- `ORG_SHARED_TRANSITION_TRIGGERS` — WHY an org stopped being personal.
+- `ORG_UNITS_ROUTES` — Canonical route path constants for the `/api/org-units` surface.
 - `ORG_UNIT_ABSOLUTE_MAX_DEPTH` — Hard ceiling mirrored by the `org_units_depth_max` CHECK; ingest-only past designed.
 - `ORG_UNIT_DESIGNED_MAX_DEPTH` — Depth a human may build from scratch; the UI ceiling for a fresh org.
+- `Occupancy` _(type)_
+- `OccupancySchema`
+- `OccupancyStatus` _(type)_
+- `OccupancyStatusSchema` — Lifecycle of a single occupancy of a position.
 - `OidcValidationResult` _(type)_ — Result of validating an OIDC discovery URL.
 - `OidcValidationResultDto` _(type)_ — Result of validating an OIDC discovery URL.
 - `OidcValidationResultSchema`
@@ -116,6 +211,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OpenRoleResponse` _(type)_
 - `OpenRoleResponseSchema`
 - `OpenRoleSchema` — An open role — a persisted placeholder for the person who will sit in a unit.
+- `OpenRoleStatus` _(type)_ — Hiring lifecycle of an open role — a persisted placeholder for the person who will sit in an org unit (PRD…
 - `OpenRoleStatusSchema` — Hiring lifecycle of an open role.
 - `OrgAuthPolicy` _(type)_ — Organization authentication policy.
 - `OrgAuthPolicyDto` _(type)_ — Organization authentication policy.
@@ -126,6 +222,13 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OrgDirectoryPersonSchema`
 - `OrgDirectoryResponse` _(type)_
 - `OrgDirectoryResponseSchema`
+- `OrgDivergence` _(type)_
+- `OrgDivergenceResolution` _(type)_
+- `OrgDivergenceResolutionSchema` — What resolving a divergence means today.
+- `OrgDivergenceSchema`
+- `OrgDomain` _(type)_ — Organization domain claim and verification status.
+- `OrgIntent` _(type)_
+- `OrgIntentSchema` — A requested org-graph change expressed as intent.
 - `OrgInvite` _(type)_ — Organization invite for the workspace invites list.
 - `OrgInviteStatus` _(type)_ — Status of an organization invite.
 - `OrgLevelConfig` _(type)_
@@ -138,20 +241,26 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OrgLogosSchema` — An org's stored marks.
 - `OrgOwnerIcon` _(type)_
 - `OrgOwnerIconSchema` — Icon options for the `owner` org-chart role.
+- `OrgReconciliationLedger` _(type)_
+- `OrgReconciliationLedgerSchema`
 - `OrgScopedContext` _(type)_ — Validated organization-scoped context for policy implementations.
+- `OrgSharedTransitionTrigger` _(type)_
 - `OrgSystemEventsList` _(type)_
 - `OrgSystemEventsListSchema`
+- `OrgTreeResponse` _(type)_
 - `OrgType` _(type)_ — Organization type distinguishes personal workspaces from shared organizations. - 'personal': Single-user…
 - `OrgUnit` _(type)_
 - `OrgUnitAncestorsResponse` _(type)_
 - `OrgUnitAncestorsResponseSchema`
 - `OrgUnitChildrenResponse` _(type)_
 - `OrgUnitChildrenResponseSchema`
+- `OrgUnitClassification` _(type)_ — Semantic classification — projection-only, never drives traversal.
 - `OrgUnitClassificationSchema`
 - `OrgUnitDescendantsResponse` _(type)_
 - `OrgUnitDescendantsResponseSchema`
 - `OrgUnitDesignation` _(type)_
 - `OrgUnitDesignationSchema` — Designation a member holds over a unit they manage.
+- `OrgUnitErrorCode` _(type)_ — Error codes returned by `POST /api/org-units/:id/reparent` and related mutation endpoints.
 - `OrgUnitErrorCodeSchema`
 - `OrgUnitMembership` _(type)_
 - `OrgUnitMembershipListResponse` _(type)_
@@ -159,7 +268,9 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OrgUnitMembershipResponse` _(type)_
 - `OrgUnitMembershipResponseSchema`
 - `OrgUnitMembershipSchema`
+- `OrgUnitMembershipSource` _(type)_ — External directory origin of a membership row.
 - `OrgUnitMembershipSourceSchema`
+- `OrgUnitMembershipStatus` _(type)_ — Active/pending/removed lifecycle for a unit membership.
 - `OrgUnitMembershipStatusSchema`
 - `OrgUnitOwner` _(type)_
 - `OrgUnitOwnerSchema`
@@ -168,19 +279,23 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OrgUnitPermissionsEntry` _(type)_
 - `OrgUnitPermissionsEntrySchema` — Effective manager of an org unit — a user whose membership (direct or inherited from an ancestor) grants the…
 - `OrgUnitRelationship` _(type)_
+- `OrgUnitRelationshipRole` _(type)_ — Edge role — refines the collaboration nature on a graph edge.
 - `OrgUnitRelationshipRoleSchema`
 - `OrgUnitRelationshipSchema`
+- `OrgUnitRelationshipType` _(type)_ — Edge classification for `org_unit_relationships`.
 - `OrgUnitRelationshipTypeSchema`
 - `OrgUnitRelationshipsResponse` _(type)_
 - `OrgUnitRelationshipsResponseSchema`
 - `OrgUnitResponse` _(type)_
 - `OrgUnitResponseSchema`
 - `OrgUnitSchema`
+- `OrgUnitSyncMode` _(type)_ — External directory reconciliation policy for a unit.
 - `OrgUnitSyncModeSchema`
 - `OrgUnitTreeNode` _(type)_
 - `OrgUnitTreeNodeSchema`
 - `OrgUnitTreeResponse` _(type)_
 - `OrgUnitTreeResponseSchema`
+- `OrgUnitVisibility` _(type)_ — Default visibility inherited by new docs under this unit.
 - `OrgUnitVisibilitySchema`
 - `OrgUsageResponse` _(type)_
 - `OrgUsageResponseSchema`
@@ -196,25 +311,62 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OwnershipTransferStatus` _(type)_ — Status of pending ownership transfer for an organization.
 - `PendingUnitOwner` _(type)_
 - `PendingUnitOwnerSchema` — A lead the structure review chose who is NOT YET an owner, because they have no account to grant to.
+- `PermissionAuditEntry` _(type)_ — Single entry in the permission change audit log.
+- `PersonStructureOutcome` _(type)_
+- `PersonStructureOutcomeSchema` — EXACTLY ONE outcome per person in the snapshot. "Zero or one placement" would accept a proposal that simply…
 - `Phase3AuditAction` _(type)_ — Audit actions for Phase 3 workspace expansion features.
+- `Phase4AuditAction` _(type)_ — Audit actions for Phase 4 enterprise identity features.
+- `Position` _(type)_
+- `PositionReporting` _(type)_
+- `PositionReportingRelationshipType` _(type)_
+- `PositionReportingRelationshipTypeSchema` — The kind of reporting line.
+- `PositionReportingSchema`
+- `PositionSchema`
+- `PositionStatus` _(type)_
+- `PositionStatusSchema` — Lifecycle of a seat's EXISTENCE — distinct from a hiring pipeline.
+- `ProposedOrgUnit` _(type)_
+- `ProposedOrgUnitSchema` — A unit the proposal wants the org to have.
+- `Provenance` _(type)_
+- `ProvenanceSchema` — Provenance — WHO/WHAT generated an intent.
 - `ProviderStatus` _(type)_ — Provider-level configuration lifecycle.
 - `ProviderSuggestion` _(type)_ — MX-based provider suggestion for SSO setup.
+- `Recommendation` _(type)_
+- `RecommendationSchema`
 - `RemoveMemberRequest` _(type)_ — Request payload for removing a member from the workspace.
 - `RemoveMemberResponse` _(type)_
 - `RemoveMemberResponseSchema`
+- `ReportingEdgeProvenance` _(type)_
+- `ReportingEdgeProvenanceSchema` — The provenance of a reporting edge a change would supersede, as the operator must see it before confirming…
+- `ReportingErrorCode` _(type)_
+- `ReportingErrorCodeSchema` — Structured codes for reporting-line mutation rejections, surfaced as `ErrorResponse.meta.reportingCode` by…
+- `ReportingLineAnomalyFacts` _(type)_
+- `ReportingLineAnomalyFactsSchema`
+- `ReportingLineAnomalyReport` _(type)_
+- `ReportingLineAnomalyReportSchema` — One report parked on the pivot, and who actually leads their department.
+- `ResolveOrgDivergenceResult` _(type)_
+- `ResolveOrgDivergenceResultSchema`
 - `RoleCatalogEntry` _(type)_ — Entry in the RBAC roles catalog (GET /api/rbac/roles).
 - `RoleCatalogEntrySchema`
 - `RoleCatalogResponseSchema`
+- `STRUCTURE_FINDING_KINDS`
+- `STRUCTURE_FINDING_STATUSES`
+- `STRUCTURE_REVIEW_ITEM_KINDS` — A question the engine is asking a human, with the competing signals attached.
 - `ScopeCheckBatchResponse` _(type)_
 - `ScopeCheckBatchResponseSchema`
 - `ScopeCheckResponse` _(type)_
 - `ScopeCheckResponseSchema`
+- `SelectionRationale` _(type)_
+- `SelectionRationaleSchema`
 - `SendInviteBatchRequest` _(type)_
 - `SendInviteBatchRequestSchema` — `expectedRevision` is REQUIRED and has no default.
 - `SetActiveOrgResponse` _(type)_
 - `SetActiveOrgResponseSchema`
 - `SetSeatManagerResponse` _(type)_
 - `SetSeatManagerResponseSchema` — Response for the one idempotent set-or-clear of a seat's solid-line manager — the reporting edge the org…
+- `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)_
+- `SourceAuthoritySchema`
 - `SsoCredentialStatus` _(type)_ — Boolean credential presence indicators (never expose actual values).
 - `SsoDiscoveryConfig` _(type)_ — OIDC discovery configuration for the SSO provider.
 - `SsoEnforcementStatus` _(type)_ — SSO enforcement status for the workspace.
@@ -225,8 +377,51 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `SsoStepperStep` _(type)_ — Backend-authoritative stepper step.
 - `StagedPlacement` _(type)_ — Staged member placement: the fuller org position an invitee is slotted into, applied as deferred grants when…
 - `StagedPlacementSchema` — Staged member placement: the fuller org position an invitee is slotted into, applied as deferred grants when…
+- `StructureAcceptedBy` _(type)_
+- `StructureAcceptedBySchema` — WHO accepted the fact.
+- `StructureAuthority` _(type)_
+- `StructureAuthoritySchema` — The authority axis — the ONLY axis precedence runs on: `human_confirmed` `ai_inferred` `hris_source`.
+- `StructureEvidence` _(type)_
+- `StructureEvidenceSchema` — TYPED evidence.
+- `StructureFinding` _(type)_
+- `StructureFindingDismissal` _(type)_
+- `StructureFindingDismissalSchema` — Who said a finding is intentional, when, and about which content.
+- `StructureFindingKind` _(type)_
+- `StructureFindingKindSchema`
+- `StructureFindingListResponse` _(type)_
+- `StructureFindingListResponseSchema`
+- `StructureFindingListStatus` _(type)_
+- `StructureFindingListStatusSchema` — Which findings a list read returns.
+- `StructureFindingResponse` _(type)_
+- `StructureFindingResponseSchema`
+- `StructureFindingSchema`
+- `StructureFindingStatus` _(type)_
+- `StructureFindingStatusSchema`
+- `StructureInferenceSnapshot` _(type)_
+- `StructureInferenceSnapshotSchema` — The inference INPUT: a point-in-time view of the PERSISTED canonical graph.
+- `StructurePersonFact` _(type)_
+- `StructurePersonFactSchema` — A person as the inference engine sees them.
+- `StructureProposal` _(type)_
+- `StructureProposalOrigin` _(type)_
+- `StructureProposalOriginSchema` — How a structural fact came to be PROPOSED.
+- `StructureProposalSchema` — A proposed desired state for one org.
+- `StructureProvenance` _(type)_
+- `StructureProvenanceSchema` — The three axes together, as one accepted structural fact records them. - v1 — AI proposes, an admin clicks…
+- `StructureReportingFact` _(type)_
+- `StructureReportingFactSchema` — One reporting edge, at person granularity.
+- `StructureReviewItem` _(type)_
+- `StructureReviewItemSchema` — A review item IS a {@link DecisionQuestion}, plus the addressing that says what the question is about.
+- `StructureUnitAuthority` _(type)_
+- `StructureUnitAuthoritySchema` — How much license the engine has over an EXISTING unit or placement.
 - `SubmitInteractiveTaskResponse` _(type)_
 - `SubmitInteractiveTaskResponseSchema` — Response for submitting a filled-in interactive chat task surface (e.g. the editable "change reporting…
+- `SubunitCandidateFacts` _(type)_
+- `SubunitCandidateFactsSchema`
+- `SupersededReportingEdge` _(type)_
+- `SupersededReportingEdgeSchema`
+- `SyncRunSummary` _(type)_
+- `SyncRunSummarySchema`
+- `TOPOLOGY_ONLY_EVIDENCE_KINDS` — Evidence kinds that alone are NOT sufficient to justify a unit boundary.
 - `TRANSFER_RESPONSIBILITIES` — Responsibility checklist items shown on the acceptance page.
 - `TestSsoInitiation` _(type)_ — Initiation payload for a test SSO login attempt.
 - `TestSsoInitiationDto` _(type)_ — Initiation payload for a test SSO login attempt.
@@ -240,10 +435,20 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `TransferMemberEligibility` _(type)_ — Per-member eligibility for transfer recipient picker
 - `TransferResponsibility` _(type)_
 - `TransferStatusResponse` _(type)_ — Response for transfer status queries — extends existing OwnershipTransferStatus.
+- `TransformStrategy` _(type)_
+- `TransformStrategySchema`
+- `TransformationOrigin` _(type)_
+- `TransformationOriginSchema` — Where a transformation originated.
+- `TransformationPreview` _(type)_
+- `TransformationPreviewSchema`
+- `TransformationRequest` _(type)_
+- `TransformationRequestSchema`
+- `TreeOrderableNode` _(type)_ — Canonical per-parent sibling ordering for OrgUnit trees.
 - `UnitLeadCleared` _(type)_
 - `UnitLeadClearedSchema` — "No lead for now": the latest `unit_head` review answer for the unit was an explicit clear, and no later…
 - `UnitMembershipRole` _(type)_
 - `UnitMembershipRoleSchema` — Positional slot a member holds in the org-unit tree.
+- `UnitRouteLevel` _(type)_ — One level of the org's chart as the route needs it: `OrgLevelConfig` satisfies this, and so does a plainer `{…
 - `UpdateAuthPolicyRequest` _(type)_ — Request payload for updating organization auth policy.
 - `UpdateDelegationRequest` _(type)_
 - `UpdateDelegationRequestSchema` — Change a delegation's expiry without revoking it: extend, shorten, or clear (set `expiresAt: null` to make it…
@@ -258,6 +463,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `UserOrgMembership` _(type)_ — User organization membership summary.
 - `UserOrgsResponse` _(type)_
 - `UserOrgsResponseSchema`
+- `VIEW_SCOPE_MAP` — View-to-scope mapping for frontend authorization. - Views with string values require that scope for access -…
 - `WorkspaceAccessResponse` _(type)_
 - `WorkspaceAccessResponseSchema`
 - `WorkspaceAuditEvent` _(type)_ — Audit event for the workspace audit log.
@@ -287,6 +493,12 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `WorkspaceSettingsOverview` _(type)_ — Full workspace overview for the Settings surface.
 - `WorkspaceSsoState` _(type)_ — Workspace SSO state derived from provider status + policy.
 - `WorkspaceSurface` _(type)_ — Discriminator for workspace surface routing. - 'info': Read-only surface, any member, org.view capabilities -…
+- `getViewScope` — Get the required scope for a view, or null if public.
+- `levelSlugForDepth` — The level segment for a depth: the configured label slugified, else `level-<depth>`.
+- `mayOverrideAuthority` — True when `incoming` may overwrite a fact currently held at `existing`.
+- `orderTreeNodes`
+- `slugifyLevelLabel` — A level label's URL form: lowercased, runs of non-alphanumerics collapsed to one hyphen, hyphens trimmed.
+- `unitRouteSegments` — The route segments one unit contributes at its depth: `[]` at the root, `[levelSlug, unitSlug]` below it.
 
 <!-- END GENERATED: readme-public-api -->
 

package/src/quality/README.md

@@ -0,0 +1,36 @@
+# quality/
+
+## Purpose
+
+The shared vocabulary of the quality control plane (control ADR slug
+quality-control-plane, INV-QC-*): the closed sets backend and app use for
+artifacts, cases, evaluation state, decisions, actions and references, plus the
+QualityRunReport wire shape a runner hands to ingest. Placement and rules are
+recorded in ADR-CONTRACTS-212.
+
+## Invariants
+
+- Closed sets only. Every tuple in `vocabulary.ts` is the complete list of legal
+  values; it is append-only, and adding a member is a MINOR release.
+- State and judgment are disjoint (INV-QC-13): `EVALUATION_STATES` and
+  `PROMOTION_OUTCOMES` are disjoint closed sets and share no member.
+- Quality run reports carry ids, scores and failure kinds only, never free text.
+  `QualityRunReportSchema` rejects any string over 128 chars outside the id
+  fields (top-level `gitSha`, `runId`, `planId`, `manifestId` and
+  `caseResults[i].caseId`); a report smuggling text fails to parse and is never
+  truncated.
+- Types and zod schemas only — no policy evaluation or scoring lives here.
+
+## Public API
+
+- `index.ts` — the domain barrel; reached only through the package root
+  re-export (no `./quality` subpath in `package.json`).
+- `vocabulary.ts` — for each closed set, the `as const` tuple
+  (e.g. `EVALUATION_STATES`), its derived type (`EvaluationState`) and its zod
+  schema (`EvaluationStateSchema`).
+- `run-report.ts` — `QualityRunReportSchema`, `QualityCaseResultSchema` and the
+  `QualityRunReport` type.
+
+## Dependencies
+
+`zod`.