Ports inbound

Les ports inbound (core/ports/inbound/for-*.ts) définissent les contrats que les use-cases exposent aux adapters (routes HTTP, CLI, etc.). C’est la surface “driving” du core hexagonal.

Source de vérité : core/ports/inbound/.

Pattern

Chaque port est un fichier for-<domaine>.ts qui exporte une interface TypeScript. Les use-cases correspondants vivent dans core/use-cases/<domaine>/ et fournissent une implémentation via une factory buildFor<Domaine>(deps).

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[] }>;
  // ...
}

Les adapters inbound (routes Fastify) consomment ces ports via la composition.

Inventaire

Les 24 ports inbound livrés actuellement, groupés par domaine fonctionnel.

Espaces de travail et projets

for-workspaces.ts — CRUD workspaces (groupes logiques de projets)
for-projects.ts — CRUD projets (marker disque + index global + cycle de vie)

Sessions et chat

for-chat.ts — démarrer, reprendre, envoyer un tour, streamer
for-runtime-context.ts — composer le contexte avant un tour LLM

Catalogue

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

Mémoire et gouvernance

for-leader-modes.ts — exécuter les modes leader (judge, analyst, strategist)
for-mission-guardian.ts — gates, preuves, verdict QA pour mission

Squads et orchestration

for-squads.ts — composer une squad (mission, agents, leader)
for-workers.ts — invoquer un worker 1-shot

ArkaDoc

for-arkadoc.ts — documents projet (CR, brief, spec, task, decision)
for-agent-action-cards.ts — cartes d’action agent (sélection avant tour)

Providers et runtimes

for-provider-instances.ts — CRUD instances provider (clés chiffrées)
for-provider-test.ts — tester la connexion d’un provider
for-cortex-runtime.ts — lire le contexte runtime Cortex
for-cortex-lite-materialization.ts — matérialiser un projet dans Cortex Lite

Connecteurs externes

for-connectors.ts — actions des connecteurs (Notion, etc.)
for-external-refs.ts — références externes (freshness, resolve)

Configuration et installation

for-preferences.ts — préférences utilisateur (langue, theme, etc.)
for-installs.ts — installations addons par projet
for-launch.ts — options de lancement provider/projet

Artefacts agentiques (Materializers)

for-hooks.ts — hooks d’agent matérialisés en fichiers
for-skills.ts — skills d’agent matérialisés

Services worker

for-worker-services.ts — assigner un service provider à un worker

Quand créer un nouveau port inbound

Un nouveau domaine métier apparaît, distinct des existants.
Le contrat est consommé par plusieurs adapters (route HTTP + CLI, par exemple).
L’implémentation peut changer sans casser l’adapter.

Pour étendre arka-deck via un addon, vous créez un port inbound dans le dossier de l’addon (addons/<name>/src/ports/for-<name>.ts), pas dans core/. Le core ne grossit qu’avec les capacités structurantes.

Voir aussi

Architecture hexagonale (ADR) : ../../adr/0001-architecture-hexagonale.md
Vue d’ensemble : ./overview
Ports outbound : ./ports-outbound
Composition root : ./composition-root