@bedrock-rbx/core 0.1.0-beta.10 → 0.1.0-beta.12

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { C as ConfigError, S as validateConfig, _ as StateConfig, a as ConfigEnvironmentUniverseId, b as UniverseOverlayWithoutId, c as DisplayNamePrefixConfig, d as GistStateConfig, f as PlaceEntry, g as ResourceEntryByKind, h as ResolvedUniverseEntry, i as Config, l as EnvironmentEntry, m as ResolvedPlaceEntry, n as ConfigInput, o as ConfigRootUniverseId, p as ResolvedConfig, r as defineConfig, s as DeveloperProductEntry, t as ConfigContext, u as GamePassEntry, v as UniverseEntry, w as ConfigValidationIssue, x as isGistStateConfig, y as UniverseOverlayWithId } from "./define-config-87u2jqjM.mjs";
-import { Type as Type$1 } from "arktype";
 import { OpenCloudError, OpenCloudError as OpenCloudError$1, Result, Result as Result$1 } from "@bedrock-rbx/ocale";
+import { Type as Type$1 } from "arktype";
 import { DeveloperProductsClient } from "@bedrock-rbx/ocale/developer-products";
 import { GamePassesClient } from "@bedrock-rbx/ocale/game-passes";
 import { PlacesClient } from "@bedrock-rbx/ocale/places";
@@ -708,17 +708,16 @@ type Prettify<T> = { readonly [K in keyof T]: T[K] };
 */
 declare const UNIVERSE_SINGLETON_KEY: ResourceKey;
 //#endregion
-//#region src/ports/resource-driver.d.ts
+//#region src/core/state.d.ts
 /**
-* Plugin contract for a resource adapter: the interface a third-party author
-* implements to teach Bedrock how to reconcile one {@link ResourceKind} against
-* its upstream API.
+* In-memory state snapshot for one environment.
 *
-* `ResourceDriver<K>` is a *driven* (secondary) port in hexagonal terms; the
-* name "driver" follows Terraform, Pulumi, and Mantle IaC convention for a
-* component that talks to a specific resource API.
+* The on-disk JSON wraps this shape with a `$bedrock: { version: N }` envelope.
+* Adapters flatten the envelope on read and re-wrap it on write; nothing
+* outside an adapter sees the `$bedrock` key.
 *
-* @template K - The {@link ResourceKind} discriminator this driver handles.
+* `version` is a literal so a breaking schema change is a compile-time type
+* shift rather than a silently accepted runtime value.
 *
 * @example
 *
@@ -727,820 +726,708 @@ declare const UNIVERSE_SINGLETON_KEY: ResourceKey;
 *     asResourceKey,
 *     asRobloxAssetId,
 *     asSha256Hex,
-*     type ResourceDriver,
+*     type BedrockState,
 * } from "@bedrock-rbx/core";
 *
-* const gamePassDriver: ResourceDriver<"gamePass"> = {
-*     async create(desired) {
-*         return {
-*             data: {
-*                 ...desired,
-*                 outputs: {
-*                     assetId: asRobloxAssetId("9876543210"),
-*                     iconAssetIds: { "en-us": asRobloxAssetId("1122334455") },
-*                 },
+* const state: BedrockState = {
+*     environment: "production",
+*     resources: [
+*         {
+*             description: "Grants VIP perks.",
+*             icon: { "en-us": "assets/vip-icon.png" },
+*             iconFileHashes: {
+*                 "en-us": asSha256Hex(
+*                     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+*                 ),
 *             },
-*             success: true,
-*         };
-*     },
+*             key: asResourceKey("vip-pass"),
+*             kind: "gamePass",
+*             name: "VIP Pass",
+*             outputs: {
+*                 assetId: asRobloxAssetId("9876543210"),
+*                 iconAssetIds: { "en-us": asRobloxAssetId("1122334455") },
+*             },
+*             price: 500,
+*         },
+*     ],
+*     version: 1,
 * };
 *
-* return gamePassDriver
-*     .create({
-*         description: "Grants VIP perks.",
-*         icon: { "en-us": "assets/vip-icon.png" },
-*         iconFileHashes: {
-*             "en-us": asSha256Hex(
-*                 "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-*             ),
-*         },
-*         key: asResourceKey("vip-pass"),
-*         kind: "gamePass",
-*         name: "VIP Pass",
-*         price: undefined,
-*     })
-*     .then((result) => {
-*         expect(result.success).toBeTrue();
-*         if (result.success) {
-*             expect(result.data.outputs.assetId).toBe("9876543210");
-*         }
-*     });
+* expect(state.version).toBe(1);
+* expect(state.resources).toHaveLength(1);
 * ```
 */
