N4: [Minor] Engine code hygiene — magic numbers, single-letter names, log field override, console.error vs structured logger

[curtyo18]

Summary

Small code-hygiene items from the 2026-05-17 full-repo review. Each is one-line-to-one-block in size. Bundled because they're cleanup that's most efficiently done in one pass.

Magic numbers to name

• packages/engine/src/api/server.ts:576, 611, 657 — chunkBytes: 1024 * 1024 magic three times. Extract const COPY_CHUNK_BYTES = 1024 * 1024; at module top.
• packages/engine/src/api/server.ts:318 — 'cache-control': 'max-age=300' magic. Named constant.
• packages/engine/src/api/preview-cache.ts:14-15, 107 — MAX_CACHE_BYTES and EVICT_INTERVAL are named (good); the eviction fraction 0.2 at line 107 is bare. Extract EVICT_FRACTION = 0.2.
• packages/engine/src/scan/orchestrator.ts:63-64 — PROGRESS_INTERVAL_MS = 1000 and PROGRESS_FILE_CADENCE = 50 are named but live inside the function body; hoist to module level (also called out in M19).
• packages/engine/src/organize/collision.ts:10 — MAX_SUFFIX_ATTEMPTS = 1000 magic; named but warrants a one-line comment.

Single-letter / cryptic names

• packages/engine/src/rules/matcher.ts:5 — m for rule.match. Rename to match (or inline).
• packages/engine/src/rules/template.ts:33 — f parameter in dateOf, yearOf, monthOf, dayOf. Rename to file.
• packages/engine/src/scan/walker.ts:136 — let s for stat result; rename to fileStat.
• packages/engine/src/scan/walker.ts:53, 78 — let entries; and let targetStat; without explicit types — works via inference but a one-line annotation clarifies for grep.

Logging consistency

• packages/engine/src/organize/undo.ts:213-218 — console.error('undo-catalog-update-failed', { ... }) uses raw console.error while reconcile.ts:8 builds a structured logger. Use the same logger.
• packages/engine/src/log.ts:31 — JSON.stringify({ ts, level, msg, ...base, ...fields }) — if fields contains a ts/level/msg key it silently overrides the canonical fields. Re-spread fields first, then the canonical keys; or document the precedence with a comment.

Dead code

• packages/engine/src/scan/orchestrator.ts:99 — entry.path.slice(0, entry.path.length - entry.name.length) reinvents path.dirname. (Also called out in M19.)
• packages/engine/src/rules/defaults.ts:14 — return 6 is a magic number that has to stay in sync with the array length; return defaultRules(cutoff).length (compute once and reuse).

Other

• packages/engine/src/rules/defaults.ts:4 — TWO_YEARS_MS = 365 * 2 * 24 * 60 * 60 * 1000 ignores leap years; the actual UX-facing setting lives in Settings.recentArchiveCutoffYears. Flag the disconnect — either honor that setting or annotate why this seeder ignores it.
• packages/engine/src/roles/defaults.ts:10 — DEFAULT_FILL_THRESHOLD_PERCENT = 90 is duplicated as a literal 90 across multiple test files and the RoleDefinition schema docs. Export from @fileorganizer/shared so tests reference the same constant.

Background

From the 2026-05-17 multi-agent full-repo review.

Acceptance criteria

• Each magic-number site gains a named constant at module top (or co-located with related defaults).
• Single-letter and cryptic identifiers renamed.
• console.error in undo.ts:213-218 replaced with the threaded structured logger (the logger needs to be available on UndoOptions or threaded; if not, settle for a console.error consistent with log.ts shape).
• log.ts:31 field-spread reordered or commented.
• orchestrator.ts:99 uses path.dirname.
• defaults.ts:14 returns defaultRules(cutoff).length.
• DEFAULT_FILL_THRESHOLD_PERCENT exported from @fileorganizer/shared and used in tests.
• TWO_YEARS_MS either honors recentArchiveCutoffYears or has a one-line comment explaining the seeder's deliberate independence from settings.
• Existing tests pass without modification.

Files affected (likely)

Each item names its file; most are 1-3 line changes.

Suggested approach

Group by file, work file-by-file. The whole issue is mechanical — likely a 30-minute PR.

Out of scope

• Larger refactors (M19 covers orchestrator.ts; this issue scopes to the line-level magic items)
• Type-narrowing improvements not flagged here

References

• Standards: standards/coding-standards.md