@homeflare/alchemy 0.31.2 → 0.33.0

package/dist/unifi/policy.d.ts

@@ -0,0 +1,20 @@
+import * as Effect from 'effect/Effect';
+export declare const UNIFI_READ_ONLY_POLICY = "read-only by Tim's rule, 2026-09-24; lifting it is a kit change";
+/** What kind of write was asked for and refused — for the message only, never acted on. */
+export type UnifiWriteAction = 'create' | 'update' | 'delete';
+declare const UnifiWriteRefused_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "UnifiWriteRefused";
+} & Readonly<A>;
+export declare class UnifiWriteRefused extends UnifiWriteRefused_base<{
+    /** The vendor type string, e.g. `Unifi.Network`. */
+    readonly type: string;
+    /** `spec.describe(props)` — the object the write would have touched. */
+    readonly identity: string;
+    readonly action: UnifiWriteAction;
+}> {
+    get message(): string;
+}
+/** The only thing `reconcile`/`delete` ever return for a write this family cannot make. */
+export declare const refuseWrite: (type: string, identity: string, action: UnifiWriteAction) => Effect.Effect<never, UnifiWriteRefused, never>;
+export {};
+//# sourceMappingURL=policy.d.ts.map

package/dist/unifi/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/unifi/policy.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,eAAO,MAAM,sBAAsB,oEACgC,CAAC;AAEpE,2FAA2F;AAC3F,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;;;;AAE9D,qBAAa,iBAAkB,SAAQ,uBAAsC;IAC3E,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC,CAAC;IACA,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;AAED,2FAA2F;AAC3F,eAAO,MAAM,WAAW,SAAU,MAAM,YAAY,MAAM,UAAU,gBAAgB,mDACpB,CAAC"}

