@orchestraworks/cli 0.5.4 → 0.5.7

package/dist/engine/refusals.d.ts

@@ -1,5 +1,5 @@
 import type { PlanKind, PlanResource, ValueFrom } from "../core/plan.js";
-import { ApplyError, type ApplyOutcome, type DesiredProject, type ProjectIdentityRefusal } from "./apply-core.js";
+import { ApplyError, type ApplyOutcome, type DesiredTeam, type TeamIdentityRefusal } from "./apply-core.js";
 /**
  * Supplied explicitly by whichever caller is classifying, never read ambiently: both callers build one from
  * their OWN reads, taken at their own time, which keeps the freshness discipline while the RULE stays
@@ -7,7 +7,7 @@ import { ApplyError, type ApplyOutcome, type DesiredProject, type ProjectIdentit
  * the one function that owns each kind.
  *
  * EVERY field is optional, because evidence gating is the module's rule and not a per-field exception: a
- * caller holding no environment or no project omits it rather than manufacturing a sentinel.
+ * caller holding no environment or no team omits it rather than manufacturing a sentinel.
  */
 export interface RefusalContext {
     /** Absent ⇒ nothing exists yet. */
@@ -20,9 +20,9 @@ export interface RefusalContext {
     resolvedDesired?: unknown;
     /** Injected, never read from `process.env` inside a classifier. Absent ⇒ the source arms decide nothing. */
     env?: Record<string, string | undefined>;
-    /** Absent ⇒ this kind has no project axis, the same inert answer `{ state: "none" }` gives. */
-    project?: DesiredProject;
-    gatewayPair?: ProjectIdentityRefusal["pairContext"];
+    /** The row's declared team. Absent ⇒ this kind has no team, or the caller cannot judge it. */
+    team?: DesiredTeam;
+    gatewayPair?: TeamIdentityRefusal["pairContext"];
     /** Secret ids owned by connections, when the caller has scanned for them. */
     reservedProviderSecretIds?: ReadonlySet<string>;
 }
@@ -31,11 +31,7 @@ export interface ResolvedSecretRef {
     readonly id: string;
     readonly label: string;
 }
-/**
- * ONE GROUP of an environment's secret references, already resolved to canonical ids. An environment
- * contributes TWO groups and classifies each on its own, because the pairwise-distinct rule is about the
- * egress group alone.
- */
+/** An environment's secret references, already resolved to canonical ids: today its pull credential. */
 export interface ResolvedEnvironmentDesired {
     readonly secretRefs: readonly ResolvedSecretRef[];
 }
@@ -53,21 +49,21 @@ export interface ResolvedConnectionDesired {
  */
 export interface LiveGatewayKeyPair {
     readonly key?: {
-        projectId?: string | null;
+        teamId?: string | null;
     } | undefined;
     readonly secret?: {
-        projectId?: string | null;
+        teamId?: string | null;
     } | undefined;
     readonly secretMarked?: boolean;
 }
 /**
- * A discriminated union, so each arm carries its own typed payload. The project arm carries the
- * machine-readable {@link ProjectIdentityRefusal} rather than a pre-rendered string, which keeps the shared
+ * A discriminated union, so each arm carries its own typed payload. The team arm carries the
+ * machine-readable {@link TeamIdentityRefusal} rather than a pre-rendered string, which keeps the shared
  * formatter the only place that conflict is worded. `code` is what `DiffEntry.blocked` carries.
  */
 export type RefusalVerdict = {
-    code: "project-identity";
-    refusal: ProjectIdentityRefusal;
+    code: "team-identity";
+    refusal: TeamIdentityRefusal;
 } | {
     code: "connector-identity";
     message: string;
@@ -98,9 +94,6 @@ export type RefusalVerdict = {
 } | {
     code: "reserved-provider-secret";
     message: string;
-} | {
-    code: "duplicate-binding";
-    message: string;
 } | {
     code: "byok-ownership";
     message: string;
@@ -110,7 +103,7 @@ export type RefusalVerdict = {
 };
 /**
  * The subtype lets the CLI present every deterministic refusal as `cannot apply:` without changing the
- * classifier's raw message, which diff rows also render. Project identity keeps its own richer subtype.
+ * classifier's raw message, which diff rows also render. Team identity keeps its own richer subtype.
  */
 export declare class AggregateRefusalError extends ApplyError {
     constructor(message: string, outcomes: ApplyOutcome[], options?: {
@@ -150,7 +143,7 @@ export declare function byokUnsetSourceMessage(slug: string, modelProvider: stri
  * SECRET's row, where an author looking at a pending value write would see them — reaches the same rule the
  * apply lane reaches through {@link refusalOf}.
  */
-export declare function gatewayKeyPairRefusal(keySlug: string, secretSlug: string, pair: LiveGatewayKeyPair, project: DesiredProject | undefined, pairContext: ProjectIdentityRefusal["pairContext"] | undefined): RefusalVerdict | null;
+export declare function gatewayKeyPairRefusal(keySlug: string, secretSlug: string, pair: LiveGatewayKeyPair, team: DesiredTeam | undefined, pairContext: TeamIdentityRefusal["pairContext"] | undefined): RefusalVerdict | null;
 /**
  * Lives here rather than in the gateway-key lane because the classifier's message names it and this module
  * must stay a leaf; the lane re-exports it.
@@ -158,13 +151,3 @@ export declare function gatewayKeyPairRefusal(keySlug: string, secretSlug: strin
 export declare const PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY = "sfdk.pendingGatewayKeyToken";
 /** The named refusal for a mint that succeeded but whose paired-Secret token write did not. */
 export declare function pendingGatewayKeyTokenRotationMessage(slug: string, secretSlug: string): string;
-/**
- * TWO shapes, because a binding is authored two ways and each is named by the spelling its AUTHOR used: a
- * managed token points at a construct in this factory, so the label names that construct's PATH — the thing
- * the author would go and edit — while an imported literal names no construct and is named by the header it
- * fills, or by its shape when a recipe binding omits one. Neither shape carries a value.
- *
- * Taken by both callers: two mirrored derivations of one label is precisely how preview came to print a
- * header for a binding apply refused by construct path.
- */
-export declare function egressCredentialBindingLabel(environmentPath: string, ruleName: unknown, ref: string, header: unknown): string;

package/dist/engine/refusals.js

@@ -12,14 +12,13 @@
 // nothing rather than guessing. No verdict can carry a credential: the classifiers read source RECIPES.
 import { connectorImmutableFields } from "../constructs/connector.js";
 import { isGatewayKeyRecipe } from "../core/gateway-key-recipe.js";
-import { isRefToken, parseRefToken } from "../core/tokens.js";
-import { ApplyError, classifyProjectIdentity, projectIdentityConflict, subsetDeepEqual, } from "./apply-core.js";
+import { ApplyError, classifyTeamIdentity, subsetDeepEqual, teamIdentityConflict, } from "./apply-core.js";
 import { isPartiallySuppliedRecipe, missingRootEnvNames, pendingCredentialWrite, } from "./secrets-apply.js";
 import { managedChatConnectionRefusalMessage } from "./connection-readiness.js";
 import { requiredConfigurationRefusalMessage } from "./connector-configuration.js";
 /**
  * The subtype lets the CLI present every deterministic refusal as `cannot apply:` without changing the
- * classifier's raw message, which diff rows also render. Project identity keeps its own richer subtype.
+ * classifier's raw message, which diff rows also render. Team identity keeps its own richer subtype.
  */
 export class AggregateRefusalError extends ApplyError {
     constructor(message, outcomes, options) {
@@ -34,8 +33,8 @@ export class AggregateRefusalError extends ApplyError {
  */
 export function refusalError(verdict, outcomes, cause) {
     const options = cause !== undefined ? { cause } : undefined;
-    if (verdict.code === "project-identity") {
-        return projectIdentityConflict(verdict.refusal, outcomes, options);
+    if (verdict.code === "team-identity") {
+        return teamIdentityConflict(verdict.refusal, outcomes, options);
     }
     return new AggregateRefusalError(verdict.message, [...outcomes], options);
 }
@@ -60,8 +59,10 @@ export function refuseIf(kind, resource, ctx, outcomes) {
  */
 export function refusalOf(kind, resource, ctx) {
     switch (kind) {
-        case "project":
-            // A project is never itself placed into a project, and it has no other pre-write refusal.
+        case "team":
+        case "role":
+        case "team-membership":
+            // None of these is placed in a team, and none has another pre-write refusal.
             return null;
         case "gateway-key":
             return gatewayKeyRefusal(resource, ctx);
@@ -79,44 +80,44 @@ export function refusalOf(kind, resource, ctx) {
         case "environment":
             return environmentRefusal(resource, ctx);
         case "skill":
-            return projectRefusal(resource, ctx);
+            return teamRefusal(resource, ctx);
         case "agent":
             return agentRefusal(resource, ctx);
         case "pipeline":
-            return projectRefusal(resource, ctx);
+            return teamRefusal(resource, ctx);
         case "workflow":
-            // A workflow takes its pipeline's project, which that pipeline's own verdict already judges.
+            // A workflow takes its pipeline's team, which that pipeline's own verdict already judges.
             return null;
     }
 }
 /**
- * The project-identity arm, shared by every stamped kind. Absent live row ⇒ nothing to conflict with; absent
- * project descriptor ⇒ this caller declares no placement to compare, which is the same inert answer.
+ * The team-identity arm, shared by every team-able kind. Absent live row ⇒ nothing to conflict with; absent
+ * team ⇒ the caller could not judge the placement, which decides nothing.
  */
-function projectRefusal(resource, ctx) {
-    return projectRefusalFor(resource.kind, resource.slug, ctx.live, ctx.project, ctx.gatewayPair);
+function teamRefusal(resource, ctx) {
+    return teamRefusalFor(resource.kind, resource.slug, ctx.live, ctx.team, ctx.gatewayPair);
 }
 /** The same arm addressed by kind+slug, for the gateway-key pair (whose two members have two slugs). */
-function projectRefusalFor(resourceKind, slug, live, project, pairContext) {
-    if (project === undefined) {
+function teamRefusalFor(resourceKind, slug, live, team, pairContext) {
+    if (team === undefined) {
         return null;
     }
-    const refusal = classifyProjectIdentity({
+    const refusal = classifyTeamIdentity({
         resourceKind,
         slug,
         live: live,
-        desired: project,
+        desired: team,
         ...(pairContext !== undefined ? { pairContext } : {}),
     });
-    return refusal !== undefined ? { code: "project-identity", refusal } : null;
+    return refusal !== undefined ? { code: "team-identity", refusal } : null;
 }
 /**
- * Order mirrors the apply decision phase exactly: a readable cross-project row outranks every other verdict,
+ * Order mirrors the apply decision phase exactly: a readable row in another team outranks every other verdict,
  * then the two source refusals. A gateway-key-backed Secret has no environment source at all and its
  * unrecoverable states belong to the PAIR, so this arm stops after the identity check for one.
  */
 function secretRefusal(resource, ctx) {
-    const identity = projectRefusal(resource, ctx);
+    const identity = teamRefusal(resource, ctx);
     if (identity !== null)
         return identity;
     const valueFrom = resource.valueFrom;
@@ -227,18 +228,18 @@ function byokPartiallySuppliedMessage(slug, modelProvider, credential, env) {
 function gatewayKeyRefusal(resource, ctx) {
     const pair = ctx.live ?? {};
     const secretSlug = ctx.gatewayPair?.secretSlug ?? "";
-    return gatewayKeyPairRefusal(resource.slug, secretSlug, pair, ctx.project, ctx.gatewayPair);
+    return gatewayKeyPairRefusal(resource.slug, secretSlug, pair, ctx.team, ctx.gatewayPair);
 }
 /**
  * Addressed by the two slugs directly, so the diff path — which renders these pair states on the paired
  * SECRET's row, where an author looking at a pending value write would see them — reaches the same rule the
  * apply lane reaches through {@link refusalOf}.
  */
-export function gatewayKeyPairRefusal(keySlug, secretSlug, pair, project, pairContext) {
-    const keyIdentity = projectRefusalFor("gateway-key", keySlug, pair.key, project, pairContext);
+export function gatewayKeyPairRefusal(keySlug, secretSlug, pair, team, pairContext) {
+    const keyIdentity = teamRefusalFor("gateway-key", keySlug, pair.key, team, pairContext);
     if (keyIdentity !== null)
         return keyIdentity;
-    const secretIdentity = projectRefusalFor("secret", secretSlug, pair.secret, project, pairContext);
+    const secretIdentity = teamRefusalFor("secret", secretSlug, pair.secret, team, pairContext);
     if (secretIdentity !== null)
         return secretIdentity;
     if (pair.key !== undefined && pair.secret === undefined) {
@@ -281,7 +282,7 @@ export function pendingGatewayKeyTokenRotationMessage(slug, secretSlug) {
  * id. Identity first, then the immutable-field refusal, then the required-configuration omission.
  */
 function connectorRefusal(resource, ctx) {
-    const identity = projectRefusal(resource, ctx);
+    const identity = teamRefusal(resource, ctx);
     if (identity !== null)
         return identity;
     const desired = ctx.resolvedDesired;
@@ -316,7 +317,7 @@ function connectorIdentityMessage(resource, changed) {
  * then the create-only OAuth app selection, then — for a ceremony-backed declaration only — the provider.
  */
 function connectionRefusal(resource, ctx) {
-    const identity = projectRefusal(resource, ctx);
+    const identity = teamRefusal(resource, ctx);
     if (identity !== null)
         return identity;
     const resolved = ctx.resolvedDesired;
@@ -359,16 +360,11 @@ function providerNotAdoptableMessage(resource, declared, live) {
         `connection if it is no longer wanted.`);
 }
 /**
- * Two rules run here, in the order apply evaluates them: pairwise-distinct, which reads only the group and so
- * decides even for a caller holding no reserved set, then connection-owned, which needs the scan.
- *
- * The GROUP is the unit on purpose. Both places an environment can bind a secret reach this arm, but as two
- * SEPARATE groups, exactly as apply refuses them: pairwise-distinct is about the egress bindings alone, and
- * merging the pull credential in would invent a refusal apply never raises, since binding one secret both
- * ways is legal. The per-ref rule is unaffected by the grouping either way.
+ * The pull credential reaches this arm as its own group; a connection-owned secret is refused, which needs
+ * the reserved-secret scan, so a caller holding none decides nothing here.
  */
 function environmentRefusal(resource, ctx) {
-    const identity = projectRefusal(resource, ctx);
+    const identity = teamRefusal(resource, ctx);
     if (identity !== null)
         return identity;
     const runtime = environmentRuntimeRefusal(resource, ctx);
@@ -377,9 +373,6 @@ function environmentRefusal(resource, ctx) {
     const resolved = ctx.resolvedDesired;
     if (resolved === undefined)
         return null;
-    const duplicate = duplicateBindingRefusal(resolved.secretRefs);
-    if (duplicate !== null)
-        return duplicate;
     const reserved = ctx.reservedProviderSecretIds;
     if (reserved === undefined)
         return null;
@@ -390,48 +383,6 @@ function environmentRefusal(resource, ctx) {
     }
     return null;
 }
-/**
- * Lives here rather than inline in the egress loop, because a rule enforced only on the apply side is
- * invisible to the preview: diff would append both bindings and the pre-flight would solicit an approval —
- * and possibly a docker build — for a change reconcile refuses without writing.
- */
-function duplicateBindingRefusal(refs) {
-    const seen = new Map(); // resolved secret id → the label of the first ref that bound it
-    for (const ref of refs) {
-        const prior = seen.get(ref.id);
-        if (prior !== undefined) {
-            return { code: "duplicate-binding", message: duplicateBindingMessage(ref.label, prior) };
-        }
-        seen.set(ref.id, ref.label);
-    }
-    return null;
-}
-/** Worded once for both callers, and value-free: two binding labels and nothing else. */
-function duplicateBindingMessage(label, prior) {
-    return (`${label} and ${prior} bind the same secret; an environment's egress credential bindings must ` +
-        `reference pairwise-distinct secrets (§6.3).`);
-}
-/**
- * TWO shapes, because a binding is authored two ways and each is named by the spelling its AUTHOR used: a
- * managed token points at a construct in this factory, so the label names that construct's PATH — the thing
- * the author would go and edit — while an imported literal names no construct and is named by the header it
- * fills, or by its shape when a recipe binding omits one. Neither shape carries a value.
- *
- * Taken by both callers: two mirrored derivations of one label is precisely how preview came to print a
- * header for a binding apply refused by construct path.
- */
-export function egressCredentialBindingLabel(environmentPath, ruleName, ref, header) {
-    const rule = `environment '${environmentPath}' egress rule '${String(ruleName)}'`;
-    if (isRefToken(ref))
-        return `${rule} → secret '${parseRefToken(ref).path.join("/")}'`;
-    const which = typeof header === "string" && header !== "" ? `credential '${header}'` : "recipe credential binding";
-    return `${rule} ${which}`;
-}
-/**
- * Worded once for BOTH places an environment can bind a secret, so the noun is the general one: the label
- * already says which of the two this is, and naming only the egress path told an author with a
- * connection-owned pull credential that their egress rules were the problem.
- */
 function reservedProviderSecretMessage(label) {
     return (`${label}: the resolved secret is owned by a connection and cannot be used as an environment credential ` +
         `binding (§6.3). The value is not echoed (§6.3).`);
@@ -442,7 +393,7 @@ function reservedProviderSecretMessage(label) {
  * apply reports the same drift again. A live row stating no harness at all is absent evidence, not a conflict.
  */
 function agentRefusal(resource, ctx) {
-    const identity = projectRefusal(resource, ctx);
+    const identity = teamRefusal(resource, ctx);
     if (identity !== null)
         return identity;
     const liveHarness = ctx.live?.harness;

package/dist/engine/role-membership-reconcile.d.ts

@@ -0,0 +1,19 @@
+import type { PlanResource } from "../core/plan.js";
+import { type ApplyOutcome, type TeamResolver } from "./apply-core.js";
+import { type PlatformApis } from "./client.js";
+/**
+ * A team's parent is fixed at create, so a live team under another parent is refused rather than moved. Name,
+ * privacy, assignment method and the declared labels are reconciled; the console owns the description.
+ */
+export declare function applyTeam(resource: PlanResource, apis: PlatformApis, outcomes: ApplyOutcome[], applied: Map<string, string>, teams: TeamResolver): Promise<void>;
+/**
+ * The platform derives a custom role's slug from its name, so the name is the key a live custom role is found
+ * by. A role's policies are a set; only the fields that drifted are sent.
+ */
+export declare function applyRole(resource: PlanResource, apis: PlatformApis, outcomes: ApplyOutcome[], applied: Map<string, string>): Promise<void>;
+/**
+ * A principal's declared rows are its full set: apply changes a row's role in place, adds a missing row and
+ * removes a row the program does not declare. It writes only `/team-memberships`, never the membership or
+ * its policy assignments, so the use policies the platform minted at agent create stay.
+ */
+export declare function applyTeamMemberships(resource: PlanResource, apis: PlatformApis, outcomes: ApplyOutcome[], applied: Map<string, string>, teams: TeamResolver): Promise<void>;

package/dist/engine/role-membership-reconcile.js

@@ -0,0 +1,276 @@
+// Teams, custom roles and the team-membership rows a program declares. A key that may not write one of these
+// gets the platform's 403, which apply records as a `refused` row and moves past, so a program that declares
+// a team runs under a weaker key for every row the key may write.
+import { createLabels, labelsPatch } from "../core/labels.js";
+import { isRefToken, refToken } from "../core/tokens.js";
+import { ApplyError, failing, getBySlugOrUndefined, mapError, } from "./apply-core.js";
+import { httpStatusOf } from "./client.js";
+import { paginate } from "./pages.js";
+import { PreflightError } from "./preflight-errors.js";
+/** The organization's catalog rows; a custom role never lives there. */
+const GLOBAL_ORGANIZATION_ID = "org_global";
+const DEFAULT_ASSIGNMENT = "AGENT_FIRST";
+/** A 403 is the platform saying this key may not write the row: recorded as refused, never fatal. */
+async function refusedOrThrow(error, ctx, outcomes, resource, id) {
+    if (httpStatusOf(error) !== 403) {
+        if (error instanceof ApplyError)
+            throw error;
+        throw new ApplyError(await mapError(error, ctx), [...outcomes], { cause: error });
+    }
+    outcomes.push({
+        path: resource.path,
+        kind: resource.kind,
+        slug: resource.slug,
+        id,
+        action: "refused",
+        reason: await mapError(error, ctx),
+    });
+}
+/**
+ * A team's parent is fixed at create, so a live team under another parent is refused rather than moved. Name,
+ * privacy, assignment method and the declared labels are reconciled; the console owns the description.
+ */
+export async function applyTeam(resource, apis, outcomes, applied, teams) {
+    const payload = resource.payload;
+    const token = refToken("team", resource.path.split("/"));
+    const surface = { kind: "team", slug: resource.slug };
+    let live;
+    try {
+        live = await getBySlugOrUndefined(() => apis.teams.getTeam({ id: resource.slug }));
+    }
+    catch (error) {
+        await refusedOrThrow(error, { ...surface, op: "get" }, outcomes, resource, "");
+        teams.markRefused(token, resource.slug);
+        return;
+    }
+    const parentTeamId = payload.parentTeamId === undefined ? undefined : await parentIdOf(payload.parentTeamId, apis, applied, resource, outcomes);
+    if (live !== undefined && (live.parentTeamId ?? undefined) !== parentTeamId) {
+        throw new ApplyError(`team '${resource.slug}': the live team's parent is ${live.parentTeamId === undefined ? "none" : `'${live.parentTeamId}'`}, ` +
+            `but this program declares ${parentTeamId === undefined ? "none" : `'${parentTeamId}'`}. A team's parent is fixed ` +
+            `when it is created, so apply never moves it. Remove the team and let apply recreate it, or declare the live parent.`, [...outcomes]);
+    }
+    let id;
+    let action;
+    try {
+        if (live === undefined) {
+            const labels = createLabels(payload.labels);
+            const body = {
+                name: payload.name,
+                slug: resource.slug,
+                ...(Object.keys(labels).length > 0 ? { labels } : {}),
+                ...(parentTeamId !== undefined ? { parentTeamId } : {}),
+                _private: payload.private,
+                assignment: payload.assignment,
+            };
+            id = (await apis.teams.createTeam({ createTeamRequest: body })).id;
+            action = "created";
+        }
+        else {
+            const labels = labelsPatch(payload.labels, live.labels);
+            const unchanged = live.name === payload.name &&
+                live._private === payload.private &&
+                (live.assignment ?? DEFAULT_ASSIGNMENT) === payload.assignment &&
+                labels === undefined;
+            if (unchanged) {
+                id = live.id;
+                action = "unchanged";
+            }
+            else {
+                const patch = {
+                    name: payload.name,
+                    _private: payload.private,
+                    assignment: payload.assignment,
+                    ...(labels !== undefined ? { labels } : {}),
+                };
+                id = (await apis.teams.updateTeam({ id: live.id, updateTeamRequest: patch })).id;
+                action = "updated";
+            }
+        }
+    }
+    catch (error) {
+        await refusedOrThrow(error, { ...surface, op: live === undefined ? "create" : "update" }, outcomes, resource, live?.id ?? "");
+        teams.markRefused(token, resource.slug);
+        return;
+    }
+    outcomes.push({ path: resource.path, kind: "team", slug: resource.slug, id, action });
+    applied.set(token, id);
+}
+async function parentIdOf(ref, apis, applied, resource, outcomes) {
+    if (isRefToken(ref)) {
+        const id = applied.get(ref);
+        if (id === undefined) {
+            throw new ApplyError(`team '${resource.slug}': its parent team was not written in this run, so the sub-team cannot be created.`, [...outcomes]);
+        }
+        return id;
+    }
+    const live = await failing(() => getBySlugOrUndefined(() => apis.teams.getTeam({ id: ref })), { kind: "team", slug: resource.slug, op: "get" }, outcomes);
+    if (live === undefined) {
+        throw new PreflightError(`team '${ref}' was not found in this organization. Create it or fix the reference.`);
+    }
+    return live.id;
+}
+/**
+ * The platform derives a custom role's slug from its name, so the name is the key a live custom role is found
+ * by. A role's policies are a set; only the fields that drifted are sent.
+ */
+export async function applyRole(resource, apis, outcomes, applied) {
+    const payload = resource.payload;
+    const surface = { kind: "role", slug: resource.slug };
+    const roles = await failing(() => paginate((page, limit) => apis.roles.listRoles({ page, limit })), { ...surface, op: "list" }, outcomes);
+    const live = roles.items.find((role) => role.name === payload.name && role.organizationId !== GLOBAL_ORGANIZATION_ID);
+    let id;
+    let action;
+    try {
+        if (live === undefined) {
+            const labels = createLabels(payload.labels);
+            const created = await apis.roles.createRole({
+                createRoleRequest: {
+                    name: payload.name,
+                    ...(payload.description !== undefined ? { description: payload.description } : {}),
+                    ...(Object.keys(labels).length > 0 ? { labels } : {}),
+                    policyIds: [...payload.policyIds],
+                },
+            });
+            id = created.id;
+            action = "created";
+        }
+        else {
+            const patch = {};
+            if (payload.description !== undefined && payload.description !== live.description) {
+                patch.description = payload.description;
+            }
+            const labels = labelsPatch(payload.labels, live.labels);
+            if (labels !== undefined)
+                patch.labels = labels;
+            if ([...live.policyIds].sort().join(" ") !== payload.policyIds.join(" ")) {
+                patch.policyIds = [...payload.policyIds];
+            }
+            if (Object.keys(patch).length === 0) {
+                id = live.id;
+                action = "unchanged";
+            }
+            else {
+                id = (await apis.roles.updateRole({ id: live.id, updateRoleRequest: patch })).id;
+                action = "updated";
+            }
+        }
+    }
+    catch (error) {
+        await refusedOrThrow(error, { ...surface, op: live === undefined ? "create" : "update" }, outcomes, resource, live?.id ?? "");
+        return;
+    }
+    outcomes.push({ path: resource.path, kind: "role", slug: resource.slug, id, action });
+    applied.set(refToken("role", resource.path.split("/")), id);
+}
+/**
+ * A principal's declared rows are its full set: apply changes a row's role in place, adds a missing row and
+ * removes a row the program does not declare. It writes only `/team-memberships`, never the membership or
+ * its policy assignments, so the use policies the platform minted at agent create stay.
+ */
+export async function applyTeamMemberships(resource, apis, outcomes, applied, teams) {
+    const payload = resource.payload;
+    const surface = { kind: "team-membership", slug: resource.slug };
+    const membershipId = await membershipIdOf(payload, resource, apis, outcomes, applied);
+    const desired = new Map();
+    for (const row of payload.rows) {
+        const body = await desiredRow(row, membershipId, resource, outcomes, applied, teams);
+        desired.set(scopeOf(body), body);
+    }
+    const live = await failing(() => paginate(async (page, limit) => {
+        const result = await apis.teamMemberships.listTeamMemberships({ membershipId, page, limit });
+        return { data: result.data, page, limit, total: result.total ?? result.data.length };
+    }), { ...surface, op: "list" }, outcomes);
+    const liveByScope = new Map();
+    for (const row of live.items)
+        liveByScope.set(scopeOf(row), row);
+    let wrote = false;
+    try {
+        for (const [scope, body] of desired) {
+            const current = liveByScope.get(scope);
+            if (current === undefined) {
+                await apis.teamMemberships.createTeamMembership({ createTeamMembershipRequest: body });
+                wrote = true;
+            }
+            else if (current.roleId !== body.roleId) {
+                await apis.teamMemberships.updateTeamMembership({
+                    id: current.id,
+                    updateTeamMembershipRequest: { roleId: body.roleId },
+                });
+                wrote = true;
+            }
+        }
+        for (const [scope, row] of liveByScope) {
+            if (desired.has(scope))
+                continue;
+            await apis.teamMemberships.deleteTeamMembership({ id: row.id });
+            wrote = true;
+        }
+    }
+    catch (error) {
+        await refusedOrThrow(error, { ...surface, op: "update" }, outcomes, resource, membershipId);
+        return;
+    }
+    outcomes.push({
+        path: resource.path,
+        kind: "team-membership",
+        slug: resource.slug,
+        id: membershipId,
+        action: wrote ? "updated" : "unchanged",
+    });
+}
+function scopeOf(row) {
+    return row.allTeams === true ? "*" : `team:${row.teamId ?? ""}`;
+}
+async function desiredRow(row, membershipId, resource, outcomes, applied, teams) {
+    let roleId = row.roleId;
+    if (isRefToken(roleId)) {
+        const id = applied.get(roleId);
+        if (id === undefined) {
+            throw new ApplyError(`team-membership '${resource.slug}' names a custom role that was not written in this run, so its rows ` +
+                `cannot be applied.`, [...outcomes]);
+        }
+        roleId = id;
+    }
+    if ("allTeams" in row)
+        return { membershipId, allTeams: true, roleId };
+    const team = await teams.desired(row.teamId, { kind: "team-membership", slug: resource.slug, op: "get" }, outcomes);
+    if (team === undefined || team.state !== "resolved") {
+        throw new ApplyError(`team-membership '${resource.slug}' names team '${row.teamId}', which this run could not resolve.`, [...outcomes]);
+    }
+    return { membershipId, teamId: team.teamId, roleId };
+}
+/**
+ * The membership the rows are written on, from the principal's own read, which names its membership. No
+ * members-list read is made, so a key with Admin at one team writes that team's rows.
+ */
+async function membershipIdOf(payload, resource, apis, outcomes, applied) {
+    const surface = { kind: "team-membership", slug: resource.slug };
+    let membershipId;
+    let label;
+    if ("agentId" in payload.principal) {
+        const ref = payload.principal.agentId;
+        const id = isRefToken(ref) ? applied.get(ref) : ref;
+        if (id === undefined) {
+            throw new ApplyError(`agent '${resource.slug}' was not written in this run, so its team memberships cannot be applied.`, [...outcomes]);
+        }
+        const agent = await failing(() => getBySlugOrUndefined(() => apis.agents.getAgent({ id })), { ...surface, op: "get" }, outcomes);
+        membershipId = agent?.membershipId;
+        label = `agent '${resource.slug}'`;
+    }
+    else {
+        const serviceAccountId = payload.principal.serviceAccountId;
+        const account = await failing(() => getBySlugOrUndefined(() => apis.serviceAccounts.getServiceAccount({ id: serviceAccountId })), { ...surface, op: "get" }, outcomes);
+        if (account === undefined) {
+            throw new ApplyError(`service account '${serviceAccountId}' was not found. The kit never creates a service account: create ` +
+                `it first, or fix the id.`, [...outcomes]);
+        }
+        membershipId = account.membershipId;
+        label = `service account '${serviceAccountId}'`;
+    }
+    if (membershipId === undefined) {
+        throw new ApplyError(`${label} has no membership in this organization, so its team rows cannot be written.`, [
+            ...outcomes,
+        ]);
+    }
+    return membershipId;
+}