feat: Add metadata support to storage read operations

packages/runner/src/storage/interface.ts

@@ -35,6 +35,18 @@ export type {
   Unit,
 };
 
+/**
+ * Metadata that can be attached to read operations
+ */
+export interface Metadata extends Record<PropertyKey, unknown> {}
+
+/**
+ * Options for read operations
+ */
+export interface IReadOptions {
+  meta?: Metadata;
+}
+
 /**
  * @deprecated - Use IAttestation instead
  */
@@ -412,9 +424,13 @@ export interface IStorageTransaction {
    * opposed to value stored.
    *
    * @param address - Memory address to read from.
+   * @param options - Optional read options including metadata
    * @returns Result containing the read value or an error.
    */
-  read(address: IMemorySpaceAddress): Result<IAttestation, ReadError>;
+  read(
+    address: IMemorySpaceAddress,
+    options?: IReadOptions,
+  ): Result<IAttestation, ReadError>;
 
   /**
    * Creates a memory space writer for this transaction. Fails if transaction is
@@ -587,8 +603,14 @@ export interface ITransactionReader {
    *  // Referencing non-existing facts produces errors
    *  assert(tx.read({ the: 'bad/mime' , of, at: ['author'] }).error.name === 'NotFoundError')
    * ```
+   *
+   * @param address - Memory address to read from
+   * @param options - Optional read options including metadata
    */
-  read(address: IMemoryAddress): Result<IAttestation, ReadError>;
+  read(
+    address: IMemoryAddress,
+    options?: IReadOptions,
+  ): Result<IAttestation, ReadError>;
 }
 
 export interface ITransactionWriter extends ITransactionReader {
@@ -859,10 +881,14 @@ export interface IStorageEdit {
 }
 
 export type Activity = Variant<{
-  read: IMemorySpaceAddress;
+  read: IReadActivity;
   write: IMemorySpaceAddress;
 }>;
 
+export interface IReadActivity extends IMemorySpaceAddress {
+  meta: Metadata;
+}
+
 /**
  * Error is returned on an attempt to open writer in a transaction that already
  * has a writer for a different space.

packages/runner/src/storage/transaction-shim.ts

@@ -6,6 +6,7 @@ import type {
   IMemorySpaceAddress,
   InactiveTransactionError,
   INotFoundError,
+  IReadOptions,
   IStorageInvariant,
   IStorageTransaction,
   IStorageTransactionComplete,
@@ -140,6 +141,7 @@ class TransactionReader implements ITransactionReader {
 
   read(
     address: IMemorySpaceAddress,
+    options?: IReadOptions,
   ): Result<Read, ReadError> {
     if (address.type !== "application/json") {
       const error = new Error(
@@ -413,13 +415,13 @@ export class StorageTransaction implements IStorageTransaction {
     return { ok: reader };
   }
 
-  read(address: IMemorySpaceAddress): Result<Read, ReadError> {
+  read(address: IMemorySpaceAddress, options?: IReadOptions): Result<Read, ReadError> {
     const readerResult = this.reader(address.space);
     if (readerResult.error) {
       return { ok: undefined, error: readerResult.error };
     }
 
-    const readResult = readerResult.ok!.read(address);
+    const readResult = readerResult.ok!.read(address, options);
     if (readResult.error) {
       return { ok: undefined, error: readResult.error };
     }
@@ -532,8 +534,8 @@ export class ExtendedStorageTransaction implements IExtendedStorageTransaction {
     return this.tx.reader(space);
   }
 
-  read(address: IMemorySpaceAddress): Result<Read, ReadError> {
-    return this.tx.read(address);
+  read(address: IMemorySpaceAddress, options?: IReadOptions): Result<Read, ReadError> {
+    return this.tx.read(address, options);
   }
 
   readOrThrow(address: IMemorySpaceAddress): JSONValue | undefined {

packages/runner/src/storage/transaction.ts

@@ -3,6 +3,7 @@ import type {
   IAttestation,
   IMemorySpaceAddress,
   InactiveTransactionError,
+  IReadOptions,
   IStorageManager,
   IStorageTransaction,
   IStorageTransactionAborted,
@@ -84,8 +85,8 @@ class StorageTransaction implements IStorageTransaction {
     return writer(this, space);
   }
 
-  read(address: IMemorySpaceAddress) {
-    return read(this, address);
+  read(address: IMemorySpaceAddress, options?: IReadOptions) {
+    return read(this, address, options);
   }
 
   write(address: IMemorySpaceAddress, value?: JSONValue) {
@@ -199,13 +200,14 @@ export const writer = (
 export const read = (
   transaction: StorageTransaction,
   address: IMemorySpaceAddress,
+  options?: IReadOptions,
 ) => {
   const { ok: space, error } = reader(transaction, address.space);
   if (error) {
     return { error };
   } else {
     const { space: _, ...memoryAddress } = address;
-    return space.read(memoryAddress);
+    return space.read(memoryAddress, options);
   }
 };
 

packages/runner/src/storage/transaction/chronicle.ts

@@ -120,6 +120,7 @@ export class Chronicle {
 
   read(
     address: IMemoryAddress,
+    options?: { meta?: unknown },
   ): Result<
     IAttestation,
     | IStorageTransactionInconsistent

packages/runner/src/storage/transaction/journal.ts

@@ -3,6 +3,7 @@ import type {
   IAttestation,
   IMemoryAddress,
   InactiveTransactionError,
+  IReadOptions,
   IStorageManager,
   IStorageTransactionAborted,
   IStorageTransactionComplete,
@@ -102,17 +103,24 @@ export const read = (
   journal: IJournal,
   space: MemorySpace,
   address: IMemoryAddress,
+  options?: IReadOptions,
 ): Result<IAttestation, ReadError> => {
   const { ok: branch, error } = checkout(journal, space);
   if (error) {
     return { error };
   } else {
-    const result = branch.read(address);
+    const result = branch.read(address, options);
     if (result.error) {
       return { error: result.error.from(space) };
     } else {
-      // Track read activity
-      journal.state.activity.push({ read: { ...address, space } });
+      // Track read activity with metadata
+      journal.state.activity.push({
+        read: {
+          ...address,
+          space,
+          meta: options?.meta ?? {},
+        },
+      });
       return result;
     }
   }
@@ -300,8 +308,8 @@ export class TransactionReader implements ITransactionReader {
     return this.#space;
   }
 
-  read(address: IMemoryAddress) {
-    return read(this.#journal, this.#space, address);
+  read(address: IMemoryAddress, options?: IReadOptions) {
+    return read(this.#journal, this.#space, address, options);
   }
 }
 
@@ -324,8 +332,8 @@ export class TransactionWriter implements ITransactionWriter {
     return this.#space;
   }
 
-  read(address: IMemoryAddress) {
-    return read(this.#journal, this.#space, address);
+  read(address: IMemoryAddress, options?: IReadOptions) {
+    return read(this.#journal, this.#space, address, options);
   }
 
   /**