@principles/core 1.179.0 → 1.181.0

package/README.md

@@ -3,27 +3,45 @@
 > **Pure logic only — no I/O.** This package must not import `fs`, `path`, or any
 > I/O module. All filesystem/DB/network operations belong in `openclaw-plugin`.
 
-## Boundary enforcement (PRI-450)
+## Boundary enforcement (PRI-450 / PRI-462)
 
 Three automated layers prevent I/O from leaking into core:
 
-1. **Architecture-regression test** — `runtime-v2/__tests__/architecture-regression.test.ts`
-   scans every `.ts` file under `src/` for `fs`/`path` imports and compares against
-   an explicit whitelist (`ALLOWED_IO_FILES`). Any new I/O file must be added there.
-
-2. **ESLint `no-restricted-imports`** — `eslint.config.js` bans `fs`/`path` imports
-   in `packages/principles-core/src/`. Whitelisted files and test files are exempt.
-
-3. **PR template & AGENTS.md** — the PR checklist asks whether new `fs`/`path` imports
-   were added; AGENTS.md lists "writing I/O code in core" as an anti-pattern trigger.
+1. **I/O seam registry** — `io-seam-registry.json` is the single source of truth
+   for which production files may import `fs`/`path`. Each file belongs to a
+   named seam with a description explaining WHY the I/O is allowed. Both the
+   architecture-regression test and ESLint derive their exemption lists from
+   this registry — there is no second hand-maintained list.
+
+2. **Architecture-regression test** — `runtime-v2/__tests__/architecture-regression.test.ts`
+   loads the registry, scans every `.ts` file under `src/` for `fs`/`path` imports,
+   and verifies they match the registry. Any new I/O file must be added to the
+   registry — otherwise CI fails.
+
+3. **ESLint `no-restricted-imports`** — `eslint.config.js` bans `fs`/`path` imports
+   in `packages/principles-core/src/`. The exemption list is generated from the
+   registry at lint time.
+
+### Named I/O seams
+
+| Seam | Files | Why allowed |
+|------|-------|-------------|
+| `ledger-tree` | `principle-tree-ledger.ts` | File-based principle ledger SSOT; pd-cli reads/writes without importing openclaw-plugin |
+| `sdk-store` | `evolution-store.ts`, `trajectory-store.ts`, `workflow-funnel-loader.ts` | Standalone SDK store primitives exposed as package subpaths |
+| `sqlite-state-store` | `runtime-v2/store/sqlite-connection.ts`, `runtime-v2/store/runtime-state-manager.ts` | runtime-v2 state.db connection + manager |
+| `cli-runtime-adapter` | `runtime-v2/adapter/openclaw-cli-runtime-adapter.ts` | Spawns openclaw CLI process |
+| `read-model` | 5 `*read-model*.ts` files | Read-only composite models querying state.db + ledger |
+| `audit-observability` | `candidate-audit.ts`, `pain-signal-observability.ts` | Audit + pain signal observability writers |
+| `remediation-review` | `internalization-integrity-remediation.ts`, `pruning-review-log.ts` | Integrity remediation + pruning review log |
 
 ### Adding a new I/O file (rare — prefer plugin)
 
 If a core file genuinely needs I/O:
 
-1. Add the file path to `ALLOWED_IO_FILES` in `architecture-regression.test.ts`
-2. Add the file path to the exemption list in `eslint.config.js`
-3. Explain in the PR why the I/O cannot live in `openclaw-plugin`
+1. Add the file path to the appropriate seam in `io-seam-registry.json`
+   (or create a new seam with a name and description)
+2. Explain in the PR why the I/O cannot live in `openclaw-plugin`
+3. Both the architecture-regression test and ESLint exemption update automatically
 
 ## Usage
 

package/dist/runtime-v2/__tests__/architecture-regression.test.js

