Skip to content

Releases

DoSync 0.9.0

Choose a tag to compare

@github-actions github-actions released this 12 Oct 04:03
e707f02

The release that closes the reengineering: SAMUEL as a standard of its own with
DoSync as its reference hub, a hub a person can govern without a terminal, the
hub's devices published as governed W3C WoT Things, and three ways to install it
(pipx, one docker run, a Home Assistant add-on).

Added

  • W3C WoT: the hub's devices as governed Things (spec §5.10). GET /v1/things and
    GET /v1/things/{id} serve each device as a TD 1.1 (application/td+json, validated against the
    official schema in the tests); GET /.well-known/wot describes the hub's Thing Description Directory
    (WoT Discovery), public and naming no device. Every form addresses the hub, never the device:
    POST /v1/things/{id}/actions/{name} fires operate_device with that one proposal (source wot), so
    G1–G9 apply as to an agent — 200 done, 202 held_for_confirmation when the operator marked it,
    403 with the reason when SAMUEL or a policy stopped it, 404 for an undeclared action (absent from the TD
    too). GET /v1/things/{id}/properties/{name} answers the last value a device reported. The exporter moved
    from tools/ into the package (dosync/wot_export.py); exported TDs used to point at the direct-control
    path, closed by default, so a WoT consumer following them was refused.
  • Interoperability tested with an independent WoT consumer. CI job wot-interop: Eclipse Thingweb
    node-wot discovers the hub, reads a production cell's TD, runs one action, gets another held for a person,
    reads a property — from the TD alone (tests/test_wot_interop.py, tools/wot_interop/).
  • Container image, amd64 + arm64, published by CI (.github/workflows/release.yml): docker run -d -p 47200:47200 -v dosync-data:/data ghcr.io/giulianireg-spec/dosync-protocol:latest. MCP included,
    everything under /data, smoke-tested before it is pushed. Authentication is now on in the image
    (it was off): a container listens on the network; the token is printed in the log on first start.
  • Home Assistant add-on (repository.yaml, homeassistant-addon/) on the same image. Its options
    become the hub's settings (dosync-container), and the bridge connects through the Supervisor with the
    add-on's own token.
  • Release workflow: on a v* tag, the image (<version>, latest), PyPI by trusted publishing, and a
    GitHub release with this file's section. edge image from main.
  • samuel-certify S21: the agent's credential is not accepted as the operator's (22 checks).

Changed

  • The policy combination rule is the SAMUEL kernel's (H6). How the operator's policies combine over a
    plan — priority order, first denial decides, modifications accumulate, emergencies ask only absolute
    restrictions — moved from PolicyEngine.evaluate into dosync/samuel/policing.py, with
    PolicyDecision, PolicyResult and BasePolicy. dosync.policies re-exports them and its engine
    delegates. The deployment's policies stay outside the kernel.

Security

  • An operator credential equal to an agent credential is not honoured (H5). If DOSYNC_OPERATOR_TOKEN
    is also the hub token, the demo token or a stored API key, the agent could release its own holds. The hub
    still starts, does not accept that value as the operator's, logs an ERROR, and reports
    operator_credential: same_as_agent in /v1/status, /v1/governance, /samuel/v0 and the dashboard.
    Creating an agent key equal to the operator token is refused.
  • A policy that fails no longer lets the plan through (H7). A policy that raised was skipped, so an
    operator's restriction with a bug was silently a pass. Outside an emergency the plan is now blocked with
    reason policy_error; in an emergency the failure is recorded and does not block (evacuation is never
    blocked by the hub). Audited as policy_error.

