SylFS 仕様書 (Sylph Filesystem Specification)

最終更新: 2026-11-10

概要

SylFS（Sylph Filesystem / Sylphid FS） は、AtmOS のためにゼロから設計・実装された高性能・高信頼性を誇る独自ファイルシステムです。

組み込み環境（Raspberry Pi 3B+ / ARMv8 64-bit）における極めて過酷な運用条件（突然の電源断、microSD カードのビット腐敗、マルチコアからの並行アクセス、フラッシュメモリの摩耗）に耐えうる堅牢性と、Web ブラウザのマルチメディアキャッシュやシステムフォント（数 MB 〜 数十 MB）をストレスなく扱う高速性を両立させる設計思想を持っています。

設計思想

1. Copy-on-Write (COW) による完全な電源断耐性: 既存のデータやメタデータ、インデックスノードをインプレース（同一箇所）で上書きすることは一切ありません。すべての変更は空きセクタへ新しく書き出され、最上位のスーパーブロックがアトミックに更新された瞬間にはじめて新バージョンが確定します。書き込み処理のどの瞬間で電源が切れても、直前の整合した状態に安全に復帰します。
2. 2重化（Dual Redundancy）と自動自己修復（Self-Healing）: 不揮発性ストレージ（microSD カード）上の全セクタは物理的にミラーリング（二重化）され、セクタ末尾に付与された CRC32 チェックサムにより読み出し時に整合性が検証されます。プライマリセクタがビット腐敗や書き込み不良で破損した場合、ミラーセクタから健全なデータを自動取得し、さらに破損したプライマリセクタを即座に書き直して修復（Self-Healing）します。
3. B+Tree / B-Tree ハイブリッドインデックス: ファイルパスや名前の検索には、FNV-1a 128-bit ハッシュをキーとしたディスク上の COW B-Tree を採用しています。大量のファイルが存在するディレクトリでも O(log N) の極めて高速な探索速度を実現します。
4. エクステント方式（Extent-based Allocation）による大容量対応: NTFS の “runs” や exFAT と同様に、ファイルを「開始セクタ番号＋連続セクタ数」のエクステント列で表現します。連続領域であれば 1 つのエントリで巨大な領域を表現でき、単一ファイルの容量上限を実質的に撤廃しています。
5. ストレージ階層・用途別振り分け（Storage Policy）: microSD カード（フラッシュメモリ）の書き換え寿命を守るため、ブラウザの一時キャッシュ（/cache/）やテンポラリ（/tmp/）は専用の広大な RAMDisk（揮発性メモリ、最大 332MB）へ自動的にルーティングされます。
6. マルチコア SMP 安全性 & パニック耐性: マルチコア環境において複数のワーカースレッドが同時にファイルシステムへアクセスしてもメタデータやビットマップが破壊されないよう、スピンロック RecoverableMutex（FS_LOCK）で保護されています。万一いずれかのコアがパニックした場合でも、該当コアが保持していたロックのみを強制回収（force release）し、OS 全体のハングアップを回避します。

1. 基本概念 & アーキテクチャ階層

SylFS は、アプリケーション層から物理ストレージハードウェアまで、明確に分離された多層アーキテクチャで構成されています。

アーキテクチャ全体図

+-----------------------------------------------------------------------+
|                アプリケーション層 (Web Browser, Desk, Shell)             |
|                                                                       |
|   Aura スクリプト (fs.*, ls, cat, save, show, find, cp, mv, rm...)     |
+-----------------------------------------------------------------------+
                                   |
                                   v
+-----------------------------------------------------------------------+
|                    VFS / SylFS Core インターフェース                   |
|                                                                       |
|   mount() / save_file() / read_file_checked() / delete_file()         |
|   find_by_label() / list_files() / list_dir()                         |
|   FS_LOCK (RecoverableMutex) 排他制御 & パニック時ロック自動回収         |
+-----------------------------------------------------------------------+
           |                                               |
           v (通常パス / 設定 / アセット)                    v (一時パス: /cache/, /tmp/)
+------------------------------------+          +-----------------------+
|   Persistent SylFS (不揮発性)      |          |  Volatile SylFS (RAM) |
|   - COW B-Tree インデックス         |          |  - 専用 RAMDisk       |
|   - エクステントアロケータ         |          |  - 寿命保護・高速処理 |
|   - 空きセクタビットマップ         |          +-----------------------+
+------------------------------------+                      |
           |                                                |
           v                                                |
+-----------------------------------------------------------v-----------+
|              MirroredBlockDevice (2重化 & 自己修復レイヤ)              |
|                                                                       |
|   - 508B データ + 4B CRC32 チェックサム付与・検証                     |
|   - SD カード: ミラーリング有効 (Primary + Mirror, 容量 50%)          |
|   - RAMDisk: ミラーリング無効 (単一領域, 容量 100% 活用)             |
|   - 読み出し時 CRC 不一致の検知とプライマリ自動書き戻し (Healing)     |
+-----------------------------------------------------------------------+
                                   |
                                   v
