V48 (impl-only): Drop attachments barrel package

Retire the plural @bitcode/attachments-generics composition barrel.
Keep the core pattern: attachment-generics primitive plus leaf bases
under generic-attachments/{file,external}.

Retarget api and conversations imports/deps to the primitive. Update
tsconfig, jest map, proven inventory, lockfile, and hierarchy docs.

Author: geraldarthurdavis

.docs/BITCODE_FILESYSTEM_TLDR.md

@@ -645,19 +645,13 @@ Format: `path -- <1 sentence TL;DR>`.
  artifacts.ts -- Source module in package `artifacts`.
  package.json -- Package/workspace manifest and dependency exports.
  README.md -- Human orientation for this directory.
- attachments-generics/ -- Domain package `attachments-generics` (pure reusable logic).
- src/ -- Subfolder of package `attachments-generics`.
- index.d.ts -- Public package export surface.
- index.js -- Package `attachments-generics` artifact.
+ attachment-generics/ -- Attachment primitive (`@bitcode/attachment-generics`).
+ src/ -- Subfolder of package `attachment-generics`.
  index.ts -- Public package export surface.
- types.d.ts -- Source module in package `attachments-generics`.
- types.js -- Package `attachments-generics` artifact.
- types.ts -- Source module in package `attachments-generics`.
- utils.d.ts -- Source module in package `attachments-generics`.
- utils.js -- Package `attachments-generics` artifact.
- utils.ts -- Source module in package `attachments-generics`.
+ types.ts -- Source module in package `attachment-generics`.
  package.json -- Package/workspace manifest and dependency exports.
  README.md -- Human orientation for this directory.
+ generic-attachments/ -- Leaf bases file|external (`@bitcode/generic-attachments-*`).
  aurora-postgres/ -- Domain package `aurora-postgres` (pure reusable logic).
  src/ -- Subfolder of package `aurora-postgres`.
  index.js -- Package `aurora-postgres` artifact.

.docs/BITCODE_SOURCE_LAYOUT.md

@@ -305,8 +305,8 @@ packages/generic-<family>/ # README only (no package.json)
 | `generic-doc-comments/` | `doc-code/`, `doc-developing/` | `@bitcode/generic-doc-comments-*` |
 | `artifact-generics/` | (package root) | `@bitcode/artifact-generics` |
 | `generic-artifacts/` | `patch/`, `aws/`, `supabase/`, `vercel/` | type + storage providers |
-| `attachment-generics/` | (package root) | `@bitcode/attachment-generics` |
-| `generic-attachments/` | `file/`, `external/` | `@bitcode/generic-attachments-*` |
+| `attachment-generics/` | (package root) | `@bitcode/attachment-generics` (primitive) |
+| `generic-attachments/` | `file/`, `external/` | `@bitcode/generic-attachments-*` (leaf bases) |
 | `files/` | (package root) | `@bitcode/files` |
 | `file-editing/` | (package root) | `@bitcode/file-editing` |
 | `file-refactoring/` | (package root) | `@bitcode/file-refactoring` |

.docs/FAMILIARIZATION.md

@@ -285,23 +285,25 @@ No standalone `@bitcode/aws` package — S3 for artifacts is `generic-artifacts-
 | Storage bases | aws / supabase / vercel | provider implementations |
 | Product | `DataPackPatchArtifact` | patch bound to `assetPackId` |
 
-### 3.1.5 Attachments (primitive → file | external)
+### 3.1.5 Attachments (primitive → file | external leaves)
+
+Core `*-generics` + `generic-*` leaf pattern (no plural composition barrel):
 
 ```
 @bitcode/attachment-generics BaseAttachment; categories file|external
  ↑
-@bitcode/generic-attachments-file FileAttachment
+@bitcode/generic-attachments-file FileAttachment   # packages/generic-attachments/file
 @bitcode/generic-attachments-external ExternalAttachment (Externals auxillary)
  ↑
