@oobe-protocol-labs/synapse-sap-sdk 0.13.0 → 0.14.0

package/dist/types/registries/session.d.ts

@@ -1,323 +0,0 @@
-/**
- * @module registries/session
- * @description Unified session lifecycle manager.
- *
- * Wraps the vault + ledger modules into a single cohesive API
- * that manages the full memory session lifecycle:
- *   1. Ensure vault exists (create if needed)
- *   2. Open a named session
- *   3. Initialize a ledger for the session
- *   4. Write data (ring buffer + TX log)
- *   5. Read latest entries from ring buffer
- *   6. Seal the ring buffer into permanent archive pages
- *   7. Close ledger + session when done
- *
- * This is the RECOMMENDED way to manage agent memory.
- *
- * @category Registries
- * @since v0.1.0
- *
- * @example
- * ```ts
- * const session = client.session;
- *
- * // Start a new conversation session
- * const ctx = await session.start("conversation-123");
- *
- * // Write messages
- * await session.write(ctx, "Hello from the agent");
- * await session.write(ctx, "Processing your request...");
- *
- * // Read latest messages from ring buffer
- * const messages = await session.readLatest(ctx);
- *
- * // Seal into permanent archive
- * await session.seal(ctx);
- *
- * // Close when done
- * await session.close(ctx);
- * ```
- */
-import { type PublicKey, type TransactionSignature } from "@solana/web3.js";
-import type { SapProgram } from "../modules/base";
-/**
- * @interface SessionContext
- * @name SessionContext
- * @description Resolved session context with all derived PDAs.
- * Created by {@link SessionManager.deriveContext} or {@link SessionManager.start}.
- * Contains the human-readable session ID, SHA-256 hash, and all
- * PDA addresses needed for session operations.
- * @category Registries
- * @since v0.1.0
- */
-export interface SessionContext {
-    /** Human-readable session identifier. */
-    readonly sessionId: string;
-    /** SHA-256 of the session ID. */
-    readonly sessionHash: Uint8Array;
-    /** Session hash as number[] for instruction args. */
-    readonly sessionHashArray: number[];
-    /** Agent PDA. */
-    readonly agentPda: PublicKey;
-    /** Memory vault PDA. */
-    readonly vaultPda: PublicKey;
-    /** Session ledger PDA. */
-    readonly sessionPda: PublicKey;
-    /** Memory ledger PDA (unified ring buffer). */
-    readonly ledgerPda: PublicKey;
-    /** Wallet public key. */
-    readonly wallet: PublicKey;
-}
-/**
- * @interface WriteResult
- * @name WriteResult
- * @description Result of writing data to a session via {@link SessionManager.write}.
- * Contains the transaction signature, content hash, and data size.
- * @category Registries
- * @since v0.1.0
- */
-export interface WriteResult {
-    /** Transaction signature. */
-    readonly txSignature: TransactionSignature;
-    /** Content hash of the written data. */
-    readonly contentHash: number[];
-    /** Data size in bytes. */
-    readonly dataSize: number;
-}
-/**
- * @interface SealResult
- * @name SealResult
- * @description Result of sealing the ring buffer into a permanent archive page
- * via {@link SessionManager.seal}.
- * @category Registries
- * @since v0.1.0
- */
-export interface SealResult {
-    /** Transaction signature. */
-    readonly txSignature: TransactionSignature;
-    /** Page index of the sealed archive. */
-    readonly pageIndex: number;
-}
-/**
- * @interface RingBufferEntry
- * @name RingBufferEntry
- * @description Decoded ring buffer entry from the on-chain memory ledger.
- * Contains raw bytes, UTF-8 text representation, and byte size.
- * @category Registries
- * @since v0.1.0
- */
-export interface RingBufferEntry {
-    /** Raw data bytes. */
-    readonly data: Uint8Array;
-    /** Data decoded as UTF-8 string (if applicable). */
-    readonly text: string;
-    /** Size in bytes. */
-    readonly size: number;
-}
-/**
- * @interface SessionStatus
- * @name SessionStatus
- * @description Full session status including vault, session, and ledger state.
- * Returned by {@link SessionManager.getStatus}.
- * @category Registries
- * @since v0.1.0
- */
-export interface SessionStatus {
-    /** Whether the vault exists. */
-    readonly vaultExists: boolean;
-    /** Whether the session exists. */
-    readonly sessionExists: boolean;
-    /** Whether the ledger exists. */
-    readonly ledgerExists: boolean;
-    /** Whether the session is closed. */
-    readonly isClosed: boolean;
-    /** Total entries written to the ledger. */
-    readonly totalEntries: number;
-    /** Total data size in bytes. */
-    readonly totalDataSize: string;
-    /** Number of sealed archive pages. */
-    readonly numPages: number;
-    /** Merkle root hex string. */
-    readonly merkleRoot: string;
-}
-/**
- * @name SessionManager
- * @description Unified session lifecycle manager for agent memory.
- *
- * Wraps vault + ledger modules into a single API that manages
- * the full memory session lifecycle: create vault, open session,
- * write data, read ring buffer, seal archives, and close sessions.
- *
- * @category Registries
- * @since v0.1.0
- *
- * @example
- * ```ts
- * const session = client.session;
- * const ctx = await session.start("conversation-123");
- * await session.write(ctx, "Hello from the agent");
- * const entries = await session.readLatest(ctx);
- * await session.seal(ctx);
- * await session.close(ctx);
- * ```
- */
-export declare class SessionManager {
-    private readonly program;
-    private readonly wallet;
-    constructor(program: SapProgram);
-    /**
-     * @name deriveContext
-     * @description Derive all PDAs for a session without creating anything.
-     * Pure computation — no network calls.
-     *
-     * @param sessionId - Human-readable session identifier (hashed for PDA derivation).
-     * @returns A {@link SessionContext} with all resolved PDAs.
-     * @since v0.1.0
-     */
-    deriveContext(sessionId: string): SessionContext;
-    /**
-     * @name start
-     * @description Start a new session: ensures vault exists, opens session,
-     * and initializes a ledger. Idempotent — skips any step
-     * that’s already done.
-     *
-     * @param sessionId - Human-readable session name (hashed for PDA).
-     * @param vaultNonce - Optional 32-byte nonce for vault init (only used if vault doesn’t exist).
-     * @returns A {@link SessionContext} with all resolved PDAs.
-     * @since v0.1.0
-     */
-    start(sessionId: string, vaultNonce?: number[]): Promise<SessionContext>;
-    /**
-     * @name write
-     * @description Write data to a session (ring buffer + permanent TX log).
-     * Cost: TX fee only (~0.000005 SOL per write).
-     *
-     * @param ctx - Session context from {@link SessionManager.start} or {@link SessionManager.deriveContext}.
-     * @param data - UTF-8 string or raw bytes to write.
-     * @returns A {@link WriteResult} with the transaction signature, content hash, and data size.
-     * @since v0.1.0
-     */
-    write(ctx: SessionContext, data: string | Buffer | Uint8Array): Promise<WriteResult>;
-    /**
-     * @name readLatest
-     * @description Read the latest entries from the ring buffer.
-     * FREE — uses `getAccountInfo()` on any RPC (no archival needed).
-     *
-     * @param ctx - Session context.
-     * @returns An array of {@link RingBufferEntry} from the current ring buffer.
-     * @since v0.1.0
-     */
-    readLatest(ctx: SessionContext): Promise<RingBufferEntry[]>;
-    /**
-     * @name seal
-     * @description Seal the ring buffer into a permanent LedgerPage.
-     * Creates a write-once, never-delete archive (~0.031 SOL per page).
-     *
-     * @param ctx - Session context.
-     * @returns A {@link SealResult} with the transaction signature and page index.
-     * @since v0.1.0
-     */
-    seal(ctx: SessionContext): Promise<SealResult>;
-    /**
-     * @name closeLedger
-     * @description Close the ledger and reclaim ~0.032 SOL rent.
-     *
-     * @param ctx - Session context.
-     * @returns The transaction signature.
-     * @since v0.1.0
-     */
-    closeLedger(ctx: SessionContext): Promise<TransactionSignature>;
-    /**
-     * @name closeSession
-     * @description Close the session (no more writes allowed).
-     *
-     * @param ctx - Session context.
-     * @returns The transaction signature.
-     * @since v0.1.0
-     */
-    closeSession(ctx: SessionContext): Promise<TransactionSignature>;
-    /**
-     * @name close
-     * @description Full session teardown: close ledger → close session.
-     * Reclaims all rent. Idempotent — skips steps already done.
-     *
-     * @param ctx - Session context.
-     * @returns Resolves when the session is fully closed.
-     * @since v0.1.0
-     */
-    close(ctx: SessionContext): Promise<void>;
-    /**
-     * @name getStatus
-     * @description Get the full status of a session.
-     * Returns vault/session/ledger existence, closure state, and metrics.
-     *
-     * @param ctx - Session context.
-     * @returns A {@link SessionStatus} with all session state information.
-     * @since v0.1.0
-     */
-    getStatus(ctx: SessionContext): Promise<SessionStatus>;
-    /**
-     * @name readPage
-     * @description Read a sealed archive page by index.
-     *
-     * @param ctx - Session context.
-     * @param pageIndex - Zero-based index of the sealed page.
-     * @returns An array of {@link RingBufferEntry} from the sealed page.
-     * @since v0.1.0
-     */
-    readPage(ctx: SessionContext, pageIndex: number): Promise<RingBufferEntry[]>;
-    /**
-     * @name readAll
-     * @description Read ALL data: ring buffer (latest) + all sealed pages (history).
-     * Returns entries in chronological order (oldest first).
-     *
-     * @param ctx - Session context.
-     * @returns An array of all {@link RingBufferEntry} in chronological order.
-     * @since v0.1.0
-     */
-    readAll(ctx: SessionContext): Promise<RingBufferEntry[]>;
-    /**
-     * @name decodeRingBuffer
-     * @description Decode a raw ring buffer byte array into structured entries.
-     * Parses length-prefixed (u16 LE) entries from the byte stream.
-     * @param ring - Raw ring buffer bytes.
-     * @returns An array of decoded {@link RingBufferEntry}.
-     * @private
-     */
-    private decodeRingBuffer;
-    /**
-     * @name accountExists
-     * @description Check if an on-chain account exists at the given PDA.
-     * @param pda - Account public key to check.
-     * @returns `true` if the account exists, `false` otherwise.
-     * @private
-     */
-    private accountExists;
-    /**
-     * @name methods
-     * @description Accessor for the Anchor program methods namespace.
-     * @returns The program methods object for building RPC calls.
-     * @private
-     */
-    private get methods();
-    /**
-     * @name fetch
-     * @description Fetch an on-chain account by name and PDA. Throws if not found.
-     * @param name - Anchor account discriminator name.
-     * @param pda - Account public key to fetch.
-     * @returns The deserialized account data.
-     * @throws If the account does not exist.
-     * @private
-     */
-    private fetch;
-    /**
-     * @name fetchNullable
-     * @description Fetch an on-chain account by name and PDA. Returns `null` if not found.
-     * @param name - Anchor account discriminator name.
-     * @param pda - Account public key to fetch.
-     * @returns The deserialized account data, or `null` if the account does not exist.
-     * @private
-     */
-    private fetchNullable;
-}
-//# sourceMappingURL=session.d.ts.map

