feat: add protocol compatibility diagnostics and historical readers

This commit is contained in:
2026-11-16 10:13:05 +00:00
parent a8a8faf5d8
commit f10c237d44
48 changed files with 1382 additions and 13 deletions
@@ -0,0 +1,170 @@
package net.intrepid.aiengineering.verification;
import net.intrepid.aiengineering.filesystem.*;
import net.intrepid.aiengineering.project.*;
import net.intrepid.aiengineering.work.*;
import net.intrepid.aiengineering.discussion.*;
import net.intrepid.aiengineering.decision.Decision;
import net.intrepid.aiengineering.planning.Plan;
import net.intrepid.aiengineering.artifact.Artifact;
import net.intrepid.aiengineering.agent.AgentRun;
import tools.jackson.databind.node.ObjectNode;
import java.nio.file.*;
import java.util.*;
/** Format inspection only. Does not lock, write, migrate, reopen or reinterpret historical approvals. */
public final class CompatibilityService {
public enum State { CURRENT, LEGACY_COMPATIBLE, UNSUPPORTED, INVALID }
public record Summary(State state, boolean readable, boolean migrationRequired, String command) {}
public record Finding(String path, String recordType, State state, Map<String, String> versions,
List<String> missingFields, String message) {
public Finding { versions = Collections.unmodifiableMap(new LinkedHashMap<>(versions)); missingFields = List.copyOf(missingFields); }
}
public record Report(int schemaVersion, String cliVersion, int currentProtocolVersion,
List<Integer> readableProtocolVersions, List<FormatVersions.Format> formats, State state,
boolean readable, boolean migrationRequired, List<Finding> findings, List<String> guidance) {
public Report {
readableProtocolVersions = List.copyOf(readableProtocolVersions); formats = List.copyOf(formats);
findings = List.copyOf(findings); guidance = List.copyOf(guidance);
}
public Summary summary() { return new Summary(state, readable, migrationRequired, "aie project compatibility --format json"); }
}
private record RecordType(String area, Class<?> type, String bodyField) {}
private static final List<RecordType> RECORDS = List.of(
new RecordType("discussions", DiscussionEntry.class, "text"), new RecordType("decisions", Decision.class, "text"),
new RecordType("plans", Plan.class, "description"), new RecordType("topics", Topic.class, "description"),
new RecordType("surveys", Survey.class, "description"), new RecordType("dispositions", Disposition.class, "reason"),
new RecordType("agent-runs", AgentRun.class, "task"), new RecordType("epic", Epic.class, "reason"));
private static final List<String> WORK_DEFAULTS = List.of("plans", "completions", "events", "archived",
"topics", "surveys", "dispositions", "agentRuns", "epic");
public Report inspect(Path root) {
var findings = new ArrayList<Finding>();
inspect(root, ".ai-engineering/ai-engineering.yaml", "project", ProjectConfig.class, null, false, findings);
Path manifest = Filespace.resolve(root, ".ai-engineering/protocol.json");
if (Files.exists(manifest)) inspect(root, ".ai-engineering/protocol.json", "manifest", ProtocolGuide.Manifest.class, null, false, findings);
else findings.add(new Finding(".ai-engineering/protocol.json", "manifest", State.LEGACY_COMPATIBLE, Map.of(), List.of(),
"No discovery manifest. Existing records are inspected independently; onboard can install the entry instructions."));
if (findings.stream().noneMatch(f -> f.recordType().equals("manifest") && (f.state() == State.UNSUPPORTED || f.state() == State.INVALID))) {
try { ProtocolGuide.validate(root); }
catch (RuntimeException e) { invalid(findings, ".ai-engineering/protocol.json", "entry-contract", e.getMessage()); }
}
Path workspace = Filespace.resolve(root, ".ai-engineering/works");
Path sequence = Filespace.resolve(root, ".ai-engineering/works/.sequence.yaml");
if (Files.exists(sequence)) inspect(root, root.relativize(sequence).toString(), "sequence", WorkService.Sequence.class, null, false, findings);
visit(root, workspace, findings, folder -> {
Path workFile = folder.resolve("work.md");
inspect(root, relative(root, workFile), "work", Work.class, null, true, findings);
if (!Files.exists(sequence)) invalid(findings, relative(root, sequence), "sequence", "Missing Work sequence");
for (var record : RECORDS) {
Path area = Filespace.resolve(root, relative(root, folder.resolve(record.area())));
if (!Files.exists(area)) continue;
visit(root, area, findings, file -> inspectRecord(root, file, record, findings));
Path history = Filespace.resolve(root, relative(root, area.resolve(".history")));
if (Files.exists(history)) visit(root, history, findings,
revisions -> visit(root, revisions, findings, file -> inspectRecord(root, file, record, findings)));
}
Path evidence = Filespace.resolve(root, relative(root, folder.resolve("artifacts/evidence")));
if (Files.exists(evidence)) visit(root, evidence, findings, artifact -> {
Path manifestPath = artifact.resolve("artifact.yaml");
inspect(root, relative(root, manifestPath), "artifact", Artifact.class, null, false, findings);
if (findings.getLast().state() == State.INVALID || findings.getLast().state() == State.UNSUPPORTED) return;
var record = Documents.read(manifestPath, Artifact.class);
Class<?> receipt = record.origin().startsWith(PlanCoordinator.RECEIPT_ORIGIN) ? PlanCoordinator.Receipt.class
: record.origin().startsWith(EpicCoordinator.RECEIPT_ORIGIN) ? EpicCoordinator.Receipt.class : null;
if (receipt != null) inspect(root, relative(root, Filespace.resolve(folder, record.path())), "completion-receipt", receipt, null, false, findings);
});
// Missing referenced records are not evidence of a readable historical format.
try {
Work work = Documents.readDocument(workFile, Work.class);
var references = new LinkedHashMap<String, List<String>>();
references.put("discussions", work.discussions()); references.put("decisions", work.decisions());
references.put("plans", work.plans()); references.put("topics", work.topics()); references.put("surveys", work.surveys());
references.put("dispositions", work.dispositions()); references.put("agent-runs", work.agentRuns());
references.put("epic", work.epic() ? List.of(work.id()) : List.of());
references.forEach((area, ids) -> ids.forEach(id -> {
String path = relative(root, folder.resolve(area).resolve(id + ".md"));
if (!Files.isRegularFile(Filespace.resolve(root, path))) invalid(findings, path, area, "Missing referenced record");
}));
for (String id : work.artifacts()) {
String path = relative(root, folder.resolve("artifacts/evidence/" + id + "/artifact.yaml"));
if (!Files.isRegularFile(Filespace.resolve(root, path))) invalid(findings, path, "artifact", "Missing referenced artifact manifest");
}
} catch (RuntimeException ignored) { /* The Work's parse diagnostic was already recorded above. */ }
});
// Presence/version inspection is independent from structural/evidence validation.
State state = findings.stream().map(Finding::state).max(Comparator.naturalOrder()).orElse(State.CURRENT);
boolean readable = state == State.CURRENT || state == State.LEGACY_COMPATIBLE;
var guidance = new ArrayList<String>();
if (readable) guidance.add("No migration is required. Keep readable historical and COMPLETED Works in their existing formats.");
else guidance.add("Unsupported versions require a compatible CLI; invalid files require deliberate repair. No migration route is inferred.");
guidance.add("onboard refreshes entry instructions only, with backups; it does not convert Works or their history.");
guidance.add("Compatibility describes storage readability, not completion readiness or evidence integrity. Run aie project validate separately.");
return new Report(1, ProtocolContract.CLI_VERSION, ProtocolContract.CURRENT, ProtocolContract.READABLE,
FormatVersions.supported(), state, readable, false, findings, guidance);
}
private void inspectRecord(Path root, Path path, RecordType type, List<Finding> findings) {
inspect(root, relative(root, path), type.area(), type.type(), type.bodyField(), true, findings);
}
private static String relative(Path root, Path path) { return root.relativize(path).toString(); }
private void visit(Path root, Path directory, List<Finding> findings, java.util.function.Consumer<Path> operation) {
try {
Path safe = Filespace.resolve(root, relative(root, directory));
for (Path child : Filespace.children(safe)) {
try { operation.accept(Filespace.resolve(root, relative(root, child))); }
catch (RuntimeException e) { invalid(findings, relative(root, child), "directory", e.getMessage()); }
}
} catch (RuntimeException e) { invalid(findings, relative(root, directory), "directory", e.getMessage()); }
}
private static void invalid(List<Finding> findings, String path, String type, String message) {
findings.add(new Finding(path, type, State.INVALID, Map.of(), List.of(), message == null ? "Cannot inspect record" : message));
}
private static final class UnsupportedFormat extends RuntimeException {
UnsupportedFormat(String message) { super(message); }
}
private boolean version(ObjectNode metadata, String field, Integer defaultVersion, FormatVersions.Format format, Map<String, String> versions) {
var value = metadata.get(field);
versions.put(field, value == null ? defaultVersion == null ? "missing" : "implicit " + defaultVersion : value.toString());
int actual;
if (value == null && defaultVersion != null) actual = defaultVersion;
else {
if (value == null || !value.isIntegralNumber() || value.bigIntegerValue().signum() <= 0)
throw ProtocolException.validation(field + " must be a positive integer");
if (!value.canConvertToInt()) throw new UnsupportedFormat("Unsupported " + field + ": " + value);
actual = value.intValue();
}
if (!format.supports(actual)) throw new UnsupportedFormat("Unsupported " + field + ": " + actual);
return actual != format.currentWriteVersion();
}
private void inspect(Path root, String relative, String name, Class<?> type, String bodyField, boolean markdown, List<Finding> findings) {
var versions = new LinkedHashMap<String, String>(); var missing = new ArrayList<String>();
try {
Path path = Filespace.resolve(root, relative);
boolean json = type == ProtocolGuide.Manifest.class || type == PlanCoordinator.Receipt.class || type == EpicCoordinator.Receipt.class;
ObjectNode metadata = markdown ? Documents.metadata(path) : json
? Documents.readJson(path, ObjectNode.class) : Documents.read(path, ObjectNode.class);
if (metadata == null) throw ProtocolException.validation("Expected record object");
var format = type == WorkService.Sequence.class ? FormatVersions.SEQUENCE
: type == ProtocolGuide.Manifest.class ? FormatVersions.MANIFEST : FormatVersions.SCHEMA;
boolean legacy = version(metadata, "schemaVersion", null, format, versions);
if (markdown) legacy |= version(metadata, "documentVersion", 1,
bodyField == null ? FormatVersions.METADATA : FormatVersions.DOCUMENT, versions);
if (type == ProtocolGuide.Manifest.class) {
legacy |= version(metadata, "protocolVersion", 1,
new FormatVersions.Format("protocol-contract", ProtocolContract.CURRENT, ProtocolContract.READABLE), versions);
if (!metadata.has("protocolVersion")) { legacy = true; missing.add("protocolVersion"); }
}
if (type == Work.class) for (String field : WORK_DEFAULTS) if (!metadata.has(field)) { missing.add(field); legacy = true; }
if (markdown) Documents.readMarkdownDocument(path, type, bodyField);
else if (json) Documents.readJson(path, type);
else Documents.read(path, type);
findings.add(new Finding(relative, name, legacy ? State.LEGACY_COMPATIBLE : State.CURRENT, versions, missing,
legacy ? "Readable legacy format; defaults are interpreted in memory. No migration required."
: "Readable current format."));
} catch (UnsupportedFormat e) {
findings.add(new Finding(relative, name, State.UNSUPPORTED, versions, missing, e.getMessage() + "; use a compatible CLI."));
} catch (RuntimeException e) {
findings.add(new Finding(relative, name, State.INVALID, versions, missing, e.getMessage() == null ? "Invalid record" : e.getMessage()));
}
}
}