@intentius/chant-lexicon-render 0.124.31 → 0.124.33

package/dist/op/activities/render-apply.js

@@ -0,0 +1,873 @@
+/**
+ * Render native applier.
+ *
+ * Peer of `flyApply`: a direct-REST applier that does its own diff, owned-only
+ * prune, and mutation waiting. Render has no server-side declarative apply
+ * (Blueprints are repo-driven, not API-driven), so this loop is hand-rolled —
+ * find-by-name, then create or PATCH per resource, resolve cross-resource ids
+ * as they become known, wait each service's deploy to `live`, and prune only
+ * what chant owns.
+ *
+ * Input is the serializer's output: a JSON object keyed by entity name, each
+ * value a single Render create request `{ kind, entityType, endpoint, method,
+ * name, body, pathParams? }`. Bodies may carry three markers the applier
+ * resolves at apply time:
+ *   - `{ $ref: "<entity>" }`  → the live id of a declared entity (must apply first)
+ *   - `{ $attr: { entity, attribute } }` → an attribute of a live entity
+ *     (`id`, `dashboardUrl`, or a datastore's connection string, read from the
+ *     `/connection-info` side endpoint)
+ *   - `{ $owner: true }` → the workspace id, when neither the author nor
+ *     `RENDER_OWNER_ID` named one; resolved once from `GET /owners`
+ *
+ * Identity. Render assigns opaque ids on create; the *name* is the reconcile
+ * key. Services are unique-by-name per workspace (Render enforces it); for the
+ * other kinds chant treats the name as unique within its scope (owner, or the
+ * parent project/service) and takes the first exact match.
+ *
+ * Endpoint override via `RENDER_API_BASE_URL` (or an explicit `endpoint` arg)
+ * so the same code points at api.render.com or a local stand-in; auth is a
+ * bearer token from `RENDER_API_KEY` (or `token`).
+ */
+import { readFileSync } from "node:fs";
+import { sleep } from "@intentius/chant/op";
+import { hasOwnershipMarker, readOwnership } from "@intentius/chant/ownership";
+import { applyResult, } from "@intentius/chant/apply";
+import { RENDER_ENV_OWNERSHIP_KEYS } from "../../ownership.js";
+import { CATALOG, ENTITY_TYPES, ENTITY_TYPE_OF_SERVICE, catalogEntry, isServiceEntityType, } from "../../catalog.js";
+import { isAttrMarker, isOwnerMarker, isRefMarker, } from "../../serializer.js";
+/** Default API host when neither an `endpoint` arg nor `RENDER_API_BASE_URL` is set. */
+export const DEFAULT_RENDER_BASE_URL = "https://api.render.com/v1";
+/** Render's list page cap. */
+const PAGE_LIMIT = 100;
+/** Deploy states that mean the deploy is finished. */
+const DEPLOY_LIVE = new Set(["live"]);
+const DEPLOY_FAILED = new Set(["build_failed", "update_failed", "canceled", "pre_deploy_failed", "deactivated"]);
+// ── Pure helpers (unit-testable without http) ─────────────────────────────────
+/**
+ * Resolve the API base URL: an explicit `endpoint` arg wins, then
+ * `RENDER_API_BASE_URL`, then api.render.com. Trailing slash stripped. Pure.
+ */
+export function resolveEndpoint(args = {}, env = process.env) {
+    const base = args.endpoint || env.RENDER_API_BASE_URL || DEFAULT_RENDER_BASE_URL;
+    return base.replace(/\/$/, "");
+}
+/** Parse the serializer's JSON output into a plan. Pure. */
+export function parsePlan(content) {
+    return JSON.parse(content);
+}
+/** Collect the entity names a value references through `$ref`/`$attr` markers. Pure. */
+export function collectDependencies(value, acc = new Set()) {
+    if (isRefMarker(value)) {
+        acc.add(value.$ref);
+        return acc;
+    }
+    if (isAttrMarker(value)) {
+        acc.add(value.$attr.entity);
+        return acc;
+    }
+    if (Array.isArray(value)) {
+        for (const v of value)
+            collectDependencies(v, acc);
+    }
+    else if (value && typeof value === "object") {
+        for (const v of Object.values(value))
+            collectDependencies(v, acc);
+    }
+    return acc;
+}
+/**
+ * Order the plan for apply: by catalog order (projects → environments →
+ * datastores/env groups → services → disks/domains → webhooks), and within
+ * that so every `$ref`/`$attr` target precedes its referrer. Throws on a cycle
+ * or a dangling reference — both are authoring errors worth naming. Pure.
+ */
+export function orderPlan(plan) {
+    const entries = Object.entries(plan);
+    const byName = new Map(entries);
+    const deps = new Map();
+    for (const [name, req] of entries) {
+        const d = collectDependencies({ body: req.body, pathParams: req.pathParams });
+        for (const dep of d) {
+            if (!byName.has(dep)) {
+                throw new Error(`render plan entry "${name}" references "${dep}", which the plan does not declare`);
+            }
+        }
+        d.delete(name);
+        deps.set(name, d);
+    }
+    const rank = (name) => catalogEntry(byName.get(name).entityType).order;
+    const sortedNames = entries.map(([n]) => n).sort((a, b) => rank(a) - rank(b));
+    // Take the first ready entry in catalog order each time, so a resource is
+    // only pulled ahead of its rank when something before it still waits on a
+    // dependency (never behind a lower-ranked one that happens to be ready).
+    const out = [];
+    const done = new Set();
+    const remaining = [...sortedNames];
+    while (remaining.length > 0) {
+        const idx = remaining.findIndex((n) => [...deps.get(n)].every((d) => done.has(d)));
+        if (idx < 0) {
+            throw new Error(`render plan has a reference cycle among: ${remaining.join(", ")}`);
+        }
+        const [n] = remaining.splice(idx, 1);
+        out.push([n, byName.get(n)]);
+        done.add(n);
+    }
+    return out;
+}
+/** Structural equality over two values, key-order-insensitive. Pure. */
+export function configEqual(a, b) {
+    return canonical(a) === canonical(b);
+}
+function canonical(v) {
+    return JSON.stringify(sortKeys(v));
+}
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v && typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            out[k] = sortKeys(v[k]);
+        }
+        return out;
+    }
+    return v;
+}
+/**
+ * The PATCH body for a live resource: the declared values of the catalog's
+ * patchable fields that differ from what is live. Only fields the author set
+ * are compared — an omitted field is "leave as is", never "reset to default".
+ * Returns `undefined` when nothing differs. Pure.
+ */
+export function diffForPatch(entry, desired, live) {
+    const patch = {};
+    for (const field of entry.patchFields) {
+        if (!(field in desired) || desired[field] === undefined)
+            continue;
+        const want = desired[field];
+        const have = live[field];
+        if (want && typeof want === "object" && !Array.isArray(want) && have && typeof have === "object") {
+            // Nested objects (serviceDetails, image): compare only the declared keys.
+            const sub = subsetDiff(want, have);
+            if (sub !== undefined)
+                patch[field] = want;
+        }
+        else if (!configEqual(want, have)) {
+            patch[field] = want;
+        }
+    }
+    return Object.keys(patch).length > 0 ? patch : undefined;
+}
+/** Recursive "declared keys differ" check; undefined when the declared subset matches. */
+function subsetDiff(want, have) {
+    for (const [k, v] of Object.entries(want)) {
+        if (v === undefined)
+            continue;
+        const h = have[k];
+        if (v && typeof v === "object" && !Array.isArray(v) && h && typeof h === "object" && !Array.isArray(h)) {
+            if (subsetDiff(v, h))
+                return true;
+        }
+        else if (!configEqual(v, h)) {
+            return true;
+        }
+    }
+    return undefined;
+}
+/** Live env-var list (`[{ envVar: {key, value}, cursor }]` or bare) → key/value map. Pure. */
+export function envVarsToMap(list) {
+    const out = {};
+    if (!Array.isArray(list))
+        return out;
+    for (const item of list) {
+        const ev = item && typeof item === "object" && "envVar" in item ? item.envVar : item;
+        if (ev && typeof ev === "object") {
+            const { key, value } = ev;
+            if (typeof key === "string")
+                out[key] = typeof value === "string" ? value : "";
+        }
+    }
+    return out;
+}
+/** Declared env-var list (`[{key, value} | {key, generateValue}]`) → key/value map (generated values as `undefined`). Pure. */
+export function declaredEnvVarsToMap(list) {
+    const out = {};
+    if (!Array.isArray(list))
+        return out;
+    for (const item of list) {
+        if (item && typeof item === "object") {
+            const { key, value } = item;
+            if (typeof key === "string")
+                out[key] = typeof value === "string" ? value : undefined;
+        }
+    }
+    return out;
+}
+/**
+ * True when a live env-var map carries chant's ownership marker. Reads the key
+ * convention the render lexicon declares (`RENDER_ENV_OWNERSHIP_KEYS`) through
+ * core's `hasOwnershipMarker`, so the prune filter and the serializer's stamp
+ * can never drift apart. Pure.
+ */
+export function isChantOwned(envVars) {
+    return hasOwnershipMarker(envVars ?? undefined, RENDER_ENV_OWNERSHIP_KEYS);
+}
+/** The stack/env identity a live env-var map carries, if marked. Pure. */
+export function ownershipOf(envVars) {
+    return readOwnership(envVars ?? undefined, RENDER_ENV_OWNERSHIP_KEYS);
+}
+/**
+ * Whether a declared env-var set and a live one differ. Generated values
+ * (`generateValue: true`) match any live value — Render made it up once and
+ * chant must not regenerate it every run. Pure.
+ */
+export function envVarsDiffer(declared, live) {
+    const want = declaredEnvVarsToMap(declared);
+    const wantKeys = Object.keys(want).sort();
+    const haveKeys = Object.keys(live).sort();
+    if (wantKeys.join("") !== haveKeys.join(""))
+        return true;
+    for (const k of wantKeys) {
+        if (want[k] !== undefined && want[k] !== live[k])
+            return true;
+    }
+    return false;
+}
+/** The plan's ownership marker (from the first marked body), for scoping prune. Pure. */
+export function planOwnership(plan) {
+    for (const req of Object.values(plan)) {
+        const entry = CATALOG[req.entityType];
+        if (!entry?.marked)
+            continue;
+        const map = declaredEnvVarsToMap(req.body.envVars);
+        const managed = map[RENDER_ENV_OWNERSHIP_KEYS.managedBy];
+        if (managed !== "chant")
+            continue;
+        return {
+            stack: map[RENDER_ENV_OWNERSHIP_KEYS.stack] ?? "",
+            env: map[RENDER_ENV_OWNERSHIP_KEYS.env],
+        };
+    }
+    return undefined;
+}
+/**
+ * Whether a live marked resource belongs to this plan's stack: same stack
+ * (and env, when the plan names one). A plan with no stack identity (bare
+ * `managed-by` only) owns every chant-marked resource in the workspace, which
+ * is the pre-#119 single-stack behaviour and is what an unconfigured project
+ * gets. Pure.
+ */
+export function inStack(live, plan) {
+    if (!live)
+        return false;
+    if (!plan || !plan.stack)
+        return true;
+    if (live.stack !== plan.stack)
+        return false;
+    if (plan.env && live.env !== plan.env)
+        return false;
+    return true;
+}
+/**
+ * Default `fetch`-based client. Sends `Authorization: Bearer <token>`; the
+ * token defaults to `RENDER_API_KEY` at call time. Retries 429 (Render rate
+ * limits at ~ 400 req/min) honouring `retry-after`, capped.
+ */
+export function defaultRenderHttp(token) {
+    return async (method, url, body, headers, signal) => {
+        const h = { accept: "application/json", ...headers };
+        if (body !== undefined)
+            h["content-type"] = "application/json";
+        const tok = token ?? process.env.RENDER_API_KEY;
+        if (tok)
+            h["authorization"] = `Bearer ${tok}`;
+        for (let attempt = 0;; attempt++) {
+            const res = await fetch(url, {
+                method,
+                headers: h,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal,
+            });
+            if (res.status === 429 && attempt < 5) {
+                const ra = Number(res.headers.get("retry-after"));
+                await sleep(Number.isFinite(ra) && ra > 0 ? ra * 1000 : 2000 * (attempt + 1), signal);
+                continue;
+            }
+            return { status: res.status, text: await res.text() };
+        }
+    };
+}
+function parseJson(text) {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function fail(what, status, text) {
+    throw new Error(`render: ${what} failed (HTTP ${status}): ${text.slice(0, 500)}`);
+}
+// ── Reads ─────────────────────────────────────────────────────────────────────
+/** Unwrap a list envelope element (`{ service: {...}, cursor }`) to the resource. */
+function unwrap(item, listKey) {
+    if (!item || typeof item !== "object")
+        return undefined;
+    if (listKey && listKey in item) {
+        const inner = item[listKey];
+        return inner && typeof inner === "object" ? inner : undefined;
+    }
+    return item;
+}
+/** GET every page of a list endpoint, following the cursor. */
+export async function listAll(ctx, path, query, listKey, http, signal) {
+    const out = [];
+    let cursor;
+    for (let page = 0; page < 50; page++) {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(query))
+            if (v !== undefined && v !== "")
+                params.set(k, v);
+        params.set("limit", String(PAGE_LIMIT));
+        if (cursor)
+            params.set("cursor", cursor);
+        const res = await http("GET", `${ctx.base}${path}?${params.toString()}`, undefined, undefined, signal);
+        if (res.status === 404 && page === 0)
+            return out;
+        if (res.status < 200 || res.status >= 300)
+            fail(`GET ${path}`, res.status, res.text);
+        const items = parseJson(res.text);
+        if (!Array.isArray(items) || items.length === 0)
+            break;
+        for (const item of items) {
+            const r = unwrap(item, listKey);
+            if (r)
+                out.push(r);
+        }
+        const last = items[items.length - 1];
+        cursor = typeof last?.cursor === "string" ? last.cursor : undefined;
+        if (items.length < PAGE_LIMIT || !cursor)
+            break;
+    }
+    return out;
+}
+/** GET one resource by id. */
+export async function getOne(ctx, path, http, signal) {
+    const res = await http("GET", `${ctx.base}${path}`, undefined, undefined, signal);
+    if (res.status === 404)
+        return undefined;
+    if (res.status < 200 || res.status >= 300)
+        fail(`GET ${path}`, res.status, res.text);
+    const v = parseJson(res.text);
+    return v && typeof v === "object" ? v : undefined;
+}
+/**
+ * Resolve the workspace id: an explicit arg, then `RENDER_OWNER_ID`, then the
+ * sole owner the token can see. Throws when the token sees several — picking
+ * one silently would deploy into the wrong team.
+ */
+export async function resolveOwner(ctx, args, http, signal, env = process.env) {
+    if (ctx.ownerId)
+        return ctx.ownerId;
+    const explicit = args.ownerId || env.RENDER_OWNER_ID;
+    if (explicit) {
+        ctx.ownerId = explicit;
+        return explicit;
+    }
+    const owners = await listAll(ctx, "/owners", {}, "owner", http, signal);
+    const ids = owners.map((o) => o.id).filter((id) => typeof id === "string");
+    if (ids.length === 1) {
+        ctx.ownerId = ids[0];
+        return ids[0];
+    }
+    if (ids.length === 0)
+        throw new Error("render: the API key sees no workspaces — set RENDER_OWNER_ID");
+    throw new Error(`render: the API key sees ${ids.length} workspaces (${ids.join(", ")}) — set RENDER_OWNER_ID or pass ownerId to choose one`);
+}
+/**
+ * Find the live resource a request declares, by name within its scope.
+ * Services also match on `type`; environments on `projectId`; disks on
+ * `serviceId`; custom domains list under their service.
+ */
+export async function findExisting(ctx, req, entry, endpoint, http, signal) {
+    const query = {};
+    if (entry.filters.name)
+        query.name = req.name;
+    if (entry.filters.ownerId)
+        query.ownerId = typeof req.body.ownerId === "string" ? req.body.ownerId : ctx.ownerId;
+    if (req.entityType === ENTITY_TYPES.environment && typeof req.body.projectId === "string") {
+        query.projectId = req.body.projectId;
+    }
+    if (req.entityType === ENTITY_TYPES.disk && typeof req.body.serviceId === "string") {
+        query.serviceId = req.body.serviceId;
+    }
+    const listPath = req.entityType === ENTITY_TYPES.customDomain ? endpoint : entry.collection;
+    const candidates = await listAll(ctx, listPath, query, entry.listKey, http, signal);
+    return candidates.find((c) => {
+        if (c.name !== req.name)
+            return false;
+        if (isServiceEntityType(req.entityType) && c.type !== req.body.type)
+            return false;
+        if (req.entityType === ENTITY_TYPES.environment && typeof req.body.projectId === "string" && c.projectId !== req.body.projectId)
+            return false;
+        if (req.entityType === ENTITY_TYPES.disk && typeof req.body.serviceId === "string" && c.serviceId !== req.body.serviceId)
+            return false;
+        return true;
+    });
+}
+/** Datastore attributes served by the `/connection-info` side endpoint. */
+const CONNECTION_INFO_ATTRS = new Set([
+    "internalConnectionString",
+    "externalConnectionString",
+    "psqlCommand",
+    "cliCommand",
+    "internalConnectionPoolString",
+    "externalConnectionPoolString",
+    "password",
+]);
+/**
+ * Resolve an attribute of a live entity: `id`, any field of the live resource,
+ * or a datastore connection-info field (fetched once per entity).
+ */
+export async function resolveAttribute(ctx, live, attribute, http, cache, signal) {
+    if (attribute === "id")
+        return live.id;
+    if (attribute in live.resource)
+        return live.resource[attribute];
+    if (CONNECTION_INFO_ATTRS.has(attribute)) {
+        const entry = catalogEntry(live.entityType);
+        const key = `${entry.collection}/${live.id}`;
+        let info = cache.get(key);
+        if (!info) {
+            info = (await getOne(ctx, `${entry.collection}/${live.id}/connection-info`, http, signal)) ?? {};
+            cache.set(key, info);
+        }
+        if (attribute in info)
+            return info[attribute];
+    }
+    throw new Error(`render: attribute "${attribute}" is not available on live ${live.entityType} ${live.id}`);
+}
+/** Replace every marker in a value with its live resolution. */
+export async function resolveMarkers(ctx, value, lives, http, cache, ownerId, signal) {
+    if (isOwnerMarker(value))
+        return ownerId();
+    if (isRefMarker(value)) {
+        const live = lives.get(value.$ref);
+        if (!live)
+            throw new Error(`render: reference to "${value.$ref}" cannot be resolved — it has not been applied`);
+        return live.id;
+    }
+    if (isAttrMarker(value)) {
+        const live = lives.get(value.$attr.entity);
+        if (!live)
+            throw new Error(`render: attribute read on "${value.$attr.entity}" cannot be resolved — it has not been applied`);
+        return resolveAttribute(ctx, live, value.$attr.attribute, http, cache, signal);
+    }
+    if (Array.isArray(value)) {
+        const out = [];
+        for (const v of value)
+            out.push(await resolveMarkers(ctx, v, lives, http, cache, ownerId, signal));
+        return out;
+    }
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = await resolveMarkers(ctx, v, lives, http, cache, ownerId, signal);
+        }
+        return out;
+    }
+    return value;
+}
+// ── Mutations ─────────────────────────────────────────────────────────────────
+/** POST a create body; returns the created resource (services: unwrapped from `{ service, deployId }`). */
+export async function create(ctx, endpoint, body, http, signal) {
+    const res = await http("POST", `${ctx.base}${endpoint}`, body, undefined, signal);
+    if (res.status < 200 || res.status >= 300)
+        fail(`POST ${endpoint}`, res.status, res.text);
+    const parsed = parseJson(res.text);
+    // Custom domains answer with an array of the domains created.
+    const first = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (!first || typeof first !== "object")
+        return { resource: {} };
+    const rec = first;
+    if (rec.service && typeof rec.service === "object") {
+        return { resource: rec.service, deployId: typeof rec.deployId === "string" ? rec.deployId : undefined };
+    }
+    return { resource: rec };
+}
+/** PATCH a live resource; returns the updated resource. */
+export async function patch(ctx, path, body, http, signal) {
+    const res = await http("PATCH", `${ctx.base}${path}`, body, undefined, signal);
+    if (res.status < 200 || res.status >= 300)
+        fail(`PATCH ${path}`, res.status, res.text);
+    const v = parseJson(res.text);
+    return v && typeof v === "object" ? v : {};
+}
+/** DELETE a live resource; false when it was already gone. */
+export async function remove(ctx, path, http, signal) {
+    const res = await http("DELETE", `${ctx.base}${path}`, undefined, undefined, signal);
+    if (res.status === 404)
+        return false;
+    if (res.status < 200 || res.status >= 300)
+        fail(`DELETE ${path}`, res.status, res.text);
+    return true;
+}
+/** Live env vars of a service (`GET /services/{id}/env-vars`), as a map. */
+export async function readServiceEnvVars(ctx, serviceId, http, signal) {
+    const items = await listAll(ctx, `/services/${serviceId}/env-vars`, {}, "envVar", http, signal);
+    return envVarsToMap(items);
+}
+/** Replace a service's env vars wholesale (`PUT /services/{id}/env-vars`). */
+export async function putServiceEnvVars(ctx, serviceId, envVars, http, signal) {
+    const res = await http("PUT", `${ctx.base}/services/${serviceId}/env-vars`, envVars, undefined, signal);
+    if (res.status < 200 || res.status >= 300)
+        fail(`PUT /services/${serviceId}/env-vars`, res.status, res.text);
+}
+/**
+ * Reconcile an env group's env vars: Render's group PATCH takes only `name`,
+ * so each var is PUT by key and removed keys are DELETEd. Returns whether
+ * anything changed.
+ */
+export async function reconcileEnvGroupVars(ctx, groupId, declared, live, http, signal) {
+    const want = declaredEnvVarsToMap(declared);
+    let changed = false;
+    for (const [key, value] of Object.entries(want)) {
+        if (value === undefined) {
+            if (key in live)
+                continue; // generated once; keep
+            const res = await http("PUT", `${ctx.base}/env-groups/${groupId}/env-vars/${encodeURIComponent(key)}`, { generateValue: true }, undefined, signal);
+            if (res.status < 200 || res.status >= 300)
+                fail(`PUT env-group var ${key}`, res.status, res.text);
+            changed = true;
+            continue;
+        }
+        if (live[key] === value)
+            continue;
+        const res = await http("PUT", `${ctx.base}/env-groups/${groupId}/env-vars/${encodeURIComponent(key)}`, { value }, undefined, signal);
+        if (res.status < 200 || res.status >= 300)
+            fail(`PUT env-group var ${key}`, res.status, res.text);
+        changed = true;
+    }
+    for (const key of Object.keys(live)) {
+        if (key in want)
+            continue;
+        const res = await http("DELETE", `${ctx.base}/env-groups/${groupId}/env-vars/${encodeURIComponent(key)}`, undefined, undefined, signal);
+        if (res.status !== 404 && (res.status < 200 || res.status >= 300))
+            fail(`DELETE env-group var ${key}`, res.status, res.text);
+        changed = true;
+    }
+    return changed;
+}
+/** Link the declared services to an env group (`POST /env-groups/{id}/services/{serviceId}`). */
+export async function linkEnvGroupServices(ctx, groupId, serviceIds, live, http, signal) {
+    const linked = new Set();
+    const links = live.serviceLinks;
+    if (Array.isArray(links)) {
+        for (const l of links) {
+            const id = l?.id;
+            if (typeof id === "string")
+                linked.add(id);
+        }
+    }
+    let changed = false;
+    for (const sid of serviceIds) {
+        if (linked.has(sid))
+            continue;
+        const res = await http("POST", `${ctx.base}/env-groups/${groupId}/services/${sid}`, undefined, undefined, signal);
+        if (res.status < 200 || res.status >= 300)
+            fail(`POST env-group link ${sid}`, res.status, res.text);
+        changed = true;
+    }
+    return changed;
+}
+/** The latest deploy of a service, if any. */
+export async function latestDeploy(ctx, serviceId, http, signal) {
+    const res = await http("GET", `${ctx.base}/services/${serviceId}/deploys?limit=1`, undefined, undefined, signal);
+    if (res.status < 200 || res.status >= 300)
+        fail(`GET deploys ${serviceId}`, res.status, res.text);
+    const items = parseJson(res.text);
+    if (!Array.isArray(items) || items.length === 0)
+        return undefined;
+    const d = unwrap(items[0], "deploy");
+    if (!d || typeof d.id !== "string")
+        return undefined;
+    return { id: d.id, status: typeof d.status === "string" ? d.status : "" };
+}
+/**
+ * Poll a service's deploy until it is `live`. Throws on a failed/canceled
+ * deploy or when the deadline passes. When `deployId` is unknown, the latest
+ * deploy is watched.
+ */
+export async function waitForDeploy(ctx, serviceId, deployId, opts, http, signal, now = Date.now) {
+    const interval = opts.intervalMs ?? 5000;
+    const deadline = now() + (opts.deadlineMs ?? 15 * 60 * 1000);
+    for (;;) {
+        let status;
+        let id = deployId;
+        if (id) {
+            const d = await getOne(ctx, `/services/${serviceId}/deploys/${id}`, http, signal);
+            status = typeof d?.status === "string" ? d.status : "";
+        }
+        else {
+            const d = await latestDeploy(ctx, serviceId, http, signal);
+            if (!d)
+                return "no-deploy";
+            id = d.id;
+            status = d.status;
+        }
+        if (DEPLOY_LIVE.has(status))
+            return status;
+        if (DEPLOY_FAILED.has(status)) {
+            throw new Error(`render: deploy ${id} of service ${serviceId} ended ${status}`);
+        }
+        if (now() >= deadline) {
+            throw new Error(`render: deploy ${id} of service ${serviceId} still ${status || "pending"} after deadline`);
+        }
+        await sleep(interval, signal);
+    }
+}
+/** Map an outcome onto core's versioned apply envelope. Pure. */
+export function toApplyResult(outcome) {
+    const applied = outcome.applied.map((a) => ({
+        kind: a.kind,
+        name: a.name,
+        action: a.action,
+        ...(a.id ? { physicalId: a.id } : {}),
+    }));
+    const pruned = outcome.pruned.map((p) => ({ kind: p.kind, name: p.name, deleted: p.deleted }));
+    return applyResult(applied, pruned, outcome.notAttempted);
+}
+/**
+ * Apply a serialized Render plan: create or update every declared resource in
+ * dependency order, resolving `$ref`/`$attr`/`$owner` markers as their targets
+ * go live; wait each created service's deploy to `live`; prune owned orphans
+ * when asked. Returns the versioned {@link ApplyResult}.
+ */
+export async function renderApply(args, signal, http = defaultRenderHttp(args.token)) {
+    const outcome = await renderApplyDetailed(args, signal, http);
+    return toApplyResult(outcome);
+}
+export async function renderApplyDetailed(args, signal, http = defaultRenderHttp(args.token)) {
+    const plan = parsePlan(readFileSync(args.planPath, "utf8"));
+    const ctx = { base: resolveEndpoint(args) };
+    const wait = args.wait ?? {};
+    const ordered = orderPlan(plan);
+    const lives = new Map();
+    const infoCache = new Map();
+    const owner = () => resolveOwner(ctx, args, http, signal);
+    const outcome = { applied: [], pruned: [], notAttempted: [] };
+    for (const [entityName, req] of ordered) {
+        const entry = catalogEntry(req.entityType);
+        // Resolve markers now that every dependency is live.
+        const body = (await resolveMarkers(ctx, req.body, lives, http, infoCache, owner, signal));
+        const pathParams = (await resolveMarkers(ctx, req.pathParams ?? {}, lives, http, infoCache, owner, signal));
+        let endpoint = req.endpoint;
+        for (const [k, v] of Object.entries(pathParams)) {
+            if (typeof v === "string")
+                endpoint = endpoint.replace(`{${k}}`, encodeURIComponent(v));
+        }
+        if (entry.filters.ownerId && typeof body.ownerId !== "string") {
+            // A list filter needs the owner even when the body does not carry it.
+            ctx.ownerId = ctx.ownerId ?? (await owner());
+        }
+        const existing = await findExisting(ctx, req, entry, endpoint, http, signal);
+        if (!existing) {
+            const { resource, deployId } = await create(ctx, endpoint, body, http, signal);
+            const id = typeof resource.id === "string" ? resource.id : "";
+            lives.set(entityName, { id, entityType: req.entityType, resource });
+            console.log(`created: ${entry.kind}/${req.name}${id ? ` (${id})` : ""}`);
+            // Env-group service links are not part of the create body.
+            if (req.entityType === ENTITY_TYPES.envGroup && Array.isArray(body.serviceIds) && id) {
+                await linkEnvGroupServices(ctx, id, body.serviceIds.filter((s) => typeof s === "string"), resource, http, signal);
+            }
+            if (isServiceEntityType(req.entityType) && id && wait.deploys !== false) {
+                await waitForDeploy(ctx, id, deployId, wait, http, signal);
+            }
+            outcome.applied.push({ kind: entry.kind, name: req.name, action: "created", id, entity: entityName });
+            continue;
+        }
+        const id = typeof existing.id === "string" ? existing.id : "";
+        lives.set(entityName, { id, entityType: req.entityType, resource: existing });
+        let changed = false;
+        // Body PATCH — the catalog's patchable fields that differ.
+        const diff = entry.patchable ? diffForPatch(entry, body, existing) : undefined;
+        if (diff && id) {
+            const updated = await patch(ctx, `${entry.collection}/${id}`, diff, http, signal);
+            lives.set(entityName, { id, entityType: req.entityType, resource: { ...existing, ...updated } });
+            changed = true;
+        }
+        // Env vars: services replace wholesale via PUT; env groups per key.
+        if (entry.marked && id) {
+            if (isServiceEntityType(req.entityType)) {
+                const live = await readServiceEnvVars(ctx, id, http, signal);
+                if (envVarsDiffer(body.envVars, live)) {
+                    // Keep live values for generated keys so Render's random values survive.
+                    const desired = (Array.isArray(body.envVars) ? body.envVars : []).map((e) => {
+                        const item = e;
+                        if (item.generateValue && item.key in live)
+                            return { key: item.key, value: live[item.key] };
+                        return item;
+                    });
+                    await putServiceEnvVars(ctx, id, desired, http, signal);
+                    changed = true;
+                }
+            }
+            else if (req.entityType === ENTITY_TYPES.envGroup) {
+                const live = envVarsToMap(existing.envVars);
+                if (await reconcileEnvGroupVars(ctx, id, body.envVars, live, http, signal))
+                    changed = true;
+                if (Array.isArray(body.serviceIds)) {
+                    const linked = await linkEnvGroupServices(ctx, id, body.serviceIds.filter((s) => typeof s === "string"), existing, http, signal);
+                    if (linked)
+                        changed = true;
+                }
+            }
+        }
+        console.log(`${changed ? "updated" : "unchanged"}: ${entry.kind}/${req.name} (${id})`);
+        outcome.applied.push({ kind: entry.kind, name: req.name, action: changed ? "updated" : "unchanged", id, entity: entityName });
+    }
+    // Prune: owned services and env groups (marked, this stack) not in the plan,
+    // and — at the service boundary — the disks and custom domains under an
+    // owned service that the plan does not declare.
+    if (args.prune) {
+        const ownerId = await owner();
+        const marker = planOwnership(plan);
+        const declaredServices = new Set(ordered.filter(([, r]) => isServiceEntityType(r.entityType)).map(([, r]) => `${r.body.type}:${r.name}`));
+        const declaredGroups = new Set(ordered.filter(([, r]) => r.entityType === ENTITY_TYPES.envGroup).map(([, r]) => r.name));
+        // Declared children by `${serviceId}:${name}`, with the parent's live id.
+        const declaredChildren = new Set();
+        for (const [, r] of ordered) {
+            const entry = catalogEntry(r.entityType);
+            if (entry.boundary !== "service")
+                continue;
+            const raw = r.entityType === ENTITY_TYPES.customDomain ? r.pathParams?.serviceId : r.body.serviceId;
+            const parentId = isRefMarker(raw) ? lives.get(raw.$ref)?.id : typeof raw === "string" ? raw : undefined;
+            if (parentId)
+                declaredChildren.add(`${parentId}:${r.name}`);
+        }
+        // Owned services first (declared or not): their undeclared children go,
+        // then the undeclared services themselves.
+        const staleServices = [];
+        for (const svc of await listAll(ctx, "/services", { ownerId }, "service", http, signal)) {
+            const id = typeof svc.id === "string" ? svc.id : undefined;
+            const name = typeof svc.name === "string" ? svc.name : "";
+            const type = typeof svc.type === "string" ? svc.type : "";
+            if (!id)
+                continue;
+            const env = await readServiceEnvVars(ctx, id, http, signal);
+            if (!isChantOwned(env) || !inStack(ownershipOf(env), marker))
+                continue;
+            const declared = declaredServices.has(`${type}:${name}`);
+            if (!declared)
+                staleServices.push({ id, name, type });
+            // Service boundary: disks and custom domains under this owned service.
+            // A stale service takes its children with it, so only a declared parent
+            // needs its children reconciled one by one.
+            if (!declared)
+                continue;
+            for (const disk of await listAll(ctx, "/disks", { serviceId: id, ownerId }, "disk", http, signal)) {
+                const diskId = typeof disk.id === "string" ? disk.id : undefined;
+                const diskName = typeof disk.name === "string" ? disk.name : "";
+                if (!diskId || disk.serviceId !== id || declaredChildren.has(`${id}:${diskName}`))
+                    continue;
+                const deleted = await remove(ctx, `/disks/${diskId}`, http, signal);
+                console.log(`pruned: Disk/${diskName} (${diskId}) under ${type}/${name}`);
+                outcome.pruned.push({ kind: "Disk", name: diskName, id: diskId, deleted });
+            }
+            for (const domain of await listAll(ctx, `/services/${id}/custom-domains`, {}, "customDomain", http, signal)) {
+                const domainId = typeof domain.id === "string" ? domain.id : undefined;
+                const domainName = typeof domain.name === "string" ? domain.name : "";
+                if (!domainId || declaredChildren.has(`${id}:${domainName}`))
+                    continue;
+                const deleted = await remove(ctx, `/services/${id}/custom-domains/${encodeURIComponent(domainId)}`, http, signal);
+                console.log(`pruned: CustomDomain/${domainName} (${domainId}) under ${type}/${name}`);
+                outcome.pruned.push({ kind: "CustomDomain", name: domainName, id: domainId, deleted });
+            }
+        }
+        for (const { id, name, type } of staleServices) {
+            const kind = catalogEntry(ENTITY_TYPE_OF_SERVICE[type] ?? ENTITY_TYPES.webService).kind;
+            const deleted = await remove(ctx, `/services/${id}`, http, signal);
+            console.log(`pruned: ${kind}/${name} (${id})`);
+            outcome.pruned.push({ kind, name, id, deleted });
+        }
+        for (const grp of await listAll(ctx, "/env-groups", { ownerId }, "envGroup", http, signal)) {
+            const id = typeof grp.id === "string" ? grp.id : undefined;
+            const name = typeof grp.name === "string" ? grp.name : "";
+            if (!id || declaredGroups.has(name))
+                continue;
+            const full = (await getOne(ctx, `/env-groups/${id}`, http, signal)) ?? grp;
+            const env = envVarsToMap(full.envVars);
+            if (!isChantOwned(env) || !inStack(ownershipOf(env), marker))
+                continue;
+            const deleted = await remove(ctx, `/env-groups/${id}`, http, signal);
+            console.log(`pruned: EnvGroup/${name} (${id})`);
+            outcome.pruned.push({ kind: "EnvGroup", name, id, deleted });
+        }
+    }
+    return outcome;
+}
+/**
+ * Delete every resource a plan declares, in reverse apply order — the
+ * teardown twin of {@link renderApply}. Looks each up by name; a resource that
+ * is already gone is reported `deleted: false`. Only what the plan names is
+ * touched.
+ */
+export async function renderDelete(args, signal, http = defaultRenderHttp(args.token)) {
+    const plan = parsePlan(readFileSync(args.planPath, "utf8"));
+    const ctx = { base: resolveEndpoint(args) };
+    const ordered = orderPlan(plan).reverse();
+    const owner = () => resolveOwner(ctx, args, http, signal);
+    const pruned = [];
+    const notAttempted = [];
+    // Ids of entities we find, so a child endpoint's `{serviceId}` can resolve
+    // even though we walk in reverse: resolve parents lazily by name.
+    const idByEntity = new Map();
+    const findId = async (entityName) => {
+        if (idByEntity.has(entityName))
+            return idByEntity.get(entityName);
+        const req = plan[entityName];
+        if (!req)
+            return undefined;
+        const entry = catalogEntry(req.entityType);
+        if (entry.filters.ownerId)
+            ctx.ownerId = ctx.ownerId ?? (await owner());
+        const endpoint = await resolveEndpointFor(req);
+        if (!endpoint)
+            return undefined;
+        const body = { ...req.body };
+        if (isOwnerMarker(body.ownerId))
+            body.ownerId = await owner();
+        const found = await findExisting(ctx, { ...req, body }, entry, endpoint, http, signal);
+        const id = typeof found?.id === "string" ? found.id : undefined;
+        if (id)
+            idByEntity.set(entityName, id);
+        return id;
+    };
+    const resolveEndpointFor = async (req) => {
+        let endpoint = req.endpoint;
+        for (const [k, v] of Object.entries(req.pathParams ?? {})) {
+            const id = isRefMarker(v) ? await findId(v.$ref) : typeof v === "string" ? v : undefined;
+            if (!id)
+                return undefined;
+            endpoint = endpoint.replace(`{${k}}`, encodeURIComponent(id));
+        }
+        return endpoint;
+    };
+    for (const [entityName, req] of ordered) {
+        const entry = catalogEntry(req.entityType);
+        const endpoint = await resolveEndpointFor(req);
+        const id = endpoint ? await findId(entityName) : undefined;
+        if (!id) {
+            pruned.push({ kind: entry.kind, name: req.name, deleted: false });
+            continue;
+        }
+        // Custom domains delete under their service; everything else at its collection.
+        const path = req.entityType === ENTITY_TYPES.customDomain ? `${endpoint}/${encodeURIComponent(id)}` : `${entry.collection}/${id}`;
+        const deleted = await remove(ctx, path, http, signal);
+        console.log(`${deleted ? "deleted" : "already gone"}: ${entry.kind}/${req.name} (${id})`);
+        pruned.push({ kind: entry.kind, name: req.name, deleted });
+    }
+    return applyResult([], pruned, notAttempted);
+}