/**
 * Value-free planning for integration mutations.
 *
 * An operator confirming "apply", "overwrite", "disable" or "undo" is agreeing to consequences
 * nobody has shown them. This module computes those consequences as bounded managed schema paths
 * and closed change kinds, and binds them to a fingerprint over every input the decision rested
 * on, so a confirmation can be refused when the state it described has moved.
 *
 * Two rules give the output its safety. Nothing here is a value: paths are structural, and a
 * segment that is not representable in the managed grammar is dropped rather than echoed, because
 * an ownership record on disk accepts arbitrary strings and is not a validation authority. And
 * nothing here writes: this module owns no IO, takes no lock, and must never import the writer.
 * The dependency direction is state/ownership/merge into here, and here into the writer and the
 * preview route.
 */
import { createHash } from "node:crypto";
import { dirname } from "node:path";
import { canonicalContribution, fingerprint, type OwnershipRecord } from "./ownership";
import { ClientPathError } from "../clients/client-path";
import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
import { OPENCODE_PROVIDER_ID } from "../clients/config-export/constants";
import { resolveModelNames, type ExportModelNames } from "../clients/config-export/model-names";
import {
  ZCODE_STORE_MODEL_RULES_PATH,
  ZCODE_STORE_PROVIDER_RULES_PATH,
} from "../clients/config-export/zcode-store";
import { createClineIO, ClineTransactionError } from "./cline-io";
import { parseClineDocument } from "./cline-document";
import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
import {
  INTEGRATION_CLIENTS,
  boundIntegrationConfigPath,
  assertDroidPathsUnambiguous,
  assertDroidRecordedSettingsUnambiguous,
  isLoopbackOnly,
  resolveIntegrationPaths,
  type ResolvedIntegrationPaths,
  restoreOwnershipCollision,
  type IntegrationClientId,
} from "./registry";
import { declaredIntegrationTarget, resolveIntegrationTarget, type IneffectiveWrite, type IneffectiveWriteReason, type IntegrationTarget } from "./target";
import { shouldInjectApiAuthHeader } from "../codex/inject";
import { buildIntegrationContribution, classifyIntegration, exportContextOf, qoderLegacyCatalogConflict, readPath, type IntegrationState, type StateReason } from "./state";
import { inspectKiloCandidates } from "./kilo-candidates";
import { InvalidSelectorError, UnrepresentableSelectorError } from "./merge";
import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
import type { OcxConfig } from "../types";
import { matchesOperationResult, type JournalEntry } from "./journal";

/**
 * Why a mutation refused. Declared here rather than in the writer so the planner can report a
 * refusal without depending on the module that performs writes; the writer re-exports it, so this
 * is a move rather than a second vocabulary.
 */
export type RefusalReason =
  | "not_installed"
  | "conflict"
  | "unsafe"
  | "non_loopback"
  | "superseded_store"
  | "drift_requires_confirm"
  | "snapshot_expired"
  | "write_failed";

export type IntegrationPlanOperation = "apply" | "overwrite" | "disable" | "restore";
export type IntegrationPlanChangeKind = "add" | "replace" | "remove" | "snapshot" | "ownership" | "journal";
export type IntegrationPlanForeignEdit = "none" | "unowned" | "foreign-edit" | "drift";

/**
 * Effects that are not places in the client's document. They carry no disk location and no value,
 * so an operator learns that history will be written without learning where it lives.
 */
export const PLAN_SNAPSHOT_PATH = "$snapshot";
export const PLAN_OWNERSHIP_PATH = "$ownership";
export const PLAN_JOURNAL_PATH = "$journal";

/**
 * Upper bound on reported changes. Above the largest contribution any registered client builds and
 * well below a response worth truncating, so the cap is a guard rather than a routine limit.
 */
export const PLAN_CHANGE_LIMIT = 256;

export interface IntegrationPlanChange {
  readonly kind: IntegrationPlanChangeKind;
  readonly path: string;
}

export interface IntegrationMutationPlan {
  readonly version: 1;
  readonly clientId: IntegrationClientId;
  readonly operation: IntegrationPlanOperation;
  readonly state: IntegrationState;
  readonly foreignEdit: IntegrationPlanForeignEdit;
  readonly changes: readonly IntegrationPlanChange[];
  readonly fingerprint: string;
  readonly canApply: boolean;
  /**
   * Whether confirming would write at all.
   *
   * An apply against an already-current file and a disable against an absent one both succeed
   * while writing nothing, so reporting a snapshot and a journal row for them would describe
   * consequences that never happen.
   */
  readonly willChange: boolean;
  readonly refusalReason?: RefusalReason;
  /**
   * `superseded_store` only: why the store the client reads is not written. The store's location
   * stays on the status row (`supersededBy`); the plan names no file.
   */
  readonly supersededReason?: IneffectiveWriteReason;
  /** `missing-store` only: the document that recreates the store, so the remedy can name it. */
  readonly missingStoreDocument?: string;
  readonly profileId?: number;
}

/** A position whose observed value is never published, only its presence. */
export const DYNAMIC_SEGMENT = "*";

/**
 * Where each client's managed fragments live, declared rather than inferred.
 *
 * A general "looks like a plain key" rule is not good enough, and Kimi is the proof: it writes one
 * fragment per model at `models.<alias>`, so an alphanumeric allowlist would publish a user's
 * model identifier verbatim. The same rule would accept any plain path sitting in an ownership
 * record, and a record on disk is not a validation authority.
 *
 * So a path is published only when it matches one of these templates exactly. Static segments must
 * match literally, a DYNAMIC_SEGMENT position accepts any observed segment, and the string that
 * leaves this module is the TEMPLATE rather than the observed path. That is what makes publishing
 * a value structurally impossible instead of merely unlikely.
 *
 * The satisfies clause makes a new client a type error here, so nobody can add one whose managed
 * paths silently have no declaration.
 */
