Files
archie/docs/architecture/dependencies-and-contracts.md
T
sam fd4420a038 docs(architecture): record decisions recovered from the pre-migration tracker
Eight approved decisions existed only as beads memories and were lost when
the tracker was removed. Recovered from a backup taken six minutes before
8bf0f6b and folded into the docs that own them, rather than a new document.

- migration-decisions: recorded position as of 2026-07-29, the deferred
  private-input-DTO compromise, and the agreed internal/app/{archied,
  agentworker} next step
- configuration: missing credential degrades a capability, only invalid
  config is fatal; config generation moves from install.sh to archied setup
- identity: the three-layer invariants/SOUL/representation model, and why
  a curator may only propose SOUL changes
- agent-system: the curator isolation invariant (curators are peers, never
  on a chat turn's critical path)
- messaging-and-work-intake: semantic search over messages is an explicit
  non-goal, with the measurements behind it
- safe-change-and-recovery: the /restart deadlock and lockout constraints
- plugins-and-extensions: dates the surprisal deferral

Also replaces the dead `**Beads issue:** archie-core-5d7` frontmatter across
all 12 documents with the GitHub issue it migrated to (#73), and rewrites
every other beads identifier to its issue number.
2026-08-09 18:10:12 +10:00

2.7 KiB

Dependencies and Contracts

Status: Approved foundation
Date: 2026-07-28
Tracking issue: #73

Dependency direction

domain and shared application contracts  <-  infrastructure implementations
                    ^
                    |
          application composition

The following rules are strict:

  1. Domains MUST NOT import internal/infrastructure.
  2. A domain defines the smallest interfaces required to perform its work.
  3. Infrastructure implements those interfaces and translates external representations at the boundary.
  4. Only application composition chooses concrete implementations.
  5. A domain MUST NOT manipulate another domain's state or call its internal services.
  6. Cross-domain work uses an explicitly designed command, event, or approved shared contract.
  7. Implementation difficulty is not permission to violate a boundary.

Broker messages, database rows, SDK response types, and configuration DTOs MUST NOT leak into domain models.

Commands and events

  • An event records something that happened and is owned by its publishing domain.
  • A command requests an action and is owned by the domain expected to handle it.
  • Consumers do not redefine an event's meaning.
  • Senders obey the receiving domain's command contract.
  • There is no generic package containing unrelated application messages.

Event bus

internal/eventbus is an approved shared application contract. It defines only the messaging behaviour Archie requires, including publication, subscription, delivery outcomes, and required lifecycle semantics.

It MUST remain broker-neutral. NATS subjects, JetStream configuration, consumer groups, acknowledgements, reconnection, and serialization belong under internal/infrastructure/eventbus/nats unless Archie explicitly requires a semantic guarantee in the shared contract.

Message schemas stay with their owning domains. The event bus transports messages; it does not own their meaning.

Wire contracts and generation

Canonical worker and service wire contracts and their authoritative generation inputs are owned by the domain or capability that defines their meaning. They MUST NOT be centralized in internal/infrastructure/spec or another generic schema package.

Infrastructure owns:

  • generic contract-generation machinery;
  • transport-specific adapters and generated implementations;
  • RPC, REST, NATS, and other external encoding and delivery concerns.

For example, agent-worker requests and results belong to task execution. Subprocess, NATS, or HTTP representations are infrastructure implementations of that contract. The same rule applies independently to forge, persistence, workspace, and other service contracts.