feat(metadata-fs): FileSystemRepository with chokidar watch + JSONL log (ADR-0008 M0 PR-4)

New package @objectstack/metadata-fs:
- repository.ts: FileSystemRepository implementing the M0 contract
  against a <root>/<type>/<name>.json + JSONL log layout. Atomic writes
  (tmpfile + rename), heads/seq recovered from log on start, chokidar
  watch translates external edits to events with source='fs', 200ms
  self-write suppression window.
- layout.ts: path helpers + parseItemPath().
- jsonl-log.ts: append-only log reader/writer with corrupt-line skip.
- sync.ts: KeyedMutex (per-key serialization) + event broker.
- watch-iterable.ts: manual AsyncIterator (reusable from in-memory pkg).
- 17 contract tests + 5 fs-specific tests pass.

metadata-core:
- Add singleBranch option to contract suite (FS is one branch per repo).
- tsup splitting: true so testing.js shares one ConflictError class
  identity with index.js (was double-bundled, breaking instanceof).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: os-zhuang

.changeset/metadata-fs-init.md

@@ -0,0 +1,37 @@
+---
+'@objectstack/metadata-fs': minor
+'@objectstack/metadata-core': patch
+---
+
+Add `@objectstack/metadata-fs` — Node-only `FileSystemRepository`
+implementation of the M0 Repository contract.
+
+Layout:
+
+```
+<root>/
+  <type>/<name>.json          # canonical body (atomic rename writes)
+  .objectstack/.log/<branch>.jsonl   # append-only change log
+```
+
+Features:
+
+- All 17 contract tests pass (`singleBranch: true`).
+- Per-key serialization via `KeyedMutex`.
+- Atomic writes via tmpfile + rename.
+- Heads and `seq` recovered from the JSONL log on `start()` — survives
+  process restart.
+- chokidar watcher translates external edits (e.g. VSCode saves) into
+  `MetadataEvent`s with `source: 'fs'`.
+- Self-write suppression: 200ms window prevents the watcher from
+  re-emitting events for files we wrote ourselves.
+- Manual `AsyncIterator` for `watch()` to mirror the in-memory pattern.
+
+Also (`metadata-core`):
+
+- Add `singleBranch` option to `runRepositoryContractTests` so
+  single-branch backends (like the FS one) skip the cross-branch test.
+- Switch tsup `splitting: true` so `index.js` and `testing.js` share a
+  single `ConflictError` class identity (was double-bundled before).
+
+See ADR-0008 §10 PR-4.

packages/metadata-core/src/contract-suite.ts

