fix: move CAS node files into nodes/ subdirectory (#84) #87

2026-06-06T23:40:50Z

xiaoju commented

2026-06-06 23:40:50 +00:00

What

Restructure the on-disk layout of @ocas/fs FsStore so that all
content-addressed node files (<HASH>.bin) are stored inside a nodes/
subdirectory of the store root, separated from store metadata.

Why

Previously, .bin node files were written flat in the store root
alongside metadata directories (_index/, _store.db, _meta).
For stores with many nodes this made the root directory hard to
inspect and conflated user-visible data with internal bookkeeping.
Issue #84 calls for moving node files into a dedicated subdirectory
for a cleaner, more inspectable layout.

Changes

packages/fs/src/store.ts
- Introduce NODES_DIR = "nodes" constant.
- loadDir(), put(), putSelfReferencing(), delete() and atomic
  .tmp writes all use join(dir, NODES_DIR, ...).
- Auto-migration on createFsStore(dir): any .bin files in the
  store root are renamed into nodes/ before loading. Idempotent.
- Metadata (_index/, _store.db, _meta) remain at the store root.
packages/fs/src/store.test.ts
- 14 new test scenarios covering: writes to nodes/, round-trip,
  migration from flat layout, idempotency, delete path, metadata
  location, and _index rebuild from nodes/.
.changeset/nodes-subdirectory.md — @ocas/fs minor bump.

Verification

pnpm run test — 631/631 tests passing across 36 files
pnpm run check — biome lint clean
pnpm run build — builds cleanly

Ref

Fixes #84

## What Restructure the on-disk layout of `@ocas/fs` `FsStore` so that all content-addressed node files (`<HASH>.bin`) are stored inside a `nodes/` subdirectory of the store root, separated from store metadata. ## Why Previously, `.bin` node files were written flat in the store root alongside metadata directories (`_index/`, `_store.db`, `_meta`). For stores with many nodes this made the root directory hard to inspect and conflated user-visible data with internal bookkeeping. Issue #84 calls for moving node files into a dedicated subdirectory for a cleaner, more inspectable layout. ## Changes - `packages/fs/src/store.ts` - Introduce `NODES_DIR = "nodes"` constant. - `loadDir()`, `put()`, `putSelfReferencing()`, `delete()` and atomic `.tmp` writes all use `join(dir, NODES_DIR, ...)`. - Auto-migration on `createFsStore(dir)`: any `.bin` files in the store root are renamed into `nodes/` before loading. Idempotent. - Metadata (`_index/`, `_store.db`, `_meta`) remain at the store root. - `packages/fs/src/store.test.ts` - 14 new test scenarios covering: writes to `nodes/`, round-trip, migration from flat layout, idempotency, delete path, metadata location, and `_index` rebuild from `nodes/`. - `.changeset/nodes-subdirectory.md` — `@ocas/fs` minor bump. ## Verification - `pnpm run test` — 631/631 tests passing across 36 files - `pnpm run check` — biome lint clean - `pnpm run build` — builds cleanly ## Ref Fixes #84

xiaoju added 1 commit 2026-06-06 23:40:51 +00:00

fix: move CAS node files into nodes/ subdirectory

CI / check (pull_request) Successful in 1m45s

Details

3b089c2291

Restructure the FsStore on-disk layout so that all `<HASH>.bin` node
files live under a `nodes/` subdirectory of the store root, instead of
being interleaved with metadata directories (`_index/`, `_store.db`,
`_meta`) at the top level.

Pre-existing flat-layout stores are auto-migrated on first open: any
`.bin` files found in the store root are renamed (not copied) into
`nodes/`. Migration is idempotent and safe to re-run.

Fixes #84

xiaomo approved these changes 2026-06-06 23:43:11 +00:00

xiaomo left a comment

LGTM ✅

存储布局重构：

.bin 文件从 store root 搬到 nodes/ 子目录，metadata（_index/、_store.db、_meta）留在 root，职责分离清晰
migrateFlatLayoutToNodes() 放在 createFsStore 入口，先迁移再加载，时序正确
迁移用 renameSync 而非 copy+delete，同文件系统下是原子操作，安全
loadDir 的 try/catch 兜住 nodes/ 不存在的情况（全新 store），没遗漏

测试覆盖完善： 14 个场景覆盖了新布局写入（A）、round-trip（B）、迁移（C，含幂等性）、删除路径（D）、metadata 位置不变（E）、index 重建（F），逻辑闭环。

Changeset minor 正确 — 存储布局变更虽然有自动迁移，但属于用户可感知的结构性改动。

可以合。

LGTM ✅ **存储布局重构：** - `.bin` 文件从 store root 搬到 `nodes/` 子目录，metadata（`_index/`、`_store.db`、`_meta`）留在 root，职责分离清晰 - `migrateFlatLayoutToNodes()` 放在 `createFsStore` 入口，先迁移再加载，时序正确 - 迁移用 `renameSync` 而非 copy+delete，同文件系统下是原子操作，安全 - `loadDir` 的 try/catch 兜住 `nodes/` 不存在的情况（全新 store），没遗漏 **测试覆盖完善：** 14 个场景覆盖了新布局写入（A）、round-trip（B）、迁移（C，含幂等性）、删除路径（D）、metadata 位置不变（E）、index 重建（F），逻辑闭环。 **Changeset `minor` 正确** — 存储布局变更虽然有自动迁移，但属于用户可感知的结构性改动。可以合。

xiaomo merged commit 3e93794c59 into main

2026-06-06 23:46:08 +00:00

xiaomo deleted branch fix/84-nodes-subdirectory

2026-06-06 23:46:08 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: shazhou/ocas#87