package/dist/types/registries/session.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/registries/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAoBlD;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,qDAAqD;IACrD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IACpC,iBAAiB;IACjB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,wBAAwB;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,yBAAyB;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,wCAAwC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAC/B,0BAA0B;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,iCAAiC;IACjC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gCAAgC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,cAAc;IAGb,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;gBAEN,OAAO,EAAE,UAAU;IAMhD;;;;;;;;OAQG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc;IAqBhD;;;;;;;;;;OAUG;IACG,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,cAAc,CAAC;IAmD1B;;;;;;;;;OASG;IACG,KAAK,CACT,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GACjC,OAAO,CAAC,WAAW,CAAC;IAqBvB;;;;;;;;OAQG;IACG,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAUjE;;;;;;;;OAQG;IACG,IAAI,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IAsBpD;;;;;;;OAOG;IACG,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAWrE;;;;;;;OAOG;IACG,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAWtE;;;;;;;;OAQG;IACG,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB/C;;;;;;;;OAQG;IACG,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAqB5D;;;;;;;;OAQG;IACG,QAAQ,CACZ,GAAG,EAAE,cAAc,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,EAAE,CAAC;IAM7B;;;;;;;;OAQG;IACG,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAwB9D;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;;;;;OAMG;YACW,aAAa;IAK3B;;;;;OAKG;IAEH,OAAO,KAAK,OAAO,GAGlB;IAED;;;;;;;;OAQG;YAEW,KAAK;IAKnB;;;;;;;OAOG;YAEW,aAAa;CAI5B"}