operating-graph

atrib operating graph

This is the complete open-source reference client for live, bounded atrib operating views. It reads signed records from a local mirror, verifies their signatures, and projects application state for a selected workspace, task, team, or agent.

The client demonstrates one application profile. It does not add fields, event types, or graph edges to the atrib protocol.

What it proves

• Named workspace, task, team, and agent views over verified records.
• Body-aware search over private mirror content.
• Live accepted-state, decision, outcome, handoff, and resolution updates.
• Conflicts that stay visible while more than one active head exists.
• Application resolution that names every active head, cites every head through informed_by, and selects one accepted head in the private body.
• Incoming handoffs that make a task visible in the receiving agent's view.
• Explicit proof posture. A verified signature and a supplied log proof are rendered as separate facts.
• Private application bodies enter a view only when they match the signed record's args_hash.
• Source-neutral D183 observation batches can enter a caller-owned atomic journal without becoming semantic state or execution evidence.
• Buzz observer windows can appear in a separate runtime-observation feed without becoming accepted state, decisions, outcomes, handoffs, or resolutions.

This client does not prove that every action was captured or that a signed claim is true. Coverage manifests, protected executors, counterparty evidence, and witness evidence address different parts of that problem.

Run the demo

From the repository root:

pnpm install --frozen-lockfile
pnpm --filter @atrib/operating-graph build
pnpm --filter @atrib/operating-graph demo

Open http://127.0.0.1:8797. The demo creates a temporary signed mirror with two named agents, a visible conflict, a resolution, an outcome, and a handoff. It does not submit records to a public log.

Run against a local mirror

ATRIB_OPERATING_MIRROR="$HOME/.atrib/records" \
pnpm --filter @atrib/operating-graph start

The default address is http://127.0.0.1:8797. Reads are always available. Writes require both ATRIB_OPERATING_WRITES=enabled and a nonempty ATRIB_OPERATING_WRITE_TOKEN. The process refuses to start in write mode without the token.

Variable	Default	Purpose
ATRIB_OPERATING_MIRROR	~/.atrib/records	JSONL mirror file or directory
ATRIB_OPERATING_HOST	127.0.0.1	HTTP bind address
ATRIB_OPERATING_PORT	8797	HTTP port
ATRIB_OPERATING_POLL_MS	1000	Mirror polling interval
ATRIB_OPERATING_TRUSTED_CREATORS	unset	Comma-separated creator-key allowlist
ATRIB_OPERATING_WRITES	disabled	Set to enabled to expose signed write routes
ATRIB_OPERATING_WRITE_TOKEN	unset	Bearer secret required by both POST routes
ATRIB_OPERATING_BODY_TOKEN	unset	Bearer secret that enables body opening
ATRIB_OPERATING_ARCHIVE_URL	unset	Optional archive fallback for signed bodies
ATRIB_OPERATING_ARCHIVE_TOKEN	unset	Optional bearer token for the archive fallback
ATRIB_OPERATING_CORS	*	CORS origin for API clients

An omitted creator allowlist accepts every locally verified signer. That is convenient for a personal mirror, but it is not an identity policy. Shared deployments should configure the allowlist or place an authenticated policy layer in front of the service.

Event body profile

The signed record remains a normal atrib observation or revision record. Its private _local.content body uses this application schema:

{
  "schema": "atrib.operating-event.v1",
  "kind": "decision",
  "workspace": { "id": "workspace-1", "name": "Apollo" },
  "task": { "id": "task-1", "name": "Ship reference client" },
  "team": { "id": "team-1", "name": "Protocol" },
  "agent": { "id": "agent-alice", "name": "Alice", "role": "builder" },
  "subject": "database",
  "value": { "selected": "sqlite" },
  "source": "operating-graph-demo"
}

Kinds are accepted_state, decision, outcome, handoff, and resolution. Handoffs use from_agent and to_agent. A resolution includes accepted_head plus resolves, and its signed record must cite every hash in resolves through informed_by.

Application state is deliberately body-aware. Public log commitments alone do not reveal names, state values, or resolution choices. The reader requires an args_hash and verifies _local.content against it before parsing an application event. A missing commitment, invalid salt, or mismatched body excludes the record from the operating view.

Runtime observations

buildRuntimeObservation() places a verified D183 batch in a workspace and optional task, team, and mapped-agent scope. The signed body commits the batch ID and bounded coverage summary. It omits raw observations, keeps execution_evidence false, and grants no accepted-state, decision, outcome, handoff, or resolution effect.

commitObservationBatch() is the file-backed reference for the caller-owned acceptance boundary. It verifies the complete portable batch, source and generation binding, expected cursor, signed observation record, and body commitment. One atomic file replacement advances the authoritative cursor and adds the signed observation together. The journal rejects stale or concurrent writers, detects persisted history tampering, and can reclaim a lock whose owning process has exited. A side cursor can be rebuilt from this journal and must not be treated as authoritative.

The generic source profile does not discover runtimes, select source files, store raw telemetry, infer application meaning, or execute tools. Source discovery and polling remain host concerns. A separate signed atrib.operating-event.v1 body must cite the verified observation through both source_observation and informed_by before it can affect an operating view.

Buzz runtime observations

