Wire A2ML metadata envelopes into all data interchange points

Every export/import/sync path now speaks A2ML: level export wraps
levelConfig in an A2ML envelope with seed/template provenance,
portfolio and campaign graph encode/decode handle both A2ML-wrapped
and raw JSON (graceful fallback), and sync server payloads carry
A2ML metadata for downstream tool inspection (Hypatia, VerisimDB).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: hyperpolymath

idaptik-ums/src/generator/A2mlWrapper.res

@@ -28,6 +28,47 @@ type a2mlMeta = {
   designerNotes: string,
 }
 
+// ---------------------------------------------------------------------------
+// Timestamp binding
+// ---------------------------------------------------------------------------
+
+@val external dateNow: unit => float = "Date.now"
+
+// ---------------------------------------------------------------------------
+// Convenience constructors
+// ---------------------------------------------------------------------------
+
+/// Build standard A2ML metadata from a generated level's seed and template.
+/// Uses "idaptik-ums" as the generator identifier and the current timestamp.
+let fromLevel = (seed: int, templateName: string): a2mlMeta => {
+  version: "1.0",
+  generator: "idaptik-ums",
+  seed: seed,
+  templateName: templateName,
+  generatedAt: Belt.Float.toString(dateNow()),
+  designerNotes: "",
+}
+
+/// Build A2ML metadata for a portfolio envelope.
+let fromPortfolio = (name: string): a2mlMeta => {
+  version: "1.0",
+  generator: "idaptik-ums-portfolio",
+  seed: 0,
+  templateName: name,
+  generatedAt: Belt.Float.toString(dateNow()),
+  designerNotes: "",
+}
+
+/// Build A2ML metadata for a campaign graph envelope.
+let fromCampaign = (portfolioId: string): a2mlMeta => {
+  version: "1.0",
+  generator: "idaptik-ums-campaign",
+  seed: 0,
+  templateName: portfolioId,
+  generatedAt: Belt.Float.toString(dateNow()),
+  designerNotes: "",
+}
+
 // ---------------------------------------------------------------------------
 // Wrap / Unwrap
 // ---------------------------------------------------------------------------

idaptik-ums/src/generator/CampaignGraph.res

@@ -204,10 +204,27 @@ let encodeCampaignGraph = (graph: campaignGraph): string => {
 }`
 }
 
-/// Decode a campaign graph from a JSON string.
+/// Encode a campaign graph to an A2ML-wrapped JSON string. The A2ML envelope
+/// carries generator metadata (version, portfolio reference) alongside the
+/// campaign graph payload.
+let encodeCampaignGraphA2ml = (graph: campaignGraph): string => {
+  let json = encodeCampaignGraph(graph)
+  let meta = A2mlWrapper.fromCampaign(graph.portfolioId)
+  A2mlWrapper.wrapInA2ml(json, meta)
+}
+
+/// Decode a campaign graph from a JSON string. Accepts both A2ML-wrapped
+/// and raw campaign graph JSON. If the input has an "a2ml" envelope,
+/// unwraps it first and uses the inner payload; otherwise treats it as
+/// raw campaign graph JSON.
 let decodeCampaignGraph = (jsonStr: string): result<campaignGraph, string> => {
+  // Try A2ML unwrap first — if it's an A2ML envelope, use the inner payload
+  let rawJson = switch A2mlWrapper.unwrapA2ml(jsonStr) {
+  | Ok((payload, _meta)) => payload
+  | Error(_) => jsonStr  // Not A2ML — treat as raw campaign graph JSON
+  }
   try {
-    let json = JSON.parseExn(jsonStr)
+    let json = JSON.parseExn(rawJson)
     let obj = json->Js.Json.decodeObject->Belt.Option.getWithDefault(Js.Dict.empty())
     let portfolioId = Js.Dict.get(obj, "portfolioId")
       ->Belt.Option.flatMap(Js.Json.decodeString)

idaptik-ums/src/generator/GeneratorDemo.res

@@ -918,7 +918,7 @@ let make = () => {
               | Some(gen) =>
                 switch (topology, powerMap) {
                 | (Some(topo), Some(pwr)) =>
-                  let json = LevelExport.exportToJson(gen, topo, pwr)
+                  let json = LevelExport.exportToA2ml(gen, topo, pwr)
                   copyToClipboard(json)
                 | _ => ()
                 }

idaptik-ums/src/generator/LevelExport.res

@@ -129,3 +129,21 @@ let exportToJson = (
   let config = exportToConfig(level, topology, power)
   LevelConfigCodec.toJsonString(config)
 }
+
+// ---------------------------------------------------------------------------
+// Export to A2ML-wrapped JSON
+// ---------------------------------------------------------------------------
+
+/// Export a generated level to an A2ML-wrapped JSON string. The A2ML envelope
+/// carries generator metadata (version, seed, template) alongside the
+/// levelConfig payload, enabling downstream tools to inspect provenance
+/// without parsing the level data itself.
+let exportToA2ml = (
+  level: LevelGen.generatedLevel,
+  topology: NetworkGen.generatedTopology,
+  power: PowerGen.powerMap,
+): string => {
+  let json = exportToJson(level, topology, power)
+  let meta = A2mlWrapper.fromLevel(level.seed, level.templateName)
+  A2mlWrapper.wrapInA2ml(json, meta)
+}

idaptik-ums/src/generator/LevelImport.res

@@ -116,11 +116,17 @@ let importFromConfig = (config: LevelConfigTypes.levelConfig): LevelGen.generate
 // Import from JSON string
 // ---------------------------------------------------------------------------
 
-/// Import a level from a JSON string. Parses the JSON, decodes to levelConfig,
-/// then converts to generatedLevel. Returns Error if JSON is malformed or
-/// doesn't match the expected schema.
+/// Import a level from a JSON string. Accepts both A2ML-wrapped and raw
+/// levelConfig JSON. If the input has an "a2ml" envelope, unwraps it first
+/// and uses the inner payload; otherwise treats it as raw levelConfig JSON.
+/// Returns Error if JSON is malformed or doesn't match the expected schema.
 let importFromJson = (jsonStr: string): result<LevelGen.generatedLevel, string> => {
-  switch LevelConfigCodec.fromJsonString(jsonStr) {
+  // Try A2ML unwrap first — if it's an A2ML envelope, use the inner payload
+  let rawJson = switch A2mlWrapper.unwrapA2ml(jsonStr) {
+  | Ok((payload, _meta)) => payload
+  | Error(_) => jsonStr  // Not A2ML — treat as raw levelConfig JSON
+  }
+  switch LevelConfigCodec.fromJsonString(rawJson) {
   | Ok(config) => Ok(importFromConfig(config))
   | Error(msg) => Error(msg)
   }

idaptik-ums/src/generator/Portfolio.res

@@ -131,11 +131,28 @@ let encodePortfolio = (p: portfolio): string => {
 }`
 }
 
