@homeflare/alchemy 0.11.0 → 0.13.0

package/dist/proxmox/pbs-notification-matcher.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `Pbs.NotificationMatcher` — which Proxmox Backup Server notifications reach which targets.
+ *
+ * ★ THIS IS WHERE A FAILED VERIFY, SYNC OR GARBAGE COLLECTION BECOMES A PAGE. pbs-verify-job.ts
+ *   explains why verification is the only thing that notices rotten chunks; a matcher is what
+ *   turns what it notices into a message. Route `match-severity: ['error']` to a webhook target
+ *   (pbs-notification-target.ts, docs/pbs-notifications.md) and a failure pages someone.
+ *
+ * ⛔ A DATASTORE IN `legacy-sendmail` MODE BYPASSES EVERY MATCHER. PBS reads the datastore's
+ *   `notification-mode` before it builds anything (src/server/notifications/mod.rs
+ *   `lookup_datastore_notify_settings`, read at HEAD 2026-09-22): `legacy-sendmail` mails the
+ *   `notify-user` directly and never consults a matcher. The default is `notification-system`
+ *   today (pbs-api-types `NotificationMode`), but a datastore created before PBS 3.2 may say
+ *   `legacy-sendmail` explicitly. `Pbs.Datastore` deliberately does not declare the mode (see
+ *   `notify` in pbs-datastore.ts), so check it by hand before trusting a matcher with a datastore:
+ *   `proxmox-backup-manager datastore show <name>`.
+ *
+ * ⚠️ THE EVENT `type` FOR A VERIFICATION JOB IS `verify`, NOT `verification`. PBS's own
+ *   notifications chapter lists `verification` in its event table and `verify` in its example,
+ *   and the source settles it: `send_verify_status` sets `("type", "verify")` (same file). A
+ *   `match-field: ['exact:type=verification']` rule matches nothing, silently.
+ *   Types at HEAD: `gc`, `prune`, `sync`, `verify`, `tape-backup`, `tape-load`,
+ *   `package-updates`, `acme`, `thresholds`, `system-mail`. GC carries `datastore` and `hostname`
+ *   but NO `job-id`; prune, sync and verify carry all three; the UI's "Test" carries no fields.
+ *
+ * ★ ADOPTING THE BUILT-IN AS IT IS. MEASURED on PBS 4.2 (2026-09-22, `proxmox-backup-manager
+ *   notification matcher show default-matcher`): it routes everything EXCEPT successful prune
+ *   jobs to `mail-to-root` — `invert-match` over `exact:type=prune` AND severity `info`:
+ *   ```ts
+ *   PbsNotificationMatcher('default-matcher', {
+ *     target: pbs, name: 'default-matcher', targets: ['mail-to-root'],
+ *     'invert-match': true, 'match-field': ['exact:type=prune'], 'match-severity': ['info'],
+ *   });
+ *   ```
+ *
+ * ★ WHAT THIS NEEDS, READ OFF THE SERVER'S SCHEMA (generated/pbs.ts source):
+ *     read      GET                 Sys.Audit  on /system/notifications
+ *     write     POST, PUT, DELETE   Sys.Modify on /system/notifications
+ *   ⚠️ NOT A DATASTORE PRIVILEGE. A PBS credential scoped to `/datastore/...` reads every matcher
+ *     as absent — the "absent, then already exists" signature notification-target.ts describes.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import { type NotificationMatcherAttributes, type NotificationMatcherFields } from './notification-matcher-form.ts';
+import { type PveRequirements, type WithPbsTarget } from './resource.ts';
+export interface PbsNotificationMatcherProps extends NotificationMatcherFields, WithPbsTarget {
+}
+export interface PbsNotificationMatcher extends Resource<'Pbs.NotificationMatcher', PbsNotificationMatcherProps, NotificationMatcherAttributes, never, PveRequirements> {
+}
+/** ⚠️ No `retain`, for notification-matcher.ts's reason; a built-in REVERTS on delete. */
+export declare const PbsNotificationMatcher: import("alchemy").ResourceClass<PbsNotificationMatcher>;
+export declare const PbsNotificationMatcherProvider: () => import("effect/Layer").Layer<Provider.Provider<PbsNotificationMatcher>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=pbs-notification-matcher.d.ts.map

package/dist/proxmox/pbs-notification-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbs-notification-matcher.d.ts","sourceRoot":"","sources":["../../src/proxmox/pbs-notification-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EACL,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAK/B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,aAAa,EAAe,MAAM,eAAe,CAAC;AAEtF,MAAM,WAAW,2BAA4B,SAAQ,yBAAyB,EAAE,aAAa;CAAG;AAEhG,MAAM,WAAW,sBAAuB,SAAQ,QAAQ,CACtD,yBAAyB,EACzB,2BAA2B,EAC3B,6BAA6B,EAC7B,KAAK,EACL,eAAe,CAChB;CAAG;AAEJ,0FAA0F;AAC1F,eAAO,MAAM,sBAAsB,yDAA8D,CAAC;AAWlG,eAAO,MAAM,8BAA8B,4IAIxC,CAAC"}

package/dist/proxmox/pbs-notification-target-form.d.ts

