SyberWork

Contracts govern work. A case history records what was proposed, admitted, observed, approved, and executed.

This is a running application, with a browser operator console, a versioned contract studio, a policy boundary, source-system readers, action executors, an external planner interface, human approval, completion checks, and amendment replay. It is separate from SyberLabs' existing cross-platform instrument panel: the panel inspects existing research systems; SyberWork executes contracts.

The syberlabs package is the reusable core: canonical JSON, the event hash chain, a JCS digest and rule id beside that chain, an HMAC witness and an Ed25519 signature of the chain head, an append-only transparency log in a separate file, a witness process that holds the signing key, the admission rules, the planner interface, and an in-memory Session for a project that does not use this application's database. New events record at as integer microseconds inside the hash. A case database from main still uses float seconds and still verifies. syberwork is the application: storage, the HTTP API, the CLI, the console, and connectors. syberlabs does not import syberwork. Both install from this repository at one version. The protocol those objects follow is sdk.syberlabs.space/v0alpha1 in spec/.

Build Thread: governed changes to your own repository

syberlabs init
syberlabs start "Add a CSV export" --paths src tests
syberlabs propose --from-worktree      # or --command ./your-model-adapter
syberlabs check c1                     # the host runs your checks on c1's exact tree
syberlabs accept c1                    # moves refs/heads/syberlabs/<thread>; never pushes or merges
syberlabs status                       # resume from the journal in any terminal

Candidates are Git commits on non-authoritative refs, written without touching your working tree. A model's claim that tests pass is shown as an unverified signal; only the host's own run counts. Acceptance is an admitted, compare-and-swap branch update, and an interrupted one is settled with syberlabs recover. Pushing, opening a pull request, and running a publish command are separate admitted actions after acceptance (syberlabs publish push_branch), each idempotent and reconcilable. python examples/build_thread.py runs the whole path without a model. See docs/BUILD_THREAD.md.

An EvoGit-style evolutionary search (syberlabs propose --evolve ./mutator, or EvolutionaryProvider) is one more provider behind the same interface. Its population lives on non-authoritative refs, its selection uses the host's own check results, and a person still accepts. python examples/evolve.py runs it on a toy fixture. See docs/EVOLUTION.md. Whether search beats one model patch at the same cost is measured by benchmarks/model_vs_patch.py; it has not been run against a real model yet (docs/MODEL_COMPARISON.md).

Use the SDK on another project

examples/release_gate.py is a software release gate. It does not import syberwork and it does not talk to the procurement ERP.

PYTHONPATH=. python examples/release_gate.py

A project installs a contract, a policy, and local actions on syberlabs.Session, then observes, proposes, commits, approves, signs, explains, and replays. Session.commit runs admission again and only then records a local effect. explain_admission returns the deciding rule and its provenance and does not write them into the hash chain. HTTP effects and economic reservations stay on syberwork.Work.

