Ports outbound

Les ports outbound (core/ports/outbound/*.ts) définissent les contrats que les adapters implémentent : I/O fichiers, HTTP, base de données, secrets, événements, chat runtime, etc. C’est la surface “driven” du core hexagonal.

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

---

Pattern

Chaque port est une interface TypeScript pure. Le core ne connaît jamais l’implémentation concrète — il reçoit toujours une instance qui satisfait l’interface, fournie par la composition.

core/ports/outbound/filesystem.ts

export interface Filesystem {
  read(path: string): Promise<string>;
  readJson<T = unknown>(path: string): Promise<T>;
  writeJson(path: string, value: unknown): Promise<void>;
  exists(path: string): Promise<boolean>;
  rm(path: string, options?: { recursive?: boolean }): Promise<void>;
  // ...
}

L’adapter concret (adapters/outbound/filesystem/fs-filesystem.ts) implémente l’interface. Pour les tests, un InMemoryFilesystem ou un fake satisfait également le contrat.

---

Inventaire par catégorie

Les principaux ports outbound livrés, groupés par responsabilité.

Infrastructure générale

• clock.ts — horloge (now())
• id-generator.ts — génération d’ID stables
• filesystem.ts — lecture/écriture fichiers locaux (avec allowlist)
• arka-home.ts — résolution du dossier ~/.arka-deck/
• event-bus.ts — bus d’événements typé in-process
• checksum-computer.ts — calcul de checksum (fichiers, artefacts)

Stockage métier

• chat-session-store.ts — sessions chat (SQLite)
• chat-attachment-store.ts — pièces jointes des sessions
• agent-action-card-store.ts — cartes d’action agent
• arkadoc-store.ts, arkadoc-manifest-store.ts, arkadoc-file-activity-store.ts — documents projet
• catalogue-cache.ts — cache du catalogue Cortex
• connector-execution-store.ts, connector-installation-store.ts, connector-action-grant-store.ts — connecteurs externes

Clients HTTP Cortex

• catalogue-client.ts — profils HYOS depuis le Cortex public
• catalogue-blocs-client.ts — blocs depuis le Cortex
• arkadoc-cortex-client.ts — sync ArkaDoc avec Cortex
• atoms-client.ts — atomes Cortex
• cortex-lite-materialization-source.ts — source de matérialisation projet

Chat et providers

• chat-runtime.ts — exécution d’un tour LLM (streaming)
• before-turn-augmenter.ts — injection de contexte avant un tour
• agent-identity-context-client.ts — contexte identité agent

Materializers

• agent-workspace-materializer.ts — agents matérialisés en fichiers locaux

Connecteurs

• connector-registry.ts — registre des connecteurs externes

Secrets

• secret-cipher.ts — chiffrement/déchiffrement (AES-256-GCM par défaut)

---

Trois familles d’implémentations

Préfixe	Famille	Usage
Fs*	Filesystem	Lecture/écriture fichiers locaux
Sqlite*	SQLite	Stockage relationnel local
Http*	HTTP	Clients Cortex public ou Cortex Lite
InMemory*	Mémoire	Tests, fakes

Chaque port a au moins une implémentation prod et un fake testable.

---

Quand créer un nouveau port outbound

• Vous avez besoin d’une nouvelle dépendance externe (un nouveau service, une nouvelle source de données).
• Plusieurs implémentations peuvent exister (par exemple Fs* + Http*).
• L’interface doit pouvoir être mockée pour les tests.

Évitez de créer des ports pour des utilitaires purs (calcul, formatage) — gardez-les dans core/_shared/ ou dans le domaine.

---

Voir aussi

• Vue d’ensemble : ./overview
• Ports inbound : ./ports-inbound
• Composition root : ./composition-root
• Stockage : ./stockage