Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)

2026-09-15 08:41:51 +08:00
commit bb35e661b2
114 changed files with 20240 additions and 0 deletions
@@ -0,0 +1,105 @@
+# Source Analysis — Document Templates
+
+> Used by Phase B1 (pipeline mode).
+> Read this file when producing the source-analysis document set.
+> Each section below is the template for the corresponding numbered file
+> under `port-{name}/source-analysis/` (wiki pages via `wiki 读写 API（见 TERMINOLOGY）`).
+
+## 01-source-overview.md
+
+```markdown
+## Source Overview
+
+- **Project**: {name}
+- **Language / Runtime**: {e.g. Python 3.11}
+- **Framework**: {e.g. FastAPI}
+- **Feature scope**: {description of what's being ported}
+- **Source files**: {N}
+- **Source LOC**: {L}
+- **Source modules**: {list of distinct functional areas}
+```
+
+## 02-public-api.md
+
+Document every public interface:
+
+```markdown
+## Public API
+
+| Method / Endpoint | Input Schema   | Output Schema   | Errors               | Notes           |
+| ----------------- | -------------- | --------------- | --------------------- | --------------- |
+| POST /auth/login  | `{email, pw}`  | `{token, user}` | 400, 401, 429, 500    | Rate limited    |
+| GET /users/:id    | path param     | `User` object   | 401, 403, 404         | Auth required   |
+```
+
+## 03-data-model.md
+
+```markdown
+## Data Model
+
+### Entity: User
+| Field       | Type       | Constraints         |
+| ----------- | ---------- | ------------------- |
+| id          | UUID       | PK, not null        |
+| email       | string     | unique, not null    |
+| password    | string     | hashed, not null    |
+| created_at  | datetime   | not null            |
+
+### Relationships
+- User 1—N Session
+- User N—M Role
+```
+
+## 04-business-logic.md
+
+Capture every business rule, validation, edge case, and state transition
+from the source. Write each rule as an executable assertion:
+
+```markdown
+## Business Logic
+
+### Login
+- RULE-01: Valid credentials → return JWT + user object
+- RULE-02: Invalid password → 401 "Invalid credentials"
+- RULE-03: Non-existent email → 401 "Invalid credentials" (same message, no enumeration)
+- RULE-04: 5 failed attempts in 1 min → 429 + lock for 15 min
+- RULE-05: Locked account + valid password → 423 "Account locked"
+
+### Edge Cases
+- Empty email → 400 "Email is required"
+- Email > 254 chars → 400 "Email too long"
+- Password < 8 chars → 400 "Password too short"
+```
+
+## 05-error-handling.md
+
+```markdown
+## Error Handling
+
+| Error Code | HTTP Status | Message              | Source Condition      |
+| ---------- | ----------- | -------------------- | --------------------- |
+| AUTH_001   | 400         | Email is required    | empty email           |
+| AUTH_002   | 401         | Invalid credentials  | wrong email or pw     |
+| AUTH_003   | 429         | Too many attempts    | rate limit exceeded   |
+| AUTH_004   | 423         | Account locked       | locked out            |
+```
+
+## 10-fidelity-baseline.md
+
+This is the master inventory used by `verify` at the end. Every source
+behavior is listed as a checkable item:
+
+```markdown
+## Fidelity Baseline
+
+| ID         | Behavior                            | Type         | Source Test          | Chunk        |
+| ---------- | ----------------------------------- | ------------ | -------------------- | ------------ |
+| FID-001    | Login with valid credentials        | happy path   | test_login_ok        | chunk-auth   |
+| FID-002    | Login with invalid password         | error path   | test_login_bad_pw    | chunk-auth   |
+| FID-003    | Login with empty email              | edge case    | test_login_empty     | chunk-auth   |
+| FID-004    | Rate limiting after 5 attempts      | error path   | test_rate_limit      | chunk-auth   |
+```
+
+Each `FID-*` item maps to a `Chunk` column — this drives the DAG node
+decomposition. Behaviors in the same chunk are ported together. The
+`Source Test` column traces back to the original test for the verify stage.