WorkGraph Reference

WorkGraph is an optional realm-scoped subsystem. Agents mutate general work items through tools. Public RPC and REST expose observability/operator lookup. CLI and trusted in-process hosts add narrow goal and attention controls. Every enabled agent/service instance is constructed with one exact WorkGraphNamespaceGrant { realm_id, namespace }. The grant is immutable and authorizes one namespace only. Cross-realm, cross-namespace, and all_namespaces requests are rejected; callers cannot widen authority by supplying filter fields.

WorkItem

Field	Type	Description
`id`	`WorkItemId`	Unique work item id
`realm_id`	`string`	Realm that owns the item
`namespace`	`WorkNamespace`	Namespace within the realm, default `default`
`title`	`string`	Short title
`description`	`string?`	Optional detail
`status`	`WorkStatus`	Lifecycle status
`priority`	`low	medium	high`	Priority
`completion_policy`	`WorkCompletionPolicy`	Closure policy for goal-like work
`failed_child_join_policy`	`require_success	propagate	accept`	Policy for failed direct children
`cancelled_child_join_policy`	`require_success	propagate	accept`	Policy for cancelled direct children
`labels`	`string[]`	Filtering and grouping labels
`owner`	`WorkOwner?`	Intended owner or assignee
`claim`	`WorkClaim?`	Active claim owner and optional lease
`machine_state`	object	Generated WorkGraph lifecycle machine state
`revision`	`u64`	CAS revision for write tools
`due_at`	RFC3339 timestamp?	Due time
`not_before`	RFC3339 timestamp?	Earliest eligibility time
`snoozed_until`	RFC3339 timestamp?	Snooze gate
`created_at`	RFC3339 timestamp	Creation time
`updated_at`	RFC3339 timestamp	Last update time
`terminal_at`	RFC3339 timestamp?	Terminal time
`external_refs`	`ExternalWorkRef[]`	Typed pointers to external objects
`evidence_refs`	`WorkEvidenceRef[]`	Typed evidence pointers

Statuses

Status	Meaning
`open`	Created and not currently claimed
`in_progress`	Claimed or actively being worked
`blocked`	Not ready because a block exists or machine state is blocked
`completed`	Terminal success
`cancelled`	Terminal cancellation
`failed`	Terminal failure

Terminal items cannot be claimed.

Completion Policies

JSON shape	Meaning
`{"kind":"self_attest"}`	The assigned attention target can request closure directly
`{"kind":"host_confirmed"}`	Typed host confirmation evidence is required
`{"kind":"principal_confirmed"}`	Typed principal confirmation evidence is required
`{"kind":"supervisor","owner_key":{...}}`	The exact supervisor owner key must confirm
`{"kind":"reviewer_quorum","threshold":N}`	`N` distinct reviewer owners must confirm; `N` is 1-64

General public goal creation exposes self_attest. Stronger policies and their typed confirmation evidence require trusted host authority. An attention-bound agent may only tighten a policy monotonically through the injected workgraph_policy_escalate operation.

Edge Kinds

Kind	Meaning
`blocks`	Source must resolve before target can be ready
`parent`	Hierarchical grouping
`related`	Non-blocking association
`supersedes`	Source replaces target
`derived_from`	Source was derived from target

WorkGraph rejects invalid endpoints, self edges, duplicate edges, and cycles for blocks and parent. For blocks, the source satisfies the edge only in completed; failed or cancelled blockers remain unsatisfied. A parent edge points from direct child to parent. Active children keep the parent join unsatisfied. For failed and cancelled children, each parent policy means:

Policy	Join result
`require_success`	Keep waiting; default
`propagate`	Terminalize the parent as failed/cancelled on reconciliation
`accept`	Treat that terminal child as joined

Owners And Claims

WorkOwnerKey.kind is one of:

principal
agent
session
mob
label

Claims are revision-based. Mutating tools require the current expected_revision. Optional leases allow abandoned work to become recoverable through machine- approved transitions. Omit both lease_seconds and lease_expires_at for no expiry. Otherwise use exactly one. Relative leases are 1-31,536,000 seconds; absolute leases must be strictly later than the store observation time. Wall-clock expiry does not mutate a claim. A trusted observer, normally a Schedule-owned sweep, asks WorkGraph to validate the row and atomically commit release plus the lease_expired fact.

Evidence Refs

WorkEvidenceRef contains:

Field	Type	Description
`kind`	`string`	Evidence type, such as `artifact`, `pr`, `log`, `summary`, or `notification`
`id`	`string`	External or Meerkat-owned artifact id
`label`	`string?`	Human label
`summary`	`string?`	Short explanation
`confirmation_kind`	`self_attest	host_confirmation	principal_confirmation	supervisor_confirmation	reviewer_confirmation`?	Typed completion-policy evidence classification
`confirming_owner_key`	`WorkOwnerKey?`	Distinct confirming owner for supervisor/reviewer policy
`execution_binding_id`	`WorkExecutionBindingId?`	Typed provenance reserved to the execution bridge

