dsh-pf-stream 0.0.0-stage → 0.1.2

package/lib/stage2/stateMachine.js

@@ -0,0 +1,180 @@
+/**
+ * Stage 2 —— 施密特四状态机（规格《三》§3）。
+ *
+ * STATIC / MOTION / SETTLE / SWITCH：
+ * - 高阈值 H_high_eff（动态，默认 0.10），低阈值联动 H_low_eff = 0.5×H_high_eff；
+ * - SETTLE 满 T_settle_eff（PTS 差值）→ 锁定 F、A←0、转 STATIC，再经 T_merge=50ms 打包；
+ * - SWITCH 原子抢占：清积分、清 P 队列、废擂台、EMA 重置 + 3 帧预热、R4 快定格、
+ *   捕获 F_switch（黑场顺延由流式引擎执行）、转 STATIC 观察 250ms。
+ *
+ * 所有时间判定基于 PTS（契约 5）。积分器 A 与擂台归状态机管，
+ * 待发 P 队列与 F 编码由 Stage 3 流式采样器执行。
+ */
+export class SchmittMachine {
+    state = 'STATIC';
+    enteredAtPtsMs = 0;
+    integratorA = 0;
+    gEma = 0;
+    emaWarmupLeft = 0;
+    settleStartPtsMs = null;
+    /** SETTLE 锁定后的防碎合并窗起点。 */
+    mergeStartPtsMs = null;
+    lastAnchorGlobalId = null;
+    /** SWITCH 后静态观察起点与 F_switch 待发标志。 */
+    switchStaticSincePtsMs = null;
+    fSwitchPending = false;
+    constructor(init) {
+        if (init)
+            Object.assign(this, init);
+    }
+    snapshot() {
+        return {
+            state: this.state,
+            enteredAtPtsMs: this.enteredAtPtsMs,
+            integratorA: this.integratorA,
+            gEma: this.gEma,
+            emaWarmupLeft: this.emaWarmupLeft,
+            settleStartPtsMs: this.settleStartPtsMs,
+            lastKCandidates: null,
+            lastMotionVec: null,
+            arena: null,
+        };
+    }
+    /** H_low_eff 联动。 */
+    static hLowOf(hHighEff) {
+        return 0.5 * hHighEff;
+    }
+    /**
+     * 单帧步进。switchVerdict 由 SwitchDetector 先行判定；
+     * settleArena 由流式引擎维护（观察窗内 g 最高帧），settle_lock 时取用。
+     */
+    step(ptsMs, d, th, switchVerdict) {
+        const effects = [];
+        const hLow = SchmittMachine.hLowOf(th.hHighEff);
+        if (switchVerdict === 'SWITCH') {
+            // 原子抢占（步骤 1-5、7）：清积分、清队列（采样器响应）、废擂台、EMA 重置、
+            // R4 由流式引擎直写 T_settle_eff=80；转 STATIC 观察。
+            this.integratorA = 0;
+            this.gEma = 0;
+            this.emaWarmupLeft = 3;
+            this.settleStartPtsMs = null;
+            this.mergeStartPtsMs = null;
+            this.state = 'STATIC';
+            this.enteredAtPtsMs = ptsMs;
+            this.switchStaticSincePtsMs = ptsMs;
+            this.fSwitchPending = true;
+            effects.push('switch');
+            return { state: this.state, effects };
+        }
+        switch (this.state) {
+            case 'STATIC': {
+                if (this.switchStaticSincePtsMs !== null) {
+                    // SWITCH 后静态观察窗（250ms）
+                    if (d > th.hHighEff) {
+                        this.switchStaticSincePtsMs = null;
+                        if (this.fSwitchPending) {
+                            this.fSwitchPending = false;
+                            effects.push('switch_motion_void');
+                        }
+                        this.toMotion(ptsMs, effects);
+                    }
+                    else if (ptsMs - this.switchStaticSincePtsMs >= th.switchStaticMs) {
+                        this.switchStaticSincePtsMs = null;
+                        if (this.fSwitchPending) {
+                            this.fSwitchPending = false;
+                            effects.push('switch_static_emit');
+                        }
+                    }
+                    // 合并窗在 SWITCH 场景不存在
+                    if (this.mergeStartPtsMs !== null)
+                        this.mergeStartPtsMs = null;
+                    return { state: this.state, effects };
+                }
+                // 常规 STATIC：防碎合并窗
+                if (this.mergeStartPtsMs !== null && ptsMs - this.mergeStartPtsMs >= th.tMergeMs) {
+                    this.mergeStartPtsMs = null;
+                    effects.push('merge_emit');
+                }
+                if (d > th.hHighEff) {
+                    // 合并窗内运动复发：锁定的 F 留待与新 P 簇合并发出（mergeStart 清除）
+                    this.mergeStartPtsMs = null;
+                    this.toMotion(ptsMs, effects);
+                }
+                return { state: this.state, effects };
+            }
+            case 'MOTION': {
+                if (d < hLow) {
+                    this.state = 'SETTLE';
+                    this.enteredAtPtsMs = ptsMs;
+                    this.settleStartPtsMs = ptsMs;
+                    effects.push('settle_enter');
+                }
+                return { state: this.state, effects };
+            }
+            case 'SETTLE': {
+                if (d >= hLow) {
+                    this.state = 'MOTION';
+                    this.enteredAtPtsMs = ptsMs;
+                    this.settleStartPtsMs = null;
+                    effects.push('settle_cancel'); // 积分器 A 保持不清零
+                    return { state: this.state, effects };
+                }
+                const start = this.settleStartPtsMs ?? ptsMs;
+                if (ptsMs - start >= th.tSettleEff) {
+                    // 锁定观察窗最清晰帧生成 F（采样器执行），清零积分器，转 STATIC + 合并窗
+                    this.integratorA = 0;
+                    this.settleStartPtsMs = null;
+                    this.state = 'STATIC';
+                    this.enteredAtPtsMs = ptsMs;
+                    this.mergeStartPtsMs = ptsMs;
+                    effects.push('settle_lock');
+                }
+                return { state: this.state, effects };
+            }
+            default:
+                return { state: this.state, effects };
+        }
+    }
+    toMotion(ptsMs, effects) {
+        this.state = 'MOTION';
+        this.enteredAtPtsMs = ptsMs;
+        this.emaWarmupLeft = 3; // EMA 3 帧预热
+        effects.push('enter_motion');
+    }
+}
+export function createClarityState() {
+    return { gEma: 0, warmupLeft: 3, rhoHistory: [] };
+}
+/** 更新 EMA（1/8 系数）与 ρ；预热期内用当前帧梯度初始化/推进。 */
+export function updateClarity(cs, g, opts = {}) {
+    if (opts.resetWarmup)
+        cs.warmupLeft = 3;
+    if (cs.warmupLeft > 0) {
+        // 预热：均值初始化并逐帧推进
+        cs.gEma = cs.gEma === 0 ? g : g / 8 + (7 / 8) * cs.gEma;
+        cs.warmupLeft -= 1;
+    }
+    else {
+        cs.gEma = g / 8 + (7 / 8) * cs.gEma;
+    }
+    const rho = g / (cs.gEma + 1e-6);
+    cs.rhoHistory.push(rho);
+    if (cs.rhoHistory.length > 3)
+        cs.rhoHistory.shift();
+    return rho;
+}
+/**
+ * PEAK 局部波峰判定：ρ_{t-1} ≥ ρ_{t-2} 且 ρ_{t-1} > ρ_t 且 ρ_{t-1} ≥ ρ_min。
+ * 预热期（warmupLeft > 0 或历史不足 3 帧）不判波峰（返回 false）。
+ */
+export function isLocalPeak(cs, rhoMin) {
+    if (cs.rhoHistory.length < 3)
+        return false;
+    const [prev2, prev1, curr] = [cs.rhoHistory[0], cs.rhoHistory[1], cs.rhoHistory[2]];
+    return prev1 >= prev2 && prev1 > curr && prev1 >= rhoMin;
+}
+/** 擂台比较：候选是否击败当前记录（ρ 更高；无记录时恒真）。 */
+export function beatsArena(candidate, rho) {
+    return candidate === null || rho > candidate.rho;
+}
+//# sourceMappingURL=stateMachine.js.map

