@llm4ts/shell 2.32.0 → 2.34.0

package/flows/port-guide.js

@@ -0,0 +1,245 @@
+// Audit the porting rulebook before it ports anything (ADR 0028, the Bun
+// port's porting-md audit): dimension auditors read the rulebook against a
+// few sample sources and propose rules; three refuters vote each finding
+// down or let it stand; a trial port of the samples by the rules and again
+// natively shows what the rulebook forgot. The result is a patch to
+// `prompts/porting.md` behind an approval; the next run applies it.
+//
+//   LLM4TS_PACK=zig-rust llm4ts run port-guide --repo ~/src/bun
+//
+// Knobs: LLM4TS_PORT_GUIDE_SAMPLE (3 files), LLM4TS_PORT_GUIDE_TRIAL (on|off).
+import { join } from "node:path";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { ApprovedMarker } from "@llm4ts/flow/Approval";
+import { makeChat } from "@llm4ts/flow/Chat";
+import { cap } from "@llm4ts/flow/Context";
+import { Info } from "@llm4ts/flow/FlowEvents";
+import { GuideFinding, defaultAuditDimensions, renderGuideAudit, standsAfterRefutes } from "@llm4ts/flow/Port";
+import { AppliedMarkerPrefix, applyRuleEdit, retroApprovalOf } from "@llm4ts/flow/Retro";
+import { asReadOnly, coderFromEnv, makeNodeWorkspace, nodePlainFileStore, openPack, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
+import { structuredAndPublish } from "@llm4ts/flow/Flow";
+import { asPortingPack, implementerPrompt, implementerSystem, nativeImplementerSystem, portEnv, portManifest, portStateDir } from "./lib/port.js";
+class Findings extends Schema.Class("Findings")({
+    findings: Schema.Array(GuideFinding)
+}) {
+}
+const findingItems = {
+    type: "array",
+    items: {
+        type: "object",
+        properties: {
+            dimension: { type: "string" },
+            finding: { type: "string" },
+            evidence: { type: "string" },
+            proposedRule: { type: "string" }
+        },
+        required: ["dimension", "finding", "evidence", "proposedRule"]
+    }
+};
+const findingsJson = {
+    type: "object",
+    properties: { findings: findingItems },
+    required: ["findings"]
+};
+class Refute extends Schema.Class("Refute")({
+    holds: Schema.Boolean,
+    why: Schema.String
+}) {
+}
+const refuteJson = {
+    type: "object",
+    properties: { holds: { type: "boolean" }, why: { type: "string" } },
+    required: ["holds", "why"]
+};
+class Trial extends Schema.Class("Trial")({
+    differences: Schema.Array(Schema.String),
+    findings: Schema.Array(GuideFinding)
+}) {
+}
+const trialJson = {
+    type: "object",
+    properties: { differences: { type: "array", items: { type: "string" } }, findings: findingItems },
+    required: ["differences", "findings"]
+};
+class AuditRecord extends Schema.Class("AuditRecord")({
+    kept: Schema.Array(GuideFinding)
+}) {
+}
+const encodeAudit = Schema.encodeSync(Schema.fromJsonString(AuditRecord));
+const decodeAudit = Schema.decodeUnknownOption(Schema.fromJsonString(AuditRecord));
+const program = Effect.gen(function* () {
+    const input = yield* resolveFlowInput("Audit the porting rulebook against sample sources");
+    const coder = coderFromEnv(process.env);
+    const files = nodePlainFileStore;
+    const knobs = portEnv(process.env);
+    const sampleSize = Math.max(1, Number.parseInt(process.env.LLM4TS_PORT_GUIDE_SAMPLE ?? "3", 10) || 3);
+    const trialOn = process.env.LLM4TS_PORT_GUIDE_TRIAL?.trim().toLowerCase() !== "off";
+    const stateDir = portStateDir(input.workDir);
+    const reportPath = join(stateDir, "guide-audit.md");
+    const recordPath = join(stateDir, "guide-audit.json");
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder,
+        reasoning: asReadOnly(coder),
+        reviewers: [asReadOnly(coder)],
+        environment: process.env
+    }, (context) => Effect.gen(function* () {
+        const events = context.events;
+        const repo = yield* makeNodeWorkspace(input.workDir);
+        const opened = yield* stage(events, "pack", openPack({
+            environment: process.env,
+            launchDir: input.workspace,
+            flowDir: import.meta.dirname
+        }));
+        const porting = yield* asPortingPack(opened);
+        const rulebookPath = `${opened.dir}/prompts/porting.md`;
+        // An approved, unapplied audit from an earlier run: apply it to the rulebook and stop.
+        const earlier = yield* files.read(reportPath);
+        if (earlier !== undefined) {
+            const approval = retroApprovalOf(earlier);
+            if (approval.approved && !approval.applied) {
+                const recordText = yield* files.read(recordPath);
+                const record = recordText === undefined ? undefined : decodeAudit(recordText);
+                if (record !== undefined && record._tag === "Some") {
+                    let text = yield* opened.workspace
+                        .read(rulebookPath)
+                        .pipe(Effect.orElseSucceed(() => porting.rulebook));
+                    let applied = 0;
+                    for (const finding of record.value.kept) {
+                        const next = applyRuleEdit(text, {
+                            target: rulebookPath,
+                            op: "append-rule",
+                            line: finding.proposedRule,
+                            why: finding.finding
+                        });
+                        if (next !== undefined) {
+                            text = next;
+                            applied += 1;
+                        }
+                    }
+                    yield* opened.workspace.write(rulebookPath, text);
+                    yield* files.writeAtomic(reportPath, `${earlier.trimEnd()}\n${AppliedMarkerPrefix} ${new Date().toISOString()}\n`);
+                    yield* events.publish(Info.make({
+                        message: `port-guide: ${applied} rule(s) appended to ${join(opened.workspace.root, rulebookPath)}`
+                    }));
+                    return;
+                }
+            }
+        }
+        const manifest = yield* stage(events, "manifest", portManifest(repo, files, input.workDir, porting));
+        const sample = manifest.slice(0, sampleSize);
+        const sources = [];
+        for (const entry of sample) {
+            const text = (yield* files.read(join(input.workDir, entry.source))) ?? "";
+            sources.push(`### ${entry.source}\n\`\`\`\n${cap(text, Math.floor(knobs.sourceChars / Math.max(1, sample.length))).text}\n\`\`\``);
+        }
+        const samples = sources.join("\n\n");
+        const dimensions = porting.pack.audit ?? defaultAuditDimensions;
+        const auditor = (dimension) => structuredAndPublish(context.reasoning, events, [
+            `You audit a porting rulebook along one dimension: ${dimension}.`,
+            "Read the rulebook and the sample source files. Report as findings the places where the",
+            "rulebook is silent, ambiguous, or wrong for what the samples actually contain: a construct",
+            "the samples use that the rules do not map, a mapping that would produce wrong or",
+            "non-idiomatic target code, two rules that conflict. Each finding names its evidence (a",
+            "rulebook line or a sample line) and proposes one rule, one line, that would settle it.",
+            "Report nothing the rulebook already covers. Return ONLY JSON matching the schema.",
+            "",
+            "# Rulebook",
+            porting.rulebook,
+            "",
+            "# Sample sources",
+            samples
+        ].join("\n"), Findings, findingsJson, "auditor");
+        const audited = yield* stage(events, "audit", Effect.forEach(dimensions, auditor, { concurrency: 3 }));
+        let proposed = audited.flatMap((result) => result.findings);
+        const trial = [];
+        if (trialOn && sample.length > 0) {
+            yield* stage(events, "trial port", Effect.forEach(sample, (entry) => Effect.gen(function* () {
+                const source = (yield* files.read(join(input.workDir, entry.source))) ?? "";
+                const byRules = {
+                    ...entry,
+                    target: `.llm4ts/port/trial/by-rules/${entry.target}`
+                };
+                const native = { ...entry, target: `.llm4ts/port/trial/native/${entry.target}` };
+                const rulesChat = yield* makeChat(context.coder, {
+                    system: implementerSystem(porting),
+                    events,
+                    agent: "coder",
+                    stall: { repeats: 5 }
+                });
+                yield* rulesChat.ask(implementerPrompt(byRules, source, porting, knobs.sourceChars));
+                const nativeChat = yield* makeChat(context.coder, {
+                    system: nativeImplementerSystem(porting),
+                    events,
+                    agent: "coder",
+                    stall: { repeats: 5 }
+                });
+                yield* nativeChat.ask(`Port \`${entry.source}\` natively. Write the ported file at: ${native.target}\n\nSource file:\n\`\`\`\n${cap(source, knobs.sourceChars).text}\n\`\`\``);
+                const rulesDraft = (yield* files.read(join(input.workDir, byRules.target))) ?? "(no draft written)";
+                const nativeDraft = (yield* files.read(join(input.workDir, native.target))) ?? "(no draft written)";
+                const compared = yield* structuredAndPublish(context.reasoning, events, [
+                    `Compare the two drafts of \`${entry.source}\`: one written by the rulebook, one natively.`,
+                    "List the differences that matter (where the native port made a better or different",
+                    "choice than the rules forced), and for each that the rulebook should settle, a finding",
+                    "with evidence and one proposed rule. Return ONLY JSON matching the schema.",
+                    "",
+                    "# Rulebook",
+                    porting.rulebook,
+                    "",
+                    "# Draft by the rules",
+                    "```",
+                    cap(rulesDraft, 20_000).text,
+                    "```",
+                    "",
+                    "# Native draft",
+                    "```",
+                    cap(nativeDraft, 20_000).text,
+                    "```"
+                ].join("\n"), Trial, trialJson, "trial-compare");
+                trial.push(...compared.differences.map((line) => `${entry.source}: ${line}`));
+                proposed = [...proposed, ...compared.findings];
+            }), { concurrency: 1 }));
+        }
+        // Three refuters per finding; a majority rejecting drops it.
+        const kept = [];
+        const dropped = [];
+        yield* stage(events, "refute", Effect.forEach(proposed, (finding) => Effect.gen(function* () {
+            const votes = yield* Effect.forEach([1, 2, 3], (vote) => structuredAndPublish(context.reasoning, events, [
+                `Refuter ${vote} of 3. Does this finding hold against the rulebook and the samples?`,
+                "Refute it (holds: false) if the rulebook already covers it, if the evidence does not",
+                "show what the finding claims, or if the proposed rule contradicts another rule. Return",
+                "ONLY JSON matching the schema.",
+                "",
+                `Dimension: ${finding.dimension}`,
+                `Finding: ${finding.finding}`,
+                `Evidence: ${finding.evidence}`,
+                `Proposed rule: ${finding.proposedRule}`,
+                "",
+                "# Rulebook",
+                porting.rulebook,
+                "",
+                "# Sample sources",
+                samples
+            ].join("\n"), Refute, refuteJson, "refuter"), { concurrency: 3 });
+            if (standsAfterRefutes(votes.map((vote) => vote.holds)))
+                kept.push(finding);
+            else
+                dropped.push(finding);
+        }), { concurrency: 2 }));
+        yield* files.writeAtomic(reportPath, renderGuideAudit({
+            pack: porting.pack.name,
+            kept,
+            dropped,
+            trial,
+            sample: sample.map((entry) => entry.source)
+        }));
+        yield* files.writeAtomic(recordPath, `${encodeAudit(AuditRecord.make({ kept }))}\n`);
+        yield* events.publish(Info.make({
+            message: `port-guide: ${kept.length} finding(s) kept, ${dropped.length} dropped — read ${reportPath}, tick \`${ApprovedMarker}\`, run again to append the rules to ${rulebookPath}`
+        }));
+    }));
+});
+runFlowMain(program);