@@ -3192,33 +3192,31 @@ describe('PRI-443: pure module boundary guards', () => {
         expect(src).not.toMatch(/export\s+type\s+\{\s*LedgerTreeStore\s*\}\s*from\s*['"]\.\.\/principle-tree-ledger\.js['"]/);
     });
 });
-// ── PRI-450: Core I/O whitelist guard ──────────────────────────────────────────
-//
-// Scans all production (.ts, non-test) files under packages/principles-core/src/
-// for fs/path imports and verifies they match an explicit whitelist. Any new file
-// that needs I/O must be added to ALLOWED_IO_FILES here — otherwise CI fails.
-// This forces developers to explain "why does this file need I/O?" in their PR.
-describe('PRI-450: core I/O whitelist guard', () => {
-    // Whitelist of production files allowed to import fs/path.
-    // Paths are relative to packages/principles-core/src/.
-    const ALLOWED_IO_FILES = new Set([
-        'principle-tree-ledger.ts',
-        'evolution-store.ts',
-        'trajectory-store.ts',
-        'workflow-funnel-loader.ts',
-        'runtime-v2/store/sqlite-connection.ts',
-        'runtime-v2/store/runtime-state-manager.ts',
-        'runtime-v2/adapter/openclaw-cli-runtime-adapter.ts',
-        'runtime-v2/candidate-audit.ts',
-        'runtime-v2/pain-signal-observability.ts',
-        'runtime-v2/internalization-chain-integrity-read-model.ts',
-        'runtime-v2/internalization-integrity-remediation.ts',
-        'runtime-v2/operator-health-read-model.ts',
-        'runtime-v2/pain-chain-read-model.ts',
-        'runtime-v2/pruning-read-model.ts',
-        'runtime-v2/pruning-review-log.ts',
-        'runtime-v2/schema-conformance-read-model.ts',
-    ]);
+describe('PRI-450 / PRI-462: core I/O seam registry guard', () => {
+    // Registry lives at packages/principles-core/io-seam-registry.json
+    // (3 levels up from __tests__: __tests__ → runtime-v2 → src → principles-core)
+    const registryPath = pathSync.resolve(__dirname, '..', '..', '..', 'io-seam-registry.json');
+    const registryRaw = fsSync.readFileSync(registryPath, 'utf-8');
+    const registry = JSON.parse(registryRaw);
+    // Runtime-validate the registry shape (Runtime Contract Rule 1+2: treat
+    // parsed JSON as unknown, validate with typeof/Array.isArray before access).
+    // `as` is used only for type narrowing AFTER runtime checks, not to bypass them.
+    function isValidRegistry(v) {
+        if (typeof v !== 'object' || v === null || !Object.hasOwn(v, 'seams'))
+            return false;
+        const { seams } = v;
+        if (!Array.isArray(seams))
+            return false;
+        return seams.every((s) => typeof s === 'object' && s !== null &&
+            typeof s.name === 'string' &&
+            typeof s.description === 'string' &&
+            Array.isArray(s.files) &&
+            s.files.every((f) => typeof f === 'string'));
+    }
+    // Flatten all registry files into a Set (relative to packages/principles-core/src/).
+    const ALLOWED_IO_FILES = new Set(isValidRegistry(registry)
+        ? registry.seams.flatMap((s) => s.files)
+        : []);
     // Extract all import module paths from source code.
     // Handles: import ... from 'mod', import 'mod' (side-effect), and multiline imports.
     // Reuses the same pattern proven in the PRI-215 extractImportModulePaths helper.
@@ -3257,7 +3255,52 @@ describe('PRI-450: core I/O whitelist guard', () => {
             }
         }
     }
-    it('core/src/ production files: only whitelisted files import fs/path', () => {
+    // ── Registry validity (PRI-462) ───────────────────────────────────────────
+    it('io-seam-registry.json is valid: seams array with name/description/files', () => {
+        expect(isValidRegistry(registry)).toBe(true);
+        if (!isValidRegistry(registry))
+            return; // type narrowing
+        expect(registry.seams.length).toBeGreaterThan(0);
+        for (const seam of registry.seams) {
+            expect(seam.name.length).toBeGreaterThan(0);
+            expect(seam.description.length).toBeGreaterThan(0);
+            expect(seam.files.length).toBeGreaterThan(0);
+        }
+    });
+    it('registry has no duplicate files across seams', () => {
+        if (!isValidRegistry(registry)) {
+            // isValidRegistry test above will fail with details; skip here.
+            expect(isValidRegistry(registry)).toBe(true);
+            return;
+        }
+        const seen = new Set();
+        const dupes = [];
+        for (const seam of registry.seams) {
+            for (const f of seam.files) {
+                if (seen.has(f))
+                    dupes.push(f);
+                seen.add(f);
+            }
+        }
+        expect(dupes).toEqual([]);
+    });
+    it('every seam description explains why the I/O is allowed (non-trivial)', () => {
+        if (!isValidRegistry(registry)) {
+            expect(isValidRegistry(registry)).toBe(true);
+            return;
+        }
+        const weak = [];
+        for (const seam of registry.seams) {
+            // Description must be at least 20 chars — a single word like "legacy" is
+            // not an explanation. This forces maintainers to write a real rationale.
+            if (seam.description.trim().length < 20) {
+                weak.push(`${seam.name}: "${seam.description}"`);
+            }
+        }
+        expect(weak).toEqual([]);
+    });
+    // ── Registry ↔ production files (PRI-450, EP-02) ──────────────────────────
+    it('core/src/ production files: only registry-listed files import fs/path', () => {
         const coreSrcDir = pathSync.resolve(__dirname, '..', '..');
         const allFiles = [];
         collectTsFiles(coreSrcDir, allFiles);
@@ -3271,9 +3314,13 @@ describe('PRI-450: core I/O whitelist guard', () => {
                 }
             }
         }
-        expect(violations).toEqual([]);
+        if (violations.length > 0) {
+            throw new Error(`Found ${violations.length} file(s) importing fs/path that are NOT in io-seam-registry.json.\n` +
+                `Add them to the appropriate seam in packages/principles-core/io-seam-registry.json.\n` +
+                `Violations:\n  ` + violations.join('\n  '));
+        }
     });
-    it('ALLOWED_IO_FILES whitelist entries all exist on disk', () => {
+    it('registry-listed files all exist on disk', () => {
         const coreSrcDir = pathSync.resolve(__dirname, '..', '..');
         const missing = [];
         for (const relPath of ALLOWED_IO_FILES) {
@@ -3284,6 +3331,19 @@ describe('PRI-450: core I/O whitelist guard', () => {
         }
         expect(missing).toEqual([]);
     });
+    // ── Registry ↔ ESLint exemption (PRI-462, EP-06 single source of truth) ───
+    //
+    // ESLint's no-restricted-imports exemption list must be DERIVED from the
+    // registry, not hand-maintained. This test verifies eslint.config.js
+    // references the registry file, proving the two stay in sync.
+    it('eslint.config.js derives fs/path exemption from the registry (no shadow list)', () => {
+        const eslintPath = pathSync.resolve(__dirname, '..', '..', '..', '..', '..', 'eslint.config.js');
+        const eslintSrc = fsSync.readFileSync(eslintPath, 'utf-8');
+        // The eslint config must read the registry JSON — if this reference is
+        // removed, someone has reintroduced a hand-maintained shadow list.
+        expect(eslintSrc).toContain('io-seam-registry.json');
+    });
+    // ── Helper unit tests ─────────────────────────────────────────────────────
     it('importsFsOrPath detects sub-path imports (fs/promises) and side-effect imports', () => {
         // Sub-path import
         expect(importsFsOrPath(`import { mkdir } from 'node:fs/promises';`)).toBe(true);