@poa-box/core 0.1.0

package/dist/graph/index.js

@@ -0,0 +1,41 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.documents = void 0;
+__exportStar(require("./client"), exports);
+exports.documents = __importStar(require("./documents"));

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @poa-box/core — the stable POP protocol layer.
+ *
+ * Subpath imports are the primary API (tree-shake friendly and explicit):
+ *
+ *   @poa-box/core/chains            chain table + env-injected resolvers + tokens
+ *   @poa-box/core/abis              generated contract ABIs (ALL_ABIS registry)
+ *   @poa-box/core/graph/client      tiered subgraph client (GraphClient)
+ *   @poa-box/core/graph/documents   GraphQL documents + pure derivation helpers
+ *   @poa-box/core/reads/*           typed reads (resolve, per-domain)
+ *   @poa-box/core/tx/*              TxIntent + per-domain intent builders
+ *   @poa-box/core/execute/*         ethers EOA executor + 4337/7702 sponsored path
+ *   @poa-box/core/metadata/*        canonical metadata builders (key order = protocol)
+ *   @poa-box/core/ipfs              pin/fetch client (injected endpoints)
+ *   @poa-box/core/payout|perms|zkemail|encoding|…  pure domain logic
+ *
+ * This barrel re-exports the kernel for convenience; bundle-sensitive
+ * consumers should prefer subpaths.
+ */
+export * from './env';
+export * from './errors';
+export * from './exit-codes';
+export * from './chains';
+export * from './contracts';
+export * from './encoding';
+export * from './format';
+export * from './validation';
+export * from './similarity';
+export * from './stats';
+export * from './label-aliases';
+export * from './multicall';
+export * from './payout';
+export * from './perms';
+export * from './error-catalog';
+export * from './sponsorship-config';
+export * from './context';
+export * from './tx/intent';
+export * from './graph/client';
+export * as documents from './graph/documents';
+export * as abis from './abis';
+export * from './reads/resolve';
+export * from './ipfs';
+export * from './version';
+export * from './task-lens';
+export * from './preflight';
+export * as zkemail from './zkemail';
+export * as intents from './tx';
+export * as reads from './reads';
+export * as metadata from './metadata';

