@ramplab/generator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RampLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @ramplab/generator
+
+The RampLab pipeline: it reads a repository, writes an edition of it, and
+mechanically resolves every code anchor against the source so nothing
+unverifiable survives.
+
+```sh
+npm install @ramplab/generator
+```
+
+Most people want [`@ramplab/cli`](https://www.npmjs.com/package/@ramplab/cli)
+instead, which wraps this with a command line, credential handling and
+progress reporting. Use this directly if you are embedding the press in
+something of your own.
+
+`resolveAnchors(spec, repoDir)` is the part worth knowing about even if you
+never press anything: it is pure over (spec, repository directory), checks that
+every anchored file, line range and symbol really exists, and fingerprints the
+region it resolved. Grounding is enforced structurally rather than promised.
+
+## Licence
+
+MIT. See [LICENSE](./LICENSE).

package/dist/agentSdkRunner.d.ts

@@ -0,0 +1,64 @@
+import type { ModelRunner } from './pipeline.js';
+/**
+ * Which credential a live run will spend (founder, 2026-07-25). Populating
+ * the library used to mean an API key and a metered bill — around $17-21 a
+ * pressing at recent Caddy sizes. The SDK's CLI will just as happily use the
+ * Claude Code login, which spends session allowance instead of API credit, so
+ * both are allowed and the run says out loud which one it took.
+ */
+export type AuthMode = 'api-key' | 'claude-code';
+export interface AuthDescription {
+    mode: AuthMode;
+    /** One line for the run banner. */
+    label: string;
+    /**
+     * True when the run bills the Anthropic API account — i.e. when a reported
+     * `costUsd` is real money. False on the Claude Code credential, where the
+     * SDK's cost figure is a token-priced estimate nobody is invoiced for.
+     */
+    billedToApiAccount: boolean;
+}
+/**
+ * Report the credential the SDK will resolve, without spending anything. A
+ * non-empty `ANTHROPIC_API_KEY` wins because that is the CLI's own precedence;
+ * everything else falls through to the Claude Code login (which may still not
+ * exist — that surfaces as an SDK auth error on the first stage, not here).
+ */
+export declare function describeAuth(env?: NodeJS.ProcessEnv): AuthDescription;
+export interface AgentSdkRunnerOptions {
+    /**
+     * Cap on agentic turns per stage call — a cost guard, not a tuning knob.
+     * @default 50
+     */
+    maxTurns?: number;
+    /**
+     * Abort a stage that has gone completely silent for this long. A working
+     * session streams messages continuously; one that stops yielding has
+     * stalled on a network read and will never resume on its own.
+     * @default 15 minutes
+     */
+    stallTimeoutMs?: number;
+}
+/** 15 minutes: far longer than a healthy turn, far shorter than a hang. */
+export declare const DEFAULT_STALL_TIMEOUT_MS: number;
+export interface StallWatchdog {
+    /** (Re)start the countdown — call on every sign of life. */
+    arm(): void;
+    /** Stop the countdown for good. */
+    disarm(): void;
+    /** True once the countdown expired and `onStall` fired. */
+    get stalled(): boolean;
+}
+/**
+ * A dead-man's switch for a streaming session (founder, 2026-07-26).
+ *
+ * A Caddy eval sat in pass-1 authoring for 5h24m having burned 16 seconds of
+ * CPU: the SDK session stopped yielding and `for await` waited forever, with
+ * `maxTurns` no help because a turn cap is not a clock. Nothing downstream
+ * had a wall-clock guard either, so the whole run hung until it was killed by
+ * hand. This watchdog is the missing clock — idle-based rather than total, so
+ * a legitimately long stage is never cut off, only a silent one.
+ */
+export declare function createStallWatchdog(timeoutMs: number, onStall: () => void): StallWatchdog;
+export declare function createAgentSdkRunner(options?: AgentSdkRunnerOptions): ModelRunner;
+//# sourceMappingURL=agentSdkRunner.d.ts.map

package/dist/agentSdkRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentSdkRunner.d.ts","sourceRoot":"","sources":["../src/agentSdkRunner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAA+B,MAAM,eAAe,CAAC;AAgC9E;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,eAAe,CAgBlF;AAED,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,QAAiB,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,GAAG,IAAI,IAAI,CAAC;IACZ,mCAAmC;IACnC,MAAM,IAAI,IAAI,CAAC;IACf,2DAA2D;IAC3D,IAAI,OAAO,IAAI,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,aAAa,CAsBzF;AAWD,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,WAAW,CAqFrF"}

package/dist/agentSdkRunner.js

@@ -0,0 +1,158 @@
+/**
+ * The live `ModelRunner`: runs a stage as a Claude Agent SDK session over
+ * the repository directory with read-only tools.
+ *
+ * CI never touches this module's runtime path — tests inject fakes at the
+ * `ModelRunner` seam — so the SDK import is lazy: `@ramplab/generator` can
+ * be loaded (and everything else tested) without the SDK spawning anything.
+ *
+ * Auth: the SDK spawns the Claude Code CLI, which resolves credentials the
+ * way Claude Code itself does — `ANTHROPIC_API_KEY` first, then
+ * `CLAUDE_CODE_OAUTH_TOKEN`, then the stored Claude Code login. Both paths
+ * generate identical labs; they differ in who pays. See {@link describeAuth},
+ * which the live entry points print so a run always says which one it is on.
+ */
+/** The agent may look, not touch: exploration tools only. */
+const READ_ONLY_TOOLS = ['Read', 'Glob', 'Grep'];
+/** Everything with side effects or network reach is denied outright. */
+const DENIED_TOOLS = [
+    'Bash',
+    'Write',
+    'Edit',
+    'NotebookEdit',
+    'WebFetch',
+    'WebSearch',
+    'Task',
+    'TodoWrite',
+];
+/**
+ * Report the credential the SDK will resolve, without spending anything. A
+ * non-empty `ANTHROPIC_API_KEY` wins because that is the CLI's own precedence;
+ * everything else falls through to the Claude Code login (which may still not
+ * exist — that surfaces as an SDK auth error on the first stage, not here).
+ */
+export function describeAuth(env = process.env) {
+    const apiKey = env['ANTHROPIC_API_KEY'];
+    if (apiKey !== undefined && apiKey.length > 0) {
+        return {
+            mode: 'api-key',
+            label: 'ANTHROPIC_API_KEY — billed to the Anthropic API account',
+            billedToApiAccount: true,
+        };
+    }
+    return {
+        mode: 'claude-code',
+        label: 'Claude Code credential (no ANTHROPIC_API_KEY set) — spends session ' +
+            'allowance, not API credit; reported costs are estimates, not charges',
+        billedToApiAccount: false,
+    };
+}
+/** 15 minutes: far longer than a healthy turn, far shorter than a hang. */
+export const DEFAULT_STALL_TIMEOUT_MS = 15 * 60 * 1000;
+/**
+ * A dead-man's switch for a streaming session (founder, 2026-07-26).
+ *
+ * A Caddy eval sat in pass-1 authoring for 5h24m having burned 16 seconds of
+ * CPU: the SDK session stopped yielding and `for await` waited forever, with
+ * `maxTurns` no help because a turn cap is not a clock. Nothing downstream
+ * had a wall-clock guard either, so the whole run hung until it was killed by
+ * hand. This watchdog is the missing clock — idle-based rather than total, so
+ * a legitimately long stage is never cut off, only a silent one.
+ */
+export function createStallWatchdog(timeoutMs, onStall) {
+    let timer;
+    let stalled = false;
+    return {
+        arm() {
+            if (stalled)
+                return;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                stalled = true;
+                onStall();
+            }, timeoutMs);
+            // Never hold the process open on the watchdog's account.
+            timer.unref?.();
+        },
+        disarm() {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+        },
+        get stalled() {
+            return stalled;
+        },
+    };
+}
+export function createAgentSdkRunner(options = {}) {
+    const maxTurns = options.maxTurns ?? 50;
+    const stallTimeoutMs = options.stallTimeoutMs ?? DEFAULT_STALL_TIMEOUT_MS;
+    return {
+        async runStage(request) {
+            const { query } = await import('@anthropic-ai/claude-agent-sdk');
+            // The CLI's dying words. A bare "exited with code 1" cost a day of
+            // guessing (2026-07-13); keep the tail and attach it to any failure.
+            let stderrTail = '';
+            const withStderr = (message) => stderrTail.length > 0 ? `${message}\nCLI stderr (tail):\n${stderrTail.trim()}` : message;
+            const abortController = new AbortController();
+            const watchdog = createStallWatchdog(stallTimeoutMs, () => abortController.abort());
+            const session = query({
+                prompt: request.prompt,
+                options: {
+                    model: request.model,
+                    cwd: request.repoDir,
+                    allowedTools: READ_ONLY_TOOLS,
+                    disallowedTools: DENIED_TOOLS,
+                    permissionMode: 'bypassPermissions',
+                    // Zero infra assumptions: never load user/project settings.
+                    settingSources: [],
+                    maxTurns,
+                    abortController,
+                    stderr: (data) => {
+                        stderrTail = `${stderrTail}${data}`.slice(-2000);
+                    },
+                },
+            });
+            const stalledError = () => new Error(withStderr(`Agent SDK session for stage "${request.stage}" produced no output for ` +
+                `${Math.round(stallTimeoutMs / 60000)} minute(s) and was aborted. The ` +
+                `session had stalled, not slowed: raise stallTimeoutMs only if a healthy ` +
+                `stage genuinely goes silent that long.`));
+            let result;
+            try {
+                watchdog.arm();
+                for await (const message of session) {
+                    watchdog.arm(); // any message is a sign of life
+                    const candidate = message;
+                    if (candidate.type === 'result') {
+                        result = candidate;
+                    }
+                }
+            }
+            catch (cause) {
+                // An abort we caused reads as a generic cancellation; say what it was.
+                if (watchdog.stalled)
+                    throw stalledError();
+                throw new Error(withStderr(cause.message), { cause });
+            }
+            finally {
+                watchdog.disarm();
+            }
+            // A stall can also surface as a clean end-of-iteration after the abort.
+            if (watchdog.stalled)
+                throw stalledError();
+            if (result === undefined) {
+                throw new Error(withStderr(`Agent SDK session for stage "${request.stage}" ended without a result message.`));
+            }
+            if (result.is_error === true || result.subtype !== 'success') {
+                throw new Error(withStderr(`Agent SDK session for stage "${request.stage}" failed` +
+                    `${result.subtype !== undefined ? ` (${result.subtype})` : ''}.`));
+            }
+            return {
+                output: result.result ?? '',
+                ...(result.total_cost_usd !== undefined ? { costUsd: result.total_cost_usd } : {}),
+            };
+        },
+    };
+}
+//# sourceMappingURL=agentSdkRunner.js.map