package/dist/unifi/providers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Every `Unifi.*` provider as one layer for a stack.
+ *
+ *     Layer.mergeAll(unifiProviders(), …the stack's other providers)
+ *       .pipe(Layer.provide(FetchHttpClient.layer))
+ *
+ * S16: a subpath's `providers()` plays the role upstream's own `Providers.ts` does — one minimal
+ * insertion per family. `FetchHttpClient.layer` is the stack's own responsibility to provide,
+ * mirroring `../discord/providers.ts`.
+ */
+import * as Layer from 'effect/Layer';
+export declare const providers: () => Layer.Layer<import("alchemy").Provider<import("./firewall-zone.ts").UnifiFirewallZone> | import("alchemy").Provider<import("./network.ts").UnifiNetwork>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=providers.d.ts.map

package/dist/unifi/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/unifi/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAItC,eAAO,MAAM,SAAS,8NAA4E,CAAC"}

package/dist/unifi/resource.d.ts

@@ -0,0 +1,64 @@
+import type { Input } from 'alchemy/Input';
+import type { UnifiNetworkOpContext } from '@distilled.cloud/unifi-network/Protocol';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+/** What every handler needs from the caller's runtime once `CredentialsFromEnv` is baked in. */
+export type UnifiRequirements = HttpClient.HttpClient;
+/**
+ * One UniFi Network object's read. `Live` is whatever the SDK decodes (a `NetworkDetails`, a
+ * `FirewallZone`, …); `E` is left to each resource file to declare (its own `fetchLive`'s error
+ * union, with `NotFound` already folded away) so the precise per-operation error union flows
+ * through instead of being widened by hand here.
+ */
+export type UnifiSpec<Props extends object, Live, Attributes extends object, E> = {
+    /** The vendor type string, e.g. `Unifi.Network` — for the refusal message only. */
+    readonly type: string;
+    /** Already folds a genuine not-found to `undefined`; nothing else is folded (see header). */
+    readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, UnifiNetworkOpContext>;
+    readonly attributes: (live: Live, props: Props) => Attributes;
+    readonly matches: (attributes: Attributes, props: Props) => boolean;
+    /** For the refusal message and read-back failures. */
+    readonly describe: (props: Props) => string;
+};
+export declare const unifiOperations: <Props extends object, Live, Attributes extends object, E>(spec: UnifiSpec<Props, Live, Attributes, E>) => {
+    read: (props: Props) => Effect.Effect<Attributes | undefined, E, UnifiNetworkOpContext>;
+    readHandler: ({ olds, output }: {
+        olds: Props;
+        output: Attributes | undefined;
+    }) => Effect.Effect<Attributes | undefined, E, UnifiNetworkOpContext>;
+    diff: (news: Input<Props>, output: Attributes | undefined) => Effect.Effect<{
+        readonly action: 'update';
+    } | {
+        readonly action: 'noop';
+    } | undefined, E, UnifiNetworkOpContext>;
+    reconcile: (news: Props) => Effect.Effect<Attributes, E | import("./policy.ts").UnifiWriteRefused, UnifiNetworkOpContext>;
+    destroy: (olds: Props) => Effect.Effect<never, import("./policy.ts").UnifiWriteRefused, never>;
+};
+/**
+ * The four provider handlers for a spec'd read-only UniFi object, wired once.
+ *
+ * ⛔ `list` ANSWERS EMPTY. `GET /v1/sites/{siteId}/networks` answers every network on the site;
+ *   adoption stays explicit, the same reasoning `Proxmox.User`'s and NetBox's `list` give.
+ */
+export declare const unifiHandlers: <Props extends object, Live, Attributes extends object, E>(spec: UnifiSpec<Props, Live, Attributes, E>) => {
+    list: () => Effect.Effect<never[], never, never>;
+    read: (args: {
+        olds: Props;
+        output: Attributes | undefined;
+    }) => Effect.Effect<Attributes | undefined, E, HttpClient.HttpClient>;
+    diff: (args: {
+        news: Input<Props>;
+        output: Attributes | undefined;
+    }) => Effect.Effect<{
+        readonly action: 'update';
+    } | {
+        readonly action: 'noop';
+    } | undefined, E, HttpClient.HttpClient>;
+    reconcile: (args: {
+        news: Props;
+    }) => Effect.Effect<Attributes, E | import("./policy.ts").UnifiWriteRefused, HttpClient.HttpClient>;
+    delete: (args: {
+        olds: Props;
+    }) => Effect.Effect<never, import("./policy.ts").UnifiWriteRefused, HttpClient.HttpClient>;
+};
+//# sourceMappingURL=resource.d.ts.map

package/dist/unifi/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/unifi/resource.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAGnE,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,UAAU,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,CAAC,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,SAAS,MAAM,EAAE,CAAC,IAAI;IAChF,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,qBAAqB,CAAC,CAAC;IAChG,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,KAAK,UAAU,CAAC;IAC9D,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACpE,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;CAC7C,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,SAAS,MAAM,EAAE,CAAC,QAChF,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;kBAEtB,KAAK;oCAQQ;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;iBAUlE,KAAK,CAAC,KAAK,CAAC,UAAU,UAAU,GAAG,SAAS;yBAIZ,QAAQ;;yBAElC,MAAM;;sBAIP,KAAK;oBAYP,KAAK;CAExB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,SAAS,MAAM,EAAE,IAAI,EAAE,UAAU,SAAS,MAAM,EAAE,CAAC,QAC9E,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IAMzC,IAAI;IACJ,IAAI,SAAS;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;IAE5D,IAAI,SAAS;QAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;yBAtCtB,QAAQ;;yBAElC,MAAM;;IAsCzB,SAAS,SAAS;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;IACjC,MAAM,SAAS;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;CAEjC,CAAC"}

package/docs/grafana-folder-dashboard.md

@@ -0,0 +1,145 @@
+# `Grafana.Folder` and `Grafana.Dashboard` — `@homeflare/alchemy/grafana`
+
+Built 2026-09-24 on the same `@distilled.cloud/grafana` (aliased onto
+`@homeflare/distilled-grafana@0.2.0`) operations that fixed the SDK gap
+[grafana.md](./grafana.md#the-sdk-gap--history-and-what-shipped-on-top-of-the-fix) recorded:
+`createFolder`/`getFolderByUID`/`updateFolder`/`deleteFolder`/`getFolders` and
+`postDashboard`/`getDashboard`/`deleteDashboard`, plus a typed `PreconditionFailed` (412) for
+dashboard version conflicts. No live call was made writing this PR — see "Measured vs inferred"
+below for exactly which claims that limits.
+
+## Both follow `Grafana.Datasource`'s doctrine
+
+Same file shape (`resource.ts`'s shared `GrafanaSpec`/`grafanaOperations`/`grafanaHandlers`), same
+credentials layer (`grafanaProviders(target)`), same **uid required, never generated** reasoning —
+`getFolderByUID`/`updateFolder`/`deleteFolder` and `getDashboard`/`postDashboard`/`deleteDashboard`
+are all UID-keyed, and neither `getFolders` nor a dashboard list endpoint takes a per-uid filter,
+so locating an object this resource didn't create would mean listing everything and matching by
+name — the ambiguity requiring `uid` up front sidesteps.
+
+## `Grafana.Folder`
+
+```ts
+import { GrafanaFolder, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class Infra extends GrafanaFolder('infra-folder', {
+  uid: 'infra',
+  title: 'Infrastructure',
+}) {}
+```
+
+- **`description` is write-only** — MEASURED against the SDK's generated types: `Folder` (the GET
+  response) has no `description` field at all, though `CreateFolderRequest`/`UpdateFolderRequest`
+  both accept one. Sent on every create/update that declares it; never compared, the same
+  treatment `Grafana.Datasource` gives `secureJsonDataRefs` for the same reason (nothing to diff
+  against).
+- **Nesting (`parentUid`) is create-only** — MEASURED: `UpdateFolderRequest` has no `parentUid`
+  field (`folder_uid`, `description`, `overwrite`, `title`, `version` only). A declaration whose
+  `parentUid` no longer matches the live folder REFUSES with `GrafanaFolderReparentError` rather
+  than silently doing nothing or deleting-and-recreating under the new parent (which — next
+  bullet — takes every dashboard and alert rule in the folder with it). Move a folder by hand in
+  Grafana, then update the declaration.
+- **Delete defaults to `retain`** — `deleteFolder`'s own operation description says it deletes
+  "all dashboards (and their alerts) stored in the folder... cannot be reverted... also deletes
+  all the subfolders." That is the multi-object cascade `openbao/mount.ts` guards with
+  `defaultRemovalPolicy: 'retain'`, verified there against Alchemy's own `Apply.ts` (not
+  re-verified here; same engine, same option — see `folder.ts`'s header). A stack that wants the
+  cascade opts in with `.pipe(RemovalPolicy.destroy())`; `destroy` still implements the real
+  `DELETE` in full either way (S11). `Grafana.Dashboard` does **not** default to retain — see its
+  own section below.
+
+## `Grafana.Dashboard`
+
+```ts
+import { GrafanaDashboard, grafanaProviders } from '@homeflare/alchemy/grafana';
+
+export class FleetOverview extends GrafanaDashboard('fleet-overview-dashboard', {
+  uid: 'fleet-overview',
+  folderUid: 'infra',
+  dashboard: {
+    title: 'Fleet Overview',
+    panels: [/* … exported straight from Grafana's own "Export as JSON" … */],
+  },
+}) {}
+```
+
+- **The declared content is the dashboard JSON model** — the same shape Grafana's own "Export as
+  JSON" produces. `dashboard-model.ts`'s `normalizeModel` strips `id`/`version`/`iteration`
+  (Grafana-managed, injected/incremented on every save) and forces `uid` to this resource's own
+  value regardless of where — or whether — the source model carried one, before ANY comparison.
+  That is what makes a pasted export (which always embeds the OLD live uid) and a freshly-read
+  live model compare equal, and what makes a no-change plan a true noop despite those fields
+  moving on every live save.
+- **Array order is significant, and nothing here needs a `sortedSet`** — `panels` (screen layout
+  via its own `gridPos`, but the array order also drives Grafana's internal panel indexing and
+  `repeat` behavior) and each panel's `targets` (query execution/legend order) are compared
+  positionally, never reordered. Nothing in a dashboard model is a genuinely unordered SET the way
+  UniFi's `trustedDhcpServerIpAddresses` is (`unifi/network-form.ts`'s `sortedSet`) — this family
+  has no field that needs one. `schemaVersion` is deliberately left comparing as-is — NOT MEASURED
+  whether Grafana rewrites it on a plain save, so normalizing it away on a guess risked hiding a
+  genuine schema mismatch instead of a false diff; see `dashboard-model.ts` for the exact reasoning
+  and what evidence would justify adding it to the volatile-field list.
+- **`matches` compares "is the declaration a subset of what is live", not plain equality** —
+  `dashboard-model.ts`'s `declaredContentMatches`, added after an adversarial review of this PR
+  found plain structural equality (`alchemy/Diff`'s `deepEqual`, used in an earlier version of this
+  PR) made an ordinary, never-edited dashboard show `update` FOREVER: Grafana's own schema
+  migration on save decorates any panel or target whose `datasource` is absent with an explicit
+  `{type, uid}` reference — documented Grafana behavior, not re-measured against a live instance in
+  this PR. A declared panel that never sets `datasource` therefore read back with that field
+  populated, disagreed with the declaration, got written back undecorated, and got redecorated
+  again — non-convergent. `declaredContentMatches` instead asks only whether every field the
+  DECLARATION mentions, at any depth, still matches what is live; `live` may carry additional
+  fields Grafana injected that the declaration never mentioned. Real content drift (a field the
+  declaration DOES mention changing, or vanishing) is still caught exactly as before. The
+  trade-off, deliberate: **removing** a field from the declaration can no longer force Grafana to
+  drop a value it — or a previous declaration — set; only an explicit replacement value changes
+  one. This is the same "undeclared means don't care, never means force-to-default" convention this
+  whole kit already uses for a plain optional prop, now applied inside the JSON model too.
+- **412 version conflicts fail loudly, never overwritten blindly.** `update` injects the version
+  this resource just read (from the same `fetchLive` call `reconcile` already made) into the model
+  it sends, and `overwrite` is never set. If Grafana's own check still fails — someone saved in the
+  gap between that read and this write — `PreconditionFailed` is left uncaught: the whole reconcile
+  fails and nothing is written. The next `plan`/`deploy` re-reads the new live version fresh; there
+  is no separate retry loop in this file, because that next run already is the re-read.
+- **No retain default**, unlike `Grafana.Folder`. Deleting one dashboard is a single-object blast
+  radius — the same class `Grafana.Datasource` already accepts without a retain guard, not
+  `Grafana.Folder`'s multi-object cascade.
+
+## Provisioned objects — refused for writes, adoption is fine
+
+A folder or dashboard that a provisioning FILE manages (rather than this API) carries a live
+signal — `Folder.managedBy` (non-empty) and `DashboardMeta.provisioned`/`provisionedExternalId` —
+that `update`/`destroy` check before ever calling the SDK; `GrafanaProvisionedObjectError` names
+the owning file when Grafana reports one (dashboards only — a folder's `managedBy` value is
+reported as-is, since the SDK does not separately expose a folder's owning file). `create` is
+never at risk: it only runs when `fetchLive` already found nothing.
+
+`matches` still compares structurally regardless of provisioned status, so a mismatched
+declaration against a provisioned object shows `update` in a plan — never a silent, permanently
+hidden noop — and only fails, loudly, when reconcile actually tries to write. A declaration that
+already matches what is live never reaches `update`/`destroy` at all (the shared engine's
+observe-before-write path), so **adopting a provisioned object read-only is safe.**
+
+⚠️ **Measured vs inferred (no live call in this PR).** `DashboardMeta.provisioned`/
+`provisionedExternalId` are exactly the fields Grafana's classic dashboard-read response types for
+this purpose — high confidence, standard shape. `Folder.managedBy` is INFERRED from the SDK's
+schema only: no live instance in this house currently has a file-provisioned FOLDER to read against
+(`teslamate-grafana` has none at all — see grafana.md). Treating any non-empty `managedBy` as
+provisioned, rather than matching specific string values that were never observed live, is the
+conservative reading; confirm against a real provisioned folder before relying on the exact value in
+an error message. The panel/target `datasource` auto-decoration `declaredContentMatches` (above)
+exists to tolerate is documented Grafana schema-migration behavior, also not re-measured live in
+this PR. And `updateFolder`'s `version` field — sent optimistically for concurrency — carries the
+SDK's own caveat "only used by the legacy folder implementation"; whether Grafana's newer
+unified-storage folder backend honors it at all is unverified (`folder.ts`'s `update`).
+
+## Tests
+
+`folder.test.ts`, `dashboard.test.ts` and `dashboard-model.test.ts` mirror `datasource.test.ts`'s
+fake-Grafana harness (`fake-grafana.ts` — the real distilled protocol, only the wire responses
+faked). Each proves: a GET never carries a body (`fake.bodies[0]` is `undefined` — the exact
+"distilled JSON-encodes unknown keys as a body" trap this family's shared memory names); a
+provisioned object refuses update and destroy with no write sent; a transient failure (403/401)
+propagates rather than folding to absent; an unchanged declaration is a noop despite `id`/
+`version`/`iteration` differing; a 412 propagates uncaught; and the folder `parentUid` reparent
+refusal sends no write.

package/docs/grafana.md

@@ -6,15 +6,14 @@ any status check. Built 2026-09-24 against the live target `teslamate-grafana.se
 measured version **13.1.3** (`teslamate/grafana:4.2.0`), listening on `127.0.0.1:3100`, served
 publicly at `tesla.homeflare.dev/dash/`.
 
-## The SDK gap — why only `Datasource` ships
+## The SDK gap — history, and what shipped on top of the fix
 
 ✅ **SDK-level gap fixed 2026-09-24** (`@distilled.cloud/grafana`, aliased onto
-`@homeflare/distilled-grafana` — 0.1.0 pre-release, 0.2.0 once its `minor` changeset publishes it;
-see [docs/distilled-interim.md](./distilled-interim.md)).
-The gap below is otherwise unchanged and left as evidence of what was measured and why; only its
-status line moved. **Still true today:** only `Grafana.Datasource` ships as a house _resource_ —
-`Grafana.Folder`, `Grafana.Dashboard`, `Grafana.AlertRule` and friends are follow-up work on top of
-the now-available SDK operations, not part of this fix.
+`@homeflare/distilled-grafana` — 0.2.0; see [docs/distilled-interim.md](./distilled-interim.md)).
+The gap below is left as evidence of what was measured and why. `Grafana.Folder` and
+`Grafana.Dashboard` now ship on top of the unblocked operations —
+[grafana-folder-dashboard.md](./grafana-folder-dashboard.md) covers both in full. `Grafana.AlertRule`,
+`ContactPoint`, `NotificationPolicy` and `MuteTiming` remain follow-up work, not part of this PR.
 
 Measured 2026-09-24 against the published `@distilled.cloud/grafana@1.0.0-rc.12` tarball (its
 `lib/services/grafana.d.ts`, 4,938 lines): the package had **no create/read/update/delete
@@ -125,8 +124,10 @@ export class TeslaMateDatasource extends GrafanaDatasource('teslamate-datasource
 
 ## Not covered
 
-- **Folders, dashboards, alert rules, contact points, notification policies, mute timings.** The
-  SDK-level blocker is fixed (above); no house `Resource` calls these operations yet — follow-up
-  work, not blocked on anything.
+- **`Grafana.Folder` and `Grafana.Dashboard` ship** — see
+  [grafana-folder-dashboard.md](./grafana-folder-dashboard.md), not repeated here.
+- **Alert rules, contact points, notification policies, mute timings.** The SDK-level blocker is
+  fixed (above); no house `Resource` calls these operations yet — follow-up work, not blocked on
+  anything.
 - **`read` never answers `Unowned`** — the same open gap forgejo's and netbox's own families
   still carry (see upstream-conformance.md); a maintainer decision on the ownership-check shape.

package/docs/opnsense.md

@@ -0,0 +1,146 @@
+# OPNsense — `@homeflare/alchemy/opnsense`
+
+Declares `Opnsense.Firewall.Alias`, `.Category` and `.Group` against
+`@distilled.cloud/opnsense` (aliased onto `@homeflare/distilled-opnsense@0.2.0` —
+[`distilled-interim.md`](./distilled-interim.md)). Built 2026-09-24. **READ-ONLY BY
+DESIGN** — see "The policy" below before reading anything else here. This is the
+estate's **edge firewall**: nothing in this family's code, or in building it,
+contacted the live box, and nothing about it may reconfigure one. (The vendor
+version pin below WAS confirmed against the live box once, read-only, during
+review — see "Vendor version" below; that probe used neither this family's
+code nor this SDK's generated client.)
+
+## Vendor version — measured 2026-09-24
+
+`@homeflare/distilled-opnsense`'s own README carries its generation pin:
+`opnsense/core`/`opnsense/plugins` tag `26.7.2`. That pin used to be an
+**inference** from a captured package list, never measured live (SSH to the
+edge is forbidden by house policy — a failed probe gets the caller's IP
+CrowdSec-banned). This PR's review measured it instead (Probe 14, 2026-09-24),
+live and read-only, over the HTTPS API only — no SSH:
+
+- `firmware-info` returned `200` with `product_version=26.7.2_2`.
+- `alias-search` returned `200` (keys: `current`, `rowCount`, `rows`, `total`).
+
+So the pin is now **measured**, not inferred: the live edge runs `26.7.2_2`,
+one patch ahead of the `26.7.2` tag the model/controller shape was generated
+from — the same series the "patch releases rarely change shape" reasoning
+already relied on, now confirmed rather than assumed. `alias-search`'s 200
+also confirms the live box's Firewall Alias API answers in the shape this SDK
+expects, even though this family reads through `get()`, not `search*` (below).
+
+## Resource set, and why these three
+
+The SDK covers 8 controllers / 83 operations (Firewall Alias/Category/Group/Filter,
+Routing Gateways, and the `os-frr` plugin's Quagga/BGP). This first import pass
+picks the three whose SDK module exports BOTH a `get()` (the whole model, keyed by
+uuid) and a `search<Item>` operation (a paginated list, OPNsense's own POST-shaped
+read) — genuine "list and get" configuration objects, not runtime state:
+
+- **Built**: `firewall_alias`, `firewall_category`, `firewall_group` (interface
+  groups, not permission groups).
+- **Skipped, and why**:
+  - `firewall_filter` (rules) and `routing_settings` (gateways) export `get()` but
+    no `search*` — no distinct list operation, so they miss this pass's own bar.
+    Rules are also the most consequential, highest-churn object in the model;
+    deferred to its own pass rather than folded in here.
+  - `quagga_general` is a global settings singleton, not a collection of items —
+    no uuid, nothing to adopt "by id".
+  - `quagga_bgp` mixes several item types (aspath, communitylist, neighbor,
+    peergroup, prefixlist, redistribution, routemap) with no `search*` for any of
+    them — deferred as a unit rather than picking one sub-type arbitrarily.
+  - `quagga_service` is pure runtime control (start/stop/restart/status) — the
+    task's own "not runtime state" exclusion, textbook case.
+
+## Why `get()`, never `getItem`/`searchItem`, for the three that shipped
+
+`get()` returns the WHOLE model tree in one GET —
+`{ alias: { aliases: { alias: { <uuid>: AliasItem, ... } } } }` for Alias, and the
+equivalent nesting for Category/Group (see each resource file's header for the
+exact path). Finding one item by uuid is then an object-key lookup, never an
+ambiguous request.
+
+That sidesteps two real gaps MEASURED in this early SDK, not a stylistic choice:
+
+1. **`firewall_alias` has no per-item get at all** — only `get` (whole model) and
+   `searchAlias` (paginated) exist.
+2. **`firewall_category`/`firewall_group` DO export `getCategory`/`getGroup`**,
+   but their generated request schema carries no `uuid` path parameter at all
+   (`GetCategoryRequest`/`GetGroupRequest` are both `S.Struct({})` against a `uri`
+   with no `{uuid}` placeholder) — a generation gap in this SDK, not a design
+   choice. Filed as an SDK gap below rather than worked around with a raw path.
+
+`searchAlias`/`searchCategory`/`searchGroup` were also passed over for `list()`
+building (they stay unused) because their generated request schema exposes no
+typed limit/offset/searchPhrase at all — a large object set could silently
+page-truncate through a naive use of them, where `get()` has no pagination to
+fall short of.
+
+## The policy: reconcile and delete always refuse
+
+Tim, 2026-09-24: UniFi and OPNsense are read-only for now. `policy.ts`'s
+`OpnsenseWriteRefused` is the ONLY error `reconcile`/`delete` can raise on any of
+the three resources — neither handler imports an `add`/`set`/`del`/`toggle`
+operation from the SDK. `reconcile` still observes with one `get()` first, so the
+refusal can say whether it would have created or updated; `delete` observes
+nothing and refuses unconditionally. `write-refusal.test.ts` proves it with a fake
+HTTP client that fails the test itself on any non-GET request, exercised through
+the exact `handlers` object each resource's `Provider` wraps — not a lower-level
+seam a real provider bypasses.
+
+Lifting this is a kit change (edit `policy.ts`, write the create/update/delete
+bodies these resources do not have), never a prop. There is no `allowWrite` flag.
+
+## Adopt is `adopt(true)`, not silent (S7, S8, H1)
+
+None of Alias, Category or Group carries an ownership marker OPNsense itself
+understands. Following upstream's `Snippet.ts` reference for a marker-less API
+(the same posture `../discord` documents, not NetBox's silent-adopt gap): a cold
+read (no persisted `output`) that finds a live object at the declared uuid
+returns `Unowned(attrs)`, so declaring it fails `OwnedBySomeoneElse` **unless**
+`adopt(true)` is set. Each resource's convenience constructor
+(`firewallAlias`/`firewallCategory`/`firewallGroup`) pipes `adopt(true)` on by
+default (H5).
+
+## The declaration renderer
+
+`aliasPropsFromLive`/`categoryPropsFromLive`/`groupPropsFromLive` (the barrel's
+names for each resource file's `propsFromLive`, itself the same function as
+`attributesOf` — see each `*-form.ts`'s header) are pure: given the uuid `get()`'s
+map key names and the item decoded at that key, they return exactly the props a
+declaration needs so `matches` reports noop against it. A future import script
+iterates `Object.entries(map)` from one `get()` call and calls the matching
+renderer once per row to generate an `alchemy.run.ts` row — no such script ships
+in this change.
+
+## Credentials
+
+`OPNSENSE_URL` / `OPNSENSE_API_KEY` / `OPNSENSE_API_SECRET`, read **at call time**
+via `@distilled.cloud/opnsense/Credentials`'s own `CredentialsFromEnv` (Basic
+auth, the vendor's own scheme), re-exported from `credentials.ts` rather than
+re-implemented. No OpenBao mint yet (H8's target is unreleased); a deploy process
+exports the three variables itself today. This package never reads, logs or
+mints them.
+
+The only key that exists today is a **ROOT API key** — not scoped to Firewall
+Alias/Category/Group, or to read-only. That is one more reason "The policy"
+above refuses every write unconditionally rather than trusting a props-level
+flag: any write path this key could reach would carry root's full blast
+radius on the estate's edge firewall, not just these three object types.
+
+## SDK gaps
+
+- 🔴 **`getCategory`/`getGroup`'s missing `uuid` path parameter** (above) — a
+  distilled generation gap, not exercised by this family, worth fixing upstream
+  in the distilled clone before a later pass tries to use either operation.
+- **No vendor constraint table**, unlike NetBox/Paperless — this pass did not
+  walk `vendor-schema` for OPNsense's field limits (e.g. `CategoryItem.color`'s
+  `/^[0-9a-fA-F]{6}$/` pattern); a malformed declaration would only be caught if
+  writes were ever lifted, not at plan time.
+- **`password`/`username`/`authtype`/`expire`** (the URL-fetch alias credential
+  fields) and **`path_expression`** (`urljson`-only) are left off `AliasProps`
+  entirely — S25 for the first four, narrow scope for the fifth. See
+  `alias-form.ts`'s header.
+- **No live lifecycle test** (H12): tests run against `fake-opnsense.ts`, a
+  loopback fake, not the real edge. This task had no credentials and was told
+  not to look for any.

package/docs/provider-standard.md

@@ -124,7 +124,7 @@ The files currently on the wrong side of the line are listed in
 | `caddy`             | Caddy 2.11.4                           | source comments only ⚠️           |
 | `forgejo`           | Forgejo 16.0.3                         | source comments only ⚠️           |
 | `talos`             | Talos v1.13 docs (never measured live) | source comments only ⚠️           |
-| `launchd` / `linux` | macOS 27 / systemd 257                 | source comments only ⚠️           |
+| `launchd` / `linux` | macOS 27 / systemd 257 / Podman 5.4.2  | source comments only ⚠️           |
 
 ⚠️ These rows record a version only in prose, so no test catches a drift. `schemas/manifest.json`
 also repeats the PVE, PBS and UniFi entries, which means there are two manifests for one

package/docs/quadlet-container.md

@@ -0,0 +1,132 @@
+# `Podman.Container` — `@homeflare/alchemy/linux`
+
+Status: active
+Verified: 2026-09-24
+
+One Podman [Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)
+`.container` file, declared, plus the systemd unit Podman's own generator
+turns it into — the container half of [linux-host.md](./linux-host.md)'s
+`Systemd.Unit` family, over the same `HostRunner` seam.
+
+★ **Why not `Docker.Container`.** Upstream Alchemy's resource was measured and
+rejected for three reasons: no host-network prop (every container CT100 runs
+uses `--network host`), `environment` puts `Redacted` secrets in Alchemy state,
+and systemd already supervises the containers this stack declares. Quadlet
+sidesteps all three: `Network=host` is a real value, `Environment=` is refused
+if it looks like a secret (below), and the GENERATED unit is what systemd
+supervises — this resource only ever declares the `.container` file that
+produces it.
+
+## Keys checked against the doc, not invented
+
+Every `[Container]` key below is checked against `podman-systemd.unit(5)`,
+**Podman 5.4** (`containers/podman` tag `v5.4.0`,
+`docs/source/markdown/podman-systemd.unit.5.md`, read 2026-09-24) — CT100 runs
+Podman 5.4.2 (`podman --version`, measured over `ssh ct100`, read-only,
+2026-09-24). `[Container]` is typed, unlike `Systemd.Unit`'s freeform
+`sections`, because Quadlet's own schema — unlike bare `systemd.unit(5)` — IS
+one vendor's documented, versioned surface. Adding a key later means checking
+it against the same doc and adding a field; there is no raw `[Container]`
+escape hatch, on purpose (see secrets, below).
+
+```ts
+PodmanContainer('grafana-primary', {
+  name: 'grafana-primary',
+  container: {
+    containerName: 'grafana-primary',
+    environmentFile: ['/etc/grafana-primary/env'],
+    image: 'docker.io/grafana/grafana:12.2.1',
+    network: 'host',
+    volume: ['grafana-primary-data:/var/lib/grafana'],
+  },
+  install: { wantedBy: ['multi-user.target'] },
+  service: { restart: 'always', restartSec: '5s' },
+});
+```
+
+Supported `[Container]` keys: `Image`, `ContainerName`, `Network` (supports
+`'host'`), `Volume` (repeatable), `EnvironmentFile` (repeatable), `Environment`
+(repeatable `KEY=VALUE`, never a secret), `PublishPort` (repeatable, refused
+together with `network: 'host'`), `Exec`, `User`, `AutoUpdate`
+(`'registry' | 'local'`), `PodmanArgs` (repeatable). `[Unit]`
+(`Description`/`Documentation` typed, everything else verbatim lines — same
+approach `Systemd.Unit` uses for the whole file, because these three sections
+stay systemd's own directive set even inside a `.container` file), `[Service]`
+(`Restart`/`RestartSec` typed, everything else verbatim), and `[Install]`
+(`WantedBy`/`RequiredBy`/`Alias` — the only three keys Quadlet honours for a
+`.container` file; NOT `Also`, which plain `systemd.unit(5)` allows).
+
+## Secrets: `EnvironmentFile=`, never `Environment=`
+
+⛔ **A secret belongs in a host path an out-of-band renderer maintains**
+(openbao-agent), named in `container.environmentFile` — never in
+`container.environment`, which is rendered into a 0644 file and stored
+unencrypted in Alchemy state, the same two reasons `Systemd.Unit`'s `content`
+is never secret.
+
+⚠️ **The refusal is best-effort, not a scanner** — `container-secrets.ts`. It
+refuses an `Environment=` key whose NAME says what it holds (`SECRET`,
+`TOKEN`, `PASSWORD`, `API_KEY`, …) and a handful of value shapes real vendor
+tokens take (`Bearer `, `ghp_`, `AKIA`, a JWT's `eyJ`, …). It cannot prove a
+value is safe, only refuse the obvious mistake — `container-secrets.test.ts`
+proves the refusal fires before any write, and that the renderer itself has no
+independent filter (validation is the only backstop, which is why every write
+path calls it first).
+
+## Lifecycle — where it differs from `Systemd.Unit`
+
+Order is **write, `daemon-reload`, VERIFY the generator, then start or restart
+the generated `<name>.service` only for a real change** — see
+`container-lifecycle.ts` and `container-generator.ts` for the full reasoning,
+each doc-cited. In brief:
+
+- ⛔ **The generated unit is never `systemctl enable`d.** MEASURED on CT100,
+  2026-09-24: `caddy.container` declares `[Install] WantedBy=multi-user.target`
+  and nothing ever ran `systemctl enable caddy`; `systemctl is-enabled
+caddy.service` prints `generated`, and
+  `/run/systemd/generator/multi-user.target.wants/caddy.service` is a symlink
+  the GENERATOR put there — doc-confirmed (`podman-systemd.unit(5)`): a
+  generated unit is transient, and `systemctl enable` "does not work" on one;
+  Quadlet applies `[Install]` itself, at every `daemon-reload`. So there is no
+  `enabled` prop: declaring `install.wantedBy` **is** the enablement.
+- ⛔ **A generator failure is a typed `QuadletGeneratorError`, never "absent".**
+  `systemd.generator(7)` (tag `v257`): `daemon-reload` deletes ALL generator
+  output and reruns every generator from the files on disk NOW. So a
+  `.container` file Quadlet refuses has no generated unit at all — even one
+  that generated fine a moment ago. An UPDATE that fails verification
+  therefore restores the LAST-KNOWN-GOOD file and reloads again, rather than
+  leaving the bad file for the next deploy to retry (`Systemd.Unit`'s own
+  choice, unit-lifecycle.ts): here "the next deploy" might be a reboot, and by
+  then the container this resource already promised running has no unit at
+  all. A CREATE that fails removes the file it wrote, same as `Systemd.Unit`.
+- ⚠️ **The one open question.** Whether an ALREADY-ACTIVE unit's `LoadState`
+  stays `loaded` through a failed regeneration (systemd need not
+  garbage-collect a referenced unit) was not measured — doing so needs writing
+  a broken file to a live host, which read-only access forbids. If it does,
+  `LoadState`/`SourcePath` alone would not catch a failed update to a
+  container that was already running; the restore-last-known-good step does
+  not depend on catching it, since it always leaves the host at a file known
+  to generate.
+- `SourcePath` (added to `systemctl.ts`'s `SHOW_PROPERTIES`, additive for
+  `Systemd.Unit`) ties the generated unit back to the `.container` file —
+  MEASURED on CT100: `SourcePath=/etc/containers/systemd/caddy.container`. A
+  mismatch means a same-named file earlier in Quadlet's search path is
+  generating the unit instead of ours — a takeover, not a success.
+- Directory allowlist is Quadlet's OWN rootful search path (doc, "Podman Unit
+  Search Path"): `/run/containers/systemd`, `/etc/containers/systemd`,
+  `/usr/share/containers/systemd` — CT100's `caddy.container` lives in the
+  middle one.
+- Adopt, restart-on-change, delete (stop, remove the file, reload — no
+  `disable`, since it was never enabled through systemctl) and the rename
+  (delete-first replace) contract are otherwise identical to `Systemd.Unit`'s
+  — see [linux-host.md](./linux-host.md).
+
+## The CT100 fixture
+
+`container-fixture.test.ts` renders the same directives as CT100's live
+`caddy.container` (read read-only over `ssh ct100`, 2026-09-24) and checks
+every line matches. Not byte-for-byte: CT100's file interleaves long prose
+comments between directives, and a typed `[Container]` has nowhere to attach
+"this comment goes between these two keys" — the same limit `Systemd.Unit`'s
+`renderUnit` has for the identical reason. The test proves directive parity;
+the file explains why byte parity is not the right bar for a typed resource.