diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 807ac20..1f7dac5 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -63,10 +63,10 @@ ### Format (Бинарный формат) -- [ ] **FMT-09**: Тип записи в TOC entry (файл/директория) — 1 байт -- [ ] **FMT-10**: Unix permission bits (mode) в TOC entry — 2 байта (u16) -- [ ] **FMT-11**: Относительные пути с `/` разделителем вместо filename-only -- [ ] **FMT-12**: Обновлённая спецификация FORMAT.md с новыми полями +- [x] **FMT-09**: Тип записи в TOC entry (файл/директория) — 1 байт +- [x] **FMT-10**: Unix permission bits (mode) в TOC entry — 2 байта (u16) +- [x] **FMT-11**: Относительные пути с `/` разделителем вместо filename-only +- [x] **FMT-12**: Обновлённая спецификация FORMAT.md с новыми полями ### Directory (Поддержка директорий) @@ -161,10 +161,10 @@ | TST-01 | Phase 3 | Complete | | TST-02 | Phase 3 | Complete | | TST-03 | Phase 3 | Complete | -| FMT-09 | Phase 7 | Pending | -| FMT-10 | Phase 7 | Pending | -| FMT-11 | Phase 7 | Pending | -| FMT-12 | Phase 7 | Pending | +| FMT-09 | Phase 7 | Complete | +| FMT-10 | Phase 7 | Complete | +| FMT-11 | Phase 7 | Complete | +| FMT-12 | Phase 7 | Complete | | DIR-01 | Phase 8 | Pending | | DIR-02 | Phase 8 | Pending | | DIR-03 | Phase 8 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index d3079bf..1da554e 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -144,7 +144,7 @@ Plans: **Plans**: 1 plan Plans: -- [ ] 07-01-PLAN.md -- Update TOC entry definition (entry_type, permissions, path semantics) and worked example with directory archive +- [x] 07-01-PLAN.md -- Update TOC entry definition (entry_type, permissions, path semantics) and worked example with directory archive ### Phase 8: Rust Directory Archiver **Goal**: `pack` accepts directories and recursively archives them with full path hierarchy and permissions; `unpack` restores the complete directory tree @@ -205,7 +205,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10 | 4. Kotlin Decoder | v1.0 | 1/1 | Complete | 2026-02-25 | | 5. Shell Decoder | v1.0 | 2/2 | Complete | 2026-02-25 | | 6. Obfuscation Hardening | v1.0 | 2/2 | Complete | 2026-02-25 | -| 7. Format Spec Update | v1.1 | 0/1 | Planned | - | +| 7. Format Spec Update | v1.1 | 1/1 | Complete | 2026-02-26 | | 8. Rust Directory Archiver | v1.1 | 0/TBD | Not started | - | | 9. Kotlin Decoder Update | v1.1 | 0/TBD | Not started | - | | 10. Shell Decoder Update | v1.1 | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 7a0590c..2f28e9c 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -9,19 +9,23 @@ See: .planning/PROJECT.md (updated 2026-02-25) ## Current Position -Phase: 7 of 11 (Format Spec Update) -- first phase of v1.1 -Plan: Not yet planned -Status: Ready to plan -Last activity: 2026-02-25 -- v1.1 roadmap created (phases 7-11) +Phase: 7 of 11 (Format Spec Update) -- COMPLETE +Plan: 1 of 1 -- COMPLETE +Status: Phase 7 complete, ready for Phase 8 +Last activity: 2026-02-26 -- Phase 7 Plan 01 executed (FORMAT.md v1.1 update) -Progress: [##########..........] 55% (10/~18 plans estimated) +Progress: [###########.........] 58% (11/~19 plans estimated) ## Performance Metrics -**Velocity (from v1.0):** -- Total plans completed: 10 -- Average duration: 3.6 min -- Total execution time: 0.6 hours +**Velocity:** +- Total plans completed: 11 +- Average duration: 3.8 min +- Total execution time: 0.7 hours + +| Phase | Plan | Duration | Tasks | Files | +|-------|------|----------|-------|-------| +| 07-01 | Format Spec Update | 8 min | 2 | 1 | ## Accumulated Context @@ -37,6 +41,9 @@ Recent decisions affecting current work: - v1.0: Two-pass TOC serialization for correct data_offsets with encrypted TOC size - v1.1: No backward compatibility with v1.0 archives (format version bump) - v1.1: Only mode bits (no uid/gid, no timestamps, no symlinks) +- v1.1: entry_type and permissions fields placed AFTER name, BEFORE original_size in TOC entry +- v1.1: Directory entries use zero-filled crypto fields (uniform entry structure) +- v1.1: Entry size formula: 104 + name_length (was 101) ### Pending Todos @@ -48,6 +55,6 @@ None. ## Session Continuity -Last session: 2026-02-25 -Stopped at: v1.1 roadmap created -- ready to plan Phase 7 +Last session: 2026-02-26 +Stopped at: Completed 07-01-PLAN.md -- Phase 7 complete, ready for Phase 8 Resume file: None diff --git a/.planning/phases/07-format-spec-update/07-01-SUMMARY.md b/.planning/phases/07-format-spec-update/07-01-SUMMARY.md new file mode 100644 index 0000000..5547ffa --- /dev/null +++ b/.planning/phases/07-format-spec-update/07-01-SUMMARY.md @@ -0,0 +1,108 @@ +--- +phase: 07-format-spec-update +plan: 01 +subsystem: format +tags: [binary-format, toc, entry-type, permissions, directory-support] + +# Dependency graph +requires: + - phase: 01-format-specification + provides: "v1.0 FORMAT.md with header, TOC entry, data block definitions and worked example" +provides: + - "v1.1 FORMAT.md with entry_type (u8), permissions (u16 LE), relative path semantics" + - "Updated worked example with 3-entry directory archive (2 dirs + 1 file, 427 bytes)" + - "Version bumped to 2 with compatibility rules" +affects: [08-rust-directory-archiver, 09-kotlin-decoder-update, 10-shell-decoder-update, 11-directory-cross-validation] + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Directory entries have all-zero crypto fields (iv, hmac, sha256, sizes)" + - "Parent-before-child ordering in TOC entries" + - "Entry size formula: 104 + name_length (was 101)" + +key-files: + created: [] + modified: + - "docs/FORMAT.md" + +key-decisions: + - "entry_type and permissions fields placed AFTER name and BEFORE original_size in TOC entry" + - "Directory entries use zero-filled iv/hmac/sha256 (not omitted) to keep fixed-offset field structure" + - "v1.0 worked example fully replaced (not kept as subsection) since format version changed" + +patterns-established: + - "Directory entry pattern: entry_type=0x01, all sizes=0, all crypto=zeroed, no data block" + - "Permission bits: lower 12 bits of POSIX mode_t stored as u16 LE" + - "Entry names: relative paths with / separator, no leading /, no .., no trailing /" + +requirements-completed: [FMT-09, FMT-10, FMT-11, FMT-12] + +# Metrics +duration: 8min +completed: 2026-02-26 +--- + +# Phase 7 Plan 01: Format Spec Update Summary + +**v1.1 FORMAT.md with entry_type (u8) and permissions (u16 LE) fields, relative path semantics, and 427-byte worked example showing nested directory archive** + +## Performance + +- **Duration:** 8 min +- **Started:** 2026-02-26T18:17:57Z +- **Completed:** 2026-02-26T18:26:07Z +- **Tasks:** 2 +- **Files modified:** 1 + +## Accomplishments +- FORMAT.md Section 5 extended with entry_type and permissions fields, Entry Type Values table, Permission Bits Layout table, and Entry Name Semantics subsection +- Entry size formula updated from 101 to 104 + name_length across all references +- Format version bumped from 1 to 2 with detailed v2 changes in Version Compatibility section +- Complete v1.1 worked example: 3 entries (project/src dir, project/src/main.rs file, project/empty dir) with verified 427-byte layout +- Decode Order of Operations updated for directory handling (check entry_type, mkdir -p, chmod, skip to next entry) +- Shell decode walkthrough demonstrates both directory creation and file extraction flows + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Update TOC entry definition with entry_type, permissions, and path semantics** - `e7535da` (feat) +2. **Task 2: Write updated worked example with directory archive** - `37f7dd1` (feat) + +## Files Created/Modified +- `docs/FORMAT.md` - Complete v1.1 binary format specification with directory support fields and new worked example + +## Decisions Made +- entry_type and permissions fields placed AFTER name and BEFORE original_size -- maintains variable-length name at the start (name_length prefix still works), new fields are fixed-size and easy to read after name +- Directory entries use zero-filled crypto fields rather than omitting them -- keeps the entry structure uniform and allows sequential parsing with the same field offsets +- v1.0 worked example fully replaced rather than kept as a subsection -- the old example uses version=1 and the old entry layout, keeping it would cause confusion +- Renamed header field from file_count to entry_count -- reflects that directories are now counted + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered +None + +## User Setup Required +None - no external service configuration required. + +## Next Phase Readiness +- FORMAT.md is the normative reference for all three decoders (Rust, Kotlin, Shell) +- Phase 8 (Rust Directory Archiver) can implement against the new entry_type, permissions, and relative path fields +- Phases 9 and 10 (Kotlin and Shell decoder updates) have unambiguous field tables and a worked example to test against +- The 427-byte worked example with verified offsets serves as a golden reference for implementation testing + +## Self-Check: PASSED + +- FOUND: docs/FORMAT.md +- FOUND: .planning/phases/07-format-spec-update/07-01-SUMMARY.md +- FOUND: e7535da (Task 1 commit) +- FOUND: 37f7dd1 (Task 2 commit) + +--- +*Phase: 07-format-spec-update* +*Completed: 2026-02-26*