@homeflare/alchemy 0.30.0 → 0.31.0

package/dist/discord/resource.d.ts

@@ -0,0 +1,75 @@
+import type { Input } from 'alchemy/Input';
+import type { DiscordOpContext } from '@distilled.cloud/discord/Protocol';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+/**
+ * What every stack must still provide after `discordHandlers` bakes in `CredentialsFromEnv`
+ * (below): the transport. `DiscordOpContext` is `Credentials | HttpClient.HttpClient`, so once
+ * `Credentials` is supplied, `HttpClient.HttpClient` is what remains — mirroring
+ * `../netbox/resource.ts#NetboxRequirements`.
+ */
+export type DiscordRequirements = HttpClient.HttpClient;
+/** Every Discord command resource's identity key, regardless of scope. */
+export interface DiscordCommandIdentity {
+    readonly name: string;
+}
+/**
+ * One Discord command object's distilled calls. `Live` is whatever the SDK decodes
+ * (`ApplicationCommandResponse`); `E` is left to each resource file to declare, so a call site's
+ * precise error union (in practice always `DiscordOpError` — see `protocol.ts` — because every
+ * generated Discord operation shares one error channel) flows straight through.
+ */
+export type DiscordSpec<Props extends DiscordCommandIdentity, Live, Attributes extends object, E> = {
+    /** Locate the live command by its declared name within this spec's scope (app, or app+guild). */
+    readonly fetchByName: (props: Props) => Effect.Effect<Live | undefined, E, DiscordOpContext>;
+    readonly attributes: (live: Live) => Attributes;
+    readonly matches: (attributes: Attributes, props: Props) => boolean;
+    readonly upsertBody: (props: Props) => Record<string, unknown>;
+    /** POST create-or-overwrite — see the upsert note above. */
+    readonly upsert: (props: Props, body: Record<string, unknown>) => Effect.Effect<Live, E, DiscordOpContext>;
+    readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, DiscordOpContext>;
+    /** For error messages and test descriptions. */
+    readonly describe: (props: Props) => string;
+};
+export declare const discordOperations: <Props extends DiscordCommandIdentity, Live, Attributes extends object, E>(spec: DiscordSpec<Props, Live, Attributes, E>) => {
+    read: ({ olds, output }: {
+        olds: Props;
+        output: Attributes | undefined;
+    }) => Effect.Effect<Attributes | undefined, E, DiscordOpContext>;
+    diff: (news: Input<Props>, output: Attributes | undefined) => Effect.Effect<{
+        readonly action: 'update';
+    } | {
+        readonly action: 'noop';
+    } | undefined, E, DiscordOpContext>;
+    reconcile: (news: Props) => Effect.Effect<Attributes, E, DiscordOpContext>;
+    destroy: (olds: Props) => Effect.Effect<void, E, DiscordOpContext>;
+};
+/**
+ * The four provider handlers for a spec'd Discord command, wired once.
+ *
+ * ★ CREDENTIALS ARE PROVIDED HERE, ONCE. `CredentialsFromEnv` resolves `DISCORD_BOT_TOKEN` /
+ *   `DISCORD_TOKEN` on the calling fiber per request (credentials.ts), so this closure keeps that
+ *   laziness — nothing is captured at module load.
+ */
+export declare const discordHandlers: <Props extends DiscordCommandIdentity, Live, Attributes extends object, E>(spec: DiscordSpec<Props, Live, Attributes, E>) => {
+    list: () => Effect.Effect<never[], never, never>;
+    read: ({ olds, output }: {
+        olds: Props;
+        output: Attributes | undefined;
+    }) => Effect.Effect<Attributes | undefined, E, HttpClient.HttpClient>;
+    diff: ({ news, output }: {
+        news: Input<Props>;
+        output: Attributes | undefined;
+    }) => Effect.Effect<{
+        readonly action: 'update';
+    } | {
+        readonly action: 'noop';
+    } | undefined, E, HttpClient.HttpClient>;
+    reconcile: ({ news }: {
+        news: Props;
+    }) => Effect.Effect<Attributes, E, HttpClient.HttpClient>;
+    delete: ({ olds }: {
+        olds: Props;
+    }) => Effect.Effect<void, E, HttpClient.HttpClient>;
+};
+//# sourceMappingURL=resource.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/discord/resource.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,UAAU,MAAM,iCAAiC,CAAC;AAGnE;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,UAAU,CAAC;AAExD,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CACrB,KAAK,SAAS,sBAAsB,EACpC,IAAI,EACJ,UAAU,SAAS,MAAM,EACzB,CAAC,IACC;IACF,iGAAiG;IACjG,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAC7F,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,UAAU,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IACpE,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/D,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,CACf,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAC5F,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC;CAC7C,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,KAAK,SAAS,sBAAsB,EACpC,IAAI,EACJ,UAAU,SAAS,MAAM,EACzB,CAAC,QAEK,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IAE7C,IAAI,qBAAqB;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;IAYxE,IAAI,SAAS,KAAK,CAAC,KAAK,CAAC,UAAU,UAAU,GAAG,SAAS;yBAIZ,QAAQ;;yBAElC,MAAM;;IAIzB,SAAS,SAAS,KAAK;IAiBvB,OAAO,SAAS,KAAK;CAMrB,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAC1B,KAAK,SAAS,sBAAsB,EACpC,IAAI,EACJ,UAAU,SAAS,MAAM,EACzB,CAAC,QAEK,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;IAM3C,IAAI;IACJ,IAAI,qBAAqB;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;IAExE,IAAI,qBAAqB;QAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;KAAE;yBArDpC,QAAQ;;yBAElC,MAAM;;IAqDvB,SAAS,aAAa;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;IACrC,MAAM,aAAa;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE;CAErC,CAAC"}

