@fugood/bricks-ctor 2.25.0-beta.43 → 2.25.0-beta.46

package/compile/__tests__/config-diff.test.js

@@ -1,4 +1,4 @@
-import { computeConfigChange, summarizeConfigChange } from '../config-diff'
+import { computeConfigChange } from '../config-diff'
 
 describe('computeConfigChange', () => {
   test('ignores the volatile top-level title and update_timestamp', () => {
@@ -54,19 +54,47 @@ describe('computeConfigChange', () => {
     })
   })
 
+  test('ignores object fields omitted by JSON.stringify', () => {
+    const before = { subspace_map: { S: { title: 'Home' } } }
+    const after = {
+      subspace_map: {
+        S: {
+          title: 'Home',
+          description: undefined,
+        },
+      },
+    }
+    expect(computeConfigChange(before, after)).toEqual({ status: 'ok', ops: [], opCount: 0 })
+  })
+
+  test('emits added values in JSON-compatible shape', () => {
+    const before = { m: {} }
+    const after = {
+      m: {
+        nested: {
+          keep: 1,
+          drop: undefined,
+        },
+        items: [undefined, 2],
+      },
+    }
+    const change = computeConfigChange(before, after)
+    expect(change.ops).toEqual([
+      { op: 'set', path: ['m', 'nested'], value: { keep: 1 } },
+      { op: 'set', path: ['m', 'items'], value: [null, 2] },
+    ])
+  })
+
+  test('compares array undefined entries like JSON nulls', () => {
+    expect(computeConfigChange({ items: [null] }, { items: [undefined] })).toEqual({
+      status: 'ok',
+      ops: [],
+      opCount: 0,
+    })
+  })
+
   test('reports no_baseline / unavailable for missing sides', () => {
     expect(computeConfigChange(null, { a: 1 })).toEqual({ status: 'no_baseline' })
     expect(computeConfigChange({ a: 1 }, null)).toEqual({ status: 'unavailable' })
   })
 })
-
-describe('summarizeConfigChange', () => {
-  test('summarizes each status', () => {
-    expect(summarizeConfigChange({ status: 'no_baseline' })).toMatch(/no prior build/)
-    expect(summarizeConfigChange({ status: 'unavailable' })).toMatch(/unavailable/)
-    expect(summarizeConfigChange({ status: 'ok', ops: [], opCount: 0 })).toBe('config change: none')
-    expect(summarizeConfigChange({ status: 'ok', ops: [{}, {}], opCount: 2 })).toBe(
-      'config change: 2 op(s)',
-    )
-  })
-})

package/compile/__tests__/index.test.js

@@ -1,11 +1,11 @@
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
-import os from 'node:os'
-import path from 'node:path'
-
 jest.mock('../../tools/_shell', () => ({
   sh: jest.fn(() => Promise.resolve({})),
 }))
 
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
 import { sh } from '../../tools/_shell'
 import { checkConfig, compile } from '../index'
 
@@ -178,34 +178,65 @@ describe('compile data remote update', () => {
   })
 })
 
