V48 (specification-implementation): Attachment hierarchy file|external; retire integration

Add @bitcode/attachment-generics (BaseAttachment, categories file|external only),
@bitcode/generic-attachments-file, and @bitcode/generic-attachments-external.
Rename integration→external everywhere to align with the Externals auxillary.
Remove vcs and url attachment categories (VCS attaches as external). BC barrel
@bitcode/attachments-generics re-exports the hierarchy.

Author: geraldarthurdavis

BITCODE_SPEC_V48_NOTES.md

@@ -1666,6 +1666,21 @@ AssetPack path+op envelopes without requiring raw source. Product binds
 `assetPackId`. Existing `saveArtifact` / `putArtifactAtKey` callers keep
 `@bitcode/artifacts`.
 
+## Attachment hierarchy: file | external only (Garrett, 2026-07-13)
+
+```
+@bitcode/attachment-generics                         # primitive (BaseAttachment, categories)
+  → @bitcode/generic-attachments-file                # FileAttachment
+  → @bitcode/generic-attachments-external            # ExternalAttachment
+@bitcode/attachments-generics                        # BC barrel
+```
+
+- Categories admitted: **`file` | `external`** only.
+- **`integration` → `external`** everywhere (aligns with Externals auxillary:
+  GitHub VCS, future Jira/Notion/etc. attach as external connections).
+- **`vcs` and `url` categories removed** (VCS is external; bare URL is not a category).
+
+
 ## AssetPack product pipelines: no lens; Simple settle-reads (Garrett, 2026-07-13)
 
 Removed the deposit|read **lens** on a single SynthesizeAssetPacks factory.

FAMILIARIZATION.md

