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

72 lines
2.7 KiB
Markdown

# Dependencies and Contracts
**Status:** Approved foundation
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Dependency direction
```text
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.