0.5.1-pre.002

ks-store/src/lib.rs

@@ -0,0 +1,257 @@
+// file: ks-store/src/lib.rs
+// version: 5
+
+//! Backend-neutral storage contracts and PostgreSQL implementation.
+#![warn(missing_docs)]
+#![deny(unreachable_pub)]
+#![forbid(unsafe_code)]
+
+mod constants;
+mod contracts;
+mod postgres;
+
+/// Canonical tracing target for storage operations.
+pub(crate) use self::constants::TRACING_TARGET;
+
+/// Core account key insert contract.
+pub use self::contracts::CoreAccountKeyInsert;
+/// Core account key SQL-like row contract.
+pub use self::contracts::CoreAccountKeyRow;
+/// Core account key source category.
+pub use self::contracts::CoreAccountKeySource;
+/// Core balance change insert contract.
+pub use self::contracts::CoreBalanceChangeInsert;
+/// Core balance change kind.
+pub use self::contracts::CoreBalanceChangeKind;
+/// Core balance change SQL-like row contract.
+pub use self::contracts::CoreBalanceChangeRow;
+/// Complete normalized core extraction write bundle.
+pub use self::contracts::CoreExtractionBundle;
+/// Failure details persisted for one canonical to core extraction attempt.
+pub use self::contracts::CoreExtractionFailure;
+/// Bounded canonical transaction selection filter for core extraction.
+pub use self::contracts::CoreExtractionSelectionFilter;
+/// Canonical transaction to core extraction storage behavior.
+pub use self::contracts::CoreExtractionStore;
+/// Core inner instruction insert contract.
+pub use self::contracts::CoreInnerInstructionInsert;
+/// Core inner instruction SQL-like row contract.
+pub use self::contracts::CoreInnerInstructionRow;
+/// Core instruction insert contract.
+pub use self::contracts::CoreInstructionInsert;
+/// Core instruction lifecycle mark request.
+pub use self::contracts::CoreInstructionLifecycleMark;
+/// Core instruction processing state.
+pub use self::contracts::CoreInstructionProcessingState;
+/// Core instruction replay filter contract.
+pub use self::contracts::CoreInstructionReplayFilter;
+/// Core instruction SQL-like row contract.
+pub use self::contracts::CoreInstructionRow;
+/// Core log insert contract.
+pub use self::contracts::CoreLogInsert;
+/// Core log SQL-like row contract.
+pub use self::contracts::CoreLogRow;
+/// Core transaction insert contract.
+pub use self::contracts::CoreTransactionInsert;
+/// Core transaction SQL-like row contract.
+pub use self::contracts::CoreTransactionRow;
+/// Core Solana storage behavior.
+pub use self::contracts::CoreTransactionStore;
+/// Default repository page size.
+pub use self::contracts::DEFAULT_PAGE_SIZE;
+/// One machine-readable decoder coverage declaration row.
+pub use self::contracts::DecodeCoverageDeclarationInsert;
+/// One observed coverage classification row owned by one decode attempt.
+pub use self::contracts::DecodeCoverageObservationInsert;
+/// One row of aggregated decoder coverage diagnostics.
+pub use self::contracts::DecodeCoverageSummaryRow;
+/// Failed decode attempt persisted in the common ledger.
+pub use self::contracts::DecodeFailure;
+/// One processor-owned decoded observation row.
+pub use self::contracts::DecodeObservationInsert;
+/// Atomic persistence bundle for one decoder and one contextual input.
+pub use self::contracts::DecodePersistenceBundle;
+/// Contextual instruction decode and materialization storage behavior.
+pub use self::contracts::DecodePipelineStore;
+/// Bounded contextual instruction selection filter for decode campaigns.
+pub use self::contracts::DecodeSelectionFilter;
+/// Decoded event insert contract.
+pub use self::contracts::DecodedEventInsert;
+/// Decoded event SQL-like row contract.
+pub use self::contracts::DecodedEventRow;
+/// Decoded event storage behavior.
+pub use self::contracts::DecodedEventStore;
+/// Insert or upsert result contract returned by repositories.
+pub use self::contracts::InsertOutcome;
+/// Maximum number of materialized rows returned by one bounded query.
+pub use self::contracts::MAX_MATERIALIZED_EVENT_QUERY_ROWS;
+/// Maximum repository page size.
+pub use self::contracts::MAX_PAGE_SIZE;
+/// Atomic persistence bundle for one materializer and one decoded observation.
+pub use self::contracts::MaterializationPersistenceBundle;
+/// Bounded read-only materialized event selection.
+pub use self::contracts::MaterializedEventFilter;
+/// Materialized event insert contract.
+pub use self::contracts::MaterializedEventInsert;
+/// One materialized output returned by a bounded query.
+pub use self::contracts::MaterializedEventQueryRow;
+/// Materialized event SQL-like row contract.
+pub use self::contracts::MaterializedEventRow;
+/// Materialized event storage behavior.
+pub use self::contracts::MaterializedEventStore;
+/// One processor-owned materialized output row.
+pub use self::contracts::MaterializedOutputInsert;
+/// Page request contract for repository list operations.
+pub use self::contracts::PageRequest;
+/// Stable processing ledger identity.
+pub use self::contracts::ProcessingLedgerIdentity;
+/// Processing ledger mark request contract.
+pub use self::contracts::ProcessingLedgerMark;
+/// Processing ledger SQL-like row contract.
+pub use self::contracts::ProcessingLedgerRow;
+/// Stable processing ledger status.
+pub use self::contracts::ProcessingLedgerStatus;
+/// Processing ledger storage behavior.
+pub use self::contracts::ProcessingLedgerStore;
+/// Program observation storage behavior.
+pub use self::contracts::ProgramObservationStore;
+/// Raw payload lifecycle mark request.
+pub use self::contracts::RawPayloadLifecycleMark;
+/// Raw payload processing state.
+pub use self::contracts::RawPayloadProcessingState;
+/// Raw payload retention state.
+pub use self::contracts::RawPayloadRetentionState;
+/// Canonical raw Solana transaction insert contract.
+pub use self::contracts::RawTransactionInsert;
+/// Canonical raw Solana transaction SQL-like row contract.
+pub use self::contracts::RawTransactionRow;
+/// Raw transaction storage behavior.
+pub use self::contracts::RawTransactionStore;
+/// Sort direction for repository list operations.
+pub use self::contracts::SortDirection;
+/// Store backend diagnostic contract.
+pub use self::contracts::StoreBackendDescriptor;
+/// Store backend kind contract.
+pub use self::contracts::StoreBackendKind;
+/// Store backend health snapshot.
+pub use self::contracts::StoreHealthSnapshot;
+/// Store backend health status.
+pub use self::contracts::StoreHealthStatus;
+/// Store health storage behavior.
+pub use self::contracts::StoreHealthStore;
+/// Store migration diagnostic snapshot contract.
+pub use self::contracts::StoreMigrationSnapshot;
+/// Store migration status contract.
+pub use self::contracts::StoreMigrationStatus;
+/// Transaction acquisition observation insert contract.
+pub use self::contracts::TransactionObservationInsert;
+/// Transaction acquisition observation origin.
+pub use self::contracts::TransactionObservationOrigin;
+/// Transaction acquisition observation SQL-like row contract.
+pub use self::contracts::TransactionObservationRow;
+/// Transaction acquisition observation status.
+pub use self::contracts::TransactionObservationStatus;
+/// Storage error helper functions.
+pub use self::contracts::storage_contract_error;
+/// Allowed Solana table domains encoded in table names.
+pub use self::postgres::ALLOWED_SOLANA_TABLE_DOMAINS;
+/// Core account key table name.
+pub use self::postgres::CORE_ACCOUNT_KEYS_TABLE_NAME;
+/// Core balance change table name.
+pub use self::postgres::CORE_BALANCE_CHANGES_TABLE_NAME;
+/// Core inner instruction table name.
+pub use self::postgres::CORE_INNER_INSTRUCTIONS_TABLE_NAME;
+/// Core instruction table name.
+pub use self::postgres::CORE_INSTRUCTIONS_TABLE_NAME;
+/// Core log table name.
+pub use self::postgres::CORE_LOGS_TABLE_NAME;
+/// Core Solana table names.
+pub use self::postgres::CORE_STORE_TABLE_NAMES;
+/// Core transaction table name.
+pub use self::postgres::CORE_TRANSACTIONS_TABLE_NAME;
+/// Machine-readable decoder coverage declaration table name.
+pub use self::postgres::DECODE_COVERAGE_DECLARATIONS_TABLE_NAME;
+/// Observed decoder coverage classification table name.
+pub use self::postgres::DECODE_COVERAGE_OBSERVATIONS_TABLE_NAME;
+/// Versioned decoded event table name.
+pub use self::postgres::DECODE_EVENTS_TABLE_NAME;
+/// Decode and materialization table names.
+pub use self::postgres::DECODE_STORE_TABLE_NAMES;
+/// Default PostgreSQL schema policy.
+pub use self::postgres::DEFAULT_SCHEMA_POLICY;
+/// Versioned materialized output table name.
+pub use self::postgres::MATERIALIZED_EVENTS_TABLE_NAME;
+/// Maximum number of rows returned by one replay candidate query.
+pub use self::postgres::MAX_REPLAY_CANDIDATE_ROWS;
+/// PostgreSQL migration strategy used by this crate.
+pub use self::postgres::MIGRATION_STRATEGY;
+/// Migration table name used by sqlx.
+pub use self::postgres::MIGRATION_TABLE_NAME;
+/// Processing ledger table name.
+pub use self::postgres::PROCESSING_LEDGER_TABLE_NAME;
+/// PostgreSQL diagnostic snapshot.
+pub use self::postgres::PostgresBackendDiagnostics;
+/// Bounded read-only filter for core entity summaries.
+pub use self::postgres::PostgresReplayEntityFilter;
+/// Core entity kind used while filtering replay candidates.
+pub use self::postgres::PostgresReplayEntityKind;
+/// Aggregated mint, owner or account-key occurrences from core tables.
+pub use self::postgres::PostgresReplayEntitySummary;
+/// Bounded read-only filter for program summaries.
+pub use self::postgres::PostgresReplayProgramFilter;
+/// Program occurrence scope used while filtering replay candidates.
+pub use self::postgres::PostgresReplayProgramScope;
+/// Aggregated program occurrences across outer, inner and linked logs.
+pub use self::postgres::PostgresReplayProgramSummary;
+/// One raw transaction candidate enriched with core and ledger diagnostics.
+pub use self::postgres::PostgresReplayTransactionCandidate;
+/// Bounded read-only filter for transaction replay candidates.
+pub use self::postgres::PostgresReplayTransactionFilter;
+/// PostgreSQL store handle.
+pub use self::postgres::PostgresStore;
+/// PostgreSQL store connection options.
+pub use self::postgres::PostgresStoreOptions;
+/// PostgreSQL diagnostic table specification.
+pub use self::postgres::PostgresTableDiagnosticSpec;
+/// PostgreSQL table diagnostic snapshot.
+pub use self::postgres::PostgresTableDiagnostics;
+/// PostgreSQL table statistics snapshot.
+pub use self::postgres::PostgresTableStatistics;
+/// Canonical transaction acquisition table names.
+pub use self::postgres::RAW_STORE_TABLE_NAMES;
+/// Canonical raw transaction table name.
+pub use self::postgres::RAW_TRANSACTIONS_TABLE_NAME;
+/// Solana application table prefix.
+pub use self::postgres::SOLANA_TABLE_PREFIX;
+/// Advisory lock id used while initializing store tables.
+pub use self::postgres::STORE_SCHEMA_ADVISORY_LOCK_ID;
+/// Transaction acquisition observation table name.
+pub use self::postgres::TRANSACTION_OBSERVATIONS_TABLE_NAME;
+/// Core store SQL statements applied by the idempotent initializer.
+pub use self::postgres::core_store_schema_statements;
+/// Core table diagnostic specs.
+pub use self::postgres::core_store_table_diagnostic_specs;
+/// Decode and materialization SQL statements applied by the idempotent initializer.
+pub use self::postgres::decode_store_schema_statements;
+/// Decode and materialization table diagnostic specs.
+pub use self::postgres::decode_store_table_diagnostic_specs;
+/// Returns true when a Solana table name follows canonical rules.
+pub use self::postgres::is_valid_solana_table_name;
+/// Returns a DSN masked for logs and UI diagnostics.
+pub use self::postgres::mask_postgres_dsn;
+/// Canonical transaction acquisition SQL statements.
+pub use self::postgres::raw_store_schema_statements;
+/// Canonical transaction acquisition diagnostic specs.
+pub use self::postgres::raw_store_table_diagnostic_specs;
+/// Validates core store table names.
+pub use self::postgres::validate_core_store_table_names;
+/// Validates decode and materialization store table names.
+pub use self::postgres::validate_decode_store_table_names;
+/// Validates canonical transaction acquisition table names.
+pub use self::postgres::validate_raw_store_table_names;
+/// Validates a canonical Solana table name.
+pub use self::postgres::validate_solana_table_name;
+/// Current normalized core replay input contract version.
+pub use ks_lib::MD_CORE_REPLAY_INPUT_CONTRACT_VERSION;
+/// Decoder replay input containing one instruction plus extracted transaction context.
+pub use ks_lib::MdCoreInstructionReplayInput;