@cat-factory/orchestration 0.136.0 → 0.137.0

package/dist/modules/execution/ExecutionServiceDependencies.d.ts

@@ -0,0 +1,381 @@
+import type { AccountRepository, AgentExecutor, BlockRepository, BlueprintService, BranchUpdater, BrainstormSessionRepository, BrainstormStage, ClarityReviewRepository, Clock, DocInterviewRepository, DocumentRepository, ExecutionEventPublisher, ExecutionRepository, GateRegistry, GroupCacheHandle, IdGenerator, InitiativePresetRegistry, InitiativeRepository, IssueWritebackProvider, ModelRef, PipelineRepository, PrVerificationReportPublisher, ProviderCapabilities, ProviderRegistry, PullRequestMerger, RequirementReviewRepository, ResolveBinaryArtifactStore, ResolveRunRepoContext, RiskPolicyCacheValue, RiskPolicyRepository, RunInitiatorScope, StepResolverRegistry, SubscriptionActivationRepository, TaskRepository, TestSecretRef, TicketTrackerProvider, WorkRunner, WorkspaceRepository, WorkspaceSettingsRepository } from '@cat-factory/kernel';
+import type { AgentKindRegistry } from '@cat-factory/agents';
+import type { BugIntakeService, EnvironmentProvisioningService, EnvironmentTeardownService } from '@cat-factory/integrations';
+import type { SpendService } from '@cat-factory/spend';
+import type { BoardService } from '../board/BoardService.js';
+import type { BrainstormService } from '../brainstorm/BrainstormService.js';
+import type { ClarityReviewService } from '../clarity/ClarityReviewService.js';
+import type { DocInterviewService } from '../docInterview/DocInterviewService.js';
+import type { InitiativeInterviewService } from '../initiative/InitiativeInterviewService.js';
+import type { InitiativeRunHarvest } from '../initiative/initiative.logic.js';
+import type { InitiativeService } from '../initiative/InitiativeService.js';
+import type { LlmObservabilityService } from '../observability/LlmObservabilityService.js';
+import type { NotificationService } from '../notifications/NotificationService.js';
+import type { RequirementReviewService } from '../requirements/RequirementReviewService.js';
+import type { WorkspaceSettingsService } from '../settings/WorkspaceSettingsService.js';
+import type { DocumentUrlResolver, FragmentBodyResolver, SkillResolver } from './AgentContextBuilder.js';
+import type { ForkChatService } from './ForkChatService.js';
+import type { PrReportLogger } from './PrVerificationReportController.js';
+import type { KaizenScheduler } from './RunStateMachine.js';
+import type { TesterQualityReviewer } from './TesterQualityReviewService.js';
+/** Reconciles a Blueprinter step's tree onto the board in place (BoardScanService). */
+export interface BlueprintReconciler {
+    reconcileBlueprint(workspaceId: string, frameId: string | null, service: BlueprintService): Promise<unknown>;
+}
+export interface ExecutionServiceDependencies {
+    workspaceRepository: WorkspaceRepository;
+    blockRepository: BlockRepository;
+    pipelineRepository: PipelineRepository;
+    executionRepository: ExecutionRepository;
+    /**
+     * Resolves the owning account of a workspace so a service that pins no cloud
+     * provider falls back to the account's `defaultCloudProvider` at dispatch.
+     */
+    accountRepository: AccountRepository;
+    idGenerator: IdGenerator;
+    clock: Clock;
+    agentExecutor: AgentExecutor;
+    /**
+     * The app-owned agent-kind registry, threaded through to the trait/inline-surface checks
+     * and a registered kind's pre/post-op hooks. `createCore` defaults it to
+     * `defaultAgentKindRegistry()` when a facade doesn't inject the shared instance.
+     */
+    agentKindRegistry: AgentKindRegistry;
+    /**
+     * The app-owned polling-gate registry (the built-in `@cat-factory/gates` suite installed by
+     * the facade + any deployment-registered gates), threaded to the dispatcher's gate machine.
+     * `createCore` defaults it to `defaultGateRegistry()` (empty) when a facade doesn't inject one.
+     */
+    gateRegistry: GateRegistry;
+    /**
+     * The app-owned step-completion-resolver registry (deployment-registered resolvers),
+     * threaded to the dispatcher. `createCore` defaults it to `defaultStepResolverRegistry()`.
+     */
+    stepResolverRegistry: StepResolverRegistry;
+    /**
+     * The app-owned provider registry (gate data sources keyed by {@link ProviderToken}), threaded
+     * to the dispatcher's gate machine so its {@link GateContext} reads the wired providers.
+     * `createCore` defaults it to `defaultProviderRegistry()` (empty ⇒ every gate passes through).
+     */
+    providerRegistry: ProviderRegistry;
+    /**
+     * The app-owned initiative-preset registry, threaded into the context builder so a spawned /
+     * planning run resolves its preset steering. `createCore` defaults it to
+     * `defaultInitiativePresetRegistry()` when a facade doesn't inject the shared instance.
+     */
+    initiativePresetRegistry: InitiativePresetRegistry;
+    workRunner: WorkRunner;
+    executionEventPublisher: ExecutionEventPublisher;
+    boardService: BoardService;
+    spendService: SpendService;
+    /**
+     * Optional: when the document-source integration is configured, documents
+     * linked to a block are resolved here and fed to the agent as extra context.
+     */
+    documentRepository?: DocumentRepository;
+    /**
+     * Optional: canonicalises a URL named in a block's description to the document's stable
+     * `(source, externalId)` (via the document providers' `parseRef`) so a pasted design/doc
+     * link auto-matches its imported page even when the URL carries title/tracking noise.
+     * Forwarded to {@link AgentContextBuilder}; absent → url-string matching only.
+     */
+    documentUrlResolver?: DocumentUrlResolver;
+    /**
+     * Optional: when the task-source integration is configured, tracker issues
+     * linked to a block are resolved here and fed to the agent as extra context.
+     */
+    taskRepository?: TaskRepository;
+    /**
+     * Optional: when the requirements-review feature is configured, a block's
+     * reworked ("incorporated") requirements are read here. When present they REPLACE
+     * the block's description + linked docs/tasks as the agent context (for every
+     * step) and become the per-task input the spec-writer aggregates. Absent
+     * → the engine uses the original description + docs/tasks unchanged.
+     */
+    requirementReviewRepository?: RequirementReviewRepository;
+    /**
+     * Optional: when the interactive document-interview feature is configured (WS5), a block's
+     * synthesized authoring brief is read here and folded into the doc-writer's context. Absent
+     * → the writer runs off the raw outline/description unchanged.
+     */
+    docInterviewRepository?: DocInterviewRepository;
+    /**
+     * Optional: the requirements-review feature's service, present when the reviewer is
+     * wired. Drives the special `requirements-review` gate step (run reviewer inline, the
+     * iterative answer → incorporate → re-review loop). Absent → the gate step passes
+     * through so pipelines run unchanged without the feature.
+     */
+    requirementReviewService?: RequirementReviewService;
+    /**
+     * Optional: the interactive document-interview service (WS5). When wired, the
+     * `doc-interviewer` step converses with the human (park/answer/resume) to refine a
+     * document's scope/structure and synthesizes an authoring brief the writer starts from.
+     * Absent (or no model) → the interviewer step passes through so document pipelines run
+     * unchanged off the raw outline.
+     */
+    docInterviewService?: DocInterviewService;
+    /**
+     * Optional: the inline grounded-chat responder for the implementation-fork decision phase.
+     * When wired, a human chat turn about the surfaced forks is answered by an inline LLM in the
+     * durable driver; absent (no model) the chat degrades to a canned "chat unavailable" reply so
+     * pick / custom still work. Passed to the {@link ForkDecisionController}.
+     */
+    forkChatService?: ForkChatService;
+    /**
+     * Optional: the inline reviewer for the test quality-control companion. When wired (and a
+     * Tester step has the companion enabled), each Tester report is audited for coverage before
+     * the greenlight/fixer decision and an inadequate report loops the Tester. Passed straight
+     * to the {@link TesterController}. Absent → QC is a pass-through.
+     */
+    testerQualityReviewer?: TesterQualityReviewer;
+    /**
+     * Optional: the Kaizen agent's scheduler. When wired, a run reaching a terminal state
+     * schedules a post-run grading for each completed agent step (skipping verified combos).
+     * Structural so the engine doesn't depend on the concrete service. Absent → no grading.
+     */
+    kaizenScheduler?: KaizenScheduler;
+    /**
+     * Optional: persistence for the clarity-review (bug-report triage) feature. Read here
+     * to substitute a converged clarified report as the downstream agent context (the
+     * mirror of `requirementReviewRepository`). Absent → no substitution.
+     */
+    clarityReviewRepository?: ClarityReviewRepository;
+    /**
+     * Optional: the clarity-review feature's service, present when the reviewer is wired.
+     * Drives the special `clarity-review` gate step (inline reviewer + the iterative
+     * answer → incorporate → re-review loop). Absent → the gate step passes through.
+     */
+    clarityReviewService?: ClarityReviewService;
+    /**
+     * Optional: the brainstorm (structured-dialogue) feature's services, one per stage, present
+     * when the brainstorm module is wired. Drive the special `requirements-brainstorm` /
+     * `architecture-brainstorm` gate steps (inline option-generator + the iterative propose →
+     * pick → incorporate → re-run loop). Absent → the gate steps pass through.
+     */
+    brainstormServices?: Record<BrainstormStage, BrainstormService>;
+    /**
+     * Optional: persistence for the brainstorm feature. Read by the agent-context builder to
+     * surface a converged `architecture-brainstorm` direction to the architect (the mirror of
+     * `requirementReviewRepository`). Absent → no substitution.
+     */
+    brainstormSessionRepository?: BrainstormSessionRepository;
+    /**
+     * Optional: resolves fragment ids against the merged tenant catalog (managed +
+     * document-backed fragments), live-resolving linked Confluence/Notion/GitHub
+     * documents at run time. Wired only when the prompt-fragment library is
+     * configured; absent → the engine resolves against the static built-in pool.
+     */
+    fragmentResolver?: FragmentBodyResolver;
+    /**
+     * Optional: resolves a `skill` step's picked skill to its instructions + resource bodies for
+     * the run (see {@link SkillResolver}). Wired only when the repo-sourced Claude Skills library is
+     * configured; a skill step dispatched with this unwired fails loudly rather than running blank.
+     */
+    skillResolver?: SkillResolver;
+    /**
+     * Optional: when the individual-usage subscription store is configured, a finished
+     * run's per-run credential activation is deleted here the moment it reaches a terminal
+     * state, bounding standing exposure to the run's own lifetime (the TTL sweep is the
+     * backstop). Absent → activations are reclaimed by the TTL sweep alone.
+     */
+    subscriptionActivationRepository?: SubscriptionActivationRepository;
+    /**
+     * Optional: resolve a workspace's per-agent-kind default model id (the same resolver
+     * the container executor uses for dispatch). The personal-credential gate consults it
+     * so a run whose block has NO pinned model but whose workspace default resolves to an
+     * individual-usage vendor is still gated up-front — matching what dispatch will resolve,
+     * instead of starting and then failing on a missing activation. Absent → the gate sees
+     * only the block's pinned model (env-routing defaults are operator-level and not gated).
+     */
+    resolveWorkspaceModelDefault?: (workspaceId: string, agentKind: string, modelPresetId?: string) => Promise<string | undefined>;
+    /**
+     * Optional: resolve the provider capabilities (configured direct keys +
+     * subscription vendors + whether Cloudflare AI is enabled) for a workspace and the
+     * run initiator. The start guard uses it to block a pipeline whose steps' canonical
+     * models have no usable provider. Absent → the guard is skipped (tests / unconfigured
+     * facades), exactly like the existing optional engine deps.
+     */
+    resolveProviderCapabilities?: (workspaceId: string, initiatedBy?: string | null) => Promise<ProviderCapabilities>;
+    /**
+     * Optional: whether a container-only subscription harness ref (`claude-code` / `codex`)
+     * can run as an INLINE LLM call in this deployment (local mode's ambient CLI). The preset
+     * satisfiability guard uses it so an inline step pinned to a subscription model is
+     * satisfiable where the harness runs inline, and refused where it doesn't (Node/Worker).
+     * From `config.agents.inlineHarnessRef`; absent → no inline harness support.
+     */
+    inlineHarnessRef?: (ref: ModelRef) => boolean;
+    /**
+     * Optional: when the environment integration is configured, a `deployer` step
+     * provisions an ephemeral environment deterministically through this service
+     * (no LLM), and downstream steps discover the resulting env via it.
+     */
+    environmentProvisioning?: EnvironmentProvisioningService;
+    /**
+     * Optional: resolve the NON-secret refs (key + description) of the sensitive test credentials
+     * for a run block's service frame, folded into the tester prompt by the context builder.
+     * Wired from the facade's `TestSecretsService`; absent ⇒ no advertised secrets. NEVER values.
+     */
+    resolveTestSecretRefs?: (workspaceId: string, blockId: string) => Promise<TestSecretRef[]>;
+    /**
+     * Optional: resolves the binary-artifact store (UI screenshots + reference design images)
+     * for a workspace's account; the `visual-confirmation` gate reads it. Absent (or resolving
+     * to null — storage not configured) → the gate passes through (auto-advances), since there
+     * is nowhere to read screenshots from.
+     */
+    resolveBinaryArtifactStore?: ResolveBinaryArtifactStore;
+    /**
+     * Optional: tears down ephemeral environments. Wired alongside
+     * {@link environmentProvisioning}; the `human-test` gate uses it to destroy an env on
+     * confirm / recreate / on-demand. Absent → the gate's destroy/recreate is a no-op.
+     */
+    environmentTeardown?: EnvironmentTeardownService;
+    /**
+     * Optional: merges the repo default branch into a block's PR branch server-side. Wired
+     * when GitHub is configured; the `human-test` gate's "pull latest main" action uses it
+     * (a clean merge rebuilds the env; a conflict escalates to the conflict-resolver). Absent
+     * → pulling main is unavailable on the gate.
+     */
+    branchUpdater?: BranchUpdater;
+    /**
+     * Optional: when the board-scan module is configured, a `blueprints` step's
+     * decomposition tree is reconciled onto the board through this (BoardScanService).
+     * Absent → a blueprint step still runs and commits its in-repo files, but the
+     * board isn't auto-updated from it.
+     */
+    blueprintReconciler?: BlueprintReconciler;
+    /**
+     * Optional: when the initiatives module is wired, the `initiative-planner` step's
+     * plan draft is ingested into the block's initiative entity through this, and the
+     * `initiative-committer` step flips it to `executing` + mirrors the in-repo
+     * tracker. Absent → the initiative steps fail loudly (an initiative pipeline is
+     * meaningless without the module) while every other pipeline runs unchanged.
+     */
+    initiativeService?: InitiativeService;
+    /**
+     * Optional: the initiative store, wired into the agent-context builder so an
+     * `initiative`-level run carries the interview + analysis context into the analyst/planner
+     * prompts. Same repo the {@link initiativeService} wraps; absent → those steps run off the
+     * raw block description.
+     */
+    initiativeRepository?: InitiativeRepository;
+    /**
+     * Optional: the inline interviewer for the interactive-planning gate (slice 2). When
+     * wired, the `initiative-interviewer` step interviews the human (park/answer/resume) and
+     * synthesizes the goal/constraints brief onto the entity before the analyst/planner run.
+     * Absent (or no model) → the interviewer step passes through and planning runs off the
+     * raw block description. Requires {@link initiativeService} to persist the interview state.
+     */
+    initiativeInterviewService?: InitiativeInterviewService;
+    /**
+     * Best-effort poke of the initiative execution loop (slice 3): called after a spawned task's
+     * PR merges (`finalizeMerge`), so its owning initiative reconciles + advances immediately
+     * rather than on the next cron sweep. Threaded through to the {@link RunStateMachine} for the
+     * symmetric terminal-run poke. Fire-and-forget; a no-op when initiatives are unwired. The
+     * optional `harvest` (slice 4) carries the settling run's follow-ups + failure cause.
+     */
+    pokeInitiativeLoop?: (workspaceId: string, initiativeBlockId: string, harvest?: InitiativeRunHarvest) => void;
+    /**
+     * Optional: raises human-actionable notifications (a PR needs a merge decision,
+     * a no-merger pipeline finished, CI fixing gave up). Absent → those events still
+     * transition the block but no notification surfaces (tests).
+     */
+    notificationService?: NotificationService;
+    /**
+     * Optional: resolves a workspace's runtime settings so {@link ExecutionService.start}
+     * can enforce the per-service running-task limit. Absent → the limit is never enforced
+     * (tests / unconfigured facades start runs unbounded).
+     */
+    workspaceSettingsService?: WorkspaceSettingsService;
+    /**
+     * Optional: performs the real GitHub merge when a task should become `done`.
+     * Absent → `done` is a board-only flip (tests); when wired, `done` provably
+     * means the PR was merged on the remote.
+     */
+    pullRequestMerger?: PullRequestMerger;
+    /**
+     * Optional: resolves a task's merge threshold preset (auto-merge ceilings + the
+     * CI-fixer attempt budget). Absent → the built-in {@link DEFAULT_RISK_POLICY}.
+     */
+    riskPolicyRepository?: RiskPolicyRepository;
+    /**
+     * Optional: the {@link AppCaches.riskPolicy} slice — read-through for `resolveRiskPolicy`
+     * so the slow-moving merge-preset row isn't re-fetched on every gate evaluation. Absent →
+     * every resolve hits the repository (tests / no cache wired). Invalidated by
+     * `RiskPolicyService` on every preset write.
+     */
+    riskPolicyCache?: GroupCacheHandle<RiskPolicyCacheValue>;
+    /**
+     * Optional: runs the gate-probe / merge GitHub reads under the run initiator's
+     * ambient context, so a per-user PAT (when set) is preferred over the deployment's
+     * App/env token (see `PatPreferringAppRegistry`). Absent → a pass-through
+     * (`(_, fn) => fn()`), so tests/conformance run unchanged.
+     */
+    runInitiatorScope?: RunInitiatorScope;
+    /**
+     * Optional: files a GitHub issue / Jira ticket for the `tracker` step (the
+     * tech-debt recurring pipeline). Absent → the `tracker` step passes through
+     * without filing anything, so the engine works unchanged when no tracker is wired.
+     */
+    ticketTrackerProvider?: TicketTrackerProvider;
+    /**
+     * Optional: writes back to a task's linked tracker issue(s) as its PR progresses
+     * (comment on PR open; comment + close as resolved on merge). Gated by the
+     * workspace's writeback settings + the per-task override. Absent → no writeback,
+     * so the engine works unchanged when no tracker writeback is wired.
+     */
+    issueWriteback?: IssueWritebackProvider;
+    /**
+     * Optional: the recurring `bug-intake` step's read-and-claim helper. When wired, a `bug-intake`
+     * step pulls one matching open issue from the schedule's configured tracker board, claims it, and
+     * seeds the reused block from it; absent (no task sources wired) → the step is a no-op that
+     * completes the run without touching the block, so the engine works unchanged.
+     */
+    bugIntakeService?: BugIntakeService;
+    /**
+     * Optional: the LLM observability sink. When wired, each emit rolls the per-run
+     * model-call aggregates onto the matching pipeline steps (`step.metrics`) so the
+     * board shows tokens / output-limit headroom / transport-vs-execution latency
+     * live. Absent (tests / unconfigured) → steps carry no `metrics`.
+     */
+    llmObservability?: LlmObservabilityService;
+    /**
+     * Optional: resolve a block's run repo (installation + repo + default branch) bound to
+     * a checkout-free {@link RepoFiles} so a registered custom kind's pre/post-op hooks
+     * read/commit a targeted subset of the repo WITHOUT a checkout. A facade composes it
+     * from its wired `GitHubClient` + `resolveRepoTarget` (`makeResolveRunRepoContext`).
+     * Absent (tests / GitHub not connected) → pre/post-ops are skipped.
+     */
+    resolveRunRepoContext?: ResolveRunRepoContext;
+    /**
+     * Optional: assert the workspace has a usable container-agent backend before a run
+     * starts (local mode delegating agents to a runner pool that isn't registered throws a
+     * clean {@link ConflictError} here). Absent → no start-time check (Cloudflare/Node have
+     * a fixed backend; a missing local pool still fails loudly at dispatch).
+     */
+    assertAgentBackendConfigured?: (workspaceId: string) => Promise<void>;
+    /**
+     * Optional: writes the engine's verification report (CI verdict, tester report, ephemeral
+     * environment lifecycle, merge assessment, run metadata + an observability deep link) onto
+     * the run's pull request as a marker-delimited, idempotently-updated section. A facade
+     * composes it from its engine VCS client, so GitLab deployments publish too. Absent (tests,
+     * a no-VCS deployment) → the engine behaves exactly as it did before the feature.
+     */
+    prVerificationReportPublisher?: PrVerificationReportPublisher;
+    /**
+     * Optional: the deployment's public SPA base URL, used to build the verification report's
+     * observability deep link. Absent → the report carries no link rather than a dead one.
+     */
+    appBaseUrl?: string;
+    /**
+     * Optional: the per-workspace settings row, read by the verification-report hook for the
+     * `publishPrVerificationReport` opt-out. Absent ⇒ the default (on).
+     */
+    workspaceSettingsRepository?: WorkspaceSettingsRepository;
+    /**
+     * Optional structured logger (the facade's pino logger) for the engine's best-effort paths —
+     * today the PR verification report, whose whole contract is that it never fails a run. Absent
+     * ⇒ those failures are silent, which is why every facade wires it.
+     */
+    logger?: PrReportLogger;
+}
+//# sourceMappingURL=ExecutionServiceDependencies.d.ts.map

