Repository navigation
Releases
DoSync 0.9.0
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/thingsand
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/wotdescribes 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}firesoperate_devicewith that one proposal (sourcewot), so
G1–G9 apply as to an agent — 200done, 202held_for_confirmationwhen 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
fromtools/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.edgeimage frommain. - 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 fromPolicyEngine.evaluateintodosync/samuel/policing.py, with
PolicyDecision,PolicyResultandBasePolicy.dosync.policiesre-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_agentin/v1/status,/v1/governance,/samuel/v0and 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
reasonpolicy_error; in an emergency the failure is recorded and does not block (evacuation is never
blocked by the hub). Audited aspolicy_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 byGET /v1/confirmations(all
holds, oldest first),GET /v1/governance,PUT /v1/governance/confirmation-marksand
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-configprints the block any MCP client pastes (this
installation's interpreter, hub address, token),--checksays 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-pathon 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 callingdosync_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_POLICIESnames one, and neither.envnor 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 ofserver.py,resolvers.pyandhub.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.pyfails 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 asresolver_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. Noexplain. 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 afterdosync-certify. -
DOSYNC_CONFIGURATION_CREDENTIAL(hub|operator; defaulthub). 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/v1these 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 onoperate_devicedid 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/v0configuration). Withoperator(andDOSYNC_OPERATOR_TOKEN
set),PATCH /v1/devices/{id}changing a place or emergency actions,POST /v1/thingsand
POST /v1/devices/registercarrying them, and creating or deleting an intent class needX-Operator-Token;
a rename does not. SAMUEL conformance requiresoperator(samuel-certify S01).dosync-certifysends 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, whileexplain()looked at tags and actions — so a class defined in
SAMUEL's model (which has no tags) listed inexplainthe 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...
DoSync Protocol v0.3.0
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
Severityenum separated fromUrgency— event classification and response priority are now distinct typesbypass_on_emergencyconfigurable per policy —BlockIntentPolicysetsbypass_on_emergency=False; operator blocks are absolute and cannot be overridden by emergency urgencyDeviceActuatorRateLimitPolicy— DB-backed persistence viarate_limit_logtable; rate limit windows survive hub restarts- Enriched
intent_blockedaudit entries withurgency,source,emergency_overridefields; distinctemergency_intent_blocked_by_policytype
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 growthconfig/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