package/dist/index.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * @poa-box/core — the stable POP protocol layer.
+ *
+ * Subpath imports are the primary API (tree-shake friendly and explicit):
+ *
+ *   @poa-box/core/chains            chain table + env-injected resolvers + tokens
+ *   @poa-box/core/abis              generated contract ABIs (ALL_ABIS registry)
+ *   @poa-box/core/graph/client      tiered subgraph client (GraphClient)
+ *   @poa-box/core/graph/documents   GraphQL documents + pure derivation helpers
+ *   @poa-box/core/reads/*           typed reads (resolve, per-domain)
+ *   @poa-box/core/tx/*              TxIntent + per-domain intent builders
+ *   @poa-box/core/execute/*         ethers EOA executor + 4337/7702 sponsored path
+ *   @poa-box/core/metadata/*        canonical metadata builders (key order = protocol)
+ *   @poa-box/core/ipfs              pin/fetch client (injected endpoints)
+ *   @poa-box/core/payout|perms|zkemail|encoding|…  pure domain logic
+ *
+ * This barrel re-exports the kernel for convenience; bundle-sensitive
+ * consumers should prefer subpaths.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metadata = exports.reads = exports.intents = exports.zkemail = exports.abis = exports.documents = void 0;
+__exportStar(require("./env"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./exit-codes"), exports);
+__exportStar(require("./chains"), exports);
+__exportStar(require("./contracts"), exports);
+__exportStar(require("./encoding"), exports);
+__exportStar(require("./format"), exports);
+__exportStar(require("./validation"), exports);
+__exportStar(require("./similarity"), exports);
+__exportStar(require("./stats"), exports);
+__exportStar(require("./label-aliases"), exports);
+__exportStar(require("./multicall"), exports);
+__exportStar(require("./payout"), exports);
+__exportStar(require("./perms"), exports);
+__exportStar(require("./error-catalog"), exports);
+__exportStar(require("./sponsorship-config"), exports);
+__exportStar(require("./context"), exports);
+__exportStar(require("./tx/intent"), exports);
+__exportStar(require("./graph/client"), exports);
+exports.documents = __importStar(require("./graph/documents"));
+exports.abis = __importStar(require("./abis"));
+__exportStar(require("./reads/resolve"), exports);
+__exportStar(require("./ipfs"), exports);
+__exportStar(require("./version"), exports);
+__exportStar(require("./task-lens"), exports);
+__exportStar(require("./preflight"), exports);
+// NOT re-exported here: ./execute (ethers EOA executor + 4337/7702 sponsored
+// path). It requires the optional viem/permissionless peers at load time, and
+// this barrel must stay loadable for reads-only consumers that skip them.
+// Import executors explicitly: '@poa-box/core/execute/ethers' / '/sponsored'.
+exports.zkemail = __importStar(require("./zkemail"));
+exports.intents = __importStar(require("./tx"));
+exports.reads = __importStar(require("./reads"));
+exports.metadata = __importStar(require("./metadata"));

package/dist/ipfs.d.ts

@@ -0,0 +1,39 @@
+/**
+ * IPFS Client
+ * Pin and fetch via The Graph's IPFS endpoint.
+ * Uses direct HTTP (FormData) to match frontend behavior.
+ *
+ * Endpoints, gateway cascade and read-only behavior are injected via
+ * IpfsOptions — hosts that used to rely on POP_IPFS_API_URL /
+ * POP_IPFS_GATEWAY_URL / POP_READONLY build the options with
+ * ipfsOptionsFromEnv(env).
+ */
+import { bytes32ToIpfsCid, ipfsCidToBytes32 } from './encoding';
+import { EnvSource } from './env';
+export interface IpfsOptions {
+    /** Pinning endpoint. Default: The Graph's IPFS API. */
+    apiUrl?: string;
+    /** Extra gateways, prepended to PUBLIC_GATEWAYS (deduped). */
+    gateways?: string[];
+    /** True => pin* throws IpfsError (POP_READONLY semantics). */
+    readonly?: boolean;
+    /** Fetch implementation override (tests / custom agents). Default: globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Build IpfsOptions from an env object using the CLI's historical variable
+ * names: POP_IPFS_API_URL, POP_IPFS_GATEWAY_URL, POP_READONLY.
+ */
+export declare function ipfsOptionsFromEnv(env: EnvSource): IpfsOptions;
+export declare function pinJson(content: string, opts?: IpfsOptions): Promise<string>;
+/**
+ * Pin a file (binary) to IPFS.
+ */
+export declare function pinFile(content: Uint8Array, opts?: IpfsOptions): Promise<string>;
+/**
+ * Fetch JSON content from IPFS.
+ * Accepts CIDv0 (Qm...) or bytes32 (0x...) hash.
+ */
+export declare function fetchJson<T = any>(hashOrCid: string, opts?: IpfsOptions): Promise<T | null>;
+/** Re-export encoding helpers for convenience */
+export { bytes32ToIpfsCid, ipfsCidToBytes32 };

package/dist/ipfs.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * IPFS Client
+ * Pin and fetch via The Graph's IPFS endpoint.
+ * Uses direct HTTP (FormData) to match frontend behavior.
+ *
+ * Endpoints, gateway cascade and read-only behavior are injected via
+ * IpfsOptions — hosts that used to rely on POP_IPFS_API_URL /
+ * POP_IPFS_GATEWAY_URL / POP_READONLY build the options with
+ * ipfsOptionsFromEnv(env).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ipfsCidToBytes32 = exports.bytes32ToIpfsCid = void 0;
+exports.ipfsOptionsFromEnv = ipfsOptionsFromEnv;
+exports.pinJson = pinJson;
+exports.pinFile = pinFile;
+exports.fetchJson = fetchJson;
+const encoding_1 = require("./encoding");
+Object.defineProperty(exports, "bytes32ToIpfsCid", { enumerable: true, get: function () { return encoding_1.bytes32ToIpfsCid; } });
+Object.defineProperty(exports, "ipfsCidToBytes32", { enumerable: true, get: function () { return encoding_1.ipfsCidToBytes32; } });
+const errors_1 = require("./errors");
+const DEFAULT_IPFS_API = 'https://api.thegraph.com/ipfs/api/v0';
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 1000;
+/** Public gateways tried in order after the (optional) caller-supplied ones. */
+const PUBLIC_GATEWAYS = [
+    'https://ipfs.io/ipfs/',
+    'https://cloudflare-ipfs.com/ipfs/',
+    'https://gateway.pinata.cloud/ipfs/',
+    'https://dweb.link/ipfs/',
+];
+/** Per-gateway fetch timeout before cascading to the next gateway. */
+const GATEWAY_TIMEOUT_MS = 5000;
+/**
+ * Build IpfsOptions from an env object using the CLI's historical variable
+ * names: POP_IPFS_API_URL, POP_IPFS_GATEWAY_URL, POP_READONLY.
+ */
+function ipfsOptionsFromEnv(env) {
+    const opts = {};
+    if (env.POP_IPFS_API_URL)
+        opts.apiUrl = env.POP_IPFS_API_URL;
+    if (env.POP_IPFS_GATEWAY_URL)
+        opts.gateways = [env.POP_IPFS_GATEWAY_URL];
+    if (env.POP_READONLY === '1')
+        opts.readonly = true;
+    return opts;
+}
+function getFetch(opts) {
+    return opts?.fetch ?? fetch;
+}
+function getIpfsApiUrl(opts) {
+    return opts?.apiUrl || DEFAULT_IPFS_API;
+}
+/**
+ * Gateway cascade order: caller-supplied gateways (if any) first, then the
+ * public gateways (deduplicated against the supplied values).
+ */
+function getGatewayUrls(opts) {
+    const urls = [];
+    for (const gateway of opts?.gateways ?? []) {
+        if (gateway && !urls.includes(gateway))
+            urls.push(gateway);
+    }
+    for (const gateway of PUBLIC_GATEWAYS) {
+        if (!urls.includes(gateway))
+            urls.push(gateway);
+    }
+    return urls;
+}
+async function withRetry(fn, maxRetries = MAX_RETRIES, baseDelay = BASE_DELAY_MS) {
+    let lastError;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < maxRetries - 1) {
+                const delay = baseDelay * Math.pow(2, attempt);
+                await new Promise(resolve => setTimeout(resolve, delay));
+            }
+        }
+    }
+    throw lastError;
+}
+/**
+ * Pin JSON content to IPFS via The Graph's endpoint.
+ * Uses FormData POST to match frontend behavior exactly.
+ * Returns CIDv0 (Qm...) string.
+ */
+function assertNotReadonly(opts) {
+    // Pinning publishes content publicly and irreversibly. Read commands can
+    // reach here via --pin (org audit-*, leaderboard, portfolio), so this is a
+    // genuine external side effect the read-only mode must refuse.
+    if (opts?.readonly) {
+        throw new errors_1.IpfsError('POP_READONLY=1 — refusing to pin: pinning publishes to IPFS publicly and irreversibly.');
+    }
+}
+async function pinJson(content, opts) {
+    assertNotReadonly(opts);
+    const apiUrl = getIpfsApiUrl(opts);
+    const doFetch = getFetch(opts);
+    const result = await withRetry(async () => {
+        // Node 18+ and every modern browser have FormData and Blob globally
+        const formData = new FormData();
+        formData.append('file', new Blob([content], { type: 'application/octet-stream' }));
+        const response = await doFetch(`${apiUrl}/add`, {
+            method: 'POST',
+            body: formData,
+        });
+        if (!response.ok) {
+            throw new Error(`IPFS upload to ${apiUrl}/add failed: ${response.status} ${response.statusText} (pinning endpoint override: POP_IPFS_API_URL)`);
+        }
+        const data = await response.json();
+        return data.Hash;
+    });
+    if (!result.startsWith('Qm')) {
+        throw new Error(`Unexpected IPFS CID format: ${result}`);
+    }
+    return result;
+}
+/**
+ * Pin a file (binary) to IPFS.
+ */
+async function pinFile(content, opts) {
+    assertNotReadonly(opts);
+    const apiUrl = getIpfsApiUrl(opts);
+    const doFetch = getFetch(opts);
+    const result = await withRetry(async () => {
+        const formData = new FormData();
+        formData.append('file', new Blob([content]));
+        const response = await doFetch(`${apiUrl}/add`, {
+            method: 'POST',
+            body: formData,
+        });
+        if (!response.ok) {
+            throw new Error(`IPFS upload to ${apiUrl}/add failed: ${response.status} ${response.statusText} (pinning endpoint override: POP_IPFS_API_URL)`);
+        }
+        const data = await response.json();
+        return data.Hash;
+    });
+    return result;
+}
+/**
+ * Fetch JSON content from IPFS.
+ * Accepts CIDv0 (Qm...) or bytes32 (0x...) hash.
+ */
+async function fetchJson(hashOrCid, opts) {
+    if (!hashOrCid)
+        return null;
+    // Handle zero hashes
+    if (hashOrCid.startsWith('0x') && /^0x0+$/.test(hashOrCid))
+        return null;
+    // Convert bytes32 to CID if needed
+    let cid = hashOrCid;
+    if (hashOrCid.startsWith('0x')) {
+        const converted = (0, encoding_1.bytes32ToIpfsCid)(hashOrCid);
+        if (!converted)
+            return null;
+        cid = converted;
+    }
+    // Two attempts (1 retry) around the FULL gateway cascade
+    const result = await withRetry(() => fetchJsonViaGatewayCascade(cid, opts), 2);
+    return result;
+}
+/**
+ * Fetch a single CID from one gateway with a hard timeout.
+ * Aborts (and cascades) after GATEWAY_TIMEOUT_MS.
+ */
+async function fetchFromGateway(gatewayUrl, cid, opts) {
+    const doFetch = getFetch(opts);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), GATEWAY_TIMEOUT_MS);
+    try {
+        const response = await doFetch(`${gatewayUrl}${cid}`, { signal: controller.signal });
+        if (!response.ok) {
+            throw new Error(`IPFS fetch failed: ${response.status} ${response.statusText}`);
+        }
+        const text = await response.text();
+        if (text.length > 10 * 1024 * 1024) {
+            throw new Error('IPFS response too large (>10MB)');
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Invalid JSON from IPFS (CID: ${cid}). Response starts with: ${text.slice(0, 100)}`);
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Try each gateway in order, cascading to the next on any failure
+ * (HTTP error, timeout/abort, oversized or non-JSON body).
+ * Throws IpfsError once every gateway has failed.
+ */
+async function fetchJsonViaGatewayCascade(cid, opts) {
+    const gateways = getGatewayUrls(opts);
+    const failures = [];
+    for (const gatewayUrl of gateways) {
+        try {
+            return await fetchFromGateway(gatewayUrl, cid, opts);
+        }
+        catch (error) {
+            const reason = error?.name === 'AbortError'
+                ? `timed out after ${GATEWAY_TIMEOUT_MS}ms`
+                : (error?.message || String(error));
+            failures.push(`${gatewayUrl}: ${reason}`);
+        }
+    }
+    throw new errors_1.IpfsError(`All ${gateways.length} gateways failed for CID ${cid}. ${failures.join('; ')}`);
+}

package/dist/label-aliases.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared label alias map for contract-name matching.
+ *
+ * Some contracts identify on-chain with a token symbol (GTC for Gitcoin)
+ * or a descriptive technical term (Vote-escrowed CRV for Curve's veCRV)
+ * that doesn't literally contain the project's name. This map says
+ * "if the expected label is X, consider these on-chain strings to be
+ * an acceptable match."
+ *
+ * Keys are lower-case filename / project labels; values are lower-case
+ * tokens expected to appear in the on-chain `name()` return value.
+ *
+ * Populated from HB#386's corpus identity sweep first-run false positives
+ * (task #391) and used by:
+ *   - src/commands/org/probe-access.ts → matchContractName (task #395, HB)
+ *   - agent/scripts/audit-corpus-identity-sweep.mjs (filename-fuzzy mode)
+ *
+ * Additions should be justified with a short comment explaining why the
+ * alias is correct (e.g. "Curve's token is CRV; the VotingEscrow contract
+ * identifies as 'Vote-escrowed CRV'").
+ */
+export declare const LABEL_ALIASES: Record<string, readonly string[]>;
+/**
+ * Return the full list of strings considered an acceptable match for the
+ * given label: the label itself, plus any aliases registered under any of
+ * its lower-cased whitespace-separated words. Case-insensitive.
+ *
+ * Example:
+ *   expandAliases("Curve VotingEscrow") → ["curve votingescrow", "crv", "vote-escrowed"]
+ */
+export declare function expandAliases(label: string): string[];

package/dist/label-aliases.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LABEL_ALIASES = void 0;
+exports.expandAliases = expandAliases;
+/**
+ * Shared label alias map for contract-name matching.
+ *
+ * Some contracts identify on-chain with a token symbol (GTC for Gitcoin)
+ * or a descriptive technical term (Vote-escrowed CRV for Curve's veCRV)
+ * that doesn't literally contain the project's name. This map says
+ * "if the expected label is X, consider these on-chain strings to be
+ * an acceptable match."
+ *
+ * Keys are lower-case filename / project labels; values are lower-case
+ * tokens expected to appear in the on-chain `name()` return value.
+ *
+ * Populated from HB#386's corpus identity sweep first-run false positives
+ * (task #391) and used by:
+ *   - src/commands/org/probe-access.ts → matchContractName (task #395, HB)
+ *   - agent/scripts/audit-corpus-identity-sweep.mjs (filename-fuzzy mode)
+ *
+ * Additions should be justified with a short comment explaining why the
+ * alias is correct (e.g. "Curve's token is CRV; the VotingEscrow contract
+ * identifies as 'Vote-escrowed CRV'").
+ */
+exports.LABEL_ALIASES = {
+    // Gitcoin's token is GTC; Gitcoin's GovernorAlpha contract identifies
+    // as "GTC Governor Alpha" on-chain. HB#386 sweep surfaced this.
+    gitcoin: ['gtc'],
+    // Curve's VotingEscrow contract identifies as "Vote-escrowed CRV" on-chain.
+    // The label "curve votingescrow" → actual "Vote-escrowed CRV" is correct
+    // but requires the CRV alias (Curve's token). HB#386 sweep.
+    curve: ['crv', 'vote-escrowed'],
+    // Balancer's veBAL at 0xC128a9954e6c874eA3d62ce62B468bA073093F25 identifies
+    // as "Vote Escrowed Balancer BPT" on-chain (the locked token is the 80/20
+    // BAL/WETH BPT, not raw BAL). Verified via eth_call name() on ethereum
+    // mainnet in HB#290 task #396. Pre-registered to unblock the veToken
+    // family expansion queued in Sprint 14.
+    balancer: ['bal', 'bpt', 'vote escrowed balancer'],
+    // Frax's veFXS at 0xc8418aF6358FFddA74e09Ca9CC3Fe03Ca6aDC5b0 identifies as
+    // "Vote-Escrowed FXS" on-chain — same Curve-style naming but with FXS
+    // token ticker. Verified via eth_call name() on ethereum mainnet in
+    // HB#290 task #396.
+    frax: ['fxs', 'vote-escrowed fxs'],
+    // Velodrome and Aerodrome are Solidly-style veNFT systems (Velodrome on
+    // Optimism, Aerodrome on Base). Both identify their vote-escrow contract
+    // with the generic token name "veNFT" rather than the project name.
+    // Pre-registered based on the Solidly contract convention. Live
+    // verification happens when the audit actually probes them.
+    velodrome: ['velo', 'venft'],
+    aerodrome: ['aero', 'venft'],
+};
+/**
+ * Return the full list of strings considered an acceptable match for the
+ * given label: the label itself, plus any aliases registered under any of
+ * its lower-cased whitespace-separated words. Case-insensitive.
+ *
+ * Example:
+ *   expandAliases("Curve VotingEscrow") → ["curve votingescrow", "crv", "vote-escrowed"]
+ */
+function expandAliases(label) {
+    const lowered = label.toLowerCase();
+    const out = [lowered];
+    for (const word of lowered.split(/\s+/).filter(Boolean)) {
+        const aliases = exports.LABEL_ALIASES[word];
+        if (aliases)
+            out.push(...aliases);
+    }
+    return out;
+}

package/dist/metadata/education.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Education module metadata document.
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT: {name, description, link, quiz, answers}
+ * MUST match the frontend for subgraph/UI compatibility. Both education
+ * writers pin this exact shape:
+ *   - `pop education create` — src/commands/education/create-module.ts
+ *   - `pop education update` — src/commands/education/update.ts (re-pin path)
+ */
+export interface EducationModuleMetadata {
+    name: string;
+    description: string;
+    link: string;
+    quiz: string[];
+    answers: string[][];
+}
+/**
+ * Port of the metadata document `pop education create` /
+ * `pop education update` pin — key order is load-bearing:
+ * name, description, link, quiz, answers.
+ */
+export declare function buildEducationModuleMetadata(params: {
+    name: string;
+    description?: string;
+    link?: string;
+    quiz?: string[];
+    answers?: string[][];
+}): EducationModuleMetadata;
+/** Exact serialization the CLI pins (plain JSON.stringify). */
+export declare function serializeEducationModuleMetadata(metadata: EducationModuleMetadata): string;

package/dist/metadata/education.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Education module metadata document.
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT: {name, description, link, quiz, answers}
+ * MUST match the frontend for subgraph/UI compatibility. Both education
+ * writers pin this exact shape:
+ *   - `pop education create` — src/commands/education/create-module.ts
+ *   - `pop education update` — src/commands/education/update.ts (re-pin path)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEducationModuleMetadata = buildEducationModuleMetadata;
+exports.serializeEducationModuleMetadata = serializeEducationModuleMetadata;
+/**
+ * Port of the metadata document `pop education create` /
+ * `pop education update` pin — key order is load-bearing:
+ * name, description, link, quiz, answers.
+ */
+function buildEducationModuleMetadata(params) {
+    return {
+        name: params.name,
+        description: params.description || '',
+        link: params.link || '',
+        quiz: params.quiz || [],
+        answers: params.answers || [],
+    };
+}
+/** Exact serialization the CLI pins (plain JSON.stringify). */
+function serializeEducationModuleMetadata(metadata) {
+    return JSON.stringify(metadata);
+}

package/dist/metadata/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Canonical metadata builders. KEY ORDER IS A PROTOCOL CONTRACT — the
+ * subgraph and every frontend parse these documents; hosts must never
+ * hand-build metadata objects.
+ */
+export * as education from './education';
+export * as org from './org';
+export * as proposal from './proposal';
+export * as role from './role';
+export * as task from './task';
+export * as token from './token';
+export * as user from './user';

package/dist/metadata/index.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Canonical metadata builders. KEY ORDER IS A PROTOCOL CONTRACT — the
+ * subgraph and every frontend parse these documents; hosts must never
+ * hand-build metadata objects.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.user = exports.token = exports.task = exports.role = exports.proposal = exports.org = exports.education = void 0;
+exports.education = __importStar(require("./education"));
+exports.org = __importStar(require("./org"));
+exports.proposal = __importStar(require("./proposal"));
+exports.role = __importStar(require("./role"));
+exports.task = __importStar(require("./task"));
+exports.token = __importStar(require("./token"));
+exports.user = __importStar(require("./user"));