V48 (specification-implementation): Host hierarchy + rename InlineHost to LocalHost

Establish host-generics (BitcodePipelineHost primitives, SandboxHost base) and
generic-hosts/{Local,VercelSandbox} bases. Rename InlineHost/hostKind inline to
LocalHost/local everywhere (BITCODE_PIPELINE_HOST=inline remains a BC alias).
pipeline-hosts becomes the harness barrel + compatibility re-exports. Align
docs with V48 G3-4 host law.

Author: geraldarthurdavis

BITCODE_SPEC_V48.md

@@ -411,7 +411,7 @@ Dispatch must use Vercel `waitUntil` (QA F31) — bare `void` after response is
 
 | HostKind | Implementation | Law |
 |---|---|---|
-| `inline` | `packages/pipeline-hosts` InlineHost + `uapi/lib/deposit-source-provisioning` | Default when `BITCODE_PIPELINE_HOST` unset. Real `git clone` of full tree; Node fs workspace; inventory `paths` + `sources` + `samples`. |
+| `local` | `packages/pipeline-hosts` LocalHost + `uapi/lib/deposit-source-provisioning` | Default when `BITCODE_PIPELINE_HOST` unset. Real `git clone` of full tree; Node fs workspace; inventory `paths` + `sources` + `samples`. |
 | `sandbox` | `VercelSandboxPipelineHost` + asset-pack harness | When `BITCODE_PIPELINE_HOST=sandbox`. Auth: OIDC or `VERCEL_TOKEN`+team+project — fail closed if missing. Deposit boxes **`persistent: false`**. Create → run harness in-box → stop/delete. Persist `context.sandboxId` while running for cancel. Events: `sandbox-create-started`, `sandbox-created`, `command-started`, `sandbox-stopped`, `sandbox-cancelled`. |
 
 Inventory scope after provision: `applyInventoryScope({ inclusions: forcedInclusions, exclusions: forcedExclusions })`. Prompt path uses `projectInventoryForPrompt` (paths+samples only — never full `sources` in prompts).
@@ -545,7 +545,7 @@ Rebuild order in `buildDepositRouteSession` / `DepositPageClient`:
 | `BITCODE_ASSET_PACK_REAL_INFERENCE` | `true` for live deposit |
 | `BITCODE_LLM_PROVIDER` / `BITCODE_LLM_MODEL` | `xai` / `grok-build-0.1` default when key present |
 | `BITCODE_LLM_CALL_TIMEOUT_MS` | `180000` |
-| `BITCODE_PIPELINE_HOST` | unset=inline; `sandbox`=in-box |
+| `BITCODE_PIPELINE_HOST` | unset=local; `sandbox`=in-box |
 | `XAI_API_KEY` | Required for xAI |
 | Vercel sandbox auth | OIDC or token+team+project when sandbox host |
 | Supabase | executions + execution_events migrations applied |
@@ -561,7 +561,7 @@ Rebuild order in `buildDepositRouteSession` / `DepositPageClient`:
 | Real option projection | `deposit-option-real-synthesis.ts` |
 | Policy / admission / earnings | `deposit-asset-pack-option-policy.ts`, `deposit-asset-pack-option-admission.ts`, `depositor-earning-supply-intelligence.ts` |
 | Settled demand | `depository-settled-demand-estimate.ts`, `uapi/lib/depository-settled-demand.ts` |
-| Hosts | `packages/pipeline-hosts/src/{inline-host,vercel-sandbox-host,asset-pack-harness,host}.ts` |
+| Hosts | `packages/pipeline-hosts/src/{local-host,vercel-sandbox-host,asset-pack-harness,host}.ts` |
 | Provisioning | `uapi/lib/deposit-source-provisioning.ts` |
 | Synthesize route | `uapi/app/api/deposit/synthesize-options/route.ts` |
 | Demand route | `uapi/app/api/deposit/demand-estimate/route.ts` |

