@kudzujs/core 0.8.36 → 0.8.38

package/framework/compiler/descriptor-session.mjs

@@ -3,23 +3,45 @@ import { createComponentAnalysis } from "./analysis/component-analysis.mjs"
 import { knownGlobalNames } from "./analysis/binding-index.mjs"
 import { bindingNames, isFunctionLike, isReferenceIdentifier, isShadowedByParameter, isShadowedIdentifier, unwrapExpression } from "./ast-helpers.mjs"
 import { generateCommandBehavior } from "./codegen/command-codegen.mjs"
-import { assertModuleIRReferences, createModuleIR, registerBinding, registerCommandHandler, registerDerived, registerEffect, registerKeyedBlock, registerModuleHandler } from "./ir/module-ir.mjs"
+import { assertModuleIRReferences, createModuleIR, registerBinding, registerCommandHandler, registerDerived, registerEffect, registerKeyedBlock, registerModuleHandler, registerSignal } from "./ir/module-ir.mjs"
 
 export function createSemanticArtifact(file) {
   return { componentAnalysis: createComponentAnalysis(file), moduleIR: createModuleIR(file) }
 }
 
-export function createDescriptorSession({ semantic, handlerUrl, factory, context, bindingIndex, compileEventCommand, handlerLowering, isPrimitiveLiteral, rejectWorkerConstructions, sourceName = source => source.fileName }) {
+export function createDescriptorSession({ semantic, handlerUrl, factory, context, bindingIndex, compileEventCommand, handlerLowering, isPrimitiveLiteral, rejectWorkerConstructions, stateReferences = () => new Map(), symbolReference, sourceName = source => source.fileName }) {
   const { moduleIR } = semantic
+  moduleIR.symbols = bindingIndex.bindings()
   const nativeHandlers = []
   const effectHandlers = []
   const reactiveBindings = []
   const listExpressions = []
+  const pendingEffects = []
   const clientModules = new Set()
 
+  const signal = (name, node, references, aliases = []) => {
+    let reference = references?.get(name) ?? stateReferences(node).get(name)
+    if (!reference && bindingIndex) {
+      const original = ts.getOriginalNode(node)
+      const names = new Set([name, ...aliases])
+      let symbol = bindingIndex.references(original, original)?.find(entry => names.has(entry.debugName))?.slot
+      if (symbol === undefined) {
+        for (let current = node; current && symbol === undefined; current = current.parent) if (isFunctionLike(current)) {
+          const parameter = current.parameters.map(parameter => bindingIdentifier(parameter.name, names)).find(Boolean)
+          symbol = parameter && bindingIndex.resolveBinding(parameter)?.slot
+          break
+        }
+      }
+      if (symbol !== undefined) reference = { kind: "symbol", symbol }
+    }
+    reference ??= symbolReference?.(name, node, aliases)
+    if (!reference) throw new Error(`ModuleIR state ${JSON.stringify(name)} has no resolved StateRef`)
+    return registerSignal(moduleIR, reference, name).slot
+  }
+
   function compileListExpression(read, expression, item, index, states = new Set(), keyedBlock, indexedBindingIndex) {
     const exportName = `listExpression${listExpressions.length}`
-    listExpressions.push({ exportName, expression, item, index, states, role: "list-expression", keyedBlock, bindingIndex: indexedBindingIndex })
+    listExpressions.push({ exportName, expression, item, index, states, signalRefs: new Map([...states].map(name => [name, signal(name, expression)])), role: "list-expression", keyedBlock, bindingIndex: indexedBindingIndex })
     const arguments_ = [read, factory.createStringLiteral(handlerUrl), factory.createStringLiteral(exportName)]
     if (states.size) arguments_.push(factory.createArrayLiteralExpression([...states].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))))
     return factory.createCallExpression(factory.createIdentifier("__kListExpression"), undefined, arguments_)
@@ -28,7 +50,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
   function compileListConditional(entry) {
     const exportName = `listExpression${listExpressions.length}`
     const indexed = indexedReferences(bindingIndex, entry.condition, entry.condition)
-    listExpressions.push({ exportName, expression: entry.condition, item: entry.item, index: entry.index, role: "list-conditional", keyedBlock: entry.keyedBlock, bindingIndex: indexed ? bindingIndex : undefined })
+    listExpressions.push({ exportName, expression: entry.condition, item: entry.item, index: entry.index, states: new Set(), signalRefs: new Map(), role: "list-conditional", keyedBlock: entry.keyedBlock, bindingIndex: indexed ? bindingIndex : undefined })
     const read = factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), entry.condition)
     const thunk = branch => factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), branch)
     return factory.createCallExpression(factory.createIdentifier("__kListConditional"), undefined, [
@@ -57,9 +79,10 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     const parts = conditionalParts(expression)
     const state = parts && directStateIdentifier(parts.condition, setters, bindingIndex)
     if (state && isPrimitiveLiteral(parts.truthy) && isPrimitiveLiteral(parts.falsy)) {
-      return factory.createCallExpression(factory.createIdentifier("__kSelect"), undefined, [state, parts.truthy, parts.falsy])
+      return { node: factory.createCallExpression(factory.createIdentifier("__kSelect"), undefined, [state, parts.truthy, parts.falsy]) }
     }
-    return factory.createCallExpression(factory.createIdentifier("__kBinding"), undefined, compileReactiveExpression(expression, setters, importBindings, keyedBlock))
+    const binding = reactiveBindings.length
+    return { node: factory.createCallExpression(factory.createIdentifier("__kBinding"), undefined, compileReactiveExpression(expression, setters, importBindings, keyedBlock)), binding }
   }
 
   function compileConditional(kind, expression, truthy, falsy, setters) {
@@ -81,7 +104,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
       ? new Set(indexed.filter(reference => ["capture", "unresolved"].includes(reference.kind) && !setters.has(reference.debugName) && !allStateNames.has(reference.debugName) && !importedNames.has(reference.debugName)).map(reference => reference.debugName))
       : new Set([...captureNames(expression, expression, setters)].filter(name => !importedNames.has(name)))
     const exportName = `binding${reactiveBindings.length}`
-    reactiveBindings.push({ exportName, expression, captures, states: usedStates, imports, role: "binding", keyedBlock, ...(indexed ? { bindingIndex } : {}) })
+    reactiveBindings.push({ slot: reactiveBindings.length, exportName, expression, captures, states: usedStates, signalRefs: new Map([...usedStates].map(name => [name, signal(name, expression)])), imports, role: "binding", keyedBlock, ...(indexed ? { bindingIndex } : {}) })
     const states = [...usedStates].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))
     const scope = [...captures].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), factory.createIdentifier(name)]))
     const stateNames = new Set(usedStates)
