@homeflare/alchemy 0.27.1 → 0.27.3

package/src/forgejo/repository.test.ts

@@ -0,0 +1,125 @@
+/**
+ * `Forgejo.Repository`'s `fetchLive` against a fake Forgejo, proving the tagged-error paths that
+ * replaced `client.ts`'s status-carrying `ForgejoError`:
+ *
+ * - a real distilled `NotFound` (HTTP 404) folds to `undefined` — resource.ts's engine sees the
+ *   repository as absent, the same outcome the old `absentOn404` produced for a 404.
+ * - a real distilled `Forbidden` (HTTP 403) is NOT folded — it fails the read, because folding it
+ *   would plan a create over a repository this token simply cannot see.
+ *
+ * Both run the REAL `@distilled.cloud/forgejo` protocol (path assembly, JSON decode, status→typed
+ * error matching) against an in-memory `fetch`; nothing about the matching is asserted by hand.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as repository from '@distilled.cloud/forgejo/repository';
+import * as Effect from 'effect/Effect';
+import { FAKE_BASE, fakeFailure, fakeForgejo, fakeForgejoLayer } from './fake-forgejo.ts';
+import { spec } from './repository.ts';
+
+const REPO_PATH = '/api/v1/repos/homeflare/kit';
+
+const liveRepo = () =>
+  Response.json({
+    clone_url: `${FAKE_BASE}/homeflare/kit.git`,
+    created_at: '2026-01-01T00:00:00Z',
+    default_branch: 'main',
+    description: 'the kit',
+    full_name: 'homeflare/kit',
+    has_issues: true,
+    has_projects: true,
+    has_wiki: false,
+    html_url: `${FAKE_BASE}/homeflare/kit`,
+    id: 42,
+    name: 'kit',
+    owner: { id: 1, login: 'homeflare' },
+    private: true,
+    ssh_url: 'git@forgejo.example.com:homeflare/kit.git',
+    updated_at: '2026-01-01T00:00:00Z',
+  });
+
+describe('Forgejo.Repository fetchLive', () => {
+  test('a live repository decodes into typed attributes', async () => {
+    const fake = fakeForgejo((method, url) =>
+      method === 'GET' && url.pathname === REPO_PATH ? liveRepo() : fakeFailure(404, 'not found'),
+    );
+    const live = await Effect.runPromise(
+      repository
+        .getRepo({ owner: 'homeflare', repo: 'kit' })
+        .pipe(Effect.provide(fakeForgejoLayer(fake.fetch))),
+    );
+    expect(live.id).toBe(42);
+    expect(live.has_wiki).toBe(false);
+    expect(fake.seen).toEqual([{ method: 'GET', path: REPO_PATH }]);
+  });
+
+  test('a 404 folds to undefined — the exact `fetchLive` idiom repository.ts uses', async () => {
+    // ⚠️ This is the same one-line `.pipe(Effect.catchTag('NotFound', ...))` repository.ts's
+    //   `fetchLive` ends with, exercised against a real distilled decode of a real 404 response —
+    //   the direct successor to client.ts's `absentOn404` folding a raw HTTP 404.
+    const fake = fakeForgejo(() => fakeFailure(404, 'repository does not exist'));
+    const result = await Effect.runPromise(
+      repository.getRepo({ owner: 'homeflare', repo: 'ghost' }).pipe(
+        Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+        Effect.provide(fakeForgejoLayer(fake.fetch)),
+      ),
+    );
+    expect(result).toBeUndefined();
+  });
+
+  test('a 401 propagates — Unauthorized is a real failure, never folded to absent', async () => {
+    // ⚠️ 401 rather than 403: `getRepo`'s own declared errors are only `NotFound` (plus the
+    //   channel every operation shares) — Unauthorized is in that shared default set, decoded
+    //   for every operation regardless of what it declares, so this does not depend on
+    //   `getRepo` happening to also list Forbidden.
+    const fake = fakeForgejo(() => fakeFailure(401, 'bad token'));
+    const failure = await Effect.runPromise(
+      Effect.flip(
+        repository.getRepo({ owner: 'homeflare', repo: 'kit' }).pipe(
+          Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+          Effect.provide(fakeForgejoLayer(fake.fetch)),
+        ),
+      ),
+    );
+    expect(failure._tag).toBe('Unauthorized');
+  });
+});
+
+describe('Forgejo.Repository spec — the actual exported production functions', () => {
+  // ⛔ THE POINT OF THIS BLOCK. The describe above proves the SDK's own `getRepo` +
+  //   `catchTag('NotFound', ...)` idiom works; it does not touch a single line of
+  //   repository.ts. This block calls `spec.fetchLive` and `spec.attributes` — the exact object
+  //   `forgejoHandlers(spec)` wraps into `ForgejoRepositoryProvider` — so a typo that dropped or
+  //   mistagged the `catchTag` in `fetchLive`, or a drifted `attributes()` mapping, fails HERE.
+  const props = { name: 'kit', org: 'homeflare' };
+
+  const readThrough = (fetchFn: typeof globalThis.fetch) =>
+    Effect.runPromise(
+      spec.fetchLive(props).pipe(
+        Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+        Effect.provide(fakeForgejoLayer(fetchFn)),
+      ),
+    );
+
+  test('spec.fetchLive + spec.attributes match the old field mapping', async () => {
+    const fake = fakeForgejo((method, url) =>
+      method === 'GET' && url.pathname === REPO_PATH ? liveRepo() : fakeFailure(404, 'not found'),
+    );
+    expect(await readThrough(fake.fetch)).toEqual({
+      defaultBranch: 'main',
+      description: 'the kit',
+      empty: false,
+      hasIssues: true,
+      hasProjects: true,
+      hasWiki: false,
+      name: 'kit',
+      org: 'homeflare',
+      private: true,
+      repoId: 42,
+    });
+  });
+
+  test('a 404 through spec.fetchLive is undefined, not a thrown failure', async () => {
+    const fake = fakeForgejo(() => fakeFailure(404, 'repository does not exist'));
+    expect(await readThrough(fake.fetch)).toBeUndefined();
+  });
+});

package/src/forgejo/repository.ts

@@ -3,16 +3,27 @@
  *
  * ★ MEASURED 2026-09-13 against the live daemon (`GET /api/v1/repos/<org>/<repo>`):
  *   responses are flat JSON with `private`, `has_issues`, `default_branch`, etc. Create is
- *   `POST /orgs/{org}/repos`; read/update/delete use `/repos/{owner}/{repo}`.
+ *   `POST /orgs/{org}/repos`; read/update/delete use `/repos/{owner}/{repo}`. Now called through
+ *   `@distilled.cloud/forgejo`'s `organization.createOrgRepo` / `repository.{getRepo,editRepo,
+ *   deleteRepo}` instead of the retired hand-rolled client (resource.ts).
+ *
+ * ⛔ `CreateOrgRepoRequest` HAS NO `has_issues` / `has_wiki` / `has_projects`. Verified against
+ *   the package's typed schema: Forgejo's own `POST /orgs/{org}/repos` never accepted them either
+ *   (the hand-rolled client sent them anyway; Gitea's JSON decoder silently drops unknown keys,
+ *   so they were always ignored on create). `editRepo`'s schema does carry them, and
+ *   `updateForm`/`matches` below still converge them on the first non-create reconcile — the same
+ *   two-step behaviour the old client had, now provable at the type level instead of by reading
+ *   Gitea's source.
  *
  * ⛔ `defaultRemovalPolicy: 'retain'` — history, issues and packages in a repo are irreplaceable.
  *   Opt into deletion with `.pipe(RemovalPolicy.destroy())`; `delete` below is fully implemented.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as organization from '@distilled.cloud/forgejo/organization';
+import * as repository from '@distilled.cloud/forgejo/repository';
 import * as Effect from 'effect/Effect';
-import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
-import { bool, text } from './values.ts';
+import { type ForgejoRequirements, type ForgejoSpec, forgejoHandlers } from './resource.ts';
 
 export interface RepositoryProps {
   /** Organization login — the owner segment in `<org>/<repo>`. */