BITCODE_SPEC_V48_NOTES.md

@@ -962,10 +962,10 @@ read locally, NEVER across a process/network boundary. The pipeline (Setup → 
 Validation) speaks only to the primitive, so its behavior is identical on every host.
 
 **HostKinds — two implementations of the primitive:**
-- **InlineHost** (`inline-host.ts`) — runs the pipeline in the current box; provisions
+- **LocalHost** (`local-host.ts`) — runs the pipeline in the current box; provisions
   via a real `git clone` of the full tree to a local working dir (Node-fs workspace).
 - **SandboxHost** (`sandbox-host.ts`) — runs the pipeline inside a provisioned, isolated
-  box that has git + FS, so within it the checkout is local exactly as for InlineHost.
+  box that has git + FS, so within it the checkout is local exactly as for LocalHost.
   It is a base for providers:
   - **Vercel** (`VercelSandboxHost`, IMPLEMENTED) — provisions via the Sandbox SDK git
     source into the box working directory.
@@ -1034,7 +1034,7 @@ is named in spec for closure):
   built by `buildRealDepositAssetPackOptionSynthesis`; the `/deposit` card renders the
   "If deposited, Bitcode receives" panel.
 - **Host + provisioning.** `packages/pipeline-hosts`: `BitcodePipelineHost` /
-  `BitcodeHostWorkspace` / `BitcodeHostCapabilities` (`host.ts`); `InlineHost`;
+  `BitcodeHostWorkspace` / `BitcodeHostCapabilities` (`host.ts`); `LocalHost`;
   `SandboxHost` + `VercelSandboxHost` (Vercel provider) + `AwsSandboxHost` (stub);
   `readWorkspaceSources`. `uapi/lib/deposit-source-provisioning.ts`:
   `selectDepositHostKind`, `resolveDepositPipelineHost`, `provisionDepositSourceInventory`.
@@ -1063,14 +1063,14 @@ the live packages and executes the full SDIVF). Deposit reuses that mechanism:
   `VERCEL_PROJECT_ID`. `assertVercelSandboxAuthAvailable` fails closed before create.
 - **Route dispatch.** When `BITCODE_PIPELINE_HOST=sandbox`, the deposit route
   dispatches via `runDepositInBoxHarness` → `VercelSandboxPipelineHost.runHarness`
-  instead of InlineHost provision + in-process SDIVF; it reads `evidence.depositOptions`,
+  instead of LocalHost provision + in-process SDIVF; it reads `evidence.depositOptions`,
   runs the SAME pure projection (`validateDepositSynthesisOptions` +
   `buildRealDepositAssetPackOptionSynthesis`) and persists the deposit option
   synthesis. `resolveDepositPipelineHost` is **inline-only** (throws if hostKind is
   sandbox — callers must use the harness path). On `sandbox-created`, the route
   persists `context.sandboxId` on the running execution row for cancel.
 - **Cooperative cancel.** See Gate-3 #26.
-- **Parity of result.** InlineHost and SandboxHost produce the SAME deposit option
+- **Parity of result.** LocalHost and SandboxHost produce the SAME deposit option
   synthesis; only WHERE the pipeline runs differs. Real-sandbox execution is verified
   against deployed sandbox infra; harness plan-building + route dispatch + projection
   are unit-tested with a mocked host.
@@ -1143,13 +1143,13 @@ Parity: ✅ specified + implemented + tested · 🟦 specified + implemented as
 | 15 | card "If deposited, Bitcode receives" | `DepositPageClient.tsx` | depositPageClient.test | ✅ |
 | 16 | full SDIVF pipeline only; Validation never skipped | deposit route (flag removed) | depositSynthesizeOptionsRoute.test | ✅ |
 | 17 | primitive Host + capabilities + workspace | `BitcodePipelineHost` / `BitcodeHostWorkspace` | inline/sandbox-host.test | ✅ |
