@agenticprimitives/agent-profile 1.0.0-alpha.22 → 1.0.0-alpha.23

package/README.md

@@ -4,14 +4,26 @@
 
 Part of [agenticprimitives](../../README.md) — the trust substrate for the agent economy: one canonical Smart Agent identity with custody, delegation, naming, credentials, and audit evidence designed as one system.
 
-Where [`agent-naming`](../agent-naming) maps names → addresses, this package maps addresses → typed profiles and optional endpoint-control proofs: the `AgentCard` schema, deterministic content hashing for on-chain anchoring, and CAIP-10 `nativeId` helpers for cross-registry back-links.
+Where [`agent-naming`](../agent-naming) maps names → addresses, this package maps addresses → typed profiles and optional endpoint-control proofs: the `CanonicalAgentProfileV1` schema, deterministic content hashing for on-chain anchoring, and CAIP-10 `nativeId` helpers for cross-registry back-links. Since spec 347 it also owns the **A2A 1.0 Agent Card model** (`./a2a`) — a different object, see below.
 
 > **Layer:** Discover — a profile **facet** (not login — that is `connect-auth`; not canonical identity — that is `agent-account`).
-> **Canonical key:** the Smart Agent address the AgentCard describes.
+> **Canonical key:** the Smart Agent address the profile describes.
+
+## Profile ≠ A2A card
+
+| | `CanonicalAgentProfileV1` (root) | `A2AAgentCardV1` (`./a2a`) |
+| --- | --- | --- |
+| Answers | what is this agent, who operates it, what does it claim | what does THIS A2A server do and how do I talk to it |
+| Shape | AP-native, discriminated on `type` | A2A 1.0 Agent Card (`supportedInterfaces`, `capabilities`, `skills`, `securitySchemes`, `signatures`) |
+| Canonical bytes | sorted-key canonical JSON → keccak (`profileContentHash`, on-chain `metadata-hash`) | RFC 8785 JCS minus `signatures` → sha256 (`cardContentDigest`) |
+| Proof | `SignedCanonicalProfileBundleV1` (ERC-1271 by the SA) | ES256 JWS (any A2A client verifies) **plus** `SmartAgentCardBindingV1` (EIP-712, ERC-1271 — AP verifiers) |
+
+`AgentCard`, `SignedAgentCardBundleV1`, `hashAgentCard`, `buildSignedAgentCardBundle`, `verifySignedAgentCardBundle` still compile as **deprecated aliases** for one release ([spec 347 §0.3](../../specs/347-a2a-agent-card-and-projection-studio.md), [ADR-0062](../../docs/architecture/decisions/0062-agent-card-projection-publication-binding.md)).
 
 ## Use this when
 
-- You author or validate an `AgentCard` (person, org, service, treasury, MCP server, multisig).
+- You author or validate a `CanonicalAgentProfileV1` (person, org, service, treasury, MCP server, multisig).
+- You inherit, curate, validate, sign, release or import an **A2A Agent Card** (`./a2a`) with field-level provenance and a Smart Agent binding.
 - You need a deterministic `profileContentHash` for the on-chain `metadata-hash` anchor — so a tampered profile is detectable by anyone holding the hash.
 - You need CAIP-10 `nativeId` encode/decode (strict encode, permissive decode) as a portable back-link to the canonical SA ([ADR-0008](../../docs/architecture/decisions/0008-caip10-nativeid-record-predicate.md)).
 - You need endpoint-verification methods (DNS TXT, signed URL, HTTP challenge, verifiable presentation) — Phase 2+.
@@ -40,12 +52,12 @@ import {
   canonicalProfileJson,
   profileContentHash,
   buildCaip10Address,
-  type AgentCard,
+  type CanonicalAgentProfileV1,
 } from '@agenticprimitives/agent-profile';
 
 const canonicalAddr = '0x0000000000000000000000000000000000000003' as const;
 
