fuli-context 0.7.4-beta.3 → 0.7.6

package/src/agent-tools/graph-handlers.js

@@ -66,6 +66,71 @@ const HANDLERS = Object.freeze({
     app.upsertPersonalProject(input)
   ),
   list_personal_projects: (app, input) => app.listPersonalProjects(input),
+  upsert_project_agent: (app, input) => captureGuard(app, () =>
+    app.upsertProjectAgent(input)
+  ),
+  list_project_agents: (app, input) => app.listCurrentProjectAgents(input),
+  get_project_agent: (app, input) => app.getProjectAgent(input),
+  delete_project_agent: (app, input) => app.deleteProjectAgent(input),
+  cleanup_test_project_agents: (app, input) => app.cleanupProjectAgentTestRoles(input),
+  create_project_agent_assignment: (app, input) =>
+    app.createProjectAgentAssignment(input),
+  list_project_agent_assignments: (app, input) =>
+    app.listProjectAgentAssignments(input),
+  end_project_agent_assignment: (app, input) =>
+    app.endProjectAgentAssignment(input),
+  replace_project_agent_assignment: (app, input) =>
+    app.replaceProjectAgentAssignment(input),
+  get_project_agent_context: (app, input) => app.getProjectAgentContext(input),
+  coordinate_project_agent_task: (app, input) =>
+    app.coordinateProjectAgentTask(input),
+  acquire_runtime_lease: (app, input) => app.acquireRuntimeLease(input),
+  refresh_runtime_lease: (app, input) => app.refreshRuntimeLease(input),
+  release_runtime_lease: (app, input) => app.releaseRuntimeLease(input),
+  submit_project_agent_task: (app, input) => app.submitProjectAgentTask(input),
+  view_project_agent_task: (app, input) => app.viewProjectAgentTask(input),
+  record_project_agent_task_activity: (app, input) =>
+    app.recordProjectAgentTaskActivity(input),
+  view_project_agent_activity: (app, input) => app.viewProjectAgentActivity(input),
+  get_project_agent_coordination_policy: (app, input) =>
+    app.getProjectAgentCoordinationPolicy(input),
+  update_project_agent_coordination_policy: (app, input) =>
+    app.updateProjectAgentCoordinationPolicy(input),
+  get_project_agent_recruitment_policy: (app, input) =>
+    app.getProjectAgentRecruitmentPolicy(input),
+  update_project_agent_recruitment_policy: (app, input) =>
+    app.updateProjectAgentRecruitmentPolicy(input),
+  list_project_agent_recruitments: (app, input) =>
+    app.listProjectAgentRecruitments(input),
+  decide_project_agent_recruitment: (app, input) =>
+    app.decideProjectAgentRecruitment(input),
+  upsert_executor: (app, input) => app.upsertExecutor(input),
+  list_executors: (app, input) => app.listExecutors(input),
+  get_executor: (app, input) => app.getExecutor(input),
+  delete_executor: (app, input) => app.deleteExecutor(input),
+  preflight_executor: (app, input) => app.preflightExecutor(input),
+  authorize_executor: (app, input) => app.authorizeExecutor(input),
+  report_executor_health: (app, input) => app.reportExecutorHealth(input),
+  record_project_agent_executor_actual: (app, input) =>
+    app.recordProjectAgentExecutorActual(input),
+  upsert_executor_routing_rule: (app, input) =>
+    app.upsertExecutorRoutingRule(input),
+  update_executor_routing_rule: (app, input) =>
+    app.updateExecutorRoutingRule(input),
+  list_executor_routing_rules: (app, input) =>
+    app.listExecutorRoutingRules(input),
+  get_executor_routing_rule: (app, input) =>
+    app.getExecutorRoutingRule(input),
+  delete_executor_routing_rule: (app, input) =>
+    app.deleteExecutorRoutingRule(input),
+  record_project_agent_task_outcome: (app, input) =>
+    app.recordProjectAgentTaskOutcome(input),
+  list_project_agent_routing_learning: (app, input) =>
+    app.listProjectAgentRoutingLearning(input),
+  ignore_project_agent_routing_learning: (app, input) =>
+    app.ignoreProjectAgentRoutingLearning(input),
+  reset_project_agent_routing_learning: (app, input) =>
+    app.resetProjectAgentRoutingLearning(input),
   start_knowledge_review: (app, input) => app.startKnowledgeReview(input),
   list_knowledge_review_candidates: (app, input) =>
     app.listKnowledgeReviewCandidates(input),

package/src/agent-tools/project-agent-definitions.js

@@ -0,0 +1,307 @@
+import {
+  arraySchema,
+  booleanSchema,
+  enumSchema,
+  integerSchema,
+  nullableStringSchema,
+  objectSchema,
+  stringSchema
+} from './schema.js';
+
+const id = boundedString(256);
+const shortText = boundedString(2048);
+const idempotencyKey = { ...boundedString(256), minLength: 8 };
+const dateTime = { ...boundedString(64), format: 'date-time' };
+const sourceApplication = {
+  type: ['string', 'null'],
+  enum: ['codex', 'claude_code', 'cursor', 'kiro', 'other', null]
+};
+
+const projectAgentStatus = enumSchema(['active', 'inactive', 'archived']);
+export const nullableProjectAgentStatus = {
+  type: ['string', 'null'],
+  enum: ['active', 'inactive', 'archived', null]
+};
+const projectAgentExecutorPolicy = objectSchema({
+  mode: enumSchema(['flexible', 'locked']),
+  lockedExecutorIds: arraySchema(id, { maxItems: 32 }),
+  preferredExecutorIds: arraySchema(id, { maxItems: 32 })
+});
+export const projectAgentModelStrategy = objectSchema({
+  mode: enumSchema(['adaptive', 'fast', 'balanced', 'deep']),
+  reasoningEffort: enumSchema(['default', 'low', 'medium', 'high']),
+  capabilityHints: arraySchema(boundedString(128), { maxItems: 16 })
+});
+export const projectAgentProfile = objectSchema({
+  name: boundedString(160),
+  responsibility: boundedString(4096),
+  occupationEmoji: { ...nullableStringSchema(), minLength: 1, maxLength: 32 },
+  agentType: enumSchema(['coordinator', 'durable', 'hr', 'temporary']),
+  workKinds: arraySchema(boundedString(512), { maxItems: 32 }),
+  capabilities: arraySchema(boundedString(512), { maxItems: 32 }),
+  initialPreferences: arraySchema(boundedString(512), { maxItems: 32 }),
+  defaultModelStrategy: projectAgentModelStrategy,
+  executorPolicy: projectAgentExecutorPolicy,
+  allowedClients: arraySchema(
+    enumSchema(['codex', 'claude_code', 'cursor', 'kiro', 'other']),
+    { maxItems: 5 }
+  ),
+  testSource: nullableStringSchema(),
+  cleanupEligible: booleanSchema(),
+  status: projectAgentStatus
+}, ['name', 'responsibility']);
+
+export const projectAgentAssignmentStatus = enumSchema(['active', 'ended']);
+export const projectAgentAssignmentInput = objectSchema({
+  personalSpaceId: id,
+  personalProjectId: id,
+  agentId: id,
+  idempotencyKey,
+  responsibility: boundedString(4096),
+  workKinds: arraySchema(boundedString(512), { maxItems: 32 }),
+  capabilities: arraySchema(boundedString(512), { maxItems: 32 }),
+  modelStrategyOverride: { ...projectAgentProfile.properties.defaultModelStrategy, type: ['object', 'null'] },
+  executorPolicyOverride: { ...projectAgentExecutorPolicy, type: ['object', 'null'] },
+  reason: shortText,
+  sourceApplication,
+  sourceSessionId: nullableStringSchema()
+}, ['personalSpaceId', 'personalProjectId', 'agentId', 'idempotencyKey', 'responsibility', 'reason']);
+export const projectAgentAssignmentEndInput = objectSchema({
+  personalSpaceId: id,
+  personalProjectId: id,
+  assignmentId: id,
+  expectedRevision: integerSchema({ minimum: 0 }),
+  reason: shortText
+}, ['personalSpaceId', 'personalProjectId', 'assignmentId', 'expectedRevision', 'reason']);
+export const projectAgentAssignmentReplaceInput = objectSchema({
+  personalSpaceId: id,
+  personalProjectId: id,
+  assignmentId: id,
+  expectedRevision: integerSchema({ minimum: 0 }),
+  replacementAgentId: id,
+  idempotencyKey,
+  responsibility: boundedString(4096),
+  workKinds: arraySchema(boundedString(512), { maxItems: 32 }),
+  capabilities: arraySchema(boundedString(512), { maxItems: 32 }),
+  modelStrategyOverride: { ...projectAgentProfile.properties.defaultModelStrategy, type: ['object', 'null'] },
+  executorPolicyOverride: { ...projectAgentExecutorPolicy, type: ['object', 'null'] },
+  reason: shortText,
+  sourceApplication,
+  sourceSessionId: nullableStringSchema()
+}, [
+  'personalSpaceId', 'personalProjectId', 'idempotencyKey',
+  'responsibility', 'reason', 'assignmentId', 'expectedRevision', 'replacementAgentId'
+]);
+const projectAgentTaskStatus = enumSchema([
+  'awaiting_recruitment', 'queued', 'running', 'paused', 'failed',
+  'awaiting_review', 'blocked', 'completed', 'cancelled'
+]);
+const projectAgentTaskDuration = enumSchema(['ongoing', 'one_off']);
+const projectAgentStaffingIntent = enumSchema([
+  'reuse_preferred', 'new_durable', 'temporary', 'unassigned'
+]);
+const projectAgentTaskComplexity = enumSchema(['simple', 'standard', 'complex']);
+const projectAgentParallelPlan = objectSchema({
+  enabled: booleanSchema(),
+  independentVerification: booleanSchema(),
+  conflictFreeScopes: booleanSchema(),
+  reason: nullableStringSchema(),
+  workstreamBoundaries: arraySchema(shortText, { maxItems: 16 })
+});
+export const projectAgentTaskSubmitInput = objectSchema({
+  personalSpaceId: id,
+  personalProjectId: id,
+  idempotencyKey,
+  title: boundedString(160),
+  objective: boundedString(4096),
+  workKind: boundedString(128),
+  requiredCapabilities: arraySchema(boundedString(512), { maxItems: 16 }),
+  duration: projectAgentTaskDuration,
+  staffingIntent: projectAgentStaffingIntent,
+  leadAgentId: nullableStringSchema(),
+  collaboratorAgentIds: arraySchema(id, { maxItems: 16 }),
+  coordinatorAgentId: nullableStringSchema(),
+  complexityHint: { ...projectAgentTaskComplexity, type: ['string', 'null'] },
+  parallelPlan: projectAgentParallelPlan,
+  modelStrategyOverride: { ...projectAgentProfile.properties.defaultModelStrategy, type: ['object', 'null'] },
+  executorPolicyOverride: { ...projectAgentExecutorPolicy, type: ['object', 'null'] },
+  sourceApplication,
+  sourceSessionId: nullableStringSchema(),
+  routingReason: shortText,
+  recruitmentProfile: { ...projectAgentProfile, type: ['object', 'null'] }
+}, [
+  'personalSpaceId', 'personalProjectId', 'idempotencyKey', 'title', 'objective',
+  'workKind', 'routingReason'
+]);
+export const projectAgentTaskCoordinateInput = objectSchema({
+  projectPath: boundedString(4096),
+  idempotencyKey,
+  title: boundedString(160),
+  objective: boundedString(4096),
+  workKind: boundedString(128),
+  requiredCapabilities: arraySchema(boundedString(512), { maxItems: 16 }),
+  duration: projectAgentTaskDuration,
+  staffingIntent: projectAgentStaffingIntent,
+  leadAgentId: nullableStringSchema(),
+  collaboratorAgentIds: arraySchema(id, { maxItems: 16 }),
+  coordinatorAgentId: nullableStringSchema(),
+  complexityHint: { ...projectAgentTaskComplexity, type: ['string', 'null'] },
+  parallelPlan: projectAgentParallelPlan,
+  modelStrategyOverride: { ...projectAgentProfile.properties.defaultModelStrategy, type: ['object', 'null'] },
+  executorPolicyOverride: { ...projectAgentExecutorPolicy, type: ['object', 'null'] },
+  routingReason: shortText,
+  recruitmentProfile: { ...projectAgentProfile, type: ['object', 'null'] },
+  contextQueries: arraySchema(shortText, { minItems: 1, maxItems: 10 }),
+  contextLimitPerQuery: integerSchema({ minimum: 1, maximum: 20 }),
+  includePendingContext: booleanSchema()
+}, [
+  'projectPath', 'idempotencyKey', 'title', 'objective', 'workKind',
+  'routingReason', 'contextQueries'
+]);
+export const projectAgentTaskActivityInput = objectSchema({
+  personalSpaceId: id,
+  personalProjectId: id,
+  taskId: id,
+  idempotencyKey,
+  expectedRevision: integerSchema({ minimum: 0 }),
+  status: projectAgentTaskStatus,
+  summary: shortText,
+  agentId: nullableStringSchema(),
+  actorKind: enumSchema(['agent', 'human']),
+  sourceApplication,
+  sourceSessionId: nullableStringSchema(),
+  actualExecutor: nullableStringSchema(),
+  actualModelProvider: nullableStringSchema(),
+  actualModel: nullableStringSchema(),
+  routingRuleId: nullableStringSchema(),
+  fallbackReason: nullableStringSchema(),
+  actualExecutorId: nullableStringSchema(),
+  matchedExecutorRuleId: nullableStringSchema(),
+  executorSelectionReason: nullableStringSchema(),
+  executorFallbackReason: nullableStringSchema(),
+  executorBlockedReason: nullableStringSchema(),
+  workerId: { ...nullableStringSchema(), minLength: 1, maxLength: 128 },
+  workerLabel: { ...nullableStringSchema(), minLength: 1, maxLength: 160 },
+  workerOccupationEmoji: { ...nullableStringSchema(), minLength: 1, maxLength: 32 },
+  workerStatus: { ...projectAgentTaskStatus, type: ['string', 'null'] }
+}, [
+  'personalSpaceId', 'personalProjectId', 'taskId', 'idempotencyKey', 'status', 'summary'
+]);
+export const recruitmentConfirmationMode = enumSchema(['automatic', 'require_confirmation']);
+const recruitmentPositionKind = enumSchema(['durable', 'temporary']);
+export const recruitmentStatus = enumSchema([
+  'awaiting_confirmation', 'requested', 'fulfilled', 'cancelled', 'blocked', 'no_hr'
+]);
+export const recruitmentDecision = enumSchema(['approve', 'cancel']);
+const executorRegistrationStatus = enumSchema(['registered', 'disabled', 'revoked']);
+const executorPermissionStatus = enumSchema(['pending', 'authorized', 'denied', 'revoked']);
+const executorPreflightStatus = enumSchema(['not_run', 'passed', 'failed', 'expired']);
+export const executorHealthStatus = enumSchema(['unknown', 'healthy', 'degraded', 'unhealthy']);
+export const executorAuthorizationStatus = enumSchema(['pending', 'authorized', 'denied', 'revoked']);
+const executorActualModelStrategySource = enumSchema([
+  'task', 'assignment', 'agent', 'routing_rule', 'coordinator'
+]);
+export const executorModel = objectSchema({
+  provider: boundedString(128),
+  model: boundedString(256),
+  capabilities: arraySchema(boundedString(512), { maxItems: 32 }),
+  strategyModes: arraySchema(enumSchema(['adaptive', 'fast', 'balanced', 'deep']), { maxItems: 4 }),
+  reasoningEfforts: arraySchema(enumSchema(['default', 'low', 'medium', 'high']), { maxItems: 4 }),
+  available: booleanSchema(),
+  observedAt: nullableStringSchema(),
+  sourceApplication,
+  unavailableReason: nullableStringSchema()
+}, ['provider', 'model']);
+export const executorProfile = objectSchema({
+  personalSpaceId: id,
+  executorId: id,
+  displayName: boundedString(160),
+  executorKind: boundedString(128),
+  capabilities: arraySchema(boundedString(512), { maxItems: 32 }),
+  advertisedModels: arraySchema(executorModel, { maxItems: 64 }),
+  globalPriority: integerSchema({ minimum: 1, maximum: 1000000 }),
+  healthRequired: booleanSchema(),
+  expectedRevision: integerSchema({ minimum: 0 }),
+  idempotencyKey,
+  sourceApplication,
+  sourceSessionId: nullableStringSchema(),
+  testSource: nullableStringSchema(),
+  cleanupEligible: booleanSchema()
+}, ['personalSpaceId', 'executorId', 'displayName', 'idempotencyKey']);
+export const routingRuleScope = enumSchema(['global', 'space', 'project', 'task']);
+export const executorRoutingRuleInput = objectSchema({
+  personalSpaceId: id,
+  scope: routingRuleScope,
+  personalProjectId: nullableStringSchema(),
+  taskId: nullableStringSchema(),
+  workKind: boundedString(128),
+  requiredCapabilities: arraySchema(boundedString(512), { maxItems: 32 }),
+  executorIds: arraySchema(id, { minItems: 1, maxItems: 32 }),
+  modelStrategy: { ...projectAgentProfile.properties.defaultModelStrategy, type: ['object', 'null'] },
+  priority: integerSchema({ minimum: 1, maximum: 1000000 }),
+  reason: shortText,
+  idempotencyKey
+}, ['scope', 'workKind', 'reason', 'idempotencyKey']);
+export const executorActualReportInput = objectSchema({
+  personalSpaceId: id,
+  personalProjectId: id,
+  taskId: id,
+  runId: id,
+  agentId: id,
+  executorId: id,
+  provider: boundedString(128),
+  model: boundedString(256),
+  modelStrategy: projectAgentProfile.properties.defaultModelStrategy,
+  modelStrategySource: executorActualModelStrategySource,
+  matchedRuleId: nullableStringSchema(),
+  fallbackReason: nullableStringSchema(),
+  idempotencyKey,
+  occurredAt: dateTime,
+  sourceApplication,
+  sourceSessionId: nullableStringSchema()
+}, [
+  'personalSpaceId', 'personalProjectId', 'taskId', 'runId', 'agentId',
+  'executorId', 'provider', 'model', 'idempotencyKey', 'occurredAt'
+]);
+const outcomeEvidenceKind = enumSchema([
+  'terminal_outcome',
+  'rework_requested', 'repeated_negative_feedback', 'explicit_praise',
+  'test_passed', 'test_failed', 'acceptance_passed', 'acceptance_failed', 'explicit_rating'
+]);
+const outcomeEvidenceSource = enumSchema(['system_terminal', 'user_explicit', 'test_fact']);
+const outcomeTerminalStatus = enumSchema(['completed', 'failed', 'cancelled']);
+export const projectAgentTaskOutcomeInput = objectSchema({
+  personalSpaceId: id,
+  personalProjectId: id,
+  workKind: boundedString(128),
+  agentId: id,
+  executorId: id,
+  taskId: id,
+  runId: nullableStringSchema(),
+  idempotencyKey,
+  modelStrategy: { ...projectAgentProfile.properties.defaultModelStrategy, type: ['object', 'null'] },
+  evidenceKind: outcomeEvidenceKind,
+  source: outcomeEvidenceSource,
+  terminalOutcome: { ...outcomeTerminalStatus, type: ['string', 'null'] },
+  rating: { ...integerSchema({ minimum: 1, maximum: 5 }), type: ['integer', 'null'] },
+  referenceIds: arraySchema(id, { maxItems: 16 }),
+  note: nullableStringSchema(),
+  occurredAt: dateTime
+}, [
+  'personalSpaceId', 'personalProjectId', 'workKind', 'agentId', 'executorId', 'taskId',
+  'idempotencyKey', 'evidenceKind', 'source', 'occurredAt'
+]);
+
+// Keep the complete state vocabulary in one place even when a state schema is
+// currently represented only in Provider responses rather than tool inputs.
+export const projectAgentResponseStateSchemas = {
+  recruitmentPositionKind,
+  executorRegistrationStatus,
+  executorPermissionStatus,
+  executorPreflightStatus,
+  executorHealthStatus
+};
+
+function boundedString(maxLength) {
+  return { ...stringSchema(), minLength: 1, maxLength };
+}

package/src/backup/graph-backup.js

@@ -0,0 +1,289 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import {
+  chmod,
+  lstat,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  writeFile
+} from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import { FULI_VERSION } from '../package-metadata.js';
+
+const BACKUP_FORMAT = 'fuli-neo4j-backup';
+const BACKUP_VERSION = 1;
+
+export async function exportGraphData({
+  outputDir,
+  sourceMode,
+  instances,
+  adapter,
+  now = () => new Date()
+}) {
+  const destination = requiredPath(outputDir, 'Backup output directory');
+  validateMode(sourceMode, 'sourceMode');
+  const selectedInstances = validateInstances(instances);
+  assertAdapter(adapter, ['stop', 'dump', 'start']);
+  if (await pathExists(destination)) {
+    throw new Error('Backup output already exists; choose a new directory.');
+  }
+  await mkdir(dirname(destination), { recursive: true });
+  const partial = `${destination}.partial-${randomUUID()}`;
+  await mkdir(partial, { recursive: false, mode: 0o700 });
+  let lifecycle = null;
+  let published = false;
+  try {
+    lifecycle = await adapter.stop();
+    const exported = [];
+    for (const id of selectedInstances) {
+      const file = `${id}.dump`;
+      const path = join(partial, file);
+      await adapter.dump(id, path);
+      await chmod(path, 0o600);
+      exported.push({ id, file, sha256: await sha256File(path) });
+    }
+    const manifest = {
+      format: BACKUP_FORMAT,
+      version: BACKUP_VERSION,
+      createdAt: now().toISOString(),
+      sourceMode,
+      fuliVersion: FULI_VERSION,
+      instances: exported,
+      ...(typeof adapter.selection === 'function'
+        ? selectionProperty(await adapter.selection())
+        : {})
+    };
+    const manifestPath = join(partial, 'manifest.json');
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+    await rename(partial, destination);
+    published = true;
+    return {
+      status: 'exported',
+      outputDir: destination,
+      sourceMode,
+      instances: selectedInstances
+    };
+  } finally {
+    if (!published) await rm(partial, { recursive: true, force: true });
+    if (lifecycle?.resume === true) await adapter.start(lifecycle);
+  }
+}
+
+export async function importGraphData({
+  inputDir,
+  targetMode,
+  rollbackDir,
+  adapter,
+  now = () => new Date()
+}) {
+  const source = requiredPath(inputDir, 'Backup input directory');
+  const rollbackBase = requiredPath(rollbackDir, 'Rollback directory');
+  validateMode(targetMode, 'targetMode');
+  assertAdapter(adapter, ['stop', 'dump', 'load', 'start']);
+  const manifest = await readGraphBackupManifest(source);
+  await verifyBackupFiles(source, manifest);
+  if (
+    Array.isArray(adapter.instances) &&
+    manifest.instances.some(({ id }) => !adapter.instances.includes(id))
+  ) {
+    throw new Error(
+      'The target runtime is not configured for every graph instance in this backup.'
+    );
+  }
+
+  const rollbackRoot = join(
+    rollbackBase,
+    `before-import-${now().toISOString().replace(/[:.]/g, '-')}-${randomUUID()}`
+  );
+  await mkdir(rollbackRoot, { recursive: true, mode: 0o700 });
+  let lifecycle = null;
+  const rollbackEntries = [];
+  let rollbackReady = false;
+  try {
+    lifecycle = await adapter.stop();
+    for (const entry of manifest.instances) {
+      if (typeof adapter.hasData === 'function' && !await adapter.hasData(entry.id)) continue;
+      const path = join(rollbackRoot, `${entry.id}.dump`);
+      await adapter.dump(entry.id, path);
+      await chmod(path, 0o600);
+      rollbackEntries.push({ id: entry.id, path });
+    }
+    if (rollbackEntries.length > 0) {
+      const rollbackManifest = {
+        format: BACKUP_FORMAT,
+        version: BACKUP_VERSION,
+        createdAt: now().toISOString(),
+        sourceMode: targetMode,
+        fuliVersion: FULI_VERSION,
+        reason: 'automatic-pre-import-rollback',
+        instances: await Promise.all(rollbackEntries.map(async ({ id, path }) => ({
+          id,
+          file: basename(path),
+          sha256: await sha256File(path)
+        })))
+      };
+      await writeFile(join(rollbackRoot, 'manifest.json'),
+        `${JSON.stringify(rollbackManifest, null, 2)}\n`, { mode: 0o600 });
+      rollbackReady = true;
+    } else {
+      await rm(rollbackRoot, { recursive: true, force: true });
+    }
+    try {
+      for (const entry of manifest.instances) {
+        await adapter.load(entry.id, join(source, entry.file), { rollback: false });
+      }
+      if (typeof adapter.reconcile === 'function') {
+        await adapter.reconcile({
+          selection: manifest.selection ?? {},
+          sourceMode: manifest.sourceMode,
+          targetMode,
+          lifecycle
+        });
+      }
+    } catch (error) {
+      let rollbackError = null;
+      for (const entry of rollbackEntries) {
+        try {
+          await adapter.load(entry.id, entry.path, { rollback: true });
+        } catch (caught) {
+          rollbackError ??= caught;
+        }
+      }
+      if (rollbackError) {
+        throw new AggregateError([error, rollbackError],
+          'Graph import failed and its automatic rollback was incomplete.');
+      }
+      throw error;
+    }
+    return {
+      status: 'imported',
+      inputDir: source,
+      targetMode,
+      instances: manifest.instances.map(({ id }) => id),
+      rollbackDir: rollbackReady ? rollbackRoot : null
+    };
+  } catch (error) {
+    if (!rollbackReady) await rm(rollbackRoot, { recursive: true, force: true });
+    throw error;
+  } finally {
+    if (lifecycle?.resume === true) await adapter.start(lifecycle);
+  }
+}
+
+export async function readGraphBackupManifest(inputDir) {
+  const root = requiredPath(inputDir, 'Backup input directory');
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(join(root, 'manifest.json'), 'utf8'));
+  } catch (error) {
+    throw new Error('Backup manifest is missing or invalid.', { cause: error });
+  }
+  if (manifest?.format !== BACKUP_FORMAT || manifest.version !== BACKUP_VERSION) {
+    throw new Error('Backup format or version is not supported.');
+  }
+  validateMode(manifest.sourceMode, 'backup source mode');
+  validateManifestInstances(manifest.instances);
+  validateSelection(manifest.selection);
+  return manifest;
+}
+
+async function verifyBackupFiles(root, manifest) {
+  for (const entry of manifest.instances) {
+    const actual = await sha256File(join(root, entry.file));
+    if (actual !== entry.sha256) {
+      throw new Error(`Backup checksum validation failed for ${entry.id}.`);
+    }
+  }
+}
+
+function validateManifestInstances(instances) {
+  if (!Array.isArray(instances) || instances.length === 0) {
+    throw new Error('Backup manifest does not contain graph instances.');
+  }
+  const ids = validateInstances(instances.map(({ id }) => id));
+  if (ids.length !== instances.length) throw new Error('Backup instances are invalid.');
+  for (const entry of instances) {
+    if (
+      entry.file !== `${entry.id}.dump` ||
+      basename(entry.file) !== entry.file ||
+      !/^[a-f0-9]{64}$/.test(entry.sha256)
+    ) {
+      throw new Error(`Backup entry for ${entry.id} is invalid.`);
+    }
+  }
+}
+
+function validateSelection(selection) {
+  if (selection === undefined) return;
+  if (
+    !selection ||
+    typeof selection !== 'object' ||
+    Object.keys(selection).some((key) => key !== 'personalSpaceId') ||
+    typeof selection.personalSpaceId !== 'string' ||
+    !selection.personalSpaceId.trim() ||
+    selection.personalSpaceId.length > 200 ||
+    /[\s\u0000-\u001f\u007f]/u.test(selection.personalSpaceId)
+  ) {
+    throw new Error('Backup personal-space selection is invalid.');
+  }
+}
+
+function selectionProperty(selection) {
+  if (selection == null) return {};
+  validateSelection(selection);
+  return { selection };
+}
+
+function validateInstances(instances) {
+  if (!Array.isArray(instances) || instances.length === 0) {
+    throw new TypeError('At least one graph instance is required.');
+  }
+  const normalized = [...new Set(instances)];
+  if (
+    normalized.length !== instances.length ||
+    normalized.some((id) => !['personal', 'workspace'].includes(id))
+  ) {
+    throw new TypeError('Graph instances must be unique personal or workspace entries.');
+  }
+  return normalized;
+}
+
+function validateMode(mode, label) {
+  if (!['container', 'native'].includes(mode)) {
+    throw new TypeError(`${label} must be container or native.`);
+  }
+}
+
+function assertAdapter(adapter, methods) {
+  if (!adapter || methods.some((method) => typeof adapter[method] !== 'function')) {
+    throw new TypeError('A complete graph backup runtime adapter is required.');
+  }
+}
+
+function requiredPath(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} is required.`);
+  return resolve(value);
+}
+
+async function pathExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+function sha256File(path) {
+  return new Promise((resolveHash, reject) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(path);
+    stream.on('error', reject);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolveHash(hash.digest('hex')));
+  });
+}