{
  "id": "page:docs-v6-spec-and-roadmap-v6-1-naming-alignment",
  "_kind": "Page",
  "_file": "wiki/docs/v6-spec-and-roadmap/v6-1/naming-alignment.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/v6-spec-and-roadmap/v6.1/naming-alignment.md",
    "sourceKind": "repo-docs",
    "title": "Naming Alignment — Graph Concepts vs Package Names",
    "displayName": "Naming Alignment — Graph Concepts vs Package Names",
    "slug": "docs/v6-spec-and-roadmap/v6-1/naming-alignment",
    "articlePath": "wiki/docs/v6-spec-and-roadmap/v6.1/naming-alignment.md",
    "article": "\n# Naming Alignment — Graph Concepts vs Package Names\n\nThis document identifies naming mismatches between the Atlas graph (source of truth) and the actual monorepo package names. Misalignment creates confusion for contributors and agents navigating the codebase.\n\n## Mismatches\n\n### 1. \"babysitter\" vs Graph Layer Names\n\nThe graph uses clean layer names (Model, Provider, Transport, Agent-Core, Agent-Runtime, etc.) but the primary orchestration package is named `babysitter-sdk`. The name \"babysitter\" is a project identity, not an architectural concept.\n\n| Graph Concept | Package Name | Mismatch |\n|---------------|-------------|----------|\n| Orchestration layer | `@a5c-ai/babysitter-sdk` | \"babysitter\" is brand, not architecture |\n| Agent-Runtime layer | `@a5c-ai/genty-platform` | Conflates runtime with brand |\n| Observer (Presentation) | `@a5c-ai/babysitter-observer-dashboard` | Long; could be `@a5c-ai/observer` |\n| Metapackage | `@a5c-ai/babysitter` | OK — intentional brand entry point |\n\n**Recommendation:** No rename needed for published packages (breaking change). Internal docs should use graph layer names when referring to architectural concerns, \"babysitter\" when referring to the product/project.\n\n### 2. \"adapters\" Scope Sprawl\n\nThe graph has distinct layers (Core, Runtime, Platform, Interaction, Presentation) but `adapters` is used as a prefix for 7+ packages spanning multiple layers:\n\n| Package | Graph Layer | Role |\n|---------|-------------|------|\n| `agent-comm-adapter` | L4 Agent-Core, L5 Agent-Runtime | Core types + runtime utilities |\n| `adapters-adapters` | L5 Agent-Runtime | Harness adapter implementations |\n| `adapters-cli` | L10 Interaction | CLI entry point |\n| `adapters-gateway` | L6 Agent-Platform | Remote API surface |\n| `adapters-tui` | L11 Presentation | TUI rendering |\n| `adapters-ui` | L11 Presentation | Shared UI foundation |\n| `adapters-webui` | L11 Presentation | Web UI |\n\nThe `adapters` prefix implies \"agent multiplexing\" but most packages don't multiplex — they implement specific layers.\n\n**Recommendation:** Accept as-is for v6.1. The `adapters` prefix is an organizational grouping, not an architectural claim. Future packages should use layer-aligned names when the concern is clearly in one layer.\n\n### 3. \"hooks-adapter\" vs Graph Concepts\n\nThe graph defines `HookSurface`, `HookMapping`, `Channel` (channels-hooks cluster) but the implementation uses \"hooks-adapter\":\n\n| Graph Concept | Package | Mismatch |\n|---------------|---------|----------|\n| HookSurface | `@a5c-ai/hooks-adapter-core` | \"adapter\" implies multiplexing; graph says \"surface\" |\n| HookMapping | `@a5c-ai/hooks-adapter-*` | Graph uses \"mapping\" not \"adapter\" |\n| Channel | (no dedicated package) | Graph concept has no implementation |\n\n**Recommendation:** The hooks-adapter naming is stable and understood. \"Channel\" from the graph maps to the event routing in hooks-adapter-core but isn't surfaced as a first-class concept in the API.\n\n### 4. \"transport-adapter\" vs Layer 3\n\nThe graph layer is \"Transport\" but the package is `transport-adapter`. The \"adapter\" suffix is consistent with hooks-adapter and adapters but the graph doesn't use \"adapter\" anywhere.\n\n**Recommendation:** Accept. The `-adapter` suffix is a codebase convention for packages that bridge multiple implementations.\n\n### 5. \"tasks-adapter\" vs Layer 9 (Sandbox)\n\nThe graph layer is \"Sandbox\" with `HumanCheckpoint`, `BreakpointStrategy`, `BreakpointAnswer` node kinds. The package is named `tasks-adapter`.\n\n| Graph Concept | Package | Alignment |\n|---------------|---------|-----------|\n| HumanCheckpoint | tasks-adapter | Good — breakpoints ARE checkpoints |\n| Sandbox (layer) | tasks-adapter | Partial — breakpoints are one aspect of sandbox |\n\n**Recommendation:** `tasks-adapter` correctly names what it does (breakpoint multiplexing). It's a subset of the Sandbox layer, not the full layer implementation. Future sandbox packages (filesystem policy, network policy) should not be under `tasks-adapter`.\n\n### 6. Graph Node Kinds Without Package Representation\n\nThese graph node kinds in the agent-stack cluster have no corresponding package:\n\n| Node Kind | Layer | Status |\n|-----------|-------|--------|\n| `CapabilityProfile` | L4-L5 | Defined in graph; no runtime implementation |\n| `SessionModel` | L5 | Defined in graph; session persistence is in babysitter-sdk/session |\n| `LaunchConfig` | L5-L6 | Defined in graph; launch configs are in agent-catalog, resolved by adapters-cli |\n| `KnowledgeFabricImpl` | L12 | Defined in graph; no implementation package |\n\n## Naming Convention Guidelines for v6.1\n\n1. **New packages** should use the graph layer name when the package implements exactly one layer\n2. **Cross-layer packages** may use domain-specific names (e.g., `tasks-adapter` spans L9 + L14)\n3. **The `-adapter` suffix** means \"multiplexes across implementations\" (multiple harnesses, multiple transports, etc.)\n4. **Graph node kinds** are the canonical vocabulary — package READMEs should reference their node kinds\n5. **\"babysitter\"** is the product name; **layer names** are the architecture vocabulary\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-v6-spec-and-roadmap-v6-1",
      "to": "page:docs-v6-spec-and-roadmap-v6-1-naming-alignment",
      "kind": "contains_page"
    }
  ]
}