@intentius/chant-lexicon-render 0.53.0

package/src/serializer.ts

@@ -0,0 +1,286 @@
+/**
+ * Render serializer.
+ *
+ * Turns declared `WebService`, `Postgres`, `EnvGroup`, `Project`, ... resources
+ * into the JSON create bodies the Render Public API accepts, so the applier can
+ * POST them straight through.
+ *
+ * Output shape — a JSON object keyed by entity name. Each value is a single
+ * Render request plus the identity the applier reconciles by:
+ *
+ *   {
+ *     "<entityName>": {
+ *       "kind": "WebService",                       // generated class name
+ *       "entityType": "Render::Services::WebService",
+ *       "endpoint": "/services",                    // create collection
+ *       "method": "POST",
+ *       "name": "my-web",                           // reconcile key (Render has no client-chosen ids)
+ *       "body": { ... },                            // the create body
+ *       "pathParams": { "serviceId": { "$ref": "web" } }   // for child collections
+ *     }
+ *   }
+ *
+ * Cross-resource references. Render identifies resources by server-assigned
+ * ids, so a Disk's `serviceId` or an Environment's `projectId` cannot be known
+ * at build time. A declared resource passed where an id is expected serializes
+ * to `{ "$ref": "<entityName>" }`; an attribute read (`db.internalConnectionString`)
+ * to `{ "$attr": { "entity": "<entityName>", "attribute": "..." } }`. The applier
+ * resolves both once the target exists.
+ *
+ * Ownership. Every serialized service and env group carries the
+ * `CHANT_MANAGED_BY=chant` marker (plus the stack/env identity from
+ * `context.ownership`) merged into `envVars`, even when the author supplied
+ * none. See ./ownership.ts for why env vars.
+ *
+ * `ownerId`. Every owner-scoped body gets `ownerId` filled from `Render.OwnerId`
+ * (`RENDER_OWNER_ID`) when the author omitted it. When that is unset too, an
+ * `{ "$owner": true }` marker is left for the applier, which resolves it from
+ * `GET /owners` when the token sees exactly one workspace.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { isPropertyDeclarable, isResourceDeclarable } from "@intentius/chant/declarable";
+import type { Serializer, SerializeContext } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { ownershipEntries, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+import { RENDER_ENV_OWNERSHIP_KEYS } from "./ownership";
+import { CATALOG, SERVICE_TYPE_OF, catalogEntry, isServiceEntityType } from "./catalog";
+
+/** A cross-resource id reference the applier resolves after the target exists. */
+export interface RefMarker {
+  $ref: string;
+}
+
+/** An attribute read the applier resolves from the live target. */
+export interface AttrMarker {
+  $attr: { entity: string; attribute: string };
+}
+
+/** The workspace placeholder left when neither the author nor `RENDER_OWNER_ID` named one. */
+export interface OwnerMarker {
+  $owner: true;
+}
+
+export function isRefMarker(v: unknown): v is RefMarker {
+  return !!v && typeof v === "object" && typeof (v as RefMarker).$ref === "string";
+}
+
+export function isAttrMarker(v: unknown): v is AttrMarker {
+  const a = v as AttrMarker;
+  return !!a && typeof a === "object" && !!a.$attr && typeof a.$attr.entity === "string";
+}
+
+export function isOwnerMarker(v: unknown): v is OwnerMarker {
+  return !!v && typeof v === "object" && (v as OwnerMarker).$owner === true;
+}
+
+/** A single Render REST call the applier can issue, plus its reconcile identity. */
+export interface RenderRequest {
+  kind: string;
+  entityType: string;
+  endpoint: string;
+  method: "POST";
+  /** The human name Render will show and chant reconciles by. */
+  name: string;
+  body: Record<string, unknown>;
+  /** Path placeholders in `endpoint` (child collections). */
+  pathParams?: Record<string, unknown>;
+}
+
+/** The serializer's whole output: entity name → request. */
+export type RenderPlan = Record<string, RenderRequest>;
+
+/**
+ * Visitor for the generic serializer walker. Property declarables
+ * (WebServiceDetails, Image, ServiceDisk, ...) are unwrapped to plain objects;
+ * resource references and attribute reads become the applier's markers.
+ */
+function renderVisitor(): SerializerVisitor {
+  return {
+    attrRef: (entity, attribute) => ({ $attr: { entity, attribute } }),
+    resourceRef: (name) => ({ $ref: name }),
+    propertyDeclarable: (entity, walk) => {
+      const props = isResourceDeclarable(entity) ? entity.props : undefined;
+      if (!props || typeof props !== "object") return undefined;
+      const result: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(props)) {
+        if (value !== undefined) result[key] = walk(value);
+      }
+      return result;
+    },
+  };
+}
+
+function readProps(entity: Declarable): Record<string, unknown> {
+  const props = isResourceDeclarable(entity) ? entity.props : undefined;
+  return props && typeof props === "object" ? (props as Record<string, unknown>) : {};
+}
+
+/**
+ * Pseudo-parameter → environment variable mapping. Render bodies are plain
+ * JSON, so `Render.OwnerId` / `Render.Region` (which the walker lowers to a
+ * `{ Ref: "Render::..." }` marker) are resolved from the environment at build
+ * time. Region has a fallback (Render's own default); the owner does not — an
+ * unset owner becomes the `$owner` marker for the applier.
+ */
+const PSEUDO_ENV_MAP: Record<string, { envVars: string[]; fallback?: unknown }> = {
+  "Render::OwnerId": { envVars: ["RENDER_OWNER_ID"], fallback: { $owner: true } },
+  "Render::Region": { envVars: ["RENDER_REGION"], fallback: "oregon" },
+};
+
+function resolvePseudoRef(ref: string): unknown {
+  const mapping = PSEUDO_ENV_MAP[ref];
+  if (!mapping) return undefined;
+  for (const envVar of mapping.envVars) {
+    const value = process.env[envVar];
+    if (value) return value;
+  }
+  return mapping.fallback;
+}
+
+/**
+ * Recursively replace pseudo-parameters with their resolved environment value.
+ * Handles both a raw `PseudoParameter` instance and the already-walked
+ * `{ Ref: "Render::X" }` shape. Everything else passes through untouched.
+ */
+export function resolvePseudoParameters(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(resolvePseudoParameters);
+  }
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+
+    if (INTRINSIC_MARKER in record && typeof record.toJSON === "function") {
+      return resolvePseudoParameters(record.toJSON());
+    }
+
+    const keys = Object.keys(record);
+    if (keys.length === 1 && keys[0] === "Ref" && typeof record.Ref === "string") {
+      const resolved = resolvePseudoRef(record.Ref);
+      if (resolved !== undefined) return resolved;
+    }
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(record)) {
+      result[key] = resolvePseudoParameters(val);
+    }
+    return result;
+  }
+  return value;
+}
+
+/** The Render name a resource gets: an explicit `name` prop, else the entity name. */
+function resourceName(props: Record<string, unknown>, entityName: string): string {
+  return typeof props.name === "string" && props.name ? props.name : entityName;
+}
+
+/**
+ * Merge chant's ownership marker into an `envVars` list. The marker wins over
+ * any colliding user key so ownership can never be silently unset; the user's
+ * ordering is otherwise preserved.
+ */
+export function stampOwnership(envVars: unknown, marker: Record<string, string>): unknown[] {
+  const list = Array.isArray(envVars) ? [...envVars] : [];
+  const out = list.filter((e) => !(e && typeof e === "object" && (e as { key?: unknown }).key !== undefined && (e as { key: string }).key in marker));
+  for (const [key, value] of Object.entries(marker)) out.push({ key, value });
+  return out;
+}
+
+/**
+ * Serialize a render partition into the plan document `renderApply` consumes.
+ *
+ * Split out of the `Serializer` object so callers that need the concrete
+ * document — the applier, its tests, the `describeResources` fixtures — get
+ * `string` rather than the interface's `string | SerializerResult` union.
+ */
+export function serializeRender(
+  entities: Map<string, Declarable>,
+  _outputs?: LexiconOutput[],
+  context?: SerializeContext,
+): string {
+  const entityNames = new Map<Declarable, string>();
+  for (const [name, entity] of entities) entityNames.set(entity, name);
+  const visitor = renderVisitor();
+
+  // Ownership marker. `CHANT_MANAGED_BY=chant` is always stamped; stack/env
+  // are added when the build threads an ownership marker through the context.
+  const ownershipEnv: Record<string, string> = context?.ownership
+    ? ownershipEntries(RENDER_ENV_OWNERSHIP_KEYS, context.ownership)
+    : { [RENDER_ENV_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE };
+
+  const requests: RenderPlan = {};
+
+  for (const [entityName, entity] of entities) {
+    if (isPropertyDeclarable(entity)) continue;
+    const entityType = (entity as unknown as { entityType?: string }).entityType;
+    if (!entityType || !(entityType in CATALOG)) continue;
+    const entry = catalogEntry(entityType);
+    const props = readProps(entity);
+
+    // Body: every prop except association hints, walked so nested property
+    // declarables flatten and references become markers.
+    const body: Record<string, unknown> = {};
+    const pathParams: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(props)) {
+      if (value === undefined) continue;
+      const walked = walkValue(value, entityNames, visitor);
+      if (entry.nonBodyProps.includes(key)) {
+        pathParams[key] = walked;
+      } else {
+        body[key] = walked;
+      }
+    }
+
+    // Services: re-inject the fixed `type` discriminator the authoring
+    // surface hides, and stamp the marker.
+    if (isServiceEntityType(entityType)) {
+      body.type = SERVICE_TYPE_OF[entityType];
+    }
+    if (entry.marked) {
+      body.envVars = stampOwnership(body.envVars, ownershipEnv);
+    }
+
+    // Owner: fill from the pseudo-parameter when omitted; the walked value
+    // of `Render.OwnerId` is a `{ Ref }` resolved below with the rest.
+    if (entry.ownerScoped && body.ownerId === undefined) {
+      body.ownerId = { Ref: "Render::OwnerId" };
+    }
+    // `image.ownerId` must match the service's; default it the same way.
+    if (isServiceEntityType(entityType) && body.image && typeof body.image === "object") {
+      const image = body.image as Record<string, unknown>;
+      if (image.ownerId === undefined) image.ownerId = body.ownerId;
+    }
+
+    // Child collections: fill the endpoint placeholder from pathParams when
+    // the value is a literal id; a `{ $ref }` stays for the applier.
+    let endpoint = entry.collection;
+    for (const [key, value] of Object.entries(pathParams)) {
+      if (typeof value === "string") endpoint = endpoint.replace(`{${key}}`, encodeURIComponent(value));
+    }
+
+    const request: RenderRequest = {
+      kind: entry.kind,
+      entityType,
+      endpoint,
+      method: "POST",
+      name: resourceName(props, entityName),
+      body,
+    };
+    if (Object.keys(pathParams).length > 0) request.pathParams = pathParams;
+    requests[entityName] = request;
+  }
+
+  // Resolve pseudo-parameter markers (Render.OwnerId, Render.Region) to their
+  // environment value so bodies carry plain strings, not `{ Ref }`.
+  return JSON.stringify(resolvePseudoParameters(requests), null, 2);
+}
+
+/**
+ * Render serializer.
+ */
+export const renderSerializer: Serializer = {
+  name: "render",
+  rulePrefix: "REN",
+  serialize: serializeRender,
+};

