@passioncode-ai/fabric-agent-adapter 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 0.19.0 - 2026-10-12
+
+Settings backups, every spending limit and the feed client's token header in both kits. These are the
+service-side surfaces the pinned contract already carries: DEC-0025 and DEC-0027 (FAA-13).
+
+### Added
+
+- **Settings backups (`fabric-settings-backup/1`, FAC-SEM-035).** Each function exists in both kits.
+  - **Location.** Snapshots live under `<root>/settings-backups/<id>/<instance>/`, outside the data directory.
+    `<root>` is per system: `~/Library/Application Support/PassionCode`, `%APPDATA%\PassionCode` or
+    `$XDG_CONFIG_HOME/PassionCode`.
+  - **Writing.** `make_settings_backup` builds a snapshot from allow-listed tables of JSON scalars. It refuses
+    secret tables, credential columns and fractions.
+  - `write_settings_backup` writes atomically, 0600 in a 0700 folder.
+    - It does not rewrite an unchanged snapshot.
+    - It removes a temporary file an interrupted write left behind.
+    - It keeps the 14 newest snapshots.
+  - `backup_due` decides when the next snapshot is due.
+  - **Reading.** `read_settings_backup` refuses a damaged file and names why.
+  - `newest_intact_backup` skips damaged files and empty snapshots.
+  - `restore_plan` adds rows and never overwrites them. It names what it drops, leaves to defaults or refuses.
+  - **The checksum** uses the settings canonical form: `settings_canonical_json` and `settings_backup_digest`.
+    They are checked against the contract's vectors.
+  - **Parity.** Both kits write byte-identical files.
+- **Every spending limit (DEC-0027, FAC-SEM-031).**
+  - `usage_report` and `usageReport` take a `budgets` list.
+  - A machine day or month limit is counted from the receipts, so it always agrees with `budget`.
+  - A per-order limit gets `spentUsd: null`.
+  - The report is refused when its limits break FAC-SEM-031.
+  - `usage_limit_problems` and `usageLimitProblems` check a report.
+- **The feed client (FAC-SEM-036).** `token_header` and `tokenHeader` give the one header the descriptor
+  declares. `check_service.py` now sends its token through it.
+- **An independent review found 20 moderate defects; all are fixed with tests.**
+  - **The readers follow the schema exactly**, and the two kits accept the same files:
+    - a trailing newline is refused (Python matches a whole string now);
+    - a timestamp is any RFC 3339 date-time with a real calendar date, including an offset;
+    - a string holds at most 1 MiB and a row at most 512 values;
+    - every `extensions` key is a URI;
+    - NaN is refused;
+    - in Node, invalid UTF-8 and a `1.0` integer are refused the way Python refuses them.
+  - **A damaged file never stops anything.** The scan skips it, the digest does not crash, a damaged newest file
+    does not suppress a good snapshot, and an impossible file name makes a snapshot due.
+  - **Safer writes:**
+    - only a temporary file older than an hour is removed;
+    - the snapshot just written is never pruned, even after the clock steps back.
+  - **The restore preview** refuses a key the snapshot holds twice.
+  - **Limits:**
+    - a machine limit over a rolling window is counted from the receipts;
+    - a limit that is not an object is refused.
+  - **Both descriptor validators** check `auth.header` and `auth.scheme` the way the schema does.
+- **Tests.**
+  - The contract's fixtures at the pin are copied to `test/fixtures/contract/dec-0025-0027/`.
+  - The Windows CI job runs both kits' new cases.
+  - Mutation testing: 79 planted defects, all caught.
+- **Docs.**
+  - `references/settings-backups.md` is new.
+  - `usage.md` covers every limit.
+  - `events-and-notifications.md` covers reading a feed.
+  - Updated: `SKILL.md` step 5 and the lifecycle reference's directory table.
+  - The scenario eval `settings-backups-and-every-limit` and two triggers came first.
+
 ## 0.18.0 - 2026-10-12
 
 Services on Linux and Windows in both kits (contract DEC-0032, DEC-0033; FAA-21): the supervisor files the

package/README.md

