v0.2.13-pre.003

crates/ksp-interface-lib/src/error.rs

@@ -0,0 +1,6 @@
+// file: crates/ksp-interface-lib/src/error.rs
+// version: 1
+
+/// Error code used when a bounded passive Program instruction contract exceeds one of its Interface-owned admission limits.
+pub const ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED: ksp_core_lib::ErrorCode =
+    ksp_core_lib::ErrorCode::new("interface", "program_instruction_limit_exceeded");

crates/ksp-interface-lib/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-interface-lib/src/lib.rs
-// version: 1
+// version: 2
 
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
@@ -7,10 +7,19 @@
 
 //! Passive wire contracts shared by KSP Program implementations.
 //!
-//! The foundation deliberately starts with the canonical Solana [`Pubkey`]
-//! owned by `ksp-core-lib`. Program-facing instruction contracts are added in
-//! later slices without introducing runtime, transport, persistence or Program
-//! behavior into Interface.
+//! The foundation reuses the canonical Solana [`Pubkey`] owned by
+//! `ksp-core-lib` and exposes only bounded, passive Program-facing structures.
+//! Runtime, transport, persistence and Program behavior remain outside this
+//! crate.
 
+mod error;
+mod program_account_meta;
+
+/// Error code used when an Interface-owned Program instruction admission limit is exceeded.
+pub use self::error::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED;
+/// Maximum number of account metas admitted by one passive Program instruction contract.
+pub use self::program_account_meta::MAX_PROGRAM_INSTRUCTION_ACCOUNTS;
+/// Passive account metadata attached to one Program instruction.
+pub use self::program_account_meta::ProgramAccountMeta;
 /// Canonical Solana account address primitive owned by `ksp-core-lib`.
 pub use ksp_core_lib::Pubkey;

crates/ksp-interface-lib/src/program_account_meta.rs