+-----------------------------------------------------------------------+
|                    BlockDevice (ハードウェア抽象化層)                  |
|                                                                       |
|   - SDCard: EMMC/SDHOST コントローラ (オフセット 256MiB, FAT32 保護)   |
|   - RAMDisk: 物理連続メモリ直接マッピング (ヒープ後方 332MB)           |
+-----------------------------------------------------------------------+

セクタとデータ境界

物理ストレージの最小読み書き単位は 512 バイト です。SylFS ではデータの信頼性を物理ブロックレベルで担保するため、セクタの末尾 4 バイトを CRC32 チェックサム領域として予約しています。

+---------------------------------------------------------------+
|                      物理セクタ (512 Bytes)                    |
+-----------------------------------------------+---------------+
|           有効データ領域 (DATA_SIZE_PER_SECTOR) | CRC32 チェック |
|                     508 Bytes                 |    4 Bytes    |
+-----------------------------------------------+---------------+
0                                             508             512

• SECTOR_SIZE: 512 バイト（物理デバイスとの最小転送単位）
• DATA_SIZE_PER_SECTOR: 508 バイト（ファイルシステム構造体が利用可能な最大長）
• CRC32: 0〜507 バイト目を対象に計算された CRC-32 (IEEE 802.3 / 0xEDB88320) をリトルエンディアンで格納

すべてのデータブロック、メタデータブロック、インデックスノード、ビットマップブロックは、この 508 バイト境界内に完全に収まるよう #[repr(C, packed)] かつコンパイル時アサーション（assert!(size_of::<T>() <= DATA_SIZE_PER_SECTOR)）により保証されています。

2. オンディスクフォーマット（バイナリレイアウト詳細）

ボリューム全体レイアウト

SylFS の物理デバイス（またはパーティション）上のレイアウトは以下のとおりです。

Sector 0        Sector 1..N           Sector N+1..
+---------------+---------------------+-----------------------------------------+
|  Superblock   |  Allocation Bitmap  |  Data Blocks / Metadata / B-Tree Nodes  |
|  (1 Sector)   |  (動的セクタ数)      |  (COW 動的割り当て領域)                 |
+---------------+---------------------+-----------------------------------------+

1. セクタ 0 (SUPERBLOCK_SECTOR): ファイルシステムの根本情報（マジック、バージョン、B-Tree ルートセクタ、ビットマップ開始セクタ・セクタ長）を保持。
2. セクタ 1 〜 N (BITMAP_START_SECTOR 〜 BITMAP_START_SECTOR + bitmap_sectors - 1): 全セクタの割当状態を 1 ビット単位で管理するビットマップ。
3. セクタ N+1 以降: ファイルデータ、ファイルメタデータ（FileMetadata）、インデックスノード（BTreeNode）、溢れエクステントセクタが混在して動的に確保されるプール。

Superblock 構造体

ファイルシステムの最重要ヘッダであり、常にセクタ 0 に配置されます。変更のコミット時に最後に書き込まれます。

#[repr(C, packed)]
#[derive(Clone, Copy)]
pub struct Superblock {
    pub magic: [u8; 8],        // 0x00..0x08: "SYLFS\0\0\0"
    pub version: u32,          // 0x08..0x0C: バージョン番号 (現在 1)
    pub root_sector: u32,      // 0x0C..0x10: B-Tree インデックスのルートセクタ番号
    pub bitmap_start: u32,     // 0x10..0x14: ビットマップ領域の開始セクタ (通常 1)
    pub bitmap_sectors: u32,   // 0x14..0x18: ビットマップ領域が占有するセクタ数
}

[!NOTE] Superblock の構造体サイズは 24 バイトであり、セクタの先頭 24 バイトに書き込まれます。残りの 484 バイトは予約領域（将来の機能拡張用パディング）となります。

FileMetadata 構造体（i-node）

各ファイルの属性、名前、ラベル、サイズ、およびデータブロックを指すエクステントリストを格納します。1 ファイルにつき 1 つのセクタを消費します。

#[repr(C, packed)]
#[derive(Clone, Copy)]
pub struct FileMetadata {
    pub filename: [u8; 128],                  // 0x000..0x080: パス名 (UTF-8, NUL終端)
    pub label_data: [u8; 64],                 // 0x080..0x0C0: ラベル一覧 (カンマ区切り, UTF-8, NUL終端)
    pub size: u64,                            // 0x0C0..0x0C8: ファイルサイズ (バイト単位, 最大 16EB)
    pub extent_count: u32,                    // 0x0C8..0x0CC: 有効エクステントの総数
    pub overflow_sector: u64,                 // 0x0CC..0x0D4: 溢れエクステントセクタへのポインタ (0なら無し)
    pub extents: [Extent; MAX_INLINE_EXTENTS],// 0x0D4..0x1F4: インラインエクステント配列 (18エントリ)
}

