add some documentation for blue book

docs/job-format.md

@@ -0,0 +1,179 @@
+# Job Format
+
+Jobs are the fundamental unit of work in Horus.
+
+## Structure
+
+```rust
+pub struct Job {
+    pub id: String,              // Unique job identifier
+    pub runner_id: String,       // Target runner ID
+    pub payload: String,         // Job payload (script/command)
+    pub timeout: Option<u64>,    // Timeout in seconds
+    pub env_vars: HashMap<String, String>, // Environment variables
+    pub signatures: Vec<Signature>, // Cryptographic signatures
+    pub created_at: i64,         // Creation timestamp
+    pub status: JobStatus,       // Current status
+}
+```
+
+## Job Status
+
+```rust
+pub enum JobStatus {
+    Pending,    // Queued, not yet started
+    Running,    // Currently executing
+    Completed,  // Finished successfully
+    Failed,     // Execution failed
+    Timeout,    // Exceeded timeout
+    Cancelled,  // Manually cancelled
+}
+```
+
+## Signature Format
+
+```rust
+pub struct Signature {
+    pub public_key: String,  // Signer's public key
+    pub signature: String,   // Cryptographic signature
+    pub algorithm: String,   // Signature algorithm (e.g., "ed25519")
+}
+```
+
+## Creating a Job
+
+### Minimal Job
+
+```rust
+use hero_job::Job;
+
+let job = Job::new(
+    "my-runner",
+    "print('Hello World')".to_string(),
+);
+```
+
+### With Timeout
+
+```rust
+let job = Job::builder()
+    .runner_id("my-runner")
+    .payload("long_running_task()")
+    .timeout(300) // 5 minutes
+    .build();
+```
+
+### With Environment Variables
+
+```rust
+use std::collections::HashMap;
+
+let mut env_vars = HashMap::new();
+env_vars.insert("API_KEY".to_string(), "secret".to_string());
+env_vars.insert("ENV".to_string(), "production".to_string());
+
+let job = Job::builder()
+    .runner_id("my-runner")
+    .payload("deploy_app()")
+    .env_vars(env_vars)
+    .build();
+```
+
+### With Signature
+
+```rust
+use hero_job::{Job, Signature};
+
+let job = Job::builder()
+    .runner_id("my-runner")
+    .payload("important_task()")
+    .signature(Signature {
+        public_key: "ed25519:abc123...".to_string(),
+        signature: "sig:xyz789...".to_string(),
+        algorithm: "ed25519".to_string(),
+    })
+    .build();
+```
+
+## Payload Format
+
+The payload format depends on the target runner:
+
+### Hero Runner
+Heroscript content:
+```heroscript
+!!git.list
+print("Repositories listed")
+!!docker.ps
+```
+
+### SAL Runner
+Rhai script with SAL modules:
+```rhai
+let files = os.list_dir("/tmp");
+for file in files {
+    print(file);
+}
+```
+
+### Osiris Runner
+Rhai script with Osiris database:
+```rhai
+let users = osiris.model("users");
+let user = users.create(#{
+    name: "Alice",
+    email: "alice@example.com"
+});
+```
+
+## Job Result
+
+```rust
+pub struct JobResult {
+    pub job_id: String,
+    pub status: JobStatus,
+    pub output: String,      // Stdout
+    pub error: Option<String>, // Stderr or error message
+    pub exit_code: Option<i32>,
+    pub started_at: Option<i64>,
+    pub completed_at: Option<i64>,
+}
+```
+
+## Best Practices
+
+### Timeouts
+- Always set timeouts for jobs
+- Default: 60 seconds
+- Long-running jobs: Set appropriate timeout
+- Infinite jobs: Use separate monitoring
+
+### Environment Variables
+- Don't store secrets in env vars in production
+- Use vault/secret management instead
+- Keep env vars minimal
+- Document required variables
+
+### Signatures
+- Always sign jobs in production
+- Use strong algorithms (ed25519)
+- Rotate keys regularly
+- Store private keys securely
+
+### Payloads
+- Keep payloads concise
+- Validate input data
+- Handle errors gracefully
+- Log important operations
+
+## Validation
+
+Jobs are validated before execution:
+
+1. **Structure**: All required fields present
+2. **Signature**: Valid cryptographic signature
+3. **Runner**: Target runner exists and available
+4. **Payload**: Non-empty payload
+5. **Timeout**: Reasonable timeout value
+
+Invalid jobs are rejected before execution.