@llm4ts/flow 0.17.0 → 0.18.0

package/dist/Approval.d.ts

@@ -0,0 +1,27 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { PlainFileStoreShape } from "./Persistence.ts";
+declare const ApprovalRequired_base: Schema.Class<ApprovalRequired, Schema.TaggedStruct<"ApprovalRequired", {
+    readonly path: Schema.String;
+    readonly marker: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The human gates of the modernization phases: a markdown document ends
+ * with a draft marker the flow writes, and the next phase refuses to start
+ * until a person has ticked it. (Moved from `@llm4ts/modernize` in 0.18.0.)
+ */
+export declare class ApprovalRequired extends ApprovalRequired_base {
+    get message(): string;
+}
+declare const MissingModernizeArtifact_base: Schema.Class<MissingModernizeArtifact, Schema.TaggedStruct<"MissingModernizeArtifact", {
+    readonly path: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class MissingModernizeArtifact extends MissingModernizeArtifact_base {
+}
+export declare const ApprovedMarker = "- [x] Approved";
+export declare const DraftApprovalMarker = "- [ ] Approved";
+export declare const withDraftApproval: (markdown: string) => string;
+export declare const requireApproval: (files: PlainFileStoreShape, path: string) => Effect.Effect<void, import("./FlowError.ts").PersistenceError | import("./FlowError.ts").PlanParseError | import("./FlowError.ts").UnsupportedSchemaVersion | import("./FlowError.ts").WorkspacePathError | import("./FlowError.ts").WorkspaceLimitError | import("./FlowError.ts").WorkspaceIoError | import("./FlowError.ts").FlowAborted | import("./FlowError.ts").ProcessError | import("./FlowError.ts").FlowLlmError | import("./FlowError.ts").FlowCapabilityDenied | import("./FlowError.ts").ColumnNotFound | import("./FlowError.ts").BudgetExceeded | import("./FlowError.ts").StoryPlanInvalid | import("./FlowError.ts").PerimeterViolation | import("./FlowError.ts").MissingDependency | import("./FlowError.ts").MergeConflict | import("./FlowError.ts").StoryFailed | ApprovalRequired | MissingModernizeArtifact, never>;
+export {};
+//# sourceMappingURL=Approval.d.ts.map

package/dist/Approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Approval.d.ts","sourceRoot":"","sources":["../src/Approval.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;;;;;AAE3D;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,qBAMrC;IACC,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF;;;;;AAED,qBAAa,wBAAyB,SAAQ,6BAM7C;CAAG;AAEJ,eAAO,MAAM,cAAc,mBAAmB,CAAA;AAC9C,eAAO,MAAM,mBAAmB,mBAAmB,CAAA;AAEnD,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,MACA,CAAA;AAErD,eAAO,MAAM,eAAe,41BAc1B,CAAA"}

package/dist/Approval.js

@@ -0,0 +1,36 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/**
+ * The human gates of the modernization phases: a markdown document ends
+ * with a draft marker the flow writes, and the next phase refuses to start
+ * until a person has ticked it. (Moved from `@llm4ts/modernize` in 0.18.0.)
+ */
+export class ApprovalRequired extends Schema.TaggedErrorClass()("ApprovalRequired", {
+    path: Schema.String,
+    marker: Schema.String
+}) {
+    get message() {
+        return `approval required in ${this.path}: set '${this.marker}'`;
+    }
+}
+export class MissingModernizeArtifact extends Schema.TaggedErrorClass()("MissingModernizeArtifact", {
+    path: Schema.String,
+    message: Schema.String
+}) {
+}
+export const ApprovedMarker = "- [x] Approved";
+export const DraftApprovalMarker = "- [ ] Approved";
+export const withDraftApproval = (markdown) => `${markdown.trimEnd()}\n\n${DraftApprovalMarker}\n`;
+export const requireApproval = Effect.fn("@llm4ts/flow/Approval.requireApproval")(function* (files, path) {
+    const contents = yield* files.read(path);
+    if (contents === undefined) {
+        return yield* MissingModernizeArtifact.make({
+            path,
+            message: `approval document does not exist: ${path}`
+        });
+    }
+    if (!contents.includes(ApprovedMarker)) {
+        return yield* ApprovalRequired.make({ path, marker: ApprovedMarker });
+    }
+});
+//# sourceMappingURL=Approval.js.map

package/dist/Approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Approval.js","sourceRoot":"","sources":["../src/Approval.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,MAAM,CAAC,gBAAgB,EAAoB,CAC/E,kBAAkB,EAClB;IACE,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM;CACtB,CACF;IACC,IAAI,OAAO;QACT,OAAO,wBAAwB,IAAI,CAAC,IAAI,UAAU,IAAI,CAAC,MAAM,GAAG,CAAA;IAClE,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,MAAM,CAAC,gBAAgB,EAA4B,CAC/F,0BAA0B,EAC1B;IACE,IAAI,EAAE,MAAM,CAAC,MAAM;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM;CACvB,CACF;CAAG;AAEJ,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAA;AAC9C,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAgB,CAAA;AAEnD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,QAAgB,EAAU,EAAE,CAC5D,GAAG,QAAQ,CAAC,OAAO,EAAE,OAAO,mBAAmB,IAAI,CAAA;AAErD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,EAAE,CAAC,uCAAuC,CAAC,CAAC,QAAQ,CAAC,EACzF,KAA0B,EAC1B,IAAY;IAEZ,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACxC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,CAAC,wBAAwB,CAAC,IAAI,CAAC;YAC1C,IAAI;YACJ,OAAO,EAAE,qCAAqC,IAAI,EAAE;SACrD,CAAC,CAAA;IACJ,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACvC,OAAO,KAAK,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;IACvE,CAAC;AACH,CAAC,CAAC,CAAA"}

package/dist/Artifacts.d.ts

@@ -0,0 +1,57 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { PlainFileStoreShape } from "./Persistence.ts";
+declare const ProgramUnit_base: Schema.Class<ProgramUnit, Schema.Struct<{
+    readonly name: Schema.String;
+    readonly sourcePath: Schema.String;
+}>, {}>;
+export declare class ProgramUnit extends ProgramUnit_base {
+}
+declare const ProgramArtifacts_base: Schema.Class<ProgramArtifacts, Schema.Struct<{
+    readonly spec: Schema.String;
+    readonly feature: Schema.String;
+    readonly traceability: Schema.String;
+    readonly mapping: Schema.String;
+}>, {}>;
+export declare class ProgramArtifacts extends ProgramArtifacts_base {
+}
+declare const ResumeSummary_base: Schema.Class<ResumeSummary, Schema.Struct<{
+    readonly created: Schema.$Array<Schema.String>;
+    readonly skipped: Schema.$Array<Schema.String>;
+}>, {}>;
+export declare class ResumeSummary extends ResumeSummary_base {
+}
+/** The four per-program artifact paths under `directory`, relative to the repository. */
+export declare const programArtifactPaths: (unit: ProgramUnit, directory?: string) => ReadonlyArray<string>;
+export interface ExtractProgramsOptions<E2, R2> {
+    /**
+     * How many programs extract at once (default 1: the sequential order the
+     * units were given in). The programs of a wave are independent — each
+     * analyst reads only its source and resolved closure and writes only its
+     * own four files — so the bound is about the model seat's quota, not about
+     * correctness.
+     */
+    readonly concurrency?: number;
+    /**
+     * Runs after a program's four artifacts are on disk and before it counts as
+     * created — the seam for per-program post-processing (pattern tagging, the
+     * program's own commit). Runs under the same concurrency as extraction:
+     * anything in it that must not interleave (git) serialises itself.
+     */
+    readonly onCreated?: (unit: ProgramUnit) => Effect.Effect<void, E2, R2>;
+}
+/**
+ * Extracts every unit whose spec is missing, writes its four artifacts, and
+ * reports what was created and what was skipped. Resumable by construction:
+ * a rerun skips every program whose spec exists.
+ *
+ * Failure keeps finished work: a program that fails stops NEW programs from
+ * starting, but programs already in flight run to completion and land on
+ * disk (and through `onCreated`) before the first failure, in unit order, is
+ * re-raised. With `concurrency` 1 that is exactly fail-fast; above 1 a quota
+ * death costs only the programs it interrupted, and a rerun resumes the rest.
+ */
+export declare const extractProgramsResumably: <E, R, E2 = never, R2 = never>(files: PlainFileStoreShape, units: readonly ProgramUnit[], extract: (unit: ProgramUnit) => Effect.Effect<ProgramArtifacts, E, R>, directory?: string | undefined, options?: ExtractProgramsOptions<E2, R2> | undefined) => Effect.Effect<ResumeSummary, import("./FlowError.ts").PersistenceError | import("./FlowError.ts").PlanParseError | import("./FlowError.ts").UnsupportedSchemaVersion | import("./FlowError.ts").WorkspacePathError | import("./FlowError.ts").WorkspaceLimitError | import("./FlowError.ts").WorkspaceIoError | import("./FlowError.ts").FlowAborted | import("./FlowError.ts").ProcessError | import("./FlowError.ts").FlowLlmError | import("./FlowError.ts").FlowCapabilityDenied | import("./FlowError.ts").ColumnNotFound | import("./FlowError.ts").BudgetExceeded | import("./FlowError.ts").StoryPlanInvalid | import("./FlowError.ts").PerimeterViolation | import("./FlowError.ts").MissingDependency | import("./FlowError.ts").MergeConflict | import("./FlowError.ts").StoryFailed | E | E2, R | R2>;
+export declare const generateVectorsResumably: <E, R>(files: PlainFileStoreShape, programs: readonly string[], generate: (program: string) => Effect.Effect<string, E, R>, directory?: string | undefined) => Effect.Effect<ResumeSummary, import("./FlowError.ts").PersistenceError | import("./FlowError.ts").PlanParseError | import("./FlowError.ts").UnsupportedSchemaVersion | import("./FlowError.ts").WorkspacePathError | import("./FlowError.ts").WorkspaceLimitError | import("./FlowError.ts").WorkspaceIoError | import("./FlowError.ts").FlowAborted | import("./FlowError.ts").ProcessError | import("./FlowError.ts").FlowLlmError | import("./FlowError.ts").FlowCapabilityDenied | import("./FlowError.ts").ColumnNotFound | import("./FlowError.ts").BudgetExceeded | import("./FlowError.ts").StoryPlanInvalid | import("./FlowError.ts").PerimeterViolation | import("./FlowError.ts").MissingDependency | import("./FlowError.ts").MergeConflict | import("./FlowError.ts").StoryFailed | E, R>;
+export {};
+//# sourceMappingURL=Artifacts.d.ts.map

package/dist/Artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Artifacts.d.ts","sourceRoot":"","sources":["../src/Artifacts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;;;;;AAE3D,qBAAa,WAAY,SAAQ,gBAG/B;CAAG;;;;;;;AAEL,qBAAa,gBAAiB,SAAQ,qBAKpC;CAAG;;;;;AAEL,qBAAa,aAAc,SAAQ,kBAGjC;CAAG;AAIL,yFAAyF;AACzF,eAAO,MAAM,oBAAoB,GAC/B,MAAM,WAAW,EACjB,kBAAgC,KAC/B,aAAa,CAAC,MAAM,CAKtB,CAAA;AAED,MAAM,WAAW,sBAAsB,CAAC,EAAE,EAAE,EAAE;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;CACxE;AAID;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAExB,CAAC,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,qFAGf,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC,EAAE,CAAC,CAAC,42BAiErE,CAAA;AAEF,eAAO,MAAM,wBAAwB,GAExB,CAAC,EAAE,CAAC,+EAGK,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,4yBAe1D,CAAA"}

package/dist/Artifacts.js

@@ -0,0 +1,103 @@
+import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+export class ProgramUnit extends Schema.Class("ProgramUnit")({
+    name: Schema.String,
+    sourcePath: Schema.String
+}) {
+}
+export class ProgramArtifacts extends Schema.Class("ProgramArtifacts")({
+    spec: Schema.String,
+    feature: Schema.String,
+    traceability: Schema.String,
+    mapping: Schema.String
+}) {
+}
+export class ResumeSummary extends Schema.Class("ResumeSummary")({
+    created: Schema.Array(Schema.String),
+    skipped: Schema.Array(Schema.String)
+}) {
+}
+const programName = (name) => name.toLowerCase();
+/** The four per-program artifact paths under `directory`, relative to the repository. */
+export const programArtifactPaths = (unit, directory = "docs/modernization") => [
+    `${directory}/specs/${unit.name}.md`,
+    `${directory}/features/${programName(unit.name)}.feature`,
+    `${directory}/traceability/${unit.name}.md`,
+    `${directory}/mapping/${unit.name}.md`
+];
+/**
+ * Extracts every unit whose spec is missing, writes its four artifacts, and
+ * reports what was created and what was skipped. Resumable by construction:
+ * a rerun skips every program whose spec exists.
+ *
+ * Failure keeps finished work: a program that fails stops NEW programs from
+ * starting, but programs already in flight run to completion and land on
+ * disk (and through `onCreated`) before the first failure, in unit order, is
+ * re-raised. With `concurrency` 1 that is exactly fail-fast; above 1 a quota
+ * death costs only the programs it interrupted, and a rerun resumes the rest.
+ */
+export const extractProgramsResumably = Effect.fn("@llm4ts/flow/Artifacts.extractProgramsResumably")(function* (files, units, extract, directory = "docs/modernization", options = {}) {
+    const concurrency = Math.max(1, Math.floor(options.concurrency ?? 1));
+    const halted = yield* Ref.make(false);
+    const extractOne = (unit) => Effect.gen(function* () {
+        if (yield* Ref.get(halted)) {
+            return "not-started";
+        }
+        const [specPath, featurePath, traceabilityPath, mappingPath] = programArtifactPaths(unit, directory);
+        if (specPath === undefined ||
+            featurePath === undefined ||
+            traceabilityPath === undefined ||
+            mappingPath === undefined) {
+            return "not-started";
+        }
+        if ((yield* files.read(specPath)) !== undefined) {
+            return "skipped";
+        }
+        const artifacts = yield* extract(unit);
+        yield* files.writeAtomic(specPath, artifacts.spec);
+        yield* files.writeAtomic(featurePath, artifacts.feature);
+        yield* files.writeAtomic(traceabilityPath, artifacts.traceability);
+        yield* files.writeAtomic(mappingPath, artifacts.mapping);
+        if (options.onCreated !== undefined) {
+            yield* options.onCreated(unit);
+        }
+        return "created";
+    });
+    const outcomes = yield* Effect.forEach(units, (unit) => Effect.result(extractOne(unit)).pipe(Effect.tap((outcome) => (Result.isFailure(outcome) ? Ref.set(halted, true) : Effect.void))), { concurrency });
+    const firstFailure = outcomes.find(Result.isFailure);
+    if (firstFailure !== undefined) {
+        return yield* Effect.fail(firstFailure.failure);
+    }
+    const created = [];
+    const skipped = [];
+    for (const [index, outcome] of outcomes.entries()) {
+        const unit = units[index];
+        if (unit === undefined || Result.isFailure(outcome)) {
+            continue;
+        }
+        if (outcome.success === "created") {
+            created.push(unit.name);
+        }
+        else if (outcome.success === "skipped") {
+            skipped.push(unit.name);
+        }
+    }
+    return ResumeSummary.make({ created, skipped });
+});
+export const generateVectorsResumably = Effect.fn("@llm4ts/flow/Artifacts.generateVectorsResumably")(function* (files, programs, generate, directory = "docs/modernization/vectors") {
+    const created = [];
+    const skipped = [];
+    for (const program of programs) {
+        const path = `${directory}/${program}.jsonl`;
+        if ((yield* files.read(path)) !== undefined) {
+            skipped.push(program);
+            continue;
+        }
+        yield* files.writeAtomic(path, yield* generate(program));
+        created.push(program);
+    }
+    return ResumeSummary.make({ created, skipped });
+});
+//# sourceMappingURL=Artifacts.js.map

package/dist/Artifacts.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/flow",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Effect-native LLM workflow, persistence, review, and repository automation",
   "license": "MIT",
   "type": "module",
@@ -13,6 +13,8 @@
     "src"
   ],
   "exports": {
+    "./Approval": "./dist/Approval.js",
+    "./Artifacts": "./dist/Artifacts.js",
     "./package.json": "./package.json",
     "./Activity": "./dist/Activity.js",
     "./AzureDevOpsTool": "./dist/AzureDevOpsTool.js",
@@ -89,7 +91,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/core": "0.17.0"
+    "@llm4ts/core": "0.18.0"
   },
   "peerDependencies": {
     "effect": "4.0.0-beta.102"

package/src/Approval.ts

@@ -0,0 +1,51 @@
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import type { FlowError } from "./FlowError.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+/**
+ * The human gates of the modernization phases: a markdown document ends
+ * with a draft marker the flow writes, and the next phase refuses to start
+ * until a person has ticked it. (Moved from `@llm4ts/modernize` in 0.18.0.)
+ */
+export class ApprovalRequired extends Schema.TaggedErrorClass<ApprovalRequired>()(
+  "ApprovalRequired",
+  {
+    path: Schema.String,
+    marker: Schema.String
+  }
+) {
+  get message(): string {
+    return `approval required in ${this.path}: set '${this.marker}'`
+  }
+}
+
+export class MissingModernizeArtifact extends Schema.TaggedErrorClass<MissingModernizeArtifact>()(
+  "MissingModernizeArtifact",
+  {
+    path: Schema.String,
+    message: Schema.String
+  }
+) {}
+
+export const ApprovedMarker = "- [x] Approved"
+export const DraftApprovalMarker = "- [ ] Approved"
+
+export const withDraftApproval = (markdown: string): string =>
+  `${markdown.trimEnd()}\n\n${DraftApprovalMarker}\n`
+
+export const requireApproval = Effect.fn("@llm4ts/flow/Approval.requireApproval")(function* (
+  files: PlainFileStoreShape,
+  path: string
+): Effect.fn.Return<void, FlowError | ApprovalRequired | MissingModernizeArtifact> {
+  const contents = yield* files.read(path)
+  if (contents === undefined) {
+    return yield* MissingModernizeArtifact.make({
+      path,
+      message: `approval document does not exist: ${path}`
+    })
+  }
+  if (!contents.includes(ApprovedMarker)) {
+    return yield* ApprovalRequired.make({ path, marker: ApprovedMarker })
+  }
+})

package/src/Artifacts.ts

@@ -0,0 +1,161 @@
+import * as Effect from "effect/Effect"
+import * as Ref from "effect/Ref"
+import * as Result from "effect/Result"
+import * as Schema from "effect/Schema"
+import type { FlowError } from "./FlowError.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+export class ProgramUnit extends Schema.Class<ProgramUnit>("ProgramUnit")({
+  name: Schema.String,
+  sourcePath: Schema.String
+}) {}
+
+export class ProgramArtifacts extends Schema.Class<ProgramArtifacts>("ProgramArtifacts")({
+  spec: Schema.String,
+  feature: Schema.String,
+  traceability: Schema.String,
+  mapping: Schema.String
+}) {}
+
+export class ResumeSummary extends Schema.Class<ResumeSummary>("ResumeSummary")({
+  created: Schema.Array(Schema.String),
+  skipped: Schema.Array(Schema.String)
+}) {}
+
+const programName = (name: string): string => name.toLowerCase()
+
+/** The four per-program artifact paths under `directory`, relative to the repository. */
+export const programArtifactPaths = (
+  unit: ProgramUnit,
+  directory = "docs/modernization"
+): ReadonlyArray<string> => [
+  `${directory}/specs/${unit.name}.md`,
+  `${directory}/features/${programName(unit.name)}.feature`,
+  `${directory}/traceability/${unit.name}.md`,
+  `${directory}/mapping/${unit.name}.md`
+]
+
+export interface ExtractProgramsOptions<E2, R2> {
+  /**
+   * How many programs extract at once (default 1: the sequential order the
+   * units were given in). The programs of a wave are independent — each
+   * analyst reads only its source and resolved closure and writes only its
+   * own four files — so the bound is about the model seat's quota, not about
+   * correctness.
+   */
+  readonly concurrency?: number
+  /**
+   * Runs after a program's four artifacts are on disk and before it counts as
+   * created — the seam for per-program post-processing (pattern tagging, the
+   * program's own commit). Runs under the same concurrency as extraction:
+   * anything in it that must not interleave (git) serialises itself.
+   */
+  readonly onCreated?: (unit: ProgramUnit) => Effect.Effect<void, E2, R2>
+}
+
+type Outcome = "created" | "skipped" | "not-started"
+
+/**
+ * Extracts every unit whose spec is missing, writes its four artifacts, and
+ * reports what was created and what was skipped. Resumable by construction:
+ * a rerun skips every program whose spec exists.
+ *
+ * Failure keeps finished work: a program that fails stops NEW programs from
+ * starting, but programs already in flight run to completion and land on
+ * disk (and through `onCreated`) before the first failure, in unit order, is
+ * re-raised. With `concurrency` 1 that is exactly fail-fast; above 1 a quota
+ * death costs only the programs it interrupted, and a rerun resumes the rest.
+ */
+export const extractProgramsResumably = Effect.fn(
+  "@llm4ts/flow/Artifacts.extractProgramsResumably"
+)(function* <E, R, E2 = never, R2 = never>(
+  files: PlainFileStoreShape,
+  units: ReadonlyArray<ProgramUnit>,
+  extract: (unit: ProgramUnit) => Effect.Effect<ProgramArtifacts, E, R>,
+  directory = "docs/modernization",
+  options: ExtractProgramsOptions<E2, R2> = {}
+): Effect.fn.Return<ResumeSummary, E | E2 | FlowError, R | R2> {
+  const concurrency = Math.max(1, Math.floor(options.concurrency ?? 1))
+  const halted = yield* Ref.make(false)
+
+  const extractOne = (unit: ProgramUnit): Effect.Effect<Outcome, E | E2 | FlowError, R | R2> =>
+    Effect.gen(function* () {
+      if (yield* Ref.get(halted)) {
+        return "not-started"
+      }
+      const [specPath, featurePath, traceabilityPath, mappingPath] = programArtifactPaths(
+        unit,
+        directory
+      )
+      if (
+        specPath === undefined ||
+        featurePath === undefined ||
+        traceabilityPath === undefined ||
+        mappingPath === undefined
+      ) {
+        return "not-started"
+      }
+      if ((yield* files.read(specPath)) !== undefined) {
+        return "skipped"
+      }
+      const artifacts = yield* extract(unit)
+      yield* files.writeAtomic(specPath, artifacts.spec)
+      yield* files.writeAtomic(featurePath, artifacts.feature)
+      yield* files.writeAtomic(traceabilityPath, artifacts.traceability)
+      yield* files.writeAtomic(mappingPath, artifacts.mapping)
+      if (options.onCreated !== undefined) {
+        yield* options.onCreated(unit)
+      }
+      return "created"
+    })
+
+  const outcomes = yield* Effect.forEach(
+    units,
+    (unit) =>
+      Effect.result(extractOne(unit)).pipe(
+        Effect.tap((outcome) => (Result.isFailure(outcome) ? Ref.set(halted, true) : Effect.void))
+      ),
+    { concurrency }
+  )
+
+  const firstFailure = outcomes.find(Result.isFailure)
+  if (firstFailure !== undefined) {
+    return yield* Effect.fail(firstFailure.failure)
+  }
+  const created: Array<string> = []
+  const skipped: Array<string> = []
+  for (const [index, outcome] of outcomes.entries()) {
+    const unit = units[index]
+    if (unit === undefined || Result.isFailure(outcome)) {
+      continue
+    }
+    if (outcome.success === "created") {
+      created.push(unit.name)
+    } else if (outcome.success === "skipped") {
+      skipped.push(unit.name)
+    }
+  }
+  return ResumeSummary.make({ created, skipped })
+})
+
+export const generateVectorsResumably = Effect.fn(
+  "@llm4ts/flow/Artifacts.generateVectorsResumably"
+)(function* <E, R>(
+  files: PlainFileStoreShape,
+  programs: ReadonlyArray<string>,
+  generate: (program: string) => Effect.Effect<string, E, R>,
+  directory = "docs/modernization/vectors"
+): Effect.fn.Return<ResumeSummary, E | FlowError, R> {
+  const created: Array<string> = []
+  const skipped: Array<string> = []
+  for (const program of programs) {
+    const path = `${directory}/${program}.jsonl`
+    if ((yield* files.read(path)) !== undefined) {
+      skipped.push(program)
+      continue
+    }
+    yield* files.writeAtomic(path, yield* generate(program))
+    created.push(program)
+  }
+  return ResumeSummary.make({ created, skipped })
+})