const CLIENT_MANAGED_PATHS = {
  qoder: [["providers", OPENCODE_PROVIDER_ID], ["modelConfigs", "customModels", DYNAMIC_SEGMENT]],
  "qoder-cn": [["providers", OPENCODE_PROVIDER_ID], ["modelConfigs", "customModels", DYNAMIC_SEGMENT]],
  workbuddy: [["models", DYNAMIC_SEGMENT], [DYNAMIC_SEGMENT]],
  "workbuddy-ai": [["models", DYNAMIC_SEGMENT], [DYNAMIC_SEGMENT]],
  opencode: [["provider", OPENCODE_PROVIDER_ID], ["providers", OPENCODE_PROVIDER_ID]],
  pi: [["providers", OPENCODE_PROVIDER_ID]],
  "gentle-shell": [["providers", OPENCODE_PROVIDER_ID]],
  omp: [["providers", OPENCODE_PROVIDER_ID]],
  hermes: [["providers", OPENCODE_PROVIDER_ID]],
  openclaw: [["models", "providers", OPENCODE_PROVIDER_ID]],
  kimi: [["providers", OPENCODE_PROVIDER_ID], ["models", DYNAMIC_SEGMENT]],
  gajae: [["providers", OPENCODE_PROVIDER_ID]],
  dsh: [["llm-pi-ai", "providers", OPENCODE_PROVIDER_ID], ["[id=llm-pi-ai]", "config", "providers", OPENCODE_PROVIDER_ID]],
  mcode: [["custom_provider", OPENCODE_PROVIDER_ID]],
  zcode: [
    ["provider", OPENCODE_PROVIDER_ID],
    /*
     * The store the current client reads. The model rule carries the model id in
     * its own selector, so the published segment is the dynamic one: the template
     * leaves this module, never the observed path.
     */
    [...ZCODE_STORE_PROVIDER_RULES_PATH, `[providerId=${OPENCODE_PROVIDER_ID}]`],
    [...ZCODE_STORE_MODEL_RULES_PATH, DYNAMIC_SEGMENT],
  ],
  /*
   * Both roots, because the client picks between them rather than reading both:
   * `document.provider ?? document.providers` in `command-code@1.66.0`. The
   * builder chooses the one the target already uses, and a block we wrote under
   * either root has to be removable from either root afterwards.
   */
  commandcode: [["provider", OPENCODE_PROVIDER_ID], ["providers", OPENCODE_PROVIDER_ID]],
  prime: [["providers", OPENCODE_PROVIDER_ID]],
  aside: [["providers", OPENCODE_PROVIDER_ID]],
  raycast: [["providers", `[id=${OPENCODE_PROVIDER_ID}]`]],
  omo: [["providers", OPENCODE_PROVIDER_ID]],
  cline: [
    ["settings", "providers", OPENCODE_PROVIDER_ID],
    ["catalog", "providers", OPENCODE_PROVIDER_ID],
  ],
  kilo: [["provider", OPENCODE_PROVIDER_ID]],
  droid: [["customModels", DYNAMIC_SEGMENT]],
  t3code: [["providerInstances", OPENCODE_PROVIDER_ID]],
} satisfies Record<IntegrationClientId, readonly (readonly string[])[]>;

/** Not a configuration surface. Exported so a parity case can compare it against the shipped clients. */
export const MANAGED_PATH_TEMPLATES: Readonly<Record<IntegrationClientId, readonly (readonly string[])[]>> = CLIENT_MANAGED_PATHS;

function matchesTemplate(template: readonly string[], path: readonly string[]): boolean {
  if (template.length !== path.length) return false;
  return template.every((segment, index) => {
    const observed = path[index];
    if (observed === undefined || observed.length === 0) return false;
    return segment === DYNAMIC_SEGMENT || segment === observed;
  });
}

/**
 * The managed schema path this change touches, or null when the path is outside the client's
 * declared grammar.
 *
 * Null is not an error to work around. A path nobody declared is either a record written by a
 * different version or something arbitrary, and neither is safe to name, so the caller reports the
 * fixed ownership pseudo-path or a refusal instead of inventing a description.
 */
export function canonicalSchemaPath(clientId: IntegrationClientId, path: readonly string[]): string | null {
  if (path.length === 0) return null;
  for (const template of CLIENT_MANAGED_PATHS[clientId]) {
    if (matchesTemplate(template, path)) return template.join(".");
  }
  return null;
}

const KIND_ORDER: readonly IntegrationPlanChangeKind[] = ["add", "replace", "remove", "snapshot", "ownership", "journal"];

/**
 * Deterministic, deduplicated and capped. Deterministic because the fingerprint is taken over this
 * projection, so an unstable order would stale a plan that did not change.
 */
export function orderPlanChanges(changes: readonly IntegrationPlanChange[]): readonly IntegrationPlanChange[] {
  const seen = new Set<string>();
  const unique: IntegrationPlanChange[] = [];
  for (const change of changes) {
    const key = `${change.kind}\u0000${change.path}`;
    if (seen.has(key)) continue;
    seen.add(key);
    unique.push(change);
  }
  unique.sort((left, right) => {
    const byKind = KIND_ORDER.indexOf(left.kind) - KIND_ORDER.indexOf(right.kind);
    if (byKind !== 0) return byKind;
    return left.path < right.path ? -1 : left.path > right.path ? 1 : 0;
  });
  return Object.freeze(unique.slice(0, PLAN_CHANGE_LIMIT));
}

/**
 * Every input the plan's authority rests on.
 *
 * `models` is here because the desired contribution is derived from it, so a model roster that
 * changed between preview and commit changes what would be written. `snapshot` carries a digest of
 * the bytes a restore would actually publish rather than only the operation id, because the id
 * names the row and the bytes are what lands in the user's file.
 */
