@vampgg/cli 1.0.0-beta.1

package/dist/generate-mutation-schema-DPVvPX4h.mjs

@@ -0,0 +1,1080 @@
+import { createRequire } from "node:module";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { parse, printParseErrorCode } from "jsonc-parser";
+import { BinarySchema } from "bebop";
+//#region src/config/loader.ts
+/** Parse jsonc, throwing a clear error (with offsets) on any syntax error. */
+function parseJsoncStrict(raw, resolved) {
+	const errors = [];
+	const config = parse(raw, errors, { allowTrailingComma: true });
+	if (errors.length) throw new Error(`Failed to parse ${resolved}: ${errors.map((e) => `${printParseErrorCode(e.error)}@${e.offset}`).join(", ")}`);
+	if (!config) throw new Error(`Failed to parse ${resolved}: empty document`);
+	return config;
+}
+function loadBebopConfig(cwd, configPath) {
+	const resolved = resolve(cwd, configPath ?? "bebop.json");
+	let raw;
+	try {
+		raw = readFileSync(resolved, "utf-8");
+	} catch {
+		throw new Error(`bebop.json not found at ${resolved}`);
+	}
+	return parseJsoncStrict(raw, resolved);
+}
+function loadVampConfig(cwd) {
+	const configPath = resolve(cwd, "vamp.json");
+	let raw;
+	try {
+		raw = readFileSync(configPath, "utf-8");
+	} catch {
+		throw new Error(`vamp.json not found in ${cwd}`);
+	}
+	const config = parseJsoncStrict(raw, configPath);
+	const { schemas, outFile } = config;
+	if (!schemas?.entity || !schemas?.actions || !schemas?.state || !schemas?.tags) throw new Error("vamp.schemas must define entity, actions, state, and tags paths");
+	if (!outFile) throw new Error("vamp.outFile is required");
+	return config;
+}
+//#endregion
+//#region src/generators/parse-bop.ts
+const WireBaseType = {
+	[-1]: "bool",
+	[-2]: "byte",
+	[-3]: "uint16",
+	[-4]: "int16",
+	[-5]: "uint32",
+	[-6]: "int32",
+	[-7]: "uint64",
+	[-8]: "int64",
+	[-9]: "float32",
+	[-10]: "float64",
+	[-11]: "string",
+	[-12]: "guid",
+	[-13]: "date"
+};
+/**
+* Scalar type names that only appear in *source* form (never as a distinct
+* wire base type). `uint8` is a bebop alias for `byte`; both are accepted in
+* `.bop` source but compile to the same wire type.
+*/
+const SOURCE_ONLY_SCALARS = ["uint8"];
+const WireTypeKind = {
+	Struct: 1,
+	Message: 2,
+	Union: 3,
+	Enum: 4
+};
+function resolveTypeName(typeId, schema) {
+	if (typeId < 0) return WireBaseType[typeId] ?? `unknown(${typeId})`;
+	return schema.getDefinition(typeId).name;
+}
+function parseField(name, field, schema) {
+	const props = field.fieldProperties;
+	const isArray = props.type === "array";
+	const isMap = props.type === "map";
+	let typeName;
+	let memberTypeName;
+	let keyTypeName;
+	let valueTypeName;
+	if (isArray) {
+		typeName = "array";
+		memberTypeName = resolveTypeName(props.memberTypeId, schema);
+	} else if (isMap) {
+		typeName = "map";
+		keyTypeName = resolveTypeName(props.keyTypeId, schema);
+		valueTypeName = resolveTypeName(props.valueTypeId, schema);
+	} else typeName = resolveTypeName(field.typeId, schema);
+	return {
+		name,
+		typeId: field.typeId,
+		isArray,
+		isMap,
+		typeName,
+		memberTypeName,
+		keyTypeName,
+		valueTypeName,
+		constantValue: field.constantValue
+	};
+}
+function parseSchema(bebopSchemaBytes) {
+	const schema = new BinarySchema(bebopSchemaBytes);
+	schema.get();
+	const ast = schema.ast;
+	const definitions = /* @__PURE__ */ new Map();
+	for (const [name, def] of Object.entries(ast.definitions)) {
+		if (def.kind === WireTypeKind.Enum) {
+			definitions.set(name, {
+				name,
+				kind: "enum",
+				fields: []
+			});
+			continue;
+		}
+		if (def.kind === WireTypeKind.Union) {
+			const branches = def.branches.map((b) => ({
+				discriminator: b.discriminator,
+				typeName: schema.getDefinition(b.typeId).name
+			}));
+			definitions.set(name, {
+				name,
+				kind: "union",
+				fields: [],
+				branches
+			});
+			continue;
+		}
+		const kind = def.kind === WireTypeKind.Struct ? "struct" : "message";
+		const fields = [];
+		const defWithFields = def;
+		if (defWithFields.fields) for (const [fieldName, field] of Object.entries(defWithFields.fields)) fields.push(parseField(fieldName, field, schema));
+		definitions.set(name, {
+			name,
+			kind,
+			fields
+		});
+	}
+	return { definitions };
+}
+/**
+* Recover the compiled `BEBOP_SCHEMA` byte array from a generated `bebop.ts`.
+*
+* Every token is validated to be an integer in 0-255; a non-numeric token, a
+* trailing comma, or any format drift throws (naming the bad token) instead of
+* silently coercing `NaN` to `0` and corrupting the binary schema.
+*/
+function scrapeSchema(content, path) {
+	const match = content.match(/export const BEBOP_SCHEMA\s*=\s*new Uint8Array\s*\(\s*\[\s*([\s\S]*?)\s*\]\s*\)/);
+	if (!match) throw new Error(`Could not find BEBOP_SCHEMA in ${path}`);
+	const bytes = match[1].split(",").map((s) => s.trim()).filter((s) => s.length > 0).map((s, i) => {
+		const n = Number(s);
+		if (!Number.isInteger(n) || n < 0 || n > 255) throw new Error(`BEBOP_SCHEMA byte ${i} ('${s}') in ${path} is not an integer in 0-255; the generated schema is corrupt — re-run bebopc build.`);
+		return n;
+	});
+	return new Uint8Array(bytes);
+}
+function loadSchemaFromFile(bebopTsPath) {
+	return scrapeSchema(readFileSync(bebopTsPath, "utf-8"), bebopTsPath);
+}
+function loadAndParseSchema(bebopTsPath) {
+	return parseSchema(loadSchemaFromFile(bebopTsPath));
+}
+//#endregion
+//#region src/generators/emit-components.ts
+/**
+* Emit the component-id map. Ids are derived from the bebop field tag
+* (`constantValue`), NOT the array position, so they are stable across field
+* reorder/insert/remove and align with the wire format. This is a deliberate,
+* breaking change from the previous positional scheme — see plan 14 §4.6.
+*/
+function emitComponents(entity) {
+	const entries = [];
+	for (const f of entity.fields) {
+		if (f.name === "tags") continue;
+		const tag = f.constantValue;
+		if (tag == null) throw new Error(`Entity field '${f.name}' has no bebop field tag; cannot derive a stable component id.`);
+		entries.push(`${f.name}: ${tag}`);
+	}
+	return `/**
+ * Component-id map for this schema, keyed by {@link Entity} field name. Ids come
+ * from the bebop field tag (stable across field reorder), not array position.
+ * Pass these to queries (\`q.every(components.health)\`) and \`world.get\`/\`put\`.
+ */
+export const components = { ${entries.join(", ")} } as const satisfies Record<keyof Omit<Entity, "tags">, number>;`;
+}
+//#endregion
+//#region src/generators/emit-delta.ts
+/**
+* Canonical scalar vocabulary, derived from the single source of truth
+* (`WireBaseType` in parse-bop.ts) plus the source-only aliases. Deriving it
+* here — rather than re-declaring a parallel list — guarantees the parser and
+* the emitter agree on what counts as a scalar. A drift-guard test asserts
+* every `WireBaseType` name also has a `scalarToTs` case.
+*/
+const SCALAR_TYPES = new Set([...Object.values(WireBaseType), ...SOURCE_ONLY_SCALARS]);
+function scalarToTs(type) {
+	switch (type) {
+		case "bool": return "boolean";
+		case "byte":
+		case "uint8":
+		case "int16":
+		case "uint16":
+		case "int32":
+		case "uint32":
+		case "float32":
+		case "float64": return "number";
+		case "int64":
+		case "uint64": return "bigint";
+		case "string":
+		case "guid": return "string";
+		case "date": return "Date";
+		default: return type;
+	}
+}
+function isScalar(typeName) {
+	return SCALAR_TYPES.has(typeName);
+}
+function deltaTypeForField$1(field, schema) {
+	if (field.isArray) {
+		const itemType = scalarToTs(field.memberTypeName);
+		return `{ set?: ${itemType}[]; add?: ${itemType}[]; remove?: ${itemType}[] }`;
+	}
+	if (isScalar(field.typeName)) return scalarToTs(field.typeName);
+	const deltaName = `${field.typeName}Delta`;
+	if (schema.definitions.has(deltaName)) return deltaName;
+	throw new Error(`No '${deltaName}' found in the compiled schema for Entity field '${field.name}'. The mutation schema generation step should have produced it; re-run 'vamp generate'.`);
+}
+function emitDelta(entity, schema) {
+	return `/**
+ * Partial, CRDT-style mutation over an {@link Entity}: scalars are
+ * last-writer-wins, array fields carry \`set\`/\`add\`/\`remove\`, and pool/vector
+ * fields use additive \`*Delta\` counters. Apply with {@link materializeDelta} or
+ * {@link mergeDelta}; combine with {@link accumulateDelta}.
+ */
+export type EntityDelta = {\n${entity.fields.map((f) => {
+		if (f.name === "tags") return "  tags?: Tags[];";
+		return `  ${f.name}?: ${deltaTypeForField$1(f, schema)};`;
+	}).join("\n")}\n};`;
+}
+//#endregion
+//#region src/generators/emit-helpers.ts
+function hasDeltaDef(field, schema) {
+	return schema.definitions.has(`${field.typeName}Delta`);
+}
+/** True when the entity has at least one array field (so the shared array applier is needed). */
+function needsArrayHelper(entity) {
+	return entity.fields.some((f) => f.isArray);
+}
+function needsPoolHelper(entity, schema) {
+	return entity.fields.some((f) => !f.isArray && !isScalar(f.typeName) && hasDeltaDef(f, schema));
+}
+/** Type-correct default literal for a component sub-field (used by materializeDelta). */
+function defaultForField(bf) {
+	if (bf.isArray) return "[]";
+	if (isScalar(bf.typeName)) {
+		if (bf.typeName === "string" || bf.typeName === "guid") return "''";
+		if (bf.typeName === "bool") return "false";
+		if (bf.typeName === "date") return "new Date(0)";
+		return "0";
+	}
+	return "undefined as any";
+}
+/**
+* Import of the canonical delta-algebra appliers from `@vampgg/ecs`, narrowed to
+* exactly the helpers this entity's fields use. The set/add/remove (array) and
+* additive (pool) semantics live in `@vampgg/ecs` so `materializeDelta`,
+* `mergeDelta`, and `accumulateDelta` cannot drift; the generated code only
+* dispatches per field. Returns "" when the entity has neither array nor pool
+* fields (so no unused import is emitted).
+*/
+function emitHelperImports(entity, schema) {
+	const names = [];
+	if (needsArrayHelper(entity)) names.push("applyArrayDelta", "accumulateArrayDelta");
+	if (needsPoolHelper(entity, schema)) names.push("applyPoolDelta", "accumulatePoolDelta");
+	if (names.length === 0) return "";
+	return `import { ${names.join(", ")} } from "@vampgg/ecs";`;
+}
+function emitHelpers(entity, schema) {
+	return [
+		emitMaterializeDelta(entity, schema),
+		emitMergeDelta(entity, schema),
+		emitAccumulateDelta(entity, schema)
+	].filter(Boolean).join("\n\n");
+}
+function emitMaterializeDelta(entity, schema) {
+	return `/**
+ * Build a full {@link Entity} from a {@link EntityDelta} and optional \`base\`,
+ * honoring array set/add/remove and additive pool semantics.
+ */
+export function materializeDelta(delta: EntityDelta, base?: Partial<Entity>): Entity {
+  return {
+${entity.fields.map((f) => {
+		if (f.name === "tags") return `    tags: delta.tags ?? base?.tags ?? []`;
+		if (f.isArray) return `    ${f.name}: applyArrayDelta(base?.${f.name} ?? [], delta.${f.name})`;
+		if (!isScalar(f.typeName) && hasDeltaDef(f, schema)) {
+			const baseMsg = schema.definitions.get(f.typeName);
+			const defaultFields = baseMsg ? baseMsg.fields.map((bf) => `${bf.name}: ${defaultForField(bf)}`).join(", ") : "";
+			return `    ${f.name}: delta.${f.name} ? applyPoolDelta(base?.${f.name} ?? { ${defaultFields} }, delta.${f.name} as Record<string, number>) : base?.${f.name} ?? { ${defaultFields} }`;
+		}
+		if (isScalar(f.typeName)) {
+			const defaultVal = f.typeName === "string" || f.typeName === "guid" ? "''" : "0";
+			return `    ${f.name}: delta.${f.name} ?? base?.${f.name} ?? ${defaultVal}`;
+		}
+		return `    ${f.name}: delta.${f.name} ? { ...base?.${f.name}, ...delta.${f.name} } as any : base?.${f.name} as any`;
+	}).join(",\n")},
+  } as Entity;
+}`;
+}
+function emitMergeDelta(entity, schema) {
+	return `/**
+ * Apply \`delta\` onto \`entity\` in place — same set/add/remove and additive pool
+ * rules as {@link materializeDelta}.
+ */
+export function mergeDelta(entity: Entity, delta: EntityDelta): void {
+${entity.fields.map((f) => {
+		if (f.name === "tags") return `  if (delta.tags !== undefined) entity.tags = delta.tags;`;
+		if (f.isArray) return `  if (delta.${f.name}) entity.${f.name} = applyArrayDelta(entity.${f.name} ?? [], delta.${f.name});`;
+		if (!isScalar(f.typeName) && hasDeltaDef(f, schema)) return `  if (delta.${f.name}) entity.${f.name} = applyPoolDelta((entity.${f.name} ?? {}) as Record<string, number>, delta.${f.name} as Record<string, number>) as Entity[${JSON.stringify(f.name)}];`;
+		if (isScalar(f.typeName)) return `  if (delta.${f.name} !== undefined) entity.${f.name} = delta.${f.name};`;
+		return `  if (delta.${f.name}) Object.assign(entity.${f.name} ??= {} as any, delta.${f.name});`;
+	}).join("\n")}
+}`;
+}
+function emitAccumulateDelta(entity, schema) {
+	return `/**
+ * Fold \`from\` into \`to\`, collapsing two {@link EntityDelta}s into one equivalent
+ * delta (array/pool deltas combine additively). Returns the mutated \`to\`.
+ */
+export function accumulateDelta(from: EntityDelta, to: EntityDelta): EntityDelta {
+${entity.fields.map((f) => {
+		if (f.name === "tags") return `  if (from.tags !== undefined) to.tags = from.tags;`;
+		if (f.isArray) return `  if (from.${f.name}) to.${f.name} = accumulateArrayDelta(to.${f.name}, from.${f.name});`;
+		if (!isScalar(f.typeName) && hasDeltaDef(f, schema)) return `  if (from.${f.name}) to.${f.name} = accumulatePoolDelta(to.${f.name} as Record<string, number> | undefined, from.${f.name} as Record<string, number>) as EntityDelta[${JSON.stringify(f.name)}];`;
+		if (isScalar(f.typeName)) return `  if (from.${f.name} !== undefined) to.${f.name} = from.${f.name};`;
+		return `  if (from.${f.name}) to.${f.name} = { ...to.${f.name}, ...from.${f.name} };`;
+	}).join("\n")}
+  return to;
+}`;
+}
+//#endregion
+//#region src/generators/emit-factory.ts
+function emitFactory() {
+	return `/**
+ * {@link ECSOptions} for this schema — wires the {@link components} map and the
+ * delta algebra ({@link materializeDelta}/{@link mergeDelta}/{@link accumulateDelta})
+ * into an ECS world. \`createId\` mints new entity ids.
+ */
+export function createECSOptions(createId: () => string): ECSOptions<Entity, EntityDelta> {
+  return { createId, components, materializeDelta, mergeDelta, accumulateDelta };
+}`;
+}
+//#endregion
+//#region src/generators/emit-classes.ts
+function emitClasses(tagsType = "number") {
+	return `/**
+ * App-typed {@link ECSDurableObject}: this schema's \`Actions\`/\`Tags\`/\`Entity\`/
+ * \`EntityDelta\` are baked in, leaving \`UserSession\`/\`Context\`/\`UpdateArguments\`
+ * open. Subclass this as your game's durable object.
+ */
+export class GameECS<
+    UserSession extends {} = {},
+    Context extends {} = {},
+    UpdateArguments extends Array<unknown> = [],
+  > extends ECSDurableObject<
+    UserSession,
+    Context,
+    UpdateArguments,
+    Actions,
+    ${tagsType},
+    Entity,
+    EntityDelta,
+    Cloudflare.Env
+  > {}
+
+/** App-typed {@link ECSStorage} over this schema's {@link Entity}. */
+export class GameStorage extends ECSStorage<Entity> {}`;
+}
+//#endregion
+//#region src/generators/emit-game-context.ts
+/**
+* Emits the `GameContext` type alias exported near the bottom of the generated
+* file. It describes the server-environment context provided to RPC method
+* implementations, i.e. the tuple `[ECS<...>, WebSocket]` that the durable
+* object hands to the tempo router. RPC methods retrieve it via
+* `const [ecs, ws] = ctx.getEnvironment<GameContext>()`.
+*/
+function emitGameContext() {
+	return `/**
+ * Server environment handed to RPC methods, app-typed for this schema. Retrieve
+ * it inside a method with \`const [ecs, ws] = ctx.getEnvironment<GameContext>()\` —
+ * the \`[ECS, WebSocket]\` tuple carrying the live world.
+ */
+export type GameContext<
+  UserSession extends {} = {},
+  Context extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+> = RPCContext<UserSession, Context, UpdateArguments, Actions, Tags, Entity, EntityDelta>;`;
+}
+//#endregion
+//#region src/generators/emit-interest.ts
+/**
+* Emits the app-typed interest-managed broadcast wrapper exported near the bottom
+* of the generated file. It binds the schema's concrete `Entity`/`EntityDelta`/
+* `MutationScope` into the worker's generic `createInterestBroadcast` and supplies
+* the two app-specific defaults a developer would otherwise hand-write: the bebop
+* `encodeBatch` codec (which the worker package cannot import — it is per-app
+* codegen), and a first-key `resolveViewer` (the convention where the client
+* passes its viewer entity id as the first key of the observe request scope's
+* `mutations` map). The interest policy (`canSee`) is left to the app; with no
+* args every observer sees every mutation (global broadcast).
+*
+* A wrapper *function* (not a type alias) is required so the bound defaults exist
+* at runtime and `UserSession`/`Context`/`UpdateArguments` stay open at the call
+* site, mirroring `defineGameECSRuntime`/`GameContext`.
+*/
+function emitInterest() {
+	return `/**
+ * Interest-managed mutation broadcast bound to this schema. Supplies the bebop
+ * \`encodeBatch\` codec and a first-key \`resolveViewer\` default; pass \`canSee\` to
+ * scope what each observer sees, or omit \`config\` for a global broadcast.
+ */
+export function createGameInterestBroadcast<
+  UserSession extends {} = {},
+  Context extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+>(
+  config: Partial<
+    InterestBroadcastConfig<
+      GameContext<UserSession, Context, UpdateArguments>[0],
+      MutationScope,
+      Entity,
+      EntityDelta
+    >
+  > = {},
+) {
+  return createInterestBroadcast<
+    GameContext<UserSession, Context, UpdateArguments>[0],
+    MutationScope,
+    MutationScope,
+    Entity,
+    EntityDelta
+  >({
+    encodeBatch: (batch: MutationBatch<Entity, EntityDelta>): Uint8Array =>
+      new Uint8Array(
+        MutationScope.encode(
+          MutationScope({ mutations: batch as unknown as Map<string, MutationRecord> }),
+        ),
+      ),
+    resolveViewer: (record: MutationScope): string | undefined => {
+      if (!record.mutations) return undefined;
+      for (const key of record.mutations.keys()) return key;
+      return undefined;
+    },
+    ...config,
+  });
+}`;
+}
+//#endregion
+//#region src/generators/emit-runtime.ts
+/**
+* Emits the app-typed runtime wrappers exported near the bottom of the generated
+* file. These bake the schema's concrete `Actions`/`Tags`/`Entity`/`EntityDelta`
+* into the worker's generic {@link ECSRuntimeConfiguration}/{@link ECSRuntimeProvider}
+* (leaving `UserSession`/`Context`/`UpdateArguments` open, mirroring `GameECS`/
+* `GameContext`), and provide a `defineGameECSRuntime` wrapper so the worker entry
+* gets call-site type safety on `ecs`, `context`, `registerSystems`, `tickArgs`,
+* and `broadcastTick`.
+*
+* A wrapper *function* is required: a type alias alone cannot constrain the
+* worker's generic `defineECSRuntime`, so the provider's return type would not be
+* inferred at the call site.
+*/
+function emitRuntime() {
+	return `/** App-typed {@link ECSRuntimeConfiguration} — the worker runtime config with this schema's types baked in. */
+export type GameECSRuntimeConfiguration<
+  UserSession extends {} = {},
+  Context extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+> = ECSRuntimeConfiguration<UserSession, Context, UpdateArguments, Actions, Tags, Entity, EntityDelta>;
+
+/** Factory returning a {@link GameECSRuntimeConfiguration}; pass it to {@link defineGameECSRuntime}. */
+export type GameECSRuntimeProvider<
+  UserSession extends {} = {},
+  Context extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+> = () => GameECSRuntimeConfiguration<UserSession, Context, UpdateArguments>;
+
+/**
+ * Register the worker's runtime provider with call-site type safety on \`ecs\`,
+ * \`context\`, \`registerSystems\`, \`tickArgs\`, and \`broadcastTick\`. Call once from
+ * the worker entry.
+ */
+export function defineGameECSRuntime<
+  UserSession extends {} = {},
+  Context extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+>(provider: GameECSRuntimeProvider<UserSession, Context, UpdateArguments>): void {
+  defineECSRuntime(provider);
+}`;
+}
+//#endregion
+//#region src/generators/emit-systems.ts
+/**
+* Emits app-typed aliases for the generic system types and factories from
+* `@vampgg/ecs` (`System.ts`). Each underlying type is generic over
+* `<State, UpdateArguments, Actions, Tags, E, D>`; this bakes the schema's
+* concrete `Actions`/`Tags`/`Entity`/`EntityDelta` into the last four slots and
+* leaves `State`/`UpdateArguments` open (mirroring `GameECS`/`GameContext`). The
+* point is developer ergonomics: game code calls `createGameEntitySystem(...)`
+* and gets a fully-typed `world` inside the executor without ever restating
+* `Tags`, `Entity`, or `EntityDelta`.
+*
+* The `createGame*` wrappers are *functions* (not just aliases) so the call site
+* keeps inference on `State`/`UpdateArguments` while the concrete types stay
+* pinned — a type alias alone cannot constrain the generic factory. Wrapper
+* parameter types are read back off the emitted aliases (e.g.
+* `GameEntitySystem<...>["execute"]`) so they cannot drift from `System.ts` and
+* we avoid importing `ECS`/`Archetype`/`CustomAction` just to restate them.
+*/
+function emitSystems() {
+	return `/**
+ * {@link EntitySystem} for this schema — runs per matching entity each update.
+ * \`Actions\`/\`Tags\`/\`Entity\`/\`EntityDelta\` are baked in; \`State\`/\`UpdateArguments\`
+ * stay open. Build one with {@link createGameEntitySystem}.
+ */
+export type GameEntitySystem<
+  State extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+> = EntitySystem<State, UpdateArguments, Actions, Tags, Entity, EntityDelta>;
+
+/**
+ * {@link ArchetypeSystem} for this schema — runs once per update over every
+ * matching archetype. Build one with {@link createGameArchetypeSystem}.
+ */
+export type GameArchetypeSystem<
+  State extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+> = ArchetypeSystem<State, UpdateArguments, Actions, Tags, Entity, EntityDelta>;
+
+/**
+ * {@link Behavior} for this schema — an event-driven handler keyed by an action
+ * tag. Build one with {@link createGameBehavior}.
+ */
+export type GameBehavior<
+  State extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+> = Behavior<State, UpdateArguments, Actions, Tags, Entity, EntityDelta>;
+
+/** Any system for this schema: entity | archetype | event | lifecycle | behavior. */
+export type GameSystem<
+  State extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+> = System<State, UpdateArguments, Actions, Tags, Entity, EntityDelta>;
+
+/**
+ * Create a per-entity system. \`world\` and the entity shape are typed for this
+ * schema, so the executor never restates \`Tags\`/\`Entity\`/\`EntityDelta\`. Specify
+ * \`<State, UpdateArguments>\` only when the system reads context or update args.
+ */
+export function createGameEntitySystem<
+  State extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+>(
+  execute: GameEntitySystem<State, UpdateArguments>["execute"],
+  query: Query | ((buildQuery: QueryBuilder) => QueryBuilder),
+): GameEntitySystem<State, UpdateArguments> {
+  return createEntitySystem(execute, query);
+}
+
+/**
+ * Create an archetype system — runs once per update over the matching
+ * archetypes. \`world\` is typed for this schema; see {@link createGameEntitySystem}.
+ */
+export function createGameArchetypeSystem<
+  State extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+>(
+  execute: GameArchetypeSystem<State, UpdateArguments>["execute"],
+  query: Query | ((buildQuery: QueryBuilder) => QueryBuilder),
+): GameArchetypeSystem<State, UpdateArguments> {
+  return createArchetypeSystem(execute, query);
+}
+
+/**
+ * Create an action-tag behavior. \`handler(world, entity, event)\` runs when
+ * \`act(tag)\` strikes a matching entity; higher \`priority\` runs first.
+ */
+export function createGameBehavior<
+  State extends Record<string, unknown> = {},
+  UpdateArguments extends Array<unknown> = [],
+>(
+  tag: number,
+  handler: GameBehavior<State, UpdateArguments>["handler"],
+  query: Query | ((buildQuery: QueryBuilder) => QueryBuilder),
+  priority?: number,
+): GameBehavior<State, UpdateArguments> {
+  return createBehavior(tag, handler, query, priority);
+}`;
+}
+//#endregion
+//#region src/generators/codegen.ts
+function generate(cwd, config, vampConfig) {
+	const schema = loadAndParseSchema(resolve(cwd, config.generators?.ts?.outFile ?? "./src/bebop.ts"));
+	const entityDef = schema.definitions.get("Entity");
+	if (!entityDef) throw new Error("No 'Entity' definition found in schema");
+	if (!schema.definitions.get("Actions")) throw new Error("No 'Actions' definition found in schema");
+	if (!schema.definitions.get("State")) throw new Error("No 'State' definition found in schema");
+	if (!schema.definitions.get("Tags")) throw new Error("No 'Tags' definition found in schema");
+	const bebopImportTypes = collectBebopImportTypes(entityDef, schema);
+	const bebopImport = "./bebop";
+	const helperImports = emitHelperImports(entityDef, schema);
+	const output = [
+		`// This file is auto-generated by @vampgg/cli. Do not edit manually.`,
+		`import type { ECSOptions, MutationBatch, EntitySystem, ArchetypeSystem, Behavior, System, Query, QueryBuilder } from "@vampgg/ecs";`,
+		`import { createEntitySystem, createArchetypeSystem, createBehavior } from "@vampgg/ecs";`,
+		...helperImports ? [helperImports] : [],
+		`import { defineECSRuntime, ECSDurableObject, ECSStorage, type ECSRuntimeConfiguration, type RPCContext } from "@vampgg/worker";`,
+		`import { createInterestBroadcast, type InterestBroadcastConfig } from "@vampgg/worker/interest";`,
+		`import type { Entity, Actions, Tags${bebopImportTypes} } from "${bebopImport}";`,
+		`import { MutationScope, type MutationRecord } from "${bebopImport}";`,
+		"",
+		emitComponents(entityDef),
+		"",
+		emitDelta(entityDef, schema),
+		"",
+		emitHelpers(entityDef, schema),
+		"",
+		emitFactory(),
+		"",
+		emitClasses("Tags"),
+		"",
+		emitGameContext(),
+		"",
+		emitRuntime(),
+		"",
+		emitSystems(),
+		"",
+		emitInterest(),
+		""
+	].join("\n");
+	const outPath = resolve(cwd, vampConfig.outFile);
+	mkdirSync(dirname(outPath), { recursive: true });
+	writeFileSync(outPath, output, "utf-8");
+	return outPath;
+}
+/** Candidate custom type names a field references (base, array member, or map value). */
+function candidateTypeNames(field) {
+	if (field.isArray) return field.memberTypeName ? [field.memberTypeName] : [];
+	if (field.isMap) return field.valueTypeName ? [field.valueTypeName] : [];
+	return [field.typeName];
+}
+function collectBebopImportTypes(entityDef, schema) {
+	const types = /* @__PURE__ */ new Set();
+	for (const field of entityDef.fields) for (const typeName of candidateTypeNames(field)) {
+		const def = schema.definitions.get(typeName);
+		if (def && def.name !== "Entity" && def.name !== "Actions" && def.name !== "State" && def.name !== "Tags") {
+			const deltaName = `${def.name}Delta`;
+			if (schema.definitions.has(deltaName)) types.add(deltaName);
+			else types.add(def.name);
+		}
+	}
+	if (types.size === 0) return "";
+	return ", " + [...types].join(", ");
+}
+//#endregion
+//#region src/generators/parse-bop-source.ts
+/** A bebop identifier per the grammar `[A-Za-z_][A-Za-z0-9_]*`. */
+const IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Escape regex metacharacters so an arbitrary name can be embedded in a RegExp. */
+function escapeRegExp(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Strip line comments (`//`) and block comments (`/* *​/`) from bebop source. */
+function stripComments(source) {
+	return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
+}
+/**
+* Remove nested brace blocks (inline messages/structs) from a message body,
+* leaving only top-level declarations. This prevents an inline `message X {...}`
+* inside `Entity` from leaking its fields in as top-level Entity fields.
+*/
+function stripNestedBlocks(body) {
+	let out = "";
+	let depth = 0;
+	for (const ch of body) {
+		if (ch === "{") {
+			depth++;
+			continue;
+		}
+		if (ch === "}") {
+			depth--;
+			continue;
+		}
+		if (depth === 0) out += ch;
+	}
+	return out;
+}
+/**
+* Extract the body of `message <name> { ... }` from bebop source text.
+* Returns null if the message is not found.
+*/
+function extractMessageBody(source, messageName) {
+	if (!IDENTIFIER_RE.test(messageName)) throw new Error(`Invalid message name '${messageName}': bebop identifiers must match [A-Za-z_][A-Za-z0-9_]*.`);
+	const clean = stripComments(source);
+	const match = new RegExp(`(?:^|\\b)message\\s+${escapeRegExp(messageName)}\\s*\\{`, "m").exec(clean);
+	if (!match) return null;
+	let depth = 0;
+	let start = -1;
+	for (let i = match.index + match[0].length - 1; i < clean.length; i++) {
+		const ch = clean[i];
+		if (ch === "{") {
+			if (depth === 0) start = i + 1;
+			depth++;
+		} else if (ch === "}") {
+			depth--;
+			if (depth === 0) return clean.slice(start, i);
+		}
+	}
+	return null;
+}
+function classifyType(rawType) {
+	const type = rawType.trim();
+	const mapMatch = /^map\s*\[\s*([^,\]]+?)\s*,\s*(.+)\s*\]$/.exec(type);
+	if (mapMatch) {
+		const keyRaw = mapMatch[1].trim();
+		const valueRaw = mapMatch[2].trim();
+		return {
+			typeName: "map",
+			isArray: false,
+			isMap: true,
+			keyType: keyRaw,
+			valueType: valueRaw,
+			valueClassified: classifyType(valueRaw),
+			isScalar: false
+		};
+	}
+	if (type.endsWith("[]")) {
+		const member = type.slice(0, -2).trim();
+		return {
+			typeName: member,
+			isArray: true,
+			isMap: false,
+			memberType: member,
+			memberClassified: classifyType(member),
+			isScalar: isScalar(member)
+		};
+	}
+	return {
+		typeName: type,
+		isArray: false,
+		isMap: false,
+		isScalar: isScalar(type)
+	};
+}
+/**
+* Parse `message <name>` field declarations from bebop source text.
+*
+* This is intentionally a lightweight, syntax-focused parser (no import
+* resolution). It only understands the constrained field syntax used in
+* generated/authored entity schemas: `<index> -> <type> <name>;`.
+*
+* Nested/inline message blocks inside the message body are stripped before
+* field extraction; their fields are NOT emitted as fields of this message. A
+* warning is logged so the user knows an inline component was ignored.
+*/
+function parseMessage(source, messageName) {
+	const rawBody = extractMessageBody(source, messageName);
+	if (rawBody === null) return null;
+	if (/\bmessage\s+[A-Za-z_]|\bstruct\s+[A-Za-z_]/.test(rawBody)) console.warn(`Warning: an inline message/struct block inside '${messageName}' was ignored. Inline components are not supported; declare it as a top-level message and reference it by name.`);
+	const body = stripNestedBlocks(rawBody);
+	const fields = [];
+	const fieldRe = /(\d+)\s*->\s*(.+?)\s+([A-Za-z_][A-Za-z0-9_]*)\s*;/g;
+	let m;
+	while ((m = fieldRe.exec(body)) !== null) {
+		const index = Number.parseInt(m[1], 10);
+		const rawType = m[2].trim();
+		const name = m[3];
+		fields.push({
+			index,
+			name,
+			rawType,
+			...classifyType(rawType)
+		});
+	}
+	return {
+		name: messageName,
+		fields
+	};
+}
+/** Convenience wrapper for the `Entity` message. */
+function parseEntityMessage(source) {
+	const entity = parseMessage(source, "Entity");
+	if (!entity) throw new Error("No 'message Entity { ... }' found in entity schema source");
+	return entity;
+}
+/**
+* Collect the names of every top-level `message <Name>` (not inline) declared
+* in the given source. Used to discover user-supplied `<Type>Delta` messages
+* and component message definitions.
+*/
+function collectMessageNames(source) {
+	const clean = stripComments(source);
+	const names = /* @__PURE__ */ new Set();
+	const re = /\bmessage\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{/g;
+	let depth = 0;
+	let lastIndex = 0;
+	let m;
+	const tally = (from, to) => {
+		for (let i = from; i < to; i++) if (clean[i] === "{") depth++;
+		else if (clean[i] === "}") depth--;
+	};
+	while ((m = re.exec(clean)) !== null) {
+		tally(lastIndex, m.index);
+		if (depth === 0) names.add(m[1]);
+		lastIndex = m.index;
+	}
+	return names;
+}
+//#endregion
+//#region src/generators/emit-mutation-bop.ts
+const HEADER = `// AUTO-GENERATED by @vampgg/cli. Do not edit manually.
+// Regenerated from the Entity message on every \`vamp generate\`.`;
+function capitalize(name) {
+	return name.length === 0 ? name : name[0].toUpperCase() + name.slice(1);
+}
+/** Message name for a per-member-type array delta (e.g. "guid" -> "GuidArrayDelta"). */
+function arrayDeltaName(memberType) {
+	return `${capitalize(memberType)}ArrayDelta`;
+}
+/**
+* True for a component sub-field that should be treated as a CRDT signed
+* counter in a synthesized delta (any integer/float scalar). Non-numeric
+* scalars (string/guid/bool/date) and custom fields are last-write-wins.
+*/
+function isCounterField(field) {
+	if (!field.isScalar) return false;
+	return field.typeName !== "string" && field.typeName !== "guid" && field.typeName !== "bool" && field.typeName !== "date";
+}
+function planCustomDelta(field, userDeltas) {
+	const deltaName = `${field.typeName}Delta`;
+	if (userDeltas.has(deltaName)) return {
+		deltaName,
+		emit: false
+	};
+	return {
+		deltaName,
+		emit: true
+	};
+}
+/**
+* Synthesize a `<Type>Delta` message from a component message. Numeric fields
+* become signed `int32` CRDT deltas (mirroring the hand-written `PoolDelta`);
+* non-numeric fields are last-write-wins (their raw type).
+*/
+function emitSynthesizedDelta(component) {
+	const fields = component.fields.map((f) => {
+		const t = isCounterField(f) ? "int32" : f.rawType;
+		return `  ${f.index} -> ${t} ${f.name};`;
+	}).join("\n");
+	return `message ${component.name}Delta {\n${fields}\n}`;
+}
+/**
+* Resolve the bebop delta type for an Entity field. Mirrors the TS delta
+* mapping in emit-delta.ts so the bebop wire type stays structurally aligned
+* with the in-memory TS EntityDelta type.
+*/
+function deltaTypeForField(field, userDeltas) {
+	if (field.name === "tags") return field.rawType;
+	if (field.isArray) {
+		if (field.isScalar) return arrayDeltaName(field.memberType);
+		return field.rawType;
+	}
+	if (field.isMap) return field.rawType;
+	if (field.isScalar) return field.typeName;
+	return planCustomDelta(field, userDeltas).deltaName;
+}
+/** Collect the distinct scalar-array member types that need a delta message. */
+function collectArrayDeltaMembers(entity) {
+	const members = /* @__PURE__ */ new Set();
+	for (const field of entity.fields) {
+		if (field.name === "tags") continue;
+		if (field.isArray && field.isScalar) members.add(field.memberType);
+	}
+	return [...members];
+}
+function emitArrayDeltaMessage(memberType) {
+	return `message ${arrayDeltaName(memberType)} {
+  1 -> ${memberType}[] set;
+  2 -> ${memberType}[] add;
+  3 -> ${memberType}[] remove;
+}`;
+}
+function emitEntityDelta(entity, userDeltas) {
+	return `message EntityDelta {\n${entity.fields.map((f) => `  ${f.index} -> ${deltaTypeForField(f, userDeltas)} ${f.name};`).join("\n")}\n}`;
+}
+const MUTATION_TYPE = `enum MutationType {
+  Insert = 1;
+  Update = 2;
+  Delete = 3;
+}`;
+const MUTATION_RECORD = `union MutationRecord {
+  1 -> struct Insert {
+    Entity entity;
+  }
+  2 -> struct Update {
+    EntityDelta delta;
+  }
+  3 -> struct Delete {
+    Entity entity;
+  }
+}`;
+const MUTATION_SCOPE = `message MutationScope {
+  1 -> map[guid, MutationRecord] mutations;
+}`;
+function planMutationSchema(entity, userDeltas, components, entitySchemaPath) {
+	const synthesized = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const field of entity.fields) {
+		if (field.name === "tags" || field.isArray || field.isMap || field.isScalar) continue;
+		const plan = planCustomDelta(field, userDeltas);
+		if (!plan.emit) continue;
+		const component = components.get(field.typeName);
+		if (!component) throw new Error(`Entity field '${field.name}: ${field.typeName}' is a custom component but no '${plan.deltaName}' was found and its definition could not be located to synthesize one. Declare a '${plan.deltaName}' message or move it into a schema file reachable from '${entitySchemaPath}'.`);
+		const nonNumeric = component.fields.filter((f) => !isCounterField(f));
+		if (nonNumeric.length > 0) throw new Error(`Cannot synthesize '${plan.deltaName}' for Entity field '${field.name}': component '${field.typeName}' has non-numeric field(s) [${nonNumeric.map((f) => `${f.name}: ${f.rawType}`).join(", ")}]. Declare a '${plan.deltaName}' message explicitly in a schema reachable from '${entitySchemaPath}'.`);
+		if (!seen.has(plan.deltaName)) {
+			seen.add(plan.deltaName);
+			synthesized.push(emitSynthesizedDelta(component));
+		}
+	}
+	return { synthesized };
+}
+/**
+* Emit the bebop schema providing serializable EntityDelta + MutationScope
+* types, derived from the Entity message.
+*
+* @param entity Parsed Entity message.
+* @param entityImportPath Import path to the entity schema, relative to the
+*   emitted file (e.g. "./entity.bop").
+* @param userDeltas Set of `<Type>Delta` message names already reachable from
+*   the user's schema (so they are reused verbatim, not re-synthesized).
+* @param components Map of component name -> parsed component message, used to
+*   synthesize a `<Type>Delta` when one is not user-supplied.
+* @param entitySchemaPath Absolute path to the entity schema (for error text).
+*/
+function emitMutationSchema(entity, entityImportPath, userDeltas = /* @__PURE__ */ new Set(), components = /* @__PURE__ */ new Map(), entitySchemaPath = "<entity schema>") {
+	const plan = planMutationSchema(entity, userDeltas, components, entitySchemaPath);
+	const sections = [HEADER, `import "${entityImportPath}"`];
+	for (const member of collectArrayDeltaMembers(entity)) sections.push(emitArrayDeltaMessage(member));
+	for (const block of plan.synthesized) sections.push(block);
+	sections.push(emitEntityDelta(entity, userDeltas), MUTATION_TYPE, MUTATION_RECORD, MUTATION_SCOPE);
+	return sections.join("\n\n") + "\n";
+}
+//#endregion
+//#region src/generators/resolve-imports.ts
+/**
+* Extract the import paths from a bebop source file. Bebop imports look like
+* `import "../relative/path.bop"` or `import "@scope/pkg/schema/foo.bop"`.
+*/
+function extractImportPaths(source) {
+	const re = /^\s*import\s+"([^"]+)"\s*;?\s*$/gm;
+	const paths = [];
+	let m;
+	while ((m = re.exec(source)) !== null) paths.push(m[1]);
+	return paths;
+}
+/**
+* Resolve a single bebop import specifier to an absolute filesystem path.
+*
+* - Relative specifiers (`./`, `../`) resolve against `fromDir`.
+* - Bare/package specifiers resolve via Node module resolution, falling back to
+*   resolving the package root and joining the subpath when the package's
+*   `exports` map blocks subpath access (the common case for `.bop` files).
+*
+* Returns null if the specifier cannot be resolved.
+*/
+function resolveBebopImport(specifier, fromDir) {
+	if (specifier.startsWith(".") || isAbsolute(specifier)) {
+		const abs = isAbsolute(specifier) ? specifier : resolve(fromDir, specifier);
+		return existsSync(abs) ? abs : null;
+	}
+	const req = createRequire(resolve(fromDir, "noop.js"));
+	try {
+		const direct = req.resolve(specifier);
+		if (existsSync(direct)) return direct;
+	} catch {}
+	const segments = specifier.split("/");
+	const pkgName = specifier.startsWith("@") ? `${segments[0]}/${segments[1]}` : segments[0];
+	const subpath = segments.slice(specifier.startsWith("@") ? 2 : 1).join("/");
+	try {
+		const joined = resolve(dirname(req.resolve(`${pkgName}/package.json`)), subpath);
+		if (existsSync(joined)) return joined;
+	} catch {}
+	return null;
+}
+/**
+* Transitively read the entity source plus every reachable imported `.bop` file,
+* returning their concatenated source text. Used so the lightweight message
+* parser can see component messages and `<Type>Delta` definitions that live in
+* imported files (e.g. `PoolDelta` in `@vampgg/utils/schema/pool.bop`).
+*
+* Unresolved imports are skipped (the caller fails loudly later if a referenced
+* type is missing). Visited files are de-duplicated to avoid cycles.
+*/
+function collectReachableSource(entityPath) {
+	const visited = /* @__PURE__ */ new Set();
+	const parts = [];
+	const visit = (filePath) => {
+		const abs = resolve(filePath);
+		if (visited.has(abs)) return;
+		visited.add(abs);
+		let src;
+		try {
+			src = readFileSync(abs, "utf-8");
+		} catch {
+			return;
+		}
+		parts.push(src);
+		for (const spec of extractImportPaths(src)) {
+			const resolved = resolveBebopImport(spec, dirname(abs));
+			if (resolved) visit(resolved);
+		}
+	};
+	visit(entityPath);
+	return parts.join("\n\n");
+}
+//#endregion
+//#region src/generators/generate-mutation-schema.ts
+/** Default mutation schema path: a `mutation.bop` sibling of the entity schema. */
+function resolveMutationPath(cwd, vampConfig) {
+	if (vampConfig.schemas.mutation) return resolve(cwd, vampConfig.schemas.mutation);
+	return resolve(dirname(resolve(cwd, vampConfig.schemas.entity)), "mutation.bop");
+}
+/** Compute the bebop import path from the mutation file to the entity file. */
+function entityImportPath(entityPath, mutationPath) {
+	const normalized = relative(dirname(mutationPath), entityPath).split("\\").join("/");
+	return normalized.startsWith(".") ? normalized : `./${normalized}`;
+}
+/**
+* From the reachable schema source, collect:
+*  - `userDeltas`: every `<Type>Delta` message name already declared.
+*  - `components`: every custom-component message referenced by Entity, parsed
+*    so a missing `<Type>Delta` can be synthesized.
+*/
+function collectSchemaContext(entity, reachableSource) {
+	const declared = collectMessageNames(reachableSource);
+	const userDeltas = new Set([...declared].filter((n) => n.endsWith("Delta")));
+	const components = /* @__PURE__ */ new Map();
+	for (const field of entity.fields) {
+		if (field.name === "tags" || field.isArray || field.isMap || field.isScalar) continue;
+		if (components.has(field.typeName)) continue;
+		if (!declared.has(field.typeName)) continue;
+		const parsed = parseMessage(reachableSource, field.typeName);
+		if (parsed) components.set(field.typeName, parsed);
+	}
+	return {
+		userDeltas,
+		components
+	};
+}
+/**
+* Parse the user's entity schema and (re)generate the bebop mutation schema
+* (EntityDelta, MutationType, MutationRecord, MutationScope) next to it.
+*
+* IMPORTANT: this must run BEFORE `bebopc build` so the generated schema is
+* picked up and compiled into serializable types.
+*
+* @returns the absolute path of the written mutation schema.
+*/
+function generateMutationSchema(cwd, vampConfig) {
+	const entityPath = resolve(cwd, vampConfig.schemas.entity);
+	const entity = parseEntityMessage(readFileSync(entityPath, "utf-8"));
+	const { userDeltas, components } = collectSchemaContext(entity, collectReachableSource(entityPath));
+	const mutationPath = resolveMutationPath(cwd, vampConfig);
+	const output = emitMutationSchema(entity, entityImportPath(entityPath, mutationPath), userDeltas, components, entityPath);
+	mkdirSync(dirname(mutationPath), { recursive: true });
+	writeFileSync(mutationPath, output, "utf-8");
+	return mutationPath;
+}
+//#endregion
+export { extractMessageBody as a, generate as c, parseSchema as d, loadBebopConfig as f, emitMutationSchema as i, loadAndParseSchema as l, resolveMutationPath as n, parseEntityMessage as o, loadVampConfig as p, resolveBebopImport as r, parseMessage as s, generateMutationSchema as t, loadSchemaFromFile as u };