@defrex/autobuild 0.8.0 → 0.10.0

package/packages/core/src/operator/query.ts

@@ -1,16 +1,36 @@
+import { composeBuildConfig } from '../config/live'
+import type { PipelineSourceMeta } from '../config/pipeline-source'
 import { configSchema, type Config } from '../config/schema'
-import { detail, statusFilter, summarize, type BuildDetail, type BuildSummary } from '../cli/status'
+import {
+  BUILD_EFFECTIVE_CONFIG_ARTIFACT,
+  parseBuildConfigMetadata,
+  parseEffectiveBuildConfig,
+} from '../processes/build-execution-state'
+import type { Artifact } from '../store/types'
+import {
+  detail,
+  statusFilter,
+  summarizeFrom,
+  type BuildDetail,
+  type BuildSummary,
+} from '../cli/status'
 import { projectRepositoryStatus, type RepositoryStatus } from '../cli/repository-status'
 import { projectHarvestStatus, type HarvestStatusView } from '../cli/harvest'
 import {
   buildDashboardFromProjected,
+  effectiveStatus,
   projectBuild,
+  projectBuildFromFacts,
   type DashboardBuild,
   type DashboardModel,
 } from '../cli/dashboard/model'
-import { reduceBuild } from '../kernel/reducer'
+import { reduceBuild, type BuildState } from '../kernel/reducer'
+import { DISPATCHER_EFFECTIVE_CONFIG_ARTIFACT } from '../store/retention'
 import { reduceDispatchStatus } from '../kernel/dispatch-status'
-import { scanUnclaimedObservations } from '../processes/harvest'
+import { readRepoEventsIfRecorded, unclaimedObservationCount } from '../processes/harvest'
+import type { RepoViewStore } from '../processes/repo-view'
+import { withOperatorView } from './read-view'
+import type { RepositoryEvent } from '../events/repository'
 import type { BuildStore, Clock } from '../store/types'
 
 export type BuildListScope = 'active' | 'queued' | 'all'
@@ -25,21 +45,55 @@ export class OperatorQueryError extends Error {
   }
 }
 