@@ -107,7 +130,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     const optimized = referencedReducerDispatches(expression.body, reducers, expression).size ? undefined : compileOptimizedEvent(expression, setters, stateOwners, owner, keyedBlock)
     if (optimized) return optimized
     rejectWorkerConstructions(expression)
-    const descriptor = compileNativeCallback(expression, { setters, reducers, entries: nativeHandlers, importBindings, prefix: "handler", role: "native", listItem, keyedBlock })
+    const descriptor = compileNativeCallback(expression, { setters, reducers, entries: nativeHandlers, importBindings, prefix: "handler", role: "native", listItem, keyedBlock, stateOwners })
     return factory.createCallExpression(factory.createIdentifier("__kNativeBehavior"), undefined, [
       factory.createStringLiteral(handlerUrl), factory.createStringLiteral(descriptor.exportName), descriptor.states, descriptor.scope
     ])
@@ -117,7 +140,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     return compileNativeCallback(expression, { ...options, entries: effectHandlers, prefix: "effect", role: "effect" })
   }
 
-  function compileNativeCallback(expression, { setters, reducers, entries, importBindings, prefix, role, listItem, keyedBlock, deferValues = false, snapshotNested = false, liveStates = new Set() }) {
+  function compileNativeCallback(expression, { setters, reducers, entries, importBindings, prefix, role, listItem, keyedBlock, stateOwners, deferValues = false, snapshotNested = false, liveStates = new Set() }) {
     const indexedBindingIndex = indexedReferences(bindingIndex, expression, expression) ? bindingIndex : undefined
     const allCaptures = nativeCaptureNames(expression, setters, indexedBindingIndex)
     const usedReducers = referencedReducerDispatches(expression.body, reducers, expression, indexedBindingIndex)
@@ -131,11 +154,13 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
       if (reducer.contextAction) for (const state of referencedStateNames(reducer.contextAction.body, reducer.states, reducer.contextAction, bindingIndex)) usedStates.add(state)
     }
     const exportName = `${prefix}${entries.length}`
-    entries.push({ exportName, expression, captures, deferValues, imports, listItem, keyedBlock, liveStates, role, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))), reducers: new Map([...reducers].filter(([name]) => usedReducers.has(name))), snapshotNested, usedStates, bindingIndex: indexedBindingIndex })
+    const entry = { exportName, expression, captures, deferValues, imports, listItem, keyedBlock, liveStates, role, setters: new Map([...setters].filter(([, state]) => usedStates.has(state))), reducers: new Map([...reducers].filter(([name]) => usedReducers.has(name))), snapshotNested, usedStates, signalRefs: new Map([...usedStates].map(name => [name, signal(name, expression, stateOwners, [...setters].filter(([, state]) => state === name).map(([setter]) => setter))])), bindingIndex: indexedBindingIndex }
+    entries.push(entry)
     const value = name => deferValues
       ? factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), factory.createIdentifier(name))
       : factory.createIdentifier(name)
     return {
+      entry,
       exportName,
       states: factory.createArrayLiteralExpression([...usedStates].map(name => factory.createArrayLiteralExpression([factory.createStringLiteral(name), value(name)]))),
       scope: factory.createArrayLiteralExpression([...captures].map(name => factory.createArrayLiteralExpression([
@@ -154,7 +179,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
     if (!commands?.length || commands.some(command => !command)) return undefined
     const original = ts.getOriginalNode(expression)
     const source = original.pos >= 0 && original.end >= 0 ? { file: sourceName(original.getSourceFile()), start: original.getStart(), end: original.end } : undefined
-    const handler = registerCommandHandler(moduleIR, commands.map(command => ({ ...command, owner: stateOwners.get(command.state) ?? owner })), source, owner)
+    const handler = registerCommandHandler(moduleIR, commands.map(command => ({ ...command, reference: stateOwners.get(command.state) ?? stateReferences(expression).get(command.state) })), source)
     if (keyedBlock !== undefined) handler.keyedBlock = keyedBlock
     return generateCommandBehavior(moduleIR, handler, factory)
   }
@@ -176,7 +201,7 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
 
   function registerDerivedResult(kind, value, states = [], node) {
     const normalized = JSON.parse(JSON.stringify(value))
-    return registerDerived(moduleIR, { kind, [kind]: normalized, states: [...states], ...(source(node) ? { source: source(node) } : {}) })
+    return registerDerived(moduleIR, { kind, [kind]: normalized, signals: [...states].map(name => signal(name, node)), ...(source(node) ? { source: source(node) } : {}) })
   }
 
   function registerKeyedBlockResult(descriptor) {
@@ -184,68 +209,79 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
   }
 
   function registerEffectResult(handler, descriptor) {
-    return registerEffect(moduleIR, { ...descriptor, setup: { exportName: handler.exportName } })
+    const effect = { ...descriptor, setup: handler }
+    pendingEffects.push(effect)
+    return effect
   }
 
   function finalize() {
     const callbacks = [...nativeHandlers, ...effectHandlers]
+    const imports = [...callbacks, ...reactiveBindings].flatMap(entry => entry.imports ?? []).map(importRecord)
+    moduleIR.imports = [...new Map(imports.map(entry => [`${entry.target}:${entry.kind}:${entry.imported ?? ""}:${entry.local}`, entry])).values()].map((entry, slot) => ({ slot, ...entry }))
+    const importSlots = new Map(moduleIR.imports.map(entry => [`${entry.target}:${entry.kind}:${entry.imported ?? ""}:${entry.local}`, entry.slot]))
+    const importSlot = entry => importSlots.get(`${entry.target}:${entry.kind}:${entry.imported ?? ""}:${entry.local}`)
     for (const entry of callbacks) {
       const lowered = handlerLowering.lowerNativeHandler(entry)
       const setters = Map.groupBy(entry.setters, ([, state]) => state)
-      registerModuleHandler(moduleIR, {
+      entry.handler = registerModuleHandler(moduleIR, {
         role: entry.role,
         ...(entry.keyedBlock !== undefined ? { keyedBlock: entry.keyedBlock } : {}),
         exportName: entry.exportName,
         async: Boolean(entry.expression.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword)),
         generator: Boolean(entry.expression.asteriskToken),
         signals: [...entry.usedStates].map(name => ({
+          signal: entry.signalRefs.get(name),
           name,
           setters: (setters.get(name) ?? []).map(([setter]) => setter),
           value: entry.deferValues ? "deferred" : "direct",
           snapshot: lowered.stateSnapshots.includes(name)
         })),
         captures: [...entry.captures].map(name => ({
+          ...(symbolSlot(entry, name) !== undefined ? { symbol: symbolSlot(entry, name) } : {}),
           name,
           source: name === (typeof entry.listItem === "string" ? entry.listItem : entry.listItem?.item) ? "list-item" : name === entry.listItem?.index ? "list-index" : "scope",
           value: entry.deferValues ? "deferred" : "direct",
           snapshot: lowered.captureSnapshots.includes(name)
         })),
-        imports: entry.imports.map(importRecord),
+        imports: entry.imports.map(entry => importSlot(importRecord(entry))),
         code: lowered.code,
         ...(source(entry.expression) ? { source: source(entry.expression) } : {})
       })
     }
     for (const entry of reactiveBindings) registerBinding(moduleIR, {
+      slot: entry.slot,
       role: entry.role,
       ...(entry.keyedBlock !== undefined ? { keyedBlock: entry.keyedBlock } : {}),
       exportName: entry.exportName,
       parameters: ["__k"],
-      states: [...entry.states],
-      captures: [...entry.captures].map(name => ({ name, source: "scope" })),
-      imports: entry.imports.map(importRecord),
+      signals: [...entry.states].map(name => entry.signalRefs.get(name)),
+      captures: [...entry.captures].map(name => ({ ...(symbolSlot(entry, name) !== undefined ? { symbol: symbolSlot(entry, name) } : {}), name, source: "scope" })),
+      imports: entry.imports.map(entry => importSlot(importRecord(entry))),
       code: handlerLowering.lowerReactiveBinding(entry),
       ...(source(entry.expression) ? { source: source(entry.expression) } : {})
     })
-    for (const entry of listExpressions) registerBinding(moduleIR, {
+    for (const [index, entry] of listExpressions.entries()) registerBinding(moduleIR, {
+      slot: reactiveBindings.length + index,
       role: entry.role,
       ...(entry.keyedBlock !== undefined ? { keyedBlock: entry.keyedBlock } : {}),
       exportName: entry.exportName,
       parameters: [entry.item, entry.index ?? "__kIndex", "__k"],
-      states: [...(entry.states ?? [])],
+      signals: [...(entry.states ?? [])].map(name => entry.signalRefs.get(name)),
       captures: [],
       imports: [],
       code: handlerLowering.lowerListExpression(entry),
       ...(source(entry.expression) ? { source: source(entry.expression) } : {})
     })
-    for (const effect of moduleIR.effects) {
-      const handler = moduleIR.handlers.find(candidate => candidate.kind === "module-export" && candidate.role === "effect" && candidate.exportName === effect.setup.exportName)
-      if (!handler) throw new Error(`Effect handler ${JSON.stringify(effect.setup.exportName)} was not finalized`)
-      effect.setup = { handler: handler.slot }
+    for (const effect of pendingEffects) {
+      if (!effect.setup.entry.handler) throw new Error(`Effect handler ${JSON.stringify(effect.setup.exportName)} was not finalized`)
+      registerEffect(moduleIR, { ...effect, setup: { handler: effect.setup.entry.handler.slot } })
     }
-    const imports = [...callbacks, ...reactiveBindings].flatMap(entry => entry.imports ?? []).map(importRecord)
-    moduleIR.imports = [...new Map(imports.map(entry => [`${entry.target}:${entry.kind}:${entry.imported ?? ""}:${entry.local}`, entry])).values()]
     moduleIR.clientModules = [...clientModules]
-    assertModuleIRReferences(moduleIR)
+    assertModuleIRReferences(moduleIR, semantic.componentAnalysis)
+  }
+
+  function symbolSlot(entry, name) {
+    return entry.bindingIndex?.references(entry.expression, entry.expression)?.find(reference => reference.debugName === name)?.slot
   }
 
   function source(node) {
@@ -256,7 +292,15 @@ export function createDescriptorSession({ semantic, handlerUrl, factory, context
 
   const importRecord = entry => ({ target: entry.target, kind: entry.kind, local: entry.local, ...(entry.imported ? { imported: entry.imported } : {}), package: Boolean(entry.package) })
 
-  return { compileConditional, compileEffectCallback, compileEvent, compileListConditional, compileListValue, compileReactiveBinding, finalize, registerDerived: registerDerivedResult, registerEffect: registerEffectResult, registerKeyedBlock: registerKeyedBlockResult }
+  return { compileConditional, compileEffectCallback, compileEvent, compileListConditional, compileListValue, compileReactiveBinding, finalize, registerDerived: registerDerivedResult, registerEffect: registerEffectResult, registerKeyedBlock: registerKeyedBlockResult, signal }
+}
+
+function bindingIdentifier(name, names) {
+  if (ts.isIdentifier(name)) return names.has(name.text) ? name : undefined
+  for (const element of name.elements) if (ts.isBindingElement(element)) {
+    const identifier = bindingIdentifier(element.name, names)
+    if (identifier) return identifier
+  }
 }
 
 function directStateIdentifier(expression, setters, bindingIndex) {

package/framework/compiler/ir/module-ir.mjs

@@ -1,48 +1,159 @@
 export function createModuleIR(file) {
-  return { version: 1, file, signals: [], handlers: [], bindings: [], derived: [], effects: [], keyedBlocks: [], imports: [], clientModules: [] }
+  return { version: 2, file, symbols: [], signals: [], handlers: [], bindings: [], derived: [], effects: [], keyedBlocks: [], imports: [], clientModules: [] }
 }
 
-export function assertModuleIRReferences(moduleIR) {
-  const slot = (records, value, label) => {
-    if (!Number.isInteger(value) || value < 0 || value >= records.length) throw new Error(`ModuleIR ${label} references missing slot ${JSON.stringify(value)}`)
+export function assertModuleIRReferences(moduleIR, componentAnalysis) {
+  if (moduleIR?.version !== 2) throw new Error(`Unsupported ModuleIR version: ${JSON.stringify(moduleIR?.version)}`)
+  if (componentAnalysis && componentAnalysis.version !== 2) throw new Error(`Unsupported ComponentAnalysis version: ${JSON.stringify(componentAnalysis.version)}`)
+  const slot = (records, value, label, kind) => {
+    if (!Number.isInteger(value) || value < 0 || value >= records.length) throw new Error(`${label} references missing ${kind} slot ${JSON.stringify(value)}`)
+    return records[value]
   }
-  for (const [name, records] of [["signal", moduleIR.signals], ["handler", moduleIR.handlers], ["binding", moduleIR.bindings], ["derived", moduleIR.derived], ["effect", moduleIR.effects], ["keyed block", moduleIR.keyedBlocks]]) {
+  const indexed = (name, records) => {
     records.forEach((record, index) => {
-      if (record.slot !== index) throw new Error(`ModuleIR ${name} slot ${JSON.stringify(record.slot)} must equal its index ${index}`)
+      if (record.slot !== index) throw new Error(`${name} slot ${JSON.stringify(record.slot)} must equal its index ${index}`)
     })
   }
+  indexed("SymbolRef", moduleIR.symbols)
+  indexed("SignalIR", moduleIR.signals)
+  indexed("HandlerIR", moduleIR.handlers)
+  indexed("BindingIR", moduleIR.bindings)
+  indexed("DerivedIR", moduleIR.derived)
+  indexed("EffectIR", moduleIR.effects)
+  indexed("KeyedBlockIR", moduleIR.keyedBlocks)
+  indexed("ImportIR", moduleIR.imports)
+  if (componentAnalysis) {
+    indexed("Component owner", componentAnalysis.owners)
+    indexed("Component specialization", componentAnalysis.specializations)
+    for (const owner of componentAnalysis.owners) {
+      indexed(`Component owner ${owner.slot} state`, owner.states)
+      indexed(`Component owner ${owner.slot} ref`, owner.refs)
+      indexed(`Component owner ${owner.slot} ID`, owner.ids)
+      for (const setter of owner.setters) slot(owner.states, setter.signal, `Component owner ${owner.slot} setter ${JSON.stringify(setter.name)}`, "state")
+      for (const state of owner.states) if (state.owner !== undefined) ownerRef(state.owner, `Component owner ${owner.slot} state ${state.slot} external owner`)
+    }
+    for (const specialization of componentAnalysis.specializations) {
+      indexed(`Component specialization ${specialization.slot} state`, specialization.states)
+      indexed(`Component specialization ${specialization.slot} ref`, specialization.refs)
+      indexed(`Component specialization ${specialization.slot} ID`, specialization.ids)
+      if (specialization.owner !== undefined) ownerRef(specialization.owner, `Component specialization ${specialization.slot} owner`)
+      for (const prop of specialization.props ?? []) for (const signal of prop.signals ?? []) slot(moduleIR.signals, signal, `Component specialization ${specialization.slot} prop ${JSON.stringify(prop.name)}`, "SignalIR")
+    }
+  }
+  function moduleSymbol(symbol, label) {
+    if (!symbol || typeof symbol.id !== "string" || typeof symbol.module !== "string" || typeof symbol.site !== "string" || typeof symbol.name !== "string") throw new Error(`${label} must be a ModuleSymbol`)
+  }
+  function ownerRef(reference, label) {
+    if (!reference || typeof reference !== "object") throw new Error(`${label} must be an OwnerRef`)
+    if (reference.kind === "component") return slot(componentAnalysis?.owners ?? [], reference.slot, label, "component owner")
+    if (reference.kind === "specialization") return slot(componentAnalysis?.specializations ?? [], reference.slot, label, "component specialization")
+    if (reference.kind === "module-symbol") return moduleSymbol(reference.symbol, label)
+    if (reference.kind !== "module") throw new Error(`${label} has invalid kind ${JSON.stringify(reference.kind)}`)
+  }
+  function stateRef(reference, label) {
+    if (!reference || typeof reference !== "object") throw new Error(`${label} must be a StateRef`)
+    if (reference.kind === "module-symbol") return moduleSymbol(reference.symbol, label)
+    if (reference.kind === "symbol") return slot(moduleIR.symbols, reference.symbol, label, "SymbolRef")
+    if (reference.kind !== "state") throw new Error(`${label} has invalid kind ${JSON.stringify(reference.kind)}`)
+    const owner = ownerRef(reference.owner, `${label} owner`)
+    const states = reference.owner.kind === "component" || reference.owner.kind === "specialization" ? owner.states : []
+    slot(states, reference.slot, label, "owner state")
+  }
+  const exports = new Map()
+  const exported = (record, label) => {
+    if (record.kind !== "module-export") return
+    if (typeof record.exportName !== "string" || !record.exportName) throw new Error(`${label} requires an export name`)
+    const previous = exports.get(record.exportName)
+    if (previous) throw new Error(`ModuleIR export ${JSON.stringify(record.exportName)} is declared by both ${previous} and ${label}`)
+    exports.set(record.exportName, label)
+  }
+  for (const signal of moduleIR.signals) stateRef(signal.reference, `SignalIR ${signal.slot}`)
   for (const handler of moduleIR.handlers) {
-    for (const command of handler.commands ?? []) slot(moduleIR.signals, command.signal, `handler ${handler.slot} command signal`)
-    if (handler.keyedBlock !== undefined) slot(moduleIR.keyedBlocks, handler.keyedBlock, `handler ${handler.slot} keyed block`)
+    exported(handler, `HandlerIR ${handler.slot}`)
+    for (const [index, command] of (handler.commands ?? []).entries()) slot(moduleIR.signals, command.signal, `HandlerIR ${handler.slot} command ${index}`, "SignalIR")
+    for (const [index, signal] of (handler.signals ?? []).entries()) slot(moduleIR.signals, signal.signal, `HandlerIR ${handler.slot} signal ${index}`, "SignalIR")
+    for (const [index, imported] of (handler.imports ?? []).entries()) slot(moduleIR.imports, imported, `HandlerIR ${handler.slot} import ${index}`, "ImportIR")
+    for (const [index, capture] of (handler.captures ?? []).entries()) if (capture.symbol !== undefined) slot(moduleIR.symbols, capture.symbol, `HandlerIR ${handler.slot} capture ${index}`, "SymbolRef")
+    if (handler.keyedBlock !== undefined) slot(moduleIR.keyedBlocks, handler.keyedBlock, `HandlerIR ${handler.slot} keyed block`, "KeyedBlockIR")
   }
-  for (const binding of moduleIR.bindings) if (binding.keyedBlock !== undefined) slot(moduleIR.keyedBlocks, binding.keyedBlock, `binding ${binding.slot} keyed block`)
+  for (const binding of moduleIR.bindings) {
+    exported(binding, `BindingIR ${binding.slot}`)
+    for (const [index, signal] of (binding.signals ?? []).entries()) slot(moduleIR.signals, signal, `BindingIR ${binding.slot} signal ${index}`, "SignalIR")
+    for (const [index, imported] of (binding.imports ?? []).entries()) slot(moduleIR.imports, imported, `BindingIR ${binding.slot} import ${index}`, "ImportIR")
+    for (const [index, capture] of (binding.captures ?? []).entries()) if (capture.symbol !== undefined) slot(moduleIR.symbols, capture.symbol, `BindingIR ${binding.slot} capture ${index}`, "SymbolRef")
+    if (binding.keyedBlock !== undefined) slot(moduleIR.keyedBlocks, binding.keyedBlock, `BindingIR ${binding.slot} keyed block`, "KeyedBlockIR")
+  }
+  for (const derived of moduleIR.derived) for (const [index, signal] of (derived.signals ?? []).entries()) slot(moduleIR.signals, signal, `DerivedIR ${derived.slot} signal ${index}`, "SignalIR")
   for (const effect of moduleIR.effects) {
-    slot(moduleIR.handlers, effect.setup?.handler, `effect ${effect.slot} setup handler`)
-    for (const dependency of effect.dependencies ?? []) if (dependency.kind === "derived") slot(moduleIR.derived, dependency.derived, `effect ${effect.slot} derived dependency`)
-    if (effect.ownership?.keyedBlock !== undefined) slot(moduleIR.keyedBlocks, effect.ownership.keyedBlock, `effect ${effect.slot} keyed block`)
+    const handler = slot(moduleIR.handlers, effect.setup?.handler, `EffectIR ${effect.slot} setup`, "HandlerIR")
+    if (handler.kind !== "module-export" || handler.role !== "effect") throw new Error(`EffectIR ${effect.slot} setup HandlerIR ${handler.slot} must have role "effect"`)
+    for (const [index, dependency] of (effect.dependencies ?? []).entries()) {
+      if (dependency.kind === "signal") slot(moduleIR.signals, dependency.signal, `EffectIR ${effect.slot} dependency ${index}`, "SignalIR")
+      else if (dependency.kind === "derived") {
+        slot(moduleIR.derived, dependency.derived, `EffectIR ${effect.slot} dependency ${index}`, "DerivedIR")
+        for (const [sourceIndex, signal] of (dependency.sources ?? []).entries()) slot(moduleIR.signals, signal, `EffectIR ${effect.slot} dependency ${index} source ${sourceIndex}`, "SignalIR")
+      } else throw new Error(`EffectIR ${effect.slot} dependency ${index} has invalid kind ${JSON.stringify(dependency.kind)}`)
+    }
+    for (const [index, signal] of (effect.subscriptions ?? []).entries()) slot(moduleIR.signals, signal, `EffectIR ${effect.slot} subscription ${index}`, "SignalIR")
+    for (const [index, signal] of (effect.dependencySignals ?? []).entries()) slot(moduleIR.signals, signal, `EffectIR ${effect.slot} dependency signal ${index}`, "SignalIR")
+    if (effect.ownership?.owner) ownerRef(effect.ownership.owner, `EffectIR ${effect.slot} ownership`)
+    if (effect.ownership?.keyedBlock !== undefined) {
+      slot(moduleIR.keyedBlocks, effect.ownership.keyedBlock, `EffectIR ${effect.slot} ownership`, "KeyedBlockIR")
+      if (handler.keyedBlock !== effect.ownership.keyedBlock) throw new Error(`EffectIR ${effect.slot} and HandlerIR ${handler.slot} must reference the same KeyedBlockIR`)
+    }
   }
   for (const block of moduleIR.keyedBlocks) {
-    if (block.parent !== undefined) slot(moduleIR.keyedBlocks, block.parent, `keyed block ${block.slot} parent`)
-    for (const child of block.children ?? []) slot(moduleIR.keyedBlocks, child, `keyed block ${block.slot} child`)
-    if (block.selector !== undefined) slot(moduleIR.derived, block.selector, `keyed block ${block.slot} selector`)
+    if (block.collection?.kind === "signal") slot(moduleIR.signals, block.collection.signal, `KeyedBlockIR ${block.slot} collection`, "SignalIR")
+    else if (block.collection?.kind === "binding") slot(moduleIR.bindings, block.collection.binding, `KeyedBlockIR ${block.slot} collection`, "BindingIR")
+    else if (block.collection?.kind === "symbol") slot(moduleIR.symbols, block.collection.symbol, `KeyedBlockIR ${block.slot} collection`, "SymbolRef")
+    else if (block.collection?.kind !== "static") throw new Error(`KeyedBlockIR ${block.slot} collection has invalid kind ${JSON.stringify(block.collection?.kind)}`)
+    if (block.parent !== undefined) {
+      const parent = slot(moduleIR.keyedBlocks, block.parent, `KeyedBlockIR ${block.slot} parent`, "KeyedBlockIR")
+      if (!(parent.children ?? []).includes(block.slot)) throw new Error(`KeyedBlockIR ${block.slot} parent ${parent.slot} does not reciprocally list child ${block.slot}`)
+    }
+    for (const childSlot of block.children ?? []) {
+      const child = slot(moduleIR.keyedBlocks, childSlot, `KeyedBlockIR ${block.slot} child`, "KeyedBlockIR")
+      if (child.parent !== block.slot) throw new Error(`KeyedBlockIR ${block.slot} child ${child.slot} does not reciprocally reference parent ${block.slot}`)
+    }
+    if (new Set(block.children ?? []).size !== (block.children ?? []).length) throw new Error(`KeyedBlockIR ${block.slot} has duplicate children`)
+    if (block.selector !== undefined) slot(moduleIR.derived, block.selector, `KeyedBlockIR ${block.slot} selector`, "DerivedIR")
+    for (const [index, signal] of (block.selectorSignals ?? []).entries()) slot(moduleIR.signals, signal, `KeyedBlockIR ${block.slot} selector signal ${index}`, "SignalIR")
+    for (const [index, specialization] of (block.specializations ?? []).entries()) slot(componentAnalysis?.specializations ?? [], specialization, `KeyedBlockIR ${block.slot} specialization ${index}`, "component specialization")
+    for (const [index, row] of (block.rowStates ?? []).entries()) slot(moduleIR.signals, row.signal, `KeyedBlockIR ${block.slot} row state ${index}`, "SignalIR")
+    for (const [index, row] of (block.rowRefs ?? []).entries()) {
+      const specialization = slot(componentAnalysis?.specializations ?? [], row.specialization, `KeyedBlockIR ${block.slot} row ref ${index}`, "component specialization")
+      slot(specialization.refs, row.ref, `KeyedBlockIR ${block.slot} row ref ${index}`, "specialization ref")
+    }
+  }
+  const visiting = new Set()
+  const visited = new Set()
+  const visit = (block, trail) => {
+    if (visiting.has(block.slot)) throw new Error(`KeyedBlockIR parent cycle: ${[...trail, block.slot].join(" -> ")}`)
+    if (visited.has(block.slot)) return
+    visiting.add(block.slot)
+    if (block.parent !== undefined) visit(moduleIR.keyedBlocks[block.parent], [...trail, block.slot])
+    visiting.delete(block.slot)
+    visited.add(block.slot)
   }
+  for (const block of moduleIR.keyedBlocks) visit(block, [])
   return moduleIR
 }
 
-export function registerCommandHandler(moduleIR, commands, source, scope = "module") {
-  const slots = new Map(moduleIR.signals.map(signal => [signal.key, signal.slot]))
-  for (const { state, owner = scope } of commands) {
-    const key = `${owner}:${state}`
-    if (slots.has(key)) continue
-    const slot = moduleIR.signals.length
-    slots.set(key, slot)
-    moduleIR.signals.push({ slot, key, debugName: state })
+export function registerSignal(moduleIR, reference, debugName) {
+  const key = JSON.stringify(reference)
+  let signal = moduleIR.signals.find(entry => JSON.stringify(entry.reference) === key)
+  if (!signal) {
+    signal = { slot: moduleIR.signals.length, reference, debugName }
+    moduleIR.signals.push(signal)
   }
-  const signal = command => slots.get(`${command.owner ?? scope}:${command.state}`)
+  return signal
+}
+
+export function registerCommandHandler(moduleIR, commands, source) {
   const handler = {
     slot: moduleIR.handlers.length,
     kind: "commands",
-    commands: commands.map(({ operation, state, owner, value, syntax }) => ({ operation, signal: signal({ state, owner }), value, ...(syntax ? { syntax } : {}) })),
+    commands: commands.map(({ operation, reference, state, value, syntax }) => ({ operation, signal: registerSignal(moduleIR, reference, state).slot, value, ...(syntax ? { syntax } : {}) })),
     ...(source ? { source } : {})
   }
   moduleIR.handlers.push(handler)
@@ -50,31 +161,31 @@ export function registerCommandHandler(moduleIR, commands, source, scope = "modu
 }
 
 export function registerModuleHandler(moduleIR, descriptor) {
-  const handler = { slot: moduleIR.handlers.length, kind: "module-export", ...descriptor }
+  const handler = { ...descriptor, slot: moduleIR.handlers.length, kind: "module-export" }
   moduleIR.handlers.push(handler)
   return handler
 }
 
 export function registerBinding(moduleIR, descriptor) {
-  const binding = { slot: moduleIR.bindings.length, kind: "module-export", ...descriptor }
+  const binding = { ...descriptor, slot: moduleIR.bindings.length, kind: "module-export" }
   moduleIR.bindings.push(binding)
   return binding
 }
 
 export function registerDerived(moduleIR, descriptor) {
-  const derived = { slot: moduleIR.derived.length, ...descriptor }
+  const derived = { ...descriptor, slot: moduleIR.derived.length }
   moduleIR.derived.push(derived)
   return derived
 }
 
 export function registerEffect(moduleIR, descriptor) {
-  const effect = { slot: moduleIR.effects.length, ...descriptor }
+  const effect = { ...descriptor, slot: moduleIR.effects.length }
   moduleIR.effects.push(effect)
   return effect
 }
 
 export function registerKeyedBlock(moduleIR, descriptor) {
-  const block = { slot: moduleIR.keyedBlocks.length, ...descriptor }
+  const block = { ...descriptor, slot: moduleIR.keyedBlocks.length }
   moduleIR.keyedBlocks.push(block)
   return block
 }

package/framework/compiler/route-build-record.mjs

@@ -0,0 +1,81 @@
+export function createRouteBuildRecord(input) {
+  const record = {
+    version: input.version ?? 1,
+    route: input.route,
+    output: input.output,
+    html: input.html,
+    plan: input.plan,
+    capabilities: input.capabilities,
+    artifacts: {
+      handlers: input.handlerReferences ?? [],
+      effects: (input.plan?.effects ?? []).map(({ module, handler }) => ({ module, handler })),
+      styles: [...new Set(input.styles ?? [])]
+    },
+    entries: input.entries ?? {},
+    ...(input.runtimeSchema ? { runtimeSchema: input.runtimeSchema } : {})
+  }
+  return assertRouteBuildRecord(record)
+}
+
+export function assertRouteBuildRecord(record) {
+  if (record?.version !== 1) throw new Error(`Unsupported RouteBuildRecord version: ${JSON.stringify(record?.version)}`)
+  if (typeof record.route !== "string" || typeof record.output !== "string" || typeof record.html !== "string" || !isRecord(record.plan)) throw new Error("Invalid RouteBuildRecord v1 structure")
+  if (record.plan.route !== record.route) throw new Error(`RouteBuildRecord route ${JSON.stringify(record.route)} does not match RouteIR route ${JSON.stringify(record.plan.route)}`)
+  const capabilityNames = ["navigable", "usesDependencyRuntime", "hasBehaviors", "hasBindings", "hasLists", "hasListStyles", "hasStateSeed", "hasParams", "hasEffects"]
+  if (!isRecord(record.capabilities) || !capabilityNames.every(name => typeof record.capabilities[name] === "boolean")) throw new Error("Invalid RouteBuildRecord v1 capabilities")
+  if (!isRecord(record.artifacts) || !Array.isArray(record.artifacts.handlers) || !Array.isArray(record.artifacts.effects) || !Array.isArray(record.artifacts.styles) || !isRecord(record.entries)) throw new Error("Invalid RouteBuildRecord v1 artifacts")
+  const handlers = new Set()
+  for (const reference of record.artifacts.handlers) {
+    assertHandlerReference(reference)
+    const key = referenceKey(reference)
+    if (handlers.has(key)) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} has duplicate handler reference ${key}`)
+    handlers.add(key)
+  }
+  for (const effect of record.artifacts.effects) {
+    assertHandlerReference(effect)
+    if (!handlers.has(referenceKey(effect))) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} effect references an unretained handler ${referenceKey(effect)}`)
+  }
+  for (const event of record.plan.events ?? []) if (event.native && !handlers.has(referenceKey(event.native))) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} event references an unretained handler ${referenceKey(event.native)}`)
+  for (const descriptor of [...(record.plan.bindings ?? []), ...(record.plan.conditions ?? []), ...(record.plan.lists ?? []).map(list => list.source).filter(Boolean)]) {
+    if (descriptor.module && !handlers.has(referenceKey(descriptor))) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} descriptor references an unretained handler ${referenceKey(descriptor)}`)
+  }
+  if (record.artifacts.styles.some(style => typeof style !== "string")) throw new Error("RouteBuildRecord styles must be strings")
+  for (const [kind, path] of Object.entries(record.entries)) if (!["effect", "native", "param"].includes(kind) || typeof path !== "string") throw new Error(`Invalid RouteBuildRecord entry ${JSON.stringify(kind)}`)
+  if (record.runtimeSchema !== undefined && !isRecord(record.runtimeSchema)) throw new Error("Invalid RouteBuildRecord runtime schema")
+  const hasNative = (record.plan.events ?? []).some(event => event.native)
+  if (Boolean(record.entries.effect) !== record.capabilities.hasEffects || record.capabilities.hasEffects !== Boolean(record.plan.effects?.length)) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} has inconsistent effect artifacts`)
+  if (Boolean(record.entries.native) !== hasNative) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} has inconsistent native artifacts`)
+  if (Boolean(record.entries.param) !== record.capabilities.hasParams) throw new Error(`RouteBuildRecord ${JSON.stringify(record.route)} has inconsistent parameter artifacts`)
+  return record
+}
+
+export function planRouteArtifacts(records, handlerModules, workerReferences, moduleUrl) {
+  for (const record of records) assertRouteBuildRecord(record)
+  const modules = new Map()
+  for (const module of handlerModules) {
+    const url = moduleUrl(module)
+    if (modules.has(url)) throw new Error(`Duplicate compiled handler module: ${url}`)
+    modules.set(url, module)
+  }
+  const retainedUrls = new Set(records.flatMap(record => record.artifacts.handlers.map(reference => reference.module)))
+  for (const url of retainedUrls) if (!modules.has(url)) throw new Error(`Handler module was not compiled: ${url}`)
+  const effects = new Map()
+  for (const reference of records.flatMap(record => record.artifacts.effects)) {
+    const handlers = effects.get(reference.module) ?? new Set()
+    handlers.add(reference.handler)
+    effects.set(reference.module, handlers)
+  }
+  return {
+    handlerModules: handlerModules.filter(module => retainedUrls.has(moduleUrl(module))),
+    workerReferences: workerReferences.filter(reference => effects.get(reference.module)?.has(reference.handler)),
+    styles: [...new Set(records.flatMap(record => record.artifacts.styles))]
+  }
+}
+
+const isRecord = value => value !== null && typeof value === "object" && !Array.isArray(value)
+
+function assertHandlerReference(reference) {
+  if (!isRecord(reference) || typeof reference.module !== "string" || !reference.module || typeof reference.handler !== "string" || !reference.handler) throw new Error("RouteBuildRecord handler references require module and handler strings")
+}
+
+const referenceKey = reference => `${JSON.stringify(reference.module)}#${JSON.stringify(reference.handler)}`

package/framework/compiler/route-capability-planner.mjs

@@ -4,7 +4,9 @@ export function usesRouteDependencyRuntime({ plan, navigable, hasBindings, hasLi
   return !navigable && hasDependencies && !plan.effects.some(effect => effect.owner) && !hasBindings && !hasLists && !plan.events.some(event => event.native)
 }
 
-export function planRouteCapabilities(plans, { routes = new Map(), navigationRouteCount = 0 } = {}) {
+export function planRouteCapabilities(records, { navigationRouteCount = 0 } = {}) {
+  for (const record of records) assertRouteBuildRecord(record)
+  const plans = records.map(record => record.plan)
   for (const plan of plans) assertRouteIR(plan)
   const commandEvents = new Set()
   const nativeEvents = new Set()
@@ -39,7 +41,7 @@ export function planRouteCapabilities(plans, { routes = new Map(), navigationRou
 
   for (let index = 0; index < plans.length; index++) {
     const plan = plans[index]
-    const route = routes.get(plan.route)
+    const route = records[index].capabilities
     for (const event of plan.events) {
       if (event.commands) commandEvents.add(event.event)
       if (event.native) nativeEvents.add(event.event)
@@ -77,7 +79,7 @@ export function planRouteCapabilities(plans, { routes = new Map(), navigationRou
     }
   }
 
-  const routeEntries = [...routes.values()]
+  const routeEntries = records.map(record => record.capabilities)
   const routeCounts = {
     behaviors: routeEntries.filter(route => route.hasBehaviors).length,
     regularBehaviors: routeEntries.filter(route => route.hasBehaviors && !route.usesDependencyRuntime).length,
@@ -151,3 +153,4 @@ function hasNestedCaptureState(value, insideCapture = false) {
   if (value.type === "object") return value.value.some(([, entry]) => hasNestedCaptureState(entry, true))
   return (Array.isArray(value) ? value : Object.values(value)).some(entry => hasNestedCaptureState(entry, false))
 }
+import { assertRouteBuildRecord } from "./route-build-record.mjs"