@dreamboard-games/sdk 0.4.0-alpha.9 → 0.5.0-alpha.1

package/README.md

@@ -1,19 +1,179 @@
 # @dreamboard-games/sdk
 
-The public Dreamboard SDK package. This repository publishes one consumer
-package, `@dreamboard-games/sdk`; public capabilities are exposed through the
-package export map rather than separate installable workspace packages.
+The public TypeScript SDK for authoring, testing, and rendering Dreamboard
+games. Install this package rather than any of the repository's unpublished
+workspace inputs.
 
-Internal workspaces such as `sdk-types`, `workspace-codegen`, and
-`reducer-contract` are implementation inputs. Consumers should not install or
-import those package names directly.
+```sh
+pnpm add @dreamboard-games/sdk
+```
 
-Typical imports:
+The package's declarations and export map are the API authority. Supported
+imports include the root module and explicit subpaths for authoring, runtime,
+reducer contracts, testing, browser interaction, UI, and reference-game
+metadata. Import only subpaths present in the installed package's `exports`
+field.
 
 ```ts
-import {
-  DREAMBOARD_SDK_PACKAGE_SET,
-  DREAMBOARD_SDK_VERSION,
-} from "@dreamboard-games/sdk";
+import { DREAMBOARD_SDK_VERSION } from "@dreamboard-games/sdk";
 import type { ReducerWire } from "@dreamboard-games/sdk/reducer-contract";
+import {
+  REFERENCE_GAME_MANIFEST_SCHEMA_VERSION,
+  parseReferenceGameManifest,
+  type ReferenceGameManifest,
+} from "@dreamboard-games/sdk/reference-games";
+
+const manifest: ReferenceGameManifest = parseReferenceGameManifest(input);
+console.log(REFERENCE_GAME_MANIFEST_SCHEMA_VERSION, manifest.id);
+```
+
+Reference-game manifests use schema V5. They describe the game workspace,
+teaching purpose, mechanics, UI patterns, and substantive rights metadata.
+
+Include the packaged stylesheet when using SDK UI components:
+
+```ts
+import "@dreamboard-games/sdk/ui/plugin-styles.css";
+```
+
+## Game authoring
+
+`createGame(model)` is the single authoring entry point. The **model** is a
+plain object: manifest ids, state schemas, one Zod schema per phase, and error
+codes. The returned value is three things at once:
+
+- the **type leaf**: `typeof game.types.State`, `.ErrorCode`, `.PlayerId`,
+  `.Queries`, `.Tx` (phantom carriers; reading them at runtime throws),
+- the **factory namespace**: `game.phase(name)`, `phase.define`,
+  `phase.interaction`, `phase.inputs.*`, `game.views.*`,
+- the **assembler**: `game.assemble({ initial, initialPhase, phases, views })`.
+
+Mutation callbacks (`enter`, `reduce`, `resolve`) receive an open transaction
+`tx`. Mutate through it and finish with a bare `return` (accept), or with
+`tx.transition(name)`, `tx.endGame(outcome)`, or `tx.reject(code)`. Events go
+through `tx.emit(...)`. `state` is the read-only snapshot the callback started
+from; `tx.state` is the current draft.
+
+```ts
+// app/game-model.ts — the model, bound once
+import { z } from "zod";
+import { createGame } from "@dreamboard-games/sdk/reducer";
+import { ids, manifestContract } from "../shared/manifest-contract";
+
+export const game = createGame({
+  manifest: manifestContract,
+  state: {
+    public: z.object({ currentPlayerId: ids.playerId.nullable() }),
+    private: z.object({}),
+    hidden: z.object({}),
+  },
+  phases: {
+    setup: z.object({}),
+    play: z.object({ leadCardId: ids.cardId.nullable() }),
+  },
+  errors: { NOT_YOUR_CARD: "Play a card from your own hand." },
+});
+
+export type GameState = typeof game.types.State;
 ```
