@algosail/lang 0.2.11 → 0.5.0

package/lib/ir/bind-values.js

@@ -0,0 +1,594 @@
+/**
+ * L4 фаза 4: привязки значений (RFC-IR section 4).
+ * Внутренний массив id (дно→вершина) — только алгоритм обхода; в wire нет поля «стек».
+ *
+ * На узле шага опционально **`valueBindings`**:
+ * - `argIds: string[]` — id, снимаемые для эффекта шага; **последний элемент — вершина** до шага.
+ * - `resultIds: string[]` — id после шага, порядок **дно → вершина** (как `postTypes`).
+ * - `dup`: один `argId`, два одинаковых id в `resultIds` (та же привязка дважды).
+ *
+ * Шаги без `preTypes`/`postTypes` или при несовпадении длины стека id с `preTypes` (в режиме по умолчанию):
+ * привязки для шага не выставляются, стек id пересобирается из `postTypes` свежими id, чтобы не ломать длину для следующих шагов.
+ * `strict: true` — ошибка при несовместимости.
+ *
+ * Семантика арности встроенных слов — по шаблонам {@link getBuiltinStackSignature} (без повторного typecheck).
+ */
+
+import { getBuiltinStackSignature } from '../typecheck/builtin-signatures.js'
+
+/**
+ * @typedef {{
+ *   wordName: string
+ *   modulePath: string
+ *   strict?: boolean
+ *   resolveLocalWordSig?: (name: string) => import('../typecheck/normalize-sig.js').NormalizedSignature | null | undefined
+ *   resolveQualifiedWordSig?: (module: string, word: string) => import('../typecheck/normalize-sig.js').NormalizedSignature | null | undefined
+ * }} BindValueBindingsOptions
+ */
+
+/** RFC-builtins §4.4–4.5: ветки valueBindings + combinatorInlineMeta для async-обхода. */
+const BUILTIN_COMBINATOR_NAMES = new Set([
+  'dip',
+  'keep',
+  'bi',
+  'tri',
+  'spread',
+  'both'
+])
+
+/** @type {Record<string, (ids: string[]) => string[]>} */
+const BUILTIN_SHUFFLE_TOP = {
+  dup: (ids) => [ids[0], ids[0]],
+  drop: () => [],
+  swap: (ids) => [ids[1], ids[0]],
+  over: (ids) => [ids[0], ids[1], ids[0]],
+  dup2: (ids) => [ids[0], ids[1], ids[0], ids[1]],
+  drop2: () => [],
+  rot: (ids) => [ids[1], ids[2], ids[0]],
+  reverse: (ids) => [ids[2], ids[0], ids[1]],
+  nip: (ids) => [ids[1]],
+  tuck: (ids) => [ids[1], ids[0], ids[1]],
+  swap2: (ids) => [...ids.slice(2, 4), ...ids.slice(0, 2)]
+}
+
+/**
+ * @param {BindValueBindingsOptions} options
+ */
+function createCtx (options) {
+  let counter = 0
+  const base = `${options.modulePath}#${options.wordName}#`
+  return {
+    options,
+    strict: options.strict === true,
+    stack: /** @type {string[]} */ ([]),
+    /** дно→вершина: id входного стека слова после первого resync (только корневой bindRecursive) */
+    entryStackIds: /** @type {string[] | null} */ (null),
+    /** id значения Quote → тело для codegen (этап 2: `call`, HOF) */
+    quoteRegistry:
+      /** @type {Map<string, { innerSteps: Record<string, unknown>[], innerEntryStackIds: string[] }>} */ (
+        new Map()
+      ),
+    makeId (hint = 'v') {
+      counter++
+      return `${base}${hint}${counter}`
+    }
+  }
+}
+
+/**
+ * @param {{ stack: string[], makeId: (hint?: string) => string, strict: boolean }} ctx
+ * @param {number} R
+ */
+function resyncStack (ctx, R) {
+  ctx.stack = Array.from({ length: R }, () => ctx.makeId('resync'))
+}
+
+/**
+ * @param {Record<string, unknown>} node
+ * @param {string[]} argIds
+ * @param {string[]} resultIds
+ */
+function attachBindings (node, argIds, resultIds) {
+  node.valueBindings = { argIds: [...argIds], resultIds: [...resultIds] }
+}
+
+/**
+ * @param {Record<string, unknown>[]} irSteps
+ * @param {{ stack: string[], makeId: (hint?: string) => string, strict: boolean, options: BindValueBindingsOptions, entryStackIds: string[] | null }} ctx
+ * @param {boolean} isRootLevel
+ */
+function bindRecursive (irSteps, ctx, isRootLevel) {
+  for (let si = 0; si < irSteps.length; si++) {
+    const raw = irSteps[si]
+    if (raw == null || typeof raw !== 'object') continue
+    const node = /** @type {Record<string, unknown>} */ (raw)
+    const pre = node.preTypes
+    const post = node.postTypes
+    if (!Array.isArray(pre)) {
+      if (ctx.strict) {
+        throw new Error(`bind-values: шаг без preTypes (${node.kind})`)
+      }
+      continue
+    }
+    const L = pre.length
+    const R =
+      post !== undefined && Array.isArray(post) ? post.length : null
+    if (R === null) {
+      if (ctx.strict) {
+        throw new Error(`bind-values: шаг без postTypes (${node.kind})`)
+      }
+      continue
+    }
+
+    if (ctx.stack.length !== L) {
+      if (ctx.strict) {
+        throw new Error(
+          `bind-values: ожидалась длина стека id ${L}, есть ${ctx.stack.length} (${node.kind})`
+        )
+      }
+      resyncStack(ctx, L)
+    }
+
+    if (isRootLevel && si === 0) {
+      ctx.entryStackIds = [...ctx.stack]
+    }
+
+    const stackIds = ctx.stack
+
+    switch (node.kind) {
+      case 'Literal':
+      case 'ListLiteral': {
+        const litId = ctx.makeId('lit')
+        const argIds = []
+        const resultIds = [...stackIds, litId]
+        attachBindings(node, argIds, resultIds)
+        ctx.stack = resultIds
+        break
+      }
+      case 'Builtin': {
+        const name = /** @type {string} */ (node.name)
+        if (name === 'call') {
+          if (L < 1) {
+            if (ctx.strict) {
+              throw new Error('bind-values: call при пустом стеке id')
+            }
+            resyncStack(ctx, R)
+            break
+          }
+          const quoteId = stackIds[L - 1]
+          const reg = ctx.quoteRegistry.get(quoteId)
+          const topT =
+            Array.isArray(node.preTypes) && node.preTypes.length >= L
+              ? node.preTypes[L - 1]
+              : null
+          const qInner =
+            topT != null &&
+            typeof topT === 'object' &&
+            (topT.kind === 'quote' || topT.kind === 'named_quote') &&
+            topT.inner != null &&
+            typeof topT.inner === 'object'
+              ? /** @type {{ left?: unknown[], right?: unknown[] }} */ (topT.inner)
+              : null
+
+          /** @type {number} */
+          let n
+          /** @type {Record<string, unknown>[]} */
+          let innerStepsArr
+          /** @type {string[]} */
+          let innerEntryArr
+          /** @type {'inline' | 'invoke'} */
+          let callKind
+
+          if (reg) {
+            n = reg.innerEntryStackIds.length
+            innerStepsArr = reg.innerSteps
+            innerEntryArr = [...reg.innerEntryStackIds]
+            callKind = 'inline'
+          } else if (qInner) {
+            n = Array.isArray(qInner.left) ? qInner.left.length : 0
+            innerStepsArr = []
+            innerEntryArr = []
+            callKind = 'invoke'
+          } else {
+            if (ctx.strict) {
+              throw new Error(
+                `bind-values: call — нет quotation в реестре и нет Quote в preTypes для id ${quoteId}`
+              )
+            }
+            resyncStack(ctx, R)
+            break
+          }
+
+          if (L < 1 + n) {
+            if (ctx.strict) {
+              throw new Error('bind-values: call — недостаточно слотов под вход quotation')
+            }
+            resyncStack(ctx, R)
+            break
+          }
+          const prefLen = L - 1 - n
+          const m = R - prefLen
+          if (m < 0 || prefLen < 0) {
+            if (ctx.strict) {
+              throw new Error('bind-values: call — несогласованные длины pre/post')
+            }
+            resyncStack(ctx, R)
+            break
+          }
+          if (
+            callKind === 'invoke' &&
+            qInner &&
+            Array.isArray(qInner.right) &&
+            qInner.right.length !== m
+          ) {
+            if (ctx.strict) {
+              throw new Error(
+                `bind-values: call invoke — несовпадение m (${m}) и inner.right (${qInner.right.length})`
+              )
+            }
+            resyncStack(ctx, R)
+            break
+          }
+          const argIds = stackIds.slice(prefLen)
+          const baseIds = stackIds.slice(0, prefLen)
+          const topOut = Array.from({ length: m }, () => ctx.makeId('call'))
+          const resultIds = baseIds.concat(topOut)
+          if (resultIds.length !== R) {
+            if (ctx.strict) {
+              throw new Error(
+                `bind-values: call: ожидалась длина пост-стека ${R}, получилось ${resultIds.length}`
+              )
+            }
+            resyncStack(ctx, R)
+            break
+          }
+          /** @type {Record<string, unknown>} */
+          const callNode = node
+          if (callKind === 'inline') {
+            callNode.callInlineMeta = {
+              kind: 'inline',
+              innerSteps: innerStepsArr,
+              innerEntryStackIds: innerEntryArr
+            }
+          } else {
+            callNode.callInlineMeta = {
+              kind: 'invoke',
+              innerInLen: n,
+              innerOutLen: m
+            }
+          }
+          attachBindings(callNode, argIds, resultIds)
+          ctx.stack = resultIds
+          break
+        }
+        if (BUILTIN_COMBINATOR_NAMES.has(name)) {
+          const combTemplate = getBuiltinStackSignature(name)
+          if (!combTemplate) {
+            if (ctx.strict) {
+              throw new Error(`bind-values: нет сигнатуры для комбинатора ${name}`)
+            }
+            resyncStack(ctx, R)
+            break
+          }
+          const nCombIn = combTemplate.left.length
+          const nCombOut = combTemplate.right.length
+          const combArgIds =
+            nCombIn === 0 ? [] : stackIds.slice(-nCombIn)
+          const combBase =
+            nCombIn === 0 ? stackIds : stackIds.slice(0, stackIds.length - nCombIn)
+          const mk = () => ctx.makeId(name)
+          /** @type {string[]} */
+          let combTopOut
+          switch (name) {
+            case 'dip':
+            case 'keep':
+              combTopOut = [mk(), combArgIds[1]]
+              break
+            case 'bi':
+            case 'tri': {
+              const freshTops = Array.from(
+                { length: nCombOut - 1 },
+                () => mk()
+              )
+              combTopOut = [combArgIds[0], ...freshTops]
+              break
+            }
+            case 'spread':
+            case 'both':
+              combTopOut = [combArgIds[0], mk(), mk()]
+              break
+            default:
+              if (ctx.strict) {
+                throw new Error(`bind-values: неподдержанный комбинатор ${name}`)
+              }
+              resyncStack(ctx, R)
+              combTopOut = []
+          }
+          if (combTopOut.length !== nCombOut) {
+            if (ctx.strict) {
+              throw new Error(
+                `bind-values: комбинатор ${name}: внутренняя ошибка длины topOut`
+              )
+            }
+            resyncStack(ctx, R)
+            break
+          }
+          const combResultIds = combBase.concat(combTopOut)
+          if (combResultIds.length !== R) {
+            if (ctx.strict) {
+              throw new Error(
+                `bind-values: комбинатор ${name}: ожидалась длина пост-стека ${R}, получилось ${combResultIds.length}`
+              )
+            }
+            resyncStack(ctx, R)
+            break
+          }
+          const pre = node.preTypes
+          /** @type {object[]} */
+          const parts = []
+          /** @type {number[]} */
+          let quoteIdxs = []
+          if (name === 'dip' || name === 'keep') quoteIdxs = [2]
+          else if (name === 'bi') quoteIdxs = [2, 3]
+          else if (name === 'tri') quoteIdxs = [2, 3, 4]
+          else if (name === 'spread') quoteIdxs = [3, 4]
+          else if (name === 'both') quoteIdxs = [3]
+          for (const qi of quoteIdxs) {
+            const qid = combArgIds[qi]
+            const reg = ctx.quoteRegistry.get(qid)
+            if (reg) {
+              parts.push({
+                kind: 'inline',
+                innerSteps: reg.innerSteps,
+                innerEntryStackIds: [...reg.innerEntryStackIds]
+              })
+              continue
+            }
+            const idxTy = L - nCombIn + qi
+            const slotTy =
+              Array.isArray(pre) && idxTy >= 0 && idxTy < pre.length
+                ? pre[idxTy]
+                : null
+            /** @type {{ left?: unknown[], right?: unknown[] } | null} */
+            let inner = null
+            if (
+              slotTy != null &&
+              typeof slotTy === 'object' &&
+              /** @type {{ kind?: string }} */ (slotTy).kind !== undefined &&
+              (/** @type {{ kind: string }} */ (slotTy).kind === 'quote' ||
+                /** @type {{ kind: string }} */ (slotTy).kind === 'named_quote')
+            ) {
+              const inn = /** @type {{ inner?: object }} */ (slotTy).inner
+              if (inn != null && typeof inn === 'object') {
+                const io = /** @type {{ left?: unknown[], right?: unknown[] }} */ (
+                  inn
+                )
+                if (Array.isArray(io.left) && Array.isArray(io.right)) {
+                  inner = io
+                }
+              }
+            }
+            if (!inner) {
+              if (ctx.strict) {
+                throw new Error(
+                  `bind-values: ${name} — нет quotation в реестре и нет Quote в preTypes для id ${qid}`
+                )
+              }
+              resyncStack(ctx, R)
+              break
+            }
+            parts.push({
+              kind: 'invoke',
+              innerInLen: inner.left.length,
+              innerOutLen: inner.right.length
+            })
+          }
+          if (parts.length !== quoteIdxs.length) {
+            break
+          }
+          /** @type {Record<string, unknown>} */
+          const combNode = node
+          combNode.combinatorInlineMeta = { parts }
+          attachBindings(combNode, combArgIds, combResultIds)
+          ctx.stack = combResultIds
+          break
+        }
+        const template = getBuiltinStackSignature(name)
+        if (!template) {
+          if (ctx.strict) {
+            throw new Error(`bind-values: неизвестный builtin ${name}`)
+          }
+          resyncStack(ctx, R)
+          break
+        }
+        const nIn = template.left.length
+        const nOut = template.right.length
+        const argIds = nIn === 0 ? [] : stackIds.slice(-nIn)
+        const base = nIn === 0 ? stackIds : stackIds.slice(0, stackIds.length - nIn)
+        const shuffle = BUILTIN_SHUFFLE_TOP[name]
+        let topOut
+        if (shuffle) {
+          topOut = shuffle(argIds)
+        } else {
+          topOut = Array.from({ length: nOut }, () => ctx.makeId(name))
+        }
+        if (topOut.length !== nOut) {
+          if (ctx.strict) {
+            throw new Error(`bind-values: внутренняя ошибка shuffle ${name}`)
+          }
+          resyncStack(ctx, R)
+          break
+        }
+        const resultIds = base.concat(topOut)
+        if (resultIds.length !== R) {
+          if (ctx.strict) {
+            throw new Error(
+              `bind-values: builtin ${name}: ожидалась длина пост-стека ${R}, получилось ${resultIds.length}`
+            )
+          }
+          resyncStack(ctx, R)
+          break
+        }
+        attachBindings(node, argIds, resultIds)
+        ctx.stack = resultIds
+        break
+      }
+      case 'Word': {
+        const sig =
+          node.ref === 'qualified' &&
+          typeof node.module === 'string' &&
+          typeof node.word === 'string'
+            ? ctx.options.resolveQualifiedWordSig?.(node.module, node.word) ??
+              null
+            : typeof node.name === 'string'
+              ? ctx.options.resolveLocalWordSig?.(node.name) ?? null
+              : null
+        if (!sig) {
+          if (ctx.strict) {
+            throw new Error('bind-values: нет сигнатуры для вызова Word')
+          }
+          resyncStack(ctx, R)
+          break
+        }
+        const nIn = sig.left.length
+        const nOut = sig.right.length
+        // slice(-0) === slice(0) даёт весь массив — для nIn===0 нужны пустые argIds
+        const argIds = nIn === 0 ? [] : stackIds.slice(-nIn)
+        const base = nIn === 0 ? stackIds : stackIds.slice(0, stackIds.length - nIn)
+        const topOut = Array.from({ length: nOut }, () => ctx.makeId('w'))
+        const resultIds = base.concat(topOut)
+        if (resultIds.length !== R) {
+          if (ctx.strict) {
+            throw new Error(
+              `bind-values: Word: несовпадение длины пост-стека (ожидалось ${R})`
+            )
+          }
+          resyncStack(ctx, R)
+          break
+        }
+        attachBindings(node, argIds, resultIds)
+        ctx.stack = resultIds
+        break
+      }
+      case 'Quotation': {
+        const innerSteps = /** @type {Record<string, unknown>[] | undefined} */ (
+          node.steps
+        )
+        /** @type {string[]} */
+        let innerEntryStackIds = []
+        if (Array.isArray(innerSteps) && innerSteps.length > 0) {
+          const inner0 = innerSteps[0]
+          const innerPreLen = Array.isArray(inner0?.preTypes)
+            ? inner0.preTypes.length
+            : 0
+          const innerStack = Array.from({ length: innerPreLen }, () =>
+            ctx.makeId('iq')
+          )
+          innerEntryStackIds = [...innerStack]
+          const innerCtx = {
+            ...ctx,
+            stack: innerStack
+          }
+          bindRecursive(innerSteps, innerCtx, false)
+        }
+
+        /** @type {Record<string, unknown>} */
+        const quotNode = node
+        quotNode.quoteEmitMeta = {
+          innerSteps: Array.isArray(innerSteps) ? innerSteps : [],
+          innerEntryStackIds
+        }
+
+        let argIds
+        let resultIds
+        if (R > L) {
+          argIds = []
+          const delta = R - L
+          resultIds = stackIds.concat(
+            Array.from({ length: delta }, () => ctx.makeId('q'))
+          )
+          const newQuoteIds = resultIds.slice(stackIds.length)
+          for (const qid of newQuoteIds) {
+            ctx.quoteRegistry.set(qid, {
+              innerSteps: Array.isArray(innerSteps) ? innerSteps : [],
+              innerEntryStackIds: [...innerEntryStackIds]
+            })
+          }
+        } else if (R < L) {
+          const drop = L - R
+          argIds = stackIds.slice(-drop)
+          resultIds = stackIds.slice(0, R)
+        } else {
+          argIds = []
+          resultIds = [...stackIds]
+        }
+        if (resultIds.length !== R) {
+          if (ctx.strict) {
+            throw new Error('bind-values: Quotation: несовпадение длин')
+          }
+          resyncStack(ctx, R)
+          break
+        }
+        attachBindings(node, argIds, resultIds)
+        ctx.stack = resultIds
+        break
+      }
+      case 'Slot': {
+        const dir = node.direction
+        const slotName = /** @type {string} */ (node.slotName)
+        if (dir === 'write') {
+          const argIds = stackIds.slice(-1)
+          const base = stackIds.slice(0, stackIds.length - 1)
+          const resultIds = base
+          if (resultIds.length !== R || argIds.length !== 1) {
+            if (ctx.strict) {
+              throw new Error('bind-values: slot_write')
+            }
+            resyncStack(ctx, R)
+            break
+          }
+          attachBindings(node, argIds, resultIds)
+          ctx.stack = resultIds
+        } else if (dir === 'read') {
+          const argIds = []
+          const readId = ctx.makeId(`slot_${slotName}`)
+          const resultIds = stackIds.concat([readId])
+          if (resultIds.length !== R) {
+            if (ctx.strict) {
+              throw new Error('bind-values: slot_read')
+            }
+            resyncStack(ctx, R)
+            break
+          }
+          attachBindings(node, argIds, resultIds)
+          ctx.stack = resultIds
+        } else if (ctx.strict) {
+          throw new Error('bind-values: Slot без direction')
+        } else {
+          resyncStack(ctx, R)
+        }
+        break
+      }
+      default: {
+        if (ctx.strict) {
+          throw new Error(`bind-values: неподдержанный kind ${node.kind}`)
+        }
+        resyncStack(ctx, R)
+      }
+    }
+  }
+}
+
+/**
+ * Заполняет `valueBindings` на узлах `irSteps` (и рекурсивно в `Quotation.steps`).
+ *
+ * @param {Record<string, unknown>[]} irSteps
+ * @param {BindValueBindingsOptions} options
+ * @returns {string[] | null} id входного стека слова (дно→вершина) или null
+ */
+export function bindValueBindingsForIrSteps (irSteps, options) {
+  if (!Array.isArray(irSteps)) return null
+  const ctx = createCtx(options)
+  bindRecursive(irSteps, ctx, true)
+  return ctx.entryStackIds
+}