{
  "id": "page:docs-genty-decoupling-coupling-audit",
  "_kind": "Page",
  "_file": "wiki/docs/genty-decoupling/coupling-audit.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/genty-decoupling/coupling-audit.md",
    "sourceKind": "repo-docs",
    "title": "Genty Babysitter-SDK Coupling Audit",
    "displayName": "Genty Babysitter-SDK Coupling Audit",
    "slug": "docs/genty-decoupling/coupling-audit",
    "articlePath": "wiki/docs/genty-decoupling/coupling-audit.md",
    "article": "\n# Genty Babysitter-SDK Coupling Audit\n\nGenerated: 2026-06-07\n\n## Summary\n\n| Category | Imports | Classification |\n|---|---|---|\n| run-lifecycle | 57 | must-extract |\n| types-only | 72 | should-internalize |\n| harness-registry | 21 | can-keep |\n| utilities | 22 | should-internalize |\n| effect-orchestration | 17 | must-extract |\n| process-creation | 13 | must-extract |\n| journal | 5 | must-extract |\n| governance | 5 | must-extract |\n| session | 5 | must-extract |\n| external-agents | 2 | must-extract |\n| **Total** | **219** | |\n\n**68 files** across **5 packages** import from `@a5c-ai/babysitter-sdk`.\n\n## Imports by Package\n\n| Package | Files | Imports |\n|---|---|---|\n| platform | 57 | 185 |\n| cli | 9 | 22 |\n| runtime | 8 | 10 |\n| core | 1 | 2 |\n| tui-plugins | 0 | 0 |\n\n## Classification Detail\n\n### must-extract (104 imports, 47.5%)\n\nThese categories represent core babysitter runtime functionality that genty uses\ndirectly. To decouple, these must be extracted into a shared interface layer or\nabsorbed into genty's own runtime abstractions.\n\n- **run-lifecycle (57)**: `createRun`, `loadJournal`, `readRunMetadata`,\n  `resolveRunsDir`, `resolveExistingRunDir`, `DEFAULTS`, `createRunDir`,\n  `readStateCache`, `readTaskDefinition`, `readTaskResult`,\n  `serializeAndWriteTaskResult`, `withRunLock`, `callHook`,\n  `loadCompressionConfig`, `createScopedRuntimeConfigState`,\n  `createReplayEngine`, `createProcessContext`, `withProcessContext`,\n  `getActiveProcessContext`, `requireProcessContext`,\n  `STATE_CACHE_SCHEMA_VERSION`, `createStateCacheSnapshot`,\n  `journalHeadsEqual`, `normalizeJournalHead`, `normalizeSnapshot`,\n  `rebuildStateCache`, `writeStateCache`, `hashInvocationKey`,\n  `RunFailedError`, `replaySchemaVersion`, `createBabysitterMcpServer`,\n  `getRunDir`\n\n- **effect-orchestration (17)**: `commitEffectResult`, `orchestrateIteration`,\n  `buildEffectIndex`, `getEffectiveConcurrency`, `commitEffectCancellation`,\n  `EffectRequestedError`, `EffectPendingError`, `EffectCancelledError`,\n  `ParallelPendingError`\n\n- **process-creation (13)**: `createPromptContextFromCatalog`,\n  `composeProcessCreatePrompt`, `resolveActiveProcessLibrary`,\n  `getDefaultProcessLibrarySpec`, `renderBreakpointHandling`,\n  `renderResultsPosting`, `renderCommandTemplate`, `renderTemplateString`,\n  `resetGlobalTaskRegistry`\n\n- **journal (5)**: `appendEvent` (used in 3 files across platform and runtime)\n\n- **governance (5)**: `addRule`, `readRules`, `removeRule`,\n  `evaluateAutoApproval`, `isStatefulRule`\n\n- **session (5)**: `resolveSessionIdWithMarker`, `getSessionMarkerPath`,\n  `readSessionMarker`, `normalizeSessionStateDir`\n\n- **external-agents (2)**: `discoverExternalAgents` (used in 2 files)\n\n### can-keep (21 imports, 9.6%)\n\nHarness-registry symbols are native to genty's adapter layer.\nThese re-exports and direct usages are the intended integration surface\nbetween genty and the SDK.\n\n- **harness-registry (21)**: `discoverHarnesses`, `detectCallerHarness`,\n  `checkCliAvailable`, `KNOWN_HARNESSES`, `detectAdapter`,\n  `getAdapterByName`, `listSupportedHarnesses`, `getAdapter`, `setAdapter`,\n  `resetAdapter`, `createClaudeCodeAdapter`, `createInternalContext`\n\n### should-internalize (94 imports, 42.9%)\n\nTypes and utility functions that should be copied or re-declared within genty\nto eliminate the import dependency. Most are simple type re-exports or\nstandalone helper functions with no state.\n\n- **types-only (72)**: `JournalEvent`, `JsonRecord`, `EffectAction`,\n  `IterationResult`, `BreakpointRule`, `BreakpointConfig`,\n  `AutoApprovalResult`, `ActionCategory`, `ApprovalPosture`,\n  `InteractionKind`, `PromptContext`, `CompressionConfig`,\n  `EffectIndex`, `AppendEventResult`, `ExternalAgentDiscovery`,\n  `ExternalAgentInfo`, `ParsedArgs`, `RuntimeConfigValueType`,\n  `PolicyRuleKind`, `PolicyConditionOp`, `PolicyAction`, `PolicyCondition`,\n  `PolicyRule`, `StatefulPolicyRule`, `PolicyEvaluationContext`,\n  `PolicyDecision`, `PolicyDecisionLog`, `PolicyEngine`,\n  `OrchestrateOptions`, `CommitEffectResultOptions`,\n  `CommitEffectResultArtifacts`, `ProcessContext`, `DefinedTask`,\n  `CreateRunOptions`, `CreateRunResult`, `ReplayEngine`,\n  `CreateReplayEngineOptions`, `StateCacheSnapshot`,\n  `StateCacheJournalHead`, `DerivedEffectSummary`\n\n- **utilities (22)**: `BabysitterRuntimeError`, `ErrorCategory`,\n  `writeFileAtomic`, `parsePattern`, `matchPattern`, `nextUlid`,\n  `densityFilterText`, `estimateTokens`, `formatErrorWithContext`,\n  `isBabysitterError`, `suggestCommand`, `toStructuredError`,\n  `applyPositionalArgs`, `BOOLEAN_FLAGS`, `FLAG_PARSERS`,\n  `__resetCacheForTests`, `__setAncestorResolverForTests`\n\n## Top 10 Most-Coupled Files\n\n| Rank | File | Package | Symbols | Categories |\n|---|---|---|---|---|\n| 1 | `src/runtime/index.ts` | platform | 38 | run-lifecycle, effect-orchestration, types-only |\n| 2 | `src/api/breakpoints.ts` | platform | 15 | governance, journal, run-lifecycle, types-only |\n| 3 | `src/api/runs.ts` | platform | 11 | effect-orchestration, run-lifecycle, types-only |\n| 4 | `src/harness/index.ts` | platform | 10 | harness-registry |\n| 5 | `src/api/effects.ts` | platform | 8 | journal, run-lifecycle, types-only |\n| 6 | `src/harness/internal/createRun/utils.ts` | platform | 8 | harness-registry, types-only, utilities |\n| 7 | `src/harness/internal/createRun/prompts.ts` | platform | 8 | process-creation, types-only |\n| 8 | `src/harness/internal/createRun/__tests__/createRun.test.ts` | platform | 8 | effect-orchestration, harness-registry, run-lifecycle, session, types-only, utilities |\n| 9 | `src/cli/ui.ts` | cli | 6 | utilities |\n| 10 | `src/harness/internal/createRun/output.ts` | platform | 5 | harness-registry, run-lifecycle, types-only, utilities |\n\n## Observations\n\n1. **platform dominates**: 84.5% of all imports (185/219) originate in\n   `@a5c-ai/genty-platform`. Any decoupling effort should focus here first.\n\n2. **runtime/index.ts is a barrel re-export**: The single file\n   `platform/src/runtime/index.ts` re-exports 38 symbols. This is the\n   largest coupling point and a natural extraction seam -- it effectively\n   defines genty's runtime contract with the SDK.\n\n3. **types-only is the largest category**: 72 imports (32.9%) are pure type\n   imports. These are the cheapest to internalize: copy the type\n   declarations into a `@a5c-ai/genty-types` package or a shared\n   `types.ts` barrel, then drop the SDK dependency from those files.\n\n4. **Duplicate modules across platform and runtime**: Several files exist in\n   both `platform/src/` and `runtime/src/` with identical imports\n   (e.g., `cost/effectCost.ts`, `cost/journal.ts`,\n   `observability/runStatus.ts`, `observability/health.ts`,\n   `observability/timeline.ts`, `session/discovery.ts`). These duplicates\n   should be consolidated before decoupling.\n\n5. **Deep path import**: `breakpoints/delegation.ts` imports from\n   `@a5c-ai/babysitter-sdk/dist/storage/atomic` -- a private path that\n   bypasses the SDK's public API. This is fragile and should be replaced\n   with a public export or internalized.\n\n6. **tui-plugins is fully decoupled**: Zero SDK imports -- already clean.\n\n7. **core has minimal coupling**: Only 1 file with 2 imports\n   (`createScopedRuntimeConfigState` + `RuntimeConfigValueType`).\n\n8. **Governance types re-exported**: `governance/types.ts` re-exports 10\n   policy types and 1 function from the SDK. This is a clear candidate for\n   type internalization.\n\n## Notes on String Literal References\n\nThe following files contain `@a5c-ai/babysitter-sdk` as string literals in\nprompt templates or test fixtures (NOT actual imports). These are excluded\nfrom the import counts above but are relevant for full decoupling:\n\n- `planProcess/prompts.ts:108` -- prompt template for process authoring\n- `planProcess/phase.ts:99` -- inline code example in system prompt\n- `planProcess/recovery.ts:16-17` -- import path normalization regex\n- `createRun.test.ts:1651,2068,2601,2826,2855,2959` -- test fixtures\n- `externalTaskValidation.test.ts:34,62,98` -- test fixtures\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs",
      "to": "page:docs-genty-decoupling-coupling-audit",
      "kind": "contains_page"
    }
  ]
}