Updates

reference_osis_actor/README.md

@@ -0,0 +1,79 @@
+# Object Storage and Indexing System (OSIS) Actor
+
+The OSIS Actor is responsible for storing and indexing objects in the system. It implements the actor interface to process jobs in a **blocking, synchronized manner**.
+
+## Job Processing Behavior
+
+The OSISActor processes jobs sequentially with the following characteristics:
+
+- **Blocking Processing**: Each job is processed completely before the next job begins
+- **Synchronized Execution**: Jobs are executed one at a time in the order they are received
+- **No Concurrency**: Unlike async actors, OSIS ensures no parallel job execution
+- **Deterministic Order**: Job completion follows the exact order of job submission
+
+This design ensures data consistency and prevents race conditions when performing storage and indexing operations.
+
+## Usage
+
+```rust
+use actor_osis::{OSISActor, spawn_osis_actor};
+
+// Create an OSIS actor with builder pattern
+let actor = OSISActor::builder()
+    .db_path("/path/to/database")
+    .redis_url("redis://localhost:6379")
+    .build()
+    .expect("Failed to build OSISActor");
+
+// Or spawn directly with convenience function
+let handle = spawn_osis_actor(
+    "/path/to/database".to_string(),
+    "redis://localhost:6379".to_string(),
+    shutdown_rx,
+);
+```
+
+## Actor Properties
+
+- **Actor ID**: `"osis"` (constant)
+- **Actor Type**: `"OSIS"`
+- **Processing Model**: Sequential, blocking
+- **Script Engine**: Rhai with OSIS-specific DSL extensions
+## Canonical Redis queues and verification
+
+The project uses canonical dispatch queues per script type. For OSIS, the work queue is:
+- hero:q:work:type:osis
+
+Consumer behavior:
+- The in-repo actor derives ScriptType=OSIS from its actor_id containing "osis" and BLPOPs hero:q:work:type:osis.
+- This repo’s OSIS actor has been updated so its actor_id is "osis", ensuring it consumes the canonical queue.
+
+Quick verification (redis-cli):
+- List work queues:
+  - KEYS hero:q:work:type:*
+- Check OSIS queue length:
+  - LLEN hero:q:work:type:osis
+- Inspect a specific job (replace {job_id} with the printed id):
+  - HGET hero:job:{job_id} status
+  - HGET hero:job:{job_id} output
+
+Run options:
+- Option A: Run the example which spawns the OSIS actor and dispatches jobs to the canonical queue.
+  1) Start Redis (if not already): redis-server
+  2) In this repo:
+     - cargo run --example actor
+  3) Observe the console: job IDs will be printed as they are created and dispatched.
+  4) In a separate terminal, verify with redis-cli:
+     - LLEN hero:q:work:type:osis (will briefly increment, then return to 0 as the actor consumes)
+     - HGET hero:job:{job_id} status (should transition to started then finished)
+     - HGET hero:job:{job_id} output (should contain the script result)
+
+- Option B: Run the standalone actor binary and dispatch from another process that pushes to the canonical type queue.
+  1) Start the actor:
+     - cargo run --bin actor_osis
+  2) From any producer, LPUSH hero:q:work:type:osis {job_id} after persisting the job hash hero:job:{job_id}.
+  3) Use the same redis-cli checks above to confirm consumption and completion.
+
+Notes:
+- Hash-only result model is the default. The job result is written to hero:job:{job_id}.output and status=finished.
+- Reply queues (hero:q:reply:{job_id}) are optional and not required for OSIS to function.