@cat-factory/contracts 0.343.0 → 0.344.0

package/dist/bugFishing.js

@@ -0,0 +1,412 @@
+import * as v from 'valibot';
+// ---------------------------------------------------------------------------
+// Bug-fishing expedition wire contracts. A `bug-fishing` task runs the read-only
+// `bug-fisher` container agent over the service's codebase REPEATEDLY — once per
+// ANGLE (a "phase") — hunting for genuine logic gaps, real defects, footguns and
+// unhandled edge cases rather than style opinions. The engine drives the phases as
+// successive dispatches of the SAME step (a container job cannot pause mid-run, the
+// same reason the fork decision splits into two dispatches), recording each phase's
+// findings onto `step.bugFishing` the moment it lands. So a human can triage a
+// finished phase's findings while the later angles are still being fished.
+//
+// Triage is the point of the flow: a human MARKS the findings worth acting on, and
+// each marked finding spawns its OWN bug-fix task (a separate block + run) linked
+// back to the expedition. The pipeline those spawned tasks run is the workspace's
+// `bugFishingFixPipelineId` setting, overridable per marking request, defaulting to
+// the built-in `pl_bugfix`.
+//
+// All expedition state rides the run's `bug-fisher` step (`PipelineStep.bugFishing`)
+// — no side table — so it is runtime-symmetric by construction, exactly like
+// `prReview` / `forkDecision`. See docs/initiatives/bug-fishing-expedition.md.
+// ---------------------------------------------------------------------------
+/**
+ * The ANGLES an expedition fishes from, each one pass of the read-only agent over the
+ * codebase. They are deliberately disjoint LENSES rather than a difficulty ladder: one pass
+ * asked to find everything returns the shallow half of everything, whereas a pass told to
+ * think only about concurrency reads the same files with a question that makes the race
+ * visible.
+ *
+ * A PERSISTED closed vocabulary: a phase id is written onto the step's recorded phases and
+ * onto every finding, so a value retired here still comes back out of stored runs. Nothing
+ * renders a phase by looking its id up — {@link bugFishingPhaseSchema} carries the title and
+ * goal it ran under — and {@link describeBugFishingPhase} names an unrecognised id as retired
+ * rather than guessing at a current member or rendering `undefined`.
+ */
+export const BUG_FISHING_PHASE_IDS = [
+    'control-flow',
+    'error-handling',
+    'boundaries',
+    'concurrency',
+    'state-lifecycle',
+    'contracts',
+    'footguns',
+    'requirements',
+];
+export const bugFishingPhaseIdSchema = v.picklist(BUG_FISHING_PHASE_IDS);
+/** Whether `id` is a phase angle this build still ships. Derived from the picklist itself. */
+export function isBugFishingPhaseId(id) {
+    return BUG_FISHING_PHASE_IDS.includes(id);
+}
+/**
+ * The shipped angle catalog, in the order an expedition fishes them. Ordered so the angles
+ * that most often hide a real defect run first, because an expedition a human stops early has
+ * then still covered the ground worth covering.
+ */
+export const BUG_FISHING_PHASES = [
+    {
+        id: 'control-flow',
+        title: 'Logic & control flow',
+        goal: 'Find branches that do the wrong thing, or that are missing entirely.',
+        focus: 'Read the decision points: conditionals, loops, early returns, switch/match arms and the ' +
+            'code paths that fall through them. Look for an inverted or short-circuited condition, a ' +
+            'case nobody handled, an off-by-one bound, a branch that cannot be reached, and a value ' +
+            'computed but never used where its absence changes the outcome.',
+    },
+    {
+        id: 'error-handling',
+        title: 'Failure handling',
+        goal: 'Find failures that are swallowed, mis-attributed, or left half-applied.',
+        focus: 'Read every failure path: caught exceptions, rejected promises, non-zero exits, error ' +
+            'returns. Look for a catch that discards the cause, a failure reported as a success, a ' +
+            'retry over a non-idempotent effect, a partially-applied write with no compensation, and ' +
+            'cleanup that only runs on the happy path.',
+    },
+    {
+        id: 'boundaries',
+        title: 'Inputs & boundary conditions',
+        goal: 'Find inputs the code does not actually survive.',
+        focus: 'Read the entry points and the values that cross them. Look for the empty collection, the ' +
+            'zero / negative / maximum number, the absent optional, the very long or non-ASCII string, ' +
+            'the duplicate key, and untrusted text that reaches a parsed surface (a shell argument, a ' +
+            'query, a rendered template) without being neutralised for it.',
+    },
+    {
+        id: 'concurrency',
+        title: 'Concurrency, ordering & idempotency',
+        goal: 'Find what breaks when two callers race, or when the same work arrives twice.',
+        focus: 'Read the shared state and the write paths. Look for a read-modify-write with no guard, a ' +
+            'check-then-act window, a delete-then-insert standing in for a uniqueness constraint, an ' +
+            'external side effect a retry or replay would perform twice, and ordering the code assumes ' +
+            'but nothing enforces.',
+    },
+    {
+        id: 'state-lifecycle',
+        title: 'State & resource lifecycle',
+        goal: 'Find state that outlives its purpose, or dies before it is finished with.',
+        focus: 'Read construction, mutation and teardown. Look for a resource never released on some ' +
+            'path, an unbounded cache or queue, a cached value nothing invalidates on the write that ' +
+            'moves it, a state machine that admits a transition it should refuse, and state left ' +
+            'inconsistent when an operation aborts halfway.',
+    },
+    {
+        id: 'contracts',
+        title: 'Interface contracts',
+        goal: 'Find places where a caller and a callee disagree about the deal.',
+        focus: 'Read the boundaries between modules, services and stored shapes. Look for a documented ' +
+            'guarantee the implementation does not hold, nullability the caller does not expect, a ' +
+            'unit or timezone mismatch, a persisted or wire shape a newer reader can no longer parse, ' +
+            'and an enum value that exists in stored data but has no arm in the current code.',
+    },
+    {
+        id: 'footguns',
+        title: 'Footguns',
+        goal: 'Find code that is correct today and will be broken by the next honest change.',
+        focus: 'Read as the next maintainer. Look for an API that is easy to call incorrectly, a silent ' +
+            'default that hides a missing decision, a name that misdescribes what the code does, two ' +
+            'sources of truth for one fact, and an invariant held only by convention with no test or ' +
+            'type enforcing it.',
+    },
+    {
+        id: 'requirements',
+        title: 'Requirements conformance',
+        goal: 'Find where the code disagrees with the product requirements and rules you were given.',
+        focus: 'Read the supplied requirement, specification and rules documents against the code that ' +
+            'implements them. Look for a stated rule with no implementation, an implementation that ' +
+            'contradicts a stated rule, and a requirement implemented on one path but not on its ' +
+            'siblings. Cite the document and the code side by side. If no such documents were ' +
+            'supplied, say exactly that in the summary and return no findings rather than inventing ' +
+            'requirements to measure the code against.',
+    },
+];
+const PHASE_BY_ID = new Map(BUG_FISHING_PHASES.map((p) => [p.id, p]));
+/**
+ * The descriptor for a phase id, including one this build no longer ships.
+ *
+ * A retired angle is NAMED as retired rather than dropped or guessed onto a current member:
+ * stored runs keep the id they ran under, and the reader that hits it first is the window
+ * telling a human what an expedition actually covered. Answering `undefined` there would put
+ * an empty header over real findings.
+ */
+export function describeBugFishingPhase(id) {
+    const known = PHASE_BY_ID.get(id);
+    if (known)
+        return known;
+    return {
+        id,
+        title: `Retired angle (${id})`,
+        goal: 'This angle is no longer part of the shipped expedition.',
+        focus: '',
+        retired: true,
+    };
+}
+/** How serious a finding is, ordered critical → low. The window groups and colours by this. */
+export const bugFishingSeveritySchema = v.picklist(['critical', 'high', 'medium', 'low']);
+/** Severity order (most severe first) — the one place the ranking is stated. */
+export const BUG_FISHING_SEVERITY_ORDER = [
+    'critical',
+    'high',
+    'medium',
+    'low',
+];
+/**
+ * What KIND of defect a finding is. Distinct from severity: an expedition is explicitly
+ * fishing for more than crashes, and a `footgun` that will cost a week next quarter is a
+ * different decision from an `edge-case` that fires today.
+ */
+export const bugFishingFindingKindSchema = v.picklist([
+    'bug',
+    'logic-gap',
+    'edge-case',
+    'footgun',
+    'requirement-gap',
+    'other',
+]);
+/** How sure the agent is that the finding is real — its own judgement, never platform-derived. */
+export const bugFishingConfidenceSchema = v.picklist(['high', 'medium', 'low']);
+/** A phase's lifecycle across the expedition's successive dispatches. */
+export const bugFishingPhaseStatusSchema = v.picklist(['pending', 'fishing', 'completed', 'failed']);
+/**
+ * One planned angle of the expedition, as recorded on the step.
+ *
+ * `title` and `goal` are COPIED from the catalog when the expedition is planned rather than
+ * looked up at render time, so a run keeps naming the angle it actually fished even after that
+ * angle is retired or reworded.
+ */
+export const bugFishingPhaseSchema = v.object({
+    /** The angle's id (a {@link BUG_FISHING_PHASE_IDS} member when it was planned). */
+    id: v.string(),
+    /** The angle's label as it stood when this expedition planned it. */
+    title: v.string(),
+    /** What this pass was told to hunt, as it stood when this expedition planned it. */
+    goal: v.string(),
+    status: bugFishingPhaseStatusSchema,
+    /** The agent's one-paragraph account of what it covered; null until the pass settles. */
+    summary: v.optional(v.nullable(v.string())),
+    /** Epoch ms the pass settled (completed or failed); null while pending / fishing. */
+    settledAt: v.optional(v.nullable(v.number())),
+    /** Why the pass failed, when it did. Null otherwise. */
+    failureReason: v.optional(v.nullable(v.string())),
+});
+/**
+ * How far a marked finding's spawn has got.
+ *
+ * - `pending`: the CLAIM. Written BEFORE the task exists, which is what makes marking safe
+ *   against two people (or a retried request) marking one finding at the same time: the second
+ *   claim finds the first and is refused, rather than both creating a task and a run.
+ * - `spawned`: terminal. The task exists and its run was started.
+ * - `failed`: the claim was taken and the work behind it did not land, carrying the cause. The
+ *   finding is markable again, because nothing was created for it.
+ */
+export const bugFishingSpawnStatusSchema = v.picklist(['pending', 'spawned', 'failed']);
+/**
+ * The record of a finding a human MARKED to be addressed: the bug-fix task the platform
+ * spawned for it, and the pipeline that task runs.
+ *
+ * It is what links the expedition to the work it caused: the window reads the spawned task's
+ * live status through it, and the spawned block carries the expedition's own block id back the
+ * other way (`Block.expeditionId`).
+ *
+ * Written TWICE, and the first write is the point. A spawn creates a board task and starts a run,
+ * so it is an external side effect in a path two callers can enter at once; the record is
+ * therefore taken as a `pending` CLAIM before any of that happens and settled to `spawned` or
+ * `failed` after. Reading it as "there is a fix task" means reading {@link
+ * bugFishingSpawnStatusSchema}, never merely the presence of this record.
+ */
+export const bugFishingSpawnSchema = v.object({
+    /** How far the spawn has got; see {@link bugFishingSpawnStatusSchema}. */
+    status: bugFishingSpawnStatusSchema,
+    /** The spawned task block's id, minted with the claim so the claimer can recognise its own. */
+    taskId: v.string(),
+    /**
+     * The run started on the task. Null while the claim is `pending`, and on a `spawned` record
+     * whose task was created but whose run reported no id.
+     */
+    executionId: v.optional(v.nullable(v.string())),
+    /** The pipeline the spawned task runs (the resolved default, or the caller's override). */
+    pipelineId: v.string(),
+    /** Who marked the finding. Null for a system-initiated marking. */
+    requestedBy: v.optional(v.nullable(v.string())),
+    /** Epoch ms the claim was taken. */
+    requestedAt: v.number(),
+    /** Why the spawn failed, on a `failed` record. Null otherwise. */
+    failureReason: v.optional(v.nullable(v.string())),
+});
+/**
+ * How long a `pending` spawn claim holds a finding before another marking may take it.
+ *
+ * The claim is held across a board insert and a run start, so it is normally seconds. The window
+ * exists for the one case the claimer cannot clean up after itself: a process killed between
+ * taking the claim and settling it, which would otherwise leave the finding claimed by nobody,
+ * forever, with no fix task to show for it. Generous enough that it can never expire under a
+ * merely slow start, which would be exactly the double spawn the claim exists to prevent.
+ */
+export const BUG_FISHING_SPAWN_CLAIM_TTL_MS = 5 * 60_000;
+/**
+ * Whether a finding is still OPEN: nothing is being done about it, so it may be marked (or
+ * dismissed) right now.
+ *
+ * Here rather than in the engine because both sides have to agree about it and neither owns the
+ * answer: the engine refuses a second marking with it, and the window counts "N left to triage"
+ * and decides which rows the working list shows with it. Stated once, the two cannot drift into
+ * a window that offers a mark the engine will refuse.
+ *
+ * Three ways to be open: nothing has been claimed, the last attempt `failed` (nothing was created,
+ * so there is nothing to collide with), or a `pending` claim has outlived
+ * {@link BUG_FISHING_SPAWN_CLAIM_TTL_MS} and its claimer is gone. A `spawned` record is terminal:
+ * the task exists, and marking again would file the same bug twice.
+ */
+export function bugFishingSpawnIsClaimable(spawn, now) {
+    if (!spawn)
+        return true;
+    if (spawn.status === 'spawned')
+        return false;
+    if (spawn.status === 'failed')
+        return true;
+    return now - spawn.requestedAt >= BUG_FISHING_SPAWN_CLAIM_TTL_MS;
+}
+/**
+ * One finding, id-stamped by the engine and anchored to the phase that surfaced it.
+ *
+ * `evidence` is kept apart from `detail` on purpose: an expedition that cannot point at the
+ * code it is describing is speculating, and separating the two makes that visible to the human
+ * triaging it rather than something they have to infer from the prose.
+ */
+export const bugFishingFindingSchema = v.object({
+    /** Engine-minted stable id (`bff_*`); the marking requests carry these ids. */
+    id: v.string(),
+    /** The phase that surfaced it (a phase id; see {@link describeBugFishingPhase}). */
+    phaseId: v.string(),
+    /** Repo-relative path the finding concerns; empty when it is not anchored to one file. */
+    path: v.string(),
+    /** The line the finding anchors to, or null. */
+    line: v.optional(v.nullable(v.number())),
+    severity: bugFishingSeveritySchema,
+    kind: bugFishingFindingKindSchema,
+    confidence: bugFishingConfidenceSchema,
+    /** Short headline. */
+    title: v.string(),
+    /** The full finding, in prose: what is wrong and what happens because of it. */
+    detail: v.string(),
+    /** How the defect manifests: the concrete inputs / interleaving / state that triggers it. */
+    failureScenario: v.optional(v.nullable(v.string())),
+    /** What the agent actually read that supports the claim (code it can point at). */
+    evidence: v.optional(v.nullable(v.string())),
+    /** A concrete suggested change, when the agent offered one. */
+    suggestedFix: v.optional(v.nullable(v.string())),
+    /**
+     * The bug-fix task spawned for this finding, when a human marked it. Null when nobody has.
+     * A record with a `failed` status is a mark that did not land: the finding is markable again,
+     * so a reader deciding whether this finding is being worked on reads the STATUS, not the
+     * presence of the record.
+     */
+    spawn: v.optional(v.nullable(bugFishingSpawnSchema)),
+    /** Set when a human dismissed the finding: it stays on the record, struck through. */
+    dismissed: v.optional(v.boolean(), false),
+});
+/**
+ * The expedition lifecycle on a `bug-fisher` step:
+ * - `fishing`: a phase's read-only container job is in flight (or the next one is about to be).
+ * - `awaiting_triage`: every phase settled; parked for the human to finish triaging.
+ * - `done`: the human finished the expedition (the run advances past it).
+ *
+ * There is deliberately no `skipped`: an expedition with no angles cannot be asked for, because
+ * an empty selection means "fish every angle" (see `planBugFishingPhases`).
+ *
+ * There is deliberately no `triaging` state: marking a finding is available from the moment
+ * its phase lands, INCLUDING while later phases are still fishing, which is the whole reason
+ * the angles run as separate passes.
+ */
+export const bugFishingStatusSchema = v.picklist(['fishing', 'awaiting_triage', 'done']);
+/**
+ * Live bug-fishing state carried on the run's `bug-fisher` step. Created by the engine when
+ * the step first runs (planning the phases from the task's selection), extended by each
+ * phase's completion, and mutated by the human's markings.
+ */
+export const bugFishingStepStateSchema = v.object({
+    status: bugFishingStatusSchema,
+    /** The planned angles, in the order they are fished. */
+    phases: v.optional(v.array(bugFishingPhaseSchema), []),
+    /**
+     * Index into {@link bugFishingStepStateSchema}'s `phases` of the pass currently being fished
+     * (or about to be). Equal to `phases.length` once every angle has settled, which is what the
+     * `awaiting_triage` status says in the other direction; an index rather than a pointer so an
+     * empty phase list still has an unambiguous value.
+     */
+    currentPhaseIndex: v.optional(v.number(), 0),
+    /** Every finding surfaced so far, oldest phase first, severity-ordered within a phase. */
+    findings: v.optional(v.array(bugFishingFindingSchema), []),
+    /** Identifier of the model that fished, for transparency. */
+    model: v.optional(v.nullable(v.string())),
+    /**
+     * The pipeline a marked finding's spawned task runs when the marking names none: the
+     * workspace's `bugFishingFixPipelineId`, else the built-in bug-fix preset. Resolved when the
+     * expedition is planned and recorded here, so the window can state the default it will use
+     * without a second read and the record says which default a spawn actually took.
+     */
+    defaultFixPipelineId: v.optional(v.nullable(v.string())),
+});
+// ---- Agent output (lenient) ----------------------------------------------
+/**
+ * The LENIENT structured shape the read-only `bug-fisher` container agent returns as
+ * `result.custom` for ONE phase (the engine mints the finding ids and stamps the phase).
+ * Every field falls back to a safe default (`v.fallback`) — exactly like
+ * `prReviewAgentOutputSchema` — so a partially-malformed reply degrades sensibly rather than
+ * failing a pass whose other findings are fine.
+ */
+export const bugFishingAgentOutputSchema = v.object({
+    /** What this pass covered and what it concluded, in one paragraph. */
+    summary: v.fallback(v.optional(v.string()), undefined),
+    /** The findings this pass surfaced. */
+    findings: v.fallback(v.array(v.fallback(v.object({
+        path: v.fallback(v.string(), ''),
+        line: v.fallback(v.optional(v.number()), undefined),
+        severity: v.fallback(bugFishingSeveritySchema, 'medium'),
+        kind: v.fallback(bugFishingFindingKindSchema, 'other'),
+        confidence: v.fallback(bugFishingConfidenceSchema, 'medium'),
+        title: v.fallback(v.string(), ''),
+        detail: v.fallback(v.string(), ''),
+        failureScenario: v.fallback(v.optional(v.string()), undefined),
+        evidence: v.fallback(v.optional(v.string()), undefined),
+        suggestedFix: v.fallback(v.optional(v.string()), undefined),
+    }), {
+        path: '',
+        severity: 'medium',
+        kind: 'other',
+        confidence: 'medium',
+        title: '',
+        detail: '',
+    })), []),
+});
+// ---- Request bodies -------------------------------------------------------
+/**
+ * Mark findings to be addressed: each one spawns its OWN bug-fix task, linked back to the
+ * expedition. Accepted while the expedition is still fishing later phases as well as once it
+ * has parked, because a completed phase's findings are actionable the moment they land.
+ *
+ * `pipelineId` overrides, for THIS request only, the pipeline the spawned tasks run; omitted
+ * ⇒ the expedition's resolved default (the workspace's `bugFishingFixPipelineId`, else the
+ * built-in bug-fix preset).
+ */
+export const addressBugFishingFindingsSchema = v.object({
+    /** The findings to act on. At least one; an unknown or already-spawned id is refused. */
+    findingIds: v.pipe(v.array(v.string()), v.minLength(1)),
+    /** Pipeline the spawned tasks run; omitted ⇒ the expedition's default. */
+    pipelineId: v.optional(v.string()),
+});
+/**
+ * Finish a parked expedition: the human is done triaging and the run advances past the step.
+ * Takes no fields — every marking already happened through its own request, so there is no
+ * curated selection left to carry here.
+ */
+export const resolveBugFishingSchema = v.object({});
+//# sourceMappingURL=bugFishing.js.map

