@homeflare/alchemy 0.27.0 → 0.27.2

package/src/forgejo/org-label.ts

@@ -12,18 +12,19 @@
  *   from the stack does not DELETE it unless the caller opts into `.pipe(RemovalPolicy.destroy())`.
  *   That matches the script's never-delete posture while still allowing a deliberate destroy.
  *
- * ⚠️ THE WIRE PATH USES NUMERIC ID, NOT NAME — measured on live org labels: PATCH and DELETE are
- *   `/orgs/{org}/labels/{id}`. `locate` lists by name; `wirePath` uses the id from that row.
+ * ⚠️ THE WIRE PATH USES NUMERIC ID, NOT NAME — measured on live org labels: edit and delete are
+ *   `orgEditLabel`/`orgDeleteLabel({ org, id })`. `fetchLive` lists by name; the id comes off that
+ *   row for `update`/`destroy`, the same seam the hand-rolled `wirePath` used.
  *
  * ⛔ TOKEN NEEDS `write:organization` FOR RECONCILE — the mcp-read token lacks it (POST 403
  *   measured 2026-09-13). Plan/deploy needs a provision-scoped credential in `FORGEJO_TOKEN`.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as organization from '@distilled.cloud/forgejo/organization';
 import * as Effect from 'effect/Effect';