package/lib/stage2/stateMachine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateMachine.js","sourceRoot":"","sources":["../../src/stage2/stateMachine.ts"],"names":[],"mappings":"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"}

package/lib/stage2/switchDetector.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Stage 2 —— 硬切（SWITCH）与极速甩镜解耦（规格《三》§2）。
+ *
+ * H_switch = 0.10 为固定常量，与动态调节的 H_high_eff 解耦；
+ * ≥ 26 块（> 80%）满足 δ_raw > 0.30 或 δ > 0.30 时进入直方图判据：
+ * D_hist ≥ 0.35 → 场景硬切；D_hist < 0.35 → 极速甩镜（维持/切入 MOTION）。
+ */
+export declare const H_SWITCH = 0.1;
+export declare const SWITCH_BLOCK_THRESHOLD = 0.3;
+export declare const SWITCH_MIN_BLOCKS = 26;
+export declare const SWITCH_HIST_L1 = 0.35;
+export type SwitchVerdict = 'none' | 'SWITCH' | 'WHIP';
+export declare function classifySceneChange(switchCandidateBlocks: number, histL1: number): SwitchVerdict;
+/**
+ * 黑场/过曝帧判定（SWITCH 原子步骤 6 顺延条件）：
+ * μ_I < 0.05 或 μ_I > 0.95 且 σ_I < 0.01。
+ */
+export declare function isBlackOrBlownFrame(gray: Float64Array): boolean;

