@bedrock-rbx/core 0.1.0-beta.13 → 0.1.0-beta.15

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { C as UniverseOverlayWithoutId, D as ConfigValidationIssue, E as ConfigError, S as UniverseOverlayWithId, T as validateConfig, _ as ResolvedPlaceEntry, a as ConfigEnvironmentUniverseId, b as StateConfig, c as DisplayNamePrefixConfig, d as GistStateConfig, f as PlaceEntry, g as ResolvedConfig, h as RedactedPlaceOverride, i as Config, l as EnvironmentEntry, m as RedactedGamePassOverride, n as ConfigInput, o as ConfigRootUniverseId, p as RedactedDeveloperProductOverride, r as defineConfig, s as DeveloperProductEntry, t as ConfigContext, u as GamePassEntry, v as ResolvedUniverseEntry, w as isGistStateConfig, x as UniverseEntry, y as ResourceEntryByKind } from "./define-config-Bd0XIiSX.mjs";
+import { C as UniverseOverlayWithId, D as ConfigError, E as validateConfig, O as ConfigValidationIssue, S as UniverseEntry, T as isGistStateConfig, _ as ResolvedConfig, a as ConfigEnvironmentUniverseId, b as ResourceEntryByKind, c as DisplayNamePrefixConfig, d as GistStateConfig, f as PlaceEntry, g as RedactedPlaceOverride, h as RedactedGamePassOverride, i as Config, l as EnvironmentEntry, m as RedactedEnvironmentOverride, n as ConfigInput, o as ConfigRootUniverseId, p as RedactedDeveloperProductOverride, r as defineConfig, s as DeveloperProductEntry, t as ConfigContext, u as GamePassEntry, v as ResolvedPlaceEntry, w as UniverseOverlayWithoutId, x as StateConfig, y as ResolvedUniverseEntry } from "./define-config-B4GZRPj-.mjs";
 import { OpenCloudError, OpenCloudError as OpenCloudError$1, Result, Result as Result$1 } from "@bedrock-rbx/ocale";
 import { Type as Type$1 } from "arktype";
 import { DeveloperProductsClient } from "@bedrock-rbx/ocale/developer-products";
