@rizom/ops 0.2.0-alpha.346 → 0.2.0-alpha.348

package/dist/legacy-projection-job-recovery.d.ts

@@ -0,0 +1,29 @@
+import { type JobInfo } from "@brains/job-queue";
+import { z } from "@brains/utils/zod";
+export declare const LEGACY_PROJECTION_JOB_TYPES: readonly ["conversation-memory:project", "skill:project", "swot:derive", "topic:project"];
+export declare const legacyProjectionJobTypeSchema: z.ZodEnum<{
+    "conversation-memory:project": "conversation-memory:project";
+    "skill:project": "skill:project";
+    "swot:derive": "swot:derive";
+    "topic:project": "topic:project";
+}>;
+export type LegacyProjectionJobType = z.output<typeof legacyProjectionJobTypeSchema>;
+export declare const LEGACY_PROJECTION_RETIREMENT_REASON = "Retired legacy projection job superseded by scheduler-owned projections";
+export interface RetireLegacyProjectionJobOptions {
+    databasePath: string;
+    jobId: string;
+    jobType: LegacyProjectionJobType;
+    confirmation?: string | undefined;
+    dryRun?: boolean | undefined;
+    now?: (() => number) | undefined;
+}
+export interface RetireLegacyProjectionJobResult {
+    databasePath: string;
+    job: Pick<JobInfo, "id" | "type" | "status" | "retryCount" | "maxRetries" | "createdAt" | "startedAt" | "completedAt">;
+    retired: boolean;
+}
+/**
+ * Retire one exact pre-scheduler projection job after proving that no attempt
+ * owns it. This is deliberately not a general job cancellation API.
+ */
+export declare function retireLegacyProjectionJob(options: RetireLegacyProjectionJobOptions): Promise<RetireLegacyProjectionJobResult>;

package/dist/run-command.d.ts

@@ -7,6 +7,7 @@ import { type SshKeygen } from "./ssh-key-bootstrap";
 import type { UserRunner } from "./user-runner";
 import type { cleanupDirectorySyncStress, runDeployedDirectorySyncStress, verifyDirectorySyncStressAccess } from "./directory-sync-stress-system";
 import type { cleanupHealthWatchdogSmoke, runHealthWatchdogSmoke } from "./health-watchdog-smoke";
+import type { retireLegacyProjectionJob } from "./legacy-projection-job-recovery";
 export interface CommandResult {
     success: boolean;
     message?: string;
@@ -27,6 +28,7 @@ export interface CommandDependencies extends LoadPilotRegistryOptions {
     directorySyncStressCleanupRunner?: typeof cleanupDirectorySyncStress | undefined;
     healthWatchdogSmokeRunner?: typeof runHealthWatchdogSmoke | undefined;
     healthWatchdogSmokeCleanupRunner?: typeof cleanupHealthWatchdogSmoke | undefined;
+    legacyProjectionJobRecoveryRunner?: typeof retireLegacyProjectionJob | undefined;
 }
 export declare const globalFlags: FlagDefinitions;
 export declare const commands: readonly CommandDefinition<CommandDependencies, CommandResult>[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rizom/ops",
-  "version": "0.2.0-alpha.346",
+  "version": "0.2.0-alpha.348",
   "description": "Operator CLI for managing private brain fleet registry repos",
   "keywords": [
     "brains",
@@ -17,12 +17,14 @@
   },
   "bugs": "https://github.com/rizom-ai/brains/issues",
   "dependencies": {
+    "@libsql/client": "^0.17.4",
     "age-encryption": "^0.3.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@brains/deploy-support": "workspace:*",
     "@brains/eslint-config": "workspace:*",
+    "@brains/job-queue": "workspace:*",
     "@brains/profile": "workspace:*",
     "@brains/site-composition": "workspace:*",
     "@brains/test-utils": "workspace:*",

package/templates/rover-pilot/docs/operator-playbook.md

@@ -56,6 +56,27 @@ Files use mode `0600` and the directory uses `0700`. A `.incomplete` directory i
 
 These are same-server rollback snapshots, not off-host disaster recovery. There is no normal skip and no automatic restore. Restoration requires separate approval: stop replacement/application processes, recheck the selected snapshot's checksums, preserve the current state, restore databases and exact Git state, then validate health, queues, Git checkpoints, durable export intents, preview, and production output before reopening the target.
 
+## Retired projection job recovery
+
+A pre-scheduler projection job can remain active after its handler type is retired. Current runtime health reports active job types missing from the finalized execution inventory as degraded. Do not restart repeatedly or relax the snapshot idle gate.
+
+Use the recovery command only after read-only evidence proves all of the following for one exact row:
+
+- its type is one of the command's fixed legacy projection types;
+- the installed runtime no longer contains that handler;
+- attempt, worker-session, lease, and heartbeat ownership are all absent;
+- no durable progress snapshot or result exists.
+
+Preview the exact row first:
+
+```sh
+bunx --package @rizom/ops@<exact-version> brains-ops \
+  recover:retire-legacy-projection-job \
+  /data/brain-jobs.db <job-id> --type <legacy-type> --dry-run
+```
+
+After separate operator review, replace `--dry-run` with the exact confirmation `--confirm retire:<job-id>`. The command atomically fences against ownership or progress appearing between inspection and retirement, and fails closed if the row changed. It is not a general job cancellation API and cannot retire arbitrary job types. Require operational health and a fully idle queue afterward, then run the unchanged canonical predeploy snapshot and Deploy workflow.
+
 ## Canonical contract crossover maintenance window
 
 Do not run this procedure without explicit operator approval. The canonical desired state, canonical `@rizom/ops`, and unified runtime image form one contract and must move or roll back together. Complete `docs/canonical-crossover-record.md` as the approval evidence without adding secret values.