@cat-factory/orchestration 0.301.3 → 0.302.0

package/dist/modules/execution/bugFishingTerritories.logic.d.ts

@@ -0,0 +1,89 @@
+import type { BlueprintService, BugFishingPhase, BugFishingTerritory, BugFishingUnfishedCell, RepoTreeListing } from '@cat-factory/kernel';
+/** Whether a repo-relative path is source the expedition should fish. */
+export declare function isFishablePath(path: string): boolean;
+/** One file of the survey's manifest: the path (survey-root-relative), and what it weighs. */
+export interface SurveyedFile {
+    path: string;
+    bytes: number;
+}
+/** What a survey of the repository tree produced. */
+export interface CodebaseSurvey {
+    /** The partition, in the order the expedition fishes it. Always at least one entry. */
+    territories: BugFishingTerritory[];
+    /**
+     * Every fishable file under the survey root, indexed by territory id, with paths in the survey
+     * root's frame (see this module's header).
+     */
+    filesByTerritory: Map<string, SurveyedFile[]>;
+    /** True when the provider cut the tree short: the manifest is a prefix of the codebase. */
+    treeTruncated: boolean;
+}
+/** Options a survey takes beyond the tree itself. */
+export interface SurveyOptions {
+    /**
+     * The monorepo subdirectory the service lives in, when it has one. The survey walks from here
+     * rather than from the repository root: a sibling service's code is out of scope for an
+     * expedition exactly as it is for every other run. It is also the frame every path this module
+     * emits is relative to, because it is the directory the agent's checkout is rooted at.
+     */
+    serviceDirectory?: string | null;
+    /**
+     * The service's committed blueprint, when the repository has one. Its modules are the
+     * platform's own decomposition and win over the directory heuristic; a module whose references
+     * the tree no longer has falls through to the directory rule rather than being guessed onto a
+     * new home.
+     */
+    blueprint?: BlueprintService | null;
+}
+/**
+ * The single territory a codebase small enough to fish whole gets.
+ *
+ * The PASS-THROUGH: its phases carry no territory id, so the expedition is byte-for-byte the one
+ * that shipped before territories existed. Large-codebase mode is a size threshold crossed, never
+ * a mode a task opts into.
+ */
+export declare function wholeCodebaseTerritory(files: readonly SurveyedFile[]): BugFishingTerritory;
+/**
+ * Partition a repository tree into the territories an expedition fishes.
+ *
+ * Blueprint modules first when the repository has a blueprint, then package and directory
+ * boundaries under the survey root, sized by the tree's blob bytes. A codebase that fits one
+ * territory yields exactly one, and the expedition it plans is today's.
+ */
+export declare function partitionCodebase(tree: RepoTreeListing, options?: SurveyOptions): CodebaseSurvey;
+/** One planned cell: an angle fished over a territory. */
+export interface PlannedCell {
+    territory: BugFishingTerritory;
+    phase: BugFishingPhase;
+}
+/**
+ * Build the pass list from the territories and the angles, TERRITORY-MAJOR, trimmed to the pass
+ * budget.
+ *
+ * Territory-major so a human gets a complete answer for one territory early and can start its
+ * fixes while the rest is still being fished, which is what the separate-dispatch design is for.
+ * The budget trims from the BOTTOM of the order rather than the middle, and what it cuts is
+ * returned as unfished: a cap silent about its tail teaches the reader that the tail was clean.
+ *
+ * A single whole-codebase territory yields the angles unchanged, with no territory stamped on
+ * them, so a small codebase's plan is field-for-field the one that shipped before territories.
+ */
+export declare function planTerritoryPasses(input: {
+    territories: readonly BugFishingTerritory[];
+    angles: readonly BugFishingPhase[];
+    passBudget: number;
+}): {
+    phases: BugFishingPhase[];
+    unfished: BugFishingUnfishedCell[];
+    plannedCells: number;
+};
+/**
+ * Order the territories a large expedition fishes, most worth fishing first.
+ *
+ * The creator's `fishingFocus` comes first, because naming a subsystem is the deliberate act and
+ * a budget that cut it would be cutting the one thing they asked for. Size decides the rest: with
+ * no scout rating relevance yet, the biggest territory is the one most likely to hide something,
+ * and it is a fact the platform can compute rather than a judgement it would be inventing.
+ */
+export declare function prioritiseTerritories(territories: readonly BugFishingTerritory[], focus: string | null | undefined): BugFishingTerritory[];
+//# sourceMappingURL=bugFishingTerritories.logic.d.ts.map