合計サイズ: 128 + 64 + 8 + 4 + 8 + 288 = 500 バイト（ ≤ 508 バイトで 1 セクタに完全に収まる）。

Extent 構造体 & 溢れエクステントチェーン

ファイルを構成するデータセクタの連続領域を効率的に表現します。

#[repr(C, packed)]
#[derive(Clone, Copy, Default)]
pub struct Extent {
    pub start: u64, // 開始セクタ番号
    pub count: u64, // 連続セクタ数 (0なら未使用)
}

エクステントの利点

従来のブロックポインタ列挙方式では、1 セクタあたり数十〜数百個のセクタ番号しか保持できず、間接ブロックを用いても数 MB で容量上限に達していました。SylFS では連続したセクタ確保が行われた場合、どれほど巨大なファイルであっても単一のエクステント（例: start: 1000, count: 20480 = 10MB）で表現できます。

溢れエクステントセクタ (overflow_sector)

ファイルの断片化（フラグメンテーション）が進み、エクステント数が 18 個を超えた場合、残りのエクステントは溢れセクタのリンクリストへ書き出されます。

FileMetadata
  overflow_sector ──> [ Overflow Sector 1 ]
                      ├── next_sector: 1542 ──> [ Overflow Sector 2 ]
                      ├── Extent 19             ├── next_sector: 0 (終端)
                      ├── Extent 20             ├── Extent 50
                      └── ... (最大31エントリ)    └── ...

• 溢れセクタ 1 つあたりの容量:
  • 先頭 8 バイト: next_sector（次の溢れセクタ番号、0 で終端）
  • 続く 500 バイト: Extent 配列（(508 − 8)/16 = 31 エントリ）
  • 合計 8 + (31 × 16) = 504 バイト（ ≤ 508 バイト）

BTreeNode 構造体

ディレクトリ探索および高速ファイル検索を行う COW B-Tree ノードのバイナリ表現です。

pub const MAX_KEYS: usize = 24;
pub const KEY_LEN: usize = 16; // 128-bit FNV-1a ハッシュ

#[repr(C, packed)]
#[derive(Clone, Copy)]
pub struct BTreeNode {
    pub node_type: u8,                       // 0: Leaf, 1: Internal
    pub num_keys: u8,                        // 現在格納されているキー数 (最大 24)
    pub padding: [u8; 2],                    // 4バイト境界アライメントパディング
    pub keys: [[u8; KEY_LEN]; MAX_KEYS + 1], // キー配列 (25エントリ: 分割時の一時オーバーフロー用+1)
    pub values: [u32; MAX_KEYS + 2],         // 値配列 (26エントリ: 葉=Metadataセクタ, 内部=子ノードセクタ)
}

• 合計サイズ: 1 + 1 + 2 + (16 × 25) + (4 × 26) = 4 + 400 + 104 = 508 バイト。 1 セクタのデータ領域（508 バイト）と完全に一致します。
• キー (keys): ファイル名文字列から計算された FNV-1a 128-bit ハッシュ値（16 バイト）。
• 値 (values):
  • 葉ノード (node_type == 0): values[i] は該当ファイルの FileMetadata が格納されたセクタ番号。
  • 内部ノード (node_type == 1): values[i] は左側の子ノードセクタ番号、values[num_keys] は最右端の子ノードセクタ番号。

3. 内部アーキテクチャとアルゴリズム

Copy-on-Write (COW) トランザクション & アトミックコミット

SylFS におけるファイルの保存・更新は、厳密な COW 手順に従って実行されます。途中で電源が断たれた場合でも、ディスク上の旧構造は一切破壊されず残存します。

sequenceDiagram
    autonumber
    participant App as 呼び出し元 (Aura / Kernel)
    participant FS as SylFS Core
    participant Bmp as 空きビットマップ
    participant Dev as MirroredBlockDevice
    participant Disk as 物理ストレージ (SD / RAM)

    App->>FS: save_file("sample.txt", data, "text")
    Note over FS: 1. データセクタの確保と書き込み
    FS->>Bmp: allocate_sector() × 必要数
    Bmp-->>FS: セクタ番号 (連続ならエクステント集約)
    FS->>Dev: write_sector(data_sec, data_chunk)
    Dev->>Disk: プライマリ & ミラー書き込み (CRC32付与)

    Note over FS: 2. メタデータの作成と書き込み
    FS->>Bmp: allocate_sector() (メタデータ用)
    Bmp-->>FS: meta_sec
    FS->>Dev: write_sector(meta_sec, FileMetadata)

    Note over FS: 3. B-Tree インデックスへの COW 再帰挿入
    FS->>FS: insert_recursive() (根から葉までのパスを複製)
    FS->>Bmp: allocate_sector() (更新されたノード用)
    FS->>Dev: write_sector(new_node_sec, new_node)
    Note over FS: 古いノードは replaced リストへ保持

    Note over FS: 4. Superblock 更新によるアトミックコミット
    FS->>Dev: write_sector(0, NewSuperblock { root: new_root })
    Dev->>Disk: 【ここで状態が確定】

    Note over FS: 5. 不要となった旧セクタの安全解放
    FS->>Bmp: deallocate_sector() (replaced 節点)
    FS->>Bmp: free_file_sectors() (上書き前の旧メタデータ&データ)
    FS-->>App: Ok(())

