@bitkyc08/opencodex 2.43.0 → 2.44.0

package/src/images/loop.ts

@@ -253,6 +253,8 @@ export interface ImageBridgeDeps {
   stallTimeoutSec?: number;
   /** Provider-specific fetch (e.g. xAI transport wrapper). Falls back to global fetch. */
   fetchImpl?: typeof globalThis.fetch;
+  /** Bind physical dispatch to this iteration's built request; pacing remains owned by the loop. */
+  fetchForRequest?: (request: AdapterRequest, parsed: OcxParsedRequest) => typeof globalThis.fetch;
   /** Reserve the routed provider's next request-start slot before each adapter dispatch. */
   waitForRequestSlot?: (signal?: AbortSignal) => Promise<void>;
   /** Raw adapter usage at the terminal event, pre wire-normalization (see bridgeToResponsesSSE onUsage). */
@@ -499,6 +501,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
           cachedRequest = request;
           cachedAdapter = requestAdapter;
         }
+        const requestFetch = deps.fetchForRequest?.(request, iterParsed) ?? fetchImpl;
         let response: Response;
         try {
           if (requestAdapter.fetchResponse) {
@@ -509,7 +512,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
               timeoutMs: connectTimeoutMs,
               returnRawErrors: true,
               stream: true,
-              executor: fetchImpl,
+              executor: requestFetch,
             });
           } else {
             response = await fetchWithResetRetry(
@@ -524,7 +527,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
                 // Same reset-recovery parity as the web-search loop: the replay needs
                 // `keepalive: false` to abandon the pooled socket, because Bun has ignored the
                 // hop-by-hop header alone (oven-sh/bun#20492).
-                return fetchImpl(request.url, applyUpstreamRecoveryInit({
+                return requestFetch(request.url, applyUpstreamRecoveryInit({
                   method: request.method,
                   headers: h,
                   body: request.body,

package/src/integrations/aside-profile-context.ts

@@ -0,0 +1,270 @@
+import { lstatSync, readdirSync, realpathSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { ClientPathError, type ExportModel } from "../clients/config-export";
+import { assertAsideProfileBoundary, guardAsideProfileIO, listAsideProfiles, type AsideProfile } from "../clients/aside-profiles";
+import type { OcxConfig } from "../types";
+import { type IntegrationIO } from "./config-io";
+import type { JournalEntry } from "./journal";
+import { IntegrationMutationBusyError, runIntegrationMutationFlight } from "./mutation-flight";
+import { fingerprint } from "./ownership";
+import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
+import type { IntegrationWriteInput, WriteOutcome } from "./writer";
+import type { IntegrationWriterLockSeams } from "./writer-lock";
+
+export interface AsideProfilesInput {
+  config: OcxConfig;
+  models: readonly ExportModel[] | (() => Promise<readonly ExportModel[]>);
+  port: number;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  store?: IntegrationStateStore;
+  io?: IntegrationIO;
+  persistConfig?: (config: OcxConfig) => void | Promise<void>;
+  lockSeams?: IntegrationWriterLockSeams;
+}
+
+export class AsideProfileError extends Error {
+  constructor(readonly code: string, readonly status: number, message: string) {
+    super(message);
+    this.name = "AsideProfileError";
+  }
+}
+
+export type AsideProfilePolicy = NonNullable<OcxConfig["asideProfileSync"]>;
+export type AsideProfileWriteOutcome = WriteOutcome & { profileId: number };
+export interface AsideProfileScope {
+  profile: AsideProfile;
+  store: IntegrationStateStore;
+  io: IntegrationIO;
+  assertBoundary: () => void;
+}
+export interface AsideProfileContext {
+  input: AsideProfilesInput;
+  profiles: AsideProfile[];
+  rootStore: IntegrationStateStore;
+  legacyProfileId: number | null;
+  defaultEnabled: boolean;
+  models: () => Promise<readonly ExportModel[]>;
+  scopes: Map<number, AsideProfileScope>;
+}
+
+function storeUnsafe(): never {
+  throw new AsideProfileError("aside_profile_store_unsafe", 409, "Aside profile ownership storage cannot be accessed safely");
+}
+
+/** Allow aliases above the trusted anchor, never at or below it. */
+function storeGuard(anchor: string, target: string): () => void {
+  const base = resolve(anchor);
+  const root = resolve(target);
+  const rel = relative(base, root);
+  if (rel.startsWith(`..${sep}`) || rel === ".." || resolve(base, rel) !== root) storeUnsafe();
+  const identities = new Map<string, string>();
+  const inspect = (path: string, directory: boolean): boolean => {
+    try {
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile()) || (!directory && stat.nlink > 1)) storeUnsafe();
+      if (directory) {
+        const identity = `${realpathSync(path)}:${stat.dev}:${stat.ino}`;
+        if (identities.has(path) && identities.get(path) !== identity) storeUnsafe();
+        identities.set(path, identity);
+      }
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT" && !identities.has(path)) return false;
+      storeUnsafe();
+    }
+  };
+  return () => {
+    let path = base;
+    if (!inspect(path, true)) return;
+    for (const part of rel ? rel.split(sep) : []) {
+      path = join(path, part);
+      if (!inspect(path, true)) return;
+    }
+    for (const name of ["records.json", "journal.jsonl", "maintenance.json"]) inspect(join(root, name), false);
+    const snapshots = join(root, "snapshots");
+    if (!inspect(snapshots, true)) return;
+    const aside = join(snapshots, "aside");
+    if (inspect(aside, true)) for (const name of readdirSync(aside)) inspect(join(aside, name), false);
+  };
+}
+
+/** Store methods close over their original root; IO bookkeeping must bind to the guarded facade. */
+function guardedStore(store: IntegrationStateStore, anchor: string): IntegrationStateStore {
+  const guard = storeGuard(anchor, store.root);
+  guard();
+  return new Proxy(store, {
+    get(target, property, receiver) {
+      const value: unknown = Reflect.get(target, property, receiver);
+      if (typeof value !== "function") return value;
+      return (...args: unknown[]) => {
+        guard();
+        if (property === "readSnapshot") assertAsideSnapshotEntry(args[0] as JournalEntry);
+        // Maintenance in this service is Aside-scoped, including a legacy shared store.
+        if (property === "retryPendingPrunes") {
+          if (store.readMaintenance().pruneFailures.aside) {
+            if (store.pruneSnapshots("aside").ok) store.clearPruneFailure("aside");
+          }
+          return;
+        }
+        return Reflect.apply(value, target, args);
+      };
+    },
+  });
+}
+
+export function asideRootStore(input: AsideProfilesInput): IntegrationStateStore {
+  const raw = input.store ?? createIntegrationStateStore();
+  return guardedStore(raw, raw.root);
+}
+
+export function assertAsideSnapshotEntry(entry: JournalEntry): void {
+  if (!entry || entry.clientId !== "aside" || typeof entry.opId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(entry.opId) || !entry.snapshot
+    || !["none", "stored", "expired"].includes(entry.snapshot.kind)
+    || (entry.snapshot.kind === "stored" && entry.snapshot.relPath !== join("snapshots", "aside", entry.opId))) {
+    throw new AsideProfileError("aside_operation_invalid", 409, "Aside operation snapshot metadata is invalid");
+  }
+}
+
+export function createAsideProfileContext(input: AsideProfilesInput): AsideProfileContext {
+  let profiles: AsideProfile[];
+  try { profiles = listAsideProfiles(input.env, input.home); }
+  catch (error) {
+    if (error instanceof ClientPathError) throw new AsideProfileError("aside_profiles_unavailable", 409, error.message);
+    throw new AsideProfileError("aside_profiles_unavailable", 409, "Aside profiles cannot be read");
+  }
+  const rootStore = asideRootStore(input);
+  const record = rootStore.readRecords().aside;
+  const matched = record?.clientId === "aside" ? profiles.find(profile => profile.configPath === record.configPath) : undefined;
+  const pinned = input.config.asideProfileSync?.legacyProfileId;
+  const newest = !record && pinned === undefined ? rootStore.listOperations("aside", 1)[0] : undefined;
+  const legacyProfileId = pinned !== undefined ? pinned : record
+    ? matched?.id ?? null
+    : profiles.find(profile => profile.configPath === newest?.configPath)?.id ?? null;
+  let loaded: Promise<readonly ExportModel[]> | undefined;
+  return {
+    input: { ...input, env: { ...(input.env ?? process.env) } }, profiles, rootStore, legacyProfileId, scopes: new Map(),
+    defaultEnabled: input.config.asideProfileSync?.allProfiles ?? Boolean(matched),
+    models: () => loaded ??= Promise.resolve().then(() => typeof input.models === "function" ? input.models() : input.models),
+  };
+}
+
+export function selectAsideProfiles(ctx: AsideProfileContext, profileId?: number): AsideProfile[] {
+  if (profileId === undefined) return ctx.profiles;
+  if (!Number.isSafeInteger(profileId) || profileId < 0 || Object.is(profileId, -0)) {
+    throw new AsideProfileError("invalid_aside_profile", 400, "Aside profile must be a nonnegative safe integer");
+  }
+  const profile = ctx.profiles.find(candidate => candidate.id === profileId);
+  if (!profile) throw new AsideProfileError("aside_profile_not_found", 404, "Aside profile is not registered");
+  return [profile];
+}
+
+export function asideProfileEnabled(ctx: AsideProfileContext, id: number): boolean {
+  return ctx.input.config.asideProfileSync?.profiles?.[String(id)] ?? ctx.defaultEnabled;
+}
+
+export function asideProfileScope(ctx: AsideProfileContext, profile: AsideProfile): AsideProfileScope {
+  try { return resolveScope(ctx, profile); }
+  catch (error) {
+    if (error instanceof ClientPathError) throw new AsideProfileError("aside_profile_unsafe", 409, error.message);
+    throw error;
+  }
+}
+
+function resolveScope(ctx: AsideProfileContext, profile: AsideProfile): AsideProfileScope {
+  const cached = ctx.scopes.get(profile.id);
+  if (cached) { cached.assertBoundary(); return cached; }
+  assertAsideProfileBoundary(profile, ctx.profiles);
+  const store = profile.id === ctx.legacyProfileId ? ctx.rootStore
+    : guardedStore(createIntegrationStateStore(join(ctx.rootStore.root, "aside-profiles", String(profile.id))), ctx.rootStore.root);
+  const assertBoundary = () => {
+    assertAsideProfileBoundary(profile, ctx.profiles);
+    const record = store.readRecords().aside;
+    if (record && (record.clientId !== "aside" || record.configPath !== profile.configPath)) {
+      throw new AsideProfileError("aside_profile_owner_mismatch", 409, "Aside ownership belongs to a different profile");
+    }
+  };
+  assertBoundary();
+  const baseIO = ctx.input.io ?? store.io();
+  const guarded = guardAsideProfileIO(profile, {
+    ...baseIO,
+    appendJournal: entry => store.appendJournal(entry),
+    putRecord: record => store.putRecord(record),
+    dropRecord: clientId => store.dropRecord(clientId),
+  }, ctx.profiles);
+  const io: IntegrationIO = {
+    ...guarded,
+    writeText: (path, text) => { assertBoundary(); guarded.writeText(path, text); },
+    removeFile: path => { assertBoundary(); guarded.removeFile(path); },
+    mkdirp: path => { assertBoundary(); guarded.mkdirp(path); },
+  };
+  const scope = { profile, store, io, assertBoundary };
+  ctx.scopes.set(profile.id, scope);
+  return scope;
+}
+
+export async function asideWriteInput(ctx: AsideProfileContext, scope: AsideProfileScope): Promise<IntegrationWriteInput> {
+  const models = await ctx.models();
+  scope.assertBoundary();
+  return {
+    clientId: "aside", config: ctx.input.config, models, port: ctx.input.port,
+    env: ctx.input.env, home: ctx.input.home, store: scope.store, io: scope.io,
+    resolvedPaths: { configPath: scope.profile.configPath, detectDir: scope.profile.detectDir },
+  };
+}
+
+/** Save intent first; an unsuccessful save must not leave even in-memory intent changed. */
+export async function persistAsidePolicy(ctx: AsideProfileContext, change?: { enabled: boolean; profileId?: number }): Promise<void> {
+  const { config, persistConfig } = ctx.input;
+  if (!persistConfig) throw new AsideProfileError("aside_profile_persistence_required", 500, "Aside profile changes require configuration persistence");
+  const previous = config.asideProfileSync;
+  const policy: AsideProfilePolicy = {
+    ...previous, allProfiles: ctx.defaultEnabled, legacyProfileId: ctx.legacyProfileId,
+    profiles: { ...previous?.profiles },
+  };
+  if (change && change.profileId === undefined) {
+    policy.allProfiles = change.enabled;
+    policy.profiles = {};
+  } else if (change) policy.profiles![String(change.profileId)] = change.enabled;
+  config.asideProfileSync = policy;
+  try { await persistConfig(config); }
+  catch {
+    if (previous === undefined) delete config.asideProfileSync;
+    else config.asideProfileSync = previous;
+    throw new AsideProfileError("aside_profile_persist_failed", 500, "Aside profile preferences could not be saved; no profile files were changed");
+  }
+  ctx.defaultEnabled = policy.allProfiles!;
+}
+
+export async function runAsideProfileAction<T>(
+  input: AsideProfilesInput,
+  profileId: number | undefined,
+  semantics: string,
+  action: (ctx: AsideProfileContext, profiles: AsideProfile[]) => Promise<T>,
+): Promise<T> {
+  const ctx = createAsideProfileContext(input);
+  const profiles = selectAsideProfiles(ctx, profileId);
+  const key = `aside:${fingerprint(`${ctx.rootStore.root}:${profiles.map(p => p.root).join(",")}`)}:${profiles.map(p => p.id).sort((a, b) => a - b).join(",")}:${semantics}:${crypto.randomUUID()}`;
+  try {
+    return await runIntegrationMutationFlight("aside", key, input.io?.now ?? Date.now, async () => {
+      // Publish the flight before invoking user-supplied persistence callbacks.
+      await Promise.resolve();
+      return action(ctx, profiles);
+    });
+  } catch (error) {
+    if (error instanceof IntegrationMutationBusyError) {
+      throw new AsideProfileError("integration_mutation_busy", 409, "An Aside profile operation is already running");
+    }
+    if (error instanceof AsideProfileError) throw error;
+    if (error instanceof ClientPathError) throw new AsideProfileError("aside_profile_unsafe", 409, error.message);
+    throw new AsideProfileError("aside_profile_operation_failed", 500, "Aside profile operation could not be completed");
+  }
+}
+
+export function asideProfileFailure(profileId: number, error: unknown): AsideProfileWriteOutcome {
+  return {
+    clientId: "aside", profileId, ok: false, reason: "unsafe", state: "unsafe",
+    message: error instanceof AsideProfileError || error instanceof ClientPathError
+      ? error.message : "Aside profile could not be updated safely",
+  };
+}

package/src/integrations/aside-profile-journal.ts

@@ -0,0 +1,229 @@
+import { EXPORT_CLIENTS } from "../clients/config-export";
+import { loadTarget, parseConfig } from "./config-io";
+import { matchesOperationResult, type JournalEntry } from "./journal";
+import { fingerprint, type OwnershipRecord } from "./ownership";
+import { classifyIntegration, exportContextOf } from "./state";
+import type { IntegrationStateStore } from "./store";
+import { restoreIntegrationCoordinated, type IntegrationWriteInput } from "./writer";
+import {
+  AsideProfileError, asideProfileFailure, asideProfileScope, asideRootStore, asideWriteInput, assertAsideSnapshotEntry,
+  createAsideProfileContext, persistAsidePolicy, runAsideProfileAction, selectAsideProfiles,
+  type AsideProfileContext, type AsideProfilesInput, type AsideProfileScope, type AsideProfileWriteOutcome,
+} from "./aside-profile-context";
+
+export interface AsideOperation {
+  profileId: number;
+  entry: JournalEntry;
+  store: IntegrationStateStore;
+}
+
+function operationRows(ctx: AsideProfileContext, profileId?: number): AsideOperation[] {
+  const rows: AsideOperation[] = [];
+  const entriesByRoot = new Map<string, JournalEntry[]>();
+  for (const profile of selectAsideProfiles(ctx, profileId)) {
+    const scope = asideProfileScope(ctx, profile);
+    const stores = scope.store.root === ctx.rootStore.root ? [scope.store] : [scope.store, ctx.rootStore];
+    for (const store of stores) {
+      let entries = entriesByRoot.get(store.root);
+      if (entries === undefined) {
+        entries = store.listOperations("aside", Number.MAX_SAFE_INTEGER);
+        entriesByRoot.set(store.root, entries);
+      }
+      for (const entry of entries) {
+        if (entry.clientId === "aside" && entry.configPath === profile.configPath) {
+          assertAsideSnapshotEntry(entry);
+          if (typeof entry.at !== "string") throw new AsideProfileError("aside_operation_invalid", 409, "Aside operation timestamp is invalid");
+          rows.push({ profileId: profile.id, entry, store });
+        }
+      }
+    }
+  }
+  // A copied entry retains its original timestamp; import time cannot make it newest.
+  return rows.sort((a, b) => b.entry.at.localeCompare(a.entry.at));
+}
+
+function uniqueOperations(rows: AsideOperation[]): AsideOperation[] {
+  const seen = new Map<string, AsideOperation>();
+  for (const row of rows) {
+    const previous = seen.get(row.entry.opId);
+    if (previous && (previous.profileId !== row.profileId || JSON.stringify(previous.entry) !== JSON.stringify(row.entry))) {
+      throw new AsideProfileError("aside_operation_ambiguous", 409, "Aside operation identifies multiple profiles");
+    }
+    if (!previous) {
+      seen.set(row.entry.opId, row);
+      continue;
+    }
+    // Identical journal rows can outlive different snapshot-retention windows.
+    const previousSnapshot = previous.store.readSnapshot(previous.entry);
+    const candidateSnapshot = row.store.readSnapshot(row.entry);
+    if (previousSnapshot.kind === "stored" && candidateSnapshot.kind === "stored"
+      && previousSnapshot.text !== candidateSnapshot.text) {
+      throw new AsideProfileError("aside_operation_ambiguous", 409, "Aside operation has conflicting snapshot copies");
+    }
+    if (previousSnapshot.kind === "expired" && candidateSnapshot.kind === "stored") seen.set(row.entry.opId, row);
+  }
+  return [...seen.values()];
+}
+
+export function listAsideOperations(input: AsideProfilesInput, profileId?: number): AsideOperation[] {
+  try { return uniqueOperations(operationRows(createAsideProfileContext(input), profileId)); }
+  catch (error) {
+    if (profileId === undefined && error instanceof AsideProfileError && error.code === "aside_profiles_unavailable") return [];
+    throw error;
+  }
+}
+
+function findOperation(ctx: AsideProfileContext, opId: string, profileId?: number): AsideOperation | null {
+  if (typeof opId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(opId)) {
+    throw new AsideProfileError("invalid_op_id", 400, "Aside operation ID is invalid");
+  }
+  const rows = uniqueOperations(operationRows(ctx, profileId));
+  const found = rows.find(row => row.entry.opId === opId);
+  if (found) return found;
+  const legacy = ctx.rootStore.findOperation(opId);
+  if (legacy?.clientId === "aside") {
+    if (!ctx.profiles.some(profile => profile.configPath === legacy.configPath)) {
+      throw new AsideProfileError("aside_profile_not_found", 404, "The operation's Aside profile is no longer registered");
+    }
+    if (profileId !== undefined) throw new AsideProfileError("aside_operation_profile_mismatch", 409, "Aside operation belongs to a different profile");
+  }
+  return null;
+}
+
+export function findAsideOperation(input: AsideProfilesInput, opId: string, profileId?: number): AsideOperation | null {
+  const legacy = asideRootStore(input).findOperation(opId);
+  if (profileId === undefined && legacy && legacy.clientId !== "aside") return null;
+  try { return findOperation(createAsideProfileContext(input), opId, profileId); }
+  catch (error) {
+    if (profileId === undefined && !legacy && error instanceof AsideProfileError && error.code === "aside_profiles_unavailable") return null;
+    throw error;
+  }
+}
+
+/** Guarded history projection: never expose profile bytes to API serializers. */
+export function asideOperationMatchesCurrent(input: AsideProfilesInput, row: AsideOperation): boolean {
+  try {
+    const ctx = createAsideProfileContext(input);
+    const verified = findOperation(ctx, row.entry.opId, row.profileId);
+    if (!verified || verified.entry.configPath !== row.entry.configPath) return false;
+    const profile = selectAsideProfiles(ctx, row.profileId)[0]!;
+    const scope = asideProfileScope(ctx, profile);
+    const target = loadTarget(scope.io, profile.configPath);
+    return target.ok && scope.io.statKind(profile.detectDir) === "dir" && matchesOperationResult(verified.entry, target.before);
+  } catch { return false; }
+}
+
+function requiredOperation(ctx: AsideProfileContext, opId: string, profileId?: number): AsideOperation {
+  const row = findOperation(ctx, opId, profileId);
+  if (!row) throw new AsideProfileError("integration_operation_not_found", 404, "Aside operation not found");
+  return row;
+}
+
+function validatePriorRecord(record: OwnershipRecord | null, configPath: string): void {
+  if (record === null) return;
+  if (!record || record.clientId !== "aside" || record.configPath !== configPath
+    || typeof record.fileFingerprint !== "string" || typeof record.blockFingerprint !== "string"
+    || typeof record.opId !== "string" || typeof record.appliedAt !== "string"
+    || !Array.isArray(record.fragmentPaths) || record.fragmentPaths.length !== 1
+    || record.fragmentPaths[0]?.length !== 2 || record.fragmentPaths[0][0] !== "providers"
+    || record.fragmentPaths[0][1] !== "opencodex"
+    || (record.createdContainers !== undefined && (!Array.isArray(record.createdContainers)
+      || !record.createdContainers.every(path => path === "providers")))) {
+    throw new AsideProfileError("aside_operation_invalid", 409, "Aside operation ownership metadata is invalid");
+  }
+}
+
+function snapshotWasOwned(entry: JournalEntry, text: string | null, bound: IntegrationWriteInput): boolean {
+  const record = entry.priorRecord;
+  if (!record || text === null || record.fileFingerprint !== fingerprint(text)) return false;
+  const state = classifyIntegration({
+    fileText: text, fileIsRegular: true, parsed: parseConfig(text, EXPORT_CLIENTS.aside.format), record,
+    contribution: EXPORT_CLIENTS.aside.buildContribution(exportContextOf(bound)),
+    configPath: entry.configPath, clientId: "aside",
+  }).state;
+  return state === "current" || state === "stale";
+}
+
+/** Import only an immutable historical row and its bytes, never the legacy ownership record. */
+function importOperation(row: AsideOperation, scope: AsideProfileScope): void {
+  if (row.store.root === scope.store.root) return;
+  const existing = scope.store.findOperation(row.entry.opId);
+  if (existing && JSON.stringify(existing) !== JSON.stringify(row.entry)) {
+    throw new AsideProfileError("aside_operation_ambiguous", 409, "Aside operation conflicts with existing profile history");
+  }
+  const snapshot = row.store.readSnapshot(row.entry);
+  if (snapshot.kind === "expired") throw new AsideProfileError("integration_snapshot_expired", 410, "That backup has expired");
+  scope.io.statKind(scope.profile.detectDir);
+  scope.assertBoundary();
+  if (snapshot.kind === "stored") {
+    const present = scope.store.readSnapshot(row.entry);
+    if (present.kind === "stored" && present.text !== snapshot.text) {
+      throw new AsideProfileError("aside_operation_ambiguous", 409, "Aside snapshot conflicts with existing profile history");
+    }
+    if (present.kind !== "stored") scope.store.captureSnapshot("aside", row.entry.opId, snapshot.text);
+  }
+  if (!existing) scope.store.appendJournal(structuredClone(row.entry));
+}
+
+export function restoreAsideProfile(
+  input: AsideProfilesInput,
+  request: { opId: string; profileId?: number; confirmDrift?: boolean },
+): Promise<AsideProfileWriteOutcome> {
+  return runAsideProfileAction<AsideProfileWriteOutcome>(input, request.profileId, `restore:${request.opId}:${Boolean(request.confirmDrift)}`, async ctx => {
+    const row = requiredOperation(ctx, request.opId, request.profileId);
+    const profile = selectAsideProfiles(ctx, row.profileId)[0]!;
+    const scope = asideProfileScope(ctx, profile);
+    assertAsideSnapshotEntry(row.entry);
+    validatePriorRecord(row.entry.priorRecord, profile.configPath);
+    const snapshot = row.store.readSnapshot(row.entry);
+    if (snapshot.kind === "expired") {
+      return { clientId: "aside", profileId: profile.id, ok: false, reason: "snapshot_expired", state: "absent", message: "That backup has expired" };
+    }
+    const bound = await asideWriteInput(ctx, scope);
+    const target = loadTarget(scope.io, profile.configPath);
+    if (!target.ok || scope.io.statKind(profile.detectDir) !== "dir") {
+      return asideProfileFailure(profile.id, new AsideProfileError("aside_profile_unsafe", 409, "Aside profile cannot be restored safely"));
+    }
+    if (!request.confirmDrift && !matchesOperationResult(row.entry, target.before)) {
+      return { clientId: "aside", profileId: profile.id, ok: false, reason: "drift_requires_confirm", state: "conflict", message: "This profile changed after that operation; confirm to replace it" };
+    }
+    const restoredText = snapshot.kind === "stored" ? snapshot.text : null;
+    await persistAsidePolicy(ctx, { profileId: profile.id, enabled: snapshotWasOwned(row.entry, restoredText, bound) });
+    try {
+      scope.assertBoundary();
+      const currentSnapshot = row.store.readSnapshot(row.entry);
+      if (JSON.stringify(row.store.findOperation(row.entry.opId)) !== JSON.stringify(row.entry)
+        || currentSnapshot.kind !== snapshot.kind
+        || (currentSnapshot.kind === "stored" && currentSnapshot.text !== restoredText)) {
+        throw new AsideProfileError("aside_operation_changed", 409, "Aside operation or snapshot changed while saving preferences");
+      }
+      importOperation(row, scope);
+      return { ...await restoreIntegrationCoordinated({ ...bound, opId: request.opId, confirmDrift: request.confirmDrift }, { lockSeams: input.lockSeams }), profileId: profile.id };
+    } catch (error) { return asideProfileFailure(profile.id, error); }
+  });
+}
+
+export function deleteAsideOperation(
+  input: AsideProfilesInput,
+  request: { opId: string; profileId?: number; principal?: string },
+): Promise<{ ok: true; clientId: "aside"; profileId: number; opId: string; snapshotRemoved: boolean }> {
+  return runAsideProfileAction(input, request.profileId, `delete:${request.opId}`, async ctx => {
+    const row = requiredOperation(ctx, request.opId, request.profileId);
+    const rows = operationRows(ctx, row.profileId);
+    if (rows[0]?.entry.opId === request.opId) {
+      throw new AsideProfileError("integration_journal_newest_protected", 409, "The newest operation for an Aside profile cannot be deleted");
+    }
+    await persistAsidePolicy(ctx);
+    const stores = new Map(rows.filter(candidate => candidate.entry.opId === request.opId).map(candidate => [candidate.store.root, candidate.store]));
+    const tombstone = { tombstone: request.opId, at: new Date(input.io?.now() ?? Date.now()).toISOString(), by: request.principal ?? "management" };
+    // Retire every copy before pruning any snapshot; deduped history must not resurrect a source row.
+    for (const store of stores.values()) store.retireOperation(tombstone);
+    let snapshotRemoved = true;
+    for (const store of stores.values()) {
+      const pruned = store.pruneSnapshots("aside");
+      if (pruned.ok) store.clearPruneFailure("aside");
+      else { snapshotRemoved = false; store.markPruneFailure("aside", pruned.error); }
+    }
+    return { ok: true, clientId: "aside", profileId: row.profileId, opId: request.opId, snapshotRemoved };
+  });
+}