English | 简体中文

Workstate

The governed work-state layer where a task is a verifiable provenance chain — origin, dependencies, ownership, transitions, and evidence — not a to-do.

Part of Octopus Core — the open infrastructure stack for governed AI. One job per repo, along the agent lifecycle: Scout · Observe · Experience · Blackboard · Runtime · Replay — with Inspect governing every stage. The whole stack rides one root primitive — the shared Evidence atom.

This repo — Workstate: Track where work came from and why it moved state — not just whether it's done.

observation / decision → WorkItem → transitions (evidence chain) → done + proof
                                       ↑ every move is verifiable Evidence

Most task tools store a status flag: can it be done, who's on it, is it finished? Workstate stores the provenance of the work itself: where it came from (its originating observation or decision), who owns it, what it depends on, and — for every state change — a piece of octopus-evidence Evidence committed to a tamper-evident audit chain. An external auditor holding only the exported trail can run verifyAuditTrail() (or WorkStateGraph.restore()) and confirm the whole history — chain, evidence, and state-machine reachability — without trusting the store. Set WORKSTATE_SECRET (keyed mode) when the store operator isn't trusted; unkeyed mode proves consistency and reachability, not authorship (details).

Quick start

import { WorkStateGraph } from "octopus-workstate";

const graph = new WorkStateGraph();

// Work exists because something was observed — not because someone typed a to-do.
graph.add({
  id: "WORK-1",
  title: "Review flagged AI draft",
  origin: { originType: "observation", ref: { type: "observation", id: "obs-4821" } },
});

graph.transition("WORK-1", "ready", { by: { id: "alice", kind: "human", source: "oidc" } });
graph.transition("WORK-1", "claimed", { by: { id: "alice", kind: "human" } });
graph.transition("WORK-1", "in_progress", { by: { id: "alice", kind: "human" } });
graph.transition("WORK-1", "done", {
  by: { id: "alice", kind: "human" },
  reason: "Draft accurate; signed off.",
  evidence: [{ evidenceId: "ev-review-hash", kind: "human-oversight" }],
});

graph.history("WORK-1"); // the item's 来时的路 — every move, in order
graph.verify(); // { ok: true } — the audit chain re-verifies independently

Run the end-to-end example: node --import tsx examples/triage.ts.

CLI (agent-friendly, zero third-party deps)

The octopus-workstate bin is a beads-style interface over a JSONL store that is the tamper-evident audit chain. Every command takes --json for agents. The npm package also installs workstate as a short alias, which the examples below use.

# a structured work-origin ref (where this work came from), not just free text
workstate add WORK-1 "Review flagged draft" --origin observation --ref-type observation --ref-id obs-4821
workstate add WORK-0 "Capture AI SOAP draft"
workstate link WORK-1 WORK-0            # WORK-1 blocks on WORK-0
workstate ready --json                  # the pull queue (WORK-0; WORK-1 is gated)
workstate transition WORK-0 ready --by scribe --by-kind agent
workstate transition WORK-0 done  --by scribe   # ... after claimed → in_progress
workstate history WORK-1                # the item's transition-provenance chain
workstate anchor                        # print {length, head} to retain as a truncation anchor
workstate verify                        # re-verify the audit chain (exit 1 on tamper)

The store (.workstate/state.jsonl) is append-only and git-diffable: a pull request shows exactly which work moved state and why it moved. Set WORKSTATE_SECRET to key (HMAC) the chain so no act can be forged or reordered without it. Edit or reorder any line by hand and verify reports it (exit 1); loading the store refuses it. Tail truncation (dropping the last lines) is caught by pinning a retained anchor (verify --expect-length <n> --expect-head <hash>) — see docs/DESIGN.md.

What it is

• A dependency graph with a ready queue. link(a, b) says a blocks on b; ready() returns the items nothing is gating — the queue an agent pulls from.
• A governed state machine. Items move proposed → ready → claimed → in_progress → done (with blocked / failed / cancelled); only legal moves are permitted.
• An audit chain. Every transition is minted as Evidence and appended to a tamper-evident chain. verify() re-checks it; keyed (HMAC) mode makes moves unforgeable without the secret.
• Accountable by construction. Each item carries a DecisionLink (its work-origin — where it came from) and each transition carries the acting Actor and any cited EvidenceRefs.

Boundaries (what Workstate is not)

This is a single-responsibility repo. It is deliberately not its neighbours:

• Not Experience. Experience owns causal learning / belief / knowledge — what the system concluded and why it's trusted. Workstate only records work-item transition provenance — where a work item is and why it moved state. Different object: knowledge-causality vs work-causality.
• Not Blackboard. Blackboard is shared cognition — what agents are thinking together (free-form shared memory). Workstate is structured work — what tasks exist, where they came from, and in what state. Different noun: shared state vs work state. (Even "claim" differs: in Workstate a work item enters the claimed state / holds a resource lease; on Blackboard you claim a note on the board — don't conflate them.)
• Not Runtime. Runtime answers "should this action execute?" for one action. Workstate tracks the state of the work across many actions. A runtime decision (or its Principal) is something a Workstate transition consumes — Workstate never reimplements the gate.
• Not Observe. An Observation is the origin a WorkItem points back to, not something Workstate produces.
• Not an issue tracker. No projects, sprints, comments, or UI. It is the work-state fact layer those tools would sit on top of.

It has zero third-party dependencies: its only runtime dependency is the first-party octopus-evidence, which provides the canonical hashing and tamper-evident chain. Interop with Runtime Principal and Observe Observation is type-level — no hard dependency on either.

How it compares

octopus-workstate is not a better issue tracker, orchestration engine, or agent framework — it is the verifiable work-state fact layer those sit on top of. Across ~20 tools (beads, Jira, Linear, Temporal, Airflow, Dagster, LangGraph, CrewAI, …), none ships all three of: a tamper-evident verifiable chain, structured work-origin provenance, and store-untrusting independent verification. Full, candid analysis — including where competitors are genuinely ahead — in docs/COMPETITIVE.md; the value case in docs/ROI.md; the architecture in docs/DESIGN.md.

Status

v0.2.0 — matured: event-sourced over a verifiable Evidence chain, with JSONL persistence, an agent CLI, resource leases, and independent verifyAuditTrail() / restore(). Deferred to a commercial operations layer (by design): UI/dashboards, multi-tenant hosting, and out-of-band anchor retention for tail-truncation detection.

License

Apache-2.0 · © Ran Tao · part of Octopus Core.