コミット前電源断に対する安全設計

手順 4（Superblock の更新）が完了する前にクラッシュが発生した場合、セクタ 0 は古い root_sector を指したままです。新しく書き込まれたデータセクタや節点セクタは孤立しますが、次回の通常操作やファイルシステムチェック時に安全に再利用され、既存ファイルシステムが不整合になることは構造上あり得ません。

同じパスへ保存し直すとき・ハッシュが衝突したとき（2026-11-10）

B-tree の値は、同じハッシュのメタデータの連鎖（collision_next_sector）の先頭を指す。保存し直すときは連鎖をたどって、次のように扱う。

前の版のデータは、確定より前には決して解放しない。確定の前に電源が切れても、前の版のメタデータが解放済みのセクタを指すことは無い。 2026-11-10 まではこの順序が崩れていた。前の版のデータを確定の前に解放してメタデータをその場で書き換えていたほか、衝突した新しいファイルを保存すると、連鎖の先頭の別のファイルを「前の版」として解放していた。 途中の節をその場で書き換える場合だけは、確定の前に電源が切れると新しい版が先に見えることがある（データは書き終えてから書き換えるので、壊れはしない）。

電源断への備え（2026-11-10）

この OS では、電源はいつでもぶつ切りされる前提で書く。

切り替えの単位は 1 セクタの書き込み。 ミラーのある記憶装置（microSD）では、1 セクタを主 → ミラーの順に書き、読むときは CRC の合わない方を捨てる。主を書いている途中で切れると主の CRC が合わず、ミラー（古い内容）が使われて主も直る。主を書き終えた後に切れると、主（新しい内容）が使われる。したがって 1 セクタの書き込みは、電源断でも「古い内容か新しい内容のどちらか」になる（論理的な判断。中途半端な内容は読まれない）。RAMDisk は揮発なので、電源断の後に残る物が無い。

すべての操作は次の順に書く。

1. 新しい物（データ・溢れのチェーン・メタデータ・木の節点の写し）を空きセクタに書く。生きている物はその場で書き換えない。
2. 1 セクタの書き込みで、指す先を切り替える（スーパーブロックの根、または 1 個のメタデータ）。
3. 届かなくなった古い物を解放する。

ビットマップの確保は 1 の前に書くので、電源断で残るのは「確保したが切り替える前」と「切り替えた後で解放する前」の漏れだけになる。

起動時の回収（recover_after_power_loss、mount で呼ぶ）。 スーパーブロックから届くセクタ（木の節点・メタデータの連鎖・データ・溢れ・ビットマップ）に印を付け、ビットマップを「届くセクタだけ使用中」に書き直す。電源断で漏れたセクタはここで戻る。届くのに空きのセクタ（破損）は使用中に直す。読めないセクタがあるときは、その先に印を付けられない恐れがあるので、漏れは解放しない（データを壊す側に倒さない）。

試験（arm/v1/tests/src/test_fs_power_loss.rs）。 RAMDisk の write_budget で「n 回書いた後の書き込みを全部失敗させる」（電源断と同じく、以後ディスクは変わらない）。保存・上書き・削除・名前の変更（溢れのある大きいファイルも）・切り詰め（溢れが残る／無くなる）・伸長・ラベルの更新のそれぞれで、切れ目 n を 0 から最後まで全部試し、開き直して回収した後に、fsck が健全で漏れが 0、ファイルの集合と中身が操作の「前」か「後」のどちらかにそっくり一致することを確かめる。修正前は、名前の変更（2 つの名前が同じデータを指す）と切り詰め（古い版の末尾をその場で 0 で埋めていたため、前とも後とも違う中身）が失敗した。

2重化 (Mirroring) と自動自己修復 (Self-Healing)

MirroredBlockDevice は、ブロックデバイス層の上位に位置し、ストレージの障害耐性を提供します。

flowchart TD
    Start([セクタ読み込み要求: sector]) --> ReadP[プライマリセクタ読み込み]
    ReadP --> CheckP{プライマリの<br/>CRC32 は正常か?}
    
    CheckP -- 一致 (健全) --> ReturnData[バッファへデータ返却: 成功]
    
    CheckP -- 不一致 (破損検知) --> IsMirrored{デバイスは<br/>二重化対象か?}
    
    IsMirrored -- No (RAMDisk) --> ErrRAM[CRC mismatch エラー返却]
    
    IsMirrored -- Yes (SDCard) --> WarnP[警告ログ出力 & ミラー探索開始]
    WarnP --> ReadM[ミラーセクタ読み込み<br/>sector + usable_sectors]
    ReadM --> CheckM{ミラーの<br/>CRC32 は正常か?}
    
    CheckM -- 一致 (健全) --> Heal[★ 自己修復: Self-Healing<br/>ミラーの健全データを<br/>プライマリセクタへ書き戻し]
    Heal --> ReturnData
    
    CheckM -- 不一致 (両系破損) --> FatalErr[二重系全損エラー: Dual-redundancy failure<br/>データ復旧不能]

