developers: stone: v1: record: Document Layout

Author: livingsilver94

astro.config.mjs

@@ -219,6 +219,7 @@ export default defineConfig({
                         { slug: "developers/stone/v1/record/attribute" },
                         { slug: "developers/stone/v1/record/content" },
                         { slug: "developers/stone/v1/record/index/index" },
+                        { slug: "developers/stone/v1/record/layout" },
                       ],
                     },
                   ],

src/content/docs/Developers/Stone/V1/Record/layout.mdx

@@ -0,0 +1,38 @@
+---
+title: Layout
+lastUpdated: 2026-04-22T00:00:00Z
+description: The format of the Layout record
+---
+
+The Layout record contains metadata of a file or directory that should be written to the mass memory.
+When combined with a Content record (and possibly an Index record), it is possible to write the file
+or directory on disk in a reproducible way.
+
+It is composed of a 32 bytes long header-like section and two fields of variable length.
+
+| Field | Type | Size (bytes) | Description |
+|---|---|---|---|
+| uid | uint | 4 | User ID of the owner of the file. |
+| gid | uint | 4 | Group ID of the owner of the file. |
+| mode | uint | 4 | File's mode and permission bits. |
+| tag | blob | 4 | Unused. |
+| source_length | uint | 2 | Length of the `source` blob. |
+| target_length | uint | 2 | Length of the `target` string. |
+| file_type | uint | 1 | Type of file to be written. |
+| padding | blob | 11 | Unused. |
+| source | blob | Specified by `source_length` | "source" of the file. Its meaning varies depending on `file_type`. |
+| target | str | Specified by `target_length` | Path where the file should be written to. |
+
+### file_type
+
+`file_type` is an enum that specifies the type of file that should be written on disk.
+
+|Value|Name|Description|Meaning of `source`|
+|---|---|---|---|
+| 1 | Regular | Regular file of data. |<a href="https://xxhash.com">XXH3_128bits</a> hash of the file.<br></br>The source is a hash because our package manager, Moss, uses a [CAS](https://en.wikipedia.org/wiki/Content-addressable_storage) to store files. |
+| 2 | Symlink | Symbolic link to another file. | String. Original file path to link somewhere else. |
+| 3 | Directory | Empty directory. | Unused. |
+| 4 | CharacterDevice | [Character device](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_91). | Unused. |
+| 5 | BlockDevice | [Block device](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_79). | Unused. |
+| 6 | FIFO | [POSIX FIFO](https://man7.org/linux/man-pages/man7/fifo.7.html). | Unused. |
+| 7 | Socket | [POSIX communication socket](https://man7.org/linux/man-pages/man2/socket.2.html). | Unused. |