Using OpenChainGraph with the Open Knowledge Format

okf/
├── index.md                      # root — progressive disclosure entry point (OKF reserved)
├── log.md                         # generation history — one line per CI run (OKF reserved)
├── mandate-types/
│   ├── index.md                   # mandate-type group index
│   ├── payment_mandate.md
│   ├── payment_policy.md
│   ├── settlement_mandate.md
│   ├── compliance_mandate.md
│   ├── prompt_template.md
│   └── …one file per distinct mandate_type
└── tools/
    ├── index.md                   # tool list — links to every concept below
    ├── art-01-ap2-mandate-chain-validator.md
    ├── art-02-agent-spend-policy-simulator.md
    ├── art-03-x402-settlement-modeler.md
    ├── art-04-agent-identity-attestation-checker.md
    ├── ptg-01-ap2-prompt-template-generator.md
    └── …one concept per node where status === "live"

---
type: DecisionTool
title: AP2 Mandate-Chain Validator
description: >
  Validates AP2 v0.2 Intent→Cart→Payment mandate trio: signature-chain
  integrity, scope/limit consistency, TTL/expiry, over-spend detection,
  Human-Not-Present autonomous-agent flows. Publishes conformance
  test-vector fixtures.
resource: https://ainumbers.co/chaingraph/art-01-ap2-mandate-chain-validator.html
tags:
  - payment_mandate
  - wave-1
  - mcp:validate_ap2_mandate_chain
timestamp: 2026-06-18T00:00:00Z
---

# AP2 Mandate-Chain Validator

Exports a decision: a conformance verdict over an AP2 v0.2 Intent→Cart→Payment
mandate chain, including signature integrity, scope limits, TTL, and
Human-Not-Present flow checks. Call this tool via MCP and receive a signed
OCG artifact — not an advisory.

## Inputs

- intent_mandate — AP2 v0.2 Intent Mandate object (JSON)
- cart_mandate — AP2 v0.2 Cart Mandate object (JSON)
- payment_mandate — AP2 v0.2 Payment Mandate object (JSON)
- agent_context — optional: HNP flag, agent DID, delegation depth

## Outputs

- conformance_verdict — PASS / FAIL / PARTIAL per check category
- signature_chain_valid — boolean
- scope_violations — array of detected scope or limit breaches
- compliance_flags[] — per-framework flags (AP2 v0.2, HNP-001)
- execution_hash — SHA-256 over sorted-key JSON of inputs + outputs

## Chains

**Consumes:** _(root tool — no upstream dependencies)_

**Feeds:**
- [Agent Spend-Policy Simulator](art-02-agent-spend-policy-simulator.md)
- [x402 Settlement Cost & Finality Modeler](art-03-x402-settlement-modeler.md)
- [Agent Identity & Authorization Attestation Checker](art-04-agent-identity-attestation-checker.md)
- [ACP Checkout Conformance Validator](art-12-acp-checkout-conformance-validator.md)
- [AP2 Prompt Template Generator](../tools/ptg-01-ap2-prompt-template-generator.md)

#!/usr/bin/env node
// generate-okf.mjs
// Reads chaingraph.json → writes okf/tools/{tool_id}.md for every live node.
// Run: node generate-okf.mjs
// Requires Node 18+ (fs/promises, no external deps)

import { readFile, writeFile, mkdir } from "fs/promises";
import { join, dirname } from "path";
import { fileURLToPath } from "url";

const __dir    = dirname(fileURLToPath(import.meta.url));
const INDEX    = join(__dir, "chaingraph.json");
const OUT_DIR  = join(__dir, "okf", "tools");
const NOW_ISO  = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");

// Build a lookup: tool_id → display_name (for resolving consumes/feeds labels)
function buildLookup(nodes) {
  const map = {};
  for (const n of nodes) map[n.tool_id] = n.display_name;
  return map;
}

// Render YAML frontmatter for a node
function frontmatter(node) {
  const desc = node.description.replace(/\n/g, "\n  "); // indent for YAML block scalar
  const tags = [
    node.mandate_type,
    `wave-${node.wave}`,
    `mcp:${node.mcp_name}`,
  ].map(t => `  - ${t}`).join("\n");
  return [
    "---",
    `type: DecisionTool`,
    `title: ${node.display_name}`,
    `description: >`,
    `  ${desc}`,
    `resource: ${node.url}`,
    `tags:`,
    tags,
    `timestamp: ${NOW_ISO}`,
    "---",
  ].join("\n");
}

// Resolve an edge array to markdown links or prose
function edgeLinks(ids, lookup, label) {
  if (!ids || ids.length === 0) {
    return `**${label}:** _(root tool — no upstream dependencies)_`;
  }
  if (ids[0] === "ALL") {
    return `**${label}:** _(standalone — accepts any upstream OCG artifact)_`;
  }
  const links = ids.map(id => {
    const name = lookup[id] ?? id;
    return `- [${name}](${id}.md)`;
  }).join("\n");
  return `**${label}:**\n${links}`;
}

// Render full concept markdown for a node
function renderConcept(node, lookup) {
  return [
    frontmatter(node),
    "",
    `# ${node.display_name}`,
    "",
    `Exports a decision via [\`${node.mcp_name}\`](${node.url}). ` +
    `Call this tool through the OpenChainGraph MCP server and receive a ` +
    `signed OCG artifact with an \`execution_hash\` — not an advisory.`,
    "",
    "## Inputs",
    "",
    `See the tool's input schema: <${node.url}#manifest>`,
    "",
    "## Outputs",
    "",
    "- `execution_hash` — SHA-256 over sorted-key JSON of inputs + outputs",
    "- `compliance_flags[]` — per-framework PASS / FAIL / PARTIAL verdicts",
    "- `audit_signature` — Ed25519 signature over the execution hash",
    "- `chain` — parent_hashes[], parent_tool_ids[], chain_depth",
    "",
    "## Chains",
    "",
    edgeLinks(node.consumes, lookup, "Consumes"),
    "",
    edgeLinks(node.feeds, lookup, "Feeds"),
  ].join("\n");
}