package/dist/agentSdkRunner.js.map

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

package/dist/assembleStage.d.ts

@@ -0,0 +1,41 @@
+import { type LabModule, type LabSpec } from '@ramplab/spec';
+import { type ResolutionPolicy, type ResolutionReport } from './resolveAnchors.js';
+/**
+ * The assemble stage (PLAN.md §4): merge the map stage's overview module and
+ * the authored modules — in plan order — into one lab spec, revalidate the
+ * whole thing against `@ramplab/spec`, and run anchor resolution per policy.
+ *
+ * Deliberately **mechanical**: no model call. Every creative decision was
+ * made upstream (map named the lab, plan ordered the modules, authors wrote
+ * the content); assembly only merges, validates, and grounds. Module ids are
+ * already stable — `repo-overview` from the map stage, plan ids for authored
+ * modules — so overlay entries and learner progress survive regeneration.
+ */
+export interface AssembleOptions {
+    /** @default 'drop' */
+    policy?: ResolutionPolicy;
+    /**
+     * Id of the authored module that opens the lab (issue #18, iteration 2):
+     * concrete-before-abstract applies to the curriculum too, so the flagship
+     * trace goes first and the map's overview module follows as the zoom-out.
+     * Undefined or unmatched keeps the map's modules first.
+     */
+    leadModuleId?: string;
+}
+export interface AssembleResult {
+    /** The merged, validated, anchor-resolved lab spec. */
+    spec: LabSpec;
+    /** Full anchor-resolution report over the merged spec. */
+    report: ResolutionReport;
+}
+/**
+ * Merge `authoredModules` (already in plan order) with the map spec's own
+ * modules and revalidate. The module named by `leadModuleId` — the flagship
+ * trace — is pulled to the front so the learner meets walked code before the
+ * map's architectural overview; the remaining authored modules keep plan
+ * order after it. Throws `LabSpecParseError` if the merge violates the spec
+ * schema — e.g. a duplicate module id, which upstream stages are built to
+ * prevent.
+ */
+export declare function assembleLab(mapSpec: LabSpec, authoredModules: readonly LabModule[], repoDir: string, options?: AssembleOptions): AssembleResult;
+//# sourceMappingURL=assembleStage.d.ts.map

