internal-surface-areas（内表面积）

Inkeep Internal Surface Area Inventory

Overview

This is a consolidated inventory of internal “surface areas”: subsystems, infrastructure, tooling, and shared code that developers/operators interact with, but which are not directly customer-facing contracts. Use it during planning or PR review to understand internal dependency chains (what breaks when X changes) and to avoid accidental workflow/build/test/deploy regressions.

Companion skills: For *who* is affected and how changes propagate per audience, load audience-impact. For customer-facing surfaces, load product-surface-areas.

Summary

Surface Catalog

Build & Package Graph

Developer/operator goal: build, link, and resolve monorepo dependencies deterministically.

Developer Workflow & Quality Gates

Developer/operator goal: enforce consistent style and catch regressions early during development.

CI/CD Pipelines

Developer/operator goal: automate checks, publishing, and deployment reliably.

Test Infrastructure

Developer/operator goal: run reliable, isolated, and fast automated tests locally and in CI.

Environment & Configuration

Developer/operator goal: configure the system safely for dev/test/prod and keep configuration documented.

Docker & Deployment Artifacts

Developer/operator goal: run the system in containers for local development and integration testing.

Database Schemas & Migrations

Developer/operator goal: evolve data models safely and reproducibly via migration tooling.

Database Clients & Data Access Layer

Developer/operator goal: query and mutate data through typed abstractions with consistent safety checks.

Validation & Shared Runtime Types

Developer/operator goal: enforce runtime correctness through shared schemas and typed validators.

Authentication & Authorization Infrastructure

Developer/operator goal: authenticate users and enforce fine-grained permissions consistently across services.

Observability Infrastructure

Developer/operator goal: emit, export, and query traces/logs for debugging and monitoring.

Runtime Engine (Agent Execution & Streaming)

Developer/operator goal: execute agent runs end-to-end (history, prompts, tool calls, streaming, persistence) safely and observably.

Tool Execution Sandboxes

Developer/operator goal: execute function tools in isolated environments with predictable limits and cleanup.

AI Development Tooling

Developer/operator goal: guide AI coding agents and automate AI-assisted workflows without breaking discovery/validation.

Package Publishing & Versioning

Developer/operator goal: version packages consistently and publish safely to npm and internal registries.

Breaking Change Impact Matrix

Transitive Chain Tracing

Use this methodology to trace what a change touches and what it should touch but may not have:

Step 1: Map changed files → directly modified surfaces

For each changed file in the PR, find the matching row in the Surface Catalog tables above. These are directly modified surfaces.

Step 2: Trace one hop out via the Breaking Change Impact Matrix

For each directly modified surface, look it up in the left column of the Breaking Change Impact Matrix. The right column lists surfaces that break when this surface changes — these are transitively impacted.

Step 3: Identify potentially unaccounted surfaces

Compare the transitively impacted set against the PR's changed files. Any surface that appears in the transitive chain but whose source files were not updated by the PR is potentially unaccounted — it may need updating, testing, or at minimum a conscious acknowledgment that no change is needed.

Example

If a PR modifies packages/agents-core/src/db/manage/manage-schema.ts:

1. Directly modified: Manage DB schema (Doltgres, versioned)
2. Transitively impacted (from the matrix): Drizzle kit configs, Migration directories, Manage DB client & pool factories, Core data-access modules, Dolt migration runner, Dolt branch schema sync, Local dev bootstrap
3. Potentially unaccounted: If the PR updated the schema and generated migrations but did not touch AGENTS.md (which documents the migration workflow) or Local dev bootstrap (which runs migrations on setup), flag those as potentially unaccounted

When to apply

• PR review (via pr-tldr): The orchestrator fills in the internal surfaces section using this methodology
• Planning/refactoring: Before starting work, trace the chain to understand the full blast radius
• Post-change audit: After implementation, verify nothing in the transitive chain was missed

Not Internal

Dependency Graph

graph TD
  %% Major internal dependency clusters only (surfaces are cataloged in tables above)

  subgraph Foundational_Tooling[Foundational Tooling]
    PNPM[pnpm workspace & dependency catalog]
    SCRIPTS[Root monorepo scripts]
    TURBO[Turborepo task graph]
    TSCFG[TypeScript project configs]
    BIOME[Biome lint/format configs]
  end

  subgraph Env_and_Infra[Environment & Infra]
    ENVLOADER[Environment file loader]
    ENVSCHEMA[Runtime env schemas]
    DOCKERDB[Local database stack]
  end

  subgraph Data_Platform[Data Platform]
    DBMAN[Manage DB schema]
    DBRUN[Runtime DB schema]
    DRIZZLE[Drizzle kit configs]
    MIGS[Migration directories]
    DATA[Core data-access modules]
    AUTH[Auth/Authz infra]
  end

  subgraph Runtime_Engine[Runtime Engine]
    EXEC[Execution loop]
    AGENT[Agent generation core]
    STREAM[Streaming helpers]
    SESSION[Agent session tracking]
    SANDBOX[Tool sandboxes]
  end

  subgraph Automation[Automation & CI]
    CI[CI workflows]
    REL[Release/publish]
    DEP[Deploy workflows]
  end

  subgraph AI_Tooling[AI Dev Tooling]
    SKILLS[Skills library]
    CLAUDE[Claude Code agents]
    VALID[AI artifact validation]
  end

  %% Tooling dependencies
  PNPM --> SCRIPTS
  PNPM --> TURBO
  TSCFG --> TURBO

  %% Env -> infra -> data
  ENVLOADER --> ENVSCHEMA
  ENVSCHEMA --> DRIZZLE
  DOCKERDB --> AUTH

  DBMAN --> DRIZZLE
  DBRUN --> DRIZZLE
  DRIZZLE --> MIGS
  MIGS --> DATA

  %% Data -> runtime
  DATA --> EXEC
  DATA --> AGENT
  STREAM --> EXEC
  SESSION --> AGENT
  SANDBOX --> AGENT

  %% CI & release
  TURBO --> CI
  CI --> REL
  REL --> DEP

  %% AI tooling
  VALID --> SKILLS
  SKILLS --> CLAUDE