Record file mode in the manifest, 0000 unless asked (closes #161)

MFFilePath gains mode (field 304): a file's permission bits, 0777 at
most, or 0000, meaning none recorded. gen and freshen record real modes
only with --include-permissions (ScannerOptions.IncludePermissions); the
builder keeps only mode.Perm(), so setuid, setgid and sticky are never
written. list -l and export show the mode in octal. check reports
MODE_MISMATCH for a recorded mode other than 0000 the file lacks. fetch
refuses a manifest with a mode above 0777 before requesting any file,
sets each recorded mode on the files it writes, and downloads again a
present file whose mode differs. The decoding-cost bound counts a file
entry at 176 bytes, up from 160.

Model: opus-5-5

docs/FORMAT.md

@@ -6,8 +6,11 @@ Version 1.0
 
 An `.mf` file is a binary manifest that describes a directory tree of files,
 including their paths, sizes, and cryptographic checksums. It supports optional
-GPG signatures for integrity verification and optional timestamps for metadata
-preservation.
+GPG signatures for integrity verification and optional timestamps and file
+permissions for metadata preservation.
+
+Nothing goes in the 1.0 manifest that 1.0 does not read or write: no field is
+reserved or kept for later use.
 
 ## File Structure
 
@@ -50,7 +53,7 @@ enforce a decompression size limit to prevent decompression bombs. The reference
 implementation limits decompressed size to 256 MB. It writes zstd frames with a
 window of at most 8 MiB, the largest window the zstd format recommends decoders
 support, and refuses frames that ask for a larger one. It also refuses an inner
-message whose file entries, hashes, timestamps and MIME types, counted at 160,
+message whose file entries, hashes, timestamps and MIME types, counted at 176,
 112, 64 and 16 bytes each, add up to more than 8 times its size.
 
 ## Inner Message (`MFFile`)
@@ -77,6 +80,21 @@ Each file entry contains:
 | `mimeType` | 301    | string (optional)         | MIME type                           |
 | `mtime`    | 302    | Timestamp (optional)      | Modification time                   |
 | `ctime`    | 303    | Timestamp (optional)      | Change time (inode metadata change) |
+| `mode`     | 304    | uint32                    | Permission bits (see File Mode)     |
+
+## File Mode
+
+`mode` holds a file's Unix permission bits, the nine `rwx` bits, so it is never
+above `0777` (octal); the setuid, setgid and sticky bits are never recorded.
+Writers record `0000` unless whoever creates the manifest asks for permissions.
+`0000`, the proto3 default, means no mode was recorded: readers never check or
+apply it.
+
+The reference implementation records modes when `gen` or `freshen` is given
+`--include-permissions`. `check` fails a file whose permission bits differ from
+a recorded mode other than `0000`. `fetch` sets a recorded mode other than
+`0000` on each file it writes, and refuses a manifest that records a mode above
+`0777` before it requests any file.
 
 ## Path Rules
 
@@ -127,6 +145,7 @@ By default, manifests are generated deterministically:
 
 - File entries are sorted by `path` in **lexicographic byte order**
 - `createdAt` is omitted unless explicitly requested
+- `mode` is `0000` unless explicitly requested
 
 This ensures that two independent runs over the same directory tree produce
 byte-identical `.mf` files (assuming file contents and metadata have not