@fugood/bricks-project 2.25.0-beta.41 → 2.25.0-beta.43

package/tools/mcp-tools/entry-editing.ts

@@ -0,0 +1,2398 @@
+import generateModule from '@babel/generator'
+import { parse, parseExpression } from '@babel/parser'
+import traverseModule from '@babel/traverse'
+import * as t from '@babel/types'
+import { parse as parseRuntimeExpression } from 'acorn'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { format as formatWithOxfmt } from 'oxfmt'
+import { mkdir, readFile, readdir, appendFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { z } from 'zod'
+
+import { verifyProject } from './_verify'
+
+const generate = (generateModule as any).default || generateModule
+const traverse = (traverseModule as any).default || traverseModule
+
+const auditLogIgnoreEntry = '.bricks/edits.jsonl'
+
+const oxfmtOptions = {
+  trailingComma: 'all',
+  tabWidth: 2,
+  semi: false,
+  singleQuote: true,
+  printWidth: 100,
+} as const
+
+const entryKinds = {
+  'bricks.ts': {
+    kind: 'brick',
+    namespace: 'bricks',
+    varPrefix: 'b',
+    idType: 'brick',
+    idPrefix: 'BRICK_',
+    typename: 'Brick',
+  },
+  'generators.ts': {
+    kind: 'generator',
+    namespace: 'generators',
+    varPrefix: 'g',
+    idType: 'generator',
+    idPrefix: 'GENERATOR_',
+    typename: 'Generator',
+  },
+  'canvases.ts': {
+    kind: 'canvas',
+    namespace: 'canvases',
+    varPrefix: 'c',
+    idType: 'canvas',
+    idPrefix: 'CANVAS_',
+    typename: 'Canvas',
+  },
+  'data.ts': {
+    kind: 'data',
+    namespace: 'data',
+    varPrefix: 'd',
+    idType: 'data',
+    idPrefix: 'PROPERTY_BANK_DATA_NODE_',
+    typename: 'Data',
+  },
+  'animations.ts': {
+    kind: 'animation',
+    namespace: 'animations',
+    varPrefix: 'a',
+    idType: 'animation',
+    idPrefix: 'ANIMATION_',
+    typename: 'Animation',
+  },
+} as const
+
+type EntryKindFile = keyof typeof entryKinds
+type EntryKind = (typeof entryKinds)[EntryKindFile]
+
+type ParsedFile = {
+  ast: t.File
+  source: string
+  absPath: string
+  relPath: string
+  kind: EntryKind
+}
+
+type ExportEntry = {
+  name: string
+  node: t.ExportNamedDeclaration
+  declaration: t.VariableDeclaration
+  declarator: t.VariableDeclarator
+  object?: t.ObjectExpression
+  id?: string
+  alias?: string
+  typeName?: string
+}
+
+type ReferenceResolution = {
+  input: string
+  id?: string
+  alias?: string
+  varName: string
+  namespace: EntryKind['namespace']
+  display: string
+  targetAbsPath: string
+  sameFile: boolean
+  subspaceLabel: string
+  importSource?: string
+  importLocal?: string
+}
+
+type EditContext = {
+  projectDir: string
+  parsed: ParsedFile
+  references: ReferenceResolution[]
+  typeImports: Set<string>
+  valueImports: Set<string>
+}
+
+class EntryEditingError extends Error {
+  code: string
+  details?: Record<string, unknown>
+  isMcpError: boolean
+
+  constructor(
+    code: string,
+    message: string,
+    details?: Record<string, unknown>,
+    isMcpError = false,
+  ) {
+    super(message)
+    this.name = 'EntryEditingError'
+    this.code = code
+    this.details = details
+    this.isMcpError = isMcpError
+  }
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+
+const isIdentifierName = (value: string) => /^[$A-Z_a-z][$\w]*$/.test(value)
+
+const normalizeRelPath = (file: string) => file.replace(/\\/g, '/').replace(/^\.\/+/, '')
+
+const projectRelativePath = (projectDir: string, absPath: string) =>
+  normalizeRelPath(path.relative(projectDir, absPath))
+
+const resolveProjectPath = (projectDir: string, file: string) => {
+  if (path.isAbsolute(file)) {
+    throw new EntryEditingError('invalid_file', 'File must be project-relative', { file })
+  }
+
+  const absPath = path.resolve(projectDir, file)
+  const relative = path.relative(projectDir, absPath)
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new EntryEditingError('invalid_file', 'File must stay inside the project directory', {
+      file,
+    })
+  }
+  return absPath
+}
+
+const getEntryKindForPath = (filePath: string): EntryKind => {
+  const filename = path.basename(filePath) as EntryKindFile
+  const kind = entryKinds[filename]
+  if (!kind) {
+    throw new EntryEditingError('unsupported_file', `Unsupported entry file: ${filename}`, {
+      file: filePath,
+      expected: Object.keys(entryKinds),
+    })
+  }
+  return kind
+}
+
+const parseFileSource = (source: string, relPath: string) => {
+  try {
+    return parse(source, {
+      sourceType: 'module',
+      plugins: ['typescript', 'topLevelAwait'],
+      errorRecovery: false,
+    })
+  } catch (err: any) {
+    throw new EntryEditingError(
+      'parse_failed',
+      `Cannot parse ${relPath} as TypeScript: ${err.message}. Edit this file directly.`,
+      { file: relPath },
+      true,
+    )
+  }
+}
+
+const readParsedFile = async (projectDir: string, absPath: string): Promise<ParsedFile> => {
+  const source = await readFile(absPath, 'utf8')
+  const relPath = projectRelativePath(projectDir, absPath)
+  return {
+    source,
+    ast: parseFileSource(source, relPath),
+    absPath,
+    relPath,
+    kind: getEntryKindForPath(absPath),
+  }
+}
+
+const getPropertyKeyName = (key: t.Expression | t.PrivateName) => {
+  if (t.isIdentifier(key)) return key.name
+  if (t.isStringLiteral(key) || t.isNumericLiteral(key)) return String(key.value)
+  return null
+}
+
+const makeObjectKey = (key: string) =>
+  isIdentifierName(key) ? t.identifier(key) : t.stringLiteral(key)
+
+const getObjectProperty = (object: t.ObjectExpression, key: string) =>
+  object.properties.find((property): property is t.ObjectProperty => {
+    if (!t.isObjectProperty(property)) return false
+    return getPropertyKeyName(property.key) === key
+  })
+
+const getStringProperty = (object: t.ObjectExpression, key: string) => {
+  const property = getObjectProperty(object, key)
+  if (!property || !t.isStringLiteral(property.value)) return undefined
+  return property.value.value
+}
+
+const setObjectProperty = (object: t.ObjectExpression, key: string, value: t.Expression) => {
+  const existing = getObjectProperty(object, key)
+  if (existing) {
+    existing.value = value
+    return
+  }
+  object.properties.push(t.objectProperty(makeObjectKey(key), value))
+}
+
+const removeObjectProperty = (object: t.ObjectExpression, key: string) => {
+  const index = object.properties.findIndex((property) => {
+    if (!t.isObjectProperty(property)) return false
+    return getPropertyKeyName(property.key) === key
+  })
+  if (index >= 0) object.properties.splice(index, 1)
+}
+
+const getExportEntries = (ast: t.File): ExportEntry[] =>
+  ast.program.body.flatMap((statement) => {
+    if (!t.isExportNamedDeclaration(statement)) return []
+    if (!t.isVariableDeclaration(statement.declaration)) return []
+    const declaration = statement.declaration
+
+    return declaration.declarations.flatMap((declarator) => {
+      if (!t.isIdentifier(declarator.id)) return []
+
+      const typeAnnotation = declarator.id.typeAnnotation
+      let typeName: string | undefined
+      if (
+        t.isTSTypeAnnotation(typeAnnotation) &&
+        t.isTSTypeReference(typeAnnotation.typeAnnotation) &&
+        t.isIdentifier(typeAnnotation.typeAnnotation.typeName)
+      ) {
+        typeName = typeAnnotation.typeAnnotation.typeName.name
+      }
+
+      const object = t.isObjectExpression(declarator.init) ? declarator.init : undefined
+      return [
+        {
+          name: declarator.id.name,
+          node: statement,
+          declaration,
+          declarator,
+          object,
+          id: object ? getStringProperty(object, 'id') : undefined,
+          alias: object ? getStringProperty(object, 'alias') : undefined,
+          typeName,
+        },
+      ]
+    })
+  })
+
+const ensureStandardEntryObject = (entry: ExportEntry, relPath: string) => {
+  if (!entry.object) {
+    throw new EntryEditingError(
+      'fallback_recommended',
+      `Entry ${entry.name} in ${relPath} is not a top-level exported object literal. Edit this file directly for this one.`,
+      { file: relPath, entry: entry.name, check: 'top-level export const object literal' },
+    )
+  }
+  return entry.object
+}
+
+const findEntryInParsedFile = (
+  parsed: ParsedFile,
+  target: { entry?: string; id?: string },
+): ExportEntry => {
+  const entries = getExportEntries(parsed.ast)
+
+  if (target.entry) {
+    const entry = entries.find((item) => item.name === target.entry)
+    if (entry) return entry
+    // Project docs tell agents aliases work in MCP tools, so accept them here too.
+    const aliasMatches = entries.filter((item) => item.alias === target.entry)
+    if (aliasMatches.length === 1) return aliasMatches[0]
+    if (aliasMatches.length > 1) {
+      throw new EntryEditingError('ambiguous_reference', `Alias is ambiguous: ${target.entry}`, {
+        file: parsed.relPath,
+        entry: target.entry,
+        matches: aliasMatches.map((item) => item.name),
+      })
+    }
+    throw new EntryEditingError(
+      'entry_not_found',
+      `Entry not found (by name or alias): ${target.entry}`,
+      {
+        file: parsed.relPath,
+        entry: target.entry,
+      },
+    )
+  }
+
+  if (target.id) {
+    const entry = entries.find((item) => item.id === target.id)
+    if (!entry) {
+      throw new EntryEditingError('entry_not_found', `Entry id not found: ${target.id}`, {
+        file: parsed.relPath,
+        id: target.id,
+      })
+    }
+    return entry
+  }
+
+  throw new EntryEditingError('missing_target', 'Provide entry or id')
+}
+
+const getSubspaceLabelFromPath = (absPath: string) => {
+  const parts = absPath.split(path.sep)
+  const subspace = parts.find((part) => /^subspace-\d+$/.test(part))
+  return subspace || 'unknown-subspace'
+}
+
+const getSubspaceDirFromPath = (absPath: string) => {
+  const parts = absPath.split(path.sep)
+  const index = parts.findIndex((part) => /^subspace-\d+$/.test(part))
+  if (index < 0) {
+    throw new EntryEditingError('invalid_file', 'Entry file must be inside subspaces/subspace-N', {
+      file: absPath,
+    })
+  }
+  return parts.slice(0, index + 1).join(path.sep)
+}
+
+const getSubspaceDirs = async (projectDir: string) => {
+  const subspacesDir = path.join(projectDir, 'subspaces')
+  const entries = await readdir(subspacesDir, { withFileTypes: true }).catch(() => [])
+  return entries
+    .filter((entry) => entry.isDirectory() && /^subspace-\d+$/.test(entry.name))
+    .map((entry) => path.join(subspacesDir, entry.name))
+    .sort()
+}
+
+const getEntryFilesInSubspace = async (subspaceDir: string) => {
+  const names = Object.keys(entryKinds)
+  const entries = await readdir(subspaceDir, { withFileTypes: true }).catch(() => [])
+  const existing = new Set(entries.filter((entry) => entry.isFile()).map((entry) => entry.name))
+  return names.filter((name) => existing.has(name)).map((name) => path.join(subspaceDir, name))
+}
+
+const getEntryFiles = async (projectDir: string) => {
+  const subspaces = await getSubspaceDirs(projectDir)
+  const nested = await Promise.all(subspaces.map(getEntryFilesInSubspace))
+  return nested.flat()
+}
+
+const resolveTargetFile = async (
+  projectDir: string,
+  input: { file?: string; entry?: string; id?: string },
+) => {
+  if (input.file) {
+    return resolveProjectPath(projectDir, input.file)
+  }
+
+  if (!input.id) {
+    throw new EntryEditingError('missing_file', 'Provide file, or provide id for global lookup')
+  }
+
+  const files = await getEntryFiles(projectDir)
+  for (const file of files) {
+    const parsed = await readParsedFile(projectDir, file)
+    const entry = getExportEntries(parsed.ast).find((item) => item.id === input.id)
+    if (entry) return file
+  }
+
+  throw new EntryEditingError('entry_not_found', `Entry id not found: ${input.id}`, {
+    id: input.id,
+  })
+}
+
+const resolveEditableTarget = async (
+  projectDir: string,
+  input: { file?: string; entry?: string; id?: string },
+) => {
+  const absPath = await resolveTargetFile(projectDir, input)
+  const parsed = await readParsedFile(projectDir, absPath)
+  const entry = findEntryInParsedFile(parsed, input)
+  const object = ensureStandardEntryObject(entry, parsed.relPath)
+  return { parsed, entry, object }
+}
+
+const shortId = (id: string) => {
+  const uuid = id.replace(/^[A-Z_]+/g, '')
+  return `${uuid.substr(15, 3)}${uuid.substr(20, 1)}`
+}
+
+const sanitizeAlias = (alias?: string) => {
+  if (!alias) return null
+  let sanitized = alias.replace(/[^a-zA-Z0-9_$]/g, '')
+  if (!sanitized) return null
+  if (/^[0-9]/.test(sanitized)) sanitized = `_${sanitized}`
+  return sanitized
+}
+
+const makeUniqueVarName = (existing: Set<string>, kind: EntryKind, id?: string, alias?: string) => {
+  const base =
+    sanitizeAlias(alias) || (id ? `${kind.varPrefix}${shortId(id)}` : `${kind.varPrefix}Entry`)
+  if (!existing.has(base)) return base
+  let index = 1
+  while (existing.has(`${base}${index}`)) index += 1
+  return `${base}${index}`
+}
+
+// Alias-keyed makeId calls hash to the same uuid regardless of declaration order, so
+// recompiles stay stable when sibling entries are added or removed. The bare form
+// falls back to the order-based counter.
+const makeIdCallExpression = (idType: string, alias?: string) =>
+  t.callExpression(
+    t.identifier('makeId'),
+    alias ? [t.stringLiteral(idType), t.stringLiteral(alias)] : [t.stringLiteral(idType)],
+  )
+
+const parsePath = (pathValue: string) => {
+  const tokens: Array<{ key: string } | { index: number }> = []
+  const parts = pathValue.split('.').filter(Boolean)
+  for (const part of parts) {
+    const pattern = /([^\[\]]+)|\[(\d+)\]/g
+    let match: RegExpExecArray | null
+    while ((match = pattern.exec(part))) {
+      if (match[1]) tokens.push({ key: match[1] })
+      if (match[2]) tokens.push({ index: Number(match[2]) })
+    }
+  }
+  if (tokens.length === 0) {
+    throw new EntryEditingError('invalid_path', `Invalid path: ${pathValue}`, { path: pathValue })
+  }
+  return tokens
+}
+
+const getExpectedContainer = (token: { key: string } | { index: number }) =>
+  'index' in token ? 'array' : 'object'
+
+// Generated sources wrap action objects in `as SystemAction...` casts; path edits
+// should see through type-only wrappers to the literal inside.
+const unwrapExpression = (node: t.Node): t.Node => {
+  if (
+    t.isTSAsExpression(node) ||
+    t.isTSSatisfiesExpression(node) ||
+    t.isTSNonNullExpression(node) ||
+    t.isParenthesizedExpression(node)
+  ) {
+    return unwrapExpression(node.expression)
+  }
+  return node
+}
+
+const assertObject = (node: t.Node, pathValue: string) => {
+  const unwrapped = unwrapExpression(node)
+  if (!t.isObjectExpression(unwrapped)) {
+    throw new EntryEditingError(
+      'fallback_recommended',
+      `Target path ${pathValue} is not an object literal. Edit this file directly for this one.`,
+      { path: pathValue, expected: 'object literal', actual: unwrapped.type },
+    )
+  }
+  return unwrapped
+}
+
+const assertArray = (node: t.Node, pathValue: string) => {
+  const unwrapped = unwrapExpression(node)
+  if (!t.isArrayExpression(unwrapped)) {
+    throw new EntryEditingError(
+      'fallback_recommended',
+      `Target path ${pathValue} is not an array literal. Edit this file directly for this one.`,
+      { path: pathValue, expected: 'array literal', actual: unwrapped.type },
+    )
+  }
+  return unwrapped
+}
+
+const createContainerForNext = (token: { key: string } | { index: number }) =>
+  getExpectedContainer(token) === 'array' ? t.arrayExpression([]) : t.objectExpression([])
+
+const setPathValue = async (
+  root: t.ObjectExpression,
+  pathValue: string,
+  rawValue: unknown,
+  ctx: EditContext,
+) => {
+  const tokens = parsePath(pathValue)
+  let current: t.Node = root
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index]
+    const isLast = index === tokens.length - 1
+    if ('key' in token) {
+      const object = assertObject(current, pathValue)
+      if (isLast) {
+        setObjectProperty(object, token.key, await expressionFromInput(rawValue, ctx))
+        return
+      }
+
+      const nextToken = tokens[index + 1]
+      let property = getObjectProperty(object, token.key)
+      if (!property) {
+        property = t.objectProperty(makeObjectKey(token.key), createContainerForNext(nextToken))
+        object.properties.push(property)
+      }
+      current = property.value as t.Node
+      continue
+    }
+
+    const array = assertArray(current, pathValue)
+    if (token.index < 0 || token.index > array.elements.length) {
+      throw new EntryEditingError('invalid_path', `Array index out of range for ${pathValue}`, {
+        path: pathValue,
+        index: token.index,
+      })
+    }
+    if (isLast) {
+      array.elements[token.index] = await expressionFromInput(rawValue, ctx)
+      return
+    }
+    if (!array.elements[token.index])
+      array.elements[token.index] = createContainerForNext(tokens[index + 1])
+    current = array.elements[token.index] as t.Node
+  }
+}
+
+const unsetPathValue = (root: t.ObjectExpression, pathValue: string) => {
+  const tokens = parsePath(pathValue)
+  let current: t.Node = root
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index]
+    const isLast = index === tokens.length - 1
+    if ('key' in token) {
+      const object = assertObject(current, pathValue)
+      if (isLast) {
+        removeObjectProperty(object, token.key)
+        return
+      }
+      const property = getObjectProperty(object, token.key)
+      if (!property) return
+      current = property.value as t.Node
+      continue
+    }
+
+    const array = assertArray(current, pathValue)
+    if (token.index < 0 || token.index >= array.elements.length) return
+    if (isLast) {
+      array.elements.splice(token.index, 1)
+      return
+    }
+    const element = array.elements[token.index]
+    if (!element) return
+    current = element
+  }
+}
+
+const getSwitchTarget = (entryObject: t.ObjectExpression, switchTarget: string | number) => {
+  const switchesProperty = getObjectProperty(entryObject, 'switches')
+  if (!switchesProperty) {
+    throw new EntryEditingError('fallback_recommended', 'Entry has no switches array', {
+      path: 'switches',
+    })
+  }
+  const switches = assertArray(switchesProperty.value as t.Node, 'switches')
+  const index =
+    typeof switchTarget === 'number'
+      ? switchTarget
+      : switches.elements.findIndex(
+          (element) =>
+            t.isObjectExpression(element) && getStringProperty(element, 'id') === switchTarget,
+        )
+
+  if (index < 0 || index >= switches.elements.length) {
+    throw new EntryEditingError('entry_not_found', `Switch not found: ${switchTarget}`, {
+      switch: switchTarget,
+    })
+  }
+
+  const item = switches.elements[index]
+  if (!t.isObjectExpression(item)) {
+    throw new EntryEditingError(
+      'fallback_recommended',
+      `Switch ${String(switchTarget)} is not an object literal. Edit this file directly for this one.`,
+      { switch: switchTarget },
+    )
+  }
+  return item
+}
+
+const relativeImportSource = (fromFile: string, toFile: string) => {
+  const withoutExt = toFile.replace(/\.[tj]sx?$/, '')
+  let relative = path.relative(path.dirname(fromFile), withoutExt).replace(/\\/g, '/')
+  if (!relative.startsWith('.')) relative = `./${relative}`
+  return relative
+}
+
+const getTopLevelNames = (ast: t.File) => {
+  const names = new Set<string>()
+  ast.program.body.forEach((statement) => {
+    if (t.isImportDeclaration(statement)) {
+      statement.specifiers.forEach((specifier) => names.add(specifier.local.name))
+      return
+    }
+    if (t.isExportNamedDeclaration(statement) && t.isVariableDeclaration(statement.declaration)) {
+      statement.declaration.declarations.forEach((declarator) => {
+        if (t.isIdentifier(declarator.id)) names.add(declarator.id.name)
+      })
+    }
+  })
+  return names
+}
+
+const insertImport = (ast: t.File, declaration: t.ImportDeclaration) => {
+  const lastImportIndex = ast.program.body.findLastIndex((statement) =>
+    t.isImportDeclaration(statement),
+  )
+  ast.program.body.splice(lastImportIndex + 1, 0, declaration)
+}
+
+const ensureNamespaceImport = (
+  parsed: ParsedFile,
+  namespace: string,
+  source: string,
+  preferredLocal: string,
+) => {
+  for (const statement of parsed.ast.program.body) {
+    if (!t.isImportDeclaration(statement) || statement.source.value !== source) continue
+    const namespaceImport = statement.specifiers.find(t.isImportNamespaceSpecifier)
+    if (namespaceImport) return namespaceImport.local.name
+  }
+
+  const usedNames = getTopLevelNames(parsed.ast)
+  let localName = preferredLocal
+  if (usedNames.has(localName)) {
+    let index = 1
+    while (usedNames.has(`${localName}${index}`)) index += 1
+    localName = `${localName}${index}`
+  }
+
+  const declaration = t.importDeclaration(
+    [t.importNamespaceSpecifier(t.identifier(localName))],
+    t.stringLiteral(source),
+  )
+  insertImport(parsed.ast, declaration)
+  return localName
+}
+
+const ensureBricksCtorImport = (
+  ast: t.File,
+  importKind: 'type' | 'value',
+  names: Iterable<string>,
+) => {
+  const missing = new Set(Array.from(names).filter(Boolean))
+  if (missing.size === 0) return
+
+  for (const statement of ast.program.body) {
+    if (!t.isImportDeclaration(statement) || statement.source.value !== 'bricks-ctor') continue
+    const isTypeImport = statement.importKind === 'type'
+    if ((importKind === 'type') !== isTypeImport) continue
+
+    statement.specifiers.forEach((specifier) => {
+      if (!t.isImportSpecifier(specifier)) return
+      const imported = specifier.imported
+      if (t.isIdentifier(imported)) missing.delete(imported.name)
+      if (t.isStringLiteral(imported)) missing.delete(imported.value)
+    })
+
+    missing.forEach((name) => {
+      statement.specifiers.push(t.importSpecifier(t.identifier(name), t.identifier(name)))
+    })
+    return
+  }
+
+  const declaration = t.importDeclaration(
+    Array.from(missing).map((name) => t.importSpecifier(t.identifier(name), t.identifier(name))),
+    t.stringLiteral('bricks-ctor'),
+  )
+  if (importKind === 'type') declaration.importKind = 'type'
+  insertImport(ast, declaration)
+}
+
+const applyPendingImports = (ctx: EditContext) => {
+  ensureBricksCtorImport(ctx.parsed.ast, 'type', ctx.typeImports)
+  ensureBricksCtorImport(ctx.parsed.ast, 'value', ctx.valueImports)
+}
+
+const resolveSubspaceDir = async (
+  projectDir: string,
+  currentSubspaceDir: string,
+  subspace?: string | number,
+) => {
+  if (subspace == null || subspace === '') return currentSubspaceDir
+  if (typeof subspace === 'number')
+    return path.join(projectDir, 'subspaces', `subspace-${subspace}`)
+
+  const normalized = String(subspace)
+  if (/^\d+$/.test(normalized)) return path.join(projectDir, 'subspaces', `subspace-${normalized}`)
+  if (/^subspace-\d+$/.test(normalized)) return path.join(projectDir, 'subspaces', normalized)
+  if (normalized.includes('/')) return resolveProjectPath(projectDir, normalized)
+
+  const subspaceDirs = await getSubspaceDirs(projectDir)
+  for (const subspaceDir of subspaceDirs) {
+    const indexPath = path.join(subspaceDir, 'index.ts')
+    const source = await readFile(indexPath, 'utf8').catch(() => '')
+    if (!source) continue
+    const ast = parseFileSource(source, projectRelativePath(projectDir, indexPath))
+    let matched = false
+    traverse(ast, {
+      ObjectProperty(propertyPath: any) {
+        if (getPropertyKeyName(propertyPath.node.key) !== 'id') return
+        if (
+          t.isStringLiteral(propertyPath.node.value) &&
+          propertyPath.node.value.value === normalized
+        ) {
+          matched = true
+          propertyPath.stop()
+        }
+      },
+    })
+    if (matched) return subspaceDir
+  }
+
+  throw new EntryEditingError('reference_not_found', `Subspace not found: ${normalized}`, {
+    subspace: normalized,
+  })
+}
+
+const resolveReference = async (
+  projectDir: string,
+  currentFile: string,
+  ref: string,
+  subspace?: string | number,
+): Promise<ReferenceResolution> => {
+  const currentSubspaceDir = getSubspaceDirFromPath(currentFile)
+  const targetSubspaceDir = await resolveSubspaceDir(projectDir, currentSubspaceDir, subspace)
+  const files = await getEntryFilesInSubspace(targetSubspaceDir)
+  const matches: ReferenceResolution[] = []
+
+  for (const file of files) {
+    const parsed = await readParsedFile(projectDir, file)
+    const kind = parsed.kind
+    for (const entry of getExportEntries(parsed.ast)) {
+      if (entry.name !== ref && entry.id !== ref && entry.alias !== ref) continue
+      const sameFile = path.resolve(file) === path.resolve(currentFile)
+      const subspaceLabel = path.basename(targetSubspaceDir)
+      matches.push({
+        input: ref,
+        id: entry.id,
+        alias: entry.alias,
+        varName: entry.name,
+        namespace: kind.namespace,
+        display: `${kind.namespace}.${entry.name}`,
+        targetAbsPath: file,
+        sameFile,
+        subspaceLabel,
+        importSource: sameFile ? undefined : relativeImportSource(currentFile, file),
+      })
+    }
+  }
+
+  if (matches.length === 0) {
+    throw new EntryEditingError('reference_not_found', `Reference not found: ${ref}`, {
+      ref,
+      subspace: subspace ?? path.basename(currentSubspaceDir),
+    })
+  }
+  if (matches.length > 1) {
+    throw new EntryEditingError('ambiguous_reference', `Reference is ambiguous: ${ref}`, {
+      ref,
+      matches: matches.map((match) => ({
+        file: projectRelativePath(projectDir, match.targetAbsPath),
+        entry: match.varName,
+        id: match.id,
+        alias: match.alias,
+      })),
+    })
+  }
+  return matches[0]
+}
+
+const resolvedReferenceExpression = async (
+  ref: string,
+  ctx: EditContext,
+  subspace?: string | number,
+) => {
+  const resolved = await resolveReference(ctx.projectDir, ctx.parsed.absPath, ref, subspace)
+  if (resolved.sameFile) {
+    ctx.references.push(resolved)
+    return t.identifier(resolved.varName)
+  }
+
+  const currentSubspace = getSubspaceDirFromPath(ctx.parsed.absPath)
+  const targetSubspace = getSubspaceDirFromPath(resolved.targetAbsPath)
+  const sameSubspace = currentSubspace === targetSubspace
+  const subspaceSuffix = resolved.subspaceLabel.replace(/[^a-zA-Z0-9_$]/g, '')
+  const preferredLocal = sameSubspace
+    ? resolved.namespace
+    : `${subspaceSuffix}${resolved.namespace[0].toUpperCase()}${resolved.namespace.slice(1)}`
+  const local = ensureNamespaceImport(
+    ctx.parsed,
+    resolved.namespace,
+    resolved.importSource!,
+    preferredLocal,
+  )
+  resolved.importLocal = local
+  ctx.references.push({ ...resolved, display: `${local}.${resolved.varName}`, importLocal: local })
+  return t.memberExpression(t.identifier(local), t.identifier(resolved.varName))
+}
+
+const expressionFromRaw = (raw: string) => {
+  try {
+    return parseExpression(raw, { plugins: ['typescript'] }) as t.Expression
+  } catch (err: any) {
+    throw new EntryEditingError('invalid_expr', `Invalid TypeScript expression: ${err.message}`, {
+      expr: raw,
+    })
+  }
+}
+
+const expressionFromInput = async (value: unknown, ctx: EditContext): Promise<t.Expression> => {
+  if (isRecord(value) && typeof value.expr === 'string' && Object.keys(value).length === 1) {
+    return expressionFromRaw(value.expr)
+  }
+
+  if (isRecord(value) && typeof value.link === 'string') {
+    ctx.valueImports.add('linkData')
+    const refExpr = await resolvedReferenceExpression(value.link, ctx, value.subspace as any)
+    return t.callExpression(t.identifier('linkData'), [t.arrowFunctionExpression([], refExpr)])
+  }
+
+  if (isRecord(value) && typeof value.ref === 'string') {
+    const refExpr = await resolvedReferenceExpression(value.ref, ctx, value.subspace as any)
+    return t.arrowFunctionExpression([], refExpr)
+  }
+
+  if (Array.isArray(value)) {
+    return t.arrayExpression(await Promise.all(value.map((item) => expressionFromInput(item, ctx))))
+  }
+
+  if (isRecord(value)) {
+    const properties = await Promise.all(
+      Object.entries(value).map(async ([key, item]) =>
+        t.objectProperty(makeObjectKey(key), await expressionFromInput(item, ctx)),
+      ),
+    )
+    return t.objectExpression(properties)
+  }
+
+  if (value === undefined) return t.identifier('undefined')
+  return t.valueToNode(value) as t.Expression
+}
+
+const referenceInputDetails = (references: ReferenceResolution[]) =>
+  references.map((reference) => ({
+    input: reference.input,
+    id: reference.id,
+    alias: reference.alias,
+    resolved: reference.importLocal
+      ? `${reference.importLocal}.${reference.varName}`
+      : reference.sameFile
+        ? reference.varName
+        : reference.display,
+    file: reference.targetAbsPath,
+  }))
+
+const printAndFormat = async (parsed: ParsedFile) => {
+  const generated = generate(parsed.ast, { comments: true }, parsed.source).code
+  const formatted = await formatWithOxfmt(parsed.absPath, generated, oxfmtOptions)
+  if (formatted.errors.length > 0) {
+    throw new EntryEditingError('format_failed', `oxfmt failed for ${parsed.relPath}`, {
+      file: parsed.relPath,
+      errors: formatted.errors,
+    })
+  }
+  return formatted.code
+}
+
+const writeParsedFile = async (parsed: ParsedFile) => {
+  const code = await printAndFormat(parsed)
+  parseFileSource(code, parsed.relPath)
+  await writeFile(parsed.absPath, code)
+  return code
+}
+
+const appendEditRecord = async (projectDir: string, record: Record<string, unknown>) => {
+  const bricksDir = path.join(projectDir, '.bricks')
+  await mkdir(bricksDir, { recursive: true })
+  await ensureAuditLogIgnored(projectDir)
+  await appendFile(path.join(bricksDir, 'edits.jsonl'), `${JSON.stringify(record)}\n`)
+}
+
+const ensureAuditLogIgnored = async (projectDir: string) => {
+  const gitignorePath = path.join(projectDir, '.gitignore')
+  const content = await readFile(gitignorePath, 'utf8').catch((err: any) => {
+    if (err?.code === 'ENOENT') return ''
+    throw err
+  })
+  const ignored = content
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .some((line) => line === auditLogIgnoreEntry || line === '.bricks/' || line === '.bricks')
+  if (ignored) return
+
+  const prefix = content && !content.endsWith('\n') ? '\n' : ''
+  await writeFile(
+    gitignorePath,
+    `${content}${prefix}\n# MCP entry-editing audit log\n${auditLogIgnoreEntry}\n`,
+  )
+}
+
+const summarizeTarget = (parsed?: ParsedFile, entry?: ExportEntry) => {
+  if (!parsed) return undefined
+  const subspace = getSubspaceLabelFromPath(parsed.absPath)
+  return `${entry?.name || 'entry'} (${parsed.kind.kind}, ${subspace})`
+}
+
+const runOperation = async (
+  projectDir: string,
+  tool: string,
+  input: any,
+  operation: () => Promise<Record<string, unknown>>,
+) => {
+  const baseRecord = {
+    ts: new Date().toISOString(),
+    tool,
+    op: input?.op || (input?.set ? 'set' : input?.unset ? 'unset' : tool),
+    target: {
+      file: input?.file,
+      entry: input?.entry,
+      id: input?.id,
+    },
+    provenance: {
+      session: process.env.BRICKS_CTOR_SESSION_ID || process.env.CODEX_SESSION_ID,
+      agent: process.env.BRICKS_CTOR_AGENT_ID || process.env.USER,
+    },
+  }
+
+  try {
+    const result = await operation()
+    const record: any = { ...baseRecord, ...result }
+    await appendEditRecord(projectDir, record).catch((err) => {
+      record.auditError = err.message
+    })
+    return record
+  } catch (err: any) {
+    const error =
+      err instanceof EntryEditingError
+        ? err
+        : new EntryEditingError('error', err.message || String(err), undefined, true)
+    const outcome = error.code === 'fallback_recommended' ? 'fallback_recommended' : 'error'
+    const record: any = {
+      ...baseRecord,
+      outcome,
+      // Keep the failing input in the audit record so error reports are diagnosable
+      // (success records already carry the applied change).
+      input,
+      error: {
+        code: error.code,
+        message: error.message,
+        details: error.details,
+      },
+      summary:
+        outcome === 'fallback_recommended'
+          ? `${tool} could not safely edit this standard path; edit the file directly`
+          : `${tool} failed: ${error.message}`,
+      isError: error.isMcpError || outcome === 'error',
+    }
+    await appendEditRecord(projectDir, record).catch((auditErr) => {
+      record.auditError = auditErr.message
+    })
+    return record
+  }
+}
+
+const editEntry = async (projectDir: string, input: any) =>
+  runOperation(projectDir, 'edit_entry', input, async () => {
+    const { parsed, entry, object } = await resolveEditableTarget(projectDir, input)
+    const ctx: EditContext = {
+      projectDir,
+      parsed,
+      references: [],
+      typeImports: new Set(),
+      valueImports: new Set(),
+    }
+    const targetObject = input.switch == null ? object : getSwitchTarget(object, input.switch)
+
+    for (const [pathValue, value] of Object.entries(input.set || {})) {
+      await setPathValue(targetObject, pathValue, value, ctx)
+    }
+    for (const pathValue of input.unset || []) {
+      unsetPathValue(targetObject, pathValue)
+    }
+
+    applyPendingImports(ctx)
+    await writeParsedFile(parsed)
+    const verify = await verifyProject(projectDir, input.verify)
+    const target = summarizeTarget(parsed, entry)
+    return {
+      file: parsed.relPath,
+      entry: entry.name,
+      id: entry.id,
+      change: {
+        set: input.set || {},
+        unset: input.unset || [],
+        references: referenceInputDetails(ctx.references),
+      },
+      outcome: verify.status === 'compile:failed' ? 'verify_failed' : 'ok',
+      verify,
+      summary: `edited ${target} -> ${verify.status}`,
+    }
+  })
+
+const describeUnsupportedStatement = (type: string) => {
+  switch (type) {
+    case 'IfStatement':
+      return 'an if statement'
+    case 'ForStatement':
+    case 'ForOfStatement':
+    case 'ForInStatement':
+      return 'a for loop'
+    case 'WhileStatement':
+    case 'DoWhileStatement':
+      return 'a while loop'
+    case 'SwitchStatement':
+      return 'a switch statement'
+    case 'TryStatement':
+      return 'a try/catch block'
+    case 'FunctionDeclaration':
+      return 'a function declaration'
+    case 'ReturnStatement':
+      return 'a return before the final statement'
+    default:
+      return `a ${type}`
+  }
+}
+
+// Mirrors the runtime expression fold (bricks-core data-operation.js compile()):
+// statements must reduce to a single expression, so only expression statements,
+// simple const/let declarations, and a final return (inside an IIFE) evaluate.
+// Anything else fails at runtime on device and simulator alike, with the error
+// visible only in a DevTools session — reject it at edit time instead.
+const findUnsupportedExpressionPart = (
+  statements: any[],
+  insideFunction: boolean,
+): string | null => {
+  for (let index = 0; index < statements.length; index += 1) {
+    const statement = statements[index]
+    const isLast = index === statements.length - 1
+    if (statement.type === 'ExpressionStatement') {
+      const offending = findUnsupportedInIife(statement.expression)
+      if (offending) return offending
+      continue
+    }
+    if (statement.type === 'VariableDeclaration') {
+      for (const declaration of statement.declarations) {
+        if (declaration.id.type !== 'Identifier' || !declaration.init) {
+          return 'a destructuring or uninitialized declaration'
+        }
+      }
+      continue
+    }
+    if (insideFunction && isLast && statement.type === 'ReturnStatement') {
+      const offending = statement.argument ? findUnsupportedInIife(statement.argument) : null
+      if (offending) return offending
+      continue
+    }
+    return describeUnsupportedStatement(statement.type)
+  }
+  return null
+}
+
+const findUnsupportedInIife = (expression: any): string | null => {
+  if (
+    expression?.type !== 'CallExpression' ||
+    expression.arguments?.length ||
+    (expression.callee?.type !== 'ArrowFunctionExpression' &&
+      expression.callee?.type !== 'FunctionExpression')
+  ) {
+    return null
+  }
+  const body = expression.callee.body
+  if (body?.type === 'BlockStatement') return findUnsupportedExpressionPart(body.body, true)
+  return findUnsupportedInIife(body)
+}
+
+const assertEvaluableExpression = (expression: string) => {
+  let program: any
+  try {
+    // Same parser and options the runtime uses (acorn, ES2020, no top-level return).
+    program = parseRuntimeExpression(expression, { ecmaVersion: 2020 })
+  } catch (err: any) {
+    throw new EntryEditingError(
+      'invalid_action',
+      `PROPERTY_BANK_EXPRESSION does not parse: ${err.message}`,
+      { expression },
+    )
+  }
+  const offending = findUnsupportedExpressionPart(program.body, false)
+  if (offending) {
+    throw new EntryEditingError(
+      'invalid_action',
+      `PROPERTY_BANK_EXPRESSION cannot evaluate ${offending}: the runtime folds the expression into a single expression (expression statements, simple const/let declarations, and a final return inside an IIFE only). Use ternaries instead of statements, or move branching logic to a DataCalculationScript.`,
+      { expression },
+    )
+  }
+}
+
+// Agents copy the compiled EventAction shape from existing source
+// ({ handler, action: { name, params: [...], dataParams: [...] }, waitAsync }), so
+// normalize it to the flattened tool grammar instead of rejecting it.
+const normalizeActionInput = (actionInput: any) => {
+  if (!isRecord(actionInput) || !isRecord(actionInput.action)) return actionInput
+  const compiled: any = actionInput.action
+  const normalized: any = {
+    handler: actionInput.handler,
+    name: compiled.name ?? compiled.__actionName,
+    waitAsync: actionInput.waitAsync,
+  }
+  if (compiled.cast) normalized.cast = compiled.cast
+  if (Array.isArray(compiled.params)) {
+    normalized.params = {}
+    for (const param of compiled.params) {
+      if (!isRecord(param) || typeof param.input !== 'string') {
+        throw new EntryEditingError(
+          'invalid_action',
+          'Compiled action params entries require { input: "name", value }',
+          { param },
+        )
+      }
+      normalized.params[param.input] = param.value
+    }
+  }
+  if (Array.isArray(compiled.dataParams)) {
+    normalized.dataParams = {}
+    for (const param of compiled.dataParams) {
+      const ref = isRecord(param?.input) ? param.input.ref : param?.input
+      if (typeof ref !== 'string' || !ref) {
+        throw new EntryEditingError(
+          'invalid_action',
+          'Compiled action dataParams entries require { input: dataRef, value }',
+          { param },
+        )
+      }
+      normalized.dataParams[ref] = param.value
+    }
+  }
+  return normalized
+}
+
+const buildAction = async (rawActionInput: any, ctx: EditContext) => {
+  if (rawActionInput?.expr) return expressionFromInput(rawActionInput, ctx)
+  const actionInput = normalizeActionInput(rawActionInput)
+
+  const actionName = actionInput?.name
+  if (!actionName) {
+    throw new EntryEditingError('invalid_action', 'Action requires name')
+  }
+
+  if (actionName === 'PROPERTY_BANK_EXPRESSION' && isRecord(actionInput.params)) {
+    const expression = (actionInput.params as any).expression
+    if (typeof expression === 'string') assertEvaluableExpression(expression)
+  }
+
+  let handler: t.Expression
+  let parent = 'System'
+  let cast = actionInput.cast
+
+  if (actionInput.handler === 'system' || actionInput.handler == null) {
+    handler = t.stringLiteral('system')
+    cast ||= `SystemAction${actionName
+      .toLowerCase()
+      .split('_')
+      .filter(Boolean)
+      .map((part: string) => `${part[0].toUpperCase()}${part.slice(1)}`)
+      .join('')}`
+  } else if (isRecord(actionInput.handler) && typeof actionInput.handler.ref === 'string') {
+    const resolved = await resolveReference(
+      ctx.projectDir,
+      ctx.parsed.absPath,
+      actionInput.handler.ref,
+      actionInput.handler.subspace as any,
+    )
+    // Codegen only supports brick/generator getter handlers (subspaces use the
+    // string-id form); any other entity kind would emit an invalid action.
+    if (resolved.namespace !== 'bricks' && resolved.namespace !== 'generators') {
+      throw new EntryEditingError(
+        'invalid_action',
+        `Action handler must be a brick or generator, got ${resolved.namespace}: ${actionInput.handler.ref}`,
+        { handler: actionInput.handler },
+      )
+    }
+    parent = resolved.namespace === 'bricks' ? 'Brick' : 'Generator'
+    const refExpr = await resolvedReferenceExpression(
+      actionInput.handler.ref,
+      ctx,
+      actionInput.handler.subspace as any,
+    )
+    handler = t.arrowFunctionExpression([], refExpr)
+  } else if (isRecord(actionInput.handler) && typeof actionInput.handler.subspace === 'string') {
+    handler = t.stringLiteral(actionInput.handler.subspace)
+    parent = 'Subspace'
+  } else {
+    throw new EntryEditingError('invalid_action', 'Unsupported action handler', {
+      handler: actionInput.handler,
+    })
+  }
+
+  const actionProperties: t.ObjectProperty[] = [
+    t.objectProperty(t.identifier('__actionName'), t.stringLiteral(actionName)),
+    t.objectProperty(t.identifier('parent'), t.stringLiteral(parent)),
+    t.objectProperty(t.identifier('name'), t.stringLiteral(actionName)),
+  ]
+
+  if (actionInput.params) {
+    const params = await Promise.all(
+      Object.entries(actionInput.params).map(async ([inputName, value]) =>
+        t.objectExpression([
+          t.objectProperty(t.identifier('input'), t.stringLiteral(inputName)),
+          t.objectProperty(t.identifier('value'), await expressionFromInput(value, ctx)),
+        ]),
+      ),
+    )
+    actionProperties.push(t.objectProperty(t.identifier('params'), t.arrayExpression(params)))
+  }
+
+  if (actionInput.dataParams) {
+    const params = await Promise.all(
+      Object.entries(actionInput.dataParams).map(async ([dataRef, value]) => {
+        const refExpr = await resolvedReferenceExpression(dataRef, ctx)
+        return t.objectExpression([
+          t.objectProperty(t.identifier('input'), t.arrowFunctionExpression([], refExpr)),
+          t.objectProperty(t.identifier('value'), await expressionFromInput(value, ctx)),
+        ])
+      }),
+    )
+    actionProperties.push(t.objectProperty(t.identifier('dataParams'), t.arrayExpression(params)))
+  }
+
+  let actionExpression: t.Expression = t.objectExpression(actionProperties)
+  if (cast) {
+    ctx.typeImports.add(cast)
+    actionExpression = t.tsAsExpression(
+      actionExpression,
+      t.tsTypeReference(t.identifier(cast)),
+    ) as any
+  }
+
+  return t.objectExpression([
+    t.objectProperty(t.identifier('handler'), handler),
+    t.objectProperty(t.identifier('action'), actionExpression),
+    t.objectProperty(t.identifier('waitAsync'), t.booleanLiteral(!!actionInput.waitAsync)),
+  ])
+}
+
+const getOrCreateObjectProperty = (object: t.ObjectExpression, key: string, pathValue: string) => {
+  let property = getObjectProperty(object, key)
+  if (!property) {
+    property = t.objectProperty(makeObjectKey(key), t.objectExpression([]))
+    object.properties.push(property)
+  }
+  return assertObject(property.value as t.Node, pathValue)
+}
+
+const getOrCreateArrayProperty = (object: t.ObjectExpression, key: string, pathValue: string) => {
+  let property = getObjectProperty(object, key)
+  if (!property) {
+    property = t.objectProperty(makeObjectKey(key), t.arrayExpression([]))
+    object.properties.push(property)
+  }
+  return assertArray(property.value as t.Node, pathValue)
+}
+
+const editEvents = async (projectDir: string, input: any) =>
+  runOperation(projectDir, 'edit_events', input, async () => {
+    const { parsed, entry, object } = await resolveEditableTarget(projectDir, input)
+    const ctx: EditContext = {
+      projectDir,
+      parsed,
+      references: [],
+      typeImports: new Set(),
+      valueImports: new Set(),
+    }
+    const targetObject = input.switch == null ? object : getSwitchTarget(object, input.switch)
+    const op = input.op
+
+    if (op === 'clear' || op === 'remove' || op === 'move') {
+      const eventsProperty = getObjectProperty(targetObject, 'events')
+      const eventsObject = eventsProperty
+        ? assertObject(eventsProperty.value as t.Node, 'events')
+        : null
+      const eventProperty = eventsObject ? getObjectProperty(eventsObject, input.event) : null
+      const eventArray = eventProperty
+        ? assertArray(eventProperty.value as t.Node, `events.${input.event}`)
+        : null
+      if (op === 'clear') {
+        // Codegen omits empty event arrays, so clear drops the event key entirely.
+        if (eventsObject) removeObjectProperty(eventsObject, input.event)
+      } else if (op === 'move') {
+        if (input.index == null) {
+          throw new EntryEditingError('invalid_index', 'move requires index')
+        }
+        if (!eventArray || input.index < 0 || input.index >= eventArray.elements.length) {
+          throw new EntryEditingError('invalid_index', 'move index out of range', {
+            index: input.index,
+          })
+        }
+        const to = Number(input.to)
+        if (!Number.isFinite(to) || to < 0 || to >= eventArray.elements.length) {
+          throw new EntryEditingError('invalid_index', 'move requires valid to index', {
+            to: input.to,
+          })
+        }
+        const [moved] = eventArray.elements.splice(input.index, 1)
+        eventArray.elements.splice(to, 0, moved)
+      } else {
+        if (input.index == null) {
+          throw new EntryEditingError('invalid_index', 'remove requires index')
+        }
+        if (!eventArray || input.index < 0 || input.index >= eventArray.elements.length) {
+          throw new EntryEditingError('invalid_index', 'remove index out of range', {
+            index: input.index,
+          })
+        }
+        eventArray.elements.splice(input.index, 1)
+        if (eventArray.elements.length === 0 && eventsObject) {
+          removeObjectProperty(eventsObject, input.event)
+        }
+      }
+    } else if (op === 'add' || op === 'replace') {
+      const action = await buildAction(input.action, ctx)
+      const eventsObject = getOrCreateObjectProperty(targetObject, 'events', 'events')
+      const eventArray = getOrCreateArrayProperty(
+        eventsObject,
+        input.event,
+        `events.${input.event}`,
+      )
+      const index = input.index ?? eventArray.elements.length
+      if (op === 'replace') {
+        if (index < 0 || index >= eventArray.elements.length) {
+          throw new EntryEditingError('invalid_index', 'replace index out of range', { index })
+        }
+        eventArray.elements[index] = action
+      } else {
+        if (index < 0 || index > eventArray.elements.length) {
+          throw new EntryEditingError('invalid_index', 'add index out of range', { index })
+        }
+        eventArray.elements.splice(index, 0, action)
+      }
+    } else {
+      throw new EntryEditingError('invalid_op', `Unsupported edit_events op: ${op}`)
+    }
+
+    applyPendingImports(ctx)
+    await writeParsedFile(parsed)
+    const verify = await verifyProject(projectDir, input.verify)
+    return {
+      file: parsed.relPath,
+      entry: entry.name,
+      id: entry.id,
+      change: {
+        event: input.event,
+        op,
+        index: input.index,
+        references: referenceInputDetails(ctx.references),
+      },
+      outcome: verify.status === 'compile:failed' ? 'verify_failed' : 'ok',
+      verify,
+      summary: `${op} event ${input.event} on ${summarizeTarget(parsed, entry)} -> ${verify.status}`,
+    }
+  })
+
+// The CanvasItem type requires a numeric frame; reject bad shapes here instead of
+// writing frame: {} and leaving the failure to compile verification.
+const assertCanvasFrame = (frame: any) => {
+  if (isRecord(frame) && typeof frame.expr === 'string') return frame
+  if (!isRecord(frame)) {
+    throw new EntryEditingError(
+      'invalid_item',
+      'Canvas item requires frame { x, y, width, height }',
+    )
+  }
+  for (const key of ['x', 'y', 'width', 'height']) {
+    if (typeof frame[key] !== 'number') {
+      throw new EntryEditingError('invalid_item', `Canvas item frame requires numeric ${key}`, {
+        frame,
+      })
+    }
+  }
+  return frame
+}
+
+const buildCanvasItem = async (item: any, ctx: EditContext, fallbackFrame?: any) => {
+  if (!item?.ref) throw new EntryEditingError('invalid_item', 'Canvas item requires ref')
+  const frame = assertCanvasFrame(item.frame ?? fallbackFrame)
+  const refExpr = await resolvedReferenceExpression(item.ref, ctx, item.subspace)
+  return t.objectExpression([
+    t.objectProperty(t.identifier('item'), t.arrowFunctionExpression([], refExpr)),
+    t.objectProperty(t.identifier('frame'), await expressionFromInput(frame, ctx)),
+    ...(item.hidden == null
+      ? []
+      : [t.objectProperty(t.identifier('hidden'), t.booleanLiteral(!!item.hidden))]),
+  ])
+}
+
+const editCanvasItems = async (projectDir: string, input: any) =>
+  runOperation(projectDir, 'edit_canvas_items', input, async () => {
+    const { parsed, entry, object } = await resolveEditableTarget(projectDir, input)
+    if (parsed.kind.kind !== 'canvas') {
+      throw new EntryEditingError(
+        'invalid_file',
+        'edit_canvas_items only edits canvases.ts entries',
+        {
+          file: parsed.relPath,
+        },
+      )
+    }
+    const ctx: EditContext = {
+      projectDir,
+      parsed,
+      references: [],
+      typeImports: new Set(),
+      valueImports: new Set(),
+    }
+    const items = getOrCreateArrayProperty(object, 'items', 'items')
+    const op = input.op
+
+    if (op === 'add' || op === 'replace') {
+      const item = await buildCanvasItem(input.item, ctx, input.frame)
+      const index = input.index ?? items.elements.length
+      if (op === 'replace') {
+        if (index < 0 || index >= items.elements.length) {
+          throw new EntryEditingError('invalid_index', 'replace index out of range', { index })
+        }
+        items.elements[index] = item
+      } else {
+        if (index < 0 || index > items.elements.length) {
+          throw new EntryEditingError('invalid_index', 'add index out of range', { index })
+        }
+        items.elements.splice(index, 0, item)
+      }
+    } else if (op === 'remove') {
+      if (input.index == null) throw new EntryEditingError('invalid_index', 'remove requires index')
+      if (input.index < 0 || input.index >= items.elements.length) {
+        throw new EntryEditingError('invalid_index', 'remove index out of range', {
+          index: input.index,
+        })
+      }
+      items.elements.splice(input.index, 1)
+    } else if (op === 'move') {
+      if (input.index == null) throw new EntryEditingError('invalid_index', 'move requires index')
+      if (!input.frame) throw new EntryEditingError('invalid_item', 'move requires frame')
+      if (input.index < 0 || input.index >= items.elements.length) {
+        throw new EntryEditingError('invalid_index', 'move index out of range', {
+          index: input.index,
+        })
+      }
+      const item = items.elements[input.index]
+      if (!t.isObjectExpression(item)) {
+        throw new EntryEditingError(
+          'fallback_recommended',
+          'Canvas item is not an object literal',
+          {
+            index: input.index,
+          },
+        )
+      }
+      setObjectProperty(
+        item,
+        'frame',
+        await expressionFromInput(assertCanvasFrame(input.frame), ctx),
+      )
+    } else {
+      throw new EntryEditingError('invalid_op', `Unsupported edit_canvas_items op: ${op}`)
+    }
+
+    applyPendingImports(ctx)
+    await writeParsedFile(parsed)
+    const verify = await verifyProject(projectDir, input.verify)
+    return {
+      file: parsed.relPath,
+      entry: entry.name,
+      id: entry.id,
+      change: { op, index: input.index, references: referenceInputDetails(ctx.references) },
+      outcome: verify.status === 'compile:failed' ? 'verify_failed' : 'ok',
+      verify,
+      summary: `${op} canvas item on ${summarizeTarget(parsed, entry)} -> ${verify.status}`,
+    }
+  })
+
+// Compiled SwitchCond shapes (__typename form) are what agents see when reading
+// existing source, so accept them as input by normalizing to the structured forms.
+const normalizeCondInput = (cond: any) => {
+  switch (cond?.__typename) {
+    case 'SwitchCondInnerStateCurrentCanvas':
+      return {
+        type: 'inner_state',
+        key: 'current_canvas',
+        value: cond.value,
+        subspace: cond.subspace,
+      }
+    case 'SwitchCondInnerStateOutlet':
+      return { type: 'inner_state', outlet: cond.outlet, value: cond.value }
+    case 'SwitchCondData':
+      return {
+        type: 'property_bank',
+        ref: cond.data ?? cond.ref,
+        value: cond.value,
+        subspace: cond.subspace,
+      }
+    case 'SwitchCondPropertyBankByItemKey':
+      return {
+        type: 'property_bank_by_item_key',
+        ref: cond.data ?? cond.ref,
+        value: cond.value,
+        subspace: cond.subspace,
+      }
+    default:
+      return cond
+  }
+}
+
+const condExpression = async (condInput: any, ctx: EditContext) => {
+  const cond = normalizeCondInput(condInput)
+  if (cond?.expr) return expressionFromInput(cond, ctx)
+  if (cond?.type === 'inner_state' && cond.key === 'current_canvas') {
+    const refExpr = await resolvedReferenceExpression(cond.value, ctx, cond.subspace)
+    return t.objectExpression([
+      t.objectProperty(
+        t.identifier('__typename'),
+        t.stringLiteral('SwitchCondInnerStateCurrentCanvas'),
+      ),
+      t.objectProperty(t.identifier('value'), t.arrowFunctionExpression([], refExpr)),
+    ])
+  }
+  if (cond?.type === 'inner_state') {
+    const outlet = cond.outlet || cond.key
+    if (!outlet) {
+      throw new EntryEditingError(
+        'invalid_switch',
+        'Switch inner-state outlet condition requires outlet or key',
+      )
+    }
+    return t.objectExpression([
+      t.objectProperty(t.identifier('__typename'), t.stringLiteral('SwitchCondInnerStateOutlet')),
+      t.objectProperty(t.identifier('outlet'), t.stringLiteral(outlet)),
+      t.objectProperty(t.identifier('value'), await expressionFromInput(cond.value, ctx)),
+    ])
+  }
+  const dataRef = cond?.ref || cond?.data || cond?.key
+  if (!dataRef) throw new EntryEditingError('invalid_switch', 'Switch condition requires data ref')
+  const refExpr = await resolvedReferenceExpression(dataRef, ctx, cond.subspace)
+  return t.objectExpression([
+    t.objectProperty(
+      t.identifier('__typename'),
+      t.stringLiteral(
+        cond?.type === 'property_bank_by_item_key'
+          ? 'SwitchCondPropertyBankByItemKey'
+          : 'SwitchCondData',
+      ),
+    ),
+    t.objectProperty(t.identifier('data'), t.arrowFunctionExpression([], refExpr)),
+    t.objectProperty(t.identifier('value'), await expressionFromInput(cond.value, ctx)),
+  ])
+}
+
+const switchKnownFields = new Set([
+  'id',
+  'title',
+  'description',
+  'conds',
+  'override',
+  'property',
+  'outlets',
+  'animation',
+  'events',
+  'disabled',
+  'break',
+])
+
+const buildSwitch = async (switchInput: any, ctx: EditContext) => {
+  for (const key of Object.keys(switchInput)) {
+    if (!switchKnownFields.has(key)) {
+      // Silently dropping unknown fields would lose caller intent (typos included).
+      throw new EntryEditingError('invalid_switch', `Unknown switch field: ${key}`, {
+        field: key,
+        supported: Array.from(switchKnownFields),
+      })
+    }
+  }
+  if (switchInput.events !== undefined) {
+    throw new EntryEditingError(
+      'invalid_switch',
+      'Set switch events with edit_events using its switch parameter',
+    )
+  }
+  if (switchInput.id && !/^BRICK_STATE_GROUP_[0-9a-fA-F-]{36}$/.test(switchInput.id)) {
+    // Compile asserts this pattern, so reject early instead of failing later.
+    throw new EntryEditingError(
+      'invalid_switch',
+      'Switch id must match BRICK_STATE_GROUP_<uuid>; omit id to generate one',
+      { id: switchInput.id },
+    )
+  }
+  const idExpression = switchInput.id
+    ? t.stringLiteral(switchInput.id)
+    : makeIdCallExpression('switch')
+  if (!switchInput.id) ctx.valueImports.add('makeId')
+  const properties: t.ObjectProperty[] = [t.objectProperty(t.identifier('id'), idExpression)]
+  if (switchInput.title != null) {
+    properties.push(t.objectProperty(t.identifier('title'), t.stringLiteral(switchInput.title)))
+  }
+  if (switchInput.description != null) {
+    properties.push(
+      t.objectProperty(t.identifier('description'), t.stringLiteral(switchInput.description)),
+    )
+  }
+  if (switchInput.conds) {
+    properties.push(
+      t.objectProperty(
+        t.identifier('conds'),
+        t.arrayExpression(
+          await Promise.all(
+            switchInput.conds.map(async (item: any) =>
+              t.objectExpression([
+                t.objectProperty(t.identifier('method'), t.stringLiteral(item.method || '==')),
+                t.objectProperty(
+                  t.identifier('cond'),
+                  await condExpression(item.cond || item, ctx),
+                ),
+              ]),
+            ),
+          ),
+        ),
+      ),
+    )
+  }
+  if (switchInput.override) {
+    properties.push(
+      t.objectProperty(
+        t.identifier('override'),
+        await expressionFromInput(switchInput.override, ctx),
+      ),
+    )
+  }
+  for (const facet of ['property', 'outlets', 'animation']) {
+    if (switchInput[facet] != null) {
+      properties.push(
+        t.objectProperty(t.identifier(facet), await expressionFromInput(switchInput[facet], ctx)),
+      )
+    }
+  }
+  if (switchInput.disabled != null) {
+    properties.push(
+      t.objectProperty(t.identifier('disabled'), t.booleanLiteral(!!switchInput.disabled)),
+    )
+  }
+  if (switchInput.break != null) {
+    properties.push(t.objectProperty(t.identifier('break'), t.booleanLiteral(!!switchInput.break)))
+  }
+  return t.objectExpression(properties)
+}
+
+const editSwitches = async (projectDir: string, input: any) =>
+  runOperation(projectDir, 'edit_switches', input, async () => {
+    const { parsed, entry, object } = await resolveEditableTarget(projectDir, input)
+    const ctx: EditContext = {
+      projectDir,
+      parsed,
+      references: [],
+      typeImports: new Set(),
+      valueImports: new Set(),
+    }
+    const switches = getOrCreateArrayProperty(object, 'switches', 'switches')
+    const op = input.op
+
+    const findIndex = (value: string | number | undefined) => {
+      if (typeof value === 'number') return value
+      if (!value) return -1
+      return switches.elements.findIndex(
+        (element) => t.isObjectExpression(element) && getStringProperty(element, 'id') === value,
+      )
+    }
+
+    if (op === 'add' || op === 'replace') {
+      const switchObject = await buildSwitch(input.switch || {}, ctx)
+      const index = input.index == null ? switches.elements.length : findIndex(input.index)
+      if (op === 'replace') {
+        if (index < 0 || index >= switches.elements.length) {
+          throw new EntryEditingError('invalid_index', 'replace index out of range', { index })
+        }
+        switches.elements[index] = switchObject
+      } else {
+        if (index < 0 || index > switches.elements.length) {
+          throw new EntryEditingError('invalid_index', 'add requires a valid switch id or index', {
+            index: input.index,
+          })
+        }
+        switches.elements.splice(index, 0, switchObject)
+      }
+    } else if (op === 'remove') {
+      const index = findIndex(input.index)
+      if (index < 0 || index >= switches.elements.length) {
+        throw new EntryEditingError('invalid_index', 'remove requires a valid switch id or index', {
+          index: input.index,
+        })
+      }
+      switches.elements.splice(index, 1)
+    } else if (op === 'move') {
+      const from = findIndex(input.index)
+      if (from < 0 || from >= switches.elements.length) {
+        throw new EntryEditingError('invalid_index', 'move requires a valid switch id or index', {
+          index: input.index,
+        })
+      }
+      const to = Number(input.to)
+      if (!Number.isFinite(to) || to < 0 || to >= switches.elements.length) {
+        throw new EntryEditingError('invalid_index', 'move requires valid to index', {
+          to: input.to,
+        })
+      }
+      const [item] = switches.elements.splice(from, 1)
+      switches.elements.splice(to, 0, item)
+    } else {
+      throw new EntryEditingError('invalid_op', `Unsupported edit_switches op: ${op}`)
+    }
+
+    applyPendingImports(ctx)
+    await writeParsedFile(parsed)
+    const verify = await verifyProject(projectDir, input.verify)
+    return {
+      file: parsed.relPath,
+      entry: entry.name,
+      id: entry.id,
+      change: { op, index: input.index, references: referenceInputDetails(ctx.references) },
+      outcome: verify.status === 'compile:failed' ? 'verify_failed' : 'ok',
+      verify,
+      summary: `${op} switch on ${summarizeTarget(parsed, entry)} -> ${verify.status}`,
+    }
+  })
+
+const createBaseEntryObject = async (
+  kind: EntryKind,
+  input: any,
+  idExpression: t.Expression,
+  ctx: EditContext,
+) => {
+  const properties: t.ObjectProperty[] = [
+    t.objectProperty(t.identifier('__typename'), t.stringLiteral(kind.typename)),
+    t.objectProperty(t.identifier('id'), idExpression),
+  ]
+  if (input.alias)
+    properties.push(t.objectProperty(t.identifier('alias'), t.stringLiteral(input.alias)))
+  if (input.title != null)
+    properties.push(t.objectProperty(t.identifier('title'), t.stringLiteral(input.title)))
+  if (input.description != null) {
+    properties.push(
+      t.objectProperty(t.identifier('description'), t.stringLiteral(input.description)),
+    )
+  }
+
+  if (kind.kind === 'brick' || kind.kind === 'generator') {
+    properties.push(
+      t.objectProperty(t.identifier('templateKey'), t.stringLiteral(input.templateKey || '')),
+    )
+    properties.push(t.objectProperty(t.identifier('property'), t.objectExpression([])))
+    properties.push(t.objectProperty(t.identifier('events'), t.objectExpression([])))
+    properties.push(t.objectProperty(t.identifier('outlets'), t.objectExpression([])))
+    // Codegen emits an animation facet for bricks only.
+    if (kind.kind === 'brick') {
+      properties.push(t.objectProperty(t.identifier('animation'), t.objectExpression([])))
+    }
+    properties.push(t.objectProperty(t.identifier('switches'), t.arrayExpression([])))
+  } else if (kind.kind === 'canvas') {
+    properties.push(t.objectProperty(t.identifier('property'), t.objectExpression([])))
+    properties.push(t.objectProperty(t.identifier('events'), t.objectExpression([])))
+    properties.push(t.objectProperty(t.identifier('switches'), t.arrayExpression([])))
+    properties.push(t.objectProperty(t.identifier('items'), t.arrayExpression([])))
+  } else if (kind.kind === 'data') {
+    properties.push(
+      t.objectProperty(t.identifier('type'), t.stringLiteral(input.dataType || 'any')),
+    )
+    properties.push(t.objectProperty(t.identifier('schema'), t.objectExpression([])))
+    properties.push(t.objectProperty(t.identifier('events'), t.objectExpression([])))
+    properties.push(t.objectProperty(t.identifier('value'), t.identifier('undefined')))
+  } else if (kind.kind === 'animation') {
+    properties.push(t.objectProperty(t.identifier('runType'), t.stringLiteral('once')))
+    properties.push(t.objectProperty(t.identifier('property'), t.stringLiteral('opacity')))
+    properties.push(
+      t.objectProperty(
+        t.identifier('config'),
+        await expressionFromInput(
+          {
+            __type: 'AnimationTimingConfig',
+            toValue: 1,
+            duration: 300,
+            easing: '',
+            delay: 0,
+            isInteraction: true,
+          },
+          ctx,
+        ),
+      ),
+    )
+  }
+  return t.objectExpression(properties)
+}
+
+// True when another entry of the same kind (same filename across subspaces) already
+// uses the alias — the aliased makeId form would collide at compile time.
+const aliasUsedInKind = async (projectDir: string, currentFile: string, alias: string) => {
+  const filename = path.basename(currentFile)
+  const files = (await getEntryFiles(projectDir)).filter((file) => path.basename(file) === filename)
+  for (const file of files) {
+    const parsed = await readParsedFile(projectDir, file)
+    if (getExportEntries(parsed.ast).some((entry) => entry.alias === alias)) return true
+  }
+  return false
+}
+
+const newEntry = async (projectDir: string, input: any) =>
+  runOperation(projectDir, 'new_entry', input, async () => {
+    if (!input.file) throw new EntryEditingError('missing_file', 'new_entry requires file')
+    if (!input.type)
+      throw new EntryEditingError('missing_type', 'new_entry requires TypeScript type')
+    const absPath = resolveProjectPath(projectDir, input.file)
+    const parsed = await readParsedFile(projectDir, absPath)
+    const existingNames = new Set(getExportEntries(parsed.ast).map((entry) => entry.name))
+    const explicitId = typeof input.id === 'string' ? input.id : undefined
+    const stableAlias =
+      !explicitId &&
+      typeof input.alias === 'string' &&
+      input.alias &&
+      !(await aliasUsedInKind(projectDir, absPath, input.alias))
+        ? input.alias
+        : undefined
+    const idExpression = explicitId
+      ? t.stringLiteral(explicitId)
+      : makeIdCallExpression(parsed.kind.idType, stableAlias)
+    const varName =
+      input.entry ||
+      makeUniqueVarName(existingNames, parsed.kind, explicitId, input.alias || input.title)
+    const ctx: EditContext = {
+      projectDir,
+      parsed,
+      references: [],
+      typeImports: new Set([input.type]),
+      valueImports: new Set(),
+    }
+    if (!explicitId) ctx.valueImports.add('makeId')
+    const object = await createBaseEntryObject(parsed.kind, input, idExpression, ctx)
+    const declarator = t.variableDeclarator(t.identifier(varName), object)
+    ;(declarator.id as t.Identifier).typeAnnotation = t.tsTypeAnnotation(
+      t.tsTypeReference(t.identifier(input.type)),
+    )
+    parsed.ast.program.body.push(
+      t.exportNamedDeclaration(t.variableDeclaration('const', [declarator])),
+    )
+
+    for (const [pathValue, value] of Object.entries(input.set || {})) {
+      await setPathValue(object, pathValue, value, ctx)
+    }
+    for (const event of input.events || []) {
+      if (!isRecord(event) || typeof event.event !== 'string' || !event.event || !event.action) {
+        throw new EntryEditingError('invalid_action', 'events entries require { event, action }', {
+          event,
+        })
+      }
+      const eventsObject = getOrCreateObjectProperty(object, 'events', 'events')
+      const eventArray = getOrCreateArrayProperty(
+        eventsObject,
+        event.event,
+        `events.${event.event}`,
+      )
+      eventArray.elements.push(await buildAction(event.action, ctx))
+    }
+
+    applyPendingImports(ctx)
+    await writeParsedFile(parsed)
+    const verify = await verifyProject(projectDir, input.verify)
+    return {
+      file: parsed.relPath,
+      entry: varName,
+      id: explicitId,
+      idExpression:
+        explicitId ??
+        (stableAlias
+          ? `makeId('${parsed.kind.idType}', '${stableAlias}')`
+          : `makeId('${parsed.kind.idType}')`),
+      change: {
+        set: input.set || {},
+        events: input.events || [],
+        references: referenceInputDetails(ctx.references),
+      },
+      outcome: verify.status === 'compile:failed' ? 'verify_failed' : 'ok',
+      verify,
+      summary: `created ${varName} (${parsed.kind.kind}, ${getSubspaceLabelFromPath(parsed.absPath)}) -> ${verify.status}`,
+    }
+  })
+
+const memberReferenceMatches = (
+  node: t.Node | null | undefined,
+  target: { varName: string; namespace: string },
+) => {
+  if (!node) return false
+  if (t.isIdentifier(node)) return node.name === target.varName
+  if (!t.isMemberExpression(node)) return false
+  if (!t.isIdentifier(node.object) || !t.isIdentifier(node.property)) return false
+  return node.object.name === target.namespace && node.property.name === target.varName
+}
+
+const isGetterReference = (
+  node: t.Node | null | undefined,
+  target: { varName: string; namespace: string },
+) =>
+  t.isArrowFunctionExpression(node) &&
+  node.params.length === 0 &&
+  memberReferenceMatches(node.body as t.Node, target)
+
+const isLinkReference = (
+  node: t.Node | null | undefined,
+  target: { varName: string; namespace: string },
+) =>
+  t.isCallExpression(node) &&
+  t.isIdentifier(node.callee, { name: 'linkData' }) &&
+  isGetterReference(node.arguments[0] as t.Node, target)
+
+const containsTargetReference = (
+  node: t.Node | null | undefined,
+  target: { varName: string; namespace: string },
+) => {
+  if (!node) return false
+  if (isGetterReference(node, target) || isLinkReference(node, target)) return true
+  let found = false
+  traverse(t.file(t.program([t.expressionStatement(t.cloneNode(node as any, true) as any)])), {
+    ArrowFunctionExpression(pathValue: any) {
+      if (isGetterReference(pathValue.node, target)) {
+        found = true
+        pathValue.stop()
+      }
+    },
+    CallExpression(pathValue: any) {
+      if (isLinkReference(pathValue.node, target)) {
+        found = true
+        pathValue.stop()
+      }
+    },
+  })
+  return found
+}
+
+const cleanReferencesInNode = (
+  node: t.Node,
+  target: { varName: string; namespace: string },
+  touched: Array<Record<string, unknown>>,
+  currentPath: string[] = [],
+  opts: { dataCalc?: boolean } = {},
+) => {
+  // Strict mode lists every getter/linkData reference via traversal. Cascade mode
+  // only rewrites refs in standard entry object/array containers; expression-position
+  // refs such as custom data-calc code are left for verify/compile to catch.
+  if (t.isProgram(node)) {
+    node.body.forEach((statement, index) =>
+      cleanReferencesInNode(statement, target, touched, [...currentPath, String(index)], opts),
+    )
+    return
+  }
+
+  if (t.isExportNamedDeclaration(node) && node.declaration) {
+    cleanReferencesInNode(node.declaration, target, touched, currentPath, opts)
+    return
+  }
+
+  if (t.isVariableDeclaration(node)) {
+    node.declarations.forEach((declaration, index) =>
+      cleanReferencesInNode(declaration, target, touched, [...currentPath, String(index)], opts),
+    )
+    return
+  }
+
+  if (t.isVariableDeclarator(node) && node.init) {
+    cleanReferencesInNode(node.init, target, touched, currentPath, opts)
+    return
+  }
+
+  if (t.isObjectExpression(node)) {
+    for (let index = node.properties.length - 1; index >= 0; index -= 1) {
+      const property = node.properties[index]
+      if (!t.isObjectProperty(property)) continue
+      const key = getPropertyKeyName(property.key) || `property-${index}`
+      const nextPath = [...currentPath, key]
+      if (
+        isGetterReference(property.value as t.Node, target) ||
+        isLinkReference(property.value as t.Node, target)
+      ) {
+        if (currentPath.includes('outlets')) {
+          node.properties.splice(index, 1)
+          touched.push({ action: 'drop_outlet', path: nextPath.join('.') })
+        } else if (opts.dataCalc && (key === 'output' || key === 'error')) {
+          // DataCalculationScript output/error are typed `(() => Data) | null`.
+          property.value = t.nullLiteral()
+          touched.push({ action: 'null_output', path: nextPath.join('.') })
+        } else {
+          property.value = t.identifier('undefined')
+          touched.push({ action: 'null_link', path: nextPath.join('.') })
+        }
+        continue
+      }
+      cleanReferencesInNode(property.value as t.Node, target, touched, nextPath, opts)
+    }
+    return
+  }
+
+  if (t.isArrayExpression(node)) {
+    const parentKey = currentPath[currentPath.length - 1]
+    const isEventArray = currentPath.includes('events') && parentKey !== 'events'
+    // Compile calls item.data() on every IO item, so a dangling data-calc input/output
+    // must be removed wholesale rather than left with data: undefined.
+    const removableParents = opts.dataCalc
+      ? ['items', 'params', 'dataParams', 'conds', 'switches', 'inputs', 'outputs']
+      : ['items', 'params', 'dataParams', 'conds', 'switches']
+    for (let index = node.elements.length - 1; index >= 0; index -= 1) {
+      const element = node.elements[index] as t.Node | null
+      if (!element) continue
+      const nextPath = [...currentPath, String(index)]
+      if (containsTargetReference(element, target)) {
+        if (
+          removableParents.includes(parentKey) ||
+          isEventArray ||
+          isGetterReference(element, target)
+        ) {
+          node.elements.splice(index, 1)
+          touched.push({
+            action: isEventArray
+              ? 'delete_event_handler'
+              : opts.dataCalc && (parentKey === 'inputs' || parentKey === 'outputs')
+                ? 'remove_io_item'
+                : 'remove_reference_item',
+            path: nextPath.join('.'),
+          })
+          continue
+        }
+      }
+      cleanReferencesInNode(element, target, touched, nextPath, opts)
+    }
+  }
+}
+
+const listReferenceSites = (ast: t.File, target: { varName: string; namespace: string }) => {
+  const sites: Array<Record<string, unknown>> = []
+  traverse(ast, {
+    ArrowFunctionExpression(pathValue: any) {
+      if (isGetterReference(pathValue.node, target)) {
+        sites.push({ type: 'ref', loc: pathValue.node.loc?.start })
+      }
+    },
+    CallExpression(pathValue: any) {
+      if (isLinkReference(pathValue.node, target)) {
+        sites.push({ type: 'link', loc: pathValue.node.loc?.start })
+      }
+    },
+  })
+  return sites
+}
+
+const cloneWithoutEntry = (parsed: ParsedFile, entryName: string) => {
+  const ast = t.cloneNode(parsed.ast, true)
+  const cloned = {
+    ...parsed,
+    ast,
+  }
+  removeEntryDeclaration(cloned, findEntryInParsedFile(cloned, { entry: entryName }))
+  return cloned
+}
+
+const removeEntryDeclaration = (parsed: ParsedFile, entry: ExportEntry) => {
+  const index = parsed.ast.program.body.indexOf(entry.node)
+  if (index >= 0) parsed.ast.program.body.splice(index, 1)
+}
+
+const getReferenceScanFiles = async (projectDir: string, targetFile: string, scope?: string) => {
+  if (scope === 'project') return getEntryFiles(projectDir)
+  const subspaceDir = getSubspaceDirFromPath(targetFile)
+  const files = await getEntryFilesInSubspace(subspaceDir)
+  const dataCalcDir = path.join(subspaceDir, 'data-calc')
+  const dataCalcFiles = await readdir(dataCalcDir, { withFileTypes: true }).catch(() => [])
+  return [
+    ...files,
+    ...dataCalcFiles
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.ts'))
+      .map((entry) => path.join(dataCalcDir, entry.name)),
+  ]
+}
+
+const removeEntry = async (projectDir: string, input: any) =>
+  runOperation(projectDir, 'remove_entry', input, async () => {
+    const { parsed, entry } = await resolveEditableTarget(projectDir, input)
+    const target = {
+      varName: entry.name,
+      namespace: parsed.kind.namespace,
+      id: entry.id,
+    }
+    const files = await getReferenceScanFiles(projectDir, parsed.absPath, input.scope)
+    const touchedSites: Array<Record<string, unknown>> = []
+    const parsedFiles = await Promise.all(
+      files.map(async (file) => {
+        const source = await readFile(file, 'utf8')
+        return {
+          absPath: file,
+          relPath: projectRelativePath(projectDir, file),
+          source,
+          ast: parseFileSource(source, projectRelativePath(projectDir, file)),
+          kind: entryKinds[path.basename(file) as EntryKindFile] || parsed.kind,
+        } as ParsedFile
+      }),
+    )
+
+    for (const file of parsedFiles) {
+      const scanFile = file.absPath === parsed.absPath ? cloneWithoutEntry(file, entry.name) : file
+      const sites = listReferenceSites(scanFile.ast, target)
+      sites.forEach((site) => touchedSites.push({ file: file.relPath, ...site }))
+    }
+
+    if (input.strict && touchedSites.length > 0) {
+      return {
+        file: parsed.relPath,
+        entry: entry.name,
+        id: entry.id,
+        outcome: 'refused',
+        touchedSites,
+        verify: { status: 'skipped', errors: [] },
+        summary: `refused to remove ${summarizeTarget(parsed, entry)}; ${touchedSites.length} reference(s) found`,
+      }
+    }
+
+    for (const file of parsedFiles) {
+      const touched: Array<Record<string, unknown>> = []
+      const cleanOpts = { dataCalc: file.absPath.split(path.sep).includes('data-calc') }
+      if (file.absPath === parsed.absPath) {
+        removeEntryDeclaration(file, findEntryInParsedFile(file, { entry: entry.name }))
+        touched.push({ action: 'remove_entry', path: entry.name })
+        cleanReferencesInNode(file.ast.program, target, touched, [], cleanOpts)
+      } else {
+        cleanReferencesInNode(file.ast.program, target, touched, [], cleanOpts)
+      }
+      if (touched.length === 0) continue
+      const code = await printAndFormat(file)
+      parseFileSource(code, file.relPath)
+      await writeFile(file.absPath, code)
+      touched.forEach((site) => touchedSites.push({ file: file.relPath, ...site }))
+    }
+
+    const verify = await verifyProject(projectDir, input.verify)
+    return {
+      file: parsed.relPath,
+      entry: entry.name,
+      id: entry.id,
+      outcome: verify.status === 'compile:failed' ? 'verify_failed' : 'ok',
+      touchedSites,
+      verify,
+      summary: `removed ${summarizeTarget(parsed, entry)} with ${touchedSites.length} touched site(s) -> ${verify.status}`,
+    }
+  })
+
+const responseFor = (result: any): any => ({
+  content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+  isError: result.isError || undefined,
+})
+
+const valueSchema = z
+  .any()
+  .describe(
+    'Value grammar: JSON scalars/arrays/objects emit literals; { link: "dataIdOrAlias" } emits linkData(() => data.dX) for property/data-link values; { ref: "idOrAliasOrVar", subspace?: "subspace-1"|1|"SUBSPACE_id" } emits () => namespace.varName; { expr: "raw TypeScript expression" } is spliced verbatim.',
+  )
+const pathSchema = z
+  .string()
+  .describe(
+    'Dotted entry path to edit, for example title, property.url, outlets.response, animation.show, value, type, switches[0].property.text, or items[0].frame.',
+  )
+const fileSchema = z
+  .string()
+  .describe(
+    'Project-relative entry file path, for example subspaces/subspace-0/bricks.ts, generators.ts, canvases.ts, data.ts, or animations.ts.',
+  )
+const entrySchema = z
+  .string()
+  .describe(
+    'Exported const name or entity alias to edit, for example bWelcomeText, gApiClient, cMain, or an alias like welcomeText.',
+  )
+const idSchema = z
+  .string()
+  .describe('Entry id fallback. When file is omitted, scans project subspaces for this id.')
+const verifySchema = z
+  .boolean()
+  .describe(
+    'Override compile verification for this call. Defaults to BRICKS_CTOR_MCP_EDIT_VERIFY, otherwise true.',
+  )
+const targetSchema = {
+  file: fileSchema.optional(),
+  entry: entrySchema.optional(),
+  id: idSchema.optional(),
+  verify: verifySchema.optional(),
+}
+
+export function register(server: McpServer, projectDir: string) {
+  server.tool(
+    'edit_entry',
+    'Edit map-shaped facets on an existing bricks-ctor entry by source AST. Use set/unset with dotted paths and the shared value grammar.',
+    {
+      ...targetSchema,
+      set: z
+        .record(pathSchema, valueSchema)
+        .describe(
+          'Map of dotted paths to values. Values use the shared grammar: JSON literals, { link }, { ref }, or { expr }.',
+        )
+        .optional(),
+      unset: z.array(pathSchema).describe('Dotted paths to remove.').optional(),
+      switch: z
+        .union([z.string(), z.number()])
+        .describe(
+          'Optional switch id or zero-based switch index; edits that switch object instead of the entry root.',
+        )
+        .optional(),
+    },
+    async (input: any) => responseFor(await editEntry(projectDir, input)),
+  )
+
+  server.tool(
+    'edit_events',
+    'Edit an event action array on an entry or switch. Adds/removes/replaces/moves/clears EventAction objects.',
+    {
+      ...targetSchema,
+      event: z
+        .string()
+        .describe(
+          'Camel-case source event key such as onPress, showStart, update, enter, or firstEnter.',
+        ),
+      op: z
+        .enum(['add', 'remove', 'replace', 'move', 'clear'])
+        .describe(
+          'Array operation. add inserts at index or appends; replace/remove require index; move reorders index to `to`; clear removes the event key.',
+        ),
+      index: z
+        .number()
+        .describe('Zero-based event action index. For add this is the insertion position.')
+        .optional(),
+      to: z.number().describe('Destination zero-based index for move.').optional(),
+      action: valueSchema
+        .describe(
+          'For add/replace, the flattened form: { handler: "system"|{ref}|{subspace}, name: "ACTION_NAME", params?: { inputName: value }, dataParams?: { dataRef: value }, cast?: "TypeName", waitAsync?: boolean }. The compiled source form { handler, action: { name, params: [...], dataParams: [...] }, waitAsync } and { expr: "raw EventAction" } are also accepted.',
+        )
+        .optional(),
+      switch: z
+        .union([z.string(), z.number()])
+        .describe('Optional switch id or zero-based switch index; edits that switch events object.')
+        .optional(),
+    },
+    async (input: any) => responseFor(await editEvents(projectDir, input)),
+  )
+
+  server.tool(
+    'edit_canvas_items',
+    'Edit a Canvas entry items array. Use add/remove/replace to place bricks or move to update an item frame.',
+    {
+      ...targetSchema,
+      op: z
+        .enum(['add', 'remove', 'replace', 'move'])
+        .describe(
+          'Canvas item operation. add inserts/appends, replace/remove use index, move updates frame at index.',
+        ),
+      index: z.number().describe('Zero-based canvas item index.').optional(),
+      item: valueSchema
+        .describe(
+          'For add/replace: { ref: "brickIdOrAliasOrVar", subspace?: ..., frame: { x, y, width, height, ... }, hidden?: boolean }. Frames require numeric x/y/width/height.',
+        )
+        .optional(),
+      frame: valueSchema
+        .describe(
+          'Replacement frame such as { x, y, width, height }. Required for move; for add/replace it is used when item.frame is omitted.',
+        )
+        .optional(),
+    },
+    async (input: any) => responseFor(await editCanvasItems(projectDir, input)),
+  )
+
+  server.tool(
+    'edit_switches',
+    'Edit an entry switches array. Use edit_entry/edit_events with switch when changing switch facet bodies.',
+    {
+      ...targetSchema,
+      op: z
+        .enum(['add', 'remove', 'replace', 'move'])
+        .describe(
+          'Switch array operation. add inserts/appends, replace/remove use index, move reorders to `to`.',
+        ),
+      index: z
+        .union([z.string(), z.number()])
+        .describe(
+          'Switch id or zero-based switch index. For add, this is optional insertion position.',
+        )
+        .optional(),
+      to: z.number().describe('Destination zero-based index for move.').optional(),
+      switch: valueSchema
+        .describe(
+          'For add/replace: { id? (BRICK_STATE_GROUP_<uuid>; omit to auto-generate), title?, description?, conds?: [{ method: "=="|"!="|">"|"<"|">="|"<=", cond }], override?: { animation?, event?, property?, outlet? }, property?, outlets?, animation?, disabled?, break? }. Cond forms: { type: "inner_state", key: "current_canvas", value: canvasRef }, { type: "inner_state", outlet: "outletName", value }, { type: "property_bank", ref: dataRef, value }, { type: "property_bank_by_item_key", ref: dataRef, value }, a compiled { __typename: "SwitchCond..." } object, or { expr }. Set switch events with edit_events using its switch parameter.',
+        )
+        .optional(),
+    },
+    async (input: any) => responseFor(await editSwitches(projectDir, input)),
+  )
+
+  server.tool(
+    'new_entry',
+    'Create a minimal standard-style exported entry skeleton in an entry file, then optionally apply set/events edits.',
+    {
+      file: fileSchema,
+      entry: entrySchema
+        .describe('Optional exported const name. Defaults from alias/title/id.')
+        .optional(),
+      templateKey: z
+        .string()
+        .describe('Brick/generator templateKey such as BRICK_TEXT or GENERATOR_HTTP.')
+        .optional(),
+      type: z
+        .string()
+        .describe(
+          'TypeScript type imported from bricks-ctor, for example BrickText, GeneratorHTTP, Canvas, Data, or Animation.',
+        ),
+      alias: z
+        .string()
+        .describe('Optional entry alias. Also influences default exported const name.')
+        .optional(),
+      title: z.string().describe('Optional entry title.').optional(),
+      description: z.string().describe('Optional entry description.').optional(),
+      id: idSchema
+        .describe(
+          'Optional explicit id. If omitted, the tool generates one with the file-kind prefix.',
+        )
+        .optional(),
+      dataType: z
+        .string()
+        .describe('For data.ts only: initial Data.type value. Defaults to any.')
+        .optional(),
+      set: z
+        .record(pathSchema, valueSchema)
+        .describe(
+          'Optional initial dotted-path values applied after creating the skeleton. Values use JSON literals, { link }, { ref }, or { expr }.',
+        )
+        .optional(),
+      events: z
+        .array(valueSchema)
+        .describe('Optional initial event actions as objects with { event, action }.')
+        .optional(),
+      verify: verifySchema.optional(),
+    },
+    async (input: any) => responseFor(await newEntry(projectDir, input)),
+  )
+
+  server.tool(
+    'remove_entry',
+    'Remove an entry. By default cascades same-subspace references in standard entry object/array shapes; strict mode refuses when references exist.',
+    {
+      ...targetSchema,
+      strict: z
+        .boolean()
+        .describe(
+          'When true, do not edit files; refuse and return reference sites if the entry is referenced.',
+        )
+        .optional(),
+      scope: z
+        .enum(['subspace', 'project'])
+        .describe('Reference scan scope. subspace is default; project scans all subspaces.')
+        .optional(),
+    },
+    async (input: any) => responseFor(await removeEntry(projectDir, input)),
+  )
+}
+
+export const __test__ = {
+  editEntry,
+  editEvents,
+  editCanvasItems,
+  editSwitches,
+  newEntry,
+  removeEntry,
+  resolveReference,
+}