-interface ResourceDriver<K extends ResourceKind> {
-  /**
-  * Create the resource upstream from its desired state and return the
-  * resulting current state (desired fields + Roblox-assigned outputs).
-  */
-  create(desired: Extract<ResourceDesiredState, {
-    kind: K;
-  }>): Promise<Result$1<ResourceCurrentState<K>, OpenCloudError$1>>;
-  /**
-  * Reconcile an upstream resource whose managed content has drifted from its
-  * desired state. Receives the last-known current state so the driver can
-  * compute a minimal patch (or no-op upstream, for file-backed kinds where
-  * republishing is unconditional).
-  *
-  * Optional. Drivers whose upstream API has no update operation omit this
-  * method; `applyOps` surfaces an `updateUnsupported` error at dispatch time
-  * instead.
-  */
-  update?(current: ResourceCurrentState<K>, desired: Extract<ResourceDesiredState, {
-    kind: K;
-  }>): Promise<Result$1<ResourceCurrentState<K>, OpenCloudError$1>>;
+interface BedrockState {
+  /** Environment name this snapshot belongs to (e.g. `"production"`, `"staging"`). */
+  readonly environment: string;
+  /** Current state of every resource Bedrock manages in this environment. */
+  readonly resources: ReadonlyArray<ResourceCurrentState>;
+  /** Schema-version literal; bumped only for breaking changes to the on-disk format. */
+  readonly version: 1;
 }
 /**
-* Polymorphic dispatch table keyed by {@link ResourceKind}, mapping each kind
-* to the {@link ResourceDriver} that handles it. `applyOps` indexes the
-* registry by `op.desired.kind` to reach the matching driver with full type
-* safety: adding a new kind to `ResourceDesiredState` is a compile error until
-* a matching registry entry is supplied.
+* Failure surfaced by a `StatePort` when a state file exists but cannot be
+* trusted: corrupt JSON, schema failure, or an unknown `$bedrock.version`.
+*
+* Narrow on `kind` rather than using `instanceof`: `StateError` is plain data,
+* not a thrown error subclass.
 *
 * @example
 *
 * ```ts
-* import { OpenCloudError, type DriverRegistry } from "@bedrock-rbx/core";
+* import type { StateError } from "@bedrock-rbx/core";
 *
-* const registry: DriverRegistry = {
-*     gamePass: {
-*         async create() {
-*             return { err: new OpenCloudError("not implemented"), success: false };
-*         },
-*     },
-*     place: {
-*         async create() {
-*             return { err: new OpenCloudError("not implemented"), success: false };
-*         },
-*     },
-*     universe: {
-*         async create() {
-*             return { err: new OpenCloudError("not implemented"), success: false };
-*         },
-*     },
-*     developerProduct: {
-*         async create() {
-*             return { err: new OpenCloudError("not implemented"), success: false };
-*         },
-*     },
+* const err: StateError = {
+*     file: ".bedrock/state/production.json",
+*     kind: "stateError",
+*     reason: "Corrupt JSON: unexpected token at line 1 column 5",
 * };
 *
-* expect(registry.gamePass).toBeObject();
+* expect(err.kind).toBe("stateError");
 * ```
 */
-type DriverRegistry = { [K in ResourceKind]: ResourceDriver<K> };
+interface StateError {
+  /** Adapter-specific path or identifier of the file that failed to parse. */
+  readonly file: string;
+  /** Literal discriminator for narrowing. */
+  readonly kind: "stateError";
+  /** Human-readable explanation of why the file could not be trusted. */
+  readonly reason: string;
+}
 //#endregion
-//#region src/adapters/developer-product-driver.d.ts
+//#region src/core/migrate/migration-report.d.ts
 /**
-* Dependencies of `createDeveloperProductDriver`. `universeId` is captured
-* at construction time (matching `GamePassDriverDeps`) so each driver
-* instance is bound to a single universe; multi-universe deploys construct
-* one driver per universe. `readFile` exists on the driver (not upstream
-* in shell) because icon hashes flow through `diff` but bytes do not.
-*
-* @example
-*
-* ```ts
-* import type { HttpClient } from "@bedrock-rbx/ocale";
-* import { DeveloperProductsClient } from "@bedrock-rbx/ocale/developer-products";
-* import { asRobloxAssetId, type DeveloperProductDriverDeps } from "@bedrock-rbx/core";
-*
-* const httpClient: HttpClient = {
-*     async request() {
-*         return { data: { body: {}, headers: {}, status: 200 }, success: true };
-*     },
-* };
-*
-* const deps: DeveloperProductDriverDeps = {
-*     client: new DeveloperProductsClient({
-*         apiKey: "rbx-your-key",
-*         httpClient,
-*         sleep: async () => {},
-*     }),
-*     readFile: async () => new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
-*     universeId: asRobloxAssetId("1234567890"),
-* };
+* Per-environment in-memory state snapshot map keyed by environment name.
 *
-* expect(deps.universeId).toBe("1234567890");
-* ```
+* `Record` rather than the PRD-suggested `Map` so the field survives
+* `JSON.stringify` for downstream logging and parallel-iterates cleanly
+* with `Config.environments` (which is itself a `Record`).
 */
-interface DeveloperProductDriverDeps {
-  /** Configured developer-products client from `@bedrock-rbx/ocale/developer-products`. */
-  readonly client: DeveloperProductsClient;
-  /** Reads icon bytes for upload; rejections propagate out of `create` and `update`. */
-  readonly readFile: (path: string) => Promise<Uint8Array>;
-  /** Universe that owns every developer product this driver creates. */
-  readonly universeId: RobloxAssetId;
+type StatesByEnvironment = Readonly<Record<string, BedrockState>>;
+/**
+* Aggregate counts for the four `MigrationWarning` kinds. Computed by
+* folding `MigrationReport.warnings`; lets a CI gate skim totals without
+* iterating every entry. All fields are zero on a clean migration.
+*/
+interface MigrationSummary {
+  /** Number of `ambiguous` warnings emitted. */
+  readonly ambiguousCount: number;
+  /** Number of `blocked` warnings emitted. */
+  readonly blockedCount: number;
+  /** Number of `deferred` warnings emitted. */
+  readonly deferredCount: number;
+  /** Number of `interpretive` warnings emitted. */
+  readonly interpretiveCount: number;
 }
 /**
-* Wraps {@link DeveloperProductsClient} as a `ResourceDriver<"developerProduct">`
-* that maps a desired-state entry to an ocale create or update call and the
-* response back to a `ResourceCurrentState<"developerProduct">`. The
-* `update` path consumes the upstream `204 No Content` response and
-* synthesizes the post-update `ResourceCurrentState` from `desired` plus
-* the existing `current.outputs`, carrying `iconImageAssetId` forward when
-* present.
+* Discriminated union describing one observation the migrator made about a
+* Mantle field that did not flow straight into bedrock config or state.
 *
-* Upstream `OpenCloudError` results pass through as `Result` failures.
+* - `deferred` - bedrock plans to support the field once the matching
+*   resource kind ships; the migration is non-destructive.
+* - `blocked` - no Open Cloud writable endpoint exists; Mantle was using a
+*   cookie or legacy API that bedrock cannot call.
+* - `interpretive` - the migrator applied a documented mapping rule
+*   (cross-field fold, list-to-flag rewrite, URL-domain dispatch). Each
+*   rule names the bedrock-side path it produced and the rule it followed
+*   so the user can audit.
+* - `ambiguous` - the field is mappable but unsafe to act on without
+*   user input; the migrator carries the hint forward instead of guessing.
 *
-* @param deps - Injected ocale client and owning universe.
-* @returns A driver indexable by `"developerProduct"` in a `DriverRegistry`.
+* Every variant carries `mantlePath` rooted at the environment so the
+* report is searchable (for example
+* `production.experienceConfiguration_singleton.genre`).
+*/
+type MigrationWarning = {
+  readonly bedrockPath: string;
+  readonly kind: "interpretive";
+  readonly mantlePath: string;
+  readonly rule: string;
+} | {
+  readonly hint: string;
+  readonly kind: "ambiguous";
+  readonly mantlePath: string;
+} | {
+  readonly kind: "blocked";
+  readonly mantlePath: string;
+  readonly reason: string;
+} | {
+  readonly kind: "deferred";
+  readonly mantlePath: string;
+  readonly reason: string;
+};
+/**
+* Failure surfaced by `migrateMantleState`. Plain-data discriminated
+* union; narrow on `kind` rather than using `instanceof`.
 *
-* @example
+* - `stateFileNotFound` - `deps.readFile` threw with `code: "ENOENT"`;
+*   the file does not exist at the supplied path. Permission failures
+*   (`EACCES`, `EPERM`) and other I/O errors are re-thrown rather than
+*   wrapped here, so callers see the original code on the rejection.
+* - `stateParseFailed` - the YAML parser refused the file's contents.
+* - `unsupportedMantleStateVersion` - the parsed file's `version` field is
+*   not one of the values in `supported`. V0.1 supports `"6"` only; older
+*   versions need to be upgraded with any recent Mantle release first.
+* - `primaryEnvironmentRequired` - the input has more than one environment
+*   and `deps.primaryEnvironment` was not supplied. The migrator refuses
+*   to silently pick a winner.
+* - `primaryEnvironmentNotFound` - `deps.primaryEnvironment` does not match
+*   any environment in the input.
+* - `internalError` - the migrator's own emitted config failed
+*   `validateConfig`; `cause` carries the `ConfigError` so callers can
+*   inspect each `validationFailed` issue. Defensive bug catcher that
+*   callers should never see in practice.
+*/
+type MigrateError = {
+  readonly available: ReadonlyArray<string>;
+  readonly kind: "primaryEnvironmentNotFound";
+  readonly primary: string;
+} | {
+  readonly available: ReadonlyArray<string>;
+  readonly kind: "primaryEnvironmentRequired";
+} | {
+  readonly cause: ConfigError;
+  readonly kind: "internalError";
+  readonly reason: string;
+} | {
+  readonly found: string;
+  readonly kind: "unsupportedMantleStateVersion";
+  readonly supported: ReadonlyArray<string>;
+} | {
+  readonly kind: "stateFileNotFound";
+  readonly path: string;
+} | {
+  readonly kind: "stateParseFailed";
+  readonly path: string;
+  readonly reason: string;
+};
+/**
+* Result returned by a successful `migrateMantleState` call.
 *
-* ```ts
-* import type { HttpClient } from "@bedrock-rbx/ocale";
-* import { DeveloperProductsClient } from "@bedrock-rbx/ocale/developer-products";
-* import {
-*     asResourceKey,
-*     asRobloxAssetId,
-*     createDeveloperProductDriver,
-* } from "@bedrock-rbx/core";
+* `config` is the bedrock-shape projection of the Mantle state file,
+* already validated against the runtime schema (a failure to validate
+* surfaces as `MigrateError.internalError`, not as a returned report).
 *
-* const httpClient: HttpClient = {
-*     async request() {
-*         return {
-*             data: {
-*                 body: {
-*                     createdTimestamp: "2024-01-15T10:30:00.000Z",
-*                     description: "Stocks the player up with 1,000 premium gems.",
-*                     iconImageAssetId: null,
-*                     isForSale: false,
-*                     isImmutable: false,
-*                     name: "Gem Pack",
-*                     priceInformation: null,
-*                     productId: 9_876_543_210,
-*                     storePageEnabled: false,
-*                     universeId: 1_234_567_890,
-*                     updatedTimestamp: "2024-01-15T10:30:00.000Z",
-*                 },
-*                 headers: {},
-*                 status: 200,
-*             },
-*             success: true,
-*         };
-*     },
-* };
+* `configFileContent` is the same data rendered as TypeScript source
+* (`defineConfig({...})`) so the caller can write it straight to disk
+* without re-serializing. `loadConfig` round-trips it cleanly.
 *
-* const driver = createDeveloperProductDriver({
-*     client: new DeveloperProductsClient({
-*         apiKey: "rbx-your-key",
-*         httpClient,
-*         sleep: async () => {},
-*     }),
-*     readFile: async () => new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
-*     universeId: asRobloxAssetId("1234567890"),
-* });
+* `statesByEnvironment` carries one in-memory `BedrockState` per
+* environment from the input. Truthful per environment (no factorization)
+* so `bedrock deploy --env=<env>` produces zero ops on first run.
 *
-* return driver
-*     .create({
-*         description: "Stocks the player up with 1,000 premium gems.",
-*         isRegionalPricingEnabled: undefined,
-*         key: asResourceKey("gem-pack"),
-*         kind: "developerProduct",
-*         name: "Gem Pack",
-*         price: undefined,
-*         storePageEnabled: undefined,
-*     })
-*     .then((result) => {
-*         expect(result.success).toBeTrue();
-*         if (result.success) {
-*             expect(result.data.outputs.productId).toBe("9876543210");
-*         }
-*     });
-* ```
+* `warnings` and `summary` describe what the migrator did *not* migrate
+* verbatim, classified for triage. The skeleton emits no warnings.
 */
-declare function createDeveloperProductDriver(deps: DeveloperProductDriverDeps): ResourceDriver<"developerProduct">;
+interface MigrationReport {
+  /** Validated bedrock config built from the Mantle state file. */
+  readonly config: Config;
+  /** Same `config` rendered as TypeScript source the caller can write to disk. */
+  readonly configFileContent: string;
+  /** One `BedrockState` per environment in the input, keyed by environment name. */
+  readonly statesByEnvironment: StatesByEnvironment;
+  /** Aggregate counts of `warnings` by kind. */
+  readonly summary: MigrationSummary;
+  /** One entry per non-trivial mapping or skipped Mantle field. */
+  readonly warnings: ReadonlyArray<MigrationWarning>;
+}
 //#endregion
-//#region src/adapters/game-pass-driver.d.ts
+//#region src/ports/state-port.d.ts
 /**
-* `universeId` is captured at construction time rather than on
-* `GamePassDesiredState` so state files round-trip with Mantle's `PassInputs`
-* shape. `readFile` exists on the driver (not upstream in shell) because icon
-* hashes flow through `diff` but bytes do not.
+* Plugin contract for persisting deployment state: the interface an adapter
+* (Gist, local filesystem, cloud object store) implements to let Bedrock load
+* and save its per-environment {@link BedrockState} snapshot.
+*
+* `StatePort` is a *driven* (secondary) port in hexagonal terms, following the
+* same naming convention as {@link "./resource-driver".ResourceDriver}.
 *
 * @example
 *
 * ```ts
-* import type { HttpClient } from "@bedrock-rbx/ocale";
-* import { GamePassesClient } from "@bedrock-rbx/ocale/game-passes";
-* import { asRobloxAssetId, type GamePassDriverDeps } from "@bedrock-rbx/core";
+* import type { BedrockState, StatePort } from "@bedrock-rbx/core";
 *
-* const httpClient: HttpClient = {
-*     async request() {
-*         return { data: { body: {}, headers: {}, status: 200 }, success: true };
-*     },
-* };
+* const store = new Map<string, BedrockState>();
 *
-* const deps: GamePassDriverDeps = {
-*     client: new GamePassesClient({
-*         apiKey: "rbx-your-key",
-*         httpClient,
-*         sleep: async () => {},
-*     }),
-*     readFile: async () => new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
-*     universeId: asRobloxAssetId("1234567890"),
+* const statePort: StatePort = {
+*     async read(environment) {
+*         return { data: store.get(environment), success: true };
+*     },
+*     async write(state) {
+*         store.set(state.environment, state);
+*         return { data: undefined, success: true };
+*     },
 * };
 *
-* expect(deps.universeId).toBe("1234567890");
+* return statePort
+*     .read("production")
+*     .then((firstRead) => {
+*         expect(firstRead.success).toBeTrue();
+*         if (firstRead.success) {
+*             expect(firstRead.data).toBeUndefined();
+*         }
+*         return statePort.write({
+*             environment: "production",
+*             resources: [],
+*             version: 1,
+*         });
+*     })
+*     .then((writeResult) => {
+*         expect(writeResult.success).toBeTrue();
+*         return statePort.read("production");
+*     })
+*     .then((secondRead) => {
+*         expect(secondRead.success).toBeTrue();
+*         if (secondRead.success && secondRead.data !== undefined) {
+*             expect(secondRead.data.environment).toBe("production");
+*             expect(secondRead.data.resources).toBeEmpty();
+*         }
+*     });
 * ```
 */
-interface GamePassDriverDeps {
-  /** Configured game-passes client from `@bedrock-rbx/ocale/game-passes`. */
-  readonly client: GamePassesClient;
-  /** Reads icon bytes for upload; rejections propagate out of `create`. */
-  readonly readFile: (path: string) => Promise<Uint8Array>;
-  /** Universe that owns every game pass this driver creates. */
-  readonly universeId: RobloxAssetId;
+interface StatePort {
+  /**
+  * Reads state for the given environment.
+  *
+  * - Returns `Ok(undefined)` when no state file exists (legitimate first deploy).
+  * - Returns `Err(StateError)` when a file exists but cannot be parsed
+  *   (corrupt JSON, schema failure, unknown `$bedrock.version`).
+  *
+  * Never silently falls back to empty state: a malformed file that collapsed
+  * to `{ resources: [] }` would cause the next apply to re-create every
+  * resource on Roblox.
+  */
+  read(environment: string): Promise<Result$1<BedrockState | undefined, StateError>>;
+  /** Writes state for the given environment, overwriting any existing file. */
+  write(state: BedrockState): Promise<Result$1<void, StateError>>;
 }
+//#endregion
+//#region src/adapters/gist-state-adapter.d.ts
 /**
-* Wraps {@link GamePassesClient} as a `ResourceDriver<"gamePass">` that maps
-* a desired-state entry to an ocale create call and the response back to a
-* `ResourceCurrentState<"gamePass">`.
-*
-* Upstream `OpenCloudError` results pass through as `Result` failures.
-* Filesystem errors from `deps.readFile` do not fit the `OpenCloudError`
-* shape and propagate as promise rejections; shell callers are expected to
-* translate them if a unified error surface is required.
+* Minimal `fetch`-compatible signature the adapter needs, narrower than
+* `typeof globalThis.fetch` so test fakes do not have to stub runtime
+* extensions such as `fetch.preconnect`.
+*/
+type GistFetch = (input: globalThis.Request | string | URL, init?: RequestInit) => Promise<Response>;
+/**
+* Configuration for {@link createGistStateAdapter}.
+*/
+interface GistStateAdapterDeps {
+  /** Injection seam for tests; defaults to `globalThis.fetch`. */
+  readonly fetch?: GistFetch | undefined;
+  /** ID of an existing GitHub Gist that holds this project's state files. */
+  readonly gistId: string;
+  /**
+  * Injection seam for retry backoff timing; defaults to a `setTimeout`-based
+  * promise. Tests pass a fake to keep retry assertions deterministic.
+  */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+  /** GitHub token (fine-grained PAT or classic PAT) with gist read/write scope. */
+  readonly token: string;
+}
+/**
+* Build a `StatePort` that persists Bedrock state in a GitHub Gist.
 *
-* @param deps - Injected ocale client, file reader, and owning universe.
-* @returns A driver indexable by `"gamePass"` in a `DriverRegistry`.
-* @throws Whatever `deps.readFile` rejects with.
+* One gist holds one file per environment, named `state.<env>.json`. The
+* adapter authenticates with a user-supplied token and speaks the GitHub
+* REST API directly; no SDK dependency.
 *
 * @example
 *
 * ```ts
-* import type { HttpClient } from "@bedrock-rbx/ocale";
-* import { GamePassesClient } from "@bedrock-rbx/ocale/game-passes";
-* import {
-*     asResourceKey,
-*     asRobloxAssetId,
-*     asSha256Hex,
-*     createGamePassDriver,
-* } from "@bedrock-rbx/core";
-*
-* const httpClient: HttpClient = {
-*     async request() {
-*         return {
-*             data: {
-*                 body: {
-*                     createdTimestamp: "2024-01-15T10:30:00.000Z",
-*                     description: "Grants VIP perks.",
-*                     gamePassId: 9_876_543_210,
-*                     iconAssetId: 1_122_334_455,
-*                     isForSale: true,
-*                     name: "VIP Pass",
-*                     updatedTimestamp: "2024-01-15T10:30:00.000Z",
-*                 },
-*                 headers: {},
-*                 status: 200,
-*             },
-*             success: true,
-*         };
-*     },
-* };
+* import { createGistStateAdapter } from "@bedrock-rbx/core";
 *
-* const driver = createGamePassDriver({
-*     client: new GamePassesClient({
-*         apiKey: "rbx-your-key",
-*         httpClient,
-*         sleep: async () => {},
-*     }),
-*     readFile: async () => new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
-*     universeId: asRobloxAssetId("1234567890"),
+* const port = createGistStateAdapter({
+*     fetch: async () =>
+*         new Response(JSON.stringify({ files: {} }), { status: 200 }),
+*     gistId: "abc123def456",
+*     token: "ghp_example",
 * });
 *
-* return driver
-*     .create({
-*         description: "Grants VIP perks.",
-*         icon: { "en-us": "assets/vip-icon.png" },
-*         iconFileHashes: {
-*             "en-us": asSha256Hex(
-*                 "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-*             ),
-*         },
-*         key: asResourceKey("vip-pass"),
-*         kind: "gamePass",
-*         name: "VIP Pass",
-*         price: 500,
-*     })
-*     .then((result) => {
-*         expect(result.success).toBeTrue();
-*         if (result.success) {
-*             expect(result.data.outputs.assetId).toBe("9876543210");
-*         }
-*     });
+* return port.read("production").then((result) => {
+*     expect(result.success).toBeTrue();
+*     if (result.success) {
+*         expect(result.data).toBeUndefined();
+*     }
+* });
 * ```
+*
+* @param deps - Gist ID, GitHub token, and optional fetch override.
+* @returns A `StatePort` ready to be passed to `deploy()`.
 */
-declare function createGamePassDriver(deps: GamePassDriverDeps): ResourceDriver<"gamePass">;
+declare function createGistStateAdapter(deps: GistStateAdapterDeps): StatePort;
 //#endregion
-//#region src/core/state.d.ts
+//#region src/shell/build-state-port.d.ts
 /**
-* In-memory state snapshot for one environment.
-*
-* The on-disk JSON wraps this shape with a `$bedrock: { version: N }` envelope.
-* Adapters flatten the envelope on read and re-wrap it on write; nothing
-* outside an adapter sees the `$bedrock` key.
-*
-* `version` is a literal so a breaking schema change is a compile-time type
-* shift rather than a silently accepted runtime value.
+* Failure surfaced when a default-constructed adapter cannot find a
+* required environment variable. The deploy boundary wraps this in a
+* `DeployError` so the caller sees a typed Result instead of an
+* exception or a confusing downstream HTTP error.
+*/
+interface MissingCredentialError {
+  /** Literal discriminator for narrowing. */
+  readonly kind: "missingCredential";
+  /** Whether the credential was needed for the state backend or the driver registry. */
+  readonly purpose: "registry" | "stateBackend";
+  /** Environment variable name the default-construction path tried to read. */
+  readonly variable: string;
+}
+/**
+* Failure surfaced when the dispatch helper sees a `state.backend` value
+* it does not recognize. The hint points at `opts.statePort` so the
+* caller can pass a custom adapter as an escape hatch.
+*/
+interface UnsupportedBackendError {
+  /** Backend name read from `state.backend`. */
+  readonly backend: string;
+  /** Suggested escape hatch routed back to the caller. */
+  readonly hint: string;
+  /** Literal discriminator for narrowing. */
+  readonly kind: "unsupportedBackend";
+}
+/** Inputs for {@link buildStatePort}. */
+interface BuildStatePortDeps {
+  /** Optional `fetch` seam plumbed through to the gist adapter for tests. */
+  readonly fetch?: GistFetch | undefined;
+  /** Reads an environment variable; injected so tests stay free of `process.env`. */
+  readonly getEnv: (name: string) => string | undefined;
+  /** Resolved state configuration for the target environment. */
+  readonly stateConfig: StateConfig;
+}
+/**
+* Construct a `StatePort` from a resolved `StateConfig`. Dispatches on
+* `stateConfig.backend` to the matching builtin adapter; reads the
+* required credential from `getEnv` and surfaces `missingCredential` or
+* `unsupportedBackend` as typed Results.
 *
 * @example
 *
 * ```ts
-* import {
-*     asResourceKey,
-*     asRobloxAssetId,
-*     asSha256Hex,
-*     type BedrockState,
-* } from "@bedrock-rbx/core";
+* import { buildStatePort } from "@bedrock-rbx/core";
 *
-* const state: BedrockState = {
-*     environment: "production",
-*     resources: [
-*         {
-*             description: "Grants VIP perks.",
-*             icon: { "en-us": "assets/vip-icon.png" },
-*             iconFileHashes: {
-*                 "en-us": asSha256Hex(
-*                     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-*                 ),
-*             },
-*             key: asResourceKey("vip-pass"),
-*             kind: "gamePass",
-*             name: "VIP Pass",
-*             outputs: {
-*                 assetId: asRobloxAssetId("9876543210"),
-*                 iconAssetIds: { "en-us": asRobloxAssetId("1122334455") },
-*             },
-*             price: 500,
-*         },
-*     ],
-*     version: 1,
-* };
+* const port = buildStatePort({
+*     fetch: async () =>
+*         new Response(JSON.stringify({ files: {} }), { status: 200 }),
+*     getEnv: (name) => (name === "GITHUB_TOKEN" ? "ghp_example" : undefined),
+*     stateConfig: { backend: "gist", gistId: "abc123" },
+* });
 *
-* expect(state.version).toBe(1);
-* expect(state.resources).toHaveLength(1);
+* expect(port.success).toBeTrue();
 * ```
+*
+* @param deps - Resolved state config plus credential-injection seams.
+* @returns A `StatePort` on success, or a typed Err describing the
+* missing credential or the unsupported backend.
 */
-interface BedrockState {
-  /** Environment name this snapshot belongs to (e.g. `"production"`, `"staging"`). */
+declare function buildStatePort(deps: BuildStatePortDeps): Result$1<StatePort, MissingCredentialError | UnsupportedBackendError>;
+//#endregion
+//#region src/core/resolve-state-config.d.ts
+/**
+* Failure surfaced when no `StateConfig` is configured for the requested
+* environment. The shell layer wraps this in a `DeployError` when default
+* state-port construction is requested but the project has not declared
+* where state should live.
+*/
+interface StateNotConfiguredError {
+  /** Environment that the resolver was called against. */
   readonly environment: string;
-  /** Current state of every resource Bedrock manages in this environment. */
-  readonly resources: ReadonlyArray<ResourceCurrentState>;
-  /** Schema-version literal; bumped only for breaking changes to the on-disk format. */
-  readonly version: 1;
+  /** Literal discriminator for narrowing. */
+  readonly kind: "stateNotConfigured";
 }
 /**
-* Failure surfaced by a `StatePort` when a state file exists but cannot be
-* trusted: corrupt JSON, schema failure, or an unknown `$bedrock.version`.
-*
-* Narrow on `kind` rather than using `instanceof`: `StateError` is plain data,
-* not a thrown error subclass.
+* Minimal structural input the state resolver needs. Both `Config`
+* (pre-merge, discriminated XOR union) and `ResolvedConfig` (post-merge)
+* satisfy this shape, so callers can route either in without coupling
+* the resolver to the discriminated-union arms.
+*/
+interface StateResolutionInputs {
+  readonly environments: Record<string, undefined | {
+    readonly state?: StateConfig;
+  }>;
+  readonly state?: StateConfig;
+}
+/**
+* Pick the `StateConfig` that applies to `environment`. Per-environment
+* overrides win over the root block; if neither is present, returns
+* `Err(stateNotConfigured)` so the deploy boundary can surface a typed
+* error instead of silently falling back.
 *
+* @param config - Validated project config.
+* @param environment - Target environment name.
+* @returns The resolved `StateConfig`, or `Err(stateNotConfigured)` when
+* neither the environment override nor the root block is set.
 * @example
 *
 * ```ts
-* import type { StateError } from "@bedrock-rbx/core";
+* import { resolveStateConfig } from "@bedrock-rbx/core";
 *
-* const err: StateError = {
-*     file: ".bedrock/state/production.json",
-*     kind: "stateError",
-*     reason: "Corrupt JSON: unexpected token at line 1 column 5",
-* };
+* const result = resolveStateConfig(
+*     {
+*         state: { backend: "gist", gistId: "root-gist" },
+*         environments: {
+*             production: { state: { backend: "gist", gistId: "prod-gist" } },
+*         },
+*     },
+*     "production",
+* );
 *
-* expect(err.kind).toBe("stateError");
+* expect(result.success).toBeTrue();
+* if (result.success) {
+*     expect(result.data).toContainEntry(["gistId", "prod-gist"]);
+* }
 * ```
 */
-interface StateError {
-  /** Adapter-specific path or identifier of the file that failed to parse. */
-  readonly file: string;
+declare function resolveStateConfig(config: StateResolutionInputs, environment: string): Result$1<StateConfig, StateNotConfiguredError>;
+//#endregion
+//#region src/core/select-environment.d.ts
+/**
+* Failure surfaced when `selectEnvironment` is asked for an environment
+* name that is not a key of `config.environments`. Carries the list of
+* declared names so callers can render a "did you mean?" hint or a
+* close-match suggestion.
+*/
+interface UnknownEnvironmentError {
+  /** Environment names that the config actually declared. */
+  readonly declared: ReadonlyArray<string>;
+  /** Environment name the caller asked for. */
+  readonly environment: string;
   /** Literal discriminator for narrowing. */
-  readonly kind: "stateError";
-  /** Human-readable explanation of why the file could not be trusted. */
-  readonly reason: string;
+  readonly kind: "unknownEnvironment";
 }
-//#endregion
-//#region src/ports/state-port.d.ts
 /**
-* Plugin contract for persisting deployment state: the interface an adapter
-* (Gist, local filesystem, cloud object store) implements to let Bedrock load
-* and save its per-environment {@link BedrockState} snapshot.
-*
-* `StatePort` is a *driven* (secondary) port in hexagonal terms, following the
-* same naming convention as {@link "./resource-driver".ResourceDriver}.
-*
-* @example
-*
-* ```ts
-* import type { BedrockState, StatePort } from "@bedrock-rbx/core";
-*
-* const store = new Map<string, BedrockState>();
-*
-* const statePort: StatePort = {
-*     async read(environment) {
-*         return { data: store.get(environment), success: true };
-*     },
-*     async write(state) {
-*         store.set(state.environment, state);
-*         return { data: undefined, success: true };
-*     },
-* };
-*
-* return statePort
-*     .read("production")
-*     .then((firstRead) => {
-*         expect(firstRead.success).toBeTrue();
-*         if (firstRead.success) {
-*             expect(firstRead.data).toBeUndefined();
-*         }
-*         return statePort.write({
-*             environment: "production",
-*             resources: [],
-*             version: 1,
-*         });
-*     })
-*     .then((writeResult) => {
-*         expect(writeResult.success).toBeTrue();
-*         return statePort.read("production");
-*     })
-*     .then((secondRead) => {
-*         expect(secondRead.success).toBeTrue();
-*         if (secondRead.success && secondRead.data !== undefined) {
-*             expect(secondRead.data.environment).toBe("production");
-*             expect(secondRead.data.resources).toBeEmpty();
-*         }
-*     });
-* ```
+* Failure surfaced when a merged place entry is missing a required field.
+* Two paths reach this error: a root place declared without a matching
+* per-environment overlay supplying `placeId`, and an overlay-only place
+* declared under `environments.X.places` with no matching root entry to
+* supply `filePath`. Surfacing both at the resolution boundary attributes
+* the missing field to the offending entry's key instead of letting
+* `buildDesired` crash with a generic `fileReadFailed` later on.
 */
-interface StatePort {
-  /**
-  * Reads state for the given environment.
-  *
-  * - Returns `Ok(undefined)` when no state file exists (legitimate first deploy).
-  * - Returns `Err(StateError)` when a file exists but cannot be parsed
-  *   (corrupt JSON, schema failure, unknown `$bedrock.version`).
-  *
-  * Never silently falls back to empty state: a malformed file that collapsed
-  * to `{ resources: [] }` would cause the next apply to re-create every
-  * resource on Roblox.
-  */
-  read(environment: string): Promise<Result$1<BedrockState | undefined, StateError>>;
-  /** Writes state for the given environment, overwriting any existing file. */
-  write(state: BedrockState): Promise<Result$1<void, StateError>>;
+interface IncompletePlaceEntryError {
+  /** ResourceKey of the place entry that is missing a required field. */
+  readonly key: string;
+  /** Environment whose overlay was projected onto the config. */
+  readonly environment: string;
+  /** Literal discriminator for narrowing. */
+  readonly kind: "incompletePlaceEntry";
+  /** Field that the merged entry lacks. */
+  readonly missingField: "filePath" | "placeId";
 }
-//#endregion
-//#region src/adapters/gist-state-adapter.d.ts
-/**
-* Minimal `fetch`-compatible signature the adapter needs, narrower than
-* `typeof globalThis.fetch` so test fakes do not have to stub runtime
-* extensions such as `fetch.preconnect`.
-*/
-type GistFetch = (input: globalThis.Request | string | URL, init?: RequestInit) => Promise<Response>;
 /**
-* Configuration for {@link createGistStateAdapter}.
+* Failure surfaced when a merged `universe` block lacks `universeId`.
+* The schema-level XOR rule normally prevents this by requiring
+* `universeId` either at the root or on every per-environment overlay;
+* this error remains as a typed safety net for callers that bypass
+* `validateConfig` and hand a `Config` to `selectEnvironment` directly.
 */
-interface GistStateAdapterDeps {
-  /** Injection seam for tests; defaults to `globalThis.fetch`. */
-  readonly fetch?: GistFetch | undefined;
-  /** ID of an existing GitHub Gist that holds this project's state files. */
-  readonly gistId: string;
-  /**
-  * Injection seam for retry backoff timing; defaults to a `setTimeout`-based
-  * promise. Tests pass a fake to keep retry assertions deterministic.
-  */
-  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
-  /** GitHub token (fine-grained PAT or classic PAT) with gist read/write scope. */
-  readonly token: string;
+interface IncompleteUniverseEntryError {
+  /** Environment whose overlay was projected onto the config. */
+  readonly environment: string;
+  /** Literal discriminator for narrowing. */
+  readonly kind: "incompleteUniverseEntry";
+  /** Field that the merged entry lacks. V1 only surfaces `"universeId"`. */
+  readonly missingField: "universeId";
 }
+/** Failure modes returned by {@link selectEnvironment}. */
+type SelectEnvironmentError = IncompletePlaceEntryError | IncompleteUniverseEntryError | UnknownEnvironmentError;
 /**
-* Build a `StatePort` that persists Bedrock state in a GitHub Gist.
-*
-* One gist holds one file per environment, named `state.<env>.json`. The
-* adapter authenticates with a user-supplied token and speaks the GitHub
-* REST API directly; no SDK dependency.
+* Project a validated `Config` onto a single environment. Looks up the
+* matching `environments[environment]` entry, deep-merges its resource
+* overlay (`passes`, `places`, `universe`) over the root config via defu,
+* and applies the env-level state override when present (the env entry's
+* `state` field wins; otherwise the root `state` flows through).
 *
-* @example
+* Pure: no I/O. Returns a `ResolvedConfig` ready to feed into downstream
+* functions (`flattenConfig`, `buildDefaultRegistry`, `resolveStateConfig`).
+* The post-merge view promotes `places` from `Record<string, PlaceEntry>`
+* (root: file-paths only) to `Record<string, ResolvedPlaceEntry>` (root +
+* overlay merged). `environments` and `extends` are passed through
+* unchanged because they preserve the shape relationship to `Config`;
+* downstream consumers do not read them post-merge.
 *
-* ```ts
-* import { createGistStateAdapter } from "@bedrock-rbx/core";
+* Defu's merge semantics are deliberate: keyed-map collections merge by
+* key (so a place declared in both root and overlay produces a single
+* entry whose overlay-supplied fields win), and `null` / `undefined` in
+* the overlay are skipped (so the overlay never deletes a root field).
+* State has its own resolution path (a single replacement, not a
+* deep-merge) because it is a tagged union: a deep-merge of
+* `{ backend: "s3" }` over `{ backend: "gist", gistId }` would produce
+* a malformed `{ backend: "s3", gistId }`.
 *
-* const port = createGistStateAdapter({
-*     fetch: async () =>
-*         new Response(JSON.stringify({ files: {} }), { status: 200 }),
-*     gistId: "abc123def456",
-*     token: "ghp_example",
-* });
+* State is left absent when neither the env override nor the root block
+* provides one. Callers that require a resolved `StateConfig` should
+* route through `resolveStateConfig` or `buildStatePort`; the absent
+* case surfaces as a typed `stateNotConfigured` there.
 *
-* return port.read("production").then((result) => {
-*     expect(result.success).toBeTrue();
-*     if (result.success) {
-*         expect(result.data).toBeUndefined();
-*     }
-* });
-* ```
+* Limitation in v1: a per-environment universe overlay that introduces a
+* brand-new universe block may still have optional fields missing, since
+* the overlay type only requires the identity-bearing key. The resolver
+* surfaces the entry as-is; the universe driver reports the missing
+* field when it tries to consume the entry. Universe is a singleton with
+* 20+ optional fields, so the same `incompletePlaceEntry`-style validation
+* is deferred to a separate follow-up.
 *
-* @param deps - Gist ID, GitHub token, and optional fetch override.
-* @returns A `StatePort` ready to be passed to `deploy()`.
-*/
-declare function createGistStateAdapter(deps: GistStateAdapterDeps): StatePort;
-//#endregion
-//#region src/adapters/place-driver.d.ts
-/**
-* Dependencies of `createPlaceDriver`. `universeId` is captured at
-* construction time (matching `GamePassDriverDeps`) so each driver instance
-* is bound to a single universe; multi-universe deploys construct one driver
-* per universe. `readFile` is injected because `diff` operates on file hashes
-* while the driver is the only place that needs the raw bytes.
+* When the project sets a `displayNamePrefix` (or omits it, in which case
+* prefixing defaults to enabled) and the chosen environment declares a
+* non-empty `label`, the resolver renders the configured template via
+* `renderDisplayNamePrefix` and prepends the result to `universe.displayName`
+* and every declared place `displayName`. An undeclared `displayName`, an
+* empty/absent label, or an explicit `displayNamePrefix.enabled: false` all
+* skip prefixing for the affected fields.
 *
 * @example
 *
 * ```ts
-* import type { HttpClient } from "@bedrock-rbx/ocale";
-* import { PlacesClient } from "@bedrock-rbx/ocale/places";
-* import { asRobloxAssetId, type PlaceDriverDeps } from "@bedrock-rbx/core";
+* import { selectEnvironment } from "@bedrock-rbx/core";
+* import type { Config } from "@bedrock-rbx/core/config";
 *
-* const httpClient: HttpClient = {
-*     async request() {
-*         return { data: { body: {}, headers: {}, status: 200 }, success: true };
+* const config: Config = {
+*     environments: {
+*         production: { universe: { universeId: "999" } },
 *     },
+*     state: { backend: "gist", gistId: "abc123" },
+*     universe: { voiceChatEnabled: true },
 * };
 *
-* const deps: PlaceDriverDeps = {
-*     client: new PlacesClient({
-*         apiKey: "rbx-your-key",
-*         httpClient,
-*         sleep: async () => {},
-*     }),
-*     readFile: async () => new Uint8Array(),
-*     universeId: asRobloxAssetId("1234567890"),
-* };
+* const result = selectEnvironment(config, "production");
 *
-* expect(deps.universeId).toBe("1234567890");
+* expect(result.success).toBeTrue();
+* if (result.success) {
+*     expect(result.data.universe?.universeId).toBe("999");
+*     expect(result.data.universe?.voiceChatEnabled).toBeTrue();
+*     expect(result.data.state?.backend).toBe("gist");
+* }
 * ```
+*
+* @param config - Validated project config carrying at least one
+* environment under `environments`.
+* @param environment - Environment name to project onto. Must be a key
+* of `config.environments`.
+* @returns `Ok(ResolvedConfig)` with the merged resource fields and the
+* resolved state, or `Err(SelectEnvironmentError)` describing why the
+* projection failed.
 */
-interface PlaceDriverDeps {
-  /** Configured places client from `@bedrock-rbx/ocale/places`. */
-  readonly client: PlacesClient;
-  /** Reads place-file bytes for upload; rejections propagate out of the driver. */
-  readonly readFile: (path: string) => Promise<Uint8Array>;
-  /** Universe that owns every place this driver publishes. */
-  readonly universeId: RobloxAssetId;
-}
+declare function selectEnvironment(config: Config, environment: string): Result$1<ResolvedConfig, SelectEnvironmentError>;
+//#endregion
+//#region src/ports/resource-driver.d.ts
 /**
-* Wraps {@link PlacesClient} as a `ResourceDriver<"place">`. `create` and
-* `update` are both thin wrappers over a shared publish helper because the
-* upstream Open Cloud call is identical either way: there is no "create
-* place" endpoint (the place is user-supplied input), only "publish version".
+* Plugin contract for a resource adapter: the interface a third-party author
+* implements to teach Bedrock how to reconcile one {@link ResourceKind} against
+* its upstream API.
 *
-* Format is detected from the file extension (`.rbxl` → binary,
-* `.rbxlx` → XML); any other extension returns an `ApiError`-backed failure
-* without hitting the network.
+* `ResourceDriver<K>` is a *driven* (secondary) port in hexagonal terms; the
+* name "driver" follows Terraform, Pulumi, and Mantle IaC convention for a
+* component that talks to a specific resource API.
 *
-* @param deps - Injected ocale client, file reader, and owning universe.
-* @returns A driver indexable by `"place"` in a `DriverRegistry`.
-* @throws Whatever `deps.readFile` rejects with.
+* @template K - The {@link ResourceKind} discriminator this driver handles.
 *
 * @example
 *
 * ```ts
-* import type { HttpClient } from "@bedrock-rbx/ocale";
-* import { PlacesClient } from "@bedrock-rbx/ocale/places";
 * import {
 *     asResourceKey,
 *     asRobloxAssetId,
 *     asSha256Hex,
-*     createPlaceDriver,
+*     type ResourceDriver,
 * } from "@bedrock-rbx/core";
 *
-* const httpClient: HttpClient = {
-*     async request() {
-*         return {
-*             data: { body: { versionNumber: 1 }, headers: {}, status: 200 },
-*             success: true,
-*         };
-*     },
-* };
-*
-* const driver = createPlaceDriver({
-*     client: new PlacesClient({
-*         apiKey: "rbx-your-key",
-*         httpClient,
-*         sleep: async () => {},
-*     }),
-*     readFile: async () =>
-*         new Uint8Array([
-*             0x3c, 0x72, 0x6f, 0x62, 0x6c, 0x6f, 0x78, 0x21, 0x89, 0xff, 0x0d, 0x0a, 0x1a,
-*             0x0a,
-*         ]),
-*     universeId: asRobloxAssetId("1234567890"),
-* });
-*
-* return driver
-*     .create({
-*         description: undefined,
-*         displayName: undefined,
-*         fileHash: asSha256Hex(
-*             "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-*         ),
-*         filePath: "places/start.rbxl",
-*         key: asResourceKey("start-place"),
-*         kind: "place",
-*         placeId: asRobloxAssetId("4711"),
-*         serverSize: undefined,
-*     })
-*     .then((result) => {
-*         expect(result.success).toBeTrue();
-*         if (result.success) {
-*             expect(result.data.outputs.versionNumber).toBe(1);
-*         }
-*     });
-* ```
-*/
-declare function createPlaceDriver(deps: PlaceDriverDeps): ResourceDriver<"place">;
-//#endregion
-//#region src/adapters/universe-driver.d.ts
-/**
-* Dependencies of `createUniverseDriver`. The driver reconciles the
-* universe singleton against both the universes endpoint and the root
-* place (for fields Roblox marks read-only on the universe, like
-* `displayName`). There is no `universeId` at construction time because
-* the universe *is* the resource the driver reconciles, so the ID rides
-* along on each `UniverseDesiredState`.
-*/
-interface UniverseDriverDeps {
-  /** Configured places client from `@bedrock-rbx/ocale/places`. */
-  readonly places: PlacesClient;
-  /** Configured universes client from `@bedrock-rbx/ocale/universes`. */
-  readonly universes: UniversesClient;
-}
-/**
-* Wraps {@link UniversesClient} as a `ResourceDriver<"universe">`. `create`
-* and `update` both delegate to a shared reconcile helper because Open
-* Cloud cannot mint universes; the user supplies an existing `universeId`
-* and bedrock adopts the universe on first apply.
-*
-* A `NotFound` error (HTTP 404) from `UniversesClient.update` is repackaged
-* as an adoption-error `ApiError` whose message names the config key and
-* the `universeId`, so operators can tell adoption failure apart from
-* transient upstream errors. A successful response whose `rootPlaceId` is
-* absent surfaces as an `ApiError` with status 200, mirroring the
-* malformed-response guard in `GamePassDriver`.
-*
-* When `displayName` is declared, the driver routes that field through
-* `PlacesClient.update` on the root place after the universe PATCH
-* succeeds. A subsequent places failure surfaces to the caller as the
-* driver's error result without rolling back the prior universe patch,
-* so callers observing a partial failure should reconcile by
-* reapplying rather than assuming the universe-level fields are
-* unchanged.
-*
-* @param deps - Injected ocale clients (universes plus places for the
-*   read-only universe fields Roblox derives from the root place).
-* @returns A driver indexable by `"universe"` in a `DriverRegistry`.
-*
-* @example
-*
-* ```ts
-* import type { HttpClient } from "@bedrock-rbx/ocale";
-* import { PlacesClient } from "@bedrock-rbx/ocale/places";
-* import { UniversesClient } from "@bedrock-rbx/ocale/universes";
-* import { validUniverseBody } from "@bedrock-rbx/ocale/testing";
-* import {
-*     asRobloxAssetId,
-*     createUniverseDriver,
-*     UNIVERSE_SINGLETON_KEY,
-* } from "@bedrock-rbx/core";
-*
-* const universeBodyHttpClient: HttpClient = {
-*     async request() {
+* const gamePassDriver: ResourceDriver<"gamePass"> = {
+*     async create(desired) {
 *         return {
 *             data: {
-*                 body: validUniverseBody({
-*                     path: "universes/1234567890",
-*                     rootPlace: "universes/1234567890/places/4711",
-*                 }),
-*                 headers: {},
-*                 status: 200,
+*                 ...desired,
+*                 outputs: {
+*                     assetId: asRobloxAssetId("9876543210"),
+*                     iconAssetIds: { "en-us": asRobloxAssetId("1122334455") },
+*                 },
 *             },
 *             success: true,
 *         };
 *     },
 * };
 *
-* const driver = createUniverseDriver({
-*     places: new PlacesClient({
-*         apiKey: "rbx-your-key",
-*         httpClient: universeBodyHttpClient,
-*         sleep: async () => {},
-*     }),
-*     universes: new UniversesClient({
-*         apiKey: "rbx-your-key",
-*         httpClient: universeBodyHttpClient,
-*         sleep: async () => {},
-*     }),
-* });
-*
-* return driver
+* return gamePassDriver
 *     .create({
-*         consoleEnabled: undefined,
-*         desktopEnabled: true,
-*         displayName: undefined,
-*         key: UNIVERSE_SINGLETON_KEY,
-*         kind: "universe",
-*         mobileEnabled: undefined,
-*         privateServerPriceRobux: undefined,
-*         tabletEnabled: undefined,
-*         universeId: asRobloxAssetId("1234567890"),
-*         voiceChatEnabled: true,
-*         vrEnabled: undefined,
+*         description: "Grants VIP perks.",
+*         icon: { "en-us": "assets/vip-icon.png" },
+*         iconFileHashes: {
+*             "en-us": asSha256Hex(
+*                 "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+*             ),
+*         },
+*         key: asResourceKey("vip-pass"),
+*         kind: "gamePass",
+*         name: "VIP Pass",
+*         price: undefined,
 *     })
 *     .then((result) => {
 *         expect(result.success).toBeTrue();
 *         if (result.success) {
-*             expect(result.data.outputs.rootPlaceId).toBe("4711");
+*             expect(result.data.outputs.assetId).toBe("9876543210");
 *         }
 *     });
 * ```
 */
-declare function createUniverseDriver(deps: UniverseDriverDeps): ResourceDriver<"universe">;
-//#endregion
-//#region src/core/derive-price-fields.d.ts
-/**
-* Wire-shape pricing fragment produced by {@link derivePriceFields}: the
-* `isForSale` flag and an optional numeric `price`. Mirrors the multipart
-* fields the Open Cloud `developer-products` create and update endpoints
-* accept for setting Robux pricing.
-*/
-interface PriceFields {
-  /** Whether the developer product should be purchasable. */
-  readonly isForSale: boolean;
-  /** Default price in Robux; absent when the product is off-sale. */
-  readonly price?: number;
+interface ResourceDriver<K extends ResourceKind> {
+  /**
+  * Create the resource upstream from its desired state and return the
+  * resulting current state (desired fields + Roblox-assigned outputs).
+  */
+  create(desired: Extract<ResourceDesiredState, {
+    kind: K;
+  }>): Promise<Result$1<ResourceCurrentState<K>, OpenCloudError$1>>;
+  /**
+  * Reconcile an upstream resource whose managed content has drifted from its
+  * desired state. Receives the last-known current state so the driver can
+  * compute a minimal patch (or no-op upstream, for file-backed kinds where
+  * republishing is unconditional).
+  *
+  * Optional. Drivers whose upstream API has no update operation omit this
+  * method; `applyOps` surfaces an `updateUnsupported` error at dispatch time
+  * instead.
+  */
+  update?(current: ResourceCurrentState<K>, desired: Extract<ResourceDesiredState, {
+    kind: K;
+  }>): Promise<Result$1<ResourceCurrentState<K>, OpenCloudError$1>>;
 }
 /**
-* Translate a Mantle-style optional price into the Open Cloud wire shape.
-*
-* `desired.price === undefined` (no price declared) becomes
-* `{ isForSale: false }` and the `price` key is omitted entirely. A defined
-* price (including `0`) becomes `{ isForSale: true, price }`. Both
-* `developerProduct` create and update paths share this helper so the
-* "absent ⇒ off-sale" semantics live in exactly one place.
-*
-* @param desired - Object carrying the user-declared `price`.
-* @returns The wire-shape `{ isForSale, price? }` fragment.
+* Polymorphic dispatch table keyed by {@link ResourceKind}, mapping each kind
+* to the {@link ResourceDriver} that handles it. `applyOps` indexes the
+* registry by `op.desired.kind` to reach the matching driver with full type
+* safety: adding a new kind to `ResourceDesiredState` is a compile error until
+* a matching registry entry is supplied.
 *
 * @example
 *
 * ```ts
-* import { derivePriceFields } from "@bedrock-rbx/core";
+* import { OpenCloudError, type DriverRegistry } from "@bedrock-rbx/core";
 *
-* expect(derivePriceFields({ price: undefined })).toStrictEqual({ isForSale: false });
-* expect(derivePriceFields({ price: 250 })).toStrictEqual({ isForSale: true, price: 250 });
+* const registry: DriverRegistry = {
+*     gamePass: {
+*         async create() {
+*             return { err: new OpenCloudError("not implemented"), success: false };
+*         },
+*     },
+*     place: {
+*         async create() {
+*             return { err: new OpenCloudError("not implemented"), success: false };
+*         },
+*     },
+*     universe: {
+*         async create() {
+*             return { err: new OpenCloudError("not implemented"), success: false };
+*         },
+*     },
+*     developerProduct: {
+*         async create() {
+*             return { err: new OpenCloudError("not implemented"), success: false };
+*         },
+*     },
+* };
+*
+* expect(registry.gamePass).toBeObject();
 * ```
 */
-declare function derivePriceFields(desired: {
-  readonly price: number | undefined;
-}): PriceFields;
+type DriverRegistry = { [K in ResourceKind]: ResourceDriver<K> };
 //#endregion
 //#region src/core/operations.d.ts
 /**
@@ -1738,162 +1625,228 @@ interface NoopOperation extends BaseOperation {
 */
 type Operation = CreateOperation | NoopOperation | UpdateOperation;
 //#endregion
-//#region src/core/diff.d.ts
+//#region src/shell/apply-ops.d.ts
 /**
-* Computes the operations required to reconcile `current` state with `desired`
-* state. Pure and synchronous: no I/O, no side effects, no `Result` wrapper.
-*
-* Each entry in `desired` is matched to `current` by `(kind, key)`: resources
-* are uniquely identified by that pair, so a `place` and a `universe` keyed
-* `"main"` are independent slots. A `(kind, key)` pair present only in
-* `desired` produces a `create` op; a pair present in both produces an
-* `update` op if any declared field differs or a `noop` op if every field
-* matches.
-*
-* Ops appear in the order their desired entries appear in the input array so
-* callers can rely on declaration order when logging or applying ops.
+* Failure surfaced by `applyOps` when an operation cannot be applied.
+* Plain-data discriminated union; narrow on `kind`, do not `instanceof` it.
 *
-* @param desired - Declared desired state from user config, already normalized
-*   (file hashes computed, nullable wire values mapped to `undefined`).
-* @param current - Last-known live state from the state file.
-* @returns Operations to reconcile the two snapshots.
+* `appliedSoFar` carries the driver outputs from operations that succeeded
+* before the failing one, in dispatched order. Callers persist this so a
+* follow-up reconcile does not duplicate Roblox-side resources that have
+* already been created or updated.
 *
 * @example
 *
 * ```ts
-* import {
-*     asResourceKey,
-*     asRobloxAssetId,
-*     asSha256Hex,
-*     diff,
-*     type GamePassDesiredState,
-*     type ResourceCurrentState,
-* } from "@bedrock-rbx/core";
+* import { asResourceKey, type ApplyError } from "@bedrock-rbx/core";
 *
-* const hash = asSha256Hex(
-*     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-* );
+* function describe(err: ApplyError): string {
+*     switch (err.kind) {
+*         case "driverFailure": {
+*             return `driver failed for ${err.key}: ${err.cause.message}`;
+*         }
+*         case "updateUnsupported": {
+*             return `update not supported for ${err.key}`;
+*         }
+*     }
+* }
 *
-* const unchanged: GamePassDesiredState = {
-*     description: "Grants VIP perks.",
-*     icon: { "en-us": "assets/vip-icon.png" },
-*     iconFileHashes: { "en-us": hash },
+* const err: ApplyError = {
 *     key: asResourceKey("vip-pass"),
-*     kind: "gamePass",
-*     name: "VIP Pass",
-*     price: 500,
-* };
-* const drifted: GamePassDesiredState = {
-*     ...unchanged,
-*     key: asResourceKey("legend-pass"),
-*     name: "Legend Pass (renamed)",
-* };
-* const fresh: GamePassDesiredState = {
-*     ...unchanged,
-*     key: asResourceKey("rookie-pass"),
-*     name: "Rookie Pass",
+*     appliedSoFar: [],
+*     kind: "updateUnsupported",
 * };
 *
-* const current: ReadonlyArray<ResourceCurrentState> = [
-*     {
-*         ...unchanged,
-*         outputs: {
-*             assetId: asRobloxAssetId("111"),
-*             iconAssetIds: { "en-us": asRobloxAssetId("222") },
+* expect(describe(err)).toBe("update not supported for vip-pass");
+* ```
+*/
+type ApplyError = {
+  readonly appliedSoFar: ReadonlyArray<ResourceCurrentState>;
+  readonly cause: OpenCloudError$1;
+  readonly key: ResourceKey;
+  readonly kind: "driverFailure";
+} | {
+  readonly appliedSoFar: ReadonlyArray<ResourceCurrentState>;
+  readonly key: ResourceKey;
+  readonly kind: "updateUnsupported";
+};
+/**
+* Dispatch each reconciliation operation to the matching resource driver
+* with first-fail semantics: on the first `Err` (driver failure or
+* `updateUnsupported`), the remaining operations are skipped and the error
+* is returned verbatim.
+*
+* Behaviour:
+* - `create` operations are routed to `registry[op.desired.kind].create`.
+* - `update` operations are routed to `registry[op.desired.kind].update`
+*   when the driver exposes it; otherwise they short-circuit to an
+*   `updateUnsupported` Err without invoking the driver.
+* - `noop` operations are skipped entirely (no I/O, no dispatch).
+*
+* On success the returned array carries the driver outputs for every
+* non-noop op, in dispatched order. Noops are not represented; callers
+* needing a full post-apply snapshot merge with the pre-apply current
+* state keyed by `ResourceKey`.
+*
+* @param ops - Reconciliation operations produced by `diff`, applied in order.
+* @param registry - Per-kind driver table; dispatch uses `op.desired.kind` as the index.
+* @returns `Ok(state)` when every operation succeeds, where `state` holds
+*   driver outputs for each non-noop op in dispatched order; or the first
+*   failure encountered.
+* @throws Whatever the dispatched driver rejects with outside its `Result`
+*   return. A driver whose injected I/O (file reads, network calls, etc.)
+*   throws will surface that rejection here rather than translating it into
+*   a `Result` failure; wrap the call site in a try/catch when drivers are
+*   not trusted to contain their own rejections.
+* @example
+*
+* ```ts
+* import {
+*     applyOps,
+*     asResourceKey,
+*     asRobloxAssetId,
+*     asSha256Hex,
+*     type DriverRegistry,
+*     type Operation,
+* } from "@bedrock-rbx/core";
+*
+* const registry: DriverRegistry = {
+*     gamePass: {
+*         async create(desired) {
+*             return {
+*                 data: {
+*                     ...desired,
+*                     outputs: {
+*                         assetId: asRobloxAssetId("9876543210"),
+*                         iconAssetIds: { "en-us": asRobloxAssetId("1122334455") },
+*                     },
+*                 },
+*                 success: true,
+*             };
+*         },
+*     },
+*     place: {
+*         async create(desired) {
+*             return {
+*                 data: { ...desired, outputs: { versionNumber: 1 } },
+*                 success: true,
+*             };
+*         },
+*     },
+*     universe: {
+*         async create(desired) {
+*             return {
+*                 data: { ...desired, outputs: { rootPlaceId: asRobloxAssetId("4711") } },
+*                 success: true,
+*             };
+*         },
+*     },
+*     developerProduct: {
+*         async create(desired) {
+*             return {
+*                 data: {
+*                     ...desired,
+*                     outputs: { productId: asRobloxAssetId("8172635495") },
+*                 },
+*                 success: true,
+*             };
 *         },
 *     },
+* };
+*
+* const ops: ReadonlyArray<Operation> = [
 *     {
-*         ...drifted,
-*         name: "Legend Pass",
-*         outputs: {
-*             assetId: asRobloxAssetId("333"),
-*             iconAssetIds: { "en-us": asRobloxAssetId("444") },
+*         key: asResourceKey("vip-pass"),
+*         type: "create",
+*         desired: {
+*             key: asResourceKey("vip-pass"),
+*             name: "VIP Pass",
+*             description: "Grants VIP perks.",
+*             icon: { "en-us": "assets/vip-icon.png" },
+*             iconFileHashes: {
+*                 "en-us": asSha256Hex(
+*                     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+*                 ),
+*             },
+*             kind: "gamePass",
+*             price: 500,
 *         },
 *     },
 * ];
 *
-* const ops = diff([unchanged, drifted, fresh], current);
-*
-* expect(ops.map((op) => op.type)).toEqual(["noop", "update", "create"]);
+* return applyOps(ops, registry).then((result) => {
+*     expect(result.success).toBe(true);
+*     expect(result.success && result.data).toHaveLength(1);
+* });
 * ```
 */
-declare function diff(desired: ReadonlyArray<ResourceDesiredState>, current: ReadonlyArray<ResourceCurrentState>): ReadonlyArray<Operation>;
+declare function applyOps(ops: ReadonlyArray<Operation>, registry: DriverRegistry): Promise<Result$1<ReadonlyArray<ResourceCurrentState>, ApplyError>>;
 //#endregion
-//#region src/core/display-name-prefix.d.ts
+//#region src/shell/build-default-registry.d.ts
 /**
-* Default template applied when a project enables display-name prefixing
-* without supplying its own `displayNamePrefix.format`. Yields outputs
-* like `[STAGING] ` for an environment whose `label` is `"staging"`.
+* Failure surfaced when default-constructing a registry needs a config
+* field that is not present. The deploy boundary wraps this in a
+* `DeployError` so the caller sees a typed Result instead of a downstream
+* driver error.
 */
-declare const DEFAULT_PREFIX_FORMAT = "[{LABEL}] ";
+interface RegistryConfigError {
+  /** Suggested fix routed back to the caller. */
+  readonly hint: string;
+  /** Literal discriminator for narrowing. */
+  readonly kind: "registryConfigMissing";
+  /** Which config field was missing. */
+  readonly missing: "universeId";
+}
+/** Inputs for {@link buildDefaultRegistry}. */
+interface BuildDefaultRegistryDeps {
+  /** Resolved project config; supplies `universe.universeId` and is read for nothing else. */
+  readonly config: ResolvedConfig;
+  /** Reads an environment variable; injected so tests stay free of `process.env`. */
+  readonly getEnv: (name: string) => string | undefined;
+  /** Reader plumbed into kind-specific drivers that ingest file bytes. */
+  readonly readFile: (path: string) => Promise<Uint8Array>;
+}
 /**
-* Render the prefix that selectEnvironment prepends to declared display
-* names when a project enables `displayNamePrefix`. The template
-* recognizes three placeholders:
-*
-* - `{label}`: label as written.
-* - `{LABEL}`: upper-cased label.
-* - `{Label}`: capitalized label (first character upper, rest as written).
-*
-* Other characters in the template flow through verbatim.
-*
-* @param label - Environment label declared on `EnvironmentEntry.label`.
-* @param format - Template string. Falls back to
-*   {@link DEFAULT_PREFIX_FORMAT} when omitted.
-* @returns The rendered prefix string.
+* Construct the default `DriverRegistry` from `config.universe.universeId`
+* and `BEDROCK_API_KEY`. Reads the API key via the injected `getEnv` seam
+* and surfaces `missingCredential` or `registryConfigMissing` as typed
+* Results instead of throwing.
 *
 * @example
 *
 * ```ts
-* import { renderDisplayNamePrefix } from "@bedrock-rbx/core";
+* import { buildDefaultRegistry } from "@bedrock-rbx/core";
 *
-* expect(renderDisplayNamePrefix("staging")).toBe("[STAGING] ");
-* expect(renderDisplayNamePrefix("staging", "{Label}: ")).toBe("Staging: ");
-* expect(renderDisplayNamePrefix("dev", "{LABEL}-{label}")).toBe("DEV-dev");
+* const registry = buildDefaultRegistry({
+*     config: {
+*         environments: { production: {} },
+*         state: { backend: "gist", gistId: "abc" },
+*         universe: { universeId: "1234567890" },
+*     },
+*     getEnv: () => "rbx-test",
+*     readFile: async () => new Uint8Array(),
+* });
+*
+* expect(registry.success).toBeTrue();
 * ```
+*
+* @param deps - Validated config plus credential and file-reader seams.
+* @returns A `DriverRegistry` on success, or a typed Err describing the
+* missing API key or the missing universe declaration.
 */
-declare function renderDisplayNamePrefix(label: string, format?: string): string;
+declare function buildDefaultRegistry(deps: BuildDefaultRegistryDeps): Result$1<DriverRegistry, MissingCredentialError | RegistryConfigError>;
 //#endregion
-//#region src/core/environment.d.ts
+//#region src/core/flatten.d.ts
 /**
-* Validate an environment name at a state-adapter boundary.
-*
-* Adapters that map environment names onto filesystem-like identifiers
-* (gist filenames, S3 keys) must reject names that could collide or escape
-* their storage layout. This helper accepts letters, digits, `-`, and `_`
-* only, with length between 1 and 64, and returns a `StateError` for
-* anything outside that set so the adapter can fail loudly instead of
-* silently stripping characters.
+* Pre-I/O game-pass input the flattener emits. Extends the authored
+* `GamePassEntry` with the tag discriminator and the `ResourceKey`-branded
+* key so `buildDesired` can consume a flat tagged list and layer on the
+* SHA-256 icon digest.
 *
 * @example
 *
 * ```ts
-* import { validateEnvironmentName } from "@bedrock-rbx/core";
-*
-* const ok = validateEnvironmentName("production");
-* expect(ok.success).toBeTrue();
-*
-* const bad = validateEnvironmentName("prod/staging");
-* expect(bad.success).toBeFalse();
-* ```
-*
-* @param environment - Raw environment name supplied by a caller.
-* @returns `Ok(environment)` when the name is safe to use, or
-* `Err(StateError)` with a descriptive reason when it is not.
-*/
-declare function validateEnvironmentName(environment: string): Result$1<string, StateError>;
-//#endregion
-//#region src/core/flatten.d.ts
-/**
-* Pre-I/O game-pass input the flattener emits. Extends the authored
-* `GamePassEntry` with the tag discriminator and the `ResourceKey`-branded
-* key so `buildDesired` can consume a flat tagged list and layer on the
-* SHA-256 icon digest.
-*
-* @example
-*
-* ```ts
-* import { asResourceKey, type GamePassDesiredInput } from "@bedrock-rbx/core";
+* import { asResourceKey, type GamePassDesiredInput } from "@bedrock-rbx/core";
 *
 * const input: GamePassDesiredInput = {
 *     description: "Grants VIP perks.",
@@ -2110,47 +2063,6 @@ type ResourceDesiredInput = DeveloperProductDesiredInput | GamePassDesiredInput
 */
 declare function flattenConfig(config: ResolvedConfig): ReadonlyArray<ResourceDesiredInput>;
 //#endregion
-//#region src/core/get-environment.d.ts
-/**
-* Failure modes returned by {@link getEnvironment}.
-*/
-type GetEnvironmentError = {
-  readonly kind: "missingEnvironment";
-} | {
-  readonly kind: "multipleEnvironments";
-  readonly values: ReadonlyArray<string>;
-};
-/**
-* Resolve the deploy environment for an override script invocation.
-*
-* Reads `--env <name>` from the supplied argv first, falls back to
-* `BEDROCK_ENVIRONMENT` from the supplied env reader. Returns
-* `missingEnvironment` when neither is present and `multipleEnvironments`
-* (with every offending value) when argv contains more than one `--env`
-* flag. Both inputs default to the running process so override scripts
-* under `.bedrock/` can call `getEnvironment()` with no arguments.
-*
-* @param argv - Argument list to scan for `--env <name>` flags. Defaults to
-* `process.argv.slice(2)` when omitted.
-* @param readEnvironment - Reads an environment variable; consulted as a
-* fallback when no `--env` flag is present. Defaults to a `process.env`
-* reader when omitted.
-* @returns `Ok(environment)` on success, `Err(GetEnvironmentError)` otherwise.
-* @example
-*
-* ```ts
-* import { getEnvironment } from "@bedrock-rbx/core";
-*
-* const result = getEnvironment(["--env", "production"], () => undefined);
-*
-* expect(result.success).toBeTrue();
-* if (result.success) {
-*     expect(result.data).toBe("production");
-* }
-* ```
-*/
-declare function getEnvironment(argv?: ReadonlyArray<string>, readEnvironment?: (name: string) => string | undefined): Result$1<string, GetEnvironmentError>;
-//#endregion
 //#region src/core/kinds/module.d.ts
 /**
 * Failure surfaced during desired-state preparation. Two variants today:
@@ -2325,1007 +2237,1284 @@ type InputFor<K extends ResourceKind> = Extract<ResourceDesiredInput, {
   readonly kind: K;
 }>;
 //#endregion
-//#region src/core/icons.d.ts
+//#region src/shell/build-desired.d.ts
 /**
-* Cost-gate for icon re-uploads. Returns `true` when the locally-hashed
-* desired icon differs from the hash recorded on the prior current-state
-* entry, signalling that the driver must re-upload before reconciling.
-* Returns `false` when the hashes match (no re-upload needed) and when
-* both sides report no icon.
-*
-* The signature takes hash maps directly (not whole-state) so the helper
-* is independent of any specific resource-kind shape; every icon-bearing
-* driver projects its own `iconFileHashes` and `outputs.iconFileHashes`
-* fields before calling.
+* Layer file I/O onto a flat tagged list of resource inputs to produce
+* `ResourceDesiredState`.
 *
-* @param currentHashes - Hashes recorded on the prior current-state entry.
-* @param desiredHashes - Hashes layered onto the desired-state entry by
-*   `normalize` from the local icon file's bytes.
-* @returns `true` when the driver should re-upload the icon.
+* For each input, reads the file bytes via the injected `readFile`, computes
+* the SHA-256 hex digest, and assembles the branded desired-state record
+* that `diff` consumes. Entries are processed sequentially so the first
+* failure's attribution is deterministic.
 *
+* @param inputs - Flat tagged resource inputs from `flattenConfig`.
+* @param readFile - Reads file bytes for a given path; rejection becomes a
+* `fileReadFailed` Err.
+* @returns `Ok` with the desired-state array (same length and order as
+* `inputs`), or `Err` with the first I/O failure.
 * @example
 *
 * ```ts
-* import { asSha256Hex, shouldReuploadIcon } from "@bedrock-rbx/core";
+* import { asResourceKey, buildDesired } from "@bedrock-rbx/core";
 *
-* const previous = asSha256Hex(
-*     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-* );
-* const fresh = asSha256Hex(
-*     "2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881",
-* );
+* async function readFile(): Promise<Uint8Array> {
+*     return new Uint8Array([1, 2, 3]);
+* }
 *
-* expect(shouldReuploadIcon({ "en-us": previous }, { "en-us": previous })).toBe(false);
-* expect(shouldReuploadIcon({ "en-us": previous }, { "en-us": fresh })).toBe(true);
+* return buildDesired(
+*     [
+*         {
+*             description: "Grants VIP perks.",
+*             icon: { "en-us": "assets/vip-icon.png" },
+*             key: asResourceKey("vip-pass"),
+*             kind: "gamePass",
+*             name: "VIP Pass",
+*             price: 500,
+*         },
+*     ],
+*     readFile,
+* ).then((result) => {
+*     expect(result.success).toBeTrue();
+*     if (result.success) {
+*         expect(result.data).toHaveLength(1);
+*         expect(result.data[0]!.kind).toBe("gamePass");
+*     }
+* });
 * ```
 */
-declare function shouldReuploadIcon(currentHashes: Record<"en-us", Sha256Hex> | undefined, desiredHashes: Record<"en-us", Sha256Hex> | undefined): boolean;
+declare function buildDesired(inputs: ReadonlyArray<ResourceDesiredInput>, readFile: (path: string) => Promise<Uint8Array>): Promise<Result$1<ReadonlyArray<ResourceDesiredState>, BuildDesiredError>>;
 //#endregion
-//#region src/core/kinds/index.d.ts
+//#region src/shell/load-config.d.ts
 /**
-* Default {@link KindRegistry} composing every resource kind bedrock ships
-* out of the box. Iteration order (`gamePass`, `place`, `universe`,
-* `developerProduct`) matches the order `flattenConfig` emits entries
-* today, preserving the observable order of generated operations.
+* Options for {@link loadConfig}. Matches a subset of c12's loader options;
+* additional fields land with the issues that introduce each flow.
+*/
+interface LoadConfigOptions {
+  /**
+  * Path to a specific config file to load, including its extension.
+  * Resolved relative to `cwd` when not absolute. Loaded as-is with no
+  * extension search; if the file does not exist at the given path,
+  * `loadConfig` returns `fileNotFound`. When omitted, `loadConfig`
+  * discovers `bedrock.config.{ts,js,...}` from `cwd`.
+  */
+  readonly configFile?: string;
+  /**
+  * Directory to search from. Defaults to `process.cwd()` at call time, so
+  * each invocation sees the current working directory.
+  */
+  readonly cwd?: string;
+}
+/**
+* Discover, parse, and validate the project config.
+*
+* Looks for `bedrock.config.{ts,js,mjs,cjs,yaml,yml,json}`, `.bedrockrc*`,
+* and `package.json#bedrock` starting at `options.cwd` (or the current
+* working directory). Returns a fresh, mutable `Config` on every call so
+* long-running scripts see up-to-date values.
+*
+* When the exported default is a function (sync or async), `loadConfig`
+* invokes it with an empty `ConfigContext` and awaits the result before
+* validating.
+*
+* Errors return via `Result`:
+* - `fileNotFound` - no config file was discovered under the search path.
+* - `parseFailed` - a config file was found but could not be parsed (for
+*   example, malformed YAML or JSON).
+* - `validationFailed` - a file was found and parsed, but its content did
+*   not satisfy the runtime schema.
+* - `configFunctionFailed` - a function-form config threw or its returned
+*   promise rejected while being invoked.
 *
+* @param options - Loader options.
+* @returns `Ok` with the validated `Config`, or `Err` with a `ConfigError`.
 * @example
 *
 * ```ts
-* import { defaultKindRegistry } from "@bedrock-rbx/core";
+* import { loadConfig } from "@bedrock-rbx/core";
 *
-* expect(defaultKindRegistry.gamePass.kind).toBe("gamePass");
-* expect(defaultKindRegistry.place.kind).toBe("place");
-* expect(defaultKindRegistry.universe.kind).toBe("universe");
-* expect(defaultKindRegistry.developerProduct.kind).toBe("developerProduct");
+* return loadConfig({
+*     configFile: "bedrock.staging.config.yaml",
+*     cwd: "/path/that/does/not/have/a/config",
+* }).then((result) => {
+*     expect(result.success).toBeFalse();
+*     if (!result.success) {
+*         expect(result.err.kind).toBe("fileNotFound");
+*     }
+* });
 * ```
 */
-declare const defaultKindRegistry: KindRegistry;
+declare function loadConfig(options?: LoadConfigOptions): Promise<Result$1<Config, ConfigError>>;
 //#endregion
-//#region src/core/migrate/migration-report.d.ts
+//#region src/shell/deploy.d.ts
 /**
-* Per-environment in-memory state snapshot map keyed by environment name.
-*
-* `Record` rather than the PRD-suggested `Map` so the field survives
-* `JSON.stringify` for downstream logging and parallel-iterates cleanly
-* with `Config.environments` (which is itself a `Record`).
+* Inputs for `deploy`. Every field except `environment` is optional;
+* omitted dependencies are default-constructed from the project config
+* and the environment variables `GITHUB_TOKEN` and `BEDROCK_API_KEY`.
 */
-type StatesByEnvironment = Readonly<Record<string, BedrockState>>;
+interface DeployOptions {
+  /** Pre-loaded, optionally-mutated project config. Omit to call `loadConfig()` automatically. */
+  readonly config?: Config;
+  /** Environment name; threaded into `StatePort.read` and the persisted snapshot. */
+  readonly environment: string;
+  /** `fetch` override plumbed into the default-constructed gist adapter when `statePort` is omitted. */
+  readonly fetch?: GistFetch;
+  /** Reads an environment variable; defaults to `(name) => process.env[name]`. */
+  readonly getEnv?: (name: string) => string | undefined;
+  /** Loader invoked when `config` is omitted; defaults to `loadConfig` from this package. */
+  readonly loadConfig?: (options?: LoadConfigOptions) => Promise<Result$1<Config, ConfigError>>;
+  /** Reads file bytes for resources that have file-backed inputs. Defaults to `node:fs/promises.readFile`. */
+  readonly readFile?: (path: string) => Promise<Uint8Array>;
+  /** Per-kind driver table consulted for create / update dispatch. Default-constructed from `BEDROCK_API_KEY` when omitted. */
+  readonly registry?: DriverRegistry;
+  /** Backend used to read the prior snapshot and persist the new one. Default-constructed from `config.state` and `GITHUB_TOKEN` when omitted. */
+  readonly statePort?: StatePort;
+}
 /**
-* Aggregate counts for the four `MigrationWarning` kinds. Computed by
-* folding `MigrationReport.warnings`; lets a CI gate skim totals without
-* iterating every entry. All fields are zero on a clean migration.
+* Failure surfaced by `deploy`. Stage-tagged so callers can branch on
+* `kind` to distinguish reconciliation failures (`stateReadFailed`,
+* `applyFailed`, ...) from default-construction failures
+* (`configLoadFailed`, `stateNotConfigured`, `unknownEnvironment`,
+* `incompletePlaceEntry`, `incompleteUniverseEntry`, `missingCredential`,
+* `unsupportedBackend`, `registryConfigMissing`).
 */
-interface MigrationSummary {
-  /** Number of `ambiguous` warnings emitted. */
-  readonly ambiguousCount: number;
-  /** Number of `blocked` warnings emitted. */
-  readonly blockedCount: number;
-  /** Number of `deferred` warnings emitted. */
-  readonly deferredCount: number;
-  /** Number of `interpretive` warnings emitted. */
-  readonly interpretiveCount: number;
-}
+type DeployError = IncompletePlaceEntryError | IncompleteUniverseEntryError | MissingCredentialError | RegistryConfigError | StateNotConfiguredError | UnknownEnvironmentError | UnsupportedBackendError | {
+  readonly cause: ApplyError;
+  readonly kind: "applyFailed";
+} | {
+  readonly cause: BuildDesiredError;
+  readonly kind: "buildDesiredFailed";
+} | {
+  readonly cause: ConfigError;
+  readonly kind: "configLoadFailed";
+} | {
+  readonly cause: StateError;
+  readonly kind: "stateReadFailed";
+} | {
+  readonly cause: StateError;
+  readonly kind: "stateWriteFailed";
+  readonly unsavedState: BedrockState;
+};
 /**
-* Discriminated union describing one observation the migrator made about a
-* Mantle field that did not flow straight into bedrock config or state.
+* Run a full reconcile end-to-end. Default-constructs missing deps from
+* the project config and the environment variables `GITHUB_TOKEN` and
+* `BEDROCK_API_KEY`; never reads `process.env` when `statePort`,
+* `registry`, and `config` are all supplied explicitly.
 *
-* - `deferred` - bedrock plans to support the field once the matching
-*   resource kind ships; the migration is non-destructive.
-* - `blocked` - no Open Cloud writable endpoint exists; Mantle was using a
-*   cookie or legacy API that bedrock cannot call.
-* - `interpretive` - the migrator applied a documented mapping rule
-*   (cross-field fold, list-to-flag rewrite, URL-domain dispatch). Each
-*   rule names the bedrock-side path it produced and the rule it followed
-*   so the user can audit.
-* - `ambiguous` - the field is mappable but unsafe to act on without
-*   user input; the migrator carries the hint forward instead of guessing.
+* @param options - Target environment plus optional overrides.
+* @returns The persisted `BedrockState` on success, or a stage-tagged
+*   `DeployError` on failure.
+* @example
 *
-* Every variant carries `mantlePath` rooted at the environment so the
-* report is searchable (for example
-* `production.experienceConfiguration_singleton.genre`).
-*/
-type MigrationWarning = {
-  readonly bedrockPath: string;
-  readonly kind: "interpretive";
-  readonly mantlePath: string;
-  readonly rule: string;
-} | {
-  readonly hint: string;
-  readonly kind: "ambiguous";
-  readonly mantlePath: string;
-} | {
-  readonly kind: "blocked";
-  readonly mantlePath: string;
-  readonly reason: string;
-} | {
-  readonly kind: "deferred";
-  readonly mantlePath: string;
-  readonly reason: string;
-};
-/**
-* Failure surfaced by `migrateMantleState`. Plain-data discriminated
-* union; narrow on `kind` rather than using `instanceof`.
+* ```ts
+* import { deploy } from "@bedrock-rbx/core";
 *
-* - `stateFileNotFound` - `deps.readFile` threw with `code: "ENOENT"`;
-*   the file does not exist at the supplied path. Permission failures
-*   (`EACCES`, `EPERM`) and other I/O errors are re-thrown rather than
-*   wrapped here, so callers see the original code on the rejection.
-* - `stateParseFailed` - the YAML parser refused the file's contents.
-* - `unsupportedMantleStateVersion` - the parsed file's `version` field is
-*   not one of the values in `supported`. V0.1 supports `"6"` only; older
-*   versions need to be upgraded with any recent Mantle release first.
-* - `primaryEnvironmentRequired` - the input has more than one environment
-*   and `deps.primaryEnvironment` was not supplied. The migrator refuses
-*   to silently pick a winner.
-* - `primaryEnvironmentNotFound` - `deps.primaryEnvironment` does not match
-*   any environment in the input.
-* - `internalError` - the migrator's own emitted config failed
-*   `validateConfig`; `cause` carries the `ConfigError` so callers can
-*   inspect each `validationFailed` issue. Defensive bug catcher that
-*   callers should never see in practice.
+* return deploy({ environment: "production" }).then((result) => {
+*     expect(result.success).toBeFalse();
+*     if (!result.success) {
+*         expect(["configLoadFailed", "stateNotConfigured"]).toContain(result.err.kind);
+*     }
+* });
+* ```
+*
+* @example
+*
+* ```ts
+* import { deploy, type BedrockState, type DriverRegistry, type StatePort } from "@bedrock-rbx/core";
+*
+* const store = new Map<string, BedrockState>();
+* const statePort: StatePort = {
+*     async read(environment) {
+*         return { data: store.get(environment), success: true };
+*     },
+*     async write(state) {
+*         store.set(state.environment, state);
+*         return { data: undefined, success: true };
+*     },
+* };
+* const registry: DriverRegistry = {
+*     developerProduct: {
+*         create: async () => { throw new Error("unreachable: empty config"); },
+*     },
+*     gamePass: { create: async () => { throw new Error("unreachable: empty config"); } },
+*     place: { create: async () => { throw new Error("unreachable: empty config"); } },
+*     universe: { create: async () => { throw new Error("unreachable: empty config"); } },
+* };
+*
+* return deploy({
+*     config: {
+*         environments: { production: {} },
+*         state: { backend: "gist", gistId: "abc" },
+*         passes: {},
+*     },
+*     environment: "production",
+*     registry,
+*     statePort,
+* }).then((result) => {
+*     expect(result.success).toBeTrue();
+*     if (result.success) {
+*         expect(result.data.environment).toBe("production");
+*         expect(result.data.resources).toBeEmpty();
+*     }
+* });
+* ```
 */
-type MigrateError = {
-  readonly available: ReadonlyArray<string>;
-  readonly kind: "primaryEnvironmentNotFound";
-  readonly primary: string;
-} | {
-  readonly available: ReadonlyArray<string>;
-  readonly kind: "primaryEnvironmentRequired";
-} | {
-  readonly cause: ConfigError;
-  readonly kind: "internalError";
-  readonly reason: string;
-} | {
-  readonly found: string;
-  readonly kind: "unsupportedMantleStateVersion";
-  readonly supported: ReadonlyArray<string>;
-} | {
-  readonly kind: "stateFileNotFound";
-  readonly path: string;
-} | {
-  readonly kind: "stateParseFailed";
-  readonly path: string;
-  readonly reason: string;
-};
+declare function deploy(options: DeployOptions): Promise<Result$1<BedrockState, DeployError>>;
+//#endregion
+//#region src/cli/render.d.ts
 /**
-* Result returned by a successful `migrateMantleState` call.
+* Output port the CLI renders through. Mirrors the subset of `@clack/prompts`
+* the bedrock CLI uses today; tests inject a fake to assert what was rendered.
 *
-* `config` is the bedrock-shape projection of the Mantle state file,
-* already validated against the runtime schema (a failure to validate
-* surfaces as `MigrateError.internalError`, not as a returned report).
+* @example
 *
-* `configFileContent` is the same data rendered as TypeScript source
-* (`defineConfig({...})`) so the caller can write it straight to disk
-* without re-serializing. `loadConfig` round-trips it cleanly.
+* ```ts
+* import type { ClackPort } from "@bedrock-rbx/core";
+*
+* const lines: Array<string> = [];
+* const port: ClackPort = {
+*     cancel: (message) => lines.push(`cancel: ${message}`),
+*     intro: (message) => lines.push(`intro: ${message}`),
+*     logError: (message) => lines.push(`error: ${message}`),
+*     logMessage: (message) => lines.push(`log: ${message}`),
+*     logSuccess: (message) => lines.push(`ok: ${message}`),
+*     outro: (message) => lines.push(`outro: ${message}`),
+* };
 *
-* `statesByEnvironment` carries one in-memory `BedrockState` per
-* environment from the input. Truthful per environment (no factorization)
-* so `bedrock deploy --env=<env>` produces zero ops on first run.
+* port.logSuccess("done");
 *
-* `warnings` and `summary` describe what the migrator did *not* migrate
-* verbatim, classified for triage. The skeleton emits no warnings.
+* expect(lines).toEqual(["ok: done"]);
+* ```
 */
-interface MigrationReport {
-  /** Validated bedrock config built from the Mantle state file. */
-  readonly config: Config;
-  /** Same `config` rendered as TypeScript source the caller can write to disk. */
-  readonly configFileContent: string;
-  /** One `BedrockState` per environment in the input, keyed by environment name. */
-  readonly statesByEnvironment: StatesByEnvironment;
-  /** Aggregate counts of `warnings` by kind. */
-  readonly summary: MigrationSummary;
-  /** One entry per non-trivial mapping or skipped Mantle field. */
-  readonly warnings: ReadonlyArray<MigrationWarning>;
+interface ClackPort {
+  /** End an interactive flow with a cancellation marker. */
+  cancel(message: string): void;
+  /** Open a framed section with a title (used for command intros). */
+  intro(message: string): void;
+  /** Render a single error line inside an open frame. */
+  logError(message: string): void;
+  /** Render a single neutral line inside an open frame. */
+  logMessage(message: string): void;
+  /** Render a single success line inside an open frame. */
+  logSuccess(message: string): void;
+  /** Close the current framed section with a final message. */
+  outro(message: string): void;
 }
 //#endregion
-//#region src/core/resolve-state-config.d.ts
+//#region src/ports/progress-port.d.ts
 /**
-* Failure surfaced when no `StateConfig` is configured for the requested
-* environment. The shell layer wraps this in a `DeployError` when default
-* state-port construction is requested but the project has not declared
-* where state should live.
+* Per-environment outcome event emitted after a deploy completes
+* successfully. Carries the environment name and the count of resources
+* present in the persisted state snapshot.
 */
-interface StateNotConfiguredError {
-  /** Environment that the resolver was called against. */
+interface DeploySuccessEvent {
+  /** The environment that finished reconciling. */
   readonly environment: string;
-  /** Literal discriminator for narrowing. */
-  readonly kind: "stateNotConfigured";
+  /** Discriminator tag. */
+  readonly kind: "deploySuccess";
+  /** Number of resources in the post-deploy state snapshot. */
+  readonly resourceCount: number;
 }
 /**
-* Minimal structural input the state resolver needs. Both `Config`
-* (pre-merge, discriminated XOR union) and `ResolvedConfig` (post-merge)
-* satisfy this shape, so callers can route either in without coupling
-* the resolver to the discriminated-union arms.
+* Per-environment outcome event emitted when a deploy fails. Carries the
+* environment name and the full {@link DeployError} so a renderer can
+* delegate to the existing diagnostic helpers.
 */
-interface StateResolutionInputs {
-  readonly environments: Record<string, undefined | {
-    readonly state?: StateConfig;
-  }>;
-  readonly state?: StateConfig;
+interface DeployFailureEvent {
+  /** The environment whose deploy failed. */
+  readonly environment: string;
+  /** Stage-tagged failure reason returned by the shell `deploy` function. */
+  readonly error: DeployError;
+  /** Discriminator tag. */
+  readonly kind: "deployFailure";
 }
 /**
-* Pick the `StateConfig` that applies to `environment`. Per-environment
-* overrides win over the root block; if neither is present, returns
-* `Err(stateNotConfigured)` so the deploy boundary can surface a typed
-* error instead of silently falling back.
+* Discriminated union of progress events the CLI emits while a deploy
+* runs. The variant set is additive: future per-stage and per-resource
+* events land as new `kind` values without breaking existing adapters.
+*/
+type ProgressEvent = DeployFailureEvent | DeploySuccessEvent;
+/**
+* Plugin contract for receiving deploy outcomes: the interface an adapter
+* (clack renderer, JSON logger, custom UI) implements to let the CLI hand
+* off events without re-implementing rendering logic.
+*
+* `ProgressPort` is a *driven* (secondary) port in hexagonal terms.
 *
-* @param config - Validated project config.
-* @param environment - Target environment name.
-* @returns The resolved `StateConfig`, or `Err(stateNotConfigured)` when
-* neither the environment override nor the root block is set.
 * @example
 *
 * ```ts
-* import { resolveStateConfig } from "@bedrock-rbx/core";
+* import type { ProgressEvent, ProgressPort } from "@bedrock-rbx/core";
 *
-* const result = resolveStateConfig(
-*     {
-*         state: { backend: "gist", gistId: "root-gist" },
-*         environments: {
-*             production: { state: { backend: "gist", gistId: "prod-gist" } },
-*         },
+* let received: ReadonlyArray<ProgressEvent> = [];
+* const port: ProgressPort = {
+*     emit(event) {
+*         received = [...received, event];
 *     },
-*     "production",
-* );
+* };
 *
-* expect(result.success).toBeTrue();
-* if (result.success) {
-*     expect(result.data).toContainEntry(["gistId", "prod-gist"]);
-* }
+* port.emit({ environment: "production", kind: "deploySuccess", resourceCount: 3 });
+*
+* expect(received).toEqual([
+*     { environment: "production", kind: "deploySuccess", resourceCount: 3 },
+* ]);
 * ```
 */
-declare function resolveStateConfig(config: StateResolutionInputs, environment: string): Result$1<StateConfig, StateNotConfiguredError>;
+interface ProgressPort {
+  /** Hand a single progress event to the adapter for rendering or logging. */
+  emit(event: ProgressEvent): void;
+}
 //#endregion
-//#region src/core/select-environment.d.ts
+//#region src/adapters/clack-progress-adapter.d.ts
 /**
-* Failure surfaced when `selectEnvironment` is asked for an environment
-* name that is not a key of `config.environments`. Carries the list of
-* declared names so callers can render a "did you mean?" hint or a
-* close-match suggestion.
+* Configuration for {@link createClackProgressAdapter}.
 */
-interface UnknownEnvironmentError {
-  /** Environment names that the config actually declared. */
-  readonly declared: ReadonlyArray<string>;
-  /** Environment name the caller asked for. */
-  readonly environment: string;
-  /** Literal discriminator for narrowing. */
-  readonly kind: "unknownEnvironment";
+interface ClackProgressAdapterDeps {
+  /** Output port the events are rendered through. */
+  readonly clack: ClackPort;
 }
 /**
-* Failure surfaced when a merged place entry is missing a required field.
-* Two paths reach this error: a root place declared without a matching
-* per-environment overlay supplying `placeId`, and an overlay-only place
-* declared under `environments.X.places` with no matching root entry to
-* supply `filePath`. Surfacing both at the resolution boundary attributes
-* the missing field to the offending entry's key instead of letting
-* `buildDesired` crash with a generic `fileReadFailed` later on.
+* Build a {@link ProgressPort} that renders events through a `ClackPort`.
+* Pattern-matches on the event `kind`: `deploySuccess` becomes a single
+* success line and `deployFailure` delegates to the package's deploy-error
+* rendering helper.
+*
+* @example
+*
+* ```ts
+* import { createClackProgressAdapter, type ClackPort } from "@bedrock-rbx/core";
+*
+* const lines: Array<string> = [];
+* const clack: ClackPort = {
+*     cancel: (message) => lines.push(`cancel: ${message}`),
+*     intro: (message) => lines.push(`intro: ${message}`),
+*     logError: (message) => lines.push(`error: ${message}`),
+*     logMessage: (message) => lines.push(`log: ${message}`),
+*     logSuccess: (message) => lines.push(`ok: ${message}`),
+*     outro: (message) => lines.push(`outro: ${message}`),
+* };
+*
+* const port = createClackProgressAdapter({ clack });
+*
+* port.emit({ environment: "production", kind: "deploySuccess", resourceCount: 3 });
+*
+* expect(lines).toEqual(["ok: production: 3 resources reconciled"]);
+* ```
+*
+* @param deps - The clack port the adapter renders through.
+* @returns A `ProgressPort` that renders via clack.
 */
-interface IncompletePlaceEntryError {
-  /** ResourceKey of the place entry that is missing a required field. */
-  readonly key: string;
-  /** Environment whose overlay was projected onto the config. */
-  readonly environment: string;
-  /** Literal discriminator for narrowing. */
-  readonly kind: "incompletePlaceEntry";
-  /** Field that the merged entry lacks. */
-  readonly missingField: "filePath" | "placeId";
-}
+declare function createClackProgressAdapter(deps: ClackProgressAdapterDeps): ProgressPort;
+//#endregion
+//#region src/adapters/developer-product-driver.d.ts
 /**
-* Failure surfaced when a merged `universe` block lacks `universeId`.
-* The schema-level XOR rule normally prevents this by requiring
-* `universeId` either at the root or on every per-environment overlay;
-* this error remains as a typed safety net for callers that bypass
-* `validateConfig` and hand a `Config` to `selectEnvironment` directly.
-*/
-interface IncompleteUniverseEntryError {
-  /** Environment whose overlay was projected onto the config. */
-  readonly environment: string;
-  /** Literal discriminator for narrowing. */
-  readonly kind: "incompleteUniverseEntry";
-  /** Field that the merged entry lacks. V1 only surfaces `"universeId"`. */
-  readonly missingField: "universeId";
+* Dependencies of `createDeveloperProductDriver`. `universeId` is captured
+* at construction time (matching `GamePassDriverDeps`) so each driver
+* instance is bound to a single universe; multi-universe deploys construct
+* one driver per universe. `readFile` exists on the driver (not upstream
+* in shell) because icon hashes flow through `diff` but bytes do not.
+*
+* @example
+*
+* ```ts
+* import type { HttpClient } from "@bedrock-rbx/ocale";
+* import { DeveloperProductsClient } from "@bedrock-rbx/ocale/developer-products";
+* import { asRobloxAssetId, type DeveloperProductDriverDeps } from "@bedrock-rbx/core";
+*
+* const httpClient: HttpClient = {
+*     async request() {
+*         return { data: { body: {}, headers: {}, status: 200 }, success: true };
+*     },
+* };
+*
+* const deps: DeveloperProductDriverDeps = {
+*     client: new DeveloperProductsClient({
+*         apiKey: "rbx-your-key",
+*         httpClient,
+*         sleep: async () => {},
+*     }),
+*     readFile: async () => new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+*     universeId: asRobloxAssetId("1234567890"),
+* };
+*
+* expect(deps.universeId).toBe("1234567890");
+* ```
+*/
+interface DeveloperProductDriverDeps {
+  /** Configured developer-products client from `@bedrock-rbx/ocale/developer-products`. */
+  readonly client: DeveloperProductsClient;
+  /** Reads icon bytes for upload; rejections propagate out of `create` and `update`. */
+  readonly readFile: (path: string) => Promise<Uint8Array>;
+  /** Universe that owns every developer product this driver creates. */
+  readonly universeId: RobloxAssetId;
 }
-/** Failure modes returned by {@link selectEnvironment}. */
-type SelectEnvironmentError = IncompletePlaceEntryError | IncompleteUniverseEntryError | UnknownEnvironmentError;
 /**
-* Project a validated `Config` onto a single environment. Looks up the
-* matching `environments[environment]` entry, deep-merges its resource
-* overlay (`passes`, `places`, `universe`) over the root config via defu,
-* and applies the env-level state override when present (the env entry's
-* `state` field wins; otherwise the root `state` flows through).
+* Wraps {@link DeveloperProductsClient} as a `ResourceDriver<"developerProduct">`
+* that maps a desired-state entry to an ocale create or update call and the
+* response back to a `ResourceCurrentState<"developerProduct">`. The
+* `update` path consumes the upstream `204 No Content` response and
+* synthesizes the post-update `ResourceCurrentState` from `desired` plus
+* the existing `current.outputs`, carrying `iconImageAssetId` forward when
+* present.
 *
-* Pure: no I/O. Returns a `ResolvedConfig` ready to feed into downstream
-* functions (`flattenConfig`, `buildDefaultRegistry`, `resolveStateConfig`).
-* The post-merge view promotes `places` from `Record<string, PlaceEntry>`
-* (root: file-paths only) to `Record<string, ResolvedPlaceEntry>` (root +
-* overlay merged). `environments` and `extends` are passed through
-* unchanged because they preserve the shape relationship to `Config`;
-* downstream consumers do not read them post-merge.
+* Upstream `OpenCloudError` results pass through as `Result` failures.
 *
-* Defu's merge semantics are deliberate: keyed-map collections merge by
-* key (so a place declared in both root and overlay produces a single
-* entry whose overlay-supplied fields win), and `null` / `undefined` in
-* the overlay are skipped (so the overlay never deletes a root field).
-* State has its own resolution path (a single replacement, not a
-* deep-merge) because it is a tagged union: a deep-merge of
-* `{ backend: "s3" }` over `{ backend: "gist", gistId }` would produce
-* a malformed `{ backend: "s3", gistId }`.
+* @param deps - Injected ocale client and owning universe.
+* @returns A driver indexable by `"developerProduct"` in a `DriverRegistry`.
 *
-* State is left absent when neither the env override nor the root block
-* provides one. Callers that require a resolved `StateConfig` should
-* route through `resolveStateConfig` or `buildStatePort`; the absent
-* case surfaces as a typed `stateNotConfigured` there.
+* @example
 *
-* Limitation in v1: a per-environment universe overlay that introduces a
-* brand-new universe block may still have optional fields missing, since
-* the overlay type only requires the identity-bearing key. The resolver
-* surfaces the entry as-is; the universe driver reports the missing
-* field when it tries to consume the entry. Universe is a singleton with
-* 20+ optional fields, so the same `incompletePlaceEntry`-style validation
-* is deferred to a separate follow-up.
+* ```ts
+* import type { HttpClient } from "@bedrock-rbx/ocale";
+* import { DeveloperProductsClient } from "@bedrock-rbx/ocale/developer-products";
+* import {
+*     asResourceKey,
+*     asRobloxAssetId,
+*     createDeveloperProductDriver,
+* } from "@bedrock-rbx/core";
+*
+* const httpClient: HttpClient = {
+*     async request() {
+*         return {
+*             data: {
+*                 body: {
+*                     createdTimestamp: "2024-01-15T10:30:00.000Z",
+*                     description: "Stocks the player up with 1,000 premium gems.",
+*                     iconImageAssetId: null,
+*                     isForSale: false,
+*                     isImmutable: false,
+*                     name: "Gem Pack",
+*                     priceInformation: null,
+*                     productId: 9_876_543_210,
+*                     storePageEnabled: false,
+*                     universeId: 1_234_567_890,
+*                     updatedTimestamp: "2024-01-15T10:30:00.000Z",
+*                 },
+*                 headers: {},
+*                 status: 200,
+*             },
+*             success: true,
+*         };
+*     },
+* };
+*
+* const driver = createDeveloperProductDriver({
+*     client: new DeveloperProductsClient({
+*         apiKey: "rbx-your-key",
+*         httpClient,
+*         sleep: async () => {},
+*     }),
+*     readFile: async () => new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+*     universeId: asRobloxAssetId("1234567890"),
+* });
+*
+* return driver
+*     .create({
+*         description: "Stocks the player up with 1,000 premium gems.",
+*         isRegionalPricingEnabled: undefined,
+*         key: asResourceKey("gem-pack"),
+*         kind: "developerProduct",
+*         name: "Gem Pack",
+*         price: undefined,
+*         storePageEnabled: undefined,
+*     })
+*     .then((result) => {
+*         expect(result.success).toBeTrue();
+*         if (result.success) {
+*             expect(result.data.outputs.productId).toBe("9876543210");
+*         }
+*     });
+* ```
+*/
+declare function createDeveloperProductDriver(deps: DeveloperProductDriverDeps): ResourceDriver<"developerProduct">;
+//#endregion
+//#region src/adapters/game-pass-driver.d.ts
+/**
+* `universeId` is captured at construction time rather than on
+* `GamePassDesiredState` so state files round-trip with Mantle's `PassInputs`
+* shape. `readFile` exists on the driver (not upstream in shell) because icon
+* hashes flow through `diff` but bytes do not.
+*
+* @example
+*
+* ```ts
+* import type { HttpClient } from "@bedrock-rbx/ocale";
+* import { GamePassesClient } from "@bedrock-rbx/ocale/game-passes";
+* import { asRobloxAssetId, type GamePassDriverDeps } from "@bedrock-rbx/core";
+*
+* const httpClient: HttpClient = {
+*     async request() {
+*         return { data: { body: {}, headers: {}, status: 200 }, success: true };
+*     },
+* };
+*
+* const deps: GamePassDriverDeps = {
+*     client: new GamePassesClient({
+*         apiKey: "rbx-your-key",
+*         httpClient,
+*         sleep: async () => {},
+*     }),
+*     readFile: async () => new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+*     universeId: asRobloxAssetId("1234567890"),
+* };
+*
+* expect(deps.universeId).toBe("1234567890");
+* ```
+*/
+interface GamePassDriverDeps {
+  /** Configured game-passes client from `@bedrock-rbx/ocale/game-passes`. */
+  readonly client: GamePassesClient;
+  /** Reads icon bytes for upload; rejections propagate out of `create`. */
+  readonly readFile: (path: string) => Promise<Uint8Array>;
+  /** Universe that owns every game pass this driver creates. */
+  readonly universeId: RobloxAssetId;
+}
+/**
+* Wraps {@link GamePassesClient} as a `ResourceDriver<"gamePass">` that maps
+* a desired-state entry to an ocale create call and the response back to a
+* `ResourceCurrentState<"gamePass">`.
+*
+* Upstream `OpenCloudError` results pass through as `Result` failures.
+* Filesystem errors from `deps.readFile` do not fit the `OpenCloudError`
+* shape and propagate as promise rejections; shell callers are expected to
+* translate them if a unified error surface is required.
+*
+* @param deps - Injected ocale client, file reader, and owning universe.
+* @returns A driver indexable by `"gamePass"` in a `DriverRegistry`.
+* @throws Whatever `deps.readFile` rejects with.
+*
+* @example
+*
+* ```ts
+* import type { HttpClient } from "@bedrock-rbx/ocale";
+* import { GamePassesClient } from "@bedrock-rbx/ocale/game-passes";
+* import {
+*     asResourceKey,
+*     asRobloxAssetId,
+*     asSha256Hex,
+*     createGamePassDriver,
+* } from "@bedrock-rbx/core";
+*
+* const httpClient: HttpClient = {
+*     async request() {
+*         return {
+*             data: {
+*                 body: {
+*                     createdTimestamp: "2024-01-15T10:30:00.000Z",
+*                     description: "Grants VIP perks.",
+*                     gamePassId: 9_876_543_210,
+*                     iconAssetId: 1_122_334_455,
+*                     isForSale: true,
+*                     name: "VIP Pass",
+*                     updatedTimestamp: "2024-01-15T10:30:00.000Z",
+*                 },
+*                 headers: {},
+*                 status: 200,
+*             },
+*             success: true,
+*         };
+*     },
+* };
+*
+* const driver = createGamePassDriver({
+*     client: new GamePassesClient({
+*         apiKey: "rbx-your-key",
+*         httpClient,
+*         sleep: async () => {},
+*     }),
+*     readFile: async () => new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+*     universeId: asRobloxAssetId("1234567890"),
+* });
+*
+* return driver
+*     .create({
+*         description: "Grants VIP perks.",
+*         icon: { "en-us": "assets/vip-icon.png" },
+*         iconFileHashes: {
+*             "en-us": asSha256Hex(
+*                 "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+*             ),
+*         },
+*         key: asResourceKey("vip-pass"),
+*         kind: "gamePass",
+*         name: "VIP Pass",
+*         price: 500,
+*     })
+*     .then((result) => {
+*         expect(result.success).toBeTrue();
+*         if (result.success) {
+*             expect(result.data.outputs.assetId).toBe("9876543210");
+*         }
+*     });
+* ```
+*/
+declare function createGamePassDriver(deps: GamePassDriverDeps): ResourceDriver<"gamePass">;
+//#endregion
+//#region src/adapters/no-op-progress-adapter.d.ts
+/**
+* Build a {@link ProgressPort} that silently drops every event. Useful for
+* tests and programmatic callers who want to invoke deploy logic without
+* any rendering.
+*
+* @example
+*
+* ```ts
+* import { createNoOpProgressAdapter } from "@bedrock-rbx/core";
 *
-* When the project sets a `displayNamePrefix` (or omits it, in which case
-* prefixing defaults to enabled) and the chosen environment declares a
-* non-empty `label`, the resolver renders the configured template via
-* `renderDisplayNamePrefix` and prepends the result to `universe.displayName`
-* and every declared place `displayName`. An undeclared `displayName`, an
-* empty/absent label, or an explicit `displayNamePrefix.enabled: false` all
-* skip prefixing for the affected fields.
+* const port = createNoOpProgressAdapter();
+*
+* expect(() =>
+*     port.emit({ environment: "production", kind: "deploySuccess", resourceCount: 3 }),
+* ).not.toThrow();
+* ```
+*
+* @returns A `ProgressPort` whose `emit` method is a no-op.
+*/
+declare function createNoOpProgressAdapter(): ProgressPort;
+//#endregion
+//#region src/adapters/place-driver.d.ts
+/**
+* Dependencies of `createPlaceDriver`. `universeId` is captured at
+* construction time (matching `GamePassDriverDeps`) so each driver instance
+* is bound to a single universe; multi-universe deploys construct one driver
+* per universe. `readFile` is injected because `diff` operates on file hashes
+* while the driver is the only place that needs the raw bytes.
 *
 * @example
 *
 * ```ts
-* import { selectEnvironment } from "@bedrock-rbx/core";
-* import type { Config } from "@bedrock-rbx/core/config";
+* import type { HttpClient } from "@bedrock-rbx/ocale";
+* import { PlacesClient } from "@bedrock-rbx/ocale/places";
+* import { asRobloxAssetId, type PlaceDriverDeps } from "@bedrock-rbx/core";
 *
-* const config: Config = {
-*     environments: {
-*         production: { universe: { universeId: "999" } },
+* const httpClient: HttpClient = {
+*     async request() {
+*         return { data: { body: {}, headers: {}, status: 200 }, success: true };
 *     },
-*     state: { backend: "gist", gistId: "abc123" },
-*     universe: { voiceChatEnabled: true },
 * };
 *
-* const result = selectEnvironment(config, "production");
+* const deps: PlaceDriverDeps = {
+*     client: new PlacesClient({
+*         apiKey: "rbx-your-key",
+*         httpClient,
+*         sleep: async () => {},
+*     }),
+*     readFile: async () => new Uint8Array(),
+*     universeId: asRobloxAssetId("1234567890"),
+* };
 *
-* expect(result.success).toBeTrue();
-* if (result.success) {
-*     expect(result.data.universe?.universeId).toBe("999");
-*     expect(result.data.universe?.voiceChatEnabled).toBeTrue();
-*     expect(result.data.state?.backend).toBe("gist");
-* }
+* expect(deps.universeId).toBe("1234567890");
 * ```
-*
-* @param config - Validated project config carrying at least one
-* environment under `environments`.
-* @param environment - Environment name to project onto. Must be a key
-* of `config.environments`.
-* @returns `Ok(ResolvedConfig)` with the merged resource fields and the
-* resolved state, or `Err(SelectEnvironmentError)` describing why the
-* projection failed.
 */
-declare function selectEnvironment(config: Config, environment: string): Result$1<ResolvedConfig, SelectEnvironmentError>;
-//#endregion
-//#region src/core/state-file.d.ts
+interface PlaceDriverDeps {
+  /** Configured places client from `@bedrock-rbx/ocale/places`. */
+  readonly client: PlacesClient;
+  /** Reads place-file bytes for upload; rejections propagate out of the driver. */
+  readonly readFile: (path: string) => Promise<Uint8Array>;
+  /** Universe that owns every place this driver publishes. */
+  readonly universeId: RobloxAssetId;
+}
 /**
-* Serialize a {@link BedrockState} to the on-disk JSON representation used by
-* state-port adapters.
+* Wraps {@link PlacesClient} as a `ResourceDriver<"place">`. `create` and
+* `update` are both thin wrappers over a shared publish helper because the
+* upstream Open Cloud call is identical either way: there is no "create
+* place" endpoint (the place is user-supplied input), only "publish version".
 *
-* The on-disk shape wraps the in-memory state with a
-* `$bedrock: { version: N }` envelope so that a future breaking change to the
-* schema can be detected and rejected at parse time rather than silently
-* accepted. The top-level `version` field is not duplicated on disk.
+* Format is detected from the file extension (`.rbxl` → binary,
+* `.rbxlx` → XML); any other extension returns an `ApiError`-backed failure
+* without hitting the network.
+*
+* @param deps - Injected ocale client, file reader, and owning universe.
+* @returns A driver indexable by `"place"` in a `DriverRegistry`.
+* @throws Whatever `deps.readFile` rejects with.
 *
 * @example
 *
 * ```ts
-* import { serializeStateFile, type BedrockState } from "@bedrock-rbx/core";
+* import type { HttpClient } from "@bedrock-rbx/ocale";
+* import { PlacesClient } from "@bedrock-rbx/ocale/places";
+* import {
+*     asResourceKey,
+*     asRobloxAssetId,
+*     asSha256Hex,
+*     createPlaceDriver,
+* } from "@bedrock-rbx/core";
 *
-* const state: BedrockState = {
-*     environment: "production",
-*     resources: [],
-*     version: 1,
+* const httpClient: HttpClient = {
+*     async request() {
+*         return {
+*             data: { body: { versionNumber: 1 }, headers: {}, status: 200 },
+*             success: true,
+*         };
+*     },
 * };
 *
-* const wire = serializeStateFile(state);
-* expect(JSON.parse(wire)).toStrictEqual({
-*     $bedrock: { version: 1 },
-*     environment: "production",
-*     resources: [],
+* const driver = createPlaceDriver({
+*     client: new PlacesClient({
+*         apiKey: "rbx-your-key",
+*         httpClient,
+*         sleep: async () => {},
+*     }),
+*     readFile: async () =>
+*         new Uint8Array([
+*             0x3c, 0x72, 0x6f, 0x62, 0x6c, 0x6f, 0x78, 0x21, 0x89, 0xff, 0x0d, 0x0a, 0x1a,
+*             0x0a,
+*         ]),
+*     universeId: asRobloxAssetId("1234567890"),
 * });
-* ```
 *
-* @param state - The in-memory state snapshot to serialize.
-* @returns A pretty-printed JSON string ready to hand to a state adapter's write method.
+* return driver
+*     .create({
+*         description: undefined,
+*         displayName: undefined,
+*         fileHash: asSha256Hex(
+*             "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+*         ),
+*         filePath: "places/start.rbxl",
+*         key: asResourceKey("start-place"),
+*         kind: "place",
+*         placeId: asRobloxAssetId("4711"),
+*         serverSize: undefined,
+*     })
+*     .then((result) => {
+*         expect(result.success).toBeTrue();
+*         if (result.success) {
+*             expect(result.data.outputs.versionNumber).toBe(1);
+*         }
+*     });
+* ```
 */
-declare function serializeStateFile(state: BedrockState): string;
+declare function createPlaceDriver(deps: PlaceDriverDeps): ResourceDriver<"place">;
+//#endregion
+//#region src/adapters/universe-driver.d.ts
 /**
-* Parse a raw on-disk state file into a {@link BedrockState}.
+* Dependencies of `createUniverseDriver`. The driver reconciles the
+* universe singleton against both the universes endpoint and the root
+* place (for fields Roblox marks read-only on the universe, like
+* `displayName`). There is no `universeId` at construction time because
+* the universe *is* the resource the driver reconciles, so the ID rides
+* along on each `UniverseDesiredState`.
+*/
+interface UniverseDriverDeps {
+  /** Configured places client from `@bedrock-rbx/ocale/places`. */
+  readonly places: PlacesClient;
+  /** Configured universes client from `@bedrock-rbx/ocale/universes`. */
+  readonly universes: UniversesClient;
+}
+/**
+* Wraps {@link UniversesClient} as a `ResourceDriver<"universe">`. `create`
+* and `update` both delegate to a shared reconcile helper because Open
+* Cloud cannot mint universes; the user supplies an existing `universeId`
+* and bedrock adopts the universe on first apply.
 *
-* A backend that reports "no state file for this environment yet" must pass
-* `undefined`: that distinguishes a legitimate first deploy from a file that
-* exists but cannot be trusted.
+* A `NotFound` error (HTTP 404) from `UniversesClient.update` is repackaged
+* as an adoption-error `ApiError` whose message names the config key and
+* the `universeId`, so operators can tell adoption failure apart from
+* transient upstream errors. A successful response whose `rootPlaceId` is
+* absent surfaces as an `ApiError` with status 200, mirroring the
+* malformed-response guard in `GamePassDriver`.
+*
+* When `displayName` is declared, the driver routes that field through
+* `PlacesClient.update` on the root place after the universe PATCH
+* succeeds. A subsequent places failure surfaces to the caller as the
+* driver's error result without rolling back the prior universe patch,
+* so callers observing a partial failure should reconcile by
+* reapplying rather than assuming the universe-level fields are
+* unchanged.
+*
+* @param deps - Injected ocale clients (universes plus places for the
+*   read-only universe fields Roblox derives from the root place).
+* @returns A driver indexable by `"universe"` in a `DriverRegistry`.
 *
 * @example
 *
 * ```ts
-* import { parseStateFile } from "@bedrock-rbx/core";
+* import type { HttpClient } from "@bedrock-rbx/ocale";
+* import { PlacesClient } from "@bedrock-rbx/ocale/places";
+* import { UniversesClient } from "@bedrock-rbx/ocale/universes";
+* import { validUniverseBody } from "@bedrock-rbx/ocale/testing";
+* import {
+*     asRobloxAssetId,
+*     createUniverseDriver,
+*     UNIVERSE_SINGLETON_KEY,
+* } from "@bedrock-rbx/core";
 *
-* const freshStart = parseStateFile(undefined, "gist:abc123/state.production.json");
-* expect(freshStart.success).toBeTrue();
-* if (freshStart.success) {
-*     expect(freshStart.data).toBeUndefined();
-* }
-* ```
+* const universeBodyHttpClient: HttpClient = {
+*     async request() {
+*         return {
+*             data: {
+*                 body: validUniverseBody({
+*                     path: "universes/1234567890",
+*                     rootPlace: "universes/1234567890/places/4711",
+*                 }),
+*                 headers: {},
+*                 status: 200,
+*             },
+*             success: true,
+*         };
+*     },
+* };
 *
-* @param raw - Raw file contents as a string, or `undefined` when the
-* backend reports no file exists yet.
-* @param file - Adapter-specific identifier included in any `StateError`
-* surfaced during parsing.
-* @returns `Ok(undefined)` for a missing file, `Ok(state)` for a parseable
-* file, or `Err(StateError)` for anything that cannot be trusted.
+* const driver = createUniverseDriver({
+*     places: new PlacesClient({
+*         apiKey: "rbx-your-key",
+*         httpClient: universeBodyHttpClient,
+*         sleep: async () => {},
+*     }),
+*     universes: new UniversesClient({
+*         apiKey: "rbx-your-key",
+*         httpClient: universeBodyHttpClient,
+*         sleep: async () => {},
+*     }),
+* });
+*
+* return driver
+*     .create({
+*         consoleEnabled: undefined,
+*         desktopEnabled: true,
+*         displayName: undefined,
+*         key: UNIVERSE_SINGLETON_KEY,
+*         kind: "universe",
+*         mobileEnabled: undefined,
+*         privateServerPriceRobux: undefined,
+*         tabletEnabled: undefined,
+*         universeId: asRobloxAssetId("1234567890"),
+*         voiceChatEnabled: true,
+*         vrEnabled: undefined,
+*     })
+*     .then((result) => {
+*         expect(result.success).toBeTrue();
+*         if (result.success) {
+*             expect(result.data.outputs.rootPlaceId).toBe("4711");
+*         }
+*     });
+* ```
 */
-declare function parseStateFile(raw: string | undefined, file: string): Result$1<BedrockState | undefined, StateError>;
+declare function createUniverseDriver(deps: UniverseDriverDeps): ResourceDriver<"universe">;
 //#endregion
-//#region src/core/validate-plan.d.ts
+//#region src/cli/clack-port.d.ts
 /**
-* Plan-time invariant check that runs after `buildDesired` and before
-* `diff`. Walks paired `(kind, key)` entries and dispatches to each
-* kind module's optional `assertReconcilable` hook so kind-specific
-* rejections (e.g. Removing a developer-product icon, which the upstream
-* API has no documented unset path for) surface as typed errors before
-* `diff` runs and before any apply-side driver I/O is attempted.
-*
-* Pure and synchronous. Current-only entries (no matching desired) are
-* ignored: their reconciliation is `diff`'s concern, not this seam's.
-*
-* @param desired - Desired state from `buildDesired`.
-* @param current - Prior current state from the state port.
-* @returns `Ok(undefined)` when every paired entry passes its kind-level
-*   reconcilability check, or the first `Err` returned by a hook.
+* Construct a `ClackPort` whose methods delegate to `@clack/prompts`. The
+* resulting port writes to `process.stdout` via clack's defaults. Kept in
+* its own module so consumers that never need the clack-backed rendering
+* (programmatic deploys, custom adapters) do not pull `@clack/prompts`
+* into their bundle.
 *
 * @example
 *
 * ```ts
-* import { asResourceKey, asRobloxAssetId, asSha256Hex, validatePlan } from "@bedrock-rbx/core";
+* import { createClackPort } from "@bedrock-rbx/core";
 *
-* const result = validatePlan(
-*     [
-*         {
-*             description: "Stocks the player up with 1,000 premium gems.",
-*             isRegionalPricingEnabled: undefined,
-*             key: asResourceKey("gem-pack"),
-*             kind: "developerProduct",
-*             name: "Gem Pack",
-*             price: undefined,
-*             storePageEnabled: undefined,
-*         },
-*     ],
-*     [
-*         {
-*             description: "Stocks the player up with 1,000 premium gems.",
-*             icon: { "en-us": "assets/gem-pack.png" },
-*             iconFileHashes: {
-*                 "en-us": asSha256Hex(
-*                     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-*                 ),
-*             },
-*             isRegionalPricingEnabled: undefined,
-*             key: asResourceKey("gem-pack"),
-*             kind: "developerProduct",
-*             name: "Gem Pack",
-*             outputs: { productId: asRobloxAssetId("9876543210") },
-*             price: undefined,
-*             storePageEnabled: undefined,
-*         },
-*     ],
-* );
+* const port = createClackPort();
 *
-* expect(result.success).toBeFalse();
-* if (!result.success) {
-*     expect(result.err.kind).toBe("iconRemovalRejected");
-* }
+* expect(typeof port.logSuccess).toBe("function");
 * ```
+*
+* @returns A port whose six methods each invoke the matching clack helper.
 */
-declare function validatePlan(desired: ReadonlyArray<ResourceDesiredState>, current: ReadonlyArray<ResourceCurrentState>): Result$1<undefined, BuildDesiredError>;
+declare function createClackPort(): ClackPort;
 //#endregion
-//#region src/shell/apply-ops.d.ts
+//#region src/core/derive-price-fields.d.ts
 /**
-* Failure surfaced by `applyOps` when an operation cannot be applied.
-* Plain-data discriminated union; narrow on `kind`, do not `instanceof` it.
+* Wire-shape pricing fragment produced by {@link derivePriceFields}: the
+* `isForSale` flag and an optional numeric `price`. Mirrors the multipart
+* fields the Open Cloud `developer-products` create and update endpoints
+* accept for setting Robux pricing.
+*/
+interface PriceFields {
+  /** Whether the developer product should be purchasable. */
+  readonly isForSale: boolean;
+  /** Default price in Robux; absent when the product is off-sale. */
+  readonly price?: number;
+}
+/**
+* Translate a Mantle-style optional price into the Open Cloud wire shape.
 *
-* `appliedSoFar` carries the driver outputs from operations that succeeded
-* before the failing one, in dispatched order. Callers persist this so a
-* follow-up reconcile does not duplicate Roblox-side resources that have
-* already been created or updated.
+* `desired.price === undefined` (no price declared) becomes
+* `{ isForSale: false }` and the `price` key is omitted entirely. A defined
+* price (including `0`) becomes `{ isForSale: true, price }`. Both
+* `developerProduct` create and update paths share this helper so the
+* "absent ⇒ off-sale" semantics live in exactly one place.
+*
+* @param desired - Object carrying the user-declared `price`.
+* @returns The wire-shape `{ isForSale, price? }` fragment.
 *
 * @example
 *
 * ```ts
-* import { asResourceKey, type ApplyError } from "@bedrock-rbx/core";
-*
-* function describe(err: ApplyError): string {
-*     switch (err.kind) {
-*         case "driverFailure": {
-*             return `driver failed for ${err.key}: ${err.cause.message}`;
-*         }
-*         case "updateUnsupported": {
-*             return `update not supported for ${err.key}`;
-*         }
-*     }
-* }
-*
-* const err: ApplyError = {
-*     key: asResourceKey("vip-pass"),
-*     appliedSoFar: [],
-*     kind: "updateUnsupported",
-* };
+* import { derivePriceFields } from "@bedrock-rbx/core";
 *
-* expect(describe(err)).toBe("update not supported for vip-pass");
+* expect(derivePriceFields({ price: undefined })).toStrictEqual({ isForSale: false });
+* expect(derivePriceFields({ price: 250 })).toStrictEqual({ isForSale: true, price: 250 });
 * ```
 */
-type ApplyError = {
-  readonly appliedSoFar: ReadonlyArray<ResourceCurrentState>;
-  readonly cause: OpenCloudError$1;
-  readonly key: ResourceKey;
-  readonly kind: "driverFailure";
-} | {
-  readonly appliedSoFar: ReadonlyArray<ResourceCurrentState>;
-  readonly key: ResourceKey;
-  readonly kind: "updateUnsupported";
-};
+declare function derivePriceFields(desired: {
+  readonly price: number | undefined;
+}): PriceFields;
+//#endregion
+//#region src/core/diff.d.ts
 /**
-* Dispatch each reconciliation operation to the matching resource driver
-* with first-fail semantics: on the first `Err` (driver failure or
-* `updateUnsupported`), the remaining operations are skipped and the error
-* is returned verbatim.
+* Computes the operations required to reconcile `current` state with `desired`
+* state. Pure and synchronous: no I/O, no side effects, no `Result` wrapper.
 *
-* Behaviour:
-* - `create` operations are routed to `registry[op.desired.kind].create`.
-* - `update` operations are routed to `registry[op.desired.kind].update`
-*   when the driver exposes it; otherwise they short-circuit to an
-*   `updateUnsupported` Err without invoking the driver.
-* - `noop` operations are skipped entirely (no I/O, no dispatch).
+* Each entry in `desired` is matched to `current` by `(kind, key)`: resources
+* are uniquely identified by that pair, so a `place` and a `universe` keyed
+* `"main"` are independent slots. A `(kind, key)` pair present only in
+* `desired` produces a `create` op; a pair present in both produces an
+* `update` op if any declared field differs or a `noop` op if every field
+* matches.
 *
-* On success the returned array carries the driver outputs for every
-* non-noop op, in dispatched order. Noops are not represented; callers
-* needing a full post-apply snapshot merge with the pre-apply current
-* state keyed by `ResourceKey`.
+* Ops appear in the order their desired entries appear in the input array so
+* callers can rely on declaration order when logging or applying ops.
+*
+* @param desired - Declared desired state from user config, already normalized
+*   (file hashes computed, nullable wire values mapped to `undefined`).
+* @param current - Last-known live state from the state file.
+* @returns Operations to reconcile the two snapshots.
 *
-* @param ops - Reconciliation operations produced by `diff`, applied in order.
-* @param registry - Per-kind driver table; dispatch uses `op.desired.kind` as the index.
-* @returns `Ok(state)` when every operation succeeds, where `state` holds
-*   driver outputs for each non-noop op in dispatched order; or the first
-*   failure encountered.
-* @throws Whatever the dispatched driver rejects with outside its `Result`
-*   return. A driver whose injected I/O (file reads, network calls, etc.)
-*   throws will surface that rejection here rather than translating it into
-*   a `Result` failure; wrap the call site in a try/catch when drivers are
-*   not trusted to contain their own rejections.
 * @example
 *
 * ```ts
 * import {
-*     applyOps,
 *     asResourceKey,
 *     asRobloxAssetId,
 *     asSha256Hex,
-*     type DriverRegistry,
-*     type Operation,
+*     diff,
+*     type GamePassDesiredState,
+*     type ResourceCurrentState,
 * } from "@bedrock-rbx/core";
 *
-* const registry: DriverRegistry = {
-*     gamePass: {
-*         async create(desired) {
-*             return {
-*                 data: {
-*                     ...desired,
-*                     outputs: {
-*                         assetId: asRobloxAssetId("9876543210"),
-*                         iconAssetIds: { "en-us": asRobloxAssetId("1122334455") },
-*                     },
-*                 },
-*                 success: true,
-*             };
-*         },
-*     },
-*     place: {
-*         async create(desired) {
-*             return {
-*                 data: { ...desired, outputs: { versionNumber: 1 } },
-*                 success: true,
-*             };
-*         },
-*     },
-*     universe: {
-*         async create(desired) {
-*             return {
-*                 data: { ...desired, outputs: { rootPlaceId: asRobloxAssetId("4711") } },
-*                 success: true,
-*             };
-*         },
-*     },
-*     developerProduct: {
-*         async create(desired) {
-*             return {
-*                 data: {
-*                     ...desired,
-*                     outputs: { productId: asRobloxAssetId("8172635495") },
-*                 },
-*                 success: true,
-*             };
-*         },
-*     },
+* const hash = asSha256Hex(
+*     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+* );
+*
+* const unchanged: GamePassDesiredState = {
+*     description: "Grants VIP perks.",
+*     icon: { "en-us": "assets/vip-icon.png" },
+*     iconFileHashes: { "en-us": hash },
+*     key: asResourceKey("vip-pass"),
+*     kind: "gamePass",
+*     name: "VIP Pass",
+*     price: 500,
+* };
+* const drifted: GamePassDesiredState = {
+*     ...unchanged,
+*     key: asResourceKey("legend-pass"),
+*     name: "Legend Pass (renamed)",
+* };
+* const fresh: GamePassDesiredState = {
+*     ...unchanged,
+*     key: asResourceKey("rookie-pass"),
+*     name: "Rookie Pass",
 * };
 *
-* const ops: ReadonlyArray<Operation> = [
+* const current: ReadonlyArray<ResourceCurrentState> = [
 *     {
-*         key: asResourceKey("vip-pass"),
-*         type: "create",
-*         desired: {
-*             key: asResourceKey("vip-pass"),
-*             name: "VIP Pass",
-*             description: "Grants VIP perks.",
-*             icon: { "en-us": "assets/vip-icon.png" },
-*             iconFileHashes: {
-*                 "en-us": asSha256Hex(
-*                     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-*                 ),
-*             },
-*             kind: "gamePass",
-*             price: 500,
+*         ...unchanged,
+*         outputs: {
+*             assetId: asRobloxAssetId("111"),
+*             iconAssetIds: { "en-us": asRobloxAssetId("222") },
+*         },
+*     },
+*     {
+*         ...drifted,
+*         name: "Legend Pass",
+*         outputs: {
+*             assetId: asRobloxAssetId("333"),
+*             iconAssetIds: { "en-us": asRobloxAssetId("444") },
 *         },
 *     },
 * ];
 *
-* return applyOps(ops, registry).then((result) => {
-*     expect(result.success).toBe(true);
-*     expect(result.success && result.data).toHaveLength(1);
-* });
+* const ops = diff([unchanged, drifted, fresh], current);
+*
+* expect(ops.map((op) => op.type)).toEqual(["noop", "update", "create"]);
 * ```
 */
-declare function applyOps(ops: ReadonlyArray<Operation>, registry: DriverRegistry): Promise<Result$1<ReadonlyArray<ResourceCurrentState>, ApplyError>>;
+declare function diff(desired: ReadonlyArray<ResourceDesiredState>, current: ReadonlyArray<ResourceCurrentState>): ReadonlyArray<Operation>;
 //#endregion
-//#region src/shell/build-state-port.d.ts
-/**
-* Failure surfaced when a default-constructed adapter cannot find a
-* required environment variable. The deploy boundary wraps this in a
-* `DeployError` so the caller sees a typed Result instead of an
-* exception or a confusing downstream HTTP error.
-*/
-interface MissingCredentialError {
-  /** Literal discriminator for narrowing. */
-  readonly kind: "missingCredential";
-  /** Whether the credential was needed for the state backend or the driver registry. */
-  readonly purpose: "registry" | "stateBackend";
-  /** Environment variable name the default-construction path tried to read. */
-  readonly variable: string;
-}
+//#region src/core/display-name-prefix.d.ts
 /**
-* Failure surfaced when the dispatch helper sees a `state.backend` value
-* it does not recognize. The hint points at `opts.statePort` so the
-* caller can pass a custom adapter as an escape hatch.
+* Default template applied when a project enables display-name prefixing
+* without supplying its own `displayNamePrefix.format`. Yields outputs
+* like `[STAGING] ` for an environment whose `label` is `"staging"`.
 */
-interface UnsupportedBackendError {
-  /** Backend name read from `state.backend`. */
-  readonly backend: string;
-  /** Suggested escape hatch routed back to the caller. */
-  readonly hint: string;
-  /** Literal discriminator for narrowing. */
-  readonly kind: "unsupportedBackend";
-}
-/** Inputs for {@link buildStatePort}. */
-interface BuildStatePortDeps {
-  /** Optional `fetch` seam plumbed through to the gist adapter for tests. */
-  readonly fetch?: GistFetch | undefined;
-  /** Reads an environment variable; injected so tests stay free of `process.env`. */
-  readonly getEnv: (name: string) => string | undefined;
-  /** Resolved state configuration for the target environment. */
-  readonly stateConfig: StateConfig;
-}
+declare const DEFAULT_PREFIX_FORMAT = "[{LABEL}] ";
 /**
-* Construct a `StatePort` from a resolved `StateConfig`. Dispatches on
-* `stateConfig.backend` to the matching builtin adapter; reads the
-* required credential from `getEnv` and surfaces `missingCredential` or
-* `unsupportedBackend` as typed Results.
+* Render the prefix that selectEnvironment prepends to declared display
+* names when a project enables `displayNamePrefix`. The template
+* recognizes three placeholders:
+*
+* - `{label}`: label as written.
+* - `{LABEL}`: upper-cased label.
+* - `{Label}`: capitalized label (first character upper, rest as written).
+*
+* Other characters in the template flow through verbatim.
+*
+* @param label - Environment label declared on `EnvironmentEntry.label`.
+* @param format - Template string. Falls back to
+*   {@link DEFAULT_PREFIX_FORMAT} when omitted.
+* @returns The rendered prefix string.
 *
 * @example
 *
 * ```ts
-* import { buildStatePort } from "@bedrock-rbx/core";
-*
-* const port = buildStatePort({
-*     fetch: async () =>
-*         new Response(JSON.stringify({ files: {} }), { status: 200 }),
-*     getEnv: (name) => (name === "GITHUB_TOKEN" ? "ghp_example" : undefined),
-*     stateConfig: { backend: "gist", gistId: "abc123" },
-* });
+* import { renderDisplayNamePrefix } from "@bedrock-rbx/core";
 *
-* expect(port.success).toBeTrue();
+* expect(renderDisplayNamePrefix("staging")).toBe("[STAGING] ");
+* expect(renderDisplayNamePrefix("staging", "{Label}: ")).toBe("Staging: ");
+* expect(renderDisplayNamePrefix("dev", "{LABEL}-{label}")).toBe("DEV-dev");
 * ```
-*
-* @param deps - Resolved state config plus credential-injection seams.
-* @returns A `StatePort` on success, or a typed Err describing the
-* missing credential or the unsupported backend.
 */
-declare function buildStatePort(deps: BuildStatePortDeps): Result$1<StatePort, MissingCredentialError | UnsupportedBackendError>;
+declare function renderDisplayNamePrefix(label: string, format?: string): string;
 //#endregion
-//#region src/shell/build-default-registry.d.ts
-/**
-* Failure surfaced when default-constructing a registry needs a config
-* field that is not present. The deploy boundary wraps this in a
-* `DeployError` so the caller sees a typed Result instead of a downstream
-* driver error.
-*/
-interface RegistryConfigError {
-  /** Suggested fix routed back to the caller. */
-  readonly hint: string;
-  /** Literal discriminator for narrowing. */
-  readonly kind: "registryConfigMissing";
-  /** Which config field was missing. */
-  readonly missing: "universeId";
-}
-/** Inputs for {@link buildDefaultRegistry}. */
-interface BuildDefaultRegistryDeps {
-  /** Resolved project config; supplies `universe.universeId` and is read for nothing else. */
-  readonly config: ResolvedConfig;
-  /** Reads an environment variable; injected so tests stay free of `process.env`. */
-  readonly getEnv: (name: string) => string | undefined;
-  /** Reader plumbed into kind-specific drivers that ingest file bytes. */
-  readonly readFile: (path: string) => Promise<Uint8Array>;
-}
+//#region src/core/environment.d.ts
 /**
-* Construct the default `DriverRegistry` from `config.universe.universeId`
-* and `BEDROCK_API_KEY`. Reads the API key via the injected `getEnv` seam
-* and surfaces `missingCredential` or `registryConfigMissing` as typed
-* Results instead of throwing.
+* Validate an environment name at a state-adapter boundary.
+*
+* Adapters that map environment names onto filesystem-like identifiers
+* (gist filenames, S3 keys) must reject names that could collide or escape
+* their storage layout. This helper accepts letters, digits, `-`, and `_`
+* only, with length between 1 and 64, and returns a `StateError` for
+* anything outside that set so the adapter can fail loudly instead of
+* silently stripping characters.
 *
 * @example
 *
 * ```ts
-* import { buildDefaultRegistry } from "@bedrock-rbx/core";
+* import { validateEnvironmentName } from "@bedrock-rbx/core";
 *
-* const registry = buildDefaultRegistry({
-*     config: {
-*         environments: { production: {} },
-*         state: { backend: "gist", gistId: "abc" },
-*         universe: { universeId: "1234567890" },
-*     },
-*     getEnv: () => "rbx-test",
-*     readFile: async () => new Uint8Array(),
-* });
+* const ok = validateEnvironmentName("production");
+* expect(ok.success).toBeTrue();
 *
-* expect(registry.success).toBeTrue();
+* const bad = validateEnvironmentName("prod/staging");
+* expect(bad.success).toBeFalse();
 * ```
 *
-* @param deps - Validated config plus credential and file-reader seams.
-* @returns A `DriverRegistry` on success, or a typed Err describing the
-* missing API key or the missing universe declaration.
+* @param environment - Raw environment name supplied by a caller.
+* @returns `Ok(environment)` when the name is safe to use, or
+* `Err(StateError)` with a descriptive reason when it is not.
 */
-declare function buildDefaultRegistry(deps: BuildDefaultRegistryDeps): Result$1<DriverRegistry, MissingCredentialError | RegistryConfigError>;
+declare function validateEnvironmentName(environment: string): Result$1<string, StateError>;
 //#endregion
-//#region src/shell/build-desired.d.ts
+//#region src/core/get-environment.d.ts
 /**
-* Layer file I/O onto a flat tagged list of resource inputs to produce
-* `ResourceDesiredState`.
+* Failure modes returned by {@link getEnvironment}.
+*/
+type GetEnvironmentError = {
+  readonly kind: "missingEnvironment";
+} | {
+  readonly kind: "multipleEnvironments";
+  readonly values: ReadonlyArray<string>;
+};
+/**
+* Resolve the deploy environment for an override script invocation.
 *
-* For each input, reads the file bytes via the injected `readFile`, computes
-* the SHA-256 hex digest, and assembles the branded desired-state record
-* that `diff` consumes. Entries are processed sequentially so the first
-* failure's attribution is deterministic.
+* Reads `--env <name>` from the supplied argv first, falls back to
+* `BEDROCK_ENVIRONMENT` from the supplied env reader. Returns
+* `missingEnvironment` when neither is present and `multipleEnvironments`
+* (with every offending value) when argv contains more than one `--env`
+* flag. Both inputs default to the running process so override scripts
+* under `.bedrock/` can call `getEnvironment()` with no arguments.
 *
-* @param inputs - Flat tagged resource inputs from `flattenConfig`.
-* @param readFile - Reads file bytes for a given path; rejection becomes a
-* `fileReadFailed` Err.
-* @returns `Ok` with the desired-state array (same length and order as
-* `inputs`), or `Err` with the first I/O failure.
+* @param argv - Argument list to scan for `--env <name>` flags. Defaults to
+* `process.argv.slice(2)` when omitted.
+* @param readEnvironment - Reads an environment variable; consulted as a
+* fallback when no `--env` flag is present. Defaults to a `process.env`
+* reader when omitted.
+* @returns `Ok(environment)` on success, `Err(GetEnvironmentError)` otherwise.
 * @example
 *
 * ```ts
-* import { asResourceKey, buildDesired } from "@bedrock-rbx/core";
+* import { getEnvironment } from "@bedrock-rbx/core";
 *
-* async function readFile(): Promise<Uint8Array> {
-*     return new Uint8Array([1, 2, 3]);
-* }
+* const result = getEnvironment(["--env", "production"], () => undefined);
 *
-* return buildDesired(
-*     [
-*         {
-*             description: "Grants VIP perks.",
-*             icon: { "en-us": "assets/vip-icon.png" },
-*             key: asResourceKey("vip-pass"),
-*             kind: "gamePass",
-*             name: "VIP Pass",
-*             price: 500,
-*         },
-*     ],
-*     readFile,
-* ).then((result) => {
-*     expect(result.success).toBeTrue();
-*     if (result.success) {
-*         expect(result.data).toHaveLength(1);
-*         expect(result.data[0]!.kind).toBe("gamePass");
-*     }
-* });
+* expect(result.success).toBeTrue();
+* if (result.success) {
+*     expect(result.data).toBe("production");
+* }
 * ```
 */
-declare function buildDesired(inputs: ReadonlyArray<ResourceDesiredInput>, readFile: (path: string) => Promise<Uint8Array>): Promise<Result$1<ReadonlyArray<ResourceDesiredState>, BuildDesiredError>>;
+declare function getEnvironment(argv?: ReadonlyArray<string>, readEnvironment?: (name: string) => string | undefined): Result$1<string, GetEnvironmentError>;
 //#endregion
-//#region src/shell/load-config.d.ts
-/**
-* Options for {@link loadConfig}. Matches a subset of c12's loader options;
-* additional fields land with the issues that introduce each flow.
-*/
-interface LoadConfigOptions {
-  /**
-  * Path to a specific config file to load, including its extension.
-  * Resolved relative to `cwd` when not absolute. Loaded as-is with no
-  * extension search; if the file does not exist at the given path,
-  * `loadConfig` returns `fileNotFound`. When omitted, `loadConfig`
-  * discovers `bedrock.config.{ts,js,...}` from `cwd`.
-  */
-  readonly configFile?: string;
-  /**
-  * Directory to search from. Defaults to `process.cwd()` at call time, so
-  * each invocation sees the current working directory.
-  */
-  readonly cwd?: string;
-}
+//#region src/core/icons.d.ts
 /**
-* Discover, parse, and validate the project config.
-*
-* Looks for `bedrock.config.{ts,js,mjs,cjs,yaml,yml,json}`, `.bedrockrc*`,
-* and `package.json#bedrock` starting at `options.cwd` (or the current
-* working directory). Returns a fresh, mutable `Config` on every call so
-* long-running scripts see up-to-date values.
+* Cost-gate for icon re-uploads. Returns `true` when the locally-hashed
+* desired icon differs from the hash recorded on the prior current-state
+* entry, signalling that the driver must re-upload before reconciling.
+* Returns `false` when the hashes match (no re-upload needed) and when
+* both sides report no icon.
 *
-* When the exported default is a function (sync or async), `loadConfig`
-* invokes it with an empty `ConfigContext` and awaits the result before
-* validating.
+* The signature takes hash maps directly (not whole-state) so the helper
+* is independent of any specific resource-kind shape; every icon-bearing
+* driver projects its own `iconFileHashes` and `outputs.iconFileHashes`
+* fields before calling.
 *
-* Errors return via `Result`:
-* - `fileNotFound` - no config file was discovered under the search path.
-* - `parseFailed` - a config file was found but could not be parsed (for
-*   example, malformed YAML or JSON).
-* - `validationFailed` - a file was found and parsed, but its content did
-*   not satisfy the runtime schema.
-* - `configFunctionFailed` - a function-form config threw or its returned
-*   promise rejected while being invoked.
+* @param currentHashes - Hashes recorded on the prior current-state entry.
+* @param desiredHashes - Hashes layered onto the desired-state entry by
+*   `normalize` from the local icon file's bytes.
+* @returns `true` when the driver should re-upload the icon.
 *
-* @param options - Loader options.
-* @returns `Ok` with the validated `Config`, or `Err` with a `ConfigError`.
 * @example
 *
 * ```ts
-* import { loadConfig } from "@bedrock-rbx/core";
+* import { asSha256Hex, shouldReuploadIcon } from "@bedrock-rbx/core";
 *
-* return loadConfig({
-*     configFile: "bedrock.staging.config.yaml",
-*     cwd: "/path/that/does/not/have/a/config",
-* }).then((result) => {
-*     expect(result.success).toBeFalse();
-*     if (!result.success) {
-*         expect(result.err.kind).toBe("fileNotFound");
-*     }
-* });
+* const previous = asSha256Hex(
+*     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+* );
+* const fresh = asSha256Hex(
+*     "2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881",
+* );
+*
+* expect(shouldReuploadIcon({ "en-us": previous }, { "en-us": previous })).toBe(false);
+* expect(shouldReuploadIcon({ "en-us": previous }, { "en-us": fresh })).toBe(true);
 * ```
 */
-declare function loadConfig(options?: LoadConfigOptions): Promise<Result$1<Config, ConfigError>>;
+declare function shouldReuploadIcon(currentHashes: Record<"en-us", Sha256Hex> | undefined, desiredHashes: Record<"en-us", Sha256Hex> | undefined): boolean;
 //#endregion
-//#region src/shell/deploy.d.ts
+//#region src/core/kinds/index.d.ts
 /**
-* Inputs for `deploy`. Every field except `environment` is optional;
-* omitted dependencies are default-constructed from the project config
-* and the environment variables `GITHUB_TOKEN` and `BEDROCK_API_KEY`.
+* Default {@link KindRegistry} composing every resource kind bedrock ships
+* out of the box. Iteration order (`gamePass`, `place`, `universe`,
+* `developerProduct`) matches the order `flattenConfig` emits entries
+* today, preserving the observable order of generated operations.
+*
+* @example
+*
+* ```ts
+* import { defaultKindRegistry } from "@bedrock-rbx/core";
+*
+* expect(defaultKindRegistry.gamePass.kind).toBe("gamePass");
+* expect(defaultKindRegistry.place.kind).toBe("place");
+* expect(defaultKindRegistry.universe.kind).toBe("universe");
+* expect(defaultKindRegistry.developerProduct.kind).toBe("developerProduct");
+* ```
 */
-interface DeployOptions {
-  /** Pre-loaded, optionally-mutated project config. Omit to call `loadConfig()` automatically. */
-  readonly config?: Config;
-  /** Environment name; threaded into `StatePort.read` and the persisted snapshot. */
-  readonly environment: string;
-  /** `fetch` override plumbed into the default-constructed gist adapter when `statePort` is omitted. */
-  readonly fetch?: GistFetch;
-  /** Reads an environment variable; defaults to `(name) => process.env[name]`. */
-  readonly getEnv?: (name: string) => string | undefined;
-  /** Loader invoked when `config` is omitted; defaults to `loadConfig` from this package. */
-  readonly loadConfig?: (options?: LoadConfigOptions) => Promise<Result$1<Config, ConfigError>>;
-  /** Reads file bytes for resources that have file-backed inputs. Defaults to `node:fs/promises.readFile`. */
-  readonly readFile?: (path: string) => Promise<Uint8Array>;
-  /** Per-kind driver table consulted for create / update dispatch. Default-constructed from `BEDROCK_API_KEY` when omitted. */
-  readonly registry?: DriverRegistry;
-  /** Backend used to read the prior snapshot and persist the new one. Default-constructed from `config.state` and `GITHUB_TOKEN` when omitted. */
-  readonly statePort?: StatePort;
-}
+declare const defaultKindRegistry: KindRegistry;
+//#endregion
+//#region src/core/state-file.d.ts
 /**
-* Failure surfaced by `deploy`. Stage-tagged so callers can branch on
-* `kind` to distinguish reconciliation failures (`stateReadFailed`,
-* `applyFailed`, ...) from default-construction failures
-* (`configLoadFailed`, `stateNotConfigured`, `unknownEnvironment`,
-* `incompletePlaceEntry`, `incompleteUniverseEntry`, `missingCredential`,
-* `unsupportedBackend`, `registryConfigMissing`).
+* Serialize a {@link BedrockState} to the on-disk JSON representation used by
+* state-port adapters.
+*
+* The on-disk shape wraps the in-memory state with a
+* `$bedrock: { version: N }` envelope so that a future breaking change to the
+* schema can be detected and rejected at parse time rather than silently
+* accepted. The top-level `version` field is not duplicated on disk.
+*
+* @example
+*
+* ```ts
+* import { serializeStateFile, type BedrockState } from "@bedrock-rbx/core";
+*
+* const state: BedrockState = {
+*     environment: "production",
+*     resources: [],
+*     version: 1,
+* };
+*
+* const wire = serializeStateFile(state);
+* expect(JSON.parse(wire)).toStrictEqual({
+*     $bedrock: { version: 1 },
+*     environment: "production",
+*     resources: [],
+* });
+* ```
+*
+* @param state - The in-memory state snapshot to serialize.
+* @returns A pretty-printed JSON string ready to hand to a state adapter's write method.
 */
-type DeployError = IncompletePlaceEntryError | IncompleteUniverseEntryError | MissingCredentialError | RegistryConfigError | StateNotConfiguredError | UnknownEnvironmentError | UnsupportedBackendError | {
-  readonly cause: ApplyError;
-  readonly kind: "applyFailed";
-} | {
-  readonly cause: BuildDesiredError;
-  readonly kind: "buildDesiredFailed";
-} | {
-  readonly cause: ConfigError;
-  readonly kind: "configLoadFailed";
-} | {
-  readonly cause: StateError;
-  readonly kind: "stateReadFailed";
-} | {
-  readonly cause: StateError;
-  readonly kind: "stateWriteFailed";
-  readonly unsavedState: BedrockState;
-};
+declare function serializeStateFile(state: BedrockState): string;
 /**
-* Run a full reconcile end-to-end. Default-constructs missing deps from
-* the project config and the environment variables `GITHUB_TOKEN` and
-* `BEDROCK_API_KEY`; never reads `process.env` when `statePort`,
-* `registry`, and `config` are all supplied explicitly.
+* Parse a raw on-disk state file into a {@link BedrockState}.
+*
+* A backend that reports "no state file for this environment yet" must pass
+* `undefined`: that distinguishes a legitimate first deploy from a file that
+* exists but cannot be trusted.
 *
-* @param options - Target environment plus optional overrides.
-* @returns The persisted `BedrockState` on success, or a stage-tagged
-*   `DeployError` on failure.
 * @example
 *
 * ```ts
-* import { deploy } from "@bedrock-rbx/core";
+* import { parseStateFile } from "@bedrock-rbx/core";
 *
-* return deploy({ environment: "production" }).then((result) => {
-*     expect(result.success).toBeFalse();
-*     if (!result.success) {
-*         expect(["configLoadFailed", "stateNotConfigured"]).toContain(result.err.kind);
-*     }
-* });
+* const freshStart = parseStateFile(undefined, "gist:abc123/state.production.json");
+* expect(freshStart.success).toBeTrue();
+* if (freshStart.success) {
+*     expect(freshStart.data).toBeUndefined();
+* }
 * ```
 *
+* @param raw - Raw file contents as a string, or `undefined` when the
+* backend reports no file exists yet.
+* @param file - Adapter-specific identifier included in any `StateError`
+* surfaced during parsing.
+* @returns `Ok(undefined)` for a missing file, `Ok(state)` for a parseable
+* file, or `Err(StateError)` for anything that cannot be trusted.
+*/
+declare function parseStateFile(raw: string | undefined, file: string): Result$1<BedrockState | undefined, StateError>;
+//#endregion
+//#region src/core/validate-plan.d.ts
+/**
+* Plan-time invariant check that runs after `buildDesired` and before
+* `diff`. Walks paired `(kind, key)` entries and dispatches to each
+* kind module's optional `assertReconcilable` hook so kind-specific
+* rejections (e.g. Removing a developer-product icon, which the upstream
+* API has no documented unset path for) surface as typed errors before
+* `diff` runs and before any apply-side driver I/O is attempted.
+*
+* Pure and synchronous. Current-only entries (no matching desired) are
+* ignored: their reconciliation is `diff`'s concern, not this seam's.
+*
+* @param desired - Desired state from `buildDesired`.
+* @param current - Prior current state from the state port.
+* @returns `Ok(undefined)` when every paired entry passes its kind-level
+*   reconcilability check, or the first `Err` returned by a hook.
+*
 * @example
 *
 * ```ts
-* import { deploy, type BedrockState, type DriverRegistry, type StatePort } from "@bedrock-rbx/core";
+* import { asResourceKey, asRobloxAssetId, asSha256Hex, validatePlan } from "@bedrock-rbx/core";
 *
-* const store = new Map<string, BedrockState>();
-* const statePort: StatePort = {
-*     async read(environment) {
-*         return { data: store.get(environment), success: true };
-*     },
-*     async write(state) {
-*         store.set(state.environment, state);
-*         return { data: undefined, success: true };
-*     },
-* };
-* const registry: DriverRegistry = {
-*     developerProduct: {
-*         create: async () => { throw new Error("unreachable: empty config"); },
-*     },
-*     gamePass: { create: async () => { throw new Error("unreachable: empty config"); } },
-*     place: { create: async () => { throw new Error("unreachable: empty config"); } },
-*     universe: { create: async () => { throw new Error("unreachable: empty config"); } },
-* };
+* const result = validatePlan(
+*     [
+*         {
+*             description: "Stocks the player up with 1,000 premium gems.",
+*             isRegionalPricingEnabled: undefined,
+*             key: asResourceKey("gem-pack"),
+*             kind: "developerProduct",
+*             name: "Gem Pack",
+*             price: undefined,
+*             storePageEnabled: undefined,
+*         },
+*     ],
+*     [
+*         {
+*             description: "Stocks the player up with 1,000 premium gems.",
+*             icon: { "en-us": "assets/gem-pack.png" },
+*             iconFileHashes: {
+*                 "en-us": asSha256Hex(
+*                     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+*                 ),
+*             },
+*             isRegionalPricingEnabled: undefined,
+*             key: asResourceKey("gem-pack"),
+*             kind: "developerProduct",
+*             name: "Gem Pack",
+*             outputs: { productId: asRobloxAssetId("9876543210") },
+*             price: undefined,
+*             storePageEnabled: undefined,
+*         },
+*     ],
+* );
 *
-* return deploy({
-*     config: {
-*         environments: { production: {} },
-*         state: { backend: "gist", gistId: "abc" },
-*         passes: {},
-*     },
-*     environment: "production",
-*     registry,
-*     statePort,
-* }).then((result) => {
-*     expect(result.success).toBeTrue();
-*     if (result.success) {
-*         expect(result.data.environment).toBe("production");
-*         expect(result.data.resources).toBeEmpty();
-*     }
-* });
+* expect(result.success).toBeFalse();
+* if (!result.success) {
+*     expect(result.err.kind).toBe("iconRemovalRejected");
+* }
 * ```
 */
-declare function deploy(options: DeployOptions): Promise<Result$1<BedrockState, DeployError>>;
+declare function validatePlan(desired: ReadonlyArray<ResourceDesiredState>, current: ReadonlyArray<ResourceCurrentState>): Result$1<undefined, BuildDesiredError>;
 //#endregion
 //#region src/shell/migrate-mantle-state.d.ts
 type ConfigFormat = "typescript" | "yaml";
@@ -3422,5 +3611,5 @@ interface MigrateMantleStateDeps {
 */
 declare function migrateMantleState(deps: MigrateMantleStateDeps): Promise<Result$1<MigrationReport, MigrateError>>;
 //#endregion
-export { type ApplyError, type BaseOperation, type BedrockState, type BuildDesiredError, type Config, type ConfigContext, type ConfigEnvironmentUniverseId, type ConfigError, type ConfigInput, type ConfigRootUniverseId, type ConfigValidationIssue, type CreateOperation, DEFAULT_PREFIX_FORMAT, type DeployError, type DeployOptions, type DeveloperProductDesiredInput, type DeveloperProductDesiredState, type DeveloperProductDriverDeps, type DeveloperProductEntry, type DeveloperProductOutputs, type DisplayNamePrefixConfig, type DriverRegistry, type EnvironmentEntry, type GamePassDesiredInput, type GamePassDesiredState, type GamePassDriverDeps, type GamePassEntry, type GamePassOutputs, type GetEnvironmentError, type GistStateAdapterDeps, type GistStateConfig, type IncompletePlaceEntryError, type IncompleteUniverseEntryError, type KindIo, type KindRegistry, type LoadConfigOptions, type MigrateError, type MigrateMantleStateDeps, type MigrationReport, type MigrationSummary, type MigrationWarning, type MissingCredentialError, type NoopOperation, OpenCloudError, type Operation, type PlaceDesiredInput, type PlaceDesiredState, type PlaceDriverDeps, type PlaceEntry, type PlaceOutputs, type PriceFields, type RegistryConfigError, type ResolvedConfig, type ResolvedPlaceEntry, type ResolvedUniverseEntry, type ResourceCurrentState, type ResourceDesiredInput, type ResourceDesiredState, type ResourceDriver, type ResourceEntryByKind, type ResourceKey, type ResourceKind, type ResourceKindModule, type ResourceOutputs, type ResourceOutputsByKind, type Result, type RobloxAssetId, SOCIAL_LINK_FIELDS, type SelectEnvironmentError, type Sha256Hex, type SocialLink, type SocialLinkField, type StateConfig, type StateError, type StateNotConfiguredError, type StatePort, type StatesByEnvironment, UNIVERSE_SINGLETON_KEY, type UniverseDesiredInput, type UniverseDesiredState, type UniverseDriverDeps, type UniverseEntry, type UniverseOutputs, type UniverseOverlayWithId, type UniverseOverlayWithoutId, type UnknownEnvironmentError, type UnsupportedBackendError, type UpdateOperation, applyOps, asResourceKey, asRobloxAssetId, asSha256Hex, buildDefaultRegistry, buildDesired, buildStatePort, createDeveloperProductDriver, createGamePassDriver, createGistStateAdapter, createPlaceDriver, createUniverseDriver, defaultKindRegistry, defineConfig, deploy, derivePriceFields, diff, flattenConfig, getEnvironment, isGistStateConfig, isResourceKey, isRobloxAssetId, isSha256Hex, loadConfig, migrateMantleState, parseStateFile, renderDisplayNamePrefix, resolveStateConfig, selectEnvironment, serializeStateFile, shouldReuploadIcon, validateConfig, validateEnvironmentName, validatePlan };
+export { type ApplyError, type BaseOperation, type BedrockState, type BuildDesiredError, type ClackPort, type ClackProgressAdapterDeps, type Config, type ConfigContext, type ConfigEnvironmentUniverseId, type ConfigError, type ConfigInput, type ConfigRootUniverseId, type ConfigValidationIssue, type CreateOperation, DEFAULT_PREFIX_FORMAT, type DeployError, type DeployFailureEvent, type DeployOptions, type DeploySuccessEvent, type DeveloperProductDesiredInput, type DeveloperProductDesiredState, type DeveloperProductDriverDeps, type DeveloperProductEntry, type DeveloperProductOutputs, type DisplayNamePrefixConfig, type DriverRegistry, type EnvironmentEntry, type GamePassDesiredInput, type GamePassDesiredState, type GamePassDriverDeps, type GamePassEntry, type GamePassOutputs, type GetEnvironmentError, type GistStateAdapterDeps, type GistStateConfig, type IncompletePlaceEntryError, type IncompleteUniverseEntryError, type KindIo, type KindRegistry, type LoadConfigOptions, type MigrateError, type MigrateMantleStateDeps, type MigrationReport, type MigrationSummary, type MigrationWarning, type MissingCredentialError, type NoopOperation, OpenCloudError, type Operation, type PlaceDesiredInput, type PlaceDesiredState, type PlaceDriverDeps, type PlaceEntry, type PlaceOutputs, type PriceFields, type ProgressEvent, type ProgressPort, type RegistryConfigError, type ResolvedConfig, type ResolvedPlaceEntry, type ResolvedUniverseEntry, type ResourceCurrentState, type ResourceDesiredInput, type ResourceDesiredState, type ResourceDriver, type ResourceEntryByKind, type ResourceKey, type ResourceKind, type ResourceKindModule, type ResourceOutputs, type ResourceOutputsByKind, type Result, type RobloxAssetId, SOCIAL_LINK_FIELDS, type SelectEnvironmentError, type Sha256Hex, type SocialLink, type SocialLinkField, type StateConfig, type StateError, type StateNotConfiguredError, type StatePort, type StatesByEnvironment, UNIVERSE_SINGLETON_KEY, type UniverseDesiredInput, type UniverseDesiredState, type UniverseDriverDeps, type UniverseEntry, type UniverseOutputs, type UniverseOverlayWithId, type UniverseOverlayWithoutId, type UnknownEnvironmentError, type UnsupportedBackendError, type UpdateOperation, applyOps, asResourceKey, asRobloxAssetId, asSha256Hex, buildDefaultRegistry, buildDesired, buildStatePort, createClackPort, createClackProgressAdapter, createDeveloperProductDriver, createGamePassDriver, createGistStateAdapter, createNoOpProgressAdapter, createPlaceDriver, createUniverseDriver, defaultKindRegistry, defineConfig, deploy, derivePriceFields, diff, flattenConfig, getEnvironment, isGistStateConfig, isResourceKey, isRobloxAssetId, isSha256Hex, loadConfig, migrateMantleState, parseStateFile, renderDisplayNamePrefix, resolveStateConfig, selectEnvironment, serializeStateFile, shouldReuploadIcon, validateConfig, validateEnvironmentName, validatePlan };
 //# sourceMappingURL=index.d.mts.map