# Where to Find the Scope Topology Declaration in agent-core-v2

> Locate the agent-core-v2 scope topology declaration inkimi-code at packages/agent-core-v2/src/_base/di/scope.ts. Discover the declareScopeTopology function and its role in global scope initialization.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: architecture
- Published: 2026-08-13

---

**The scope topology declaration in agent-core-v2 is located in [`packages/agent-core-v2/src/_base/di/scope.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/_base/di/scope.ts) within the exported `declareScopeTopology` function, which initializes the global `_scopeTopology` array that governs the hierarchical order of scope kinds.**

The `agent-core-v2` package in the MoonshotAI/kimi-code repository implements a strict hierarchical dependency injection system where scopes must follow a defined topology. Understanding where this topology is declared is essential for correctly initializing the application's container hierarchy and preventing illegal scope nesting.

## The Core Declaration Location

The single source of truth for the scope hierarchy is defined in the dependency injection core of the package. This declaration is process-static, meaning it is set once at startup and enforced globally thereafter.

### The `_scopeTopology` Variable

At line 72 of [`packages/agent-core-v2/src/_base/di/scope.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/_base/di/scope.ts), the topology is stored in a module-level variable:

```typescript
let _scopeTopology: readonly string[] | undefined;

```

This variable holds the ordered list of **ScopeKind** values that defines the hierarchy from root to leaf. The type is `readonly` to prevent mutation after declaration, and it remains `undefined` until explicitly set.

### The `declareScopeTopology` Function

The topology is declared via the exported function at line 80:

```typescript
export function declareScopeTopology(kinds: readonly ScopeKind[]) {
  if (_scopeTopology !== undefined) {
    // Runtime guard against re-declaration with different ordering
    // ... error handling omitted
  }
  // Validate that provided kind list is exhaustive
  // Ensure the topology is a permutation of all kinds
  _scopeTopology = [...kinds];
}

```

This function performs two critical tasks: it validates that the provided array contains every **ScopeKind** exactly once, and it prevents subsequent calls from altering the established order. The **ScopeKind** type is defined at line 55 as `'app' | 'workspace' | 'session' | 'agent'`.

## How the Topology Enforcement Works

Once declared, the topology is consulted whenever the `Scope.createChild` method is invoked. The system enforces that child scopes must follow their parents in the declared hierarchy. For example, an `'app'` scope can create a `'workspace'` child, but a `'workspace'` cannot create an `'app'` child.

The enforcement logic compares indices within the `_scopeTopology` array to ensure the child kind appears after the parent kind in the ordered list.

## Practical Implementation Example

To initialize the dependency injection system correctly, declare the topology before creating any scopes:

```typescript
// 1️⃣ Declare the topology once at application startup
import { declareScopeTopology } from '#/agent-core-v2/_base/di/scope';

// The order must include every ScopeKind exactly once
declareScopeTopology(['app', 'workspace', 'session', 'agent']);

```

```typescript
// 2️⃣ Create the root 'app' scope
import { createAppScope } from '#/agent-core-v2/_base/di/scope';

const appScope = createAppScope({ id: 'mainApp' });

// 3️⃣ Create a valid child 'workspace' scope
const workspace = appScope.createChild('workspace', 'myWorkspace');

// ❌ Invalid: attempting to create 'app' under 'workspace' throws an error
try {
  workspace.createChild('app', 'illegalApp');
} catch (e) {
  console.error(e.message);
  // Output: "child scope kind 'app' must be greater than parent kind 'workspace'"
}

```

## Related Files in the DI System

The scope topology mechanism spans several key files within the `agent-core-v2` package:

- **[`packages/agent-core-v2/src/_base/di/scope.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/_base/di/scope.ts)** – Contains the `_scopeTopology` declaration, `declareScopeTopology` function, and the `Scope` class implementation.
- **[`packages/agent-core-v2/src/_base/di/instantiation.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/_base/di/instantiation.ts)** – Provides the `InstantiationService` used by `Scope` to create child containers and resolve dependencies.
- **[`packages/agent-core-v2/src/_base/di/types.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/_base/di/types.ts)** – Defines the `ScopeKind` union type and `ScopeOptions` interface used throughout the system.

## Summary

- The scope topology is declared in [`packages/agent-core-v2/src/_base/di/scope.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/_base/di/scope.ts) via the `declareScopeTopology` function.
- The global state is stored in the `_scopeTopology` variable, which is typed as `readonly string[] | undefined`.
- Valid **ScopeKind** values are `'app'`, `'workspace'`, `'session'`, and `'agent'`.
- The topology can only be set once per process; subsequent calls with different orderings will throw errors.
- Child scope creation validates against this topology to enforce hierarchical boundaries.

## Frequently Asked Questions

### What is the scope topology in agent-core-v2?

The scope topology is a statically declared ordered array of **ScopeKind** values (`app`, `workspace`, `session`, `agent`) that defines the legal parent-child relationships in the dependency injection container hierarchy. It ensures that scopes can only be created in a specific descending order, preventing architectural violations where a child scope might incorrectly parent a higher-level scope.

### What happens if I call `declareScopeTopology` twice?

The function guards against re-declaration. If `_scopeTopology` is already defined and the new `kinds` array differs from the existing one, the function will throw a runtime error. This prevents multiple parts of the application from accidentally establishing conflicting hierarchies, ensuring a single consistent topology per process.

### Where is the topology validated during child scope creation?

The validation occurs within the `Scope.createChild` method implementation in [`packages/agent-core-v2/src/_base/di/scope.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/_base/di/scope.ts). When `createChild` is called, the system checks the `_scopeTopology` array to verify that the requested child kind has a higher index than the current scope's kind. If the check fails, an error is thrown before the container is instantiated.

### Why must the topology include all ScopeKinds exactly once?

The `declareScopeTopology` function validates that the input array is an exhaustive permutation of all available **ScopeKind** values. This ensures the hierarchy is complete and unambiguous, preventing gaps in the chain that could lead to orphaned scopes or undefined behavior during service resolution across scope boundaries.