@bedrock-rbx/core 0.1.0-beta.1

package/dist/index.d.mts

@@ -0,0 +1,3449 @@
+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-D-LAhfSJ.mjs";
+import { Type as Type$1 } from "arktype";
+import { OpenCloudError, OpenCloudError as OpenCloudError$1, Result, Result as Result$1 } from "@bedrock-rbx/ocale";
+import { DeveloperProductsClient } from "@bedrock-rbx/ocale/developer-products";
+import { GamePassesClient } from "@bedrock-rbx/ocale/game-passes";
+import { PlacesClient } from "@bedrock-rbx/ocale/places";
+import { SocialLink, SocialLink as SocialLink$1, UniversesClient } from "@bedrock-rbx/ocale/universes";
+
+//#region ../../node_modules/.pnpm/tagged-tag@1.0.0/node_modules/tagged-tag/index.d.ts
+declare const tag: unique symbol;
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.6.0/node_modules/type-fest/source/tagged.d.ts
+// eslint-disable-next-line type-fest/require-exported-types
+type TagContainer<Token> = {
+  readonly [tag]: Token;
+};
+type Tag<Token extends PropertyKey, TagMetadata> = TagContainer<{ [K in Token]: TagMetadata }>;
+/**
+Create a [tagged type](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d) that can support [multiple tags](https://github.com/sindresorhus/type-fest/issues/665) and [per-tag metadata](https://medium.com/@ethanresnick/advanced-typescript-tagged-types-improved-with-type-level-metadata-5072fc125fcf).
+
+A type returned by `Tagged` can be passed to `Tagged` again, to create a type with multiple tags.
+
+A tag's name is usually a string (and must be a string, number, or symbol), but each application of a tag can also contain an arbitrary type as its "metadata". See {@link GetTagMetadata} for examples and explanation.
+
+A type `A` returned by `Tagged` is assignable to another type `B` returned by `Tagged` if and only if:
+  - the underlying (untagged) type of `A` is assignable to the underlying type of `B`;
+	- `A` contains at least all the tags `B` has;
+	- and the metadata type for each of `A`'s tags is assignable to the metadata type of `B`'s corresponding tag.
+
+There have been several discussions about adding similar features to TypeScript. Unfortunately, nothing has (yet) moved forward:
+	- [Microsoft/TypeScript#202](https://github.com/microsoft/TypeScript/issues/202)
+	- [Microsoft/TypeScript#4895](https://github.com/microsoft/TypeScript/issues/4895)
+	- [Microsoft/TypeScript#33290](https://github.com/microsoft/TypeScript/pull/33290)
+
+@example
+```
+import type {Tagged} from 'type-fest';
+
+type AccountNumber = Tagged<number, 'AccountNumber'>;
+type AccountBalance = Tagged<number, 'AccountBalance'>;
+
+function createAccountNumber(): AccountNumber {
+	// As you can see, casting from a `number` (the underlying type being tagged) is allowed.
+	return 2 as AccountNumber;
+}
+
+declare function getMoneyForAccount(accountNumber: AccountNumber): AccountBalance;
+
+// This will compile successfully.
+getMoneyForAccount(createAccountNumber());
+
+// But this won't, because it has to be explicitly passed as an `AccountNumber` type!
+// Critically, you could not accidentally use an `AccountBalance` as an `AccountNumber`.
+// @ts-expect-error
+getMoneyForAccount(2);
+
+// You can also use tagged values like their underlying, untagged type.
+// I.e., this will compile successfully because an `AccountNumber` can be used as a regular `number`.
+// In this sense, the underlying base type is not hidden, which differentiates tagged types from opaque types in other languages.
+const accountNumber = createAccountNumber() + 2;
+```
+
+@example
+```
+import type {Tagged} from 'type-fest';
+
+// You can apply multiple tags to a type by using `Tagged` repeatedly.
+type Url = Tagged<string, 'URL'>;
+type SpecialCacheKey = Tagged<Url, 'SpecialCacheKey'>;
+
+// You can also pass a union of tag names, so this is equivalent to the above, although it doesn't give you the ability to assign distinct metadata to each tag.
+type SpecialCacheKey2 = Tagged<string, 'URL' | 'SpecialCacheKey'>;
+```
+
+@category Type
+*/
+type Tagged<Type, TagName extends PropertyKey, TagMetadata = never> = Type & Tag<TagName, TagMetadata>;
+//#endregion
+//#region src/types/ids.d.ts
+/**
+* User-supplied identifier for a resource within a config (e.g. `"vip-pass"`).
+* Stable across deploys; used to correlate desired ↔ current state.
+*/
+type ResourceKey = Tagged<string, "ResourceKey">;
+/**
+* Roblox-assigned numeric asset ID, represented as a string to avoid int64
+* precision loss in JavaScript.
+*/
+type RobloxAssetId = Tagged<string, "RobloxAssetId">;
+/**
+* Lowercase hex-encoded SHA-256 digest (exactly 64 characters drawn from
+* `0-9a-f`). Used to detect changes to file-backed resource inputs such as
+* game-pass icons without re-uploading the file.
+*/
+type Sha256Hex = Tagged<string, "Sha256Hex">;
+/**
+* Type predicate: test whether a raw string is a valid {@link ResourceKey}.
+*
+* Prefer this when the caller owns error handling (for example, constructing a
+* `Result` error in a shell-layer parser). Use {@link asResourceKey} when an
+* exception is the right failure mode.
+*
+* @example
+*
+* ```ts
+* import { isResourceKey } from "@bedrock-rbx/core";
+*
+* const valid = isResourceKey("vip-pass");
+* const invalid = isResourceKey("vip pass");
+* expect(valid).toBe(true);
+* expect(invalid).toBe(false);
+* ```
+*
+* @param raw - String to test.
+* @returns `true` when `raw` matches the ResourceKey shape; narrows `raw`.
+*/
+declare function isResourceKey(raw: string): raw is ResourceKey;
+/**
+* Validate and brand a raw string as a {@link ResourceKey}.
+*
+* Accepts non-empty strings of alphanumeric characters, hyphens, and
+* underscores (matching `/^[A-Za-z0-9_-]+$/`).
+*
+* @example
+*
+* ```ts
+* import { asResourceKey } from "@bedrock-rbx/core";
+*
+* const key = asResourceKey("vip-pass");
+*
+* let thrown: unknown;
+* try {
+*     asResourceKey("vip pass");
+* } catch (error) {
+*     thrown = error;
+* }
+*
+* expect(key).toBe("vip-pass");
+* expect(thrown).toBeInstanceOf(RangeError);
+* ```
+*
+* @param raw - Raw string to validate and brand.
+* @returns The input re-typed as a {@link ResourceKey}.
+* @throws RangeError when `raw` is empty or contains disallowed characters.
+*/
+declare function asResourceKey(raw: string): ResourceKey;
+/**
+* Type predicate: test whether a raw string is a valid {@link RobloxAssetId}.
+*
+* Prefer this when the caller owns error handling (for example, constructing a
+* `Result` error in a shell-layer parser). Use {@link asRobloxAssetId} when an
+* exception is the right failure mode.
+*
+* @example
+*
+* ```ts
+* import { isRobloxAssetId } from "@bedrock-rbx/core";
+*
+* const valid = isRobloxAssetId("12345");
+* const invalid = isRobloxAssetId("12345abc");
+* expect(valid).toBe(true);
+* expect(invalid).toBe(false);
+* ```
+*
+* @param raw - String to test.
+* @returns `true` when `raw` matches the RobloxAssetId shape; narrows `raw`.
+*/
+declare function isRobloxAssetId(raw: string): raw is RobloxAssetId;
+/**
+* Validate and brand a raw string as a {@link RobloxAssetId}.
+*
+* Accepts non-empty digit-only strings (matching `/^\d+$/`). Roblox asset IDs
+* are int64 values carried as strings because JavaScript's `number` cannot
+* represent the full int64 range.
+*
+* @example
+*
+* ```ts
+* import { asRobloxAssetId } from "@bedrock-rbx/core";
+*
+* const id = asRobloxAssetId("12345");
+*
+* let thrown: unknown;
+* try {
+*     asRobloxAssetId("12345abc");
+* } catch (error) {
+*     thrown = error;
+* }
+*
+* expect(id).toBe("12345");
+* expect(thrown).toBeInstanceOf(RangeError);
+* ```
+*
+* @param raw - Raw string to validate and brand.
+* @returns The input re-typed as a {@link RobloxAssetId}.
+* @throws RangeError when `raw` is empty or contains non-digit characters.
+*/
+declare function asRobloxAssetId(raw: string): RobloxAssetId;
+/**
+* Type predicate: test whether a raw string is a valid {@link Sha256Hex}.
+*
+* Accepts exactly 64 lowercase hexadecimal characters (matching
+* `/^[0-9a-f]{64}$/`). Prefer this when the caller owns error handling;
+* use {@link asSha256Hex} when throwing is the right failure mode.
+*
+* @example
+*
+* ```ts
+* import { isSha256Hex } from "@bedrock-rbx/core";
+*
+* const digest = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+* const valid = isSha256Hex(digest);
+* const invalid = isSha256Hex(digest.toUpperCase());
+* expect(valid).toBe(true);
+* expect(invalid).toBe(false);
+* ```
+*
+* @param raw - String to test.
+* @returns `true` when `raw` matches the Sha256Hex shape; narrows `raw`.
+*/
+declare function isSha256Hex(raw: string): raw is Sha256Hex;
+/**
+* Validate and brand a raw string as a {@link Sha256Hex}.
+*
+* Accepts exactly 64 lowercase hexadecimal characters. Uppercase hex, lengths
+* other than 64, and any non-hex character are rejected so the brand is a
+* canonical representation.
+*
+* @example
+*
+* ```ts
+* import { asSha256Hex } from "@bedrock-rbx/core";
+*
+* const digest = asSha256Hex(
+*     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+* );
+*
+* let thrown: unknown;
+* try {
+*     asSha256Hex("deadbeef");
+* } catch (error) {
+*     thrown = error;
+* }
+*
+* expect(digest).toHaveLength(64);
+* expect(thrown).toBeInstanceOf(RangeError);
+* ```
+*
+* @param raw - Raw string to validate and brand.
+* @returns The input re-typed as a {@link Sha256Hex}.
+* @throws RangeError when `raw` is not exactly 64 lowercase hex characters.
+*/
+declare function asSha256Hex(raw: string): Sha256Hex;
+//#endregion
+//#region src/core/resources.d.ts
+/**
+* Desired state for a game pass, as declared in user config.
+*
+* Each field is `readonly` because desired state is treated as an immutable
+* snapshot once normalized by `buildDesired`; downstream consumers (`diff`,
+* drivers) must not mutate it.
+*
+* @example
+*
+* ```ts
+* import { asResourceKey, asSha256Hex, type GamePassDesiredState } from "@bedrock-rbx/core";
+*
+* const pass: GamePassDesiredState = {
+*     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,
+* };
+*
+* expect(pass.kind).toBe("gamePass");
+* expect(pass.price).toBeUndefined();
+* ```
+*/
+interface GamePassDesiredState {
+  /** User-supplied key; stable across deploys; used to correlate desired with current. */
+  readonly key: ResourceKey;
+  /** User-facing game-pass name as shown on the Roblox storefront. */
+  readonly name: string;
+  /** User-facing description shown on the game-pass detail page. */
+  readonly description: string;
+  /**
+  * Locale-keyed icon paths declared on the authored config. The Roblox
+  * game-pass API is monolingual, so only the `"en-us"` icon is ever
+  * uploaded; the map shape mirrors `UniverseDesiredState.icon` for
+  * cross-kind parity.
+  */
+  readonly icon: Record<"en-us", string>;
+  /**
+  * SHA-256 digests of the local icon files keyed by the same locales as
+  * the icon map. The diff compares this map against the prior current
+  * state so the driver re-uploads only when a file's bytes change.
+  */
+  readonly iconFileHashes: Record<"en-us", Sha256Hex>;
+  /** Discriminator tag for the `ResourceDesiredState` union. */
+  readonly kind: "gamePass";
+  /**
+  * Robux price. `undefined` means off-sale (mirrors Mantle's `Option<u32>`;
+  * the state parser normalizes JSON `null` to `undefined` at the wire
+  * boundary per the project type convention).
+  */
+  readonly price: number | undefined;
+}
+/**
+* Desired state for a place, the `.rbxl` or `.rbxlx` file a universe serves
+* as one of its levels.
+*
+* `placeId` sits on desired state (rather than on outputs like
+* {@link GamePassOutputs.assetId}) because Roblox Open Cloud cannot mint
+* places; the user supplies the existing place ID per entry. `filePath` and
+* `fileHash` describe the local file the driver publishes; `buildDesired`
+* computes `fileHash` from the file bytes so `diff` can detect drift without
+* re-uploading unchanged content. `displayName`, `description`, and
+* `serverSize` are optional metadata fields routed through
+* `PlacesClient.update`; `undefined` leaves the server value untouched.
+*
+* @example
+*
+* ```ts
+* import {
+*     asResourceKey,
+*     asRobloxAssetId,
+*     asSha256Hex,
+*     type PlaceDesiredState,
+* } from "@bedrock-rbx/core";
+*
+* const place: PlaceDesiredState = {
+*     description: undefined,
+*     displayName: "Start Place",
+*     fileHash: asSha256Hex(
+*         "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+*     ),
+*     filePath: "places/start.rbxl",
+*     key: asResourceKey("start-place"),
+*     kind: "place",
+*     placeId: asRobloxAssetId("4711"),
+*     serverSize: 50,
+* };
+*
+* expect(place.kind).toBe("place");
+* expect(place.displayName).toBe("Start Place");
+* expect(place.description).toBeUndefined();
+* expect(place.serverSize).toBe(50);
+* ```
+*/
+interface PlaceDesiredState {
+  /** User-supplied key; stable across deploys; used to correlate desired with current. */
+  readonly key: ResourceKey;
+  /** User-facing place description; `undefined` leaves the server value untouched. */
+  readonly description: string | undefined;
+  /** User-facing place name; `undefined` leaves the server value untouched. */
+  readonly displayName: string | undefined;
+  /** SHA-256 hex digest of the place file, computed by `buildDesired` in shell. */
+  readonly fileHash: Sha256Hex;
+  /** Path to the `.rbxl` or `.rbxlx` file on disk, relative to the config file. */
+  readonly filePath: string;
+  /** Discriminator tag for the `ResourceDesiredState` union. */
+  readonly kind: "place";
+  /** Existing Roblox place ID; Open Cloud cannot create places, so this is an input, not an output. */
+  readonly placeId: RobloxAssetId;
+  /** Maximum players per server; positive integer. `undefined` leaves the server value untouched. */
+  readonly serverSize: number | undefined;
+}
+/**
+* Roblox-returned value produced by publishing a place version. The publish
+* endpoint does not return an asset ID (the `placeId` is supplied by the
+* caller); `versionNumber` is the only Roblox-assigned field the response
+* carries.
+*/
+interface PlaceOutputs {
+  /** Auto-incrementing version number assigned by Roblox on every publish. */
+  readonly versionNumber: number;
+}
+/**
+* Desired state for the singleton universe a config manages.
+*
+* The universe is adopted rather than provisioned: the user supplies an
+* existing `universeId` (Open Cloud cannot mint universes) and bedrock
+* reconciles the declared managed fields against it.
+*
+* Most managed fields use `T | undefined` to mean "unmanaged": the diff
+* treats `undefined` as absent and the driver omits the field from the
+* `updateMask`. The clearable fields (`privateServerPriceRobux` and each
+* social link) are additionally key-presence aware: a present key with
+* `undefined` tells the driver to clear the server value (ocale emits
+* JSON `null`), while an absent key leaves the server value untouched.
+*
+* @example
+*
+* ```ts
+* import {
+*     asRobloxAssetId,
+*     UNIVERSE_SINGLETON_KEY,
+*     type UniverseDesiredState,
+* } from "@bedrock-rbx/core";
+*
+* const universe: UniverseDesiredState = {
+*     consoleEnabled: undefined,
+*     desktopEnabled: true,
+*     discordSocialLink: { title: "Join our Discord", uri: "https://discord.gg/example" },
+*     displayName: "Fun Universe",
+*     key: UNIVERSE_SINGLETON_KEY,
+*     kind: "universe",
+*     mobileEnabled: false,
+*     privateServerPriceRobux: undefined,
+*     tabletEnabled: undefined,
+*     twitterSocialLink: undefined,
+*     universeId: asRobloxAssetId("1234567890"),
+*     voiceChatEnabled: true,
+*     vrEnabled: undefined,
+* };
+*
+* expect(universe.kind).toBe("universe");
+* expect("privateServerPriceRobux" in universe).toBeTrue();
+* expect(universe.discordSocialLink?.title).toBe("Join our Discord");
+* expect(universe.twitterSocialLink).toBeUndefined();
+* ```
+*/
+interface UniverseDesiredState {
+  /** Fixed singleton key (`"main"`); bedrock synthesizes it in `flattenConfig`. */
+  readonly key: ResourceKey;
+  /** Whether console players can join; `undefined` leaves the server value untouched. */
+  readonly consoleEnabled: boolean | undefined;
+  /** Whether desktop players can join; `undefined` leaves the server value untouched. */
+  readonly desktopEnabled: boolean | undefined;
+  /** Discord social link; tri-state (absent/undefined/set) — see interface JSDoc. */
+  readonly discordSocialLink?: SocialLink$1 | undefined;
+  /**
+  * Display name for the universe. `undefined` leaves the server
+  * value untouched. The driver routes declared updates through
+  * `PlacesClient.update` because the universe PATCH endpoint treats
+  * `displayName` as read-only.
+  */
+  readonly displayName: string | undefined;
+  /** Facebook social link; tri-state (absent/undefined/set) — see interface JSDoc. */
+  readonly facebookSocialLink?: SocialLink$1 | undefined;
+  /** Guilded social link; tri-state (absent/undefined/set) — see interface JSDoc. */
+  readonly guildedSocialLink?: SocialLink$1 | undefined;
+  /**
+  * Locale-keyed experience-icon paths declared on the authored config.
+  * Absent when the user did not declare an icon block.
+  */
+  readonly icon?: Record<"en-us", string>;
+  /**
+  * SHA-256 digests of the local icon files keyed by the same locales as
+  * the icon map. The diff compares this map against the prior current
+  * state so the driver re-uploads only when a file's bytes change.
+  */
+  readonly iconFileHashes?: Record<"en-us", Sha256Hex>;
+  /** Discriminator tag for the `ResourceDesiredState` union. */
+  readonly kind: "universe";
+  /** Whether mobile players can join; `undefined` leaves the server value untouched. */
+  readonly mobileEnabled: boolean | undefined;
+  /**
+  * Private-server price in Robux. A present key with `undefined`
+  * clears the server value on apply; an absent key leaves the server
+  * value untouched.
+  */
+  readonly privateServerPriceRobux?: number | undefined;
+  /** Roblox Group social link; tri-state (absent/undefined/set) — see interface JSDoc. */
+  readonly robloxGroupSocialLink?: SocialLink$1 | undefined;
+  /** Whether tablet players can join; `undefined` leaves the server value untouched. */
+  readonly tabletEnabled: boolean | undefined;
+  /** Twitch social link; tri-state (absent/undefined/set) — see interface JSDoc. */
+  readonly twitchSocialLink?: SocialLink$1 | undefined;
+  /** Twitter social link; tri-state (absent/undefined/set) — see interface JSDoc. */
+  readonly twitterSocialLink?: SocialLink$1 | undefined;
+  /** User-supplied Roblox universe ID; the universe must already exist. */
+  readonly universeId: RobloxAssetId;
+  /** Whether voice chat is enabled; `undefined` leaves the server value untouched. */
+  readonly voiceChatEnabled: boolean | undefined;
+  /** Whether VR players can join; `undefined` leaves the server value untouched. */
+  readonly vrEnabled: boolean | undefined;
+  /** YouTube social link; tri-state (absent/undefined/set) — see interface JSDoc. */
+  readonly youtubeSocialLink?: SocialLink$1 | undefined;
+}
+/**
+* Tuple of every social link field name on {@link UniverseDesiredState}.
+* Iterated by flatten, driver, and diff to handle the tri-state clearable
+* semantics uniformly across all seven fields.
+*/
+declare const SOCIAL_LINK_FIELDS: readonly ["discordSocialLink", "facebookSocialLink", "guildedSocialLink", "robloxGroupSocialLink", "twitchSocialLink", "twitterSocialLink", "youtubeSocialLink"];
+/** Union of the seven social link field names on {@link UniverseDesiredState}. */
+type SocialLinkField = (typeof SOCIAL_LINK_FIELDS)[number];
+/**
+* Desired state for a developer product, the consumable a player can buy via
+* `MarketplaceService:PromptProductPurchase`.
+*
+* @example
+*
+* ```ts
+* import { asResourceKey, type DeveloperProductDesiredState } from "@bedrock-rbx/core";
+*
+* const product: DeveloperProductDesiredState = {
+*     description: "Stocks the player up with 1,000 premium gems.",
+*     isRegionalPricingEnabled: true,
+*     key: asResourceKey("gem-pack"),
+*     kind: "developerProduct",
+*     name: "Gem Pack",
+*     price: 100,
+*     storePageEnabled: true,
+* };
+*
+* expect(product.kind).toBe("developerProduct");
+* expect(product.price).toBe(100);
+* ```
+*/
+interface DeveloperProductDesiredState {
+  /** User-supplied key; stable across deploys; used to correlate desired with current. */
+  readonly key: ResourceKey;
+  /** User-facing developer product name as shown on the storefront. */
+  readonly name: string;
+  /** User-facing description shown on the developer product detail page. */
+  readonly description: string;
+  /**
+  * Locale-keyed icon paths declared on the authored config. Absent when
+  * the user did not declare an icon block. The Roblox developer-product
+  * API is monolingual, so only the `"en-us"` icon is ever uploaded; the
+  * map shape mirrors `GamePassDesiredState.icon` for cross-kind parity.
+  */
+  readonly icon?: Record<"en-us", string>;
+  /**
+  * SHA-256 digests of the local icon files keyed by the same locales as
+  * the icon map. The diff compares this map against the prior current
+  * state so the driver re-uploads only when a file's bytes change. Absent
+  * when `icon` is absent.
+  */
+  readonly iconFileHashes?: Record<"en-us", Sha256Hex>;
+  /**
+  * Whether Roblox-managed regional pricing applies to the product.
+  * Tri-state: `undefined` means the flag is unmanaged (the diff ignores
+  * it); a defined value is propagated to Roblox on every deploy.
+  */
+  readonly isRegionalPricingEnabled: boolean | undefined;
+  /** Discriminator tag for the `ResourceDesiredState` union. */
+  readonly kind: "developerProduct";
+  /**
+  * Robux price. `undefined` means off-sale; removing the field from config
+  * takes the product off-sale on the next deploy, re-adding puts it back
+  * on sale.
+  */
+  readonly price: number | undefined;
+  /**
+  * Whether the product appears on the universe's external store page.
+  * Tri-state: `undefined` means the flag is unmanaged. A defined value is
+  * applied via a follow-up PATCH after the create POST because the v2
+  * create endpoint does not accept this field.
+  */
+  readonly storePageEnabled: boolean | undefined;
+}
+/**
+* Discriminated union of every desired-state shape Bedrock manages.
+*
+* Extend by adding new members to this union; the mapped
+* `ResourceOutputsByKind` interface then forces a matching outputs entry for
+* the new kind at compile time.
+*/
+type ResourceDesiredState = DeveloperProductDesiredState | GamePassDesiredState | PlaceDesiredState | UniverseDesiredState;
+/**
+* Roblox-returned identifiers produced by creating or updating a game pass.
+*
+* Distinct from `GamePassDesiredState.key`: the desired-state key is a
+* user-supplied handle, while these IDs are assigned by Roblox and
+* discovered only after the first successful API call.
+*/
+interface GamePassOutputs {
+  /** Primary Roblox asset ID for the game pass itself. */
+  readonly assetId: RobloxAssetId;
+  /**
+  * Locale-keyed Roblox-assigned image IDs for the game-pass icons.
+  * Mirrors `UniverseOutputs.iconAssetIds` for cross-kind shape parity;
+  * the Roblox game-pass API only ever populates the `"en-us"` entry.
+  */
+  readonly iconAssetIds: Record<"en-us", RobloxAssetId>;
+}
+/**
+* Roblox-returned identifiers produced by creating or updating a developer
+* product. `productId` is what `MarketplaceService:PromptProductPurchase`
+* accepts and is stable across re-deploys. `iconImageAssetId` is optional
+* because the wire returns it as nullable when no icon is uploaded; slice 1
+* never populates it because icon support lands in a later slice.
+*/
+interface DeveloperProductOutputs {
+  /** Roblox asset ID of the uploaded icon image; `undefined` when no icon is uploaded. */
+  readonly iconImageAssetId?: RobloxAssetId | undefined;
+  /** Roblox-assigned developer product ID; stable across re-deploys. */
+  readonly productId: RobloxAssetId;
+}
+/**
+* Roblox-returned value produced by reconciling a universe. The root place
+* ID is server-authoritative: bedrock cannot set it directly, but records it
+* so a future places slice can cross-validate the declared start place.
+*/
+interface UniverseOutputs {
+  /**
+  * Locale-keyed Roblox-assigned image IDs for the experience icons. Only
+  * populated for locales whose icon was uploaded by the universe driver;
+  * the entry persists across re-deploys until the locale is removed from
+  * the authored config.
+  */
+  readonly iconAssetIds?: Record<"en-us", RobloxAssetId>;
+  /** Server-assigned root place ID for the universe. */
+  readonly rootPlaceId: RobloxAssetId;
+}
+/**
+* String union of every discriminator tag in `ResourceDesiredState`.
+*
+* Derived from the union rather than hand-maintained so adding a new
+* `ResourceDesiredState` member automatically widens this type.
+*/
+type ResourceKind = ResourceDesiredState["kind"];
+/**
+* Per-kind outputs registry. Each `ResourceKind` must have a matching entry
+* or `ResourceOutputs<K>` is a compile error. Modelled as an interface (not a
+* type alias) so downstream packages can use declaration merging to register
+* outputs for new kinds without touching this module.
+*
+* @example
+*
+* ```ts
+* import { asRobloxAssetId, type ResourceOutputsByKind } from "@bedrock-rbx/core";
+*
+* const outputs: ResourceOutputsByKind["gamePass"] = {
+*     assetId: asRobloxAssetId("9876543210"),
+*     iconAssetIds: { "en-us": asRobloxAssetId("1122334455") },
+* };
+*
+* expect(outputs.assetId).toBe("9876543210");
+* ```
+*/
+interface ResourceOutputsByKind {
+  /** Outputs returned by the Roblox API for a developer-product resource. */
+  developerProduct: DeveloperProductOutputs;
+  /** Outputs returned by the Roblox API for a game-pass resource. */
+  gamePass: GamePassOutputs;
+  /** Outputs returned by the Roblox API for a place publish. */
+  place: PlaceOutputs;
+  /** Outputs returned by the Roblox API for a universe reconcile. */
+  universe: UniverseOutputs;
+}
+/**
+* Resolved outputs for a specific resource kind.
+*
+* @template K - The resource kind discriminator.
+*/
+type ResourceOutputs<K extends ResourceKind> = ResourceOutputsByKind[K];
+/**
+* Current (live) state for a resource kind.
+*
+* Composed from the matching desired-state shape plus a nested `outputs`
+* object carrying Roblox-assigned identifiers. The outer `K extends
+* ResourceKind` conditional distributes `K` across the union so the default
+* `ResourceCurrentState` resolves to a clean per-kind union rather than a
+* cross-product intersection of every kind's fields.
+*
+* The `outputs` sub-object stays nested (rather than flattening into the
+* top level) to mirror Mantle's `{ inputs, outputs }` state layout,
+* keeping migration copy clean.
+*
+* @template K - The resource kind discriminator. Defaults to the full
+* `ResourceKind` union for the broad form used in `ReadonlyArray`
+* collections.
+*
+* @example
+*
+* ```ts
+* import {
+*     asResourceKey,
+*     asRobloxAssetId,
+*     asSha256Hex,
+*     type ResourceCurrentState,
+* } from "@bedrock-rbx/core";
+*
+* const current: ResourceCurrentState<"gamePass"> = {
+*     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,
+* };
+*
+* expect(current.outputs.assetId).toBe("9876543210");
+* expect(current.kind).toBe("gamePass");
+* ```
+*/
+type ResourceCurrentState<K extends ResourceKind = ResourceKind> = K extends ResourceKind ? Prettify<Extract<ResourceDesiredState, {
+  kind: K;
+}> & {
+  readonly outputs: ResourceOutputs<K>;
+}> : never;
+type Prettify<T> = { readonly [K in keyof T]: T[K] };
+/**
+* Fixed stable key for the singleton universe resource. `flattenConfig`
+* stamps this onto the sole `UniverseDesiredInput` it emits; fixtures and
+* state adapters share the constant so the invariant is encoded once.
+*
+* @example
+*
+* ```ts
+* import { UNIVERSE_SINGLETON_KEY } from "@bedrock-rbx/core";
+*
+* expect(UNIVERSE_SINGLETON_KEY).toBe("main");
+* ```
+*/
+declare const UNIVERSE_SINGLETON_KEY: ResourceKey;
+//#endregion
+//#region src/ports/resource-driver.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.
+*
+* `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.
+*
+* @template K - The {@link ResourceKind} discriminator this driver handles.
+*
+* @example
+*
+* ```ts
+* import {
+*     asResourceKey,
+*     asRobloxAssetId,
+*     asSha256Hex,
+*     type ResourceDriver,
+* } from "@bedrock-rbx/core";
+*
+* const gamePassDriver: ResourceDriver<"gamePass"> = {
+*     async create(desired) {
+*         return {
+*             data: {
+*                 ...desired,
+*                 outputs: {
+*                     assetId: asRobloxAssetId("9876543210"),
+*                     iconAssetIds: { "en-us": asRobloxAssetId("1122334455") },
+*                 },
+*             },
+*             success: true,
+*         };
+*     },
+* };
+*
+* 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");
+*         }
+*     });
+* ```
+*/
+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>>;
+}
+/**
+* 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 { OpenCloudError, type DriverRegistry } 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 };
+*         },
+*     },
+* };
+*
+* expect(registry.gamePass).toBeObject();
+* ```
+*/
+type DriverRegistry = { [K in ResourceKind]: ResourceDriver<K> };
+//#endregion
+//#region src/adapters/developer-product-driver.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"),
+* };
+*
+* 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;
+}
+/**
+* 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.
+*
+* Upstream `OpenCloudError` results pass through as `Result` failures.
+*
+* @param deps - Injected ocale client and owning universe.
+* @returns A driver indexable by `"developerProduct"` in a `DriverRegistry`.
+*
+* @example
+*
+* ```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/core/state.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.
+*
+* @example
+*
+* ```ts
+* import {
+*     asResourceKey,
+*     asRobloxAssetId,
+*     asSha256Hex,
+*     type BedrockState,
+* } 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,
+* };
+*
+* expect(state.version).toBe(1);
+* expect(state.resources).toHaveLength(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;
+}
+/**
+* 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 type { StateError } from "@bedrock-rbx/core";
+*
+* const err: StateError = {
+*     file: ".bedrock/state/production.json",
+*     kind: "stateError",
+*     reason: "Corrupt JSON: unexpected token at line 1 column 5",
+* };
+*
+* expect(err.kind).toBe("stateError");
+* ```
+*/
+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/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();
+*         }
+*     });
+* ```
+*/
+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
+/**
+* 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.
+*
+* 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 { createGistStateAdapter } from "@bedrock-rbx/core";
+*
+* const port = createGistStateAdapter({
+*     fetch: async () =>
+*         new Response(JSON.stringify({ files: {} }), { status: 200 }),
+*     gistId: "abc123def456",
+*     token: "ghp_example",
+* });
+*
+* 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 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.
+*
+* @example
+*
+* ```ts
+* import type { HttpClient } from "@bedrock-rbx/ocale";
+* import { PlacesClient } from "@bedrock-rbx/ocale/places";
+* import { asRobloxAssetId, type PlaceDriverDeps } from "@bedrock-rbx/core";
+*
+* const httpClient: HttpClient = {
+*     async request() {
+*         return { data: { body: {}, headers: {}, status: 200 }, success: true };
+*     },
+* };
+*
+* const deps: PlaceDriverDeps = {
+*     client: new PlacesClient({
+*         apiKey: "rbx-your-key",
+*         httpClient,
+*         sleep: async () => {},
+*     }),
+*     readFile: async () => new Uint8Array(),
+*     universeId: asRobloxAssetId("1234567890"),
+* };
+*
+* expect(deps.universeId).toBe("1234567890");
+* ```
+*/
+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;
+}
+/**
+* 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".
+*
+* 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 type { HttpClient } from "@bedrock-rbx/ocale";
+* import { PlacesClient } from "@bedrock-rbx/ocale/places";
+* import {
+*     asResourceKey,
+*     asRobloxAssetId,
+*     asSha256Hex,
+*     createPlaceDriver,
+* } 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;
+  /** Reads icon bytes for upload; rejections propagate out of `create`/`update`. */
+  readonly readFile: (path: string) => Promise<Uint8Array>;
+  /**
+  * Configured universes client from `@bedrock-rbx/ocale/universes`. Localized
+  * experience-icon Operations are reached through `universes.icon.*`.
+  */
+  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() {
+*         return {
+*             data: {
+*                 body: validUniverseBody({
+*                     path: "universes/1234567890",
+*                     rootPlace: "universes/1234567890/places/4711",
+*                 }),
+*                 headers: {},
+*                 status: 200,
+*             },
+*             success: true,
+*         };
+*     },
+* };
+*
+* const driver = createUniverseDriver({
+*     places: new PlacesClient({
+*         apiKey: "rbx-your-key",
+*         httpClient: universeBodyHttpClient,
+*         sleep: async () => {},
+*     }),
+*     readFile: async () => new Uint8Array(),
+*     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 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;
+}
+/**
+* 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.
+*
+* @example
+*
+* ```ts
+* import { derivePriceFields } from "@bedrock-rbx/core";
+*
+* expect(derivePriceFields({ price: undefined })).toStrictEqual({ isForSale: false });
+* expect(derivePriceFields({ price: 250 })).toStrictEqual({ isForSale: true, price: 250 });
+* ```
+*/
+declare function derivePriceFields(desired: {
+  readonly price: number | undefined;
+}): PriceFields;
+//#endregion
+//#region src/core/operations.d.ts
+/**
+* Fields shared by every operation variant.
+*
+* `key` is hoisted to op-level (rather than nested under `desired` or
+* `current`) so callers can read it from any variant without first narrowing
+* on the discriminator. `applyOps` and logging both rely on this uniform
+* access pattern.
+*
+* @example
+*
+* ```ts
+* import { asResourceKey, type BaseOperation } from "@bedrock-rbx/core";
+*
+* const base: BaseOperation = { key: asResourceKey("vip-pass") };
+*
+* expect(base.key).toBe("vip-pass");
+* ```
+*/
+interface BaseOperation {
+  /** Resource key copied from the desired or current entry the op describes. */
+  readonly key: ResourceKey;
+}
+/**
+* Reconcile an absent resource: produced when a `desired` entry has no
+* matching `current` entry. The driver creates the resource and records the
+* Roblox-assigned outputs into state.
+*
+* @example
+*
+* ```ts
+* import {
+*     asResourceKey,
+*     asSha256Hex,
+*     type CreateOperation,
+* } from "@bedrock-rbx/core";
+*
+* const op: CreateOperation = {
+*     desired: {
+*         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,
+*     },
+*     key: asResourceKey("vip-pass"),
+*     type: "create",
+* };
+*
+* expect(op.type).toBe("create");
+* expect(op.desired.kind).toBe("gamePass");
+* ```
+*/
+interface CreateOperation extends BaseOperation {
+  /** Declared desired state to materialize through the driver. */
+  readonly desired: ResourceDesiredState;
+  /** Discriminator tag for the `Operation` union. */
+  readonly type: "create";
+}
+/**
+* Reconcile a drifted resource: produced when a `desired` entry differs from
+* its matching `current` entry. Both states are carried so the driver can
+* compute the minimal patch.
+*
+* @example
+*
+* ```ts
+* import {
+*     asResourceKey,
+*     asRobloxAssetId,
+*     asSha256Hex,
+*     type UpdateOperation,
+* } from "@bedrock-rbx/core";
+*
+* const op: UpdateOperation = {
+*     current: {
+*         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,
+*     },
+*     desired: {
+*         description: "Grants VIP perks plus emote.",
+*         icon: { "en-us": "assets/vip-icon.png" },
+*         iconFileHashes: {
+*             "en-us": asSha256Hex(
+*                 "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+*             ),
+*         },
+*         key: asResourceKey("vip-pass"),
+*         kind: "gamePass",
+*         name: "VIP Pass",
+*         price: 750,
+*     },
+*     key: asResourceKey("vip-pass"),
+*     type: "update",
+* };
+*
+* expect(op.type).toBe("update");
+* if (op.desired.kind === "gamePass") {
+*     expect(op.desired.price).toBe(750);
+* }
+* if (op.current.kind === "gamePass") {
+*     expect(op.current.outputs.assetId).toBe("9876543210");
+* }
+* ```
+*/
+interface UpdateOperation extends BaseOperation {
+  /** Last-known live state; the driver computes a patch against `desired`. */
+  readonly current: ResourceCurrentState;
+  /** Declared desired state to converge toward. */
+  readonly desired: ResourceDesiredState;
+  /** Discriminator tag for the `Operation` union. */
+  readonly type: "update";
+}
+/**
+* Acknowledge that a resource is already in sync: produced when a `desired`
+* entry matches its `current` entry exactly. The driver performs no I/O for
+* this variant.
+*
+* Bare by design: the operation carries only `key` and `type` because no
+* payload is needed at apply time. Callers that need the matching desired or
+* current state look it up in the snapshots passed to `diff`.
+*
+* @example
+*
+* ```ts
+* import { asResourceKey, type NoopOperation } from "@bedrock-rbx/core";
+*
+* const op: NoopOperation = {
+*     key: asResourceKey("vip-pass"),
+*     type: "noop",
+* };
+*
+* expect(op.type).toBe("noop");
+* expect(op.key).toBe("vip-pass");
+* ```
+*/
+interface NoopOperation extends BaseOperation {
+  /** Discriminator tag for the `Operation` union. */
+  readonly type: "noop";
+}
+/**
+* Discriminated union of every reconciliation step `diff` produces and
+* `applyOps` consumes. The `type` field is the discriminator (`kind` is
+* reserved for the resource discriminator in `ResourceDesiredState`).
+*
+* A `delete` variant is intentionally absent: resources present only in
+* current state (orphans) are ignored, never reconciled.
+*
+* @example
+*
+* ```ts
+* import { asResourceKey, type Operation } from "@bedrock-rbx/core";
+*
+* function describeOp(op: Operation): string {
+*     switch (op.type) {
+*         case "create": {
+*             return `create ${op.desired.kind} ${op.key}`;
+*         }
+*         case "update": {
+*             return `update ${op.desired.kind} ${op.key}`;
+*         }
+*         case "noop": {
+*             return `noop ${op.key}`;
+*         }
+*     }
+* }
+*
+* const op: Operation = {
+*     key: asResourceKey("vip-pass"),
+*     type: "noop",
+* };
+*
+* expect(describeOp(op)).toBe("noop vip-pass");
+* ```
+*/
+type Operation = CreateOperation | NoopOperation | UpdateOperation;
+//#endregion
+//#region src/core/diff.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.
+*
+* @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.
+*
+* @example
+*
+* ```ts
+* import {
+*     asResourceKey,
+*     asRobloxAssetId,
+*     asSha256Hex,
+*     diff,
+*     type GamePassDesiredState,
+*     type ResourceCurrentState,
+* } from "@bedrock-rbx/core";
+*
+* 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 current: ReadonlyArray<ResourceCurrentState> = [
+*     {
+*         ...unchanged,
+*         outputs: {
+*             assetId: asRobloxAssetId("111"),
+*             iconAssetIds: { "en-us": asRobloxAssetId("222") },
+*         },
+*     },
+*     {
+*         ...drifted,
+*         name: "Legend Pass",
+*         outputs: {
+*             assetId: asRobloxAssetId("333"),
+*             iconAssetIds: { "en-us": asRobloxAssetId("444") },
+*         },
+*     },
+* ];
+*
+* const ops = diff([unchanged, drifted, fresh], current);
+*
+* expect(ops.map((op) => op.type)).toEqual(["noop", "update", "create"]);
+* ```
+*/
+declare function diff(desired: ReadonlyArray<ResourceDesiredState>, current: ReadonlyArray<ResourceCurrentState>): ReadonlyArray<Operation>;
+//#endregion
+//#region src/core/display-name-prefix.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"`.
+*/
+declare const DEFAULT_PREFIX_FORMAT = "[{LABEL}] ";
+/**
+* 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 { renderDisplayNamePrefix } from "@bedrock-rbx/core";
+*
+* expect(renderDisplayNamePrefix("staging")).toBe("[STAGING] ");
+* expect(renderDisplayNamePrefix("staging", "{Label}: ")).toBe("Staging: ");
+* expect(renderDisplayNamePrefix("dev", "{LABEL}-{label}")).toBe("DEV-dev");
+* ```
+*/
+declare function renderDisplayNamePrefix(label: string, format?: string): string;
+//#endregion
+//#region src/core/environment.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.
+*
+* @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";
+*
+* const input: GamePassDesiredInput = {
+*     description: "Grants VIP perks.",
+*     icon: { "en-us": "assets/vip-icon.png" },
+*     key: asResourceKey("vip-pass"),
+*     kind: "gamePass",
+*     name: "VIP Pass",
+*     price: 500,
+* };
+*
+* expect(input.kind).toBe("gamePass");
+* ```
+*/
+interface GamePassDesiredInput extends Readonly<GamePassEntry> {
+  /** User-supplied handle, already validated against the `ResourceKey` brand. */
+  readonly key: ResourceKey;
+  /** Discriminator tag for the `ResourceDesiredInput` union. */
+  readonly kind: "gamePass";
+}
+/**
+* Pre-I/O place input the flattener emits. Carries the resolved place
+* fields (`filePath` from the root, `placeId` from the per-environment
+* overlay) plus the optional metadata fields and the tag discriminator and
+* the `ResourceKey`-branded key, so `buildDesired` can consume a flat
+* tagged list and layer on the SHA-256 file digest.
+*
+* @example
+*
+* ```ts
+* import { asResourceKey, asRobloxAssetId, type PlaceDesiredInput } from "@bedrock-rbx/core";
+*
+* const input: PlaceDesiredInput = {
+*     description: undefined,
+*     displayName: "Start Place",
+*     filePath: "places/start.rbxl",
+*     key: asResourceKey("start-place"),
+*     kind: "place",
+*     placeId: asRobloxAssetId("4711"),
+*     serverSize: 50,
+* };
+*
+* expect(input.kind).toBe("place");
+* expect(input.displayName).toBe("Start Place");
+* ```
+*/
+interface PlaceDesiredInput {
+  /** User-supplied handle, already validated against the `ResourceKey` brand. */
+  readonly key: ResourceKey;
+  /** User-facing place description; `undefined` leaves the server value untouched. */
+  readonly description: string | undefined;
+  /** User-facing place name; `undefined` leaves the server value untouched. */
+  readonly displayName: string | undefined;
+  /** Path to the `.rbxl` or `.rbxlx` file; read by `buildDesired`. */
+  readonly filePath: string;
+  /** Discriminator tag for the `ResourceDesiredInput` union. */
+  readonly kind: "place";
+  /** Existing Roblox place ID, validated and branded at flatten time. */
+  readonly placeId: RobloxAssetId;
+  /** Maximum players per server; `undefined` leaves the server value untouched. */
+  readonly serverSize: number | undefined;
+}
+/**
+* Pre-I/O universe input the flattener emits. Carries the fixed singleton
+* key (`"main"`) and the branded `universeId` so `buildDesired` can hand a
+* single tagged record downstream without a shape divergence for the
+* singleton kind.
+*
+* @example
+*
+* ```ts
+* import { asRobloxAssetId, UNIVERSE_SINGLETON_KEY, type UniverseDesiredInput } from "@bedrock-rbx/core";
+*
+* const input: UniverseDesiredInput = {
+*     consoleEnabled: undefined,
+*     desktopEnabled: true,
+*     displayName: undefined,
+*     key: UNIVERSE_SINGLETON_KEY,
+*     kind: "universe",
+*     mobileEnabled: undefined,
+*     tabletEnabled: undefined,
+*     universeId: asRobloxAssetId("1234567890"),
+*     voiceChatEnabled: true,
+*     vrEnabled: undefined,
+* };
+*
+* expect(input.kind).toBe("universe");
+* expect(input.key).toBe("main");
+* expect(input.desktopEnabled).toBeTrue();
+* ```
+*/
+interface UniverseDesiredInput {
+  /** Synthesized singleton key (`"main"`), already validated against the `ResourceKey` brand. */
+  readonly key: ResourceKey;
+  /** Whether console players can join; `undefined` leaves the server value untouched. */
+  readonly consoleEnabled: boolean | undefined;
+  /** Whether desktop players can join; `undefined` leaves the server value untouched. */
+  readonly desktopEnabled: boolean | undefined;
+  /** Discord social link; tri-state (absent/undefined/set) — see `UniverseDesiredState`. */
+  readonly discordSocialLink?: SocialLink$1 | undefined;
+  /**
+  * Display name for the universe. `undefined` leaves the server value
+  * untouched. The driver routes declared updates through
+  * `PlacesClient.update` because the universe PATCH endpoint treats
+  * `displayName` as read-only.
+  */
+  readonly displayName: string | undefined;
+  /** Facebook social link; tri-state (absent/undefined/set) — see `UniverseDesiredState`. */
+  readonly facebookSocialLink?: SocialLink$1 | undefined;
+  /** Guilded social link; tri-state (absent/undefined/set) — see `UniverseDesiredState`. */
+  readonly guildedSocialLink?: SocialLink$1 | undefined;
+  /**
+  * Locale-keyed experience-icon paths copied from the user-supplied
+  * `UniverseEntry`. Absent when the user did not declare an icon block.
+  */
+  readonly icon?: Record<"en-us", string>;
+  /** Discriminator tag for the `ResourceDesiredInput` union. */
+  readonly kind: "universe";
+  /** Whether mobile players can join; `undefined` leaves the server value untouched. */
+  readonly mobileEnabled: boolean | undefined;
+  /**
+  * Private-server price in Robux. A present key with `undefined`
+  * clears the server value (ocale emits JSON `null`); an absent key
+  * leaves the server value untouched.
+  */
+  readonly privateServerPriceRobux?: number | undefined;
+  /** Roblox Group social link; tri-state (absent/undefined/set) — see `UniverseDesiredState`. */
+  readonly robloxGroupSocialLink?: SocialLink$1 | undefined;
+  /** Whether tablet players can join; `undefined` leaves the server value untouched. */
+  readonly tabletEnabled: boolean | undefined;
+  /** Twitch social link; tri-state (absent/undefined/set) — see `UniverseDesiredState`. */
+  readonly twitchSocialLink?: SocialLink$1 | undefined;
+  /** Twitter social link; tri-state (absent/undefined/set) — see `UniverseDesiredState`. */
+  readonly twitterSocialLink?: SocialLink$1 | undefined;
+  /** Existing Roblox universe ID, validated and branded at flatten time. */
+  readonly universeId: RobloxAssetId;
+  /** Whether voice chat is enabled; `undefined` leaves the server value untouched. */
+  readonly voiceChatEnabled: boolean | undefined;
+  /** Whether VR players can join; `undefined` leaves the server value untouched. */
+  readonly vrEnabled: boolean | undefined;
+  /** YouTube social link; tri-state (absent/undefined/set) — see `UniverseDesiredState`. */
+  readonly youtubeSocialLink?: SocialLink$1 | undefined;
+}
+/**
+* Pre-I/O developer-product input the flattener emits. Extends the authored
+* `DeveloperProductEntry` with the tag discriminator and the
+* `ResourceKey`-branded key so `buildDesired` can consume a flat tagged
+* list.
+*
+* @example
+*
+* ```ts
+* import { asResourceKey, type DeveloperProductDesiredInput } from "@bedrock-rbx/core";
+*
+* const input: DeveloperProductDesiredInput = {
+*     description: "Stocks the player up with 1,000 premium gems.",
+*     key: asResourceKey("gem-pack"),
+*     kind: "developerProduct",
+*     name: "Gem Pack",
+* };
+*
+* expect(input.kind).toBe("developerProduct");
+* ```
+*/
+interface DeveloperProductDesiredInput extends Readonly<DeveloperProductEntry> {
+  /** User-supplied handle, already validated against the `ResourceKey` brand. */
+  readonly key: ResourceKey;
+  /** Discriminator tag for the `ResourceDesiredInput` union. */
+  readonly kind: "developerProduct";
+}
+/**
+* Flat tagged input for `buildDesired`. One member per resource kind; future
+* kinds widen this union as they land.
+*/
+type ResourceDesiredInput = DeveloperProductDesiredInput | GamePassDesiredInput | PlaceDesiredInput | UniverseDesiredInput;
+/**
+* Turn a resolved `Config` into a flat, tagged list of resource inputs.
+*
+* Pure and infallible: validation and per-environment overlay merging
+* have already happened upstream (typically via `selectEnvironment`), so
+* every invariant this function relies on is guaranteed by the input
+* shape. Entries appear in the insertion order of each collection;
+* `passes` are emitted before `places`.
+*
+* @param config - Resolved config returned by `selectEnvironment`.
+* @returns Flat tagged list ready for `buildDesired`.
+* @example
+*
+* ```ts
+* import { flattenConfig, selectEnvironment, type Config } from "@bedrock-rbx/core";
+*
+* const config: Config = {
+*     environments: {
+*         production: { places: { "start-place": { placeId: "4711" } } },
+*     },
+*     passes: {
+*         "vip-pass": {
+*             description: "Grants VIP perks.",
+*             icon: { "en-us": "assets/vip-icon.png" },
+*             name: "VIP Pass",
+*             price: 500,
+*         },
+*     },
+*     places: { "start-place": { filePath: "places/start.rbxl" } },
+* };
+*
+* const resolved = selectEnvironment(config, "production");
+* expect(resolved.success).toBeTrue();
+* if (resolved.success) {
+*     const inputs = flattenConfig(resolved.data);
+*     expect(inputs.map((input) => input.kind)).toEqual(["gamePass", "place"]);
+*     expect(inputs.map((input) => input.key)).toEqual(["vip-pass", "start-place"]);
+* }
+* ```
+*/
+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:
+*
+* - `fileReadFailed`: a kind module's `normalize` could not read a file
+*   the input declared (e.g. An icon path that is missing on disk).
+* - `iconRemovalRejected`: `validatePlan` saw a kind whose prior current
+*   state recorded an icon that the desired state no longer declares,
+*   and the kind has no documented unset path on the upstream API.
+*
+* Both variants carry the offending `key` so the CLI can attribute the
+* failure to a single resource entry.
+*
+* @example
+*
+* ```ts
+* import { asResourceKey, type BuildDesiredError } from "@bedrock-rbx/core";
+*
+* const err: BuildDesiredError = {
+*     filePath: "assets/vip-icon.png",
+*     key: asResourceKey("vip-pass"),
+*     kind: "fileReadFailed",
+*     reason: "ENOENT",
+* };
+*
+* expect(err.kind).toBe("fileReadFailed");
+* ```
+*/
+type BuildDesiredError = {
+  /** Path of the file that failed to read. */readonly filePath: string; /** ResourceKey of the input whose file failed to read. */
+  readonly key: ResourceKey; /** Literal discriminator for narrowing. */
+  readonly kind: "fileReadFailed"; /** Human-readable explanation; typically the caught error message. */
+  readonly reason: string;
+} | {
+  /** ResourceKey of the entry whose icon is being removed. */readonly key: ResourceKey; /** Literal discriminator for narrowing. */
+  readonly kind: "iconRemovalRejected"; /** Human-readable explanation naming the resource and the invariant. */
+  readonly message: string;
+};
+/**
+* I/O surface the shell injects into kind-module `normalize` calls. Carries
+* only file-reading capability today; new capabilities widen this shape
+* when a kind module needs them.
+*
+* @example
+*
+* ```ts
+* import type { KindIo } from "@bedrock-rbx/core";
+*
+* const io: KindIo = {
+*     readFile: async () => new Uint8Array([1, 2, 3]),
+* };
+*
+* expect(io.readFile).toBeFunction();
+* ```
+*/
+interface KindIo {
+  /** Reads file bytes for a given path; rejection becomes a `fileReadFailed` Err. */
+  readonly readFile: (path: string) => Promise<Uint8Array>;
+}
+/**
+* Plugin contract for a resource kind: concentrates the per-kind domain
+* surface (authored entry schema, flatten, pre-I/O normalize, drift
+* equality) behind one interface that the core `diff` and shell
+* `buildDesired` functions dispatch through at runtime. Composes with the
+* `ResourceDriver<K>` port, which stays the I/O half of the kind.
+*
+* @template K - The {@link ResourceKind} discriminator this module handles.
+*
+* @example
+*
+* ```ts
+* import { type } from "arktype";
+*
+* import { asResourceKey, asSha256Hex, type ResourceKindModule } from "@bedrock-rbx/core";
+*
+* const stubKind: ResourceKindModule<"gamePass"> = {
+*     kind: "gamePass",
+*     entrySchema: type({
+*         description: "string",
+*         icon: type({ "en-us": "string" }).onUndeclaredKey("reject"),
+*         name: "string",
+*         "price?": "number | undefined",
+*     }),
+*     flatten: () => [],
+*     normalize: async (input) => ({
+*         data: {
+*             description: input.description,
+*             icon: input.icon,
+*             iconFileHashes: {
+*                 "en-us": asSha256Hex(
+*                     "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+*                 ),
+*             },
+*             key: input.key,
+*             kind: "gamePass",
+*             name: input.name,
+*             price: input.price,
+*         },
+*         success: true,
+*     }),
+*     fieldsEqual: (desired, current) => desired.name === current.name,
+* };
+*
+* expect(stubKind.kind).toBe("gamePass");
+* ```
+*/
+interface ResourceKindModule<K extends ResourceKind> {
+  /**
+  * Optional plan-time invariant check called by `validatePlan` for every
+  * `(kind, key)` pair that exists on both sides. Surfaces kind-specific
+  * rejections (e.g. Removing a developer-product icon, which the upstream
+  * API has no documented unset path for) before `diff` runs and before
+  * any apply-side driver I/O is attempted. Kinds without plan-level
+  * invariants omit this hook.
+  */
+  readonly assertReconcilable?: (current: ResourceCurrentState<K>, desired: DesiredFor<K>) => Result$1<undefined, BuildDesiredError>;
+  /** ArkType schema for the authored entry body of this kind. */
+  readonly entrySchema: Type$1<ResourceEntryByKind[K]>;
+  /**
+  * Managed-field equality. Identity fields (`key`, `kind`, and kind-specific
+  * inputs like `placeId` or `universeId`) are excluded by the
+  * implementation; `diff` treats `true` as "no drift, emit noop".
+  */
+  fieldsEqual(desired: DesiredFor<K>, current: ResourceCurrentState<K>): boolean;
+  /**
+  * Project a resolved `Config` into a flat, tagged list of this kind's
+  * pre-I/O inputs. Pure and infallible: validation and per-environment
+  * overlay merging have already happened upstream, so every invariant
+  * this function relies on is guaranteed by the input shape.
+  */
+  flatten(config: ResolvedConfig): ReadonlyArray<InputFor<K>>;
+  /** Discriminator literal for this kind. */
+  readonly kind: K;
+  /**
+  * Layer pre-I/O work (file reads, hashing) onto an input to produce a
+  * branded desired-state record. Rejections from `io.readFile` are caught
+  * and surfaced as `fileReadFailed`.
+  */
+  normalize(input: InputFor<K>, io: KindIo): Promise<Result$1<DesiredFor<K>, BuildDesiredError>>;
+}
+/**
+* Polymorphic dispatch table keyed by {@link ResourceKind}, mapping each
+* kind to the {@link ResourceKindModule} that handles its domain surface.
+* Adding a new kind to `ResourceKind` is a compile error at `KindRegistry`
+* until a matching entry is supplied, matching how `DriverRegistry`
+* enforces the same invariant on its I/O half.
+*
+* @example
+*
+* ```ts
+* import { defaultKindRegistry, type KindRegistry } from "@bedrock-rbx/core";
+*
+* const registry: KindRegistry = defaultKindRegistry;
+* expect(registry.gamePass.kind).toBe("gamePass");
+* ```
+*/
+type KindRegistry = { [K in ResourceKind]: ResourceKindModule<K> };
+/**
+* Desired-state narrowed to a single resource kind.
+*
+* @template K - The resource-kind discriminator.
+*/
+type DesiredFor<K extends ResourceKind> = Extract<ResourceDesiredState, {
+  readonly kind: K;
+}>;
+/**
+* Flat pre-I/O input narrowed to a single resource kind.
+*
+* @template K - The resource-kind discriminator.
+*/
+type InputFor<K extends ResourceKind> = Extract<ResourceDesiredInput, {
+  readonly kind: K;
+}>;
+//#endregion
+//#region src/core/icons.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.
+*
+* @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.
+*
+* @example
+*
+* ```ts
+* import { asSha256Hex, shouldReuploadIcon } from "@bedrock-rbx/core";
+*
+* 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 shouldReuploadIcon(currentHashes: Record<"en-us", Sha256Hex> | undefined, desiredHashes: Record<"en-us", Sha256Hex> | undefined): boolean;
+//#endregion
+//#region src/core/kinds/index.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.
+*
+* @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");
+* ```
+*/
+declare const defaultKindRegistry: KindRegistry;
+//#endregion
+//#region src/core/migrate/migration-report.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`).
+*/
+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;
+}
+/**
+* Discriminated union describing one observation the migrator made about a
+* Mantle field that did not flow straight into bedrock config or state.
+*
+* - `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.
+*
+* 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`.
+*
+* - `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.
+*
+* `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).
+*
+* `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.
+*
+* `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.
+*
+* `warnings` and `summary` describe what the migrator did *not* migrate
+* verbatim, classified for triage. The skeleton emits no warnings.
+*/
+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/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;
+  /** Literal discriminator for narrowing. */
+  readonly kind: "stateNotConfigured";
+}
+/**
+* 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 { resolveStateConfig } from "@bedrock-rbx/core";
+*
+* const result = resolveStateConfig(
+*     {
+*         state: { backend: "gist", gistId: "root-gist" },
+*         environments: {
+*             production: { state: { backend: "gist", gistId: "prod-gist" } },
+*         },
+*     },
+*     "production",
+* );
+*
+* expect(result.success).toBeTrue();
+* if (result.success) {
+*     expect(result.data).toContainEntry(["gistId", "prod-gist"]);
+* }
+* ```
+*/
+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: "unknownEnvironment";
+}
+/**
+* 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 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";
+}
+/**
+* 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";
+}
+/** 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).
+*
+* 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.
+*
+* 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 }`.
+*
+* 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.
+*
+* 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.
+*
+* 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 { selectEnvironment } from "@bedrock-rbx/core";
+* import type { Config } from "@bedrock-rbx/core/config";
+*
+* const config: Config = {
+*     environments: {
+*         production: { universe: { universeId: "999" } },
+*     },
+*     state: { backend: "gist", gistId: "abc123" },
+*     universe: { voiceChatEnabled: true },
+* };
+*
+* const result = selectEnvironment(config, "production");
+*
+* 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.
+*/
+declare function selectEnvironment(config: Config, environment: string): Result$1<ResolvedConfig, SelectEnvironmentError>;
+//#endregion
+//#region src/core/state-file.d.ts
+/**
+* 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.
+*/
+declare function serializeStateFile(state: BedrockState): string;
+/**
+* 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.
+*
+* @example
+*
+* ```ts
+* import { parseStateFile } from "@bedrock-rbx/core";
+*
+* 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 { asResourceKey, asRobloxAssetId, asSha256Hex, validatePlan } 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,
+*         },
+*     ],
+* );
+*
+* expect(result.success).toBeFalse();
+* if (!result.success) {
+*     expect(result.err.kind).toBe("iconRemovalRejected");
+* }
+* ```
+*/
+declare function validatePlan(desired: ReadonlyArray<ResourceDesiredState>, current: ReadonlyArray<ResourceCurrentState>): Result$1<undefined, BuildDesiredError>;
+//#endregion
+//#region src/shell/apply-ops.d.ts
+/**
+* Failure surfaced by `applyOps` when an operation cannot be applied.
+* Plain-data discriminated union; narrow on `kind`, do not `instanceof` it.
+*
+* `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, 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",
+* };
+*
+* 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> = [
+*     {
+*         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,
+*         },
+*     },
+* ];
+*
+* return applyOps(ops, registry).then((result) => {
+*     expect(result.success).toBe(true);
+*     expect(result.success && result.data).toHaveLength(1);
+* });
+* ```
+*/
+declare function applyOps(ops: ReadonlyArray<Operation>, registry: DriverRegistry): Promise<Result$1<ReadonlyArray<ResourceCurrentState>, ApplyError>>;
+//#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;
+}
+/**
+* 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 { 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" },
+* });
+*
+* 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.
+*/
+declare function buildStatePort(deps: BuildStatePortDeps): Result$1<StatePort, MissingCredentialError | UnsupportedBackendError>;
+//#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>;
+}
+/**
+* Construct the default `DriverRegistry` from `config.universe.universeId`
+* and `ROBLOX_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 { buildDefaultRegistry } 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(),
+* });
+*
+* 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 buildDefaultRegistry(deps: BuildDefaultRegistryDeps): Result$1<DriverRegistry, MissingCredentialError | RegistryConfigError>;
+//#endregion
+//#region src/shell/build-desired.d.ts
+/**
+* Layer file I/O onto a flat tagged list of resource inputs to produce
+* `ResourceDesiredState`.
+*
+* 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 { asResourceKey, buildDesired } from "@bedrock-rbx/core";
+*
+* async function readFile(): Promise<Uint8Array> {
+*     return new Uint8Array([1, 2, 3]);
+* }
+*
+* 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 buildDesired(inputs: ReadonlyArray<ResourceDesiredInput>, readFile: (path: string) => Promise<Uint8Array>): Promise<Result$1<ReadonlyArray<ResourceDesiredState>, BuildDesiredError>>;
+//#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;
+}
+/**
+* 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 { loadConfig } 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");
+*     }
+* });
+* ```
+*/
+declare function loadConfig(options?: LoadConfigOptions): Promise<Result$1<Config, ConfigError>>;
+//#endregion
+//#region src/shell/deploy.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 `ROBLOX_API_KEY`.
+*/
+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 `ROBLOX_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;
+}
+/**
+* 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`).
+*/
+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;
+};
+/**
+* Run a full reconcile end-to-end. Default-constructs missing deps from
+* the project config and the environment variables `GITHUB_TOKEN` and
+* `ROBLOX_API_KEY`; never reads `process.env` when `statePort`,
+* `registry`, and `config` are all supplied explicitly.
+*
+* @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";
+*
+* 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();
+*     }
+* });
+* ```
+*/
+declare function deploy(options: DeployOptions): Promise<Result$1<BedrockState, DeployError>>;
+//#endregion
+//#region src/shell/migrate-mantle-state.d.ts
+type ConfigFormat = "typescript" | "yaml";
+/**
+* Inputs for `migrateMantleState`. The state file is read via
+* `readFile` (defaults to `node:fs/promises.readFile`) so callers can
+* inject in-memory fixtures from tests and the JSDoc `@example` block
+* stays self-contained.
+*
+* `configFormat` selects the output shape: `"typescript"` emits a
+* `bedrock.config.ts` with `defineConfig({...})`; `"yaml"` emits a
+* `bedrock.config.yaml` body. Both shapes round-trip through
+* `loadConfig` cleanly.
+*/
+interface MigrateMantleStateDeps {
+  /**
+  * Output format for the emitted bedrock config file. `"typescript"`
+  * produces a `defineConfig({...})` module; `"yaml"` produces a YAML
+  * body whose keys match the `Config` schema.
+  */
+  readonly configFormat: ConfigFormat;
+  /**
+  * Environment in the input state file whose resolved values seed
+  * the root config. Required when the state file declares more than
+  * one environment; ignored when only one environment is present.
+  */
+  readonly primaryEnvironment?: string;
+  /**
+  * Reads file bytes; defaults to `node:fs/promises.readFile`. Kept
+  * `Uint8Array`-typed to match `deploy`, `buildDesired`, and
+  * `buildDefaultRegistry`. UTF-8 decoding happens inside the migrator
+  * before YAML parsing.
+  */
+  readonly readFile?: (path: string) => Promise<Uint8Array>;
+  /** Absolute path to the `.mantle-state.yml` file to migrate. */
+  readonly stateFilePath: string;
+}
+/**
+* Read a Mantle state file and produce a `MigrationReport` containing a
+* bedrock config, per-environment `BedrockState`s, and a structured list
+* of fields that did not migrate verbatim.
+*
+* Skeleton: handles single-environment or multi-environment states with
+* universe, place, and game-pass resources. The primary environment
+* auto-picks when only one environment is present; multi-environment
+* inputs without an explicit `primaryEnvironment` return
+* `Err({ kind: "primaryEnvironmentRequired", available })` so the
+* migrator never silently picks a winner. Future slices add social
+* links and the deferred / blocked warning categories.
+*
+* @param deps - Inputs for the migration.
+* @returns `Ok` with a `MigrationReport` on success, or `Err` with a
+*   discriminated `MigrateError` on failure.
+* @rejects Re-thrown `readFile` failure when the underlying error code is
+*   not in the recognized "missing file" set; surfaced so callers see
+*   permission or filesystem outages instead of having them coerced to
+*   `stateFileNotFound`.
+* @example
+*
+* ```ts
+* import { migrateMantleState } from "@bedrock-rbx/core";
+*
+* const yaml = [
+*     'version: "6"',
+*     "environments:",
+*     "  production:",
+*     "    - id: experience_singleton",
+*     "      inputs:",
+*     "        experience:",
+*     "          groupId: ~",
+*     "      outputs:",
+*     "        experience:",
+*     "          assetId: 6031475575",
+*     "          startPlaceId: 17613681043",
+*     "      dependencies: []",
+*     "",
+* ].join("\n");
+*
+* async function readFile(): Promise<Uint8Array> {
+*     return new TextEncoder().encode(yaml);
+* }
+*
+* return migrateMantleState({
+*     configFormat: "typescript",
+*     readFile,
+*     stateFilePath: ".mantle-state.yml",
+* }).then((result) => {
+*     expect(result.success).toBeTrue();
+*     if (result.success) {
+*         expect(result.data.config.universe?.universeId).toBe("6031475575");
+*     }
+* });
+* ```
+*/
+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 };
+//# sourceMappingURL=index.d.mts.map