-/// Decode a portfolio from a JSON string. Rebuilds levels by regenerating
-/// from the stored seeds (deterministic generation ensures identical output).
+/// Encode a portfolio to an A2ML-wrapped JSON string. The A2ML envelope
+/// carries generator metadata (version, portfolio name) alongside the
+/// portfolio payload, enabling downstream tools to inspect provenance.
+let encodePortfolioA2ml = (p: portfolio): string => {
+  let json = encodePortfolio(p)
+  let meta = A2mlWrapper.fromPortfolio(p.name)
+  A2mlWrapper.wrapInA2ml(json, meta)
+}
+
+/// Decode a portfolio from a JSON string. Accepts both A2ML-wrapped and raw
+/// portfolio JSON. If the input has an "a2ml" envelope, unwraps it first
+/// and uses the inner payload; otherwise treats it as raw portfolio JSON.
+/// Rebuilds levels by regenerating from the stored seeds (deterministic
+/// generation ensures identical output).
 let decodePortfolio = (jsonStr: string): result<portfolio, string> => {
+  // Try A2ML unwrap first — if it's an A2ML envelope, use the inner payload
+  let rawJson = switch A2mlWrapper.unwrapA2ml(jsonStr) {
+  | Ok((payload, _meta)) => payload
+  | Error(_) => jsonStr  // Not A2ML — treat as raw portfolio JSON
+  }
   try {
-    let json = JSON.parseExn(jsonStr)
+    let json = JSON.parseExn(rawJson)
     let obj = json->Js.Json.decodeObject->Belt.Option.getWithDefault(Js.Dict.empty())
     let getString = (d, k) => Js.Dict.get(d, k)->Belt.Option.flatMap(Js.Json.decodeString)->Belt.Option.getWithDefault("")
     let getFloat = (d, k) => Js.Dict.get(d, k)->Belt.Option.flatMap(Js.Json.decodeNumber)->Belt.Option.getWithDefault(0.0)

idaptik-ums/src/generator/PortfolioSync.res

@@ -65,9 +65,10 @@ let parseResponse = %raw(`
 // ---------------------------------------------------------------------------
 
 /// Save a portfolio to VerisimDB via the sync server.
-/// The portfolio is serialized to JSON and sent as a POST to /db/portfolios.
+/// The portfolio is serialized to A2ML-wrapped JSON and sent as a POST to
+/// /db/portfolios. The A2ML envelope carries portfolio provenance metadata.
 let savePortfolio = (portfolio: Portfolio.portfolio): promise<result<string, string>> => {
-  let json = Portfolio.encodePortfolio(portfolio)
+  let json = Portfolio.encodePortfolioA2ml(portfolio)
   let url = `${syncServerUrl}/db/portfolios`
   let response = fetchJson(url, "POST", json)
   response->Js.Promise.then_(r => {
@@ -91,9 +92,9 @@ let loadPortfolio = (portfolioId: string): promise<result<string, string>> => {
 
 /// Save a campaign graph to ArangoDB via the sync server.
 /// Campaign edges are stored as an ArangoDB edge collection for efficient
-/// graph traversal.
+/// graph traversal. The graph is wrapped in an A2ML envelope for provenance.
 let saveCampaignGraph = (graph: CampaignGraph.campaignGraph): promise<result<string, string>> => {
-  let json = CampaignGraph.encodeCampaignGraph(graph)
+  let json = CampaignGraph.encodeCampaignGraphA2ml(graph)
   let url = `${syncServerUrl}/db/campaigns`
   let response = fetchJson(url, "POST", json)
   response->Js.Promise.then_(r => {