package/flows/port-ledger.js

@@ -0,0 +1,180 @@
+// A precomputed cross-file table for the implementers (ADR 0028, the Bun
+// port's LIFETIMES.tsv): every unit the pack's `## Ledger` regex names in a
+// source file is classified by the reasoning seat with the line that proves
+// it; UNKNOWN and low-confidence rows plus a fifth of the rest face three
+// refuters; the table lands beside the specs and `port-files` hands each
+// implementer its own rows, "trust the table over local guessing".
+//
+//   LLM4TS_PACK=zig-rust llm4ts run port-ledger --repo ~/src/bun
+//
+// Knobs: LLM4TS_PORT_CONCURRENCY (4), LLM4TS_PORT_SOURCE_CHARS (120000).
+import { join } from "node:path";
+import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import { cap } from "@llm4ts/flow/Context";
+import { FlowAborted } from "@llm4ts/flow/FlowError";
+import { Info } from "@llm4ts/flow/FlowEvents";
+import { LedgerRow, renderLedger, standsAfterRefutes, unitsIn } from "@llm4ts/flow/Port";
+import { runQueue } from "@llm4ts/flow/WorkQueue";
+import { asReadOnly, coderFromEnv, makeNodeWorkspace, nodePlainFileStore, openPack, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
+import { structuredAndPublish } from "@llm4ts/flow/Flow";
+import { asPortingPack, ledgerPath, portEnv, portManifest } from "./lib/port.js";
+class Classified extends Schema.Class("Classified")({
+    rows: Schema.Array(Schema.Struct({
+        unit: Schema.String,
+        class: Schema.String,
+        evidence: Schema.String,
+        confidence: Schema.Literals(["high", "medium", "low"])
+    }))
+}) {
+}
+const classifiedJson = {
+    type: "object",
+    properties: {
+        rows: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    unit: { type: "string" },
+                    class: { type: "string" },
+                    evidence: { type: "string" },
+                    confidence: { type: "string", enum: ["high", "medium", "low"] }
+                },
+                required: ["unit", "class", "evidence", "confidence"]
+            }
+        }
+    },
+    required: ["rows"]
+};
+class Refute extends Schema.Class("Refute")({
+    holds: Schema.Boolean,
+    why: Schema.String,
+    correctedClass: Schema.optionalKey(Schema.String)
+}) {
+}
+const refuteJson = {
+    type: "object",
+    properties: {
+        holds: { type: "boolean" },
+        why: { type: "string" },
+        correctedClass: { type: "string" }
+    },
+    required: ["holds", "why"]
+};
+const program = Effect.gen(function* () {
+    const input = yield* resolveFlowInput("Classify every unit the pack's ledger regex names");
+    const coder = coderFromEnv(process.env);
+    const files = nodePlainFileStore;
+    const knobs = portEnv(process.env);
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder,
+        reasoning: asReadOnly(coder),
+        reviewers: [asReadOnly(coder)],
+        environment: process.env
+    }, (context) => Effect.gen(function* () {
+        const events = context.events;
+        const repo = yield* makeNodeWorkspace(input.workDir);
+        const opened = yield* stage(events, "pack", openPack({
+            environment: process.env,
+            launchDir: input.workspace,
+            flowDir: import.meta.dirname
+        }));
+        const porting = yield* asPortingPack(opened);
+        const ledger = porting.pack.ledger;
+        if (ledger === undefined) {
+            return yield* FlowAborted.make({
+                message: `pack '${porting.pack.name}' has no '## Ledger' section (- unit: <regex>, - classes: …, - question: …)`
+            });
+        }
+        const classes = ledger.classes.length === 0 ? ["UNKNOWN"] : ledger.classes;
+        const unknown = classes.find((name) => name.toUpperCase() === "UNKNOWN") ?? "UNKNOWN";
+        const manifest = yield* stage(events, "manifest", portManifest(repo, files, input.workDir, porting));
+        const rows = yield* Ref.make([]);
+        const finished = yield* Ref.make(new Set());
+        yield* runQueue({
+            label: "ledger",
+            items: manifest,
+            done: (entry) => Effect.map(Ref.get(finished), (set) => set.has(entry.id)),
+            concurrency: knobs.concurrency,
+            maxRounds: 2,
+            events,
+            work: (entry) => Effect.gen(function* () {
+                const text = (yield* files.read(join(input.workDir, entry.source))) ?? "";
+                const units = unitsIn(text, ledger.unit);
+                if (units.length === 0) {
+                    yield* Ref.update(finished, (set) => new Set([...set, entry.id]));
+                    return { note: "no units" };
+                }
+                const classified = yield* structuredAndPublish(context.reasoning, events, [
+                    `Classify every unit listed below in \`${entry.source}\`. ${ledger.question}`,
+                    `Classes: ${classes.join(", ")}. Use ${unknown} when the file alone cannot tell.`,
+                    "For each unit give the class, the evidence as `file:line` of the statement that proves",
+                    "it (an initialisation, a deinit, an assignment), and your confidence. Return ONLY JSON",
+                    "matching the schema.",
+                    "",
+                    "Units:",
+                    ...units.map((unit) => `- unit: ${unit}`),
+                    "",
+                    "```",
+                    cap(text, knobs.sourceChars).text,
+                    "```"
+                ].join("\n"), Classified, classifiedJson, "ledger");
+                const settled = [];
+                for (const [index, row] of classified.rows.entries()) {
+                    if (!units.includes(row.unit))
+                        continue;
+                    const doubtful = row.class.toUpperCase() === unknown.toUpperCase() ||
+                        row.confidence === "low" ||
+                        index % 5 === 0;
+                    let klass = classes.includes(row.class) ? row.class : unknown;
+                    let confidence = row.confidence;
+                    if (doubtful) {
+                        const votes = yield* Effect.forEach([1, 2, 3], (vote) => structuredAndPublish(context.reasoning, events, [
+                            `Refuter ${vote} of 3. Does this classification hold? ${ledger.question}`,
+                            `Unit \`${row.unit}\` in \`${entry.source}\` was classified ${klass} (evidence: ${row.evidence}).`,
+                            `Classes: ${classes.join(", ")}. Refute it (holds: false) and give correctedClass when the`,
+                            "file shows a different class, or when the evidence does not support it. Return ONLY JSON.",
+                            "",
+                            "```",
+                            cap(text, knobs.sourceChars).text,
+                            "```"
+                        ].join("\n"), Refute, refuteJson, "ledger-refuter"), { concurrency: 3 });
+                        if (!standsAfterRefutes(votes.map((vote) => vote.holds))) {
+                            const corrected = votes
+                                .map((vote) => vote.correctedClass)
+                                .find((candidate) => candidate !== undefined && classes.includes(candidate));
+                            klass = corrected ?? unknown;
+                            confidence = corrected === undefined ? "low" : "medium";
+                        }
+                    }
+                    settled.push(LedgerRow.make({
+                        file: entry.source,
+                        unit: row.unit,
+                        class: klass,
+                        evidence: row.evidence,
+                        confidence
+                    }));
+                }
+                yield* Ref.update(rows, (all) => [...all, ...settled]);
+                yield* Ref.update(finished, (set) => new Set([...set, entry.id]));
+                return { note: `${settled.length} unit(s)` };
+            })
+        });
+        const all = [...(yield* Ref.get(rows))].sort((left, right) => `${left.file}\t${left.unit}`.localeCompare(`${right.file}\t${right.unit}`));
+        const path = ledgerPath(porting);
+        yield* files.writeAtomic(join(input.workDir, path), renderLedger(all));
+        yield* context.git.commitPaths(`port: ledger of ${all.length} unit(s)`, [path]);
+        const counts = new Map();
+        for (const row of all)
+            counts.set(row.class, (counts.get(row.class) ?? 0) + 1);
+        yield* events.publish(Info.make({
+            message: `port-ledger: ${all.length} unit(s) in ${manifest.length} file(s) → ${path} (${[...counts.entries()].map(([klass, count]) => `${klass} ${count}`).join(", ")})`
+        }));
+    }));
+});
+runFlowMain(program);

