create-agdf 0.20.2 → 0.30.0

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-maintenance/compatibility.js

@@ -1,149 +1,59 @@
-import { lstatSync, readdirSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
-import { discoverRuns } from "../control-state/run-state-reader.js";
-import { directoryIdentity, regularFileSnapshot } from "../control-state/run-store-inspection.js";
-import { artefactFileDigest, listedArtefactPaths, pendingArtefactPaths, runSealState } from "../control-state/run-seal.js";
-import { inspectRunRecovery } from "../control-state/run-recovery.js";
-import { doctorRequiredFiles } from "../control-evaluation/required-files.js";
-import { inspectControlConfiguration } from "../control-state/control-configuration.js";
-import { hasSymlinkComponent } from "../control-state/contained-file.js";
-import { APPROVAL_GATES } from "../control-state/run-seal-compute.js";
-
-function entryExists(path) {
-  try { lstatSync(path); return true; } catch (error) {
-    if (error.code === "ENOENT") return false;
-    throw error;
-  }
-}
-
-export function safeApprovalReset(approvals) {
-  return APPROVAL_GATES.every((gate) => approvals.some((approval) => approval.gate === gate))
-    && approvals.every((approval) => approval.status === "missing" && !approval.evidence);
-}
-
-function interruptedRecoveries(root, runId) {
-  const directory = join(root, ".agdf", "control", "runs", runId, "recovery-previews");
-  if (!entryExists(directory)) return [];
-  directoryIdentity(directory);
-  return readdirSync(directory).filter((name) => name.endsWith(".json")).map((name) => {
-    const journal = JSON.parse(regularFileSnapshot(join(directory, name)).content.toString("utf8"));
-    return journal.phase === "applying" ? { preview_id: journal.preview_id, confirmation: journal.confirmation,
-      prior_approvals: journal.prior_approvals, source_revision_id: journal.source_revision_id, next_gate: journal.next_gate,
-      journal: `.agdf/control/runs/${runId}/recovery-previews/${name}` } : null;
-  }).filter(Boolean);
-}
-
-export const CONTROL_MIGRATION_STATUSES = Object.freeze(["not_checked", "absent", "current", "migration_required", "repair_required"]);
-
+import { lstatSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { discoverRuns } from '../control-state/run-state-reader.js';
+import { directoryIdentity, regularFileSnapshot } from '../control-state/run-store-inspection.js';
+import { runSealState } from '../control-state/run-seal.js';
+import { requiredControlFiles } from '../control-evaluation/required-files.js';
+import { readControlLayout } from '../control-state/control-layout.js';
+import { inspectControlConfiguration } from '../control-state/control-configuration.js';
+
+const present = path => { try { lstatSync(path); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; } };
+export const CONTROL_COMPATIBILITY_STATUSES = Object.freeze(['not_checked', 'absent', 'current', 'unsupported', 'repair_required']);
 export function uncheckedControl() {
-  return { schema_version: 1, supported_control_state_version: 2, target: null,
-    status: "not_checked", runs: [], diagnostics: [], changes: [], authorizes: false };
+  return { schema_version: 1, supported_control_state_version: 4, supported_control_state_versions: [4], control_layout: null,
+    target: null, status: 'not_checked', runs: [], diagnostics: [], changes: [], authorizes: false };
 }
-
-// Repository compatibility is separate from delivery readiness and grants no gate authority.
-// Never search neighbouring repositories or infer a write target from a host configuration path.
-export function inspectControlMigration(root) {
+// Read-only compatibility, never migration or reset. Unsupported and corrupt
+// current state are distinct; neither classification creates write permission.
+export function inspectControlCompatibility(root) {
   if (!root) return uncheckedControl();
-  if (!isAbsolute(root)) throw new Error("AGDF_CONTROL_MIGRATION_TARGET_INVALID");
-  const result = { ...uncheckedControl(), target: root, status: "absent" };
-  const agdf = join(root, ".agdf");
+  if (!isAbsolute(root)) throw Error('AGDF_CONTROL_COMPATIBILITY_TARGET_INVALID');
+  const result = { ...uncheckedControl(), target: root, status: 'absent' };
   try {
-    if (!entryExists(agdf)) return result;
-    for (const path of [root, agdf, join(agdf, "control")]) {
-      try { directoryIdentity(path); } catch {
-        throw Object.assign(new Error("AGDF_CONTROL_PATH_INVALID"), { path });
-      }
-    }
-    const required = [join(".agdf", "control", "config.json"), join(".agdf", "control", "README.md"),
-      ...doctorRequiredFiles.filter((path) => !path.endsWith("AGDF_RUN.md"))];
-    for (const path of required) {
-      try { regularFileSnapshot(join(root, path)); } catch {
-        throw Object.assign(new Error("AGDF_CONTROL_SCAFFOLD_INCOMPLETE"), { path });
-      }
-    }
+    if (!present(join(root, '.agdf/control'))) return result;
+    for (const path of [root, join(root, '.agdf'), join(root, '.agdf/control')]) directoryIdentity(path);
+    result.control_layout = readControlLayout(root).layout;
+    for (const relative of ['.agdf/control/config.json', '.agdf/control/README.md', ...requiredControlFiles(root)])
+      regularFileSnapshot(join(root, relative));
     const configuration = inspectControlConfiguration(root);
-    if (!configuration.active) throw new Error(configuration.diagnostic);
-    const legacyPath = join(agdf, "control", "AGDF_RUN.md");
-    if (entryExists(legacyPath)) {
-      const legacy = regularFileSnapshot(legacyPath).content.toString("utf8");
-      if (!legacy.startsWith("<!-- AGDF LEGACY PROJECTION")) {
-        result.diagnostics.push({ code: "AGDF_LEGACY_MIGRATION_REQUIRED", path: ".agdf/control/AGDF_RUN.md" });
-      }
-    }
-    const runsPath = join(agdf, "control", "runs");
-    if (!entryExists(runsPath) && result.diagnostics.length) {
-      result.status = "migration_required";
-      return result;
-    }
-    directoryIdentity(runsPath);
+    if (!configuration.active) throw Error(configuration.diagnostic);
+    directoryIdentity(join(root, '.agdf/control/runs'));
     for (const run of discoverRuns(root)) {
+      const unsupported = run.findings.some(row => row.classification === 'unsupported_version');
       const entry = { run_id: run.run_id, control_state_version: run.meta?.control_state_version ?? null,
-        lifecycle: run.meta?.lifecycle ?? null, status: "current", seal_status: null,
-        safe_to_migrate: false, approvals: [], pending_recoveries: [], diagnostics: [] };
-      if (!run.valid) {
-        entry.status = "repair_required";
-        entry.diagnostics = run.findings;
-      } else {
+        status: unsupported ? 'unsupported' : !run.valid ? 'repair_required' : 'current', diagnostics: [...run.findings], pending_recoveries: [] };
+      if (run.valid) {
         const seal = runSealState(root, run.content);
-        entry.seal_status = seal.status;
-        const pending = new Set(pendingArtefactPaths(run.content));
-        const unresolved = listedArtefactPaths(run.content).filter((path) => {
-          const status = artefactFileDigest(root, path);
-          return status === "unresolved" || (status === "missing" && (!pending.has(path) || hasSymlinkComponent(root, path)));
-        });
-        if (run.meta.lifecycle !== "active" && seal.status === "unsealed") {
-          // Historical records remain non-authorizing evidence; installation does not reopen them
-          // or manufacture a retrospective integrity/approval attestation.
-          entry.status = "historical";
-        } else if (unresolved.length) {
-          entry.status = "repair_required";
-          entry.diagnostics = unresolved.map((path) => ({ code: "AGDF_RECOVERY_ARTEFACT_MISSING", path }));
-        } else if (seal.status === "unsealed" && run.meta.lifecycle === "active") {
-          const inspection = inspectRunRecovery(root, run.run_id, { inspectHistory: false });
-          entry.approvals = inspection.approvals;
-          entry.next_gate = inspection.next_gate_if_recovered;
-          entry.status = inspection.artefacts.every((file) => file.status === "valid" || file.planned) ? "migration_required" : "repair_required";
-          entry.safe_to_migrate = entry.status === "migration_required" && safeApprovalReset(inspection.approvals);
-          entry.diagnostics = inspection.artefacts.filter((file) => file.status !== "valid" && !file.planned)
-            .map((file) => ({ code: "AGDF_RECOVERY_ARTEFACT_PATH_INVALID", path: file.path }));
-        } else if (seal.status !== "valid") {
-          entry.status = "repair_required";
-          entry.diagnostics = [{ code: "AGDF_RUN_SEAL_INVALID", seal_status: seal.status }];
-        }
-        entry.pending_recoveries = interruptedRecoveries(root, run.run_id);
-        if (entry.pending_recoveries.length) {
-          entry.status = "repair_required";
-          entry.diagnostics.push({ code: "AGDF_RECOVERY_RESUME_REQUIRED" });
-        }
+        if (seal.status !== 'valid') { entry.status = 'repair_required'; entry.diagnostics.push({ code: 'AGDF_RUN_SEAL_INVALID', seal_status: seal.status }); }
+        else if (run.meta.lifecycle !== 'active') entry.status = 'historical';
       }
       result.runs.push(entry);
     }
-    result.status = result.runs.some((run) => run.status === "repair_required") ? "repair_required"
-      : result.diagnostics.length || result.runs.some((run) => run.status === "migration_required") ? "migration_required" : "current";
+    result.status = result.runs.some(run => run.status === 'unsupported') ? 'unsupported'
+      : result.runs.some(run => run.status === 'repair_required') ? 'repair_required' : 'current';
   } catch (error) {
-    result.status = "repair_required";
-    result.diagnostics.push({ code: String(error.code ?? error.message), ...(error.path ? { path: error.path } : {}) });
+    const code = String(error.code ?? error.message);
+    result.status = /LAYOUT_UNSUPPORTED|VERSION_UNSUPPORTED/u.test(code) ? 'unsupported' : 'repair_required';
+    result.diagnostics.push({ code, ...(error.path ? { path: error.path } : {}) });
   }
   return result;
 }
-
-export function assertControlMigration(value) {
-  if (!value || value.schema_version !== 1 || value.supported_control_state_version !== 2
-      || !CONTROL_MIGRATION_STATUSES.includes(value.status) || value.authorizes !== false
-      || !(value.target === null || (typeof value.target === "string" && isAbsolute(value.target)))
-      || (value.status === "not_checked" && value.target !== null)
-      || (value.status !== "not_checked" && value.target === null)
-      || !Array.isArray(value.runs) || !Array.isArray(value.diagnostics) || !Array.isArray(value.changes)) {
-    throw new Error("AGDF_CONTROL_MIGRATION_REPORT_INVALID");
-  }
-  if (value.repair && (value.repair.authorizes !== false || value.repair.target !== value.target
-      || !["needs_input", "deferred", "partial", "applied"].includes(value.repair.status)
-      || !Array.isArray(value.repair.diagnostics) || !Array.isArray(value.repair.items)
-      || value.repair.items.some((item) => typeof item.run_id !== "string" || typeof item.available !== "boolean"
-        || !["manual", "self_reference", "run_snapshot", "missing_artefacts"].includes(item.kind)
-        || !Array.isArray(item.sources) || !Array.isArray(item.required)))) {
-    throw new Error("AGDF_CONTROL_REPAIR_REPORT_INVALID");
-  }
+export function assertControlCompatibility(value) {
+  if (!value || value.schema_version !== 1 || value.supported_control_state_version !== 4
+    || JSON.stringify(value.supported_control_state_versions) !== '[4]' || !CONTROL_COMPATIBILITY_STATUSES.includes(value.status)
+    || value.authorizes !== false || !(value.target === null || typeof value.target === 'string' && isAbsolute(value.target))
+    || (value.status === 'not_checked') !== (value.target === null) || !Array.isArray(value.runs)
+    || !Array.isArray(value.diagnostics) || !Array.isArray(value.changes) || value.changes.length)
+    throw Error('AGDF_CONTROL_COMPATIBILITY_REPORT_INVALID');
   return value;
 }
-

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-maintenance/contract.js

@@ -1,10 +1,10 @@
 import { isAbsolute } from "node:path";
-import { assertControlMigration } from "./compatibility.js";
+import { assertControlCompatibility } from "./compatibility.js";
 
 // Counts are presentation projections of the canonical inventory, never a stored policy.
 export function controlCounts(control) {
   return {
-    migration: control.runs.filter((run) => run.status === "migration_required" || run.pending_recoveries?.length === 1).length,
+    unsupported: control.runs.filter((run) => run.status === "unsupported").length,
     repair: control.runs.filter((run) => run.status === "repair_required" && run.pending_recoveries?.length !== 1).length,
     historical: control.runs.filter((run) => run.status === "historical").length,
   };
@@ -13,12 +13,12 @@ export function controlCounts(control) {
 export function assertMaintenanceResult(value, target = value?.target) {
   if (!value || value.schema_version !== 1 || value.authorizes !== false
       || typeof target !== "string" || !isAbsolute(target) || value.target !== target
-      || !["inspect", "guided"].includes(value.operation)
+      || value.operation !== "inspect"
       || !["complete", "unavailable", "not_checked"].includes(value.inspection_state)
-      || !["not_started", "deferred", "applied", "partial", "needs_input"].includes(value.maintenance_outcome)
+      || value.maintenance_outcome !== "not_started"
       || !Array.isArray(value.diagnostics)) throw new Error("AGDF_MAINTENANCE_RESULT_INVALID");
   if (value.inspection_state === "complete") {
-    assertControlMigration(value.compatibility);
+    assertControlCompatibility(value.compatibility);
     if (value.compatibility.target !== target
         || JSON.stringify(value.counts) !== JSON.stringify(controlCounts(value.compatibility))) {
       throw new Error("AGDF_MAINTENANCE_TARGET_MISMATCH");

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-maintenance/presentation.js

@@ -1,122 +1,30 @@
-import { interactionLocales } from "../resources/context.js";
-import { localePack } from "../interaction-presentation.js";
-import { controlCounts } from "./contract.js";
-
-export function renderMaintenanceOffer(control, { registry = interactionLocales, language = "en", details = false } = {}) {
-  const copy = localePack(registry, language).repositoryMaintenance;
-  return [renderControlMigration(control, { registry, language, details }),
-    `[1] ${copy.start}`, `[2] ${copy.later}`, `[3] ${copy.details}`].join("\n");
-}
-
-export function renderMaintenanceResult(report, { registry = interactionLocales, language = "en", details = false } = {}) {
-  const copy = localePack(registry, language).repositoryMaintenance;
-  if (report.inspection_state !== "complete") return `${copy.unavailable}: ${report.target}\n${report.diagnostics.map((item) => item.code).join("\n")}`;
-  return [renderControlMigration(report.compatibility, { registry, language, details }),
-    ...report.diagnostics.map((item) => `${item.run_id ? `${item.run_id}: ` : ""}${item.code}${item.path ? `: ${item.path}` : ""}`),
-    `${copy.title}: ${copy.outcomes[report.maintenance_outcome]}`].join("\n");
-}
-
-export function renderStartupControlNotice(facts, { registry = interactionLocales, language = "en", platform = process.platform } = {}) {
-  if (!facts.invocation) return "";
-  const pack = localePack(registry, language);
-  const copy = pack.repositoryMaintenance;
-  const migration = pack.installSetup.controlMigration;
-  const quote = platform === "win32" ? (value) => `'${String(value).replaceAll("'", "''")}'`
-    : (value) => `'${String(value).replaceAll("'", `'"'"'`)}'`;
-  const command = [facts.invocation.executable, ...facts.invocation.argv].map(quote).join(" ");
-  return [copy.title, `${migration.target}: ${facts.target}`,
-    facts.status === "unavailable" ? copy.unavailable : `${migration.state}: ${migration.states[facts.status]}`,
-    ...(facts.counts ? [replacement(migration.eligibleDescription, { count: facts.counts.migration }),
-      replacement(migration.blockedDescription, { count: facts.counts.repair })] : []),
-    copy.next, `${platform === "win32" ? "& " : ""}${command}`].join("\n");
-}
-
-function replacement(template, values = {}) {
-  return Object.entries(values).reduce((current, [key, value]) => current.replaceAll(`{${key}}`, String(value)), template);
-}
-
-export function renderControlMigration(control, { registry = interactionLocales, language = "en", details = false } = {}) {
-  if (!control || control.status === "not_checked") return "";
-  const copy = localePack(registry, language).installSetup.controlMigration;
-  const lines = ["", copy.title, `${copy.target}: ${control.target}`,
-    `${copy.state}: ${copy.states[control.status]}`];
-  const { migration: eligible, repair } = controlCounts(control);
-  if (eligible) lines.push(replacement(copy.eligibleDescription, { count: eligible }));
-  if (repair) lines.push(replacement(copy.blockedDescription, { count: repair }));
-  if (control.changes.length) lines.push(replacement(copy.changed, { count: control.changes.length }));
-  if (control.repair) {
-    const repairCopy = localePack(registry, language).installSetup.controlRepair;
-    lines.push(replacement(repairCopy.repairedDescription, { count: control.repair.items.filter((item) => item.outcome === "repaired").length }));
-    for (const item of control.repair.items.filter((item) => !item.available)) {
-      for (const finding of item.required) lines.push(`${item.run_id}: ${repairCopy.reasons[finding.code] ?? repairCopy.manualDescription}${finding.path ? `: ${finding.path}` : ""}`);
-    }
-  }
-  if (!details) {
-    if (control.diagnostics.length && !repair) lines.push(copy.repairDescription);
-    if (eligible || repair || control.diagnostics.length) lines.push(copy.detailsDescription);
-    return lines.join("\n");
-  }
-  lines.push(`${copy.format}: ${control.supported_control_state_version}`,
-    replacement(copy.historicalCount, { count: control.runs.filter((run) => run.status === "historical").length }));
-  for (const run of control.runs.filter((entry) => entry.status !== "current" && entry.status !== "historical")) {
-    lines.push(`${run.run_id}: ${copy.states[run.status]}`);
-    for (const finding of run.diagnostics) lines.push(`  ${finding.code}${finding.path ? `: ${finding.path}` : ""}`);
-  }
-  for (const diagnostic of control.diagnostics) lines.push(`${diagnostic.code}${diagnostic.path ? `: ${diagnostic.path}` : ""}`);
-  for (const change of control.changes) lines.push(`${change.run_id}: ${copy.backup}: ${change.backup}`);
-  if (control.status === "migration_required") lines.push(copy.migrationDescription, copy.manualDescription, copy.legacyDescription);
-  if (control.status === "repair_required") lines.push(copy.repairDescription);
-  return lines.join("\n");
-}
-
-export function renderControlMigrationDecision(plan, { registry = interactionLocales, language = "en", details = false } = {}) {
-  const copy = localePack(registry, language).installSetup.controlMigration;
-  const lines = [renderControlMigration(plan.control, { registry, language, details }),
-    replacement(copy.batchDescription, { count: plan.runs.length }), copy.backupDescription];
-  if (plan.approval_reset_count) lines.push(replacement(copy.resetDescription, { count: plan.approval_reset_count }));
+import { interactionLocales } from '../resources/context.js';
+import { localePack } from '../interaction-presentation.js';
+import { controlCounts } from './contract.js';
+
+export function renderControlCompatibility(control, { registry = interactionLocales, language = 'en', details = false } = {}) {
+  if (!control || control.status === 'not_checked') return '';
+  const pack = localePack(registry, language), copy = pack.installSetup.controlCompatibility;
+  const counts = controlCounts(control);
+  const lines = ['', pack.repositoryMaintenance.title, `${copy.target}: ${control.target}`,
+    `${copy.state}: ${copy.states[control.status] ?? control.status}`,
+    `run-folders-v1 · Run 4 · unsupported: ${counts.unsupported} · repair_required: ${counts.repair}`];
   if (details) {
-    for (const run of plan.runs) {
-      lines.push(`${copy.run}: ${run.run_id}`, `${copy.sourceRevision}: ${run.source_revision_id}`,
-        `${copy.nextGate}: ${run.next_gate}`,
-        ...run.prior_approvals.filter((row) => row.status !== "missing" || row.evidence)
-          .map((row) => `  ${row.gate}: ${row.status} (${row.evidence})`));
-    }
-    for (const diagnostic of plan.diagnostics) lines.push(`${diagnostic.run_id}: ${diagnostic.code}`);
-  }
-  lines.push(`[1] ${copy.migrateChoice}`, `[2] ${copy.skipChoice}`, `[3] ${copy.detailsChoice}`);
-  return lines.join("\n");
-}
-
-export function renderControlRepairOffer(control, { registry = interactionLocales, language = "en", details = false } = {}) {
-  const copy = localePack(registry, language).installSetup.controlRepair;
-  return [renderControlMigration(control, { registry, language, details }), copy.searchDescription,
-    `[1] ${copy.startChoice}`, `[2] ${copy.skipChoice}`, `[3] ${copy.detailsChoice}`].join("\n");
-}
-
-export function renderControlRepairPlan(plan, { registry = interactionLocales, language = "en", details = false } = {}) {
-  const pack = localePack(registry, language).installSetup;
-  const copy = pack.controlRepair;
-  const candidates = plan.items.filter((item) => item.available);
-  const lines = [copy.title, `${pack.controlMigration.target}: ${plan.target}`,
-    replacement(copy.availableDescription, { count: candidates.length }), copy.backupDescription];
-  if (candidates.some((item) => item.approval_reset)) lines.push(copy.resetDescription);
-  for (const item of plan.items) {
-    lines.push(`${item.run_id}: ${copy.kinds[item.kind]}`);
-    for (const finding of item.required) lines.push(`  ${copy.reasons[finding.code] ?? copy.manualDescription}${finding.path ? `: ${finding.path}` : ""}`);
-    if (details) for (const source of item.sources) lines.push(`  ${source.path}: ${source.source} ${source.commit ?? source.journal ?? ""}`);
-    if (details && item.available && item.source_content !== item.candidate_content) {
-      const before = item.source_content.split("\n");
-      const after = item.candidate_content.split("\n");
-      let start = 0;
-      while (start < before.length && start < after.length && before[start] === after[start]) start++;
-      let end = 0;
-      while (end < before.length - start && end < after.length - start && before.at(-1 - end) === after.at(-1 - end)) end++;
-      lines.push(...before.slice(start, before.length - end).map((line) => `- ${line}`),
-        ...after.slice(start, after.length - end).map((line) => `+ ${line}`));
-    }
+    for (const finding of control.diagnostics) lines.push(`${finding.code}${finding.path ? `: ${finding.path}` : ''}`);
+    for (const run of control.runs) lines.push(`${run.run_id}: ${run.status}`, ...run.diagnostics.map(finding => `  ${finding.code}`));
   }
-  for (const finding of plan.diagnostics) lines.push(`${copy.manualDescription}${finding.path ? `: ${finding.path}` : ""}${details ? ` (${finding.code})` : ""}`);
-  if (candidates.length) lines.push(`[1] ${copy.applyChoice}`);
-  lines.push(`[2] ${copy.skipChoice}`, `[3] ${copy.detailsChoice}`);
-  return lines.join("\n");
+  return lines.join('\n');
+}
+export function renderMaintenanceResult(report, options = {}) {
+  if (report.inspection_state !== 'complete') return `${report.target}\n${report.diagnostics.map(item => item.code).join('\n')}`;
+  return [renderControlCompatibility(report.compatibility, options), ...report.diagnostics.map(item => item.code)].join('\n');
+}
+export function renderStartupControlNotice(facts, { registry = interactionLocales, language = 'en', platform = process.platform } = {}) {
+  if (!facts.invocation) return '';
+  const pack = localePack(registry, language), copy = pack.installSetup.controlCompatibility;
+  const quote = platform === 'win32' ? value => `'${String(value).replaceAll("'", "''")}'`
+    : value => `'${String(value).replaceAll("'", `'"'"'`)}'`;
+  const command = [facts.invocation.executable, ...facts.invocation.argv].map(quote).join(' ');
+  return [pack.repositoryMaintenance.title, `${copy.target}: ${facts.target}`, `${copy.state}: ${copy.states[facts.status] ?? facts.status}`,
+    `${platform === 'win32' ? '& ' : ''}${command}`].join('\n');
 }

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-maintenance/service.js

@@ -1,38 +1,10 @@
-import { isAbsolute } from "node:path";
-import { directoryIdentity } from "../control-state/run-store-inspection.js";
-import { inspectControlMigration } from "./compatibility.js";
-import { migrateInstallationControl } from "./migration.js";
-import { repairInstallationControl } from "./repair.js";
-import { maintenanceResult } from "./contract.js";
-
-export async function runControlMaintenance(target, { guided = false, chooseMaintenance, confirmMigration, confirmRepair, readGitOriginals } = {}) {
-  if (typeof target !== "string" || !isAbsolute(target)) throw new Error("AGDF_MAINTENANCE_TARGET_REQUIRED");
-  const identity = directoryIdentity(target);
-  const verifyTarget = () => {
-    const current = directoryIdentity(target);
-    if (current.realpath !== identity.realpath || current.dev !== identity.dev || current.ino !== identity.ino) {
-      throw new Error("AGDF_MAINTENANCE_TARGET_CHANGED: inspect the target again before applying a new plan");
-    }
-  };
-  const reviewed = (callback) => async (plan) => {
-    verifyTarget();
-    const decision = await callback(plan);
-    verifyTarget();
-    return decision;
-  };
-  const before = inspectControlMigration(target);
-  if (!guided || ["absent", "current"].includes(before.status)) return maintenanceResult(target, before, { operation: guided ? "guided" : "inspect" });
-  if (![chooseMaintenance, confirmMigration, confirmRepair].every((callback) => typeof callback === "function")) {
-    throw new Error("AGDF_MAINTENANCE_INTERACTION_REQUIRED");
-  }
-  if (await reviewed(chooseMaintenance)(structuredClone(before)) !== "start") {
-    return maintenanceResult(target, inspectControlMigration(target), { operation: "guided", outcome: "deferred" });
-  }
-  let after = await migrateInstallationControl(target, { mode: "safe", confirmMigration: reviewed(confirmMigration) });
-  const diagnostics = [...after.diagnostics];
-  after = await repairInstallationControl(after, { chooseRepair: () => "start", confirmRepair: reviewed(confirmRepair), readGitOriginals });
-  const changed = after.changes.length + (after.repair?.items.filter((item) => item.outcome === "repaired").length ?? 0);
-  const outcome = changed ? (after.status === "current" ? "applied" : "partial")
-    : diagnostics.length || after.repair?.status === "needs_input" ? "needs_input" : "deferred";
-  return maintenanceResult(target, after, { operation: "guided", outcome, diagnostics });
+import { isAbsolute } from 'node:path';
+import { directoryIdentity } from '../control-state/run-store-inspection.js';
+import { inspectControlCompatibility } from './compatibility.js';
+import { maintenanceResult } from './contract.js';
+export async function runControlMaintenance(target, { guided = false } = {}) {
+  if (typeof target !== 'string' || !isAbsolute(target)) throw Error('AGDF_MAINTENANCE_TARGET_REQUIRED');
+  if (guided) throw Error('AGDF_CONTROL_MIGRATION_UNSUPPORTED');
+  directoryIdentity(target);
+  return maintenanceResult(target, inspectControlCompatibility(target));
 }

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-read/cockpit-pool.js

@@ -1,27 +1,41 @@
 import { Worker } from 'node:worker_threads';
 import { READ_LIMITS, ControlReadError } from './snapshot.js';
+export const READ_SESSION_CAPACITY = 4;
+export function createReadWorkerBudget(maximum = READ_SESSION_CAPACITY) {
+  if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > READ_SESSION_CAPACITY) throw Error('read_capacity_invalid');
+  const owners = new Set();
+  return Object.freeze({ acquire(owner) { if (owners.size >= maximum) return false; owners.add(owner); return true; },
+    release(owner) { owners.delete(owner); }, inspect() { return { occupied: owners.size, maximum }; } });
+}
 
 export class ReadWorkerPool {
   constructor(root, { timeout = READ_LIMITS.timeout, workerURL = new URL('./cockpit-worker.js', import.meta.url),
-    limits, maxOldGenerationSizeMb = 768 } = {}) {
+    limits, maxOldGenerationSizeMb = 768, budget } = {}) {
     this.root = root; this.timeout = timeout; this.workerURL = workerURL;
     this.limits = limits; this.maxOldGenerationSizeMb = maxOldGenerationSizeMb;
+    this.budget = budget;
     this.retiring = null; this.scope = null; this.changed = null; this.changeWaiter = null;
     this.worker = null; this.active = null; this.waiting = null; this.closed = false; this.sequence = 0;
   }
   #spawn() {
+    const token = {};
+    if (this.budget && !this.budget.acquire(token)) throw new ControlReadError('resource_limit');
     const env = { ...process.env }; delete env.AGDF_RUN_ID;
-    const worker = new Worker(this.workerURL, { workerData: { root: this.root, limits: this.limits }, env, execArgv: [],
-      resourceLimits: { maxOldGenerationSizeMb: this.maxOldGenerationSizeMb } });
+    let worker;
+    try { worker = new Worker(this.workerURL, { workerData: { root: this.root, limits: this.limits }, env, execArgv: [],
+      resourceLimits: { maxOldGenerationSizeMb: this.maxOldGenerationSizeMb } }); }
+    catch (e) { this.budget?.release(token); throw e; }
+    worker.once('exit', () => this.budget?.release(token));
     this.worker = worker;
-    worker.on('message', ({ id, result, error, changed }) => {
+    worker.on('message', ({ id, result, error, changed, phase }) => {
       if (this.worker !== worker) return;
+      if (phase === 'read_worker_ready') { if (this.active) this.active.startup_ms = performance.now() - this.active.started; return; }
       if (changed) {
         if (changed === this.scope?.snapshot_id) { this.changed = changed; this.changeWaiter?.finish(true); }
         return;
       }
       if (this.worker !== worker || this.active?.id !== id) return;
-      if (!error && result?.snapshot_id && ['snapshot', 'run', 'backlog_titles', 'document', 'context', 'artifact_readiness'].includes(this.active.request.operation)) {
+      if (!error && result?.snapshot_id && ['snapshot', 'run', 'document', 'context', 'artifact_readiness'].includes(this.active.request.operation)) {
         this.scope = { ...result, data: null }; this.changed = null;
         this.changeWaiter?.reject(new ControlReadError('cancelled'));
       }
@@ -34,6 +48,7 @@ export class ReadWorkerPool {
     clearTimeout(job.timer); job.signal?.removeEventListener('abort', job.abort);
     if (this.active === job) this.active = null;
     if (this.waiting === job) this.waiting = null;
+    this.lastTiming = { elapsed_ms: performance.now() - job.started, startup_ms: job.startup_ms ?? (job.reused ? 0 : null) };
     error ? job.reject(error) : job.resolve(result);
     this.#pump();
   }
@@ -59,21 +74,22 @@ export class ReadWorkerPool {
     try {
       if (!this.worker) this.#spawn();
       this.worker.postMessage({ id: job.id, ...job.request });
-    } catch { this.#reset('read_failed'); }
+    } catch (e) { this.#reset(e.code === 'resource_limit' ? 'resource_limit' : 'read_failed'); }
   }
-  request(request, signal) {
+  request(request, signal, { timeout = this.timeout } = {}) {
+    if (!Number.isFinite(timeout) || timeout <= 0) return Promise.reject(new ControlReadError('timeout'));
     if (this.closed) return Promise.reject(new ControlReadError('read_failed'));
     if (this.waiting) return Promise.reject(new ControlReadError('busy'));
     if (signal?.aborted) return Promise.reject(new ControlReadError('cancelled'));
     return new Promise((resolve, reject) => {
-      const job = { id: ++this.sequence, request, signal, resolve, reject };
+      const job = { id: ++this.sequence, request, signal, resolve, reject, started: performance.now(), reused: Boolean(this.worker) };
       job.abort = () => {
         if (this.active === job) {
           // The bounded read finishes inside its deadline; retain the immutable view for other readers.
           job.reject(new ControlReadError('cancelled'));
         } else this.#finish(job, new ControlReadError('cancelled'));
       };
-      job.timer = setTimeout(() => this.active === job ? this.#reset('timeout') : this.#finish(job, new ControlReadError('timeout')), this.timeout);
+      job.timer = setTimeout(() => this.active === job ? this.#reset('timeout') : this.#finish(job, new ControlReadError('timeout')), Math.min(timeout, this.timeout));
       signal?.addEventListener('abort', job.abort, { once: true });
       this.waiting = job; this.#pump();
     });

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-read/cockpit-worker.js

@@ -12,10 +12,11 @@ const changes = createControlChangeObserver(workerData.root, () => {
 });
 parentPort.on('message', ({ id, operation, selector, snapshot, input }) => {
   try {
-    const result = operation === 'snapshot' ? reader.snapshot(input?.run_id)
+    const result = operation === 'snapshot' ? reader.snapshot(input?.run_id, input?.view)
       : operation === 'run' ? reader.run(selector, snapshot)
+      : operation === 'archive' ? reader.archive(selector, snapshot, input?.resource_id)
+      : operation === 'planned' ? reader.planned(selector, snapshot)
       : operation === 'artifact_readiness' ? reader.artifactReadiness(input.run_id, snapshot, input.gate, input.expected_revision_id)
-      : operation === 'backlog_titles' ? reader.backlogTitles(input?.row_ids, snapshot)
       : operation === 'document' ? reader.document(selector, snapshot, input?.run_id)
       : operation === 'freshness' ? reader.freshness(snapshot)
       : operation === 'context' ? reader.context(selector, snapshot)
@@ -23,7 +24,7 @@ parentPort.on('message', ({ id, operation, selector, snapshot, input }) => {
       : operation === 'validate_context' ? reader.validateContext(input.context_id, input.generation)
       : operation === 'invalidate_context' ? reader.invalidateContext()
       : (() => { throw Object.assign(Error('resource_denied'), { code: 'resource_denied' }); })();
-    if (result.snapshot_id && ['snapshot', 'run', 'backlog_titles', 'document', 'context', 'artifact_readiness'].includes(operation)) {
+    if (result.snapshot_id && ['snapshot', 'run', 'document', 'context', 'artifact_readiness'].includes(operation)) {
       current = result.snapshot_id; changes.bind(reader.dependencies());
     }
     parentPort.postMessage({ id, result });