@oobe-protocol-labs/synapse-client-sdk 1.2.2 → 2.0.0

package/dist/esm/ai/sap/program.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @module ai/sap/program
+ * @description SAP — Instruction builder for the Solana Agent Protocol program.
+ *
+ * Creates `TransactionInstruction`-compatible objects for every SAP method:
+ * - `register`         — create a new agent PDA
+ * - `update`           — update agent capabilities, pricing, endpoint
+ * - `deactivate`       — mark agent as inactive
+ * - `updateReputation` — post new reputation metrics
+ *
+ * The user signs and sends the transaction via their wallet/signer.
+ *
+ * @example
+ * ```ts
+ * import { SAPInstructionBuilder } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const builder = new SAPInstructionBuilder({ programId: 'SAPAgnt1...' });
+ * const ix = builder.register({
+ *   walletPubkey: wallet.publicKey.toBase58(),
+ *   name: 'DeFi Oracle Agent',
+ *   description: 'Jupiter + Raydium tools',
+ *   capabilities: [{ id: 'jupiter:swap' }, { id: 'raydium:pool_info' }],
+ *   pricing: [{ tierId: 'standard', pricePerCall: 1000n, rateLimit: 10, maxCallsPerSession: 100, tokenType: 'USDC' }],
+ * });
+ * // ix is a TransactionInstruction — add to a transaction and sign
+ * ```
+ *
+ * @since 1.3.0
+ */
+import type { SAPConfig, SAPInstruction, RegisterAgentParams, UpdateAgentParams, UpdateReputationParams } from './types';
+import { type SAPValidatorConfig, type ValidationReport } from './validator';
+/**
+ * @description Error class for SAP instruction building failures.
+ * @since 1.3.0
+ */
+export declare class SAPProgramError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * @description Builds Solana transaction instructions for the SAP program.
+ *
+ * Each method returns an {@link SAPInstruction} object that can be added to a
+ * `Transaction` and signed with the agent's wallet.
+ *
+ * @since 1.3.0
+ */
+export declare class SAPInstructionBuilder {
+    private readonly programId;
+    private readonly validator;
+    private lastValidationReport;
+    /**
+     * @param {Partial<SAPConfig> & { validation?: SAPValidatorConfig }} [config] - Configuration with optional program ID and validation settings
+     */
+    constructor(config?: Partial<SAPConfig> & {
+        validation?: SAPValidatorConfig;
+    });
+    /**
+     * @description Get the validation report from the last `register()` or `update()` call.
+     * Returns `null` if no call has been made yet.
+     * @returns {ValidationReport | null}
+     * @since 1.4.0
+     */
+    getLastValidationReport(): ValidationReport | null;
+    /**
+     * @description Get the configured program ID.
+     * @returns {string} Program ID (base58)
+     */
+    getProgramId(): string;
+    /**
+     * @description Build a `register` instruction to create a new agent PDA.
+     *
+     * Account layout:
+     * 0. `[signer, writable]` Wallet (payer + authority)
+     * 1. `[writable]`         Agent PDA
+     * 2. `[]`                 System Program
+     *
+     * @param {RegisterAgentParams} params - Agent registration data
+     * @returns {SAPInstruction} Transaction instruction ready to sign
+     * @throws {SAPProgramError} If name or description exceeds size limits
+     *
+     * @example
+     * ```ts
+     * const ix = builder.register({
+     *   walletPubkey: 'ABcD...1234',
+     *   name: 'My Agent',
+     *   description: 'Provides DeFi tools',
+     *   capabilities: [{ id: 'jupiter:swap' }],
+     * });
+     * ```
+     *
+     * @since 1.3.0
+     */
+    register(params: RegisterAgentParams): SAPInstruction;
+    /**
+     * @description Build an `update` instruction to modify an existing agent PDA.
+     *
+     * Only provided fields are updated; omitted fields remain unchanged on-chain.
+     *
+     * Account layout:
+     * 0. `[signer]`   Wallet (authority)
+     * 1. `[writable]` Agent PDA
+     *
+     * @param {UpdateAgentParams} params - Fields to update
+     * @returns {SAPInstruction} Transaction instruction
+     *
+     * @example
+     * ```ts
+     * const ix = builder.update({
+     *   walletPubkey: 'ABcD...1234',
+     *   capabilities: [
+     *     { id: 'jupiter:swap' },
+     *     { id: 'raydium:pool_info' },
+     *     { id: 'metaplex:mint' },
+     *   ],
+     *   x402Endpoint: 'https://myagent.xyz/.well-known/x402',
+     * });
+     * ```
+     *
+     * @since 1.3.0
+     */
+    update(params: UpdateAgentParams): SAPInstruction;
+    /**
+     * @description Build a `deactivate` instruction to mark an agent as inactive.
+     *
+     * Account layout:
+     * 0. `[signer]`   Wallet (authority)
+     * 1. `[writable]` Agent PDA
+     *
+     * @param {string} walletPubkey - Agent's wallet public key (base58)
+     * @returns {SAPInstruction} Transaction instruction
+     *
+     * @since 1.3.0
+     */
+    deactivate(walletPubkey: string): SAPInstruction;
+    /**
+     * @description Build an `updateReputation` instruction.
+     *
+     * Typically called by the agent itself to self-report metrics, or by a
+     * trusted facilitator/oracle with delegated authority.
+     *
+     * Account layout:
+     * 0. `[signer]`   Wallet or authorized updater
+     * 1. `[writable]` Agent PDA
+     *
+     * @param {UpdateReputationParams} params - Reputation data to update
+     * @returns {SAPInstruction} Transaction instruction
+     *
+     * @since 1.3.0
+     */
+    updateReputation(params: UpdateReputationParams): SAPInstruction;
+}
+//# sourceMappingURL=program.d.ts.map