package/src/skills/chant-render-patterns.md

@@ -0,0 +1,126 @@
+---
+skill: chant-render-patterns
+description: Render patterns in chant — env groups, projects and environments, disks, custom domains, image-backed and cron services, and the ownership model
+user-invocable: true
+---
+
+# Render Patterns
+
+Companion to `chant-render`. Each pattern is a fragment you can drop into `src/`.
+
+## Env groups shared across services
+
+An `EnvGroup` holds env vars (and secret files) many services share. Link services with `serviceIds`, passing the declared resources:
+
+```ts
+import { EnvGroup, EnvVar, GeneratedEnvVar, WebService, BackgroundWorker, WebServiceDetails, BackgroundWorkerDetails } from "@intentius/chant-lexicon-render";
+
+export const web = new WebService({ name: "web", repo: REPO, serviceDetails: new WebServiceDetails({ runtime: "docker" }) });
+export const worker = new BackgroundWorker({ name: "worker", repo: REPO, serviceDetails: new BackgroundWorkerDetails({ runtime: "docker" }) });
+
+export const shared = new EnvGroup({
+  name: "shared",
+  envVars: [
+    new EnvVar({ key: "LOG_LEVEL", value: "info" }),
+    new GeneratedEnvVar({ key: "SIGNING_KEY", generateValue: true }),
+  ],
+  serviceIds: [web, worker],
+});
+```
+
+The applier links each service after both exist (`POST /env-groups/{id}/services/{serviceId}`) and reconciles group vars per key on later runs. Env groups carry the ownership marker, so they are prunable.
+
+## Projects and environments
+
+A `Project` groups `Environment`s; a service, datastore, or env group joins one through `environmentId`. Reference the declared environment and the applier fills the id:
+
+```ts
+import { Project, ProjectEnvironment, Environment, Postgres } from "@intentius/chant-lexicon-render";
+
+export const project = new Project({ name: "shop", environments: [new ProjectEnvironment({ name: "production" })] });
+export const prod = new Environment({ name: "production", projectId: project, protectedStatus: "protected" });
+export const db = new Postgres({ name: "shop-db", plan: "basic_1gb", version: "16", environmentId: prod });
+```
+
+`Project.environments` creates environments with the project (Render requires at least one); a separate `Environment` resource is how you reference one from other resources and PATCH it later. Reconciling by name means the environment created inline and the one declared separately are the same live object.
+
+## Persistent disks
+
+Two ways. Inline, as part of the service (created with it):
+
+```ts
+serviceDetails: new WebServiceDetails({ runtime: "docker", plan: "starter", disk: new ServiceDisk({ name: "data", mountPath: "/data", sizeGB: 10 }) })
+```
+
+Or as a standalone `Disk` attached to a declared service, which can be resized independently:
+
+```ts
+export const data = new Disk({ name: "data", sizeGB: 10, mountPath: "/data", serviceId: web });
+```
+
+Disks are only valid on web services, private services, and background workers (the `serviceId` type says so), and never on the free plan (REN012).
+
+## Custom domains
+
+```ts
+export const apex = new CustomDomain({ name: "example.com", serviceId: web });
+export const www = new CustomDomain({ name: "www.example.com", serviceId: web });
+```
+
+The domain is created under the service (`POST /services/{id}/custom-domains`); DNS verification stays a manual step in Render's dashboard or via the `/verify` endpoint. `describeResources` reports the domain's `verificationStatus` as its status.
+
+## Image-backed services
+
+```ts
+import { WebService, WebServiceDetails, Image, RegistryCredential } from "@intentius/chant-lexicon-render";
+
+export const cred = new RegistryCredential({ name: "ghcr", registry: "GITHUB", username: "me", authToken: process.env.GHCR_TOKEN! });
+export const api = new WebService({
+  name: "api",
+  image: new Image({ imagePath: "ghcr.io/acme/api:1.4.2", registryCredentialId: cred }),
+  serviceDetails: new WebServiceDetails({ runtime: "image", plan: "starter" }),
+});
+```
+
+`Image.ownerId` is filled from the service's owner. `registryCredentialId` accepts the declared credential. Deploying a new tag is a change to `imagePath` → a PATCH → Render redeploys.
+
+## Cron jobs
+
+```ts
+export const nightly = new CronJob({
+  name: "nightly-report",
+  repo: REPO,
+  serviceDetails: new CronJobDetails({
+    runtime: "python",
+    schedule: "0 3 * * *",
+    envSpecificDetails: new NativeEnvironmentDetails({ buildCommand: "pip install -r requirements.txt", startCommand: "python report.py" }),
+  }),
+});
+```
+
+`schedule` is a five-field cron expression (REN003); Render accepts no `@daily`-style macros.
+
+## Static sites
+
+```ts
+export const site = new StaticSite({
+  name: "docs",
+  repo: REPO,
+  serviceDetails: new StaticSiteDetails({
+    buildCommand: "npm ci && npm run build",
+    publishPath: "dist",
+    routes: [new Route({ type: "rewrite", source: "/*", destination: "/index.html" })],
+    headers: [new Header({ path: "/*", name: "X-Frame-Options", value: "DENY" })],
+  }),
+});
+```
+
+## The ownership model
+
+Render has no tags or labels. chant's marker is an env var:
+
+- **Services and env groups** carry `CHANT_MANAGED_BY=chant`, `CHANT_STACK=<stack>`, `CHANT_ENV=<env>` in their env vars. That is the primary marker: `describeResources` answers `owned` / `foreign` from it, and `prune: true` deletes only marked resources of the current stack that the plan no longer declares. A service someone created in the dashboard is `foreign` and is never modified or deleted by prune — but it *is* adopted by name if you declare it (a PATCH brings it to the declared shape and stamps the marker).
+- **Disks and custom domains** have no marker but hang off a service and inherit its verdict — the service boundary. An undeclared disk or domain under a chant-owned service is pruned with `prune: true`; one under a foreign service is foreign and untouched.
+- **Everything else** (Postgres, KeyValue, Project, Environment, RegistryCredential, Webhook) has no marker channel and no boundary; its verdict is `unknown` and it is never pruned. Remove one by dropping it from the plan and running `renderDelete` on the old plan, or by hand.
+
+The marker keys are visible in the service's environment. That is deliberate — it is the same information a Kubernetes label or an AWS tag carries, in the only durable key/value store Render exposes.