@@ -0,0 +1,63 @@
+/**
+ * When a PBS notification target has changed, and the forms that change it.
+ *
+ * ★ THREE QUESTIONS, NOT ONE, because the three kinds of field can be checked three ways:
+ *     plain   every field the server returns in full — compared by value, like any family here
+ *     header  names from the read, values by digest (pbs-notification-target-wire.ts)
+ *     sealed  secret values and the smtp password: the server returns names at best, so values
+ *             are checked against the seal of what this provider last wrote (write-only.ts)
+ *   Each answers `match`, `stale` or `unknown`; only `stale` writes. `unknown` is "the plan cannot
+ *   see it" — a variable missing from the plan's environment, or a secret this provider never
+ *   wrote (an adoption) — and it is PRESENCE-ONLY by design: a plan never invents drift it
+ *   cannot see, and adoption stays free.
+ *
+ * ⛔ A WRITE SENDS ONLY THE GROUPS THAT ARE STALE. Omitting `header` or `secret` from a PUT keeps
+ *   what the server holds (api/webhook.rs `update_endpoint`), so a changed comment is written
+ *   without reading a single secret — and a deploy environment without the secrets can still
+ *   repair the rest. A group that IS stale needs every value it holds; a missing one fails the
+ *   deploy by variable name before anything is sent.
+ */
+import type { PveForm } from './client.ts';
+import type { PbsNotificationTargetAttributes, PbsNotificationTargetProps } from './pbs-notification-target.ts';
+import { type Environment } from './write-only.ts';
+type Props = PbsNotificationTargetProps;
+/**
+ * Why this declaration cannot be written, or nothing. Checked at PLAN, so a webhook without a
+ * URL fails `alchemy plan` naming the field rather than a deploy failing on a 400.
+ * ⚠️ "AT PLAN" MEANS `diff` FOR A TARGET WITH STATE AND THE ADOPTION PROBE (`read`) FOR ONE
+ *   WITHOUT — pbs-notification-target-lifecycle.ts has why both are needed.
+ */
+export declare const refusals: (props: Props) => string[];
+/** Each group's values, resolved from `env`, plus the variables that were missing. */
+export declare const resolveGroups: (props: Props, env?: Environment) => {
+    header: {
+        missing: readonly string[];
+        values: {
+            [x: string]: string;
+        };
+    };
+    sealed: {
+        readonly values: Readonly<Record<string, string>>;
+        readonly missing: readonly string[];
+    };
+};
+export type Groups = ReturnType<typeof resolveGroups>;
+export type GroupState = 'match' | 'stale' | 'unknown';
+/** Every field the server returns in full. `disable` is the one with no undeclared case. */
+export declare const plainMatches: (live: PbsNotificationTargetAttributes, props: Props) => boolean;
+export declare const headerState: (live: PbsNotificationTargetAttributes, props: Props, groups: Groups) => GroupState;
+export declare const sealedState: (live: PbsNotificationTargetAttributes, props: Props, groups: Groups, sealed: string) => GroupState;
+/** Which write-only groups a write carries. A create carries every declared one. */
+export interface Carry {
+    readonly header: boolean;
+    readonly sealed: boolean;
+}
+/**
+ * The body of a create or an update — keys are the server's own, checked against generated/pbs.ts
+ * by pbs-notification-target.test.ts. ⛔ `disable` IS ALWAYS SENT, `0` included — the PVE family's
+ * reason: it is always compared, and "undeclared" and "false" must be one state, not a plan that
+ * asks for an update the PUT never performs.
+ */
+export declare const targetForm: (props: Props, groups: Groups, carry: Carry, mode: 'create' | 'update') => PveForm;
+export {};
+//# sourceMappingURL=pbs-notification-target-form.d.ts.map

package/dist/proxmox/pbs-notification-target-form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbs-notification-target-form.d.ts","sourceRoot":"","sources":["../../src/proxmox/pbs-notification-target-form.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EACV,+BAA+B,EAC/B,0BAA0B,EAC3B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,KAAK,WAAW,EAAyC,MAAM,iBAAiB,CAAC;AAE1F,KAAK,KAAK,GAAG,0BAA0B,CAAC;AAkCxC;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,UAAW,KAAK,KAAG,MAAM,EAsB7C,CAAC;AAIF,sFAAsF;AACtF,eAAO,MAAM,aAAa,UAAW,KAAK,QAAO,WAAW;;;;;;;;;;;CAgB3D,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAKvD,4FAA4F;AAC5F,eAAO,MAAM,YAAY,SAAU,+BAA+B,SAAS,KAAK,KAAG,OAagB,CAAC;AAEpG,eAAO,MAAM,WAAW,SAChB,+BAA+B,SAC9B,KAAK,UACJ,MAAM,KACb,UAKF,CAAC;AAEF,eAAO,MAAM,WAAW,SAChB,+BAA+B,SAC9B,KAAK,UACJ,MAAM,UACN,MAAM,KACb,UAMF,CAAC;AAEF,oFAAoF;AACpF,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAmCD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,UACd,KAAK,UACJ,MAAM,SACP,KAAK,QACN,QAAQ,GAAG,QAAQ,KACxB,OAkBF,CAAC"}

package/dist/proxmox/pbs-notification-target-lifecycle.d.ts