• 容量計算:

  • SD カードなどの不揮発性デバイスでは should_mirror() == true となり、デバイスの物理セクタ数の半分（usable_sectors = total_sectors / 2）が利用可能セクタ数となります。
  • セクタ S に対するミラーセクタは常に S + usable_sectors に配置されます。

• 自己修復の実装コード（抜粋）:

  if crc_stored == crc_calc {
      // プライマリ正常
      data[..DATA_SIZE_PER_SECTOR].copy_from_slice(&buf[..DATA_SIZE_PER_SECTOR]);
      return Ok(());
  } else if self.mirrored {
      crate::warn!("CRC mismatch on Primary Sector {}. Initiating Self-Healing...", sector);
      let mirror_sector = sector + self.usable_sectors;
      if self.backend.read_raw_sector(mirror_sector, &mut buf).is_ok() {
          if check_crc(&buf) {
              crate::info!("Mirror Sector {} is healthy. Healing Primary Sector {}...", mirror_sector, sector);
              let _ = self.backend.write_raw_sector(sector, &buf); // 修復書き込み
              data[..DATA_SIZE_PER_SECTOR].copy_from_slice(&buf[..DATA_SIZE_PER_SECTOR]);
              return Ok(());
          }
      }
      return Err("read_sector: both primary and mirror corrupted");
  }

B+Tree / B-Tree インデックスアルゴリズム

SylFS では、単一の木構造の中で「葉ノード」と「内部ノード」で異なる分割規則を採用したハイブリッド方式を用いています。

1. 葉ノード（B+Tree 方式）:
   • データの実体（メタデータセクタ番号）はすべて葉ノードに保持されます。
   • 分割時（ノード内のキー数が MAX_KEYS = 24 を超過した際）、中央のキー K_mid は親ノードへ分離キーとして「コピー引き上げ」され、同時に右の兄弟ノードの先頭にも残されます。これにより、葉ノードを順次走査するだけで全エントリを取りこぼしなく列挙できます。
2. 内部ノード（B-Tree 方式）:
   • 子ノードへのルーティング（ナビゲーション）のみを担当します。
   • 分割時、中央のキー K_mid は親ノードへ「移動（昇格）」し、子ノード内からは完全に除外されます。
3. キー比較: UTF-8 ファイル名の FNV-1a 128-bit ハッシュ値（16 バイト）のバイト単位昇順比較。

pub fn fnv1a_128(data: &[u8]) -> [u8; 16] {
    let mut hash: u128 = 0x6c62272e07bb014262b821756295c58d;
    for &b in data {
        hash ^= b as u128;
        hash = hash.wrapping_mul(0x0000000001000000000000000000013B);
    }
    hash.to_le_bytes()
}

空きセクタビットマップアロケータ

ビットマップセクタ数の動的算出

ファイルシステム全体のセクタ数に応じて、必要なビットマップセクタ数が自動算出されます。

$$\text{bitmap\_sectors} = \left\lceil \frac{\text{total\_usable\_sectors}}{508 \times 8} \right\rceil$$

1 つのビットマップセクタ（508 バイト）で 508 × 8 = 4, 064 セクタ（約 2MB）を管理できます。1GB のストレージであっても約 515 セクタ（約 260KB）のビットマップで全域を完全にカバーします。

O(1) 近傍アロケーションヒント (next_bitmap_hint)

ファイルを保存する際、毎回ビットマップの先頭（セクタ 1）から走査すると、ディスクが使用されるにつれて走査コストが O(N²) に悪化し、メガバイト単位のファイル書き込み時に数秒のレイテンシが発生します。 SylFS では next_bitmap_hint に前回確保したビットマップセクタ番号を記憶させ、次回の探索をその位置から開始します。これにより連続確保が事実上 O(1) で完了し、ディスク満杯時にはリング状に一巡して全空き領域を漏れなく検知します。

余剰ビット（境界外）の保護

ビットマップセクタの総ビット数は通常、デバイスの有効セクタ数よりわずかに多くなります（端数）。SylFS は allocated_sector >= total_usable_sectors を厳格に検査し、実在しない架空のセクタ番号が払い出されるのを防ぎます。

ストレージ階層ポリシー（Storage Policy）

pub const TEMP_PREFIXES: &[&str] = &["/cache/", "/tmp/"];

pub fn target_for(path: &str) -> StorageTarget {
    let p = path.trim();
    for prefix in TEMP_PREFIXES {
        if p.starts_with(prefix) {
            return StorageTarget::Volatile; // RAM 上。電源断で消えてよい
        }
    }
    StorageTarget::Persistent // SD カード。電源断後も残す
}

