Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ Open `http://127.0.0.1:8766/`. Save the credentials printed by `init` somewhere
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.
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, and the witness's signed heads when a witness log is configured.

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.

Expand All @@ -93,7 +93,7 @@ This output only creates a proposal. Admission rechecks the bound observation, g
- `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}/facts`: record a manually asserted fact, tagged as unverified. It is refused (`attestation_denied`) for a key the contract reads (a required fact, an argument binding, a fact acceptance clause, or a resolution's evidence), unless a required fact names this same source and does not ask for verification. A key the contract never reads is recorded and decides nothing.
- `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](docs/EVOLUTION.md).
Expand Down Expand Up @@ -128,7 +128,7 @@ A versioned contract can declare a resolution with an owner role, escalation rol

## 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.
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. When serve reads the witness's log (`SYBERWORK_WITNESS_LOG`, `SYBERWORK_WITNESS_PUBLIC`), Verify history and `syberwork verify` also check the heads the witness signed, which are outside the database, so a history rewritten after a head was signed fails. Events after the newest signed head, and an installation with no witness log, keep the chain's limit, and the verify response says which applies.

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](docs/INDUSTRIAL_CELL.md).

Expand Down
2 changes: 1 addition & 1 deletion docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,6 @@ For each past proposal, replay evaluates a selected new contract and policy agai

## Integration

HTTP sources and effects are bound by administrator-installed definitions and do not accept an LLM-provided destination URL. Authorization headers use environment variable names in definitions; secrets never enter the contract. Cross-origin redirects are blocked. Source URLs and the planner URL go through `trusted_origin`. HTTPS must name a public host; loopback HTTP stays `127.0.0.1` with a port. `guard_request` checks the addresses HTTPS resolves to before the call and refuses a name it cannot resolve; a host with percent-escapes or other characters `urllib.request` would rewrite is refused before it is classified. The credentialed openers ignore `http_proxy`/`https_proxy` (`targets.credentialed_opener`), so a bearer token is never handed to an environment proxy, and their HTTPS connections are pinned: each resolves and checks its host again and dials only the addresses it accepted, keeping the name for SNI and Host. IANA special-purpose ranges are refused explicitly rather than by `is_global` alone. Header values (`If-Match` from `version_arg`) are refused if they hold a line break, control character or edge whitespace, before the effect is claimed. A manual attestation (`POST /api/cases/{id}/facts`) may not set a key the case's contract reads from another source or only verified, and an `observer`-only credential reads no case, contract, certificate, metric or builder view. The console document refuses framing (`frame-ancestors 'none'`). The signing key for a chain head is not stored in the case database. `python -m syberlabs.witness` holds that seed in a separate process, checks the chain, and appends to the transparency log. `WitnessClient` keeps the public key and opens the log read-only. The log refuses to open a file that already has a `cases` table. A process running as the same OS user can still open the file writable, and an operator who holds the seed can rebuild the log. It is not a public transparency service. Model suggestions are proposals accepted under separate model-bearing credentials, never direct network effects. The included `reference_system.py` is one fully running integration. `translate_stabilize` is a tested translator for one SyberRuntime outcome, not a live adapter. Barn, OmniOS, and customer tools still need adapters matching their authority and event semantics. The other rows in `spec/MAPPINGS.md` stay proposed.
HTTP sources and effects are bound by administrator-installed definitions and do not accept an LLM-provided destination URL. Authorization headers use environment variable names in definitions; secrets never enter the contract. Cross-origin redirects are blocked. Source URLs and the planner URL go through `trusted_origin`. HTTPS must name a public host; loopback HTTP stays `127.0.0.1` with a port. `guard_request` checks the addresses HTTPS resolves to before the call and refuses a name it cannot resolve; a host with percent-escapes or other characters `urllib.request` would rewrite is refused before it is classified. The credentialed openers ignore `http_proxy`/`https_proxy` (`targets.credentialed_opener`), so a bearer token is never handed to an environment proxy, and their HTTPS connections are pinned: each resolves and checks its host again and dials only the addresses it accepted, keeping the name for SNI and Host. IANA special-purpose ranges are refused explicitly rather than by `is_global` alone. Header values (`If-Match` from `version_arg`) are refused if they hold a line break, control character or edge whitespace, before the effect is claimed. A manual attestation (`POST /api/cases/{id}/facts`) may not set a key the case's contract reads from another source or only verified, and an `observer`-only credential reads no case, contract, certificate, metric or builder view. The console document refuses framing (`frame-ancestors 'none'`). The signing key for a chain head is not stored in the case database. `python -m syberlabs.witness` holds that seed in a separate process, checks the chain, and appends to the transparency log. `WitnessClient` keeps the public key and opens the log read-only. The log refuses to open a file that already has a `cases` table. A process running as the same OS user can still open the file writable, and an operator who holds the seed can rebuild the log. It is not a public transparency service. Verify history (`Work.verify_history`: `GET /api/cases/{id}/verify`, `syberwork verify`) reads that log when one is configured: `valid` is false when a signed head conflicts with the case (`head_differs`, `beyond_history`, `chain_broken`), so a history the database owner rewrote and rehashed after signing fails. The response carries `chain`, `witness` (`witnessed_through`, `count`, `conflicts`, or null without a log) and a note saying what the check could not see; events after the newest signed head are covered by the chain alone. Model suggestions are proposals accepted under separate model-bearing credentials, never direct network effects. The included `reference_system.py` is one fully running integration. `translate_stabilize` is a tested translator for one SyberRuntime outcome, not a live adapter. Barn, OmniOS, and customer tools still need adapters matching their authority and event semantics. The other rows in `spec/MAPPINGS.md` stay proposed.

The [`economic_http` effect](ECONOMIC_ACTIONS.md) adds exact atomic units and a cross-case budget reservation to this same admission boundary. Its trusted settlement service is a separate authority; SyberWork records that service's matching receipt and status assertion, not independent blockchain finality.
2 changes: 1 addition & 1 deletion docs/console/NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ tab or choose **Forget all** to drop them.
| 7 | manager | **Approve** (press twice) | The armed button names the action, the role, and the exact arguments the approval binds to. |
| 8 | scheduler | **Execute** (press twice) | A real POST to the reference system with `Idempotency-Key` and `If-Match`; *Applied · destination acknowledged HTTP 201*. Only the original proposer can execute; anyone else gets *only the original proposer (scheduler) may execute* with a switch link. |
| 9 | manager | **Sign off as manager** | The sign-off is offered only after `issue_order` has applied, because the server accepts an earlier signature but it never satisfies the clause. The case becomes *Complete*. |
| 10 | any | History (`5`), then `v` | The server's `/verify` result is recorded with the head it covered (`intact through #13 …`). It is marked stale when newer events arrive. |
| 10 | any | History (`5`), then `v` | The server's `/verify` result is recorded with the head it covered (`intact through #13 …`). It is marked stale when newer events arrive. With a witness log configured, `/verify` is also invalid when a signed head conflicts with the history (`Work.verify_history`). |
| 11 | manager | History → Witness → **Ask witness to sign** (press twice) | Before: *not witnessed*. Another credential sees the button disabled with *manager role required to ask the witness* and **⇄ switch to manager** (the role is `SYBERWORK_WITNESS_ROLE`). The armed note says the witness appends a leaf that cannot be removed and nothing is written to the case. After: *Witness signed #1–#13*, the panel reads *witnessed through #13* with the leaf, its signed head and *in the log*, and the button is disabled: *a signed head in the log already covers #1–#13*. An event added later is listed as *not witnessed*, and asking again signs the longer history. Without a configured log, **Witness** reads *not configured* and names the variables. |

If the destination is down at step 8, the effect becomes *Outcome unknown · check destination*, the
Expand Down
42 changes: 37 additions & 5 deletions syberlabs/publish.py
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
from syberlabs import critic, outcome
from syberlabs.checks import _stop
from syberlabs.errors import Rejected
from syberlabs.gitspace import Repo
from syberlabs.session import NoWrite
from syberlabs.targets import credentialed_opener, guard_request, trusted_origin

Expand Down Expand Up @@ -189,6 +190,31 @@ def validate(doc: dict) -> None:
raise _bad(f"unknown field {sorted(unknown)[0]} for {effect}")


def _bounded(argv: list[str], env: dict, timeout: float) -> tuple[int | None, str]:
"""Run ``argv`` to completion or to ``timeout``; ``(None, "")`` when the deadline ended it.

The command runs in its own session (POSIX) and a timeout ends that session, or the process tree on
Windows, through ``checks._stop``: ``subprocess.run(timeout=...)`` ends ``git`` and leaves a transport
it started, such as ``ssh``, running past the publish. Output is read from a file, never a pipe, so a
child that keeps the pipe open cannot hold the call past its deadline.
"""
with tempfile.TemporaryFile() as out:
proc = subprocess.Popen(argv, env=env, stdin=subprocess.DEVNULL, stdout=out, stderr=subprocess.DEVNULL,
start_new_session=hasattr(os, "setsid"))
deadline = time.monotonic() + timeout
while proc.poll() is None:
if time.monotonic() > deadline or os.fstat(out.fileno()).st_size > MAX_OUTPUT:
_stop(proc)
return None, ""
time.sleep(0.02)
out.seek(0)
return proc.returncode, out.read(MAX_OUTPUT).decode(errors="replace")


def _git_env() -> dict:
return {**os.environ, "GIT_TERMINAL_PROMPT": "0", "LC_ALL": "C"}


class _Publisher:
"""Shared plumbing: the thread a proposal belongs to, and bounded subprocesses."""

Expand All @@ -211,8 +237,12 @@ def _lease(self, case_id: str) -> str:
return "" if "{thread}" in self.doc.get("branch", "syberlabs/{thread}") else self._thread(case_id).base

def _remote_head(self, ref: str) -> str | None:
raw = self.kit.repo.git("ls-remote", self.doc["remote"], ref, timeout=self.timeout)
for line in raw.decode().splitlines():
# The same argv and scrubbed environment as ``Repo.git``, under a deadline that ends the transport too.
code, text = _bounded(["git", "-C", str(self.kit.repo.root), "-c", "core.fsmonitor=false",
"ls-remote", self.doc["remote"], ref], Repo._env(), self.timeout)
if code != 0:
raise RuntimeError("ls-remote did not finish")
for line in text.splitlines():
commit, _, name = line.partition("\t")
if name == ref:
return commit
Expand All @@ -222,9 +252,11 @@ def apply(self, case_id: str, args: dict, key: str) -> dict:
ref = "refs/heads/" + self._branch(case_id)
argv = ["git", "-C", str(self.kit.repo.root), "push", "--porcelain",
f"--force-with-lease={ref}:{self._lease(case_id)}", self.doc["remote"], f"{args['commit']}:{ref}"]
done = subprocess.run(argv, capture_output=True, text=True, timeout=self.timeout,
env={**os.environ, "GIT_TERMINAL_PROMPT": "0", "LC_ALL": "C"})
flags = [line.split("\t") for line in done.stdout.splitlines() if "\t" in line]
code, text = _bounded(argv, _git_env(), self.timeout)
if code is None:
# The deadline ended the push and everything it started; the remote may or may not have the ref.
raise RuntimeError("push outcome unknown")
flags = [line.split("\t") for line in text.splitlines() if "\t" in line]
mine = next((f for f in flags if len(f) >= 2 and f[1].endswith(":" + ref)), None)
if mine and mine[0] in ("*", " ", "="):
return {"destination": f"git:{self.doc['remote']}:{ref}", "external_id": args["commit"]}
Expand Down
2 changes: 1 addition & 1 deletion syberwork/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ def main():
elif args.command == "inspect":
print(json.dumps(db.inspect(args.case_id), indent=2))
elif args.command == "verify":
print(json.dumps({"valid": db.verify_chain(args.case_id)}))
print(json.dumps(db.verify_history(args.case_id, _witness_log(parser))))


if __name__ == "__main__":
Expand Down
28 changes: 28 additions & 0 deletions syberwork/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -1237,6 +1237,34 @@ def verify_chain(self, case_id: str) -> bool:
with self.tx() as db:
return self.chain_ok(db, case_id)

def verify_history(self, case_id: str, log=None) -> dict:
"""``GET /api/cases/{id}/verify`` and ``syberwork verify``: the hash chain, and the witness's log when one is read.

The chain alone (``chain``) catches an edit that was not rehashed. Whoever owns the database can rewrite an
event and rehash every event after it, and the chain still verifies. A head the witness signed is outside the
database, under a key the database owner does not hold, so with ``log`` (``TransparencyLog.open_readonly``)
a rewritten, truncated or rehashed history shows as a conflict (``head_differs``, ``beyond_history``,
``chain_broken``) and ``valid`` is false. Without a log, or for events after ``witnessed_through``, ``valid``
is the chain's answer and the note says what it cannot see. Events are read once, in one transaction.
"""
with self.tx() as db:
chain = self.chain_ok(db, case_id)
events = self._events(db, case_id)
if log is None:
return {"valid": chain, "chain": chain, "witness": None,
"note": "Hash chain only: it does not detect a history rewritten and rehashed by the database owner. "
"Read a witness log (SYBERWORK_WITNESS_LOG, SYBERWORK_WITNESS_PUBLIC) to check against signed heads"}
status = self._witness_judgement(case_id, events, log)
conflicts = [entry for entry in status["entries"] if entry["verdict"] in WITNESS_CONFLICTS]
through = status["witnessed_through"]
note = ("A head the witness signed conflicts with this history: it was changed after signing" if conflicts else
f"Chain checked, and events #1 to #{through} match a head the witness signed" if through else
"Chain checked; the witness has signed no head of this case yet, so a rehash would not show")
return {"valid": chain and not conflicts, "chain": chain,
"witness": {"witnessed_through": through, "count": status["count"],
"conflicts": [{"index": e["index"], "count": e["count"], "verdict": e["verdict"]} for e in conflicts]},
"note": note}

def side_channel(self, case_id: str) -> list[dict]:
"""JCS digest and deciding rule id for each new event. Neither is in the event hash.

Expand Down
Loading
Loading