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

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-C2cOtDpP.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";
@@ -1329,127 +1329,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 +1440,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,6 +1456,13 @@ interface CreateOperation extends BaseOperation {
 * ```
 */
 interface UpdateOperation extends BaseOperation {
+  /**
+  * Top-level field names that differ between `current` and `desired`,
+  * populated by `diff` from the kind module's `changedFieldsBetween`.
+  * Plan 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 live state; the driver computes a patch against `desired`. */
   readonly current: ResourceCurrentState;
   /** Declared desired state to converge toward. */
@@ -1587,9 +1475,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 +1486,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 +1530,7 @@ interface NoopOperation extends BaseOperation {
 *
 * const op: Operation = {
 *     key: asResourceKey("vip-pass"),
+*     kind: "gamePass",
 *     type: "noop",
 * };
 *
@@ -1646,15 +1539,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 +1689,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,7 +1700,6 @@ type Operation = CreateOperation | NoopOperation | UpdateOperation;
 *
 * const err: ApplyError = {
 *     key: asResourceKey("vip-pass"),
-*     appliedSoFar: [],
 *     kind: "updateUnsupported",
 * };
 *
@@ -1682,126 +1707,290 @@ type Operation = CreateOperation | NoopOperation | UpdateOperation;
 * ```
 */
 type ApplyError = {
-  readonly appliedSoFar: ReadonlyArray<ResourceCurrentState>;
   readonly cause: OpenCloudError$1;
   readonly key: ResourceKey;
   readonly kind: "driverFailure";
 } | {
-  readonly appliedSoFar: ReadonlyArray<ResourceCurrentState>;
+  readonly cause: unknown;
+  readonly key: ResourceKey;
+  readonly kind: "unexpectedThrow";
+} | {
   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.
+* 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 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.
+* - `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;
+  /** 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;
+}
+/**
+* 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 +2275,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 during desired-state preparation. 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.
+* - `redactedNameCollision`: `validatePlan` saw two developer-products in
+*   the same plan that 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 +2315,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 +2383,8 @@ interface KindIo {
 *         },
 *         success: true,
 *     }),
+*     changedFieldsBetween: (desired, current) =>
+*         desired.name === current.name ? [] : ["name"],
 *     fieldsEqual: (desired, current) => desired.name === current.name,
 * };
 *
@@ -2200,6 +2401,15 @@ interface ResourceKindModule<K extends ResourceKind> {
   * 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`. Plan 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]>;
   /**
@@ -2383,6 +2593,13 @@ 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. */
@@ -2399,7 +2616,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;
@@ -2521,70 +2738,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 +2745,18 @@ interface ProgressPort {
 interface ClackProgressAdapterDeps {
   /** Output port the events are rendered through. */
   readonly clack: ClackPort;
+  /**
+  * Loaded project config; 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;
 }
 /**
 * 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 +2775,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;
@@ -3184,8 +3343,12 @@ 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`).
@@ -3249,6 +3412,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>;
@@ -3632,5 +3800,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 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 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, createDeveloperProductDriver, createGamePassDriver, createGistStateAdapter, createNoOpProgressAdapter, createPlaceDriver, createUniverseDriver, defaultKindRegistry, defineConfig, deploy, derivePriceFields, diff, flattenConfig, getEnvironment, isGistStateConfig, isResourceKey, isRobloxAssetId, isSha256Hex, loadConfig, migrateMantleState, parseStateFile, renderDisplayNamePrefix, resolveStateConfig, selectEnvironment, serializeStateFile, shouldReuploadIcon, validateConfig, validateEnvironmentName, validatePlan };
 //# sourceMappingURL=index.d.mts.map