@orchestraworks/cli 0.5.4 → 0.5.7

package/dist/core/plan.d.ts

@@ -1,18 +1,17 @@
 import type { TriggerDocument } from "../constructs/trigger.js";
 export type { TriggerDocument } from "../constructs/trigger.js";
 /**
- * Fixed dependency order — `PLAN_KINDS.indexOf(kind)` is the sort key for resources within a plan, so the
- * edges that force it are: `project` first, because it is the confinement scope every stamped resource
- * resolves its `projectId` against; `gateway-key` before `secret`, because a key's paired Secret takes its
- * value from the key; `secret` before `connector` and `connection`, which reference secrets for their
- * app-registration and auth material; `connector` before `connection`, which names it; `connection` and
- * `compute-provider` before `environment`, which binds a connection in its egress policy and names the
- * compute provider whose Launcher runs its machines; and `skill` before `agent`, whose `skillIds` resolve to
- * skills applied earlier in the run; `pipeline` after `agent`, whose ids its check grants name. `workflow` is
- * not reconciled with the rest: it applies in its own phase after the plan kinds, because its rules name the
- * pipeline's live stages and the pipeline's entries name the version it writes.
+ * Fixed dependency order: `PLAN_KINDS.indexOf(kind)` sorts a plan's resources. `team` comes first, because every
+ * placed row resolves its `teamId` against it; `role` before `team-membership`, whose rows name custom roles;
+ * `gateway-key` before `secret`, whose paired Secret takes the key's value; `secret` before `connector` and
+ * `connection`, which reference secrets; `connector` before `connection`, which names it; `connection` before
+ * `environment`, so an incomplete installation stops the apply before any environment is written;
+ * `compute-provider` before `environment`, which names it; `skill` before `agent`, whose `skillIds` resolve to it;
+ * `pipeline` and `team-membership` after `agent`, whose id each names. `workflow` applies in its own phase after the
+ * plan kinds, because its rules name the pipeline's live stages and the pipeline's entries name the version it
+ * writes.
  */
