diff --git a/docs/eve-migration-roadmap.md b/docs/eve-migration-roadmap.md index c9f8dd9..cb76fb7 100644 --- a/docs/eve-migration-roadmap.md +++ b/docs/eve-migration-roadmap.md @@ -274,15 +274,17 @@ Exit criteria: ## Active Work Queue -1. Add plugin ABI fixtures for Sai, Norn, and TeX describe/validate/project/apply - behavior without moving their semantics into Eve core. -2. Add Aetheria scenario conformance replay that consumes provider +1. Add Aetheria scenario conformance replay that consumes provider advertisements and reports command receipts without provider internals. -3. Add runtime command-transport smokes for Flutter and Unity so split targets +2. Add runtime command-transport smokes for Flutter and Unity so split targets can prove command emission through `gamecult.eve.command.v1`. Recently cut: +- Sai, Norn, and TeX now have plugin ABI fixtures for describe, validate, + project, and apply behavior. The parity harness validates those fixtures + against plugin manifests, so Eve proves the ABI shape without owning plugin + semantics. - Split-readiness reporting now exists for `EveFlutter` and `EveUnity`. The parity report lists member runtime health, required plugin capability claims, pending proofs, and blockers before either repo can graduate out of Eve diff --git a/plugins/incubating/norn-graph.plugin-abi-fixture.json b/plugins/incubating/norn-graph.plugin-abi-fixture.json new file mode 100644 index 0000000..a68fe76 --- /dev/null +++ b/plugins/incubating/norn-graph.plugin-abi-fixture.json @@ -0,0 +1,60 @@ +{ + "schema": "gamecult.eve.plugin_abi_fixture.v1", + "fixtureId": "norn-graph-plugin-abi", + "pluginId": "norn.graph", + "ownerRepo": "Norn", + "contract": "gamecult.eve.plugin_abi.v1", + "sourceFixture": "sai-vn", + "operations": [ + { + "operation": "describe", + "input": { + "manifest": "plugins/incubating/norn-graph.plugin.json", + "advertisement": "plugins/incubating/norn-graph.plugin-advertisement.json" + }, + "expect": { + "pluginId": "norn.graph", + "componentKinds": ["embed.norn"], + "commands": ["graph.node.activate", "graph.focus"], + "capabilities": ["embed.norn", "graph.node.activate"] + } + }, + { + "operation": "validate", + "input": { + "surface": "web/fixtures/sai-vn-surface.json", + "componentKinds": ["embed.norn"] + }, + "expect": { + "acceptedComponentKinds": ["embed.norn"], + "rejectedComponentKinds": ["embed.tex", "vn.stage"], + "requiredCapabilities": ["embed.norn"] + } + }, + { + "operation": "project", + "input": { + "surface": "web/fixtures/sai-vn-surface.json", + "nodeKind": "embed.norn" + }, + "expect": { + "projectionKind": "embedded-semantic-surface", + "ownedComponentKinds": ["embed.norn"], + "outputSchemas": ["norn.graph.document.v1", "norn.graph.layout_request.v1", "norn.graph.layout_result.v1"] + } + }, + { + "operation": "apply", + "input": { + "commands": ["graph.node.activate", "graph.focus"] + }, + "expect": { + "commandEffects": { + "graph.node.activate": "activate-node", + "graph.focus": "focus-graph" + }, + "receiptSchema": "gamecult.eve.command_receipt.v1" + } + } + ] +} diff --git a/plugins/incubating/norn-graph.plugin.json b/plugins/incubating/norn-graph.plugin.json index 545917f..4ded2e3 100644 --- a/plugins/incubating/norn-graph.plugin.json +++ b/plugins/incubating/norn-graph.plugin.json @@ -36,6 +36,9 @@ "path": "web/fixtures/sai-vn-surface.json" } ], + "abiFixtures": [ + "plugins/incubating/norn-graph.plugin-abi-fixture.json" + ], "capabilities": { "requires": [ "embed.norn" diff --git a/plugins/incubating/sai-vn.plugin-abi-fixture.json b/plugins/incubating/sai-vn.plugin-abi-fixture.json new file mode 100644 index 0000000..ec53db2 --- /dev/null +++ b/plugins/incubating/sai-vn.plugin-abi-fixture.json @@ -0,0 +1,61 @@ +{ + "schema": "gamecult.eve.plugin_abi_fixture.v1", + "fixtureId": "sai-vn-plugin-abi", + "pluginId": "sai.vn", + "ownerRepo": "Sai", + "contract": "gamecult.eve.plugin_abi.v1", + "sourceFixture": "sai-vn", + "operations": [ + { + "operation": "describe", + "input": { + "manifest": "plugins/incubating/sai-vn.plugin.json", + "advertisement": "plugins/incubating/sai-vn.plugin-advertisement.json" + }, + "expect": { + "pluginId": "sai.vn", + "componentKinds": ["vn.stage", "panel.dialogue", "text.dialogue", "rail.actions"], + "commands": ["story.continue", "story.choose", "story.jump"], + "capabilities": ["vn.stage", "story.choose", "story.continue", "story.jump"] + } + }, + { + "operation": "validate", + "input": { + "surface": "web/fixtures/sai-vn-surface.json", + "componentKinds": ["vn.stage", "panel.dialogue", "text.dialogue", "rail.actions"] + }, + "expect": { + "acceptedComponentKinds": ["vn.stage", "panel.dialogue", "text.dialogue", "rail.actions"], + "rejectedComponentKinds": ["combat.timeline"], + "requiredCapabilities": ["vn.stage", "story.choose", "story.continue", "story.jump"] + } + }, + { + "operation": "project", + "input": { + "surface": "web/fixtures/sai-vn-surface.json", + "rootKind": "vn.stage" + }, + "expect": { + "projectionKind": "semantic-surface", + "ownedComponentKinds": ["vn.stage", "panel.dialogue", "text.dialogue", "rail.actions"], + "delegatedPlugins": ["norn.graph", "tex.math"] + } + }, + { + "operation": "apply", + "input": { + "commands": ["story.continue", "story.choose", "story.jump"] + }, + "expect": { + "commandEffects": { + "story.continue": "advance-story", + "story.choose": "choose-branch", + "story.jump": "jump-to-knot" + }, + "receiptSchema": "gamecult.eve.command_receipt.v1" + } + } + ] +} diff --git a/plugins/incubating/sai-vn.plugin.json b/plugins/incubating/sai-vn.plugin.json index 5ea043d..fa5da50 100644 --- a/plugins/incubating/sai-vn.plugin.json +++ b/plugins/incubating/sai-vn.plugin.json @@ -43,6 +43,9 @@ "path": "web/fixtures/sai-vn-surface.json" } ], + "abiFixtures": [ + "plugins/incubating/sai-vn.plugin-abi-fixture.json" + ], "capabilities": { "requires": [ "vn.stage", diff --git a/plugins/incubating/tex-math.plugin-abi-fixture.json b/plugins/incubating/tex-math.plugin-abi-fixture.json new file mode 100644 index 0000000..5ed753a --- /dev/null +++ b/plugins/incubating/tex-math.plugin-abi-fixture.json @@ -0,0 +1,57 @@ +{ + "schema": "gamecult.eve.plugin_abi_fixture.v1", + "fixtureId": "tex-math-plugin-abi", + "pluginId": "tex.math", + "ownerRepo": "EvePlugins", + "contract": "gamecult.eve.plugin_abi.v1", + "sourceFixture": "sai-vn", + "operations": [ + { + "operation": "describe", + "input": { + "manifest": "plugins/incubating/tex-math.plugin.json", + "advertisement": "plugins/incubating/tex-math.plugin-advertisement.json" + }, + "expect": { + "pluginId": "tex.math", + "componentKinds": ["embed.tex"], + "commands": [], + "capabilities": ["embed.tex", "tex.inline", "tex.block"] + } + }, + { + "operation": "validate", + "input": { + "surface": "web/fixtures/sai-vn-surface.json", + "componentKinds": ["embed.tex"] + }, + "expect": { + "acceptedComponentKinds": ["embed.tex"], + "rejectedComponentKinds": ["embed.norn", "vn.stage"], + "requiredCapabilities": ["embed.tex"] + } + }, + { + "operation": "project", + "input": { + "surface": "web/fixtures/sai-vn-surface.json", + "nodeKind": "embed.tex" + }, + "expect": { + "projectionKind": "render-request", + "ownedComponentKinds": ["embed.tex"], + "outputSchemas": ["tex.math.render_request.v1", "tex.math.render_result.v1"] + } + }, + { + "operation": "apply", + "input": { + "stateSchemas": ["tex.math.source.v1", "tex.math.render_request.v1", "tex.math.render_result.v1"] + }, + "expect": { + "stateEffects": ["cache-render-result", "emit-fallback-on-render-failure"], + "receiptSchema": "gamecult.eve.plugin_receipt.v1" + } + } + ] +} diff --git a/plugins/incubating/tex-math.plugin.json b/plugins/incubating/tex-math.plugin.json index 85bbedc..6c6fe3b 100644 --- a/plugins/incubating/tex-math.plugin.json +++ b/plugins/incubating/tex-math.plugin.json @@ -25,6 +25,9 @@ "path": "web/fixtures/sai-vn-surface.json" } ], + "abiFixtures": [ + "plugins/incubating/tex-math.plugin-abi-fixture.json" + ], "capabilities": { "requires": [ "embed.tex" diff --git a/schemas/gamecult.eve.plugin.v1.schema.json b/schemas/gamecult.eve.plugin.v1.schema.json index 645f679..6e4d51d 100644 --- a/schemas/gamecult.eve.plugin.v1.schema.json +++ b/schemas/gamecult.eve.plugin.v1.schema.json @@ -125,6 +125,13 @@ "additionalProperties": true } }, + "abiFixtures": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + }, "capabilities": { "type": "object", "required": [ diff --git a/schemas/gamecult.eve.plugin_abi_fixture.v1.schema.json b/schemas/gamecult.eve.plugin_abi_fixture.v1.schema.json new file mode 100644 index 0000000..4e17ad9 --- /dev/null +++ b/schemas/gamecult.eve.plugin_abi_fixture.v1.schema.json @@ -0,0 +1,64 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "gamecult.eve.plugin_abi_fixture.v1", + "title": "Eve Plugin ABI Fixture", + "type": "object", + "required": [ + "schema", + "fixtureId", + "pluginId", + "ownerRepo", + "contract", + "operations" + ], + "properties": { + "schema": { + "const": "gamecult.eve.plugin_abi_fixture.v1" + }, + "fixtureId": { + "type": "string", + "minLength": 1 + }, + "pluginId": { + "type": "string", + "minLength": 1 + }, + "ownerRepo": { + "type": "string", + "minLength": 1 + }, + "contract": { + "type": "string", + "minLength": 1 + }, + "sourceFixture": { + "type": "string", + "minLength": 1 + }, + "operations": { + "type": "array", + "items": { + "type": "object", + "required": [ + "operation", + "input", + "expect" + ], + "properties": { + "operation": { + "type": "string", + "minLength": 1 + }, + "input": { + "type": "object" + }, + "expect": { + "type": "object" + } + }, + "additionalProperties": true + } + } + }, + "additionalProperties": true +} diff --git a/tools/parity/parity-manifest.json b/tools/parity/parity-manifest.json index 46b2f8a..608c8a5 100644 --- a/tools/parity/parity-manifest.json +++ b/tools/parity/parity-manifest.json @@ -9,6 +9,7 @@ "gamecult.eve.conformance_fixture.v1": "schemas/gamecult.eve.conformance_fixture.v1.schema.json", "gamecult.eve.command.v1": "schemas/gamecult.eve.command.v1.schema.json", "gamecult.eve.plugin.v1": "schemas/gamecult.eve.plugin.v1.schema.json", + "gamecult.eve.plugin_abi_fixture.v1": "schemas/gamecult.eve.plugin_abi_fixture.v1.schema.json", "gamecult.eve.plugin_advertisement.v1": "schemas/gamecult.eve.plugin_advertisement.v1.schema.json", "gamecult.eve.provider_advertisement.v1": "schemas/gamecult.eve.provider_advertisement.v1.schema.json" }, @@ -321,10 +322,12 @@ "requiredFixtures": ["sai-vn"], "schemaPath": "schemas/gamecult.eve.plugin.v1.schema.json", "manifestPath": "plugins/incubating/sai-vn.plugin.json", + "abiFixturePath": "plugins/incubating/sai-vn.plugin-abi-fixture.json", "advertisementSchemaPath": "schemas/gamecult.eve.plugin_advertisement.v1.schema.json", "advertisementPath": "plugins/incubating/sai-vn.plugin-advertisement.json", "expectedPaths": [ "plugins/incubating/sai-vn.plugin.json", + "plugins/incubating/sai-vn.plugin-abi-fixture.json", "plugins/incubating/sai-vn.plugin-advertisement.json" ] }, @@ -340,10 +343,12 @@ "requiredFixtures": ["sai-vn"], "schemaPath": "schemas/gamecult.eve.plugin.v1.schema.json", "manifestPath": "plugins/incubating/norn-graph.plugin.json", + "abiFixturePath": "plugins/incubating/norn-graph.plugin-abi-fixture.json", "advertisementSchemaPath": "schemas/gamecult.eve.plugin_advertisement.v1.schema.json", "advertisementPath": "plugins/incubating/norn-graph.plugin-advertisement.json", "expectedPaths": [ "plugins/incubating/norn-graph.plugin.json", + "plugins/incubating/norn-graph.plugin-abi-fixture.json", "plugins/incubating/norn-graph.plugin-advertisement.json" ] }, @@ -359,10 +364,12 @@ "requiredFixtures": ["sai-vn"], "schemaPath": "schemas/gamecult.eve.plugin.v1.schema.json", "manifestPath": "plugins/incubating/tex-math.plugin.json", + "abiFixturePath": "plugins/incubating/tex-math.plugin-abi-fixture.json", "advertisementSchemaPath": "schemas/gamecult.eve.plugin_advertisement.v1.schema.json", "advertisementPath": "plugins/incubating/tex-math.plugin-advertisement.json", "expectedPaths": [ "plugins/incubating/tex-math.plugin.json", + "plugins/incubating/tex-math.plugin-abi-fixture.json", "plugins/incubating/tex-math.plugin-advertisement.json" ] } diff --git a/tools/parity/run-parity.mjs b/tools/parity/run-parity.mjs index fd07f41..4e3ac95 100644 --- a/tools/parity/run-parity.mjs +++ b/tools/parity/run-parity.mjs @@ -348,6 +348,7 @@ async function evaluatePlugin(plugin, fixtureResults) { schema: "gamecult.eve.plugin_advertisement.v1", pluginId: plugin.pluginId, }); + const abiErrors = await validatePluginAbiFixture(plugin); const status = missingPaths.length ? "missing-body" : missingRequiredFixtures.length @@ -358,9 +359,11 @@ async function evaluatePlugin(plugin, fixtureResults) { ? "invalid-plugin-manifest" : advertisementErrors.length ? "invalid-plugin-advertisement" - : plugin.kind === "incubating" - ? "incubating" - : "external-owner-planned"; + : abiErrors.length + ? "invalid-plugin-abi-fixture" + : plugin.kind === "incubating" + ? "incubating" + : "external-owner-planned"; return { pluginId: plugin.pluginId, @@ -376,10 +379,12 @@ async function evaluatePlugin(plugin, fixtureResults) { missingRequiredFixtures, schemaPath: plugin.schemaPath || "", manifestPath: plugin.manifestPath || "", + abiFixturePath: plugin.abiFixturePath || "", advertisementSchemaPath: plugin.advertisementSchemaPath || "", advertisementPath: plugin.advertisementPath || "", schemaErrors, advertisementErrors, + abiErrors, expectedPaths, missingPaths, missingIncubationFields, @@ -484,6 +489,85 @@ async function readJsonDocument(documentPath) { return JSON.parse(await readFile(path.join(repoRoot, documentPath), "utf8")); } +async function validatePluginAbiFixture(plugin) { + const errors = await validateJsonDocument( + manifest.schemas?.["gamecult.eve.plugin_abi_fixture.v1"], + plugin.abiFixturePath, + { + schema: "gamecult.eve.plugin_abi_fixture.v1", + pluginId: plugin.pluginId, + }, + ); + if (errors.length) return errors; + + try { + const abiFixture = await readJsonDocument(plugin.abiFixturePath); + const pluginManifest = await readJsonDocument(plugin.manifestPath); + const operations = new Map((abiFixture.operations || []).map(operation => [operation.operation, operation])); + + if (abiFixture.ownerRepo !== plugin.ownerRepo) { + errors.push(`${plugin.abiFixturePath}:ownerRepo:expected ${plugin.ownerRepo} got ${abiFixture.ownerRepo}`); + } + if (abiFixture.contract !== "gamecult.eve.plugin_abi.v1") { + errors.push(`${plugin.abiFixturePath}:contract:expected gamecult.eve.plugin_abi.v1 got ${abiFixture.contract}`); + } + + for (const operation of ["describe", "validate", "project", "apply"]) { + if (!operations.has(operation)) errors.push(`${plugin.abiFixturePath}:operation:${operation}:missing`); + } + + if (!(pluginManifest.abiFixtures || []).includes(plugin.abiFixturePath)) { + errors.push(`${plugin.manifestPath}:abiFixtures:${plugin.abiFixturePath}:missing`); + } + + const manifestCommands = (pluginManifest.commands || []).map(command => command.command); + const manifestComponentKinds = pluginManifest.componentKinds || []; + const manifestCommandEffects = new Map((pluginManifest.commands || []).map(command => [command.command, command.effect])); + + const describe = operations.get("describe")?.expect || {}; + if (describe.pluginId !== plugin.pluginId) { + errors.push(`${plugin.abiFixturePath}:describe.pluginId:expected ${plugin.pluginId} got ${describe.pluginId}`); + } + errors.push(...missingMembers(manifestComponentKinds, describe.componentKinds || [], `${plugin.abiFixturePath}:describe.componentKinds`)); + errors.push(...missingMembers(manifestCommands, describe.commands || [], `${plugin.abiFixturePath}:describe.commands`)); + errors.push(...missingMembers(plugin.capabilities || [], describe.capabilities || [], `${plugin.abiFixturePath}:describe.capabilities`)); + + const validate = operations.get("validate")?.expect || {}; + errors.push(...missingMembers(manifestComponentKinds, validate.acceptedComponentKinds || [], `${plugin.abiFixturePath}:validate.acceptedComponentKinds`)); + + const project = operations.get("project")?.expect || {}; + errors.push(...missingMembers(manifestComponentKinds, project.ownedComponentKinds || [], `${plugin.abiFixturePath}:project.ownedComponentKinds`)); + if (!project.projectionKind) errors.push(`${plugin.abiFixturePath}:project.projectionKind:missing`); + + const apply = operations.get("apply")?.expect || {}; + if (manifestCommands.length) { + const commandEffects = apply.commandEffects || {}; + for (const command of manifestCommands) { + if (!commandEffects[command]) { + errors.push(`${plugin.abiFixturePath}:apply.commandEffects:${command}:missing`); + continue; + } + + const expectedEffect = manifestCommandEffects.get(command); + if (commandEffects[command] !== expectedEffect) { + errors.push(`${plugin.abiFixturePath}:apply.commandEffects:${command}:expected ${expectedEffect} got ${commandEffects[command]}`); + } + } + } else if (!(apply.stateEffects || []).length) { + errors.push(`${plugin.abiFixturePath}:apply.stateEffects:missing`); + } + } catch (error) { + errors.push(`${plugin.abiFixturePath}:invalid-json:${error instanceof Error ? error.message : String(error)}`); + } + + return errors; +} + +function missingMembers(expected, actual, label) { + const actualSet = new Set(actual); + return expected.filter(item => !actualSet.has(item)).map(item => `${label}:${item}:missing`); +} + async function validateJsonDocument(schemaPath, documentPath, expected = {}) { const errors = []; if (!schemaPath) errors.push("schemaPath:missing"); @@ -854,7 +938,7 @@ function renderMarkdown(report) { lines.push(`| ${fixture.title} | ${fixture.metadataPath} | ${fixture.metadata?.purpose || ""} | ${fixture.metadataErrors.join(", ")} |`); } - lines.push("", "## Plugins", "", "| Plugin | Status | Owner | Capabilities | Missing |", "| --- | --- | --- | --- | --- |"); + lines.push("", "## Plugins", "", "| Plugin | Status | Owner | ABI Fixture | Capabilities | Missing |", "| --- | --- | --- | --- | --- | --- |"); for (const plugin of report.plugins || []) { const missing = [ ...plugin.missingPaths, @@ -862,8 +946,9 @@ function renderMarkdown(report) { ...plugin.missingIncubationFields.map(id => `metadata:${id}`), ...plugin.schemaErrors.map(id => `schema:${id}`), ...plugin.advertisementErrors.map(id => `advertisement:${id}`), + ...plugin.abiErrors.map(id => `abi:${id}`), ].join(", "); - lines.push(`| ${plugin.title || plugin.pluginId} | ${plugin.status} | ${plugin.ownerRepo} | ${plugin.capabilities.join(", ")} | ${missing} |`); + lines.push(`| ${plugin.title || plugin.pluginId} | ${plugin.status} | ${plugin.ownerRepo} | ${plugin.abiFixturePath || ""} | ${plugin.capabilities.join(", ")} | ${missing} |`); } lines.push("", "## Providers", "", "| Provider | Status | Owner | Surfaces | Commands | Witnesses | Missing |", "| --- | --- | --- | --- | --- | --- | --- |");