034a6939f1
- SUMMARY.md with execution metrics and self-check - STATE.md updated: Phase 7 complete, progress 58% - ROADMAP.md: Phase 7 marked complete (1/1 plans) - REQUIREMENTS.md: FMT-09, FMT-10, FMT-11, FMT-12 marked complete Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
109 lines
4.5 KiB
Markdown
109 lines
4.5 KiB
Markdown
---
|
|
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*
|