dirpush 0.0.0 → 0.1.0

package/src/db/index.ts

@@ -0,0 +1,29 @@
+import { Database } from "bun:sqlite";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { migrate } from "drizzle-orm/bun-sqlite/migrator";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import * as schema from "./schema";
+
+/** Where the package lives: registry, migrations, examples, scripts and the skill. Read-only once installed. */
+export const PKG = join(import.meta.dir, "../..");
+/**
+ * Where your launch lives: data/ (database, Chrome profile, evidence) and workspace/ (products, identity).
+ * A git checkout keeps it in the repo, as before; an installed package uses ~/.dirpush. LAUNCH_HOME overrides both.
+ */
+export const HOME = process.env.LAUNCH_HOME ?? (existsSync(join(PKG, ".git")) ? PKG : join(homedir(), ".dirpush"));
+
+export function openDb(path = process.env.LAUNCH_DB ?? join(HOME, "data/launch.db")) {
+  if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+  const sqlite = new Database(path, { create: true, strict: true });
+  sqlite.run("PRAGMA journal_mode = WAL");
+  sqlite.run("PRAGMA busy_timeout = 5000");
+  sqlite.run("PRAGMA foreign_keys = ON");
+  const db = drizzle(sqlite, { schema });
+  migrate(db, { migrationsFolder: join(PKG, "drizzle") });
+  return db;
+}
+
+export type Db = ReturnType<typeof openDb>;
+export { schema };

package/src/db/schema.ts