package/dist/modules/execution/ExecutionServiceDependencies.d.ts.map

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

package/dist/modules/execution/ExecutionServiceDependencies.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ExecutionServiceDependencies.js.map

package/dist/modules/execution/ExecutionServiceDependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionServiceDependencies.js","sourceRoot":"","sources":["../../../src/modules/execution/ExecutionServiceDependencies.ts"],"names":[],"mappings":""}

package/dist/modules/execution/PrVerificationReportController.d.ts

@@ -0,0 +1,106 @@
+import type { BlockRepository, Clock, ExecutionInstance, PrVerificationReportPublisher, TaskRepository, WorkspaceSettingsRepository } from '@cat-factory/kernel';
+/** Minimal structured logger (pino-compatible); optional, like every other best-effort path. */
+export interface PrReportLogger {
+    warn(obj: Record<string, unknown>, msg?: string): void;
+}
+/**
+ * The engine collaborator that keeps a run's **verification report** on its pull request.
+ *
+ * Shape decision (see `docs/initiatives/pr-verification-report.md`, D2): this is an engine
+ * HOOK on step settlement, not a pipeline step — so it is pipeline-shape agnostic (a
+ * deployment-authored pipeline gets a report without editing it) and a run that fails or
+ * parks part-way still leaves its evidence on the PR. `RunDispatcher.recordStepResult` calls
+ * {@link publishForRun} once per settled step, positioned AFTER the terminal step resolver
+ * (so the `merger` step's publish carries the resolved `MergeDecision`) and BEFORE
+ * `finalizeBlock` (so the `pipeline_complete` card a merger-less pipeline raises points at a
+ * PR that already carries the finished report). A passing polling gate settles through the
+ * same `recordStepResult`, so the CI verdict needs no hook of its own.
+ *
+ * Everything it reports is already in memory on the {@link ExecutionInstance}; the only reads
+ * are one block point-read and one batched `listByBlock` for the linked tracker issues — no
+ * N+1, and no re-probe of the CI/mergeability providers (which would cost a round trip and
+ * could disagree with the verdict the gate actually acted on).
+ *
+ * Every failure mode is a silent no-op: no publisher wired (tests, a no-VCS deployment), no
+ * PR yet, an unchanged report, or a transport error. Publishing a report must never fail a
+ * run that otherwise succeeded.
+ */
+export interface PrVerificationReportControllerDeps {
+    blockRepository: BlockRepository;
+    clock: Clock;
+    /**
+     * Optional: writes the rendered section onto the block's PR. Absent (no VCS client wired)
+     * ⇒ every publish is a no-op, so the engine behaves exactly as it did before this feature.
+     */
+    publisher?: PrVerificationReportPublisher;
+    /** Optional: resolves the task's linked tracker issues in ONE batched read. */
+    taskRepository?: TaskRepository;
+    /**
+     * Optional: the per-workspace `publishPrVerificationReport` opt-out. Absent (or no saved
+     * settings row) ⇒ the default, which is ON — a deployment that wired a publisher wants the
+     * report.
+     */
+    workspaceSettingsRepository?: WorkspaceSettingsRepository;
+    /**
+     * Optional: the deployment's public SPA base URL, used to build the observability deep
+     * link. Absent ⇒ the report's `observability.runUrl` is null and no link is rendered
+     * (better than emitting a link to nowhere).
+     */
+    appBaseUrl?: string;
+    /**
+     * Optional structured logger for the best-effort failure path. Wire it: publishing is the
+     * one part of the run that is DESIGNED to fail silently, so without a log a revoked token or
+     * a rejected body leaves no trace anywhere — the report simply stops appearing.
+     */
+    logger?: PrReportLogger;
+}
+export declare class PrVerificationReportController {
+    private readonly deps;
+    /**
+     * The last section published per execution id, so settlements that change nothing a reader
+     * would see cost no PR edit at all.
+     *
+     * It does NOT collapse a run to one edit: the report carries a per-step state table, so most
+     * settlements genuinely do change it and the report tracks the run as it progresses — which
+     * is the intent ("rewritten in place as the run progresses"). What the cache removes is the
+     * repeat write from a replayed durable step, a re-poll, or a settlement whose evidence is
+     * identical to the last one.
+     *
+     * In-process only and deliberately so: it is a WRITE-AVOIDANCE cache, never a correctness
+     * mechanism — the marker splice is idempotent, so a cold process (or a peer replica) simply
+     * re-publishes the same section and the adapter's own unchanged-check suppresses the remote
+     * write.
+     */
+    private readonly lastPublished;
+    /**
+     * Hard cap on {@link lastPublished}. A long-lived Node replica serves an unbounded number of
+     * runs, and each entry holds a rendered section, so the map is bounded here rather than
+     * relying on a call site to evict finished runs (a coupling that would silently leak the
+     * moment a new terminal path forgot to call it). Oldest-first eviction: `Map` preserves
+     * insertion order, and evicting an entry only costs one redundant (idempotent) republish.
+     */
+    private static readonly MAX_TRACKED_RUNS;
+    constructor(deps: PrVerificationReportControllerDeps);
+    /**
+     * Compose the report for `instance` and upsert it onto the run's PR. Best-effort: returns
+     * silently on every skip/failure path.
+     */
+    publishForRun(workspaceId: string, instance: ExecutionInstance): Promise<void>;
+    /** Record the published fingerprint, evicting the oldest entry once the cap is reached. */
+    private remember;
+    /**
+     * The workspace's opt-out. Checked BEFORE anything is read or composed, so a workspace that
+     * turned the report off pays nothing for the hook. A workspace with no saved settings row
+     * reads as the default (on).
+     */
+    private publishingEnabled;
+    private linkedIssues;
+    /**
+     * The deep link into the run's observability panel (Model activity / Provided context).
+     * The SPA is a single canvas, so the target is the board with the run's view params — see
+     * `useRunDeepLink` in `@cat-factory/app`, and slice 4 of the global-search initiative,
+     * which will generalise the parser.
+     */
+    private runUrl;
+}
+//# sourceMappingURL=PrVerificationReportController.d.ts.map