@@ -27,6 +27,12 @@ import { ConflictError } from './errors.js';
 export interface ContractSuiteOptions {
   /** If the implementation supports `version`-pinned reads, set true. */
   supportsVersionedReads?: boolean;
+  /**
+   * Set true for backends that are scoped to a single branch (e.g. the
+   * FileSystemRepository is one branch per instance). The cross-branch
+   * test is skipped.
+   */
+  singleBranch?: boolean;
 }
 
 const refOf = (overrides: Partial<MetaRef> = {}): MetaRef => ({
@@ -171,6 +177,7 @@ export function runRepositoryContractTests(
       });
 
       it('different branches have independent sequences', async () => {
+        if (opts.singleBranch) return;
         const repo = await factory();
         const mainRef = refOf({ branch: 'main' });
         const devRef = refOf({ branch: 'dev' });

packages/metadata-core/tsup.config.ts

@@ -4,7 +4,7 @@ import { defineConfig } from 'tsup';
 
 export default defineConfig({
   entry: ['src/index.ts', 'src/testing.ts'],
-  splitting: false,
+  splitting: true,
   sourcemap: true,
   clean: true,
   dts: true,

packages/metadata-fs/README.md

@@ -0,0 +1,52 @@
+# @objectstack/metadata-fs
+
+`FileSystemRepository` — Node-only implementation of the
+`MetadataRepository` contract defined in `@objectstack/metadata-core`.
+
+## Layout on disk
+
+```
+<root>/
+  <type>/
+    <name>.json          # canonical body of the item
+  .objectstack/
+    .log/
+      <branch>.jsonl     # append-only change log (one JSON object per line)
+```
+
+For example:
+
+```
+metadata/
+  view/
+    case_grid.json
+    case_timeline.json
+  object/
+    case.json
+  .objectstack/.log/main.jsonl
+```
+
+## Usage
+
+```ts
+import { FileSystemRepository } from '@objectstack/metadata-fs';
+
+const repo = new FileSystemRepository({
+  root: './metadata',
+  org: 'system',
+  project: 'crm',
+  branch: 'main',
+});
+await repo.start();          // scan + open watcher
+
+const view = await repo.get({
+  org: 'system', project: 'crm', branch: 'main',
+  type: 'view', name: 'case_grid',
+});
+
+for await (const evt of repo.watch({})) {
+  console.log('changed', evt.ref, evt.hash);
+}
+```
+
+See ADR-0008 §10 PR-4.

packages/metadata-fs/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@objectstack/metadata-fs",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "FileSystemRepository: Node-only Repository implementation backed by JSON files and a JSONL change log (ADR-0008).",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "objectstack",
+    "metadata",
+    "filesystem",
+    "repository"
+  ],
+  "dependencies": {
+    "@objectstack/metadata-core": "workspace:*",
+    "chokidar": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "author": "ObjectStack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/framework.git",
+    "directory": "packages/metadata-fs"
+  },
+  "homepage": "https://objectstack.ai/docs",
+  "bugs": "https://github.com/objectstack-ai/framework/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

packages/metadata-fs/src/index.ts

@@ -0,0 +1,5 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export * from './repository.js';
+export { JsonlLog } from './jsonl-log.js';
+export type { FsLayout } from './layout.js';

packages/metadata-fs/src/jsonl-log.ts

@@ -0,0 +1,59 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Append-only JSONL change log writer / reader. Each line is a single
+ * `MetadataEvent` serialized via `JSON.stringify`.
+ *
+ * Durability strategy
+ * ───────────────────
+ *   - Append with `O_APPEND` semantics (Node's `fs.appendFile` is
+ *     atomic for sub-PIPE_BUF-sized writes; events are well under 4 KiB).
+ *   - Read by streaming the file line-by-line and JSON.parse-ing each.
+ *   - On a corrupt line we skip and continue — the body files are the
+ *     source of truth; the log is a denormalised history index.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline';
+import { createReadStream, existsSync } from 'node:fs';
+import type { MetadataEvent } from '@objectstack/metadata-core';
+
+export class JsonlLog {
+  constructor(private readonly file: string) {}
+
+  async append(evt: MetadataEvent): Promise<void> {
+    await fs.mkdir(path.dirname(this.file), { recursive: true });
+    await fs.appendFile(this.file, JSON.stringify(evt) + '\n', 'utf8');
+  }
+
+  /** Read all events in seq order (i.e. file order). */
+  async *readAll(): AsyncIterable<MetadataEvent> {
+    if (!existsSync(this.file)) return;
+    const rl = readline.createInterface({
+      input: createReadStream(this.file, { encoding: 'utf8' }),
+      crlfDelay: Infinity,
+    });
+    try {
+      for await (const line of rl) {
+        if (!line.trim()) continue;
+        try {
+          yield JSON.parse(line) as MetadataEvent;
+        } catch {
+          // Skip corrupt line.
+        }
+      }
+    } finally {
+      rl.close();
+    }
+  }
+
+  /** Return the highest seq number in the log, or 0 if empty. */
+  async highestSeq(): Promise<number> {
+    let max = 0;
+    for await (const evt of this.readAll()) {
+      if (typeof evt.seq === 'number' && evt.seq > max) max = evt.seq;
+    }
+    return max;
+  }
+}

packages/metadata-fs/src/layout.ts

@@ -0,0 +1,50 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Disk layout helpers — see ADR-0008 §10 PR-4 / packages/metadata-fs README.
+ *
+ *   <root>/<type>/<name>.json          — canonical body
+ *   <root>/.objectstack/.log/<branch>.jsonl — append-only change log
+ */
+
+import path from 'node:path';
+import type { MetadataType } from '@objectstack/metadata-core';
+
+export interface FsLayout {
+  /** Absolute path to the metadata root. */
+  root: string;
+  /** Branch name (e.g. "main"). */
+  branch: string;
+}
+
+export function itemPath(layout: FsLayout, type: MetadataType, name: string): string {
+  return path.join(layout.root, type, `${name}.json`);
+}
+
+export function typeDir(layout: FsLayout, type: MetadataType): string {
+  return path.join(layout.root, type);
+}
+
+export function logDir(layout: FsLayout): string {
+  return path.join(layout.root, '.objectstack', '.log');
+}
+
+export function logFile(layout: FsLayout): string {
+  return path.join(logDir(layout), `${layout.branch}.jsonl`);
+}
+
+/** Parse a path like ".../view/case_grid.json" into {type, name}. */
+export function parseItemPath(
+  layout: FsLayout,
+  absPath: string,
+): { type: string; name: string } | null {
+  const rel = path.relative(layout.root, absPath);
+  if (rel.startsWith('..') || rel.startsWith('.objectstack')) return null;
+  const segments = rel.split(path.sep);
+  if (segments.length !== 2) return null;
+  const type = segments[0]!;
+  const file = segments[1]!;
+  if (!file.endsWith('.json')) return null;
+  const name = file.slice(0, -'.json'.length);
+  return { type, name };
+}