// Generated from types/*.ts — do not edit.
// Regenerate with: npm run generate:typescript

/**
 * Changeset Channel Actions — Mutations of an `ahp-changeset:` channel's
 * state.
 *
 * @module channels-changeset/actions
 */

import { ActionType } from '../common/actions.js';
import type { ErrorInfo } from '../common/state.js';
import type { ChangesetFile, ChangesetOperation } from './state.js';
import { ChangesetStatus } from './state.js';
import type { ChangesetOperationStatus } from './state.js';

// ─── Changeset Actions ───────────────────────────────────────────────────────

/**
 * The {@link ChangesetState.status} for this changeset transitioned (e.g.
 * `computing → ready`). The error payload is set together with `status`
 * whenever it transitions to {@link ChangesetStatus.Error | Error}.
 *
 * @category Changeset Actions
 * @version 2
 */
export interface ChangesetStatusChangedAction {
  type: ActionType.ChangesetStatusChanged;
  /** New computation lifecycle status. */
  status: ChangesetStatus;
  /** Cause when `status === ChangesetStatus.Error`; otherwise omitted. */
  error?: ErrorInfo;
}

/**
 * Upsert a {@link ChangesetFile} in the changeset — adds a new entry, or
 * replaces an existing one identified by {@link ChangesetFile.id}.
 *
 * @category Changeset Actions
 * @version 2
 */
export interface ChangesetFileSetAction {
  type: ActionType.ChangesetFileSet;
  /** The new or replacement file entry. */
  file: ChangesetFile;
}

/**
 * Remove a {@link ChangesetFile} from the changeset by its id.
 *
 * Typically dispatched when a file is reverted, staged out, or otherwise
 * no longer in scope (e.g. a renamed file is replaced by a new entry).
 *
 * @category Changeset Actions
 * @version 2
 */
export interface ChangesetFileRemovedAction {
  type: ActionType.ChangesetFileRemoved;
  /** The {@link ChangesetFile.id} of the file to remove. */
  fileId: string;
}

/**
 * Set the {@link ChangesetFile.reviewed} flag for one or more files — the
 * GitHub-style "Viewed" toggle, applied in a single batch.
 *
 * Targets files by their {@link ChangesetFile.id}. Ids in {@link files} that
 * do not match a file currently present in the changeset are ignored; if none
 * match, the action is a no-op. Only the {@link ChangesetFile.reviewed} field
 * of each matched file is affected; the files' {@link ChangesetFile.edit | edit}
 * and {@link ChangesetFile._meta | _meta} are left untouched.
 *
 * Only meaningful on a changeset that advertises
 * {@link ChangesetCapabilities.review}. Unlike every other `changeset/*` action
 * this one is **client-dispatchable**: a reviewer toggles review state directly,
 * applying it optimistically through the write-ahead reducer and letting the
 * server echo it back on the normal `action` envelope stream. The server MAY
 * also originate it (e.g. an agent marking its own output reviewed).
 *
 * There is no protocol-level content version, so review is not reset
 * automatically when a file's contents change under a stable id. The server,
 * which is the authority on what changed, resets review explicitly — either by
 * re-emitting the file without `reviewed: true`, or by dispatching this action
 * with `reviewed: false`.
 *
 * @category Changeset Actions
 * @version 1
 * @clientDispatchable
 */
export interface ChangesetFilesReviewChangedAction {
  type: ActionType.ChangesetFilesReviewChanged;
  /** The {@link ChangesetFile.id | ids} of the files whose review state changed. */
  files: string[];
  /** New review state applied to every listed file: `true` once reviewed, `false` to clear it. */
  reviewed: boolean;
}

/**
 * The changeset's full content changed. Full replacement semantics: `files`
 * replaces the previous file list, and `operations`, when present, replaces
 * the previous operation list.
 *
 * Producers SHOULD use this action for initial snapshots and bulk refreshes;
 * use {@link ChangesetFileSetAction}, {@link ChangesetFileRemovedAction}, and
 * {@link ChangesetOperationsChangedAction} for incremental updates.
 *
 * @category Changeset Actions
 * @version 4
 */
export interface ChangesetContentChangedAction {
  type: ActionType.ChangesetContentChanged;
  /** Full replacement file list. */
  files: ChangesetFile[];
  /** Full replacement operation list. Omit when operations are unchanged. */
  operations?: ChangesetOperation[];
}

/**
 * The set of operations available on this changeset changed. Full
 * replacement semantics: `operations` replaces the previous list (or
 * removes it entirely when `operations` is `undefined`).
 *
 * @category Changeset Actions
 * @version 2
 */
export interface ChangesetOperationsChangedAction {
  type: ActionType.ChangesetOperationsChanged;
  /** Updated operation list. Pass `undefined` to clear all operations. */
  operations: ChangesetOperation[] | undefined;
}

/**
 * The {@link ChangesetOperation.status} for a single operation transitioned
 * (e.g. `idle → running → idle`, or `running → error`). The error payload
 * is set together with `status` whenever it transitions to
 * {@link ChangesetOperationStatus.Error | Error}, and cleared on any other
 * transition.
 *
 * Targets one operation by its {@link ChangesetOperation.id}. If no
 * operation with that id is currently present in the changeset, the action
 * is a no-op. Use {@link ChangesetOperationsChangedAction} to add, remove,
 * or otherwise replace the operation list itself.
 *
 * @category Changeset Actions
 * @version 3
 */
export interface ChangesetOperationStatusChangedAction {
  type: ActionType.ChangesetOperationStatusChanged;
  /** The {@link ChangesetOperation.id} whose status changed. */
  operationId: string;
  /** New execution status. */
  status: ChangesetOperationStatus;
  /** Cause when `status === ChangesetOperationStatus.Error`; otherwise omitted. */
  error?: ErrorInfo;
}

/**
 * Drop every file from the changeset.
 *
 * Two cases use this:
 * 1. The underlying source moved (branch switched, fork point invalidated,
 *    …) and the server is recomputing from scratch — subsequent
 *    {@link ChangesetFileSetAction} entries will repopulate it.
 * 2. The owning session has ended and the URI is becoming
 *    un-subscribable — the server will unsubscribe all clients shortly
 *    after dispatching this action.
 *
 * Clients SHOULD release any references on receipt and SHOULD NOT
 * distinguish the two cases from the action alone — instead, react to
 * the corresponding session-level lifecycle signal (e.g.
 * `root/sessionRemoved`) for the "going away" case.
 *
 * @category Changeset Actions
 * @version 2
 */
export interface ChangesetClearedAction {
  type: ActionType.ChangesetCleared;
}