Phase 0: In-process contract seams (modular monolith, no process split) #111

Closed
opened 2026-10-27 13:34:59 +00:00 by sam · 0 comments
Owner

First phase of the resolved extraction order (open question #1). Still a
modular monolith -- no new process, nothing listening on a real port.
Introduces, in-process, the seams that make later extraction a swap of
transport rather than a rewrite, per open question #3's resolved
mechanism (multiplexed in-process is the migration default).

Scope:

  • A ChatContract interface owned by the Gateway, aligning
    Router/SessionStore/Turns/ModelManager/PersonaRegistry behind it, so
    internal/webui depends on the contract type rather than holding
    *gateway.Router, gateway.SessionStore, *gateway.Turns,
    gateway.ModelManager, and *gateway.PersonaRegistry directly
    (internal/webui/api_chat.go's current ChatService struct, lines 22-26).
  • The ServiceRegistry interface from the discovery research
    (Resolve(service string) []Endpoint; Watch(service string) <-chan
    Event), landed as a real internal package
    (internal/servicediscovery/servicediscovery.go per the research doc's
    citation) -- network-only; it never returns an in-process shim (see
    question #3's resolution part 3).
  • The State Store's already-narrow interfaces (TaskStore, CaptureStore,
    MappingStore, BindingStore, WorkflowStore in
    internal/store/interface.go) ratified as the State Store contract
    surface -- no code change to the interfaces themselves, this is the
    authority decision plus wiring them as wire-safe contracts.
  • For the ChatContract specifically: a wire-safe Go interface (values and
    streams only, no callbacks like Gateway's LLMStreamResponder, no
    *sql.Tx, no leaked object identity), a local in-process adapter (real
    production adapter, not a test fake), a generated gRPC client adapter
    satisfying the same interface via a compile-time assertion (the var _ store.WorkflowStore = (*Client)(nil) idiom, internal/storerpc/storerpc.go:136),
    and a per-contract conformance suite run against both adapters over
    bufconn (the runSessionStoreSuite idiom,
    internal/gateway/sessionstore_conformance_test.go:65).
  • Composition (internal/app wiring), not ServiceRegistry, picks
    mode = "inproc" | "remote" per service, defaulting to "inproc".

Depends on the contract-definition-mechanism issue (buf/proto toolchain)
since ChatContract's .proto definition and generated Go land here.

Full reasoning: docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#1
(Phase 0 section) and #3 (the six-part mechanism).

Acceptance criteria

  • proto/gateway/v1/ ChatContract .proto definition committed, generated
    Go landed at internal/contracts/gateway/v1/ via the proto toolchain
    from the contract-mechanism issue.
  • ChatContract Go interface defined, wire-safe (no callbacks, no *sql.Tx,
    no object identity leaks).
  • A local adapter satisfying ChatContract that wraps the existing
    Router/SessionStore/Turns/ModelManager/PersonaRegistry in-process, with
    zero serialization.
  • A generated gRPC client adapter satisfying the same ChatContract
    interface, with a compile-time var _ ChatContract = (*Client)(nil)
    assertion.
  • A bufconn-based conformance test suite exercising both adapters against
    the same behavioural assertions.
  • internal/webui's ChatService depends on the ChatContract interface type,
    not on gateway.Router/SessionStore/Turns/ModelManager/PersonaRegistry
    structs directly.
  • mode = "inproc" | "remote" config plumbed through composition wiring,
    defaulting to "inproc"; no cmd/archie-gateway binary and nothing
    listening on a real network port yet.
  • ServiceRegistry interface (Resolve/Watch) exists as a real Go interface
    in internal/servicediscovery, even if only a stub/no-op implementation
    backs it at this phase.
  • task check passes; no behavioural change to production traffic (still
    fully in-process).

Close reason

Gateway ChatContract, local and gRPC adapters, bufconn conformance, discovery boundary, inproc/remote composition, and webui migration implemented.


Imported from beads archie-core-8cda.2 · GitHub #722 · type task · priority P1 · created 2026-09-05 · closed 2026-09-05

First phase of the resolved extraction order (open question #1). Still a modular monolith -- no new process, nothing listening on a real port. Introduces, in-process, the seams that make later extraction a swap of transport rather than a rewrite, per open question #3's resolved mechanism (multiplexed in-process is the migration default). Scope: - A ChatContract interface owned by the Gateway, aligning Router/SessionStore/Turns/ModelManager/PersonaRegistry behind it, so internal/webui depends on the contract type rather than holding *gateway.Router, gateway.SessionStore, *gateway.Turns, gateway.ModelManager, and *gateway.PersonaRegistry directly (internal/webui/api_chat.go's current ChatService struct, lines 22-26). - The ServiceRegistry interface from the discovery research (Resolve(service string) []Endpoint; Watch(service string) <-chan Event), landed as a real internal package (internal/servicediscovery/servicediscovery.go per the research doc's citation) -- network-only; it never returns an in-process shim (see question #3's resolution part 3). - The State Store's already-narrow interfaces (TaskStore, CaptureStore, MappingStore, BindingStore, WorkflowStore in internal/store/interface.go) ratified as the State Store contract surface -- no code change to the interfaces themselves, this is the authority decision plus wiring them as wire-safe contracts. - For the ChatContract specifically: a wire-safe Go interface (values and streams only, no callbacks like Gateway's LLMStreamResponder, no *sql.Tx, no leaked object identity), a local in-process adapter (real production adapter, not a test fake), a generated gRPC client adapter satisfying the same interface via a compile-time assertion (the `var _ store.WorkflowStore = (*Client)(nil)` idiom, internal/storerpc/storerpc.go:136), and a per-contract conformance suite run against both adapters over bufconn (the runSessionStoreSuite idiom, internal/gateway/sessionstore_conformance_test.go:65). - Composition (internal/app wiring), not ServiceRegistry, picks mode = "inproc" | "remote" per service, defaulting to "inproc". Depends on the contract-definition-mechanism issue (buf/proto toolchain) since ChatContract's .proto definition and generated Go land here. Full reasoning: docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#1 (Phase 0 section) and #3 (the six-part mechanism). ### Acceptance criteria - proto/gateway/v1/ ChatContract .proto definition committed, generated Go landed at internal/contracts/gateway/v1/ via the proto toolchain from the contract-mechanism issue. - ChatContract Go interface defined, wire-safe (no callbacks, no *sql.Tx, no object identity leaks). - A local adapter satisfying ChatContract that wraps the existing Router/SessionStore/Turns/ModelManager/PersonaRegistry in-process, with zero serialization. - A generated gRPC client adapter satisfying the same ChatContract interface, with a compile-time `var _ ChatContract = (*Client)(nil)` assertion. - A bufconn-based conformance test suite exercising both adapters against the same behavioural assertions. - internal/webui's ChatService depends on the ChatContract interface type, not on gateway.Router/SessionStore/Turns/ModelManager/PersonaRegistry structs directly. - mode = "inproc" | "remote" config plumbed through composition wiring, defaulting to "inproc"; no cmd/archie-gateway binary and nothing listening on a real network port yet. - ServiceRegistry interface (Resolve/Watch) exists as a real Go interface in internal/servicediscovery, even if only a stub/no-op implementation backs it at this phase. - task check passes; no behavioural change to production traffic (still fully in-process). ### Close reason Gateway ChatContract, local and gRPC adapters, bufconn conformance, discovery boundary, inproc/remote composition, and webui migration implemented. --- _Imported from beads `archie-core-8cda.2` · GitHub #722 · type task · priority P1 · created 2026-09-05 · closed 2026-09-05_
sam added the hightask labels 2026-10-27 13:34:59 +00:00
sam self-assigned this 2026-10-27 13:35:00 +00:00
sam closed this issue 2026-10-27 13:35:00 +00:00
sam added a new dependency 2026-10-27 13:41:44 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#111