dosync 0.5.0__tar.gz → 0.6.1__tar.gz

{dosync-0.5.0 → dosync-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dosync
-Version: 0.5.0
+Version: 0.6.1
 Summary: The semantic layer between AI agents and physical devices
 Author-email: Rodrigo Giuliani <rgiuliani@dosync.dev>
 License-Expression: Apache-2.0
@@ -194,7 +194,7 @@ DoSync earns its place in specific situations — and honestly gets in the way i
 - Have a single device or one brand's ecosystem — you don't need a coordination layer.
 - Don't need auditability or a policy layer.
 
-**If the first list is you:** the fastest way in is the **[20-minute device tutorial](TUTORIAL.md)** — build a device that senses, expresses a goal, and acts, with the full audit trail. Or open an [issue](https://github.com/giulianireg-spec/dosync-protocol/issues) describing what you're trying to coordinate and we'll tell you honestly whether DoSync fits.
+**If the first list is you:** the fastest way in is the **[20-minute device tutorial](docs/DEVICE-INTEGRATION.md)** — build a device that senses, expresses a goal, and acts, with the full audit trail. Or open an [issue](https://github.com/giulianireg-spec/dosync-protocol/issues) describing what you're trying to coordinate and we'll tell you honestly whether DoSync fits.
 
 ---
 
@@ -249,6 +249,20 @@ Benchmark (Raspberry Pi 5, Python 3.11.2):
 
 ---
 
+## Where to start
+
+| You want to… | Go to |
+|---|---|
+| **run a hub and see your devices** | [Quick start](#quick-start), below — about five minutes, no terminal after the first command |
+| **build a device that speaks the protocol** | [docs/DEVICE-INTEGRATION.md](docs/DEVICE-INTEGRATION.md) — needs Docker, a broker and Python |
+| **implement DoSync yourself, or check conformance** | [spec/](spec/) — the wire format, the JSON schemas, and `certify.py` |
+| **understand why it is built this way** | [DESIGN-PRINCIPLES.md](DESIGN-PRINCIPLES.md) |
+| **know its scope, or who decides** | [docs/VISION.md](docs/VISION.md) · [GOVERNANCE.md](GOVERNANCE.md) |
+
+Three of those four were reachable only by guessing. The one called `TUTORIAL.md`
+sat in the repository root, where a reader looks first, and asked for Docker in
+its first step.
+
 ## Quick start
 
 ### Install and run — five minutes, no hardware
@@ -283,6 +297,10 @@ Two things the rest of this page assumes that PowerShell does not provide:
 `curl.exe`, or the PowerShell examples further down. `setup_pki.sh` is a shell
 script and needs Git Bash or WSL.
 
+If a control library for your hardware needs installing afterwards, a plain
+`pip install` will not reach it — `pipx` keeps the hub in its own isolated
+environment. See **pipx inject**, below.
+
 </details>
 
 ### Then open the dashboard
@@ -502,6 +520,22 @@ The operator runs `pip install dosync-adapter-daikin` and the hub finds it. No
 pull request here, and no promise from this project to maintain code for
 hardware it has never seen — the publisher answers for their own adapter.
 
+**If DoSync itself was installed with `pipx`, a plain `pip install` lands in
+the wrong environment.** `pipx` deliberately isolates the hub in its own
+virtual environment, separate from the system Python, so a vendor library
+installed the ordinary way is invisible to it — the hub stays silent about
+this exactly as it does about an uninstalled one, because from its side
+there is no difference. Install into the hub's own environment instead:
+
+```bash
+pipx inject dosync dosync-adapter-daikin
+```
+
+This is not specific to any one vendor's product: it is how you add *any*
+optional dependency — a control library, a third-party adapter package, a
+protocol SDK — after installing DoSync with `pipx`. Whichever hardware you
+own, `pipx inject dosync <package>` is the command, not `pip install`.
+
 A third-party adapter runs inside the hub with the hub's permissions, so the hub
 says so: it is logged at WARNING when loaded, recorded in the audit chain, and
 reported as `kind: third_party` at `/v1/adapters` regardless of what the plugin
@@ -654,6 +688,104 @@ pytest                                  # runs the full suite
 dosync-hub --reload
 ```
 
+The hub stops when the terminal closes. To keep it running across reboots, see
+[Keeping the hub running](#keeping-the-hub-running).
+
+---
+
+## Keeping the hub running
+
+Everything above starts a hub in a terminal, and it stops when that terminal
+closes. Nothing in this project has explained how to change that — while the
+repository has shipped a systemd unit at its root for months and this page
+refers to *"your service"* as though you already had one. That gap is the
+reason this section exists.
+
+DoSync does not implement supervision on any platform. It delegates: to systemd
+on Linux, to the task scheduler on Windows. What differs between them is how
+much you have to write, not whether it works.
+
+**Say once what is at stake:** a hub that governs physical actions and does not
+come back after a power cut is a deployment decision with consequences. If a
+lock, an alarm or a machine depends on it, this is not optional.
+
+### Linux — systemd
+
+`dosync.service` in the repository root is a template. Adjust the paths, then:
+
+```bash
+sudo cp dosync.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now dosync
+systemctl status dosync
+```
+
+**Keep secrets out of the unit.** It is a file people copy, and this one carried
+a real Home Assistant token in a public repository until August 2026. Put them
+in a drop-in that is not tracked:
+
+```bash
+sudo install -d -m 700 /etc/systemd/system/dosync.service.d
+sudo tee /etc/systemd/system/dosync.service.d/local.conf >/dev/null <<'EOF'
+[Service]
+Environment="HA_TOKEN=your-token-here"
+EOF
+sudo chmod 600 /etc/systemd/system/dosync.service.d/local.conf
+sudo systemctl daemon-reload && sudo systemctl restart dosync
+```
+
+systemd merges drop-ins over the unit, so the template never needs editing.
+
+### Windows — Task Scheduler
+
+*Verified on Windows 11 ARM64 in a virtual machine, Python 3.14, installed with
+`pipx`.*
+
+Run PowerShell **as administrator**:
+
+```powershell
+$exe = (Get-Command dosync-hub).Source
+$db  = "$env:USERPROFILE\.local\state\dosync\dosync.db"
+
+$action = New-ScheduledTaskAction -Execute "cmd.exe" `
+  -Argument "/c set DOSYNC_DB=$db && `"$exe`""
+$trigger   = New-ScheduledTaskTrigger -AtStartup
+$principal = New-ScheduledTaskPrincipal -UserId "SYSTEM" `
+  -LogonType ServiceAccount -RunLevel Highest
+$settings  = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries `
+  -DontStopIfGoingOnBatteries -RestartCount 3 `
+  -RestartInterval (New-TimeSpan -Minutes 1)
+
+Register-ScheduledTask -TaskName "DoSync Hub" -Action $action `
+  -Trigger $trigger -Principal $principal -Settings $settings
+```
+
+`-AtStartup` with `SYSTEM` means the hub comes back after a reboot without
+anyone logging in — the closest equivalent to systemd. `-RestartCount` covers a
+process that dies.
+
+**`DOSYNC_DB` is not optional, and leaving it out fails silently.** A scheduled
+task does not inherit your environment, so a hub started this way writes to
+`C:\Windows\System32\config\systemprofile\` — a different database from the
+one you used by hand. It starts perfectly, reports `devices: 0`, and looks like
+your inventory was lost. Setting `DOSYNC_DB` points both at the same file;
+running it by hand afterwards reads what the scheduled task wrote, with no
+permission conflict.
+
+Check it:
+
+```powershell
+curl.exe -s http://localhost:47200/v1/status | findstr db_path
+Get-ScheduledTask -TaskName "DoSync Hub" | Get-ScheduledTaskInfo
+```
+
+`LastTaskResult: 267009` is `0x41301` — *the task is currently running*. That is
+the healthy value here; `0` would mean it exited.
+
+**NSSM** installs the hub as a real Windows service and is what a server
+deployment would use. It is third-party software this project does not ship or
+test, so it is named rather than recommended.
+
 ---
 
 ## What's built today
@@ -726,7 +858,7 @@ is implementable in a second language against the same certification suite —
 both share the same author. A genuinely **independent** implementation
 (different author or organization) is a tracked milestone for v1.0: a protocol
 needs multiple independent implementations to become a standard. See the
-[roadmap](ROADMAP.md).
+[vision and scope](docs/VISION.md).
 
 ---
 
@@ -757,7 +889,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, including the C
 - [spec/DoSync-SPEC-v0.1.md](spec/DoSync-SPEC-v0.1.md) — full protocol specification
 - [spec/RESOLVER-SPEC-v0.3.md](spec/RESOLVER-SPEC-v0.3.md) — resolver interface + external resolver protocol
 - [DESIGN-PRINCIPLES.md](DESIGN-PRINCIPLES.md) — architectural decisions and rationale
-- [COMPATIBILITY.md](COMPATIBILITY.md) — backward compatibility guarantees
+- [COMPATIBILITY.md](docs/COMPATIBILITY.md) — backward compatibility guarantees
 
 ---
 

{dosync-0.5.0 → dosync-0.6.1}/README.md

@@ -132,7 +132,7 @@ DoSync earns its place in specific situations — and honestly gets in the way i
 - Have a single device or one brand's ecosystem — you don't need a coordination layer.
 - Don't need auditability or a policy layer.
 
-**If the first list is you:** the fastest way in is the **[20-minute device tutorial](TUTORIAL.md)** — build a device that senses, expresses a goal, and acts, with the full audit trail. Or open an [issue](https://github.com/giulianireg-spec/dosync-protocol/issues) describing what you're trying to coordinate and we'll tell you honestly whether DoSync fits.
+**If the first list is you:** the fastest way in is the **[20-minute device tutorial](docs/DEVICE-INTEGRATION.md)** — build a device that senses, expresses a goal, and acts, with the full audit trail. Or open an [issue](https://github.com/giulianireg-spec/dosync-protocol/issues) describing what you're trying to coordinate and we'll tell you honestly whether DoSync fits.
 
 ---
 
@@ -187,6 +187,20 @@ Benchmark (Raspberry Pi 5, Python 3.11.2):
 
 ---
 
+## Where to start
+
+| You want to… | Go to |
+|---|---|
+| **run a hub and see your devices** | [Quick start](#quick-start), below — about five minutes, no terminal after the first command |
+| **build a device that speaks the protocol** | [docs/DEVICE-INTEGRATION.md](docs/DEVICE-INTEGRATION.md) — needs Docker, a broker and Python |
+| **implement DoSync yourself, or check conformance** | [spec/](spec/) — the wire format, the JSON schemas, and `certify.py` |
+| **understand why it is built this way** | [DESIGN-PRINCIPLES.md](DESIGN-PRINCIPLES.md) |
+| **know its scope, or who decides** | [docs/VISION.md](docs/VISION.md) · [GOVERNANCE.md](GOVERNANCE.md) |
+
+Three of those four were reachable only by guessing. The one called `TUTORIAL.md`
+sat in the repository root, where a reader looks first, and asked for Docker in
+its first step.
+
 ## Quick start
 
 ### Install and run — five minutes, no hardware
@@ -221,6 +235,10 @@ Two things the rest of this page assumes that PowerShell does not provide:
 `curl.exe`, or the PowerShell examples further down. `setup_pki.sh` is a shell
 script and needs Git Bash or WSL.
 
+If a control library for your hardware needs installing afterwards, a plain
+`pip install` will not reach it — `pipx` keeps the hub in its own isolated
+environment. See **pipx inject**, below.
+
 </details>
 
 ### Then open the dashboard
@@ -440,6 +458,22 @@ The operator runs `pip install dosync-adapter-daikin` and the hub finds it. No
 pull request here, and no promise from this project to maintain code for
 hardware it has never seen — the publisher answers for their own adapter.
 
+**If DoSync itself was installed with `pipx`, a plain `pip install` lands in
+the wrong environment.** `pipx` deliberately isolates the hub in its own
+virtual environment, separate from the system Python, so a vendor library
+installed the ordinary way is invisible to it — the hub stays silent about
+this exactly as it does about an uninstalled one, because from its side
+there is no difference. Install into the hub's own environment instead:
+
+```bash
+pipx inject dosync dosync-adapter-daikin
+```
+
+This is not specific to any one vendor's product: it is how you add *any*
+optional dependency — a control library, a third-party adapter package, a
+protocol SDK — after installing DoSync with `pipx`. Whichever hardware you
+own, `pipx inject dosync <package>` is the command, not `pip install`.
+
 A third-party adapter runs inside the hub with the hub's permissions, so the hub
 says so: it is logged at WARNING when loaded, recorded in the audit chain, and
 reported as `kind: third_party` at `/v1/adapters` regardless of what the plugin
@@ -592,6 +626,104 @@ pytest                                  # runs the full suite
 dosync-hub --reload
 ```
 
+The hub stops when the terminal closes. To keep it running across reboots, see
+[Keeping the hub running](#keeping-the-hub-running).
+
+---
+
+## Keeping the hub running
+
+Everything above starts a hub in a terminal, and it stops when that terminal
+closes. Nothing in this project has explained how to change that — while the
+repository has shipped a systemd unit at its root for months and this page
+refers to *"your service"* as though you already had one. That gap is the
+reason this section exists.
+
+DoSync does not implement supervision on any platform. It delegates: to systemd
+on Linux, to the task scheduler on Windows. What differs between them is how
+much you have to write, not whether it works.
+
+**Say once what is at stake:** a hub that governs physical actions and does not
+come back after a power cut is a deployment decision with consequences. If a
+lock, an alarm or a machine depends on it, this is not optional.
+
+### Linux — systemd
+
+`dosync.service` in the repository root is a template. Adjust the paths, then:
+
+```bash
+sudo cp dosync.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now dosync
+systemctl status dosync
+```
+
+**Keep secrets out of the unit.** It is a file people copy, and this one carried
+a real Home Assistant token in a public repository until August 2026. Put them
+in a drop-in that is not tracked:
+
+```bash
+sudo install -d -m 700 /etc/systemd/system/dosync.service.d
+sudo tee /etc/systemd/system/dosync.service.d/local.conf >/dev/null <<'EOF'
+[Service]
+Environment="HA_TOKEN=your-token-here"
+EOF
+sudo chmod 600 /etc/systemd/system/dosync.service.d/local.conf
+sudo systemctl daemon-reload && sudo systemctl restart dosync
+```
+
+systemd merges drop-ins over the unit, so the template never needs editing.
+
+### Windows — Task Scheduler
+
+*Verified on Windows 11 ARM64 in a virtual machine, Python 3.14, installed with
+`pipx`.*
+
+Run PowerShell **as administrator**:
+
+```powershell
+$exe = (Get-Command dosync-hub).Source
+$db  = "$env:USERPROFILE\.local\state\dosync\dosync.db"
+
+$action = New-ScheduledTaskAction -Execute "cmd.exe" `
+  -Argument "/c set DOSYNC_DB=$db && `"$exe`""
+$trigger   = New-ScheduledTaskTrigger -AtStartup
+$principal = New-ScheduledTaskPrincipal -UserId "SYSTEM" `
+  -LogonType ServiceAccount -RunLevel Highest
+$settings  = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries `
+  -DontStopIfGoingOnBatteries -RestartCount 3 `
+  -RestartInterval (New-TimeSpan -Minutes 1)
+
+Register-ScheduledTask -TaskName "DoSync Hub" -Action $action `
+  -Trigger $trigger -Principal $principal -Settings $settings
+```
+
+`-AtStartup` with `SYSTEM` means the hub comes back after a reboot without
+anyone logging in — the closest equivalent to systemd. `-RestartCount` covers a
+process that dies.
+
+**`DOSYNC_DB` is not optional, and leaving it out fails silently.** A scheduled
+task does not inherit your environment, so a hub started this way writes to
+`C:\Windows\System32\config\systemprofile\` — a different database from the
+one you used by hand. It starts perfectly, reports `devices: 0`, and looks like
+your inventory was lost. Setting `DOSYNC_DB` points both at the same file;
+running it by hand afterwards reads what the scheduled task wrote, with no
+permission conflict.
+
+Check it:
+
+```powershell
+curl.exe -s http://localhost:47200/v1/status | findstr db_path
+Get-ScheduledTask -TaskName "DoSync Hub" | Get-ScheduledTaskInfo
+```
+
+`LastTaskResult: 267009` is `0x41301` — *the task is currently running*. That is
+the healthy value here; `0` would mean it exited.
+
+**NSSM** installs the hub as a real Windows service and is what a server
+deployment would use. It is third-party software this project does not ship or
+test, so it is named rather than recommended.
+
 ---
 
 ## What's built today
@@ -664,7 +796,7 @@ is implementable in a second language against the same certification suite —
 both share the same author. A genuinely **independent** implementation
 (different author or organization) is a tracked milestone for v1.0: a protocol
 needs multiple independent implementations to become a standard. See the
-[roadmap](ROADMAP.md).
+[vision and scope](docs/VISION.md).
 
 ---
 
@@ -695,7 +827,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, including the C
 - [spec/DoSync-SPEC-v0.1.md](spec/DoSync-SPEC-v0.1.md) — full protocol specification
 - [spec/RESOLVER-SPEC-v0.3.md](spec/RESOLVER-SPEC-v0.3.md) — resolver interface + external resolver protocol
 - [DESIGN-PRINCIPLES.md](DESIGN-PRINCIPLES.md) — architectural decisions and rationale
-- [COMPATIBILITY.md](COMPATIBILITY.md) — backward compatibility guarantees
+- [COMPATIBILITY.md](docs/COMPATIBILITY.md) — backward compatibility guarantees
 
 ---
 

{dosync-0.5.0 → dosync-0.6.1}/dosync/__init__.py

@@ -13,5 +13,5 @@ The two numbers move independently on purpose:
   __version__           this implementation of the hub  (semver)
   __protocol_version__  the wire contract other implementations must match
 """
-__version__ = "0.5.0"
+__version__ = "0.6.1"
 __protocol_version__ = "0.4"