V48 (specification-implementation): Hierarchy-encoded Pipeline type names

Enforce naming that always expresses full inheritance ancestry:
Pipeline → SDIVFPipeline → SynthesizeAssetPacksSDIVFPipeline. Rename factories
and types accordingly (factorySDIVFPipelineFromExecutors,
factorySynthesizeAssetPacksSDIVFPipeline, …) with deprecated short aliases for
compatibility. Document the law in FAMILIARIZATION, SOURCE_LAYOUT, and V48 notes.

Author: geraldarthurdavis

BITCODE_SPEC_V48_NOTES.md

@@ -1550,3 +1550,21 @@ Those failsafe types now live with failsafes.
 Physical move of `createFailsafeGenerationSequence` / Thinkings factories out of
 agent-generics remains gated on inverting AgentExecution LLM coupling.
 
+## Pipeline hierarchy naming law (Garrett, 2026-07-13)
+
+Type and factory names must always express full inheritance ancestry:
+
+```
+Pipeline                              # primitive
+SDIVFPipeline                         # base + primitive
+SynthesizeAssetPacksSDIVFPipeline     # specific + base + primitive
+```
+
+Canonical factories:
+- `factoryPipeline` → `Pipeline`
+- `factorySDIVFPipeline` / `factorySDIVFPipelineFromExecutors` → `SDIVFPipeline`
+- `factorySynthesizeAssetPacksSDIVFPipeline` → `SynthesizeAssetPacksSDIVFPipeline`
+
+Short aliases (`factorySDIVFExecutorPipeline`, `synthesizeAssetPacksPipeline`,
+`runSDIVFPipeline`) are deprecated compatibility shims only.
+

FAMILIARIZATION.md

@@ -164,13 +164,22 @@ pipeline-local tools            e.g. AssetPackLexicalDepositorySearchTool
 
 ### 3.3 Pipelines
 
+**Hierarchy naming law:** names always encode full ancestry
+(specific → base → primitive), never a leaf-only label.
+
+| Layer | Type name | Factory (examples) |
+| --- | --- | --- |
+| Primitive | `Pipeline` | `factoryPipeline` |
+| Base + primitive | `SDIVFPipeline` | `factorySDIVFPipeline`, `factorySDIVFPipelineFromExecutors` |
+| Specific + base + primitive | `SynthesizeAssetPacksSDIVFPipeline` | `factorySynthesizeAssetPacksSDIVFPipeline` |
+
 ```
-@bitcode/pipelines-generics              Pipeline, PhaseDelegator, composition, streaming
+@bitcode/pipelines-generics              Pipeline primitive
         ↑
-@bitcode/generic-pipelines-sdivf         SDIVF *base* loop (Setup-[DIV]*-Finish)
+@bitcode/generic-pipelines-sdivf         SDIVFPipeline base (Setup-[DIV]*-Finish)
         ↑
-@bitcode/pipeline-asset-pack             SynthesizeAssetPacks (deposit | read);
-                                         future SettleAssetPacks extends SDIVF base
+@bitcode/pipeline-asset-pack             SynthesizeAssetPacksSDIVFPipeline (deposit | read);
+                                         future SettleAssetPacksSDIVFPipeline
 @bitcode/pipeline-hosts                  Inline host + Vercel Sandbox harness
 ```
 
@@ -182,6 +191,9 @@ Product pipelines supply phase executors/agents; they do not reimplement the DIV
 `pipelines-generics` re-exports SDIVF for compatibility — prefer importing
 `@bitcode/generic-pipelines-sdivf` in new code.
 
+Deprecated short aliases (`synthesizeAssetPacksPipeline`, `factorySDIVFExecutorPipeline`,
+`runSDIVFPipeline`, …) remain for BC; new code uses hierarchy-encoded names.
+
 Product UI says **Pipeline**. Low-level packages may still say `execution` /
 `Execution` — do **not** rename `execution-generics` blindly.
 

internal-docs/BITCODE_SOURCE_LAYOUT.md

@@ -174,6 +174,21 @@ uapi/components/bitcode/
 Packages hold **framework-agnostic** domain logic. Prefer existing packages;
 add new packages when a domain is clearly shared and non-UI.
 
