Export handoff documents with conformance packs

This commit is contained in:
Meta Vens 2026-07-09 01:54:43 +01:00
commit d158425ace
6 changed files with 111 additions and 1 deletions

View file

@ -280,6 +280,12 @@ Exit criteria:
Recently cut:
- Conformance export now copies handoff documents into `handoffs/*.json` rather
than exporting Eve-local source paths only. The export carries handoff export
paths for EveConformance, Sai/Norn plugins, Aetheria, and EveUnity; the
generic consumer verifies those copied documents for conformance, plugin,
provider, and runtime handoff assertions. Owner repos can inspect the
boundary map from the exported pack itself.
- EveConformance now has a machine-readable handoff at
`tools/conformance/eveconformance-handoff.json` and a verifier at
`scripts/run-eveconformance-handoff-smoke.ps1`. The handoff names the

View file

@ -85,6 +85,11 @@ machine-readable EveConformance split map. That handoff is incubation evidence:
it names which runner, schema, consumer-smoke, and fixture-corpus paths move
when the conformance body leaves Eve.
Handoff documents are also copied into the export under `handoffs/*.json`.
Consumer smokes assert those exported copies, not just Eve-local source paths,
so owner repos can inspect plugin, provider, runtime, and conformance handoff
maps from the exported pack itself.
The conformance export includes runtime `capabilityManifestPath` and
`capabilityManifestErrors` fields so external consumers can distinguish a
generic projection runtime from a runtime that can project plugin-declared

View file

