@vgai/sdk 0.4.0-canary.20260715.0

package/src/project/discovery-operations.ts

@@ -0,0 +1,269 @@
+/**
+ * `project.story.discover`, `project.theatre.*`, `project.xstate.*` (B2,
+ * §8 B2 "story discovery", "Theatre project-state discovery/validation",
+ * "XState machine discovery/validation where statically possible").
+ *
+ * These three are DISCOVERY/VALIDATION-ONLY by design (the B2 task brief
+ * explicitly allows this "where the spec says 'where statically possible'"):
+ *
+ *  - Stories (CSF) are ordinary `.tsx`/`.ts` modules (§5.2/C3) — VGAI stores
+ *    no duplicate story registry, so there is nothing to mutate here; listing
+ *    `*.stories.tsx`/`*.stories.ts` is the whole B2 surface.
+ *  - Theatre project state (`*.theatre-project.json`) is a real, versioned,
+ *    proprietary Theatre.js format this repo does not own (§3.2/§5.3 — "the
+ *    committed Theatre project state is authoritative authored data"). B2
+ *    validates only the OUTER shape (`sheetsById`/`definitionVersion`/
+ *    `revisionHistory` — confirmed against the real committed fixtures,
+ *    e.g. `packages/engine/test/fixtures/theatre-director-proof.theatre-project.json`)
+ *    — never the internal per-track keyframe format, which is Theatre
+ *    Studio's own authoring concern, not VGAI's.
+ *  - XState machines are ordinary TypeScript modules (§3.3/§5.6) with no
+ *    VGAI-owned serialization. Statically discovering/validating one without
+ *    executing/transpiling the module is necessarily a heuristic (regex-based
+ *    "does this file import `xstate` and call `createMachine`") — this is
+ *    named as a LIMIT, not silently passed off as full validation.
+ */
+
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  listProjectFiles,
+  NO_PROJECT_ROOT_ERROR,
+  PATH_OUTSIDE_PROJECT_ERROR,
+  requireProjectRoot,
+  resolveProjectPath,
+} from './shared.js';
+
+// ---------------------------------------------------------------------------
+// project.story.discover
+// ---------------------------------------------------------------------------
+
+export const projectStoryDiscover = defineOperation({
+  name: 'project.story.discover',
+  summary: 'List every Storybook CSF story module (*.stories.tsx / *.stories.ts) in the project.',
+  description:
+    'List-only (§5.2/C3: CSF is the canonical story format; VGAI keeps no duplicate registry). ' +
+    'Does not parse story exports/args/decorators — an agent opens the module directly for that.',
+  input: z.object({}),
+  result: z.object({ storyFiles: z.array(z.string()).describe('Project-relative paths, sorted.') }),
+  errors: [NO_PROJECT_ROOT_ERROR],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Walks the project file tree; no writes.' },
+  async impl(_input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const storyFiles = listProjectFiles(
+      projectRoot,
+      (p) => p.endsWith('.stories.tsx') || p.endsWith('.stories.ts'),
+    );
+    return { storyFiles };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.theatre.discover
+// ---------------------------------------------------------------------------
+
+export const projectTheatreDiscover = defineOperation({
+  name: 'project.theatre.discover',
+  summary:
+    'List every committed Theatre project-state file (*.theatre-project.json) in the project.',
+  description:
+    'List-only (§3.2/§5.3: the committed Theatre project state is authoritative authored data VGAI does not own the internal format of).',
+  input: z.object({}),
+  result: z.object({
+    theatreProjectFiles: z.array(z.string()).describe('Project-relative paths, sorted.'),
+  }),
+  errors: [NO_PROJECT_ROOT_ERROR],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Walks the project file tree; no writes.' },
+  async impl(_input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const theatreProjectFiles = listProjectFiles(projectRoot, (p) =>
+      p.endsWith('.theatre-project.json'),
+    );
+    return { theatreProjectFiles };
+  },
+});
+
+// Best-effort OUTER shape only — see module jsdoc for why this deliberately
+// does not validate `sheetsById`'s internal track/keyframe format.
+const TheatreProjectStateShape = z.object({
+  sheetsById: z.record(z.string(), z.unknown()),
+  definitionVersion: z.string(),
+  revisionHistory: z.array(z.unknown()),
+});
+
+const ProjectTheatreValidateInput = z.object({
+  theatreProjectPath: z
+    .string()
+    .optional()
+    .describe('Validate this project-relative file instead of `document`.'),
+  document: z
+    .unknown()
+    .optional()
+    .describe('Validate this raw document instead of reading `theatreProjectPath`.'),
+});
+
+export const projectTheatreValidate = defineOperation({
+  name: 'project.theatre.validate',
+  summary:
+    'Validate a Theatre project-state file’s OUTER shape (sheetsById/definitionVersion/revisionHistory).',
+  description:
+    'Shape-only — Theatre’s internal per-track keyframe format is a real, versioned, ' +
+    'proprietary Theatre.js format this repo does not own (§3.2/§5.3), so this does not attempt ' +
+    'deep validation of track/keyframe contents.',
+  input: ProjectTheatreValidateInput,
+  result: z.object({ valid: z.boolean(), issues: z.array(z.string()) }),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    {
+      code: 'BAD_INPUT',
+      summary: 'Neither theatreProjectPath nor document was given.',
+      data: z.object({}),
+    },
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: {
+    risk: 'read',
+    summary: 'Reads a Theatre project-state file (or validates a given document); no writes.',
+  },
+  async impl(input, ctx) {
+    let json: unknown;
+    if (input.document !== undefined) {
+      json = input.document;
+    } else if (input.theatreProjectPath !== undefined) {
+      const projectRoot = requireProjectRoot(ctx);
+      const absPath = resolveProjectPath(projectRoot, input.theatreProjectPath);
+      json = JSON.parse(readFileSync(absPath, 'utf-8'));
+    } else {
+      throw new OperationError(
+        'BAD_INPUT',
+        'One of theatreProjectPath or document must be given.',
+        {},
+      );
+    }
+    const parsed = TheatreProjectStateShape.safeParse(json);
+    if (!parsed.success) {
+      return {
+        valid: false,
+        issues: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+      };
+    }
+    return { valid: true, issues: [] };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.xstate.discover / .validate — best-effort STATIC discovery only.
+// ---------------------------------------------------------------------------
+
+/** True when the file text looks like it defines an XState machine — a heuristic, not a parse. */
+function looksLikeXStateMachine(text: string): { importsXstate: boolean; definesMachine: boolean } {
+  const importsXstate = /from\s+['"]xstate['"]/.test(text);
+  const definesMachine = /\.createMachine\s*\(|(?<!\.)createMachine\s*\(/.test(text);
+  return { importsXstate, definesMachine };
+}
+
+export const projectXstateDiscover = defineOperation({
+  name: 'project.xstate.discover',
+  summary:
+    'Best-effort static discovery of TypeScript modules that appear to define an XState machine.',
+  description:
+    'STATIC HEURISTIC, not a parse/execute: a file is reported when its text imports from ' +
+    "'xstate' AND contains a `createMachine(...)`/`setup(...).createMachine(...)` call. This can " +
+    'both miss machines built through indirection and never proves the machine config is valid ' +
+    '— see project.xstate.validate for the same limit named on the validation side.',
+  input: z.object({}),
+  result: z.object({
+    machineFiles: z
+      .array(
+        z.object({ path: z.string(), importsXstate: z.boolean(), definesMachine: z.boolean() }),
+      )
+      .describe(
+        'Every *.ts/*.tsx file that imports xstate, with whether it also defines a machine.',
+      ),
+  }),
+  errors: [NO_PROJECT_ROOT_ERROR],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: {
+    risk: 'read',
+    summary: 'Reads *.ts/*.tsx file contents under the project; no writes.',
+  },
+  async impl(_input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const candidates = listProjectFiles(
+      projectRoot,
+      (p) => (p.endsWith('.ts') || p.endsWith('.tsx')) && !p.endsWith('.d.ts'),
+    );
+    const machineFiles: { path: string; importsXstate: boolean; definesMachine: boolean }[] = [];
+    for (const rel of candidates) {
+      const abs = resolveProjectPath(projectRoot, rel);
+      let text: string;
+      try {
+        text = readFileSync(abs, 'utf-8');
+      } catch {
+        continue;
+      }
+      const { importsXstate, definesMachine } = looksLikeXStateMachine(text);
+      if (importsXstate) machineFiles.push({ path: rel, importsXstate, definesMachine });
+    }
+    return { machineFiles };
+  },
+});
+
+const ProjectXstateValidateInput = z.object({
+  machinePath: z.string().describe('Project-relative path to a TypeScript module to check.'),
+});
+
+export const projectXstateValidate = defineOperation({
+  name: 'project.xstate.validate',
+  summary:
+    'Best-effort static check that a TypeScript module imports xstate and defines a machine.',
+  description:
+    'STATIC HEURISTIC, not a parse/execute (see project.xstate.discover’s jsdoc for the same ' +
+    'limit): this cannot validate states/transitions/guards/events — only that the file imports ' +
+    "'xstate' and contains a machine-creation call. A file that fails this check may still be a " +
+    'perfectly valid hand-authored machine using an unusual construction pattern.',
+  input: ProjectXstateValidateInput,
+  result: z.object({ valid: z.boolean(), issues: z.array(z.string()) }),
+  errors: [NO_PROJECT_ROOT_ERROR, PATH_OUTSIDE_PROJECT_ERROR],
+  requires: { project: true },
+  host: 'node',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads one file’s text; no writes.' },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const absPath = resolveProjectPath(projectRoot, input.machinePath);
+    const text = readFileSync(absPath, 'utf-8');
+    const { importsXstate, definesMachine } = looksLikeXStateMachine(text);
+    const issues: string[] = [];
+    if (!importsXstate) issues.push(`${input.machinePath} does not import from 'xstate'.`);
+    if (!definesMachine) issues.push(`${input.machinePath} has no createMachine(...) call.`);
+    return { valid: issues.length === 0, issues };
+  },
+});
+
+/** Register every B2 story/Theatre/XState discovery operation onto `registry`. */
+export function registerDiscoveryOperations(registry: OperationRegistry): void {
+  registry.register(projectStoryDiscover);
+  registry.register(projectTheatreDiscover);
+  registry.register(projectTheatreValidate);
+  registry.register(projectXstateDiscover);
+  registry.register(projectXstateValidate);
+}

package/src/project/entity-operations.ts

@@ -0,0 +1,366 @@
+/**
+ * `project.scene.entity.*` (B2, §8 B2 "entity add/update/move/remove").
+ *
+ * ID-AWARE BY CONSTRUCTION: every op here targets an entity by its stable
+ * `id` (never an array index) and builds exactly one `DiffOp`
+ * (`@vgai/engine/scene/scene-diff-types`) for `applyDiff`
+ * (`@vgai/engine/scene/scene-apply`) to execute — the SAME op-ordering/
+ * placement machinery `project.scene.apply` and `vgai apply-diff` use. This
+ * module only assembles the single-op `SceneDiff`; it never walks/splices the
+ * entity tree itself.
+ *
+ * `entity.update` is a convenience MERGE over applyDiff's `update` op (which
+ * is itself a full field replace — see scene-apply.ts's jsdoc): the impl
+ * reads the entity's current fields, overlays the caller's `fields` on top,
+ * and hands the FULL merged object to applyDiff as the update payload — so a
+ * caller can patch just `{ transform: { position: [...] } }` without
+ * re-stating every other field, while applyDiff still only ever sees (and
+ * only ever needs to implement) a full-replace update.
+ */
+
+import { parseSceneFile, SceneParseError } from '@vgai/engine/scene/parse';
+import type { applyDiff } from '@vgai/engine/scene/scene-apply';
+import type { SceneEntity } from '@vgai/engine/scene/scene-types';
+import { SceneEntitySchema } from '@vgai/engine/scene/schema/entity';
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  APPLY_DIFF_FAILED_ERROR,
+  applyDiffOrThrow,
+  readAndParseScene,
+  SCENE_INVALID_ERROR,
+} from './scene-operations.js';
+import {
+  BaseHashField,
+  CONFLICT_ERROR,
+  checkNotStale,
+  DryRunField,
+  ENTITY_NOT_FOUND_ERROR,
+  FILE_NOT_FOUND_ERROR,
+  findEntityById,
+  mutationResultSchema,
+  NO_PROJECT_ROOT_ERROR,
+  PATH_OUTSIDE_PROJECT_ERROR,
+  requireEntityById,
+  requireProjectRoot,
+  writeFileAtomic,
+} from './shared.js';
+
+const EntityAfterSchema = z.object({
+  entity: z
+    .unknown()
+    .describe('The affected entity after the change (or that WOULD result), by id.'),
+});
+
+/**
+ * Shared write tail: re-validate the whole document, honor dryRun, write via
+ * checkNotStale-guarded atomic write, and shape the mutation envelope.
+ * `before`/`after` are passed through AS GIVEN (not wrapped) — callers shape
+ * them to match their own op's declared `after` result schema (entity ops
+ * wrap as `{ entity }`; component-operations.ts's callers pass their own
+ * `{ entityId, componentName, data }` shape directly).
+ */
+function finalizeSceneMutation<TBefore, TAfter>(
+  absPath: string,
+  scenePath: string,
+  result: SceneFileLike,
+  dryRun: boolean,
+  before: TBefore,
+  after: TAfter,
+) {
+  try {
+    parseSceneFile(result, scenePath);
+  } catch (err) {
+    if (err instanceof SceneParseError) {
+      throw new OperationError('SCENE_INVALID', `Result fails validation: ${err.message}`, {
+        issues: err.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+      });
+    }
+    throw err;
+  }
+  if (!dryRun) {
+    writeFileAtomic(absPath, `${JSON.stringify(result, null, 2)}\n`);
+  }
+  return { dryRun, written: !dryRun, filesChanged: [absPath], before, after };
+}
+
+// SceneFile is only used structurally here (applyDiff's return type) — avoid
+// a second import cycle by aliasing via the already-imported applyDiff's own
+// parameter type through a small local type alias.
+type SceneFileLike = ReturnType<typeof applyDiff>;
+
+// ---------------------------------------------------------------------------
+// project.scene.entity.add
+// ---------------------------------------------------------------------------
+
+const ProjectSceneEntityAddInput = z.object({
+  scenePath: z.string().describe('Project-relative path to the .vscn.json scene file.'),
+  parentId: z.string().nullable().describe('Parent entity id, or null for a top-level entity.'),
+  index: z.number().int().min(0).describe('Target position among the (new) parent’s children.'),
+  entity: SceneEntitySchema.describe('The entity to insert (id auto-generated if omitted).'),
+  dryRun: DryRunField,
+  baseHash: BaseHashField,
+});
+
+export const projectSceneEntityAdd = defineOperation({
+  name: 'project.scene.entity.add',
+  summary: 'Insert a new entity into a scene, by parent id + index.',
+  description:
+    'Builds a single `add` DiffOp and delegates to applyDiff — the same insertion/placement logic project.scene.apply uses.',
+  input: ProjectSceneEntityAddInput,
+  result: mutationResultSchema(EntityAfterSchema),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    FILE_NOT_FOUND_ERROR,
+    SCENE_INVALID_ERROR,
+    APPLY_DIFF_FAILED_ERROR,
+    CONFLICT_ERROR,
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: true,
+  permission: { risk: 'write', summary: 'Writes the target scene file.' },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const { absPath, hash, scene } = readAndParseScene(projectRoot, input.scenePath);
+    checkNotStale(absPath, hash, input.baseHash);
+
+    const result = applyDiffOrThrow(scene, {
+      ops: [
+        {
+          type: 'add',
+          entity: input.entity as SceneEntity,
+          parentId: input.parentId,
+          index: input.index,
+        },
+      ],
+      environmentChanged: false,
+      metaChanged: false,
+    });
+
+    // Report the entity as it landed (id may have been auto-generated).
+    const after = input.entity.id
+      ? findEntityById(result.entities, input.entity.id)
+      : findEntityById(result.entities, findNewestSiblingId(result, input.parentId, input.index));
+
+    return finalizeSceneMutation(
+      absPath,
+      input.scenePath,
+      result,
+      input.dryRun ?? false,
+      { entity: null },
+      { entity: after ?? null },
+    );
+  },
+});
+
+/** Best-effort: when the caller omitted `id`, look up whatever landed at the target position after the add. */
+function findNewestSiblingId(scene: SceneFileLike, parentId: string | null, index: number): string {
+  const siblings =
+    parentId === null ? scene.entities : (findEntityById(scene.entities, parentId)?.children ?? []);
+  const clamped = Math.min(index, siblings.length - 1);
+  return siblings[clamped]?.id ?? '';
+}
+
+// ---------------------------------------------------------------------------
+// project.scene.entity.update — merge-onto-full-replace convenience.
+// ---------------------------------------------------------------------------
+
+const ProjectSceneEntityUpdateInput = z.object({
+  scenePath: z.string().describe('Project-relative path to the .vscn.json scene file.'),
+  id: z.string().describe('Id of the entity to update (never an array index).'),
+  fields: z
+    .record(z.string(), z.unknown())
+    .describe(
+      'Fields to overlay onto the entity’s CURRENT fields (a merge, not a full replace — ' +
+        'unlike the underlying applyDiff `update` op, which this is built on top of). `id` and ' +
+        '`children` are ignored if present.',
+    ),
+  dryRun: DryRunField,
+  baseHash: BaseHashField,
+});
+
+export const projectSceneEntityUpdate = defineOperation({
+  name: 'project.scene.entity.update',
+  summary: 'Merge field changes onto an existing entity, addressed by stable id.',
+  description:
+    'ID-aware — resolves the target by `id` regardless of its position/reordering in the ' +
+    'entities array. Reads the entity’s current fields, overlays `fields`, and hands the merged ' +
+    'whole object to applyDiff’s `update` op (a full replace under the hood) so nothing the ' +
+    'caller did not mention is lost.',
+  input: ProjectSceneEntityUpdateInput,
+  result: mutationResultSchema(EntityAfterSchema),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    FILE_NOT_FOUND_ERROR,
+    SCENE_INVALID_ERROR,
+    APPLY_DIFF_FAILED_ERROR,
+    CONFLICT_ERROR,
+    ENTITY_NOT_FOUND_ERROR,
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: true,
+  permission: { risk: 'write', summary: 'Writes the target scene file.' },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const { absPath, hash, scene } = readAndParseScene(projectRoot, input.scenePath);
+    checkNotStale(absPath, hash, input.baseHash);
+
+    const current = requireEntityById(scene.entities, input.id);
+    const { id: _id, children: _children, ...currentFields } = current;
+    const {
+      id: _fid,
+      children: _fchildren,
+      ...overlayFields
+    } = input.fields as Record<string, unknown>;
+    const merged = { ...currentFields, ...overlayFields };
+
+    const result = applyDiffOrThrow(scene, {
+      ops: [{ type: 'update', id: input.id, entity: merged as SceneEntity }],
+      environmentChanged: false,
+      metaChanged: false,
+    });
+
+    const after = findEntityById(result.entities, input.id) ?? null;
+    return finalizeSceneMutation(
+      absPath,
+      input.scenePath,
+      result,
+      input.dryRun ?? false,
+      { entity: current },
+      { entity: after },
+    );
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.scene.entity.move
+// ---------------------------------------------------------------------------
+
+const ProjectSceneEntityMoveInput = z.object({
+  scenePath: z.string().describe('Project-relative path to the .vscn.json scene file.'),
+  id: z.string().describe('Id of the entity to move.'),
+  parentId: z.string().nullable().describe('New parent entity id, or null for top-level.'),
+  index: z.number().int().min(0).describe('Target position among the new parent’s children.'),
+  dryRun: DryRunField,
+  baseHash: BaseHashField,
+});
+
+export const projectSceneEntityMove = defineOperation({
+  name: 'project.scene.entity.move',
+  summary: 'Reparent and/or reorder an existing entity, addressed by stable id.',
+  description: 'Builds a single `move` DiffOp and delegates to applyDiff.',
+  input: ProjectSceneEntityMoveInput,
+  result: mutationResultSchema(EntityAfterSchema),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    FILE_NOT_FOUND_ERROR,
+    SCENE_INVALID_ERROR,
+    APPLY_DIFF_FAILED_ERROR,
+    CONFLICT_ERROR,
+    ENTITY_NOT_FOUND_ERROR,
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: true,
+  permission: { risk: 'write', summary: 'Writes the target scene file.' },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const { absPath, hash, scene } = readAndParseScene(projectRoot, input.scenePath);
+    checkNotStale(absPath, hash, input.baseHash);
+
+    const before = requireEntityById(scene.entities, input.id);
+    const result = applyDiffOrThrow(scene, {
+      ops: [{ type: 'move', id: input.id, parentId: input.parentId, index: input.index }],
+      environmentChanged: false,
+      metaChanged: false,
+    });
+    const after = findEntityById(result.entities, input.id) ?? null;
+
+    return finalizeSceneMutation(
+      absPath,
+      input.scenePath,
+      result,
+      input.dryRun ?? false,
+      { entity: before },
+      { entity: after },
+    );
+  },
+});
+
+// ---------------------------------------------------------------------------
+// project.scene.entity.remove
+// ---------------------------------------------------------------------------
+
+const ProjectSceneEntityRemoveInput = z.object({
+  scenePath: z.string().describe('Project-relative path to the .vscn.json scene file.'),
+  id: z.string().describe('Id of the entity (and its subtree) to remove.'),
+  dryRun: DryRunField,
+  baseHash: BaseHashField,
+});
+
+export const projectSceneEntityRemove = defineOperation({
+  name: 'project.scene.entity.remove',
+  summary: 'Delete an entity (and its subtree), addressed by stable id.',
+  description: 'Builds a single `remove` DiffOp and delegates to applyDiff.',
+  input: ProjectSceneEntityRemoveInput,
+  result: mutationResultSchema(EntityAfterSchema),
+  errors: [
+    NO_PROJECT_ROOT_ERROR,
+    PATH_OUTSIDE_PROJECT_ERROR,
+    FILE_NOT_FOUND_ERROR,
+    SCENE_INVALID_ERROR,
+    APPLY_DIFF_FAILED_ERROR,
+    CONFLICT_ERROR,
+    ENTITY_NOT_FOUND_ERROR,
+  ],
+  requires: { project: true },
+  host: 'node',
+  mutates: true,
+  supportsDryRun: true,
+  permission: {
+    risk: 'destructive',
+    summary: 'Deletes an entity subtree from the target scene file.',
+  },
+  async impl(input, ctx) {
+    const projectRoot = requireProjectRoot(ctx);
+    const { absPath, hash, scene } = readAndParseScene(projectRoot, input.scenePath);
+    checkNotStale(absPath, hash, input.baseHash);
+
+    const before = requireEntityById(scene.entities, input.id);
+    const result = applyDiffOrThrow(scene, {
+      ops: [{ type: 'remove', id: input.id }],
+      environmentChanged: false,
+      metaChanged: false,
+    });
+
+    return finalizeSceneMutation(
+      absPath,
+      input.scenePath,
+      result,
+      input.dryRun ?? false,
+      { entity: before },
+      { entity: null },
+    );
+  },
+});
+
+/** Register every B2 `project.scene.entity.*` operation onto `registry`. */
+export function registerEntityOperations(registry: OperationRegistry): void {
+  registry.register(projectSceneEntityAdd);
+  registry.register(projectSceneEntityUpdate);
+  registry.register(projectSceneEntityMove);
+  registry.register(projectSceneEntityRemove);
+}
+
+// Re-exported for component-operations.ts (avoids a second copy of the
+// "merge fields -> applyDiff update -> finalize" plumbing).
+export { finalizeSceneMutation };

package/src/project/index.ts

@@ -0,0 +1,55 @@
+/**
+ * B2 — `project.*` operations
+ * (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B2). Registered
+ * SEPARATELY from B1's `registerBuiltinOperations` (see `../operations.ts`)
+ * so B1's own registry tests — which assert `registerBuiltinOperations`
+ * registers "exactly the three B1 sample operations" — are unaffected; the
+ * default `operations` singleton (`../index.ts`) calls both.
+ */
+
+export * from './asset-operations.js';
+export * from './component-operations.js';
+export * from './discovery-operations.js';
+export * from './entity-operations.js';
+export * from './input-map-operations.js';
+export * from './manifest-operations.js';
+export * from './scene-operations.js';
+export {
+  BaseHashField,
+  CONFLICT_ERROR,
+  checkNotStale,
+  DryRunField,
+  ENTITY_NOT_FOUND_ERROR,
+  FILE_NOT_FOUND_ERROR,
+  findEntityById,
+  listProjectFiles,
+  mutationResultSchema,
+  NO_PROJECT_ROOT_ERROR,
+  PATH_OUTSIDE_PROJECT_ERROR,
+  readFileWithHash,
+  requireEntityById,
+  requireProjectRoot,
+  resolveProjectPath,
+  sha256Hex,
+  writeFileAtomic,
+} from './shared.js';
+
+import type { OperationRegistry } from '../registry.js';
+import { registerAssetOperations } from './asset-operations.js';
+import { registerComponentOperations } from './component-operations.js';
+import { registerDiscoveryOperations } from './discovery-operations.js';
+import { registerEntityOperations } from './entity-operations.js';
+import { registerInputMapOperations } from './input-map-operations.js';
+import { registerManifestOperations } from './manifest-operations.js';
+import { registerSceneOperations } from './scene-operations.js';
+
+/** Register every B2 `project.*` operation onto `registry`. */
+export function registerProjectOperations(registry: OperationRegistry): void {
+  registerManifestOperations(registry);
+  registerSceneOperations(registry);
+  registerEntityOperations(registry);
+  registerComponentOperations(registry);
+  registerAssetOperations(registry);
+  registerInputMapOperations(registry);
+  registerDiscoveryOperations(registry);
+}