@oobe-protocol-labs/synapse-sap-sdk 0.1.0

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

@@ -0,0 +1,323 @@
+/**
+ * @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

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