+
+```ts
+// app/phases/play.ts — one phase, one file
+import { game } from "../game-model";
+
+const play = game.phase("play");
+
+// Inputs name their candidate domain and eligibility predicates directly.
+// `where.errorCode` is checked against `model.errors`.
+const ownCard = play.inputs.card({
+  from: ["hand"],
+  where: {
+    id: "own-card",
+    errorCode: "NOT_YOUR_CARD",
+    test: ({ q, playerId, targetId }) =>
+      q.zone.playerCards(playerId, "hand").includes(targetId),
+  },
+});
+
+export default play.define({
+  kind: "player",
+  initialState: () => ({ leadCardId: null }),
+  actor: ({ state }) => state.publicState.currentPlayerId,
+  interactions: {
+    playCard: play.interaction({
+      inputs: { cardId: ownCard },
+      reduce({ tx, input, q }) {
+        // tx.state.phase.leadCardId and input.params.cardId are inferred.
+        tx.moveCardFromPlayerZoneToSharedZone({
+          playerId: input.playerId,
+          fromZoneId: "hand",
+          toZoneId: "trick",
+          cardId: input.params.cardId,
+        });
+        tx.patchPhaseState({ leadCardId: input.params.cardId });
+        const next = q.player.nextInOrder(input.playerId);
+        if (next) tx.setActivePlayers([next]);
+        if (q.zone.playerCards(input.playerId, "hand").length === 0) {
+          return tx.transition("setup");
+        }
+      },
+    }),
+  },
+});
+```
+
+```ts
+// app/game.ts — assembly
+import { game } from "./game-model";
+import play from "./phases/play";
+import setup from "./phases/setup";
+
+export default game.assemble({
+  initial: {
+    public: ({ playerIds }) => ({ currentPlayerId: playerIds[0] ?? null }),
+    private: () => ({}),
+    hidden: () => ({}),
+  },
+  initialPhase: "setup",
+  phases: { setup, play },
+  views: {
+    shared: game.views.empty(),
+    player: game.views.player({
+      project: ({ state, playerId, q }) => ({
+        me: playerId,
+        hand: q.zone.playerCards(playerId, "hand"),
+        current: state.publicState.currentPlayerId,
+      }),
+    }),
+  },
+});
+```
+
+A missing, extra, or misspelled phase key fails to typecheck at `assemble`
+or at `game.phase(name)`. Rules, views, and tests import `GameState` and
+`typeof game.types.Tx` from the model module; nothing but the test harness
+imports the assembled game, so there is no import cycle.
+
+New workspaces keep authored starter code in `app/game.ts` and `ui/App.tsx`.
+Run the package-local `pnpm generate` command to refresh framework-owned
+manifest and UI contracts; generated files are not authoring surfaces.
+
+## Reducer runner contract
+
+`createReducerBundle(game)` returns exactly the contract version and four
+operations: `boardStatic()`, `initialize(input)`, `dispatch({ state, input })`,
+and `project({ state, playerIds })`. The runner contract is `0.5.0`; hosts must
+require that exact version. Dispatch includes validation and effect execution. Initialization returns
+`{ state, terminal?, events? }`, preserving outcomes and events from initial
+phase entry and automatic continuations.
+
+The authoritative state is explicit on every dispatch and projection. A host
+may retain a warm worker and SDK caches, but replaying the same state and input
+must produce the same gameplay result as a fresh worker. Projection timing is
+diagnostic and is excluded from this equivalence.
+
+Seat projections are independent of session versions. The gameplay service
+owns the monotonically increasing version, perspective, and action-set identity.
+The plugin frame basis contains `version`, `actionSetVersion`, and
+`perspectivePlayerId`; it has no generation counter. Hosts merge the separately
+cached board static projection when materializing plugin gameplay frames.

package/dist/authoring/index.d.ts

@@ -1,10 +1,7 @@
 import { JsonValue } from '../types.js';
 