-@bitcode/attachments-generics composition barrel
+product (api, conversations) imports primitive for refs/categories; leaves when specializing
 ```
 
 | Category | Role |
 | --- | --- |
 | `file` | Direct uploads |
 | `external` | Externals connections (GitHub, Jira, Notion, …) — not “integration” |
 
-Removed: `vcs`, `url`. VCS attaches as **external**.
+Removed: `vcs`, `url`. VCS attaches as **external**. Retired: `@bitcode/attachments-generics` twin-name barrel.
 
 ### 3.2.0 VCS
 

apps/uapi/jest.config.cjs

@@ -115,7 +115,6 @@ module.exports = {
     '^@bitcode/attachment-generics$': '<rootDir>/../../packages/attachment-generics/src/index.ts',
     '^@bitcode/generic-attachments-file$': '<rootDir>/../../packages/generic-attachments/file/src/index.ts',
     '^@bitcode/generic-attachments-external$': '<rootDir>/../../packages/generic-attachments/external/src/index.ts',
-    '^@bitcode/attachments-generics$': '<rootDir>/../../packages/attachments-generics/src/index.ts',
     '^@bitcode/mcp-generics$': '<rootDir>/../../packages/mcp-generics/src/index.ts',
     '^@bitcode/generic-mcps-bitcode$': '<rootDir>/../apps/mcp/src/index.ts',
     '^@bitcode/generic-mcps-bitcode$': '<rootDir>/../apps/mcp/src/index.ts',

packages/api/package.json

@@ -12,7 +12,7 @@
     "type-check": "pnpm run typecheck"
   },
   "dependencies": {
-    "@bitcode/attachments-generics": "workspace:*",
+    "@bitcode/attachment-generics": "workspace:*",
     "@bitcode/auth": "workspace:*",
     "@bitcode/generic-vcs-bitbucket": "workspace:*",
     "@bitcode/conversations": "workspace:*",

packages/api/src/conversations/attachments.ts

@@ -4,7 +4,7 @@
  */
 
 import { supabaseAdmin } from '@bitcode/supabase';
-import { AttachmentReference, AttachmentCategory } from '@bitcode/attachments-generics';
+import { AttachmentReference, AttachmentCategory } from '@bitcode/attachment-generics';
 import { log } from '@bitcode/logger';
 import * as crypto from 'crypto';
 

packages/api/src/conversations/messages.ts

@@ -6,7 +6,7 @@
 import { supabaseAdmin } from '@bitcode/supabase';
 // Use DB table type for strong alignment with current schema
 import type { Message } from '@bitcode/orm';
-import { AttachmentReference } from '@bitcode/attachments-generics';
+import { AttachmentReference } from '@bitcode/attachment-generics';
 import { log } from '@bitcode/logger';
 import * as crypto from 'crypto';
 import {

packages/api/src/routes/conversations.ts

@@ -8,8 +8,8 @@
 import * as crypto from 'crypto';
 
 import { createAdminClient } from '@bitcode/orm';
-import type { AttachmentReference } from '@bitcode/attachments-generics';
-import { validateAttachmentCategory } from '@bitcode/attachments-generics';
+import type { AttachmentReference } from '@bitcode/attachment-generics';
+import { validateAttachmentCategory } from '@bitcode/attachment-generics';
 import { createClient } from '@bitcode/supabase/ssr/server';
 import { traceRoute } from '@bitcode/observability';
 import { createJsonResponse } from '@bitcode/api/responses';

packages/attachment-generics/README.md

@@ -2,17 +2,22 @@
 
 **Attachment** primitive contracts — base identity, admitted categories, and references.
 
-## Hierarchy
+## Hierarchy (core pattern)
 
 ```
-@bitcode/attachment-generics # this package (Attachment primitive)
+@bitcode/attachment-generics              # this package (Attachment primitive)
  ↑
-@bitcode/generic-attachments-file # FileAttachment base
-@bitcode/generic-attachments-external # ExternalAttachment base (Externals auxillary)
+@bitcode/generic-attachments-file         # packages/generic-attachments/file
+@bitcode/generic-attachments-external     # packages/generic-attachments/external
  ↑
-product conversations / API / UI
+product (api, conversations, uapi)        # import primitive and/or leaf bases
 ```
 
+Leaf packages under `generic-attachments/` are the correct organizational pattern
+for file | external **base implementations**. Prefer leaf imports when you need
+`FileAttachment` / `ExternalAttachment`; use this package for
+`BaseAttachment`, `AttachmentReference`, and category guards.
+
 ## Admitted categories (only)
 
 | Category | Role |
@@ -27,3 +32,4 @@ product conversations / API / UI
 - Primitive does not own file MIME tables or provider payloads.
 - Bases live under `packages/generic-attachments/{file,external}/`.
 - **External** vocabulary aligns with the Externals auxillary (not “integration”).
+- Do **not** reintroduce a plural composition barrel (`attachments-generics`); that twin name was retired in favor of primitive + leaves.

packages/attachment-generics/src/index.ts

@@ -3,12 +3,14 @@
  *
  * Attachment **primitive** — base fields, categories file|external, references.
  *
- * Prefer:
- *   @bitcode/attachment-generics
- *   @bitcode/generic-attachments-file
- *   @bitcode/generic-attachments-external
+ * Hierarchy (core *generics + generic-* leaves pattern):
+ *   @bitcode/attachment-generics              # this package
+ *     → @bitcode/generic-attachments-file     # file leaf base
+ *     → @bitcode/generic-attachments-external # external leaf base
  *
- * Composition: @bitcode/attachments-generics re-exports this surface + bases.
+ * Product code imports this package for refs/categories, and leaf packages
+ * when specializing FileAttachment / ExternalAttachment. There is no plural
+ * composition barrel package.
  */
 
 export type {