Inbound ports

Inbound ports (core/ports/inbound/for-*.ts) define the contracts that use-cases expose to adapters (HTTP routes, CLI, etc.). This is the “driving” surface of the hexagonal core.

Source of truth: core/ports/inbound/.

Pattern

Each port is a for-<domain>.ts file exporting a TypeScript interface. Corresponding use-cases live under core/use-cases/<domain>/ and provide an implementation via a buildFor<Domain>(deps) factory.

export interface ForProjects {
  create(input: CreateProjectInput): Promise<Project>;
  list(): Promise<readonly Project[]>;
  findByCwd(cwd: string): Promise<Project | null>;
  forget(projectId: string): Promise<void>;
  purge(projectId: string): Promise<{ deletedPaths: readonly string[] }>;
  // ...
}

Inbound adapters (Fastify routes) consume these ports via composition.

Inventory

The 24 inbound ports currently shipped, grouped by functional domain.

Workspaces and projects

for-workspaces.ts — workspace CRUD (logical project groups)
for-projects.ts — project CRUD (disk marker + global index + lifecycle)

Sessions and chat

for-chat.ts — start, resume, send a turn, stream
for-runtime-context.ts — compose context before an LLM turn

Catalogue

for-catalogue.ts — HYOS profiles (browse, install)
for-blocs-catalogue.ts — Cortex blocs (tree, search)

Memory and governance

for-leader-modes.ts — execute leader modes (judge, analyst, strategist)
for-mission-guardian.ts — gates, evidence, mission QA verdict

Squads and orchestration

for-squads.ts — compose a squad (mission, agents, leader)
for-workers.ts — invoke a 1-shot worker

ArkaDoc

for-arkadoc.ts — project documents (report, brief, spec, task, decision)
for-agent-action-cards.ts — agent action cards (pre-turn selection)

Providers and runtimes

for-provider-instances.ts — provider instance CRUD (encrypted keys)
for-provider-test.ts — test a provider’s connection
for-cortex-runtime.ts — read Cortex runtime context
for-cortex-lite-materialization.ts — materialize a project in Cortex Lite

External connectors

for-connectors.ts — connector actions (Notion, etc.)
for-external-refs.ts — external references (freshness, resolve)

Configuration and installation

for-preferences.ts — user preferences (language, theme, etc.)
for-installs.ts — per-project addon installations
for-launch.ts — launch options per provider/project

Agent artifacts (Materializers)

for-hooks.ts — agent hooks materialized as files
for-skills.ts — agent skills materialized

Worker services

for-worker-services.ts — assign a provider service to a worker

When to create a new inbound port

A new business domain appears, distinct from existing ones.
The contract is consumed by several adapters (HTTP route + CLI, for example).
The implementation can change without breaking the adapter.

To extend arka-deck via an addon, you create an inbound port inside the addon’s folder (addons/<name>/src/ports/for-<name>.ts), not in core/. The core grows only with structuring capabilities.