package/dist/esm/ai/sap/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../../../src/ai/sap/program.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EAEd,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAgB,KAAK,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAQ3F;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aACK,IAAI,EAAE,MAAM;gBAA7C,OAAO,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM;CAI1D;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,oBAAoB,CAAiC;IAE7D;;OAEG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,kBAAkB,CAAA;KAAE;IAK7E;;;;;OAKG;IACH,uBAAuB,IAAI,gBAAgB,GAAG,IAAI;IAIlD;;;OAGG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,cAAc;IAsBrD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,cAAc;IAmBjD;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc;IAchD;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,cAAc;CAsBjE"}

package/dist/esm/ai/sap/program.js

@@ -0,0 +1,222 @@
+/**
+ * @module ai/sap/program
+ * @description SAP — Instruction builder for the Solana Agent Protocol program.
+ *
+ * Creates `TransactionInstruction`-compatible objects for every SAP method:
+ * - `register`         — create a new agent PDA
+ * - `update`           — update agent capabilities, pricing, endpoint
+ * - `deactivate`       — mark agent as inactive
+ * - `updateReputation` — post new reputation metrics
+ *
+ * The user signs and sends the transaction via their wallet/signer.
+ *
+ * @example
+ * ```ts
+ * import { SAPInstructionBuilder } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const builder = new SAPInstructionBuilder({ programId: 'SAPAgnt1...' });
+ * const ix = builder.register({
+ *   walletPubkey: wallet.publicKey.toBase58(),
+ *   name: 'DeFi Oracle Agent',
+ *   description: 'Jupiter + Raydium tools',
+ *   capabilities: [{ id: 'jupiter:swap' }, { id: 'raydium:pool_info' }],
+ *   pricing: [{ tierId: 'standard', pricePerCall: 1000n, rateLimit: 10, maxCallsPerSession: 100, tokenType: 'USDC' }],
+ * });
+ * // ix is a TransactionInstruction — add to a transaction and sign
+ * ```
+ *
+ * @since 1.3.0
+ */
+import { SAP_DEFAULT_PROGRAM_ID, SAP_INSTRUCTION_DISCRIMINATORS } from './types.js';
+import { deriveAgentPDA, BorshWriter, serializeRegisterData, serializeUpdateData } from './pda.js';
+import { SAPValidator } from './validator.js';
+/**
+ * @description Solana system program ID.
+ * @since 1.3.0
+ */
+const SYSTEM_PROGRAM_ID = '11111111111111111111111111111111';
+/**
+ * @description Error class for SAP instruction building failures.
+ * @since 1.3.0
+ */
+export class SAPProgramError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'SAPProgramError';
+    }
+}
+/**
+ * @description Builds Solana transaction instructions for the SAP program.
+ *
+ * Each method returns an {@link SAPInstruction} object that can be added to a
+ * `Transaction` and signed with the agent's wallet.
+ *
+ * @since 1.3.0
+ */
+export class SAPInstructionBuilder {
+    programId;
+    validator;
+    lastValidationReport = null;
+    /**
+     * @param {Partial<SAPConfig> & { validation?: SAPValidatorConfig }} [config] - Configuration with optional program ID and validation settings
+     */
+    constructor(config) {
+        this.programId = config?.programId ?? SAP_DEFAULT_PROGRAM_ID;
+        this.validator = new SAPValidator(config?.validation);
+    }
+    /**
+     * @description Get the validation report from the last `register()` or `update()` call.
+     * Returns `null` if no call has been made yet.
+     * @returns {ValidationReport | null}
+     * @since 1.4.0
+     */
+    getLastValidationReport() {
+        return this.lastValidationReport;
+    }
+    /**
+     * @description Get the configured program ID.
+     * @returns {string} Program ID (base58)
+     */
+    getProgramId() {
+        return this.programId;
+    }
+    /**
+     * @description Build a `register` instruction to create a new agent PDA.
+     *
+     * Account layout:
+     * 0. `[signer, writable]` Wallet (payer + authority)
+     * 1. `[writable]`         Agent PDA
+     * 2. `[]`                 System Program
+     *
+     * @param {RegisterAgentParams} params - Agent registration data
+     * @returns {SAPInstruction} Transaction instruction ready to sign
+     * @throws {SAPProgramError} If name or description exceeds size limits
+     *
+     * @example
+     * ```ts
+     * const ix = builder.register({
+     *   walletPubkey: 'ABcD...1234',
+     *   name: 'My Agent',
+     *   description: 'Provides DeFi tools',
+     *   capabilities: [{ id: 'jupiter:swap' }],
+     * });
+     * ```
+     *
+     * @since 1.3.0
+     */
+    register(params) {
+        // Deep validation (replaces basic name/desc checks)
+        this.lastValidationReport = this.validator.validateRegistration(params);
+        const pda = deriveAgentPDA(params.walletPubkey, this.programId);
+        const instructionData = serializeRegisterData(params);
+        // Prepend discriminator + bump
+        const data = new Uint8Array(SAP_INSTRUCTION_DISCRIMINATORS.register.length + 1 + instructionData.length);
+        data.set(SAP_INSTRUCTION_DISCRIMINATORS.register, 0);
+        data[8] = pda.bump;
+        data.set(instructionData, 9);
+        const keys = [
+            { pubkey: params.walletPubkey, isSigner: true, isWritable: true },
+            { pubkey: pda.address, isSigner: false, isWritable: true },
+            { pubkey: SYSTEM_PROGRAM_ID, isSigner: false, isWritable: false },
+        ];
+        return { programId: this.programId, keys, data };
+    }
+    /**
+     * @description Build an `update` instruction to modify an existing agent PDA.
+     *
+     * Only provided fields are updated; omitted fields remain unchanged on-chain.
+     *
+     * Account layout:
+     * 0. `[signer]`   Wallet (authority)
+     * 1. `[writable]` Agent PDA
+     *
+     * @param {UpdateAgentParams} params - Fields to update
+     * @returns {SAPInstruction} Transaction instruction
+     *
+     * @example
+     * ```ts
+     * const ix = builder.update({
+     *   walletPubkey: 'ABcD...1234',
+     *   capabilities: [
+     *     { id: 'jupiter:swap' },
+     *     { id: 'raydium:pool_info' },
+     *     { id: 'metaplex:mint' },
+     *   ],
+     *   x402Endpoint: 'https://myagent.xyz/.well-known/x402',
+     * });
+     * ```
+     *
+     * @since 1.3.0
+     */
+    update(params) {
+        // Deep validation
+        this.lastValidationReport = this.validator.validateUpdate(params);
+        const pda = deriveAgentPDA(params.walletPubkey, this.programId);
+        const instructionData = serializeUpdateData(params);
+        const data = new Uint8Array(SAP_INSTRUCTION_DISCRIMINATORS.update.length + instructionData.length);
+        data.set(SAP_INSTRUCTION_DISCRIMINATORS.update, 0);
+        data.set(instructionData, 8);
+        const keys = [
+            { pubkey: params.walletPubkey, isSigner: true, isWritable: false },
+            { pubkey: pda.address, isSigner: false, isWritable: true },
+        ];
+        return { programId: this.programId, keys, data };
+    }
+    /**
+     * @description Build a `deactivate` instruction to mark an agent as inactive.
+     *
+     * Account layout:
+     * 0. `[signer]`   Wallet (authority)
+     * 1. `[writable]` Agent PDA
+     *
+     * @param {string} walletPubkey - Agent's wallet public key (base58)
+     * @returns {SAPInstruction} Transaction instruction
+     *
+     * @since 1.3.0
+     */
+    deactivate(walletPubkey) {
+        const pda = deriveAgentPDA(walletPubkey, this.programId);
+        const data = new Uint8Array(SAP_INSTRUCTION_DISCRIMINATORS.deactivate.length);
+        data.set(SAP_INSTRUCTION_DISCRIMINATORS.deactivate, 0);
+        const keys = [
+            { pubkey: walletPubkey, isSigner: true, isWritable: false },
+            { pubkey: pda.address, isSigner: false, isWritable: true },
+        ];
+        return { programId: this.programId, keys, data };
+    }
+    /**
+     * @description Build an `updateReputation` instruction.
+     *
+     * Typically called by the agent itself to self-report metrics, or by a
+     * trusted facilitator/oracle with delegated authority.
+     *
+     * Account layout:
+     * 0. `[signer]`   Wallet or authorized updater
+     * 1. `[writable]` Agent PDA
+     *
+     * @param {UpdateReputationParams} params - Reputation data to update
+     * @returns {SAPInstruction} Transaction instruction
+     *
+     * @since 1.3.0
+     */
+    updateReputation(params) {
+        const pda = deriveAgentPDA(params.walletPubkey, this.programId);
+        const w = new BorshWriter();
+        w.writeOption(params.totalCallsServed, (v) => w.writeU64(v));
+        w.writeOption(params.avgLatencyMs, (v) => w.writeU32(v));
+        w.writeOption(params.uptimePercent, (v) => w.writeU8(v));
+        w.writeOption(params.score, (v) => w.writeU32(v));
+        const instructionData = w.toBytes();
+        const data = new Uint8Array(SAP_INSTRUCTION_DISCRIMINATORS.updateReputation.length + instructionData.length);
+        data.set(SAP_INSTRUCTION_DISCRIMINATORS.updateReputation, 0);
+        data.set(instructionData, 8);
+        const keys = [
+            { pubkey: params.walletPubkey, isSigner: true, isWritable: false },
+            { pubkey: pda.address, isSigner: false, isWritable: true },
+        ];
+        return { programId: this.programId, keys, data };
+    }
+}
+//# sourceMappingURL=program.js.map

