@sixb/core 0.1.14 → 0.1.15

package/src/deploy/types.ts

@@ -0,0 +1,338 @@
+/**
+ * A deployment of this project: which services run, how browsers reach them, and the target that
+ * runs them. `sixb deploy` loads it from `sixb.deploy.ts`; the running app never reads it.
+ */
+export interface DeployConfig {
+  /**
+   * Names the deployment on its target and in default domains. Lowercase letters, numbers, and
+   * hyphens.
+   */
+  readonly name: string
+  /**
+   * Parent domain for HTTP services without their own `domain`: `<name>-<service>.<domain>`.
+   * Required unless every enabled HTTP service sets `domain`.
+   */
+  readonly domain?: string
+  /** Where the services run, such as `new SshTarget({ host })` from `@sixb/deploy-ssh`. */
+  readonly target: DeployTarget
+  /**
+   * Environment for every service and release step. Committed with the project, so secrets
+   * belong in the target's `.env` instead.
+   */
+  readonly env?: DeployEnv
+  /** Override or disable the Sixb services. Every service runs unless set to `false`. */
+  readonly services?: DeployServicesConfig
+  /** Long-running project scripts, supervised alongside the Sixb services. */
+  readonly processes?: Readonly<Record<string, DeployProcessDefinition>>
+}
+
+export type DeployEnv = Readonly<Record<string, string>>
+
+/** The services a browser or client reaches through a public domain. */
+export type DeployHttpServiceName = "api" | "atlas" | "app"
+
+/** The services that must run as exactly one process: a second would duplicate their work. */
+export type DeploySingletonServiceName = "orchestrator" | "scheduler" | "rules"
+
+export type DeployServiceName = DeployHttpServiceName | DeploySingletonServiceName | "workers"
+
+export type DeployWorkerType = "sync" | "action" | "agent" | "pipeline" | "projection" | "workflow"
+
+/** Action jobs run one at a time, so their concurrency is fixed. */
+export type DeployConfigurableWorkerType = Exclude<DeployWorkerType, "action">
+
+export interface DeployServicesConfig {
+  readonly api?: boolean | DeployHttpServiceConfig
+  readonly atlas?: boolean | DeployHttpServiceConfig
+  readonly app?: boolean | DeployHttpServiceConfig
+  readonly orchestrator?: boolean | DeploySingletonServiceConfig
+  readonly scheduler?: boolean | DeploySingletonServiceConfig
+  readonly rules?: boolean | DeploySingletonServiceConfig
+  readonly workers?: boolean | DeployWorkersConfig
+}
+
+export interface DeployHttpServiceConfig {
+  /** Public hostname. Defaults to `<name>-<service>.<domain>`. */
+  readonly domain?: string
+  /** Added to the deployment's `env` for this service only. */
+  readonly env?: DeployEnv
+  readonly process?: DeployProcessOptions
+}
+
+export interface DeploySingletonServiceConfig {
+  /** Added to the deployment's `env` for this service only. */
+  readonly env?: DeployEnv
+  readonly process?: DeployProcessOptions
+}
+
+export interface DeployWorkersConfig {
+  /**
+   * The worker types to run. `"all"`, the default, runs every type the project registers work
+   * for.
+   */
+  readonly types?: readonly DeployWorkerType[] | "all"
+  /** Wall-clock budget for one agent turn, such as `"30s"`, `"10m"`, or `"1h"`. */
+  readonly agentTurnTimeout?: string
+  /** Jobs each worker type runs at once inside one process. */
+  readonly concurrency?: Readonly<Partial<Record<DeployConfigurableWorkerType, number>>>
+  /** Added to the deployment's `env` for the workers only. */
+  readonly env?: DeployEnv
+  readonly process?: DeployScalableProcessOptions
+}
+
+export interface DeployProcessDefinition {
+  /** Script to run with Bun, relative to the project directory. */
+  readonly entrypoint: string
+  readonly args?: readonly string[]
+  /** Added to the deployment's `env` for this process only. */
+  readonly env?: DeployEnv
+  readonly process?: DeployScalableProcessOptions
+}
+
+export interface DeployProcessOptions {
+  /** How long a stopping process may take before it is killed. Defaults to 10000. */
+  readonly killTimeoutMs?: number
+  /** Wait before restarting a process that exited, growing with each restart. Defaults to 1000. */
+  readonly restartDelayMs?: number
+  /** Restart the process when its memory passes this size, such as `"512M"` or `"2G"`. */
+  readonly maxMemory?: string
+}
+
+export interface DeployScalableProcessOptions extends DeployProcessOptions {
+  /** How many copies of the process to run. Defaults to 1. */
+  readonly instances?: number
+}
+
+/**
+ * Runs a deployment. `@sixb/deploy-ssh` provides the SSH target. Third-party targets are not
+ * supported in 0.1.x: this contract still grows with each thing `sixb deploy` learns to do.
+ */
+export interface DeployTarget {
+  /** The kind of target, shown in `sixb deploy` output, such as `"ssh"`. */
+  readonly kind: string
+  /** Where the deployment runs, shown in output, such as `"sixb@203.0.113.10"`. */
+  readonly location: string
+  /** The address an HTTP service listens on, where the target's proxy reaches it. */
+  listenAddress(service: DeployHttpServiceName): DeployListenAddress
+  /**
+   * Ships the source, runs the release, and resolves once its services answer. Rejects with the
+   * reason when a step fails; the steps it reported say how far it got.
+   */
+  deploy(release: DeployRelease, source: DeploySource, context: DeployContext): Promise<void>
+  /** What the deployment runs right now, and which release it runs. */
+  status(context: DeployOperationContext): Promise<DeployStatus>
+  /** Writes recent log lines, then new ones as they arrive when `follow` is set. */
+  logs(options: DeployLogsOptions, context: DeployOperationContext): Promise<void>
+  /** Restarts, stops, or starts one service, or every service. */
+  control(
+    action: DeployControlAction,
+    service: string | undefined,
+    context: DeployOperationContext
+  ): Promise<void>
+  /** What stands between the target and a working deploy of the release, changing nothing. */
+  check(release: DeployRelease, context: DeployCheckContext): Promise<readonly DeployCheck[]>
+  /** Prepares the target for the release, fixing what `check` reports as fixable. */
+  setup?(release: DeployRelease, context: DeploySetupContext): Promise<void>
+  /** Who may deploy and operate the deployment, for a target reached with keys. */
+  readonly access?: DeployAccess
+  /** Credentials for a CI job that deploys, for a target reached with keys. */
+  readonly ci?: DeployCi
+}
+
+export interface DeployCheck {
+  readonly id: string
+  /** What was checked, such as `"SSH"` or `"api DNS"`. */
+  readonly label: string
+  /**
+   * `fixable`: `sixb deploy setup` fixes it. `manual`: only you can, as `remedy` says. Both stop
+   * a deploy; a `warning` does not.
+   */
+  readonly status: "ok" | "fixable" | "manual" | "warning"
+  readonly detail: string
+  /** What to do about it, when the status is not `ok`. */
+  readonly remedy?: string
+}
+
+export interface DeployCheckContext extends DeployOperationContext {
+  /** The project's directory inside its repository: `.` at the root. */
+  readonly projectPath: string
+}
+
+export interface DeploySetupContext extends DeployCheckContext {
+  /** The account with sudo that prepares a server, for a target that needs one. */
+  readonly admin?: string
+  /** A public key file to authorize for deploys, instead of the one the target would pick. */
+  readonly key?: string
+  /** A line of progress for the person running setup. */
+  write(line: string): void
+}
+
+export interface DeployAccess {
+  list(context: DeployOperationContext): Promise<readonly DeployAccessKey[]>
+  /** Authorizes a public key, given as its text (`ssh-ed25519 AAAA… comment`). */
+  add(key: string, context: DeployOperationContext): Promise<DeployAccessKey>
+  /** Revokes the keys whose fingerprint or comment matches, and returns them. */
+  remove(match: string, context: DeployOperationContext): Promise<readonly DeployAccessKey[]>
+}
+
+export interface DeployAccessKey {
+  readonly type: string
+  readonly fingerprint: string
+  readonly comment: string
+  /** Whether the key is limited to running commands: no forwarding, no terminal. */
+  readonly restricted: boolean
+}
+
+/**
+ * Lets a CI job deploy. `sixb deploy ci` stores what `create` returns as the CI system's secrets and
+ * writes the workflow around it.
+ */
+export interface DeployCi {
+  /**
+   * Creates a credential for one CI job, such as `"github:acme/shop"`, and authorizes it on the
+   * target next to the job's earlier ones. Running it again for the same job rotates the credential.
+   */
+  create(job: string, context: DeployOperationContext): Promise<DeployCiCredential>
+}
+
+export interface DeployCiCredential {
+  /** Describes the credential, such as its key's fingerprint. */
+  readonly description: string
+  /** What the CI job needs, by environment variable name. CI stores them as secrets. */
+  readonly secrets: Readonly<Record<string, string>>
+  /** Shell lines that install the credential on the CI runner, with `secrets` in the environment. */
+  readonly install: readonly string[]
+  /** Revokes the job's earlier credentials once CI holds this one, and returns them. */
+  retireOthers(): Promise<readonly DeployAccessKey[]>
+  /** Revokes this credential, when CI could not store it. */
+  revoke(): Promise<void>
+}
+
+export interface DeployListenAddress {
+  readonly host: string
+  readonly port: number
+}
+
+/**
+ * Everything a deployment runs, resolved by `sixb deploy` from `sixb.deploy.ts`. A target decides
+ * where and how it runs; which processes exist, and the command each one starts with, come from
+ * Sixb.
+ */
+export interface DeployRelease {
+  readonly name: string
+  readonly target: { readonly kind: string; readonly location: string }
+  /** The Bun version the project runs on. */
+  readonly bunVersion: string
+  /** The environment every step and service starts from. */
+  readonly env: DeployEnv
+  readonly steps: {
+    /** Runs while the previous release still serves. */
+    readonly build: readonly DeployCommand[]
+    /** Runs after the services stop and before they start again. */
+    readonly beforeStart: readonly DeployCommand[]
+  }
+  readonly services: readonly DeployReleaseService[]
+}
+
+export interface DeployCommand {
+  /** `sixb` is the CLI the project installs; `bun` runs a project script. */
+  readonly program: "sixb" | "bun"
+  readonly args: readonly string[]
+}
+
+export interface DeployReleaseService {
+  readonly name: string
+  readonly kind: "http" | "singleton" | "workers" | "script"
+  readonly command: DeployCommand
+  /** The complete environment: the release's, then the service's own additions. */
+  readonly env: DeployEnv
+  readonly instances: number
+  readonly http?: DeployReleaseHttp
+  readonly process: DeployReleaseProcess
+}
+
+export interface DeployReleaseHttp extends DeployListenAddress {
+  readonly domain: string
+  readonly publicOrigin: string
+  /** Answers once the service can take traffic, when the service has such a route. */
+  readonly readinessPath?: string
+}
+
+export interface DeployReleaseProcess {
+  readonly killTimeoutMs: number
+  readonly restartDelayMs: number
+  readonly maxMemory?: string
+}
+
+/** The committed files a deployment runs, read from git by `sixb deploy`. */
+export interface DeploySource {
+  /** The commit being deployed. */
+  readonly commit: string
+  /** What the deployer asked for, such as `HEAD` or `main`. */
+  readonly ref: string
+  /** The project's directory inside the repository: `.` at its root. */
+  readonly projectPath: string
+  /** Tar archives of the committed files: the repository first, then each submodule. */
+  readonly archives: readonly DeploySourceArchive[]
+}
+
+export interface DeploySourceArchive {
+  /** Where the archive's files belong, relative to the repository root: `.` for the root. */
+  readonly path: string
+  open(): ReadableStream<Uint8Array>
+}
+
+export interface DeployOperationContext {
+  /** The deployment's `name`, which a target may run several of. */
+  readonly name: string
+}
+
+export interface DeployContext extends DeployOperationContext {
+  /** Who deployed, recorded with the release. */
+  readonly deployedBy: string
+  report(event: DeployEvent): void
+}
+
+export type DeployEvent =
+  /** The steps the deployment will run, reported before the first one starts. */
+  | { readonly type: "steps"; readonly labels: readonly string[] }
+  | { readonly type: "step"; readonly index: number; readonly status: "running" | "done" }
+  | { readonly type: "output"; readonly line: string }
+
+export interface DeployStatus {
+  /** The release the target last deployed, if any. */
+  readonly release: DeployRecord | null
+  /** Whether the target's process supervisor is running. */
+  readonly running: boolean
+  readonly processes: readonly DeployProcessStatus[]
+}
+
+export interface DeployRecord {
+  readonly commit: string
+  readonly ref: string
+  readonly deployedAt: string
+  readonly deployedBy: string
+}
+
+export interface DeployProcessStatus {
+  readonly service: string
+  readonly instance: number
+  readonly status: "starting" | "running" | "stopping" | "stopped" | "exited"
+  readonly pid?: number
+  readonly restarts: number
+  readonly startedAt?: string
+  readonly cpuPercent?: number
+  readonly memoryBytes?: number
+  readonly lastError?: string
+}
+
+export interface DeployLogsOptions {
+  /** One service's logs, or every service's. */
+  readonly service?: string
+  /** How many recent lines to write first. */
+  readonly tail: number
+  readonly follow: boolean
+  write(line: string): void
+}
+
+export type DeployControlAction = "restart" | "start" | "stop"

