@gordon.gan/specflow 1.7.0-beta → 1.8.0-alpha

package/dist/core/document/input-digest.js

@@ -0,0 +1,121 @@
+/**
+ * Document Engine — Pass 0.5 input compression + source segmentation (decision 8·P0-A, decision 9).
+ *
+ * Long inputs are split into stable segments (seg id → original file + line range),
+ * each segment is compressed in a bounded-context LLM call, then segment digests are
+ * merged into a global input digest (~1–2k tokens). Pass 1 generates the outline from the
+ * global digest; Pass 2 pulls original detail by `source_segments` from the segment index.
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { segmentIndexPath } from './paths.js';
+const SEGMENT_CHAR_BUDGET = 4000; // ~1-2k tokens per segment, bounded context
+export function segmentInputs(inputs) {
+    const segments = [];
+    for (const input of inputs) {
+        const lines = input.content.split('\n');
+        const n = Math.max(1, Math.ceil(lines.length / Math.max(1, Math.floor(SEGMENT_CHAR_BUDGET / 200))));
+        const perChunk = Math.max(1, Math.ceil(lines.length / n));
+        for (let i = 0; i < lines.length; i += perChunk) {
+            const chunk = lines.slice(i, i + perChunk);
+            const idx = segments.length + 1;
+            segments.push({
+                id: `seg-${input.type}-${String(idx).padStart(2, '0')}`,
+                type: input.type,
+                label: `${input.type} #${idx}`,
+                source: input.source,
+                startLine: i + 1,
+                endLine: i + chunk.length,
+                content: chunk.join('\n'),
+            });
+        }
+    }
+    return segments;
+}
+// ============= Compression (T4.2) =============
+const COMPRESS_SYSTEM = '你是长文档输入压缩器。将给定原文段压缩为紧凑摘要，保留：关键实体名（接口/表/页面）、决策线索、约束。不要复述细节，只要提炼。';
+export async function compressSegment(seg, llm) {
+    const input = {
+        system: COMPRESS_SYSTEM,
+        messages: [{ role: 'user', content: `段 ${seg.id}（${seg.label}）：\n${seg.content}` }],
+    };
+    const summary = (await llm.complete(input)).content.trim();
+    return {
+        id: seg.id,
+        type: seg.type,
+        label: seg.label,
+        summary,
+        entity_candidates: extractEntityCandidates(summary),
+    };
+}
+/** Heuristic entity-candidate extraction: backtick tokens + PascalCase/snake tokens. */
+export function extractEntityCandidates(text) {
+    const out = new Set();
+    for (const m of text.matchAll(/`([^`]+)`/g))
+        out.add(m[1].trim());
+    for (const m of text.matchAll(/\b([A-Z][A-Za-z0-9]{2,})\b/g))
+        out.add(m[1]);
+    return [...out];
+}
+// ============= Merge (T4.3) =============
+const MERGE_SYSTEM = '你是长文档输入压缩合并器。将多段摘要合并为一份全局摘要（~1-2k token），保留各段 id、实体候选与关键约束，不丢失任何段。';
+export async function mergeSegmentDigests(digests, llm) {
+    const payload = digests.map((d) => `[${d.id}] ${d.summary}`).join('\n\n');
+    const input = {
+        system: MERGE_SYSTEM,
+        messages: [{ role: 'user', content: payload }],
+    };
+    const summary = (await llm.complete(input)).content.trim();
+    return { segments: digests, summary };
+}
+// ============= Segment index (T4.4) =============
+export async function writeSegmentIndex(workRoot, segments) {
+    const index = {
+        schema: 'specflow.document.segments/v1',
+        segments: segments.map((s) => ({
+            id: s.id,
+            type: s.type,
+            label: s.label,
+            source: s.source,
+            startLine: s.startLine,
+            endLine: s.endLine,
+        })),
+    };
+    const path = segmentIndexPath(workRoot);
+    await fs.mkdir(join(workRoot, 'segments'), { recursive: true });
+    await fs.writeFile(path, JSON.stringify(index, null, 2), 'utf-8');
+    return path;
+}
+export async function readSegmentIndex(workRoot) {
+    const raw = JSON.parse(await fs.readFile(segmentIndexPath(workRoot), 'utf-8'));
+    return raw;
+}
+/** Fetch original text for a set of source_segments (bounded, decision 9). */
+export async function fetchSegments(workRoot, segmentIds) {
+    const index = await readSegmentIndex(workRoot);
+    const wanted = new Set(segmentIds);
+    const matched = index.segments.filter((s) => wanted.has(s.id));
+    const parts = [];
+    for (const s of matched) {
+        parts.push(`[${s.id} · ${s.label}] ${s.source} ${s.startLine}-${s.endLine}`);
+        try {
+            const text = await fs.readFile(s.source, 'utf-8');
+            const lines = text.split('\n').slice(s.startLine - 1, s.endLine);
+            parts.push(lines.join('\n'));
+        }
+        catch {
+            parts.push('(原文不可读，使用段摘要)');
+        }
+    }
+    return parts.join('\n\n');
+}
+// ============= Top-level orchestration (T4.x entry) =============
+export async function compressInputs(workRoot, inputs, llm) {
+    const segments = segmentInputs(inputs);
+    await writeSegmentIndex(workRoot, segments);
+    const digests = [];
+    for (const seg of segments) {
+        digests.push(await compressSegment(seg, llm));
+    }
+    return mergeSegmentDigests(digests, llm);
+}

package/dist/core/document/input-features.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Document Engine — input feature registry + `when` DSL.
+ *
+ * `when` expression grammar (design §3.1, decision 9):
+ *   term      := "input." <feature> | "(" expr ")" | "!" term
+ *   and-or    := term (("&&" | "||") term)*
+ * Built-in features: containsApiChange, hasPersistence, uiInScope, hasLogic.
+ * Unknown features surface as validation warnings (T2.3).
+ */
+export declare const INPUT_FEATURES: readonly ["containsApiChange", "hasPersistence", "uiInScope", "hasLogic", "includeSignoff"];
+export type InputFeature = (typeof INPUT_FEATURES)[number];
+export type InputFeatureMap = Record<string, boolean>;
+export declare function isKnownFeature(name: string): boolean;
+/** Tokenize a when expression into a simple AST via recursive descent. */
+export interface WhenExpr {
+    op: 'and' | 'or' | 'not' | 'feature';
+    feature?: string;
+    left?: WhenExpr;
+    right?: WhenExpr;
+}
+export declare function parseWhen(expr: string): WhenExpr;
+export declare function evaluateWhen(expr: string, features: InputFeatureMap): boolean;
+/** Collect feature names referenced in a when expression (for T2.3 validation). */
+export declare function featuresInWhen(expr: string): string[];

package/dist/core/document/input-features.js

@@ -0,0 +1,112 @@
+/**
+ * Document Engine — input feature registry + `when` DSL.
+ *
+ * `when` expression grammar (design §3.1, decision 9):
+ *   term      := "input." <feature> | "(" expr ")" | "!" term
+ *   and-or    := term (("&&" | "||") term)*
+ * Built-in features: containsApiChange, hasPersistence, uiInScope, hasLogic.
+ * Unknown features surface as validation warnings (T2.3).
+ */
+export const INPUT_FEATURES = [
+    'containsApiChange',
+    'hasPersistence',
+    'uiInScope',
+    'hasLogic',
+    'includeSignoff',
+];
+export function isKnownFeature(name) {
+    return INPUT_FEATURES.includes(name);
+}
+class WhenParser {
+    src;
+    pos = 0;
+    constructor(src) {
+        this.src = src;
+        this.src = src.replace(/\s+/g, '');
+    }
+    parse() {
+        const expr = this.parseOr();
+        if (this.pos < this.src.length) {
+            throw new Error(`WhenParser: unexpected token at ${this.pos}: "${this.src.slice(this.pos)}"`);
+        }
+        return expr;
+    }
+    parseOr() {
+        let left = this.parseAnd();
+        while (this.peek('||')) {
+            this.pos += 2;
+            left = { op: 'or', left, right: this.parseAnd() };
+        }
+        return left;
+    }
+    parseAnd() {
+        let left = this.parseNot();
+        while (this.peek('&&')) {
+            this.pos += 2;
+            left = { op: 'and', left, right: this.parseNot() };
+        }
+        return left;
+    }
+    parseNot() {
+        if (this.peek('!')) {
+            this.pos += 1;
+            return { op: 'not', right: this.parseNot() };
+        }
+        if (this.peek('(')) {
+            this.pos += 1;
+            const inner = this.parseOr();
+            if (!this.peek(')'))
+                throw new Error('WhenParser: missing ")"');
+            this.pos += 1;
+            return inner;
+        }
+        return this.parseFeature();
+    }
+    parseFeature() {
+        const m = this.src.slice(this.pos).match(/^input\.[A-Za-z_][A-Za-z0-9_]*/);
+        if (!m)
+            throw new Error(`WhenParser: expected input.<feature> at "${this.src.slice(this.pos)}"`);
+        this.pos += m[0].length;
+        return { op: 'feature', feature: m[0].slice('input.'.length) };
+    }
+    peek(token) {
+        return this.src.startsWith(token, this.pos);
+    }
+}
+export function parseWhen(expr) {
+    if (!expr || !expr.trim())
+        throw new Error('WhenParser: empty expression');
+    return new WhenParser(expr).parse();
+}
+export function evaluateWhen(expr, features) {
+    const ast = parseWhen(expr);
+    return evalNode(ast, features);
+}
+function evalNode(node, features) {
+    switch (node.op) {
+        case 'feature':
+            return features[node.feature] === true;
+        case 'not':
+            return !evalNode(node.right, features);
+        case 'and':
+            return evalNode(node.left, features) && evalNode(node.right, features);
+        case 'or':
+            return evalNode(node.left, features) || evalNode(node.right, features);
+        default:
+            return false;
+    }
+}
+/** Collect feature names referenced in a when expression (for T2.3 validation). */
+export function featuresInWhen(expr) {
+    const out = [];
+    walk(parseWhen(expr), out);
+    return out;
+}
+function walk(node, acc) {
+    if (node.op === 'feature')
+        acc.push(node.feature);
+    if (node.left)
+        walk(node.left, acc);
+    if (node.right)
+        walk(node.right, acc);
+}

package/dist/core/document/lint.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Document Engine — lint: reference checks, stub detection, budget checks (decision 6).
+ */
+export interface LintDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+}
+export interface LintOptions {
+    /** Minimum meaningful content length for narrative (default 20). */
+    minNarrativeChars?: number;
+}
+export declare function lintNarrative(chapterId: string, narrative: string, options?: LintOptions): LintDiagnostic[];
+export interface BudgetDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+}
+/** Check chapter output against per-chapter budget (decision 6/P6). */
+export declare function checkBudget(chapterId: string, tokens: number, budgetTokens?: number): BudgetDiagnostic[];

package/dist/core/document/lint.js

@@ -0,0 +1,29 @@
+/**
+ * Document Engine — lint: reference checks, stub detection, budget checks (decision 6).
+ */
+import { findForbiddenMatch, findInconsistencyHints } from './forbidden-patterns.js';
+export function lintNarrative(chapterId, narrative, options = {}) {
+    const diags = [];
+    const min = options.minNarrativeChars ?? 20;
+    const trimmed = narrative.trim();
+    if (trimmed.length < min) {
+        diags.push({ code: 'narrative_too_short', severity: 'error', chapter: chapterId, message: `Chapter "${chapterId}" narrative too short (< ${min} chars)` });
+    }
+    const forbidden = findForbiddenMatch(trimmed);
+    if (forbidden) {
+        diags.push({ code: 'forbidden_pattern', severity: 'error', chapter: chapterId, message: `Chapter "${chapterId}": forbidden stub pattern (${forbidden.source})` });
+    }
+    for (const hint of findInconsistencyHints(trimmed)) {
+        diags.push({ code: 'inconsistency_hint', severity: 'warning', chapter: chapterId, message: `Chapter "${chapterId}": possible inconsistency (${hint.source})` });
+    }
+    return diags;
+}
+/** Check chapter output against per-chapter budget (decision 6/P6). */
+export function checkBudget(chapterId, tokens, budgetTokens) {
+    if (budgetTokens === undefined)
+        return [];
+    if (tokens > budgetTokens) {
+        return [{ code: 'budget_exceeded', severity: 'error', chapter: chapterId, message: `Chapter "${chapterId}" ${tokens} tokens exceeds budget ${budgetTokens}` }];
+    }
+    return [];
+}

package/dist/core/document/llm.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Document Engine — injectable LLM interface
+ *
+ * The engine does NOT bind to any specific LLM SDK. Consumers provide a
+ * `DocumentLLM` implementation. `completeJSON` parses + zod-validates the
+ * model response so all downstream consumers get typed data or a clean error.
+ */
+import type { z } from 'zod';
+export interface LLMMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+export interface LLMInput {
+    system?: string;
+    messages: LLMMessage[];
+}
+export interface LLMOutput {
+    content: string;
+}
+export interface DocumentLLM {
+    /** Generic completion — returns raw text. */
+    complete(input: LLMInput): Promise<LLMOutput>;
+    /** Structured completion — returns a zod-validated value. */
+    completeJSON<T>(input: LLMInput, schema: z.ZodType<T>): Promise<T>;
+    /** Token estimate for budget checks (character-based is acceptable). */
+    countTokens(text: string): number;
+}
+/**
+ * Default character-based token estimate.
+ * NOTE: under-counts Chinese (~1 char ≈ 1 token vs len/4); budget gates are
+ * intentionally lenient. Callers may override by wrapping countTokens.
+ */
+export declare function estimateTokens(text: string): number;
+/** Strip markdown code-fence around a JSON payload (helper for completeJSON impls). */
+export declare function extractJSON(content: string): string;

package/dist/core/document/llm.js

@@ -0,0 +1,27 @@
+/**
+ * Document Engine — injectable LLM interface
+ *
+ * The engine does NOT bind to any specific LLM SDK. Consumers provide a
+ * `DocumentLLM` implementation. `completeJSON` parses + zod-validates the
+ * model response so all downstream consumers get typed data or a clean error.
+ */
+/**
+ * Default character-based token estimate.
+ * NOTE: under-counts Chinese (~1 char ≈ 1 token vs len/4); budget gates are
+ * intentionally lenient. Callers may override by wrapping countTokens.
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    // Count CJK chars at 1 token/char, others at ~4 chars/token.
+    let tokens = 0;
+    for (const ch of text) {
+        tokens += /[\u2E80-\u9FFF\uF900-\uFAFF\uFF00-\uFFEF\u3000-\u303F]/.test(ch) ? 1 : 0.25;
+    }
+    return Math.max(1, Math.ceil(tokens));
+}
+/** Strip markdown code-fence around a JSON payload (helper for completeJSON impls). */
+export function extractJSON(content) {
+    const match = content.match(/```json\s*([\s\S]*?)```/) || content.match(/```\s*([\s\S]*?)```/);
+    return (match ? match[1] : content).trim();
+}

package/dist/core/document/map.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Document Engine — Pass 2 per-chapter fill-in (decisions 6/8/9).
+ *
+ * Four-layer context injection per chapter:
+ *   ① outline points + global entities/decisions
+ *   ② dependency digests (navigation)
+ *   ③ upstream contract entities injected deterministically (registry + referenced full contracts)
+ *   ④ source segments (original input by source_segments)
+ *
+ * Fills by point kind: entity/mixed → structured contract entities; narrative/mixed → Markdown.
+ * Output budget enforced per chapter (decision 6/P6). fill_once falls back to per-chapter when
+ * the estimated input context exceeds the budget (decision 9).
+ */
+import { Outline, OutlineChapter, Entities, ChapterComponent } from './schemas.js';
+import type { DocumentLLM, LLMInput } from './llm.js';
+export interface ChapterFill {
+    chapterId: string;
+    narrative: string;
+    entities: Entities;
+    tokens: number;
+}
+export interface MapContext {
+    outline: Outline;
+    digests: Map<string, string>;
+    upstreamEntities: Entities;
+    workRoot: string;
+    chapterById: Map<string, ChapterComponent>;
+}
+export declare function buildChapterContext(chapter: OutlineChapter, ctx: MapContext): Promise<{
+    input: LLMInput;
+    estimatedTokens: number;
+}>;
+export interface FillChapterResult {
+    ok: boolean;
+    fill?: ChapterFill;
+    error?: string;
+}
+export declare function fillChapter(llm: DocumentLLM, chapter: OutlineChapter, ctx: MapContext, budgetTokens?: number): Promise<FillChapterResult>;
+export declare function shouldFillOnce(outline: Outline, ctx: MapContext): Promise<boolean>;
+export interface FillOnceResult {
+    ok: boolean;
+    chapters: ChapterFill[];
+    fellBackToPerChapter: boolean;
+    error?: string;
+}
+export declare function fillOnce(llm: DocumentLLM, outline: Outline, ctx: MapContext): Promise<FillOnceResult>;

package/dist/core/document/map.js

@@ -0,0 +1,212 @@
+/**
+ * Document Engine — Pass 2 per-chapter fill-in (decisions 6/8/9).
+ *
+ * Four-layer context injection per chapter:
+ *   ① outline points + global entities/decisions
+ *   ② dependency digests (navigation)
+ *   ③ upstream contract entities injected deterministically (registry + referenced full contracts)
+ *   ④ source segments (original input by source_segments)
+ *
+ * Fills by point kind: entity/mixed → structured contract entities; narrative/mixed → Markdown.
+ * Output budget enforced per chapter (decision 6/P6). fill_once falls back to per-chapter when
+ * the estimated input context exceeds the budget (decision 9).
+ */
+import { parseEntities } from './schemas.js';
+import { estimateTokens } from './llm.js';
+import { fetchSegments } from './input-digest.js';
+const MAP_SYSTEM = '你是方案文档撰写员。按给定章节要点"填空题"式展开：逐要点填充，不自由发挥。' +
+    'kind=entity 或 mixed 的要点 → 产出结构化契约实体（JSON）；kind=narrative 或 mixed 的要点 → 产出叙述 Markdown。' +
+    '契约实体必须满足字段约束（接口须含 failure_examples，表须含 ddl/migration/rollback）。';
+// ============= Four-layer context build (T6.2) =============
+export async function buildChapterContext(chapter, ctx) {
+    const { outline, digests, upstreamEntities, workRoot } = ctx;
+    // ① outline points + global entities/decisions
+    const chapterPoints = chapter.points.map((p) => `${p.id} [${p.kind}] ${p.text}${(p.references ?? []).length ? ` refs=${(p.references ?? []).join(',')}` : ''}`).join('\n');
+    const globalEntities = outline.entities.map((e) => `${e.id} (${e.frozen}${e.standalone ? ', standalone' : ''})`).join(', ');
+    // ② dependency digests
+    const deps = [];
+    const chComp = ctx.chapterById.get(chapter.id);
+    for (const dep of chComp?.depends_on ?? []) {
+        const d = digests.get(dep);
+        if (d)
+            deps.push(`[依赖 ${dep}] ${d}`);
+    }
+    // ③ upstream contract entities: registry (all) + full contracts for referenced ids
+    const referencedIds = new Set();
+    for (const p of chapter.points)
+        for (const r of p.references ?? [])
+            referencedIds.add(r);
+    const registry = [
+        ...upstreamEntities.interfaces.map((i) => `I ${i.id}: ${i.name}`),
+        ...upstreamEntities.tables.map((t) => `T ${t.id}: ${t.name}`),
+    ].join('\n');
+    const fullContracts = [
+        ...upstreamEntities.interfaces.filter((i) => referencedIds.has(i.id)),
+        ...upstreamEntities.tables.filter((t) => referencedIds.has(t.id)),
+    ].map((e) => JSON.stringify(e)).join('\n');
+    // ④ source segments
+    const segmentIds = new Set();
+    for (const p of chapter.points)
+        for (const s of p.source_segments ?? [])
+            segmentIds.add(s);
+    const segments = segmentIds.size > 0 ? await fetchSegments(workRoot, [...segmentIds]) : '';
+    const content = [
+        `## 章节 ${chapter.id}（${chapter.title}）`,
+        `### 要点清单（填空）`,
+        chapterPoints,
+        `### 全局实体/决策`,
+        globalEntities,
+        deps.length ? `### 依赖摘要\n${deps.join('\n\n')}` : '',
+        registry ? `### 上游契约实体注册表\n${registry}` : '',
+        fullContracts ? `### 上游契约实体完整契约（引用）\n${fullContracts}` : '',
+        segments ? `### 本片片段（原文）\n${segments}` : '',
+    ].filter(Boolean).join('\n\n');
+    const input = {
+        system: MAP_SYSTEM,
+        messages: [{ role: 'user', content }],
+    };
+    return { input, estimatedTokens: estimateTokens(content) + estimateTokens(MAP_SYSTEM) };
+}
+export async function fillChapter(llm, chapter, ctx, budgetTokens) {
+    let input;
+    let estimatedTokens;
+    try {
+        const built = await buildChapterContext(chapter, ctx);
+        input = built.input;
+        estimatedTokens = built.estimatedTokens;
+    }
+    catch (e) {
+        return { ok: false, error: `Chapter "${chapter.id}" context build failed: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    let res;
+    try {
+        res = await llm.complete(input);
+    }
+    catch (e) {
+        return { ok: false, error: `Chapter "${chapter.id}" LLM call failed: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    const narrative = res.content.trim();
+    // Extract embedded contract entities (JSON blocks). Strict: if this chapter's points require
+    // entities (kind=entity|mixed with references) and none are extracted, fail loudly rather than
+    // silently produce a contract-less chapter (decision 1 layered source of truth).
+    let entities = { interfaces: [], tables: [], decisions: [] };
+    const jsonMatch = narrative.match(/```json\s*([\s\S]*?)```/g);
+    if (jsonMatch) {
+        const merged = { interfaces: [], tables: [], decisions: [] };
+        for (const block of jsonMatch) {
+            try {
+                const parsed = JSON.parse(block.replace(/```json\s*/, '').replace(/```$/, '').trim());
+                if (parsed.entities) {
+                    const e = parseEntities(parsed.entities);
+                    merged.interfaces.push(...e.interfaces);
+                    merged.tables.push(...e.tables);
+                    merged.decisions.push(...e.decisions);
+                }
+            }
+            catch {
+                // non-entity JSON blocks are ignored; strict entity-presence check below catches gaps
+            }
+        }
+        entities = merged;
+    }
+    // Clean the narrative: remove the embedded ```json entity blocks so they are not rendered
+    // verbatim inside chapters (contract entities are rendered deterministically in the 契约 section).
+    const cleanNarrative = narrative.replace(/```json\s*[\s\S]*?```/g, '').replace(/\n{3,}/g, '\n\n').trim();
+    // Strict: entity-requiring points must have their referenced entities filled.
+    const requiredEntityIds = new Set();
+    for (const p of chapter.points) {
+        if ((p.kind === 'entity' || p.kind === 'mixed') && (p.references ?? []).length > 0) {
+            for (const ref of p.references)
+                requiredEntityIds.add(ref);
+        }
+    }
+    const filledEntityIds = new Set([
+        ...entities.interfaces.map((i) => i.id),
+        ...entities.tables.map((t) => t.id),
+        ...entities.decisions.map((d) => d.id),
+    ]);
+    for (const id of requiredEntityIds) {
+        if (!filledEntityIds.has(id)) {
+            return { ok: false, error: `Chapter "${chapter.id}" requires entity "${id}" (point references) but none was extracted` };
+        }
+    }
+    const tokens = estimateTokens(cleanNarrative) + estimateTokens(JSON.stringify(entities));
+    // Input-side budget guard: reject clearly-over-budget inputs (decision 6/P6 hard gate).
+    const maxInputTokens = budgetTokens ? budgetTokens * 4 : undefined;
+    if (maxInputTokens !== undefined && estimatedTokens > maxInputTokens) {
+        return { ok: false, error: `Chapter "${chapter.id}" input context ${estimatedTokens} tokens exceeds 4× output budget` };
+    }
+    if (budgetTokens !== undefined && tokens > budgetTokens) {
+        return { ok: false, error: `Chapter "${chapter.id}" output ${tokens} tokens exceeds budget ${budgetTokens}` };
+    }
+    return {
+        ok: true,
+        fill: { chapterId: chapter.id, narrative: cleanNarrative, entities, tokens },
+    };
+}
+// ============= fill_once decision (T6.5/T6.6) =============
+export async function shouldFillOnce(outline, ctx) {
+    if (!outline.fill_once?.enabled)
+        return false;
+    const budget = outline.fill_once.input_budget_tokens ?? 8000;
+    let total = 0;
+    for (const ch of outline.chapters) {
+        const { estimatedTokens } = await buildChapterContext(ch, ctx);
+        total += estimatedTokens;
+    }
+    return total <= budget;
+}
+const FILL_ONCE_SYSTEM = '你是方案文档撰写员。一次填完全部章节，输出结构化 JSON：' +
+    '{"chapters":{"<chapterId>":{"narrative":"本章叙述 Markdown","entities":{"interfaces":[...],"tables":[...],"decisions":[...]}},...}}。' +
+    '每章内容必须差异化（针对该章要点），禁止复制同一段到所有章节。契约实体须含 failure_examples（接口）/ddl（表）。';
+export async function fillOnce(llm, outline, ctx) {
+    // Build a single combined context (all chapters) — bounded by shouldFillOnce pre-check.
+    const sections = [];
+    for (const ch of outline.chapters) {
+        const { input } = await buildChapterContext(ch, ctx);
+        sections.push(input.messages[0].content);
+    }
+    const res = await llm.complete({
+        system: FILL_ONCE_SYSTEM,
+        messages: [{ role: 'user', content: sections.join('\n\n=====\n\n') }],
+    });
+    const content = res.content.trim();
+    // Parse structured per-chapter output; fall back to per-chapter fill on parse failure.
+    try {
+        const parsed = JSON.parse(content);
+        if (!parsed.chapters || typeof parsed.chapters !== 'object') {
+            return { ok: false, chapters: [], fellBackToPerChapter: true, error: 'fill_once: missing chapters object' };
+        }
+        const chapters = [];
+        for (const ch of outline.chapters) {
+            const entry = parsed.chapters[ch.id];
+            if (!entry || typeof entry.narrative !== 'string' || entry.narrative.trim().length === 0) {
+                return { ok: false, chapters: [], fellBackToPerChapter: true, error: `fill_once: chapter ${ch.id} missing narrative` };
+            }
+            let entities = { interfaces: [], tables: [], decisions: [] };
+            try {
+                if (entry.entities)
+                    entities = parseEntities(entry.entities);
+            }
+            catch {
+                entities = { interfaces: [], tables: [], decisions: [] };
+            }
+            const narrative = entry.narrative.trim();
+            chapters.push({
+                chapterId: ch.id,
+                narrative,
+                entities,
+                tokens: estimateTokens(narrative) + estimateTokens(JSON.stringify(entities)),
+            });
+        }
+        return { ok: true, chapters, fellBackToPerChapter: false };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            chapters: [],
+            fellBackToPerChapter: true,
+            error: `fill_once: unparsable output (${e instanceof Error ? e.message : String(e)})`,
+        };
+    }
+}

package/dist/core/document/outline.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Document Engine — Pass 1 outline generation + lint + freeze (decisions 6/8/9).
+ *
+ * Generates the Outline from the global input digest + profile constraints,
+ * lints it (required/forbidden, references forward + reverse, kind consistency),
+ * then freezes to work/outline.yaml.
+ */
+import { Outline, ScenarioProfile } from './schemas.js';
+import type { DocumentLLM } from './llm.js';
+import { GlobalInputDigest } from './input-digest.js';
+export interface OutlineDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+}
+export interface GenerateOutlineOptions {
+    profile: ScenarioProfile;
+    inputDigest: GlobalInputDigest;
+    prompt?: string;
+}
+export declare function generateOutline(llm: DocumentLLM, options: GenerateOutlineOptions): Promise<Outline>;
+export declare function lintOutline(outline: Outline, profile: ScenarioProfile): OutlineDiagnostic[];
+export declare function outlineHasErrors(diags: OutlineDiagnostic[]): boolean;
+export declare function freezeOutline(workRoot: string, outline: Outline): Promise<string>;
+export declare function readOutline(workRoot: string): Promise<Outline>;