refactor: repository-wide structure and naming audit#263
Open
Menci wants to merge 4 commits into
Open
Conversation
Repository-wide structure and naming audit, round 1. Every directory and every named concept was reviewed independently, and the surviving changes are the ones that leave observable behavior identical while making the tree read the way it would if written today. Ownership moves. `FileProvider` becomes `FileStore` and the channel-broker contract joins it in `@floway-dev/platform`, so the runtime seam is declared in one package instead of two. GitHub device-flow and quota wire helpers move out of the control plane into `provider-copilot`, leaving the gateway with the routes and none of the vendor knowledge. Session-token generation moves under `repo/`, chat attempt helpers gain a coherent home, and orphaned tests rejoin their subjects. Dead surface removed. The orphan Responses item views, the obsolete interceptor context type, unreachable env/Azure/Copilot/Codex helpers, stale export-map subpaths, and inert JSX compiler options are gone. `capabilities` in `protocols` is renamed to `endpoints`, matching what it actually enumerates, and the telemetry view is renamed to the usage view it became. Test discovery repaired. The root Vitest config listed projects by hand and had drifted, so `provider-ollama`'s suites never ran; projects are now discovered by glob. Documentation corrected. Both pricing skills described a retired schema and a cost formula off by a factor of a million — following them against production D1 would have written wrong rates. AGENTS.md and README.md now describe the architecture that exists.
Second audit round over the backend tree (directory structure, concept naming, identifier names). Every directory and concept was reviewed independently by two models; a decider merged the reports into eleven work items partitioned by exclusive file ownership, and one implementer executed each. Behavior is unchanged. Wire protocols, HTTP status/headers/bodies, routing outcomes, persisted names, migrations, affinity bytes, provider account state, and the frontend contract are all untouched; the round rejected every proposal that could not prove that property. What moved: - Backend scripts, package Vitest configs, and Agent Setup installer fragments gain checked sources of truth. The fragment inventory lives only in the generator, and the installer harness now executes the same bytes the routes serve instead of rebuilding a second ordering. - The gateway core is recomposed around its consumers: the provider registry splits into composition, catalog, and resolution; the request context moves out of the chat subtree; affinity absorbs candidate narrowing; scheduled cleanup leaves the repository layer. - Protocols own their vocabulary and codecs, with the pricing engine in its own module and the identity pricing aliases removed. Providers take back their vendor wire knowledge. The interceptor's second slot is named for what it carries. - Platform implementations are named after the contracts they implement. - Architecture specifications are rewritten against the resulting tree.
Found while auditing the two landed refactor commits against the tree.
The README's Custom-provider row claimed live catalog discovery accepts
an OpenAI-compatible `/models` only. The parser accepts three shapes —
OpenAI, Anthropic, and the superset — so the row understated it.
The PowerShell installer test searched for `function Set-ScriptAgent {`
while the fragments define `Set-SetupAgent`. `indexOf` returned -1, so
the ordering assertion degraded to `29331 > -1` and could no longer fail.
The agent function was renamed without its assertion following.
Audited the two preceding commits against the tree, one job per landed work item and one per rejection, then executed what the audit recovered. The audit found the branch behavior-preserving: every accepted item preserves observable behavior, migrations are untouched, and every route literal, error code, and status literal is unchanged. What it found instead was residue. The rejection categories covered renames, moves, sweeps, decompositions, and behavior changes; none of them covered "make this statement true", so factual comment corrections had neither an owner nor a rejecter and fell through unadjudicated. Nine in ten of the recovered items are correctness work of that kind. Corrected the statements the code falsifies, across the operator skills, AGENTS.md, README.md, the routing and translation specifications, and the gateway, provider, protocols, translate, and vendor-package comments. The TTFT anchor is now described the same way in all three of its homes: the interval includes the gateway's own egress work and excludes pre-dispatch work, and clears per candidate, so a recorded interval after failover is shorter than what the client observed. Deleted declarations a fresh census proves unreachable, and extracted what two callers had been copying: the constant-time comparison, the JSON passthrough preflight, the egress-probe IP grammar, the WebP quality constant, the workerd WebSocket test double, and the Copilot upstream-config grammar, which moves into the Copilot package with both parsers intact — they diverge on blank githubToken and must. Closed three verification gaps. The affinity carrier now has a golden vector generated from the codec itself, and each chat protocol has an egress-to-ingress round trip through its real reassembler, so the AAD domain is linked across the membrane rather than discarded by a stub. The HTTP header-overflow limit is asserted at parser level again, and the assembled installer bodies are checked against an independently restated section tiling. Every new assertion was mutation-checked. Pinned the OverlayScrollbars patch key to its version: a bare key makes pnpm treat a failed patch as a warning rather than an error.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A rolling audit of the repository's directory structure, concept boundaries,
and identifier names. Every directory and every named concept is reviewed
independently; the changes that land are the ones that leave observable
behavior identical while making the tree read the way it would if it were
written today. Rounds accumulate on this branch, one commit each.
Round 1
FileStore, andChannelBrokernow liveswith the other platform contracts instead of behind a gateway export.
provider-copilot,while every control-plane route and wire result remains unchanged.
translateandprotocolslose orphaned views, duplicate assertions, deadhelpers, and misleading module names, without changing the package surfaces
the dashboard consumes.
capabilitiesbecomesendpoints, which is what itenumerates.
test ownership now match their actual lifecycle stages.
restores
provider-ollama's suites — they had silently stopped running.guidance, and stale code comments are synchronized with the current code.
Both pricing skills described a retired schema and a cost formula off by a
factor of a million; following them against production D1 would have written
wrong rates.
Route paths, wire bodies and headers, routing outcomes, stored schemas,
migrations, affinity bytes,
apps/web/, andpackages/ui/are deliberatelyunchanged.
pnpm run test(402 files, 4861 tests),pnpm run lint, andpnpm run typecheckall pass.