package/src/skills/chant-render.md

@@ -0,0 +1,112 @@
+---
+skill: chant-render
+description: Author, lint, and deploy Render services, datastores, and env groups from a chant project, applied straight to the Render Public API
+user-invocable: true
+---
+
+# Deploy to Render Operational Playbook
+
+## How chant and Render relate
+
+chant is a synthesis compiler: it compiles TypeScript in `src/` into a plan of Render Public API create requests, then reconciles that plan against a Render workspace. There is no external CLI to hand off to and no Blueprint (`render.yaml`) to keep in sync. `renderApply` speaks the Public API directly (`https://api.render.com/v1`), so the same code that builds the plan also applies it, and there is no state file to store, lock, or back up.
+
+The source of truth is the TypeScript in `src/`. The serialized plan (a JSON object keyed by entity name, each value a `{ kind, entityType, endpoint, method, name, body }` request) is an intermediate artifact.
+
+Your job as an agent:
+
+- Use `chant build` for synthesis and lint (region, secret literals, cron schedule, runtime commands, source, free-plan scaling).
+- Use `renderApply` (via the deploy Op, `chant run`) to reconcile the plan against the workspace: create or update each resource by name, wait each created service's deploy to `live`, and optionally prune what chant owns.
+
+## Credentials and the workspace
+
+Three environment variables:
+
+- `RENDER_API_KEY` — a Render API key (Account Settings → API Keys). Required for every apply and read. Sent as `Authorization: Bearer`.
+- `RENDER_OWNER_ID` — the workspace (team or personal) id, `tea-…` or `usr-…`. Every `ownerId` chant fills in defaults to it (`Render.OwnerId`). If unset, the applier reads `GET /owners` and uses the sole workspace the key can see; several visible workspaces is an error, never a guess.
+- `RENDER_API_BASE_URL` — optional endpoint override (a local stand-in). Default `https://api.render.com/v1`.
+
+Resolution order for the endpoint is: an explicit `endpoint` arg, then `RENDER_API_BASE_URL`, then the default.
+
+Start from the runnable [`examples/getting-started`](../../lexicons/render/examples/getting-started) stack:
+
+```bash
+cd lexicons/render/examples/getting-started
+export RENDER_API_KEY=rnd_…  RENDER_OWNER_ID=tea-…
+npm run build        # chant build src --lexicon render -o dist/render.json
+chant run render     # build → renderApply (creates the web service, waits for its deploy)
+```
+
+## Author a service and a database
+
+Import resource types from `@intentius/chant-lexicon-render`. They are generated from Render's Public API OpenAPI spec, so `WebServiceDetails`, `Image`, `ServiceDisk`, and friends are typed all the way down, and every enum (`plan`, `region`, `runtime`) is a string-literal union.
+
+```ts
+import {
+  WebService, WebServiceDetails, NativeEnvironmentDetails, EnvVar, GeneratedEnvVar, Postgres, Render,
+} from "@intentius/chant-lexicon-render";
+
+export const db = new Postgres({ name: "app-db", plan: "free", version: "16", region: Render.Region });
+
+export const web = new WebService({
+  name: "app-web",
+  repo: "https://github.com/render-examples/express-hello-world",
+  branch: "main",
+  serviceDetails: new WebServiceDetails({
+    runtime: "node",
+    plan: "starter",
+    region: Render.Region,
+    envSpecificDetails: new NativeEnvironmentDetails({ buildCommand: "npm ci", startCommand: "npm start" }),
+  }),
+  envVars: [
+    new EnvVar({ key: "DATABASE_URL", value: db.internalConnectionString }),
+    new GeneratedEnvVar({ key: "SESSION_SECRET", generateValue: true }),
+  ],
+});
+```
+
+Each service type is its own class — `WebService`, `StaticSite`, `PrivateService`, `BackgroundWorker`, `CronJob` — with `serviceDetails` narrowed to that type's shape (`CronJobDetails` requires `schedule`; `StaticSiteDetails` has `publishPath` and `routes`). The other resources are `Postgres`, `KeyValue`, `EnvGroup`, `Project`, `Environment`, `Disk`, `CustomDomain`, `RegistryCredential`, and `Webhook`.
+
+You do not stamp the ownership marker yourself: the serializer writes `CHANT_MANAGED_BY=chant` (plus `CHANT_STACK` / `CHANT_ENV`) into each service's and env group's `envVars`, and the owned-only prune reads it back.
+
+### References between resources
+
+Render assigns ids on create, so a Disk's `serviceId`, an Environment's `projectId`, or a service's `environmentId` cannot be a literal at build time. Pass the declared resource instead — `serviceId: web`, `projectId: project`, `environmentId: env` — and the applier substitutes the live id after the target exists. Attribute reads work the same way: `db.internalConnectionString`, `db.externalConnectionString`, `kv.internalConnectionString`, `web.id`, `web.dashboardUrl` resolve from the live resource (connection strings from the `/connection-info` endpoint).
+
+## Build and lint
+
+```bash
+chant build src/
+```
+
+Build synthesizes the plan and runs the lint rules before anything reaches the API:
+
+| Rule | Catches |
+|------|---------|
+| REN001 | `region` is not a Render region (frankfurt, oregon, ohio, singapore, virginia) |
+| REN002 | A secret-looking env var (`*_PASSWORD`, `*_TOKEN`, `API_KEY`, …) with a literal value |
+| REN003 | A `schedule` that is not a five-field cron expression |
+| REN010 | A native-runtime service (node, python, …) with no `buildCommand`/`startCommand` |
+| REN011 | A service with neither `repo` nor `image`, or `runtime: "image"` without an image |
+| REN012 | A free-plan service with `numInstances > 1`, `autoscaling`, or a `disk` |
+
+Fix every reported violation before applying. Secret values belong in `generateValue: true`, an `EnvGroup`, a resource attribute, or `process.env` — never a literal (REN002).
+
+## Apply with renderApply
+
+`renderApply` reads the plan and, in dependency order (projects → environments → env groups/datastores → services → disks/domains → webhooks):
+
+1. Resolves `{ $ref }`, `{ $attr }`, and `{ $owner }` markers from what is already live.
+2. Finds the existing resource by name (services also by type; environments by project; disks by service).
+3. `POST`s a create when absent, or `PATCH`es the differing patchable fields when present. Service env vars are replaced through `PUT /services/{id}/env-vars`; a `generateValue` var keeps its live value rather than being regenerated. Env-group vars are reconciled per key.
+4. Waits each **created** service's first deploy to `live` (`wait.deploys: false` to skip; `wait.deadlineMs` default 15 minutes) and throws on `build_failed`/`update_failed`/`canceled`.
+5. With `prune: true`, deletes services and env groups that carry the marker for this stack but are no longer in the plan, and the disks and custom domains under an owned declared service that the plan no longer declares. Foreign resources (no marker) and other stacks' resources are never touched. Datastores, projects, environments, registry credentials, and webhooks are never pruned — they have no marker; remove them explicitly with `renderDelete`.
+
+Returns the versioned apply envelope: `applied` (`created` / `updated` / `unchanged`, with the Render id as `physicalId`) and `pruned`.
+
+## Read back with plan
+
+`chant lifecycle plan` (via `describeResources`) lists what is live for every declared entity, with an ownership verdict: services and env groups are `owned` or `foreign` by the marker; disks and custom domains inherit their service's verdict; everything else is `unknown`, which the change set never escalates to a delete. Undeclared chant-owned services, env groups, disks, and domains surface as owned orphans, so a removed declaration shows up as a delete candidate before you prune.
+
+## Teardown
+
+`renderDelete` (or `renderDeploy({ teardown: true })`) deletes what the plan names in reverse order, looking each up by name; already-gone resources are reported `deleted: false`. Only what the plan declares is touched.

