V48 (specification-implementation): Generation hierarchy; failsafe context types leave context/

Audit @bitcode/context: prepared-context types belong with failsafes, not a
process-global bag. Establish generation-generics primitives and nested
generic-generations/{failsafes,thinkings}. Move PreparedContext helpers into
failsafes; leave GlobalContext (+ BC re-exports) in context. agent-generics
composes bases; AssetPack synthesis documents product extension without
reimplementing failsafe/thinkings. LLM-bound factories remain in agent-generics
until AgentExecution coupling is inverted.

Author: geraldarthurdavis

BITCODE_SPEC_V48_NOTES.md

@@ -1531,3 +1531,22 @@ Pipeline inheritance hierarchy is now explicit:
 `factorySDIVFExecutorPipeline` / `factorySDIVFPipeline` / `SDIVFPhase` live in
 `@bitcode/generic-pipelines-sdivf`. AssetPack imports the base package directly.
 `pipelines-generics` re-exports for compatibility.
+
+## Generation hierarchy + context/failsafes audit (Garrett, 2026-07-13)
+
+Audit: `@bitcode/context` mixed process-global `GlobalContext` with failsafe
+prepared-context types (`PreparedContext`, `prepareConciseContext`, chunking).
+Those failsafe types now live with failsafes.
+
+```
+@bitcode/generation-generics
+  → @bitcode/generic-generations-failsafes   # packages/generic-generations/failsafes
+  → @bitcode/generic-generations-thinkings   # packages/generic-generations/thinkings
+    → @bitcode/agent-generics                # PTRR agents; still hosts LLM-bound factories
+      → @bitcode/pipeline-asset-pack         # product uses bases; does not reimplement
+```
+
+`@bitcode/context` keeps only `GlobalContext` (+ BC re-exports of failsafe helpers).
+Physical move of `createFailsafeGenerationSequence` / Thinkings factories out of
+agent-generics remains gated on inverting AgentExecution LLM coupling.
+

FAMILIARIZATION.md

@@ -111,13 +111,28 @@ uapi                               →  HTTP + React adapters only
 ```
 @bitcode/execution-generics     Execution + Executor (lowest runtime primitive)
         ↑
-@bitcode/agent-generics         Agent : Executor, PTRR steps, failsafes, Thinkings
+@bitcode/agent-generics         Agent : Executor, PTRR steps over generations
         ↑
 @bitcode/generic-agents/*       Base agents (VCS, danger-wall, code-editor, …)
         ↑
 @bitcode/pipeline-asset-pack    Deposit/read SDIVF agents (setup/discovery/…)
 ```
 
+### 3.1.1 Generations (failsafes + thinkings)
+
+```
+@bitcode/generation-generics              Generation type + failsafe/thinkings enums
+        ↑
+@bitcode/generic-generations-failsafes    failsafes/ — prepared-context types + base
+@bitcode/generic-generations-thinkings    thinkings/ — Reason→Judge→StructuredOutput base
+        ↑
+@bitcode/agent-generics                   composes failsafes/thinkings into PTRR Agents
+        ↑
+@bitcode/pipeline-asset-pack              product synthesis / phase agents (no reimplementation)
+```
+
+Package path: `packages/generic-generations/{failsafes,thinkings}/`.
+
 **PTRR** (Plan / Try / Refine / Retry) is the agent step model. Each step runs a
 **Failsafes** sequence:
 
@@ -127,6 +142,14 @@ uapi                               →  HTTP + React adapters only
 
 Each failsafe’s generation is **Thinkings**: Reason → Judge → StructuredOutput.
 
+Prepared-context types (`PreparedContext`, `prepareConciseContext`, …) live with
+**failsafes** (`@bitcode/generic-generations-failsafes`), not a free-floating
+context domain. `@bitcode/context` retains only process-global `GlobalContext`
+(+ BC re-exports of failsafe prepared-context helpers).
+
+LLM-bound failsafe/thinkings **factories** still execute via `AgentExecution`
+inside `agent-generics` until inverted onto pure Execution + LLM registry.
+
 Factories: `factoryAgent`, `factoryAgentWithPTRR` in `agent-generics`.
 
 ### 3.2 Tools
