agentvault 1.0.2 → 1.0.5

package/dist/src/packaging/state-format.d.ts

@@ -0,0 +1,332 @@
+/**
+ * State Serialization Format
+ *
+ * This module defines the canonical state serialization format for AgentVault.
+ * It supports versioning, integrity verification, and efficient storage in ICP canisters.
+ *
+ * Design Goals:
+ * - Deterministic serialization for reproducible builds
+ * - Schema versioning for forward/backward compatibility
+ * - Integrity verification via checksums
+ * - Efficient binary encoding for canister storage
+ * - Support for incremental state updates (deltas)
+ */
+import type { AgentConfig, AgentType } from './types.js';
+import type { Memory, Task } from './serializer.js';
+/**
+ * Current format version following semver
+ * Major: Breaking changes to format structure
+ * Minor: Backward-compatible additions
+ * Patch: Bug fixes in serialization logic
+ */
+export declare const STATE_FORMAT_VERSION = "1.0.0";
+/**
+ * Schema URL pattern for JSON Schema validation
+ */
+export declare const SCHEMA_URL_PATTERN = "https://agentvault.dev/schemas/state-v{version}.json";
+/**
+ * Magic bytes to identify AgentVault state files
+ * "AVST" in ASCII (AgentVault STate)
+ */
+export declare const STATE_MAGIC_BYTES: Uint8Array<ArrayBuffer>;
+/**
+ * Supported encoding formats for state data
+ */
+export type StateEncoding = 'json' | 'cbor' | 'msgpack';
+/**
+ * State entry types for typed state data
+ */
+export type StateEntryType = 'memory' | 'task' | 'context' | 'config' | 'checkpoint' | 'custom';
+/**
+ * State header containing metadata about the serialized state
+ */
+export interface StateHeader {
+    /** Format version (semver) */
+    version: string;
+    /** Schema URL for validation */
+    schema: string;
+    /** Encoding format used for the payload */
+    encoding: StateEncoding;
+    /** SHA-256 checksum of the payload (hex) */
+    checksum: string;
+    /** Timestamp of serialization (ISO 8601) */
+    timestamp: string;
+    /** Unique state ID for tracking */
+    stateId: string;
+    /** Previous state ID for delta chains (optional) */
+    previousStateId?: string;
+    /** Compression algorithm used (optional) */
+    compression?: 'none' | 'gzip' | 'lz4';
+    /** Original size before compression (bytes) */
+    originalSize: number;
+    /** Compressed size (bytes, same as originalSize if no compression) */
+    compressedSize: number;
+}
+/**
+ * Agent identity information
+ */
+export interface AgentIdentity {
+    /** Agent name */
+    name: string;
+    /** Agent type */
+    type: AgentType;
+    /** Agent version */
+    version: string;
+    /** Unique agent ID (derived from name and type) */
+    agentId: string;
+    /** Optional description */
+    description?: string;
+}
+/**
+ * Source metadata for reconstruction
+ */
+export interface SourceMetadata {
+    /** Original source path */
+    sourcePath: string;
+    /** Entry point file */
+    entryPoint?: string;
+    /** Source files hash for verification */
+    sourceHash?: string;
+    /** Git commit hash if available */
+    gitCommit?: string;
+    /** Git branch if available */
+    gitBranch?: string;
+}
+/**
+ * Runtime state data
+ */
+export interface RuntimeState {
+    /** Whether the agent has been initialized */
+    initialized: boolean;
+    /** Agent memories */
+    memories: Memory[];
+    /** Agent task queue */
+    tasks: Task[];
+    /** Runtime context key-value pairs */
+    context: Record<string, unknown>;
+    /** Custom state extensions */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * State statistics for monitoring
+ */
+export interface StateStats {
+    /** Total number of memories */
+    memoryCount: number;
+    /** Total number of tasks */
+    taskCount: number;
+    /** Number of completed tasks */
+    completedTaskCount: number;
+    /** Number of context entries */
+    contextEntryCount: number;
+    /** Total state size in bytes */
+    totalSize: number;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last modification timestamp */
+    lastModifiedAt: string;
+}
+/**
+ * Delta operation types for incremental updates
+ */
+export type DeltaOperation = 'add' | 'update' | 'remove';
+/**
+ * Delta entry for incremental state updates
+ */
+export interface DeltaEntry {
+    /** Type of operation */
+    operation: DeltaOperation;
+    /** Path to the changed field (dot notation) */
+    path: string;
+    /** Entry type being modified */
+    entryType: StateEntryType;
+    /** New value (for add/update) */
+    value?: unknown;
+    /** Previous value (for update/remove) */
+    previousValue?: unknown;
+    /** Timestamp of the change */
+    timestamp: string;
+}
+/**
+ * Delta state for incremental updates
+ */
+export interface StateDelta {
+    /** Base state ID this delta applies to */
+    baseStateId: string;
+    /** New state ID after applying delta */
+    newStateId: string;
+    /** List of changes */
+    entries: DeltaEntry[];
+    /** Timestamp of delta creation */
+    timestamp: string;
+}
+/**
+ * Complete serialized state format (JSON representation)
+ */
+export interface SerializedStateV1 {
+    /** State header with metadata */
+    header: StateHeader;
+    /** Agent identity */
+    agent: AgentIdentity;
+    /** Source metadata for reconstruction */
+    source: SourceMetadata;
+    /** Runtime state data */
+    state: RuntimeState;
+    /** Statistics about the state */
+    stats: StateStats;
+}
+/**
+ * Binary state format header (fixed 64 bytes)
+ * Used for canister storage optimization
+ */
+export interface BinaryStateHeader {
+    /** Magic bytes (4 bytes) */
+    magic: Uint8Array;
+    /** Version major (2 bytes) */
+    versionMajor: number;
+    /** Version minor (2 bytes) */
+    versionMinor: number;
+    /** Version patch (2 bytes) */
+    versionPatch: number;
+    /** Encoding type (1 byte): 0=json, 1=cbor, 2=msgpack */
+    encoding: number;
+    /** Compression type (1 byte): 0=none, 1=gzip, 2=lz4 */
+    compression: number;
+    /** Flags (4 bytes): bit flags for options */
+    flags: number;
+    /** Checksum (32 bytes): SHA-256 of payload */
+    checksum: Uint8Array;
+    /** Payload size (8 bytes): uint64 */
+    payloadSize: bigint;
+    /** Reserved (8 bytes): for future use */
+    reserved: Uint8Array;
+}
+/**
+ * State format options for serialization
+ */
+export interface StateFormatOptions {
+    /** Encoding format (default: 'json') */
+    encoding?: StateEncoding;
+    /** Compression algorithm (default: 'none') */
+    compression?: 'none' | 'gzip' | 'lz4';
+    /** Pretty print JSON (default: false for efficiency) */
+    prettyPrint?: boolean;
+    /** Include statistics (default: true) */
+    includeStats?: boolean;
+    /** Include source metadata (default: true) */
+    includeSource?: boolean;
+    /** Generate delta from previous state */
+    previousState?: SerializedStateV1;
+}
+/**
+ * State validation result
+ */
+export interface StateValidationResult {
+    /** Whether the state is valid */
+    valid: boolean;
+    /** Validation errors */
+    errors: StateValidationError[];
+    /** Validation warnings */
+    warnings: string[];
+    /** Checksum verified */
+    checksumValid: boolean;
+    /** Version compatible */
+    versionCompatible: boolean;
+}
+/**
+ * State validation error
+ */
+export interface StateValidationError {
+    /** Error code */
+    code: string;
+    /** Error message */
+    message: string;
+    /** Path to the invalid field */
+    path?: string;
+    /** Expected value or type */
+    expected?: string;
+    /** Actual value or type */
+    actual?: string;
+}
+/**
+ * Generate a unique state ID
+ */
+export declare function generateStateId(): string;
+/**
+ * Generate an agent ID from name and type
+ */
+export declare function generateAgentId(name: string, type: AgentType): string;
+/**
+ * Parse version string into components
+ */
+export declare function parseVersion(version: string): {
+    major: number;
+    minor: number;
+    patch: number;
+};
+/**
+ * Check if a version is compatible with the current format
+ * Compatible if major version matches and minor version is <= current
+ */
+export declare function isVersionCompatible(version: string): boolean;
+/**
+ * Calculate SHA-256 checksum of data
+ */
+export declare function calculateChecksum(data: string | Uint8Array): Promise<string>;
+/**
+ * Create state header
+ */
+export declare function createStateHeader(payload: string, options?: StateFormatOptions): Promise<StateHeader>;
+/**
+ * Create agent identity from config
+ */
+export declare function createAgentIdentity(config: AgentConfig): AgentIdentity;
+/**
+ * Create source metadata from config
+ */
+export declare function createSourceMetadata(config: AgentConfig): SourceMetadata;
+/**
+ * Calculate state statistics
+ */
+export declare function calculateStateStats(state: RuntimeState): StateStats;
+/**
+ * Create a serialized state object
+ */
+export declare function createSerializedState(config: AgentConfig, runtimeState: RuntimeState, options?: StateFormatOptions): Promise<SerializedStateV1>;
+/**
+ * Serialize state to JSON string
+ */
+export declare function serializeStateToJson(config: AgentConfig, runtimeState: RuntimeState, options?: StateFormatOptions): Promise<string>;
+/**
+ * Deserialize state from JSON string
+ */
+export declare function deserializeStateFromJson(json: string): SerializedStateV1;
+/**
+ * Validate a serialized state
+ */
+export declare function validateSerializedState(state: SerializedStateV1): Promise<StateValidationResult>;
+/**
+ * Create binary state header (64 bytes fixed size)
+ */
+export declare function createBinaryHeader(header: StateHeader): Uint8Array;
+/**
+ * Parse binary state header (64 bytes)
+ */
+export declare function parseBinaryHeader(data: Uint8Array): BinaryStateHeader | null;
+/**
+ * Serialize state to binary format (header + JSON payload)
+ */
+export declare function serializeStateToBinary(config: AgentConfig, runtimeState: RuntimeState, options?: StateFormatOptions): Promise<Uint8Array>;
+/**
+ * Deserialize state from binary format
+ */
+export declare function deserializeStateFromBinary(data: Uint8Array): SerializedStateV1 | null;
+/**
+ * Create a delta between two states
+ */
+export declare function createStateDelta(oldState: SerializedStateV1, newState: SerializedStateV1): StateDelta;
+/**
+ * Apply a delta to a state
+ */
+export declare function applyStateDelta(baseState: SerializedStateV1, delta: StateDelta): SerializedStateV1;
+//# sourceMappingURL=state-format.d.ts.map

package/dist/src/packaging/state-format.d.ts.map

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