clawmates: phase work

Mission: 01a00c41-bac0-7eb3-a8c8-8b7044f3086d
Phase: 01a00c41-bac2-71e3-a58b-c473421200ee

Committed by the ClawMates delivery pipeline from the agents' working tree. Authored by agents, not by the named committer.

crates/clawhdf5-migrate/src/hdf5_reader.rs

@@ -49,6 +49,10 @@ pub fn read_hdf5(path: &str) -> Result<SqliteData, BoxErr> {
         entities,
         relations,
         embedding_dim,
+        // Not a SQLite read — the caller (incremental migration) carries
+        // forward the current run's actual `source_path` from the fresh
+        // SQLite read instead of using this placeholder.
+        source_path: String::new(),
     })
 }
 

crates/clawhdf5-migrate/src/hdf5_writer.rs

@@ -20,6 +20,7 @@ pub fn write_hdf5(
     opts: &WriteOptions,
 ) -> Result<(), Box<dyn std::error::Error>> {
     let mut builder = FileBuilder::new();
+    let timestamp = iso8601_now();
 
     // Root-level metadata attributes
     builder.set_attr("agent_id", AttrValue::String(opts.agent_id.clone()));
@@ -27,8 +28,18 @@ pub fn write_hdf5(
     builder.set_attr("embedding_dim", AttrValue::I64(data.embedding_dim as i64));
     builder.set_attr("source", AttrValue::String("sqlite-migration".into()));
     builder.set_attr("version", AttrValue::I64(1));
+    // Lineage: which SQLite database this output was migrated from and when,
+    // plus the migrator tool version — so a chain of `--incremental` runs
+    // still has an audit trail instead of every run overwriting the same
+    // static attributes (see research/03_provenance.md, INT-03).
+    builder.set_attr("source_path", AttrValue::String(data.source_path.clone()));
+    builder.set_attr("migrated_at", AttrValue::String(timestamp.clone()));
+    builder.set_attr(
+        "migrator_version",
+        AttrValue::String(env!("CARGO_PKG_VERSION").to_owned()),
+    );
 
-    write_chunks_group(&mut builder, data, opts);
+    write_chunks_group(&mut builder, data, opts, &timestamp);
     write_sessions_group(&mut builder, data);
     write_entities_group(&mut builder, data);
     write_relations_group(&mut builder, data);
@@ -37,6 +48,36 @@ pub fn write_hdf5(
     Ok(())
 }
 
+/// Current UTC time formatted as an ISO-8601 / RFC-3339 timestamp
+/// (`YYYY-MM-DDTHH:MM:SSZ`), with no external date/time dependency.
+fn iso8601_now() -> String {
+    let secs = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs();
+    let days = (secs / 86_400) as i64;
+    let time_of_day = secs % 86_400;
+    let (h, m, s) = (time_of_day / 3600, (time_of_day % 3600) / 60, time_of_day % 60);
+    let (y, mo, d) = civil_from_days(days);
+    format!("{y:04}-{mo:02}-{d:02}T{h:02}:{m:02}:{s:02}Z")
+}
+
+/// Days-since-epoch to (year, month, day), Howard Hinnant's `civil_from_days`
+/// algorithm (proleptic Gregorian calendar, valid for the full `i64` range).
+fn civil_from_days(z: i64) -> (i64, u32, u32) {
+    let z = z + 719_468;
+    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
+    let doe = (z - era * 146_097) as u64; // [0, 146096]
+    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365; // [0, 399]
+    let y = yoe as i64 + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); // [0, 365]
+    let mp = (5 * doy + 2) / 153; // [0, 11]
+    let d = (doy - (153 * mp + 2) / 5 + 1) as u32; // [1, 31]
+    let m = (if mp < 10 { mp + 3 } else { mp - 9 }) as u32; // [1, 12]
+    let y = if m <= 2 { y + 1 } else { y };
+    (y, m, d)
+}
+
 /// Build a fixed-length string Datatype from the max byte length of the items.
 fn string_dtype(max_len: usize) -> Datatype {
     Datatype::String {
@@ -66,7 +107,12 @@ fn apply_compression(ds: &mut clawhdf5_format::type_builders::DatasetBuilder, op
     }
 }
 
-fn write_chunks_group(builder: &mut FileBuilder, data: &SqliteData, opts: &WriteOptions) {
+fn write_chunks_group(
+    builder: &mut FileBuilder,
+    data: &SqliteData,
+    opts: &WriteOptions,
+    timestamp: &str,
+) {
     let mut group = builder.create_group("chunks");
     let n = data.chunks.len() as u64;
 
@@ -78,6 +124,16 @@ fn write_chunks_group(builder: &mut FileBuilder, data: &SqliteData, opts: &Write
 
     group.set_attr("count", AttrValue::I64(n as i64));
 
+    // Source attribution attached directly to the content-bearing datasets
+    // (SHA-256 of the raw bytes + creator/timestamp/source), so the chunk
+    // text and embeddings each carry their own verifiable provenance
+    // (see clawhdf5_format::provenance / `Dataset::verify_provenance`).
+    let source_opt = if data.source_path.is_empty() {
+        None
+    } else {
+        Some(data.source_path.as_str())
+    };
+
     // ids
     let ids: Vec<i64> = data.chunks.iter().map(|c| c.id).collect();
     group.create_dataset("id").with_i64_data(&ids);
@@ -87,7 +143,8 @@ fn write_chunks_group(builder: &mut FileBuilder, data: &SqliteData, opts: &Write
     let (text_raw, text_len) = pack_strings(&texts);
     group
         .create_dataset("text")
-        .with_compound_data(string_dtype(text_len), text_raw, n);
+        .with_compound_data(string_dtype(text_len), text_raw, n)
+        .with_provenance("clawhdf5-migrate", timestamp, source_opt);
 
     // embeddings - flatten to [N, dim]
     let dim = data.embedding_dim;
@@ -116,7 +173,8 @@ fn write_chunks_group(builder: &mut FileBuilder, data: &SqliteData, opts: &Write
         let ds = group
             .create_dataset("embeddings")
             .with_compound_data(f16_dtype, raw, n)
-            .with_shape(&[n, dim as u64]);
+            .with_shape(&[n, dim as u64])
+            .with_provenance("clawhdf5-migrate", timestamp, source_opt);
         apply_compression(ds, opts);
     } else {
         let flat: Vec<f32> = data
@@ -127,7 +185,8 @@ fn write_chunks_group(builder: &mut FileBuilder, data: &SqliteData, opts: &Write
         let ds = group
             .create_dataset("embeddings")
             .with_f32_data(&flat)
-            .with_shape(&[n, dim as u64]);
+            .with_shape(&[n, dim as u64])
+            .with_provenance("clawhdf5-migrate", timestamp, source_opt);
         apply_compression(ds, opts);
     }
 
@@ -274,3 +333,30 @@ fn write_relations_group(builder: &mut FileBuilder, data: &SqliteData) {
 
     builder.add_group(group.finish());
 }
+
+#[cfg(test)]
+mod time_tests {
+    use super::civil_from_days;
+
+    #[test]
+    fn epoch_day_zero_is_1970_01_01() {
+        assert_eq!(civil_from_days(0), (1970, 1, 1));
+    }
+
+    #[test]
+    fn known_dates_roundtrip() {
+        // 2026-08-16 is 20,681 days after 1970-01-01.
+        assert_eq!(civil_from_days(20_681), (2026, 8, 16));
+        // 2000-02-29 (leap day itself) and 2000-03-01 (the day after).
+        assert_eq!(civil_from_days(11_016), (2000, 2, 29));
+        assert_eq!(civil_from_days(11_017), (2000, 3, 1));
+    }
+
+    #[test]
+    fn iso8601_now_has_expected_shape() {
+        let ts = super::iso8601_now();
+        assert_eq!(ts.len(), "2026-08-16T00:00:00Z".len());
+        assert!(ts.starts_with("20")); // sanity: 21st-century year
+        assert!(ts.ends_with('Z'));
+    }
+}

crates/clawhdf5-migrate/src/main.rs

@@ -154,6 +154,10 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
             base.entities = source.entities;
             base.relations = source.relations;
             base.embedding_dim = source.embedding_dim.max(base.embedding_dim);
+            // Carry the current run's real SQLite source forward for
+            // provenance — `base` (re-read from the prior HDF5 output) has
+            // no meaningful source_path of its own.
+            base.source_path = source.source_path;
             if cli.verbose {
                 eprintln!("Incremental: appended {added} new chunks (id > {min_chunk_id})");
             }
@@ -199,6 +203,11 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         summary.embedding_dim,
         summary.rows_checked,
     );
+    if summary.provenance_verified {
+        eprintln!("Provenance: chunks/text and chunks/embeddings SHA-256 hashes verified.");
+    } else if cli.verbose {
+        eprintln!("Provenance: no provenance hash found to verify (older output format?).");
+    }
 
     Ok(())
 }

crates/clawhdf5-migrate/src/sqlite_reader.rs

@@ -51,6 +51,11 @@ pub struct SqliteData {
     pub entities: Vec<Entity>,
     pub relations: Vec<Relation>,
     pub embedding_dim: usize,
+    /// Filesystem path of the SQLite database this data was read from, for
+    /// provenance attribution on the HDF5 output. Empty when the data did
+    /// not come directly from a SQLite read (e.g. re-read of a prior HDF5
+    /// migration output for an incremental merge).
+    pub source_path: String,
 }
 
 /// A table name plus the ordered column names the reader maps by position.
@@ -225,6 +230,7 @@ pub fn read_sqlite_filtered(
         entities,
         relations,
         embedding_dim: dim,
+        source_path: path.to_owned(),
     })
 }
 

crates/clawhdf5-migrate/src/validate.rs

@@ -1,3 +1,6 @@
+use clawhdf5::reader::File as Hdf5File;
+use clawhdf5_format::provenance::VerifyResult;
+
 use crate::hdf5_reader::read_hdf5;
 use crate::sqlite_reader::SqliteData;
 
@@ -13,6 +16,12 @@ pub struct ValidationSummary {
     pub embedding_dim: u64,
     /// Number of rows whose full content was compared against the source.
     pub rows_checked: u64,
+    /// Whether the `chunks/text` and `chunks/embeddings` SHINES provenance
+    /// hashes (written via [`crate::hdf5_writer`]) were both present and
+    /// matched their recomputed SHA-256 on read-back. `false` when either
+    /// dataset has no provenance metadata (e.g. an older output file) or
+    /// there are zero chunks to check.
+    pub provenance_verified: bool,
 }
 
 /// Validate a migrated HDF5 file against the source data.
@@ -30,6 +39,7 @@ pub fn validate_hdf5(
     float16: bool,
 ) -> Result<ValidationSummary, BoxErr> {
     let got = read_hdf5(path)?;
+    let provenance_verified = verify_chunk_provenance(path)?;
 
     // ---- Counts ----
     check_count("chunk", got.chunks.len(), source.chunks.len())?;
@@ -126,6 +136,7 @@ pub fn validate_hdf5(
         relations: got.relations.len() as u64,
         embedding_dim: got.embedding_dim as u64,
         rows_checked,
+        provenance_verified,
     })
 }
 
@@ -136,6 +147,42 @@ fn check_count(kind: &str, got: usize, expected: usize) -> Result<(), BoxErr> {
     Ok(())
 }
 
+/// Re-verify the SHA-256 provenance hash of `chunks/text` and
+/// `chunks/embeddings` against their actual stored bytes, catching
+/// post-write corruption that a plain content comparison against the
+/// in-memory source wouldn't (the source is compared against what
+/// `read_hdf5` decoded, not against the raw bytes on disk).
+///
+/// Returns `Ok(true)` only if both datasets exist and both hashes match.
+/// Returns `Ok(false)` (not an error) if a dataset has no provenance
+/// attributes at all (e.g. a file written before this check existed) or
+/// there are zero chunks. Returns an error only on an actual hash mismatch —
+/// that indicates real corruption.
+fn verify_chunk_provenance(path: &str) -> Result<bool, BoxErr> {
+    let file = Hdf5File::open(path)?;
+    let Ok(chunks) = file.group("chunks") else {
+        return Ok(false);
+    };
+    let mut all_present = true;
+    for name in ["text", "embeddings"] {
+        let Ok(ds) = chunks.dataset(name) else {
+            all_present = false;
+            continue;
+        };
+        match ds.verify_provenance()? {
+            VerifyResult::Ok => {}
+            VerifyResult::NoHash => all_present = false,
+            VerifyResult::Mismatch { stored, computed } => {
+                return Err(format!(
+                    "provenance hash mismatch on chunks/{name}: stored {stored}, recomputed {computed} — data may be corrupted"
+                )
+                .into());
+            }
+        }
+    }
+    Ok(all_present)
+}
+
 fn field_err<T: std::fmt::Display>(kind: &str, i: usize, field: &str, s: T, g: T) -> BoxErr {
     format!("{kind}[{i}].{field} mismatch: source {s}, HDF5 {g}").into()
 }