@@ -239,14 +262,17 @@ Grouped by role. Names are `@bitcode/<name>` unless noted.
 | Package | Responsibility |
 | --- | --- |
 | `execution-generics` | `Execution` state tree, `Executor`, sequential/parallel/pipe |
-| `agent-generics` | Agent = Executor + PTRR + failsafes + generations |
+| `agent-generics` | Agent = Executor + PTRR composition over generations |
 | `tools-generics` | `Tool` class, factories, MCP bridges |
 | `pipelines-generics` | Pipeline / PhaseDelegator primitives / stream hooks (re-exports SDIVF) |
 | `generic-pipelines-sdivf` | SDIVF base loop (`packages/generic-pipelines/SDIVF`) |
+| `generation-generics` | Generation primitive + failsafe/thinkings enums |
+| `generic-generations-failsafes` | Failsafe base + prepared-context types |
+| `generic-generations-thinkings` | Thinkings base vocabulary surface |
 | `llm-generics` | Pure LLM call contracts |
 | `registry` | Hierarchical registry (Prompt is a Registry) |
 | `prompts` | Prompt + PromptPart + **all** raw prompt parts |
-| `context` | Prepared context types for failsafes |
+| `context` | Process-global `GlobalContext` only (failsafe context → failsafes package) |
 | `logger` | Shared logging |
 
 ### 5.2 Generic implementations
@@ -257,6 +283,7 @@ Grouped by role. Names are `@bitcode/<name>` unless noted.
 | `generic-tools/*` | Nested base tools: editing, git, VCS, LSP, web-search, repository-setup, … |
 | `generic-pipelines/*` | Nested base pipelines: SDIVF, … |
 | `generic-llms/*` | Nested providers (xAI, OpenAI, Anthropic, Google), defaults, registry aggregator |
+| `generic-generations/*` | Nested generation bases: failsafes, thinkings |
 | `generic-doc-comment-plugins/*` | Nested doc-comment plugins |
 
 ### 5.3 Product domain (AssetPack / BTD / market)

internal-docs/BITCODE_SOURCE_LAYOUT.md

@@ -193,6 +193,7 @@ packages/generic-<family>/          # README only (no package.json)
 | `generic-tools/` | `web-search/`, `vcs/`, … | `@bitcode/generic-tools-*` |
 | `generic-pipelines/` | `SDIVF/` | `@bitcode/generic-pipelines-sdivf` |
 | `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` |
 
 **Do not** put a root `package.json` on the family folder. Workspace globs are
@@ -285,6 +286,10 @@ bitcode/
 │   │   ├── Google/                    # @bitcode/generic-llms-google
 │   │   ├── defaults/                  # @bitcode/generic-llms-defaults
 │   │   └── registry/                  # @bitcode/generic-llms (aggregator)
+│   ├── generation-generics/           # Generation primitive vocabulary
+│   ├── generic-generations/
+│   │   ├── failsafes/                 # @bitcode/generic-generations-failsafes
+│   │   └── thinkings/                 # @bitcode/generic-generations-thinkings
 │   ├── pipelines/
 │   │   └── asset-pack/                # SynthesizeAssetPacks (extends SDIVF)
 │   ├── agent-generics/

package.json

@@ -13,6 +13,7 @@
     "packages/generic-agents/*",
     "packages/generic-pipelines/*",
     "packages/generic-llms/*",
+    "packages/generic-generations/*",
     "packages/generic-doc-comment-plugins/*",
     "packages/pipelines/*",
     "uapi",

packages/agent-generics/jest.config.cjs