• Dedicated RAMDisk（専用揮発性ディスク）: Raspberry Pi 3B+ の 1GB RAM のうち、カーネルヒープの終端から GPU デバイス領域開始地点（mmu::DEVICE_REGION_START）までの広大な物理 RAM 領域（実測約 332MB）をヒープ外メモリとして直接 SylFS に割り当てます。
• 寿命保護: Web ブラウザの画像やスタイルシート、スクリプトキャッシュはすべて /cache/ 配下に保存され、SD カードの NAND フラッシュ書き換え回数を一切消費しません。

4. 排他制御と並行性（SMP Safety）

SylFS は、マルチコア並行アクセスおよびパニック時の耐障害性を確保するため、以下の同期機構を備えています。

FS_LOCK (RecoverableMutex<()>)

pub static FS_LOCK: crate::kernel::reclock::RecoverableMutex<()> =
    crate::kernel::reclock::RecoverableMutex::new(());

• 背景: ブラウザのバックグラウンドワーカー（フォントデコーダ、WebP 画像デコーダ、HTTP ダウンローダ等）がマルチコアで動作する際、同時に get_fs() を呼び出してビットマップや B-Tree を操作すると、セクタの二重割り当てやインデックス破壊が発生します。
• ロック保持ルール: ファイルシステムのメタデータを変更または走査するすべてのコンテキストは、操作を行うスコープ内で let _guard = crate::kernel::fs::FS_LOCK.lock(); を取得しなければなりません。
• パニック時の強制ロック回収 (force_release_locks): AtmOS は panic = "abort" で動作しており、スタックの巻き戻し（Unwinding）が行われません。デコーダ等の処理中に特定コアでパニックが発生した場合、通常のミューテックスではロックが永久に握られたままになり、OS 全体がデッドロック（ハングアップ）します。 RecoverableMutex はロックを保持している Core ID を記録しており、パニックハンドラから force_release_locks(core_id) を呼び出すことで、異常終了したコアのロックのみを安全に解放し、健全な他コアの FS 処理を継続させます。

5. API リファレンス

カーネル内部 Rust API

初期化・マウント

pub fn mount() -> Result<(), &'static str>

ファイルシステムをマウントします。microSD カード（SDHOST）の初期化を試行し、検出できた場合は SDCard バックエンドでマウントします。初期化に失敗した場合は Dedicated RAMDisk へ自動フォールバックします。未フォーマットの場合は自動的にフォーマットを実行します。また、/cache/ 等の一時ファイル用 RAMDisk の紐付けと、プリインストールアプリ（APP_ASSETS）の整合性確認を行います。

pub fn format_device(device: &mut MirroredBlockDevice<block::BackendDevice>) -> Result<Superblock, &'static str>

ブロックデバイスを SylFS 形式で初期化（フォーマット）します。ビットマップ領域およびセクタ 0 のスーパーブロックを正しく書き込みます。

pub fn is_mounted() -> bool

SylFS がマウント済みであるかを返します。

pub fn get_fs() -> &'static mut SylFS

グローバルな SylFS インスタンスへの可変参照を取得します。呼び出し時は必ず FS_LOCK を保持している必要があります。

ファイル操作 API

pub fn save_file(&mut self, filename: &str, content: &[u8], labels: &str) -> Result<(), &'static str>