package/lib/stage2/switchDetector.js

@@ -0,0 +1,34 @@
+/**
+ * Stage 2 —— 硬切（SWITCH）与极速甩镜解耦（规格《三》§2）。
+ *
+ * H_switch = 0.10 为固定常量，与动态调节的 H_high_eff 解耦；
+ * ≥ 26 块（> 80%）满足 δ_raw > 0.30 或 δ > 0.30 时进入直方图判据：
+ * D_hist ≥ 0.35 → 场景硬切；D_hist < 0.35 → 极速甩镜（维持/切入 MOTION）。
+ */
+export const H_SWITCH = 0.1;
+export const SWITCH_BLOCK_THRESHOLD = 0.3;
+export const SWITCH_MIN_BLOCKS = 26;
+export const SWITCH_HIST_L1 = 0.35;
+export function classifySceneChange(switchCandidateBlocks, histL1) {
+    if (switchCandidateBlocks < SWITCH_MIN_BLOCKS)
+        return 'none';
+    return histL1 >= SWITCH_HIST_L1 ? 'SWITCH' : 'WHIP';
+}
+/**
+ * 黑场/过曝帧判定（SWITCH 原子步骤 6 顺延条件）：
+ * μ_I < 0.05 或 μ_I > 0.95 且 σ_I < 0.01。
+ */
+export function isBlackOrBlownFrame(gray) {
+    let mean = 0;
+    for (let i = 0; i < gray.length; i++)
+        mean += gray[i];
+    mean /= gray.length;
+    if (mean >= 0.05 && mean <= 0.95)
+        return false;
+    let variance = 0;
+    for (let i = 0; i < gray.length; i++)
+        variance += (gray[i] - mean) ** 2;
+    variance /= gray.length;
+    return Math.sqrt(variance) < 0.01;
+}
+//# sourceMappingURL=switchDetector.js.map

package/lib/stage2/switchDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"switchDetector.js","sourceRoot":"","sources":["../../src/stage2/switchDetector.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAC;AAC5B,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAC1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AACpC,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAInC,MAAM,UAAU,mBAAmB,CACjC,qBAA6B,EAC7B,MAAc;IAEd,IAAI,qBAAqB,GAAG,iBAAiB;QAAE,OAAO,MAAM,CAAC;IAC7D,OAAO,MAAM,IAAI,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAkB;IACpD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,IAAI,IAAI,CAAC,CAAC,CAAE,CAAC;IACvD,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC;IACpB,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,QAAQ,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACzE,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC;IACxB,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;AACpC,CAAC"}

