@peac/kernel 0.11.0 → 0.11.2

package/README.md

@@ -12,6 +12,15 @@ pnpm add @peac/kernel
 
 See [peacprotocol.org](https://www.peacprotocol.org) for full documentation.
 
+## For Agent Developers
+
+If you are building an AI agent or MCP server that needs evidence receipts:
+
+- Start with [`@peac/mcp-server`](https://www.npmjs.com/package/@peac/mcp-server) for a ready-to-use MCP tool server
+- See the [llms.txt](https://github.com/peacprotocol/peac/blob/main/llms.txt) for a concise overview of all packages
+- Use `@peac/protocol` for programmatic receipt issuance and verification
+- Use `@peac/kernel` types (`PeacEvidenceCarrier`, `ErrorDefinition`) for type-safe integration
+
 ## License
 
 Apache-2.0

package/dist/__tests__/carrier.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=carrier.test.d.ts.map

package/dist/__tests__/carrier.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carrier.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/carrier.test.ts"],"names":[],"mappings":""}

package/dist/carrier.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Evidence Carrier Contract types (DD-124)
+ *
+ * Pure TypeScript types for the universal evidence carry interface.
+ * Zero runtime dependencies: this module exports only types.
+ *
+ * The Evidence Carrier Contract defines how any protocol (MCP, A2A, ACP,
+ * UCP, x402, HTTP) carries PEAC receipts without kernel changes.
+ */
+/**
+ * Canonical HTTP header name for PEAC receipts (DD-127).
+ *
+ * The wire token is exactly "PEAC-Receipt" (mixed-case, hyphenated).
+ * This is the only valid spelling in conformance fixtures and attach() output.
+ * HTTP header lookups SHOULD be case-insensitive per RFC 9110, but conformance
+ * fixtures and attach() output MUST use this exact spelling.
+ */
+export declare const PEAC_RECEIPT_HEADER: "PEAC-Receipt";
+/**
+ * Canonical HTTP header name for receipt URL locator hint (DD-135).
+ *
+ * HTTPS-only, max 2048 chars, no credentials.
+ * MUST NOT trigger implicit fetch (DD-55).
+ */
+export declare const PEAC_RECEIPT_URL_HEADER: "PEAC-Receipt-URL";
+/** Content-addressed receipt reference: SHA-256 of the compact JWS bytes */
+export type ReceiptRef = `sha256:${string}`;
+/** Carrier format: embed (inline) or reference (URL/pointer) */
+export type CarrierFormat = 'embed' | 'reference';
+/**
+ * Universal evidence carrier.
+ *
+ * Every protocol-specific adapter produces and consumes this shape.
+ * Fields marked optional are SHOULD or MAY per the carrier contract spec.
+ */
+export interface PeacEvidenceCarrier {
+    /** Content-addressed receipt reference (MUST): sha256:<hex64> */
+    receipt_ref: ReceiptRef;
+    /** Compact JWS of the signed receipt (SHOULD for embed format) */
+    receipt_jws?: string;
+    /**
+     * Locator hint for detached receipt resolution (DD-135).
+     * HTTPS-only, max 2048 chars, no credentials.
+     * MUST NOT trigger implicit fetch (DD-55).
+     * If a caller fetches, it MUST verify sha256(receipt_jws) == receipt_ref.
+     */
+    receipt_url?: string;
+    /** Policy binding hash for verification (MAY) */
+    policy_binding?: string;
+    /** Actor binding identifier (MAY) */
+    actor_binding?: string;
+    /** Request nonce for replay protection (MAY) */
+    request_nonce?: string;
+    /** Reference to a verification report (MAY) */
+    verification_report_ref?: string;
+    /** Reference to a use policy (MAY) */
+    use_policy_ref?: string;
+    /** Reference to a representation (MAY) */
+    representation_ref?: string;
+    /** Reference to an attestation (MAY) */
+    attestation_ref?: string;
+}
+/**
+ * Transport-level metadata describing how a carrier is placed.
+ *
+ * Used by validateConstraints() to enforce transport-specific size limits
+ * and format requirements (DD-127).
+ */
+export interface CarrierMeta {
+    /** Transport identifier (e.g. 'mcp', 'a2a', 'acp', 'ucp', 'x402', 'http') */
+    transport: string;
+    /** Carrier format: embed or reference */
+    format: CarrierFormat;
+    /** Maximum carrier size in bytes for this transport */
+    max_size: number;
+    /** Fields that have been redacted (MAY) */
+    redaction?: string[];
+}
+/** Result of carrier constraint validation */
+export interface CarrierValidationResult {
+    valid: boolean;
+    violations: string[];
+}
+/**
+ * Protocol-specific carrier adapter (DD-124).
+ *
+ * Each protocol mapping implements this interface to attach/extract
+ * PEAC evidence carriers in the protocol's native format.
+ *
+ * @typeParam TInput - The protocol-specific input type (e.g. A2A TaskStatus)
+ * @typeParam TOutput - The protocol-specific output type
+ */
+export interface CarrierAdapter<TInput, TOutput> {
+    /**
+     * Extract PEAC evidence carriers from a protocol message.
+     * Returns null if no carrier is present.
+     */
+    extract(input: TInput): {
+        receipts: PeacEvidenceCarrier[];
+        meta: CarrierMeta;
+    } | null;
+    /**
+     * Attach PEAC evidence carriers to a protocol message.
+     * Returns the modified output with carriers placed per protocol conventions.
+     */
+    attach(output: TOutput, carriers: PeacEvidenceCarrier[], meta?: CarrierMeta): TOutput;
+    /**
+     * Validate a carrier against transport-specific constraints (DD-127, DD-129).
+     * Takes CarrierMeta for transport-aware size and format validation.
+     */
+    validateConstraints(carrier: PeacEvidenceCarrier, meta: CarrierMeta): CarrierValidationResult;
+}
+//# sourceMappingURL=carrier.d.ts.map

package/dist/carrier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carrier.d.ts","sourceRoot":"","sources":["../src/carrier.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAG,cAAuB,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAG,kBAA2B,CAAC;AAMnE,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,UAAU,MAAM,EAAE,CAAC;AAE5C,gEAAgE;AAChE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,WAAW,CAAC;AAMlD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,WAAW,EAAE,UAAU,CAAC;IACxB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wCAAwC;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,MAAM,EAAE,aAAa,CAAC;IACtB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAMD,8CAA8C;AAC9C,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,EAAE,OAAO;IAC7C;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,mBAAmB,EAAE,CAAC;QAAC,IAAI,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAAC;IAEtF;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IAEtF;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,WAAW,GAAG,uBAAuB,CAAC;CAC/F"}

package/dist/error-categories.generated.d.ts

@@ -3,7 +3,7 @@
  *
  * AUTO-GENERATED from specs/kernel/errors.json
  * DO NOT EDIT MANUALLY - run: npx tsx scripts/codegen-errors.ts
- * Spec version: 0.11.0
+ * Spec version: 0.11.2
  */
 /**
  * Canonical error categories derived from specs/kernel/errors.json.