android-encrypted-archiver/.planning/phases/07-format-spec-update/07-01-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, duration, completed

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	patterns-established	requirements-completed	duration	completed
07-format-spec-update	01	format	binary-format toc entry-type permissions directory-support	phase provides 01-format-specification v1.0 FORMAT.md with header, TOC entry, data block definitions and worked example	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	08-rust-directory-archiver 09-kotlin-decoder-update 10-shell-decoder-update 11-directory-cross-validation	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)	created modified docs/FORMAT.md	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	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 /	FMT-09 FMT-10 FMT-11 FMT-12	8min	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