package/lib/stage3/deterministicRouter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Stage 3 —— 确定性检视路由（《四、采样逻辑…》§3）。
+ *
+ * 旁路状态机与自闭环，复用 Stage 0（解码）与 Stage 4（视窗归一化与画布打包）：
+ * - 单时间戳 / focus=detail 逐帧 → FORM_3（1F，274 Tokens，slot F 全分辨率）；
+ * - uniform + focus=motion → 每 4 帧一组 FORM_2（4P 概览）；
+ * - 默认 balanced → 每组前 1~3 帧 P + 组末帧 F（FORM_1 / FORM_4）；
+ * - 批量退化：目标数 ≥32 且平均间隔 ≤2s → 单遍区间解码 + 最近 PTS 帧映射；
+ * - 空帧回退复用最后一个有效解码帧。
+ */
+import { type PacketArtifact } from '../stage4/canvasPacker.js';
+import type { IntentDirective, ProbeResult } from '../types.js';
+export interface RouterOptions {
+    ffmpegPath: string;
+    renderVisualId: boolean;
+    packetIdStart: number;
+    globalIdStart: number;
+    appliedIntentId: string;
+    /** 请求字节水位（Base64 后口径；缺省不校验）。规格《六》§2 对 PATH_DETERMINISTIC 同样生效。 */
+    maxRequestBytes?: number | undefined;
+    /** 单图视觉 Token 上限（meteringProfile 口径；缺省不校验）。 */
+    maxTokensPerImage?: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface InspectionResult {
+    packets: PacketArtifact[];
+    hintLines: string[];
+    /** 实际抽帧 PTS 序列（毫秒，排序去重后）。 */
+    sampledPtsMs: number[];
+}
+/** 目标 PTS 列表推导：排序、去重、钳制。 */
+export declare function resolveTargets(intent: IntentDirective, probe: ProbeResult): number[];
+/** 批量退化判定。 */
+export declare function shouldBatchDecode(targets: number[]): boolean;
+interface GroupPlan {
+    form: 'FORM_1_STANDARD_STRIP' | 'FORM_2_COMPACT_4P' | 'FORM_3_COMPACT_1F' | 'FORM_4_PARTIAL_STRIP';
+    pCount: number;
+    hasF: boolean;
+}
+/** 分组与形态规划。 */
+export declare function planGroups(targets: number[], focus: IntentDirective['focus'], singleTimestamp: boolean): GroupPlan[];
+/** 执行确定性检视。 */
+export declare function runDeterministicInspection(videoPath: string, probe: ProbeResult, intent: IntentDirective, options: RouterOptions): Promise<InspectionResult>;
+export {};

package/lib/stage3/deterministicRouter.js

@@ -0,0 +1,203 @@
+/**
+ * Stage 3 —— 确定性检视路由（《四、采样逻辑…》§3）。
+ *
+ * 旁路状态机与自闭环，复用 Stage 0（解码）与 Stage 4（视窗归一化与画布打包）：
+ * - 单时间戳 / focus=detail 逐帧 → FORM_3（1F，274 Tokens，slot F 全分辨率）；
+ * - uniform + focus=motion → 每 4 帧一组 FORM_2（4P 概览）；
+ * - 默认 balanced → 每组前 1~3 帧 P + 组末帧 F（FORM_1 / FORM_4）；
+ * - 批量退化：目标数 ≥32 且平均间隔 ≤2s → 单遍区间解码 + 最近 PTS 帧映射；
+ * - 空帧回退复用最后一个有效解码帧。
+ */
+import { decodePointWithFallback, decodeRangeStreaming } from '../stage0/decoder.js';
+import { packCanvas, timelineHintLine } from '../stage4/canvasPacker.js';
+import { applyViewport, planViewport } from '../stage4/viewport.js';
+import { assertCanvasTokenLegal, encodedSizeOf } from '../stage6/precheck.js';
+import { PfStreamError } from '../errors.js';
+/** 目标 PTS 列表推导：排序、去重、钳制。 */
+export function resolveTargets(intent, probe) {
+    const last = probe.lastPtsMs;
+    if (intent.action === 'timestamps') {
+        const list = (intent.timestamps_ms ?? []).map((t) => Math.min(Math.max(Math.round(t), 0), last));
+        return dedupeSorted(list.sort((a, b) => a - b));
+    }
+    // uniform
+    const w0raw = intent.pts_window?.[0] ?? 0;
+    const w1raw = intent.pts_window?.[1] ?? last;
+    const w0 = Math.min(Math.max(Math.round(Math.min(w0raw, w1raw)), 0), last);
+    const w1 = Math.min(Math.max(Math.round(Math.max(w0raw, w1raw)), 0), last);
+    const out = [];
+    if (intent.frame_count != null && intent.frame_count >= 1) {
+        if (intent.frame_count === 1)
+            return [w0];
+        const step = (w1 - w0) / (intent.frame_count - 1);
+        for (let i = 0; i < intent.frame_count; i++)
+            out.push(Math.round(w0 + step * i));
+    }
+    else if (intent.interval_ms != null && intent.interval_ms > 0) {
+        for (let t = w0; t <= w1; t += intent.interval_ms)
+            out.push(Math.round(t));
+    }
+    else {
+        out.push(w0);
+    }
+    return dedupeSorted(out.map((t) => Math.min(t, last)));
+}
+function dedupeSorted(list) {
+    const out = [];
+    for (const t of list) {
+        if (out.length === 0 || out[out.length - 1] !== t)
+            out.push(t);
+    }
+    return out;
+}
+/** 批量退化判定。 */
+export function shouldBatchDecode(targets) {
+    if (targets.length < 32)
+        return false;
+    const span = targets[targets.length - 1] - targets[0];
+    const avgGap = span / (targets.length - 1);
+    return avgGap <= 2000;
+}
+/** 分组与形态规划。 */
+export function planGroups(targets, focus, singleTimestamp) {
+    const detailMode = focus === 'detail' || singleTimestamp;
+    if (detailMode) {
+        return targets.map(() => ({ form: 'FORM_3_COMPACT_1F', pCount: 0, hasF: true }));
+    }
+    if (focus === 'motion') {
+        const groups = [];
+        for (let i = 0; i < targets.length; i += 4) {
+            groups.push({ form: 'FORM_2_COMPACT_4P', pCount: Math.min(4, targets.length - i), hasF: false });
+        }
+        return groups;
+    }
+    // balanced：每组 5 帧满组（前 4 帧 P + 组末帧 F → FORM_1）；
+    // 余组 2~4 帧（前 k-1 帧 P + 组末帧 F → FORM_4），单帧余量 → FORM_3
+    const groups = [];
+    for (let i = 0; i < targets.length; i += 5) {
+        const n = Math.min(5, targets.length - i);
+        if (n === 1) {
+            groups.push({ form: 'FORM_3_COMPACT_1F', pCount: 0, hasF: true });
+        }
+        else if (n === 5) {
+            groups.push({ form: 'FORM_1_STANDARD_STRIP', pCount: 4, hasF: true });
+        }
+        else {
+            groups.push({ form: 'FORM_4_PARTIAL_STRIP', pCount: n - 1, hasF: true });
+        }
+    }
+    return groups;
+}
+/** 执行确定性检视。 */
+export async function runDeterministicInspection(videoPath, probe, intent, options) {
+    const targets = resolveTargets(intent, probe);
+    if (targets.length === 0) {
+        return { packets: [], hintLines: [], sampledPtsMs: [] };
+    }
+    const decodeOptions = {
+        ffmpegPath: options.ffmpegPath,
+        displayWidth: probe.displayWidth,
+        displayHeight: probe.displayHeight,
+        signal: options.signal,
+    };
+    // 解码：批量退化（单遍流式 + 最近 PTS 帧映射）或逐点
+    const frames = new Map();
+    if (shouldBatchDecode(targets)) {
+        const best = new Map();
+        let firstUnfinalized = 0;
+        await decodeRangeStreaming(videoPath, targets[0], targets[targets.length - 1], decodeOptions, (image, ptsMs) => {
+            // 帧按 PTS 升序到达：越过目标即定稿
+            while (firstUnfinalized < targets.length && ptsMs > targets[firstUnfinalized]) {
+                const t = targets[firstUnfinalized];
+                const hit = best.get(t);
+                if (hit)
+                    frames.set(t, hit.image);
+                firstUnfinalized++;
+            }
+            for (let j = firstUnfinalized; j < Math.min(targets.length, firstUnfinalized + 8); j++) {
+                const t = targets[j];
+                const dist = Math.abs(ptsMs - t);
+                const prev = best.get(t);
+                if (!prev || dist < prev.dist)
+                    best.set(t, { dist, image });
+            }
+        });
+        for (let j = firstUnfinalized; j < targets.length; j++) {
+            const t = targets[j];
+            const hit = best.get(t);
+            if (hit)
+                frames.set(t, hit.image);
+        }
+    }
+    else {
+        let lastValid = null;
+        for (const target of targets) {
+            const frame = await decodePointWithFallback(videoPath, target, probe.lastPtsMs, decodeOptions, lastValid);
+            lastValid = frame;
+            frames.set(target, frame);
+        }
+    }
+    // 视窗计划（同组共享源帧参数，槽位不同）
+    const groups = planGroups(targets, intent.focus, targets.length === 1 && intent.action === 'timestamps');
+    const packets = [];
+    // 提示行（let：字节水位截断时需同步移除对应行）
+    let hintLines = [];
+    let globalId = options.globalIdStart;
+    let packetId = options.packetIdStart;
+    let targetIdx = 0;
+    for (const group of groups) {
+        const units = [];
+        const groupTargets = targets.slice(targetIdx, targetIdx + group.pCount + (group.hasF ? 1 : 0));
+        for (let i = 0; i < groupTargets.length; i++) {
+            const isF = group.hasF && i === groupTargets.length - 1;
+            const pts = groupTargets[i];
+            const frame = frames.get(pts);
+            if (!frame)
+                continue;
+            const plan = planViewport({
+                displayWidth: probe.displayWidth,
+                displayHeight: probe.displayHeight,
+                roi: intent.roi_hint,
+                fullFrame: intent.full_frame === true,
+                slot: isF ? 'F' : 'P',
+            });
+            units.push({
+                globalId: globalId++,
+                ptsMs: pts,
+                scale: isF ? '2x2_F' : '1x1_P',
+                eventType: 'DETERMINISTIC',
+                image: applyViewport(frame, plan, isF ? 'F' : 'P'),
+                sourceCropBbox: plan.sourceCropBbox,
+            });
+        }
+        targetIdx += groupTargets.length;
+        if (units.length === 0)
+            continue;
+        const artifact = packCanvas(group.form, units, {
+            packetId: packetId++,
+            appliedIntentId: options.appliedIntentId,
+            renderVisualId: options.renderVisualId,
+            triggerPath: 'DETERMINISTIC',
+        });
+        packets.push(artifact);
+        hintLines.push(timelineHintLine(artifact.packet, intent.roi_hint ?? null));
+        if (intent.max_packets != null && packets.length >= intent.max_packets)
+            break;
+    }
+    // 预检（规格《六》§2 对 PATH_DETERMINISTIC 同样生效）：
+    // 单图 Token 上限逐包校验（违规即错误）；字节水位超限从尾部截断增量包。
+    if (options.maxTokensPerImage !== undefined) {
+        for (const p of packets)
+            assertCanvasTokenLegal(p, options.maxTokensPerImage);
+    }
+    if (options.maxRequestBytes !== undefined) {
+        let total = packets.reduce((acc, p) => acc + encodedSizeOf(p.imageBytes), 0);
+        while (total > options.maxRequestBytes && packets.length > 0) {
+            const last = packets.pop();
+            total -= encodedSizeOf(last.imageBytes);
+            hintLines = hintLines.filter((l) => !l.includes(`Packet #${last.packet.packetId} `));
+        }
+    }
+    return { packets, hintLines, sampledPtsMs: targets };
+}
+//# sourceMappingURL=deterministicRouter.js.map

package/lib/stage3/deterministicRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deterministicRouter.js","sourceRoot":"","sources":["../../src/stage3/deterministicRouter.ts"],"names":[],"mappings":"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"}

package/lib/stage3/streamSampler.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Stage 3 —— 流式采样引擎（pf_stream 主体，规格《三》《四》《六》）。
+ *
+ * 单遍顺序解码（decodeRangeStreaming）+ 逐帧感知 + 施密特状态机驱动：
+ * - P 单元：MOTION 位移积分（A += α·d·ΔPTS/33.3，A ≥ S_eff 出一张 336 P）；
+ * - F 单元：SETTLE 观察窗最清晰帧 / MOTION PEAK 擂台 / SWITCH 静态保底（黑场顺延 ≤300ms）；
+ * - 四路流式发包：PATH_SETTLE / PEAK_FULL / PEAK_TIMEOUT / SWITCH_STATIC（DETERMINISTIC 在
+ *   deterministicRouter）；M2 阶段全部 history_mode = 'initial'；
+ * - R4 快定格：SWITCH 时 T_settle_eff 直写 80ms，首个 MOTION 或静态稳定后恢复基准；
+ * - 近邻去重：<500ms 且期间 d < H_low 的未发出 F 原地覆盖；
+ * - 长静止心跳：每 5s（PTS）一条轻量 JSON，独立编号空间，不参与包龄计算；
+ * - 时间判定全部基于 PTS（契约 5）；相同视频输入产出幂等事件流（case 19 断言）。
+ */
+import { type PacketArtifact } from '../stage4/canvasPacker.js';
+import { type StreamBaselines } from '../stage5/intent.js';
+import type { CtrlTickLogEntry, ProbeResult, SessionIntent, StreamCursor } from '../types.js';
+export declare const STEP_MS = 33.3;
+export declare const T_MERGE_MS = 50;
+export declare const SWITCH_STATIC_MS = 250;
+export declare const F_SWITCH_DEFER_MAX_MS = 300;
+export declare const NEAR_DUP_MS = 500;
+export declare const HEARTBEAT_INTERVAL_MS = 5000;
+export interface StreamRunOptions {
+    ffmpegPath: string;
+    renderVisualId: boolean;
+    /** 流式窗口长度（defaultStreamWindowMs）。 */
+    windowMs: number;
+    /** 窗口起点（intent.pts_window[0]）；缺省从会话游标续流。 */
+    windowStartMs?: number | undefined;
+    /** 流式工作副本上限（streamWorkMaxEdge，0 = 不限）。 */
+    streamWorkMaxEdge: number;
+    maxPackets: number;
+    maxTokensBudget: number;
+    appliedIntentId: string;
+    packetIdStart: number;
+    globalIdStart: number;
+    heartbeatSeqStart: number;
+    signal?: AbortSignal | undefined;
+}
+export interface StreamTelemetry {
+    decodeMs: number;
+    perceiveMs: number;
+    packMs: number;
+    pathLatencyMs: number;
+    framesDecoded: number;
+    framesStepped: number;
+    ptsRealign: number;
+    /** 每次 ffmpeg 解码进程的 argv 快照（单遍解码断言：计数=1、单次 -ss）。 */
+    ffmpegSpawns: string[][];
+    /** 运行期间同一时刻持有的 672 擂台槽位数峰值（单槽位约束：≤2 = MOTION 1 + SETTLE 1）。 */
+    arenaMaxHeld: number;
+    window: [number, number];
+    stopReason: 'budget_packets' | 'budget_tokens' | 'end_of_window' | 'end_of_stream';
+    ctrlParams: StreamBaselines;
+    /** 500ms 节拍生效值轨迹（R1/R2/R3/R4 断言用）。 */
+    ctrlTickLog: CtrlTickLogEntry[];
+}
+export interface StreamRunResult {
+    packets: PacketArtifact[];
+    hintLines: string[];
+    heartbeats: Array<{
+        seq: number;
+        ptsMs: number;
+    }>;
+    telemetry: StreamTelemetry;
+    nextCursor: StreamCursor;
+    /** 本次运行实际消耗的序号终值（含本次）。 */
+    counters: {
+        packetSeq: number;
+        globalUnitSeq: number;
+        heartbeatSeq: number;
+    };
+}
+export declare function runStreamPass(videoPath: string, probe: ProbeResult, sessionIntent: SessionIntent, cursor: StreamCursor, options: StreamRunOptions): Promise<StreamRunResult>;