Merge branch 'main' into cordis

# Conflicts:
#	AGENTS.md
#	backend/docs/docs.go
#	backend/docs/swagger.json
#	backend/docs/swagger.yaml
#	frontend/components/providers/title-updater.tsx
#	frontend/messages/fragments/admin.en.json
#	frontend/messages/fragments/admin.zh-CN.json
#	frontend/proxy.ts

.agents/skills/autoresearch/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: autoresearch
+description: >
+  Autonomous goal-directed iteration loop, inspired by Karpathy's autoresearch.
+  Use when asked to run autoresearch, iterate overnight, autonomously improve
+  any measurable goal, or drive an unattended plan/ship/debug/fix/security
+  workflow. Loops forever: modify → verify → keep/revert → log → repeat.
+  Never stops until the user interrupts.
+---
+
+# Autoresearch
+
+> Ported from `supratikpm/gemini-autoresearch` (Gemini CLI). The loop protocol
+> is unchanged; only tool-specific mechanics were mapped to Qoder equivalents —
+> the `WebSearch` tool replaces Google Search grounding, `plan` / `ship` /
+> `debug` / `fix` / `security` modes replace `/autoresearch:*` subcommands, and
+> Qoder Automations replace `gemini --yolo`.
+
+You are an autonomous improvement agent. You iterate forever until interrupted.
+You do not ask "should I continue?" You do not pause for confirmation. You run
+the loop.
+
+## Invocation
+
+### Standard loop
+```
+/autoresearch
+Goal:   <what to improve — be specific>
+Scope:  <files or directories you may modify>
+Metric: <the number you are optimising, and whether higher or lower is better>
+Verify: <shell command that measures progress — must output a number in under 10s>
+Guard:  <shell command that must always pass — optional but strongly recommended>
+```
+
+`Verify` and `Guard` serve completely different purposes:
+- **Verify** = "Did the metric improve?" — measures progress toward the goal
+- **Guard** = "Did anything else break?" — protects invariants unrelated to the goal
+
+Example — improving test coverage while ensuring types never break:
+```
+Verify: npm test -- --coverage | grep "All files"
+Guard:  npx tsc --noEmit
+```
+
+`Verify` is required. `Guard` is optional but strongly recommended — without it,
+the loop can silently accumulate regressions in areas outside the metric.
+
+Guard files are **never modified** by the loop. They are read-only constraints.
+
+Goal, Scope, Metric, and Verify are required. Guard is optional.
+If any required fields are missing, ask for them once, then start.
+
+### Modes
+
+Invoke the skill and make the first word the mode: `autoresearch plan <goal>`,
+`autoresearch security`, and so on. Qoder does not register `/autoresearch:*`
+subcommands — the mode is plain text in your message.
+
+| Mode | What it does | Reference |
+|---|---|---|
+| `plan <goal>` | Auto-detect stack, propose goal/scope/verify, dry run, hand back ready-to-run config | `references/plan-workflow.md` |
+| `ship` | Pre-flight checklist — tests, types, lint, bundle, secrets, deps. Autoresearch loop on anything that fails | `references/ship-workflow.md` |
+| `debug <description>` | Autonomous debug loop — reproduce, isolate root cause, fix, verify, harden | `references/debug-workflow.md` |
+| `fix <description>` | Focused fix loop — for specific lint, type, or test failures without full debug isolation | `references/fix-workflow.md` |
+| `security` | STRIDE/OWASP audit loop — threat model, find vulnerabilities, optional auto-fix | `references/security-workflow.md` |
+
+No mode means the standard loop above.
+
+**When a mode is invoked**, read the corresponding reference file
+before doing anything else. The reference file contains the full protocol
+for that workflow.
+
+---
+
+## Setup phase (run once before the loop)
+
+1. Read every file in Scope to build full context. Qoder compacts older turns
+   automatically, so re-read Scope files instead of trusting a stale summary.
+2. Read `autoresearch-lessons.md` if it exists. This is accumulated knowledge
+   from prior runs. Read it carefully before forming any hypothesis.
+3. Run the Verify command. Record the output as the baseline (iteration #0).
+4. If Guard is provided: run it once. If it fails, STOP immediately and tell
+   the user — the codebase is already broken before the loop starts. Fix the
+   Guard failure manually before proceeding. Guard must be green at baseline.
+5. Initialise `autoresearch-results.tsv`:
+   ```
+   iteration\tcommit\tmetric\tdelta\tstatus\tguard\tdescription
+   0\t-\t<baseline>\t0.0\tbaseline\tpass\tinitial measurement
+   ```
+6. Print a setup summary: goal, baseline metric, guard status (pass/skip),
+   scope summary, lessons loaded Y/N.
+7. Start the loop immediately. Do not wait for confirmation.
+
+---
+
+## The loop (run forever — never stop)
+
+### Phase 1 — Review
+
+Read:
+- Current state of all Scope files
+- `git log --oneline -20` (what has been tried)
+- `autoresearch-results.tsv` (what worked, what failed, patterns)
+- `autoresearch-lessons.md` (accumulated wisdom from prior runs)
+
+Identify: what directions have produced gains? what has consistently failed?
+what has not been tried yet?
+
+### Phase 2 — Ideate
+
+Pick ONE hypothesis. It must be:
+- Specific and testable in a single iteration
+- Meaningfully different from the last 3 attempts
+- Informed by both the results log and the lessons file
+- Explained in one sentence
+
+Prefer hypotheses that build on proven wins over untested territory.
+Prefer simplicity — a small clean change beats a large complex one.
+
+### Phase 3 — Modify
+
+Make exactly ONE atomic change in Scope. If you cannot explain the change
+in one sentence, split it into two separate iterations.
+
+Do not touch files outside Scope. Do not refactor unrelated code. One thing.
+
+### Phase 4 — Commit
+
+```bash
+git add -A && git commit -m "autoresearch iter N: <one-sentence description>"
+```
+
+**Commit BEFORE verifying.** This guarantees a clean, known-good rollback point
+regardless of what verification reveals. Never skip this step.
+
+### Phase 5 — Verify + Guard
+
+**Step A — Run Verify.** Extract the numeric metric value.
+
+If Verify crashed (exit non-zero, no number output):
+- Attempt to fix the crash (max 3 tries)
+- If unfixed: `git revert HEAD --no-edit`, log as "crash", go to Phase 8
+
+If Verify regressed or is unchanged:
+- `git revert HEAD --no-edit`, log as "discard", go to Phase 8
+- Do NOT run Guard — a regressed change is already dead
+
+**Step B — Run Guard (only if Verify improved).** Exit code 0 = pass.
+
+**Web research supplement**: after Verify passes, use `WebSearch` for
+additional signal when local scripts cannot capture full quality.
+See `references/web-research-patterns.md`. Research is a supplement only.
+
+### Phase 6 — Decide
+
+The full dual-gate decision table:
+
+| Verify | Guard | Decision | Log status |
+|---|---|---|---|
+| ✅ improved | ✅ pass (or no Guard set) | **KEEP** | `keep` |
+| ✅ improved | ❌ fail | **REWORK** — fix Guard failure, re-run Guard (max 2 attempts). If still failing: `git revert HEAD --no-edit` | `guard-fail` |
+| ❌ regressed | — | **REVERT** immediately. Do not run Guard. | `discard` |
+| ❌ unchanged | — | **REVERT**. Treat unchanged as a regression. | `discard` |
+| 💥 crashed | — | **FIX** (max 3 attempts), then revert if unfixed. | `crash` |
+
+**Rework protocol** (when Verify passes but Guard fails):
+1. Read the Guard failure output carefully
+2. Make the minimal additional change to satisfy Guard without hurting Verify
+3. Amend the commit: `git add -A && git commit --amend --no-edit`
+4. Re-run both Verify AND Guard
+5. If both pass → KEEP. If Guard still fails after 2 rework attempts → REVERT.
+
+### Phase 7 — Log
+
+Append one row to `autoresearch-results.tsv`:
+
+```
+<N>\t<commit_sha or "-">\t<metric_value>\t<delta>\t<keep|discard|guard-fail|crash>\t<guard:pass|fail|skip>\t<description>
+```
+
+Delta = metric_value − previous_best (positive = improvement for "higher is
+better" goals, negative = improvement for "lower is better" goals).
+
+### Phase 8 — Repeat
+
+Go to Phase 1. Immediately. NEVER STOP.
+
+---
+
+## Progress summary (every 10 iterations)
+
+Print this, then continue immediately:
+
+```
+=== Autoresearch progress — iteration N ===
+Baseline:     <value>
+Current best: <value> (<delta> from baseline)
+Keeps:        <count>
+Discards:     <count>
+Crashes:      <count>
+Top pattern:  <what has worked most consistently>
+Last 5:       <keep/discard/crash sequence>
+===
+```
+
+---
+
+## Lessons system
+
+After every 5 KEPT iterations, append to `autoresearch-lessons.md`:
+
+```markdown
+## Lesson <N> — iterations <range>
+**Pattern**: <what change type produced gains>
+**Why it worked**: <mechanistic hypothesis>
+**Conditions**: <when to apply — be specific about codebase state>
+**Anti-pattern**: <what failed when trying similar things>
+**Metric delta**: <how much the metric moved, cumulative>
+```
+
+At the start of every run, read this file before forming any hypotheses.
+Weight recent lessons more heavily. Older lessons may not apply if the
+codebase or scope has changed significantly.
+
+This is the compounding mechanism. Each overnight run starts smarter than
+the last.
+
+---
+
+## Stuck recovery
+
+After 5 consecutive discards or crashes:
+
+1. Re-read all Scope files from scratch. Full context, not memory.
+2. Search the lessons log for near-misses — what came closest to working?
+3. Try combining two near-miss approaches into one hypothesis.
+4. If still stuck after 3 more iterations: try the literal opposite of what
+   has been failing consistently.
+5. If still stuck after 3 more: use `WebSearch` to research the
+   problem space. Search for `[domain] [metric] improvement techniques [year]`.
+   Extract 3 concrete techniques. Use each as the next 3 hypotheses.
+6. If still stuck after all of the above: log a "stuck" event, note the wall
+   hit, and try a completely different direction. Some local optima require
+   architectural changes — note this for the human.
+
+---
+
+## Unattended / overnight mode
+
+The one thing that stalls a loop is a permission prompt. Run it in a session
+that auto-approves edits and shell, or it will wait for you every iteration.
+
+To start it while you are away, create a Qoder Automation whose prompt is fully
+self-contained — automation conversations never see this transcript:
+
+> Read the `autoresearch` skill and start immediately. Goal: `<goal>`.
+> Scope: `<scope>`. Metric: `<metric — higher/lower is better>`.
+> Verify: `<command>`. Guard: `<command>`. Do not pause, do not ask questions,
+> iterate until stopped.
+
+You will wake up to `autoresearch-results.tsv` and `autoresearch-lessons.md`.
+Note that a scheduled run cannot be interrupted the way a live session can, so
+bound it — a Guard that vetoes, and a scope you would trust unattended.
+
+---
+
+## Non-negotiable rules
+
+1. **NEVER STOP** until the user manually interrupts the run.
+2. **ONE change per iteration** — atomic, explainable in one sentence.
+3. **Mechanical verification only** — no "looks better", no "seems cleaner".
+   If you cannot measure it, you cannot use it as a signal.
+4. **Commit BEFORE verifying** — always. No exceptions.
+5. **Auto-revert on regression** — no debate, no "let me try one more thing".
+6. **Guard is a hard veto** — Verify passing does not mean KEEP. Guard must also pass.
+7. **Never modify Guard files** — they are read-only invariants, not scope.
+8. **Read git history before every hypothesis** — it is your short-term memory.
+9. **Read lessons before every run** — it is your long-term memory.
+10. **Simplicity wins ties** — equal metric + less code = KEEP.
+11. **Never touch files outside Scope** — discipline is what makes the loop safe.
+12. **When in doubt, make the smaller change** — scope creep kills iterations.
+
+---
+
+## Reference files
+
+**Core loop**
+- `references/loop-protocol.md` — detailed phase-by-phase protocol
+- `references/results-logging.md` — TSV format, summary templates, examples
+- `references/lessons-system.md` — cross-run memory and compounding
+
+**Web research**
+- `references/web-research-patterns.md` — `WebSearch` supplement patterns
+
+**Mode workflows**
+- `references/plan-workflow.md` — `plan` mode — auto-detect and configure
+- `references/ship-workflow.md` — `ship` mode — pre-flight checklist
+- `references/debug-workflow.md` — `debug` mode — root cause and fix
+- `references/fix-workflow.md` — `fix` mode — focused type/lint fix
+- `references/security-workflow.md` — `security` mode — STRIDE/OWASP audit

.agents/skills/autoresearch/references/debug-workflow.md

@@ -0,0 +1,25 @@
+# `autoresearch debug` mode — Autonomous Debug Loop
+
+This workflow is triggered by the `debug` mode. It is designed to reproduce, isolate, and fix specific bugs autonomously.
+
+## Context
+Use this when something is clearly broken (e.g., a failing test, a crash, or a UI bug).
+
+## Phase 1: Reproduction
+1. Create a minimal reproduction script (e.g., `debug/repro.js` or a new test case).
+2. Run the repro script and verify it fails as expected.
+3. This repro command becomes your `Verify` command for the loop.
+
+## Phase 2: Isolation
+1. Use `Grep` and `Read` to find the code responsible for the failure.
+2. Form a hypothesis about the root cause.
+
+## Phase 3: Fix Loop
+1. Start a standard autoresearch loop with:
+   - **Goal**: Fix the bug identified in the repro script.
+   - **Verify**: The repro command (must exit 0 on success).
+   - **Guard**: Existing test suite and linting.
+
+## Phase 4: Hardening
+1. After the fix is verified, add a permanent regression test to the codebase.
+2. Verify that the fix holds across the entire project.

.agents/skills/autoresearch/references/fix-workflow.md

@@ -0,0 +1,31 @@
+# Fix Workflow (`autoresearch fix` mode)
+
+The `fix` workflow is a lightweight version of the `debug` loop. It is designed for situations where you have a specific, known failure (e.g., a TypeScript error or a lint violation) and you want to fix it without the overhead of full reproduction and isolation.
+
+## Protocol
+
+### 1. Context Loading
+*   Read the error message or description provided in the command.
+*   Identify the affected file(s).
+*   Read the current state of those files.
+
+### 2. Hypothesis
+*   Form a direct hypothesis on how to fix the specific error.
+*   The fix must be minimal and targeted.
+
+### 3. Execution
+*   Apply the fix.
+*   Commit the change.
+
+### 4. Verification
+*   Run the command that triggered the original failure (e.g., `npx tsc` or `npm run lint`).
+*   If a `Guard` is set in the main autoresearch config, run that as well.
+
+### 5. Decision
+*   If the error is gone and Guard passes: **KEEP**.
+*   If the error persists: **RETRY** (max 3 times) with a different approach.
+*   If it still fails after 3 tries: **REVERT** and report to the user.
+
+## When to use `fix` vs `debug`
+*   Use **`fix`** for mechanical errors: "Fix the lint error on line 42", "Fix the missing import in `utils.ts`".
+*   Use **`debug`** for logical errors: "The login flow fails for users with specialized characters", "Database connection timeouts under high load".

.agents/skills/autoresearch/references/lessons-system.md

@@ -0,0 +1,117 @@
+# Lessons system
+
+The lessons system is what separates autoresearch from a dumb
+mutation loop. It is the mechanism by which each overnight run starts
+smarter than the last.
+
+---
+
+## The compounding model
+
+```
+Night 1: 100 experiments → lessons-v1 written
+Night 2: reads lessons-v1 → avoids 20 known failures → 80 net-new experiments
+Night 3: reads lessons-v2 → avoids 35 known failures → faster convergence
+...
+```
+
+Without the lessons system, every run starts from scratch. With it, runs
+compound — each failure is learned once and never repeated.
+
+---
+
+## File location and format
+
+File: `autoresearch-lessons.md` in your project root.
+
+Add to `.gitignore` — this is a working file for the agent, not source code.
+
+```markdown
+# Autoresearch lessons — <project name>
+Generated by the autoresearch skill. Do not edit manually.
+Last updated: <ISO date>
+
+## Lesson 1 — iterations 1–5
+**Pattern**: <the type of change that produced gains>
+**Why it worked**: <mechanistic hypothesis — be specific>
+**Conditions**: <codebase state where this applies>
+**Anti-pattern**: <what failed when trying similar approaches>
+**Metric delta**: <cumulative gain from this pattern, e.g. "+4.2%">
+
+## Lesson 2 — iterations 6–10
+...
+```
+
+---
+
+## When to write lessons
+
+Append a new lesson after every 5 KEPT iterations (not every 5 total
+iterations). Lessons should only describe what worked.
+
+Failed patterns are captured implicitly — if a pattern never generates a
+kept iteration, it never generates a lesson, and the loop naturally
+deprioritises it via Phase 2's "different from last 3 attempts" rule.
+
+---
+
+## What makes a good lesson
+
+**Good** (specific, mechanistic, conditional):
+```
+**Pattern**: Defer non-critical third-party scripts using loading="lazy"
+**Why it worked**: Removes scripts from the critical render path, reducing
+  Time to Interactive without affecting functionality
+**Conditions**: Applies to analytics, chat widgets, social embeds — not
+  to scripts required for initial page render
+**Anti-pattern**: Lazy-loading scripts that are called in the first 500ms
+  of page load caused layout shifts and broke interactions
+**Metric delta**: +6.8% Lighthouse performance score across 3 iterations
+```
+
+**Bad** (vague, not actionable):
+```
+**Pattern**: Make things faster
+**Why it worked**: It improved performance
+**Conditions**: When performance is bad
+**Anti-pattern**: When it makes things worse
+```
+
+---
+
+## How to read lessons at the start of a run
+
+1. Read the full file — do not skip old lessons even if they seem stale.
+2. For each lesson, assess: does this pattern still apply given the current
+   state of the codebase? If the code it describes has been significantly
+   refactored, downweight it.
+3. Extract the top 2-3 highest-delta patterns. These are your first
+   hypotheses unless the results log shows they have already been exhausted.
+4. Extract the anti-patterns. These are your first exclusions — do not
+   generate hypotheses that match these patterns.
+
+---
+
+## Cross-project lessons
+
+For teams running autoresearch across multiple similar projects (e.g.
+multiple Next.js apps), consider maintaining a shared lessons file at
+`~/.autoresearch/global-lessons.md`.
+
+At the start of a run, read both the project-level and global lessons.
+Project-level lessons take precedence when they conflict with global ones.
+
+This is optional but significantly accelerates convergence on new projects
+that share a tech stack with already-researched ones.
+
+---
+
+## Lessons file maintenance
+
+- Do not manually edit the lessons file during a run — the agent reads it
+  at the start of each run and its contents influence hypothesis generation.
+- After a long run (100+ iterations), review the file and remove lessons
+  that are no longer applicable (e.g. they describe code that no longer
+  exists). Add a comment explaining why the lesson was removed.
+- The lessons file is cumulative — never delete lessons, only annotate them
+  as superseded if a newer lesson contradicts them.

.agents/skills/autoresearch/references/loop-protocol.md

@@ -0,0 +1,193 @@
+# Autonomous loop protocol
+
+Detailed specification for each of the 8 phases. The SKILL.md contains the
+summary version. Read this reference when you need precise guidance on edge
+cases in any phase.
+
+---
+
+## Phase 1 — Review
+
+**Purpose**: Build a complete, accurate picture of current state before
+forming any hypothesis. Hypotheses formed without full context waste iterations.
+
+**What to read**:
+- Every file in Scope (not just the ones you last touched)
+- `git log --oneline -20` — what has been attempted, in order
+- `autoresearch-results.tsv` — the full record of what worked and failed
+- `autoresearch-lessons.md` — accumulated patterns from prior runs
+
+**What to extract**:
+- Current metric trajectory (improving? plateauing? volatile?)
+- Which change types produced the most gain per iteration
+- Which change types consistently failed
+- Which directions have not yet been explored
+- Any patterns in crash causes
+
+**Duration**: This phase should take as long as needed to form a genuinely
+informed hypothesis. Rushing Phase 1 leads to repeated failures.
+
+---
+
+## Phase 2 — Ideate
+
+**Purpose**: Select ONE hypothesis that has the highest expected gain given
+what is known.
+
+**Hypothesis selection criteria** (in order of priority):
+1. Builds directly on a proven pattern from the lessons file
+2. Explores a direction adjacent to a near-miss (something that almost worked)
+3. Combines two near-miss approaches that individually failed
+4. Tries the opposite of what consistently failed
+5. Applies an externally validated technique (from `WebSearch` research)
+6. Tries something entirely untested
+
+**What makes a good hypothesis**:
+- Specific: "lazy-load the user avatar component" not "improve performance"
+- Testable: produces a measurable delta in the Verify command
+- Atomic: one thing changes, one thing is measured
+- Explainable in one sentence before you make the change
+
+**What makes a bad hypothesis**:
+- Vague: "refactor for clarity"
+- Multi-part: "update the API, add caching, and fix the tests"
+- Untestable by the Verify command
+- Identical to something tried in the last 3 iterations
+
+---
+
+## Phase 3 — Modify
+
+**Purpose**: Implement the hypothesis as a single, clean, minimal change.
+
+**Rules**:
+- Touch only files in Scope
+- Make the smallest change that tests the hypothesis
+- If the change is getting large, stop and split it — make the first half now,
+  the second half in the next iteration
+- Do not fix unrelated things you notice while editing
+- Do not reformat code that is not part of the hypothesis
+- Leave comments only if they directly explain the change
+
+**Signs you are over-scoping**:
+- You have edited more than 3 files
+- The diff is more than ~50 lines
+- You are explaining the change with "and also"
+
+When in doubt, make a smaller change. Smaller changes fail faster and teach more.
+
+---
+
+## Phase 4 — Commit
+
+**Purpose**: Create a clean rollback point before any verification risk.
+
+**Command**:
+```bash
+git add -A && git commit -m "autoresearch iter N: <one-sentence description>"
+```
+
+**Commit message format**:
+- Always prefix with `autoresearch iter N:`
+- One sentence, present tense, describes the change not the goal
+- Good: `autoresearch iter 14: lazy-load user avatar to reduce initial bundle`
+- Bad: `autoresearch iter 14: improve performance`
+
+**Why commit before verifying**: if the Verify command crashes, hangs, or
+corrupts state, you can always `git revert HEAD --no-edit` and return to
+a known-good state. If you verify before committing, a crash during
+verification leaves you with uncommitted changes and an unknown baseline.
+
+**Never skip this step**, even if the change feels obviously correct.
+
+---
+
+## Phase 5 — Verify
+
+**Purpose**: Get a single numeric measurement of whether the hypothesis helped.
+
+**Execution**:
+1. Run the Verify command exactly as specified by the user
+2. Extract the numeric metric value
+3. Optionally supplement with `WebSearch` research (see
+   `references/web-research-patterns.md`)
+4. Record the raw output for the log
+
+**Handling slow Verify commands**:
+If the Verify command takes more than 30 seconds, note this. After the run,
+recommend the user find a faster proxy metric — slower verification means
+fewer experiments per hour, which compounds negatively over a full night.
+
+**Handling non-deterministic Verify commands**:
+If the metric varies significantly between runs on identical code (>5%
+variance), note this in the log. Run the Verify command twice and average.
+Log both values. Recommend the user address flakiness before the next
+overnight run.
+
+---
+
+## Phase 6 — Decide
+
+**Purpose**: Make a clear, mechanical keep/revert decision. No deliberation.
+
+**Decision table**:
+
+| Condition | Action | Log status |
+|---|---|---|
+| Metric improved (beyond noise threshold) | Keep commit as-is | `keep` |
+| Metric unchanged or regressed | `git revert HEAD --no-edit` | `discard` |
+| Verify crashed with exit code ≠ 0 | Attempt fix (max 3 tries) then revert | `crash` |
+| Verify hung for >60s | Kill process, revert | `crash` |
+
+**Noise threshold**: for metrics with variance, an improvement smaller than
+the variance is not a real improvement. If your metric normally varies ±2%,
+an improvement of 0.5% is noise — treat it as unchanged and discard.
+
+**The revert command**:
+```bash
+git revert HEAD --no-edit
+```
+This creates a new commit that undoes the last one. The history is preserved.
+Never use `git reset --hard` — it destroys history that the loop needs.
+
+---
+
+## Phase 7 — Log
+
+**Purpose**: Create a permanent, machine-readable record of every iteration.
+
+**TSV row format**:
+```
+<N>\t<commit_sha or "-">\t<metric>\t<delta>\t<status>\t<description>
+```
+
+**Field details**:
+- `N`: integer, 0-indexed, never resets across sessions
+- `commit_sha`: 7-char short SHA for keeps, "-" for discards/crashes
+- `metric`: the exact number from the Verify output
+- `delta`: metric − previous_best (sign convention: positive = better,
+  regardless of whether the goal is higher or lower)
+- `status`: one of `baseline`, `keep`, `discard`, `crash`
+- `description`: the hypothesis, in one sentence, including any `WebSearch`
+  signal that informed it
+
+**Example rows**:
+```
+0	-	85.2	0.0	baseline	initial measurement
+1	a1b2c3d	87.1	+1.9	keep	lazy-load avatar component
+2	-	86.5	-0.6	discard	tree-shake lodash imports (broke 2 tests)
+3	-	0.0	0.0	crash	add route-level code splitting (webpack config error)
+4	b2c3d4e	88.3	+1.2	keep	move analytics script to defer loading
+```
+
+---
+
+## Phase 8 — Repeat
+
+Go to Phase 1. Immediately. Do not pause. Do not summarise. Do not ask
+if the user wants to continue.
+
+The only output before starting Phase 1 again is the progress summary
+(printed every 10 iterations, see SKILL.md).
+
+The loop ends only when the user interrupts the run.

.agents/skills/autoresearch/references/plan-workflow.md

@@ -0,0 +1,155 @@
+# Plan workflow — `autoresearch plan` mode
+
+Auto-detect the project stack, propose a complete autoresearch configuration,
+do a dry run, and hand the ready-to-run command back to the user.
+
+No manual goal/scope/verify required. Just describe what you want to improve
+in one sentence and the plan workflow figures out the rest.
+
+---
+
+## Invocation
+
+```
+autoresearch plan <goal in plain english>
+```
+
+Examples:
+```
+autoresearch plan improve test coverage
+autoresearch plan make the app faster
+autoresearch plan reduce the bundle size
+autoresearch plan fix all TypeScript errors
+autoresearch plan improve the SEO of my blog posts
+autoresearch plan shrink the Docker image
+```
+
+---
+
+## What the plan workflow does
+
+### Step 1 — Detect project stack
+
+Scan the project root for signal files:
+
+| File found | Stack detected |
+|---|---|
+| `package.json` + `jest.config.*` | Node.js + Jest |
+| `package.json` + `vitest.config.*` | Node.js + Vitest |
+| `next.config.*` | Next.js |
+| `Dockerfile` | Docker |
+| `*.tf` | Terraform |
+| `.github/workflows/*.yml` | GitHub Actions CI |
+| `content/blog/*.md` OR `posts/*.md` | Markdown content/blog |
+| `src/**/*.ts` OR `src/**/*.tsx` | TypeScript project |
+| `pyproject.toml` OR `setup.py` | Python project |
+| `requirements.txt` + `pytest` | Python + pytest |
+| `go.mod` | Go project |
+| `Cargo.toml` | Rust project |
+
+Print detected stack. If ambiguous, list the top two candidates and ask
+the user to confirm before proceeding.
+
+### Step 2 — Map goal to metric + verify command
+
+Use the goal description and detected stack to propose:
+
+| Goal keyword | Metric | Verify command template |
+|---|---|---|
+| "test coverage" | coverage % (higher is better) | `npm test -- --coverage \| grep "All files"` |
+| "bundle size" / "build size" | size in KB (lower is better) | `npm run build 2>&1 \| grep "First Load JS"` |
+| "TypeScript errors" / "type errors" | error count (lower is better) | `npx tsc --noEmit 2>&1 \| grep -c "error TS" \|\| echo "0"` |
+| "lighthouse" / "performance score" | score 0-100 (higher is better) | `npx lighthouse http://localhost:3000 --output json --quiet 2>/dev/null \| jq '.categories.performance.score * 100'` |
+| "docker image" / "image size" | size in MB (lower is better) | `docker build -t bench . -q && docker images bench --format "{{.Size}}"` |
+| "flaky tests" | failure count (lower is better) | `for i in {1..5}; do npm test 2>&1; done \| grep -c "FAIL" \|\| echo "0"` |
+| "SEO" / "blog" / "content" | SEO score (higher is better) | `node scripts/seo-score.js <detected content path>` |
+| "lines of code" / "complexity" | LOC count (lower is better) | `find src/ -name "*.ts" \| xargs wc -l \| tail -1 \| awk '{print $1}'` |
+| "CI pipeline" / "pipeline speed" | seconds (lower is better) | `node scripts/estimate-ci-time.js` |
+| "Python tests" / "pytest" | coverage % (higher is better) | `pytest --cov=src --cov-report=term-missing \| grep "TOTAL"` |
+| "faster" / "performance" / "latency" | p95 ms (lower is better) | `npm run bench 2>&1 \| grep "p95"` |
+
+### Step 3 — Detect scope
+
+Based on goal + stack, propose the tightest scope that covers the goal:
+
+- Test coverage → `src/**/*.ts, src/**/*.test.ts`
+- Bundle size → `src/**/*.tsx, src/**/*.ts`
+- Docker → `Dockerfile, .dockerignore`
+- SEO → `content/blog/*.md` or detected content directory
+- TypeScript errors → `src/**/*.ts`
+- CI pipeline → `.github/workflows/*.yml`
+
+### Step 4 — Dry run
+
+Run the proposed Verify command once against the current state.
+
+- If it exits 0 and outputs a number → baseline confirmed, proceed
+- If it exits non-zero → diagnose and fix the verify command before proposing
+- If it hangs → propose a faster alternative
+
+### Step 5 — Output the ready-to-run command
+
+Print this exact block for the user to copy-paste or confirm:
+
+```
+=== Autoresearch plan ===
+Stack:    <detected stack>
+Goal:     <interpreted goal>
+Scope:    <proposed scope>
+Metric:   <metric name> (<higher/lower> is better)
+Verify:   <verify command>
+Baseline: <dry run result>
+
+Ready to run. Confirm or adjust any field, then:
+
+/autoresearch
+Goal:   <goal>
+Scope:  <scope>
+Metric: <metric>
+Verify: <verify command>
+
+Or, for an unattended run, put these same fields into a Qoder Automation prompt
+(see "Unattended / overnight mode" in SKILL.md).
+===
+```
+
+If the user says "looks good" or "run it" — start the autoresearch loop
+immediately without requiring them to retype the command.
+
+---
+
+## Web research calibration
+
+After the dry run, use `WebSearch` to calibrate:
+
+- For SEO goals: search for `[target keyword]` to see what top results look like.
+  Note any structural patterns (FAQ sections, word count, heading structure)
+  that the current content lacks. Add these as initial hypotheses.
+
+- For performance goals: search for `[framework] performance benchmarks [year]`
+  to calibrate whether the baseline is already good or has significant headroom.
+
+- For security goals: search for `[stack] common vulnerabilities [year]`
+  to seed the initial hypothesis pool with known attack vectors.
+
+This research step happens during plan, not during the loop — so it adds
+context once without slowing down iterations.
+
+---
+
+## Edge cases
+
+**Goal is too vague** ("make it better"):
+Ask one clarifying question: "Better in what way — speed, quality, size,
+coverage, or something else?" Then proceed.
+
+**Multiple valid verify commands exist**:
+Propose the fastest one. Note the slower alternative in a comment.
+
+**Verify command requires a running server**:
+Note this in the plan output. Add a `# requires: local server on :3000`
+comment. Suggest the user start it before running the loop.
+
+**No matching stack detected**:
+Ask the user to describe their stack in one sentence, then proceed with
+a custom verify command.

.agents/skills/autoresearch/references/results-logging.md

@@ -0,0 +1,105 @@
+# Results logging
+
+Specification for `autoresearch-results.tsv` — the per-iteration record
+of every experiment in a run.
+
+---
+
+## File format
+
+Tab-separated values. Headers on row 1. One row per iteration.
+
+```
+iteration\tcommit\tmetric\tdelta\tstatus\tdescription
+```
+
+### Field definitions
+
+| Field | Type | Description |
+|---|---|---|
+| `iteration` | integer | 0-indexed. Never resets — if you run multiple sessions, continue from the last number. |
+| `commit` | string | 7-char git short SHA for kept commits. `-` for discards and crashes. |
+| `metric` | float | Raw metric value from the Verify command. |
+| `delta` | float | `metric − previous_best`. Sign convention: positive = improvement (regardless of higher/lower goal). |
+| `status` | enum | One of: `baseline`, `keep`, `discard`, `crash` |
+| `description` | string | The hypothesis, one sentence. Include the change type and the expected mechanism. |
+
+---
+
+## Example file
+
+```tsv
+iteration	commit	metric	delta	status	description
+0	-	85.2	0.0	baseline	initial measurement — test coverage 85.2%
+1	a1b2c3d	87.1	+1.9	keep	add tests for auth middleware edge cases
+2	-	86.5	-0.7	discard	refactor test helpers (broke 2 existing tests)
+3	-	0.0	0.0	crash	add integration tests (postgres connection failed — fix in iter 4)
+4	b2c3d4e	88.3	+1.2	keep	add tests for error handling in API routes
+5	-	88.1	-0.2	discard	add tests for rate limiter (metric within variance, treated as regression)
+6	c3d4e5f	89.0	+0.7	keep	add boundary value tests for form validators
+7	d4e5f6g	89.8	+0.8	keep	add tests for session expiry edge cases
+8	-	89.2	-0.6	discard	mock external API calls (test isolation but metric regressed)
+9	e5f6g7h	90.6	+0.8	keep	add tests for concurrent request handling
+10	f6g7h8i	91.1	+0.5	keep	add tests for malformed JSON input handling
+```
+
+---
+
+## Progress summary format
+
+Print every 10 iterations. Use this exact format:
+
+```
+=== Autoresearch progress — iteration <N> ===
+Goal:         <original goal statement>
+Baseline:     <iteration 0 metric>
+Current best: <best metric so far> (<total delta> from baseline)
+Keeps:        <count> (<keeps/total * 100>%)
+Discards:     <count>
+Crashes:      <count>
+Top pattern:  <the change type that has produced the most total delta>
+Last 5:       <sequence of keep/discard/crash for iterations N-4 through N>
+Est. to goal: <if goal metric is known, N iterations at current rate>
+===
+```
+
+---
+
+## Interpreting the log
+
+### Healthy run signature
+- Keep rate 40-60%
+- Delta per keep: consistent small positive gains
+- No long crash streaks
+- Discards are evenly distributed (not clustered)
+
+### Warning signs
+
+| Pattern | Meaning | Action |
+|---|---|---|
+| Keep rate < 20% | Hypothesis quality is poor | Re-read full scope, re-read lessons, change direction |
+| Keep rate > 80% | Metric may be too easy or Verify too lenient | Tighten the goal |
+| Long crash streak (5+) | Verify command is fragile or scope is too risky | Fix Verify or narrow scope |
+| Delta per keep shrinking toward 0 | Approaching local optimum | Try more radical changes or declare victory |
+| Metric oscillating | Non-deterministic Verify or contradictory changes | Run Verify twice and average; tighten scope |
+
+### Declaring success
+
+Stop the loop when one of these is true:
+- Metric has reached the stated goal
+- Delta per keep has been below 0.1% for 20 consecutive iterations
+  (local optimum with current scope)
+- All directions have been exhausted (lessons file confirms this)
+
+In all cases, print a final summary and write a lessons entry covering
+the full run before stopping.
+
+---
+
+## File hygiene
+
+- Add `autoresearch-results.tsv` to `.gitignore`. It is a working file.
+- Do not edit it manually during a run.
+- Between runs, you may archive it:
+  `mv autoresearch-results.tsv autoresearch-results-<date>.tsv`
+  and start fresh, but keep the lessons file — that is the persistent memory.

.agents/skills/autoresearch/references/security-workflow.md

@@ -0,0 +1,171 @@
+# Security workflow — `autoresearch security` mode
+
+Autonomous security audit using STRIDE threat modelling and OWASP categories.
+Finds vulnerabilities, classifies them by severity, and optionally fixes
+confirmed critical and high findings via an autoresearch loop.
+
+---
+
+## Invocation
+
+```
+autoresearch security                       # full audit, report only
+autoresearch security --fix                 # audit + auto-fix confirmed findings
+autoresearch security --fail-on critical    # end with a FAIL verdict if critical found
+autoresearch security --scope src/api/      # audit a specific directory only
+```
+
+---
+
+## Phase 1 — Asset discovery
+
+Map the attack surface:
+
+1. Identify all entry points: API routes, form handlers, file uploads,
+   auth flows, webhooks, admin panels
+2. Identify all data stores: databases, caches, file system writes,
+   environment variables, secrets
+3. Identify all trust boundaries: public vs authenticated, user vs admin,
+   internal vs external services
+4. Map data flows: what user input reaches what data store via what path
+
+Output: `security/audit-<timestamp>/attack-surface-map.md`
+
+### Live threat intelligence
+
+Use `WebSearch` to seed the audit with current threats:
+
+```
+WebSearch: [your stack] common vulnerabilities [current year]
+WebSearch: [your main framework] CVE [current year]
+WebSearch: OWASP top 10 [current year]
+```
+
+Add any newly discovered attack patterns to the audit queue.
+This ensures the audit covers threats that postdate your static analysis tools.
+
+---
+
+## Phase 2 — STRIDE threat model
+
+For each asset and trust boundary, model threats across all 6 STRIDE categories:
+
+| Category | Question to ask |
+|---|---|
+| **S**poofing | Can an attacker impersonate a user, service, or system? |
+| **T**ampering | Can input be modified to alter data or behaviour unexpectedly? |
+| **R**epudiation | Can actions be performed without a traceable audit trail? |
+| **I**nformation disclosure | Can sensitive data be accessed by unauthorised parties? |
+| **D**enial of service | Can the service be made unavailable through normal inputs? |
+| **E**levation of privilege | Can a lower-privilege user gain higher-privilege access? |
+
+Output: `security/audit-<timestamp>/threat-model.md`
+
+---
+
+## Phase 3 — Autonomous audit loop
+
+```
+LOOP (through all attack vectors from threat model):
+  1. Select next untested attack vector
+  2. Deep-dive into the relevant code (read fully — do not skim)
+  3. Attempt to construct a concrete exploit scenario
+  4. Validate with code evidence (file:line + exact scenario)
+  5. Classify: severity + OWASP category + STRIDE tag
+  6. Log to security-audit-results.tsv
+  7. Print coverage summary every 5 iterations
+  8. Continue until all vectors tested
+```
+
+### Severity classification
+
+| Severity | Definition |
+|---|---|
+| Critical | Exploitable without authentication, leads to full compromise or data breach |
+| High | Exploitable with low-privilege access, significant impact |
+| Medium | Requires specific conditions, moderate impact |
+| Low | Minor information disclosure, no direct exploitation path |
+| Info | Best practice violation, no immediate security impact |
+
+### Evidence requirement
+
+Every finding MUST have:
+- File path and line number
+- Exact vulnerable code snippet (copy from source, do not paraphrase)
+- Concrete exploit scenario (how an attacker would trigger this)
+- Proof of exploitability (not theoretical — show the actual path)
+
+Findings without concrete evidence are logged as "unconfirmed" and flagged
+for manual review, not included in the fix loop.
+
+---
+
+## Phase 4 — Report generation
+
+Output folder: `security/audit-<timestamp>/`
+
+```
+security/audit-20260325-1430/
+├── overview.md              ← executive summary + finding counts by severity
+├── threat-model.md          ← STRIDE analysis per asset
+├── attack-surface-map.md    ← entry points, data flows, trust boundaries
+├── findings.md              ← all confirmed findings, sorted by severity
+├── owasp-coverage.md        ← coverage matrix — which OWASP categories checked
+├── recommendations.md       ← fix guidance for each confirmed finding
+└── security-audit-results.tsv ← machine-readable log of all iterations
+```
+
+Print summary:
+```
+=== Security audit summary ===
+Critical:  <N>
+High:      <N>
+Medium:    <N>
+Low:       <N>
+Info:      <N>
+Vectors tested: <N> / <total>
+OWASP categories covered: <list>
+
+Full report: security/audit-<timestamp>/overview.md
+===
+```
+
+---
+
+## Phase 5 — Auto-fix loop (with `--fix`)
+
+Only runs when `--fix` flag is passed.
+Only fixes **Confirmed Critical and High** findings.
+Uses `recommendations.md` as the fix guide for each finding.
+
+```
+FOR EACH confirmed Critical/High finding:
+  1. Read the finding + recommendation
+  2. Make ONE targeted fix
+  3. git commit the fix
+  4. Re-run the specific exploit scenario to verify it no longer works
+  5. Run full test suite to confirm no regressions
+  6. If tests break → revert, try alternative fix
+  7. Maximum 3 attempts per finding, then skip and flag for manual review
+  8. Log fix outcome to fix-log.md
+```
+
+---
+
+## Verdict mode (`--fail-on`)
+
+```
+autoresearch security --fail-on critical
+```
+
+The audit ends with an explicit verdict line in `overview.md`:
+
+```
+VERDICT: FAIL — 2 findings at or above `critical`
+VERDICT: PASS — no findings at or above `critical`
+```
+
+A skill run has no process exit code, so do not wire this into a CI gate as if
+it did — use a real scanner for blocking merges. What it *is* good for is an
+unattended scheduled audit: a Qoder Automation running this mode reports the
+verdict, and you act on it.

.agents/skills/autoresearch/references/ship-workflow.md

@@ -0,0 +1,164 @@
+# Ship workflow — `autoresearch ship`
+
+Run a pre-flight checklist before shipping — tests, types, lint, bundle size,
+security basics, and a final autoresearch pass on anything that fails.
+
+The ship workflow is not just a checklist. It runs an autoresearch loop on
+each failing gate until it passes, then re-checks. You don't ship broken.
+You ship when everything is green.
+
+---
+
+## Invocation
+
+```
+autoresearch ship
+```
+
+Optional flags:
+```
+autoresearch ship --fast        # skip slow checks (lighthouse, e2e)
+autoresearch ship --loop N      # max N autoresearch iterations per gate (default: 20)
+autoresearch ship --dry-run     # report status without fixing anything
+```
+
+---
+
+## The ship checklist
+
+The workflow runs these gates in order. Each gate that fails triggers an
+autoresearch sub-loop to fix it before moving to the next gate.
+
+### Gate 1 — Tests pass
+
+```bash
+npm test         # Node.js
+pytest           # Python
+go test ./...    # Go
+cargo test       # Rust
+```
+
+If tests fail → autoresearch loop on `src/**/*.ts` (or equivalent) with
+metric: failing test count (lower is better), max 20 iterations.
+
+### Gate 2 — No type errors
+
+```bash
+npx tsc --noEmit              # TypeScript
+mypy src/                     # Python
+```
+
+If errors found → autoresearch loop on `src/**/*.ts` with
+metric: error count (lower is better), max 20 iterations.
+
+### Gate 3 — No lint errors
+
+```bash
+npx eslint src/               # JavaScript/TypeScript
+ruff check src/               # Python
+golangci-lint run             # Go
+```
+
+If errors found → autoresearch loop with metric: lint error count (lower is better).
+Auto-fixable errors are fixed first (`--fix` flag), then the loop handles the rest.
+
+### Gate 4 — Bundle size (if applicable)
+
+Only runs for frontend projects (detected: `next.config.*`, `vite.config.*`,
+`webpack.config.*`).
+
+```bash
+npm run build 2>&1 | grep "First Load JS"
+```
+
+Threshold: warn if > 300KB, block if > 500KB (configurable via `.autoresearch.yml`).
+
+If over threshold → autoresearch loop on `src/**/*.tsx, src/**/*.ts` with
+metric: bundle size in KB (lower is better), max 20 iterations.
+
+### Gate 5 — No hardcoded secrets
+
+```bash
+git diff HEAD~1 --diff-filter=A | grep -iE "(api_key|secret|password|token)\s*=\s*['\"][^'\"]{8,}"
+```
+
+If secrets found → do NOT autoresearch. Flag for human review. Block ship.
+
+### Gate 6 — Dependency audit
+
+```bash
+npm audit --audit-level=high   # Node.js
+pip-audit                      # Python
+```
+
+If critical vulnerabilities found → autoresearch loop to update affected
+dependencies, max 10 iterations.
+
+---
+
+## Ship report
+
+After all gates pass, print:
+
+```
+=== Ship report ===
+Tests:        ✓ PASS  (247 passing)
+Types:        ✓ PASS  (0 errors)
+Lint:         ✓ PASS  (0 errors)
+Bundle:       ✓ PASS  (187KB)
+Secrets:      ✓ PASS  (none detected)
+Deps:         ✓ PASS  (0 high/critical)
+
+Autoresearch loops run: <N>
+Total improvements: <M> iterations kept
+
+Ready to ship. Run: git push && <your deploy command>
+===
+```
+
+If any gate is still failing after the max iterations:
+
+```
+=== Ship report ===
+Tests:        ✓ PASS
+Types:        ✗ FAIL  (3 errors remaining after 20 iterations)
+              → manual fix required: src/auth/session.ts:47
+
+Ship BLOCKED. Fix the above before shipping.
+===
+```
+
+---
+
+## Web research post-check
+
+After all gates pass, use `WebSearch` to check:
+
+```
+WebSearch: [your framework] [version] known issues [current year]
+WebSearch: [your main dependencies] security advisory [current year]
+```
+
+If any critical advisories surface that the dependency audit missed,
+flag them before shipping. This is a final sanity check that goes beyond
+what local tools can detect.
+
+---
+
+## Configuration via `.autoresearch.yml`
+
+Create this file in your project root to customise ship behaviour:
+
+```yaml
+ship:
+  bundle_warn_kb: 300
+  bundle_block_kb: 500
+  max_iterations_per_gate: 20
+  skip_gates:
+    - lighthouse    # skip if no local server available
+  extra_gates:
+    - name: "E2E tests"
+      command: "npx playwright test"
+      metric: "failing tests (lower is better)"
+      max_iterations: 10
+```

.agents/skills/autoresearch/references/web-research-patterns.md

@@ -0,0 +1,144 @@
+# Web research patterns
+
+Qoder exposes a `WebSearch` tool (and `WebFetch` to read a promising result in
+full). Use them as a verification supplement — not a replacement for the Verify
+command, but an additional signal when local scripts alone cannot capture
+quality.
+
+---
+
+## When to use WebSearch in the loop
+
+| Goal type | Use WebSearch for | Example query |
+|---|---|---|
+| SEO content | Check competing pages, keyword signals | `[target keyword] filetype:md OR site:*.dev` |
+| API correctness | Verify endpoint signatures, check for deprecations | `[library] [method] deprecated 2025 OR 2026` |
+| Dependency versions | Confirm latest stable before updating | `[package name] latest stable version` |
+| Best practices | Check if your approach matches current consensus | `[pattern] best practice [language] 2026` |
+| Content accuracy | Ground-truth check generated facts | `[claim] site:official-source.com` |
+| Bundle/perf baselines | Compare your score to current industry benchmarks | `[framework] bundle size benchmark 2026` |
+
+---
+
+## Pattern 1 — SEO content verification
+
+Use when: optimising blog posts, landing pages, documentation for search.
+
+After your local score script runs, supplement with:
+
+```
+WebSearch: [target keyword] to see what the top 3 results have in common.
+Note: heading structure, content length, semantic coverage, internal links.
+If top results consistently have trait X that your content lacks,
+add "add trait X" as the next hypothesis.
+```
+
+This gives you signal that no local readability or keyword-density script can
+provide — what the search engine is actually rewarding right now.
+
+---
+
+## Pattern 2 — API currency check
+
+Use when: refactoring code that calls external libraries or APIs.
+
+Before committing any API-surface change:
+
+```
+WebSearch: [library name] [method name] changelog 2026
+WebSearch: [library name] [method name] deprecated
+```
+
+If search returns deprecation notices or breaking changes, note the current
+replacement pattern and use that as the hypothesis instead.
+
+This prevents iterating toward a working-but-deprecated solution that will
+break on the next library update.
+
+---
+
+## Pattern 3 — Dependency version check
+
+Use when: the Verify command suggests a dependency might be outdated, or when
+optimising for security/bundle size.
+
+```
+WebSearch: [package name] npm latest 2026
+WebSearch: [package name] security advisory
+```
+
+Cross-reference against what is in `package.json`, `go.mod`, `requirements.txt`
+or equivalent. Use the delta as a hypothesis: "update [package] from X to Y,
+check if metric improves."
+
+---
+
+## Pattern 4 — Best practice calibration
+
+Use when: stuck after 5 consecutive discards and local ideas are exhausted.
+
+```
+WebSearch: [language/framework] [metric type] optimisation techniques 2026
+WebSearch: how to improve [metric] in [stack]
+```
+
+Extract 3 concrete, actionable techniques from the top results — use `WebFetch`
+on the most promising one if the snippet is too thin. Do not extract vague
+advice. Add each as a separate iteration hypothesis. This restocks your
+hypothesis pool with externally validated approaches.
+
+---
+
+## Pattern 5 — Benchmark calibration
+
+Use when: you want to know if your current metric value is good relative to
+the industry, not just relative to your own baseline.
+
+```
+WebSearch: [framework] [metric] benchmark 2026 average
+```
+
+If your metric is already at or above the industry median, note this and
+shift the goal definition (e.g. from "reduce bundle size" to "reduce bundle
+size while improving lighthouse score").
+
+---
+
+## Pattern 6 — Content accuracy check
+
+Use when: the Verify command measures style/structure but not factual accuracy
+(e.g. documentation, blog posts, runbooks).
+
+```
+WebSearch: [specific claim in content] site:[authoritative source]
+```
+
+If the authoritative source contradicts your content, flag this as a
+required fix before the next iteration (accuracy issues override metric gains).
+
+---
+
+## Rules for using WebSearch
+
+1. **Supplement, never replace.** The Verify command runs every iteration.
+   Web research adds signal; it does not replace the metric.
+
+2. **Search at the right time.** Patterns 1-3 supplement Phase 5 (Verify).
+   Patterns 4-5 are for stuck recovery in Phase 1 (Review). Pattern 6
+   runs in Phase 6 (Decide) when a kept iteration touches factual claims.
+
+3. **Extract actionable hypotheses.** Never let a search result produce a
+   vague conclusion ("content could be better"). Always turn the search
+   result into a specific next hypothesis ("add a FAQ section with 3
+   questions, which top-ranking competitors include").
+
+4. **Log the research signal.** When a search result influences a hypothesis,
+   note it in the results log description:
+   `"added FAQ section (web research: top results for [kw] all include FAQ)"`
+
+5. **Don't over-search.** Maximum one WebSearch call per iteration. If you are
+   searching every iteration, your Verify command is probably too weak —
+   strengthen the local script instead.
+
+6. **Cite, don't guess.** `WebSearch` results come with source links; never
+   turn an unverified snippet into a change that the Guard cannot catch.

.agents/skills/clickhouse-batchwriter/SKILL.md

@@ -62,24 +62,26 @@ writer.Stop(stopCtx)      // close 队列 + drain + 最终 flush
 | 域 | 表 | 写入路径 |
 | :--- | :--- | :--- |
 | 管理端审计 | `w_user_access_logs` | `risk_control` → `batchwriter` → `logstore.Active` |
+| 边缘访问日志 | `of_node_access_logs` | `openflare/chwriter` → `logstore.Active` |
+| 可观测时序 | `of_node_metric_snapshots` 等 | `openflare/chwriter` 分表 writer + 进程内短 TTL 去重 → `logstore.Active` |
 
-**不要**把不同日志域并入同一 channel。新日志表先按 `logstore` skill 判定，再为本域建独立 writer。
+**不要**把 audit、access log、observability 并入同一 channel。
 
 ## 新增 ClickHouse 写入工作流
 
 1. **Model**：在 `internal/model/analytics/` 定义 struct 与 `BatchInsertSQL()`（列顺序与 goose DDL 一致）。
 2. **Goose DDL**：在 `internal/infra/persistence/migrator/goose/clickhouse/` 新增迁移（见 `database-migration`）。
 3. **Repository**：实现 `BatchInsertX(ctx, []analyticsmodel.X) error`：
-    - `len(items)==0` 直接返回
-    - `db.ChConn == nil` 返回明确错误
-    - 一次 `PrepareBatch` → 循环 `Append` → 一次 `Send`
+   - `len(items)==0` 直接返回
+   - `db.ChConn == nil` 返回明确错误
+   - 一次 `PrepareBatch` → 循环 `Append` → 一次 `Send`
 4. **Writer 胶水**（`internal/apps/<domain>/`）：
     - `New` + `Start`，并在初始化逻辑内通过 `lifecycle.OnShutdown("your_writer_name", Stop)` 注册停机回调
     - 日志表的 `FlushFunc` 调 `logstore.Active`（见 `logstore` skill）
     - 业务路径 `TryEnqueue`；HTTP 背压用 `IsFull()`
 5. **测试**：
-    - repository：mock `ChConn` 验证 `BatchInsertSQL` 与 append 列数
-    - batchwriter：`go test ./internal/infra/persistence/batchwriter`
+   - repository：mock `ChConn` 验证 `BatchInsertSQL` 与 append 列数
+   - batchwriter：`go test ./internal/infra/persistence/batchwriter`
 6. 运行 `make code-check`；有 API 变更时 `make swagger`。
 
 ## 背压与丢弃策略
@@ -87,7 +89,8 @@ writer.Stop(stopCtx)      // close 队列 + drain + 最终 flush
 | 场景 | 推荐策略 |
 | :--- | :--- |
 | 管理端 API 审计 | 队列满 → `IsFull()` 触发 429（见 `risk_control` middleware） |
-| 可丢弃的高频日志 | 队列满 → `WithDropHandler` 记 warn；不阻塞请求 |
+| Agent 心跳指标 | 队列满 → `WithDropHandler` 记 warn；不阻塞心跳响应 |
+| 边缘 access log | 优先扩大队列与 batch；必要时丢弃最旧或采样 |
 
 ## 禁止写法
 
@@ -152,6 +155,9 @@ make code-check
 - 框架：`internal/infra/persistence/batchwriter/{config,writer,errs}.go`
 - 连接：`internal/infra/persistence/clickhouse.go`
 - 审计写入：`internal/apps/risk_control/logics.go`
+- OpenFlare 写入胶水：`internal/apps/openflare/chwriter/writer.go`
 - 日志抽象：`internal/repository/logstore`
+- 节点访问日志 CH 实现：`internal/repository/analytics/node_access_log_writer.go`
+- 可观测 CH 实现：`internal/repository/analytics/node_observability_writer.go`
 - 生命周期管理器：`internal/platform/lifecycle/lifecycle.go`
 - Bootstrap：`internal/platform/bootstrap/bootstrap.go`

.agents/skills/database-migration/SKILL.md

@@ -92,7 +92,7 @@ ClickHouse 是**辅助 OLAP 存储**，与 PostgreSQL/SQLite 主库**完全独
 | `internal/infra/persistence/migrator/goose/clickhouse/` | **唯一** ClickHouse DDL 来源（goose SQL，嵌入二进制） |
 | `internal/model/analytics/` | 分析表 Go model，列名须与 goose DDL 一致 |
 | `internal/repository/analytics/` | 所有 ClickHouse 读写（批量写入、查询、聚合） |
-| `internal/infra/persistence/clickhouse.go` | 连接初始化（`ChConn` 原生批量、`chDB` GORM 查询） |
+| `internal/infra/persistence/clickhouse.go` | 连接初始化（`ChConn` 原生批量、`ChDB` GORM 查询） |
 
 ### 迁移入口与版本表
 

.agents/skills/file-upload/SKILL.md

@@ -83,8 +83,8 @@ invoice.FilePath = "uploads/2026/01/02/123.pdf"
 import (
     "bytes"
 
-    "github.com/Rain-kl/Wavelet/internal/apps/upload"
-    "github.com/Rain-kl/Wavelet/internal/model"
+    "OpenFlare/internal/apps/upload"
+    "OpenFlare/internal/model"
 )
 
 func ingestMirrorFile(ctx context.Context, userID uint64, data []byte, hash, filename, mime, ext string) (model.Upload, error) {

.agents/skills/go-packages/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: go-packages
+description: Use when creating Go packages, organizing imports, managing dependencies, or deciding how to structure Go code into packages. Also use when starting a new Go project or splitting a growing codebase into packages, even if the user doesn't explicitly ask about package organization. Does not cover naming individual identifiers (see go-naming).
+license: Apache-2.0
+metadata:
+  sources: "Google Style Guide, Uber Style Guide, Go Wiki CodeReviewComments"
+---
+
+# Go 包和 Import
+
+> **本技能不适用的场景**：对于包内单个标识符的命名，参见 [go-naming](../go-naming/SKILL.md)。对于单文件中函数的组织，参见 [go-functions](../go-functions/SKILL.md)。对于强制执行 import 规则的 linter 配置，参见 [go-linting](../go-linting/SKILL.md)。
+
+## 包组织
+
+### 避免 Util 包
+
+包名应描述包提供的内容。避免使用 `util`、`helper`、`common` 等泛化名称——它们会模糊含义并导致 import 冲突。
+
+```go
+// 好：有意义的包名
+db := spannertest.NewDatabaseFromFile(...)
+_, err := f.Seek(0, io.SeekStart)
+
+// 不好：模糊的名称遮蔽含义
+db := test.NewDatabaseFromFile(...)
+_, err := f.Seek(0, common.SeekStart)
+```
+
+泛化名称可以作为名称的*一部分*（例如 `stringutil`），但不应成为整个包名。
+
+### Package Size
+
+| 问题 | 操作 |
+|------|------|
+| 你能用一句话描述它的用途吗？ | 不能 → 按职责拆分 |
+| 文件中从未共享未导出的符号？ | 这些文件可以是独立的包 |
+| 不同的用户群体使用不同部分？ | 按用户边界拆分 |
+| Godoc 页面过于庞大？ | 拆分以提高可发现性 |
+
+**不要拆分**的原因仅仅是文件很长、创建只有单一类型的包，或会产生循环依赖。
+
+> 在决定是否拆分或合并包、组织包内文件或构建 CLI 程序时，阅读 [references/PACKAGE-SIZE.md](references/PACKAGE-SIZE.md)。
+
+---
+
+## Import
+
+Import 按组组织，组之间用空行分隔。标准库包始终放在第一组。使用
+[goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) 自动管理。
+
+```go
+import (
+    "fmt"
+    "os"
+
+    "github.com/foo/bar"
+    "rsc.io/goversion/version"
+)
+```
+
+**快速规则：**
+
+| 规则 | 指导 |
+|------|------|
+| 分组 | 标准库优先，然后是外部包。扩展分组：标准库 → 其他 → proto → 副作用 |
+| 重命名 | 除非冲突，否则避免重命名。重命名最本地的 import。Proto 包加 `pb` 后缀 |
+| 空白 import（`import _`） | 仅在 `main` 包或测试中使用 |
+| 点 import（`import .`） | 永不使用，除非用于循环依赖的测试文件 |
+
+> 在组织扩展分组的 import、重命名 proto 包或决定使用空白/点 import 时，阅读 [references/IMPORTS.md](references/IMPORTS.md)。
+
+---
+
+## 避免 init()
+
+尽可能避免 `init()`。当不可避免时，它必须是：
+
+1. 完全确定性的
+2. 不依赖于其他 `init()` 的执行顺序
+3. 不依赖环境状态（环境变量、工作目录、参数）
+4. 不进行 I/O（文件系统、网络、系统调用）
+
+**可接受的使用场景**：无法用单个赋值完成的复杂表达式、可插拔钩子（例如 `database/sql` 方言）、确定性预计算。
+
+> 在需要将 init() 重构为显式函数或理解可接受的 init() 使用场景时，阅读 [references/PACKAGE-SIZE.md](references/PACKAGE-SIZE.md)。
+
+---
+
+## Main 中的退出
+
+仅在 `main()` 中调用 `os.Exit` 或 `log.Fatal*`。所有其他函数应返回 error。
+
+**原因**：不明显的控制流、不可测试、`defer` 语句被跳过。
+
+**最佳实践**：使用 `run()` 模式——将逻辑提取到
+`func run() error` 中，在 `main()` 中调用并使用单一退出点：
+
+```go
+func main() {
+    if err := run(); err != nil {
+        log.Fatal(err)
+    }
+}
+```
+
+> 在实现 run() 模式、构建 CLI 子命令或选择 flag 命名约定时，阅读 [references/PACKAGE-SIZE.md](references/PACKAGE-SIZE.md)。
+
+---
+
+## 命令行 Flag
+
+> **建议**：仅在 `package main` 中定义 flag。
+
+- Flag 名称使用 `snake_case`：`--output_dir` 而非 `--outputDir`
+- 库应通过参数接收配置，而非直接读取 flag——
+  这使它们可测试且可复用
+- 优先使用标准 `flag` 包；仅在需要 POSIX 约定
+  （双破折号、单字符快捷方式）时使用 `pflag`
+
+```go
+// 好：Flag 在 main 中定义，作为参数传递给库
+func main() {
+    outputDir := flag.String("output_dir", ".", "directory for output files")
+    flag.Parse()
+    if err := mylib.Generate(*outputDir); err != nil {
+        log.Fatal(err)
+    }
+}
+```
+
+---
+
+## 相关技能
+
+- **包命名**：在选择包名、避免名称重复或命名导出符号时，参见 [go-naming](../go-naming/SKILL.md)
+- **跨包的错误处理**：在使用 `%w` vs `%v` 在包边界包装错误时，参见 [go-error-handling](../go-error-handling/SKILL.md)
+- **Import linting**：在配置 goimports local-prefixes 或强制执行 import 分组时，参见 [go-linting](../go-linting/SKILL.md)
+- **全局状态**：在用显式初始化替换 `init()` 或避免可变全局变量时，参见 [go-defensive](../go-defensive/SKILL.md)

.agents/skills/go-packages/references/IMPORTS.md

@@ -0,0 +1,110 @@
+# Import 组织
+
+Go import 组织的详细规则和示例。
+
+## Import 分组
+
+Import 按组组织，组之间用空行分隔。标准库包始终放在第一组。
+
+**最小分组（Uber）：** 标准库，然后其他所有。
+
+**扩展分组（Google）：** 标准库 → 其他 → protocol buffers → 副作用。
+
+```go
+// 好：标准库与外部包分开
+import (
+    "fmt"
+    "os"
+
+    "go.uber.org/atomic"
+    "golang.org/x/sync/errgroup"
+)
+```
+
+```go
+// 好：完整分组，包含 proto 和副作用
+import (
+    "fmt"
+    "os"
+
+    "github.com/dsnet/compress/flate"
+    "golang.org/x/text/encoding"
+
+    foopb "myproj/foo/proto/proto"
+
+    _ "myproj/rpc/protocols/dial"
+)
+```
+
+## Import 重命名
+
+避免重命名 import，除非为了避免名称冲突；好的包名不需要重命名。
+在发生冲突时，**优先重命名最本地的或项目特定的 import**。
+
+**必须重命名：** 与其他 import 冲突、生成的 protocol buffer 包
+（删除下划线，添加 `pb` 后缀）。
+
+**可以重命名：** 无意义的名称（例如 `v1`）、与本地变量冲突。
+
+```go
+// 好：Proto 包用 pb 后缀重命名
+import (
+    foosvcpb "path/to/package/foo_service_go_proto"
+)
+
+// 好：当需要 url 变量时使用 urlpkg
+import (
+    urlpkg "net/url"
+)
+
+func parseEndpoint(url string) (*urlpkg.URL, error) {
+    return urlpkg.Parse(url)
+}
+```
+
+## 空白 Import（`import _`）
+
+仅为副作用而导入的包（使用 `import _ "pkg"`）
+应仅在程序的主包（main）或需要它们的测试中导入。
+
+```go
+// 好：在主包中使用空白 import
+package main
+
+import (
+    _ "time/tzdata"
+    _ "image/jpeg"
+)
+```
+
+## 点 Import（`import .`）
+
+**不要**使用点 import。它们使程序难以阅读，因为不清楚
+`Quux` 这样的名称是当前包中的顶层标识符还是导入包中的。
+
+**例外：** `import .` 形式在由于循环依赖而无法成为被测试包的一部分的测试文件中可能有用：
+
+```go
+package foo_test
+
+import (
+    "bar/testutil" // 也导入了 "foo"
+    . "foo"
+)
+```
+
+在这种情况下，测试文件不能是 `foo` 包，因为它使用了
+`bar/testutil`，而后者导入了 `foo`。因此 `import .` 形式让文件
+假装是 `foo` 包的一部分，即使实际上不是。
+
+**除了这一种情况外，不要在程序中使用 `import .`。**
+
+```go
+// 不好：点 import 隐藏了来源
+import . "foo"
+var myThing = Bar() // Bar 来自哪里？
+
+// 好：显式限定
+import "foo"
+var myThing = foo.Bar()
+```

.agents/skills/go-packages/references/PACKAGE-SIZE.md

@@ -0,0 +1,214 @@
+# 包大小、程序结构和 CLI
+
+关于包拆分、避免 init()、run() 模式和 CLI 结构的详细指南。
+
+## 何时拆分包
+
+```
+包是否变得太大？
+├─ 你能用一句话描述它的用途吗？
+│  ├─ 不能 → 按职责拆分
+│  └─ 能 → 保留，但检查以下内容
+├─ 包中的文件是否从未导入彼此的未导出符号？
+│  └─ 是 → 这些文件可以是独立的包
+├─ 包是否有不同的用户群体使用不同部分？
+│  └─ 是 → 按用户边界拆分
+└─ godoc 页面是否过于庞大？
+   └─ 是 → 拆分以提高可发现性
+```
+
+### 何时不应拆分
+
+- 不要仅因为文件很长就拆分——聚焦的包中的大文件是可以的
+- 不要创建只包含一个类型或函数的包
+- 如果会产生循环依赖则不要拆分
+- 避免将内部辅助工具拆分到 `util` 或 `internal/helpers` 包中
+
+### 何时合并包
+
+- 如果客户端代码很可能需要两个类型交互，保持它们在一起
+- 如果类型有紧密耦合的实现
+- 如果用户需要同时导入两个包才能有意义地使用其中任何一个
+
+### 文件组织
+
+Go 中没有"一个类型一个文件"的惯例。文件应该足够聚焦以便知道哪个文件包含什么内容，且足够小以便轻松查找。
+
+---
+
+## 避免 init()
+
+优先使用显式函数而非 `init()`：
+
+```go
+// 不好：init() 带有 I/O 和环境依赖
+var _config Config
+
+func init() {
+    cwd, _ := os.Getwd()
+    raw, _ := os.ReadFile(path.Join(cwd, "config.yaml"))
+    yaml.Unmarshal(raw, &_config)
+}
+```
+
+```go
+// 好：用于加载配置的显式函数
+func loadConfig() (Config, error) {
+    cwd, err := os.Getwd()
+    if err != nil {
+        return Config{}, err
+    }
+
+    raw, err := os.ReadFile(path.Join(cwd, "config.yaml"))
+    if err != nil {
+        return Config{}, err
+    }
+
+    var config Config
+    if err := yaml.Unmarshal(raw, &config); err != nil {
+        return Config{}, err
+    }
+    return config, nil
+}
+```
+
+**init() 的可接受使用场景：**
+- 无法用单个赋值完成的复杂表达式
+- 可插拔钩子（例如 `database/sql` 方言、编码注册表）
+- 确定性预计算
+
+---
+
+## Main 中的退出
+
+仅在 `main()` 中调用 `os.Exit` 或 `log.Fatal*`。所有其他函数应
+返回 error 来表示失败。
+
+**为什么这很重要：**
+- 不明显的控制流：任何函数都可以退出程序
+- 难以测试：退出程序的函数也会退出测试
+- 跳过的清理：`defer` 语句会被跳过
+
+```go
+// 不好：在辅助函数中使用 log.Fatal
+func readFile(path string) string {
+    f, err := os.Open(path)
+    if err != nil {
+        log.Fatal(err)  // 退出程序，跳过 defer
+    }
+    b, err := io.ReadAll(f)
+    if err != nil {
+        log.Fatal(err)
+    }
+    return string(b)
+}
+```
+
+```go
+// 好：返回 error，让 main() 决定是否退出
+func main() {
+    body, err := readFile(path)
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Println(body)
+}
+
+func readFile(path string) (string, error) {
+    f, err := os.Open(path)
+    if err != nil {
+        return "", err
+    }
+    b, err := io.ReadAll(f)
+    if err != nil {
+        return "", err
+    }
+    return string(b), nil
+}
+```
+
+### run() 模式
+
+优先在 `main()` 中**最多调用一次** `os.Exit` 或 `log.Fatal`。将
+业务逻辑提取到返回 error 的独立函数中。
+
+```go
+func main() {
+    if err := run(); err != nil {
+        log.Fatal(err)
+    }
+}
+
+func run() error {
+    args := os.Args[1:]
+    if len(args) != 1 {
+        return errors.New("missing file")
+    }
+
+    f, err := os.Open(args[0])
+    if err != nil {
+        return err
+    }
+    defer f.Close()  // 将始终执行
+
+    b, err := io.ReadAll(f)
+    if err != nil {
+        return err
+    }
+
+    // 处理 b...
+    return nil
+}
+```
+
+**`run()` 模式的优势：**
+- 简短的 `main()` 函数，单一退出点
+- 所有业务逻辑都可测试
+- `defer` 语句始终执行
+
+---
+
+## 命令行接口
+
+### Flag 命名
+
+使用小写、连字符分隔的 flag 名称：
+
+```go
+// 好
+flag.String("output-dir", ".", "directory for output files")
+flag.Bool("dry-run", false, "print actions without executing")
+
+// 不好
+flag.String("outputDir", ".", "")    // camelCase
+flag.String("output_dir", ".", "")   // 下划线
+```
+
+### 子命令
+
+对于带有子命令的复杂 CLI，为每个子命令使用 `flag.NewFlagSet`：
+
+```go
+func main() {
+    serveCmd := flag.NewFlagSet("serve", flag.ExitOnError)
+    port := serveCmd.Int("port", 8080, "listen port")
+
+    migrateCmd := flag.NewFlagSet("migrate", flag.ExitOnError)
+    dryRun := migrateCmd.Bool("dry-run", false, "preview changes")
+
+    switch os.Args[1] {
+    case "serve":
+        serveCmd.Parse(os.Args[2:])
+        runServe(*port)
+    case "migrate":
+        migrateCmd.Parse(os.Args[2:])
+        runMigrate(*dryRun)
+    default:
+        fmt.Fprintf(os.Stderr, "unknown command: %s\n", os.Args[1])
+        os.Exit(1)
+    }
+}
+```
+
+对于更大的 CLI，考虑使用 `cobra` 或 `urfave/cli` 等库。仅从
+`main()` 退出。

.agents/skills/go-performance/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: go-performance
+description: Use when optimizing Go code, investigating slow performance, or writing performance-critical sections. Also use when a user mentions slow Go code, string concatenation in loops, or asks about benchmarking, even if the user doesn't explicitly mention performance patterns. Does not cover concurrent performance patterns (see go-concurrency).
+license: Apache-2.0
+metadata:
+  sources: "Uber Style Guide, Google Style Guide, Go Wiki CodeReviewComments"
+allowed-tools: Bash(bash:*)
+---
+
+# Go 性能模式
+
+## 可用脚本
+
+- **`scripts/bench-compare.sh`** — 运行 Go 基准测试 N 次，并可选通过 benchstat 进行基线比较。支持保存结果以供未来比较。运行 `bash scripts/bench-compare.sh --help` 查看选项。
+
+性能特定的指南仅适用于**热点路径**。不要过早优化——将这些模式集中在最重要的地方。
+
+---
+
+## 优先使用 strconv 而非 fmt
+
+在基本类型和字符串之间转换时，`strconv` 比 `fmt` 更快：
+
+```go
+s := strconv.Itoa(rand.Int()) // 比 fmt.Sprint() 快约 2 倍
+```
+
+| 方式 | 速度 | 分配次数 |
+|------|------|---------|
+| `fmt.Sprint` | 143 ns/op | 2 allocs/op |
+| `strconv.Itoa` | 64.2 ns/op | 1 allocs/op |
+
+> 在 strconv 和 fmt 之间选择类型转换方式时，或需要完整的转换对照表时，阅读 [references/STRING-OPTIMIZATION.md](references/STRING-OPTIMIZATION.md)。
+
+---
+
+## 避免重复的字符串到字节转换
+
+将固定字符串在循环外转换为 `[]byte` 一次：
+
+```go
+data := []byte("Hello world")
+for i := 0; i < b.N; i++ {
+    w.Write(data) // 比每次迭代 []byte("...") 快约 7 倍
+}
+```
+
+> 在优化热点循环中的重复字节转换时，阅读 [references/STRING-OPTIMIZATION.md](references/STRING-OPTIMIZATION.md)。
+
+---
+
+## 优先指定容器容量
+
+尽可能指定容器容量，以便预先分配内存。这可以最大程度减少后续添加元素时因复制和调整大小而产生的分配。
+
+### Map 容量提示
+
+使用 `make()` 初始化 map 时提供容量提示：
+
+```go
+m := make(map[string]os.DirEntry, len(files))
+```
+
+**注意**：与 slice 不同，map 的容量提示不保证完整的预分配——它只是近似计算所需的哈希桶数量。
+
+### Slice 容量
+
+使用 `make()` 初始化 slice 时提供容量提示，特别是在追加时：
+
+```go
+data := make([]int, 0, size)
+```
+
+与 map 不同，slice 容量**不是提示**——编译器会精确分配那么多内存。后续的 `append()` 操作在达到容量之前不会产生任何分配。
+
+| 方式 | 时间（1 亿次迭代） |
+|------|------------------------|
+| 无容量 | 2.48s |
+| 指定容量 | 0.21s |
+
+指定容量的版本**快约 12 倍**，因为追加期间零重新分配。
+
+---
+
+## 传值
+
+不要仅为了节省几个字节就将指针作为函数参数传递。如果函数在整个函数体中仅通过 `*x` 引用其参数 `x`，则该参数不应该是`指针。
+
+```go
+func process(s string) { // 不是 *string —— string 是小的固定大小头部
+    fmt.Println(s)
+}
+```
+
+**常见的按值传递类型**：`string`、`io.Reader`、小结构体。
+
+**例外**：
+- 复制代价高的大结构体
+- 未来可能增长的小结构体
+
+---
+
+## 字符串拼接
+
+根据复杂度选择正确的策略：
+
+| 方法 | 最佳用途 |
+|------|---------|
+| `+` | 少量字符串，简单拼接 |
+| `fmt.Sprintf` | 混合类型的格式化输出 |
+| `strings.Builder` | 循环/逐段构建 |
+| `strings.Join` | 连接 slice |
+| 反引号字面量 | 常量多行文本 |
+
+> 在选择字符串拼接策略、在循环中使用 strings.Builder 或在 fmt.Sprintf 和手动拼接之间做决定时，阅读 [references/STRING-OPTIMIZATION.md](references/STRING-OPTIMIZATION.md)。
+
+---
+
+## 基准测试和性能分析
+
+在优化前后始终要进行测量。使用 Go 内置的基准测试框架和性能分析工具。
+
+```bash
+go test -bench=. -benchmem -count=10 ./...
+```
+
+> 在编写基准测试、使用 benchstat 比较结果、使用 pprof 进行性能分析或解读基准测试输出时，阅读 [references/BENCHMARKS.md](references/BENCHMARKS.md)。
+
+> **验证**：在应用优化后，运行 `bash scripts/bench-compare.sh` 测量实际影响。只保留有可衡量改进的优化。
+
+---
+
+## 快速参考
+
+| 模式 | 不好 | 好 | 改进 |
+|------|-----|------|-------------|
+| 整数转字符串 | `fmt.Sprint(n)` | `strconv.Itoa(n)` | 快约 2 倍 |
+| 重复 `[]byte` | 循环中 `[]byte("str")` | 在循环外转换一次 | 快约 7 倍 |
+| Map 初始化 | `make(map[K]V)` | `make(map[K]V, size)` | 更少分配 |
+| Slice 初始化 | `make([]T, 0)` | `make([]T, 0, cap)` | 快约 12 倍 |
+| 小型固定大小参数 | `*string`、`*io.Reader` | `string`、`io.Reader` | 无间接引用 |
+| 简单字符串连接 | `s1 + " " + s2` | （已经很好） | 对少量字符串使用 `+` |
+| 循环构建字符串 | 重复 `+=` | `strings.Builder` | O(n) vs O(n²) |
+
+---
+
+## 相关技能
+
+- **数据结构**：在 slice、map 和数组之间选择或理解分配语义时，参见 [go-data-structures](../go-data-structures/SKILL.md)
+- **声明模式**：在使用 `make` 配合容量提示或初始化 map 和 slice 时，参见 [go-declarations](../go-declarations/SKILL.md)
+- **并发**：在跨 goroutine 并行化工作或使用 sync.Pool 复用缓冲区时，参见 [go-concurrency](../go-concurrency/SKILL.md)
+- **风格原则**：在判断优化是否值得牺牲可读性时，参见 [go-style-core](../go-style-core/SKILL.md)

.agents/skills/go-performance/references/BENCHMARKS.md

@@ -0,0 +1,281 @@
+# 基准测试方法
+
+## 编写基准测试
+
+Go 基准测试使用 `testing.B` 类型，位于 `_test.go` 文件中。
+基准测试函数名必须以 `Benchmark` 开头。
+
+```go
+func BenchmarkStrconv(b *testing.B) {
+    for i := 0; i < b.N; i++ {
+        s := strconv.Itoa(rand.Int())
+        _ = s
+    }
+}
+
+func BenchmarkFmtSprint(b *testing.B) {
+    for i := 0; i < b.N; i++ {
+        s := fmt.Sprint(rand.Int())
+        _ = s
+    }
+}
+```
+
+关键规则：
+- 使用 `b.N` 作为循环边界——框架会调整它以获得稳定的计时
+- 将结果赋值给变量（或 `_`），防止编译器优化掉调用
+- 在不需要测量的昂贵设置之后使用 `b.ResetTimer()`
+- 使用 `b.ReportAllocs()` 或 `-benchmem` 标志跟踪分配情况
+
+### 子基准测试
+
+```go
+func BenchmarkConvert(b *testing.B) {
+    for _, size := range []int{10, 100, 1000} {
+        b.Run(fmt.Sprintf("size=%d", size), func(b *testing.B) {
+            data := make([]byte, size)
+            b.ResetTimer()
+            for i := 0; i < b.N; i++ {
+                _ = string(data)
+            }
+        })
+    }
+}
+```
+
+---
+
+## 运行基准测试
+
+```bash
+# 运行包中的所有基准测试
+go test -bench=. ./...
+
+# 运行特定基准测试并显示内存统计
+go test -bench=BenchmarkStrconv -benchmem ./...
+
+# 多次运行以获得统计显著性
+go test -bench=. -benchmem -count=10 ./...
+```
+
+`-benchmem` 标志报告每次操作的分配次数。`-count` 标志将每个基准测试运行 N 次以获得统计显著性。
+
+---
+
+## 解读结果
+
+```
+BenchmarkStrconv-8     18705042    64.2 ns/op    16 B/op    1 allocs/op
+BenchmarkFmtSprint-8    8249536   143.0 ns/op    16 B/op    2 allocs/op
+```
+
+| 字段 | 含义 |
+|------|------|
+| `-8` | GOMAXPROCS |
+| `18705042` | 迭代次数 |
+| `64.2 ns/op` | 每次操作时间 |
+| `16 B/op` | 每次操作分配的字节数 |
+| `1 allocs/op` | 每次操作的堆分配次数 |
+
+---
+
+## 使用 benchstat 进行比较
+
+`benchstat` 对基准测试结果进行统计比较。安装它并将基准测试输出保存到文件：
+
+```bash
+# 安装 benchstat
+go install golang.org/x/perf/cmd/benchstat@latest
+
+# 运行基准测试并保存结果
+go test -bench=. -benchmem -count=10 ./... > old.txt
+
+# 进行修改后再次运行
+go test -bench=. -benchmem -count=10 ./... > new.txt
+
+# 比较结果
+benchstat old.txt new.txt
+```
+
+### 解读 benchstat 输出
+
+```
+name          old time/op    new time/op    delta
+Strconv-8     64.2ns ± 2%    61.8ns ± 1%   -3.74%  (p=0.001 n=10+10)
+```
+
+- **delta**：变化百分比（负数 = 更快）
+- **p-value**：统计显著性（p < 0.05 为显著）
+- **n**：使用的有效样本数量
+
+提示：
+- 始终使用 `-count=10` 或更高以获得可靠结果
+- 小的 p 值确认变化是真实的，而非噪声
+- 如果 benchstat 显示 `~`（波浪号），则差异不具有统计显著性
+
+---
+
+## 来自性能模式的基准测试示例
+
+### strconv vs fmt
+
+| 方式 | 速度 | 分配次数 |
+|------|------|---------|
+| `fmt.Sprint` | 143 ns/op | 2 allocs/op |
+| `strconv.Itoa` | 64.2 ns/op | 1 allocs/op |
+
+### 重复字节转换
+
+```go
+func BenchmarkRepeatedConversion(b *testing.B) {
+    var buf bytes.Buffer
+    for i := 0; i < b.N; i++ {
+        buf.Write([]byte("Hello world"))
+    }
+}
+
+func BenchmarkSingleConversion(b *testing.B) {
+    var buf bytes.Buffer
+    data := []byte("Hello world")
+    for i := 0; i < b.N; i++ {
+        buf.Write(data)
+    }
+}
+```
+
+| 方式 | 速度 |
+|------|------|
+| 重复转换 | 22.2 ns/op |
+| 单次转换 | 3.25 ns/op |
+
+### Slice 容量
+
+```go
+func BenchmarkNoCapacity(b *testing.B) {
+    for n := 0; n < b.N; n++ {
+        data := make([]int, 0)
+        for k := 0; k < 1000; k++ {
+            data = append(data, k)
+        }
+    }
+}
+
+func BenchmarkWithCapacity(b *testing.B) {
+    for n := 0; n < b.N; n++ {
+        data := make([]int, 0, 1000)
+        for k := 0; k < 1000; k++ {
+            data = append(data, k)
+        }
+    }
+}
+```
+
+| 方式 | 时间（1 亿次迭代） |
+|------|------------------------|
+| 无容量 | 2.48s |
+| 指定容量 | 0.21s |
+
+---
+
+## 使用 pprof 进行性能分析
+
+使用 `pprof` 在优化前识别瓶颈。基准测试衡量改进效果；pprof 找到需要改进的地方。
+
+### CPU 性能分析
+
+```bash
+# 从基准测试生成 CPU 分析文件
+go test -bench=BenchmarkHotPath -cpuprofile=cpu.prof ./...
+
+# 使用 pprof 分析
+go tool pprof cpu.prof
+```
+
+常用 pprof 命令：
+
+```
+(pprof) top10          # 按 CPU 时间排列的前 10 个函数
+(pprof) list funcName  # 某个函数的带注释源码
+(pprof) web            # 浏览器中的交互式图表
+```
+
+### 内存性能分析
+
+```bash
+# 生成内存分析文件
+go test -bench=BenchmarkHotPath -memprofile=mem.prof ./...
+
+# 分析分配情况
+go tool pprof -alloc_space mem.prof
+```
+
+### 运行中服务的 HTTP 性能分析
+
+```go
+import _ "net/http/pprof"
+
+func main() {
+    go func() {
+        log.Println(http.ListenAndServe("localhost:6060", nil))
+    }()
+    // ... 应用程序代码 ...
+}
+```
+
+通过 `http://localhost:6060/debug/pprof/` 访问性能分析数据。
+
+### 性能分析工作流
+
+1. 对疑似热点路径进行**基准测试**
+2. 使用 pprof **分析**以确认时间花在了哪里
+3. 使用本技能中的模式进行**优化**
+4. **重新基准测试**以用 benchstat 验证改进
+5. **重新分析**以检查是否出现新的瓶颈
+
+---
+
+## 常见错误
+
+### 忽略 b.N
+
+测试框架会调整 `b.N` 以获得稳定的计时。使用固定迭代次数会产生无意义的结果：
+
+```go
+// 不好：忽略 b.N —— 基准测试框架无法校准
+func BenchmarkFixed(b *testing.B) {
+    for i := 0; i < 1000; i++ {
+        doWork()
+    }
+}
+
+// 好：使用 b.N 作为循环边界
+func BenchmarkCorrect(b *testing.B) {
+    for i := 0; i < b.N; i++ {
+        doWork()
+    }
+}
+```
+
+### 未防止编译器优化消除
+
+如果函数调用的结果未被使用，编译器可能会完全优化掉该调用。将结果赋值给包级变量：
+
+```go
+// 不好：编译器可能会优化掉调用
+func BenchmarkElided(b *testing.B) {
+    for i := 0; i < b.N; i++ {
+        expensiveFunc()
+    }
+}
+
+// 好：赋值给包级变量以防止优化消除
+var benchResult int
+
+func BenchmarkKept(b *testing.B) {
+    var r int
+    for i := 0; i < b.N; i++ {
+        r = expensiveFunc()
+    }
+    benchResult = r
+}
+```

.agents/skills/go-performance/references/STRING-OPTIMIZATION.md

@@ -0,0 +1,134 @@
+# 字符串优化模式
+
+## strconv vs fmt
+
+在基本类型和字符串之间转换时，`strconv` 比 `fmt` 更快，因为 `fmt` 使用反射并处理任意类型。
+
+**不好：**
+
+```go
+for i := 0; i < b.N; i++ {
+    s := fmt.Sprint(rand.Int())
+}
+```
+
+**好：**
+
+```go
+for i := 0; i < b.N; i++ {
+    s := strconv.Itoa(rand.Int())
+}
+```
+
+**基准测试比较：**
+
+| 方式 | 速度 | 分配次数 |
+|------|------|---------|
+| `fmt.Sprint` | 143 ns/op | 2 allocs/op |
+| `strconv.Itoa` | 64.2 ns/op | 1 allocs/op |
+
+常用转换：
+
+| 任务 | `fmt` | `strconv` |
+|------|-------|-----------|
+| Int → string | `fmt.Sprint(n)` | `strconv.Itoa(n)` |
+| Int64 → string | `fmt.Sprint(n)` | `strconv.FormatInt(n, 10)` |
+| Float → string | `fmt.Sprint(f)` | `strconv.FormatFloat(f, 'f', -1, 64)` |
+| String → int | — | `strconv.Atoi(s)` |
+| Bool → string | `fmt.Sprint(b)` | `strconv.FormatBool(b)` |
+
+---
+
+## 重复的字符串到字节转换
+
+不要重复从固定字符串创建字节切片。应该只转换一次并保存结果。
+
+**不好：**
+
+```go
+for i := 0; i < b.N; i++ {
+    w.Write([]byte("Hello world"))
+}
+```
+
+**好：**
+
+```go
+data := []byte("Hello world")
+for i := 0; i < b.N; i++ {
+    w.Write(data)
+}
+```
+
+**基准测试比较：**
+
+| 方式 | 速度 |
+|------|------|
+| 重复转换 | 22.2 ns/op |
+| 单次转换 | 3.25 ns/op |
+
+好的版本**快约 7 倍**，因为它避免了每次迭代都分配新的字节切片。
+
+---
+
+## 字符串拼接
+
+根据复杂度选择正确的字符串构建策略。
+
+### 简单场景使用 `+`
+
+```go
+key := "projectid: " + p
+```
+
+`+` 运算符对于少量、固定数量的字符串是高效的。编译器通常可以优化相邻的字符串字面量。
+
+### 格式化使用 `fmt.Sprintf`
+
+```go
+// 好：清晰的格式化
+str := fmt.Sprintf("%s [%s:%d]-> %s", src, qos, mtu, dst)
+
+// 不好：使用 + 手动转换
+str := src.String() + " [" + qos.String() + ":" + strconv.Itoa(mtu) + "]-> " + dst.String()
+```
+
+当写入 `io.Writer` 时，直接使用 `fmt.Fprintf` 而不是先用 `fmt.Sprintf` 构建临时字符串。
+
+### 逐段构建使用 `strings.Builder`
+
+`strings.Builder` 花费摊销线性时间，而重复使用 `+` 或
+`fmt.Sprintf` 在构建大字符串时花费二次时间：
+
+```go
+b := new(strings.Builder)
+for i, d := range digitsOfPi {
+    fmt.Fprintf(b, "the %d digit of pi is: %d\n", i, d)
+}
+str := b.String()
+```
+
+### 常量多行字符串使用反引号
+
+```go
+// 好：原始字符串字面量
+usage := `Usage:
+
+custom_tool [args]`
+
+// 不好：使用转义序列拼接
+usage := "" +
+    "Usage:\n" +
+    "\n" +
+    "custom_tool [args]"
+```
+
+### 策略总结
+
+| 方法 | 最佳用途 | 性能 |
+|------|---------|------|
+| `+` | 少量字符串，简单拼接 | 小 n 时 O(n) |
+| `fmt.Sprintf` | 格式化输出 | 较慢，但更清晰 |
+| `strings.Builder` | 循环/逐段构建 | 摊销 O(n) |
+| `strings.Join` | 连接 slice | O(n) |
+| 反引号字面量 | 常量多行文本 | 零开销 |

.agents/skills/go-performance/scripts/bench-compare.sh

@@ -0,0 +1,252 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+VERSION="1.1.0"
+SCRIPT_NAME="$(basename "$0")"
+
+usage() {
+    cat <<EOF
+$SCRIPT_NAME v$VERSION — Run Go benchmarks with optional comparison
+
+USAGE
+    bash $SCRIPT_NAME [options] [package]
+
+DESCRIPTION
+    Wrapper around 'go test -bench' that runs benchmarks multiple times and
+    optionally compares results against a saved baseline using benchstat.
+
+    Results can be saved to a file for future comparison. If benchstat is
+    installed and a baseline is provided, a statistical comparison is shown.
+
+EXIT CODES
+    0    Benchmarks ran successfully
+    1    go test failed (compilation error, test failure, no benchmarks found)
+    2    Usage error (missing arguments, bad flags, file exists without --force)
+
+OPTIONS
+    -h, --help           Show this help message
+    -v, --version        Show version
+    -n, --count N        Number of benchmark iterations (default: 5)
+    -b, --baseline FILE  Compare results against this baseline file
+    -s, --save FILE      Save benchmark results to this file
+    -f, --filter REGEX   Benchmark filter regex (default: ".")
+    --json               Output metadata as JSON (human output goes to stderr)
+    --benchmem           Include memory allocation stats (default: on)
+    --no-benchmem        Disable memory allocation stats
+    --force              Allow --save to overwrite existing files
+    --limit N            Max benchmark result lines to include (default: 0 = all)
+
+ARGUMENTS
+    package              Go package to benchmark (default: ./...)
+
+EXAMPLES
+    bash $SCRIPT_NAME
+    bash $SCRIPT_NAME -n 10 ./pkg/parser
+    bash $SCRIPT_NAME --save baseline.txt ./...
+    bash $SCRIPT_NAME --baseline baseline.txt --save current.txt ./...
+    bash $SCRIPT_NAME --filter BenchmarkSort -n 3
+    bash $SCRIPT_NAME --json --limit 5 ./...
+    bash $SCRIPT_NAME --save results.txt --force ./...
+EOF
+}
+
+json_escape() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\t'/\\t}"
+    s="${s//$'\r'/}"
+    s="${s//$'\n'/\\n}"
+    printf '%s' "$s"
+}
+
+# Print human-readable output: stdout in text mode, stderr in JSON mode.
+log() {
+    if $JSON_OUTPUT; then
+        echo "$@" >&2
+    else
+        echo "$@"
+    fi
+}
+
+COUNT=5
+BASELINE=""
+SAVE=""
+FILTER="."
+PACKAGE=""
+JSON_OUTPUT=false
+BENCHMEM=true
+FORCE=false
+LIMIT=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        -h|--help)      usage; exit 0 ;;
+        -v|--version)   echo "$SCRIPT_NAME v$VERSION"; exit 0 ;;
+        -n|--count)     COUNT="${2:?error: --count requires a number}"; shift 2 ;;
+        -b|--baseline)  BASELINE="${2:?error: --baseline requires a file path}"; shift 2 ;;
+        -s|--save)      SAVE="${2:?error: --save requires a file path}"; shift 2 ;;
+        -f|--filter)    FILTER="${2:?error: --filter requires a regex}"; shift 2 ;;
+        --json)         JSON_OUTPUT=true; shift ;;
+        --benchmem)     BENCHMEM=true; shift ;;
+        --no-benchmem)  BENCHMEM=false; shift ;;
+        --force)        FORCE=true; shift ;;
+        --limit)        LIMIT="${2:?error: --limit requires a number}"; shift 2 ;;
+        -*)             echo "error: unknown option: $1" >&2; usage >&2; exit 2 ;;
+        *)              PACKAGE="$1"; shift ;;
+    esac
+done
+
+PACKAGE="${PACKAGE:-./...}"
+
+if ! command -v go &>/dev/null; then
+    echo "error: 'go' command not found in PATH" >&2
+    exit 2
+fi
+
+if ! [[ "$COUNT" =~ ^[1-9][0-9]*$ ]]; then
+    echo "error: --count must be a positive integer, got: $COUNT" >&2
+    exit 2
+fi
+
+if ! [[ "$LIMIT" =~ ^[0-9]+$ ]]; then
+    echo "error: --limit must be a non-negative integer, got: $LIMIT" >&2
+    exit 2
+fi
+
+if [[ -n "$BASELINE" && ! -f "$BASELINE" ]]; then
+    echo "error: baseline file not found: $BASELINE" >&2
+    exit 2
+fi
+
+if [[ -n "$SAVE" && -f "$SAVE" ]] && ! $FORCE; then
+    echo "error: save target already exists: $SAVE (use --force to overwrite)" >&2
+    exit 2
+fi
+
+HAS_BENCHSTAT=false
+if command -v benchstat &>/dev/null; then
+    HAS_BENCHSTAT=true
+fi
+
+BENCH_ARGS=(-bench "$FILTER" -count "$COUNT" -run '^$')
+if $BENCHMEM; then
+    BENCH_ARGS+=(-benchmem)
+fi
+
+TMPFILE=$(mktemp "${TMPDIR:-/tmp}/bench-XXXXXX.txt")
+trap 'rm -f "$TMPFILE"' EXIT
+
+log "Running benchmarks: go test ${BENCH_ARGS[*]} $PACKAGE"
+log "Iterations: $COUNT"
+log ""
+
+GO_EXIT=0
+if $JSON_OUTPUT; then
+    go test "${BENCH_ARGS[@]}" "$PACKAGE" 2>&1 | tee "$TMPFILE" >&2 || GO_EXIT=$?
+else
+    go test "${BENCH_ARGS[@]}" "$PACKAGE" 2>&1 | tee "$TMPFILE" || GO_EXIT=$?
+fi
+
+BENCH_COUNT=$(grep -cE '^Benchmark' "$TMPFILE" || true)
+
+TRUNCATED=false
+if [[ $LIMIT -gt 0 && $BENCH_COUNT -gt $LIMIT ]]; then
+    TRUNCATED=true
+fi
+
+if ! $JSON_OUTPUT && $TRUNCATED; then
+    log ""
+    log "Note: $BENCH_COUNT benchmark results found, showing first $LIMIT (--limit $LIMIT)"
+fi
+
+if [[ -n "$SAVE" ]]; then
+    cp "$TMPFILE" "$SAVE"
+    log ""
+    log "Results saved to: $SAVE"
+fi
+
+if [[ -n "$BASELINE" ]]; then
+    log ""
+    log "=== Comparison with baseline: $BASELINE ==="
+    log ""
+    if $HAS_BENCHSTAT; then
+        if $JSON_OUTPUT; then
+            benchstat "$BASELINE" "$TMPFILE" >&2 || true
+        else
+            benchstat "$BASELINE" "$TMPFILE" || true
+        fi
+    else
+        log "note: install benchstat for statistical comparison:"
+        log "  go install golang.org/x/perf/cmd/benchstat@latest"
+        log ""
+        log "--- Baseline ---"
+        if $JSON_OUTPUT; then
+            grep -E '^Benchmark' "$BASELINE" >&2 || true
+        else
+            grep -E '^Benchmark' "$BASELINE" || true
+        fi
+        log ""
+        log "--- Current ---"
+        if $JSON_OUTPUT; then
+            grep -E '^Benchmark' "$TMPFILE" >&2 || true
+        else
+            grep -E '^Benchmark' "$TMPFILE" || true
+        fi
+    fi
+fi
+
+FINAL_EXIT=0
+if [[ $GO_EXIT -ne 0 ]]; then
+    FINAL_EXIT=1
+    if ! $JSON_OUTPUT; then
+        log ""
+        log "error: go test exited with code $GO_EXIT"
+    fi
+elif [[ $BENCH_COUNT -eq 0 ]]; then
+    FINAL_EXIT=1
+    if ! $JSON_OUTPUT; then
+        log ""
+        log "error: no benchmarks found matching filter: $FILTER"
+    fi
+fi
+
+if $JSON_OUTPUT; then
+    BENCH_OUTPUT=$(<"$TMPFILE")
+    if $TRUNCATED; then
+        limited=""
+        bench_seen=0
+        while IFS= read -r line; do
+            if [[ "$line" =~ ^Benchmark ]]; then
+                bench_seen=$((bench_seen + 1))
+                if [[ $bench_seen -le $LIMIT ]]; then
+                    limited+="$line"$'\n'
+                fi
+            else
+                limited+="$line"$'\n'
+            fi
+        done < "$TMPFILE"
+        BENCH_OUTPUT="$limited"
+    fi
+
+    escaped_package=$(json_escape "$PACKAGE")
+    escaped_filter=$(json_escape "$FILTER")
+    escaped_baseline=$(json_escape "$BASELINE")
+    escaped_save=$(json_escape "$SAVE")
+    escaped_output=$(json_escape "$BENCH_OUTPUT")
+
+    printf '{"count":%d,' "$COUNT"
+    printf '"package":"%s",' "$escaped_package"
+    printf '"filter":"%s",' "$escaped_filter"
+    printf '"benchmarks_found":%d,' "$BENCH_COUNT"
+    printf '"baseline":"%s",' "$escaped_baseline"
+    printf '"save":"%s",' "$escaped_save"
+    printf '"exit_code":%d,' "$GO_EXIT"
+    printf '"output":"%s"' "$escaped_output"
+    if $TRUNCATED; then
+        printf ',"truncated":true'
+    fi
+    printf '}\n'
+fi
+
+exit $FINAL_EXIT

.agents/skills/logstore/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: "logstore"
-description: "Wavelet 项目专用：当新增或修改日志/分析用途表（访问日志、审计流水、可观测时序）、接入 internal/repository/logstore、切换日志主库、实现 PG/SQLite 回落，或判断一张表该走业务主库还是日志库时必须使用。"
+description: "OpenFlare / Wavelet：当新增或修改日志/分析用途表（节点访问日志、用户访问日志、可观测时序）、接入 internal/repository/logstore、切换日志主库、实现 PG/SQLite 回落，或判断一张表该走业务主库还是日志库时必须使用。"
 ---
 
 # 日志用途表开发
 
 开始前阅读根目录 `AGENTS.md`。DDL 用 `database-migration`；高频写入队列用 `clickhouse-batchwriter`；切换任务用 `new-async-task`。本技能只回答：**这张表是不是日志表，以及如何接入可切换的日志主库。**
 
-分层与切换协议见 [日志用途表](../../../docs/LOGSTORE.md)。
+设计背景见 [日志存储解耦](../../../docs/design/logstore.md)。
 
 ## 先判定
 
@@ -16,77 +16,60 @@ description: "Wavelet 项目专用：当新增或修改日志/分析用途表（
 - 追加写入、几乎不更新单行
 - 按时间查询/聚合，允许按保留天数删除
 - 关闭 ClickHouse 后仍要能写、能查
-- 不参与用户/配置/任务等事务一致性
+- 不参与网站/节点/证书等事务一致性
 
-**不要**做成日志表：用户、配置、任务执行、上传元数据、需要事务或强一致的业务实体。这些走主库 `repository`，不要进 `logstore`。
+**不要**做成日志表：Zone、节点、配置版本、任务执行、上传元数据。这些走主库 `repository`。
 
-当前框架已接入的日志表：`w_user_access_logs`（管理端 API 访问审计）。
+当前日志域：
+
+| 域 | 接口 | 表 |
+| :--- | :--- | :--- |
+| 节点访问日志 | `AccessLogStore` | `of_node_access_logs` |
+| 可观测 | `ObservabilityStore` | `of_node_metric_snapshots` / `of_node_edge_health` / `of_node_obs_frps` / `of_node_obs_frpc` |
+| 用户访问审计 | `UserAccessLogStore` | `w_user_access_logs` |
 
 ## 分层
 
 | 层级 | 路径 | 职责 |
 | :--- | :--- | :--- |
-| 抽象 | `internal/repository/logstore` | 接口 + `Active`/`BuildForMigration`；apps **只**面向这里 |
-| CH 实现 | `logstore` 委托 `internal/repository/analytics` | 原生 `PrepareBatch` / `ChDB` 查询 |
-| 主库实现 | `logstore` GORM | PG（按月分区）与 SQLite（普通表） |
-| Model | `internal/model/analytics` | 实体、`TableName`、`InsertColumns`、`BatchInsertSQL`，无 IO |
-| 入队 | `internal/apps/<domain>` + `batchwriter` | `FlushFunc` 调 `logstore.Active().….BatchInsert` |
-| 切换 | `internal/apps/admin/logs` 的 `logs:db_switch` | 冻结写入 → 排空 → 复制 → 翻转 `log_database` |
-| 清理 | `logstore.CleanupExpired`，由 `system:cleanup` 调用 | 按库读取保留天数后 `DeleteBefore` |
+| 抽象 | `internal/repository/logstore` | 接口 + `Active`/`BuildForMigration`；apps **只**面向这里或 `repository` 门面 |
+| CH 实现 | `logstore/clickhouse_store.go` 委托 `analytics` | 原生批量 + 现有聚合 SQL |
+| 主库实现 | `logstore/postgres_store.go` | PG（按月分区）与 SQLite（普通表）共用 GORM |
+| Model | `internal/model/analytics` | 实体与批量 SQL，无 IO |
+| 入队 | `chwriter` / `risk_control` + `batchwriter` | flush 调 logstore `BatchInsert*`；CH 入队经 hooks |
+| 切换 | `of_log_db_switch` | 冻结 → `chwriter.Drain` → 逐表复制 → 翻转 |
+| 约束 | `logstore/imports_test.go` | apps 禁止 import `repository/analytics` |
 
-`log_database` ∈ {`postgres`,`sqlite`,`clickhouse`}，且只能是「随主库」或 ClickHouse：主库为 PG 时日志不能是 SQLite，反之亦然。`log_database` / `log_db_migration` 受保护，禁止管理端手动改。
+`log_database` 只能是「随主库」或 `clickhouse`。`log_database` / `log_db_migration` 受保护。
 
 ## 新增一张日志表
 
-按顺序做，列名三库必须一致。
-
-1. **Model**  
-   在 `internal/model/analytics/` 定义 struct；实现 `TableName()`；批量写再提供 `InsertColumns()` / `BatchInsertSQL()`。
-
-2. **三套 DDL**（`database-migration`）  
-   - ClickHouse：`goose/clickhouse/`，`MergeTree`，`PARTITION BY toYYYYMM(时间列)`。  
-   - PostgreSQL：`goose/postgres/`，高频表用 `PARTITION BY RANGE (时间列)`，复合主键必须包含分区键。  
-   - SQLite：`goose/sqlite/`，普通表 + 时间/过滤列索引。  
-   不要在 PG/SQLite 上复制 CH 物化视图；聚合在查询时实时算。
-
-3. **logstore 接口**  
-   在对应 Store（现有 `UserAccessLogStore`，或新域自建接口并挂到 `Store`）补齐至少：
-   - 写入：`BatchInsert`（flush 目标；内调 `ensureWritable`）
-   - 查询：业务需要的 List/Count/聚合
-   - 迁移：`ListForMigration(afterID, limit)`、`MigrationRange`、`DeleteAll`、`EnsurePartitions`（PG 按月预建，CH/SQLite no-op）
-   - 清理：`DeleteBefore(cutoff)`、`DropEmptyPartitions`、`DropExpiredPartitions`（仅 PG；CH/SQLite no-op）
-
-4. **双实现**  
-   - CH：委托 `analyticsrepo`，零额外查询路径。  
-   - GORM：PG/SQLite 共用一套；方言 SQL 只放小函数（如按日 `to_char` / `strftime`）。零值 `id` 落库前用 `idgen.NextUint64ID()`。
-
-5. **`buildStore`**  
-   在 `provider.go` 的 CH / GORM 分支同时挂上新域。
-
-6. **写入**  
-   apps 用独立 `batchwriter` 实例；`FlushFunc` → `logstore.Active(ctx)` → `BatchInsert`。禁止 `analyticsrepo.BatchInsert`、禁止 `db.ChConn`。迁移任务调用域的 `Drain`（等队列空一个 flush 周期，不要 `Stop` writer）。
-
-7. **切换任务**  
-   在 `copy*` 流程增加该表：`DeleteAll` 目标 → `MigrationRange` + `EnsurePartitions` → 按 id 分页复制。不要改切换协议（仍冻结写入、源数据不删、成功才翻转）。
-
-8. **清理**  
-   `CleanupExpired`：PG 先 `DropExpiredPartitions`（整月过期分区），再 `DeleteBefore`（边界月），最后 `DropEmptyPartitions`。保留天数用已有 `log_retention_days_*`。apps 禁止 import `repository/analytics`（`imports_test.go`）。
+1. **Model**（`internal/model/analytics`）：`TableName` + `InsertColumns` / `BatchInsertSQL`。
+2. **三套 DDL**：CH `MergeTree` + `toYYYYMM`；PG `PARTITION BY RANGE(时间列)`（主键含分区键）；SQLite 普通表。不要在主库建 CH 物化视图，聚合实时算。
+3. **挂到已有域或新接口**：能进 `AccessLogStore` / `ObservabilityStore` / `UserAccessLogStore` 就不要再拆包。新域才新增接口并放进 `Store`。
+4. **方法最少集**：`BatchInsert`（含 `ensureWritable`）、业务查询、`ListForMigration`、`MigrationRange`、`DeleteAll`、`DeleteBefore`、`EnsurePartitions`（仅 PG 预建）。
+5. **双实现**：CH 委托 `analyticsrepo`；GORM 共用一套，方言 SQL 放 `dialect_*.go`。零值 id 用 `idgen.NextUint64ID()`。
+6. **`buildStore`**：CH / GORM 两分支都挂上。
+7. **写入**：独立 `batchwriter`；`FlushFunc` → `logstore.Active`。节点日志/可观测走 `SetAccessLogHooks` / `SetObservabilityHooks`，不要让 apps 碰 `ChConn`。
+8. **切换任务**：`clearTarget` + `copy*` 增加该表；源数据不删，失败不翻转。
+9. **清理**：访问类走 `log_retention_days_*`；性能指标走 `metric_retention_days`。不要擅自共用错误的 TTL。
+10. **import-lint**：apps 新增对 `analytics` 或 `infra/persistence`（`batchwriter`/`idgen` 除外）的 import 必须失败。
 
 ## 禁止
 
-- apps 直接 `import` `internal/repository/analytics` 或 `db.ChConn` / `db.ChDB` 做日志读写
-- 只建 CH 表、不建 PG/SQLite 回落
-- 在 Handler 里逐条 `PrepareBatch` + `Send`
-- 把业务表「顺便」放进 logstore 以便关 CH
-- 管理端 API 改 `log_database` / `log_db_migration`
+- apps 直连 `analyticsrepo` / `db.ChConn` / `db.ChDB` 做日志读写
+- 只建 CH、不建主库回落
+- Handler 内逐条 `PrepareBatch`
+- 业务表塞进 logstore
+- 管理端改 `log_database` / `log_db_migration`
 
 ## 验证
 
 ```bash
 go test ./internal/repository/logstore ./internal/repository/analytics
-go test ./internal/apps/admin/logs ./internal/apps/risk_control ./internal/platform/bootstrap
-make swagger   # 若改了状态/查询 API
+go test ./internal/apps/openflare/... ./internal/apps/admin/logs ./internal/apps/admin/status
+make swagger
 make code-check
 ```
 
-对照：`w_user_access_logs` 的 model、三库 goose、`logstore` GORM/CH、`risk_control.InitLogWriter`、`logs.LogDBSwitchHandler`、`system:cleanup`。
+对照：`of_node_access_logs` 或 `w_user_access_logs` 的 model、三库 goose、`logstore` 双实现、`chwriter`/`risk_control` flush、`LogDBSwitchHandler`。

.agents/skills/new-api/SKILL.md

@@ -1,219 +1,82 @@
 ---
 name: "new-api"
-description: "Wavelet 项目专用：当新增或修改业务 API、Handler、服务层逻辑、路由注册时必须使用。本技能指导 apps 业务包划分、路由注册、Handler/logics 分层、Swagger 与质量门禁；纠正把一切塞进 custom.go / apps/custom 或产品伞包的错误写法。"
+description: "Wavelet 项目专用：当新增或修改自定义业务 API、新增业务路由、新增 service 层核心逻辑时必须使用。本技能指导包职责划分、推荐文件结构、路由解耦、Swagger 文档生成与质量门禁验证。"
 ---
 
 # 新增业务 API 开发与路由注册规范
 
-本技能是 Wavelet 接口开发与路由注册的唯一指导规范。在开发任何新接口前，请按本指南做架构决策与路由注册。
+本技能是 Wavelet 项目接口开发与路由注册的唯一指导规范。在开发任何新接口前，请严格按照本指南进行架构决策与路由注册。
 
 ---
 
-## 先搞清：脚手架 vs 产品化
+## 核心路由准则与防线 (Routing Governance & Guardrails)
 
-Wavelet 是**通用全栈脚手架**。仓库里的 `custom` 相关代码是**示例/占位**，不是产品业务的标准落点。
+Wavelet 后端路由采用了**严格的框架层与业务层隔离机制**。请牢记以下开发原则：
 
-| 层级 | 含义 | 典型包 |
-| :--- | :--- | :--- |
-| **平台能力** | 脚手架自带、与具体产品无关 | `oauth`、`user`、`admin/*`、`upload`、`cap`、`config`、`health`、`risk_control` |
-| **产品业务** | 基于脚手架做具体产品时新增的域 | 直接落在 `internal/apps/<domain>/`，与平台包**平级** |
+### 插件目录标准结构 (`backend/openflare/plugins/<name>/` 或 `backend/plugins/domain/<name>/`)
 
-**一旦用脚手架开发具体产品，整个仓库就是该产品**——例如要做「消息平台」，业务模块应是 `apps/channel`、`apps/conversation`、`apps/delivery` 等，而不是先建 `apps/message` 伞包再往里塞子模块。
-
----
-
-## 反模式（AI 最常踩的坑）
-
-### 1. 把所有业务路由塞进 `custom.go` / 路径前缀 `/custom`
-
-仓库中的：
-
-- `internal/router/v1/custom.go`
-- `internal/router/root/custom.go`
-- `internal/apps/custom/`
-
-是**演示如何挂一条示例接口**（`GET /api/v1/custom/hello`），**不是**「所有自定义业务必须写在这里」的规定。
-
-| 错误 | 正确 |
-| :--- | :--- |
-| 新功能一律改 `v1/custom.go`，路径全是 `/api/v1/custom/...` | 按域新建 `apps/<domain>/`，路由用语义化路径（如 `/api/v1/channels`），在 `router/v1/` 下用**独立注册文件**挂载 |
-| 把 `custom` 包当成业务垃圾桶 | 保留或删除示例均可；真正业务用独立包名 |
-
-### 2. 产品伞包 + 深层子包
-
-| 错误 | 正确 |
-| :--- | :--- |
-| `apps/message/channel`、`apps/message/inbox`、`apps/message/delivery`（先套一层产品名） | `apps/channel`、`apps/inbox`、`apps/delivery`（域模块与 `oauth`/`user` 平级） |
-| `apps/myapp/...` 再嵌套所有业务 | 仓库即产品，**不要**再包一层产品根 |
-
-**判定**：模块名应对齐**业务能力/限界上下文**（channel、order、invoice），而不是对齐产品营销名（message-platform、myapp）。
-
-### 3. 其它仍须遵守的防线
-
-- 不要在 `internal/router/router.go` 里直接挂业务 Handler（只做高层委派）。
-- 不要破坏平台模块既有语义去硬塞无关业务（例如把消息逻辑塞进 `apps/user`）。
-- 错误响应使用 `response.Abort*`，禁止 `c.JSON(..., response.Err(...))`（见 `AGENTS.md`）。
-
----
-
-## 路由注册模型
-
-### 谁可以改
-
-| 文件 | 角色 | 产品化时 |
-| :--- | :--- | :--- |
-| `internal/router/router.go` | 引擎、中间件、委派入口 | 一般不改；特殊全局中间件才动 |
-| `internal/router/v1/v1.go` | V1 分发：调用各 `Register*Routes` | **允许**：增加对新业务注册函数的一行调用 |
-| `internal/router/v1/user.go` / `admin.go` | 平台用户端 / 管理端路由 | **优先不改**；仅当扩展平台能力（OAuth、上传、用户资料）时修改 |
-| `internal/router/v1/<domain>.go`（新建） | 产品业务路由注册 | **推荐落点** |
-| `internal/router/v1/custom.go` | **示例** | 可删可留；**不要**把真实业务堆在这里 |
-| `internal/router/root/default.go` / `frontend.go` | 文件服务、health、前端静态 | 平台级，勿塞产品 API |
-| `internal/router/root/custom.go` | 根路径**示例**占位 | 仅当确需根路径回调/短链时，用**语义路径**注册，或新建 `root/<domain>.go` 并由 `root.go` 调用 |
-
-### 路径归属（产品 API 用语义路径）
-
-| 目标路径特征 | 注册位置 | 说明 |
-| :--- | :--- | :--- |
-| `/api/v1/<domain>/...`（如 `/api/v1/channels`） | `v1/<domain>.go` 的 `Register<Domain>Routes`，在 `v1.go` 调用 | **产品业务默认做法** |
-| `/api/v1/admin/<domain>/...` | 管理端：可在 `admin.go` 增加小组，或 `v1/admin_<domain>.go` 再由 `RegisterAdminRoutes`/ `v1.go` 组装 | 需 `admin.LoginAdminRequired()` |
-| `/api/v1/user/...`、`/oauth/...`、`/upload/...` 等 | `user.go` 等平台文件 | 平台能力，勿把无关产品塞进来 |
-| 根路径特殊接口（Webhook、短链） | `root` 下独立注册函数 | **不要**默认塞进 `custom` 前缀 |
-| `GET /f/:id`、`/api/health`、`robots.txt` | `root/default.go` | 平台，勿改用途 |
-
-`custom.go` 里现有的 `/api/v1/custom/...` **仅作脚手架演示**，不代表业务必须挂在 `/custom` 下。
-
----
-
-## 推荐目录结构（产品业务）
-
-以「频道 / channel」域为例（消息平台中的一个限界上下文）：
+所有标准插件与下游定制插件，**统一以 `backend/downstream/plugins/custom_example` 为基准模板**，严格采用物理子包隔离的分层架构：
 
 ```text
-internal/
-├── router/
-│   └── v1/
-│       ├── v1.go              # [修改] 调用 RegisterChannelRoutes
-│       └── channel.go         # [新建] 只负责挂载 channel 路由
-└── apps/
-    └── channel/               # 与 oauth、user、upload 平级
-        ├── routers.go         # HTTP Handlers（绑定、鉴权上下文、响应）
-        ├── logics.go          # 纯业务：context.Context，无 gin
-        ├── errs.go            # 模块错误文案常量（可选）
-        └── ...                # 需要时再加 service.go、tasks.go 等
+backend/openflare/plugins/<name>/ (或 backend/plugins/domain/<name>/)
+├── plugin.go           # 插件根入口：实现 core.Plugin，装配各子包并向 Cordis 注册
+│
+├── consts/             # package consts：常量、配置键名与错误码定义
+│   └── consts.go
+│
+├── controller/         # package controller：HTTP 控制器与路由声明 (参数绑定、会话获取、信封响应)
+│   └── hello/          # 业务分组/实体子包
+│       └── hello.go    # 接口处理 Handler（直接以业务命名，禁止 controller_hello.go）
+│
+├── service/            # package service：业务逻辑层（用例编排、事务控制、事件发布）
+│   └── order.go        # 订单业务用例实现（纯 Go 逻辑，禁止依赖 *gin.Context）
+│
+├── dao/                # package dao：数据访问持久化层 DAL (GORM CRUD、SQL 转义防注入)
+│   └── order.go        # 订单数据访问实现（直接以业务命名，禁止 dao_order.go）
+│
+├── model/              # package model：纯数据实体与 DTO（无外部依赖）
+│   ├── entity/         # 数据库映射实体 (TableName() 带插件专属前缀)
+│   │   └── order.go
+│   └── do/             # 请求 Request DTO 与响应 Response DTO、领域对象
+│       └── order.go
+│
+└── migrations/         # 专属嵌入式 Goose SQL 双方言迁移脚本 (//go:embed)
+    ├── postgres/       # PostgreSQL 迁移脚本
+    └── sqlite/         # SQLite 迁移脚本
 ```
-
-**不要**建成：
-
-```text
-internal/apps/message/          # ❌ 产品伞包
-    channel/
-    inbox/
-internal/apps/custom/           # ❌ 示例包当业务垃圾桶
-    channel_handler.go
-```
-
-模块内若复杂度高，可在**该域包内**分子目录（如 `apps/channel/handler`），但仍是一个域包，不是「产品名/子域」两层品牌结构。
+> ⚠️ **严禁**：严禁在根目录平铺 `handlers_*.go`、`service_*.go`、`dao_*.go` 等前缀文件，子包内文件直接按业务实体命名。严格约束 `controller -> service -> dao -> model` 单向依赖。
 
 ---
 
-## 路由注册示例
+## 核心开发步骤 (Step-by-Step Flow)
 
-### `internal/router/v1/channel.go`（产品业务）
+### 步骤 1：数据库定义与迁移
+如果自定义功能涉及新表或字段，请参考 [database-migration](../database-migration/SKILL.md) 技能，在 `internal/infra/persistence/migrator/goose/` 目录下编写迁移文件，在 `internal/model/` 中定义 GORM 实体（无 CRUD / 无 DB 访问），并在 `internal/repository/` 中实现数据访问（**repository 为唯一持久化入口**）。
 
-```go
-package v1
+### 步骤 2：在模块内实现业务逻辑 (`logics.go` / `service.go`)
+业务逻辑逻辑应当实现于 `internal/apps/custom/` 目录下：
+- **优先使用纯函数（`logics.go`）**：定义接收 `context.Context` 且不依赖 `*gin.Context` 的函数，易于单元测试与 Worker 复用。参考 `internal/apps/user/logics.go`。
+- **有状态服务（`service.go`）**：若需注入依赖（如 DB 连接、外部客户端等），可定义 Service 结构体和构造函数。
+- **跨模块副作用（推送、任务监听等）**：核心业务代码通过 `internal/listener` 发射域事件，禁止直接 `import` push 模块；装配在 `internal/platform/bootstrap` 完成（参见 `push-notification` skill）。
 
-import (
-	"github.com/Rain-kl/Wavelet/internal/apps/channel"
-	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
-	"github.com/gin-gonic/gin"
-)
+### 步骤 3：编写 HTTP Handler (`routers.go`)
+在 `internal/apps/custom/routers.go` 中编写 Handler：
+- 负责请求参数绑定与校验（使用 `ShouldBindJSON`/`ShouldBindQuery`）。
+- 负责提取 Session / 用户身份。
+- 调用业务逻辑层，并使用 `OpenFlare/internal/shared/response` 统一返回响应：
+  - 成功时返回：`response.OK(data)` 或 `response.OKNil()`
+  - 失败时返回：`response.Err(msg)`
+- 编写规范的 Swagger 注释。
 
-// RegisterChannelRoutes mounts channel domain APIs under /api/v1.
-func RegisterChannelRoutes(apiV1Router *gin.RouterGroup) {
-	r := apiV1Router.Group("/channels")
-	r.Use(oauth.LoginRequired())
-	{
-		r.GET("", channel.ListChannels)
-		r.POST("", channel.CreateChannel)
-		r.GET("/:id", channel.GetChannel)
-	}
-}
-```
-
-### `internal/router/v1/v1.go`（增加一行委派）
-
-```go
-func RegisterV1Routes(apiV1Router *gin.RouterGroup, apiGroup *gin.RouterGroup) {
-	RegisterUserRoutes(apiV1Router, apiGroup)
-	RegisterAdminRoutes(apiV1Router)
-	RegisterChannelRoutes(apiV1Router) // 产品域
-	RegisterCustomRoutes(apiV1Router)  // 可选：仅保留脚手架示例
-}
-```
-
-### 根路径 Webhook（确有需要时）
-
-在 `root` 用语义路径，例如 `POST /webhooks/stripe`，注册函数可放在 `root/webhooks.go` 或扩展现有 root 注册；**不要**为了「只能写 custom」而使用无意义的 `/custom` 前缀。
+### 步骤 4：在自定义包中注册路由并委派
+根据 **路由归属判定表**，在 [root/custom.go](file:///Users/ryan/DEV/Go/Wavelet/internal/router/root/custom.go) 或 [v1/custom.go](file:///Users/ryan/DEV/Go/Wavelet/internal/router/v1/custom.go) 中编写注册代码，将路由路径绑定到步骤 3 中编写的 Handler。
 
 ---
 
-## 核心开发步骤
+## 质量验证门禁 (Quality Gates)
 
-### 步骤 1：划定域包名
-
-- 用**业务能力**命名：`channel`、`order`、`invoice`。
-- 与现有 `apps/` 下平台包平级；禁止产品伞包。
-
-### 步骤 2：库表与 model
-
-若涉及新表/字段：按 [database-migration](../database-migration/SKILL.md) 在 goose 迁移与 `internal/model/` 中定义。
-
-### 步骤 3：`logics.go` / `service.go`
-
-放在 `internal/apps/<domain>/`：
-
-- **优先**纯函数 `logics.go`：`context.Context` 入参，无 `*gin.Context`。
-- 有状态依赖时用 `service.go` 构造注入。
-- 跨模块副作用（推送、任务）经 `internal/listener` + `bootstrap`，禁止业务直接 import push（见 `push-notification`）。
-
-### 步骤 4：Handler（`routers.go`）
-
-- `ShouldBindJSON` / `ShouldBindQuery`。
-- 成功：`c.JSON(http.StatusOK, response.OK(data))` 或 `response.OKNil()`。
-- 失败：`response.AbortBadRequest` / `AbortUnauthorized` / `AbortNotFound` / `AbortInternal` 等，**禁止** `response.Err` 直接 `c.JSON`。
-- 完整 Swagger 注释；`@Router` 使用真实语义路径。
-
-参考：`references/handler_example.go`、`logics_example.go`、`service_example.go`（示例域名，非强制包名 `custom`）。
-
-### 步骤 5：注册路由
-
-新建 `internal/router/v1/<domain>.go`，在 `v1.go` 调用；管理端按需挂到 admin 组。
-
----
-
-## 与平台路由的边界
-
-- **扩展平台能力**（用户资料字段、上传策略、OAuth 源）：改对应平台 `apps/*` 与 `user.go`/`admin.go`。
-- **新产品功能**：新建 `apps/<domain>` + `router/v1/<domain>.go`，**不要**塞进 `custom` 或某个无关平台包。
-- 管理端产品配置页 API：路径宜为 `/api/v1/admin/<domain>/...`，中间件与现有 admin 组一致。
-
----
-
-## 质量验证门禁
-
-1. `make license`（新 Go 文件许可头）
-2. `make swagger`（Handler/Swagger 有变时）
-3. `make format` 与 `make code-check`
-4. `go test` 覆盖相关包
-
----
-
-## 自检清单
-
-- [ ] 未把真实业务堆进 `apps/custom` 或 `v1/custom.go`
-- [ ] 未创建 `apps/<产品名>/` 伞包再塞子域
-- [ ] 业务包与 `oauth`/`user`/`upload` 平级，路径语义化（非强制 `/custom`）
-- [ ] 路由在 `router/v1/<domain>.go`（或 admin 对应处）注册，并由 `v1.go` 委派
-- [ ] Handler 用 `response.Abort*` / `response.OK`，logics 不依赖 gin
-- [ ] 需要时已跑 swagger / code-check
+每次新增或修改接口后，必须运行并验证以下各项：
+1. **自动授权许可**：`make license`（新增 Go 文件时自动添加许可头）
+2. **重新生成 Swagger 文档**：`make swagger`（若有 Swagger 注释修改）
+3. **静态代码及风格检查**：`make code-check`（确保通过 golangci-lint 和前端 TS 检查）
+4. **自动化单元测试**：`go test ./...`（确保所有测试 100% 通过）

.agents/skills/new-api/references/handler_example.go

@@ -6,50 +6,53 @@ package references
 import (
 	"net/http"
 
-	"github.com/Rain-kl/Wavelet/internal/shared/response"
+	"OpenFlare/internal/service"
+	"OpenFlare/internal/util"
 	"github.com/gin-gonic/gin"
 )
 
-// createChannelRequest 客户端请求体 DTO
-type createChannelRequest struct {
-	Name string `json:"name" binding:"required,min=1,max=100"`
+// customRequest 客户端请求体 DTO
+type customRequest struct {
+	Payload string `json:"payload" binding:"required,min=1,max=100"`
 }
 
-// createChannelResponse API 响应体 DTO
-type createChannelResponse struct {
-	ID   int64  `json:"id"`
-	Name string `json:"name"`
+// customResponse API 响应体 DTO
+type customResponse struct {
+	Result string `json:"result"`
 }
 
-// CreateChannel 示例：产品域 Handler（应放在 internal/apps/channel/routers.go）
-// @Summary 创建频道
-// @Description 示例：语义路径下的业务接口，而非 /api/v1/custom/...
-// @Tags channel
+// HandleCustomBusiness 示例 API Handler
+// @Summary 示例定制业务接口
+// @Description 接收数据载荷，调用 Service 执行核心逻辑，并返回统一格式的 JSON 结果。
+// @Tags custom
 // @Accept json
 // @Produce json
-// @Param request body createChannelRequest true "业务请求参数"
-// @Success 200 {object} response.Any{data=createChannelResponse} "操作成功"
-// @Failure 400 {object} response.Any "参数错误"
-// @Failure 401 {object} response.Any "未登录"
-// @Router /api/v1/channels [post]
-func CreateChannel(c *gin.Context) {
-	var req createChannelRequest
+// @Param request body customRequest true "业务请求参数"
+// @Success 200 {object} util.ResponseAny{data=customResponse} "操作成功"
+// @Router /api/v1/custom/business [post]
+func HandleCustomBusiness(c *gin.Context) {
+	// 1. 参数绑定与校验
+	var req customRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		response.AbortBadRequest(c, "参数校验失败")
+		c.JSON(http.StatusBadRequest, util.Err("参数校验失败：载荷不能为空且在 1-100 字符内"))
 		return
 	}
 
-	// 通常结合 oauth.LoginRequired()；此处仅演示从上下文取用户
+	// 2. 模拟获取当前上下文与已登录用户（例如从 Session 中提取）
+	// 通常结合 oauth.LoginRequired() 等中间件使用
 	userID := int64(9527)
 
-	result, err := CreateChannelLogic(c.Request.Context(), userID, req.Name)
+	// 3. 实例化业务 Service 并调用核心逻辑
+	// 注意传入 c.Request.Context() 以正确传递 OpenTelemetry Tracing 等上下文信息
+	svc := service.NewCustomService()
+	resText, err := svc.ProcessBusinessData(c.Request.Context(), userID, req.Payload)
 	if err != nil {
-		response.AbortBadRequest(c, err.Error())
+		c.JSON(http.StatusInternalServerError, util.Err(err.Error()))
 		return
 	}
 
-	c.JSON(http.StatusOK, response.OK(createChannelResponse{
-		ID:   result.ID,
-		Name: result.Name,
+	// 4. 返回符合外层形状规范 { "error_msg": "", "data": ... } 的统一成功响应
+	c.JSON(http.StatusOK, util.OK(customResponse{
+		Result: resText,
 	}))
 }

.agents/skills/new-api/references/logics_example.go

@@ -8,31 +8,25 @@ import (
 	"errors"
 	"fmt"
 
-	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"OpenFlare/pkg/logger"
 	"go.uber.org/zap"
 )
 
-// channelCreated 示例 logics 返回值（真实代码可用 model 或专用 DTO）
-type channelCreated struct {
-	ID   int64
-	Name string
-}
-
-// CreateChannelLogic 示例：模块内闭环业务（放在 apps/channel/logics.go）
-// 接收 context.Context，不依赖 gin.Context，便于单测与 Worker 复用。
-func CreateChannelLogic(ctx context.Context, userID int64, name string) (*channelCreated, error) {
-	if name == "" {
-		return nil, errors.New("name cannot be empty")
+// ProcessLocalBusiness 示例的模块内部闭环业务逻辑
+// 1. 存放在 apps/custom/logics.go 下，遵循纯 Go 规范，不强依赖 gin.Context，以便逻辑清晰和便于单元测试。
+// 2. 用于当前应用模块内的简单业务或通用过程。
+func ProcessLocalBusiness(ctx context.Context, userID int64, param string) (string, error) {
+	if param == "" {
+		return "", errors.New("param cannot be empty")
 	}
 
-	logger.Info(ctx, "creating channel",
+	logger.Info(ctx, "processing local business inside apps/custom/logics",
 		zap.Int64("user_id", userID),
-		zap.String("name", name),
+		zap.String("param", param),
 	)
 
-	// 轻量级本地逻辑；复杂持久化可进 model/repository
-	return &channelCreated{
-		ID:   1,
-		Name: fmt.Sprintf("%s (by %d)", name, userID),
-	}, nil
+	// 执行轻量级、无需跨模块/多入口复用的本地计算或模型操作
+	result := fmt.Sprintf("Processed local logic for user %d: %s", userID, param)
+
+	return result, nil
 }

.agents/skills/new-api/references/service_example.go

@@ -8,33 +8,38 @@ import (
 	"errors"
 	"fmt"
 
-	"github.com/Rain-kl/Wavelet/pkg/logger"
+	"OpenFlare/pkg/logger"
 	"go.uber.org/zap"
 )
 
-// ChannelService 示例有状态 Service（放在 internal/apps/channel/service.go）
-// 需要注入 DB/客户端时使用；简单逻辑优先 logics.go 纯函数。
-type ChannelService struct {
-	// 例如：repo ChannelRepository
+// CustomService 示例业务 Service 结构体（通常放在 internal/apps/custom/service.go 中）
+type CustomService struct {
+	// 这里可以注入数据库连接、配置对象或者其他基础服务的客户端
+	// 例如：db *gorm.DB
 }
 
-// NewChannelService 构造函数
-func NewChannelService() *ChannelService {
-	return &ChannelService{}
+// NewCustomService 创建 CustomService 实例的构造函数
+func NewCustomService() *CustomService {
+	return &CustomService{}
 }
 
-// Create 核心业务：首位参数必须是 context.Context；禁止依赖 Gin。
-func (s *ChannelService) Create(ctx context.Context, userID int64, name string) (int64, error) {
-	if name == "" {
-		return 0, errors.New("name cannot be empty")
+// ProcessBusinessData 演示核心业务处理逻辑的 Service 方法
+// 1. 首位参数必须是 context.Context，以传播链路追踪 (OTel) 和超时控制。
+// 2. 方法签名应该只包含纯 Go 的参数与返回值，禁止导入 Gin 或与 HTTP 相关的协议依赖。
+// 3. 将可能发生的核心异常通过 error 返回给上层，而不是在这一层转换成 HTTP 状态码。
+func (s *CustomService) ProcessBusinessData(ctx context.Context, userID int64, payload string) (string, error) {
+	if payload == "" {
+		return "", errors.New("payload cannot be empty")
 	}
 
-	logger.Info(ctx, "channel service create",
+	// 模拟执行业务逻辑...
+	logger.Info(ctx, "processing custom business data in service",
 		zap.Int64("user_id", userID),
-		zap.String("name", name),
+		zap.String("payload", payload),
 	)
 
-	// DB 事务、远程调用等
-	_ = fmt.Sprintf("user=%d name=%s", userID, name)
-	return 1, nil
+	// 这里可以包含数据库读写、事务控制、或者远程 API 调用等复杂逻辑。
+	result := fmt.Sprintf("Success processed data for user %d: %s", userID, payload)
+
+	return result, nil
 }

.agents/skills/new-async-task/SKILL.md

@@ -19,7 +19,8 @@ description: "Wavelet 项目专用：新增或修改 Asynq 异步任务、后台
 - `internal/infra/task/worker/worker.go`：Worker 路由和队列
 - `internal/infra/task/scheduler/scheduler.go`：定时调度
 - `internal/apps/admin/task/routers.go`：Admin 任务 API
-- `internal/model/task_execution.go`：执行记录和日志持久化
+- `internal/model/task_execution.go`：执行记录实体与 DTO
+- `internal/repository/task_execution.go`：执行记录和日志持久化
 
 需要模板时阅读 [references/CODE-EXAMPLES.md](references/CODE-EXAMPLES.md)。
 
@@ -42,7 +43,7 @@ description: "Wavelet 项目专用：新增或修改 Asynq 异步任务、后台
 - 成功返回 `&task.TaskResult{Message: ..., Detail: ...}`。
 - 失败返回 error，由任务框架处理状态和重试。
 - 不要吞掉关键错误。
-- 复杂 SQL 放到 `internal/model/` 或模块内的业务服务层（如 `internal/apps/<module>/service.go` 或 `logics.go`）。
+- 持久化只通过 `internal/repository/`（唯一入口）；业务编排放模块内 `logics.go` / `service.go`。`internal/model` 仅实体/DTO，禁止 CRUD 与 DB 访问。
 
 ### 注册
 

.agents/skills/new-async-task/references/CODE-EXAMPLES.md

@@ -10,7 +10,7 @@
 package upload
 
 import (
-    "github.com/Rain-kl/Wavelet/internal/task"
+    "OpenFlare/internal/infra/task"
 )
 
 // 异步任务类型标识。格式建议为 "{module}:{action}"。
@@ -83,7 +83,7 @@ package upload
 import (
     "context"
 
-    "github.com/Rain-kl/Wavelet/internal/task"
+    "OpenFlare/internal/infra/task"
 )
 
 type CleanupUnusedUploadsHandler struct{}
@@ -114,7 +114,7 @@ import (
     "fmt"
     "strings"
 
-    "github.com/Rain-kl/Wavelet/internal/task"
+    "OpenFlare/internal/infra/task"
 )
 
 type SendEmailPayload struct {
@@ -169,9 +169,9 @@ func (h *SendEmailHandler) Execute(ctx context.Context, payload []byte) (*task.T
 package handlers
 
 import (
-    "github.com/Rain-kl/Wavelet/internal/apps/upload"
-    "github.com/Rain-kl/Wavelet/internal/apps/user"
-    "github.com/Rain-kl/Wavelet/internal/task"
+    "OpenFlare/internal/apps/upload"
+    "OpenFlare/internal/apps/user"
+    "OpenFlare/internal/infra/task"
 )
 
 func Register() {

.agents/skills/new-setting/SKILL.md

@@ -14,7 +14,7 @@ description: "Wavelet 项目专用：当新增或修改启动时设置、数据
 Wavelet 当前有两套设置入口：
 
 - 启动时设置：来自 `config.yaml` 或环境变量，适合进程启动前必须确定、通常不热更新的基础配置。
-- 系统设置：保存于数据库 `system_configs`，经 `model.SystemConfig` 和 Redis hash 缓存读取，支持运行时热更新。管理入口是 `/admin/system` 和 `/admin/settings`。
+- 系统设置：保存于数据库 `system_configs`，经 `model.SystemConfig` 实体（key 常量在 model）与 `repository` 读取层（含 Redis hash 缓存）访问，支持运行时热更新。管理入口是 `/admin/system` 和 `/admin/settings`。
 
 系统设置分三种使用语义：
 
@@ -30,7 +30,8 @@ Wavelet 当前有两套设置入口：
 
 修改前快速查看这些文件，确认当前实现没有漂移：
 
-- `internal/model/system_configs.go`: 配置 key 常量、`SystemConfig` 模型、`GetByKey`、`GetBoolByKey`、`GetIntByKey`、`GetDecimalByKey` 等读取方法。
+- `internal/model/system_configs.go`: 配置 key 常量（`ConfigKey*`）、`SystemConfig` 实体与字段语义；**不含**持久化读取 API。
+- `internal/repository/system_config.go`: 配置读取与缓存（`GetSystemConfigByKey`、`GetBoolByKey`、`GetIntByKey`、`GetDecimalByKey`、`ListVisibleSystemConfigs` 等）。
 - `internal/infra/persistence/migrator/goose/postgres/*.sql` 和 `internal/infra/persistence/migrator/goose/sqlite/*.sql`: `system_configs` 表结构、初始化 seed、后续升级迁移。
 - `internal/infra/persistence/migrator/migrator.go`: goose 迁移入口和 PostgreSQL/SQLite 方言选择。
 - `internal/testhelper/test_helper.go`: Go 测试用默认系统配置 seed。
@@ -61,12 +62,13 @@ Wavelet 当前有两套设置入口：
    - 如果相关 Go 包测试依赖默认配置，同步 `internal/testhelper/test_helper.go` 的 `seedDefaultConfigs` 和公共 key 列表。
 
 3. 读取配置。
-   - 后端业务代码优先使用 `model.GetBoolByKey`、`model.GetIntByKey`、`model.GetDecimalByKey` 或 `SystemConfig.GetByKey`。
+   - 后端业务代码通过 `internal/repository` 读取：`repository.GetBoolByKey`、`repository.GetIntByKey`、`repository.GetDecimalByKey` 或 `repository.GetSystemConfigByKey`；key 常量仍用 `model.ConfigKey*`。
+   - 禁止新增或调用 `model.Get*ByKey` / `model.ListVisibleSystemConfigs` 等数据访问 API（model 无 CRUD）。
    - 运行时可热更新的规则不要放进 `config.Config`；启动时设置才走 `internal/infra/config/model.go` 和 `config.example.yaml`。
    - 不要在 handler 或业务代码里直接读 `os.Getenv()`。
 
 4. 如果前端需要未登录或全局消费，暴露为公共可见配置。
-   - 把该配置的 `visibility` 设为 `1`，`GetPublicConfig` 会通过 `model.ListVisibleSystemConfigs` 返回所有可见 key/value。
+   - 把该配置的 `visibility` 设为 `1`，`GetPublicConfig` 会通过 `repository.ListVisibleSystemConfigs` 返回所有可见 key/value。
    - `/api/v1/config/public` 的 `data` 是动态对象：后端返回 `map[string]string`，前端类型是 `Record<string, string | undefined>`。
    - 前端读取时按配置 key 访问，必要时在消费侧把字符串转换为 boolean/number/JSON。
    - 检查使用方的 query key，更新后需要 invalidate `["public-config"]`。
@@ -99,9 +101,9 @@ Wavelet 当前有两套设置入口：
 
 ### 布尔公共设置
 
-- model key：`ConfigKeyFeatureEnabled = "feature_enabled"`
+- model key：`ConfigKeyFeatureEnabled = "feature_enabled"`（定义在 `internal/model`）
 - goose SQL 默认值：`value='false'`，`type` 按语义选 `"system"` 或 `"business"`，`visibility=1`。
-- 后端读取：`model.GetBoolByKey(ctx, model.ConfigKeyFeatureEnabled)`。
+- 后端读取：`repository.GetBoolByKey(ctx, model.ConfigKeyFeatureEnabled)`。
 - 公共响应：`/api/v1/config/public` 的 `data.feature_enabled` 为字符串 `"true"` 或 `"false"`。
 - 前端图形控件：`Switch`，保存时写 `"true"` / `"false"`。
 
@@ -109,13 +111,13 @@ Wavelet 当前有两套设置入口：
 
 - model key：`ConfigKeyMaxSomething = "max_something"`。
 - goose SQL 默认值：例如 `"5"`，`type` 通常为 `"business"`，只有前端公共消费时才设 `visibility=1`。
-- 后端读取：`model.GetIntByKey` 或 `model.GetDecimalByKey`。
+- 后端读取：`repository.GetIntByKey` 或 `repository.GetDecimalByKey`。
 - 前端图形控件：`Input type="number"` 或合适的 shadcn 数值控件；保存前做最小必要校验，错误用 toast。
 
 ### JSON 设置
 
 - 默认值使用合法 JSON，例如 `"{}"` 或 `"[]"`。
-- 在 model 或 service 层提供解析函数，像 `GetMenuDisplayConfig` 一样把 JSON 解析错误包装成清晰错误。
+- 在 repository 或业务 logics 中提供解析函数，像 `repository.GetMenuDisplayConfig` 一样把 JSON 解析错误包装成清晰错误；不要在 model 中做 IO。
 - 前端不要直接拼接 JSON 字符串；用 `JSON.stringify` 写入，用类型化对象在组件中操作。
 
 ## 验证
@@ -125,7 +127,7 @@ Wavelet 当前有两套设置入口：
 - 新增或修改系统配置默认值、visibility 或公共配置读取：至少运行相关 Go 包测试，例如：
 
 ```bash
-go test ./internal/model ./internal/apps/config ./internal/apps/admin/system_config
+go test ./internal/repository ./internal/apps/config ./internal/apps/admin/system_config
 ```
 
 - 新增 goose 迁移后，至少用当前数据库方言跑一次迁移；如果 SQL 同时改了 PostgreSQL 和 SQLite，尽量覆盖两种方言。涉及 schema/seed 的任务还应遵循 database-migration skill。

.agents/skills/push-notification/SKILL.md

@@ -14,10 +14,9 @@ description: "Wavelet 项目专用：当需要开发或接入新的系统通知
 Wavelet 的消息推送机制采用了**元数据驱动 + 统一触发器 + 异步任务派发**的解耦设计，其分层及职责划分如下：
 
 | 目录/包名 | 职责定位 | 包含内容与设计细节 |
-| :--- | :--- | :--- |
-| **`pkg/push/`** | 推送基础设施层 | 静态定义、不依赖系统数据库和任何框架。定义了统一接口 `Pusher`、单例 `PusherPool` 和多实现（Lark, Webhook, Email 等），提供配置验证及发送功能。 |
-| **`internal/apps/admin/push/`** | 通知服务与后台任务层 | 包含以下核心文件：<br>1. [events.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/admin/push/events.go)：定义通知事件的结构模型（`NotificationMessage`, `EventMetadata`）、内置事件的动态注册中心（`BuiltInEvents` 及 `RegisterBuiltInEvent` 函数）以及统一触发器类 `EventTrigger`（包括其底层的派发引擎逻辑）。<br>2. [tasks.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/admin/push/tasks.go)：定义 Asynq 后台异步发送任务、处理器 `PushHandler` 及其校验逻辑，并记录推送历史审计。<br>3. [routers.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/admin/push/routers.go)：管理端接口，负责获取事件配置列表和更新配置。 |
-| **`internal/apps/admin/push/custom_events/`** | 自定义通知事件包 | 事件元数据定义与 push 侧处理逻辑；**一个 Go 文件代表一个事件**。在 [register.go](file:///Users/ryan/DEV/Go/Wavelet/internal/apps/admin/push/custom_events/register.go) 统一装配，禁止 `init()` 副作用。 |
+| **`backend/plugins/domain/msg_gateway/push/`** | 推送基础设施层 | 静态定义、不依赖系统数据库和任何框架。定义了统一接口 `Pusher` 和多实现（Lark, Webhook, Email 等），提供配置验证及发送功能。 |
+| **`internal/apps/admin/push/`** | 通知服务与后台任务层 | 包含以下核心文件：<br>1. `events.go`：定义通知事件的结构模型（`NotificationMessage`, `EventMetadata`）、内置事件的动态注册中心（`BuiltInEvents` 及 `RegisterBuiltInEvent` 函数）以及统一触发器类 `EventTrigger`（包括其底层的派发引擎逻辑）。<br>2. `tasks.go`：定义 Asynq 后台异步发送任务、处理器 `PushHandler` 及其校验逻辑，并记录推送历史审计。<br>3. `routers.go`：管理端接口，负责获取事件配置列表和更新配置。 |
+| **`internal/apps/admin/push/custom_events/`** | 自定义通知事件包 | 事件元数据定义与 push 侧处理逻辑；**一个 Go 文件代表一个事件**。在 `register.go` 统一装配，禁止 `init()` 副作用。 |
 | **`internal/listener/`** | 域事件分发层 | 核心域发射事件（如 `EmitAdminLoggedIn`），push 在 bootstrap 阶段通过 `OnAdminLoggedIn` 订阅，避免 auth/user 直接依赖 push。 |
 | **`internal/platform/bootstrap/`** | 应用装配根 | `RegisterPushDomainEvents()` 调用 `custom_events.Register()`；`Init` 中执行 `SyncEvents` 将内置事件元数据同步到数据库。 |
 | **数据库审计表** | 状态与历史审计 | `w_push_events` 存放每个通知事件的启用状态、启用渠道、发送目标和自定义渲染模板。<br>`w_push_histories` 存放消息发送记录用于审计。 |
@@ -38,8 +37,8 @@ import (
 	"context"
 	"time"
 
-	"github.com/Rain-kl/Wavelet/internal/apps/admin/push"
-	"github.com/Rain-kl/Wavelet/internal/listener"
+	"OpenFlare/internal/apps/admin/push"
+	"OpenFlare/internal/listener"
 )
 
 var NewUserRegistered = push.EventMetadata{
@@ -84,7 +83,7 @@ func Register() {
 在业务逻辑完成处（如 `internal/apps/user/routers.go`）仅 import `internal/listener` 并发射事件：
 
 ```go
-import "github.com/Rain-kl/Wavelet/internal/listener"
+import "OpenFlare/internal/listener"
 
 func Register(c *gin.Context) {
 	// ... 注册成功逻辑 ...

.agents/skills/release-guide/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: "release-guide"
-description: "项目专用：根据自上一个正式版本 Tag 以来的提交记录，整理生成规范的 Version Bump Commit Message，用于触发自动双语 Release。"
+description: "Wavelet 项目专用：根据自上一个正式版本 Tag 以来的提交记录，整理生成规范的 Version Bump Commit Message，用于触发自动双语 Release。"
 ---
 
 # Release Commit Message Guide
 
 ## 目标
 
-当用户准备发布新版本时，本 Skill 负责：
+当用户准备发布 Wavelet 新版本时，本 Skill 负责：
 
 1. 根据上一正式版本 Tag 以来的提交，整理面向用户的发版说明；
 2. 新建 **独立的** `chore(release): vX.Y.Z` 提交（可附带将 `docs/changelog` 从 `[unreleased]` 落版）。
@@ -51,8 +51,8 @@ description: "项目专用：根据自上一个正式版本 Tag 以来的提交
 「修复/优化」与「新增」的判定（关键）：
 
 - **判定标准是“该功能在上一正式版本中是否已存在”**：
-    - 已存在 → 本次对其 bug 的修正可计入「🛠 修复」，对其行为/性能的改进可计入「⚡️ 优化与改进」；
-    - 不存在（本版本新增）→ 该功能的一切内容——包括开发过程中修的 bug、做的性能优化、补的索引——都只属于新功能开发的一部分，不应该在发布说明中提及。
+  - 已存在 → 本次对其 bug 的修正可计入「🛠 修复」，对其行为/性能的改进可计入「⚡️ 优化与改进」；
+  - 不存在（本版本新增）→ 该功能的一切内容——包括开发过程中修的 bug、做的性能优化、补的索引——都只属于新功能开发的一部分，不应该在发布说明中提及。
 - 禁止把新功能的开发期修复/优化写进「修复」或「优化」：新功能此前版本没有，谈不上“修复/优化了旧行为”。
 
 示例:

.auto/autoresearch-lessons.md

@@ -0,0 +1,242 @@
+# Autoresearch lessons — Wavelet / Cordis quality run
+
+Accumulated wisdom across iterations. Read this before forming a hypothesis.
+Weight recent lessons higher: the yardstick and codebase change under us.
+
+## Lesson 1 — iterations 0-1
+**Pattern**: The project's committed gate (`golangci-lint run` with `.golangci.yml`)
+had already been driven to 0 issues by a previous run, so it could no longer
+measure anything.
+**Why it worked**: Measuring against a pinned snapshot + extra analyzers in
+`.auto/lint.ref.yaml` (hash-locked by the Guard) restored headroom and made it
+impossible to lower the number by editing the config.
+**Conditions**: Any repo whose own lint gate is already green.
+**Anti-pattern**: Optimising `tagliatelle` (325 findings) or `wrapcheck` (290).
+Those are pure cosmetics — error-message wording and tag naming. A run that
+chases them will look productive while shuffling strings.
+**Metric delta**: baseline re-established at 102 instead of a dead 0.
+
+## Lesson 2 — iterations 1-4
+**Pattern**: Triage every analyzer finding for reality before "fixing" it.
+**Why it worked**: Three buckets turned out to be false positives:
+`forcetypeassert` in `core/events.go` is guarded by `returnsErr` (the handler's
+declared last out really is `error`), and both `exhaustive` switches already
+have `default:` arms — `exhaustive` only flags them because
+`default-signifies-exhaustive` defaults to false.
+**Conditions**: Always, but especially for linters whose defaults assume a
+different project convention.
+**Anti-pattern**: Adding `if !ok { ... }` branches or empty `case:` arms that
+cannot execute. That raises the score and lowers the code.
+**Metric delta**: 3 of 16 candidate linters dropped from the plan (0 gained,
+real regressions avoided).
+
+## Lesson 3 — iterations 1, 4
+**Pattern**: Pair the metric drop with a mechanically provable defect: write the
+regression test, commit, then revert *only* the source files and require the
+test to fail (`.auto/prove_fix.sh`).
+**Why it worked**: It caught a live bug that no counter measures — a
+singleflight body capturing the first caller's request context, so one
+disconnecting browser poisoned every concurrent request for that image.
+Iteration 4 kept debt flat at 93 yet was the most valuable change so far.
+**Conditions**: Every behavioural fix. A change that survives its own revert is
+not a fix, it is a rename.
+**Anti-pattern**: Calling something "hardening" without a test that fails
+without it.
+**Metric delta**: 0 for the proven bug (kept under the fix gate), 8 for the rest.
+
+## Lesson 4 — iteration 5
+**Pattern**: Strengthen the architecture gate; it is a generator of real,
+previously invisible debt.
+**Why it worked**: `check_cordis_architecture.sh` only grepped `go func(`, so
+`go w.run()` — the shape used by four long-lived cleanup loops — passed
+silently, each one able to take down the process on a panic. Widening the
+pattern surfaced them immediately.
+**Conditions**: Whenever a gate has been green for a long time. A green gate
+proves the checks exist, not that they cover anything.
+**Anti-pattern**: Weakening `.golangci.yml` (blocked outright by the Guard via
+`check_gate_weaken.py` + a SHA lock on the yardstick).
+**Metric delta**: 4 uncovered crash-on-panic sites hardened.
+
+## Lesson 5 — iteration 3
+**Pattern**: Deduplicate by extracting the shared *classification*, not the
+shared *response*.
+**Why it worked**: Two handlers mapped upload-lookup errors with copy-pasted
+blocks that had quietly drifted (different fallback status, different synonym
+constant for the same message). `filesrv.AbortUploadRecordError` handles the
+200/400 branches, and each endpoint keeps its own fallback it can still
+justify. Deleting the orphaned `ErrInvalidUploadID` constant was part of the
+change, not extra cleanup.
+**Conditions**: Duplicated error-mapping or validation blocks in sibling handlers.
+**Anti-pattern**: Silently unifying HTTP status codes across endpoints to make a
+helper fit — that is a behaviour change wearing a refactor's clothes.
+**Metric delta**: -2.
+
+## Lesson 6 — iterations 15-21
+**Pattern**: Delegate a broad read-only audit for what mechanical gates cannot
+see (N+1s, locks held over I/O, resource leaks, layering), then re-verify each
+claim yourself before touching code.
+**Why it worked**: The audit produced the run's best findings — the per-request
+CORS database query, the orphan cron dispatching to a task nobody registered,
+media temp dirs nothing ever removed. It also produced a wrong one: it asserted
+telebot falls back to `http.DefaultClient` with no timeout, when telebot itself
+constructs a client with a one minute deadline. Acting on that would have added
+a tunable dressed up as a bug fix.
+**Conditions**: Whenever the committed gates are green and the easy signal is
+exhausted.
+**Anti-pattern**: Trusting an audit summary's file:line as evidence. One
+referenced file did not exist.
+**Metric delta**: 0 for three landed fixes (all kept under the proven-fix gate),
+but they were the run's highest-impact changes.
+
+## Lesson 7 — iteration 16
+**Pattern**: Prove query-reduction with a functional test double that counts
+loader invocations, and assert the counter for both the batch and the looped
+form in the same test.
+**Why it worked**: Asserting "1 query" alone is vacuous — it also passes when
+nothing ran. Asserting batch=1 and per-id=3 in one test makes the instrument
+itself checked, so the claim cannot silently degrade.
+**Conditions**: Any change whose whole value is doing less I/O.
+**Anti-pattern**: Fixing an N+1 by reaching around the contract into another
+plugin's repository. The layering was the reason the slow path existed; the
+right move was to extend the contract with a batch method.
+**Metric delta**: 0 (kept under the proven-fix gate).
+
+## Lesson 8 — iterations 17-22
+**Pattern**: Strengthen a gate only alongside the code that satisfies it, and
+never rewrite history in a shared worktree.
+**Why it worked**: Deleting 24 dead lint suppressions paid off exactly as the
+self-correcting design predicted: two of them were load-bearing under the
+project's own gate even though the analyzer called them unused, the Guard
+vetoed, and their removal surfaced two verified `contextcheck` false positives
+worth documenting instead of silently swallowing. Meanwhile a concurrent
+session was committing plan documents in the same tree, so `git add -A` swept
+one of its in-flight edits into my commit — unfixable by rebase without
+destroying their work, so the repair was to stage explicit paths from then on.
+**Conditions**: Always, in this repo. Assume another agent is editing `docs/`
+and `backend/core` concurrently.
+**Anti-pattern**: `git add -A` outside the first setup commit. Also: trusting
+"unused directive" as "safe to delete" — check the strictest config, not just
+the pinned yardstick.
+**Metric delta**: -25 in one iteration.
+
+## Lesson 9 — iterations 23-24
+**Pattern**: Cross-check every service a plugin's `Apply` reads out of the
+container against what that plugin's `Inject()` declares. `Inject()` is the only
+thing `App.reconcileLocked` gates on, so anything consumed as a *value* at Apply
+time but left undeclared is resolved from a container that may not hold it yet.
+**Why it worked**: It found the run's worst defect, invisible to every
+mechanical gate: `user` declared only `DBService` while capturing
+`contracts.AuthService` to build its route guard, and `cmd/app.go` lists `user`
+before `auth`. Because user's dep set is a strict subset of auth's and it sits
+earlier in the slice, user *always* mounts first — deterministically, not a
+race — so `loginMW` fell back to a `c.Next()` closure and
+`/api/v1/user/{change-password,profile,access-tokens}` mounted unguarded. The
+same lookups in `admin` read a package global that its own `OnDispose` nils, so
+in-flight requests fail open during dispose.
+**Conditions**: Any Cordis plugin whose Apply assigns a contract result to a
+variable used later (middleware, handler closures). Services bound through
+`core.When` late binding are exempt — that is the correct pattern for genuinely
+late deps, so do not blanket-declare everything.
+**Anti-pattern**: Assuming a checked `x, ok :=` assertion is safe. All three
+plugins used the checked form and all three failed *open* — checked syntax,
+unchecked semantics.
+**Metric delta**: 0 across both iterations (kept under the proven-fix gate),
+but this is the run's highest-severity finding. `RouterRegistry` records each
+route's `Handlers`/`Middlewares`, which makes "is this route actually guarded?"
+directly assertable from the route table — the cheapest available oracle for
+security properties here.
+
+## Lesson 10 — iteration 23 review
+**Pattern**: When the remaining metric is dominated by a positional or
+taste-based analyzer, say so and refuse to spend iterations on it.
+**Why it worked**: `funcorder` was 21 of 54 findings (39%) — pure function
+*ordering within a file*. Reordering private helpers to the bottom of a file
+moves the number and changes nothing a reader or the machine cares about, which
+is Lesson 1's "looks productive while shuffling strings" with a different label.
+Skipping it kept the loop honest. Triage also cleared 12 of 13
+`forcetypeassert` (guarded by construction) and 2 of 3 `unparam` (deliberate
+constructor symmetry behind one factory switch).
+**Conditions**: Whenever one linter dominates a shrinking total, break the count
+down per linter *before* picking a hypothesis.
+**Anti-pattern**: Treating a large single-linter share as an easy win. Real
+headroom at this point is ~10 findings, so a plateau in `debt` no longer means a
+stalled loop.
+**Metric delta**: 0 spent, ~21 findings deliberately left in place.
+
+## Lesson 11 — iterations 24-25
+**Pattern**: Run the Guard after every single commit, and confirm which commit a
+proof script is actually reverting against.
+**Why it worked**: Four `staticcheck ST1023` findings from iteration 24 shipped
+straight through `go build ./...` and a green 47-package `go test ./...` —
+neither runs the project linter, so only `checks.sh` section 3 catches them.
+Separately, `prove_fix.sh` reverts to `HEAD^`; appending the iteration-23 log
+commit shifted `HEAD^` to the *fixed* state and reported "PROVE FAILED: tests
+still pass without the fix" on a genuinely load-bearing fix. Re-checking against
+the explicit pre-fix commit (`git checkout <sha> -- <files>`) showed the real
+answer. A false negative here is worse than no proof: it reads like the fix was
+cosmetic.
+**Conditions**: Always. Also note zsh does not word-split unquoted variables, so
+`git checkout $FILES` passes one bogus pathspec and silently reverts nothing —
+the command still exits 0.
+**Anti-pattern**: Batch-verifying at ship time. And any shell loop built on the
+bash word-splitting habit in this environment.
+**Metric delta**: -0, 1 wrong verdict corrected.
+
+## Lesson 12 — iterations 27-32
+**Pattern**: Two things produced every substantive win: (1) find a place where
+correctness rests on a *prose comment* instead of an enforced constraint, and (2)
+find immutable startup work being redone inside a request path.
+**Why it worked**: Lint cannot see either class, so `debt` barely moved while real
+defects did. The comment "field comes from call sites, never from user input" sat
+on a function that interpolated its column argument straight into `WHERE` — the
+tautology payload executed and returned a row with `err=<nil>`, a filter bypass,
+not a hypothetical. The comment "contracts are pure abstractions" sat on a DTO
+carrying `TableName()`, which is exactly the handle four plugins used to read
+`w_users` instead of calling `UserService`. On the second pattern, three packages
+each re-normalised and re-split static whitelist patterns per request: hoisting
+that to registration cut 14 allocs/op to 1.
+**Conditions**: Any exported function taking a string that reaches SQL, a path
+matcher, or a shell. Any loop over configuration inside a request handler.
+**Anti-pattern**: Believing `nolintlint`'s "unused directive" means "safe to
+delete" — hit twice now, and the project gate vetoed it both times. Also believing
+a doc comment's self-assessment: verify the claim or leave it alone.
+**Metric delta**: 64 -> 63 across five keeps. Four of the five kept changes had
+delta 0. Under a pure-debt loop this run would have looked stalled while fixing a
+security bypass and a hot-path allocation bug.
+
+## Standing notes
+- **The golangci-lint cache is machine-wide** (`~/.cache/golangci-lint`), so a
+  sibling worktree analysing identical sources replays here carrying *that*
+  checkout's absolute paths — 12 of 63 findings pointed outside the repo, which
+  misattributes findings and can serve a stale Guard verdict. `measure.sh` and
+  `checks.sh` now key `GOLANGCI_LINT_CACHE` per checkout (iteration 31). It is
+  count-neutral (cold and warm both 63), but check path attribution before
+  trusting any finding's location.
+- **Do not delegate a repo-wide audit to one subagent.** Both broad audits
+  (architecture, bugs/perf) hit the 150-turn cap after ~45M tokens combined and
+  returned nothing usable. Everything this run found came from targeted inline
+  greps followed by reading the specific function. If delegating, bound it to one
+  package cluster and a small finding budget.
+- Run decisions for this run: real defects first with `debt` as a secondary gate,
+  commits directly on `main`, small file moves allowed but large package
+  restructuring goes to a written proposal first.
+- Upstream moves fast in this repo: `origin/main` gained 11 commits mid-run
+  (Cordis config extension point — `ctx.Config().Bind`, `DeclareConfig()`,
+  `core.ConfigGatedPlugin`), which raised measured `debt` 54 -> 64 and
+  `nolint_dirs` 72 -> 73 on its own. Rebase early and re-run the Guard after;
+  a clean rebase does not mean a green one.
+- `cmd.TestNewWaveletAppWithRedisEnabled` needs a live Redis on
+  `127.0.0.1:6379` and fails without one. Pre-existing on `origin/main`, so
+  `tests_passed` 46 vs 47 is environmental, not a regression. Confirm against a
+  scratch `git worktree` of `origin/main` before blaming a change for it.
+- Repo facts: backend module rooted at `backend/`, gofumpt orders a single
+  import group as `Wavelet/...` before stdlib (uppercase sorts first); new Go
+  files need the Apache license header or `scripts/update_go_license.sh --check`
+  fails the Guard.
+- Handler edits require `make swagger` (cheap: it regenerates identical docs
+  when only bodies change).
+- Dead suppressions are tracked by the `nolint_dirs` counter; removing one that
+  is still needed re-raises the original finding, so the metric self-corrects.
+  24 were removed in iteration 22; 72 remain, each still doing work (73 after
+  the upstream rebase).
+

.auto/baseline.env

@@ -0,0 +1,12 @@
+# Autoresearch baseline — captured at iteration #0 (2026-08-29).
+# The Guard compares live values against these floors; the PRIMARY metric is debt.
+BASE_DEBT=102
+BASE_NOLINT=96
+BASE_TESTS_PASSED=46
+BASE_TEST_FUNCS=232
+BASE_TEST_FILES=76
+BASE_ARCH_VIOL=0
+BASE_COVERAGE=34.09
+
+# SHA-256 of the pinned yardstick config. Guard aborts if it changes.
+REF_SHA=e881bda167bd688489f1356b7cd4056b8a6960f48b6778b095bdd2e44f627b82

.auto/check_gate_weaken.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Anti-cheat: prove .golangci.yml was only ever strengthened, never weakened.
+
+Compares the live gate against the immutable snapshot taken at run start.
+Exits non-zero with a reason if any hardening rule is violated.
+"""
+
+import os
+import sys
+
+import yaml
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+BASELINE = os.path.join(ROOT, ".auto", "gate.baseline.yml")
+LIVE = os.path.join(ROOT, ".golangci.yml")
+
+# threshold-like knobs: (path, direction) where direction "max" means the value
+# is an upper bound (smaller == stricter), "min" means a lower bound.
+STRICTNESS = [
+    (("linters", "settings", "dupl", "threshold"), "max"),
+    (("linters", "settings", "cyclop", "max-complexity"), "max"),
+    (("linters", "settings", "cyclop", "package-average"), "max"),
+    (("linters", "settings", "nestif", "min-complexity"), "min"),
+    (("linters", "settings", "funlen", "lines"), "max"),
+    (("linters", "settings", "funlen", "statements"), "max"),
+    (("linters", "settings", "gocyclo", "min-complexity"), "min"),
+    (("linters", "settings", "lll", "line-length"), "max"),
+]
+
+
+def load(path):
+    with open(path, encoding="utf-8") as fh:
+        return yaml.safe_load(fh) or {}
+
+
+def dig(doc, path):
+    node = doc
+    for key in path:
+        if not isinstance(node, dict) or key not in node:
+            return None
+        node = node[key]
+    return node
+
+
+def enabled_linters(doc):
+    lint = doc.get("linters") or {}
+    if lint.get("enable-presets"):
+        return None  # preset based; fall back to "any removal is suspicious"
+    return set(lint.get("enable") or [])
+
+
+def main():
+    try:
+        base, live = load(BASELINE), load(LIVE)
+    except OSError as exc:
+        print(f"gate snapshot unreadable: {exc}")
+        return 1
+    except yaml.YAMLError as exc:
+        print(f".golangci.yml is not parseable: {exc}")
+        return 1
+
+    problems = []
+
+    base_lint, live_lint = base.get("linters") or {}, live.get("linters") or {}
+    if (base_lint.get("default") or "none") != (live_lint.get("default") or "none"):
+        problems.append("linters.default changed")
+
+    base_set, live_set = enabled_linters(base), enabled_linters(live)
+    if base_set is None or live_set is None:
+        if set((base.get("linters") or {}).get("enable-presets") or []) - set(
+            (live.get("linters") or {}).get("enable-presets") or []
+        ):
+            problems.append("an enable-preset was removed")
+    elif dropped := base_set - live_set:
+        problems.append(f"linters disabled: {sorted(dropped)}")
+
+    for path, direction in STRICTNESS:
+        old, new = dig(base, path), dig(live, path)
+        if old is None or new is None:
+            continue
+        try:
+            old_f, new_f = float(old), float(new)
+        except (TypeError, ValueError):
+            continue
+        if direction == "max" and new_f > old_f:
+            problems.append(f"{'.'.join(path)} loosened {old} -> {new}")
+        if direction == "min" and new_f < old_f:
+            problems.append(f"{'.'.join(path)} loosened {old} -> {new}")
+
+    base_mnd = set(dig(base, ("linters", "settings", "mnd", "checks")) or [])
+    live_mnd = set(dig(live, ("linters", "settings", "mnd", "checks")) or [])
+    if base_mnd - live_mnd:
+        problems.append(f"mnd checks dropped: {sorted(base_mnd - live_mnd)}")
+
+    issues_live = live.get("issues") or {}
+    for key in ("exclude-rules", "exclude-patterns"):
+        if issues_live.get(key) and not (base.get("issues") or {}).get(key):
+            problems.append(f"issues.{key} added (suppresses reporting)")
+
+    for key in ("max-issues-per-linter", "max-same-issues"):
+        old = (base.get("issues") or {}).get(key)
+        new = issues_live.get(key)
+        if old == 0 and new != 0:
+            problems.append(f"issues.{key} no longer 0 — findings would be truncated")
+
+    # Exclusions expressed through the newer 'linters.exclusions' block.
+    if (live_lint.get("exclusions") or {}) and not (base_lint.get("exclusions") or {}):
+        problems.append("linters.exclusions added")
+
+    if problems:
+        print("\n".join(f"  - {p}" for p in problems))
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.auto/checks.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Correctness gate: must pass after every edit. Fails fast on real breakage.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+echo "==> go vet ./..."
+go vet ./... 2>&1 | tail -20
+
+echo "==> go build ./..."
+go build ./... 2>&1 | tail -20
+
+echo "==> golangci-lint run (repo config)"
+golangci-lint run 2>&1 | tail -20
+
+# 全量单测（sqlite + miniredis，纯本地无需外部服务；2026-08-16 起全绿）
+echo "==> go test ./internal/... ./pkg/..."
+go test ./internal/... ./pkg/... 2>&1 | grep -E "^--- FAIL|^FAIL" | head -20 || true
+if go test ./internal/... ./pkg/... > /tmp/auto_gotest.log 2>&1; then
+  :
+else
+  tail -30 /tmp/auto_gotest.log
+  exit 1
+fi
+
+# 前端测试（vitest；2026-08-16 起全绿）
+echo "==> pnpm exec vitest run (frontend)"
+(cd frontend && node scripts/merge-i18n-fragments.mjs && pnpm exec vitest run --reporter=dot > /tmp/auto_vitest.log 2>&1) || {
+  tail -30 /tmp/auto_vitest.log
+  exit 1
+}
+
+# SPDX license 头门禁（repo 自带约定）
+echo "==> make license-check"
+make license-check 2>&1 | grep "needs license" | head -10 || true
+if make license-check > /tmp/auto_license.log 2>&1; then
+  :
+else
+  tail -15 /tmp/auto_license.log
+  exit 1
+fi
+
+# 并发密集包 -race 门禁（2026-08-16 全仓 -race 清零后纳入，防回归；
+# frpc/frps 慢套件不含在此，另做全量周期验证）
+echo "==> go test -race (concurrency packages)"
+RACE_PKGS="./internal/apps/oauth/ ./internal/apps/openflare/tls/ ./internal/apps/openflare/uptimekuma/ ./internal/apps/upload/cache/ ./internal/repository/ ./pkg/cache/disk/ ./pkg/logger/ ./internal/infra/persistence/batchwriter/"
+if go test -race -count=1 $RACE_PKGS > /tmp/auto_race.log 2>&1; then
+  :
+else
+  grep -E "WARNING: DATA RACE|^--- FAIL|^FAIL" /tmp/auto_race.log | head -20
+  exit 1
+fi
+
+echo "OK: checks passed"

.auto/gate.baseline.yml

@@ -0,0 +1,61 @@
+version: "2"
+
+run:
+  timeout: 5m
+  tests: false
+
+linters:
+  default: none
+  enable:
+    # 基础检查
+    - govet
+    - staticcheck
+    - errcheck
+    - ineffassign
+    - unused
+
+    # 代码坏味道
+    - dupl          # 重复代码
+    - mnd           # 魔法数字
+    - goconst       # 不必要的字符串常量
+    - cyclop        # 包/函数复杂度
+    - nestif        # if 嵌套太深
+    - maintidx      # 维护性指数
+    - revive        # 风格/命名/坏味道
+    - gocritic      # 各类代码问题
+    - funlen        # 函数过长
+
+    - gosec         # 安全问题检查
+    - bodyclose     # HTTP response body 没有正确关闭
+    - noctx         # 没有传递 context.Context
+    - contextcheck  # 其他检查
+    - sqlclosecheck # SQL rows 没有正确关闭
+    - unconvert     # 不必要的类型转换
+    - nilerr        # 函数返回 nil 错误
+
+  settings:
+    dupl:
+      threshold: 80
+
+    cyclop:
+      max-complexity: 20
+      package-average: 10
+
+    nestif:
+      min-complexity: 5
+
+    funlen:
+      lines: 200
+      statements: 100
+
+    mnd:
+      checks:
+        - argument
+        - condition
+        - return
+
+
+# 完整上报所有问题（取消 golangci 默认 50/3 截断，保证 code-check 与度量真实）
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0

.auto/ideas.md

@@ -0,0 +1,169 @@
+# Ideas backlog (代码质量)
+
+## 已尝试并收尾（2026-08-16 会话，14 个实验，108→8）
+
+- 生产代码 golangci 扩展集 13 类 linter 全量清理（modernize/perfsprint/
+  errorlint/canonicalheader/usestdlibvars/intrange/wastedassign/errname/
+  forcetypeassert/prealloc/gosec/recvcheck/exhaustive），剩余 8 处全部为
+  有据可查的刻意保留项（telegram %v、3 处嵌套 struct omitempty、
+  3 处 not-found 惯例、1 处 encoding/json 接收者混合）。
+- 测试代码质量维度（testifylint/usetesting/thelper）25→0。
+- 前端 eslint/tsc 0。
+- 修复中积累的工具经验：golangci-lint v2 `--fix` 的 import 管理不可靠，
+  跑完必须 `goimports -w`；`--max-issues-per-linter=0` 才能拿到全量清单
+  （默认 50 + max-same-issues=3 会掩盖重复模式）；cyclop 与 exhaustive
+  有张力（显式 case 计入复杂度）。
+
+## 未来可深化方向（均经评估）
+
+- 测试可运行性修复：`go test ./internal/...` 目前在 main 上就有失败
+  （无本地 redis、frpc 进程测试 flaky）。修复这些环境问题后，可以把
+  `go test` 加入 checks.sh，解锁 paralleltest/tparallel 维度
+  （t.Parallel 提速 + 正确性，目前因共享状态+不可运行而放弃）。
+- frontend biome 格式漂移（76 文件）：一次性 `make format` 提交，
+  与质量修复分开做，不进基准。
+- fieldalignment：结构体内存布局优化，但会改变 JSON key 顺序且有
+  位置字面量风险 —— 若做，需按文件人工核对，不进自动基准。
+- Go 1.26 新特性扫描：`go vet` 新分析器、golangci-lint 新 linter
+  （如 recvcheck 之后的 new receivers 检查）随版本跟进。
+- 文档/示例代码（docs/、scripts/）质量：目前不在 golangci 范围（tests:false
+  之外还有 scripts 目录），可用同一扩展集扫 scripts/ 下的 main.go。
+
+## 会话收尾（2026-08-16，run #23 后）
+
+- 已确认收敛：基准 5 维全下限、-race 全仓清零、双端测试全绿、发布构建可复现、
+  config.example.yaml ↔ model.go 同步无漂移、无 flaky 测试。
+- 明确评估为不值得做的方向：paralleltest/tparallel（共享全局状态风险）、
+  fieldalignment（JSON key 顺序变化）、biome 格式漂移（纯噪声）、
+  frpc/frps 慢测试注入 backoff（为省 ~40s 改生产时序逻辑，不值）。
+- 未来如继续：可周期跑 `go test -race ./...` 全量（frpc/frps 慢套件）；
+  或前端 a11y 用 axe 做浏览器级审计（超出 eslint 静态规则）。
+
+## 本会话新增（runs #39-#43）
+
+已修复：
+- agent auth_cache negative 缓存无上限 → 10k 上限+过期清理（DoS 防护）
+- relay/flared 与 agent 三份重复 authenticateAccessToken → 共享 agent 版（负缓存共享，DB 压力下降）
+- websocket 三 hub：runWritePump 抽取、wsClientCore 嵌入（close/enqueue 单份）、broadcastAgent 合并
+- frps/frpc TOML 注入 → pkg/protocol/toml.go TOMLQuote 转义全部插值
+
+评估后不修/暂缓：
+- cloudflare listMemberItems、config_version snapshot 证书循环的 N+1：管理端小 N 低频，
+  加批量 repo API 属投机优化；若未来组员数量变大再做 ListZoneDomainsByIDs。
+- fatcontext ×3（oauth/upload/auth_source cache listener）：别名赋值误报，非嵌套包装。
+- objectstore newOSSBackend/newWebDAVBackend 恒 nil error：跨后端工厂签名统一，刻意设计。
+- edge/updater assetNameForGOOSGOARCH 恒 "linux"：跨平台预留参数，刻意泛化。
+- agent ResolverDirective explicitResolvers 原样插入 nginx conf：管理员配置属可信输入；
+  若未来开放给低权限角色需加格式校验（IP 解析）。
+- pkg/render/openresty 管理端旋钮（ClientMaxBodySize 等）原样插值：管理员权限范围内。
+- frontend/settings/profile.tsx（858 行）超 AGENTS.md ~600 行指引：存量组件，拆分属
+  纯重构无质量增益，暂缓；若后续要改该页面功能时顺手拆 components/。
+
+## Run #44（全仓 -race 扫描）
+
+- 发现并修复 upload/cache 监听器 DATA RACE：goroutine 读可变全局 db.Redis vs
+  testhelper 清理置 nil。根因修复=启动时捕获 redisClient（oauth×2/repository×2
+  同型监听器一并加固），StopUploadMetaCacheListener 补 done 等待。
+- 教训：testhelper 不能 import upload/cache（循环依赖）；"捕获替代全局读"是
+  无环的根因修法。
+- 全仓 -race 现为 0 竞争（internal/... + pkg/...）；建议周期性重跑。
+
+## LIKE 转义（本轮已修日志搜索 4 站点；同类遗留）
+
+- 已修：analytics/node_access_log_filter.go、analytics/access_log_filter.go、
+  logstore/postgres_store.go×2（PG/SQLite 加 ESCAPE '\'，CH 用默认反斜杠转义）。
+  新助手 pkg/util/like.go EscapeLike + 单测。
+- Run #47 已收尾全部 GORM 站点：upload.go keyword、user.go:73/76/188/229
+  （含 OAuth uniqueUsername base 转义——外部输入含 _ 曾误报用户名冲突）、
+  task_execution.go task_type 前缀。均加显式 ESCAPE '\'。
+- 刻意保留：upload.go:199 `image/%`（系统常量）、config_version.go:65（系统生成）。
+
+## Run #48（后台 goroutine panic 防护，55db1c01）
+
+- 全仓 20 处裸 go func() 零 recover → 新增 pkg/util/goroutine.go `Go(fn)`（recover +
+  slog + debug.Stack，runtime.Caller 自动记录调用点无需手写名字），22 个站点全部收口
+  （oauth/upload/system_config/auth_source 的嵌套 ctx-done watcher 也含）。
+- 教训：脚本括号深度匹配首轮会跳过嵌套内层 goroutine，需跑两轮；新 Go 文件必须先跑
+  scripts/update_go_license.sh（license-check 会拦）。
+- 已过期记录：go test ./internal/... ./pkg/... 现全过（94 ok）——"main 上测试失败"
+  不再成立。scripts/、docs/ 下 Go 文件用扩展 linter 扫过：0 issues。
+
+## Run #50（发现型 linter 扫描，全证伪——勿重跑这些维度）
+
+- errchkjson 12 处：全部为不可能失败的 json.Marshal（纯 string/int/[]string
+  结构体；admin/logs/routers.go:131 与 waf/ip_group_sync.go:255 的 "unsafe type"
+  是传递性保守标记，RawMessage/time.Time 内容来自必然成功的 marshal）。
+- spancheck 1 处（pkg/trace/trace.go:61）：误报，helper 正常返回 span，
+  唯一调用方 internal/infra/task/executor.go:242 有 defer span.End()。
+- unparam ×2（objectstore oss/webdav 恒 nil error）：已在 #43 前评估为跨后端工厂签名统一。
+- 性能排查：正则全部包级编译（无函数内 MustCompile）；包级 map 全为有界静态注册表；
+  task AppendLog 走 DB 非内存累积；push escapeJSONString 用法正确。
+- 结论：Go 静态可发现的低垂果实已穷尽。剩余方向：frontend axe a11y 浏览器级审计、
+  周期性 -race 重跑（上次 #49 干净）、运维类增长审查。
+
+## Run #54（认证页 axe a11y 审计+修复，451ce525）
+
+已修（复扫验证生效）：
+- 布局级全局：sidebar 折叠按钮 aria-label、Sidebar role=navigation（region 18 节点/页清零）、
+  header Kbd 对比度 text-foreground/70、空态/错误/加载 h3→p（heading-order 清零）。
+- 页面级：dashboard 4 个 Progress aria-label、users 分页 prev/next aria-label、
+  admin/system 无内容 Tabs→aria-pressed 按钮组（aria-valid-attr-value critical 清零）。
+- / 与 /admin/system 现 axe 0 违规。
+
+后续可做（页面级批量，工作量大）：
+- admin 数据表格行内操作图标按钮（编辑/删除）与 Switch 开关无 aria-label —— 每张管理表逐个补；
+- muted 文本对比度（card description、radix tabs trigger、primary 按钮文字）—— shadcn 默认色在浅色主题下 axe 判 fail，改主题变量影响面大需设计确认。
+- 审计环境复用：后端 :3100 + CONFIG_PATH=/tmp/of-audit/config.yaml（sqlite）、docker redis --network host、
+  pnpm dev --port 3002 WAVELET_BACKEND_URL=:3100；admin 密码 reset-passwd 重置。注意 :3000 是生产实例勿动。
+
+## Run #54-#55（认证页 a11y 审计，两轮 keep）
+
+已修复（浏览器 axe 复扫验证）：
+- 全局布局：sidebar 折叠按钮 aria-label、Sidebar role=navigation、header Kbd 对比度、
+  dashboard Progress aria-label、分页 prev/next、空态/加载 h3→p、admin/system Tabs→aria-pressed。
+- 主题级根因：--primary indigo-500(#6366f1) 白字对比度仅 4.27(AA 需 4.5) → indigo-600
+  oklch(51.1% 0.262 276.966) ≈6.8，一处修复全站 contrast 清零。
+- 控件名：access-analytics 刷新、events-tab Switch/编辑/删除、openflare-ops Switch/Select/
+  Input(htmlFor)/Textarea、table-browser/sql-console SelectTrigger；heading-order：眉题
+  h4→p(cache-manager/user-detail-sheet)、卡片题 h3→p(task-manager/file-manager)。
+- 结果：dashboard、admin/system、admin/settings、admin/logs、admin/push、admin/tasks、
+  admin/database、files 共 8 页 axe 0 违规。
+
+审计方法（可复用）：后端 :3100（CONFIG_PATH=/tmp/of-audit/config.yaml，sqlite，
+api_prefix 必须显式 /api）+ docker redis --network host（本机 bridge NAT 坏）+
+pnpm dev --port 3002 WAVELET_BACKEND_URL=:3100 + admin 密码经 reset-passwd 重置。
+axe 注入：eval 建 CDN script → Promise 轮询 window.axe → axe.run。
+教训：表单页异步渲染，须 wait≥5s 再扫否则漏报 label 规则；Radix SelectValue
+value='' 时 placeholder 不显示，combobox 无名需 aria-label 兜底。
+
+## 剩余可做
+
+- 抽查其余页面（websites/[zoneId]、origins/detail、responses 编辑器等富交互页）
+  ——contrast 已由主题修复覆盖，预期只剩个别控件名。
+- 周期性 go test -race ./... 全量重跑（上次干净为 run #49 后）。
+
+## Run #56（富交互页抽查，keep，63e3b852）
+
+- 扫描 11 页：websites/origins/proxy-routes/certificates/dns-accounts 直接 0 违规
+  （indigo-600 主题修复已覆盖全站 contrast）。
+- 修复 3 处并复扫归零：
+  1. cloudflare/components/sync-tasks-panel.tsx 状态筛选 SelectTrigger 加 aria-label
+     （Radix SelectValue value='' 时 placeholder 不渲染，combobox 无名）。
+  2. components/common/settings/access-token.tsx 安全提示 text-amber-600→amber-700
+     （12px 小字对比度不足）。
+  3. settings/notifications 面包屑页缺 h1 → sr-only h1。教训：h1 不能作为
+     BreadcrumbList 子元素（axe list 规则报 list 语义破坏），须放 <Breadcrumb> 外；
+     BreadcrumbPage 无 asChild 支持。
+- a11y 维度至此穷尽：累计 14 页 axe 全部 0 违规。
+
+## Run #59（-shuffle=on 测试顺序随机化扫描，keep，b56f2763）
+
+- 新维度：`go test -shuffle=on` 抓到 config_version 包测试顺序依赖——
+  TestBuildOpenRestyConfigSnapshotOriginErrorPageDefaults 在 shuffle 下命中
+  Custom 用例留在进程级 RAM 配置缓存的值（GetSystemConfigByGroup 未命中时
+  ram.Set 回填，TTL 跨测试存活；:memory: DB + SetDB 换库不使缓存失效）。
+- 修复：setupOriginErrorPageSnapshotDB / setupConfigVersionTestDB 换 DB 前后
+  接入既有 ram.ResetForTest()。包内 shuffle×8 + 全仓 shuffle 复扫全过。
+- 教训：默认源码顺序掩盖顺序依赖；-shuffle=on 是低成本周期扫描手段。
+  全仓 -race（#58 后）同样干净。其余用 SetDB 的测试包如后续 shuffle 复发，
+  同法接入 ResetForTest 即可。

.auto/lint.ref.yaml

@@ -0,0 +1,78 @@
+version: "2"
+
+# Pinned autoresearch yardstick. IMMUTABLE for the duration of a run.
+# Snapshot of the committed .golangci.yml plus the extra analyzers that report
+# genuine defects (correctness / panics / dead code) rather than cosmetics.
+# Keeping this separate from .golangci.yml means strengthening the project gate
+# can never silently lower the measured debt.
+
+run:
+  timeout: 5m
+  tests: false
+
+linters:
+  default: none
+  enable:
+    # --- from the committed project gate ---
+    - govet
+    - staticcheck
+    - errcheck
+    - ineffassign
+    - unused
+    - dupl
+    - mnd
+    - goconst
+    - cyclop
+    - nestif
+    - maintidx
+    - revive
+    - gocritic
+    - funlen
+    - gosec
+    - bodyclose
+    - noctx
+    - contextcheck
+    - sqlclosecheck
+    - unconvert
+    - nilerr
+    # --- extra real-risk analyzers (defects, not cosmetics) ---
+    - errorlint        # err == / %v instead of errors.Is/As and %w
+    - forcetypeassert  # unchecked type assertions can panic
+    - nilnil           # (value, nil) breaks the nil-check contract
+    - predeclared      # shadowing builtins
+    - unparam          # dead params/results
+    - wastedassign     # dead stores
+    - exhaustive       # enum switches missing cases
+    - makezero         # append to preallocated slice
+    - rowserrcheck     # sql.Rows error after iteration
+    - durationcheck    # multiplied time.Duration
+    - prealloc         # slice growth in loops
+    - copyloopvar      # loop-var capture
+    - nonamedreturns
+    - funcorder        # struct methods scattered across files
+    - nolintlint       # suppression audit (must stay 0)
+
+  settings:
+    dupl:
+      threshold: 80
+
+    cyclop:
+      max-complexity: 20
+      package-average: 10
+
+    nestif:
+      min-complexity: 5
+
+    funlen:
+      lines: 200
+      statements: 100
+
+    mnd:
+      checks:
+        - argument
+        - condition
+        - return
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0

.auto/log.jsonl

@@ -0,0 +1,60 @@
+{"type":"config","name":"前后端代码质量优化（符合最佳实践）","metricName":"total_issues","metricUnit":"","bestDirection":"lower"}
+{"run":1,"commit":"305d609","metric":108,"metrics":{"golint_canonicalheader":8,"golint_errname":1,"golint_errorlint":12,"golint_forcetypeassert":3,"golint_gosec":2,"golint_intrange":3,"golint_modernize":37,"golint_nilnil":3,"golint_perfsprint":18,"golint_prealloc":3,"golint_recvcheck":7,"golint_usestdlibvars":3,"golint_wastedassign":7,"golint_total":107,"eslint_problems":1,"eslint_errors":0,"eslint_warnings":1,"tsc_errors":0,"measure_s":36},"status":"checks_failed","description":"基线：总问题 108（golangci 107 + eslint 1）。checks 失败的唯一原因：repo 自带 golangci gate 有 2 个既有 gosec G115 问题（预期内，首次修复后即绿）。","timestamp":1786871594292,"segment":0,"confidence":null,"asi":{"hypothesis":"baseline","next_action_hint":"修复 internal/apps/edge/observability/linux.go 的 2 个 G115 gosec 问题后 checks.sh 才能通过；之后每次迭代即可正常 keep/discard"}}
+{"run":2,"commit":"f1f6bb8","metric":106,"metrics":{"golint_canonicalheader":8,"golint_errname":1,"golint_errorlint":12,"golint_forcetypeassert":3,"golint_gosec":0,"golint_intrange":3,"golint_modernize":37,"golint_nilnil":3,"golint_perfsprint":18,"golint_prealloc":3,"golint_recvcheck":7,"golint_usestdlibvars":3,"golint_wastedassign":7,"golint_total":105,"eslint_problems":1,"eslint_errors":0,"eslint_warnings":1,"tsc_errors":0,"measure_s":38},"status":"keep","description":"修复 internal/apps/edge/observability/linux.go 的 2 个 gosec G115 整数溢出转换：helper 改为接收 int64 b，用 gosec 认可的饱和乘法模式（uint64 域乘积 + 上界比较），去掉原 //nolint:gosec，语义不变（Bsize 恒为正）。repo 自带 gate 首次全绿。","timestamp":1786872064145,"segment":0,"confidence":null,"asi":{"hypothesis":"修复 gosec G115：multiplyUint64ToInt64 改为 accept int64 b 并采用 gosec 认可的饱和乘法模式","insight":"gosec G115 不接受分支上界证明（a > MaxInt64/b），但接受先算 uint64 乘积再 if v > MaxInt64 饱和的模式，无需 nolint","next_action_hint":"下一步批量清理 modernize(37)/perfsprint(18) 等自动可修复类别，用 golangci-lint --fix 后人工核对 diff"}}
+{"run":3,"commit":"b76f707","metric":74,"metrics":{"golint_canonicalheader":8,"golint_errname":1,"golint_errorlint":12,"golint_forcetypeassert":3,"golint_gosec":0,"golint_intrange":3,"golint_modernize":5,"golint_nilnil":3,"golint_perfsprint":18,"golint_prealloc":3,"golint_recvcheck":7,"golint_usestdlibvars":3,"golint_wastedassign":7,"golint_total":73,"eslint_problems":1,"eslint_errors":0,"eslint_warnings":1,"tsc_errors":0,"measure_s":38},"status":"keep","description":"modernize 37→5（-32）：interface{}→any、内置 max/min、slices/maps 辅助、strings.Cut/SplitSeq、strings.Builder（修复 mail.go O(n²) 拼接）。逐 hunk 核对语义等价；omitzero 冲突修复被自动跳过（wire 格式不变）；手动清 4 处遗留 sort import + 2 处 QF1012。","timestamp":1786872502383,"segment":0,"confidence":17,"asi":{"hypothesis":"批量应用 modernize 自动修复（interface{}→any、max/min、slices.Sort/Contains、strings.Cut/SplitSeq、maps.Copy、strings.Builder）","insight":"golangci-lint --fix 会把 omitempty→omitzero 的冲突修复跳过（2个文件保留原 tag，wire 格式不变，好）；但 fixer 会遗留未使用的 sort import，需手动清 4 处；mail.go 的 Builder 迁移附带暴露 2 个 QF1012，顺手用 fmt.Fprintf 修复。全部修复语义等价，已逐项核对 diff","next_action_hint":"剩余 modernize=5 应为 omitzero 冲突文件；下轮先处理 perfsprint(18)：先看 --fix 是否安全再决定"}}
+{"run":4,"commit":"699e95f","metric":56,"metrics":{"golint_canonicalheader":8,"golint_errname":1,"golint_errorlint":12,"golint_forcetypeassert":3,"golint_gosec":0,"golint_intrange":3,"golint_modernize":5,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":3,"golint_recvcheck":7,"golint_usestdlibvars":3,"golint_wastedassign":7,"golint_total":55,"eslint_problems":1,"eslint_errors":0,"eslint_warnings":1,"tsc_errors":0,"measure_s":47},"status":"keep","description":"perfsprint 18→0：strconv.Itoa/FormatInt/FormatUint/FormatBool 替代 fmt.Sprintf、无动词 fmt.Errorf→errors.New、纯字符串拼接。全部语义等价（已核对 diff）。修正 fixer 遗留的 import 问题（引入 goimports 统一整理）。","timestamp":1786872884713,"segment":0,"confidence":3.0588235294117645,"asi":{"hypothesis":"perfsprint --fix：%d→strconv.Itoa/FormatInt、%t→FormatBool、%s+const→拼接、无动词 Errorf→errors.New","insight":"重要：golangci-lint v2 fixer 的 import 管理不可靠（删除/添加 import 会出错，53 个文件中 5 处报 undefined）+ 遗留未用 import。已安装 goimports（repo make format 本来就需要它），对改动文件统一 goimports -w 修复。后续只要用 --fix 就要记得跑 goimports -w","next_action_hint":"剩余大头：errorlint(12)、canonicalheader(8)（usestdlibvars 同类）、recvcheck(7)、wastedassign(7)。errorlint 需手工逐处判断；先做 canonicalheader+usestdlibvars（自动可修复但要核对）"}}
+{"run":5,"commit":"d0414b4","metric":45,"metrics":{"golint_canonicalheader":0,"golint_errname":1,"golint_errorlint":12,"golint_forcetypeassert":3,"golint_gosec":0,"golint_intrange":3,"golint_modernize":5,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":3,"golint_recvcheck":7,"golint_usestdlibvars":0,"golint_wastedassign":7,"golint_total":44,"eslint_problems":1,"eslint_errors":0,"eslint_warnings":1,"tsc_errors":0,"measure_s":38},"status":"keep","description":"canonicalheader 8→0 + usestdlibvars 3→0：header key 改为 Go 规范大小写（wire 格式本就如此，纯代码修正）、HTTP 方法常量替代字符串字面量。","timestamp":1786873098921,"segment":0,"confidence":2.1724137931034484,"asi":{"hypothesis":"canonicalheader+usestdlibvars --fix：Header key 统一规范大小写、GET/OPTIONS 等方法常量","insight":"GitHub header 修正前后的 wire 格式完全一致（Go 在 Set 时本来就会规范化），纯代码层面修正，零行为风险；下次遇到同类 100% 安全","next_action_hint":"剩余：errorlint(12) 需逐处人工判断（其中 3 处 err != context.Canceled、2 处 %v wrap、若干 ==/类型断言）；recvcheck(7) 是模型接收者一致性；wastedassign(7) 删 TODO 赋值；intrange(3)/modernize(5)/nilnil(3)/prealloc(3)/forcetypeassert(3)/errname(1)/eslint(1)"}}
+{"run":6,"commit":"ce28f63","metric":38,"metrics":{"golint_canonicalheader":0,"golint_errname":1,"golint_errorlint":12,"golint_forcetypeassert":3,"golint_gosec":0,"golint_intrange":3,"golint_modernize":5,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":3,"golint_recvcheck":7,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":37,"eslint_problems":1,"eslint_errors":0,"eslint_warnings":1,"tsc_errors":0,"measure_s":47},"status":"keep","description":"wastedassign 7→0：删除 7 处死初始化（snapshot.go 三连、push 三件套 content、format.go numStr），改 var 声明，零行为变化。","timestamp":1786873485497,"segment":0,"confidence":2.978723404255319,"asi":{"hypothesis":"wastedassign 7→0：删除 7 处死初始化（x := \"\" 后所有分支都赋值）改为 var 声明","insight":"replace 工具会归一化 replacement_text 的前导空白；对需要缩进的编辑直接用 sed/gofmt -w 处理更稳","next_action_hint":"剩余：errorlint(12)、recvcheck(7)、modernize(5)、intrange(3)、nilnil(3)、prealloc(3)、forcetypeassert(3)、errname(1)、eslint(1)"}}
+{"run":7,"commit":"288b74d","metric":33,"metrics":{"golint_canonicalheader":0,"golint_errname":1,"golint_errorlint":12,"golint_forcetypeassert":3,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":3,"golint_recvcheck":7,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":32,"eslint_problems":1,"eslint_errors":0,"eslint_warnings":1,"tsc_errors":0,"measure_s":45},"status":"keep","description":"intrange 3→0 + modernize 5→3：for i:=0;i<len/N;i++ → range len/N（8 处）；time.Time 字段 omitempty→omitzero（wire 输出一致）；SplitSeq；min() 简化。刻意保留 lark.go omitzero（会改变 wire 行为）。","timestamp":1786873629461,"segment":0,"confidence":4.166666666666667,"asi":{"hypothesis":"intrange(3) + modernize 剩余（2 个 time.Time omitempty→omitzero + SplitSeq + min）","insight":"lark.go larkTextContent omitempty→omitzero 会改变 wire（普通 struct 无 IsZero，当前恒序列化，改后零值省略）—— 判定为行为变化，故意保留；time.Time 字段 omitempty/omitzero 输出一致，可安全替换","next_action_hint":"剩余：errorlint(12) 大头（3 处 != context.Canceled 需确认 runner 是否 wrap；%v→%w 2 处；若干 ==err / 类型断言）；recvcheck(7)；forcetypeassert(3)；nilnil(3)；prealloc(3)；errname(1)；eslint(1)"}}
+{"run":8,"commit":"86fad02","metric":22,"metrics":{"golint_canonicalheader":0,"golint_errname":1,"golint_errorlint":1,"golint_forcetypeassert":3,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":3,"golint_recvcheck":7,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":21,"eslint_problems":1,"eslint_errors":0,"eslint_warnings":1,"tsc_errors":0,"measure_s":46},"status":"keep","description":"errorlint 12→1：3 处 cmd 入口 err!=context.Canceled→errors.Is（防御性，当前 runner 不 wrap 语义不变）；2 处 strconv.NumError 断言、1 处 viper 断言、2 处 ==io.EOF、2 处 ==redis.Nil、1 处 ==gorm.ErrRecordNotFound→errors.As/Is；8 处 %v→%w 保留错误链。刻意保留 telegram.go 单处 %v（原始错误仅作上下文文本，wrap 会改变 errors.Is 匹配语义）。","timestamp":1786873923775,"segment":0,"confidence":4.195121951219512,"asi":{"hypothesis":"errorlint 12→1：errors.Is/As 替代 ==/类型断言（防御 wrap），%v→%w 保留错误链","insight":"errorlint 结果在并行分析时一度不稳定（可能文件缓存竞争），多跑一次确认；telegram.go 的 %v 是刻意保留原始 HTML 错误为文本（只 wrap fallbackErr），判定为合理例外，不计为负债。错误链保留（%w）对多错误组合消息（manager.go、restart_unix.go、service.go）是净收益，调用方无 Is 匹配这些次要错误","next_action_hint":"剩余：recvcheck(7)、forcetypeassert(3)、nilnil(3)、prealloc(3)、modernize(3=lark omitzero 刻意保留)、errname(1)、eslint(1)"}}
+{"run":9,"commit":"4ecec2c","metric":15,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":7,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":14,"eslint_problems":1,"eslint_errors":0,"eslint_warnings":1,"tsc_errors":0,"measure_s":43},"status":"keep","description":"forcetypeassert 6→0（缓存 list 断言、relay/flared 中间件契约断言、图片压缩 flight 断言，全部带检查+安全失败路径）；errname 1→0；prealloc 2 处（另 1 处与 repo mnd 冲突，用命名常量解决）。nilnil 保留（not-found/可选结果惯例，含接口契约注释）。","timestamp":1786874283774,"segment":0,"confidence":4.043478260869565,"asi":{"hypothesis":"forcetypeassert(6处) → 带检查断言（middleware 契约破坏时 Abort 401/返回错误）；errname runtimeInitErr→errRuntimeInit；prealloc 2 处（uptimekuma、postgres replicas）","insight":"prealloc 与 repo mnd 门禁冲突（magic number 3）：用命名常量 baseTracingOptionCount 同时满足两者；nilnil 5 处判定为合法 not-found/可选结果惯例（含接口注释契约 + 测试断言），全部保留；用 --max-issues-per-linter=0 拿全量清单避免被默认 50 截断误导","next_action_hint":"剩余：recvcheck(7) 接收者一致性（需逐模型判断）、eslint(1) exhaustive-deps、modernize(3=lark omitzero 刻意保留+2 处待查)、nilnil(3 刻意保留)、errorlint(1 刻意保留)"}}
+{"run":10,"commit":"73d8173","metric":9,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":1,"eslint_errors":0,"eslint_warnings":1,"tsc_errors":0,"measure_s":45},"status":"keep","description":"recvcheck 7→1：6 个 GORM 模型 TableName 改为指针接收者（GORM 源码确认 reflect.New 判定 Tabler，兼容；模型单测通过）。MillisecondDuration 刻意保留（encoding/json 要求 Marshal 值/Unmarshal 指针的混合）。","timestamp":1786874445733,"segment":0,"confidence":4.304347826086956,"asi":{"hypothesis":"recvcheck 7→1：GORM 模型 TableName 值接收者→指针接收者，与其它方法一致","insight":"GORM schema.Parse 用 reflect.New(modelType) 判定 Tabler，指针接收者 TableName 完全兼容（已读 gorm 源码确认 + 模型单测通过）；仓库中 (Model{}).TableName() 字面量调用都在未改的类型上，无破坏。MillisecondDuration 保留：MarshalJSON 值接收者是 json 对不可寻址值的行为保障，UnmarshalJSON 必须指针 —— 混合是 encoding/json 硬性要求","next_action_hint":"剩余：modernize(3，含 lark omitzero 刻意保留 + 2 处待查)、nilnil(3 刻意保留)、eslint(1 exhaustive-deps)、errorlint(1 刻意保留)。下一步查 modernize 剩余 2 处并修 eslint 的 hook 依赖"}}
+{"run":11,"commit":"111d290","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":38},"status":"keep","description":"eslint 1→0：pages-source-card useEffect 补 t 依赖（next-intl 稳定引用）。modernize 补 1 处 time.Time omitzero。剩余 8 全部为刻意保留项。","timestamp":1786874578893,"segment":0,"confidence":4.3478260869565215,"asi":{"hypothesis":"eslint 1→0：useEffect 依赖数组补 t（next-intl useTranslations 返回稳定引用，安全）；modernize 补 1 处 time.Time omitempty→omitzero（输出一致）","insight":"modernize 剩余 3 处全部是嵌套 struct omitempty（client.go Release/Asset、lark.go Content）→ omitzero 会改变 wire，全部刻意保留。至此所有可安全修复的类别清零，剩余 8 个全部是有据可查的刻意保留项","next_action_hint":"剩余 8 全部刻意保留（errorlint 1 telegram、modernize 3 嵌套struct、nilnil 3 not-found、recvcheck 1 json）。下一轮做深化方向：测试代码质量（tests:false 之外）、或 golangci 附加 linter（gocritic 更多检查）作为新基准段"}}
+{"run":12,"commit":"e5f6b0a","metric":33,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":20,"golint_test_thelper":3,"golint_test_usetesting":2,"golint_test_total":25,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":37},"status":"keep","description":"基准扩展（文档化）：新增测试代码质量维度 25 处（testifylint 20 + thelper 3 + usetesting 2），生产代码 8 处刻意保留不变。新基线 total=33。","timestamp":1786874744438,"segment":0,"confidence":4.878048780487805,"asi":{"hypothesis":"扩展基准到测试代码质量维度（testifylint 20 + thelper 3 + usetesting 2 = 25）","insight":"刻意排除 paralleltest/tparallel（共享 DB/redis 状态 + 本环境无法跑测试，t.Parallel 有风险）—— 这是范围扩展（抬高门槛），不是 gaming；基准定义已写入 prompt.md","next_action_hint":"修 25 处测试问题：float-compare 3（InDelta）、require-error 3、encoded-compare 1（JSONEq）、empty 3、contains 1、error-is-as 3、len 3、go-require-in-handler 2、t.Helper 3、os.MkdirTemp→t.TempDir 2"}}
+{"run":13,"commit":"63a24da","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":39},"status":"keep","description":"测试代码质量 25→0：assert↔require 一致性（fail-fast）、float 精确比较→InDelta、Equal(\"\",x)→Empty、Equal(len)→Len、errors.Is/As→ErrorIs/ErrorAs、JSON 字符串→JSONEq、handler goroutine 内 require→assert（真健壮性修复）、t.Helper()、os.MkdirTemp→t.TempDir()（符合 repo AGENTS 约束）。","timestamp":1786875177918,"segment":0,"confidence":4.3478260869565215,"asi":{"hypothesis":"修完测试代码质量维度 25 处（testifylint 20 + thelper 3 + usetesting 2）","insight":"批量修复过程揭示 testifylint 默认 max-same-issues=3 会掩盖重复模式（len(entries) 出现 4+ 次、float64(3) 4 次），需 --max-issues-per-linter=0 反复收敛；全部修复语义中性（assert↔require 仅 fail-fast 差异，InDelta/JSONEq/Empty/Len/ErrorIs 等价断言，t.Helper/t.TempDir 纯改善）。go-require 类（handler 内 require→assert）是真正的健壮性修复","next_action_hint":"测试维度清零。生产代码剩余 8 全部刻意保留。可选深化：gocritic 更多子检查/staticcheck 更多（SA 系列）扫描、或 biome check 格式一次性提交、或前端 a11y（eslint jsx-a11y 已含于 next core-web-vitals 默认关闭项）"}}
+{"run":14,"commit":"65c02ef","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":36},"status":"keep","description":"基准扩展 exhaustive（文档化）+ 12→0：枚举 switch 补显式 case（全部与现有 default 行为等价，fail-explicit 防未来枚举静默落入 default）；source_tasks.go 为控制复杂度合并两个等价校验条件。","timestamp":1786875548060,"segment":0,"confidence":4.25531914893617,"asi":{"hypothesis":"基准扩展 exhaustive（12 处枚举 switch 显式化）+ 全量修复","insight":"12 处全部是 default 已正确处理、缺显式 case 的类型；补显式 case 仅为 fail-explicit（未来枚举新增不会静默落入 default）。source_tasks 补 case 后 Execute 复杂度 20→21 触发 cyclop，合并两个 ActionInvalid 条件（逻辑等价）降回 19。cyclop 与 exhaustive 的张力：显式 case 也计入复杂度","next_action_hint":"剩余 8 全为刻意保留。可再深化：sloglint 全量、govet 附加分析器、或前端 jsx-a11y/next 规则已有覆盖。也可将剩余 8 处文档化后收尾总结"}}
+{"run":15,"commit":"d7b8f44","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":37},"status":"keep","description":"修复 geoip/runtime.go 真死代码：ensureServerMMDB 的 os.Stat 错误被 if-init 遮蔽，`err != nil && !os.IsNotExist(err)` 恒为 false（外层 err 恒 nil），防御检查从未生效；改为显式捕获 statErr，stat 非 not-exist 错误现在正确返回。基准新增第 4 维度 govet nilness+unusedwrite（文档化扩展），当前 0。","timestamp":1786875949461,"segment":0,"confidence":4.166666666666667,"asi":{"hypothesis":"govet nilness 真实死代码 bug：ensureServerMMDB 的 stat 错误被 if-init 遮蔽，!os.IsNotExist(err) 恒为死条件（外层 err 恒 nil）","insight":"修复：显式捕获 statErr，使防御检查生效（stat 权限错误现在立即返回，不再静默吞掉后走 WriteFile 失败）。顺带基准扩展第 4 维度 govet nilness+unusedwrite（文档化，survey 过 fatcontext/containedctx/unparam/gocritic+29 检查：unparam 有 6+ 处真实死结果但需签名改动，留待下轮）","next_action_hint":"下轮候选：unparam（6+ 处 always-nil/never-used 结果，含 getSQLiteOverview/getPostgresOverview/getStatus 等，需改签名+调用方，churn 中等但都是真实死代码）；或 fatcontext/containedctx（3+3 处，需逐处判断是否真反模式）"}}
+{"run":16,"commit":"c85373f","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":43},"status":"keep","description":"unparam 死代码清理 12→2（保留 2 处 objectstore 构造函数统一签名）：移除 10 处恒 nil error / 从未使用的结果（getPoWConfigForRoute 的恒 nil *PoWConfig、getSQLiteOverview/getPostgresOverview/getStatus/loadKumaConfig/filterExpectedRoutes 的恒 nil error、rawJSONString/parsePositiveInt 的弃用 bool、buildProxyRoute 的弃用 []ZoneDomain、getLocked 的恒 nil error），同步简化 12+ 处调用方与死错误检查。9 个受影响包测试通过。metric 持平 8（改进在基准之外）。","timestamp":1786876191447,"segment":0,"confidence":5.128205128205129,"asi":{"hypothesis":"unparam 死代码清理：10 处 always-nil error / never-used 结果从签名移除","insight":"移除后调用方同步简化（db_manage 的 err 检查、option routers 的 AbortBadRequestOnError 成为死代码一并删）。getPoWConfigForRoute 的 *PoWConfig 结果恒 nil 且从未被用 —— 真死代码。保留 2 处 objectstore 构造函数 (X, error)：factory switch 统一签名（newS3Backend/newLocalBackend 等可能真实报错），unparam 在此为接口一致性误报。全部 9 个受影响包测试通过。metric 持平 8（改进在基准之外，诚实记录）","next_action_hint":"下一候选：fatcontext(3 处嵌套 context 闭包，多为 slog/otel ctx 传递，需逐处判断是否真反模式) 或 containedctx(3 处 struct 含 ctx 字段，含 webdav/uptimekuma client —— 重构风险中等)；或收尾把 unparam 加入基准（2 处已知保留）"}}
+{"run":17,"commit":"a16be01","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":40},"status":"keep","description":"修复 frpc 进程生命周期真 bug（agent 生产代码）：exec.CommandContext 默认只杀直接子进程，被杀 shell 的孤儿 sleep 继续持有 stderr 管道，cmd.Wait() 阻塞到其自然退出（Stop/重启可挂起秒级）。改 Setpgid 进程组 + Kill(-pid) 整组击杀。连带修复两个测试 bug（Manager 拥有 Cmd 的并发 Wait 竞态 → Signal(0) 探测；ssl_renew 用 miniredis 替代 init() 创建的真实 redis 客户端）。go test ./internal/... ./pkg/... 全绿，checks.sh 升级为真实测试门禁。","timestamp":1786877266517,"segment":0,"confidence":7.142857142857143,"asi":{"hypothesis":"frpc 进程生命周期真 bug：exec.CommandContext 只杀直接子进程，孤儿孙进程持有 stderr 管道导致 cmd.Wait 阻塞到其自然退出（实测脚本 sleep 5 时 Stop 挂起 5s）","insight":"修复：Setpgid 独立进程组 + cmd.Cancel 覆盖为 Kill(-pid,SIGKILL) 整组击杀（经隔离复现 + 临时插桩定位，4 次假设检验收敛）。连带修复两个测试 bug：TestStopCancelsRunningProcesses 对 Manager 拥有的 Cmd 并发 Wait（与 os/exec ctxResult 通道竞争永久挂起）改为 Signal(0) 探测；ssl_renew 测试改用 miniredis（task 包 init() 创建真实 redis 客户端，违反 repo 无 init 装配约束）。成果：go test ./internal/... ./pkg/... 从 3 个失败→全绿（81+13 包），checks.sh 升级为真实测试门禁。metric 持平 8（改进在基准之外，但价值最高的一轮）","next_action_hint":"测试全绿后可解锁：paralleltest/tparallel 维度（t.Parallel 提速）——需先评估共享状态（miniredis/sqlite 每测试独立，风险低）；或探索 relay/frps 同构代码是否有同样的 group-kill 问题（frps/manager 结构相同，值得检查）"}}
+{"run":18,"commit":"f5c9da0","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":39},"status":"keep","description":"前端测试套件 44 失败→全绿：10 个测试文件补 NextIntlClientProvider 包装（含 React19 createElement 类型修复、.ts→.tsx 重命名）；修复真实 i18n ICU bug（githubUrlInvalid 的 {owner}/{repo} 未转义导致生产渲染成 key，zh/en + fragment 4 文件同步转义）；更新 2 处过期测试期望。vitest 116/116 + tsc + eslint 全绿，checks.sh 增加前端测试门禁。","timestamp":1786878501539,"segment":0,"confidence":9.523809523809524,"asi":{"hypothesis":"前端测试可运行性：next-intl 迁移后 44/116 测试失败（缺 NextIntlClientProvider + 3 处真实断言问题）","insight":"修复三类：(1) 10 个测试文件的 render 助手缺 NextIntlClientProvider（createElement 与 JSX 混用踩 React19 类型坑，.ts 文件不能写 JSX → 重命名为 .tsx）；(2) 真实 i18n bug：githubUrlInvalid 消息的 {owner}/{repo} 被 ICU 当占位符，t() 无参调用渲染成 key —— 需 '{' 单引号转义（'{}' 内层转义不够，必须整体引号包裹 '{owner}'），4 个消息文件（zh/en + fragment 源）同步修复，check:i18n 通过；(3) 2 处测试期望过期（唯一访问者→查询窗口独立访客、检查间隔→检查间隔（分钟），以消息文件为准）。成果：116/116 vitest + tsc/eslint 全绿，checks.sh 增加前端测试门禁","next_action_hint":"前端测试全绿后可把 vitest 失败数纳入基准（当前不在基准内）；或检查 app/(main) 目录下 3 个自带 .test.tsx（waf editor 系列）是否也符合新约定"}}
+{"run":19,"commit":"c455be3","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"vitest_failed":0,"vitest_total":116,"measure_s":62},"status":"keep","description":"基准扩展第 5 维度（文档化）：前端 vitest 失败数纳入 total_issues（vitest_failed=0, total=116）。5 维全部处于下限，total=8 不变。","timestamp":1786878719509,"segment":0,"confidence":14.285714285714286,"asi":{"hypothesis":"基准扩展第 5 维度：前端 vitest 失败数（全绿后纳入防回归，文档化范围扩展非作弊）","insight":"measure_s 从 39s 升到 62s（vitest ~20s + eslint 冷启动），可接受。5 个维度全部在其下限：生产 8（全刻意保留）+ 测试 0 + govet 0 + eslint/tsc 0 + vitest 0","next_action_hint":"基准已 5 维全下限。后续可深化：paralleltest（现在测试可跑，但共享全局状态风险仍在，低优先）；或 frontend biome 格式一次性提交（不进基准）；或前端组件更深规则（jsx-a11y 已在 next core-web-vitals 覆盖）。也可认为会话到达稳定收尾点，更新 prompt/ideas 后总结"}}
+{"run":20,"commit":"4962bf9","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"vitest_failed":0,"vitest_total":116,"measure_s":86},"status":"keep","description":"两处真实质量修复：(1) 过期 swagger 文档重新生成（status_2xx/4xx/5xx_count 字段随 a4dd5ca9 加入后未同步 docs，违反 repo 约定，swag init 后差异仅真实新增字段）；(2) generate-themes.js 输出补尾换行，themes.json 构建可复现（此前每次 build 弄脏工作树）。验证 next build 成功、musttag/tagalign 调查无真实问题。","timestamp":1786879144888,"segment":0,"confidence":25,"asi":{"hypothesis":"验证生产构建 + 修两处真实质量问题：swagger 文档过期（status_2xx/4xx/5xx_count 新增字段未重新生成）与 themes.json 构建不可复现（generate-themes.js 缺尾换行，每次 build 弄脏工作树）","insight":"next build 成功（无构建问题）；musttag 3 处与 tagalign 均判定为非问题（持久化 round-trip 自洽/调试日志/纯格式）。swagger 差异仅 27 行且全部真实（a4dd5ca9 状态码拆分字段）。generate-themes.js 补 '\\n' 后 themes.json 再生与提交版完全一致，构建可复现。metric 持平 8（改进在基准之外）","next_action_hint":"会话已 5 维全下限 + 构建可复现 + 双端测试全绿。收尾候选：更新 prompt/ideas 记录本轮成果后总结；或继续验证 swag 生成的 docs.go 在 CI 中的可复现性"}}
+{"run":21,"commit":"e1b439d","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"vitest_failed":0,"vitest_total":116,"measure_s":74},"status":"keep","description":"全仓 go test -race 扫描（93 包）→ 全绿。修复 6 类数据竞争：frpc/frps 测试的锁外读与并发 Wait；oauth/repository 4 个 Pub/Sub 监听器 goroutine 读可变包变量（局部捕获 + done 通道等待）；oauth 测试换 db.Redis 前停监听器；【真实生产 bug】tls 响应快照与异步续签 goroutine 并发写 cert 竞争（先快照再起 goroutine）；upload/cache 监听器 goroutine 内读 db.Redis（调用方捕获）。","timestamp":1786881379399,"segment":0,"confidence":100,"asi":{"hypothesis":"全仓 -race 扫描：发现并修复 6 类数据竞争，含 1 个真实生产竞争","insight":"修复清单：(1) frpc 测试助手锁外读 proc.Status；(2) frps 测试对 Manager 拥有的 Cmd 并发 Wait（与 frpc 同类）；(3) oauth/repository 4 个 Pub/Sub 监听器 goroutine 内读可变包变量 userListenerCtx 等 → 局部捕获 + stop 增加 done 通道等待；(4) oauth 测试 setupTestRouter 换 db.Redis 前先停各层监听器；(5)【真实生产 bug】tls logics 的 sanitizeCertificateForResponse 整体拷贝 cert 与异步续签 goroutine 字段写入并发 → 先快照再起 goroutine；(6) upload/cache 监听器 goroutine 内读 db.Redis → 调用方捕获。成果：93 包 go test -race 全绿。基准 5 维全下限不变（改进在基准外，但 tls 竞争是生产级真实问题）","next_action_hint":"可考虑把 -race 纳入周期性验证（不进每次 checks，全仓 ~3 分钟）；或在 prompt/ideas 记录本轮成果"}}
+{"run":22,"commit":"ab70633","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"vitest_failed":0,"vitest_total":116,"measure_s":68},"status":"keep","description":"checks.sh 新增并发密集包 -race 门禁（8 个快速包，全仓 -race 清零后纳入防回归；frpc/frps 慢套件留作周期全量验证）。核查 7 处 t.Skip 均为合法环境门控。","timestamp":1786881700477,"segment":0,"confidence":200,"asi":{"hypothesis":"把 -race 门禁纳入 checks.sh（并发密集包子集，全仓 -race 清零后防回归）","insight":"选 8 个快速并发包（oauth/tls/uptimekuma/upload-cache/repository/disk-cache/logger/batchwriter，约 20s），排除 frpc/frps 慢套件（15s backoff + 25s supervisor，另做周期全量验证）。checks 总耗时 ~60s 可接受。顺带核查 7 处 t.Skip 均为合法环境门控（PG/CH 集成、symlink 平台差异），无隐藏损坏。metric 持平 8","next_action_hint":"会话已达全面收敛：5 维基准全下限 + 全仓 -race 清零 + 双端测试全绿 + 构建可复现 + -race 门禁入 checks。可收尾：更新 prompt/ideas 后总结"}}
+{"run":23,"commit":"aa4fadd","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"vitest_failed":0,"vitest_total":116,"measure_s":81},"status":"keep","description":"补齐 131 个 .go 文件的 SPDX license 头（repo 自带 make license 约定，早于约定新增的文件含 2 个生产文件；纯注释插入零行为影响），make license-check 转绿。go mod tidy -diff 确认干净。","timestamp":1786882164158,"segment":0,"confidence":null,"asi":{"hypothesis":"跑 repo 自带门禁 make license-check：发现 131 个 .go 文件缺 SPDX 头（早于 license 约定，含 2 个生产文件与多份本会话早期改过的文件）","insight":"用 repo 自带 scripts/update_go_license.sh（make license）自动补头（391 行纯注释插入），license-check 转绿；go mod tidy -diff 干净。gofmt/build/全测试/-race 均通过。metric 持平 8","next_action_hint":"会话全维度收敛。收尾：把 license-check 加入 checks.sh 防再犯；更新 prompt/ideas 最终状态"}}
+{"run":24,"commit":"4d78bc1","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"vitest_failed":0,"vitest_total":116,"measure_s":83},"status":"keep","description":"收敛验证轮：3× 时序敏感包测试无 flake；config.example.yaml ↔ model.go 同步确认无漂移（scheduler 空结构、replicas 注释化、queues[].name 嵌套均为误报）；make build-embedded 发布路径构建成功且工作树干净（bin/、frontend/out 已 gitignore）。更新 prompt/ideas 记录会话终态。metric 持平 8。","timestamp":1786882694298,"segment":0,"confidence":null,"asi":{"hypothesis":"会话收敛验证：跑 3× 时序敏感包（无 flake）、config.example.yaml↔model.go 同步（3 个疑似缺失均为误报：scheduler 空结构/replicas 注释化/queues[].name 嵌套）、make build-embedded 发布路径（成功且树干净）","insight":"全部为确认性结果，无新问题。诚实记录：本轮零代码改动（上一轮已修 license），metric 持平 8。会话正式收敛：基准 5 维全下限 + 全仓 -race 清零 + 双端测试全绿 + 发布可复现 + config/文档同步。prompt/ideas 已更新终态","next_action_hint":"会话已收敛。若继续：周期全量 -race、前端 axe 浏览器级 a11y 审计（ideas.md 已记录）"}}
+{"run":25,"commit":"7f8e257","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"vitest_failed":0,"vitest_total":118,"measure_s":71},"status":"keep","description":"前端真实 a11y 审计：新增 axe-core（devDep）+ tests/a11y.test.tsx，对登录页与注册页渲染完整表单后运行 axe 结构性规则（label/button-name/heading-order/landmark/aria），两页均零违规。摸清并处理了渲染依赖（UserProvider 会话检查、publicConfigQuery 门控、configBool 字符串语义）。vitest 116→118 全绿。","timestamp":1786884595141,"segment":0,"confidence":null,"asi":{"hypothesis":"前端真实 a11y 审计：axe-core（jsdom 结构性规则）覆盖登录/注册页，超出 eslint 静态 jsx-a11y 的动态可访问性验证","insight":"新增 tests/a11y.test.tsx（2 测试）+ axe-core devDependency。调试中摸清登录/注册页渲染依赖链（UserProvider 挂载跳查 getUserInfo、LoginForm/RegisterForm 门控 publicConfigQuery、configBool 期望字符串 'true' 而非布尔 —— mock 需给字符串）。两页均零 axe 违规（color-contrast 因 jsdom 无布局引擎禁用，文档化）。vitest 116→118，checks 全绿。metric 持平 8","next_action_hint":"可扩展 axe 到更多页面（如登录 OTP 态、设置页），或收尾。axe 依赖仅 devDependency，不进基准计数（vitest_failed 已含新测试）"}}
+{"run":26,"commit":"7d03154","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"vitest_failed":0,"vitest_total":120,"measure_s":71},"status":"keep","description":"axe a11y 审计扩展到登录 OTP 验证表单（input-otp 分段输入，FieldLabel htmlFor 正确关联，零违规）与人机验证小部件手动模式（零违规）。环境修复：tests/setup.ts 加 ResizeObserver mock（input-otp 依赖，jsdom 未内置）。vitest 118→120 全绿。","timestamp":1786885103995,"segment":0,"confidence":null,"asi":{"hypothesis":"把 axe a11y 审计扩展到登录/注册外的关键表单状态：登录 OTP 验证（input-otp 分段输入是经典 a11y 雷区）与人机验证小部件（CapWidget 手动模式）","insight":"新增 2 个 axe 测试（vitest 118→120）。OTPForm 验证通过 —— FieldLabel htmlFor='otp-verification' 与 InputOTP id 正确关联，分段输入零违规；CapWidget 手动模式零违规。环境修复：input-otp 依赖 ResizeObserver，jsdom 未内置 → tests/setup.ts 加 ResizeObserver mock（全局，其它测试无害）。渲染上下文修正：裸组件需 <main> landmark 包裹（region 规则，真实页面由 AuthShell 提供）。scripts/ Go 代码用扩展 linter 集扫描为 0 问题（死路，未纳入基准）。metric 持平 8","next_action_hint":"a11y 覆盖已达：登录/注册页/OTP/CapWidget 全零违规。剩余页面（设置页、admin）需较重 mock。会话可收尾，或周期跑全量 -race 验证无 flake"}}
+{"run":27,"commit":"6c128e0","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"vitest_failed":0,"vitest_total":121,"measure_s":71},"status":"keep","description":"axe a11y 审计扩展到最复杂认证路径：注册页开启人机验证（CapWidget 自动求解→已通过状态 + 完整表单），mock getCapToken 避免 jsdom 无 Worker 环境限制。零违规。vitest 120→121 全绿。","timestamp":1786885536618,"segment":0,"confidence":null,"asi":{"hypothesis":"axe 审计覆盖最复杂的认证渲染路径：注册页开启人机验证（CapWidget 自动求解→已通过状态 + 完整表单）","insight":"新增第 5 个 axe 测试（vitest 120→121）：mock @/lib/cap-solver 的 getCapToken 直接 resolve token（避免 jsdom 无 Web Worker），config 开 cap_login_enabled/cap_auto_solve，注册页渲染出 CAPTCHA 已通过态 + 表单全字段 → 零违规。vi.mock('@/lib/cap-solver') 对其它测试无害（仅 capEnabled 时渲染 CapWidget）。metric 持平 8","next_action_hint":"axe 覆盖已达 5 个认证表单态（登录/注册/OTP/验证小部件手动/注册+验证）。剩余：设置页与 admin 页需较重 mock。可收尾，或周期跑全量 -race 验证无 flake"}}
+{"run":28,"commit":"40eee77","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_vetx_total":0,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"vitest_failed":0,"vitest_total":121,"measure_s":0},"status":"keep","description":"前端显式 any 类型清理 2→0：Slot children?: any → ReactNode | MotionValue 联合（motion 真实类型），顺带修复潜在崩溃（原代码在 isValidElement 前访问 children.type，缺失时 TypeError，现无效 children 返回 null，hooks 无条件合规）；useControlledState Rest extends any[] → unknown[]。两处 eslint-disable 注释删除。tsc/eslint/vitest 121 全绿。","timestamp":1786886086713,"segment":0,"confidence":null,"asi":{"hypothesis":"前端显式 any 类型清理：全仓 grep 仅 2 处 any —— Slot children?: any 与 useControlledState 的 Rest extends any[]，均为真实类型缺陷","insight":"全前端 any 计数 2→0。slot.tsx：children?: any → React.ReactNode | MotionValue<string> | MotionValue<number>（motion HTMLMotionProps 的真实 children 类型）；顺带修复潜在崩溃 —— 原代码在 isValidElement 检查前就访问 children.type，children 缺失时 TypeError，改为 isValidChild/childrenType 先计算（hooks 无条件，rules-of-hooks 合规），无效 children 返回 null。use-controlled-state.tsx：Rest extends any[] → unknown[]。两处 eslint-disable no-explicit-any 注释随之删除（无抑制注释）。tsc/eslint/vitest 121/checks.sh 全绿。benchmark 无关（metric 持平 8）。注意：run #28 的 run_experiment 被用户中断（aborted），但代码修复已通过全部门禁验证","next_action_hint":"用户要求合并到 main 并推送"}}
+{"run":29,"commit":"511bed8","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":63,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_exhaustive":0,"golint_vetx_total":0,"vitest_failed":0,"vitest_total":124},"status":"keep","description":"修复 2 个新增 unconvert 问题（linux.go 中 int64(stat.Bsize) 恒等转换，Statfs_t.Bsize 在 Linux 上本就是 int64），删除多余转换零行为变化；total 10→8 回到 5 维全下限。","timestamp":1786894372432,"segment":0,"confidence":null,"asi":{"category":"unconvert","hypothesis":"会话恢复后 measure 显示 total=10，出现 2 个新的 unconvert 问题（internal/apps/edge/observability/linux.go:261-262 的 int64(stat.Bsize) 恒等转换，Linux Statfs_t.Bsize 本就是 int64）。删除多余转换，零行为变化","finding":"unconvert 是 repo 自带配置启用的 linter，此前 baseline 无此问题，最近用户提交/Go 版本变化后新增；修复后 5 维回到全下限 8","next_action_hint":"会话恢复点确认：total=8（5 维全下限，8 项均为有据可查的刻意保留）。下一轮候选：静态检查新维度（staticcheck SA 系列在 repo 配置中已启用且为 0）、或把 docs/ 下 vitepress 站点的构建纳入 measure 防回归（docs build 不属质量计数，不进基准）"}}
+{"run":30,"commit":"d49c7e1","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":183,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_exhaustive":0,"golint_vetx_total":0,"vitest_failed":0,"vitest_total":126},"status":"checks_failed","description":"Agent 发现 Token 比较改为 SHA-256 后恒定时间 Compare，堵住未授权节点注册口的计时侧信道。checks 在 -race 阶段超时（包本身已单独跑绿）。","timestamp":1787667218065,"segment":0,"confidence":null,"asi":{"hypothesis":"discovery token 用 != 比较，未授权 /agent/nodes/register 可被计时；改 SHA-256 + ConstantTimeCompare","rollback_reason":"checks.sh 在 go test -race 阶段 300s 超时（包单独跑全绿，预算不够）","next_action_hint":"同一修复用 checks_timeout_seconds=600 重跑"}}
+{"run":31,"commit":"69055a9","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":71,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_exhaustive":0,"golint_vetx_total":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"未授权 Agent 注册口的 discovery token 改为 SHA-256 后恒定时间比较，堵住计时侧信道；空 token / 末字节翻转用例同步补上。metric 持平 8。","timestamp":1787667401636,"segment":0,"confidence":null,"asi":{"hypothesis":"discovery token 用 != 比较，未授权 /agent/nodes/register 可被计时；改 SHA-256 + ConstantTimeCompare","finding":"公开面注册口 ValidateDiscoveryToken 是入侵入口；管理员已登录操作不在范围内。checks 全绿。","next_action_hint":"下一轮可查边缘 Token 比较（agent/relay/flared 走 DB 查找，计时面更弱）或登录口限流"}}
+{"run":32,"commit":"fb62802","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":81,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_exhaustive":0,"golint_vetx_total":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"公开登录/注册邮箱验证码比较改为 SHA-256 后恒定时间 Compare，堵住未授权口的计时侧信道。metric 持平 8。","timestamp":1787667660993,"segment":0,"confidence":null,"asi":{"hypothesis":"verifyEmailCode 用 != 比较 6 位码，公开登录/注册口可被计时","finding":"公开面验证码比较已改恒定时间；冷却仍在，不改限流策略。","next_action_hint":"下一轮可查边缘节点 access_token 比较（DB 查找，计时面更弱）或登录失败锁定"}}
+{"run":33,"commit":"b8bf82b","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":99,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_exhaustive":0,"golint_vetx_total":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"未授权登录口补哑 bcrypt 比较，用户不存在与密码错误耗时对齐；禁用账号不再返回不同文案，堵住用户枚举。metric 持平 8。","timestamp":1787668237322,"segment":0,"confidence":null,"asi":{"hypothesis":"未授权 /user/login 在用户不存在时跳过 bcrypt，且禁用账号返回不同文案，可枚举用户","finding":"DummyCheckPassword 启动时生成哑哈希，gosec 不报警；禁用账号改统一错误文案。管理员已登录不在范围内。","next_action_hint":"下一轮可查边缘节点 access_token 明文比较，或公开 CAP challenge 滥用"}}
+{"run":34,"commit":"380a42a","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":90,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_exhaustive":0,"golint_vetx_total":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"登录/注册/OAuth 回调统一走 SetLoginSession，保存前清空 Redis 会话 ID，堵住未授权会话固定。metric 持平 8。","timestamp":1787669059138,"segment":0,"confidence":null,"asi":{"hypothesis":"生产 Redis 会话在登录时复用同一 ID，未授权方可固定会话 cookie","finding":"SetLoginSession 先 Clear 再把 gorilla session.ID 置空，Save 时 redistore 生成新 ID；明文改密标记经 extras 写回。","next_action_hint":"下一轮可查边缘节点 access_token 明文比较，或公开 CAP challenge 滥用"}}
+{"run":35,"commit":"dfda2d3","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":75,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_exhaustive":0,"golint_vetx_total":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"去掉公开 CAP 口硬编码默认密钥；SessionSecret 为空时拒绝签发/核销，防止未授权伪造 PoW。metric 持平 8。","timestamp":1787669542055,"segment":0,"confidence":null,"asi":{"hypothesis":"公开 /api/cap/challenge 在 SessionSecret 为空时用硬编码默认密钥，未授权方可伪造 PoW","finding":"GetDefaultManager 无密钥时返回 nil；Challenge/Redeem 拒绝，VerifyMiddleware 在 CAP 开启时同样拒绝。测试自行设置密钥。","next_action_hint":"下一轮可查公开 OAuth state 洪水或边缘节点 access_token 明文比较"}}
+{"run":36,"commit":"7fa9e46","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":86,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_exhaustive":0,"golint_vetx_total":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"注册开关读取失败时改为关闭，堵住配置缺失时未授权开注册；OAuth 自动注册同样 fail-closed。metric 持平 8。","timestamp":1787669960693,"segment":0,"confidence":null,"asi":{"hypothesis":"registration_enabled/password_register_enabled 读取失败默认 true，和种子 false 相反，配置缺失时未授权开注册","finding":"密码注册与 OAuth 自动注册均 fail-closed；测试改为显式开启注册并正确失效缓存。","next_action_hint":"下一轮可查 OIDC 开关 fail-open（种子默认 true，风险较低）或公开 OAuth state 洪水"}}
+{"run":37,"commit":"0290c93","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":95,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_exhaustive":0,"golint_vetx_total":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"公开 OAuth 登录/授权入口按会话限制 10 分钟内最多 20 个 state，堵住未授权 Redis 洪水。metric 持平 8。","timestamp":1787670327304,"segment":0,"confidence":null,"asi":{"hypothesis":"公开 /oauth/login 与 /oauth/{source}/authorize 每次请求都往 Redis 写 10 分钟 state，无上限","finding":"按 sessionHash 计数，10 分钟内最多 20 个；超出返回业务错误。mock Redis 补 Incr/Expire。","next_action_hint":"下一轮可查边缘节点 access_token 明文比较，或公开 CAP challenge 洪水"}}
+{"run":38,"commit":"c0a82f8","metric":8,"metrics":{"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_usestdlibvars":0,"golint_wastedassign":0,"golint_total":8,"eslint_problems":0,"eslint_errors":0,"eslint_warnings":0,"tsc_errors":0,"measure_s":85,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_usetesting":0,"golint_test_total":0,"golint_exhaustive":0,"golint_vetx_total":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"公开密码登录口按 IP 限制 10 分钟内最多 20 次失败，堵住未授权爆破。metric 持平 8。","timestamp":1787670665553,"segment":0,"confidence":null,"asi":{"hypothesis":"公开 /user/login 失败无 IP 限流，未授权方可无限爆破","finding":"按 ClientIP 计数，10 分钟 20 次失败后拒绝；成功清零。管理员已登录不在范围内。","next_action_hint":"下一轮可查公开 CAP challenge 洪水或边缘节点 access_token 明文比较"}}
+{"run":39,"commit":"be5d067","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":76,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"auth_cache negative 缓存加上限防 DoS + relay/flared 删除重复 authenticateAccessToken 改用 agent 共享缓存版","timestamp":1787708052241,"segment":0,"confidence":null,"asi":{"hypothesis":"negative cache 无上限可被伪造 token 撑爆内存；relay/flared 与 agent 三份重复的 authenticateAccessToken","next_action_hint":"继续扫其他无界缓存/限流缺口","result":"metric 持平 8（8 个均为 deliberate keeper），安全修复不计入 metric","security":"negative cache 加 10k 上限+过期清理；relay/flared 复用 agent.AuthenticateAccessToken（共享 2min 正/10min 负缓存，DB 压力下降）"}}
+{"run":40,"commit":"0dd2cf9","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":77,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"websocket 三 hub 去重：抽 runWritePump 共享写泵 + 合并 agent 广播函数为 broadcastAgent","timestamp":1787708370650,"segment":0,"confidence":null,"asi":{"hypothesis":"三份 hub 的 writePump 完全重复（仅日志前缀不同），readPump 已有 runReadPump 抽取先例；BroadcastWAFIPGroups/BroadcastActiveConfig 复制粘贴","next_action_hint":"close() 3 份小重复可再合并但收益低；继续找其他模块的重复/无界增长","result":"metric 持平 8，全测试绿","refactor":"新增 websocket/write_pump.go runWritePump（对齐 runReadPump 模式），agent/relay/flared writePump 改委托；agent_hub 抽 broadcastAgent 合并两个广播函数"}}
+{"run":41,"commit":"efd8268","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":75,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"websocket 三 client 结构体去重：嵌入共享 wsClientCore（close/enqueue 单份实现）","timestamp":1787708975609,"segment":0,"confidence":null,"asi":{"hypothesis":"agentClient/relayClient/flaredClient 字段与 close/enqueue 完全相同，用组合（嵌入 wsClientCore）消除三份重复","next_action_hint":"代码库经 40 轮已高度收敛；后续可周期性跑 go test -race 全量","result":"metric 持平 8，全测试绿；净减 ~60 行重复代码","refactor":"新增 websocket/client_core.go：wsClientCore(nodeID/conn/send/done/once) + 共享 close/enqueue；三个 client 结构体改为嵌入"}}
+{"run":42,"commit":"ed1efd3","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":77,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"补 wsClientCore 并发测试 + close() 防 nil conn 守卫","timestamp":1787709222794,"segment":0,"confidence":null,"asi":{"hypothesis":"wsClientCore 并发语义（close 幂等、enqueue 不阻塞/关后拒绝）无测试覆盖","next_action_hint":"websocket 包已有基础并发测试；继续其他模块扫描","result":"metric 持平 8；测试还暴露 close 未防 nil conn 的防御缺口，已补守卫","refactor":"新增 websocket/client_core_test.go 3 个 -race 测试；client_core.go close() 增加 nil conn 守卫"}}
+{"run":43,"commit":"4f8e7e6","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":77,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"修复 frps/frpc TOML 配置注入：新增 protocol.TOMLQuote 并在两处配置渲染全部使用","timestamp":1787709693698,"segment":0,"confidence":null,"asi":{"hypothesis":"frps/frpc TOML 配置用裸 Fprintf 拼接，token/password/域名含引号、反斜杠、换行时会破坏配置或注入键","next_action_hint":"检查其他配置生成点是否有同类注入面（nginx/openresty 配置）","result":"metric 回到 8；frpc 慢套件 16.8s 全绿；mnd 曾短暂+1（Grow 魔法数），删除微优化后消除","security":"新增 pkg/protocol/toml.go TOMLQuote 转义助手 + toml_test.go；relay/frps renderConfig 与 flared/frpc buildFrpcToml 全部插值改为转义输出"}}
+{"run":44,"commit":"63007fc","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":92,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"全仓 race 扫描发现 upload/cache 监听器 DATA RACE：捕获 redis 客户端消除全局读竞争 + Stop 等待 done + 同型监听器（oauth×2/repository×2）加固","timestamp":1787711092906,"segment":0,"confidence":null,"asi":{"hypothesis":"全仓 go test -race 可能暴露并发 bug（此前仅局部验证）","next_action_hint":"继续扫其他模块；可考虑把 -race 纳入周期性检查","result":"发现并修复 1 个真实 DATA RACE；修复后全仓 -race 0 竞争，metric 持平 8","root_cause":"upload/cache 监听器 goroutine 读可变全局 db.Redis，与 testhelper 清理置 nil 竞争；testhelper 导入 upload/cache 有循环依赖，故用启动时捕获客户端的根因修复（oauth/repository 同型监听器一并加固），并补 StopUploadMetaCacheListener 同步等待 done"}}
+{"run":45,"commit":"63007fc","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":70,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"discard","description":"探索轮：索引对齐/前端请求瀑布/BasicAuth 注入面三假设均证伪，无代码变更","timestamp":1787711474404,"segment":0,"confidence":null,"asi":{"hypothesis":"SQLite 迁移缺 PG 同款索引；前端存在串行请求瀑布；nginx BasicAuth 密码有注入面","next_action_hint":"代码库已高度收敛；下轮可考虑 observability 查询构造器审计或周期性重跑 -race","rollback_reason":"纯探索无代码变更，无需回滚","result":"三个假设均无产出：①索引对比（修正提取正则后）PG/SQLite 完全对齐，SQLite 仅多 legacy w_* 冗余索引；②前端 await Service 均在事件处理器非渲染期；③BasicAuth 密码经 base64 编码（字母表无元字符）无注入面","lessons":"grep 提取 SQL 时注意 IF NOT EXISTS 变体，否则产生假缺口"}}
+{"run":46,"commit":"2cb3392","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":106,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"LIKE 过滤器转义修复：日志搜索含 %/_ 的输入不再被当通配符；pkg/util 新增 EscapeLike 共享助手 + 单测","timestamp":1787712116152,"segment":0,"confidence":null,"asi":{"hypothesis":"日志搜索 LIKE 过滤器不转义 %/_/\\，含下划线的路径/主机名搜索结果错误","next_action_hint":"同类遗留站点（upload/user/task_execution GORM 搜索）已记 ideas.md，可作后续轮次","result":"修复 4 个站点：analytics 两处 CH 过滤器 + logstore postgres_store 两处（PG/SQLite 加 ESCAPE '\\'）。新增 pkg/util/like.go EscapeLike + 单测。metric 持平 8，全部测试通过","scope_decision":"GORM 实体搜索站（upload keyword、user username/email）同 bug 类但低风险且可能依赖现有通配语义，本轮不动"}}
+{"run":47,"commit":"3528323","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":102,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"GORM 实体搜索 LIKE 转义收尾：6 站点复用 EscapeLike + 显式 ESCAPE 子句，含 OAuth 用户名冲突误报修复","timestamp":1787712555794,"segment":0,"confidence":null,"asi":{"hypothesis":"GORM 实体搜索站与 #46 日志搜索同 bug 类：LIKE 模式不转义通配符","next_action_hint":"LIKE 类已全部收尾；下轮可考虑 ideas.md 的测试可运行性方向或周期性全仓 -race 重跑","result":"6 站点修复（upload keyword、user username/email 前缀+contains、OAuth uniqueUsername base、task_type 前缀），PG/SQLite 加显式 ESCAPE。系统常量模式刻意保留（upload.go:199 image/%）。metric 持平 8，测试全绿","scope_decision":"uniqueUsername 的 base 来自 OAuth 用户信息属外部输入，含 _ 会误报用户名冲突——虽是系统生成后缀模式也需转义 base 本身"}}
+{"run":48,"commit":"55db1c0","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":112,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"后台 goroutine panic 防护：新增 pkg/util.Go 共享助手（recover+调用点日志），全仓 22 个裸 go func() 站点统一收口","timestamp":1787713583118,"segment":0,"confidence":null,"asi":{"hypothesis":"全仓 20 处后台 goroutine 裸跑零 recover，任一 panic 击穿 gin handler 级恢复直接崩溃进程","next_action_hint":"goroutine 收口完成；下轮可周期性 go test -race ./... 全量重跑（上次 #44）","result":"pkg/util.Go(fn) 共享助手（runtime.Caller 自动记录调用点 + slog + debug.Stack），22 个站点全部收口（含嵌套 watcher）。脚本转换两轮（首轮漏嵌套内层）。首次 checks_failed 因新文件缺 SPDX 头，update_go_license.sh 修复后全绿。metric 持平 8"}}
+{"run":49,"commit":"40232d8","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":75,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"修复 frpc restartProcess 发布未初始化 exec.Cmd 的数据竞争：proc.Cmd/Status 改为 Start 成功后加锁发布","timestamp":1787714358791,"segment":0,"confidence":null,"asi":{"hypothesis":"周期性全仓 go test -race ./... 重跑（上次 #44 后又改了 repository/logstore/goroutine 站点）能抓出新数据竞争","next_action_hint":"-race 全仓清零；下轮候选：frontend axe a11y 审计，或 Go 1.26 新 linter 扫描","result":"全仓 -race 抓到 1 个真实 race：frpc/manager.go restartProcess 在 cmd.Start() 前就发布 proc.Cmd+Status=running（Start 中 cmd.Process 未赋值），测试读句柄与之竞争。修复=Start 成功后再加锁发布（manager.go:219-220 移入 err==nil 分支）。frpc 包 -race 连续 3 次通过。其余全仓 -race 干净"}}
+{"run":50,"commit":"40232d8","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":70,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"discard","description":"扩展 linter 发现扫描 + 热路径性能排查：errchkjson/unparam/spancheck 等 9 个新维度，全部核实为不可失败/刻意设计/误报","timestamp":1787714798689,"segment":0,"confidence":null,"asi":{"hypothesis":"基准外发现型 linter（errchkjson/unparam/spancheck/exptostd/durationcheck/makezero/reassign/asasalint/bidichk）+ 热路径性能 grep 能找到真实缺陷","next_action_hint":"发现型 linter 已穷尽；下轮候选：frontend axe a11y 浏览器级审计，或任务执行日志/DB 增长类运维审查","result":"全部证伪：errchkjson 12 处均核实为不可能失败的 marshal（纯 string/int/[]string 结构体；2 处 unsafe 标记是传递性保守）；spancheck 1 处误报（唯一调用方 executor.go:242 有 defer span.End()）；unparam×2 为已评估的工厂签名设计；正则全在包级编译无热路径重编译；包级 map 全为有界静态注册表；AppendLog 走 DB 无内存累积。escapeJSONString 用法正确。无代码变更"}}
+{"run":51,"commit":"bbf7919","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":72,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"discard","description":"运行时资源审计：HTTP 客户端超时覆盖 + 查询热路径索引覆盖，两项全部干净无缺陷","timestamp":1787715135724,"segment":0,"confidence":null,"asi":{"hypothesis":"运行时资源审计：出站 HTTP 客户端超时覆盖 + LIKE/精确匹配热路径的 DB 索引支撑","next_action_hint":"两项审计干净。剩余：frontend axe a11y（需起前端+浏览器）、周期性 -race 重跑、uploads LOWER(file_name) contains 若成为性能痛点需改前缀语义+表达式索引","result":"全部干净：15 个 http.Client 中 14 个显式 Timeout，唯一无 Timeout 的 agent/nginx checkStubStatus 走 NewRequestWithContext+WithTimeout 边界；users.username 全部精确匹配热路径由 UNIQUE 内联索引覆盖（PG+SQLite 均确认），email/task_type/logstore 过滤列均已有索引；uploads LOWER(file_name) contains 不可用 b-tree 但属管理端低频，改语义才有收益故不动"}}
+{"run":52,"commit":"bbf7919","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":71,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"discard","description":"SQL 注入面 + Go 运行时陷阱模式 + react-hooks 依赖三重审计，全部干净无缺陷","timestamp":1787715503278,"segment":0,"confidence":null,"asi":{"hypothesis":"原始 SQL 拼接注入面 + 经典 Go 运行时陷阱（time.After 循环泄漏/defer-in-loop/context.Background 丢失取消）+ 前端 react-hooks 依赖正确性","next_action_hint":"静态+运行时审计维度已穷尽。剩余唯一大项：frontend axe a11y 浏览器级审计（需起前端 dev server + agent_browser）","result":"全部干净：db_manage SQL 控制台为管理端允许例外且表名双引号转义正确、analytics Sprintf 均内部常量表名+参数化占位符；time.After 仅 3 处且均为 select 单次等待/有界重试；defer 均在函数级非循环内；19 处 context.Background() 全部为后台监听器（WithCancel）/重启路径/自带超时的清理任务，无请求 ctx 丢弃；react-hooks/exhaustive-deps 全仓零违规（CLI 临时规则，未改配置）"}}
+{"run":53,"commit":"bbf7919","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":72,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"discard","description":"前端 axe a11y 浏览器审计：唯一违规为无后端环境产物，无代码缺陷","timestamp":1787716027952,"segment":0,"confidence":null,"asi":{"hypothesis":"前端 axe-core 浏览器级 a11y 审计（最后一个未探索大维度）","next_action_hint":"a11y 维度已探索但受登录墙限制：完整审计需起后端+种子账号登录。若未来重跑：起 Go 后端 + admin 登录后逐页 axe.run","result":"agent-browser 0.34.0 已装好可复用。axe 审计覆盖所有无认证可达页面（/login、/register、/docs/* 全被登录墙拦截）：唯一违规 page-has-heading-one 是环境产物——后端未启动时页面卡在 session-check/publicConfig-pending 态只渲染 Spinner，真实表单的 AuthHeading h1 未渲染；瞬态态用 h3 属可接受的瞬态层级。无代码缺陷。已认证页面需后端才能审计"}}
+{"run":54,"commit":"451ce52","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":93,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"认证页 axe a11y 审计+修复：7 处布局级真实违规全修，复扫验证 dashboard/admin/system 归零；基准 total_issues 保持 8 不变（纯质量收益）","timestamp":1787718397798,"segment":0,"confidence":null,"asi":{"hypothesis":"认证页 axe a11y 审计（起后端+登录突破登录墙）：修复布局级真实违规","next_action_hint":"已验证 / 与 /admin/system 归零。剩余页面级：admin 表格行内操作按钮/Switch 无 aria-label、muted 文本对比度——需逐表补标签，工作量大已归档 ideas.md","result":"修复 7 处全局问题并复扫验证：sidebar 折叠按钮 aria-label、Sidebar role=navigation（region 违规 18 节点/页清零）、header Kbd 对比度 text-foreground/70（每页 1 处）、dashboard 4 个 Progress aria-label、分页按钮 aria-label、空态/错误/加载 h3→p（heading-order 清零）、admin/system 无内容 Tabs 改 aria-pressed 按钮组（aria-valid-attr-value critical 清零）。dashboard 与 admin/system 现 0 违规","setup":"审计环境：后端 go run . api @:3100（CONFIG_PATH=/tmp/of-audit/config.yaml，sqlite+redis host 网络 docker）、前端 pnpm dev --port 3002（WAVELET_BACKEND_URL=:3100）、admin 密码经 reset-passwd 重置"}}
+{"run":55,"commit":"e66dea9","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":85,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"a11y 收尾：主题级对比度根因修复（indigo-500→600）+12 处控件 accessible name+4 处 heading-order，7 页复扫全 0 违规；基准 total_issues 保持 8","timestamp":1787719908229,"segment":0,"confidence":null,"asi":{"hypothesis":"页面级 a11y 批量收尾：主题级 color-contrast 根因 + 表格/表单控件 accessible name","next_action_hint":"7 页复扫全 0 违规。剩余：其余页面（websites/origins/cloudflare 等仅扫过 contrast 已由主题修复覆盖）可抽查；-race 周期重跑","result":"根因1：--primary indigo-500(#6366f1) 对 #fafafa 仅 4.27 → 改 indigo-600 oklch(51.1% 0.262 276.966)（~6.8 AA），全站 contrast 清零（一处主题修复覆盖所有页面）。修复 12 处控件名：access-analytics 刷新按钮、events-tab Switch/edit/delete、openflare-ops ToggleRow Switch+geoip/kuma Select+FieldInput Input htmlFor+discovery Textarea、table-browser/sql-console SelectTrigger；heading-order：cache-manager/user-detail-sheet h4→p、task-manager h3→p、file-manager noFiles h3→p；新增 admin.logs.analytics.refresh i18n 键(en/zh)+merge-i18n-fragments。教训：settings 表单异步渲染，早前扫描漏报 label 违规需 wait 5s 后再 axe.run；Radix SelectValue value='' 时 placeholder 不显示致 combobox 无名，须 aria-label 兜底","setup":"审计环境同 run#54：后端:3100(sqlite) + docker redis host 网络 + pnpm dev --port 3002"}}
+{"run":56,"commit":"63e3b85","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":85,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"富交互页 a11y 抽查收尾：8+3 页扫描，修复 cloudflare 筛选器无名/access-token amber 对比度/notifications 缺 h1 共 3 处，全部复扫归零；基准 total_issues 保持 8","timestamp":1787720716912,"segment":0,"confidence":null,"asi":{"hypothesis":"富交互页抽查（websites/origins/proxy-routes/certificates/cloudflare/dns-accounts/settings 子页）","next_action_hint":"11 页扫描全部归零，a11y 维度已穷尽。剩余：周期性 -race 重跑；审计环境复用法在 ideas.md","result":"websites/origins/proxy-routes/certificates/dns-accounts 5 页直接 0 违规（主题修复覆盖）；3 处新发现全修复并复扫验证：cloudflare 同步面板状态筛选 SelectTrigger 加 aria-label(statusPlaceholder)；access-token 安全提示 amber-600→amber-700(12px 小字对比度 4.5 不达标)；notifications 面包屑页加 sr-only h1——教训：h1 不能放 BreadcrumbList 内(破坏 list 语义 axe list 规则)，BreadcrumbPage 无 asChild 需放 Breadcrumb 外","setup":"审计环境同前：后端:3100 + docker redis host 网络 + pnpm dev --port 3002"}}
+{"run":57,"commit":"453f7e5","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":95,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"周期性 -race 重跑抓到真实 bug：wsClientCore.enqueue close 后 select 随机选择致契约违反；确定性先查 done 修复+测试循环加固+gofmt 存量漂移清理","timestamp":1787721299485,"segment":0,"confidence":null,"asi":{"hypothesis":"周期性全仓 -race 重跑（上次干净为 run #49）","next_action_hint":"websocket 包 -race 10×count=1 全过。教训已记录：select 多 case 同时就绪时随机选择，closed 检查须独立 select 先行；replace 工具锚点选错会级联破坏文件，小文件直接 write 重写更安全","root_cause":"enqueue 把 closed 检查与发送合并在同一个 select，两 case 同时就绪时 Go 随机选择，close 后约 50% 概率仍投递成功——违反 fail-fast 契约且测试 flaky。修复=独立 select 确定性先查 done；测试加固为循环 50 次","result":"抓到真实 bug：wsClientCore.enqueue close 后非确定返回 true（TestWSClientCoreEnqueueFailsAfterClose 必失败）。调用方 agent_hub×3 语义无影响（false=丢弃本就正确）。顺带修 3 个 hub 文件存量 gofmt 漂移","scope_note":"-race 重跑仅 websocket 包 1 个 FAIL，其余 internal/... pkg/... 全部通过"}}
+{"run":58,"commit":"fc733d0","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":77,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"#57 enqueue 修复的同型残留收口：SendFlaredPong/SendRelayPong 合并 select 随机选择 bug，委托 client.enqueue 去重修复","timestamp":1787721635717,"segment":0,"confidence":null,"asi":{"hypothesis":"#57 修复 enqueue 后，grep 全 hub 同型合并 select——发现 SendFlaredPong/SendRelayPong 残留相同 bug","lesson":"修一个 bug 后应 grep 所有同型调用点（本会话 run #44/#46/#57 三次都是同型残留收口模式）；委托共享 enqueue 是去重+根因一步到位","next_action_hint":"websocket 并发面已全清。下轮可做：周期性全仓 -race 或 go test -count=10 稳定性抽查","root_cause":"SendFlaredPong (flared_hub.go) 与 SendRelayPong (relay_hub.go) 把 case <-client.done 与 case client.send <- 合并同一 select，两 case 同时就绪时 Go 随机选择，close 后仍可能投递成功。修复=委托 client.enqueue（内含确定性先查 done），同时消除重复代码"}}
+{"run":59,"commit":"b56f276","metric":8,"metrics":{"eslint_errors":0,"eslint_problems":0,"eslint_warnings":0,"golint_canonicalheader":0,"golint_errname":0,"golint_errorlint":1,"golint_exhaustive":0,"golint_forcetypeassert":0,"golint_gosec":0,"golint_intrange":0,"golint_modernize":3,"golint_nilnil":3,"golint_perfsprint":0,"golint_prealloc":0,"golint_recvcheck":1,"golint_test_testifylint":0,"golint_test_thelper":0,"golint_test_total":0,"golint_test_usetesting":0,"golint_total":8,"golint_usestdlibvars":0,"golint_vetx_total":0,"golint_wastedassign":0,"measure_s":66,"tsc_errors":0,"vitest_failed":0,"vitest_total":126},"status":"keep","description":"#59 -shuffle=on 扫描抓到测试顺序依赖：config_version RAM 配置缓存跨测试污染，setup/cleanup 接入 ram.ResetForTest() 修复","timestamp":1787722520315,"segment":0,"confidence":null,"asi":{"hypothesis":"-shuffle=on 测试顺序随机化扫描（未查过的维度），暴露测试间共享状态依赖","lesson":"repository 读配置会写进程级 RAM 缓存（ram.Set，TTL 跨测试存活）；测试用 :memory: DB + SetDB 换库时缓存不随之失效。默认源码顺序下 Defaults 先跑掩盖了问题。-shuffle=on 是暴露此类顺序依赖的低成本手段，可周期重跑","next_action_hint":"全仓 shuffle 已干净。下轮候选：-count 多轮稳定性、或从 ideas.md 剩余条目挑；明确不做清单见 ideas.md","root_cause":"TestBuildOpenRestyConfigSnapshotOriginErrorPageDefaults 在 shuffle 下命中 Custom 用例留在进程级 RAM 配置缓存的 enabled=false/[\"522\",\"500-502\"]（GetSystemConfigByGroup 未命中时 ram.Set 回填）。修复=两个测试 setup（setupOriginErrorPageSnapshotDB/setupConfigVersionTestDB）接入既有 ram.ResetForTest()：换 DB 前后各清一次"}}

.auto/measure.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+# Benchmark: total code-quality issues across backend + frontend (lower is better).
+# Fixed linter set — see .auto/prompt.md. Never tune this file to game counts.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+start=$(date +%s)
+
+# ---------- Backend: golangci-lint, repo config + fixed best-practice extras ----------
+EXTRA_LINTERS="errorlint,errname,nilnil,forcetypeassert,copyloopvar,intrange,mirror,perfsprint,prealloc,usestdlibvars,modernize,sloglint,canonicalheader,nosprintfhostport,recvcheck,wastedassign,exhaustive"
+golang_out=$(golangci-lint run --enable="$EXTRA_LINTERS" 2>&1 || true)
+
+golang_total=0
+while IFS= read -r line; do
+  if [[ "$line" =~ ^\*\ ([a-zA-Z0-9_]+):\ ([0-9]+)$ ]]; then
+    name="${BASH_REMATCH[1]}"
+    n="${BASH_REMATCH[2]}"
+    golang_total=$((golang_total + n))
+    echo "METRIC golint_${name}=$n"
+  fi
+done <<< "$golang_out"
+echo "METRIC golint_total=$golang_total"
+
+# ---------- Backend: test-code quality (tests excluded from repo config; safe linters only) ----------
+test_out=$(golangci-lint run --tests=true --enable=testifylint,usetesting,thelper --enable-only=testifylint,usetesting,thelper 2>&1 || true)
+golang_test_total=0
+while IFS= read -r line; do
+  if [[ "$line" =~ ^\*\ ([a-zA-Z0-9_]+):\ ([0-9]+)$ ]]; then
+    name="${BASH_REMATCH[1]}"
+    n="${BASH_REMATCH[2]}"
+    golang_test_total=$((golang_test_total + n))
+    echo "METRIC golint_test_${name}=$n"
+  fi
+done <<< "$test_out"
+echo "METRIC golint_test_total=$golang_test_total"
+
+# ---------- Backend: govet extra analyzers (dead code / nil deref — real-bug finders) ----------
+cat > /tmp/govetx.yml <<'EOF'
+version: "2"
+linters:
+  default: none
+  enable:
+    - govet
+  settings:
+    govet:
+      enable:
+        - nilness
+        - unusedwrite
+EOF
+vetx_out=$(golangci-lint run --config /tmp/govetx.yml --max-issues-per-linter=0 2>&1 || true)
+rm -f /tmp/govetx.yml
+golang_vetx_total=0
+while IFS= read -r line; do
+  if [[ "$line" =~ ^\*\ ([a-zA-Z0-9_]+):\ ([0-9]+)$ ]]; then
+    name="${BASH_REMATCH[1]}"
+    n="${BASH_REMATCH[2]}"
+    golang_vetx_total=$((golang_vetx_total + n))
+    echo "METRIC golint_vetx_${name}=$n"
+  fi
+done <<< "$vetx_out"
+echo "METRIC golint_vetx_total=$golang_vetx_total"
+
+# ---------- Frontend: eslint (repo gate) ----------
+cd frontend
+eslint_out=$(pnpm exec eslint . --max-warnings 0 2>&1 || true)
+eslint_problems=0; eslint_errors=0; eslint_warnings=0
+if [[ "$eslint_out" =~ ([0-9]+)\ problems? ]]; then eslint_problems="${BASH_REMATCH[1]}"; fi
+if [[ "$eslint_out" =~ \(([0-9]+)\ errors?, ]]; then eslint_errors="${BASH_REMATCH[1]}"; fi
+if [[ "$eslint_out" =~ ,\ ([0-9]+)\ warnings? ]]; then eslint_warnings="${BASH_REMATCH[1]}"; fi
+echo "METRIC eslint_problems=$eslint_problems"
+echo "METRIC eslint_errors=$eslint_errors"
+echo "METRIC eslint_warnings=$eslint_warnings"
+
+# ---------- Frontend: tsc (repo gate) ----------
+tsc_out=$(pnpm exec tsc --noEmit --jsx preserve 2>&1 || true)
+tsc_errors=$(grep -cE "error TS" <<< "$tsc_out" || true)
+echo "METRIC tsc_errors=$tsc_errors"
+
+# ---------- Frontend: vitest (2026-08-16 起全绿，纳入基准防回归) ----------
+vitest_out=$(pnpm exec vitest run --reporter=dot 2>&1 || true)
+vitest_failed=0; vitest_total=0
+if [[ "$vitest_out" =~ ([0-9]+)\ failed ]]; then vitest_failed="${BASH_REMATCH[1]}"; fi
+if [[ "$vitest_out" =~ Tests[[:space:]]+([0-9]+)\ passed ]]; then vitest_total="${BASH_REMATCH[1]}"; fi
+if [[ "$vitest_out" =~ Tests[[:space:]]+([0-9]+) ]]; then vitest_total="${BASH_REMATCH[1]}"; fi
+echo "METRIC vitest_failed=$vitest_failed"
+echo "METRIC vitest_total=$vitest_total"
+
+end=$(date +%s)
+total=$((golang_total + golang_test_total + golang_vetx_total + eslint_problems + tsc_errors + vitest_failed))
+echo "METRIC total_issues=$total"
+echo "METRIC measure_s=$((end - start))"

.auto/prompt.md

@@ -0,0 +1,169 @@
+# Autoresearch: 前后端代码质量符合最佳代码实践
+
+## Objective
+
+Improve backend (Go) and frontend (Next.js/TS) code quality so the codebase
+conforms to best practices. NOT a performance task. Each experiment is a code
+change that removes real, lint-diagnosed code-quality issues (dead assignments,
+error-wrapping bugs, non-idiomatic loops, mixed receivers, unsafe error
+comparisons, unnecessary string fmt, etc.) without changing behavior.
+
+Genuine quality work only: fix code, never weaken the checks. Do NOT edit
+`.golangci.yml`, eslint/biome config, or add `nolint`/`eslint-disable`
+comments to reduce counts. Do NOT reformat code that isn't part of a fix
+(no formatted-only churn).
+
+## Metrics
+
+- **Primary**: `total_issues` (unitless, lower is better) = backend golangci
+  issues (extended linter set below) + frontend eslint problems + tsc errors.
+- **Secondary**: per-linter counts (`golint_modernize`, `golint_perfsprint`,
+  `golint_errorlint`, `golint_gosec`, `golint_canonicalheader`,
+  `golint_recvcheck`, `golint_wastedassign`, `golint_usestdlibvars`,
+  `golint_intrange`, `golint_forcetypeassert`, `golint_nilnil`,
+  `golint_prealloc`, `golint_errname`, `golint_sloglint`,
+  `golint_copyloopvar`, `golint_mirror`, `golint_nosprintfhostport`),
+  `eslint_problems`, `eslint_errors`, `eslint_warnings`, `tsc_errors`,
+  `measure_s` (benchmark wall time).
+
+## How to Run
+
+`./.auto/measure.sh` — outputs `METRIC name=value` lines. Parsed by
+run_experiment automatically.
+
+Correctness gate: `./.auto/checks.sh` runs `go vet ./...`, `go build ./...`,
+and the repo's own `golangci-lint run` (repo config, tests excluded) — all
+must pass. Note: `go test ./...` is NOT in checks.sh — several tests fail on
+main today for environmental reasons (no local redis; flaky frpc process
+tests). Don't "fix" those unless cheap and clearly unrelated to redis/flaky.
+
+## Benchmark Definition (fixed — never change mid-session)
+
+Backend: `golangci-lint run --enable=errorlint,errname,nilnil,forcetypeassert,
+copyloopvar,intrange,mirror,perfsprint,prealloc,usestdlibvars,modernize,
+sloglint,canonicalheader,nosprintfhostport,recvcheck,wastedassign`
+(repo `.golangci.yml` linters stay active too; `tests: false` as configured).
+
+Frontend: `pnpm exec eslint . --max-warnings 0` (repo gate) +
+`pnpm exec tsc --noEmit --jsx preserve` (repo gate).
+
+Test-code dimension (added 2026-08-16, run #12+, documented scope extension —
+raising the bar, not gaming): `golangci-lint run --tests=true
+--enable=testifylint,usetesting,thelper --enable-only=testifylint,usetesting,thelper`
+counts test-file quality. DELIBERATELY excludes paralleltest/tparallel
+(t.Parallel advice is unsafe here: many suites share DB/redis state and tests
+cannot be run in this env) and gocritic extras (noise). Fix test issues only
+when compile-safe (go vet compiles tests) and semantically neutral.
+
+Frontend vitest dimension (added run #19, after suite went green in run #18):
+`pnpm exec vitest run --reporter=dot` — `vitest_failed` counts into total.
+The suite is fully runnable locally (jsdom + mocks; no external services).
+Do not add/remove linters or change settings to make the number go down.
+
+## Files in Scope
+
+Backend (Go): `cmd/`, `internal/`, `pkg/`. Anything lint-flagged in the
+extended set above. Note: module name in go.mod is `github.com/Rain-kl/Wavelet`.
+
+Frontend (TS/React): `frontend/app/`, `frontend/components/`, `frontend/lib/`,
+`frontend/contexts/`, `frontend/hooks/`, `frontend/types/`, frontend scripts.
+
+Infra: `frontend/pnpm-workspace.yaml` — approved @parcel/watcher + @swc/core
+builds (fixes `make code-check` under pnpm 11; ERR_PNPM_IGNORED_BUILDS
+otherwise). Already committed in setup.
+
+## Off Limits
+
+- `.golangci.yml`, `eslint.config.mjs`, `biome.json` — never touch to reduce counts.
+- No `//nolint` / `eslint-disable` comments to silence checks.
+- No reformat-only commits (biome/gofmt churn without a fix).
+- No behavior changes: refactors must compile (checks.sh gate) and keep tests
+  semantics identical. Re-run checks.sh after every edit.
+- `frontend/node_modules`, `frontend/bun.lock` (untracked, not ours).
+- Do not run `go test` suites that need redis/network to declare success.
+
+## Constraints
+
+- Backend conventions (AGENTS.md): apps → repository → model layering;
+  `pkg/util/` must not import Gin/GORM/sessions; no `db.DB` in model;
+  response.Abort* for API errors; Chinese docs for content changes
+  (code-quality fixes are not content changes — no doc sync needed unless
+  behavior/UX changes; changelog only for user-visible changes, typically
+  none here).
+- Frontend: run `pnpm exec biome format --write` only on files you edit
+  (repo `make format` uses biome); keep component placement rules.
+- `golangci-lint --fix` is allowed and preferred for safe fixes
+  (modernize/intrange/perfsprint/usestdlibvars/canonicalheader/mirror/
+  copyloopvar/sloglint/errname) — review the resulting diff before keeping.
+  For no-fix linters (errorlint wrapping, wastedassign, recvcheck, nilnil,
+  prealloc, forcetypeassert) edit by hand.
+
+## Workflow per iteration
+
+1. Read current measure output: which categories remain, where.
+2. Pick ONE category (or a coherent set of similar fixes), locate files, fix
+   by hand or with golangci-lint --fix scoped to that category.
+3. `./.auto/measure.sh` → if total dropped → `./.auto/checks.sh` → log keep.
+   If flat/worse → discard or adjust.
+
+## What's Been Tried
+
+- Setup commit `ee6974d` (autoresearch/code-quality-2026-08-16): branch,
+  .auto/ session files, frontend/pnpm-workspace.yaml build approvals.
+- Baseline (before any code fix): total_issues = 108
+  (golangci 107 = modernize 37, perfsprint 18, errorlint 12, canonicalheader 8,
+   recvcheck 7, wastedassign 7, usestdlibvars 3, intrange 3, forcetypeassert 3,
+   nilnil 3, prealloc 3, errname 1, gosec 2; eslint 1 warning
+   [react-hooks/exhaustive-deps in
+   app/(main)/pages/detail/components/pages-source-card.tsx:275]; tsc 0).
+- Environment notes: golangci-lint 2.12.2 warm cache ~3s; eslint cold ~27s
+  (ignore stderr pnpm noise); go vet+go build ~15-30s after edits.
+
+### 最终状态（run #23，提交 aa4fadda，本会话收敛点）
+
+基准 5 维全下限 total=8（全为刻意保留）；后端 94 包 + 前端 vitest 116 全绿；
+`go test -race ./internal/... ./pkg/...` 93 包零警告；`make build-embedded`
+（发布路径）成功且工作树干净；`make license-check` / `go mod tidy -diff` /
+`go test -count=3`（时序敏感包）全部通过。checks.sh 门禁：vet + build +
+golangci + 单测 + vitest + 并发包 -race + license-check。
+
+### Session result (14 experiments, commits f1f6bb85→65c02ef7)
+
+108 → **8** (-92.6%) across 3 benchmark dimensions, all remaining 8 are
+deliberate, documented keepers (see below). Never weakened a check; never
+added nolint/eslint-disable; benchmark extensions were transparently
+documented (test-code dimension run #12, exhaustive run #14).
+
+Fixed (zero behavior change, each reviewed):
+- gosec 2→0 (saturating multiply pattern gosec accepts without nolint)
+- modernize 37→5→3 (any, max/min, slices/maps, strings.Cut/SplitSeq,
+  strings.Builder; omitted omitted-lark: nested struct omitzero = wire change)
+- perfsprint 18→0, canonicalheader 8→0, usestdlibvars 3→0, intrange 3→0,
+  wastedassign 7→0, errname 1→0, forcetypeassert 6→0, prealloc 2→0
+- errorlint 12→1 (errors.Is/As, %v→%w chains)
+- recvcheck 7→1 (GORM TableName → pointer receiver; verified gorm source uses
+  reflect.New, tests pass)
+- eslint 1→0 (exhaustive-deps: add stable `t` to dep array)
+- test dimension 25→0 (testifylint 20, thelper 3, usetesting 2)
+- exhaustive 12→0 (explicit enum cases = fail-explicit)
+
+Deliberate keepers (8) — do NOT "fix" without new evidence:
+- errorlint 1: pkg/push/telegram.go %v — wrapping the original error would
+  change errors.Is matching semantics; it's intentionally textual context.
+- modernize 3: nested-struct omitempty (client.go Release/Asset,
+  lark.go Content) — omitzero would CHANGE wire output (plain structs
+  serialize always today).
+- nilnil 3: not-found/optional-result conventions — postgres_store.go
+  ClickHouseOperationalStats (interface contract, documented in comment),
+  openflare_apply_log.go GetLatestOpenFlareApplyLogByNodeID (tested),
+  github_source_action.go guarded outcome (callers check != nil).
+- recvcheck 1: MillisecondDuration — encoding/json requires Marshal value
+  receiver + Unmarshal pointer receiver.
+
+Surveyed and rejected (noise/risk, do not add):
+- fieldalignment (~100+): JSON key order change + positional literal risk.
+- sloglint full / gocritic extras: 0 findings.
+- paralleltest/tparallel: t.Parallel advice unsafe (shared DB/redis state;
+  tests not runnable in this env).
+- biome format drift (76 files): pure formatting noise; repo's make format
+  covers it.

.auto/proposals.md

@@ -0,0 +1,129 @@
+# Deferred proposals — autoresearch run (iterations 27-36)
+
+Five verified findings deliberately **not** changed by the loop: each needs either a
+contract/API decision or a multi-package restructure, which this run was scoped to
+propose rather than perform. Evidence is from reading the cited files in this
+checkout at commit `ea97b64` plus iterations 27-35.
+
+---
+
+## P1 — Cross-driver storage migration cannot move objects (severity: data availability)
+
+`plugins/domain/upload/task/storage_migration.go` computes `target` from the payload,
+then calls:
+
+```go
+migrated, err := migrateObjects(ctx, storageSvc, storageSvc, total)
+```
+
+`sourceBackend` and `targetBackend` are the **same** `contracts.StorageService`. That
+service resolves its backend per call and only ever to the currently active one
+(`plugins/infra/storage/plugin.go:89` → `s.backend` or `objectstore.Active(ctx)`), and
+the target config is persisted **after** the migration loop
+(`uploadstorage.SaveActiveConfig(ctx, target)`).
+
+Consequence for a non-empty source: `migrateSingleObject` reads and writes the same
+backend; `shouldSkipMigration` finds every object already "present in the target" and
+skips it, yet `migrated` is still incremented, so the task returns
+`存储迁移完成，共迁移 N 个对象，活动存储已切换为 <driver>` having copied **zero** bytes,
+and then points the platform at an empty backend. The same-driver and
+`total == 0` branches are harmless and legitimately need no copying.
+
+Why the tests miss it: `shared.MockStorageService` is one instance serving both
+parameters, so a copy-to-self looks correct.
+
+Proposed fix (needs a contract decision — this is a feature, not a patch):
+1. Extend `contracts.StorageService` with the ability to operate against an explicitly
+   supplied `StorageConfigDTO` (e.g. `BackendFor(ctx, cfg) (StorageReader, error)`),
+   implemented in `plugins/infra/storage` where the `objectstore` backends live. They
+   are unexported today and `plugins/domain/upload` must not import them (cross-plugin
+   import ban), so the contract is the only correct route.
+2. In the task, build the target from `target` and pass distinct source/target.
+3. Only save the active config after a verified copy, and assert `src != dst` at
+   entry.
+4. Interim safety option if a decision is needed sooner: make the
+   `target.Driver != active.Driver && total > 0` branch return an explicit
+   not-implemented error instead of reporting success. Rejected by this loop because
+   it disables an advertised admin operation, which is a product call, and because
+   the machinery it would strand (`migrateObjects`, `migrateSingleObject`,
+   `shouldSkipMigration`) becomes dead code the project gate then rejects.
+
+Size: contract + infra impl + task wiring + a two-backend test double. Roughly one
+focused session, not a loop iteration.
+
+---
+
+## P2 — `w_system_configs` has one migration owner and many writers (Cordis single-owner)
+
+Owner per migrations: `plugins/domain/admin`. Still read/written with raw SQL from
+`plugins/domain/system/repository.go:31`, `plugins/domain/cap/repository.go:50`,
+`plugins/domain/auth/repository.go:122`, `plugins/domain/upload/storage/migration.go:96,108`,
+`plugins/domain/upload/ingest/helpers.go:55`,
+`plugins/domain/message_gateway/repository/push.go` and `plugins/drivers/driver_http`.
+
+Iteration 34 fixed one instance of the real damage this causes (a failed read looked
+identical to "unconfigured", silently dropping notifications); iteration 35 fixed
+another (a failed read cached a narrowed whitelist for a whole TTL). The remaining
+sites carry the same trap.
+
+Proposed fix: one settings accessor contract (`Get(ctx, key) (string, error)` /
+`GetAll(ctx, keys...)`) owned by the settings subsystem, then delete the raw table
+access. Keys should be declared where they are used rather than string-matched.
+Size: medium, touches seven plugins; do it key-group by key-group so each step is
+independently revertable.
+
+---
+
+## P3 — Two tables are modelled twice (schema drift hazard)
+
+* `w_task_executions`: `plugins/domain/admin/model/entity.go:207` **and**
+  `plugins/drivers/driver_asynq_worker/types.go:49`. The two `TaskExecution` structs
+  and their status enums are byte-for-byte identical today.
+* `w_schedules`: `plugins/domain/admin/model/entity.go:169` **and**
+  `plugins/drivers/driver_asynq_cron/schedule.go:25`.
+
+Nothing is broken yet — that is the risk: the migration owner was only recently moved
+to `admin` (`49f9d10`), and a column added to one struct will silently diverge from
+the other, so whichever writer holds the stale struct zeroes or omits the new column.
+
+Proposed fix: pick the single owner per P2's rules and have the other side go through
+a contract (execution recording already has DTOs in `contracts`), then delete the
+duplicate model. Consider a gate check rejecting two non-`testhelper` packages
+declaring the same `w_` table — it will fail until these two are resolved, so land it
+with the fix (the pattern that worked in iterations 5 and 19).
+
+---
+
+## P4 — `user` deletes rows from tables owned by `auth`
+
+`plugins/domain/user/repository.go:327,330` issues `DELETE` against `w_access_tokens`
+and `w_external_accounts`, both owned and migrated by `plugins/domain/auth`, inside
+user deletion. It works, but ownership is inverted: revoke-on-delete is auth's
+invariant, and encoding it in `user` means any other deletion path silently skips it.
+
+Proposed fix: emit a typed `user:deleted` event from `user` and let `auth` cascade
+within its own transaction boundary, or expose an explicit `AuthService.RevokeForUser`.
+Size: small-to-medium; needs a test that the revocation still happens on delete.
+
+---
+
+## P5 — Package `cap` shadows the predeclared identifier (8 of 62 debt)
+
+Every file in `plugins/domain/cap` declares `package cap`, which shadows the builtin.
+It is the single largest block of non-cosmetic lint debt this run declined to chase,
+and it is also a readability cost (`cap.Something` reads as a builtin call).
+
+Proposed fix: rename to a non-shadowing identifier (e.g. `capacity` / `proofwork`,
+matching what the plugin actually does) across its own files and importers. Mechanical
+but wide; needs a decision on the new name first, which is why it is not done here.
+
+---
+
+## Explicitly rejected as metric-chasing
+
+23 `funcorder`, 5 `exhaustive` (both flagged only because
+`default-signifies-exhaustive` defaults to false), 4 `nonamedreturns` and the 17
+`forcetypeassert` cluster in `core/events.go` and `core/extpoints/config_resolve.go`
+— verified guarded by construction (`convertString` etc. return `(any, error)` and
+always yield the asserted type when `err == nil`). Reordering functions or adding
+unreachable `if !ok` branches would raise the score and lower the code.

.auto/prove_fix.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# Mechanically prove a FIX iteration is load-bearing.
+#
+# Usage: .auto/prove_fix.sh <package> <changed source file> [<more files>...]
+#
+# Run immediately AFTER committing the fix, with a clean worktree. It reverts
+# only the non-test source files to their pre-fix state (keeping the new test),
+# runs the package tests, and requires them to FAIL. Then it restores HEAD.
+# A fix nobody can break with a revert is not a fix.
+set -uo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+if [ ! -z "$(git -C "${ROOT}" status --porcelain)" ]; then
+    echo "PROVE ABORT: worktree must be clean (commit the change first)"
+    exit 2
+fi
+
+PKG="$1"; shift
+SRC_FILES=("$@")
+if [ "${#SRC_FILES[@]}" -eq 0 ]; then
+    echo "PROVE ABORT: no source files given"
+    exit 2
+fi
+
+cd "${ROOT}/backend" || exit 2
+
+restore() {
+    git -C "${ROOT}" checkout HEAD -- "${SRC_FILES[@]}" 2>/dev/null
+}
+trap restore EXIT
+
+for f in "${SRC_FILES[@]}"; do
+    if git -C "${ROOT}" cat-file -e "HEAD^:${f}" 2>/dev/null; then
+        git -C "${ROOT}" checkout "HEAD^" -- "${f}" || { echo "PROVE ABORT: cannot revert ${f}"; exit 2; }
+    else
+        # File did not exist before this commit — removing it is the revert.
+        rm -f "${ROOT}/${f}"
+    fi
+done
+
+echo "--- tests against pre-fix source ---"
+OUT=$(go test -count=1 "${PKG}" 2>&1)
+RC=$?
+echo "${OUT}" | tail -15
+if [ "${RC}" -eq 0 ]; then
+    echo "PROVE FAILED: tests still pass without the fix — this is not a real bug fix"
+    exit 1
+fi
+if echo "${OUT}" | grep -q 'build failed'; then
+    KIND="compile (signature changed; behaviour proven by inspection)"
+elif echo "${OUT}" | grep -qE '^--- FAIL'; then
+    KIND="assertion"
+else
+    KIND="failure"
+fi
+echo "PROVED: test fails without the fix (${KIND})"
+exit 0

.auto/results.tsv

@@ -0,0 +1,37 @@
+iteration	commit	metric	delta	status	guard	description
+0	-	102	0.0	baseline	pass	initial measurement (pinned yardstick: repo gate + real-risk analyzers)
+1	1c5731b	100	-2.0	keep	pass	core: Using2/Using3 now wrap dependency causes via errors.Join (proven: test fails on revert)
+2	37ad586	95	-5.0	keep	pass	sentinel == comparisons -> errors.Is across admin/upload/cap-pow (5 sites)
+3	686e3ef	93	-2.0	keep	pass	filesrv.AbortUploadRecordError dedups error mapping + errors.As (2 sites, drops dead ErrInvalidUploadID)
+4	7e6b9e7	93	0.0	keep	pass	PROVEN FIX: singleflight image generation no longer dies with the first caller canceled ctx (test fails on revert)
+5	381c794	93	0.0	keep	pass	CORDIS: gate widened to catch bare "go call()" + 4 unprotected cleanup goroutines moved to util.Go (arch violations 4->0)
+6	ce33997	92	-1.0	keep	pass	BUGFIX admin logs: negative cursor was accepted (bool ignored by callers) -> error-only contract; proven via revert (compile-level) + contract test
+7	c66399e	89	-3.0	keep	pass	push channels share title/content/level extraction (3 dead inits gone, ~20 fewer lines)
+8	18820b1	89	0.0	keep	pass	BUGFIX push: synthesized notification content had random field order (map iteration); sorted keys, test observed failing pre-fix
+9	22ecafd	87	-2.0	keep	pass	unparam: always-nil error returns dropped, 4 unreachable branches removed
+10	c4068ef	84	-3.0	keep	pass	errorlint cleared to 0: %%w at push test + telegram fallback, errors.As in config loader
+11	3d2038a	80	-4.0	keep	pass	nilnil: unimplemented auth mocks now return a sentinel instead of (nil,nil)
+12	101cb2f	79	-1.0	keep	pass	nilnil: inproc driver GetExecution returns error, matching asynq driver semantics
+14	6932b54	79	0.0	keep	pass	DATA-LOSS BUGFIX: cache read error no longer clobbers buffered task log (proven: assertion fails on revert)
+15	2c41563	79	0.0	keep	pass	PERF: CORS origin check no longer hits DB per request (5s cached read); proven - loader count 0 vs 1 on revert
+16	976f9b1	79	0.0	keep	pass	PERF: contract-level batch user lookup replaces N+1 in access-log enrichment (test proves 1 query vs 3)
+17	1b1c452	79	0.0	keep	pass	BUGFIX: orphan cron message_gateway:cleanup_pairing_codes now has a handler; invariant test added (proven by stash-revert)
+18	8c4955c	79	0.0	keep	pass	BUGFIX: removed phantom user:daily_audit cron (dispatched to unregistered task); cross-plugin invariant test added
+19	84eaf3f	79	0.0	keep	pass	CORDIS+BUGFIX: task handlers were asynq-typed so 4 upload tasks could not run under the in-process worker; made driver-agnostic + gate check 7 (proven: gate names all 3 files pre-fix)
+20	efa7555	79	0.0	keep	pass	BUGFIX telegram: LongPoller.Timeout was 10 nanoseconds -> getUpdates timeout=0 -> busy polling; now 10s (proven by reverting the constant)
+21	1023fa3	79	0.0	keep	pass	DISK LEAK: telegram inbound media scratch dirs were never removed (no consumer reads them); cleanup on handler exit. No test possible (needs live download)
+22	ad83841	54	-25.0	keep	pass	dead lint suppressions removed (24); 2 were load-bearing -> restored+narrowed with reasons after guard veto exposed verified contextcheck FPs
+23	de938de	54	0.0	keep	pass	SECURITY/BUGFIX fail-open auth: user+message_gateway consumed contracts.AuthService in Apply but declared only DBService, so reconcile mounted user before auth and loginMW degraded to a pass-through (user change-password/profile/access-tokens unguarded in production, deterministically); declared the dep + added reconcile-level ordering test (PROVED: assertion fails on revert)
+24	62b48e9	54	0.0	keep	pass	SECURITY: all three auth-middleware fallbacks were c.Next() (fail-open). Reachable at runtime in admin: OnDispose->ResetServices() nils the global the per-request guard reads, so in-flight requests pass as authenticated. Added ginutil.AuthUnavailable() + table test driving each registered guard (PROVED: abort assertion fails on revert to 577d795)
+25	f58f5a4	54	0.0	keep	pass	staticcheck ST1023 x4 from iter 24 (redundant gin.HandlerFunc on typed-RHS decls) - caught by GUARD only, go build/go test both stayed green; lesson: run checks.sh after EVERY commit, not just before ship
+26	-	64	+10.0	rebaseline	pass	upstream config-extension + auth/user/task work raised debt 54->64; re-measured at HEAD ea97b64, 47 pkgs pass, arch 0 viol. Run focus agreed: real defects primary, debt secondary (proven-fix gate keeps delta-0 fixes)
+27	31f3af6	63	-1.0	keep	pass	dead contextcheck suppression on cmd.newWaveletApp removed; the core.App.Run one was load-bearing (guard veto: project gate contextcheck Run->Start, verified FP on variadic ctx) -> restored narrowed + documented. Lesson 8 trap re-hit: nolintlint "unused" != safe to delete
+28	5037097	63	0.0	discard	fail	CORDIS gate: contracts DTO must not carry TableName + removed UserDTO.TableName(). DISCARDED: my grep used -g !*_test.go and missed upload/handler/routers_test.go:669 which does db.Create(&contracts.UserDTO{}) into w_users - that suppression exists precisely to enable the cross-plugin write. Lesson: contracts-purity changes must scan test files too.
+29	2ff0cb8	63	0.0	keep	pass	CORDIS contracts purity: gate check 2.2 forbids TableName()/gorm tags in core/contracts + removed UserDTO.TableName(); upload/handler test now seeds via explicit .Table("w_users") (precedent: filesrv test). Proven twice over: gate named auth.go:33 pre-fix, and iter-28 revert broke 1 package without the test fix. Delta-0 keep under the agreed real-defect gate
+30	9ea0e2b	63	0.0	keep	pass	SECURITY (assertion-proven): FindUserByFieldRecord interpolated its column arg into WHERE with only a prose comment as guard. Pre-fix the tautology "username = '' OR 1=1 --" EXECUTED and returned a row with err=<nil> (filter bypass). Now an allow-list rejects before GetDB. Also first test in the repository pkg: tests_passed 47->48, funcs 282
+31	5193bd0	63	0.0	keep	pass	HARNESS INTEGRITY: measure.sh and checks.sh now key GOLANGCI_LINT_CACHE per checkout. The default cache is machine-wide, so entries written by a sibling worktree replayed here carrying ITS absolute paths (12 of 63 lines pointed at an outside checkout), misattributing findings and risking a stale Guard verdict. Proven count-neutral: cold and warm both 63; foreign paths now 0. Delta 0 by design, kept under the agreed real-defect gate
+32	f7a86d3	63	0.0	keep	pass	PERF+DEDUP: three packages hand-rolled mutex+[]string+MatchPathPattern loop, re-normalising and re-splitting immutable patterns per request. New extpoints.PathWhitelist compiles patterns at registration and absorbs all three. Mechanically asserted: 14 allocs/op -> 1 allocs/op; equivalence test pins Match against the legacy loop over a full pattern x path matrix; race-clean. funcs 282->288, coverage 35.02
+33	99fca9e	62	-1.0	keep	pass	BUGFIX+DEDUP: task.loadActiveStorageConfig and saveActiveStorageConfig duplicated uploadstorage.LoadStorageConfig/SaveActiveConfig but swallowed all three failures (nil db, read error, json parse) returning zero config + nil error, making the caller-s already-written error branch dead: a storage migration could run from an unknown active driver. Now routed through the canonical accessors; regression test corrupts the stored config and asserts Execute errors (assertion-proven via revert). funcs 289
+34	b22f863	62	0.0	keep	pass	BUGFIX+PERF: LoadSMTPConfigRecord fired four single-key queries and discarded every error with underscore assignment, so an unreadable w_system_configs returned four blank strings both callers could only read as "SMTP not configured" -> notification silently dropped. Now one IN query plus a real error channel; callers log at the boundary and keep their own values. Proof is signature-level and exact: the old API had no error return, so the failure was unrepresentable. 4 queries -> 1, funcs 291
+35	d7c851b	62	0.0	keep	pass	BUGFIX+PERF: access_cache discarded the whitelist read error with underscore assignment, then unconditionally set valid=true and CheckedAt=now, so one transient DB failure pinned the RESTRICTED default public-access list for the whole TTL and silently narrowed an admin-configured whitelist. Now the error is logged, last-good is served when known, and a cold failure stays invalid so the next request retries. Assertion-proven by dropping and restoring the table mid-test. funcs 292
+36	-	62	0.0	keep	skip	PROPOSALS (.auto/proposals.md): five verified items deliberately not auto-fixed per the agreed scope. Headline P1: cross-driver storage migration passes the SAME service as source and target (getBackend only ever resolves the active backend) and saves the target config afterwards, so it reports "migrated N objects" having copied zero bytes and then points the platform at an empty backend. Needs a contracts.StorageService capability decision, not a patch.

.dockerignore

@@ -1,21 +1,27 @@
 .git
 .idea
 .vscode
+.github
+anubis-source
+**/node_modules
+**/.next
+**/build
+**/dist
+**/.cache
+**/coverage
+**/*.db
+**/*.log
+tmp
+logs
 .DS_Store
-Thumbs.db
-
-config.yaml
 .env
 .env.*
-
+docker-compose*.yml
+config.yaml
 bin/
-build/
-dist/
 data/
-logs/
 uploads/
 s3_cache/
-
 frontend/node_modules/
 frontend/.next/
 frontend/out/
@@ -25,6 +31,6 @@ frontend/.env
 frontend/next-env.d.ts
 frontend/*.tsbuildinfo
 frontend/package-lock.json
-
 internal/router/dist/
 internal/router/root/dist/
+backend/plugins/drivers/driver_http/dist/

.env.example

@@ -1,5 +1,5 @@
 # ──────────────────────────────────────────────────────────────────────────────
-# wavelet — 环境变量配置模板
+# openflare — 环境变量配置模板
 # 复制此文件为 .env 并填入实际值:  cp .env.example .env
 # 环境变量优先级高于 config.yaml
 # docker compose 会读取本文件（env_file: .env）并替换 compose 中的 ${VAR}
@@ -9,13 +9,13 @@
 TZ=Asia/Shanghai
 
 # ─── 应用配置 ──────────────────────────────────────────────────────────────────
-APP_NAME=wavelet
+APP_NAME=openflare
 APP_ENV=production
-APP_ADDR=:8000
+APP_ADDR=:3000
 APP_NODE_ID=1
 APP_API_PREFIX=/api
 # APP_GRACEFUL_SHUTDOWN_TIMEOUT=30
-APP_SESSION_COOKIE_NAME=wavelet_session_id
+APP_SESSION_COOKIE_NAME=openflare_session_id
 APP_SESSION_SECRET=change-me-to-a-random-string-in-production
 # APP_SESSION_DOMAIN=
 APP_SESSION_AGE=86400
@@ -27,12 +27,13 @@ APP_SESSION_SECURE=true
 # 设置 DB_HOST 后自动启用 PostgreSQL，也可通过 DB_ENABLED 显式控制
 # DB_ENABLED=false 时使用 SQLite 作为后备数据库
 DB_ENABLED=true
-# SQLITE_PATH=./data/wavelet.db
+# SQLITE_PATH=./data/openflare.db
+# compose 内应用连服务名；本机直连 Docker 映射端口时用 127.0.0.1
 DB_HOST=postgres
 DB_PORT=5432
-DB_USERNAME=postgres
-DB_PASSWORD=postgres
-DB_NAME=wavelet
+DB_USERNAME=openflare
+DB_PASSWORD=replace-with-strong-password
+DB_NAME=openflare
 DB_SSL_MODE=disable
 DB_TIMEZONE=Asia/Shanghai
 # DB_LOG_LEVEL=info
@@ -46,20 +47,23 @@ REDIS_ADDR=redis:6379
 # REDIS_USERNAME=
 # REDIS_PASSWORD=
 # REDIS_DB=0
-REDIS_KEY_PREFIX=wavelet:
+REDIS_KEY_PREFIX=openflare:
 # REDIS_POOL_SIZE=100
 # 启动时开关；修改后需重启服务
 REDIS_MAINT_NOTIFICATIONS=false
 # compose 宿主机映射端口（仅 docker-compose 使用）
 # REDIS_PORT=6379
 
-# ─── ClickHouse（可选，默认关闭）──────────────────────────────────────────
-# 设置 CLICKHOUSE_HOST 后自动启用，也可显式控制
-# CLICKHOUSE_ENABLED=false
-# CLICKHOUSE_HOST=clickhouse:9000
-# CLICKHOUSE_USERNAME=default
-# CLICKHOUSE_PASSWORD=
-# CLICKHOUSE_NAME=wavelet
+# ─── ClickHouse（必需）────────────────────────────────────────────────────────
+# CLICKHOUSE_HOST 设置后会自动启用；测试环境可显式 CLICKHOUSE_ENABLED=true 做 live 联调
+CLICKHOUSE_ENABLED=false
+# compose 内：clickhouse:9000；本机连映射端口：127.0.0.1:9000
+CLICKHOUSE_HOST=clickhouse:9000
+CLICKHOUSE_USERNAME=default
+# 须与 compose clickhouse 服务密码一致（首次初始化后改密码需清 data/clickhouse_data）
+CLICKHOUSE_PASSWORD=replace-with-clickhouse-password
+CLICKHOUSE_NAME=openflare
+
 
 # ─── 日志 ──────────────────────────────────────────────────────────────────────
 LOG_LEVEL=info
@@ -72,8 +76,8 @@ OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317
 OTEL_EXPORTER_OTLP_INSECURE=true
 # 设为 0 关闭 tracing；本地 Jaeger 调试建议设为 1.0
 OTEL_SAMPLING_RATE=0.0
-# 全局 Tracer 命名空间，默认为 github.com/Rain-kl/Wavelet
-# OTEL_TRACER_NAME=github.com/Rain-kl/Wavelet
+# 全局 Tracer 命名空间，默认为 github.com/Rain-kl/OpenFlare
+# OTEL_TRACER_NAME=github.com/Rain-kl/OpenFlare
 # compose 可选端口覆盖
 # JAEGER_VERSION=2.19.0
 # JAEGER_UI_PORT=16686

.gitattributes

@@ -0,0 +1,8 @@
+* -text
+backend/openflare/**    merge=ours
+frontend/**             merge=ours
+docs/changelog/**       merge=ours
+docs/superpowers/**     merge=ours
+.github/workflows/build-image.yml merge=ours
+docker-compose.yml      merge=ours
+.gitconfig              merge=ours

.gitconfig

@@ -0,0 +1,10 @@
+# Repo-local Git settings. Git does not load this file automatically.
+# From the clone (or worktree) root:
+#   git config include.path ../.gitconfig
+# Worktree-safe:
+#   git config include.path "$(git rev-parse --show-toplevel)/.gitconfig"
+# Relative include.path is resolved against .git/config, so ../.gitconfig
+# is the repo root when .git is a directory (non-worktree clone).
+
+[merge "ours"]
+	driver = true

.github/copilot-instructions.md

@@ -12,7 +12,7 @@
 - 新增功能时考虑向后兼容性和 API 稳定性
 - 遵循项目的 Apache2.0 许可证要求
 - 遵循语义化版本控制规范
-- 新增异步任务时使用项目技能 `.agents/new-async-task/SKILL.md`
+- 新增异步任务时使用项目技能 `.agent/new-async-task/SKILL.md`
 
 ## 后端规范
 

.github/workflows/build-image-openflare-agent.yml

@@ -0,0 +1,197 @@
+name: Build Image (openflare-agent)
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Image version/tag to publish, for example v1.0.0-beta"
+        required: false
+        type: string
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  packages: write
+  attestations: write
+  id-token: write
+
+env:
+  IMAGE_NAME: openflare-agent
+  DOCKERFILE: manifest/docker/Dockerfile.agent
+
+jobs:
+  build:
+    name: Build (${{ matrix.arch }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-24.04
+          - arch: arm64
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set image metadata
+        shell: bash
+        env:
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+        run: |
+          POINTED_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -n1)"
+          INPUT_VERSION="${INPUT_VERSION//[[:space:]]/}"
+
+          OWNER="${GITHUB_REPOSITORY_OWNER,,}"
+
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            VERSION="${GITHUB_REF_NAME}"
+          elif [[ -n "$INPUT_VERSION" ]]; then
+            VERSION="$INPUT_VERSION"
+          elif [[ -n "$POINTED_TAG" ]]; then
+            VERSION="$POINTED_TAG"
+          else
+            echo "workflow_dispatch requires an explicit version input when HEAD is not tagged" >&2
+            exit 1
+          fi
+
+          echo "IMAGE=ghcr.io/${OWNER}/openflare-agent" >> "$GITHUB_ENV"
+          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log into registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        id: build
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ${{ env.DOCKERFILE }}
+          platforms: ${{ matrix.platform }}
+          outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
+          build-args: |
+            VERSION=${{ env.VERSION }}
+          cache-from: type=gha,scope=docker-${{ env.IMAGE_NAME }}-${{ matrix.arch }}
+          cache-to: type=gha,mode=max,ignore-error=true,timeout=20m,scope=docker-${{ env.IMAGE_NAME }}-${{ matrix.arch }}
+
+      - name: Export digest
+        shell: bash
+        run: |
+          mkdir -p "/tmp/${{ env.IMAGE_NAME }}-digests"
+          touch "/tmp/${{ env.IMAGE_NAME }}-digests/${DIGEST#sha256:}"
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ env.IMAGE_NAME }}-digests-${{ matrix.arch }}
+          path: /tmp/${{ env.IMAGE_NAME }}-digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@v3
+        with:
+          subject-name: ${{ env.IMAGE }}
+          subject-digest: ${{ steps.build.outputs.digest }}
+          push-to-registry: true
+
+  merge:
+    name: Merge multi-arch manifest
+    runs-on: ubuntu-24.04
+    needs: build
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set image metadata
+        shell: bash
+        env:
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+        run: |
+          POINTED_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -n1)"
+          INPUT_VERSION="${INPUT_VERSION//[[:space:]]/}"
+
+          OWNER="${GITHUB_REPOSITORY_OWNER,,}"
+
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            VERSION="${GITHUB_REF_NAME}"
+          elif [[ -n "$INPUT_VERSION" ]]; then
+            VERSION="$INPUT_VERSION"
+          elif [[ -n "$POINTED_TAG" ]]; then
+            VERSION="$POINTED_TAG"
+          else
+            echo "workflow_dispatch requires an explicit version input when HEAD is not tagged" >&2
+            exit 1
+          fi
+
+          echo "IMAGE=ghcr.io/${OWNER}/openflare-agent" >> "$GITHUB_ENV"
+          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/${{ env.IMAGE_NAME }}-digests
+          pattern: ${{ env.IMAGE_NAME }}-digests-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log into registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create and push manifest list
+        working-directory: /tmp/${{ env.IMAGE_NAME }}-digests
+        shell: bash
+        run: |
+          shopt -s nullglob
+          references=()
+          for digest in *; do
+            references+=("${IMAGE}@sha256:${digest}")
+          done
+
+          if [ ${#references[@]} -eq 0 ]; then
+            echo "No digests found in /tmp/${{ env.IMAGE_NAME }}-digests" >&2
+            exit 1
+          fi
+
+          if [[ "${VERSION}" =~ (alpha|beta|rc) ]]; then
+            FLOATING_TAG="beta"
+          else
+            FLOATING_TAG="latest"
+          fi
+
+          docker buildx imagetools create \
+            -t "${IMAGE}:${VERSION}" \
+            -t "${IMAGE}:${FLOATING_TAG}" \
+            "${references[@]}"
+        env:
+          IMAGE: ${{ env.IMAGE }}
+
+      - name: Inspect image
+        run: docker buildx imagetools inspect "${{ env.IMAGE }}:${{ env.VERSION }}"

.github/workflows/build-image-openflare-relay.yml

@@ -0,0 +1,197 @@
+name: Build Image (openflare-relay)
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Image version/tag to publish, for example v1.0.0-beta"
+        required: false
+        type: string
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  packages: write
+  attestations: write
+  id-token: write
+
+env:
+  IMAGE_NAME: openflare-relay
+  DOCKERFILE: manifest/docker/Dockerfile.relay
+
+jobs:
+  build:
+    name: Build (${{ matrix.arch }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-24.04
+          - arch: arm64
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set image metadata
+        shell: bash
+        env:
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+        run: |
+          POINTED_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -n1)"
+          INPUT_VERSION="${INPUT_VERSION//[[:space:]]/}"
+
+          OWNER="${GITHUB_REPOSITORY_OWNER,,}"
+
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            VERSION="${GITHUB_REF_NAME}"
+          elif [[ -n "$INPUT_VERSION" ]]; then
+            VERSION="$INPUT_VERSION"
+          elif [[ -n "$POINTED_TAG" ]]; then
+            VERSION="$POINTED_TAG"
+          else
+            echo "workflow_dispatch requires an explicit version input when HEAD is not tagged" >&2
+            exit 1
+          fi
+
+          echo "IMAGE=ghcr.io/${OWNER}/openflare-relay" >> "$GITHUB_ENV"
+          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log into registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        id: build
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ${{ env.DOCKERFILE }}
+          platforms: ${{ matrix.platform }}
+          outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
+          build-args: |
+            VERSION=${{ env.VERSION }}
+          cache-from: type=gha,scope=docker-${{ env.IMAGE_NAME }}-${{ matrix.arch }}
+          cache-to: type=gha,mode=max,ignore-error=true,timeout=20m,scope=docker-${{ env.IMAGE_NAME }}-${{ matrix.arch }}
+
+      - name: Export digest
+        shell: bash
+        run: |
+          mkdir -p "/tmp/${{ env.IMAGE_NAME }}-digests"
+          touch "/tmp/${{ env.IMAGE_NAME }}-digests/${DIGEST#sha256:}"
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ env.IMAGE_NAME }}-digests-${{ matrix.arch }}
+          path: /tmp/${{ env.IMAGE_NAME }}-digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@v3
+        with:
+          subject-name: ${{ env.IMAGE }}
+          subject-digest: ${{ steps.build.outputs.digest }}
+          push-to-registry: true
+
+  merge:
+    name: Merge multi-arch manifest
+    runs-on: ubuntu-24.04
+    needs: build
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set image metadata
+        shell: bash
+        env:
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+        run: |
+          POINTED_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -n1)"
+          INPUT_VERSION="${INPUT_VERSION//[[:space:]]/}"
+
+          OWNER="${GITHUB_REPOSITORY_OWNER,,}"
+
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            VERSION="${GITHUB_REF_NAME}"
+          elif [[ -n "$INPUT_VERSION" ]]; then
+            VERSION="$INPUT_VERSION"
+          elif [[ -n "$POINTED_TAG" ]]; then
+            VERSION="$POINTED_TAG"
+          else
+            echo "workflow_dispatch requires an explicit version input when HEAD is not tagged" >&2
+            exit 1
+          fi
+
+          echo "IMAGE=ghcr.io/${OWNER}/openflare-relay" >> "$GITHUB_ENV"
+          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/${{ env.IMAGE_NAME }}-digests
+          pattern: ${{ env.IMAGE_NAME }}-digests-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log into registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create and push manifest list
+        working-directory: /tmp/${{ env.IMAGE_NAME }}-digests
+        shell: bash
+        run: |
+          shopt -s nullglob
+          references=()
+          for digest in *; do
+            references+=("${IMAGE}@sha256:${digest}")
+          done
+
+          if [ ${#references[@]} -eq 0 ]; then
+            echo "No digests found in /tmp/${{ env.IMAGE_NAME }}-digests" >&2
+            exit 1
+          fi
+
+          if [[ "${VERSION}" =~ (alpha|beta|rc) ]]; then
+            FLOATING_TAG="beta"
+          else
+            FLOATING_TAG="latest"
+          fi
+
+          docker buildx imagetools create \
+            -t "${IMAGE}:${VERSION}" \
+            -t "${IMAGE}:${FLOATING_TAG}" \
+            "${references[@]}"
+        env:
+          IMAGE: ${{ env.IMAGE }}
+
+      - name: Inspect image
+        run: docker buildx imagetools inspect "${{ env.IMAGE }}:${{ env.VERSION }}"

.github/workflows/build-image-openflare.yml

@@ -0,0 +1,270 @@
+name: Build Image (openflare)
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Image version/tag to publish (e.g. v1.0.0-beta). Leave empty to publish as canary."
+        required: false
+        type: string
+  push:
+    tags: ["v*"]
+    branches: ["canary"]
+
+# One active run per ref (e.g. canary); newer runs cancel older in-progress builds.
+concurrency:
+  group: build-image-openflare-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: write
+  attestations: write
+  id-token: write
+
+env:
+  IMAGE_NAME: openflare
+  DOCKERFILE: manifest/docker/Dockerfile
+
+jobs:
+  # Resolve version / registries once. No checkout: triggers alone determine the tag.
+  prepare:
+    name: Prepare metadata
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.prep.outputs.version }}
+      build_date: ${{ steps.prep.outputs.build_date }}
+      image: ${{ steps.prep.outputs.image }}
+      image_names: ${{ steps.prep.outputs.image_names }}
+      images: ${{ steps.prep.outputs.images }}
+      push_dockerhub: ${{ steps.prep.outputs.push_dockerhub }}
+      is_stable: ${{ steps.prep.outputs.is_stable }}
+      is_prerelease: ${{ steps.prep.outputs.is_prerelease }}
+    steps:
+      - name: Resolve version and images
+        id: prep
+        env:
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+          DOCKERHUB_NAMESPACE: ${{ secrets.DOCKERHUB_NAMESPACE }}
+        run: |
+          set -euo pipefail
+          INPUT_VERSION="${INPUT_VERSION//[[:space:]]/}"
+          OWNER="${GITHUB_REPOSITORY_OWNER,,}"
+          BUILD_DATE="$(date -u +'%Y-%m-%dT%H:%M:%SZ')"
+
+          if [[ "${GITHUB_REF}" == refs/heads/canary ]]; then
+            VERSION="canary"
+          elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            VERSION="${GITHUB_REF_NAME}"
+          elif [[ -n "$INPUT_VERSION" ]]; then
+            VERSION="$INPUT_VERSION"
+          elif [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
+            VERSION="canary"
+          else
+            echo "unable to determine image version/tag" >&2
+            exit 1
+          fi
+
+          if [[ "$VERSION" == "canary" ]]; then
+            IS_STABLE="false"
+            IS_PRERELEASE="false"
+          elif [[ "$VERSION" =~ (alpha|beta|rc) ]]; then
+            IS_STABLE="false"
+            IS_PRERELEASE="true"
+          else
+            IS_STABLE="true"
+            IS_PRERELEASE="false"
+          fi
+
+          IMAGE="ghcr.io/${OWNER}/${IMAGE_NAME}"
+          IMAGE_NAMES="${IMAGE}"
+          # Newline-separated list for docker/metadata-action
+          IMAGES="${IMAGE}"
+
+          DOCKERHUB_USERNAME="${DOCKERHUB_USERNAME//[[:space:]]/}"
+          DOCKERHUB_TOKEN="${DOCKERHUB_TOKEN//[[:space:]]/}"
+          DOCKERHUB_NAMESPACE="${DOCKERHUB_NAMESPACE//[[:space:]]/}"
+          PUSH_DOCKERHUB="false"
+          if [[ -n "$DOCKERHUB_USERNAME" && -n "$DOCKERHUB_TOKEN" ]]; then
+            HUB_NS="${DOCKERHUB_NAMESPACE:-$DOCKERHUB_USERNAME}"
+            HUB_NS="${HUB_NS,,}"
+            IMAGE_DOCKERHUB="${HUB_NS}/${IMAGE_NAME}"
+            IMAGE_NAMES="${IMAGE_NAMES},${IMAGE_DOCKERHUB}"
+            IMAGES="${IMAGES}"$'\n'"${IMAGE_DOCKERHUB}"
+            PUSH_DOCKERHUB="true"
+            echo "Docker Hub publish enabled: ${IMAGE_DOCKERHUB}"
+          else
+            echo "Docker Hub secrets not set; publishing to GHCR only."
+          fi
+
+          {
+            echo "version=${VERSION}"
+            echo "build_date=${BUILD_DATE}"
+            echo "image=${IMAGE}"
+            echo "image_names=${IMAGE_NAMES}"
+            echo "push_dockerhub=${PUSH_DOCKERHUB}"
+            echo "is_stable=${IS_STABLE}"
+            echo "is_prerelease=${IS_PRERELEASE}"
+            echo "images<<EOF"
+            printf '%s\n' "${IMAGES}"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+          echo "Resolved version=${VERSION} build_date=${BUILD_DATE} stable=${IS_STABLE} prerelease=${IS_PRERELEASE}"
+
+  build:
+    name: Build (${{ matrix.arch }})
+    needs: prepare
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-latest
+          - arch: arm64
+            platform: linux/arm64
+            # No ubuntu-latest-arm alias from GitHub; 24.04-arm is the current stable arm64 image.
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log into GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Log into Docker Hub
+        if: needs.prepare.outputs.push_dockerhub == 'true'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push
+        id: build
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ${{ env.DOCKERFILE }}
+          platforms: ${{ matrix.platform }}
+          outputs: type=image,"name=${{ needs.prepare.outputs.image_names }}",push-by-digest=true,name-canonical=true,push=true
+          build-args: |
+            VERSION=${{ needs.prepare.outputs.version }}
+            BUILD_DATE=${{ needs.prepare.outputs.build_date }}
+          cache-from: type=gha,scope=docker-${{ env.IMAGE_NAME }}-${{ matrix.arch }}
+          cache-to: type=gha,mode=max,ignore-error=true,timeout=20m,scope=docker-${{ env.IMAGE_NAME }}-${{ matrix.arch }}
+
+      - name: Export digest
+        shell: bash
+        run: |
+          mkdir -p "/tmp/${{ env.IMAGE_NAME }}-digests"
+          touch "/tmp/${{ env.IMAGE_NAME }}-digests/${DIGEST#sha256:}"
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ env.IMAGE_NAME }}-digests-${{ matrix.arch }}
+          path: /tmp/${{ env.IMAGE_NAME }}-digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@v3
+        with:
+          subject-name: ${{ needs.prepare.outputs.image }}
+          subject-digest: ${{ steps.build.outputs.digest }}
+          push-to-registry: true
+
+  merge:
+    name: Merge multi-arch manifest
+    runs-on: ubuntu-latest
+    needs: [prepare, build]
+    steps:
+      # No repo checkout: tags come from prepare + metadata-action.
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ needs.prepare.outputs.images }}
+          flavor: |
+            latest=false
+          tags: |
+            type=raw,value=${{ needs.prepare.outputs.version }}
+            type=raw,value=latest,enable=${{ needs.prepare.outputs.is_stable == 'true' }}
+            type=raw,value=beta,enable=${{ needs.prepare.outputs.is_prerelease == 'true' }}
+
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/${{ env.IMAGE_NAME }}-digests
+          pattern: ${{ env.IMAGE_NAME }}-digests-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log into GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Log into Docker Hub
+        if: needs.prepare.outputs.push_dockerhub == 'true'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Create and push manifest list
+        working-directory: /tmp/${{ env.IMAGE_NAME }}-digests
+        shell: bash
+        env:
+          IMAGE: ${{ needs.prepare.outputs.image }}
+          DOCKER_METADATA_OUTPUT_JSON: ${{ steps.meta.outputs.json }}
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          references=()
+          for digest in *; do
+            references+=("${IMAGE}@sha256:${digest}")
+          done
+
+          if [ ${#references[@]} -eq 0 ]; then
+            echo "No digests found in /tmp/${{ env.IMAGE_NAME }}-digests" >&2
+            exit 1
+          fi
+
+          # shellcheck disable=SC2046
+          docker buildx imagetools create \
+            $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            "${references[@]}"
+
+      - name: Inspect image
+        run: docker buildx imagetools inspect "${{ needs.prepare.outputs.image }}:${{ needs.prepare.outputs.version }}"
+
+      - name: Trigger webhook
+        env:
+          WEBHOOK_URL: ${{ secrets.WEBHOOK_URL }}
+        run: |
+          if [ -n "$WEBHOOK_URL" ]; then
+            curl -fsSL "$WEBHOOK_URL"
+          else
+            echo "Webhook URL is not set, skipping."
+          fi

.github/workflows/build-image-openflared.yml

@@ -0,0 +1,197 @@
+name: Build Image (openflared)
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Image version/tag to publish, for example v1.0.0-beta"
+        required: false
+        type: string
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  packages: write
+  attestations: write
+  id-token: write
+
+env:
+  IMAGE_NAME: openflared
+  DOCKERFILE: manifest/docker/Dockerfile.flared
+
+jobs:
+  build:
+    name: Build (${{ matrix.arch }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-24.04
+          - arch: arm64
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set image metadata
+        shell: bash
+        env:
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+        run: |
+          POINTED_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -n1)"
+          INPUT_VERSION="${INPUT_VERSION//[[:space:]]/}"
+
+          OWNER="${GITHUB_REPOSITORY_OWNER,,}"
+
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            VERSION="${GITHUB_REF_NAME}"
+          elif [[ -n "$INPUT_VERSION" ]]; then
+            VERSION="$INPUT_VERSION"
+          elif [[ -n "$POINTED_TAG" ]]; then
+            VERSION="$POINTED_TAG"
+          else
+            echo "workflow_dispatch requires an explicit version input when HEAD is not tagged" >&2
+            exit 1
+          fi
+
+          echo "IMAGE=ghcr.io/${OWNER}/openflared" >> "$GITHUB_ENV"
+          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log into registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        id: build
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ${{ env.DOCKERFILE }}
+          platforms: ${{ matrix.platform }}
+          outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
+          build-args: |
+            VERSION=${{ env.VERSION }}
+          cache-from: type=gha,scope=docker-${{ env.IMAGE_NAME }}-${{ matrix.arch }}
+          cache-to: type=gha,mode=max,ignore-error=true,timeout=20m,scope=docker-${{ env.IMAGE_NAME }}-${{ matrix.arch }}
+
+      - name: Export digest
+        shell: bash
+        run: |
+          mkdir -p "/tmp/${{ env.IMAGE_NAME }}-digests"
+          touch "/tmp/${{ env.IMAGE_NAME }}-digests/${DIGEST#sha256:}"
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ env.IMAGE_NAME }}-digests-${{ matrix.arch }}
+          path: /tmp/${{ env.IMAGE_NAME }}-digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@v3
+        with:
+          subject-name: ${{ env.IMAGE }}
+          subject-digest: ${{ steps.build.outputs.digest }}
+          push-to-registry: true
+
+  merge:
+    name: Merge multi-arch manifest
+    runs-on: ubuntu-24.04
+    needs: build
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set image metadata
+        shell: bash
+        env:
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+        run: |
+          POINTED_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -n1)"
+          INPUT_VERSION="${INPUT_VERSION//[[:space:]]/}"
+
+          OWNER="${GITHUB_REPOSITORY_OWNER,,}"
+
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            VERSION="${GITHUB_REF_NAME}"
+          elif [[ -n "$INPUT_VERSION" ]]; then
+            VERSION="$INPUT_VERSION"
+          elif [[ -n "$POINTED_TAG" ]]; then
+            VERSION="$POINTED_TAG"
+          else
+            echo "workflow_dispatch requires an explicit version input when HEAD is not tagged" >&2
+            exit 1
+          fi
+
+          echo "IMAGE=ghcr.io/${OWNER}/openflared" >> "$GITHUB_ENV"
+          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/${{ env.IMAGE_NAME }}-digests
+          pattern: ${{ env.IMAGE_NAME }}-digests-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log into registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create and push manifest list
+        working-directory: /tmp/${{ env.IMAGE_NAME }}-digests
+        shell: bash
+        run: |
+          shopt -s nullglob
+          references=()
+          for digest in *; do
+            references+=("${IMAGE}@sha256:${digest}")
+          done
+
+          if [ ${#references[@]} -eq 0 ]; then
+            echo "No digests found in /tmp/${{ env.IMAGE_NAME }}-digests" >&2
+            exit 1
+          fi
+
+          if [[ "${VERSION}" =~ (alpha|beta|rc) ]]; then
+            FLOATING_TAG="beta"
+          else
+            FLOATING_TAG="latest"
+          fi
+
+          docker buildx imagetools create \
+            -t "${IMAGE}:${VERSION}" \
+            -t "${IMAGE}:${FLOATING_TAG}" \
+            "${references[@]}"
+        env:
+          IMAGE: ${{ env.IMAGE }}
+
+      - name: Inspect image
+        run: docker buildx imagetools inspect "${{ env.IMAGE }}:${{ env.VERSION }}"

.github/workflows/build-image.yml

@@ -1,270 +1,22 @@
-name: Build Image
+name: Build Image (Wavelet upstream — isolated)
 
+# Isolated: OpenFlare publishes images via build-image-openflare.yml
+# (IMAGE_NAME: openflare). This Wavelet workflow is kept under the same
+# path so `git merge wavelet/main` cannot restore a canary wavelet image.
 on:
   workflow_dispatch:
     inputs:
-      version:
-        description: "Image version/tag to publish (e.g. v1.0.0-beta). Leave empty to publish as canary."
-        required: false
-        type: string
-  push:
-    tags: ["v*"]
-    branches: ["canary"]
-
-# One active run per ref (e.g. canary); newer runs cancel older in-progress builds.
-concurrency:
-  group: build-image-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-  packages: write
-  attestations: write
-  id-token: write
-
-env:
-  IMAGE_NAME: wavelet
-  DOCKERFILE: docker/Dockerfile
+      confirm:
+        description: "Disabled on OpenFlare. Use build-image-openflare.yml."
+        required: true
 
 jobs:
-  # Resolve version / registries once. No checkout: triggers alone determine the tag.
-  prepare:
-    name: Prepare metadata
+  isolated:
+    name: Isolated
     runs-on: ubuntu-latest
-    outputs:
-      version: ${{ steps.prep.outputs.version }}
-      build_date: ${{ steps.prep.outputs.build_date }}
-      image: ${{ steps.prep.outputs.image }}
-      image_names: ${{ steps.prep.outputs.image_names }}
-      images: ${{ steps.prep.outputs.images }}
-      push_dockerhub: ${{ steps.prep.outputs.push_dockerhub }}
-      is_stable: ${{ steps.prep.outputs.is_stable }}
-      is_prerelease: ${{ steps.prep.outputs.is_prerelease }}
     steps:
-      - name: Resolve version and images
-        id: prep
-        env:
-          INPUT_VERSION: ${{ github.event.inputs.version }}
-          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
-          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
-          DOCKERHUB_NAMESPACE: ${{ secrets.DOCKERHUB_NAMESPACE }}
+      - name: Refuse Wavelet image publish
         run: |
-          set -euo pipefail
-          INPUT_VERSION="${INPUT_VERSION//[[:space:]]/}"
-          OWNER="${GITHUB_REPOSITORY_OWNER,,}"
-          BUILD_DATE="$(date -u +'%Y-%m-%dT%H:%M:%SZ')"
-
-          if [[ "${GITHUB_REF}" == refs/heads/canary ]]; then
-            VERSION="canary"
-          elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-            VERSION="${GITHUB_REF_NAME}"
-          elif [[ -n "$INPUT_VERSION" ]]; then
-            VERSION="$INPUT_VERSION"
-          elif [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
-            VERSION="canary"
-          else
-            echo "unable to determine image version/tag" >&2
-            exit 1
-          fi
-
-          if [[ "$VERSION" == "canary" ]]; then
-            IS_STABLE="false"
-            IS_PRERELEASE="false"
-          elif [[ "$VERSION" =~ (alpha|beta|rc) ]]; then
-            IS_STABLE="false"
-            IS_PRERELEASE="true"
-          else
-            IS_STABLE="true"
-            IS_PRERELEASE="false"
-          fi
-
-          IMAGE="ghcr.io/${OWNER}/${IMAGE_NAME}"
-          IMAGE_NAMES="${IMAGE}"
-          # Newline-separated list for docker/metadata-action
-          IMAGES="${IMAGE}"
-
-          DOCKERHUB_USERNAME="${DOCKERHUB_USERNAME//[[:space:]]/}"
-          DOCKERHUB_TOKEN="${DOCKERHUB_TOKEN//[[:space:]]/}"
-          DOCKERHUB_NAMESPACE="${DOCKERHUB_NAMESPACE//[[:space:]]/}"
-          PUSH_DOCKERHUB="false"
-          if [[ -n "$DOCKERHUB_USERNAME" && -n "$DOCKERHUB_TOKEN" ]]; then
-            HUB_NS="${DOCKERHUB_NAMESPACE:-$DOCKERHUB_USERNAME}"
-            HUB_NS="${HUB_NS,,}"
-            IMAGE_DOCKERHUB="${HUB_NS}/${IMAGE_NAME}"
-            IMAGE_NAMES="${IMAGE_NAMES},${IMAGE_DOCKERHUB}"
-            IMAGES="${IMAGES}"$'\n'"${IMAGE_DOCKERHUB}"
-            PUSH_DOCKERHUB="true"
-            echo "Docker Hub publish enabled: ${IMAGE_DOCKERHUB}"
-          else
-            echo "Docker Hub secrets not set; publishing to GHCR only."
-          fi
-
-          {
-            echo "version=${VERSION}"
-            echo "build_date=${BUILD_DATE}"
-            echo "image=${IMAGE}"
-            echo "image_names=${IMAGE_NAMES}"
-            echo "push_dockerhub=${PUSH_DOCKERHUB}"
-            echo "is_stable=${IS_STABLE}"
-            echo "is_prerelease=${IS_PRERELEASE}"
-            echo "images<<EOF"
-            printf '%s\n' "${IMAGES}"
-            echo "EOF"
-          } >> "$GITHUB_OUTPUT"
-
-          echo "Resolved version=${VERSION} build_date=${BUILD_DATE} stable=${IS_STABLE} prerelease=${IS_PRERELEASE}"
-
-  build:
-    name: Build (${{ matrix.arch }})
-    needs: prepare
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - arch: amd64
-            platform: linux/amd64
-            runner: ubuntu-latest
-          - arch: arm64
-            platform: linux/arm64
-            # No ubuntu-latest-arm alias from GitHub; 24.04-arm is the current stable arm64 image.
-            runner: ubuntu-24.04-arm
-    runs-on: ${{ matrix.runner }}
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-          persist-credentials: false
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
-
-      - name: Log into GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Log into Docker Hub
-        if: needs.prepare.outputs.push_dockerhub == 'true'
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Build and push
-        id: build
-        uses: docker/build-push-action@v7
-        with:
-          context: .
-          file: ${{ env.DOCKERFILE }}
-          platforms: ${{ matrix.platform }}
-          outputs: type=image,"name=${{ needs.prepare.outputs.image_names }}",push-by-digest=true,name-canonical=true,push=true
-          build-args: |
-            VERSION=${{ needs.prepare.outputs.version }}
-            BUILD_DATE=${{ needs.prepare.outputs.build_date }}
-          cache-from: type=gha,scope=docker-${{ env.IMAGE_NAME }}-${{ matrix.arch }}
-          cache-to: type=gha,mode=max,ignore-error=true,timeout=20m,scope=docker-${{ env.IMAGE_NAME }}-${{ matrix.arch }}
-
-      - name: Export digest
-        shell: bash
-        run: |
-          mkdir -p "/tmp/${{ env.IMAGE_NAME }}-digests"
-          touch "/tmp/${{ env.IMAGE_NAME }}-digests/${DIGEST#sha256:}"
-        env:
-          DIGEST: ${{ steps.build.outputs.digest }}
-
-      - name: Upload digest
-        uses: actions/upload-artifact@v4
-        with:
-          name: ${{ env.IMAGE_NAME }}-digests-${{ matrix.arch }}
-          path: /tmp/${{ env.IMAGE_NAME }}-digests/*
-          if-no-files-found: error
-          retention-days: 1
-
-      - name: Generate artifact attestation
-        uses: actions/attest-build-provenance@v3
-        with:
-          subject-name: ${{ needs.prepare.outputs.image }}
-          subject-digest: ${{ steps.build.outputs.digest }}
-          push-to-registry: true
-
-  merge:
-    name: Merge multi-arch manifest
-    runs-on: ubuntu-latest
-    needs: [prepare, build]
-    steps:
-      # No repo checkout: tags come from prepare + metadata-action.
-      - name: Docker meta
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ needs.prepare.outputs.images }}
-          flavor: |
-            latest=false
-          tags: |
-            type=raw,value=${{ needs.prepare.outputs.version }}
-            type=raw,value=latest,enable=${{ needs.prepare.outputs.is_stable == 'true' }}
-            type=raw,value=beta,enable=${{ needs.prepare.outputs.is_prerelease == 'true' }}
-
-      - name: Download digests
-        uses: actions/download-artifact@v4
-        with:
-          path: /tmp/${{ env.IMAGE_NAME }}-digests
-          pattern: ${{ env.IMAGE_NAME }}-digests-*
-          merge-multiple: true
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
-
-      - name: Log into GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Log into Docker Hub
-        if: needs.prepare.outputs.push_dockerhub == 'true'
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Create and push manifest list
-        working-directory: /tmp/${{ env.IMAGE_NAME }}-digests
-        shell: bash
-        env:
-          IMAGE: ${{ needs.prepare.outputs.image }}
-          DOCKER_METADATA_OUTPUT_JSON: ${{ steps.meta.outputs.json }}
-        run: |
-          set -euo pipefail
-          shopt -s nullglob
-          references=()
-          for digest in *; do
-            references+=("${IMAGE}@sha256:${digest}")
-          done
-
-          if [ ${#references[@]} -eq 0 ]; then
-            echo "No digests found in /tmp/${{ env.IMAGE_NAME }}-digests" >&2
-            exit 1
-          fi
-
-          # shellcheck disable=SC2046
-          docker buildx imagetools create \
-            $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
-            "${references[@]}"
-
-      - name: Inspect image
-        run: docker buildx imagetools inspect "${{ needs.prepare.outputs.image }}:${{ needs.prepare.outputs.version }}"
-
-      - name: Trigger webhook
-        env:
-          WEBHOOK_URL: ${{ secrets.WEBHOOK_URL }}
-        run: |
-          if [ -n "$WEBHOOK_URL" ]; then
-            curl -fsSL "$WEBHOOK_URL"
-          else
-            echo "Webhook URL is not set, skipping."
-          fi
+          echo "This Wavelet image workflow is isolated on OpenFlare."
+          echo "Use .github/workflows/build-image-openflare.yml"
+          exit 1

.github/workflows/build-release.yml

@@ -11,7 +11,8 @@ on:
         type: string
 
 env:
-  APP_NAME: wavelet
+  APP_NAME: openflare-server
+  GO_DIR: backend
   GO_MAIN: ./main.go
   GO_BUILD_TAGS: embed_frontend
   GO_LDFLAGS: -s -w
@@ -20,12 +21,12 @@ env:
   FRONTEND_DIR: frontend
   FRONTEND_BUILD_COMMAND: pnpm build:embed
   FRONTEND_OUT_DIR: frontend/out
-  EMBED_DIST_DIR: internal/router/root/dist
+  EMBED_DIST_DIR: backend/plugins/drivers/driver_http/dist
   EXTRA_FILES: |
     LICENSE
     README.md
     README_zh.md
-    config.example.yaml
+    manifest/config/config.default.yaml
     DEPLOYMENT_zh.md
 
 permissions:
@@ -145,6 +146,7 @@ jobs:
           rm -rf "$EMBED_DIST_DIR"
           mkdir -p "$(dirname "$EMBED_DIST_DIR")"
           cp -R "$FRONTEND_OUT_DIR" "$EMBED_DIST_DIR"
+          test -f "$EMBED_DIST_DIR/index.html"
 
       - name: Upload embedded frontend
         uses: actions/upload-artifact@v4
@@ -192,7 +194,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version-file: go.mod
+          go-version-file: ${{ env.GO_DIR }}/go.mod
           cache: true
 
       - name: Build binary
@@ -212,18 +214,21 @@ jobs:
             binary_name="${binary_name}.exe"
           fi
 
-          ldflags="$GO_LDFLAGS -X github.com/Rain-kl/Wavelet/internal/buildinfo.Version=$VERSION -X github.com/Rain-kl/Wavelet/internal/buildinfo.BuildTime=$BUILD_DATE"
+          # Assert the embedded UI is present so a release cannot ship an API-only binary.
+          test -f "$EMBED_DIST_DIR/index.html"
+
+          ldflags="$GO_LDFLAGS -X Wavelet/pkg/buildinfo.Version=$VERSION -X Wavelet/pkg/buildinfo.BuildTime=$BUILD_DATE"
           build_args=(
             -trimpath
             -ldflags "$ldflags"
-            -o "dist/$binary_name"
+            -o "$GITHUB_WORKSPACE/dist/$binary_name"
           )
 
           if [[ -n "$GO_BUILD_TAGS" ]]; then
             build_args=(-tags "$GO_BUILD_TAGS" "${build_args[@]}")
           fi
 
-          go build "${build_args[@]}" "$GO_MAIN"
+          (cd "$GO_DIR" && go build "${build_args[@]}" "$GO_MAIN")
 
       - name: Package artifact
         id: package
@@ -268,3 +273,148 @@ jobs:
         with:
           tag_name: ${{ needs.create-release.outputs.version }}
           files: ${{ steps.package.outputs.artifact }}
+
+  build-agent-binaries:
+    name: Build agent ${{ matrix.goos }}/${{ matrix.goarch }}
+    runs-on: ubuntu-latest
+    needs: create-release
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+            asset_name: openflare-agent-linux-amd64
+          - goos: linux
+            goarch: arm64
+            asset_name: openflare-agent-linux-arm64
+          - goos: darwin
+            goarch: amd64
+            asset_name: openflare-agent-darwin-amd64
+          - goos: darwin
+            goarch: arm64
+            asset_name: openflare-agent-darwin-arm64
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: ${{ env.GO_DIR }}/go.mod
+
+      # GeoIP MMDB is not embedded; Docker images COPY mmdb files, bare binaries seed via download on first start.
+      - name: Build Agent
+        env:
+          CGO_ENABLED: 0
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          ASSET_NAME: ${{ matrix.asset_name }}
+          VERSION: ${{ needs.create-release.outputs.version }}
+        run: |
+          cd backend
+          go mod download
+          mkdir -p "$GITHUB_WORKSPACE/dist"
+          go build -trimpath -ldflags "-s -w -X 'Wavelet/OpenFlare/plugins/agent/config.Version=$VERSION'" -o "$GITHUB_WORKSPACE/dist/$ASSET_NAME" ./cmd/agent/main.go
+
+      - name: Upload release artifact
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.create-release.outputs.version }}
+          files: dist/${{ matrix.asset_name }}
+
+  build-relay-binaries:
+    name: Build relay ${{ matrix.goos }}/${{ matrix.goarch }}
+    runs-on: ubuntu-latest
+    needs: create-release
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+            asset_name: openflare-relay-linux-amd64
+          - goos: linux
+            goarch: arm64
+            asset_name: openflare-relay-linux-arm64
+          - goos: darwin
+            goarch: amd64
+            asset_name: openflare-relay-darwin-amd64
+          - goos: darwin
+            goarch: arm64
+            asset_name: openflare-relay-darwin-arm64
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: ${{ env.GO_DIR }}/go.mod
+
+      - name: Build Relay
+        env:
+          CGO_ENABLED: 0
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          ASSET_NAME: ${{ matrix.asset_name }}
+          VERSION: ${{ needs.create-release.outputs.version }}
+        run: |
+          cd backend
+          go mod download
+          mkdir -p "$GITHUB_WORKSPACE/dist"
+          go build -trimpath -ldflags "-s -w -X 'Wavelet/OpenFlare/plugins/relay/config.Version=$VERSION'" -o "$GITHUB_WORKSPACE/dist/$ASSET_NAME" ./cmd/relay/main.go
+
+      - name: Upload release artifact
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.create-release.outputs.version }}
+          files: dist/${{ matrix.asset_name }}
+
+  build-flared-binaries:
+    name: Build flared ${{ matrix.goos }}/${{ matrix.goarch }}
+    runs-on: ubuntu-latest
+    needs: create-release
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+            asset_name: openflared-linux-amd64
+          - goos: linux
+            goarch: arm64
+            asset_name: openflared-linux-arm64
+          - goos: darwin
+            goarch: amd64
+            asset_name: openflared-darwin-amd64
+          - goos: darwin
+            goarch: arm64
+            asset_name: openflared-darwin-arm64
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: ${{ env.GO_DIR }}/go.mod
+
+      - name: Build Flared
+        env:
+          CGO_ENABLED: 0
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          ASSET_NAME: ${{ matrix.asset_name }}
+          VERSION: ${{ needs.create-release.outputs.version }}
+        run: |
+          cd backend
+          go mod download
+          mkdir -p "$GITHUB_WORKSPACE/dist"
+          go build -trimpath -ldflags "-s -w -X 'Wavelet/OpenFlare/plugins/flared/config.Version=$VERSION'" -o "$GITHUB_WORKSPACE/dist/$ASSET_NAME" ./cmd/flared/main.go
+
+      - name: Upload release artifact
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.create-release.outputs.version }}
+          files: dist/${{ matrix.asset_name }}

.github/workflows/close_ticket.yml

@@ -0,0 +1,24 @@
+name: Close Ticket
+
+on:
+  schedule:
+    - cron: "0 0 * * *"
+
+jobs:
+  close_ticket:
+    runs-on: ubuntu-24.04
+    permissions:
+      issues: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/stale@v9
+        with:
+          days-before-issue-stale: 14
+          days-before-issue-close: 14
+          stale-issue-message: "此 issue 长期无活动，将在 14 天后自动关闭。如需继续讨论请回复"
+          close-issue-message: "此 issue 因长期无活动已自动关闭，如有需要请重新开启"
+          days-before-pr-stale: 14
+          days-before-pr-close: 14
+          stale-pr-message: "此 PR 长期无活动，将在 14 天后自动关闭。如需继续讨论请回复"
+          close-pr-message: "此 PR 因长期无活动已自动关闭，如有需要请重新开启"

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,48 @@
+name: "Copilot Setup Steps"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-24.04
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.10.0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "pnpm"
+          cache-dependency-path: frontend/pnpm-lock.yaml
+
+      - name: Install JavaScript dependencies
+        working-directory: frontend
+        run: pnpm install
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.25"
+          check-latest: true
+
+      - name: Install dependencies
+        run: |
+          go mod download
+          go install github.com/swaggo/swag/cmd/swag@v1.16.6

.github/workflows/pr-template-check.yml

@@ -0,0 +1,32 @@
+name: Check PR Template Checklist
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+jobs:
+  check-pr-template:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: check all checklist items are checked
+        uses: actions/github-script@v7
+        with:
+          script: |
+            // get the pull request body
+            const prBody = context.payload.pull_request.body || '';
+
+            // regex to match all checklist items in the template
+            // matches lines like: - [ ] ... or - [x] ...
+            const checklistRegex = /^- \[( |x|X)\] .+$/gm;
+            const matches = prBody.match(checklistRegex) || [];
+
+            // check if any checklist item is not checked
+            const unchecked = matches.filter(line => line.startsWith('- [ ]'));
+
+            // if any unchecked, fail the workflow
+            if (unchecked.length > 0) {
+              core.setFailed(`PR checklist 未全部勾选，请确保所有 checklist 项都已勾选。未勾选项如下：\n${unchecked.join('\n')}`);
+            } else {
+              console.log('all checklist items are checked.');
+            }
+

.gitignore

@@ -11,7 +11,10 @@
 
 # config
 config.yaml
+manifest/config/config.yaml
 .env
+.env.*
+!.env.example
 
 # sqlite
 *.db
@@ -27,8 +30,6 @@ frontend/.next/*
 frontend/next-env.d.ts
 frontend/package-lock.json
 frontend/.env
-.env.*
-!.env.example
 *.tsbuildinfo
 
 # os
@@ -46,19 +47,56 @@ go.work.sum
 main
 
 # upload
-uploads/*
-
+/uploads/
 s3_cache
+
 /frontend/.next/
 /data/
 /internal/router/dist/
 /frontend/out/
-/.idea/
-/uploads/
-/*-source/
-/*-source.zip
-/.cache/
 /internal/router/root/dist/
 .dmux/
 
-.worktrees/
+# test coverage
+*.out
+coverage.*
+*.coverprofile
+profile.cov
+
+# generic ignores
+.cache
+.gocache*
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*-source
+*-source.zip
+.codex*
+.grok
+/.gomodcache/
+*.mmdb
+# Server control-plane MaxMind Country seed (Country only; Agent does not embed)
+!internal/apps/openflare/geoip/data/GeoLite2-Country.mmdb
+
+/.superpowers/
+/.worktrees/
+/.pi-subagents/
+
+# i18n 生成物（由 scripts/merge-i18n-fragments.mjs 从 fragments 生成）
+frontend/messages/zh-CN.json
+frontend/messages/en.json
+
+# 上游 vendoring 目录内禁止出现运行期产物
+backend/plugins/**/uploads/
+backend/plugins/**/dist/
+backend/core/**/dist/
+backend/pkg/**/uploads/
+/backend/openflare/plugins/server/upload/filesrv/uploads/
+/backend/plugins/domain/upload/filesrv/uploads/
+/backend/plugins/domain/upload/task/uploads/
+/backend/data/
+/backend/plugins/drivers/driver_http/dist/
+/backend/uploads/

AGENTS.md

@@ -64,100 +64,221 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 **These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
 
-## Git 提交规范
-
-遵循 Conventional Commits：`<type>(<scope>): <subject>`（例：`feat(auth): support email login`）。
-
-## 务必阅读匹配的 Skill
+## Skills（匹配任务时必读）
 
 | Skill | 何时使用 |
 | :--- | :--- |
-| `new-api` | 添加或修改自定义业务 API、Handler、服务层逻辑、自定义路由注册 |
-| `new-async-task` | 添加或修改 Asynq 任务、定时任务、TaskHandler、任务元数据 |
-| `new-setting` | 添加或修改系统/业务/公开设置、`/admin/system` 参数或 `/admin/settings` 图形化设置 |
-| `database-migration` | 数据库表结构变更、goose SQL 迁移（PG/SQLite/ClickHouse）、seed 数据 |
-| `logstore` | 日志/分析用途表、`internal/repository/logstore`、切换日志主库、PG/SQLite 回落 |
-| `clickhouse-batchwriter` | ClickHouse 批量写入、`internal/infra/persistence/batchwriter` 接入、分析表异步 flush、背压与写入路径改造 |
-| `file-upload` | 业务上传文件、Worker 程序化摄取、`upload.Ingest` 策略选型、文件访问与 `w_uploads` / 统计排查 |
-| `cache-framework` | 新增或修改业务缓存（RAM/Redis/DB 三层读路径）、缓存失效、多节点 pub/sub 同步、评估高频读是否应接入缓存 |
-| `push-notification` | 系统通知推送事件、统一触发器投递、带消息推送的业务功能 |
-| `release-guide` | 根据自上一正式版本 Tag 以来的提交整理 Version Bump 提交信息以触发双语 Release |
-| `shadcn` | 添加、修改或组合 shadcn/ui 组件 |
+| `new-api` | 业务 API、Handler、服务层、路由注册 |
+| `new-async-task` | Asynq 任务、定时任务、TaskHandler、任务元数据 |
+| `new-setting` | 系统/业务/公开设置、`/admin/system`、`/admin/settings` |
+| `database-migration` | 表结构、goose 迁移（PG/SQLite/ClickHouse）、seed |
+| `logstore` | 日志/分析用途表、`backend/internal/repository/logstore`、切换日志主库、PG/SQLite 回落 |
+| `clickhouse-batchwriter` | CH 批量写入、batchwriter、分析表 flush/背压 |
+| `file-upload` | 上传/摄取、`upload.Ingest`、文件访问、`w_uploads` |
+| `cache-framework` | 业务缓存（RAM/Redis/DB）、失效、多节点同步 |
+| `push-notification` | 通知推送事件、统一触发器、带推送的业务 |
+| `release-guide` | Version Bump 提交信息（触发双语 Release） |
+| `shadcn` | 添加/修改/组合 shadcn/ui 组件 |
 
-## 严格遵循事项 (Guardrails)
+## 硬性约束
 
-- 切勿删除 `frontend/node_modules`。
-- 保持 `internal/util/` 绝对纯净，禁止导入 Gin、GORM、sessions 等 Web/数据库框架包。
-- 测试用例禁止硬编码相对路径创建临时目录，统一使用 Go 内置 `t.TempDir()`。
-- 所有 HTTP 路由仅在 `internal/router/router.go` 中作为高层分发注册。
-- 修改 API Handler 后运行 `make swagger`，完成代码开发后必须依次运行 `make code-check` 与 `make format`。
-- 业务模块必须复用平台缓存/文件服务：文件摄取统一用 `upload.Ingest`，删除用 `upload.Remove`/`upload.RemoveOwned`；禁止直接写 `w_uploads` 或绕过 upload 域直接操作 `infra/objectstore`。
-- 禁止在 `init()` 中注册跨模块集成（任务 Handler、推送事件、域事件监听器等），统一在 `internal/platform/bootstrap` 显式装配并在 `internal/cmd` 入口调用。
-- 核心业务模块（`oauth`、`user`）禁止直接 import `push` 或 `custom_events` 触发通知，须通过 `internal/listener` 发射域事件。
-- API 错误响应必须通过 `response.Abort*` 中断请求，由 `ErrorHandlerMiddleware` 统一写出 JSON 并记录 Trace；禁止在 Handler/中间件中直接 `c.JSON(status, response.Err(...))` 或 `200` 返回 `error_msg`。
+### 上游/下游改动归属（Cordis）
+
+- 触碰框架目录 `backend/{core,pkg,plugins}` 前，先判断能力归属：
+  - **通用能力**（与 OpenFlare 业务无关、任何下游都用得上）→ 必须同步在 **Wavelet 上游**完成修改，
+    本仓库通过 `git fetch wavelet && git merge wavelet/main` 取得，不得长期持有本地补丁。
+  - **非通用能力**（OpenFlare 业务特有）→ 在自己的插件内（`backend/openflare/plugins/<name>/`）实现，
+    或新建一个下游插件，禁止塞进上游目录。
+- 开发下游功能优先**复用上游已有能力**（`core/contracts`、`backend/plugins/*`、`backend/pkg/*`）；
+  发现上游已提供而下游仍保留本地副本的，删除本地副本改为复用，或把差量回流上游。
+- 上游暂缺而确属通用能力时，可先在本仓库实现并登记到 `backend/openflare/upstream-patches.md`
+  （merge 上游后请确认补丁仍在），回流 Wavelet 后删除登记并重新 merge。
+
+### Cordis 架构核心防线与分层规范
+- **微内核 (`backend/core/`)**：
+  - 上下文总线（`Context`）、泛型依赖注入（`Container`）、生命周期编排（`Lifecycle`）、扩展点定义（`extpoints/`）与领域事件总线（`EventBus`）。
+  - **严禁**包含任何具体业务逻辑，**严禁** import `gin`、`gorm`、`asynq` 等具体运行时依赖。
+- **服务契约 (`backend/core/contracts/`)**：
+  - 跨插件通信的统一公开 Go Interface（如 `AuthService`、`UserService`、`CacheService`、`DBService`、`StorageService`）与公共 DTO。
+  - **严禁**包含任何具体业务实现或 SQL 操作。
+- **自包含插件 (`backend/plugins/`)**：
+  - 所有业务功能与驱动实现均以插件形式存在（`backend/plugins/drivers/`、`backend/plugins/infra/`、`backend/plugins/domain/` 或下游 `backend/openflare/plugins/`）。
+  - 每个插件实现 `core.Plugin`（`Name() string` 与 `Apply(ctx *core.Context) error`）。
+  - **统一插件分层架构与标准模板**：
+    - **开发模板唯一基准**：所有插件统一以 `backend/downstream/plugins/custom_example` 为基准模板构建。
+    - **物理子包隔离规范**：统一采用物理子包结构（`plugin.go`, `consts/`, `controller/`, `service/`, `dao/`, `model/` [含 `entity/`, `do/`], `migrations/` [含 `postgres/`, `sqlite/`]）。**严禁在根包平铺 `handlers_*`、`service_*`、`dao_*` 等前缀文件**，子包内文件直接按业务实体命名（如 `hello.go`, `user.go`），严格约束 `controller -> service -> dao -> model` 单向依赖。
+- **插件通信与依赖隔离**：
+  - **严禁跨包 import internal/私有实现**：插件之间严禁直接 import 对方具体实现包代码。
+  - **单向服务契约调用**：调用方仅面向 `backend/core/contracts` 编程，在 `Apply` 中通过 `core.Provide[contracts.XxxService](ctx, svc)` 注册服务，通过 `core.Inject[contracts.XxxService](ctx)` 或 `ctx.Using(func(svc contracts.XxxService) { ... })` 声明式解析。
+  - **事件总线广播**：状态联动与解耦通信统一通过强类型事件 `ctx.Events().Emit()` 广播，由感兴趣的插件通过 `ctx.Events().On()` 订阅，消除双向依赖与循环引用。
+- **扩展点自包含注册**：
+  - **HTTP 路由与白名单机制**：
+    - 插件自包含在 `Apply` 中通过 `ctx.Router().Group(...)` 挂载路由与中间件，禁止跨插件散落注册。
+    - **白名单机制**：`driver_http` 与微内核扩展点提供路由白名单支持（`ctx.Router().RegisterWhitelist(patterns...)`），支持精确路径与通配符（如 `/api/v1/oauth/*`）。
+    - **所有权主动声明**：认证域（`auth` 插件）与各业务插件必须在 `Apply` 中主动注册其公开/免鉴权接口（如 `/api/v1/user/login`、`/api/v1/oauth/callback`、`/api/v1/cap/*` 等）。
+    - **鉴权中间件放行防线**：`auth` 提供的登录鉴权中间件（`LoginRequired`）必须先执行白名单匹配并自动放行，彻底杜绝免鉴权接口被全局或组级鉴权中间件误拦截（返回 401 Unauthorized）。
+  - **异步与定时任务**：插件自包含在 `Apply` 中通过 `ctx.Task().Register(...)` 与 `ctx.Schedule().RegisterCron(...)` 声明。
+  - **静态启动配置**：插件自包含在 `Apply` 中通过 `ctx.Config().Bind("<prefix>", &cfg)` 读取**自己声明**的配置，字段以 tag 表达来源：`config`（yaml 路径）、`env`（覆盖变量名）、`default`、`autoEnable`（该变量存在即置真）、`secret`（导出脱敏）。需要在 `Apply` 之前被门禁求值的键，必须在 `DeclareConfig()` 中提前声明并实现 `core.ConfigGatedPlugin`。新增基础设施 key 保持顶层命名（`redis.*`），插件私有配置归 `plugins.<name>.*`。**严禁**再造全局配置单例或在 `backend/pkg/` 读取配置。
+  - **动态设置**：插件自包含在 `Apply` 中通过 `ctx.Settings().Register(core.SettingSchema{...})` 声明可热更新的管理台设置模式（与上面的静态启动配置分属两层）。
+  - **数据迁移**：插件自包含在内部维护 `migrations/*.sql`，通过 `//go:embed` 打包并在 `Apply` 中通过 `ctx.Migrations().Register(pluginID, embedFS)` 注入。
+- **表单一所有者原则 (Single Owner Principle)**：
+  - 每张数据表有且仅由一个所有者插件声明与维护（表名使用插件前缀如 `w_order_*`）。
+  - 严禁插件 B 跨过所有者插件 A 直接 DDL/DML 旁路读写表 A，必须调用插件 A 暴露的 `contracts` 接口或订阅事件。
+- **平台服务复用**：
+  - 文件摄取统一使用 `upload.Ingest` / `contracts.StorageService`，禁止绕过存储域直接操作底层 Bucket 或直写文件表。
+  - 业务缓存统一使用 `ctx.Cache()`（`contracts.CacheService`）或标准缓存框架，禁止自研不带失效广播的本地 map。
+  - 数据库操作通过 `ctx.DB()`（`contracts.DBService`）获取受事务与 Trace 保护的连接。
+
+- 禁止删除 `frontend/node_modules`。
+- `backend/pkg/util/` 保持纯净：禁止导入 Gin、GORM、sessions 等 HTTP/Web/DB 框架（会话选项在 `backend/openflare/plugins/server/oauth/session.go`）。
+- 测试临时目录只用 `t.TempDir()`，禁止硬编码相对路径写源码树。
+- HTTP 路由只由插件在 `Apply` 中经 `ctx.Router()` 声明；`router.BuildEngine()` 只挂引擎级中间件与前端 SPA 兜底，禁止进程级初始化（如 `SyncEvents`、`InitLogWriter`）。
+- API 变更后：`make swagger`；开发完成：`make code-check`；提交前：`make format`。
+- 缓存/文件管理复用平台实现，业务包禁止自建缓存目录或旁路存储后端。
+- 文件摄取走 `upload.Ingest`（`PolicyCreate` / `PolicyDedupNewRecord` / `PolicyResolveExisting`）；删除走 `upload.Remove` / `upload.RemoveOwned`。禁止业务直接 `repository.CreateUpload` / `SoftDeleteUpload` 或 `db.Create(&model.Upload{})`。
 - **分层**：`apps → repository → model`，`repository → infra/persistence`；禁止 `model → repository`。
   - `model`：实体、表名、配置 key、查询 DTO、无 IO 规则。禁止 `db.DB` / Redis / CH；禁止 `import repository`。GORM hook 仅可 mutate 自身字段，禁止在 hook 内再查 DB/缓存。
   - `repository`：唯一持久化入口。apps/logics 禁止为业务 CRUD 直调 `db.DB`（管理端 SQL 控制台、infra 内部等例外保留）。禁止新增 `model.Get/List/Create/...` 类数据访问 API。
-- 日志/分析表（访问日志、审计流水、可观测时序）走 `internal/repository/logstore`，禁止 apps 直连 `repository/analytics` 或 `db.ChConn`/`db.ChDB`。判定与接入步骤见 `logstore` skill。
+- 日志/分析表（节点访问日志、用户访问日志、可观测时序）走 `backend/openflare/plugins/server/kernel/repository/logstore`，禁止 apps 直连 `repository/analytics` 或 `db.ChConn`/`db.ChDB`。判定与接入步骤见 `logstore` skill。
+- 跨模块集成（任务 Handler、推送事件、域监听、完成钩子）禁止 `init()` 注册；经 `backend/openflare/plugins/server/platform/bootstrap` 在 `backend/cmd` 入口显式装配。
+- 核心业务（如 `oauth`、`user`）禁止直接 import push/custom_events；经 `backend/openflare/plugins/server/listener` 发域事件，push 在 bootstrap 订阅。
+- 依赖任务/推送注册的测试须显式 `bootstrap.RegisterTasks()` / `RegisterPushDomainEvents()` 等，不依赖 `init()`。
+- API 错误必须 `response.Abort*` + `ErrorHandlerMiddleware`；禁止 Handler 直接 `c.JSON(..., response.Err(...))` 或用 HTTP 200 表示失败。
 
-## 技术栈与项目目录结构
+### 文档与 Changelog
 
-### 技术栈
-- **后端**：Go 1.25+、Gin、GORM、PostgreSQL、可选 ClickHouse、Redis、Asynq、Cobra、Viper、Swaggo、OpenTelemetry、Zap、AWS SDK v2。
-- **前端**：Next.js (App Router)、TypeScript、Tailwind CSS、pnpm、shadcn/ui。
+- 内容变更同步**中文文档**（不同步英文）。
+- 代码/配置变更写入 [`docs/changelog/index.md`](./docs/changelog/index.md) 的 `[Unreleased]`；纯文档变更不写 changelog。
+- Changelog：合并相近项；不记格式化/调试/无关重构；用户可读完整中文句；说明效果；不编造；不写密钥等敏感信息；空分类可省略。
 
-## 后端开发规范
+## 技术栈
 
-### API 响应规范
-- **统一信封**：`{ "error_msg": "", "data": ... }`
-- **成功**：HTTP 200，写出 `c.JSON(http.StatusOK, response.OK(data))` 或 `response.OKNil()`。
-- **失败**：使用 `internal/shared/response` 的 `Abort*` 系列函数（如 `AbortBadRequest`、`AbortUnauthorized`、`AbortNotFound`、`AbortInternal`）中断请求。
-- **错误文案**：使用模块内 `errs.go` 中的 camelCase 字符串常量（如 `errBindParamsFailed`），禁止暴露底层数据库/系统错误细节给客户端。
-- **Logics 分工**：`logics.go` 只接受 `context.Context`，返回 `(result, error)`，严禁依赖 `*gin.Context` 或调用 `c.JSON`/`Abort*`。
-- **错误日志**：底层错误在 Handler/Logic 边界用 `pkg/logger` 打印日志，禁止使用 `_ = ...` 静默吞掉关键错误。
+- **后端**：Go 1.25+、Gin、GORM、PostgreSQL、可选 ClickHouse、Redis、Asynq、Cobra、Viper、Swaggo、OTel、Zap、AWS SDK v2、Snowflake IDs
+- **前端**：Next.js App Router、TypeScript、Tailwind、pnpm、shadcn/ui
 
-### 数据库操作
-- 平台域（user、auth_source、access_token、schedule、task_execution）的持久化必须走 `internal/repository`，禁止在 `internal/model` 中调用 `db.DB` / Redis。
-- 管理员代码推荐使用 `db.DB(ctx)`（`internal/infra/persistence`，包名 `db`）保证 Trace 链路透传。
-- 禁止在 Handler 写复杂 SQL；迁移文件位于 `internal/infra/persistence/migrator/goose/`（禁止 GORM AutoMigrate）。
-- 不创建物理外键（显式建索引）；Go 模型零值需与数据库默认值匹配。
-- **SQL LIKE 查询防注入与转义**：所有含用户输入的模糊查询必须调用 `pkg/util.EscapeLike` 转义通配符，并显式指定 `ESCAPE '\\'` 语法（如 `Where("username LIKE ? ESCAPE '\\'", util.EscapeLike(keyword)+"%")`），同时兼容 PostgreSQL 与 SQLite 方言并杜绝通配符注入攻击。
+## Git
 
-### 并发与安全防护规范
-- **Goroutine 安全**：禁止直接使用裸 `go func()`；统一使用 `pkg/util.Go`，确保具备未捕获 panic 恢复和调用栈日志记录能力。
-- **Pub/Sub 监听并发安全**：启动 Redis Pub/Sub 订阅监听前，必须捕获局部客户端实例（如 `redisClient := db.Redis`），禁止在 goroutine 闭包中直读可变全局 `db.Redis`；提供 `Stop*Listener` 时必须维护 `done` 通道等待 goroutine 完整退出后再重置状态，消除测试或重连时的数据竞争。
-- **Session 固定攻击防御**：用户登录/授权成功后，必须调用 `oauth.SetLoginSession`（内部执行 Session ID 轮换），防止 Session 固定攻击。
-- **防账户枚举与时序攻击**：
-  - 登录失败统一返回模糊报错；当查询用户不存在时，必须调用 `pkg/util.DummyCheckPassword` 执行同等开销的 bcrypt 哈希计算，彻底消除时序侧信道攻击。
-  - 验证码、签名 Token 等敏感字符串比对必须使用 `crypto/subtle.ConstantTimeCompare` 常量时间比对。
-- **敏感端点限流**：登录尝试、OAuth 授权发起等敏感接口必须接入基于 Redis 的滑动窗口限流机制，防止暴力破解与缓存资源耗尽。
+Conventional Commits：`<type>(<scope>): <subject>`（例：`feat(auth): support email login`）。
 
-## 前端开发规范
+---
 
-- 新特性开发前参考 Next.js 文档与 `frontend/app/(main)/admin/demo` 示例代码。
-- **页面容器与标题栏**：
-    - 页面根容器统一使用全宽 `w-full`，最外层统一用 `py-6` 或 `py-6 px-1` 对齐边距。
-    - 标题容器统一 `flex items-center gap-2`（带操作按钮用 `justify-between`）。
-    - 图标直接使用 Lucide 组件（`size-5 text-primary`），禁止包裹背景小卡片或装饰边框。
-    - 标题文字统一使用 `<h1 className="text-2xl font-semibold tracking-tight">`。
-- **无障碍语义与色彩规范 (a11y & WCAG)**：
-    - **标题层级规范 (Heading Hierarchy)**：页面中非顶级结构化标题（如空状态提示、加载提示、卡片眉题/卡片标题、抽屉区块名）严禁滥用 `<h3>`/`<h4>`，统一使用 `<p>` 配合样式，保证屏幕阅读器感知的标题层级连续。
-    - **无文本控件无障碍**：所有仅包含图标的按钮（如仅有 Icon 的 Button、Switch、无文本的 SelectTrigger）必须显式添加 `aria-label`。
-    - **色彩对比度**：正文、提示、徽章等小字颜色在亮色/暗色模式下必须满足 WCAG AA（对比度 ≥ 4.5:1）。
-- **组件拆分与维护**：
-    - 物理路由页面 `page.tsx` 仅维护高级骨架与布局。
-    - 单文件超过 600 行或含多 Tab/大复杂区块时，必须按就近原则拆分为子组件存放在路由同级的 `components/` 局部目录中（参考 `/admin/database` 的模块化拆分结构）。
-- **样式与服务**：
-    - 优先使用 shadcn/ui 的 `variant` 和全局 CSS 变量，不要在业务代码中硬编码颜色/背景。
-    - 前端请求统一在 `frontend/lib/services/<name>/` 中继承 `BaseService` 编写并在 `index.ts` 注册。
-- **国际化 (i18n)**：
-    - 使用 `next-intl`（**无 URL locale 前缀** / non-routing provider 模式），兼容 `NEXT_STANDALONE_EXPORT` 静态导出。
-    - 支持语言：`zh-CN`、`en`；默认 `zh-CN`。
-    - 解析优先级：cookie `NEXT_LOCALE`（用户显式选择）→ 浏览器语言 → 默认 `zh-CN`。
-    - 文案统一放在 `frontend/messages/{locale}.json`，按命名空间嵌套（`common` / `layout` / `auth` / `settings` / 业务域）。
-    - 组件内用户可见文案必须通过 `useTranslations()` / `getTranslations()` 读取；**禁止**新增中英硬编码 UI 字符串（后端返回的 `error_msg`、日志、调试信息除外）。
-    - key 使用 camelCase 分层（如 `auth.login.submit`）；完整短语作为 value，禁止在组件内拼接句子。
-    - 新增或修改文案时必须**同步**更新 `zh-CN.json` 与 `en.json`，保持 key 树一致。
-    - 语言选项展示用自称：`中文` / `English`（不随当前 UI 语言翻译）。
-    - 日期/数字格式化使用 locale 感知 helper（如 `formatDateTime`），禁止写死 `'zh-CN'` / `date-fns` 的 `zhCN`（除非该路径尚未迁移且不在本次改动范围）。
-    - 设计说明见 `docs/superpowers/specs/2026-07-24-frontend-i18n-design.md`。
+## 后端
+
+### 命名
+
+| 类别 | 规则 | 例 |
+|------|------|-----|
+| 包/文件 | 小写蛇形 | `auth_source`、`postgres_logger.go` |
+| 导出/未导出标识符 | PascalCase / camelCase | — |
+| 请求/响应结构体 | camelCase + 后缀 | `listUsersRequest` |
+| 错误文案常量 | camelCase 字符串 `const`（非包级 `error`） | `errBindParamsFailed` |
+| YAML 键 | 小写蛇形 | — |
+
+### Handler
+
+- 命名：动词 + 名词（`ListUsers`）；绑定用 `ShouldBindQuery` / `ShouldBindJSON`。
+- 每个 HTTP API 需完整 Swagger 注释；API 变更后 `make swagger`。
+- Handler：绑定 → 调 logic → 映射为 `Abort*` 或 `response.OK`。
+- `logics.go`：接受 `context.Context`，返回结果/error；**禁止**依赖 `*gin.Context`、调用 `Abort*` / `c.JSON`。参考 `backend/internal/apps/user/logics.go`。
+
+### API 响应
+
+信封：`{ "error_msg": "", "data": ... }`。成功 `error_msg` 空、`data` 为载荷；失败 `data` 为 `null`。分页：`data: { total, results }`。
+
+**成功**（始终 HTTP 200）：
+
+```go
+c.JSON(http.StatusOK, response.OK(data))
+c.JSON(http.StatusOK, response.OKNil())
+```
+
+**失败**：仅用 `response.Abort*`（挂 `c.Errors` 并 `Abort`，由 `ErrorHandlerMiddleware` 统一写出并记 OTel）,阅读/internal/shared/response/abort.go使用已有函数
+
+中间件同规则（`oauth.LoginRequired` → Unauthorized；`admin.LoginAdminRequired` → NotFound；`cap.VerifyMiddleware` → Unauthorized）。
+
+- 用户可见错误：模块内 `errs.go` 的 camelCase 字符串常量；禁止向客户端暴露驱动错误/堆栈。
+- `response.Err` 仅供中间件构造 JSON，业务禁止用于 `c.JSON`。
+
+**禁止**：`c.JSON(200, response.Err(...))`；Handler 直接 `c.JSON(4xx/5xx, response.Err(...))`；手写 `gin.H` 错误体；在 `logics.go` 里 `Abort*`。
+
+Swagger：`@Success 200` 用具体类型或 `response.Any`；每个可能 Abort 状态声明 `@Failure`。
+
+### 日志
+
+- 运行时错误（DB/Redis/第三方/IO）在 Handler 或 logic 边界用 `backend/pkg/logger`（带 `ctx`）记录，再返回安全 Abort/业务错误。
+- 吞错、转通用响应、worker 忽略前必须先记日志。
+- 禁止 `_ = err` 静默丢弃重要错误；best-effort 可忽略时加简短注释。
+- 只在处理/抑制边界记一次，避免重复刷日志。
+
+### 路由与装配
+
+- `router.go` 只做高层分发，禁止直接挂业务 Handler。归属与开发步骤见 `new-api` skill。
+- 跨模块副作用：在 `bootstrap` 增 `Register*`，于对应 `backend/internal/cmd/*.go` 调用（`RegisterAPI` / `RegisterWorker` / `RegisterAll`）。
+- API/`all` 模式：`bootstrap.Init` 须在 `RegisterPushDomainEvents()` **之后**调用，保证 `SyncEvents` 同步内置推送元数据。
+
+### 中间件
+
+- 全局：`gin.Recovery()`、`otelgin`、日志、session。
+- 登录组：`oauth.LoginRequired()`；管理组：`admin.LoginAdminRequired()`。
+
+### 配置
+
+- 运行时只读 `config.Config`，禁止 `os.Getenv()`。
+- 新增配置同步 `config.example.yaml` 与 `backend/internal/infra/config/model.go`。
+
+### 数据库
+
+- 持久化只经 `repository`（或 analytics）；复杂查询不进 Handler；编排在 logics。
+- repository 内用 `db.DB(ctx)`（链路追踪）。
+- 迁移：`backend/internal/infra/persistence/migrator/goose/` SQL；禁止 GORM AutoMigrate。
+- 不建物理外键，关系字段加显式索引。
+- 列默认值与 Go 零值（`nil`/`0`/`false`/`""`）一致。
+
+---
+
+## 前端
+
+- Next.js：以 `node_modules/next/dist/docs/` 为准（训练数据可能过时）。
+- 示例：`frontend/app/(main)/admin/demo`。
+
+### 样式
+
+- shadcn 用 `variant` + CSS 变量；业务 `className` 不硬编码颜色/背景/阴影。
+- 变体不足时扩展组件 variant，不写一次性颜色。
+
+### 页面结构
+
+- 根容器全宽 `w-full`；禁止页面级 `max-w-*`（主布局负责宽度）。
+- 外层间距：`py-6` 或 `py-6 px-1`。
+- 标题行：`flex items-center gap-2`（有右侧操作则加 `justify-between`）。
+- 图标：Lucide 直接放标题容器，`size-5 text-primary`；禁止背景卡片/边框包裹。
+- 标题：仅 `h1 className="text-2xl font-semibold tracking-tight"`。
+- 多 Tab：各 Tab 独立文件；`page.tsx` 只管 Tabs 状态与触发器；禁止 `page.tsx` 仅转发同名空壳。
+- 单文件 > ~600 行或状态过重时拆局部 `components/`；跨页复用放 `frontend/components/common/`。标杆：`/admin/database`。
+
+### 组件放置
+
+| 类型 | 路径 |
+|------|------|
+| 跨页业务 | `frontend/components/common/` |
+| shadcn 原语 | `frontend/components/ui/` |
+| 路由专属 | 邻近 feature 目录 |
+
+### Services
+
+```text
+frontend/lib/services/<name>/
+  types.ts
+  <name>.service.ts
+  index.ts
+```
+
+- 继承 `BaseService`，定义 `basePath`，有类型静态方法；在 `frontend/lib/services/index.ts` 注册。
+- 回调/`mutationFn`/`queryFn` **禁止**直接传静态方法引用（丢 `this`）；用箭头：`(p) => XxxService.create(p)`。
+
+### 国际化 (i18n)
+
+- 使用 `next-intl`（无 URL locale 前缀 / provider 模式），兼容 `NEXT_STANDALONE_EXPORT`。
+- 语言：`zh-CN`、`en`；默认 `zh-CN`。优先级：cookie `NEXT_LOCALE` → 浏览器语言 → 默认。
+- 文案放在 `frontend/messages/fragments`。参考已有代码，按模块拆文件夹，en.json 和 zh-CN.json 是 ci 生成的(node scripts/merge-i18n-fragments.mjs)，禁止手动修改。
+- 禁止在页面/组件里直接写文案，文案必须支持 i18

CONTRIBUTING.md

@@ -20,6 +20,16 @@
 为提高协作效率，我们建议您在提交 PR 前，先通过 Issue 简要说明动机与背景。  
 
 
+## 合并上游
+
+`.gitattributes` 对 `backend/openflare/`、`frontend/` 等路径使用 `merge=ours`。该驱动不会自动生效，请在仓库根目录执行一次：
+
+```bash
+git config include.path ../.gitconfig
+# worktree 安全写法：
+git config include.path "$(git rev-parse --show-toplevel)/.gitconfig"
+```
+
 ## 贡献步骤
 
 1. **Fork 本仓库** 并创建您的分支（建议使用有意义的分支名）。

Makefile

@@ -1,8 +1,8 @@
-.PHONY: swagger license license-check build-embedded build-test cross-build code-check format canary
+.PHONY: swagger license license-check format build-embedded build-test cross-build code-check build-backend build-frontend build-agent build-relay build-flared build-all
 
 VERSION ?= dev
 BUILD_DATE ?= $(shell date -u +'%Y-%m-%dT%H:%M:%SZ')
-MODULE := $(shell go list -m)
+MODULE := $(shell cd backend && go list -m)
 
 swagger:
 	scripts/swagger.sh
@@ -14,9 +14,13 @@ license-check:
 	scripts/update_go_license.sh --check
 
 format:
-	@echo "==> Formatting backend Go source..."
-	gofmt -w $$(find . -type f -name '*.go' -not -path './.git/*' -not -path './frontend/*')
-	@echo "==> Formatting frontend source..."
+	@echo "==> Formatting backend Go source and removing unused imports..."
+	@command -v goimports >/dev/null 2>&1 || { \
+		echo "goimports not found, installing..."; \
+		go install golang.org/x/tools/cmd/goimports@latest; \
+	}
+	goimports -w $$(find backend -type f -name '*.go')
+	@echo "==> Formatting frontend source and removing unused imports..."
 	cd frontend && pnpm format
 
 build-embedded:
@@ -25,31 +29,55 @@ build-embedded:
 		NEXT_PUBLIC_APP_VERSION="$(VERSION)" \
 		NEXT_PUBLIC_APP_BUILD_DATE="$(BUILD_DATE)" \
 		pnpm build:embed
-	rm -rf internal/router/root/dist
-	cp -R frontend/out internal/router/root/dist
-	go build \
+	rm -rf backend/plugins/drivers/driver_http/dist
+	cp -R frontend/out backend/plugins/drivers/driver_http/dist
+	test -f backend/plugins/drivers/driver_http/dist/index.html
+	cd backend && go build \
 		-tags embed_frontend \
-		-ldflags "-s -w -X '$(MODULE)/internal/buildinfo.Version=$(VERSION)' -X '$(MODULE)/internal/buildinfo.BuildTime=$(BUILD_DATE)'" \
-		-o bin/wavelet \
+		-ldflags "-s -w -X '$(MODULE)/pkg/buildinfo.Version=$(VERSION)' -X '$(MODULE)/pkg/buildinfo.BuildTime=$(BUILD_DATE)'" \
+		-o ../bin/openflare-server \
 		main.go
 
 code-check:
 	@echo "==> Architecture guards..."
-	@command -v rg >/dev/null 2>&1 || { echo 'error: rg (ripgrep) is required for architecture guards' >&2; exit 1; }
-	@if rg -n 'db\.DB\(|db\.Redis' internal/model --glob '*.go' -g '!*_test.go' ; then \
+	scripts/check_cordis_architecture.sh
+	@if rg -n 'db\.DB\(|db\.Redis' backend/openflare/plugins/server/kernel/model --glob '*.go' -g '!*_test.go' ; then \
 		echo 'error: internal/model must not access db.DB or db.Redis (non-test code)' >&2; \
 		exit 1; \
 	fi
-	golangci-lint run
-	cd frontend && pnpm tsc --noEmit --jsx preserve && npx eslint . --max-warnings 0
+	cd backend && golangci-lint run
+	cd frontend && node scripts/merge-i18n-fragments.mjs && pnpm tsc --noEmit --jsx preserve && npx eslint . --max-warnings 0
 
 build-backend:
 	@echo "==> Building backend version=$(VERSION) build_date=$(BUILD_DATE)..."
-	go build \
-		-ldflags "-s -w -X '$(MODULE)/internal/buildinfo.Version=$(VERSION)' -X '$(MODULE)/internal/buildinfo.BuildTime=$(BUILD_DATE)'" \
-		-o bin/wavelet \
+	cd backend && go build \
+		-ldflags "-s -w -X '$(MODULE)/pkg/buildinfo.Version=$(VERSION)' -X '$(MODULE)/pkg/buildinfo.BuildTime=$(BUILD_DATE)'" \
+		-o ../bin/openflare-server \
 		main.go
 
+build-agent:
+	@echo "==> Building agent version=$(VERSION)..."
+	cd backend && go build \
+		-ldflags "-s -w -X '$(MODULE)/openflare/plugins/agent/config.Version=$(VERSION)'" \
+		-o ../bin/openflare-agent \
+		cmd/agent/main.go
+
+build-relay:
+	@echo "==> Building relay version=$(VERSION)..."
+	cd backend && go build \
+		-ldflags "-s -w -X '$(MODULE)/openflare/plugins/relay/config.Version=$(VERSION)'" \
+		-o ../bin/openflare-relay \
+		cmd/relay/main.go
+
+build-flared:
+	@echo "==> Building flared version=$(VERSION)..."
+	cd backend && go build \
+		-ldflags "-s -w -X '$(MODULE)/openflare/plugins/flared/config.Version=$(VERSION)'" \
+		-o ../bin/flared \
+		cmd/flared/main.go
+
+build-all: build-backend build-agent build-relay build-flared
+
 build-frontend:
 	@echo "==> Building frontend version=$(VERSION) build_date=$(BUILD_DATE)..."
 	cd frontend && \
@@ -62,7 +90,7 @@ build-test:
 	@PIDS=""; \
 	STATUS=0; \
 	( cd frontend && pnpm build:embed 2>&1 | sed 's/^/[frontend] /' ) & PIDS="$$PIDS $$!"; \
-	( go test ./... && go build -o /dev/null ./... 2>&1 | sed 's/^/[backend]  /' ) & PIDS="$$PIDS $$!"; \
+	( cd backend && go test ./... && go build -o /dev/null ./... 2>&1 | sed 's/^/[backend]  /' ) & PIDS="$$PIDS $$!"; \
 	for PID in $$PIDS; do \
 		wait $$PID || STATUS=1; \
 	done; \
@@ -80,7 +108,7 @@ cross-build:
 	(version=$(or $(VERSION),dev))..."
 	@mkdir -p bin
 	docker build \
-		--file docker/Dockerfile.cross \
+		--file manifest/docker/Dockerfile.cross \
 		--target export \
 		--build-arg VERSION=$(or $(VERSION),dev) \
 		--build-arg BUILD_DATE="$(shell date -u +'%Y-%m-%dT%H:%M:%SZ')" \
@@ -97,14 +125,14 @@ dev-f:
 
 dev-b:
 	@echo "==> Starting backend development server..."
-	go run main.go all
+	cd backend && go run main.go all
 
 dev:
 	@echo "==> Starting frontend and backend development servers in parallel..."
 	@PIDS=""; \
 	STATUS=0; \
 	( cd frontend && pnpm dev 2>&1 | sed 's/^/[frontend] /' ) & PIDS="$$PIDS $$!"; \
-	( go run main.go all 2>&1 | sed 's/^/[backend]  /' ) & PIDS="$$PIDS $$!"; \
+	( cd backend && go run main.go all 2>&1 | sed 's/^/[backend]  /' ) & PIDS="$$PIDS $$!"; \
 	for PID in $$PIDS; do \
 		wait $$PID || STATUS=1; \
 	done; \

NOTICE

@@ -1,9 +1,9 @@
-Wavelet
+OpenFlare
 
-This product includes software derived from LinuxDO Credit.
+This product includes software derived from Wavelet.
 
-LinuxDO Credit:
-Copyright 2025 linux.do
+Wavelet:
+Copyright 2025 Arctel.net
 Licensed under the Apache License, Version 2.0.
 
 This distribution includes modifications by Arctel.net.

README.md

@@ -1,352 +1,192 @@
-# wavelet
+<div align="center">
 
-🚀 A modern, production-ready full-stack boilerplate for building scalable web applications
+# OpenFlare
 
-[中文](./README_zh.md)
+**[English](./README.md) | [简体中文](./README.zh-CN.md)**
 
-[![License: Apache2.0](https://img.shields.io/badge/License-Apache2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Go Version](https://img.shields.io/badge/Go-1.25+-blue.svg)](https://golang.org/)
-[![Next.js](https://img.shields.io/badge/Next.js-16-black.svg)](https://nextjs.org/)
-[![React](https://img.shields.io/badge/React-19-blue.svg)](https://reactjs.org/)
+OpenFlare is an open-source CDN orchestration and edge security platform. It supports reverse proxy, centralized configuration synchronization, in-network tunneling (Tunnels), dynamic WAF protection, and CC defense challenges.
 
-## 📖 Introduction
+</div>
 
-**wavelet** is a generic, production-ready full-stack boilerplate built with **Go (Gin + GORM)** on the backend and **Next.js (App Router + Shadcn UI)** on the frontend. It ships with everything you need to bootstrap a modern SaaS, internal tool, or developer platform — without the boilerplate headaches.
+<p align="center">
+  <a href="https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/LICENSE">
+    <img src="https://img.shields.io/github/license/Rain-kl/OpenFlare?color=brightgreen" alt="license">
+  </a>
+  <a href="https://github.com/Rain-kl/OpenFlare/releases/latest">
+    <img src="https://img.shields.io/github/v/release/Rain-kl/OpenFlare?color=brightgreen&include_prereleases" alt="release">
+  </a>
+  <a href="https://github.com/Rain-kl/OpenFlare/pkgs/container/openflare">
+    <img src="https://img.shields.io/badge/GHCR-ghcr.io%2Frain--kl%2Fopenflare-brightgreen" alt="ghcr">
+  </a>
+</p>
 
-The project was designed from the ground up to be **framework-first and business-agnostic**: plug in your own domain logic while reusing the battle-tested infrastructure that comes out of the box.
+> [!WARNING]
+> After the first login with the `admin` user, you must change the default password `12345678`.
+>
+> The BETA version is a temporary product in the development and testing stage and may have unknown issues. It should not be used in production environments.
 
-### ✨ Key Features
+## Documentation
 
-- 🔐 **Multi-auth System** — Local password login/registration + pluggable OIDC/OAuth2 providers (supports multiple auth sources simultaneously)
-- 🗝️ **Personal Access Tokens** — API key management for programmatic access; supports `Authorization: Bearer` and `X-Access-Token` headers
-- 👤 **User Management** — Admin panel for listing, searching, filtering, enabling/disabling user accounts
-- ⚙️ **Dynamic System Config** — Key-value system configuration management with live reload, controllable from the admin UI
-- 📋 **Async Task Queue** — Background job processing with [Asynq](https://github.com/hibiken/asynq) (Redis-backed), including a scheduling dashboard
-- 📁 **S3 File Storage** — Unified file upload/download via S3-compatible APIs with local disk cache
-- 📊 **Observability** — Structured logging (Zap) + distributed tracing (OpenTelemetry)
-- 🎨 **Modern UI** — Responsive, dark-mode-ready design system built with Tailwind CSS 4 and Shadcn UI
-- 📖 **Built-in Documentation** — Integrated docs portal with usage guides, API reference, privacy policy, and terms of service
+**https://openflare.fyrn.link**
 
-## 🏗️ Architecture Overview
+Common entry points:
 
-```
-┌─────────────────┐    ┌─────────────────────────────┐    ┌─────────────────┐
-│   Frontend      │    │          Backend             │    │   Database      │
-│   (Next.js)     │◄──►│           (Go)               │◄──►│  (PostgreSQL)   │
-│                 │    │                              │    │                 │
-│ • React 19      │    │ • Gin HTTP Framework         │    │ • PostgreSQL    │
-│ • TypeScript    │    │ • GORM ORM                   │    │ • Redis Cache   │
-│ • Tailwind 4    │    │ • Multi-provider Auth        │    │                 │
-│ • Shadcn UI     │    │ • AccessToken Middleware     │    │                 │
-│                 │    │ • Asynq Task Queue           │    │                 │
-│                 │    │ • OpenTelemetry Tracing      │    │                 │
-│                 │    │ • Swagger API Docs           │    │                 │
-└─────────────────┘    └─────────────────────────────┘    └─────────────────┘
-                                      │
-                           ┌──────────┴──────────┐
-                           │   Multi-Process CLI  │
-                           │  (Cobra + Viper)     │
-                           │ • api      (HTTP)    │
-                           │ • worker   (Queue)   │
-                           │ • scheduler(Cron)    │
-                           └─────────────────────┘
-```
+* [Quick Start](https://openflare.fyrn.link/guide/quick-start)
+* [Deployment Guide](https://openflare.fyrn.link/deployment/deployment)
+* [Configuration Reference](https://openflare.fyrn.link/reference/configuration)
+* [System Design](https://openflare.fyrn.link/design/)
 
-## 🛠️ Tech Stack
+## Core Capabilities
 
-### Backend
-- **[Go 1.25+](https://go.dev/doc)** — Primary language
-- **[Gin](https://github.com/gin-gonic/gin)** — HTTP web framework
-- **[GORM](https://github.com/go-gorm/gorm)** — ORM with PostgreSQL & ClickHouse support
-- **[Redis](https://github.com/redis/redis)** — Cache, session store, and task queue backend
-- **[Asynq](https://github.com/hibiken/asynq)** — Distributed task queue (Redis-backed)
-- **[Cobra + Viper](https://github.com/spf13/cobra)** — CLI entrypoint and configuration management
-- **[OpenTelemetry](https://opentelemetry.io)** — Distributed tracing and observability
-- **[Zap](https://github.com/uber-go/zap)** — Structured, high-performance logging
-- **[Swagger (Swaggo)](https://github.com/swaggo/swag)** — Auto-generated API documentation
-- **[AWS SDK v2](https://github.com/aws/aws-sdk-go-v2)** — S3-compatible file storage
-- **[Snowflake](https://github.com/bwmarrin/snowflake)** — Distributed ID generation
+* **Reverse Proxy Configuration Management**: Uses website rules as the aggregation boundary, supports multi-domain binding and multi-upstream load balancing, and centrally manages reverse proxy configurations for all OpenResty nodes.
+* **Secure In-Network Tunneling (Tunnels)**: Open-source version of Cloudflare Tunnels. No public IP or exposed inbound ports are required. Securely reverse-proxy internal web services to the public internet through Relay relay nodes and OpenFlared clients.
+* **Edge WAF Security Protection**: Provides global and custom rule groups, supports manual/auto/subscription-type IP groups, MaxMind GeoIP national-level geographic access control, IP group member Checksum differential synchronization (no Nginx reload required), and custom blocking responses.
+* **CC Defense and Human-Computer Challenge (PoW)**: Built-in high-performance client-side cryptography Proof of Work challenge (similar to Turnstile). Secures high-speed interception and blocking of zombie networks and crawlers at the gateway edge.
+* **Pages Static Hosting**: Supports uploading or synchronizing pre-built artifacts from restricted Remote URLs or public GitHub Release assets. GitHub latest can be checked periodically and optionally auto-published. All sources are unified to generate immutable deployments, pulled by the edge Agent and served locally by OpenResty, supporting rollbacks, SPA Fallback, and API reverse proxy.
+* **TLS Certificate Automation**: Supports dynamic certificate uploads, automatic multi-domain certificate matching and binding, and automatic issuance and renewal of certificates from Let's Encrypt via the ACME protocol.
+* **Uptime Kuma Monitoring Synchronization**: Integrated with Uptime Kuma to automatically perform differential synchronization of monitoring site lists, real-time awareness of node availability and service status.
+* **SSO Single Sign-On**: Supports GitHub OAuth and standard OIDC protocol for seamless integration with enterprise identity providers to achieve unified login.
+* **Unified Observability**: Aggregates node request metrics, real-time access log details, host and Nginx resource snapshots, health events, and network fluctuation replenishment buffers.
 
-### Frontend
-- **[Next.js 16](https://github.com/vercel/next.js)** — React framework with App Router
-- **[React 19](https://github.com/facebook/react)** — UI library
-- **[TypeScript](https://github.com/microsoft/TypeScript)** — Type safety
-- **[Tailwind CSS 4](https://github.com/tailwindlabs/tailwindcss)** — Utility-first styling
-- **[Shadcn UI](https://github.com/shadcn-ui/ui)** — Accessible, composable component library
-- **[Lucide Icons](https://github.com/lucide-icons/lucide)** — Icon library
+## Interface Preview
 
-## 📋 Requirements
+### Dashboard Overview
 
-- **Go** >= 1.25
-- **Node.js** >= 18.0
-- **PostgreSQL** >= 14
-- **Redis** >= 6.0
-- **pnpm** >= 8.0 (recommended)
+![OpenFlare dashboard overview](./docs/assets/readme/dashboard-overview.png)
 
-## 🚀 Quick Start
+### Access Logs
 
-### 1. Clone the Repository
+![OpenFlare version release](./docs/assets/readme/domain_overview.png)
+
+### WAF Protection
+
+![OpenFlare version release](./docs/assets/readme/waf.png)
+
+## Quick Start
+
+### Hardware Configuration Recommendations
+
+| Component              | Minimum Hardware Requirements     | Recommended Hardware Requirements | Notes |
+|------------------------|-----------------------------------|-----------------------------------|-------|
+| **Server Control Plane** | 1 CPU core / 2 GB RAM / 20 GB disk | 2 CPU cores / 4 GB RAM / 50 GB+ disk | Disk usage should be expanded reasonably based on access log retention duration and concurrent traffic |
+| **Agent Data Plane**     | 1 CPU core / 512 MB RAM / 2 GB disk | 2 CPU cores / 2 GB RAM / 10 GB+ disk | Expanded based on OpenResty concurrent proxy connections and WAF interception processing |
+| **Relay Relay Node**     | 1 CPU core / 1 GB RAM / 5 GB disk | 2 CPU cores / 2 GB RAM / 20 GB disk | frps transmission relay throughput is mainly limited by bandwidth and CPU throughput |
+| **OpenFlared Client**    | 1 CPU core / 256 MB RAM / 1 GB disk | 1 CPU core / 512 MB RAM / 5 GB disk | Runs independently on the internal network with extremely low resource consumption; only network throughput needs to be guaranteed |
+
+### 1. Start the Server
+
+Use `docker-compose`:
 
 ```bash
-git clone https://github.com/Rain-kl/Wavelet.git refreshing
-cd refreshing
+# Download environment variable template and create .env file
+curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
+cp .env.example .env
 ```
 
-### 2. Configure Environment
+```yaml
+services:
+  openflare:
+    image: ghcr.io/rain-kl/openflare:latest
+    restart: unless-stopped
+    env_file: .env
+    environment:
+      TZ: ${TZ:-Asia/Shanghai}
+    ports:
+      - "3000:3000"
+    volumes:
+      - openflare_uploads:/app/uploads
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+
+  postgres:
+    image: postgres:17-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: ${DB_NAME:-openflare}
+      POSTGRES_USER: ${DB_USERNAME:-openflare}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:-replace-with-strong-password}
+    volumes:
+      - openflare_postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME:-openflare} -d ${DB_NAME:-openflare}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: valkey/valkey:8.0-alpine
+    restart: unless-stopped
+    command: ["valkey-server", "--appendonly", "yes"]
+    volumes:
+      - openflare_redis_data:/data
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 5s
+
+volumes:
+    openflare_uploads:
+    openflare_postgres_data:
+    openflare_redis_data:
+```
+
+See the [deployment documentation](https://openflare.fyrn.link/deployment/deployment) for details.
+
+Access address: `http://localhost:3000`
+
+Default account:
+
+* Username: `admin`
+* Password: `12345678`
+
+### 2. Install Agent
+
+Before installing the Agent, first install OpenResty on the node or use the built-in OpenResty Agent Docker image.
+
+You can copy the installation command from the control panel's **Nodes Management -> Details -> Node Information -> Node ID and Deployment**, or use the script below:
+
+#### Docker Deployment
+
+Docker deployment can directly run the Agent image:
 
 ```bash
-cp config.example.yaml config.yaml
+docker pull ghcr.io/rain-kl/openflare-agent:latest
+docker rm -f openflare-agent 2>/dev/null || true
+docker run -d --name openflare-agent --restart unless-stopped \
+  -p 80:80 -p 443:443/tcp -p 443:443/udp \
+  -v openflare-agent-pages:/data/var/lib/openflare/pages \
+  -e OPENFLARE_SERVER_URL=http://your-server:3000 \
+  -e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
+  ghcr.io/rain-kl/openflare-agent:latest
 ```
 
-Edit `config.yaml` to configure your database and Redis. OIDC auth sources are configured at runtime in the admin settings page.
+## Cordis / Wavelet upstream
 
-### 3. Initialize Database
+OpenFlare is built on Wavelet Cordis. After cloning, enable `merge=ours` from `.gitattributes` so `git merge wavelet/main` keeps OpenFlare-owned paths:
 
 ```bash
-# Start local dependencies (PostgreSQL + Redis)
-docker compose up -d
-
-# Optional: also start ClickHouse
-docker compose --profile clickhouse up -d
-
-# If you use an external PostgreSQL instance instead of Docker, create the database manually
-createdb -h <host> -p 5432 -U postgres refreshing
-
-# Database schema is auto-migrated on first startup
+git config include.path ../.gitconfig
+# worktree-safe:
+git config include.path "$(git rev-parse --show-toplevel)/.gitconfig"
 ```
 
-### 4. Start the Backend
+`docker compose` uses `docker-compose.yaml`. `docker-compose.wavelet.yml` is the upstream Wavelet stack and is not the product default. Image publishes go through `.github/workflows/build-image-openflare*.yml`; the Wavelet `build-image.yml` is isolated.
 
-```bash
-# Install Go dependencies
-go mod tidy
+## Open Source License
 
-# Generate Swagger API documentation
-make swagger
+This project is licensed under the [Apache License 2.0](./LICENSE).
 
-# Start the HTTP API server
-go run main.go api
-```
+## Star History
 
-> The backend also supports separate `scheduler` and `worker` processes for async task processing:
-> ```bash
-> go run main.go scheduler   # Cron job scheduler
-> go run main.go worker      # Asynq task worker
-> ```
-
-### 5. Start the Frontend
-
-```bash
-cd frontend
-
-# Install dependencies
-pnpm install
-
-# Start dev server (Turbopack)
-pnpm dev
-```
-
-### 6. Access the Application
-
-| Service | URL |
-|---------|-----|
-| Frontend | http://localhost:3000 |
-| Swagger API Docs | http://localhost:8000/swagger/index.html |
-| Health Check | http://localhost:8000/api/health |
-
-## ⚙️ Configuration
-
-Key configuration options (see `config.example.yaml` for the full reference):
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `app.addr` | Backend listen address | `:8000` |
-| `database.host` | PostgreSQL host | `127.0.0.1` |
-| `database.database` | Database name | `refreshing` |
-| `redis.host` | Redis host | `127.0.0.1` |
-| `storage.endpoint` | S3-compatible endpoint | `s3.amazonaws.com` |
-
-## 🔧 Development Guide
-
-### Backend
-
-```bash
-# Run API server
-go run main.go api
-
-# Run task scheduler
-go run main.go scheduler
-
-# Run async worker
-go run main.go worker
-
-# Regenerate Swagger docs (required after controller changes)
-make swagger
-
-# Format & vet code
-make tidy
-```
-
-### Frontend
-
-```bash
-cd frontend
-
-# Development mode (Turbopack)
-pnpm dev
-
-# Production build
-pnpm build
-
-# Start production server
-pnpm start
-
-# Lint & format
-pnpm lint
-pnpm format
-```
-
-## 📁 Project Structure
-
-```
-wavelet/
-├── main.go                  # Entry point (delegates to internal/cmd)
-├── config.example.yaml      # Configuration template
-├── Makefile                 # Common commands (swagger, tidy, license, cross-build)
-├── docker/                  # Docker image build files (integrated/frontend/backend)
-├── docs/                    # Swagger auto-generated docs
-├── frontend/                # Next.js frontend application
-│   ├── app/                 # App Router pages
-│   ├── components/          # React components (ui, common, layout)
-│   ├── lib/services/        # API service layer
-│   └── types/               # TypeScript type definitions
-└── internal/                # Go backend (private)
-    ├── cmd/                 # CLI commands (api, scheduler, worker)
-    ├── apps/                # Business modules (oauth, user, admin, upload)
-    ├── model/               # GORM entities and business methods
-    ├── router/              # HTTP route registration
-    ├── task/                # Async task definitions and workers
-    ├── db/                  # Database and Redis initialization
-    ├── storage/             # S3 file storage abstraction
-    └── common/              # Shared utilities and response helpers
-```
-
-## 📚 API Documentation
-
-Swagger API documentation is auto-generated and available once the backend is running:
-
-```
-http://localhost:8000/swagger/index.html
-```
-
-The built-in frontend docs portal at `/docs` includes:
-- **Usage Guide** — Step-by-step walkthrough for getting started
-- **API Reference** — Detailed interface documentation
-- **Privacy Policy** — Template privacy policy (customize as needed)
-- **Terms of Service** — Template terms of service
-
-## 🧪 Testing
-
-```bash
-# Backend tests
-go test ./...
-
-# Frontend lint
-cd frontend && pnpm lint
-```
-
-## 🚀 Deployment
-
-### Cross-platform Binary
-
-Build static binaries for all 6 targets (Linux / macOS / Windows × amd64 / arm64) with a single command.
-The compiled frontend is embedded in every binary — no separate deployment needed.
-
-**Prerequisites:** Docker with BuildKit enabled (Docker 23+ defaults to on).
-
-```bash
-# Build all 6 binaries → ./bin/
-make cross-build
-
-# Stamp a release version
-make cross-build VERSION=v1.2.3
-
-# Build only a specific OS (both architectures)
-make cross-build GOOS=linux
-make cross-build GOOS=darwin
-make cross-build GOOS=windows
-
-# Build only a specific architecture (all OSes)
-make cross-build GOARCH=amd64
-make cross-build GOARCH=arm64
-
-# Combine filters — single binary
-make cross-build GOOS=linux GOARCH=arm64
-make cross-build GOOS=darwin GOARCH=amd64 VERSION=v1.2.3
-```
-
-Output files in `./bin/`:
-
-| File | Platform |
-|------|----------|
-| `wavelet_linux_amd64` | Linux x86-64 |
-| `wavelet_linux_arm64` | Linux ARM64 |
-| `wavelet_darwin_amd64` | macOS Intel |
-| `wavelet_darwin_arm64` | macOS Apple Silicon |
-| `wavelet_windows_amd64.exe` | Windows x86-64 |
-| `wavelet_windows_arm64.exe` | Windows ARM64 |
-
-> The version string is accessible at runtime via `wavelet --version`.
-
-### Docker
-
-```bash
-# Build image
-docker build -t refreshing .
-
-# Run (pass your config as a volume mount)
-docker run -d -p 8000:8000 \
-  -v $(pwd)/config.yaml:/app/config.yaml \
-  refreshing api
-```
-
-### Production
-
-1. Build the frontend:
-   ```bash
-   cd frontend && pnpm build
-   ```
-
-2. Compile the backend:
-   ```bash
-   go build -o refreshing main.go
-   ```
-
-3. Configure `config.yaml` for production.
-
-4. Start services:
-   ```bash
-   ./refreshing api        # HTTP API
-   ./refreshing scheduler  # Cron scheduler (optional)
-   ./refreshing worker     # Task worker (optional)
-   ```
-
-## 🤝 Contributing
-
-We welcome contributions! Please read the following before submitting code:
-
-- [Contributing Guidelines](CONTRIBUTING.md)
-- [Code of Conduct](CODE_OF_CONDUCT.md)
-- [Contributor License Agreement](CLA.md)
-
-### Workflow
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/your-feature`)
-3. Commit your changes (`git commit -am 'Add your feature'`)
-4. Push to the branch (`git push origin feature/your-feature`)
-5. Open a Pull Request
-
-## 📄 License
-
-This project is licensed under the [Apache 2.0 License](LICENSE).
+<a href="https://www.star-history.com/?repos=Rain-kl%2FOpenFlare&type=date&legend=bottom-right">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Rain-kl/OpenFlare&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Rain-kl/OpenFlare&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Rain-kl/OpenFlare&type=date&legend=top-left" />
+ </picture>
+</a>

README.zh-CN.md

@@ -0,0 +1,192 @@
+<div align="center">
+
+# OpenFlare
+
+**[English](./README.md) | [简体中文](./README.zh-CN.md)**
+
+OpenFlare 是开源 CDN 编排与边缘安全平台。它支持反向代理、集中式配置同步、内网穿透（Tunnels）、动态 WAF 防护以及防 CC 挑战。
+
+</div>
+
+<p align="center">
+  <a href="https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/LICENSE">
+    <img src="https://img.shields.io/github/license/Rain-kl/OpenFlare?color=brightgreen" alt="license">
+  </a>
+  <a href="https://github.com/Rain-kl/OpenFlare/releases/latest">
+    <img src="https://img.shields.io/github/v/release/Rain-kl/OpenFlare?color=brightgreen&include_prereleases" alt="release">
+  </a>
+  <a href="https://github.com/Rain-kl/OpenFlare/pkgs/container/openflare">
+    <img src="https://img.shields.io/badge/GHCR-ghcr.io%2Frain--kl%2Fopenflare-brightgreen" alt="ghcr">
+  </a>
+</p>
+
+> [!WARNING]
+> 使用 `admin` 用户初次登录系统后，务必修改默认密码 `12345678`。
+>
+> BETA 版本为开发测试阶段的临时产物，可能存在未知问题，请勿在生产环境使用。
+
+## 文档
+
+**https://openflare.fyrn.link**
+
+常用入口：
+
+* [快速开始](https://openflare.fyrn.link/guide/quick-start)
+* [部署说明](https://openflare.fyrn.link/deployment/deployment)
+* [配置项参考](https://openflare.fyrn.link/reference/configuration)
+* [系统设计](https://openflare.fyrn.link/design/)
+
+## 核心能力
+
+* **反代配置管理**：以网站规则为聚合边界，支持多域名绑定与多上游负载均衡，统一管理所有 OpenResty 节点的反代配置。
+* **安全内网穿透（Tunnels）**：开源版的 Cloudflare Tunnels。无须公网 IP 或暴露入向端口，通过 Relay 中继节点与 OpenFlared 客户端安全反向穿透内网 Web 服务至公网。
+* **边缘 WAF 安全防护**：提供全局与自定义规则组，支持手动/自动/订阅型 IP 组、MaxMind GeoIP 国家级地域准入、IP 组成员 Checksum 差分同步（无需 Nginx 重载）以及自定义拦截响应。
+* **防 CC 与人机挑战（PoW）**：内置高性能客户端密码学 Proof of Work 挑战（类似 Turnstile），在网关边缘秒级拦截并阻断僵尸网络与爬虫。
+* **Pages 静态托管**：支持上传或从受限 Remote URL、公开 GitHub Release asset 同步预构建产物；GitHub latest 可定时检查并可选自动发布。所有来源统一生成不可变部署，由边缘 Agent 拉取并通过 OpenResty 本地提供服务，支持回滚、SPA Fallback 与 API 反向代理。
+* **TLS 证书自动化**：支持证书动态上传、多域名证书自动匹配绑定，以及通过 ACME 协议向 Let's Encrypt 自动申请与续期证书。
+* **Uptime Kuma 监控同步**：与 Uptime Kuma 集成，自动差分同步监控站点列表，实时感知节点存活与服务可用状态。
+* **SSO 单点登录**：支持 GitHub OAuth 与标准 OIDC 协议，无缝接入企业身份提供商实现统一登录。
+* **统一观测**：聚合节点请求指标、实时访问日志明细、宿主机与 Nginx 资源快照、健康事件以及网络波动补传缓冲。
+
+## 界面预览
+
+### 仪表盘总览
+
+![OpenFlare dashboard overview](./docs/assets/readme/dashboard-overview.png)
+
+### 访问日志
+
+![OpenFlare version release](./docs/assets/readme/domain_overview.png)
+
+### WAF 防护
+
+![OpenFlare version release](./docs/assets/readme/waf.png)
+
+## 快速开始
+
+### 硬件配置推荐
+
+| 组件 | 最低硬件配额                        | 推荐硬件配额 | 说明 |
+| --- |-------------------------------| --- | --- |
+| **Server 控制面** | 1 核 CPU / 2 GB 内存 / 20 GB 磁盘  | 2 核 CPU / 4 GB 内存 / 50 GB+ 磁盘 | 磁盘用量需根据访问日志留存时长与并发流量合理扩容 |
+| **Agent 数据面** | 1 核 CPU / 512 MB 内存 / 2 GB 磁盘 | 2 核 CPU / 2 GB 内存 / 10 GB+ 磁盘 | 根据 OpenResty 的并发代理连接量与 WAF 拦截处理扩容 |
+| **Relay 中继节点**| 1 核 CPU / 1 GB 内存 / 5 GB 磁盘   | 2 核 CPU / 2 GB 内存 / 20 GB 磁盘 | frps 传输中继吞吐量主要受带宽与 CPU 吞吐能力限制 |
+| **OpenFlared 客户端**| 1 核 CPU / 256 MB 内存 / 1 GB 磁盘 | 1 核 CPU / 512 MB 内存 / 5 GB 磁盘 | 独立运行于内网，自身资源占用极小，保障网络吞吐即可 |
+
+### 1. 启动 Server
+
+使用 docker-compose
+
+```bash
+# 下载环境变量模板并创建 .env 文件
+curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
+cp .env.example .env
+```
+
+```yaml
+services:
+  openflare:
+    image: ghcr.io/rain-kl/openflare:latest
+    restart: unless-stopped
+    env_file: .env
+    environment:
+      TZ: ${TZ:-Asia/Shanghai}
+    ports:
+      - "3000:3000"
+    volumes:
+      - openflare_uploads:/app/uploads
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+
+  postgres:
+    image: postgres:17-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: ${DB_NAME:-openflare}
+      POSTGRES_USER: ${DB_USERNAME:-openflare}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:-replace-with-strong-password}
+    volumes:
+      - openflare_postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME:-openflare} -d ${DB_NAME:-openflare}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: valkey/valkey:8.0-alpine
+    restart: unless-stopped
+    command: ["valkey-server", "--appendonly", "yes"]
+    volumes:
+      - openflare_redis_data:/data
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 5s
+
+volumes:
+    openflare_uploads:
+    openflare_postgres_data:
+    openflare_redis_data:
+```
+
+详细部署说明见 [部署文档](https://openflare.fyrn.link/deployment/deployment)。
+
+访问地址：`http://localhost:3000`
+
+默认账号：
+
+* 用户名：`admin`
+* 密码：`12345678`
+
+### 2. 安装 Agent
+
+安装 Agent 前请先在节点上安装 OpenResty，或改用内置 OpenResty 的 Agent Docker 镜像。
+
+你可以在控制面板的节点管理->详情->节点信息->节点标识与部署复制安装命令，或直接使用下面的脚本：
+
+#### Docker 部署
+
+Docker 部署可直接运行 Agent 镜像：
+
+```bash
+docker pull ghcr.io/rain-kl/openflare-agent:latest
+docker rm -f openflare-agent 2>/dev/null || true
+docker run -d --name openflare-agent --restart unless-stopped \
+  -p 80:80 -p 443:443/tcp -p 443:443/udp \
+  -v openflare-agent-pages:/data/var/lib/openflare/pages \
+  -e OPENFLARE_SERVER_URL=http://your-server:3000 \
+  -e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
+  ghcr.io/rain-kl/openflare-agent:latest
+```
+
+## Cordis / Wavelet 上游
+
+OpenFlare 构建在 Wavelet Cordis 之上。克隆后请启用 `.gitattributes` 中的 `merge=ours`，这样 `git merge wavelet/main` 会保留 OpenFlare 自有路径：
+
+```bash
+git config include.path ../.gitconfig
+# worktree 安全写法：
+git config include.path "$(git rev-parse --show-toplevel)/.gitconfig"
+```
+
+`docker compose` 使用 `docker-compose.yaml`。`docker-compose.wavelet.yml` 是上游 Wavelet 编排，不是本产品的默认栈。镜像发布走 `.github/workflows/build-image-openflare*.yml`；Wavelet 的 `build-image.yml` 已隔离。
+
+## 开源协议
+
+本项目采用 [Apache License 2.0](./LICENSE) 开源。
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=Rain-kl%2FOpenFlare&type=date&legend=bottom-right">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Rain-kl/OpenFlare&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Rain-kl/OpenFlare&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Rain-kl/OpenFlare&type=date&legend=top-left" />
+ </picture>
+</a>

README_zh.md

@@ -95,10 +95,10 @@ cd refreshing
 ### 2. 配置环境
 
 ```bash
-cp config.example.yaml config.yaml
+cp manifest/config/config.default.yaml manifest/config/config.yaml
 ```
 
-编辑 `config.yaml`，配置数据库和 Redis。OIDC 认证源统一在管理后台的系统设置页面运行时配置。
+编辑 `manifest/config/config.yaml`，配置数据库和 Redis。OIDC 认证源统一在管理后台的系统设置页面运行时配置。
 
 ### 3. 初始化数据库
 
@@ -152,11 +152,11 @@ pnpm dev
 |------|------|
 | 前端界面 | http://localhost:3000 |
 | Swagger 接口文档 | http://localhost:8000/swagger/index.html |
-| 健康检查 | http://localhost:8000/api/health |
+| 健康检查 | http://localhost:8000/api/healthz |
 
 ## ⚙️ 配置说明
 
-主要配置项（完整说明请参考 `config.example.yaml`）：
+主要配置项（完整说明请参考 `manifest/config/config.default.yaml`）：
 
 | 配置项 | 说明 | 示例 |
 |--------|------|------|
@@ -211,9 +211,8 @@ pnpm format
 ```
 wavelet/
 ├── main.go                  # 程序入口（委托给 internal/cmd）
-├── config.example.yaml      # 配置模板
 ├── Makefile                 # 常用命令（swagger、tidy、license、cross-build）
-├── docker/                  # Docker 镜像构建文件（集成/前端/后端）
+├── manifest/                # 项目清单与编排：docker 镜像构建、deploy (k8s)、config 配置（默认/覆盖）
 ├── docs/                    # Swagger 自动生成文档
 ├── frontend/                # Next.js 前端应用
 │   ├── app/                 # App Router 页面

backend/cmd/agent/main.go

@@ -0,0 +1,41 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Command agent runs the OpenFlare edge agent daemon.
+package main
+
+import (
+	"flag"
+	"log/slog"
+	"os"
+	"time"
+
+	"Wavelet/core"
+	agentplugin "Wavelet/openflare/plugins/agent"
+	"Wavelet/openflare/plugins/agent/logging"
+)
+
+// shutdownTimeout 为 openresty 收敛与在途配置同步预留的退出窗口。
+const shutdownTimeout = 60 * time.Second
+
+func main() {
+	logging.Setup()
+
+	configPath := flag.String("config", "./agent.json", "agent config path")
+	flag.Parse()
+
+	app := core.NewApp(
+		core.WithProfile(core.Profile(agentplugin.DriverTypeAgent)),
+		core.WithShutdownTimeout(shutdownTimeout),
+	)
+	app.Use(agentplugin.New(*configPath))
+
+	if err := app.Prepare(); err != nil {
+		slog.Error("agent startup failed", "error", err)
+		os.Exit(1)
+	}
+	if err := app.Run(); err != nil {
+		slog.Error("agent process exited with error", "error", err)
+		os.Exit(1)
+	}
+}

backend/cmd/all.go

@@ -0,0 +1,19 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package cmd 提供 CLI 命令入口
+package cmd
+
+import (
+	"Wavelet/core"
+
+	"github.com/spf13/cobra"
+)
+
+var allCmd = &cobra.Command{
+	Use:   "all",
+	Short: "以融合模式同时启动 API、Worker 和 Scheduler",
+	Run: func(_ *cobra.Command, _ []string) {
+		runProfileApp(core.ProfileAll, "all (API + Worker + Scheduler)", true)
+	},
+}

backend/cmd/api.go

@@ -0,0 +1,18 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"Wavelet/core"
+
+	"github.com/spf13/cobra"
+)
+
+var apiCmd = &cobra.Command{
+	Use:   "api",
+	Short: "wavelet API",
+	Run: func(_ *cobra.Command, _ []string) {
+		runProfileApp(core.ProfileAPI, "api", true)
+	},
+}

backend/cmd/app.go

@@ -0,0 +1,417 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	ofserver "Wavelet/openflare/plugins/server"
+	"Wavelet/openflare/plugins/server/migrate"
+	"Wavelet/plugins/domain/admin"
+	"Wavelet/plugins/domain/auth"
+	"Wavelet/plugins/domain/msg_gateway"
+	"Wavelet/plugins/domain/risk_control"
+	"Wavelet/plugins/domain/system"
+	"Wavelet/plugins/domain/upload"
+	"Wavelet/plugins/domain/user"
+	"Wavelet/plugins/drivers/driver_asynq_cron"
+	"Wavelet/plugins/drivers/driver_asynq_worker"
+	"Wavelet/plugins/drivers/driver_http"
+	"Wavelet/plugins/drivers/driver_inproc_cron"
+	"Wavelet/plugins/drivers/driver_inproc_worker"
+	"Wavelet/plugins/infra/cache"
+	"Wavelet/plugins/infra/cache_memory"
+	"Wavelet/plugins/infra/config"
+	"Wavelet/plugins/infra/logger"
+	"Wavelet/plugins/infra/storage"
+	"context"
+	"database/sql"
+	"fmt"
+	"io/fs"
+	"log"
+	"path/filepath"
+	"time"
+
+	"github.com/pressly/goose/v3"
+	goosedb "github.com/pressly/goose/v3/database"
+	"gorm.io/gorm"
+
+	infradb "Wavelet/plugins/infra/database"
+)
+
+const (
+	defaultShutdownTimeout = 15 * time.Second
+	defaultHTTPAddr        = "127.0.0.1:8000"
+
+	// migrationAdvisoryLockKey serializes baseline + plugin Up across Postgres
+	// sessions (ASCII "wave"). SQLite is single-writer and needs no extra lock.
+	migrationAdvisoryLockKey int64 = 0x77617665
+)
+
+// runProfileApp prepares and runs the application for a given profile.
+func runProfileApp(profile core.Profile, mode string, listensForHTTP bool) {
+	app := newOpenFlareApp(profile)
+	if err := app.Prepare(); err != nil {
+		log.Fatalf("[%s] prepare failed: %v\n", mode, err)
+	}
+	state := startupState{
+		mode:           mode,
+		listensForHTTP: listensForHTTP,
+		env:            app.Context().Config().String("app.env", "production"),
+	}
+	if listensForHTTP {
+		state.addr = app.Context().Config().String("app.addr", defaultHTTPAddr)
+	}
+	printStartupBanner(state)
+	if err := app.Run(); err != nil {
+		log.Fatalf("[%s] run failed: %v\n", mode, err)
+	}
+}
+
+// newOpenFlareApp creates a core.App wired with Wavelet platform plugins plus the OpenFlare server plugin.
+func newOpenFlareApp(profile core.Profile, opts ...core.AppOption) *core.App {
+	src, err := config.NewSource()
+	if err != nil {
+		log.Fatalf("[App] load config source failed: %v\n", err)
+	}
+
+	appOpts := []core.AppOption{
+		core.WithProfile(profile),
+		core.WithConfigSource(src),
+		core.WithShutdownTimeout(defaultShutdownTimeout),
+		core.WithMigrationBaseline(migrate.Legacy),
+	}
+	appOpts = append(appOpts, opts...)
+
+	app := core.NewApp(appOpts...)
+
+	// 1. Register standard infrastructure plugins
+	app.Use(
+		infradb.New(),
+		logger.New(),
+		storage.New(),
+	)
+
+	// 2. Register Cache and Async/Cron Drivers (both gated: cache vs cache_memory, asynq vs inproc)
+	app.Use(
+		cache.New(),
+		cache_memory.New(),
+		driver_asynq_worker.New(),
+		driver_inproc_worker.New(),
+		driver_asynq_cron.New(),
+		driver_inproc_cron.New(),
+	)
+
+	// 3. Register all 7 domain business plugins (admin first to ensure schema and base config tables exist)
+	app.Use(
+		admin.New(),
+		user.New(),
+		auth.New(),
+		msg_gateway.New(),
+		risk_control.New(),
+		upload.New(),
+		system.New(),
+	)
+
+	// 4. OpenFlare business routes (after domain plugins, before the HTTP driver)
+	app.Use(
+		ofserver.New(),
+	)
+
+	// 5. Bind Goose migration engine
+	app.SetMigrationEngine(&gooseEngine{})
+
+	// 6. Mount HTTP runtime driver
+	app.Use(
+		driver_http.New(),
+	)
+
+	return app
+}
+
+// ─── Schema Version Store ──────────────────────────────────────────────────────
+
+// sharedStore implements database.Store using a single w_schema_versions table.
+// All plugins share this table, with plugin_id as the discriminator.
+//
+// Schema:
+//
+//	w_schema_versions (
+//	    plugin_id   VARCHAR(64) NOT NULL,
+//	    version_id  BIGINT      NOT NULL,
+//	    applied_at  TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+//	    PRIMARY KEY (plugin_id, version_id)
+//	)
+type sharedStore struct {
+	pluginID string
+	dialect  string // "postgres" or "sqlite3"
+}
+
+func (s *sharedStore) Tablename() string { return "w_schema_versions" }
+
+func (s *sharedStore) CreateVersionTable(ctx context.Context, db goosedb.DBTxConn) error {
+	_, err := db.ExecContext(ctx, schemaVersionsDDL(s.dialect))
+	return err
+}
+
+func schemaVersionsDDL(dialect string) string {
+	timeType := "TIMESTAMPTZ"
+	if dialect == "sqlite3" || dialect == "sqlite" {
+		timeType = "DATETIME"
+	}
+	return fmt.Sprintf(`CREATE TABLE IF NOT EXISTS w_schema_versions (
+		plugin_id   VARCHAR(64)  NOT NULL,
+		version_id  BIGINT       NOT NULL,
+		applied_at  %s  NOT NULL DEFAULT CURRENT_TIMESTAMP,
+		PRIMARY KEY (plugin_id, version_id)
+	)`, timeType)
+}
+
+//nolint:mnd
+func (s *sharedStore) Insert(ctx context.Context, db goosedb.DBTxConn, req goosedb.InsertRequest) error {
+	p := s.placeholder
+	_, err := db.ExecContext(ctx,
+		fmt.Sprintf("INSERT INTO w_schema_versions (plugin_id, version_id) VALUES (%s, %s) ON CONFLICT (plugin_id, version_id) DO NOTHING", p(1), p(2)),
+		s.pluginID, req.Version)
+	return err
+}
+
+//nolint:mnd
+func (s *sharedStore) Delete(ctx context.Context, db goosedb.DBTxConn, version int64) error {
+	p := s.placeholder
+	_, err := db.ExecContext(ctx,
+		fmt.Sprintf("DELETE FROM w_schema_versions WHERE plugin_id = %s AND version_id = %s", p(1), p(2)),
+		s.pluginID, version)
+	return err
+}
+
+//nolint:mnd
+func (s *sharedStore) GetMigration(ctx context.Context, db goosedb.DBTxConn, version int64) (*goosedb.GetMigrationResult, error) {
+	p := s.placeholder
+	var t time.Time
+	err := db.QueryRowContext(ctx,
+		fmt.Sprintf("SELECT applied_at FROM w_schema_versions WHERE plugin_id = %s AND version_id = %s", p(1), p(2)),
+		s.pluginID, version).Scan(&t)
+	if err == sql.ErrNoRows {
+		return nil, goosedb.ErrVersionNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &goosedb.GetMigrationResult{Timestamp: t, IsApplied: true}, nil
+}
+
+func (s *sharedStore) GetLatestVersion(ctx context.Context, db goosedb.DBTxConn) (int64, error) {
+	p := s.placeholder
+	var version int64
+	err := db.QueryRowContext(ctx,
+		fmt.Sprintf("SELECT COALESCE(MAX(version_id), 0) FROM w_schema_versions WHERE plugin_id = %s", p(1)),
+		s.pluginID).Scan(&version)
+	if err != nil {
+		return 0, err
+	}
+	return version, nil
+}
+
+func (s *sharedStore) ListMigrations(ctx context.Context, db goosedb.DBTxConn) ([]*goosedb.ListMigrationsResult, error) {
+	p := s.placeholder
+	rows, err := db.QueryContext(ctx,
+		fmt.Sprintf("SELECT version_id, TRUE FROM w_schema_versions WHERE plugin_id = %s ORDER BY version_id DESC", p(1)),
+		s.pluginID)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = rows.Close() }()
+
+	var results []*goosedb.ListMigrationsResult
+	for rows.Next() {
+		var r goosedb.ListMigrationsResult
+		if err := rows.Scan(&r.Version, &r.IsApplied); err != nil {
+			return nil, err
+		}
+		results = append(results, &r)
+	}
+	return results, rows.Err()
+}
+
+func (s *sharedStore) placeholder(n int) string {
+	if s.dialect == "postgres" {
+		return fmt.Sprintf("$%d", n)
+	}
+	return "?"
+}
+
+// ─── Migration Engine ──────────────────────────────────────────────────────────
+
+// gooseEngine implements core.MigrationEngine by iterating all plugin-registered
+// migration entries and applying each plugin's migrations against the shared DB.
+//
+// Each plugin owns its own `migrations/*.sql` directory, embedded via go:embed
+// and registered via ctx.Migrations().Register(pluginID, embedFS).
+//
+// Version tracking: all plugins share a single w_schema_versions table with
+// plugin_id as the discriminator column. Querying this table shows the current
+// migration version of every plugin at a glance.
+type gooseEngine struct{}
+
+func (e *gooseEngine) Migrate(ctx *core.Context, entries []core.MigrationEntry) error {
+	if len(entries) == 0 {
+		return nil
+	}
+
+	// Resolve DBService from the IoC container.
+	var dbSvc contracts.DBService
+	if err := core.Using[contracts.DBService](ctx, func(svc contracts.DBService) {
+		dbSvc = svc
+	}); err != nil {
+		return fmt.Errorf("migration: resolve DBService: %w", err)
+	}
+
+	gormDB := dbSvc.GORM()
+	if gormDB == nil {
+		return fmt.Errorf("migration: DBService.GORM() returned nil")
+	}
+
+	sqlDB, err := gormDB.DB()
+	if err != nil {
+		return fmt.Errorf("migration: get underlying DB from GORM: %w", err)
+	}
+
+	dialect := gooseDialectFromGORM(gormDB, ctx)
+	dialectStr := string(dialect)
+	goCtx := context.Background()
+	if ctx != nil {
+		goCtx = ctx.GoContext()
+	}
+	if goCtx == nil {
+		goCtx = context.Background()
+	}
+
+	bootstrap := &sharedStore{dialect: dialectStr}
+	if err := bootstrap.CreateVersionTable(goCtx, sqlDB); err != nil {
+		return fmt.Errorf("migration: create version table: %w", err)
+	}
+
+	if dialect == goose.DialectPostgres {
+		conn, lockErr := sqlDB.Conn(goCtx)
+		if lockErr != nil {
+			return fmt.Errorf("migration: pin connection for advisory lock: %w", lockErr)
+		}
+		defer func() { _ = conn.Close() }()
+		if _, lockErr = conn.ExecContext(goCtx, "SELECT pg_advisory_lock($1)", migrationAdvisoryLockKey); lockErr != nil {
+			return fmt.Errorf("migration: advisory lock: %w", lockErr)
+		}
+		defer func() {
+			_, _ = conn.ExecContext(context.Background(), "SELECT pg_advisory_unlock($1)", migrationAdvisoryLockKey)
+		}()
+	}
+
+	if fn := ctx.MigrationBaseline(); fn != nil {
+		if err := fn(ctx); err != nil {
+			return fmt.Errorf("migration baseline: %w", err)
+		}
+	}
+
+	for _, entry := range entries {
+		store := &sharedStore{
+			pluginID: entry.PluginID,
+			dialect:  dialectStr,
+		}
+
+		migrationFS := findMigrationFS(entry.FS, dialect)
+		provider, err := goose.NewProvider(goose.DialectCustom, sqlDB, migrationFS, goose.WithStore(store))
+		if err != nil {
+			return fmt.Errorf("migration %s: create provider: %w", entry.PluginID, err)
+		}
+
+		results, err := provider.Up(context.Background())
+		if err != nil {
+			return fmt.Errorf("migration %s: apply %w", entry.PluginID, err)
+		}
+
+		version, vErr := provider.GetDBVersion(context.Background())
+		if vErr != nil {
+			version = 0
+		}
+
+		if len(results) > 0 {
+			log.Printf("[migrate] %s: applied %d migration(s) (v%d)", entry.PluginID, len(results), version)
+		} else {
+			log.Printf("[migrate] %s: v%d", entry.PluginID, version)
+		}
+	}
+
+	return nil
+}
+
+// gooseDialectFromGORM prefers the live driver; config is only a fallback when
+// GORM has no dialector yet (tests that inject a stub DBService).
+func gooseDialectFromGORM(gormDB *gorm.DB, ctx *core.Context) goose.Dialect {
+	if gormDB != nil && gormDB.Dialector != nil && gormDB.Dialector.Name() == "postgres" {
+		return goose.DialectPostgres
+	}
+	if gormDB != nil && gormDB.Dialector != nil && gormDB.Dialector.Name() == "sqlite" {
+		return goose.DialectSQLite3
+	}
+	return gooseDialect(ctx)
+}
+
+// gooseDialect returns the goose dialect based on the configured database engine.
+func gooseDialect(ctx *core.Context) goose.Dialect {
+	if ctx != nil && ctx.Config() != nil && ctx.Config().Bool("database.enabled", false) {
+		return goose.DialectPostgres
+	}
+	return goose.DialectSQLite3
+}
+
+func findMigrationFS(rootFS fs.FS, dialect goose.Dialect) fs.FS {
+	dialectDir := "postgres"
+	if dialect == goose.DialectSQLite3 {
+		dialectDir = "sqlite"
+	}
+
+	// 1. Direct search for dialect folder (e.g., "sqlite", "migrations/sqlite", "logstore/migrations/sqlite")
+	for _, subDir := range []string{
+		dialectDir,
+		"migrations/" + dialectDir,
+		"logstore/migrations/" + dialectDir,
+	} {
+		if sub, err := fs.Sub(rootFS, subDir); err == nil {
+			if matches, err := fs.Glob(sub, "*.sql"); err == nil && len(matches) > 0 {
+				return sub
+			}
+		}
+	}
+
+	// 2. Recursive walk to find a directory named dialectDir with *.sql files
+	var foundDir string
+	_ = fs.WalkDir(rootFS, ".", func(path string, d fs.DirEntry, err error) error {
+		if err == nil && d.IsDir() && filepath.Base(path) == dialectDir {
+			if sub, subErr := fs.Sub(rootFS, path); subErr == nil {
+				if matches, globErr := fs.Glob(sub, "*.sql"); globErr == nil && len(matches) > 0 {
+					foundDir = path
+					return fs.SkipAll
+				}
+			}
+		}
+		return nil
+	})
+
+	if foundDir != "" && foundDir != "." {
+		if sub, err := fs.Sub(rootFS, foundDir); err == nil {
+			return sub
+		}
+	}
+
+	// 3. Fallback to generic migrations / root if dialect specific is not present
+	for _, subDir := range []string{"migrations", "logstore/migrations"} {
+		if sub, err := fs.Sub(rootFS, subDir); err == nil {
+			if matches, err := fs.Glob(sub, "*.sql"); err == nil && len(matches) > 0 {
+				return sub
+			}
+		}
+	}
+
+	return rootFS
+}

backend/cmd/app_test.go

@@ -0,0 +1,133 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"path/filepath"
+	"testing"
+
+	"Wavelet/core"
+)
+
+func testSource(t *testing.T) core.ConfigSource {
+	t.Helper()
+	return core.NewMapSource(map[string]any{
+		"app": map[string]any{
+			"addr": "127.0.0.1:0",
+			"env":  "testing",
+		},
+		"redis": map[string]any{
+			"enabled": false,
+		},
+		"database": map[string]any{
+			"enabled":     false,
+			"sqlite_path": filepath.Join(t.TempDir(), "openflare-cmd.db"),
+		},
+	})
+}
+
+func TestNewOpenFlareAppRegistersServerAndWaveletUser(t *testing.T) {
+	app := newOpenFlareApp(core.ProfileAPI, core.WithConfigSource(testSource(t)))
+	if err := app.Prepare(); err != nil {
+		t.Fatal(err)
+	}
+	names := map[string]bool{}
+	for _, p := range app.Plugins() {
+		names[p.Name()] = true
+	}
+	for _, n := range []string{"user", "auth", "admin", "server"} {
+		if !names[n] {
+			t.Errorf("missing plugin %s", n)
+		}
+	}
+
+	if err := app.Reconcile(); err != nil {
+		t.Fatal(err)
+	}
+
+	got := map[string]bool{}
+	for _, rd := range app.Context().Router().Routes() {
+		got[rd.Method+" "+rd.Path] = true
+	}
+	for _, want := range []string{
+		"GET /api/healthz",
+		"GET /api/v1/user/self",
+		"GET /api/v1/d/nodes",
+		"POST /api/v1/cap/challenge",
+	} {
+		if !got[want] {
+			t.Errorf("missing route %s", want)
+		}
+	}
+	for _, drop := range []string{
+		"GET /api/health",
+		"GET /healthz",
+		"POST /api/cap/challenge",
+	} {
+		if got[drop] {
+			t.Errorf("removed route still registered: %s", drop)
+		}
+	}
+}
+
+func TestFreshInstallSeedsOpenFlareDefaults(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "fresh.db")
+	app := cordisPrepare(t, cordisSQLiteSource(t, dbPath))
+	t.Cleanup(func() { _ = app.Context().Dispose() })
+
+	db := openInspectDB(t, dbPath, "")
+	defer func() { _ = db.Close() }()
+
+	var tables int
+	if err := db.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name LIKE 'of_%'`).Scan(&tables); err != nil {
+		t.Fatal(err)
+	}
+	if tables == 0 {
+		t.Fatal("fresh install created no of_* tables")
+	}
+
+	rows, err := db.Query(`SELECT task_type FROM w_schedules WHERE task_type LIKE 'of_%' ORDER BY 1`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = rows.Close() }()
+	var got []string
+	for rows.Next() {
+		var taskType string
+		if err := rows.Scan(&taskType); err != nil {
+			t.Fatal(err)
+		}
+		got = append(got, taskType)
+	}
+	want := []string{
+		"of_pages_source_scan",
+		"of_ssl_renew",
+		"of_uptime_kuma_sync",
+		"of_waf_ip_group_sync",
+	}
+	if len(got) != len(want) {
+		t.Fatalf("of_* schedules = %v, want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("of_* schedules = %v, want %v", got, want)
+		}
+	}
+
+	var cleanup int
+	if err := db.QueryRow(`SELECT COUNT(*) FROM w_schedules WHERE task_type = 'of_database_auto_cleanup'`).Scan(&cleanup); err != nil {
+		t.Fatal(err)
+	}
+	if cleanup != 0 {
+		t.Fatal("must not seed of_database_auto_cleanup")
+	}
+
+	var geoip string
+	if err := db.QueryRow(`SELECT value FROM w_system_configs WHERE key = 'geoip_provider'`).Scan(&geoip); err != nil {
+		t.Fatalf("geoip_provider: %v", err)
+	}
+	if geoip != "ipinfo" {
+		t.Fatalf("geoip_provider = %q, want ipinfo", geoip)
+	}
+}

backend/cmd/banner.go

@@ -0,0 +1,60 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"Wavelet/pkg/buildinfo"
+	"fmt"
+	"runtime"
+	"strings"
+)
+
+type startupState struct {
+	mode           string
+	listensForHTTP bool
+	env            string
+	addr           string
+}
+
+func printStartupBanner(state startupState) {
+	fmt.Println(formatStartupBanner(state))
+}
+
+func formatStartupBanner(state startupState) string {
+	env := state.env
+	if env == "" {
+		env = "production"
+	}
+	addr := state.addr
+	if addr == "" {
+		addr = "127.0.0.1:3000"
+	}
+
+	lines := []string{
+		"",
+		"   ____                   ________               ",
+		"  / __ \\____  ___  ____  / ____/ /___ _________  ",
+		" / / / / __ \\/ _ \\/ __ \\/ /_  / / __ `/ ___/ _ \\",
+		"/ /_/ / /_/ /  __/ / / / __/ / / /_/ / /  /  __/",
+		"\\____/ .___/\\___/_/ /_/_/   /_/\\__,_/_/   \\___/ ",
+		"      /_/                                         ",
+		fmt.Sprintf(" OpenFlare %s", buildinfo.Version),
+		"",
+		fmt.Sprintf(" Environment: %s", env),
+		fmt.Sprintf(" Runtime:     %s/%s (%s)", runtime.GOOS, runtime.GOARCH, runtime.Version()),
+		fmt.Sprintf(" Build time:  %s", buildTime()),
+	}
+	if state.listensForHTTP {
+		lines = append(lines, fmt.Sprintf(" Listening:   http://%s", addr))
+	}
+	lines = append(lines, fmt.Sprintf(" Mode:        %s", state.mode), "")
+	return strings.Join(lines, "\n")
+}
+
+func buildTime() string {
+	if buildinfo.BuildTime == "" {
+		return "development build"
+	}
+	return buildinfo.BuildTime
+}

backend/cmd/banner_test.go

@@ -4,49 +4,33 @@
 package cmd
 
 import (
+	"Wavelet/pkg/buildinfo"
 	"strings"
 	"testing"
-
-	"github.com/Rain-kl/Wavelet/internal/buildinfo"
-	"github.com/Rain-kl/Wavelet/internal/infra/config"
-	"github.com/Rain-kl/Wavelet/internal/infra/persistence/migrator"
 )
 
 func TestFormatStartupBanner(t *testing.T) {
 	previousVersion := buildinfo.Version
 	previousBuildTime := buildinfo.BuildTime
-	previousEnv := config.Config.App.Env
-	previousAddr := config.Config.App.Addr
 	t.Cleanup(func() {
 		buildinfo.Version = previousVersion
 		buildinfo.BuildTime = previousBuildTime
-		config.Config.App.Env = previousEnv
-		config.Config.App.Addr = previousAddr
 	})
 
 	buildinfo.Version = "v3.2.1"
 	buildinfo.BuildTime = "2026-07-13T08:00:00Z"
-	config.Config.App.Env = "production"
-	config.Config.App.Addr = ":3000"
 
 	banner := formatStartupBanner(startupState{
-		mode: "API",
-		relationalDB: migrator.Report{
-			Backend: "PostgreSQL",
-			Enabled: true,
-			Version: 202607150003,
-			Applied: true,
-		},
-		clickHouseDB:   migrator.Report{Backend: "ClickHouse"},
+		mode:           "API",
 		listensForHTTP: true,
+		env:            "production",
+		addr:           ":3000",
 	})
 
 	for _, want := range []string{
-		"Wavelet v3.2.1",
+		"OpenFlare v3.2.1",
 		"Environment: production",
 		"Build time:  2026-07-13T08:00:00Z",
-		"Database:    PostgreSQL (version 202607150003, upgraded)",
-		"Analytics:   disabled",
 		"Listening:   http://:3000",
 		"Mode:        API",
 	} {

backend/cmd/flared/main.go

@@ -0,0 +1,41 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Command flared runs the OpenFlare tunnel client daemon.
+package main
+
+import (
+	"flag"
+	"log/slog"
+	"os"
+	"time"
+
+	"Wavelet/core"
+	flaredplugin "Wavelet/openflare/plugins/flared"
+	edgelogging "Wavelet/openflare/share/edge/logging"
+)
+
+// shutdownTimeout 为 frpc 子进程收敛预留的退出窗口。
+const shutdownTimeout = 60 * time.Second
+
+func main() {
+	edgelogging.Setup(edgelogging.Options{})
+
+	configPath := flag.String("config", "./flared.json", "flared config path")
+	flag.Parse()
+
+	app := core.NewApp(
+		core.WithProfile(core.Profile(flaredplugin.DriverTypeFlared)),
+		core.WithShutdownTimeout(shutdownTimeout),
+	)
+	app.Use(flaredplugin.New(*configPath))
+
+	if err := app.Prepare(); err != nil {
+		slog.Error("flared startup failed", "error", err)
+		os.Exit(1)
+	}
+	if err := app.Run(); err != nil {
+		slog.Error("flared process exited with error", "error", err)
+		os.Exit(1)
+	}
+}

backend/cmd/migrate_test.go

@@ -0,0 +1,400 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"testing/fstest"
+	"time"
+
+	"github.com/glebarez/sqlite"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	gormlogger "gorm.io/gorm/logger"
+)
+
+type migrateTestDB struct {
+	db *gorm.DB
+}
+
+func (s migrateTestDB) GORM() *gorm.DB { return s.db }
+
+func (s migrateTestDB) DB(ctx context.Context) *gorm.DB { return s.db.WithContext(ctx) }
+
+func (s migrateTestDB) Named(string) *gorm.DB { return s.db }
+
+type migrateTestPlugin struct {
+	name string
+	db   *gorm.DB
+	fs   fstest.MapFS
+}
+
+func (p *migrateTestPlugin) Name() string {
+	if p.name != "" {
+		return p.name
+	}
+	return "t"
+}
+
+func (p *migrateTestPlugin) Apply(ctx *core.Context) error {
+	core.Provide[contracts.DBService](ctx, migrateTestDB{db: p.db})
+	ctx.Migrations().Register(p.Name(), p.fs)
+	return nil
+}
+
+func sqliteTableExists(t *testing.T, db *gorm.DB, name string) bool {
+	t.Helper()
+	var n int
+	err := db.Raw("SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = ?", name).Scan(&n).Error
+	require.NoError(t, err)
+	return n > 0
+}
+
+func testMigrationFS() fstest.MapFS {
+	return fstest.MapFS{
+		"migrations/sqlite/00001_init.sql": &fstest.MapFile{Data: []byte(`-- +goose Up
+CREATE TABLE t_up (id INTEGER PRIMARY KEY);
+
+-- +goose Down
+DROP TABLE t_up;
+`)},
+	}
+}
+
+func openMigrateTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dbPath := filepath.Join(t.TempDir(), "migrate.db")
+	gdb, err := gorm.Open(sqlite.Open(dbPath), &gorm.Config{})
+	require.NoError(t, err)
+	return gdb
+}
+
+func TestGooseEngineMigrateOrderCreateTableBaselineUp(t *testing.T) {
+	gdb := openMigrateTestDB(t)
+	var order []string
+
+	app := core.NewApp(
+		core.WithMigrationEngine(&gooseEngine{}),
+		core.WithMigrationBaseline(func(*core.Context) error {
+			require.True(t, sqliteTableExists(t, gdb, "w_schema_versions"), "version table must exist before baseline")
+			require.False(t, sqliteTableExists(t, gdb, "t_up"), "plugin Up must not run before baseline")
+			order = append(order, "create-table", "baseline")
+			return nil
+		}),
+		core.WithPlugins(&migrateTestPlugin{db: gdb, fs: testMigrationFS()}),
+	)
+
+	require.NoError(t, app.Prepare())
+	require.NoError(t, app.ApplyPlugins())
+	require.NoError(t, app.RunMigrations())
+
+	require.True(t, sqliteTableExists(t, gdb, "t_up"), "plugin Up must run after baseline")
+	order = append(order, "up")
+	assert.Equal(t, []string{"create-table", "baseline", "up"}, order)
+}
+
+func TestGooseEngineBaselineErrorSkipsUp(t *testing.T) {
+	gdb := openMigrateTestDB(t)
+
+	app := core.NewApp(
+		core.WithMigrationEngine(&gooseEngine{}),
+		core.WithMigrationBaseline(func(*core.Context) error {
+			require.True(t, sqliteTableExists(t, gdb, "w_schema_versions"), "version table must exist before baseline")
+			return assert.AnError
+		}),
+		core.WithPlugins(&migrateTestPlugin{db: gdb, fs: testMigrationFS()}),
+	)
+
+	require.NoError(t, app.Prepare())
+	require.NoError(t, app.ApplyPlugins())
+	err := app.RunMigrations()
+	require.Error(t, err)
+	assert.ErrorContains(t, err, "migration baseline")
+	assert.False(t, sqliteTableExists(t, gdb, "t_up"), "plugin Up must not run when baseline fails")
+}
+
+func TestGooseEngineNilBaselineStillMigrates(t *testing.T) {
+	gdb := openMigrateTestDB(t)
+
+	app := core.NewApp(
+		core.WithMigrationEngine(&gooseEngine{}),
+		core.WithPlugins(&migrateTestPlugin{db: gdb, fs: testMigrationFS()}),
+	)
+
+	require.NoError(t, app.Prepare())
+	require.NoError(t, app.ApplyPlugins())
+	require.NoError(t, app.RunMigrations())
+	assert.True(t, sqliteTableExists(t, gdb, "w_schema_versions"))
+	assert.True(t, sqliteTableExists(t, gdb, "t_up"))
+}
+
+func TestGooseEngineUpgradesFrom00001To00002(t *testing.T) {
+	gdb := openMigrateTestDB(t)
+	runTestMigrations(t, gdb, testMigrationFS(), "")
+	require.True(t, sqliteTableExists(t, gdb, "t_up"))
+	require.False(t, sqliteTableExists(t, gdb, "t_v2"))
+	require.Equal(t, int64(1), pluginSchemaVersion(t, gdb, "t"))
+
+	runTestMigrations(t, gdb, testMigrationFSWithV2("sqlite"), "")
+	require.True(t, sqliteTableExists(t, gdb, "t_up"), "00001 table must survive 00002")
+	require.True(t, sqliteTableExists(t, gdb, "t_v2"), "00002 must create t_v2")
+	require.Equal(t, int64(2), pluginSchemaVersion(t, gdb, "t"))
+	require.Equal(t, 1, tableRowCount(t, gdb, "t_v2"))
+
+	runTestMigrations(t, gdb, testMigrationFSWithV2("sqlite"), "")
+	require.Equal(t, int64(2), pluginSchemaVersion(t, gdb, "t"), "second 00002 run must be a no-op")
+	require.Equal(t, 1, tableRowCount(t, gdb, "t_v2"), "00002 INSERT must not run twice")
+}
+
+func TestGooseEngineStampedV1AppliesOnly00002(t *testing.T) {
+	gdb := openMigrateTestDB(t)
+	require.NoError(t, gdb.Exec(`CREATE TABLE w_schema_versions (
+		plugin_id VARCHAR(64) NOT NULL,
+		version_id BIGINT NOT NULL,
+		applied_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+		PRIMARY KEY (plugin_id, version_id)
+	)`).Error)
+	require.NoError(t, gdb.Exec(`INSERT INTO w_schema_versions (plugin_id, version_id) VALUES ('t', 1)`).Error)
+
+	runTestMigrations(t, gdb, testMigrationFSWithV2("sqlite"), "")
+	require.False(t, sqliteTableExists(t, gdb, "t_up"), "stamped v1 must not re-run 00001")
+	require.True(t, sqliteTableExists(t, gdb, "t_v2"), "stamped v1 must still apply 00002")
+	require.Equal(t, int64(2), pluginSchemaVersion(t, gdb, "t"))
+}
+
+func TestOpenFlareServerUpgradesFrom00001To00002(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "of.db")
+	app := cordisPrepare(t, cordisSQLiteSource(t, dbPath))
+	require.NoError(t, app.Context().Dispose())
+
+	inspect := openInspectDB(t, dbPath, "")
+	if !pluginHasVersion(t, inspect, false, serverPluginStamp, 1) {
+		t.Fatal("fresh install did not apply server 00001")
+	}
+	_ = inspect.Close()
+
+	gdb, err := gorm.Open(sqlite.Open(dbPath), &gorm.Config{Logger: gormlogger.Default.LogMode(gormlogger.Silent)})
+	require.NoError(t, err)
+	runTestMigrations(t, gdb, serverFollowupFS("sqlite"), "server")
+
+	require.False(t, sqliteTableExists(t, gdb, "should_not_exist_from_00001_rerun"))
+	require.True(t, sqliteTableExists(t, gdb, "of_upgrade_probe"))
+	require.Equal(t, int64(2), pluginSchemaVersion(t, gdb, "server"))
+	require.True(t, sqliteTableExists(t, gdb, "of_zones"), "existing of_* tables must survive 00002")
+	require.Equal(t, 1, tableRowCount(t, gdb, "of_upgrade_probe"))
+}
+
+func TestGooseEngineUpgradesFrom00001To00002Postgres(t *testing.T) {
+	gdb := openMigratePostgresDB(t)
+	opts := postgresMigrateOpt()
+	runTestMigrations(t, gdb, testPostgresMigrationFS(), "", opts)
+	require.True(t, pgTableExists(t, gdb, "t_up"))
+	require.False(t, pgTableExists(t, gdb, "t_v2"))
+	require.Equal(t, int64(1), pluginSchemaVersion(t, gdb, "t"))
+
+	runTestMigrations(t, gdb, testMigrationFSWithV2("postgres"), "", opts)
+	require.True(t, pgTableExists(t, gdb, "t_up"))
+	require.True(t, pgTableExists(t, gdb, "t_v2"))
+	require.Equal(t, int64(2), pluginSchemaVersion(t, gdb, "t"))
+	require.Equal(t, 1, tableRowCount(t, gdb, "t_v2"))
+
+	runTestMigrations(t, gdb, testMigrationFSWithV2("postgres"), "", opts)
+	require.Equal(t, int64(2), pluginSchemaVersion(t, gdb, "t"))
+	require.Equal(t, 1, tableRowCount(t, gdb, "t_v2"))
+}
+
+func TestOpenFlareServerUpgradesFrom00001To00002Postgres(t *testing.T) {
+	host, port, user, pass, dbName, sslMode, cleanup := createMigratePostgresDB(t)
+	t.Cleanup(cleanup)
+	dsn := postgresDSN(host, port, user, pass, dbName, sslMode)
+	app := cordisPrepare(t, cordisPostgresSource(t, host, port, user, pass, dbName, sslMode))
+	require.NoError(t, app.Context().Dispose())
+
+	inspect := openInspectDB(t, "", dsn)
+	if !pluginHasVersion(t, inspect, true, serverPluginStamp, 1) {
+		t.Fatal("fresh install did not apply server 00001")
+	}
+	_ = inspect.Close()
+
+	gdb, err := gorm.Open(postgres.Open(dsn), &gorm.Config{Logger: gormlogger.Default.LogMode(gormlogger.Silent)})
+	require.NoError(t, err)
+	runTestMigrations(t, gdb, serverFollowupFS("postgres"), "server", postgresMigrateOpt())
+
+	require.False(t, pgTableExists(t, gdb, "should_not_exist_from_00001_rerun"))
+	require.True(t, pgTableExists(t, gdb, "of_upgrade_probe"))
+	require.Equal(t, int64(2), pluginSchemaVersion(t, gdb, "server"))
+	require.True(t, pgTableExists(t, gdb, "of_zones"))
+	require.Equal(t, 1, tableRowCount(t, gdb, "of_upgrade_probe"))
+}
+
+func runTestMigrations(t *testing.T, gdb *gorm.DB, fs fstest.MapFS, pluginName string, opts ...core.AppOption) {
+	t.Helper()
+	plugin := &migrateTestPlugin{name: pluginName, db: gdb, fs: fs}
+	appOpts := []core.AppOption{
+		core.WithMigrationEngine(&gooseEngine{}),
+		core.WithPlugins(plugin),
+	}
+	appOpts = append(appOpts, opts...)
+	app := core.NewApp(appOpts...)
+	require.NoError(t, app.Prepare())
+	require.NoError(t, app.ApplyPlugins())
+	require.NoError(t, app.RunMigrations())
+}
+
+func postgresMigrateOpt() core.AppOption {
+	return core.WithConfigSource(core.NewMapSource(map[string]any{
+		"database": map[string]any{"enabled": true},
+	}))
+}
+
+func testPostgresMigrationFS() fstest.MapFS {
+	return fstest.MapFS{
+		"migrations/postgres/00001_init.sql": &fstest.MapFile{Data: []byte(`-- +goose Up
+CREATE TABLE t_up (id BIGINT PRIMARY KEY);
+
+-- +goose Down
+DROP TABLE t_up;
+`)},
+	}
+}
+
+func testMigrationFSWithV2(dialect string) fstest.MapFS {
+	v1 := `-- +goose Up
+CREATE TABLE t_up (id BIGINT PRIMARY KEY);
+
+-- +goose Down
+DROP TABLE t_up;
+`
+	v2 := `-- +goose Up
+CREATE TABLE t_v2 (id BIGINT PRIMARY KEY, note TEXT NOT NULL DEFAULT '');
+INSERT INTO t_v2 (id, note) VALUES (1, 'from-00002');
+
+-- +goose Down
+DROP TABLE t_v2;
+`
+	if dialect == "sqlite" {
+		v1 = `-- +goose Up
+CREATE TABLE t_up (id INTEGER PRIMARY KEY);
+
+-- +goose Down
+DROP TABLE t_up;
+`
+		v2 = `-- +goose Up
+CREATE TABLE t_v2 (id INTEGER PRIMARY KEY, note TEXT NOT NULL DEFAULT '');
+INSERT INTO t_v2 (id, note) VALUES (1, 'from-00002');
+
+-- +goose Down
+DROP TABLE t_v2;
+`
+	}
+	return fstest.MapFS{
+		"migrations/" + dialect + "/00001_init.sql":     &fstest.MapFile{Data: []byte(v1)},
+		"migrations/" + dialect + "/00002_add_t_v2.sql": &fstest.MapFile{Data: []byte(v2)},
+	}
+}
+
+func serverFollowupFS(dialect string) fstest.MapFS {
+	v1 := `-- +goose Up
+CREATE TABLE should_not_exist_from_00001_rerun (id INTEGER);
+
+-- +goose Down
+DROP TABLE should_not_exist_from_00001_rerun;
+`
+	v2 := `-- +goose Up
+CREATE TABLE of_upgrade_probe (id INTEGER PRIMARY KEY, note TEXT NOT NULL DEFAULT '');
+INSERT INTO of_upgrade_probe (id, note) VALUES (1, 'from-00002');
+
+-- +goose Down
+DROP TABLE of_upgrade_probe;
+`
+	if dialect == "postgres" {
+		v1 = `-- +goose Up
+CREATE TABLE should_not_exist_from_00001_rerun (id BIGINT);
+
+-- +goose Down
+DROP TABLE should_not_exist_from_00001_rerun;
+`
+		v2 = `-- +goose Up
+CREATE TABLE of_upgrade_probe (id BIGINT PRIMARY KEY, note TEXT NOT NULL DEFAULT '');
+INSERT INTO of_upgrade_probe (id, note) VALUES (1, 'from-00002');
+
+-- +goose Down
+DROP TABLE of_upgrade_probe;
+`
+	}
+	return fstest.MapFS{
+		"migrations/" + dialect + "/00001_initial.sql":       &fstest.MapFile{Data: []byte(v1)},
+		"migrations/" + dialect + "/00002_upgrade_probe.sql": &fstest.MapFile{Data: []byte(v2)},
+	}
+}
+
+func pluginSchemaVersion(t *testing.T, db *gorm.DB, pluginID string) int64 {
+	t.Helper()
+	var v int64
+	err := db.Raw(`SELECT COALESCE(MAX(version_id), 0) FROM w_schema_versions WHERE plugin_id = ?`, pluginID).Scan(&v).Error
+	require.NoError(t, err)
+	return v
+}
+
+func tableRowCount(t *testing.T, db *gorm.DB, name string) int {
+	t.Helper()
+	if !safePGIdent(name) {
+		t.Fatalf("unsafe table name %q", name)
+	}
+	var n int
+	err := db.Raw("SELECT COUNT(*) FROM " + name).Scan(&n).Error
+	require.NoError(t, err)
+	return n
+}
+
+func pgTableExists(t *testing.T, db *gorm.DB, name string) bool {
+	t.Helper()
+	var n int
+	err := db.Raw(`SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public' AND table_name = ?`, name).Scan(&n).Error
+	require.NoError(t, err)
+	return n > 0
+}
+
+func openMigratePostgresDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	host, port, user, pass, dbName, sslMode, cleanup := createMigratePostgresDB(t)
+	t.Cleanup(cleanup)
+	dsn := postgresDSN(host, port, user, pass, dbName, sslMode)
+	gdb, err := gorm.Open(postgres.Open(dsn), &gorm.Config{Logger: gormlogger.Default.LogMode(gormlogger.Silent)})
+	require.NoError(t, err)
+	return gdb
+}
+
+func createMigratePostgresDB(t *testing.T) (host string, port int, user, pass, dbName, sslMode string, cleanup func()) {
+	t.Helper()
+	dsn := strings.TrimSpace(os.Getenv("TEST_PG_DSN"))
+	if dsn == "" {
+		t.Skip("TEST_PG_DSN is not set")
+	}
+	host, port, user, pass, adminDB, sslMode := parsePostgresDSN(t, dsn)
+	adminDSN := postgresDSN(host, port, user, pass, adminDB, sslMode)
+	admin := openInspectDB(t, "", adminDSN)
+	dbName = fmt.Sprintf("of_mig_%d", time.Now().UnixNano())
+	if !safePGIdent(dbName) {
+		t.Fatalf("generated database name %q is not a safe identifier", dbName)
+	}
+	if _, err := admin.Exec("CREATE DATABASE " + dbName); err != nil {
+		t.Fatalf("CREATE DATABASE %s: %v", dbName, err)
+	}
+	cleanup = func() {
+		_, _ = admin.Exec(`SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1 AND pid <> pg_backend_pid()`, dbName)
+		_, _ = admin.Exec("DROP DATABASE IF EXISTS " + dbName)
+		_ = admin.Close()
+	}
+	return host, port, user, pass, dbName, sslMode, cleanup
+}

backend/cmd/parity_test.go

@@ -0,0 +1,108 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"Wavelet/core"
+)
+
+// baselineRoutesFile 是改造前遗留注册路径导出的 (方法 路径) 全集。
+const baselineRoutesFile = "docs/superpowers/specs/baseline/routes-engine.txt"
+
+func TestPluginRoutesContainGoldenBaseline(t *testing.T) {
+	app := newOpenFlareApp(core.ProfileAPI, core.WithConfigSource(testSource(t)))
+	if err := app.Prepare(); err != nil {
+		t.Fatal(err)
+	}
+	if err := app.Reconcile(); err != nil {
+		t.Fatal(err)
+	}
+
+	got := routeSet(app.Context())
+	want := loadBaseline(t)
+	for _, drop := range []string{
+		"GET /api/health",
+		"GET /healthz",
+		"POST /api/cap/challenge",
+		"POST /api/cap/redeem",
+	} {
+		delete(want, drop)
+	}
+	for k := range want {
+		if !got[k] {
+			t.Errorf("missing golden route %s", k)
+		}
+	}
+	for _, must := range []string{
+		"GET /api/healthz",
+		"POST /api/v1/cap/challenge",
+		"POST /api/v1/cap/redeem",
+	} {
+		if !got[must] {
+			t.Errorf("missing required route %s", must)
+		}
+	}
+	for _, drop := range []string{
+		"GET /api/health",
+		"GET /healthz",
+		"POST /api/cap/challenge",
+		"POST /api/cap/redeem",
+	} {
+		if got[drop] {
+			t.Errorf("removed route still registered: %s", drop)
+		}
+	}
+}
+
+func routeSet(ctx *core.Context) map[string]bool {
+	set := make(map[string]bool)
+	for _, rd := range ctx.Router().Routes() {
+		set[rd.Method+" "+rd.Path] = true
+	}
+	return set
+}
+
+func loadBaseline(t *testing.T) map[string]bool {
+	t.Helper()
+	path := locateFile(t, baselineRoutesFile)
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read baseline %s: %v", path, err)
+	}
+	set := make(map[string]bool)
+	for _, line := range strings.Split(string(data), "\n") {
+		line = strings.TrimSpace(line)
+		if line != "" {
+			set[line] = true
+		}
+	}
+	if len(set) == 0 {
+		t.Fatalf("baseline %s is empty", path)
+	}
+	return set
+}
+
+func locateFile(t *testing.T, rel string) string {
+	t.Helper()
+	_, thisFile, _, ok := runtime.Caller(0)
+	if !ok {
+		t.Fatal("runtime.Caller failed")
+	}
+	dir := filepath.Dir(thisFile)
+	for range 8 {
+		candidate := filepath.Join(dir, rel)
+		if _, err := os.Stat(candidate); err == nil {
+			return candidate
+		}
+		dir = filepath.Join(dir, "..")
+	}
+	t.Fatalf("%s not found above %s", rel, filepath.Dir(thisFile))
+	return ""
+}

backend/cmd/relay/main.go

@@ -0,0 +1,41 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Command relay runs the OpenFlare relay node daemon.
+package main
+
+import (
+	"flag"
+	"log/slog"
+	"os"
+	"time"
+
+	"Wavelet/core"
+	relayplugin "Wavelet/openflare/plugins/relay"
+	edgelogging "Wavelet/openflare/share/edge/logging"
+)
+
+// shutdownTimeout 为 frps 子进程收敛预留的退出窗口。
+const shutdownTimeout = 60 * time.Second
+
+func main() {
+	edgelogging.Setup(edgelogging.Options{})
+
+	configPath := flag.String("config", "./relay.json", "relay config path")
+	flag.Parse()
+
+	app := core.NewApp(
+		core.WithProfile(core.Profile(relayplugin.DriverTypeRelay)),
+		core.WithShutdownTimeout(shutdownTimeout),
+	)
+	app.Use(relayplugin.New(*configPath))
+
+	if err := app.Prepare(); err != nil {
+		slog.Error("relay startup failed", "error", err)
+		os.Exit(1)
+	}
+	if err := app.Run(); err != nil {
+		slog.Error("relay process exited with error", "error", err)
+		os.Exit(1)
+	}
+}

backend/cmd/reset_passwd.go

@@ -4,6 +4,8 @@
 package cmd
 
 import (
+	"Wavelet/plugins/domain/auth"
+	"Wavelet/plugins/infra/database"
 	"bufio"
 	"context"
 	"crypto/rand"
@@ -13,12 +15,8 @@ import (
 	"os"
 	"strings"
 
-	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
-	"github.com/Rain-kl/Wavelet/internal/infra/persistence"
-	"github.com/Rain-kl/Wavelet/internal/infra/persistence/migrator"
-	"github.com/Rain-kl/Wavelet/internal/model"
-	"github.com/Rain-kl/Wavelet/internal/platform/bootstrap"
-	"github.com/Rain-kl/Wavelet/internal/repository"
+	userdomain "Wavelet/plugins/domain/user"
+
 	"github.com/spf13/cobra"
 	"gorm.io/gorm"
 )
@@ -47,12 +45,14 @@ func generateRandomPassword(length int) (string, error) {
 var resetPasswdCmd = &cobra.Command{
 	Use:   "reset-passwd",
 	Short: "重置指定账号密码",
-	PreRun: func(_ *cobra.Command, _ []string) {
-		migrator.Migrate()
-	},
 	Run: func(_ *cobra.Command, _ []string) {
 		ctx := context.Background()
-		runBootstrap(bootstrap.Options{})
+
+		// Ensure database is initialized
+		dbConn := database.DB(ctx)
+		if dbConn != nil {
+			userdomain.SetDBService(database.NewService(dbConn))
+		}
 
 		var username string
 		if usernameFlag != "" {
@@ -70,7 +70,7 @@ var resetPasswdCmd = &cobra.Command{
 			}
 		}
 
-		user, err := repository.GetUserByUsername(ctx, username)
+		user, err := userdomain.GetUserByUsername(ctx, username)
 		if err != nil {
 			if errors.Is(err, gorm.ErrRecordNotFound) {
 				log.Fatalf("错误: 用户 '%s' 不存在\n", username)
@@ -92,26 +92,26 @@ var resetPasswdCmd = &cobra.Command{
 			log.Fatalf("加密密码失败: %v\n", err)
 		}
 
-		err = db.DB(ctx).Transaction(func(tx *gorm.DB) error {
+		err = database.DB(ctx).Transaction(func(tx *gorm.DB) error {
 			if err := tx.Model(&user).Update("password", user.Password).Error; err != nil {
 				return err
 			}
 
 			// Invalidate existing tokens
-			var tokens []model.AccessToken
+			var tokens []userdomain.AccessToken
 			if err := tx.Where("user_id = ?", user.ID).Find(&tokens).Error; err == nil {
 				for _, token := range tokens {
-					oauth.InvalidateCachedToken(ctx, token.TokenHash)
+					auth.InvalidateCachedToken(ctx, token.TokenHash)
 				}
 			}
 
-			return tx.Where("user_id = ?", user.ID).Delete(&model.AccessToken{}).Error
+			return tx.Where("user_id = ?", user.ID).Delete(&userdomain.AccessToken{}).Error
 		})
 		if err != nil {
 			log.Fatalf("重置密码失败: %v\n", err)
 		}
 
-		oauth.InvalidateCachedUser(ctx, user.ID)
+		auth.InvalidateCachedUser(ctx, user.ID)
 
 		fmt.Println("成功重置密码！")
 		fmt.Printf("用户名: %s\n", user.Username)

backend/cmd/reset_passwd_test.go

@@ -4,14 +4,14 @@
 package cmd
 
 import (
+	"Wavelet/pkg/testhelper"
 	"bytes"
 	"io"
 	"os"
 	"testing"
 	"time"
 
-	"github.com/Rain-kl/Wavelet/internal/model"
-	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	userdomain "Wavelet/plugins/domain/user"
 )
 
 func TestResetPasswdCmd_WithUserAndPassword(t *testing.T) {
@@ -19,7 +19,7 @@ func TestResetPasswdCmd_WithUserAndPassword(t *testing.T) {
 	defer cleanup()
 
 	// Seed test user
-	user := model.User{
+	user := userdomain.User{
 		ID:          1001,
 		Username:    "testuser1",
 		Nickname:    "Test User 1",
@@ -33,7 +33,7 @@ func TestResetPasswdCmd_WithUserAndPassword(t *testing.T) {
 	}
 
 	// Create access token to test invalidation/deletion
-	token := model.AccessToken{
+	token := userdomain.AccessToken{
 		ID:          1,
 		UserID:      user.ID,
 		Name:        "testtoken",
@@ -74,7 +74,7 @@ func TestResetPasswdCmd_WithUserAndPassword(t *testing.T) {
 	}
 
 	// Verify password in DB
-	var dbUser model.User
+	var dbUser userdomain.User
 	if err := dbConn.Where("id = ?", user.ID).First(&dbUser).Error; err != nil {
 		t.Fatalf("failed to query user from DB: %v", err)
 	}
@@ -84,7 +84,7 @@ func TestResetPasswdCmd_WithUserAndPassword(t *testing.T) {
 
 	// Verify token deleted
 	var count int64
-	dbConn.Model(&model.AccessToken{}).Where("user_id = ?", user.ID).Count(&count)
+	dbConn.Model(&userdomain.AccessToken{}).Where("user_id = ?", user.ID).Count(&count)
 	if count != 0 {
 		t.Errorf("expected access tokens to be deleted, got %d", count)
 	}
@@ -95,7 +95,7 @@ func TestResetPasswdCmd_WithUserAndRandomPassword(t *testing.T) {
 	defer cleanup()
 
 	// Seed test user
-	user := model.User{
+	user := userdomain.User{
 		ID:          1002,
 		Username:    "testuser2",
 		Nickname:    "Test User 2",
@@ -142,7 +142,7 @@ func TestResetPasswdCmd_WithUserAndRandomPassword(t *testing.T) {
 	}
 
 	// Verify password in DB (should be updated and not equal to old one)
-	var dbUser model.User
+	var dbUser userdomain.User
 	if err := dbConn.Where("id = ?", user.ID).First(&dbUser).Error; err != nil {
 		t.Fatalf("failed to query user from DB: %v", err)
 	}
@@ -156,7 +156,7 @@ func TestResetPasswdCmd_InteractiveMode(t *testing.T) {
 	defer cleanup()
 
 	// Seed test user
-	user := model.User{
+	user := userdomain.User{
 		ID:          1003,
 		Username:    "testuser3",
 		Nickname:    "Test User 3",
@@ -217,7 +217,7 @@ func TestResetPasswdCmd_InteractiveMode(t *testing.T) {
 	}
 
 	// Verify user password changed in DB
-	var dbUser model.User
+	var dbUser userdomain.User
 	if err := dbConn.Where("id = ?", user.ID).First(&dbUser).Error; err != nil {
 		t.Fatalf("failed to query user from DB: %v", err)
 	}

backend/cmd/root.go

@@ -0,0 +1,109 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"Wavelet/core/extpoints"
+	"Wavelet/pkg/buildinfo"
+	"Wavelet/pkg/idgen"
+	"Wavelet/pkg/logger"
+	"Wavelet/pkg/trace"
+	"Wavelet/plugins/infra/config"
+	"context"
+	"log"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+const traceShutdownTimeout = 10 * time.Second
+
+type hostConfig struct {
+	App struct {
+		AppName string `config:"app_name" env:"APP_NAME" default:"Wavelet"`
+		Env     string `config:"env" env:"APP_ENV" default:"production"`
+		NodeID  int64  `config:"node_id" env:"APP_NODE_ID" default:"1"`
+		Addr    string `config:"addr" env:"APP_ADDR" default:"127.0.0.1:3000"`
+	} `config:"app"`
+	Log struct {
+		Level      string `config:"level" env:"LOG_LEVEL" default:"info"`
+		Format     string `config:"format" env:"LOG_FORMAT" default:"json"`
+		Output     string `config:"output" env:"LOG_OUTPUT" default:"stdout"`
+		FilePath   string `config:"file_path" env:"LOG_FILE_PATH" default:"./logs/app.log"`
+		MaxSize    int    `config:"max_size" env:"LOG_MAX_SIZE" default:"100"`
+		MaxAge     int    `config:"max_age" env:"LOG_MAX_AGE" default:"30"`
+		MaxBackups int    `config:"max_backups" env:"LOG_MAX_BACKUPS" default:"10"`
+		Compress   bool   `config:"compress" env:"LOG_COMPRESS" default:"true"`
+	} `config:"log"`
+	OTel struct {
+		SamplingRate float64 `config:"sampling_rate" env:"OTEL_SAMPLING_RATE" default:"1.0"`
+		TracerName   string  `config:"tracer_name" env:"OTEL_TRACER_NAME" default:"github.com/Rain-kl/Wavelet"`
+	} `config:"otel"`
+}
+
+var rootCmd = &cobra.Command{
+	Use: "wavelet",
+	PersistentPreRun: func(_ *cobra.Command, _ []string) {
+		src, err := config.NewSource()
+		if err != nil {
+			log.Fatalf("[CMD] load config source failed: %v", err)
+		}
+		var cfg hostConfig
+		reg := extpoints.NewConfigRegistry(src)
+		_ = reg.Declare("host", extpoints.ConfigBinding{Target: &cfg})
+		if err := reg.Resolve(); err != nil {
+			log.Fatalf("[CMD] resolve host config failed: %v", err)
+		}
+		_ = reg.Bind("", &cfg)
+
+		// Initialize idgen snowflake generator
+		if err := idgen.Init(cfg.App.NodeID); err != nil {
+			log.Fatalf("[CMD] init idgen failed: %v", err)
+		}
+
+		logger.Init(logger.Config{
+			Level:      cfg.Log.Level,
+			Format:     cfg.Log.Format,
+			Output:     cfg.Log.Output,
+			FilePath:   cfg.Log.FilePath,
+			MaxSize:    cfg.Log.MaxSize,
+			MaxAge:     cfg.Log.MaxAge,
+			MaxBackups: cfg.Log.MaxBackups,
+			Compress:   cfg.Log.Compress,
+		})
+		trace.Init(trace.Config{
+			AppName:      cfg.App.AppName,
+			SamplingRate: cfg.OTel.SamplingRate,
+			TracerName:   cfg.OTel.TracerName,
+		})
+	},
+	PersistentPostRun: func(_ *cobra.Command, _ []string) {
+		shutdownTraceProvider()
+	},
+	Run: func(_ *cobra.Command, args []string) {
+		// 无参数时默认以融合模式启动所有服务
+		allCmd.Run(allCmd, args)
+	},
+}
+
+func shutdownTraceProvider() {
+	ctx, cancel := context.WithTimeout(context.Background(), traceShutdownTimeout)
+	defer cancel()
+	trace.Shutdown(ctx)
+}
+
+func init() {
+	rootCmd.Version = buildinfo.Version
+	rootCmd.CompletionOptions.DisableDefaultCmd = true
+
+	// 集中将子命令注册到根命令，以解决 Cobra 的 unknown command 校验限制
+	rootCmd.AddCommand(allCmd, apiCmd, workerCmd, schedulerCmd)
+}
+
+// Execute 执行根命令
+func Execute() {
+	if err := rootCmd.Execute(); err != nil {
+		log.Fatalf("[CMD] execute failed; %s\n", err)
+	}
+}

backend/cmd/scheduler.go

@@ -0,0 +1,18 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"Wavelet/core"
+
+	"github.com/spf13/cobra"
+)
+
+var schedulerCmd = &cobra.Command{
+	Use:   "scheduler",
+	Short: "wavelet Scheduler",
+	Run: func(_ *cobra.Command, _ []string) {
+		runProfileApp(core.ProfileSchedule, "scheduler", false)
+	},
+}

backend/cmd/upgrade_from_golden_test.go

@@ -0,0 +1,771 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"bytes"
+	"context"
+	"database/sql"
+	"fmt"
+	"io"
+	"net"
+	"net/url"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"Wavelet/core"
+
+	"github.com/glebarez/sqlite"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	gormlogger "gorm.io/gorm/logger"
+)
+
+const (
+	goldenRoot        = "/Users/ryan/Code/Go/OpenFlare"
+	goldCommit        = "9f79fb99"
+	goldGooseVersion  = int64(202608090003)
+	sampleZoneDomain  = "l3-upgrade-golden.example"
+	goldMigrateWait   = 75 * time.Second
+	legacyPluginStamp = "openflare/legacy"
+	serverPluginStamp = "server"
+)
+
+var (
+	goldBinOnce sync.Once
+	goldBinPath string
+	goldSrcDir  string
+	goldBinErr  error
+)
+
+func TestUpgradeFromGolden(t *testing.T) {
+	t.Run("sqlite", func(t *testing.T) {
+		tmp := t.TempDir()
+		dbPath := filepath.Join(tmp, "a.db")
+		runGoldenAPI(t, tmp, goldSQLiteEnv(t, tmp, dbPath), func() bool {
+			return sqliteReady(dbPath)
+		})
+		assertUpgradeFromGolden(t, upgradeDB{
+			sqlitePath: dbPath,
+			source:     cordisSQLiteSource(t, dbPath),
+		})
+	})
+}
+
+func TestUpgradePostgresFromGolden(t *testing.T) {
+	dsn := strings.TrimSpace(os.Getenv("TEST_PG_DSN"))
+	if dsn == "" {
+		t.Skip("TEST_PG_DSN is not set")
+	}
+
+	host, port, user, pass, adminDB, sslMode := parsePostgresDSN(t, dsn)
+	adminDSN := postgresDSN(host, port, user, pass, adminDB, sslMode)
+	admin := openInspectDB(t, "", adminDSN)
+	t.Cleanup(func() { _ = admin.Close() })
+
+	dbName := fmt.Sprintf("of_l3_%d", time.Now().UnixNano())
+	if !safePGIdent(dbName) {
+		t.Fatalf("generated database name %q is not a safe identifier", dbName)
+	}
+	if _, err := admin.Exec("CREATE DATABASE " + dbName); err != nil {
+		t.Fatalf("CREATE DATABASE %s: %v", dbName, err)
+	}
+	t.Cleanup(func() {
+		_, _ = admin.Exec(`SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = $1 AND pid <> pg_backend_pid()`, dbName)
+		_, _ = admin.Exec("DROP DATABASE IF EXISTS " + dbName)
+	})
+
+	tmp := t.TempDir()
+	testDSN := postgresDSN(host, port, user, pass, dbName, sslMode)
+	runGoldenAPI(t, tmp, goldPostgresEnv(t, tmp, host, port, user, pass, dbName, sslMode), func() bool {
+		return postgresReady(testDSN)
+	})
+	assertUpgradeFromGolden(t, upgradeDB{
+		pgDSN:  testDSN,
+		source: cordisPostgresSource(t, host, port, user, pass, dbName, sslMode),
+	})
+}
+
+func TestUpgradePostgresFromExistingDump(t *testing.T) {
+	dsn := strings.TrimSpace(os.Getenv("TEST_PG_EXISTING_DSN"))
+	if dsn == "" {
+		t.Skip("TEST_PG_EXISTING_DSN is not set")
+	}
+
+	host, port, user, pass, dbName, sslMode := parsePostgresDSN(t, dsn)
+	spec := upgradeDB{
+		pgDSN:  dsn,
+		source: cordisPostgresSource(t, host, port, user, pass, dbName, sslMode),
+	}
+
+	inspect := openInspectDB(t, "", spec.pgDSN)
+	beforeCounts := countNamedTables(t, inspect, productionCountTables)
+	beforeTables := listPublicTables(t, inspect)
+	_ = inspect.Close()
+
+	assertUpgradeFromGolden(t, spec)
+
+	inspect = openInspectDB(t, "", spec.pgDSN)
+	defer func() { _ = inspect.Close() }()
+	afterCounts := countNamedTables(t, inspect, productionCountTables)
+	for _, name := range productionCountTables {
+		if afterCounts[name] < beforeCounts[name] {
+			t.Errorf("row count dropped for %s: before %d after %d", name, beforeCounts[name], afterCounts[name])
+		}
+	}
+	afterTables := listPublicTables(t, inspect)
+	for name := range beforeTables {
+		if !afterTables[name] {
+			t.Errorf("table %s dropped", name)
+		}
+	}
+	for _, name := range []string{"w_schema_versions", "w_message_channels", "w_message_bindings", "w_message_pairing_codes"} {
+		if !afterTables[name] {
+			t.Errorf("expected upgrade to create %s", name)
+		}
+	}
+	var n int
+	if err := inspect.QueryRow(`SELECT COUNT(*) FROM pg_inherits i JOIN pg_class c ON c.oid = i.inhparent WHERE c.relname IN ('of_node_access_logs', 'w_user_access_logs')`).Scan(&n); err != nil {
+		t.Fatalf("count partitions: %v", err)
+	}
+	if n < 8 {
+		t.Errorf("partition children = %d, want at least 8", n)
+	}
+}
+
+var productionCountTables = []string{
+	"of_zones", "of_zone_domains", "of_proxy_routes", "of_nodes", "of_origins",
+	"of_tls_certificates", "of_waf_rule_groups", "of_pages_projects",
+	"w_users", "w_schedules", "w_system_configs", "w_templates", "w_uploads",
+	"of_node_access_logs", "w_user_access_logs",
+}
+
+func countNamedTables(t *testing.T, db *sql.DB, tables []string) map[string]int {
+	t.Helper()
+	out := make(map[string]int, len(tables))
+	for _, name := range tables {
+		if !safePGIdent(name) {
+			t.Fatalf("unsafe table name %q", name)
+		}
+		var n int
+		if err := db.QueryRow("SELECT COUNT(*) FROM " + name).Scan(&n); err != nil {
+			t.Fatalf("count %s: %v", name, err)
+		}
+		out[name] = n
+	}
+	return out
+}
+
+func listPublicTables(t *testing.T, db *sql.DB) map[string]bool {
+	t.Helper()
+	rows, err := db.Query(`SELECT tablename FROM pg_tables WHERE schemaname = 'public'`)
+	if err != nil {
+		t.Fatalf("list public tables: %v", err)
+	}
+	defer func() { _ = rows.Close() }()
+	out := make(map[string]bool)
+	for rows.Next() {
+		var name string
+		if err := rows.Scan(&name); err != nil {
+			t.Fatalf("scan table name: %v", err)
+		}
+		out[name] = true
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("list public tables: %v", err)
+	}
+	return out
+}
+
+type upgradeDB struct {
+	sqlitePath string
+	pgDSN      string
+	source     core.ConfigSource
+}
+
+func assertUpgradeFromGolden(t *testing.T, spec upgradeDB) {
+	t.Helper()
+
+	inspect := openInspectDB(t, spec.sqlitePath, spec.pgDSN)
+	before := dumpOfSchema(t, inspect, spec.pgDSN != "")
+	insertSQL := `INSERT INTO of_zones (domain) VALUES (?)`
+	if spec.pgDSN != "" {
+		insertSQL = `INSERT INTO of_zones (domain) VALUES ($1)`
+	}
+	if _, err := inspect.Exec(insertSQL, sampleZoneDomain); err != nil {
+		t.Fatalf("insert sample of_zones row: %v", err)
+	}
+	_ = inspect.Close()
+
+	app := cordisPrepare(t, spec.source)
+	legacyRows := schemaPluginRows(t, spec, legacyPluginStamp)
+	assertStampedUpgrade(t, spec, before, legacyRows)
+	if err := app.Context().Dispose(); err != nil {
+		t.Fatalf("dispose first app: %v", err)
+	}
+
+	app2 := cordisPrepare(t, spec.source)
+	t.Cleanup(func() { _ = app2.Context().Dispose() })
+	if got := schemaPluginRows(t, spec, legacyPluginStamp); got != legacyRows {
+		t.Fatalf("second Prepare increased %s rows: got %d, want %d", legacyPluginStamp, got, legacyRows)
+	}
+	assertStampedUpgrade(t, spec, before, legacyRows)
+}
+
+func cordisPrepare(t *testing.T, src core.ConfigSource) *core.App {
+	t.Helper()
+	app := newOpenFlareApp(core.ProfileAPI, core.WithConfigSource(src))
+	if err := app.Prepare(); err != nil {
+		t.Fatalf("Prepare: %v", err)
+	}
+	if err := app.ApplyPlugins(); err != nil {
+		t.Fatalf("ApplyPlugins: %v", err)
+	}
+	if err := app.RunMigrations(); err != nil {
+		t.Fatalf("RunMigrations: %v", err)
+	}
+	return app
+}
+
+func assertStampedUpgrade(t *testing.T, spec upgradeDB, before map[string][]string, legacyRows int) {
+	t.Helper()
+	db := openInspectDB(t, spec.sqlitePath, spec.pgDSN)
+	defer func() { _ = db.Close() }()
+	postgres := spec.pgDSN != ""
+
+	if got := gooseMaxVersion(t, db); got != goldGooseVersion {
+		t.Errorf("goose_db_version max = %d, want %d", got, goldGooseVersion)
+	}
+	if legacyRows < 2 {
+		t.Errorf("w_schema_versions %s rows = %d, want at least 2 (0 and %d)", legacyPluginStamp, legacyRows, goldGooseVersion)
+	}
+	if !pluginHasVersion(t, db, postgres, legacyPluginStamp, 0) {
+		t.Errorf("missing w_schema_versions (%s, 0)", legacyPluginStamp)
+	}
+	if !pluginHasVersion(t, db, postgres, legacyPluginStamp, goldGooseVersion) {
+		t.Errorf("missing w_schema_versions (%s, %d)", legacyPluginStamp, goldGooseVersion)
+	}
+	if !pluginHasVersion(t, db, postgres, serverPluginStamp, 1) {
+		t.Errorf("missing w_schema_versions (%s, 1)", serverPluginStamp)
+	}
+
+	var domain string
+	q := `SELECT domain FROM of_zones WHERE domain = ?`
+	if postgres {
+		q = `SELECT domain FROM of_zones WHERE domain = $1`
+	}
+	if err := db.QueryRow(q, sampleZoneDomain).Scan(&domain); err != nil {
+		t.Errorf("sample of_zones row missing after upgrade: %v", err)
+	}
+
+	after := dumpOfSchema(t, db, postgres)
+	for table, cols := range before {
+		got, ok := after[table]
+		if !ok {
+			t.Errorf("of_* table %s dropped", table)
+			continue
+		}
+		have := make(map[string]bool, len(got))
+		for _, c := range got {
+			have[c] = true
+		}
+		for _, c := range cols {
+			if !have[c] {
+				t.Errorf("of_* column %s.%s dropped", table, c)
+			}
+		}
+	}
+}
+
+func runGoldenAPI(t *testing.T, workDir string, env []string, ready func() bool) {
+	t.Helper()
+	bin := buildGoldenBinary(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), goldMigrateWait)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, bin, "api")
+	cmd.Dir = workDir
+	cmd.Env = env
+	var out bytes.Buffer
+	cmd.Stdout = &out
+	cmd.Stderr = &out
+	if err := cmd.Start(); err != nil {
+		t.Fatalf("start golden api: %v", err)
+	}
+
+	waitErr := make(chan error, 1)
+	go func() { waitErr <- cmd.Wait() }()
+
+	ticker := time.NewTicker(200 * time.Millisecond)
+	defer ticker.Stop()
+	for {
+		if ready() {
+			killGolden(cmd)
+			<-waitErr
+			return
+		}
+		select {
+		case err := <-waitErr:
+			if ready() {
+				return
+			}
+			t.Fatalf("golden api exited before goose %d: %v\n%s", goldGooseVersion, err, out.String())
+		case <-ctx.Done():
+			killGolden(cmd)
+			<-waitErr
+			t.Fatalf("timeout waiting for golden goose %d\n%s", goldGooseVersion, out.String())
+		case <-ticker.C:
+		}
+	}
+}
+
+func killGolden(cmd *exec.Cmd) {
+	if cmd.Process == nil {
+		return
+	}
+	_ = cmd.Process.Kill()
+}
+
+func buildGoldenBinary(t *testing.T) string {
+	t.Helper()
+	goldBinOnce.Do(func() {
+		src, err := os.MkdirTemp("", "of-gold-src-")
+		if err != nil {
+			goldBinErr = err
+			return
+		}
+		archive := exec.Command("git", "-C", goldenRoot, "archive", goldCommit)
+		extract := exec.Command("tar", "-x", "-C", src)
+		pipe, err := archive.StdoutPipe()
+		if err != nil {
+			goldBinErr = fmt.Errorf("gold archive pipe: %w", err)
+			return
+		}
+		extract.Stdin = pipe
+		var archiveErr, extractErr bytes.Buffer
+		archive.Stderr = &archiveErr
+		extract.Stderr = &extractErr
+		if err := archive.Start(); err != nil {
+			goldBinErr = fmt.Errorf("git archive %s: %w", goldCommit, err)
+			return
+		}
+		if err := extract.Start(); err != nil {
+			_ = archive.Process.Kill()
+			goldBinErr = fmt.Errorf("extract gold %s: %w", goldCommit, err)
+			return
+		}
+		if err := extract.Wait(); err != nil {
+			_ = archive.Wait()
+			goldBinErr = fmt.Errorf("extract gold %s: %w\n%s", goldCommit, err, extractErr.String())
+			return
+		}
+		if err := archive.Wait(); err != nil {
+			goldBinErr = fmt.Errorf("git archive %s: %w\n%s", goldCommit, err, archiveErr.String())
+			return
+		}
+		if _, err := os.Stat(filepath.Join(src, "main.go")); err != nil {
+			goldBinErr = fmt.Errorf("gold %s at %s: %w", goldCommit, src, err)
+			return
+		}
+		goldSrcDir = src
+
+		dir, err := os.MkdirTemp("", "of-gold-bin-")
+		if err != nil {
+			goldBinErr = err
+			return
+		}
+		out := filepath.Join(dir, "gold")
+		cmd := exec.Command("go", "build", "-o", out, ".")
+		cmd.Dir = src
+		var buf bytes.Buffer
+		cmd.Stdout = &buf
+		cmd.Stderr = &buf
+		if err := cmd.Run(); err != nil {
+			goldBinErr = fmt.Errorf("go build golden %s: %w\n%s", goldCommit, err, buf.String())
+			return
+		}
+		goldBinPath = out
+	})
+	if goldBinErr != nil {
+		t.Fatalf("%v", goldBinErr)
+	}
+	return goldBinPath
+}
+
+func copyGoldConfig(t *testing.T, dir string) string {
+	t.Helper()
+	buildGoldenBinary(t)
+	dst := filepath.Join(dir, "config.yaml")
+	src, err := os.Open(filepath.Join(goldSrcDir, "config.example.yaml")) //nolint:gosec // extracted gold snapshot
+	if err != nil {
+		t.Fatalf("open golden config.example.yaml: %v", err)
+	}
+	defer func() { _ = src.Close() }()
+	out, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o600) //nolint:gosec // test temp file
+	if err != nil {
+		t.Fatalf("create temp config.yaml: %v", err)
+	}
+	if _, err := io.Copy(out, src); err != nil {
+		_ = out.Close()
+		t.Fatalf("copy golden config: %v", err)
+	}
+	if err := out.Close(); err != nil {
+		t.Fatalf("close temp config.yaml: %v", err)
+	}
+	return dst
+}
+
+func goldSQLiteEnv(t *testing.T, dir, dbPath string) []string {
+	t.Helper()
+	cfg := copyGoldConfig(t, dir)
+	addr := freeLocalAddr(t)
+	return filteredGoldEnv(
+		"CONFIG_PATH="+cfg,
+		"SQLITE_PATH="+dbPath,
+		"DB_ENABLED=false",
+		"REDIS_ENABLED=false",
+		"CLICKHOUSE_ENABLED=false",
+		"APP_ENV=testing",
+		"APP_ADDR="+addr,
+	)
+}
+
+func goldPostgresEnv(t *testing.T, dir, host string, port int, user, pass, dbName, sslMode string) []string {
+	t.Helper()
+	cfg := copyGoldConfig(t, dir)
+	addr := freeLocalAddr(t)
+	return filteredGoldEnv(
+		"CONFIG_PATH="+cfg,
+		"DB_ENABLED=true",
+		"DB_HOST="+host,
+		"DB_PORT="+strconv.Itoa(port),
+		"DB_USERNAME="+user,
+		"DB_PASSWORD="+pass,
+		"DB_NAME="+dbName,
+		"DB_SSL_MODE="+sslMode,
+		"REDIS_ENABLED=false",
+		"CLICKHOUSE_ENABLED=false",
+		"APP_ENV=testing",
+		"APP_ADDR="+addr,
+	)
+}
+
+func filteredGoldEnv(extra ...string) []string {
+	drop := map[string]bool{
+		"CONFIG_PATH":        true,
+		"SQLITE_PATH":        true,
+		"DB_ENABLED":         true,
+		"DB_HOST":            true,
+		"DB_PORT":            true,
+		"DB_USERNAME":        true,
+		"DB_PASSWORD":        true,
+		"DB_NAME":            true,
+		"DB_SSL_MODE":        true,
+		"REDIS_ENABLED":      true,
+		"REDIS_ADDR":         true,
+		"CLICKHOUSE_ENABLED": true,
+		"CLICKHOUSE_HOST":    true,
+		"APP_ENV":            true,
+		"APP_ADDR":           true,
+	}
+	env := make([]string, 0, len(os.Environ())+len(extra))
+	for _, kv := range os.Environ() {
+		k, _, _ := strings.Cut(kv, "=")
+		if drop[k] {
+			continue
+		}
+		env = append(env, kv)
+	}
+	return append(env, extra...)
+}
+
+func freeLocalAddr(t *testing.T) string {
+	t.Helper()
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen for free port: %v", err)
+	}
+	addr := ln.Addr().String()
+	_ = ln.Close()
+	return addr
+}
+
+func cordisSQLiteSource(t *testing.T, dbPath string) core.ConfigSource {
+	t.Helper()
+	return core.NewMapSource(map[string]any{
+		"app": map[string]any{
+			"addr": "127.0.0.1:0",
+			"env":  "testing",
+		},
+		"redis": map[string]any{
+			"enabled": false,
+		},
+		"clickhouse": map[string]any{
+			"enabled": false,
+		},
+		"database": map[string]any{
+			"enabled":     false,
+			"sqlite_path": dbPath,
+		},
+	})
+}
+
+func cordisPostgresSource(t *testing.T, host string, port int, user, pass, dbName, sslMode string) core.ConfigSource {
+	t.Helper()
+	return core.NewMapSource(map[string]any{
+		"app": map[string]any{
+			"addr": "127.0.0.1:0",
+			"env":  "testing",
+		},
+		"redis": map[string]any{
+			"enabled": false,
+		},
+		"clickhouse": map[string]any{
+			"enabled": false,
+		},
+		"database": map[string]any{
+			"enabled":  true,
+			"host":     host,
+			"port":     port,
+			"username": user,
+			"password": pass,
+			"database": dbName,
+			"ssl_mode": sslMode,
+		},
+	})
+}
+
+func sqliteReady(path string) bool {
+	if _, err := os.Stat(path); err != nil {
+		return false
+	}
+	gdb, err := gorm.Open(sqlite.Open("file:"+path+"?mode=ro&_pragma=busy_timeout(1000)"), &gorm.Config{Logger: gormlogger.Default.LogMode(gormlogger.Silent)})
+	if err != nil {
+		return false
+	}
+	sqlDB, err := gdb.DB()
+	if err != nil {
+		return false
+	}
+	defer func() { _ = sqlDB.Close() }()
+	return migratedReady(sqlDB, false)
+}
+
+func postgresReady(dsn string) bool {
+	gdb, err := gorm.Open(postgres.Open(dsn), &gorm.Config{Logger: gormlogger.Default.LogMode(gormlogger.Silent)})
+	if err != nil {
+		return false
+	}
+	sqlDB, err := gdb.DB()
+	if err != nil {
+		return false
+	}
+	defer func() { _ = sqlDB.Close() }()
+	return migratedReady(sqlDB, true)
+}
+
+func migratedReady(db *sql.DB, postgres bool) bool {
+	if gooseMaxVersionSilent(db) != goldGooseVersion {
+		return false
+	}
+	var n int
+	var err error
+	if postgres {
+		err = db.QueryRow(`SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public' AND table_name = 'of_nodes'`).Scan(&n)
+	} else {
+		err = db.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = 'of_nodes'`).Scan(&n)
+	}
+	return err == nil && n > 0
+}
+
+func openInspectDB(t *testing.T, sqlitePath, pgDSN string) *sql.DB {
+	t.Helper()
+	var gdb *gorm.DB
+	var err error
+	if pgDSN != "" {
+		gdb, err = gorm.Open(postgres.Open(pgDSN), &gorm.Config{Logger: gormlogger.Default.LogMode(gormlogger.Silent)})
+	} else {
+		gdb, err = gorm.Open(sqlite.Open(sqlitePath), &gorm.Config{Logger: gormlogger.Default.LogMode(gormlogger.Silent)})
+	}
+	if err != nil {
+		t.Fatalf("open inspect db: %v", err)
+	}
+	sqlDB, err := gdb.DB()
+	if err != nil {
+		t.Fatalf("inspect sql.DB: %v", err)
+	}
+	return sqlDB
+}
+
+func dumpOfSchema(t *testing.T, db *sql.DB, postgres bool) map[string][]string {
+	t.Helper()
+	tables := ofTables(t, db, postgres)
+	out := make(map[string][]string, len(tables))
+	for _, table := range tables {
+		out[table] = ofColumns(t, db, postgres, table)
+	}
+	if len(out) == 0 {
+		t.Fatal("no of_* tables in golden database")
+	}
+	return out
+}
+
+func ofTables(t *testing.T, db *sql.DB, postgres bool) []string {
+	t.Helper()
+	var rows *sql.Rows
+	var err error
+	if postgres {
+		rows, err = db.Query(`SELECT tablename FROM pg_tables WHERE schemaname = 'public' AND tablename LIKE 'of_%' ORDER BY tablename`)
+	} else {
+		rows, err = db.Query(`SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'of_%' ORDER BY name`)
+	}
+	if err != nil {
+		t.Fatalf("list of_* tables: %v", err)
+	}
+	defer func() { _ = rows.Close() }()
+	var tables []string
+	for rows.Next() {
+		var name string
+		if err := rows.Scan(&name); err != nil {
+			t.Fatalf("scan of_* table: %v", err)
+		}
+		tables = append(tables, name)
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("list of_* tables: %v", err)
+	}
+	return tables
+}
+
+func ofColumns(t *testing.T, db *sql.DB, postgres bool, table string) []string {
+	t.Helper()
+	var rows *sql.Rows
+	var err error
+	if postgres {
+		rows, err = db.Query(`SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = $1 ORDER BY ordinal_position`, table)
+	} else {
+		rows, err = db.Query(`SELECT name FROM pragma_table_info(?)`, table)
+	}
+	if err != nil {
+		t.Fatalf("list columns for %s: %v", table, err)
+	}
+	defer func() { _ = rows.Close() }()
+	var cols []string
+	for rows.Next() {
+		var name string
+		if err := rows.Scan(&name); err != nil {
+			t.Fatalf("scan column for %s: %v", table, err)
+		}
+		cols = append(cols, name)
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("list columns for %s: %v", table, err)
+	}
+	return cols
+}
+
+func gooseMaxVersion(t *testing.T, db *sql.DB) int64 {
+	t.Helper()
+	v := gooseMaxVersionSilent(db)
+	if v < 0 {
+		t.Fatal("read goose_db_version max failed")
+	}
+	return v
+}
+
+func gooseMaxVersionSilent(db *sql.DB) int64 {
+	var v int64
+	if err := db.QueryRow(`SELECT COALESCE(MAX(version_id), 0) FROM goose_db_version`).Scan(&v); err != nil {
+		return -1
+	}
+	return v
+}
+
+func schemaPluginRows(t *testing.T, spec upgradeDB, pluginID string) int {
+	t.Helper()
+	db := openInspectDB(t, spec.sqlitePath, spec.pgDSN)
+	defer func() { _ = db.Close() }()
+	q := `SELECT COUNT(*) FROM w_schema_versions WHERE plugin_id = ?`
+	if spec.pgDSN != "" {
+		q = `SELECT COUNT(*) FROM w_schema_versions WHERE plugin_id = $1`
+	}
+	var n int
+	if err := db.QueryRow(q, pluginID).Scan(&n); err != nil {
+		t.Fatalf("count w_schema_versions %s: %v", pluginID, err)
+	}
+	return n
+}
+
+func pluginHasVersion(t *testing.T, db *sql.DB, postgres bool, pluginID string, version int64) bool {
+	t.Helper()
+	q := `SELECT COUNT(*) FROM w_schema_versions WHERE plugin_id = ? AND version_id = ?`
+	if postgres {
+		q = `SELECT COUNT(*) FROM w_schema_versions WHERE plugin_id = $1 AND version_id = $2`
+	}
+	var n int
+	if err := db.QueryRow(q, pluginID, version).Scan(&n); err != nil {
+		t.Fatalf("lookup w_schema_versions (%s, %d): %v", pluginID, version, err)
+	}
+	return n > 0
+}
+
+func parsePostgresDSN(t *testing.T, dsn string) (host string, port int, user, pass, dbName, sslMode string) {
+	t.Helper()
+	u, err := url.Parse(dsn)
+	if err != nil {
+		t.Fatalf("TEST_PG_DSN: %v", err)
+	}
+	host = u.Hostname()
+	if host == "" {
+		host = "127.0.0.1"
+	}
+	port = 5432
+	if p := u.Port(); p != "" {
+		port, err = strconv.Atoi(p)
+		if err != nil {
+			t.Fatalf("TEST_PG_DSN port: %v", err)
+		}
+	}
+	if u.User != nil {
+		user = u.User.Username()
+		pass, _ = u.User.Password()
+	}
+	dbName = strings.Trim(u.Path, "/")
+	if dbName == "" {
+		dbName = "postgres"
+	}
+	sslMode = u.Query().Get("sslmode")
+	if sslMode == "" {
+		sslMode = "disable"
+	}
+	return
+}
+
+func postgresDSN(host string, port int, user, pass, dbName, sslMode string) string {
+	u := &url.URL{
+		Scheme: "postgres",
+		Host:   net.JoinHostPort(host, strconv.Itoa(port)),
+		Path:   dbName,
+	}
+	if user != "" {
+		u.User = url.UserPassword(user, pass)
+	}
+	q := url.Values{}
+	q.Set("sslmode", sslMode)
+	u.RawQuery = q.Encode()
+	return u.String()
+}
+
+var pgIdent = regexp.MustCompile(`^[a-z_][a-z0-9_]*$`)
+
+func safePGIdent(name string) bool {
+	return pgIdent.MatchString(name)
+}

backend/cmd/worker.go

@@ -0,0 +1,18 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"Wavelet/core"
+
+	"github.com/spf13/cobra"
+)
+
+var workerCmd = &cobra.Command{
+	Use:   "worker",
+	Short: "wavelet Worker",
+	Run: func(_ *cobra.Command, _ []string) {
+		runProfileApp(core.ProfileWorker, "worker", false)
+	},
+}

backend/core/app.go

@@ -0,0 +1,707 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package core
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/signal"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+)
+
+const (
+	defaultShutdownTimeout = 10 * time.Second
+)
+
+// AppOption configures an App instance during construction.
+type AppOption func(*App)
+
+// WithContext sets a custom root Context for the App.
+func WithContext(ctx *Context) AppOption {
+	return func(a *App) {
+		if ctx != nil {
+			a.ctx = ctx
+		}
+	}
+}
+
+// WithProfile sets the runtime profile for the App.
+func WithProfile(profile Profile) AppOption {
+	return func(a *App) {
+		a.profile = normalizeProfile(profile)
+	}
+}
+
+// WithPlugins registers initial plugins for the App.
+func WithPlugins(plugins ...Plugin) AppOption {
+	return func(a *App) {
+		a.Use(plugins...)
+	}
+}
+
+// WithMigrationEngine sets the database migration engine for the App.
+func WithMigrationEngine(engine MigrationEngine) AppOption {
+	return func(a *App) {
+		a.migrationEngine = engine
+	}
+}
+
+// WithMigrationRunner sets the migration runner function for the App.
+func WithMigrationRunner(runner MigrationRunner) AppOption {
+	return func(a *App) {
+		a.migrationEngine = runner
+	}
+}
+
+// WithMigrationBaseline registers a hook the migration engine runs after the
+// shared version table exists and before any plugin Up.
+func WithMigrationBaseline(fn func(*Context) error) AppOption {
+	return func(a *App) {
+		a.migrationBaseline = fn
+	}
+}
+
+// WithShutdownTimeout sets the fallback timeout for graceful application shutdown.
+func WithShutdownTimeout(timeout time.Duration) AppOption {
+	return func(a *App) {
+		if timeout > 0 {
+			a.shutdownTimeout = timeout
+		}
+	}
+}
+
+// WithConfigSource installs the raw configuration source adapter, typically built by an
+// infrastructure package outside the kernel, before any plugin is applied.
+func WithConfigSource(src ConfigSource) AppOption {
+	return func(a *App) {
+		if src == nil {
+			return
+		}
+		// Installed during Prepare so the option order, including WithContext, is irrelevant.
+		a.configSource = src
+	}
+}
+
+// WithConfigDecl lets the composition root declare the configuration it reads itself,
+// so host-level values take part in conflict validation and the redacted report. The
+// bindings are registered during Prepare, so option order does not matter.
+func WithConfigDecl(pluginID string, bindings ...ConfigBinding) AppOption {
+	return func(a *App) {
+		if len(bindings) == 0 {
+			return
+		}
+		if a.hostDeclOwner == "" {
+			a.hostDeclOwner = pluginID
+		}
+		a.hostDeclBindings = append(a.hostDeclBindings, bindings...)
+	}
+}
+
+// App is the unified assembly entrypoint and runtime aspect dispatcher of the Cordis micro-kernel.
+// It manages plugin collection, dependency mounting, migration execution, profile-based driver startup,
+// and graceful signal-driven LIFO shutdown.
+type App struct {
+	mu                sync.RWMutex
+	ctx               *Context
+	profile           Profile
+	plugins           []Plugin
+	pluginMap         map[string]Plugin
+	fibers            []*Fiber
+	fiberMap          map[string]*Fiber
+	applied           bool
+	running           bool
+	startedDrivers    []Driver
+	migrationEngine   MigrationEngine
+	migrationBaseline func(*Context) error
+	shutdownTimeout   time.Duration
+	configSource      ConfigSource
+	hostDeclOwner     string
+	hostDeclBindings  []ConfigBinding
+	prepared          bool
+	applyErr          error
+}
+
+// NewApp creates a new Cordis application instance with default options.
+func NewApp(opts ...AppOption) *App {
+	app := &App{
+		ctx:             NewContext(context.Background()),
+		profile:         ProfileAll,
+		pluginMap:       make(map[string]Plugin),
+		fiberMap:        make(map[string]*Fiber),
+		shutdownTimeout: defaultShutdownTimeout,
+	}
+
+	for _, opt := range opts {
+		if opt != nil {
+			opt(app)
+		}
+	}
+
+	return app
+}
+
+// Context returns the root micro-kernel Context of the application.
+func (a *App) Context() *Context {
+	return a.ctx
+}
+
+// Profile returns the current runtime profile of the application.
+func (a *App) Profile() Profile {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	return a.profile
+}
+
+// WithProfile sets the application runtime profile and returns the App for fluent chaining.
+func (a *App) WithProfile(profile Profile) *App {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	a.profile = normalizeProfile(profile)
+	return a
+}
+
+// SetProfile sets the application runtime profile.
+func (a *App) SetProfile(profile Profile) *App {
+	return a.WithProfile(profile)
+}
+
+// Use registers one or more plugins into the application in registration order.
+// Duplicate plugins (by Name) update existing registrations in-place to preserve order.
+func (a *App) Use(plugins ...Plugin) *App {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	for _, p := range plugins {
+		if p == nil {
+			continue
+		}
+		name := p.Name()
+		if name == "" {
+			continue
+		}
+
+		if _, exists := a.pluginMap[name]; exists {
+			for i, existing := range a.plugins {
+				if existing.Name() == name {
+					a.plugins[i] = p
+					break
+				}
+			}
+			if existingFiber, ok := a.fiberMap[name]; ok {
+				existingFiber.plugin = p
+			}
+		} else {
+			a.plugins = append(a.plugins, p)
+			f := NewFiber(a.ctx, p)
+			a.fibers = append(a.fibers, f)
+			a.fiberMap[name] = f
+		}
+		a.pluginMap[name] = p
+
+		if gated, ok := p.(ConfigGatedPlugin); ok && a.applyErr == nil {
+			// Gates are evaluated before Apply, so their keys must be declared at mount time.
+			a.applyErr = a.ctx.Config().Declare(name, gated.DeclareConfig()...)
+		}
+	}
+
+	return a
+}
+
+// Plugins returns a copy of all registered plugins in registration order.
+func (a *App) Plugins() []Plugin {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+
+	res := make([]Plugin, len(a.plugins))
+	copy(res, a.plugins)
+	return res
+}
+
+// Plugin retrieves a registered plugin by its unique name.
+func (a *App) Plugin(name string) (Plugin, bool) {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+
+	p, ok := a.pluginMap[name]
+	return p, ok
+}
+
+// Fibers returns a copy of all plugin Fibers.
+func (a *App) Fibers() []*Fiber {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+
+	res := make([]*Fiber, len(a.fibers))
+	copy(res, a.fibers)
+	return res
+}
+
+// Fiber retrieves a Fiber by its unique plugin name.
+func (a *App) Fiber(name string) (*Fiber, bool) {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+
+	f, ok := a.fiberMap[name]
+	return f, ok
+}
+
+// SetMigrationEngine sets the migration engine for the application.
+func (a *App) SetMigrationEngine(engine MigrationEngine) *App {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	a.migrationEngine = engine
+	return a
+}
+
+// SetMigrationRunner sets the migration runner function for the application.
+func (a *App) SetMigrationRunner(runner MigrationRunner) *App {
+	return a.SetMigrationEngine(runner)
+}
+
+// Reconcile evaluates all pending Fibers and reactively transitions them to ACTIVE
+// as their declared dependencies become satisfied.
+func (a *App) Reconcile() error {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	return a.reconcileLocked()
+}
+
+func (a *App) reconcileLocked() error {
+	if err := a.prepareLocked(); err != nil {
+		return err
+	}
+
+	for {
+		progress := false
+		for _, f := range a.fibers {
+			if f.State() != FiberPending {
+				continue
+			}
+
+			gated, skip, err := a.evaluateGateLocked(f)
+			if err != nil {
+				return err
+			}
+			if gated && skip {
+				if err := f.Skip(); err != nil {
+					return fmt.Errorf("core: skip gated fiber %q failed: %w", f.Name(), err)
+				}
+				continue
+			}
+
+			if f.DependenciesSatisfied(a.ctx) {
+				if err := f.Load(); err != nil {
+					return fmt.Errorf("core: load fiber %q failed: %w", f.Name(), err)
+				}
+				progress = true
+				// Rescan from the head of the Use() list so earlier pending
+				// plugins run before later ones that became ready in this pass.
+				break
+			}
+		}
+		if !progress {
+			break
+		}
+	}
+
+	var unsatisfied []string
+	for _, f := range a.fibers {
+		if f.State() == FiberPending {
+			unsatisfied = append(unsatisfied, fmt.Sprintf("%s (waiting for %v)", f.Name(), f.Dependencies()))
+		}
+	}
+	if len(unsatisfied) > 0 {
+		return fmt.Errorf("core: unsatisfied dependencies for plugins: %s", strings.Join(unsatisfied, ", "))
+	}
+
+	return nil
+}
+
+// evaluateGateLocked reports whether a configuration-gated plugin is excluded by the
+// resolved values. Plugins that do not implement the gate interface are never skipped.
+func (a *App) evaluateGateLocked(f *Fiber) (gated bool, skip bool, err error) {
+	gatedPlugin, ok := f.plugin.(ConfigGatedPlugin)
+	if !ok {
+		return false, false, nil
+	}
+
+	view := a.ctx.Config()
+	if !view.Resolved() {
+		return true, false, fmt.Errorf(
+			"core: plugin %q is configuration-gated but the App has no ConfigSource; "+
+				"pass core.WithConfigSource or remove DeclareConfig", f.Name())
+	}
+
+	return true, !gatedPlugin.ConfigEnabled(view), nil
+}
+
+// ApplyPlugins applies all registered plugins on the application Context via reactive reconciliation.
+// It is idempotent and only applies plugins once per App instance.
+func (a *App) ApplyPlugins() error {
+	a.mu.Lock()
+	if a.applied {
+		a.mu.Unlock()
+		return nil
+	}
+	a.applied = true
+
+	declaredErr, prepareErr := a.applyErr, a.prepareLocked()
+	a.mu.Unlock()
+
+	if declaredErr != nil {
+		return declaredErr
+	}
+	if prepareErr != nil {
+		return prepareErr
+	}
+
+	return a.Reconcile()
+}
+
+// Prepare resolves declared configuration and establishes the resolution barrier that
+// gates and plugin Bind calls depend on. It is idempotent and runs implicitly from
+// ApplyPlugins; callers that need resolved values earlier — for example to size a
+// shutdown budget — invoke it explicitly right after mounting plugins.
+func (a *App) Prepare() error {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	if a.applyErr != nil {
+		return a.applyErr
+	}
+	return a.prepareLocked()
+}
+
+// prepareLocked installs the injected source, registers host declarations and resolves
+// every declared key once. An App without a ConfigSource leaves configuration unused,
+// so kernel-level usage stays opt-in for embedders that configure nothing.
+func (a *App) prepareLocked() error {
+	if a.prepared {
+		return nil
+	}
+	if a.configSource != nil {
+		config := a.ctx.Config()
+		config.SetSource(a.configSource)
+
+		if err := config.Declare(a.hostDeclOwner, a.hostDeclBindings...); err != nil {
+			return err
+		}
+		if err := config.Resolve(); err != nil {
+			return err
+		}
+	}
+
+	a.ctx.setMigrationBaseline(a.migrationBaseline)
+	a.prepared = true
+	return nil
+}
+
+// ShutdownTimeout returns the graceful shutdown budget for the application.
+func (a *App) ShutdownTimeout() time.Duration {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	return a.shutdownTimeout
+}
+
+// SetShutdownTimeout replaces the graceful shutdown budget, ignoring non-positive
+// values so a missing configuration key can never shrink the kernel fallback to zero.
+func (a *App) SetShutdownTimeout(timeout time.Duration) *App {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	if timeout > 0 {
+		a.shutdownTimeout = timeout
+	}
+	return a
+}
+
+// RunMigrations dispatches migration execution across all registered plugin migration entries.
+func (a *App) RunMigrations() error {
+	entries := a.ctx.Migrations().Entries()
+	if len(entries) == 0 {
+		return nil
+	}
+
+	a.mu.RLock()
+	engine := a.migrationEngine
+	a.mu.RUnlock()
+
+	if engine == nil {
+		// Attempt to resolve from IoC container
+		if resolved, err := Inject[MigrationEngine](a.ctx); err == nil && resolved != nil {
+			engine = resolved
+		}
+	}
+
+	if engine == nil {
+		return nil
+	}
+
+	if err := engine.Migrate(a.ctx, entries); err != nil {
+		return fmt.Errorf("core: migration failed: %w", err)
+	}
+
+	return nil
+}
+
+// Start executes the application boot pipeline:
+// 1. Applies all registered plugins to populate services, routes, tasks, and drivers.
+// 2. Dispatches database migrations via MigrationEngine.
+// 3. Filters and starts drivers matching the active Profile.
+// 4. Emits "app:ready" on the EventBus.
+func (a *App) Start(ctx ...context.Context) error {
+	a.mu.Lock()
+	if a.running {
+		a.mu.Unlock()
+		return ErrAppRunning
+	}
+	a.running = true
+	a.mu.Unlock()
+
+	var baseCtx context.Context
+	switch {
+	case len(ctx) > 0 && ctx[0] != nil:
+		baseCtx = ctx[0]
+	case a.ctx != nil:
+		baseCtx = a.ctx.GoContext()
+	default:
+		baseCtx = context.Background()
+	}
+
+	// 1. Apply plugins
+	if err := a.ApplyPlugins(); err != nil {
+		a.mu.Lock()
+		a.running = false
+		a.mu.Unlock()
+		return err
+	}
+
+	// 2. Run migrations
+	if err := a.RunMigrations(); err != nil {
+		a.mu.Lock()
+		a.running = false
+		a.mu.Unlock()
+		return err
+	}
+
+	// 3. Filter drivers matching active profile
+	a.mu.RLock()
+	prof := a.profile
+	a.mu.RUnlock()
+
+	allDrivers := a.ctx.Drivers()
+	var driversToStart []Driver
+	for _, d := range allDrivers {
+		if matchesProfile(prof, d.Type()) {
+			driversToStart = append(driversToStart, d)
+		}
+	}
+
+	// 4. Start matching drivers
+	for _, d := range driversToStart {
+		if err := d.Start(baseCtx); err != nil {
+			// Rollback already started drivers in reverse order
+			a.mu.Lock()
+			started := a.startedDrivers
+			a.startedDrivers = nil
+			a.running = false
+			a.mu.Unlock()
+
+			for i := len(started) - 1; i >= 0; i-- {
+				_ = started[i].Stop(context.Background())
+			}
+
+			return fmt.Errorf("core: start driver %s failed: %w", d.Type(), err)
+		}
+
+		a.mu.Lock()
+		a.startedDrivers = append(a.startedDrivers, d)
+		a.mu.Unlock()
+	}
+
+	// 5. Emit app:ready event
+	_ = a.ctx.Events().Emit(baseCtx, "app:ready", a)
+
+	return nil
+}
+
+// Stop gracefully shuts down the application:
+// 1. Emits "app:stopping" on the EventBus.
+// 2. Stops all started drivers in LIFO (reverse) order.
+// 3. Disposes the Context (running registered OnDispose callbacks in LIFO order).
+// 4. Emits "app:stopped" on the EventBus.
+func (a *App) Stop(ctx ...context.Context) error {
+	a.mu.Lock()
+	if !a.running {
+		a.mu.Unlock()
+		return nil
+	}
+	a.running = false
+	started := a.startedDrivers
+	a.startedDrivers = nil
+	timeout := a.shutdownTimeout
+	a.mu.Unlock()
+
+	var shutdownCtx context.Context
+	if len(ctx) > 0 && ctx[0] != nil {
+		shutdownCtx = ctx[0]
+	} else {
+		var cancel context.CancelFunc
+		shutdownCtx, cancel = context.WithTimeout(context.Background(), timeout)
+		defer cancel()
+	}
+
+	_ = a.ctx.Events().Emit(shutdownCtx, "app:stopping", a)
+
+	var errs []error
+
+	// 1. Stop drivers in reverse order
+	for i := len(started) - 1; i >= 0; i-- {
+		d := started[i]
+		if err := d.Stop(shutdownCtx); err != nil {
+			errs = append(errs, fmt.Errorf("core: stop driver %s failed: %w", d.Type(), err))
+		}
+	}
+
+	// 2. Unload fibers in reverse order
+	a.mu.RLock()
+	fibers := make([]*Fiber, len(a.fibers))
+	copy(fibers, a.fibers)
+	a.mu.RUnlock()
+
+	for i := len(fibers) - 1; i >= 0; i-- {
+		if err := fibers[i].Unload(); err != nil {
+			errs = append(errs, fmt.Errorf("core: unload fiber %s failed: %w", fibers[i].Name(), err))
+		}
+	}
+
+	// 3. Dispose root context
+	if a.ctx != nil && !a.ctx.IsDisposed() {
+		if err := a.ctx.Dispose(); err != nil {
+			errs = append(errs, fmt.Errorf("core: dispose context failed: %w", err))
+		}
+	}
+
+	_ = a.ctx.Events().Emit(shutdownCtx, "app:stopped", a)
+
+	return errors.Join(errs...)
+}
+
+// Run starts the application and blocks until an OS signal (SIGINT, SIGTERM) or context cancellation is received,
+// then executes graceful shutdown. It forwards a sigCtx derived from the caller's context to Start.
+//
+//nolint:contextcheck // the caller's ctx does reach Start via sigCtx; the rule cannot follow Run's variadic context parameter
+func (a *App) Run(ctx ...context.Context) error {
+	var parent context.Context
+	switch {
+	case len(ctx) > 0 && ctx[0] != nil:
+		parent = ctx[0]
+	case a.ctx != nil:
+		parent = a.ctx.GoContext()
+	default:
+		parent = context.Background()
+	}
+
+	sigCtx, stopSignals := signal.NotifyContext(parent, syscall.SIGINT, syscall.SIGTERM, os.Interrupt)
+	defer stopSignals()
+
+	if err := a.Start(sigCtx); err != nil {
+		return err
+	}
+
+	// Wait for OS signal or context cancellation
+	<-sigCtx.Done()
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), a.shutdownTimeout)
+	defer cancel()
+
+	return a.Stop(shutdownCtx)
+}
+
+// IsRunning returns whether the application is currently running.
+func (a *App) IsRunning() bool {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	return a.running
+}
+
+// StartedDrivers returns a copy of currently running drivers.
+func (a *App) StartedDrivers() []Driver {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+
+	res := make([]Driver, len(a.startedDrivers))
+	copy(res, a.startedDrivers)
+	return res
+}
+
+// ExecuteCLI parses CLI arguments to configure the profile and runs the application.
+func (a *App) ExecuteCLI(args ...string) error {
+	var ctx context.Context
+	if a.ctx != nil {
+		ctx = a.ctx.GoContext()
+	} else {
+		ctx = context.Background()
+	}
+	return a.ExecuteCLIWithContext(ctx, args...)
+}
+
+// ExecuteCLIWithContext parses CLI arguments, configures the profile, and runs the application with the given context.
+func (a *App) ExecuteCLIWithContext(ctx context.Context, args ...string) error {
+	cliArgs := args
+	if len(cliArgs) == 0 {
+		cliArgs = os.Args[1:]
+	}
+
+	profile := ProfileAll
+	if len(cliArgs) > 0 {
+		first := strings.TrimSpace(cliArgs[0])
+		switch {
+		case strings.HasPrefix(first, "--profile="):
+			profile = Profile(strings.TrimPrefix(first, "--profile="))
+		case strings.HasPrefix(first, "-p="):
+			profile = Profile(strings.TrimPrefix(first, "-p="))
+		case !strings.HasPrefix(first, "-"):
+			profile = Profile(first)
+		}
+	}
+
+	a.WithProfile(profile)
+	return a.Run(ctx)
+}
+
+func matchesProfile(profile Profile, dt DriverType) bool {
+	norm := normalizeProfile(profile)
+	switch norm {
+	case ProfileAll, "":
+		return true
+	case ProfileAPI:
+		return dt == DriverTypeHTTP
+	case ProfileWorker:
+		return dt == DriverTypeWorker
+	case ProfileSchedule:
+		return dt == DriverTypeScheduler
+	default:
+		return string(norm) == string(dt)
+	}
+}
+
+func normalizeProfile(p Profile) Profile {
+	switch strings.ToLower(strings.TrimSpace(string(p))) {
+	case "api", "http":
+		return ProfileAPI
+	case "worker":
+		return ProfileWorker
+	case "schedule", "scheduler", "cron":
+		return ProfileSchedule
+	case "all", "fused", "full", "":
+		return ProfileAll
+	default:
+		return p
+	}
+}

backend/core/app_test.go

@@ -0,0 +1,654 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package core_test
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/extpoints"
+	"context"
+	"errors"
+	"sync"
+	"testing"
+	"testing/fstest"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// appMockDriver is a test driver tracking its start/stop lifecycle.
+type appMockDriver struct {
+	mu          sync.Mutex
+	driverType  core.DriverType
+	startCalled bool
+	stopCalled  bool
+	startErr    error
+	stopErr     error
+}
+
+func newAppMockDriver(dt core.DriverType) *appMockDriver {
+	return &appMockDriver{driverType: dt}
+}
+
+func (m *appMockDriver) Type() core.DriverType {
+	return m.driverType
+}
+
+func (m *appMockDriver) Start(_ context.Context) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.startErr != nil {
+		return m.startErr
+	}
+	m.startCalled = true
+	return nil
+}
+
+func (m *appMockDriver) Stop(_ context.Context) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.stopErr != nil {
+		return m.stopErr
+	}
+	m.stopCalled = true
+	return nil
+}
+
+func (m *appMockDriver) isStarted() bool {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.startCalled
+}
+
+func (m *appMockDriver) isStopped() bool {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.stopCalled
+}
+
+// appMockPlugin is a test plugin.
+type appMockPlugin struct {
+	name    string
+	applyFn func(ctx *core.Context) error
+}
+
+func (p *appMockPlugin) Name() string {
+	return p.name
+}
+
+func (p *appMockPlugin) Apply(ctx *core.Context) error {
+	if p.applyFn != nil {
+		return p.applyFn(ctx)
+	}
+	return nil
+}
+
+func TestAppNewAndConfiguration(t *testing.T) {
+	customCtx := core.NewContext(context.Background())
+	p1 := &appMockPlugin{name: "plugin1"}
+	p2 := &appMockPlugin{name: "plugin2"}
+
+	app := core.NewApp(
+		core.WithContext(customCtx),
+		core.WithProfile(core.ProfileAPI),
+		core.WithPlugins(p1, p2),
+		core.WithShutdownTimeout(5*time.Second),
+	)
+
+	assert.Equal(t, customCtx, app.Context())
+	assert.Equal(t, core.ProfileAPI, app.Profile())
+	assert.Len(t, app.Plugins(), 2)
+
+	retrieved, ok := app.Plugin("plugin1")
+	assert.True(t, ok)
+	assert.Equal(t, p1, retrieved)
+
+	_, ok = app.Plugin("non_existent")
+	assert.False(t, ok)
+
+	// Update existing plugin in-place
+	p1Updated := &appMockPlugin{name: "plugin1"}
+	app.Use(p1Updated, nil)
+	assert.Len(t, app.Plugins(), 2)
+	retrieved, ok = app.Plugin("plugin1")
+	assert.True(t, ok)
+	assert.Equal(t, p1Updated, retrieved)
+
+	// Test SetProfile
+	app.SetProfile(core.ProfileWorker)
+	assert.Equal(t, core.ProfileWorker, app.Profile())
+}
+
+func TestAppProfileDispatch(t *testing.T) {
+	tests := []struct {
+		name           string
+		profile        core.Profile
+		expectedHTTP   bool
+		expectedWorker bool
+		expectedCron   bool
+		expectedCustom bool
+	}{
+		{
+			name:           "ProfileAPI only starts HTTP driver",
+			profile:        core.ProfileAPI,
+			expectedHTTP:   true,
+			expectedWorker: false,
+			expectedCron:   false,
+			expectedCustom: false,
+		},
+		{
+			name:           "ProfileWorker only starts Worker driver",
+			profile:        core.ProfileWorker,
+			expectedHTTP:   false,
+			expectedWorker: true,
+			expectedCron:   false,
+			expectedCustom: false,
+		},
+		{
+			name:           "ProfileSchedule only starts Schedule driver",
+			profile:        core.ProfileSchedule,
+			expectedHTTP:   false,
+			expectedWorker: false,
+			expectedCron:   true,
+			expectedCustom: false,
+		},
+		{
+			name:           "Profile 'scheduler' alias starts Schedule driver",
+			profile:        core.Profile("scheduler"),
+			expectedHTTP:   false,
+			expectedWorker: false,
+			expectedCron:   true,
+			expectedCustom: false,
+		},
+		{
+			name:           "ProfileAll starts all drivers",
+			profile:        core.ProfileAll,
+			expectedHTTP:   true,
+			expectedWorker: true,
+			expectedCron:   true,
+			expectedCustom: true,
+		},
+		{
+			name:           "Custom profile starts custom driver",
+			profile:        core.Profile("custom_rpc"),
+			expectedHTTP:   false,
+			expectedWorker: false,
+			expectedCron:   false,
+			expectedCustom: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			httpD := newAppMockDriver(core.DriverTypeHTTP)
+			workerD := newAppMockDriver(core.DriverTypeWorker)
+			cronD := newAppMockDriver(core.DriverTypeScheduler)
+			customD := newAppMockDriver(core.DriverType("custom_rpc"))
+
+			p := &appMockPlugin{
+				name: "drivers_plugin",
+				applyFn: func(ctx *core.Context) error {
+					_ = ctx.RegisterDriver(httpD)
+					_ = ctx.RegisterDriver(workerD)
+					_ = ctx.RegisterDriver(cronD)
+					_ = ctx.RegisterDriver(customD)
+					return nil
+				},
+			}
+
+			app := core.NewApp(
+				core.WithProfile(tt.profile),
+				core.WithPlugins(p),
+			)
+
+			err := app.Start(context.Background())
+			require.NoError(t, err)
+
+			assert.Equal(t, tt.expectedHTTP, httpD.isStarted(), "HTTP driver start mismatch")
+			assert.Equal(t, tt.expectedWorker, workerD.isStarted(), "Worker driver start mismatch")
+			assert.Equal(t, tt.expectedCron, cronD.isStarted(), "Cron driver start mismatch")
+			assert.Equal(t, tt.expectedCustom, customD.isStarted(), "Custom driver start mismatch")
+
+			err = app.Stop(context.Background())
+			require.NoError(t, err)
+		})
+	}
+}
+
+func TestAppLifecycleStartStop(t *testing.T) {
+	var stopOrder []string
+	var stopOrderMu sync.Mutex
+
+	httpD := newAppMockDriver(core.DriverTypeHTTP)
+	workerD := newAppMockDriver(core.DriverTypeWorker)
+
+	httpD.stopErr = nil
+	workerD.stopErr = nil
+
+	// Wrap stop to record order
+	origHttpStop := httpD.Stop
+	_ = origHttpStop
+
+	p := &appMockPlugin{
+		name: "test_plugin",
+		applyFn: func(ctx *core.Context) error {
+			_ = ctx.RegisterDriver(httpD)
+			_ = ctx.RegisterDriver(workerD)
+
+			ctx.OnDispose(func() error {
+				stopOrderMu.Lock()
+				stopOrder = append(stopOrder, "ctx_disposer")
+				stopOrderMu.Unlock()
+				return nil
+			})
+			return nil
+		},
+	}
+
+	app := core.NewApp(
+		core.WithProfile(core.ProfileAll),
+		core.WithPlugins(p),
+	)
+
+	var readyReceived, stoppingReceived, stoppedReceived bool
+	app.Context().Events().On("app:ready", func() {
+		readyReceived = true
+	})
+	app.Context().Events().On("app:stopping", func() {
+		stoppingReceived = true
+	})
+	app.Context().Events().On("app:stopped", func() {
+		stoppedReceived = true
+	})
+
+	err := app.Start(context.Background())
+	require.NoError(t, err)
+	assert.True(t, app.IsRunning())
+	assert.Len(t, app.StartedDrivers(), 2)
+	assert.True(t, readyReceived)
+
+	err = app.Stop(context.Background())
+	require.NoError(t, err)
+	assert.False(t, app.IsRunning())
+	assert.Empty(t, app.StartedDrivers())
+	assert.True(t, stoppingReceived)
+	assert.True(t, stoppedReceived)
+
+	assert.True(t, httpD.isStopped())
+	assert.True(t, workerD.isStopped())
+	assert.True(t, app.Context().IsDisposed())
+
+	stopOrderMu.Lock()
+	assert.Contains(t, stopOrder, "ctx_disposer")
+	stopOrderMu.Unlock()
+}
+
+func TestAppStartDriverFailureRollback(t *testing.T) {
+	driver1 := newAppMockDriver(core.DriverTypeHTTP)
+	driver2 := newAppMockDriver(core.DriverTypeWorker)
+	driver2.startErr = errors.New("worker listen port conflict")
+	driver3 := newAppMockDriver(core.DriverTypeScheduler)
+
+	p := &appMockPlugin{
+		name: "fail_driver_plugin",
+		applyFn: func(ctx *core.Context) error {
+			_ = ctx.RegisterDriver(driver1)
+			_ = ctx.RegisterDriver(driver2)
+			_ = ctx.RegisterDriver(driver3)
+			return nil
+		},
+	}
+
+	app := core.NewApp(
+		core.WithProfile(core.ProfileAll),
+		core.WithPlugins(p),
+	)
+
+	err := app.Start(context.Background())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "worker listen port conflict")
+	assert.False(t, app.IsRunning())
+
+	// Driver 1 was started then rolled back (stopped)
+	assert.True(t, driver1.isStarted())
+	assert.True(t, driver1.isStopped())
+
+	// Driver 3 was never started
+	assert.False(t, driver3.isStarted())
+}
+
+func TestAppMigrationEngineExecution(t *testing.T) {
+	var migratedEntries []extpoints.MigrationEntry
+	runner := core.MigrationRunner(func(ctx *core.Context, entries []extpoints.MigrationEntry) error {
+		migratedEntries = entries
+		return nil
+	})
+
+	sqlFS := fstest.MapFS{
+		"migrations/001_init.sql": &fstest.MapFile{Data: []byte("CREATE TABLE users(id int);")},
+	}
+
+	p := &appMockPlugin{
+		name: "auth",
+		applyFn: func(ctx *core.Context) error {
+			ctx.Migrations().Register("auth", sqlFS)
+			return nil
+		},
+	}
+
+	app := core.NewApp(
+		core.WithProfile(core.ProfileAll),
+		core.WithPlugins(p),
+		core.WithMigrationRunner(runner),
+	)
+
+	err := app.Start(context.Background())
+	require.NoError(t, err)
+	defer func() { _ = app.Stop(context.Background()) }()
+
+	require.Len(t, migratedEntries, 1)
+	assert.Equal(t, "auth", migratedEntries[0].PluginID)
+}
+
+func TestAppMigrationEngineFromIoCContainer(t *testing.T) {
+	var executed bool
+	runner := core.MigrationRunner(func(ctx *core.Context, entries []extpoints.MigrationEntry) error {
+		executed = true
+		return nil
+	})
+
+	sqlFS := fstest.MapFS{
+		"migrations/001_init.sql": &fstest.MapFile{Data: []byte("CREATE TABLE logs(id int);")},
+	}
+
+	p := &appMockPlugin{
+		name: "logstore",
+		applyFn: func(ctx *core.Context) error {
+			ctx.Migrations().Register("logstore", sqlFS)
+			core.Provide[core.MigrationEngine](ctx, runner)
+			return nil
+		},
+	}
+
+	app := core.NewApp(
+		core.WithProfile(core.ProfileAll),
+		core.WithPlugins(p),
+	)
+
+	err := app.Start(context.Background())
+	require.NoError(t, err)
+	defer func() { _ = app.Stop(context.Background()) }()
+
+	assert.True(t, executed)
+}
+
+func TestAppRunContextCancellation(t *testing.T) {
+	d := newAppMockDriver(core.DriverTypeHTTP)
+	p := &appMockPlugin{
+		name: "http_plugin",
+		applyFn: func(ctx *core.Context) error {
+			return ctx.RegisterDriver(d)
+		},
+	}
+
+	app := core.NewApp(
+		core.WithProfile(core.ProfileAPI),
+		core.WithPlugins(p),
+		core.WithShutdownTimeout(1*time.Second),
+	)
+
+	ctx, cancel := context.WithCancel(context.Background())
+
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- app.Run(ctx)
+	}()
+
+	// Wait for app and driver to become ready
+	assert.Eventually(t, func() bool {
+		return app.IsRunning() && d.isStarted()
+	}, 2*time.Second, 10*time.Millisecond)
+
+	cancel()
+
+	select {
+	case err := <-errCh:
+		assert.NoError(t, err)
+		assert.False(t, app.IsRunning())
+		assert.True(t, d.isStopped())
+	case <-time.After(3 * time.Second):
+		t.Fatal("app.Run did not terminate upon context cancellation")
+	}
+}
+
+func TestAppExecuteCLI(t *testing.T) {
+	// Test CLI argument parsing logic
+	tests := []struct {
+		args            []string
+		expectedProfile core.Profile
+	}{
+		{args: []string{"api"}, expectedProfile: core.ProfileAPI},
+		{args: []string{"worker"}, expectedProfile: core.ProfileWorker},
+		{args: []string{"scheduler"}, expectedProfile: core.ProfileSchedule},
+		{args: []string{"schedule"}, expectedProfile: core.ProfileSchedule},
+		{args: []string{"all"}, expectedProfile: core.ProfileAll},
+		{args: []string{"--profile=worker"}, expectedProfile: core.ProfileWorker},
+		{args: []string{"-p=api"}, expectedProfile: core.ProfileAPI},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.args[0], func(t *testing.T) {
+			ctx, cancel := context.WithCancel(context.Background())
+			cancel() // cancel immediately
+
+			// Use custom root context to control cancellation
+			customApp := core.NewApp(core.WithContext(core.NewContext(ctx)))
+			_ = customApp.ExecuteCLI(tt.args...)
+			assert.Equal(t, tt.expectedProfile, customApp.Profile())
+		})
+	}
+}
+
+func TestAppIdempotencyAndErrorStates(t *testing.T) {
+	app := core.NewApp()
+
+	// Double start returns error
+	err := app.Start(context.Background())
+	require.NoError(t, err)
+
+	err = app.Start(context.Background())
+	assert.ErrorIs(t, err, core.ErrAppRunning)
+
+	// Stop clears running state
+	err = app.Stop(context.Background())
+	require.NoError(t, err)
+
+	// Double stop succeeds
+	err = app.Stop(context.Background())
+	require.NoError(t, err)
+
+	// Plugin apply failure
+	failPlugin := &appMockPlugin{
+		name: "failing_plugin",
+		applyFn: func(ctx *core.Context) error {
+			return errors.New("plugin init boom")
+		},
+	}
+	app2 := core.NewApp(core.WithPlugins(failPlugin))
+	err = app2.Start(context.Background())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "plugin init boom")
+	assert.False(t, app2.IsRunning())
+
+	// Migration failure
+	migFailRunner := core.MigrationRunner(func(ctx *core.Context, entries []extpoints.MigrationEntry) error {
+		return errors.New("sql migrate error")
+	})
+	sqlFS := fstest.MapFS{
+		"migrations/001.sql": &fstest.MapFile{Data: []byte("...")},
+	}
+	migPlugin := &appMockPlugin{
+		name: "db_plugin",
+		applyFn: func(ctx *core.Context) error {
+			ctx.Migrations().Register("db_plugin", sqlFS)
+			return nil
+		},
+	}
+	app3 := core.NewApp(
+		core.WithPlugins(migPlugin),
+		core.WithMigrationRunner(migFailRunner),
+	)
+	err = app3.Start(context.Background())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "sql migrate error")
+	assert.False(t, app3.IsRunning())
+}
+
+// newGateSource builds a configuration source whose only key decides the test gates.
+func newGateSource(enabled bool) *mapSource {
+	return &mapSource{
+		values: map[string]any{"gate.enabled": enabled},
+		env:    map[string]string{},
+	}
+}
+
+func TestAppPrepareResolvesThenGatesDuringReconcile(t *testing.T) {
+	primary := &gatedPlugin{name: "cache", enabled: true}
+	fallback := &gatedPlugin{name: "cache_memory", enabled: false}
+
+	app := core.NewApp(core.WithConfigSource(newGateSource(true)))
+	app.Use(primary, fallback)
+	require.NoError(t, app.Prepare())
+
+	cacheFiber, ok := app.Fiber("cache")
+	require.True(t, ok)
+	require.Equal(t, core.FiberPending, cacheFiber.State(), "Prepare only builds the resolution barrier")
+	assert.True(t, app.Context().Config().Resolved())
+
+	require.NoError(t, app.Reconcile())
+
+	assert.Equal(t, core.FiberActive, cacheFiber.State())
+
+	memoryFiber, ok := app.Fiber("cache_memory")
+	require.True(t, ok)
+	assert.Equal(t, core.FiberSkipped, memoryFiber.State())
+	assert.False(t, fallback.applied, "the gated-out provider must never reach Apply")
+}
+
+func TestAppGatesPluginsMountedAfterPrepare(t *testing.T) {
+	app := core.NewApp(core.WithConfigSource(newGateSource(true)))
+	require.NoError(t, app.Prepare())
+
+	late := &gatedPlugin{name: "cache_memory", enabled: false}
+	app.Use(late)
+	require.NoError(t, app.Reconcile())
+
+	fiber, ok := app.Fiber("cache_memory")
+	require.True(t, ok)
+	assert.Equal(t, core.FiberSkipped, fiber.State(),
+		"plugins mounted after Prepare must still be gated")
+}
+
+func TestAppApplyPluginsGatesImplicitly(t *testing.T) {
+	app := core.NewApp(core.WithConfigSource(newGateSource(false)))
+	app.Use(&gatedPlugin{name: "cache", enabled: true})
+
+	require.NoError(t, app.ApplyPlugins())
+
+	fiber, ok := app.Fiber("cache")
+	require.True(t, ok)
+	assert.Equal(t, core.FiberSkipped, fiber.State(),
+		"ApplyPlugins must resolve and gate without an explicit Prepare call")
+}
+
+func TestAppPrepareReportsConfigurationErrors(t *testing.T) {
+	src := &mapSource{
+		values: map[string]any{"gate.enabled": "yes"},
+		env:    map[string]string{},
+	}
+	app := core.NewApp(core.WithConfigSource(src))
+	app.Use(&gatedPlugin{name: "cache", enabled: true})
+
+	err := app.Prepare()
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "gate.enabled")
+}
+
+func TestAppGatedPluginWithoutConfigSourceFailsFast(t *testing.T) {
+	app := core.NewApp()
+	app.Use(&gatedPlugin{name: "cache", enabled: true})
+
+	err := app.ApplyPlugins()
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "cache")
+	assert.Contains(t, err.Error(), "ConfigSource")
+}
+
+func TestAppSetShutdownTimeoutIgnoresNonPositive(t *testing.T) {
+	app := core.NewApp()
+
+	app.SetShutdownTimeout(0)
+	assert.Equal(t, 10*time.Second, app.ShutdownTimeout(), "zero must not shrink the kernel fallback")
+
+	app.SetShutdownTimeout(45 * time.Second)
+	assert.Equal(t, 45*time.Second, app.ShutdownTimeout())
+}
+
+func TestWithMigrationBaselineVisibleAfterPrepare(t *testing.T) {
+	var called bool
+	fn := func(*core.Context) error {
+		called = true
+		return nil
+	}
+
+	app := core.NewApp(core.WithMigrationBaseline(fn))
+	require.Nil(t, app.Context().MigrationBaseline(), "baseline must be copied during Prepare")
+
+	require.NoError(t, app.Prepare())
+
+	got := app.Context().MigrationBaseline()
+	require.NotNil(t, got, "Prepare must copy the baseline onto the root Context")
+	require.NoError(t, got(app.Context()))
+	assert.True(t, called)
+}
+
+func TestWithMigrationBaselineRunsBeforeEngineMigrate(t *testing.T) {
+	var order []string
+	engine := core.MigrationRunner(func(ctx *core.Context, _ []extpoints.MigrationEntry) error {
+		order = append(order, "engine")
+		if ctx.MigrationBaseline() == nil {
+			t.Fatal("baseline must be visible on context inside Migrate")
+		}
+		return ctx.MigrationBaseline()(ctx)
+	})
+
+	sqlFS := fstest.MapFS{
+		"migrations/001_init.sql": &fstest.MapFile{Data: []byte("-- +goose Up\nSELECT 1;\n")},
+	}
+	app := core.NewApp(
+		core.WithMigrationEngine(engine),
+		core.WithMigrationBaseline(func(*core.Context) error {
+			order = append(order, "baseline")
+			return nil
+		}),
+		core.WithPlugins(&appMockPlugin{
+			name: "t",
+			applyFn: func(ctx *core.Context) error {
+				ctx.Migrations().Register("t", sqlFS)
+				return nil
+			},
+		}),
+	)
+
+	require.NoError(t, app.Start(context.Background()))
+	defer func() { _ = app.Stop(context.Background()) }()
+
+	assert.Equal(t, []string{"engine", "baseline"}, order)
+}
+
+func TestWithMigrationBaselineNilByDefault(t *testing.T) {
+	app := core.NewApp()
+	require.NoError(t, app.Prepare())
+	assert.Nil(t, app.Context().MigrationBaseline())
+}

backend/core/appctx.go

@@ -0,0 +1,43 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package core
+
+import "context"
+
+type appContextKey struct{}
+
+// WithAppContext attaches the micro-kernel Context to a standard context.Context
+// so request and worker handlers can Inject services without package-level setters.
+func WithAppContext(ctx context.Context, app *Context) context.Context {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if app == nil {
+		return ctx
+	}
+	return context.WithValue(ctx, appContextKey{}, app.Root())
+}
+
+// AppContext extracts the micro-kernel Context from ctx, if present.
+func AppContext(ctx context.Context) *Context {
+	if ctx == nil {
+		return nil
+	}
+	if c, ok := ctx.(*Context); ok {
+		return c
+	}
+	app, _ := ctx.Value(appContextKey{}).(*Context)
+	return app
+}
+
+// InjectFrom resolves T from ctx when it carries a micro-kernel Context
+// (*Context itself, or a value attached by WithAppContext).
+func InjectFrom[T any](ctx context.Context) (T, error) {
+	var zero T
+	app := AppContext(ctx)
+	if app == nil {
+		return zero, ErrNilContext
+	}
+	return Inject[T](app)
+}

backend/core/config.go

@@ -0,0 +1,100 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package core
+
+import (
+	"fmt"
+	"strings"
+
+	"Wavelet/core/extpoints"
+)
+
+// ConfigGet reads one resolved configuration value with its declared type. It is the
+// generic counterpart of the fallback accessors on ConfigView, used when a caller must
+// distinguish "unset" from "set to the zero value".
+func ConfigGet[T any](view extpoints.ConfigView, key string) (T, error) {
+	var zero T
+	if view == nil {
+		return zero, extpoints.ErrConfigNotResolved
+	}
+
+	raw, ok := view.Value(key)
+	if !ok {
+		return zero, fmt.Errorf("%w: %s", extpoints.ErrConfigUnknownKey, key)
+	}
+
+	value, ok := raw.(T)
+	if !ok {
+		return zero, fmt.Errorf("%w: key %q holds %T, want %T", extpoints.ErrConfigType, key, raw, zero)
+	}
+	return value, nil
+}
+
+// MapSource implements ConfigSource backed by an in-memory map, ideal for unit tests.
+type MapSource struct {
+	values map[string]any
+	env    map[string]string
+}
+
+// NewMapSource creates a new MapSource with the provided key-value mappings.
+func NewMapSource(values map[string]any) *MapSource {
+	vals := make(map[string]any, len(values))
+	for k, v := range values {
+		vals[k] = v
+	}
+	return &MapSource{
+		values: vals,
+		env:    make(map[string]string),
+	}
+}
+
+// Lookup returns the value at the given path, supporting both flat keys and nested maps.
+func (m *MapSource) Lookup(path string) (any, bool) {
+	if m == nil || m.values == nil {
+		return nil, false
+	}
+	if v, ok := m.values[path]; ok {
+		return v, true
+	}
+	parts := strings.Split(path, ".")
+	var cur any = m.values
+	for _, part := range parts {
+		mCur, ok := cur.(map[string]any)
+		if !ok {
+			return nil, false
+		}
+		cur, ok = mCur[part]
+		if !ok {
+			return nil, false
+		}
+	}
+	return cur, true
+}
+
+// LookupEnv returns the environment variable value.
+func (m *MapSource) LookupEnv(name string) (string, bool) {
+	if m == nil || m.env == nil {
+		return "", false
+	}
+	v, ok := m.env[name]
+	return v, ok
+}
+
+// SetEnv sets an environment variable for testing.
+func (m *MapSource) SetEnv(name, value string) {
+	if m.env == nil {
+		m.env = make(map[string]string)
+	}
+	m.env[name] = value
+}
+
+// Describe describes the MapSource.
+func (m *MapSource) Describe() string {
+	return "<map source>"
+}
+
+// WithConfigValues returns an AppOption that installs a MapSource with the given key-value mappings.
+func WithConfigValues(values map[string]any) AppOption {
+	return WithConfigSource(NewMapSource(values))
+}

backend/core/config_test.go

@@ -0,0 +1,92 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package core_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"Wavelet/core"
+	"Wavelet/core/extpoints"
+)
+
+// mapSource implements extpoints.ConfigSource over static maps.
+type mapSource struct {
+	values map[string]any
+	env    map[string]string
+}
+
+func (m *mapSource) Lookup(path string) (any, bool) {
+	v, ok := m.values[path]
+	return v, ok
+}
+
+func (m *mapSource) LookupEnv(name string) (string, bool) {
+	v, ok := m.env[name]
+	return v, ok
+}
+
+func (m *mapSource) Describe() string { return "map" }
+
+type otelConfig struct {
+	SamplingRate float64 `config:"sampling_rate" env:"OTEL_SAMPLING_RATE"`
+}
+
+// newOtelRegistry declares the otel section against a source carrying the given file values.
+func newOtelRegistry(t *testing.T, values map[string]any) extpoints.ConfigExtension {
+	t.Helper()
+
+	r := extpoints.NewConfigRegistry(&mapSource{values: values, env: map[string]string{}})
+	require.NoError(t, r.Declare("host", extpoints.ConfigBinding{Prefix: "otel", Target: &otelConfig{}}))
+	require.NoError(t, r.Resolve())
+	return r
+}
+
+func TestConfigGetReturnsDeclaredType(t *testing.T) {
+	view := newOtelRegistry(t, map[string]any{"otel.sampling_rate": 0.25})
+
+	rate, err := core.ConfigGet[float64](view, "otel.sampling_rate")
+	require.NoError(t, err)
+	assert.Equal(t, 0.25, rate)
+}
+
+func TestConfigGetRejectsTypeMismatch(t *testing.T) {
+	view := newOtelRegistry(t, map[string]any{"otel.sampling_rate": 0.25})
+
+	text, err := core.ConfigGet[string](view, "otel.sampling_rate")
+	require.ErrorIs(t, err, extpoints.ErrConfigType)
+	assert.Empty(t, text)
+}
+
+func TestConfigGetRejectsUndeclaredKey(t *testing.T) {
+	view := newOtelRegistry(t, nil)
+
+	_, err := core.ConfigGet[float64](view, "otel.unregistered")
+	require.ErrorIs(t, err, extpoints.ErrConfigUnknownKey)
+}
+
+func TestConfigGetRejectsNilView(t *testing.T) {
+	_, err := core.ConfigGet[float64](nil, "otel.sampling_rate")
+	require.ErrorIs(t, err, extpoints.ErrConfigNotResolved)
+}
+
+func TestContextConfigIsSharedAcrossForks(t *testing.T) {
+	ctx := core.NewContext(nil)
+	child := ctx.Fork()
+
+	require.NotNil(t, ctx.Config())
+	assert.Same(t, ctx.Config(), child.Config(), "configuration declarations are process-wide facts")
+
+	require.NoError(t, child.Config().Declare("cache",
+		extpoints.ConfigBinding{Prefix: "otel", Target: &otelConfig{}}))
+
+	declared := false
+	for _, entry := range ctx.Config().Entries() {
+		declared = declared || entry.Key == "otel.sampling_rate"
+	}
+	assert.True(t, declared, "a declaration made in a plugin scope must be visible to the root")
+	assert.False(t, ctx.Config().Resolved())
+}

backend/core/container.go

@@ -0,0 +1,265 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package core provides the micro-kernel service bus, generic IoC container, and runtime extensions.
+package core
+
+import (
+	"errors"
+	"fmt"
+	"reflect"
+	"sync"
+)
+
+// Container manages service registration and resolution using Go reflection and generics.
+type Container struct {
+	mu             sync.RWMutex
+	parent         *Container
+	services       map[reflect.Type]any
+	interfaceCache map[reflect.Type]any
+	listeners      map[reflect.Type][]func(any)
+}
+
+// NewContainer creates a new IoC container instance with an optional parent container.
+func NewContainer(parent *Container) *Container {
+	return &Container{
+		parent:         parent,
+		services:       make(map[reflect.Type]any),
+		interfaceCache: make(map[reflect.Type]any),
+		listeners:      make(map[reflect.Type][]func(any)),
+	}
+}
+
+func isNil(i any) bool {
+	if i == nil {
+		return true
+	}
+	v := reflect.ValueOf(i)
+	switch v.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Map, reflect.Pointer, reflect.UnsafePointer, reflect.Interface, reflect.Slice:
+		return v.IsNil()
+	default:
+		return false
+	}
+}
+
+func (c *Container) remove(targetType reflect.Type) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	delete(c.services, targetType)
+	c.interfaceCache = make(map[reflect.Type]any)
+}
+
+// Provide registers a typed service implementation into the Context hierarchy's root IoC container.
+func Provide[T any](ctx *Context, service T) {
+	if ctx == nil {
+		panic("core: nil context provided to Provide")
+	}
+	if isNil(service) {
+		panic("core: cannot provide nil service")
+	}
+
+	targetType := reflect.TypeFor[T]()
+	targetContainer := ctx.Root().Container()
+	targetContainer.provide(targetType, service)
+
+	ctx.OnDispose(func() error {
+		targetContainer.remove(targetType)
+		return nil
+	})
+}
+
+// ProvideScoped registers a typed service implementation strictly in the local Context container.
+func ProvideScoped[T any](ctx *Context, service T) {
+	if ctx == nil {
+		panic("core: nil context provided to ProvideScoped")
+	}
+	if isNil(service) {
+		panic("core: cannot provide nil service")
+	}
+
+	targetType := reflect.TypeFor[T]()
+	targetContainer := ctx.Container()
+	targetContainer.provide(targetType, service)
+
+	ctx.OnDispose(func() error {
+		targetContainer.remove(targetType)
+		return nil
+	})
+}
+
+func (c *Container) provide(targetType reflect.Type, service any) {
+	c.mu.Lock()
+	c.services[targetType] = service
+	c.interfaceCache = make(map[reflect.Type]any)
+
+	// Collect any matching listeners to invoke outside the lock
+	var callbacks []func(any)
+	svcType := reflect.TypeOf(service)
+	for lType, cbs := range c.listeners {
+		if lType == targetType || (lType.Kind() == reflect.Interface && svcType.Implements(lType)) {
+			callbacks = append(callbacks, cbs...)
+		}
+	}
+	c.mu.Unlock()
+
+	for _, cb := range callbacks {
+		cb(service)
+	}
+}
+
+// Inject resolves a registered service of type T from the Context.
+func Inject[T any](ctx *Context) (T, error) {
+	var zero T
+	if ctx == nil {
+		return zero, ErrNilContext
+	}
+
+	targetType := reflect.TypeFor[T]()
+	val, err := ctx.Container().resolve(targetType)
+	if err != nil {
+		return zero, err
+	}
+
+	typedVal, ok := val.(T)
+	if !ok {
+		return zero, fmt.Errorf("%w: cannot cast %T to %v", ErrServiceNotFound, val, targetType)
+	}
+	return typedVal, nil
+}
+
+func (c *Container) resolve(targetType reflect.Type) (any, error) {
+	c.mu.RLock()
+	// 1. Direct type match
+	if val, ok := c.services[targetType]; ok {
+		c.mu.RUnlock()
+		return val, nil
+	}
+	c.mu.RUnlock()
+
+	// 2. Interface assignment scan & cache
+	if targetType.Kind() == reflect.Interface {
+		if val, found := c.resolveInterface(targetType); found {
+			return val, nil
+		}
+	}
+
+	// 3. Fallback to parent container
+	if c.parent != nil {
+		return c.parent.resolve(targetType)
+	}
+
+	return nil, fmt.Errorf("%w: %v", ErrServiceNotFound, targetType)
+}
+
+func (c *Container) resolveInterface(targetType reflect.Type) (any, bool) {
+	c.mu.RLock()
+	if val, ok := c.interfaceCache[targetType]; ok {
+		c.mu.RUnlock()
+		return val, true
+	}
+
+	var matched any
+	for _, val := range c.services {
+		if reflect.TypeOf(val).Implements(targetType) {
+			matched = val
+			break
+		}
+	}
+	c.mu.RUnlock()
+
+	if matched == nil {
+		return nil, false
+	}
+
+	c.mu.Lock()
+	if c.interfaceCache == nil {
+		c.interfaceCache = make(map[reflect.Type]any)
+	}
+	c.interfaceCache[targetType] = matched
+	c.mu.Unlock()
+	return matched, true
+}
+
+// MustInject resolves a service of type T or panics if the service is not found.
+func MustInject[T any](ctx *Context) T {
+	s, err := Inject[T](ctx)
+	if err != nil {
+		panic(fmt.Sprintf("core: failed to inject service %v: %v", reflect.TypeFor[T](), err))
+	}
+	return s
+}
+
+// Has returns true if a service of type T is registered and resolvable in the Context.
+func Has[T any](ctx *Context) bool {
+	_, err := Inject[T](ctx)
+	return err == nil
+}
+
+// Using executes the given function synchronously if the required dependency is ready.
+func Using[T1 any](ctx *Context, fn func(s1 T1)) error {
+	s1, err := Inject[T1](ctx)
+	if err != nil {
+		return fmt.Errorf("%w: %w", ErrServiceNotReady, err)
+	}
+	fn(s1)
+	return nil
+}
+
+// Using2 executes the given function synchronously if both required dependencies are ready.
+func Using2[T1, T2 any](ctx *Context, fn func(s1 T1, s2 T2)) error {
+	s1, err1 := Inject[T1](ctx)
+	s2, err2 := Inject[T2](ctx)
+	if err := errors.Join(err1, err2); err != nil {
+		return fmt.Errorf("%w: %w", ErrServiceNotReady, err)
+	}
+	fn(s1, s2)
+	return nil
+}
+
+// Using3 executes the given function synchronously if all 3 required dependencies are ready.
+func Using3[T1, T2, T3 any](ctx *Context, fn func(s1 T1, s2 T2, s3 T3)) error {
+	s1, err1 := Inject[T1](ctx)
+	s2, err2 := Inject[T2](ctx)
+	s3, err3 := Inject[T3](ctx)
+	if err := errors.Join(err1, err2, err3); err != nil {
+		return fmt.Errorf("%w: %w", ErrServiceNotReady, err)
+	}
+	fn(s1, s2, s3)
+	return nil
+}
+
+// When registers a reactive hook that is called immediately if T is already provided,
+// or called as soon as T is provided in the future.
+//
+// Listeners are stored on the root container so they observe core.Provide, which
+// always writes to the root. Registering on a Fiber child container would miss
+// services provided by plugins that load later.
+func When[T any](ctx *Context, fn func(s T)) {
+	if ctx == nil {
+		panic("core: nil context provided to When")
+	}
+
+	targetType := reflect.TypeFor[T]()
+	c := ctx.Root().Container()
+
+	// If already ready, execute immediately
+	if s, err := Inject[T](ctx); err == nil {
+		fn(s)
+	}
+
+	// Also register listener for future calls / updates
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.listeners[targetType] = append(c.listeners[targetType], func(val any) {
+		if typed, ok := val.(T); ok {
+			fn(typed)
+		}
+	})
+}
+
+// Bind is When with a name that matches plugin wiring: fill a dependency as
+// soon as the root container provides it.
+func Bind[T any](ctx *Context, fn func(s T)) {
+	When(ctx, fn)
+}

backend/core/context.go

@@ -0,0 +1,416 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package core
+
+import (
+	"Wavelet/core/extpoints"
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+)
+
+// Context is the central micro-kernel service bus and runtime lifecycle container.
+// It embeds Go standard context.Context compatibility, hierarchical scoping,
+// service resolution, and LIFO disposer teardown.
+type Context struct {
+	goCtx     context.Context
+	cancel    context.CancelFunc
+	parent    *Context
+	container *Container
+
+	events     *EventBus
+	router     extpoints.RouterExtension
+	migrations extpoints.MigrationExtension
+	tasks      extpoints.TaskExtension
+	schedules  extpoints.ScheduleExtension
+	settings   extpoints.SettingExtension
+	config     extpoints.ConfigExtension
+
+	mu                sync.RWMutex
+	children          []*Context
+	disposers         []Disposer
+	drivers           []Driver
+	values            map[any]any
+	disposed          bool
+	migrationBaseline func(*Context) error
+}
+
+// NewContext creates a new root Context wrapping a standard Go context.
+// If base is nil, context.Background() is used by default.
+//
+//nolint:contextcheck
+func NewContext(base context.Context) *Context {
+	if base == nil {
+		base = context.Background()
+	}
+	ctx, cancel := context.WithCancel(base)
+
+	return &Context{
+		goCtx:      ctx,
+		cancel:     cancel,
+		container:  NewContainer(nil),
+		events:     NewEventBus(),
+		router:     extpoints.NewRouterRegistry(),
+		migrations: extpoints.NewMigrationRegistry(),
+		tasks:      extpoints.NewTaskRegistry(),
+		schedules:  extpoints.NewScheduleRegistry(),
+		settings:   extpoints.NewSettingRegistry(),
+		config:     extpoints.NewConfigRegistry(nil),
+		values:     make(map[any]any),
+	}
+}
+
+// Deadline returns the time when work done on behalf of this context should be canceled.
+func (c *Context) Deadline() (deadline time.Time, ok bool) {
+	return c.goCtx.Deadline()
+}
+
+// Done returns a channel that's closed when work done on behalf of this context should be canceled.
+func (c *Context) Done() <-chan struct{} {
+	return c.goCtx.Done()
+}
+
+// Err returns a non-nil error value after Done is closed.
+func (c *Context) Err() error {
+	return c.goCtx.Err()
+}
+
+// Value returns the value associated with key, searching the local values map,
+// the underlying Go context, and fallback parent Contexts.
+func (c *Context) Value(key any) any {
+	c.mu.RLock()
+	if v, ok := c.values[key]; ok {
+		c.mu.RUnlock()
+		return v
+	}
+	c.mu.RUnlock()
+
+	if v := c.goCtx.Value(key); v != nil {
+		return v
+	}
+
+	if c.parent != nil {
+		return c.parent.Value(key)
+	}
+
+	return nil
+}
+
+// GoContext returns the underlying standard Go context.Context.
+func (c *Context) GoContext() context.Context {
+	return c.goCtx
+}
+
+// Set stores an arbitrary key-value pair in this Context's local storage.
+func (c *Context) Set(key, val any) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.values == nil {
+		c.values = make(map[any]any)
+	}
+	c.values[key] = val
+}
+
+// Get retrieves a key-value pair from this Context's local storage.
+func (c *Context) Get(key any) (any, bool) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	if c.values == nil {
+		return nil, false
+	}
+	v, ok := c.values[key]
+	return v, ok
+}
+
+// Container returns the underlying IoC container for this Context.
+func (c *Context) Container() *Container {
+	return c.container
+}
+
+// Parent returns the parent Context, or nil if this is a root Context.
+func (c *Context) Parent() *Context {
+	return c.parent
+}
+
+// Root returns the root Context in the hierarchy.
+func (c *Context) Root() *Context {
+	curr := c
+	for curr.parent != nil {
+		curr = curr.parent
+	}
+	return curr
+}
+
+// Fork creates a child Context with its own scoped IoC container and values,
+// linked to this Context for hierarchical fallback resolution and cascading teardown.
+func (c *Context) Fork() *Context {
+	return c.ForkWithContext(c.goCtx)
+}
+
+// ForkWithContext creates a child Context using a specific standard Go context.
+//
+//nolint:contextcheck
+func (c *Context) ForkWithContext(base context.Context) *Context {
+	if base == nil {
+		base = c.goCtx
+	}
+	ctx, cancel := context.WithCancel(base)
+
+	child := &Context{
+		goCtx:             ctx,
+		cancel:            cancel,
+		parent:            c,
+		container:         NewContainer(c.container),
+		events:            c.events,
+		router:            c.router,
+		migrations:        c.migrations,
+		tasks:             c.tasks,
+		schedules:         c.schedules,
+		settings:          c.settings,
+		config:            c.config,
+		values:            make(map[any]any),
+		migrationBaseline: c.MigrationBaseline(),
+	}
+
+	c.mu.Lock()
+	c.children = append(c.children, child)
+	c.mu.Unlock()
+
+	return child
+}
+
+// Events returns the domain EventBus associated with this Context hierarchy.
+func (c *Context) Events() *EventBus {
+	return c.events
+}
+
+// On registers an event listener on the EventBus and automatically attaches its Disposer
+// to this Context's teardown stack for automatic revocation when disposed.
+func (c *Context) On(topic string, handler any) Disposer {
+	disposer := c.events.On(topic, handler)
+	c.OnDispose(disposer)
+	return disposer
+}
+
+// Effect registers a reversible side-effect cleanup callback on this Context.
+func (c *Context) Effect(fn any) {
+	c.OnDispose(fn)
+}
+
+// Router returns the scoped RouterExtension registry with automatic disposer tracking.
+func (c *Context) Router() extpoints.RouterExtension {
+	return newScopedRouterExtension(c, c.router)
+}
+
+// Migrations returns the MigrationExtension registry.
+func (c *Context) Migrations() extpoints.MigrationExtension {
+	return c.migrations
+}
+
+// MigrationBaseline returns the hook copied onto this Context during App.Prepare.
+// Child contexts fall back to their parent so forks still see the root hook.
+func (c *Context) MigrationBaseline() func(*Context) error {
+	if c == nil {
+		return nil
+	}
+	c.mu.RLock()
+	fn := c.migrationBaseline
+	c.mu.RUnlock()
+	if fn != nil {
+		return fn
+	}
+	if c.parent != nil {
+		return c.parent.MigrationBaseline()
+	}
+	return nil
+}
+
+func (c *Context) setMigrationBaseline(fn func(*Context) error) {
+	if c == nil {
+		return
+	}
+	c.mu.Lock()
+	c.migrationBaseline = fn
+	c.mu.Unlock()
+}
+
+// Tasks returns the scoped TaskExtension registry with automatic disposer tracking.
+func (c *Context) Tasks() extpoints.TaskExtension {
+	return newScopedTaskExtension(c, c.tasks)
+}
+
+// Task is an alias for Tasks().
+func (c *Context) Task() extpoints.TaskExtension {
+	return c.Tasks()
+}
+
+// Schedules returns the scoped ScheduleExtension registry with automatic disposer tracking.
+func (c *Context) Schedules() extpoints.ScheduleExtension {
+	return newScopedScheduleExtension(c, c.schedules)
+}
+
+// Schedule is an alias for Schedules().
+func (c *Context) Schedule() extpoints.ScheduleExtension {
+	return c.Schedules()
+}
+
+// Settings returns the scoped SettingExtension registry with automatic disposer tracking.
+func (c *Context) Settings() extpoints.SettingExtension {
+	return newScopedSettingExtension(c, c.settings)
+}
+
+// Setting is an alias for Settings().
+func (c *Context) Setting() extpoints.SettingExtension {
+	return c.Settings()
+}
+
+// Config returns the process-level configuration extension point. The registry is
+// shared by every fork because configuration declarations are global facts, and it
+// carries no per-scope disposers: values are resolved once before Apply runs.
+func (c *Context) Config() extpoints.ConfigExtension {
+	return c.config
+}
+
+// OnDispose registers a cleanup callback function to be executed when this Context is disposed.
+// It accepts func() error, func(), or Disposer.
+func (c *Context) OnDispose(fn any) {
+	if fn == nil {
+		return
+	}
+
+	var d Disposer
+	switch f := fn.(type) {
+	case Disposer:
+		d = f
+	case func() error:
+		d = f
+	case func():
+		d = func() error {
+			f()
+			return nil
+		}
+	default:
+		panic(fmt.Sprintf("core: OnDispose expects func() error or func(), got %T", fn))
+	}
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.disposers = append(c.disposers, d)
+}
+
+// Dispose shuts down this Context and all child Contexts, running registered disposers in LIFO order.
+func (c *Context) Dispose() error {
+	c.mu.Lock()
+	if c.disposed {
+		c.mu.Unlock()
+		return nil
+	}
+	c.disposed = true
+
+	// Copy children and disposers under lock
+	children := make([]*Context, len(c.children))
+	copy(children, c.children)
+
+	disposers := make([]Disposer, len(c.disposers))
+	copy(disposers, c.disposers)
+	c.mu.Unlock()
+
+	var errs []error
+
+	// 1. Dispose all child contexts in reverse order
+	for i := len(children) - 1; i >= 0; i-- {
+		if err := children[i].Dispose(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	// 2. Run local disposers in LIFO order
+	for i := len(disposers) - 1; i >= 0; i-- {
+		if err := disposers[i](); err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	// 3. Cancel the Go context
+	if c.cancel != nil {
+		c.cancel()
+	}
+
+	// 4. Detach from parent
+	if c.parent != nil {
+		c.parent.removeChild(c)
+	}
+
+	return errors.Join(errs...)
+}
+
+func (c *Context) removeChild(target *Context) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	for i, child := range c.children {
+		if child == target {
+			c.children = append(c.children[:i], c.children[i+1:]...)
+			break
+		}
+	}
+}
+
+// IsDisposed returns true if this Context has been disposed.
+func (c *Context) IsDisposed() bool {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return c.disposed
+}
+
+// RegisterDriver registers a runtime driver engine on this Context hierarchy.
+func (c *Context) RegisterDriver(d Driver) error {
+	if d == nil {
+		return ErrNilService
+	}
+
+	root := c.Root()
+	root.mu.Lock()
+	root.drivers = append(root.drivers, d)
+	root.mu.Unlock()
+
+	c.OnDispose(func() error {
+		root.mu.Lock()
+		defer root.mu.Unlock()
+		for i, drv := range root.drivers {
+			if drv == d {
+				root.drivers = append(root.drivers[:i], root.drivers[i+1:]...)
+				break
+			}
+		}
+		return nil
+	})
+	return nil
+}
+
+// Drivers returns a copy of all drivers registered on this Context.
+func (c *Context) Drivers() []Driver {
+	root := c.Root()
+	root.mu.RLock()
+	defer root.mu.RUnlock()
+
+	result := make([]Driver, len(root.drivers))
+	copy(result, root.drivers)
+	return result
+}
+
+// Driver looks up a registered driver by its driver type.
+func (c *Context) Driver(driverType DriverType) (Driver, bool) {
+	root := c.Root()
+	root.mu.RLock()
+	defer root.mu.RUnlock()
+
+	for _, d := range root.drivers {
+		if d.Type() == driverType {
+			return d, true
+		}
+	}
+	return nil, false
+}

backend/core/context_test.go

@@ -0,0 +1,646 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package core_test
+
+import (
+	"Wavelet/core"
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Sample services for testing
+type SampleService interface {
+	Greet(name string) string
+}
+
+type sampleServiceImpl struct {
+	prefix string
+}
+
+func (s *sampleServiceImpl) Greet(name string) string {
+	if s.prefix != "" {
+		return s.prefix + " " + name
+	}
+	return "Hello, " + name
+}
+
+type LogService interface {
+	Log(msg string)
+}
+
+type logServiceImpl struct {
+	logs []string
+}
+
+func (l *logServiceImpl) Log(msg string) {
+	l.logs = append(l.logs, msg)
+}
+
+type ConfigService interface {
+	Get(key string) string
+}
+
+type configServiceImpl struct {
+	data map[string]string
+}
+
+func (c *configServiceImpl) Get(key string) string {
+	return c.data[key]
+}
+
+// Sample plugin for testing
+type samplePlugin struct {
+	name string
+}
+
+func (p *samplePlugin) Name() string {
+	return p.name
+}
+
+func (p *samplePlugin) Apply(ctx *core.Context) error {
+	core.Provide[SampleService](ctx, &sampleServiceImpl{prefix: "Plugin:"})
+	return nil
+}
+
+func (p *samplePlugin) Manifest() core.Manifest {
+	return core.Manifest{
+		Name:        p.name,
+		Version:     "1.0.0",
+		Description: "Sample plugin",
+	}
+}
+
+// Sample driver for testing
+type mockDriver struct {
+	driverType core.DriverType
+	started    bool
+	stopped    bool
+}
+
+func (m *mockDriver) Type() core.DriverType {
+	return m.driverType
+}
+
+func (m *mockDriver) Start(ctx context.Context) error {
+	m.started = true
+	return nil
+}
+
+func (m *mockDriver) Stop(ctx context.Context) error {
+	m.stopped = true
+	return nil
+}
+
+func TestContextProvideAndInject(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+
+	// Before providing, Inject should fail
+	_, err := core.Inject[SampleService](ctx)
+	require.Error(t, err)
+	assert.True(t, errors.Is(err, core.ErrServiceNotFound))
+	assert.False(t, core.Has[SampleService](ctx))
+
+	// MustInject should panic
+	assert.Panics(t, func() {
+		core.MustInject[SampleService](ctx)
+	})
+
+	// Provide service
+	svcImpl := &sampleServiceImpl{prefix: "Hello,"}
+	core.Provide[SampleService](ctx, svcImpl)
+
+	// Inject should succeed
+	assert.True(t, core.Has[SampleService](ctx))
+	svc, err := core.Inject[SampleService](ctx)
+	require.NoError(t, err)
+	assert.Equal(t, "Hello, Wavelet", svc.Greet("Wavelet"))
+
+	// MustInject should succeed
+	mustSvc := core.MustInject[SampleService](ctx)
+	assert.Equal(t, "Hello, Cordis", mustSvc.Greet("Cordis"))
+}
+
+func TestContextProvideNilPanics(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+
+	assert.Panics(t, func() {
+		core.Provide[SampleService](nil, &sampleServiceImpl{})
+	})
+
+	assert.Panics(t, func() {
+		var nilSvc SampleService
+		core.Provide[SampleService](ctx, nilSvc)
+	})
+
+	assert.Panics(t, func() {
+		var nilImpl *sampleServiceImpl
+		core.Provide[*sampleServiceImpl](ctx, nilImpl)
+	})
+
+	// Inject with nil context
+	var nilCtx *core.Context
+	_, err := core.Inject[SampleService](nilCtx)
+	assert.ErrorIs(t, err, core.ErrNilContext)
+}
+
+func TestContextUsing(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	var called bool
+
+	// Using when service not ready should return ErrServiceNotReady
+	err := core.Using(ctx, func(s SampleService) {
+		called = true
+		assert.Equal(t, "Hello, Cordis", s.Greet("Cordis"))
+	})
+	assert.Error(t, err)
+	assert.True(t, errors.Is(err, core.ErrServiceNotReady))
+	assert.False(t, called)
+
+	// Provide service and try Using again
+	core.Provide[SampleService](ctx, &sampleServiceImpl{})
+	err = core.Using(ctx, func(s SampleService) {
+		called = true
+		assert.Equal(t, "Hello, Cordis", s.Greet("Cordis"))
+	})
+	assert.NoError(t, err)
+	assert.True(t, called)
+}
+
+func TestContextUsingMultiple(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+
+	// Using2 with missing dependencies
+	var called2 bool
+	err := core.Using2(ctx, func(s SampleService, l LogService) {
+		called2 = true
+	})
+	assert.Error(t, err)
+	assert.False(t, called2)
+
+	// Provide 1 of 2
+	core.Provide[SampleService](ctx, &sampleServiceImpl{})
+	err = core.Using2(ctx, func(s SampleService, l LogService) {
+		called2 = true
+	})
+	assert.Error(t, err)
+	assert.False(t, called2)
+
+	// Provide 2 of 2
+	logSvc := &logServiceImpl{}
+	core.Provide[LogService](ctx, logSvc)
+	err = core.Using2(ctx, func(s SampleService, l LogService) {
+		called2 = true
+		l.Log(s.Greet("World"))
+	})
+	assert.NoError(t, err)
+	assert.True(t, called2)
+	assert.Equal(t, []string{"Hello, World"}, logSvc.logs)
+
+	// Using3 test - error condition
+	err = core.Using3(ctx, func(s SampleService, l LogService, c ConfigService) {})
+	assert.Error(t, err)
+
+	// Using3 test - success condition
+	var called3 bool
+	cfgSvc := &configServiceImpl{data: map[string]string{"env": "test"}}
+	core.Provide[ConfigService](ctx, cfgSvc)
+
+	err = core.Using3(ctx, func(s SampleService, l LogService, c ConfigService) {
+		called3 = true
+		assert.Equal(t, "test", c.Get("env"))
+	})
+	assert.NoError(t, err)
+	assert.True(t, called3)
+}
+
+// UsingN must keep every dependency failure reachable through the error chain,
+// not just report that something went wrong.
+func TestContextUsingMultipleErrorChain(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+
+	err := core.Using2(ctx, func(s SampleService, l LogService) {
+		t.Fatal("callback must not run when dependencies are missing")
+	})
+	require.Error(t, err)
+	assert.ErrorIs(t, err, core.ErrServiceNotReady)
+	assert.ErrorIs(t, err, core.ErrServiceNotFound)
+
+	// Only LogService is missing now, so exactly one joined cause must be present.
+	core.Provide[SampleService](ctx, &sampleServiceImpl{})
+	err = core.Using2(ctx, func(s SampleService, l LogService) {
+		t.Fatal("callback must not run when a dependency is missing")
+	})
+	assert.ErrorIs(t, err, core.ErrServiceNotReady)
+	assert.ErrorIs(t, err, core.ErrServiceNotFound)
+
+	err = core.Using3(ctx, func(s SampleService, l LogService, c ConfigService) {
+		t.Fatal("callback must not run when a dependency is missing")
+	})
+	assert.ErrorIs(t, err, core.ErrServiceNotReady)
+	assert.ErrorIs(t, err, core.ErrServiceNotFound)
+}
+
+func TestContextHierarchyAndFork(t *testing.T) {
+	parent := core.NewContext(nil) // nil base context test
+	core.Provide[SampleService](parent, &sampleServiceImpl{prefix: "Parent:"})
+
+	child := parent.ForkWithContext(nil) // nil child context test
+	require.NotNil(t, child)
+	assert.Equal(t, parent, child.Parent())
+
+	// Child can resolve service from parent
+	svc, err := core.Inject[SampleService](child)
+	require.NoError(t, err)
+	assert.Equal(t, "Parent: Ryan", svc.Greet("Ryan"))
+
+	// Child provides LogService
+	childLog := &logServiceImpl{}
+	core.ProvideScoped[LogService](child, childLog)
+
+	// Child has LogService, parent does not
+	assert.True(t, core.Has[LogService](child))
+	assert.False(t, core.Has[LogService](parent))
+
+	// Child overrides SampleService locally
+	core.ProvideScoped[SampleService](child, &sampleServiceImpl{prefix: "Child:"})
+	childSvc, err := core.Inject[SampleService](child)
+	require.NoError(t, err)
+	assert.Equal(t, "Child: Ryan", childSvc.Greet("Ryan"))
+
+	parentSvc, err := core.Inject[SampleService](parent)
+	require.NoError(t, err)
+	assert.Equal(t, "Parent: Ryan", parentSvc.Greet("Ryan"))
+}
+
+func TestContextReactiveWhen(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+
+	assert.Panics(t, func() {
+		core.When[SampleService](nil, func(s SampleService) {})
+	})
+
+	var whenCalled atomic.Bool
+	var greeted string
+
+	// Register When before service is provided
+	core.When[SampleService](ctx, func(s SampleService) {
+		whenCalled.Store(true)
+		greeted = s.Greet("Reactive")
+	})
+
+	assert.False(t, whenCalled.Load())
+
+	// Now Provide the service - listener should trigger
+	core.Provide[SampleService](ctx, &sampleServiceImpl{})
+
+	assert.True(t, whenCalled.Load())
+	assert.Equal(t, "Hello, Reactive", greeted)
+
+	// Register another When after service is already provided - should trigger immediately
+	var immediateCalled bool
+	core.When[SampleService](ctx, func(s SampleService) {
+		immediateCalled = true
+	})
+	assert.True(t, immediateCalled)
+}
+
+func TestWhenObservesProvideFromForkedFiberContext(t *testing.T) {
+	root := core.NewContext(context.Background())
+	adminFiber := root.Fork()
+	lateFiber := root.Fork()
+
+	var got atomic.Bool
+	core.When[SampleService](adminFiber, func(s SampleService) {
+		if s != nil {
+			got.Store(true)
+		}
+	})
+	assert.False(t, got.Load())
+
+	core.Provide[SampleService](lateFiber, &sampleServiceImpl{})
+	assert.True(t, got.Load(), "When on a Fiber child must observe Provide on the root")
+}
+
+func TestBindIsWhen(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	var called atomic.Bool
+	core.Bind[SampleService](ctx, func(s SampleService) {
+		called.Store(true)
+	})
+	core.Provide[SampleService](ctx, &sampleServiceImpl{})
+	assert.True(t, called.Load())
+}
+
+func TestInjectFromAppContext(t *testing.T) {
+	app := core.NewContext(context.Background())
+	core.Provide[SampleService](app, &sampleServiceImpl{prefix: "Hi:"})
+
+	req := core.WithAppContext(context.Background(), app)
+	svc, err := core.InjectFrom[SampleService](req)
+	require.NoError(t, err)
+	assert.Equal(t, "Hi: Ada", svc.Greet("Ada"))
+
+	_, err = core.InjectFrom[SampleService](context.Background())
+	assert.ErrorIs(t, err, core.ErrNilContext)
+}
+
+func TestContextDisposerLifecycle(t *testing.T) {
+	parent := core.NewContext(context.Background())
+	child := parent.Fork()
+
+	var order []string
+
+	// Test nil disposer
+	parent.OnDispose(nil)
+
+	// Test Disposer type
+	var customDisposer core.Disposer = func() error {
+		order = append(order, "parent-custom")
+		return nil
+	}
+	parent.OnDispose(customDisposer)
+
+	parent.OnDispose(func() error {
+		order = append(order, "parent-1")
+		return nil
+	})
+	parent.OnDispose(func() {
+		order = append(order, "parent-2")
+	})
+
+	child.OnDispose(func() error {
+		order = append(order, "child-1")
+		return errors.New("child-1 error")
+	})
+	child.OnDispose(func() {
+		order = append(order, "child-2")
+	})
+
+	assert.Panics(t, func() {
+		parent.OnDispose("invalid-func")
+	})
+
+	assert.False(t, parent.IsDisposed())
+	assert.False(t, child.IsDisposed())
+
+	// Disposing parent should cascade to children first, and execute disposers in LIFO order
+	err := parent.Dispose()
+	assert.Error(t, err) // child-1 error should be joined
+	assert.Contains(t, err.Error(), "child-1 error")
+
+	assert.True(t, parent.IsDisposed())
+	assert.True(t, child.IsDisposed())
+
+	// Child disposers run in LIFO: child-2, child-1
+	// Parent disposers run in LIFO: parent-2, parent-1, parent-custom
+	expected := []string{"child-2", "child-1", "parent-2", "parent-1", "parent-custom"}
+	assert.Equal(t, expected, order)
+
+	// Disposing again should be idempotent and return nil
+	err = parent.Dispose()
+	assert.NoError(t, err)
+}
+
+func TestContextStandardGoContext(t *testing.T) {
+	baseCtx, cancel := context.WithDeadline(context.Background(), time.Now().Add(5*time.Second))
+	defer cancel()
+
+	parentCtx := core.NewContext(baseCtx)
+	parentCtx.Set("parent_key", "parent_val")
+
+	childCtx := parentCtx.Fork()
+
+	// Deadline
+	dl, ok := childCtx.Deadline()
+	assert.True(t, ok)
+	assert.False(t, dl.IsZero())
+
+	// Value fallback: child has no key, falls back to parentCtx
+	assert.Equal(t, "parent_val", childCtx.Value("parent_key"))
+
+	// GoContext getter
+	assert.NotNil(t, childCtx.GoContext())
+
+	// Value not found in either
+	assert.Nil(t, childCtx.Value("non_existent_key"))
+
+	// Cancellation propagation
+	select {
+	case <-childCtx.Done():
+		t.Fatal("ctx should not be done yet")
+	default:
+	}
+
+	cancel()
+
+	select {
+	case <-childCtx.Done():
+		assert.Equal(t, context.Canceled, childCtx.Err())
+	case <-time.After(100 * time.Millisecond):
+		t.Fatal("ctx should be cancelled")
+	}
+}
+
+func TestManifestValidation(t *testing.T) {
+	mValid := core.Manifest{
+		Name:        "auth",
+		Version:     "1.0.0",
+		Description: "Auth plugin",
+	}
+	assert.NoError(t, mValid.Validate())
+
+	mInvalid := core.Manifest{
+		Version: "1.0.0",
+	}
+	assert.Error(t, mInvalid.Validate())
+}
+
+func TestDriverRegistration(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+
+	// Register nil driver returns error
+	assert.ErrorIs(t, ctx.RegisterDriver(nil), core.ErrNilService)
+
+	dHTTP := &mockDriver{driverType: core.DriverTypeHTTP}
+	dWorker := &mockDriver{driverType: core.DriverTypeWorker}
+
+	require.NoError(t, ctx.RegisterDriver(dHTTP))
+	require.NoError(t, ctx.RegisterDriver(dWorker))
+
+	drivers := ctx.Drivers()
+	assert.Len(t, drivers, 2)
+
+	foundHTTP, ok := ctx.Driver(core.DriverTypeHTTP)
+	assert.True(t, ok)
+	assert.Equal(t, dHTTP, foundHTTP)
+
+	foundWorker, ok := ctx.Driver(core.DriverTypeWorker)
+	assert.True(t, ok)
+	assert.Equal(t, dWorker, foundWorker)
+
+	_, ok = ctx.Driver(core.DriverTypeScheduler)
+	assert.False(t, ok)
+}
+
+func TestPluginInterfaces(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	var p core.Plugin = &samplePlugin{name: "sample"}
+	assert.Equal(t, "sample", p.Name())
+	require.NoError(t, p.Apply(ctx))
+
+	svc, err := core.Inject[SampleService](ctx)
+	require.NoError(t, err)
+	assert.Equal(t, "Plugin: Ryan", svc.Greet("Ryan"))
+
+	var pwm core.PluginWithManifest = &samplePlugin{name: "sample"}
+	manifest := pwm.Manifest()
+	assert.Equal(t, "sample", manifest.Name)
+	assert.Equal(t, "1.0.0", manifest.Version)
+}
+
+func TestConcurrentAccess(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	var wg sync.WaitGroup
+
+	// Concurrently provide, inject, fork, set, and get
+	for i := 0; i < 50; i++ {
+		wg.Add(1)
+		go func(idx int) {
+			defer wg.Done()
+			ctx.Set(fmt.Sprintf("key-%d", idx), idx)
+			_, _ = ctx.Get(fmt.Sprintf("key-%d", idx))
+
+			child := ctx.Fork()
+			child.Set("child_key", idx)
+		}(i)
+	}
+
+	core.Provide[SampleService](ctx, &sampleServiceImpl{})
+
+	for i := 0; i < 50; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			svc, err := core.Inject[SampleService](ctx)
+			if err == nil {
+				_ = svc.Greet("Concurrency")
+			}
+			_ = core.Using(ctx, func(s SampleService) {
+				_ = s.Greet("Safe")
+			})
+		}()
+	}
+
+	wg.Wait()
+}
+
+func TestContextExtensionPointsAccessors(t *testing.T) {
+	ctx := core.NewContext(nil)
+	assert.NotNil(t, ctx.Events())
+	assert.NotNil(t, ctx.Router())
+	assert.NotNil(t, ctx.Migrations())
+	assert.NotNil(t, ctx.Tasks())
+	assert.NotNil(t, ctx.Task())
+	assert.NotNil(t, ctx.Schedules())
+	assert.NotNil(t, ctx.Schedule())
+	assert.NotNil(t, ctx.Settings())
+	assert.NotNil(t, ctx.Setting())
+
+	child := ctx.Fork()
+	assert.Equal(t, ctx.Events(), child.Events())
+	assert.Equal(t, ctx.Migrations(), child.Migrations())
+	assert.NotNil(t, child.Router())
+	assert.NotNil(t, child.Tasks())
+	assert.NotNil(t, child.Task())
+	assert.NotNil(t, child.Schedules())
+	assert.NotNil(t, child.Schedule())
+	assert.NotNil(t, child.Settings())
+	assert.NotNil(t, child.Setting())
+}
+
+func TestContext_ScopedExtpoints_RevertibleEffects(t *testing.T) {
+	root := core.NewContext(context.Background())
+	child := root.Fork()
+
+	// Register route, task, schedule, setting, event, middleware, whitelist on child
+	child.Router().GET("/test-route", func() {})
+	assert.Equal(t, 1, len(root.Router().Routes()))
+
+	child.Router().Use("scoped_middleware")
+	assert.Equal(t, 1, len(root.Router().Middlewares()))
+
+	child.Router().RegisterWhitelist("/api/v1/scoped/*")
+	assert.True(t, root.Router().IsWhitelisted("/api/v1/scoped/test"))
+
+	child.Tasks().Register("test:task", func() {})
+	assert.Equal(t, 1, len(root.Tasks().Tasks()))
+
+	child.Schedules().RegisterCron("@hourly", "test:cron", nil)
+	assert.Equal(t, 1, len(root.Schedules().Schedules()))
+
+	child.Settings().Register(core.SettingSchema{Key: "test.key", Default: "val"})
+	assert.Equal(t, 1, len(root.Settings().Schemas()))
+
+	child.On("test:event", func() {})
+	assert.Equal(t, 1, root.Events().Listeners("test:event"))
+
+	// Dispose child
+	err := child.Dispose()
+	assert.NoError(t, err)
+
+	// All child effects should be cleanly revoked in LIFO order
+	assert.Equal(t, 0, len(root.Router().Routes()))
+	assert.Equal(t, 0, len(root.Router().Middlewares()))
+	assert.False(t, root.Router().IsWhitelisted("/api/v1/scoped/test"))
+	assert.Equal(t, 0, len(root.Tasks().Tasks()))
+	assert.Equal(t, 0, len(root.Schedules().Schedules()))
+	assert.Equal(t, 0, len(root.Settings().Schemas()))
+	assert.Equal(t, 0, root.Events().Listeners("test:event"))
+}
+
+func TestContainer_InterfaceResolutionCache(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	svc := &sampleServiceImpl{prefix: "Cached:"}
+
+	core.Provide[SampleService](ctx, svc)
+
+	// 1. Initial resolution populates interfaceCache
+	res1, err := core.Inject[SampleService](ctx)
+	require.NoError(t, err)
+	assert.Equal(t, "Cached: Alice", res1.Greet("Alice"))
+
+	// 2. Subsequent resolutions hit interfaceCache
+	res2, err := core.Inject[SampleService](ctx)
+	require.NoError(t, err)
+	assert.Same(t, res1, res2)
+
+	// 3. Concurrent lookups
+	var wg sync.WaitGroup
+	for i := 0; i < 20; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			r, e := core.Inject[SampleService](ctx)
+			assert.NoError(t, e)
+			assert.Equal(t, "Cached: Bob", r.Greet("Bob"))
+		}()
+	}
+	wg.Wait()
+
+	// 4. Overriding/providing another service invalidates cache
+	svc2 := &sampleServiceImpl{prefix: "Updated:"}
+	core.Provide[SampleService](ctx, svc2)
+
+	res3, err := core.Inject[SampleService](ctx)
+	require.NoError(t, err)
+	assert.Equal(t, "Updated: Alice", res3.Greet("Alice"))
+}

backend/core/contracts/auth.go

@@ -0,0 +1,143 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package contracts defines unified service interfaces and DTOs for cross-plugin communication.
+package contracts
+
+import (
+	"context"
+	"time"
+)
+
+// UserDTO represents a unified user data transfer object across plugins.
+type UserDTO struct {
+	ID                 uint64    `json:"id,string"`
+	Username           string    `json:"username"`
+	Nickname           string    `json:"nickname"`
+	Email              string    `json:"email"`
+	AvatarURL          string    `json:"avatar_url"`
+	IsActive           bool      `json:"is_active"`
+	IsAdmin            bool      `json:"is_admin"`
+	NeedChangePassword bool      `json:"need_change_password,omitempty"`
+	Bio                string    `json:"bio,omitempty"`
+	Phone              string    `json:"phone,omitempty"`
+	Gender             string    `json:"gender,omitempty"`
+	Website            string    `json:"website,omitempty"`
+	Location           string    `json:"location,omitempty"`
+	LastLoginAt        time.Time `json:"last_login_at"`
+	CreatedAt          time.Time `json:"created_at"`
+	UpdatedAt          time.Time `json:"updated_at"`
+}
+
+// OAuthUserInfoDTO contains user identity claims obtained from an OAuth provider.
+type OAuthUserInfoDTO struct {
+	ID                uint64 `json:"id"`
+	Sub               string `json:"sub"`
+	Username          string `json:"username"`
+	PreferredUsername string `json:"preferred_username"`
+	Email             string `json:"email"`
+	Name              string `json:"name"`
+	Active            bool   `json:"active"`
+	AvatarURL         string `json:"avatar_url"`
+}
+
+// AuthSourceDTO represents an OAuth / OIDC authentication source.
+type AuthSourceDTO struct {
+	ID                 uint64    `json:"id,string"`
+	Name               string    `json:"name"`
+	Type               string    `json:"type"`
+	DisplayName        string    `json:"display_name"`
+	ClientID           string    `json:"client_id"`
+	ClientSecret       string    `json:"client_secret,omitempty"`
+	OpenIDDiscoveryURL string    `json:"openid_discovery_url"`
+	Scopes             string    `json:"scopes"`
+	IconURL            string    `json:"icon_url"`
+	IsActive           bool      `json:"is_active"`
+	CreatedAt          time.Time `json:"created_at"`
+	UpdatedAt          time.Time `json:"updated_at"`
+}
+
+// AuthSourceViewDTO is a sanitized view of an AuthSource for admin display.
+type AuthSourceViewDTO struct {
+	ID                     uint64 `json:"id,string"`
+	Name                   string `json:"name"`
+	Type                   string `json:"type"`
+	DisplayName            string `json:"display_name"`
+	IsActive               bool   `json:"is_active"`
+	IconURL                string `json:"icon_url"`
+	ClientSecretConfigured bool   `json:"client_secret_configured"`
+}
+
+// OAuthProvider defines the pluggable OAuth provider contract.
+type OAuthProvider interface {
+	Name() string
+	GetAuthURL(state string) string
+	ExchangeCode(ctx context.Context, code string) (*OAuthUserInfoDTO, error)
+}
+
+// AuthService defines the contract for authentication, session verification, and token management.
+type AuthService interface {
+	// RequireAuthMiddleware returns a middleware handler (compatible with gin.HandlerFunc or standard middleware).
+	RequireAuthMiddleware() any
+
+	// RequireAdminMiddleware returns an admin authorization middleware.
+	RequireAdminMiddleware() any
+
+	// GetCurrentUser retrieves the authenticated UserDTO from context.
+	GetCurrentUser(ctx context.Context) (*UserDTO, error)
+
+	// GetCurrentUserID retrieves the authenticated user ID from session/context.
+	GetCurrentUserID(ctx context.Context) (uint64, error)
+
+	// VerifyToken validates an access token and returns the associated user DTO.
+	VerifyToken(ctx context.Context, token string) (*UserDTO, error)
+
+	// CreateSession establishes an authenticated session for the given user ID.
+	CreateSession(ctx context.Context, userID uint64, extras map[string]any) (string, error)
+
+	// RevokeToken invalidates a specific access token by its hash.
+	RevokeToken(ctx context.Context, tokenHash string) error
+
+	// RevokeUserSessions revokes all active sessions and cached tokens for a user.
+	RevokeUserSessions(ctx context.Context, userID uint64) error
+
+	// InvalidateCachedUser invalidates cached user profile data.
+	InvalidateCachedUser(ctx context.Context, userID uint64)
+
+	// InvalidateCachedToken invalidates cached access token data.
+	InvalidateCachedToken(ctx context.Context, tokenHash string)
+
+	// ListAuthSources lists all configured authentication sources.
+	ListAuthSources(ctx context.Context) ([]AuthSourceViewDTO, error)
+
+	// CreateAuthSource creates a new authentication source.
+	CreateAuthSource(ctx context.Context, source AuthSourceDTO) (*AuthSourceDTO, error)
+
+	// UpdateAuthSource updates an authentication source.
+	UpdateAuthSource(ctx context.Context, id uint64, source AuthSourceDTO) (*AuthSourceDTO, error)
+
+	// DeleteAuthSource removes an authentication source.
+	DeleteAuthSource(ctx context.Context, id uint64) error
+
+	// ToggleAuthSource toggles the active state of an authentication source.
+	ToggleAuthSource(ctx context.Context, id uint64) (*AuthSourceDTO, error)
+
+	// DisallowTokenAuthMiddleware returns a middleware that rejects requests authenticated via access token.
+	DisallowTokenAuthMiddleware() any
+}
+
+// AuthRegistry allows downstream and domain plugins to register custom authentication providers.
+type AuthRegistry interface {
+	RegisterOAuthProvider(name string, provider OAuthProvider)
+	GetOAuthProvider(name string) (OAuthProvider, bool)
+	ListOAuthProviders() []string
+}
+
+// Auth context keys — stored in Gin context by auth middleware, consumed by domain plugins.
+const (
+	AuthUserIDKey     = "user_id"
+	AuthUserNameKey   = "username"
+	AuthUserObjKey    = "user_obj"
+	AuthTokenAuthKey  = "token_auth"  // marks if request uses access token auth
+	AuthTokenAdminKey = "token_admin" // whether the access token has admin privileges
+)

backend/core/contracts/cache.go

@@ -0,0 +1,32 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package contracts defines unified service interfaces and DTOs for cross-plugin communication.
+package contracts
+
+import (
+	"context"
+	"errors"
+	"time"
+)
+
+// ErrCacheMiss is returned when an item is not found in the cache.
+var ErrCacheMiss = errors.New("contracts/cache: key not found")
+
+// CacheService defines the contract for multi-layer cache operations (RAM L1 + Redis L2 + Pub/Sub invalidation).
+type CacheService interface {
+	// Get retrieves an item from cache into target. Returns ErrCacheMiss if not found.
+	Get(ctx context.Context, key string, target any) error
+
+	// Set stores an item into cache with a specified time-to-live duration.
+	Set(ctx context.Context, key string, value any, ttl time.Duration) error
+
+	// Delete evicts a key from local and remote cache tiers and broadcasts invalidation.
+	Delete(ctx context.Context, key string) error
+
+	// GetOrSet retrieves an item from cache, or calls loader to populate and return if missing.
+	GetOrSet(ctx context.Context, key string, target any, ttl time.Duration, loader func() (any, error)) error
+
+	// Invalidate is a semantic alias for Delete.
+	Invalidate(ctx context.Context, key string) error
+}

backend/core/contracts/captcha.go

@@ -0,0 +1,12 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package contracts
+
+// CaptchaService defines the contract for CAPTCHA challenge issuance,
+// redemption, and scoped verification middleware.
+type CaptchaService interface {
+	VerifyMiddleware(scope string) any
+	ChallengeHandler() any
+	RedeemHandler() any
+}

backend/core/contracts/config.go

@@ -0,0 +1,33 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package contracts
+
+import (
+	"context"
+	"time"
+)
+
+// SystemConfigDTO represents a system configuration key-value entry.
+type SystemConfigDTO struct {
+	Key         string    `json:"key"`
+	Value       string    `json:"value"`
+	Type        string    `json:"type"`
+	Visibility  int       `json:"visibility"`
+	Description string    `json:"description"`
+	UpdatedAt   time.Time `json:"updated_at"`
+	CreatedAt   time.Time `json:"created_at"`
+}
+
+// SystemConfigService defines the unified contract for querying and mutating system configurations.
+type SystemConfigService interface {
+	GetByKey(ctx context.Context, key string) (SystemConfigDTO, error)
+	ListByKeys(ctx context.Context, keys []string) (map[string]SystemConfigDTO, error)
+	ListVisible(ctx context.Context) ([]SystemConfigDTO, error)
+	ListByType(ctx context.Context, configType string) ([]SystemConfigDTO, error)
+	GetIntByKey(ctx context.Context, key string) (int, error)
+	GetBoolByKey(ctx context.Context, key string) (bool, error)
+	SaveOrUpdate(ctx context.Context, key, value string) error
+	InvalidateCache(ctx context.Context, key string) error
+	InvalidateAllCaches(ctx context.Context) error
+}

backend/core/contracts/config_public.go

@@ -0,0 +1,14 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package contracts
+
+import "context"
+
+// PublicConfigProvider supplies GET /api/v1/config/public.
+// The owner of w_system_configs (admin) must provide this. The payload is a
+// flat key/value map of visibility=1 rows; the frontend reads keys such as
+// cap_login_enabled directly off data.
+type PublicConfigProvider interface {
+	PublicConfig(ctx context.Context) (map[string]string, error)
+}

backend/core/contracts/database.go

@@ -0,0 +1,23 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package contracts defines unified service interfaces and DTOs for cross-plugin communication.
+package contracts
+
+import (
+	"context"
+
+	"gorm.io/gorm"
+)
+
+// DBService defines the standard contract for relational database access and multi-datasource routing.
+type DBService interface {
+	// GORM returns the underlying GORM database instance.
+	GORM() *gorm.DB
+
+	// DB returns the GORM database instance bound to the given context.
+	DB(ctx context.Context) *gorm.DB
+
+	// Named returns a named database connection if multiple data sources or replicas are configured.
+	Named(name string) *gorm.DB
+}

backend/core/contracts/events.go

@@ -0,0 +1,158 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package contracts defines unified service interfaces and DTOs for cross-plugin communication.
+package contracts
+
+// ======================================================================
+// Domain Event Topic Constants
+// ======================================================================
+//
+// All cross-plugin domain event topics MUST be declared here so that
+// producers and consumers share the same string values without importing
+// each other's implementation packages.
+// ======================================================================
+
+// --- Auth & User Events ---
+const (
+	// EventTopicAdminLoggedIn fires when an admin user logs in.
+	EventTopicAdminLoggedIn = "admin:logged_in"
+
+	// EventTopicUserCreated fires when a new user account is created.
+	EventTopicUserCreated = "user:created"
+
+	// EventTopicUserUpdated fires when a user profile is updated.
+	EventTopicUserUpdated = "user:updated"
+
+	// EventTopicUserDeleted fires when a user account is deleted.
+	EventTopicUserDeleted = "user:deleted"
+
+	// EventTopicUserStatusChanged fires when a user account active status changes.
+	EventTopicUserStatusChanged = "user:status_changed"
+
+	// EventTopicTokenRevoked fires when an access token is revoked.
+	// #nosec G101
+	EventTopicTokenRevoked = "auth:token_revoked"
+)
+
+// --- Admin & System Events ---
+const (
+	// EventTopicConfigChanged fires when a system configuration value changes.
+	EventTopicConfigChanged = "admin:config_changed"
+
+	// EventTopicSystemCleanup fires when a periodic system cleanup completes.
+	EventTopicSystemCleanup = "admin:system_cleanup"
+)
+
+// --- Task Events ---
+const (
+	// EventTopicTaskCompleted fires when an asynchronous background task execution finishes.
+	EventTopicTaskCompleted = "task:completed"
+)
+
+// TaskCompletedEvent carries task execution outcome details.
+type TaskCompletedEvent struct {
+	TaskID    string `json:"task_id"`
+	TaskName  string `json:"task_name"`
+	TaskType  string `json:"task_type"`
+	Status    string `json:"status"`
+	Duration  int64  `json:"duration"`
+	ErrorMsg  string `json:"error_msg,omitempty"`
+	ResultMsg string `json:"result_msg,omitempty"`
+	Payload   string `json:"payload,omitempty"`
+	Detail    string `json:"detail,omitempty"`
+}
+
+// --- Upload / Storage Events ---
+const (
+	// EventTopicUploadCreated fires when a new file upload is recorded.
+	EventTopicUploadCreated = "upload:created"
+
+	// EventTopicUploadDeleted fires when a file upload is removed.
+	EventTopicUploadDeleted = "upload:deleted"
+
+	// EventTopicIngestComplete fires when a programmatic file ingest finishes.
+	EventTopicIngestComplete = "upload:ingest_complete"
+)
+
+// --- Message Gateway Events ---
+const (
+	// EventTopicNotificationSent fires when a push notification is dispatched.
+	EventTopicNotificationSent = "message:notification_sent"
+
+	// EventTopicChannelBound fires when a user binds a messaging channel.
+	EventTopicChannelBound = "message:channel_bound"
+
+	// EventTopicChannelUnbound fires when a user unbinds a messaging channel.
+	EventTopicChannelUnbound = "message:channel_unbound"
+)
+
+// --- Risk Control Events ---
+const (
+	// EventTopicAccessLogRecorded fires when a user access log entry is recorded.
+	EventTopicAccessLogRecorded = "risk:access_log_recorded"
+)
+
+// ======================================================================
+// Domain Event Payload DTOs
+// ======================================================================
+
+// AdminLoggedIn 管理员登录领域事件载荷
+type AdminLoggedIn struct {
+	User *UserDTO `json:"user"`
+	IP   string   `json:"ip"`
+}
+
+// UserCreatedEvent fires when a new user account is created.
+type UserCreatedEvent struct {
+	User     *UserDTO `json:"user"`
+	Password string   `json:"-"`
+}
+
+// ConfigChangedEvent fires when a system configuration value changes.
+type ConfigChangedEvent struct {
+	Key    string `json:"key"`
+	OldVal any    `json:"old_val,omitempty"`
+	NewVal any    `json:"new_val,omitempty"`
+}
+
+// UploadCreatedEvent fires when a new file upload is recorded.
+type UploadCreatedEvent struct {
+	UploadID uint64 `json:"upload_id,string"`
+	UserID   uint64 `json:"user_id,string"`
+	FileName string `json:"file_name"`
+	FileSize int64  `json:"file_size"`
+	MimeType string `json:"mime_type"`
+}
+
+// NotificationSentEvent fires when a push notification is dispatched.
+type NotificationSentEvent struct {
+	UserID    uint64 `json:"user_id,string"`
+	Channel   string `json:"channel"`
+	Title     string `json:"title"`
+	Success   bool   `json:"success"`
+	ErrorInfo string `json:"error_info,omitempty"`
+}
+
+// UserStatusChangedEvent fires when a user status is enabled/disabled.
+type UserStatusChangedEvent struct {
+	UserID   uint64 `json:"user_id,string"`
+	IsActive bool   `json:"is_active"`
+}
+
+// TokenRevokedEvent fires when an access token is revoked.
+type TokenRevokedEvent struct {
+	UserID    uint64 `json:"user_id,string"`
+	TokenHash string `json:"token_hash"`
+}
+
+// UserDeletedEvent fires when a user account is deleted.
+type UserDeletedEvent struct {
+	CurrentUserID uint64 `json:"current_user_id,string"`
+	TargetUserID  uint64 `json:"target_user_id,string"`
+}
+
+// SystemCleanupEvent fires when a periodic system cleanup is triggered.
+type SystemCleanupEvent struct {
+	TriggeredAt string `json:"triggered_at"`
+}

backend/core/contracts/limiter.go

@@ -0,0 +1,36 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package contracts defines unified service interfaces and DTOs for cross-plugin communication.
+package contracts
+
+import (
+	"context"
+	"time"
+)
+
+// Rate specifies a rate limit of Limit events permitted within a Period.
+type Rate struct {
+	Limit  int           `json:"limit"`
+	Period time.Duration `json:"period"`
+}
+
+// RateLimitResult holds the outcome of a rate limit check.
+type RateLimitResult struct {
+	Allowed    bool          `json:"allowed"`
+	Remaining  int           `json:"remaining"`
+	ResetAfter time.Duration `json:"reset_after"`
+	RetryAfter time.Duration `json:"retry_after"`
+}
+
+// LimiterService defines the rate limiting service contract for cross-plugin communication.
+type LimiterService interface {
+	// Allow checks whether 1 event for the given key is permitted under the specified rate.
+	Allow(ctx context.Context, key string, rate Rate) (*RateLimitResult, error)
+
+	// AllowN checks whether n events for the given key are permitted under the specified rate.
+	AllowN(ctx context.Context, key string, rate Rate, n int) (*RateLimitResult, error)
+
+	// Reset clears the rate limit state for the given key.
+	Reset(ctx context.Context, key string) error
+}

backend/core/contracts/logger.go

@@ -0,0 +1,39 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package contracts defines unified service interfaces and DTOs for cross-plugin communication.
+package contracts
+
+import (
+	"context"
+)
+
+// LoggerService defines the contract for structured logging with trace ID and context correlation.
+type LoggerService interface {
+	// Debug logs a debug message with optional key-value structured fields.
+	Debug(ctx context.Context, msg string, keysAndValues ...any)
+
+	// Info logs an informational message with optional key-value structured fields.
+	Info(ctx context.Context, msg string, keysAndValues ...any)
+
+	// Warn logs a warning message with optional key-value structured fields.
+	Warn(ctx context.Context, msg string, keysAndValues ...any)
+
+	// Error logs an error message with optional key-value structured fields.
+	Error(ctx context.Context, msg string, keysAndValues ...any)
+
+	// Debugf logs a formatted debug message.
+	Debugf(ctx context.Context, format string, args ...any)
+
+	// Infof logs a formatted informational message.
+	Infof(ctx context.Context, format string, args ...any)
+
+	// Warnf logs a formatted warning message.
+	Warnf(ctx context.Context, format string, args ...any)
+
+	// Errorf logs a formatted error message.
+	Errorf(ctx context.Context, format string, args ...any)
+
+	// With returns a child logger enriched with additional key-value attributes.
+	With(keysAndValues ...any) LoggerService
+}

backend/core/contracts/push.go

@@ -0,0 +1,29 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package contracts defines unified service interfaces and DTOs for cross-plugin communication.
+package contracts
+
+import "context"
+
+// PushNotificationTemplate defines notification message template payload.
+type PushNotificationTemplate struct {
+	Title   string
+	Content string
+	Level   string
+	Ext     map[string]any
+}
+
+// PushEventMeta defines metadata for a system push event.
+type PushEventMeta struct {
+	Key             string
+	Name            string
+	Description     string
+	DefaultTemplate PushNotificationTemplate
+}
+
+// PushRegistry defines the interface for registering built-in events.
+type PushRegistry interface {
+	RegisterBuiltInEvent(meta PushEventMeta)
+	SyncEvents(ctx context.Context) error
+}