package/dist/esm/ai/sap/program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.js","sourceRoot":"","sources":["../../../../src/ai/sap/program.ts"],"names":[],"mappings":"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"}

package/dist/esm/ai/sap/registry.d.ts

@@ -0,0 +1,218 @@
+/**
+ * @module ai/sap/registry
+ * @description SAP — Canonical capability registry for the agent sub-network.
+ *
+ * Defines the **standard capability catalog** — every protocol/method pair
+ * that SAP-registered agents can advertise. This gives the network a shared
+ * vocabulary so discovery queries are reliable and unambiguous.
+ *
+ * Capabilities follow the `protocol:method` convention (e.g. `jupiter:swap`).
+ * Each entry carries metadata: human description, category, expected I/O
+ * schema hints, and minimum version.
+ *
+ * @example
+ * ```ts
+ * import { SAPCapabilityRegistry } from '@oobe-protocol-labs/synapse-client-sdk/ai/sap';
+ *
+ * const reg = SAPCapabilityRegistry.default();
+ *
+ * // List everything Jupiter supports
+ * const jupiterCaps = reg.byProtocol('jupiter');
+ *
+ * // Check if a capability ID is known
+ * const valid = reg.has('jupiter:swap');          // true
+ * const unknown = reg.has('made_up:blah');        // false
+ *
+ * // All capabilities in the 'defi' category
+ * const defi = reg.byCategory('defi');
+ *
+ * // Full catalog
+ * const all = reg.list();
+ * ```
+ *
+ * @since 1.4.0
+ */
+/**
+ * @description Category of a registered capability.
+ * @since 1.4.0
+ */
+export type CapabilityCategory = 'defi' | 'nft' | 'data' | 'ai' | 'governance' | 'payments' | 'identity' | 'infrastructure' | 'oracle' | 'social' | 'custom';
+/**
+ * @description Schema hint describing expected input/output for a capability.
+ * Not a full JSON-Schema — just enough for agents to negotiate compatibility.
+ * @since 1.4.0
+ */
+export interface CapabilityIOSchema {
+    /** Short key-type pairs, e.g. `{ inputMint: 'string', amount: 'bigint' }` */
+    fields: Record<string, 'string' | 'number' | 'bigint' | 'boolean' | 'bytes' | 'object'>;
+}
+/**
+ * @description Full metadata for a registered capability.
+ * @since 1.4.0
+ */
+export interface CapabilityDefinition {
+    /** Canonical ID (`protocol:method`). */
+    id: string;
+    /** Protocol namespace (e.g. `jupiter`). */
+    protocol: string;
+    /** Human-readable description. */
+    description: string;
+    /** Functional category. */
+    category: CapabilityCategory;
+    /** Minimum version that supports this capability. */
+    minVersion?: string;
+    /** Expected input schema. */
+    input?: CapabilityIOSchema;
+    /** Expected output schema. */
+    output?: CapabilityIOSchema;
+    /** Related capability IDs (often used together). */
+    relatedCapabilities?: string[];
+    /** Whether this is a critical/core capability. */
+    isCritical?: boolean;
+    /** Deprecation notice (if any). */
+    deprecated?: string;
+}
+/**
+ * @description Canonical catalog of capabilities for the SAP agent network.
+ *
+ * Provides lookup / filtering by ID, protocol, category, and supports
+ * custom registrations so third-party protocols can extend the catalog
+ * at runtime.
+ *
+ * @since 1.4.0
+ */
+export declare class SAPCapabilityRegistry {
+    private readonly capabilities;
+    /**
+     * @param {CapabilityDefinition[]} [initial] - Seed capabilities
+     */
+    constructor(initial?: CapabilityDefinition[]);
+    /**
+     * @description Create a registry pre-loaded with all default (known) capabilities.
+     * @returns {SAPCapabilityRegistry}
+     * @since 1.4.0
+     */
+    static default(): SAPCapabilityRegistry;
+    /**
+     * @description Create an empty registry (for testing or fully custom setups).
+     * @returns {SAPCapabilityRegistry}
+     * @since 1.4.0
+     */
+    static empty(): SAPCapabilityRegistry;
+    /**
+     * @description Register a new capability (or overwrite an existing one).
+     * @param {CapabilityDefinition} def - Capability definition
+     * @since 1.4.0
+     */
+    register(def: CapabilityDefinition): void;
+    /**
+     * @description Register multiple capabilities at once.
+     * @param {CapabilityDefinition[]} defs - Capability definitions
+     * @since 1.4.0
+     */
+    registerMany(defs: CapabilityDefinition[]): void;
+    /**
+     * @description Remove a capability from the registry.
+     * @param {string} id - Capability ID
+     * @returns {boolean} `true` if the capability was found and removed
+     * @since 1.4.0
+     */
+    remove(id: string): boolean;
+    /**
+     * @description Check if a capability ID is registered.
+     * @param {string} id - Capability ID (e.g. `"jupiter:swap"`)
+     * @returns {boolean}
+     * @since 1.4.0
+     */
+    has(id: string): boolean;
+    /**
+     * @description Get a single capability by ID.
+     * @param {string} id - Capability ID
+     * @returns {CapabilityDefinition | undefined}
+     * @since 1.4.0
+     */
+    get(id: string): CapabilityDefinition | undefined;
+    /**
+     * @description List all registered capabilities.
+     * @returns {CapabilityDefinition[]}
+     * @since 1.4.0
+     */
+    list(): CapabilityDefinition[];
+    /**
+     * @description Get all registered capability IDs.
+     * @returns {string[]}
+     * @since 1.4.0
+     */
+    ids(): string[];
+    /**
+     * @description Total number of registered capabilities.
+     * @returns {number}
+     * @since 1.4.0
+     */
+    get size(): number;
+    /**
+     * @description Get all capabilities for a given protocol.
+     * @param {string} protocol - Protocol name (e.g. `"jupiter"`)
+     * @returns {CapabilityDefinition[]}
+     * @since 1.4.0
+     */
+    byProtocol(protocol: string): CapabilityDefinition[];
+    /**
+     * @description Get all capabilities in a given category.
+     * @param {CapabilityCategory} category
+     * @returns {CapabilityDefinition[]}
+     * @since 1.4.0
+     */
+    byCategory(category: CapabilityCategory): CapabilityDefinition[];
+    /**
+     * @description Get all unique protocol names.
+     * @returns {string[]}
+     * @since 1.4.0
+     */
+    protocols(): string[];
+    /**
+     * @description Get all unique categories in use.
+     * @returns {CapabilityCategory[]}
+     * @since 1.4.0
+     */
+    categories(): CapabilityCategory[];
+    /**
+     * @description Search capabilities by free-text query (matches id, description, protocol).
+     * @param {string} query - Search text (case-insensitive)
+     * @returns {CapabilityDefinition[]}
+     * @since 1.4.0
+     */
+    search(query: string): CapabilityDefinition[];
+    /**
+     * @description Get all critical (core) capabilities.
+     * @returns {CapabilityDefinition[]}
+     * @since 1.4.0
+     */
+    critical(): CapabilityDefinition[];
+    /**
+     * @description Get deprecated capabilities.
+     * @returns {CapabilityDefinition[]}
+     * @since 1.4.0
+     */
+    deprecated(): CapabilityDefinition[];
+    /**
+     * @description Validate a list of capability IDs against the registry.
+     * Returns unknown IDs (not registered) — useful during agent registration.
+     * @param {string[]} ids - Capability IDs to check
+     * @returns {{ known: string[]; unknown: string[]; deprecated: string[] }}
+     * @since 1.4.0
+     */
+    validate(ids: string[]): {
+        known: string[];
+        unknown: string[];
+        deprecated: string[];
+    };
+    /**
+     * @description Get the dependency graph: which capabilities are frequently used together.
+     * @param {string} id - Root capability ID
+     * @returns {string[]} Related capability IDs (transitive, max 2 levels)
+     * @since 1.4.0
+     */
+    relatedGraph(id: string): string[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/esm/ai/sap/registry.d.ts.map

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