package/dist/modules/execution/bugFishingTerritories.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bugFishingTerritories.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/bugFishingTerritories.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAEhB,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EAEtB,eAAe,EAChB,MAAM,qBAAqB,CAAA;AA0I5B,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOpD;AAED,8FAA8F;AAC9F,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,WAAW,EAAE,mBAAmB,EAAE,CAAA;IAClC;;;OAGG;IACH,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAA;IAC7C,2FAA2F;IAC3F,aAAa,EAAE,OAAO,CAAA;CACvB;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;CACpC;AA+ED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,mBAAmB,CAU1F;AAsND;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,eAAe,EACrB,OAAO,GAAE,aAAkB,GAC1B,cAAc,CAuChB;AAID,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,mBAAmB,CAAA;IAC9B,KAAK,EAAE,eAAe,CAAA;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAA;IAC3C,MAAM,EAAE,SAAS,eAAe,EAAE,CAAA;IAClC,UAAU,EAAE,MAAM,CAAA;CACnB,GAAG;IAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAAC,QAAQ,EAAE,sBAAsB,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAgC1F;AAWD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,SAAS,mBAAmB,EAAE,EAC3C,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,mBAAmB,EAAE,CAiBvB"}

package/dist/modules/execution/bugFishingTerritories.logic.js

