Carry over the agent context and openspec history from lab 2

Bring the Claude Code settings, the lint hook, the opsx commands and
skills, the architecture notes, the lab 1 and lab 2 specs and the
archived lab 1 and lab 2 changes into the lab 3 skeleton, so lab 3
continues the same spec history instead of starting from scratch.

Rewrite AGENTS.md and the openspec context and rules for lab 3:
HAProxy in front of several stateless API replicas, X-Instance-Id on
every response, a mandatory Idempotency-Key for messages shared by all
replicas through PostgreSQL, explicit stop-one and restart hooks, Out
of scope moved to labs 4-7 plus Swarm and HA storage, and rules on
retry policy, timeout chains and replica-local state.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Artyom
2026-10-28 11:23:53 +03:00
co-authored by Claude Opus 5.5
parent 0ab3a341aa
commit 0ec2f9dae3
61 changed files with 5668 additions and 0 deletions
+181
View File
@@ -0,0 +1,181 @@
---
name: "OPSX: Apply"
description: "Implement tasks from an OpenSpec change (Experimental)"
allowed-tools: Bash(openspec:*)
category: "Workflow"
tags: ["workflow", "artifacts", "experimental"]
---
Implement tasks from an OpenSpec change.
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
2. **Check status to understand the schema**
```bash
openspec status --change "<name>" --json
```
Parse the JSON to understand:
- `schemaName`: The workflow being used (e.g., "spec-driven")
- `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
- Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
3. **Get apply instructions**
```bash
openspec instructions apply --change "<name>" --json
```
This returns:
- `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
- Progress (total, complete, remaining)
- Task list with status
- Dynamic instruction based on current state
- Optional `context`: current required project instruction input from the selected root
- Optional `operationGuidance`: current advisory guidance for apply
**Handle states:**
- If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue` (if it is not installed, run `openspec status --change "<name>" --json` to see the next artifact and `openspec instructions <artifact-id> --change "<name>" --json` for how to create it)
- If `state: "all_done"`: congratulate, suggest archive
- Otherwise: proceed to implementation
Treat `context` as a required prompt-level input. Read and consider it, and
apply relevant project facts, conventions, and constraints while implementing.
Treat `operationGuidance` as optional additive advice. Read and consider every
entry, and follow entries that are applicable and compatible with the built-in
workflow.
Keep both fields separate from CLI-returned state, missing artifacts, tasks,
progress, `contextFiles`, and the built-in `instruction`. They are not
evidence of task completion, do not replace the built-in instruction, and do
not permit bypassing a blocked state. If context conflicts with the built-in
instruction, an explicit user choice, or a CLI-controlled value, report the
conflict and preserve the controlling value. If guidance is inapplicable or
conflicts with those controlling inputs, do not follow it and explain why.
These are prompt-level behavior contracts, not enforceable checks.
4. **Read context files**
Read every file path listed under `contextFiles` from the apply instructions output.
The files depend on the schema being used:
- **spec-driven**: proposal, specs, design, tasks
- Other schemas: follow the contextFiles from CLI output
Do not copy `context` or `operationGuidance` verbatim into implementation
files or planning artifacts unless the user separately asks for that content.
5. **Show current progress**
Display:
- Schema being used
- Progress: "N/M tasks complete"
- Remaining tasks overview
- Dynamic instruction from CLI
6. **Implement tasks (loop until done or blocked)**
For each pending task:
- Show which task is being worked on
- Make the code changes required
- Keep changes minimal and focused
- Mark task complete in the tasks file: `- [ ]` → `- [x]`
- Continue to next task
**Pause if:**
- Task is unclear → ask for clarification
- Implementation reveals a design issue → suggest updating artifacts
- Error or blocker encountered → report and wait for guidance
- User interrupts
7. **On completion or pause, show status**
Display:
- Tasks completed this session
- Overall progress: "N/M tasks complete"
- If all done: suggest archive
- If paused: explain why and wait for guidance
**Output During Implementation**
```
## Implementing: <change-name> (schema: <schema-name>)
Working on task 3/7: <task description>
[...implementation happening...]
✓ Task complete
Working on task 4/7: <task description>
[...implementation happening...]
✓ Task complete
```
**Output On Completion**
```
## Implementation Complete
**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 7/7 tasks complete ✓
### Completed This Session
- [x] Task 1
- [x] Task 2
...
All tasks complete! You can archive this change with `/opsx:archive`.
```
**Output On Pause (Issue Encountered)**
```
## Implementation Paused
**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 4/7 tasks complete
### Issue Encountered
<description of the issue>
**Options:**
1. <option 1>
2. <option 2>
3. Other approach
What would you like to do?
```
**Guardrails**
- Keep going through tasks until done or blocked
- Always read context files before starting (from the apply instructions output)
- If task is ambiguous, pause and ask before implementing
- If implementation reveals issues, pause and suggest artifact updates
- Keep code changes minimal and scoped to each task
- Update task checkbox immediately after completing each task
- Pause on errors, blockers, or unclear requirements - don't guess
- Use contextFiles from CLI output, don't assume specific file names
- Do not use context or operation guidance as proof that a task is complete
- Apply relevant project context; report conflicts with controlling workflow inputs
- Consider every guidance entry; explain any inapplicable or conflicting advice
- Do not copy runtime context or operation guidance into implementation files or planning artifacts
- Preserve CLI-controlled blocked/ready/all-done behavior and completion criteria
**Fluid Workflow Integration**
This skill supports the "actions on a change" model:
- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
+225
View File
@@ -0,0 +1,225 @@
---
name: "OPSX: Archive"
description: "Archive a completed change in the experimental workflow"
allowed-tools: Bash(openspec:*)
category: "Workflow"
tags: ["workflow", "archive", "experimental"]
---
Archive a completed change in the experimental workflow.
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
When prompting, show only active changes (not already archived).
Include the schema used for each change if available.
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:archive <other>`).
**Load current archive inputs before the existing archive checks:**
After resolving the selected change and planning root, run:
```bash
openspec instructions archive --change "<name>" --json
```
Keep the same selected-root flags on this command. This lookup is advisory and
optional: it only supplies extra prompt inputs, so it must never block archiving.
If it exits non-zero or returns invalid JSON — for example on an older CLI that
does not support this command yet — continue the archive workflow with no
context and no operation guidance. Do not report an error and do not stop.
A successful response may omit both optional fields. Treat `context` as a
required prompt-level input: read and consider it, and apply relevant project
facts, conventions, and constraints. Treat `operationGuidance` as optional
additive advice: read and consider every entry, and follow entries that are
applicable and compatible with the built-in archive workflow.
Keep both fields separate from built-in steps, explicit user choices, resolved
paths, CLI checks, and command contracts. If context conflicts with one of those
controlling inputs, report the conflict and preserve the controlling value. If
guidance is inapplicable or conflicts with a controlling input, do not follow it
and explain why. Do not infer replacement paths, skipped prompts, or flags from
either field, and do not copy their text verbatim into specs, change artifacts,
or archive summaries unless the user separately asks for it. These are
prompt-level behavior contracts, not enforceable checks.
2. **Check artifact completion status**
Run `openspec status --change "<name>" --json` to check artifact completion.
Parse the JSON to understand:
- `schemaName`: The workflow being used
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
- `artifacts`: List of artifacts with their status (`done`, `skipped`, or other)
**If any artifacts are neither `done` nor `skipped`** (skipped artifacts satisfy the requirement - the change declares skip_specs):
- Display warning listing incomplete artifacts
- Prompt user for confirmation to continue
- Proceed if user confirms
3. **Check task completion status**
Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
**If incomplete tasks found:**
- Display warning showing count of incomplete tasks
- Prompt user for confirmation to continue
- Proceed if user confirms
**If no tasks file exists:** Proceed without task-related warning.
4. **Assess delta spec sync state**
Use `artifactPaths.specs.existingOutputPaths` from status JSON as the only
delta-spec source. If the `specs` entry is missing or
`existingOutputPaths` is empty, proceed without a sync prompt and do not infer
delta specs from other artifacts.
**If delta specs exist:**
- Compare each delta spec with its corresponding main spec at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (use the store-aware `planningHome.root` from step 2, not a hardcoded repo path)
- Determine what changes would be applied (adds, modifications, removals, renames)
- Show a combined summary before prompting
**Prompt options:**
- If changes needed: "Sync now (recommended)", "Archive without syncing"
- If already synced: "Archive now", "Sync anyway", "Cancel"
Route on the answer:
- "Cancel" — stop, do not archive
- "Archive without syncing" or "Archive now" — proceed to archive
- "Sync now" or "Sync anyway" — sync, then verify (below)
- Anything else — ask again rather than archiving
Before a selected sync writes any main spec, run
`openspec instructions specs --change "<name>" --json` once with the same
selected-root flags. Require a zero exit status and valid artifact-instruction
JSON. If the lookup fails or returns invalid JSON, report the error and stop
before writing any main spec or moving the change. A valid response with omitted
`rules` is the no-rules case. Apply returned `rules` only to the content and
form of main specs produced by this merge; do not use them as archive guidance,
change CLI behavior, or copy the rule text into any output file.
Then run the `/opsx:sync` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching `specs` instructions again. Do not delegate it to a background task — step 5 would move `changeRoot` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
Then re-run the comparison from the top of this step against every capability that has a delta spec in `artifactPaths.specs.existingOutputPaths` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
- ADDED requirements present
- MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact
- REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving `## Requirements` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
- RENAMED requirements present under the new name and absent under the old one
If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and `changeRoot` is intact, so the user can fix the mismatch or re-run the sync and start the archive again.
5. **Perform the archive**
Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
```bash
mkdir -p "<planningHome.changesDir>/archive"
```
Generate the target name: use the change name as-is when it already starts with a `YYYY-MM-DD-` prefix; otherwise prepend the current date as `YYYY-MM-DD-<change-name>`. Never stack a second date (same rule as `openspec archive`).
**Check if target already exists:**
- If yes: Fail with error, suggest renaming existing archive or using different date
- If no: Move `changeRoot` to the archive directory
```bash
mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
```
6. **Display summary**
Show archive completion summary including:
- Change name
- Schema that was used
- Archive location
- Spec sync status (synced / sync skipped / no delta specs)
- Note about any warnings (incomplete artifacts/tasks)
**Output On Success**
```markdown
## Archive Complete
**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** the archive path derived from `planningHome.changesDir`/<target-name>/
**Specs:** ✓ Synced to main specs
All artifacts complete. All tasks complete.
```
**Output On Success (No Delta Specs)**
```markdown
## Archive Complete
**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** the archive path derived from `planningHome.changesDir`/<target-name>/
**Specs:** No delta specs
All artifacts complete. All tasks complete.
```
**Output On Success With Warnings**
```markdown
## Archive Complete (with warnings)
**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** the archive path derived from `planningHome.changesDir`/<target-name>/
**Specs:** Sync skipped (user chose to skip)
**Warnings:**
- Archived with 2 incomplete artifacts
- Archived with 3 incomplete tasks
- Delta spec sync was skipped (user chose to skip)
Review the archive if this was not intentional.
```
**Output On Error (Archive Exists)**
```markdown
## Archive Failed
**Change:** <change-name>
**Target:** the archive path derived from `planningHome.changesDir`/<target-name>/
Target archive directory already exists.
**Options:**
1. Rename the existing archive
2. Delete the existing archive if it's a duplicate
3. Wait until a different date to archive
```
**Guardrails**
- Announce the selected change; prompt for selection when it is ambiguous
- Use artifact graph (openspec status --json) for completion checking
- Don't block archive on warnings - just inform and confirm
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
- Show clear summary of what happened
- If sync is requested, run the `/opsx:sync` workflow inline (agent-driven)
- Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving `changeRoot`
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
- Apply relevant runtime context and report conflicts; operation guidance remains advisory
- Consider every guidance entry and explain any inapplicable or conflicting advice
- Existing CLI checks, resolved paths, prompts, and command contracts are unchanged
- Artifact rules constrain only the specs being written and are never operation guidance
- Never copy runtime context, operation guidance, or artifact-rule text verbatim into output files
+193
View File
@@ -0,0 +1,193 @@
---
name: "OPSX: Explore"
description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
allowed-tools: Bash(openspec:*)
category: "Workflow"
tags: ["workflow", "explore", "experimental", "thinking"]
---
Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. For a new change, scaffold it first as described below.
**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
- A vague idea: "real-time collaboration"
- A specific problem: "the auth system is getting unwieldy"
- A change name: "add-dark-mode" (to explore in context of that change)
- A comparison: "postgres vs sqlite for this"
- Nothing (just enter explore mode)
---
## The Stance
- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
- **Adaptive** - Follow interesting threads, pivot when new information emerges
- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
- **Grounded** - Explore the actual codebase when relevant, don't just theorize
---
## What You Might Do
Depending on what the user brings, you might:
**Explore the problem space**
- Ask clarifying questions that emerge from what they said
- Challenge assumptions
- Reframe the problem
- Find analogies
**Investigate the codebase**
- Map existing architecture relevant to the discussion
- Find integration points
- Identify patterns already in use
- Surface hidden complexity
**Compare options**
- Brainstorm multiple approaches
- Build comparison tables
- Sketch tradeoffs
- Recommend a path (if asked)
**Visualize**
```
┌─────────────────────────────────────────┐
│ Use ASCII diagrams liberally │
├─────────────────────────────────────────┤
│ │
│ ┌────────┐ ┌────────┐ │
│ │ State │────────▶│ State │ │
│ │ A │ │ B │ │
│ └────────┘ └────────┘ │
│ │
│ System diagrams, state machines, │
│ data flows, architecture sketches, │
│ dependency graphs, comparison tables │
│ │
└─────────────────────────────────────────┘
```
**Surface risks and unknowns**
- Identify what could go wrong
- Find gaps in understanding
- Suggest spikes or investigations
---
## OpenSpec Awareness
You have full context of the OpenSpec system. Use it naturally, don't force it.
### Check for context
At the start, quickly check what exists:
```bash
openspec list --json
```
This tells you:
- If there are active changes
- Their names, schemas, and status
- What the user might be working on
Then read the project's own context from the resolved root - `<root.path>/openspec/config.yaml` (or `config.yml`). Use the `root.path` returned above, and skip this if neither file exists:
- `context`: project background - tech stack, conventions, constraints
- `rules`: keyed by artifact id - the entries for an artifact apply only when you write that artifact
Ground your thinking in these. They are constraints for you to follow, not content to reproduce: do NOT copy them into the conversation or into any artifact you create.
If the user mentioned a specific change name, read its artifacts for context.
### When no change exists
Think freely. When insights crystallize, you might offer:
- "This feels solid enough to start a change. Want me to create a proposal?"
- Or keep exploring - no pressure to formalize
If the user asks you to capture the exploration as a new change, transition seamlessly into the requested capture:
1. Run `openspec new change "<name>"` (with `--store <id>` when applicable) before creating any artifacts. Never create a new change directory under `openspec/changes/` by hand; the CLI scaffold creates required metadata such as `.openspec.yaml`. Keep the selected `--store <id>` on every applicable follow-up `status` and `instructions` command.
2. Run `openspec status --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store), then process the requested artifacts in dependency order. For each requested artifact that is `ready`, run `openspec instructions "<artifact-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store). Before creating a requested artifact, evaluate any condition in its own `instruction` against the explored change; record a deliberate skip instead when the condition does not apply. If a requested artifact is blocked by a direct prerequisite the user did not request, run `openspec instructions "<prerequisite-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) for that prerequisite whether it is `ready` or `blocked`. If its own `instruction` states a condition, evaluate that condition against the explored change and record a deliberate skip only when the condition does not apply. If the condition applies, or the prerequisite is not conditional, treat it as a normal prerequisite and ask before expanding the capture. Do not create an unrequested prerequisite unless the user approves.
3. Follow the returned `template` and `instruction` fields. Read completed dependency files listed in `dependencies`, and apply `context` and `rules` as constraints without copying them into the artifact. If the instruction delegates creation to a specific skill or command, invoke it; otherwise write the artifact to `resolvedOutputPath`, using the instruction to choose a concrete path when it is a glob. Verify that the selected concrete output exists.
4. After creating each artifact, re-run `openspec status --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) and continue until every requested artifact is `done`, `skipped`, or was deliberately skipped because its own `instruction` stated a condition that did not apply. Tell the user about a deliberate conditional skip, remember it, and do not reconsider it. Dependencies are enablers, not gates: if a requested artifact is still `blocked` only because you deliberately skipped a conditional prerequisite, run `openspec instructions "<artifact-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) despite the blocked status, then create it using step 3 only when those recorded conditional skips are its sole missing dependencies. If a requested artifact is blocked by a prerequisite the user did not ask to capture and cannot be conditionally skipped, explain that dependency and ask before expanding the capture.
Capture the artifact(s) the user requested without asking them to invoke another workflow command. If they asked only to start a change, stop after scaffolding and show its status.
### When a change exists
If the user mentions a change or you detect one is relevant:
1. **Resolve and read existing artifacts for context**
- Run `openspec status --change "<name>" --json`.
- Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
- Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
2. **Reference them naturally in conversation**
- "Your design mentions using Redis, but we just realized SQLite fits better..."
- "The proposal scopes this to premium users, but we're now thinking everyone..."
3. **Offer to capture when decisions are made**
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve an existing capability's full path and follow the project's established organization for new capabilities.
| Insight Type | Where to Capture |
|----------------------------|-------------------------------------|
| New requirement discovered | `specs/<capability-path>/spec.md` |
| Requirement changed | `specs/<capability-path>/spec.md` |
| Design decision made | `design.md` |
| Scope changed | `proposal.md` |
| New work identified | `tasks.md` |
| Assumption invalidated | Relevant artifact |
Example offers:
- "That's a design decision. Capture it in design.md?"
- "This is a new requirement. Add it to specs?"
- "This changes scope. Update the proposal?"
4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
---
## What You Don't Have To Do
- Follow a script
- Ask the same questions every time
- Produce a specific artifact
- Reach a conclusion
- Stay on topic if a tangent is valuable
- Be brief (this is thinking time)
---
## Ending Discovery
There's no required ending. Discovery might:
- **Flow into a proposal**: "Ready to start? I can create a change proposal."
- **Result in artifact updates**: "Updated design.md with these decisions"
- **Just provide clarity**: User has what they need, moves on
- **Continue later**: "We can pick this up anytime"
When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
---
## Guardrails
- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
- **Don't fake understanding** - If something is unclear, dig deeper
- **Don't rush** - Discovery is thinking time, not task time
- **Don't force structure** - Let patterns emerge naturally
- **Don't auto-capture** - Offer to save insights, don't just do it
- **Don't manually scaffold changes** - Never create a new change directory under `openspec/changes/` by hand. Always use `openspec new change "<name>"` (with `--store <id>` when applicable) so required metadata such as `.openspec.yaml` is created before writing artifacts.
- **Do visualize** - A good diagram is worth many paragraphs
- **Do explore the codebase** - Ground discussions in reality
- **Do question assumptions** - Including the user's and your own
+145
View File
@@ -0,0 +1,145 @@
---
name: "OPSX: Propose"
description: "Propose a new change - create it and generate all artifacts in one step"
allowed-tools: Bash(openspec:*)
category: "Workflow"
tags: ["workflow", "artifacts", "experimental"]
---
Propose a new change - create the change and generate all artifacts in one step.
**Planning boundary**: This workflow creates planning artifacts only. The user request that selected or triggered this workflow authorizes planning only, even if it asks to build or fix something. Do not edit project code. After the planning artifacts are complete, stop. Do not start implementation in the same response, even if the initial request asks for it. Wait for a new user request after the artifacts are presented; then start the apply workflow.
I'll create a change with the artifacts your schema defines. With the default spec-driven schema that is:
- proposal.md (what & why)
- `specs/<capability-path>/spec.md` (what the system must do - a delta, not the main spec)
- design.md (how)
- tasks.md (implementation steps)
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve an existing capability's full path and follow the project's established organization for new capabilities.
When the user is ready to implement, they must start the apply workflow explicitly.
---
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
**Steps**
1. **Understand the request and clarify material ambiguity**
If no input is provided, ask the user (open-ended, no preset options):
> "What change do you want to work on? Describe what you want to build or fix."
From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
**IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
If the request contains ambiguity that would materially affect scope, externally observable behavior, compatibility, or acceptance criteria, ask the user before creating the change. For minor details, make a reasonable assumption and record it in the planning artifacts.
2. **Determine the workflow schema**
Use the configured default schema unless the user explicitly requests a different workflow.
**Use a different schema only if the user:**
- Explicitly requests a specific schema by name → use `--schema <schema-name>`
- Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running `openspec context --json` from the current working directory. If the user explicitly selected a registered store, use `openspec context --json --store "<store-id>"`. Then run `openspec schemas --json` with its working directory set to the returned `root.path` and let them choose. This preserves roots selected by a local `store:` pointer or the global `defaultStore`; `schemas` does not accept `--store`. If context reports only `no_openspec_root`, run `openspec schemas --json` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
Otherwise, omit `--schema` to preserve the configured default.
3. **Create the change directory**
Choose one schema form below. If a registered store is selected, append `--store "<store-id>"` to that command and each later OpenSpec command shown below that accepts `--store`.
Using the configured default:
```bash
openspec new change "<name>"
```
Using an explicitly requested schema:
```bash
openspec new change "<name>" --schema "<schema-name>"
```
This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
4. **Get the artifact build order**
```bash
openspec status --change "<name>" --json
```
Parse the JSON to get:
- `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
- `artifacts`: list of all artifacts, each with its `status` and its `requires` edges (the artifact IDs it directly depends on)
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
5. **Create every artifact in the required set**
Use a todo list to track progress through the artifacts.
Loop through artifacts in dependency order (artifacts with no pending dependencies first):
a. **For each artifact that is `ready` (dependencies satisfied)**:
- Get instructions:
```bash
openspec instructions <artifact-id> --change "<name>" --json
```
- The instructions JSON includes:
- `context`: Project background (constraints for you - do NOT include in output)
- `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
- `template`: The structure to use for your output file
- `instruction`: Schema-specific guidance for this artifact type
- `skipped`/`warning`: present when the change declares skip_specs and this artifact must NOT be created - stop and pick another artifact
- `resolvedOutputPath`: Resolved path or pattern to write the artifact
- `dependencies`: Completed artifacts to read for context
- Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
- If the `instruction` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at `resolvedOutputPath`
- Otherwise create the artifact file using `template` as the structure and write it to `resolvedOutputPath`. If `resolvedOutputPath` is a glob, follow `instruction` to choose the concrete file path
- Apply `context` and `rules` as constraints - but do NOT copy them into the file
- Show brief progress: "Created <artifact-id>"
b. **Continue until every artifact in the required set exists (not just `apply.requires`)**
- After creating each artifact, re-run `openspec status --change "<name>" --json`
- The required set is `applyRequires` plus every artifact reachable from those by following the `requires` edges in `status --json` - walk them transitively (spec-driven closes over proposal, specs, design, tasks). Leave artifacts outside that set alone
- `status` is file-existence only, so an `applyRequires` artifact reading `done` does NOT mean its dependencies exist - writing `tasks.md` early marks `tasks` done while `specs` was never written. Use each artifact's `requires` edges, not its `status`, to build the required set: a `done` artifact still lists what it depends on
- An artifact already reading `status: "skipped"` is satisfied: the change declares `skip_specs` in `.openspec.yaml`, so its files must NOT exist. Never try to create one
- Create every artifact in the required set that is missing, then re-check - creating one can unblock others
- Skip one only when `status` already reports it `skipped`, or when its own `instruction` says it is conditional: run `openspec instructions <artifact-id> --change "<name>" --json` and skip only if its `instruction` field marks it optional (e.g. "create only if..."). Spec-driven's `design.md` qualifies; `specs` qualifies only via the `skipped` status above, never by your own judgment. Tell the user, and do not reconsider it
- Dependencies are enablers, not gates: if a required artifact is still `blocked` only because you skipped a conditional dependency, write it anyway
- Stop when every artifact in the required set is `done`, `skipped`, or was deliberately skipped
c. **If an artifact requires user input** (unclear context):
- Ask the user to clarify
- Then continue with creation
6. **Show final status**
```bash
openspec status --change "<name>"
```
**Output**
After completing all artifacts, summarize:
- Change name and location
- List of artifacts created with brief descriptions, plus any conditional artifact you skipped and why
- What's ready: "All artifacts needed for implementation are ready."
- Prompt: "The artifacts are ready for review. When you are ready, run `/opsx:apply`."
**Artifact Creation Guidelines**
- Follow the `instruction` field from `openspec instructions` for each artifact type - it is the authoritative guidance, even for familiar artifact names
- If the `instruction` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly
- The schema defines what each artifact should contain - follow it
- Read dependency artifacts for context before creating new ones
- Use `template` as the structure for your output file - fill in its sections
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
- Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
- These guide what you write, but should never appear in the output
**Guardrails**
- The request that invoked this workflow authorizes planning only. Any implementation or apply instruction in that request does not carry forward. Do NOT implement the change, start the apply workflow, or edit project code during this workflow. After presenting the artifacts, stop and wait for a new user request to start the apply workflow
- Create every artifact the apply phase transitively depends on, not just the ids listed in `apply.requires`
- Always read dependency artifacts before creating a new one - re-read from disk, not from conversation memory (files may have changed since you last saw them)
- Ask about ambiguities that would materially change scope, externally observable behavior, compatibility, or acceptance criteria; for minor details, make reasonable assumptions and record them
- If a change with that name already exists, ask if user wants to continue it or create a new one
- Verify each artifact file exists after writing before proceeding to next
+258
View File
@@ -0,0 +1,258 @@
---
name: "OPSX: Sync"
description: "Sync delta specs from a change to main specs"
allowed-tools: Bash(openspec:*)
category: "Workflow"
tags: ["workflow", "specs", "experimental"]
---
Sync delta specs from a change to main specs.
This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
**Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
When prompting, show changes that have delta specs (under `specs/` directory).
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:sync <other>`).
2. **Resolve change context**
Run:
```bash
openspec status --change "<name>" --json
```
The JSON includes `planningHome.root`. Main specs live under `<planningHome.root>/openspec/specs/` — use that (store-aware) root for every main-spec path below, not a hardcoded repo path. When a store is selected it points at the store, not the current repository.
3. **Find delta specs**
Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the
only source of delta spec paths. If the `specs` entry is missing or
`existingOutputPaths` is empty, report that there are no delta specs to sync,
do not infer them from other artifacts, and stop without requesting artifact
instructions or writing a main spec.
Sync every path in `existingOutputPaths` unless the caller narrowed the set.
A caller narrows it by naming an explicit list of complete entries from
`existingOutputPaths` — copy those absolute values verbatim. Archive does
this inline, and a user can too (for example, by selecting the entry ending
in `/specs/billing/invoices/spec.md`).
Then sync only the named paths and leave the remaining delta specs untouched:
bulk archive excludes a delta whose implementation it could not find, and
syncing it anyway would write a main spec the caller deliberately withheld.
Carry that narrowed selection through step 4; never widen it back to the full
list. If a named path is not in `existingOutputPaths`, do not sync it —
report it and stop, rather than dropping it silently. If the named list is
empty, report that there is nothing to sync and stop without writing a main
spec.
Each delta spec file contains sections like:
- `## ADDED Requirements` - New requirements to add
- `## MODIFIED Requirements` - Changes to existing requirements
- `## REMOVED Requirements` - Requirements to remove
- `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
If no delta specs found, inform user and stop.
4. **For each delta spec, apply changes to main specs**
Before the first main-spec write, obtain one current specs-rule snapshot:
- If archive invoked this workflow inline and supplied a valid snapshot from
`openspec instructions specs --change "<name>" --json`, reuse it and do not
fetch the same instructions again.
- Otherwise run that command once now with the same selected-root flags.
- If the direct lookup exits non-zero or returns invalid artifact-instruction
JSON, report the error and stop before writing any main spec. Do not treat the
failure as an absent rule set.
- A valid response with omitted `rules` means no artifact rules are configured
and the existing semantic merge continues.
Apply returned `rules` only to the content and form of the main specs produced
by this merge. Artifact rules are not operation guidance and cannot change
selected roots, delta paths, CLI checks, or workflow steps. Use their text as
constraints without copying it verbatim into a main spec or summary.
For each capability delta spec path selected in step 3 — the full `existingOutputPaths` list, or the narrowed subset when a caller supplied one (these may belong to a selected store, not the repo):
a. **Read the delta spec** to understand the intended changes
b. **Read the main spec** at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (may not exist yet)
c. **Apply changes intelligently**:
**ADDED Requirements:**
- If requirement doesn't exist in main spec → add it
- If requirement already exists → update it to match (treat as implicit MODIFIED)
**MODIFIED Requirements:**
- Find the requirement in main spec
- Apply the changes - this can be:
- Adding new scenarios the main spec does not have yet
- Modifying existing scenarios
- Changing the requirement description
- Preserve scenarios/content not mentioned in the delta
**REMOVED Requirements:**
- Remove the entire requirement block from main spec
- Retiring the capability. Delete the whole `spec.md` - and the directory once
nothing else is left in it - only when ALL of these hold:
1. removing the requirements *this run* left no requirement blocks;
2. the rest of the spec is well-formed (it still has a `## Purpose`);
3. the main spec was not already empty before this sync - if you removed
nothing, change nothing;
4. every other nonblank line in the whole file is accounted for as the
title, Purpose, Requirements header, or a canonical requirement's
statement, scenarios, or fenced examples;
5. the change's `.openspec.yaml` declares `retire_capabilities: true`;
6. the `spec.md` resolves inside the real specs root (do not follow a
capability-directory symlink to delete an external file).
If removing the selected requirements would leave no requirement blocks and
any retirement condition is not satisfied, do not modify the main spec. Stop
the sync for that capability, report the blocking condition, and tell the user
how to resolve it. Never write or leave an empty `## Requirements` section.
When only the marker is missing, say that too - it is the one thing the user
can add to make the retirement go through.
- Deleting the file also deletes its `## Purpose`; any other section blocks
retirement. Name Purpose when you report the retirement. Include a pasteable
`git checkout` only when the spec lived in the caller's checkout;
otherwise give checkout-scoped recovery guidance.
**RENAMED Requirements:**
- Find the FROM requirement, rename to TO
**`## Purpose` in the delta:**
- The main spec already has one and it is authoritative - leave it alone
(this is what `openspec archive` does; it warns and moves on)
d. **Create new main spec** if capability doesn't exist yet:
- Create `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
- Add Purpose section: copy the delta's `## Purpose` body verbatim when it has one
(this is what `openspec archive` does); only write a brief TBD placeholder when it does not
- Add Requirements section with the ADDED requirements
- Follow the **Main Spec Format Reference** below
5. **Validate updated main specs**
Run `openspec validate --specs` with the same selected-root flags used earlier.
If validation fails, report the problems and do not claim the sync succeeded.
6. **Show summary**
After applying all changes, summarize:
- Which capabilities were updated
- What changes were made (requirements added/modified/removed/renamed)
- Any new main spec left with a TBD Purpose placeholder, so it gets written
now rather than lingering
- Any capability retired, naming the deleted `spec.md`, its Purpose, and
either a pasteable `git checkout` or checkout-scoped recovery guidance
**Delta Spec Format Reference**
```markdown
## Purpose
Only on a delta that introduces a brand-new capability. Seeds the new main spec.
## ADDED Requirements
### Requirement: New Feature
The system SHALL do something new.
#### Scenario: Basic case
- **WHEN** user does X
- **THEN** system does Y
## MODIFIED Requirements
### Requirement: Existing Feature
The system SHALL keep doing the existing thing, now also handling A.
#### Scenario: Scenario the main spec already has
- **WHEN** user does X
- **THEN** system does Y
#### Scenario: New scenario to add
- **WHEN** user does A
- **THEN** system does B
## REMOVED Requirements
### Requirement: Deprecated Feature
## RENAMED Requirements
- FROM: `### Requirement: Old Name`
- TO: `### Requirement: New Name`
```
**Main Spec Format Reference**
Main specs are what the delta merges INTO. They must never contain delta operation headers (`## ADDED/MODIFIED/REMOVED/RENAMED Requirements`) - after syncing, every requirement lives under a single `## Requirements` section:
```markdown
# <capability> Specification
## Purpose
Short description of what this capability does and why it exists.
## Requirements
### Requirement: New Feature
The system SHALL do something new.
#### Scenario: Basic case
- **WHEN** user does X
- **THEN** system does Y
```
**Key Principle: Intelligent Merging**
Unlike programmatic merging, you merge rather than overwrite:
- A MODIFIED block carries the whole requirement - body plus every scenario that survives the change. `openspec validate` and `openspec archive` both reject one that drops a scenario the main spec still has.
- Keep anything the delta does not mention, in the main spec's existing order
- Use your judgment to merge changes sensibly
**Output On Success**
```markdown
## Specs Synced: <change-name>
Updated main specs:
**<capability-1>**:
- Added requirement: "New Feature"
- Modified requirement: "Existing Feature" (added 1 scenario)
**<capability-2>**:
- Created new spec file
- Added requirement: "Another Feature"
Main specs are now updated. The change remains active - archive when implementation is complete.
```
**Guardrails**
- Read both delta and main specs before making changes
- Preserve existing content not mentioned in delta
- Never copy a delta file into a main spec as-is - merge its content so the main spec keeps the Main Spec Format Reference structure, with no delta operation headers
- If something is unclear, ask for clarification
- Show what you're changing as you go
- The operation should be idempotent - running twice should give same result
- Use only `artifactPaths.specs.existingOutputPaths`; never infer delta specs from unrelated artifacts
- Honor a caller-supplied subset of `existingOutputPaths`; never widen it back to the full list
- Fetch specs instructions once for direct sync, or reuse the archive-supplied snapshot inline
- Stop before every main-spec write on a non-zero or invalid JSON specs-instruction response
- Artifact rules constrain only the specs being written and are never copied into output files
+87
View File
@@ -0,0 +1,87 @@
---
name: "OPSX: Update"
description: "Update a change - revise existing planning artifacts and keep them coherent (Experimental)"
allowed-tools: Bash(openspec:*)
category: "Workflow"
tags: ["workflow", "artifacts", "experimental"]
---
Revise a change's existing planning artifacts and keep them coherent. Never edit code.
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
**Input**: Optionally specify a change name after `/opsx:update` (e.g., `/opsx:update add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
`/opsx:continue` is an expanded-profile workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, `openspec status --change "<name>" --json` shows the next artifact and `openspec instructions "<artifact-id>" --change "<name>" --json` explains how to create it.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json` to get available changes sorted by most recently modified, and ask the user to select one
When prompting, present the top 3-4 most recently modified changes as options, showing:
- Change name
- Schema (from `schema` field if present, otherwise "spec-driven")
- Status (e.g., "0/5 tasks", "complete", "no tasks")
- How recently it was modified (from `lastModified` field)
Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:update <other>`).
2. **Get the change's artifacts**
```bash
openspec status --change "<name>" --json
```
Parse the JSON to understand current state. The response includes:
- `schemaName`: The workflow schema being used (e.g., "spec-driven")
- `artifacts`: Array of artifacts with their status ("done", "skipped", "ready", "blocked")
- `isPlanningComplete`: Boolean indicating if all planning artifacts are complete. Older CLI versions expose the same value as `isComplete`.
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
The files to edit are `artifactPaths.<id>.existingOutputPaths` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. `specs/**/*.md`). Do NOT write to `resolvedOutputPath`: for a glob artifact it is still the glob pattern, not a real file.
3. **Understand the request**
- If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
- If they only said "update" / "make this coherent", treat it as a coherence review: read the existing artifacts and check them against each other for contradictions, gaps, and duplication.
4. **Read and reconcile**
- Read the artifact(s) the request touches and the change's other existing artifacts.
- Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
- Note everything that is now inconsistent, missing, or contradictory.
- Revise only files that already exist (`existingOutputPaths`). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to `/opsx:continue` to create them.
- If the change is already coherent, say so and make no edits.
5. **Confirm and apply, one artifact at a time**
- Show each proposed revision and why. Write only after the user confirms.
- If the user rejects a revision, do not write it - leave that artifact unchanged.
- When a substantial rewrite is needed, get that artifact's rules and template first:
```bash
openspec instructions "<artifact-id>" --change "<name>" --json
```
6. **Point to the next step (guidance only - NEVER act on it)**
- Artifacts still missing -> suggest `/opsx:continue` to create them.
- Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest `/opsx:apply` to carry the delta into code.
- Everything done and implemented -> suggest `/opsx:archive`.
**Output**
After each invocation, show:
- Which artifacts were revised (and which proposed revisions were rejected)
- Anything deferred to `/opsx:continue` (not-yet-created artifacts or files)
- Where the change stands and the recommended next command
**Guardrails**
- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to `/opsx:apply`.
- Use the artifact ids and paths reported by `openspec status`; never branch on hardcoded artifact names.
- Edit only the concrete files in `existingOutputPaths`; never write to a glob `resolvedOutputPath`.
- Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is `/opsx:continue`'s job.
- Confirm every edit with the user before writing.
- If the request changes the change's *intent* rather than refining it, first verify whether the expanded-profile `/opsx:new` workflow is available. If it is, recommend starting fresh with `/opsx:new` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend `openspec new change "<new-change-name>"` instead.
+45
View File
@@ -0,0 +1,45 @@
#!/usr/bin/env bash
set -uo pipefail
ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
PAYLOAD=$(cat)
FILE=$(printf '%s' "$PAYLOAD" | /usr/bin/python3 -c 'import json,sys
try:
d = json.load(sys.stdin)
except Exception:
sys.exit(0)
t = d.get("tool_input") or {}
r = d.get("tool_response") or {}
p = r.get("filePath") or t.get("file_path") or ""
print(p)
' 2>/dev/null)
case "$FILE" in
"") exit 0 ;;
*.py) ;;
*) exit 0 ;;
esac
case "$FILE" in
"$ROOT"/src/*) ;;
src/*) FILE="$ROOT/$FILE" ;;
*) exit 0 ;;
esac
[ -f "$FILE" ] || exit 0
[ -x "$ROOT/.venv/bin/ruff" ] || exit 0
OUT=$(
cd "$ROOT" || exit 0
"$ROOT/.venv/bin/ruff" check --fix --quiet "$FILE" 2>&1
"$ROOT/.venv/bin/ruff" format --quiet "$FILE" 2>&1
if [ -x "$ROOT/.venv/bin/ty" ]; then
"$ROOT/.venv/bin/ty" check --quiet "$FILE" 2>&1 | grep -v "^All checks passed" || true
fi
)
if [ -n "$OUT" ]; then
printf 'ruff/ty по %s:\n%s\n' "${FILE#"$ROOT"/}" "$OUT" >&2
exit 2
fi
exit 0
+17
View File
@@ -0,0 +1,17 @@
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit|NotebookEdit",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/lint-python.sh",
"timeout": 60,
"statusMessage": "ruff + ty по src/"
}
]
}
]
}
}
@@ -0,0 +1,185 @@
---
name: openspec-apply-change
description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.8.0"
---
Implement tasks from an OpenSpec change.
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
2. **Check status to understand the schema**
```bash
openspec status --change "<name>" --json
```
Parse the JSON to understand:
- `schemaName`: The workflow being used (e.g., "spec-driven")
- `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
- Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
3. **Get apply instructions**
```bash
openspec instructions apply --change "<name>" --json
```
This returns:
- `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
- Progress (total, complete, remaining)
- Task list with status
- Dynamic instruction based on current state
- Optional `context`: current required project instruction input from the selected root
- Optional `operationGuidance`: current advisory guidance for apply
**Handle states:**
- If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue` (if it is not installed, run `openspec status --change "<name>" --json` to see the next artifact and `openspec instructions <artifact-id> --change "<name>" --json` for how to create it)
- If `state: "all_done"`: congratulate, suggest archive
- Otherwise: proceed to implementation
Treat `context` as a required prompt-level input. Read and consider it, and
apply relevant project facts, conventions, and constraints while implementing.
Treat `operationGuidance` as optional additive advice. Read and consider every
entry, and follow entries that are applicable and compatible with the built-in
workflow.
Keep both fields separate from CLI-returned state, missing artifacts, tasks,
progress, `contextFiles`, and the built-in `instruction`. They are not
evidence of task completion, do not replace the built-in instruction, and do
not permit bypassing a blocked state. If context conflicts with the built-in
instruction, an explicit user choice, or a CLI-controlled value, report the
conflict and preserve the controlling value. If guidance is inapplicable or
conflicts with those controlling inputs, do not follow it and explain why.
These are prompt-level behavior contracts, not enforceable checks.
4. **Read context files**
Read every file path listed under `contextFiles` from the apply instructions output.
The files depend on the schema being used:
- **spec-driven**: proposal, specs, design, tasks
- Other schemas: follow the contextFiles from CLI output
Do not copy `context` or `operationGuidance` verbatim into implementation
files or planning artifacts unless the user separately asks for that content.
5. **Show current progress**
Display:
- Schema being used
- Progress: "N/M tasks complete"
- Remaining tasks overview
- Dynamic instruction from CLI
6. **Implement tasks (loop until done or blocked)**
For each pending task:
- Show which task is being worked on
- Make the code changes required
- Keep changes minimal and focused
- Mark task complete in the tasks file: `- [ ]` → `- [x]`
- Continue to next task
**Pause if:**
- Task is unclear → ask for clarification
- Implementation reveals a design issue → suggest updating artifacts
- Error or blocker encountered → report and wait for guidance
- User interrupts
7. **On completion or pause, show status**
Display:
- Tasks completed this session
- Overall progress: "N/M tasks complete"
- If all done: suggest archive
- If paused: explain why and wait for guidance
**Output During Implementation**
```
## Implementing: <change-name> (schema: <schema-name>)
Working on task 3/7: <task description>
[...implementation happening...]
✓ Task complete
Working on task 4/7: <task description>
[...implementation happening...]
✓ Task complete
```
**Output On Completion**
```
## Implementation Complete
**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 7/7 tasks complete ✓
### Completed This Session
- [x] Task 1
- [x] Task 2
...
All tasks complete! You can archive this change with `/opsx:archive`.
```
**Output On Pause (Issue Encountered)**
```
## Implementation Paused
**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 4/7 tasks complete
### Issue Encountered
<description of the issue>
**Options:**
1. <option 1>
2. <option 2>
3. Other approach
What would you like to do?
```
**Guardrails**
- Keep going through tasks until done or blocked
- Always read context files before starting (from the apply instructions output)
- If task is ambiguous, pause and ask before implementing
- If implementation reveals issues, pause and suggest artifact updates
- Keep code changes minimal and scoped to each task
- Update task checkbox immediately after completing each task
- Pause on errors, blockers, or unclear requirements - don't guess
- Use contextFiles from CLI output, don't assume specific file names
- Do not use context or operation guidance as proof that a task is complete
- Apply relevant project context; report conflicts with controlling workflow inputs
- Consider every guidance entry; explain any inapplicable or conflicting advice
- Do not copy runtime context or operation guidance into implementation files or planning artifacts
- Preserve CLI-controlled blocked/ready/all-done behavior and completion criteria
**Fluid Workflow Integration**
This skill supports the "actions on a change" model:
- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
@@ -0,0 +1,182 @@
---
name: openspec-archive-change
description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.8.0"
---
Archive a completed change in the experimental workflow.
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
When prompting, show only active changes (not already archived).
Include the schema used for each change if available.
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:archive <other>`).
**Load current archive inputs before the existing archive checks:**
After resolving the selected change and planning root, run:
```bash
openspec instructions archive --change "<name>" --json
```
Keep the same selected-root flags on this command. This lookup is advisory and
optional: it only supplies extra prompt inputs, so it must never block archiving.
If it exits non-zero or returns invalid JSON — for example on an older CLI that
does not support this command yet — continue the archive workflow with no
context and no operation guidance. Do not report an error and do not stop.
A successful response may omit both optional fields. Treat `context` as a
required prompt-level input: read and consider it, and apply relevant project
facts, conventions, and constraints. Treat `operationGuidance` as optional
additive advice: read and consider every entry, and follow entries that are
applicable and compatible with the built-in archive workflow.
Keep both fields separate from built-in steps, explicit user choices, resolved
paths, CLI checks, and command contracts. If context conflicts with one of those
controlling inputs, report the conflict and preserve the controlling value. If
guidance is inapplicable or conflicts with a controlling input, do not follow it
and explain why. Do not infer replacement paths, skipped prompts, or flags from
either field, and do not copy their text verbatim into specs, change artifacts,
or archive summaries unless the user separately asks for it. These are
prompt-level behavior contracts, not enforceable checks.
2. **Check artifact completion status**
Run `openspec status --change "<name>" --json` to check artifact completion.
Parse the JSON to understand:
- `schemaName`: The workflow being used
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
- `artifacts`: List of artifacts with their status (`done`, `skipped`, or other)
**If any artifacts are neither `done` nor `skipped`** (skipped artifacts satisfy the requirement - the change declares skip_specs):
- Display warning listing incomplete artifacts
- Ask the user to confirm they want to proceed
- Proceed if user confirms
3. **Check task completion status**
Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
**If incomplete tasks found:**
- Display warning showing count of incomplete tasks
- Ask the user to confirm they want to proceed
- Proceed if user confirms
**If no tasks file exists:** Proceed without task-related warning.
4. **Assess delta spec sync state**
Use `artifactPaths.specs.existingOutputPaths` from status JSON as the only
delta-spec source. If the `specs` entry is missing or
`existingOutputPaths` is empty, proceed without a sync prompt and do not infer
delta specs from other artifacts.
**If delta specs exist:**
- Compare each delta spec with its corresponding main spec at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (use the store-aware `planningHome.root` from step 2, not a hardcoded repo path)
- Determine what changes would be applied (adds, modifications, removals, renames)
- Show a combined summary before prompting
**Prompt options:**
- If changes needed: "Sync now (recommended)", "Archive without syncing"
- If already synced: "Archive now", "Sync anyway", "Cancel"
Route on the answer:
- "Cancel" — stop, do not archive
- "Archive without syncing" or "Archive now" — proceed to archive
- "Sync now" or "Sync anyway" — sync, then verify (below)
- Anything else — ask again rather than archiving
Before a selected sync writes any main spec, run
`openspec instructions specs --change "<name>" --json` once with the same
selected-root flags. Require a zero exit status and valid artifact-instruction
JSON. If the lookup fails or returns invalid JSON, report the error and stop
before writing any main spec or moving the change. A valid response with omitted
`rules` is the no-rules case. Apply returned `rules` only to the content and
form of main specs produced by this merge; do not use them as archive guidance,
change CLI behavior, or copy the rule text into any output file.
Then run the `openspec-sync-specs` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching `specs` instructions again. Do not delegate it to a background task — step 5 would move `changeRoot` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
Then re-run the comparison from the top of this step against every capability that has a delta spec in `artifactPaths.specs.existingOutputPaths` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
- ADDED requirements present
- MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact
- REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving `## Requirements` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
- RENAMED requirements present under the new name and absent under the old one
If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and `changeRoot` is intact, so the user can fix the mismatch or re-run the sync and start the archive again.
5. **Perform the archive**
Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
```bash
mkdir -p "<planningHome.changesDir>/archive"
```
Generate the target name: use the change name as-is when it already starts with a `YYYY-MM-DD-` prefix; otherwise prepend the current date as `YYYY-MM-DD-<change-name>`. Never stack a second date (same rule as `openspec archive`).
**Check if target already exists:**
- If yes: Fail with error, suggest renaming existing archive or using different date
- If no: Move `changeRoot` to the archive directory
```bash
mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
```
6. **Display summary**
Show archive completion summary including:
- Change name
- Schema that was used
- Archive location
- Whether specs were synced (if applicable)
- Note about any warnings (incomplete artifacts/tasks)
**Output On Success**
```markdown
## Archive Complete
**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** the archive path derived from `planningHome.changesDir`/<target-name>/
**Specs:** <"✓ Synced to main specs" only if the step 4 verification passed; otherwise "No delta specs" or "Sync skipped">
<"All artifacts complete. All tasks complete." — or, if archived with warnings, list them instead (e.g. "Archived with 2 incomplete tasks")>
```
**Guardrails**
- Announce the selected change; prompt for selection when it is ambiguous
- Use artifact graph (openspec status --json) for completion checking
- Don't block archive on warnings - just inform and confirm
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
- Show clear summary of what happened
- If sync is requested, run the `openspec-sync-specs` workflow inline (agent-driven)
- Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving `changeRoot`
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
- Apply relevant runtime context and report conflicts; operation guidance remains advisory
- Consider every guidance entry and explain any inapplicable or conflicting advice
- Existing CLI checks, resolved paths, prompts, and command contracts are unchanged
- Artifact rules constrain only the specs being written and are never operation guidance
- Never copy runtime context, operation guidance, or artifact-rule text verbatim into output files
+308
View File
@@ -0,0 +1,308 @@
---
name: openspec-explore
description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.8.0"
---
Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing. For a new change, scaffold it first as described below.
**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
---
## The Stance
- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
- **Adaptive** - Follow interesting threads, pivot when new information emerges
- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
- **Grounded** - Explore the actual codebase when relevant, don't just theorize
---
## What You Might Do
Depending on what the user brings, you might:
**Explore the problem space**
- Ask clarifying questions that emerge from what they said
- Challenge assumptions
- Reframe the problem
- Find analogies
**Investigate the codebase**
- Map existing architecture relevant to the discussion
- Find integration points
- Identify patterns already in use
- Surface hidden complexity
**Compare options**
- Brainstorm multiple approaches
- Build comparison tables
- Sketch tradeoffs
- Recommend a path (if asked)
**Visualize**
```
┌─────────────────────────────────────────┐
│ Use ASCII diagrams liberally │
├─────────────────────────────────────────┤
│ │
│ ┌────────┐ ┌────────┐ │
│ │ State │────────▶│ State │ │
│ │ A │ │ B │ │
│ └────────┘ └────────┘ │
│ │
│ System diagrams, state machines, │
│ data flows, architecture sketches, │
│ dependency graphs, comparison tables │
│ │
└─────────────────────────────────────────┘
```
**Surface risks and unknowns**
- Identify what could go wrong
- Find gaps in understanding
- Suggest spikes or investigations
---
## OpenSpec Awareness
You have full context of the OpenSpec system. Use it naturally, don't force it.
### Check for context
At the start, quickly check what exists:
```bash
openspec list --json
```
This tells you:
- If there are active changes
- Their names, schemas, and status
- What the user might be working on
Then read the project's own context from the resolved root - `<root.path>/openspec/config.yaml` (or `config.yml`). Use the `root.path` returned above, and skip this if neither file exists:
- `context`: project background - tech stack, conventions, constraints
- `rules`: keyed by artifact id - the entries for an artifact apply only when you write that artifact
Ground your thinking in these. They are constraints for you to follow, not content to reproduce: do NOT copy them into the conversation or into any artifact you create.
### When no change exists
Think freely. When insights crystallize, you might offer:
- "This feels solid enough to start a change. Want me to create a proposal?"
- Or keep exploring - no pressure to formalize
If the user asks you to capture the exploration as a new change, transition seamlessly into the requested capture:
1. Run `openspec new change "<name>"` (with `--store <id>` when applicable) before creating any artifacts. Never create a new change directory under `openspec/changes/` by hand; the CLI scaffold creates required metadata such as `.openspec.yaml`. Keep the selected `--store <id>` on every applicable follow-up `status` and `instructions` command.
2. Run `openspec status --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store), then process the requested artifacts in dependency order. For each requested artifact that is `ready`, run `openspec instructions "<artifact-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store). Before creating a requested artifact, evaluate any condition in its own `instruction` against the explored change; record a deliberate skip instead when the condition does not apply. If a requested artifact is blocked by a direct prerequisite the user did not request, run `openspec instructions "<prerequisite-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) for that prerequisite whether it is `ready` or `blocked`. If its own `instruction` states a condition, evaluate that condition against the explored change and record a deliberate skip only when the condition does not apply. If the condition applies, or the prerequisite is not conditional, treat it as a normal prerequisite and ask before expanding the capture. Do not create an unrequested prerequisite unless the user approves.
3. Follow the returned `template` and `instruction` fields. Read completed dependency files listed in `dependencies`, and apply `context` and `rules` as constraints without copying them into the artifact. If the instruction delegates creation to a specific skill or command, invoke it; otherwise write the artifact to `resolvedOutputPath`, using the instruction to choose a concrete path when it is a glob. Verify that the selected concrete output exists.
4. After creating each artifact, re-run `openspec status --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) and continue until every requested artifact is `done`, `skipped`, or was deliberately skipped because its own `instruction` stated a condition that did not apply. Tell the user about a deliberate conditional skip, remember it, and do not reconsider it. Dependencies are enablers, not gates: if a requested artifact is still `blocked` only because you deliberately skipped a conditional prerequisite, run `openspec instructions "<artifact-id>" --change "<name>" --json` (append the confirmed `--store "<id>"` only for a registered standalone store) despite the blocked status, then create it using step 3 only when those recorded conditional skips are its sole missing dependencies. If a requested artifact is blocked by a prerequisite the user did not ask to capture and cannot be conditionally skipped, explain that dependency and ask before expanding the capture.
Capture the artifact(s) the user requested without asking them to invoke another workflow command. If they asked only to start a change, stop after scaffolding and show its status.
### When a change exists
If the user mentions a change or you detect one is relevant:
1. **Resolve and read existing artifacts for context**
- Run `openspec status --change "<name>" --json`.
- Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
- Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
2. **Reference them naturally in conversation**
- "Your design mentions using Redis, but we just realized SQLite fits better..."
- "The proposal scopes this to premium users, but we're now thinking everyone..."
3. **Offer to capture when decisions are made**
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve an existing capability's full path and follow the project's established organization for new capabilities.
| Insight Type | Where to Capture |
|----------------------------|-------------------------------------|
| New requirement discovered | `specs/<capability-path>/spec.md` |
| Requirement changed | `specs/<capability-path>/spec.md` |
| Design decision made | `design.md` |
| Scope changed | `proposal.md` |
| New work identified | `tasks.md` |
| Assumption invalidated | Relevant artifact |
Example offers:
- "That's a design decision. Capture it in design.md?"
- "This is a new requirement. Add it to specs?"
- "This changes scope. Update the proposal?"
4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
---
## What You Don't Have To Do
- Follow a script
- Ask the same questions every time
- Produce a specific artifact
- Reach a conclusion
- Stay on topic if a tangent is valuable
- Be brief (this is thinking time)
---
## Handling Different Entry Points
**User brings a vague idea:**
```
User: I'm thinking about adding real-time collaboration
You: Real-time collab is a big space. Let me think about this...
COLLABORATION SPECTRUM
════════════════════════════════════════════
Awareness Coordination Sync
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│Presence│ │Cursors │ │ CRDT │
│ "3 │ │ Multi │ │Conflict│
│online" │ │ select │ │ free │
└────────┘ └────────┘ └────────┘
│ │ │
trivial moderate complex
Where's your head at?
```
**User brings a specific problem:**
```
User: The auth system is a mess
You: [reads codebase]
┌─────────────────────────────────────────────┐
│ CURRENT AUTH FLOW │
└─────────────────────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Google │ │ GitHub │ │ Email │
│ OAuth │ │ OAuth │ │ Magic │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└─────────────┼─────────────┘
▼
┌───────────┐
│ Session │
└─────┬─────┘
│
▼
┌───────────┐
│ Perms │
└───────────┘
I see three tangles. Which one's burning?
```
**User is stuck mid-implementation:**
```
User: /opsx:explore add-auth-system
The OAuth integration is more complex than expected
You: [reads change artifacts]
You're on task 4: "Implement OAuth flow"
Let me trace what's involved...
[draws diagram, explores options, suggests paths]
Want to update the design to reflect this?
Or add a spike task to investigate?
```
**User wants to compare options:**
```
User: Should we use Postgres or SQLite?
You: Generic answer is boring. What's the context?
User: A CLI tool that tracks local dev environments
You: That changes everything.
┌─────────────────────────────────────────────────┐
│ CLI TOOL DATA STORAGE │
└─────────────────────────────────────────────────┘
Key constraints:
• No daemon running
• Must work offline
• Single user
SQLite Postgres
Deployment embedded ✓ needs server ✗
Offline yes ✓ no ✗
Single file yes ✓ no ✗
SQLite. Not even close.
Unless... is there a sync component?
```
---
## Ending Discovery
There's no required ending. Discovery might:
- **Flow into a proposal**: "Ready to start? I can create a change proposal."
- **Result in artifact updates**: "Updated design.md with these decisions"
- **Just provide clarity**: User has what they need, moves on
- **Continue later**: "We can pick this up anytime"
When it feels like things are crystallizing, you might summarize:
```
## What We Figured Out
**The problem**: [crystallized understanding]
**The approach**: [if one emerged]
**Open questions**: [if any remain]
**Next steps** (if ready):
- Create a change proposal
- Keep exploring: just keep talking
```
But this summary is optional. Sometimes the thinking IS the value.
---
## Guardrails
- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
- **Don't fake understanding** - If something is unclear, dig deeper
- **Don't rush** - Discovery is thinking time, not task time
- **Don't force structure** - Let patterns emerge naturally
- **Don't auto-capture** - Offer to save insights, don't just do it
- **Don't manually scaffold changes** - Never create a new change directory under `openspec/changes/` by hand. Always use `openspec new change "<name>"` (with `--store <id>` when applicable) so required metadata such as `.openspec.yaml` is created before writing artifacts.
- **Do visualize** - A good diagram is worth many paragraphs
- **Do explore the codebase** - Ground discussions in reality
- **Do question assumptions** - Including the user's and your own
+149
View File
@@ -0,0 +1,149 @@
---
name: openspec-propose
description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.8.0"
---
Propose a new change - create the change and generate all artifacts in one step.
**Planning boundary**: This workflow creates planning artifacts only. The user request that selected or triggered this workflow authorizes planning only, even if it asks to build or fix something. Do not edit project code. After the planning artifacts are complete, stop. Do not start implementation in the same response, even if the initial request asks for it. Wait for a new user request after the artifacts are presented; then start the apply workflow.
I'll create a change with the artifacts your schema defines. With the default spec-driven schema that is:
- proposal.md (what & why)
- `specs/<capability-path>/spec.md` (what the system must do - a delta, not the main spec)
- design.md (how)
- tasks.md (implementation steps)
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve an existing capability's full path and follow the project's established organization for new capabilities.
When the user is ready to implement, they must start the apply workflow explicitly.
---
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
**Steps**
1. **Understand the request and clarify material ambiguity**
If no clear input is provided, ask the user (open-ended, no preset options):
> "What change do you want to work on? Describe what you want to build or fix."
From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
**IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
If the request contains ambiguity that would materially affect scope, externally observable behavior, compatibility, or acceptance criteria, ask the user before creating the change. For minor details, make a reasonable assumption and record it in the planning artifacts.
2. **Determine the workflow schema**
Use the configured default schema unless the user explicitly requests a different workflow.
**Use a different schema only if the user:**
- Explicitly requests a specific schema by name → use `--schema <schema-name>`
- Asks to "show workflows" or asks "what workflows" exist → resolve the authoritative root by running `openspec context --json` from the current working directory. If the user explicitly selected a registered store, use `openspec context --json --store "<store-id>"`. Then run `openspec schemas --json` with its working directory set to the returned `root.path` and let them choose. This preserves roots selected by a local `store:` pointer or the global `defaultStore`; `schemas` does not accept `--store`. If context reports only `no_openspec_root`, run `openspec schemas --json` from the current working directory instead. Do not use this fallback for invalid or unavailable stores.
Otherwise, omit `--schema` to preserve the configured default.
3. **Create the change directory**
Choose one schema form below. If a registered store is selected, append `--store "<store-id>"` to that command and each later OpenSpec command shown below that accepts `--store`.
Using the configured default:
```bash
openspec new change "<name>"
```
Using an explicitly requested schema:
```bash
openspec new change "<name>" --schema "<schema-name>"
```
This creates a scaffolded change in the planning home resolved by the CLI with `.openspec.yaml`.
4. **Get the artifact build order**
```bash
openspec status --change "<name>" --json
```
Parse the JSON to get:
- `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
- `artifacts`: list of all artifacts, each with its `status` and its `requires` edges (the artifact IDs it directly depends on)
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
5. **Create every artifact in the required set**
Use a todo list to track progress through the artifacts.
Loop through artifacts in dependency order (artifacts with no pending dependencies first):
a. **For each artifact that is `ready` (dependencies satisfied)**:
- Get instructions:
```bash
openspec instructions <artifact-id> --change "<name>" --json
```
- The instructions JSON includes:
- `context`: Project background (constraints for you - do NOT include in output)
- `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
- `template`: The structure to use for your output file
- `instruction`: Schema-specific guidance for this artifact type
- `skipped`/`warning`: present when the change declares skip_specs and this artifact must NOT be created - stop and pick another artifact
- `resolvedOutputPath`: Resolved path or pattern to write the artifact
- `dependencies`: Completed artifacts to read for context
- Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
- If the `instruction` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at `resolvedOutputPath`
- Otherwise create the artifact file using `template` as the structure and write it to `resolvedOutputPath`. If `resolvedOutputPath` is a glob, follow `instruction` to choose the concrete file path
- Apply `context` and `rules` as constraints - but do NOT copy them into the file
- Show brief progress: "Created <artifact-id>"
b. **Continue until every artifact in the required set exists (not just `apply.requires`)**
- After creating each artifact, re-run `openspec status --change "<name>" --json`
- The required set is `applyRequires` plus every artifact reachable from those by following the `requires` edges in `status --json` - walk them transitively (spec-driven closes over proposal, specs, design, tasks). Leave artifacts outside that set alone
- `status` is file-existence only, so an `applyRequires` artifact reading `done` does NOT mean its dependencies exist - writing `tasks.md` early marks `tasks` done while `specs` was never written. Use each artifact's `requires` edges, not its `status`, to build the required set: a `done` artifact still lists what it depends on
- An artifact already reading `status: "skipped"` is satisfied: the change declares `skip_specs` in `.openspec.yaml`, so its files must NOT exist. Never try to create one
- Create every artifact in the required set that is missing, then re-check - creating one can unblock others
- Skip one only when `status` already reports it `skipped`, or when its own `instruction` says it is conditional: run `openspec instructions <artifact-id> --change "<name>" --json` and skip only if its `instruction` field marks it optional (e.g. "create only if..."). Spec-driven's `design.md` qualifies; `specs` qualifies only via the `skipped` status above, never by your own judgment. Tell the user, and do not reconsider it
- Dependencies are enablers, not gates: if a required artifact is still `blocked` only because you skipped a conditional dependency, write it anyway
- Stop when every artifact in the required set is `done`, `skipped`, or was deliberately skipped
c. **If an artifact requires user input** (unclear context):
- Ask the user to clarify
- Then continue with creation
6. **Show final status**
```bash
openspec status --change "<name>"
```
**Output**
After completing all artifacts, summarize:
- Change name and location
- List of artifacts created with brief descriptions, plus any conditional artifact you skipped and why
- What's ready: "All artifacts needed for implementation are ready."
- Prompt: "The artifacts are ready for review. When you are ready, run `/opsx:apply` or ask me to apply this change."
**Artifact Creation Guidelines**
- Follow the `instruction` field from `openspec instructions` for each artifact type - it is the authoritative guidance, even for familiar artifact names
- If the `instruction` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly
- The schema defines what each artifact should contain - follow it
- Read dependency artifacts for context before creating new ones
- Use `template` as the structure for your output file - fill in its sections
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
- Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
- These guide what you write, but should never appear in the output
**Guardrails**
- The request that invoked this workflow authorizes planning only. Any implementation or apply instruction in that request does not carry forward. Do NOT implement the change, start the apply workflow, or edit project code during this workflow. After presenting the artifacts, stop and wait for a new user request to start the apply workflow
- Create every artifact the apply phase transitively depends on, not just the ids listed in `apply.requires`
- Always read dependency artifacts before creating a new one - re-read from disk, not from conversation memory (files may have changed since you last saw them)
- Ask about ambiguities that would materially change scope, externally observable behavior, compatibility, or acceptance criteria; for minor details, make reasonable assumptions and record them
- If a change with that name already exists, ask if user wants to continue it or create a new one
- Verify each artifact file exists after writing before proceeding to next
+262
View File
@@ -0,0 +1,262 @@
---
name: openspec-sync-specs
description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.8.0"
---
Sync delta specs from a change to main specs.
This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
When prompting, show changes that have delta specs (under `specs/` directory).
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:sync <other>`).
2. **Resolve change context**
Run:
```bash
openspec status --change "<name>" --json
```
The JSON includes `planningHome.root`. Main specs live under `<planningHome.root>/openspec/specs/` — use that (store-aware) root for every main-spec path below, not a hardcoded repo path. When a store is selected it points at the store, not the current repository.
3. **Find delta specs**
Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the
only source of delta spec paths. If the `specs` entry is missing or
`existingOutputPaths` is empty, report that there are no delta specs to sync,
do not infer them from other artifacts, and stop without requesting artifact
instructions or writing a main spec.
Sync every path in `existingOutputPaths` unless the caller narrowed the set.
A caller narrows it by naming an explicit list of complete entries from
`existingOutputPaths` — copy those absolute values verbatim. Archive does
this inline, and a user can too (for example, by selecting the entry ending
in `/specs/billing/invoices/spec.md`).
Then sync only the named paths and leave the remaining delta specs untouched:
bulk archive excludes a delta whose implementation it could not find, and
syncing it anyway would write a main spec the caller deliberately withheld.
Carry that narrowed selection through step 4; never widen it back to the full
list. If a named path is not in `existingOutputPaths`, do not sync it —
report it and stop, rather than dropping it silently. If the named list is
empty, report that there is nothing to sync and stop without writing a main
spec.
Each delta spec file contains sections like:
- `## ADDED Requirements` - New requirements to add
- `## MODIFIED Requirements` - Changes to existing requirements
- `## REMOVED Requirements` - Requirements to remove
- `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
If no delta specs found, inform user and stop.
4. **For each delta spec, apply changes to main specs**
Before the first main-spec write, obtain one current specs-rule snapshot:
- If archive invoked this workflow inline and supplied a valid snapshot from
`openspec instructions specs --change "<name>" --json`, reuse it and do not
fetch the same instructions again.
- Otherwise run that command once now with the same selected-root flags.
- If the direct lookup exits non-zero or returns invalid artifact-instruction
JSON, report the error and stop before writing any main spec. Do not treat the
failure as an absent rule set.
- A valid response with omitted `rules` means no artifact rules are configured
and the existing semantic merge continues.
Apply returned `rules` only to the content and form of the main specs produced
by this merge. Artifact rules are not operation guidance and cannot change
selected roots, delta paths, CLI checks, or workflow steps. Use their text as
constraints without copying it verbatim into a main spec or summary.
For each capability delta spec path selected in step 3 — the full `existingOutputPaths` list, or the narrowed subset when a caller supplied one (these may belong to a selected store, not the repo):
a. **Read the delta spec** to understand the intended changes
b. **Read the main spec** at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (may not exist yet)
c. **Apply changes intelligently**:
**ADDED Requirements:**
- If requirement doesn't exist in main spec → add it
- If requirement already exists → update it to match (treat as implicit MODIFIED)
**MODIFIED Requirements:**
- Find the requirement in main spec
- Apply the changes - this can be:
- Adding new scenarios the main spec does not have yet
- Modifying existing scenarios
- Changing the requirement description
- Preserve scenarios/content not mentioned in the delta
**REMOVED Requirements:**
- Remove the entire requirement block from main spec
- Retiring the capability. Delete the whole `spec.md` - and the directory once
nothing else is left in it - only when ALL of these hold:
1. removing the requirements *this run* left no requirement blocks;
2. the rest of the spec is well-formed (it still has a `## Purpose`);
3. the main spec was not already empty before this sync - if you removed
nothing, change nothing;
4. every other nonblank line in the whole file is accounted for as the
title, Purpose, Requirements header, or a canonical requirement's
statement, scenarios, or fenced examples;
5. the change's `.openspec.yaml` declares `retire_capabilities: true`;
6. the `spec.md` resolves inside the real specs root (do not follow a
capability-directory symlink to delete an external file).
If removing the selected requirements would leave no requirement blocks and
any retirement condition is not satisfied, do not modify the main spec. Stop
the sync for that capability, report the blocking condition, and tell the user
how to resolve it. Never write or leave an empty `## Requirements` section.
When only the marker is missing, say that too - it is the one thing the user
can add to make the retirement go through.
- Deleting the file also deletes its `## Purpose`; any other section blocks
retirement. Name Purpose when you report the retirement. Include a pasteable
`git checkout` only when the spec lived in the caller's checkout;
otherwise give checkout-scoped recovery guidance.
**RENAMED Requirements:**
- Find the FROM requirement, rename to TO
**`## Purpose` in the delta:**
- The main spec already has one and it is authoritative - leave it alone
(this is what `openspec archive` does; it warns and moves on)
d. **Create new main spec** if capability doesn't exist yet:
- Create `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
- Add Purpose section: copy the delta's `## Purpose` body verbatim when it has one
(this is what `openspec archive` does); only write a brief TBD placeholder when it does not
- Add Requirements section with the ADDED requirements
- Follow the **Main Spec Format Reference** below
5. **Validate updated main specs**
Run `openspec validate --specs` with the same selected-root flags used earlier.
If validation fails, report the problems and do not claim the sync succeeded.
6. **Show summary**
After applying all changes, summarize:
- Which capabilities were updated
- What changes were made (requirements added/modified/removed/renamed)
- Any new main spec left with a TBD Purpose placeholder, so it gets written
now rather than lingering
- Any capability retired, naming the deleted `spec.md`, its Purpose, and
either a pasteable `git checkout` or checkout-scoped recovery guidance
**Delta Spec Format Reference**
```markdown
## Purpose
Only on a delta that introduces a brand-new capability. Seeds the new main spec.
## ADDED Requirements
### Requirement: New Feature
The system SHALL do something new.
#### Scenario: Basic case
- **WHEN** user does X
- **THEN** system does Y
## MODIFIED Requirements
### Requirement: Existing Feature
The system SHALL keep doing the existing thing, now also handling A.
#### Scenario: Scenario the main spec already has
- **WHEN** user does X
- **THEN** system does Y
#### Scenario: New scenario to add
- **WHEN** user does A
- **THEN** system does B
## REMOVED Requirements
### Requirement: Deprecated Feature
## RENAMED Requirements
- FROM: `### Requirement: Old Name`
- TO: `### Requirement: New Name`
```
**Main Spec Format Reference**
Main specs are what the delta merges INTO. They must never contain delta operation headers (`## ADDED/MODIFIED/REMOVED/RENAMED Requirements`) - after syncing, every requirement lives under a single `## Requirements` section:
```markdown
# <capability> Specification
## Purpose
Short description of what this capability does and why it exists.
## Requirements
### Requirement: New Feature
The system SHALL do something new.
#### Scenario: Basic case
- **WHEN** user does X
- **THEN** system does Y
```
**Key Principle: Intelligent Merging**
Unlike programmatic merging, you merge rather than overwrite:
- A MODIFIED block carries the whole requirement - body plus every scenario that survives the change. `openspec validate` and `openspec archive` both reject one that drops a scenario the main spec still has.
- Keep anything the delta does not mention, in the main spec's existing order
- Use your judgment to merge changes sensibly
**Output On Success**
```markdown
## Specs Synced: <change-name>
Updated main specs:
**<capability-1>**:
- Added requirement: "New Feature"
- Modified requirement: "Existing Feature" (added 1 scenario)
**<capability-2>**:
- Created new spec file
- Added requirement: "Another Feature"
Main specs are now updated. The change remains active - archive when implementation is complete.
```
**Guardrails**
- Read both delta and main specs before making changes
- Preserve existing content not mentioned in delta
- Never copy a delta file into a main spec as-is - merge its content so the main spec keeps the Main Spec Format Reference structure, with no delta operation headers
- If something is unclear, ask for clarification
- Show what you're changing as you go
- The operation should be idempotent - running twice should give same result
- Use only `artifactPaths.specs.existingOutputPaths`; never infer delta specs from unrelated artifacts
- Honor a caller-supplied subset of `existingOutputPaths`; never widen it back to the full list
- Fetch specs instructions once for direct sync, or reuse the archive-supplied snapshot inline
- Stop before every main-spec write on a non-zero or invalid JSON specs-instruction response
- Artifact rules constrain only the specs being written and are never copied into output files
@@ -0,0 +1,91 @@
---
name: openspec-update-change
description: Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Never edits code.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.8.0"
---
Revise a change's existing planning artifacts and keep them coherent. Never edit code.
**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`, `view`). Once selected, treat `--store <id>` as sticky for the rest of the workflow. Every unscoped example of those commands below is shorthand: before running it, append the flag. For example, run `openspec status --change "<name>" --json --store "<id>"`, not the unscoped form shown below. Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
`/opsx:continue` is an expanded-profile workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, `openspec status --change "<name>" --json` shows the next artifact and `openspec instructions "<artifact-id>" --change "<name>" --json` explains how to create it.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json` to get available changes sorted by most recently modified, and ask the user to select one
When prompting, present the top 3-4 most recently modified changes as options, showing:
- Change name
- Schema (from `schema` field if present, otherwise "spec-driven")
- Status (e.g., "0/5 tasks", "complete", "no tasks")
- How recently it was modified (from `lastModified` field)
Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to update.
Always announce: "Using change: <name>" and how to override (e.g., `/opsx:update <other>`).
2. **Get the change's artifacts**
```bash
openspec status --change "<name>" --json
```
Parse the JSON to understand current state. The response includes:
- `schemaName`: The workflow schema being used (e.g., "spec-driven")
- `artifacts`: Array of artifacts with their status ("done", "skipped", "ready", "blocked")
- `isPlanningComplete`: Boolean indicating if all planning artifacts are complete. Older CLI versions expose the same value as `isComplete`.
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
The files to edit are `artifactPaths.<id>.existingOutputPaths` - the concrete files that exist on disk, already glob-expanded for glob artifacts (e.g. `specs/**/*.md`). Do NOT write to `resolvedOutputPath`: for a glob artifact it is still the glob pattern, not a real file.
3. **Understand the request**
- If the user asked for a specific revision ("the design now uses X"), that is the starting edit.
- If they only said "update" / "make this coherent", treat it as a coherence review: read the existing artifacts and check them against each other for contradictions, gaps, and duplication.
4. **Read and reconcile**
- Read the artifact(s) the request touches and the change's other existing artifacts.
- Apply the requested edit. Then check every other existing artifact against it - in ANY direction: an edit to a later artifact may require revising an earlier one, not only the other way around. Build order is a useful reading order, not a constraint on which artifacts may be revised.
- Note everything that is now inconsistent, missing, or contradictory.
- Revise only files that already exist (`existingOutputPaths`). Do NOT create artifacts that don't exist yet, and do NOT invent new files under a glob artifact - note them and point the user to `/opsx:continue` to create them.
- If the change is already coherent, say so and make no edits.
5. **Confirm and apply, one artifact at a time**
- Show each proposed revision and why. Write only after the user confirms.
- If the user rejects a revision, do not write it - leave that artifact unchanged.
- When a substantial rewrite is needed, get that artifact's rules and template first:
```bash
openspec instructions "<artifact-id>" --change "<name>" --json
```
6. **Point to the next step (guidance only - NEVER act on it)**
- Artifacts still missing -> suggest `/opsx:continue` to create them.
- Change already implemented (tasks checked off / already applied) -> the code may no longer match the revised plan; suggest `/opsx:apply` to carry the delta into code.
- Everything done and implemented -> suggest `/opsx:archive`.
**Output**
After each invocation, show:
- Which artifacts were revised (and which proposed revisions were rejected)
- Anything deferred to `/opsx:continue` (not-yet-created artifacts or files)
- Where the change stands and the recommended next command
**Guardrails**
- Planning artifacts only - NEVER edit implementation code. If the revised plan implies code changes, stop and point to `/opsx:apply`.
- Use the artifact ids and paths reported by `openspec status`; never branch on hardcoded artifact names.
- Edit only the concrete files in `existingOutputPaths`; never write to a glob `resolvedOutputPath`.
- Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is `/opsx:continue`'s job.
- Confirm every edit with the user before writing.
- If the request changes the change's *intent* rather than refining it, first verify whether the expanded-profile `/opsx:new` workflow is available. If it is, recommend starting fresh with `/opsx:new` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend `openspec new change "<new-change-name>"` instead.
+8
View File
@@ -30,3 +30,11 @@ coverage/
.vscode/
# Keep small, sanitized evidence summaries in evidence/ under version control.
# Inspect git diff --cached: ignore rules are not a secret scanner.
# Тулчейн студенческой реализации
.pytest_cache/
.ruff_cache/
.ty_cache/
# Локальные настройки агента
.claude/settings.local.json
+57
View File
@@ -0,0 +1,57 @@
## Что это за репозиторий
Skeleton лабораторной 3 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение в ветке `solution/bpi2303-kostylev`. Skeleton даёт задание (`README.md`), нормативный контракт (`contracts/`) и публичные black-box проверки (`tests/`). Реализация API, Dockerfile, compose-стенд, конфигурация балансировщика, миграции, хуки отказов и собственные тесты — студенческие; решение лабы 3 построено переносом решения лабы 2.
Лаба 3: несколько взаимозаменяемых реплик API за единой точкой входа — **HAProxy**. Реплики не держат состояния: PostgreSQL остаётся источником истины для пользователей, сессий, чатов и сообщений, Valkey — общий кэш сессий. Каждый ответ API несёт `X-Instance-Id` обслужившей реплики, отправка сообщения требует `Idempotency-Key`, а повтор с тем же ключом через любую реплику не создаёт дубль. Остановка одной реплики не прерывает чтение и запись дольше 10 с.
## Команды
```sh
make check # offline: структура skeleton, JSON, локальные $ref, синтаксис Python, X-Instance-Id в контракте
make validate PYTHON=.venv/bin/python # полная валидация OpenAPI 3.1 (venv с requirements-dev.txt)
make install # uv sync --group dev
make lint # ruff check + ruff format --check + ty check; обязательно перед commit
make student-test # собственные тесты (поднимают одноразовые PostgreSQL и Valkey в Docker)
make secrets # локальные secrets/* и .env из .env.example (не коммитятся)
make up # docker compose up -d --build --wait: postgres, valkey, migrate, api ×API_REPLICAS, lb
make test # публичный smoke через LB (BASE_URL, по умолчанию http://localhost:8080)
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт lb, api, postgres, valkey с сохранением volumes
make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановка реплики TARGET_INSTANCE_ID под запросами
make restore # вернуть остановленные реплики и дождаться их в ротации LB
make lb-check # ≥2 X-Instance-Id на одном токене и гонка одного Idempotency-Key
make down # остановка без удаления данных; make reset-data — намеренное удаление volumes
```
`tests/*.py` и `scripts/*.py` — только stdlib, синтаксис Python 3.9 (`make check` разбирает их системным `python3`). Проверки сами не поднимают стенд. Хуки `scripts/stop-one.sh` и `scripts/restart.sh` запускаются тестом без shell, поэтому исполняемые и с shebang. Данные не удаляются автоматически: каждый прогон smoke создаёт новых синтетических пользователей.
## Архитектура skeleton
- `lab.json` — единственный источник номера лабы (3). От него зависят `scripts/check_contract.py` (`info.version == 1.3.0`, `X-Instance-Id` во всех ответах) и `tests/client.py` (с lab3 проверяет непустой `X-Instance-Id` на любом ответе и шлёт `Idempotency-Key` в каждом POST сообщения).
- `tests/resilience.py --mode failover`: `TARGET_INSTANCE_ID` — реплика, обслужившая первое сообщение; 40 `GET /users/me` одним токеном должны дать ≥2 `X-Instance-Id`; hook возвращается <10 с с кодом 0; первая запись после hook — не позже 10 с от его старта; ≥5 записей после; target отсутствует в последних 5 ответах; история без дублей и байт-в-байт равна подтверждённым ответам. Таймаут клиента 2 с, после ошибки повтор с тем же ключом и текстом.
- `tests/resilience.py --mode persistence`: hook ≤90 с, затем `/health/ready` и `/users/me` прежним токеном до 90 с, сверка истории.
- `contracts/infrastructure.json` — роли `api` (≥2, без локального состояния), `postgres` (persistent volume), `load_balancer` (единственная публичная точка, readiness backend), опциональный `redis_or_valkey`. `compose.example.yaml` — только worksheet ролей.
## Ключевые правила контракта (lab3)
- `X-Instance-Id` и `X-Request-Id` — на каждом ответе API, включая health, `204` logout, `404/405` неизвестного маршрута и `500`. `X-Instance-Id` один на реплику (контейнер), стабилен на жизнь процесса и одинаков у всех воркеров gunicorn. Ответы, сгенерированные самим LB, его могут не иметь.
- `POST /api/v1/chats/{chat_id}/messages` требует `Idempotency-Key` (`^[A-Za-z0-9._:-]{1,128}$`); нет или неверный — `400`. Область ключа — пользователь + метод + путь + ключ, результат хранится ≥24 ч (`IDEMPOTENCY_TTL_SECONDS`). Повтор того же JSON — тот же `201` и тот же `Message` (включая строку `created_at`), другой JSON — `409`. Повтор заново проверяет сессию (`401`) и доступ (`404`). Сохраняется только `201`; запись сообщения и ключа — одна транзакция PostgreSQL.
- LB и клиент не повторяют прозрачно `POST /users` и `POST /chats`. Балансировка без sticky-сессий.
- Сохраняются правила lab2: `Basic` только на `POST /api/v1/auth/sessions`, иначе `Bearer`; `WWW-Authenticate` по пути; `X-User-Id` игнорируется; logout `204`, повтор `401`; абсолютный TTL сессии. И lab1: формат ошибки `{"error":{code,message,request_id}}`, посторонний → `404`, keyset `(created_at, id)`, `limit` 1–100, cursor привязан к чату, время RFC 3339 с `Z`.
## Правила работы с репозиторием
- Не менять и не ослаблять `contracts/`, `tests/`, `README.md`, `COURSE.md`, рубрику. Расхождение оформляется вопросом преподавателю.
- Код — `src/messenger/`, миграции — `src/messenger/migrations/NNNN_*.sql`, конфигурация LB и нагрузки — `infra/`, хуки и обвязка стенда — `scripts/`, собственные тесты — `student-tests/`, обезличенные доказательства — `evidence/`.
- Без комментариев в коде; отступы — пробелы (`[tool.ruff.format]`); Python 3.14 без `from __future__ import annotations` и `TYPE_CHECKING`.
- Порты реплик API наружу не публикуются: только LB. Нет `container_name`, `hostname` и общего `INSTANCE_ID` у сервиса `api`.
- `REPORT.md`: команды из чистого clone, архитектура, таблица «критерий → команда → наблюдение → файл», таблица отказов. PASS без команды не доказательство; для отказов — какой контейнер реально остановлен (`docker ps -a`).
- Ветка `solution/bpi2303-kostylev`, коммиты на английском, перед каждым — `make lint`. Никогда не коммитить `.env`, `secrets/`, токены, volumes, дампы.
## Уровни оценки
Решение заявлено на **«5»** с треком 1 «Цена масштабирования»; таблица доказательств — в `REPORT.md`.
- **3** — стенд в `compose.yaml`: HAProxy → ≥2 реплики API → общие PostgreSQL и Valkey; разные реплики на одном токене; остановка любой реплики с восстановлением ≤10 с; идемпотентная отправка, включая конкурентный повтор и смену реплики; `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`; минимум lab2 сохранён.
- **4** — согласованные readiness, таймауты и `SIGTERM`, период проверок и время обнаружения; поочерёдная остановка каждой реплики под нагрузкой с RPS, ошибками и временем восстановления; лимиты CPU/RAM, API без опубликованных портов; rolling update под нагрузкой и однократные совместимые миграции.
- **5** — трек 1: 1/2/4 реплики при фиксированном бюджете CPU/RAM и серия с ростом ресурсов, saturation point БД/LB/пула, графики и одно подтверждённое улучшение.
@@ -0,0 +1,4 @@
schema: spec-driven
created: 2026-09-29
archived: 2026-09-29
lab: 1
@@ -0,0 +1,177 @@
## Context
См. `proposal.md` — Why. Ограничения, формирующие подход:
- Состояние живёт только в памяти одного процесса. Это не временное упрощение, а условие лабы: репозиторий не прячет БД, он прячет её отсутствие.
- Публичный `tests/smoke.py` сверяет порядок истории с `sorted(key=(created_at, UUID(id).int))`. Любая неоднозначность порядка при равных отметках времени ломает проверку пагинации.
- Проверки идут в порядке «идентификация → доступ → содержимое»: посторонний с некорректным телом обязан получить `404`, а не `400`.
- Домен лабы 1 беден: три сущности, пять правил. По книге (с. 71) это ровно тот случай, когда весь аппарат не окупается. Он вводится сознательно как учебная цель курса и как задел на лабы 2–7, где за теми же портами встанут PostgreSQL, Redis, S3 и брокер. Цена названа в разделе «Risks».
- Это монолит, а не набор служб: один процесс, одна точка входа, один образ. Разделение на доменные зоны — способ удержать границы внутри монолита, а не подготовка к немедленному разъезду по репозиториям.
## Goals / Non-Goals
**Goals:**
- Правило зависимостей соблюдается механически: `domain/` не импортирует ничего инфраструктурного, `application/` знает только порты, адаптеры подключаются в единственной точке сборки.
- Границы доменных зон проверяются тестом по графу импортов, а не держатся на дисциплине.
- Порядок истории строго определён при конкурентной записи, без сортировки на чтении.
- Замена in-memory адаптеров на адаптеры лаб 2–5 не требует правок в `domain/` и `application/`.
- Режим блокировки хранилища и вариант конвейера запроса переключаются конфигурацией — это измерительные инструменты трека «5», а не мёртвый код.
**Non-Goals:**
- Не вводится ORM, миграции и слой представлений поверх SQL — их нечем наполнить.
- Не вводится оптимистическая блокировка по номеру версии: конкурентная запись идёт только в append-only историю, конфликт обновления невозможен.
- Не строится обобщённый механизм повторов и dead-letter: события лабы 1 не переживают процесс по условию.
- Зоны не разносятся по процессам и образам: это остаётся монолитом, а разделение существует внутри него.
## Decisions
### Две доменные зоны и общий минимум
```
src/messenger/
main.py сборка приложения: вклады зон в один процесс
gunicorn_conf.py конфигурация сервера
identity/ domain (ошибки, события, значения, User) / application / infrastructure /
entrypoints (роутер, провайдер DI, отображение ошибок, журнал, идентификация)
messaging/ domain (ошибки, события, значения, ключ истории, агрегат Chat) /
application / infrastructure (память, курсор) / config /
entrypoints (роутеры, провайдер DI, отображение ошибок, журнал)
shared/ domain / application / infrastructure — платформа без транспорта
entrypoints/ — транспортная платформа: конвейер, health, актор запроса,
механизм ответа об ошибке, транспортные настройки, платформенный провайдер
```
Отдельного каталога точек входа на верхнем уровне нет: правило «общее — в `shared/`, доменное — в зону» не допускает второго места для общего кода. Транспортная платформа — общее, поэтому живёт в `shared/entrypoints/`. Сборка — ни то ни другое, поэтому лежит в `main.py` в корне пакета.
Правило простое: **ошибки, события и команды принадлежат зоне**. Общих доменных понятий не существует — в `shared/` лежат только их базовые типы, нужные шине, чтобы уметь их переносить.
Границы зон взяты по ресурсным корням API: `/api/v1/users` — одна зона, `/api/v1/chats` вместе с историей — другая. Сообщения отдельной зоной не выделены: у них нет жизненного цикла вне чата, это сущность внутри агрегата `Chat`.
Внутри зоны каталоги повторяют словарь книги («Порты и адаптеры», гл. 13). Порт объявляется в `application/ports.py` своей зоны, адаптеры лежат в её `infrastructure/`. Точка сборки одна — `entrypoints/api/ioc.py`, где каждая зона представлена своим провайдером.
`shared/` — крайняя мера: туда попадает только платформа (часы, идентификаторы, журнал, брокер) и механизм связи (шина, базовые типы сообщений). Проверка простая: ни один файл в `shared/` не упоминает ни одну зону, и это закреплено тестом.
Отдельно вынесены из домена коды контракта. Раньше `DomainError` нёс поля `code` и `http_status` — словарь протокола, протёкший в доменный слой. Теперь домен кидает свою ошибку (`UsernameAlreadyTaken`, `ChatNotFound`, `InvalidPageRequest`), а таблица перевода в коды контракта живёт в точке входа. Домен ничего не знает про HTTP, и это тоже проверяется тестом.
**Альтернатива:** плоский пакет с `routers/`, `services/`, `models/`. Отвергнута: в ней нет места, куда положить порт, и правило зависимостей нечем проверить. **Альтернатива:** отдельная зона для сообщений. Отвергнута: инвариант порядка истории держит агрегат `Chat`, и разрыв границы потребовал бы распределённой согласованности там, где её можно не заводить.
### Зона владеет всем своим HTTP-слоем
В `<зона>/entrypoints/` лежит не только роутер, но и провайдер DI, отображение доменных ошибок на коды контракта и журнал событий зоны. У `identity` там же живёт идентификация: разбор заголовка, проверка по справочнику и слоёный middleware.
В `entrypoints/api/` остаётся только транспортная платформа: конвейер запроса, health, механизм формирования ответа об ошибке, примитив «актор запроса» и сборка приложения. Единственный модуль платформы, знающий обе зоны, — `app.py`, и это его работа: он собирает вклады (роутеры, провайдеры, реестры ошибок, поля журнала) в одно приложение, запускаемое одним процессом.
Конвейер запроса не знает, кто такой пользователь: он принимает функцию-страж снаружи, а её даёт `identity`. Примитив `Actor` платформенный и опирается на транспортную ошибку `Unauthenticated`, а не на доменную, — «заголовок не предъявлен» это факт транспорта, а не предметной области.
Проверяется тестом: ни один модуль платформы, кроме `app.py`, не импортирует ни одну зону.
Изоляция транспорта держится не каталогом верхнего уровня, а слоями внутри `shared/`: ядро (`domain`, `application`, `infrastructure`) не импортирует ни FastAPI, ни Starlette, и это проверяется тестом. В лабе 5 появится второй вход — worker: он подключит ядро `shared/` и не тронет `shared/entrypoints/`, поэтому веб-фреймворк за собой не потащит.
По той же логике разделены настройки: платформенные (`host`, `port`, `log_level`, предел очереди событий) живут в `shared/config.py`, транспортные (`pipeline`, предел тела, таймаут) — в `shared/entrypoints/config.py`, а `storage_locking` и секрет курсора принадлежат `messaging` и лежат в её `config.py`.
### Связь зон: событие и проекция, а не вызов
`messaging` не спрашивает у `identity`, существует ли пользователь. У него есть собственный реестр участников (`MemberRegistry`), который наполняет проекция на событие `UserRegistered`. Единственное, что `messaging` заимствует у соседней зоны, — объявление этого события.
Проекции выполняются синхронно, до того как клиент получит ответ: иначе «зарегистрировался и сразу создал чат» превратилось бы в гонку, а контракт требует, чтобы подтверждённая запись была видна следующему чтению. Остальные подписчики — журнал активности, внешний брокер — работают через очередь и на ответ не влияют.
Правило проверяется тестом по графу импортов, а не только договорённостью: `identity` не смеет знать о `messaging` вовсе, `messaging` — только об объявлении события.
**Альтернатива:** порт `MemberDirectory`, за которым стоит адаптер поверх `identity`. Отвергнута: это скрытый синхронный вызов между зонами, который при разделении на службы превратится в сетевую зависимость. Цена выбранного варианта — дублирование идентификаторов в двух местах; в обмен зоны можно разнести, не переписывая ни строчки домена.
### Агрегат: чат вместе с историей
Граница согласованности — `Chat`: состав участников и append-only история. `Message` — сущность внутри агрегата, доступная только через него. `User` — отдельный агрегат.
Инварианты, которые держит `Chat`: отправитель входит в состав; пара `(created_at, id)` строго возрастает по всей истории; состав неизменен после создания.
**Альтернатива:** сделать `Message` самостоятельным агрегатом, а членство проверять в обработчике. Отвергнута: инвариант порядка тогда некому держать, и проверка членства расползается по обработчикам. Цена выбранного варианта — агрегат неограниченно растёт; в памяти это дёшево (взятие ссылки, не загрузка), но при переходе на PostgreSQL в лабе 2 репозиторий обязан отдавать агрегат без материализации истории. Это отмечено как точка пересмотра границы.
### Строго возрастающие часы вместо сортировки на чтении
Порт `Clock` реализуется адаптером, который выдаёт метки в UTC с микросекундной точностью и гарантирует строгое возрастание: если системные часы вернули значение, не большее предыдущего, выдаётся предыдущее плюс одна микросекунда.
Следствия: история хранится как append-only список, уже упорядоченный по `(created_at, id)`; keyset-чтение — срез по позиции, найденной двоичным поиском; сортировка на чтении не нужна вовсе.
**Альтернатива:** брать системное время как есть и вставлять с `bisect.insort` по ключу `(created_at, id)`. Отвергнута: вставка в середину — O(n) на сообщение, а при совпадении меток порядок вставки перестаёт совпадать с порядком чтения, и страница может потерять запись. Цена выбранного варианта — отметка времени может обогнать системные часы на микросекунды при всплеске записи; это фиксируется в отчёте как объявленная семантика (`contracts/README.md` прямо требует её описать).
### Keyset-курсор: подписанный и привязанный к запросу
Курсор — base64url от `<версия>.<область>.<время в микросекундах>.<id>` с усечённой подписью HMAC-SHA256. Область — `messages:<chat_id>` либо `chats:<user_id>`. Ключ подписи читается из `CURSOR_SECRET`, а при его отсутствии генерируется случайно на старте процесса.
Это даёт непрозрачность, обнаружение подделки и привязку к ресурсу одним механизмом: курсор от другого чата не пройдёт проверку области и даст `400`. Случайный ключ по умолчанию означает, что курсоры не переживают перезапуск — ровно как и данные.
**Альтернатива:** отдавать `created_at` и `id` открытым составным значением. Отвергнута: клиент начнёт на них полагаться, а подделанный курсор придётся отличать от испорченного вручную.
### Команды, события и две шины
`CommandBus` направляет команду ровно одному обработчику, ошибка всплывает к вызывающему. `EventBus` рассылает событие всем подписчикам через `asyncio.Queue` с явным пределом; исключение обработчика логируется и не мешает ни ответу клиента, ни остальным подписчикам. События собираются из агрегатов в UoW после фиксации (`.seen` → `collect_new_events`), обработчик команды их не публикует.
**Альтернатива:** синхронный вызов обработчиков событий прямо в обработчике команды. Отвергнута: скрытая работа удлиняет HTTP-ответ, а отказ уведомления опрокидывает подтверждённую запись.
### Порт EventPublisher
`EventPublisher` — порт с единственным адаптером `InMemoryEventPublisher`, который кладёт события в `EventBus`. Внешних сервисов в лабе 1 нет: состояние живёт только в памяти процесса, и брокер был бы таким же нарушением условия, как и база данных.
Порт при этом сохранён: в лабе 5 за ним встанет брокер, и ни домен, ни обработчики команд об этом не узнают. Это ровно та развязка, ради которой порт и вводится.
### Сторона чтения в обход агрегата
Запросы (`GetCurrentUser`, `ListChats`, `ReadHistory`) читают хранилище напрямую через отдельный порт и возвращают плоские структуры. Они не поднимают агрегат и не проходят через репозиторий.
Это лёгкая форма CQRS (гл. 12): выделен модуль «только для чтения», отдельного хранилища нет. Мотив: чтение истории — срез упорядоченного списка, и тащить ради него агрегат с инвариантами незачем. Цена — две дороги к одним данным; она оправдана тем, что сторона чтения не меняет состояние и её нечем нарушить.
### Конкурентность: блокировка на агрегат, переключаемая режимом
Приложение работает одним процессом и одним event loop; несколько воркеров Uvicorn несовместимы с общим состоянием в памяти и запрещены конфигурацией. Атомарность операции обеспечивает UoW, удерживая `asyncio.Lock` на время команды.
Режим задаётся `STORAGE_LOCKING`:
- `global` — одна блокировка на всё хранилище; операции разных чатов сериализуются;
- `per-chat` — блокировка на агрегат (значение по умолчанию); операции в разных чатах идут параллельно.
Оба режима — реальные реализации одного порта, и их сравнение образует эксперимент трека «5»: гипотеза в том, что глобальная блокировка становится узким местом при росте конкуренции, а не при росте истории.
**Альтернатива:** положиться на то, что корутина не прерывается между `await`. Отвергнута: инвариант перестанет держаться при первом же `await` внутри критической секции, а проверка «участник → добавить сообщение» станет гонкой.
### Порядок проверок в точке входа
`401` даёт зависимость идентификации, выполняемая до валидации тела; `404` даёт проверка доступа внутри обработчика команды; `400` даёт валидация DTO и доменные ошибки. `RequestValidationError` и ошибка разбора JSON переводятся в `400 invalid_request`; неперехваченное исключение — в `500 internal_error`. Все ответы проходят через middleware, проставляющее `X-Request-Id` и пишущее строку лога без тел запросов.
### Конвейер запроса: один слой вместо трёх
Порядок действий над запросом фиксирован: `X-Request-Id` → предел размера тела → идентификация → таймаут обработки → запись в журнал. Идентификация обязана опережать разбор тела, иначе запрос без заголовка и с испорченным JSON получил бы `400` вместо `401`.
Реализаций две, обе живые и переключаются настройкой `PIPELINE`: `layered` — три `BaseHTTPMiddleware`, `single` — один чистый ASGI-слой. Наблюдаемое поведение API у них совпадает, что закреплено тестом, прогоняющим контрактный сценарий в обоих режимах. Выбор по умолчанию — `single`, и он обоснован измерением, а не вкусом: см. `REPORT.md`.
### Сервер приложений и единый журнал
gunicorn с ровно одним `UvicornWorker`. Несколько воркеров означали бы несколько процессов с независимой памятью: два клиента получали бы разные множества данных. Число воркеров поэтому не настройка, а константа конфигурации.
Логгер в приложении один — structlog за портом `Logger`. Сообщения gunicorn, uvicorn и библиотек перенаправлены в тот же поток и получают тот же формат; access-лог uvicorn заглушён, потому что запись `request.handled` уже содержит те же поля и `request_id`. Поля пишутся по белому списку — это делает утечку текста сообщений невозможной по построению, а не по внимательности автора.
На каждый запрос действует предел времени: при превышении клиент получает `503`, факт записывается в журнал, остальные запросы не затронуты. Предел gunicorn по времени воркера выставлен выше прикладного, чтобы сначала срабатывал аккуратный ответ, а не убийство процесса.
### Конфигурация и контейнер
Настройки читаются из окружения через `pydantic-settings`; значения по умолчанию рассчитаны на запуск без единой переменной. Образ — multi-stage на закреплённом по digest `python:3.14-slim-trixie`, зависимости ставятся из `uv.lock`, рабочий пользователь непривилегированный, `HEALTHCHECK` опрашивает `/health/live`, gunicorn запускается exec-формой и потому получает `SIGTERM` как PID 1; срок корректной остановки — 10 секунд.
## Risks / Trade-offs
- **Аппарат паттернов тяжелее домена лабы 1** → цена принята сознательно: ровно те же порты обслуживают лабы 2–7, где адаптеры меняются на PostgreSQL, Redis, S3 и брокер. В отчёте это названо прямо, а не выдано за необходимость.
- **Реестр участников дублирует идентификаторы пользователей** → это осознанная цена разделения зон: расхождение возможно только если событие потеряно, а проекции выполняются синхронно и потому теряться не могут, пока процесс один. При переходе к нескольким процессам сюда понадобится надёжная доставка.
- **Две реализации конвейера запроса в кодовой базе** → вторая существует как контрольная серия эксперимента и покрыта тем же контрактным тестом; если эксперимент больше не нужен, слоёная реализация удаляется одним файлом.
- **Агрегат `Chat` растёт неограниченно** → в памяти это ссылка, а не загрузка; при переходе на БД граница агрегата пересматривается, и это зафиксировано как точка пересмотра, а не скрытый долг.
- **Строго возрастающие часы могут обогнать системное время при всплеске записи** → расхождение ограничено микросекундами на сообщение и описано в отчёте как объявленная семантика.
- **Один процесс и одно состояние** → горизонтального масштабирования нет и не может быть; несколько воркеров Uvicorn дали бы разные множества данных, поэтому запрещены конфигурацией и проверяются тестом.
- **Событие, потерянное при переполнении очереди, не восстанавливается** → предел очереди явный, отбрасывание логируется; долговечность доставки появится вместе с брокером в лабе 5.
- **Курсоры и данные не переживают перезапуск** → это требование лабы, а не дефект; демонстрируется в сценарии защиты.
- **Измерения снимаются на одной машине, клиент и сервер делят ресурсы** → закрытый контур даёт согласованные пропуски; в отчёте указано, что измерение сравнивает две реализации между собой, а не устанавливает абсолютную пропускную способность.
## Migration Plan
Миграции данных нет: приложение создаётся впервые, состояние пустое по определению. Откат — возврат к предыдущему образу; потеря данных при откате ожидаема и не требует отдельной процедуры.
Порядок выката: собрать образ из чистого clone → запустить контейнер с публикацией порта → дождаться `healthy` → прогнать `make test` → снять измерения трека «5» → заполнить `REPORT.md`.
@@ -0,0 +1,38 @@
## Why
В репозитории есть контракт и публичные проверки, но нет приложения: `make test` падает на отказе соединения. Лабораторная 1 закрывается только работающим сервисом, поэтому нужно превратить `contracts/openapi.json` в процесс и воспроизводимый контейнер. Целевая оценка — «5»: весь уровень 4 плюс завершённый трек 1 «Предел in-memory архитектуры».
## What Changes
- Появляется приложение в `src/messenger/`: обязательный API лабы 1, состояние только в памяти одного процесса, идентификация по `X-User-Id`.
- Две доменные зоны монолита: `identity/` (пользователи) и `messaging/` (чаты и история). У каждой свои ошибки, события, команды, объекты-значения, хранилище и HTTP-фасад. В `shared/` остаются только платформа и механизм связи: базовые типы ошибки, события и команды, технические порты и шина. Коды контракта и HTTP-статусы живут в точке входа. Точка входа одна — `entrypoints/api/`.
- Зоны не вызывают друг друга: `messaging` ведёт собственный реестр участников, наполняемый проекцией на событие `UserRegistered` зоны `identity`. Команда имеет ровно одного обработчика, событие — сколько угодно; проекции выполняются до подтверждения записи, прочие обработчики — через `asyncio.Queue`.
- Порт `EventPublisher` с единственным адаптером — внутренней очередью в памяти. Внешних сервисов в лабе 1 нет; порт остаётся точкой расширения для лабы 5.
- Сервер — gunicorn с одним `UvicornWorker` (несколько воркеров несовместимы с состоянием в памяти); его логи идут через тот же структурный логгер, что и логи приложения. На каждый запрос действует таймаут с предсказуемым `503`.
- Уровень «4»: собственные тесты одной командой, конкурентный тест 100 сообщений от 10 клиентов, non-root контейнер с закреплёнными версиями, SIGTERM ≤10 с, healthcheck, логи без текста сообщений.
- Трек «5»: повторяемый эксперимент 3 размера истории × 3 уровня конкуренции, замеры throughput / p95 / p99 / RSS; проверены две гипотезы об узком месте, сравнение «до/после» приложено для каждой.
- Заполняются `REPORT.md` и `evidence/`; в `Makefile` добавляются цели запуска, тестов и измерений, существующие цели не меняются.
## Capabilities
### New Capabilities
- `lab1-messenger-identity`: регистрация пользователя, уникальность `username`, идентификация запроса по `X-User-Id` и её отказы.
- `lab1-messenger-chats`: создание чата с явным списком участников, членство как граница доступа, список чатов с keyset-пагинацией.
- `lab1-messenger-history`: отправка сообщения с выводом отправителя из идентификации, порядок `(created_at, id)`, keyset-курсор, привязанный к чату.
- `lab1-service-operability`: health-пробы, `X-Request-Id`, единый формат ошибки, таймаут запроса, поведение при SIGTERM, единый журнал всех сообщений процесса, контейнерная поставка.
- `lab1-event-publication`: регистрация доменных событий, доставка проекциям и подписчикам внутренней шиной, изоляция доменных зон друг от друга.
- `lab1-inmemory-capacity`: наблюдаемый предел in-memory хранения — что измеряется, при каких условиях и что считается подтверждённым улучшением.
### Modified Capabilities
<!-- нет: спеки создаются впервые -->
## Impact
- Новое: `src/messenger/{shared,identity,messaging,entrypoints}/**`, `student-tests/**`, `pyproject.toml`, `uv.lock`, `Dockerfile`, `scripts/bench.py`.
- Правится: `REPORT.md`, `evidence/**`, `Makefile` (только новые цели), `.gitignore`.
- Зависимости: `fastapi`, `uvicorn`, `gunicorn`, `pydantic`, `pydantic-settings`, `dishka`, `structlog`, `pytest`, `pytest-asyncio`, `ruff`, `ty`.
- Не затрагиваются: `contracts/**`, `tests/**`, `README.md`, `COURSE.md`, `CONTRIBUTING.md` — контракт и публичные проверки остаются как есть.
## Non-goals
Из Out of scope не появляется ничего: PostgreSQL, Redis и файлы состояния на пути данных, Bearer-сессии и пароли (лаба 2), несколько реплик, балансировщик и `Idempotency-Key` (лаба 3), вложения и S3 (лаба 4), worker и обработка изображений (лаба 5), OTel и Grafana (лаба 6), TLS и Argon2id (лаба 7). Web UI, WebSocket, редактирование и удаление сообщений, изменение состава участников и поиск пользователей не реализуются.
@@ -0,0 +1,102 @@
## Purpose
Определяет, как зоны предметной области узнают о произошедшем, не вызывая друг друга напрямую: модель регистрирует факт, шина разводит его по обработчикам. Транспорт доставки заменяем, и его отказ не влияет на обязательный путь данных.
## ADDED Requirements
### Requirement: Побочные эффекты выполняются через события
Побочная работа, не входящая в границу согласованности операции, SHALL выполняться обработчиками событий, а не внутри обработчика команды. Событие SHALL регистрироваться моделью как факт о произошедшем и SHALL публиковаться только после успешного завершения операции, породившей его.
#### Scenario: Успешная операция порождает событие
- **WHEN** сообщение успешно сохранено и клиент получил `201`
- **THEN** зарегистрировано событие об отправке сообщения, доступное обработчикам
#### Scenario: Отклонённая операция событий не порождает
- **WHEN** отправка сообщения отклонена с `400` или `404`
- **THEN** ни одно событие об отправке не публикуется
#### Scenario: Событие получают все подписчики
- **WHEN** на один тип события подписано несколько обработчиков
- **THEN** событие доставляется каждому из них
### Requirement: Отказ обработчика события не влияет на ответ клиента
Исключение в обработчике события SHALL быть залогировано и SHALL NOT менять код ответа уже подтверждённой операции. Отказ одного обработчика SHALL NOT мешать остальным обработчикам того же события.
#### Scenario: Обработчик падает после подтверждения
- **WHEN** обработчик события завершается исключением после того, как клиент получил `201`
- **THEN** ответ клиента остаётся `201`
- **AND** факт отказа виден в логах с идентификатором запроса
#### Scenario: Один обработчик не блокирует остальные
- **WHEN** первый из двух обработчиков события завершается исключением
- **THEN** второй обработчик всё равно вызывается
### Requirement: Публикация событий не удлиняет обязательный путь
Доставка событий обработчикам SHALL быть развязана с обработкой HTTP-запроса: публикация SHALL завершаться, не дожидаясь работы обработчиков. Очередь публикации SHALL иметь явный предел; при его достижении событие SHALL отбрасываться с записью в лог, а обязательный путь данных SHALL продолжать работать.
#### Scenario: Ответ не ждёт обработчиков
- **WHEN** обработчик события выполняется заметно дольше, чем обработка запроса
- **THEN** клиент получает ответ, не дожидаясь завершения обработчика
#### Scenario: Очередь переполнена
- **WHEN** события публикуются быстрее, чем разбираются, и очередь достигла предела
- **THEN** новые события отбрасываются с записью в лог
- **AND** запись сообщений продолжает подтверждаться кодом `201`
### Requirement: Доставка событий не требует внешних сервисов
Публикация событий SHALL выполняться через порт, реализованный внутренней очередью в памяти процесса. Сервис SHALL NOT зависеть от внешнего брокера, базы данных или иного сетевого сервиса для работы обязательного API.
#### Scenario: Сервис работает без единого внешнего сервиса
- **WHEN** сервис запущен и ни один внешний сервис не поднят
- **THEN** весь обязательный API работает, а события доставляются внутренней очередью
#### Scenario: Публикация скрыта за портом
- **WHEN** проверяется слой приложения
- **THEN** он обращается к публикации только через порт и не знает её реализации
### Requirement: Опубликованное событие не раскрывает содержимого сообщений
Полезная нагрузка события SHALL содержать только идентификаторы и метаданные. Текст сообщений, `display_name` и любые пользовательские данные SHALL NOT попадать ни в тело события, ни в журнал.
#### Scenario: Событие об отправке сообщения без текста
- **WHEN** опубликовано событие об отправке сообщения
- **THEN** его тело содержит идентификаторы сообщения, чата и отправителя и отметку времени
- **AND** не содержит текста сообщения
### Requirement: Доменные зоны связаны только событиями
Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» напрямую. Сведения о существующих участниках SHALL поддерживаться собственной проекцией зоны, наполняемой событием о регистрации пользователя. Проекция SHALL обновляться до того, как клиент получит подтверждение операции, породившей событие.
#### Scenario: Регистрация видна чатам сразу
- **WHEN** пользователь зарегистрирован и немедленно создаёт чат со своим участием
- **THEN** чат создаётся успешно, потому что проекция участников уже знает этот идентификатор
#### Scenario: Неизвестный зоне участник отклоняется
- **WHEN** в состав чата передан идентификатор, о регистрации которого зона не получала события
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Зона пользователей не знает о чатах
- **WHEN** проверяется список зависимостей модулей зоны «пользователи»
- **THEN** среди них нет ни одного модуля зоны «чаты и сообщения»
#### Scenario: Обратная связь идёт только через контракт события
- **WHEN** проверяется список зависимостей модулей зоны «чаты и сообщения»
- **THEN** единственная заимствованная у зоны «пользователи» единица — объявление события о регистрации
@@ -0,0 +1,60 @@
## Purpose
Определяет трек «5» — предел in-memory архитектуры: что измеряется, при каких условиях измерение считается повторяемым и что считается подтверждённым улучшением, а что остаётся гипотезой.
## ADDED Requirements
### Requirement: Повторяемая методика измерения
Эксперимент SHALL выполняться одной командой и SHALL покрывать не менее трёх размеров истории и не менее трёх уровней конкуренции. Каждый прогон SHALL фиксировать длительность, прогрев, уровень конкуренции, размер набора данных, успешные RPS, долю ошибок, p50/p95/p99 задержки и RSS процесса. Результаты SHALL сохраняться машиночитаемым файлом без учётных данных и пользовательских данных.
#### Scenario: Матрица прогонов выполнена
- **WHEN** запущен сценарий измерения предела in-memory
- **THEN** выполняются прогоны для всех сочетаний трёх размеров истории и трёх уровней конкуренции
- **AND** результат каждого прогона содержит успешные RPS, p50/p95/p99, долю ошибок и RSS
#### Scenario: Прогон воспроизводим
- **WHEN** сценарий запущен повторно с теми же параметрами и теми же ресурсными лимитами
- **THEN** сохранённый отчёт содержит версии runtime и образа, лимиты CPU и памяти, длительность и прогрев, позволяющие повторить измерение
#### Scenario: Отчёт не содержит чувствительных данных
- **WHEN** сохранён файл результатов
- **THEN** он не содержит текстов сообщений, учётных данных и идентификаторов реальных людей
### Requirement: Наблюдаемый предел хранения в памяти
Сервис SHALL позволять измерить стоимость хранения одного сообщения в памяти. Эксперимент SHALL показать зависимость RSS от размера истории и SHALL давать оценку числа сообщений, при котором процесс исчерпает заданный лимит памяти.
#### Scenario: Рост RSS измерен
- **WHEN** история чата последовательно доводится до трёх заданных размеров
- **THEN** для каждого размера зафиксирован RSS процесса
- **AND** из измерений выводится средняя стоимость одного сообщения в байтах
#### Scenario: Предел объяснён
- **WHEN** известны стоимость сообщения и лимит памяти контейнера
- **THEN** отчёт приводит оценку предельного числа сообщений и называет допущения этой оценки
### Requirement: Узкое место названо и подтверждено изменением
Отчёт SHALL называть узкое место, выявленное измерениями, и SHALL описывать ровно одно внесённое изменение, направленное на него. Сравнение «до» и «после» SHALL выполняться при одинаковых ресурсных лимитах, одинаковом профиле нагрузки и одинаковом размере набора данных. Улучшение SHALL считаться подтверждённым только при наблюдаемом изменении метрик; необоснованные измерениями выводы SHALL быть помечены как гипотезы.
#### Scenario: Сравнение до и после
- **WHEN** режим работы переключён на изменённую реализацию и прогон повторён с теми же параметрами
- **THEN** отчёт содержит обе серии измерений и разницу по throughput и p95/p99
#### Scenario: Улучшение не подтвердилось
- **WHEN** после изменения метрики не улучшились или ухудшились
- **THEN** отчёт фиксирует это как наблюдение, а не как успех
- **AND** объясняет, какое допущение гипотезы не подтвердилось
#### Scenario: Границы эксперимента названы
- **WHEN** сформулирован вывод об узком месте
- **THEN** отчёт называет, что измерение не доказывает: закрытый контур создаёт согласованные пропуски, клиент и сервер делят одну машину, единственный процесс не даёт отказоустойчивости
@@ -0,0 +1,85 @@
## Purpose
Определяет чат как границу доступа: кто попадает в состав участников, кто видит чат в списке и что происходит с посторонним. Состав участников задаётся при создании и в обязательном API лабы 1 не меняется.
## ADDED Requirements
### Requirement: Создание чата
Сервис SHALL принимать `POST /api/v1/chats` от идентифицированного пользователя с телом `{"title":..., "member_ids":[...]}` и возвращать `201` с объектом `Chat`. `title` SHALL содержать от 1 до 100 code points и не состоять только из пробельных символов. `member_ids` SHALL содержать от 1 до 100 уникальных идентификаторов существующих пользователей и SHALL включать вызывающего. Чат SHALL создаваться атомарно: при любой ошибке валидации он не создаётся вовсе.
#### Scenario: Чат создан
- **WHEN** участник отправляет `POST /api/v1/chats` с корректным `title` и списком из своего и чужого идентификаторов
- **THEN** ответ `201`, тело соответствует схеме `Chat`, `member_ids` совпадает с запрошенным составом
- **AND** `id` и `created_at` назначены сервером
#### Scenario: Вызывающий не входит в состав
- **WHEN** `member_ids` не содержит идентификатора вызывающего
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Состав содержит дубликаты
- **WHEN** `member_ids` содержит один и тот же идентификатор дважды
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Состав содержит неизвестного пользователя
- **WHEN** `member_ids` содержит идентификатор, которому не соответствует ни один пользователь
- **THEN** ответ `400` с кодом `invalid_request`
- **AND** чат не создаётся
#### Scenario: Запрос без идентификации
- **WHEN** `POST /api/v1/chats` приходит без действительного `X-User-Id`
- **THEN** ответ `401` с кодом `unauthorized`
### Requirement: Членство как граница доступа
Чат SHALL быть доступен только своим участникам. Посторонний пользователь SHALL получать `404` с кодом `not_found` — тот же ответ, что и для несуществующего чата. Сервис SHALL NOT использовать `403` и SHALL NOT раскрывать факт существования чужого чата ни кодом ответа, ни текстом сообщения.
#### Scenario: Участник читает чат
- **WHEN** участник запрашивает `GET /api/v1/chats/{chat_id}` своего чата
- **THEN** ответ `200` с объектом `Chat`
#### Scenario: Посторонний читает чужой чат
- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats/{chat_id}`
- **THEN** ответ `404` с кодом `not_found`
#### Scenario: Запрос несуществующего чата
- **WHEN** запрашивается `GET /api/v1/chats/{chat_id}` с UUID, которому не соответствует ни один чат
- **THEN** ответ `404` с кодом `not_found`, неотличимый от ответа на чужой чат
#### Scenario: Идентификатор чата не является UUID
- **WHEN** `chat_id` в пути не является UUID
- **THEN** ответ `400` с кодом `invalid_request`
### Requirement: Список чатов пользователя
Сервис SHALL отдавать по `GET /api/v1/chats` страницу `{"items":[...],"next_cursor":...}` с чатами, в которых состоит вызывающий, упорядоченными по `(created_at, id)` по возрастанию. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. Список SHALL NOT содержать чатов, недоступных вызывающему.
#### Scenario: Участник видит свой чат
- **WHEN** участник запрашивает `GET /api/v1/chats?limit=100`
- **THEN** ответ `200`, и его чат присутствует в `items`
#### Scenario: Посторонний не видит чужой чат
- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats?limit=100`
- **THEN** ответ `200`, и этого чата в `items` нет
#### Scenario: Limit вне допустимого диапазона
- **WHEN** запрос содержит `limit=0`, `limit=101` или нечисловое значение
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Обход списка курсором
- **WHEN** пользователь состоит в нескольких чатах и запрашивает страницы по одному элементу, передавая `next_cursor` предыдущей страницы
- **THEN** страницы идут в порядке `(created_at, id)` по возрастанию, ни один чат не повторяется и не пропускается
- **AND** `next_cursor` последней страницы равен `null`
@@ -0,0 +1,106 @@
## Purpose
Определяет отправку сообщений и чтение истории чата: кто считается отправителем, в каком порядке лежат сообщения и какие гарантии даёт keyset-курсор при обходе истории.
## ADDED Requirements
### Requirement: Отправка сообщения
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":...}` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL содержать от 1 до 4000 Unicode code points и SHALL NOT состоять только из пробельных символов. `id` и `created_at` SHALL назначаться сервером.
#### Scenario: Сообщение отправлено
- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат
- **THEN** ответ `201`, тело соответствует схеме `Message`
- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным
#### Scenario: Отправитель не берётся из тела запроса
- **WHEN** тело запроса содержит поле `sender_id`
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Пустой или пробельный текст
- **WHEN** тело содержит `{"text":""}` или `{"text":" "}`
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Текст длиннее предела
- **WHEN** `text` содержит более 4000 Unicode code points
- **THEN** ответ `400` с кодом `invalid_request`
- **AND** длина считается в code points, а не в байтах UTF-8
#### Scenario: Посторонний пишет в чужой чат
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение
- **THEN** ответ `404` с кодом `not_found`
- **AND** сообщение не сохраняется
#### Scenario: Доступ проверяется раньше содержимого
- **WHEN** посторонний отправляет в чужой чат тело, нарушающее схему
- **THEN** ответ `404`, а не `400`
### Requirement: Порядок истории
История чата SHALL быть упорядочена по паре `(created_at, id)` по возрастанию. Время SHALL назначаться сервером в формате RFC 3339 UTC с суффиксом `Z`. Сервис SHALL гарантировать, что пара `(created_at, id)` строго возрастает для последовательно принятых сообщений, в том числе при конкурентных вставках, — иначе обход истории теряет или дублирует записи.
#### Scenario: Сообщения возвращаются в порядке приёма
- **WHEN** в чат последовательно отправлены два сообщения от разных участников
- **THEN** `GET /api/v1/chats/{chat_id}/messages` возвращает их в порядке отправки
#### Scenario: Конкурентная запись не ломает порядок
- **WHEN** 10 клиентов параллельно отправляют по 10 сообщений в один чат
- **THEN** история содержит ровно 100 сообщений с попарно различными `id`
- **AND** порядок `(created_at, id)` строго возрастает по всей истории
### Requirement: Чтение истории keyset-курсором
Сервис SHALL отдавать по `GET /api/v1/chats/{chat_id}/messages` страницу `{"items":[...],"next_cursor":...}`. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. `next_cursor` SHALL быть непрозрачной для клиента строкой либо `null`, если на момент чтения следующей записи нет. Курсор SHALL быть привязан к чату: курсор, выданный для другого чата, SHALL приводить к `400`. Обход неизменной истории SHALL NOT повторять и SHALL NOT пропускать записи; `limit` разрешается менять между страницами.
#### Scenario: Первая страница отдаёт курсор
- **WHEN** в чате два сообщения и запрошено `?limit=1`
- **THEN** ответ содержит один элемент и непустой `next_cursor`
#### Scenario: Последняя страница закрывает историю
- **WHEN** запрошена вторая страница с курсором предыдущей и `limit=1`
- **THEN** ответ содержит оставшийся элемент и `next_cursor` равный `null`
- **AND** элемент первой страницы не повторяется
#### Scenario: Курсор не привязан к читателю
- **WHEN** курсор, выданный одному участнику чата, предъявляет другой участник того же чата
- **THEN** страница отдаётся на общих основаниях
#### Scenario: Курсор от другого чата
- **WHEN** курсор, выданный для одного чата, предъявлен при чтении другого чата
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Испорченный или подделанный курсор
- **WHEN** значение `cursor` не является ранее выданным сервером курсором
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Limit вне допустимого диапазона
- **WHEN** запрос содержит `limit=0` или `limit=101`
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Посторонний читает чужую историю
- **WHEN** пользователь, не входящий в состав чата, запрашивает его историю
- **THEN** ответ `404` с кодом `not_found`
### Requirement: Подтверждённое сообщение видно следующему чтению
Сообщение, на которое выдан ответ `201`, SHALL быть видно любому последующему чтению истории этого чата. Кэширование допускается, но SHALL NOT возвращать историю, устаревшую относительно успешной записи.
#### Scenario: Запись видна сразу после подтверждения
- **WHEN** участник получил `201` на отправку сообщения и немедленно читает историю
- **THEN** отправленное сообщение присутствует в ответе
@@ -0,0 +1,84 @@
## Purpose
Определяет, как пользователь появляется в системе и как сервер узнаёт, от чьего имени пришёл запрос. В лабе 1 идентификация учебная и никого не аутентифицирует: любой клиент может выдать себя за другого, предъявив чужой идентификатор.
## ADDED Requirements
### Requirement: Регистрация пользователя
Сервис SHALL принимать `POST /api/v1/users` без идентификации и возвращать `201` с объектом `User`, содержащим назначенные сервером `id` и `created_at`. Тело запроса SHALL содержать ровно поля `username` и `display_name`. `username` SHALL соответствовать `^[a-z0-9_]{3,32}$` и быть уникальным, `display_name` SHALL содержать от 1 до 100 Unicode code points и не состоять только из пробельных символов. Ответ SHALL NOT содержать полей, отсутствующих в схеме `User`.
#### Scenario: Пользователь создан
- **WHEN** приходит `POST /api/v1/users` с телом `{"username":"alice_01","display_name":"Алиса"}`
- **THEN** ответ `201`, тело соответствует схеме `User`, `username` и `display_name` совпадают с запросом
- **AND** `id` — UUID, назначенный сервером, `created_at` — RFC 3339 UTC с суффиксом `Z`
#### Scenario: Username занят
- **WHEN** приходит `POST /api/v1/users` с `username`, уже принадлежащим другому пользователю
- **THEN** ответ `409` с телом ошибки и кодом `conflict`
#### Scenario: Username нарушает формат
- **WHEN** `username` содержит заглавные буквы, дефис, пробел или имеет длину вне 3–32 символов
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Display_name пуст или состоит из пробелов
- **WHEN** `display_name` равен `""`, `" "` или длиннее 100 code points
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Тело запроса нарушает схему
- **WHEN** тело содержит лишнее поле, неверный тип поля, не содержит обязательного поля или не является корректным JSON
- **THEN** ответ `400` с кодом `invalid_request`
- **AND** сообщение ошибки не содержит stack trace и внутренних деталей реализации
#### Scenario: Регистрация не требует идентификации
- **WHEN** `POST /api/v1/users` приходит без заголовка `X-User-Id`
- **THEN** запрос обрабатывается на общих основаниях, ответ не равен `401`
### Requirement: Идентификация запроса заголовком X-User-Id
Защищённые endpoint SHALL требовать заголовок `X-User-Id` со значением идентификатора существующего пользователя. Отсутствующий, синтаксически неверный и неизвестный идентификатор SHALL приводить к `401` с кодом `unauthorized`. Проверка идентификации SHALL выполняться до проверки доступа к конкретному ресурсу и до содержательной проверки тела запроса.
#### Scenario: Заголовок отсутствует
- **WHEN** приходит `GET /api/v1/users/me` без `X-User-Id`
- **THEN** ответ `401` с кодом `unauthorized`
#### Scenario: Идентификатор неизвестен системе
- **WHEN** `X-User-Id` содержит синтаксически корректный UUID, которому не соответствует ни один пользователь
- **THEN** ответ `401` с кодом `unauthorized`
- **AND** ответ не сообщает, существовал ли такой пользователь когда-либо
#### Scenario: Идентификатор не является UUID
- **WHEN** `X-User-Id` содержит произвольную строку, пустое значение или несколько значений
- **THEN** ответ `401` с кодом `unauthorized`
#### Scenario: Идентификация проверяется раньше тела запроса
- **WHEN** приходит запрос без `X-User-Id` и с телом, нарушающим схему
- **THEN** ответ `401`, а не `400`
### Requirement: Чтение текущего пользователя
Сервис SHALL отдавать по `GET /api/v1/users/me` объект `User`, соответствующий предъявленной идентификации, в том же виде, в каком он был возвращён при регистрации.
#### Scenario: Текущий пользователь возвращён
- **WHEN** приходит `GET /api/v1/users/me` с `X-User-Id` существующего пользователя
- **THEN** ответ `200`, тело соответствует схеме `User` и совпадает с телом ответа его регистрации
### Requirement: Состояние пользователей не переживает перезапуск
Список пользователей SHALL храниться только в памяти процесса. После перезапуска процесса ранее выданные идентификаторы SHALL перестать быть действительными.
#### Scenario: Идентификатор после перезапуска недействителен
- **WHEN** процесс перезапущен и приходит запрос с `X-User-Id`, выданным до перезапуска
- **THEN** ответ `401` с кодом `unauthorized`
@@ -0,0 +1,164 @@
## Purpose
Определяет наблюдаемое поведение сервиса как эксплуатируемого процесса: пробы жизни и готовности, сквозной идентификатор запроса, единый формат ошибок, реакция на сигнал остановки и требования к контейнерной поставке.
## ADDED Requirements
### Requirement: Пробы жизни и готовности
Сервис SHALL отвечать на `GET /health/live` кодом `200` с телом `{"status":"ok"}`, проверяя только жизнь процесса. Сервис SHALL отвечать на `GET /health/ready` кодом `200` с тем же телом, если он способен обслуживать обязательный синхронный путь, и кодом `503` с телом ошибки в общем формате в противном случае. Пробы SHALL NOT требовать идентификации. Недоступность опциональных зависимостей SHALL NOT переводить готовность в `503`.
#### Scenario: Проба жизни отвечает без идентификации
- **WHEN** приходит `GET /health/live` без заголовков идентификации
- **THEN** ответ `200` с телом `{"status":"ok"}`
#### Scenario: Готовность подтверждена
- **WHEN** приходит `GET /health/ready` на полностью запущенном процессе
- **THEN** ответ `200` с телом `{"status":"ok"}`
#### Scenario: Готовность не зависит от внешних сервисов
- **WHEN** проверяется готовность сервиса
- **THEN** она определяется только состоянием самого процесса, поскольку внешних зависимостей нет
#### Scenario: Сервис остановлен
- **WHEN** процесс получил сигнал остановки и перестал принимать новую работу
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable` либо соединение не устанавливается
### Requirement: Сквозной идентификатор запроса
Каждый ответ сервиса, включая ответы проб и ответы об ошибках, SHALL содержать непустой заголовок `X-Request-Id`. Если запрос принёс собственный `X-Request-Id`, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое.
#### Scenario: Идентификатор присутствует в любом ответе
- **WHEN** выполняется любой запрос к сервису, успешный или ошибочный
- **THEN** ответ содержит непустой `X-Request-Id`
#### Scenario: Клиентский идентификатор сохраняется
- **WHEN** запрос содержит `X-Request-Id` с непустым значением
- **THEN** ответ содержит то же значение
### Requirement: Единый формат ошибки
Ответ с кодом `4xx` или `5xx` SHALL иметь `Content-Type: application/json` и тело `{"error":{"code":...,"message":...,"request_id":...}}` без каких-либо дополнительных полей. `code` SHALL принимать значение из перечисления контракта, `request_id` SHALL совпадать со значением заголовка `X-Request-Id`. `message` SHALL быть непустым и SHALL NOT содержать stack trace, SQL, учётных данных, внутренних путей и сведений о существовании чужих объектов.
#### Scenario: Тело ошибки соответствует схеме
- **WHEN** запрос завершается ошибкой любого класса
- **THEN** тело ответа соответствует схеме `Error` контракта
- **AND** `request_id` в теле совпадает с заголовком `X-Request-Id`
#### Scenario: Необработанное исключение
- **WHEN** обработка запроса завершается непредвиденным исключением
- **THEN** ответ `500` с кодом `internal_error` и телом в общем формате
- **AND** тело не раскрывает внутренних деталей
#### Scenario: Неподдерживаемый метод или несуществующий путь
- **WHEN** запрашивается несуществующий путь или неподдерживаемый метод существующего пути
- **THEN** ответ имеет тело в общем формате ошибки с непустым `X-Request-Id`
### Requirement: Корректное завершение по сигналу
По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
#### Scenario: Остановка укладывается в срок
- **WHEN** запущенному контейнеру послан `SIGTERM`
- **THEN** процесс завершается не позднее чем через 10 секунд
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
#### Scenario: Принятый запрос дорабатывается
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
- **THEN** этот запрос получает ответ до завершения процесса
### Requirement: Логи без содержимого сообщений
Сервис SHALL писать в stdout/stderr структурированную запись на каждый запрос с методом, шаблоном маршрута, кодом ответа, длительностью и `X-Request-Id`. Логи SHALL NOT содержать текста сообщений, `display_name`, значений заголовков идентификации и тел запросов.
#### Scenario: Запись о запросе присутствует
- **WHEN** обработан любой запрос к API
- **THEN** в stdout появляется запись с методом, шаблоном маршрута, кодом ответа и идентификатором запроса
#### Scenario: Текст сообщения не попадает в логи
- **WHEN** отправлено сообщение с известным текстом-маркером
- **THEN** этот текст отсутствует в stdout и stderr процесса
### Requirement: Контейнерная поставка
Сервис SHALL собираться из исходников в образ, слушать `0.0.0.0:8080` и читать конфигурацию из переменных окружения. Контейнер SHALL выполняться от непривилегированного пользователя, SHALL фиксировать версию базового образа и версии зависимостей и SHALL объявлять healthcheck, опирающийся на пробу жизни.
#### Scenario: Образ собирается из чистого clone
- **WHEN** выполняется сборка образа в свежей копии репозитория
- **THEN** сборка завершается успешно без обращения к артефактам вне репозитория
#### Scenario: API доступен на опубликованном порту
- **WHEN** контейнер запущен с публикацией порта 8080
- **THEN** `GET /health/ready` с хоста отвечает `200`
#### Scenario: Процесс работает не от root
- **WHEN** в работающем контейнере проверяется эффективный пользователь процесса сервера
- **THEN** это не `root`, и идентификатор пользователя не равен 0
#### Scenario: Healthcheck отражает состояние сервиса
- **WHEN** контейнер запущен и сервис готов
- **THEN** статус healthcheck контейнера становится `healthy`
### Requirement: Состояние живёт только в памяти процесса
Сервис SHALL хранить пользователей, чаты и сообщения только в памяти своего процесса. Сервис SHALL NOT использовать внешние СУБД, кэши и файлы состояния на обязательном пути данных. После перезапуска процесса всё состояние SHALL быть пустым.
#### Scenario: Данные исчезают после перезапуска
- **WHEN** созданы пользователь, чат и сообщение, после чего контейнер перезапущен тем же образом
- **THEN** прежний идентификатор пользователя получает `401`, а созданные чат и сообщение недоступны
#### Scenario: Нет записи состояния на диск
- **WHEN** сервис обработал запись пользователей, чатов и сообщений
- **THEN** в файловой системе контейнера не появляется файлов с этим состоянием
### Requirement: Предел времени обработки запроса
Обработка запроса SHALL ограничиваться настраиваемым пределом времени. При его превышении сервис SHALL отвечать `503` с кодом `unavailable`, если ответ ещё не начал отправляться, и SHALL записывать факт превышения в журнал. Превышение предела одним запросом SHALL NOT влиять на последующие запросы и на готовность сервиса.
#### Scenario: Запрос превысил предел
- **WHEN** обработка запроса длится дольше установленного предела
- **THEN** ответ `503` с кодом `unavailable` и телом в общем формате ошибки
#### Scenario: Сервис продолжает работать после превышения
- **WHEN** после превышения предела приходит обычный запрос
- **THEN** он обрабатывается штатно, а `GET /health/ready` отвечает `200`
#### Scenario: Запись о превышении не раскрывает содержимого
- **WHEN** запрос с известным текстом-маркером превысил предел
- **THEN** в журнале появляется запись о превышении, и этот текст в ней отсутствует
### Requirement: Единый журнал всех сообщений процесса
Сервис SHALL выводить в stdout единый поток структурированных записей. Сообщения сервера приложений и используемых библиотек SHALL проходить через тот же журнал и иметь тот же формат, что и сообщения приложения. Записи SHALL содержать только поля из объявленного перечня; поля вне перечня SHALL отбрасываться.
#### Scenario: Сообщения сервера приложений в общем формате
- **WHEN** процесс запускается и печатает сообщения о старте сервера
- **THEN** каждая строка stdout разбирается как структурированная запись того же формата, что и записи приложения
#### Scenario: Незаявленное поле не попадает в журнал
- **WHEN** запись журнала формируется с полем, отсутствующим в перечне разрешённых
- **THEN** это поле в выводе отсутствует
@@ -0,0 +1,94 @@
## 1. Тулчейн и каркас проекта
- [x] 1.1 Завести `pyproject.toml`: метаданные, `requires-python`, зависимости рантайма (`fastapi`, `uvicorn[standard]`, `gunicorn`, `pydantic`, `pydantic-settings`, `dishka`, `structlog`) и dev-группу (`pytest`, `pytest-asyncio`, `httpx`, `ruff`, `ty`)
- [x] 1.2 Настроить `ruff` в `pyproject.toml`: целевая версия Python, набор правил, `line-length`, стиль отступов, изоляция `student-tests/` от правил приложения
- [x] 1.3 Настроить `ty` в `pyproject.toml`: корень исходников `src/`, строгость проверок, исключения для тестов
- [x] 1.4 Закрепить версии: `uv lock`, зафиксировать `uv.lock` в репозитории, дополнить `.gitignore` и `.dockerignore` артефактами сборки
- [x] 1.5 Добавить в `Makefile` цели `lint`, `format`, `typecheck`, `student-test`, `app-run`, `app-stop`, `bench`, не трогая существующие цели
- [x] 1.6 Настроить PostToolUse-хук Claude Code в `.claude/settings.json`: после каждой правки файла под `src/` выполняются `ruff check --fix`, `ruff format` и `ty check` по этому файлу; правки вне `src/` хук пропускает
- [x] 1.7 Проверка группы: `uv sync`, затем `make lint` и `make check` на пустом каркасе проходят
## 2. Доменные зоны
- [x] 2.1 Разделить приложение на зоны `identity/` и `messaging/`; в `shared/` оставить только базовый тип события, коды ошибок, общие проверки строк и ключ истории
- [x] 2.2 Зона `identity`: объекты-значения `Username` и `DisplayName`, сущность `User`, событие `UserRegistered`
- [x] 2.3 Зона `messaging`: объекты-значения `ChatTitle` и `MessageText`, агрегат `Chat` с составом участников и append-only историей, сущность `Message`, события `ChatCreated` и `MessagePosted`
- [x] 2.4 Инварианты агрегата `Chat`: отправитель входит в состав, пара `(created_at, id)` строго возрастает, состав неизменен после создания
- [x] 2.5 Коды ошибок контракта в `shared/domain/errors.py`: `invalid_request`, `not_found`, `conflict`, `unauthorized`, `unavailable`
- [x] 2.6 Проверка группы: юнит-тесты обеих зон на правила `username`, длину текста в code points, членство и монотонность истории
## 3. Слой приложения
- [x] 3.1 Общие порты в `shared/application/ports.py`: `Clock`, `IdGenerator`, `Logger`, `UnitOfWork`, `EventPublisher`, `CursorCodec`
- [x] 3.2 Порты зоны `identity`: `UserRepository`, `IdentityUnitOfWork`, `UserDirectory`; команда `RegisterUser` и её обработчик
- [x] 3.3 Порты зоны `messaging`: `ChatRepository`, `MemberRegistry`, `MessagingUnitOfWork`, `ChatDirectory`; команды `CreateChat` и `PostMessage` и их обработчики
- [x] 3.4 Сторона чтения: `GetCurrentUser` в `identity`, `GetChat`, `ListChats` и `ReadHistory` в `messaging` — плоские результаты в обход агрегата
- [x] 3.5 Шины в `shared/application/messagebus.py`: `CommandBus` (ровно один обработчик, ошибка всплывает) и `EventBus` с двумя видами подписки — проекции до подтверждения и отложенные обработчики через `asyncio.Queue` с пределом
- [x] 3.6 Проекция `MemberProjection` в `messaging`: реестр участников наполняется событием `UserRegistered` зоны `identity`, прямых вызовов между зонами нет
- [x] 3.7 Сбор событий: UoW обходит `.seen` после фиксации и передаёт события публикатору
- [x] 3.8 Проверка группы: тесты границ зон по графу импортов и тесты консистентности данных между зонами
## 4. Инфраструктура
- [x] 4.1 Хранилище зоны `identity`: индексы по идентификатору и по `username`, своя блокировка
- [x] 4.2 Хранилище зоны `messaging`: чаты, индекс по участнику, реестр известных участников; история как append-only список внутри агрегата
- [x] 4.3 Репозитории и UoW обеих зон с ведением `.seen`; фиксация явная, откат по умолчанию
- [x] 4.4 Режимы блокировки `global` и `per-chat` за одним портом, выбор через настройку `STORAGE_LOCKING`
- [x] 4.5 Часы `shared/infrastructure/clock.py`: UTC, микросекунды, строго возрастающие метки; генератор идентификаторов
- [x] 4.6 Кодек курсора: base64url, подпись HMAC-SHA256, привязка к области `messages:<chat_id>` и `chats:<user_id>`
- [x] 4.7 Адаптер публикации `InMemoryEventPublisher` поверх `EventBus`; порт `EventPublisher` остаётся точкой расширения на лабу 5
- [x] 4.8 Структурный логгер на structlog за портом `Logger`: единый JSON-поток, белый список полей, сообщения сервера приложений и библиотек идут через него же
- [x] 4.9 Проверка группы: тесты кодека курсора (подделка, чужая область, испорченное значение) и монотонности часов под конкурентной нагрузкой
## 5. Точка входа HTTP
- [x] 5.1 Настройки `config.py` через `pydantic-settings`: хост, порт, лимиты, режим блокировки, параметры брокера, срок остановки; рабочие значения по умолчанию
- [x] 5.2 DTO запросов и ответов в `entrypoints/api/schemas.py` с запретом лишних полей; тела ответов ровно по схемам контракта
- [x] 5.3 Middleware `X-Request-Id`: использовать клиентское значение либо сгенерировать, проставить в каждый ответ, связать с логом
- [x] 5.4 Обработчики ошибок: доменные ошибки, `RequestValidationError`, ошибка разбора JSON, `404`/`405` и неперехваченное исключение — все в единый формат `Error`
- [x] 5.5 Зависимость идентификации `X-User-Id`, выполняемая до валидации тела; отсутствие, неверный формат и неизвестный идентификатор дают `401`
- [x] 5.6 Маршруты health, users, chats, messages; путь запроса переводится в команду или запрос и передаётся шине
- [x] 5.7 Сборка зависимостей `ioc.py` на dishka: отдельные провайдеры `SharedProvider`, `IdentityProvider`, `MessagingProvider` и `BusProvider`; `Scope.APP` для хранилищ, часов, публикатора и шины событий, `Scope.REQUEST` для UoW и шин команд
- [x] 5.8 Жизненный цикл приложения: старт и остановка фоновой задачи разбора событий, закрытие контейнера DI, перевод `/health/ready` в `503` при остановке
- [x] 5.9 Единый конвейер запроса как чистый ASGI-middleware: `X-Request-Id`, предел тела, идентификация, таймаут обработки и запись в журнал; слоёный вариант сохраняется для сравнения
- [x] 5.10 Проверка группы: `make app-run`, затем `make test` — публичный smoke проходит целиком
## 6. Контейнер
- [x] 6.1 `Dockerfile`: multi-stage, базовый образ закреплён по digest, зависимости из `uv.lock`, слой зависимостей отделён от слоя исходников
- [x] 6.2 Непривилегированный пользователь, минимальный набор файлов в финальном образе, `.dockerignore` исключает `.venv`, `.git`, `evidence` и кэши
- [x] 6.3 Сервер — gunicorn с одним `UvicornWorker`, конфигурация в `gunicorn_conf.py`, его журнал перенастроен на общий логгер; `HEALTHCHECK` на `/health/live` без дополнительных пакетов; `CMD` в exec-форме, gunicorn — PID 1
- [x] 6.4 Корректная остановка: `SIGTERM` завершает процесс не дольше 10 секунд, принятые запросы дорабатываются
- [x] 6.6 Проверка группы: сборка из чистого clone, запуск, `healthy`, `make test`, замер времени остановки, проверка пользователя процесса
## 7. Собственные тесты (уровень «4»)
- [x] 7.1 Негативные тесты API: malformed JSON, лишнее поле, неверный тип, пустой и пробельный текст, текст свыше 4000 code points
- [x] 7.2 Тесты доступа: чужой чат даёт `404` на чтение и на запись, чужой чат не виден в списке, `403` не используется
- [x] 7.3 Тесты идентификации: отсутствующий, неверный и неизвестный `X-User-Id` дают `401`; дубликат `username` даёт `409`
- [x] 7.4 Тесты пагинации: обход нескольких страниц без повторов и пропусков, смена `limit` между страницами, курсор от другого чата, подделанный курсор, `limit` вне диапазона
- [x] 7.5 Конкурентный тест: 100 сообщений от 10 клиентов дают ровно 100 уникальных сообщений и строго возрастающий порядок
- [x] 7.6 Тест логов: текст-маркер сообщения не появляется в stdout и stderr
- [x] 7.8 Тесты границ зон: граф импортов подтверждает, что `identity` не знает о `messaging`, а `messaging` заимствует только объявление события
- [x] 7.9 Тесты консистентности между зонами: регистрация сразу видна чатам, отклонённые операции не оставляют следа ни в одной зоне, параллельная работа обеих зон не расходится по счётчикам
- [x] 7.10 Тесты таймаута запроса: предсказуемый `503`, отсутствие влияния на следующие запросы, запись в журнал без текста сообщения
- [x] 7.11 Проверка группы: `make student-test` запускает всё одной командой и проходит
## 8. Трек «5»: предел in-memory архитектуры
- [x] 8.1 `scripts/bench.py`: матрица из трёх размеров истории и трёх уровней конкуренции, прогрев, сбор успешных RPS, доли ошибок, p50/p95/p99 и RSS
- [x] 8.2 Снятие RSS процесса контейнера и вывод средней стоимости одного сообщения в байтах
- [x] 8.3 Гипотеза 1: блокировка хранилища. Прогон матрицы в режимах `global` и `per-chat` при тех же лимитах, сохранение обеих серий
- [x] 8.4 Профилирование пути записи для поиска настоящего узкого места, когда гипотеза 1 не подтвердилась
- [x] 8.5 Гипотеза 2: накладные расходы конвейера запроса. Прогон матрицы в режимах `layered` и `single`, сохранение обеих серий
- [x] 8.6 Сведение серий в сравнительные таблицы: throughput, p95, p99, RSS, разница по каждому сочетанию
- [x] 8.7 Оценка предела: число сообщений до исчерпания лимита памяти, допущения и границы экстраполяции
- [x] 8.8 Проверка группы: `make bench` воспроизводит серии, результаты машиночитаемы и не содержат пользовательских данных
## 9. Отчёт и приёмка
- [x] 9.1 Заполнить `REPORT.md`: запуск из чистого clone, версии, архитектура, границы транзакций, объявленная семантика времени и курсоров
- [x] 9.2 Таблица «критерий → команда → наблюдение → файл доказательства» для каждого заявленного пункта уровней «3», «4» и трека «5»
- [x] 9.3 Таблица воздействий: перезапуск контейнера, `SIGTERM` под нагрузкой, недоступный брокер при включённой публикации
- [x] 9.4 Раздел ограничений: какие отказы не выдерживаются, где учебное упрощение, что подтверждено измерением, а что осталось гипотезой
- [x] 9.5 Проверка группы: `make check`, `make lint`, `make student-test` и `make test` против собранного образа проходят подряд
@@ -0,0 +1,5 @@
schema: spec-driven
created: 2026-10-12
skip_specs: true
archived: 2026-10-12
lab: 1
@@ -0,0 +1,66 @@
## Context
Мотивация — в `proposal.md` (Why). Сейчас FastAPI 0.141 уже сериализует успешные ответы через pydantic-core: аннотация `-> dict[str, Any]` превращается в TypeAdapter, и JSON-байты собираются на стороне Rust. Значит, модели ответов не добавляют новый сериализатор: меняется только то, что собирается в Python, — dict или модель. Тело ошибки отправляется в обход FastAPI, из сырого ASGI-конвейера (`shared/entrypoints/pipeline.py`) и из `identification.py`, сейчас через `orjson.dumps(error_body(...))`.
Изменение затрагивает обе зоны и `shared/entrypoints/`, но новой связи между зонами не вводит: каждая зона правит только свой HTTP-слой, обмен событиями не меняется.
## Goals / Non-Goals
**Goals:**
- Каждое значение, пересекающее HTTP-границу, имеет объявленный pydantic-тип; внутри — только dataclass и доменные объекты.
- Ядро зон (`domain/`, `application/`) не импортирует pydantic: схемы живут в `entrypoints/`, настройки — в `config.py`.
- Байт-в-байт тот же JSON на всех endpoint и в теле ошибки.
**Non-Goals:**
- Перенос доменных инвариантов в схемы.
- Замена `tuple` (`HistoryKey`, `tuple[list[T], bool]` из портов, `tuple[str, int]` в реестре ошибок) — это не dict.
- Изменение индексов хранилища, ASGI-сообщений, реестров обработчиков, `CONFIG_KWARGS` uvicorn.
- Изменения контейнера: пользователь, закрепление версий, healthcheck, обработка `SIGTERM` и переменные окружения остаются прежними.
## Decisions
### D1. Схемы транспорта лежат в `entrypoints/schemas.py` своей зоны
`identity/entrypoints/schemas.py`: `CreateUserRequest`, `UserOut`. `messaging/entrypoints/schemas.py`: `CreateChatRequest`, `CreateMessageRequest`, `PageQuery`, `ChatOut`, `MessageOut`, `PageOut[T]`. `shared/entrypoints/schemas.py`: `ErrorEnvelope` и `ErrorDetail`, `HealthOut`.
В `shared/` попадают только конверт ошибки и health: это механизм платформы, общий для всех ответов, а не доменное понятие. Коды ошибок по-прежнему объявляет зона в своём `errors.py`. `PageOut` остаётся в `messaging`, потому что страницы есть только там.
Что получаем: форма ответа объявлена типом и проверяется `ty` и FastAPI, а валидация входа заканчивается до application. Чего стоит: форма дублирует `contracts/openapi.json`, при этом источником истины остаётся `contracts/`.
### D2. Маппинг явным `of(domain)`, а не `from_attributes`
`UserOut.of(user)`, `ChatOut.of(chat)`, `MessageOut.of(message)`, `PageOut[MessageOut].of(page, MessageOut.of)`. В доменных объектах лежат value objects (`username.value`, `text.value`), и `from_attributes` пришлось бы подстраивать алиасами или свойствами в домене, а домен не должен знать транспорт. Чего стоит: один конструктор модели на элемент ответа.
### D3. Типы полей ответа — `UUID` и `datetime`
Поля `id`, `chat_id`, `sender_id`, `member_ids`, `created_at` типизированы по смыслу; pydantic сериализует `UUID` строкой, а UTC-`datetime` — с `Z`. Функция `moment()`, которая дублируется в двух зонах, удаляется. Альтернатива — поля `str`, заполняемые маппером, — отвергнута, потому что дублирует форматирование. Если формат разойдётся с текущим `isoformat().replace("+00:00", "Z")`, поле получит `Annotated[datetime, PlainSerializer(...)]` с прежним форматом.
### D4. Параметры запроса типизируются на границе
- `GET /chats` и `GET .../messages` принимают `Annotated[PageQuery, Query()]`: `limit: int = Field(50, ge=1, le=100)`, `cursor: str | None = None`. `extra="forbid"` у этой модели не ставится, потому что неизвестные query-параметры сегодня игнорируются. Строгий режим тоже не ставится: значения query — строки.
- `chat_id: UUID` в path; функция `chat_uuid()` удаляется.
- `CreateChatRequest.member_ids: list[Annotated[UUID, Field(strict=False)]]`. Модель остаётся `strict=True`, но FastAPI проверяет уже распарсенный dict в python-режиме, а там строгий `UUID` не принимает строку.
- `parse_limit` и `LIMIT_*` уходят из `messaging/application/queries.py`. `ListChats` и `ReadHistory` получают `limit: int`. `CreateChat.member_ids` становится `Sequence[UUID]`, а `parse_uuids` в обработчике удаляется. Проверки дубликатов, неизвестных участников и отсутствия вызывающего остаются в домене и обработчике.
Ошибка разбора даёт `RequestValidationError` → `400 invalid_request`, то есть тот же код, что сейчас дают `InvalidPageRequest` и `InvalidChatData`. Курсор остаётся непрозрачной строкой, и разбирает его по-прежнему `SignedCursorCodec`.
### D5. Конверт ошибки сериализует pydantic-core
`ErrorEnvelope.of(code, message, request_id)` заменяет `error_body()` во всех четырёх местах вызова (`errors.py`, `pipeline.py`, `middleware.py`, `identification.py`). Байты получаются через `model_dump_json().encode()`, и на этом заканчивается использование orjson для HTTP-ответов. `orjson` остаётся зависимостью ради строк журнала.
### D6. Внутренние dict-методы удаляются
`DomainEvent.payload()` и его реализации в `UserRegistered`, `ChatCreated`, `MessagePosted` удаляются: событие уже frozen dataclass и само служит внутренним DTO. Журналы читают поля события напрямую. Порт `ChatDirectory.totals()`, его адаптер и метод хранилища тоже удаляются, потому что вызовов нет. Альтернатива — dataclass `Totals` и `EventPayload` — отвергнута как код ради кода. Когда в лабе 5 появится брокер, сериализацию события для него определит схема на той границе.
## Risks / Trade-offs
- [Формат `created_at` от pydantic расходится с текущим, например в долях секунды] → тест сравнивает ответ с форматом `isoformat().replace("+00:00", "Z")` на моменте с микросекундами и без них; при расхождении применяется резерв из D3.
- [Строгий `UUID` в python-режиме отвергает корректный `member_ids`] → тест на успешный `POST /chats` закрывает это до остальных правок.
- [Lax-разбор `limit` принимает нестандартную запись вроде `+5`, `05`, `1.0` или `1_0`, которую сейчас отвергает `parse_limit`] → контракт задаёт только целое 1–100; `0`, `101`, `abc` и отсутствие параметра ведут себя как прежде, это подтверждают собственные негативные тесты.
- [Текст `message` в ответе 400 для плохого `limit` или `chat_id` станет общим `MESSAGES["invalid_request"]`] → контракт фиксирует `code`, а не текст; тесты проверяют код.
- [Регрессия горячего пути: на страницу из 50 сообщений строится 50 моделей вместо 50 dict] → контрольный прогон `scripts/bench.py` по сценариям read и write в режиме `pipeline=single+locking=per-chat`; регрессия больше разброса повторов (3.2%) считается блокирующей и разбирается до архивации.
- [Абзац REPORT про `orjson` устаревает] → уточняется отдельной задачей.
## Migration Plan
Миграции нет: состояние живёт в памяти, данных между перезапусками нет. Откат — `git revert` коммитов изменения.
@@ -0,0 +1,37 @@
## Why
На краях сервиса данные описаны нетипизированными `dict[str, Any]`: ответы собираются вручную функциями `*_view`, тело ошибки — `error_body()`, health — литералом, а `limit`, `cursor` и `chat_id` приходят сырыми строками и разбираются внутри слоя application. Форма ответа нигде не объявлена как тип, поэтому ни `ty`, ни FastAPI её не проверяют, а транспортная валидация протекла внутрь (`parse_limit` в `messaging/application/queries.py`, `parse_uuids` в обработчике команды).
Правило изменения: на границе с внешним миром — pydantic-схемы, внутри — dataclass.
## What Changes
- Ответы всех endpoint объявляются pydantic-моделями: `UserOut`, `ChatOut`, `MessageOut`, `PageOut[T]`, `HealthOut`, `ErrorEnvelope`; функции `*_view`, `moment()` и `error_body()` удаляются.
- Query-параметры пагинации описываются моделью `PageQuery`, `chat_id` в path типизируется как `UUID`, `member_ids` в `CreateChatRequest` — как `list[UUID]`. Проверка `limit` и UUID переезжает из application на границу; application и команды получают уже типизированные значения.
- Внутренние dict-«DTO» удаляются как неиспользуемые: `DomainEvent.payload()` (вызывается только тестами) и порт `totals()` (вызовов нет). Событие уже является dataclass и само служит внутренним DTO.
- Инварианты (`username`, длины, пустой текст) остаются в доменных value objects и не дублируются в схемах.
- `HistoryKey` остаётся `tuple`; индексы хранилища, ASGI-сообщения и реестры обработчиков — структуры данных, а не DTO, и не меняются.
Наблюдаемое поведение API не меняется: те же коды, тела, заголовки и `X-Request-Id`.
## Capabilities
### New Capabilities
Нет.
### Modified Capabilities
Нет: изменение — чистый рефакторинг без изменения требований, поэтому в `.openspec.yaml` выставлен `skip_specs: true`.
## Non-goals
Всё из Out of scope лабы 1 остаётся вне изменения. Схемы для брокера событий не вводятся: внешний брокер появится в лабе 5, тогда у него будет своя граница и своя схема. Публикация FastAPI `/openapi.json` не становится заменой `contracts/openapi.json`. Контракт, публичные тесты и рубрика не меняются.
## Impact
- Уровень рубрики: «3» (контракт сохраняется, `make test` проходит) и «4» (собственные негативные тесты подтверждают, что поведение не изменилось). Для трека «5» нужен контрольный прогон, показывающий отсутствие регрессии на горячем пути.
- Строки `REPORT.md`: «**«3»** Все endpoint, форматы ошибок…» (`make test`), «Собственные негативные тесты одной командой» (`make student-test`), «Измерения предела in-memory» (`make bench`); абзац про `orjson` уточняется: успешные ответы сериализует pydantic-core.
- Код: `identity/entrypoints/http.py`, `messaging/entrypoints/http.py`, новые `*/entrypoints/schemas.py`, `shared/entrypoints/{errors,health,pipeline,middleware}.py`, `identity/entrypoints/identification.py`, `messaging/application/{queries,handlers,commands,ports}.py`, `messaging/infrastructure/memory/{store,directory}.py`, `*/domain/events.py`, `shared/domain/events.py`.
- Тесты: `student-tests/api/test_events.py`, `student-tests/unit/test_domain.py` проверяют поля события через `dataclasses.fields` вместо `payload()`.
- Зависимости не меняются.
@@ -0,0 +1,47 @@
## 1. Подготовка и страховочные тесты
- [x] 1.1 Закоммитить текущие незафиксированные правки (`scripts/bench.py`, `main.py`, `shared/entrypoints/config.py`, `REPORT.md`, `evidence/bench/repeats/`) отдельным коммитом, чтобы рефакторинг начинался с чистого дерева
- [x] 1.2 Добавить в `student-tests/api/` тест формата `created_at` у пользователя, чата и сообщения: RFC 3339 UTC с `Z`, совпадение с `isoformat().replace("+00:00", "Z")` на моменте с микросекундами и без них
- [x] 1.3 Добавить тест на `?limit=abc`, отсутствие `limit` (по умолчанию 50) и неизвестный query-параметр (игнорируется), если таких сценариев ещё нет
- [x] 1.4 Проверка: `make student-test` зелёный на текущем коде
## 2. Платформа `shared/entrypoints`
- [x] 2.1 Создать `shared/entrypoints/schemas.py`: `ErrorDetail`, `ErrorEnvelope` с `of(code, message, request_id)` и `HealthOut`
- [x] 2.2 Заменить `error_body()` на `ErrorEnvelope` в `errors.py`, `pipeline.py`, `middleware.py` и удалить `error_body()`
- [x] 2.3 Перевести `/health/live` и `/health/ready` на `-> HealthOut`
- [x] 2.4 Проверка: `make student-test -k "operability or pipeline_modes or timeout"` зелёный
## 3. Зона `identity`
- [x] 3.1 Создать `identity/entrypoints/schemas.py`: перенести `CreateUserRequest`, добавить `UserOut.of(user)` с полями `UUID` и `datetime`
- [x] 3.2 Перевести `create_user` и `current_user` на `-> UserOut`, удалить `user_view()` и `moment()` из `identity/entrypoints/http.py`
- [x] 3.3 Заменить `error_body()` на `ErrorEnvelope` в `identity/entrypoints/identification.py`
- [x] 3.4 Удалить `UserRegistered.payload()`, перевести `student-tests/unit/test_domain.py` на проверку `dataclasses.fields`
- [x] 3.5 Проверка: `make student-test -k "access or negative or domain"` зелёный
## 4. Зона `messaging`: граница
- [x] 4.1 Создать `messaging/entrypoints/schemas.py`: перенести `CreateChatRequest` с `member_ids: list[Annotated[UUID, Field(strict=False)]]` и `CreateMessageRequest`, добавить `PageQuery` с `limit` 1–100 (по умолчанию 50) и `cursor`, добавить `ChatOut`, `MessageOut`, `PageOut[T]` с `of(...)`
- [x] 4.2 Перевести обработчики `messaging/entrypoints/http.py` на `chat_id: UUID`, `Annotated[PageQuery, Query()]` и типизированные ответы; удалить `chat_uuid()`, `moment()` и все `*_view()`
- [x] 4.3 Проверка: успешный `POST /api/v1/chats` с корректными `member_ids` проходит, `make student-test -k "negative or pagination"` зелёный
## 5. Зона `messaging`: application, domain, infrastructure
- [x] 5.1 В `messaging/application/queries.py` принять `limit: int` в `ListChats` и `ReadHistory`, удалить `parse_limit` и `LIMIT_*`
- [x] 5.2 В `messaging/application/commands.py` сменить `CreateChat.member_ids` на `Sequence[UUID]`, в `handlers.py` удалить `parse_uuids`
- [x] 5.3 Удалить `ChatDirectory.totals()` из `ports.py`, адаптера `memory/directory.py` и `memory/store.py`
- [x] 5.4 Удалить `payload()` у `ChatCreated`, `MessagePosted` и базового `DomainEvent`; перевести `student-tests/api/test_events.py` на `dataclasses.fields`
- [x] 5.5 Проверка: `rg "dict\[str, Any\]|payload\(|totals\(" src` не находит DTO-словарей, `make lint` (ruff + ty) и `make student-test` зелёные, `test_bounded_contexts` подтверждает, что `domain/` и `application/` не импортируют pydantic
## 6. Контракт и измерения
- [x] 6.1 Собрать образ, поднять контейнер, прогнать `make test` и `make check`: `PASS: lab1 public API scenario`
- [x] 6.2 Контрольный прогон `scripts/bench.py --scenario read` и `--scenario write` в режиме `pipeline=single+locking=per-chat`, сравнить RPS и p95/p99 с текущими `evidence/bench/repeats/`; регрессия больше 3.2% блокирует архивацию
- [x] 6.3 Проверка: результаты контрольного прогона сохранены в `evidence/bench/`, расхождение с прежними цифрами в пределах разброса
## 7. Отчёт
- [x] 7.1 Уточнить в `REPORT.md` абзац про `orjson`: успешные ответы и тело ошибки сериализует pydantic-core, `orjson` остаётся для журнала
- [x] 7.2 Обновить в таблице доказательств число тестов в строке «Собственные негативные тесты одной командой» и сослаться на файл контрольного прогона
- [x] 7.3 Проверка: `make lint`, `make student-test`, `make check` зелёные, `evidence/student-tests.txt` перезаписан свежим выводом
@@ -0,0 +1,5 @@
schema: spec-driven
created: 2026-10-28
retire_capabilities: true
archived: 2026-10-28
lab: 2
@@ -0,0 +1,104 @@
## Context
Мотивация — в `proposal.md`. Исходная точка — решение лабы 1 (ветка `solution/bpi2303-kostylev` в `mtusi2026lab1`): две зоны `identity` и `messaging`, порты и адаптеры в память, единый ASGI-конвейер с идентификацией раньше разбора тела, шина событий, курсор с HMAC. Ограничения лабы 2, формирующие решение:
- Smoke и persistence-тест сравнивают dict'ы целиком: `Session.user` с ответом регистрации, страницы истории с ответами `POST`, историю после рестарта с исходным сообщением. Формат `created_at` и порядок полей обязаны совпадать до символа.
- Persistence-тест ждёт ответ не дольше 2 с и до 90 с опрашивает готовность после hook.
- Несколько воркеров gunicorn — несколько процессов: ничто, что должно быть общим (секрет курсора, порядок истории), не может жить в памяти одного процесса.
- Изменение касается обеих зон и `shared/`. Новой связи между зонами в коде не появляется: общая точка — схема БД.
## Goals / Non-Goals
**Goals:**
- PostgreSQL — единственный источник истины для пользователей, сессий, чатов, участников и сообщений; адаптеры встают за существующие порты, `domain/` и `application/` не импортируют asyncpg.
- Аутентификация целиком в ASGI-конвейере: `401` раньше доступа и валидации, точные challenge-заголовки, `X-User-Id` не читается вовсе.
- Порядок истории строго определён при нескольких процессах API.
- Стенд поднимается из чистого clone двумя командами, рестартуется hook-ом без потери данных и сессий.
**Non-Goals:**
- Valkey, тесты гонок и отказов, EXPLAIN — изменение уровня «4».
- ORM и генераторы миграций: SQL пишется руками, его план виден напрямую.
- Очистка истёкших сессий фоновым процессом: строки удаляются при следующем входе того же пользователя.
## Decisions
### D1. Что переносится и что удаляется
Переносятся зоны, шина, конвейер, курсор, журнал, схемы pydantic, тесты и тулчейн. Удаляются адаптеры в память, `MemberRegistry` с проекцией `MemberProjection`, ошибка `HistoryOrderViolated`, слоёный конвейер на трёх `BaseHTTPMiddleware` (`PIPELINE=layered`), режимы блокировки `STORAGE_LOCKING` и `scripts/bench.py`. Последние три были измерительными инструментами трека лабы 1: с переездом в PostgreSQL сравнивать их больше не с чем. Что получаем: меньше кода и одно поведение. Чего стоит: эксперимент лабы 1 нельзя повторить на этой ветке — он остаётся в репозитории лабы 1.
### D2. Схема и границы транзакций
```
users(id uuid PK, username text UNIQUE CHECK ~ '^[a-z0-9_]{3,32}$', display_name text CHECK 1..100,
password_hash text, created_at timestamptz)
sessions(token_hash bytea PK CHECK 32 байта, user_id → users ON DELETE CASCADE,
created_at, expires_at CHECK > created_at) индекс (user_id)
chats(id uuid PK, title text CHECK 1..100, created_at, last_message_at timestamptz NULL)
chat_members(chat_id → chats ON DELETE CASCADE, user_id → users, position smallint,
chat_created_at timestamptz, PK (chat_id, user_id)) индекс (user_id, chat_created_at, chat_id)
messages(id uuid PK, chat_id, sender_id, text CHECK 1..4000, created_at,
FK (chat_id, sender_id) → chat_members) индекс (chat_id, created_at, id)
```
Длины в `CHECK` считаются `char_length` — в code points, как в контракте. Составной внешний ключ `messages → chat_members` гарантирует на уровне БД, что отправитель — участник своего чата. `position` хранит порядок `member_ids` из запроса, `chat_created_at` денормализован ради keyset-списка чатов по одному индексу. Индекс истории `(chat_id, created_at, id)` обслуживает keyset-запрос без сортировки; его обоснование планом — в изменении уровня «4».
Транзакции: регистрация — один `INSERT … ON CONFLICT (username) DO NOTHING RETURNING`; вход — удаление истёкших сессий пользователя и вставка новой одним оператором; создание чата — `INSERT chats` и `INSERT chat_members` из `unnest(…) WITH ORDINALITY` в одной транзакции UoW; сообщение — `SELECT … FOR UPDATE` строки чата, `INSERT messages`, `UPDATE chats.last_message_at` в одной транзакции. Чтения идут без явной транзакции, по одному оператору.
### D3. Миграции
`src/messenger/migrations/NNNN_*.sql` поставляются внутри пакета, применяет их `python -m messenger.migrate`: `pg_advisory_lock`, таблица `schema_migrations(version, checksum, applied_at)`, каждая миграция и запись о ней — в одной транзакции, SHA-256 текста сверяется с записанным. Запуск — одноразовый compose-сервис `migrate` на образе приложения; `api` зависит от него `service_completed_successfully`. Альтернатива — миграции при старте каждого воркера — отвергнута: четыре процесса гоняли бы DDL одновременно, а сбой миграции превращался бы в crash-loop API. Чего стоит: ещё один сервис в compose и ~50 строк runner-а вместо готового инструмента.
### D4. Доступ к PostgreSQL: пул, UoW и ошибки зависимости
`shared/infrastructure/postgres.py` — платформа: `Database` над `asyncpg.Pool` (ленивый, `min_size=0`, `max_size` на воркер, таймауты подключения, `acquire`, команды и `statement_timeout` на сервере) и база `PostgresUnitOfWork` (соединение на транзакцию, фиксация явная, откат по умолчанию, сбор событий). SQL только параметризованный (`$1…`). Ошибки сети, таймауты и отказ сервера (`OSError`, `asyncpg.InterfaceError`, `PostgresConnectionError`, классы `57*` и `53*`) превращаются в платформенное `Unavailable` (`shared/application/errors.py`), которое точка входа отдаёт как `503 unavailable`. Нарушения ограничений адаптер зоны переводит в доменные ошибки (`UsernameAlreadyTaken`, `InvalidChatData`). В `shared/` попадает только механизм — пул, транзакция, классификация отказа; ни одной таблицы зоны.
Пул ленивый, поэтому процесс стартует и при недоступной БД: `/health/live` отвечает, `/health/ready` даёт `503` до первого успешного `SELECT 1`. Готовность пингует БД через тот же пул с таймаутом 1 с.
### D5. Пароли и сессии (зона `identity`)
- `Password` — объект-значение (12–128 code points, не только пробелы). Хеш — порт `PasswordHasher`, адаптер `argon2-cffi`: Argon2id, `m=19 MiB, t=2, p=1` (минимум OWASP). Хеширование и проверка идут в пуле потоков под семафором (`PASSWORD_HASH_CONCURRENCY`, по умолчанию 2 на воркер), чтобы не блокировать event loop и ограничить память при всплеске регистраций. Для неизвестного `username` выполняется проверка против заранее вычисленного фиктивного хеша — время ответа не выдаёт существование пользователя.
- Токен — `secrets.token_urlsafe(32)` (43 символа, 256 бит). В БД хранится только `sha256(token)`: у токена полная энтропия, медленный KDF ему не нужен, а утечка таблицы не даёт действующих токенов. В этом и разница с паролем, у которого энтропия мала и перебор надо удорожать.
- `Session(token_hash, user_id, expires_at)`; `expires_at = now + SESSION_TTL_SECONDS`, абсолютный, не продлевается. Проверка — `expires_at > now` по часам приложения: один источник времени для назначения и проверки. Выход — `DELETE` строки.
- Команды `RegisterUser`, `OpenSession`, `CloseSession` идут через `CommandBus` и UoW зоны; запросы `VerifyCredentials` и `Authenticate` — через справочники `UserDirectory` и `SessionDirectory`. События `SessionOpened` и `SessionClosed` пишутся в журнал аудита без токена.
### D6. Аутентификация в конвейере
Страж зоны `identity` (`entrypoints/authentication.py`) вызывается `RequestPipeline` до приложения и возвращает `None` или отказ `Rejection(status, code, headers)`; `Unavailable` из стража конвейер превращает в `503`. Публичны `/health/*` и `POST /api/v1/users`. На `POST /api/v1/auth/sessions` страж разбирает `Basic` своим парсером (строгий base64, первое `:`, UTF-8, ASCII-username) и проверяет пароль; на остальных `/api/v1/*` — `Bearer` (схема без учёта регистра). Challenge выбирает функция `challenge_for(path)` зоны, её же применяет обработчик ошибок `401` внутри приложения. Встроенный `fastapi.security.HTTPBasic` отвергнут: он декодирует ASCII и отвечает своим `401` без `realm`/`charset`. `X-User-Id` не читается нигде. Что получаем: порядок `401 → 404 → 400` держится одним местом. Чего стоит: проверка Argon2 на входе выполняется в конвейере, а не в обработчике.
### D7. Агрегат `Chat` без истории и порядок сообщений
Агрегат больше не держит историю: в памяти это была ссылка, в БД — материализация всей переписки. `Chat` хранит состав и `last_message_at`. `PostMessage` загружает чат `SELECT … FOR UPDATE`, агрегат проверяет членство и назначает `created_at = max(now, last_message_at + 1 мкс)`, адаптер вставляет сообщение и обновляет `last_message_at` в той же транзакции. Блокировка строки сериализует запись в один чат между процессами, поэтому порядок фиксации совпадает с порядком `(created_at, id)`, и keyset-читатель не пропускает сообщение, зафиксированное позже с меньшей отметкой. Это заменяет монотонные часы процесса лабы 1, которые при нескольких воркерах ничего не гарантируют. Чего стоит: запись в один горячий чат идёт последовательно (как блокировка `per-chat` в лабе 1); разные чаты не мешают друг другу. Альтернатива — время БД `clock_timestamp()` без блокировки — отвергнута: отметка назначается до фиксации, и параллельная транзакция может зафиксироваться позже с меньшей отметкой.
Идентификаторы — UUIDv7 (`uuid.uuid7()` в Python 3.14): вставки в B-tree первичных ключей идут в правый край, а порядок при равных отметках по-прежнему задаёт `uuid` как 128-битное число (сравнение `uuid` в PostgreSQL побайтовое и совпадает с `UUID.int`).
### D8. Зоны и общая БД
Проекция `MemberProjection` заменена внешним ключом `chat_members.user_id → users`: проверка «участник существует» выполняется СУБД в транзакции создания чата, и отказ откатывает её целиком. С реестром участников это была бы проекция в отдельной транзакции после фиксации пользователя — окно рассогласования без outbox. SQL зоны `messaging` не читает `users` и `sessions`, зона `identity` не читает таблиц чатов; тест границ проверяет и импорты, и тексты SQL. Событие `UserRegistered` остаётся (журнал аудита).
### D9. Курсор и секреты
`SignedCursorCodec` не меняется, но секрет обязателен и приходит из `CURSOR_SECRET_FILE`: случайный секрет на процесс ломал бы вторую страницу на другом воркере и после рестарта. Платформенный источник настроек читает `<ИМЯ>_FILE` для любого поля (`DATABASE_URL_FILE`, `CURSOR_SECRET_FILE`, позже `CACHE_URL_FILE`). `.env` приложение больше не читает: его использует только compose для подстановки.
### D10. Процесс и контейнер
gunicorn с `WEB_CONCURRENCY` (по умолчанию 4) воркерами `uvicorn_worker.UvicornWorker` (модуль `uvicorn.workers` объявлен устаревшим). Пул на воркер `DB_POOL_MAX_SIZE=8`: 4×8 плюс экземпляры тестов остаются ниже `max_connections=100`. Образ — как в лабе 1: python по digest, non-root `10001`, `SIGTERM` ≤10 с; healthcheck compose проверяет `/health/ready`.
Стенд `compose.yaml`: `postgres` (`postgres:17.11-alpine@sha256:…`, volume `pgdata`, `pg_isready`), `migrate`, `api` (`127.0.0.1:8080`). Учётные данные — compose secrets из `secrets/` (`postgres_password`, `database_url`, `cursor_secret`), их создаёт идемпотентный `scripts/secrets.sh` (`make secrets`) и не перезаписывает существующие. `scripts/restart.sh`: `stop api` → `restart postgres` → `up -d api` (повторно прогоняет `migrate`, что заодно проверяет идемпотентность).
Соответствие `.env.example`: `APP_HOST`/`APP_PORT` → `HOST`/`PORT` (задаёт образ), `APP_ENV` не используется, `SESSION_TTL_SECONDS` → `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE` → `DATABASE_URL_FILE`, `SESSION_STORE=postgres` — фиксированный выбор (PostgreSQL — источник истины), `CACHE_URL_FILE` — изменение уровня «4».
### D11. Собственные тесты
Тесты API по-прежнему поднимают приложение в процессе (httpx + ASGI), но против настоящего PostgreSQL: фикстура сессии запускает одноразовый контейнер того же образа по digest, что и стенд, на случайном порту `127.0.0.1`, применяет миграции runner-ом и удаляет контейнер в конце. SQLite не используется. Публичный `make test` и persistence-тест идут против compose-стенда.
## Risks / Trade-offs
- [Argon2 на входе в конвейере под нагрузкой упирается в CPU] → семафор на воркер, параметры документированы; вход — не горячий путь.
- [Первый запрос после рестарта PostgreSQL получает мёртвое соединение из пула] → asyncpg закрывает соединение по разрыву TCP, ошибка классифицируется как `503`, клиент persistence-теста повторяет запрос.
- [`FOR UPDATE` сериализует запись в горячий чат] → это та же цена, что `per-chat` блокировка лабы 1; измерение стоимости записи — в треке «5».
- [Истёкшие сессии копятся у пользователей, которые больше не входят] → индекс по `user_id` и удаление при входе; фоновой очистки нет, это записано в ограничениях.
- [Секреты в `secrets/` на хосте читаемы контейнерами] → каталог в `.gitignore` и `.dockerignore`, файлы создаются скриптом, значения не печатаются.
## Migration Plan
Перехода данных нет: лаба 1 не хранила состояния. Схема создаётся миграцией `0001_init.sql` на пустом volume. Откат — `git revert` и `make reset-data` (намеренное удаление volumes).
@@ -0,0 +1,39 @@
## Why
Решение лабы 1 держит всё состояние в памяти одного процесса и узнаёт пользователя по `X-User-Id`, которым любой клиент выдаёт себя за другого. Контракт 1.2.0 лабы 2 требует, чтобы пользователи, чаты, сообщения и действующие сессии переживали рестарт API и хранилищ, а запросы связывались с пользователем, доказавшим знание пароля. Изменение закрывает уровень «3» рубрики `README.md` и строки «Публичный smoke», «Persistence» и строки уровня 3 таблицы доказательств `REPORT.md`.
## What Changes
- Решение лабы 1 переносится в skeleton лабы 2: `src/`, `student-tests/`, `Dockerfile`, тулчейн, цели `Makefile`, CI-job.
- **BREAKING** Состояние переезжает в PostgreSQL: таблицы `users`, `sessions`, `chats`, `chat_members`, `messages` с первичными и внешними ключами, `UNIQUE(username)` и `CHECK`. Схема задаётся версионируемыми SQL-миграциями, которые применяет одноразовый сервис `migrate`; повторный запуск ничего не меняет.
- Адаптеры PostgreSQL встают за существующие порты репозиториев, справочников и `UnitOfWork`; адаптеры в память, реестр участников с проекцией и экспериментальные режимы лабы 1 (`PIPELINE=layered`, `STORAGE_LOCKING`, `scripts/bench.py`) удаляются.
- **BREAKING** `POST /api/v1/users` требует `password` (12–128 code points), пароль хранится только как Argon2id. `POST /api/v1/auth/sessions` принимает только `Basic` и выдаёт непрозрачный токен с абсолютным сроком `SESSION_TTL_SECONDS`; в БД лежит лишь его SHA-256. `DELETE /api/v1/auth/sessions/current` отзывает сессию.
- **BREAKING** Все остальные `/api/v1/*` принимают только `Authorization: Bearer`; `X-User-Id` игнорируется. Аутентификация остаётся в ASGI-конвейере раньше доступа и валидации; `401` несёт точный `WWW-Authenticate` контракта.
- Порядок истории при нескольких воркерах держит агрегат `Chat`: запись сообщения блокирует строку чата, и `created_at` строго возрастает в порядке фиксации.
- Курсор подписывается постоянным секретом из `secrets/`, поэтому переживает рестарт и работает при нескольких воркерах.
- Стенд — Docker Compose: `postgres` по digest с именованным volume, `migrate`, `api` (gunicorn с несколькими `UvicornWorker`, готовность пингует БД). Секреты — compose secrets из gitignored `secrets/`, генерируемых `make secrets`; `scripts/restart.sh` перезапускает API и PostgreSQL без удаления volumes.
## Capabilities
### New Capabilities
- `lab2-auth-sessions`: пароль и KDF, вход `Basic`, `Bearer`-сессии с абсолютным TTL, отзыв, игнорирование `X-User-Id`, challenge-заголовки `401`.
- `lab2-persistent-storage`: схема PostgreSQL с ограничениями, версионируемые миграции, атомарное создание чата, сохранность данных и сессий при рестарте, воспроизводимый стенд, секреты вне Git.
### Modified Capabilities
- `lab1-messenger-identity`: регистрация с паролем; идентификация по `X-User-Id` и требование «пользователи не переживают перезапуск» снимаются.
- `lab1-messenger-chats`: запрос без действительной сессии вместо запроса без `X-User-Id`.
- `lab1-messenger-history`: порядок истории гарантируется при нескольких процессах API.
- `lab1-service-operability`: готовность зависит от PostgreSQL; логи без токенов и паролей; требование «состояние только в памяти» снимается.
- `lab1-event-publication`: зоны связаны событием и внешним ключом схемы вместо проекции; событиям по-прежнему не нужен брокер.
- `lab1-inmemory-capacity`: трек «5» лабы 1 о пределе памяти снимается вместе с in-memory хранением.
## Impact
- Код: все зоны `src/messenger/**`, новые `migrate.py`, `migrations/0001_init.sql`, `shared/infrastructure/postgres.py`; удаляются `*/infrastructure/memory/`, `messaging/application/projections.py`, `shared/entrypoints/middleware.py`.
- Стенд: `compose.yaml`, `scripts/secrets.sh`, `scripts/restart.sh`, `.env.example`, `.dockerignore`, `Makefile`, `.github/workflows/application.yml`.
- Зависимости: `asyncpg`, `argon2-cffi`, `uvicorn-worker`; образ `postgres:17.11-alpine` по digest.
- Отчёт: `REPORT.md` (запуск, архитектура, строки уровня 3), `evidence/`.
## Non-goals
Valkey, гонки, rollback-тест, индекс истории с EXPLAIN и автотесты отказов — следующее изменение уровня «4»; трек «5» — третье. Из Out of scope лабы 2 не появляется ничего: реплики за балансировщиком и `Idempotency-Key` (лаба 3), S3 (лаба 4), брокер и worker (лаба 5), OTel (лаба 6), TLS (лаба 7). Контракт, публичные тесты, `README.md` и `COURSE.md` не меняются.
@@ -0,0 +1,48 @@
## ADDED Requirements
### Requirement: Публикация событий не требует брокера
Публикация событий SHALL выполняться через порт, реализованный внутренней очередью в памяти процесса. Доставка событий SHALL NOT зависеть от внешнего брокера; из сетевых сервисов обязательный API зависит только от PostgreSQL.
#### Scenario: События доставляются без брокера
- **WHEN** стенд поднят без брокера сообщений
- **THEN** весь обязательный API работает, а события доставляются внутренней очередью
#### Scenario: Публикация скрыта за портом
- **WHEN** проверяется слой приложения
- **THEN** он обращается к публикации только через порт и не знает её реализации
## MODIFIED Requirements
### Requirement: Доменные зоны связаны только событиями
Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» и импортировать её модули, кроме объявления события о регистрации. Существование участника SHALL проверяться внешним ключом схемы БД в той же транзакции, что и запись чата; SQL каждой зоны SHALL читать только таблицы своей зоны.
#### Scenario: Регистрация видна чатам сразу
- **WHEN** пользователь зарегистрирован и немедленно создаёт чат со своим участием
- **THEN** чат создаётся успешно: ответ регистрации отправлен после фиксации пользователя в БД
#### Scenario: Неизвестный зоне участник отклоняется
- **WHEN** в состав чата передан идентификатор, которому не соответствует ни один пользователь
- **THEN** ответ `400` с кодом `invalid_request`, чат не создаётся
#### Scenario: Зона пользователей не знает о чатах
- **WHEN** проверяется список зависимостей модулей зоны «пользователи»
- **THEN** среди них нет ни одного модуля зоны «чаты и сообщения»
#### Scenario: Обратная связь идёт только через контракт события
- **WHEN** проверяется список зависимостей модулей зоны «чаты и сообщения»
- **THEN** единственная заимствованная у зоны «пользователи» единица — объявление события о регистрации, а SQL зоны не упоминает таблиц `users` и `sessions`
## REMOVED Requirements
### Requirement: Доставка событий не требует внешних сервисов
**Reason**: С лабы 2 обязательный API зависит от PostgreSQL, поэтому формулировка «ни одного внешнего сервиса» больше неверна.
**Migration**: Требование «Публикация событий не требует брокера» этой же capability.
@@ -0,0 +1,16 @@
## REMOVED Requirements
### Requirement: Повторяемая методика измерения
**Reason**: Трек «5» лабы 1 измерял предел хранения в памяти одного процесса; с лабы 2 этого хранения нет.
**Migration**: Повторяемая методика трека «5» лабы 2 — `lab2-query-plan-recovery` (вводится третьим изменением).
### Requirement: Наблюдаемый предел хранения в памяти
**Reason**: Сообщения больше не хранятся в памяти процесса API, RSS не растёт с историей.
**Migration**: Стоимость хранения измеряется размером таблиц и индексов PostgreSQL в треке «5» лабы 2.
### Requirement: Узкое место названо и подтверждено изменением
**Reason**: Требование относилось к эксперименту in-memory архитектуры лабы 1.
**Migration**: Сравнение вариантов индексов и запросов «до/после» — в треке «5» лабы 2.
@@ -0,0 +1,32 @@
## MODIFIED Requirements
### Requirement: Создание чата
Сервис SHALL принимать `POST /api/v1/chats` от аутентифицированного пользователя с телом `{"title":..., "member_ids":[...]}` и возвращать `201` с объектом `Chat`. `title` SHALL содержать от 1 до 100 code points и не состоять только из пробельных символов. `member_ids` SHALL содержать от 1 до 100 уникальных идентификаторов существующих пользователей и SHALL включать вызывающего. Чат SHALL создаваться атомарно: при любой ошибке валидации он не создаётся вовсе.
#### Scenario: Чат создан
- **WHEN** участник отправляет `POST /api/v1/chats` с корректным `title` и списком из своего и чужого идентификаторов
- **THEN** ответ `201`, тело соответствует схеме `Chat`, `member_ids` совпадает с запрошенным составом
- **AND** `id` и `created_at` назначены сервером
#### Scenario: Вызывающий не входит в состав
- **WHEN** `member_ids` не содержит идентификатора вызывающего
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Состав содержит дубликаты
- **WHEN** `member_ids` содержит один и тот же идентификатор дважды
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Состав содержит неизвестного пользователя
- **WHEN** `member_ids` содержит идентификатор, которому не соответствует ни один пользователь
- **THEN** ответ `400` с кодом `invalid_request`
- **AND** чат не создаётся
#### Scenario: Запрос без идентификации
- **WHEN** `POST /api/v1/chats` приходит без `Authorization: Bearer` или с недействительным токеном
- **THEN** ответ `401` с кодом `unauthorized` и `WWW-Authenticate: Bearer realm="messenger"`
@@ -0,0 +1,21 @@
## MODIFIED Requirements
### Requirement: Порядок истории
История чата SHALL быть упорядочена по паре `(created_at, id)` по возрастанию. Время SHALL назначаться сервером в формате RFC 3339 UTC с суффиксом `Z`. Сервис SHALL гарантировать, что `created_at` внутри одного чата строго возрастает в порядке фиксации сообщений, в том числе при конкурентных вставках через разные процессы API, — иначе обход истории keyset-курсором теряет запись, зафиксированную позже с меньшей отметкой.
#### Scenario: Сообщения возвращаются в порядке приёма
- **WHEN** в чат последовательно отправлены два сообщения от разных участников
- **THEN** `GET /api/v1/chats/{chat_id}/messages` возвращает их в порядке отправки
#### Scenario: Конкурентная запись не ломает порядок
- **WHEN** 10 клиентов параллельно отправляют по 10 сообщений в один чат
- **THEN** история содержит ровно 100 сообщений с попарно различными `id`
- **AND** `created_at` строго возрастает по всей истории
#### Scenario: Отметка не уходит назад при отставших часах процесса
- **WHEN** процесс API назначает сообщению отметку меньше, чем у последнего зафиксированного сообщения чата
- **THEN** сообщение получает отметку на одну микросекунду больше последней, и порядок истории сохраняется
@@ -0,0 +1,58 @@
## MODIFIED Requirements
### Requirement: Регистрация пользователя
Сервис SHALL принимать `POST /api/v1/users` без аутентификации и возвращать `201` с объектом `User`, содержащим назначенные сервером `id` и `created_at`. Тело запроса SHALL содержать ровно поля `username`, `display_name` и `password`. `username` SHALL соответствовать `^[a-z0-9_]{3,32}$` и быть уникальным, `display_name` SHALL содержать от 1 до 100 Unicode code points и не состоять только из пробельных символов, требования к `password` задаёт `lab2-auth-sessions`. Ответ SHALL NOT содержать полей, отсутствующих в схеме `User`. Уникальность SHALL соблюдаться и при конкурентной регистрации одного `username`: успешной будет ровно одна, остальные получат `409`.
#### Scenario: Пользователь создан
- **WHEN** приходит `POST /api/v1/users` с телом `{"username":"alice_01","display_name":"Алиса","password":"<12+ символов>"}`
- **THEN** ответ `201`, тело соответствует схеме `User`, `username` и `display_name` совпадают с запросом
- **AND** `id` — UUID, назначенный сервером, `created_at` — RFC 3339 UTC с суффиксом `Z`
#### Scenario: Username занят
- **WHEN** приходит `POST /api/v1/users` с `username`, уже принадлежащим другому пользователю
- **THEN** ответ `409` с телом ошибки и кодом `conflict`
#### Scenario: Username нарушает формат
- **WHEN** `username` содержит заглавные буквы, дефис, пробел, перевод строки или имеет длину вне 3–32 символов
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Display_name пуст или состоит из пробелов
- **WHEN** `display_name` равен `""`, `" "` или длиннее 100 code points
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Тело запроса нарушает схему
- **WHEN** тело содержит лишнее поле, неверный тип поля, не содержит обязательного поля (в том числе `password`) или не является корректным JSON
- **THEN** ответ `400` с кодом `invalid_request`
- **AND** сообщение ошибки не содержит stack trace и внутренних деталей реализации
#### Scenario: Регистрация не требует идентификации
- **WHEN** `POST /api/v1/users` приходит без заголовка `Authorization`
- **THEN** запрос обрабатывается на общих основаниях, ответ не равен `401`
### Requirement: Чтение текущего пользователя
Сервис SHALL отдавать по `GET /api/v1/users/me` объект `User` владельца предъявленной `Bearer`-сессии в том же виде, в каком он был возвращён при регистрации.
#### Scenario: Текущий пользователь возвращён
- **WHEN** приходит `GET /api/v1/users/me` с действительным `Bearer`-токеном пользователя
- **THEN** ответ `200`, тело соответствует схеме `User` и совпадает с телом ответа его регистрации
## REMOVED Requirements
### Requirement: Идентификация запроса заголовком X-User-Id
**Reason**: Контракт 1.2.0 заменяет учебную идентификацию аутентификацией: `X-User-Id` с лабы 2 игнорируется.
**Migration**: Получить токен `POST /api/v1/auth/sessions` с `Basic` и передавать `Authorization: Bearer <token>`; правила описаны в `lab2-auth-sessions`.
### Requirement: Состояние пользователей не переживает перезапуск
**Reason**: С лабы 2 пользователи хранятся в PostgreSQL и обязаны переживать рестарт.
**Migration**: Требование «Данные и сессии переживают рестарт» в `lab2-persistent-storage`.
@@ -0,0 +1,56 @@
## MODIFIED Requirements
### Requirement: Пробы жизни и готовности
Сервис SHALL отвечать на `GET /health/live` кодом `200` с телом `{"status":"ok"}`, проверяя только жизнь процесса. Сервис SHALL отвечать на `GET /health/ready` кодом `200` с тем же телом, только если в момент запроса выполнен запрос к PostgreSQL за ограниченное время, и кодом `503` с телом ошибки в общем формате в противном случае. Пробы SHALL NOT требовать аутентификации. Недоступность необязательных зависимостей SHALL NOT переводить готовность в `503`.
#### Scenario: Проба жизни отвечает без идентификации
- **WHEN** приходит `GET /health/live` без заголовка `Authorization`
- **THEN** ответ `200` с телом `{"status":"ok"}`
#### Scenario: Готовность подтверждена
- **WHEN** приходит `GET /health/ready`, а PostgreSQL доступен
- **THEN** ответ `200` с телом `{"status":"ok"}`
#### Scenario: Готовность не зависит от внешних сервисов
- **WHEN** проверяется готовность, а недоступна только необязательная зависимость
- **THEN** ответ `200`: из внешних сервисов готовность зависит лишь от PostgreSQL
#### Scenario: Готовность отражает PostgreSQL
- **WHEN** PostgreSQL остановлен
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable`, а `GET /health/live` — `200`
#### Scenario: Сервис остановлен
- **WHEN** процесс получил сигнал остановки и перестал принимать новую работу
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable` либо соединение не устанавливается
### Requirement: Логи без содержимого сообщений
Сервис SHALL писать в stdout/stderr структурированную запись на каждый запрос с методом, шаблоном маршрута, кодом ответа, длительностью и `X-Request-Id`. Логи SHALL NOT содержать текста сообщений, `display_name`, паролей, токенов сессий, значений заголовка `Authorization`, строк подключения к хранилищам и тел запросов.
#### Scenario: Запись о запросе присутствует
- **WHEN** обработан любой запрос к API
- **THEN** в stdout появляется запись с методом, шаблоном маршрута, кодом ответа и идентификатором запроса
#### Scenario: Текст сообщения не попадает в логи
- **WHEN** отправлено сообщение с известным текстом-маркером
- **THEN** этот текст отсутствует в stdout и stderr процесса
#### Scenario: Учётные данные не попадают в логи
- **WHEN** пользователь зарегистрировался, вошёл и выполнил запрос с токеном
- **THEN** ни пароль, ни токен, ни значение `Authorization` не встречаются в stdout и stderr процесса
## REMOVED Requirements
### Requirement: Состояние живёт только в памяти процесса
**Reason**: С лабы 2 обязательное состояние хранится в PostgreSQL и переживает рестарт процесса.
**Migration**: Требования `lab2-persistent-storage`.
@@ -0,0 +1,123 @@
## Purpose
Определяет, как пользователь доказывает знание пароля, получает непрозрачную сессию с абсолютным сроком жизни, предъявляет её на защищённых endpoint и отзывает её. Заменяет учебную идентификацию `X-User-Id` лабы 1.
## ADDED Requirements
### Requirement: Пароль хранится только как password KDF
Сервис SHALL хранить пароль пользователя только в виде хеша библиотечного password KDF Argon2id с солью. Пароль, его хеш и сессионные данные SHALL NOT входить в объект `User` и SHALL NOT попадать в журнал. Пароль SHALL содержать от 12 до 128 Unicode code points и SHALL NOT состоять только из пробельных символов.
#### Scenario: В хранилище нет открытого пароля
- **WHEN** пользователь зарегистрирован с паролем
- **THEN** запись пользователя в БД содержит строку, начинающуюся с `$argon2id$`, и не содержит пароля
#### Scenario: Пароль вне допустимой длины
- **WHEN** `POST /api/v1/users` содержит `password` короче 12 или длиннее 128 code points
- **THEN** ответ `400` с кодом `invalid_request`, пользователь не создаётся
#### Scenario: Пароль из одних пробелов
- **WHEN** `password` состоит только из пробельных символов
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Ответ регистрации без пароля
- **WHEN** пользователь успешно зарегистрирован
- **THEN** тело `201` содержит ровно `id`, `username`, `display_name`, `created_at`
### Requirement: Вход по Basic выдаёт сессию
Сервис SHALL принимать `POST /api/v1/auth/sessions` только с заголовком `Authorization: Basic <base64(username:password)>` и без тела. Декодирование base64 SHALL быть строгим, разделителем SHALL служить первое двоеточие, пароль SHALL декодироваться как UTF-8. При верных учётных данных ответ SHALL быть `201` с телом `{"token","token_type":"Bearer","expires_at","user"}`, где `token` — непрозрачная случайная строка не короче 32 символов с энтропией не менее 256 бит, `expires_at` — RFC 3339 UTC с `Z`, а `user` совпадает с ответом регистрации. Неверный пароль, неизвестный `username`, отсутствующий и испорченный заголовок SHALL давать одинаковый `401` с кодом `unauthorized` и заголовком `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
#### Scenario: Успешный вход
- **WHEN** зарегистрированный пользователь отправляет верные `username:password` в `Basic`
- **THEN** ответ `201`, тело соответствует схеме `Session`, `token_type` равен `Bearer`
- **AND** `user` побайтно равен телу ответа его регистрации, `expires_at` в будущем
#### Scenario: Неверный пароль и неизвестный пользователь неразличимы
- **WHEN** приходит `Basic` с неверным паролем существующего пользователя или с несуществующим `username`
- **THEN** оба ответа — `401` с кодом `unauthorized` и `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`
- **AND** тела ответов различаются только `request_id`
#### Scenario: Испорченный заголовок Basic
- **WHEN** заголовок отсутствует, содержит другую схему, невалидный base64 или строку без двоеточия
- **THEN** ответ `401` с тем же заголовком `WWW-Authenticate: Basic ...`
#### Scenario: Двоеточие в пароле
- **WHEN** пароль пользователя содержит двоеточие и он входит по `Basic`
- **THEN** ответ `201`: разделителем служит первое двоеточие
#### Scenario: Тело запроса при входе
- **WHEN** запрос с верным `Basic` содержит тело
- **THEN** ответ `400` с кодом `invalid_request`, сессия не создаётся
### Requirement: Защищённые endpoint принимают только Bearer
Все `/api/v1/*`, кроме `POST /api/v1/users` и `POST /api/v1/auth/sessions`, SHALL требовать `Authorization: Bearer <token>`; схема сравнивается без учёта регистра. Отсутствующий, неизвестный, истёкший и отозванный токен, а также `Basic` на этих endpoint SHALL давать `401` с кодом `unauthorized` и `WWW-Authenticate: Bearer realm="messenger"`. Заголовок `X-User-Id` SHALL игнорироваться: он не даёт доступа и не меняет владельца сессии. Аутентификация SHALL выполняться раньше проверки доступа к ресурсу и раньше валидации пути, параметров и тела.
#### Scenario: Только X-User-Id
- **WHEN** `GET /api/v1/users/me` приходит с `X-User-Id` существующего пользователя и без `Authorization`
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
#### Scenario: X-User-Id не подменяет владельца
- **WHEN** `GET /api/v1/users/me` приходит с `Bearer` пользователя alice и `X-User-Id` пользователя eve
- **THEN** ответ `200` с пользователем alice
#### Scenario: Basic на бизнес-endpoint
- **WHEN** `GET /api/v1/users/me` приходит с верным `Basic`
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
#### Scenario: Неизвестный токен
- **WHEN** запрос несёт `Bearer` со случайной строкой
- **THEN** ответ `401` с кодом `unauthorized`
#### Scenario: Аутентификация раньше валидации
- **WHEN** `POST /api/v1/chats/not-a-uuid/messages` приходит без `Authorization` и с испорченным JSON
- **THEN** ответ `401`, а не `400`
### Requirement: Абсолютный срок жизни сессии
Срок жизни сессии SHALL задаваться `SESSION_TTL_SECONDS` (по умолчанию 3600) от момента входа и SHALL NOT продлеваться ни использованием, ни рестартом сервиса. После `expires_at` токен SHALL давать `401`.
#### Scenario: Срок назначен при входе
- **WHEN** пользователь вошёл
- **THEN** `expires_at` равен моменту входа плюс `SESSION_TTL_SECONDS` секунд
#### Scenario: Истёкший токен
- **WHEN** сервис запущен с `SESSION_TTL_SECONDS=2` и токен предъявлен через 3 секунды после входа
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
### Requirement: Отзыв текущей сессии
`DELETE /api/v1/auth/sessions/current` SHALL отзывать предъявленный токен и отвечать `204` без тела. После отзыва этот токен SHALL давать `401`, в том числе на повторный `DELETE`. Остальные сессии того же пользователя SHALL оставаться действительными.
#### Scenario: Выход
- **WHEN** пользователь отправляет `DELETE /api/v1/auth/sessions/current` со своим токеном
- **THEN** ответ `204` с пустым телом и непустым `X-Request-Id`
- **AND** следующий `GET /api/v1/users/me` с этим токеном получает `401`
#### Scenario: Повторный выход
- **WHEN** `DELETE /api/v1/auth/sessions/current` повторяется с уже отозванным токеном
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
#### Scenario: Другая сессия не затронута
- **WHEN** пользователь вошёл дважды и отозвал первую сессию
- **THEN** второй токен продолжает получать `200`
@@ -0,0 +1,76 @@
## Purpose
Определяет постоянное хранение лабы 2: схему PostgreSQL с ограничениями, версионируемые миграции, атомарность составных операций, сохранность данных и сессий при рестарте и воспроизводимый стенд из репозитория без секретов в Git.
## ADDED Requirements
### Requirement: Схема с ограничениями целостности
PostgreSQL SHALL хранить пользователей, сессии, чаты, участников и сообщения в отдельных таблицах с первичными ключами. Уникальность `username` SHALL обеспечиваться ограничением БД. Участник чата SHALL ссылаться на существующего пользователя и существующий чат, сообщение SHALL ссылаться на участника своего чата, сессия — на пользователя. Схема SHALL дублировать правила контракта проверками `CHECK` (формат `username`, длины строк).
#### Scenario: Ограничения видны в схеме
- **WHEN** оператор выполняет `\d+` по таблицам `users`, `chat_members`, `messages`
- **THEN** видны `PRIMARY KEY`, `UNIQUE (username)` и внешние ключи `chat_members → users, chats`, `messages → chat_members`
#### Scenario: Сообщение от постороннего не записывается даже в обход API
- **WHEN** в `messages` вставляется строка, отправитель которой не состоит в чате
- **THEN** вставка отклоняется нарушением внешнего ключа
### Requirement: Версионируемые миграции
Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одноразовым процессом до старта API, одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой.
#### Scenario: Миграции с пустого volume
- **WHEN** стенд поднимается на пустом volume PostgreSQL
- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартует API
#### Scenario: Повторный запуск
- **WHEN** процесс миграций запускается повторно на той же БД
- **THEN** он завершается кодом 0, журнал версий и число строк во всех таблицах не меняются
#### Scenario: Изменённая миграция
- **WHEN** текст применённой миграции изменён и процесс миграций запущен
- **THEN** процесс завершается ненулевым кодом и схему не трогает
### Requirement: Атомарное создание чата
Создание чата SHALL записывать чат и всех его участников в одной транзакции. Если хотя бы одна запись нарушает ограничение, транзакция SHALL откатываться целиком: ни строки чата, ни строк участников не остаётся.
#### Scenario: Неизвестный участник откатывает чат
- **WHEN** `POST /api/v1/chats` содержит в `member_ids` UUID несуществующего пользователя
- **THEN** ответ `400` с кодом `invalid_request`
- **AND** в БД нет ни чата с этим `title`, ни его участников
### Requirement: Данные и сессии переживают рестарт
Пользователи, чаты, участники, сообщения и ещё действующие сессии SHALL сохраняться при перезапуске API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, а подтверждённое сообщение SHALL читаться побайтно тем же.
#### Scenario: Полный рестарт стенда
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
- **THEN** hook перезапускает API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`
#### Scenario: Логаут после рестарта
- **WHEN** после рестарта пользователь отзывает прежний токен
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
### Requirement: Воспроизводимый стенд из репозитория
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck. Наружу SHALL публиковаться только API на `127.0.0.1:8080`. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, и SHALL NOT появляться в Git, образе и журнале.
#### Scenario: Подъём из чистого clone
- **WHEN** в чистом clone выполняются `make secrets` и `make up`
- **THEN** все сервисы становятся `healthy` или завершаются кодом 0, а `GET /health/ready` отвечает `200`
#### Scenario: Секреты и volumes вне Git
- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url .env`
- **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
@@ -0,0 +1,52 @@
## 1. Перенос решения лабы 1
- [x] 1.1 Перенести из `mtusi2026lab1` (ветка `solution/bpi2303-kostylev`) `src/`, `student-tests/`, `Dockerfile`, `pyproject.toml`, `uv.lock`, цели `Makefile`, `.github/workflows/application.yml`, дополнения `.dockerignore`; версия пакета — `1.2.0`
- [x] 1.2 Проверка группы: `uv sync --group dev`, `make lint`, `make check` проходят на перенесённом коде
## 2. Схема и миграции
- [x] 2.1 Написать `src/messenger/migrations/0001_init.sql`: таблицы `users`, `sessions`, `chats`, `chat_members`, `messages` с PK, FK, `UNIQUE(username)`, `CHECK` и индексами из design D2
- [x] 2.2 Платформа `shared/infrastructure/postgres.py`: `Database` (ленивый пул, таймауты, `ping`, классификация отказа в `Unavailable`) и база `PostgresUnitOfWork`; `Unavailable` в `shared/application/errors.py`
- [x] 2.3 Runner `src/messenger/migrate.py`: advisory lock, `schema_migrations` с checksum, транзакция на файл, отказ на изменённой миграции
- [x] 2.4 Источник настроек `<ИМЯ>_FILE` в `shared/config.py`; `database_url` и параметры пула в `PlatformSettings`; приложение не читает `.env`
- [x] 2.5 Проверка группы: тест runner-а — с нуля применяет все версии, повтор ничего не меняет, изменённая миграция отклоняется
## 3. Зона `identity`
- [x] 3.1 Домен: объект-значение `Password`, поле `password_hash` у `User`, сущность `Session` с выпуском токена и `sha256`, события `SessionOpened` и `SessionClosed`
- [x] 3.2 Приложение: порты `PasswordHasher`, `SessionRepository`, `SessionDirectory`, расширенные `UserDirectory`/`IdentityUnitOfWork`; команды и обработчики `RegisterUser` (с паролем), `OpenSession`, `CloseSession`; запросы `VerifyCredentials` (с фиктивной проверкой) и `Authenticate`
- [x] 3.3 Инфраструктура: адаптер Argon2id в пуле потоков под семафором; адаптеры PostgreSQL пользователей и сессий; `UsernameAlreadyTaken` из `ON CONFLICT DO NOTHING`
- [x] 3.4 Точка входа: `IdentitySettings` (`SESSION_TTL_SECONDS`, `PASSWORD_HASH_CONCURRENCY`), схемы `CreateUserRequest` с `password` и `SessionOut`, роутеры `/api/v1/users` и `/api/v1/auth/sessions`, провайдер DI, журнал
- [x] 3.5 Страж `entrypoints/authentication.py`: строгий парсер `Basic`, разбор `Bearer`, `challenge_for(path)`, публичные маршруты, `X-User-Id` не читается
- [x] 3.6 Проверка группы: юнит-тесты `Password`, парсеров `Basic`/`Bearer` и выпуска токена; API-тесты входа, неверного пароля, неизвестного пользователя, Basic на бизнес-endpoint, только `X-User-Id`, выхода и повторного выхода
## 4. Зона `messaging`
- [x] 4.1 Домен: `Chat` без истории, с `last_message_at` и правилом `created_at = max(now, last + 1 мкс)`; удалить `HistoryOrderViolated`, проверку известных участников и реестр
- [x] 4.2 Приложение: порты `ChatRepository` (`add`, `get` с блокировкой, `append`), `MessagingUnitOfWork`, `ChatDirectory`; удалить `MemberRegistry` и `MemberProjection`
- [x] 4.3 Инфраструктура: адаптеры PostgreSQL — создание чата двумя операторами в транзакции с переводом FK-нарушения в `InvalidChatData`, запись сообщения под `FOR UPDATE`, keyset-запросы списка чатов и истории (`limit + 1`), отдельный текст запроса для первой страницы
- [x] 4.4 Обязательный `CURSOR_SECRET` (`CURSOR_SECRET_FILE`), удалить случайный секрет и `STORAGE_LOCKING`
- [x] 4.5 Проверка группы: API-тесты создания чата с неизвестным участником (`400`, строк нет), пагинации списка и истории, курсора чужого чата, конкурентной записи 100 сообщений от 10 клиентов со строго возрастающим `created_at`
## 5. Платформа и сборка
- [x] 5.1 Конвейер: страж возвращает `Rejection` с заголовками, `Unavailable` из стража → `503`; удалить `PIPELINE=layered` и `shared/entrypoints/middleware.py`
- [x] 5.2 Обработчики ошибок: `Unavailable` → `503`, `401` из приложения получает challenge зоны; `/health/ready` пингует БД
- [x] 5.3 `main.py`: провайдер `Database` с закрытием пула, связывание журналов без проекций; генератор UUIDv7
- [x] 5.4 `gunicorn_conf.py`: `uvicorn_worker.UvicornWorker`, `WEB_CONCURRENCY` воркеров
- [x] 5.5 Проверка группы: `make lint`, тест границ зон (импорты и SQL зон), `make student-test` зелёные
## 6. Стенд
- [x] 6.1 `compose.yaml`: `postgres` по digest с volume `pgdata` и `pg_isready`, `migrate` на образе приложения, `api` на `127.0.0.1:8080` с healthcheck готовности; compose secrets; процессы не от root
- [x] 6.2 `scripts/secrets.sh` (`make secrets`): идемпотентная генерация `secrets/*` и `.env` из `.env.example`; дополнить `.env.example` (`CURSOR_SECRET_FILE`, `WEB_CONCURRENCY`)
- [x] 6.3 `scripts/restart.sh`: остановить API, перезапустить PostgreSQL, поднять API (с повторным `migrate`), без удаления volumes
- [x] 6.4 Цели `Makefile`: `secrets`, `up`, `down`, `reset-data`, `migrate`, `ps`, `logs`, `restart-evidence`; существующие цели skeleton не меняются
- [x] 6.5 CI-job приложения: lint и собственные тесты, затем сборка стенда, `make test` и persistence-тест
- [x] 6.6 Проверка группы: из чистого состояния `make secrets up`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, повторный `make migrate` без изменений
## 7. Отчёт и доказательства
- [x] 7.1 Сохранить в `evidence/` обезличенные выводы: smoke, persistence с `StartedAt` до и после, `\d+` схемы, повторные миграции, `$argon2id$`-префикс, `git check-ignore`, собственные тесты
- [x] 7.2 Заполнить `REPORT.md`: шапка, запуск из чистого clone, архитектура и решения, соответствие переменных, строки уровня «3»
- [x] 7.3 Проверка группы: `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` зелёные
@@ -0,0 +1,4 @@
schema: spec-driven
created: 2026-10-28
archived: 2026-10-28
lab: 2
@@ -0,0 +1,62 @@
## Context
Мотивация — в `proposal.md`. После уровня «3» каждая проверка `Bearer` — запрос `SELECT … FROM sessions WHERE token_hash = $1` к PostgreSQL. Пул, таймауты и перевод сетевых ошибок в `503` уже есть, но не проверены на живом стенде. Изменение касается только зоны `identity` (кэш сессий), стенда и тестов; новой связи между зонами нет.
## Goals / Non-Goals
**Goals:**
- Valkey с одной ролью — кэш сессий, — которую можно назвать, измерить и сломать без потери данных и без открытия доступа.
- Каждый отказ зависимости из рубрики проверяется автотестом против стенда с кодом ответа и временем.
- Индекс истории обоснован реальным планом на ≥10 000 сообщений.
**Non-Goals:**
- Кэш истории и списков: read-after-write из контракта дороже, чем экономия.
- Valkey как единственное хранилище сессий.
- Сравнение вариантов индексов, стоимость записи, backup — трек «5».
## Decisions
### D1. Роль Valkey: read-through кэш сессий, PostgreSQL — источник истины
Порт `SessionDirectory` уже отделяет проверку сессии от хранения. Новый адаптер `CachedSessionDirectory` (`identity/infrastructure/valkey.py`) оборачивает `PostgresSessionDirectory` — паттерн «декоратор» за тем же портом, домен и обработчики не меняются. Ключ — `session:<hex sha256(token)>`, значение — `user_id`, `created_at`, `expires_at`; токен в открытом виде в кэш не попадает.
- Чтение: `GET`; отметка отзыва → `None` (401); значение → сессия, если `expires_at > now`; промах → PostgreSQL, затем `SET … NX PXAT min(expires_at, now + SESSION_CACHE_TTL_SECONDS)`.
- Expiry: `PXAT` от сохранённого `expires_at` (абсолютный срок), а не `EXPIRE ttl` при каждой записи, поэтому повторное заполнение не продлевает сессию. Ограничение `SESSION_CACHE_TTL_SECONDS` (300 с) — страховка: даже при ошибке инвалидации устаревшая запись живёт не дольше пяти минут.
- Инвалидация: `CloseSession` сначала пишет отметку отзыва `SET key "-" PXAT expires_at` (перетирая значение), затем удаляет строку в БД. Заполнение идёт только с `NX`, поэтому гонка «читатель достал сессию из БД до удаления и положил её в кэш после» не оживляет токен: его `SET NX` не перетрёт отметку. Если отметку записать нельзя, выход отвечает `503` и строку в БД не трогает — иначе после возвращения Valkey из AOF могла бы ожить закэшированная запись.
Что получаем: проверка сессии без обращения к БД на горячем пути, `FLUSHALL` безвреден (источник истины цел). Чего стоит: выход зависит от Valkey; ещё один сервис в стенде.
### D2. Обход недоступного Valkey
Клиент `redis.asyncio` с таймаутами подключения и чтения 0.2 с и одним немедленным повтором: после рестарта Valkey первая команда на старом соединении падает, повтор идёт уже по новому. Любая ошибка кэша (`RedisError`, `OSError`) на чтении и заполнении глотается: проверка идёт в PostgreSQL. Чтобы не платить таймаут на каждом запросе, простой размыкатель после ошибки пропускает кэш `CACHE_COOLDOWN_SECONDS` (1 с). Запрос при этом не становится анонимным: результат даёт только PostgreSQL, а его отказ — `503`. Готовность от Valkey не зависит: кэш не критичен для обязательного пути.
### D3. Persistence Valkey
AOF с `appendfsync always` на volume `valkeydata`: подтверждённая запись отметки отзыва уже на диске, поэтому рестарт или падение Valkey не возвращает закэшированную запись без её отметки. Частота записей низкая (вход, первое чтение сессии, выход), так что fsync на запись не заметен. `everysec` отвергнут: потеря последней секунды могла бы потерять отметку отзыва при живой записи сессии. Пароль `requirepass` лежит в `secrets/valkey.conf`, URL с паролем — в `secrets/cache_url`; процесс Valkey работает от uid 999.
### D4. Отказ PostgreSQL и пул
Поведение уже есть с уровня «3»: ленивый пул, `acquire` 1 с, команда 2 с, перевод ошибок в `503`. Здесь оно закрепляется тестами: in-process тест с пулом из одного соединения, занятым тестом, ждёт `503` за время `acquire`; тест стенда останавливает `postgres` и меряет время ответов `/health/ready`, `/users/me` и запроса с неизвестным токеном, затем запускает БД и ждёт восстановления без рестарта API. После остановки PostgreSQL контейнер не имеет DNS-имени, поэтому подключение падает сразу; зависшая БД ограничена таймаутами пула и команды.
### D5. Экземпляр с коротким TTL
`api-shortttl` — тот же образ с `SESSION_TTL_SECONDS=2`, один воркер, профиль compose `faults`, порт `127.0.0.1:${SHORTTTL_PORT:-8082}`. Отдельный экземпляр нужен, потому что smoke и persistence требуют TTL ≥300; БД и Valkey общие, что заодно проверяет, что истечение задаёт сессия, а не процесс.
### D6. Индекс истории и EXPLAIN
`scripts/sql/seed-history.sql` детерминированно создаёт синтетического пользователя и чат с 20 000 сообщений (`generate_series`, фиксированные UUID, `ON CONFLICT DO NOTHING` — повтор безопасен), `ANALYZE`. `scripts/sql/explain-history.sql` готовит тексты запросов приложения через `PREPARE` и снимает `EXPLAIN (ANALYZE, BUFFERS)` для первой страницы, глубокой keyset-страницы после 10 000-го сообщения и той же страницы через `OFFSET 10000`. Ожидание: keyset — `Index Scan` по `messages_history_idx`, 51 строка; `OFFSET` — тот же индекс, но 10 051 прочитанная строка.
### D7. Тесты стенда
`student-tests/stack/` — black-box тесты против поднятого стенда (`BASE_URL`, `SHORTTTL_URL`) с маркером `stack`, по умолчанию исключены из `make student-test`. `make test-faults` поднимает `api-shortttl` и запускает их. Отказы — `docker compose stop/start/restart/exec` подпроцессом; каждый тест возвращает стенд в рабочее состояние в `finally`.
## Risks / Trade-offs
- [Выход недоступен, пока недоступен Valkey] → осознанный выбор строгой инвалидации; ответ `503` честно говорит клиенту, что сессия ещё жива.
- [`appendfsync always` замедляет запись при высокой частоте входов] → входы редки, а каждый вход и так стоит Argon2 (~30 мс) — fsync на этом фоне не виден.
- [Тесты отказов меняют общий стенд] → каждый тест восстанавливает сервис в `finally` и ждёт готовности.
- [Один повтор удваивает время отказа кэша до 0.4 с] → размыкатель платит его не чаще раза в секунду на воркер; потеря заполнения безвредна, потеря отметки отзыва — `503` клиенту.
## Migration Plan
Схема БД не меняется. Новый сервис и secrets появляются после `make secrets` (дописывает недостающие файлы) и `make up`. Без `CACHE_URL` приложение работает как на уровне «3».
@@ -0,0 +1,34 @@
## Why
Уровень «3» закрыт: состояние и сессии в PostgreSQL. Рубрика «4» `README.md` требует Valkey с конкретной ролью, политикой expiry и инвалидации; ограниченный пул и таймауты; проверенные гонку регистрации и rollback; индекс истории, обоснованный `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщений; автоматические проверки expiry, logout, неверного пароля и недоступности Valkey и БД. Изменение закрывает строки уровня 4 таблицы доказательств `REPORT.md` и таблицу отказов.
## What Changes
- Появляется сервис `valkey` (8.1.11-alpine по digest, AOF `appendfsync always` на volume `valkeydata`, `requirepass` из secret). Роль — read-through кэш сессий поверх PostgreSQL: запись `session:<sha256>` живёт до `expires_at` сессии (`PXAT`, но не дольше `SESSION_CACHE_TTL_SECONDS`), выход пишет tombstone до удаления строки в БД, заполнение идёт `SET NX` и не перетирает tombstone.
- Недоступный Valkey обходится за короткий таймаут с размыкателем: проверка сессии уходит в PostgreSQL, неверный токен по-прежнему `401`. Выход при недоступном кэше отвечает `503`: отзыв подтверждается только тогда, когда он виден и в кэше.
- Недоступный PostgreSQL даёт `503 unavailable` за ограниченное время на защищённых endpoint и в `/health/ready`; `/health/live` остаётся `200`; после старта БД пул переподключается без рестарта API. Исчерпание пула — `503` по таймауту ожидания соединения.
- Отдельный экземпляр `api-shortttl` (профиль `faults`, `SESSION_TTL_SECONDS=2`, порт `SHORTTTL_PORT`) для автотеста истечения.
- Собственные тесты стенда (`make test-faults`): гонка 50 регистраций одного `username`, rollback создания чата, expiry, logout, неверный пароль, остановка и рестарт Valkey, `FLUSHALL`, остановка PostgreSQL — с кодами и временем ответа.
- `make seed` (≥10 000 сообщений синтетического чата) и `make explain`: планы `EXPLAIN (ANALYZE, BUFFERS)` первой и глубокой keyset-страницы против `OFFSET`.
- `scripts/restart.sh` перезапускает и Valkey.
## Capabilities
### New Capabilities
- `lab2-session-cache`: роль Valkey, источник истины, политика expiry и инвалидации, поведение при недоступности, `FLUSHALL` и рестарте кэша.
- `lab2-dependency-failures`: ограниченный по времени `503` при отказе PostgreSQL и исчерпании пула, готовность, восстановление без рестарта, запрет анонимного доступа.
- `lab2-history-index`: индекс истории, обоснованный планом на ≥10 000 сообщений; страница истории не сканирует всю историю.
### Modified Capabilities
Нет: гонка регистрации и откат создания чата уже записаны требованиями `lab1-messenger-identity` и `lab2-persistent-storage`, здесь добавляются их проверки.
## Impact
- Код: `identity/infrastructure/valkey.py`, `identity/config.py`, `identity/entrypoints/ioc.py`; тесты `student-tests/api/test_cache.py`, `student-tests/api/test_pool.py`, `student-tests/stack/`.
- Стенд: `compose.yaml` (`valkey`, `api-shortttl`), `scripts/secrets.sh`, `scripts/restart.sh`, `scripts/sql/seed-history.sql`, `scripts/sql/explain-history.sql`, `Makefile`, `.env.example`, CI.
- Зависимость: `redis` (клиент `redis.asyncio`, протокол совместим с Valkey).
- Отчёт: строки уровня «4», таблица отказов, `evidence/`.
## Non-goals
Кэш истории сообщений и списков чатов не вводится: он рисковал бы нарушить read-after-write из контракта, а нагрузка его не требует. Valkey не становится единственным хранилищем сессий. Сравнение нескольких индексов, стоимость записи, backup и restore — трек «5», следующее изменение. Из Out of scope лабы 2 не появляется ничего.
@@ -0,0 +1,37 @@
## Purpose
Определяет поведение API при отказе PostgreSQL и при исчерпании пула соединений: ограниченная по времени ошибка `503` вместо зависания, `500` или анонимного доступа, и восстановление без рестарта процесса.
## ADDED Requirements
### Requirement: Отказ PostgreSQL даёт ограниченную ошибку
При недоступном PostgreSQL защищённые endpoint и `/health/ready` SHALL отвечать `503` с кодом `unavailable` в общем формате ошибки быстрее 2 секунд. Проверка сессии, которая не смогла обратиться к БД, SHALL давать `503`, а не `401`, и SHALL NOT пропускать запрос. `/health/live` SHALL отвечать `200`.
#### Scenario: PostgreSQL остановлен
- **WHEN** сервис `postgres` остановлен
- **THEN** `GET /health/ready` и `GET /api/v1/users/me` отвечают `503 unavailable` быстрее 2 с, `GET /health/live` — `200`, ни один ответ не `500`
#### Scenario: Неизвестный токен при остановленной БД
- **WHEN** PostgreSQL остановлен и приходит запрос с неизвестным токеном
- **THEN** ответ `503`, а не `200`
### Requirement: Восстановление без рестарта API
После возвращения PostgreSQL API SHALL восстанавливать обслуживание без перезапуска своего процесса за счёт переподключения пула.
#### Scenario: PostgreSQL снова запущен
- **WHEN** сервис `postgres` запущен после остановки
- **THEN** в течение 30 с `/health/ready` отвечает `200`, а прежний токен читает свои данные
### Requirement: Ограниченный пул соединений
Каждый процесс API SHALL держать не больше заданного числа соединений с PostgreSQL. Запрос, не получивший соединение за заданное время, SHALL получать `503` и SHALL NOT ждать бесконечно. Все SQL-запросы SHALL быть параметризованными.
#### Scenario: Пул исчерпан
- **WHEN** все соединения пула заняты и приходит запрос, требующий БД
- **THEN** ответ `503 unavailable` за время ожидания соединения
@@ -0,0 +1,24 @@
## Purpose
Определяет, чем обоснован индекс истории сообщений: планом запроса страницы на наборе не меньше 10 000 сообщений и отсутствием полного прохода по истории на каждой странице.
## ADDED Requirements
### Requirement: Индекс истории обоснован планом
Чтение страницы истории SHALL обслуживаться индексом по `(chat_id, created_at, id)` так, что число прочитанных строк и буферов пропорционально `limit`, а не размеру истории чата. Обоснование SHALL быть получено `EXPLAIN (ANALYZE, BUFFERS)` на чате не меньше чем из 10 000 сообщений для первой и для глубокой страницы и сохранено в доказательствах.
#### Scenario: Первая страница
- **WHEN** выполняется запрос первой страницы истории с `limit=50` на чате из ≥10 000 сообщений
- **THEN** план — `Index Scan` по индексу истории без узла `Sort`, прочитана 51 строка
#### Scenario: Глубокая страница keyset-курсором
- **WHEN** выполняется запрос страницы после курсора, указывающего на 10 000-е сообщение
- **THEN** план — `Index Scan` с условием по `(created_at, id)`, прочитана 51 строка, без прохода по предыдущим 10 000
#### Scenario: Сравнение с OFFSET
- **WHEN** та же глубокая страница запрашивается через `OFFSET 10000`
- **THEN** план читает и отбрасывает ≥10 000 строк, что фиксируется рядом с keyset-планом как обоснование выбора курсора
@@ -0,0 +1,56 @@
## Purpose
Определяет роль Valkey в лабе 2: read-through кэш сессий поверх PostgreSQL — что в нём лежит, сколько живёт, как инвалидируется при выходе и что происходит при его недоступности, очистке и рестарте.
## ADDED Requirements
### Requirement: Кэш сессий поверх источника истины
Проверка `Bearer`-токена SHALL сначала обращаться к кэшу Valkey по ключу от SHA-256 токена и только при промахе — к PostgreSQL, после чего заполнять кэш. PostgreSQL SHALL оставаться единственным источником истины: в кэш SHALL NOT попадать ничего, чего нет в БД, а запись кэша SHALL NOT жить дольше `expires_at` сессии. Токен в открытом виде SHALL NOT храниться в кэше.
#### Scenario: Повторная проверка обслуживается кэшем
- **WHEN** пользователь дважды подряд выполняет `GET /api/v1/users/me` с одним токеном
- **THEN** второй запрос находит сессию в Valkey: счётчик попаданий `keyspace_hits` растёт, в кэше есть ключ `session:<sha256>`
#### Scenario: Срок записи кэша не превышает срок сессии
- **WHEN** сессия закэширована
- **THEN** абсолютный срок жизни ключа (`PEXPIRETIME`) не позже `expires_at` сессии
### Requirement: Выход инвалидирует кэш
Отзыв сессии SHALL записывать в кэш отметку отзыва на оставшийся срок сессии до удаления строки в БД, а заполнение кэша после промаха SHALL выполняться только при отсутствии ключа. Отозванный токен SHALL получать `401` и при гонке «чтение заполнило кэш после выхода». Если отметку отзыва записать нельзя, выход SHALL отвечать `503` и SHALL NOT удалять сессию.
#### Scenario: Отозванный токен не оживает из кэша
- **WHEN** токен закэширован, после чего пользователь выполняет `DELETE /api/v1/auth/sessions/current`
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
#### Scenario: Выход при недоступном кэше
- **WHEN** Valkey остановлен и пользователь выполняет `DELETE /api/v1/auth/sessions/current`
- **THEN** ответ `503` с кодом `unavailable`, а после запуска Valkey повторный выход отвечает `204`
### Requirement: Недоступный кэш обходится, но не открывает доступ
При ошибке или таймауте Valkey проверка сессии SHALL выполняться по PostgreSQL за ограниченное время, а повторные попытки обращения к кэшу SHALL приостанавливаться на короткий интервал. Недействительный токен SHALL получать `401`; запрос SHALL NOT приниматься как анонимный. Недоступность Valkey SHALL NOT переводить `/health/ready` в `503`.
#### Scenario: Valkey остановлен
- **WHEN** сервис `valkey` остановлен
- **THEN** `GET /api/v1/users/me` с действительным токеном отвечает `200` быстрее 1 с, с неизвестным токеном — `401`, `/health/ready` — `200`, вход по `Basic` — `201`
### Requirement: Очистка и рестарт кэша безопасны
Потеря содержимого Valkey (`FLUSHALL`, рестарт без данных) SHALL NOT терять сессии и SHALL NOT оживлять отозванные. Valkey SHALL хранить данные с AOF на именованном volume, чтобы рестарт сохранял тёплый кэш и отметки отзыва.
#### Scenario: FLUSHALL
- **WHEN** в Valkey выполнен `FLUSHALL`
- **THEN** действующий токен получает `200`, отозванный — `401`
#### Scenario: Рестарт Valkey
- **WHEN** сервис `valkey` перезапущен
- **THEN** ключи сессий на месте, действующий токен получает `200`, отозванный — `401`
@@ -0,0 +1,38 @@
## 1. Кэш сессий (зона `identity`)
- [x] 1.1 Добавить зависимость `redis`; настройки `CACHE_URL`, `SESSION_CACHE_TTL_SECONDS`, `CACHE_TIMEOUT_SECONDS`, `CACHE_COOLDOWN_SECONDS` в `IdentitySettings`
- [x] 1.2 Адаптер `CachedSessionDirectory`: чтение с отметкой отзыва, заполнение `SET NX PXAT`, инвалидация отметкой с `503` при отказе, размыкатель
- [x] 1.3 Провайдер DI: кэш подключается при заданном `CACHE_URL`, клиент закрывается вместе с контейнером
- [x] 1.4 Проверка группы: in-process тесты против одноразового Valkey — попадание в кэш, срок ключа не позже `expires_at`, выход оставляет отметку, гонка заполнения после выхода, обход недоступного кэша, `503` выхода без кэша
## 2. Отказы PostgreSQL и пул
- [x] 2.1 In-process тест исчерпания пула: пул из одного занятого соединения → `503` за время ожидания
- [x] 2.2 Проверка группы: `make student-test` зелёный
## 3. Стенд
- [x] 3.1 `compose.yaml`: `valkey` по digest (uid 999, AOF `always`, volume `valkeydata`, healthcheck с паролем), `CACHE_URL_FILE` в API, `api-shortttl` в профиле `faults`
- [x] 3.2 `scripts/secrets.sh` дописывает `valkey.conf` и `cache_url`; `scripts/restart.sh` перезапускает и Valkey; `.env.example` — `SHORTTTL_PORT`
- [x] 3.3 Проверка группы: `make up`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
## 4. Тесты стенда
- [x] 4.1 `student-tests/stack/`: фикстуры `BASE_URL`/`SHORTTTL_URL`, вызовы `docker compose`, маркер `stack` вне набора по умолчанию
- [x] 4.2 Гонка 50 регистраций одного `username` (1×201 + 49×409, одна строка в БД) и rollback чата с неизвестным участником (строк нет)
- [x] 4.3 Expiry на `api-shortttl`, logout и повторный logout, неверный пароль и неизвестный пользователь
- [x] 4.4 Остановка и рестарт Valkey, `FLUSHALL`, кэш реально используется (`keyspace_hits`)
- [x] 4.5 Остановка PostgreSQL: `503` быстрее 2 с, `live` 200, восстановление без рестарта API
- [x] 4.6 Цель `make test-faults`; проверка группы: прогон зелёный, вывод сохранён в `evidence/faults.txt`
## 5. Индекс истории
- [x] 5.1 `scripts/sql/seed-history.sql` и `make seed`: 20 000 сообщений синтетического чата, повтор безопасен
- [x] 5.2 `scripts/sql/explain-history.sql` и `make explain`: первая и глубокая keyset-страница против `OFFSET` → `evidence/explain-history.txt`
- [x] 5.3 Проверка группы: в планах `Index Scan using messages_history_idx`, 51 строка у keyset, ≥10 000 у `OFFSET`
## 6. Отчёт
- [x] 6.1 Нагрузка `tests/load.py --concurrency 64`: без `500`, ошибки и задержки в `evidence/load.json`
- [x] 6.2 `REPORT.md`: роль Valkey, источник истины, expiry и инвалидация, persistence, пул и таймауты, строки уровня «4», таблица отказов
- [x] 6.3 Проверка группы: `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-faults` зелёные
+148
View File
@@ -0,0 +1,148 @@
schema: spec-driven
context: |
# Лабораторная 3 «Балансировка и отказ API-реплики» — контекст проекта
## Что это
Skeleton лабораторной 3 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение
в ветке `solution/bpi2303-kostylev`, построенное переносом решения лабы 2. Skeleton содержит
задание (`README.md`), нормативный контракт (`contracts/`, версия 1.3.0) и публичные black-box
проверки (`tests/`). Целевая оценка — «5»: весь уровень 4 плюс трек 1 «Цена масштабирования».
## Границы (менять нельзя)
In scope лабы 3: несколько взаимозаменяемых реплик API (≥2) за единственной публичной точкой
входа — балансировщиком с проверкой готовности backend и обновлением адресов через DNS, без
sticky-сессий; `X-Instance-Id` обслужившей реплики в каждом ответе API; обязательный
`Idempotency-Key` в `POST /api/v1/chats/{chat_id}/messages` с общей для всех реплик
идемпотентностью (повтор, конкурентный повтор, смена реплики); миграции однократно, а не гонкой
реплик; graceful shutdown; явные хуки остановки одной реплики и рестарта стенда. Весь
обязательный минимум lab1 и lab2 (PostgreSQL, Basic → Bearer, Argon2id, TTL и отзыв сессий,
keyset-пагинация, переживание рестарта) сохраняется с объявленными переходами.
Out of scope (не проектировать, не закладывать «на будущее»): вложения и S3 (лаба 4); worker,
брокер и обработка изображений (лаба 5); OTel и Grafana (лаба 6); TLS, mTLS, OpenBao и
непрозрачный alias вместо hostname в `X-Instance-Id` (лаба 7); Docker Swarm и несколько узлов;
репликация и HA PostgreSQL, резервирование балансировщика; Web UI, WebSocket, редактирование и
удаление сообщений, изменение состава участников, публичный поиск пользователей, Kubernetes.
## Стек
Python 3.14 (аннотации вычисляются лениво по PEP 649, `TYPE_CHECKING` и
`from __future__ import annotations` не используются), FastAPI, gunicorn с несколькими
`UvicornWorker` (пакет `uvicorn-worker`), dishka (DI), pydantic v2 + pydantic-settings, structlog,
asyncpg (параметризованный SQL без ORM), redis-py (`redis.asyncio`) для Valkey, argon2-cffi,
pytest + pytest-asyncio + httpx. Зависимости — uv и `uv.lock`; ruff и ty обязательны на `src/`,
`student-tests/` и Python-обвязке стенда; `scripts/*.py` держат синтаксис Python 3.9 и stdlib.
Инфраструктура — Docker Compose: `lb` (HAProxy 3.2 LTS по digest, единственные опубликованные
порты — HTTP и статистика на 127.0.0.1, активная проверка `GET /health/ready`, `server-template`
с resolvers Docker DNS, round robin), `api` (один compose-service с `deploy.replicas`, без
`container_name` и опубликованных портов, `X-Instance-Id` = hostname контейнера, non-root,
read-only, лимиты CPU/RAM, `SIGTERM` ≤ `stop_grace_period`), одноразовый `migrate` на образе
приложения под advisory lock, `postgres` (17.x-alpine по digest, volume, `pg_stat_statements`),
`valkey` (8.x-alpine по digest, AOF), `k6` под профилем `bench` для измерений. Сети `edge`
(LB и генератор нагрузки) и `backend` (internal). Секреты — compose secrets из gitignored
`secrets/`, приложение читает их через `*_FILE`.
## Архитектура
Монолит с двумя доменными зонами по книге Персиваля и Грегори
(`openspec/notes/architecture-patterns-python.md`), развёрнутый N одинаковыми репликами:
main.py сборка приложения: собирает вклады зон в один процесс
migrate.py одноразовая точка входа: применяет SQL-миграции под advisory lock
identity/ пользователи, пароли и сессии: ошибки, события, команды, значения, порты,
адаптеры PostgreSQL/Valkey/Argon2 и весь свой HTTP-слой, включая аутентификацию
messaging/ чаты, история и идемпотентная отправка: ошибки, события, команды, агрегат Chat,
курсор, адаптеры PostgreSQL и весь свой HTTP-слой
shared/ только платформа: domain / application / infrastructure (часы, id, журнал,
пул PostgreSQL, UoW-база) и entrypoints/ (конвейер, health, ошибки, настройки,
идентификатор реплики)
Стрелки указывают внутрь: `domain/` не импортирует инфраструктуру, `application/` зависит только
от портов, адаптеры подключаются в `ioc.py` зоны. Ядро `shared/` не импортирует веб-фреймворк.
Зоны не импортируют друг друга; общая точка — схема БД: внешние ключи между таблицами зон
допустимы как ограничение целостности, но SQL одной зоны не читает таблицы другой.
Реплика не держит состояния, от которого зависит корректность: PostgreSQL — источник истины
для всего, включая сессии и ключи идемпотентности; Valkey — только общий кэш сессий.
## Источники норм
- `contracts/README.md` — нормативная семантика API, включая «Балансировка и повторная отправка».
- `contracts/openapi.json` — OpenAPI 3.1.0, обязательный минимум.
- `contracts/infrastructure.json`, `infra/README.md` — роли инфраструктуры и что о них отчитать.
- `README.md` — рубрика уровней «3» / «4» / «5».
- `COURSE.md` — карта курса и объявленные переходы API между лабами.
- `openspec/notes/architecture-patterns-python.md` — словарь паттернов и их компромиссов.
При расхождении артефакта с `contracts/` источником считается `contracts/`.
Подгонка контракта или публичных тестов под реализацию решением не является.
rules:
proposal:
- "Пиши на русском; идентификаторы, поля, коды ошибок и имена файлов — в оригинальном виде."
- "Держи в пределах 400 слов: Why / What changes / Impact без воды."
- "Указывай, какой уровень рубрики закрывает изменение: «3», «4» или заявленный трек «5»."
- "Обязательна секция «Non-goals» со ссылкой на Out of scope; не тащи в лабу 3 возможности лаб 4–7."
- "Связывай изменение с конкретным пунктом рубрики `README.md` и строкой таблицы доказательств `REPORT.md`."
- "Если изменение трогает `contracts/`, `tests/`, `README.md` или `COURSE.md` — это запрещено, оформляй как вопрос преподавателю."
specs:
- "Имя capability начинается с префикса лабы, в которой требование введено: `lab<N>-<имя>`, например `lab1-messenger-history`. Номер берётся из `lab.json`."
- "Префикс означает происхождение, а не срок действия: требование с `lab1-` продолжает действовать в лабах 2–7, пока его явно не изменит новая дельта."
- "Требование существующей capability правится дельтой к ней же, под её исходным префиксом; новый префикс заводится только для по-настоящему нового поведения."
- "Дельта-спека описывает только наблюдаемое поведение, не реализацию."
- "Требования о границах доменных зон формулируй как наблюдаемые: через поведение API или через проверяемый граф зависимостей модулей."
- "Формулируй требования как `### Requirement:` плюс `#### Scenario:` в форме WHEN/THEN на русском."
- "Для API-требований фиксируй метод, путь, коды ответов, заголовки и форму тела ошибки."
- "Каждое требование трассируется на пункт `contracts/README.md` или на критерий рубрики `README.md`."
- "Сценарии обязаны покрывать негативные пути: отсутствующий и неверный `Idempotency-Key`, тот же ключ с другим телом, тот же ключ у другого пользователя или в другом чате, повтор после отзыва сессии, конкурентный повтор через разные реплики, остановленная реплика, недоступная зависимость, а также прежние: malformed JSON, лишние поля, чужой чат (404, не 403), cursor от другого чата, limit вне 1–100, истёкший токен."
- "Для инфраструктурных требований фиксируй наблюдаемое: какие порты опубликованы, какие реплики видны по `X-Instance-Id`, за какое время восстанавливается запись, что показывает `docker ps -a`."
- "Не вводи в контракт поля и коды, которых нет в `contracts/openapi.json`."
design:
- "Создавай, если изменение затрагивает границы доменных зон, слои, агрегаты, конкурентность, идемпотентность, балансировку, поведение при сигналах или конфигурацию контейнера."
- "Для каждого введённого паттерна отвечай по формуле книги: что за это получаем и чего это стоит."
- "Явно называй порт, его адаптеры и точку сборки; проверяй правило зависимостей: домен не импортирует инфраструктуру."
- "Указывай, к какой доменной зоне относится изменение; если оно задевает обе — объясняй, каким событием они связаны."
- "Всё, что кладётся в `shared/`, обосновывай отдельно: туда попадает только платформа и механизм связи, но не доменные понятия."
- "Ошибки, события и команды принадлежат зоне; в `shared/` живут лишь их базовые типы, без кодов контракта."
- "Фиксируй границы согласованности и способ защиты состояния от гонок между процессами и репликами; объясняй выбранную семантику времени и сортировки."
- "Для балансировщика фиксируй алгоритм, проверку готовности (период, fall/rise, таймаут), обнаружение адресов, политику повторов (какие запросы LB может повторить и почему) и цепочку таймаутов клиент > LB > приложение > БД."
- "Секреты, токены и реальные данные в артефакт не попадают — только плейсхолдеры и имена переменных окружения."
- "Отмечай, что требуется от контейнера: пользователь, закрепление версий, healthcheck, обработка SIGTERM, лимиты, опубликованные порты, переменные окружения."
- "Для каждого хранилища называй источник истины, границы транзакций, политику expiry и инвалидации, поведение при недоступности (503 или обход кэша) и что переживает рестарт."
- "SQL описывай вместе с индексом, который его обслуживает, и ожидаемым планом; схему, ограничения и индексы фиксируй до запросов; миграции — аддитивные (expand/contract), совместимые с работающей версией."
tasks:
- "Задачи — атомарные шаги не длиннее 2 часов, в порядке исполнения."
- "Группируй по слоям и артефактам: схема и миграции, доменные зоны, приложение, инфраструктура, точка входа, стенд, хуки отказов, тесты, измерения, отчёт."
- "Одна задача не пересекает границу доменной зоны; связь зон (событие или внешний ключ схемы) оформляется отдельной задачей."
- "Первой в цепочке идёт задача уровня «3», задачи уровня «4» и трека «5» — после неё."
- "Каждая группа завершается задачей проверки: какой командой убедиться, что критерий рубрики выполнен."
- "Не создавай задач, меняющих `contracts/`, `tests/`, `README.md`, `COURSE.md` или рубрику."
operations:
apply:
guidance:
- "Соблюдай правило зависимостей: адаптер добавляется за существующим портом, а не импортом инфраструктуры в домен."
- "Новый код кладётся в свою доменную зону вместе со своими ошибками, событиями, командами и HTTP-фасадом."
- "`shared/` пополняется только платформой и механизмом связи; доменное понятие туда не попадает никогда."
- "Коды контракта и HTTP-статусы объявляет зона в своём `entrypoints/errors.py`; платформа только применяет реестр."
- "Роутер, провайдер DI, журнал, отображение ошибок и настройки зоны лежат в её `entrypoints/` и `config.py`."
- "Ядро `shared/` (domain, application, infrastructure) не импортирует веб-фреймворк: транспорт живёт только в `shared/entrypoints/` и в `entrypoints/` зон."
- "Отдельного каталога точек входа на верхнем уровне не заводи: общее кладётся в `shared/`, доменное — в зону, сборка — в `main.py`."
- "Зоны не импортируют модули друг друга, кроме объявления события, — это проверяется тестом; в БД связь зон — только внешний ключ, SQL зоны читает лишь свои таблицы."
- "Пиши под Python 3.14 с ленивыми аннотациями: без `TYPE_CHECKING` и без `from __future__ import annotations`."
- "Логирование — только через порт `Logger`; второй логгер в приложении не заводится, сообщения сервера и библиотек идут через тот же поток."
- "Код приложения — в `src/`, конфигурация LB и нагрузки — в `infra/`, собственные тесты — в `student-tests/`, обезличенные доказательства — в `evidence/`."
- "Перед коммитом прогоняй `make lint`, `make student-test` и `make check`."
- "SQL только параметризованный (`$1`, `$2`); значения из запроса никогда не склеиваются в текст запроса."
- "Реплика не хранит в памяти процесса ничего, от чего зависит корректность ответа другой реплики: сессии, ключи идемпотентности и курсоры проверяются через общее хранилище или общий секрет."
- "Ошибка зависимости (PostgreSQL, Valkey) превращается в `503 unavailable` за ограниченное время; отказ кэша обходится и никогда не превращается в анонимный доступ."
- "Схема меняется только новым файлом миграции; применённую миграцию не редактируют; миграция совместима с работающей предыдущей версией."
- "Публичные `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` запускаются против поднятого стенда (`make up`) через LB после готовности всех реплик; после failover реплика возвращается `make restore`."
- "Каждый заявленный критерий рубрики подтверждай командой и наблюдаемым результатом в `REPORT.md`; PASS без команды доказательством не считается."
- "Отмечай выполнение в `tasks.md`; резюме держи кратким."
archive:
guidance:
- "Имя архивной папки начинается с даты архивации в формате `ГГГГ-ММ-ДД`, а не с даты создания change."
- "В `.openspec.yaml` архивной папки проставь `archived: <дата архивации>` и `lab: <номер из lab.json>` — по ним видно, когда и в какой лабе изменение закрыто."
- "Перед архивацией сверься с рубрикой `README.md`: какой уровень закрывает изменение и каким файлом доказательства."
- "Убедись, что `make check`, `make lint`, `make student-test`, `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` и `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` против стенда проходят."
- "Сохранившиеся дальше требования должны попасть в `openspec/specs/`, иначе исчезнут вместе с архивом."
- "Зафиксируй, что именно демонстрируется в сценарии защиты и какие измерения приложены к треку «5»."
@@ -0,0 +1,349 @@
# Паттерны разработки на Python — рабочая заметка
Источник: Гарри Персиваль, Боб Грегори. «Паттерны разработки на Python: TDD, DDD и событийно-ориентированная архитектура» (Architecture Patterns with Python), Питер, 2022, 336 с.
Файл: `~/Library/Mobile Documents/com~apple~CloudDocs/Книги/Паттерны разработки на Python.pdf`. **Номер страницы PDF = номер страницы книги (смещение 0)** — ссылки ниже кликаются напрямую.
Ремарка о стеке (дальше не повторяется): все примеры книги показаны на конкретном веб-фреймворке, ORM и pub/sub-хранилище. Ниже они обобщены до ролей — «точка входа», «ORM», «брокер сообщений». Стек выбирается отдельно, ни один паттерн от него не зависит.
Формула книги (Рич Хикки, с. 65): при вводе каждого паттерна спрашивать «что мы за это получаем и чего это стоит». Ни один паттерн в книге не подаётся как обязательный.
---
## 1. Модель предметной области (Domain Model)
Слой, где живёт вся бизнес-логика, выраженный языком бизнеса и свободный от инфраструктуры.
**Задача.** Бизнес-логика расползается по всем слоям (контроллеры, «менеджеры», хранимки), её невозможно найти, понять и изменить. Разработчики начинают со схемы БД, а объектная модель появляется с запозданием — «на первом месте должно быть поведение, которое управляет требованиями к хранилищу» (с. 29).
Строительные блоки: **сущность** (entity) — идентичность сохраняется при смене атрибутов; **объект-значение** (value object) — немутируемый, полностью определяется атрибутами, взаимозаменяем; **служба предметной области** (domain service) — глагол, который не принадлежит ни одной сущности, обычная функция. Исключения тоже часть языка предметной области.
| Применять | Не применять |
|---|---|
| Сложная бизнес-логика, много правил и крайних случаев | Приложение — простая CRUD-оболочка над БД («модель предметной области или репозиторий вам не нужны», с. 71) |
| Правила меняются чаще, чем инфраструктура | Логика тождественна схеме данных — тогда чтение и запись связаны, и разделение не окупается (с. 236) |
| Нужны юнит-тесты как живая документация правил | Работает график с. 72: для простых доменов ORM/Active Record дешевле, кривые пересекаются только при росте сложности |
**Связи.** Требует «Репозиторий», чтобы остаться не осведомлённой о хранении. Требует «Агрегат», чтобы задать границу согласованности. Заменяет анемичную модель + толстые сервисы. Позже отдаёт побочные эффекты «Событиям предметной области».
Отдельная таблица «плюсы/минусы» для главы 1 в книге отсутствует — компромисс сформулирован в главе 2 (табл. 2.1, рис. 2.6) и в «Итогах части I».
---
## 2. Репозиторий (Repository)
Абстракция над постоянным хранением: коллекция объектов, как будто целиком лежащая в памяти.
**Задача.** Модель предметной области не должна знать о БД. Минимальный интерфейс — `add()` и `get()`. Список/удаление/обновление в идеале не нужны: удаление — мягкое (метод домена), обновление — забота UoW.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Простой интерфейс между хранилищем и доменом | ORM и так частично устраняет связанность: сменить одну СУБД на другую будет довольно легко, хотя поменять внешние ключи может оказаться непросто |
| Тривиально подделывается для юнит-тестов (fake = обёртка над `set`) | Ручное отображение объектов на таблицы — дополнительная работа и код |
| Модель пишется до планирования хранения — фокус на бизнес-задаче, миграции откладываются | Ещё один слой косвенности: рост стоимости сопровождения и «фактор WTF» для тех, кто паттерна не видел |
| Полный контроль над схемой БД, она остаётся простой | Для CRUD-обёртки — не нужен вовсе |
**Связи.** Реализует принцип инверсии зависимостей на уровне данных: ORM импортирует модель, а не наоборот. `AbstractRepository` — **порт**, конкретная и поддельная реализации — **адаптеры**. Один агрегат = один репозиторий, репозиторий возвращает **только** агрегаты (гл. 7). Начиная с гл. 6 доступ к репозиториям выдаёт UoW, а не точка входа. Начиная с гл. 8 репозиторий ведёт `.seen` — множество загруженных агрегатов, откуда UoW собирает события.
Эвристика (с. 70): «если делать подделки трудно, то абстракция, вероятно, слишком сложная».
---
## 3. Сервисный слой / варианты использования (Service Layer, Use Cases)
Оркестровка: тонкий API приложения, где каждый вариант использования — одна функция.
**Задача.** Логика оркестровки (достать → проверить → вызвать домен → сохранить) заползает в контроллеры. Типовая функция слоя: извлечь объекты из репозитория, проверить предусловия, вызвать службу предметной области, сохранить изменения.
Не путать со **службой предметной области**: доменная служба выражает бизнес-концепцию, сервисный слой — способ использования приложения; сервисный слой часто вызывает доменную службу.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Единое место для всех сценариев использования | Приложение исключительно веб — контроллеры и так единственная точка сбора сценариев |
| Домен спрятан за API — его можно свободно перерабатывать | Ещё один слой абстракции |
| «Всё про HTTP» отделено от «всё про предметную область» | Слишком много логики в сервисном слое → антипаттерн «анемичная модель» |
| Вместе с репозиторием даёт быстрые тесты выше уровня домена | Часто хватает «толстых моделей, тонких контроллеров» — вытолкнуть логику из контроллера вниз, в модель, без промежуточного слоя |
**Связи.** Требует «Репозиторий» (зависит от абстракции, не от реализации). До гл. 6 связан с сессией БД — развязывается через UoW. Аргументы выражаются **примитивами**, не доменными объектами (гл. 5) — иначе тесты слоя остаются связанными с доменом. В гл. 9 функции сервисного слоя становятся **обработчиками сообщений** (`services.py` → `handlers.py`), и разница между «службой» и «обработчиком» исчезает.
Совет из книги: вводить слой после того, как заметили оркестровку в контроллерах, а не заранее.
---
## 4. Абстракции и выбор швов (гл. 3)
Отделять «что сделать» от «как сделать»: функциональное ядро + императивная оболочка.
**Задача.** Высокоуровневый код сцеплен с вводом-выводом, тесты медленные и громоздкие, добавить режим `--dry-run` или другой бэкенд невозможно.
Приём: представить состояние внешнего мира простой структурой данных, а результат работы — списком команд-намерений; чистое ядро принимает и возвращает структуры данных, оболочка выполняет ввод-вывод.
Таблицы компромиссов у главы нет — вместо неё **четыре вопроса-эвристики** (с. 89):
1. Какой знакомой структурой данных представить состояние запутанной системы, и какая одна функция может её вернуть?
2. Где провести грань, вырезать **шов**, чтобы вставить абстракцию?
3. Как разделить код на компоненты с разными обязанностями? Какие неявные концепции сделать явными?
4. Каковы зависимости и какова ключевая бизнес-логика?
**Связи.** Это обоснование для всех остальных абстракций книги: репозиторий, UoW, шина сообщений — частные случаи. «Проектирование с учётом тестопригодности означает проектирование с учётом расширяемости» (с. 87).
---
## 5. TDD по слоям: подделки против имитаций, повышенная и пониженная передачи
Тесты — в первую очередь практика проектирования, во вторую — практика тестирования.
**Определения (врезка в гл. 3, с. 87).** **Имитация** (mock) проверяет, *как* нечто использовалось (`assert_called_once_with`), лондонская школа. **Подделка** (fake) — рабочая реализация только для тестов (репозиторий в памяти), утверждения делаются о *конечном состоянии*, классическая школа. Авторы твёрдо на стороне классиков: избыток имитаций скрывает предмет теста.
**Спектр тестов (рис. 5.1).** Тесты домена: эффективная обратная связь по дизайну, точечный охват, высокий барьер для изменений, хрупкие. Тесты API: широкий охват, низкий барьер, но ничего не говорят о дизайне объектов. Тесты сервисного слоя — компромисс посередине.
**Передачи.** *Пониженная* — тесты прямо на модель: новый проект, особенно сложная задача, нужно нащупать дизайн и получить документацию. *Повышенная* — тесты на сервисный слой: обычная фича или багфикс, меньше связанности, шире охват, свобода рефакторить модель.
Таблицы у главы нет; вместо неё врезка **«Эмпирические правила для разных типов тестов»** (с. 119):
| Уровень | Сколько | Зачем |
|---|---|---|
| Сквозной (E2E) | ~1 на функциональное свойство | Показать, что все движущиеся части склеены |
| Сервисный слой | Основная масса | Все крайние случаи бизнес-логики, ввод-вывод подделан |
| Модель предметной области | Малое ядро | Самая эффективная обратная связь по дизайну; удалять без сожаления, когда покрыто выше |
| Несчастливые пути | 1 сквозной на все + много юнит-тестов | Обработка ошибок трактуется как отдельное функциональное свойство |
**Связи.** Работает только при наличии сервисного слоя и подделок репозитория/UoW. «Каждая строка кода в тесте удерживает систему в определённой форме, словно капля клея» (с. 111). Признак недоработанного сервисного слоя: в его тестах приходится напрямую собирать доменные объекты.
---
## 6. UoW — единица работы (Unit of Work)
Абстракция идеи атомарной операции; контекстный менеджер, внутри которого либо всё, либо ничего.
**Задача.** Сервисный слой напрямую держит сессию БД; точка входа общается сразу с тремя слоями. UoW оставляет точке входа две задачи: создать UoW и вызвать службу.
Фиксация **явная**, откат — по умолчанию: единственный путь к изменению состояния — полный успех и явный commit; любой ранний выход оставляет систему в безопасном состоянии.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Хорошая абстракция атомарности; блоки кода видны глазами | ORM/фреймворк, вероятно, уже даёт такую абстракцию (сессия + контекстный менеджер) — можно просто передавать сессию |
| Явный контроль границ транзакции, отказ безопасен по умолчанию | Откаты, многопоточность, вложенные транзакции требуют отдельного продумывания — «выглядит легко» обманчиво |
| Единая точка доступа ко всем репозиториям | |
| Позже — место сбора и публикации событий | |
**Связи.** Требует «Репозиторий» (предоставляет его наружу) и завершает связку с «Сервисным слоем»: один вариант использования = один UoW, успешный или неуспешный целиком. Требуется «Агрегатом» для соблюдения инвариантов на уровне БД. В гл. 8 UoW становится издателем событий, в гл. 10 — источником очереди сообщений (`collect_new_events`).
---
## 7. Агрегат и границы согласованности (Aggregate, Consistency Boundary)
Кластер связанных объектов, изменяемый как единое целое; единственная публичная точка входа в своё поддерево модели.
**Задача.** **Ограничение** — правило, лимитирующее возможные состояния; **инвариант** — условие, всегда истинное. Соблюдать инварианты при параллельной записи, не блокируя всю таблицу. Агрегат очерчивает минимальный кусок модели, который должен быть согласован атомарно; всё, что вне его, согласуется в конечном счёте.
Правило выбора: граница вокруг наименьшего числа объектов, которые обязаны быть согласованы; ей нужно хорошее имя из языка предметной области. Правильного ответа нет — выбор пересматривается, если упирается в производительность.
**Конкурентность.** Оптимистическая блокировка через номер версии на агрегате (конфликт ловится, операция повторяется) против пессимистической — блокировка строк/`SELECT FOR UPDATE` (конфликта не будет, но возможны тупики и просадка). Номер версии книга размещает **в домене**: сервисный слой раздваивает ответственность между слоями, а UoW/репозиторий могут сделать это, лишь допустив, что изменились все агрегаты, — и наращивают версию там, где это не нужно.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Явно делит классы модели на «публичные» и «внутренние» | Третий тип доменного объекта поверх сущности и объекта-значения — рост порога входа |
| Моделирование вокруг явных границ снимает проблемы производительности ORM | Правило «менять только один агрегат за транзакцию» — большой сдвиг в мышлении |
| Единственная ответственная точка за инварианты — проще рассуждать о системе | Работать с итоговой согласованностью между агрегатами сложно |
**Связи.** **Один агрегат = один репозиторий**, репозиторий возвращает только агрегаты. Требует UoW для атомарности. Порождает потребность в «Событиях предметной области»: если процесс пересекает границу агрегатов, его нельзя выполнить одной транзакцией. Диагностика из эпилога (с. 285): нужда атомарно обновить два агрегата означает, что граница выбрана неверно.
Соседняя концепция — **ограниченный контекст** (bounded context): одно и то же слово в разных контекстах значит разное; модель включает только данные, нужные для её расчётов. Выбор агрегатов = выбор контекста, в котором они живут.
---
## 8. События предметной области (Domain Events)
Немутируемые классы данных — факты о произошедшем, зарегистрированные моделью.
**Задача.** Побочное требование («когда товара нет — уведомить закупки») некуда положить: в контроллере — не его дело, в модели — зависимость от инфраструктуры, в сервисном слое — нарушение принципа единственной обязанности. Признак нарушения: работу функции нельзя описать без «затем» и «и».
Модель **регистрирует** факт на языке предметной области; реагировать на него — обязанность кого-то другого.
**Три схемы публикации** (номера вариантов в тексте главы и в её резюме не совпадают, поэтому лучше различать их по издателю):
- публикует **сервисный слой**, забирая события из модели — проще всего, работает;
- **модель порождает, сервисный слой публикует** — логика «когда инициировать» живёт рядом с правилом;
- публикует **UoW**, обходя `.seen` после фиксации — выбор авторов: сервисный слой полностью чист, но механизм «загадочный».
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Хороший способ развести несколько действий в ответ на один запрос | Ещё один механизм; вариант с публикацией из UoW изящен, но неочевиден — из вызова commit не видно, что уйдёт письмо |
| Обработчики отцеплены от стержневой логики, их реализацию легко менять | Скрытая обработка выполняется **синхронно** — неожиданные просадки на веб-эндпоинтах |
| События хорошо ложатся на деловой язык, годятся для работы со стейкхолдерами | Событийный поток размазан по цепочке обработчиков — нет одного места, где видно, как выполняется запрос |
| | Риск циклических зависимостей и бесконечных циклов между обработчиками |
**Связи.** **Заменяет** исключения как поток управления: «если вы реализуете события предметной области, то не инициируйте исключения для описания той же концепции» (с. 169). Требует UoW (границы транзакции) и репозитория (`.seen`). Даёт агрегатам способ влиять друг на друга без длинных транзакций на несколько таблиц. Требует «Шину сообщений» как маршрутизатор.
---
## 9. Шина сообщений и обработчики (Message Bus, Handlers)
Словарь «тип сообщения → список обработчиков»; немая инфраструктура, ничего не знающая о смысле событий.
**Задача.** Дать событиям адресатов и позволить обработчикам порождать новые события, не превращая код в цепочку прямых вызовов. Дальше — радикальный шаг гл. 9: **входы в систему тоже становятся сообщениями**, функции сервисного слоя становятся обработчиками, различие «внутреннее/внешнее» исчезает. Обработчиков у одного события может быть несколько; они могут инициировать другие события.
Важно: шина обрабатывает по одному обработчику за раз. Цель не параллелизм, а концептуальное разделение задач и минимально малый UoW.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Обработчики и службы — одно и то же, конструкций меньше | Непредсказуемость для веб-процесса: заранее не известно, когда всё закончится |
| Изящная структура данных на входе в систему | Неизбежное дублирование между объектами модели и событиями: поле добавляется минимум в двух местах |
| Сложные требования добавляются без архитектурных изменений — только новые события и обработчики | |
**Связи.** Требует «События предметной области». Поглощает «Сервисный слой» (`services.py` → `handlers.py`). Требует разделения на команды и события (гл. 10), иначе непонятно, что обязано выполниться. В гл. 13 превращается из модуля-одиночки в класс с внедрёнными обработчиками. Тестировать сначала «от края до края» и переходить к изолированным юнит-тестам обработчиков (через поддельную шину) только по мере усложнения цепочек.
---
## 10. Команды против событий (Commands vs Events)
Два вида сообщений, обрабатываемых одной шиной по разным правилам.
| | Событие | Команда |
|---|---|---|
| Имя | Прошедшее время («заказ размещён») | Повелительное наклонение («разместить заказ») |
| Смысл | Факт о прошлом | Намерение, чего мы хотим от системы |
| Отправка | Всем слушателям, отправитель их не знает | Одному получателю |
| Обработчиков | Много | Ровно один |
| Отказ | Независимый: логируется, повторяется, поток не прерывает | Заметный: исключение всплывает к отправителю |
**Задача.** Отделить то, что обязано выполниться (команда пользователя, меняющая один агрегат), от того, что можно доделать позже (уведомления, проекции, обновление соседних агрегатов). Успех команды не зависит от успеха обработчиков событий — занятый почтовый сервер не должен мешать принять оплату.
Восстановление: повторные попытки с экспоненциальной задержкой; каждая попытка начинается с согласованного состояния благодаря UoW.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Видно, что обязано выполниться, а что можно привести в порядок позже | Семантическая граница между командой и событием тонкая, споры о ней бывают жаркими |
| Имя «CreateBatch» честнее, чем «BatchCreated», для входа в систему | Отказы допускаются намеренно: система становится менее понятной и требует более качественного мониторинга |
**Связи.** **Заменяет** события-как-входы из гл. 9 (`Allocate` ← `AllocationRequired`, `CreateBatch` ← `BatchCreated`). Требует агрегата как границы согласованности — именно он гарантирует, что отказ обработчика не оставит систему в противоречивом состоянии. Требует UoW для атомарности каждой попытки. Известен также как паттерн «Обработчик команд» (Command Handler).
---
## 11. Событийно-управляемая архитектура и интеграция служб (гл. 8–11, внешние события — гл. 11)
Службы интегрируются асинхронными сообщениями через брокер, а не синхронными вызовами API.
**Антипаттерн.** Резать систему по **существительным** (Заказы, Партии, Клиенты), давать каждой таблице микросервис и CRUD-интерфейс поверх анемичной модели. Граф вызовов быстро запутывается в обе стороны, а сетевой отказ одной службы бьёт по надёжности другой — «распределённый комок грязи».
**Лекарство.** Думать **глаголами**: не «система заказов», а «процесс размещения заказа». Микросервисы — такие же границы согласованности, как агрегаты: служба принимает внешние команды, публикует события, остальные слушают. Внутренние и внешние события держать раздельно; исходящие обязательно валидировать.
Архитектурно это то же приложение: сервисный слой + UoW, перенастроенные как асинхронный процессор сообщений. Потребитель событий транслирует внешние сообщения во внутренние команды, издатель выталкивает внутренние события наружу.
| Применять (плюсы) | Не применять (минусы) |
|---|---|
| Не даёт вырасти распределённому комку грязи | Совокупный поток информации труднее увидеть; логический процесс размазан по уведомлениям и неявен в коде |
| Службы отцеплены: проще менять существующие и добавлять новые | Конечная согласованность — новая концепция, с которой надо уметь работать |
| Отказ части системы не блокирует остальные | Надёжность доставки: выбирать между «как минимум один раз» и «как максимум один раз» |
**Связи.** Тот же аппарат, что для внутренних событий, только транспорт другой. Требует агрегатов (границы), команд/событий (что обязано, что нет), шины сообщений. Микросервисы **не обязательны** для остальных паттернов: «эти методы появились примерно на десять лет раньше микросервисов» (с. 287).
**Мелкий шрифт (эпилог, «Выстрел в ногу»).** Надёжный обмен сообщениями организовать очень сложно; лёгкий pub/sub из примеров ненадёжен и не годится как общецелевой транспорт. Мелкие независимо отказывающие транзакции требуют мониторинга и воспроизведения событий (см. паттерн Outbox). Идемпотентность обработчиков в книге не рассмотрена, а на практике обязательна. Схемы событий будут меняться — нужен способ версионирования и публикации схемы для потребителей.
---
## 12. CQRS — разделение обязанностей команд и запросов
Чтение и запись — разные задачи, поэтому у них разные модели.
**Задача.** Модель предметной области построена под запись: инварианты, транзакционная согласованность, сложная логика. Для чтения она неудобна и медленна — приходится дописывать вспомогательные методы в репозиторий и агрегат, гонять фильтрацию в приложении вместо БД.
| | Сторона чтения | Сторона записи |
|---|---|---|
| Поведение | Простое чтение | Сложная бизнес-логика |
| Кешируемость | Хорошая | Непригодна |
| Согласованность | Может быть устаревшей | Обязана быть транзакционной |
**Ключевой аргумент.** Устаревшее чтение безопасно: данные устаревают в момент открытия страницы, и любое размещение всё равно перепроверяет текущее состояние при записи. Никакая система не согласована с реальностью — бизнес-процессы на крайние случаи нужны в любом случае. Поэтому согласованность чтения разумно менять на производительность и горизонтальное масштабирование (реплики чтения не нужно согласовывать между собой).
Более слабая версия принципа — **CQS**: функция либо меняет состояние, либо отвечает на вопрос, но не то и другое сразу (частный случай — веб-паттерн POST/Redirect/GET).
| Вариант модели чтения | Плюсы | Минусы |
|---|---|---|
| Через существующий репозиторий | Простой согласованный подход | Просадки на сложных запросах; в репозиторий и модель лезут ненужные вспомогательные методы |
| Запросы через ORM | Переиспользуются конфигурация БД и определения модели | Ещё один язык запросов со своими причудами; риск `SELECT N+1` |
| Ручной SQL в отдельном модуле представлений | Точный контроль над производительностью, стандартный синтаксис | Изменения схемы надо вносить и в запросы, и в определения ORM; сильно нормализованные схемы всё равно упираются в join'ы |
| Отдельное денормализованное хранилище чтения, обновляемое обработчиками событий | Реплики только для чтения масштабируются легко; запросы предельно просты | Самый сложный вариант |
**Не применять**, если приложение — простой CRUD: чтение и запись там тесно связаны, ни модель предметной области, ни CQRS не нужны. Полномасштабный CQRS с отдельным хранилищем — крайний случай; выделение представлений в отдельный модуль «только для чтения» полезно само по себе.
**Связи.** Сторона чтения **сознательно обходит** репозиторий и модель предметной области — книга разбирает обе «очевидные альтернативы» и отвергает их. Модель чтения обновляется обработчиками событий, то есть **требует** событий и шины. Модель чтения перестраиваема: прогнать текущее состояние стороны записи через тот же обработчик. Интеграционный тест пишется через шину сообщений — тогда он переживает смену реализации хранилища чтения.
---
## 13. Инверсия зависимостей (DIP) — правило зависимостей
Формулировка (с. 26): (1) высокоуровневые модули не зависят от низкоуровневых, оба зависят от абстракций; (2) абстракции не зависят от деталей, детали зависят от абстракций.
**Высокоуровневые модули** — то, что интересует организацию (пациенты, сделки, инциденты). **Низкоуровневые** — то, что ей неинтересно: файловые системы, сокеты, протоколы. «Зависит от» шире, чем «импортирует»: это знание одного модуля о другом.
Смысл — менять бизнес-логику и инфраструктуру независимо: правки в домене не должны тормозить из-за миграций, а шардирование БД не должно требовать правок в бизнес-слое.
**Порты и адаптеры в терминах книги.** Термин «луковая архитектура» книга не использует; её словарь — **порты и адаптеры**, **гексагональная/чистая архитектура**, «выворачиваем трёхслойную архитектуру наизнанку».
| Понятие | Что это в книге |
|---|---|
| Порт | Интерфейс между приложением и абстрагируемым: абстрактный базовый класс либо просто утиный тип (имена методов и типы аргументов) |
| Адаптер | Реализация за этим интерфейсом |
| Первичные (ведущие) адаптеры | Точки входа: HTTP API, CLI, потребитель событий, **тесты** |
| Вторичные (ведомые) адаптеры | Репозиторий, издатель событий, отправка уведомлений — всё, что смотрит наружу из системы |
Каталоги, отражающие это правило: `domain/`, `service_layer/`, `adapters/`, `entrypoints/`; порт обычно лежит рядом со своими адаптерами.
**Проверка правила зависимостей.** Домен не импортирует ничего инфраструктурного; ORM импортирует модель, а не наоборот; сервисный слой зависит от абстрактного репозитория/UoW; конкретные реализации подключаются на внешнем краю системы.
---
## 14. Внедрение зависимостей и сценарий начальной загрузки (DI, Bootstrap)
Одно место, где приложение собирается: `bootstrap.py` — точка сборки (composition root).
**Задача.** До гл. 13 книга обходится без DI-фреймворка вообще. Проблема возникает, когда зависимостей становится несколько: неявные зависимости через импорт приходится глушить `mock.patch` в каждом тесте, а явные — руками протаскивать через каждую точку входа (веб, потребитель событий, тесты), дублируя проводку.
Сценарий начальной загрузки обязан: объявить зависимости по умолчанию с возможностью переопределить; выполнить одноразовую инициализацию (маппинги ORM, логирование); внедрить зависимости в обработчики; вернуть готовую шину сообщений.
Внедрение делается замыканиями или частичным применением. Книга показывает и «магический» вариант (инспекция сигнатур), и полностью ручной список лямбд — авторы отмечают, что ручной вариант жизнеспособен и при десятках обработчиков.
Таблицы компромиссов у главы нет; из «Выводов»:
| Стоит | Не стоит |
|---|---|
| Адаптеров несколько и проводка дублируется по точкам входа | Один-два адаптера и никакого дублирования — явная передача аргументов дешевле |
| Нужно одно место для разумных умолчаний и для подмены адаптеров подделками в тестах | |
| Есть **цепочки** зависимостей (у зависимостей свои зависимости) или внедрение в разных местах — тогда оправдан и полноценный DI-фреймворк | Внедрение только в обработчики — «ручной» DI достаточен, фреймворк избыточен |
**Рецепт «правильного» адаптера (с. 267).** 1) определить API абстрактным базовым классом; 2) реализовать настоящий; 3) сделать подделку для юнит-тестов и тестов обработчиков; 4) найти «менее поддельную» версию для контура (тестовый сервер сервиса); 5) протестировать её интеграционно.
**Связи.** **Заменяет** проводку в точках входа: они теперь только транслируют вход в команды и передают их шине. Требует, чтобы шина стала классом с внедрёнными обработчиками. Не то же самое, что DIP: DIP — правило направления зависимостей, DI — механика их подстановки.
---
## Сквозная логика книги
**Как складываются слои.** Домен (сущности, объекты-значения, агрегаты, доменные службы, события) ← сервисный слой / обработчики (варианты использования, оркестровка, UoW) ← точки входа (HTTP, CLI, потребитель событий, тесты). Наружу — адаптеры (репозиторий, издатель событий, уведомления). Всё собирается загрузчиком.
**Правило зависимостей.** Стрелки всегда указывают внутрь, к домену. Домен ничего не знает о слоях снаружи. Каждое пересечение границы идёт через порт: сервисный слой зависит от `AbstractRepository`/`AbstractUnitOfWork`, а не от их реализаций; тесты и продакшн подставляют разные адаптеры за одним и тем же портом. Книга описывает это как «выворачивание трёхслойной архитектуры наизнанку»: слой БД перестаёт быть фундаментом и становится деталью на внешнем краю.
**Направление развития по книге.** Модель предметной области → репозиторий (снимаем БД) → сервисный слой (снимаем HTTP) → UoW (снимаем сессию) → агрегат (границы согласованности) → события (снимаем побочные эффекты) → шина (входы становятся сообщениями) → команды/события (что обязано, что нет) → внешние события (границы служб) → CQRS (отделяем чтение) → загрузчик (собираем всё в одном месте). Каждый шаг вводится **после** того, как показана боль без него, — порядок в проекте разумно повторять.
**Когда весь аппарат не нужен.**
- «Если ваше приложение представляет собой простую CRUD-обёртку вокруг базы данных, то модель предметной области или репозиторий вам не нужны» (с. 71).
- «Если ваше приложение по сути является простой обёрткой CRUD вокруг базы данных и вряд ли будет чем-то большим в обозримом будущем, то вам эти паттерны не нужны. Используйте [фреймворк] и дальше и избавьте себя от многих хлопот» (с. 158).
- График с. 72: при низкой сложности домена ORM/Active Record дешевле; кривые пересекаются только при её росте. Слои косвенности стоят сложности, дублирования и порога входа для новых разработчиков.
- CQRS не нужен там, где чтение и запись концептуально совпадают.
- Микросервисы не требуются ни одним из паттернов.
**Как внедрять в существующий комок грязи (эпилог).**
1. Сформулировать проблему: трудно менять? тормозит? необъяснимые баги? Без цели не расставить приоритеты и не убедить команду.
2. Продавать как «налог на архитектуру» под конкретную новую функциональность: три недели чистки под полугодовой проект защитить легко.
3. Начать с **сервисного слоя**: выписать варианты использования (имена в повелительном наклонении), у каждого — своя транзакция, свои предусловия, свой атомарный успех/провал.
4. Дублирование на этом шаге допустимо и даже желательно: скопировать код в новое место, там привести в порядок, потом переключить вызовы. «Лучше дублировать код, чем иметь варианты использования, вызывающие друг друга в длинной цепочке».
5. Вытащить ввод-вывод и доступ к данным из модели в варианты использования.
6. Дальше — агрегаты и ограниченные контексты, затем события; переход к службам — по паттерну «Душитель» (Strangler).
---
## Карта глав
| Гл. | Стр. | Паттерн / тема |
|---|---|---|
| Введение | 21 | Комок грязи, инкапсуляция и абстракции, разделение на слои, **принцип инверсии зависимостей** |
| 1 | 32 | **Модель предметной области**: сущность, объект-значение, служба предметной области |
| 2 | 53 | **Репозиторий**; порты и адаптеры; табл. 2.1 и график компромиссов (с. 72) |
| 3 | 74 | Связанность и **выбор абстракций**; функциональное ядро / императивная оболочка; **подделки против имитаций** (с. 87) |
| 4 | 90 | **Сервисный слой** и первая точка входа; структура каталогов; табл. 4.1 |
| 5 | 109 | **TDD на повышенной и пониженной передачах**; тестовый спектр; эмпирические правила по типам тестов (с. 119) |
| 6 | 120 | **UoW**; явная фиксация и откат по умолчанию; табл. 6.1 |
| 7 | 136 | **Агрегат и границы согласованности**; инварианты; оптимистическая конкурентность; ограниченные контексты; табл. 7.1; итоги части I (с. 157) |
| 8 | 162 | **События предметной области и шина сообщений**; три схемы публикации; табл. 8.1 |
| 9 | 180 | **Всё приложение — шина сообщений**; службы становятся обработчиками; табл. 9.1 |
| 10 | 200 | **Команды и обработчики команд**; различия в обработке ошибок; повторные попытки; табл. 10.1 и 10.2 |
| 11 | 211 | **Внешние события, интеграция служб**; распределённый комок грязи; табл. 11.1 |
| 12 | 226 | **CQRS**; модель чтения; четыре варианта представлений; табл. 12.1 и 12.2 |
| 13 | 246 | **Внедрение зависимостей и сценарий начальной загрузки**; рецепт «правильного» адаптера (с. 267) |
| Эпилог | 268 | Как внедрять в существующую систему; паттерн «Душитель»; вопросы редакторов; **«Выстрел в ногу»** (с. 287) |
| Прил. А | 290 | **Сводная диаграмма и таблица компонентов** — лучшая одностраничная шпаргалка книги |
| Прил. Б | 292 | Шаблонная структура проекта |
| Прил. В | 302 | Полная замена инфраструктуры при неизменном домене |
| Прил. Г | 308 | Репозиторий и UoW поверх «толстого» фреймворка |
| Прил. Д | 318 | Валидация; паттерн «Обеспечение» (precondition) |
@@ -0,0 +1,102 @@
# lab1-event-publication Specification
## Purpose
Определяет, как зоны предметной области узнают о произошедшем, не вызывая друг друга напрямую: модель регистрирует факт, шина разводит его по обработчикам. Транспорт доставки заменяем, и его отказ не влияет на обязательный путь данных.
## Requirements
### Requirement: Побочные эффекты выполняются через события
Побочная работа, не входящая в границу согласованности операции, SHALL выполняться обработчиками событий, а не внутри обработчика команды. Событие SHALL регистрироваться моделью как факт о произошедшем и SHALL публиковаться только после успешного завершения операции, породившей его.
#### Scenario: Успешная операция порождает событие
- **WHEN** сообщение успешно сохранено и клиент получил `201`
- **THEN** зарегистрировано событие об отправке сообщения, доступное обработчикам
#### Scenario: Отклонённая операция событий не порождает
- **WHEN** отправка сообщения отклонена с `400` или `404`
- **THEN** ни одно событие об отправке не публикуется
#### Scenario: Событие получают все подписчики
- **WHEN** на один тип события подписано несколько обработчиков
- **THEN** событие доставляется каждому из них
### Requirement: Отказ обработчика события не влияет на ответ клиента
Исключение в обработчике события SHALL быть залогировано и SHALL NOT менять код ответа уже подтверждённой операции. Отказ одного обработчика SHALL NOT мешать остальным обработчикам того же события.
#### Scenario: Обработчик падает после подтверждения
- **WHEN** обработчик события завершается исключением после того, как клиент получил `201`
- **THEN** ответ клиента остаётся `201`
- **AND** факт отказа виден в логах с идентификатором запроса
#### Scenario: Один обработчик не блокирует остальные
- **WHEN** первый из двух обработчиков события завершается исключением
- **THEN** второй обработчик всё равно вызывается
### Requirement: Публикация событий не удлиняет обязательный путь
Доставка событий обработчикам SHALL быть развязана с обработкой HTTP-запроса: публикация SHALL завершаться, не дожидаясь работы обработчиков. Очередь публикации SHALL иметь явный предел; при его достижении событие SHALL отбрасываться с записью в лог, а обязательный путь данных SHALL продолжать работать.
#### Scenario: Ответ не ждёт обработчиков
- **WHEN** обработчик события выполняется заметно дольше, чем обработка запроса
- **THEN** клиент получает ответ, не дожидаясь завершения обработчика
#### Scenario: Очередь переполнена
- **WHEN** события публикуются быстрее, чем разбираются, и очередь достигла предела
- **THEN** новые события отбрасываются с записью в лог
- **AND** запись сообщений продолжает подтверждаться кодом `201`
### Requirement: Опубликованное событие не раскрывает содержимого сообщений
Полезная нагрузка события SHALL содержать только идентификаторы и метаданные. Текст сообщений, `display_name` и любые пользовательские данные SHALL NOT попадать ни в тело события, ни в журнал.
#### Scenario: Событие об отправке сообщения без текста
- **WHEN** опубликовано событие об отправке сообщения
- **THEN** его тело содержит идентификаторы сообщения, чата и отправителя и отметку времени
- **AND** не содержит текста сообщения
### Requirement: Доменные зоны связаны только событиями
Зона «чаты и сообщения» SHALL NOT вызывать зону «пользователи» и импортировать её модули, кроме объявления события о регистрации. Существование участника SHALL проверяться внешним ключом схемы БД в той же транзакции, что и запись чата; SQL каждой зоны SHALL читать только таблицы своей зоны.
#### Scenario: Регистрация видна чатам сразу
- **WHEN** пользователь зарегистрирован и немедленно создаёт чат со своим участием
- **THEN** чат создаётся успешно: ответ регистрации отправлен после фиксации пользователя в БД
#### Scenario: Неизвестный зоне участник отклоняется
- **WHEN** в состав чата передан идентификатор, которому не соответствует ни один пользователь
- **THEN** ответ `400` с кодом `invalid_request`, чат не создаётся
#### Scenario: Зона пользователей не знает о чатах
- **WHEN** проверяется список зависимостей модулей зоны «пользователи»
- **THEN** среди них нет ни одного модуля зоны «чаты и сообщения»
#### Scenario: Обратная связь идёт только через контракт события
- **WHEN** проверяется список зависимостей модулей зоны «чаты и сообщения»
- **THEN** единственная заимствованная у зоны «пользователи» единица — объявление события о регистрации, а SQL зоны не упоминает таблиц `users` и `sessions`
### Requirement: Публикация событий не требует брокера
Публикация событий SHALL выполняться через порт, реализованный внутренней очередью в памяти процесса. Доставка событий SHALL NOT зависеть от внешнего брокера; из сетевых сервисов обязательный API зависит только от PostgreSQL.
#### Scenario: События доставляются без брокера
- **WHEN** стенд поднят без брокера сообщений
- **THEN** весь обязательный API работает, а события доставляются внутренней очередью
#### Scenario: Публикация скрыта за портом
- **WHEN** проверяется слой приложения
- **THEN** он обращается к публикации только через порт и не знает её реализации
@@ -0,0 +1,85 @@
# lab1-messenger-chats Specification
## Purpose
Определяет чат как границу доступа: кто попадает в состав участников, кто видит чат в списке и что происходит с посторонним. Состав участников задаётся при создании и в обязательном API лабы 1 не меняется.
## Requirements
### Requirement: Создание чата
Сервис SHALL принимать `POST /api/v1/chats` от аутентифицированного пользователя с телом `{"title":..., "member_ids":[...]}` и возвращать `201` с объектом `Chat`. `title` SHALL содержать от 1 до 100 code points и не состоять только из пробельных символов. `member_ids` SHALL содержать от 1 до 100 уникальных идентификаторов существующих пользователей и SHALL включать вызывающего. Чат SHALL создаваться атомарно: при любой ошибке валидации он не создаётся вовсе.
#### Scenario: Чат создан
- **WHEN** участник отправляет `POST /api/v1/chats` с корректным `title` и списком из своего и чужого идентификаторов
- **THEN** ответ `201`, тело соответствует схеме `Chat`, `member_ids` совпадает с запрошенным составом
- **AND** `id` и `created_at` назначены сервером
#### Scenario: Вызывающий не входит в состав
- **WHEN** `member_ids` не содержит идентификатора вызывающего
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Состав содержит дубликаты
- **WHEN** `member_ids` содержит один и тот же идентификатор дважды
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Состав содержит неизвестного пользователя
- **WHEN** `member_ids` содержит идентификатор, которому не соответствует ни один пользователь
- **THEN** ответ `400` с кодом `invalid_request`
- **AND** чат не создаётся
#### Scenario: Запрос без идентификации
- **WHEN** `POST /api/v1/chats` приходит без `Authorization: Bearer` или с недействительным токеном
- **THEN** ответ `401` с кодом `unauthorized` и `WWW-Authenticate: Bearer realm="messenger"`
### Requirement: Членство как граница доступа
Чат SHALL быть доступен только своим участникам. Посторонний пользователь SHALL получать `404` с кодом `not_found` — тот же ответ, что и для несуществующего чата. Сервис SHALL NOT использовать `403` и SHALL NOT раскрывать факт существования чужого чата ни кодом ответа, ни текстом сообщения.
#### Scenario: Участник читает чат
- **WHEN** участник запрашивает `GET /api/v1/chats/{chat_id}` своего чата
- **THEN** ответ `200` с объектом `Chat`
#### Scenario: Посторонний читает чужой чат
- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats/{chat_id}`
- **THEN** ответ `404` с кодом `not_found`
#### Scenario: Запрос несуществующего чата
- **WHEN** запрашивается `GET /api/v1/chats/{chat_id}` с UUID, которому не соответствует ни один чат
- **THEN** ответ `404` с кодом `not_found`, неотличимый от ответа на чужой чат
#### Scenario: Идентификатор чата не является UUID
- **WHEN** `chat_id` в пути не является UUID
- **THEN** ответ `400` с кодом `invalid_request`
### Requirement: Список чатов пользователя
Сервис SHALL отдавать по `GET /api/v1/chats` страницу `{"items":[...],"next_cursor":...}` с чатами, в которых состоит вызывающий, упорядоченными по `(created_at, id)` по возрастанию. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. Список SHALL NOT содержать чатов, недоступных вызывающему.
#### Scenario: Участник видит свой чат
- **WHEN** участник запрашивает `GET /api/v1/chats?limit=100`
- **THEN** ответ `200`, и его чат присутствует в `items`
#### Scenario: Посторонний не видит чужой чат
- **WHEN** пользователь, не входящий в состав, запрашивает `GET /api/v1/chats?limit=100`
- **THEN** ответ `200`, и этого чата в `items` нет
#### Scenario: Limit вне допустимого диапазона
- **WHEN** запрос содержит `limit=0`, `limit=101` или нечисловое значение
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Обход списка курсором
- **WHEN** пользователь состоит в нескольких чатах и запрашивает страницы по одному элементу, передавая `next_cursor` предыдущей страницы
- **THEN** страницы идут в порядке `(created_at, id)` по возрастанию, ни один чат не повторяется и не пропускается
- **AND** `next_cursor` последней страницы равен `null`
@@ -0,0 +1,111 @@
# lab1-messenger-history Specification
## Purpose
Определяет отправку сообщений и чтение истории чата: кто считается отправителем, в каком порядке лежат сообщения и какие гарантии даёт keyset-курсор при обходе истории.
## Requirements
### Requirement: Отправка сообщения
Сервис SHALL принимать `POST /api/v1/chats/{chat_id}/messages` от участника чата с телом `{"text":...}` и возвращать `201` с объектом `Message`. Отправитель SHALL выводиться из предъявленной идентификации; поле `sender_id` в теле запроса SHALL NOT приниматься. `text` SHALL содержать от 1 до 4000 Unicode code points и SHALL NOT состоять только из пробельных символов. `id` и `created_at` SHALL назначаться сервером.
#### Scenario: Сообщение отправлено
- **WHEN** участник отправляет `{"text":"Привет, мир 👋"}` в свой чат
- **THEN** ответ `201`, тело соответствует схеме `Message`
- **AND** `sender_id` равен идентификатору вызывающего, `chat_id` равен чату из пути, `text` побайтово совпадает с отправленным
#### Scenario: Отправитель не берётся из тела запроса
- **WHEN** тело запроса содержит поле `sender_id`
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Пустой или пробельный текст
- **WHEN** тело содержит `{"text":""}` или `{"text":" "}`
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Текст длиннее предела
- **WHEN** `text` содержит более 4000 Unicode code points
- **THEN** ответ `400` с кодом `invalid_request`
- **AND** длина считается в code points, а не в байтах UTF-8
#### Scenario: Посторонний пишет в чужой чат
- **WHEN** пользователь, не входящий в состав чата, отправляет корректное сообщение
- **THEN** ответ `404` с кодом `not_found`
- **AND** сообщение не сохраняется
#### Scenario: Доступ проверяется раньше содержимого
- **WHEN** посторонний отправляет в чужой чат тело, нарушающее схему
- **THEN** ответ `404`, а не `400`
### Requirement: Порядок истории
История чата SHALL быть упорядочена по паре `(created_at, id)` по возрастанию. Время SHALL назначаться сервером в формате RFC 3339 UTC с суффиксом `Z`. Сервис SHALL гарантировать, что `created_at` внутри одного чата строго возрастает в порядке фиксации сообщений, в том числе при конкурентных вставках через разные процессы API, — иначе обход истории keyset-курсором теряет запись, зафиксированную позже с меньшей отметкой.
#### Scenario: Сообщения возвращаются в порядке приёма
- **WHEN** в чат последовательно отправлены два сообщения от разных участников
- **THEN** `GET /api/v1/chats/{chat_id}/messages` возвращает их в порядке отправки
#### Scenario: Конкурентная запись не ломает порядок
- **WHEN** 10 клиентов параллельно отправляют по 10 сообщений в один чат
- **THEN** история содержит ровно 100 сообщений с попарно различными `id`
- **AND** `created_at` строго возрастает по всей истории
#### Scenario: Отметка не уходит назад при отставших часах процесса
- **WHEN** процесс API назначает сообщению отметку меньше, чем у последнего зафиксированного сообщения чата
- **THEN** сообщение получает отметку на одну микросекунду больше последней, и порядок истории сохраняется
### Requirement: Чтение истории keyset-курсором
Сервис SHALL отдавать по `GET /api/v1/chats/{chat_id}/messages` страницу `{"items":[...],"next_cursor":...}`. Параметр `limit` SHALL быть целым в диапазоне 1–100 со значением по умолчанию 50. `next_cursor` SHALL быть непрозрачной для клиента строкой либо `null`, если на момент чтения следующей записи нет. Курсор SHALL быть привязан к чату: курсор, выданный для другого чата, SHALL приводить к `400`. Обход неизменной истории SHALL NOT повторять и SHALL NOT пропускать записи; `limit` разрешается менять между страницами.
#### Scenario: Первая страница отдаёт курсор
- **WHEN** в чате два сообщения и запрошено `?limit=1`
- **THEN** ответ содержит один элемент и непустой `next_cursor`
#### Scenario: Последняя страница закрывает историю
- **WHEN** запрошена вторая страница с курсором предыдущей и `limit=1`
- **THEN** ответ содержит оставшийся элемент и `next_cursor` равный `null`
- **AND** элемент первой страницы не повторяется
#### Scenario: Курсор не привязан к читателю
- **WHEN** курсор, выданный одному участнику чата, предъявляет другой участник того же чата
- **THEN** страница отдаётся на общих основаниях
#### Scenario: Курсор от другого чата
- **WHEN** курсор, выданный для одного чата, предъявлен при чтении другого чата
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Испорченный или подделанный курсор
- **WHEN** значение `cursor` не является ранее выданным сервером курсором
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Limit вне допустимого диапазона
- **WHEN** запрос содержит `limit=0` или `limit=101`
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Посторонний читает чужую историю
- **WHEN** пользователь, не входящий в состав чата, запрашивает его историю
- **THEN** ответ `404` с кодом `not_found`
### Requirement: Подтверждённое сообщение видно следующему чтению
Сообщение, на которое выдан ответ `201`, SHALL быть видно любому последующему чтению истории этого чата. Кэширование допускается, но SHALL NOT возвращать историю, устаревшую относительно успешной записи.
#### Scenario: Запись видна сразу после подтверждения
- **WHEN** участник получил `201` на отправку сообщения и немедленно читает историю
- **THEN** отправленное сообщение присутствует в ответе
@@ -0,0 +1,50 @@
# lab1-messenger-identity Specification
## Purpose
Определяет, как пользователь появляется в системе и как сервер узнаёт, от чьего имени пришёл запрос. В лабе 1 идентификация учебная и никого не аутентифицирует: любой клиент может выдать себя за другого, предъявив чужой идентификатор.
## Requirements
### Requirement: Регистрация пользователя
Сервис SHALL принимать `POST /api/v1/users` без аутентификации и возвращать `201` с объектом `User`, содержащим назначенные сервером `id` и `created_at`. Тело запроса SHALL содержать ровно поля `username`, `display_name` и `password`. `username` SHALL соответствовать `^[a-z0-9_]{3,32}$` и быть уникальным, `display_name` SHALL содержать от 1 до 100 Unicode code points и не состоять только из пробельных символов, требования к `password` задаёт `lab2-auth-sessions`. Ответ SHALL NOT содержать полей, отсутствующих в схеме `User`. Уникальность SHALL соблюдаться и при конкурентной регистрации одного `username`: успешной будет ровно одна, остальные получат `409`.
#### Scenario: Пользователь создан
- **WHEN** приходит `POST /api/v1/users` с телом `{"username":"alice_01","display_name":"Алиса","password":"<12+ символов>"}`
- **THEN** ответ `201`, тело соответствует схеме `User`, `username` и `display_name` совпадают с запросом
- **AND** `id` — UUID, назначенный сервером, `created_at` — RFC 3339 UTC с суффиксом `Z`
#### Scenario: Username занят
- **WHEN** приходит `POST /api/v1/users` с `username`, уже принадлежащим другому пользователю
- **THEN** ответ `409` с телом ошибки и кодом `conflict`
#### Scenario: Username нарушает формат
- **WHEN** `username` содержит заглавные буквы, дефис, пробел, перевод строки или имеет длину вне 3–32 символов
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Display_name пуст или состоит из пробелов
- **WHEN** `display_name` равен `""`, `" "` или длиннее 100 code points
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Тело запроса нарушает схему
- **WHEN** тело содержит лишнее поле, неверный тип поля, не содержит обязательного поля (в том числе `password`) или не является корректным JSON
- **THEN** ответ `400` с кодом `invalid_request`
- **AND** сообщение ошибки не содержит stack trace и внутренних деталей реализации
#### Scenario: Регистрация не требует идентификации
- **WHEN** `POST /api/v1/users` приходит без заголовка `Authorization`
- **THEN** запрос обрабатывается на общих основаниях, ответ не равен `401`
### Requirement: Чтение текущего пользователя
Сервис SHALL отдавать по `GET /api/v1/users/me` объект `User` владельца предъявленной `Bearer`-сессии в том же виде, в каком он был возвращён при регистрации.
#### Scenario: Текущий пользователь возвращён
- **WHEN** приходит `GET /api/v1/users/me` с действительным `Bearer`-токеном пользователя
- **THEN** ответ `200`, тело соответствует схеме `User` и совпадает с телом ответа его регистрации
@@ -0,0 +1,160 @@
# lab1-service-operability Specification
## Purpose
Определяет наблюдаемое поведение сервиса как эксплуатируемого процесса: пробы жизни и готовности, сквозной идентификатор запроса, единый формат ошибок, реакция на сигнал остановки и требования к контейнерной поставке.
## Requirements
### Requirement: Пробы жизни и готовности
Сервис SHALL отвечать на `GET /health/live` кодом `200` с телом `{"status":"ok"}`, проверяя только жизнь процесса. Сервис SHALL отвечать на `GET /health/ready` кодом `200` с тем же телом, только если в момент запроса выполнен запрос к PostgreSQL за ограниченное время, и кодом `503` с телом ошибки в общем формате в противном случае. Пробы SHALL NOT требовать аутентификации. Недоступность необязательных зависимостей SHALL NOT переводить готовность в `503`.
#### Scenario: Проба жизни отвечает без идентификации
- **WHEN** приходит `GET /health/live` без заголовка `Authorization`
- **THEN** ответ `200` с телом `{"status":"ok"}`
#### Scenario: Готовность подтверждена
- **WHEN** приходит `GET /health/ready`, а PostgreSQL доступен
- **THEN** ответ `200` с телом `{"status":"ok"}`
#### Scenario: Готовность не зависит от внешних сервисов
- **WHEN** проверяется готовность, а недоступна только необязательная зависимость
- **THEN** ответ `200`: из внешних сервисов готовность зависит лишь от PostgreSQL
#### Scenario: Готовность отражает PostgreSQL
- **WHEN** PostgreSQL остановлен
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable`, а `GET /health/live` — `200`
#### Scenario: Сервис остановлен
- **WHEN** процесс получил сигнал остановки и перестал принимать новую работу
- **THEN** `GET /health/ready` отвечает `503` с кодом `unavailable` либо соединение не устанавливается
### Requirement: Сквозной идентификатор запроса
Каждый ответ сервиса, включая ответы проб и ответы об ошибках, SHALL содержать непустой заголовок `X-Request-Id`. Если запрос принёс собственный `X-Request-Id`, сервис SHALL использовать его значение, иначе SHALL сгенерировать новое.
#### Scenario: Идентификатор присутствует в любом ответе
- **WHEN** выполняется любой запрос к сервису, успешный или ошибочный
- **THEN** ответ содержит непустой `X-Request-Id`
#### Scenario: Клиентский идентификатор сохраняется
- **WHEN** запрос содержит `X-Request-Id` с непустым значением
- **THEN** ответ содержит то же значение
### Requirement: Единый формат ошибки
Ответ с кодом `4xx` или `5xx` SHALL иметь `Content-Type: application/json` и тело `{"error":{"code":...,"message":...,"request_id":...}}` без каких-либо дополнительных полей. `code` SHALL принимать значение из перечисления контракта, `request_id` SHALL совпадать со значением заголовка `X-Request-Id`. `message` SHALL быть непустым и SHALL NOT содержать stack trace, SQL, учётных данных, внутренних путей и сведений о существовании чужих объектов.
#### Scenario: Тело ошибки соответствует схеме
- **WHEN** запрос завершается ошибкой любого класса
- **THEN** тело ответа соответствует схеме `Error` контракта
- **AND** `request_id` в теле совпадает с заголовком `X-Request-Id`
#### Scenario: Необработанное исключение
- **WHEN** обработка запроса завершается непредвиденным исключением
- **THEN** ответ `500` с кодом `internal_error` и телом в общем формате
- **AND** тело не раскрывает внутренних деталей
#### Scenario: Неподдерживаемый метод или несуществующий путь
- **WHEN** запрашивается несуществующий путь или неподдерживаемый метод существующего пути
- **THEN** ответ имеет тело в общем формате ошибки с непустым `X-Request-Id`
### Requirement: Корректное завершение по сигналу
По получении `SIGTERM` сервис SHALL перестать принимать новые соединения, дождаться завершения принятых запросов и завершить процесс не более чем за 10 секунд. Процесс сервера SHALL быть основным процессом контейнера и SHALL получать сигналы напрямую.
#### Scenario: Остановка укладывается в срок
- **WHEN** запущенному контейнеру послан `SIGTERM`
- **THEN** процесс завершается не позднее чем через 10 секунд
- **AND** код завершения соответствует штатной остановке, а не убийству по таймауту
#### Scenario: Принятый запрос дорабатывается
- **WHEN** `SIGTERM` приходит во время обработки принятого запроса
- **THEN** этот запрос получает ответ до завершения процесса
### Requirement: Логи без содержимого сообщений
Сервис SHALL писать в stdout/stderr структурированную запись на каждый запрос с методом, шаблоном маршрута, кодом ответа, длительностью и `X-Request-Id`. Логи SHALL NOT содержать текста сообщений, `display_name`, паролей, токенов сессий, значений заголовка `Authorization`, строк подключения к хранилищам и тел запросов.
#### Scenario: Запись о запросе присутствует
- **WHEN** обработан любой запрос к API
- **THEN** в stdout появляется запись с методом, шаблоном маршрута, кодом ответа и идентификатором запроса
#### Scenario: Текст сообщения не попадает в логи
- **WHEN** отправлено сообщение с известным текстом-маркером
- **THEN** этот текст отсутствует в stdout и stderr процесса
#### Scenario: Учётные данные не попадают в логи
- **WHEN** пользователь зарегистрировался, вошёл и выполнил запрос с токеном
- **THEN** ни пароль, ни токен, ни значение `Authorization` не встречаются в stdout и stderr процесса
### Requirement: Контейнерная поставка
Сервис SHALL собираться из исходников в образ, слушать `0.0.0.0:8080` и читать конфигурацию из переменных окружения. Контейнер SHALL выполняться от непривилегированного пользователя, SHALL фиксировать версию базового образа и версии зависимостей и SHALL объявлять healthcheck, опирающийся на пробу жизни.
#### Scenario: Образ собирается из чистого clone
- **WHEN** выполняется сборка образа в свежей копии репозитория
- **THEN** сборка завершается успешно без обращения к артефактам вне репозитория
#### Scenario: API доступен на опубликованном порту
- **WHEN** контейнер запущен с публикацией порта 8080
- **THEN** `GET /health/ready` с хоста отвечает `200`
#### Scenario: Процесс работает не от root
- **WHEN** в работающем контейнере проверяется эффективный пользователь процесса сервера
- **THEN** это не `root`, и идентификатор пользователя не равен 0
#### Scenario: Healthcheck отражает состояние сервиса
- **WHEN** контейнер запущен и сервис готов
- **THEN** статус healthcheck контейнера становится `healthy`
### Requirement: Предел времени обработки запроса
Обработка запроса SHALL ограничиваться настраиваемым пределом времени. При его превышении сервис SHALL отвечать `503` с кодом `unavailable`, если ответ ещё не начал отправляться, и SHALL записывать факт превышения в журнал. Превышение предела одним запросом SHALL NOT влиять на последующие запросы и на готовность сервиса.
#### Scenario: Запрос превысил предел
- **WHEN** обработка запроса длится дольше установленного предела
- **THEN** ответ `503` с кодом `unavailable` и телом в общем формате ошибки
#### Scenario: Сервис продолжает работать после превышения
- **WHEN** после превышения предела приходит обычный запрос
- **THEN** он обрабатывается штатно, а `GET /health/ready` отвечает `200`
#### Scenario: Запись о превышении не раскрывает содержимого
- **WHEN** запрос с известным текстом-маркером превысил предел
- **THEN** в журнале появляется запись о превышении, и этот текст в ней отсутствует
### Requirement: Единый журнал всех сообщений процесса
Сервис SHALL выводить в stdout единый поток структурированных записей. Сообщения сервера приложений и используемых библиотек SHALL проходить через тот же журнал и иметь тот же формат, что и сообщения приложения. Записи SHALL содержать только поля из объявленного перечня; поля вне перечня SHALL отбрасываться.
#### Scenario: Сообщения сервера приложений в общем формате
- **WHEN** процесс запускается и печатает сообщения о старте сервера
- **THEN** каждая строка stdout разбирается как структурированная запись того же формата, что и записи приложения
#### Scenario: Незаявленное поле не попадает в журнал
- **WHEN** запись журнала формируется с полем, отсутствующим в перечне разрешённых
- **THEN** это поле в выводе отсутствует
+123
View File
@@ -0,0 +1,123 @@
# lab2-auth-sessions Specification
## Purpose
Определяет, как пользователь доказывает знание пароля, получает непрозрачную сессию с абсолютным сроком жизни, предъявляет её на защищённых endpoint и отзывает её. Заменяет учебную идентификацию `X-User-Id` лабы 1.
## Requirements
### Requirement: Пароль хранится только как password KDF
Сервис SHALL хранить пароль пользователя только в виде хеша библиотечного password KDF Argon2id с солью. Пароль, его хеш и сессионные данные SHALL NOT входить в объект `User` и SHALL NOT попадать в журнал. Пароль SHALL содержать от 12 до 128 Unicode code points и SHALL NOT состоять только из пробельных символов.
#### Scenario: В хранилище нет открытого пароля
- **WHEN** пользователь зарегистрирован с паролем
- **THEN** запись пользователя в БД содержит строку, начинающуюся с `$argon2id$`, и не содержит пароля
#### Scenario: Пароль вне допустимой длины
- **WHEN** `POST /api/v1/users` содержит `password` короче 12 или длиннее 128 code points
- **THEN** ответ `400` с кодом `invalid_request`, пользователь не создаётся
#### Scenario: Пароль из одних пробелов
- **WHEN** `password` состоит только из пробельных символов
- **THEN** ответ `400` с кодом `invalid_request`
#### Scenario: Ответ регистрации без пароля
- **WHEN** пользователь успешно зарегистрирован
- **THEN** тело `201` содержит ровно `id`, `username`, `display_name`, `created_at`
### Requirement: Вход по Basic выдаёт сессию
Сервис SHALL принимать `POST /api/v1/auth/sessions` только с заголовком `Authorization: Basic <base64(username:password)>` и без тела. Декодирование base64 SHALL быть строгим, разделителем SHALL служить первое двоеточие, пароль SHALL декодироваться как UTF-8. При верных учётных данных ответ SHALL быть `201` с телом `{"token","token_type":"Bearer","expires_at","user"}`, где `token` — непрозрачная случайная строка не короче 32 символов с энтропией не менее 256 бит, `expires_at` — RFC 3339 UTC с `Z`, а `user` совпадает с ответом регистрации. Неверный пароль, неизвестный `username`, отсутствующий и испорченный заголовок SHALL давать одинаковый `401` с кодом `unauthorized` и заголовком `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
#### Scenario: Успешный вход
- **WHEN** зарегистрированный пользователь отправляет верные `username:password` в `Basic`
- **THEN** ответ `201`, тело соответствует схеме `Session`, `token_type` равен `Bearer`
- **AND** `user` побайтно равен телу ответа его регистрации, `expires_at` в будущем
#### Scenario: Неверный пароль и неизвестный пользователь неразличимы
- **WHEN** приходит `Basic` с неверным паролем существующего пользователя или с несуществующим `username`
- **THEN** оба ответа — `401` с кодом `unauthorized` и `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`
- **AND** тела ответов различаются только `request_id`
#### Scenario: Испорченный заголовок Basic
- **WHEN** заголовок отсутствует, содержит другую схему, невалидный base64 или строку без двоеточия
- **THEN** ответ `401` с тем же заголовком `WWW-Authenticate: Basic ...`
#### Scenario: Двоеточие в пароле
- **WHEN** пароль пользователя содержит двоеточие и он входит по `Basic`
- **THEN** ответ `201`: разделителем служит первое двоеточие
#### Scenario: Тело запроса при входе
- **WHEN** запрос с верным `Basic` содержит тело
- **THEN** ответ `400` с кодом `invalid_request`, сессия не создаётся
### Requirement: Защищённые endpoint принимают только Bearer
Все `/api/v1/*`, кроме `POST /api/v1/users` и `POST /api/v1/auth/sessions`, SHALL требовать `Authorization: Bearer <token>`; схема сравнивается без учёта регистра. Отсутствующий, неизвестный, истёкший и отозванный токен, а также `Basic` на этих endpoint SHALL давать `401` с кодом `unauthorized` и `WWW-Authenticate: Bearer realm="messenger"`. Заголовок `X-User-Id` SHALL игнорироваться: он не даёт доступа и не меняет владельца сессии. Аутентификация SHALL выполняться раньше проверки доступа к ресурсу и раньше валидации пути, параметров и тела.
#### Scenario: Только X-User-Id
- **WHEN** `GET /api/v1/users/me` приходит с `X-User-Id` существующего пользователя и без `Authorization`
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
#### Scenario: X-User-Id не подменяет владельца
- **WHEN** `GET /api/v1/users/me` приходит с `Bearer` пользователя alice и `X-User-Id` пользователя eve
- **THEN** ответ `200` с пользователем alice
#### Scenario: Basic на бизнес-endpoint
- **WHEN** `GET /api/v1/users/me` приходит с верным `Basic`
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
#### Scenario: Неизвестный токен
- **WHEN** запрос несёт `Bearer` со случайной строкой
- **THEN** ответ `401` с кодом `unauthorized`
#### Scenario: Аутентификация раньше валидации
- **WHEN** `POST /api/v1/chats/not-a-uuid/messages` приходит без `Authorization` и с испорченным JSON
- **THEN** ответ `401`, а не `400`
### Requirement: Абсолютный срок жизни сессии
Срок жизни сессии SHALL задаваться `SESSION_TTL_SECONDS` (по умолчанию 3600) от момента входа и SHALL NOT продлеваться ни использованием, ни рестартом сервиса. После `expires_at` токен SHALL давать `401`.
#### Scenario: Срок назначен при входе
- **WHEN** пользователь вошёл
- **THEN** `expires_at` равен моменту входа плюс `SESSION_TTL_SECONDS` секунд
#### Scenario: Истёкший токен
- **WHEN** сервис запущен с `SESSION_TTL_SECONDS=2` и токен предъявлен через 3 секунды после входа
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
### Requirement: Отзыв текущей сессии
`DELETE /api/v1/auth/sessions/current` SHALL отзывать предъявленный токен и отвечать `204` без тела. После отзыва этот токен SHALL давать `401`, в том числе на повторный `DELETE`. Остальные сессии того же пользователя SHALL оставаться действительными.
#### Scenario: Выход
- **WHEN** пользователь отправляет `DELETE /api/v1/auth/sessions/current` со своим токеном
- **THEN** ответ `204` с пустым телом и непустым `X-Request-Id`
- **AND** следующий `GET /api/v1/users/me` с этим токеном получает `401`
#### Scenario: Повторный выход
- **WHEN** `DELETE /api/v1/auth/sessions/current` повторяется с уже отозванным токеном
- **THEN** ответ `401` с `WWW-Authenticate: Bearer realm="messenger"`
#### Scenario: Другая сессия не затронута
- **WHEN** пользователь вошёл дважды и отозвал первую сессию
- **THEN** второй токен продолжает получать `200`
@@ -0,0 +1,37 @@
# lab2-dependency-failures Specification
## Purpose
Определяет поведение API при отказе PostgreSQL и при исчерпании пула соединений: ограниченная по времени ошибка `503` вместо зависания, `500` или анонимного доступа, и восстановление без рестарта процесса.
## Requirements
### Requirement: Отказ PostgreSQL даёт ограниченную ошибку
При недоступном PostgreSQL защищённые endpoint и `/health/ready` SHALL отвечать `503` с кодом `unavailable` в общем формате ошибки быстрее 2 секунд. Проверка сессии, которая не смогла обратиться к БД, SHALL давать `503`, а не `401`, и SHALL NOT пропускать запрос. `/health/live` SHALL отвечать `200`.
#### Scenario: PostgreSQL остановлен
- **WHEN** сервис `postgres` остановлен
- **THEN** `GET /health/ready` и `GET /api/v1/users/me` отвечают `503 unavailable` быстрее 2 с, `GET /health/live` — `200`, ни один ответ не `500`
#### Scenario: Неизвестный токен при остановленной БД
- **WHEN** PostgreSQL остановлен и приходит запрос с неизвестным токеном
- **THEN** ответ `503`, а не `200`
### Requirement: Восстановление без рестарта API
После возвращения PostgreSQL API SHALL восстанавливать обслуживание без перезапуска своего процесса за счёт переподключения пула.
#### Scenario: PostgreSQL снова запущен
- **WHEN** сервис `postgres` запущен после остановки
- **THEN** в течение 30 с `/health/ready` отвечает `200`, а прежний токен читает свои данные
### Requirement: Ограниченный пул соединений
Каждый процесс API SHALL держать не больше заданного числа соединений с PostgreSQL. Запрос, не получивший соединение за заданное время, SHALL получать `503` и SHALL NOT ждать бесконечно. Все SQL-запросы SHALL быть параметризованными.
#### Scenario: Пул исчерпан
- **WHEN** все соединения пула заняты и приходит запрос, требующий БД
- **THEN** ответ `503 unavailable` за время ожидания соединения
+24
View File
@@ -0,0 +1,24 @@
# lab2-history-index Specification
## Purpose
Определяет, чем обоснован индекс истории сообщений: планом запроса страницы на наборе не меньше 10 000 сообщений и отсутствием полного прохода по истории на каждой странице.
## Requirements
### Requirement: Индекс истории обоснован планом
Чтение страницы истории SHALL обслуживаться индексом по `(chat_id, created_at, id)` так, что число прочитанных строк и буферов пропорционально `limit`, а не размеру истории чата. Обоснование SHALL быть получено `EXPLAIN (ANALYZE, BUFFERS)` на чате не меньше чем из 10 000 сообщений для первой и для глубокой страницы и сохранено в доказательствах.
#### Scenario: Первая страница
- **WHEN** выполняется запрос первой страницы истории с `limit=50` на чате из ≥10 000 сообщений
- **THEN** план — `Index Scan` по индексу истории без узла `Sort`, прочитана 51 строка
#### Scenario: Глубокая страница keyset-курсором
- **WHEN** выполняется запрос страницы после курсора, указывающего на 10 000-е сообщение
- **THEN** план — `Index Scan` с условием по `(created_at, id)`, прочитана 51 строка, без прохода по предыдущим 10 000
#### Scenario: Сравнение с OFFSET
- **WHEN** та же глубокая страница запрашивается через `OFFSET 10000`
- **THEN** план читает и отбрасывает ≥10 000 строк, что фиксируется рядом с keyset-планом как обоснование выбора курсора
@@ -0,0 +1,76 @@
# lab2-persistent-storage Specification
## Purpose
Определяет постоянное хранение лабы 2: схему PostgreSQL с ограничениями, версионируемые миграции, атомарность составных операций, сохранность данных и сессий при рестарте и воспроизводимый стенд из репозитория без секретов в Git.
## Requirements
### Requirement: Схема с ограничениями целостности
PostgreSQL SHALL хранить пользователей, сессии, чаты, участников и сообщения в отдельных таблицах с первичными ключами. Уникальность `username` SHALL обеспечиваться ограничением БД. Участник чата SHALL ссылаться на существующего пользователя и существующий чат, сообщение SHALL ссылаться на участника своего чата, сессия — на пользователя. Схема SHALL дублировать правила контракта проверками `CHECK` (формат `username`, длины строк).
#### Scenario: Ограничения видны в схеме
- **WHEN** оператор выполняет `\d+` по таблицам `users`, `chat_members`, `messages`
- **THEN** видны `PRIMARY KEY`, `UNIQUE (username)` и внешние ключи `chat_members → users, chats`, `messages → chat_members`
#### Scenario: Сообщение от постороннего не записывается даже в обход API
- **WHEN** в `messages` вставляется строка, отправитель которой не состоит в чате
- **THEN** вставка отклоняется нарушением внешнего ключа
### Requirement: Версионируемые миграции
Схема SHALL создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одноразовым процессом до старта API, одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой.
#### Scenario: Миграции с пустого volume
- **WHEN** стенд поднимается на пустом volume PostgreSQL
- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартует API
#### Scenario: Повторный запуск
- **WHEN** процесс миграций запускается повторно на той же БД
- **THEN** он завершается кодом 0, журнал версий и число строк во всех таблицах не меняются
#### Scenario: Изменённая миграция
- **WHEN** текст применённой миграции изменён и процесс миграций запущен
- **THEN** процесс завершается ненулевым кодом и схему не трогает
### Requirement: Атомарное создание чата
Создание чата SHALL записывать чат и всех его участников в одной транзакции. Если хотя бы одна запись нарушает ограничение, транзакция SHALL откатываться целиком: ни строки чата, ни строк участников не остаётся.
#### Scenario: Неизвестный участник откатывает чат
- **WHEN** `POST /api/v1/chats` содержит в `member_ids` UUID несуществующего пользователя
- **THEN** ответ `400` с кодом `invalid_request`
- **AND** в БД нет ни чата с этим `title`, ни его участников
### Requirement: Данные и сессии переживают рестарт
Пользователи, чаты, участники, сообщения и ещё действующие сессии SHALL сохраняться при перезапуске API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, а подтверждённое сообщение SHALL читаться побайтно тем же.
#### Scenario: Полный рестарт стенда
- **WHEN** выполняется `make test-persistence ACTION_SCRIPT=scripts/restart.sh`
- **THEN** hook перезапускает API и хранилища за ≤90 с с кодом 0, а тест печатает `PASS: persistence preserved confirmed data and existing session`
#### Scenario: Логаут после рестарта
- **WHEN** после рестарта пользователь отзывает прежний токен
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
### Requirement: Воспроизводимый стенд из репозитория
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck. Наружу SHALL публиковаться только API на `127.0.0.1:8080`. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, и SHALL NOT появляться в Git, образе и журнале.
#### Scenario: Подъём из чистого clone
- **WHEN** в чистом clone выполняются `make secrets` и `make up`
- **THEN** все сервисы становятся `healthy` или завершаются кодом 0, а `GET /health/ready` отвечает `200`
#### Scenario: Секреты и volumes вне Git
- **WHEN** выполняются `git ls-files secrets .env` и `git check-ignore secrets/database_url .env`
- **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
+56
View File
@@ -0,0 +1,56 @@
# lab2-session-cache Specification
## Purpose
Определяет роль Valkey в лабе 2: read-through кэш сессий поверх PostgreSQL — что в нём лежит, сколько живёт, как инвалидируется при выходе и что происходит при его недоступности, очистке и рестарте.
## Requirements
### Requirement: Кэш сессий поверх источника истины
Проверка `Bearer`-токена SHALL сначала обращаться к кэшу Valkey по ключу от SHA-256 токена и только при промахе — к PostgreSQL, после чего заполнять кэш. PostgreSQL SHALL оставаться единственным источником истины: в кэш SHALL NOT попадать ничего, чего нет в БД, а запись кэша SHALL NOT жить дольше `expires_at` сессии. Токен в открытом виде SHALL NOT храниться в кэше.
#### Scenario: Повторная проверка обслуживается кэшем
- **WHEN** пользователь дважды подряд выполняет `GET /api/v1/users/me` с одним токеном
- **THEN** второй запрос находит сессию в Valkey: счётчик попаданий `keyspace_hits` растёт, в кэше есть ключ `session:<sha256>`
#### Scenario: Срок записи кэша не превышает срок сессии
- **WHEN** сессия закэширована
- **THEN** абсолютный срок жизни ключа (`PEXPIRETIME`) не позже `expires_at` сессии
### Requirement: Выход инвалидирует кэш
Отзыв сессии SHALL записывать в кэш отметку отзыва на оставшийся срок сессии до удаления строки в БД, а заполнение кэша после промаха SHALL выполняться только при отсутствии ключа. Отозванный токен SHALL получать `401` и при гонке «чтение заполнило кэш после выхода». Если отметку отзыва записать нельзя, выход SHALL отвечать `503` и SHALL NOT удалять сессию.
#### Scenario: Отозванный токен не оживает из кэша
- **WHEN** токен закэширован, после чего пользователь выполняет `DELETE /api/v1/auth/sessions/current`
- **THEN** ответ `204`, а следующий запрос с этим токеном получает `401`
#### Scenario: Выход при недоступном кэше
- **WHEN** Valkey остановлен и пользователь выполняет `DELETE /api/v1/auth/sessions/current`
- **THEN** ответ `503` с кодом `unavailable`, а после запуска Valkey повторный выход отвечает `204`
### Requirement: Недоступный кэш обходится, но не открывает доступ
При ошибке или таймауте Valkey проверка сессии SHALL выполняться по PostgreSQL за ограниченное время, а повторные попытки обращения к кэшу SHALL приостанавливаться на короткий интервал. Недействительный токен SHALL получать `401`; запрос SHALL NOT приниматься как анонимный. Недоступность Valkey SHALL NOT переводить `/health/ready` в `503`.
#### Scenario: Valkey остановлен
- **WHEN** сервис `valkey` остановлен
- **THEN** `GET /api/v1/users/me` с действительным токеном отвечает `200` быстрее 1 с, с неизвестным токеном — `401`, `/health/ready` — `200`, вход по `Basic` — `201`
### Requirement: Очистка и рестарт кэша безопасны
Потеря содержимого Valkey (`FLUSHALL`, рестарт без данных) SHALL NOT терять сессии и SHALL NOT оживлять отозванные. Valkey SHALL хранить данные с AOF на именованном volume, чтобы рестарт сохранял тёплый кэш и отметки отзыва.
#### Scenario: FLUSHALL
- **WHEN** в Valkey выполнен `FLUSHALL`
- **THEN** действующий токен получает `200`, отозванный — `401`
#### Scenario: Рестарт Valkey
- **WHEN** сервис `valkey` перезапущен
- **THEN** ключи сессий на месте, действующий токен получает `200`, отозванный — `401`