+### 6.0 Hierarchy naming law (required)
+
+Type, factory, and export names **always encode full inheritance ancestry**:
+
+```
+Pipeline                              # primitive
+SDIVFPipeline                         # base + primitive
+SynthesizeAssetPacksSDIVFPipeline     # specific + base + primitive
+```
+
+Do not introduce leaf-only names for layered types (e.g. avoid a product
+pipeline named only `AssetPackPipeline` when it is an `…SDIVFPipeline`).
+Deprecated short aliases may exist for compatibility; new code uses the
+full hierarchy name.
+
 ### 6.1 Nested `generic-*` families (required)
 
 Every `packages/generic-*` path is a **family folder**, not a single package.
@@ -191,7 +206,7 @@ packages/generic-<family>/          # README only (no package.json)
 | --- | --- | --- |
 | `generic-agents/` | `vcs/`, `danger-wall/`, … | `@bitcode/generic-agents-*` |
 | `generic-tools/` | `web-search/`, `vcs/`, … | `@bitcode/generic-tools-*` |
-| `generic-pipelines/` | `SDIVF/` | `@bitcode/generic-pipelines-sdivf` |
+| `generic-pipelines/` | `SDIVF/` | `@bitcode/generic-pipelines-sdivf` (`SDIVFPipeline`) |
 | `generic-llms/` | `xAI/`, `OpenAI/`, `Anthropic/`, `Google/`, `defaults/`, `registry/` | `@bitcode/generic-llms-*` (+ aggregator `@bitcode/generic-llms`) |
 | `generic-generations/` | `failsafes/`, `thinkings/` | `@bitcode/generic-generations-failsafes`, `-thinkings` |
 | `generic-doc-comment-plugins/` | `doc-developing/` | `@bitcode/doc-comment-developing` |

packages/agent-generics/src/steps/thinkings-generation.ts

@@ -11,6 +11,11 @@ import { sequential, type Executor } from '@bitcode/execution-generics';
 import { z } from 'zod';
 import { factoryReason, factoryJudge, factoryStructuredOutput } from '../substeps/factories';
 
+/**
+ * Thinkings + Generation hierarchy name (base Thinkings composition of the
+ * Generation primitive). Prefer hierarchy-encoded names for product extensions
+ * (e.g. MeasureAbsolutesThinkingsGeneration) when introducing specialized bases.
+ */
 export type ThinkingsGeneration<TIn = any, TOut = any> = Executor<TIn, TOut>;
 
 export function createThinkingsGeneration<TIn, TOut>(outputSchema: z.ZodType<TOut>): ThinkingsGeneration<TIn, TOut> {

packages/executions-mcp/src/mcp-server/src/__tests__/setup/mcpTestSetup.ts

@@ -382,6 +382,20 @@ jest.mock('@bitcode/pipelines-generics', () => ({
       success: true
     }))
   ),