@ -90,6 +90,12 @@ if (Test-Path -LiteralPath (Join-Path $absoluteExportDirectory "index.json")) {
if ($export.conformanceHandoffPath -ne $expectedPath) {
throw "Conformance export does not point at EveConformance handoff. Expected $expectedPath got $($export.conformanceHandoffPath)"
}
if (-not $export.conformanceHandoffExportPath) {
throw "Conformance export missing EveConformance handoff export path"
}
if (-not (Test-Path -LiteralPath (Join-Path $absoluteExportDirectory $export.conformanceHandoffExportPath))) {
throw "Conformance export missing EveConformance handoff document: $($export.conformanceHandoffExportPath)"
}
foreach ($packId in @("core", "plugin", "provider", "runtime")) {
$pack = @($export.packs) | Where-Object { $_.id -eq $packId } | Select-Object -First 1
if (-not $pack) {

View file

@ -48,6 +48,7 @@ node $consumerScript $consumerExport `
--expect-runtime-feature windows-flutter:embeddedDocuments `
--expect-runtime-feature unity-uitoolkit:embeddedDocuments `
--expect-runtime-feature direct2d:embeddedDocuments `
--expect-runtime-handoff unity-uitoolkit `
--expect-runtime-command-schema web:gamecult.eve.command.v1 `
--expect-runtime-command-schema windows-flutter:gamecult.eve.command.v1 `
--expect-runtime-command-schema unity-uitoolkit:gamecult.eve.command.v1 `

View file

@ -26,6 +26,7 @@ if (!exportDirectory) {
" --expect-provider-handoff <providerId>",
" --expect-runtime-status <runtimeId:status>",
" --expect-runtime-feature <runtimeId:feature>",
" --expect-runtime-handoff <runtimeId>",
" --expect-runtime-command-schema <runtimeId:schema>",
" --expect-runtime-capture-status <runtimeId:status>",
" --expect-split-target-status <targetId:status>",
@ -109,6 +110,9 @@ function validateIndex(index, directory, expectations, errors) {
if (expectations.conformanceHandoff && !index.conformanceHandoffPath) {
errors.push("conformanceHandoffPath:missing");
}
if (expectations.conformanceHandoff) {
validateExportedHandoff(index.conformanceHandoffExportPath, directory, "conformanceHandoff", errors);
}
for (const expectedFixture of expectations.fixtures) {
if (!fixtureIds.has(expectedFixture)) errors.push(`fixture:${expectedFixture}:missing`);
@ -145,6 +149,7 @@ function validateIndex(index, directory, expectations, errors) {
if (!plugin.handoffPath) {
errors.push(`plugins:${expectedPlugin}:handoffPath:missing`);
}
validateExportedHandoff(plugin.handoffExportPath, directory, `plugins:${expectedPlugin}:handoff`, errors);
}
for (const expectedProvider of expectations.providers) {
if (!providers.some(provider => provider.providerId === expectedProvider)) errors.push(`providers:${expectedProvider}:missing`);
@ -188,6 +193,7 @@ function validateIndex(index, directory, expectations, errors) {
if (!provider.handoffPath) {
errors.push(`providers:${expectedProvider}:handoffPath:missing`);
}
validateExportedHandoff(provider.handoffExportPath, directory, `providers:${expectedProvider}:handoff`, errors);
}
for (const expectedRuntime of expectations.runtimes) {
if (!runtimes.some(runtime => runtime.runtimeId === expectedRuntime)) errors.push(`runtimes:${expectedRuntime}:missing`);
@ -232,6 +238,17 @@ function validateIndex(index, directory, expectations, errors) {
errors.push(`runtimes:${expectation.runtimeId}:captureStatus:expected ${expectation.status} got ${runtime.captureStatus || ""}`);
}
}
for (const expectedRuntime of expectations.runtimeHandoffs) {
const runtime = runtimes.find(candidate => candidate.runtimeId === expectedRuntime);
if (!runtime) {
errors.push(`runtimes:${expectedRuntime}:missing`);
continue;
}
if (!runtime.splitHandoffPath) {
errors.push(`runtimes:${expectedRuntime}:splitHandoffPath:missing`);
}
validateExportedHandoff(runtime.splitHandoffExportPath, directory, `runtimes:${expectedRuntime}:splitHandoff`, errors);
}
for (const expectedScenario of expectations.scenarios) {
if (!providers.some(provider => provider.scenarioId === expectedScenario)) errors.push(`providers:scenario:${expectedScenario}:missing`);
}
@ -292,6 +309,16 @@ function readFileSyncUtf8(filePath) {
return readFileSync(filePath, "utf8");
}
function validateExportedHandoff(exportPath, directory, label, errors) {
if (!exportPath) {
errors.push(`${label}:exportPath:missing`);
return;
}
if (!existsSync(path.join(directory, exportPath))) {
errors.push(`${label}:exportPath:${exportPath}:missing`);
}
}
function parseArguments(args) {
const exportPath = args[0] ? path.resolve(args[0]) : "";
const expectations = {
@ -309,6 +336,7 @@ function parseArguments(args) {
runtimes: [],
runtimeStatuses: [],
runtimeFeatures: [],
runtimeHandoffs: [],
runtimeCommandSchemas: [],
runtimeCaptureStatuses: [],
scenarios: [],
@ -335,6 +363,7 @@ function parseArguments(args) {
["--expect-provider-handoff", expectations.providerHandoffs],
["--expect-runtime-status", expectations.runtimeStatuses],
["--expect-runtime-feature", expectations.runtimeFeatures],
["--expect-runtime-handoff", expectations.runtimeHandoffs],
["--expect-runtime-command-schema", expectations.runtimeCommandSchemas],
["--expect-runtime-capture-status", expectations.runtimeCaptureStatuses],
["--expect-split-target-status", expectations.splitTargetStatuses],
@ -376,6 +405,8 @@ function parseArguments(args) {
target.push(parseRuntimeExpectation(value, "status"));
} else if (option === "--expect-runtime-feature") {
target.push(parseRuntimeExpectation(value, "feature"));
} else if (option === "--expect-runtime-handoff") {
target.push(value);
} else if (option === "--expect-runtime-command-schema") {
target.push(parseRuntimeExpectation(value, "schema"));
} else if (option === "--expect-runtime-capture-status") {

View file

@ -303,6 +303,7 @@ async function evaluateRuntime(runtime, fixtureResults) {
}
const commandTransportSmokeErrors = await validateRuntimeCommandTransportSmoke(runtime);
const capabilityManifestErrors = await validateRuntimeCapabilityManifest(runtime);
const splitHandoffPath = await readRuntimeSplitHandoffPath(runtime.capabilityManifest);
const localProviderCatalogErrors = await validateRuntimeLocalProviderCatalog(runtime);
const missingIncubationFields = requiredIncubationFields(runtime).filter(field => !runtime[field]);
const pluginCapabilityGaps = collectPluginCapabilityGaps(runtime, fixtureResults);
@ -349,6 +350,7 @@ async function evaluateRuntime(runtime, fixtureResults) {
commandTransportSmokeErrors,
capabilityManifest: runtime.capabilityManifest || null,
capabilityManifestErrors,
splitHandoffPath,
localProviderCatalog: runtime.localProviderCatalog || null,
localProviderCatalogErrors,
lifecycle: runtime.lifecycle || null,
@ -404,6 +406,18 @@ async function validateRuntimeLocalProviderCatalog(runtime) {
return errors;
}
async function readRuntimeSplitHandoffPath(capabilityManifest) {
if (!capabilityManifest?.manifestPath) return "";
const documentPath = path.join(repoRoot, capabilityManifest.manifestPath);
if (!existsSync(documentPath)) return "";
try {
const document = JSON.parse(await readFile(documentPath, "utf8"));
return document.incubation?.splitHandoff?.manifestPath || "";
} catch {
return "";
}
}
function normalizePath(candidate) {
return candidate.replaceAll("\\", "/").replace(/^\.\//, "");
}
@ -1339,6 +1353,7 @@ function buildConformanceExport(report) {
boundaryRule: report.repoStrategy.boundaryRule || "",
incubationPolicy: report.repoStrategy.incubationPolicy || "",
conformanceHandoffPath: report.repoStrategy.conformanceHandoffPath || "",
conformanceHandoffExportPath: makeHandoffExportPath("conformance", "EveConformance", report.repoStrategy.conformanceHandoffPath || ""),
packs,
plugins: (report.plugins || []).map(plugin => ({
pluginId: plugin.pluginId,
@ -1349,6 +1364,7 @@ function buildConformanceExport(report) {
manifestPath: plugin.manifestPath,
advertisementPath: plugin.advertisementPath,
handoffPath: plugin.handoffPath,
handoffExportPath: makeHandoffExportPath("plugin", plugin.pluginId, plugin.handoffPath),
abiFixturePath: plugin.abiFixturePath,
abiOperations: plugin.abiOperations || [],
optionalPlugins: plugin.optionalPlugins || [],
@ -1361,6 +1377,7 @@ function buildConformanceExport(report) {
advertisementPath: provider.advertisementPath,
scenarioPath: provider.scenarioPath,
handoffPath: provider.handoffPath,
handoffExportPath: makeHandoffExportPath("provider", provider.providerId, provider.handoffPath),
scenarioId: provider.scenarioId,
receiptStates: provider.scenarioReceiptStates || [],
surfaces: provider.surfaceIds,
@ -1377,6 +1394,8 @@ function buildConformanceExport(report) {
unsupportedPlugins: runtime.unsupportedPlugins,
capabilityManifestPath: runtime.capabilityManifest?.manifestPath || "",
capabilityManifestErrors: runtime.capabilityManifestErrors || [],
splitHandoffPath: runtime.splitHandoffPath || "",
splitHandoffExportPath: makeHandoffExportPath("runtime", runtime.id, runtime.splitHandoffPath || ""),
commandTransportSchema: runtime.commandTransportSmoke?.schema || "",
captureStatus: runtime.capture?.status || "",
lifecycle: runtime.lifecycle,
@ -1387,11 +1406,53 @@ function buildConformanceExport(report) {
async function writeConformanceExport(conformanceExport, directory) {
await mkdir(path.join(directory, "packs"), { recursive: true });
await mkdir(path.join(directory, "handoffs"), { recursive: true });
await writeFile(path.join(directory, "index.json"), `${JSON.stringify(conformanceExport, null, 2)}\n`);
await writeFile(path.join(directory, "index.md"), renderConformanceExportMarkdown(conformanceExport));
for (const pack of conformanceExport.packs) {
await writeFile(path.join(directory, "packs", `${pack.id}.json`), `${JSON.stringify(pack, null, 2)}\n`);
}
for (const handoff of collectConformanceHandoffs(conformanceExport)) {
if (!handoff.sourcePath || !handoff.exportPath) continue;
const sourcePath = path.join(repoRoot, handoff.sourcePath);
if (!existsSync(sourcePath)) continue;
const destinationPath = path.join(directory, handoff.exportPath);
await mkdir(path.dirname(destinationPath), { recursive: true });
await writeFile(destinationPath, await readFile(sourcePath, "utf8"));
}
}
function collectConformanceHandoffs(conformanceExport) {
return [
{
sourcePath: conformanceExport.conformanceHandoffPath || "",
exportPath: conformanceExport.conformanceHandoffExportPath || "",
},
...(conformanceExport.plugins || []).map(plugin => ({
sourcePath: plugin.handoffPath || "",
exportPath: plugin.handoffExportPath || "",
})),
...(conformanceExport.providers || []).map(provider => ({
sourcePath: provider.handoffPath || "",
exportPath: provider.handoffExportPath || "",
})),
...(conformanceExport.runtimes || []).map(runtime => ({
sourcePath: runtime.splitHandoffPath || "",
exportPath: runtime.splitHandoffExportPath || "",
})),
];
}
function makeHandoffExportPath(kind, id, sourcePath) {
if (!sourcePath) return "";
return `handoffs/${kind}-${slugify(id)}.json`;
}
function slugify(value) {
return String(value || "unknown")
.replace(/[^a-zA-Z0-9._-]+/g, "-")
.replace(/^-+|-+$/g, "")
|| "unknown";
}
function renderConformanceExportMarkdown(conformanceExport) {
@ -1401,7 +1462,7 @@ function renderConformanceExportMarkdown(conformanceExport) {
`Generated: ${conformanceExport.generatedAt}`,
"",
`Boundary rule: ${conformanceExport.boundaryRule || "not declared"}`,
`Conformance handoff: ${conformanceExport.conformanceHandoffPath || "not declared"}`,
`Conformance handoff: ${conformanceExport.conformanceHandoffExportPath || conformanceExport.conformanceHandoffPath || "not declared"}`,
"",
"## Packs",
"",