@@ -0,0 +1,52 @@
+// file: crates/ksp-interface-lib/src/program_account_meta.rs
+// version: 1
+
+/// Maximum number of account metas admitted by one passive Program instruction contract.
+pub const MAX_PROGRAM_INSTRUCTION_ACCOUNTS: usize = 255;
+
+/// Passive account metadata attached to one Program instruction.
+///
+/// Account metas preserve the caller-provided Solana account identity and the
+/// signer/writable flags without applying Program-specific semantics.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct ProgramAccountMeta {
+    pubkey: crate::Pubkey,
+    is_signer: bool,
+    is_writable: bool,
+}
+
+impl ProgramAccountMeta {
+    /// Creates one read-only account meta.
+    #[must_use]
+    pub const fn readonly(pubkey: crate::Pubkey, is_signer: bool) -> Self {
+        return Self { pubkey, is_signer, is_writable: false };
+    }
+
+    /// Creates one writable account meta.
+    #[must_use]
+    pub const fn writable(pubkey: crate::Pubkey, is_signer: bool) -> Self {
+        return Self { pubkey, is_signer, is_writable: true };
+    }
+
+    /// Returns whether this account must sign the containing instruction.
+    #[must_use]
+    pub const fn is_signer(&self) -> bool {
+        return self.is_signer;
+    }
+
+    /// Returns whether this account may be written by the containing instruction.
+    #[must_use]
+    pub const fn is_writable(&self) -> bool {
+        return self.is_writable;
+    }
+
+    /// Returns the canonical account address.
+    #[must_use]
+    pub const fn pubkey(&self) -> &crate::Pubkey {
+        return &self.pubkey;
+    }
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/program_account_meta.rs"]
+mod tests;

crates/ksp-interface-lib/tests/dependency_boundary.rs

@@ -1,7 +1,7 @@
 // file: crates/ksp-interface-lib/tests/dependency_boundary.rs
-// version: 1
+// version: 2
 
-//! Dependency and passive-surface canaries for the Interface scaffold.
+//! Dependency and passive-surface canaries for the Interface foundation.
 
 #[test]
 fn pre_002_manifest_has_exact_core_only_runtime_dependency() {
@@ -45,10 +45,11 @@ fn pre_002_manifest_has_exact_core_only_runtime_dependency() {
 }
 
 #[test]
-fn pre_002_scaffold_remains_passive_without_runtime_logging_surface() {
+fn pre_003_surface_remains_passive_without_instruction_or_runtime_logging() {
     let crate_root = include_str!("../src/lib.rs");
-    assert!(crate_root.contains("pub use ksp_core_lib::Pubkey;"));
-    assert!(!crate_root.contains("ProgramAccountMeta"));
+    assert!(crate_root.contains("ProgramAccountMeta"));
+    assert!(crate_root.contains("MAX_PROGRAM_INSTRUCTION_ACCOUNTS"));
+    assert!(crate_root.contains("ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED"));
     assert!(!crate_root.contains("ProgramInstruction"));
     assert!(!crate_root.contains("TRACING_TARGET"));
     assert!(!crate_root.contains("ksp_logging_lib"));

crates/ksp-interface-lib/tests/public_api.rs

@@ -1,7 +1,7 @@
 // file: crates/ksp-interface-lib/tests/public_api.rs
-// version: 1
+// version: 2
 
-//! Integration canaries for the public `ksp-interface-lib` scaffold.
+//! Integration canaries for the public `ksp-interface-lib` foundation.
 
 fn consume_pubkey(pubkey: ksp_interface_lib::Pubkey) -> [u8; 32] {
     return pubkey.to_bytes();
@@ -13,3 +13,26 @@ fn public_pre_002_pubkey_contract_is_available_from_crate_root() {
     assert_eq!(consume_pubkey(pubkey), [0_u8; 32]);
     return;
 }
+
+#[test]
+fn public_pre_003_account_meta_and_limit_contracts_are_available_from_crate_root() {
+    let pubkey = ksp_interface_lib::Pubkey::new_from_array([3_u8; 32]);
+    let readonly = ksp_interface_lib::ProgramAccountMeta::readonly(pubkey, true);
+    let writable = ksp_interface_lib::ProgramAccountMeta::writable(pubkey, false);
+    assert_eq!(readonly.pubkey(), &pubkey);
+    assert!(readonly.is_signer());
+    assert!(!readonly.is_writable());
+    assert_eq!(writable.pubkey(), &pubkey);
+    assert!(!writable.is_signer());
+    assert!(writable.is_writable());
+    assert_eq!(ksp_interface_lib::MAX_PROGRAM_INSTRUCTION_ACCOUNTS, 255);
+    return;
+}
+
+#[test]
+fn public_pre_003_interface_error_code_is_stable_and_core_owned() {
+    let code: ksp_core_lib::ErrorCode = ksp_interface_lib::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED;
+    assert_eq!(code.domain(), "interface");
+    assert_eq!(code.code(), "program_instruction_limit_exceeded");
+    return;
+}

crates/ksp-interface-lib/unit_tests/program_account_meta.rs

@@ -0,0 +1,31 @@
+// file: crates/ksp-interface-lib/unit_tests/program_account_meta.rs
+// version: 1
+
+#[test]
+fn readonly_and_writable_constructors_preserve_identity_signer_and_writable_flags() {
+    let readonly_pubkey = crate::Pubkey::new_from_array([7_u8; 32]);
+    let writable_pubkey = crate::Pubkey::new_from_array([9_u8; 32]);
+    let readonly = crate::ProgramAccountMeta::readonly(readonly_pubkey, true);
+    assert_eq!(readonly.pubkey(), &readonly_pubkey);
+    assert!(readonly.is_signer());
+    assert!(!readonly.is_writable());
+    let writable = crate::ProgramAccountMeta::writable(writable_pubkey, false);
+    assert_eq!(writable.pubkey(), &writable_pubkey);
+    assert!(!writable.is_signer());
+    assert!(writable.is_writable());
+    return;
+}
+
+#[test]
+fn account_meta_accepts_opaque_pubkeys_without_program_registry_validation() {
+    let opaque_pubkey = crate::Pubkey::new_from_array([0xA5_u8; 32]);
+    let meta = crate::ProgramAccountMeta::readonly(opaque_pubkey, false);
+    assert_eq!(meta.pubkey(), &opaque_pubkey);
+    return;
+}
+
+#[test]
+fn account_limit_constant_matches_the_interface_admission_contract() {
+    assert_eq!(crate::MAX_PROGRAM_INSTRUCTION_ACCOUNTS, 255);
+    return;
+}