@@ -8,6 +8,9 @@ module.exports = {
     '^@bitcode/pipelines-generics$': '<rootDir>/../pipelines-generics/src/index.ts',
     '^@bitcode/pipelines-generics/(.*)$': '<rootDir>/../pipelines-generics/src/$1',
     // nested generic-llms family (not packages/generic-llms/src)
+    '^@bitcode/generation-generics$': '<rootDir>/../generation-generics/src/index.ts',
+    '^@bitcode/generic-generations-failsafes$': '<rootDir>/../generic-generations/failsafes/src/index.ts',
+    '^@bitcode/generic-generations-thinkings$': '<rootDir>/../generic-generations/thinkings/src/index.ts',
     '^@bitcode/generic-llms$': '<rootDir>/../generic-llms/registry/src/index.ts',
     '^@bitcode/generic-llms/defaults$': '<rootDir>/../generic-llms/defaults/src/index.ts',
     '^@bitcode/generic-llms-defaults$': '<rootDir>/../generic-llms/defaults/src/index.ts',

packages/agent-generics/package.json

@@ -13,6 +13,9 @@
   },
   "dependencies": {
     "@bitcode/execution-generics": "workspace:*",
+    "@bitcode/generation-generics": "workspace:*",
+    "@bitcode/generic-generations-failsafes": "workspace:*",
+    "@bitcode/generic-generations-thinkings": "workspace:*",
     "@bitcode/generic-llms": "workspace:*",
     "@bitcode/prompts": "workspace:*",
     "@bitcode/tools-generics": "workspace:*",

packages/agent-generics/src/index.ts

@@ -1,33 +1,52 @@
 /**
- * AGENT-GENERICS - Retained agent orchestration primitives
+ * AGENT-GENERICS - Agent orchestration over generation bases
  *
- * Agents are Executors that sequence retained PTRR-style steps.
- * This package survives as reusable orchestration infrastructure and as a
- * reference surface for Bitcode-native pipelines; it is not itself proof that
- * the old agent families remain live Bitcode canon.
+ * Hierarchy:
+ *   generation-generics → generic-generations/{failsafes,thinkings}
+ *     → agent-generics (this package: Agent + PTRR composition)
+ *     → product (pipeline-asset-pack agents / synthesis)
+ *
+ * Agents are Executors that sequence PTRR-style steps. Each step runs 3 failsafe
+ * parents (PrepareConciseContext → ChunkThenSum → StitchUntilComplete), each
+ * driving Thinkings (Reason → Judge → StructuredOutput). Tools run after failsafes.
+ *
+ * Generation vocabulary: @bitcode/generation-generics
+ * Failsafe prepared-context types: @bitcode/generic-generations-failsafes
+ * LLM-bound failsafe/thinkings factories still hosted here until AgentExecution
+ * coupling is inverted into pure Execution + LLM registry.
  *
- * Different agent implementations are selected from registries dynamically.
- * Each step runs 3 failsafe parents sequentially, each running 3 generation children.
- * Tools execute AFTER all failsafes complete (conditional on reasoning + judgment output).
- * 
- * Key Abstractions:
- * - Agent: Executor that sequences PTRR steps
- * - Step: StepExecutor that sequences 7 SubSteps
- * - SubStep: The atomic operations (3 failsafes + 3 generation + 1 tool)
- * 
  * @doc-package
  * version: 1.0.0
  * pattern: ptrr-orchestration
- * philosophy: "Retained orchestration families remain reusable, but Bitcode decides which ones are admitted as live product behavior"
+ * philosophy: "Agents compose generic generations; product specializes agents"
  */
 
 // ==================== CORE TYPES ====================
 
+// Generation vocabulary (prefer direct import from generation-generics)
+export {
+  FailsafeMetaSubStep,
+  GenerationSubMetaSubStep,
+  type Generation,
+} from '@bitcode/generation-generics';
+
+// Failsafe prepared-context types (prefer generic-generations-failsafes)
+export type {
+  PreparedContext,
+  ContextSelector,
+  PrepareConciseContextOptions,
+  PrepareConciseContextResult,
+} from '@bitcode/generic-generations-failsafes';
+export {
+  estimateSerializedSize,
+  createContextSelectors,
+  chunkContext,
+  prepareConciseContext,
+} from '@bitcode/generic-generations-failsafes';
+
 // Agent enums and types
 export {
   AgentVariationStep,
-  FailsafeMetaSubStep,
-  GenerationSubMetaSubStep
 } from './types';
 
 // Agent interfaces
@@ -37,7 +56,6 @@ export type {
   AgentGeneration,
   QuickAgent,
   StepExecutor,
-  PreparedContext,
   Chunk,
   Reasoning,
   UseTool,

packages/agent-generics/src/steps/failsafe-sequence.ts

@@ -1,22 +1,18 @@
 /**
- * FailsafeGenerationSequence - Canonical failsafes sequence builder
+ * FailsafeGenerationSequence - canonical failsafe base composition.
  *
- * Formalizes the default step generation as THREE failsafes in fixed order,
- * each with a DISTINCT trigger and a DISTINCT job:
+ * Logical home: @bitcode/generic-generations-failsafes.
+ * Hosted in agent-generics while failsafe factories still require
+ * AgentExecution registries. Prepared-context pure types live in
+ * @bitcode/generic-generations-failsafes; vocabulary in
+ * @bitcode/generation-generics.
  *
- * 1. PrepareConciseContext (context failsafe; ALWAYS runs; selection-only):
- *    ONE selection Thinkings against the key-selection schema over the
- *    keys-only root execution state, then the value read-in of exactly the
- *    selected keys.
- * 2. ChunkThenSum (input failsafe; trigger = composed request exceeds the
- *    request limit): ONE task Thinkings when the request fits; per-chunk task
- *    generations + one summing pass when it does not.
- * 3. StitchUntilComplete (output failsafe; trigger = schema-INCOMPLETE or
- *    truncated): repair-only, error-carrying stitch generations, bounded.
+ * THREE failsafes in fixed order, each with a DISTINCT trigger and job:
+ * 1. PrepareConciseContext — selection-only key Thinkings + value read-in
+ * 2. ChunkThenSum — task Thinkings once or per-chunk + sum
+ * 3. StitchUntilComplete — repair-only on incomplete/truncated output
  *
- * The sequence is selection -> task(xchunks) -> repair-only; the failsafes do
- * NOT wrap three identical task generations. Tools execution is a Step-level
- * postprocess and is composed by step factories after this core.
+ * Sequence: selection → task(×chunks) → repair-only. Tools are step postprocess.
  */
 
 import { sequential, type Executor } from '@bitcode/execution-generics';

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

@@ -1,9 +1,10 @@
 /**
- * ThinkingsGeneration - A single Generation composed of three child LLM calls
- * in strict order: Reason → Judge → StructuredOutput.
+ * ThinkingsGeneration - Reason → Judge → StructuredOutput.
  *
- * This is the atomic typed "Generation" used by steps. Failsafe wrappers
- * (PTRR-specific) can execute this generation under different parents.
+ * Logical home: @bitcode/generic-generations-thinkings (base Thinkings).
+ * Hosted here while factoryReason/Judge/StructuredOutput still depend on
+ * AgentExecution LLM registries. Product code should treat this as the
+ * generic-generations Thinkings base, not a product-local helper.
  */
 
 import { sequential, type Executor } from '@bitcode/execution-generics';

packages/agent-generics/src/substeps/factories.ts

@@ -56,7 +56,7 @@ import { PROMPTPART_GENERIC_AGENT_GENERATION_TOP_LEVEL_KEYS_HINT } from '@bitcod
  *    truncated output): error-carrying repair generations, bounded.
  */
 
-import { estimateSerializedSize } from '@bitcode/context';
+import { estimateSerializedSize } from '@bitcode/generic-generations-failsafes';
 import {
   sequential,
   parallel,