@fugood/bricks-project 2.25.0-beta.42 → 2.25.0-beta.45

package/tools/mcp-tools/data-calc-editing.ts

@@ -0,0 +1,1395 @@
+import generateModule from '@babel/generator'
+import { parse, parseExpression } from '@babel/parser'
+import * as t from '@babel/types'
+import { parse as parseSandboxModule } from 'acorn'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { format as formatWithOxfmt } from 'oxfmt'
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { z } from 'zod'
+
+import { verifyProject } from './_verify'
+import { appendEditRecord, editProvenance } from '../_edits-log'
+
+const generate = (generateModule as any).default || generateModule
+
+const oxfmtOptions = {
+  trailingComma: 'all',
+  tabWidth: 2,
+  semi: false,
+  singleQuote: true,
+  printWidth: 100,
+} as const
+
+type ParsedFile = {
+  ast: t.File
+  source: string
+  absPath: string
+  relPath: string
+}
+
+type ExportEntry = {
+  name: string
+  object?: t.ObjectExpression
+  id?: string
+  alias?: string
+  typeName?: string
+}
+
+type ReferenceResolution = {
+  input: string
+  id?: string
+  alias?: string
+  varName: string
+  sameFile: boolean
+  importSource?: string
+}
+
+type EditContext = {
+  projectDir: string
+  parsed: ParsedFile
+  references: ReferenceResolution[]
+  typeImports: Set<string>
+  valueImports: Set<string>
+}
+
+type CalcTarget = {
+  parsed: ParsedFile
+  object: t.ObjectExpression
+  slug: string
+  sandboxFile: string
+}
+
+class DataCalcEditingError 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 = 'DataCalcEditingError'
+    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 DataCalcEditingError('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 DataCalcEditingError('invalid_file', 'File must stay inside the project directory', {
+      file,
+    })
+  }
+  return absPath
+}
+
+const parseFileSource = (source: string, relPath: string) => {
+  try {
+    return parse(source, {
+      sourceType: 'module',
+      plugins: ['typescript', 'topLevelAwait'],
+      errorRecovery: false,
+    })
+  } catch (err: any) {
+    throw new DataCalcEditingError(
+      '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,
+  }
+}
+
+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 []
+    return statement.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,
+          object,
+          id: object ? getStringProperty(object, 'id') : undefined,
+          alias: object ? getStringProperty(object, 'alias') : undefined,
+          typeName,
+        },
+      ]
+    })
+  })
+
+const getCalcDirFromSubspaceDir = (subspaceDir: string) => path.join(subspaceDir, 'data-calc')
+
+const getSubspaceDirFromCalcFile = (absPath: string) => {
+  const parts = absPath.split(path.sep)
+  const index = parts.findIndex((part) => /^subspace-\d+$/.test(part))
+  if (index < 0) {
+    throw new DataCalcEditingError(
+      'invalid_file',
+      'Data-calc file must be inside subspaces/subspace-N/data-calc',
+      { file: absPath },
+    )
+  }
+  return parts.slice(0, index + 1).join(path.sep)
+}
+
+const resolveSubspaceDir = (projectDir: string, subspace?: string | number) => {
+  if (subspace == null || subspace === '') return path.join(projectDir, 'subspaces/subspace-0')
+  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)
+
+  throw new DataCalcEditingError(
+    'unsupported_subspace',
+    `Unsupported subspace locator: ${normalized}`,
+    {
+      subspace: normalized,
+    },
+  )
+}
+
+const calcSlugFromFile = (absPath: string) => {
+  const basename = path.basename(absPath)
+  const match = /^data-calculation-(.+)\.ts$/.exec(basename)
+  if (!match) {
+    throw new DataCalcEditingError('invalid_file', 'Expected data-calculation-{slug}.ts file', {
+      file: absPath,
+    })
+  }
+  return match[1]
+}
+
+const getDataCalcFiles = async (dataCalcDir: string) => {
+  const entries = await readdir(dataCalcDir, { withFileTypes: true }).catch(() => [])
+  return entries
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        /^data-calculation-.+\.ts$/.test(entry.name) &&
+        !entry.name.endsWith('.sandbox.ts'),
+    )
+    .map((entry) => path.join(dataCalcDir, entry.name))
+    .sort()
+}
+
+const extractCalcObject = (parsed: ParsedFile) => {
+  const entries = getExportEntries(parsed.ast)
+  const calcEntry = entries.find((entry) => entry.name === 'dataCalculation')
+  if (!calcEntry || !calcEntry.object) {
+    throw new DataCalcEditingError(
+      'fallback_recommended',
+      `Data calc ${parsed.relPath} is not a single exported object literal. Edit this file directly for this one.`,
+      { file: parsed.relPath, check: 'export const dataCalculation object literal' },
+    )
+  }
+
+  const typename = getStringProperty(calcEntry.object, '__typename')
+  if (typename !== 'DataCalculationScript') {
+    throw new DataCalcEditingError(
+      'fallback_recommended',
+      `Data calc ${parsed.relPath} is ${typename || 'not DataCalculationScript'}. DataCalculationMap is out of scope; edit this file directly.`,
+      { file: parsed.relPath, typename },
+    )
+  }
+
+  return calcEntry.object
+}
+
+const getCodeExpression = (object: t.ObjectExpression): t.Expression | null => {
+  const value = getObjectProperty(object, 'code')?.value
+  return value && t.isExpression(value) ? value : null
+}
+
+// Sibling sandbox files only: a plain `./name.sandbox.js` basename. Anything else
+// (nested paths, ../ traversal, non-sandbox files) is not ours to rewrite or delete.
+const isSandboxFilename = (value: string) => /^(\.\/)?[^/\\]+\.sandbox\.js$/.test(value)
+
+const readCodeUrlFilename = (code: t.Expression | null | undefined) => {
+  const expression = t.isAwaitExpression(code) ? code.argument : code
+  if (!t.isCallExpression(expression)) return null
+  const firstArg = expression.arguments[0]
+  if (!t.isNewExpression(firstArg)) return null
+  if (!t.isIdentifier(firstArg.callee) || firstArg.callee.name !== 'URL') return null
+  const filenameArg = firstArg.arguments[0]
+  if (!t.isStringLiteral(filenameArg)) return null
+  return filenameArg.value
+}
+
+const sandboxFilenameFromCodeExpression = (
+  code: t.Expression | null | undefined,
+  fallbackSlug: string,
+) => {
+  const filename = readCodeUrlFilename(code)
+  if (!filename || !isSandboxFilename(filename)) {
+    return `data-calculation-${fallbackSlug}.sandbox.js`
+  }
+  return filename.replace(/^\.\//, '')
+}
+
+const isRecognizedCodeExpression = (code: t.Expression | null | undefined) => {
+  if (!code) return false
+  if (t.isStringLiteral(code) || t.isTemplateLiteral(code)) return true
+  const filename = readCodeUrlFilename(code)
+  return filename != null && isSandboxFilename(filename)
+}
+
+const resolveCalcTarget = async (projectDir: string, input: any): Promise<CalcTarget> => {
+  let absPath: string | undefined
+
+  if (input.file) {
+    absPath = resolveProjectPath(projectDir, input.file)
+  } else {
+    const subspaceDir = resolveSubspaceDir(projectDir, input.subspace)
+    const calcDir = getCalcDirFromSubspaceDir(subspaceDir)
+    const files = await getDataCalcFiles(calcDir)
+    const calc = input.calc
+    if (!calc) {
+      throw new DataCalcEditingError('missing_calc', 'Provide file or subspace+calc')
+    }
+
+    for (const file of files) {
+      if (calc === calcSlugFromFile(file)) {
+        absPath = file
+        break
+      }
+      // Tolerate unparseable / non-Script siblings while scanning: they only opt out
+      // of alias/id matching here; standard-style checks run on the resolved target.
+      try {
+        const parsed = await readParsedFile(projectDir, file)
+        const entry = getExportEntries(parsed.ast).find((item) => item.name === 'dataCalculation')
+        if (entry && (calc === entry.alias || calc === entry.id)) {
+          absPath = file
+          break
+        }
+      } catch {
+        continue
+      }
+    }
+  }
+
+  if (!absPath) {
+    throw new DataCalcEditingError('calc_not_found', `Data calc not found: ${input.calc}`, {
+      calc: input.calc,
+      subspace: input.subspace ?? 'subspace-0',
+    })
+  }
+
+  const parsed = await readParsedFile(projectDir, absPath)
+  const object = extractCalcObject(parsed)
+  const slug = calcSlugFromFile(absPath)
+  const sandboxFile = sandboxFilenameFromCodeExpression(getCodeExpression(object), slug)
+  return { parsed, object, slug, sandboxFile }
+}
+
+const relativeImportSource = (fromFile: string, toFile: string) => {
+  let rel = path.relative(path.dirname(fromFile), toFile).replace(/\\/g, '/')
+  if (!rel.startsWith('.')) rel = `./${rel}`
+  return rel.replace(/\.(ts|tsx|js|jsx)$/, '')
+}
+
+const insertImport = (ast: t.File, declaration: t.ImportDeclaration) => {
+  const body = ast.program.body
+  const lastImportIndex = body.findLastIndex((statement) => t.isImportDeclaration(statement))
+  body.splice(lastImportIndex + 1, 0, declaration)
+}
+
+const ensureNamespaceImport = (parsed: ParsedFile, source: string, preferredLocal: string) => {
+  for (const statement of parsed.ast.program.body) {
+    if (!t.isImportDeclaration(statement) || statement.source.value !== source) continue
+    const namespace = statement.specifiers.find(
+      (specifier): specifier is t.ImportNamespaceSpecifier =>
+        t.isImportNamespaceSpecifier(specifier),
+    )
+    if (namespace) return namespace.local.name
+  }
+
+  const declaration = t.importDeclaration(
+    [t.importNamespaceSpecifier(t.identifier(preferredLocal))],
+    t.stringLiteral(source),
+  )
+  insertImport(parsed.ast, declaration)
+  return preferredLocal
+}
+
+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 ensureReadFileImport = (ast: t.File) => {
+  for (const statement of ast.program.body) {
+    if (!t.isImportDeclaration(statement) || statement.source.value !== 'node:fs/promises') {
+      continue
+    }
+    const hasReadFile = statement.specifiers.some(
+      (specifier) =>
+        t.isImportSpecifier(specifier) &&
+        t.isIdentifier(specifier.imported) &&
+        specifier.imported.name === 'readFile',
+    )
+    if (!hasReadFile) {
+      statement.specifiers.push(
+        t.importSpecifier(t.identifier('readFile'), t.identifier('readFile')),
+      )
+    }
+    return
+  }
+
+  insertImport(
+    ast,
+    t.importDeclaration(
+      [t.importSpecifier(t.identifier('readFile'), t.identifier('readFile'))],
+      t.stringLiteral('node:fs/promises'),
+    ),
+  )
+}
+
+const applyPendingImports = (ctx: EditContext) => {
+  ensureBricksCtorImport(ctx.parsed.ast, 'type', ctx.typeImports)
+  ensureBricksCtorImport(ctx.parsed.ast, 'value', ctx.valueImports)
+}
+
+const resolveDataReference = async (
+  projectDir: string,
+  currentFile: string,
+  ref: string,
+  subspace?: string | number,
+): Promise<ReferenceResolution> => {
+  const currentSubspaceDir = getSubspaceDirFromCalcFile(currentFile)
+  const targetSubspaceDir =
+    subspace == null ? currentSubspaceDir : resolveSubspaceDir(projectDir, subspace)
+  const dataFile = path.join(targetSubspaceDir, 'data.ts')
+  const parsed = await readParsedFile(projectDir, dataFile)
+  const matches = getExportEntries(parsed.ast).filter(
+    (entry) => entry.name === ref || entry.id === ref || entry.alias === ref,
+  )
+
+  if (matches.length === 0) {
+    throw new DataCalcEditingError('reference_not_found', `Data reference not found: ${ref}`, {
+      ref,
+      subspace: path.basename(targetSubspaceDir),
+    })
+  }
+  if (matches.length > 1) {
+    throw new DataCalcEditingError('ambiguous_reference', `Data reference is ambiguous: ${ref}`, {
+      ref,
+      matches: matches.map((match) => ({
+        file: projectRelativePath(projectDir, dataFile),
+        entry: match.name,
+        id: match.id,
+        alias: match.alias,
+      })),
+    })
+  }
+
+  const sameFile = path.resolve(dataFile) === path.resolve(currentFile)
+  return {
+    input: ref,
+    id: matches[0].id,
+    alias: matches[0].alias,
+    varName: matches[0].name,
+    sameFile,
+    importSource: sameFile ? undefined : relativeImportSource(currentFile, dataFile),
+  }
+}
+
+const dataGetterExpression = async (input: any, ctx: EditContext): Promise<t.Expression> => {
+  if (isRecord(input) && typeof input.expr === 'string') {
+    return parseExpression(input.expr, { plugins: ['typescript'] }) as t.Expression
+  }
+
+  const ref = typeof input === 'string' ? input : isRecord(input) ? input.ref : undefined
+  if (typeof ref !== 'string' || !ref) {
+    throw new DataCalcEditingError('invalid_ref', 'Data getter requires a data ref string')
+  }
+
+  const resolved = await resolveDataReference(
+    ctx.projectDir,
+    ctx.parsed.absPath,
+    ref,
+    isRecord(input) ? (input.subspace as any) : undefined,
+  )
+  const local = resolved.sameFile
+    ? 'data'
+    : ensureNamespaceImport(ctx.parsed, resolved.importSource || '../data', 'data')
+  ctx.references.push(resolved)
+  return t.arrowFunctionExpression(
+    [],
+    t.memberExpression(t.identifier(local), t.identifier(resolved.varName)),
+  )
+}
+
+const nullableDataGetterExpression = async (value: any, ctx: EditContext) => {
+  if (value == null) return t.nullLiteral()
+  return dataGetterExpression(value, ctx)
+}
+
+// Alias-keyed makeId calls hash to the same uuid regardless of declaration order, so
+// recompiles stay stable when sibling entries are added or removed.
+const makeIdCallExpression = (idType: string, alias?: string) =>
+  t.callExpression(
+    t.identifier('makeId'),
+    alias ? [t.stringLiteral(idType), t.stringLiteral(alias)] : [t.stringLiteral(idType)],
+  )
+
+// True when another calc anywhere in the project already uses the alias — the aliased
+// makeId form would collide at compile time.
+const aliasUsedInCalcs = async (projectDir: string, alias: string) => {
+  const subspacesDir = path.join(projectDir, 'subspaces')
+  const entries = await readdir(subspacesDir, { withFileTypes: true }).catch(() => [])
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !/^subspace-\d+$/.test(entry.name)) continue
+    const files = await getDataCalcFiles(path.join(subspacesDir, entry.name, 'data-calc'))
+    for (const file of files) {
+      try {
+        const parsed = await readParsedFile(projectDir, file)
+        const calcEntry = getExportEntries(parsed.ast).find(
+          (item) => item.name === 'dataCalculation',
+        )
+        if (calcEntry?.alias === alias) return true
+      } catch {
+        continue
+      }
+    }
+  }
+  return false
+}
+
+// Required by the DataCalculationScript type; unsetting them yields a calc that
+// crashes compile with an unrelated-looking error instead of a clear refusal here.
+const requiredCalcFields = new Set([
+  '__typename',
+  'id',
+  'code',
+  'enableAsync',
+  'inputs',
+  'output',
+  'outputs',
+  'error',
+])
+
+const makeCodeReadFileExpression = (sandboxFile: string) =>
+  t.awaitExpression(
+    t.callExpression(t.identifier('readFile'), [
+      t.newExpression(t.identifier('URL'), [
+        t.stringLiteral(`./${sandboxFile}`),
+        t.memberExpression(
+          t.metaProperty(t.identifier('import'), t.identifier('meta')),
+          t.identifier('url'),
+        ),
+      ]),
+      t.stringLiteral('utf8'),
+    ]),
+  )
+
+const expressionFromInput = async (input: any, ctx: EditContext): Promise<t.Expression> => {
+  if (isRecord(input)) {
+    if (typeof input.expr === 'string') {
+      return parseExpression(input.expr, { plugins: ['typescript'] }) as t.Expression
+    }
+    if (typeof input.ref === 'string') return dataGetterExpression(input, ctx)
+  }
+  if (input === null) return t.nullLiteral()
+  if (input === undefined) return t.identifier('undefined')
+  if (typeof input === 'string') return t.stringLiteral(input)
+  if (typeof input === 'number') return t.numericLiteral(input)
+  if (typeof input === 'boolean') return t.booleanLiteral(input)
+  if (Array.isArray(input)) {
+    return t.arrayExpression(
+      await Promise.all(input.map((value) => expressionFromInput(value, ctx))),
+    )
+  }
+  if (isRecord(input)) {
+    const properties = await Promise.all(
+      Object.entries(input).map(async ([key, value]) =>
+        t.objectProperty(makeObjectKey(key), await expressionFromInput(value, ctx)),
+      ),
+    )
+    return t.objectExpression(properties)
+  }
+  throw new DataCalcEditingError('invalid_value', `Unsupported value: ${String(input)}`)
+}
+
+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 DataCalcEditingError('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 responseFor = (result: any): any => ({
+  content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
+  isError: result.isError || undefined,
+})
+
+const referenceInputDetails = (references: ReferenceResolution[]) =>
+  references.map((reference) => ({
+    input: reference.input,
+    id: reference.id,
+    alias: reference.alias,
+    entry: reference.varName,
+  }))
+
+const runOperation = async (
+  projectDir: string,
+  tool: string,
+  input: any,
+  operation: () => Promise<any>,
+) => {
+  const startedAt = new Date().toISOString()
+  const provenance = editProvenance()
+  try {
+    const result = await operation()
+    await appendEditRecord(projectDir, {
+      ts: startedAt,
+      tool,
+      input,
+      provenance,
+      outcome: result.outcome,
+      summary: result.summary,
+      result,
+    })
+    return result
+  } catch (err: any) {
+    const isMcpError = err instanceof DataCalcEditingError
+    const outcome =
+      isMcpError && err.code === 'fallback_recommended' ? 'fallback_recommended' : 'error'
+    const result = {
+      outcome,
+      // Fallback recommendations are guidance, not MCP errors (mirrors entry-editing).
+      isError: outcome === 'error',
+      error: {
+        code: isMcpError ? err.code : 'unexpected_error',
+        message: err.message,
+        details: isMcpError ? err.details : undefined,
+      },
+      summary: `${tool} failed: ${err.message}`,
+    }
+    await appendEditRecord(projectDir, {
+      ts: startedAt,
+      tool,
+      input,
+      provenance,
+      outcome: result.outcome,
+      summary: result.summary,
+      error: result.error,
+    }).catch(() => undefined)
+    return result
+  }
+}
+
+const slugify = (value: string) => {
+  const slug = value
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return slug || 'calc'
+}
+
+const nextFreeSlug = async (dataCalcDir: string, preferred?: string) => {
+  const existing = new Set((await getDataCalcFiles(dataCalcDir)).map(calcSlugFromFile))
+  if (preferred) {
+    let slug = slugify(preferred)
+    if (!existing.has(slug)) return slug
+    let index = 1
+    while (existing.has(`${slug}-${index}`)) index += 1
+    return `${slug}-${index}`
+  }
+
+  let index = 0
+  while (existing.has(String(index))) index += 1
+  return String(index)
+}
+
+// Compile unwraps the sandbox with the same acorn parse (compile/index.ts
+// compileScriptCalculationCode, ecmaVersion 2020) and silently falls back to the raw
+// wrapped string when it fails, so an unparseable sandbox must be rejected here.
+const sandboxParses = (source: string) => {
+  try {
+    parseSandboxModule(source, { sourceType: 'module', ecmaVersion: 2020 })
+    return true
+  } catch {
+    return false
+  }
+}
+
+const wrapSandboxCode = (code?: string) => {
+  const body = code ?? ''
+  if (/export\s+(async\s+)?function\s+main\s*\(/.test(body)) {
+    const wrapped = body.endsWith('\n') ? body : `${body}\n`
+    if (!sandboxParses(wrapped)) {
+      throw new DataCalcEditingError(
+        'invalid_code',
+        'Sandbox code does not parse as a module (note: top-level await requires export async function main)',
+      )
+    }
+    return wrapped
+  }
+  const trimmed = body.trim()
+  if (!trimmed) return 'export function main() {\n}\n'
+  // Bodies using top-level await (enableAsync mode) only parse inside an async main;
+  // compile unwraps either wrapper form to the same script body.
+  for (const asyncPrefix of ['', 'async ']) {
+    const wrapped = `export ${asyncPrefix}function main() {\n${trimmed}\n}\n`
+    if (sandboxParses(wrapped)) return wrapped
+  }
+  throw new DataCalcEditingError(
+    'invalid_code',
+    'Sandbox code does not parse as a script body (statements with top-level return)',
+  )
+}
+
+const regenerateDataCalcIndex = async (projectDir: string, dataCalcDir: string) => {
+  await mkdir(dataCalcDir, { recursive: true })
+  const files = await getDataCalcFiles(dataCalcDir)
+  const imports = files
+    .map((file, index) => {
+      const slug = calcSlugFromFile(file)
+      return `import { dataCalculation as dataCalculation${index} } from './data-calculation-${slug}'`
+    })
+    .join('\n')
+  const list = files.map((_, index) => `dataCalculation${index}`).join(',\n  ')
+  const source = `${imports}
+
+export const dataCalculation = [
+  ${list}
+]
+`
+  const indexPath = path.join(dataCalcDir, 'index.ts')
+  const parsed: ParsedFile = {
+    absPath: indexPath,
+    relPath: projectRelativePath(projectDir, indexPath),
+    source,
+    ast: parseFileSource(source, projectRelativePath(projectDir, indexPath)),
+  }
+  await writeParsedFile(parsed)
+  return projectRelativePath(projectDir, indexPath)
+}
+
+const getDefaultExportObject = (ast: t.File) => {
+  for (const statement of ast.program.body) {
+    if (!t.isExportDefaultDeclaration(statement)) continue
+    const declaration = statement.declaration
+    if (t.isObjectExpression(declaration)) return declaration
+    if (t.isTSAsExpression(declaration) && t.isObjectExpression(declaration.expression)) {
+      return declaration.expression
+    }
+  }
+  return null
+}
+
+const ensureSubspaceRootDataCalcImport = async (
+  projectDir: string,
+  subspaceDir: string,
+): Promise<{ touched?: string; warning?: string } | null> => {
+  const indexPath = path.join(subspaceDir, 'index.ts')
+  const relPath = projectRelativePath(projectDir, indexPath)
+  const source = await readFile(indexPath, 'utf8').catch((err: any) => {
+    if (err?.code === 'ENOENT') return null
+    throw err
+  })
+  if (source == null) {
+    return { warning: `${relPath} not found; wire the data-calc import manually` }
+  }
+
+  const parsed = await readParsedFile(projectDir, indexPath)
+  const object = getDefaultExportObject(parsed.ast)
+  if (!object) {
+    return {
+      warning: `${relPath} has no default-export object; wire the data-calc import manually`,
+    }
+  }
+
+  const property = getObjectProperty(object, 'dataCalculation')
+  if (property && t.isIdentifier(property.value)) return null
+  if (property && !(t.isArrayExpression(property.value) && property.value.elements.length === 0)) {
+    // Only the codegen minimal-subspace shape (dataCalculation: []) is safe to rewire;
+    // replacing any other value (inline calcs, spreads) would silently drop config.
+    return {
+      warning: `${relPath} has a non-empty dataCalculation value; wire the data-calc import manually`,
+    }
+  }
+
+  const alreadyImported = parsed.ast.program.body.some(
+    (statement) =>
+      t.isImportDeclaration(statement) &&
+      (statement.source.value === './data-calc' || statement.source.value === './data-calc/index'),
+  )
+  if (!alreadyImported) {
+    insertImport(
+      parsed.ast,
+      t.importDeclaration(
+        [t.importSpecifier(t.identifier('dataCalculation'), t.identifier('dataCalculation'))],
+        t.stringLiteral('./data-calc'),
+      ),
+    )
+  }
+
+  if (!property) {
+    const dataCalculationProperty = t.objectProperty(
+      t.identifier('dataCalculation'),
+      t.identifier('dataCalculation'),
+    )
+    dataCalculationProperty.shorthand = true
+    object.properties.push(dataCalculationProperty)
+  } else {
+    property.value = t.identifier('dataCalculation')
+    if (t.isIdentifier(property.key)) property.shorthand = true
+  }
+
+  await writeParsedFile(parsed)
+  return { touched: parsed.relPath }
+}
+
+const buildIoObject = async (field: 'inputs' | 'outputs', input: any, ctx: EditContext) => {
+  if (!input.key) {
+    throw new DataCalcEditingError('missing_key', `${field} item requires key`)
+  }
+  if (input.data == null) {
+    throw new DataCalcEditingError('missing_data', `${field} item requires data`)
+  }
+  const properties: t.ObjectProperty[] = [
+    t.objectProperty(t.identifier('key'), t.stringLiteral(input.key)),
+    t.objectProperty(t.identifier('data'), await dataGetterExpression(input.data, ctx)),
+  ]
+  if (field === 'inputs') {
+    properties.push(
+      t.objectProperty(t.identifier('trigger'), t.booleanLiteral(input.trigger !== false)),
+    )
+  }
+  return t.objectExpression(properties)
+}
+
+const buildIoArrayExpression = async (
+  field: 'inputs' | 'outputs',
+  items: any[],
+  ctx: EditContext,
+) => {
+  if (field === 'inputs') {
+    const keys = new Set<string>()
+    for (const item of items) {
+      if (keys.has(item?.key)) {
+        throw new DataCalcEditingError('duplicate_key', `Input key already exists: ${item.key}`, {
+          key: item.key,
+        })
+      }
+      keys.add(item?.key)
+    }
+  }
+  return t.arrayExpression(await Promise.all(items.map((item) => buildIoObject(field, item, ctx))))
+}
+
+const getOrCreateArrayProperty = (object: t.ObjectExpression, key: string) => {
+  const existing = getObjectProperty(object, key)
+  if (existing) {
+    if (!t.isArrayExpression(existing.value)) {
+      throw new DataCalcEditingError(
+        'fallback_recommended',
+        `${key} is not an array. Edit this file directly.`,
+      )
+    }
+    return existing.value
+  }
+  const array = t.arrayExpression([])
+  object.properties.push(t.objectProperty(t.identifier(key), array))
+  return array
+}
+
+const findIoIndex = (array: t.ArrayExpression, target: { key?: string; index?: number }) => {
+  if (typeof target.index === 'number') return target.index
+  if (!target.key) return -1
+  const matches = array.elements
+    .map((element, index) => ({ element, index }))
+    .filter(
+      ({ element }) =>
+        t.isObjectExpression(element) && getStringProperty(element, 'key') === target.key,
+    )
+  if (matches.length > 1) {
+    throw new DataCalcEditingError('ambiguous_key', `IO key is ambiguous: ${target.key}`, {
+      key: target.key,
+      count: matches.length,
+    })
+  }
+  return matches[0]?.index ?? -1
+}
+
+const assertInputKeyUnique = (array: t.ArrayExpression, key: string, ignoreIndex?: number) => {
+  const duplicate = array.elements.some(
+    (element, index) =>
+      index !== ignoreIndex &&
+      t.isObjectExpression(element) &&
+      getStringProperty(element, 'key') === key,
+  )
+  if (duplicate) {
+    throw new DataCalcEditingError('duplicate_key', `Input key already exists: ${key}`, { key })
+  }
+}
+
+const buildCalcObject = async (
+  input: any,
+  sandboxFile: string,
+  ctx: EditContext,
+  stableIdAlias?: string,
+) => {
+  ctx.typeImports.add('DataCalculationScript')
+  ctx.valueImports.add('makeId')
+  ensureReadFileImport(ctx.parsed.ast)
+
+  const properties: t.ObjectProperty[] = [
+    t.objectProperty(t.identifier('__typename'), t.stringLiteral('DataCalculationScript')),
+    t.objectProperty(
+      t.identifier('id'),
+      input.id
+        ? t.stringLiteral(input.id)
+        : makeIdCallExpression('property_bank_calc', stableIdAlias),
+    ),
+  ]
+  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 (input.note != null)
+    properties.push(t.objectProperty(t.identifier('note'), t.stringLiteral(input.note)))
+
+  properties.push(t.objectProperty(t.identifier('code'), makeCodeReadFileExpression(sandboxFile)))
+  properties.push(
+    t.objectProperty(t.identifier('enableAsync'), t.booleanLiteral(!!input.enableAsync)),
+  )
+  if (input.triggerMode != null) {
+    properties.push(
+      t.objectProperty(t.identifier('triggerMode'), t.stringLiteral(input.triggerMode)),
+    )
+  }
+
+  properties.push(
+    t.objectProperty(
+      t.identifier('inputs'),
+      await buildIoArrayExpression('inputs', input.inputs || [], ctx),
+    ),
+  )
+  properties.push(
+    t.objectProperty(t.identifier('output'), await nullableDataGetterExpression(input.output, ctx)),
+  )
+  properties.push(
+    t.objectProperty(
+      t.identifier('outputs'),
+      await buildIoArrayExpression('outputs', input.outputs || [], ctx),
+    ),
+  )
+  properties.push(
+    t.objectProperty(t.identifier('error'), await nullableDataGetterExpression(input.error, ctx)),
+  )
+
+  return t.objectExpression(properties)
+}
+
+const createCalcParsedFile = (projectDir: string, absPath: string): ParsedFile => {
+  const relPath = projectRelativePath(projectDir, absPath)
+  const source = 'export const dataCalculation = {}\n'
+  const ast = parseFileSource(source, relPath)
+  ast.program.body = []
+  return { ast, source, absPath, relPath }
+}
+
+const newDataCalc = async (projectDir: string, input: any) =>
+  runOperation(projectDir, 'new_data_calc', input, async () => {
+    const subspaceDir = resolveSubspaceDir(projectDir, input.subspace)
+    const dataCalcDir = getCalcDirFromSubspaceDir(subspaceDir)
+    await mkdir(dataCalcDir, { recursive: true })
+    const slug = await nextFreeSlug(dataCalcDir, input.alias)
+    const sandboxFile = `data-calculation-${slug}.sandbox.js`
+    const calcPath = path.join(dataCalcDir, `data-calculation-${slug}.ts`)
+    const sandboxPath = path.join(dataCalcDir, sandboxFile)
+    const parsed = createCalcParsedFile(projectDir, calcPath)
+    const ctx: EditContext = {
+      projectDir,
+      parsed,
+      references: [],
+      typeImports: new Set(),
+      valueImports: new Set(),
+    }
+    const stableIdAlias =
+      !input.id &&
+      typeof input.alias === 'string' &&
+      input.alias &&
+      !(await aliasUsedInCalcs(projectDir, input.alias))
+        ? input.alias
+        : undefined
+    const object = await buildCalcObject(input, sandboxFile, ctx, stableIdAlias)
+    const declarator = t.variableDeclarator(t.identifier('dataCalculation'), object)
+    ;(declarator.id as t.Identifier).typeAnnotation = t.tsTypeAnnotation(
+      t.tsTypeReference(t.identifier('DataCalculationScript')),
+    )
+    parsed.ast.program.body.push(
+      t.exportNamedDeclaration(t.variableDeclaration('const', [declarator])),
+    )
+    applyPendingImports(ctx)
+
+    await writeFile(sandboxPath, wrapSandboxCode(input.code))
+    await writeParsedFile(parsed)
+    const touchedSites = [
+      { file: projectRelativePath(projectDir, calcPath), action: 'create_calc' },
+      { file: projectRelativePath(projectDir, sandboxPath), action: 'write_sandbox' },
+    ]
+    touchedSites.push({
+      file: await regenerateDataCalcIndex(projectDir, dataCalcDir),
+      action: 'regenerate_index',
+    })
+    const rootWiring = await ensureSubspaceRootDataCalcImport(projectDir, subspaceDir)
+    if (rootWiring?.touched) {
+      touchedSites.push({ file: rootWiring.touched, action: 'wire_subspace_index' })
+    }
+
+    const verify = await verifyProject(projectDir, input.verify)
+    return {
+      file: projectRelativePath(projectDir, calcPath),
+      subspace: path.basename(subspaceDir),
+      calc: slug,
+      idExpression:
+        input.id ??
+        (stableIdAlias
+          ? `makeId('property_bank_calc', '${stableIdAlias}')`
+          : "makeId('property_bank_calc')"),
+      outcome: verify.status === 'compile:failed' ? 'verify_failed' : 'ok',
+      touchedSites,
+      ...(rootWiring?.warning ? { warnings: [rootWiring.warning] } : {}),
+      verify,
+      references: referenceInputDetails(ctx.references),
+      summary: `created data calc ${slug} in ${path.basename(subspaceDir)} -> ${verify.status}`,
+    }
+  })
+
+const editDataCalc = async (projectDir: string, input: any) =>
+  runOperation(projectDir, 'edit_data_calc', input, async () => {
+    const target = await resolveCalcTarget(projectDir, input)
+    const ctx: EditContext = {
+      projectDir,
+      parsed: target.parsed,
+      references: [],
+      typeImports: new Set(),
+      valueImports: new Set(),
+    }
+    const touchedSites: Array<Record<string, unknown>> = []
+
+    for (const [key, value] of Object.entries(input.set || {})) {
+      if (key === 'output' || key === 'error') {
+        setObjectProperty(target.object, key, await nullableDataGetterExpression(value, ctx))
+      } else if (key === 'inputs' || key === 'outputs') {
+        if (!Array.isArray(value)) {
+          throw new DataCalcEditingError('invalid_value', `${key} must be an array of IO items`)
+        }
+        setObjectProperty(target.object, key, await buildIoArrayExpression(key, value, ctx))
+      } else if (key === 'code') {
+        throw new DataCalcEditingError(
+          'invalid_field',
+          'Set code via the dedicated code parameter so it stays normalized to the sandbox file',
+        )
+      } else {
+        setObjectProperty(target.object, key, await expressionFromInput(value, ctx))
+      }
+    }
+    for (const key of input.unset || []) {
+      if (requiredCalcFields.has(key)) {
+        throw new DataCalcEditingError('invalid_field', `Cannot unset required field: ${key}`, {
+          field: key,
+        })
+      }
+      removeObjectProperty(target.object, key)
+    }
+
+    if (input.code != null) {
+      const codeExpression = getCodeExpression(target.object)
+      if (!isRecognizedCodeExpression(codeExpression)) {
+        throw new DataCalcEditingError(
+          'fallback_recommended',
+          `Data calc ${target.parsed.relPath} has an unsupported code expression. Edit this file directly for this one.`,
+          { file: target.parsed.relPath, field: 'code' },
+        )
+      }
+      const sandboxFile = target.sandboxFile
+      const sandboxPath = path.join(path.dirname(target.parsed.absPath), sandboxFile)
+      await writeFile(sandboxPath, wrapSandboxCode(input.code))
+      ensureReadFileImport(target.parsed.ast)
+      setObjectProperty(target.object, 'code', makeCodeReadFileExpression(sandboxFile))
+      touchedSites.push({
+        file: projectRelativePath(projectDir, sandboxPath),
+        action: 'write_sandbox',
+      })
+    }
+
+    applyPendingImports(ctx)
+    await writeParsedFile(target.parsed)
+    touchedSites.unshift({ file: target.parsed.relPath, action: 'edit_calc' })
+    const verify = await verifyProject(projectDir, input.verify)
+    return {
+      file: target.parsed.relPath,
+      calc: target.slug,
+      outcome: verify.status === 'compile:failed' ? 'verify_failed' : 'ok',
+      touchedSites,
+      verify,
+      references: referenceInputDetails(ctx.references),
+      summary: `edited data calc ${target.slug} -> ${verify.status}`,
+    }
+  })
+
+const editDataCalcIo = async (projectDir: string, input: any) =>
+  runOperation(projectDir, 'edit_data_calc_io', input, async () => {
+    const target = await resolveCalcTarget(projectDir, input)
+    const ctx: EditContext = {
+      projectDir,
+      parsed: target.parsed,
+      references: [],
+      typeImports: new Set(),
+      valueImports: new Set(),
+    }
+    const field = input.field as 'inputs' | 'outputs'
+    const array = getOrCreateArrayProperty(target.object, field)
+    const op = input.op
+
+    if (op === 'clear') {
+      array.elements = []
+    } else if (op === 'remove') {
+      const index = findIoIndex(array, input)
+      if (index < 0 || index >= array.elements.length) {
+        throw new DataCalcEditingError('invalid_index', 'remove requires a valid key or index')
+      }
+      array.elements.splice(index, 1)
+    } else if (op === 'add' || op === 'replace') {
+      const index = op === 'replace' ? findIoIndex(array, input) : input.index
+      if (op === 'replace' && (index < 0 || index >= array.elements.length)) {
+        throw new DataCalcEditingError('invalid_index', 'replace requires a valid key or index')
+      }
+      if (
+        op === 'add' &&
+        typeof index === 'number' &&
+        (index < 0 || index > array.elements.length)
+      ) {
+        throw new DataCalcEditingError('invalid_index', 'add index out of range', { index })
+      }
+      if (field === 'inputs')
+        assertInputKeyUnique(array, input.key, op === 'replace' ? index : undefined)
+      const item = await buildIoObject(field, input, ctx)
+      if (op === 'replace') array.elements[index] = item
+      else array.elements.splice(typeof index === 'number' ? index : array.elements.length, 0, item)
+    } else {
+      throw new DataCalcEditingError('invalid_op', `Unsupported edit_data_calc_io op: ${op}`)
+    }
+
+    applyPendingImports(ctx)
+    await writeParsedFile(target.parsed)
+    const verify = await verifyProject(projectDir, input.verify)
+    return {
+      file: target.parsed.relPath,
+      calc: target.slug,
+      outcome: verify.status === 'compile:failed' ? 'verify_failed' : 'ok',
+      change: { field, op, key: input.key, index: input.index },
+      verify,
+      references: referenceInputDetails(ctx.references),
+      summary: `${op} ${field} on data calc ${target.slug} -> ${verify.status}`,
+    }
+  })
+
+const removeDataCalc = async (projectDir: string, input: any) =>
+  runOperation(projectDir, 'remove_data_calc', input, async () => {
+    const target = await resolveCalcTarget(projectDir, input)
+    const dataCalcDir = path.dirname(target.parsed.absPath)
+    const sandboxPath = path.join(dataCalcDir, target.sandboxFile)
+    await rm(target.parsed.absPath, { force: true })
+    await rm(sandboxPath, { force: true })
+    const indexRelPath = await regenerateDataCalcIndex(projectDir, dataCalcDir)
+    const verify = await verifyProject(projectDir, input.verify)
+    return {
+      file: target.parsed.relPath,
+      calc: target.slug,
+      outcome: verify.status === 'compile:failed' ? 'verify_failed' : 'ok',
+      touchedSites: [
+        { file: target.parsed.relPath, action: 'delete_calc' },
+        { file: projectRelativePath(projectDir, sandboxPath), action: 'delete_sandbox' },
+        { file: indexRelPath, action: 'regenerate_index' },
+      ],
+      verify,
+      summary: `removed data calc ${target.slug} -> ${verify.status}`,
+    }
+  })
+
+const valueSchema = z
+  .any()
+  .describe(
+    'Value grammar: JSON literals, bare data ref strings for output/error/IO data, { ref, subspace }, or { expr: "raw TypeScript expression" }.',
+  )
+const fileSchema = z
+  .string()
+  .describe(
+    'Project-relative data-calc file path, for example subspaces/subspace-0/data-calc/data-calculation-total.ts.',
+  )
+const subspaceSchema = z
+  .union([z.string(), z.number()])
+  .describe(
+    'Subspace locator. Defaults to subspace-0; accepts 0, "0", "subspace-0", or a project-relative subspace path.',
+  )
+const calcSchema = z
+  .string()
+  .describe('Data calc locator inside the subspace: alias, explicit string id, or filename slug.')
+const verifySchema = z
+  .boolean()
+  .describe(
+    'Override compile verification. Defaults to BRICKS_CTOR_MCP_EDIT_VERIFY, otherwise true.',
+  )
+const targetSchema = {
+  file: fileSchema.optional(),
+  subspace: subspaceSchema.optional(),
+  calc: calcSchema.optional(),
+  verify: verifySchema.optional(),
+}
+const ioItemSchema = z
+  .object({
+    key: z.string().describe('Sandbox input/output key, for example "price" or "total".'),
+    data: valueSchema.describe('Data ref as alias/id/varName, { ref, subspace }, or { expr }.'),
+    trigger: z.boolean().describe('Inputs only; defaults true.').optional(),
+  })
+  .describe('DataCalculationScript IO item.')
+
+export function register(server: McpServer, projectDir: string) {
+  server.tool(
+    'new_data_calc',
+    'Create a standard DataCalculationScript in data-calc/{calc}.ts plus its sandbox JS file, regenerate data-calc/index.ts, and wire minimal subspace indexes.',
+    {
+      subspace: subspaceSchema.optional(),
+      alias: z.string().describe('Optional alias; also drives the filename slug.').optional(),
+      title: z.string().describe('Optional title.').optional(),
+      description: z.string().describe('Optional description.').optional(),
+      note: z.string().describe('Optional script note.').optional(),
+      triggerMode: z
+        .enum(['auto', 'manual'])
+        .describe('Optional trigger mode; omitted by default.')
+        .optional(),
+      enableAsync: z
+        .boolean()
+        .describe('Whether the sandbox main may be async. Defaults false.')
+        .optional(),
+      code: z
+        .string()
+        .describe(
+          'Sandbox body. The tool wraps it as export function main() { ... } unless already wrapped.',
+        )
+        .optional(),
+      inputs: z
+        .array(ioItemSchema)
+        .describe('Initial script inputs. Input keys must be unique.')
+        .optional(),
+      outputs: z
+        .array(ioItemSchema)
+        .describe('Initial fan-out outputs. Output keys may repeat.')
+        .optional(),
+      output: valueSchema.describe('Single output data ref or null.').optional(),
+      error: valueSchema.describe('Error output data ref or null.').optional(),
+      id: z
+        .string()
+        .describe(
+          "Optional explicit id. Defaults to source expression makeId('property_bank_calc').",
+        )
+        .optional(),
+      verify: verifySchema.optional(),
+    },
+    async (input: any) => responseFor(await newDataCalc(projectDir, input)),
+  )
+
+  server.tool(
+    'edit_data_calc',
+    'Edit DataCalculationScript scalar fields, output/error refs, or sandbox code. Code edits normalize inline code to sandbox file-form.',
+    {
+      ...targetSchema,
+      set: z
+        .record(
+          z
+            .string()
+            .describe(
+              'Top-level field path such as title, description, note, alias, triggerMode, enableAsync, output, or error.',
+            ),
+          valueSchema,
+        )
+        .describe(
+          'Fields to set. output/error accept bare data ref strings, { ref, subspace }, { expr }, or null; inputs/outputs accept whole replacement arrays of { key, data, trigger? }. Use the code parameter for code.',
+        )
+        .optional(),
+      unset: z.array(z.string()).describe('Top-level fields to remove.').optional(),
+      code: z
+        .string()
+        .describe(
+          'Replacement sandbox body. The tool wraps it as export function main() { ... } unless already wrapped.',
+        )
+        .optional(),
+    },
+    async (input: any) => responseFor(await editDataCalc(projectDir, input)),
+  )
+
+  server.tool(
+    'edit_data_calc_io',
+    'Edit DataCalculationScript inputs or outputs arrays. Inputs require unique keys; outputs may repeat keys for fan-out.',
+    {
+      ...targetSchema,
+      field: z.enum(['inputs', 'outputs']).describe('Which IO array to edit.'),
+      op: z.enum(['add', 'remove', 'replace', 'clear']).describe('Array operation.'),
+      key: z
+        .string()
+        .describe('IO key target. Ambiguous repeated output keys must use index.')
+        .optional(),
+      index: z.number().describe('Zero-based IO index target or add insertion index.').optional(),
+      data: valueSchema
+        .describe('For add/replace: data ref as string, { ref, subspace }, or { expr }.')
+        .optional(),
+      trigger: z.boolean().describe('Inputs only; defaults true.').optional(),
+    },
+    async (input: any) => responseFor(await editDataCalcIo(projectDir, input)),
+  )
+
+  server.tool(
+    'remove_data_calc',
+    'Remove a standard DataCalculationScript .ts file plus its sandbox file and regenerate data-calc/index.ts. No reverse cascade is needed.',
+    targetSchema,
+    async (input: any) => responseFor(await removeDataCalc(projectDir, input)),
+  )
+}
+
+export const __test__ = {
+  newDataCalc,
+  editDataCalc,
+  editDataCalcIo,
+  removeDataCalc,
+  resolveCalcTarget,
+}