Evidence refs are pointers. WorkGraph does not own the artifact content. Reserved confirmation classifications cannot be minted by generic workgraph_add_evidence calls.

Events And Durable Facts

WorkGraphEventKind is one of created, updated, readiness_observed, claimed, released, blocked, closed, linked, evidence_added, attention_created, attention_updated, execution_bound, or execution_transitioned. An event may carry typed facts committed with the same mutation:

Fact	Meaning
`item_ready`	This item revision was first observed ready
`lease_expired`	This exact owner/lease was observed expired and released
`namespace_terminal`	The namespace was observed to have no nonterminal work

These are ledger facts, not wake instructions. WorkGraph owns no timer. Snapshots are single-namespace atomic observations containing captured store time, event high-water mark, bounded items, included edges/attention bindings, and machine-derived ready_item_ids.

Goal Attention Bindings

An attention binding targets a session or a lowered owner. Its mode is one of pursue, coordinate, review, falsify, judge, or observe. Its status is active, paused, superseded, or stopped; only the last two are terminal. Delegated authority is one of add_evidence, close_own_review_item, request_closure, or close_if_policy_allows. The active projection also carries bounded item/parent context and its exact binding and item revisions. Reassignment and policy escalation require that current projection.

Flow Execution Bindings

WorkExecutionBinding durably associates one item with one exact Mob Flow attempt.

Field	Type	Description
`binding_id`	`WorkExecutionBindingId`	Stable binding identity
`work_ref`	`WorkItemRef`	Realm, namespace, and item identity
`target`	`mob_flow` target	Mob id, Flow id and digest, run id, and opaque activation parameters
`idempotency_key`	`string`	Caller-stable launch identity
`correlation_id`	UUID	Stable delivery correlation
`supersedes`	binding id?	Previous terminal attempt in the retry chain
`machine_state`	object	Generated execution-handoff lifecycle authority
`created_at`	RFC3339 timestamp	Store-owned creation time

The lifecycle phases distinguish launch request, uncertain launch, running, evidence projection, closure request, terminal Flow failure or cancellation, policy-refused closure, and successful WorkGraph closure. A retry may supersede only a terminal binding. The store enforces a single append-only retry chain with CAS machine revisions. A machine-derived, indexed recovery projection contains only nonterminal obligations, so host reconciliation does not scan or deserialize historical terminal bindings. The crash-safe launch sequence is binding commit, external-delivery begin, deterministic pending-run persistence, delivery realization claim, and Mob run start. realizing therefore implies that the exact run was already persisted. begun without a run is an abandonable uncertain launch. realizing without a run is quarantined as an invariant breach or legacy-corruption case. The WorkGraph bridge has no caller-asserted break-glass transition out of that state. It fails closed until the exact run is observed or a future sealed host authority is introduced. Every terminal Flow outcome creates evidence kind mob_flow_run_completed, mob_flow_run_failed, or mob_flow_run_canceled with the deterministic id work_execution:<binding_id>. Only completed-run evidence proceeds to a WorkGraph closure request. Exact evidence replay is a no-op; different content under the same evidence id fails closed. The typed execution_binding_id provenance is reserved to the execution bridge; the display id is never read as authority. If a completed run disappears before its evidence commits, the execution machine converts the attempt to a run-lost failure rather than closing the WorkGraph item without proof.

Public MCP

Tool	Purpose
`meerkat_workgraph_flow_launch`	Commit a binding before launch, start its exact Mob Flow run, and reconcile visible results
`meerkat_workgraph_flow_reconcile`	Resume the machine-owned handoff from its first incomplete durable boundary
`meerkat_workgraph_flow_abandon_uncertain`	Under binding-revision CAS and host custody, resolve an ambiguous launch only after its deterministic run is absent, then require a superseding retry
`meerkat_workgraph_flow_binding_get`	Read one redacted execution linkage
`meerkat_workgraph_flow_binding_list`	List bounded redacted execution linkages

meerkat_mob_flow_status includes the corresponding redacted execution binding when the run was created by this bridge. Activation parameters, idempotency keys, correlation ids, and execution principals remain internal to the trusted realm host. The durable store journal retains full execution events for deterministic rebuild, but the general workgraph_events projection omits those event kinds. Public consumers observe execution through the redacted binding and Flow-status projections, so activation parameters and execution principals never cross the coarse WorkGraph event-read boundary. expected_item_revision is required when creating a new binding. An exact idempotent replay selects the existing binding even if later evidence changed the item revision. A changed effective Flow run configuration cannot be launched under an older binding digest.

Agent Tools

