@llm4ts/shell 2.33.0 → 2.34.0

package/flows/lib/port.js

@@ -8,7 +8,7 @@ import { autonomyContract } from "@llm4ts/flow/AutonomyContract";
 import { cap } from "@llm4ts/flow/Context";
 import { FlowAborted } from "@llm4ts/flow/FlowError";
 import { loadPatternCards } from "@llm4ts/flow/Patterns";
-import { PortEntry, linesOf, portStatusInstruction, targetPathOf } from "@llm4ts/flow/Port";
+import { PortEntry, linesOf, parseLedger, portStatusInstruction, targetPathOf } from "@llm4ts/flow/Port";
 import { matchingFiles } from "@llm4ts/flow/SpecChecks";
 /** Where the port flows keep their state, under the target repository. */
 export const portStateDir = (workDir) => join(workDir, ".llm4ts", "port");
@@ -73,9 +73,16 @@ export const implementerSystem = (porting) => [
     "",
     implementerDenials
 ].join("\n");
-export const implementerPrompt = (entry, sourceText, porting, sourceChars) => [
+export const implementerPrompt = (entry, sourceText, porting, sourceChars, ledgerRows) => [
     `Port \`${entry.source}\` (${entry.loc} lines). Write the ported file at: ${entry.target}`,
     "The draft need not compile; it must capture the logic faithfully.",
+    ...(ledgerRows === undefined
+        ? []
+        : [
+            "",
+            "Precomputed classifications for this file (cross-file analysis; trust them over local guessing):",
+            ledgerRows
+        ]),
     "",
     portStatusInstruction(porting.comment),
     "",
@@ -111,6 +118,20 @@ export const compileFixerSystem = (porting) => [
     "# Porting rulebook",
     porting.rulebook
 ].join("\n");
+/** The ledger the pack's `port-ledger` writes, beside the specs; `undefined` when none. */
+export const ledgerPath = (porting) => `${porting.pack.specsDir}/ledger.tsv`;
+export const readLedgerRows = (files, workDir, porting) => Effect.map(files.read(join(workDir, ledgerPath(porting))), (text) => text === undefined ? [] : parseLedger(text));
+/** A native engineer's brief for the trial port: no rulebook, idiomatic target code. */
+export const nativeImplementerSystem = (porting) => [
+    autonomyContract("minimal"),
+    "",
+    `You are a senior engineer in the target language of pack ${porting.pack.name}. Port the`,
+    "source file the way you would write it natively and idiomatically, with no rulebook: your",
+    "draft is compared with a rules-following draft to find what the rulebook forgot. Read",
+    "exactly one source file; do not run a build or any git command; write only the target file.",
+    "",
+    implementerDenials
+].join("\n");
 export const portEnv = (environment) => {
     const int = (raw, fallback, min = 1) => {
         const value = Number.parseInt(raw ?? "", 10);

package/flows/port-files.js

@@ -17,11 +17,11 @@ import * as Effect from "effect/Effect";
 import { ApprovedMarker, requireApproval } from "@llm4ts/flow/Approval";
 import { makeChat } from "@llm4ts/flow/Chat";
 import { Info } from "@llm4ts/flow/FlowEvents";
-import { asAddedFileDiff, batchesOf, portStatusIn, renderPilotReport } from "@llm4ts/flow/Port";
+import { asAddedFileDiff, batchesOf, ledgerRowsFor, portStatusIn, renderPilotReport } from "@llm4ts/flow/Port";
 import { adversarialReviewer, reviewAndFixLoop } from "@llm4ts/flow/Review";
 import { runQueue } from "@llm4ts/flow/WorkQueue";
 import { asReadOnly, coderFromEnv, makeNodeWorkspace, nodePlainFileStore, openPack, resolveFlowInput, runFlowMain, runNode, stage } from "@llm4ts/runner";
-import { asPortingPack, implementerPrompt, implementerSystem, portEnv, portFixerSystem, portManifest, portStateDir } from "./lib/port.js";
+import { asPortingPack, implementerPrompt, implementerSystem, ledgerPath, portEnv, readLedgerRows, portFixerSystem, portManifest, portStateDir } from "./lib/port.js";
 const renderReport = (outcomes, total, pending) => {
     const done = outcomes.filter((outcome) => outcome.status === "done");
     const failed = outcomes.filter((outcome) => outcome.status === "failed");
@@ -85,6 +85,13 @@ const program = Effect.gen(function* () {
             yield* requireApproval(files, pilotPath);
         }
         const items = knobs.pilot > 0 ? pending.slice(0, knobs.pilot) : pending;
+        // A ledger written by port-ledger rides into every implementer prompt.
+        const ledger = yield* readLedgerRows(files, input.workDir, porting);
+        if (ledger.length > 0) {
+            yield* events.publish(Info.make({
+                message: `port: ${ledger.length} ledger row(s) from ${ledgerPath(porting)}`
+            }));
+        }
         const batches = batchesOf(items, { files: knobs.batch });
         const started = yield* Clock.currentTimeMillis;
         const outcomes = [];
@@ -108,7 +115,7 @@ const program = Effect.gen(function* () {
                         agent: "coder",
                         stall: { repeats: 5 }
                     });
-                    yield* chat.ask(implementerPrompt(entry, source, porting, knobs.sourceChars));
+                    yield* chat.ask(implementerPrompt(entry, source, porting, knobs.sourceChars, ledgerRowsFor(ledger, entry.source)));
                     const targetPath = join(input.workDir, entry.target);
                     if ((yield* files.read(targetPath)) === undefined) {
                         return { note: `nothing written at ${entry.target}` };

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

@@ -18,10 +18,15 @@ kits/port/
     patterns/pitfalls-zig-rust.md   syntactically alike, semantically different
 ```
 
-Flows: `port-files` (drafts), `port-compile` (diagnostics as a queue). A
-pack for another pair copies `zig-rust` and replaces the rulebook, the
-pitfall card, `target:` and the diagnostics command.
+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                         |
-| ---------- | --------------- | ----------------------------------- |
-| `zig-rust` | Zig → Rust      | `cargo check --message-format=json` |
+| 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.

package/kits/port/packs/scala-ts/patterns/pitfalls-scala-ts.md

@@ -0,0 +1,21 @@
+---
+title: Scala/ZIO → TypeScript/Effect pitfalls — alike on the page, different at runtime
+matches: .
+tags: port, scala, zio, effect
+---
+1. **Type parameter order.** `ZIO[R, E, A]` is `Effect<A, E, R>`: a mechanical
+   copy of the parameter list silently swaps the requirement and the value.
+2. **Equality.** `==` on a case class compares structure; `===` on an object
+   compares identity. Use `Equal.equals` or compare fields.
+3. **Laziness.** A Scala `lazy val` or by-name parameter evaluates once or on
+   demand; a TypeScript expression evaluates where it is written. Wrap in a
+   thunk or `Effect.suspend`.
+4. **Option.get and head.** Scala throws; TypeScript yields `undefined` and
+   carries on. Make the absence a typed failure.
+5. **Integer division and overflow.** Scala `Int` wraps at 32 bits and `/`
+   truncates; JavaScript numbers are doubles. Use `Math.trunc` and check
+   ranges where the source relied on `Int`.
+6. **String formatting and `toString`.** A Scala `toString` on a case class
+   prints its fields; the TypeScript default prints `[object Object]`.
+7. **Implicit conversions and givens.** They vanish in the port; every one is
+   an explicit call or a service the draft must name.

package/kits/port/packs/scala-ts/prompts/porting.md

@@ -0,0 +1,64 @@
+You are translating one Scala 3 / ZIO 2 file to TypeScript with Effect 4.
+Read this whole document before writing any code. The first pass is a
+**draft** `.ts` beside the `.scala`, same basename, that captures the logic
+faithfully; it does **not** need to type-check. The compile pass makes it
+type-check module by module.
+
+## Ground rules
+
+- Same module, same names (camelCase for values, PascalCase for types), same
+  order of declarations, same control flow. Reviewers diff the two files side
+  by side.
+- Use Effect 4 as the repository uses it: `Effect.gen` for sequencing,
+  `Effect.fn` for named reusable operations, `Context.Service` and `Layer` for
+  replaceable dependencies, `Schema.Class` / `Schema.TaggedClass` for data,
+  `Schema.TaggedError` for expected failures. Never `any`, never an unchecked
+  cast, never a global `Error` as a domain error.
+- Relative imports use `.ts` extensions; a module imports a contract, never a
+  sibling's internals.
+- Leave `// TODO(port): <reason>` for anything you cannot translate
+  confidently. Do not guess.
+- Do not translate build definitions, sbt plugins or Scala-only tooling;
+  note them as `// SKIPPED(port): <what>`.
+
+## Type map
+
+| Scala / ZIO                          | TypeScript / Effect                            |
+| ------------------------------------ | ---------------------------------------------- |
+| `ZIO[R, E, A]`                       | `Effect.Effect<A, E, R>` (note the order)      |
+| `UIO[A]` / `Task[A]`                 | `Effect.Effect<A>` / `Effect.Effect<A, UnknownException>` |
+| `ZStream[R, E, A]`                   | `Stream.Stream<A, E, R>`                       |
+| `ZLayer[RIn, E, ROut]`               | `Layer.Layer<ROut, E, RIn>`                    |
+| `trait Service` + `ZIO.service`      | `Context.Service` class + `yield* Service`     |
+| `case class`                         | `Schema.Class`                                 |
+| `enum` / sealed trait ADT            | `Schema.Union` of `Schema.TaggedClass`         |
+| `Option[A]`                          | optional property / `A \| undefined`           |
+| `Either[E, A]`                       | `Result` or `Effect.Effect<A, E>`              |
+| `Chunk[A]`                           | `ReadonlyArray<A>`                             |
+| `Ref[A]`, `Queue[A]`, `Hub[A]`       | `Ref`, `Queue`, `PubSub`                       |
+| `Scope` / `acquireRelease`           | `Scope` / `Effect.acquireRelease`              |
+| `Schedule`                           | `Schedule`                                     |
+| zio-json codecs                      | `Schema` with `Schema.fromJsonString`          |
+| ZIO Test `spec` / `test`             | `@effect/vitest` `describe` / `it.effect`      |
+| `for` comprehension                  | `Effect.gen(function* () { … })`               |
+
+## Idiom map
+
+- `ZIO.attempt(…)` → `Effect.try(…)`; `ZIO.fail(E)` → `Effect.fail(E)`; `.orDie` → `Effect.orDie`.
+- `.provide(layer)` / `.provideSome` → `Effect.provide(layer)`; layer composition order follows `Layer.provide`.
+- `.catchSome { case e: X => … }` → `Effect.catchTag("X", …)`.
+- `zio.Duration` → `Duration` from effect; `ZIO.sleep` → `Effect.sleep`.
+- Implicit parameters and givens become explicit arguments or services.
+- `==` on case classes is structural; TypeScript needs `Equal.equals` or a field-by-field compare.
+
+## Output format
+
+End the file with the trailer the flow reads:
+
+```ts
+// PORT STATUS
+// source: <path>.scala
+// confidence: high | medium | low
+// todos: <count of TODO(port)>
+// notes: <one line>
+```

package/kits/port/packs/scala-ts/reviewers/effect-fidelity.md

@@ -0,0 +1,13 @@
+---
+files: \.ts$
+---
+Review a TypeScript draft against the rulebook as a port reviewer would, with
+the Scala source in mind: the diff is the draft. Report as findings: a method,
+field or case the source has that the draft lacks; `any`, an unchecked cast, a
+namespace, or a global `Error` in an error channel; a service without a layer
+where the source had a `ZLayer`; a relative import without a `.ts` extension;
+a case class turned into a plain interface where a `Schema.Class` belongs;
+`ZIO[R, E, A]` order kept as `Effect<R, E, A>`; a `for` comprehension turned
+into nested callbacks where `Effect.gen` was the answer; a guessed translation
+where a `TODO(port)` was honest. Do not report imports that cannot resolve
+yet: the compile pass owns those.

package/kits/port/packs/zig-rust/pack.md

@@ -17,6 +17,23 @@ features-dir: docs/port/features
 - command: cargo check --workspace --message-format=json
 - format: cargo
 
+## Ledger
+
+- unit: ^\s+(\w+):\s*(?:\?\*|\*|\[\]|\[\*\])
+- classes: OWNED, SHARED, BORROW_PARAM, BORROW_FIELD, STATIC, JSC_BORROW, BACKREF, INTRUSIVE, FFI, ARENA, UNKNOWN
+- question: Who owns the memory this pointer or slice field points at, and how long does it live? The Rust type follows from the class (OWNED → Box/Vec, BORROW_* → a reference with a lifetime, SHARED → Rc/Arc, FFI → a raw pointer).
+
+## Differential
+
+- tests: ^test/.*\.test\.(ts|js)$
+- legacy: scripts/legacy-test.sh {{file}}
+- target: scripts/target-test.sh {{file}}
+- timeout: 60
+
+## Audit
+
+- dimensions: error model, allocator threading, collections and strings, comptime carry-over, pointer and ownership idioms, API shape, what not to translate
+
 ## Review rules
 
 Every `unsafe` block carries a `// SAFETY: <why>` comment, and no new

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/shell",
-  "version": "2.33.0",
+  "version": "2.34.0",
   "description": "Interactive shell and CLI for llm4ts: flow discovery, run-a-flow, and view",
   "license": "MIT",
   "type": "module",
@@ -52,9 +52,9 @@
   "dependencies": {
     "@effect/platform-node": "4.0.0",
     "@effect/platform-node-shared": "4.0.0",
-    "@llm4ts/core": "2.33.0",
-    "@llm4ts/flow": "2.33.0",
-    "@llm4ts/runner": "2.33.0"
+    "@llm4ts/core": "2.34.0",
+    "@llm4ts/flow": "2.34.0",
+    "@llm4ts/runner": "2.34.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"