@@ -0,0 +1,100 @@
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type { PbsNotificationTargetAttributes, PbsNotificationTargetProps } from './pbs-notification-target.ts';
+type Props = PbsNotificationTargetProps;
+type Attributes = PbsNotificationTargetAttributes;
+export declare const handlers: {
+    /** ⛔ EMPTY: `mail-to-root` is on every host, and adoption stays an explicit act (resource.ts). */
+    list: () => Effect.Effect<never[], never, never>;
+    /**
+     * ⛔ WITH NO `output` THIS IS ALCHEMY'S ADOPTION PROBE, AND THE ONLY PLAN-TIME HOOK A NEW TARGET
+     *   GETS — so the refusals run here too. Measured on beta.79 (Plan.ts, the `oldState ===
+     *   undefined` branch): a declaration with no state row is `read` with `olds: news` and never
+     *   `diff`ed, and Apply then commits its props as `creating` BEFORE `reconcile` runs. A refusal
+     *   left to `reconcile` fired after the props — a literal token included — were in the store.
+     * ⚠️ ONLY WHEN THE PROPS ARE RESOLVED: Plan skips the probe while any prop is an unresolved
+     *   Output, and then `reconcile` is the first check. docs/pbs-notifications.md says so.
+     * ★ A DEFECT (`Effect.die`), NOT A FAILURE, AND THAT IS WHAT KEEPS IT FROM WEDGING A STAGE. The
+     *   same `read`-with-no-output shape is Alchemy's RECOVERY read of an interrupted create, at plan
+     *   and before a delete (Plan.ts, Apply.ts), with the STORED props — and both wrap it in
+     *   `catchDefect`, degrading to "nothing recovered". A typed failure would pass that catch and
+     *   block the plan or the delete on props the user already fixed. The cold-start probe has no
+     *   catch, so there the defect fails the plan, as intended. A refused create sent no request,
+     *   so "nothing recovered" is also the truth.
+     */
+    read: ({ olds, output }: {
+        olds: Props;
+        output: Attributes | undefined;
+    }) => Effect.Effect<{
+        sealed: string;
+        name: string;
+        type: import("./pbs-notification-target.ts").PbsNotificationTargetType;
+        origin: string;
+        comment: string;
+        disable: boolean;
+        mailto: string;
+        'mailto-user': string;
+        'from-address': string;
+        author: string;
+        server: string;
+        port: number;
+        mode: string;
+        username: string;
+        url: string;
+        method: string;
+        body: string;
+        header: string;
+        headerDigest: string;
+        secret: string;
+    } | undefined, never, import("effect/unstable/http/HttpClient").HttpClient>;
+    /**
+     * ⚠️ `Input<Props>` and `isResolved`, resource.ts's reason: at plan time a prop can still be an
+     *   unresolved Output, and comparing a placeholder to a live value reports a phantom update.
+     * ⛔ A NEW `type` UNDER THE SAME `name` REPLACES DELETE-FIRST: names are unique across every
+     *   family on the host (api `ensure_unique`), so creating the new one first would be refused.
+     */
+    diff: ({ news, olds, output, }: {
+        news: Input<Props>;
+        olds: Props;
+        output: Attributes | undefined;
+    }) => Effect.Effect<{
+        readonly action: 'replace';
+        readonly deleteFirst: boolean;
+    } | {
+        readonly deleteFirst?: never;
+        readonly action: 'update';
+    } | {
+        readonly deleteFirst?: never;
+        readonly action: 'noop';
+    } | undefined, never, import("effect/unstable/http/HttpClient").HttpClient>;
+    reconcile: ({ news, output }: {
+        news: Props;
+        output: Attributes | undefined;
+    }) => Effect.Effect<{
+        sealed: string;
+        name: string;
+        type: import("./pbs-notification-target.ts").PbsNotificationTargetType;
+        origin: string;
+        comment: string;
+        disable: boolean;
+        mailto: string;
+        'mailto-user': string;
+        'from-address': string;
+        author: string;
+        server: string;
+        port: number;
+        mode: string;
+        username: string;
+        url: string;
+        method: string;
+        body: string;
+        header: string;
+        headerDigest: string;
+        secret: string;
+    }, Error, import("effect/unstable/http/HttpClient").HttpClient>;
+    delete: ({ olds }: {
+        olds: Props;
+    }) => Effect.Effect<unknown, Error, import("effect/unstable/http/HttpClient").HttpClient>;
+};
+export {};
+//# sourceMappingURL=pbs-notification-target-lifecycle.d.ts.map

package/dist/proxmox/pbs-notification-target-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbs-notification-target-lifecycle.d.ts","sourceRoot":"","sources":["../../src/proxmox/pbs-notification-target-lifecycle.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,EACV,+BAA+B,EAC/B,0BAA0B,EAC3B,MAAM,8BAA8B,CAAC;AActC,KAAK,KAAK,GAAG,0BAA0B,CAAC;AACxC,KAAK,UAAU,GAAG,+BAA+B,CAAC;AA8ClD,eAAO,MAAM,QAAQ;IACnB,kGAAkG;IAClG,IAAI;IACJ;;;;;;;;;;;;;;;OAeG;IACH,IAAI,qBAAqB;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;;;;;;;;;;;;;;;;;;;;;;IAOxE;;;;;OAKG;IACH,IAAI,4BAID;QACD,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QACnB,IAAI,EAAE,KAAK,CAAC;QACZ,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;KAChC;yBAIsB,SAAS;;;;yBAIa,QAAQ;;;yBAElC,MAAM;;IAGzB,SAAS,qBAAqB;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;;;;;;;;;;;;;;;;;;;;;;IAyC7E,MAAM,aAAa;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;CACnC,CAAC"}

