feat: add protocol compatibility diagnostics and historical readers

This commit is contained in:
Nilton Constantino
2026-11-16 10:13:05 +00:00
parent bd2c9133da
commit 3dd04a730f
48 changed files with 1382 additions and 13 deletions
@@ -0,0 +1,173 @@
package net.intrepid.aiengineering;
import net.intrepid.aiengineering.cli.EngineeringCli;
import net.intrepid.aiengineering.filesystem.*;
import net.intrepid.aiengineering.project.*;
import net.intrepid.aiengineering.verification.*;
import net.intrepid.aiengineering.work.*;
import tools.jackson.databind.node.ObjectNode;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.io.*;
import java.nio.file.*;
import java.util.*;
import static org.assertj.core.api.Assertions.*;
import static net.intrepid.aiengineering.verification.CompatibilityService.State.*;
class CompatibilityTest {
@TempDir Path root;
private record Result(int code, String out, String err) {}
private Result run(String... args) {
var out = new StringWriter(); var err = new StringWriter();
int code = new EngineeringCli(root).execute(new PrintWriter(out), new PrintWriter(err), args);
return new Result(code, out.toString(), err.toString());
}
private String ok(String... args) {
var result = run(args); assertThat(result.code()).as(result.err() + result.out()).isZero(); return result.out();
}
private void init() { ok("init", "--name", "Test"); }
private Path work() { return root.resolve(".ai-engineering/works/WRK-0001-delivered-baseline"); }
private CompatibilityService.Report inspect() { return new CompatibilityService().inspect(root); }
private Map<String, String> snapshot(Path directory) throws Exception {
var result = new TreeMap<String, String>();
try (var paths = Files.walk(directory)) {
for (Path path : paths.filter(Files::isRegularFile).toList())
result.put(directory.relativize(path).toString(), Base64.getEncoder().encodeToString(Files.readAllBytes(path)));
}
return result;
}
private void baseline() throws Exception {
init(); ok("work", "create", "Delivered baseline");
Path fixtures = Path.of(getClass().getResource("/compatibility/baseline-v1/.ai-engineering").toURI());
try (var files = Files.walk(fixtures)) {
for (Path path : files.filter(Files::isRegularFile).toList()) {
Path target = root.resolve(".ai-engineering").resolve(fixtures.relativize(path));
Files.createDirectories(target.getParent()); Files.copy(path, target, StandardCopyOption.REPLACE_EXISTING);
}
}
}
@Test void currentProjectExposesSupportedFormatsAndDoesNotWriteDuringInspection() throws Exception {
init(); var before = snapshot(root);
var report = inspect();
assertThat(report.state()).isEqualTo(CURRENT); assertThat(report.readable()).isTrue();
assertThat(report.migrationRequired()).isFalse();
assertThat(report.currentProtocolVersion()).isEqualTo(1);
assertThat(report.formats()).contains(FormatVersions.SEQUENCE, FormatVersions.DOCUMENT);
assertThat(ok("project", "compatibility", "--format", "json")).contains("\"cliVersion\"", "\"readableVersions\"", "\"migrationRequired\" : false");
assertThat(ok("status", "--format", "json")).contains("\"compatibility\"", "\"state\" : \"CURRENT\"");
assertThat(snapshot(root)).isEqualTo(before);
}
@Test void frozenDeliveredWorkRetainsMeaningApprovalsEvidenceAndBytesAcrossReadsAndOnboarding() throws Exception {
baseline(); var before = snapshot(root); var historical = snapshot(root.resolve(".ai-engineering/works"));
var service = new VerificationService();
var context = service.context(root, "WRK-0001");
assertThat(context.work().status()).isEqualTo(Work.Status.COMPLETED);
assertThat(context.work().topics()).isEmpty(); assertThat(context.work().epic()).isFalse();
assertThat(context.decisions().getFirst().approvalStatus().name()).isEqualTo("ACCEPTED");
assertThat(context.work().completions().getFirst().origin()).isEqualTo(Work.CompletionOrigin.HUMAN);
assertThat(context.work().completions().getFirst().humanApproved()).isTrue();
String digest = context.work().completions().getFirst().scopeHash();
assertThat(service.scopeHash(root, context.work())).isEqualTo(digest);
var report = inspect(); assertThat(report.state()).isEqualTo(LEGACY_COMPATIBLE);
assertThat(report.readable()).isTrue(); assertThat(report.migrationRequired()).isFalse();
assertThat(report.findings()).anySatisfy(finding -> {
assertThat(finding.recordType()).isEqualTo("work");
assertThat(finding.missingFields()).contains("topics", "agentRuns", "epic");
});
for (String[] args : List.of(new String[]{"project", "compatibility", "--format", "json"},
new String[]{"project", "validate"}, new String[]{"status"}, new String[]{"next-actions"},
new String[]{"work", "context", "WRK-0001"}, new String[]{"decision", "history", "WRK-0001", "DEC-0001"})) ok(args);
assertThat(snapshot(root)).isEqualTo(before);
ok("onboard");
assertThat(snapshot(root.resolve(".ai-engineering/works"))).isEqualTo(historical);
var after = service.context(root, "WRK-0001");
assertThat(after.work()).isEqualTo(context.work()); assertThat(after.decisions()).isEqualTo(context.decisions());
assertThat(after.discussionHistory()).isEqualTo(context.discussionHistory()); assertThat(after.artifacts()).isEqualTo(context.artifacts());
assertThat(service.scopeHash(root, after.work())).isEqualTo(digest);
assertThat(inspect().state()).isEqualTo(LEGACY_COMPATIBLE); // refreshing the manifest did not migrate the Work.
ok("project", "validate");
assertThat(snapshot(root.resolve(".ai-engineering/works"))).isEqualTo(historical);
}
@Test void newerContractsAreDiagnosableAndCannotBeSilentlyDowngraded() throws Exception {
init(); Path manifest = root.resolve(".ai-engineering/protocol.json"); String original = Files.readString(manifest);
for (String field : List.of("protocolVersion", "schemaVersion")) {
var metadata = Documents.parseJson(original, ObjectNode.class); metadata.put(field, 99);
Files.writeString(manifest, Documents.json(metadata)); var before = snapshot(root);
assertThat(inspect().state()).isEqualTo(UNSUPPORTED); assertThat(inspect().migrationRequired()).isFalse();
var result = run("project", "compatibility", "--format", "json");
assertThat(result.code()).isEqualTo(4); assertThat(result.out()).contains("UNSUPPORTED", field, "99");
assertThat(run("onboard").code()).isEqualTo(4);
assertThat(run("work", "create", "Do not write").code()).isEqualTo(4);
assertThat(snapshot(root)).isEqualTo(before);
}
}
@Test void manifestCannotHideAnUnsupportedWorkOrHistoricalRevision() throws Exception {
baseline(); ok("onboard"); // current manifest, with genuine old formats beneath it.
Path prior = work().resolve("decisions/.history/DEC-0001/r0001.md"); String original = Files.readString(prior);
Files.writeString(prior, original.replace("\"schemaVersion\": 1", "\"schemaVersion\": 77"));
var before = snapshot(root); var report = inspect();
assertThat(report.readable()).isFalse(); assertThat(report.state()).isEqualTo(UNSUPPORTED);
assertThat(report.findings()).anySatisfy(finding -> {
assertThat(finding.path()).endsWith("decisions/.history/DEC-0001/r0001.md");
assertThat(finding.state()).isEqualTo(UNSUPPORTED);
});
assertThat(snapshot(root)).isEqualTo(before);
Files.writeString(prior, original);
Path path = work().resolve("work.md"); String work = Files.readString(path);
Files.writeString(path, work.replace("\"schemaVersion\": 1", "\"schemaVersion\": 88"));
assertThat(inspect().state()).isEqualTo(UNSUPPORTED);
assertThat(run("project", "compatibility").code()).isEqualTo(4);
}
@Test void incompatibleDocumentsAndMalformedVersionsAreReportedWithoutMutation() throws Exception {
baseline(); Path entry = work().resolve("discussions/DSC-0001.md"); String original = Files.readString(entry);
for (String version : List.of("99", "99999999999999999999999", "\"2\"", "null", "0", "-1", "2.5")) {
// Use a valid YAML envelope so that the version itself, rather than YAML syntax, is diagnosed.
var metadata = Documents.parse(original.substring(4, original.lastIndexOf("---")), ObjectNode.class);
String yaml = Documents.yaml(metadata).replaceFirst("^---\\n", "");
Files.writeString(entry, "---\n" + yaml + "documentVersion: " + version + "\n---\n");
var before = snapshot(root); var finding = inspect().findings().stream().filter(f -> f.path().endsWith("discussions/DSC-0001.md")).findFirst().orElseThrow();
assertThat(finding.state()).isEqualTo(version.startsWith("99") ? UNSUPPORTED : INVALID);
assertThat(snapshot(root)).isEqualTo(before);
}
}
@Test void missingReferencesAndUnknownFieldsAreNotLabelledLegacyCompatible() throws Exception {
baseline(); Path path = work().resolve("discussions/DSC-0001.md"); String original = Files.readString(path);
Files.delete(path); assertThat(inspect().state()).isEqualTo(INVALID);
Files.writeString(path, original.replace("\"schemaVersion\": 1", "\"unknownField\": true,\n\"schemaVersion\": 1"));
assertThat(inspect().state()).isEqualTo(INVALID);
}
@Test void completionReceiptFormatsAreInspectedButOrdinaryEvidenceIsNotParsedAsProtocol() throws Exception {
init(); ok("work", "create", "Plan delivery");
Files.writeString(root.resolve("evidence.txt"), "This is evidence, not YAML or JSON.\n");
ok("artifact", "add", "WRK-0001", "--file", "evidence.txt", "--purpose", "Observed test result");
ok("plan", "create", "WRK-0001", "--title", "Delivery");
ok("plan", "step", "add", "WRK-0001", "PLN-0001", "--title", "Verify");
ok("plan", "step", "status", "WRK-0001", "PLN-0001", "TSK-0001", "COMPLETED", "--by", "agent", "--reason", "Verified", "--evidence", "ART-0001");
assertThat(inspect().state()).isEqualTo(CURRENT);
var receipt = inspect().findings().stream().filter(f -> f.recordType().equals("completion-receipt")).findFirst().orElseThrow();
Path path = root.resolve(receipt.path()); var metadata = Documents.readJson(path, ObjectNode.class);
metadata.put("schemaVersion", 99); Files.writeString(path, Documents.json(metadata));
var before = snapshot(root);
assertThat(inspect().findings()).anySatisfy(finding -> {
assertThat(finding.recordType()).isEqualTo("completion-receipt");
assertThat(finding.state()).isEqualTo(UNSUPPORTED);
});
assertThat(snapshot(root)).isEqualTo(before);
}
@Test void projectWithoutDiscoveryFilesRemainsReadableAndInspectionIsIdempotent() throws Exception {
init();
for (String file : List.of("README.md", "AGENTS.md", "protocol.json")) Files.delete(root.resolve(".ai-engineering/" + file));
var before = snapshot(root); String first = ok("project", "compatibility", "--format", "json");
assertThat(first).contains("LEGACY_COMPATIBLE", "No discovery manifest");
assertThat(ok("project", "compatibility", "--format", "json")).isEqualTo(first);
assertThat(snapshot(root)).isEqualTo(before); ok("project", "validate");
}
@Test void diagnosticRejectsSymlinksWithoutReadingTheTarget() throws Exception {
init(); Path outside = Files.createTempFile("aie-compatibility-outside-", ".txt");
Files.writeString(outside, "PRIVATE TARGET CONTENT");
Path manifest = root.resolve(".ai-engineering/protocol.json"); Files.delete(manifest); Files.createSymbolicLink(manifest, outside);
var result = run("project", "compatibility", "--format", "json");
assertThat(result.code()).isEqualTo(2); assertThat(result.err()).contains("Symlink rejected").doesNotContain("PRIVATE TARGET CONTENT");
}
}
@@ -105,7 +105,7 @@ class ProtocolIntegrationTest {
}
@Test void cliSmokeAndHelpForEveryCommand() {
assertThat(ok("--version").out()).isEqualTo("ai-engineering 0.1.0\n");
for (String command : new String[]{"", "init", "project", "project show", "project validate", "repo", "repo add", "repo list",
for (String command : new String[]{"", "init", "project", "project show", "project validate", "project compatibility", "repo", "repo add", "repo list",
"work", "work create", "work update", "work list", "work show", "work validate", "work context", "discussion", "discussion add",
"discussion list", "discussion migrate", "decision", "decision draft", "decision list", "decision show", "decision update",
"decision accept", "decision reject", "decision revise", "decision history", "artifact", "artifact add",