Added (since 0.8.0, before this release)

  • A person can govern the hub from the dashboard, without a terminal. What SAMUEL reserves to a person
    had endpoints and no page, so its guarantees held for developers only. The dashboard now has ⏸
    (every action held for confirmation, with Confirm/Deny), Governance (where each device is, what it does
    in an emergency, and which actions must wait for a person) and Agent (the MCP configuration for the
    agent you use, with this hub's address and command filled in). Backed by GET /v1/confirmations (all
    holds, oldest first), GET /v1/governance, PUT /v1/governance/confirmation-marks and
    GET /v1/agent/connect. Confirmation marks set here are kept by the hub, add to the deployment policy file
    (which stays read-only to the hub), hold exactly like it, are audited (confirmation_marks_changed) and
    always need the operator credential — removing a mark removes a restriction. The operator credential is
    kept for the browser tab only (sessionStorage), never with the hub token.
  • dosync-mcp: runs the MCP server, --print-config prints the block any MCP client pastes (this
    installation's interpreter, hub address, token), --check says in words what is missing. The step that
    stopped non-developers — which python, inside a pipx venv they never see — is no longer theirs to work out.
  • CI job pipx-path on Linux and macOS runs the README's path as a person would: pipx install, inject
    MCP, dosync-hub, dashboard served, dosync-mcp --check, and an agent started from the printed
    configuration listing tools and calling dosync_get_status (tools/smoke_mcp_stdio.py).

Fixed

  • Certify mode is isolated from the machine it runs on. On the Pi it loaded /etc/dosync/policies.json,
    the deployment's .env (with a real phone number) and a notifier. It now loads a policy file only when
    DOSYNC_POLICIES names one, and neither .env nor notifications. An in-memory database is reported as
    such, not as a …/:memory: path that never existed.

Changed

  • The SAMUEL kernel: the nine guarantees decided in one place (dosync/samuel/). If the agent is the mind
    and the devices the body, DoSync is the nervous system, and this is the part of it that decides what may
    pass. Extracted, not rewritten: admission of an intent as a whole (samuel.admit), validation of proposed
    actions (samuel.validate_proposals), the no-oscillation guard (samuel.OscillationGuard) and the
    confirmation split (samuel.split_by_confirmation) moved out of server.py, resolvers.py and hub.py
    unchanged; those call the kernel now. The kernel imports nothing of DoSync but its data models and has no
    I/O (tests/test_samuel_kernel_boundary.py fails otherwise). Resolution stays outside it: it is one more
    way of proposing, and the hub validates proposals itself, so a hub whose resolver is external no longer
    refuses every proposal as resolver_cannot_validate. Behaviour is otherwise identical: suite, certification
    (CONFORMANCE 72/72), the laboratory's parity and the fourth comparison's replay (144/144 identical) give the
    same results before and after.

Added

  • SAMUEL 0.2 (spec/SAMUEL-SPEC-v0.2.md), normative on its own. Rules R1–R12 stated in SAMUEL itself
    (the protocol's §6.8 now defers to it), a threat model (hub and operator credential trusted; the attacker
    controls the agent's inputs and does not know what the operator marked), the lifecycle of a hold, the
    record, an HTTP binding (§11) and conformance (§12). §13 says what was measured against a misled agent and
    that the guarantees are tested, not formally verified. v0.1 is kept, marked superseded.

  • The SAMUEL HTTP binding, /samuel/v0 (dosync/samuel_http.py). Eight operations in SAMUEL's model —
    a device is {actions, sensors, place, emergency_capable, emergency_actions}, not a Capability Manifest —
    with two credentials: the agent's (bearer) fires intents; the operator's (X-Operator-Token) places
    devices, defines classes, releases or denies holds and reads the record. No explain. Policies are set
    over it only in conformance mode.

  • samuel-certify (dosync/samuel_certify.py). The conformance suite any hub runs against the binding:
    standard library only, 21 checks mapped to G1–G9, a scene of a production cell, a line and a hangar bay.
    The reference hub conforms (21/21, tests/test_samuel_conformance.py); CI runs it after dosync-certify.

  • DOSYNC_CONFIGURATION_CREDENTIAL (hub | operator; default hub). SAMUEL reserves to the operator
    where a device is, what it does in an emergency and which intent classes exist (a class is a grant of
    authority). On /v1 these took the hub credential — the one an agent's tools also hold — so an agent with
    HTTP access and the token could move a device, change its emergency actions or register a class that a
    policy on operate_device did not cover. The default stays as it was, by the deployment's choice: the hub
    warns once at start while configuration is open and reports the setting (/v1/status
    configuration_credential, /samuel/v0 configuration). With operator (and DOSYNC_OPERATOR_TOKEN
    set), PATCH /v1/devices/{id} changing a place or emergency actions, POST /v1/things and
    POST /v1/devices/register carrying them, and creating or deleting an intent class need X-Operator-Token;
    a rename does not. SAMUEL conformance requires operator (samuel-certify S01). dosync-certify sends the
    operator credential, when it has one, on its own configuration requests only.

Fixed

  • A class that grants actions but names no tags resolved to sensor reads. resolve() decided "status
    query" on the absence of tags alone, while explain() looked at tags and actions — so a class defined in
    SAMUEL's model (which has no tags) listed in explain the devices it would act on and then read their
    sensors instead. Rule 1 says tags only rank. No production class was affected (the only tagless class with
    grants, operate_device, acts only on proposals). Found by `samuel-certify...
Read more

DoSync Protocol v0.3.0

Choose a tag to compare

@giulianireg-spec giulianireg-spec released this 09 Jun 17:43

What's new in v0.3.0

New components

MQTT transport adapter — Layer 1 HAL via Mosquitto broker. Devices register, send events, and receive commands over MQTT. Authenticated via DOSYNC_MQTT_SECRET. Includes LWT, QoS 1, exponential backoff, and retained message cleanup on device DELETE.

ExternalResolver — HTTP wire protocol (RESOLVER-SPEC v0.3 §5) for language-independent resolver implementations. Auto-fallback to CapabilityMatchingResolver on error. HTTPS support via DOSYNC_RESOLVER_CA_CERT.

Protocol improvements

  • Severity enum separated from Urgency — event classification and response priority are now distinct types
  • bypass_on_emergency configurable per policy — BlockIntentPolicy sets bypass_on_emergency=False; operator blocks are absolute and cannot be overridden by emergency urgency
  • DeviceActuatorRateLimitPolicy — DB-backed persistence via rate_limit_log table; rate limit windows survive hub restarts
  • Enriched intent_blocked audit entries with urgency, source, emergency_override fields; distinct emergency_intent_blocked_by_policy type

Operational

  • Hub version bumped to 0.3.0
  • Heartbeat endpoint exposes MQTT transport status (transports.mqtt.*)
  • purge_rate_limit_events() on startup — prevents unbounded DB growth
  • config/mosquitto-secure.conf — secure Mosquitto configuration example in repo
  • Systemd secrets file enforced chmod 600

Certification

Tier Tests Status
Basic 10/10 ✅
Standard 32/32 ✅ (was 22)
Emergency 35/35 ✅ (was 32)

Independent implementation

dosync-node — Node.js implementation, Standard 32/32, own CI, own repo.

CI/CD

GitHub Actions workflow on every push and PR — 6 steps (syntax, imports, Severity regression, resolver scoring, hub startup, policy engine), ~41s.


Full specification: spec/DOSYNC-SPEC-v0.1.md
Resolver spec: spec/RESOLVER-SPEC-v0.3.md