@wildo-ai/saas-models 1.1.5 → 1.1.7

package/dist/esm/organizations/service-provider-relationships.shared.schemas.js

@@ -0,0 +1,869 @@
+/**
+ * Service-provider relationships — a service firm's experts working inside CLIENT organizations,
+ * under a relationship the client declares, controls and can end on the next request.
+ *
+ * ## The shape (#1597)
+ *
+ * An AI-native service company is a firm whose experts work inside every client's tenant every day.
+ * Platform access grants cannot carry that: they are break-glass by design (time-boxed, justified,
+ * operator-only), and making them standing would be the standing privilege the zero-standing-privilege
+ * decision removed. So the firm↔client link is its own, customer-controlled relationship:
+ *
+ * | resource | lives in | written by |
+ * |---|---|---|
+ * | `SERVICE_PROVIDER_RELATIONSHIPS` | the CLIENT organization | the client's verbs; the firm's verbs through the mirror |
+ * | `SERVICE_ENGAGEMENTS` | the PROVIDER organization | system-written beside every relationship transition — the firm's view |
+ * | `SERVICE_ENGAGEMENT_ASSIGNMENTS` | the PROVIDER organization | the firm's administrators: which experts serve which client |
+ *
+ * An assigned expert receives a REAL membership in the client organization, marked with the
+ * relationship (`serviceProviderRelationshipId`, `providerOrganizationId`). The membership is what the
+ * rest of the framework already understands; the relationship is what decides whether it confers
+ * anything, re-checked on every request by the execution-context builder (the "live filter").
+ *
+ * ## Each side acts only inside its own tenant
+ *
+ * The client's verbs are on the relationship (client scope); the firm's verbs (`propose`, `accept` of a
+ * client's proposal, `withdraw`) are on the engagement (firm scope). The counterpart row is written by
+ * the system in the same transaction. Neither side ever reaches into the other's tenant through a
+ * request, so no cross-tenant admission exists here at all — that door belongs to platform operators.
+ */
+import { z } from 'zod';
+import { addImpersonalizeWith } from '@wildo-ai/zod-decorators';
+import { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas.js';
+import { RedactionType } from '../compliance/privacy/redaction.shared.schemas.js';
+import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
+import { AUTONOMOUS_AGENT_REFS_PER_CLIENT_MAX, AutonomousAgentRefSchema } from '../flows-actors/autonomous-agents.shared.schemas.js';
+import { ServiceProviderActivityFeedDisclosure, ServiceProviderMfaTrust } from './service-provider-client-controls.shared.schemas.js';
+import { HumanDecision_Outcome, HumanDecision_ResponseIntent, HumanDecision_RouteKind, ReviewClockBasis, ReviewDeadlineStage, ReviewEscalationActionKind, } from '../flows-actors/human-decision.shared.schemas.js';
+import { armReviewDeadlines, dueReviewDeadlineStages, nextReviewDeadlineDueAt, resolveReviewDeadlinePolicy, reviewDeadlinesDeclarationIssues, } from '../flows-actors/review-deadlines.shared.schemas.js';
+import { CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas.js';
+import { ServiceEngagementDelegatedCapabilitySchema, isDelegatedCapabilityRole } from './service-provider-capability-grants.shared.schemas.js';
+/** @wildo_source:part:start saas.models.organizations.service-provider-relationships facet:layer:shared facet:audience:app-developer */
+/**
+ * Where a service-provider relationship stands. One member per distinct claim, so the record says WHO
+ * ended it and HOW.
+ *
+ * Only {@link ServiceProviderRelationshipStatus.ACTIVE} confers anything, and even then only while
+ * `endsAt` is absent or in the future — {@link isServiceProviderRelationshipConferring} is the one
+ * predicate, and it reads `endsAt` itself rather than trusting {@link EXPIRED}.
+ */
+export var ServiceProviderRelationshipStatus;
+(function (ServiceProviderRelationshipStatus) {
+    /** Proposed by one side, awaiting the other. Confers nothing. */
+    ServiceProviderRelationshipStatus["PROPOSED"] = "PROPOSED";
+    /** Accepted by the non-proposing side. Confers, subject to the live filter. */
+    ServiceProviderRelationshipStatus["ACTIVE"] = "ACTIVE";
+    /** Paused by the client. Confers nothing; `resume` returns it to ACTIVE. */
+    ServiceProviderRelationshipStatus["SUSPENDED"] = "SUSPENDED";
+    /** The client refused the firm's proposal. Terminal. */
+    ServiceProviderRelationshipStatus["DECLINED"] = "DECLINED";
+    /**
+     * The firm ended it (or withdrew its proposal) — or the firm's ORGANIZATION was deleted (the purge after its retention
+     * window, or an operator's immediate delete), which ends every relationship it serves the same way. Terminal.
+     */
+    ServiceProviderRelationshipStatus["WITHDRAWN"] = "WITHDRAWN";
+    /**
+     * The client ended it — or the client's ORGANIZATION was deleted (the purge, or an operator's immediate delete), which
+     * ends every relationship it holds the same way. Terminal.
+     */
+    ServiceProviderRelationshipStatus["TERMINATED"] = "TERMINATED";
+    /** The sweep relabelled it after `endsAt`. Terminal bookkeeping — admission never reads this label. */
+    ServiceProviderRelationshipStatus["EXPIRED"] = "EXPIRED";
+})(ServiceProviderRelationshipStatus || (ServiceProviderRelationshipStatus = {}));
+/** Statuses from which a relationship can still move — at most one of these per (provider, client). */
+export const SERVICE_PROVIDER_RELATIONSHIP_LIVE_STATUSES = [
+    ServiceProviderRelationshipStatus.PROPOSED,
+    ServiceProviderRelationshipStatus.ACTIVE,
+    ServiceProviderRelationshipStatus.SUSPENDED,
+];
+/** Statuses that end a relationship for good. Reaching one ends every assignment and provider membership. */
+export const SERVICE_PROVIDER_RELATIONSHIP_TERMINAL_STATUSES = [
+    ServiceProviderRelationshipStatus.DECLINED,
+    ServiceProviderRelationshipStatus.WITHDRAWN,
+    ServiceProviderRelationshipStatus.TERMINATED,
+    ServiceProviderRelationshipStatus.EXPIRED,
+];
+/** One lifecycle audit row per transition, written to BOTH organizations' trails. */
+export var ServiceProviderRelationshipTransition;
+(function (ServiceProviderRelationshipTransition) {
+    ServiceProviderRelationshipTransition["PROPOSED"] = "PROPOSED";
+    ServiceProviderRelationshipTransition["ACCEPTED"] = "ACCEPTED";
+    ServiceProviderRelationshipTransition["DECLINED"] = "DECLINED";
+    ServiceProviderRelationshipTransition["SUSPENDED"] = "SUSPENDED";
+    ServiceProviderRelationshipTransition["RESUMED"] = "RESUMED";
+    ServiceProviderRelationshipTransition["SCOPE_AMENDED"] = "SCOPE_AMENDED";
+    ServiceProviderRelationshipTransition["TERMINATED"] = "TERMINATED";
+    ServiceProviderRelationshipTransition["WITHDRAWN"] = "WITHDRAWN";
+    ServiceProviderRelationshipTransition["EXPIRED"] = "EXPIRED";
+    /**
+     * The client changed how the firm's experts are admitted (#1612) — see
+     * {@link ServiceProviderExpertAdmissionPolicy}. Not retroactive: experts already admitted stay admitted.
+     */
+    ServiceProviderRelationshipTransition["EXPERT_ADMISSION_POLICY_CHANGED"] = "EXPERT_ADMISSION_POLICY_CHANGED";
+})(ServiceProviderRelationshipTransition || (ServiceProviderRelationshipTransition = {}));
+/**
+ * How the firm's assigned experts are admitted into the CLIENT organization under one relationship (#1612).
+ *
+ * The CLIENT's choice, stored on the relationship it controls: set when the client proposes or accepts, and
+ * changed later only by a client administrator. The firm can never set or change it. An application may
+ * declare the default a client organization type starts from (`acceptsServiceProviders.defaultExpertAdmissionPolicy`),
+ * and the relationship's own value always wins.
+ *
+ * A change is NOT retroactive: experts already admitted stay admitted, and the client removes anyone through
+ * the ordinary member verbs.
+ */
+export var ServiceProviderExpertAdmissionPolicy;
+(function (ServiceProviderExpertAdmissionPolicy) {
+    /** The relationship admits every expert the firm assigns (the #1597 behaviour, and the default). */
+    ServiceProviderExpertAdmissionPolicy["RELATIONSHIP_APPROVES_ASSIGNED_EXPERTS"] = "RELATIONSHIP_APPROVES_ASSIGNED_EXPERTS";
+    /**
+     * Each assigned expert waits for the client's own approval — a human decision routed to the client's
+     * administrators — and receives no membership until a client administrator approves them.
+     */
+    ServiceProviderExpertAdmissionPolicy["CLIENT_APPROVES_EACH_EXPERT"] = "CLIENT_APPROVES_EACH_EXPERT";
+})(ServiceProviderExpertAdmissionPolicy || (ServiceProviderExpertAdmissionPolicy = {}));
+/** Whether a firm's expert currently serves an engagement. */
+export var ServiceEngagementAssignmentStatus;
+(function (ServiceEngagementAssignmentStatus) {
+    /** Designated by the firm; the expert holds a provider membership in the client organization. */
+    ServiceEngagementAssignmentStatus["ACTIVE"] = "ACTIVE";
+    /**
+     * Unassigned, ended with the relationship, or withdrawn while still awaiting the client's approval. The
+     * client membership (when one was ever created) is INACTIVE; the row is evidence.
+     */
+    ServiceEngagementAssignmentStatus["ENDED"] = "ENDED";
+    /**
+     * The firm assigned the expert under a relationship whose client approves each expert (#1612), and the
+     * client has not answered yet. Confers NOTHING by construction: no membership row exists in the client,
+     * so there is no role entry, nothing in any membership consumer, and no (person, client) slot taken.
+     */
+    ServiceEngagementAssignmentStatus["PENDING_CLIENT_APPROVAL"] = "PENDING_CLIENT_APPROVAL";
+    /**
+     * The client refused the expert — or approved, but the relationship, the expert's firm membership or the
+     * (person, client) slot no longer allowed admission when the approval was applied. Nothing was created.
+     * Terminal; `approvalDenialReason` says which.
+     */
+    ServiceEngagementAssignmentStatus["DENIED"] = "DENIED";
+    /** Nobody in the client answered before the approval's lapse (decision deadlines, #1628). Nothing was created. Terminal. */
+    ServiceEngagementAssignmentStatus["LAPSED"] = "LAPSED";
+})(ServiceEngagementAssignmentStatus || (ServiceEngagementAssignmentStatus = {}));
+/** Assignment statuses that still hold, or still wait for, a place in the client — the ones a second assignment collides with. */
+export const SERVICE_ENGAGEMENT_ASSIGNMENT_LIVE_STATUSES = [
+    ServiceEngagementAssignmentStatus.ACTIVE,
+    ServiceEngagementAssignmentStatus.PENDING_CLIENT_APPROVAL,
+];
+/**
+ * Why a per-expert approval ended without admitting the expert (#1612). Recorded on the assignment the firm
+ * reads, so it names a FACT the firm may know — never the client administrator who answered.
+ */
+export var ServiceProviderExpertApprovalDenialReason;
+(function (ServiceProviderExpertApprovalDenialReason) {
+    /** A client administrator refused the expert. */
+    ServiceProviderExpertApprovalDenialReason["REFUSED_BY_CLIENT"] = "REFUSED_BY_CLIENT";
+    /** The client approved, but the relationship no longer confers (ended, suspended, or past its term). */
+    ServiceProviderExpertApprovalDenialReason["RELATIONSHIP_NO_LONGER_CONFERS"] = "RELATIONSHIP_NO_LONGER_CONFERS";
+    /** The client approved, but the expert is no longer an active, ordinary member of the firm, or the firm no longer confers authority. */
+    ServiceProviderExpertApprovalDenialReason["EXPERT_NO_LONGER_ELIGIBLE"] = "EXPERT_NO_LONGER_ELIGIBLE";
+    /** The client approved, but the person meanwhile holds another membership in the client (their own, a suspended one, or another firm's). */
+    ServiceProviderExpertApprovalDenialReason["CONFLICTS_WITH_CLIENT_MEMBERSHIP"] = "CONFLICTS_WITH_CLIENT_MEMBERSHIP";
+})(ServiceProviderExpertApprovalDenialReason || (ServiceProviderExpertApprovalDenialReason = {}));
+/**
+ * The two answers a per-expert approval offers (#1612), in the one answer shape (`HumanDecision_Answer.optionRef`).
+ * APPROVE proceeds (the expert is admitted, re-checked at that moment); REJECT ends the waiting assignment.
+ */
+export var ServiceProviderExpertApprovalOption;
+(function (ServiceProviderExpertApprovalOption) {
+    ServiceProviderExpertApprovalOption["APPROVE"] = "approve";
+    ServiceProviderExpertApprovalOption["REJECT"] = "reject";
+})(ServiceProviderExpertApprovalOption || (ServiceProviderExpertApprovalOption = {}));
+/** @wildo_source:part:end saas.models.organizations.service-provider-relationships */
+/**
+ * Does this relationship confer authority RIGHT NOW?
+ *
+ * The single predicate every consumer uses — the execution-context live filter, machine-client
+ * admission, the client-mailbox domain authorization, and any screen. `endsAt` is read here rather than
+ * trusting the EXPIRED label, so the term ends the moment it elapses with no writer involved: a
+ * relationship whose term passed must stop working whether or not the sweep has run.
+ */
+export function isServiceProviderRelationshipConferring(relationship, now) {
+    if (!relationship)
+        return false;
+    if (relationship.status !== ServiceProviderRelationshipStatus.ACTIVE)
+        return false;
+    if (relationship.endsAt === undefined || relationship.endsAt === null)
+        return true;
+    const endsAt = relationship.endsAt instanceof Date ? relationship.endsAt : new Date(relationship.endsAt);
+    return Number.isFinite(endsAt.getTime()) && endsAt.getTime() > now.getTime();
+}
+/**
+ * Is this membership row a PROVIDER membership — held through a service-provider relationship rather
+ * than as the organization's own member?
+ *
+ * The one definition, used by every membership consumer that must treat the two differently: the owner
+ * floor (never counts), `grantOwnership` (refuses), the generic member UPDATE (roles are owned by the
+ * relationship), SCIM `/Users` (not the client's directory), user-type revocation (grants none), and the
+ * execution-context live filter (confers only through a live relationship).
+ */
+export function isServiceProviderMembership(member) {
+    const row = member;
+    // ANY present marker classifies the row as a provider row — not only a well-formed string. The failure
+    // this rules out is fail-OPEN: a marker of another type (an ObjectId from a direct store write, a number)
+    // read as "ordinary member" would let the row's own `roles` confer authority the relationship never
+    // granted. Classified as a provider row, a malformed one confers nothing: the live filter needs a readable
+    // relationship id and skips it.
+    return isPresentMarker(row?.serviceProviderRelationshipId) || isPresentMarker(row?.providerOrganizationId);
+}
+function isPresentMarker(value) {
+    return value !== undefined && value !== null && value !== '';
+}
+/**
+ * The role entries a LIVE relationship confers on one of its experts (or admitted machine clients) in the
+ * client organization — the pure half of the execution-context live filter, so the emission rule has one
+ * definition that the builder and its tests share.
+ *
+ * - No `organizationUnitIds` ⇒ ONE organization-wide entry.
+ * - `organizationUnitIds` ⇒ one unit-scoped entry per unit and NO organization-wide entry. The expert is
+ *   then a UNIT-ONLY principal, which is the whole of what a unit-scoped relationship means.
+ *
+ * The attribution fields are audit-only (see `ExecutionContext_RoleInfo.viaServiceProviderRelationshipId`).
+ */
+export function buildServiceProviderRoleEntries(relationship, relationshipId, providerOrganizationId, 
+/**
+ * The roles of the relationship's LIVE capability grants (#1631), added beside the relationship's role on its
+ * organization-wide entry. A unit-scoped relationship emits none of them (every capability needs an organization-wide
+ * relationship). The live filter decides which grants are live; this only places them.
+ */
+capabilityRoles = []) {
+    const attribution = { viaServiceProviderRelationshipId: relationshipId, viaProviderOrganizationId: providerOrganizationId };
+    const unitIds = [...new Set((relationship.organizationUnitIds ?? []).filter((unitId) => typeof unitId === 'string' && unitId.length > 0))];
+    if (unitIds.length === 0) {
+        return [{
+                roles: [relationship.role, ...capabilityRoles.filter((role) => role !== relationship.role)],
+                relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS,
+                relatedResourceId: relationship.organizationId,
+                ...attribution,
+            }];
+    }
+    // A unit-scoped relationship carries NO capability role: every capability needs an organization-wide relationship
+    // (`ORGANIZATION_LEVEL_DELEGATED_CAPABILITIES`), so a grant surviving a narrowing confers nothing, by construction.
+    return unitIds.map((organizationUnitId) => ({
+        roles: [relationship.role],
+        relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS,
+        relatedResourceId: relationship.organizationId,
+        organizationUnitId,
+        ...attribution,
+    }));
+}
+/**
+ * The service-provider attribution an audit row written in `organizationId` carries, read from the role
+ * entries the execution-context live filter emitted — THE ONLY reader of `viaServiceProviderRelationshipId`
+ * and `viaProviderOrganizationId` (invariant 18 of #1597): no authority decision may consult them.
+ *
+ * Only an entry for the ROW's organization counts. A firm member acting in their own firm carries no
+ * attribution there even while they hold a live client relationship elsewhere, and a row in the client
+ * organization names the relationship that admitted the principal into it. Every entry the live filter
+ * emits for one relationship carries the same pair, so the first attributed entry is the answer.
+ */
+export function resolveServiceProviderAuditAttribution(initiatorRoles, organizationId) {
+    if (!organizationId || !initiatorRoles)
+        return undefined;
+    const entry = initiatorRoles.find((roleInfo) => roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS
+        && roleInfo.relatedResourceId === organizationId
+        && typeof roleInfo.viaServiceProviderRelationshipId === 'string'
+        && typeof roleInfo.viaProviderOrganizationId === 'string');
+    if (!entry)
+        return undefined;
+    return {
+        actingViaServiceProviderRelationshipId: entry.viaServiceProviderRelationshipId,
+        providerOrganizationId: entry.viaProviderOrganizationId,
+    };
+}
+/** Placeholder written over free text an erasure scrubs; non-empty because `purpose` is required. */
+export const ERASED_SERVICE_PROVIDER_TEXT = '[erased]';
+/**
+ * Free text written by a person at one of the two organizations — why the relationship exists, or why a
+ * side refused or ended it. The surface most likely to name a third party in passing, so it is scrubbed
+ * on erasure while the relationship's structural record (who, which tenants, when, which scope) survives.
+ */
+const purposeField = () => addImpersonalizeWith(z.string().min(1).max(1000).isSummaryField().excludeFromCreate().excludeFromUpdate()
+    .dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.MASK, { maskValue: ERASED_SERVICE_PROVIDER_TEXT });
+const decisionReasonField = () => addImpersonalizeWith(z.string().max(1000).optional().excludeFromCreate().excludeFromUpdate()
+    .dataCategories(PersonalDataCategory.USER_CONTENT), RedactionType.REMOVE);
+/** @wildo_source:part:start saas.models.organizations.service-provider-relationships */
+/**
+ * One admitted client's agents, as the CLIENT organization chose them (#1611). See
+ * `ServiceProviderRelationship.admittedAutonomousAgents`.
+ */
+export const ServiceProviderAdmittedAutonomousAgentsSchema = z.object({
+    oauthClientId: z.string().min(1).describe('The firm\'s machine client this entry is for. It is always one of the relationship\'s `admittedMachineClientIds`.'),
+    autonomousAgentRefs: z
+        .array(AutonomousAgentRefSchema)
+        .max(AUTONOMOUS_AGENT_REFS_PER_CLIENT_MAX)
+        .describe('The agents of that client the client organization lets act inside it. An empty list admits none, even if the firm runs more agents on that client.'),
+});
+/**
+ * Does this relationship let this firm client run this autonomous agent in the client organization (#1611)?
+ * The client's consent only: whether the client is admitted at all, live, and with which role is
+ * `admitServiceProviderMachineClient`'s question, and whether the firm binds the agent to it is the client
+ * row's. The one predicate the principal resolver, the schedule's nomination and the admission audit share.
+ */
+export function serviceProviderAdmitsAutonomousAgent(relationship, oauthClientId, autonomousAgentRef) {
+    if (!relationship || !(relationship.admittedMachineClientIds ?? []).includes(oauthClientId))
+        return false;
+    return (relationship.admittedAutonomousAgents ?? [])
+        .some((entry) => entry.oauthClientId === oauthClientId && entry.autonomousAgentRefs.includes(autonomousAgentRef));
+}
+/**
+ * The relationship, stored in the CLIENT organization — the party that controls it.
+ *
+ * Every field is server-authored. There is no generic CREATE or UPDATE: each field changes only through
+ * the verb that owns its transition, which is what makes the record evidence rather than a form.
+ */
+export const ServiceProviderRelationshipSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    /** The CLIENT organization — the scope anchor, and the only party that can widen or end the relationship. */
+    organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate().isAuditEvidence(),
+    /**
+     * The service FIRM. A plain indexed id, not a foreign key: it names another tenant, and a navigable
+     * edge from one tenant's row into another tenant is exactly what this model refuses to create.
+     */
+    providerOrganizationId: z.string().min(1).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /** The firm's name when the relationship was proposed — a snapshot, because the client cannot read the firm's row. */
+    providerOrganizationName: z.string().max(200).optional().isSummaryField().excludeFromCreate().excludeFromUpdate(),
+    status: z.enum(ServiceProviderRelationshipStatus)
+        .systemEnum('ServiceProviderRelationshipStatus')
+        .default(ServiceProviderRelationshipStatus.PROPOSED)
+        .isDBIndexed()
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate()
+        .isAuditEvidence(),
+    /**
+     * The role every assigned expert holds in the client organization. One of the provider organization
+     * type's `servesAsProvider.providerRoles`, never one leading up to `ORG_ADMIN` (refused at startup).
+     * The provider memberships' `roles` mirror it; the live filter emits THIS value.
+     */
+    role: z.string().min(1).isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /**
+     * Engagement scope. Absent or empty ⇒ organization-wide. Present ⇒ the experts reach ONLY these units:
+     * the live filter emits one unit-scoped role entry per id and NO organization-wide entry, so a
+     * resource that neither narrows by unit nor is declared organization-wide for providers is refused.
+     * Stored once, here — no `ORGANIZATION_UNIT_MEMBERS` rows mirror it.
+     */
+    organizationUnitIds: z.array(z.string().min(1)).optional().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /** The term. Absent ⇒ open-ended. Admission reads this, never the EXPIRED label. */
+    // Nullish: `amendScope` CLEARS a term by writing null, which means "no term".
+    endsAt: z.date().nullish().isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /** Why the relationship exists — required, and the fact the client's processor register derives from. */
+    purpose: purposeField(),
+    /**
+     * Firm-owned OAuth clients the client admits into its organization under this relationship (S3). A
+     * listed client authenticating by client credentials receives the relationship's role in THIS
+     * organization, re-checked per request. What such a principal may do is decided elsewhere.
+     */
+    admittedMachineClientIds: z.array(z.string().min(1)).optional().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /**
+     * Which of the firm's autonomous agents the client lets each admitted client run HERE (#1611). The firm
+     * decides which agents its client runs (`autonomousAgentRefs` on the client); the CLIENT decides which of
+     * those may act in its organization, at the relationship's role and on its token budget. A turn needs both:
+     * see {@link serviceProviderAdmitsAutonomousAgent}. No entry for a client, or an empty list, admits none —
+     * a firm adding an agent to its own client never starts it in a client organization that did not choose it.
+     *
+     * Written only by `admitMachineClient` (which replaces the client's entry) and `removeMachineClient` (which
+     * drops it), so it can never name a client `admittedMachineClientIds` does not.
+     */
+    admittedAutonomousAgents: z.array(ServiceProviderAdmittedAutonomousAgentsSchema).optional().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /**
+     * Whether each expert the firm assigns waits for the client's own approval (#1612). The CLIENT's choice:
+     * written by the client's `propose`, `accept` and `setExpertAdmissionPolicy` only — a firm's proposal starts
+     * from the client organization type's declared default, and no firm verb reads a value for it.
+     */
+    expertAdmissionPolicy: z.enum(ServiceProviderExpertAdmissionPolicy)
+        .systemEnum('ServiceProviderExpertAdmissionPolicy')
+        .default(ServiceProviderExpertAdmissionPolicy.RELATIONSHIP_APPROVES_ASSIGNED_EXPERTS)
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate()
+        .isAuditEvidence(),
+    /**
+     * Whether the client accepts the multi-factor proof the FIRM's own enterprise identity provider made (#1633). The
+     * client's choice, written only by its `setProviderMfaTrust` verb (ORG_OWNER, step-up); off by default. The client
+     * organization type's authentication policy governs the experts either way — this only decides whether a factor
+     * the firm's provider reported may satisfy it. See {@link ServiceProviderMfaTrust}.
+     */
+    providerMfaTrust: z.enum(ServiceProviderMfaTrust)
+        .systemEnum('ServiceProviderMfaTrust')
+        .default(ServiceProviderMfaTrust.NOT_TRUSTED)
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate()
+        .isAuditEvidence(),
+    /**
+     * How much the firm's expert-activity feed may say about work done in this client (#1632). The client's choice,
+     * written only by its `setActivityFeedDisclosure` verb (ORG_ADMIN). Read LIVE by the feed writer, so a change takes
+     * effect on the expert's next action. Metadata only at every level. See {@link ServiceProviderActivityFeedDisclosure}.
+     */
+    activityFeedDisclosure: z.enum(ServiceProviderActivityFeedDisclosure)
+        .systemEnum('ServiceProviderActivityFeedDisclosure')
+        .default(ServiceProviderActivityFeedDisclosure.OPERATION_AND_OUTCOME)
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate()
+        .isAuditEvidence(),
+    /** Which side proposed — the OTHER side accepts. */
+    proposedByOrganizationId: z.string().min(1).isDBIndexed().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    proposedByUserId: z.string().min(1).optional().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    acceptedByUserId: z.string().min(1).optional().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    acceptedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
+    endedByUserId: z.string().min(1).optional().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /** When a terminal status was reached — the retention clock's start point. */
+    endedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    decisionReason: decisionReasonField(),
+    createdAt: z.date().optional(),
+    updatedAt: z.date().optional(),
+});
+/**
+ * The firm's mirror of one relationship, stored in the PROVIDER organization.
+ *
+ * System-written in the same transaction as every relationship transition, and what the firm reads —
+ * its clients list, the expert assignment screen, the organization switcher's grouping. It carries only
+ * what the firm needs: the client's unit ids stay in the client's tenant (`scopedToOrganizationUnits`
+ * says whether a scope exists, not what it is).
+ */
+export const ServiceEngagementSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    /** The PROVIDER organization — the firm. */
+    organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate().isAuditEvidence(),
+    /** The client organization. A plain id for the same reason as `providerOrganizationId` on the relationship. */
+    clientOrganizationId: z.string().min(1).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /** The relationship this mirrors, in the client's tenant. Unique: one mirror per relationship. */
+    serviceProviderRelationshipId: z.string().min(1).isDBIndexed().isUnique().isSummaryField().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    status: z.enum(ServiceProviderRelationshipStatus)
+        .systemEnum('ServiceProviderRelationshipStatus')
+        .default(ServiceProviderRelationshipStatus.PROPOSED)
+        .isDBIndexed()
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate(),
+    role: z.string().min(1).isSummaryField().excludeFromCreate().excludeFromUpdate(),
+    scopedToOrganizationUnits: z.boolean().default(false).isSummaryField().excludeFromCreate().excludeFromUpdate(),
+    // Nullish, and always written by the mirror sync: a term the client cleared must clear here too.
+    endsAt: z.date().nullish().isSummaryField().excludeFromCreate().excludeFromUpdate(),
+    purpose: purposeField(),
+    proposedByOrganizationId: z.string().min(1).excludeFromCreate().excludeFromUpdate(),
+    /**
+     * Display copy of the client's name — the firm cannot read the client row. Written only once the client has
+     * consented to the firm knowing it (it proposed to this firm, or accepted the firm's proposal), then refreshed at each
+     * transition. Absent while a firm's proposal is pending and after a decline: a proposal must not be a way to learn a
+     * tenant's name.
+     */
+    clientOrganizationName: z.string().max(200).optional().isSummaryField().excludeFromCreate().excludeFromUpdate(),
+    /**
+     * The client's admission policy, mirrored so the firm knows before assigning whether each expert will wait for
+     * the client's approval (#1612). Read-only here: the firm has no verb that writes it.
+     */
+    expertAdmissionPolicy: z.enum(ServiceProviderExpertAdmissionPolicy)
+        .systemEnum('ServiceProviderExpertAdmissionPolicy')
+        .default(ServiceProviderExpertAdmissionPolicy.RELATIONSHIP_APPROVES_ASSIGNED_EXPERTS)
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate(),
+    /**
+     * The administrative capabilities the client currently lends this firm (#1631), with when each ends — mirrored so the
+     * firm knows what its experts may do there. System-written on every grant and revocation; read-only to the firm, which
+     * can never grant, widen or extend one.
+     */
+    delegatedCapabilities: z.array(ServiceEngagementDelegatedCapabilitySchema).optional().excludeFromCreate().excludeFromUpdate(),
+    /** Mirrors the relationship's end — the retention clock's start point, so the sweep queries it (indexed). */
+    endedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+    decisionReason: decisionReasonField(),
+    createdAt: z.date().optional(),
+    updatedAt: z.date().optional(),
+});
+/**
+ * Which of the firm's members serve which engagement — stored in the PROVIDER organization, decided by
+ * the firm's administrators. Assigning creates (or reactivates) the expert's provider membership in the
+ * client organization; unassigning makes it INACTIVE. The live filter reads the ACTIVE assignment for
+ * `(serviceProviderRelationshipId, userId)` on every request.
+ */
+export const ServiceEngagementAssignmentSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    /** The PROVIDER organization. */
+    organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate().isAuditEvidence(),
+    /** The engagement (mirror) this assignment serves — same tenant, a real edge. */
+    serviceEngagementId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate().isAuditEvidence(),
+    /** The expert. Must be an ACTIVE, ordinary member of the firm when assigned. */
+    userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate().isAuditEvidence(),
+    /** Copied from the engagement so the live filter reads one row by `(relationship, user)`. */
+    serviceProviderRelationshipId: z.string().min(1).isDBIndexed().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    clientOrganizationId: z.string().min(1).isDBIndexed().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    status: z.enum(ServiceEngagementAssignmentStatus)
+        .systemEnum('ServiceEngagementAssignmentStatus')
+        .default(ServiceEngagementAssignmentStatus.ACTIVE)
+        .isDBIndexed()
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate()
+        .isAuditEvidence(),
+    assignedByUserId: z.string().min(1).optional().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    assignedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
+    /**
+     * The client's pending approval of this expert (#1612): the `HumanDecision_Request.decisionId` of the
+     * decision routed to the client's administrators, set when the assignment was made under a relationship
+     * whose client approves each expert. It is the ONE key the decision is read, listed and settled by, and the
+     * settle write matches on it, so an answer can only ever settle the request it was given.
+     */
+    approvalDecisionId: z.string().min(1).optional().isDBIndexed().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /** When the client's approval ended — approved, denied or lapsed. The client administrator who answered is NOT stored here: the firm reads this row. */
+    approvalResolvedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
+    /** Why a DENIED assignment admitted nobody — a fact the firm may know, never who in the client decided. */
+    approvalDenialReason: z.enum(ServiceProviderExpertApprovalDenialReason)
+        .systemEnum('ServiceProviderExpertApprovalDenialReason')
+        .optional()
+        .excludeFromCreate()
+        .excludeFromUpdate(),
+    /**
+     * The clocks of a pending client approval (#1909), armed at `assign` from the client organization type's
+     * `acceptsServiceProviders.expertApprovalDeadlines` with #1628's model, and stored rather than recomputed so a
+     * deployment that changes the declaration never reshapes a clock already running.
+     *
+     * - `approvalLapseAt` — when the approval ends LAPSED, admitting nobody. The firm may see it: it is when its request
+     *   stops waiting.
+     * - `approvalDecisionDeadlineAt` / `approvalDecisionWarningAt` — the DECISION service target and its optional
+     *   warning, on `approvalDecisionClockBasis`. There is no CLAIM clock: this plane offers no claim.
+     * - `approvalDecisionWarningFiredAt` / `approvalDecisionMissedFiredAt` — each stage's fired marker, set by a
+     *   compare-and-swap that requires it null, so a stage fires exactly once across hosts.
+     * - `approvalNextDueAt` — the earliest of the lapse and any stage still to fire: what the sweep selects by index.
+     */
+    approvalLapseAt: z.date().nullish().isDBIndexed().excludeFromCreate().excludeFromUpdate()
+        .describe('While the client has not decided on this assignment: when the request lapses, admitting nobody. Empty once the client has decided.'),
+    approvalDecisionDeadlineAt: z.date().nullish().excludeFromCreate().excludeFromUpdate()
+        .describe('The service target by which the client is expected to decide on this assignment, counted on `approvalDecisionClockBasis`.'),
+    approvalDecisionWarningAt: z.date().nullish().excludeFromCreate().excludeFromUpdate()
+        .describe('When the client is warned that the decision target is near, when the client organization declares a warning. Empty otherwise.'),
+    approvalDecisionClockBasis: z.enum(ReviewClockBasis).systemEnum('ReviewClockBasis').nullish().excludeFromCreate().excludeFromUpdate()
+        .describe('How the decision target is counted: `elapsed` wall-clock time, or `calendar` working hours of the application\'s review calendar.'),
+    approvalDecisionWarningFiredAt: z.date().nullish().isBackendOnly().excludeFromCreate().excludeFromUpdate(),
+    approvalDecisionMissedFiredAt: z.date().nullish().isBackendOnly().excludeFromCreate().excludeFromUpdate(),
+    approvalNextDueAt: z.date().nullish().isDBIndexed().isBackendOnly().excludeFromCreate().excludeFromUpdate(),
+    endedByUserId: z.string().min(1).optional().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    /** When the assignment ended — the retention clock's start point. */
+    endedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate().isAuditEvidence(),
+    createdAt: z.date().optional(),
+    updatedAt: z.date().optional(),
+});
+/**
+ * The input of the INTERNAL `settleClientApproval` verb (#1612): which pending approval, and how the client answered.
+ *
+ * `outcome` is the one decision vocabulary (`HumanDecision_Outcome`). Only ACCEPTED, REJECTED and LAPSED settle an
+ * expert approval — the verb refuses the others rather than reading them as one of these.
+ */
+export const ServiceEngagementAssignmentSettleClientApprovalDtoSchema = z.object({
+    approvalDecisionId: z.string().min(1),
+    outcome: z.enum(HumanDecision_Outcome),
+    /** The client administrator who answered — recorded in the CLIENT's trail only, never on the assignment the firm reads. */
+    decidedByUserId: z.string().min(1).optional(),
+});
+/**
+ * The client-branchable codes a service-provider refusal carries (all answer 409 CONFLICT: the caller is
+ * authorized and the payload is valid; the current STATE forbids the write).
+ */
+export var ServiceProviderRelationshipErrorCode;
+(function (ServiceProviderRelationshipErrorCode) {
+    /** A PROPOSED, ACTIVE or SUSPENDED relationship already links this firm and this client. */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_RELATIONSHIP_ALREADY_LIVE"] = "SERVICE_PROVIDER_RELATIONSHIP_ALREADY_LIVE";
+    /** The expert is one of the client's OWN members; a person is in an organization one way at a time. */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_ASSIGNMENT_CONFLICTS_WITH_MEMBERSHIP"] = "SERVICE_PROVIDER_ASSIGNMENT_CONFLICTS_WITH_MEMBERSHIP";
+    /** The expert already serves this client under another live relationship. */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_ASSIGNMENT_ALREADY_LIVE"] = "SERVICE_PROVIDER_ASSIGNMENT_ALREADY_LIVE";
+    /** A provider membership's roles belong to the relationship; change the relationship, not the membership. */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_MEMBERSHIP_ROLES_OWNED_BY_RELATIONSHIP"] = "SERVICE_PROVIDER_MEMBERSHIP_ROLES_OWNED_BY_RELATIONSHIP";
+    /**
+     * An invitation to a person who has a PROVIDER membership in this organization. A live one: the person is
+     * already here through a firm. An ended one (INACTIVE): remove that membership first, then invite.
+     */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_MEMBERSHIP_CONFLICTS_WITH_INVITATION"] = "SERVICE_PROVIDER_MEMBERSHIP_CONFLICTS_WITH_INVITATION";
+    /** The other party's organization type is not one this relationship's provider type serves (or does not serve at all). */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_ORGANIZATION_TYPE_NOT_ELIGIBLE"] = "SERVICE_PROVIDER_ORGANIZATION_TYPE_NOT_ELIGIBLE";
+    /** The side that proposed tried to accept its own proposal. */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_PROPOSAL_ACCEPTED_BY_PROPOSER"] = "SERVICE_PROVIDER_PROPOSAL_ACCEPTED_BY_PROPOSER";
+    /** The requested role is not one of the provider type's `providerRoles`. */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_ROLE_NOT_DECLARED"] = "SERVICE_PROVIDER_ROLE_NOT_DECLARED";
+    /** A requested organization unit is not a unit of the client organization. */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_UNIT_NOT_IN_CLIENT"] = "SERVICE_PROVIDER_UNIT_NOT_IN_CLIENT";
+    /** Assignment needs an ACTIVE engagement and an ACTIVE, ordinary member of the firm. */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_ASSIGNMENT_NOT_ELIGIBLE"] = "SERVICE_PROVIDER_ASSIGNMENT_NOT_ELIGIBLE";
+    /**
+     * The client SUSPENDED this expert's membership. That is the client's decision about one person, and a
+     * firm's assignment may not undo it: the client reactivates the membership first.
+     */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_EXPERT_SUSPENDED_BY_CLIENT"] = "SERVICE_PROVIDER_EXPERT_SUSPENDED_BY_CLIENT";
+    /** The OAuth client to admit is not an ACTIVE client owned by the provider organization. */
+    ServiceProviderRelationshipErrorCode["SERVICE_PROVIDER_MACHINE_CLIENT_NOT_ELIGIBLE"] = "SERVICE_PROVIDER_MACHINE_CLIENT_NOT_ELIGIBLE";
+})(ServiceProviderRelationshipErrorCode || (ServiceProviderRelationshipErrorCode = {}));
+/**
+ * May an organization of `providerType` enter a relationship with an organization of `clientType`, and
+ * with which role? The ONE rule both sides' verbs apply (propose, accept, amend) — so a relationship can
+ * never be accepted on terms that could not have been proposed.
+ *
+ * Returns the resolved role, or the refusal code. Fails closed on anything undeclared.
+ */
+export function resolveServiceProviderRelationshipTerms(input) {
+    const providerType = input.providerOrganizationType ? input.organizationTypes?.[input.providerOrganizationType] : undefined;
+    const clientType = input.clientOrganizationType ? input.organizationTypes?.[input.clientOrganizationType] : undefined;
+    const servesAsProvider = providerType?.servesAsProvider;
+    if (!servesAsProvider || !clientType || !input.clientOrganizationType
+        || !servesAsProvider.clientOrganizationTypes.includes(input.clientOrganizationType)) {
+        return { allowed: false, code: ServiceProviderRelationshipErrorCode.SERVICE_PROVIDER_ORGANIZATION_TYPE_NOT_ELIGIBLE };
+    }
+    const role = input.requestedRole ?? servesAsProvider.defaultProviderRole;
+    const clientRoles = (clientType.availableOrgRoles ?? []).map(String);
+    if (!servesAsProvider.providerRoles.includes(role) || !clientRoles.includes(role)) {
+        return { allowed: false, code: ServiceProviderRelationshipErrorCode.SERVICE_PROVIDER_ROLE_NOT_DECLARED };
+    }
+    return { allowed: true, role };
+}
+/** Why a `servesAsProvider` declaration was refused at startup. */
+export var ServiceProviderDeclarationViolationKind;
+(function (ServiceProviderDeclarationViolationKind) {
+    /** A provider role whose `inheritFrom` chain reaches `ORG_ADMIN` — a relationship must never confer administration. */
+    ServiceProviderDeclarationViolationKind["PROVIDER_ROLE_REACHES_ADMINISTRATION"] = "PROVIDER_ROLE_REACHES_ADMINISTRATION";
+    /** A provider role unknown to the organization role table. */
+    ServiceProviderDeclarationViolationKind["PROVIDER_ROLE_UNDECLARED"] = "PROVIDER_ROLE_UNDECLARED";
+    /** A provider role a client type does not list in `availableOrgRoles`. */
+    ServiceProviderDeclarationViolationKind["PROVIDER_ROLE_UNAVAILABLE_IN_CLIENT_TYPE"] = "PROVIDER_ROLE_UNAVAILABLE_IN_CLIENT_TYPE";
+    /** `defaultProviderRole` is not one of `providerRoles`. */
+    ServiceProviderDeclarationViolationKind["DEFAULT_PROVIDER_ROLE_NOT_DECLARED"] = "DEFAULT_PROVIDER_ROLE_NOT_DECLARED";
+    /** A client organization type that is not declared. */
+    ServiceProviderDeclarationViolationKind["CLIENT_ORGANIZATION_TYPE_UNDECLARED"] = "CLIENT_ORGANIZATION_TYPE_UNDECLARED";
+    /**
+     * A provider role that is a delegated capability role (`ORG_DELEGATED_*`, #1631). A capability is conferred ONLY by a
+     * live, dated grant the client can revoke; as a provider role it would ride every assignment for the whole
+     * relationship, with no term, no owner-only verb and no grant row — the standing access the grant exists to prevent.
+     */
+    ServiceProviderDeclarationViolationKind["PROVIDER_ROLE_IS_DELEGATED_CAPABILITY"] = "PROVIDER_ROLE_IS_DELEGATED_CAPABILITY";
+})(ServiceProviderDeclarationViolationKind || (ServiceProviderDeclarationViolationKind = {}));
+/**
+ * Validate every `servesAsProvider` declaration against the LIVE organization role table.
+ *
+ * `administrationAnchorRole` is `ORG_ADMIN`; a provider role reaches it when the hierarchy walk of that
+ * role (the one the authorization layer uses) includes it — so a custom role inheriting from `ORG_ADMIN`
+ * is refused exactly like `ORG_ADMIN` itself.
+ */
+export function collectServiceProviderDeclarationViolations(input) {
+    const violations = [];
+    for (const [providerOrganizationType, definition] of Object.entries(input.organizationTypes ?? {})) {
+        const declaration = definition?.servesAsProvider;
+        if (!declaration)
+            continue;
+        const push = (kind, subject) => violations.push({ providerOrganizationType, kind, subject });
+        if (!declaration.providerRoles.includes(declaration.defaultProviderRole)) {
+            push(ServiceProviderDeclarationViolationKind.DEFAULT_PROVIDER_ROLE_NOT_DECLARED, declaration.defaultProviderRole);
+        }
+        for (const role of declaration.providerRoles) {
+            const hierarchy = input.organizationRoleHierarchy(role);
+            if (hierarchy.length === 0)
+                push(ServiceProviderDeclarationViolationKind.PROVIDER_ROLE_UNDECLARED, role);
+            if (hierarchy.includes(input.administrationAnchorRole))
+                push(ServiceProviderDeclarationViolationKind.PROVIDER_ROLE_REACHES_ADMINISTRATION, role);
+            if (isDelegatedCapabilityRole(role))
+                push(ServiceProviderDeclarationViolationKind.PROVIDER_ROLE_IS_DELEGATED_CAPABILITY, role);
+        }
+        for (const clientType of declaration.clientOrganizationTypes) {
+            const clientDefinition = input.organizationTypes?.[clientType];
+            if (!clientDefinition) {
+                push(ServiceProviderDeclarationViolationKind.CLIENT_ORGANIZATION_TYPE_UNDECLARED, clientType);
+                continue;
+            }
+            const available = (clientDefinition.availableOrgRoles ?? []).map(String);
+            for (const role of declaration.providerRoles) {
+                if (!available.includes(role))
+                    push(ServiceProviderDeclarationViolationKind.PROVIDER_ROLE_UNAVAILABLE_IN_CLIENT_TYPE, `${clientType}:${role}`);
+            }
+        }
+    }
+    return violations;
+}
+/** @wildo_source:part:start saas.models.organizations.service-provider-relationships */
+/**
+ * The client's verbs. Kept with the vocabulary, not the resources-config, for the reason recorded on
+ * `PlatformAccessGrants_Operations`: authorization and batch code need the names without dragging
+ * resource-configuration evaluation into their module graph.
+ *
+ * No generic CREATE / UPDATE: every field's server authorship IS the control.
+ */
+export var ServiceProviderRelationships_Operations;
+(function (ServiceProviderRelationships_Operations) {
+    /** Client ORG_OWNER proposes a relationship to a firm. The proposal is the client's consent. */
+    ServiceProviderRelationships_Operations["PROPOSE"] = "propose";
+    /** Client ORG_OWNER accepts a FIRM's proposal (step-up). Never available to the proposing side. */
+    ServiceProviderRelationships_Operations["ACCEPT"] = "accept";
+    /** Client ORG_ADMIN refuses a firm's proposal. */
+    ServiceProviderRelationships_Operations["DECLINE"] = "decline";
+    ServiceProviderRelationships_Operations["SUSPEND"] = "suspend";
+    ServiceProviderRelationships_Operations["RESUME"] = "resume";
+    ServiceProviderRelationships_Operations["TERMINATE"] = "terminate";
+    /** Client ORG_OWNER changes role, units or term (step-up). The firm cannot widen what the client granted. */
+    ServiceProviderRelationships_Operations["AMEND_SCOPE"] = "amendScope";
+    ServiceProviderRelationships_Operations["ADMIT_MACHINE_CLIENT"] = "admitMachineClient";
+    ServiceProviderRelationships_Operations["REMOVE_MACHINE_CLIENT"] = "removeMachineClient";
+    /** ACTIVE → EXPIRED past `endsAt`, dispatched by the credential-expiry sweep only. */
+    ServiceProviderRelationships_Operations["EXPIRE"] = "expire";
+    /** Client ORG_OWNER decides whether the firm's own identity provider's MFA counts here (#1633, step-up). */
+    ServiceProviderRelationships_Operations["SET_PROVIDER_MFA_TRUST"] = "setProviderMfaTrust";
+    /** Client ORG_ADMIN decides how much the firm's expert-activity feed may say about work here (#1632). */
+    ServiceProviderRelationships_Operations["SET_ACTIVITY_FEED_DISCLOSURE"] = "setActivityFeedDisclosure";
+    /** Client ORG_ADMIN changes how the firm's experts are admitted (#1612). Not retroactive. The firm has no such verb. */
+    ServiceProviderRelationships_Operations["SET_EXPERT_ADMISSION_POLICY"] = "setExpertAdmissionPolicy";
+})(ServiceProviderRelationships_Operations || (ServiceProviderRelationships_Operations = {}));
+/** The firm's verbs, on its own mirror. */
+export var ServiceEngagements_Operations;
+(function (ServiceEngagements_Operations) {
+    /** Firm ORG_ADMIN proposes a relationship to a client organization. */
+    ServiceEngagements_Operations["PROPOSE"] = "propose";
+    /** Firm ORG_ADMIN accepts a CLIENT's proposal. */
+    ServiceEngagements_Operations["ACCEPT"] = "accept";
+    /** Firm ORG_ADMIN ends the relationship, or withdraws its own pending proposal. */
+    ServiceEngagements_Operations["WITHDRAW"] = "withdraw";
+})(ServiceEngagements_Operations || (ServiceEngagements_Operations = {}));
+export var ServiceEngagementAssignments_Operations;
+(function (ServiceEngagementAssignments_Operations) {
+    /** Firm ORG_ADMIN designates one of its members to serve an ACTIVE engagement. */
+    ServiceEngagementAssignments_Operations["ASSIGN"] = "assign";
+    /** Ends an ACTIVE assignment, or withdraws one still awaiting the client's approval (#1612). */
+    ServiceEngagementAssignments_Operations["UNASSIGN"] = "unassign";
+    /**
+     * Apply the client's answer to a per-expert approval (#1612) — INTERNAL only, reached through the human-decision
+     * answer path after the answerer was authorized there. Approval re-checks everything admission depends on,
+     * inside one transaction, before creating the membership.
+     */
+    ServiceEngagementAssignments_Operations["SETTLE_CLIENT_APPROVAL"] = "settleClientApproval";
+})(ServiceEngagementAssignments_Operations || (ServiceEngagementAssignments_Operations = {}));
+/** @wildo_source:part:end saas.models.organizations.service-provider-relationships */
+/**
+ * The admission policy a relationship starts with (#1612): the CLIENT's explicit choice when it made one, else the
+ * client organization type's declared default, else {@link ServiceProviderExpertAdmissionPolicy.RELATIONSHIP_APPROVES_ASSIGNED_EXPERTS}.
+ *
+ * The firm's type is never consulted: the choice belongs to the party whose tenant the experts enter.
+ */
+export function resolveServiceProviderExpertAdmissionPolicy(input) {
+    if (input.clientChoice)
+        return input.clientChoice;
+    const declared = input.clientOrganizationType
+        ? input.organizationTypes?.[input.clientOrganizationType]?.acceptsServiceProviders?.defaultExpertAdmissionPolicy
+        : undefined;
+    return declared ?? ServiceProviderExpertAdmissionPolicy.RELATIONSHIP_APPROVES_ASSIGNED_EXPERTS;
+}
+/**
+ * Who may answer a per-expert approval (#1612): the CLIENT organization's administrator ROLE — ORG_ADMIN, which an
+ * ORG_OWNER holds through the role hierarchy — organization-wide, and never a named person. Derived from the
+ * assignment rather than stored beside it, so it cannot drift from the organization the expert would enter.
+ *
+ * A provider role never reaches ORG_ADMIN (refused at startup), so no firm's expert can answer for the client.
+ */
+export function serviceProviderExpertApprovalRoute(clientOrganizationId) {
+    return { kind: HumanDecision_RouteKind.ROLE, eligibleRole: CORE_ORG_ROLES.ORG_ADMIN, organizationId: clientOrganizationId };
+}
+/**
+ * The question a client's administrators are asked about one expert (#1612), in the one decision shape.
+ *
+ * The title and description are the host's authored account for readers with no screen (a trail, a CLI); an inbox
+ * renders its own translated words from the card's subject. Two options: APPROVE proceeds, REJECT ends the waiting
+ * assignment. Its lapse is armed on the assignment (#1909) and shown on the card; the request itself carries none.
+ */
+export function serviceProviderExpertApprovalRequest(input) {
+    const firm = input.providerOrganizationName ?? 'A service firm';
+    return {
+        decisionId: input.decisionId,
+        title: `Admit an expert from ${firm}`,
+        description: `${firm} assigned one of its experts to work in your organization with the ${input.role} role. `
+            + 'Approving gives them a membership now, if the relationship still allows it; rejecting admits nobody.',
+        fields: [],
+        options: [
+            { ref: ServiceProviderExpertApprovalOption.APPROVE, label: 'Approve', intent: HumanDecision_ResponseIntent.PROCEED_WITH_VALUES },
+            { ref: ServiceProviderExpertApprovalOption.REJECT, label: 'Reject', intent: HumanDecision_ResponseIntent.ABORT },
+        ],
+        requestedAt: input.requestedAt,
+    };
+}
+/**
+ * Everything wrong with a client organization type's `acceptsServiceProviders.expertApprovalDeadlines` (#1909), as
+ * sentences naming the fix. Startup refuses a type with any. On top of #1628's checks for a ROLE route:
+ *
+ * - no `claim` target and no CLAIM-stage rule — this plane offers no claim, so a CLAIM clock could only ever be missed;
+ * - no REASSIGN rule — the route is always the client's administrators, never a named person, so it cannot move;
+ * - no `pauseStates` — this plane offers no pause, so a declared pause state could never be entered.
+ *
+ * A declaration asking for something the plane cannot do is refused rather than half-honoured: a setting that looks
+ * like a control and does nothing is the defect this check exists to prevent.
+ */
+export function serviceProviderExpertApprovalDeadlinesIssues(declaration, context) {
+    if (!declaration)
+        return [];
+    const issues = reviewDeadlinesDeclarationIssues(declaration, { routeKind: HumanDecision_RouteKind.ROLE, calendarDeclared: context.calendarDeclared });
+    if (declaration.claim)
+        issues.push('expertApprovalDeadlines.claim is declared, but an expert approval offers no claim, so a CLAIM clock could only be missed. Remove it.');
+    for (const rule of declaration.rules ?? []) {
+        if (rule.stage === ReviewDeadlineStage.CLAIM_WARNING || rule.stage === ReviewDeadlineStage.CLAIM_MISSED) {
+            issues.push(`expertApprovalDeadlines.rules names ${rule.stage}, but an expert approval has no CLAIM clock. Remove the rule.`);
+        }
+        if (rule.action === ReviewEscalationActionKind.REASSIGN) {
+            issues.push(`expertApprovalDeadlines.rules REASSIGNs at ${rule.stage}, but an expert approval is routed to the client's administrators and cannot move. Use NOTIFY.`);
+        }
+    }
+    if ((declaration.pauseStates ?? []).length > 0)
+        issues.push('expertApprovalDeadlines.pauseStates is declared, but an expert approval offers no pause. Remove it.');
+    return issues;
+}
+/**
+ * Arm a pending approval's clocks at `assign` (#1909), with #1628's model. A type declaring nothing gets the
+ * framework's defaults — the same lapse window and DECISION reminder every human decision gets — so a pending
+ * approval no longer waits forever; the CLAIM target is never armed on this plane.
+ */
+export function armServiceProviderExpertApprovalClocks(input) {
+    const policy = resolveReviewDeadlinePolicy(input.declaration);
+    const armed = armReviewDeadlines({ requestedAt: input.requestedAt, policy, calendar: input.calendar });
+    const clocks = {
+        approvalLapseAt: armed.lapseAt,
+        approvalDecisionDeadlineAt: armed.decisionDeadlineAt,
+        approvalDecisionWarningAt: armed.decisionWarningAt ?? null,
+        approvalDecisionClockBasis: armed.decisionBasis,
+    };
+    return { ...clocks, approvalNextDueAt: serviceProviderExpertApprovalNextDueAt(clocks) };
+}
+const asDate = (value) => value === null || value === undefined ? undefined : (value instanceof Date ? value : new Date(value));
+/** The row's DECISION stages as #1628's schedule. No CLAIM stage is ever due on this plane. */
+function expertApprovalStageSchedule(row) {
+    const warning = asDate(row.approvalDecisionWarningAt);
+    const deadline = asDate(row.approvalDecisionDeadlineAt);
+    const warningFired = asDate(row.approvalDecisionWarningFiredAt);
+    const missedFired = asDate(row.approvalDecisionMissedFiredAt);
+    const lapseAt = asDate(row.approvalLapseAt);
+    return {
+        dueAt: {
+            ...(warning ? { [ReviewDeadlineStage.DECISION_WARNING]: warning } : {}),
+            ...(deadline ? { [ReviewDeadlineStage.DECISION_MISSED]: deadline } : {}),
+        },
+        firedAt: {
+            ...(warningFired ? { [ReviewDeadlineStage.DECISION_WARNING]: warningFired } : {}),
+            ...(missedFired ? { [ReviewDeadlineStage.DECISION_MISSED]: missedFired } : {}),
+        },
+        claimed: false,
+        ...(lapseAt ? { lapseAt } : {}),
+    };
+}
+/** The DECISION stages due at `now`, in firing order (#1909). */
+export function dueServiceProviderExpertApprovalStages(row, now) {
+    return dueReviewDeadlineStages(expertApprovalStageSchedule(row), now);
+}
+/**
+ * What the row's indexed `approvalNextDueAt` holds: the earliest of any stage still to fire and the lapse. The lapse
+ * is included because this plane's one sweep ends the approval too; `null` for a row with no clock.
+ */
+export function serviceProviderExpertApprovalNextDueAt(row) {
+    const stage = nextReviewDeadlineDueAt(expertApprovalStageSchedule(row));
+    const lapseAt = asDate(row.approvalLapseAt);
+    const candidates = [stage, lapseAt].filter((instant) => !!instant);
+    return candidates.length === 0 ? null : new Date(Math.min(...candidates.map((instant) => instant.getTime())));
+}
+//# sourceMappingURL=service-provider-relationships.shared.schemas.js.map