-describe('compile config change report', () => {
-  test('prints the config delta vs the prior build artifact in cwd', async () => {
-    const logSpy = jest.spyOn(console, 'log').mockImplementation(() => {})
+describe('compile config-change audit log', () => {
+  const readAudit = async (projectDir) =>
+    (await readFile(path.join(projectDir, '.bricks/edits.jsonl'), 'utf8'))
+      .trim()
+      .split('\n')
+      .map((line) => JSON.parse(line))
+
+  const seedArtifact = async (projectDir, config) => {
+    const artifactPath = path.join(projectDir, '.bricks/build/application-config.json')
+    await mkdir(path.dirname(artifactPath), { recursive: true })
+    await writeFile(artifactPath, JSON.stringify(config))
+  }
+
+  test('records the config delta only in the editing-tools context', async () => {
     const prevCwd = process.cwd()
+    const prevEnv = process.env.BRICKS_CTOR_ENABLE_EDITING_TOOLS
     let projectDir
     try {
-      // No .bricks/build artifact in the test cwd → the report stays silent.
-      const before = await compile(makeApp([], [makeData(undefined)]))
-      expect(logSpy.mock.calls.flat().join('\n')).not.toContain('config change')
-
-      projectDir = await mkdtemp(path.join(os.tmpdir(), 'bricks-compile-diff-'))
-      const artifactPath = path.join(projectDir, '.bricks/build/application-config.json')
-      await mkdir(path.dirname(artifactPath), { recursive: true })
-      await writeFile(artifactPath, JSON.stringify(before))
+      projectDir = await mkdtemp(path.join(os.tmpdir(), 'bricks-compile-audit-'))
       process.chdir(projectDir)
 
-      const second = await compile(makeApp([], [makeData({ type: 'auto' })]))
-      const output = logSpy.mock.calls.flat().join('\n')
-      expect(output).toMatch(/config change: \d+ op\(s\)/)
-      expect(output).toContain('property_bank_map')
-
-      await writeFile(artifactPath, JSON.stringify(second))
-      logSpy.mockClear()
-      await compile(makeApp([], [makeData({ type: 'auto' })]))
-      expect(logSpy.mock.calls.flat().join('\n')).toContain('config change: none')
+      // (1) Editing tools disabled: even a real delta against a baseline is not recorded.
+      delete process.env.BRICKS_CTOR_ENABLE_EDITING_TOOLS
+      const empty = await compile(makeApp([], []))
+      await seedArtifact(projectDir, empty)
+      await compile(makeApp([], [makeData(undefined)]))
+      await expect(readFile(path.join(projectDir, '.bricks/edits.jsonl'))).rejects.toThrow()
+
+      // (2) Editing tools enabled: the compiled-config delta is recorded.
+      process.env.BRICKS_CTOR_ENABLE_EDITING_TOOLS = '1'
+      await seedArtifact(projectDir, empty)
+      const withData = await compile(makeApp([], [makeData(undefined)]))
+      const audit = await readAudit(projectDir)
+      expect(audit).toHaveLength(1)
+      expect(audit[0].tool).toBe('compile')
+      expect(audit[0].outcome).toBe('ok')
+      expect(audit[0].summary).toMatch(/compile: \d+ config op\(s\)/)
+      expect(JSON.stringify(audit[0].configChange)).toContain('property_bank_map')
+      // The audit log gets gitignored on first write.
+      const gitignore = await readFile(path.join(projectDir, '.gitignore'), 'utf8')
+      expect(gitignore).toContain('.bricks/edits.jsonl')
+
+      // (3) Recompiling with no source change records a "no config change" entry.
+      await seedArtifact(projectDir, withData)
+      await compile(makeApp([], [makeData(undefined)]))
+      const afterNoop = await readAudit(projectDir)
+      expect(afterNoop).toHaveLength(2)
+      expect(afterNoop[1].summary).toBe('compile: no config change')
+
+      // (4) Turning the flag off again (as the editing tools do for their verify compiles)
+      // suppresses the record even though there is a real delta.
+      process.env.BRICKS_CTOR_ENABLE_EDITING_TOOLS = '0'
+      await seedArtifact(projectDir, withData)
+      await compile(makeApp([], []))
+      expect(await readAudit(projectDir)).toHaveLength(2)
     } finally {
+      if (prevEnv === undefined) delete process.env.BRICKS_CTOR_ENABLE_EDITING_TOOLS
+      else process.env.BRICKS_CTOR_ENABLE_EDITING_TOOLS = prevEnv
       process.chdir(prevCwd)
-      logSpy.mockRestore()
       if (projectDir) await rm(projectDir, { recursive: true, force: true })
     }
   })

package/compile/__tests__/util.test.js

@@ -66,9 +66,14 @@ describe('validateConfig', () => {
   })
 })
 
+// generateCalulationMap now seeds command ids from the owning calc id; tests that don't
+// assert id values share one fixed id (ids stay deterministic with no global state).
+const CALC_ID = 'PROPERTY_BANK_COMMAND_MAP_00000000-0000-4000-8000-000000000000'
+const genMap = (config, calcId = CALC_ID) => generateCalulationMap(config, calcId)
+
 describe('generateCalulationMap', () => {
   test('produces only the three sandbox nodes for an empty config', () => {
-    const result = generateCalulationMap(baseConfig())
+    const result = genMap(baseConfig())
 
     expect(Object.keys(result.map)).toHaveLength(3)
     const { run, error, result: returnValue } = findSandboxIds(result.map)
@@ -80,7 +85,7 @@ describe('generateCalulationMap', () => {
   })
 
   test('chains multiple inputs through OBJECT_SET commands', () => {
-    const result = generateCalulationMap(baseConfig({ inputs: { a: 'foo.bar', b: 'baz' } }))
+    const result = genMap(baseConfig({ inputs: { a: 'foo.bar', b: 'baz' } }))
 
     const { run } = findSandboxIds(result.map)
 
@@ -110,7 +115,7 @@ describe('generateCalulationMap', () => {
   })
 
   test('builds OBJECT_GET commands and target data-nodes for outputs', () => {
-    const result = generateCalulationMap(baseConfig({ outputs: { resultPath: ['pb1', 'pb2'] } }))
+    const result = genMap(baseConfig({ outputs: { resultPath: ['pb1', 'pb2'] } }))
 
     const { result: returnValue } = findSandboxIds(result.map)
 
@@ -152,7 +157,7 @@ describe('generateCalulationMap', () => {
     ['output', { output: 'shared' }],
     ['error', { error: 'shared' }],
   ])('preserves input out.value when %s target reuses an input id', (_, overrides) => {
-    const result = generateCalulationMap(
+    const result = genMap(
       baseConfig({ trigger_mode: 'manual', inputs: { shared: 'foo' }, ...overrides }),
     )
     expect(Array.isArray(result.map.shared.out.value)).toBe(true)
@@ -160,7 +165,7 @@ describe('generateCalulationMap', () => {
   })
 
   test('also rewires in.change to OBJECT_GET when an outputs target reuses an input id', () => {
-    const result = generateCalulationMap(
+    const result = genMap(
       baseConfig({
         trigger_mode: 'manual',
         inputs: { shared: 'foo' },
@@ -175,9 +180,7 @@ describe('generateCalulationMap', () => {
     // Two outputs entries both target `pb1`. The reduce visits each entry in turn
     // and must preserve the accumulated `out.value` from the first iteration via
     // `acc.map[pb]` rather than wiping it on the second.
-    const result = generateCalulationMap(
-      baseConfig({ outputs: { first: ['pb1'], second: ['pb1'] } }),
-    )
+    const result = genMap(baseConfig({ outputs: { first: ['pb1'], second: ['pb1'] } }))
     expect(result.map.pb1.type).toBe('data-node')
     // Without an input, out.value remains null after both passes.
     expect(result.map.pb1.out.value).toBeNull()
@@ -187,7 +190,7 @@ describe('generateCalulationMap', () => {
   })
 
   test('wires the error data-node when error is configured', () => {
-    const result = generateCalulationMap(baseConfig({ error: 'errNode' }))
+    const result = genMap(baseConfig({ error: 'errNode' }))
 
     const { error } = findSandboxIds(result.map)
     // SANDBOX_GET_ERROR now broadcasts to the error data-node's `change` port.
@@ -201,7 +204,7 @@ describe('generateCalulationMap', () => {
   })
 
   test('wires the output data-node when output is configured', () => {
-    const result = generateCalulationMap(baseConfig({ output: 'outNode' }))
+    const result = genMap(baseConfig({ output: 'outNode' }))
 
     const { result: returnValue } = findSandboxIds(result.map)
     expect(result.map[returnValue].out.result).toEqual([{ id: 'outNode', port: 'change' }])
@@ -211,7 +214,7 @@ describe('generateCalulationMap', () => {
   })
 
   test('manual trigger mode sets disable_trigger_command on input value ports', () => {
-    const result = generateCalulationMap(
+    const result = genMap(
       baseConfig({
         trigger_mode: 'manual',
         inputs: { a: 'foo', b: 'bar' },
@@ -224,7 +227,7 @@ describe('generateCalulationMap', () => {
   })
 
   test('auto trigger mode honours per-key disabled_triggers', () => {
-    const result = generateCalulationMap(
+    const result = genMap(
       baseConfig({
         inputs: { a: 'foo', b: 'bar' },
         disabled_triggers: { a: true, b: false },
@@ -238,30 +241,44 @@ describe('generateCalulationMap', () => {
   })
 
   test('auto trigger mode without disabled_triggers leaves disable_trigger_command undefined', () => {
-    const result = generateCalulationMap(baseConfig({ inputs: { a: 'foo' } }))
+    const result = genMap(baseConfig({ inputs: { a: 'foo' } }))
     const aCmdId = result.map.a.out.value[0].id
     expect(result.map[aCmdId].in.value[0].disable_trigger_command).toBeUndefined()
   })
 
-  test('snapshotMode forwards to makeId so generated ids are deterministic v4 uuids', () => {
-    const result = generateCalulationMap(baseConfig({ inputs: { a: 'foo' } }), {
-      snapshotMode: true,
-    })
-    const sandboxIds = sandboxNodeIds(result.map).map((s) => s.id)
+  test('derives command ids deterministically from the calc id (stable across compiles)', () => {
+    const config = baseConfig({ inputs: { a: 'foo' }, outputs: { out: ['pb1'] } })
+    const first = generateCalulationMap(config, CALC_ID)
+    const second = generateCalulationMap(config, CALC_ID)
+    // Same calc id + same config must yield byte-identical ids, so recompiling unchanged
+    // source produces no spurious property_bank_calc_map diff.
+    expect(Object.keys(second.map)).toEqual(Object.keys(first.map))
+
     const uuid = '[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}'
-    sandboxIds.forEach((id) => {
+    sandboxNodeIds(first.map).forEach(({ id }) => {
       expect(id).toMatch(new RegExp(`^PROPERTY_BANK_COMMAND_NODE_${uuid}$`))
     })
   })
 
-  test('validateConfig errors propagate out of generateCalulationMap', () => {
-    expect(() => generateCalulationMap(baseConfig({ inputs: { a: 'foo' }, error: 'a' }))).toThrow(
-      /key: error/,
+  test('seeds command ids per calc so different calcs never collide (edit isolation)', () => {
+    const config = baseConfig({ inputs: { a: 'foo' } })
+    const a = generateCalulationMap(
+      config,
+      'PROPERTY_BANK_COMMAND_MAP_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
     )
+    const b = generateCalulationMap(
+      config,
+      'PROPERTY_BANK_COMMAND_MAP_bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb',
+    )
+    expect(findSandboxIds(a.map).run).not.toBe(findSandboxIds(b.map).run)
+  })
+
+  test('validateConfig errors propagate out of generateCalulationMap', () => {
+    expect(() => genMap(baseConfig({ inputs: { a: 'foo' }, error: 'a' }))).toThrow(/key: error/)
   })
 
   test('SANDBOX_GET_RETURN_VALUE broadcasts to both output target and outputs commands', () => {
-    const result = generateCalulationMap(
+    const result = genMap(
       baseConfig({
         output: 'outNode',
         outputs: { foo: ['pb1'] },

package/compile/config-diff.ts

@@ -27,17 +27,60 @@ export type ConfigChange =
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value)
 
+const isJsonDroppedValue = (value: unknown) =>
+  value === undefined || typeof value === 'function' || typeof value === 'symbol'
+
+const toJsonComparableScalar = (value: unknown) => {
+  if (typeof value === 'number' && !Number.isFinite(value)) return null
+  return value
+}
+
+const toJsonCompatibleValue = (value: unknown): unknown => {
+  if (isJsonDroppedValue(value)) return undefined
+  if (Array.isArray(value)) {
+    return value.map((item) => (isJsonDroppedValue(item) ? null : toJsonCompatibleValue(item)))
+  }
+  if (isRecord(value)) {
+    return Object.entries(value).reduce((acc, [key, item]) => {
+      if (!isJsonDroppedValue(item)) acc[key] = toJsonCompatibleValue(item)
+      return acc
+    }, {})
+  }
+  return toJsonComparableScalar(value)
+}
+
+const hasJsonObjectKey = (value: Record<string, unknown>, key: string) =>
+  Object.prototype.hasOwnProperty.call(value, key) && !isJsonDroppedValue(value[key])
+
+const getJsonArrayItem = (value: unknown[], index: number) => {
+  const item = value[index]
+  return isJsonDroppedValue(item) ? null : item
+}
+
 const deepEqual = (a: unknown, b: unknown): boolean => {
+  a = toJsonComparableScalar(a)
+  b = toJsonComparableScalar(b)
   if (a === b) return true
   if (Array.isArray(a) && Array.isArray(b)) {
-    return a.length === b.length && a.every((item, index) => deepEqual(item, b[index]))
+    if (a.length !== b.length) return false
+    for (let index = 0; index < a.length; index += 1) {
+      if (!deepEqual(getJsonArrayItem(a, index), getJsonArrayItem(b, index))) return false
+    }
+    return true
   }
   if (isRecord(a) && isRecord(b)) {
-    const aKeys = Object.keys(a)
-    return (
-      aKeys.length === Object.keys(b).length &&
-      aKeys.every((key) => key in b && deepEqual(a[key], b[key]))
-    )
+    let comparableAKeys = 0
+    for (const key of Object.keys(a)) {
+      if (isJsonDroppedValue(a[key])) continue
+      comparableAKeys += 1
+      if (!hasJsonObjectKey(b, key) || !deepEqual(a[key], b[key])) return false
+    }
+
+    let comparableBKeys = 0
+    for (const key of Object.keys(b)) {
+      if (!isJsonDroppedValue(b[key])) comparableBKeys += 1
+    }
+    return comparableAKeys === comparableBKeys
   }
   return false
 }
@@ -64,22 +107,32 @@ const diffInto = (
   if (isRecord(before) && isRecord(after)) {
     const keys = new Set([...Object.keys(before), ...Object.keys(after)])
     for (const key of keys) {
+      const beforeHasKey = hasJsonObjectKey(before, key)
+      const afterHasKey = hasJsonObjectKey(after, key)
+      if (!beforeHasKey && !afterHasKey) continue
+
       const nextPath = [...currentPath, key]
-      if (!(key in after)) ops.push({ op: 'unset', path: nextPath })
-      else if (!(key in before)) ops.push({ op: 'set', path: nextPath, value: after[key] })
-      else diffInto(before[key], after[key], nextPath, ops)
+      if (!afterHasKey) ops.push({ op: 'unset', path: nextPath })
+      else if (!beforeHasKey) {
+        ops.push({ op: 'set', path: nextPath, value: toJsonCompatibleValue(after[key]) })
+      } else diffInto(before[key], after[key], nextPath, ops)
     }
     return
   }
 
   if (Array.isArray(before) && Array.isArray(after) && before.length === after.length) {
     for (let index = 0; index < after.length; index += 1) {
-      diffInto(before[index], after[index], [...currentPath, index], ops)
+      diffInto(
+        getJsonArrayItem(before, index),
+        getJsonArrayItem(after, index),
+        [...currentPath, index],
+        ops,
+      )
     }
     return
   }
 
-  ops.push({ op: 'set', path: currentPath, value: after })
+  ops.push({ op: 'set', path: currentPath, value: toJsonCompatibleValue(after) })
 }
 
 // Diff two compiled configs. `before == null` means there was no prior build to compare
@@ -100,9 +153,3 @@ export const readBuildConfig = async (projectDir: string): Promise<unknown> => {
     return null
   }
 }
-
-export const summarizeConfigChange = (change: ConfigChange): string => {
-  if (change.status === 'no_baseline') return 'config change: no prior build to compare'
-  if (change.status === 'unavailable') return 'config change: build artifact unavailable'
-  return change.opCount === 0 ? 'config change: none' : `config change: ${change.opCount} op(s)`
-}

package/compile/index.ts

@@ -8,10 +8,12 @@ import type { ExportNamedDeclaration, FunctionDeclaration } from 'acorn'
 import escodegen from 'escodegen'
 import { makeId } from '../utils/id'
 import { generateCalulationMap } from './util'
-import { computeConfigChange, readBuildConfig, summarizeConfigChange } from './config-diff'
 import { templateActionNameMap } from './action-name-map'
 import { templateEventPropsMap } from '../utils/event-props'
 import { sh } from '../tools/_shell'
+import { computeConfigChange, readBuildConfig } from './config-diff'
+import { appendEditRecord, editProvenance } from '../tools/_edits-log'
+import { isTruthyEnv } from '../tools/mcp-env'
 import type {
   Application,
   Data,
@@ -702,24 +704,37 @@ const compileAutomation = (automationMap: AutomationMap) =>
     }),
   )
 
-// Print the minimal config delta vs the previous `bun compile` artifact (volatile
-// timestamp fields excluded). Silent when there is no prior build to compare, so
-// direct compile() callers (tests, tooling outside a project) emit nothing.
-const reportConfigChange = (previousConfig: unknown, config: unknown) => {
+// Record the minimal compiled-config delta this compile produced to the shared audit
+// log (`.bricks/edits.jsonl`), so editing files directly and running `bun compile`
+// leaves the same trail as the MCP source-editing tools. Maintained only in the
+// editing-tools context (`BRICKS_CTOR_ENABLE_EDITING_TOOLS`); the source-editing tools
+// turn it off for their verify compiles (see _verify.ts) so a tool edit records one
+// richer entry instead of an extra generic compile entry. Also silent when there is no
+// prior build to diff against (fresh projects, package tests, tooling outside a project).
+const recordConfigChange = async (previousConfig: unknown, config: unknown) => {
   if (previousConfig == null) return
-  // The baseline was parsed from JSON; round-trip the fresh config the same way so
-  // keys holding undefined (dropped by the artifact's JSON.stringify) don't diff
-  // as phantom sets.
-  const change = computeConfigChange(previousConfig, JSON.parse(JSON.stringify(config)))
+  if (!isTruthyEnv(process.env.BRICKS_CTOR_ENABLE_EDITING_TOOLS)) return
+  // The baseline was parsed from JSON; `computeConfigChange` applies the same
+  // JSON-omitted-field rules lazily so compile avoids cloning the full config.
+  const change = computeConfigChange(previousConfig, config)
   if (change.status !== 'ok') return
-  console.log(summarizeConfigChange(change))
-  if (change.opCount > 0) console.log(JSON.stringify(change.ops, null, 2))
+  await appendEditRecord(process.cwd(), {
+    ts: new Date().toISOString(),
+    tool: 'compile',
+    provenance: editProvenance(),
+    outcome: 'ok',
+    summary:
+      change.opCount === 0
+        ? 'compile: no config change'
+        : `compile: ${change.opCount} config op(s)`,
+    configChange: change,
+  }).catch(() => undefined)
 }
 
 export const compile = async (app: Application) => {
   await new Promise((resolve) => setImmediate(resolve, 0))
-  // Snapshot the previous build artifact before the caller's compile.ts overwrites it,
-  // so the config change introduced by this compile can be reported on return.
+  // Snapshot the prior build artifact before the caller's compile.ts overwrites it, so
+  // the config change introduced by this compile can be recorded on return.
   const previousConfig = await readBuildConfig(process.cwd())
   const timestamp = Date.now()
   // Pre-index subspace ids so the canvas-item validation below stays O(1).
@@ -1433,12 +1448,7 @@ export const compile = async (app: Application) => {
                 : null,
             }
 
-            Object.assign(
-              calc,
-              generateCalulationMap(calc.script_config, {
-                snapshotMode: process.env.BRICKS_SNAPSHOT_MODE === '1',
-              }),
-            )
+            Object.assign(calc, generateCalulationMap(calc.script_config, dataCalcId))
           }
           map[dataCalcId] = calc
           return map
@@ -1475,7 +1485,7 @@ export const compile = async (app: Application) => {
     automation_map: compiledAutomationMap || app.metadata?.TEMP_automation_map || {},
     update_timestamp: timestamp,
   }
-  reportConfigChange(previousConfig, config)
+  await recordConfigChange(previousConfig, config)
   return config
 }
 

package/compile/util.ts

@@ -1,4 +1,4 @@
-import { makeId } from '../utils/id'
+import { makeSeededId } from '../utils/id'
 
 type ScriptConfig = {
   title?: string
@@ -33,15 +33,18 @@ const padding = 15
 const layerXInterval = 300
 const layerYInterval = 150
 
-export const generateCalulationMap = (config: ScriptConfig, opts?: { snapshotMode?: boolean }) => {
+// `calcId` (the owning script calc's stable id) seeds every derived command-node id, so an
+// unchanged calc recompiles to identical ids and editing one calc never shifts another's —
+// keeping the compiled config byte-stable for change detection. See makeSeededId in utils/id.
+export const generateCalulationMap = (config: ScriptConfig, calcId: string) => {
   validateConfig(config)
-  const sandboxId = makeId('property_bank_command', opts)
-  const sandboxErrorId = makeId('property_bank_command', opts)
-  const sandboxResultId = makeId('property_bank_command', opts)
+  const sandboxId = makeSeededId('property_bank_command', `${calcId}:sandbox-run`)
+  const sandboxErrorId = makeSeededId('property_bank_command', `${calcId}:sandbox-error`)
+  const sandboxResultId = makeSeededId('property_bank_command', `${calcId}:sandbox-result`)
 
   const inputs = Object.entries(config.inputs).reduce(
     (acc, [key, value], index) => {
-      const commandId = makeId('property_bank_command', opts)
+      const commandId = makeSeededId('property_bank_command', `${calcId}:input:${key}`)
       acc.map[key] = {
         type: 'data-node',
         properties: {},
@@ -123,7 +126,7 @@ export const generateCalulationMap = (config: ScriptConfig, opts?: { snapshotMod
   let y = 0
   const outputs = Object.entries(config.outputs).reduce(
     (acc, [key, pbList], index) => {
-      const commandId = makeId('property_bank_command', opts)
+      const commandId = makeSeededId('property_bank_command', `${calcId}:output:${key}`)
       acc.commandIdList.push(commandId)
       acc.map[commandId] = {
         type: 'command-node-object',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fugood/bricks-ctor",
-  "version": "2.25.0-beta.43",
+  "version": "2.25.0-beta.46",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -11,7 +11,7 @@
     "@babel/parser": "7.28.5",
     "@babel/traverse": "7.28.5",
     "@babel/types": "7.28.5",
-    "@fugood/bricks-cli": "^2.25.0-beta.43",
+    "@fugood/bricks-cli": "^2.25.0-beta.46",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",
@@ -29,5 +29,5 @@
   "peerDependencies": {
     "oxfmt": "^0.36.0"
   },
-  "gitHead": "e98adf7777d310a0fdc4de374af9744fc804298d"
+  "gitHead": "877bdee4953bcdc09b2dd04f28c8d7edc37824ab"
 }

package/skills/bricks-ctor/references/simulator.md

@@ -46,7 +46,7 @@ These work, but with browser caveats:
 | WebView / WebCrawler | Subject to browser CORS — a load/fetch that works on device may be blocked |
 | On-device AI (LLM / STT / VAD / Vector Store / Reranker) | Runs **single-threaded** — far slower than the device, not representative of real latency. Also subject to the model fallbacks below |
 | On-device database (SQLite — `GENERATOR_SQLITE`) | Runs for real on the in-memory WASM `sqlite-vec` build — `execute` / `query` / `transaction` / batch all work. `storageType: file` is transparently treated as in-memory, so nothing persists across reloads (see above) |
-| Scene3D / Maps / Sketch / WebRTC | Supported |
+| Scene3D / Sketch / WebRTC | Supported |
 
 Feature availability also varies across the device platforms themselves (iOS / tvOS / Android / the desktop OSes). When a deployment targets a specific platform's capability, confirm it on that platform.
 
@@ -89,6 +89,7 @@ So that camera and AI features are usable without device permissions, multi-giga
 | Brick / Generator | In the Simulator | Does NOT prove |
 |-------------------|------------------|----------------|
 | Camera (`BRICK_CAMERA`) | A 3D mock canvas, no camera permission prompt. `takePicture` snapshots the canvas; recording produces a placeholder clip | Real camera feed, focus, recording, permission flow |
+| Maps (`BRICK_MAPS`) | A real interactive map on free OpenStreetMap-based tiles — no Google Maps API key needed. Markers, path polyline, the six themes / map types (approximated with free tile sets + CSS tints), and the zoom / pan / navigate / focus / reset / fit actions all work | Google / Apple Maps rendering, exact `customMapStyle` / theme styling (approximated), traffic / buildings / indoors layers, real device geolocation |
 | Thermal Printer (`GENERATOR_THERMAL_PRINTER`) | A simulated printer — `init` / `checkStatus` / `scan` fake per-driver status and discovered devices (ESC/POS, Star, TSC, Castles); `print` renders an approximate on-screen receipt. A bottom-left bubble shows live status with a fault toggle to exercise error wiring. Print results can be exported as PNG via `bricks-cli` (see below) | Real device connection, actual paper output, exact native driver status codes |
 | LLM (`GENERATOR_LLM`) | Swapped to a tiny local stand-in model | Output quality / latency of your real model |
 | Reranker — GGML (`GENERATOR_RERANKER`) | Swapped to a small local multilingual reranker model | Ranking quality / latency of your real model |
@@ -119,7 +120,7 @@ The PNG is the same approximate receipt the on-screen preview shows (rendered fr
 
 ### Running the real implementation instead
 
-Each substituted brick/generator can be switched back to its real implementation per item: open the **gear (Simulator settings)** in the editor's preview toolbar, uncheck the item, and **Apply**. Apply persists the choice and reloads the preview so it takes effect (a plain refresh won't). Use this to, e.g., point a Vector Store at a real API key in the preview. The browser limits above still apply, and **Buttress stays disabled regardless** — there's no backend for it here.
+Each substituted brick/generator can be switched back to its real implementation per item: open the **gear (Simulator settings)** in the editor's preview toolbar, uncheck the item, and **Apply**. Apply persists the choice and reloads the preview so it takes effect (a plain refresh won't). Use this to, e.g., point a Vector Store at a real API key in the preview, or render the real Google/Apple Maps brick (which needs a Maps API key on web). The browser limits above still apply, and **Buttress stays disabled regardless** — there's no backend for it here.
 
 The Thermal Printer is the exception: it has no real web implementation to switch to (the native drivers can't run in a browser), so it is **always simulated** and is not in the gear list.
 

package/skills/bricks-ctor/references/verification-toolchain.md

@@ -71,6 +71,8 @@ Useful flags:
 
 For ad-hoc CDP inspection against this local preview, connect any CDP client to `localhost:19852` — Chrome DevTools front-end works directly. For an agent-friendly CLI over CDP (screenshot, brick tree/query, input emulation, storage reads, runtime eval, network capture), the `bricks-cli` skill documents the `bricks devtools` command surface — read that skill if it is installed in this workspace. If it is not installed, run `bricks --help` and `bricks devtools --help`; the CLI's own help output is authoritative.
 
+To inspect Data / Property Bank or storage state, prefer the dedicated `bricks devtools storage` subcommands — `storage data-bank get <S_xxxx>` (saved Data values), `storage system persist|memory`, `storage system get <key>` — over hand-written `runtime eval`. Reach for `runtime eval` only for *live* store internals that aren't persisted to a data bank (e.g. a current transient value: `runtime eval "system.data.property('S_xxxx', '<alias>')"`); don't reverse-engineer the `system.*` globals.
+
 ### Project Automations
 
 E2E tests authored in TypeScript inside the project (`AutomationTest` / `TestCase`). Test cases include:

package/tools/_edits-log.ts

@@ -0,0 +1,41 @@
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+const auditLogIgnoreEntry = '.bricks/edits.jsonl'
+
+// Ensure the project's .gitignore excludes the audit log. No-op when it is already
+// ignored directly or via a broader `.bricks` rule.
+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`,
+  )
+}
+
+// Append one JSON record to `.bricks/edits.jsonl`, creating the directory and the
+// gitignore entry as needed. Shared by the source-editing tools and `compile()` so
+// every project mutation lands in the same audit log.
+export 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`)
+}
+
+// Provenance stamped on every audit record: which agent/session produced the change.
+export const editProvenance = () => ({
+  session: process.env.BRICKS_CTOR_SESSION_ID || process.env.CODEX_SESSION_ID,
+  agent: process.env.BRICKS_CTOR_AGENT_ID || process.env.USER,
+})

package/tools/mcp-env.ts

@@ -9,5 +9,5 @@ export function isTruthyEnv(value: string | undefined) {
 }
 
 export function shouldRegisterEditingTools(env: Record<string, string | undefined> = process.env) {
-  return isTruthyEnv(env.BRICKS_CTOR_MCP_ENABLE_EDITING_TOOLS)
+  return isTruthyEnv(env.BRICKS_CTOR_ENABLE_EDITING_TOOLS)
 }

package/tools/mcp-tools/__tests__/mcp-env.test.js

@@ -9,13 +9,11 @@ describe('mcp env helpers', () => {
 
   test('does not enable editing tools by default', () => {
     expect(shouldRegisterEditingTools({})).toBe(false)
-    expect(shouldRegisterEditingTools({ BRICKS_CTOR_MCP_ENABLE_EDITING_TOOLS: '0' })).toBe(false)
-    expect(shouldRegisterEditingTools({ BRICKS_CTOR_MCP_ENABLE_EDITING_TOOLS: 'false' })).toBe(
-      false,
-    )
+    expect(shouldRegisterEditingTools({ BRICKS_CTOR_ENABLE_EDITING_TOOLS: '0' })).toBe(false)
+    expect(shouldRegisterEditingTools({ BRICKS_CTOR_ENABLE_EDITING_TOOLS: 'false' })).toBe(false)
   })
 
   test('enables editing tools when explicitly requested', () => {
-    expect(shouldRegisterEditingTools({ BRICKS_CTOR_MCP_ENABLE_EDITING_TOOLS: '1' })).toBe(true)
+    expect(shouldRegisterEditingTools({ BRICKS_CTOR_ENABLE_EDITING_TOOLS: '1' })).toBe(true)
   })
 })

package/tools/mcp-tools/_verify.ts

@@ -17,7 +17,12 @@ export const compileAndDiff = async (projectDir: string): Promise<VerificationRe
   // Snapshot the prior compiled config before recompiling (the new artifact overwrites it).
   const before = await readBuildConfig(projectDir)
   try {
-    await sh`bun compile`.cwd(projectDir).env(noColorEnv).text()
+    // Turn off the editing-tools audit for this spawned compile so compile() doesn't write
+    // a duplicate generic entry — the calling editing tool records its own richer entry.
+    await sh`bun compile`
+      .cwd(projectDir)
+      .env({ ...noColorEnv, BRICKS_CTOR_ENABLE_EDITING_TOOLS: '0' })
+      .text()
   } catch (err: any) {
     const stdout = err.stdout?.toString() ?? ''
     const stderr = err.stderr?.toString() ?? ''

package/tools/mcp-tools/compile.ts

@@ -10,9 +10,9 @@ const noColorEnv = { FORCE_COLOR: '0', NO_COLOR: '1' }
 export function register(server: McpServer, projectDir: string) {
   const { dirname } = import.meta
 
+  // `bun compile` records the resulting config delta to `.bricks/edits.jsonl` itself
+  // (see compile() in compile/index.ts), so the spawned output below already reflects it.
   server.tool('compile', {}, async () => {
-    // The config-change report is printed by compile() itself (compile/config-diff.ts),
-    // so the spawned `bun compile` output below already carries it.
     let log = 'Type checking & Compiling...\n'
     try {
       log += await sh`bun compile`.cwd(projectDir).env(noColorEnv).text()

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

@@ -4,16 +4,15 @@ 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 { appendFile, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+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 auditLogIgnoreEntry = '.bricks/edits.jsonl'
-
 const oxfmtOptions = {
   trailingComma: 'all',
   tabWidth: 2,
@@ -646,32 +645,6 @@ const writeParsedFile = async (parsed: ParsedFile) => {
   return code
 }
 
-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 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 responseFor = (result: any): any => ({
   content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
   isError: result.isError || undefined,
@@ -692,10 +665,7 @@ const runOperation = async (
   operation: () => Promise<any>,
 ) => {
   const startedAt = new Date().toISOString()
-  const provenance = {
-    session: process.env.BRICKS_CTOR_SESSION_ID || process.env.CODEX_SESSION_ID,
-    agent: process.env.BRICKS_CTOR_AGENT_ID || process.env.USER,
-  }
+  const provenance = editProvenance()
   try {
     const result = await operation()
     await appendEditRecord(projectDir, {

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

@@ -5,17 +5,16 @@ 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 { readFile, readdir, 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 traverse = (traverseModule as any).default || traverseModule
 
-const auditLogIgnoreEntry = '.bricks/edits.jsonl'
-
 const oxfmtOptions = {
   trailingComma: 'all',
   tabWidth: 2,
@@ -894,32 +893,6 @@ const writeParsedFile = async (parsed: ParsedFile) => {
   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)
@@ -941,10 +914,7 @@ const runOperation = async (
       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,
-    },
+    provenance: editProvenance(),
   }
 
   try {

package/types/data-calc-command/color.d.ts

@@ -250,7 +250,7 @@ export type DataCommandColorRandom = DataCommand & {
   outputs?: Array<DataCalcOutput<'result'> /* target: string */>
 }
 
-/* RGBA — Generate color string RGBA values */
+/* RGBA — Generate a color from RGBA channels (red/green/blue: 0-255, alpha: 0-1) */
 export type DataCommandColorRgba = DataCommand & {
   __commandName: 'COLOR_RGBA'
   inputs?: Array<

package/types/data-calc-command/datetime.d.ts

@@ -22,7 +22,7 @@ export type DataCommandDatetimeDate = DataCommand & {
   outputs?: Array<DataCalcOutput<'result'> /* target: number */>
 }
 
-/* Day — Get day (Sunday is 7) */
+/* Day — Get day of week (0-based: Sunday is 0, Saturday is 6) */
 export type DataCommandDatetimeDay = DataCommand & {
   __commandName: 'DATETIME_DAY'
   inputs?: Array<
@@ -64,7 +64,7 @@ export type DataCommandDatetimeMinute = DataCommand & {
   outputs?: Array<DataCalcOutput<'result'> /* target: number */>
 }
 
-/* Month — Get month (January is 1) */
+/* Month — Get month (0-based: January is 0, December is 11) */
 export type DataCommandDatetimeMonth = DataCommand & {
   __commandName: 'DATETIME_MONTH'
   inputs?: Array<

package/utils/__tests__/calc.test.js

@@ -0,0 +1,25 @@
+import { generateDataCalculationMapEditorInfo } from '../calc'
+
+describe('generateDataCalculationMapEditorInfo', () => {
+  test('indexes source nodes while resolving array input connections', () => {
+    const firstSource = { id: 'PROPERTY_BANK_DATA_NODE_first', title: 'First source' }
+    const secondSource = { id: 'PROPERTY_BANK_DATA_NODE_second', title: 'Second source' }
+    const command = {
+      id: 'PROPERTY_BANK_COMMAND_NODE_merge',
+      title: 'Merge values',
+      inputs: [
+        [
+          { id: firstSource.id, port: 'value' },
+          { id: secondSource.id, port: 'value' },
+          { id: 'PROPERTY_BANK_DATA_NODE_missing', port: 'value' },
+        ],
+      ],
+      outputs: [[{ id: firstSource.id, port: 'value' }]],
+    }
+
+    const editorInfo = generateDataCalculationMapEditorInfo([firstSource, secondSource, command])
+    const commandInfo = editorInfo.find((info) => info.node === command)
+
+    expect(commandInfo?.position.x).toBe(615)
+  })
+})

package/utils/calc.ts

@@ -28,6 +28,10 @@ export const generateDataCalculationMapEditorInfo = (
     DataCalculationData | DataCommand,
     Set<DataCalculationData | DataCommand>
   >()
+  const nodeById = new Map<string, DataCalculationData | DataCommand>()
+  for (const node of nodes) {
+    if ('id' in node) nodeById.set(node.id, node)
+  }
 
   // Analyze node connections
   nodes.forEach((node) => {
@@ -48,7 +52,7 @@ export const generateDataCalculationMapEditorInfo = (
             if (!connectedTo.has(node)) {
               connectedTo.set(node, new Set())
             }
-            const sourceNode = nodes.find((n) => 'id' in n && n.id === conn.id)
+            const sourceNode = nodeById.get(conn.id)
             if (sourceNode) {
               connectedTo.get(node)!.add(sourceNode)
             }

package/utils/id.ts

@@ -69,63 +69,65 @@ const makeStableUuid = (type: string, alias?: string) => {
   })
 }
 
-// Make stable ids by default; explicit snapshotMode: false preserves the random escape hatch.
-export const makeId = (type: IdType, aliasOrOpts?: string | IdOptions, opts?: IdOptions) => {
-  if (type === 'subspace') {
-    throw new Error('Currently subspace is not supported for ID generation, please use a fixed ID')
-  }
-
-  const alias = typeof aliasOrOpts === 'string' ? aliasOrOpts : undefined
-  const options = typeof aliasOrOpts === 'string' ? opts : (aliasOrOpts ?? opts)
-
-  let prefix = ''
+const idPrefix = (type: IdType): string => {
   switch (type) {
     case 'animation':
-      prefix = 'ANIMATION_'
-      break
+      return 'ANIMATION_'
     case 'brick':
-      prefix = 'BRICK_'
-      break
+      return 'BRICK_'
     case 'dynamic-brick':
-      prefix = 'DYNAMIC_BRICK_'
-      break
+      return 'DYNAMIC_BRICK_'
     case 'canvas':
-      prefix = 'CANVAS_'
-      break
+      return 'CANVAS_'
     case 'generator':
-      prefix = 'GENERATOR_'
-      break
+      return 'GENERATOR_'
     case 'data':
-      prefix = 'PROPERTY_BANK_DATA_NODE_'
-      break
+      return 'PROPERTY_BANK_DATA_NODE_'
     case 'switch':
-      prefix = 'BRICK_STATE_GROUP_'
-      break
+      return 'BRICK_STATE_GROUP_'
     case 'property_bank_command':
-      prefix = 'PROPERTY_BANK_COMMAND_NODE_'
-      break
+      return 'PROPERTY_BANK_COMMAND_NODE_'
     case 'property_bank_calc':
-      prefix = 'PROPERTY_BANK_COMMAND_MAP_'
-      break
+      return 'PROPERTY_BANK_COMMAND_MAP_'
     case 'automation_map':
-      prefix = 'AUTOMATION_MAP_'
-      break
+      return 'AUTOMATION_MAP_'
     case 'test':
-      prefix = 'TEST_'
-      break
+      return 'TEST_'
     case 'test_case':
-      prefix = 'TEST_CASE_'
-      break
+      return 'TEST_CASE_'
     case 'test_var':
-      prefix = 'TEST_VAR_'
-      break
+      return 'TEST_VAR_'
     default:
+      return ''
+  }
+}
+
+// Make stable ids by default; explicit snapshotMode: false preserves the random escape hatch.
+export const makeId = (type: IdType, aliasOrOpts?: string | IdOptions, opts?: IdOptions) => {
+  if (type === 'subspace') {
+    throw new Error('Currently subspace is not supported for ID generation, please use a fixed ID')
   }
 
+  const alias = typeof aliasOrOpts === 'string' ? aliasOrOpts : undefined
+  const options = typeof aliasOrOpts === 'string' ? opts : (aliasOrOpts ?? opts)
+
   const useCountFallback = aliasOrOpts === undefined && opts === undefined
   const id =
     alias !== undefined || options?.snapshotMode || useCountFallback
       ? makeStableUuid(type, alias)
       : uuid()
-  return `${prefix}${id}`
+  return `${idPrefix(type)}${id}`
+}
+
+// Deterministic id derived solely from a caller-supplied seed. Unlike makeId it keeps no
+// global state — no incrementing counter, no alias registry — so the same (type, seed)
+// always maps to the same id on every compile and in any process. Compiled artifacts seed
+// their ids this way (e.g. generateCalulationMap's command nodes, seeded by their calc id +
+// structural role) so unchanged source recompiles byte-identically and editing one calc
+// never shifts another's ids. The seed must be unique within a single config.
+export const makeSeededId = (type: IdType, seed: string) => {
+  if (type === 'subspace') {
+    throw new Error('Currently subspace is not supported for ID generation, please use a fixed ID')
+  }
+  return `${idPrefix(type)}${uuid({ random: hashToRandomBytes([readApplicationId(), type, seed]) })}`
 }