package/dist/assembleStage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembleStage.d.ts","sourceRoot":"","sources":["../src/assembleStage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,SAAS,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAC;IACd,0DAA0D;IAC1D,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,OAAO,EAChB,eAAe,EAAE,SAAS,SAAS,EAAE,EACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAsBhB"}

package/dist/assembleStage.js

@@ -0,0 +1,33 @@
+import { parseLabSpec } from '@ramplab/spec';
+import { resolveAnchors, } from './resolveAnchors.js';
+/**
+ * Merge `authoredModules` (already in plan order) with the map spec's own
+ * modules and revalidate. The module named by `leadModuleId` — the flagship
+ * trace — is pulled to the front so the learner meets walked code before the
+ * map's architectural overview; the remaining authored modules keep plan
+ * order after it. Throws `LabSpecParseError` if the merge violates the spec
+ * schema — e.g. a duplicate module id, which upstream stages are built to
+ * prevent.
+ */
+export function assembleLab(mapSpec, authoredModules, repoDir, options = {}) {
+    const lead = authoredModules.filter((m) => m.id === options.leadModuleId);
+    const rest = authoredModules.filter((m) => m.id !== options.leadModuleId);
+    const candidate = {
+        schemaVersion: mapSpec.schemaVersion,
+        id: mapSpec.id,
+        title: mapSpec.title,
+        ...(mapSpec.repo !== undefined ? { repo: mapSpec.repo } : {}),
+        base: {
+            modules: [...lead, ...mapSpec.base.modules, ...rest],
+        },
+        overlay: mapSpec.overlay,
+    };
+    // Single validation path: a JSON round-trip plus parseLabSpec guarantees
+    // the merged spec is exactly what a consumer would load from disk.
+    const merged = parseLabSpec(JSON.parse(JSON.stringify(candidate)));
+    const { spec, report } = resolveAnchors(merged, repoDir, {
+        policy: options.policy ?? 'drop',
+    });
+    return { spec, report };
+}
+//# sourceMappingURL=assembleStage.js.map