package/dist/modules/execution/PrVerificationReportController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrVerificationReportController.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/PrVerificationReportController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,KAAK,EACL,iBAAiB,EAEjB,6BAA6B,EAC7B,cAAc,EACd,2BAA2B,EAC5B,MAAM,qBAAqB,CAAA;AAI5B,gGAAgG;AAChG,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,kCAAkC;IACjD,eAAe,EAAE,eAAe,CAAA;IAChC,KAAK,EAAE,KAAK,CAAA;IACZ;;;OAGG;IACH,SAAS,CAAC,EAAE,6BAA6B,CAAA;IACzC,+EAA+E;IAC/E,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B;;;;OAIG;IACH,2BAA2B,CAAC,EAAE,2BAA2B,CAAA;IACzD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAA;CACxB;AAED,qBAAa,8BAA8B;IA2B7B,OAAO,CAAC,QAAQ,CAAC,IAAI;IA1BjC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAE1D;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAM;IAE9C,YAA6B,IAAI,EAAE,kCAAkC,EAAI;IAEzE;;;OAGG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCnF;IAED,2FAA2F;IAC3F,OAAO,CAAC,QAAQ;IAUhB;;;;OAIG;YACW,iBAAiB;YAOjB,YAAY;IAY1B;;;;;OAKG;IACH,OAAO,CAAC,MAAM;CAef"}

