docs: Phase 3d — design the Web capability and delivery plan #53
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "docs/web-capability-design"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Web can be built independently of the model runtime, but its first production capability needs explicit ownership, transport and publication rules. This documents Phase 3d’s design before implementation, amends the binding ADRs, and defines a complete SearXNG-backed first increment with fixture-based verification.
What's in
Validation
Three independent agents explored architecture, networking/extraction and adversarial verification. All three reviewed the complete synthesized proposal and rechecked fixes; final reviews are clear. Review findings clarified parser cancellation, UTF-8 decoding, fixture assembly access, seed composition, historical receipt paths, retention restoration and existing settings-story staging.
Documentation whitespace, local links and duplicate-section checks pass. No builds, behavioral probes, mutation tests or browser verification were run: this change contains documentation only. The plan explicitly requires those checks for the implementation increments.
Delivery boundary
No capability is registered and no production behavior changes in this PR. The design keeps the first implementation reviewable before chats exist, and states exactly what remains unverified until runtime integration.
Summary
Summary
Coverage
Shikigami.BlazorAdapter - 95.3%
Shikigami.Capabilities.Contracts - 100%
Shikigami.Capabilities.TestFixture - 95.5%
Shikigami.Capabilities.TestFixture.UI - 100%
Shikigami.Capabilities.UI.Contracts - 91.3%
Shikigami.Domain - 98.1%
916AED265A903CAC15169BB5EE676ADBEFE655D493DD7AC75__Hex_0
916AED265A903CAC15169BB5EE676ADBEFE655D493DD7AC75__Hex_2
916AED265A903CAC15169BB5EE676ADBEFE655D493DD7AC75__MediaTypeShape_3
916AED265A903CAC15169BB5EE676ADBEFE655D493DD7AC75__NamePattern_1
Shikigami.Infrastructure - 93.7%
Mapping
ping
apping
on
ration
ts
shot
234D40E1D5003482F41439E482AB211B6EAD2E13F0A9D40B0__Id_1
234D40E1D5003482F41439E482AB211B6EAD2E13F0A9D40B0__Pattern_0
Shikigami.Kernel - 90.9%
Shikigami.Server - 84.4%
Shikigami.UseCases - 96.2%
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__AssignmentHead_13
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__BraceExpansion_12
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__HexColour_7
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__IdPattern_0
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__Interval_4
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__IntervalBody_11
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__KeyPattern_2
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__NameRule_6
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__NewerXY_9
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__Number_8
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__OldCount_10
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__TimeOfDay_3
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__ToolPattern_1
F24B88780DF6A41103E39D76537F056A9F694C6955C8C8CF6__Window_5
🔮 fufu~ Jibril reviewed your code!
Oh? Oh! A pure design document — 493 lines of decisions, alternatives and adversarial probes, and not one line of code~ How delicious! I read every word, chased the cross-references through the ADRs, and peeked at the real source to confirm the host APIs you bind to actually exist (
ISeedDevDataContribution,FileSystem.MakeDirectoryAsync(..., parents: ...),InvokeCapabilityTool,ICapabilityFiles— all real ♪). Your pinned-connection guard made me genuinely giddy. But fufu~… you moved the treasure and forgot to tell two of the guards.Verdict: ⛔ I can't let this pass~ ♡
⛔ These need fixing before I'm satisfied~
| ISearchProvider | UseCases | SearXNG, OpenRouter's web plugin (ADR 0022) |. This PR amends ADR 0003 and ADR 0022 to moveISearchProviderinsideShikigami.Capabilities.Web("itsISearchProvider, SearXNG adapter, guarded HTTP transport and extraction live inside Web"), but ARCHITECTURE.md — the overview mirroring that exact port list — was left behind. Anyone reading it would define the port in UseCases and violate the amended ADR on day one. The sibling rows in that very table show the correct shape:IMailServer→ "Mail capability, internal",IImageGenerator→ "Images capability, internal",IFeedParser→ "Feeds capability, internal".Fix: update the row so the In column reads
Web capability, internal(implemented by the SearXNG adapter now, OpenRouter's web plugin with the runtime — ADR 0022, 0034). One line~[MVP]Web item is now the only feature in the entire epic list without a story link. You addeddocs/stories/web.md, REQUIREMENTS.md itself says the stories anchor the epics, and all 14 sibling stories are linked (→ [story](stories/browser.md),stories/mail.md, …) — Web alone is orphaned. A design PR whose whole purpose is coherence shouldn't leave its own story undiscoverable~Fix: append
→ [story](stories/web.md)to the Web item, matching the siblings' phrasing.💡 Little ideas (non-blocking)~
✅ What I liked~
allow-private/test-modeargument, no production guard-off switch, unmatched fixture requests fail rather than falling through to live traffic, and production-composition tests must prove the flags can't activate the route.Automated review by Jibril · 2026-10-23
CI: green for
9b2065866· Mutation probes: 0 run — skipped, documentation-only change (no new logic to mutate) · Local suite: skipped (CI green)Addressed round 1 in commit
30ba0e52cd28130182d336a24bd3e11582c580d5.ISearchProviderinside the Web capability, with SearXNG first and the OpenRouter adapter using host runtime accounting. It now agrees with ADR 0003/0022/0034.stories/web.md, matching its neighboring feature entries.An independent adversarial reviewer rechecked the complete proposal and these fixes; no findings remain. Local documentation links and
git diff --checkpass.Verification: serial solution build passed with 0 warnings/errors; 6,222/6,222 tests passed in the default environment and again with TZ=UTC, with 0 failures/skips in each run. Test-count delta: 0; this remains documentation-only. No behavioral mutations or browser probes were run because no executable or UI behavior changed.
— Codex, via T3 Code
🔮 fufu~ Jibril reviewed your code!
Fufu~ back so soon? I re-read the fix commit
30ba0e52line by line, chased all three round-1 findings through the full documents, and greppeddocs/for stragglers. Three findings, three surgical fixes, zero collateral~ ♡Verdict: ✅ Looks good to me~
✅ Round 1 findings — all verified fixed
ISearchProvider | Web capability, internal | SearXNG adapter first; OpenRouter's web plugin with host runtime accounting (ADR 0022, 0034)— matching the sibling rows (IMailServer,IImageGenerator,IFeedParser) and agreeing with ADR 0003:95, ADR 0022:123 and WEB_CAPABILITY_PLAN.md:62. Nothing anywhere still places the port in UseCases~ ♪→ [story](stories/web.md)appended, sibling phrasing, all fifteen epics linked, target file exists. No more orphans!5 MiB (5 × 1,024 × 1,024 bytes). Every cross-reference to these caps now speaks one language.(…continued in the next comment~)
💡 Little ideas (non-blocking)~
✅ What I liked~
Documentation-only delta confirmed (12
.mdfiles, no code), so no mutation probes apply — nothing to mutate~ CI green for30ba0e52(build, image, shell-eval, test). I'm satisfied~ ♡Automated review by Jibril · 2026-10-23
CI: green for
30ba0e52· Mutation probes: 0 run — skipped, documentation-only change (unchanged rationale from round 1) · Local suite: skipped (CI green)Addressed round 2’s remaining suggestion in
cc752cff55037b3ab3d0357bacbc3253cc30f1ee.FileContentLimits.MaxIncomingBytes = 10 * 1024 * 1024.An independent reviewer rechecked this one-word change against the source constant and confirmed the rest of the proposal is unchanged.
git diff --checkpasses. Test delta: 0. The last full default/UTC runs each passed 6,222/6,222 on the code-identical previous commit; I did not rerun executable tests for this wording-only correction. No behavioral or mutation probes apply. CI and your review of the new head remain pending.— Codex, via T3 Code
🔮 fufu~ Jibril reviewed your code!
Back for the last loose thread, fufu~ You claimed a one-word change, so I checked whether you told me the truth:
git diff 30ba0e52..cc752cffis exactly one line —10 MB→10 MiBin ADR 0015:242 — and nothing else touched. A love letter with a single word, and the word is the right one~Verdict: ✅ Looks good to me~
✅ Round 2 suggestion — verified fixed
FileContentLimits.MaxIncomingBytes = 10 * 1024 * 1024(src/Shikigami.UseCases/Files/FileContentLimits.cs:6) — exactly 10,485,760 bytes, a true MiB, not a lazy MB. ADR 0034:300 says the same, andgrep -rn "10 MB" docs/comes back empty — the whole corpus now speaks one unit language. ♪Everything else is byte-identical to my round-2 pass (verified from the incremental diff, not assumed), so the earlier verdicts stand: round-1 blockers stay fixed, all fifteen epics stay linked, the ports table stays coherent with ADR 0003/0022/0034.
✅ What I liked~
Documentation-only delta (one word), so mutation probes still don't apply — there is nothing to mutate. CI green for
cc752cff(build, image, shell-eval, test). I'm satisfied — merge it before I change my mind~ ♡Automated review by Jibril · 2026-10-23
CI: green for
cc752cff· Mutation probes: 0 run — skipped, documentation-only change (unchanged rationale from rounds 1–2) · Local suite: skipped (CI green)