@@ -0,0 +1,152 @@
+import { sql } from "drizzle-orm";
+import { integer, primaryKey, real, sqliteTable, text, uniqueIndex, index } from "drizzle-orm/sqlite-core";
+
+const now = sql`(unixepoch() * 1000)`;
+const json = <T>(name: string) => text(name, { mode: "json" }).$type<T>();
+
+export const CLASSIFICATIONS = [
+  "UNVERIFIED",
+  "VERIFIED_FREE",
+  "FREEMIUM",
+  "CONDITIONAL_FREE",
+  "PAID",
+  "DEAD",
+  "NOT_RELEVANT",
+] as const;
+export type Classification = (typeof CLASSIFICATIONS)[number];
+
+export type Provenance = { source: string; name?: string; url: string; claims?: Record<string, unknown> };
+
+/** Unverified research queue. Only verified entries become registry/directories/*.yaml. */
+export const candidates = sqliteTable("candidates", {
+  domain: text("domain").primaryKey(),
+  name: text("name"),
+  url: text("url").notNull(),
+  classification: text("classification").$type<Classification>().notNull().default("UNVERIFIED"),
+  provenance: json<Provenance[]>("provenance").notNull().default([]),
+  notes: text("notes"),
+  createdAt: integer("created_at").notNull().default(now),
+  updatedAt: integer("updated_at").notNull().default(now),
+});
+
+export const JOB_STATUSES = ["queued", "running", "blocked", "retry", "unknown", "failed", "done"] as const;
+export type JobStatus = (typeof JOB_STATUSES)[number];
+export type JobKind = "research" | "submission";
+
+/**
+ * One row per canonical unit of work: a research job per candidate domain, a
+ * submission job per (product, directory). `status` is coarse and enforced;
+ * `step` is the agent's free-form checkpoint inside a running job.
+ */
+export const jobs = sqliteTable(
+  "jobs",
+  {
+    id: text("id").primaryKey(),
+    kind: text("kind").$type<JobKind>().notNull(),
+    subject: text("subject").notNull(), // candidate domain or directory id
+    productId: text("product_id").notNull().default(""),
+    status: text("status").$type<JobStatus>().notNull().default("queued"),
+    step: text("step").notNull().default("queued"),
+    worker: text("worker"),
+    leaseExpiresAt: integer("lease_expires_at"),
+    notBefore: integer("not_before"),
+    attempts: integer("attempts").notNull().default(0),
+    blockType: text("block_type"),
+    blockMessage: text("block_message"),
+    lastError: text("last_error"),
+    outcome: text("outcome"), // research: classification; submission: submitted|pending|live|rejected
+    listingUrl: text("listing_url"),
+    data: json<Record<string, unknown>>("data").notNull().default({}),
+    createdAt: integer("created_at").notNull().default(now),
+    updatedAt: integer("updated_at").notNull().default(now),
+  },
+  (t) => [uniqueIndex("jobs_unique_subject").on(t.kind, t.productId, t.subject), index("jobs_status").on(t.status)],
+);
+
+export const events = sqliteTable(
+  "events",
+  {
+    id: integer("id").primaryKey({ autoIncrement: true }),
+    jobId: text("job_id"),
+    type: text("type").notNull(),
+    worker: text("worker"),
+    data: json<Record<string, unknown>>("data").notNull().default({}),
+    at: integer("at").notNull().default(now),
+  },
+  (t) => [index("events_job").on(t.jobId)],
+);
+
+export type GalleryItem = { id: string; path: string; description: string };
+
+export const galleries = sqliteTable("galleries", {
+  revision: integer("revision").primaryKey({ autoIncrement: true }),
+  productId: text("product_id").notNull(),
+  items: json<GalleryItem[]>("items").notNull(),
+  status: text("status").$type<"proposed" | "approved" | "rejected">().notNull().default("proposed"),
+  createdAt: integer("created_at").notNull().default(now),
+});
+
+/** Product-wide approvals (such as permission-gated asset capture), independent of directory jobs. */
+export const productApprovals = sqliteTable("product_approvals", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  productId: text("product_id").notNull(),
+  action: text("action").notNull(),
+  message: text("message").notNull(),
+  status: text("status").$type<"pending" | "approved" | "rejected" | "used">().notNull().default("pending"),
+  createdAt: integer("created_at").notNull().default(now),
+  resolvedAt: integer("resolved_at"),
+});
+
+export const registryChanges = sqliteTable("registry_changes", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  directoryId: text("directory_id").notNull(),
+  observation: json<Record<string, unknown>>("observation").notNull(),
+  status: text("status").$type<"proposed" | "accepted" | "rejected">().notNull().default("proposed"),
+  createdAt: integer("created_at").notNull().default(now),
+});
+
+/** Things only the human can do that don't hold up a job (verify an email, check a listing). */
+export const todos = sqliteTable("todos", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  productId: text("product_id").notNull().default(""),
+  jobId: text("job_id"),
+  message: text("message").notNull(),
+  url: text("url"),
+  status: text("status").$type<"open" | "done">().notNull().default("open"),
+  createdAt: integer("created_at").notNull().default(now),
+});
+
+/**
+ * One row per directory account (per product unless shared). Written whenever a job checkpoints an `account`, so
+ * "do we already have a login here, and how do we sign in?" has one answer. Never holds a secret: passwords stay in
+ * the agent-browser vault, referenced by `vault`.
+ */
+export const ACCOUNT_METHODS = ["password", "google", "github", "magic_link", "other"] as const;
+export const accounts = sqliteTable(
+  "accounts",
+  {
+    directoryId: text("directory_id").notNull(),
+    productId: text("product_id").notNull().default(""), // "" = one account shared by every product
+    method: text("method", { enum: ACCOUNT_METHODS }).notNull(),
+    username: text("username"),
+    vault: text("vault"),
+    jobId: text("job_id"),
+    createdAt: integer("created_at").notNull().default(now),
+    lastLoginAt: integer("last_login_at"),
+  },
+  (t) => [primaryKey({ columns: [t.directoryId, t.productId] })],
+);
+export type Account = typeof accounts.$inferSelect;
+
+/** Append-only Ahrefs Domain Rating readings (optional, needs AHREFS_API_KEY). Latest = highest measuredAt. */
+export const domainRatings = sqliteTable(
+  "domain_ratings",
+  {
+    domain: text("domain").notNull(),
+    measuredAt: integer("measured_at").notNull(),
+    rating: real("rating").notNull(),
+  },
+  (t) => [primaryKey({ columns: [t.domain, t.measuredAt] })],
+);
+
+export type Job = typeof jobs.$inferSelect;

package/src/directory-kinds.ts

@@ -0,0 +1,12 @@
+export const DIRECTORY_KINDS = {
+  listing: "Software directory",
+  launch_board: "Launch site",
+  mcp_registry: "MCP registry",
+  github_list: "GitHub list",
+  plugin_marketplace: "Plugin marketplace",
+  api_catalog: "API catalog",
+  llms_directory: "llms.txt directory",
+  campaign: "Campaign",
+  lead_gen: "Lead generation",
+  marketplace: "Marketplace",
+} as const;

package/src/import-hosted.ts

