Data Structure Protocol (DSP)

DSP builds a dependency graph of project entities in a .dsp/ directory. Each entity (module, function, external dependency) gets a UID, description, import list, and export index. The graph answers: what exists, why it exists, what depends on what, and who uses what.

DSP is NOT documentation for humans or AST dump. It captures _meaning_ (purpose), _boundaries_ (imports/exports), and _reasons for connections_ (why).

Agent Prompt

Embed this context when working on a DSP-tracked project:

> This project uses DSP (Data Structure Protocol).

> The .dsp/ directory is the entity graph of this project: modules, functions, dependencies, public API. It is your long-term memory of the code structure.

>

> Core rules:

>

> 1. Before changing code — find affected entities via dsp-cli search, find-by-source, or read-toc. Read their description and imports to understand context.

> 2. When creating a file/module — call dsp-cli create-object. For each exported function — create-function (with --owner). Register exports via create-shared.

> 3. When adding an import — call dsp-cli add-import with a brief why. For external dependencies — first create-object --kind external if the entity doesn't exist yet.

> 4. When removing import / export / file — call remove-import, remove-shared, remove-entity respectively. Cascade cleanup is automatic.

> 5. When renaming/moving a file — call move-entity. UID does not change.

> 6. Don't touch DSP if only internal implementation changed without affecting purpose or dependencies.

> 7. Bootstrap — if .dsp/ is empty, traverse the project from root entrypoint via DFS on imports, documenting every file.

>

> Key commands:

> ```

> dsp-cli init

> dsp-cli create-object [--kind external] [--toc ROOT_UID]

> dsp-cli create-function [--owner UID] [--toc ROOT_UID]

> dsp-cli create-shared [ ...]

> dsp-cli add-import [--exporter UID]

> dsp-cli remove-import [--exporter UID]

> dsp-cli remove-shared

> dsp-cli remove-entity

> dsp-cli move-entity

> dsp-cli update-description [--source S] [--purpose P] [--kind K]

> dsp-cli get-entity

> dsp-cli get-children [--depth N]

> dsp-cli get-parents [--depth N]

> dsp-cli search

> dsp-cli find-by-source

> dsp-cli read-toc [--toc ROOT_UID]

> dsp-cli get-stats

> ```

Using the CLI

The script is at scripts/dsp-cli.py relative to this skill directory.

python <skill-path>/scripts/dsp-cli.py [--root <project-root>] <command> [args]

--root defaults to current working directory. All paths in arguments are repo-relative.

Core Concepts

• Code = graph. Nodes are Objects and Functions. Edges are imports and shared/exports.
• Identity by UID, not file path. Path is an attribute; renames/moves don't change UID.
• "Shared" creates an entity. If something becomes public (exported), it gets its own UID.
• Import tracks both "from where" and "what". One code import may create two DSP links: to the module and to the specific shared entity.
• Full import coverage. Every imported file/asset must be an Object in .dsp — code, images, styles, configs, everything.
• why lives next to the imported entity in its exports/ directory (reverse index).
• Start from roots. Each root entrypoint has its own TOC file.
• External deps — record only. kind: external, no deep dive into node_modules/site-packages/etc. But exports index works — shows who imports it.

UID Format

• Objects: obj-<8 hex> (e.g., obj-a1b2c3d4)
• Functions: func-<8 hex> (e.g., func-7f3a9c12)

UID marker in source code — comment @dsp before declaration:

// @dsp func-7f3a9c12
export function calculateTotal(items) { ... }

# @dsp obj-e5f6g7h8
class UserService:

Workflows

Setting Up DSP

1. Run dsp-cli init to create .dsp/ directory.
2. Identify root entrypoint(s) — package.json main, framework entry, etc.
3. Run bootstrap (DFS from root). See bootstrap.md.

Creating Entities (when writing new code)

1. Create module: dsp-cli create-object
2. Create functions: dsp-cli create-function # --owner
3. Register exports: dsp-cli create-shared [ ...]
4. Register imports: dsp-cli add-import [--exporter ]
5. External deps: dsp-cli create-object --kind external

Navigating the Graph (when reading/understanding code)

• Find entity by file: dsp-cli find-by-source
• Search by keyword: dsp-cli search
• Read TOC: dsp-cli read-toc → get all UIDs, then get-entity for details
• Dependency tree down: dsp-cli get-children --depth N
• Dependency tree up: dsp-cli get-parents --depth N
• Impact analysis: dsp-cli get-recipients — who depends on this entity
• Path between entities: dsp-cli get-path

Updating (when modifying code)

• Purpose changed: dsp-cli update-description --purpose
• File moved: dsp-cli move-entity
• Import reason changed: dsp-cli update-import-why

Deleting (when removing code)

• Import removed: dsp-cli remove-import [--exporter UID]
• Export removed: dsp-cli remove-shared
• File/module deleted: dsp-cli remove-entity (cascading cleanup)

Diagnostics

• dsp-cli detect-cycles — circular dependencies
• dsp-cli get-orphans — unused entities
• dsp-cli get-stats — project graph overview

When to Update DSP

References

• Storage format — .dsp/ directory structure, file formats, TOC
• Bootstrap procedure — initial project markup (DFS algorithm)
• Operations reference — detailed semantics of all operations with import examples