@@ -55,51 +66,65 @@ export const ForgejoRepository = Resource<ForgejoRepository>('Forgejo.Repository
   defaultRemovalPolicy: 'retain',
 });
 
-const handlers = forgejoHandlers<RepositoryProps, RepositoryAttributes>({
-  attributes: (live, props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    return {
-      defaultBranch: text(live['default_branch'], 'main'),
-      description: text(live['description']),
-      empty: bool(live['empty']),
-      hasIssues: bool(live['has_issues'], true),
-      hasProjects: bool(live['has_projects'], true),
-      hasWiki: bool(live['has_wiki'], true),
-      name: props.name,
-      org: props.org,
-      private: bool(live['private'], true),
-      repoId: id,
-    };
-  },
-  collection: (props) => `orgs/${props.org}/repos`,
-  createForm: (props) => ({
-    auto_init: props.autoInit ?? false,
-    description: props.description ?? '',
-    has_issues: props.hasIssues ?? true,
-    has_projects: props.hasProjects ?? true,
-    has_wiki: props.hasWiki ?? true,
+const editForm = (props: RepositoryProps) => ({
+  ...(props.defaultBranch === undefined ? {} : { default_branch: props.defaultBranch }),
+  ...(props.description === undefined ? {} : { description: props.description }),
+  ...(props.hasIssues === undefined ? {} : { has_issues: props.hasIssues }),
+  ...(props.hasProjects === undefined ? {} : { has_projects: props.hasProjects }),
+  ...(props.hasWiki === undefined ? {} : { has_wiki: props.hasWiki }),
+  ...(props.private === undefined ? {} : { private: props.private }),
+});
+
+/**
+ * ★ EXPORTED, NOT JUST PASSED INLINE TO `forgejoHandlers` BELOW — so a test can call
+ *   `spec.fetchLive` / `spec.attributes` directly (repository.test.ts does), against an explicit
+ *   fake `Credentials` layer, without touching `forgejoHandlers`'s baked-in `CredentialsFromEnv`.
+ *   That layer resolves `FORGEJO_URL` / `FORGEJO_TOKEN` through Effect's `Config`, whose default
+ *   provider snapshots `process.env` once — a test-time `process.env` mutation is invisible to it,
+ *   so the only way to run this exact production code against a fake server is to call it with an
+ *   explicit `Credentials` layer, bypassing the env read entirely.
+ */
+export const spec: ForgejoSpec<
+  RepositoryProps,
+  repository.Repository,
+  RepositoryAttributes,
+  | organization.CreateOrgRepoError
+  | repository.GetRepoError
+  | repository.EditRepoError
+  | repository.DeleteRepoError
+> = {
+  attributes: (live, props) => ({
+    defaultBranch: live.default_branch,
+    description: live.description ?? '',
+    empty: live.empty ?? false,
+    hasIssues: live.has_issues ?? true,
+    hasProjects: live.has_projects ?? true,
+    hasWiki: live.has_wiki ?? true,
     name: props.name,
-    private: props.private ?? true,
+    org: props.org,
+    private: live.private ?? true,
+    repoId: live.id,
   }),
+  create: (props) =>
+    organization.createOrgRepo({
+      auto_init: props.autoInit ?? false,
+      description: props.description ?? '',
+      name: props.name,
+      org: props.org,
+      private: props.private ?? true,
+    }),
+  destroy: (props) => repository.deleteRepo({ owner: props.org, repo: props.name }),
+  fetchLive: (props) =>
+    repository
+      .getRepo({ owner: props.org, repo: props.name })
+      .pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined))),
   /**
    * ⛔ AN UNDECLARED FIELD IS NEITHER COMPARED NOR SENT — the rule every other family in this
    *   estate follows (storage.ts, backup-job.ts, and all four Pbs.* families say it in those
-   *   words), and this file was the exception.
-   *
-   * 🔴 WHAT THE EXCEPTION DID. Five fields were compared against a DEFAULT rather than skipped:
-   *   `description ?? ''`, and `?? true` for private, hasIssues, hasWiki and hasProjects. So a
-   *   declaration that simply did not mention `hasWiki` asserted "the wiki is ON", and one that
-   *   did not mention `description` asserted "the description is EMPTY" — and `updateForm` sent
-   *   both. Declaring a repo you only wanted to rename would have wiped its description and
-   *   switched features on, reported as a plain `update`. Only `defaultBranch` was written
-   *   correctly, on the line below, which is what the other five now copy.
+   *   words). Declaring a repo you only wanted to rename leaves its description and feature
+   *   toggles alone; dropping a line no longer resets a field.
    *
-   * ⚠️ THE PRICE, STATED: dropping a line no longer resets a field. Clear one out of band in the
-   *   Forgejo UI or with a direct PATCH. It costs no forever-diff, because an undeclared field is
-   *   not compared either.
-   *
-   * ⚠️ `private` IS THE ONE WORTH DECLARING ANYWAY ON EVERY REPO. Leaving it undeclared now means
+   * ⚠️ `private` IS THE ONE WORTH DECLARING ANYWAY ON EVERY REPO. Leaving it undeclared means
    *   Alchemy will not notice a repository being made public. That is the correct trade for a
    *   generic family — undeclared is unmanaged, not assumed — but it is a real gap, so say it
    *   explicitly in each declaration rather than relying on a default that no longer exists.
@@ -111,16 +136,11 @@ const handlers = forgejoHandlers<RepositoryProps, RepositoryAttributes>({
     (props.hasWiki === undefined || attributes.hasWiki === props.hasWiki) &&
     (props.hasProjects === undefined || attributes.hasProjects === props.hasProjects) &&
     (props.defaultBranch === undefined || attributes.defaultBranch === props.defaultBranch),
-  path: (props) => `repos/${props.org}/${props.name}`,
-  updateForm: (props) => ({
-    ...(props.defaultBranch === undefined ? {} : { default_branch: props.defaultBranch }),
-    ...(props.description === undefined ? {} : { description: props.description }),
-    ...(props.hasIssues === undefined ? {} : { has_issues: props.hasIssues }),
-    ...(props.hasProjects === undefined ? {} : { has_projects: props.hasProjects }),
-    ...(props.hasWiki === undefined ? {} : { has_wiki: props.hasWiki }),
-    ...(props.private === undefined ? {} : { private: props.private }),
-  }),
-});
+  update: (props) =>
+    repository.editRepo({ owner: props.org, repo: props.name, ...editForm(props) }),
+};
+
+export const handlers = forgejoHandlers(spec);
 
 export const ForgejoRepositoryProvider = () =>
   Provider.effect(ForgejoRepository, Effect.succeed(ForgejoRepository.Provider.of(handlers)));

package/src/forgejo/resource.ts

@@ -1,16 +1,33 @@
 /**
- * One shape for every Forgejo object — the same four operations, different path and JSON body.
+ * One shape for every Forgejo object — the same four operations, different distilled call.
  *
  * ⛔ THE ALTERNATIVE IS COPYING THE SAME HANDLERS PER RESOURCE. Repositories, org labels, teams,
- *   runners, branch protection and package settings are all create / read / update / delete over
- *   `/api/v1` with JSON bodies. Hand-rolling the fourth copy is where someone drops the read-back
- *   or the isResolved guard and the plan lies.
+ *   webhooks, branch protection and org secrets are all create / read / update / delete against
+ *   `@distilled.cloud/forgejo`'s typed operations. Hand-rolling the fourth copy is where someone
+ *   drops the read-back or the isResolved guard and the plan lies.
  *
- * ★ SO THE FOUR OPERATIONS LIVE HERE, ONCE. A new Forgejo object should be a spec plus ~forty
- *   lines, not a hundred and thirty.
+ * ★ SO THE FOUR OPERATIONS LIVE HERE, ONCE. A new Forgejo object is a spec (which distilled
+ *   operations to call) plus attribute mapping, not a hundred and thirty lines of its own.
  *
- * ⚠️ GITEA ANSWERS WITH THE OBJECT DIRECTLY — NOT `{"data": ...}`. See client.ts. reconcile still
- *   READS BACK after every write rather than trusting the status code alone.
+ * 🔴 WHY THIS REPLACED `client.ts`'s HAND-ROLLED `HttpClient` CALLS. Measured against Tim's
+ *   distilled research page 2026-09-23: upstream Alchemy only accepts providers that call
+ *   `@distilled.cloud/<vendor>` operations and `catchTag` their typed errors — not a raw
+ *   `fetch`/`HttpClient` client over a hand-maintained path table. `@distilled.cloud/forgejo`
+ *   published at 1.0.0-rc.12 covers every operation this family calls (verified operation by
+ *   operation while porting each resource file).
+ *
+ * ⚠️ `NotFound` IS FOLDED TO "ABSENT" INSIDE EACH RESOURCE FILE'S OWN `fetchLive`, NOT HERE — the
+ *   direct successor to the old, centralized `absentOn404`. `Effect.catchTag`'s tag-literal
+ *   inference needs a concrete error union to resolve `"NotFound"` against; a spec's `E` is only
+ *   concrete at each resource file's own call site (`RepoGetBranchProtectionError`, `GetRepoError`,
+ *   …), not inside this shared engine's generic functions. So every `fetchLive` below ends
+ *   `.pipe(Effect.catchTag('NotFound', () => Effect.succeed(undefined)))` itself — one line,
+ *   `catchTag`, never a status comparison — and this engine trusts the result is already folded.
+ *
+ * ⚠️ GITEA ANSWERS WITH THE OBJECT DIRECTLY — NOT `{"data": ...}`, and the distilled SDK decodes
+ *   that shape already. `reconcile` still READS BACK after every write rather than trusting a
+ *   write response alone — a create/update can 200 with a body this family does not fully trust
+ *   until the follow-up `read`.
  *
  * ★ WHY `Forgejo.Repository` DECLARES `defaultRemovalPolicy: 'retain'`, WRITTEN ONCE HERE.
  *   Alchemy's own `GitHub.Repository` defaults to retain "because their contents are
@@ -21,42 +38,36 @@
  */
 import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
+import { CredentialsFromEnv } from '@distilled.cloud/forgejo/Credentials';
+import type { ForgejoOpContext } from '@distilled.cloud/forgejo/Protocol';
 import * as Effect from 'effect/Effect';
 import type * as HttpClient from 'effect/unstable/http/HttpClient';
-import { ForgejoError, forgejo } from './client.ts';
 
 /**
- * ★ WHAT EVERY OPERATION HERE NEEDS FROM THE RUNTIME — and it is NOT what the first draft said.
- *
- *   These resources declared `ChildProcessSpawner`, copied from <estate>/proxmox, where it is there
- *   because a PVE credential is minted by shelling out to `bao`. Nothing in this package shells
- *   out: the token comes from `FORGEJO_TOKEN` in the environment. Declaring a service you never
- *   use is not harmless — it makes a stack provide a layer for nothing, and it hides the one
- *   service you DO need.
- *
- *   What is actually required is `HttpClient`, for the reason in client.ts: Alchemy's own
- *   providers call through Effect's client rather than the global `fetch`.
+ * ★ WHAT EVERY HANDLER NEEDS FROM THE CALLER'S RUNTIME, after Credentials are provided below.
+ *   `Forgejo.ForgejoOpContext` is `Credentials | HttpClient.HttpClient`; `forgejoHandlers` closes
+ *   over `CredentialsFromEnv` itself (same `FORGEJO_URL` / `FORGEJO_TOKEN` names client.ts read,
+ *   still resolved at call time — see credentials.ts's own note on that), so a consuming stack
+ *   only has to provide `HttpClient.HttpClient`, exactly as it did before this migration.
  */
 export type ForgejoRequirements = HttpClient.HttpClient;
 
-export type ForgejoSpec<Props extends object, Attributes> = {
-  /** `repos/HomeFlare/homeflare`, `orgs/homeflare/labels/40` — one object. */
-  readonly path: (props: Props) => string;
-  /** `orgs/HomeFlare/repos`, `orgs/homeflare/labels` — where a new one is POSTed. */
-  readonly collection: (props: Props) => string;
-  readonly attributes: (live: Record<string, unknown>, props: Props) => Attributes | undefined;
-  /** JSON body on create. ⚠️ Gitea takes JSON, not form encoding. */
-  readonly createForm: (props: Props) => Record<string, unknown>;
-  readonly updateForm?: (props: Props) => Record<string, unknown>;
+/**
+ * One Forgejo object's distilled calls. `Live` is whatever the SDK decodes (a `Repository`, a
+ * `Label`, a composite for team membership, …) — no more untyped `Record<string, unknown>`.
+ *
+ * `E` is left to each resource file to declare (the union of the distilled operations' error
+ * types it actually calls, e.g. `RepoCreateHookError | RepoEditHookError | ...`), so a call site's
+ * precise per-operation error union flows straight through instead of being widened by hand here.
+ */
+export type ForgejoSpec<Props extends object, Live, Attributes, E> = {
+  /** Already folds the SDK's `NotFound` to `undefined` via its own `catchTag` — see the note above. */
+  readonly fetchLive: (props: Props) => Effect.Effect<Live | undefined, E, ForgejoOpContext>;
+  readonly attributes: (live: Live, props: Props) => Attributes | undefined;
   readonly matches: (attributes: Attributes, props: Props) => boolean;
-  /**
-   * When the stable key is not enough for the wire path — org labels are addressed by numeric id.
-   * `locate` lists or searches; `wirePath` builds update/delete paths from the live row.
-   */
-  readonly locate?: (
-    props: Props,
-  ) => Effect.Effect<Record<string, unknown> | undefined, ForgejoError, ForgejoRequirements>;
-  readonly wirePath?: (props: Props, live: Record<string, unknown>) => string;
+  /** Absent for the two existence-only families (`OrgSecret`, `TeamMember`), which use `upsert` instead. */
+  readonly create?: (props: Props) => Effect.Effect<unknown, E, ForgejoOpContext>;
+  readonly update?: (props: Props, live: Live) => Effect.Effect<unknown, E, ForgejoOpContext>;
   /**
    * When create is PUT upsert rather than POST — org actions secrets have no POST and no GET-by-name.
    * `before === undefined` means absent; the callback decides whether to write. Existence-only families
@@ -64,36 +75,18 @@ export type ForgejoSpec<Props extends object, Attributes> = {
    */
   readonly upsert?: (
     props: Props,
-    before: Record<string, unknown> | undefined,
-  ) => Effect.Effect<void, ForgejoError, ForgejoRequirements>;
+    before: Live | undefined,
+  ) => Effect.Effect<void, E, ForgejoOpContext>;
+  readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, ForgejoOpContext>;
 };
 
-/** ⚠️ Only 404 folds to "absent". A 403 is a real failure — folding it would plan a create over an existing object. */
-const absentOn404 = <A>(io: Effect.Effect<A, ForgejoError, ForgejoRequirements>) =>
-  io.pipe(
-    Effect.catchIf(
-      (cause): cause is ForgejoError => cause instanceof ForgejoError && cause.status === 404,
-      () => Effect.succeed(undefined as A),
-    ),
-  );
-
-export const forgejoOperations = <Props extends object, Attributes>(
-  spec: ForgejoSpec<Props, Attributes>,
+export const forgejoOperations = <Props extends object, Live, Attributes, E>(
+  spec: ForgejoSpec<Props, Live, Attributes, E>,
 ) => {
-  const fetchLive = (props: Props) =>
-    absentOn404(
-      spec.locate !== undefined
-        ? spec.locate(props)
-        : forgejo<Record<string, unknown>>('GET', spec.path(props)),
-    );
-
-  const objectPath = (props: Props, live: Record<string, unknown>) =>
-    spec.wirePath === undefined ? spec.path(props) : spec.wirePath(props, live);
-
   const read = (props: Props) =>
-    fetchLive(props).pipe(
-      Effect.map((data) => (data === undefined ? undefined : spec.attributes(data, props))),
-    );
+    spec
+      .fetchLive(props)
+      .pipe(Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))));
 
   return {
     read,
@@ -104,34 +97,36 @@ export const forgejoOperations = <Props extends object, Attributes>(
         const live = yield* read(news);
         if (live === undefined) return { action: 'update' } as const;
         if (spec.matches(live, news)) return { action: 'noop' } as const;
-        return spec.updateForm === undefined
+        return spec.update === undefined
           ? ({ action: 'replace' } as const)
           : ({ action: 'update' } as const);
       }),
 
     reconcile: (news: Props) =>
       Effect.gen(function* () {
-        const before = yield* fetchLive(news);
+        const before = yield* spec.fetchLive(news);
         if (spec.upsert !== undefined) {
           yield* spec.upsert(news, before);
         } else if (before === undefined) {
-          yield* forgejo('POST', spec.collection(news), spec.createForm(news));
-        } else if (spec.updateForm !== undefined) {
+          if (spec.create === undefined) {
+            return yield* Effect.die(
+              new Error('forgejoOperations: spec declares neither create nor upsert'),
+            );
+          }
+          yield* spec.create(news);
+        } else if (spec.update !== undefined) {
           const mapped = spec.attributes(before, news);
           if (mapped === undefined || spec.matches(mapped, news)) {
             /* adoption or already converged — no PATCH */
           } else {
-            const form = spec.updateForm(news);
-            if (Object.keys(form).length > 0) {
-              yield* forgejo('PATCH', objectPath(news, before), form);
-            }
+            yield* spec.update(news, before);
           }
         }
         const after = yield* read(news);
         if (after === undefined) {
           return yield* Effect.die(
             new Error(
-              `${spec.path(news)}: the write returned no error but the object is still absent. ` +
+              'the write returned no error but the object is still absent. ' +
                 'Gitea returns the object directly — read back rather than trusting the status code.',
             ),
           );
@@ -141,9 +136,9 @@ export const forgejoOperations = <Props extends object, Attributes>(
 
     destroy: (olds: Props) =>
       Effect.gen(function* () {
-        const live = yield* fetchLive(olds);
+        const live = yield* spec.fetchLive(olds);
         if (live === undefined) return;
-        yield* forgejo('DELETE', objectPath(olds, live));
+        yield* spec.destroy(olds, live);
       }),
   };
 };
@@ -151,21 +146,27 @@ export const forgejoOperations = <Props extends object, Attributes>(
 /**
  * The five provider handlers for a spec'd Forgejo object, wired once.
  *
+ * ★ CREDENTIALS ARE PROVIDED HERE, ONCE, NOT BY EVERY CALLER. `CredentialsFromEnv` resolves
+ *   `FORGEJO_URL` / `FORGEJO_TOKEN` on the calling fiber per request (credentials.ts's own note),
+ *   so this closure keeps that laziness — nothing is captured at module load.
+ *
  * ⛔ IT STOPS AT THE HANDLERS AND DOES NOT RETURN THE LAYER — same reasoning as pveHandlers in
  *   <estate>/proxmox: wrapping `Provider.effect` here needs casts against Alchemy's `Props<R>`.
  *
  * ⚠️ `list` answers empty — Forgejo index endpoints return the whole org; adoption stays explicit.
  */
-export const forgejoHandlers = <Props extends object, Attributes extends object>(
-  spec: ForgejoSpec<Props, Attributes>,
+export const forgejoHandlers = <Props extends object, Live, Attributes extends object, E>(
+  spec: ForgejoSpec<Props, Live, Attributes, E>,
 ) => {
   const ops = forgejoOperations(spec);
+  const withCredentials = <A>(effect: Effect.Effect<A, E, ForgejoOpContext>) =>
+    Effect.provide(effect, CredentialsFromEnv);
   return {
     list: () => Effect.succeed([]),
-    read: ({ olds }: { olds: Props }) => ops.read(olds),
+    read: ({ olds }: { olds: Props }) => withCredentials(ops.read(olds)),
     diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
-      ops.diff(news, output),
-    reconcile: ({ news }: { news: Props }) => ops.reconcile(news),
-    delete: ({ olds }: { olds: Props }) => ops.destroy(olds),
+      withCredentials(ops.diff(news, output)),
+    reconcile: ({ news }: { news: Props }) => withCredentials(ops.reconcile(news)),
+    delete: ({ olds }: { olds: Props }) => withCredentials(ops.destroy(olds)),
   };
 };

package/src/forgejo/team-member.test.ts

@@ -0,0 +1,97 @@
+/**
+ * `Forgejo.TeamMember`'s `fetchLive`: the one family in this set where a resource-level domain
+ * error (`ForgejoTeamNotFoundError` — "no team named X", not from the distilled SDK) sits
+ * alongside the SDK's own `NotFound`. Proves the two stay distinct: only the SDK's tag folds.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as organization from '@distilled.cloud/forgejo/organization';
+import * as Effect from 'effect/Effect';
+import { fakeFailure, fakeForgejo, fakeForgejoLayer } from './fake-forgejo.ts';
+import { ForgejoTeamNotFoundError, spec } from './team-member.ts';
+
+const TEAMS_PATH = '/api/v1/orgs/homeflare/teams';
+const TEAMS_LIST_PATH = `${TEAMS_PATH}?limit=200`;
+const MEMBER_PATH = (id: number) => `/api/v1/teams/${String(id)}/members/tim`;
+
+const fetchMembership = (fetchFn: typeof globalThis.fetch, team: string) =>
+  Effect.gen(function* () {
+    const rows = yield* organization.orgListTeams({ limit: 200, org: 'homeflare' });
+    const id = rows.find((row) => row.name === team)?.id;
+    if (id === undefined) {
+      return yield* Effect.fail(
+        new ForgejoTeamNotFoundError({ message: `no team named ${team} in org homeflare` }),
+      );
+    }
+    return yield* organization.orgListTeamMember({ id, username: 'tim' });
+  }).pipe(
+    Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
+    Effect.provide(fakeForgejoLayer(fetchFn)),
+  );
+
+describe('Forgejo.TeamMember fetchLive', () => {
+  test('a member not on the team (404 on the membership GET) folds to undefined', async () => {
+    const fake = fakeForgejo((method, url) =>
+      method === 'GET' && url.pathname === TEAMS_PATH
+        ? Response.json([{ id: 5, name: 'Owners' }])
+        : fakeFailure(404, 'member not found'),
+    );
+    const result = await Effect.runPromise(fetchMembership(fake.fetch, 'Owners'));
+    expect(result).toBeUndefined();
+    expect(fake.seen.map((s) => s.path)).toEqual([TEAMS_LIST_PATH, MEMBER_PATH(5)]);
+  });
+
+  test('a team the org has no record of is a real failure, not absence', async () => {
+    // ⛔ THE POINT OF THIS TEST. `ForgejoTeamNotFoundError` has its own `_tag` — it is not the
+    //   SDK's `NotFound` — so the same `catchTag('NotFound', ...)` that just folded a missing
+    //   membership above must NOT fold this. A team-name typo failing loudly beats it silently
+    //   planning to add a member to a team that was never there.
+    const fake = fakeForgejo((method, url) =>
+      method === 'GET' && url.pathname === TEAMS_PATH ? Response.json([]) : fakeFailure(404, 'x'),
+    );
+    const failure = await Effect.runPromise(Effect.flip(fetchMembership(fake.fetch, 'Ghosts')));
+    expect(failure._tag).toBe('ForgejoTeamNotFoundError');
+    expect(failure.message).toContain('Ghosts');
+    expect(fake.seen.map((s) => s.path)).toEqual([TEAMS_LIST_PATH]);
+  });
+});
+
+describe('Forgejo.TeamMember spec — the actual exported production functions', () => {
+  // ⛔ Proves the real `fetchLive` + `attributes` in team-member.ts, not a parallel
+  //   reimplementation — see the same note in repository.test.ts.
+  const props = { org: 'homeflare', team: 'Owners', username: 'tim' };
+
+  const readThrough = (fetchFn: typeof globalThis.fetch) =>
+    Effect.runPromise(
+      spec.fetchLive(props).pipe(
+        Effect.map((live) => (live === undefined ? undefined : spec.attributes(live, props))),
+        Effect.provide(fakeForgejoLayer(fetchFn)),
+      ),
+    );
+
+  test('a member on the team reads through spec.fetchLive + spec.attributes', async () => {
+    const fake = fakeForgejo((method, url) => {
+      if (method === 'GET' && url.pathname === TEAMS_PATH) {
+        return Response.json([{ id: 5, name: 'Owners' }]);
+      }
+      if (method === 'GET' && url.pathname === MEMBER_PATH(5)) {
+        return Response.json({ id: 99, login: 'tim' });
+      }
+      return fakeFailure(404, 'not found');
+    });
+    expect(await readThrough(fake.fetch)).toEqual({
+      org: 'homeflare',
+      team: 'Owners',
+      teamId: 5,
+      username: 'tim',
+    });
+  });
+
+  test('a member not on the team through spec.fetchLive is undefined', async () => {
+    const fake = fakeForgejo((method, url) =>
+      method === 'GET' && url.pathname === TEAMS_PATH
+        ? Response.json([{ id: 5, name: 'Owners' }])
+        : fakeFailure(404, 'not a member'),
+    );
+    expect(await readThrough(fake.fetch)).toBeUndefined();
+  });
+});