Validate Eve plugin ABI fixtures

This commit is contained in:
Meta Vens 2026-07-09 00:06:00 +01:00
commit 54e1707a6a
11 changed files with 361 additions and 9 deletions

View file

@ -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

View file

@ -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"
}
}
]
}

View file

@ -36,6 +36,9 @@
"path": "web/fixtures/sai-vn-surface.json"
}
],
"abiFixtures": [
"plugins/incubating/norn-graph.plugin-abi-fixture.json"
],
"capabilities": {
"requires": [
"embed.norn"

View file

@ -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"
}
}
]
}

View file

@ -43,6 +43,9 @@
"path": "web/fixtures/sai-vn-surface.json"
}
],
"abiFixtures": [
"plugins/incubating/sai-vn.plugin-abi-fixture.json"
],
"capabilities": {
"requires": [
"vn.stage",

View file

@ -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"
}
}
]
}

View file

@ -25,6 +25,9 @@
"path": "web/fixtures/sai-vn-surface.json"
}
],
"abiFixtures": [
"plugins/incubating/tex-math.plugin-abi-fixture.json"
],
"capabilities": {
"requires": [
"embed.tex"

View file

@ -125,6 +125,13 @@
"additionalProperties": true
}
},
"abiFixtures": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"capabilities": {
"type": "object",
"required": [

View file

@ -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
}

View file

@ -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"
]
}

View file

@ -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 |", "| --- | --- | --- | --- | --- | --- | --- |");