capture #49b: CaptureService use-case + BrainStore extraction + ports/entities #51
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: mathias/hyperguild#51
Reference in New Issue
Block a user
Parent: #49 · Spec:
specs/capture-bdd-spec.md§1 · Depends on: nothing (buildable against fake ports) · Blocks: #49c, #49dScope
The Clean-Architecture core of capture: extract #45's brain write/update/get logic out of the MCP-only layer into a shared
BrainStore, define the ports and entities, and implement theCaptureServiceorchestration. Build and unit-test against fake ports — no live gating, no HTTP, no real gitea yet. The classification check is an injected policy (satisfied later by #49a/#50).This is the biggest single chunk and the spine everything else hangs off.
Ground-truth (from #49)
brain_update/brain_getcurrently live iningestion/internal/mcp/only;/write(api.WriteNote, a free function) is the only brain write reachable from the REST/api layer. The extraction lifts the update/get logic into a shared impl both the MCP handlers and capture call — the Clean-Arch payoff, real work, not a wrapper.What to build
ingestion/internal/capture/package.BrainStore—Write(ctx, note) (ref, error),Update(ctx, slug, note) (ref, error),Get(ctx, id) (note, error)whereref = {id, path, content_hash}.IssueTracker—CreateIssue,CloseIssue,CommentIssue(interface only here; impl in #49c).SummaryWriter—WriteFile(repo, path, content) error.ClassificationPolicy—Derive(target) level+Effective(declared, derived) level(interface only; impl in #49a/#50).AuditSink—Record(ctx, auditEntry) error(interface only; impl in #49e/#49f).Insight,Ticket,Summary,CaptureContext,CaptureReceipt— plain structs.BrainStoreextraction: liftbrain_update/brain_get/brain_writelogic frommcp/into a concreteBrainStoreimpl; re-point the existing MCP handlers at it so there's one implementation, not two (DRY — the whole point). Preserve the #45 read-after-write contract and the batch staleness discipline inside the store/use-case so callers never carry the rule.CaptureService.Capture(ctx, CaptureInput) (CaptureReceipt, error): validate-before-write (fail-closed), resolve effective classification via the policy port, orchestrate insights (write/supersede) → tickets → summary, best-effort with per-item outcome, assemble the partial-aware receipt.dry_runshort-circuits after validation.Acceptance criteria
capture/package: ports, entities,CaptureServiceBrainStoreconcrete impl with Write/Update/Get; MCP handlers re-pointed at it (no duplicate logic)ok/error; no rollbackdry_runreturns would-be receipt, writes nothingClassificationPolicy(stricter wins)brain_update/brain_gettests still pass after re-pointingtask checkgreenNotes
No HTTP, no live gitea, no live audit in this issue — all injected as interfaces, real impls land in #49c/d/e/f. The value here is a fully unit-tested use-case before any I/O is wired. Gherkin scenarios this satisfies (against fakes): supersede-not-duplicate, fail-closed validation, partial-failure receipt, dry-run, stricter-classification-wins.
Implemented — PR #57 (open, stacked on #56)
PR: #57 · base
feat/capture-classification(merge #56 first; #57 is #51-only diff)Two packages:
capture/— pure use-case: ports (BrainStore/IssueTracker/SummaryWriter/ClassificationPolicy/AuditSink), entities,CaptureService.Capture(validate-fail-closed → effective classification → insights/tickets/summary best-effort → audit → partial receipt;dry_runwrites nothing).brainstore/— the extraction: one concreteStoreimplementingcapture.BrainStore(api primitives + wing-index/auto-tunnel/graph). MCPbrain_write/brain_update/brain_getre-pointed at it — one impl, not two. Existing MCP tests pass unmodified;{id,path,content_hash}contract preserved.Soft dep on #50: reuses
classification.Level/Targetrather than duplicating the enum → branch stacked on #56.classification.Configis a drop-inClassificationPolicy.Deliberate scope boundaries:
Effectivefolded into the service asStricter(port staysDerive-only).All ACs met;
task checkgreen. BDD scenarios satisfied against fakes: supersede-not-duplicate, fail-closed validation, partial-failure receipt, dry-run, stricter-wins, caller-raising-honoured, summary fidelity.Critical path next: #52 (Gitea
IssueTrackerimpl — depends on this) → #53 (REST + I1 gate). TheIssueTracker/SummaryWriter/AuditSinkports are ready for their real adapters.