@legioncodeinc/nectar 0.0.1

package/dist/brooding/pipeline.d.ts

@@ -0,0 +1,198 @@
+/**
+ * The brooding pipeline orchestrator (PRD-007).
+ *
+ * Runs the FIXED order carried verbatim from `brooding-pipeline.md`, mirroring
+ * honeycomb's `runGraphBuild` discover->extract->persist composition:
+ *
+ *   discover -> pre-check -> bucket -> describe -> embed -> persist -> regenerate-projection
+ *
+ * `planBrood` runs discover -> pre-check -> bucket -> estimate with NO LLM call
+ * and NO store write (the `--dry-run` cost preview). `runBrood` runs the full
+ * pipeline: it inherits hash-matched files ($0), applies the resumability state
+ * machine to skip already-brooded files, mints identities, describes and embeds
+ * the survivors, persists the rows, and regenerates the projection.
+ *
+ * Every mint and every description is a committed store write (no in-memory
+ * accumulation), so a killed brood resumes from `describe_status` with no
+ * lockfile (PRD-007c). All stages beyond discovery reuse the existing modules:
+ * `hive-graph` (store/model/ulid/hash/paths), `portkey` (transport), `embeddings`
+ * (provider), `projection` (inherit/rebuild).
+ */
+import type { HiveGraphRow, HiveGraphVersionRow, Tenancy } from "../hive-graph/model.js";
+import type { HiveGraphStore } from "../hive-graph/store.js";
+import type { RegistrationFs } from "../registration/service.js";
+import type { IgnorePredicate } from "../registration/ignore.js";
+import { type PortkeyFetch } from "../portkey/transport.js";
+import type { PortkeyEnabled } from "../portkey/config.js";
+import { type EmbedProvider } from "../embeddings/provider.js";
+import { type PortableProjection } from "../projection/format.js";
+import { type DiscoverySource, type GitLsFiles } from "./discovery.js";
+import { type PreparedFile } from "./precheck.js";
+import { type PackBatchesOptions } from "./bucketing.js";
+import { type BroodCostEstimate } from "./cost.js";
+import { type DescribeFn } from "./describe.js";
+/** A typed pipeline error (e.g. a real brood invoked with no describe transport). */
+export declare class BroodError extends Error {
+    constructor(message: string);
+}
+/** Shared configuration for {@link planBrood} and {@link runBrood}. */
+export interface BroodConfig {
+    readonly store: HiveGraphStore;
+    readonly tenancy: Tenancy;
+    /** The project root discovery walks and the projection is written under. */
+    readonly root: string;
+    /** Filesystem seam (stat/read/list); typically `createDiskRegistrationFs(root)`. */
+    readonly fs: RegistrationFs;
+    /** git-ls-files seam (default spawns git); overridden in tests. */
+    readonly gitLsFiles?: GitLsFiles;
+    /** Ignore predicate for the walk fallback (default: the shared CodeGraph ignore). */
+    readonly isIgnored?: IgnorePredicate;
+    /**
+     * The committed projection consulted by the pre-check. `undefined` -> attempt
+     * to load `<root>/.honeycomb/nectars.json`; `null` -> no projection (every
+     * candidate is a survivor).
+     */
+    readonly projection?: PortableProjection | null;
+    /** ISO 8601 "now"; injectable for deterministic tests. */
+    readonly now?: () => string;
+    /** Dynamic batch-packing overrides (default: the decision #22 constants). */
+    readonly packOptions?: PackBatchesOptions;
+    /** Structured log sink; defaults to a no-op. */
+    readonly log?: (line: Record<string, unknown>) => void;
+}
+/** Options that shape a full {@link runBrood} (the CLI flags). */
+export interface BroodRunOptions {
+    /** `--force`: re-describe every non-skipped file, ignoring existing descriptions. */
+    readonly force?: boolean;
+    /** `--limit N`: brood at most N pending (describe-eligible) files (cost cap). */
+    readonly limit?: number;
+    /** `--dry-run`: discover + bucket + estimate, no LLM call, no writes. */
+    readonly dryRun?: boolean;
+    /** `--model <new>`: the resolved describe model id (audit-stamped on each row). */
+    readonly model?: string;
+}
+/** Transport + provider seams a full describe run needs (never touched by dry-run). */
+export interface BroodRuntimeDeps {
+    /** The chat transport. Default wires {@link describeViaPortkey} against `portkey`. */
+    readonly describe?: DescribeFn;
+    /** Portkey credentials used to build the default `describe` when none is given. */
+    readonly portkey?: PortkeyEnabled;
+    /** Injectable fetch for the default describe transport (tests). */
+    readonly fetch?: PortkeyFetch;
+    /** The embedding provider (default: the disabled provider -> NULL embeddings, BM25 fallback). */
+    readonly embedProvider?: EmbedProvider;
+    /** Active embedding model id stamped as `embed_model` on rows carrying an embedding (PRD-018i / NEC-018). */
+    readonly embedModelId?: string | null;
+    /** Projection regeneration seam (default: `rebuildProjection` from the store). Return the written path. */
+    readonly regenerateProjection?: (store: HiveGraphStore, tenancy: Tenancy, root: string) => string;
+}
+/** The bucket + estimate a dry-run (or the plan phase of a run) produces. */
+export interface BroodPlan {
+    readonly source: DiscoverySource;
+    /** PRD-018c AC-018c.10/11: set when `source` is "walk" because git was present but errored (never when git is simply absent). */
+    readonly degraded?: {
+        readonly reason: string;
+    };
+    readonly discoveredCount: number;
+    readonly inheritedCount: number;
+    readonly survivorCount: number;
+    readonly skipBinaryCount: number;
+    readonly skipTooLargeCount: number;
+    readonly batchFileCount: number;
+    readonly soloFileCount: number;
+    readonly batchCalls: number;
+    readonly soloCalls: number;
+    readonly estimate: BroodCostEstimate;
+}
+/**
+ * Real per-call token usage summed across every describe call this run
+ * (brooding review M4 / EX-3), as opposed to {@link BroodPlan.estimate}'s
+ * pre-run projection. Zero on a dry-run (no calls are made).
+ */
+export interface ActualBroodUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly usd: number;
+}
+/** The full outcome of a {@link runBrood}. */
+export interface BroodResult extends BroodPlan {
+    readonly dryRun: boolean;
+    /** Files skipped on resume because already terminally brooded (rule 1). */
+    readonly skippedResumeCount: number;
+    /** Files whose nectar was reused (rule 2 re-enqueue). */
+    readonly reenqueueCount: number;
+    /** Files minted fresh (rule 3 discover-fresh). */
+    readonly freshCount: number;
+    /** Files that reached `describe_status = 'described'` this run. */
+    readonly describedCount: number;
+    /** Files whose description failed this run (re-enqueueable). */
+    readonly failedCount: number;
+    /** The projection path written at end-of-brood, or null on dry-run. */
+    readonly projectionPath: string | null;
+    /** Real per-call usage summed from describe results (brooding review M4 / EX-3); zero on dry-run. */
+    readonly actualUsage: ActualBroodUsage;
+}
+export declare function defaultNow(): string;
+/**
+ * The store-agnostic subset {@link resolveProjection} needs. Both the sync
+ * {@link BroodConfig} and the async brood config (`pipeline-async.ts`) satisfy
+ * it, so the projection-resolution + row-building helpers below are shared
+ * verbatim across the sync and async pipelines rather than duplicated.
+ */
+export interface BroodProjectionContext {
+    readonly root: string;
+    readonly tenancy: Tenancy;
+    readonly projection?: PortableProjection | null;
+}
+/** Resolve the projection to consult: explicit value, else a disk load, else null. */
+export declare function resolveProjection(config: BroodProjectionContext): PortableProjection | null;
+/** The subset of {@link BroodRunOptions} a plan-only pass needs (`--force` only; a plan never brooding-limits or dry-runs itself). */
+export interface PlanBroodOptions {
+    readonly force?: boolean;
+}
+/**
+ * The `--dry-run` cost preview (PRD-007d): discover -> pre-check -> bucket ->
+ * estimate. Makes NO LLM call and writes NOTHING (no rows, no projection). The
+ * bucket counts and estimate reflect only the resumability-remaining survivors
+ * (brooding review M4 / EX-3), so a preview on a partially-brooded project
+ * quotes the cost of finishing the job, not re-doing it.
+ */
+export declare function planBrood(config: BroodConfig, options?: PlanBroodOptions): BroodPlan;
+export interface RowFields {
+    readonly title?: string;
+    readonly description?: string;
+    readonly concepts?: string;
+    readonly describeStatus: HiveGraphVersionRow["describeStatus"];
+    readonly describeModel?: string;
+    readonly describedAt?: string;
+    readonly embedding?: number[] | null;
+    /** Embedding-model provenance (PRD-018i / NEC-018); stamped only when `embedding` is non-null. */
+    readonly embedModel?: string | null;
+}
+/** Build a version row for a prepared file at `seq` with the given describe fields. */
+export declare function buildVersionRow(tenancy: Tenancy, now: string, prepared: PreparedFile, nectar: string, seq: number, fields: RowFields): HiveGraphVersionRow;
+/** Mint a fresh identity row for a brooded file (originally minted; no copy provenance). */
+export declare function buildIdentity(tenancy: Tenancy, now: string, nectar: string): HiveGraphRow;
+export interface ToBroodItem {
+    readonly prepared: PreparedFile;
+    readonly action: "fresh" | "re-enqueue";
+    /** The existing nectar for a re-enqueue; undefined for fresh (minted in phase A). */
+    readonly existingNectar?: string;
+    /** True when the re-enqueue's latest version is already `pending` (no new pending write needed). */
+    readonly latestPending?: boolean;
+}
+/**
+ * The full brooding run (PRD-007). Applies resumability, mints, describes,
+ * embeds, persists, and regenerates the projection. On `dryRun`, delegates to
+ * {@link planBrood} and returns without any LLM call or store write.
+ */
+export declare function runBrood(config: BroodConfig, deps?: BroodRuntimeDeps, options?: BroodRunOptions): Promise<BroodResult>;
+/** The describe-transport seams shared by the sync and async brood runtime deps. */
+export interface DescribeSeams {
+    readonly describe?: DescribeFn;
+    readonly portkey?: PortkeyEnabled;
+    readonly fetch?: PortkeyFetch;
+}
+/** Resolve the describe transport: explicit seam, else build one from Portkey creds. */
+export declare function resolveDescribeFn(deps: DescribeSeams, describeCount: number): DescribeFn;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/brooding/pipeline.d.ts.map

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