-| 18 | InlineHost (real clone + Node fs) | `InlineHost` | inline-host.test | ✅ |
+| 18 | LocalHost (real clone + Node fs) | `LocalHost` | local-host.test | ✅ |
 | 19 | SandboxHost + Vercel provider | `SandboxHost` / `VercelSandboxHost` | sandbox-host.test | ✅ |
 | 20 | AWS provider seam | `AwsSandboxHost` (stub: provision throws) | sandbox-host.test | 🟦 |
 | 21 | checkout → sources bridge | `readWorkspaceSources` | inline/sandbox-host.test | ✅ |
 | 22 | HostKind selection (configured, not env) | `selectDepositHostKind` / `resolveDepositPipelineHost` | depositSourceProvisioning.test | ✅ |
 | 23 | full inventory (sources+samples) + fail-closed exclusions | `provisionDepositSourceInventory` / `applyExclusionsToInventory` | depositSourceProvisioning.test, asset-packs-synthesis.test | ✅ |
-| 24 | deposit provisions full checkout via Host | deposit route + `InlineHost` path | depositSynthesizeOptionsRoute.test | ✅ |
+| 24 | deposit provisions full checkout via Host | deposit route + `LocalHost` path | depositSynthesizeOptionsRoute.test | ✅ |
 | 25 | SandboxHost IN-BOX deposit dispatch (run the pipeline in the box) | harness deposit mode (`synthesizeMode` + steering → in-box runner; `depositOptions` in evidence) + `runDepositInBoxHarness` + route hostKind branch; ephemeral `persistent:false`; OIDC/token auth fail-closed | asset-pack-harness.test, depositSourceProvisioning.test, depositSynthesizeOptionsRoute.test, vercel-sandbox-host.test | ✅* |
 | 26 | Cooperative run cancel | `POST /api/executions/[runId]/cancel` + `execution-cancel.ts` + deposit route polls + sandbox `shouldAbort` + UI Cancel run + `deposit_synthesis_cancelled` analytics | executionCancelRoute.test, vercel-sandbox-host.test (abort), depositPageClient (cancel control) | ✅ |
 | 27 | Run configuration locked above telemetry in run detail | `DepositPageClient` config above telemetry; `disabled` when `synthesisRunId` set | depositPageClient.test | ✅ |