package/docs/credentials.md

@@ -46,6 +46,15 @@ CLI client's variable names, not a house choice), still resolved on the calling
 never captured at module scope. `Authorization: Bearer <value>` is built by the package's protocol
 layer, not by this package. ⛔ The key is never a prop, for the same reason as above.
 
+The Discord subpath (2026-09-24, new — `@distilled.cloud/discord`, no prior hand-rolled client)
+resolves credentials through the SDK's own `CredentialsFromEnv` layer, which reads
+`DISCORD_BOT_TOKEN` (falling back to `DISCORD_TOKEN`), resolved on the calling fiber per request,
+never captured at module scope. `Authorization: Bot <value>` is built by the package's protocol
+layer. On CT100, `hf-discord-halibut.service` holds its own bot token at
+`/opt/homeflare/env/discord-halibut.env`; this package never reads that file. ⛔ The token is
+never a prop, for the same reason as above. See [discord.md](./discord.md) for the live census
+this credential would let a deploy act against.
+
 The Google Workspace subpath (new 2026-09-24, on `@distilled.cloud/google-workspace`) resolves
 credentials through the SDK's own `CredentialsFromEnv`, which reads `GOOGLE_ACCESS_TOKEN` — but
 unlike NetBox/Forgejo/Paperless/LiteLLM's API-token schemes, this variable holds an OAuth2 bearer

package/docs/discord.md

