GEP schemas

GEP uses structured objects for methods, execution results, and process records. Choose the object, then validate fields, content identifiers, and references. This guide uses official schemas and hashing from @evomap/gep-sdk; Evolver and the Hub separately handle storage, execution, and publishing.

Choose an object

ValidationReport carries verification environment, commands, and evidence; Memory carries local relationships and recall records. Each has separate storage and runtime contracts rather than using the Gene schema.

Gene fields

Before constructing or exporting assets, remove node_secret, access tokens, signing keys, production credentials, personal data, and private paths from free-text fields and attached artifacts. Schema and content-hash validation do not inspect secrets or grant publication permission. Before a separately authorized publication, run evolver_asset_validate for local redaction, quality, and safety checks, then review its result.

Construct and validate a Gene

In a separate example directory, install dependencies and save this as validate-gene.mjs:

npm init -y
npm install @evomap/gep-sdk ajv

import Ajv from "ajv";
import { SCHEMA_VERSION, computeAssetId, verifyAssetId } from "@evomap/gep-sdk";
import geneSchema from "@evomap/gep-sdk/schemas/gene.schema.json" with { type: "json" };

const gene = {
  type: "Gene",
  schema_version: SCHEMA_VERSION,
  id: "gene_fix_horizontal_overflow",
  category: "repair",
  signals_match: ["horizontal_overflow"],
  preconditions: ["A browser reproduction and editable source are available."],
  strategy: [
    "Reproduce the overflowing layout at the reported viewport.",
    "Identify the element and the width constraint causing overflow.",
    "Fix that constraint and verify menu interaction and desktop layout."
  ],
  constraints: { max_files: 3, forbidden_paths: [".git", ".env"] },
  validation: ["Run the project checks and exercise the affected menu at both phone widths."],
  asset_id: ""
};
gene.asset_id = computeAssetId(gene);
const validate = new Ajv({ allErrors: true }).compile(geneSchema);
if (!validate(gene) || !verifyAssetId(gene)) throw new Error("Invalid Gene");
console.log(JSON.stringify(gene, null, 2));

Run node validate-gene.mjs to check the schema and hash, then print a Gene with its content hash. The command constructs and checks the object locally; it does not execute the strategy, store an Evolver asset, or publish it.

Use the SDK's SCHEMA_VERSION rather than an npm package or Desktop version. Recompute asset_id after changing content; previous hashes and verification bindings do not transfer to edited content.

Link Capsules and process records

A Capsule references a Gene through gene; trigger, summary, blast_radius, and outcome describe the result. confidence ranges from 0 to 1 but does not establish execution evidence. Resolve the Gene and tie claims to real artifacts and verification records.

EvolutionEvent links attempts through genes_used, mutation_id, and capsule_id, retaining signals, source, and outcome. Keep event identity, asset content identity, and remote operation IDs distinct.

Validate related objects

Run the previous example and save the Gene as gene.json:

node --input-type=module -e 'import { execFileSync } from "node:child_process"; import { writeFileSync } from "node:fs"; const output = execFileSync(process.execPath, ["validate-gene.mjs"]); writeFileSync("gene.json", output, { flag: "wx" });'

Validation completes before file creation. The command refuses to overwrite an existing gene.json; retain it and choose a separate example directory for another generated object.

Save the following as validate-related.mjs. It constructs a local failure-path example in which no repair was executed, rather than fabricating successful evidence. It neither writes Evolver execution history nor sends objects to the Hub.

import { readFileSync, writeFileSync } from "node:fs";
import Ajv from "ajv";
import { SCHEMA_VERSION, computeAssetId, verifyAssetId } from "@evomap/gep-sdk";
import capsuleSchema from "@evomap/gep-sdk/schemas/capsule.schema.json" with { type: "json" };
import eventSchema from "@evomap/gep-sdk/schemas/evolution-event.schema.json" with { type: "json" };
import recipeSchema from "@evomap/gep-sdk/schemas/recipe.schema.json" with { type: "json" };

const gene = JSON.parse(readFileSync("gene.json", "utf8"));
if (gene.type !== "Gene" || !verifyAssetId(gene)) throw new Error("Invalid source Gene");
const capsule = {
  type: "Capsule", schema_version: SCHEMA_VERSION, id: "capsule_schema_example",
  trigger: ["horizontal_overflow"], gene: gene.id,
  summary: "Schema example only; no project repair was executed.",
  confidence: 0, blast_radius: { files: 0, lines: 0 },
  outcome: { status: "failed", score: 0 }, asset_id: ""
};
capsule.asset_id = computeAssetId(capsule);
const event = {
  type: "EvolutionEvent", schema_version: SCHEMA_VERSION, id: "event_schema_example",
  intent: "repair", signals: ["horizontal_overflow"], genes_used: [gene.id],
  mutation_id: "", capsule_id: capsule.id, blast_radius: capsule.blast_radius,
  outcome: capsule.outcome, source_type: "user_authored", asset_id: ""
};
event.asset_id = computeAssetId(event);
const recipe = {
  title: "Inspect horizontal overflow",
  description: "A local create-payload example; no Hub record is created.",
  steps: [{ asset_id: gene.asset_id, asset_type: "Gene", position: 0 }]
};
const ajv = new Ajv({ allErrors: true });
for (const [schema, object] of [[capsuleSchema, capsule], [eventSchema, event], [recipeSchema, recipe]]) {
  const validate = ajv.compile(schema);
  if (!validate(object)) throw new Error(JSON.stringify(validate.errors));
}
if (!verifyAssetId(capsule) || !verifyAssetId(event)) throw new Error("Hash mismatch");
if (capsule.gene !== gene.id || !event.genes_used.includes(gene.id) || event.capsule_id !== capsule.id) {
  throw new Error("Broken local references");
}
writeFileSync("related-objects.json", JSON.stringify({ capsule, event, recipe }, null, 2), { flag: "wx" });
console.log("Capsule, EvolutionEvent, and Recipe structure and local references validated");

Run node validate-related.mjs. Success creates a new related-objects.json containing three schema-validated objects; an existing file is preserved and the command fails instead of overwriting it. Here gene, genes_used, and capsule_id resolve local logical IDs; Recipe steps reference content asset_id values. Keep these identities distinct.

An empty mutation_id means this example references no actual mutation. Real execution records use the runner's mutation, verification report, and artifact relationships. Outcomes and impact must come from that execution; changing this fixture to success does not create a successful history.

Check three negative cases: changing the Capsule summary without rehashing must fail integrity validation; confidence 2 must fail schema validation; a capsule_id outside the loaded set must fail reference resolution. A string passing schema validation does not resolve the referenced object.

Recipe structure differs

Recipe creation requires title and nonempty steps. Each step supplies asset_id and asset_type (Gene or Capsule), with optional conditions, parameters, and optional-step settings. Referenced assets must already exist in the target Hub with matching types.

The Hub assigns Recipe record IDs; Recipes do not use Gene/Capsule content addressing. For step order, input/output contracts, and execution state, see Recipes and experience reuse. For authoring, see Distill Genes, Skills, and Recipes.

Handle failures by layer

See Asset paths for asset pools, events, and materialized views. Stop writes for unknown structures; deleting fields or inventing outcomes does not establish compatibility.