-import { forgejo } from './client.ts';
-import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
-import { bool, color, text } from './values.ts';
+import { type ForgejoRequirements, type ForgejoSpec, forgejoHandlers } from './resource.ts';
+import { color } from './values.ts';
 
 export interface OrgLabelProps {
   /** Organization login — `homeflare` / `HomeFlare` must match the live org. */
@@ -57,44 +58,53 @@ export const ForgejoOrgLabel = Resource<ForgejoOrgLabel>('Forgejo.OrgLabel', {
   defaultRemovalPolicy: 'retain',
 });
 
-const handlers = forgejoHandlers<OrgLabelProps, OrgLabelAttributes>({
-  attributes: (live, props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    return {
-      color: color(live['color']),
-      description: text(live['description']),
-      exclusive: bool(live['exclusive']),
-      labelId: id,
-      name: props.name,
-      org: props.org,
-    };
-  },
-  collection: (props) => `orgs/${props.org}/labels`,
-  createForm: (props) => ({
-    color: color(props.color),
-    description: props.description ?? '',
-    exclusive: props.exclusive ?? false,
+/** ★ EXPORTED for direct testing with an explicit fake `Credentials` layer — see repository.ts. */
+export const spec: ForgejoSpec<
+  OrgLabelProps,
+  organization.Label,
+  OrgLabelAttributes,
+  | organization.OrgCreateLabelError
+  | organization.OrgEditLabelError
+  | organization.OrgDeleteLabelError
+  | organization.OrgListLabelsError
+> = {
+  attributes: (live, props) => ({
+    color: color(live.color),
+    description: live.description ?? '',
+    exclusive: live.exclusive ?? false,
+    labelId: live.id,
     name: props.name,
+    org: props.org,
   }),
-  locate: (props) =>
-    forgejo<Record<string, unknown>[]>('GET', `orgs/${props.org}/labels?limit=200`).pipe(
-      Effect.map((rows) =>
-        Array.isArray(rows) ? rows.find((row) => row['name'] === props.name) : undefined,
-      ),
+  create: (props) =>
+    organization.orgCreateLabel({
+      color: color(props.color),
+      description: props.description ?? '',
+      exclusive: props.exclusive ?? false,
+      name: props.name,
+      org: props.org,
+    }),
+  destroy: (props, live) => organization.orgDeleteLabel({ org: props.org, id: live.id }),
+  fetchLive: (props) =>
+    organization.orgListLabels({ org: props.org, limit: 200 }).pipe(
+      Effect.map((rows) => rows.find((row) => row.name === props.name)),
+      Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
     ),
   matches: (attributes, props) =>
     attributes.color === color(props.color) &&
     attributes.description === (props.description ?? '') &&
     attributes.exclusive === (props.exclusive ?? false),
-  path: (props) => `orgs/${props.org}/labels/${props.name}`,
-  updateForm: (props) => ({
-    color: color(props.color),
-    description: props.description ?? '',
-    exclusive: props.exclusive ?? false,
-  }),
-  wirePath: (props, live) => `orgs/${props.org}/labels/${String(live['id'])}`,
-});
+  update: (props, live) =>
+    organization.orgEditLabel({
+      color: color(props.color),
+      description: props.description ?? '',
+      exclusive: props.exclusive ?? false,
+      id: live.id,
+      org: props.org,
+    }),
+};
+
+export const handlers = forgejoHandlers(spec);
 
 export const ForgejoOrgLabelProvider = () =>
   Provider.effect(ForgejoOrgLabel, Effect.succeed(ForgejoOrgLabel.Provider.of(handlers)));

package/src/forgejo/org-team.ts

@@ -3,24 +3,31 @@
  *
  * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json` (Forgejo 16.x OpenAPI): create is
  *   `POST /orgs/{org}/teams`; read/update/delete use numeric id at `/teams/{id}` — not the name.
+ *   Now `organization.orgCreateTeam` / `orgListTeams` / `orgEditTeam` / `orgDeleteTeam`.
  *
- * ⚠️ PATCH AND DELETE USE `/teams/{id}` — same seam as org labels. `locate` lists by name;
- *   `wirePath` carries the id from that row.
+ * ⚠️ `orgEditTeam`/`orgDeleteTeam` TAKE ONLY `{ id, ... }` — NO `org` FIELD. The package's schema
+ *   confirms Forgejo's edit/delete routes are `/teams/{id}` with no org segment; `fetchLive` lists
+ *   by name and `update`/`destroy` carry the id off that row, same seam as org labels.
+ *
+ * ⚠️ `live.permission` IS TYPED `"none" | "read" | "write" | "admin" | "owner"` IN THE PACKAGE —
+ *   wider than this family's own `TeamPermission`. The guard below keeps the original behaviour:
+ *   an out-of-range value (`none`/`owner`) folds `attributes` to `undefined` rather than lying
+ *   about which of the three this family manages the team is at.
  *
  * ⛔ TOKEN NEEDS `write:organization` TO CREATE OR PATCH — read list/get needs `read:organization`.
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as organization from '@distilled.cloud/forgejo/organization';
 import * as Effect from 'effect/Effect';
-import { forgejo } from './client.ts';
-import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
-import { bool, recordEqual, stringArray, stringRecord, text } from './values.ts';
+import { type ForgejoRequirements, type ForgejoSpec, forgejoHandlers } from './resource.ts';
+import { recordEqual, stringArray, stringRecord } from './values.ts';
 
 export type TeamPermission = 'read' | 'write' | 'admin';
 
 export interface OrgTeamProps {
   org: string;
-  /** Team name — primary locate key; sent on every PATCH body. */
+  /** Team name — primary locate key; sent on every edit body. */
   name: string;
   description?: string;
   permission?: TeamPermission;
@@ -62,31 +69,37 @@ const teamForm = (props: OrgTeamProps) => ({
   ...(props.unitsMap === undefined ? {} : { units_map: props.unitsMap }),
 });
 
-const handlers = forgejoHandlers<OrgTeamProps, OrgTeamAttributes>({
+/** ★ EXPORTED for direct testing with an explicit fake `Credentials` layer — see repository.ts. */
+export const spec: ForgejoSpec<
+  OrgTeamProps,
+  organization.Team,
+  OrgTeamAttributes,
+  | organization.OrgCreateTeamError
+  | organization.OrgEditTeamError
+  | organization.OrgDeleteTeamError
+  | organization.OrgListTeamsError
+> = {
   attributes: (live, props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    const permission = text(live['permission'], 'read');
+    const permission = live.permission ?? 'read';
     if (permission !== 'read' && permission !== 'write' && permission !== 'admin') return undefined;
     return {
-      canCreateOrgRepo: bool(live['can_create_org_repo']),
-      description: text(live['description']),
-      includesAllRepositories: bool(live['includes_all_repositories']),
+      canCreateOrgRepo: live.can_create_org_repo ?? false,
+      description: live.description ?? '',
+      includesAllRepositories: live.includes_all_repositories ?? false,
       name: props.name,
       org: props.org,
       permission,
-      teamId: id,
-      units: stringArray(live['units']),
-      unitsMap: stringRecord(live['units_map']),
+      teamId: live.id,
+      units: stringArray(live.units ?? []),
+      unitsMap: stringRecord(live.units_map ?? {}),
     };
   },
-  collection: (props) => `orgs/${props.org}/teams`,
-  createForm: teamForm,
-  locate: (props) =>
-    forgejo<Record<string, unknown>[]>('GET', `orgs/${props.org}/teams?limit=200`).pipe(
-      Effect.map((rows) =>
-        Array.isArray(rows) ? rows.find((row) => row['name'] === props.name) : undefined,
-      ),
+  create: (props) => organization.orgCreateTeam({ org: props.org, ...teamForm(props) }),
+  destroy: (_props, live) => organization.orgDeleteTeam({ id: live.id }),
+  fetchLive: (props) =>
+    organization.orgListTeams({ org: props.org, limit: 200 }).pipe(
+      Effect.map((rows) => rows.find((row) => row.name === props.name)),
+      Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
     ),
   matches: (attributes, props) =>
     attributes.description === (props.description ?? '') &&
@@ -96,10 +109,10 @@ const handlers = forgejoHandlers<OrgTeamProps, OrgTeamAttributes>({
     (props.units === undefined ||
       stringArray(props.units).join('\0') === attributes.units.join('\0')) &&
     (props.unitsMap === undefined || recordEqual(attributes.unitsMap, props.unitsMap)),
-  path: (props) => `orgs/${props.org}/teams/${props.name}`,
-  updateForm: teamForm,
-  wirePath: (_props, live) => `teams/${String(live['id'])}`,
-});
+  update: (props, live) => organization.orgEditTeam({ id: live.id, ...teamForm(props) }),
+};
+
+export const handlers = forgejoHandlers(spec);
 
 export const ForgejoOrgTeamProvider = () =>
   Provider.effect(ForgejoOrgTeam, Effect.succeed(ForgejoOrgTeam.Provider.of(handlers)));

package/src/forgejo/repo-webhook-form.ts

@@ -1,15 +1,20 @@
 /**
- * JSON bodies for `Forgejo.RepoWebhook` — split to keep repo-webhook.ts under the line cap.
+ * `config` bodies for `Forgejo.RepoWebhook` — split to keep repo-webhook.ts under the line cap.
  *
  * ⛔ `config.secret` IS NEVER A PROP. When present it is read from `FORGEJO_HOOK_SECRET_*` at
  *   create/update time only (see hookSecretEnvKey in values.ts). Alchemy attributes are Postgres
  *   plaintext — a webhook HMAC secret must not be stored there.
+ *
+ * ⛔ NO `name` FIELD ON EITHER SIDE. `@distilled.cloud/forgejo`'s `RepoCreateHookRequest` and
+ *   `Hook` (the create input and the read/list output) have no `name` property — verified against
+ *   the package's schema. The hand-rolled client sent `name: props.name` on create anyway; Gitea's
+ *   JSON decoder silently dropped it, so `locate` never actually matched by name either (its
+ *   `row['name']` read was always `undefined` on an untyped response) — matching was always by
+ *   URL in practice. `props.name`/`RepoWebhookAttributes.name` stay as this family's own stable
+ *   key; nothing on the wire carries it.
  */
 import type { RepoWebhookProps } from './repo-webhook.ts';
-import { hookSecretEnvKey, stringRecord, text } from './values.ts';
-
-export const hookUrl = (live: Record<string, unknown>) =>
-  text(live['url']) || text(stringRecord(live['config'])['url']);
+import { hookSecretEnvKey } from './values.ts';
 
 export const hookConfigForm = (props: RepoWebhookProps, includeSecret: boolean) => {
   const config: Record<string, string> = {
@@ -23,25 +28,3 @@ export const hookConfigForm = (props: RepoWebhookProps, includeSecret: boolean)
   }
   return config;
 };
-
-export const createHookForm = (props: RepoWebhookProps) => ({
-  active: props.active ?? true,
-  ...(props.authorizationHeader === undefined
-    ? {}
-    : { authorization_header: props.authorizationHeader }),
-  ...(props.branchFilter === undefined ? {} : { branch_filter: props.branchFilter }),
-  config: hookConfigForm(props, true),
-  events: props.events,
-  name: props.name,
-  type: props.type,
-});
-
-export const updateHookForm = (props: RepoWebhookProps) => ({
-  active: props.active ?? true,
-  ...(props.authorizationHeader === undefined
-    ? {}
-    : { authorization_header: props.authorizationHeader }),
-  ...(props.branchFilter === undefined ? {} : { branch_filter: props.branchFilter }),
-  config: hookConfigForm(props, false),
-  events: props.events,
-});

package/src/forgejo/repo-webhook.ts

@@ -2,7 +2,13 @@
  * `Forgejo.RepoWebhook` — one repository webhook under `/repos/{owner}/{repo}/hooks`.
  *
  * ★ READ OFF `<estate>/mcp-servers/docs/api/upstream/forgejo.json`: create is POST collection; read/update/delete
- *   use numeric hook id at `/repos/{owner}/{repo}/hooks/{id}`. `locate` lists and matches on `name`.
+ *   use numeric hook id at `/repos/{owner}/{repo}/hooks/{id}`. Now `repository.repoCreateHook` /
+ *   `repoListHooks` / `repoEditHook` / `repoDeleteHook`. `fetchLive` lists and matches on `url` —
+ *   see repo-webhook-form.ts for why name was never the real match key.
+ *
+ * ⚠️ `Hook.url` IS A REQUIRED STRING IN THE PACKAGE'S SCHEMA — the `config.url` fallback the
+ *   hand-rolled client carried (`stringRecord(live['config'])['url']`) is gone; a response
+ *   without `url` now fails the operation's decode.
  *
  * ⛔ NO WEBHOOK `secret` IN PROPS OR ATTRIBUTES. Optional HMAC material is env-only at write time
  *   (`FORGEJO_HOOK_SECRET_*` — see repo-webhook-form.ts). `hookConfigPublic` strips `secret` on read.
@@ -11,11 +17,11 @@
  */
 import { Resource } from 'alchemy';
 import * as Provider from 'alchemy/Provider';
+import * as repository from '@distilled.cloud/forgejo/repository';
 import * as Effect from 'effect/Effect';
-import { forgejo } from './client.ts';
-import { createHookForm, hookUrl, updateHookForm } from './repo-webhook-form.ts';
-import { type ForgejoRequirements, forgejoHandlers } from './resource.ts';
-import { bool, hookConfigPublic, stringArray, text } from './values.ts';
+import { hookConfigForm } from './repo-webhook-form.ts';
+import { type ForgejoRequirements, type ForgejoSpec, forgejoHandlers } from './resource.ts';
+import { hookConfigPublic, stringArray } from './values.ts';
 
 export type RepoWebhookType =
   | 'dingtalk'
@@ -33,7 +39,7 @@ export type RepoWebhookType =
 export interface RepoWebhookProps {
   owner: string;
   repo: string;
-  /** Stable locate key — also sent as Hook.name on create. */
+  /** Stable locate key on this side only — Forgejo hooks have no `name` field (see the form file). */
   name: string;
   type: RepoWebhookType;
   url: string;
@@ -68,38 +74,51 @@ export interface ForgejoRepoWebhook extends Resource<
 
 export const ForgejoRepoWebhook = Resource<ForgejoRepoWebhook>('Forgejo.RepoWebhook');
 
-const handlers = forgejoHandlers<RepoWebhookProps, RepoWebhookAttributes>({
+/** ★ EXPORTED for direct testing with an explicit fake `Credentials` layer — see repository.ts. */
+export const spec: ForgejoSpec<
+  RepoWebhookProps,
+  repository.Hook,
+  RepoWebhookAttributes,
+  | repository.RepoCreateHookError
+  | repository.RepoEditHookError
+  | repository.RepoDeleteHookError
+  | repository.RepoListHooksError
+> = {
   attributes: (live, props) => {
-    const id = live['id'];
-    if (typeof id !== 'number') return undefined;
-    const config = hookConfigPublic(live['config']);
-    const type = text(live['type']);
+    const config = hookConfigPublic(live.config);
     return {
-      active: bool(live['active'], true),
-      authorizationHeader: text(live['authorization_header']),
-      branchFilter: text(live['branch_filter']),
-      contentType: text(config['content_type'], text(live['content_type'], 'json')),
-      events: stringArray(live['events']),
-      hookId: id,
+      active: live.active ?? true,
+      authorizationHeader: live.authorization_header ?? '',
+      branchFilter: live.branch_filter ?? '',
+      contentType: config['content_type'] ?? live.content_type ?? 'json',
+      events: stringArray(live.events ?? []),
+      hookId: live.id,
       name: props.name,
       owner: props.owner,
       repo: props.repo,
-      type: type as RepoWebhookType,
-      url: hookUrl(live),
+      type: live.type as RepoWebhookType,
+      url: live.url,
     };
   },
-  collection: (props) => `repos/${props.owner}/${props.repo}/hooks`,
-  createForm: createHookForm,
-  locate: (props) =>
-    forgejo<Record<string, unknown>[]>(
-      'GET',
-      `repos/${props.owner}/${props.repo}/hooks?limit=200`,
-    ).pipe(
-      Effect.map((rows) =>
-        Array.isArray(rows)
-          ? rows.find((row) => text(row['name']) === props.name || hookUrl(row) === props.url)
-          : undefined,
-      ),
+  create: (props) =>
+    repository.repoCreateHook({
+      active: props.active ?? true,
+      ...(props.authorizationHeader === undefined
+        ? {}
+        : { authorization_header: props.authorizationHeader }),
+      ...(props.branchFilter === undefined ? {} : { branch_filter: props.branchFilter }),
+      config: hookConfigForm(props, true),
+      events: props.events,
+      owner: props.owner,
+      repo: props.repo,
+      type: props.type,
+    }),
+  destroy: (props, live) =>
+    repository.repoDeleteHook({ owner: props.owner, repo: props.repo, id: live.id }),
+  fetchLive: (props) =>
+    repository.repoListHooks({ owner: props.owner, repo: props.repo, limit: 200 }).pipe(
+      Effect.map((rows) => rows.find((row) => row.url === props.url)),
+      Effect.catchTag('NotFound', () => Effect.succeed(undefined)),
     ),
   matches: (attributes, props) =>
     attributes.type === props.type &&
@@ -109,10 +128,22 @@ const handlers = forgejoHandlers<RepoWebhookProps, RepoWebhookAttributes>({
     attributes.branchFilter === (props.branchFilter ?? '') &&
     attributes.authorizationHeader === (props.authorizationHeader ?? '') &&
     stringArray(props.events).join('\0') === attributes.events.join('\0'),
-  path: (props) => `repos/${props.owner}/${props.repo}/hooks/${props.name}`,
-  updateForm: updateHookForm,
-  wirePath: (props, live) => `repos/${props.owner}/${props.repo}/hooks/${String(live['id'])}`,
-});
+  update: (props, live) =>
+    repository.repoEditHook({
+      active: props.active ?? true,
+      ...(props.authorizationHeader === undefined
+        ? {}
+        : { authorization_header: props.authorizationHeader }),
+      ...(props.branchFilter === undefined ? {} : { branch_filter: props.branchFilter }),
+      config: hookConfigForm(props, false),
+      events: props.events,
+      id: live.id,
+      owner: props.owner,
+      repo: props.repo,
+    }),
+};
+
+export const handlers = forgejoHandlers(spec);
 
 export const ForgejoRepoWebhookProvider = () =>
   Provider.effect(ForgejoRepoWebhook, Effect.succeed(ForgejoRepoWebhook.Provider.of(handlers)));

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();
+  });
+});