package/flows/port-tests.js

@@ -0,0 +1,177 @@
+// The differential tier (ADR 0028, the Bun port's test swarm): every test
+// file runs once on the legacy build for a baseline, then on the target; a
+// file passes when the target exits 0 and its pass count equals the
+// baseline's; the rest are classified diverge, crash or hang and written as
+// `.diag` files; one fixer per red file reads its diag as its only runtime
+// evidence; two votes review; one rebuild per round; until green or stalled.
+//
+//   LLM4TS_PACK=zig-rust llm4ts run port-tests --repo ~/src/bun
+//
+// Knobs: LLM4TS_PORT_CONCURRENCY (4), LLM4TS_REVIEW_VOTES (2 here),
+// LLM4TS_PORT_TEST_ROUNDS (4), LLM4TS_GATE_TAIL_CHARS (4000).
+import { join } from "node:path";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import { makeChat } from "@llm4ts/flow/Chat";
+import { FlowAborted, Stalled } from "@llm4ts/flow/FlowError";
+import { Info } from "@llm4ts/flow/FlowEvents";
+import { diffVerdict, renderDiag, renderDifferentialReport } from "@llm4ts/flow/Port";
+import { ReviewResult, adversarialReviewer, lintCommand, reviewAndFixLoop } from "@llm4ts/flow/Review";
+import { matchingFiles } from "@llm4ts/flow/SpecChecks";
+import { runQueue } from "@llm4ts/flow/WorkQueue";
+import { asReadOnly, coderFromEnv, makeNodeWorkspace, nodePlainFileStore, nodeProcessExecutor, openPack, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
+import { asPortingPack, compileFixerSystem, portEnv, portStateDir } from "./lib/port.js";
+const Baseline = Schema.fromJsonString(ReviewResult);
+const encodeBaseline = Schema.encodeSync(Baseline);
+const decodeBaseline = Schema.decodeUnknownOption(Baseline);
+const slug = (path) => path.replace(/[^a-z0-9]+/giu, "-").replace(/^-|-$/gu, "");
+const program = Effect.gen(function* () {
+    const input = yield* resolveFlowInput("Run every test file on the legacy and the target build, fix what diverges");
+    const coder = coderFromEnv(process.env);
+    const files = nodePlainFileStore;
+    const knobs = portEnv(process.env);
+    const maxRounds = Math.max(1, Number.parseInt(process.env.LLM4TS_PORT_TEST_ROUNDS ?? "4", 10) || 4);
+    const tailChars = Math.max(500, Number.parseInt(process.env.LLM4TS_GATE_TAIL_CHARS ?? "4000", 10) || 4000);
+    const stateDir = join(portStateDir(input.workDir), "tests");
+    yield* runNode({
+        workDir: input.workDir,
+        workspace: input.workspace,
+        userPrompt: input.prompt,
+        coder,
+        reasoning: asReadOnly(coder),
+        reviewers: [asReadOnly(coder)],
+        environment: process.env
+    }, (context) => Effect.gen(function* () {
+        const events = context.events;
+        const repo = yield* makeNodeWorkspace(input.workDir);
+        const opened = yield* stage(events, "pack", openPack({
+            environment: process.env,
+            launchDir: input.workspace,
+            flowDir: import.meta.dirname
+        }));
+        const porting = yield* asPortingPack(opened);
+        const differential = porting.pack.differential;
+        if (differential === undefined) {
+            return yield* FlowAborted.make({
+                message: `pack '${porting.pack.name}' has no '## Differential' section (- tests: <regex>, - legacy: <cmd {{file}}>, - target: <cmd {{file}}>)`
+            });
+        }
+        const timeout = Duration.seconds(differential.timeoutSeconds);
+        const testFiles = yield* stage(events, "test files", matchingFiles(repo, differential.tests, porting.pack.exclude));
+        const command = (template, file) => template.map((part) => part.replaceAll("{{file}}", file));
+        const build = porting.pack.gate("build") ?? porting.pack.gate("check");
+        const baselineOf = (file) => Effect.gen(function* () {
+            const path = join(stateDir, `${slug(file)}.baseline.json`);
+            const stored = yield* files.read(path);
+            const decoded = stored === undefined ? undefined : decodeBaseline(stored);
+            if (decoded !== undefined && decoded._tag === "Some")
+                return decoded.value;
+            const legacy = yield* lintCommand(nodeProcessExecutor, events, command(differential.legacy, file), input.workDir, { timeout });
+            yield* files.writeAtomic(path, encodeBaseline(legacy));
+            return legacy;
+        });
+        let previous;
+        let flat = 0;
+        for (let round = 1; round <= maxRounds; round += 1) {
+            if (build !== undefined) {
+                const built = yield* stage(events, `build round ${round}`, lintCommand(nodeProcessExecutor, events, build, input.workDir, {
+                    timeout: Duration.minutes(20)
+                }));
+                if (!built.isClean) {
+                    return yield* FlowAborted.make({
+                        message: `the target does not build; run port-compile first:\n${built.issues
+                            .map((issue) => issue.description)
+                            .join("\n")
+                            .slice(-tailChars)}`
+                    });
+                }
+            }
+            const verdicts = yield* stage(events, `differential round ${round}`, Effect.forEach(testFiles, (file) => Effect.gen(function* () {
+                const legacy = yield* baselineOf(file);
+                const target = yield* lintCommand(nodeProcessExecutor, events, command(differential.target, file), input.workDir, { timeout });
+                const verdict = diffVerdict(file, legacy, target, [input.workDir]);
+                if (verdict.class !== "pass" && verdict.class !== "legacy-red") {
+                    yield* files.writeAtomic(join(stateDir, `${slug(file)}.diag.md`), renderDiag(verdict, tailChars));
+                }
+                return verdict;
+            }), { concurrency: knobs.concurrency }));
+            yield* files.writeAtomic(join(stateDir, `report-${round}.md`), renderDifferentialReport(round, verdicts));
+            const red = verdicts.filter((verdict) => verdict.class === "diverge" || verdict.class === "crash" || verdict.class === "hang");
+            yield* events.publish(Info.make({
+                message: `port-tests: round ${round}, ${verdicts.length} file(s): ${verdicts.length - red.length - verdicts.filter((v) => v.class === "legacy-red").length} pass, ${red.length} red, ${verdicts.filter((v) => v.class === "legacy-red").length} red on legacy too`
+            }));
+            if (red.length === 0) {
+                yield* events.publish(Info.make({
+                    message: `port-tests: green after ${round} round(s) — reports under ${stateDir}`
+                }));
+                return;
+            }
+            if (previous !== undefined && red.length >= previous) {
+                flat += 1;
+                if (flat >= 2) {
+                    return yield* Stalled.make({
+                        signal: "no-progress",
+                        detail: `port-tests: ${red.length} red file(s) after round ${round}, no fewer than before`
+                    });
+                }
+            }
+            else {
+                flat = 0;
+            }
+            previous = red.length;
+            if (round === maxRounds)
+                break;
+            const finished = yield* Ref.make(new Set());
+            yield* runQueue({
+                label: `port-tests fix round ${round}`,
+                items: red.map((verdict) => ({ id: verdict.file, verdict })),
+                done: (item) => Effect.map(Ref.get(finished), (set) => set.has(item.id)),
+                concurrency: knobs.concurrency,
+                maxRounds: 1,
+                events,
+                ledger: { files, path: join(stateDir, "fix-ledger.jsonl") },
+                work: (item) => Effect.gen(function* () {
+                    const diag = (yield* files.read(join(stateDir, `${slug(item.id)}.diag.md`))) ??
+                        renderDiag(item.verdict, tailChars);
+                    const chat = yield* makeChat(context.coder, {
+                        system: compileFixerSystem(porting),
+                        events,
+                        agent: "coder",
+                        stall: { repeats: 5 }
+                    });
+                    yield* chat.ask([
+                        `Test file \`${item.id}\` passes on the legacy build and is ${item.verdict.class} on the target.`,
+                        "The diagnostic below is your ONLY runtime evidence: fix the target code it points at (never",
+                        "the test), do not rebuild or run tests yourself, and say `confidence: low` if you are",
+                        "guessing without runtime confirmation.",
+                        "",
+                        diag
+                    ].join("\n"));
+                    yield* reviewAndFixLoop({
+                        reviewers: [adversarialReviewer, ...porting.pack.lenses],
+                        reviewerService: context.reviewers[0] ?? context.reasoning,
+                        coder: chat,
+                        taskTitle: `port-tests ${item.id}`,
+                        currentDiff: context.git.diffAll,
+                        events,
+                        maxRounds: 2,
+                        votes: knobs.votes,
+                        oracle: { diff: context.git.diffAll }
+                    });
+                    yield* Ref.update(finished, (set) => new Set([...set, item.id]));
+                    return { note: item.verdict.class };
+                })
+            }).pipe(Effect.catchTag("Stalled", () => Effect.void));
+            const dirty = yield* context.git.uncommittedFiles;
+            if (dirty.length > 0) {
+                yield* context.git.commitAll(`port-tests: round ${round}, ${red.length} red file(s) worked`);
+            }
+        }
+        yield* events.publish(Info.make({
+            message: `port-tests: ${maxRounds} round(s) done, red files remain — see ${stateDir}`
+        }));
+    }));
+});
+runFlowMain(program);

package/kits/port/README.md

@@ -0,0 +1,32 @@
+# port
+
+Language-to-language ports, file by file, the way Bun was rewritten from Zig
+to Rust in May 2026 (ADR 0028): a rulebook the human writes with the model, a
+pilot of a few files behind an approval, then every source file drafted at its
+target path by one implementer with exactly one source in view, reviewed by
+two adversarial votes, fixed by a separate fixer, ending in a `PORT STATUS`
+trailer; then compiler diagnostics worked as a queue, one unit per fixer, one
+rebuild per round. The source stays in the tree as the spec: this kit is not
+clean-room.
+
+```text
+kits/port/
+  packs/zig-rust/     the reference pair, distilled from the Bun port
+    pack.md           sources:, target:, comment:, ## Gates, ## Diagnostics
+    prompts/porting.md   the rulebook every implementer reads whole
+    reviewers/         lenses that diff source and target
+    patterns/pitfalls-zig-rust.md   syntactically alike, semantically different
+```
+
+Flows, in the order a port runs them: `port-guide` (audit the rulebook on a
+few samples, behind an approval), `port-ledger` (classify the units the pack
+names into `ledger.tsv`), `port-files` (drafts, with a pilot), `port-compile`
+(diagnostics as a queue), `port-tests` (the differential tier). A pack for
+another pair copies one of these and replaces the rulebook, the pitfall card,
+`target:`, the diagnostics command, the ledger regex and the two test
+commands.
+
+| Pack       | Source → target                 | Diagnostics                         | Ledger units             |
+| ---------- | ------------------------------- | ----------------------------------- | ------------------------ |
+| `zig-rust` | Zig → Rust                      | `cargo check --message-format=json` | pointer and slice fields |
+| `scala-ts` | Scala 3 / ZIO 2 → TS / Effect 4 | `tsc --pretty false`                | classes, objects, traits |

package/kits/port/packs/scala-ts/pack.md

@@ -0,0 +1,36 @@
+# Pack: scala-ts
+
+source: scala
+sources: .*\.scala$
+exclude: (^|/)(target|node_modules|\.bloop|\.metals|project)/
+target: {{dir}}/{{base}}.ts
+comment: //
+specs-dir: docs/port
+features-dir: docs/port/features
+
+## Gates
+
+- typecheck: pnpm typecheck
+- test: pnpm test
+
+## Diagnostics
+
+- command: pnpm exec tsc -p tsconfig.json --pretty false
+- format: tsc
+
+## Ledger
+
+- unit: ^\s*(?:final\s+)?(?:case\s+)?(?:class|object|trait|enum)\s+(\w+)
+- classes: SERVICE, LAYER, DATA, ERROR, STREAM, TEST, UTIL, UNKNOWN
+- question: What kind of thing is this declaration in an Effect port? SERVICE (a ZIO service trait → Context.Service), LAYER (a ZLayer → Layer), DATA (a case class or enum → Schema.Class or a tagged union), ERROR (an error ADT → Schema.TaggedError), STREAM (ZStream producer → Stream), TEST (a spec → @effect/vitest), UTIL (pure helpers).
+
+## Audit
+
+- dimensions: error channel and variance, services and layers, data modelling and schemas, streams and resources, concurrency primitives, test idioms, what not to translate
+
+## Review rules
+
+`any`, unchecked casts, namespaces and a global `Error` in the error channel
+are findings. Every expected failure is a `Schema.TaggedError`; every
+replaceable dependency is a service with a layer. Relative imports carry `.ts`
+extensions.