package/src/deploy/validation.ts

@@ -0,0 +1,261 @@
+import {
+  DEPLOY_CONFIGURABLE_WORKER_TYPES,
+  DEPLOY_SERVICES,
+  DEPLOY_WORKER_TYPES,
+  isDeployHttpService,
+  isDeploySingletonService,
+} from "./services"
+import type { DeployConfig } from "./types"
+
+type UnknownRecord = Record<string, unknown>
+
+const NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
+const DOMAIN_LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?"
+const DOMAIN_PATTERN = new RegExp(`^${DOMAIN_LABEL}(?:\\.${DOMAIN_LABEL})*$`, "i")
+const ENV_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/
+const MEMORY_PATTERN = /^\d+(?:\.\d+)?\s*(?:b|k|kb|m|mb|g|gb)?$/i
+/** Longest delay a timer honors; anything larger fires immediately. */
+const MAX_TIMER_MS = 2_147_483_647
+
+const PROCESS_OPTIONS = ["killTimeoutMs", "restartDelayMs", "maxMemory"] as const
+const SCALABLE_PROCESS_OPTIONS = [...PROCESS_OPTIONS, "instances"] as const
+
+/**
+ * Checks a loaded `sixb.deploy.ts` default export and returns it typed. Validates shape and
+ * values only; `sixb deploy` resolves defaults and checks what depends on the target.
+ */
+export function validateDeployConfig(value: unknown): DeployConfig {
+  const config = record(value, "The deploy config")
+  knownKeys(config, ["name", "domain", "target", "env", "services", "processes"], "")
+
+  name(config.name, "name")
+  if (config.domain !== undefined) domain(config.domain, "domain")
+  target(config.target)
+  if (config.env !== undefined) env(config.env, "env")
+  if (config.services !== undefined) services(config.services)
+  if (config.processes !== undefined) processes(config.processes)
+
+  return value as DeployConfig
+}
+
+function target(value: unknown): void {
+  const hint = "Use a deploy target, such as `new SshTarget({ host })` from @sixb/deploy-ssh."
+  if (typeof value !== "object" || value === null) {
+    throw new Error(`[SixbDeploy] target is required. ${hint}`)
+  }
+  const candidate = value as UnknownRecord
+  const methods = ["listenAddress", "deploy", "status", "logs", "control", "check"]
+  if (
+    typeof candidate.kind !== "string" ||
+    typeof candidate.location !== "string" ||
+    methods.some((method) => typeof candidate[method] !== "function")
+  ) {
+    throw new Error(`[SixbDeploy] target is not a deploy target. ${hint}`)
+  }
+}
+
+function services(value: unknown): void {
+  const config = record(value, "services")
+  knownKeys(config, DEPLOY_SERVICES, "services")
+
+  for (const service of DEPLOY_SERVICES) {
+    const override = config[service]
+    if (override === undefined || typeof override === "boolean") continue
+    const path = `services.${service}`
+    const options = record(override, path)
+
+    if (isDeployHttpService(service)) {
+      knownKeys(options, ["domain", "env", "process"], path, {
+        port: "Ports belong to the target, such as `new SshTarget({ ports: { api: 3012 } })`.",
+      })
+      if (options.domain !== undefined) domain(options.domain, `${path}.domain`)
+      if (options.process !== undefined) {
+        processOptions(options.process, `${path}.process`, PROCESS_OPTIONS, {
+          instances: "HTTP services run one process each.",
+        })
+      }
+    } else if (isDeploySingletonService(service)) {
+      knownKeys(options, ["env", "process"], path)
+      if (options.process !== undefined) {
+        processOptions(options.process, `${path}.process`, PROCESS_OPTIONS, {
+          instances: `The ${service} runs exactly one process: a second would duplicate its work.`,
+        })
+      }
+    } else {
+      knownKeys(options, ["types", "agentTurnTimeout", "concurrency", "env", "process"], path)
+      if (options.types !== undefined) workerTypes(options.types, `${path}.types`)
+      if (options.agentTurnTimeout !== undefined) {
+        string(options.agentTurnTimeout, `${path}.agentTurnTimeout`)
+      }
+      if (options.concurrency !== undefined) {
+        workerConcurrency(options.concurrency, `${path}.concurrency`)
+      }
+      if (options.process !== undefined) {
+        processOptions(options.process, `${path}.process`, SCALABLE_PROCESS_OPTIONS)
+      }
+    }
+
+    if (options.env !== undefined) env(options.env, `${path}.env`)
+  }
+}
+
+function processes(value: unknown): void {
+  const config = record(value, "processes")
+
+  for (const [processName, definition] of Object.entries(config)) {
+    const path = `processes.${processName}`
+    name(processName, path)
+    if ((DEPLOY_SERVICES as readonly string[]).includes(processName)) {
+      throw new Error(`[SixbDeploy] ${path} uses the name of a Sixb service. Rename the process.`)
+    }
+
+    const options = record(definition, path)
+    knownKeys(options, ["entrypoint", "args", "env", "process"], path)
+    entrypoint(options.entrypoint, `${path}.entrypoint`)
+    if (options.args !== undefined) {
+      if (!Array.isArray(options.args) || options.args.some((arg) => typeof arg !== "string")) {
+        throw new Error(`[SixbDeploy] ${path}.args must be an array of strings.`)
+      }
+    }
+    if (options.env !== undefined) env(options.env, `${path}.env`)
+    if (options.process !== undefined) {
+      processOptions(options.process, `${path}.process`, SCALABLE_PROCESS_OPTIONS)
+    }
+  }
+}
+
+function workerTypes(value: unknown, path: string): void {
+  if (value === "all") return
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`[SixbDeploy] ${path} must be "all" or a non-empty list of worker types.`)
+  }
+  const seen = new Set<string>()
+  for (const workerType of value) {
+    if (!(DEPLOY_WORKER_TYPES as readonly unknown[]).includes(workerType)) {
+      throw new Error(
+        `[SixbDeploy] ${path} has unknown worker type ${JSON.stringify(workerType)}. ` +
+          `Available: ${DEPLOY_WORKER_TYPES.join(", ")}.`
+      )
+    }
+    if (seen.has(workerType)) {
+      throw new Error(`[SixbDeploy] ${path} lists ${workerType} more than once.`)
+    }
+    seen.add(workerType)
+  }
+}
+
+function workerConcurrency(value: unknown, path: string): void {
+  const config = record(value, path)
+  for (const [workerType, concurrency] of Object.entries(config)) {
+    if (workerType === "action") {
+      throw new Error(`[SixbDeploy] ${path}.action cannot be set: action jobs run one at a time.`)
+    }
+    if (!(DEPLOY_CONFIGURABLE_WORKER_TYPES as readonly string[]).includes(workerType)) {
+      throw new Error(
+        `[SixbDeploy] ${path} has unknown worker type "${workerType}". ` +
+          `Available: ${DEPLOY_CONFIGURABLE_WORKER_TYPES.join(", ")}.`
+      )
+    }
+    positiveInteger(concurrency, `${path}.${workerType}`)
+  }
+}
+
+function processOptions(
+  value: unknown,
+  path: string,
+  allowed: readonly string[],
+  hints: Readonly<Record<string, string>> = {}
+): void {
+  const options = record(value, path)
+  knownKeys(options, allowed, path, hints)
+  if (options.instances !== undefined) positiveInteger(options.instances, `${path}.instances`)
+  if (options.killTimeoutMs !== undefined) {
+    positiveInteger(options.killTimeoutMs, `${path}.killTimeoutMs`, MAX_TIMER_MS)
+  }
+  if (options.restartDelayMs !== undefined) {
+    positiveInteger(options.restartDelayMs, `${path}.restartDelayMs`, MAX_TIMER_MS)
+  }
+  if (options.maxMemory !== undefined) {
+    if (typeof options.maxMemory !== "string" || !MEMORY_PATTERN.test(options.maxMemory.trim())) {
+      throw new Error(`[SixbDeploy] ${path}.maxMemory must be a size such as "512M" or "2G".`)
+    }
+  }
+}
+
+function entrypoint(value: unknown, path: string): void {
+  string(value, path)
+  const segments = value.split(/[\\/]/)
+  if (value.startsWith("/") || segments.includes("..")) {
+    throw new Error(
+      `[SixbDeploy] ${path} must be a path inside the project, relative to its directory.`
+    )
+  }
+}
+
+function env(value: unknown, path: string): void {
+  const variables = record(value, path)
+  for (const [key, variable] of Object.entries(variables)) {
+    if (!ENV_NAME_PATTERN.test(key)) {
+      throw new Error(
+        `[SixbDeploy] ${path}.${key} is not a valid environment variable name. ` +
+          "Use uppercase letters, digits, and underscores."
+      )
+    }
+    if (typeof variable !== "string") {
+      throw new Error(`[SixbDeploy] ${path}.${key} must be a string.`)
+    }
+  }
+}
+
+function name(value: unknown, path: string): void {
+  string(value, path)
+  if (!NAME_PATTERN.test(value) || value.length > 63) {
+    throw new Error(
+      `[SixbDeploy] ${path} must use lowercase letters, numbers, and hyphens, ` +
+        "start and end with a letter or number, and be at most 63 characters."
+    )
+  }
+}
+
+function domain(value: unknown, path: string): void {
+  string(value, path)
+  if (value.includes("://") || value.includes("/")) {
+    throw new Error(`[SixbDeploy] ${path} must be a hostname such as app.example.com, not a URL.`)
+  }
+  if (value.length > 253 || !DOMAIN_PATTERN.test(value)) {
+    throw new Error(`[SixbDeploy] ${path} must be a valid hostname such as app.example.com.`)
+  }
+}
+
+function positiveInteger(value: unknown, path: string, maximum = Number.MAX_SAFE_INTEGER): void {
+  if (!Number.isInteger(value) || (value as number) < 1 || (value as number) > maximum) {
+    throw new Error(`[SixbDeploy] ${path} must be a positive integer.`)
+  }
+}
+
+function string(value: unknown, path: string): asserts value is string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`[SixbDeploy] ${path} must be a non-empty string.`)
+  }
+}
+
+function record(value: unknown, path: string): UnknownRecord {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`[SixbDeploy] ${path} must be an object.`)
+  }
+  return value as UnknownRecord
+}
+
+function knownKeys(
+  value: UnknownRecord,
+  allowed: readonly string[],
+  path: string,
+  hints: Readonly<Record<string, string>> = {}
+): void {
+  for (const key of Object.keys(value)) {
+    if (allowed.includes(key)) continue
+    const setting = path ? `${path}.${key}` : key
+    const hint = hints[key] ?? `Available: ${allowed.join(", ")}.`
+    throw new Error(`[SixbDeploy] Unknown deploy setting '${setting}'. ${hint}`)
+  }
+}

