aipou-mcp-server 0.4.0 → 0.6.0

package/dist/init.d.ts

@@ -1,3 +1,5 @@
+export declare const AIPOU_TOKEN_ADDRESS = "0x55f0Cc5e51A1284D20337d6cbb18938C8A1ABCbB";
+export declare const AIPOU_CLAIMS_ADDRESS = "0x4ca4C98fB784D20EdC8E2A7F531dAab4c6e53058";
 export interface InitializationResult {
     mode: "persistent_identity_initialized" | "persistent_identity_already_initialized";
     wallet: string;
@@ -7,8 +9,8 @@ export interface InitializationResult {
     mcpConfig: {
         mcpServers: {
             aipou: {
-                command: "npx";
-                args: ["-y", "aipou-mcp-server"];
+                command: string;
+                args: string[];
                 env: {
                     AIPOU_AGENT_KEY_FILE: string;
                     AIPOU_DATA_DIR: string;
@@ -26,5 +28,9 @@ export interface InitializationResult {
         claimSubmitted: false;
     };
 }
+export declare function installationCommand(moduleUrl?: string): Promise<{
+    command: string;
+    args: string[];
+}>;
 export declare function initializePersistentIdentity(dataDirInput?: string): Promise<InitializationResult>;
 export declare function describeExistingIdentity(dataDirInput?: string): Promise<InitializationResult>;

package/dist/init.js

@@ -1,15 +1,29 @@
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { Wallet } from "ethers";
 import { restrictToCurrentUser } from "./secure-file.js";
-const TOKEN_ADDRESS = "0x55f0Cc5e51A1284D20337d6cbb18938C8A1ABCbB";
-const CLAIMS_ADDRESS = "0x4ca4C98fB784D20EdC8E2A7F531dAab4c6e53058";
+export const AIPOU_TOKEN_ADDRESS = "0x55f0Cc5e51A1284D20337d6cbb18938C8A1ABCbB";
+export const AIPOU_CLAIMS_ADDRESS = "0x4ca4C98fB784D20EdC8E2A7F531dAab4c6e53058";
 function identityPaths(dataDirInput) {
     const dataDir = path.resolve(dataDirInput || path.join(os.homedir(), ".aipou"));
     return { dataDir, keyFile: path.join(dataDir, "agent-wallet.key") };
 }
-function buildResult(mode, walletAddress, dataDir, keyFile) {
+export async function installationCommand(moduleUrl = import.meta.url) {
+    const directory = path.dirname(fileURLToPath(moduleUrl));
+    try {
+        const workspace = JSON.parse(await readFile(path.resolve(directory, "../../package.json"), "utf8"));
+        if (workspace.name === "ai-proof-of-us" && workspace.workspaces?.includes("mcp-server")) {
+            return { command: process.execPath, args: [path.join(directory, "index.js")] };
+        }
+    }
+    catch { /* An npm installation has no source workspace. */ }
+    const pkg = JSON.parse(await readFile(path.resolve(directory, "../package.json"), "utf8"));
+    return { command: "npx", args: ["-y", `aipou-mcp-server@${pkg.version}`] };
+}
+async function buildResult(mode, walletAddress, dataDir, keyFile) {
+    const launch = await installationCommand();
     return {
         mode,
         wallet: walletAddress,
@@ -19,13 +33,12 @@ function buildResult(mode, walletAddress, dataDir, keyFile) {
         mcpConfig: {
             mcpServers: {
                 aipou: {
-                    command: "npx",
-                    args: ["-y", "aipou-mcp-server"],
+                    ...launch,
                     env: {
                         AIPOU_AGENT_KEY_FILE: keyFile,
                         AIPOU_DATA_DIR: dataDir,
-                        AIPOU_CONTRACT_ADDRESS: TOKEN_ADDRESS,
-                        AIPOU_CLAIMS_ADDRESS: CLAIMS_ADDRESS
+                        AIPOU_CONTRACT_ADDRESS: AIPOU_TOKEN_ADDRESS,
+                        AIPOU_CLAIMS_ADDRESS
                     }
                 }
             }

package/dist/init.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdtemp, mkdir, readFile, writeFile, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -9,8 +9,20 @@ import { promisify } from "node:util";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { agentWallet } from "./identity.js";
-import { describeExistingIdentity, initializePersistentIdentity } from "./init.js";
+import { describeExistingIdentity, initializePersistentIdentity, installationCommand } from "./init.js";
 const execFileAsync = promisify(execFile);
+test("installed package config pins its actual version instead of silently switching latest", async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "aipou-installed-config-"));
+    try {
+        await mkdir(path.join(dir, "dist"));
+        await writeFile(path.join(dir, "package.json"), JSON.stringify({ version: "0.6.0" }));
+        const { pathToFileURL } = await import("node:url");
+        assert.deepEqual(await installationCommand(pathToFileURL(path.join(dir, "dist", "index.js")).href), { command: "npx", args: ["-y", "aipou-mcp-server@0.6.0"] });
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
 function parseTextResult(result) {
     const content = result.content;
     const text = content?.find((part) => part.type === "text")?.text;
@@ -91,9 +103,11 @@ test("CLI init output starts an MCP server with the generated key file", async (
         const privateKey = (await readFile(result.keyFile, "utf8")).trim();
         assert.equal(stdout.includes(privateKey), false);
         const config = result.mcpConfig.mcpServers.aipou;
+        assert.equal(config.command, process.execPath);
+        assert.deepEqual(config.args, [indexPath]);
         transport = new StdioClientTransport({
-            command: process.execPath,
-            args: [indexPath],
+            command: config.command,
+            args: config.args,
             stderr: "pipe",
             env: { ...process.env, ...config.env }
         });

package/dist/lock.js

@@ -1,13 +1,50 @@
-import { rm, stat, writeFile } from "node:fs/promises";
-// State mutations finish in well under a second, so a lock older than this
-// belongs to a crashed process and can be reclaimed safely.
+import { readFile, rm, stat, writeFile } from "node:fs/promises";
+// Age alone never makes a live process's lock reclaimable.
 const STALE_LOCK_MS = 15_000;
 const ACQUIRE_TIMEOUT_MS = 10_000;
+async function reclaimDeadLock(lockPath) {
+    // Serialize reclaimers so a second observer cannot delete a new owner's lock
+    // using a stale PID read. An interrupted reclaimer fails closed for review.
+    const gate = `${lockPath}.reclaim`;
+    try {
+        await writeFile(gate, `${process.pid}\n`, { flag: "wx", mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return;
+        throw error;
+    }
+    try {
+        const info = await stat(lockPath);
+        if (Date.now() - info.mtimeMs <= STALE_LOCK_MS)
+            return;
+        const pid = Number((await readFile(lockPath, "utf8")).trim());
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            return;
+        try {
+            process.kill(pid, 0);
+        }
+        catch (error) {
+            if (error.code === "ESRCH")
+                await rm(lockPath);
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    finally {
+        await rm(gate, { force: true });
+    }
+}
 async function acquire(lockPath) {
     const deadline = Date.now() + ACQUIRE_TIMEOUT_MS;
     for (;;) {
         try {
-            await writeFile(lockPath, `${process.pid}\n`, { encoding: "utf8", flag: "wx" });
+            await writeFile(lockPath, `${process.pid}\n`, {
+                encoding: "utf8",
+                flag: "wx",
+            });
             return;
         }
         catch (error) {
@@ -17,16 +54,17 @@ async function acquire(lockPath) {
         try {
             const info = await stat(lockPath);
             if (Date.now() - info.mtimeMs > STALE_LOCK_MS) {
-                await rm(lockPath, { force: true });
-                continue;
+                await reclaimDeadLock(lockPath);
             }
         }
-        catch {
+        catch (error) {
             // The holder released the lock between attempts; retry immediately.
-            continue;
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
         }
         if (Date.now() > deadline) {
-            throw new Error(`Timed out waiting for lock ${lockPath}; remove it manually if no other AIPOU process is running`);
+            throw new Error("AIPOU operation is busy; retry when the other process finishes. Never remove an active lock.");
         }
         await new Promise((resolve) => setTimeout(resolve, 25 + Math.floor(Math.random() * 75)));
     }

package/dist/lock.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lock.test.js

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, writeFile, utimes, rm, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { withFileLock } from "./lock.js";
+test("a live PID keeps its old lock; a stopped process can be reclaimed", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "aipou-lock-test-"));
+    const file = path.join(dir, "operation.lock");
+    try {
+        await writeFile(file, String(process.pid));
+        await utimes(file, 0, 0);
+        await assert.rejects(withFileLock(file, async () => assert.fail("live lock was stolen")), /busy/);
+        assert.equal(await readFile(file, "utf8"), String(process.pid));
+        const child = spawn(process.execPath, ["-e", "process.exit(0)"]);
+        await once(child, "exit");
+        await writeFile(file, String(child.pid));
+        await utimes(file, 0, 0);
+        assert.equal(await withFileLock(file, async () => "recovered"), "recovered");
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});

package/dist/observed-outcome-pilot.d.ts

@@ -0,0 +1,16 @@
+import type { EvidenceReport } from "./evidence.js";
+export interface ObservedOutcomePilotResult {
+    mode: "observed_outcome_pilot";
+    storage: "removed_after_pilot";
+    workReceiptId: string;
+    evidence: EvidenceReport;
+    safety: {
+        networkRequired: false;
+        fundsMoved: false;
+        claimSubmitted: false;
+        deliveryClaimed: false;
+        acceptanceClaimed: false;
+    };
+}
+/** Rehearses local receipt creation and independent verification only. */
+export declare function runObservedOutcomePilot(): Promise<ObservedOutcomePilotResult>;

package/dist/observed-outcome-pilot.js

@@ -0,0 +1,59 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Wallet } from "ethers";
+import { canonicalJson, sha256Hex } from "./canonical.js";
+import { beginTask, completeTask } from "./receipts.js";
+import { verifyAipouReceipt } from "./receipt-verifier.js";
+const CLAIMS_ADDRESS = "0x4ca4C98fB784D20EdC8E2A7F531dAab4c6e53058";
+const ENVIRONMENT_KEYS = ["AIPOU_AGENT_PRIVATE_KEY", "AIPOU_DATA_DIR"];
+/** Rehearses local receipt creation and independent verification only. */
+export async function runObservedOutcomePilot() {
+    const previous = new Map(ENVIRONMENT_KEYS.map((key) => [key, process.env[key]]));
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), "aipou-observed-outcome-pilot-"));
+    process.env.AIPOU_DATA_DIR = dataDir;
+    process.env.AIPOU_AGENT_PRIVATE_KEY = Wallet.createRandom().privateKey;
+    try {
+        const session = await beginTask({
+            provider: "local-pilot",
+            model: "observed-outcome-pilot",
+            client: "aipou-cli",
+            taskHash: sha256Hex(canonicalJson({ kind: "pilot", action: "bounded_local_execution" })),
+            chainId: 8453,
+            verifyingContract: CLAIMS_ADDRESS
+        });
+        const receipt = await completeTask({
+            nonce: session.nonce,
+            inputTokens: 24,
+            outputTokens: 16,
+            durationSeconds: 1,
+            outputHash: sha256Hex(canonicalJson({ artifact: "pilot-output-reference", status: "host-observed" }))
+        });
+        const verification = verifyAipouReceipt(receipt);
+        if (!verification.valid)
+            throw new Error(`Pilot receipt verification failed: ${verification.errors.join("; ")}`);
+        return {
+            mode: "observed_outcome_pilot",
+            storage: "removed_after_pilot",
+            workReceiptId: receipt.receiptId,
+            evidence: verification.evidence,
+            safety: {
+                networkRequired: false,
+                fundsMoved: false,
+                claimSubmitted: false,
+                deliveryClaimed: false,
+                acceptanceClaimed: false
+            }
+        };
+    }
+    finally {
+        await rm(dataDir, { recursive: true, force: true });
+        for (const key of ENVIRONMENT_KEYS) {
+            const value = previous.get(key);
+            if (value === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = value;
+        }
+    }
+}

package/dist/observed-outcome-pilot.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/observed-outcome-pilot.test.js

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { runObservedOutcomePilot } from "./observed-outcome-pilot.js";
+test("observed-outcome pilot does not upgrade local execution into delivery or acceptance", async () => {
+    const result = await runObservedOutcomePilot();
+    assert.equal(result.mode, "observed_outcome_pilot");
+    assert.match(result.workReceiptId, /^0x[0-9a-f]{64}$/);
+    assert.deepEqual(result.evidence, {
+        receiptIntegrity: "VERIFIED",
+        walletAuthorization: "VERIFIED",
+        collectorSignature: "VERIFIED",
+        hostExecution: "OBSERVED",
+        delivery: "UNKNOWN",
+        businessAcceptance: "ABSENT",
+        settlement: "ABSENT",
+        externalEffect: "UNKNOWN"
+    });
+    assert.deepEqual(result.safety, {
+        networkRequired: false,
+        fundsMoved: false,
+        claimSubmitted: false,
+        deliveryClaimed: false,
+        acceptanceClaimed: false
+    });
+});

package/dist/paybox-link.d.ts

@@ -0,0 +1,34 @@
+export declare const PAYBOX_OPERATION_SCHEME = "paybox-operation-v1";
+export declare const EXTERNAL_EVIDENCE_LINK_SCHEME = "external-evidence-link-v1";
+export type PayboxWorkLinkInput = {
+    workReceiptId: string;
+    payboxOperationId: string;
+    payboxOperationDigest: string;
+    issuedAt: string;
+};
+export type PayboxWorkLink = {
+    scheme: typeof EXTERNAL_EVIDENCE_LINK_SCHEME;
+    /** Stable logical identity that excludes issuedAt for retry-safe deduplication. */
+    linkId: string;
+    relation: "supports";
+    source: {
+        kind: "receipt";
+        scheme: "aipou-receipt-v1";
+        id: string;
+        digest: string;
+    };
+    target: {
+        kind: "payment-operation";
+        scheme: typeof PAYBOX_OPERATION_SCHEME;
+        id: string;
+        digest: string;
+    };
+    privacy: "digest_only";
+    issuedAt: string;
+    linkDigest: string;
+};
+/**
+ * Creates a correlation artifact only. It neither calls Paybox nor establishes
+ * payment, settlement, claim eligibility, or any authority beyond the link.
+ */
+export declare function createPayboxWorkLink(input: PayboxWorkLinkInput): PayboxWorkLink;

package/dist/paybox-link.js

@@ -0,0 +1,52 @@
+import { canonicalJson, sha256Hex } from "./canonical.js";
+export const PAYBOX_OPERATION_SCHEME = "paybox-operation-v1";
+export const EXTERNAL_EVIDENCE_LINK_SCHEME = "external-evidence-link-v1";
+const receiptIdPattern = /^0x[0-9a-f]{64}$/;
+const sha256Pattern = /^sha256:[0-9a-f]{64}$/;
+function assertValidInput(input) {
+    if (!receiptIdPattern.test(input.workReceiptId)) {
+        throw new Error("workReceiptId must be a lowercase 0x-prefixed SHA-256 identifier");
+    }
+    if (!sha256Pattern.test(input.payboxOperationDigest)) {
+        throw new Error("payboxOperationDigest must be a lowercase sha256 digest");
+    }
+    if (input.payboxOperationId.length < 1 || input.payboxOperationId.length > 256) {
+        throw new Error("payboxOperationId must be an opaque reference between 1 and 256 characters");
+    }
+    if (!Number.isFinite(Date.parse(input.issuedAt))) {
+        throw new Error("issuedAt must be an ISO-8601 timestamp");
+    }
+}
+/**
+ * Creates a correlation artifact only. It neither calls Paybox nor establishes
+ * payment, settlement, claim eligibility, or any authority beyond the link.
+ */
+export function createPayboxWorkLink(input) {
+    assertValidInput(input);
+    const identity = {
+        scheme: EXTERNAL_EVIDENCE_LINK_SCHEME,
+        relation: "supports",
+        source: {
+            kind: "receipt",
+            scheme: "aipou-receipt-v1",
+            id: input.workReceiptId,
+            digest: `sha256:${input.workReceiptId.slice(2)}`
+        },
+        target: {
+            kind: "payment-operation",
+            scheme: PAYBOX_OPERATION_SCHEME,
+            id: input.payboxOperationId,
+            digest: input.payboxOperationDigest
+        },
+        privacy: "digest_only"
+    };
+    const payload = {
+        ...identity,
+        issuedAt: input.issuedAt
+    };
+    return {
+        ...payload,
+        linkId: `sha256:${sha256Hex(canonicalJson(identity)).slice(2)}`,
+        linkDigest: `sha256:${sha256Hex(canonicalJson(payload)).slice(2)}`
+    };
+}

package/dist/paybox-link.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/paybox-link.test.js

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createPayboxWorkLink } from "./paybox-link.js";
+const input = {
+    workReceiptId: `0x${"ab".repeat(32)}`,
+    payboxOperationId: "pbx_op_synthetic_delivery_001",
+    payboxOperationDigest: `sha256:${"cd".repeat(32)}`,
+    issuedAt: "2026-07-30T13:30:00.000Z"
+};
+test("creates a digest-only Paybox to AIPOU work link without payment authority", () => {
+    const link = createPayboxWorkLink(input);
+    assert.equal(link.scheme, "external-evidence-link-v1");
+    assert.equal(link.relation, "supports");
+    assert.equal(link.source.id, input.workReceiptId);
+    assert.equal(link.target.scheme, "paybox-operation-v1");
+    assert.equal(link.target.id, input.payboxOperationId);
+    assert.equal(link.target.digest, input.payboxOperationDigest);
+    assert.match(link.linkId, /^sha256:[0-9a-f]{64}$/);
+    assert.match(link.linkDigest, /^sha256:[0-9a-f]{64}$/);
+    assert.equal("wallet" in link, false);
+    assert.equal("paymentStatus" in link, false);
+    assert.equal("claimStatus" in link, false);
+    assert.equal("reward" in link, false);
+});
+test("is deterministic and changes when the external artifact changes", () => {
+    assert.equal(createPayboxWorkLink(input).linkDigest, createPayboxWorkLink(input).linkDigest);
+    assert.equal(createPayboxWorkLink(input).linkId, createPayboxWorkLink({ ...input, issuedAt: "2026-07-30T14:30:00.000Z" }).linkId);
+    assert.notEqual(createPayboxWorkLink(input).linkDigest, createPayboxWorkLink({ ...input, issuedAt: "2026-07-30T14:30:00.000Z" }).linkDigest);
+    assert.notEqual(createPayboxWorkLink(input).linkId, createPayboxWorkLink({ ...input, payboxOperationDigest: `sha256:${"ef".repeat(32)}` }).linkId);
+});
+test("rejects malformed receipt, digest, opaque reference, and timestamp inputs", () => {
+    assert.throws(() => createPayboxWorkLink({ ...input, workReceiptId: "0xabc" }));
+    assert.throws(() => createPayboxWorkLink({ ...input, payboxOperationDigest: "sha256:ABC" }));
+    assert.throws(() => createPayboxWorkLink({ ...input, payboxOperationId: "" }));
+    assert.throws(() => createPayboxWorkLink({ ...input, issuedAt: "not-a-date" }));
+});

package/dist/private-json.d.ts

@@ -0,0 +1,2 @@
+export declare function writePrivateJson(file: string, value: unknown): Promise<void>;
+export declare function readOptionalJson<T>(file: string): Promise<T | null>;

package/dist/private-json.js

@@ -0,0 +1,39 @@
+import { mkdir, open, rename, readFile } from "node:fs/promises";
+import path from "node:path";
+import { restrictToCurrentUser } from "./secure-file.js";
+export async function writePrivateJson(file, value) {
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temp = `${file}.${process.pid}.tmp`;
+    const handle = await open(temp, "w", 0o600);
+    try {
+        if (process.platform !== "win32")
+            await handle.chmod(0o600);
+        await handle.writeFile(JSON.stringify(value, null, 2) + "\n");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    if (!(await restrictToCurrentUser(temp)))
+        throw new Error("Could not restrict private state file access; update was not committed");
+    await rename(temp, file);
+    if (process.platform !== "win32") {
+        const directory = await open(path.dirname(file), "r");
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+}
+export async function readOptionalJson(file) {
+    try {
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}

package/dist/protocol.test.js

@@ -8,6 +8,7 @@ import { Wallet, keccak256, toUtf8Bytes } from "ethers";
 import { canonicalJson } from "./canonical.js";
 import { verifyCollectorPayload } from "./collector.js";
 import { verifyTaskAuthorization } from "./identity.js";
+import { isTaskSessionExpired, taskSessionExpiry } from "./identity.js";
 import { filterEligibleReceipts } from "./policy.js";
 import { providerAssertion } from "./providers.js";
 import { beginTask, completeTask } from "./receipts.js";
@@ -63,6 +64,28 @@ test("creates verifiable receipts and rejects nonce/evidence replay", async () =
         outputHash
     }), /Duplicate task\/output evidence/);
 });
+test("expires abandoned task sessions instead of treating stale authority as completable", async () => {
+    const dataDir = await mkdtemp(path.join(tmpdir(), "aipou-expiry-"));
+    process.env.AIPOU_DATA_DIR = dataDir;
+    process.env.AIPOU_AGENT_PRIVATE_KEY = Wallet.createRandom().privateKey;
+    process.env.AIPOU_TASK_SESSION_TTL_SECONDS = "60";
+    try {
+        const session = await beginTask({
+            provider: "local",
+            model: "expiry-test",
+            taskHash: keccak256(toUtf8Bytes("expired task")),
+            client: "test-client",
+            chainId: 8453,
+            verifyingContract: Wallet.createRandom().address
+        });
+        assert.equal(taskSessionExpiry(session), session.issuedAt + 60);
+        assert.equal(isTaskSessionExpired(session, session.issuedAt + 59), false);
+        assert.equal(isTaskSessionExpired(session, session.issuedAt + 60), true);
+    }
+    finally {
+        delete process.env.AIPOU_TASK_SESSION_TTL_SECONDS;
+    }
+});
 test("derives provider_signed only from a configured valid signature", async () => {
     const dataDir = await mkdtemp(path.join(tmpdir(), "aipou-provider-"));
     process.env.AIPOU_DATA_DIR = dataDir;

package/dist/receipt-metadata.d.ts

@@ -0,0 +1,13 @@
+export declare const AIPOU_RECEIPT_META_KEY = "io.github.0xddneto/aipou-receipt";
+export declare const AIPOU_SPAN_ATTRIBUTE_NAMES: {
+    readonly workReceiptId: "aipou.work_receipt_id";
+    readonly evidenceClass: "aipou.evidence_class";
+    readonly scheme: "aipou.scheme";
+};
+export declare function buildReceiptSpanAttributes(receipt: {
+    receiptId: string;
+}): Record<string, string>;
+export declare function buildReceiptResultMeta(receipt: {
+    receiptId: string;
+    collectorPublicKey: string;
+}): Record<string, unknown>;

package/dist/receipt-metadata.js

@@ -0,0 +1,28 @@
+import { collectorFingerprint } from "./collector.js";
+export const AIPOU_RECEIPT_META_KEY = "io.github.0xddneto/aipou-receipt";
+export const AIPOU_SPAN_ATTRIBUTE_NAMES = {
+    workReceiptId: "aipou.work_receipt_id",
+    evidenceClass: "aipou.evidence_class",
+    scheme: "aipou.scheme"
+};
+export function buildReceiptSpanAttributes(receipt) {
+    return {
+        [AIPOU_SPAN_ATTRIBUTE_NAMES.workReceiptId]: receipt.receiptId,
+        [AIPOU_SPAN_ATTRIBUTE_NAMES.evidenceClass]: "issuer_asserted",
+        [AIPOU_SPAN_ATTRIBUTE_NAMES.scheme]: "aipou-receipt-v1"
+    };
+}
+export function buildReceiptResultMeta(receipt) {
+    const digest = receipt.receiptId.replace(/^0x/, "").toLowerCase();
+    return {
+        [AIPOU_RECEIPT_META_KEY]: {
+            id: receipt.receiptId,
+            uri: `aipou://receipts/${receipt.receiptId}`,
+            issuer: collectorFingerprint(receipt.collectorPublicKey),
+            digest: `sha256:${digest}`,
+            evidenceClass: "issuer_asserted",
+            scheme: "aipou-receipt-v1",
+            status: "local"
+        }
+    };
+}

package/dist/receipt-metadata.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/receipt-metadata.test.js

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import { generateKeyPairSync } from "node:crypto";
+import test from "node:test";
+import { AIPOU_RECEIPT_META_KEY, AIPOU_SPAN_ATTRIBUTE_NAMES, buildReceiptResultMeta, buildReceiptSpanAttributes } from "./receipt-metadata.js";
+test("receipt result metadata is compact, namespaced, and contains no claim authority", () => {
+    const pair = generateKeyPairSync("ed25519");
+    const collectorPublicKey = pair.publicKey.export({ format: "pem", type: "spki" }).toString();
+    const receiptId = `0x${"ab".repeat(32)}`;
+    const metadata = buildReceiptResultMeta({ receiptId, collectorPublicKey });
+    const projection = metadata[AIPOU_RECEIPT_META_KEY];
+    assert.deepEqual(Object.keys(metadata), [AIPOU_RECEIPT_META_KEY]);
+    assert.equal(projection.id, receiptId);
+    assert.equal(projection.uri, `aipou://receipts/${receiptId}`);
+    assert.match(String(projection.issuer), /^sha256:[0-9a-f]{64}$/);
+    assert.equal(projection.digest, `sha256:${"ab".repeat(32)}`);
+    assert.equal(projection.evidenceClass, "issuer_asserted");
+    assert.equal(projection.scheme, "aipou-receipt-v1");
+    assert.equal(projection.status, "local");
+    assert.equal("wallet" in projection, false);
+    assert.equal("reward" in projection, false);
+    assert.equal("claimStatus" in projection, false);
+});
+test("span projection matches the OpenLLMetry correlation boundary", () => {
+    const receiptId = `0x${"cd".repeat(32)}`;
+    const attributes = buildReceiptSpanAttributes({ receiptId });
+    assert.deepEqual(attributes, {
+        "aipou.work_receipt_id": receiptId,
+        "aipou.evidence_class": "issuer_asserted",
+        "aipou.scheme": "aipou-receipt-v1"
+    });
+    assert.deepEqual(AIPOU_SPAN_ATTRIBUTE_NAMES, {
+        workReceiptId: "aipou.work_receipt_id",
+        evidenceClass: "aipou.evidence_class",
+        scheme: "aipou.scheme"
+    });
+    for (const forbidden of ["wallet", "reward", "prompt", "output", "claimAuthority", "aipou.validation_status"]) {
+        assert.equal(forbidden in attributes, false);
+    }
+});

package/dist/receipt-verifier.d.ts

@@ -0,0 +1,13 @@
+import { type EvidenceReport } from "./evidence.js";
+export interface ReceiptVerificationResult {
+    valid: boolean;
+    errors: string[];
+    workReceiptId: string | null;
+    claimedWorkReceiptId: string | null;
+    evidence: EvidenceReport;
+}
+/**
+ * Verifies only the self-contained receipt facts. It does not check a
+ * collector allowlist, an on-chain claim, delivery, or business acceptance.
+ */
+export declare function verifyAipouReceipt(candidate: unknown): ReceiptVerificationResult;