package/dist/proxmox/pbs-notification-target-wire.d.ts

@@ -0,0 +1,30 @@
+import type { PbsNotificationTargetAttributes, PbsNotificationTargetProps } from './pbs-notification-target.ts';
+export declare const base64: (value: string) => string;
+/** ⚠️ Node's decoder skips characters it does not know rather than throwing, so this never throws. */
+export declare const unbase64: (value: string) => string;
+/**
+ * One `KeyAndBase64Val` property string — `name=<name>,value=<base64>` — split into its halves.
+ * ⚠️ KEYED BY NAME, NOT BY POSITION: the server serialises `name` first today, and a parser that
+ *   relied on that would read a reordered item as a header called `value=…`.
+ * ★ A comma cannot occur inside either half: base64 has none, and `refusals` keeps names clean.
+ */
+export declare const keyAndValue: (item: string) => {
+    name: string;
+    value?: string;
+};
+/** The wire item for one header or secret. The value is base64 — the server decodes it to use it. */
+export declare const wireItem: (name: string, value: string) => string;
+/** Sorted, comma-joined names — presence, the only thing the store may know about the values. */
+export declare const names: (keys: readonly string[]) => string;
+/**
+ * ★ A FIXED SALT PER TARGET, SO AN UNCHANGED HEADER SET DIGESTS THE SAME ON EVERY READ. A random
+ *   one would rewrite the state row on every plan. The server shows these values to its auditors
+ *   anyway; what the salt and scrypt buy is that the STORE does not become a second, weaker copy.
+ */
+export declare const headerDigest: (target: string, pairs: Readonly<Record<string, string>>) => string;
+/**
+ * Live JSON to attributes. `sealed` is left empty here: it is not the server's to report, and the
+ * handlers in pbs-notification-target.ts carry it forward from the previous state.
+ */
+export declare const targetAttributes: (live: Record<string, unknown>, props: PbsNotificationTargetProps) => PbsNotificationTargetAttributes;
+//# sourceMappingURL=pbs-notification-target-wire.d.ts.map

package/dist/proxmox/pbs-notification-target-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbs-notification-target-wire.d.ts","sourceRoot":"","sources":["../../src/proxmox/pbs-notification-target-wire.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,+BAA+B,EAC/B,0BAA0B,EAC3B,MAAM,8BAA8B,CAAC;AAItC,eAAO,MAAM,MAAM,UAAW,MAAM,KAAG,MAAuD,CAAC;AAE/F,sGAAsG;AACtG,eAAO,MAAM,QAAQ,UAAW,MAAM,KAAG,MAAuD,CAAC;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,WAAW,SAAU,MAAM,KAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAQxE,CAAC;AAEF,qGAAqG;AACrG,eAAO,MAAM,QAAQ,SAAU,MAAM,SAAS,MAAM,KAAG,MAChB,CAAC;AAKxC,iGAAiG;AACjG,eAAO,MAAM,KAAK,SAAU,SAAS,MAAM,EAAE,KAAG,MAIlC,CAAC;AAEf;;;;GAIG;AACH,eAAO,MAAM,YAAY,WAAY,MAAM,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAG,MAC3B,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,gBAAgB,SACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SACtB,0BAA0B,KAChC,+BAkCF,CAAC"}

package/dist/proxmox/pbs-notification-target.d.ts

