OS inode metadata (ownership, permissions, flags, filesystem timestamps) -- the record git's object model never captures
| Tier | foundation |
| Role | unclassified (baselined) |
| Path | crates/foundation/fs-metadata |
| Edition | 2021 |
| Targets | foundation_fs_metadata |
| Public items | 7 across 0 modules |
| Tests | 3 |
What it is for
OS inode metadata: ownership, permissions, flags, and the four filesystem timestamps (btime/mtime/ctime/atime). Lifted 2026-08-13 (Gate 4.5: two real consumers, tools-knowitall's fs_path walk and tools-org-knowledge's corpus_doc walk, both same-layer tools crates that cannot depend on each other) from tools-knowitall's lib.rs/fsmeta.rs, unchanged in behavior.
Exists because git's object model has zero visibility into any of this: git tracks content plus one coarse executable/symlink mode bit, and its commit timestamps record when a commit was authored, never a working-tree file's actual creation/modification/metadata-change/access times. A working-tree file's permissions, ownership, or flags can be tampered with and git status/git diff show nothing — this crate is what closes that gap for any consumer that walks a filesystem and wants to record it.
Capabilities
crate root
OS inode metadata: ownership, permissions, flags, and the four filesystem
| Item |
|---|
fn decode_flags(bits : u32) -> String |
fn flags_for(_path : & Path) -> Option <String> |
FsMetadata
OS inode metadata: ownership, permissions, flags, and the four filesystem
| Item |
|---|
pub struct FsMetadata |
fn metadata_from(meta : & fs::Metadata) -> FsMetadata |
Resolver
OS inode metadata: ownership, permissions, flags, and the four filesystem
| Item |
|---|
pub struct Resolver |
Resolver :: fn owner(& mut self, uid : u32) -> Option <String> |
Resolver :: fn group(& mut self, gid : u32) -> Option <String> |
How to use it
No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.
Module structure
No public modules: the crate root is its whole surface.
Public surface
`crate root`
| Item | What it is |
|---|---|
pub struct FsMetadata | One filesystem path's OS-level metadata, independent of what a consumer does with it (catalog row, corpus row, ...) |
fn metadata_from(meta : & fs::Metadata) -> FsMetadata | Map a path's lstat metadata to FsMetadata |
pub struct Resolver | Caches uid/gid -> name across a walk so a big traversal doesn't re-hit passwd/group per file. |
Resolver :: fn owner(& mut self, uid : u32) -> Option <String> | — |
Resolver :: fn group(& mut self, gid : u32) -> Option <String> | — |
fn decode_flags(bits : u32) -> String | Decode the security-relevant chattr flag bits to a readable string |
fn flags_for(_path : & Path) -> Option <String> | Read + decode a path's flags |
No pub use re-exports: every item above is declared in this crate.
Boundary
Depends on no other workspace tier.
Shares tier foundation with 27 other crates: foundation-audit-log, foundation-basemodels, foundation-bounded-io, foundation-conversation-closure, foundation-crypto-sign, foundation-decisioning, foundation-encounter-vocabulary, foundation-i18n, … (27 total).
_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._
Where it sits
| Tier (ontology) | foundation |
| Architectural role (taxonomy) | unclassified (baselined) |
| Location | crates/foundation/fs-metadata |
| Vocabulary in force (lexicon) | current |
Dependencies
Runtime, from outside the workspace.
| Crate | Requirement | Features | Optional | Only on |
|---|---|---|---|---|
chrono | ^0.4 | serde | no | always |
uzers | ^0.12 | — | no | always |
Development. None.
Build. None.
Depended on by. 3 workspace crates.
Signal flow — what reaches this crate, and what it reaches.
flowchart LR n_application_wiki["application-wiki"] -->|uses| SELF n_tools_corpus["tools-corpus"] -->|uses| SELF n_tools_knowitall["tools-knowitall"] -->|uses| SELF SELF["foundation-fs-metadata"] classDef self fill:#1f883d,stroke:#1f883d,color:#fff; class SELF self;
Feature flags
No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.
Targets
| Kind | Name | Source |
|---|---|---|
| lib | foundation_fs_metadata | `src/lib.rs` |
Error model
No public error type was detected: no public item declares a type named *Error, and no public signature returns one.
Operational characteristics
| Property | Evidence |
|---|---|
| async public surface | none detected |
| async runtime | none detected |
| database access | none detected |
| network I/O | none detected |
| unsafe code | none detected |
| environment variables | none detected |
No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.
Configuration
No environment variable is read with a literal name anywhere in this crate. A variable whose key is computed at run time cannot be listed here, and is not claimed to be absent.
Related capabilities
3 workspace crates depend on this one: application-wiki, tools-corpus, tools-knowitall.
Verification
| Kind | Count |
|---|---|
| Unit tests | 3 |
| Integration tests | 0 |
| Examples | 0 |
| Doctests | 0 |
Evidence by module. How often each public module is named by something executable.
| Module | Tests | Examples | Consumers |
|---|---|---|---|
crate root | 5 | 0 | 8 |
What the tests establish, by name:
decode_known_flags—src/lib.rsmetadata_from_reads_real_file—src/lib.rsuid_zero_resolves_to_root—src/lib.rs
Documentation coverage
| Measure | Documented | Total |
|---|---|---|
| Public items with rustdoc | 5 | 7 |
Public modules with a //! block | 0 | 0 |
pie showData
title Public items with rustdoc
"Documented" : 5
"No rustdoc detected" : 2
Metrics
| Metric | Value |
|---|---|
| Rust source files | 1 |
| Source lines | 166 |
| Code lines | 118 |
| Public API items | 7 |
| Public modules | 0 |
| Tests | 3 |
| Examples | 0 |
| Cargo features | 0 |
| Direct runtime dependencies | 2 |
| Workspace reverse dependencies | 3 |
pie showData
title Public API by kind
"function" : 3
"method" : 2
"struct" : 2
pie showData
title Rust source composition
"Code" : 118
"Blank or comment" : 48
Generation
Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.