feat: add protocol compatibility diagnostics and historical readers
This commit is contained in:
@@ -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()));
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user