package/dist/assembleStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembleStage.js","sourceRoot":"","sources":["../src/assembleStage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAgC,MAAM,eAAe,CAAC;AAC3E,OAAO,EACL,cAAc,GAGf,MAAM,qBAAqB,CAAC;AAiC7B;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,OAAgB,EAChB,eAAqC,EACrC,OAAe,EACf,UAA2B,EAAE;IAE7B,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC1E,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC1E,MAAM,SAAS,GAAG;QAChB,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,IAAI,EAAE;YACJ,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;SACrD;QACD,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;IAEF,yEAAyE;IACzE,mEAAmE;IACnE,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAEnE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE;QACvD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,MAAM;KACjC,CAAC,CAAC;IACH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1B,CAAC"}

package/dist/authorStage.d.ts

@@ -0,0 +1,123 @@
+import { type LabModule } from '@ramplab/spec';
+import { type ModelRunner } from './pipeline.js';
+import type { CurriculumPlan, PlannedModule } from './planStage.js';
+/**
+ * The author stage (PLAN.md §4, pass 2): fan out one authoring agent per
+ * planned module, in parallel under a small concurrency cap. Each agent
+ * writes a full module — a mix of anchored widgets (callouts, code
+ * walkthroughs, code figures, diagrams, and a closing quiz) — validated
+ * against `@ramplab/spec`'s module schema with the same bounded retry the
+ * other stages use.
+ *
+ * Diagrams are budgeted, not left over (founder, 2026-07-25): the Edition v2
+ * threads gave every module several prose obligations inside an unchanged
+ * 4-to-8 widget budget, and the only widget family described as optional —
+ * the diagrams — is what got squeezed out. Live editions pressed on 2026-07-13
+ * carried 3-5 system maps; those pressed on 2026-07-14 carried 1-2, with the
+ * callout share climbing from 29% to 50% across the same five editions. The
+ * range now starts higher, the diagram catalogue sits above code-figure and
+ * quiz rather than last, and {@link SHAPE_CONTRACT} states the expectation
+ * outright. The escape hatch stays honest: no diagram where the code has no
+ * shape, and every node still carries its own anchor.
+ *
+ * Narrative continuity without serializing the fan-out (issue #18): each
+ * author prompt carries its module's **learner-state ledger slice** — what
+ * the learner has already seen (`assumes`, plus the titles of earlier
+ * modules it may reference), and what this module must add (`teaches`) —
+ * plus the **style contract** (concrete before abstract, jargon defined at
+ * first use, analogies anchored, mechanism-and-why over structural survey).
+ *
+ * Failure policy (deliberate, documented): a module that is still
+ * schema-invalid after its retries **fails the whole stage** with an error
+ * naming the module — there is no silent-skip mode. A planned module is a
+ * curriculum commitment; dropping it quietly would ship a lab with a hole
+ * the lead never sees. Other in-flight modules finish before the error is
+ * raised, so all failures are reported at once.
+ */
+/** Default cap on concurrent authoring agents. */
+export declare const DEFAULT_AUTHOR_CONCURRENCY = 4;
+/**
+ * Widgets per authored chapter. The floor clears the module's mandatory prose
+ * — a quiz, the capability callout, the "when it breaks" warning, the threads
+ * the plan assigned — so a diagram has somewhere to go.
+ */
+export declare const DEFAULT_WIDGET_RANGE: {
+    readonly min: 6;
+    readonly max: 10;
+};
+/** Widgets per chapter for repos deep enough to earn a 7-module plan. */
+export declare const DEEP_WIDGET_RANGE: {
+    readonly min: 7;
+    readonly max: 12;
+};
+export interface AuthorStageOptions {
+    /**
+     * Widget count guidance interpolated into the prompt. Bigger repos earn
+     * deeper chapters, not only more of them. The floor has to clear the
+     * module's mandatory prose (a quiz, the capability callout, the "when it
+     * breaks" warning, the threads the plan assigned) before a diagram can fit
+     * at all — see the module comment. @default 6 to 10
+     */
+    widgetRange?: {
+        min: number;
+        max: number;
+    };
+    model: string;
+    plan: CurriculumPlan;
+    /**
+     * How many times to re-prompt a single module after schema-invalid output.
+     * @default 1
+     */
+    maxRetries?: number;
+    /**
+     * Max authoring agents in flight at once.
+     * @default 4
+     */
+    concurrency?: number;
+    /**
+     * Titles of chapters the reader meets BEFORE this plan's modules in the
+     * finished lab. Prepended to every module's ledger slice. Needed when a
+     * plan covers only part of the book — re-authoring the overview chapter
+     * passes the flagship trace's title here, so the overview is told to build
+     * on the trace instead of being mistaken for the opening chapter (which is
+     * what an empty ledger means).
+     */
+    precedingTitles?: readonly string[];
+    /**
+     * Called as soon as each module validates — while other modules are still
+     * in flight. This is the fan-out's progress seam: `generateLab` and pass 1
+     * forward it as `module-authored` events. Invoked synchronously and not
+     * awaited; completion order follows the fan-out, not plan order.
+     */
+    onModuleAuthored?: (authored: AuthoredModule) => void;
+}
+export interface AuthoredModule {
+    /** A valid lab module — not yet anchor-resolved. */
+    module: LabModule;
+    /** Attempts spent on this module (1 = no retry needed). */
+    attempts: number;
+}
+export interface AuthorStageResult {
+    /** One authored module per planned module, in plan order. */
+    modules: AuthoredModule[];
+    /** Summed cost across all modules and attempts, if the runner reports cost. */
+    costUsd: number | undefined;
+}
+/** One module's terminal failure inside the author stage. */
+export interface AuthorModuleFailure {
+    moduleId: string;
+    attempts: number;
+    lastFailure: string;
+}
+/** Raised when at least one planned module never produced a valid module. */
+export declare class AuthorStageError extends Error {
+    readonly failures: readonly AuthorModuleFailure[];
+    constructor(failures: readonly AuthorModuleFailure[]);
+}
+export declare function runAuthorStage(runner: ModelRunner, repoDir: string, options: AuthorStageOptions): Promise<AuthorStageResult>;
+/** Exported for prompt-contract tests; not part of the stage's runtime API. */
+export declare function buildAuthorPrompt(planned: PlannedModule, earlierTitles: readonly string[], range: {
+    min: number;
+    max: number;
+}): string;
+//# sourceMappingURL=authorStage.d.ts.map

package/dist/authorStage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorStage.d.ts","sourceRoot":"","sources":["../src/authorStage.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,EAAsB,KAAK,WAAW,EAAsB,MAAM,eAAe,CAAC;AACzF,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,kDAAkD;AAClD,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;CAA+B,CAAC;AAEjE,yEAAyE;AACzE,eAAO,MAAM,iBAAiB;;;CAA+B,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;CACvD;AAED,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,MAAM,EAAE,SAAS,CAAC;IAClB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,+EAA+E;IAC/E,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,6EAA6E;AAC7E,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;gBAEtC,QAAQ,EAAE,SAAS,mBAAmB,EAAE;CAerD;AASD,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAkC5B;AA4KD,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,aAAa,EACtB,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAClC,MAAM,CAuDR"}