@@ -0,0 +1,519 @@
+import { WHOLE_CODEBASE_TERRITORY_ID } from '@cat-factory/kernel';
+// ---------------------------------------------------------------------------
+// Partitioning a codebase into TERRITORIES, and planning the (territory x angle) matrix an
+// expedition fishes over them.
+//
+// Everything here is a pure function of (tree, options) -> plan, so the rule that decides what a
+// large expedition covers is unit-testable without a repository, a run, or a model. The design
+// record is docs/initiatives/bug-fishing-expedition.md ("Large codebases"); the one sentence that
+// governs the whole module is its rule: the platform COMPUTES the partition, the model JUDGES the
+// code. Nothing below asks an LLM where the modules are.
+//
+// THE FRAME, and it binds every path this module emits: a territory's roots and its manifest are
+// relative to the SURVEY ROOT, which is the service's own directory in a monorepo and the
+// repository root otherwise. That is the frame the agent works in — the harness roots its checkout
+// at `<clone>/<serviceDirectory>` — so it is the frame the manifest has to be written in, the
+// frame the pass reports its reads and its findings in, and therefore the frame the scope check
+// and the coverage intersection have to judge in. A repo-relative manifest handed to a service
+// agent lists paths it cannot open, and every finding it reports back lands outside every root.
+// The tree read is repo-relative, so the prefix is stripped ONCE, here, in `fishableFiles`.
+// ---------------------------------------------------------------------------
+/**
+ * Target source tokens per territory: roughly what one pass can read a meaningful share of with
+ * ranged reads. Bytes / 4 over the tree's blob sizes, so it is an estimate by construction, which
+ * is why the persisted field is named `approxTokens`.
+ */
+const TARGET_TERRITORY_TOKENS = 150_000;
+/** No territory may exceed twice the target; one that would is split along its sub-directories. */
+const MAX_TERRITORY_TOKENS = TARGET_TERRITORY_TOKENS * 2;
+/** Bytes per token, the estimator every sizing decision here uses. */
+const BYTES_PER_TOKEN = 4;
+/**
+ * What a file with no reported size is assumed to weigh.
+ *
+ * GitHub's tree read carries a blob size per file; GitLab's does not. Rather than sizing a GitLab
+ * repository as weightless (which would pack the whole codebase into one territory and silently
+ * undo the partition), a size-less entry counts as a middling source file. The estimate is stated
+ * here in one place so the failure mode is "territories are sized coarsely" rather than "sizing
+ * silently stopped applying on one provider".
+ */
+const ASSUMED_FILE_BYTES = 4_000;
+/**
+ * Paths never worth fishing: generated output, vendored trees, dependency directories, lockfiles
+ * and fixtures. The finding bar cannot be applied to code nobody in this repository wrote, and a
+ * territory packed with `dist/` is budget spent on nothing.
+ *
+ * The vocabulary the file-size ratchet skips (`scripts/check-file-size.mjs`'s `SKIP_DIRS`) plus
+ * the generated/vendored shapes that ratchet never has to see, because it scans a checkout and
+ * this reads a provider's whole tree.
+ */
+const IGNORED_DIR_SEGMENTS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'out',
+    'vendor',
+    'vendored',
+    'third_party',
+    'coverage',
+    '.git',
+    '.turbo',
+    '.nuxt',
+    '.output',
+    '.next',
+    '.venv',
+    '.stryker-tmp',
+    '__snapshots__',
+    '__pycache__',
+]);
+/** File names that are generated or otherwise not source anybody reads for defects. */
+const IGNORED_FILE_NAMES = new Set([
+    'pnpm-lock.yaml',
+    'package-lock.json',
+    'yarn.lock',
+    'bun.lockb',
+    'poetry.lock',
+    'Cargo.lock',
+    'go.sum',
+    'composer.lock',
+    'Gemfile.lock',
+]);
+/** A file name suffix that marks generated output regardless of where it sits. */
+const IGNORED_FILE_SUFFIXES = ['.generated.ts', '.generated.js', '.min.js', '.snap', '.map'];
+/**
+ * A file that marks the directory it sits in as a PACKAGE boundary. A territory stops here rather
+ * than packing across it, because a package is a unit somebody already decided was cohesive, and
+ * "has something else already handled it?" is answered inside one far more often than across two.
+ */
+const PACKAGE_MARKERS = new Set([
+    'package.json',
+    'pyproject.toml',
+    'setup.py',
+    'go.mod',
+    'Cargo.toml',
+    'pom.xml',
+    'build.gradle',
+    'build.gradle.kts',
+    'composer.json',
+    'Gemfile',
+]);
+/**
+ * The id and label stem for the files sitting DIRECTLY in a root, beside its sub-directories.
+ *
+ * They are a group in their own right rather than a claim on the root itself: see
+ * {@link groupByChildDirectory} for why owning the root would be either an over-claim or, at the
+ * survey root, nothing at all.
+ */
+const LOOSE_FILES_SEGMENT = 'root-files';
+/** The label those loose files get, under a root and at the survey root. */
+function looseFilesLabel(root) {
+    return root ? `${root} (files)` : 'Top-level files';
+}
+/**
+ * Whether any of a candidate's roots is a directory carrying a package marker.
+ *
+ * Asked of every root rather than only of a lone one: a candidate that already packed two
+ * directories together is exactly the one that must stop packing when the next is a package, and
+ * the earlier "only when there is a single root" reading meant the first pack disabled the
+ * boundary check for everything after it.
+ */
+function isPackageRoot(candidate) {
+    return candidate.roots.some((root) => {
+        const prefix = root ? `${root}/` : '';
+        return candidate.files.some((file) => file.path.startsWith(prefix) && PACKAGE_MARKERS.has(file.path.slice(prefix.length)));
+    });
+}
+/** Whether a repo-relative path is source the expedition should fish. */
+export function isFishablePath(path) {
+    if (!path)
+        return false;
+    const segments = path.split('/');
+    const name = segments[segments.length - 1] ?? '';
+    if (segments.some((segment) => IGNORED_DIR_SEGMENTS.has(segment)))
+        return false;
+    if (IGNORED_FILE_NAMES.has(name))
+        return false;
+    return !IGNORED_FILE_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+/** Normalise a repo-relative path: no leading or trailing slash, no `./`. */
+function normalizePath(path) {
+    return path.replace(/^\.\//, '').replace(/^\/+/, '').replace(/\/+$/, '');
+}
+/**
+ * The fishable FILES of a tree, scoped to the survey root, sized, and REBASED onto that root.
+ *
+ * Directories are dropped here rather than filtered at each later step: a territory is a set of
+ * files, and a `dir` entry carries no bytes to size it with. The ignore rules are applied to the
+ * FULL repo path, before the rebase, so `packages/api/dist` is still recognised as generated
+ * output once the prefix is gone.
+ */
+function fishableFiles(entries, root) {
+    const prefix = root ? `${root}/` : '';
+    const files = [];
+    for (const entry of entries) {
+        if (entry.type !== 'file')
+            continue;
+        const path = normalizePath(entry.path);
+        if (prefix && !path.startsWith(prefix))
+            continue;
+        if (!isFishablePath(path))
+            continue;
+        files.push({
+            path: path.slice(prefix.length),
+            bytes: typeof entry.size === 'number' ? entry.size : ASSUMED_FILE_BYTES,
+        });
+    }
+    return files.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * Shas of the tree's entries, keyed by normalised REPO-relative path.
+ *
+ * Directories and files both: a territory root is usually a directory, whose subtree sha answers
+ * "has this changed since it was fished" with a string compare, but the loose-files group's roots
+ * are individual files, and a blob sha answers exactly the same question about one of those.
+ */
+function entryShas(entries) {
+    const shas = new Map();
+    for (const entry of entries) {
+        if (entry.sha)
+            shas.set(normalizePath(entry.path), entry.sha);
+    }
+    return shas;
+}
+function tokensOf(files) {
+    return Math.round(files.reduce((sum, file) => sum + file.bytes, 0) / BYTES_PER_TOKEN);
+}
+/** The slug a territory id is built from: path-shaped, safe to read and to put in a log field. */
+function territorySlug(idBase) {
+    const slug = idBase.replace(/[^a-zA-Z0-9._/-]/g, '-').replace(/\//g, '.');
+    return slug || WHOLE_CODEBASE_TERRITORY_ID;
+}
+/**
+ * Stamp a territory id that no other territory of this survey carries.
+ *
+ * Ids are DERIVED from paths, and derived ids collide: two blueprint modules whose first reference
+ * is the same directory produce the same stem, and so does a directory whose name happens to match
+ * the loose-files stem. A collision is not cosmetic — `filesByTerritory` is keyed by id, so the
+ * second territory would overwrite the first's manifest and every lookup by id would resolve both
+ * to one set of roots. Suffixing is enough because an id only has to be stable and distinct WITHIN
+ * one expedition: nothing looks a territory up across surveys (see the schema's note on why the
+ * label and roots are recorded rather than re-derived).
+ */
+function uniqueTerritoryId(stem, used) {
+    let id = stem;
+    for (let n = 2; used.has(id); n++)
+        id = `${stem}~${n}`;
+    used.add(id);
+    return id;
+}
+/** The label a human reads for a territory rooted at `root` (already in the survey frame). */
+function labelForRoot(root) {
+    return root || 'Whole codebase';
+}
+/**
+ * The single territory a codebase small enough to fish whole gets.
+ *
+ * The PASS-THROUGH: its phases carry no territory id, so the expedition is byte-for-byte the one
+ * that shipped before territories existed. Large-codebase mode is a size threshold crossed, never
+ * a mode a task opts into.
+ */
+export function wholeCodebaseTerritory(files) {
+    return {
+        id: WHOLE_CODEBASE_TERRITORY_ID,
+        label: 'Whole codebase',
+        roots: [],
+        fileCount: files.length,
+        approxTokens: tokensOf(files),
+        source: 'whole-codebase',
+        subtreeShas: [],
+    };
+}
+/**
+ * Group a set of files by their first path segment BELOW `root`, so a directory stays whole
+ * whenever it fits.
+ *
+ * Files sitting DIRECTLY in `root` form their own group, and that group owns its FILES rather than
+ * `root`. Owning `root` would be an over-claim wherever `root` is a real directory — it is a prefix
+ * over every sibling group here too, so a finding in one of them would be attributed to this one —
+ * and at the SURVEY root, where `root` is the empty string, it is worse than that: read as a
+ * prefix, the empty root matches no path at all, so every finding a pass raised on a top-level file
+ * was dropped as out of scope, and the empty id it derived was falsy enough that the pass was
+ * dispatched with no manifest and no scope in the first place.
+ */
+function groupByChildDirectory(files, root) {
+    const directories = new Map();
+    const loose = [];
+    const prefixLength = root ? root.length + 1 : 0;
+    for (const file of files) {
+        const rest = file.path.slice(prefixLength);
+        const slash = rest.indexOf('/');
+        if (slash === -1) {
+            loose.push(file);
+            continue;
+        }
+        const child = rest.slice(0, slash);
+        const key = root ? `${root}/${child}` : child;
+        const bucket = directories.get(key);
+        if (bucket)
+            bucket.push(file);
+        else
+            directories.set(key, [file]);
+    }
+    const groups = [...directories.entries()].map(([key, groupFiles]) => ({
+        key,
+        idBase: key,
+        roots: [key],
+        label: labelForRoot(key),
+        files: groupFiles,
+    }));
+    if (loose.length > 0) {
+        groups.push({
+            // A trailing slash sorts the loose group immediately before the child directories of the
+            // same root, and the survey root's loose group first of all.
+            key: root ? `${root}/` : '',
+            idBase: root ? `${root}/${LOOSE_FILES_SEGMENT}` : LOOSE_FILES_SEGMENT,
+            roots: loose.map((file) => file.path),
+            label: looseFilesLabel(root),
+            files: loose,
+        });
+    }
+    return groups.sort((a, b) => a.key.localeCompare(b.key));
+}
+/** A file group as a directory-sourced candidate. */
+function directoryCandidate(group) {
+    return {
+        idBase: group.idBase,
+        roots: group.roots,
+        labels: [group.label],
+        files: group.files,
+        source: 'directory',
+    };
+}
+/**
+ * Split a candidate that is over the hard ceiling along its own sub-directories, recursively.
+ *
+ * A group that cannot be split further (one directory whose own files exceed the ceiling) is
+ * KEPT oversized rather than chopped at an arbitrary file boundary: a territory is meant to be a
+ * unit somebody could reason about, and half of one is worse for the finding bar than a big one.
+ */
+function splitOversized(candidate) {
+    if (tokensOf(candidate.files) <= MAX_TERRITORY_TOKENS)
+        return [candidate];
+    const root = candidate.roots[0];
+    if (candidate.roots.length !== 1 || root === undefined) {
+        // A multi-root candidate over the ceiling is a blueprint module spanning several references
+        // (packing runs after this), so give each reference its own territory rather than chopping the
+        // module at a file boundary.
+        return candidate.roots
+            .map((r) => ({
+            idBase: r,
+            roots: [r],
+            labels: [labelForRoot(r)],
+            files: candidate.files.filter((f) => f.path === r || f.path.startsWith(`${r}/`)),
+            source: candidate.source,
+        }))
+            .filter((unpacked) => unpacked.files.length > 0)
+            .flatMap(splitOversized);
+    }
+    const groups = groupByChildDirectory(candidate.files, root);
+    if (groups.length <= 1)
+        return [candidate];
+    return groups.flatMap((group) => splitOversized({ ...directoryCandidate(group), source: candidate.source }));
+}
+/**
+ * Pack small candidates together up to the target size, keeping catalog order.
+ *
+ * Sibling directories of a few hundred lines each are not worth their own dispatch: eight angles
+ * over a five-file territory spends the pass budget on orientation. Packing is ordered rather
+ * than best-fit so two surveys of the same tree produce the same partition.
+ */
+function packSmall(candidates) {
+    const packed = [];
+    for (const candidate of candidates) {
+        const previous = packed[packed.length - 1];
+        if (previous &&
+            previous.source === candidate.source &&
+            !isPackageRoot(candidate) &&
+            !isPackageRoot(previous) &&
+            tokensOf(previous.files) + tokensOf(candidate.files) <= TARGET_TERRITORY_TOKENS) {
+            previous.roots.push(...candidate.roots);
+            previous.labels.push(...candidate.labels);
+            previous.files.push(...candidate.files);
+            continue;
+        }
+        packed.push({
+            idBase: candidate.idBase,
+            roots: [...candidate.roots],
+            labels: [...candidate.labels],
+            files: [...candidate.files],
+            source: candidate.source,
+        });
+    }
+    return packed;
+}
+/**
+ * A blueprint module's references, in the SURVEY root's frame.
+ *
+ * A reference is written by whoever ran the Blueprinter, and the two authorings differ by exactly
+ * the service prefix: an agent rooted at the service directory writes `src/billing`, while one
+ * that saw the repository root writes `packages/api/src/billing`. Both name the same code, so the
+ * prefix is stripped where it is present rather than assumed either way. A reference that matches
+ * nothing is dropped downstream, which is what makes normalising safe: nothing here can move a
+ * module onto code it does not name.
+ */
+function blueprintReferenceRoots(module, serviceRoot) {
+    return (module.references ?? [])
+        .map((reference) => normalizePath(reference))
+        .map((reference) => serviceRoot && (reference === serviceRoot || reference.startsWith(`${serviceRoot}/`))
+        ? reference.slice(serviceRoot.length).replace(/^\/+/, '')
+        : reference)
+        .filter((reference) => reference.length > 0);
+}
+/**
+ * The blueprint's own decomposition as candidates, plus whatever it does not cover.
+ *
+ * A blueprint's `references` were written by a model against an older tree, so a reference the
+ * tree no longer has is DROPPED and its module falls through to the directory rule for its part
+ * of the tree, never guessed onto a new home. Anything no module claims is partitioned by the
+ * directory rule too, so a partial blueprint narrows the heuristic rather than replacing it.
+ */
+function blueprintCandidates(files, blueprint, serviceRoot) {
+    const claimed = new Set();
+    const candidates = [];
+    for (const module of blueprint.modules ?? []) {
+        const roots = blueprintReferenceRoots(module, serviceRoot);
+        const moduleFiles = files.filter((file) => !claimed.has(file.path) &&
+            roots.some((root) => file.path === root || file.path.startsWith(`${root}/`)));
+        if (moduleFiles.length === 0)
+            continue;
+        for (const file of moduleFiles)
+            claimed.add(file.path);
+        // The module NAME is both the better label and the better id stem: it is what the person who
+        // decomposed the service called this, and unlike the first reference it distinguishes two
+        // modules that happen to share one.
+        const name = module.name?.trim() ?? '';
+        candidates.push({
+            idBase: name || (roots[0] ?? ''),
+            roots,
+            labels: [name || roots.map(labelForRoot).join(', ')],
+            files: moduleFiles,
+            source: 'blueprint',
+        });
+    }
+    return { candidates, unclaimed: files.filter((file) => !claimed.has(file.path)) };
+}
+/**
+ * Partition a repository tree into the territories an expedition fishes.
+ *
+ * Blueprint modules first when the repository has a blueprint, then package and directory
+ * boundaries under the survey root, sized by the tree's blob bytes. A codebase that fits one
+ * territory yields exactly one, and the expedition it plans is today's.
+ */
+export function partitionCodebase(tree, options = {}) {
+    const serviceRoot = normalizePath(options.serviceDirectory ?? '');
+    const files = fishableFiles(tree.entries, serviceRoot);
+    const shas = entryShas(tree.entries);
+    const filesByTerritory = new Map();
+    if (tokensOf(files) <= MAX_TERRITORY_TOKENS) {
+        const only = wholeCodebaseTerritory(files);
+        filesByTerritory.set(only.id, files);
+        return { territories: [only], filesByTerritory, treeTruncated: tree.truncated };
+    }
+    const blueprint = options.blueprint
+        ? blueprintCandidates(files, options.blueprint, serviceRoot)
+        : { candidates: [], unclaimed: files };
+    const byDirectory = groupByChildDirectory(blueprint.unclaimed, '').map(directoryCandidate);
+    const candidates = packSmall([...blueprint.candidates, ...byDirectory].flatMap((candidate) => splitOversized(candidate)));
+    const usedIds = new Set();
+    const territories = candidates.map((candidate) => {
+        const id = uniqueTerritoryId(territorySlug(candidate.idBase), usedIds);
+        filesByTerritory.set(id, candidate.files);
+        return {
+            id,
+            label: candidate.labels.join(', '),
+            roots: candidate.roots,
+            fileCount: candidate.files.length,
+            approxTokens: tokensOf(candidate.files),
+            source: candidate.source,
+            // The sha map is keyed in the tree's own repo-relative frame, so the survey-framed root goes
+            // back through the service prefix to look itself up.
+            subtreeShas: candidate.roots.map((root) => shas.get(serviceRoot ? `${serviceRoot}/${root}` : root) ?? ''),
+        };
+    });
+    return { territories, filesByTerritory, treeTruncated: tree.truncated };
+}
+/**
+ * Build the pass list from the territories and the angles, TERRITORY-MAJOR, trimmed to the pass
+ * budget.
+ *
+ * Territory-major so a human gets a complete answer for one territory early and can start its
+ * fixes while the rest is still being fished, which is what the separate-dispatch design is for.
+ * The budget trims from the BOTTOM of the order rather than the middle, and what it cuts is
+ * returned as unfished: a cap silent about its tail teaches the reader that the tail was clean.
+ *
+ * A single whole-codebase territory yields the angles unchanged, with no territory stamped on
+ * them, so a small codebase's plan is field-for-field the one that shipped before territories.
+ */
+export function planTerritoryPasses(input) {
+    const { territories, angles, passBudget } = input;
+    const only = territories[0];
+    if (territories.length === 0 || (territories.length === 1 && only?.source === 'whole-codebase')) {
+        // The whole-codebase branch names its cut cells from the ANGLES rather than from a cell list,
+        // because a survey that could not read the repository hands over no territory to build cells
+        // from — and the budget can cut angles all the same. Deriving the tail from the cells left the
+        // one case the record exists for, a cut nobody can see, as the one case it did not cover.
+        return {
+            phases: angles.slice(0, passBudget),
+            unfished: angles.slice(passBudget).map((phase) => ({
+                territoryId: only?.id ?? WHOLE_CODEBASE_TERRITORY_ID,
+                territoryLabel: only?.label ?? 'Whole codebase',
+                phaseId: phase.id,
+                phaseTitle: phase.title,
+            })),
+            plannedCells: angles.length,
+        };
+    }
+    const cells = territories.flatMap((territory) => angles.map((phase) => ({ territory, phase })));
+    const kept = cells.slice(0, passBudget);
+    return {
+        phases: kept.map(({ territory, phase }) => ({
+            ...phase,
+            territoryId: territory.id,
+            territoryLabel: territory.label,
+        })),
+        unfished: unfishedFor(cells.slice(passBudget)),
+        plannedCells: cells.length,
+    };
+}
+function unfishedFor(cells) {
+    return cells.map(({ territory, phase }) => ({
+        territoryId: territory.id,
+        territoryLabel: territory.label,
+        phaseId: phase.id,
+        phaseTitle: phase.title,
+    }));
+}
+/**
+ * Order the territories a large expedition fishes, most worth fishing first.
+ *
+ * The creator's `fishingFocus` comes first, because naming a subsystem is the deliberate act and
+ * a budget that cut it would be cutting the one thing they asked for. Size decides the rest: with
+ * no scout rating relevance yet, the biggest territory is the one most likely to hide something,
+ * and it is a fact the platform can compute rather than a judgement it would be inventing.
+ */
+export function prioritiseTerritories(territories, focus) {
+    const needles = (focus ?? '')
+        .toLowerCase()
+        .split(/[\s,;]+/)
+        .map((needle) => needle.trim())
+        .filter((needle) => needle.length >= 3);
+    const focused = (territory) => needles.some((needle) => territory.label.toLowerCase().includes(needle) ||
+        (territory.roots ?? []).some((root) => root.toLowerCase().includes(needle)));
+    return [...territories].sort((a, b) => {
+        const byFocus = Number(focused(b)) - Number(focused(a));
+        if (byFocus !== 0)
+            return byFocus;
+        return (b.approxTokens ?? 0) - (a.approxTokens ?? 0);
+    });
+}
+//# sourceMappingURL=bugFishingTerritories.logic.js.map

package/dist/modules/execution/bugFishingTerritories.logic.js.map

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

package/dist/modules/execution/dispatcher-registries.d.ts

@@ -11,6 +11,7 @@ import type { BinaryCandidateController } from './BinaryCandidateController.js';
 import type { ForkDecisionController } from './ForkDecisionController.js';
 import { PrReviewController } from './PrReviewController.js';
 import { BugFishingController } from './BugFishingController.js';
+import type { CodebaseSurveyResult } from './bugFishingSurvey.js';
 import type { InterviewGateController } from './InterviewGateController.js';
 import type { TesterController } from './TesterController.js';
 import type { RalphController } from './RalphController.js';
@@ -68,6 +69,13 @@ export interface DispatcherRegistryDeps {
     handleForkDecisionPhase: (ctx: StepHandlerContext) => Promise<AdvanceResult>;
     handlePrReviewResolution: (ctx: StepHandlerContext) => Promise<AdvanceResult>;
     handleAgentStep: (ctx: StepHandlerContext, dispatchKind?: string, augmentContext?: (context: AgentRunContext) => void) => Promise<AdvanceResult>;
+    /**
+     * Survey the codebase a block's run targets: the repository tree partitioned into the
+     * TERRITORIES a bug-fishing expedition fishes. Bound to the dispatcher, which owns the run's
+     * repo resolution; the read is cached per ref, so the dispatch and completion paths of one
+     * expedition share it.
+     */
+    surveyCodebase: (workspaceId: string, blockId: string) => Promise<CodebaseSurveyResult>;
     ingestBlueprint: (workspaceId: string, blockId: string, rawService: unknown) => Promise<void>;
     ingestSpec: (workspaceId: string, rawDoc: unknown) => Promise<void>;
 }