@bevel-software/platform-core-backend 0.4.0 → 0.5.0

package/src/modules/groups/__tests__/join-requests.service.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  DEFAULT_BRANCH,
+  joinBranchFor,
+  type AuthUser,
+  type ChangeRequest,
+  type IWorkflowService,
+} from '@bevel-software/platform-shared';
+import {
+  workspaceIdForBranch,
+  type WorkspaceService,
+} from '../../workspace/workspace.service.js';
+import { JoinRequestsService } from '../join-requests.service.js';
+
+/**
+ * The derived lifecycle: a join request is open exactly while its branch's
+ * `access.md` grants something the default branch's does not, and settling it
+ * is what happens when that stops being true — nothing stores a status.
+ */
+const ALI = 'ali@bevel.software';
+const FOLDER = 'Groups/GTM';
+const ACCESS_MD = `${FOLDER}/access.md`;
+const ACTOR: AuthUser = { id: 'u-1', email: 'olga@bevel.software', name: 'Olga Ivanova' };
+
+const base = (body: string) => `---\nread:\n  - everyone\n---\n${body}`;
+const DEFAULT_MD = base('read:\n  - GTM Team\n');
+const PROPOSING_MD = base('read:\n  - GTM Team\n  - Ali Baba <ali@bevel.software>\n');
+
+function cr(over: Partial<ChangeRequest> = {}): ChangeRequest {
+  return {
+    number: 7,
+    title: 'Join request: GTM',
+    author: { login: 'user-abc' },
+    authorId: 'hash-ali',
+    appAuthor: { name: 'Ali Baba' },
+    branch: joinBranchFor(ALI, 'GTM'),
+    base: DEFAULT_BRANCH,
+    state: 'open',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    touchedNodePaths: [ACCESS_MD],
+    review: { approvals: 0, changesRequested: 0, pendingLogins: [] },
+    url: '/change-requests/7',
+    ...over,
+  } as ChangeRequest;
+}
+
+/** `byRef[ref]` is the access.md content at that ref (undefined ⇒ absent). */
+function makeHarness(byRef: Record<string, string>) {
+  const workspaceService = {
+    ensureRemotesFetched: vi.fn(async () => undefined),
+    readFileAtRef: vi.fn(async (_ws: string, ref: string, path: string) =>
+      path === ACCESS_MD ? (byRef[ref] ?? null) : null,
+    ),
+  } as unknown as WorkspaceService;
+  const workflow = {
+    rejectChangeRequest: vi.fn(async () => ({ number: 7, state: 'closed' })),
+    deleteBranch: vi.fn(async () => undefined),
+  } as unknown as IWorkflowService;
+  return { svc: new JoinRequestsService(workspaceService, workflow), workflow, workspaceService };
+}
+
+const refs = (branchMd: string | undefined, defaultMd = DEFAULT_MD) => ({
+  [`origin/${DEFAULT_BRANCH}`]: defaultMd,
+  ...(branchMd === undefined ? {} : { [`origin/${joinBranchFor(ALI, 'GTM')}`]: branchMd }),
+});
+
+describe('JoinRequestsService.list', () => {
+  it('reports a request with its pending proposals, and leaves it open', async () => {
+    const h = makeHarness(refs(PROPOSING_MD));
+    const out = await h.svc.list('GTM', FOLDER, [cr()], ACTOR);
+    expect(out).toHaveLength(1);
+    expect(out[0]).toMatchObject({ number: 7, requesterName: 'Ali Baba' });
+    expect(out[0].proposals.map((p) => p.label)).toEqual(['Ali Baba']);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('SETTLES a request whose proposals have all landed: closes it, deletes the branch, omits it', async () => {
+    // The grant is on the default branch now, so the branch adds nothing.
+    const h = makeHarness(refs(PROPOSING_MD, PROPOSING_MD));
+    const out = await h.svc.list('GTM', FOLDER, [cr()], ACTOR);
+    expect(out).toEqual([]);
+    expect(h.workflow.rejectChangeRequest).toHaveBeenCalledWith(
+      7,
+      ACTOR,
+      'open',
+      'hash-ali',
+      DEFAULT_BRANCH,
+      // The WORKSPACE id, which merely happens to equal the branch name for
+      // slash-less branches — assert the encoding so a slashed default
+      // branch could never silently break this.
+      workspaceIdForBranch(DEFAULT_BRANCH),
+    );
+    expect(h.workflow.deleteBranch).toHaveBeenCalledWith(
+      workspaceIdForBranch(DEFAULT_BRANCH),
+      joinBranchFor(ALI, 'GTM'),
+      ACTOR,
+    );
+  });
+
+  it('ignores change requests that are closed or not on a join branch', async () => {
+    const h = makeHarness(refs(PROPOSING_MD));
+    const out = await h.svc.list(
+      'GTM',
+      FOLDER,
+      [cr({ state: 'closed' }), cr({ number: 9, branch: 'ali/some-draft' })],
+      ACTOR,
+    );
+    expect(out).toEqual([]);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('keeps listing when closing one request fails', async () => {
+    const h = makeHarness(refs(PROPOSING_MD, PROPOSING_MD));
+    (h.workflow.rejectChangeRequest as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new Error('gh down'),
+    );
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    await expect(h.svc.list('GTM', FOLDER, [cr()], ACTOR)).resolves.toEqual([]);
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('still closes the request when the branch delete fails, and says so', async () => {
+    const h = makeHarness(refs(PROPOSING_MD, PROPOSING_MD));
+    (h.workflow.deleteBranch as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('protected'));
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    // The request still settles (omitted from the list) — the leftover branch
+    // is cosmetic, and the failure is logged rather than swallowed.
+    await expect(h.svc.list('GTM', FOLDER, [cr()], ACTOR)).resolves.toEqual([]);
+    expect(h.workflow.rejectChangeRequest).toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('could not delete'));
+    warn.mockRestore();
+  });
+
+  it('NEVER settles a slug-colliding other group\'s request (branch match is exact)', async () => {
+    // `Finance!` slugs to `finance` too. Its branch's copy of
+    // `Groups/finance/access.md` is unchanged, so if the branch matched, the
+    // empty diff would settle — closing a change request and deleting a
+    // branch that belong to a DIFFERENT group. The group tag in the branch
+    // name is what forbids the match.
+    const other = cr({ branch: joinBranchFor(ALI, 'Finance!') });
+    const h = makeHarness({
+      [`origin/${DEFAULT_BRANCH}`]: DEFAULT_MD,
+      [`origin/${joinBranchFor(ALI, 'Finance!')}`]: DEFAULT_MD,
+    });
+    await expect(h.svc.list('finance', 'Groups/finance', [other], ACTOR)).resolves.toEqual([]);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+    expect(h.workflow.deleteBranch).not.toHaveBeenCalled();
+    await expect(h.svc.reconcile('finance', 'Groups/finance', other, ACTOR)).resolves.toBe(false);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+  });
+});
+
+describe('JoinRequestsService.reconcile', () => {
+  it('settles and reports true once nothing is pending', async () => {
+    const h = makeHarness(refs(PROPOSING_MD, PROPOSING_MD));
+    await expect(h.svc.reconcile('GTM', FOLDER, cr(), ACTOR)).resolves.toBe(true);
+    expect(h.workflow.rejectChangeRequest).toHaveBeenCalled();
+    expect(h.workflow.deleteBranch).toHaveBeenCalled();
+  });
+
+  it('leaves a request alone while proposals remain', async () => {
+    const h = makeHarness(refs(PROPOSING_MD));
+    await expect(h.svc.reconcile('GTM', FOLDER, cr(), ACTOR)).resolves.toBe(false);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+  });
+
+  it('refuses a change request that is not this group\'s join branch', async () => {
+    const h = makeHarness(refs(PROPOSING_MD, PROPOSING_MD));
+    await expect(
+      h.svc.reconcile('GTM', FOLDER, cr({ branch: 'ali/some-draft' }), ACTOR),
+    ).resolves.toBe(false);
+    expect(h.workflow.rejectChangeRequest).not.toHaveBeenCalled();
+  });
+});

package/src/modules/groups/group-provision.service.ts

@@ -0,0 +1,328 @@
+/**
+ * Group provisioning — the ONE privileged door for bringing a `Groups/<name>/`
+ * folder into existence, and (via {@link GroupProvisionService.deleteGroup})
+ * for taking one back out of it.
+ *
+ * Creating a group is the single operation the access model cannot govern
+ * from inside: the folder that will carry the rules does not exist yet, and
+ * the root's own rule (`write: Admin`) says no. The old answer was a
+ * carve-out inside the generic write gate — every write path could claim an
+ * unused name under `Groups/`, and the gate had to re-derive "is this that
+ * one blessed case?" on every check. This service replaces that: the generic
+ * gate is uniformly strict again, and the privilege lives here, named,
+ * behind its own endpoint.
+ *
+ * What a provision IS: one exclusive write of the new folder's `access.md`
+ * (flag `wx`, so two concurrent creators race for the fs, not for the
+ * overwrite), then one SYNCHRONOUS commit+push. Synchronous on purpose — the
+ * write gate reads rules at HEAD, so a creation whose access.md were still
+ * sitting in the async commit queue would 403 the very next thing its
+ * creator does (writing the first skill into it).
+ *
+ * Two shapes, two templates:
+ *
+ *   - A NAMED group: discoverable by design. The access.md's own frontmatter
+ *     reads `everyone` — anyone may open the FILE, see the group listed, and
+ *     ask to join — while the BODY (the folder's actual rules) names only
+ *     the creator under read, write and owner.
+ *   - A PERSONAL folder (`personal-<user-id>`): private by design. No
+ *     frontmatter grant at all, so nobody else can even see it exists; the
+ *     body names its owner. Created lazily (ensure semantics) on the first
+ *     personal skill.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  DEFAULT_BRANCH,
+  GROUPS_DIR,
+  PERSONAL_GROUP_PREFIX,
+  isPersonalGroupFolder,
+  personalGroupFolderName,
+  type AuthUser,
+} from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { IAccessControl } from '../access/access-control.interface.js';
+import { creatorPrincipal } from '../access/creator-access.js';
+import { spliceGrant } from '../access/access-splice.js';
+import { WorkspaceMutex } from '../workflow/git/mutex.js';
+
+/** Commit machinery the provision rides — the pending-commit pipeline, run inline. */
+export interface ProvisionCommitDriver {
+  runPendingCommit(
+    workspaceId: string,
+    branch: string,
+    targetPath: string,
+    user: AuthUser,
+    opts?: { systemAuthorized?: boolean },
+  ): Promise<void>;
+}
+
+export interface ProvisionedGroup {
+  /** The folder name under `Groups/` (not the full path). */
+  folder: string;
+  /** False when an ensure found the folder already there. */
+  created: boolean;
+}
+
+/** A refusal the route can pass through: message + HTTP status. */
+export class GroupProvisionError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = 'GroupProvisionError';
+  }
+}
+
+export class GroupProvisionService {
+  /**
+   * Serialises creations by NORMALIZED (lowercased) folder name. The wx write
+   * arbitrates same-path races, but on a case-sensitive filesystem `GTM` and
+   * `gtm` are different paths — without this lock two concurrent requests
+   * could both pass the collision check and both land, breaking the
+   * case-insensitive uniqueness the check promises.
+   */
+  private readonly creations = new WorkspaceMutex();
+
+  constructor(
+    private readonly workspaceService: WorkspaceService,
+    private readonly commits: ProvisionCommitDriver,
+    private readonly accessControl: IAccessControl,
+    private readonly kbDirName: string,
+    private readonly events?: { emit(event: { kind: 'fs-tree-changed'; workspaceId: string; branch: string }): void },
+  ) {}
+
+  /**
+   * Create `Groups/<name>/` for `user`. Throws `GroupProvisionError` 422 on a
+   * name the filesystem or the model cannot carry, 409 when the name is taken
+   * (case-insensitively — the workspaces live on case-insensitive
+   * filesystems too, where `GTM` and `gtm` are one folder).
+   */
+  async createGroup(user: AuthUser, rawName: string): Promise<ProvisionedGroup> {
+    const name = rawName.trim();
+    if (!name) throw new GroupProvisionError('A group needs a name.', 422);
+    // eslint-disable-next-line no-control-regex -- NUL and control chars are
+    // exactly what a filesystem path cannot carry; refusing them here keeps
+    // the refusal a 422 instead of the fs layer's 500.
+    if (/[/\\\u0000-\u001f\u007f]/.test(name) || name === '.' || name === '..' || name.startsWith('.')) {
+      throw new GroupProvisionError(
+        'A group name can\'t contain / or \\ or control characters, or start with a dot.',
+        422,
+      );
+    }
+    if (name.toLowerCase().startsWith(PERSONAL_GROUP_PREFIX)) {
+      // Reserved: the personal-folder namespace. A group squatting there
+      // would collide with somebody's future personal folder.
+      throw new GroupProvisionError(
+        `Group names starting with "${PERSONAL_GROUP_PREFIX}" are reserved.`,
+        422,
+      );
+    }
+    return this.creations.run(`group:${name.toLowerCase()}`, async () => {
+      const existing = await this.existingFolder(name);
+      if (existing !== null) {
+        throw new GroupProvisionError(`A group named "${existing}" already exists.`, 409);
+      }
+      await this.provision(user, name, groupAccessMd(user));
+      return { folder: name, created: true };
+    });
+  }
+
+  /**
+   * Ensure the caller's personal folder exists — idempotent, keyed to the
+   * stable user id. Returns `created: false` when it is already there.
+   */
+  async ensurePersonalGroup(user: AuthUser): Promise<ProvisionedGroup> {
+    const folder = personalGroupFolderName(user.id);
+    return this.creations.run(`group:${folder.toLowerCase()}`, async () => {
+      if ((await this.existingFolder(folder)) !== null) {
+        return { folder, created: false };
+      }
+      try {
+        await this.provision(user, folder, personalAccessMd(user));
+      } catch (err) {
+        // ENSURE semantics even under a race the lock cannot see (another
+        // process, a checkout that appeared between check and write): the
+        // folder existing is this method's success case, never its error.
+        if (err instanceof GroupProvisionError && err.status === 409) {
+          return { folder, created: false };
+        }
+        throw err;
+      }
+      return { folder, created: true };
+    });
+  }
+
+  /**
+   * Delete `Groups/<name>/` — the whole folder, its skills and tools
+   * included, in ONE commit. MECHANISM only: the route owns the
+   * authorization (the caller must hold the `owner` verb on the folder;
+   * this service never re-derives it), exactly as `createGroup` leaves
+   * "any signed-in user" to its endpoint.
+   *
+   * Shape mirrors a provision run in reverse, with the same failure
+   * contract: the folder is PARKED (renamed to a dot-prefixed sibling the
+   * scanners ignore) rather than removed, the deletion is committed
+   * synchronously, and only a landed commit lets the parked bytes go. A
+   * refused commit renames the folder back, so a failed delete leaves the
+   * group exactly as it was — never half-gone on disk while origin still
+   * carries it.
+   *
+   * Serialised on the same per-name lock creations use, so a delete can
+   * never interleave with a re-creation of the same name.
+   */
+  async deleteGroup(user: AuthUser, rawName: string): Promise<void> {
+    const name = rawName.trim();
+    if (!name) throw new GroupProvisionError('A group needs a name.', 422);
+    if (isPersonalGroupFolder(name)) {
+      // Personal folders are not groups (the catalog never lists them), and
+      // nobody deletes somebody's private shelf through the group door.
+      throw new GroupProvisionError('Unknown group', 404);
+    }
+    return this.creations.run(`group:${name.toLowerCase()}`, async () => {
+      const existing = await this.existingFolder(name);
+      // Exact match only — the catalog hands the route the on-disk casing,
+      // so a mismatch means the group is gone (or was never there).
+      if (existing !== name) throw new GroupProvisionError('Unknown group', 404);
+
+      const wsId = await this.readyWorkspaceId();
+      const wsDir = await this.workspaceService.getWorkspacePath(wsId);
+      const groupsDir = path.join(wsDir, this.kbDirName, GROUPS_DIR);
+      const folderDir = path.join(groupsDir, name);
+      // Dot-prefixed ⇒ invisible to the group scanner and the collision
+      // check for the whole window the commit is in flight.
+      const parkedDir = path.join(groupsDir, `.${name}.deleting`);
+
+      await fs.rm(parkedDir, { recursive: true, force: true }); // a stale park from a crashed run
+      await fs.rename(folderDir, parkedDir);
+      try {
+        // Inline and `systemAuthorized`, for `provision`'s reasons in
+        // reverse: the gate reads rules at HEAD, and the endpoint has
+        // already authorized the delete (owner verdict), so the per-user
+        // push gate — which would re-read an access.md this very commit
+        // removes — is skipped for exactly this commit. `commitFile` is
+        // path-scoped (`git add -- <path>`), and a folder path stages every
+        // deletion under it: one commit, one removed group.
+        await this.commits.runPendingCommit(
+          wsId,
+          DEFAULT_BRANCH,
+          `${this.kbDirName}/${GROUPS_DIR}/${name}`,
+          user,
+          { systemAuthorized: true },
+        );
+      } catch (err) {
+        // The commit did not land: put the folder back, so a failed delete
+        // is a no-op rather than a group that exists at origin but not here.
+        try {
+          await fs.rename(parkedDir, folderDir);
+        } catch {
+          /* the park survives for the next attempt — better than masking the real error */
+        }
+        throw err;
+      }
+      await fs.rm(parkedDir, { recursive: true, force: true }).catch(() => {});
+      // The folder's rules left the access model — drop the resolver cache
+      // so the very next check runs against a tree without them.
+      this.accessControl.invalidate(wsId);
+      this.events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch: DEFAULT_BRANCH });
+    });
+  }
+
+  /** The taken name (in its on-disk casing) colliding with `name`, or null. */
+  private async existingFolder(name: string): Promise<string | null> {
+    const wsId = await this.readyWorkspaceId();
+    const wsDir = await this.workspaceService.getWorkspacePath(wsId);
+    let children: string[];
+    try {
+      children = await fs.readdir(path.join(wsDir, this.kbDirName, GROUPS_DIR));
+    } catch {
+      return null; // no Groups/ root yet — nothing can collide
+    }
+    const lower = name.toLowerCase();
+    return children.find((c) => c.toLowerCase() === lower) ?? null;
+  }
+
+  private async provision(user: AuthUser, folder: string, accessMd: string): Promise<void> {
+    const wsId = await this.readyWorkspaceId();
+    const wsRelPath = `${this.kbDirName}/${GROUPS_DIR}/${folder}/access.md`;
+    try {
+      // Exclusive create — the fs is the arbiter of a same-name race, not
+      // the (stale-able) existence check above.
+      await this.workspaceService.writeFile(wsId, wsRelPath, accessMd, { failIfExists: true });
+    } catch (err) {
+      if ((err as { status?: number }).status === 409) {
+        throw new GroupProvisionError(`A group named "${folder}" already exists.`, 409);
+      }
+      throw err;
+    }
+    try {
+      // Inline, not enqueued: the gate reads rules at HEAD, so the folder is
+      // only real once this commit lands. `runPendingCommit` is the same
+      // commit+push (with pull-rebase recovery) the queue worker runs.
+      // `systemAuthorized`: the push gate reads access at origin, where this
+      // folder does not exist yet and the root says `write: Admin` — the very
+      // rule this endpoint exists to carve through. The endpoint has already
+      // authorized the write (any signed-in user, unused name, exclusive
+      // create), so the per-user gate is skipped for exactly this commit.
+      await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, wsRelPath, user, {
+        systemAuthorized: true,
+      });
+    } catch (err) {
+      // The commit did not land: roll the seeded file back off the disk,
+      // best-effort, so a retry doesn't find a half-made group and report
+      // "already exists" for something that never got committed. Only OUR
+      // file and — when that leaves it empty — the folder; never recursive,
+      // so a concurrent writer's bytes can't be collateral.
+      try {
+        const wsDir = await this.workspaceService.getWorkspacePath(wsId);
+        const folderDir = path.join(wsDir, this.kbDirName, GROUPS_DIR, folder);
+        await fs.rm(path.join(folderDir, 'access.md'), { force: true });
+        await fs.rmdir(folderDir).catch(() => {});
+      } catch {
+        /* leave it for the next attempt's wx conflict — better than masking the real error */
+      }
+      throw err;
+    }
+    // The folder's rules changed the access model — drop the resolver cache
+    // so the very next check (the creator's first skill write) sees them.
+    this.accessControl.invalidate(wsId);
+    this.events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch: DEFAULT_BRANCH });
+  }
+
+  private async readyWorkspaceId(): Promise<string> {
+    const ws = await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
+    return ws.id;
+  }
+}
+
+/**
+ * A named group's access.md: discoverable file (frontmatter `read: everyone`
+ * — anyone may see the group listed and ask to join), creator-run folder
+ * (body read/write/owner name the creator). The `read: []` placeholder makes
+ * the body parse as rules from the first byte, so every later splice targets
+ * the body rather than the frontmatter.
+ */
+export function groupAccessMd(creator: { name: string; email: string }): string {
+  return withCreatorGrants('---\nread:\n  - everyone\n---\nread: []\n', creator);
+}
+
+/**
+ * A personal folder's access.md: PRIVATE — no frontmatter grant, so the
+ * folder is invisible to everyone but its owner; the body names the owner
+ * under read, write and owner.
+ */
+export function personalAccessMd(creator: { name: string; email: string }): string {
+  return withCreatorGrants('read: []\n', creator);
+}
+
+function withCreatorGrants(base: string, creator: { name: string; email: string }): string {
+  const principal = creatorPrincipal(creator);
+  let out = base;
+  for (const verb of ['read', 'write', 'owner'] as const) {
+    out = spliceGrant(out, verb, principal, { allowScalar: false, target: 'folder' }).text;
+  }
+  return out;
+}