Tool	Purpose
`workgraph_create`	Create a work item
`workgraph_get`	Read one item
`workgraph_list`	List items
`workgraph_ready`	List machine-derived ready items
`workgraph_snapshot`	Read items, edges, ready ids, scope, timestamp, and event high-water mark
`workgraph_events`	Read event history
`workgraph_claim`	Claim an item with CAS revision
`workgraph_release`	Release an active claim
`workgraph_update`	Update mutable item fields
`workgraph_block`	Put an item into blocked state
`workgraph_close`	Close as `completed`, `cancelled`, or `failed`
`workgraph_link`	Add a graph edge
`workgraph_add_evidence`	Add an evidence reference
`workgraph_attention_reassign`	Reassign the active attention binding under its exact authority projection
`workgraph_policy_escalate`	Monotonically tighten completion policy under active attention authority

The last two tools are injected only when a turn carries a matching active attention projection. Their arguments cannot manufacture delegated authority.

RPC

Method	Purpose
`workgraph/get`	Read one item
`workgraph/list`	List items
`workgraph/ready`	List ready items
`workgraph/snapshot`	Read graph snapshot
`workgraph/events`	Read event history
`workgraph/goal/status`	Read goal and attention status
`workgraph/attention/list`	List attention bindings

General WorkGraph item mutation remains tool-owned. Attention reassignment and policy escalation are authority-bearing WorkGraph tool operations injected into turns with active attention, not public RPC methods.

REST

Method	Path	Purpose
`GET`	`/workgraph/items`	List items
`GET`	`/workgraph/items/{id}`	Read one item
`GET`	`/workgraph/ready`	List ready items
`GET`	`/workgraph/snapshot`	Read graph snapshot
`GET`	`/workgraph/events`	Read event history
`POST`	`/workgraph/goal/status`	Read goal and attention status
`POST`	`/workgraph/attention/list`	List attention bindings

The GET routes use query parameters such as realm_id, namespace, all_namespaces, statuses, labels, include_terminal, limit, and after_seq for events. The POST /workgraph/goal/status and POST /workgraph/attention/list routes accept JSON request bodies. all_namespaces remains present in generic filter wire shapes and CLI syntax, but the standard public services hold one namespace grant and reject it. A future/bespoke host needs a separate explicit multi-namespace capability; a namespace grant never implies one.

CLI

rkat workgraph list [--namespace <NS>] [--all-namespaces] [--status <STATUS>] [--label <LABEL>] [--include-terminal] [--limit <N>] [--json]
rkat workgraph show <ID> [--namespace <NS>] [--json]
rkat workgraph ready [--namespace <NS>] [--label <LABEL>] [--limit <N>] [--json]
rkat workgraph snapshot [--namespace <NS>] [--all-namespaces] [--status <STATUS>] [--label <LABEL>] [--include-terminal] [--limit <N>] [--json]
rkat workgraph events [--namespace <NS>] [--all-namespaces] [--after-seq <N>] [--limit <N>] [--json]
rkat workgraph goal-create <SESSION_ID> <TITLE> [--namespace <NS>] [--description <TEXT>] [--mode <MODE>] [--completion-policy self-attest|host-confirmed] [--json]
rkat workgraph goal-status <BINDING_ID> [--namespace <NS>] [--json]
rkat workgraph goal-confirm <BINDING_ID> --expected-revision <N> --kind <KIND> --id <ID> [--namespace <NS>] [--label <TEXT>] [--summary <TEXT>] [--json]
rkat workgraph goal-close <BINDING_ID> --expected-revision <N> [--status completed|cancelled|failed] [--namespace <NS>] [--json]
rkat workgraph attention-list [--namespace <NS>] [--status <STATUS>] [--json]
rkat workgraph attention-pause <BINDING_ID> --expected-revision <N> [--namespace <NS>] [--json]
rkat workgraph attention-resume <BINDING_ID> --expected-revision <N> [--namespace <NS>] [--json]

CLI commands use the same realm flags as other rkat commands. On standard surfaces, select the granted namespace (normally default) and do not pass --all-namespaces.

Companion Skill

workgraph-workflow is an embedded builtin companion skill gated by the work_graph capability. It teaches agents how to use the WorkGraph tool family. It is discoverable through the normal skills inventory and is not automatically preloaded.

Reference

Architecture

Historical Implementation Records

Operations

WorkGraph Reference

WorkGraph Reference

WorkItem

Statuses

Completion Policies

Edge Kinds

Owners And Claims

Evidence Refs

Events And Durable Facts

Goal Attention Bindings

Flow Execution Bindings

Public MCP

Agent Tools

RPC

REST

CLI

Companion Skill

​WorkGraph Reference

​WorkItem

​Statuses

​Completion Policies

​Edge Kinds

​Owners And Claims

​Evidence Refs

​Events And Durable Facts

​Goal Attention Bindings

​Flow Execution Bindings

​Public MCP

​Agent Tools

​RPC

​REST

​CLI

​Companion Skill

WorkGraph Reference

WorkItem

Statuses

Completion Policies

Edge Kinds

Owners And Claims

Evidence Refs

Events And Durable Facts

Goal Attention Bindings

Flow Execution Bindings

Public MCP

Agent Tools

RPC

REST

CLI

Companion Skill