@@ -0,0 +1,123 @@
+/**
+ * `Pbs.NotificationTarget` — where a Proxmox Backup Server sends a notification: a `webhook`, or
+ * mail through `sendmail` or `smtp`.
+ *
+ * ★ THE WEBHOOK IS THE POINT. A failed verify, sync or garbage collection reaches a human through a
+ *   target a matcher names (pbs-notification-matcher.ts). Out of the box that is `mail-to-root`,
+ *   one mailbox on one host; a webhook can post an Alertmanager alert instead, and then the failure
+ *   pages like everything else. docs/pbs-alertmanager-body.md has the body template.
+ *
+ * ⛔ SECRETS ARE DECLARED BY THE NAME OF AN ENVIRONMENT VARIABLE, NEVER BY VALUE, and NO VALUE EVER
+ *   REACHES STATE — not as a prop, not as an attribute. write-only.ts has the whole argument; the
+ *   short form: Alchemy stores props and attributes unencrypted, so `secret`, `password` and any
+ *   header holding a credential take `{ fromEnv: 'NAME' }`, read by the deploying process at call
+ *   time. What the store keeps is presence (names) and digests, and the plan diffs on those.
+ *   ★ THIS IS WHERE THE PBS FAMILY PARTS FROM notification-target.ts (PVE), which refuses every
+ *     secret and so cannot create a signed webhook at all.
+ *
+ * ⛔ THE PER-OBJECT PATH CARRIES THE FAMILY: `config/notifications/endpoints/{type}/{name}`. `type`
+ *   is identity, and changing it or `name` plans a REPLACE here — `diff` compares them with the
+ *   recorded props. `/config/notifications/targets` is a read-only union view, as on PVE.
+ *
+ * ⚠️ A BUILT-IN TARGET REVERTS ON DELETE instead of disappearing (`origin: builtin`, measured on
+ *   PBS 4.2 for `mail-to-root`), and PBS reports success either way — notification-target.ts has
+ *   the consequence. Read `origin` before declaring a name you did not create.
+ *
+ * ★ WHAT THIS NEEDS (generated/pbs.ts source): Sys.Audit on /system/notifications to read,
+ *   Sys.Modify there to write. A datastore-scoped credential reads every target as absent.
+ */
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import type { PveRequirements, WithPbsTarget } from './resource.ts';
+import type { FromEnv } from './write-only.ts';
+export type PbsNotificationTargetType = 'sendmail' | 'smtp' | 'webhook';
+/**
+ * ⚠️ PBS'S OWN KEY NAMES, DASHES INCLUDED, for the reason backup-job.ts gives. A field outside its
+ *   family (a `url` on a sendmail target) is refused at plan by name, not sent for a 400.
+ * ⚠️ AN UNDECLARED FIELD IS NEITHER SENT NOR COMPARED; `''` or `[]` (or `{}`) CLEARS ONE.
+ */
+export interface PbsNotificationTargetProps extends WithPbsTarget {
+    /** ⛔ IDENTITY: it picks the family and the URL. Changing it is a replace. */
+    type: PbsNotificationTargetType;
+    /** Unique across ALL families on the host: a webhook cannot be called `mail-to-root`. */
+    name: string;
+    comment?: string;
+    /** Configured but not delivering. Always sent and always compared. */
+    disable?: boolean;
+    /** sendmail, smtp: recipient addresses. Order is not meaning. */
+    mailto?: readonly string[];
+    /** sendmail, smtp: PBS users whose configured address receives the mail. */
+    'mailto-user'?: readonly string[];
+    /** smtp: required. sendmail: optional. */
+    'from-address'?: string;
+    author?: string;
+    /** smtp: the relay host. Required. */
+    server?: string;
+    /** smtp. Unset lets PBS pick from `mode`. */
+    port?: number;
+    /** smtp. PBS's default is `tls`. */
+    mode?: 'insecure' | 'starttls' | 'tls';
+    /** smtp. */
+    username?: string;
+    /** smtp: ⛔ WRITE-ONLY. The server never returns it; the plan compares its seal. */
+    password?: FromEnv;
+    /** webhook: required. Supports templating: `{{ secrets.<name> }}` keeps a token out of it. */
+    url?: string;
+    /** webhook: required. */
+    method?: 'get' | 'post' | 'put';
+    /**
+     * webhook: header name → template text, or `{ fromEnv }` for a value that is itself a secret.
+     * ⚠️ PLAIN VALUES ARE PROPS, AND PROPS ARE STORED: `Content-Type` is fine, a token is not. Put a
+     *   credential in `secret` and write `'Bearer {{ secrets.token }}'` here instead.
+     */
+    header?: Readonly<Record<string, FromEnv | string>>;
+    /**
+     * webhook: the body TEMPLATE, as text. ★ Declared DECODED — the wire is base64, and this family
+     *   encodes on write and decodes on read, so a plan shows a readable diff.
+     */
+    body?: string;
+    /** webhook: ⛔ WRITE-ONLY. Name → variable. Referenced as `{{ secrets.<name> }}`. */
+    secret?: Readonly<Record<string, FromEnv>>;
+}
+/** ⛔ NO VALUE OF A SECRET, PASSWORD OR HEADER — names and digests only. */
+export interface PbsNotificationTargetAttributes {
+    name: string;
+    type: PbsNotificationTargetType;
+    /** `builtin`, `modified-builtin`, `user-created` — reported, never compared. */
+    origin: string;
+    comment: string;
+    disable: boolean;
+    mailto: string;
+    'mailto-user': string;
+    'from-address': string;
+    author: string;
+    server: string;
+    /** 0 means PBS holds no port. */
+    port: number;
+    mode: string;
+    username: string;
+    url: string;
+    method: string;
+    /** The decoded body template. */
+    body: string;
+    /** Header NAMES, sorted — presence. */
+    header: string;
+    /** scrypt digest of the live header pairs, fixed salt per target. */
+    headerDigest: string;
+    /** Secret NAMES, sorted — all PBS will say. */
+    secret: string;
+    /**
+     * Seal of the secret values and password THIS PROVIDER LAST WROTE; `''` if it never wrote them
+     * (an adoption). ⚠️ `''` makes those values presence-only until the first write that carries them.
+     */
+    sealed: string;
+}
+export interface PbsNotificationTarget extends Resource<'Pbs.NotificationTarget', PbsNotificationTargetProps, PbsNotificationTargetAttributes, never, PveRequirements> {
+}
+export declare const PbsNotificationTarget: import("alchemy").ResourceClass<PbsNotificationTarget>;
+/**
+ * ⛔ `Provider.of` STAYS HERE, for resource.ts's reason: it is the one place the handlers are
+ *   checked against the concrete resource types, so the lifecycle file cannot drift from them.
+ */
+export declare const PbsNotificationTargetProvider: () => import("effect/Layer").Layer<Provider.Provider<PbsNotificationTarget>, never, import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=pbs-notification-target.d.ts.map

package/dist/proxmox/pbs-notification-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pbs-notification-target.d.ts","sourceRoot":"","sources":["../../src/proxmox/pbs-notification-target.ts"],"names":[],"mappings":"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"}

package/dist/proxmox/pbs-prune-job.d.ts

@@ -37,10 +37,10 @@
  *   answers 401 "authentication failure", which reads as a bad credential rather than as a
  *   malformed header — the same trap credentials.ts already records for PVE's colon form.
  *   ⛔ AND THERE IS NO MOUNT TO MINT FROM. `mint()` runs `bao read <mount>/creds/<role>`; no