export interface PlanFingerprintInput {
  readonly requestedModelNames?: ExportModelNames;
  readonly modelNames?: ExportModelNames;
  readonly operation: IntegrationPlanOperation;
  readonly clientId: IntegrationClientId;
  readonly profileId?: number;
  readonly configPath: string;
  readonly detectDir: string;
  /**
   * What the detect directory actually was when observed, not merely where it is.
   *
   * Binding only the path leaves a confirmation valid across an uninstall: the contribution is
   * unchanged, so every other component matches, while the answer to "is this client installed"
   * has flipped. The observed kind is the input the not_installed refusal is derived from.
   */
  readonly installKind: string;
  /**
   * Whether admission policy blocks this integration, which is the non_loopback refusal's input.
   *
   * Config eligibility can change without touching the file, the record or the contribution, so a
   * plan that did not bind it could be confirmed after the proxy stopped being a legal target.
   */
  readonly admissionBlocked: boolean;
  /**
   * Why a write to the target would not reach the client, or null.
   *
   * Bound for the same reason `installKind` is: it can flip without touching the
   * file, the record or the contribution. A client that creates its new store
   * while a confirmation is outstanding has changed whether the write can reach
   * it, and a plan that did not bind this would still authorize the write. The
   * reason travels with the location because both can move on their own: a store
   * whose schema version changes under an unchanged path is the same class of
   * flip as a store appearing.
   */
  readonly ineffectiveWrite: string | null;
  /**
   * The same finding as `ineffectiveWrite`, unflattened, for the refusal's description. It is
   * descriptive only: the bound token above is what decides and what the fingerprint covers.
   */
  readonly ineffective?: IneffectiveWrite | null;
  /** Exact current bytes, or null when the target is missing. Missing and empty are not equal. */
  readonly before: string | null;
  readonly contribution: ManagedContribution | null;
  readonly record: OwnershipRecord | null;
  readonly models: readonly ExportModel[];
  readonly restore?: {
    readonly opId: string;
    readonly entry: JournalEntry;
    readonly snapshotKind: string;
    /** Digest of the snapshot's exact text, or null when it holds none. */
    readonly snapshotText: string | null;
    readonly confirmDrift: boolean;
    /**
     * Whether the target has changed since the operation being undone, which is the
     * drift_requires_confirm predicate. Passed in rather than recomputed so the plan and the
     * mutation read drift from the same comparison.
     */
    readonly driftsFromResult: boolean;
  };
}

const PLAN_FINGERPRINT_VERSION = "p3";

function digest(value: string): string {
  return createHash("sha256").update(value).digest("hex").slice(0, 32);
}

/**
 * An opaque optimistic-concurrency token, not authorization.
 *
 * Longer than the 16-hex ownership fingerprint because this one is supplied by a caller and
 * compared for equality, so accidental collision matters more than it does for a stored digest.
 * The version prefix means a future input set invalidates old tokens instead of silently
 * comparing two different meanings.
 */
export function planFingerprint(input: PlanFingerprintInput): string {
  const restore = input.restore;
  const components = [
    PLAN_FINGERPRINT_VERSION,
    input.operation,
    input.clientId,
    input.requestedModelNames ?? null,
    input.modelNames ?? null,
    input.profileId === undefined ? null : input.profileId,
    input.configPath,
    input.detectDir,
    input.installKind,
    input.admissionBlocked,
    input.ineffectiveWrite,
    input.before === null ? "\u0000absent" : fingerprint(input.before),
    input.contribution === null ? null : fingerprint(canonicalContribution(input.contribution)),
    input.record === null ? null : fingerprint(JSON.stringify(input.record)),
    fingerprint(JSON.stringify(input.models)),
    restore === undefined ? null : [
      restore.opId,
      fingerprint(JSON.stringify(restore.entry)),
      restore.snapshotKind,
      restore.snapshotText === null ? "\u0000none" : fingerprint(restore.snapshotText),
      restore.confirmDrift,
      restore.driftsFromResult,
    ],
  ];
  return `${PLAN_FINGERPRINT_VERSION}:${digest(JSON.stringify(components))}`;
}

/** The observation facts a plan is derived from, beside the fingerprint inputs. */
export interface PlanInput extends PlanFingerprintInput {
  readonly classified: { readonly state: IntegrationState; readonly reason?: StateReason };
  /**
   * The parsed target document. Whether a managed place is occupied is a fact about the file, not
   * about our record: an overwrite of a key somebody else wrote replaces a value even though no
   * record of ours mentions it.
   */
  readonly parsed: unknown;
}

type PlanOutcome =
  | { readonly kind: "refuse"; readonly reason: RefusalReason }
  | { readonly kind: "noop" }
  | { readonly kind: "change" };

const CHANGE: PlanOutcome = { kind: "change" };
const NOOP: PlanOutcome = { kind: "noop" };
const deny = (reason: RefusalReason): PlanOutcome => ({ kind: "refuse", reason });

function foreignEditOf(input: PlanInput): IntegrationPlanForeignEdit {
  if (input.restore?.driftsFromResult) return "drift";
  if (input.classified.reason === "unowned-key") return "unowned";
  if (input.classified.reason === "foreign-edit") return "foreign-edit";
  return "none";
}

/**
 * Why this operation would refuse, in the writer's own order.
 *
 * The order is not cosmetic. An uninstalled client is reported as not installed rather than as
 * whatever its leftover file happens to classify as, and an unreadable or unparseable file is
 * reported before either, because that is the sequence the writer itself refuses in. A plan that
 * named a different reason than the mutation would name is worse than no plan.
 */