ファイルを保存または完全上書きします（COW 方式）。 - 引数: - filename: 保存先のパス（例: "/user/memo.txt"、最大 127 バイト） - content: ファイルデータの生バイト列 - labels: 検索用ラベル（カンマ区切り、例: "user,doc"、最大 63 バイト） - 戻り値: 成功時は Ok(())、容量不足やハードウェア書き込み失敗時は Err(&'static str)

pub fn read_file_checked(&mut self, filename: &str) -> Result<Option<(FileMetadata, Vec<u8>)>, &'static str>

指定されたパスのファイルを読み込みます。「存在しない」ことと「破損等の異常で読めない」ことを明確に区別して返します。 - 引数: - filename: 読み出すファイルのパス - 戻り値: - Ok(Some((meta, data))): 正常に読み出し完了 - Ok(None): ファイルが存在しない（正常） - Err("metadata sector unreadable"): メタデータが破損しており読み込めない - Err("filename hash collision"): ハッシュ衝突が発生した - Err("extent list unreadable"): エクステント情報が読み込めない - Err("data sector unreadable"): データブロックが破損しており両系復旧も失敗した - Err("file data is truncated"): 実データが途中で途切れている

pub fn read_file(&mut self, filename: &str) -> Option<(FileMetadata, Vec<u8>)>

read_file_checked の簡易ラッパーです。エラー発生時はカーネルエラーログを出力し None を返します。

pub fn delete_file(&mut self, filename: &str) -> Result<(), &'static str>

ファイルを削除します。 - メタデータセクタ内の filename[0] を 0（NUL）に書き換えて論理削除マークを付与します。 - 当該ファイルが占有していた全データセクタおよび溢れエクステントセクタをビットマップ上で即座に解放（deallocate_sector）します。 - B-Tree のダングリングポインタ化を防ぐため、メタデータセクタ自身は予約セクタとして残します。

pub fn list_files(&mut self) -> Vec<FileMetadata>

ファイルシステム内に存在するすべての有効な通常ファイル（削除済みを除く）のメタデータ一覧を返します。SD カードおよび RAMDisk（一時領域）の双方が結合されます。

pub fn list_dir(&mut self, prefix: &str) -> Vec<FileMetadata>

指定されたディレクトリパス（接頭辞 prefix）で始まるファイルをすべて列挙します。

pub fn find_by_label(&mut self, label: &str) -> Vec<FileMetadata>

指定されたラベル（例: "font"）を持つすべてのファイルをメタデータ走査により高速抽出します。

pub fn fsck(&mut self) -> Result<FsckReport, &'static str>

ファイルシステム全体の整合性検査（fsck）を実行し、統計情報と健全性フラグを返します。 - 検査項目（2026-11-10 に到達性の検査へ強化）: - スーパーブロック・ビットマップ・B-tree の全節点・メタデータ（衝突の連鎖の 2 個目以降も）・データ・溢れのチェーンから実際に届くセクタに印を付ける。 - 印とビットマップを突き合わせる: 使用中だが届かない＝漏れ（leaked_sectors）、届くのに空き＝破損（unallocated_refs。次の確保で上書きされる）、2 か所から届く＝二重参照（double_refs）。範囲外の番号・読めないセクタは corrupted_sectors。 - is_healthy は破損・二重参照・範囲外が 0 のとき真。漏れはデータを壊さないので健全のまま、数だけ報告する。 - 戻り値: 成功時は Ok(FsckReport)（is_healthy, total_sectors, used_sectors, file_count, extent_count, btree_node_count, corrupted_sectors, leaked_sectors, unallocated_refs, double_refs） - 以前はビットマップの使用数を数え、木の葉が指す先頭のメタデータだけを見ていたので、漏れも解放済みのセクタを指す破損も、衝突の連鎖の 2 個目以降のファイルも見えなかった。 - 試験 arm/v1/tests/src/test_fs_fsck_random.rs は、断片化させた上で保存・上書き・削除・名前の変更・切り詰め・伸長を無作為に約 3,000 回繰り返し、毎回この fsck（漏れも 0）と中身を確かめる。

Aura スクリプト組み込みコマンド / システムコール

Aura シェルおよびスクリプト環境から直接呼び出し可能なファイルシステム関連の組み込み関数一覧です。

6. エラーハンドリング・耐障害性・デバッグ

主要エラーコードと原因・対策

自己修復のテスト手法（フォールトインジェクション）

SylFS では、Aura の corrupt コマンドおよびカーネル単体テストを通じて、意図的に特定セクタの生データを破壊し、自己修復機能が正しく動作するかを検証できます。

;; 1. テストファイルを保存
(save "/user/test.txt" "AtmOS Resilient Storage Data" "test")

;; 2. ファイルのメタ情報とセクタを確認して生セクタを意図的に破壊
(corrupt 5)

;; 3. 再度読み出しを試みる
;; カーネルは CRC 不一致を検知し、ミラーセクタから自動修復して正常に内容を表示する
(cat "/user/test.txt")
;; ログ出力:
;; [WARN ] CRC mismatch on Primary Sector 5. Initiating Self-Healing...
;; [INFO ] Mirror Sector 524293 is healthy. Healing Primary Sector 5...
;; => "AtmOS Resilient Storage Data"

7. 実装ファイル構成 & 単体テスト体系

カーネル実装ファイル一覧

ホスト完全隔離テスト体系

カーネルのソースコード（src/）に一切テストコードを混入させず、arm/v1/tests/ ディレクトリ配下の独立テストクレートから検証されます。ホスト環境（macOS / Linux）上で make test により数ミリ秒で全件実行されます。

8. 実践コード例

1. カーネル内部（Rust）からの利用例

設定ファイルの安全な読み書き

use crate::kernel::fs::{get_fs, FS_LOCK};

pub fn save_system_config(config_json: &str) -> Result<(), &'static str> {
    // 1. マルチコア排他ロックを取得
    let _guard = FS_LOCK.lock();
    let fs = get_fs();

    // 2. ラベル "sys,config" を付与してアトミック保存
    fs.save_file("/sys/config.json", config_json.as_bytes(), "sys,config")?;
    crate::info!("[CONFIG] System configuration successfully updated.");
    Ok(())
}

pub fn load_system_config() -> Result<String, &'static str> {
    let _guard = FS_LOCK.lock();
    let fs = get_fs();

    // 存在しないことと破損を厳格に区別
    match fs.read_file_checked("/sys/config.json")? {
        Some((_meta, data)) => {
            let text = alloc::string::String::from_utf8(data)
                .map_err(|_| "Invalid UTF-8 in config")?;
            Ok(text)
        }
        None => {
            crate::warn!("[CONFIG] Config not found, generating default.");
            Ok(alloc::string::String::from("{}"))
        }
    }
}