- *     OpenBao mount vends PBS tokens — `proxmox-tb4` and `proxmox-ops` vend PVE ones. The
+ *     OpenBao mount vends PBS tokens — `proxmox-c1` and `proxmox-c2` vend PVE ones. The
  *     `kv/infra/proxmox` shelf holds a READ-ONLY `Audit` token for PBS, and a read-only token
  *     cannot create a prune job. I could not confirm that shelf's contents: this machine's
- *     claude-code approle answers 403 on `sys/mounts` AND on `kv/metadata/infra/proxmox`
+ *     agent approle answers 403 on `sys/mounts` AND on `kv/metadata/infra/proxmox`
  *     (MEASURED). What is needed is a dynamic PBS mount vending a `provision` role with
  *     `Datastore.Modify` — say that, rather than reaching for the stored auditor token.
  *

package/dist/proxmox/pbs-sync-job.d.ts

@@ -12,14 +12,14 @@
  *
  * ⛔ THE CREDENTIAL IS A PBS TOKEN AND IT DOES NOT EXIST YET; NO MOUNT NAME IS INVENTED IN THIS
  *   FILE. PBS wants `user@realm!tokenname` plus a UUID secret, issued by PBS — a PVE token is not
- *   one, whatever it is spelled like. MEASURED from this machine on 2026-09-13: the `claude-code`
+ *   one, whatever it is spelled like. MEASURED from this machine on 2026-09-13: the agent's
  *   approle cannot enumerate mounts (`bao secrets list` -> 403) and
  *   `bao token capabilities kv/infra/proxmox/pbs` -> `deny`, so I could not confirm from here what
  *   does or does not exist. What credentials.ts records is that every PBS token on the kv shelf is
- *   READ-ONLY (`Audit`, as `monitoring@pve`) and STATIC — too narrow to create a sync job, and
+ *   READ-ONLY (`Audit`, as `metrics@pve`) and STATIC — too narrow to create a sync job, and
  *   exactly the kind of credential this provider exists to avoid writing with.
  *   ★ SO THE MOUNT IS A `PbsTarget.mount` THE STACK SUPPLIES, and somebody has to build it first:
- *     a dynamic PBS mount with `read` and `provision` roles mirroring `proxmox-tb4`. Until it
+ *     a dynamic PBS mount with `read` and `provision` roles mirroring `proxmox-c1`. Until it
  *     exists this family can be declared and cannot be deployed. `permission denied` means the
  *     grant is missing — say which mount and role you needed; do not fall back to the shelf token.
  *