function applyOutcome(input: PlanInput): PlanOutcome {
  if (input.installKind !== "dir") return deny("not_installed");
  if (input.admissionBlocked) return deny("non_loopback");
  if (input.clientId === "droid" && input.contribution?.fragments.length === 0) return deny("unsafe");
  /*
   * Before any file state. The document may be perfectly writable and our block
   * may already be current in it; neither says anything about whether the
   * client reads it, and reporting a change to a file nobody opens is the
   * defect this refusal exists for.
   */
  if (input.ineffectiveWrite !== null) return deny("superseded_store");
  // Overwrite exists precisely to proceed through a conflict the operator has been shown.
  // A Qoder legacy-catalog collision is not on a path overwrite replaces, so it still refuses.
  if (input.classified.state === "conflict" && (input.operation !== "overwrite"
    || qoderLegacyCatalogConflict(input.parsed, input.record, input.contribution))) return deny("conflict");
  if (input.classified.state === "unsafe") return deny("unsafe");
  if (input.classified.state === "current"
    && (input.modelNames ?? "routed") === (input.record?.modelNames ?? "routed")) return NOOP;
  return CHANGE;
}

/**
 * Disable answers a different question, so it asks different ones.
 *
 * It never checks installation or admission: removing what we wrote from a file that still exists
 * is meaningful whether or not the client is installed now, and it emits nothing that admission
 * policy could object to. An absent block is a success that writes nothing rather than a refusal.
 */
function disableOutcome(input: PlanInput): PlanOutcome {
  if (input.classified.state === "absent") return NOOP;
  if (input.classified.state === "conflict") return deny("conflict");
  if (input.classified.state === "unsafe") return deny("unsafe");
  return CHANGE;
}

function restoreOutcome(input: PlanInput): PlanOutcome {
  if (input.restore === undefined) return deny("unsafe");
  if (input.restore.snapshotKind === "expired") return deny("snapshot_expired");
  if (input.restore.driftsFromResult && !input.restore.confirmDrift) return deny("drift_requires_confirm");
  return CHANGE;
}

/**
 * What this operation would do, decided the way the operation itself decides it.
 *
 * Applying one global sequence to all four was wrong: it reported disable as refused on an
 * uninstalled client the writer would have accepted, and it ranked the classifier's unsafe ahead
 * of a conflict that apply reports first. A plan is only useful if it reaches the same verdict,
 * for the same reason, as the mutation it describes.
 */
function outcomeOf(input: PlanInput): PlanOutcome {
  if (input.operation === "restore") return restoreOutcome(input);
  if (input.operation === "disable") return disableOutcome(input);
  return applyOutcome(input);
}


/**
 * The managed places this operation would touch, plus the history it would write.
 *
 * A path that does not canonicalize is omitted rather than guessed at. For a shipped client that
 * cannot happen, and the parity case proves it; what it does cover is a record written by another
 * version, where declining to describe a path is the honest answer and the fixed ownership entry
 * still tells the operator that ownership changes.
 */
function changesOf(input: PlanInput): readonly IntegrationPlanChange[] {
  const changes: IntegrationPlanChange[] = [];
  if (input.operation === "apply" || input.operation === "overwrite") {
    for (const fragment of input.contribution?.fragments ?? []) {
      const path = canonicalSchemaPath(input.clientId, fragment.path);
      if (path === null) continue;
      // Occupied is a fact about the document. Deciding from our own record instead would call an
      // overwrite of somebody else's key an addition, which is the one case overwrite exists for.
      const occupied = readPath(input.parsed, fragment.path) !== undefined;
      changes.push({ kind: occupied ? "replace" : "add", path });
    }
  }
  if (input.operation === "disable") {
    for (const owned of input.record?.fragmentPaths ?? []) {
      const path = canonicalSchemaPath(input.clientId, owned);
      if (path === null) continue;
      changes.push({ kind: "remove", path });
    }
  }
  if (input.operation === "restore") {
    /*
     * An undo replaces the whole document, so what it changes is the difference between the
     * places that are ours now and the places the row recorded as ours before that operation ran.
     *
     * Reading only the prior record got both common undos wrong. Undoing an initial apply has no
     * prior record, so the plan described a change to nothing at all while the undo removed the
     * managed block. Undoing a disable has a prior record and an empty document, so the plan said
     * it would replace paths the file does not currently have.
     *
     * Provenance is still restored rather than re-derived: the prior record is what says which
     * places are ours afterwards. The document only answers whether each of them is there now.
     */
    const prior = new Map<string, readonly string[]>();
    for (const fragment of input.restore?.entry.priorRecord?.fragmentPaths ?? []) {
      const path = canonicalSchemaPath(input.clientId, fragment);
      if (path !== null) prior.set(path, fragment);
    }
    /*
     * A document we could not read says nothing about whether a place is there, and restore does
     * not need it read: eligibility is a question about bytes. Where it cannot be read, each place
     * is reported as a replacement, which is what this list said before any of it was derived.
     */
    const documentKnown = input.parsed !== PARSE_FAILED;
    for (const [path, fragment] of prior) {
      let absent = false;
      if (documentKnown) {
        try {
          absent = readPath(input.parsed, fragment) === undefined;
        } catch (error) {
          /*
           * Restore eligibility is byte-based and does not parse ownership paths.
           * A malformed versioned selector therefore makes this ONE descriptive
           * comparison unknown; it must not make preview execute a different
           * selector, and it must not hide the backup behind an internal error.
           */
          if (!(error instanceof InvalidSelectorError)) throw error;
        }
      }
      changes.push({ kind: absent ? "add" : "replace", path });
    }
    for (const fragment of input.record?.fragmentPaths ?? []) {
      const path = canonicalSchemaPath(input.clientId, fragment);
      if (path === null || prior.has(path)) continue;
      changes.push({ kind: "remove", path });
    }
  }
  changes.push({ kind: "snapshot", path: PLAN_SNAPSHOT_PATH });
  changes.push({ kind: "ownership", path: PLAN_OWNERSHIP_PATH });
  changes.push({ kind: "journal", path: PLAN_JOURNAL_PATH });
  return orderPlanChanges(changes);
}

