create-agdf 0.20.2 → 0.31.0

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

@@ -1,17 +1,23 @@
+import { baseResult, bindHostAction } from "./result.js";
+import { inspectArtefactRecordingMode } from '../control-state/run-artefact-recording.js';
+import { preparedCommandCall } from '../control-state/prepared-control-calls.js';
+import { inspectProjectState } from './project-state.js';
 import process from "node:process";
 import { DISPATCH_RECOVERY } from "../interaction-catalog.js";
 import { buildStatusCard, evaluateGateCheck, postApprovalTransition, printApprovalEnvelope, printGateCheckReport } from "../control-evaluation/gate-check.js";
 import { evaluateDoctor } from "../control-evaluation/doctor.js";
 import { evaluateDeliveryMap } from "../control-evaluation/delivery-map.js";
-import { readRuntimeContract } from "../resources/contracts.js";
-import { renderSkillDispatchInputRecovery, renderSkillDispatchRecovery, renderTaskTargetOrientation, renderActiveRunInventory } from "../interaction-presentation.js";
+import { readRuntimeContract, runtimeContractModules } from "../resources/contracts.js";
+import { renderSkillDispatchInputRecovery, renderSkillDispatchRecovery, renderTaskTargetOrientation, renderActiveRunInventory, renderRunInventory } from "../interaction-presentation.js";
 import { resolveTaskTarget, TaskTargetInputError } from "../task-target-resolution.js";
 import { SKILL_DISPATCH_PRESENTATION_LANGUAGE_RECOVERY, SkillDispatchInputError, emptySkillDispatchTiming } from "../skill-dispatch/contract.js";
-import { CONTROL_INSPECT_CONTRACT_VERSION, CONTROL_INSPECT_SCHEMA_VERSION, ReadSelectionError, normalizeControlInspectInput, inspectContractHelp, PRESENTATION_CATALOG_MODULE } from "./contract.js";
+import { CONTROL_INSPECT_CONTRACT_VERSION, CONTROL_INSPECT_SCHEMA_VERSION, ReadSelectionError, normalizeControlInspectInput, inspectContractHelp, inspectModuleRecoveryCall, OPERATION_CONTRACT_MODULES, PRESENTATION_CATALOG_MODULE } from "./contract.js";
 import { RUN_COMMAND_DESCRIPTORS, operationContract } from '../control-state/run-command-contract.js';
+import { PROPOSAL_COMMAND_KINDS, PROPOSAL_MATERIAL_SLOT } from '../control-state/run-command-schema.js';
 import { inspectRunOperation } from '../control-state/run-operation-status.js';
 import { resolveControlCommandTarget } from '../control-state/approval-command-contract.js';
 import { readRunState } from '../control-evaluation/run-state.js';
+import { readRunInventory } from '../control-state/run-inventory-reader.js';
 import { inspectArtifactReadiness } from "./artifact-readiness.js";
 import { policyForRunContent } from '../control-evaluation/run-step-policy.js';
 import { parseRunState } from '../control-state/run-state-parser.js';
@@ -21,6 +27,16 @@ import { readPresentationDocument, readPresentationPreview, readPresentationCata
 import { sourceRevisionBoundary } from '../control-state/run-revision-boundary.js';
 import { sourceRevisionQualityFacts } from '../control-state/run-source-revisions.js';
 import { readHistoryBytes } from '../control-state/run-revision-history.js';
+import { creationRunId } from '../control-state/run-create-command.js';
+import { inspectAuthoringInputs } from './authoring-inputs.js';
+import { PLANNING_COMMAND_KINDS } from '../control-state/run-command-schema.js';
+import { inspectPlannedEntry, inspectPlannedOperation, plannedEntryPath } from '../control-state/planned-entry.js';
+import { controlPathPresent } from '../control-read/snapshot.js';
+import { inspectPlannedHandoffOperation } from '../control-state/planned-handoff.js';
+import { readPlannedInventory, readWorkInventory } from '../control-state/planned-inventory.js';
+import { readControlLayout, CURRENT_LAYOUT } from '../control-state/control-layout.js';
+import { existsSync } from '../control-read/fs.js';
+import { join } from 'node:path';
 
 // Read-only projection of canonical CLI evaluators and Core validators. It never
 // writes, selects a Run or prepares approval. Git observations are unavailable.
@@ -64,61 +80,6 @@ function runtimeEvidence(expectedVersion, evidence, env) {
   });
 }
 
