tensorfs 0.3.68__tar.gz → 0.3.69__tar.gz

{tensorfs-0.3.68 → tensorfs-0.3.69}/Cargo.lock

@@ -439,7 +439,7 @@ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
 [[package]]
 name = "tensorfs-core"
-version = "0.3.68"
+version = "0.3.69"
 dependencies = [
  "fs2",
  "libc",
@@ -454,7 +454,7 @@ dependencies = [
 
 [[package]]
 name = "tensorfs-py"
-version = "0.3.68"
+version = "0.3.69"
 dependencies = [
  "pyo3",
  "tensorfs-core",

{tensorfs-0.3.68 → tensorfs-0.3.69}/Cargo.toml

@@ -3,5 +3,5 @@ resolver = "2"
 members = ["crates/tensorfs-core", "crates/tensorfs-py"]
 
 [workspace.package]
-version = "0.3.68"
+version = "0.3.69"
 edition = "2021"

{tensorfs-0.3.68 → tensorfs-0.3.69}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensorfs
-Version: 0.3.68
+Version: 0.3.69
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Rust

{tensorfs-0.3.68 → tensorfs-0.3.69}/crates/tensorfs-core/src/derived/part_rows_tests.rs

@@ -324,3 +324,50 @@ fn an_indexed_checkpoint_does_not_reread_its_chain() {
     release_guards(&meta, Some(writer.writer_hold), writer.source_leases);
     std::fs::remove_dir_all(store.root()).unwrap();
 }
+
+#[test]
+fn a_digest_receipt_names_the_declaration_the_intent_bound() {
+    let (store, meta, id, declaration) = fixture("receipt-digest");
+    let intent = declaration.clone().canonical_work_bytes().unwrap();
+    let writer = begin(&store, &meta, &id, 1, declaration, None).unwrap();
+    for (index, key) in ["weight_0", "weight_1", "weight_2"].into_iter().enumerate() {
+        add(&store, &meta, &id, &writer, key, index as u8 + 1).unwrap();
+    }
+    let receipt = commit(&store, &meta, &id, 1).unwrap();
+    let inline = receipt.value(ReceiptDeclaration::Inline);
+    let digest = receipt.value(ReceiptDeclaration::Digest);
+    assert_eq!(inline, receipt.to_value());
+    let field = |value: &Value, name: &str| {
+        as_obj("receipt", "facts", value)
+            .unwrap()
+            .iter()
+            .find(|(key, _)| key == name)
+            .map(|(_, value)| value.clone())
+    };
+    assert_eq!(
+        crate::canon::write(&field(&inline, "declaration").unwrap()),
+        intent
+    );
+    assert!(field(&digest, "declaration").is_none());
+    assert_eq!(
+        field(&digest, "declaration_digest"),
+        Some(Value::str(ObjectRef::of(&intent).id()))
+    );
+    assert_eq!(
+        field(&digest, "declaration_length"),
+        Some(Value::uint(intent.len() as u64))
+    );
+    // Every other fact is identical in both forms.
+    let others = |value: &Value| {
+        as_obj("receipt", "facts", value)
+            .unwrap()
+            .iter()
+            .filter(|(key, _)| !key.starts_with("declaration"))
+            .cloned()
+            .collect::<Vec<_>>()
+    };
+    assert_eq!(others(&inline), others(&digest));
+    let _ = fence(&meta, &id, 1);
+    release_guards(&meta, Some(writer.writer_hold), writer.source_leases);
+    std::fs::remove_dir_all(store.root()).unwrap();
+}

{tensorfs-0.3.68 → tensorfs-0.3.69}/crates/tensorfs-core/src/derived/retention.rs

@@ -5,7 +5,8 @@ use std::io::{Read, Write};
 use std::path::PathBuf;
 
 use super::{
-    checkpoint, receipt_from, require_payload_record, roots, Disposition, TransactionState,
+    checkpoint, receipt_from, require_payload_record, roots, Disposition, ReceiptDeclaration,
+    TransactionState,
 };
 use crate::canon::{Fields, Value};
 use crate::catalog::WriterGuard;
@@ -217,7 +218,12 @@ pub fn retain_result(
         );
     }
     let facts = receipt_from(store, row)?;
-    if object_id(&crate::canon::write(&facts.to_value())) != receipt {
+    // A receipt's identity is the digest of whichever form its caller was handed.
+    let forms = [ReceiptDeclaration::Inline, ReceiptDeclaration::Digest];
+    if !forms
+        .iter()
+        .any(|form| object_id(&crate::canon::write(&facts.value(*form))) == receipt)
+    {
         return refuse(
             Code::OBJECT_ID_MISMATCH,
             "retained result receipt differs from committed computation",
@@ -369,6 +375,29 @@ mod tests {
         }
     }
 
+    #[test]
+    fn a_result_is_retained_under_either_receipt_form_and_nothing_else() {
+        let f = fixture();
+        let facts = derived::lookup(&f.store, &f.meta, &f.transaction).unwrap();
+        let derived::Lookup::Committed(committed) = facts else {
+            panic!("committed result expected")
+        };
+        let digest_form = object_id(&crate::canon::write(
+            &committed.receipt().value(ReceiptDeclaration::Digest),
+        ));
+        assert_ne!(digest_form, f.receipt);
+        let retained =
+            retain_result(&f.store, &f.meta, &f.transaction, &digest_form, &id("b1")).unwrap();
+        assert_eq!(retained.receipt_digest, digest_form);
+        retain_result(&f.store, &f.meta, &f.transaction, &f.receipt, &id("b2")).unwrap();
+        assert_eq!(
+            retain_result(&f.store, &f.meta, &f.transaction, &id("99"), &id("b3"))
+                .unwrap_err()
+                .code,
+            Code::OBJECT_ID_MISMATCH
+        );
+    }
+
     #[test]
     fn independent_owners_keep_original_bytes_and_receipt_through_disposal_and_gc() {
         let f = fixture();

{tensorfs-0.3.68 → tensorfs-0.3.69}/crates/tensorfs-core/src/derived.rs

@@ -3421,8 +3421,38 @@ pub struct ReceiptFacts {
     pub inherited_payload_bytes: u64,
 }
 
+/// How a receipt names its declaration: the whole document, or its digest and length.
+/// The whole document grows with the tensors declared; a digest keeps receipts constant.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum ReceiptDeclaration {
+    #[default]
+    Inline,
+    Digest,
+}
+
 impl ReceiptFacts {
     pub fn to_value(&self) -> Value {
+        self.value(ReceiptDeclaration::Inline)
+    }
+
+    pub fn value(&self, form: ReceiptDeclaration) -> Value {
+        let mut value = self.inline_value();
+        if form == ReceiptDeclaration::Digest {
+            if let Value::Obj(fields) = &mut value {
+                let bytes = crate::canon::write(&self.declaration.to_value());
+                fields.retain(|(key, _)| key != "declaration");
+                fields.push((
+                    "declaration_digest".into(),
+                    Value::str(ObjectRef::of(&bytes).id()),
+                ));
+                fields.push(("declaration_length".into(), Value::uint(bytes.len() as u64)));
+                fields.sort_by(|left, right| left.0.cmp(&right.0));
+            }
+        }
+        value
+    }
+
+    fn inline_value(&self) -> Value {
         Value::obj(vec![
             (
                 "added_objects",

{tensorfs-0.3.68 → tensorfs-0.3.69}/crates/tensorfs-py/src/store.rs

@@ -454,8 +454,26 @@ fn source_component<'p>(
     Ok(rows)
 }
 
-fn receipt<'p>(py: Python<'p>, receipt: &derived::ReceiptFacts) -> PyResult<Bound<'p, PyAny>> {
-    marshal(py, &receipt.to_value())
+fn receipt<'p>(
+    py: Python<'p>,
+    receipt: &derived::ReceiptFacts,
+    form: derived::ReceiptDeclaration,
+) -> PyResult<Bound<'p, PyAny>> {
+    marshal(py, &receipt.value(form))
+}
+
+fn receipt_form(py: Python<'_>, name: &str) -> PyResult<derived::ReceiptDeclaration> {
+    match name {
+        "inline" => Ok(derived::ReceiptDeclaration::Inline),
+        "digest" => Ok(derived::ReceiptDeclaration::Digest),
+        _ => Err(to_py(
+            py,
+            &Refusal {
+                code: Code::UNKNOWN_FIELD,
+                detail: format!("receipts must be \"inline\" or \"digest\", not {name:?}"),
+            },
+        )),
+    }
 }
 
 // ---------------------------------------------------------------- store
@@ -559,42 +577,48 @@ fn checkpoint_root_dict<'p>(
 pub struct PyStore {
     pub store: Arc<CoreStore>,
     pub meta: Arc<Meta>,
+    /// How derived receipts from this handle name their declaration. A caller that reads
+    /// the digest form opts in; the default keeps the declaration inline.
+    receipts: derived::ReceiptDeclaration,
 }
 
 fn open_store(
     py: Python<'_>,
     root: PathBuf,
     open: fn(&Path) -> tensorfs_core::err::Result<CoreStore>,
+    receipts: &str,
 ) -> PyResult<PyStore> {
+    let receipts = receipt_form(py, receipts)?;
     let s = open(&root).or_refuse(py)?;
     let m = Meta::open(&s).or_refuse(py)?;
     Ok(PyStore {
         store: Arc::new(s),
         meta: Arc::new(m),
+        receipts,
     })
 }
 
 #[pymethods]
 impl PyStore {
     #[staticmethod]
-    #[pyo3(signature = (root = None))]
-    fn ensure(py: Python<'_>, root: Option<PathBuf>) -> PyResult<PyStore> {
+    #[pyo3(signature = (root = None, *, receipts = "inline"))]
+    fn ensure(py: Python<'_>, root: Option<PathBuf>, receipts: &str) -> PyResult<PyStore> {
         let root = tensorfs_core::home::store_root(root.as_deref()).or_refuse(py)?;
-        open_store(py, root, CoreStore::ensure)
+        open_store(py, root, CoreStore::ensure, receipts)
     }
 
     #[staticmethod]
-    #[pyo3(signature = (root = None))]
-    fn open(py: Python<'_>, root: Option<PathBuf>) -> PyResult<PyStore> {
+    #[pyo3(signature = (root = None, *, receipts = "inline"))]
+    fn open(py: Python<'_>, root: Option<PathBuf>, receipts: &str) -> PyResult<PyStore> {
         let root = tensorfs_core::home::store_root(root.as_deref()).or_refuse(py)?;
-        open_store(py, root, CoreStore::open)
+        open_store(py, root, CoreStore::open, receipts)
     }
 
     #[staticmethod]
-    #[pyo3(signature = (root = None))]
-    fn init(py: Python<'_>, root: Option<PathBuf>) -> PyResult<PyStore> {
+    #[pyo3(signature = (root = None, *, receipts = "inline"))]
+    fn init(py: Python<'_>, root: Option<PathBuf>, receipts: &str) -> PyResult<PyStore> {
         let root = tensorfs_core::home::store_root(root.as_deref()).or_refuse(py)?;
-        open_store(py, root, CoreStore::init)
+        open_store(py, root, CoreStore::init, receipts)
     }
 
     #[getter]
@@ -2278,6 +2302,7 @@ impl PyStore {
             source_views: begin.source_views,
             additions: begin.additions,
             cursor: Mutex::new(None),
+            receipts: self.receipts,
             guards: Mutex::new(Some(DerivedGuards {
                 writer_hold: begin.writer_hold,
                 source_leases: begin.source_leases,
@@ -2347,7 +2372,7 @@ impl PyStore {
             }
             derived::Lookup::Committed(value) => {
                 out.set_item("state", "committed")?;
-                out.set_item("receipt", receipt(py, value.receipt())?)?;
+                out.set_item("receipt", receipt(py, value.receipt(), self.receipts)?)?;
                 out.set_item("disposition", marshal(py, &value.disposition_value())?)?;
             }
             derived::Lookup::Abandoned => out.set_item("state", "abandoned")?,
@@ -2381,7 +2406,7 @@ impl PyStore {
             None => out.set_item("state", "abandoned")?,
             Some(value) => {
                 out.set_item("state", "committed")?;
-                out.set_item("receipt", receipt(py, &value)?)?;
+                out.set_item("receipt", receipt(py, &value, self.receipts)?)?;
             }
         }
         Ok(out)
@@ -2399,7 +2424,7 @@ impl PyStore {
             .or_refuse(py)?;
         let out = marshal(py, &value.to_value())?;
         out.cast::<PyDict>()?
-            .set_item("receipt", receipt(py, value.receipt())?)?;
+            .set_item("receipt", receipt(py, value.receipt(), self.receipts)?)?;
         Ok(out)
     }
 
@@ -2458,7 +2483,7 @@ impl PyStore {
             .or_refuse(py)?;
         let out = marshal(py, &value.to_value())?;
         let out_dict = out.cast::<PyDict>()?;
-        out_dict.set_item("receipt", receipt(py, value.receipt())?)?;
+        out_dict.set_item("receipt", receipt(py, value.receipt(), self.receipts)?)?;
         Ok(out)
     }
 
@@ -2568,6 +2593,7 @@ pub struct PyDerivedWriter {
     source_views: Vec<derived::SourceView>,
     additions: derived::Additions,
     cursor: Mutex<Option<derived::CheckpointCursor>>,
+    receipts: derived::ReceiptDeclaration,
     guards: Mutex<Option<DerivedGuards>>,
 }
 
@@ -2873,7 +2899,7 @@ impl PyDerivedWriter {
             })
             .or_refuse(py)?;
         self.release_holds(py);
-        receipt(py, &value)
+        receipt(py, &value, self.receipts)
     }
 
     fn fence(&self, py: Python<'_>) -> PyResult<bool> {

{tensorfs-0.3.68 → tensorfs-0.3.69}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "tensorfs"
-version = "0.3.68"
+version = "0.3.69"
 description = "TensorFS — canonical tensor artifact substrate"
 requires-python = ">=3.12"
 classifiers = [

{tensorfs-0.3.68 → tensorfs-0.3.69}/python/tensorfs/_ext.pyi

@@ -433,11 +433,17 @@ class Store:
     refuses an absent root, `ensure` creates one, `init` demands a fresh one (tfs-053)."""
 
     @staticmethod
-    def ensure(root: StrPath | None = None) -> Store: ...
+    def ensure(
+        root: StrPath | None = None, *, receipts: Literal["inline", "digest"] = "inline"
+    ) -> Store: ...
     @staticmethod
-    def open(root: StrPath | None = None) -> Store: ...
+    def open(
+        root: StrPath | None = None, *, receipts: Literal["inline", "digest"] = "inline"
+    ) -> Store: ...
     @staticmethod
-    def init(root: StrPath | None = None) -> Store: ...
+    def init(
+        root: StrPath | None = None, *, receipts: Literal["inline", "digest"] = "inline"
+    ) -> Store: ...
     @property
     def root(self) -> str: ...
     def bind_fingerprint_registry(self, data: bytes | None) -> None: ...