package/dist/modules/execution/PrVerificationReportController.js

@@ -0,0 +1,134 @@
+import { DEFAULT_WORKSPACE_SETTINGS } from '@cat-factory/kernel';
+import { composePrVerificationReport, renderPrVerificationReport } from './prReport.logic.js';
+export class PrVerificationReportController {
+    deps;
+    /**
+     * The last section published per execution id, so settlements that change nothing a reader
+     * would see cost no PR edit at all.
+     *
+     * It does NOT collapse a run to one edit: the report carries a per-step state table, so most
+     * settlements genuinely do change it and the report tracks the run as it progresses — which
+     * is the intent ("rewritten in place as the run progresses"). What the cache removes is the
+     * repeat write from a replayed durable step, a re-poll, or a settlement whose evidence is
+     * identical to the last one.
+     *
+     * In-process only and deliberately so: it is a WRITE-AVOIDANCE cache, never a correctness
+     * mechanism — the marker splice is idempotent, so a cold process (or a peer replica) simply
+     * re-publishes the same section and the adapter's own unchanged-check suppresses the remote
+     * write.
+     */
+    lastPublished = new Map();
+    /**
+     * Hard cap on {@link lastPublished}. A long-lived Node replica serves an unbounded number of
+     * runs, and each entry holds a rendered section, so the map is bounded here rather than
+     * relying on a call site to evict finished runs (a coupling that would silently leak the
+     * moment a new terminal path forgot to call it). Oldest-first eviction: `Map` preserves
+     * insertion order, and evicting an entry only costs one redundant (idempotent) republish.
+     */
+    static MAX_TRACKED_RUNS = 256;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Compose the report for `instance` and upsert it onto the run's PR. Best-effort: returns
+     * silently on every skip/failure path.
+     */
+    async publishForRun(workspaceId, instance) {
+        const publisher = this.deps.publisher;
+        if (!publisher)
+            return;
+        try {
+            if (!(await this.publishingEnabled(workspaceId)))
+                return;
+            // Ask the adapter WHERE this would go before composing anything: it both short-circuits a
+            // run that has no PR yet (most runs, for most of their life) and supplies the repo +
+            // provider the report states — the same resolution the write itself uses, so the report
+            // can never name a different repo from the one it lands on.
+            const target = await publisher.resolveTarget(workspaceId, instance.blockId);
+            if (!target)
+                return;
+            const block = await this.deps.blockRepository.get(workspaceId, instance.blockId);
+            // Only a task carries an implementation PR; a frame/module run has nothing to report on.
+            if (!block)
+                return;
+            const section = renderPrVerificationReport(composePrVerificationReport(instance, {
+                block,
+                issues: await this.linkedIssues(workspaceId, instance.blockId),
+                repo: target.repo,
+                provider: target.provider,
+                runUrl: this.runUrl(workspaceId, instance),
+                now: this.deps.clock.now(),
+            }));
+            // `generatedAt` changes on every compose, so compare the section with it masked out —
+            // otherwise the cache would never hit and every step would edit the PR.
+            const fingerprint = section.replaceAll(/"generatedAt": \d+/g, '"generatedAt": 0');
+            if (this.lastPublished.get(instance.id) === fingerprint)
+                return;
+            await publisher.publish(workspaceId, block.id, section);
+            this.remember(instance.id, fingerprint);
+        }
+        catch (error) {
+            // A PR-report write is bookkeeping. A provider outage, a revoked token, or a PR someone
+            // closed underneath the run must never turn a green run red.
+            this.deps.logger?.warn({ err: error, executionId: instance.id, blockId: instance.blockId, workspaceId }, 'Failed to publish the PR verification report');
+        }
+    }
+    /** Record the published fingerprint, evicting the oldest entry once the cap is reached. */
+    remember(executionId, fingerprint) {
+        this.lastPublished.delete(executionId);
+        this.lastPublished.set(executionId, fingerprint);
+        while (this.lastPublished.size > PrVerificationReportController.MAX_TRACKED_RUNS) {
+            const oldest = this.lastPublished.keys().next();
+            if (oldest.done)
+                break;
+            this.lastPublished.delete(oldest.value);
+        }
+    }
+    /**
+     * The workspace's opt-out. Checked BEFORE anything is read or composed, so a workspace that
+     * turned the report off pays nothing for the hook. A workspace with no saved settings row
+     * reads as the default (on).
+     */
+    async publishingEnabled(workspaceId) {
+        const repo = this.deps.workspaceSettingsRepository;
+        if (!repo)
+            return true;
+        const settings = (await repo.get(workspaceId)) ?? DEFAULT_WORKSPACE_SETTINGS;
+        return settings.publishPrVerificationReport;
+    }
+    async linkedIssues(workspaceId, blockId) {
+        const repo = this.deps.taskRepository;
+        if (!repo)
+            return [];
+        const records = await repo.listByBlock(workspaceId, blockId);
+        return records.map((record) => ({
+            source: record.source,
+            externalId: record.externalId,
+            title: record.title,
+            url: record.url,
+        }));
+    }
+    /**
+     * The deep link into the run's observability panel (Model activity / Provided context).
+     * The SPA is a single canvas, so the target is the board with the run's view params — see
+     * `useRunDeepLink` in `@cat-factory/app`, and slice 4 of the global-search initiative,
+     * which will generalise the parser.
+     */
+    runUrl(workspaceId, instance) {
+        const base = this.deps.appBaseUrl?.trim();
+        if (!base)
+            return null;
+        // Built by hand rather than with `URLSearchParams`: orchestration is runtime-neutral and
+        // compiles without the DOM lib, so the global isn't in its type surface.
+        const query = Object.entries({
+            ws: workspaceId,
+            block: instance.blockId,
+            run: instance.id,
+            view: 'observability',
+        })
+            .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+            .join('&');
+        return `${base.replace(/\/$/, '')}/?${query}`;
+    }
+}
+//# sourceMappingURL=PrVerificationReportController.js.map