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 versions, List 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 readableProtocolVersions, List formats, State state, boolean readable, boolean migrationRequired, List findings, List 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 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 WORK_DEFAULTS = List.of("plans", "completions", "events", "archived", "topics", "surveys", "dispositions", "agentRuns", "epic", "guidance"); public Report inspect(Path root) { var findings = new ArrayList(); 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 : record.origin().startsWith(net.intrepid.aiengineering.legacyimport.DiscussionImport.RECEIPT_ORIGIN) ? net.intrepid.aiengineering.legacyimport.DiscussionImport.Receipt.class : null; if (receipt != null) inspect(root, relative(root, Filespace.resolve(folder, record.path())), receipt == net.intrepid.aiengineering.legacyimport.DiscussionImport.Receipt.class ? "discussion-import-receipt" : "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>(); 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(); 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 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 findings, java.util.function.Consumer 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 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 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 findings) { var versions = new LinkedHashMap(); var missing = new ArrayList(); try { Path path = Filespace.resolve(root, relative); boolean json = type == ProtocolGuide.Manifest.class || type == PlanCoordinator.Receipt.class || type == EpicCoordinator.Receipt.class || type == net.intrepid.aiengineering.legacyimport.DiscussionImport.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())); } } }