@@ -1599,3 +1599,15 @@ Compatibility shims remain at `@bitcode/vcs`, `@bitcode/github`, `@bitcode/gitla
 `generic-tools/vcs` and `generic-agents-vcs` are tools/agents over the VCS layer,
 not provider packages.
 
+## Host hierarchy modularization + Local rename (Garrett, 2026-07-13)
+
+```
+@bitcode/host-generics                         # primitives (BitcodePipelineHost, SandboxHost)
+  → @bitcode/generic-hosts-local               # LocalHost (renamed from InlineHost)
+  → @bitcode/generic-hosts-vercel-sandbox      # VercelSandboxHost + PipelineHost harness
+    → @bitcode/pipeline-hosts                  # AssetPack harness barrel + BC re-exports
+```
+
+HostKind `local` replaces `inline` (BITCODE_PIPELINE_HOST; `inline` accepted as alias).
+Spec G3-4 tables updated to LocalHost / hostKind `local`.
+

BITCODE_V48_QA.md

@@ -593,7 +593,7 @@ lines / UI values into §6 for the QA record.
   - `BITCODE_ASSET_PACK_REAL_INFERENCE=true` — the ONLY required flag. Do NOT set
     `BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE` (profiles removed, F26-A; it is a no-op).
   - Anthropic key present (default `claude-haiku-4-5` since 2026-07-03; `BITCODE_LLM_MODEL` overrides).
-  - `BITCODE_PIPELINE_HOST` unset (defaults to `inline`) — the dev Node server IS the
+  - `BITCODE_PIPELINE_HOST` unset (defaults to `local`) — the dev Node server IS the
     inline host, so it must have `git` on PATH + a writable temp dir.
 - Supabase LOCAL (decided 2026-07-03): `uapi/.env.local` points at the local stack
   (`127.0.0.1:54321`, `supabase start`/Docker running); `dev:remote` serves against it directly.
@@ -611,7 +611,7 @@ the streaming accordion log.
 
 | # | What | COPY | PASS |
 |---|---|---|---|
-| Host | `Provisioning {repo}@{ref} on the inline host…` then `Checkout ready: N files (M withheld by K protected-IP exclusions; full source measured, S prompt excerpts).` | the "Checkout ready" line | N = the repo's REAL tracked-file count (full repo, not ≤400/≤10); "full source measured"; M = exclusion-withheld files. FAIL if N≤10 or "samples"/API language → stopgap still active |
+| Host | `Provisioning {repo}@{ref} on the local host…` then `Checkout ready: N files (M withheld by K protected-IP exclusions; full source measured, S prompt excerpts).` | the "Checkout ready" line | N = the repo's REAL tracked-file count (full repo, not ≤400/≤10); "full source measured"; M = exclusion-withheld files. FAIL if N≤10 or "samples"/API language → stopgap still active |
 | Pipeline | `Running SynthesizeAssetPacks (deposit mode): Setup → Discovery → Implementation → Validation → Finish…` | the Phase pills from telemetry | all five phases present; Validation never skipped |
 | Absolutes | Validation telemetry shows `AssetPackMeasureAbsolutesAgent:deposit`; card measurements tile: `Functions: <N> functions · <v>% / weight 0.18`, `Types`, `File span`, `Correctness · <v>% / weight 0.28`, `Semantic volume` | the tile values + `output.depositOptionSynthesis.options[i].measurements` | size measures carry `magnitude`(int)+`unit`+`category:'absolute'`; magnitudes are plausible real counts; weights sum to 1. FAIL if `source-coverage`/`demand-alignment`/`reuse-likelihood` appear → placeholders still in use |
 | Card payload | option card emerald panel "If deposited, Bitcode receives": patchSummary + "Synthesized contents · N file(s)" (op-colored create/modify/delete) + "Provenant source · N files available to Bitcode" | `…options[i].contents` (patchSummary, fileChanges, provenantSourcePaths, provenantSourceCount) + screenshot | BOTH the synthesized contents AND the provenant source files shown prominently; fileChanges are path+op only (no raw code) |
@@ -641,7 +641,7 @@ cd uapi && pnpm exec jest depositSourceProvisioning depositSynthesizeOptionsRout
 ```
 
 **5. #25 SandboxHost in-box dispatch (deployment-conditional)**
-- Local default is inline. To exercise the sandbox path: `BITCODE_PIPELINE_HOST=sandbox`
+- Local default is local host. To exercise the sandbox path: `BITCODE_PIPELINE_HOST=sandbox`
   + sandbox auth (`VERCEL_OIDC_TOKEN` via `vercel env pull`, or
   `VERCEL_TOKEN`/`VERCEL_TEAM_ID`/`VERCEL_PROJECT_ID`) + `@vercel/sandbox` + git in the box image.
   Missing auth must fail closed with a clear message (not a silent hang).

FAMILIARIZATION.md