-const profile: AgentCard = {
+const profile: CanonicalAgentProfileV1 = {
   type: 'person',
   displayName: 'Alice',
 };
@@ -59,6 +71,37 @@ const nativeId = buildCaip10Address({
 // Anchor hash + nativeId on chain via agent-naming records or profile resolver.
 ```
 
+### A2A card in 60 seconds
+
+```ts
+import {
+  inheritCardBase, draftFromBase, applyOverride, createRelease, transition, attachSignature,
+  generateA2ACardSigningKey, signA2ACard, verifyA2ACardSignatures, importA2ACard,
+} from '@agenticprimitives/agent-profile/a2a';
+
+const now = new Date().toISOString();
+const base = inheritCardBase({
+  profile, names: { primary: 'alice.svc.agent' },
+  surfaceCards: toCardProjectionSet(catalog),        // surface-catalog — the only source of inherited skills
+  runtimeCapabilities: { streaming: false, pushNotifications: false },
+  deployment: { host: 'https://alice.agent.example', a2aUrl: 'https://alice.agent.example/api/a2a' },
+  agentVersion: '2.0.0', now,
+});
+let draft = draftFromBase(base, { cardResourceId: 'card_01', now });
+draft = applyOverride(draft, '/description', 'Curated copy.', { now });   // recorded, reviewable
+let release = createRelease(draft, { releaseNumber: 1, agentVersion: '2.0.0', now,
+  validation: { environment: 'production', catalogSkills: base.card.skills, runtimeCapabilities: {} } });
+release = transition(release, 'approvalPending', { now });
+release = transition(release, 'approved', { now, approval });              // ApprovalRefV1 names the exact digest
+const key = await generateA2ACardSigningKey();                             // ES256, kid = RFC 7638 thumbprint
+const signed = await signA2ACard(release.unsignedCard, { privateKey: key.privateKey, kid: key.kid });
+release = attachSignature(release, { signedCard: signed.card, signature: signed.signature });
+// A non-AP client:
+await verifyA2ACardSignatures(signed.card, { keys: (kid) => (kid === key.kid ? key.publicJwk : undefined) });
+// Importing someone else's card: bytes kept, signatures verified BEFORE normalizing, unknown fields flagged.
+const { imported, diagnostics } = await importA2ACard(bytes, { verifyKeys });
+```
+
 ## How it's different
 
 The reference points are registry and agent-card ecosystems, but this package defines the AP-native primitive:
@@ -70,7 +113,9 @@ The reference points are registry and agent-card ecosystems, but this package de
 
 ## Main concepts
 
-- **AgentCard**: AP-native typed JSON discriminated by `type`, with type-specific sub-objects (`AiAgentProfile`, `McpServerProfile`, `MultisigProfile`, `ServiceProfile`).
+- **CanonicalAgentProfileV1**: AP-native typed JSON discriminated by `type`, with type-specific sub-objects (`AiAgentProfile`, `McpServerProfile`, `MultisigProfile`, `ServiceProfile`).
+- **A2A Agent Card** (`./a2a`): `A2AAgentCardV1` + draft / release / `FieldBindingV1` provenance (`inherit | override | computed | manual`), pure `validateA2ACard` (stable `DIAGNOSTIC_CODES`, incl. `CATALOG_DIVERGENCE` and `CAPABILITY_UNVERIFIED`), lifecycle `draft → validated → approvalPending → approved → signed → published → superseded | deprecated | revoked`.
+- **Distribution** (`AgentDistributionV1`, spec 347 §8.5): how to OBTAIN AND RUN the agent's software — `acp?` (ACP conformance, the eligibility flag for a hosted ACP `registry.json`), `version?` (implementation semver), `npx` / `uvx` `{ package, args?, env? }`, `binary[<ACP_PLATFORMS>] { archive (https, no .dmg/.pkg/.deb/.rpm), cmd, sha256?, args?, env? }` — field names verbatim from the ACP registry `agent.schema.json`. Stored as the SA-keyed `DISTRIBUTION` (`atl:distribution`) string property in JCS form: `validateDistribution` (pure, `string[]` issues) · `encodeDistribution` (throws on invalid) · `decodeDistribution` (fail-closed → `null`) · `buildSetDistributionCall`. Public on-chain data by construction — never put a secret in `env`.
 - **Profile facet**: `metadata-uri` + `metadata-hash` pointing at the canonical SA.
 - **CAIP-10 `nativeId`**: the cross-registry back-link; must match the SA on EVM chains.
 - **Verification**: proves an MCP/A2A URL is controlled by the SA (distinct from naming).
@@ -81,10 +126,13 @@ See [`docs/concepts.md`](docs/concepts.md).
 
 - `@agenticprimitives/agent-profile/caip10` — CAIP-10 helpers only (no client baggage).
 - `@agenticprimitives/agent-profile/profile` — canonical JSON + content hash.
+- `@agenticprimitives/agent-profile/card` — signed canonical-profile bundle.
+- `@agenticprimitives/agent-profile/a2a` — A2A 1.0 Agent Card model: JCS canonical bytes, ES256 JWS, EIP-712 Smart Agent binding, field provenance, validation, import, release lifecycle.
 
 ## Security invariants
 
 - Profile content-hash is deterministic (canonical JSON).
+- Card canonical bytes are RFC 8785 JCS (never the sorted-key `canonicalizeJson`); signature and binding verification are fail-closed; import verifies before it normalizes; validation refuses secret material, private URLs and vault references in a card.
 - No raw passkey material in profiles — only `credentialIdDigest`.
 - Verification methods are explicit, not auto-selected.
 - No UAID generation ([ADR-0008](../../docs/architecture/decisions/0008-caip10-nativeid-record-predicate.md)).

package/dist/a2a/binding.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `SmartAgentCardBindingV1` — the Smart Agent's EIP-712 statement that a specific released card (by
+ * resource, release, URI and BOTH digests) is its card, signed by the SA and validated through ERC-1271
+ * (spec 347 §4.2; ADR-0062 §2).
+ *
+ * Separate from the JWS on purpose: a non-AP A2A client verifies the JWS and never needs this; an AP
+ * verifier checks JWS → key thumbprint authorized → binding. The binding carries NO authority to act — it
+ * is descriptive evidence that the SA stands behind these exact bytes.
+ *
+ * Domain: `{ name:'AgenticPrimitivesAgentCard', version:'1', chainId, verifyingContract: <SA> }`.
+ * The ERC-1271 read is INJECTED (`Erc1271Verifier`, same port as `card.ts`) so this stays network-free.
+ */
+import { type Address, type Hex } from 'viem';
+import type { Erc1271Verifier } from '../card.js';
+import type { Sha256 } from '../types.js';
+import type { SignedSmartAgentCardBindingV1, SmartAgentCardBindingV1 } from './types.js';
+export declare const SMART_AGENT_CARD_BINDING_DOMAIN_NAME = "AgenticPrimitivesAgentCard";
+export declare const SMART_AGENT_CARD_BINDING_DOMAIN_VERSION = "1";
+export declare const SMART_AGENT_CARD_BINDING_TYPES: {
+    readonly SmartAgentCardBinding: readonly [{
+        readonly name: "canonicalAgentId";
+        readonly type: "string";
+    }, {
+        readonly name: "cardResourceId";
+        readonly type: "string";
+    }, {
+        readonly name: "cardReleaseId";
+        readonly type: "string";
+    }, {
+        readonly name: "cardUri";
+        readonly type: "string";
+    }, {
+        readonly name: "unsignedCardDigest";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "signedCardDigest";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "signerKeyThumbprint";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "validFrom";
+        readonly type: "uint64";
+    }, {
+        readonly name: "validUntil";
+        readonly type: "uint64";
+    }];
+};
+/** The EIP-712 type string (for on-chain `TYPEHASH` parity checks). */
+export declare const SMART_AGENT_CARD_BINDING_TYPE_STRING = "SmartAgentCardBinding(string canonicalAgentId,string cardResourceId,string cardReleaseId,string cardUri,bytes32 unsignedCardDigest,bytes32 signedCardDigest,bytes32 signerKeyThumbprint,uint64 validFrom,uint64 validUntil)";
+export declare function smartAgentCardBindingDomain(chainId: number, smartAgent: Address): {
+    readonly name: "AgenticPrimitivesAgentCard";
+    readonly version: "1";
+    readonly chainId: number;
+    readonly verifyingContract: `0x${string}`;
+};
+export declare function sha256ToBytes32(digest: Sha256 | string): Hex;
+export declare function bytes32ToSha256(h: Hex): Sha256;
+/** RFC 7638 thumbprint (base64url of a sha256) ↔ bytes32. */
+export declare function thumbprintToBytes32(thumbprint: string): Hex;
+export declare function bytes32ToThumbprint(h: Hex): string;
+/** The EIP-712 message as signed: digests + thumbprint as bytes32, times as uint64. */
+export declare function smartAgentCardBindingMessage(b: SmartAgentCardBindingV1): {
+    canonicalAgentId: string;
+    cardResourceId: string;
+    cardReleaseId: string;
+    cardUri: string;
+    unsignedCardDigest: `0x${string}`;
+    signedCardDigest: `0x${string}`;
+    signerKeyThumbprint: `0x${string}`;
+    validFrom: bigint;
+    validUntil: bigint;
+};
+/** The 32-byte EIP-712 digest the SA signs and ERC-1271 validates. */
+export declare function smartAgentCardBindingDigest(binding: SmartAgentCardBindingV1, chainId: number, smartAgent: Address): Hex;
+export type VerifySmartAgentCardBindingResult = {
+    ok: true;
+    smartAgent: Address;
+    digest: Hex;
+} | {
+    ok: false;
+    reason: 'bad_shape' | 'agent_mismatch' | 'digest_mismatch' | 'not_yet_valid' | 'expired' | 'signature_invalid';
+};
+export interface VerifySmartAgentCardBindingOptions {
+    erc1271Verifier: Erc1271Verifier;
+    /** Unix seconds; defaults to now. */
+    now?: number;
+    /** When given, the binding's digests MUST equal these (the release actually being verified). */
+    expect?: {
+        unsignedCardDigest?: Sha256;
+        signedCardDigest?: Sha256;
+    };
+}
+/**
+ * Fail-closed verification: shape → `canonicalAgentId` names this SA on this chain → expected digests →
+ * validity window → ERC-1271 over the EIP-712 digest. Any anomaly ⇒ `ok:false`.
+ */
+export declare function verifySmartAgentCardBinding(signed: SignedSmartAgentCardBindingV1, opts: VerifySmartAgentCardBindingOptions): Promise<VerifySmartAgentCardBindingResult>;
+//# sourceMappingURL=binding.d.ts.map

package/dist/a2a/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/a2a/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAiB,KAAK,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,6BAA6B,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEzF,eAAO,MAAM,oCAAoC,+BAA+B,CAAC;AACjF,eAAO,MAAM,uCAAuC,MAAM,CAAC;AAE3D,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAYjC,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,oCAAoC,gOAC8K,CAAC;AAEhO,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO;;;;;EAO/E;AAMD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,GAAG,CAI5D;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,CAG9C;AAED,6DAA6D;AAC7D,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAI3D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,CAKlD;AAID,uFAAuF;AACvF,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,uBAAuB;;;;;;;;;;EAetE;AAED,sEAAsE;AACtE,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,GAAG,CAOvH;AAID,MAAM,MAAM,iCAAiC,GACzC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,GAAG,CAAA;CAAE,GAC9C;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EACF,WAAW,GACX,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,GACf,SAAS,GACT,mBAAmB,CAAC;CACzB,CAAC;AAEN,MAAM,WAAW,kCAAkC;IACjD,eAAe,EAAE,eAAe,CAAC;IACjC,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,MAAM,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE;AAID;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,kCAAkC,GACvC,OAAO,CAAC,iCAAiC,CAAC,CAuC5C"}

package/dist/a2a/binding.js

@@ -0,0 +1,142 @@
+/**
+ * `SmartAgentCardBindingV1` — the Smart Agent's EIP-712 statement that a specific released card (by
+ * resource, release, URI and BOTH digests) is its card, signed by the SA and validated through ERC-1271
+ * (spec 347 §4.2; ADR-0062 §2).
+ *
+ * Separate from the JWS on purpose: a non-AP A2A client verifies the JWS and never needs this; an AP
+ * verifier checks JWS → key thumbprint authorized → binding. The binding carries NO authority to act — it
+ * is descriptive evidence that the SA stands behind these exact bytes.
+ *
+ * Domain: `{ name:'AgenticPrimitivesAgentCard', version:'1', chainId, verifyingContract: <SA> }`.
+ * The ERC-1271 read is INJECTED (`Erc1271Verifier`, same port as `card.ts`) so this stays network-free.
+ */
+import { hashTypedData } from 'viem';
+import { base64UrlDecode, base64UrlEncode } from './jws.js';
+export const SMART_AGENT_CARD_BINDING_DOMAIN_NAME = 'AgenticPrimitivesAgentCard';
+export const SMART_AGENT_CARD_BINDING_DOMAIN_VERSION = '1';
+export const SMART_AGENT_CARD_BINDING_TYPES = {
+    SmartAgentCardBinding: [
+        { name: 'canonicalAgentId', type: 'string' },
+        { name: 'cardResourceId', type: 'string' },
+        { name: 'cardReleaseId', type: 'string' },
+        { name: 'cardUri', type: 'string' },
+        { name: 'unsignedCardDigest', type: 'bytes32' },
+        { name: 'signedCardDigest', type: 'bytes32' },
+        { name: 'signerKeyThumbprint', type: 'bytes32' },
+        { name: 'validFrom', type: 'uint64' },
+        { name: 'validUntil', type: 'uint64' },
+    ],
+};
+/** The EIP-712 type string (for on-chain `TYPEHASH` parity checks). */
+export const SMART_AGENT_CARD_BINDING_TYPE_STRING = 'SmartAgentCardBinding(string canonicalAgentId,string cardResourceId,string cardReleaseId,string cardUri,bytes32 unsignedCardDigest,bytes32 signedCardDigest,bytes32 signerKeyThumbprint,uint64 validFrom,uint64 validUntil)';
+export function smartAgentCardBindingDomain(chainId, smartAgent) {
+    return {
+        name: SMART_AGENT_CARD_BINDING_DOMAIN_NAME,
+        version: SMART_AGENT_CARD_BINDING_DOMAIN_VERSION,
+        chainId,
+        verifyingContract: smartAgent,
+    };
+}
+// ─── digest ↔ bytes32 ────────────────────────────────────────────────────────────────────────────────
+const SHA256_RE = /^sha256:([0-9a-f]{64})$/;
+export function sha256ToBytes32(digest) {
+    const m = SHA256_RE.exec(digest.toLowerCase());
+    if (!m)
+        throw new Error(`not a sha256 digest: "${digest}"`);
+    return `0x${m[1]}`;
+}
+export function bytes32ToSha256(h) {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(h))
+        throw new Error(`not a bytes32: "${h}"`);
+    return `sha256:${h.slice(2).toLowerCase()}`;
+}
+/** RFC 7638 thumbprint (base64url of a sha256) ↔ bytes32. */
+export function thumbprintToBytes32(thumbprint) {
+    const bytes = base64UrlDecode(thumbprint);
+    if (bytes.length !== 32)
+        throw new Error('signerKeyThumbprint must be a base64url sha256 (32 bytes)');
+    return `0x${Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')}`;
+}
+export function bytes32ToThumbprint(h) {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(h))
+        throw new Error(`not a bytes32: "${h}"`);
+    const bytes = new Uint8Array(32);
+    for (let i = 0; i < 32; i++)
+        bytes[i] = parseInt(h.slice(2 + i * 2, 4 + i * 2), 16);
+    return base64UrlEncode(bytes);
+}
+// ─── digest ──────────────────────────────────────────────────────────────────────────────────────────
+/** The EIP-712 message as signed: digests + thumbprint as bytes32, times as uint64. */
+export function smartAgentCardBindingMessage(b) {
+    if (!Number.isInteger(b.validFrom) || b.validFrom < 0 || !Number.isInteger(b.validUntil) || b.validUntil < 0) {
+        throw new Error('validFrom/validUntil must be non-negative integer unix seconds');
+    }
+    return {
+        canonicalAgentId: b.canonicalAgentId,
+        cardResourceId: b.cardResourceId,
+        cardReleaseId: b.cardReleaseId,
+        cardUri: b.cardUri,
+        unsignedCardDigest: sha256ToBytes32(b.unsignedCardDigest),
+        signedCardDigest: sha256ToBytes32(b.signedCardDigest),
+        signerKeyThumbprint: thumbprintToBytes32(b.signerKeyThumbprint),
+        validFrom: BigInt(b.validFrom),
+        validUntil: BigInt(b.validUntil),
+    };
+}
+/** The 32-byte EIP-712 digest the SA signs and ERC-1271 validates. */
+export function smartAgentCardBindingDigest(binding, chainId, smartAgent) {
+    return hashTypedData({
+        domain: smartAgentCardBindingDomain(chainId, smartAgent),
+        types: SMART_AGENT_CARD_BINDING_TYPES,
+        primaryType: 'SmartAgentCardBinding',
+        message: smartAgentCardBindingMessage(binding),
+    });
+}
+const CAIP10_EVM = /^eip155:(\d+):(0x[0-9a-fA-F]{40})$/;
+/**
+ * Fail-closed verification: shape → `canonicalAgentId` names this SA on this chain → expected digests →
+ * validity window → ERC-1271 over the EIP-712 digest. Any anomaly ⇒ `ok:false`.
+ */
+export async function verifySmartAgentCardBinding(signed, opts) {
+    const b = signed?.binding;
+    if (!b ||
+        typeof signed.chainId !== 'number' ||
+        typeof signed.verifyingContract !== 'string' ||
+        typeof signed.signature !== 'string' ||
+        typeof b.canonicalAgentId !== 'string') {
+        return { ok: false, reason: 'bad_shape' };
+    }
+    const m = CAIP10_EVM.exec(b.canonicalAgentId);
+    if (!m || Number(m[1]) !== signed.chainId || m[2].toLowerCase() !== signed.verifyingContract.toLowerCase()) {
+        return { ok: false, reason: 'agent_mismatch' };
+    }
+    if (opts.expect?.unsignedCardDigest && opts.expect.unsignedCardDigest !== b.unsignedCardDigest) {
+        return { ok: false, reason: 'digest_mismatch' };
+    }
+    if (opts.expect?.signedCardDigest && opts.expect.signedCardDigest !== b.signedCardDigest) {
+        return { ok: false, reason: 'digest_mismatch' };
+    }
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    if (now < b.validFrom)
+        return { ok: false, reason: 'not_yet_valid' };
+    if (b.validUntil !== 0 && now > b.validUntil)
+        return { ok: false, reason: 'expired' };
+    let digest;
+    try {
+        digest = smartAgentCardBindingDigest(b, signed.chainId, signed.verifyingContract);
+    }
+    catch {
+        return { ok: false, reason: 'bad_shape' };
+    }
+    let valid;
+    try {
+        valid = await opts.erc1271Verifier.verifyHash({ address: signed.verifyingContract, hash: digest, signature: signed.signature });
+    }
+    catch {
+        return { ok: false, reason: 'signature_invalid' };
+    }
+    if (!valid)
+        return { ok: false, reason: 'signature_invalid' };
+    return { ok: true, smartAgent: signed.verifyingContract, digest };
+}
+//# sourceMappingURL=binding.js.map

package/dist/a2a/binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../../src/a2a/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAA0B,MAAM,MAAM,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG5D,MAAM,CAAC,MAAM,oCAAoC,GAAG,4BAA4B,CAAC;AACjF,MAAM,CAAC,MAAM,uCAAuC,GAAG,GAAG,CAAC;AAE3D,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,qBAAqB,EAAE;QACrB,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC5C,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC1C,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,EAAE;QACzC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE;QACnC,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,SAAS,EAAE;QAC/C,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,SAAS,EAAE;QAC7C,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,SAAS,EAAE;QAChD,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE;QACrC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE;KACvC;CACO,CAAC;AAEX,uEAAuE;AACvE,MAAM,CAAC,MAAM,oCAAoC,GAC/C,6NAA6N,CAAC;AAEhO,MAAM,UAAU,2BAA2B,CAAC,OAAe,EAAE,UAAmB;IAC9E,OAAO;QACL,IAAI,EAAE,oCAAoC;QAC1C,OAAO,EAAE,uCAAuC;QAChD,OAAO;QACP,iBAAiB,EAAE,UAAU;KACrB,CAAC;AACb,CAAC;AAED,wGAAwG;AAExG,MAAM,SAAS,GAAG,yBAAyB,CAAC;AAE5C,MAAM,UAAU,eAAe,CAAC,MAAuB;IACrD,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/C,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,GAAG,CAAC,CAAC;IAC5D,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAAS,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,CAAM;IACpC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAC7E,OAAO,UAAU,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,EAAY,CAAC;AACxD,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,MAAM,KAAK,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IAC1C,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IACtG,OAAO,KAAK,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,EAAS,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,CAAM;IACxC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAC7E,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE;QAAE,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACpF,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED,wGAAwG;AAExG,uFAAuF;AACvF,MAAM,UAAU,4BAA4B,CAAC,CAA0B;IACrE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QAC7G,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;IACpF,CAAC;IACD,OAAO;QACL,gBAAgB,EAAE,CAAC,CAAC,gBAAgB;QACpC,cAAc,EAAE,CAAC,CAAC,cAAc;QAChC,aAAa,EAAE,CAAC,CAAC,aAAa;QAC9B,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,kBAAkB,EAAE,eAAe,CAAC,CAAC,CAAC,kBAAkB,CAAC;QACzD,gBAAgB,EAAE,eAAe,CAAC,CAAC,CAAC,gBAAgB,CAAC;QACrD,mBAAmB,EAAE,mBAAmB,CAAC,CAAC,CAAC,mBAAmB,CAAC;QAC/D,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9B,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC;KACjC,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,2BAA2B,CAAC,OAAgC,EAAE,OAAe,EAAE,UAAmB;IAChH,OAAO,aAAa,CAAC;QACnB,MAAM,EAAE,2BAA2B,CAAC,OAAO,EAAE,UAAU,CAAC;QACxD,KAAK,EAAE,8BAA8B;QACrC,WAAW,EAAE,uBAAuB;QACpC,OAAO,EAAE,4BAA4B,CAAC,OAAO,CAAC;KAC/C,CAAC,CAAC;AACL,CAAC;AAyBD,MAAM,UAAU,GAAG,oCAAoC,CAAC;AAExD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,MAAqC,EACrC,IAAwC;IAExC,MAAM,CAAC,GAAG,MAAM,EAAE,OAAO,CAAC;IAC1B,IACE,CAAC,CAAC;QACF,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;QAClC,OAAO,MAAM,CAAC,iBAAiB,KAAK,QAAQ;QAC5C,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;QACpC,OAAO,CAAC,CAAC,gBAAgB,KAAK,QAAQ,EACtC,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC5C,CAAC;IACD,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAC9C,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,iBAAiB,CAAC,WAAW,EAAE,EAAE,CAAC;QAC5G,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACjD,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,EAAE,kBAAkB,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,KAAK,CAAC,CAAC,kBAAkB,EAAE,CAAC;QAC/F,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAClD,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,EAAE,gBAAgB,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,KAAK,CAAC,CAAC,gBAAgB,EAAE,CAAC;QACzF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAClD,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACtD,IAAI,GAAG,GAAG,CAAC,CAAC,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IACrE,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,UAAU;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAEtF,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,2BAA2B,CAAC,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC5C,CAAC;IACD,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,iBAAiB,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;IAClI,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,EAAE,CAAC;AACpE,CAAC"}

package/dist/a2a/canonical.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Canonical form of an A2A Agent Card (spec 347 §4.2).
+ *
+ *   remove `signatures` → RFC 8785 JCS → UTF-8 bytes → `sha256:<hex>`
+ *
+ * Uses `types.jcsCanonicalize` (RFC 8785: number formatting, escaping, UTF-16 code-unit key order) and
+ * NOT the sorted-key `canonicalizeJson` — those produce different bytes for the same document, and these
+ * bytes are what every JWS signs and every Smart Agent binding names. Presence is preserved: an omitted
+ * optional and an explicit default are different bytes, on purpose.
+ */
+import type { Sha256 } from '../types.js';
+/** Anything card-shaped: the typed card, or a raw imported object (unknown fields included — they are
+ *  part of what an existing signature covers). */
+export type CardLike = {
+    signatures?: unknown;
+};
+/** The card without `signatures` — the exact object every signature is computed over. */
+export declare function unsignedCard<T extends CardLike>(card: T): Omit<T, 'signatures'>;
+/** JCS string of the unsigned card. Throws (`JcsError`) on non-JSON values — never silently drops. */
+export declare function canonicalCardJson(card: CardLike): string;
+/** UTF-8 bytes of {@link canonicalCardJson}. */
+export declare function canonicalCardBytes(card: CardLike): Uint8Array;
+/** `sha256:<hex>` of arbitrary bytes. */
+export declare function sha256Digest(bytes: Uint8Array): Sha256;
+/** `sha256:<hex>` of a JCS-canonicalized value (used for field digests + etags). */
+export declare function jcsDigest(value: unknown): Sha256;
+/** `unsignedContentDigest`: sha256 of the canonical (unsigned) card bytes. */
+export declare function cardContentDigest(card: CardLike): Sha256;
+/** `signedContentDigest`: sha256 over JCS of the WHOLE card, signatures included. */
+export declare function signedCardContentDigest(card: CardLike): Sha256;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/a2a/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/a2a/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;kDACkD;AAClD,MAAM,MAAM,QAAQ,GAAG;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhD,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,YAAY,CAAC,CAG/E;AAED,sGAAsG;AACtG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAExD;AAID,gDAAgD;AAChD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAE7D;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEtD;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAExD;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAE9D"}

package/dist/a2a/canonical.js

@@ -0,0 +1,43 @@
+/**
+ * Canonical form of an A2A Agent Card (spec 347 §4.2).
+ *
+ *   remove `signatures` → RFC 8785 JCS → UTF-8 bytes → `sha256:<hex>`
+ *
+ * Uses `types.jcsCanonicalize` (RFC 8785: number formatting, escaping, UTF-16 code-unit key order) and
+ * NOT the sorted-key `canonicalizeJson` — those produce different bytes for the same document, and these
+ * bytes are what every JWS signs and every Smart Agent binding names. Presence is preserved: an omitted
+ * optional and an explicit default are different bytes, on purpose.
+ */
+import { jcsCanonicalize } from '@agenticprimitives/types';
+import { sha256 as viemSha256 } from 'viem';
+/** The card without `signatures` — the exact object every signature is computed over. */
+export function unsignedCard(card) {
+    const { signatures: _drop, ...rest } = card;
+    return rest;
+}
+/** JCS string of the unsigned card. Throws (`JcsError`) on non-JSON values — never silently drops. */
+export function canonicalCardJson(card) {
+    return jcsCanonicalize(unsignedCard(card));
+}
+const utf8 = new TextEncoder();
+/** UTF-8 bytes of {@link canonicalCardJson}. */
+export function canonicalCardBytes(card) {
+    return utf8.encode(canonicalCardJson(card));
+}
+/** `sha256:<hex>` of arbitrary bytes. */
+export function sha256Digest(bytes) {
+    return `sha256:${viemSha256(bytes).slice(2)}`;
+}
+/** `sha256:<hex>` of a JCS-canonicalized value (used for field digests + etags). */
+export function jcsDigest(value) {
+    return sha256Digest(utf8.encode(jcsCanonicalize(value)));
+}
+/** `unsignedContentDigest`: sha256 of the canonical (unsigned) card bytes. */
+export function cardContentDigest(card) {
+    return sha256Digest(canonicalCardBytes(card));
+}
+/** `signedContentDigest`: sha256 over JCS of the WHOLE card, signatures included. */
+export function signedCardContentDigest(card) {
+    return jcsDigest(card);
+}
+//# sourceMappingURL=canonical.js.map

package/dist/a2a/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../src/a2a/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AAO5C,yFAAyF;AACzF,MAAM,UAAU,YAAY,CAAqB,IAAO;IACtD,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC5C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,OAAO,eAAe,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;AAE/B,gDAAgD;AAChD,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,OAAO,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC5C,OAAO,UAAU,UAAU,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAY,CAAC;AAC1D,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,OAAO,YAAY,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,uBAAuB,CAAC,IAAc;IACpD,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC"}

package/dist/a2a/field-binding.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Field provenance (spec 347 §4.3; ADR-0062 §4): inherit the card base, curate with recorded overrides,
+ * detect when an inherited source moved under a draft. PURE — the clock is an input.
+ *
+ * Sources are STRUCTURAL (no package import): `surfaceCards` is shaped like `surface-catalog`'s
+ * `toCardProjectionSet(...)` output, `publicSkillCandidates` like `capability-claims`'
+ * `A2aAgentSkillDescriptor`. surface-catalog remains the only generator of inherited interface/skill
+ * fields; capability claims add PUBLIC skills with their own provenance.
+ */
+import type { EvidenceRefV1 } from '@agenticprimitives/types';
+import type { CanonicalAgentProfileV1 } from '../types.js';
+import type { A2AAgentCapabilitiesV1, A2AAgentCardDraftV1, A2AAgentCardV1, A2AAgentInterfaceV1, FieldBindingSourceKind, FieldBindingV1, Sha256 } from './types.js';
+/** Shape of `surface-catalog` `A2aCardSkillLike` (structural, no package dependency). */
+export interface SurfaceCardSkillLike {
+    id: string;
+    name: string;
+    description?: string;
+}
+/** Structural shape of `AdvertisedCapabilityV1` — used for both profile capabilities and public claims. */
+export interface AdvertisedCapabilityLike {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    examples?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+}
+/** @deprecated Name says "skill"; this is an advertised capability. Alias kept for existing importers. */
+export interface PublicSkillCandidateLike {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    examples?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+}
+export interface InheritCardBaseInput {
+    profile: CanonicalAgentProfileV1;
+    /** From `agent-naming`: the primary public name (used as the card name when present). */
+    names?: {
+        primary?: string;
+        all?: string[];
+    };
+    /** `toCardProjectionSet(catalog).public` — the runtime-served public skills. */
+    surfaceCards: {
+        public: SurfaceCardSkillLike[];
+    };
+    /** Interfaces the surface catalog / deployment serves; absent ⇒ computed from `deployment.a2aUrl`. */
+    surfaceInterfaces?: A2AAgentInterfaceV1[];
+    /** What the runtime actually implements. Absent ⇒ every flag false (honest, ADR-0059). */
+    runtimeCapabilities?: A2AAgentCapabilitiesV1;
+    /** Eligible PUBLIC capability claims, already policy-filtered (spec 347 §5). */
+    publicSkillCandidates?: PublicSkillCandidateLike[];
+    deployment: {
+        /** Public origin, e.g. `https://agent.example`. */
+        host?: string;
+        /** The A2A message endpoint URL. */
+        a2aUrl: string;
+        protocolBinding?: A2AAgentInterfaceV1['protocolBinding'];
+        documentationUrl?: string;
+        /** Provider organization/url (operator relationship); falls back to the profile. */
+        provider?: {
+            organization: string;
+            url: string;
+        };
+    };
+    /** The AGENT implementation version. Default `'0.1.0'`. */
+    agentVersion?: string;
+    protocolVersion?: string;
+    mediaModes?: {
+        input?: string[];
+        output?: string[];
+    };
+    /** ISO timestamp for every binding's `updatedAt` (pure — the caller supplies the clock). */
+    now: string;
+}
+export interface InheritedCardBase {
+    card: A2AAgentCardV1;
+    fieldBindings: Record<string, FieldBindingV1>;
+    /** `sha256:` of the inherited card — the draft's `sourceSnapshotDigest`. */
+    snapshotDigest: Sha256;
+}
+/** Generate the card base from canonical sources. Every field carries an `inherit` or `computed` binding. */
+export declare function inheritCardBase(input: InheritCardBaseInput): InheritedCardBase;
+/** Start a draft from an inherited base. */
+export declare function draftFromBase(base: InheritedCardBase, opts: {
+    cardResourceId: string;
+    now: string;
+    revision?: number;
+    basedOnReleaseId?: string;
+}): A2AAgentCardDraftV1;
+/** Opaque optimistic-concurrency token: digest of card + bindings + revision. */
+export declare function draftEtag(d: Pick<A2AAgentCardDraftV1, 'card' | 'fieldBindings' | 'revision' | 'extendedCardPolicies'>): string;
+export interface ApplyOverrideOptions {
+    source?: {
+        kind: FieldBindingSourceKind;
+        ref?: string;
+    };
+    evidence?: EvidenceRefV1[];
+    now: string;
+}
+/**
+ * Curate one field. Returns a NEW draft (revision+1) with an `override` binding at `pointer` that remembers
+ * the digest of the value it replaced. Nothing is mutated. `value === undefined` removes the field.
+ */
+export declare function applyOverride(draft: A2AAgentCardDraftV1, pointer: string, value: unknown, opts: ApplyOverrideOptions): A2AAgentCardDraftV1;
+export interface StaleReport {
+    /** Inherited/computed pointers whose fresh base value differs from the draft. */
+    stale: string[];
+    /** Overridden pointers whose fresh base value differs from the value the override replaced. */
+    conflict: string[];
+    /** The draft with binding states updated (`stale` / `conflict`); overrides' VALUES untouched. */
+    draft: A2AAgentCardDraftV1;
+}
+/**
+ * Compare a draft against a freshly inherited base. Published releases are never touched; the draft's
+ * bindings become `stale` (inherited value moved) or `conflict` (base moved under an override). The
+ * editor then shows old / new / effective and the user accepts, retains, or revises.
+ */
+export declare function detectStale(draft: A2AAgentCardDraftV1, freshBase: Pick<InheritedCardBase, 'card' | 'snapshotDigest'>): StaleReport;
+/** Accept the fresh inherited value for one stale pointer (binding back to `inherit`, state `fresh`). */
+export declare function acceptInherited(draft: A2AAgentCardDraftV1, pointer: string, freshBase: Pick<InheritedCardBase, 'card' | 'fieldBindings'>, now: string): A2AAgentCardDraftV1;
+//# sourceMappingURL=field-binding.d.ts.map

package/dist/a2a/field-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-binding.d.ts","sourceRoot":"","sources":["../../src/a2a/field-binding.ts"],"names":[],"mappings":"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"}