package/src/spec/fetch.ts

@@ -0,0 +1,33 @@
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache } from "@intentius/chant/codegen/fetch";
+
+/**
+ * Render's published Public API OpenAPI 3.0 spec.
+ *
+ * Render serves the current spec at a fixed URL with no version or release tag
+ * to pin (the document's own `info.version` has sat at "1.0.0" across many
+ * additive changes), so — like fly — the plugin declares no `upstreamPin`.
+ * Re-running `generate` picks up whatever the URL currently serves.
+ */
+export const SCHEMA_URL = "https://api-docs.render.com/v1.0/openapi/render-public-api-1.json";
+
+/**
+ * Cache under `~/.chant` so CI's `~/.chant` schema cache covers it — an
+ * api-docs.render.com hiccup then falls back to the cache instead of failing
+ * the generate step.
+ */
+const CACHE_FILE = join(homedir(), ".chant", "render-public-api-openapi.json");
+
+/**
+ * Fetch the Render OpenAPI spec and return it as a Map<typeName, Buffer>
+ * compatible with the generatePipeline fetchSchemas callback.
+ *
+ * The spec is a single document, so we return a single entry keyed by
+ * "Render::OpenAPI" — the parse step splits it into the curated resources and
+ * their reachable property types.
+ */
+export async function fetchSchemas(options?: { force?: boolean }): Promise<Map<string, Buffer>> {
+  const raw = await fetchWithCache({ url: SCHEMA_URL, cacheFile: CACHE_FILE }, options?.force);
+  return new Map([["Render::OpenAPI", raw]]);
+}