@@ -197,6 +197,19 @@ Compatibility shims: `@bitcode/vcs`, `@bitcode/github`, …
 pipeline-local tools            e.g. AssetPackLexicalDepositorySearchTool
 ```
 
+### 3.2.1 Hosts
+
+```
+@bitcode/host-generics                         BitcodePipelineHost primitive
+        ↑
+@bitcode/generic-hosts-local                   LocalHost (default; was InlineHost)
+@bitcode/generic-hosts-vercel-sandbox          VercelSandboxHost / PipelineHost
+        ↑
+@bitcode/pipeline-hosts                        Harness orchestration + BC re-exports
+```
+
+`BITCODE_PIPELINE_HOST`: unset|`local` (default; `inline` alias) | `sandbox`.
+
 ### 3.3 Pipelines
 
 **Hierarchy naming law:** names always encode full ancestry
@@ -215,7 +228,7 @@ pipeline-local tools            e.g. AssetPackLexicalDepositorySearchTool
         ↑
 @bitcode/pipeline-asset-pack             SynthesizeAssetPacksSDIVFPipeline (deposit | read);
                                          future SettleAssetPacksSDIVFPipeline
-@bitcode/pipeline-hosts                  Inline host + Vercel Sandbox harness
+@bitcode/pipeline-hosts                  Local host + Vercel Sandbox harness
 ```
 
 **SDIVF** = Setup → Discovery → Implementation → Validation → Finish  

README.md

@@ -146,7 +146,7 @@ Full QA checklist: `BITCODE_V48_QA.md` → Gate 3 depositing runbook.
 |---|---|
 | `uapi/` | Next.js app — `/deposits`, `/reads`, `/packs`, APIs |
 | `packages/pipelines/asset-pack/` | SynthesizeAssetPacks SDIVF, deposit agents, policy, demand estimate |
-| `packages/pipeline-hosts/` | InlineHost, VercelSandbox, harness |
+| `packages/pipeline-hosts/` | LocalHost, VercelSandbox, harness |
 | `packages/agent-generics/` | PTRR, failsafes, Thinkings, LLM call timeout |
 | `packages/generic-llms/` | xAI/Grok and other LLM providers |
 | `packages/execution-generics/` | Execution tree, streaming adapters |

internal-docs/BITCODE_SOURCE_LAYOUT.md

@@ -212,6 +212,8 @@ packages/generic-<family>/          # README only (no package.json)
 | `generic-measurements/` | `measure-agent/`, `absolutes/`, `needinesses/` | `@bitcode/generic-measurements-*` |
 | `generic-vcs/` | `github/`, `gitlab/`, `bitbucket/`, `git/` | `@bitcode/generic-vcs-*` |
 | `vcs-generics/` | (package root) | `@bitcode/vcs-generics` |
+| `host-generics/` | (package root) | `@bitcode/host-generics` |
+| `generic-hosts/` | `Local/`, `VercelSandbox/` | `@bitcode/generic-hosts-*` |
 | `asset-packs/` | `synthesis/`, `settle/` | `@bitcode/asset-packs-synthesis`, `-settle` |
 | `generic-doc-comment-plugins/` | `doc-developing/` | `@bitcode/doc-comment-developing` |
 

package.json

@@ -16,6 +16,7 @@
     "packages/generic-generations/*",
     "packages/generic-measurements/*",
     "packages/generic-vcs/*",
+    "packages/generic-hosts/*",
     "packages/asset-packs/*",
     "packages/generic-doc-comment-plugins/*",
     "packages/pipelines/*",

packages/generic-hosts/Local/jest.config.cjs

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

packages/generic-hosts/Local/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@bitcode/generic-hosts-local",
+  "version": "0.1.0",
+  "private": true,
+  "description": "LocalHost: in-process HostKind (git clone + Node filesystem). Formerly InlineHost.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": { ".": "./src/index.ts" },
+  "scripts": {
+    "test": "pnpm exec jest --config jest.config.cjs --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@bitcode/host-generics": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^25.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.0.0"
+  }
+}

…-hosts/src/__tests__/inline-host.test.ts …s/Local/src/__tests__/local-host.test.tspackages/pipeline-hosts/src/__tests__/inline-host.test.ts renamed to packages/generic-hosts/Local/src/__tests__/local-host.test.ts packages/pipeline-hosts/src/__tests__/inline-host.test.ts renamed to packages/generic-hosts/Local/src/__tests__/local-host.test.ts