-function baseResult({ outcome, operation, runtime, timing }) {
-  return {
-    schema_version: CONTROL_INSPECT_SCHEMA_VERSION,
-    contract_version: CONTROL_INSPECT_CONTRACT_VERSION,
-    outcome,
-    terminal: outcome !== "inspect_result",
-    authorizes: false,
-    operation: operation ?? null,
-    runtime,
-    target: null,
-    report: null,
-    presentation: null,
-    recovery: null,
-    host_action: null,
-    timing,
-    diagnostics: [],
-  };
-}
-
-function bindHostAction(result) {
-  if (result.outcome === "inspect_result") {
-    result.host_action = Object.freeze({
-      mode: "consume_report_and_continue",
-      source: result.presentation?.markdown ? "presentation.markdown" : "report",
-      ...(result.presentation?.markdown ? { text: result.presentation.markdown } : {}),
-      allow_surrounding_text: true,
-      may_request_run_or_evidence: false,
-    });
-  } else if (result.presentation?.markdown) {
-    result.host_action = Object.freeze({
-      mode: "transmit_presentation_verbatim_and_stop",
-      source: "presentation.markdown",
-      text: result.presentation.markdown,
-      allow_surrounding_text: false,
-      may_request_run_or_evidence: false,
-    });
-  } else {
-    result.host_action = Object.freeze({
-      mode: "transmit_recovery_verbatim_and_stop",
-      source: "recovery.action",
-      text: result.recovery?.action ?? "",
-      allow_surrounding_text: false,
-      may_request_run_or_evidence: false,
-    });
-  }
-  return Object.freeze(result);
-}
-
-export function createInspectFailureResult(code, runtime, action) {
-  const result = baseResult({ outcome: "evaluator_error", runtime, timing: emptySkillDispatchTiming() });
-  result.recovery = { action };
-  result.diagnostics = [{ code }];
-  return bindHostAction(result);
-}
-
 function gateCheckPresentation(report, variant, reEvaluate) {
   if (variant === "approval-envelope" || variant === "status-card") {
     const lines = [];
@@ -143,10 +104,11 @@ export function createControlInspectService(dependencies = {}) {
   const gateCheck = dependencies.evaluateGateCheck ?? evaluateGateCheck;
   const deliveryMap = dependencies.evaluateDeliveryMap ?? evaluateDeliveryMap;
   const readContract = dependencies.readRuntimeContract ?? readRuntimeContract;
+  const readModules = dependencies.runtimeContractModules ?? runtimeContractModules;
   const validateControlReadBoundary = dependencies.validateControlReadBoundary;
   const deliveryMapDependencies = Object.freeze({ evaluateDoctor: doctor, buildStatusCard, postApprovalTransition });
 
-  return function executeControlInspect(rawInput) {
+  return function executeControlInspect(rawInput, { signal } = {}) {
     const started = now();
     const timing = emptySkillDispatchTiming();
     const runtime = runtimeEvidence(rawInput.expectedVersion, dependencies.runtimeEvidence, env);
@@ -172,6 +134,19 @@ export function createControlInspectService(dependencies = {}) {
       result.diagnostics = [{ code: "inspect_input_invalid", field,
         ...(inputError?.allowedValues?.length ? { allowed_values: [...inputError.allowedValues] } : {}),
       }];
+      if (field === 'module') {
+        const supplied = { operation: rawInput.operation,
+          ...Object.fromEntries([['module', 'contractModule'], ['working_directory', 'workingDirectory'],
+            ['primary_target', 'primaryTarget'], ['target_source', 'targetSource'], ['presentation_language', 'presentationLanguage'],
+            ['run_id', 'runId'], ['expected_revision_id', 'expectedRevisionId'], ['gate', 'gate'], ['target_id', 'targetId']]
+            .filter(([, key]) => rawInput[key] !== undefined).map(([field, key]) => [field, rawInput[key]])) };
+        // Preserve unsupported selectors too, so they prevent a misleading
+        // executable suggestion rather than disappearing from the new lookup.
+        for (const [field, key] of [['presentation_id', 'presentationId'], ['cursor', 'cursor'], ['planning', 'planning'], ['all_active', 'allActive']])
+          if (rawInput[key] !== undefined) supplied[field] = rawInput[key];
+        const next = inspectModuleRecoveryCall(supplied);
+        if (next) result.recovery.next_calls = [next];
+      }
       return bindHostAction(result);
     }
     timing.input_ms = round(milliseconds(started, now()));
@@ -196,6 +171,33 @@ export function createControlInspectService(dependencies = {}) {
         timing.total_ms = round(milliseconds(started, now()));
         return bindHostAction(result);
       }
+      if (input.target_id && resolveControlCommandTarget(target.governance_target).target_id !== input.target_id) {
+        const result = baseResult({ outcome: 'invalid_input', operation: input.operation, runtime, timing });
+        result.target = target;
+        result.diagnostics = [{ code: 'target_binding_mismatch', field: 'target_id' }];
+        result.recovery = { action: renderInputRecovery({ field: 'target_id', allowedValues: [] },
+          { registry: rawInput.interactionLocales, requestedLocale: input.presentation_language }) };
+        timing.total_ms = round(milliseconds(started, now()));
+        return bindHostAction(result);
+      }
+      if (input.operation === 'doctor' && dependencies.observeDoctor) {
+        const controlStarted = now();
+        return Promise.resolve(dependencies.observeDoctor(target.governance_target, input, signal)).then(report => {
+          timing.control_ms = round(milliseconds(controlStarted, now()));
+          const result = baseResult({ outcome: 'inspect_result', operation: input.operation, runtime, timing });
+          result.target = target; result.report = report;
+          // Reuse the existing localized inventory only when this reply holds
+          // the complete inventory. Paged replies remain explicit scoped data;
+          // the agent follows every advertised cursor before summarizing them.
+          if (input.all_active && report.available && report.completeness === 'complete'
+            && report.inventory?.accounted_count === report.runs?.length + (report.invalid_entries?.length ?? 0)) {
+            const renderStarted = now();
+            result.presentation = renderActiveRunInventory(report, rawInput.interactionLocales, input.presentation_language);
+            timing.render_ms = round(milliseconds(renderStarted, now()));
+          }
+          timing.total_ms = round(milliseconds(started, now())); return bindHostAction(result);
+        });
+      }
       const controlStarted = now();
       const { report, presentation, invalidModule, navigation } = stage(DISPATCH_RECOVERY.control_evaluation_failed, () => {
         validateControlReadBoundary?.(target.governance_target);
@@ -205,11 +207,14 @@ export function createControlInspectService(dependencies = {}) {
         };
         switch (input.operation) {
           case 'presentation-document':
-          case 'presentation-preview':
-            return { report: (input.operation === 'presentation-preview' ? readPresentationPreview : readPresentationDocument)(target.governance_target, {
+          case 'presentation-preview': {
+            const report = (input.operation === 'presentation-preview' ? readPresentationPreview : readPresentationDocument)(target.governance_target, {
               runId: input.run_id, gate: input.gate, revisionId: input.expected_revision_id,
               presentationId: input.presentation_id, targetId: input.target_id, cursor: input.cursor,
-            }), presentation: null };
+            });
+            if (input.operation === 'presentation-document' && report.available) report.delivery_instruction = 'If full text is requested and an explicitly configured verified host renderer consumes these MCP pages, fetch all next_cursor pages with the exact original binding; let that renderer verify and output the bytes. Otherwise send this content verbatim in a user-visible agent message BEFORE fetching next_cursor, repeating in byte order. Tool output alone is not delivery. Retain already read pages. Never claim complete delivery from a successful read alone. Rendering is not human approval.';
+            return { report, presentation: null };
+          }
           case 'runtime-generations':
           case 'native-qualification': {
             const state = readRunState(target.governance_target, { runId: input.run_id });
@@ -218,18 +223,40 @@ export function createControlInspectService(dependencies = {}) {
             if (!valid) return { report: { available: false, reason: 'operation_binding_stale_or_invalid', authorizes: false }, presentation: null };
             if (input.operation === 'runtime-generations') return { report: dependencies.runtimeControl?.status()
               ?? { available: false, reason: 'connection_control_unavailable', authorizes: false }, presentation: null };
-            const decision = gateCheck(target.governance_target, { runId: input.run_id, presentationLanguage: input.presentationLanguage });
+            const decision = gateCheck(target.governance_target, { runId: input.run_id, presentationLanguage: input.presentation_language });
             return { report: { available: true, run_id: input.run_id, revision_id: state.meta.revision_id,
               ui_rendering_support: 'unknown', action_qualification: { qualified: false, reason: 'host_context_unavailable', authorizes: false },
               business_readiness: { current_gate: decision.current_gate, status: decision.status,
                 next_operation: decision.next_operation, blocking_reason: decision.blocking_reason }, authorizes: false }, presentation: null };
           }
           case 'operation-contract': {
+            if (PLANNING_COMMAND_KINDS.includes(input.kind) && !input.run_id) {
+              const contract = operationContract(input.group, input.kind);
+              return { report: { ...contract, binding: { target_id: resolveControlCommandTarget(target.governance_target).target_id },
+                next_calls: [{ tool: input.group, kind: input.kind, instruction: contract.planning_capture?.instructions
+                  ?? 'Use the confirmed planning scope and original UUID; no Run/revision. Planning never approves a gate. Start a Run only from a deliberately selected complete source.' }] }, presentation: null };
+            }
+            if (['agdf_run', 'agdf_project'].includes(input.group) && !input.run_id) {
+              const prepared = preparedCommandCall(input.group, input.kind, { ...input, presentation_language: input.presentation_language,
+                target_id: resolveControlCommandTarget(target.governance_target).target_id });
+              return { report: { ...operationContract(input.group, input.kind),
+              binding: { target_id: resolveControlCommandTarget(target.governance_target).target_id },
+              prepared_call: prepared, next_calls: prepared?.state === 'ready' ? [prepared.call] : [],
+              next_action: input.group === 'agdf_project' ? 'Explicit fixed setup only. No Run, repair, installation or approval.'
+                : 'Fill the prepared title from the authorized original request, preserving its UUID and target. No prior Run/revision.' }, presentation: null };
+            }
             const state = readRunState(target.governance_target, { runId: input.run_id });
             const targetId = resolveControlCommandTarget(target.governance_target).target_id;
             const valid = parseRunState(state.content, input.run_id).valid && state.meta?.revision_id === input.expected_revision_id
               && runSealState(target.governance_target, state.content).status === 'valid';
-            return { report: valid ? { ...operationContract(input.group, input.kind, { gate: input.gate }),
+            return { report: valid ? { ...operationContract(input.group, input.kind, { gate: input.gate ?? state.current_gate }),
+              prepared_call: preparedCommandCall(input.group, input.kind, { ...input, presentation_language: input.presentation_language, target_id: targetId },
+                { gate: input.gate ?? state.current_gate, recording: inspectArtefactRecordingMode(state, input.gate ?? state.current_gate) }),
+              ...(input.kind === 'artefact.record' ? { recording: inspectArtefactRecordingMode(state, input.gate ?? state.current_gate) } : {}),
+              // Revision proposals are staged in their own slot. Offer that staging form with the
+              // revision commands and beside a material.stage form, whose prepared_call uses the gate's slot.
+              ...(PROPOSAL_COMMAND_KINDS.includes(input.kind) || input.kind === 'material.stage' ? { material_call: preparedCommandCall('agdf_record', 'material.stage',
+                { ...input, presentation_language: input.presentation_language, target_id: targetId }, { gate: PROPOSAL_MATERIAL_SLOT }) } : {}),
               ...(input.contract_module === PRESENTATION_CATALOG_MODULE ? {
                 inspect_contract: inspectContractHelp(),
                 presentation_catalog: readPresentationCatalog(target.governance_target, { runId: input.run_id,
@@ -243,7 +270,7 @@ export function createControlInspectService(dependencies = {}) {
                 quality_records: sourceRevisionQualityFacts(state, path => { try { return readHistoryBytes(target.governance_target, path).toString('utf8'); } catch { return undefined; } }),
               } } : {}),
               binding: { target_id: targetId, run_id: input.run_id, expected_revision_id: input.expected_revision_id },
-              current: (() => { const decision = gateCheck(target.governance_target, { runId: input.run_id, presentationLanguage: input.presentationLanguage });
+              current: (() => { const decision = gateCheck(target.governance_target, { runId: input.run_id, presentationLanguage: input.presentation_language });
                 return { current_gate: decision.current_gate, lifecycle: state.meta.lifecycle, status: decision.status, missing_approval: decision.missing_approval,
                   next_operation: decision.next_operation, completion: decision.completion,
                   artefacts: [...state.artefacts].filter(([type]) => ['UR', 'PRD', 'SD', 'TP', 'Brownfield Review', 'UX Intent Definition', 'Brownfield Analysis', 'CD+Tests', 'TP Review', 'Clean Implementation Review', 'CR', 'QA', 'OR'].includes(type))
@@ -252,13 +279,46 @@ export function createControlInspectService(dependencies = {}) {
                   source_bindings: readArtefactBindings(state.content).active.map(row => ({ binding_id: row.binding_id, source: row.source, destination: row.destination, relationship: row.relationship })) }; })() }
               : { available: false, authorizes: false, reason: 'operation_binding_stale_or_invalid' }, presentation: null };
           }
+          case 'project-state':
+            return { report: inspectProjectState(target.governance_target, input, dependencies.gitObservation), presentation: null };
           case 'operation-status':
-            return { report: { ...inspectRunOperation(target.governance_target, { runId: input.run_id, operationId: input.operation_id, targetId: resolveControlCommandTarget(target.governance_target).target_id }), expected_revision_id: input.expected_revision_id }, presentation: null };
+            if (input.planning) return { report: input.contract_module.startsWith('run.create_from_planned/')
+              ? inspectPlannedHandoffOperation(target.governance_target, input.planning.plan_id, input.operation_id)
+              : inspectPlannedOperation(target.governance_target, input.planning.plan_id, input.operation_id), presentation: null };
+            if (input.contract_module.startsWith('project.initialize/')) return { report: inspectProjectState(target.governance_target, input, dependencies.gitObservation), presentation: null };
+            return { report: { ...inspectRunOperation(target.governance_target, { runId: input.run_id ?? creationRunId(input.operation_id), operationId: input.operation_id, targetId: resolveControlCommandTarget(target.governance_target).target_id }), expected_revision_id: input.expected_revision_id ?? null,
+              ...(!input.run_id ? { lookup_scope: 'run_creation', recovery_instruction: 'This target-only lookup is for Run creation. For a write to an existing Run, inspect operation-status with the original run_id, original expected_revision_id and the same original UUID in module. An unavailable creation lookup does not prove an approval effect. Never substitute a fresh UUID or infer success from a changed gate alone.' } : {}) }, presentation: null };
           case "artifact-readiness":
             return { report: inspectArtifactReadiness(target.governance_target, {
               runId: input.run_id, gate: input.gate, expectedRevisionId: input.expected_revision_id,
               presentationLanguage: input.presentation_language,
             }), presentation: null };
+          case 'authoring-inputs':
+            return { report: inspectAuthoringInputs(target.governance_target, input, { gitObservation: dependencies.gitObservation }), presentation: null };
+          case 'planned-inventory': {
+            const inventory = readPlannedInventory(target.governance_target, { language: input.presentation_language });
+            return { report: { ...inventory, available: inventory.state !== 'unavailable' }, presentation: null };
+          }
+          case 'planned-entry': {
+            const path = plannedEntryPath(input.planning.plan_id);
+            if (!controlPathPresent(target.governance_target, `${path}/UR.md`)) {
+              const inventory = readPlannedInventory(target.governance_target, { language: input.presentation_language });
+              const unavailable = inventory.state === 'unavailable', incomplete = existsSync(join(target.governance_target, path));
+              return { report: { available: false, state: unavailable ? 'unavailable' : 'missing',
+                reason: unavailable ? 'planning_store_unavailable' : incomplete ? 'planned_document_missing' : 'planned_entry_missing',
+                plan_id: input.planning.plan_id, authorizes: false,
+                ...(unavailable ? { findings: inventory.findings } : {}),
+                ...(!unavailable && !incomplete && input.planning.expected_digest === null ? { next_calls: [{ tool: 'agdf_inspect',
+                  arguments: { operation: 'authoring-inputs', working_directory: input.working_directory,
+                    target_source: input.target_source, primary_target: input.primary_target,
+                    presentation_language: input.presentation_language, planning: input.planning },
+                  instruction: 'Read the version-matched UR inputs before capture. Planning authoring needs no module, gate, Run or revision.' }] } : {}) }, presentation: null };
+            }
+            const entry = inspectPlannedEntry(target.governance_target, input.planning.plan_id, { presentationLanguage: input.presentation_language });
+            return { report: input.planning.expected_digest && input.planning.expected_digest !== entry.digest
+              ? { available: false, reason: 'planning_source_stale', plan_id: input.planning.plan_id, authorizes: false }
+              : { ...entry, available: true }, presentation: null };
+          }
           case "doctor": {
             const evaluated = doctor(target.governance_target, selection);
             return { report: evaluated, presentation: input.all_active
@@ -280,20 +340,37 @@ export function createControlInspectService(dependencies = {}) {
                   primaryTarget: input.primary_target, language: input.presentation_language });
                 const kind = evaluated.next_operation?.operation_key;
                 const group = RUN_COMMAND_DESCRIPTORS[kind]?.group;
-                const nextCalls = catalog.state !== 'unavailable' && group ? [{ tool: 'agdf_inspect', arguments: {
-                  operation: 'operation-contract', ...common, module: `${group}/${kind}` } }] : [];
+                const nextCalls = [];
+                // Read the selected immutable document first. Operation help is
+                // optional and must not delay a user's read-only document task.
                 if (catalog.state === 'unique' && catalog.complete_scan && catalog.page_complete)
                   nextCalls.push({ tool: 'agdf_inspect', arguments: catalog.candidates[0].read_arguments });
-                navigation = { presentation_catalog: catalog, next_calls: nextCalls };
+                if (catalog.state !== 'unavailable' && group) nextCalls.push({ tool: 'agdf_inspect', arguments: {
+                  operation: 'operation-contract', ...common, module: `${group}/${kind}` } });
+                // An explicit reusable locator, not retained connection state or
+                // authority. Reuse passes through the ordinary target/Run checks.
+                const { expected_revision_id: _revision, ...readContext } = common;
+                navigation = { read_context: readContext, presentation_catalog: catalog, next_calls: nextCalls };
               }
             } catch { /* Advisory navigation unavailable. */ }
             return { report: evaluated, navigation, presentation: gateCheckPresentation(evaluated, input.variant, evaluate) };
           }
+          case "inventory": {
+            // Read-only inventory also works before control initialization. An
+            // existing config still goes through strict layout validation.
+            if (existsSync(join(target.governance_target, '.agdf/control/config.json'))
+              && readControlLayout(target.governance_target).layout === CURRENT_LAYOUT) return { report: readWorkInventory(target.governance_target, { language: input.presentation_language }), presentation: null };
+            const inventory = readRunInventory(target.governance_target, { language: input.presentation_language });
+            return { report: inventory, presentation: renderRunInventory(inventory, rawInput.interactionLocales, input.presentation_language) };
+          }
           case "delivery-map": {
             const evaluated = deliveryMap(target.governance_target, selection, deliveryMapDependencies);
             return { report: evaluated, presentation: null };
           }
           case "contract": {
+            if (!input.contract_module) return { report: { available: true, modules: readModules(),
+              operation_modules: OPERATION_CONTRACT_MODULES, inspect_contract: inspectContractHelp(),
+              instruction: 'contract reads a listed runtime module. operation-contract reads an exact listed group/kind; omit planning, gate and Run/revision for creation help. Copy operation-specific arguments; never copy whole command bindings.', authorizes: false }, presentation: null };
             const read = readContract(input.contract_module, { pluginRoot: null });
             if (!read.ok) return { report: null, presentation: null, invalidModule: read };
             return { report: { module: read.module, content: read.content }, presentation: { markdown: read.content, authorizes: false } };
@@ -335,3 +412,5 @@ export function createControlInspectService(dependencies = {}) {
     }
   };
 }
+
+export { createInspectFailureResult } from "./result.js";

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");