+  factorySDIVFPipelineFromExecutors: jest.fn().mockImplementation((_name: string, config: any) =>
+    jest.fn().mockImplementation(async (input: any, execution: any) => {
+      let current = input;
+      if (config?.preprocess) current = await config.preprocess(current, execution);
+      if (config?.setup) current = await config.setup(current, execution);
+      if (config?.discovery) current = await config.discovery(current, execution);
+      if (config?.implementation) current = await config.implementation(current, execution);
+      if (config?.validation) current = await config.validation(current, execution);
+      if (config?.finish) current = await config.finish(current, execution);
+      if (config?.postprocess) current = await config.postprocess(current, execution);
+      return current;
+    })
+  ),
+  // @deprecated alias of factorySDIVFPipelineFromExecutors
   factorySDIVFExecutorPipeline: jest.fn().mockImplementation((_name: string, config: any) =>
     jest.fn().mockImplementation(async (input: any, execution: any) => {
       let current = input;

packages/generic-pipelines/README.md

@@ -2,23 +2,35 @@
 
 Base pipeline implementations that extend `@bitcode/pipelines-generics` primitives.
 
-## Hierarchy
+## Hierarchy (names encode full ancestry)
 
 ```
-@bitcode/pipelines-generics          # Pipeline / PhaseDelegator / composition primitives
+Pipeline                                    # primitive (@bitcode/pipelines-generics)
         ↑
-@bitcode/generic-pipelines-sdivf     # SDIVF base loop (this folder: SDIVF/)
+SDIVFPipeline                               # base + primitive (@bitcode/generic-pipelines-sdivf)
         ↑
-@bitcode/pipeline-asset-pack         # SynthesizeAssetPacks (and future SettleAssetPacks)
+SynthesizeAssetPacksSDIVFPipeline           # specific + base + primitive (pipeline-asset-pack)
+SettleAssetPacksSDIVFPipeline               # future product
+```
+
+```
+@bitcode/pipelines-generics          # factoryPipeline → Pipeline
+        ↑
+@bitcode/generic-pipelines-sdivf     # factorySDIVFPipeline / FromExecutors → SDIVFPipeline
+        ↑
+@bitcode/pipeline-asset-pack         # factorySynthesizeAssetPacksSDIVFPipeline
 ```
 
 ## Packages
 
 | Path | Package name | Role |
 | --- | --- | --- |
-| `SDIVF/` | `@bitcode/generic-pipelines-sdivf` | Setup-[Discovery-Implementation-Validation]*-Finish base |
+| `SDIVF/` | `@bitcode/generic-pipelines-sdivf` | `SDIVFPipeline` base (Setup-[DIV]*-Finish) |
 
 Product pipelines supply phase agents/executors; they do not reimplement the DIV loop.
+**Naming law:** every type/factory name must express the full inheritance chain
+(e.g. never call a product pipeline merely `AssetPackPipeline` when it is an
+`…SDIVFPipeline`).
 
 ## Nested-package pattern
 

packages/generic-pipelines/SDIVF/src/__tests__/sdivf-executor-loop.test.ts

@@ -1,6 +1,6 @@
 // @ts-nocheck
 /**
- * factorySDIVFExecutorPipeline semantics (V48 Gate 3).
+ * factorySDIVFPipelineFromExecutors semantics (V48 Gate 3).
  *
  * This is the SDIVF variant the SynthesizeAssetPacks pipeline actually runs
  * (packages/pipelines/asset-pack/src/index.ts) — NOT factorySDIVFPipeline,
@@ -28,7 +28,7 @@
  * (finalApproval/passed false), so the exact-iteration-count pins exercise the
  * bounded (max-iterations) side of the gate.
  */
-import { factorySDIVFExecutorPipeline } from '../index';
+import { factorySDIVFPipelineFromExecutors } from '../index';
 import { Execution } from '@bitcode/execution-generics/Execution';
 
 type Recorded = { calls: string[]; inputs: Record<string, any[]>; nodes: Record<string, string[]> };
@@ -66,10 +66,10 @@ function buildConfig(recorded: Recorded, overrides: Record<string, any> = {}) {
   };
 }
 
-describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
+describe('factorySDIVFPipelineFromExecutors (executor-variant SDIVF loop)', () => {
   it('runs preprocess → setup → (D→I→V) × maxIterations → finish → postprocess in order', async () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-loop-order', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-loop-order', {
       ...buildConfig(recorded),
       maxIterations: 2,
     });
@@ -94,7 +94,7 @@ describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
 
   it('never exceeds maxIterations (single-iteration loop)', async () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-loop-single', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-loop-single', {
       ...buildConfig(recorded),
       maxIterations: 1,
     });
@@ -109,7 +109,7 @@ describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
 
   it('exits the DIV loop early when the validation RESULT signals ready-to-finish', async () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-gate-result', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-gate-result', {
       ...buildConfig(recorded, {
         validation: async (input: any, exec: any) => {
           record(recorded, 'validation', input, exec);
@@ -135,7 +135,7 @@ describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
   it('exits the DIV loop early via the cross-phase validation:readyToFinish artifact on the ROOT', async () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
     const root = new Execution('root-gate-artifact');
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-gate-artifact', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-gate-artifact', {
       ...buildConfig(recorded, {
         validation: async (input: any, exec: any) => {
           record(recorded, 'validation', input, exec);
@@ -163,7 +163,7 @@ describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
   it('honors a cfg.readyToFinish override as the gate', async () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
     const gateCalls: any[] = [];
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-gate-override', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-gate-override', {
       ...buildConfig(recorded),
       readyToFinish: async (result: any) => {
         gateCalls.push(result);
@@ -186,7 +186,7 @@ describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
   it('records loop observability: per-iteration pass flags and the max-iterations marker', async () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
     const root = new Execution('root-gate-observe');
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-gate-observe', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-gate-observe', {
       ...buildConfig(recorded),
       maxIterations: 2,
     });
@@ -203,7 +203,7 @@ describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
 
   it('threads each phase output into the next phase input', async () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-threading', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-threading', {
       ...buildConfig(recorded),
       maxIterations: 2,
     });
@@ -230,7 +230,7 @@ describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
 
   it('runs iterationPreprocess before each Discovery and threads its return into the loop', async () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-iterpre', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-iterpre', {
       ...buildConfig(recorded),
       iterationPreprocess: async (input: any, exec: any) => {
         record(recorded, 'iterationPreprocess', input, exec);
@@ -257,7 +257,7 @@ describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
     const seen: Record<string, any> = {};
     const root = new Execution('root-topology');
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-topology', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-topology', {
       ...buildConfig(recorded, {
         setup: async (input: any, exec: any) => {
           record(recorded, 'setup', input, exec);
@@ -297,7 +297,7 @@ describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
   it('stores phase start/complete observability with iteration numbers', async () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
     const root = new Execution('root-observe');
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-observe', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-observe', {
       ...buildConfig(recorded),
       maxIterations: 2,
     });
@@ -325,7 +325,7 @@ describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
   it('fails closed: a throwing implementation rejects the pipeline and stops downstream phases', async () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
     const root = new Execution('root-fail');
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-fail', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-fail', {
       ...buildConfig(recorded, {
         implementation: async (input: any, exec: any) => {
           record(recorded, 'implementation', input, exec);
@@ -354,7 +354,7 @@ describe('factorySDIVFExecutorPipeline (executor-variant SDIVF loop)', () => {
 
   it('fails closed on a throwing setup: the DIV loop and finish never start', async () => {
     const recorded: Recorded = { calls: [], inputs: {}, nodes: {} };
-    const pipeline = factorySDIVFExecutorPipeline('sdivf-fail-setup', {
+    const pipeline = factorySDIVFPipelineFromExecutors('sdivf-fail-setup', {
       ...buildConfig(recorded, {
         setup: async (input: any, exec: any) => {
           record(recorded, 'setup', input, exec);

packages/generic-pipelines/SDIVF/src/index.ts

@@ -1,19 +1,31 @@
 /**
  * @bitcode/generic-pipelines-sdivf
  *
- * Base SDIVF Pipeline implementation extending pipelines-generics primitives.
- * Product pipelines (SynthesizeAssetPacks, future SettleAssetPacks) extend this
- * base rather than reimplementing the Setup-[DIV]*-Finish loop.
+ * Base SDIVFPipeline (hierarchy: SDIVF + Pipeline primitive).
+ * Product pipelines name themselves as Specific+SDIVF+Pipeline, e.g.
+ * SynthesizeAssetPacksSDIVFPipeline — they do not reimplement the DIV loop.
  */
 
+export type { SDIVFPipeline } from './sdivf-factory';
+
 export {
   factorySDIVFPipeline,
+  factorySDIVFPipelineFromExecutors,
+  /** @deprecated Use factorySDIVFPipelineFromExecutors */
   factorySDIVFExecutorPipeline,
+  type SDIVFPipelineConfig,
+  type SDIVFPipelineExecutorConfig,
+  /** @deprecated Use SDIVFPipelineConfig */
   type SDIVFConfig,
+  /** @deprecated Use SDIVFPipelineExecutorConfig */
   type SDIVFExecutorConfig,
 } from './sdivf-factory';
 
 export {
+  SDIVFPipelinePhase,
+  factorySDIVFPipelinePhaseDelegators,
+  /** @deprecated Use SDIVFPipelinePhase */
   SDIVFPhase,
+  /** @deprecated Use factorySDIVFPipelinePhaseDelegators */
   factorySDIVFPhaseDelegators,
 } from './sdivf-phases';