buildBuzzRuntimeObservation() accepts a concrete BuzzObserverRuntimeLogSource, exports and verifies a bounded window, and builds an atrib.operating-runtime-observation.buzz.v1 body. The caller assigns the window to a workspace and can optionally assign a task, team, and mapped_agent. The mapped agent is an application placement. Buzz Nostr authors remain separate in source.observed_agent_pubkeys, and the atrib record signer is the host that signs the observation.

The body commits the full runtime-window manifest and sequence audit. It keeps raw observer payloads out of the portable observation and sets execution_evidence to false. Its trust facts record the observer's claim that its adapter verified the Nostr signatures and recipient-owner match. The operating-graph reader verifies the atrib record signature and body commitment. It does not receive or replay the source frames, manifest, or sequence audit. Those source checks therefore remain claims by the observation signer unless a consumer obtains and verifies the external artifacts. The body does not claim owner authorization, relay admission or persistence, operator audit inclusion, result truth, or capture beyond the requested window.

The caller signs the body through the normal attest() path. It then appears under GET /v1/runtime-observations and in the browser's Runtime observations panel; it never enters the semantic operating view. The workspace index includes observation-only workspaces. To create semantic state from an observation, the application signs a separate atrib.operating-event.v1 body with source_observation and cites the same record hash through informed_by. The reader also requires the cited observation's atrib signature to verify and requires the same named workspace, task, team, and agent. buildBuzzSemanticPromotion() prepares those two linked inputs but does not sign them or choose an application policy.

HTTP surface

Route	Purpose
GET /v1/health	Mirror, revision, write, and trust-policy status
GET /v1/workspaces	Named workspace index
GET /v1/view	Bounded operating view
GET /v1/search	Body-aware search inside the selected scope
GET /v1/runtime-observations	Bounded, non-semantic runtime observations
GET /v1/stream	SSE revision stream with exact reconnect cursors
GET /v1/body/<hash>	Verify and disclose authorized opening material
POST /v1/events	Sign an application event when writes are enabled
POST /v1/resolve	Sign an all-head application resolution

GET /v1/view requires workspace_id. Optional task_id, team_id, and agent_id parameters narrow the view. A signed handoff includes the handed-off task's prior state in the receiving agent's view. cell_limit, head_limit, and event_limit are bounded server-side.

The stream cursor is exclusive. Every event carries the resulting revision as its SSE event ID. A cursor ahead of the local revision returns 409. A cursor behind the current revision receives an explicit gap event so the client reloads its bounded view instead of assuming it saw every intermediate projection.

The runtime-observation route uses the same required workspace_id and optional task, team, and agent filters as the bounded view. It returns at most 200 observations. agent_id selects the caller-owned mapped_agent, not a Buzz Nostr signer.

Body retrieval is disabled until ATRIB_OPERATING_BODY_TOKEN is set. Authorized lookups rehash and verify the signed record. Local mirror lookups also test any available content, tool-name, argument, and result openings against the record commitments before returning them. An archive fallback can return and verify the signed record body, retention state, and proof bundle, but it cannot invent local opening material that the producer never archived.

Both POST routes require Authorization: Bearer <write token>. The browser client asks for the token on the first resolution attempt and keeps it only in session storage.

Container deployment

The compose file mounts the operator's mirror read-only and keeps writes disabled:

docker compose \
  -f apps/operating-graph/deploy/docker-compose.yml \
  up --build

For a hosted deployment, terminate TLS and authentication in a reverse proxy, set ATRIB_OPERATING_TRUSTED_CREATORS, and mount only the mirror data the service should read. Do not expose a writable signing environment in the same container unless the deployment has a deliberate key-custody and policy boundary.

The service is stateless. Reset it by replacing the container. Its source mirror is not application-owned and must not be deleted during a reset.

Fresh-machine proof

After committing the source:

pnpm --filter @atrib/operating-graph prove:fresh-machine

The script exports HEAD into a temporary directory, runs a frozen install, builds the reference client, and executes its tests. It never reads the current checkout's node_modules.

Conformance participation

conformance/operating-view-v1.json pins the application projection for conflicts, all-head resolution, named identities, and handoff visibility. The fixture test consumes that file directly.

Another application can:

1. consume the fixture and publish its result;
2. submit a new fixture that exposes an ambiguous application behavior;
3. demonstrate the same event profile in an independent client; or
4. document why its conflict policy cannot be represented with existing records and informed_by.

Only the fourth case supplies evidence for revisiting a public merge primitive. One application preferring a different UI does not.

Verification

pnpm --filter @atrib/operating-graph typecheck
pnpm --filter @atrib/operating-graph test
pnpm --filter @atrib/operating-graph build
pnpm --filter @atrib/integration open-runtime-composition
pnpm --filter @atrib/integration test -- hostile-operating-graph.test.ts

The open runtime composition uses the public Codex rollout adapter, atomic observation journal, separate signed semantic mapping, bounded view receipt, paired SDK action records, signed D168 coverage, and an independently signed receiver gate. It is a local deterministic fixture. It does not claim a live external session, complete capture, runtime-vendor provenance, telemetry as execution, arbitrary result truth, or a deployed product.

The hostile suite covers checkpoint rollback, result-evidence inconsistency, permit replay and revoked credentials, withheld bodies, conflicting heads, and an action omitted from an event projection.