package/dist/brooding/pipeline.js

@@ -0,0 +1,454 @@
+import { mintNectar, nectarCreatedAt } from "../hive-graph/ulid.js";
+import { filenameOf, extOf } from "../hive-graph/paths.js";
+import { describeViaPortkey } from "../portkey/transport.js";
+import { createOffProvider } from "../embeddings/provider.js";
+import { isValidEmbedding } from "../hive-graph/model.js";
+import { loadProjectionFromFile, } from "../projection/load.js";
+import { DEFAULT_PROJECTION_REL_PATH } from "../projection/format.js";
+import { projectionFinalPath, rebuildProjection } from "../projection/write.js";
+import { discoverFiles } from "./discovery.js";
+import { contentHashPrecheck, prepareFiles } from "./precheck.js";
+import { bucketFiles, classifyBucket } from "./bucketing.js";
+import { estimateBroodCost, usageCostUsd } from "./cost.js";
+import { describeBatchGroup, describeSoloFile, embedDescriptions, } from "./describe.js";
+import { classifyResume } from "./resumability.js";
+/** A typed pipeline error (e.g. a real brood invoked with no describe transport). */
+export class BroodError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BroodError";
+    }
+}
+const ZERO_ACTUAL_USAGE = { inputTokens: 0, outputTokens: 0, usd: 0 };
+export function defaultNow() {
+    return new Date().toISOString();
+}
+/** Resolve the projection to consult: explicit value, else a disk load, else null. */
+export function resolveProjection(config) {
+    if (config.projection !== undefined)
+        return config.projection;
+    const path = projectionFinalPath(config.root, DEFAULT_PROJECTION_REL_PATH);
+    const result = loadProjectionFromFile(path, { tenancy: config.tenancy });
+    return result.ok ? result.doc : null;
+}
+/** The set of nectars already present in the store (skip re-inheriting these). */
+function existingNectarSet(store, tenancy) {
+    const set = new Set();
+    for (const lv of store.listLatestVersions(tenancy))
+        set.add(lv.identity.nectar);
+    return set;
+}
+/** Stage 1-3: discover -> pre-check -> bucket, returning the survivors + buckets. */
+function discoverPrecheckBucket(config, options = {}) {
+    const discovery = discoverFiles({
+        root: config.root,
+        fs: config.fs,
+        gitLsFiles: config.gitLsFiles,
+        isIgnored: config.isIgnored,
+    });
+    const prepared = prepareFiles(config.fs, discovery.files);
+    const precheck = contentHashPrecheck(prepared, {
+        tenancy: config.tenancy,
+        projection: resolveProjection(config),
+        existingNectars: existingNectarSet(config.store, config.tenancy),
+        nowIso: (config.now ?? defaultNow)(),
+    });
+    // Apply the resume partition before bucketing (brooding review M4 / EX-3):
+    // a `--dry-run` (or the plan phase of a run) should quote the REMAINING
+    // cost, not the full original cost, on a project that was already
+    // partially (or fully) brooded.
+    const remaining = [];
+    for (const p of precheck.survivors) {
+        const existing = config.store.latestVersionByPath(config.tenancy, p.file.relPath);
+        const action = classifyResume(existing?.version, { force: options.force, preparedContentHash: p.contentHash });
+        if (action !== "skip")
+            remaining.push(p);
+    }
+    const bucketed = bucketFiles(remaining, config.packOptions);
+    return {
+        source: discovery.source,
+        ...(discovery.degraded !== undefined ? { degraded: discovery.degraded } : {}),
+        discoveredCount: discovery.files.length,
+        inheritedRows: precheck.inheritedRows,
+        survivors: precheck.survivors,
+        bucketed,
+    };
+}
+/**
+ * The `--dry-run` cost preview (PRD-007d): discover -> pre-check -> bucket ->
+ * estimate. Makes NO LLM call and writes NOTHING (no rows, no projection). The
+ * bucket counts and estimate reflect only the resumability-remaining survivors
+ * (brooding review M4 / EX-3), so a preview on a partially-brooded project
+ * quotes the cost of finishing the job, not re-doing it.
+ */
+export function planBrood(config, options = {}) {
+    const { source, degraded, discoveredCount, inheritedRows, bucketed } = discoverPrecheckBucket(config, options);
+    const estimate = estimateBroodCost(bucketed);
+    return {
+        source,
+        ...(degraded !== undefined ? { degraded } : {}),
+        discoveredCount,
+        inheritedCount: inheritedRows.length,
+        survivorCount: bucketed.skipBinary.length + bucketed.skipTooLarge.length + bucketed.batchFileCount + bucketed.soloFileCount,
+        skipBinaryCount: bucketed.skipBinary.length,
+        skipTooLargeCount: bucketed.skipTooLarge.length,
+        batchFileCount: bucketed.batchFileCount,
+        soloFileCount: bucketed.soloFileCount,
+        batchCalls: bucketed.batches.length,
+        soloCalls: bucketed.soloFiles.length,
+        estimate,
+    };
+}
+/** Build a version row for a prepared file at `seq` with the given describe fields. */
+export function buildVersionRow(tenancy, now, prepared, nectar, seq, fields) {
+    const f = prepared.file;
+    return {
+        nectar,
+        contentHash: prepared.contentHash,
+        seq,
+        path: f.relPath,
+        filename: filenameOf(f.relPath),
+        ext: extOf(f.relPath),
+        sizeBytes: f.sizeBytes,
+        mtimeObserved: f.mtimeObserved,
+        title: fields.title ?? "",
+        description: fields.description ?? "",
+        concepts: fields.concepts ?? "[]",
+        embedding: fields.embedding ?? null,
+        embedModel: fields.embedding != null ? (fields.embedModel ?? null) : null,
+        confidence: null,
+        fingerprint: null,
+        describedAt: fields.describedAt ?? "",
+        describeModel: fields.describeModel ?? "",
+        describeStatus: fields.describeStatus,
+        observedAt: now,
+        orgId: tenancy.orgId,
+        workspaceId: tenancy.workspaceId,
+        projectId: tenancy.projectId,
+        lastUpdateDate: now,
+    };
+}
+/** Mint a fresh identity row for a brooded file (originally minted; no copy provenance). */
+export function buildIdentity(tenancy, now, nectar) {
+    return {
+        nectar,
+        kind: "file",
+        createdAt: nectarCreatedAt(nectar),
+        derivedFromNectar: "",
+        forkContentHash: "",
+        orgId: tenancy.orgId,
+        workspaceId: tenancy.workspaceId,
+        projectId: tenancy.projectId,
+        lastUpdateDate: now,
+    };
+}
+/**
+ * The full brooding run (PRD-007). Applies resumability, mints, describes,
+ * embeds, persists, and regenerates the projection. On `dryRun`, delegates to
+ * {@link planBrood} and returns without any LLM call or store write.
+ */
+export async function runBrood(config, deps = {}, options = {}) {
+    const now = config.now ?? defaultNow;
+    if (options.dryRun === true) {
+        const plan = planBrood(config, { force: options.force });
+        return {
+            ...plan,
+            dryRun: true,
+            skippedResumeCount: 0,
+            reenqueueCount: 0,
+            freshCount: 0,
+            describedCount: 0,
+            failedCount: 0,
+            projectionPath: null,
+            actualUsage: ZERO_ACTUAL_USAGE,
+        };
+    }
+    // ── Stage 1-2: discover + pre-check (writes inherited rows, $0) ──────────────
+    const discovery = discoverFiles({
+        root: config.root,
+        fs: config.fs,
+        gitLsFiles: config.gitLsFiles,
+        isIgnored: config.isIgnored,
+    });
+    const prepared = prepareFiles(config.fs, discovery.files);
+    const precheck = contentHashPrecheck(prepared, {
+        tenancy: config.tenancy,
+        projection: resolveProjection(config),
+        existingNectars: existingNectarSet(config.store, config.tenancy),
+        nowIso: now(),
+    });
+    for (const row of precheck.inheritedRows) {
+        if (config.store.getIdentity(row.identity.nectar) === undefined) {
+            config.store.insertIdentity(row.identity);
+        }
+        config.store.appendVersion(row.version);
+    }
+    // ── Resumability: partition survivors into skip / re-enqueue / fresh ─────────
+    let skippedResumeCount = 0;
+    const toBrood = [];
+    for (const p of precheck.survivors) {
+        const existing = config.store.latestVersionByPath(config.tenancy, p.file.relPath);
+        const action = classifyResume(existing?.version, {
+            force: options.force,
+            preparedContentHash: p.contentHash,
+        });
+        if (action === "skip") {
+            skippedResumeCount += 1;
+            continue;
+        }
+        if (action === "re-enqueue") {
+            toBrood.push({
+                prepared: p,
+                action: "re-enqueue",
+                existingNectar: existing?.identity.nectar,
+                latestPending: existing?.version.describeStatus === "pending",
+            });
+        }
+        else {
+            toBrood.push({ prepared: p, action: "fresh" });
+        }
+    }
+    // ── Stage 3: bucket. Skip buckets are terminal writes; batch/solo get described.
+    const skipItems = [];
+    const describeItems = [];
+    for (const item of toBrood) {
+        const bucket = classifyBucket(item.prepared);
+        if (bucket === "skip-binary" || bucket === "skip-too-large")
+            skipItems.push(item);
+        else
+            describeItems.push(item);
+    }
+    // Persist the skip buckets (mint nectar / reuse; write a terminal skip row).
+    let skipBinaryCount = 0;
+    let skipTooLargeCount = 0;
+    for (const item of skipItems) {
+        const bucket = classifyBucket(item.prepared);
+        const status = bucket === "skip-binary" ? "skipped-binary" : "skipped-too-large";
+        if (status === "skipped-binary")
+            skipBinaryCount += 1;
+        else
+            skipTooLargeCount += 1;
+        persistTerminal(config, now(), item, {
+            title: filenameOf(item.prepared.file.relPath),
+            describeStatus: status,
+        });
+    }
+    // ── `--limit N`: cap describe-eligible files (the rest resume on a later run).
+    const capped = options.limit !== undefined && options.limit >= 0
+        ? describeItems.slice(0, options.limit)
+        : describeItems;
+    // ── Phase A: mint identities + write pending rows for the describe set ───────
+    const nectarByPrepared = new Map();
+    let freshCount = 0;
+    let reenqueueCount = 0;
+    for (const item of capped) {
+        if (item.action === "fresh") {
+            freshCount += 1;
+            const nectar = mintNectar();
+            config.store.insertIdentity(buildIdentity(config.tenancy, now(), nectar));
+            config.store.appendVersion(buildVersionRow(config.tenancy, now(), item.prepared, nectar, 0, { describeStatus: "pending" }));
+            nectarByPrepared.set(item.prepared, nectar);
+        }
+        else {
+            reenqueueCount += 1;
+            const nectar = item.existingNectar;
+            if (item.latestPending !== true) {
+                // Make the latest version pending again (re-enqueue a failed/described row).
+                const seq = config.store.nextSeq(nectar);
+                config.store.appendVersion(buildVersionRow(config.tenancy, now(), item.prepared, nectar, seq, { describeStatus: "pending" }));
+                config.store.touchIdentity(nectar, now());
+            }
+            nectarByPrepared.set(item.prepared, nectar);
+        }
+    }
+    // ── Stage 4-6: describe -> embed -> persist, INCREMENTALLY per batch group
+    // and per solo call (NEC-003 / AC-018e.1-3): a chunk's described+failed rows
+    // are committed to the store before the next chunk's describe call runs, so
+    // a mid-run kill (or a throwing embed provider, violating its never-rejects
+    // contract) leaves every already-completed chunk durable rather than lost to
+    // an end-of-run accumulation. A transport-level batch failure marks its rows
+    // failed with no solo retry, and a truncated batch is halved and retried
+    // (NEC-013); the positional-fallback safety lives in `describe.ts` (NEC-014).
+    const describe = resolveDescribeFn(deps, capped.length);
+    const bucketed = bucketFiles(capped.map((i) => i.prepared), config.packOptions);
+    const embedProvider = deps.embedProvider ?? createOffProvider();
+    const embedModelId = deps.embedModelId ?? null;
+    const preparedByNectar = new Map();
+    for (const [prepared, nectar] of nectarByPrepared)
+        preparedByNectar.set(nectar, prepared);
+    const targetFor = (p) => ({ nectar: nectarByPrepared.get(p), prepared: p });
+    let describedCount = 0;
+    let failedCount = 0;
+    let actualInputTokens = 0;
+    let actualOutputTokens = 0;
+    function accumulateUsage(usage) {
+        if (usage === null)
+            return;
+        actualInputTokens += usage.inputTokens;
+        actualOutputTokens += usage.outputTokens;
+    }
+    /**
+     * Embed one chunk's described payloads and persist them immediately. This is
+     * the single write path Stage 4 uses for every described outcome (batch or
+     * solo), so a chunk is durable before the pipeline moves on to the next
+     * describe call.
+     */
+    async function persistDescribedChunk(entries) {
+        if (entries.length === 0)
+            return;
+        const vectors = await embedDescriptions(embedProvider, entries.map((e) => e.payload));
+        entries.forEach((e, i) => {
+            const raw = vectors[i] ?? null;
+            const embedding = isValidEmbedding(raw) ? raw : null;
+            const seq = config.store.nextSeq(e.nectar);
+            config.store.appendVersion(buildVersionRow(config.tenancy, now(), e.prepared, e.nectar, seq, {
+                title: e.payload.title,
+                description: e.payload.description,
+                concepts: e.payload.concepts,
+                describeStatus: "described",
+                describeModel: e.model,
+                describedAt: now(),
+                embedding,
+                embedModel: embedding !== null ? embedModelId : null,
+            }));
+            config.store.touchIdentity(e.nectar, now());
+            describedCount += 1;
+        });
+    }
+    /** Persist a set of nectars as `failed` immediately (re-enqueueable next run / by the enricher). */
+    function persistFailedNectars(nectars) {
+        for (const nectar of nectars) {
+            const prepared = preparedByNectar.get(nectar);
+            if (prepared === undefined)
+                continue;
+            const seq = config.store.nextSeq(nectar);
+            config.store.appendVersion(buildVersionRow(config.tenancy, now(), prepared, nectar, seq, { describeStatus: "failed" }));
+            config.store.touchIdentity(nectar, now());
+            failedCount += 1;
+        }
+    }
+    /** Describe one solo target and persist its outcome before the next solo call is issued (AC-018e.2). */
+    async function describeAndPersistSolo(target) {
+        const solo = await describeSoloFile(target, describe, options.model);
+        accumulateUsage(solo.usage);
+        if (solo.payload !== null) {
+            await persistDescribedChunk([
+                { nectar: target.nectar, prepared: target.prepared, payload: solo.payload, model: solo.model },
+            ]);
+        }
+        else {
+            persistFailedNectars([target.nectar]);
+        }
+    }
+    /**
+     * Describe one batch group, applying the failure-class retry policy
+     * (NEC-013) and the malformed-entry solo retry (spec-preserved), persisting
+     * as soon as each outcome is known.
+     */
+    async function describeAndPersistGroup(targets) {
+        if (targets.length === 0)
+            return;
+        const result = await describeBatchGroup(targets, describe, { model: options.model });
+        accumulateUsage(result.usage);
+        if (result.outcome === "transport-failed") {
+            // Whole-call transport failure: fail the batch's rows and move on; the
+            // spec reserves the solo retry for malformed entries, not this (AC-018f.1).
+            persistFailedNectars(result.failed);
+            return;
+        }
+        if (result.outcome === "truncated") {
+            if (targets.length === 1) {
+                // Cannot split further; a single-file batch that still truncates is failed.
+                persistFailedNectars(targets.map((t) => t.nectar));
+                return;
+            }
+            const mid = Math.ceil(targets.length / 2);
+            await describeAndPersistGroup(targets.slice(0, mid));
+            await describeAndPersistGroup(targets.slice(mid));
+            return;
+        }
+        // outcome === "ok": persist the well-formed entries, then solo-retry the
+        // malformed ones (per spec), persisting each solo result immediately.
+        const describedEntries = [];
+        for (const d of result.described) {
+            const target = targets.find((t) => t.nectar === d.nectar);
+            if (target !== undefined) {
+                describedEntries.push({ nectar: d.nectar, prepared: target.prepared, payload: d.payload, model: result.model });
+            }
+        }
+        await persistDescribedChunk(describedEntries);
+        for (const nectar of result.failed) {
+            const target = targets.find((t) => t.nectar === nectar);
+            if (target === undefined) {
+                persistFailedNectars([nectar]);
+                continue;
+            }
+            await describeAndPersistSolo(target);
+        }
+    }
+    for (const group of bucketed.batches) {
+        await describeAndPersistGroup(group.files.map(targetFor));
+    }
+    for (const p of bucketed.soloFiles) {
+        await describeAndPersistSolo(targetFor(p));
+    }
+    // ── Stage 7: regenerate the projection ──────────────────────────────────────
+    const regenerate = deps.regenerateProjection ??
+        ((store, tenancy, root) => rebuildProjection(store, tenancy, { projectRoot: root }).path);
+    const projectionPath = regenerate(config.store, config.tenancy, config.root);
+    const estimate = estimateBroodCost(bucketed);
+    return {
+        source: discovery.source,
+        discoveredCount: discovery.files.length,
+        inheritedCount: precheck.inheritedRows.length,
+        survivorCount: precheck.survivors.length,
+        skipBinaryCount,
+        skipTooLargeCount,
+        batchFileCount: bucketed.batchFileCount,
+        soloFileCount: bucketed.soloFileCount,
+        batchCalls: bucketed.batches.length,
+        soloCalls: bucketed.soloFiles.length,
+        estimate,
+        dryRun: false,
+        skippedResumeCount,
+        reenqueueCount,
+        freshCount,
+        describedCount,
+        failedCount,
+        projectionPath,
+        actualUsage: {
+            inputTokens: actualInputTokens,
+            outputTokens: actualOutputTokens,
+            usd: usageCostUsd(actualInputTokens, actualOutputTokens),
+        },
+    };
+}
+/** Persist a terminal (skip) row: mint+insert for fresh, append+touch for re-enqueue. */
+function persistTerminal(config, now, item, fields) {
+    if (item.action === "fresh") {
+        const nectar = mintNectar();
+        config.store.insertIdentity(buildIdentity(config.tenancy, now, nectar));
+        config.store.appendVersion(buildVersionRow(config.tenancy, now, item.prepared, nectar, 0, fields));
+    }
+    else {
+        const nectar = item.existingNectar;
+        const seq = config.store.nextSeq(nectar);
+        config.store.appendVersion(buildVersionRow(config.tenancy, now, item.prepared, nectar, seq, fields));
+        config.store.touchIdentity(nectar, now);
+    }
+}
+/** Resolve the describe transport: explicit seam, else build one from Portkey creds. */
+export function resolveDescribeFn(deps, describeCount) {
+    if (deps.describe !== undefined)
+        return deps.describe;
+    if (describeCount === 0) {
+        // Nothing to describe; return a transport that is never called.
+        return () => Promise.reject(new BroodError("describe transport not configured"));
+    }
+    const portkey = deps.portkey;
+    if (portkey === undefined) {
+        throw new BroodError("runBrood: a describe transport is required (pass deps.describe, or deps.portkey to build the default)");
+    }
+    return (req) => describeViaPortkey(req, { portkey, fetch: deps.fetch });
+}
+//# sourceMappingURL=pipeline.js.map