@@ -80,7 +80,7 @@ export interface SyncJobProps extends WithPbsTarget {
      *   `Pbs.Remote` family is OUT OF SCOPE for this package rather than merely unwritten:
      *   `POST /config/remote` requires `password`, and Alchemy persists props and attributes to its
      *   state store UNENCRYPTED (StateEncoding.ts tags Redacted values rather than encrypting them),
-     *   which here is the `alchemy` Postgres that pg-backup.sh dumps nightly to CT100. A remote's
+     *   which here is the `alchemy` Postgres that a nightly job dumps to a backup guest. A remote's
      *   password in a prop is that password in four places, for months. The only Remote resource that
      *   could exist would refuse `password` the way storage.ts refuses it — as a `never` — and could
      *   therefore never CREATE a remote, which is a resource that cannot do what its name promises.

package/dist/proxmox/pbs-verify-job.d.ts

@@ -11,7 +11,7 @@
  *
  * ⛔ THIS FILE CANNOT AUTHENTICATE UNTIL TWO THINGS OUTSIDE IT CHANGE, AND IT IS SHIPPED SAYING SO
  *   RATHER THAN SHIPPED LOOKING FINISHED. Both are recorded on `PbsTarget` below:
- *     1. `credentials.ts` has no PBS mint. MEASURED 2026-09-13 from this Mac: the `claude-code`
+ *     1. `credentials.ts` has no PBS mint. MEASURED 2026-09-13 from this Mac: the agent's
  *        approle is refused `sys/mounts`, `kv/infra/proxmox` and `proxmox-pbs/creds/read` alike —
  *        403 permission denied on all three — so there is no mount to name and none is invented.
  *     2. `client.ts`'s `authorization()` builds a PVE header, and PBS will not accept it. See the

package/dist/proxmox/pool.d.ts

@@ -8,11 +8,11 @@
  *   its own state would have reported noop straight past a hand-edit in the UI.
  *
  * ⚠️ IT 403'd UNTIL THE ROLE WAS WIDENED, AND THE HISTORY IS WORTH KEEPING. `hf-provision@pve`
- *   held `LXCProvisioner` on `/` with no `Pool.Allocate`, so reconcile answered
- *   "Permission check failed (/pool/house, Pool.Allocate)". The credential could not widen itself
+ *   held the provision role on `/` with no `Pool.Allocate`, so reconcile answered
+ *   "Permission check failed (/pool/lab, Pool.Allocate)". The credential could not widen itself
  *   — `PUT /access/roles` is 403 for it too — so the role was extended over SSH with
- *   `pveum role modify LXCProvisioner --privs "<existing>,Pool.Allocate,Pool.Audit"`, preserving
- *   every existing privilege. Each new resource in this package should state the privileges its
+ *   `pveum role modify <role> --privs "<existing>,Pool.Allocate,Pool.Audit"`, preserving every
+ *   existing privilege. `PROVISION_PRIVILEGES` (provision-baseline.ts) carries both now. Each new resource in this package should state the privileges its
  *   reconcile needs, so widening stays a deliberate act rather than a reaction to a 403.
  */
 import { Resource } from 'alchemy';

package/dist/proxmox/provision-baseline.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The provisioning baseline: the access every PVE cluster and node needs before a stack built on
+ * this package can manage it — one role, the users OpenBao mints tokens for, the group that fences
+ * the mint, and the grants that bind them. ONE description, read by both halves:
+ *   · provision-declare.ts turns it into `Proxmox.Role`/`Group`/`User`/`Acl` resources, so a stack
+ *     adopts the baseline and keeps it (drift is a plan, not a 403 weeks later);
+ *   · provision-bootstrap.ts turns it into the one-time root commands for a NEW cluster or node.
+ * The two cannot drift apart because neither holds a name or a privilege of its own.
+ *
+ * ⛔ THE PROVISION LANE CANNOT CREATE ITSELF. Every write here runs as a token OpenBao mints for the
+ *   provision user, and minting needs that user to exist, in the mint group, bound to this role.
+ *   So a new cluster is bootstrapped ONCE by root@pam with the generated commands, and the stack
+ *   then adopts what they made (docs/provision-baseline.md).
+ *
+ * ★ ONE PRIVILEGE LIST FOR EVERY FAMILY, NOT A ROLE PER RESOURCE. The list is what the families'
+ *   reconciles need, unioned — the set a hand-kept provision role reached one 403 at a time, each
+ *   step recorded where it was hit (pool.ts, sdn-vnet.ts, ha-rule.ts). It includes what the lane needs
+ *   to manage THIS baseline (`Sys.Modify` for the role, `Realm.AllocateUser`/`User.Modify` for the
+ *   users, `Group.Allocate`, `Permissions.Modify` for the grants), so declaring it can never narrow
+ *   the lane out of its own repair (role.ts: "A ROLE CAN LOCK ITS OWN PROVIDER OUT").
+ * ⚠️ NOT EVERY FAMILY: root@pam-only writes (device passthrough, bind mounts — lxc-judge.ts) and
+ *   privileges a family names as still missing (`VM.Replicate`, replication-job.ts) are outside it.
+ */
+/** The provision role's privileges, sorted — the exact set, never an addition to a live one. */
+export declare const PROVISION_PRIVILEGES: readonly string[];
+/** The names a baseline uses. Every field has a generic default (`PROVISION_DEFAULTS`). */
+export interface ProvisionNames {
+    /** The role holding `PROVISION_PRIVILEGES` on `/`. */
+    readonly role?: string | undefined;
+    /** The user OpenBao's `provision` role mints tokens for, realm-qualified. */
+    readonly provisionUser?: string | undefined;
+    /** The group whose members OpenBao may mint for — the fence around the mint. */
+    readonly mintGroup?: string | undefined;
+    /** The user OpenBao's `read` role mints for, or `null` for a baseline with no read lane. */
+    readonly readUser?: string | null | undefined;
+    /** The role the read user holds on `/`. ⛔ It must already exist: a built-in, or one you declare. */
+    readonly readRole?: string | undefined;
+    /** The comment on the group and both users — how a person on the node learns what they are. */
+    readonly comment?: string | undefined;
+}
+/** Every name, resolved: what `PROVISION_DEFAULTS` holds and what a baseline is built from. */
+export type ResolvedProvisionNames = {
+    readonly [K in keyof ProvisionNames]-?: Exclude<ProvisionNames[K], undefined>;
+};
+/** ★ Generic, kit-prefixed names: nothing here is any one estate's. */
+export declare const PROVISION_DEFAULTS: ResolvedProvisionNames;
+/** Which credential lane a user or a grant belongs to — the OpenBao role that mints for it. */
+export type ProvisionLane = 'provision' | 'read';
+/** A baseline, resolved: exactly what the declaration holds and the bootstrap makes. */
+export interface ProvisionBaseline {
+    readonly role: {
+        readonly roleid: string;
+        readonly privs: readonly string[];
+    };
+    readonly group: {
+        readonly groupid: string;
+        readonly comment: string;
+    };
+    readonly users: readonly {
+        readonly lane: ProvisionLane;
+        readonly userid: string;
+        readonly comment: string;
+        readonly groups: readonly string[];
+    }[];
+    /** Each binds one user to one role on `/`, with propagate — the only shape the lanes need. */
+    readonly grants: readonly {
+        readonly lane: ProvisionLane;
+        readonly userid: string;
+        readonly roleid: string;
+    }[];
+}
+/** Resolve `names` over the defaults and check them. Throws with every problem at once. */
+export declare const provisionBaseline: (names?: ProvisionNames) => ProvisionBaseline;
+//# sourceMappingURL=provision-baseline.d.ts.map

package/dist/proxmox/provision-baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provision-baseline.d.ts","sourceRoot":"","sources":["../../src/proxmox/provision-baseline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,gGAAgG;AAChG,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EA4BhD,CAAC;AAEH,2FAA2F;AAC3F,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9C,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,+FAA+F;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,+FAA+F;AAC/F,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,CAAC,IAAI,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;CAC9E,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,EAAE,sBAQ/B,CAAC;AAEH,+FAA+F;AAC/F,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,MAAM,CAAC;AAEjD,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9E,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,QAAQ,CAAC,KAAK,EAAE,SAAS;QACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,EAAE,CAAC;IACJ,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,SAAS;QACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,EAAE,CAAC;CACL;AA8BD,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,WAAW,cAAc,KAAQ,iBAwB9D,CAAC"}

package/dist/proxmox/provision-bootstrap.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `provisionBootstrap` — the provisioning baseline (provision-baseline.ts) as the one-time root
+ * commands for a NEW cluster or node: a POSIX `sh` script, printed, never run from here.
+ *
+ *     bun -e "import { provisionBootstrap } from '@homeflare/alchemy/proxmox';
+ *             process.stdout.write(provisionBootstrap())" | ssh root@<node> sh
+ *
+ * ⛔ WHY IT EXISTS: THE PROVISION LANE CANNOT CREATE ITSELF. Every resource in this package runs as a
+ *   token OpenBao mints for the provision user, and a cluster without that user, its group and its
+ *   grant has nothing to mint for — the plan that would create them cannot authenticate. So root
+ *   makes them once, and the stack adopts and keeps them (provision-declare.ts). This is the only
+ *   hand step, and it is generated from the same baseline the stack declares.
+ * ⛔ NEVER A TOKEN, NEVER A PASSWORD. The users are created with neither: OpenBao mints short-lived
+ *   tokens for them later, and an `@pve` user with no password cannot log in to the UI. Nothing
+ *   secret is in the script, so it can be read, reviewed and pasted.
+ * ★ CHECK, THEN CHANGE — IDEMPOTENT BY CONSTRUCTION. Each object is read first (`pvesh get … json`,
+ *   parsed with Perl's core JSON::PP, which every PVE node has), compared with the baseline, and
+ *   written only when it differs, naming what it does. A second run prints `ok` for everything and
+ *   writes nothing. It also CONVERGES: a role with other privileges is set to exactly the baseline,
+ *   as the stack's `Proxmox.Role` would set it (role.ts: a declaration replaces the set).
+ * ★ ONE NODE PER CLUSTER. Users, groups, roles and ACLs live in `/etc/pve/user.cfg`, which pmxcfs
+ *   shares across the cluster: a node joining a cluster that has the baseline needs nothing, and a
+ *   run there is all `ok`. A new standalone node or a new cluster is where it creates.
+ * ⚠️ NAMES ARE NOT QUOTED INTO SAFETY, THEY ARE REFUSED INTO IT: provision-baseline.ts admits only
+ *   characters that need no quoting in `sh` or in a Perl `q{}`.
+ */
+import { type ProvisionNames } from './provision-baseline.ts';
+/**
+ * The script for `names` (defaults: `PROVISION_DEFAULTS`). Pure: it reads nothing and runs nothing.
+ * Throws, like `provisionBaseline`, on a name the baseline refuses.
+ */
+export declare const provisionBootstrap: (names?: ProvisionNames) => string;
+//# sourceMappingURL=provision-bootstrap.d.ts.map

package/dist/proxmox/provision-bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provision-bootstrap.d.ts","sourceRoot":"","sources":["../../src/proxmox/provision-bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,yBAAyB,CAAC;AAsFjC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,WAAW,cAAc,KAAQ,MAc/D,CAAC"}

package/dist/proxmox/provision-cli-fake.d.ts

@@ -0,0 +1,38 @@
+export type CliUser = {
+    comment: string;
+    email: string;
+    enable: number;
+    expire: number;
+    firstname: string;
+    lastname: string;
+    groups: string[];
+};
+export type CliGrant = {
+    path: string;
+    type: string;
+    ugid: string;
+    roleid: string;
+    propagate: number;
+};
+export type CliState = {
+    roles: Record<string, string[]>;
+    groups: Record<string, {
+        comment: string;
+    }>;
+    users: Record<string, CliUser>;
+    acl: CliGrant[];
+};
+/** A cluster as PVE installs it: the built-in auditor role, and nothing of the baseline. */
+export declare const freshCluster: () => CliState;
+/** Every item GET the scripts and the providers make, keyed `access/…` without a leading slash. */
+export declare const apiView: (state: CliState) => Record<string, unknown>;
+export type ScriptRun = {
+    code: number;
+    stdout: string;
+    stderr: string;
+    writes: string[];
+    state: CliState;
+};
+/** Run `script` under `sh` against `state`, with the fakes first on PATH. */
+export declare const runScript: (script: string, state: CliState) => Promise<ScriptRun>;
+//# sourceMappingURL=provision-cli-fake.d.ts.map

package/dist/proxmox/provision-cli-fake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provision-cli-fake.d.ts","sourceRoot":"","sources":["../../src/proxmox/provision-cli-fake.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,OAAO,GAAG;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AACF,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AACF,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,GAAG,EAAE,QAAQ,EAAE,CAAC;CACjB,CAAC;AAEF,4FAA4F;AAC5F,eAAO,MAAM,YAAY,QAAO,QAc9B,CAAC;AAIH,mGAAmG;AACnG,eAAO,MAAM,OAAO,UAAW,QAAQ,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAsB/D,CAAC;AA0FF,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;CACjB,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,SAAS,WAAkB,MAAM,SAAS,QAAQ,KAAG,OAAO,CAAC,SAAS,CAkClF,CAAC"}