-type GeneratedAuthoringMetadataV1 = {
+type AuthoringMetadataV1 = {
     sdkVersion: string;
-    codegenVersion: string;
-    manifestSchemaVersion: number;
-    generatedArtifactSchemaVersion: number;
 };
 type AuthoringValidationResultV1 = {
     valid: boolean;
@@ -36,7 +33,7 @@ type AuthoringManifestConformanceCaseV1 = {
 };
 type ProjectAuthoringAdapterV1 = {
     protocolVersion: 1;
-    metadata: GeneratedAuthoringMetadataV1;
+    metadata: AuthoringMetadataV1;
     generatedPaths: readonly string[];
     generatedPathPatterns: readonly GeneratedPathPatternV1[];
     manifestConformanceCases: readonly AuthoringManifestConformanceCaseV1[];
@@ -59,4 +56,4 @@ declare const GENERATED_WORKSPACE_PATH_PATTERNS: readonly GeneratedWorkspacePath
 declare const MANIFEST_CONFORMANCE_CASES: readonly AuthoringManifestConformanceCaseV1[];
 declare const projectAuthoringAdapter: ProjectAuthoringAdapterV1;
 
-export { type AuthoringManifestConformanceCaseV1, type AuthoringValidationResultV1, GENERATED_WORKSPACE_PATHS, GENERATED_WORKSPACE_PATH_PATTERNS, type GeneratedArtifactV1, type GeneratedAuthoringMetadataV1, type GeneratedPathPatternV1, MANIFEST_CONFORMANCE_CASES, type ProjectAuthoringAdapterV1, diagnosticCodesForValidationErrors, generateWorkspaceArtifacts, materializeManifest, projectAuthoringAdapter, validateManifest };
+export { type AuthoringManifestConformanceCaseV1, type AuthoringMetadataV1, type AuthoringValidationResultV1, GENERATED_WORKSPACE_PATHS, GENERATED_WORKSPACE_PATH_PATTERNS, type GeneratedArtifactV1, type GeneratedPathPatternV1, MANIFEST_CONFORMANCE_CASES, type ProjectAuthoringAdapterV1, diagnosticCodesForValidationErrors, generateWorkspaceArtifacts, materializeManifest, projectAuthoringAdapter, validateManifest };

package/dist/authoring/index.js

@@ -7,9 +7,9 @@ import {
   materializeManifest,
   projectAuthoringAdapter,
   validateManifest
-} from "../chunk-7ADPYKFT.js";
-import "../chunk-SFOAY5H4.js";
-import "../chunk-SACZWUA6.js";
+} from "../chunk-QLSK3DYO.js";
+import "../chunk-EY2LL5WD.js";
+import "../chunk-JUGQ6F3N.js";
 import "../chunk-PZ5AY32C.js";
 export {
   GENERATED_WORKSPACE_PATHS,

package/dist/authoring-compiler.d.ts

@@ -4,7 +4,7 @@ type MaterializeWorkspaceOptions = {
     /** Scaffolding-only. Existing build/test paths leave seed files untouched. */
     readonly writeMissingSeeds?: boolean;
 };
-type MaterializedWorkspaceReceipt = {
+type MaterializedWorkspaceResult = {
     readonly schemaVersion: 1;
     readonly projectRoot: string;
     readonly authoritativeFiles: number;
@@ -22,6 +22,6 @@ type MaterializedWorkspaceReceipt = {
  * scaffolding caller explicitly opts in. No test state or projection artifact
  * is emitted.
  */
-declare function materializeWorkspace(options: MaterializeWorkspaceOptions): Promise<MaterializedWorkspaceReceipt>;
+declare function materializeWorkspace(options: MaterializeWorkspaceOptions): Promise<MaterializedWorkspaceResult>;
 
-export { type MaterializeWorkspaceOptions, type MaterializedWorkspaceReceipt, materializeWorkspace };
+export { type MaterializeWorkspaceOptions, type MaterializedWorkspaceResult, materializeWorkspace };

package/dist/authoring-compiler.js

@@ -1,10 +1,9 @@
 import {
   materializeWorkspace
-} from "./chunk-P6IJ5YVY.js";
-import "./chunk-7ADPYKFT.js";
-import "./chunk-UNVCT5Z7.js";
-import "./chunk-SFOAY5H4.js";
-import "./chunk-SACZWUA6.js";
+} from "./chunk-2WJSQQT7.js";
+import "./chunk-QLSK3DYO.js";
+import "./chunk-EY2LL5WD.js";
+import "./chunk-JUGQ6F3N.js";
 import "./chunk-PZ5AY32C.js";
 export {
   materializeWorkspace

package/dist/{authoring-materialize-cli.js → authoring-generate-cli.js}

@@ -1,17 +1,16 @@
 #!/usr/bin/env node
 import {
   materializeWorkspace
-} from "./chunk-P6IJ5YVY.js";
-import "./chunk-7ADPYKFT.js";
-import "./chunk-UNVCT5Z7.js";
-import "./chunk-SFOAY5H4.js";
-import "./chunk-SACZWUA6.js";
+} from "./chunk-2WJSQQT7.js";
+import "./chunk-QLSK3DYO.js";
+import "./chunk-EY2LL5WD.js";
+import "./chunk-JUGQ6F3N.js";
 import "./chunk-PZ5AY32C.js";
 
-// src/authoring-materialize-cli.ts
+// src/authoring-generate-cli.ts
 var options = parseArgs(process.argv.slice(2));
-var receipt = await materializeWorkspace(options);
-console.log(JSON.stringify(receipt, null, 2));
+var result = await materializeWorkspace(options);
+console.log(JSON.stringify(result, null, 2));
 function parseArgs(argv) {
   let manifestPath;
   let projectRoot;
@@ -43,4 +42,4 @@ function parseArgs(argv) {
     ...writeMissingSeeds ? { writeMissingSeeds: true } : {}
   };
 }
-//# sourceMappingURL=authoring-materialize-cli.js.map
+//# sourceMappingURL=authoring-generate-cli.js.map

package/dist/authoring-generate-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/authoring-generate-cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { materializeWorkspace } from \"./authoring/materialize-workspace.js\";\n\nconst options = parseArgs(process.argv.slice(2));\nconst result = await materializeWorkspace(options);\nconsole.log(JSON.stringify(result, null, 2));\n\nfunction parseArgs(argv: readonly string[]): {\n  readonly manifestPath: string;\n  readonly projectRoot?: string;\n  readonly writeMissingSeeds?: boolean;\n} {\n  let manifestPath: string | undefined;\n  let projectRoot: string | undefined;\n  let writeMissingSeeds = false;\n  for (let index = 0; index < argv.length; index += 1) {\n    const arg = argv[index];\n    if (arg === \"--manifest\") {\n      manifestPath = argv[index + 1];\n      index += 1;\n      continue;\n    }\n    if (arg === \"--project-root\") {\n      projectRoot = argv[index + 1];\n      index += 1;\n      continue;\n    }\n    if (arg === \"--write-missing-seeds\") {\n      writeMissingSeeds = true;\n      continue;\n    }\n    throw new Error(`Unknown argument '${arg}'.`);\n  }\n  if (!manifestPath) {\n    throw new Error(\"--manifest is required.\");\n  }\n  return {\n    manifestPath,\n    ...(projectRoot === undefined ? {} : { projectRoot }),\n    ...(writeMissingSeeds ? { writeMissingSeeds: true } : {}),\n  };\n}\n"],"mappings":";;;;;;;;;;AAGA,IAAM,UAAU,UAAU,QAAQ,KAAK,MAAM,CAAC,CAAC;AAC/C,IAAM,SAAS,MAAM,qBAAqB,OAAO;AACjD,QAAQ,IAAI,KAAK,UAAU,QAAQ,MAAM,CAAC,CAAC;AAE3C,SAAS,UAAU,MAIjB;AACA,MAAI;AACJ,MAAI;AACJ,MAAI,oBAAoB;AACxB,WAAS,QAAQ,GAAG,QAAQ,KAAK,QAAQ,SAAS,GAAG;AACnD,UAAM,MAAM,KAAK,KAAK;AACtB,QAAI,QAAQ,cAAc;AACxB,qBAAe,KAAK,QAAQ,CAAC;AAC7B,eAAS;AACT;AAAA,IACF;AACA,QAAI,QAAQ,kBAAkB;AAC5B,oBAAc,KAAK,QAAQ,CAAC;AAC5B,eAAS;AACT;AAAA,IACF;AACA,QAAI,QAAQ,yBAAyB;AACnC,0BAAoB;AACpB;AAAA,IACF;AACA,UAAM,IAAI,MAAM,qBAAqB,GAAG,IAAI;AAAA,EAC9C;AACA,MAAI,CAAC,cAAc;AACjB,UAAM,IAAI,MAAM,yBAAyB;AAAA,EAC3C;AACA,SAAO;AAAA,IACL;AAAA,IACA,GAAI,gBAAgB,SAAY,CAAC,IAAI,EAAE,YAAY;AAAA,IACnD,GAAI,oBAAoB,EAAE,mBAAmB,KAAK,IAAI,CAAC;AAAA,EACzD;AACF;","names":[]}

package/dist/browser-interaction.d.ts

@@ -111,8 +111,8 @@ declare const gameplaySemanticEffectSchema: z.ZodUnion<readonly [z.ZodObject<{
 declare const browserInteractionDiagnosticSchema: z.ZodObject<{
     code: z.ZodString;
     severity: z.ZodEnum<{
-        error: "error";
         warning: "warning";
+        error: "error";
     }>;
     message: z.ZodString;
     surface: z.ZodOptional<z.ZodString>;
@@ -190,8 +190,8 @@ declare const browserInteractionActuatorSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -225,8 +225,8 @@ declare const browserInteractionPointerTargetSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -315,8 +315,8 @@ declare const browserGameplayInteractionSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -350,8 +350,8 @@ declare const browserGameplayInteractionSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -365,8 +365,8 @@ declare const browserGameplayInteractionSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -458,8 +458,8 @@ declare const browserGameplaySurfaceSnapshotSchema: z.ZodObject<{
             diagnostics: z.ZodArray<z.ZodObject<{
                 code: z.ZodString;
                 severity: z.ZodEnum<{
-                    error: "error";
                     warning: "warning";
+                    error: "error";
                 }>;
                 message: z.ZodString;
                 surface: z.ZodOptional<z.ZodString>;
@@ -493,8 +493,8 @@ declare const browserGameplaySurfaceSnapshotSchema: z.ZodObject<{
             diagnostics: z.ZodArray<z.ZodObject<{
                 code: z.ZodString;
                 severity: z.ZodEnum<{
-                    error: "error";
                     warning: "warning";
+                    error: "error";
                 }>;
                 message: z.ZodString;
                 surface: z.ZodOptional<z.ZodString>;
@@ -508,8 +508,8 @@ declare const browserGameplaySurfaceSnapshotSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -523,8 +523,8 @@ declare const browserGameplaySurfaceSnapshotSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -616,8 +616,8 @@ declare const browserSemanticSurfaceSnapshotSchema: z.ZodObject<{
             diagnostics: z.ZodArray<z.ZodObject<{
                 code: z.ZodString;
                 severity: z.ZodEnum<{
-                    error: "error";
                     warning: "warning";
+                    error: "error";
                 }>;
                 message: z.ZodString;
                 surface: z.ZodOptional<z.ZodString>;
@@ -651,8 +651,8 @@ declare const browserSemanticSurfaceSnapshotSchema: z.ZodObject<{
             diagnostics: z.ZodArray<z.ZodObject<{
                 code: z.ZodString;
                 severity: z.ZodEnum<{
-                    error: "error";
                     warning: "warning";
+                    error: "error";
                 }>;
                 message: z.ZodString;
                 surface: z.ZodOptional<z.ZodString>;
@@ -666,8 +666,8 @@ declare const browserSemanticSurfaceSnapshotSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -681,8 +681,8 @@ declare const browserSemanticSurfaceSnapshotSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -699,8 +699,8 @@ declare const browserUnknownSurfaceSnapshotSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;
@@ -797,8 +797,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
                 diagnostics: z.ZodArray<z.ZodObject<{
                     code: z.ZodString;
                     severity: z.ZodEnum<{
-                        error: "error";
                         warning: "warning";
+                        error: "error";
                     }>;
                     message: z.ZodString;
                     surface: z.ZodOptional<z.ZodString>;
@@ -832,8 +832,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
                 diagnostics: z.ZodArray<z.ZodObject<{
                     code: z.ZodString;
                     severity: z.ZodEnum<{
-                        error: "error";
                         warning: "warning";
+                        error: "error";
                     }>;
                     message: z.ZodString;
                     surface: z.ZodOptional<z.ZodString>;
@@ -847,8 +847,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
             diagnostics: z.ZodArray<z.ZodObject<{
                 code: z.ZodString;
                 severity: z.ZodEnum<{
-                    error: "error";
                     warning: "warning";
+                    error: "error";
                 }>;
                 message: z.ZodString;
                 surface: z.ZodOptional<z.ZodString>;
@@ -862,8 +862,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -879,8 +879,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             surface: z.ZodOptional<z.ZodString>;
@@ -894,8 +894,8 @@ declare const browserInteractionSnapshotSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         surface: z.ZodOptional<z.ZodString>;

package/dist/{chunk-P6IJ5YVY.js → chunk-2WJSQQT7.js}

@@ -1,12 +1,9 @@
 import {
   generateWorkspaceArtifacts
-} from "./chunk-7ADPYKFT.js";
-import {
-  compareReferenceGameCanonicalStrings
-} from "./chunk-UNVCT5Z7.js";
+} from "./chunk-QLSK3DYO.js";
 import {
   WORKSPACE_CODEGEN_OWNERSHIP
-} from "./chunk-SACZWUA6.js";
+} from "./chunk-JUGQ6F3N.js";
 
 // src/authoring/materialize-workspace.ts
 import { createHash, randomUUID } from "crypto";
@@ -52,7 +49,7 @@ async function materializeWorkspace(options) {
     const actual = createHash("sha256").update(bytes).digest("hex");
     if (actual !== artifact.contentSha256) {
       throw new Error(
-        `Generated ${artifact.path} digest does not match its SDK receipt.`
+        `Generated ${artifact.path} digest does not match its declared digest.`
       );
     }
     records.push({
@@ -62,7 +59,7 @@ async function materializeWorkspace(options) {
     });
   }
   records.sort(
-    (left, right) => compareReferenceGameCanonicalStrings(left.path, right.path)
+    (left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0
   );
   return {
     schemaVersion: 1,
@@ -74,6 +71,7 @@ async function materializeWorkspace(options) {
   };
 }
 async function loadManifest(options) {
+  const typesEntry = await resolveCurrentSdkTypesFacade();
   const entryPath = path.join(
     options.projectRoot,
     "node_modules/.cache/dreamboard-workspace-compiler",
@@ -89,7 +87,9 @@ async function loadManifest(options) {
       format: "esm",
       platform: "node",
       target: "node24",
-      packages: "external",
+      alias: {
+        "@dreamboard-games/sdk/types": typesEntry
+      },
       sourcemap: "inline",
       logLevel: "silent"
     });
@@ -104,6 +104,18 @@ async function loadManifest(options) {
     await rm(entryPath, { force: true });
   }
 }
+async function resolveCurrentSdkTypesFacade() {
+  const candidates = [
+    path.resolve(import.meta.dirname, "../types.ts"),
+    path.resolve(import.meta.dirname, "types.js")
+  ];
+  for (const candidate of candidates) {
+    if (await isFile(candidate)) return candidate;
+  }
+  throw new Error(
+    `Could not resolve the current @dreamboard-games/sdk/types facade from ${import.meta.dirname}.`
+  );
+}
 async function writeAuthoritativeFile(destination, content) {
   const temporaryPath = path.join(
     path.dirname(destination),
@@ -151,4 +163,4 @@ async function isFile(filePath) {
 export {
   materializeWorkspace
 };
-//# sourceMappingURL=chunk-P6IJ5YVY.js.map
+//# sourceMappingURL=chunk-2WJSQQT7.js.map

package/dist/chunk-2WJSQQT7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/authoring/materialize-workspace.ts"],"sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport { mkdir, readFile, rename, rm, stat, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport { WORKSPACE_CODEGEN_OWNERSHIP } from \"@dreamboard-games/workspace-codegen\";\nimport { build } from \"esbuild\";\nimport { generateWorkspaceArtifacts } from \"./adapter.js\";\n\nexport type MaterializeWorkspaceOptions = {\n  readonly manifestPath: string;\n  readonly projectRoot?: string;\n  /** Scaffolding-only. Existing build/test paths leave seed files untouched. */\n  readonly writeMissingSeeds?: boolean;\n};\n\nexport type MaterializedWorkspaceResult = {\n  readonly schemaVersion: 1;\n  readonly projectRoot: string;\n  readonly authoritativeFiles: number;\n  readonly seededFiles: number;\n  readonly artifacts: readonly {\n    readonly path: string;\n    readonly ownership: \"authoritative\";\n    readonly sha256: `sha256:${string}`;\n  }[];\n  readonly digest: `sha256:${string}`;\n};\n\ntype ManifestModule = {\n  readonly default?: unknown;\n  readonly manifest?: unknown;\n};\n\nconst authoritativePaths = new Set(\n  WORKSPACE_CODEGEN_OWNERSHIP.dynamic.generatedFiles,\n);\n\n/**\n * Materialize SDK-owned workspace contracts from authored manifest source.\n * Authoritative files are always replaced. Seed files are untouched unless a\n * scaffolding caller explicitly opts in. No test state or projection artifact\n * is emitted.\n */\nexport async function materializeWorkspace(\n  options: MaterializeWorkspaceOptions,\n): Promise<MaterializedWorkspaceResult> {\n  const projectRoot = path.resolve(options.projectRoot ?? process.cwd());\n  const manifestPath = resolveProjectPath(projectRoot, options.manifestPath);\n  if (!(await isFile(manifestPath))) {\n    throw new Error(`Manifest source does not exist: ${manifestPath}.`);\n  }\n  const manifest = await loadManifest({ manifestPath, projectRoot });\n  const artifacts = generateWorkspaceArtifacts(manifest);\n  const emittedAuthoritative = new Set(\n    artifacts\n      .filter(({ ownership }) => ownership === \"authoritative\")\n      .map(({ path: artifactPath }) => artifactPath),\n  );\n  assertExactAuthoritativeInventory(emittedAuthoritative);\n\n  let seededFiles = 0;\n  const records: Array<{\n    readonly path: string;\n    readonly ownership: \"authoritative\";\n    readonly sha256: `sha256:${string}`;\n  }> = [];\n  for (const artifact of artifacts) {\n    const destination = resolveProjectPath(projectRoot, artifact.path);\n    if (artifact.ownership === \"seed\") {\n      if (!options.writeMissingSeeds || (await isFile(destination))) {\n        continue;\n      }\n    }\n    await mkdir(path.dirname(destination), { recursive: true });\n    if (artifact.ownership === \"authoritative\") {\n      await writeAuthoritativeFile(destination, artifact.content);\n    } else {\n      await writeFile(destination, artifact.content);\n    }\n    if (artifact.ownership === \"seed\") {\n      seededFiles += 1;\n      continue;\n    }\n    const bytes = await readFile(destination);\n    const actual = createHash(\"sha256\").update(bytes).digest(\"hex\");\n    if (actual !== artifact.contentSha256) {\n      throw new Error(\n        `Generated ${artifact.path} digest does not match its declared digest.`,\n      );\n    }\n    records.push({\n      path: artifact.path,\n      ownership: \"authoritative\",\n      sha256: `sha256:${actual}`,\n    });\n  }\n  records.sort((left, right) =>\n    left.path < right.path ? -1 : left.path > right.path ? 1 : 0,\n  );\n  return {\n    schemaVersion: 1,\n    projectRoot,\n    authoritativeFiles: records.length,\n    seededFiles,\n    artifacts: records,\n    digest: `sha256:${createHash(\"sha256\")\n      .update(JSON.stringify(records))\n      .digest(\"hex\")}`,\n  };\n}\n\nasync function loadManifest(options: {\n  readonly manifestPath: string;\n  readonly projectRoot: string;\n}): Promise<unknown> {\n  const typesEntry = await resolveCurrentSdkTypesFacade();\n  const entryPath = path.join(\n    options.projectRoot,\n    \"node_modules/.cache/dreamboard-workspace-compiler\",\n    `manifest-${process.pid}-${randomUUID()}.mjs`,\n  );\n  await mkdir(path.dirname(entryPath), { recursive: true });\n  try {\n    const result = await build({\n      entryPoints: [options.manifestPath],\n      outfile: entryPath,\n      absWorkingDir: options.projectRoot,\n      bundle: true,\n      format: \"esm\",\n      platform: \"node\",\n      target: \"node24\",\n      alias: {\n        \"@dreamboard-games/sdk/types\": typesEntry,\n      },\n      sourcemap: \"inline\",\n      logLevel: \"silent\",\n    });\n    void result;\n    const loaded = (await import(\n      pathToFileURL(entryPath).href\n    )) as ManifestModule;\n    const manifest = loaded.manifest ?? loaded.default;\n    if (!manifest || typeof manifest !== \"object\") {\n      throw new Error(\"Manifest source must export a manifest object.\");\n    }\n    return manifest;\n  } finally {\n    await rm(entryPath, { force: true });\n  }\n}\n\nasync function resolveCurrentSdkTypesFacade(): Promise<string> {\n  const candidates = [\n    path.resolve(import.meta.dirname, \"../types.ts\"),\n    path.resolve(import.meta.dirname, \"types.js\"),\n  ];\n  for (const candidate of candidates) {\n    if (await isFile(candidate)) return candidate;\n  }\n  throw new Error(\n    `Could not resolve the current @dreamboard-games/sdk/types facade from ${import.meta.dirname}.`,\n  );\n}\n\nasync function writeAuthoritativeFile(\n  destination: string,\n  content: string,\n): Promise<void> {\n  const temporaryPath = path.join(\n    path.dirname(destination),\n    `.${path.basename(destination)}.${process.pid}.${randomUUID()}.tmp`,\n  );\n  try {\n    await writeFile(temporaryPath, content);\n    await rename(temporaryPath, destination);\n  } finally {\n    await rm(temporaryPath, { force: true });\n  }\n}\n\nfunction assertExactAuthoritativeInventory(emitted: ReadonlySet<string>): void {\n  const missing = [...authoritativePaths].filter(\n    (value) => !emitted.has(value),\n  );\n  const unexpected = [...emitted].filter(\n    (value) => !authoritativePaths.has(value),\n  );\n  if (missing.length > 0 || unexpected.length > 0) {\n    throw new Error(\n      `SDK workspace ownership mismatch (missing: ${missing.join(\", \") || \"none\"}; unexpected: ${unexpected.join(\", \") || \"none\"}).`,\n    );\n  }\n}\n\nfunction resolveProjectPath(projectRoot: string, value: string): string {\n  if (\n    typeof value !== \"string\" ||\n    value.length === 0 ||\n    path.isAbsolute(value) ||\n    value.split(/[\\\\/]+/).some((segment) => segment === \"..\")\n  ) {\n    throw new Error(`Workspace path must be project-relative: ${value}.`);\n  }\n  const resolved = path.resolve(projectRoot, value);\n  if (!resolved.startsWith(`${projectRoot}${path.sep}`)) {\n    throw new Error(`Workspace path escapes the project root: ${value}.`);\n  }\n  return resolved;\n}\n\nasync function isFile(filePath: string): Promise<boolean> {\n  return stat(filePath)\n    .then((value) => value.isFile())\n    .catch((error: unknown) => {\n      if (\n        typeof error === \"object\" &&\n        error !== null &&\n        \"code\" in error &&\n        error.code === \"ENOENT\"\n      ) {\n        return false;\n      }\n      throw error;\n    });\n}\n"],"mappings":"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","names":[]}