KwestKarz Log Chain Specification - wwestlake/KwestKarz GitHub Wiki

KwestKarz Log Chain Specification

This specification defines how time-based, user-scoped blockchain-style logs are managed to ensure tamper-evident, verifiable audit trails for real-world actions like task completion, employee check-ins, or shift tracking.

📘 Chain Definition

Each log chain is implicitly defined by:

Account (User ID or Email)
Date Range (e.g., a week)
Starting Entry: PreviousHash = null
Ending Entry: Action = "CHAIN_END"

Chains are not tracked separately — they are discovered and validated entirely by structure and content.

🔗 LogEntry Fields

{
  "id": "guid",
  "timestamp": "datetime",
  "action": "string",
  "result": "string",
  "account": "string",
  "category": "string",
  "type": "string",
  "previousHash": "string",
  "hash": "string"
}

🧭 Chain Validation Rules

Every chain starts with a record where PreviousHash = null
Each subsequent log must:
- Include the hash of the prior log
- Have a Hash value computed from full content + previous hash

A valid chain ends with:

{
  "action": "CHAIN_END",
  "category": "System",
  "type": "Info",
  "result": "Finalized"
}

No logs may be added after CHAIN_END appears
Each chain must be validated from root to end before appending

🧾 Chain Sealing Process

The system (or admin) creates a final log entry:

{
  "action": "CHAIN_END",
  "category": "System",
  "type": "Info",
  "result": "Finalized",
  "account": "[email protected]",
  "timestamp": "datetime"
}

This entry is linked just like any other with PreviousHash
Its hash becomes the terminal point for the chain

🔍 Chain Discovery

To locate a user's chain for a given week:

Query logs by Account
Filter by date range (e.g., week start/end)
Find the log with PreviousHash = null
Traverse forward
Stop when CHAIN_END is encountered

🔐 Benefits

Tamper-evident audit trails
Clean, finite chains per week per user
Append-only design enforces log integrity
Chain sealing supports downstream analytics, pay cycles, or inspection