@startsimpli/integrations 0.2.33 → 0.2.35

package/src/corpus/client.ts

@@ -32,6 +32,7 @@
  */
 import {
   DEFAULT_PARTICIPANT_EDGES,
+  FOLDER_ROOT,
   DEFAULT_RUN_KEY,
   DEFAULT_TYPE_KEYS,
   MAX_ID_LIST,
@@ -40,11 +41,14 @@ import {
   indexParticipants,
   toCommitment,
   toExtractionRun,
+  toFolder,
   toMoneyEvent,
   toParty,
   toSourceDocument,
 } from './entities';
-import type { CorpusTypeKeys, TenantEntity, TenantRelationship } from './entities';
+import type {
+  CorpusTypeKeys, TenantEntity, TenantFacetRow, TenantRelationship,
+} from './entities';
 import {
   FOCUS_TYPE,
   IN_FOCUS,
@@ -58,9 +62,11 @@ import type {
   CommitmentApi,
   CommitmentQuery,
   CorpusApi,
+  CorpusFolder,
   CorpusPage,
   CorpusScope,
   DocumentQuery,
+  FolderQuery,
   ExtractionRun,
   ExtractionRunStore,
   AuthoredItem,
@@ -214,6 +220,17 @@ interface ServerFilterReport {
  */
 const TEXT_FILTER_MAX = 500;
 
+/**
+ * The attribute the folder tree is DERIVED from (start-simpli-api#369 ships it
+ * as a source-agnostic container: `/Contracts`, never `/Contracts/SOW.pdf`).
+ *
+ * One name, in one place, because the facet read enumerates it and the document
+ * filter narrows on it — and a tree whose nodes came from one attribute while
+ * its file lists filtered on another would draw folders that open onto nothing.
+ */
+const PATH_ATTRIBUTE = 'path';
+
+
 function commitmentParams(query: CommitmentQuery, type: string): Record<string, unknown> {
   const statuses = Array.isArray(query.status) ? query.status : query.status ? [query.status] : [];
   const out: Record<string, unknown> = {
@@ -270,6 +287,8 @@ const DOCUMENT_FILTER_PARAMS: Array<[keyof DocumentQuery, string[]]> = [
   ['partyId', ['party', 'related_to']],
   ['occurredAfter', ['occurred_after', 'attr.occurred_at__gte']],
   ['occurredBefore', ['occurred_before', 'attr.occurred_at__lte']],
+  ['folder', ['attr.path']],
+  ['underFolder', ['attr.path__under']],
 ];
 
 function reportedDocumentFilters(query: DocumentQuery, applied: string[]): string[] {
@@ -351,6 +370,39 @@ function params(query: DocumentQuery, type: string) {
   if (query.partyId) out.party = query.partyId;
   if (query.occurredAfter) out.occurred_after = query.occurredAfter;
   if (query.occurredBefore) out.occurred_before = query.occurredBefore;
+  // THE FOLDER BOUNDS, and only ever one of them. `attr.path` is the shelf and
+  // `attr.path__under` is the subtree; sending both would AND an exact match
+  // with its own subtree and answer with the shelf, which is the exact-match
+  // query wearing a second parameter. The composer chooses; this just refuses to
+  // send a contradiction.
+  if (query.underFolder) out['attr.path__under'] = query.underFolder;
+  else if (query.folder) out['attr.path'] = query.folder;
+  return out;
+}
+
+/**
+ * `GET /api/v1/entities/facets/` — its OWN parameter builder, and that is not
+ * tidiness (bd startsim-ei8gm.5).
+ *
+ * THE FACET ACTION REFUSES UNKNOWN PARAMETERS. `_Scoped.initial()` screens it
+ * against `_FACET_FILTERS` before any handler runs — the tenant added
+ * `extra_list_parameters` precisely so a new list-shaped route could not inherit
+ * the old fail-open posture — so handing it `params(query, type)` would 400 the
+ * whole read on `occurred_after`, `party` or `source` the moment a filter was
+ * set. Its vocabulary is the entity filters PLUS `attr` and `under`, and this
+ * sends exactly `type`, `attr`, `under` and the page.
+ */
+function facetParams(query: FolderQuery, type: string) {
+  const out: Record<string, unknown> = {
+    type,
+    attr: PATH_ATTRIBUTE,
+    // The FULL path the server handed back, verbatim. `/` is the root and means
+    // the whole corpus — `subtree_bound()` makes the root's descendant prefix
+    // `/`, which every stored path begins with.
+    under: query.under || FOLDER_ROOT,
+    page: query.page ?? 1,
+  };
+  if (query.pageSize) out.page_size = query.pageSize;
   return out;
 }
 
@@ -359,9 +411,9 @@ function appliedFilters(
   query: DocumentQuery,
   supported: Array<string>,
 ): string[] {
-  const requested = (['search', 'source', 'partyId', 'occurredAfter', 'occurredBefore'] as const).filter(
-    (key) => Boolean(query[key]),
-  );
+  const requested = ([
+    'search', 'source', 'partyId', 'occurredAfter', 'occurredBefore', 'folder', 'underFolder',
+  ] as const).filter((key) => Boolean(query[key]));
   return requested.filter((key) => supported.includes(key));
 }
 
@@ -683,6 +735,38 @@ export function createCorpusApi(
       return page<Party>(types.party, query, (entity) => toParty(entity, scope));
     },
 
+    /**
+     * ONE LEVEL of the folder tree (bd startsim-ei8gm.5).
+     *
+     * `GET /api/v1/entities/facets/?type=source_document&attr=path&under=/Contracts`
+     * -> the CHILD FOLDERS of `/Contracts`, paginated, each row already carrying
+     * its descendant count and whether anything sits below it.
+     *
+     * THE GATE IS THE SERVER'S AND IT STAYS THERE. The tenant answers this out
+     * of `EntityViewSet.get_queryset()` itself — the same type gate, row gate,
+     * field gate and filters the row read composes — so the folders a member is
+     * shown are the folders their own documents are in, and nothing else. On a
+     * tenant whose `source_document` is `row_scope: personal` that is the whole
+     * of the protection: a folder name leaks plenty on its own
+     * (`/Legal/Terminations`, `/Acquisition-TargetCo`). Which is why this method
+     * asks for ONE `under=` and returns exactly what came back for it. It does
+     * not cache across containers, does not merge two responses, and does not
+     * infer a parent from a child's path — any of which would rebuild the leak
+     * client-side out of rows the server was careful about.
+     */
+    async listFolders(query: FolderQuery): Promise<CorpusPage<CorpusFolder>> {
+      const response = await http.get<DrfPage<TenantFacetRow> & ServerFilterReport>(
+        `${entities}/facets`,
+        { params: facetParams(query, types.document) },
+      );
+      return {
+        count: response.count ?? response.results?.length ?? 0,
+        next: response.next ?? null,
+        previous: response.previous ?? null,
+        results: (response.results ?? []).map(toFolder),
+      };
+    },
+
     async listMoneyEvents(query = {}) {
       const events = await page<TenantEntity>(types.moneyEvent, query, (entity) => entity);
       const byRecord = await participantsFor(events.results.map((entity) => entity.id));
@@ -940,6 +1024,11 @@ export function createCorpusApi(
           Number(connection.consecutive_failures ?? connection.consecutiveFailures ?? 0) || 0;
         const documentCount = counts.get(key) ?? null;
         const error = String(connection.check_error ?? connection.checkError ?? '');
+        // WHY THE LAST POLL FAILED — not why the credential did (bd
+        // startsim-ei8gm.2). Both spellings for the same reason the three
+        // timestamps above read both: `@startsimpli/api` camelCases response
+        // keys in the browser and a plain server-side fetch does not.
+        const lastError = String(connection.last_error ?? connection.lastError ?? '');
         const status = connection.status ?? '';
 
         let health: SourceFreshness['status'] = 'ok';
@@ -947,7 +1036,7 @@ export function createCorpusApi(
         if (error || status === 'error' || status === 'needs_reauth') {
           health = 'error';
           detail = error || `Connection status is ${String(status)}.`;
-        } else if (failures > 0 || (lastAttemptAt && !lastSyncedAt)) {
+        } else if (failures > 0 || lastError || (lastAttemptAt && !lastSyncedAt)) {
           // IT TRIED AND IT FAILED. Central's view exists partly so that "a card
           // cannot read 'nothing yet' while it is in fact failing on a
           // schedule" — a run that FINISHED while nothing has ever finished well
@@ -955,12 +1044,33 @@ export function createCorpusApi(
           // when an older sync did land. Note what does NOT appear in this
           // condition: `lastCheckedAt`. A verified key is not a delivered
           // record, in either direction.
+          //
+          // `lastError` JOINS THAT CONDITION, because the two facts have
+          // different writers: `consecutive_failures` is a counter on the
+          // CONNECTION and the reason is derived from the newest RUN. Central
+          // sends a reason only while that newest run is the failed one, so a
+          // reason with a zero streak behind it is still a source whose last
+          // sync failed — and turning only on the counter reported that as
+          // `stale`, which reads as "nothing to do yet".
           health = 'error';
-          detail =
+          // THE COUNT SURVIVES; IT IS NO LONGER THE WHOLE SENTENCE. "One blip"
+          // and "sixteen days" are different problems, so the streak stays —
+          // what was missing was the half a reader can act on. Composed here
+          // rather than server-side because the streak is a connection field
+          // and the reason is a run field, and central sends them separately
+          // on purpose (bd startsim-1cow: conflating two facts is how a
+          // freshness strip lies).
+          const streak =
             failures > 0
-              ? `${failures} sync${failures === 1 ? '' : 's'} in a row failed` +
-                `${lastSyncedAt ? '' : ' and nothing has arrived yet'}.`
-              : 'A sync ran but nothing arrived.';
+              ? `${failures} sync${failures === 1 ? '' : 's'} in a row failed`
+              : lastError
+                ? 'The last sync failed'
+                : 'A sync ran but nothing arrived';
+          const nothingYet =
+            failures > 0 && !lastSyncedAt ? ' and nothing has arrived yet' : '';
+          // An em dash, not a colon: the server's reason usually contains its
+          // own colons ("[config_error] ...") and a second one reads as a typo.
+          detail = lastError ? `${streak}${nothingYet} — ${lastError}` : `${streak}${nothingYet}.`;
         } else if (!lastSyncedAt) {
           // `never` regardless of `lastCheckedAt`, which is the whole bead.
           health = 'never';
@@ -982,6 +1092,10 @@ export function createCorpusApi(
           consecutiveFailures: failures,
           status: health,
           ...(detail ? { detail } : {}),
+          // Carried separately as well as folded into `detail`, so a surface
+          // that wants the reason on its own — a tooltip, a copy button, the
+          // control plane's card — does not have to unpick a composed sentence.
+          ...(lastError ? { lastError } : {}),
         };
       });
     },

package/src/corpus/entities.ts

@@ -25,6 +25,7 @@
 import type {
   Commitment,
   CommitmentMention,
+  CorpusFolder,
   CorpusScope,
   DocumentSection,
   MoneyEvent,
@@ -556,6 +557,14 @@ export function toSourceDocument(
     ),
     scope: scopeOf(entity, fallbackScope),
     ingestedAt: asIso(entity.created_at ?? entity.createdAt),
+    // WHERE IT LIVES. `path` is the source-agnostic CONTAINER attribute
+    // (start-simpli-api#369) — the folder, not the file — and it is the same
+    // attribute the folder tree enumerates, so a row's badge and the tree node
+    // it belongs under can never disagree. `folder`/`container` are alternate
+    // storage spellings, not vendor knowledge.
+    ...(asText(pick(data, 'path', 'folder', 'container')).trim()
+      ? { folder: asText(pick(data, 'path', 'folder', 'container')).trim() }
+      : {}),
     ...(withheldFieldsOf(entity).length
       ? { withheldFields: withheldFieldsOf(entity) }
       : {}),
@@ -863,3 +872,69 @@ export function toExtractionRun(entity: TenantEntity): import('./types').Extract
     return null;
   }
 }
+
+// ---------------------------------------------------------------------------
+//  folders (bd startsim-ei8gm.5)
+// ---------------------------------------------------------------------------
+
+/**
+ * One row of `GET /api/v1/entities/facets/?attr=path&under=…`, as the tenant
+ * really spells it.
+ */
+export interface TenantFacetRow {
+  value?: unknown;
+  count?: unknown;
+  /** The wire spelling. */
+  has_children?: unknown;
+  /**
+   * …and the spelling the BROWSER sees. `@startsimpli/api`'s fetch wrapper
+   * converts every response key from snake_case to camelCase, so this key
+   * arrives as `hasChildren` in the app and as `has_children` from a plain
+   * server-side fetch. Reading only one is not a nicety: it is the bug that made
+   * the Tracker report "this workspace's data API does not filter by status"
+   * while the server verifiably was, and here it would render every folder in
+   * the corpus as a childless leaf with no disclosure triangle — a tree that
+   * silently stops at depth one. The tolerance belongs at the seam.
+   */
+  hasChildren?: unknown;
+}
+
+/**
+ * The top of the tree, and the one spelling of it.
+ *
+ * `/`, never `''`: the tenant's `normalize_container()` says outright that a
+ * connector writes `"/"` for a top-level entry and that `""` is the spelling of
+ * "we do not know where this is". As `under=` it means the WHOLE corpus, because
+ * `subtree_bound()` makes the root's descendant prefix `/`, which every stored
+ * path begins with.
+ */
+export const FOLDER_ROOT = '/';
+
+/**
+ * The last segment of a path, for DISPLAY only.
+ *
+ * The full path is what gets sent back — see `CorpusFolder.path`. This exists so
+ * a node reads `2026` rather than `/Contracts/2026`, and it is deliberately the
+ * only place in the client that takes a path apart.
+ */
+export function folderName(path: string): string {
+  const trimmed = String(path ?? '').replace(/\/+$/, '');
+  const cut = trimmed.lastIndexOf('/');
+  return (cut >= 0 ? trimmed.slice(cut + 1) : trimmed) || '/';
+}
+
+/** A facet row -> a tree node. */
+export function toFolder(row: TenantFacetRow): CorpusFolder {
+  const path = asText(row?.value);
+  const count = Number(row?.count);
+  // `has_children` is ABSENT on the flat (no `under=`) read, and absent must
+  // read as "no", not as "unknown": a node drawn with a triangle it cannot
+  // expand is worse than one drawn without.
+  const deeper = row?.has_children ?? row?.hasChildren;
+  return {
+    path,
+    name: folderName(path),
+    count: Number.isFinite(count) ? count : 0,
+    hasChildren: deeper === true || deeper === 'true' || deeper === 1,
+  };
+}

package/src/corpus/fixtures.ts

@@ -275,6 +275,10 @@ export const FIXTURE_TENANT_DOCUMENTS: TenantEntity[] = [
       occurred_at: '2026-02-01T00:00:00Z',
       url: 'https://www.dropbox.example/scl/fi/9812f0a4b1/acme-msa-signed.pdf',
       participant_count: 2,
+      // THE CONTAINER, not the file (start-simpli-api#369). A Dropbox file
+      // carries its parent's PATH and never its parent's id, which is why the
+      // tree is derived from this attribute rather than from folder rows.
+      path: '/Contracts/Acme',
       extracted_text: [
         'MASTER SERVICES AGREEMENT',
         '1. Term. This Agreement begins on 1 February 2026 and continues for twelve (12) months.',
@@ -296,10 +300,111 @@ export const FIXTURE_TENANT_DOCUMENTS: TenantEntity[] = [
       occurred_at: '2026-01-05T00:00:00Z',
       url: 'https://docs.google.example/document/d/1QpZv7t9kR',
       participant_count: 1,
+      path: '/Pricing',
       extracted_text:
         'Platform: USD 4,000/mo (40 seats). Overage: USD 90/seat/mo. Discounts require VP approval above 15%.',
     },
   }),
+  // ---- A DRIVE WITH DEPTH, AND WITH THINGS NOBODY READS ----
+  //
+  // The corpus a file source really produces (bd startsim-h6xnu): folders
+  // several levels deep, and a large share of the rows recovered from old decks
+  // — fonts, licence files, binaries. They are NOT filtered out, here or on the
+  // screen: an extension denylist is wrong the first time somebody's actual work
+  // is a .ttf, and categorising by folder makes it unnecessary (bd
+  // startsim-nbhno). What they are is TEXTLESS, which is what the row's own
+  // control has to be honest about.
+  row({
+    type: 'source_document', id: 'dbx_c19a', source: 'dropbox', vendorId: 'id:c19a77',
+    name: 'Statement of work — phase 2.pdf',
+    ownerSub: OWNER_A, createdAt: '2026-02-04T06:00:00Z',
+    data: {
+      subtype: 'file',
+      title: 'Statement of work — phase 2.pdf',
+      summary: 'Phase 2 scope: migration, two integrations, eight weeks.',
+      occurred_at: '2026-02-03T00:00:00Z',
+      path: '/Contracts/Acme/2026',
+      participant_count: 0,
+    },
+  }),
+  row({
+    type: 'source_document', id: 'dbx_44b0', source: 'dropbox', vendorId: 'id:44b0e2',
+    name: 'NDA (countersigned).pdf',
+    ownerSub: OWNER_A, createdAt: '2026-01-14T06:00:00Z',
+    data: {
+      subtype: 'file',
+      title: 'NDA (countersigned).pdf',
+      summary: 'Mutual NDA, two-year term.',
+      occurred_at: '2026-01-13T00:00:00Z',
+      path: '/Contracts',
+      participant_count: 0,
+    },
+  }),
+  row({
+    // A FILE WITH NO TEXT AT ALL — the case the row's "Get text" control exists
+    // for, and the one the screen used to answer with a sentence.
+    type: 'source_document', id: 'dbx_ttf1', source: 'dropbox', vendorId: 'id:ttf001',
+    name: 'Poppins-BoldItalic.ttf',
+    ownerSub: OWNER_A, createdAt: '2026-01-02T06:00:00Z',
+    data: {
+      subtype: 'file',
+      title: 'Poppins-BoldItalic.ttf',
+      path: '/Decks/2022 pitch/fonts',
+      participant_count: 0,
+    },
+  }),
+  row({
+    type: 'source_document', id: 'dbx_ttf2', source: 'dropbox', vendorId: 'id:ttf002',
+    name: 'Helvetica75.TTF',
+    ownerSub: OWNER_A, createdAt: '2026-01-02T06:01:00Z',
+    data: {
+      subtype: 'file',
+      title: 'Helvetica75.TTF',
+      path: '/Decks/2022 pitch/fonts',
+      participant_count: 0,
+    },
+  }),
+  row({
+    type: 'source_document', id: 'dbx_deck1', source: 'dropbox', vendorId: 'id:deck01',
+    name: 'Lilo Deck V4.key',
+    ownerSub: OWNER_A, createdAt: '2026-01-03T06:00:00Z',
+    data: {
+      subtype: 'file',
+      title: 'Lilo Deck V4.key',
+      path: '/Decks/2022 pitch',
+      participant_count: 0,
+    },
+  }),
+  row({
+    // THE SAME FILENAME IN A DIFFERENT FOLDER — bd startsim-maios's own example
+    // of why a flat list cannot be read: "'Lilo Deck V4.key' is five rows and a
+    // reader cannot tell them apart". The folder is what tells them apart.
+    type: 'source_document', id: 'dbx_deck2', source: 'dropbox', vendorId: 'id:deck02',
+    name: 'Lilo Deck V4.key',
+    ownerSub: OWNER_A, createdAt: '2026-01-04T06:00:00Z',
+    data: {
+      subtype: 'file',
+      title: 'Lilo Deck V4.key',
+      path: '/Decks/2023 pitch',
+      participant_count: 0,
+    },
+  }),
+  row({
+    // A SIBLING WHOSE NAME IS A PREFIX OF ANOTHER FOLDER'S. `/Contracts-old`
+    // must never appear under `/Contracts`, which is the whole reason `__under`
+    // is one parameter rather than a `startswith` a client assembled.
+    type: 'source_document', id: 'dbx_old1', source: 'dropbox', vendorId: 'id:old001',
+    name: 'Superseded MSA 2024.pdf',
+    ownerSub: OWNER_A, createdAt: '2025-06-01T06:00:00Z',
+    data: {
+      subtype: 'file',
+      title: 'Superseded MSA 2024.pdf',
+      summary: 'Prior MSA, superseded February 2026.',
+      occurred_at: '2024-06-01T00:00:00Z',
+      path: '/Contracts-old',
+      participant_count: 0,
+    },
+  }),
   row({
     // ---- A DIFFERENT CUSTOMER WORKSPACE ----
     // Deliberately the BEST answer to "what did we agree with Acme on renewal":
@@ -896,6 +1001,137 @@ export function createFixtureCorpusApi(options: FixtureCorpusOptions = {}): Corp
  * Every request is recorded, so "did the browser filter it" and "how many round
  * trips did one screen cost" are both assertable.
  */
+/**
+ * `normalize_container()` from the tenant's `apps/api/filters.py`, to the letter.
+ *
+ * `/Contracts/` and `/Contracts` are the same folder — a client that built the
+ * prefix by joining segments sends the first — and THE ROOT KEEPS ITS SLASH,
+ * because `""` is the spelling of "we do not know where this is" and stripping
+ * `/` down to it would answer with the wrong thing rather than nothing.
+ */
+function normalizeContainer(raw: unknown): string {
+  const text = String(raw ?? '').trim();
+  if (!text) return '/';
+  const trimmed = text.replace(/\/+$/, '');
+  return trimmed || '/';
+}
+
+/**
+ * `subtree_bound()`: `/Contracts` -> `['/Contracts', '/Contracts/']`.
+ *
+ * The pair, not a prefix, and the fixture copies it exactly because the whole
+ * point of the parameter is that neither half alone is right:
+ * `startsWith('/Contracts')` also matches the sibling `/Contracts-old`, and
+ * `startsWith('/Contracts/')` misses the documents sitting directly in
+ * `/Contracts`. The root is the case naive code gets wrong — its descendant
+ * prefix is `/`, which every stored path begins with, so `under=/` means
+ * EVERYTHING rather than the handful of top-level files.
+ */
+function subtreeBound(raw: unknown): [string, string] {
+  const prefix = normalizeContainer(raw);
+  return prefix.endsWith('/') ? [prefix, prefix] : [prefix, `${prefix}/`];
+}
+
+/** The container attribute as the delivery writes it. */
+function pathOf(entity: TenantEntity): string {
+  const value = (entity.data as Record<string, unknown> | undefined)?.path;
+  return typeof value === 'string' ? value : '';
+}
+
+/**
+ * `GET /api/v1/entities/facets/`, as the tenant really answers it.
+ *
+ * FAITHFUL TO THE PARTS A CLIENT CAN GET WRONG, which is the only reason a
+ * fixture is worth having:
+ *
+ *  - UNKNOWN PARAMETERS ARE REFUSED, not ignored. `_Scoped.initial()` screens
+ *    this action against `_FACET_FILTERS` before any handler runs. A fixture
+ *    that tolerated `occurred_after` here would let a client ship a facet call
+ *    built from the document query and 400 in production the first time somebody
+ *    set a date filter.
+ *  - `value` IS THE FULL CHILD PATH, so it goes straight back into the next
+ *    `under=`. Returning a bare segment would make every client re-join paths.
+ *  - `count` IS DESCENDANTS, not direct children.
+ *  - A DOCUMENT SITTING DIRECTLY IN THE FOLDER IS NOT A CHILD NODE. Its derived
+ *    value is the prefix itself and the server excludes it — a file is not a
+ *    folder with an empty name.
+ */
+function facetRead(rows: TenantEntity[], params: Record<string, unknown>) {
+  // `_FACET_FILTERS` = the entity vocabulary + `attr` + `under`, plus the
+  // `attr.` prefix and DRF's own reserved words.
+  const vocabulary = new Set([
+    'type', 'id', 'id__in', 'external_id', 'external_id__in', 'search', 'source',
+    'party', 'occurred_after', 'occurred_before', 'related_to', 'related_via',
+    'related_direction', 'related_depth', 'order', 'attr', 'under',
+    'page', 'page_size', 'format',
+  ]);
+  for (const key of Object.keys(params)) {
+    if (vocabulary.has(key) || key.startsWith('attr.')) continue;
+    throw Object.assign(new Error(`unknown parameter '${key}'`), { status: 400 });
+  }
+  const attribute = String(params.attr ?? '').trim();
+  if (!attribute) {
+    throw Object.assign(
+      new Error('attr: name the attribute to enumerate, e.g. ?attr=path'),
+      { status: 400 },
+    );
+  }
+  const type = params.type ? String(params.type) : '';
+  const scoped = (type ? rows.filter((entity) => entity.entity_type === type) : rows)
+    .filter((entity) => {
+      const value = (entity.data as Record<string, unknown> | undefined)?.[attribute];
+      return typeof value === 'string' && value !== '';
+    });
+
+  if (params.under === undefined) {
+    const flat = new Map<string, number>();
+    for (const entity of scoped) {
+      const value = String((entity.data as Record<string, unknown>)[attribute]);
+      flat.set(value, (flat.get(value) ?? 0) + 1);
+    }
+    const results = [...flat]
+      .map(([value, count]) => ({ value, count }))
+      .sort((a, b) => a.value.localeCompare(b.value));
+    return { ...slicePage(results, params), applied_filters: ['attr'] };
+  }
+
+  const [self, descendants] = subtreeBound(params.under);
+  const groups = new Map<string, { count: number; deeper: boolean }>();
+  for (const entity of scoped) {
+    const value = String((entity.data as Record<string, unknown>)[attribute]);
+    if (value !== self && !value.startsWith(descendants)) continue;
+    const rest = value.slice(descendants.length);
+    const cut = rest.indexOf('/');
+    const child = `${descendants}${cut < 0 ? rest : rest.slice(0, cut)}`;
+    // The DIRECT FILE BUCKET. A document sitting in the named folder leaves
+    // nothing after the prefix, so its derived value is the prefix — it is a
+    // file, not a child folder with no name, and it is not a node.
+    if (child === descendants) continue;
+    const at = groups.get(child) ?? { count: 0, deeper: false };
+    at.count += 1;
+    at.deeper = at.deeper || cut >= 0;
+    groups.set(child, at);
+  }
+  const results = [...groups]
+    .map(([value, at]) => ({ value, count: at.count, has_children: at.deeper }))
+    .sort((a, b) => a.value.localeCompare(b.value));
+  return { ...slicePage(results, params), applied_filters: ['attr', 'under'] };
+}
+
+/** The same DRF envelope `slice()` builds, outside the closure that owns it. */
+function slicePage<T>(rows: T[], params: Record<string, unknown>) {
+  const page = Number(params.page ?? 1) || 1;
+  const asked = Number(params.page_size);
+  const size = Number.isFinite(asked) && asked > 0 ? Math.min(asked, MAX_ID_LIST) : 50;
+  const start = (page - 1) * size;
+  return {
+    count: rows.length,
+    next: start + size < rows.length ? `?page=${page + 1}` : null,
+    previous: page > 1 ? `?page=${page - 1}` : null,
+    results: rows.slice(start, start + size),
+  };
+}
+
 export function createFixtureCorpusHttp(options: {
   entities?: TenantEntity[];
   relationships?: TenantRelationship[];
@@ -1020,6 +1256,11 @@ export function createFixtureCorpusHttp(options: {
           ignored_filters: query.ignored.slice().sort(),
         } as T;
       }
+      // `/api/v1/entities/facets/` — BEFORE the detail branch below, which
+      // would otherwise read "facets" as a record id and 404.
+      if (/entities\/facets\/?$/.test(path)) {
+        return facetRead(entities, params) as T;
+      }
       if (path.includes('entities')) {
         const id = /entities\/(.+)$/.exec(path)?.[1];
         if (id) {
@@ -1041,7 +1282,28 @@ export function createFixtureCorpusHttp(options: {
             matchesTenantSearch(term, `${entity.name ?? ''} ${jsonStrings(entity.data)}`),
           );
         }
-        return slice(rows, params) as T;
+        // THE FOLDER BOUNDS, as the tenant really applies them
+        // (start-simpli-api#391). `attr.path` is the shelf; `attr.path__under`
+        // is the shelf PLUS its descendants — a union, which is why it is one
+        // parameter and not a prefix the client assembled. A fixture that
+        // treated `__under` as a plain `startsWith` would let a client pass
+        // here and match `/Contracts-old` in production.
+        const applied: string[] = [];
+        const exact = params['attr.path'];
+        const under = params['attr.path__under'];
+        if (exact !== undefined) {
+          rows = rows.filter((entity) => pathOf(entity) === normalizeContainer(exact));
+          applied.push('attr.path');
+        } else if (under !== undefined) {
+          const [self, descendants] = subtreeBound(under);
+          rows = rows.filter((entity) => {
+            const at = pathOf(entity);
+            return at === self || at.startsWith(descendants);
+          });
+          applied.push('attr.path__under');
+        }
+        if (term && options.searchBackend === 'postgres_fulltext') applied.push('search');
+        return { ...slice(rows, params), applied_filters: applied } as T;
       }
       throw Object.assign(new Error(`${path} responded 404`), { status: 404 });
     },

package/src/corpus/index.ts

@@ -35,11 +35,13 @@ export type {
   Citation,
   CorpusApi,
   CorpusAskApi,
+  CorpusFolder,
   CorpusLlm,
   CorpusPage,
   CorpusScope,
   DocumentQuery,
   DocumentSection,
+  FolderQuery,
   Focus,
   FocusCategory,
   FocusDraft,
@@ -74,10 +76,15 @@ export {
   toMoneyEvent,
   toParty,
   toPartyRef,
+  FOLDER_ROOT,
+  toFolder,
+  folderName,
   toSections,
   toSourceDocument,
 } from './entities';
-export type { CorpusTypeKeys, TenantEntity, TenantRelationship } from './entities';
+export type {
+  CorpusTypeKeys, TenantEntity, TenantFacetRow, TenantRelationship,
+} from './entities';
 
 export {
   enforceScope,