@@ -0,0 +1,156 @@
+import { and, eq, gt, inArray, like } from "drizzle-orm";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Db } from "./db";
+import { events, jobs, type Job } from "./db/schema";
+import * as J from "./jobs";
+import { recordRating } from "./ratings";
+
+/**
+ * One-off import of the retired dirpush.com app's D1 export (see `launch import hosted`).
+ * The hosted app ran the same launch through MCP from Oct 11–14, so its rows are often newer than ours.
+ */
+
+/** A tracked_targets row as exported by `wrangler d1 execute --json`. */
+export type HostedTarget = {
+  product_id: string; directory_id: string; state: string; detail: string | null; listing_url: string | null; updated_at: number;
+  job_id: string | null; block_type: string | null; fields: string | null; badge: number; decision: string | null;
+  answer: string | null; reason: string | null; action: string | null; diagnostics: string | null; account_hint: string | null;
+};
+export type HostedEvent = { id: number; product_id: string; directory_id: string; at: number; kind: string; data: string | null };
+export type HostedRating = { domain: string; measured_at: number; rating: number };
+
+const parse = (s: string | null) => {
+  if (s == null) return undefined;
+  try {
+    return JSON.parse(s) as unknown;
+  } catch {
+    return s;
+  }
+};
+
+/** The local job fields a hosted state stands for; null = a hosted-only recommendation that was never queued. */
+export function jobPatch(t: HostedTarget): Partial<Job> | null {
+  const clear = { worker: null, leaseExpiresAt: null, notBefore: null, blockType: null, blockMessage: null, lastError: null };
+  switch (t.state) {
+    case "live":
+    case "pending":
+    case "needs_badge":
+    case "rejected":
+      return { ...clear, status: "done", step: "submitted", outcome: t.state, ...(t.listing_url && { listingUrl: t.listing_url }) };
+    case "blocked":
+      return { ...clear, status: "blocked", blockType: t.block_type ?? "manual", blockMessage: t.detail ?? "blocked on the hosted dashboard" };
+    case "paused":
+      return { ...clear, status: "blocked", blockType: "hold", blockMessage: t.detail ?? "paused on the hosted dashboard" };
+    case "failed":
+      return { ...clear, status: "failed", lastError: [t.reason, t.detail].filter(Boolean).join(": ") || "failed on the hosted dashboard" };
+    case "todo":
+      if (t.badge && t.decision === "declined") return { ...clear, status: "failed", lastError: "badge: free only with a badge, declined" };
+      // The old sync pushed unqueued recommendations as "recommended, not queued"; anything else was worked on hosted.
+      return t.job_id || (t.detail && t.detail !== "recommended, not queued") ? { ...clear, status: "queued", step: "queued" } : null;
+    case "in_progress":
+      return { ...clear, status: "queued", step: "queued" };
+    default:
+      return null;
+  }
+}
+
+/** Hosted-only context the dashboard recorded (customer replies, required fields, agent diagnostics). */
+function hostedData(t: HostedTarget) {
+  const entries = Object.entries({
+    action: parse(t.action), fields: parse(t.fields), answer: parse(t.answer), diagnostics: parse(t.diagnostics),
+    reason: t.reason, decision: t.decision, accountHint: t.account_hint,
+  }).filter(([, v]) => v != null);
+  return entries.length ? { hosted: Object.fromEntries(entries) } : {};
+}
+
+export function importHosted(
+  db: Db,
+  input: { targets: HostedTarget[]; events: HostedEvent[]; ratings: HostedRating[] },
+  products: string[],
+) {
+  const summary = { applied: 0, created: 0, keptLocal: 0, recommendationsSkipped: 0, events: 0, ratings: 0, skippedProducts: new Set<string>() };
+  const known = new Set(products);
+  const jobFor = new Map<string, string>(); // product/directory -> local job id, for events
+
+  for (const t of input.targets) {
+    if (!known.has(t.product_id)) {
+      summary.skippedProducts.add(t.product_id);
+      continue;
+    }
+    const local =
+      (t.job_id && db.select().from(jobs).where(eq(jobs.id, t.job_id)).get()) ||
+      db.select().from(jobs).where(and(eq(jobs.kind, "submission"), eq(jobs.productId, t.product_id), eq(jobs.subject, t.directory_id))).get();
+    if (local) jobFor.set(`${t.product_id}/${t.directory_id}`, local.id);
+    const patch = jobPatch(t);
+    if (!patch) {
+      summary.recommendationsSkipped++;
+      continue;
+    }
+    if (local && local.updatedAt >= t.updated_at) {
+      summary.keptLocal++;
+      continue;
+    }
+    const job = local ?? J.enqueue(db, "submission", t.directory_id, t.product_id, t.updated_at);
+    if (!local) summary.created++;
+    jobFor.set(`${t.product_id}/${t.directory_id}`, job.id);
+    db.transaction((tx) => {
+      tx.update(jobs).set({ ...patch, data: { ...job.data, ...hostedData(t) }, updatedAt: t.updated_at }).where(eq(jobs.id, job.id)).run();
+      tx.insert(events).values({ jobId: job.id, type: "hosted_import", worker: "hosted", data: { from: { status: job.status, outcome: job.outcome }, to: t.state }, at: Date.now() }).run();
+    });
+    summary.applied++;
+  }
+
+  // Events are append-only history; the hosted id makes re-running the import a no-op.
+  const seen = new Set(
+    db.select({ data: events.data }).from(events).where(like(events.type, "hosted.%")).all().map((e) => (e.data as { hostedEventId?: number }).hostedEventId),
+  );
+  for (const e of input.events) {
+    if (!known.has(e.product_id) || seen.has(e.id)) continue;
+    const data = parse(e.data);
+    db.insert(events).values({
+      jobId: jobFor.get(`${e.product_id}/${e.directory_id}`) ?? null,
+      type: `hosted.${e.kind}`,
+      worker: "hosted",
+      data: { hostedEventId: e.id, directoryId: e.directory_id, ...(data && typeof data === "object" ? data : { value: data }) },
+      at: e.at,
+    }).run();
+    summary.events++;
+  }
+
+  // The import's own events would otherwise sort as "today" in a job's timeline: date them to the hosted history.
+  const firstHosted = new Map<string, number>();
+  for (const e of input.events) {
+    const k = `${e.product_id}/${e.directory_id}`;
+    firstHosted.set(k, Math.min(firstHosted.get(k) ?? e.at, e.at));
+  }
+  for (const t of input.targets) {
+    const jobId = jobFor.get(`${t.product_id}/${t.directory_id}`);
+    if (!jobId) continue;
+    const first = Math.min(firstHosted.get(`${t.product_id}/${t.directory_id}`) ?? t.updated_at, t.updated_at);
+    db.update(events).set({ at: t.updated_at }).where(and(eq(events.jobId, jobId), eq(events.type, "hosted_import"))).run();
+    db.update(events).set({ at: first - 1 }).where(and(eq(events.jobId, jobId), inArray(events.type, ["job_created"]), gt(events.at, t.updated_at))).run();
+  }
+
+  for (const r of input.ratings) {
+    recordRating(db, r.domain, r.rating, r.measured_at);
+    summary.ratings++;
+  }
+  return { ...summary, skippedProducts: [...summary.skippedProducts] };
+}
+
+/** Reads the `wrangler d1 execute --json` files written to `dir` (one per table). */
+export async function readHostedExport(dir: string) {
+  const table = async <T>(name: string): Promise<T[]> => {
+    const file = join(dir, `${name}.json`);
+    if (!existsSync(file)) throw new Error(`missing ${file}; export it first (see 'dirpush import hosted' in docs/operator.md)`);
+    const parsed = JSON.parse(await Bun.file(file).text()) as { results?: T[]; error?: unknown }[] | { error: unknown };
+    if (!Array.isArray(parsed) || !parsed[0]?.results) throw new Error(`${file} is not a successful wrangler --json export`);
+    return parsed[0].results;
+  };
+  return {
+    targets: await table<HostedTarget>("tracked_targets"),
+    events: await table<HostedEvent>("target_events"),
+    ratings: await table<HostedRating>("domain_rating_history"),
+  };
+}