2. Aura スクリプトからの実用例

シナリオ A: 日常的なメモの作成とタグ検索

;; メモを作成して保存
(save "/user/notes/meeting.txt" "2026-11-09: SylFS 仕様策定ミーティング議事録" "work,meeting,spec")
(save "/user/notes/todo.txt" "1. ブラウザキャッシュ検証\n2. QEMU 音声出力テスト" "work,todo")

;; "meeting" タグがついたメモを一覧検索
(find "meeting")

;; 内容を確認
(cat "/user/notes/meeting.txt")

シナリオ B: ディレクトリ構造の操作とファイル整理

;; ディレクトリ作成
(mkdir "/user/archive")

;; ファイルをアーカイブへ移動
(mv "/user/notes/meeting.txt" "/user/archive/meeting_20261109.txt")

;; 一覧確認 (詳細表示)
(ls "-l" "/user/archive/")

;; 不要になったファイルの削除
(rm "/user/notes/todo.txt")

シナリオ C: システムログの監視

;; 最新のログ末尾 15 行を確認
(tail "/tmp/system.log" 15)

;; エラー行を抽出
(grep "ERROR" "/tmp/system.log")

削除（delete_file、2026-11-10）

1. 連鎖を先頭からたどり、消す節とその前の節を探す。
2. 連鎖の途中なら、前の節の collision_next_sector を次の節へつなぎ替える。連鎖の先頭なら、木の値を次の節（無ければ 0 =「削除した」印）へ差し替えてスーパーブロックを書き、確定する。
3. データ・溢れのチェーン・メタデータのセクタを返す。2 で木を写せなかった（満杯）ときは、メタデータに印（ファイル名の先頭を 0）を付けて残し、データだけ返す。

search と一覧（collect_leaf_entries）は値 0 のキーを「無い」として扱う。以前は印を付けたメタデータを必ず 1 セクタ残したので、別々のパスを作っては消すと空きが減り続けた（512 セクタで 473 個目に満杯）。

一覧（collect_leaf_entries）の打ち切りは、深さ 32 で行う。以前はたどった節点の総数が 100 を超えると打ち切っていたので、ファイルが約 1,200 個を超えると一覧・fsck から黙って漏れた（3000 個中 1483 個しか出なかった）。

名前の変更（rename_file、2026-11-10）

1. 移動先の名前が既にあれば失敗する。
2. 古い名前を連鎖から外す。連鎖の先頭なら木の値を次の節へ差し替える。途中なら、先頭からその手前までの節を空きセクタへ写し（つなぎ先だけ変える）、木の値を写しの先頭へ差し替える（生きている節はその場で書き換えない）。
3. 新しいメタデータ（データ・溢れ・ラベルを引き継ぐ）を空きセクタに書き、移動先の連鎖の先頭につなぐ。
4. 2 と 3 の木の変更を同じ写しの上で行い、スーパーブロック 1 回で同時に切り替える。
5. 確定の後で、古いメタデータ・写す前の節・写す前の木の節点を返す。

以前は、新しい名前を確定した後に別の書き込みで古いメタデータへ削除の印を付けていたので、その間で電源が切れると 2 つの名前が同じデータを指したまま残った（電源断の試験で再現）。さらに以前は古い名前を先に削除済みにしていたので、木への登録に失敗するとファイルが消えた。

既知の制約（2026-11-10 時点）

• 削除したパスのキーは B-tree に残る（値を 0 =「削除した」印にする。節点の削除・併合は未実装）。キー 1 個は 20 バイトなので、別々のパスを数千個作っては消しても節点が数十個増える程度。満杯で木の節点を写せないときの削除は、メタデータに印を付けて 1 セクタ残す（次に同じハッシュへ保存するときに使い直す）。
• 切り詰めで溢れのチェーンを作り直すときは、新しいチェーンを先に空きセクタへ書くので、断片化した大きいファイルを満杯の記憶装置で切り詰めると「満杯」で失敗することがある（電源断で壊れない側を選んだ）。
• 衝突の連鎖の途中にあるファイルの削除・名前の変更は、電源断の試験で確かめていない（128 bit のハッシュの衝突を試験の中で作れないため。手順は論理的に点検した）。
• 一覧・ラベル検索は全件走査（ラベル・日時の索引は無い）。
• スーパーブロックの書き込みに失敗したときは、この操作で確保したセクタをその場では返さない（片系だけ書けていると新しい根が生きている場合があり、返すと壊れるため）。次の起動時の回収で戻る。
• QEMU では microSD のデータ転送の確認に失敗し、RAMDisk だけで動く（一時ファイルを RAMDisk へ振り分ける経路はホストの単体試験で確かめている）。

付録: 定数・マジックナンバー一覧 & 限界値

定数定義テーブル

システム限界値