@@ -2,8 +2,8 @@ import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-import { InlineHost, type InlineHostOptions } from '../inline-host';
-import { readWorkspaceSources, type HostExec } from '../host';
+import { LocalHost, type LocalHostOptions } from '../local-host';
+import { readWorkspaceSources, type HostExec } from '@bitcode/host-generics';
 
 const FIXTURE: Record<string, string> = {
   'README.md': '# Demo\nA demo project.',
@@ -35,20 +35,20 @@ function fakeExec(): { exec: HostExec; calls: string[][] } {
   return { exec, calls };
 }
 
-describe('InlineHost (primitive Host implementation)', () => {
+describe('LocalHost (primitive Host implementation)', () => {
   let rootDir: string;
   afterEach(async () => {
     if (rootDir) await fs.rm(rootDir, { recursive: true, force: true });
   });
   async function makeRoot() {
-    rootDir = await fs.mkdtemp(path.join(os.tmpdir(), 'inline-host-test-'));
+    rootDir = await fs.mkdtemp(path.join(os.tmpdir(), 'local-host-test-'));
     return rootDir;
   }
 
-  it('reports inline capabilities (clone + filesystem + exec)', async () => {
-    const host = new InlineHost({ exec: fakeExec().exec, rootDir: await makeRoot() });
+  it('reports local capabilities (clone + filesystem + exec)', async () => {
+    const host = new LocalHost({ exec: fakeExec().exec, rootDir: await makeRoot() });
     expect(host.capabilities).toMatchObject({
-      hostKind: 'inline',
+      hostKind: 'local',
       clone: true,
       filesystem: true,
       exec: true,
@@ -58,7 +58,7 @@ describe('InlineHost (primitive Host implementation)', () => {
 
   it('provisions a full checkout (clone + checkout) and exposes the filesystem', async () => {
     const { exec, calls } = fakeExec();
-    const host = new InlineHost({ exec, rootDir: await makeRoot() });
+    const host = new LocalHost({ exec, rootDir: await makeRoot() });
     const ws = await host.provisionRepository({
       repositoryFullName: 'engineeredsoftware/demo',
       url: 'https://github.com/engineeredsoftware/demo.git',
@@ -79,7 +79,7 @@ describe('InlineHost (primitive Host implementation)', () => {
   });
 
   it('readFile refuses path traversal outside the checkout', async () => {
-    const host = new InlineHost({ exec: fakeExec().exec, rootDir: await makeRoot() });
+    const host = new LocalHost({ exec: fakeExec().exec, rootDir: await makeRoot() });
     const ws = await host.provisionRepository({
       repositoryFullName: 'o/r',
       url: 'https://github.com/o/r.git',
@@ -89,7 +89,7 @@ describe('InlineHost (primitive Host implementation)', () => {
   });
 
   it('readWorkspaceSources reads full content (all, subset, and bounded)', async () => {
-    const host = new InlineHost({ exec: fakeExec().exec, rootDir: await makeRoot() });
+    const host = new LocalHost({ exec: fakeExec().exec, rootDir: await makeRoot() });
     const ws = await host.provisionRepository({
       repositoryFullName: 'o/r',
       url: 'https://github.com/o/r.git',
@@ -115,15 +115,15 @@ describe('InlineHost (primitive Host implementation)', () => {
       const url = args[args.length - 2] ?? '';
       return { exitCode: 128, stdout: '', stderr: `fatal: could not read from ${url}` };
     };
-    const host = new InlineHost({ exec: failingExec, rootDir: await makeRoot() });
+    const host = new LocalHost({ exec: failingExec, rootDir: await makeRoot() });
     await expect(
       host.provisionRepository({
         repositoryFullName: 'o/r',
         url: 'https://github.com/o/r.git',
         revision: 'main',
         password: 'ghs_secrettoken',
       }),
-    ).rejects.toThrow(/InlineHost git clone failed/);
+    ).rejects.toThrow(/LocalHost git clone failed/);
 
     const cloneCall = calls.find((c) => c[1] === 'clone')!;
     const urlArg = cloneCall[2];