@rebasepro/types 0.16.0 → 0.16.1-canary.g0d7af95

package/src/types/resource_kinds.ts

@@ -0,0 +1,324 @@
+/**
+ * The kinds Rebase ships, and the constructors a project declares them with.
+ *
+ * Each kind is registered rather than hardcoded, so a fourth one arrives
+ * without editing a manifest schema, a validator and a switch statement. That
+ * cost is precisely why databases and buckets ended up declared in different
+ * files with different rules — the cheapest thing to do was always to bolt the
+ * new kind onto whichever home was nearest.
+ *
+ * A kind owns its engine list. `custom:<id>` is always accepted, so a build
+ * that ships an engine this package has never heard of says so at the call site
+ * instead of looking like a typo of one that exists.
+ */
+import {
+    DEFAULT_RESOURCE_KEY,
+    declareResource,
+    declaredResources,
+    registerResourceKind,
+    type DeclareOptions,
+    type ResourceHandle,
+    type ResourceTransport
+} from "./resources";
+
+// ── database ─────────────────────────────────────────────────────────────────
+
+registerResourceKind({
+    kind: "database",
+    engines: ["postgres", "mongodb", "firestore", "sqlite"],
+    defaultEngine: "postgres",
+    // REBASE_DRIVER overrides the engine's default driver package; the pool
+    // ceiling is per-source because one source can be a single-session PGlite
+    // and another a real server.
+    envBases: ["DATABASE_URL", "REBASE_DRIVER", "REBASE_DB_POOL_MAX"],
+    // No per-engine narrowing: every engine binds from the same three, and the
+    // driver package that differs between them is named by REBASE_DRIVER either
+    // way.
+    optionKeys: ["databaseId", "migrations"],
+    // A backend without a database is not a backend, so one exists whether or
+    // not a project says so.
+    implicitDefault: true
+});
+
+/** Options a database accepts beyond the common ones. */
+export interface DatabaseOptions extends DeclareOptions {
+    /**
+     * The physical database or schema within the engine, when it differs from
+     * the engine's own default. Threaded to drivers as `databaseId`.
+     */
+    databaseId?: string;
+    /** Directory of migration files, relative to the config directory. */
+    migrations?: string;
+}
+
+/** A database handle. Collections point at it via `dataSource`. */
+export type DatabaseHandle = ResourceHandle;
+
+/**
+ * Declare a database.
+ *
+ * ```ts
+ * export const main      = database();               // the default one
+ * export const analytics = database("analytics");    // reads DATABASE_URL__ANALYTICS
+ * ```
+ */
+export function database(key: string = DEFAULT_RESOURCE_KEY, options: DatabaseOptions = {}): DatabaseHandle {
+    return declareResource("database", key, options);
+}
+
+// ── bucket ───────────────────────────────────────────────────────────────────
+
+registerResourceKind({
+    kind: "bucket",
+    engines: ["local", "s3", "gcs", "azure", "firebase"],
+    defaultEngine: "local",
+    envBases: ["S3_BUCKET", "GCS_BUCKET", "STORAGE_BUCKET", "STORAGE_PUBLIC_URL"],
+    envBasesByEngine: {
+        local: ["STORAGE_BUCKET"],
+        s3: ["S3_BUCKET", "STORAGE_ENDPOINT", "STORAGE_REGION", "STORAGE_PUBLIC_URL"],
+        gcs: ["GCS_BUCKET", "STORAGE_PUBLIC_URL"],
+        azure: ["STORAGE_BUCKET", "STORAGE_PUBLIC_URL"],
+        firebase: ["STORAGE_BUCKET", "STORAGE_PUBLIC_URL"]
+    },
+    optionKeys: ["publicRead", "prefix", "account"],
+    // Storage is genuinely optional: plenty of projects store nothing.
+    implicitDefault: false
+});
+
+/** Options a bucket accepts beyond the common ones. */
+export interface BucketOptions extends DeclareOptions {
+    /**
+     * Whether objects are world-readable by default.
+     *
+     * Declared rather than inferred from the engine, because the two have
+     * disagreed before: a private object served through a cacheable public URL
+     * is a data leak that nothing errors on.
+     */
+    publicRead?: boolean;
+    /** Key prefix within the bucket, for sharing one bucket between sources. */
+    prefix?: string;
+    /**
+     * The credential set this bucket signs with, when several share one.
+     *
+     * `bucket("media", { engine: "s3", account: "minio" })` keeps reading its own
+     * `S3_BUCKET__MEDIA` — the bucket name is what distinguishes one source from
+     * another and never falls back — while the provider-level variables
+     * (`S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_ENDPOINT`, `S3_REGION`,
+     * `S3_FORCE_PATH_STYLE`) fall back to `__MINIO` when no per-key value is set.
+     *
+     * Fifteen buckets on one install go from ninety variables to eighteen, and
+     * rotating the key becomes one edit. A per-bucket value still wins, so a
+     * single source can move to another provider without breaking the rest off
+     * their shared account.
+     */
+    account?: string;
+}
+
+/** A bucket handle. Storage properties point at it via `storageSource`. */
+export type BucketHandle = ResourceHandle;
+
+/**
+ * Declare a bucket.
+ *
+ * ```ts
+ * export const media = bucket("media", { transport: "direct" });
+ * ```
+ *
+ * `transport: "direct"` means a provider SDK talks to the bucket and the
+ * backend is not in the upload path.
+ */
+export function bucket(key: string = DEFAULT_RESOURCE_KEY, options: BucketOptions = {}): BucketHandle {
+    return declareResource("bucket", key, options);
+}
+
+// ── topic ────────────────────────────────────────────────────────────────────
+
+registerResourceKind({
+    kind: "topic",
+    // `jobs` is the durable local implementation: a topic fans out to one job
+    // row per subscription, so each subscriber retries on its own schedule and
+    // a failure is a row somebody can look at rather than a lost message.
+    engines: ["jobs"],
+    defaultEngine: "jobs",
+    envBases: ["REBASE_TOPIC_URL"],
+    optionKeys: ["delivery", "maxAttempts"],
+    implicitDefault: false
+});
+
+/**
+ * How hard the runtime tries to deliver.
+ *
+ * Only `at-least-once` is implemented, and it is the honest name for what a
+ * retrying queue does: a handler must tolerate seeing the same event twice.
+ * `at-most-once` is listed so a future transport can offer it without the
+ * option changing shape, and is refused today rather than silently upgraded.
+ */
+export type TopicDelivery = "at-least-once" | "at-most-once";
+
+/** Options a topic accepts beyond the common ones. */
+export interface TopicOptions extends DeclareOptions {
+    delivery?: TopicDelivery;
+    /** Attempts per subscription before a message is left failed. Default 5. */
+    maxAttempts?: number;
+}
+
+/**
+ * What a subscription does with an event.
+ *
+ * `attempt` counts from 1. Worth branching on: the first delivery and the
+ * fourth are the same call, but the fourth is where it is worth logging loudly.
+ */
+export type TopicHandler<T> = (event: T, context: { attempt: number; topic: string; subscription: string }) => Promise<void> | void;
+
+/** A declared subscription, as recorded in the graph and wired at boot. */
+export interface TopicSubscription<T = unknown> {
+    topic: string;
+    name: string;
+    handler: TopicHandler<T>;
+    maxAttempts?: number;
+}
+
+/**
+ * What a topic publishes through.
+ *
+ * Installed by `@rebasepro/server` at boot. Absent — in the CLI evaluating
+ * config to derive the graph, or in a unit test — publishing throws a message
+ * naming the cause, rather than resolving and dropping the event. A publish
+ * that silently does nothing is the failure mode a queue exists to prevent.
+ */
+export interface TopicRuntime {
+    publish(topic: string, event: unknown): Promise<void>;
+}
+
+const runtimeHolder: { current: TopicRuntime | null } = { current: null };
+
+/** Install the transport topics publish through. Called by the server at boot. */
+export function setTopicRuntime(runtime: TopicRuntime | null): void {
+    runtimeHolder.current = runtime;
+}
+
+const subscriptions: TopicSubscription[] = [];
+
+/** Every declared subscription, for the worker to wire and the graph to record. */
+export function declaredSubscriptions(topic?: string): TopicSubscription[] {
+    return topic ? subscriptions.filter(s => s.topic === topic) : subscriptions.slice();
+}
+
+/** Forget declared subscriptions. For tests, alongside `resetDeclaredResources`. */
+export function resetDeclaredSubscriptions(): void {
+    subscriptions.length = 0;
+}
+
+/** A topic handle, carrying its payload type. */
+export interface TopicHandle<T> extends ResourceHandle {
+    /**
+     * Publish an event.
+     *
+     * Resolves once the event is durably recorded for every subscription, not
+     * once they have run. Enqueued inside a transaction that rolls back, it was
+     * never published.
+     */
+    publish(event: T): Promise<void>;
+    /**
+     * Declare a subscription.
+     *
+     * The name is its identity: it is what the job row records, what a retry
+     * counts against, and what a second subscription must not collide with.
+     */
+    subscription(name: string, handler: TopicHandler<T>, options?: { maxAttempts?: number }): void;
+}
+
+/**
+ * Declare a topic.
+ *
+ * ```ts
+ * export const signups = topic<{ userId: string }>("signups");
+ * signups.subscription("send-welcome", async (event) => { … });
+ * await signups.publish({ userId });
+ * ```
+ */
+export function topic<T = unknown>(key: string, options: TopicOptions = {}): TopicHandle<T> {
+    if (options.delivery === "at-most-once") {
+        throw new Error(
+            `Topic "${key}" asks for at-most-once delivery, which no shipped transport implements. ` +
+            "The durable queue behind topics retries, so it is at-least-once and a handler must " +
+            "tolerate seeing an event twice. Refused rather than quietly given the other guarantee."
+        );
+    }
+    const handle = declareResource("topic", key, options);
+
+    return {
+        ...handle,
+        toString() { return key; },
+        async publish(event: T): Promise<void> {
+            const runtime = runtimeHolder.current;
+            if (!runtime) {
+                throw new Error(
+                    `Cannot publish to topic "${key}": no topic runtime is installed. ` +
+                    "Publishing works inside a running Rebase backend; this looks like config " +
+                    "being evaluated outside one (a build, a script, or a test without a harness)."
+                );
+            }
+            await runtime.publish(key, event);
+        },
+        subscription(name: string, handler: TopicHandler<T>, subOptions: { maxAttempts?: number } = {}): void {
+            if (!name || name.trim() === "") {
+                throw new Error(`A subscription on topic "${key}" needs a non-empty name.`);
+            }
+            if (subscriptions.some(s => s.topic === key && s.name === name)) {
+                throw new Error(
+                    `Topic "${key}" already has a subscription named "${name}". ` +
+                    "The name is what a job row records and what a retry counts against, so two " +
+                    "cannot share one."
+                );
+            }
+            subscriptions.push({
+                topic: key,
+                name,
+                handler: handler as TopicHandler<unknown>,
+                ...(subOptions.maxAttempts !== undefined ? { maxAttempts: subOptions.maxAttempts } : {})
+            });
+        }
+    } as TopicHandle<T>;
+}
+
+// ── Handing declarations to the frontend ─────────────────────────────────────
+
+/**
+ * The declared databases, in the shape `<Rebase dataSources>` takes.
+ *
+ * The frontend needs to know which sources exist and how they are reached — a
+ * `direct`-transport source is one the browser talks to itself — and it imports
+ * the same config package the backend does. Without these it would mean writing
+ * the list a second time, by hand, next to the declarations, which is precisely
+ * the two-homes problem this model removed everywhere else.
+ *
+ * ```tsx
+ * import "../config/resources";                 // registers them
+ * import { declaredDataSources, declaredStorageSources } from "@rebasepro/types";
+ *
+ * <Rebase dataSources={declaredDataSources()} storageSources={declaredStorageSources()} />
+ * ```
+ *
+ * The import is what registers them, so a bundler that drops an unused module
+ * would leave this empty — hence the side-effect import above rather than a
+ * bare re-export.
+ */
+export function declaredDataSources(): { key: string; engine: string; transport: ResourceTransport; label?: string }[] {
+    return declaredResources("database").map(r => ({
+        key: r.key,
+        engine: r.engine,
+        transport: r.transport,
+        ...(r.label !== undefined ? { label: r.label } : {})
+    }));
+}
+
+/** The declared buckets, in the shape `<Rebase storageSources>` takes. */
+export function declaredStorageSources(): { key: string; engine: string; transport: ResourceTransport; label?: string }[] {
+    return declaredResources("bucket").map(r => ({
+        key: r.key,
+        engine: r.engine,
+        transport: r.transport,
+        ...(r.label !== undefined ? { label: r.label } : {})
+    }));
+}