A contract may add an optional evolution section. It lets a search provider (a person's patch, a model adapter, or an EvoGit-style search) propose provisional candidates with Git lineage, and fixes the mutable scope, operators, budget, checks, and promotion authority. A candidate is promoted only through ordinary admission plus candidate.promotable: a human-origin proposal, the host's own passing evaluation of the candidate's exact tree, and any required approval. Lineage is provenance, not evidence of superiority. See docs/EVOLUTION.md.

examples/access_review.py is a second project: a quarterly access review. Development notes are in docs/SDK_FEEDBACK.md. The standards gap and the order to close it are in docs/SDK_REDTEAM.md.

PYTHONPATH=. python examples/access_review.py
PYTHONPATH=. python benchmarks/run_bench.py

Start

Python 3.11 or newer; no runtime dependencies. In the project directory:

python -m syberwork.cli --home .syberwork init
python examples/reference_system.py --database .reference/system.sqlite3

In a second terminal:

python -m syberwork.cli --home .syberwork serve

Open http://127.0.0.1:8766/. Save the credentials printed by init somewhere private. The server retains only their hashes in .syberwork/users.json; init will never overwrite them. Use a different credential for each identity. All API routes except static assets require a bearer token. The service binds only to loopback.

examples/reference_system.py is a separate SQLite-backed source of inventory, supplier quotes, and orders. It is a real HTTP integration with durable order writes, version headers, idempotency keys, and conditional writes. Its seeded inventory record is P-104; its supplier quote is Q-7 at 250. Replace its fixed URLs and data with actual customer systems by publishing new source and action names.

Complete the included case

1. Connect as operator. Create contract purchase-order version 1 with input {"part_number":"P-104","quantity":2}.
2. Refresh key part_number from source inventory, record key P-104. Refresh key quote from source supplier, record key Q-7. The returned ETags and selected values are stored as observations. Manually typed observations remain marked verified: false and cannot satisfy this contract.
3. Connect as scheduler and choose Propose next compiled step. record_review is proposed with its argument bound to the verified inventory observation. Execute that proposal. The review becomes a case event.
4. Propose the next compiled step. issue_order receives the observed part number, quote, price, quote ID, and quote version. The decision requests independent manager approval.
5. Connect as manager, select the proposal from case history, and approve it. Reconnect as scheduler, select the same proposal, and execute. SyberWork submits a real POST to the reference source's /orders with an Idempotency-Key and If-Match header. The order is stored in the other database. You can fetch it from http://127.0.0.1:8999/orders/{id} using the ID in the effect response.
6. Reconnect as manager and sign off. The case becomes complete only after the order effect and the later signoff. Verify history checks the per-case hash chain.

The Contract & connector studio accepts immutable contract and policy JSON documents. The compiler produces a dependency-ordered known path when one is not authored, plus inspectable action gates, acceptance queries, and an input form schema. Publish a higher version, then use Amendment replay to compare decisions against the recorded history. Replay makes no model calls, destination writes, or live source reads.

External planners

To run a planner, set SYBERWORK_PLANNER_URL to an HTTPS or loopback endpoint and optionally set SYBERWORK_PLANNER_TOKEN. Connect with the planner credential and click Ask configured planner, or POST to /api/cases/{id}/suggest. The endpoint receives JSON containing objective, allowed_actions, contract, events, and acceptance. It must return JSON shaped like:

{"action":"record_review","args":{"part_number":"P-104"}}

This output only creates a proposal. Admission rechecks the bound observation, global policy, roles, prior effects, and required approval. The planner receives no executor credential. The configured endpoint is the HttpPlanner behind the syberlabs planner interface; a planner cannot do anything except return {action, args}. The scheduler credential generates the next proposed compiled step directly from fact bindings; neither proposer can bypass the case API.

API and data ownership

• POST /api/contracts, /api/policies, /api/actions/{name}, /api/sources/{name}: administrator publication.
• POST /api/cases: create a case pinned to a contract version.
• POST /api/cases/{id}/refresh: fetch and record a versioned fact from a configured source.
• POST /api/cases/{id}/facts: record a manually asserted fact, tagged as unverified.
• POST /api/cases/{id}/resolution-request, /resolution-resolve, /resolution-escalate, /cancel: open a source-backed decision task, verify its authoritative resolution, escalate it after its deadline, or close the case explicitly.
• POST /api/cases/{id}/proposals, /compiled, /suggest: human, compiled, or model proposal.
• POST /api/cases/{id}/candidates, /searches (search or operator credential), /evaluations (evaluator credential); GET /api/cases/{id}/candidates: provisional candidates for a contract with an evolution section. See docs/EVOLUTION.md.
• POST /api/cases/{id}/approve, /commit, /signoff, /reconcile: decision operations.
• GET /api/cases/{id}, /verify; POST /api/cases/{id}/replay: inspection and counterfactual comparison.

The case SQLite database is authoritative for SyberWork decisions and observed responses. The source systems remain authoritative for inventory, quotes, and purchase orders. An observation stores its source, record version, observed value, observation time, and whether it came from a configured connector. An action rechecks admission when committed. The reference destination checks the quote version at write time. For an unknown result, a manager may trigger the installed destination status lookup. SyberWork requires a committed record with the original idempotency key and exact request digest before recording verified success. A 404 remains pending and blocks another effect of the same action; a manager cannot assert success with a text reference. Explicit adapter-declared no-write precondition rejections can release a fresh proposal. See reconciliation contract.

Economic actions

An administrator can install an economic_http action with a fixed settlement service URL, same-origin status lookup, asset, rail and counterparty. Its global policy gives the action an exact atomic-unit limit and a budget shared across cases. The contract binds amount_units to a verified quote and requires evidence observations; a proposed purchase_capability or transfer includes their hashes, purpose and expiry. SyberWork admission (the economic.reserve rule in syberlabs.admission) checks these again at commit, reserves budget atomically, and only then invokes the settlement service. A missing or mismatched receipt remains uncertain and keeps the reservation until destination status proves the outcome. The economic action contract includes the wire requirements and limits. The tests run against a local settlement simulator and move no funds. This adapter is not an x402 implementation or on-chain finality verifier.

Verification

PYTHONPATH=. python -m unittest discover -s tests -v
PYTHONPATH=. python -m conformance.run
python -m conformance.clean_install

conformance/clean_install builds the wheel, installs it into a new virtual environment, and runs the two SDK examples from a directory outside this checkout. It fails if syberlabs or syberwork is imported from the repository instead of the installed wheel. conformance/run recaptures the case-study and admission traces and diffs them against conformance/golden. It exits nonzero on any difference. The unit tests include a case database created on main (a2f909b) and check that verify_chain and replay still accept it.

The tests cover the full case, independent approval, policy precedence, model and compiled proposals, amendment replay, tamper detection, concurrent-action claims, a real local HTTP source reader, an HTTP effect with its idempotency key, and simulated economic settlements with shared budgets and reconciliation. A passing test demonstrates those paths in this implementation. It does not establish that a new customer's source systems, payment provider or policies have been integrated correctly.

Resolution tasks

A versioned contract can declare a resolution with an owner role, escalation role, deadline, source-backed trigger and choices, a result path tied to the case input, and actions blocked until the decision is verified. An operator refreshes the trigger and choices and requests a task. The assigned owner updates the source system with its own credentials; clicking Verify source decision reads the configured source again and closes the task only if its version changed and its selection matches one of the recorded options and the correct case. Merely choosing a candidate in the console cannot complete the task. The console shows open, overdue, escalated, completed, and cancelled tasks; a manager can escalate after the due time or cancel an unresolved case with a reason. Source-system write access is independent of the SyberWork token. See resolution task contract.

Executed enterprise case study

Case Study 001 executes ten procurement scenarios against a separate synthetic ERP. The missing-site and competing-quote paths now continue through role checked source-system changes to valid orders; a separate unresolved quote path ends in explicit manager cancellation. The recorded run contains case events, source updates, and external order snapshots. Run it with PYTHONPATH=. python -m case_studies.enterprise_procurement. This is a simulation with fictional data, not a customer deployment.

Deployment boundary

The included service is local and single-installation. Its role-bearing tokens are provisioned locally. It does not provide SSO, multi-tenant isolation, a distributed transaction with an external API, a customer-specific semantic layer, or an automatic translation from arbitrary prose into a correct contract. The interface requires human review of published contracts. Preserve the .syberwork database and credentials together when moving the installation. A hash chain detects accidental editing against its local history; it does not prevent a database owner from replacing and rehashing the whole chain.

A cell is the deployment that comes after that appliance: one organization, one database, one runtime. Work talks to SQLite or PostgreSQL through the same stores. syberwork worker finishes effects that were claimed and then interrupted. syberwork backup and restore move the cell. The loopback default remains. Set SYBERWORK_BIND only when the process should listen on another address. Details and the limits are in Industrial Cell v0.1.

License

Apache License 2.0. See LICENSE and NOTICE.