package/src/errors/catalog.ts

@@ -146,6 +146,10 @@ export const SIXB_ERROR_DEFINITIONS = {
     publicMessage: "The embedding call was interrupted; its outcome and charges may be unknown.",
     retryable: false,
   },
+  "storage.unavailable": {
+    publicMessage: "Storage is temporarily unavailable.",
+    retryable: true,
+  },
   "sync.execution_failed": {
     publicMessage: "Sync execution failed.",
     retryable: false,

package/src/maintenance/ontology-maintenance.ts

@@ -24,6 +24,9 @@ const DEGRADED_FAILURE_THRESHOLD = 2
 // run ahead of the database's; the sweep leaves sessions alone until this long past expiry.
 const ABANDONED_UPLOAD_SWEEP_DELAY_MS = 5 * 60_000
 const ABANDONED_UPLOAD_ABORT_GRACE_MS = 15 * 60_000
+// One abandoned candidate of a large projection holds hundreds of thousands of rows. Batches this
+// size keep each delete short while clearing such a candidate within a pass.
+const ABANDONED_SOURCE_PURGE_BATCH = 50_000
 
 interface OntologyMaintenanceDependencies {
   readonly projectId: string
@@ -188,6 +191,11 @@ export class OntologyMaintenance {
       failures,
       { rowsDeleted: 0, materializationsDeleted: 0 }
     )
+    const abandonedSources = await captureFailure(
+      () => this.purgeAbandonedSources(started),
+      failures,
+      { rowsDeleted: 0, materializationsDeleted: 0 }
+    )
     const uploads = this.storage.fileUploadSessions
     if (uploads) {
       // Retire abandoned uploads first: the store never reaps one that is still pending.
@@ -197,8 +205,30 @@ export class OntologyMaintenance {
 
     return {
       publishedOutboxRowsDeleted,
-      terminalSourceRowsDeleted: terminalSources.rowsDeleted,
-      terminalSourceMaterializationsDeleted: terminalSources.materializationsDeleted,
+      terminalSourceRowsDeleted: terminalSources.rowsDeleted + abandonedSources.rowsDeleted,
+      terminalSourceMaterializationsDeleted:
+        terminalSources.materializationsDeleted + abandonedSources.materializationsDeleted,
+    }
+  }
+
+  /** Deletes abandoned candidates batch after batch, until none is left or the pass runs long. */
+  private async purgeAbandonedSources(
+    started: Date
+  ): Promise<{ readonly rowsDeleted: number; readonly materializationsDeleted: number }> {
+    let rowsDeleted = 0
+    let materializationsDeleted = 0
+    while (true) {
+      const purged = await this.storage.ontology.sources.purgeAbandoned({
+        projectId: this.projectId,
+        limit: ABANDONED_SOURCE_PURGE_BATCH,
+      })
+      rowsDeleted += purged.rowsDeleted
+      materializationsDeleted += purged.materializationsDeleted
+      const exhausted =
+        purged.rowsDeleted + purged.materializationsDeleted < ABANDONED_SOURCE_PURGE_BATCH
+      if (exhausted || this.now().getTime() - started.getTime() >= this.intervalMs) {
+        return { rowsDeleted, materializationsDeleted }
+      }
     }
   }
 

package/src/maintenance/types.ts

@@ -3,9 +3,15 @@ export interface OntologyMaintenanceOptions {
   readonly intervalMs?: number
   /** Published outbox retention. Defaults to 24 hours. */
   readonly publishedOutboxRetentionMs?: number
-  /** Superseded/abandoned source retention. Defaults to 24 hours. */
+  /**
+   * Retention of superseded source versions. Defaults to 24 hours. Abandoned candidates have none:
+   * nothing reads them, so the next pass deletes them whole.
+   */
   readonly terminalSourceRetentionMs?: number
-  /** Maximum deletions attempted per cleanup domain and pass. Defaults to 1,000. */
+  /**
+   * Maximum deletions attempted per cleanup domain and pass. Defaults to 1,000. Abandoned
+   * candidates are deleted in larger batches until none is left or the pass reaches `intervalMs`.
+   */
   readonly cleanupLimit?: number
   /** Warn after this shutdown grace period, then wait for active operations. Defaults to 30 seconds. */
   readonly shutdownTimeoutMs?: number