@@ -245,6 +245,24 @@ Package paths: `packages/artifact-generics/`, `packages/generic-artifacts/patch/
 | Base | `PatchArtifact` | path+op patchfile envelope for AssetPack patches |
 | Product | `AssetPackPatchArtifact` | patch bound to `assetPackId` for synthesis |
 
+### 3.1.5 Attachments (primitive → file | external)
+
+```
+@bitcode/attachment-generics                      BaseAttachment; categories file|external
+        ↑
+@bitcode/generic-attachments-file                 FileAttachment
+@bitcode/generic-attachments-external             ExternalAttachment (Externals auxillary)
+        ↑
+@bitcode/attachments-generics                     BC barrel
+```
+
+| Category | Role |
+| --- | --- |
+| `file` | Direct uploads |
+| `external` | Externals connections (GitHub, Jira, Notion, …) — not “integration” |
+
+Removed: `vcs`, `url`. VCS attaches as **external**.
+
 ### 3.2.0 VCS
 
 

internal-docs/BITCODE_SOURCE_LAYOUT.md

@@ -228,6 +228,9 @@ packages/generic-<family>/          # README only (no package.json)
 | `artifact-generics/` | (package root) | `@bitcode/artifact-generics` (Artifact + storage contract) |
 | `generic-artifacts/` | `patch/` | `@bitcode/generic-artifacts-patch` (PatchArtifact base) |
 | `artifacts/` | (package root) | `@bitcode/artifacts` (S3/Supabase ArtifactStorage backend) |
+| `attachment-generics/` | (package root) | `@bitcode/attachment-generics` (file|external primitives) |
+| `generic-attachments/` | `file/`, `external/` | `@bitcode/generic-attachments-*` |
+| `attachments-generics/` | (package root) | BC barrel over attachment hierarchy |
 | `generic-doc-comment-plugins/` | `doc-developing/` | `@bitcode/doc-comment-developing` |
 
 **Do not** put a root `package.json` on the family folder. Workspace globs are

package.json

@@ -21,6 +21,7 @@
     "packages/asset-packs/*",
     "packages/generic-asset-packs/*",
     "packages/generic-artifacts/*",
+    "packages/generic-attachments/*",
     "packages/asset-packs-pipelines/*",
     "packages/generic-doc-comment-plugins/*",
     "packages/pipelines/*",

packages/api/src/conversations/__tests__/branch-conversation.test.ts

@@ -103,7 +103,7 @@ describe('branchConversation', () => {
         id: 'att-source-1',
         message_id: 'm1',
         attachment_id: 'repo-1',
-        attachment_category: 'integration',
+        attachment_category: 'external',
         attachment_type: 'github_repo',
         metadata: { token_type: 'source', title: 'bitcode/terminal' },
         created_at: new Date().toISOString(),
@@ -112,7 +112,7 @@ describe('branchConversation', () => {
         id: 'att-destination-1',
         message_id: 'm2',
         attachment_id: 'dest-1',
-        attachment_category: 'integration',
+        attachment_category: 'external',
         attachment_type: 'settlement_target',
         metadata: { token_type: 'destination', title: 'Settlement lane' },
         created_at: new Date().toISOString(),

packages/attachment-generics/README.md

@@ -0,0 +1,29 @@
+# @bitcode/attachment-generics
+
+**Attachment** primitive contracts — base identity, admitted categories, and references.
+
+## Hierarchy
+
+```
+@bitcode/attachment-generics                    # this package (Attachment primitive)
+        ↑
+@bitcode/generic-attachments-file               # FileAttachment base
+@bitcode/generic-attachments-external           # ExternalAttachment base (Externals auxillary)
+        ↑
+product conversations / API / UI
+```
+
+## Admitted categories (only)
+
+| Category | Role |
+| --- | --- |
+| `file` | Direct file uploads |
+| `external` | Connections from Externals (GitHub VCS, Jira, Notion, …) |
+
+**Not admitted (removed):** `vcs`, `url` — VCS/repo linking is an **external** connection; bare URLs are not a separate attachment category.
+
+## Law
+
+- 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”).

packages/attachment-generics/jest.config.cjs

@@ -0,0 +1,11 @@
+module.exports = {
+  preset: 'ts-jest/presets/js-with-ts',
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  moduleNameMapper: {
+    '^@bitcode/attachment-generics$': '<rootDir>/src/index.ts',
+  },
+  globals: {
+    'ts-jest': { tsconfig: '<rootDir>/../../tsconfig.json', diagnostics: false },
+  },
+};

packages/attachment-generics/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@bitcode/attachment-generics",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Attachment primitive: BaseAttachment, categories file|external, references, type guards",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm exec jest --config jest.config.cjs --passWithNoTests"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^25.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.0.0"
+  }
+}

packages/attachment-generics/src/__tests__/attachment-primitive.test.ts

@@ -0,0 +1,25 @@
+import {
+  validateAttachmentCategory,
+  isBaseAttachment,
+  type BaseAttachment,
+} from '../index';
+
+describe('attachment-generics primitives', () => {
+  it('admits only file and external categories', () => {
+    expect(validateAttachmentCategory('file')).toBe(true);
+    expect(validateAttachmentCategory('external')).toBe(true);
+    expect(validateAttachmentCategory('vcs')).toBe(false);
+    expect(validateAttachmentCategory('url')).toBe(false);
+    expect(validateAttachmentCategory('integration')).toBe(false);
+  });
+
+  it('recognizes a base attachment shape', () => {
+    const attachment: BaseAttachment = {
+      id: 'att-1',
+      category: 'file',
+      title: 'Screenshot',
+      created_at: new Date().toISOString(),
+    };
+    expect(isBaseAttachment(attachment)).toBe(true);
+  });
+});

packages/attachment-generics/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @bitcode/attachment-generics
+ *
+ * Attachment **primitive** — base fields, categories file|external, references.
+ *
+ * Prefer:
+ *   @bitcode/attachment-generics
+ *   @bitcode/generic-attachments-file
+ *   @bitcode/generic-attachments-external
+ *
+ * BC: @bitcode/attachments-generics re-exports this surface + bases.
+ */
+
+export type {
+  AttachmentCategory,
+  BaseAttachment,
+  AttachmentReference,
+  CreateAttachmentInput,
+} from './types';
+export {
+  isAttachmentCategory,
+  validateAttachmentCategory,
+  isBaseAttachment,
+} from './types';