package/dist/bugFishing.js.map

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

package/dist/deploy-fix.d.ts

@@ -40,8 +40,21 @@ export type DeployFixConfig = v.InferOutput<typeof deployFixConfigSchema>;
  * teardown probe and the bugfix reproduction proof are built on.
  */
 export declare const deployFixAttemptSchema: v.ObjectSchema<{
-    /** 1-based attempt number (matches `attempts` when the fixer was dispatched). */
+    /**
+     * 1-based ordinal in this log. It matches `attempts` on a run that never loops back to the
+     * deployer, and diverges from it after one: the counter is re-armed for each provisioning cycle
+     * (`restartDeployFixState`) while these rows survive the whole run, being what the verification
+     * report reduces.
+     */
     readonly attempt: v.NumberSchema<undefined>;
+    /**
+     * The 0-based provisioning CYCLE this round was dispatched in. A loop-back to the deployer
+     * re-arms the budget and opens a new cycle (`restartDeployFixState`) while these rows
+     * survive the whole run, so the marker is what tells a reader which rounds were counted
+     * against the LIVE budget and how many cycles the log spans. Absent on a row written before
+     * the field existed, which reads as cycle 0, the only cycle such a run had reached.
+     */
+    readonly cycle: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
     /** Epoch ms when the fixer job settled. */
     readonly at: v.NumberSchema<undefined>;
     /** Whether the fixer's own job completed or died without finishing. */
@@ -78,10 +91,34 @@ export declare const deployFixStateSchema: v.ObjectSchema<{
     readonly reason: v.StringSchema<undefined>;
     /** The provisioning error the in-flight round was handed. */
     readonly lastError: v.StringSchema<undefined>;
-    /** Per-round history; see {@link deployFixAttemptSchema}. */
+    /**
+     * The 0-based provisioning cycle now running, bumped by `restartDeployFixState`. It is
+     * what {@link deployFixAttemptSchema}'s own `cycle` is stamped from, and what scopes a read of
+     * the run-long log back to the rounds the live budget was spent on.
+     */
+    readonly cycle: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+    /**
+     * Per-round history, newest last, CAPPED at {@link MAX_DEPLOY_FIX_ATTEMPT_LOG}. The log
+     * survives the whole run (the verification report reduces it) while the state rides the run's
+     * `detail` JSON, which is re-serialized on every step write, so an uncapped log would grow
+     * with every loop-back for the rest of the run. See {@link droppedAttempts}.
+     */
     readonly attemptLog: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.ObjectSchema<{
-        /** 1-based attempt number (matches `attempts` when the fixer was dispatched). */
+        /**
+         * 1-based ordinal in this log. It matches `attempts` on a run that never loops back to the
+         * deployer, and diverges from it after one: the counter is re-armed for each provisioning cycle
+         * (`restartDeployFixState`) while these rows survive the whole run, being what the verification
+         * report reduces.
+         */
         readonly attempt: v.NumberSchema<undefined>;
+        /**
+         * The 0-based provisioning CYCLE this round was dispatched in. A loop-back to the deployer
+         * re-arms the budget and opens a new cycle (`restartDeployFixState`) while these rows
+         * survive the whole run, so the marker is what tells a reader which rounds were counted
+         * against the LIVE budget and how many cycles the log spans. Absent on a row written before
+         * the field existed, which reads as cycle 0, the only cycle such a run had reached.
+         */
+        readonly cycle: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
         /** Epoch ms when the fixer job settled. */
         readonly at: v.NumberSchema<undefined>;
         /** Whether the fixer's own job completed or died without finishing. */
@@ -93,6 +130,19 @@ export declare const deployFixStateSchema: v.ObjectSchema<{
         /** The fixer's account of what it changed, or the job error when it failed. */
         readonly summary: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
     }, undefined>, undefined>, undefined>, undefined>;
+    /**
+     * How many of the oldest rounds the {@link attemptLog} cap has dropped. Recorded rather than
+     * silently truncated: the report counts finished and died rounds off the surviving rows, so a
+     * dropped one would otherwise turn into a round that reads as never having run.
+     */
+    readonly droppedAttempts: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
 }, undefined>;
 export type DeployFixState = v.InferOutput<typeof deployFixStateSchema>;
+/**
+ * How many `deploy-fixer` rounds the run-long {@link deployFixStateSchema.entries.attemptLog}
+ * keeps. Four times the per-cycle ceiling of 5, so only a run that looped its deployer back
+ * several times over reaches it, and what it then drops is the oldest cycle rather than the one
+ * a reader is looking at.
+ */
+export declare const MAX_DEPLOY_FIX_ATTEMPT_LOG = 20;
 //# sourceMappingURL=deploy-fix.d.ts.map

package/dist/deploy-fix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy-fix.d.ts","sourceRoot":"","sources":["../src/deploy-fix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAiB5B;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,IAAI,CAAA;AAEhD,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,4KAAgE,CAAA;AAEpG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;IAChC;;;;OAIG;;IAEH,wEAAwE;;aAExE,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB;IACjC,iFAAiF;;IAEjF,2CAA2C;;IAE3C,uEAAuE;;IAEvE,8DAA8D;;IAE9D,oDAAoD;;IAEpD,+EAA+E;;aAE/E,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB;;IAE/B,sCAAsC;;IAEtC,oGAAoG;;IAEpG,6DAA6D;;IAE7D,uFAAuF;;IAEvF,6DAA6D;;IAE7D,6DAA6D;;QAvC7D,iFAAiF;;QAEjF,2CAA2C;;QAE3C,uEAAuE;;QAEvE,8DAA8D;;QAE9D,oDAAoD;;QAEpD,+EAA+E;;;aA+B/E,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA"}
+{"version":3,"file":"deploy-fix.d.ts","sourceRoot":"","sources":["../src/deploy-fix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAiB5B;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,IAAI,CAAA;AAEhD,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,4KAAgE,CAAA;AAEpG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;IAChC;;;;OAIG;;IAEH,wEAAwE;;aAExE,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB;IACjC;;;;;OAKG;;IAEH;;;;;;OAMG;;IAEH,2CAA2C;;IAE3C,uEAAuE;;IAEvE,8DAA8D;;IAE9D,oDAAoD;;IAEpD,+EAA+E;;aAE/E,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB;;IAE/B,sCAAsC;;IAEtC,oGAAoG;;IAEpG,6DAA6D;;IAE7D,uFAAuF;;IAEvF,6DAA6D;;IAE7D;;;;OAIG;;IAEH;;;;;OAKG;;QA/DH;;;;;WAKG;;QAEH;;;;;;WAMG;;QAEH,2CAA2C;;QAE3C,uEAAuE;;QAEvE,8DAA8D;;QAE9D,oDAAoD;;QAEpD,+EAA+E;;;IA0C/E;;;;OAIG;;aAEH,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAA"}

package/dist/deploy-fix.js

@@ -53,8 +53,21 @@ export const deployFixConfigSchema = v.object({
  * teardown probe and the bugfix reproduction proof are built on.
  */
 export const deployFixAttemptSchema = v.object({
-    /** 1-based attempt number (matches `attempts` when the fixer was dispatched). */
+    /**
+     * 1-based ordinal in this log. It matches `attempts` on a run that never loops back to the
+     * deployer, and diverges from it after one: the counter is re-armed for each provisioning cycle
+     * (`restartDeployFixState`) while these rows survive the whole run, being what the verification
+     * report reduces.
+     */
     attempt: v.number(),
+    /**
+     * The 0-based provisioning CYCLE this round was dispatched in. A loop-back to the deployer
+     * re-arms the budget and opens a new cycle (`restartDeployFixState`) while these rows
+     * survive the whole run, so the marker is what tells a reader which rounds were counted
+     * against the LIVE budget and how many cycles the log spans. Absent on a row written before
+     * the field existed, which reads as cycle 0, the only cycle such a run had reached.
+     */
+    cycle: v.optional(v.nullable(v.number())),
     /** Epoch ms when the fixer job settled. */
     at: v.number(),
     /** Whether the fixer's own job completed or died without finishing. */
@@ -90,7 +103,31 @@ export const deployFixStateSchema = v.object({
     reason: v.string(),
     /** The provisioning error the in-flight round was handed. */
     lastError: v.string(),
-    /** Per-round history; see {@link deployFixAttemptSchema}. */
+    /**
+     * The 0-based provisioning cycle now running, bumped by `restartDeployFixState`. It is
+     * what {@link deployFixAttemptSchema}'s own `cycle` is stamped from, and what scopes a read of
+     * the run-long log back to the rounds the live budget was spent on.
+     */
+    cycle: v.optional(v.nullable(v.number())),
+    /**
+     * Per-round history, newest last, CAPPED at {@link MAX_DEPLOY_FIX_ATTEMPT_LOG}. The log
+     * survives the whole run (the verification report reduces it) while the state rides the run's
+     * `detail` JSON, which is re-serialized on every step write, so an uncapped log would grow
+     * with every loop-back for the rest of the run. See {@link droppedAttempts}.
+     */
     attemptLog: v.optional(v.nullable(v.array(deployFixAttemptSchema))),
+    /**
+     * How many of the oldest rounds the {@link attemptLog} cap has dropped. Recorded rather than
+     * silently truncated: the report counts finished and died rounds off the surviving rows, so a
+     * dropped one would otherwise turn into a round that reads as never having run.
+     */
+    droppedAttempts: v.optional(v.nullable(v.number())),
 });
+/**
+ * How many `deploy-fixer` rounds the run-long {@link deployFixStateSchema.entries.attemptLog}
+ * keeps. Four times the per-cycle ceiling of 5, so only a run that looped its deployer back
+ * several times over reaches it, and what it then drops is the oldest cycle rather than the one
+ * a reader is looking at.
+ */
+export const MAX_DEPLOY_FIX_ATTEMPT_LOG = 20;
 //# sourceMappingURL=deploy-fix.js.map

package/dist/deploy-fix.js.map

@@ -1 +1 @@
-{"version":3,"file":"deploy-fix.js","sourceRoot":"","sources":["../src/deploy-fix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,8EAA8E;AAC9E,yFAAyF;AACzF,oDAAoD;AACpD,EAAE;AACF,gGAAgG;AAChG,0FAA0F;AAC1F,2CAA2C;AAC3C,EAAE;AACF,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,wDAAwD;AACxD,wDAAwD;AACxD,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAA;AAEhD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;AAEpG;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C;;;;OAIG;IACH,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAChC,wEAAwE;IACxE,WAAW,EAAE,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC;CACjD,CAAC,CAAA;AAGF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,iFAAiF;IACjF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,2CAA2C;IAC3C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,uEAAuE;IACvE,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC5C,8DAA8D;IAC9D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,oDAAoD;IACpD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,+EAA+E;IAC/E,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5C,CAAC,CAAA;AAGF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACzC,sCAAsC;IACtC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,oGAAoG;IACpG,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,6DAA6D;IAC7D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,uFAAuF;IACvF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,6DAA6D;IAC7D,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,6DAA6D;IAC7D,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,CAAC;CACpE,CAAC,CAAA"}
+{"version":3,"file":"deploy-fix.js","sourceRoot":"","sources":["../src/deploy-fix.ts"],"names":[],"mappings":"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"}

package/dist/entities.d.ts

@@ -188,6 +188,21 @@ export declare const blockSchema: v.ObjectSchema<{
      * initiative. Only meaningful on `task`-level blocks.
      */
     readonly initiativeId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    /**
+     * Membership link to the BUG-FISHING EXPEDITION task whose finding caused this task to
+     * exist, INDEPENDENT of `parentId` (which stays the enclosing service frame, so a spawned
+     * fix runs against the same repo the expedition fished).
+     *
+     * Written once, when a human marks a finding and the platform spawns the fix task; never
+     * cleared, because it records where the work came from rather than a current relationship.
+     * The other direction lives on the expedition's own step state
+     * (`step.bugFishing.findings[].spawn`), and that side is written FIRST, as a `pending` claim
+     * carrying the id this block is about to be created with: spawning is an external side effect
+     * two markings can enter at once, so the claim is what makes exactly one of them win. Which is
+     * why the finding's own record is read through its status rather than its presence.
+     * Absent/null ⇒ not spawned by an expedition. Only meaningful on `task`-level blocks.
+     */
+    readonly expeditionId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
     /**
      * Preceding-task toggle: when this task's PR merges (it reaches `done`), the
      * engine automatically starts every task that `dependsOn` it and whose other
@@ -226,7 +241,7 @@ export declare const blockSchema: v.ObjectSchema<{
      * fields, and the per-service running-task limit's optional per-type bucketing. Only
      * meaningful on `task`-level blocks; absent ⇒ treated as `feature`.
      */
-    readonly taskType: v.OptionalSchema<v.UnionSchema<[v.PicklistSchema<readonly ["feature", "bug", "document", "spike", "review", "ralph", "media", "recurring"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>, undefined>;
+    readonly taskType: v.OptionalSchema<v.UnionSchema<[v.PicklistSchema<readonly ["feature", "bug", "bug-fishing", "document", "spike", "review", "ralph", "media", "recurring"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>, undefined>;
     /**
      * Small per-type fields collected on the create-task form (see {@link taskTypeFieldsSchema}),
      * e.g. a bug's severity / repro steps, a spike's time-box. Only meaningful on `task`-level
@@ -256,6 +271,8 @@ export declare const blockSchema: v.ObjectSchema<{
         readonly prUrl: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 500, undefined>]>, undefined>;
         readonly reviewFocus: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 4000, undefined>]>, undefined>;
         readonly reviewSkillIds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>, v.MaxLengthAction<string[], 8, undefined>]>, undefined>;
+        readonly fishingPhaseIds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 60, undefined>]>, undefined>, v.MaxLengthAction<string[], 32, undefined>]>, undefined>;
+        readonly fishingFocus: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 4000, undefined>]>, undefined>;
         readonly custom: v.OptionalSchema<v.RecordSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 80, undefined>]>, v.UnionSchema<[v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>, v.MaxLengthAction<string[], 50, undefined>]>, v.BooleanSchema<undefined>, v.NumberSchema<undefined>], undefined>, undefined>, undefined>;
     }, undefined>, undefined>, undefined>;
     /**