-export declare const PLAN_KINDS: readonly ["project", "gateway-key", "model-provider-key", "secret", "connector", "connection", "compute-provider", "environment", "skill", "agent", "pipeline", "workflow"];
+export declare const PLAN_KINDS: readonly ["team", "role", "gateway-key", "model-provider-key", "secret", "connector", "connection", "compute-provider", "environment", "skill", "agent", "pipeline", "team-membership", "workflow"];
 export type PlanKind = (typeof PLAN_KINDS)[number];
 /**
  * Names only, never values: every compound arm is a recipe resolved at apply. The `cli:` suffix is a display
@@ -39,6 +38,10 @@ export type ValueFrom = `env:${string}` | `cli:${string}` | {
         accessKeyIdSource: ValueFrom;
         secretAccessKeySource: ValueFrom;
     };
+} | {
+    fields: {
+        [name: string]: ValueFrom;
+    };
 } | {
     gatewayKey: {
         ref: string;

package/dist/core/plan.js

@@ -2,19 +2,19 @@
 // ever enters it: cross-references are symbolic `${ref:…}` tokens and declared secret values are byte-free
 // `valueFrom` recipes naming a source.
 /**
- * Fixed dependency order — `PLAN_KINDS.indexOf(kind)` is the sort key for resources within a plan, so the
- * edges that force it are: `project` first, because it is the confinement scope every stamped resource
- * resolves its `projectId` against; `gateway-key` before `secret`, because a key's paired Secret takes its
- * value from the key; `secret` before `connector` and `connection`, which reference secrets for their
- * app-registration and auth material; `connector` before `connection`, which names it; `connection` and
- * `compute-provider` before `environment`, which binds a connection in its egress policy and names the
- * compute provider whose Launcher runs its machines; and `skill` before `agent`, whose `skillIds` resolve to
- * skills applied earlier in the run; `pipeline` after `agent`, whose ids its check grants name. `workflow` is
- * not reconciled with the rest: it applies in its own phase after the plan kinds, because its rules name the
- * pipeline's live stages and the pipeline's entries name the version it writes.
+ * Fixed dependency order: `PLAN_KINDS.indexOf(kind)` sorts a plan's resources. `team` comes first, because every
+ * placed row resolves its `teamId` against it; `role` before `team-membership`, whose rows name custom roles;
+ * `gateway-key` before `secret`, whose paired Secret takes the key's value; `secret` before `connector` and
+ * `connection`, which reference secrets; `connector` before `connection`, which names it; `connection` before
+ * `environment`, so an incomplete installation stops the apply before any environment is written;
+ * `compute-provider` before `environment`, which names it; `skill` before `agent`, whose `skillIds` resolve to it;
+ * `pipeline` and `team-membership` after `agent`, whose id each names. `workflow` applies in its own phase after the
+ * plan kinds, because its rules name the pipeline's live stages and the pipeline's entries name the version it
+ * writes.
  */
 export const PLAN_KINDS = [
-    "project",
+    "team",
+    "role",
     "gateway-key",
     "model-provider-key",
     "secret",
@@ -25,6 +25,7 @@ export const PLAN_KINDS = [
     "skill",
     "agent",
     "pipeline",
+    "team-membership",
     "workflow",
 ];
 export function emptyPlanDocument(factory) {

package/dist/engine/apply-core.d.ts

@@ -1,10 +1,11 @@
 import { PLAN_FEATURE_DISABLED_CODE } from "../cli/core/errors.js";
 import type { PlanKind, PlanResource } from "../core/plan.js";
+import { type PlatformApis } from "./client.js";
 /**
  * `needs-attention` is a connection created or observed `NEEDS_ATTENTION` with a server-owned
  * `auth.authorizationUrl` — non-fatal: apply continues and the context collects its setup handoff.
  */
-export type Action = "created" | "updated" | "unchanged" | "needs-attention";
+export type Action = "created" | "updated" | "unchanged" | "needs-attention" | "refused";
 /** `id` is the resolved canonical id. */
 export interface ApplyOutcome {
     path: string;
@@ -21,6 +22,8 @@ export interface ApplyOutcome {
      * itself, whose sensitivity is output-side. Value-free: it says THAT bytes were written, never what.
      */
     sensitive?: "credential-value";
+    /** Set on a `refused` row: why the platform would not write it, in the platform's own words. */
+    reason?: string;
     /**
      * Set when the bytes this apply wrote REPLACED the live value of a credential that already existed, from a
      * source the author did not type at the prompt. Never present without {@link sensitive}: a replacement is a
@@ -79,101 +82,102 @@ export declare class ApplyError extends Error {
     });
 }
 /**
- *   - `resolved`        — the Factory's project exists and its canonical id is in hand. Apply only ever
- *                         reaches the comparison in this state.
- *   - `pending-managed` — a MANAGED project declaration whose row does not exist yet, which only diff sees.
- *                         No live stamp can equal a project that has not been created, so every readable row
+ *   - `resolved`        — the declared team exists and its canonical id is in hand. `shared` marks Shared, the
+ *                         team a row that names none is created in.
+ *   - `shared`          — the row names no team, so it is in Shared, and no live row has needed Shared's id
+ *                         yet. A live row that reports a team is judged only after `TeamResolver.judged` has
+ *                         read Shared, so a platform that serves no teams is never asked for one.
+ *   - `pending-managed` — a team this program manages whose row does not exist yet, which only diff sees. No
+ *                         live row can sit in a team that has not been created, so every readable row
  *                         conflicts; the payload names the declared plan slug and never invents an id.
- *   - `none`            — the declaration manages no project, so the field is unmanaged and inert.
  */
-export type DesiredProject = {
+export type DesiredTeam = {
     state: "resolved";
-    projectId: string;
+    teamId: string;
+    shared?: boolean;
 } | {
-    state: "pending-managed";
-    projectRef: string;
+    state: "shared";
 } | {
-    state: "none";
+    state: "pending-managed";
+    teamRef: string;
 };
 /**
- * No lane spells this mapping itself, because `undefined` must mean "the field is UNMANAGED and inert" and
- * never "commons": a lane writing its own ternary could get that backwards and start refusing every
- * project-less declaration whose live row someone moved in the console.
- */
-export declare function desiredProjectOf(projectId: string | undefined): DesiredProject;
-/**
- * The diff-side twin, for the one state apply never sees. `projectRef` is the project's DECLARED PLAN SLUG,
- * the single canonical public representation of a pending project. `undefined` maps to `none` rather than to
- * a fabricated reference: the synthesized `${ref:project:…}` token is explicitly not one.
- */
-export declare function pendingDesiredProject(projectRef: string | undefined): DesiredProject;
-/**
- * `liveProjectId` is normalized: the generated client represents a commons row as `projectId: undefined`, and
- * no public payload may expose that — commons is `null`.
+ * `liveTeamId` is `null` for a live row that reports no team, which the platform reads as Shared.
  *
- * `pairContext` is LIFECYCLE-NEUTRAL. It says only that two slugs are the members of one gateway-key pair,
- * claiming nothing about whether that pair is steady, mid-mint, adopted or resumed, which is what makes its
- * two remedies safe at every point in the mint protocol.
+ * `pairContext` says only that two slugs are the members of one gateway-key pair, claiming nothing about
+ * where that pair is in the mint protocol, which is what makes its remedy safe at every point.
  */
-export type ProjectIdentityRefusal = {
+export type TeamIdentityRefusal = {
     resourceKind: string;
     slug: string;
-    liveProjectId: string | null;
-    desiredProject: {
-        state: "resolved";
-        projectId: string;
-    } | {
-        state: "pending-managed";
-        projectRef: string;
-    };
+    liveTeamId: string | null;
+    desiredTeam: DesiredTeam;
     pairContext?: {
         kind: "gateway-key-secret";
         gatewayKeySlug: string;
         secretSlug: string;
     };
 };
-/**
- * A distinct class rather than an `ApplyError` carrying similar text, so `instanceof` and `error.code`
- * survive all four conversion boundaries the raised error passes through.
- */
-export declare class ProjectIdentityConflictError extends ApplyError {
-    readonly code = "PROJECT_IDENTITY_CONFLICT";
-    readonly refusal: ProjectIdentityRefusal;
-    constructor(refusal: ProjectIdentityRefusal, outcomes: ApplyOutcome[], options?: {
+/** A distinct class, so `instanceof` and `error.code` survive every boundary the raised error crosses. */
+export declare class TeamIdentityConflictError extends ApplyError {
+    readonly code = "TEAM_IDENTITY_CONFLICT";
+    readonly refusal: TeamIdentityRefusal;
+    constructor(refusal: TeamIdentityRefusal, outcomes: ApplyOutcome[], options?: {
         cause?: unknown;
     });
 }
-/**
- * Every lane calls this rather than `new`-ing the error, so the outcomes are always COPIED: a later mutation
- * of the caller's accumulator cannot rewrite the partial progress a raised error already reported.
- */
-export declare function projectIdentityConflict(refusal: ProjectIdentityRefusal, outcomes: ApplyOutcome[], options?: {
+/** Copies the outcomes, so a later push to the caller's accumulator cannot rewrite the progress reported. */
+export declare function teamIdentityConflict(refusal: TeamIdentityRefusal, outcomes: ApplyOutcome[], options?: {
     cause?: unknown;
-}): ProjectIdentityConflictError;
+}): TeamIdentityConflictError;
 /**
- * NEVER throws, so the diff path can use it as a per-row verdict — a throw would abort the whole preview.
- *
- * `live` is the LIVE ROW rather than a bare id deliberately: an absent row has no identity to conflict with
- * and must still apply as a create, whereas a readable row whose `projectId` is absent really is in the org
- * commons. Passing `live?.projectId` would collapse those two and refuse every create. The commons
- * normalization happens here and only here.
+ * NEVER throws, so the diff path can use it as a per-row verdict. `live` is the live row rather than a bare
+ * id: an absent row has nothing to conflict with and still applies as a create.
  */
-export declare function classifyProjectIdentity(input: {
+export declare function classifyTeamIdentity(input: {
     resourceKind: string;
     slug: string;
     live: {
-        projectId?: string | null;
+        teamId?: string | null;
     } | undefined;
-    desired: DesiredProject;
-    pairContext?: ProjectIdentityRefusal["pairContext"];
-}): ProjectIdentityRefusal | undefined;
+    desired: DesiredTeam;
+    pairContext?: TeamIdentityRefusal["pairContext"];
+}): TeamIdentityRefusal | undefined;
+/**
+ * The one formatter, called by the error's own message and by every diff renderer, so apply and preview cannot
+ * word one conflict two ways.
+ */
+export declare function describeTeamIdentityRefusal(refusal: TeamIdentityRefusal): string;
+/**
+ * Resolves the team each row names to the id apply compares and sends. A row that names none is in Shared;
+ * a managed team is read from `applied` once its phase has run; an imported team is read by id or slug once
+ * per run. In a preview, a managed team that does not exist yet is `pending-managed`, and an import the
+ * caller cannot read is left unjudged rather than refused.
+ */
+export interface TeamResolver {
+    desired(raw: unknown, ctx: ErrorSurface, outcomes: ApplyOutcome[]): Promise<DesiredTeam | undefined>;
+    /**
+     * The team to judge `live` against. A row in Shared whose live row reports a team needs Shared's id to tell
+     * Shared from another team, so Shared is read here and only then.
+     */
+    judged(team: DesiredTeam | undefined, live: unknown, ctx: ErrorSurface, outcomes: ApplyOutcome[]): Promise<DesiredTeam | undefined>;
+    /** Shared's row, the organization's built-in team. */
+    shared(ctx: ErrorSurface, outcomes: ApplyOutcome[]): Promise<{
+        id: string;
+    }>;
+    /** A managed team the platform refused to write, so a row placed in it stops with a named reason. */
+    markRefused(token: string, slug: string): void;
+}
+export declare function createTeamResolver(apis: PlatformApis, applied: ReadonlyMap<string, string>, options?: {
+    preview?: {
+        pendingManaged: ReadonlyMap<string, string>;
+    };
+}): TeamResolver;
 /**
- * The one formatter, called by the error's own message and by all three diff renderers, so apply and preview
- * cannot word the same conflict differently. It offers only remedies the affected kind actually supports, and
- * every create-in-the-intended-project remedy insists on a NEW slug because reusing the old one just
- * rediscovers or collides with the row already there.
+ * The id a create body carries: the resolved team, or nothing for Shared, so a team-less row's body is the
+ * one the platform has always taken. Every update body strips the field, because a team is fixed at create.
  */
-export declare function describeProjectIdentityRefusal(refusal: ProjectIdentityRefusal): string;
+export declare function stampTeam(body: Record<string, unknown>, desired: DesiredTeam | undefined): void;
 /**
  * Records the outcome row plus its `${ref:kind:path}` → canonical-id entry, so a later resource can resolve a
  * reference to it. `markers` is stamped by the lane that PERFORMED the write, because only that lane knows

package/dist/engine/apply-core.js

@@ -6,7 +6,8 @@
 // Value hygiene: nothing here ever sees a secret value. `mapError` reads the platform's `ApiError` body,
 // whose message/code/details triple is non-secret by the platform's own contract.
 import { PLAN_FEATURE_DISABLED_CODE, readApiError } from "../cli/core/errors.js";
-import { refToken } from "../core/tokens.js";
+import { isRefToken, refToken } from "../core/tokens.js";
+import { SHARED_TEAM_SLUG } from "../constructs/team.js";
 import { httpStatusOf } from "./client.js";
 import { PreflightError, RedactedRefError } from "./preflight.js";
 /**
@@ -35,123 +36,139 @@ export class ApplyError extends Error {
         this.outcomes = outcomes;
     }
 }
-/**
- * No lane spells this mapping itself, because `undefined` must mean "the field is UNMANAGED and inert" and
- * never "commons": a lane writing its own ternary could get that backwards and start refusing every
- * project-less declaration whose live row someone moved in the console.
- */
-export function desiredProjectOf(projectId) {
-    return projectId === undefined ? { state: "none" } : { state: "resolved", projectId };
-}
-/**
- * The diff-side twin, for the one state apply never sees. `projectRef` is the project's DECLARED PLAN SLUG,
- * the single canonical public representation of a pending project. `undefined` maps to `none` rather than to
- * a fabricated reference: the synthesized `${ref:project:…}` token is explicitly not one.
- */
-export function pendingDesiredProject(projectRef) {
-    return projectRef === undefined ? { state: "none" } : { state: "pending-managed", projectRef };
-}
-/**
- * A distinct class rather than an `ApplyError` carrying similar text, so `instanceof` and `error.code`
- * survive all four conversion boundaries the raised error passes through.
- */
-export class ProjectIdentityConflictError extends ApplyError {
-    code = "PROJECT_IDENTITY_CONFLICT";
+/** A distinct class, so `instanceof` and `error.code` survive every boundary the raised error crosses. */
+export class TeamIdentityConflictError extends ApplyError {
+    code = "TEAM_IDENTITY_CONFLICT";
     refusal;
     constructor(refusal, outcomes, options) {
-        super(describeProjectIdentityRefusal(refusal), outcomes, options);
-        this.name = "ProjectIdentityConflictError";
+        super(describeTeamIdentityRefusal(refusal), outcomes, options);
+        this.name = "TeamIdentityConflictError";
         this.refusal = refusal;
     }
 }
-/**
- * Every lane calls this rather than `new`-ing the error, so the outcomes are always COPIED: a later mutation
- * of the caller's accumulator cannot rewrite the partial progress a raised error already reported.
- */
-export function projectIdentityConflict(refusal, outcomes, options) {
-    return new ProjectIdentityConflictError(refusal, [...outcomes], options);
+/** Copies the outcomes, so a later push to the caller's accumulator cannot rewrite the progress reported. */
+export function teamIdentityConflict(refusal, outcomes, options) {
+    return new TeamIdentityConflictError(refusal, [...outcomes], options);
 }
 /**
- * NEVER throws, so the diff path can use it as a per-row verdict — a throw would abort the whole preview.
- *
- * `live` is the LIVE ROW rather than a bare id deliberately: an absent row has no identity to conflict with
- * and must still apply as a create, whereas a readable row whose `projectId` is absent really is in the org
- * commons. Passing `live?.projectId` would collapse those two and refuse every create. The commons
- * normalization happens here and only here.
+ * NEVER throws, so the diff path can use it as a per-row verdict. `live` is the live row rather than a bare
+ * id: an absent row has nothing to conflict with and still applies as a create.
  */
-export function classifyProjectIdentity(input) {
+export function classifyTeamIdentity(input) {
     const { resourceKind, slug, live, desired, pairContext } = input;
-    if (live === undefined || desired.state === "none") {
+    if (live === undefined)
         return undefined;
+    const liveTeamId = live.teamId ?? null;
+    if (desired.state === "resolved") {
+        if (liveTeamId === desired.teamId)
+            return undefined;
+        if (liveTeamId === null && desired.shared === true)
+            return undefined;
     }
-    const liveProjectId = live.projectId ?? null;
-    if (desired.state === "resolved" && liveProjectId === desired.projectId) {
+    if (desired.state === "shared" && liveTeamId === null)
         return undefined;
-    }
     return {
         resourceKind,
         slug,
-        liveProjectId,
-        desiredProject: desired,
+        liveTeamId,
+        desiredTeam: desired,
         ...(pairContext !== undefined ? { pairContext } : {}),
     };
 }
 /**
- * Pinned to the real construct statics by a test, so a construct that gains or loses an importer fails the
- * build instead of letting the message lie. A kind absent from the table has NO importer, which is the
- * truthful default: the formatter must never recommend one that does not exist.
+ * The one formatter, called by the error's own message and by every diff renderer, so apply and preview cannot
+ * word one conflict two ways.
  */
-const IMPORTERS_BY_RESOURCE_KIND = {
-    agent: ["Agent.fromSlug", "Agent.fromId"],
-    connection: ["Connection.fromSlug", "Connection.fromId", "Connection.fromEnv"],
-    connector: ["Connector.fromSlug", "Connector.fromId"],
-    environment: ["Environment.fromSlug"],
-    secret: ["Secret.fromSlug", "Secret.fromId"],
-    skill: ["Skill.fromSlug", "Skill.fromId"],
-    // No entry — and no importer — for `gateway-key`, `workflow`, and `trigger`.
-};
-/** `a`, `a or b`, `a, b or c` — the importer list, read out in prose. */
-function orList(items) {
-    return items.length <= 1
-        ? items.join("")
-        : `${items.slice(0, -1).join(", ")} or ${items[items.length - 1]}`;
+export function describeTeamIdentityRefusal(refusal) {
+    const { resourceKind, slug, liveTeamId, desiredTeam, pairContext } = refusal;
+    const livePlacement = liveTeamId === null ? "Shared" : `team '${liveTeamId}'`;
+    const desiredPlacement = desiredTeam.state === "resolved"
+        ? desiredTeam.shared === true
+            ? `Shared (team '${desiredTeam.teamId}')`
+            : `team '${desiredTeam.teamId}'`
+        : desiredTeam.state === "shared"
+            ? "Shared"
+            : `the team '${desiredTeam.teamRef}', which apply has not created yet`;
+    const remedy = pairContext !== undefined
+        ? `A gateway key and its paired Secret are one unit (GatewayKey '${pairContext.gatewayKeySlug}' and ` +
+            `Secret '${pairContext.secretSlug}'), so act on both: remove both rows and let apply recreate both in ` +
+            `the declared team, or declare both back in ${livePlacement}.`
+        : `Remove the live row and let apply recreate it in the declared team, or declare it back in ` +
+            `${livePlacement}.`;
+    return (`${resourceKind} '${slug}': the live row is in ${livePlacement}, but this program places it in ` +
+        `${desiredPlacement}. A row's team is fixed when it is created, so apply never moves it. ${remedy}`);
 }
-/**
- * The one formatter, called by the error's own message and by all three diff renderers, so apply and preview
- * cannot word the same conflict differently. It offers only remedies the affected kind actually supports, and
- * every create-in-the-intended-project remedy insists on a NEW slug because reusing the old one just
- * rediscovers or collides with the row already there.
- */
-export function describeProjectIdentityRefusal(refusal) {
-    const { resourceKind, slug, liveProjectId, desiredProject, pairContext } = refusal;
-    const livePlacement = liveProjectId === null ? "the org commons (no project)" : `project '${liveProjectId}'`;
-    const desiredPlacement = desiredProject.state === "resolved"
-        ? `project '${desiredProject.projectId}'`
-        : `the managed project '${desiredProject.projectRef}', which apply has not created yet`;
-    const newSlugReason = `reusing an existing slug would rediscover or collide with the row that is already there`;
-    const remedy = (() => {
-        if (pairContext !== undefined) {
-            return (`A gateway key and its paired Secret are one unit (GatewayKey '${pairContext.gatewayKeySlug}' and ` +
-                `Secret '${pairContext.secretSlug}'), so both remedies act on the pair: either remove BOTH ` +
-                `declarations from this Factory, which leaves whatever exists untouched where it is for a human to ` +
-                `inspect or clean up; or declare BOTH members under NEW slugs in the intended project, which mints a ` +
-                `fresh pair (${newSlugReason}). Importing the paired Secret is never a remedy: its value is ` +
-                `meaningful only as the counterpart of one specific minted key, and may be an inert placeholder or a ` +
-                `stale credential.`);
+export function createTeamResolver(apis, applied, options = {}) {
+    const reads = new Map();
+    const refused = new Map();
+    const read = (ref) => {
+        let found = reads.get(ref);
+        if (found === undefined) {
+            found = getBySlugOrUndefined(() => apis.teams.getTeam({ id: ref }));
+            reads.set(ref, found);
         }
-        const importers = IMPORTERS_BY_RESOURCE_KIND[resourceKind];
-        if (importers === undefined) {
-            return (`A ${resourceKind} has no importer, so the existing row cannot be referenced from a declaration: ` +
-                `either declare it under a NEW slug in the intended project (${newSlugReason}), or stop declaring ` +
-                `that row in this Factory and leave it where it is.`);
+        return found;
+    };
+    const shared = async (ctx, outcomes) => {
+        const row = await failing(() => read(SHARED_TEAM_SLUG), ctx, outcomes);
+        if (row === undefined) {
+            throw new ApplyError(`${ctx.kind} '${ctx.slug}': the organization's Shared team could not be read. Check that the key ` +
+                `may read teams in this organization.`, [...outcomes]);
         }
-        return (`Either keep the live placement and reference the existing row instead of declaring it ` +
-            `(${orList(importers)}), or declare it under a NEW slug in the intended project (${newSlugReason}) ` +
-            `and repoint whatever references it.`);
-    })();
-    return (`${resourceKind} '${slug}': the live row is in ${livePlacement}, but this Factory declares ` +
-        `${desiredPlacement}. A project placement is identity, not drift — orchestra never moves an existing row ` +
-        `into another project. ${remedy}`);
+        return row;
+    };
+    return {
+        shared,
+        markRefused(token, slug) {
+            refused.set(token, slug);
+        },
+        async judged(team, live, ctx, outcomes) {
+            if (team?.state !== "shared")
+                return team;
+            const liveTeamId = live?.teamId ?? null;
+            if (liveTeamId === null)
+                return team;
+            const row = await shared(ctx, outcomes);
+            return { state: "resolved", teamId: row.id, shared: true };
+        },
+        async desired(raw, ctx, outcomes) {
+            if (typeof raw !== "string" || raw === "")
+                return { state: "shared" };
+            if (isRefToken(raw)) {
+                const id = applied.get(raw);
+                if (id !== undefined)
+                    return { state: "resolved", teamId: id };
+                const refusedSlug = refused.get(raw);
+                if (refusedSlug !== undefined) {
+                    throw new ApplyError(`${ctx.kind} '${ctx.slug}' is placed in team '${refusedSlug}', which the platform refused to write ` +
+                        `with this key, so it cannot be applied.`, [...outcomes]);
+                }
+                const pending = options.preview?.pendingManaged.get(raw);
+                if (pending !== undefined)
+                    return { state: "pending-managed", teamRef: pending };
+                throw new ApplyError(`${ctx.kind} '${ctx.slug}' names team reference ${raw}, which this run has not resolved.`, [...outcomes]);
+            }
+            const row = options.preview !== undefined
+                ? await read(raw).catch(() => undefined)
+                : await failing(() => read(raw), ctx, outcomes);
+            if (row === undefined) {
+                if (options.preview !== undefined)
+                    return undefined;
+                throw new PreflightError(`team '${raw}' was not found in this organization. Create it or fix the reference.`);
+            }
+            return { state: "resolved", teamId: row.id, ...(row.slug === SHARED_TEAM_SLUG || row.builtIn === true ? { shared: true } : {}) };
+        },
+    };
+}
+/**
+ * The id a create body carries: the resolved team, or nothing for Shared, so a team-less row's body is the
+ * one the platform has always taken. Every update body strips the field, because a team is fixed at create.
+ */
+export function stampTeam(body, desired) {
+    if (desired?.state === "resolved" && desired.shared !== true)
+        body.teamId = desired.teamId;
+    else
+        delete body.teamId;
 }
 /**
  * Records the outcome row plus its `${ref:kind:path}` → canonical-id entry, so a later resource can resolve a
@@ -336,6 +353,14 @@ export async function mapError(error, ctx) {
             return `${ctx.kind} '${ctx.slug}': the platform refused the ${ctx.op} (403): ${body.message}`;
         }
     }
+    // The local environment answers every route outside its subset 501 with a sentence naming what it serves, which
+    // says more than "a platform error" would.
+    if (status === 501) {
+        const offender = await platformErrorMessage(error);
+        if (offender !== undefined && offender.trim() !== "") {
+            return `${ctx.kind} '${ctx.slug}': the platform does not serve this ${ctx.op} (501): ${offender}`;
+        }
+    }
     if (status === 401 || status === 403) {
         return (`${ctx.kind} '${ctx.slug}': the platform returned ${status}. The token is expired or cannot access ` +
             `the resolved organization — re-login (\`orchestra auth login\`) or fix ORCHESTRA_ORGANIZATION_ID.`);

package/dist/engine/client.d.ts

@@ -1,4 +1,4 @@
-import { AgentsApi, ComputeProvidersApi, ConnectionInstallLinksApi, ConnectionsApi, ConnectorsApi, ProvidersApi, EnvironmentsApi, type FetchAPI, FilesApi, GatewayKeysApi, GroupsApi, ModelProviderKeysApi, OrganizationsApi, PipelinesApi, ProjectsApi, SecretsApi, SkillsApi, TriggersApi, UserGrantsApi, VolumesApi, WorkflowsApi } from "@orchestraworks/client";
+import { AgentsApi, ComputeProvidersApi, ConnectionInstallLinksApi, ConnectionsApi, ConnectorsApi, ProvidersApi, EnvironmentsApi, type FetchAPI, FilesApi, GatewayKeysApi, ImagesApi, ModelProviderKeysApi, OrganizationMembershipsApi, OrganizationsApi, PipelinesApi, PoliciesApi, RolesApi, SecretsApi, ServiceAccountsApi, SkillsApi, TeamMembershipsApi, TeamsApi, TriggersApi, UserGrantsApi, VolumesApi, WorkflowsApi } from "@orchestraworks/client";
 import { type PlatformTarget } from "../cli/core/platform-client.js";
 /**
  * `target` is exposed so a downstream phase can re-check the transport rule without re-plumbing the base URL,
@@ -8,11 +8,21 @@ import { type PlatformTarget } from "../cli/core/platform-client.js";
 export interface PlatformApis {
     readonly target: PlatformTarget;
     readonly organizations: OrganizationsApi;
-    readonly projects: ProjectsApi;
+    readonly teams: TeamsApi;
+    readonly teamMemberships: TeamMembershipsApi;
+    readonly roles: RolesApi;
+    /** Read only: apply finds an agent's or a service account's membership to write its team rows on. */
+    readonly organizationMemberships: OrganizationMembershipsApi;
+    /** Read only: an imported service account must exist; the kit creates none. */
+    readonly serviceAccounts: ServiceAccountsApi;
+    /** Read only: a custom role's policies are imported by id. */
+    readonly policies: PoliciesApi;
     readonly secrets: SecretsApi;
     readonly environments: EnvironmentsApi;
     readonly skills: SkillsApi;
     readonly files: FilesApi;
+    /** Apply's image phase alone: an image is uploaded and read, never declared as a plan kind. */
+    readonly images: ImagesApi;
     readonly agents: AgentsApi;
     readonly connections: ConnectionsApi;
     readonly connectors: ConnectorsApi;
@@ -31,8 +41,6 @@ export interface PlatformApis {
     readonly workflows: WorkflowsApi;
     readonly triggers: TriggersApi;
     readonly pipelines: PipelinesApi;
-    /** Read only: a rule or a stage gate names a group, and orchestra declares none. */
-    readonly groups: GroupsApi;
     /** A grant is driven, never declared: no plan kind, no reconcile phase, so the CLI alone uses this. */
     readonly userGrants: UserGrantsApi;
 }

package/dist/engine/client.js

@@ -5,7 +5,7 @@
 //
 // Secret hygiene invariants this module upholds: the API token travels only in the `Authorization` header and
 // never the URL; no middleware logs bodies; and no thrown error message interpolates the token.
-import { AgentsApi, ComputeProvidersApi, ConnectionInstallLinksApi, ConnectionsApi, ConnectorsApi, ProvidersApi, EnvironmentsApi, FilesApi, GatewayKeysApi, GroupsApi, ModelProviderKeysApi, OrganizationsApi, PipelinesApi, ProjectsApi, SecretsApi, SkillsApi, TriggersApi, UserGrantsApi, VolumesApi, WorkflowsApi, } from "@orchestraworks/client";
+import { AgentsApi, ComputeProvidersApi, ConnectionInstallLinksApi, ConnectionsApi, ConnectorsApi, ProvidersApi, EnvironmentsApi, FilesApi, GatewayKeysApi, ImagesApi, ModelProviderKeysApi, OrganizationMembershipsApi, OrganizationsApi, PipelinesApi, PoliciesApi, RolesApi, SecretsApi, ServiceAccountsApi, SkillsApi, TeamMembershipsApi, TeamsApi, TriggersApi, UserGrantsApi, VolumesApi, WorkflowsApi, } from "@orchestraworks/client";
 import { platformConfiguration } from "../cli/core/platform-client.js";
 /**
  * `fetchApi` is a test seam; production leaves it undefined and the SDK uses global `fetch`. A target with no
@@ -18,11 +18,17 @@ export function makeApis(target, fetchApi) {
     return {
         target,
         organizations: new OrganizationsApi(configuration),
-        projects: new ProjectsApi(configuration),
+        teams: new TeamsApi(configuration),
+        teamMemberships: new TeamMembershipsApi(configuration),
+        roles: new RolesApi(configuration),
+        organizationMemberships: new OrganizationMembershipsApi(configuration),
+        serviceAccounts: new ServiceAccountsApi(configuration),
+        policies: new PoliciesApi(configuration),
         secrets: new SecretsApi(configuration),
         environments: new EnvironmentsApi(configuration),
         skills: new SkillsApi(configuration),
         files: new FilesApi(configuration),
+        images: new ImagesApi(configuration),
         agents: new AgentsApi(configuration),
         connections: new ConnectionsApi(configuration),
         connectors: new ConnectorsApi(configuration),
@@ -35,7 +41,6 @@ export function makeApis(target, fetchApi) {
         workflows: new WorkflowsApi(configuration),
         triggers: new TriggersApi(configuration),
         pipelines: new PipelinesApi(configuration),
-        groups: new GroupsApi(configuration),
         userGrants: new UserGrantsApi(configuration),
     };
 }

package/dist/engine/compute-provider-reconcile.js

@@ -1,5 +1,5 @@
 // The compute provider apply lane: find the record by its slug, then POST it, or PATCH the drifted name and
-// the whole Azure block. The record is organization-wide, so no body carries a project.
+// the whole Azure block. The record is organization-wide, so no body carries a team.
 //
 // Key hygiene: a create answers the record's key once. The key leaves this lane through exactly one seam,
 // the caller's `onKey` step, and never enters an outcome, the `applied` id map, a thrown message, `plan.json`