@@ -1017,6 +1017,13 @@ interface GistStateAdapterDeps {
   /** ID of an existing GitHub Gist that holds this project's state files. */
   readonly gistId: string;
   /**
+  * Injection seam for retry jitter; defaults to `Math.random`. Tests pass a
+  * deterministic source so jittered sleep durations stay stable across runs.
+  * Jitter prevents concurrent callers (parallel CI jobs writing to the same
+  * gist) from retrying in lockstep and re-colliding on each backoff.
+  */
+  readonly random?: (() => number) | undefined;
+  /**
   * Injection seam for retry backoff timing; defaults to a `setTimeout`-based
   * promise. Tests pass a fake to keep retry assertions deterministic.
   */
@@ -1107,7 +1114,7 @@ interface BuildStatePortDeps {
 * const port = buildStatePort({
 *     fetch: async () =>
 *         new Response(JSON.stringify({ files: {} }), { status: 200 }),
-*     getEnv: (name) => (name === "GITHUB_TOKEN" ? "ghp_example" : undefined),
+*     getEnv: (name) => (name === "BEDROCK_GITHUB_TOKEN" ? "ghp_example" : undefined),
 *     stateConfig: { backend: "gist", gistId: "abc123" },
 * });
 *
@@ -1329,127 +1336,6 @@ type SelectEnvironmentError = IncompletePassEntryError | IncompletePlaceEntryErr
 */
 declare function selectEnvironment(config: Config, environment: string): Result$1<ResolvedConfig, SelectEnvironmentError>;
 //#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/core/operations.d.ts
 /**
 * Fields shared by every operation variant.
@@ -1561,11 +1447,13 @@ interface CreateOperation extends BaseOperation {
 *         name: "VIP Pass",
 *         price: 750,
 *     },
+*     changedFields: ["description", "price"],
 *     key: asResourceKey("vip-pass"),
 *     type: "update",
 * };
 *
 * expect(op.type).toBe("update");
+* expect(op.changedFields).toStrictEqual(["description", "price"]);
 * if (op.desired.kind === "gamePass") {
 *     expect(op.desired.price).toBe(750);
 * }
@@ -1575,7 +1463,14 @@ interface CreateOperation extends BaseOperation {
 * ```
 */
 interface UpdateOperation extends BaseOperation {
-  /** Last-known live state; the driver computes a patch against `desired`. */
+  /**
+  * Top-level field names that differ between `current` and `desired`,
+  * populated by `diff` from the kind module's `changedFieldsBetween`.
+  * Preview and apply renderers consume this as the single source of truth
+  * for "what changed" on this op; never empty for an `update` variant.
+  */
+  readonly changedFields: ReadonlyArray<string>;
+  /** Last-known current state; the driver computes a patch against `desired`. */
   readonly current: ResourceCurrentState;
   /** Declared desired state to converge toward. */
   readonly desired: ResourceDesiredState;
@@ -1587,9 +1482,9 @@ interface UpdateOperation extends BaseOperation {
 * 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`.
+* Carries `key` and `kind` so progress renderers and adapters can describe the
+* unchanged resource without re-looking it up in the desired or current
+* snapshots passed to `diff`.
 *
 * @example
 *
@@ -1598,14 +1493,18 @@ interface UpdateOperation extends BaseOperation {
 *
 * const op: NoopOperation = {
 *     key: asResourceKey("vip-pass"),
+*     kind: "gamePass",
 *     type: "noop",
 * };
 *
 * expect(op.type).toBe("noop");
+* expect(op.kind).toBe("gamePass");
 * expect(op.key).toBe("vip-pass");
 * ```
 */
 interface NoopOperation extends BaseOperation {
+  /** Resource-kind discriminator copied from the matching desired/current entry. */
+  readonly kind: ResourceKind;
   /** Discriminator tag for the `Operation` union. */
   readonly type: "noop";
 }
@@ -1638,6 +1537,7 @@ interface NoopOperation extends BaseOperation {
 *
 * const op: Operation = {
 *     key: asResourceKey("vip-pass"),
+*     kind: "gamePass",
 *     type: "noop",
 * };
 *
@@ -1646,15 +1546,145 @@ interface NoopOperation extends BaseOperation {
 */
 type Operation = CreateOperation | NoopOperation | UpdateOperation;
 //#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/shell/apply-ops.d.ts
 /**
+* Optional wiring `applyOps` uses to emit per-resource and aggregate progress
+* events. When omitted, `applyOps` runs silently (backward-compatible with
+* pre-progress callers).
+*/
+interface ApplyOpsReporting {
+  /** Environment name stamped on every emitted event. */
+  readonly environment: string;
+  /** Sink the apply pipeline pushes events into. */
+  readonly progress: ProgressPort;
+}
+/**
 * 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.
+* One `ApplyError` describes one failing op; the surrounding
+* `AggregateApplyError` carries the full batch outcome (every survivor and
+* every failure).
 *
 * @example
 *
@@ -1666,6 +1696,9 @@ type Operation = CreateOperation | NoopOperation | UpdateOperation;
 *         case "driverFailure": {
 *             return `driver failed for ${err.key}: ${err.cause.message}`;
 *         }
+*         case "unexpectedThrow": {
+*             return `unexpected error for ${err.key}`;
+*         }
 *         case "updateUnsupported": {
 *             return `update not supported for ${err.key}`;
 *         }
@@ -1674,134 +1707,297 @@ type Operation = CreateOperation | NoopOperation | UpdateOperation;
 *
 * 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>;
+type ApplyError = {
+  readonly cause: OpenCloudError$1;
+  readonly key: ResourceKey;
+  readonly kind: "driverFailure";
+} | {
+  readonly cause: unknown;
+  readonly key: ResourceKey;
+  readonly kind: "unexpectedThrow";
+} | {
+  readonly key: ResourceKey;
+  readonly kind: "updateUnsupported";
+};
+/**
+* Aggregate outcome returned by `applyOps` when one or more ops fail.
+* `applied` is the survivor set in Phase 1 then Phase 2 input order.
+* `failures` is the non-empty list of `ApplyError`s, one per failing op,
+* grouped the same way.
+*
+* @example
+*
+* ```ts
+* import { asResourceKey, type AggregateApplyError } from "@bedrock-rbx/core";
+*
+* function summarize(err: AggregateApplyError): string {
+*     return `${err.applied.length} survived, ${err.failures.length} failed`;
+* }
+*
+* const err: AggregateApplyError = {
+*     applied: [],
+*     failures: [{ key: asResourceKey("vip-pass"), kind: "updateUnsupported" }],
+* };
+*
+* expect(summarize(err)).toBe("0 survived, 1 failed");
+* ```
+*/
+interface AggregateApplyError {
+  /** Survivors persisted to state, in Phase 1 then Phase 2 input order. */
+  readonly applied: ReadonlyArray<ResourceCurrentState>;
+  /** Per-op failures, at least one, in Phase 1 then Phase 2 input order. */
+  readonly failures: readonly [ApplyError, ...ReadonlyArray<ApplyError>];
+}
+/**
+* Dispatch reconciliation operations to their matching drivers in two phases
+* with continue-on-failure semantics. Phase 1 runs universe ops sequentially
+* (singleton per environment; sequencing it before everything else avoids the
+* `displayName` race against the root `Place`). Phase 2 dispatches every
+* remaining non-noop op concurrently via `Promise.all`; every op is
+* attempted regardless of earlier failures.
+*
+* Behaviour:
+* - `create` operations route to `registry[op.desired.kind].create`.
+* - `update` operations route to `registry[op.desired.kind].update` when the
+*   driver exposes it; otherwise they yield an `updateUnsupported`
+*   `ApplyError` without invoking the driver.
+* - `noop` operations are skipped entirely (no I/O, no dispatch).
+* - A driver that throws outside its `Result` contract is caught at the
+*   dispatch boundary and translated to an `unexpectedThrow` `ApplyError`
+*   scoped to that op alone; the rest of the batch keeps running.
+*
+* On Ok the returned array carries driver outputs for every non-noop op
+* in phase order: Phase 1 universe entries first, then Phase 2 entries in
+* their input order. Noops are not represented; callers needing a full
+* post-apply snapshot merge with the pre-apply current state keyed by
+* `ResourceKey`.
+*
+* On Err the aggregate carries every survivor in `applied` (Phase 1 first,
+* then Phase 2 input order) and every failure in `failures` with the same
+* grouping. Neither array reflects completion order.
+*
+* @param ops - Reconciliation operations produced by `diff`, applied in
+*   declaration order.
+* @param registry - Per-kind driver table; dispatch uses `op.desired.kind`
+*   as the index.
+* @param reporting - Optional progress wiring. When supplied, `applyOps`
+*   emits one `resourceOpStarted` and one terminal event per non-noop op,
+*   one `resourceOpNoop` per noop op, and a final `applySummary` carrying
+*   the per-type counts and the wall-clock apply duration. When omitted,
+*   no events fire.
+* @returns `Ok(state)` when every op succeeded; otherwise
+*   `Err(AggregateApplyError)` with the survivors and the non-empty
+*   failures tuple.
+* @example
+*
+* ```ts
+* import { applyOps, type DriverRegistry } from "@bedrock-rbx/core";
+*
+* const noopRegistry: DriverRegistry = {
+*     developerProduct: { create: async () => ({ err: new Error("stub") as never, success: false }) },
+*     gamePass: { create: async () => ({ err: new Error("stub") as never, success: false }) },
+*     place: { create: async () => ({ err: new Error("stub") as never, success: false }) },
+*     universe: { create: async () => ({ err: new Error("stub") as never, success: false }) },
+* };
+*
+* return applyOps([], noopRegistry).then((result) => {
+*     expect(result).toStrictEqual({ data: [], success: true });
+* });
+* ```
+*/
+declare function applyOps(ops: ReadonlyArray<Operation>, registry: DriverRegistry, reporting?: ApplyOpsReporting): Promise<Result$1<ReadonlyArray<ResourceCurrentState>, AggregateApplyError>>;
+//#endregion
+//#region src/ports/progress-port.d.ts
+/**
+* Per-environment outcome event emitted after a deploy completes
+* successfully. Carries the environment name and the count of resources
+* present in the persisted state snapshot.
+*/
+interface DeploySuccessEvent {
+  /** The environment that finished reconciling. */
+  readonly environment: string;
+  /** Discriminator tag. */
+  readonly kind: "deploySuccess";
+  /** Number of resources in the post-deploy state snapshot. */
+  readonly resourceCount: number;
+}
+/**
+* Per-environment outcome event emitted when a deploy fails. Carries the
+* environment name and the full {@link DeployError} so a renderer can
+* delegate to the existing diagnostic helpers.
+*/
+interface DeployFailureEvent {
+  /** The environment whose deploy failed. */
+  readonly environment: string;
+  /** Stage-tagged failure reason returned by the shell `deploy` function. */
+  readonly error: DeployError;
+  /** Discriminator tag. */
+  readonly kind: "deployFailure";
+}
+/**
+* Per-resource event emitted immediately before `applyOps` dispatches a
+* non-noop op to its driver. Adapters may render a "starting" line or
+* stay silent; the matching terminal event ({@link ResourceOpSucceededEvent}
+* or {@link ResourceOpFailedEvent}) fires when the driver settles.
+*/
+interface ResourceOpStartedEvent {
+  /** User-supplied resource key. */
+  readonly key: ResourceKey;
+  /** Environment whose reconcile is running. */
+  readonly environment: string;
+  /** Discriminator tag. */
+  readonly kind: "resourceOpStarted";
+  /** Operation type being dispatched. Noops never fire this event. */
+  readonly opType: "create" | "update";
+  /** Resource-kind discriminator (`gamePass`, `place`, ...). */
+  readonly resourceKind: ResourceKind;
+}
+/**
+* Terminal event for a successful create op. The `resourceKind` discriminator
+* narrows `outputs` to the matching `ResourceOutputs<K>` shape so renderers
+* can read Roblox-assigned IDs without casts.
+*/
+type ResourceOpSucceededCreateEvent = { [K in ResourceKind]: Readonly<{
+  environment: string;
+  key: ResourceKey;
+  kind: "resourceOpSucceeded";
+  opType: "create";
+  outputs: ResourceOutputs<K>;
+  resourceKind: K;
+}> }[ResourceKind];
+/**
+* Terminal event for a successful update op. Carries the list of top-level
+* fields the diff flagged as changed so renderers can attribute the update.
+*/
+interface ResourceOpSucceededUpdateEvent {
+  /** User-supplied resource key. */
+  readonly key: ResourceKey;
+  /** Top-level field names whose values differed between desired and current. */
+  readonly changedFields: ReadonlyArray<string>;
+  /** Environment whose reconcile is running. */
+  readonly environment: string;
+  /** Discriminator tag. */
+  readonly kind: "resourceOpSucceeded";
+  /** Operation type. */
+  readonly opType: "update";
+  /** Resource-kind discriminator. */
+  readonly resourceKind: ResourceKind;
+}
+/**
+* Terminal event for a successful non-noop op. Sub-discriminated by `opType`
+* so a renderer can extract `outputs` (creates) or `changedFields` (updates)
+* without losing type narrowing.
+*/
+type ResourceOpSucceededEvent = ResourceOpSucceededCreateEvent | ResourceOpSucceededUpdateEvent;
+/**
+* Per-resource event emitted for each op the diff produced as a noop.
+* Noops never fire a `started`/terminal pair; this single event stands in
+* for the entire op so adapters can render a "unchanged" line.
+*/
+interface ResourceOpNoopEvent {
+  /** User-supplied resource key. */
+  readonly key: ResourceKey;
+  /** Environment whose reconcile is running. */
+  readonly environment: string;
+  /** Discriminator tag. */
+  readonly kind: "resourceOpNoop";
+  /** Resource-kind discriminator. */
+  readonly resourceKind: ResourceKind;
+}
+/**
+* Terminal event for a failed non-noop op. Carries the {@link ApplyError}
+* so a renderer can delegate to the existing apply-cause diagnostic helper.
+*/
+interface ResourceOpFailedEvent {
+  /** User-supplied resource key. */
   readonly key: ResourceKey;
-  readonly kind: "updateUnsupported";
-};
+  /** Environment whose reconcile is running. */
+  readonly environment: string;
+  /** Apply error returned by `dispatchOp`. */
+  readonly error: ApplyError;
+  /** Discriminator tag. */
+  readonly kind: "resourceOpFailed";
+  /** Operation type that was being attempted. */
+  readonly opType: "create" | "update";
+  /** Resource-kind discriminator. */
+  readonly resourceKind: ResourceKind;
+}
 /**
-* 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).
+* Aggregate footer event emitted after `applyOps` finishes (Phase 2 settled).
+* Fires unconditionally, including on partial failure; `durationMs` measures
+* apply time only (state-write time excluded).
+*/
+interface ApplySummaryEvent {
+  /** Count of successful create ops. */
+  readonly created: number;
+  /** Wall-clock duration between `applyOps` entry and Phase 2 resolution, in milliseconds. */
+  readonly durationMs: number;
+  /** Environment whose reconcile is running. */
+  readonly environment: string;
+  /** Count of failed ops (any opType). */
+  readonly failed: number;
+  /** Discriminator tag. */
+  readonly kind: "applySummary";
+  /** Count of noop ops. */
+  readonly noop: number;
+  /** Count of successful update ops. */
+  readonly updated: number;
+}
+/**
+* Per-environment event emitted after `statePort.write` returns `Ok`.
+* Not emitted on write failure: the existing `deployFailure` event with
+* `kind: "stateWriteFailed"` runs the existing failure flow. The payload
+* carries no backend identity; renderers read the backend label from the
+* project config when constructing the rendered line.
+*/
+interface StateWrittenEvent {
+  /** Environment whose state snapshot was just persisted. */
+  readonly environment: string;
+  /** Discriminator tag. */
+  readonly kind: "stateWritten";
+}
+/**
+* Discriminated union of progress events the CLI emits while a deploy
+* runs. The variant set is additive: future per-stage and per-resource
+* events land as new `kind` values without breaking existing adapters.
+*/
+type ProgressEvent = ApplySummaryEvent | DeployFailureEvent | DeploySuccessEvent | ResourceOpFailedEvent | ResourceOpNoopEvent | ResourceOpStartedEvent | ResourceOpSucceededEvent | StateWrittenEvent;
+/**
+* Plugin contract for receiving deploy outcomes: the interface an adapter
+* (clack renderer, JSON logger, custom UI) implements to let the CLI hand
+* off events without re-implementing rendering logic.
 *
-* 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`.
+* `ProgressPort` is a *driven* (secondary) port in hexagonal terms.
 *
-* @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";
+* import type { ProgressEvent, ProgressPort } 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,
-*             };
-*         },
+* let received: ReadonlyArray<ProgressEvent> = [];
+* const port: ProgressPort = {
+*     emit(event) {
+*         received = [...received, event];
 *     },
 * };
 *
-* 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,
-*         },
-*     },
-* ];
+* port.emit({ environment: "production", kind: "deploySuccess", resourceCount: 3 });
 *
-* return applyOps(ops, registry).then((result) => {
-*     expect(result.success).toBe(true);
-*     expect(result.success && result.data).toHaveLength(1);
-* });
+* expect(received).toEqual([
+*     { environment: "production", kind: "deploySuccess", resourceCount: 3 },
+* ]);
 * ```
 */
-declare function applyOps(ops: ReadonlyArray<Operation>, registry: DriverRegistry): Promise<Result$1<ReadonlyArray<ResourceCurrentState>, ApplyError>>;
+interface ProgressPort {
+  /** Hand a single progress event to the adapter for rendering or logging. */
+  emit(event: ProgressEvent): void;
+}
 //#endregion
 //#region src/shell/build-default-registry.d.ts
 /**
@@ -2086,16 +2282,21 @@ declare function flattenConfig(config: ResolvedConfig): ReadonlyArray<ResourceDe
 //#endregion
 //#region src/core/kinds/module.d.ts
 /**
-* Failure surfaced during desired-state preparation. Two variants today:
+* Failure surfaced before `diff` runs. Three 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.
+* - `iconRemovalRejected`: a kind's 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.
+* - `redactedNameCollision`: two developer-products in the same batch
+*   resolve to the same wire `name`. The upstream Roblox API enforces
+*   per-universe uniqueness on developer-product names and would reject
+*   the second PATCH with `DuplicateProductName`.
 *
-* Both variants carry the offending `key` so the CLI can attribute the
-* failure to a single resource entry.
+* The single-resource variants carry the offending `key` so the CLI can
+* attribute the failure to one entry; `redactedNameCollision` carries
+* both colliding keys and the resolved name.
 *
 * @example
 *
@@ -2121,6 +2322,11 @@ type BuildDesiredError = {
   /** 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;
+} | {
+  /** The two developer-product keys whose desired `name` resolves to the same string. */readonly keys: readonly [ResourceKey, ResourceKey]; /** Literal discriminator for narrowing. */
+  readonly kind: "redactedNameCollision"; /** Human-readable explanation naming both keys and the override remedy. */
+  readonly message: string; /** The wire `name` value both products resolve to. */
+  readonly resolvedName: string;
 };
 /**
 * I/O surface the shell injects into kind-module `normalize` calls. Carries
@@ -2184,6 +2390,8 @@ interface KindIo {
 *         },
 *         success: true,
 *     }),
+*     changedFieldsBetween: (desired, current) =>
+*         desired.name === current.name ? [] : ["name"],
 *     fieldsEqual: (desired, current) => desired.name === current.name,
 * };
 *
@@ -2192,14 +2400,22 @@ interface KindIo {
 */
 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
+  * Optional reconcilability invariant invoked for every `(kind, key)` pair
+  * that exists on both sides before `diff` runs. 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.
+  * API has no documented unset path for) before any apply-side driver I/O
+  * is attempted. Kinds without such invariants omit this hook.
   */
   readonly assertReconcilable?: (current: ResourceCurrentState<K>, desired: DesiredFor<K>) => Result$1<undefined, BuildDesiredError>;
+  /**
+  * Top-level field names that differ between `desired` and `current`,
+  * in a kind-specific deterministic order. Mirrors `fieldsEqual`
+  * semantics, so `fieldsEqual(d, c)` is `true` iff this returns `[]`.
+  * Granularity is top-level: `discordSocialLink`, not
+  * `discordSocialLink.uri`. Preview and apply renderers consume this as
+  * the single source of truth for "what changed" on an update op.
+  */
+  changedFieldsBetween(desired: DesiredFor<K>, current: ResourceCurrentState<K>): ReadonlyArray<string>;
   /** ArkType schema for the authored entry body of this kind. */
   readonly entrySchema: Type$1<ResourceEntryByKind[K]>;
   /**
@@ -2370,7 +2586,7 @@ declare function loadConfig(options?: LoadConfigOptions): Promise<Result$1<Confi
 /**
 * Inputs for `deploy`. Every field except `environment` is optional;
 * omitted dependencies are default-constructed from the project config
-* and the environment variables `GITHUB_TOKEN` and `BEDROCK_API_KEY`.
+* and the environment variables `BEDROCK_GITHUB_TOKEN` and `BEDROCK_API_KEY`.
 */
 interface DeployOptions {
   /** Pre-loaded, optionally-mutated project config. Omit to call `loadConfig()` automatically. */
@@ -2383,11 +2599,18 @@ interface DeployOptions {
   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>>;
+  /**
+  * Optional sink for per-resource and aggregate progress events. When
+  * supplied, `applyOps` emits one started/terminal pair per non-noop op
+  * (plus per-noop and summary events), and `deploy` emits `stateWritten`
+  * after a successful state-write. Omit to run silently.
+  */
+  readonly progress?: ProgressPort;
   /** Reads file bytes for resources that have file-backed inputs. Defaults to `node:fs/promises.readFile`. */
   readonly readFile?: (path: string) => Promise<Uint8Array>;
   /** Per-kind driver table consulted for create / update dispatch. Default-constructed from `BEDROCK_API_KEY` when omitted. */
   readonly registry?: DriverRegistry;
-  /** Backend used to read the prior snapshot and persist the new one. Default-constructed from `config.state` and `GITHUB_TOKEN` when omitted. */
+  /** Backend used to read the prior snapshot and persist the new one. Default-constructed from `config.state` and `BEDROCK_GITHUB_TOKEN` when omitted. */
   readonly statePort?: StatePort;
 }
 /**
@@ -2399,7 +2622,7 @@ interface DeployOptions {
 * `unsupportedBackend`, `registryConfigMissing`).
 */
 type DeployError = IncompletePassEntryError | IncompletePlaceEntryError | IncompleteUniverseEntryError | MissingCredentialError | RegistryConfigError | StateNotConfiguredError | UnknownEnvironmentError | UnsupportedBackendError | {
-  readonly cause: ApplyError;
+  readonly cause: AggregateApplyError;
   readonly kind: "applyFailed";
 } | {
   readonly cause: BuildDesiredError;
@@ -2417,9 +2640,13 @@ type DeployError = IncompletePassEntryError | IncompletePlaceEntryError | Incomp
 };
 /**
 * Run a full reconcile end-to-end. Default-constructs missing deps from
-* the project config and the environment variables `GITHUB_TOKEN` and
-* `BEDROCK_API_KEY`; never reads `process.env` when `statePort`,
-* `registry`, and `config` are all supplied explicitly.
+* the project config and the environment variables `BEDROCK_GITHUB_TOKEN`
+* and `BEDROCK_API_KEY`; emits a terminal `deploySuccess` or `deployFailure`
+* event through the resolved `progress` port. When `progress` is omitted,
+* the default port comes from `BEDROCK_CLI`: a non-empty value selects the
+* clack-backed adapter, any other reading selects the no-op adapter. No
+* environment lookups happen when `statePort`, `registry`, `config`, and
+* `progress` are all supplied explicitly.
 *
 * @param options - Target environment plus optional overrides.
 * @returns The persisted `BedrockState` on success, or a stage-tagged
@@ -2481,6 +2708,167 @@ type DeployError = IncompletePassEntryError | IncompletePlaceEntryError | Incomp
 */
 declare function deploy(options: DeployOptions): Promise<Result$1<BedrockState, DeployError>>;
 //#endregion
+//#region src/cli/spawner.d.ts
+/**
+* Concrete invocation passed to {@link Spawner.spawn}: the executable name,
+* its argv, and an env-var override map layered on top of the host process
+* environment. The adapter is responsible for merging `envOverrides` with
+* `process.env` so overrides win on collisions.
+*/
+interface SpawnInvocation {
+  /** Argv to pass to the spawned executable, excluding the command itself. */
+  readonly args: ReadonlyArray<string>;
+  /** Executable name to spawn (e.g. `"bun"`). */
+  readonly command: string;
+  /** Env-var entries that should overlay the host process environment. */
+  readonly envOverrides: Readonly<Record<string, string>>;
+}
+/**
+* Structural shape of the underlying error a {@link Spawner} surfaces when
+* a child cannot be launched. Mirrors the subset of Node's `ErrnoException`
+* the dispatcher and downstream renderers care about, without requiring
+* consumers to install `@types/node` to consume the public surface.
+*/
+interface SpawnLaunchCause extends Error {
+  /** Errno code like `"ENOENT"`, `"EACCES"`, or `undefined` when the error did not carry one. */
+  readonly code?: string | undefined;
+}
+/**
+* Failure surfaced by {@link Spawner.spawn} when the child process could not
+* be started at all (e.g. `ENOENT` for a missing executable). Carries the
+* underlying error so callers can render a precise diagnostic.
+*/
+interface SpawnLaunchError {
+  /** Underlying error from the spawn attempt; structurally an `Error` with an optional errno `code`. */
+  readonly cause: SpawnLaunchCause;
+  /** Discriminator tag. */
+  readonly kind: "launchFailed";
+}
+/**
+* Plugin contract for spawning a child process: the interface an adapter
+* (a `node:child_process` wrapper, a fake recorder in tests) implements to
+* let the CLI dispatch override scripts without binding to a concrete
+* process API.
+*
+* `Spawner` is a *driven* (secondary) port; the dispatcher drives the
+* spawner to perform a launch. Stdio is always inherited from the parent
+* process so the spawned script's output appears within the CLI's frame
+* in chronological order.
+*
+* @example
+*
+* ```ts
+* import type { Spawner, SpawnInvocation } from "@bedrock-rbx/core";
+*
+* const invocations: Array<SpawnInvocation> = [];
+* const spawner: Spawner = {
+*     async spawn(invocation) {
+*         invocations.push(invocation);
+*         return { data: 0, success: true };
+*     },
+* };
+*
+* return spawner
+*     .spawn({ args: ["--env", "production"], command: "bun", envOverrides: {} })
+*     .then((result) => {
+*         expect(result.success).toBeTrue();
+*         expect(invocations).toHaveLength(1);
+*     });
+* ```
+*/
+interface Spawner {
+  /**
+  * Launch the supplied invocation and resolve once the child closes.
+  *
+  * - `Ok(exitCode)` carries the child's numeric exit code (including 0).
+  * - `Err(launchFailed)` covers cases where the child could not be
+  *   started at all (missing executable, permission denied, signal'd
+  *   before exit).
+  */
+  spawn(invocation: SpawnInvocation): Promise<Result$1<number, SpawnLaunchError>>;
+}
+//#endregion
+//#region src/cli/dispatch-override.d.ts
+/**
+* Parsed deploy arguments forwarded to a `.bedrock/<command>.ts` override
+* script. Credential flags are translated into env-var overrides by the
+* dispatcher so secrets never reach the child's argv.
+*/
+interface OverrideInvocation {
+  /** Optional `--api-key` value; translated to `BEDROCK_API_KEY` in env. */
+  readonly apiKey?: string;
+  /** Optional `--config <path>` value; forwarded unchanged in argv when present. */
+  readonly configFile?: string;
+  /** Target environment for this single override invocation. */
+  readonly environment: string;
+  /** Optional `--github-token` value; translated to `BEDROCK_GITHUB_TOKEN` in env. */
+  readonly githubToken?: string;
+  /** Path to the override script file to invoke. */
+  readonly overridePath: string;
+}
+/**
+* Failure modes returned by {@link dispatchOverride}.
+*
+* - `launchFailed` — the child process could not be started (e.g. `bun`
+*   missing, permission denied). Wraps the {@link SpawnLaunchCause} the
+*   underlying spawner surfaced so callers can render a precise diagnostic.
+* - `nonZeroExit` — the child started, ran, and exited with a non-zero
+*   exit code. Callers should propagate `exitCode` into the CLI's own
+*   process exit code so CI failure modes mirror the override's outcome.
+*/
+type SpawnOverrideError = {
+  readonly cause: SpawnLaunchCause;
+  readonly kind: "launchFailed";
+} | {
+  readonly exitCode: number;
+  readonly kind: "nonZeroExit";
+};
+/**
+* Dispatch a single `.bedrock/<command>.ts` override invocation through the
+* supplied {@link Spawner}. Encapsulates the spawn protocol:
+*
+* - argv = `[overridePath, "--env", environment]`, with `"--config", configFile`
+*   appended when supplied.
+* - `apiKey` becomes the `BEDROCK_API_KEY` env-var override; `githubToken`
+*   becomes `BEDROCK_GITHUB_TOKEN`. Neither value appears in argv.
+* - `BEDROCK_CLI=1` is always set in the env. The override's `deploy()`
+*   reads this on the `getEnv` seam to default to the clack progress
+*   adapter; absent that downstream wiring, the variable is a forward-
+*   compatible signal a future caller can act on.
+*
+* The dispatcher itself reads no ambient state: every input arrives via the
+* `invocation` argument and the `Spawner` port is the only side-effect seam.
+*
+* @param invocation - Path, environment, and parsed deploy-flag inputs.
+* @param spawner - Port the dispatcher hands the resolved
+*   {@link SpawnInvocation} to.
+* @returns `Ok(undefined)` when the child exited zero; otherwise an
+*   {@link SpawnOverrideError} discriminating launch vs non-zero exit.
+*
+* @example
+*
+* ```ts
+* import { dispatchOverride, type Spawner } from "@bedrock-rbx/core";
+*
+* const spawner: Spawner = {
+*     async spawn() {
+*         return { data: 0, success: true };
+*     },
+* };
+*
+* return dispatchOverride(
+*     {
+*         environment: "production",
+*         overridePath: "/abs/.bedrock/deploy.ts",
+*     },
+*     spawner,
+* ).then((result) => {
+*     expect(result.success).toBeTrue();
+* });
+* ```
+*/
+declare function dispatchOverride(invocation: OverrideInvocation, spawner: Spawner): Promise<Result$1<void, SpawnOverrideError>>;
+//#endregion
 //#region src/cli/render.d.ts
 /**
 * Output port the CLI renders through. Mirrors the subset of `@clack/prompts`
@@ -2521,70 +2909,6 @@ interface ClackPort {
   outro(message: string): void;
 }
 //#endregion
-//#region src/ports/progress-port.d.ts
-/**
-* Per-environment outcome event emitted after a deploy completes
-* successfully. Carries the environment name and the count of resources
-* present in the persisted state snapshot.
-*/
-interface DeploySuccessEvent {
-  /** The environment that finished reconciling. */
-  readonly environment: string;
-  /** Discriminator tag. */
-  readonly kind: "deploySuccess";
-  /** Number of resources in the post-deploy state snapshot. */
-  readonly resourceCount: number;
-}
-/**
-* Per-environment outcome event emitted when a deploy fails. Carries the
-* environment name and the full {@link DeployError} so a renderer can
-* delegate to the existing diagnostic helpers.
-*/
-interface DeployFailureEvent {
-  /** The environment whose deploy failed. */
-  readonly environment: string;
-  /** Stage-tagged failure reason returned by the shell `deploy` function. */
-  readonly error: DeployError;
-  /** Discriminator tag. */
-  readonly kind: "deployFailure";
-}
-/**
-* Discriminated union of progress events the CLI emits while a deploy
-* runs. The variant set is additive: future per-stage and per-resource
-* events land as new `kind` values without breaking existing adapters.
-*/
-type ProgressEvent = DeployFailureEvent | DeploySuccessEvent;
-/**
-* Plugin contract for receiving deploy outcomes: the interface an adapter
-* (clack renderer, JSON logger, custom UI) implements to let the CLI hand
-* off events without re-implementing rendering logic.
-*
-* `ProgressPort` is a *driven* (secondary) port in hexagonal terms.
-*
-* @example
-*
-* ```ts
-* import type { ProgressEvent, ProgressPort } from "@bedrock-rbx/core";
-*
-* let received: ReadonlyArray<ProgressEvent> = [];
-* const port: ProgressPort = {
-*     emit(event) {
-*         received = [...received, event];
-*     },
-* };
-*
-* port.emit({ environment: "production", kind: "deploySuccess", resourceCount: 3 });
-*
-* expect(received).toEqual([
-*     { environment: "production", kind: "deploySuccess", resourceCount: 3 },
-* ]);
-* ```
-*/
-interface ProgressPort {
-  /** Hand a single progress event to the adapter for rendering or logging. */
-  emit(event: ProgressEvent): void;
-}
-//#endregion
 //#region src/adapters/clack-progress-adapter.d.ts
 /**
 * Configuration for {@link createClackProgressAdapter}.
@@ -2592,12 +2916,19 @@ interface ProgressPort {
 interface ClackProgressAdapterDeps {
   /** Output port the events are rendered through. */
   readonly clack: ClackPort;
+  /**
+  * Loaded project config (raw `Config` or env-resolved `ResolvedConfig`);
+  * the `stateWritten` case resolves the per-environment `StateConfig`
+  * against this to format the backend label. When omitted, `stateWritten`
+  * renders the generic `"state"` placeholder.
+  */
+  readonly config?: Config | ResolvedConfig;
 }
 /**
 * Build a {@link ProgressPort} that renders events through a `ClackPort`.
-* Pattern-matches on the event `kind`: `deploySuccess` becomes a single
-* success line and `deployFailure` delegates to the package's deploy-error
-* rendering helper.
+* Pattern-matches on the event `kind`: per-resource events render one line each,
+* the aggregate `applySummary` becomes the deploy footer, and `stateWritten`
+* names the persistence backend resolved from the loaded `Config`.
 *
 * @example
 *
@@ -2616,12 +2947,12 @@ interface ClackProgressAdapterDeps {
 *
 * const port = createClackProgressAdapter({ clack });
 *
-* port.emit({ environment: "production", kind: "deploySuccess", resourceCount: 3 });
+* port.emit({ environment: "production", kind: "stateWritten" });
 *
-* expect(lines).toEqual(["ok: production: 3 resources reconciled"]);
+* expect(lines).toEqual(["log: State written to state"]);
 * ```
 *
-* @param deps - The clack port the adapter renders through.
+* @param deps - The clack port and optional config the adapter renders through.
 * @returns A `ProgressPort` that renders via clack.
 */
 declare function createClackProgressAdapter(deps: ClackProgressAdapterDeps): ProgressPort;
@@ -3134,6 +3465,47 @@ declare function createUniverseDriver(deps: UniverseDriverDeps): ResourceDriver<
 */
 declare function createClackPort(): ClackPort;
 //#endregion
+//#region src/cli/default-spawner.d.ts
+/**
+* Construct a {@link Spawner} backed by `node:child_process.spawn` with
+* `stdio` inherited from the parent process. The child's environment is
+* `process.env` overlaid with {@link SpawnInvocation.envOverrides} (overrides
+* win on key collision).
+*
+* - Exit codes resolve as `Ok(exitCode)` (including `0`).
+* - `ENOENT` and other launch-time errors resolve as `Err(launchFailed)`
+*   with the original error in `cause` (its `code` field carries the
+*   errno where present).
+* - Children terminated by signal before producing an exit code collapse
+*   into `launchFailed` with a synthetic `Error` whose message names the
+*   signal; a distinct variant lands the day a caller needs to act on the
+*   difference.
+*
+* @returns A `Spawner` whose `spawn` settles once the child closes.
+* @example
+*
+* ```ts
+* import { createDefaultSpawner } from "@bedrock-rbx/core";
+* import process from "node:process";
+*
+* const spawner = createDefaultSpawner();
+*
+* return spawner
+*     .spawn({
+*         args: ["-e", "process.exit(0)"],
+*         command: process.execPath,
+*         envOverrides: {},
+*     })
+*     .then((result) => {
+*         expect(result.success).toBeTrue();
+*         if (result.success) {
+*             expect(result.data).toBe(0);
+*         }
+*     });
+* ```
+*/
+declare function createDefaultSpawner(): Spawner;
+//#endregion
 //#region src/core/derive-price-fields.d.ts
 /**
 * Wire-shape pricing fragment produced by {@link derivePriceFields}: the
@@ -3184,12 +3556,16 @@ declare function derivePriceFields(desired: {
 * `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.
+* Ops appear in the order their desired entries appear in the input array.
+* `applyOps` regroups them into Phase 1 (universe) and Phase 2 (everything
+* else) when dispatching; the execution order within Phase 2 is not
+* guaranteed because Phase 2 dispatches concurrently. Persisted state-file
+* order is determined by the merge in `deploy.runReconcile` (which retains
+* prior-snapshot positions for unchanged keys), not by this diff output.
 *
 * @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.
+* @param current - Last-known current state from the state file.
 * @returns Operations to reconcile the two snapshots.
 *
 * @example
@@ -3249,6 +3625,11 @@ declare function derivePriceFields(desired: {
 * const ops = diff([unchanged, drifted, fresh], current);
 *
 * expect(ops.map((op) => op.type)).toEqual(["noop", "update", "create"]);
+*
+* const updateOp = ops[1]!;
+* if (updateOp.type === "update") {
+*     expect(updateOp.changedFields).toStrictEqual(["name"]);
+* }
 * ```
 */
 declare function diff(desired: ReadonlyArray<ResourceDesiredState>, current: ReadonlyArray<ResourceCurrentState>): ReadonlyArray<Operation>;
@@ -3475,68 +3856,6 @@ declare function serializeStateFile(state: BedrockState): string;
 */
 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/migrate-mantle-state.d.ts
 type ConfigFormat = "typescript" | "yaml";
 /**
@@ -3632,5 +3951,5 @@ interface MigrateMantleStateDeps {
 */
 declare function migrateMantleState(deps: MigrateMantleStateDeps): Promise<Result$1<MigrationReport, MigrateError>>;
 //#endregion
-export { type ApplyError, type BaseOperation, type BedrockState, type BuildDesiredError, type ClackPort, type ClackProgressAdapterDeps, type Config, type ConfigContext, type ConfigEnvironmentUniverseId, type ConfigError, type ConfigInput, type ConfigRootUniverseId, type ConfigValidationIssue, type CreateOperation, DEFAULT_PREFIX_FORMAT, type DeployError, type DeployFailureEvent, type DeployOptions, type DeploySuccessEvent, type DeveloperProductDesiredInput, type DeveloperProductDesiredState, type DeveloperProductDriverDeps, type DeveloperProductEntry, type DeveloperProductOutputs, type DisplayNamePrefixConfig, type DriverRegistry, type EnvironmentEntry, type GamePassDesiredInput, type GamePassDesiredState, type GamePassDriverDeps, type GamePassEntry, type GamePassOutputs, type GetEnvironmentError, type GistStateAdapterDeps, type GistStateConfig, type IncompletePlaceEntryError, type IncompleteUniverseEntryError, type KindIo, type KindRegistry, type LoadConfigOptions, type MigrateError, type MigrateMantleStateDeps, type MigrationReport, type MigrationSummary, type MigrationWarning, type MissingCredentialError, type NoopOperation, OpenCloudError, type Operation, type PlaceDesiredInput, type PlaceDesiredState, type PlaceDriverDeps, type PlaceEntry, type PlaceOutputs, type PriceFields, type ProgressEvent, type ProgressPort, type RedactedDeveloperProductOverride, type RedactedGamePassOverride, type RedactedPlaceOverride, type RegistryConfigError, type ResolvedConfig, type ResolvedPlaceEntry, type ResolvedUniverseEntry, type ResourceCurrentState, type ResourceDesiredInput, type ResourceDesiredState, type ResourceDriver, type ResourceEntryByKind, type ResourceKey, type ResourceKind, type ResourceKindModule, type ResourceOutputs, type ResourceOutputsByKind, type Result, type RobloxAssetId, SOCIAL_LINK_FIELDS, type SelectEnvironmentError, type Sha256Hex, type SocialLink, type SocialLinkField, type StateConfig, type StateError, type StateNotConfiguredError, type StatePort, type StatesByEnvironment, UNIVERSE_SINGLETON_KEY, type UniverseDesiredInput, type UniverseDesiredState, type UniverseDriverDeps, type UniverseEntry, type UniverseOutputs, type UniverseOverlayWithId, type UniverseOverlayWithoutId, type UnknownEnvironmentError, type UnsupportedBackendError, type UpdateOperation, applyOps, asResourceKey, asRobloxAssetId, asSha256Hex, buildDefaultRegistry, buildDesired, buildStatePort, createClackPort, createClackProgressAdapter, createDeveloperProductDriver, createGamePassDriver, createGistStateAdapter, createNoOpProgressAdapter, createPlaceDriver, createUniverseDriver, defaultKindRegistry, defineConfig, deploy, derivePriceFields, diff, flattenConfig, getEnvironment, isGistStateConfig, isResourceKey, isRobloxAssetId, isSha256Hex, loadConfig, migrateMantleState, parseStateFile, renderDisplayNamePrefix, resolveStateConfig, selectEnvironment, serializeStateFile, shouldReuploadIcon, validateConfig, validateEnvironmentName, validatePlan };
+export { type AggregateApplyError, type ApplyError, type ApplyOpsReporting, type ApplySummaryEvent, type BaseOperation, type BedrockState, type BuildDesiredError, type ClackPort, type ClackProgressAdapterDeps, type Config, type ConfigContext, type ConfigEnvironmentUniverseId, type ConfigError, type ConfigInput, type ConfigRootUniverseId, type ConfigValidationIssue, type CreateOperation, DEFAULT_PREFIX_FORMAT, type DeployError, type DeployFailureEvent, type DeployOptions, type DeploySuccessEvent, type DeveloperProductDesiredInput, type DeveloperProductDesiredState, type DeveloperProductDriverDeps, type DeveloperProductEntry, type DeveloperProductOutputs, type DisplayNamePrefixConfig, type DriverRegistry, type EnvironmentEntry, type GamePassDesiredInput, type GamePassDesiredState, type GamePassDriverDeps, type GamePassEntry, type GamePassOutputs, type GetEnvironmentError, type GistStateAdapterDeps, type GistStateConfig, type IncompletePlaceEntryError, type IncompleteUniverseEntryError, type KindIo, type KindRegistry, type LoadConfigOptions, type MigrateError, type MigrateMantleStateDeps, type MigrationReport, type MigrationSummary, type MigrationWarning, type MissingCredentialError, type NoopOperation, OpenCloudError, type Operation, type OverrideInvocation, type PlaceDesiredInput, type PlaceDesiredState, type PlaceDriverDeps, type PlaceEntry, type PlaceOutputs, type PriceFields, type ProgressEvent, type ProgressPort, type RedactedDeveloperProductOverride, type RedactedEnvironmentOverride, type RedactedGamePassOverride, type RedactedPlaceOverride, 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 ResourceOpFailedEvent, type ResourceOpNoopEvent, type ResourceOpStartedEvent, type ResourceOpSucceededCreateEvent, type ResourceOpSucceededEvent, type ResourceOpSucceededUpdateEvent, type ResourceOutputs, type ResourceOutputsByKind, type Result, type RobloxAssetId, SOCIAL_LINK_FIELDS, type SelectEnvironmentError, type Sha256Hex, type SocialLink, type SocialLinkField, type SpawnInvocation, type SpawnLaunchCause, type SpawnLaunchError, type SpawnOverrideError, type Spawner, type StateConfig, type StateError, type StateNotConfiguredError, type StatePort, type StateWrittenEvent, type StatesByEnvironment, UNIVERSE_SINGLETON_KEY, type UniverseDesiredInput, type UniverseDesiredState, type UniverseDriverDeps, type UniverseEntry, type UniverseOutputs, type UniverseOverlayWithId, type UniverseOverlayWithoutId, type UnknownEnvironmentError, type UnsupportedBackendError, type UpdateOperation, applyOps, asResourceKey, asRobloxAssetId, asSha256Hex, buildDefaultRegistry, buildDesired, buildStatePort, createClackPort, createClackProgressAdapter, createDefaultSpawner, createDeveloperProductDriver, createGamePassDriver, createGistStateAdapter, createNoOpProgressAdapter, createPlaceDriver, createUniverseDriver, defaultKindRegistry, defineConfig, deploy, derivePriceFields, diff, dispatchOverride, flattenConfig, getEnvironment, isGistStateConfig, isResourceKey, isRobloxAssetId, isSha256Hex, loadConfig, migrateMantleState, parseStateFile, renderDisplayNamePrefix, resolveStateConfig, selectEnvironment, serializeStateFile, shouldReuploadIcon, validateConfig, validateEnvironmentName };
 //# sourceMappingURL=index.d.mts.map