-async function repoEvents(store: BuildStore, repo: string) {
-  return (await store.getRepo(repo)) === null ? [] : store.getRepoEvents(repo)
-}
-
 export async function listOperatorBuilds(opts: {
   store: BuildStore
   repo: string
   scope: BuildListScope
   now: Date
 }): Promise<BuildSummary[]> {
+  return withOperatorView(opts.store, opts.repo, 'builds', (view) => listFromView(view, opts))
+}
+
+async function listFromView(
+  view: RepoViewStore,
+  opts: { repo: string; scope: BuildListScope; now: Date },
+): Promise<BuildSummary[]> {
   const statuses = new Set(statusFilter(opts.scope === 'all', opts.scope === 'queued'))
+  // Records are read and held before the digest read: builds are never
+  // deleted, so every record iterated below is guaranteed an entry in the
+  // digest map fetched after it — a build created between the two reads
+  // appears only in the digest map, which is harmless — and the completeness
+  // check can only ever catch a genuine adapter bug, never a concurrent
+  // dispatch. The reverse order would let a concurrent creation abort the
+  // whole listing (AUT-488 finding f_3cb67aba).
+  const records = await view.listBuilds()
+  // One digest read gates the per-build reads (AUT-488): the active and queued
+  // scopes never show a terminal build, so a build whose digest already
+  // carries a terminal fact is skipped and the listing's cost stays flat as
+  // finished builds accumulate. The `--all` scope includes terminal statuses,
+  // so it takes no digest read and skips nothing; its terminal builds are
+  // restored from the reducer snapshots the dispatcher leaves at settlement.
+  const digests = opts.scope === 'all' ? undefined : await view.getRepoBuildDigests(opts.repo)
   const output: BuildSummary[] = []
-  for (const record of await opts.store.listBuilds()) {
+  for (const record of records) {
     if (record.repo !== opts.repo) continue
-    const projected = summarize(record, await opts.store.getEvents(record.slug), opts.now)
+    if (digests !== undefined) {
+      // Completeness is contractual (one entry per repo build); a missing
+      // entry is an adapter bug and must fail loudly rather than silently
+      // drop the build from the listing.
+      const digest = digests.get(record.slug)
+      if (digest === undefined) {
+        throw new Error(`getRepoBuildDigests is missing an entry for build "${record.slug}"`)
+      }
+      // The digest's `terminal` follows `reduceBuild`'s terminal rule exactly
+      // (in-order overwrite of `build.completed`/`build.aborted`, never
+      // cleared — pinned against `reduceBuild` in store/digest.test.ts), so
+      // `terminal !== undefined` is exactly reduced status `done`/`aborted`,
+      // which the active and queued status sets never include. Skipping the
+      // build therefore cannot change the emitted summaries.
+      if (digest.terminal !== undefined) continue
+    }
+    const projected = summarizeFrom(record, (await view.buildFacts(record.slug)).state, opts.now)
     if (statuses.has(projected.status)) output.push(projected)
   }
   return output.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
@@ -57,12 +111,15 @@ async function requireBuild(store: BuildStore, repo: string, slug: string) {
 export async function effectiveConfig(
   store: BuildStore,
   repo: string,
+  /** The bounded journal, when the caller already holds it (a repository
+   * view); otherwise it is read from the store. */
+  journal?: RepositoryEvent[],
 ): Promise<{
   config: Config
-  repositoryEvents: Awaited<ReturnType<typeof repoEvents>>
+  repositoryEvents: RepositoryEvent[]
   status: ReturnType<typeof reduceDispatchStatus>
 }> {
-  const repositoryEvents = await repoEvents(store, repo)
+  const repositoryEvents = journal ?? (await readRepoEventsIfRecorded(store, repo))
   let latestRun: string | undefined
   for (const event of repositoryEvents) {
     if (event.type === 'dispatcher.run-started') latestRun = event.payload.run
@@ -112,6 +169,65 @@ export interface OperatorBuildView {
   dashboardRow: DashboardBuild | null
 }
 
+interface PinnedProjection {
+  config: Config
+  revision?: number
+  pipelineSource?: PipelineSourceMeta
+}
+
+/** Read one build's pinned effective-config artifact (SPEC §16.1): its parsed
+ * build-owned sections composed over the live snapshot's deployment-owned
+ * ones, plus the artifact's metadata projection. Every row must be projected
+ * against the pipeline the build actually runs — the artifact's build-owned
+ * sections — never the dispatcher's live base-branch snapshot, which a pinned
+ * build may never execute. All read failures are display-only: an absent or
+ * malformed artifact degrades to the live config, the pre-pin behavior. */
+async function readPinnedConfig(
+  store: BuildStore,
+  slug: string,
+  live: Config,
+): Promise<PinnedProjection> {
+  let artifact: Artifact | null
+  try {
+    artifact = await store.getArtifact(slug, BUILD_EFFECTIVE_CONFIG_ARTIFACT)
+  } catch {
+    artifact = null
+  }
+  if (artifact === null) return { config: live }
+  let config: Config
+  try {
+    config = composeBuildConfig(parseEffectiveBuildConfig(artifact), live)
+  } catch {
+    config = live
+  }
+  return { config, ...parseBuildConfigMetadata(artifact) }
+}
+
+/** The shared null-row gate (AUT-486 snapshot, AUT-496 getOperatorBuild,
+ * AUT-487 digest): `effectiveStatus` maps only `done` outside the visible set
+ * (cli/dashboard/model.ts `isVisible`), so `projectBuild` returns null
+ * exactly for this state, and a pinned effective-config read for such a
+ * build could never be surfaced. One predicate so every consumer cannot
+ * diverge from each other or from the row projection: the digest's `terminal`
+ * is a third consumer of the same gate — `terminal === 'done'` is exactly
+ * `reduceBuild(...).status === 'done'` — and the snapshot uses it to skip a
+ * finished build's history and pinned-config reads without weakening this
+ * predicate as the authority. If cli/dashboard/model.ts ever adds a
+ * non-visible status, this predicate must follow — the snapshot
+ * byte-identical differential test and the done/aborted query tests pin the
+ * coupling. */
+function projectsNoDashboardRow(state: BuildState): boolean {
+  return effectiveStatus(state) === 'done'
+}
+
+/** Attach the effective-config metadata (SPEC §16.1) to a projected row so an
+ * operator can see which autobuild.toml the build runs under. */
+function decorateWithPinnedMeta(row: DashboardBuild, pinned: PinnedProjection): DashboardBuild {
+  if (pinned.revision !== undefined) row.effectiveConfigRev = pinned.revision
+  if (pinned.pipelineSource !== undefined) row.pipelineSource = pinned.pipelineSource
+  return row
+}
+
 export async function getOperatorBuild(opts: {
   store: BuildStore
   repo: string
@@ -122,22 +238,36 @@ export async function getOperatorBuild(opts: {
   const events = await opts.store.getEvents(opts.slug)
   const state = reduceBuild(events)
   const { config } = await effectiveConfig(opts.store, opts.repo)
-  const dashboardRow = projectBuild(record, state, config, events)
-  return { detail: detail(record, events, opts.now), dashboardRow }
+  let dashboardRow: DashboardBuild | null = null
+  if (!projectsNoDashboardRow(state)) {
+    const pinned = await readPinnedConfig(opts.store, opts.slug, config)
+    const row = projectBuild(record, state, config, events, undefined, pinned.config)
+    // Implied by the gate; kept as an explicit check (not an assertion) so the
+    // code never lies if `effectiveStatus` and `projectBuild` ever drift.
+    if (row !== null) dashboardRow = decorateWithPinnedMeta(row, pinned)
+  }
+  return {
+    detail: detail(record, events, opts.now),
+    dashboardRow,
+  }
 }
 
 export async function getRepositoryStatus(
   store: BuildStore,
   repo: string,
 ): Promise<RepositoryStatus> {
-  return projectRepositoryStatus(repo, await repoEvents(store, repo))
+  return withOperatorView(store, repo, 'journal', async (view) =>
+    projectRepositoryStatus(repo, view.recordedJournal()),
+  )
 }
 
 export async function getHarvestStatus(
   store: BuildStore,
   repo: string,
 ): Promise<HarvestStatusView> {
-  return projectHarvestStatus(repo, await repoEvents(store, repo))
+  return withOperatorView(store, repo, 'journal', async (view) =>
+    projectHarvestStatus(repo, view.recordedJournal()),
+  )
 }
 
 export interface OperatorDashboardSnapshot {
@@ -156,18 +286,68 @@ export async function getOperatorDashboard(opts: {
   repo: string
   clock: Clock
 }): Promise<OperatorDashboardSnapshot> {
-  const { config, repositoryEvents, status } = await effectiveConfig(opts.store, opts.repo)
+  return withOperatorView(opts.store, opts.repo, 'builds', (view) => dashboardFromView(view, opts))
+}
+
+async function dashboardFromView(
+  view: RepoViewStore,
+  opts: { repo: string; clock: Clock },
+): Promise<OperatorDashboardSnapshot> {
+  const { config, repositoryEvents, status } = await effectiveConfig(
+    view,
+    opts.repo,
+    view.recordedJournal(),
+  )
+  const records = await view.listBuilds()
+  // One digest read covers every build of the repository (AUT-487): the
+  // row gate (a `done` digest means no row) and the observation count need no
+  // per-build histories, so the snapshot's traffic stays flat as finished
+  // builds accumulate. Row-rendering builds derive from the repository view's
+  // reducer snapshots plus a delta read (AUT-650); every snapshot is a cache
+  // the event log regenerates, so the response equals a full replay's.
+  const digests = await view.getRepoBuildDigests(opts.repo)
   const projected: DashboardBuild[] = []
   let activeCount = 0
-  for (const record of await opts.store.listBuilds()) {
+  for (const record of records) {
     if (record.repo !== opts.repo) continue
-    const events = await opts.store.getEvents(record.slug)
-    const state = reduceBuild(events)
-    if (state.status !== 'done' && state.status !== 'aborted') activeCount += 1
-    const row = projectBuild(record, state, config, events)
-    if (row !== null) projected.push(row)
+    const digest = digests.get(record.slug)
+    // Completeness is contractual (one entry per repo build); a missing entry
+    // is an adapter bug and must fail loudly rather than silently drop the
+    // build from the active count or the row list.
+    if (digest === undefined) {
+      throw new Error(`getRepoBuildDigests is missing an entry for build "${record.slug}"`)
+    }
+    // Reduced status is `done`/`aborted` exactly when a terminal fact exists,
+    // so `terminal === undefined` is exactly the old active test — no history
+    // read needed for the count.
+    if (digest.terminal === undefined) activeCount += 1
+    if (digest.terminal === 'done') continue
+    // Both query surfaces share the `projectsNoDashboardRow` gate (AUT-486
+    // snapshot, AUT-496 detail query): a build that projects no row —
+    // `effectiveStatus` maps only `done` outside the visible set — never
+    // reads its pinned effective-config artifact, because the read result
+    // could never be surfaced. The digest already excluded `done` builds
+    // above; the gate stays as the authority for the row projection so the
+    // digest and the reducer cannot silently diverge. Every row-rendering
+    // build still gets its facts and pinned pipeline.
+    const facts = await view.buildFacts(record.slug)
+    if (projectsNoDashboardRow(facts.state)) continue
+    const pinned = await readPinnedConfig(view, record.slug, config)
+    const row = projectBuildFromFacts(
+      record,
+      facts.state,
+      { dashboard: facts.dashboard, log: facts.log, deferral: facts.deferral },
+      config,
+      undefined,
+      pinned.config,
+    )
+    if (row !== null) projected.push(decorateWithPinnedMeta(row, pinned))
   }
-  const scan = await scanUnclaimedObservations(opts.store, opts.repo)
+  // The unclaimed-observation count comes from the digests and the journal
+  // `effectiveConfig` already returned — no per-build history reads (AUT-487).
+  // The pure core writes nothing — a snapshot performs no store writes and
+  // never creates or locks the repository record.
+  const observationCount = unclaimedObservationCount({ digests, harvestEvents: repositoryEvents })
   const warningLines = [
     ...status.roleWarnings,
     ...(status.warningNotice !== undefined ? [status.warningNotice] : []),
@@ -179,7 +359,7 @@ export async function getOperatorDashboard(opts: {
       queued: status.queued ?? 0,
       activeCount,
       capacity: config.capacity,
-      observationCount: scan.observations.length,
+      observationCount,
       observationLimit: config.policy.harvestThreshold,
       ...(status.availableUpgrade !== undefined
         ? { availableUpgrade: status.availableUpgrade }
@@ -199,3 +379,52 @@ export async function getOperatorDashboard(opts: {
     },
   }
 }
+
+/** Thrown when a deposited `dispatcher-effective-config` artifact exists but
+ * cannot be parsed or validated: the hosted message route maps this to a 500
+ * `internal` — a broken config must never silently disable the orchestrator
+ * (AUT-342). */
+export class OrchestratorConfigError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'OrchestratorConfigError'
+  }
+}
+
+/** The repository's orchestrator configuration, resolved from the latest
+ * deposited `dispatcher-effective-config` artifact (AUT-342). Returns null
+ * when no artifact exists — the orchestrator is disabled, and message
+ * posting behaves exactly as it did before this feature. Throws
+ * `OperatorQueryError` (code `effective-config-unavailable`) when an
+ * artifact exists but is unreadable or invalid: a deployment that deposited
+ * a broken config must fail loudly (a 500 on the message route), never
+ * silently disable the orchestrator. */
+export async function orchestratorConfig(store: BuildStore, repo: string): Promise<Config | null> {
+  // A repository the store has no record for has no deposited artifact and
+  // no dispatcher history: the orchestrator is disabled there.
+  if ((await store.getRepo(repo)) === null) return null
+  const artifacts = await store.listRepoArtifacts(repo, DISPATCHER_EFFECTIVE_CONFIG_ARTIFACT)
+  if (artifacts.length === 0) return null
+  const latest = [...artifacts].sort((a, b) => b.revision - a.revision)[0]!
+  const artifact = await store.getRepoArtifact(repo, latest.kind, latest.revision)
+  if (artifact === null) {
+    throw new OrchestratorConfigError(
+      `effective config ${latest.kind}@${latest.revision} is not retrievable`,
+    )
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(new TextDecoder().decode(artifact.content))
+  } catch {
+    throw new OrchestratorConfigError(
+      `effective config ${latest.kind}@${latest.revision} is not valid JSON`,
+    )
+  }
+  const parsed = configSchema.safeParse(raw)
+  if (!parsed.success) {
+    throw new OrchestratorConfigError(
+      `effective config ${latest.kind}@${latest.revision} is invalid: ${parsed.error.message}`,
+    )
+  }
+  return parsed.data.orchestrator.enabled ? parsed.data : null
+}

package/packages/core/src/operator/read-view.ts

@@ -0,0 +1,98 @@
+/**
+ * The operator read paths' repository view: every poll-driven route (dashboard,
+ * repository and harvest status, build listings) derives its state from a
+ * `RepoViewStore` cold-started from stored reducer snapshots and advanced with
+ * delta reads, so a poll's event-row cost follows the events appended since the
+ * last one, never the history, the open tabs, or the watchers.
+ *
+ * Passes are single-flight per `(store, repo)` within one serving process: at
+ * most one pass runs at a time, and requests arriving while it runs join the
+ * one trailing pass (each needs state at least as new as its arrival, which the
+ * running pass cannot promise). That trailing pass restores from the snapshot
+ * the previous pass persisted, so N concurrent pollers cost one delta read per
+ * pass, not N. The coordination is scheduling inside this process; every datum
+ * still comes from durable state, and a second serving process simply reads the
+ * same delta once itself (duplicate reads are bounded by the process count).
+ */
+import { RepoViewStore } from '../processes/repo-view'
+import type { BuildStore } from '../store/types'
+
+/** What a request reads: the journal alone, or the builds beside it. */
+export type OperatorViewNeed = 'journal' | 'builds'
+
+interface Waiter {
+  need: OperatorViewNeed
+  run: (view: RepoViewStore) => Promise<unknown>
+  resolve: (value: unknown) => void
+  reject: (error: unknown) => void
+}
+
+interface Flight {
+  running: boolean
+  queue: Waiter[]
+}
+
+const flights = new WeakMap<BuildStore, Map<string, Flight>>()
+
+function flightFor(store: BuildStore, repo: string): Flight {
+  let byRepo = flights.get(store)
+  if (byRepo === undefined) {
+    byRepo = new Map()
+    flights.set(store, byRepo)
+  }
+  let flight = byRepo.get(repo)
+  if (flight === undefined) {
+    flight = { running: false, queue: [] }
+    byRepo.set(repo, flight)
+  }
+  return flight
+}
+
+async function pass(store: BuildStore, repo: string, waiters: Waiter[]): Promise<void> {
+  const view = new RepoViewStore(store, { repo })
+  try {
+    if (waiters.some((waiter) => waiter.need === 'builds')) await view.refresh()
+    else await view.startJournal()
+  } catch (error) {
+    for (const waiter of waiters) waiter.reject(error)
+    return
+  }
+  await Promise.all(waiters.map((waiter) => waiter.run(view).then(waiter.resolve, waiter.reject)))
+  // Leave the advanced state behind for the next pass (this process's or
+  // another's). `held` also writes a settled build read for a listing. The
+  // cache never fails a read.
+  try {
+    await view.persistSnapshots({ force: true, held: true })
+  } catch {
+    // A cache: the next pass retries.
+  }
+}
+
+async function drain(store: BuildStore, repo: string, flight: Flight): Promise<void> {
+  flight.running = true
+  try {
+    while (flight.queue.length > 0) {
+      const waiters = flight.queue
+      flight.queue = []
+      await pass(store, repo, waiters)
+    }
+  } finally {
+    flight.running = false
+  }
+}
+
+/** Run `run` against a freshly advanced repository view. The view is only valid
+ * inside `run`; the response must not hold it. */
+export function withOperatorView<T>(
+  store: BuildStore,
+  repo: string,
+  need: OperatorViewNeed,
+  run: (view: RepoViewStore) => Promise<T>,
+): Promise<T> {
+  const flight = flightFor(store, repo)
+  const result = new Promise<T>((resolve, reject) => {
+    flight.queue.push({ need, run, resolve: resolve as (value: unknown) => void, reject })
+  })
+  if (!flight.running) void drain(store, repo, flight)
+  return result
+}

package/packages/core/src/operator/registry.ts

@@ -15,7 +15,8 @@
  * carried as base64 strings at the entry level (`builds.artifact`'s
  * `contentBase64` is the base64 of the exact artifact bytes), so a binding's
  * `JSON.stringify` can never silently corrupt bytes. The contract suite
- * (registry.contract.test.ts) asserts the round-trip for every tool.
+ * (packages/hosted-store-service/src/registry.contract.test.ts) asserts the
+ * round-trip for every tool.
  *
  * Risk classes live in `operator/annotations.ts` (checked in, enforced by the
  * contract suite). The registry itself enforces only what every binding needs
@@ -428,6 +429,25 @@ const sandboxWriteFileInput = z.strictObject({
 
 const sandboxResetInput = z.strictObject({ repo: repoField })
 
+const sandboxPublishInput = z.strictObject({
+  repo: repoField,
+  title: z.string().min(1).max(200).describe('Pull-request title, 1-200 characters.'),
+  body: z
+    .string()
+    .max(65_536)
+    .optional()
+    .describe(
+      'Optional pull-request body, at most 65,536 characters; an attribution block naming the operator and session is appended automatically.',
+    ),
+  commit: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Optional commit-ish to publish instead of the checkout HEAD; must resolve to a commit that is a descendant of the base head recorded at provision or reset time.',
+    ),
+})
+
 // ── The closed version-one table ─────────────────────────────────────────────
 
 function defineTool(
@@ -455,7 +475,7 @@ function defineTool(
 
 /** The closed version-one tool table. Adding a tool means adding an entry
  * here and a row in `operator/annotations.ts`; the contract suite proves the
- * two stay in lockstep. Sandbox and publish tools are later tickets. */
+ * two stay in lockstep. */
 export const TOOLS: readonly ToolEntry[] = [
   defineTool(
     'builds.list',
@@ -893,6 +913,22 @@ export const TOOLS: readonly ToolEntry[] = [
       return { ok: true as const }
     },
   ),
+  defineTool(
+    'sandbox.publish',
+    "Publish your operator sandbox's work as a pull request: push the checkout's current head commit (or an explicit commit) to your operator's dedicated branch and open or update a PR against the base branch. Refuses when the checkout has uncommitted changes (tracked or untracked; the sandbox's own provisioning marker is excluded), when the commit is not a descendant of the base head recorded at provision or reset time, or when the base branch head itself would be published. The sandbox itself never pushes and holds no credential — the push and PR creation are kernel plumbing; a publication is a durable repository-journal fact. PR only: the base branch is never pushed to.",
+    sandboxPublishInput,
+    '{branch, sha, pr: {number, url, headSha}}: the publication branch, the published commit, and the opened or updated pull request.',
+    async (raw, ctx) => {
+      const input = raw as z.infer<typeof sandboxPublishInput>
+      return sandboxOf(ctx).publish(attributed(ctx), {
+        repo: input.repo,
+        title: input.title,
+        ...(input.body !== undefined ? { body: input.body } : {}),
+        ...(input.commit !== undefined ? { commit: input.commit } : {}),
+        ...(ctx.via !== undefined ? { via: ctx.via } : {}),
+      })
+    },
+  ),
 ]
 
 // ── The registry constructor ─────────────────────────────────────────────────
@@ -900,8 +936,9 @@ export const TOOLS: readonly ToolEntry[] = [
 export interface RegistryOptions {
   store: BuildStore
   tickets?: OperatorTicketBackend
-  /** The operator-sandbox backend; when absent the six sandbox tools are
-   * neither advertised nor callable (the compatibility case). */
+  /** The operator-sandbox backend; when absent the sandbox tools are
+   * neither advertised nor callable (the compatibility case). When present
+   * but `canPublish` is false, only `sandbox.publish` is filtered. */
   sandbox?: OperatorSandboxService
   clock?: Clock
   /** Constrain every call to this repository identity (the `ab mcp --repo` flag). */
@@ -917,7 +954,8 @@ export interface OperatorToolRegistry {
 }
 
 /** Map a service error to the registry's operator-API-shaped failure body —
- * the same kind mapping as the catch block in operator/server.ts. */
+ * the same kind mapping as the catch block in the hosted package's
+ * operator-server.ts. */
 function mapDomainError(error: unknown): RegistryError {
   if (error instanceof RegistryError) return error
   if (error instanceof RouteRefusalError) {
@@ -976,15 +1014,22 @@ function mapDomainError(error: unknown): RegistryError {
 /** Bind the closed table to an opened store (and optional ticket and sandbox
  * backends). The returned registry is the in-process binding; every other
  * binding is generated from `entries`. Advertisement and dispatch share ONE
- * table: without a sandbox backend the six sandbox tools are filtered from
- * `entries` AND from `call()` dispatch, so a binding that cannot provision
- * sandboxes never advertises or serves them. */
+ * table: a filtered tool is neither advertised nor served. */
 export function buildRegistry(options: RegistryOptions): OperatorToolRegistry {
   const sandboxToolNames = new Set(
     Object.keys(OPERATOR_TOOL_ANNOTATIONS).filter((name) => name.startsWith('sandbox.')),
   )
-  const table =
-    options.sandbox === undefined ? TOOLS.filter((tool) => !sandboxToolNames.has(tool.name)) : TOOLS
+  // Without a sandbox backend every sandbox tool is filtered; with a backend
+  // that cannot publish (no forge or no provider publication capability),
+  // only `sandbox.publish` is filtered. Filtered tools are absent from
+  // `entries` AND from `call()` dispatch.
+  const filtered = new Set<string>()
+  if (options.sandbox === undefined) {
+    for (const name of sandboxToolNames) filtered.add(name)
+  } else if (options.sandbox.canPublish === false) {
+    filtered.add('sandbox.publish')
+  }
+  const table = filtered.size === 0 ? TOOLS : TOOLS.filter((tool) => !filtered.has(tool.name))
   return {
     entries: table,
     async call(name, input, partial = {}) {

package/packages/core/src/operator/requests.ts

@@ -4,9 +4,10 @@
  *
  * This module is registry-owned on purpose: the operator API routes were
  * declared out of scope for the registry ticket, so the parity between a
- * tool and its route is *proven* by the contract suite (registry.contract
- * .test.ts) rather than obtained by extraction. Every refusal text here is
- * load-bearing — it must stay byte-identical to `operator/server.ts` so the
+ * tool and its route is *proven* by the contract suite
+ * (packages/hosted-store-service/src/registry.contract.test.ts) rather than
+ * obtained by extraction. Every refusal text here is load-bearing — it must
+ * stay byte-identical to the hosted package's `operator-server.ts` so the
  * suite's full-body comparisons hold.
  */
 import { reduceBuild } from '../kernel/reducer'
@@ -34,7 +35,8 @@ export class RouteRefusalError extends Error {
   }
 }
 
-/** `requireRouteBuild` (operator/server.ts): 404 unless the slug exists and
+/** `requireRouteBuild` (the hosted package's operator-server.ts): 404 unless
+ * the slug exists and
  * belongs to the named repository. */
 export async function requireRouteBuild(
   store: BuildStore,
@@ -61,7 +63,7 @@ export function parseArtifactRevision(raw: string): number {
 /**
  * The route's control-request prechecks: build existence/repo, then the
  * pending-state checks for pause and cancel-pause. Byte-identical to the
- * `POST …/control` branch in operator/server.ts.
+ * `POST …/control` branch in the hosted package's operator-server.ts.
  */
 export async function controlPrechecks(
   store: BuildStore,
@@ -97,7 +99,8 @@ export async function controlPrechecks(
 
 /**
  * The route's answer request → `BuildControlAction` translation, byte-identical
- * to the `POST …/answer` branch in operator/server.ts. The ticket-origin body
+ * to the `POST …/answer` branch in the hosted package's operator-server.ts.
+ * The ticket-origin body
  * reader travels separately, exactly as the route passes `readTicketBody`.
  */
 export function answerAction(request: OperatorAnswerRequest): {