@@ -230,8 +230,8 @@ FABRIC_CONTRACT_OLD=/path/to/legacy-contract FABRIC_CONTRACT_NEW=/path/to/curren
 ```
 
 Without both environment variables, those tests explicitly skip as `NOT_RUN`.
-This source checkout is 0.18.0. 0.17.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
-were never released); 0.18.0 is published by its `v0.18.0` tag. Source delivery does not update installed skills or live sessions.
+This source checkout is 0.19.0. 0.18.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
+were never released); 0.19.0 is published by its `v0.19.0` tag. Source delivery does not update installed skills or live sessions.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
     "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"

package/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.18.0"
+  version: "0.19.0"
   contract-version: "0.1.0"
   contract-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
 ---

package/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -16,7 +16,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.18.0"
+  version: "0.19.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
@@ -228,8 +228,12 @@ log, retention and notification policy.
 
 An agent that calls paid models reports **what it spent**: one receipt per call from the
 provider's own usage numbers, served behind the token at `surfaces.usage` as the DEC-0021 usage
-report. An unknown cost is null, never 0. Read [the usage reference](references/usage.md)
-before wiring it.
+report. An unknown cost is null, never 0. It lists **every** spending limit the service applies
+in `budgets`, enforced or not. Read [the usage reference](references/usage.md) before wiring it.
+
+A service whose store holds what the operator decided keeps **settings backups** outside its data
+directory, restores only on a fresh database and never overwrites. Read
+[the settings backups reference](references/settings-backups.md).
 
 ## Step 6 — verify
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/events-and-notifications.md

@@ -11,6 +11,15 @@
 
 The feed is a view: never copy rows into a second store that can drift from the first.
 
+## Reading a feed (FAC-SEM-036)
+
+A client of `GET /fabric/v1/events` — or of any token-protected route — sends the token in the
+header the descriptor's `auth.header` names, in the form `auth.scheme` names: the raw token for
+`none`, `Bearer <token>` for `Bearer`. Never assume `Authorization: Bearer`: a client that did
+was refused on every poll and silently dropped every notify event. `token_header(auth, token)` /
+`tokenHeader(auth, token)` gives the one header; the token never travels in another header or
+in the URL.
+
 ## Writing an event
 
 - `kind`: dotted, stable, past tense or state (`job.failed`, `job.awaiting_choice`,

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/lifecycle.md

@@ -88,6 +88,7 @@ remove; the back-off only stops the loop from costing the machine.
 | logs | `~/Library/Logs/<id>/` | `${XDG_STATE_HOME:-~/.local/state}/<id>/logs/` | `%LOCALAPPDATA%\<id>\Logs\` |
 | cache (deletable any time) | `~/Library/Caches/<id>/` | `${XDG_CACHE_HOME:-~/.cache}/<id>/` | `%LOCALAPPDATA%\<id>\Cache\` |
 | code | `~/.local/share/<id>/releases/…` | same | under `%LOCALAPPDATA%` too, never a network share |
+| settings backups ([DEC-0025](settings-backups.md)) | `~/Library/Application Support/PassionCode/settings-backups/<id>/<instance>/` | `${XDG_CONFIG_HOME:-~/.config}/PassionCode/settings-backups/…` | `%APPDATA%\PassionCode\settings-backups\…` |
 
 A repository that versions the data itself (a registry, a plan) may hold the data; the
 service's own code checkout and its releases may not. Directories 0700, secret files 0600. A store carries a schema version and the service

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/settings-backups.md

@@ -0,0 +1,67 @@
+# Settings backups — what the operator decided survives the data directory (DEC-0025)
+
+Fabric Agent Contract DEC-0025, `docs/specification/service.md` → *Settings backup*, schema
+`schemas/settings-backup.schema.json`, rule `FAC-SEM-035`. A service whose store holds what the operator
+decided — which projects it serves, how each is bound, which secret slot each binding uses, their overrides —
+SHOULD keep settings backups, so a lost, purged or wrongly migrated data directory costs the operator nothing.
+
+## Where
+
+`<root>/settings-backups/<id>/<instance>/settings-<UTC %Y%m%dT%H%M%S%fZ>.json`, outside the data directory:
+
+| System | `<root>` (`settings_backup_root` / `settingsBackupRoot`) |
+|---|---|
+| macOS | `~/Library/Application Support/PassionCode` |
+| Windows | `%APPDATA%\PassionCode` |
+| Linux | `$XDG_CONFIG_HOME/PassionCode`, default `~/.config/PassionCode` |
+
+`settings_backup_dir(id, instance)` / `settingsBackupDir(id, instance)` names the folder. Directories are 0700
+(on Windows a protected ACL), files 0600, writes atomic.
+
+## Take a snapshot
+
+```python
+dirs = fs.settings_backup_dir(ID, INSTANCE)
+if fs.backup_due(dirs):                                   # none yet, or the newest is older than 24 hours
+    doc = fs.make_settings_backup(service_id=ID, instance=INSTANCE, version=VERSION, schema=SCHEMA_VERSION,
+                                  tables=allow_listed_tables(db), reason="start")      # or daily, uninstall, manual
+    fs.write_settings_backup(doc, dirs)                   # None when unchanged; keeps the 14 newest
+```
+
+```js
+const dir = k.settingsBackupDir(ID, INSTANCE);
+if (k.backupDue(dir)) k.writeSettingsBackup(k.makeSettingsBackup({ id: ID, instance: INSTANCE, version, schema, tables, reason: 'daily' }), dir);
+```
+
+- **Tables on an allow-list**, each `{"columns": [...], "rows": [[...], ...]}` of JSON scalars. A fraction is its
+  decimal string (`"0.25"`), binary data is never stored, and an integer stays within ±(2^53 − 1).
+- **Secrets by name only.** `make_settings_backup` refuses a table that can only hold connections, tokens,
+  secrets, credentials, passwords, login codes or sessions, and a column whose name says it holds a credential
+  value (`access_token`, `client_secret`); `secret_name` and `token_slot` pass. The names cannot see values, so
+  back up what is on the allow-list, never everything except a deny-list.
+- **When:** at start when `backup_due`, then daily; on uninstall a last one, read-only (open the store without
+  migrating or writing). An unchanged snapshot is not rewritten; a temporary file an interrupted write left is
+  removed first. A fresh, empty database writes none: it would hide the good snapshot before it is restored.
+- Both kits write byte-identical files (`test/fabric-service-backups.test.mjs`, last case).
+
+## Read and restore
+
+`read_settings_backup` / `readSettingsBackup` refuses a file whose checksum, counts or row widths disagree with
+its tables, that carries a value with no canonical form, or whose `format` it does not know, naming why
+(`FAC-SEM-035`). The checksum is SHA-256 of the settings canonical form of `tables`
+(`settings_canonical_json` / `settingsCanonicalJson`: Python's `json.dumps(sort_keys=True,
+ensure_ascii=False)`).
+
+Restore **adds and never overwrites**:
+
+```python
+path, doc, skipped = fs.newest_intact_backup(dirs)        # the newest intact snapshot with content; damaged ones named
+plan = fs.restore_plan(doc, {"projects": {"columns": [...], "key": ["id"], "required": ["id", "name"],
+                                          "existing": existing_keys("projects")}})
+# plan["tables"]["projects"]: insert, present, droppedColumns, defaultedColumns, missingRequired, refused
+```
+
+- **Automatic restore** only on a *fresh* database — no domain records **and** the service has never started —
+  so a restart never undoes a deletion. Insert `plan[...]["insert"]` and add every row the database refuses to
+  `refused` with its key and reason.
+- **Manual restore** shows the plan first; applying it is the operator's act, never an agent's.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/usage.md

@@ -50,6 +50,29 @@ left out.
 **Budget.** Pass `budget` only if the service **enforces** that limit itself. The report states
 it, and the host only shows it.
 
+**Every limit (DEC-0027).** Pass `budgets` to list every spending limit the service applies,
+enforced or not, so the spend view shows all of them — the operator asked for that on 2026-10-07:
+
+```python
+ledger.report(service_id=ID, budget={"period": "month", "limitUsd": 100}, budgets=[
+    {"id": "machine.monthly", "scope": "machine", "kind": "monthly", "period": "month", "limitUsd": 100, "enforced": True},
+    {"id": "project.demo.daily", "scope": "project", "subject": "demo", "kind": "daily", "windowSeconds": 86400,
+     "limitUsd": 5, "spentUsd": 0.31, "enforced": True},
+    {"id": "job.cap", "scope": "job", "kind": "per_job", "limitUsd": 2, "enforced": True},
+])
+```
+
+- A machine limit with a `period` and no `spentUsd` is counted by the kit from the receipts, the
+  way `budget` is, so `budget` and its twin in `budgets` never disagree. A per-order limit
+  (`per_job`, `approval`) gets `spentUsd: null`. Every other limit states its own spend.
+- `scope` is `machine`, `project`, `pool` or `job`; a `project` or `pool` limit names its
+  `subject`. A limit has at most one window — `period`, `windowSeconds` or `since` — and it agrees
+  with the kind (`daily`: the day or 86400 s; `monthly`: the month or 28–31 days; `velocity`: a
+  rolling window). `tripped: true` (work stopped by it now) needs `enforced: true`. An unknown
+  kind is shown generically, never refused.
+- The kits refuse a report that breaks these (`usage_limit_problems` / `usageLimitProblems`,
+  `FAC-SEM-031`). A breach is not refused: the report shows it, and the host shows it first.
+
 Call `ledger.prune()` at start (or daily) to keep the file at the reported window (LC-12).
 
 `JsonlUsageLedger` appends 0600 JSON lines. A line torn by a killed writer is skipped, and the

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service.py

@@ -162,10 +162,9 @@ class Probe:
             conn.close()
 
     def auth_headers(self) -> Dict[str, str]:
-        auth = self.d.get("auth", {})
-        header = auth.get("header", "Authorization")
-        value = self.token or ""
-        return {header: ("Bearer " + value) if auth.get("scheme", "Bearer") == "Bearer" else value}
+        # The header and form the descriptor declares, never an assumed `Authorization: Bearer` (FAC-SEM-036).
+        name, value = fs.token_header(self.d.get("auth"), self.token or "")
+        return {name: value}
 
     # descriptor ------------------------------------------------------------
     def descriptor_rules(self) -> None: