docs(canvas): explain query indexes, copy checkpoints and runtime ports

src/lib/canvas-runtime/structures.ts

@@ -1,31 +1,51 @@
+/**
+ * runtime 使用的基础调度容器，不包含任务状态事实：FIFO 存可执行顺序，min-heap 存优先项。
+ * 两者都是内存结构，ledger/checkpoint 才负责可恢复事实；容器本身不去重、不校验依赖或执行网络。
+ */
 /** FIFO with amortized O(1) removal, without Array.shift on each item. */
+/** 当前接口是先进先出队列：push 入尾、pop 出头，并非 history 的后进先出 stack。
+ * head 游标避免每次 Array.shift 搬动所有元素，周期压缩使出队摊销 O(1)。 */
 export function createDeque<T>() {
+  // 已出队区间保留到下一次压缩/clear；有效长度为 items.length-head。
   let items: T[] = [], head = 0;
   return {
+    /** 有效未消费数量，不包含 head 前已取出的槽位。 */
     get size() { return items.length - head; },
+    /** 追加队尾，不处理重复值；queued Set 等去重策略由上层维护。 */
     push(value: T) { items.push(value); },
+    /** 查看最早未消费项，不移动 head。 */
     peek(): T | undefined { return items[head]; },
+    /** 取出队头；空队列返回 undefined，已消费量较大且过半时压缩数组。 */
     pop(): T | undefined {
       if (head === items.length) return undefined;
       const value = items[head++];
       if (head > 1024 && head * 2 >= items.length) { items = items.slice(head); head = 0; }
       return value;
     },
+    /** 同时丢弃底层数组和游标，释放旧任务引用。 */
     clear() { items = []; head = 0; },
+    /** 返回有效区间的数组副本，外部改副本不会更改队列成员。 */
     values() { return items.slice(head); },
   };
 }
+/** 数组实现二叉最小堆，compare<0 表示左项优先；peek O(1)，push/pop O(log n)。
+ * 相等优先级不保证插入稳定性，上层若需要 FIFO tie-break 必须把序列写进 comparator。 */
 export function createMinHeap<T>(compare: (left: T, right: T) => number) {
+  // 父下标 (i-1)>>1，左右孩子 2i+1/2i+2；堆序只要求父不大于孩子，不是全数组排序。
   const items: T[] = [];
   return {
+    /** 当前堆条目数，包含上层可能尚未清理的过期条目。 */
     get size() { return items.length; },
+    /** 查看最优项，不移除；任务是否过期仍由调度器校验。 */
     peek(): T | undefined { return items[0]; },
+    /** 新值从末端向上筛选，把较大的祖先下移到空位，最后写入新值。 */
     push(value: T) {
       let index = items.length; items.push(value);
       while (index > 0) { const parent = (index - 1) >> 1; if (compare(items[parent], value) <= 0) break; items[index] = items[parent]; index = parent; }
       items[index] = value;
     },
     pop(): T | undefined {
+      // 出堆：取根并移走末项，再将末项沿较小孩子向下筛选，恢复父≤孩子的不变量。
       if (!items.length) return undefined;
       const first = items[0], last = items.pop()!;
       if (items.length) {
@@ -40,6 +60,7 @@ export function createMinHeap<T>(compare: (left: T, right: T) => number) {
       }
       return first;
     },
+    /** 清空全部条目；不会替任务执行取消或修改 ledger 状态。 */
     clear() { items.length = 0; },
   };
 }