/**
 * The whole plan, value-free.
 *
 * A refused plan is still worth returning: knowing that undo is blocked because the backup expired
 * is the answer an operator needs, and it carries no more detail than an allowed one.
 */
export function buildMutationPlan(input: PlanInput): IntegrationMutationPlan {
  const outcome = outcomeOf(input);
  return Object.freeze({
    version: 1 as const,
    clientId: input.clientId,
    operation: input.operation,
    state: input.classified.state,
    foreignEdit: foreignEditOf(input),
    // Only a plan that would actually write describes places to write.
    changes: outcome.kind === "change" ? changesOf(input) : Object.freeze([]),
    fingerprint: planFingerprint(input),
    canApply: outcome.kind !== "refuse",
    willChange: outcome.kind === "change",
    ...(outcome.kind === "refuse" ? { refusalReason: outcome.reason } : {}),
    ...(outcome.kind === "refuse" && outcome.reason === "superseded_store" && input.ineffective
      ? {
          supersededReason: input.ineffective.why,
          ...(input.ineffective.emptyDocument === undefined ? {} : { missingStoreDocument: input.ineffective.emptyDocument }),
        }
      : {}),
    ...(input.profileId === undefined ? {} : { profileId: input.profileId }),
  });
}

/**
 * The token a plan carries when observation itself refused.
 *
 * Such a plan never read the state it would have bound, so there is nothing to bind. It is safe
 * for every one of them to share this value because `canApply` is false, and a mutation may only
 * be bound to a plan that could apply.
 */
export const PLAN_UNBOUND_FINGERPRINT = `${PLAN_FINGERPRINT_VERSION}:unbound`;

function unboundPlan(
  clientId: IntegrationClientId,
  operation: IntegrationPlanOperation,
  failure: IntegrationObservationFailure,
  profileId?: number,
): IntegrationMutationPlan {
  return Object.freeze({
    version: 1 as const,
    clientId,
    operation,
    state: failure.state,
    foreignEdit: "none" as const,
    changes: Object.freeze([]),
    fingerprint: PLAN_UNBOUND_FINGERPRINT,
    canApply: false,
    willChange: false,
    refusalReason: failure.reason,
    ...(profileId === undefined ? {} : { profileId }),
  });
}

/** A restore must not recreate a declared store without its client's lock. */
export function restoreStoreDirectoryRefusal(
  input: IntegrationWriteInput,
  configPath: string,
  io: IntegrationIO,
): string | null {
  const declared = INTEGRATION_CLIENTS[input.clientId].currentStore;
  if (!declared?.lockFile) return null;
  let storePath: string;
  try {
    storePath = declared.path(input.env, input.home, io);
  } catch (error) {
    if (error instanceof ClientPathError) return null;
    throw error;
  }
  return configPath === storePath && io.statKind(dirname(storePath)) !== "dir"
    ? "the client store directory is missing; restore will not create it" : null;
}

/**
 * Restore reads a different specification, so it gets its own observation.
 *
 * The writer's undo path never parses and never classifies: it compares the resolved config path
 * against the one the journal row was recorded for, reads the snapshot, and reads the target's
 * BYTES. Routing a preview through the general observation therefore refused an undo of a file
 * that was readable but unparseable, which is the state that most needs restoring, and accepted a
 * row recorded against a previous home, which is the single case path equality exists to refuse.
 */