package/src/modules/groups/groups.contract.ts

@@ -0,0 +1,107 @@
+/**
+ * Groups — the folders under `Groups/` that carry a team's skills and the
+ * tools those skills need. A group is a FOLDER, never a role: one access
+ * boundary, one place, derived from the path exactly the way `groupOfPath`
+ * derives it.
+ *
+ * A group EXISTS exactly when its folder carries an `access.md` — the file
+ * the provisioning endpoint seeds. A bare directory under `Groups/` is not a
+ * group (git cannot record an empty folder, so deleted groups leave ghost
+ * directories on live checkouts).
+ *
+ * Enumeration then follows the KB's read model with NO special cases: an
+ * existing group appears for a caller exactly when the access resolution says
+ * something about it —
+ *
+ *   - MEMBER: the caller can read the folder itself (`canRead`).
+ *   - MANAGER: the caller can write the folder's `access.md` (`canWrite`,
+ *     admin-rescued).
+ *   - DISCOVERABLE: the caller can read the `access.md` FILE — which, in the
+ *     new body-governed format, is granted by the file's own
+ *     `read: everyone` frontmatter (see `accessMdSelfEntries`). The group
+ *     shows locked, and the caller may ask to join.
+ *
+ * A group where all three verdicts are false is ABSENT from the response —
+ * name, counts and principals never leave the backend. Making a group secret
+ * is therefore an ordinary access edit: drop the `everyone` grant from its
+ * access.md frontmatter.
+ *
+ * Requesting access is a CHANGE REQUEST, not a bespoke system: the join
+ * route commits "add me to the body's `read:` list" on a draft branch and
+ * opens a CR that the folder's writers approve by merging (or by granting
+ * via Manage access, which makes the CR moot). To agents these are plain
+ * change requests; only the UI dresses them up.
+ */
+
+/** Access-rule principals as the resolver hands them back. */
+export interface ResolvedPrincipals {
+  roles: string[];
+  users: { name: string; email: string }[];
+}
+
+export interface ResolvedReaders extends ResolvedPrincipals {
+  restricted: boolean;
+}
+
+/** One group as `GET /api/groups` reports it, resolved for ONE caller. */
+export interface GroupSummary {
+  /** Group folder name, e.g. `GTM`. */
+  name: string;
+  /** Repo-relative constituent folders, e.g. `['Groups/GTM']`. */
+  folders: string[];
+  /**
+   * Per-caller: the caller can read the FOLDER (membership). Every returned
+   * group has at least one of `canRead` / `canWrite` / discoverability; a
+   * group with none is not returned at all.
+   */
+  canRead: boolean;
+  /**
+   * Per-caller; true ⇒ may manage access. Resolved as write on the folder's
+   * `access.md`, which admin-rescues — so a platform Admin locked OUT of
+   * reading still sees the group and gets the self-service way back in.
+   */
+  canWrite: boolean;
+  /**
+   * Per-caller: the caller holds the `owner` verb on the FOLDER — resolved
+   * from the `owner:` lists alone, no admin rescue. Deleting the group is the
+   * owner's verb (the DELETE route enforces the same verdict); managers who
+   * merely write the access.md do not get it.
+   */
+  isOwner: boolean;
+  /** Caller-INDEPENDENT total (the group's whole content, not the caller's slice). */
+  skillCount: number;
+  toolCount: number;
+  /** For display: "Run by …" (fallback chain: owners → writers → 'the workspace admins'). */
+  owners: ResolvedPrincipals;
+  writers: ResolvedPrincipals;
+  readers: ResolvedReaders;
+  /**
+   * The caller has an OPEN join change request for this group (their
+   * deterministic join branch has an open CR). Always false for a member.
+   */
+  hasRequested: boolean;
+  /** The open join CR's number when `hasRequested` (deep-links the UI). */
+  requestNumber: number | null;
+}
+
+/**
+ * The caller-INDEPENDENT slice of a group — what `catalog()` computes once and
+ * caches. The per-caller verdicts (`canRead`/`canWrite`, and whether the group
+ * appears at all) are resolved per request in the route.
+ */
+export interface GroupCatalogEntry {
+  name: string;
+  folders: string[];
+  skillCount: number;
+  toolCount: number;
+  owners: ResolvedPrincipals;
+  writers: ResolvedPrincipals;
+  readers: ResolvedReaders;
+}
+
+export interface IGroupIndexService {
+  /** Caller-independent catalog part (folders, counts, principals) — cached 60s. */
+  catalog(): Promise<GroupCatalogEntry[]>;
+  /** Drop the cached catalog (call after a default-branch change under a group root). */
+  invalidate(): void;
+}