@moretea-labs/forge 1.7.1 → 1.8.0

package/src/cli/controller/context/types.ts

@@ -3,7 +3,7 @@ import type { CodeGraphIndexMetadata, CodeGraphNodeSummary, CodeGraphReadProvide
 import type { queryCodeGraphReadProvider, queryCodeGraphReadProviderAsync } from '../../../runtime/context/codegraph-read-provider';
 import type { MaterializedSourceSnippet } from './source-materializer';
 
-export const CONTEXT_PACK_SCHEMA_VERSION = 10;
+export const CONTEXT_PACK_SCHEMA_VERSION = 11;
 export type StructuralContextMode = 'off' | 'auto' | 'required';
 export type ControllerContextRetrievalMode = 'implementation' | 'plan' | 'debug' | 'review';
 export type ControllerEvidenceReadinessStatus = 'ready' | 'degraded' | 'insufficient';
@@ -113,7 +113,10 @@ export interface ControllerContextPackProjection {
     policyDeniedFiles: number;
     skippedLargeFiles: number;
     skippedBinaryFiles: number;
+    /** Raw lexical/discovery result cap was reached. This may be harmless when exact-known files were fully materialized. */
     truncated: boolean;
+    /** True only when truncation can hide material source evidence. */
+    evidenceTruncated: boolean;
     cacheHit: boolean;
   };
   instructionContext: {
@@ -233,7 +236,10 @@ export interface ControllerContextPackProjection {
       policyDeniedFiles: number;
       largeFiles: number;
       binaryFiles: number;
+      /** Raw result cap signal retained for diagnostics. */
       searchTruncated: boolean;
+      /** Whether the raw cap actually omitted material evidence. */
+      evidenceTruncated: boolean;
       structuralTruncated: boolean;
     };
     materialization: { completeFiles: number; symbols: number; fallbackWindows: number };

package/src/cli/controller/context-pack.ts

@@ -237,6 +237,7 @@ export function buildControllerContextPack(
         limit: Math.min(Math.max(maxFiles, 4), 12),
         maxNodes: Math.min(Math.max(maxFiles * 5, 20), 60),
         maxDepth: 2,
+        ...(structuralMode === 'required' ? { refresh: 'if_stale' as const } : {}),
       });
       const graph = structuralResult(structural);
       const metadata = structural.metadata
@@ -810,6 +811,22 @@ export function buildControllerContextPack(
     .filter((file) => file.reasons.includes("explicit-known-path"))
     .map((file) => file.path);
   const materializedExactKnownSet = new Set(materializedExactKnownPaths);
+  const omittedCandidateCount = rankedCandidates.filter((entry) => !inspectedSet.has(entry.path)).length;
+  const exactKnownFilesFullyMaterialized = scopedExactKnownFileSearch
+    && exactKnownFiles.length > 0
+    && exactKnownFiles.every((path) => files.some((file) => file.path === path
+      && file.snippets.some((snippet) => snippet.materialization === "complete_file" && !snippet.truncated)));
+  // `search.truncated` records that lexical hit collection reached a result cap.
+  // That is not automatically an evidence gap. For an exact-known implementation
+  // scope, if every requested file is fully materialized and there are no omitted
+  // or denied candidates, the cap only discarded redundant hit lines.
+  const evidenceSearchTruncated = searchTruncated
+    && !(exactKnownFilesFullyMaterialized
+      && omittedCandidateCount === 0
+      && policyDeniedFiles === 0
+      && deniedPaths.length === 0
+      && skippedLargeFiles === 0
+      && skippedBinaryFiles === 0);
   const unresolvedRelationships = Array.from(new Set([
     ...coverageGaps,
     ...expansionSignals,
@@ -819,7 +836,7 @@ export function buildControllerContextPack(
   const readinessReasonCodes = Array.from(new Set([
     ...(files.length === 0 ? ["raw_source_unavailable"] : []),
     ...(rawSnippetTruncated ? ["raw_source_truncated"] : []),
-    ...(searchTruncated ? ["retrieval_truncated"] : []),
+    ...(evidenceSearchTruncated ? ["retrieval_truncated"] : []),
     ...(structuralMode === "required" && !structuralContext.requiredSatisfied ? ["required_structural_context_unsatisfied"] : []),
     ...(structuralContext.status === "stale" ? ["structural_context_stale"] : []),
     ...(structuralContext.status === "unavailable" || structuralContext.status === "degraded" ? ["structural_provider_degraded"] : []),
@@ -853,8 +870,8 @@ export function buildControllerContextPack(
     },
     semantic: { status: "not_requested", reasonCodes: ["semantic_navigation_not_requested"] },
     retrieval: {
-      searchTruncated,
-      omittedCandidateCount: rankedCandidates.filter((entry) => !inspectedSet.has(entry.path)).length,
+      searchTruncated: evidenceSearchTruncated,
+      omittedCandidateCount,
       policyDeniedCandidateCount: policyDeniedFiles + deniedPaths.length,
       likelyRelatedNotInspectedCount: likelyRelatedNotInspected.length,
     },
@@ -895,6 +912,7 @@ export function buildControllerContextPack(
       skippedLargeFiles,
       skippedBinaryFiles,
       truncated: searchTruncated,
+      evidenceTruncated: evidenceSearchTruncated,
       cacheHit: lexicalCacheHit,
     },
     instructionContext,
@@ -920,6 +938,7 @@ export function buildControllerContextPack(
         largeFiles: skippedLargeFiles,
         binaryFiles: skippedBinaryFiles,
         searchTruncated,
+        evidenceTruncated: evidenceSearchTruncated,
         structuralTruncated: structuralContext.truncated,
       },
       materialization: {
@@ -1104,6 +1123,7 @@ export async function buildControllerContextPackAsync(
     limit: Math.min(Math.max(maxFiles, 4), 12),
     maxNodes: Math.min(Math.max(maxFiles * 5, 20), 60),
     maxDepth: 2,
+    ...(structuralMode === 'required' ? { refresh: 'if_stale' as const } : {}),
   };
   const structuralCacheKey = JSON.stringify({ queryRoot: structuralIndexRoot, request: structuralRequest });
   const sessionCache = getRepositoryReadSessionCache(repoRoot, options.session);

package/src/cli/controller/issue-store.ts

@@ -30,7 +30,7 @@ import { completionEvidenceComplete, executionScopesConflict, taskExecutionPolic
 import { resolveCompletionTargetBranch } from './completion-target';
 import { listControllerChecks } from './check-runner';
 import { normalizeCheckIds } from '../../runtime/control-plane/facade/check-normalization';
-import { getWorkContract } from '../../runtime/control-plane/facade/work-contract-store';
+import { getWorkContract } from '../../../packages/kernel/work/api/index';
 import { projectControllerTaskFromWork } from '../../runtime/control-plane/facade/work-task-projection';
 import type { WorkContract } from '../../runtime/control-plane/facade/types';
 import { resolveRepoPreferredControllerHome } from '../repositories/controller-home';

package/src/cli/controller/systemd-user.ts

@@ -0,0 +1,110 @@
+import { spawnSync, type SpawnSyncReturns } from 'child_process';
+import { mkdirSync, renameSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+
+export interface SystemdUserUnitInput {
+  description?: string;
+  executable: string;
+  args: string[];
+  environment: Record<string, string>;
+  restart?: 'no' | 'on-failure' | 'always';
+  restartSec?: number;
+}
+
+function atomicWrite(path: string, content: string, mode = 0o644): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, content, { encoding: 'utf8', mode });
+  renameSync(temporary, path);
+}
+
+export function systemdEscape(value: string): string {
+  return `"${value.replaceAll('%', '%%').replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+
+export function renderSystemdUserUnit(input: SystemdUserUnitInput): string {
+  const environment = Object.entries(input.environment)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, value]) => `Environment=${systemdEscape(`${key}=${value}`)}`)
+    .join('\n');
+  return [
+    '[Unit]',
+    `Description=${input.description ?? 'Forge service'}`,
+    'After=network-online.target',
+    '',
+    '[Service]',
+    'Type=simple',
+    `ExecStart=${[input.executable, ...input.args].map(systemdEscape).join(' ')}`,
+    ...(environment ? [environment] : []),
+    `Restart=${input.restart ?? 'on-failure'}`,
+    `RestartSec=${Math.max(1, Math.trunc(input.restartSec ?? 5))}`,
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+function commandSucceeded(command: string, args: string[], env: NodeJS.ProcessEnv): SpawnSyncReturns<string> {
+  return spawnSync(command, args, { encoding: 'utf8', env, timeout: 30_000 });
+}
+
+export function systemdUserAvailable(env: NodeJS.ProcessEnv = process.env): boolean {
+  return commandSucceeded('systemctl', ['--user', 'show-environment'], env).status === 0;
+}
+
+export function systemdUserUnitName(label: string): string {
+  const normalized = label.trim();
+  if (!normalized) throw new Error('SYSTEMD_USER_UNIT_LABEL_REQUIRED');
+  return normalized.endsWith('.service') ? normalized : `${normalized}.service`;
+}
+
+export function systemdUserUnitPath(unitName: string, env: NodeJS.ProcessEnv = process.env): string {
+  return join(env.HOME ?? homedir(), '.config', 'systemd', 'user', systemdUserUnitName(unitName));
+}
+
+export function systemdUserInstallCommands(unitName: string): string[][] {
+  const unit = systemdUserUnitName(unitName);
+  return [
+    ['--user', 'daemon-reload'],
+    ['--user', 'enable', unit],
+    ['--user', 'restart', unit],
+  ];
+}
+
+export function writeSystemdUserUnit(
+  unitName: string,
+  input: SystemdUserUnitInput,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const unitPath = systemdUserUnitPath(unitName, env);
+  atomicWrite(unitPath, renderSystemdUserUnit(input), 0o644);
+  return unitPath;
+}
+
+export function installSystemdUserUnit(input: {
+  unitName: string;
+  unit: SystemdUserUnitInput;
+  env?: NodeJS.ProcessEnv;
+  errorPrefix?: string;
+}): string {
+  const env = input.env ?? process.env;
+  const unit = systemdUserUnitName(input.unitName);
+  const unitPath = writeSystemdUserUnit(unit, input.unit, env);
+  for (const args of systemdUserInstallCommands(unit)) {
+    const result = commandSucceeded('systemctl', args, env);
+    if (result.status !== 0) {
+      const prefix = input.errorPrefix?.trim() || 'SYSTEMD_USER_INSTALL_FAILED';
+      throw new Error(`${prefix}: systemctl ${args.join(' ')}: ${(result.stderr || result.stdout || '').trim()}`);
+    }
+  }
+  return unitPath;
+}
+
+export function systemdUserServicePid(unitName: string, env: NodeJS.ProcessEnv = process.env): number | undefined {
+  const result = commandSucceeded('systemctl', ['--user', 'show', '--property', 'MainPID', '--value', systemdUserUnitName(unitName)], env);
+  if (result.status !== 0) return undefined;
+  const pid = Number(result.stdout.trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}

package/src/cli/controller/types.ts

@@ -1,4 +1,14 @@
 import type { ProcessCheckReceiptEvidence } from '../../runtime/evidence/process-check-receipt';
+import type { CompletionMaintenanceWarning, CompletionReceipt, CompletionResourceBlocker } from '../../../packages/kernel/work/api/index';
+export type {
+  CompletionMaintenanceWarning,
+  CompletionReceipt,
+  CompletionReceiptCleanupStatus,
+  CompletionReceiptDeliveryKind,
+  CompletionReceiptDeliveryStatus,
+  CompletionReceiptSource,
+  CompletionResourceBlocker,
+} from '../../../packages/kernel/work/api/index';
 
 export type IssueKind = 'bug' | 'feature' | 'governance' | 'investigation';
 export type IssueStatus = 'backlog' | 'analysis' | 'planned' | 'launch_blocked' | 'in_progress' | 'review' | 'done' | 'cancelled';
@@ -59,76 +69,6 @@ export interface CleanupEvidence {
   recordedAt: string;
 }
 
-export type CompletionReceiptSource =
-  | 'direct_edit'
-  | 'controller_work'
-  | 'isolated_agent_run'
-  | 'workspace_run'
-  | 'remote_no_change_execution';
-
-export type CompletionReceiptDeliveryKind = 'commit' | 'no_change' | 'remote' | 'superseded';
-export type CompletionReceiptDeliveryStatus = 'integrated' | 'blocked';
-export type CompletionReceiptCleanupStatus = 'complete' | 'maintenance_warning' | 'blocked';
-
-export interface CompletionMaintenanceWarning {
-  code:
-    | 'worktree_cleanup_failed'
-    | 'branch_cleanup_failed'
-    | 'edit_session_backup_retained'
-    | 'cleanup_retained_by_request';
-  message: string;
-  resourceKind?: 'worktree' | 'branch' | 'edit_session' | 'lease' | 'process' | 'workspace';
-  resourceId?: string;
-  recordedAt: string;
-}
-
-export interface CompletionResourceBlocker {
-  code:
-    | 'unintegrated_changes'
-    | 'active_write_process'
-    | 'unknown_resource_ownership'
-    | 'dirty_owned_paths'
-    | 'edit_session_open'
-    | 'lease_active'
-    | 'run_not_terminal'
-    | 'target_revision_unreachable';
-  message: string;
-  resourceKind?: 'worktree' | 'branch' | 'edit_session' | 'lease' | 'process' | 'workspace';
-  resourceId?: string;
-  recordedAt: string;
-}
-
-export interface CompletionReceipt {
-  schemaVersion: 1;
-  receiptId: string;
-  source: CompletionReceiptSource;
-  issueId: string;
-  taskId: string;
-  runId?: string;
-  workId?: string;
-  editSessionId?: string;
-  targetBranch: string;
-  targetRevision: string;
-  sourceRevision?: string;
-  baseRevision?: string;
-  changedPaths: string[];
-  delivery: {
-    kind: CompletionReceiptDeliveryKind;
-    status: CompletionReceiptDeliveryStatus;
-    strategy: 'edit_session_commit' | 'already_integrated' | 'no_change' | 'remote';
-    reachable: boolean;
-    recordedAt: string;
-  };
-  cleanup: {
-    status: CompletionReceiptCleanupStatus;
-    warnings: CompletionMaintenanceWarning[];
-    blockers: CompletionResourceBlocker[];
-    recordedAt: string;
-  };
-  verifiedAt: string;
-  recordedAt: string;
-}
-
 export type TaskAcceptanceOutcome = 'passed' | 'failed' | 'not_evaluated';
 export type TaskAcceptanceSource = 'human_review' | 'controller_check' | 'run_completion' | 'reported' | 'legacy';
 

package/src/cli/controller/worklog.ts

@@ -7,8 +7,10 @@ import {
   writeFileSync,
 } from "fs";
 import { dirname, isAbsolute, join, relative, resolve } from "path";
+import { durableControllerHome, repositoryControllerRoot } from "../repositories/controller-home";
+import { findRegisteredRepositoryByCheckoutRoot } from "../repositories/registry";
 
-const WORKLOG_PATH = ".ai/harness/controller/worklog.jsonl";
+const WORKLOG_CONTROLLER_RELATIVE_PATH = "controller/worklog.jsonl";
 
 export const WORKLOG_CATEGORIES = [
   "issue",
@@ -61,8 +63,56 @@ export interface WorklogFilter {
   limit?: number;
 }
 
-function worklogPath(repoRoot: string): string {
-  return join(repoRoot, WORKLOG_PATH);
+export interface ControllerWorklogStorageAuthority {
+  controllerHome: string;
+  repoId: string;
+}
+
+export interface ResolvedControllerWorklogStorage extends ControllerWorklogStorageAuthority {
+  repoRoot: string;
+  physicalPath: string;
+}
+
+function resolveControllerWorklogStorageIfKnown(
+  repoRoot: string,
+  explicit?: ControllerWorklogStorageAuthority,
+): ResolvedControllerWorklogStorage | undefined {
+  const root = resolve(repoRoot);
+  if (explicit) {
+    const controllerHome = durableControllerHome(explicit.controllerHome);
+    const repoId = explicit.repoId.trim();
+    if (!repoId) throw new Error("CONTROLLER_WORKLOG_REPOSITORY_ID_REQUIRED");
+    const registered = findRegisteredRepositoryByCheckoutRoot(root, controllerHome);
+    if (registered && registered.repoId !== repoId) {
+      throw new Error(`CONTROLLER_WORKLOG_REPOSITORY_ID_MISMATCH: expected ${registered.repoId}, received ${repoId}`);
+    }
+    return {
+      controllerHome,
+      repoId,
+      repoRoot: root,
+      physicalPath: join(repositoryControllerRoot(controllerHome, repoId), WORKLOG_CONTROLLER_RELATIVE_PATH),
+    };
+  }
+
+  const controllerHome = durableControllerHome();
+  const registered = findRegisteredRepositoryByCheckoutRoot(root, controllerHome);
+  if (!registered) return undefined;
+  return {
+    controllerHome,
+    repoId: registered.repoId,
+    repoRoot: root,
+    physicalPath: join(repositoryControllerRoot(controllerHome, registered.repoId), WORKLOG_CONTROLLER_RELATIVE_PATH),
+  };
+}
+
+/** Resolve Controller-owned worklog storage without registering or initializing the repository. */
+export function resolveControllerWorklogStorage(
+  repoRoot: string,
+  explicit?: ControllerWorklogStorageAuthority,
+): ResolvedControllerWorklogStorage {
+  const storage = resolveControllerWorklogStorageIfKnown(repoRoot, explicit);
+  if (!storage) throw new Error(`CONTROLLER_WORKLOG_REPOSITORY_AUTHORITY_REQUIRED: ${resolve(repoRoot)}`);
+  return storage;
 }
 
 function eventId(): string {
@@ -75,6 +125,7 @@ export function appendControllerWorklogEvent(
     at?: string;
     actor?: string;
   },
+  authority?: ControllerWorklogStorageAuthority,
 ): ControllerWorklogEvent {
   const record: ControllerWorklogEvent = {
     schemaVersion: 1,
@@ -93,18 +144,19 @@ export function appendControllerWorklogEvent(
     statusTo: event.statusTo,
     details: event.details,
   };
-  const path = worklogPath(repoRoot);
-  mkdirSync(dirname(path), { recursive: true });
-  appendFileSync(path, `${JSON.stringify(record)}\n`, "utf-8");
+  const storage = resolveControllerWorklogStorage(repoRoot, authority);
+  mkdirSync(dirname(storage.physicalPath), { recursive: true });
+  appendFileSync(storage.physicalPath, `${JSON.stringify(record)}\n`, "utf-8");
   return record;
 }
 
 export function tryAppendControllerWorklogEvent(
   repoRoot: string,
   event: Parameters<typeof appendControllerWorklogEvent>[1],
+  authority?: ControllerWorklogStorageAuthority,
 ): void {
   try {
-    appendControllerWorklogEvent(repoRoot, event);
+    appendControllerWorklogEvent(repoRoot, event, authority);
   } catch (_error) {
     // Worklog recording is evidence enrichment. It must not corrupt the source mutation.
   }
@@ -113,12 +165,13 @@ export function tryAppendControllerWorklogEvent(
 export function listControllerWorklogEvents(
   repoRoot: string,
   filter: WorklogFilter = {},
+  authority?: ControllerWorklogStorageAuthority,
 ): ControllerWorklogEvent[] {
-  const path = worklogPath(repoRoot);
-  if (!existsSync(path)) return [];
+  const storage = resolveControllerWorklogStorageIfKnown(repoRoot, authority);
+  if (!storage || !existsSync(storage.physicalPath)) return [];
   const since = filter.since ? Date.parse(filter.since) : Number.NEGATIVE_INFINITY;
   const until = filter.until ? Date.parse(filter.until) : Number.POSITIVE_INFINITY;
-  const events = readFileSync(path, "utf-8")
+  const events = readFileSync(storage.physicalPath, "utf-8")
     .split(/\r?\n/)
     .filter(Boolean)
     .flatMap((line) => {
@@ -155,13 +208,14 @@ export function exportControllerWorklog(
     format?: "markdown" | "json";
     outputPath?: string;
     filter?: WorklogFilter;
+    authority?: ControllerWorklogStorageAuthority;
   } = {},
 ): { path: string; format: "markdown" | "json"; eventCount: number } {
   const format = options.format ?? "markdown";
   const events = listControllerWorklogEvents(repoRoot, {
     ...options.filter,
     limit: options.filter?.limit ?? 5000,
-  }).slice().reverse();
+  }, options.authority).slice().reverse();
   const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
   const defaultPath = `tasks/reports/controller-worklog-${stamp}.${format === "json" ? "json" : "md"}`;
   const outputPath = options.outputPath?.trim() || defaultPath;
@@ -196,6 +250,6 @@ export function exportControllerWorklog(
   return { path: relative(repoRoot, absolute).replace(/\\/g, "/"), format, eventCount: events.length };
 }
 
-export function controllerWorklogLocation(): string {
-  return WORKLOG_PATH;
+export function controllerWorklogLocation(repoId: string = "<repoId>"): string {
+  return `controller-home://repositories/${repoId}/controller/worklog.jsonl`;
 }

package/src/cli/editing/edit-operation-contract.ts

@@ -0,0 +1,92 @@
+export const EDIT_OPERATION_TYPES = [
+  'create',
+  'write',
+  'replace',
+  'insert_before',
+  'insert_after',
+  'prepend',
+  'append',
+  'delete',
+] as const;
+
+export type EditOperation =
+  | { type: 'create'; path: string; content: string }
+  | { type: 'write'; path: string; expectedSha256: string; content: string }
+  | { type: 'replace'; path: string; expectedSha256: string; replacements: Array<{ oldText: string; newText: string; replaceAll?: boolean }> }
+  | { type: 'insert_before' | 'insert_after'; path: string; expectedSha256: string; anchor: string; content: string; occurrence?: number }
+  | { type: 'prepend' | 'append'; path: string; expectedSha256: string; content: string }
+  | { type: 'delete'; path: string; expectedSha256: string };
+
+export const EDIT_OPERATION_INPUT_SCHEMA = {
+  type: 'object',
+  properties: {
+    type: { type: 'string', enum: [...EDIT_OPERATION_TYPES] },
+    path: { type: 'string' },
+    content: { type: 'string' },
+    expected_sha256: { type: 'string' },
+    anchor: { type: 'string', description: 'Anchor text for insert_before or insert_after.' },
+    occurrence: { type: 'number', description: '1-based anchor occurrence; defaults to 1.' },
+    replacements: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          old_text: { type: 'string' },
+          new_text: { type: 'string' },
+          replace_all: { type: 'boolean' },
+        },
+        required: ['old_text', 'new_text'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['type', 'path'],
+  additionalProperties: false,
+} as const;
+
+function objectEntries(value: unknown): Record<string, unknown>[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is Record<string, unknown> => typeof entry === 'object' && entry !== null && !Array.isArray(entry));
+}
+
+function normalizeReplacements(value: unknown): Array<{ oldText: string; newText: string; replaceAll?: boolean }> {
+  return objectEntries(value).map((replacement) => ({
+    oldText: String(replacement.old_text ?? replacement.oldText ?? ''),
+    newText: String(replacement.new_text ?? replacement.newText ?? ''),
+    replaceAll: replacement.replace_all === true || replacement.replaceAll === true,
+  }));
+}
+
+export function normalizeEditOperation(entry: Record<string, unknown>): EditOperation {
+  const type = String(entry.type ?? '');
+  const path = String(entry.path ?? '');
+  const expectedSha256 = String(entry.expected_sha256 ?? entry.expectedSha256 ?? '');
+  if (type === 'create') return { type, path, content: String(entry.content ?? '') };
+  if (type === 'delete') return { type, path, expectedSha256 };
+  if (type === 'write') return { type, path, expectedSha256, content: String(entry.content ?? '') };
+  if (type === 'replace') {
+    const replacements = Array.isArray(entry.replacements)
+      ? normalizeReplacements(entry.replacements)
+      : (entry.old_text !== undefined || entry.oldText !== undefined)
+        ? normalizeReplacements([entry])
+        : [];
+    if (replacements.length === 0) throw new Error('replace requires replacements[] or old_text/new_text');
+    return { type, path, expectedSha256, replacements };
+  }
+  if (type === 'insert_before' || type === 'insert_after') {
+    return {
+      type,
+      path,
+      expectedSha256,
+      anchor: String(entry.anchor ?? ''),
+      content: String(entry.content ?? ''),
+      occurrence: typeof entry.occurrence === 'number' ? Math.trunc(entry.occurrence) : undefined,
+    };
+  }
+  if (type === 'prepend' || type === 'append') return { type, path, expectedSha256, content: String(entry.content ?? '') };
+  throw new Error(`invalid edit operation type: ${type}`);
+}
+
+export function normalizeEditOperations(value: unknown): EditOperation[] {
+  return objectEntries(value).map(normalizeEditOperation);
+}