@vorim/sdk 3.2.0 → 3.3.1

package/dist/index.d.cts

@@ -75,6 +75,76 @@ interface AuditEventInput {
      * is `"v1"`; you can also pass it on a per-event basis.
      */
     canonical_form?: 'v0' | 'v1';
+    /**
+     * Per-event delegation context (VAIP -02 § 6). Populated by the
+     * server when the emitting agent is acting via a delegation chain;
+     * callers may also set these manually for events recorded outside
+     * the standard delegation flow. v1 signatures cover these fields.
+     */
+    on_behalf_of?: string;
+    delegator_agent_id?: string;
+    delegation_chain_id?: string;
+    delegation_depth?: number;
+}
+/**
+ * Claims structure for one VAIP -02 § 5 delegation link.
+ *
+ * Each delegation step in a chain is one of these objects, RFC 8785 JCS
+ * canonicalised and Ed25519-signed by the delegator. Mirrors the same
+ * type in `@vorim/shared-types`; duplicated here so the SDK ships zero
+ * runtime dependencies. Byte-equivalence with the shared definition is
+ * enforced by the cross-language parity script.
+ */
+interface DelegationLinkClaims {
+    v: 0;
+    type: 'vaip-delegation-link';
+    chain_id: string;
+    depth: number;
+    delegator: string;
+    delegate: string;
+    scopes: string[];
+    max_chain_depth: number;
+    valid_from: string;
+    valid_until: string | null;
+    parent_link_hash: string | null;
+}
+/**
+ * One step in an agent-to-agent identity delegation chain (VAIP -02 § 5).
+ *
+ * Returned by {@link VorimSDK.delegateToAgent} and the listing endpoints.
+ */
+interface AgentDelegationRecord {
+    /** Internal row id. */
+    id: string;
+    /** Public chain identifier (format `chain_<32hex>`). Stamped on
+     *  every audit event in this chain. */
+    publicChainId: string;
+    /** Organisation id. */
+    orgId: string;
+    /** Internal DB id of the delegator agent. */
+    delegatorAgentId: string;
+    /** Internal DB id of the delegate agent. */
+    delegateAgentId: string;
+    /** Public agent_id of the delegator (e.g. agid_acme_abc). */
+    delegatorAgentPublicId: string;
+    /** Public agent_id of the delegate. */
+    delegateAgentPublicId: string;
+    /** Scopes the delegate may exercise. */
+    scopesDelegated: string[];
+    /** How many further hops the delegate is permitted. */
+    maxChainDepth: number;
+    /** This step's depth from the root (root delegator step = 1). */
+    currentDepth: number;
+    /** Active / suspended / revoked / expired. */
+    status: 'active' | 'suspended' | 'revoked' | 'expired';
+    /** Parent delegation row (null for the root of an identity chain). */
+    parentDelegationId: string | null;
+    /** Public agent_id of the root principal of this chain. */
+    onBehalfOf: string;
+    /** ISO8601 creation timestamp. */
+    createdAt: string;
+    /** Optional ISO8601 expiry. */
+    validUntil: string | null;
 }
 interface TrustRecord {
     agent_id: string;
@@ -302,6 +372,14 @@ declare class VorimSDK {
      * link to the old chain.
      */
     private lastEventHash;
+    /**
+     * Per-agent monotonic counter incremented by `forgetAgentKey`. An
+     * emit that started before `forgetAgentKey` ran will read a stale
+     * epoch and refuse to repopulate the chain tail, preventing the
+     * revoked agent from inheriting a new lastEventHash from the
+     * in-flight emit that the lock was holding.
+     */
+    private agentForgetEpoch;
     /**
      * Per-agent emit promise. Each new emit awaits the previous one so
      * the chain is constructed in order. Concurrent emits to the same
@@ -392,6 +470,97 @@ declare class VorimSDK {
      * Revoke a specific permission scope from an agent.
      */
     revokePermission(agentId: string, scope: PermissionScope): Promise<any>;
+    /**
+     * Delegate the right to act on this agent's behalf to another agent
+     * in the same org, with a strict subset of this agent's scopes.
+     *
+     * Multi-hop chains are supported up to depth 32. Scope subset is
+     * enforced at every hop. Audit events emitted by the delegate carry
+     * the chain context (`on_behalf_of`, `delegator_agent_id`,
+     * `delegation_chain_id`, `delegation_depth`) so a verifier walking
+     * the bundle can reconstruct the full chain.
+     *
+     * @example
+     * ```ts
+     * const chain = await vorim.delegateToAgent('agid_parent_abc', {
+     *   delegate_agent_id: 'agid_child_xyz',
+     *   scopes_delegated: ['agent:read', 'agent:execute'],
+     *   max_chain_depth: 1,        // delegate may make ONE further hop
+     *   valid_until: '2026-12-31T00:00:00Z',
+     * });
+     * console.log(chain.public_chain_id); // chain_<hex>
+     * ```
+     */
+    delegateToAgent(delegatorAgentId: string, input: {
+        delegate_agent_id: string;
+        scopes_delegated: PermissionScope[];
+        max_chain_depth?: number;
+        valid_until?: string;
+        /**
+         * Optional Ed25519-signed delegation link (VAIP -02 § 5). When
+         * provided, the server verifies the signature against the
+         * delegator's stored public key, persists alongside the chain
+         * row, and exports it in bundle delegation_tokens so the chain
+         * is offline-verifiable by `@vorim/verify`. Compute via
+         * {@link signDelegationLink} or set manually if signing
+         * elsewhere.
+         */
+        signed_link?: {
+            claims: DelegationLinkClaims;
+            signature: string;
+        };
+    }): Promise<AgentDelegationRecord>;
+    /**
+     * Sign a delegation link with the delegator's private key. Returns
+     * the signed link in the shape accepted by `delegateToAgent`'s
+     * `signed_link` field.
+     *
+     * The signature is Ed25519 over the RFC 8785 JCS-canonical bytes of
+     * the claims object. Same algorithm the server and `@vorim/verify`
+     * use for verification.
+     *
+     * Use this when the delegator's private key is in this SDK's
+     * keyring (i.e. set via `register()` or `useAgentKey()`).
+     *
+     * @example
+     * ```ts
+     * const signed = await vorim.signDelegationLink({
+     *   v: 0,
+     *   type: 'vaip-delegation-link',
+     *   chain_id: 'chain_abc',           // server returns this on first delegation
+     *   depth: 1,
+     *   delegator: 'agid_parent',
+     *   delegate: 'agid_child',
+     *   scopes: ['agent:read', 'agent:execute'],
+     *   max_chain_depth: 1,
+     *   valid_from: new Date().toISOString(),
+     *   valid_until: null,
+     *   parent_link_hash: null,
+     * });
+     * ```
+     */
+    signDelegationLink(claims: DelegationLinkClaims): Promise<{
+        claims: DelegationLinkClaims;
+        signature: string;
+    }>;
+    /**
+     * List active identity-chain entries this agent participates in
+     * (either as delegator or delegate). Useful for showing the current
+     * delegation graph in an admin UI.
+     */
+    listAgentDelegations(agentId: string): Promise<AgentDelegationRecord[]>;
+    /**
+     * Walk a delegation chain by its public id. Returns the full chain
+     * in depth order.
+     */
+    getDelegationChain(agentId: string, chainId: string): Promise<AgentDelegationRecord[]>;
+    /**
+     * Revoke this agent's delegation in a given chain. Cascades to all
+     * descendants beneath this agent's depth in the chain.
+     */
+    revokeAgentDelegation(agentId: string, chainId: string): Promise<{
+        revoked: number;
+    }>;
     /**
      * Emit an audit event for an agent action.
      *
@@ -412,12 +581,18 @@ declare class VorimSDK {
      * Emit a batch of audit events (up to 1,000). Each event is signed
      * independently using its agent_id to look up the signing key. See
      * {@link VorimSDK.emit} for signing behaviour and opt-out.
+     *
+     * When the server returns `ingested < events.length` (e.g. one event
+     * referenced an unknown agent_id), a `console.warn` is emitted so
+     * operators don't silently lose audit rows. The result is returned
+     * unchanged so callers can inspect / act on it.
      */
     emitBatch(events: AuditEventInput[], options?: {
         sign?: boolean;
     }): Promise<{
         ingested: number;
     }>;
+    private warnOnPartialIngest;
     /**
      * Internal: prepare an event for transmission. Auto-signs if the SDK has a
      * key for this agent and signing isn't explicitly opted out. Pre-existing
@@ -444,7 +619,15 @@ declare class VorimSDK {
     private prepareEvent;
     /** Serialise per-agent and apply chain hash + sign. */
     private prepareEventChained;
-    /** Sign an event right now, no chain handling. */
+    /** Sign an event right now, no chain handling.
+     *
+     * On signing failure (malformed key, Web Crypto unavailable, etc.)
+     * the event ships with its requested `canonical_form` preserved and
+     * a one-line warning is logged via `console.warn`. The previous
+     * behaviour silently dropped both the signature AND the
+     * canonical_form marker, which caused the event to be classified
+     * server-side as a v0 `signature_missing` instead of a v1 attempt
+     * that failed — making the breakage invisible to operators. */
     private signEventNow;
     /**
      * Export a signed audit bundle for a date range.
@@ -568,4 +751,4 @@ declare class VorimError extends Error {
 }
 declare function createVorim(config: VorimConfig): VorimSDK;
 
-export { type Agent, type AgentRegistrationInput, type AgentRegistrationResult, type AgentStatus, type AuditEventInput, type AuditEventType, type AuditResult, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type PermissionCheckResult, type PermissionScope, type ReplayContext, type ReplayInputs, type TrustRecord, type VorimConfig, VorimError, VorimSDK, canonicalPayloadV0, canonicalPayloadV1, createVorim as default, hashPreviousEvent, hashSystemPrompt, hashTool, hashToolCatalogue, jcsCanonicalise, prepareReplayContext };
+export { type Agent, type AgentDelegationRecord, type AgentRegistrationInput, type AgentRegistrationResult, type AgentStatus, type AuditEventInput, type AuditEventType, type AuditResult, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type DelegationLinkClaims, type PermissionCheckResult, type PermissionScope, type ReplayContext, type ReplayInputs, type TrustRecord, type VorimConfig, VorimError, VorimSDK, canonicalPayloadV0, canonicalPayloadV1, createVorim as default, hashPreviousEvent, hashSystemPrompt, hashTool, hashToolCatalogue, jcsCanonicalise, prepareReplayContext };

package/dist/index.d.ts

@@ -75,6 +75,76 @@ interface AuditEventInput {
      * is `"v1"`; you can also pass it on a per-event basis.
      */
     canonical_form?: 'v0' | 'v1';
+    /**
+     * Per-event delegation context (VAIP -02 § 6). Populated by the
+     * server when the emitting agent is acting via a delegation chain;
+     * callers may also set these manually for events recorded outside
+     * the standard delegation flow. v1 signatures cover these fields.
+     */
+    on_behalf_of?: string;
+    delegator_agent_id?: string;
+    delegation_chain_id?: string;
+    delegation_depth?: number;
+}
+/**
+ * Claims structure for one VAIP -02 § 5 delegation link.
+ *
+ * Each delegation step in a chain is one of these objects, RFC 8785 JCS
+ * canonicalised and Ed25519-signed by the delegator. Mirrors the same
+ * type in `@vorim/shared-types`; duplicated here so the SDK ships zero
+ * runtime dependencies. Byte-equivalence with the shared definition is
+ * enforced by the cross-language parity script.
+ */
+interface DelegationLinkClaims {
+    v: 0;
+    type: 'vaip-delegation-link';
+    chain_id: string;
+    depth: number;
+    delegator: string;
+    delegate: string;
+    scopes: string[];
+    max_chain_depth: number;
+    valid_from: string;
+    valid_until: string | null;
+    parent_link_hash: string | null;
+}
+/**
+ * One step in an agent-to-agent identity delegation chain (VAIP -02 § 5).
+ *
+ * Returned by {@link VorimSDK.delegateToAgent} and the listing endpoints.
+ */
+interface AgentDelegationRecord {
+    /** Internal row id. */
+    id: string;
+    /** Public chain identifier (format `chain_<32hex>`). Stamped on
+     *  every audit event in this chain. */
+    publicChainId: string;
+    /** Organisation id. */
+    orgId: string;
+    /** Internal DB id of the delegator agent. */
+    delegatorAgentId: string;
+    /** Internal DB id of the delegate agent. */
+    delegateAgentId: string;
+    /** Public agent_id of the delegator (e.g. agid_acme_abc). */
+    delegatorAgentPublicId: string;
+    /** Public agent_id of the delegate. */
+    delegateAgentPublicId: string;
+    /** Scopes the delegate may exercise. */
+    scopesDelegated: string[];
+    /** How many further hops the delegate is permitted. */
+    maxChainDepth: number;
+    /** This step's depth from the root (root delegator step = 1). */
+    currentDepth: number;
+    /** Active / suspended / revoked / expired. */
+    status: 'active' | 'suspended' | 'revoked' | 'expired';
+    /** Parent delegation row (null for the root of an identity chain). */
+    parentDelegationId: string | null;
+    /** Public agent_id of the root principal of this chain. */
+    onBehalfOf: string;
+    /** ISO8601 creation timestamp. */
+    createdAt: string;
+    /** Optional ISO8601 expiry. */
+    validUntil: string | null;
 }
 interface TrustRecord {
     agent_id: string;
@@ -302,6 +372,14 @@ declare class VorimSDK {
      * link to the old chain.
      */
     private lastEventHash;
+    /**
+     * Per-agent monotonic counter incremented by `forgetAgentKey`. An
+     * emit that started before `forgetAgentKey` ran will read a stale
+     * epoch and refuse to repopulate the chain tail, preventing the
+     * revoked agent from inheriting a new lastEventHash from the
+     * in-flight emit that the lock was holding.
+     */
+    private agentForgetEpoch;
     /**
      * Per-agent emit promise. Each new emit awaits the previous one so
      * the chain is constructed in order. Concurrent emits to the same
@@ -392,6 +470,97 @@ declare class VorimSDK {
      * Revoke a specific permission scope from an agent.
      */
     revokePermission(agentId: string, scope: PermissionScope): Promise<any>;
+    /**
+     * Delegate the right to act on this agent's behalf to another agent
+     * in the same org, with a strict subset of this agent's scopes.
+     *
+     * Multi-hop chains are supported up to depth 32. Scope subset is
+     * enforced at every hop. Audit events emitted by the delegate carry
+     * the chain context (`on_behalf_of`, `delegator_agent_id`,
+     * `delegation_chain_id`, `delegation_depth`) so a verifier walking
+     * the bundle can reconstruct the full chain.
+     *
+     * @example
+     * ```ts
+     * const chain = await vorim.delegateToAgent('agid_parent_abc', {
+     *   delegate_agent_id: 'agid_child_xyz',
+     *   scopes_delegated: ['agent:read', 'agent:execute'],
+     *   max_chain_depth: 1,        // delegate may make ONE further hop
+     *   valid_until: '2026-12-31T00:00:00Z',
+     * });
+     * console.log(chain.public_chain_id); // chain_<hex>
+     * ```
+     */
+    delegateToAgent(delegatorAgentId: string, input: {
+        delegate_agent_id: string;
+        scopes_delegated: PermissionScope[];
+        max_chain_depth?: number;
+        valid_until?: string;
+        /**
+         * Optional Ed25519-signed delegation link (VAIP -02 § 5). When
+         * provided, the server verifies the signature against the
+         * delegator's stored public key, persists alongside the chain
+         * row, and exports it in bundle delegation_tokens so the chain
+         * is offline-verifiable by `@vorim/verify`. Compute via
+         * {@link signDelegationLink} or set manually if signing
+         * elsewhere.
+         */
+        signed_link?: {
+            claims: DelegationLinkClaims;
+            signature: string;
+        };
+    }): Promise<AgentDelegationRecord>;
+    /**
+     * Sign a delegation link with the delegator's private key. Returns
+     * the signed link in the shape accepted by `delegateToAgent`'s
+     * `signed_link` field.
+     *
+     * The signature is Ed25519 over the RFC 8785 JCS-canonical bytes of
+     * the claims object. Same algorithm the server and `@vorim/verify`
+     * use for verification.
+     *
+     * Use this when the delegator's private key is in this SDK's
+     * keyring (i.e. set via `register()` or `useAgentKey()`).
+     *
+     * @example
+     * ```ts
+     * const signed = await vorim.signDelegationLink({
+     *   v: 0,
+     *   type: 'vaip-delegation-link',
+     *   chain_id: 'chain_abc',           // server returns this on first delegation
+     *   depth: 1,
+     *   delegator: 'agid_parent',
+     *   delegate: 'agid_child',
+     *   scopes: ['agent:read', 'agent:execute'],
+     *   max_chain_depth: 1,
+     *   valid_from: new Date().toISOString(),
+     *   valid_until: null,
+     *   parent_link_hash: null,
+     * });
+     * ```
+     */
+    signDelegationLink(claims: DelegationLinkClaims): Promise<{
+        claims: DelegationLinkClaims;
+        signature: string;
+    }>;
+    /**
+     * List active identity-chain entries this agent participates in
+     * (either as delegator or delegate). Useful for showing the current
+     * delegation graph in an admin UI.
+     */
+    listAgentDelegations(agentId: string): Promise<AgentDelegationRecord[]>;
+    /**
+     * Walk a delegation chain by its public id. Returns the full chain
+     * in depth order.
+     */
+    getDelegationChain(agentId: string, chainId: string): Promise<AgentDelegationRecord[]>;
+    /**
+     * Revoke this agent's delegation in a given chain. Cascades to all
+     * descendants beneath this agent's depth in the chain.
+     */
+    revokeAgentDelegation(agentId: string, chainId: string): Promise<{
+        revoked: number;
+    }>;
     /**
      * Emit an audit event for an agent action.
      *
@@ -412,12 +581,18 @@ declare class VorimSDK {
      * Emit a batch of audit events (up to 1,000). Each event is signed
      * independently using its agent_id to look up the signing key. See
      * {@link VorimSDK.emit} for signing behaviour and opt-out.
+     *
+     * When the server returns `ingested < events.length` (e.g. one event
+     * referenced an unknown agent_id), a `console.warn` is emitted so
+     * operators don't silently lose audit rows. The result is returned
+     * unchanged so callers can inspect / act on it.
      */
     emitBatch(events: AuditEventInput[], options?: {
         sign?: boolean;
     }): Promise<{
         ingested: number;
     }>;
+    private warnOnPartialIngest;
     /**
      * Internal: prepare an event for transmission. Auto-signs if the SDK has a
      * key for this agent and signing isn't explicitly opted out. Pre-existing
@@ -444,7 +619,15 @@ declare class VorimSDK {
     private prepareEvent;
     /** Serialise per-agent and apply chain hash + sign. */
     private prepareEventChained;
-    /** Sign an event right now, no chain handling. */
+    /** Sign an event right now, no chain handling.
+     *
+     * On signing failure (malformed key, Web Crypto unavailable, etc.)
+     * the event ships with its requested `canonical_form` preserved and
+     * a one-line warning is logged via `console.warn`. The previous
+     * behaviour silently dropped both the signature AND the
+     * canonical_form marker, which caused the event to be classified
+     * server-side as a v0 `signature_missing` instead of a v1 attempt
+     * that failed — making the breakage invisible to operators. */
     private signEventNow;
     /**
      * Export a signed audit bundle for a date range.
@@ -568,4 +751,4 @@ declare class VorimError extends Error {
 }
 declare function createVorim(config: VorimConfig): VorimSDK;
 
-export { type Agent, type AgentRegistrationInput, type AgentRegistrationResult, type AgentStatus, type AuditEventInput, type AuditEventType, type AuditResult, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type PermissionCheckResult, type PermissionScope, type ReplayContext, type ReplayInputs, type TrustRecord, type VorimConfig, VorimError, VorimSDK, canonicalPayloadV0, canonicalPayloadV1, createVorim as default, hashPreviousEvent, hashSystemPrompt, hashTool, hashToolCatalogue, jcsCanonicalise, prepareReplayContext };
+export { type Agent, type AgentDelegationRecord, type AgentRegistrationInput, type AgentRegistrationResult, type AgentStatus, type AuditEventInput, type AuditEventType, type AuditResult, CANONICAL_TOOL_CATALOGUE_VERSION, type CatalogueTool, type DelegationLinkClaims, type PermissionCheckResult, type PermissionScope, type ReplayContext, type ReplayInputs, type TrustRecord, type VorimConfig, VorimError, VorimSDK, canonicalPayloadV0, canonicalPayloadV1, createVorim as default, hashPreviousEvent, hashSystemPrompt, hashTool, hashToolCatalogue, jcsCanonicalise, prepareReplayContext };

package/dist/index.js

@@ -70,7 +70,7 @@ async function prepareReplayContext(inputs) {
 }
 
 // src/index.ts
-var SDK_VERSION = true ? "3.2.0" : "0.0.0";
+var SDK_VERSION = true ? "3.3.1" : "0.0.0";
 var USER_AGENT = `vorim-sdk/${SDK_VERSION}`;
 function canonicalPayloadV0(event) {
   return [
@@ -108,6 +108,14 @@ var VorimSDK = class {
    * link to the old chain.
    */
   lastEventHash = /* @__PURE__ */ new Map();
+  /**
+   * Per-agent monotonic counter incremented by `forgetAgentKey`. An
+   * emit that started before `forgetAgentKey` ran will read a stale
+   * epoch and refuse to repopulate the chain tail, preventing the
+   * revoked agent from inheriting a new lastEventHash from the
+   * in-flight emit that the lock was holding.
+   */
+  agentForgetEpoch = /* @__PURE__ */ new Map();
   /**
    * Per-agent emit promise. Each new emit awaits the previous one so
    * the chain is constructed in order. Concurrent emits to the same
@@ -142,6 +150,7 @@ var VorimSDK = class {
     this.agentKeys.delete(agentId);
     this.lastEventHash.delete(agentId);
     this.chainLocks.delete(agentId);
+    this.agentForgetEpoch.set(agentId, (this.agentForgetEpoch.get(agentId) ?? 0) + 1);
   }
   // ─── Health Check ────────────────────────────────────────────────
   /**
@@ -230,6 +239,95 @@ var VorimSDK = class {
   async revokePermission(agentId, scope) {
     return this.delete(`/agents/${agentId}/permissions/${scope}`);
   }
+  // ─── Agent-to-Agent Identity Delegation (VAIP -02 § 5) ──────────────
+  /**
+   * Delegate the right to act on this agent's behalf to another agent
+   * in the same org, with a strict subset of this agent's scopes.
+   *
+   * Multi-hop chains are supported up to depth 32. Scope subset is
+   * enforced at every hop. Audit events emitted by the delegate carry
+   * the chain context (`on_behalf_of`, `delegator_agent_id`,
+   * `delegation_chain_id`, `delegation_depth`) so a verifier walking
+   * the bundle can reconstruct the full chain.
+   *
+   * @example
+   * ```ts
+   * const chain = await vorim.delegateToAgent('agid_parent_abc', {
+   *   delegate_agent_id: 'agid_child_xyz',
+   *   scopes_delegated: ['agent:read', 'agent:execute'],
+   *   max_chain_depth: 1,        // delegate may make ONE further hop
+   *   valid_until: '2026-12-31T00:00:00Z',
+   * });
+   * console.log(chain.public_chain_id); // chain_<hex>
+   * ```
+   */
+  async delegateToAgent(delegatorAgentId, input) {
+    return this.post(`/agents/${delegatorAgentId}/delegations`, input);
+  }
+  /**
+   * Sign a delegation link with the delegator's private key. Returns
+   * the signed link in the shape accepted by `delegateToAgent`'s
+   * `signed_link` field.
+   *
+   * The signature is Ed25519 over the RFC 8785 JCS-canonical bytes of
+   * the claims object. Same algorithm the server and `@vorim/verify`
+   * use for verification.
+   *
+   * Use this when the delegator's private key is in this SDK's
+   * keyring (i.e. set via `register()` or `useAgentKey()`).
+   *
+   * @example
+   * ```ts
+   * const signed = await vorim.signDelegationLink({
+   *   v: 0,
+   *   type: 'vaip-delegation-link',
+   *   chain_id: 'chain_abc',           // server returns this on first delegation
+   *   depth: 1,
+   *   delegator: 'agid_parent',
+   *   delegate: 'agid_child',
+   *   scopes: ['agent:read', 'agent:execute'],
+   *   max_chain_depth: 1,
+   *   valid_from: new Date().toISOString(),
+   *   valid_until: null,
+   *   parent_link_hash: null,
+   * });
+   * ```
+   */
+  async signDelegationLink(claims) {
+    const key = this.agentKeys.get(claims.delegator);
+    if (!key) {
+      throw new VorimError(
+        400,
+        "NO_AGENT_KEY",
+        `SDK has no private key for delegator ${claims.delegator}`
+      );
+    }
+    const bytes = jcsCanonicalise(claims);
+    const signature = await this.sign(bytes, key);
+    return { claims, signature };
+  }
+  /**
+   * List active identity-chain entries this agent participates in
+   * (either as delegator or delegate). Useful for showing the current
+   * delegation graph in an admin UI.
+   */
+  async listAgentDelegations(agentId) {
+    return this.get(`/agents/${agentId}/delegations`);
+  }
+  /**
+   * Walk a delegation chain by its public id. Returns the full chain
+   * in depth order.
+   */
+  async getDelegationChain(agentId, chainId) {
+    return this.get(`/agents/${agentId}/delegation-chain/${chainId}`);
+  }
+  /**
+   * Revoke this agent's delegation in a given chain. Cascades to all
+   * descendants beneath this agent's depth in the chain.
+   */
+  async revokeAgentDelegation(agentId, chainId) {
+    return this.delete(`/agents/${agentId}/delegations/${chainId}`);
+  }
   // ─── Audit ────────────────────────────────────────────────────────
   /**
    * Emit an audit event for an agent action.
@@ -244,16 +342,35 @@ var VorimSDK = class {
    */
   async emit(event, options) {
     const prepared = await this.prepareEvent(event, options?.sign);
-    return this.post("/audit/events", { events: [prepared] });
+    const result = await this.post("/audit/events", { events: [prepared] });
+    this.warnOnPartialIngest(1, result?.ingested ?? 0);
+    return result;
   }
   /**
    * Emit a batch of audit events (up to 1,000). Each event is signed
    * independently using its agent_id to look up the signing key. See
    * {@link VorimSDK.emit} for signing behaviour and opt-out.
+   *
+   * When the server returns `ingested < events.length` (e.g. one event
+   * referenced an unknown agent_id), a `console.warn` is emitted so
+   * operators don't silently lose audit rows. The result is returned
+   * unchanged so callers can inspect / act on it.
    */
   async emitBatch(events, options) {
     const prepared = await Promise.all(events.map((e) => this.prepareEvent(e, options?.sign)));
-    return this.post("/audit/events", { events: prepared });
+    const result = await this.post("/audit/events", { events: prepared });
+    this.warnOnPartialIngest(events.length, result?.ingested ?? 0);
+    return result;
+  }
+  warnOnPartialIngest(submitted, ingested) {
+    if (ingested < submitted) {
+      try {
+        console.warn(
+          `[@vorim/sdk] partial ingest: server stored ${ingested}/${submitted} events. Common causes: unknown agent_id (cross-org or typo), invalid signature when strict verification is enabled.`
+        );
+      } catch {
+      }
+    }
   }
   /**
    * Internal: prepare an event for transmission. Auto-signs if the SDK has a
@@ -298,6 +415,7 @@ var VorimSDK = class {
     });
     this.chainLocks.set(agentId, prior.then(() => next));
     await prior;
+    const startEpoch = this.agentForgetEpoch.get(agentId) ?? 0;
     try {
       const prev = this.lastEventHash.get(agentId);
       const eventWithPrev = prev ? { ...event, prev_event_hash: prev } : event;
@@ -305,7 +423,10 @@ var VorimSDK = class {
       const wireForm = prepared.canonical_form ?? "v0";
       const bytes = wireForm === "v1" ? canonicalPayloadV1(prepared) : canonicalPayloadV0(prepared);
       try {
-        this.lastEventHash.set(agentId, await hashPreviousEvent(bytes));
+        const tail = await hashPreviousEvent(bytes);
+        if ((this.agentForgetEpoch.get(agentId) ?? 0) === startEpoch) {
+          this.lastEventHash.set(agentId, tail);
+        }
       } catch {
         this.lastEventHash.delete(agentId);
       }
@@ -314,18 +435,32 @@ var VorimSDK = class {
       release();
     }
   }
-  /** Sign an event right now, no chain handling. */
+  /** Sign an event right now, no chain handling.
+   *
+   * On signing failure (malformed key, Web Crypto unavailable, etc.)
+   * the event ships with its requested `canonical_form` preserved and
+   * a one-line warning is logged via `console.warn`. The previous
+   * behaviour silently dropped both the signature AND the
+   * canonical_form marker, which caused the event to be classified
+   * server-side as a v0 `signature_missing` instead of a v1 attempt
+   * that failed — making the breakage invisible to operators. */
   async signEventNow(event, _shouldSign) {
     const key = this.agentKeys.get(event.agent_id);
     if (!key) return event;
     const form = event.canonical_form ?? this.canonicalForm;
+    const withForm = form === "v0" ? event : { ...event, canonical_form: "v1" };
     try {
-      const withForm = form === "v0" ? event : { ...event, canonical_form: "v1" };
       const payload = form === "v1" ? canonicalPayloadV1(withForm) : canonicalPayloadV0(withForm);
       const signature = await this.sign(payload, key);
       return { ...withForm, signature };
-    } catch {
-      return event;
+    } catch (err) {
+      try {
+        console.warn(
+          `[@vorim/sdk] signing failed for agent_id=${event.agent_id} form=${form}: ${err?.message ?? err}. Event will be emitted unsigned with canonical_form retained.`
+        );
+      } catch {
+      }
+      return withForm;
     }
   }
   /**