// Main
async function main() {
  const raw   = await readFile(INDEX, "utf8");
  const index = JSON.parse(raw);
  const live  = index.nodes.filter(n => n.status === "live");
  const lookup = buildLookup(live);

  await mkdir(OUT_DIR, { recursive: true });

  let count = 0;
  for (const node of live) {
    const filename = join(OUT_DIR, `${node.tool_id}.md`);
    const content  = renderConcept(node, lookup);
    await writeFile(filename, content, "utf8");
    count++;
  }

  console.log(`[generate-okf] wrote ${count} concept files → ${OUT_DIR}`);
  console.log(`[generate-okf] index version: ${index.version}, updated: ${index.updated}`);
}

main().catch(err => { console.error(err); process.exit(1); });

---
type: KnowledgeIndex
title: OpenChainGraph Tool Concepts
description: >
  OKF companion bundle for the AINumbers ChainGraph suite.
  One concept file per live tool — auto-generated from chaingraph.json.
  Graph edges (consumes/feeds) are markdown links: follow them to plan
  a decision chain before calling any MCP endpoint.
resource: https://ainumbers.co/chaingraph/chaingraph-hub.html
tags:
  - openchain-graph
  - v0.3
  - okf-companion
timestamp: 2026-06-18T00:00:00Z
---

# OpenChainGraph Tool Concepts

This bundle maps every live tool in the AINumbers ChainGraph suite to an
OKF concept document. Use it to understand what each tool does, what it
consumes, and what it feeds — then invoke the real MCP endpoint at
`https://mcp.ainumbers.co/mcp`.

## By mandate type

- [Payment Mandate tools](mandate-types/payment_mandate.md) — AP2 v0.2 mandate validation and related
- [Payment Policy tools](mandate-types/payment_policy.md) — spend policy simulation
- [Settlement Mandate tools](mandate-types/settlement_mandate.md) — x402 and FX settlement
- [Compliance Mandate tools](mandate-types/compliance_mandate.md) — KYA, EU AI Act, sanctions
- [Prompt Template tools](mandate-types/prompt_template.md) — artifact-to-LLM prompt generation

## All tools (alphabetical)

See [tools/index.md](tools/index.md) for the full list.

## What this bundle is not

These concept documents describe tools. They are not OCG decision artifacts.
They carry no `execution_hash`, no `audit_signature`, and no compliance verdict.
OCG artifacts are produced at runtime by the tools themselves — they are never
stored in this knowledge bundle.

# OKF Bundle Generation Log

Each line records a bundle regeneration. Format:
`- {ISO date} — generated {N} concepts from chaingraph.json v{version}`

- 2026-06-18 — generated 48 concepts from chaingraph.json v1.10.0

/**
 * walkOkfChain(startConceptMd, fetchFn)
 *   startConceptMd — the markdown text of the starting concept file
 *   fetchFn        — async (relativePath: string) => markdown text
 *
 * Resolves the "Feeds" links from the start concept,
 * fetches each linked concept, and returns a flat ordered list
 * of { toolId, displayName, mcpTag, resourceUrl } for chain planning.
 *
 * This mirrors walking chaingraph.json's feeds[] edges — the OKF links
 * are the same graph, expressed as navigable markdown.
 */
async function walkOkfChain(startConceptMd, fetchFn) {
  const visited = new Set();
  const chain   = [];

  async function visit(md, depth) {
    if (depth > 6) return;  // guard against deep cycles

    // Extract title and mcp tag from frontmatter
    const titleMatch = md.match(/^title:\s*(.+)$/m);
    const mcpMatch   = md.match(/^\s*-\s*mcp:(\S+)/m);
    const resMatch   = md.match(/^resource:\s*(.+)$/m);

    const displayName = titleMatch?.[1]?.trim() ?? "Unknown";
    const mcpTag      = mcpMatch?.[1] ?? "";
    const resourceUrl = resMatch?.[1]?.trim() ?? "";

    chain.push({ displayName, mcpTag, resourceUrl });

    // Find all markdown links in the ## Feeds section
    const feedsSection = md.match(/## Chains[\s\S]*?\*\*Feeds:\*\*([\s\S]*?)(?=\n##|\n---|\Z)/)?.[1] ?? "";
    const linkRe       = /\[([^\]]+)\]\(([^)]+\.md)\)/g;
    let match;

    while ((match = linkRe.exec(feedsSection)) !== null) {
      const relativePath = match[2];
      if (visited.has(relativePath)) continue;
      visited.add(relativePath);
      try {
        const nextMd = await fetchFn(relativePath);
        await visit(nextMd, depth + 1);
      } catch { /* skip missing concepts */ }
    }
  }

  await visit(startConceptMd, 0);
  return chain;
}

// Usage — plan a chain starting from AP2 Mandate-Chain Validator:
const chain = await walkOkfChain(
  await fetch("https://ainumbers.co/chaingraph/okf/tools/art-01-ap2-mandate-chain-validator.md").then(r => r.text()),
  path => fetch(`https://ainumbers.co/chaingraph/okf/tools/${path}`).then(r => r.text())
);
// → [{ displayName: "AP2 Mandate-Chain Validator", mcpTag: "validate_ap2_mandate_chain", ... }, ...]
// Now call each mcp_name tool in order via https://mcp.ainumbers.co/mcp