export function observeRestore(
  input: IntegrationWriteInput,
  opId: string,
  effects: ObservationEffects,
  /**
   * The row a caller already selected, with the store it came from.
   *
   * Aside can hold more than one valid copy of the same operation, so re-resolving here could
   * legitimately pick a different row than the mutation will. The plan would then describe an
   * operation the confirmation was never about. A caller that has resolved one passes it in, and
   * neither side resolves again.
   */
  selectedOperation?: { entry: JournalEntry; store: IntegrationStateStore },
) {
  const store = selectedOperation?.store ?? input.store ?? createIntegrationStateStore();
  let io = input.io ?? defaultIntegrationIO(store);
  const clientId = input.clientId;
  let resolved: ResolvedIntegrationPaths;
  try {
    const context = exportContextOf(input);
    resolved = clientId === "zcode" || !input.resolvedPaths
      ? resolveIntegrationPaths(clientId, input.env, input.home, context, io) : input.resolvedPaths;
    if (clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(resolved.detectDir, context);
  } catch (error) {
    if (!(error instanceof ClientPathError)) throw error;
    return { failed: observationFailure("unsafe", "unsafe", error.message) } as const;
  }
  // Coordinated restore refuses this before it looks at the row at all: an undo will not create
  // the client's home, so a writer-lock client without one has nothing to restore into.
  if (INTEGRATION_CLIENTS[clientId].writerLock && io.statKind(resolved.detectDir) !== "dir") {
    return {
      failed: observationFailure("unsafe", "unsafe", "the client home is missing; restore will not create it"),
    } as const;
  }
  const entry = selectedOperation?.entry ?? store.findOperation(opId);
  if (!entry || entry.clientId !== clientId) {
    return { failed: observationFailure("unsafe", "unsafe", "that operation cannot be undone") } as const;
  }
  const configPath = entry.configPath;
  /*
   * An undo acts on the path the operation was journaled against. A row recorded for one home must
   * never be allowed to rewrite a file in another — but a client may legally have written more than
   * one file, so the test is whether this client still names that location, not whether it is the
   * config file. The answer also carries the document shape those bytes are in.
   */
  const rowTarget = declaredIntegrationTarget({
    clientId, configPath, resolvedConfigPath: resolved.configPath, env: input.env, home: input.home, io,
  });
  if (rowTarget === null) {
    return {
      failed: observationFailure("conflict", "conflict", "that operation was recorded for a different location"),
    } as const;
  }
  const directoryRefusal = restoreStoreDirectoryRefusal(input, configPath, io);
  if (directoryRefusal !== null) {
    return { failed: observationFailure("unsafe", "unsafe", directoryRefusal) } as const;
  }
  /*
   * A legal historical path is not enough. Another candidate can already own
   * the single record, and committing this row's prior record would orphan the
   * block that candidate still holds. Direct restore asks the same question.
   */
  const currentOwner = store.readRecords()[clientId] ?? null;
  const collision = restoreOwnershipCollision({
    clientId,
    journaledPath: configPath,
    currentPath: currentOwner && currentOwner.clientId === clientId ? currentOwner.configPath : null,
    env: input.env,
    home: input.home,
  });
  if (collision !== null) {
    return { failed: observationFailure("conflict", "conflict", collision) } as const;
  }
  if (clientId === "cline") {
    try { io = createClineIO(io, configPath, store, effects.recover); }
    catch (error) {
      if (!(error instanceof ClineTransactionError)) throw error;
      return { failed: { ...observationFailure("unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const;
    }
  }
  const snapshot = store.readSnapshot(entry);
  /*
   * Expiry is decided before the target is read, exactly as the writer decides it. Reading first
   * let an expired backup over an unreadable file report the file as the problem, when the answer
   * the operator needs is that the backup is gone.
   */
  if (snapshot.kind === "expired") {
    return { failed: observationFailure("snapshot_expired", "absent", "that backup has expired") } as const;
  }
  const target = loadTarget(io, configPath);
  if (!target.ok) {
    return { failed: observationFailure("unsafe", "unsafe", "the target cannot be read safely") } as const;
  }
  const before = target.before;
  return {
    failed: undefined,
    clientId,
    configPath,
    format: rowTarget.format,
    detectDir: resolved.detectDir,
    installKind: io.statKind(resolved.detectDir),
    entry,
    snapshotKind: snapshot.kind,
    snapshotText: snapshot.kind === "stored" ? snapshot.text : null,
    before,
    // Bytes only. Parsing here is exactly what must not happen.
    driftsFromResult: !matchesOperationResult(entry, before),
  } as const;
}

export interface PreviewRequest {
  readonly operation: IntegrationPlanOperation;
  /** Required for restore; names the journalled operation being undone. */
  readonly opId?: string;
  readonly confirmDrift?: boolean;
  readonly profileId?: number;
  /** A row and store the caller already selected, so neither side resolves it twice. */
  readonly resolved?: { entry: JournalEntry; store: IntegrationStateStore };
}

/**
 * Plan an operation without performing it.
 *
 * Observation runs with both write-capable effects off, so this path prunes nothing, recovers
 * nothing, takes no lock and enters no mutation flight. Everything it reads is a read: the target
 * file, the ownership records, and for restore the journal row and its snapshot.
 */
export function previewIntegration(input: IntegrationWriteInput, request: PreviewRequest): IntegrationMutationPlan {
  // Restore never reaches the general observation, because the writer's undo path never parses
  // or classifies and a preview that did would answer a different question.
  if (request.operation === "restore") return previewRestore(input, request);
  const observed = observeIntegration(input, { maintenance: false, recover: false }, request.operation);
  if (observed.failed) return unboundPlan(input.clientId, request.operation, observed.failed, request.profileId);

  const shared = {
    operation: request.operation,
    clientId: observed.clientId,
    configPath: observed.configPath,
    detectDir: observed.detectDir,
    installKind: observed.io.statKind(observed.detectDir),
    // Loopback-only clients cannot carry the admission header a non-loopback bind requires.
    admissionBlocked: isLoopbackOnly(observed.clientId) && shouldInjectApiAuthHeader(input.config),
    ineffectiveWrite: observed.ineffectiveWrite,
    ineffective: observed.target.ineffective,
    before: observed.before,
    contribution: observed.contribution,
    record: observed.record,
    requestedModelNames: input.modelNames,
    modelNames: observed.modelNames,
    models: input.models,
    classified: observed.classified,
    parsed: observed.parsed,
    ...(request.profileId === undefined ? {} : { profileId: request.profileId }),
  };

  return buildMutationPlan(shared);
}

/**
 * Which places are ours in the file this undo would rewrite, read the same way the general
 * observation reads them.
 *
 * Read from the store bound to the target being rewritten, never from the store a historical row
 * was selected out of. Aside keeps a copy of an operation in the root store while the profile's
 * own store holds the ownership for its file, so asking the selected row's store would have
 * described the wrong file's ownership. The selected store stays what it is for: the row and its
 * snapshot. A record written for another location grants nothing here either, which is the same
 * rule the writer applies.
 */
function currentRecordFor(
  input: IntegrationWriteInput,
  clientId: IntegrationClientId,
  configPath: string,
): OwnershipRecord | null {
  const store = input.store ?? createIntegrationStateStore();
  const stored = store.readRecords()[clientId] ?? null;
  return stored && stored.clientId === clientId && stored.configPath === configPath ? stored : null;
}

/**
 * Plan an undo the way the writer performs one.
 *
 * State is derived from bytes alone: a missing target is absent, a target that no longer matches
 * the row's recorded result is a conflict, and anything else is current. Admission is not asked
 * about, because restore emits nothing an admission policy could object to and the writer does not
 * ask either.
 */
function previewRestore(input: IntegrationWriteInput, request: PreviewRequest): IntegrationMutationPlan {
  const refusal = (message: string): IntegrationMutationPlan =>
    unboundPlan(input.clientId, "restore", { reason: "unsafe", state: "unsafe", message }, request.profileId);
  if (request.opId === undefined) return refusal("that operation cannot be undone");

  const observed = observeRestore(
    input,
    request.opId,
    { maintenance: false, recover: false },
    request.resolved,
  );
  if (observed.failed) return unboundPlan(input.clientId, "restore", observed.failed, request.profileId);

  /*
   * Drift decides first. A row that recorded a file and now finds none has drifted, and calling
   * that absent would report a missing file as an ordinary undo while the writer refuses it
   * pending confirmation. Absent is only honest when the recorded result was absence too.
   */
  const state: IntegrationState = observed.driftsFromResult
    ? "conflict"
    : observed.before === null ? "absent" : "current";

  return buildMutationPlan({
    operation: "restore",
    clientId: observed.clientId,
    configPath: observed.configPath,
    detectDir: observed.detectDir,
    installKind: observed.installKind,
    admissionBlocked: false,
    /*
     * Undo puts back bytes this project already wrote to this file. Whether the
     * client still reads the file does not change whether those bytes may be
     * restored, and refusing here would strand a user on a state they asked to
     * leave.
     */
    ineffectiveWrite: null,
    before: observed.before,
    contribution: null,
    // Descriptive, never decisive. The record says which places are ours now and the document
    // says which of them the file holds, so the change list can distinguish a place this undo
    // adds back from one it replaces and one it takes away. Neither is allowed to refuse: an
    // unreadable document is reported as PARSE_FAILED and leaves every place a replacement, and
    // restore eligibility stays the byte comparison it was.
    record: currentRecordFor(input, observed.clientId, observed.configPath),
    models: input.models,
    classified: { state },
    parsed: observed.before === null
      ? {}
      : observed.clientId === "cline"
        ? parseClineDocument(observed.before)
        : parseConfig(observed.before, observed.format, EXPORT_CLIENTS[observed.clientId].jsonc ? { jsonc: true } : undefined),
    restore: {
      opId: observed.entry.opId,
      entry: observed.entry,
      snapshotKind: observed.snapshotKind,
      snapshotText: observed.snapshotText,
      confirmDrift: request.confirmDrift === true,
      driftsFromResult: observed.driftsFromResult,
    },
    ...(request.profileId === undefined ? {} : { profileId: request.profileId }),
  });
}

/**
 * What a mutation is asked to do. Declared here because the observation below consumes it and the
 * planner must not depend on the writer; the writer re-exports it, so callers are unaffected.
 */
export interface IntegrationWriteInput {
  modelNames?: ExportModelNames;
  clientId: IntegrationClientId;
  models: readonly ExportModel[];
  config: OcxConfig;
  port: number;
  /** Explicit Droid-only defaults; omitted means retain matching owned rows. */
  droidReasoningDefaults?: Record<string, string>;
  env?: NodeJS.ProcessEnv;
  home?: string;
  store?: IntegrationStateStore;
  io?: IntegrationIO;
  /** Frozen once by the async coordinator; synchronous callers may omit it. */
  resolvedPaths?: ResolvedIntegrationPaths;
}

/** A refusal in the planner's own vocabulary, so observation does not depend on the writer's result type. */
export interface IntegrationObservationFailure {
  readonly reason: RefusalReason;
  readonly state: IntegrationState;
  readonly message: string;
  readonly snapshotPath?: string;
  /** A Cline transaction left residue that only a mutation may clear. */
  readonly residual?: boolean;
}

function observationFailure(
  reason: RefusalReason,
  state: IntegrationState,
  message: string,
  snapshotPath?: string,
): IntegrationObservationFailure {
  return { reason, state, message, ...(snapshotPath ? { snapshotPath } : {}) };
}

/**
 * What preview and mutation are allowed to touch while looking.
 *
 * Both are false for a preview and both are true for a mutation, and neither defaults, because the
 * difference is the whole safety argument. `maintenance` runs pending snapshot pruning, which
 * writes; `recover` lets the Cline adapter repair a pending transaction, which also writes. A
 * preview that quietly inherited either would be a mutation wearing a read's name.
 */
export interface ObservationEffects {
  readonly maintenance: boolean;
  readonly recover: boolean;
}

/**
 * Detect, gate, read, parse and classify, once, for both preview and mutation.
 *
 * Extracted from the writer so a plan and the mutation it authorizes rest on the same
 * classification rather than two independent reads that can disagree. The ordering of refusals is
 * load-bearing and is preserved exactly as the writer had it.
 */
export function observeIntegration(
  input: IntegrationWriteInput,
  effects: ObservationEffects,
  operation: Exclude<IntegrationPlanOperation, "restore">,
) {
  const store = input.store ?? createIntegrationStateStore();
  let io = input.io ?? defaultIntegrationIO(store);
  const clientId = input.clientId;
  const spec = INTEGRATION_CLIENTS[clientId];
  const exportSpec = EXPORT_CLIENTS[clientId];
  /*
   * Resolution itself can refuse: a relative OPENCLAW_* selector is rejected
   * because we cannot know the gateway's working directory. That is a refusal
   * about the user's configuration, not an internal fault, so it must not
   * escape as an exception — the collection route would answer 500 for the
   * whole Integrations page because one client is misconfigured.
   */
  let configPath: string;
  let detectDir: string;
  let effective: IntegrationTarget;
  let stored: OwnershipRecord | null;
  try {
    /*
     * Resolve the PAIR, never one half.
     *
     * The coordinated path hands us a frozen pair, but applyIntegration,
     * refreshIntegration and disableIntegration are public and may be called
     * without one. Resolving configPath here and detectDir separately later let
     * an Aside account switch land between the two, so a direct apply could
     * verify account 1 was installed and then write account 0's catalog.
     */
    const context = exportContextOf(input);
    const resolved = clientId === "zcode" || !input.resolvedPaths
      ? resolveIntegrationPaths(clientId, input.env, input.home, context, io) : input.resolvedPaths;
    if (clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(resolved.detectDir, context);
    detectDir = resolved.detectDir;
    if (clientId === "cline") io = createClineIO(io, resolved.configPath, store, effects.recover);
    /*
     * A record proves ownership of the file it was written FOR, and it is also
     * one of the inputs the target is chosen from: a block we already wrote to
     * the config file keeps this operation on that file, so disable removes what
     * we wrote from where we wrote it. Matching by path happens after the
     * target is known, because that is the path it has to match.
     */
    stored = store.readRecords()[clientId] ?? null;
    const recordedPath = boundIntegrationConfigPath({
      clientId, record: stored, resolvedPath: resolved.configPath,
      statKind: io.statKind, env: input.env, home: input.home,
    });
    /*
     * Inside the same guard as resolution, because this resolver can refuse the
     * same way: the store is named by a client env var, and a relative one is a
     * misconfiguration to report rather than an exception to leak through the
     * collection route.
     */
    effective = resolveIntegrationTarget({
      clientId, configPath: recordedPath, io, record: stored, env: input.env, home: input.home, resolvedPaths: resolved,
    });
    configPath = effective.configPath;
    if (effective.pathError && operation !== "disable") {
      return { failed: observationFailure("unsafe", "unsafe", effective.pathError) } as const;
    }
  } catch (error) {
    if (error instanceof ClineTransactionError) {
      return { failed: { ...observationFailure("unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const;
    }
    if (!(error instanceof ClientPathError)) throw error;
    return { failed: observationFailure("unsafe", "unsafe", error.message) } as const;
  }
  // Pruning writes, so only a mutation may perform it. Preview reports the state it finds.
  if (clientId === "kilo" && operation !== "disable") {
    const candidates = inspectKiloCandidates({ io, selectedPath: configPath, env: input.env, home: input.home });
    if (candidates.kind !== "ok") return { failed: candidates.kind === "conflict"
      ? observationFailure("conflict", "conflict", `${configPath} cannot be managed while ${candidates.paths.join(", ")} also defines provider.opencodex`)
      : observationFailure("unsafe", "unsafe", `${candidates.path} cannot be inspected safely (${candidates.why})`),
    } as const;
  }
  if (effects.maintenance) store.retryPendingPrunes();

  const loaded = loadTarget(io, configPath);
  if (!loaded.ok) {
    return {
      failed: observationFailure("unsafe", "unsafe",
        loaded.why === "read-failed"
          ? `${configPath} exists but could not be read`
          : `${configPath} is not a regular file`),
    } as const;
  }
  const before = loaded.before;
  const parsed = clientId === "cline"
    ? parseClineDocument(before)
    : parseConfig(before, effective.format, exportSpec.jsonc ? { jsonc: true } : undefined);
  if (parsed === PARSE_FAILED) {
    return { failed: observationFailure("unsafe", "unsafe",
      `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const;
  }
  /*
   * The shape the TARGET's reader understands, which is not always the
   * client's config format: a client that moved its providers to another file
   * reads a different document there, and a write in the config file's shape
   * would be as unread as a write to the config file itself.
   */
  // A record proves ownership of the file it was written FOR. Matching only by
  // client id let a record for one home authorize a write to another whose
  // bytes happened to hash the same — which deleted a config we never touched.
  const record = stored && stored.clientId === clientId && stored.configPath === configPath
    ? stored
    : null;
  if (operation !== "disable") {
    const refusal = exportSpec.validateApply?.({ ...exportContextOf(input), document: parsed });
    if (refusal) return { failed: observationFailure("unsafe", "unsafe", refusal) } as const;
  }
  let contribution: ManagedContribution;
  let modelNames: ExportModelNames;
  try {
    modelNames = resolveModelNames(clientId, input.modelNames, record?.modelNames);
    contribution = buildIntegrationContribution(input, effective, parsed, record);
  } catch (error) {
    if (!(error instanceof UnrepresentableSelectorError)) throw error;
    return { failed: observationFailure("unsafe", "unsafe", error.message) } as const;
  }
  if (clientId === "droid" && input.models.length > 0 && contribution.fragments.length === 0 && !record) {
    return { failed: observationFailure("unsafe", "unsafe", "Factory Droid has no addressable models in the selected catalog") } as const;
  }
  // `configPath`/`clientId` are load-bearing, not decoration: a record proves
  // ownership of ONE file, and the writer mutates whatever path resolves NOW.
  // Without them a record written for another home directory would grant
  // ownership here and disable would delete fragments it never wrote.
  const classified = classifyIntegration({
    fileText: before, fileIsRegular: true, parsed, record, contribution, configPath, clientId,
    format: effective.format, sourcePreservingYaml: effective.sourcePreservingYaml !== null,
  });
  if (clientId === "droid" && record && (classified.state === "current" || classified.state === "stale")) {
    try { assertDroidRecordedSettingsUnambiguous(detectDir, parsed, record); }
    catch (error) {
      if (!(error instanceof ClientPathError)) throw error;
      return { failed: observationFailure("unsafe", "unsafe", error.message) } as const;
    }
  }
  return {
    failed: undefined, store, io, clientId, spec, exportSpec, target: effective, configPath, detectDir,
    /*
     * One token for the plan, because the location alone is not the input: a
     * store whose schema stops being one we recognise changes the answer while
     * its path stays exactly the same.
     */
    ineffectiveWrite: effective.ineffective === null
      ? null
      : `${effective.ineffective.why}\u0000${effective.ineffective.store}`,
    before, parsed, contribution, record, classified, modelNames,
  } as const;
}