package/src/types/resources.ts

@@ -0,0 +1,368 @@
+/**
+ * The resource graph: one declaration site for every named thing a project needs.
+ *
+ * ## The rule
+ *
+ * **Every named resource is declared with a constructor in config code.** A
+ * database, a bucket, a topic and whatever kind comes next are all spelled the
+ * same way, so "where do I declare my second one" has one answer instead of one
+ * answer per kind.
+ *
+ * ```ts
+ * export const main    = database("main");
+ * export const media   = bucket("media", { transport: "direct" });
+ * export const signups = topic<SignupEvent>("signups");
+ * ```
+ *
+ * ## Declaration is not binding
+ *
+ * A declaration says a resource *exists* and what shape it has. It never says
+ * how to reach it — that is a property of the environment, not of the project,
+ * and it differs between a laptop, a self-hosted box and a tenant in the cloud.
+ * Binding lives in `@rebasepro/server`'s boot path, reading environment
+ * variables or an infrastructure config file, and it keys off the logical name
+ * declared here.
+ *
+ * This split is the whole point. Before it, storage topology was hand-written
+ * into `rebase.json` while database topology lived in TypeScript, and the
+ * boundary between them was a fact about what the control plane could read
+ * before a build — a platform implementation detail that a developer had no way
+ * to derive. Worse, storage could be declared in *both* places, and the merge
+ * silently kept the JSON's engine and discarded the code's.
+ *
+ * ## Why a registry rather than a fixed union
+ *
+ * Kinds register themselves. Adding pub/sub, a cache or a search index must not
+ * require editing a manifest schema, a validator and three switch statements —
+ * that cost is exactly why the last two kinds ended up in different homes.
+ */
+
+/** How a client reaches a resource. */
+export type ResourceTransport =
+    /** Through the backend. The default, and the only one that needs no client SDK. */
+    | "server"
+    /** A provider SDK talks to the resource directly; the backend is not in the path. */
+    | "direct";
+
+/**
+ * A resource kind, as registered.
+ *
+ * `engines` is an allowlist rather than documentation. An unrecognised engine
+ * used to be a free string that passed every check and failed later, further
+ * from the typo that caused it — `"s2"` for `"s3"` reached the runtime. Anything
+ * genuinely outside the list is spelled `custom:<id>`, which says so at the call
+ * site instead of looking like a typo.
+ */
+export interface ResourceKindSpec {
+    /** The kind's name, as it appears in a declaration and in the graph. */
+    kind: string;
+    /** Engines this kind ships with. `custom:<id>` is always additionally valid. */
+    engines: readonly string[];
+    /** Used when a declaration names none. */
+    defaultEngine: string;
+    /**
+     * Environment variable base names this kind binds from, in the order a
+     * binder should try them. A resource keyed `analytics` reads
+     * `<BASE>__ANALYTICS`; the default-keyed resource reads `<BASE>` unsuffixed,
+     * so a single-resource project configured the obvious way declares nothing.
+     */
+    envBases: readonly string[];
+    /**
+     * The subset of `envBases` that matters for a given engine.
+     *
+     * The binder reads every base and takes whichever is set — harmless, and it
+     * keeps binding tolerant. A GENERATOR cannot be that relaxed: `rebase eject
+     * infra` writing S3_BUCKET, GCS_BUCKET, STORAGE_BUCKET and
+     * STORAGE_PUBLIC_URL for a `local` bucket hands somebody four variables of
+     * which three are noise, and a config file full of irrelevant keys is one
+     * nobody reads carefully.
+     *
+     * Keyed by engine; an engine with no entry falls back to all of them, which
+     * is the honest answer for one this package has never heard of.
+     */
+    envBasesByEngine?: Readonly<Record<string, readonly string[]>>;
+    /** Option keys this kind accepts beyond the common ones, for validation. */
+    optionKeys?: readonly string[];
+    /**
+     * Whether a project implicitly has one of these even when it declares
+     * nothing. True for databases — a backend without one is not a backend —
+     * and false for topics, where zero is the normal number.
+     */
+    implicitDefault?: boolean;
+}
+
+/** The key a resource takes when a project declares only one of its kind. */
+export const DEFAULT_RESOURCE_KEY = "(default)";
+
+/** A declared resource, as it appears in the graph. */
+export interface ResourceDeclaration {
+    kind: string;
+    /** Unique within its kind. What a binder looks up and what an env suffix is built from. */
+    key: string;
+    engine: string;
+    transport: ResourceTransport;
+    label?: string;
+    /** Kind-specific options, validated against the kind's `optionKeys`. */
+    options: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * The value a constructor returns.
+ *
+ * Carries its own declaration so config code can hold it and pass it around,
+ * and stringifies to its key so it drops into the places that still take one.
+ * Collections name a data source by string today; a handle works there without
+ * the collection API having to change, which keeps this a config redesign
+ * rather than a rewrite of the data layer.
+ */
+export interface ResourceHandle extends ResourceDeclaration {
+    toString(): string;
+}
+
+const BRAND = Symbol.for("@rebasepro/types.resource");
+
+/** Whether a value is a resource handle rather than a plain string key. */
+export function isResourceHandle(value: unknown): value is ResourceHandle {
+    return typeof value === "object" && value !== null && BRAND in value;
+}
+
+/** The key a resource reference names, whether it is a handle or already a key. */
+export function resourceKeyOf(ref: string | ResourceHandle): string {
+    return isResourceHandle(ref) ? ref.key : ref;
+}
+
+/**
+ * The process-wide registry.
+ *
+ * Keyed off `globalThis` through a shared symbol rather than held in a module
+ * local, because a module local is per *copy* of this package. A project that
+ * ends up with two copies of `@rebasepro/types` — which a partially-linked
+ * `node_modules` produces, and which has already caused a phantom
+ * "JWT secret not configured" bug in this repo — would otherwise register into
+ * one registry and read from the other, and see an empty graph with nothing
+ * anywhere to explain it.
+ */
+interface Registry {
+    kinds: Map<string, ResourceKindSpec>;
+    declarations: Map<string, ResourceDeclaration>;
+}
+
+const GLOBAL_KEY = Symbol.for("@rebasepro/types.resourceRegistry");
+
+function registry(): Registry {
+    const g = globalThis as unknown as Record<symbol, Registry | undefined>;
+    let existing = g[GLOBAL_KEY];
+    if (!existing) {
+        existing = { kinds: new Map(), declarations: new Map() };
+        g[GLOBAL_KEY] = existing;
+    }
+    return existing;
+}
+
+/** `kind:key`, the graph's primary key. */
+function declarationId(kind: string, key: string): string {
+    return `${kind}:${key}`;
+}
+
+/** Register a resource kind. Idempotent for an identical spec; throws on a conflicting one. */
+export function registerResourceKind(spec: ResourceKindSpec): void {
+    const existing = registry().kinds.get(spec.kind);
+    if (existing && JSON.stringify(existing) !== JSON.stringify(spec)) {
+        throw new Error(
+            `Resource kind "${spec.kind}" is already registered with a different definition. ` +
+            "Two packages cannot define the same kind."
+        );
+    }
+    registry().kinds.set(spec.kind, spec);
+}
+
+/** Every registered kind, for validators and for `rebase doctor`. */
+export function resourceKinds(): ResourceKindSpec[] {
+    return [...registry().kinds.values()];
+}
+
+/** One registered kind, or undefined. */
+export function resourceKind(kind: string): ResourceKindSpec | undefined {
+    return registry().kinds.get(kind);
+}
+
+/** Options every kind accepts. */
+export interface DeclareOptions {
+    engine?: string;
+    transport?: ResourceTransport;
+    label?: string;
+    [option: string]: unknown;
+}
+
+const COMMON_OPTION_KEYS = ["engine", "transport", "label"] as const;
+
+/** Whether an engine is one the kind knows, or an explicit `custom:` opt-out. */
+export function isValidEngine(spec: ResourceKindSpec, engine: string): boolean {
+    return engine.startsWith("custom:") || spec.engines.includes(engine);
+}
+
+/**
+ * Declare a resource. The primitive every kind's constructor is built from.
+ *
+ * Redeclaring the same `kind:key` with a *different* shape throws rather than
+ * merging. Merging is what the old storage path did, and it silently discarded
+ * one of the two engines — a declaration accepted and then ignored, which is
+ * the failure this whole model exists to remove. Redeclaring it identically is
+ * fine: a config module evaluated twice must not be an error.
+ */
+export function declareResource(
+    kind: string,
+    key: string = DEFAULT_RESOURCE_KEY,
+    options: DeclareOptions = {}
+): ResourceHandle {
+    const spec = registry().kinds.get(kind);
+    if (!spec) {
+        const known = [...registry().kinds.keys()].sort().join(", ") || "none";
+        throw new Error(
+            `Unknown resource kind "${kind}". Registered kinds: ${known}. ` +
+            "Call registerResourceKind() before declaring one."
+        );
+    }
+
+    if (!key || typeof key !== "string" || key.trim() === "") {
+        throw new Error(`A ${kind} needs a non-empty key.`);
+    }
+
+    const engine = options.engine ?? spec.defaultEngine;
+    if (!isValidEngine(spec, engine)) {
+        throw new Error(
+            `Unknown ${kind} engine "${engine}" for "${key}". ` +
+            `Known engines: ${spec.engines.join(", ")}. ` +
+            `An engine this build does not ship is spelled "custom:${engine}", ` +
+            "which says so at the call site rather than failing later."
+        );
+    }
+
+    const allowed = new Set<string>([...COMMON_OPTION_KEYS, ...(spec.optionKeys ?? [])]);
+    const unknown = Object.keys(options).filter(k => !allowed.has(k));
+    if (unknown.length > 0) {
+        throw new Error(
+            `Unknown option(s) on ${kind} "${key}": ${unknown.join(", ")}. ` +
+            `A ${kind} accepts: ${[...allowed].sort().join(", ")}.`
+        );
+    }
+
+    const extra: Record<string, unknown> = {};
+    for (const k of spec.optionKeys ?? []) {
+        if (options[k] !== undefined) extra[k] = options[k];
+    }
+
+    const declaration: ResourceDeclaration = {
+        kind,
+        key,
+        engine,
+        transport: options.transport ?? "server",
+        ...(options.label !== undefined ? { label: options.label } : {}),
+        options: Object.freeze(extra)
+    };
+
+    const id = declarationId(kind, key);
+    const previous = registry().declarations.get(id);
+    if (previous) {
+        if (JSON.stringify(previous) !== JSON.stringify(declaration)) {
+            throw new Error(
+                `${kind} "${key}" is declared twice with different configuration. ` +
+                "Declare it once and export it — two declarations of one resource is " +
+                "the ambiguity this model exists to remove, so it is refused rather " +
+                "than merged."
+            );
+        }
+    } else {
+        registry().declarations.set(id, declaration);
+    }
+
+    const handle = {
+        ...declaration,
+        toString() { return key; },
+        [BRAND]: true as const
+    };
+    return handle as ResourceHandle;
+}
+
+/** Every declared resource, in declaration order, optionally filtered by kind. */
+export function declaredResources(kind?: string): ResourceDeclaration[] {
+    const all = [...registry().declarations.values()];
+    return kind ? all.filter(r => r.kind === kind) : all;
+}
+
+/**
+ * Forget every declaration, keeping registered kinds.
+ *
+ * For tests and for a CLI that evaluates more than one project in a process.
+ * Kinds survive because they are registered by module import, which will not
+ * happen a second time.
+ */
+export function resetDeclaredResources(): void {
+    registry().declarations.clear();
+}
+
+/**
+ * The env-var suffix a resource's bindings use: `__ANALYTICS` for `analytics`,
+ * and nothing at all for the default-keyed one.
+ *
+ * The default takes no suffix so that a project with one database configured
+ * through plain `DATABASE_URL` keeps working having declared nothing — the
+ * overwhelmingly common project must not have to say so.
+ */
+export function resourceEnvSuffix(key: string): string {
+    if (key === DEFAULT_RESOURCE_KEY) return "";
+    return `__${key.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
+}
+
+/**
+ * Two resources of a kind whose keys differ but whose env suffixes do not.
+ *
+ * `media-files` and `media_files` both become `__MEDIA_FILES`, so one would
+ * silently read the other's configuration. Returned rather than thrown so the
+ * caller can report it with the rest of a validation pass.
+ */
+export function findEnvSuffixCollision(keys: readonly string[]): { a: string; b: string; suffix: string } | null {
+    const seen = new Map<string, string>();
+    for (const key of keys) {
+        const suffix = resourceEnvSuffix(key);
+        const previous = seen.get(suffix);
+        if (previous !== undefined && previous !== key) return { a: previous, b: key, suffix };
+        seen.set(suffix, key);
+    }
+    return null;
+}
+
+/**
+ * The whole graph, as recorded in a manifest and read by a host.
+ *
+ * `version` is the graph format, not the project's. A host reading a graph it
+ * does not understand must say so rather than provision half of it.
+ */
+export interface ResourceGraph {
+    version: 1;
+    resources: ResourceDeclaration[];
+}
+
+/** The current graph format version. */
+export const RESOURCE_GRAPH_VERSION = 1 as const;
+
+/** Build a graph from the current declarations, sorted for a stable diff. */
+export function buildResourceGraph(): ResourceGraph {
+    const resources = declaredResources().slice().sort(
+        (a, b) => a.kind.localeCompare(b.kind) || a.key.localeCompare(b.key)
+    );
+    return { version: RESOURCE_GRAPH_VERSION, resources };
+}
+
+/**
+ * The environment variables worth writing for a resource, given its engine.
+ *
+ * Falls back to every base the kind reads when the engine is unknown — a
+ * `custom:` engine gets the full list rather than an empty one, because
+ * guessing narrow would silently omit the variable it actually needs.
+ */
+export function envBasesForResource(declaration: ResourceDeclaration): readonly string[] {
+    const spec = resourceKind(declaration.kind);
+    if (!spec) return [];
+    return spec.envBasesByEngine?.[declaration.engine] ?? spec.envBases;
+}