@@ -0,0 +1,129 @@
+# Discord — `@homeflare/alchemy/discord`
+
+Declares Discord application commands (global and guild-scoped) against
+`@distilled.cloud/discord@1.0.0-rc.12`. Built 2026-09-24, walked against the live target,
+`hf-discord-halibut.service` on CT100 — read-only; nothing in this walk deployed anything or
+touched a real token. See [`upstream-conformance.md`](./upstream-conformance.md#discord) for the
+rule-by-rule accounting.
+
+## Resource set, and why it stops there
+
+Two resources: `Discord.ApplicationCommand` (global) and `Discord.GuildApplicationCommand`
+(guild-scoped). The SDK's `discord.ts` service also generates guild role, guild channel and
+webhook operations (`createGuildRole`, `createGuildChannel`, `createWebhook`, …), but
+`hf-discord-halibut.service` — the only live Discord workload the estate runs — touches none of
+them: it registers slash commands and nothing else (measured on CT100, see below). "Start with
+what Halibut actually uses" (the task this shipped under) means roles, channels and webhooks stay
+unbuilt until a real stack needs to declare one; the engine in `resource.ts` is generic enough
+that adding `Discord.GuildRole` later is a new spec file, not a new engine.
+
+## Halibut, measured on CT100 (read-only, 2026-09-24)
+
+- **Application/bot**: `hf-discord-halibut.service`, `/opt/homeflare/discord-bot/halibut`,
+  Sapphire on discord.js. Token in `/opt/homeflare/env/discord-halibut.env`
+  (`DISCORD_TOKEN`, `0640 root:homeflare`), loaded by systemd's `EnvironmentFile=`. Never read by
+  this package.
+- **Guild(s)**: `DISCORD_GUILD_ID`, a CSV of two snowflakes (commented `HomeFlare,schenanigans`
+  in `register.ts`) — guild-scoped registration only; `DISCORD_GUILD_ID` is always set in
+  production, so `guildIdsForRegister()` never falls through to global.
+- **Commands** (`CURRENT_SLASH_NAMES`, `src/discord/register.ts`): `ping`, `whoami`, `session`,
+  `status`, `llmstats`, `run`, `sch`, `pr`, `voice` — nine guild-scoped slash commands.
+- **Registration timing**: `applySapphireGuildRegister()` runs once **before login**, setting
+  Sapphire's `RegisterBehavior.BulkOverwrite` and its default guild ids. On every connect,
+  Sapphire then `application.commands.set()`s the exact `CURRENT_SLASH_NAMES` set — a PUT that
+  wipes anything else registered on those guilds ("Stale guild cmds … have no handler → Discord
+  'interaction failed'", the file's own comment, measured 2026-09-04).
+- **Webhooks, roles, channels**: none found. `grep -rli webhook` over `dist/` matched nothing;
+  the only role/channel-shaped env var is an unrelated `DISCORD_FORUM_TAG_MAP`.
+
+## 🔴 Ownership conflict: do not deploy `GuildApplicationCommand` against Halibut's guilds yet
+
+Halibut's `BulkOverwrite` on every restart and this resource's `reconcile` (an upsert on every
+apply where `matches` fails) are two independent writers converging the same object on two
+different schedules. Declaring `Discord.GuildApplicationCommand` for `ping`/`whoami`/… on
+Halibut's guilds today would not replace Halibut's registration — it would race it. Whichever ran
+last after each of the bot's restarts and each `alchemy deploy` would win until the other ran
+again, and `alchemy plan` would report drift the bot itself caused.
+
+**The handover, when someone runs it (none of this is done by this change):**
+
+1. Freeze `CURRENT_SLASH_NAMES` — it is already the single source of truth for the set.
+2. Declare each command as a `guildApplicationCommand(...)` (the `adopt(true)` constructor) with
+   props matching what is live exactly. A verified apply should be a no-op — `hf-adopt-verify`
+   proves that without writing (H6).
+3. **In the same deploy window**, remove the `applySapphireGuildRegister()` call from Halibut's
+   `src/discord/register.ts` and redeploy the bot. Step 2 without step 3 leaves both writers
+   active; step 3 without step 2 leaves the commands with no owner at all until the next deploy.
+
+Steps 1–3 are bot-runtime changes and out of scope for this family, which is declarative only.
+
+## Credentials
+
+`DISCORD_BOT_TOKEN` (falling back to `DISCORD_TOKEN`), read **at call time**, never a prop —
+`@distilled.cloud/discord/Credentials`' own `CredentialsFromEnv`, re-exported from
+`credentials.ts` rather than re-implemented. No OpenBao mint yet (H8's target,
+`Alchemy.Stack({ secrets })`, is unreleased); today a deploy process exports the variable itself.
+
+## Adopt is `adopt(true)`, not silent
+
+Unlike NetBox (H1's documented gap), this family follows upstream's `Snippet.ts` reference for a
+marker-less API exactly: a cold `read` (no persisted `output`) that finds a live command by name
+returns `Unowned(attrs)`, so a first deploy against an existing command fails
+`OwnedBySomeoneElse` **unless** `adopt(true)` is set. Both convenience constructors
+(`applicationCommand`, `guildApplicationCommand`) pipe `adopt(true)` on by default (H5), matching
+`cloudflare/website.ts`'s `astroWebsite`/`viteWebsite`.
+
+## Reconcile is one upsert call
+
+Discord's own docs for both Create Global/Guild Application Command say a command with the same
+name (and type) as an existing one overwrites it — the create endpoint is a true upsert, the same
+shape `Snippet.ts`'s `putSnippet` uses. `reconcile` therefore has no separate PATCH path: it reads
+the live command, and calls `create` only when `commandMatches` says the declaration and the live
+object disagree. ⚠️ REASONED NOT MEASURED — this task had no token and made no real Discord API
+call; it is documented Discord behaviour, unchanged across API v10, not something exercised here.
+
+## Rate limits: the SDK's default bound, not a house retry
+
+Every generated operation threads a `Retry` context tag (`retry: Retry.Retry` in
+`protocol.ts`/`api.ts`). With no policy installed, `@distilled.cloud/core`'s `makeDefault` applies:
+capped exponential backoff (250ms × 2, capped at 5s), **`Schedule.recurs(8)`** (bounded — S26 asks
+for 8–10 attempts), and a `429`'s `Retry-After` honored with precedence, itself capped at 60s
+(`DEFAULT_SERVER_RETRY_HINT_CAP_MS`). This family adds nothing on top — no `Discord.Retry.policy`
+call anywhere in `resource.ts` — because adding one could only make it either redundant with, or
+looser than, the bound the SDK already guarantees. `retry.test.ts` proves both directions against
+the fake: a rate-limited call is retried and eventually succeeds, AND a call rate-limited forever
+still stops — `fake.seen.length` is asserted `<= 9` (1 attempt + `Schedule.recurs(8)`), not just
+"eventually rejects", so the bound itself is what the test checks.
+
+## SDK gaps
+
+- 🔴 **MEASURED: every generated operation's typed error union is narrower than the protocol's own
+  `HTTP_STATUS_MAP`.** `tsc` is what surfaced this — see `guild-application-command.test.ts`'s
+  401 test and its own comment. `DiscordOpError` (every operation's declared error type) resolves
+  to `DefaultErrors | ConfigError | HttpClientError`, and core's `DefaultErrors` is built only from
+  `DEFAULT_ERROR_STATUSES` — 401, 429, 500, 502, 503, 504. `Forbidden` (403), `NotFound` (404),
+  `BadRequest` (400) and `Conflict` (409) are in `HTTP_STATUS_MAP` and so ARE constructed by the
+  protocol at runtime on those statuses, but they are absent from the exported error TYPE, so
+  `catchTag('Forbidden', …)` does not type-check anywhere in this family without an unsafe cast.
+  Nothing in `resource.ts` currently needs to catch any of those four (locate is list-based and
+  never 404s, the same reasoning `netbox/prefix.ts` documents), but a future resource that does —
+  or `destroy`'s own TOCTOU race, where the command could vanish between `fetchByName` and the
+  delete call and legitimately 404 — cannot `catchTag('NotFound', …)` today. That gap is real and
+  unhandled in `resource.ts#destroy`, documented rather than papered over with a cast.
+- **`options` is passed through opaquely**, not re-modeled. The generated option union is ~40
+  nested schema types; `command-form.ts` types it as `readonly Record<string, unknown>[]` and
+  neither validates nor transforms it. A caller supplies Discord's own wire shape.
+- **No vendor constraint table**, unlike NetBox/Paperless. Distilled's schema carries Discord's
+  field limits (name length, description length, max 25 options, …) but this change did not walk
+  `vendor-schema` for Discord; a bad declaration fails at the API call, not at plan time.
+- **`default_member_permissions` type asymmetry**: the generated request types show
+  `number | null`, the response shows `string | null`. Discord's real wire contract is a
+  stringified bitfield on both sides; `command-form.ts` types the prop as `string` (matching the
+  response and Discord's docs) and casts through `unknown` at the SDK call boundary, the same
+  pattern `netbox/prefix.ts` uses for its own generated-type mismatches.
+- **Global command propagation** (up to an hour, Discord's own docs) is not polled — S26 bounds
+  waits at ~60s, which cannot cover an hour. A `diff` run inside that window may report transient
+  drift. Documented in `application-command.ts`, not solved.
+- **No live lifecycle test** (H12): tests run against `fake-discord.ts`, a loopback fake, not a
+  real Discord application. This task could not hold a token to run one even if the house allowed
+  agent-run live writes, which it currently does not.

package/docs/upstream-conformance.md

@@ -224,8 +224,24 @@ HttpClient` client. The old status-carrying `NetboxError` and its `cause.status
     the house's glyph rationale into `//` comments.
 13. **Tests never use `alchemy/Test/Bun`.** Every lifecycle is proven against loopback
     fakes (S28, H12). Live suites need a place to run, and that is a maintainer decision.
+14. **`discord/*` is new (2026-09-24, task-authorized, kit PR TBD) and built directly on
+    `@distilled.cloud/discord` — no hand-rolled `client.ts` ever existed to retire.**
+    `Discord.ApplicationCommand` and `Discord.GuildApplicationCommand` call the SDK's
+    typed operations, `catchTag`'d through the shared `DiscordOpError` union (S21), with no
+    status sniffing anywhere in `resource.ts`. It follows upstream's `Snippet.ts` reference
+    exactly for a marker-less API (S7, S8): a cold `read` returns `Unowned(attrs)`, and both
+    convenience constructors pipe `adopt(true)` (H5) — a stricter posture than `netbox/*`'s
+    documented H1 gap, not a repeat of it. Rate-limit handling is the SDK's own default
+    `Retry` policy (bounded: `Schedule.recurs(8)`, S26) — this family adds nothing on top.
+    Full detail, the live Halibut census and its ownership-handover sequence, and every SDK
+    gap: [`discord.md`](./discord.md). ⛔ **Diverges on S24/S25 the same way every distilled
+    family in this ledger does:** credentials are read at call time through the SDK's own
+    `CredentialsFromEnv`, not a house `alchemy/Auth` provider — unchanged from `netbox/*`
+    and `litellm/*`'s entries above. **Gap, not yet fixed:** no vendor constraint table
+    (unlike NetBox/Paperless); `options` passed through opaquely rather than modeled from
+    the schema (`docs/discord.md#sdk-gaps`).
 
-14. **`grafana/*` (added 2026-09-24) ships only `Datasource` — a real SDK gap, not scope-trimming.**
+15. **`grafana/*` (added 2026-09-24) ships only `Datasource` — a real SDK gap, not scope-trimming.**
     Measured against the published `@distilled.cloud/grafana@1.0.0-rc.12` tarball's
     `lib/services/grafana.d.ts` (4,938 lines): the package has no create/read/update/delete
     operations for folders (only `updateFolderPermissions` exists), plain dashboards (only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homeflare/alchemy",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Custom Alchemy providers for Cloudflare, Proxmox, OpenBao, Forgejo, Talos, launchd and Caddy, and a verifier that proves adoptions are no-ops.",
   "homepage": "https://github.com/taslabs-net/homeflare-kit/tree/main/packages/alchemy#readme",
   "bugs": "https://github.com/taslabs-net/homeflare-kit/issues",
@@ -96,6 +96,10 @@
       "types": "./dist/verify/index.d.ts",
       "default": "./dist/verify/index.js"
     },
+    "./discord": {
+      "types": "./dist/discord/index.d.ts",
+      "default": "./dist/discord/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/src/discord/application-command.test.ts

@@ -0,0 +1,103 @@
+/**
+ * `Discord.ApplicationCommand`'s `spec` (global scope) against a fake Discord. Shares its engine
+ * (`discordOperations`) and its comparison functions (`command-form.ts`) with
+ * `guild-application-command.test.ts`, which covers those in depth — this file proves only what
+ * differs for global commands: the URL shape (no `guild_id`), and that `spec.attributes` never
+ * invents one.
+ */
+import { describe, expect, test } from 'bun:test';
+import type * as command from '@distilled.cloud/discord/discord';
+import * as Effect from 'effect/Effect';
+import { spec } from './application-command.ts';
+import type { ApplicationCommandProps } from './application-command.ts';
+import { fakeDiscord, fakeDiscordLayer, fakeFailure } from './fake-discord.ts';
+import { discordOperations } from './resource.ts';
+
+const APP = '111111111111111111';
+const CMD_PATH = `/applications/${APP}/commands`;
+const PROPS: ApplicationCommandProps = {
+  applicationId: APP,
+  description: 'ping the bot',
+  name: 'ping',
+};
+
+/** Loosely typed on purpose — a fixture, cast to the real response shape at the boundary. */
+const liveCommand = (overrides: Record<string, unknown> = {}) =>
+  ({
+    application_id: APP,
+    default_member_permissions: null,
+    description: 'ping the bot',
+    id: '999',
+    name: 'ping',
+    nsfw: false,
+    type: 1,
+    version: '1',
+    ...overrides,
+  }) as unknown as command.ApplicationCommandResponse;
+
+describe('Discord.ApplicationCommand spec.fetchByName', () => {
+  test('lists the GLOBAL path, with no guild segment', async () => {
+    const fake = fakeDiscord((method, url) =>
+      method === 'GET' && url.pathname === CMD_PATH
+        ? Response.json([liveCommand()])
+        : fakeFailure(400, 0, 'unexpected request'),
+    );
+    const live = await Effect.runPromise(
+      spec.fetchByName(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('999');
+    expect(fake.seen[0]?.path).toBe(CMD_PATH);
+  });
+});
+
+describe('Discord.ApplicationCommand spec.attributes', () => {
+  test('has no guildId field at all — a global command is scopeless', () => {
+    const attrs = spec.attributes(liveCommand());
+    expect('guildId' in attrs).toBe(false);
+    expect(attrs.applicationId).toBe(APP);
+  });
+});
+
+describe('discordOperations(spec).reconcile', () => {
+  test('creates against the global path when absent', async () => {
+    const fake = fakeDiscord((method, url) => {
+      if (method === 'GET' && url.pathname === CMD_PATH) return Response.json([]);
+      if (method === 'POST' && url.pathname === CMD_PATH) return Response.json(liveCommand());
+      return fakeFailure(400, 0, 'unexpected request');
+    });
+    const ops = discordOperations(spec);
+    const attrs = await Effect.runPromise(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(attrs.commandId).toBe('999');
+    expect(fake.seen.some((s) => s.method === 'POST' && s.path === CMD_PATH)).toBe(true);
+  });
+
+  test('a matching live command makes zero write calls (S10)', async () => {
+    const fake = fakeDiscord((method, url) =>
+      method === 'GET' && url.pathname === CMD_PATH
+        ? Response.json([liveCommand()])
+        : fakeFailure(500, 0, 'unexpected write'),
+    );
+    const ops = discordOperations(spec);
+    await Effect.runPromise(
+      ops.reconcile(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(fake.seen).toHaveLength(1);
+    expect(fake.seen[0]?.method).toBe('GET');
+  });
+});
+
+describe('discordOperations(spec).destroy', () => {
+  test('deletes against the global path by command id', async () => {
+    const fake = fakeDiscord((method, url) => {
+      if (method === 'GET' && url.pathname === CMD_PATH) return Response.json([liveCommand()]);
+      if (method === 'DELETE' && url.pathname === `${CMD_PATH}/999`)
+        return new Response(null, { status: 204 });
+      return fakeFailure(400, 0, 'unexpected request');
+    });
+    const ops = discordOperations(spec);
+    await Effect.runPromise(ops.destroy(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))));
+    expect(fake.seen.some((s) => s.method === 'DELETE')).toBe(true);
+  });
+});

package/src/discord/application-command.ts

@@ -0,0 +1,109 @@
+/**
+ * `Discord.ApplicationCommand` — one GLOBAL slash/user/message command on a Discord application.
+ *
+ * ⛔ NOT WHAT `hf-discord-halibut.service` USES TODAY. Halibut registers guild-scoped commands
+ *   only (`DISCORD_GUILD_ID` is always set in production — see `docs/discord.md#halibut`), so this
+ *   resource has no live object to adopt yet. It exists because the distilled SDK, and Discord's
+ *   own API, model global and guild commands as siblings (same shape, different scope), and a
+ *   future bot or a future Halibut command that goes global needs it without a second family.
+ *
+ * ⚠️ GLOBAL COMMAND CHANGES TAKE UP TO AN HOUR TO PROPAGATE (Discord's own docs). A `diff` that
+ *   ran right after a write could see stale results; this resource does not poll for propagation
+ *   (S26 bounds waits at ~60s, an hour is not boundable), so a plan run inside that window may
+ *   report drift that will resolve itself. Documented, not solved — see `docs/discord.md`.
+ */
+import { adopt } from 'alchemy/AdoptPolicy';
+import { Resource } from 'alchemy';
+import * as Provider from 'alchemy/Provider';
+import * as command from '@distilled.cloud/discord/discord';
+import type { DiscordOpError } from '@distilled.cloud/discord/Protocol';
+import * as Effect from 'effect/Effect';
+import {
+  type CommandFields,
+  type CommandFieldsAttributes,
+  commandBody,
+  commandFieldsOf,
+  commandMatches,
+} from './command-form.ts';
+import type { DiscordRequirements, DiscordSpec } from './resource.ts';
+import { discordHandlers } from './resource.ts';
+
+export interface ApplicationCommandProps extends CommandFields {
+  /** The Discord application (bot) this command belongs to — a public snowflake, not a secret. */
+  applicationId: string;
+}
+
+export interface ApplicationCommandAttributes extends CommandFieldsAttributes {
+  commandId: string;
+  applicationId: string;
+  version: string;
+}
+
+export interface DiscordApplicationCommand extends Resource<
+  'Discord.ApplicationCommand',
+  ApplicationCommandProps,
+  ApplicationCommandAttributes,
+  never,
+  DiscordRequirements
+> {}
+
+export const DiscordApplicationCommand = Resource<DiscordApplicationCommand>(
+  'Discord.ApplicationCommand',
+  {
+    // Commands are the thing a user reads; nothing here can be edited into another object.
+    defaultRemovalPolicy: 'retain',
+  },
+);
+
+export const isDiscordApplicationCommand = (value: unknown): value is DiscordApplicationCommand =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Discord.ApplicationCommand';
+
+const attributesOf = (live: command.ApplicationCommandResponse): ApplicationCommandAttributes => ({
+  applicationId: live.application_id,
+  commandId: live.id,
+  version: live.version,
+  ...commandFieldsOf(live),
+});
+
+/** Exported for direct testing against `fake-discord.ts` — the same seam `../netbox/prefix.ts` uses. */
+export const spec: DiscordSpec<
+  ApplicationCommandProps,
+  command.ApplicationCommandResponse,
+  ApplicationCommandAttributes,
+  DiscordOpError
+> = {
+  attributes: attributesOf,
+  describe: (props) => `applications/${props.applicationId}/commands ${props.name}`,
+  destroy: (props, live) =>
+    command.deleteApplicationCommand({ application_id: props.applicationId, command_id: live.id }),
+  fetchByName: (props) =>
+    command
+      .listApplicationCommands({ application_id: props.applicationId })
+      .pipe(Effect.map((rows) => rows.find((row) => row.name === props.name))),
+  matches: commandMatches,
+  upsert: (props, body) =>
+    command.createApplicationCommand({
+      application_id: props.applicationId,
+      ...(body as Omit<command.CreateApplicationCommandRequest, 'application_id'>),
+    }),
+  upsertBody: commandBody,
+};
+
+export const handlers = discordHandlers(spec);
+
+export const DiscordApplicationCommandProvider = () =>
+  Provider.effect(
+    DiscordApplicationCommand,
+    Effect.succeed(DiscordApplicationCommand.Provider.of(handlers)),
+  );
+
+/**
+ * `applicationCommand('help', { applicationId, name: 'help', description: '…' })` — `adopt(true)`
+ *   piped on by default (H5), so a first deploy against a command that already exists silently
+ *   takes it over instead of failing `OwnedBySomeoneElse`. Mirrors `cloudflare/website.ts`'s
+ *   `astroWebsite`/`viteWebsite` convenience constructors.
+ */
+export const applicationCommand = (id: string, props: ApplicationCommandProps) =>
+  DiscordApplicationCommand(id, props).pipe(adopt(true));

package/src/discord/command-form.test.ts

@@ -0,0 +1,144 @@
+/**
+ * `command-form.ts`'s pure functions — no server, no Effect runtime, the same shape
+ * `../netbox/prefix-form.test.ts` uses for `prefixBody`/`prefixMatches`.
+ */
+import { describe, expect, test } from 'bun:test';
+import {
+  type CommandFields,
+  type CommandFieldsAttributes,
+  commandBody,
+  commandFieldsOf,
+  commandMatches,
+} from './command-form.ts';
+
+describe('commandBody', () => {
+  test('settles description/nsfw/type when undeclared, the way Discord itself would', () => {
+    expect(commandBody({ name: 'ping' })).toEqual({
+      description: '',
+      name: 'ping',
+      nsfw: false,
+      type: 1,
+    });
+  });
+
+  test('an omitted field is left OUT of the body, never sent empty/null/false', () => {
+    const body = commandBody({ name: 'ping' });
+    expect(Object.prototype.hasOwnProperty.call(body, 'options')).toBe(false);
+    expect(Object.prototype.hasOwnProperty.call(body, 'default_member_permissions')).toBe(false);
+    expect(Object.prototype.hasOwnProperty.call(body, 'dm_permission')).toBe(false);
+    expect(Object.prototype.hasOwnProperty.call(body, 'contexts')).toBe(false);
+    expect(Object.prototype.hasOwnProperty.call(body, 'integration_types')).toBe(false);
+  });
+
+  test('every declared field reaches the wire body under its wire name', () => {
+    const props: CommandFields = {
+      contexts: [0, 1],
+      defaultMemberPermissions: '2147483648',
+      description: 'ping the bot',
+      dmPermission: false,
+      integrationTypes: [0],
+      name: 'ping',
+      nsfw: true,
+      options: [{ name: 'loud', type: 5 }],
+      type: 1,
+    };
+    expect(commandBody(props)).toEqual({
+      contexts: [0, 1],
+      default_member_permissions: '2147483648',
+      description: 'ping the bot',
+      dm_permission: false,
+      integration_types: [0],
+      name: 'ping',
+      nsfw: true,
+      options: [{ name: 'loud', type: 5 }],
+      type: 1,
+    });
+  });
+});
+
+const attrsOf = (overrides: Partial<CommandFieldsAttributes> = {}): CommandFieldsAttributes => ({
+  contexts: undefined,
+  defaultMemberPermissions: undefined,
+  description: '',
+  dmPermission: undefined,
+  integrationTypes: undefined,
+  name: 'ping',
+  nsfw: false,
+  options: [],
+  type: 1,
+  ...overrides,
+});
+
+describe('commandMatches', () => {
+  test('an exact match reports no drift', () => {
+    expect(commandMatches(attrsOf(), { name: 'ping' })).toBe(true);
+  });
+
+  test('a description change is drift', () => {
+    expect(
+      commandMatches(attrsOf({ description: 'old' }), { description: 'new', name: 'ping' }),
+    ).toBe(false);
+  });
+
+  test('a name change is drift — name is part of identity but still compared', () => {
+    expect(commandMatches(attrsOf({ name: 'ping' }), { name: 'pong' })).toBe(false);
+  });
+
+  test('options are compared by deep equality, order included', () => {
+    const live = attrsOf({ options: [{ name: 'a' }, { name: 'b' }] });
+    expect(commandMatches(live, { name: 'ping', options: [{ name: 'a' }, { name: 'b' }] })).toBe(
+      true,
+    );
+    expect(commandMatches(live, { name: 'ping', options: [{ name: 'b' }, { name: 'a' }] })).toBe(
+      false,
+    );
+  });
+
+  test('an undeclared optional field is not compared — "not mine", both directions', () => {
+    const live = attrsOf({ defaultMemberPermissions: '8', dmPermission: true });
+    expect(commandMatches(live, { name: 'ping' })).toBe(true);
+  });
+
+  /**
+   * 🔴 THE CASE THAT SHIPPED WRONG ONCE (caught in review, before merge — not measured live).
+   *   `options` must be gated exactly like every other optional field above: a declaration with
+   *   no `options` at all reports no drift against a live command that has some, because
+   *   `commandBody` already omits `options` when undeclared — comparing unconditionally would
+   *   report drift no write could ever fix (an infinite "update"), and worse, the first real
+   *   (non-dry-run) deploy would send a body with no `options` key, and Discord's real
+   *   full-replace create would wipe the live command's arguments.
+   */
+  test('undeclared options against a live command that HAS options is not drift', () => {
+    const live = attrsOf({ options: [{ name: 'loud', type: 5 }] });
+    expect(commandMatches(live, { name: 'ping' })).toBe(true);
+  });
+
+  test('a declared optional field that disagrees with live is drift', () => {
+    const live = attrsOf({ defaultMemberPermissions: '8' });
+    expect(commandMatches(live, { defaultMemberPermissions: '16', name: 'ping' })).toBe(false);
+  });
+});
+
+describe('commandFieldsOf', () => {
+  test('reads every field off an ApplicationCommandResponse-shaped object, null coerced to undefined', () => {
+    expect(
+      commandFieldsOf({
+        contexts: null,
+        default_member_permissions: null,
+        description: 'ping the bot',
+        dm_permission: undefined,
+        integration_types: undefined,
+        name: 'ping',
+        nsfw: undefined,
+        options: null,
+        type: 1,
+      }),
+    ).toEqual(attrsOf({ description: 'ping the bot' }));
+  });
+
+  test('nsfw is strictly `=== true`, never truthy-coerced', () => {
+    expect(commandFieldsOf({ description: '', name: 'x', nsfw: undefined, type: 1 }).nsfw).toBe(
+      false,
+    );
+  });
+});