P2: Apply commenting style guide to Memory package load-bearing actors #71

New Issue

2026-05-12T19:21:34Z

KofTwentyTwo commented

2026-05-12 19:21:34 +00:00

(Migrated from github.com)

Goal

Bring the Memory package's load-bearing actors up to the standard in .planning/code-commenting-guide.md.

Files in scope

packages/Memory/Sources/Memory/MemoryStore.swift
packages/Memory/Sources/Memory/MemoryExtractionOrchestrator.swift
packages/Memory/Sources/Memory/MemoryExtractionCoordinator.swift
packages/Memory/Sources/Memory/MemoryExtractor.swift

Constraints

ONE atomic commit per file (4 commits total). No code behavior changes — comments + docstrings only.
18/18 boundary gates green.
Apply the guide's 5 comment shapes per file:
- 5-line opener (WHY this actor exists, threading model, who calls it)
- Type-level /// docstring with Overview + Topics + Threading + See Also
- Method-level docstrings on public + key private methods
- ASCII diagram where the file owns an orchestration (extraction pipeline: turn → extractor → ADD/UPDATE/NOOP → store; embedding/vec0 path; temporal validity flow)
- "Before you edit" invariants block (vec0 dim contract — no inline literal; FTS5 + vec0 single store; single memoryUsed / memoryMutated emit per turn; temporal valid_from / valid_to never overwritten; nomic-embed-text dim drift fails boot)
- MARK dividers as a table of contents

Anti-patterns to remove

Plan-ID-only comments — rewrite WHY-first.
Stale references to closed Plan IDs or removed types.
Bare TODO: / FIXME: without issue link.

Follow the canonical pattern

Use the AppDelegate.swift P0 rewrite (#65) as the canonical applied pattern.

Parent epic

#64

Source

.planning/code-commenting-guide.md → Migration plan → P2

## Goal Bring the Memory package's load-bearing actors up to the standard in `.planning/code-commenting-guide.md`. ## Files in scope - `packages/Memory/Sources/Memory/MemoryStore.swift` - `packages/Memory/Sources/Memory/MemoryExtractionOrchestrator.swift` - `packages/Memory/Sources/Memory/MemoryExtractionCoordinator.swift` - `packages/Memory/Sources/Memory/MemoryExtractor.swift` ## Constraints - ONE atomic commit per file (4 commits total). No code behavior changes — comments + docstrings only. - 18/18 boundary gates green. - Apply the guide's 5 comment shapes per file: - 5-line opener (WHY this actor exists, threading model, who calls it) - Type-level `///` docstring with Overview + Topics + Threading + See Also - Method-level docstrings on public + key private methods - ASCII diagram where the file owns an orchestration (extraction pipeline: turn → extractor → ADD/UPDATE/NOOP → store; embedding/vec0 path; temporal validity flow) - "Before you edit" invariants block (vec0 dim contract — no inline literal; FTS5 + vec0 single store; single memoryUsed / memoryMutated emit per turn; temporal valid_from / valid_to never overwritten; nomic-embed-text dim drift fails boot) - MARK dividers as a table of contents ## Anti-patterns to remove - Plan-ID-only comments — rewrite WHY-first. - Stale references to closed Plan IDs or removed types. - Bare `TODO:` / `FIXME:` without issue link. ## Follow the canonical pattern Use the AppDelegate.swift P0 rewrite (#65) as the canonical applied pattern. ## Parent epic #64 ## Source .planning/code-commenting-guide.md → Migration plan → P2

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: KofTwentyTwo/Jarvis#71