package/src/jobs.ts

@@ -0,0 +1,270 @@
+import { and, asc, eq, inArray, isNull, lte, or } from "drizzle-orm";
+import type { Db } from "./db";
+import { events, jobs, type Job, type JobKind } from "./db/schema";
+import { recordAccount } from "./accounts";
+
+export const LEASE_MS = 15 * 60_000;
+export const MAX_ATTEMPTS = 5;
+/** The one step with an external side effect we cannot see from here. */
+export const SUBMITTING = "submitting";
+
+export class JobError extends Error {}
+
+type Tx = Parameters<Parameters<Db["transaction"]>[0]>[0];
+
+function logEvent(tx: Tx | Db, jobId: string | null, type: string, worker: string | null, data: Record<string, unknown> = {}) {
+  tx.insert(events).values({ jobId, type, worker, data }).run();
+}
+
+function get(tx: Tx, id: string): Job {
+  const job = tx.select().from(jobs).where(eq(jobs.id, id)).get();
+  if (!job) throw new JobError(`no such job: ${id}`);
+  return job;
+}
+
+function set(tx: Tx, id: string, patch: Partial<Job>, now: number) {
+  return tx.update(jobs).set({ ...patch, updatedAt: now }).where(eq(jobs.id, id)).returning().get()!;
+}
+
+function owned(job: Job, worker: string, now: number, statuses: Job["status"][] = ["running"]) {
+  if (!statuses.includes(job.status)) throw new JobError(`job ${job.id} is ${job.status}, expected ${statuses.join("|")}`);
+  if (job.worker !== worker) throw new JobError(`job ${job.id} is leased to ${job.worker}, not ${worker}`);
+  if ((job.leaseExpiresAt ?? 0) < now) throw new JobError(`lease on ${job.id} expired; claim it again`);
+}
+
+/** Leaving a job mid-submit means we no longer know whether the directory got it. */
+const released = (job: Job) => (job.step === SUBMITTING ? ("unknown" as const) : null);
+
+const tx = <T>(db: Db, fn: (tx: Tx) => T) => db.transaction(fn, { behavior: "immediate" });
+
+export function enqueue(db: Db, kind: JobKind, subject: string, productId = "", now = Date.now()): Job {
+  return tx(db, (t) => {
+    const existing = t
+      .select()
+      .from(jobs)
+      .where(and(eq(jobs.kind, kind), eq(jobs.subject, subject), eq(jobs.productId, productId)))
+      .get();
+    if (existing) return existing;
+    const id = `${kind === "research" ? "r" : "s"}_${crypto.randomUUID().slice(0, 8)}`;
+    const job = t.insert(jobs).values({ id, kind, subject, productId, createdAt: now, updatedAt: now }).returning().get();
+    logEvent(t, id, "job_created", null, { kind, subject, productId });
+    return job;
+  });
+}
+
+function claimableWhere(now: number, kind?: JobKind) {
+  const expired = or(isNull(jobs.leaseExpiresAt), lte(jobs.leaseExpiresAt, now));
+  const ready = or(
+    eq(jobs.status, "queued"),
+    and(eq(jobs.status, "retry"), or(isNull(jobs.notBefore), lte(jobs.notBefore, now))),
+    and(inArray(jobs.status, ["running", "unknown"]), expired),
+  );
+  return kind ? and(eq(jobs.kind, kind), ready) : ready;
+}
+
+/** Unknown first (they block retries), then oldest. */
+export function next(db: Db, kind?: JobKind, now = Date.now()): Job | undefined {
+  const rows = db.select().from(jobs).where(claimableWhere(now, kind)).orderBy(asc(jobs.createdAt)).all();
+  return rows.find((j) => j.status === "unknown") ?? rows[0];
+}
+
+export function claim(db: Db, id: string, worker: string, now = Date.now()): Job {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    const ok = t.select({ id: jobs.id }).from(jobs).where(and(eq(jobs.id, id), claimableWhere(now))).get();
+    if (!ok) throw new JobError(`job ${id} is not claimable (${job.status}, worker ${job.worker ?? "-"})`);
+    let status = job.status;
+    if (status === "running") {
+      logEvent(t, id, "lease_expired", job.worker, { step: job.step });
+      if (job.step === SUBMITTING) {
+        status = "unknown";
+        logEvent(t, id, "submission_state_unknown", job.worker, { reason: "lease expired during submit" });
+      }
+    }
+    const fresh = status === "queued" || status === "retry";
+    const updated = set(
+      t,
+      id,
+      {
+        status: status === "unknown" ? "unknown" : "running",
+        worker,
+        leaseExpiresAt: now + LEASE_MS,
+        attempts: fresh ? job.attempts + 1 : job.attempts,
+        notBefore: null,
+      },
+      now,
+    );
+    logEvent(t, id, "claimed", worker, { status: updated.status, step: updated.step, attempt: updated.attempts });
+    return updated;
+  });
+}
+
+export function heartbeat(db: Db, id: string, worker: string, now = Date.now()) {
+  return tx(db, (t) => {
+    owned(get(t, id), worker, now, ["running", "unknown"]);
+    return set(t, id, { leaseExpiresAt: now + LEASE_MS }, now);
+  });
+}
+
+export function checkpoint(db: Db, id: string, worker: string, step: string, data: Record<string, unknown> = {}, now = Date.now()) {
+  if (step === SUBMITTING) throw new JobError(`use 'work begin-submit' to enter ${SUBMITTING}`);
+  return tx(db, (t) => {
+    const job = get(t, id);
+    owned(job, worker, now);
+    if (job.step === SUBMITTING) throw new JobError(`job ${id} is mid-submit; record 'work submitted' or fail it`);
+    logEvent(t, id, "checkpoint", worker, { step, ...data });
+    recordAccount(t, job, data, now); // a checkpoint carrying {"account":…} keeps the accounts table current
+    return set(t, id, { step, data: { ...job.data, ...data }, leaseExpiresAt: now + LEASE_MS }, now);
+  });
+}
+
+/** Call immediately before clicking the directory's final submit button. */
+export function beginSubmit(db: Db, id: string, worker: string, now = Date.now()) {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    owned(job, worker, now);
+    if (job.kind !== "submission") throw new JobError(`job ${id} is not a submission`);
+    logEvent(t, id, "submit_attempted", worker);
+    return set(t, id, { step: SUBMITTING, leaseExpiresAt: now + LEASE_MS }, now);
+  });
+}
+
+export type Outcome = "submitted" | "pending" | "live" | "rejected" | "needs_badge"; // needs_badge: accepted but only goes/stays live with their badge on our site (we never add one)
+
+/** Record that the directory has the listing. Valid mid-submit or while verifying an unknown job. */
+export function recordSubmitted(db: Db, id: string, worker: string, outcome: Outcome = "submitted", listingUrl?: string, now = Date.now()) {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    owned(job, worker, now, ["running", "unknown"]);
+    if (job.status === "running" && job.step !== SUBMITTING) throw new JobError(`job ${id} never began submitting`);
+    logEvent(t, id, "submission_recorded", worker, { outcome, listingUrl });
+    return set(t, id, { status: "done", step: "submitted", outcome, listingUrl: listingUrl ?? job.listingUrl, worker: null, leaseExpiresAt: null }, now);
+  });
+}
+
+/** Verification of an unknown job found no listing: safe to submit again. */
+export function recordNotSubmitted(db: Db, id: string, worker: string, evidence: string, now = Date.now()) {
+  return tx(db, (t) => {
+    owned(get(t, id), worker, now, ["unknown"]);
+    logEvent(t, id, "verified_not_submitted", worker, { evidence });
+    return set(t, id, { status: "running", step: "verified_not_submitted", leaseExpiresAt: now + LEASE_MS }, now);
+  });
+}
+
+export function complete(db: Db, id: string, worker: string, outcome: string, data: Record<string, unknown> = {}, now = Date.now()) {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    owned(job, worker, now);
+    if (job.step === SUBMITTING) throw new JobError(`job ${id} is mid-submit; use 'work submitted'`);
+    logEvent(t, id, "completed", worker, { outcome });
+    return set(t, id, { status: "done", step: "done", outcome, data: { ...job.data, ...data }, worker: null, leaseExpiresAt: null }, now);
+  });
+}
+
+export function block(db: Db, id: string, worker: string, type: string, message: string, now = Date.now()) {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    owned(job, worker, now, ["running", "unknown"]);
+    logEvent(t, id, "blocked", worker, { type, message, step: job.step });
+    return set(t, id, { status: "blocked", blockType: type, blockMessage: message, worker: null, leaseExpiresAt: null }, now);
+  });
+}
+
+/** Human resolved the block. `approved` = explicit go-ahead on a permission block (dashboard Approve only). */
+export function unblock(db: Db, id: string, note = "", now = Date.now(), approved = false) {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    if (job.status !== "blocked") throw new JobError(`job ${id} is ${job.status}, not blocked`);
+    logEvent(t, id, "unblocked", "human", { type: job.blockType, note, ...(approved && job.blockType === "permission" && { approved }) });
+    return set(t, id, { status: released(job) ?? "queued", blockType: null, blockMessage: null }, now);
+  });
+}
+
+export function fail(db: Db, id: string, worker: string, reason: string, retryable: boolean, now = Date.now()) {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    owned(job, worker, now, ["running", "unknown"]);
+    const base = { lastError: reason, worker: null, leaseExpiresAt: null };
+    if (released(job) || job.status === "unknown") {
+      logEvent(t, id, "submission_state_unknown", worker, { reason });
+      return set(t, id, { ...base, status: "unknown" }, now);
+    }
+    if (retryable && job.attempts < MAX_ATTEMPTS) {
+      const notBefore = now + 2 ** job.attempts * 60_000;
+      logEvent(t, id, "failed_retryable", worker, { reason, notBefore });
+      return set(t, id, { ...base, status: "retry", notBefore }, now);
+    }
+    logEvent(t, id, "failed", worker, { reason, retryable });
+    return set(t, id, { ...base, status: "failed" }, now);
+  });
+}
+
+/** Graceful stop: hand the job back without penalty. */
+export function release(db: Db, id: string, worker: string, now = Date.now()) {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    owned(job, worker, now, ["running", "unknown"]);
+    logEvent(t, id, "released", worker, { step: job.step });
+    const status = job.status === "unknown" ? "unknown" : (released(job) ?? "queued");
+    return set(t, id, { status, worker: null, leaseExpiresAt: null }, now);
+  });
+}
+
+/** Did the human press Approve on a permission block of this job? */
+export function approved(db: Db, id: string) {
+  return db.select().from(events).where(and(eq(events.jobId, id), eq(events.type, "unblocked"))).all().some((e) => e.data.approved === true);
+}
+
+/** Human: give a failed job another go. */
+export function requeue(db: Db, id: string, now = Date.now()) {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    if (job.status !== "failed") throw new JobError(`job ${id} is ${job.status}, not failed`);
+    logEvent(t, id, "requeued", "human");
+    return set(t, id, { status: "queued", step: "queued", attempts: 0, lastError: null }, now);
+  });
+}
+
+/** Human: redo a finished research job (verdict looked wrong). */
+export function reopen(db: Db, id: string, note = "", now = Date.now()) {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    // A queued job can be reopened again to replace its note.
+    if (job.kind !== "research" || (job.status !== "done" && job.status !== "queued")) throw new JobError(`job ${id} is not a finished or queued research job`);
+    logEvent(t, id, "reopened", "human", { previous: job.outcome, note });
+    return set(t, id, { status: "queued", step: "queued", attempts: 0, outcome: null, data: { ...job.data, reopenNote: note } }, now);
+  });
+}
+
+/**
+ * The human listed the product themselves (or found it already listed). Any job that isn't mid-run becomes a
+ * finished submission, so no agent submits there again; `submissions check` then tracks it like any other.
+ */
+export function recordManual(db: Db, id: string, outcome: Outcome, listingUrl?: string, now = Date.now()) {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    if (job.kind !== "submission") throw new JobError(`job ${id} is not a submission`);
+    if ((job.status === "running" || job.status === "unknown") && (job.leaseExpiresAt ?? 0) > now)
+      throw new JobError(`an agent (${job.worker}) is working on ${job.subject} right now; wait for it to stop`);
+    logEvent(t, id, "added_manually", "human", { outcome, listingUrl, from: job.status });
+    return set(t, id, {
+      status: "done", step: "submitted", outcome, listingUrl: listingUrl ?? job.listingUrl,
+      worker: null, leaseExpiresAt: null, blockType: null, blockMessage: null, lastError: null,
+    }, now);
+  });
+}
+
+/** Moderation tracking after submit: pending -> live/rejected. */
+export function setOutcome(db: Db, id: string, outcome: Outcome, listingUrl?: string, now = Date.now()) {
+  return tx(db, (t) => {
+    const job = get(t, id);
+    if (job.status !== "done" || job.kind !== "submission") throw new JobError(`job ${id} is not a finished submission`);
+    logEvent(t, id, "outcome_changed", null, { from: job.outcome, to: outcome, listingUrl });
+    return set(t, id, { outcome, listingUrl: listingUrl ?? job.listingUrl }, now);
+  });
+}
+
+export const jobEvents = (db: Db, id: string) =>
+  db.select().from(events).where(eq(events.jobId, id)).orderBy(asc(events.at), asc(events.id)).all();
+
+export { logEvent };