Merge pull request #2719 from pikasTech/feat/hwpod-host-postgres

feat(hwpod): 持久化 runtime spec 到 PostgreSQL

internal/hwpod/http.ts

@@ -52,7 +52,10 @@ export function createHwpodHttpApp(options: { runtimeApiUrl: string; runtimeApiA
         return json(status, { ok: false, status: "failed", error: { code, message: error?.message ?? String(error), ...(error?.details && typeof error.details === "object" ? error.details : {}) }, valuesPrinted: false });
       }
     },
-    close: async () => options.temporal.close()
+    close: async () => {
+      await options.specRegistry.close?.();
+      await options.temporal.close();
+    }
   };
 }
 

internal/hwpod/spec-registry.test.ts

@@ -4,21 +4,15 @@
  * 责任: 验证 runtime spec CRUD、重启持久化与 YAML-first 内置冻结合同。
  */
 
-import { afterEach, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import path from "node:path";
+import { expect, test } from "bun:test";
 
 import { createHwpodHttpApp } from "./http.ts";
-import { createHwpodSpecRegistry } from "./spec-registry.ts";
-
-const temporaryDirs: string[] = [];
-afterEach(async () => { await Promise.all(temporaryDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true }))); });
+import { createHwpodSpecRegistry, type HwpodRuntimeSpecRecord, type HwpodRuntimeSpecStore } from "./spec-registry.ts";
 
 test("runtime spec repository persists CRUD and freezes YAML-first built-ins", async () => {
-  const runtimeDir = await tempDir();
+  const store = memoryStore();
   const builtIn = spec("builtin-pod", "/builtin");
-  const registry = createHwpodSpecRegistry({ runtimeDir, builtIns: [{ configRef: "config/hwpod.yaml#spec", sha256: "source-sha", document: builtIn }] });
+  const registry = createHwpodSpecRegistry({ store, builtIns: [{ configRef: "config/hwpod.yaml#spec", sha256: "source-sha", document: builtIn }] });
 
   const initial = await registry.list();
   expect(initial.specs).toHaveLength(1);
@@ -27,7 +21,7 @@ test("runtime spec repository persists CRUD and freezes YAML-first built-ins", a
   const created = await registry.create(spec("runtime-pod", "/runtime-v1"));
   expect(created).toMatchObject({ status: "created", hwpodId: "runtime-pod", authority: "runtime", mutable: true, frozen: false, mutation: true });
 
-  const restarted = createHwpodSpecRegistry({ runtimeDir, builtIns: [{ configRef: "config/hwpod.yaml#spec", document: builtIn }] });
+  const restarted = createHwpodSpecRegistry({ store, builtIns: [{ configRef: "config/hwpod.yaml#spec", document: builtIn }] });
   expect((await restarted.get("runtime-pod")).document.spec.workspace.path).toBe("/runtime-v1");
   expect((await restarted.update("runtime-pod", spec("runtime-pod", "/runtime-v2"))).status).toBe("updated");
   expect((await restarted.get("runtime-pod")).document.spec.workspace.path).toBe("/runtime-v2");
@@ -41,8 +35,7 @@ test("runtime spec repository persists CRUD and freezes YAML-first built-ins", a
 });
 
 test("L1 HWPOD HTTP exposes runtime CRUD and typed frozen errors", async () => {
-  const runtimeDir = await tempDir();
-  const registry = createHwpodSpecRegistry({ runtimeDir, builtIns: [{ configRef: "config/hwpod.yaml#spec", document: spec("builtin-pod", "/builtin") }] });
+  const registry = createHwpodSpecRegistry({ store: memoryStore(), builtIns: [{ configRef: "config/hwpod.yaml#spec", document: spec("builtin-pod", "/builtin") }] });
   const temporal = { close: async () => {}, start: async () => ({}), describe: async () => ({}), result: async () => ({}) };
   const app = createHwpodHttpApp({ runtimeApiUrl: "http://runtime.invalid", runtimeApiAuthorization: "Bearer test", temporal, specRegistry: registry });
 
@@ -65,5 +58,20 @@ async function request(app: any, method: string, pathname: string, body?: unknow
   return { status: response.status, body: await response.json() };
 }
 
-async function tempDir() { const dir = await mkdtemp(path.join(tmpdir(), "hwpod-spec-registry-")); temporaryDirs.push(dir); return dir; }
+function memoryStore(): HwpodRuntimeSpecStore {
+  const records = new Map<string, HwpodRuntimeSpecRecord>();
+  return {
+    list: async () => [...records.values()],
+    get: async (id) => records.get(id) ?? null,
+    create: async (record) => records.has(record.hwpodId) ? false : (records.set(record.hwpodId, structuredClone(record)), true),
+    update: async (id, document, updatedAt) => {
+      const existing = records.get(id);
+      if (!existing) return null;
+      const record = { ...existing, document: structuredClone(document), updatedAt };
+      records.set(id, record);
+      return record;
+    },
+    delete: async (id) => { const record = records.get(id) ?? null; records.delete(id); return record; },
+  };
+}
 function spec(name: string, workspacePath: string) { return { apiVersion: "hwlab.dev/v0alpha1", kind: "Hwpod", metadata: { name }, spec: { targetDevice: { board: "test" }, workspace: { path: workspacePath }, debugProbe: { type: "test" }, ioProbe: { type: "test" }, nodeBinding: { nodeId: "node-test" } } }; }

internal/hwpod/spec-registry.ts

@@ -1,40 +1,46 @@
 /*
  * SPEC: PJ2026-010102 HWPOD 工具；PJ2026-010103 HWPOD 服务；
  * PJ2026-01010305 71FREQ 预装 draft-2026-06-26-71freq-v03-hwpod-preinstall。
- * 责任: 为 L0 native function 与 L1 API 提供同一 HWPOD runtime spec registry。
+ * 责任: 为 L0-L3 提供唯一 host PostgreSQL runtime spec registry。
  */
 
-import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
+import { createHash } from "node:crypto";
+import pg from "pg";
 
+import { buildPostgresPoolConfig, postgresSslModeFromConnectionString } from "../db/runtime-store-core.ts";
 import { normalizeHwpodSpec } from "./spec-document.ts";
 
-const CONTRACT_VERSION = "hwpod-spec-registry-v2";
+const { Pool } = pg;
+const CONTRACT_VERSION = "hwpod-spec-registry-v3";
 
 type BuiltInInput = { configRef: string; sha256?: string; document: unknown };
-type RuntimeRecord = { contractVersion: string; authority: "runtime"; hwpodId: string; createdAt: string; updatedAt: string; document: unknown };
-
-export function hwpodSpecRegistryFromEnv(env: Record<string, string | undefined> = process.env, options: { cwd?: string; runtimeDir?: string } = {}) {
-  const cwd = options.cwd ?? process.cwd();
-  const runtimeDirValue = String(options.runtimeDir ?? env.HWPOD_RUNTIME_SPEC_REGISTRY_DIR ?? "").trim();
-  if (!runtimeDirValue) throw codedError("hwpod_runtime_spec_registry_dir_required", "HWPOD_RUNTIME_SPEC_REGISTRY_DIR or --runtime-spec-dir is required");
-  const runtimeDir = path.resolve(cwd, runtimeDirValue);
-  const builtIns = parseBuiltIns(env.HWPOD_BUILTIN_SPEC_DOCUMENTS_JSON);
-  return createHwpodSpecRegistry({ runtimeDir, builtIns });
+export type HwpodRuntimeSpecRecord = { authority: "runtime"; hwpodId: string; createdAt: string; updatedAt: string; document: unknown };
+export interface HwpodRuntimeSpecStore {
+  list(): Promise<HwpodRuntimeSpecRecord[]>;
+  get(hwpodId: string): Promise<HwpodRuntimeSpecRecord | null>;
+  create(record: HwpodRuntimeSpecRecord): Promise<boolean>;
+  update(hwpodId: string, document: unknown, updatedAt: string): Promise<HwpodRuntimeSpecRecord | null>;
+  delete(hwpodId: string): Promise<HwpodRuntimeSpecRecord | null>;
+  close?(): Promise<void>;
 }
 
-export function createHwpodSpecRegistry(options: { runtimeDir: string; builtIns?: BuiltInInput[]; now?: () => string }) {
-  const runtimeDir = path.resolve(options.runtimeDir);
+export function hwpodSpecRegistryFromEnv(env: Record<string, string | undefined> = process.env) {
+  const databaseUrl = requiredEnv(env, "HWPOD_SPEC_DATABASE_URL");
+  const schema = postgresIdentifier(requiredEnv(env, "HWPOD_SPEC_DATABASE_SCHEMA"), "HWPOD_SPEC_DATABASE_SCHEMA");
+  const table = postgresIdentifier(requiredEnv(env, "HWPOD_SPEC_DATABASE_TABLE"), "HWPOD_SPEC_DATABASE_TABLE");
+  const builtIns = parseBuiltIns(env.HWPOD_BUILTIN_SPEC_DOCUMENTS_JSON);
+  return createHwpodSpecRegistry({ store: createPostgresHwpodRuntimeSpecStore({ databaseUrl, schema, table }), builtIns });
+}
+
+export function createHwpodSpecRegistry(options: { store: HwpodRuntimeSpecStore; builtIns?: BuiltInInput[]; now?: () => string }) {
+  const store = options.store;
   const now = options.now ?? (() => new Date().toISOString());
   const builtIns = normalizeBuiltIns(options.builtIns ?? []);
 
   async function list() {
-    const runtime = await readRuntimeRecords(runtimeDir);
+    const runtime = new Map((await store.list()).map((record) => [record.hwpodId, record]));
     assertNoAuthorityConflicts(builtIns, runtime);
-    const specs = [...builtIns.values(), ...runtime.values()]
-      .map(summary)
-      .sort((left, right) => left.hwpodId.localeCompare(right.hwpodId));
+    const specs = [...builtIns.values(), ...runtime.values()].map(summary).sort((left, right) => left.hwpodId.localeCompare(right.hwpodId));
     return { ok: true, status: specs.length === 0 ? "empty" : "completed", contractVersion: CONTRACT_VERSION, count: specs.length, specs, valuesPrinted: false };
   }
 
@@ -42,7 +48,7 @@ export function createHwpodSpecRegistry(options: { runtimeDir: string; builtIns?
     const id = validId(hwpodId);
     const builtIn = builtIns.get(id);
     if (builtIn) return entity(builtIn);
-    const runtime = (await readRuntimeRecords(runtimeDir)).get(id);
+    const runtime = await store.get(id);
     if (!runtime) throw codedError("hwpod_spec_not_found", `HWPOD spec was not found: ${id}`, { hwpodId: id });
     return entity(runtime);
   }
@@ -51,39 +57,108 @@ export function createHwpodSpecRegistry(options: { runtimeDir: string; builtIns?
     const normalized = normalizedDocument(documentInput, "runtime:create");
     const id = specId(normalized);
     assertNotFrozen(id, builtIns);
-    const runtime = await readRuntimeRecords(runtimeDir);
-    if (runtime.has(id)) throw codedError("hwpod_spec_exists", `HWPOD runtime spec already exists: ${id}`, { hwpodId: id });
     const observedAt = now();
-    const record: RuntimeRecord = { contractVersion: CONTRACT_VERSION, authority: "runtime", hwpodId: id, createdAt: observedAt, updatedAt: observedAt, document: normalized };
-    await writeRuntimeRecord(runtimeDir, record);
+    const record: HwpodRuntimeSpecRecord = { authority: "runtime", hwpodId: id, createdAt: observedAt, updatedAt: observedAt, document: normalized };
+    if (!await store.create(record)) throw codedError("hwpod_spec_exists", `HWPOD runtime spec already exists: ${id}`, { hwpodId: id });
     return mutation("created", record);
   }
 
   async function update(hwpodId: string, documentInput: unknown) {
     const id = validId(hwpodId);
     assertNotFrozen(id, builtIns);
-    const runtime = await readRuntimeRecords(runtimeDir);
-    const existing = runtime.get(id);
-    if (!existing) throw codedError("hwpod_spec_not_found", `HWPOD runtime spec was not found: ${id}`, { hwpodId: id });
     const normalized = normalizedDocument(documentInput, `runtime:${id}`);
     const documentId = specId(normalized);
     if (documentId !== id) throw codedError("hwpod_spec_id_mismatch", `HWPOD spec document id ${documentId} does not match route id ${id}`, { hwpodId: id, documentHwpodId: documentId });
-    const record: RuntimeRecord = { ...existing, updatedAt: now(), document: normalized };
-    await writeRuntimeRecord(runtimeDir, record);
+    const record = await store.update(id, normalized, now());
+    if (!record) throw codedError("hwpod_spec_not_found", `HWPOD runtime spec was not found: ${id}`, { hwpodId: id });
     return mutation("updated", record);
   }
 
   async function remove(hwpodId: string) {
     const id = validId(hwpodId);
     assertNotFrozen(id, builtIns);
-    const runtime = await readRuntimeRecords(runtimeDir);
-    const existing = runtime.get(id);
+    const existing = await store.delete(id);
     if (!existing) throw codedError("hwpod_spec_not_found", `HWPOD runtime spec was not found: ${id}`, { hwpodId: id });
-    await rm(runtimeRecordPath(runtimeDir, id), { force: true });
     return { ok: true, status: "deleted", contractVersion: CONTRACT_VERSION, hwpodId: id, authority: "runtime", mutable: true, frozen: false, mutation: true, previousFingerprint: documentFingerprint(existing.document), valuesPrinted: false };
   }
 
-  return { list, get, create, update, delete: remove, runtimeDir };
+  return { list, get, create, update, delete: remove, close: async () => store.close?.() };
+}
+
+export function createPostgresHwpodRuntimeSpecStore(options: { databaseUrl: string; schema: string; table: string }): HwpodRuntimeSpecStore {
+  const schema = postgresIdentifier(options.schema, "schema");
+  const table = postgresIdentifier(options.table, "table");
+  const qualifiedTable = `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
+  const pool = new Pool(buildPostgresPoolConfig({
+    dbUrl: options.databaseUrl,
+    sslMode: postgresSslModeFromConnectionString(options.databaseUrl) ?? "disable",
+  }));
+  let ready: Promise<void> | undefined;
+
+  function ensureSchema() {
+    ready ??= migrate();
+    return ready;
+  }
+
+  async function migrate() {
+    const client = await pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(`CREATE SCHEMA IF NOT EXISTS ${quoteIdentifier(schema)}`);
+      await client.query(`CREATE TABLE IF NOT EXISTS ${qualifiedTable} (
+        hwpod_id TEXT PRIMARY KEY,
+        authority TEXT NOT NULL DEFAULT 'runtime' CHECK (authority = 'runtime'),
+        document JSONB NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      )`);
+      await client.query(`CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${table}_updated_at_idx`)} ON ${qualifiedTable} (updated_at DESC, hwpod_id)`);
+      await client.query("COMMIT");
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => {});
+      ready = undefined;
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
+  return {
+    async list() {
+      await ensureSchema();
+      const result = await pool.query(`SELECT hwpod_id, authority, document, created_at, updated_at FROM ${qualifiedTable} ORDER BY hwpod_id`);
+      return result.rows.map(runtimeRow);
+    },
+    async get(hwpodId) {
+      await ensureSchema();
+      const result = await pool.query(`SELECT hwpod_id, authority, document, created_at, updated_at FROM ${qualifiedTable} WHERE hwpod_id=$1`, [hwpodId]);
+      return result.rows[0] ? runtimeRow(result.rows[0]) : null;
+    },
+    async create(record) {
+      await ensureSchema();
+      const result = await pool.query(`INSERT INTO ${qualifiedTable} (hwpod_id, authority, document, created_at, updated_at) VALUES ($1,'runtime',$2::jsonb,$3,$4) ON CONFLICT (hwpod_id) DO NOTHING RETURNING hwpod_id`, [record.hwpodId, JSON.stringify(record.document), record.createdAt, record.updatedAt]);
+      return result.rowCount === 1;
+    },
+    async update(hwpodId, document, updatedAt) {
+      await ensureSchema();
+      const result = await pool.query(`UPDATE ${qualifiedTable} SET document=$2::jsonb, updated_at=$3 WHERE hwpod_id=$1 AND authority='runtime' RETURNING hwpod_id, authority, document, created_at, updated_at`, [hwpodId, JSON.stringify(document), updatedAt]);
+      return result.rows[0] ? runtimeRow(result.rows[0]) : null;
+    },
+    async delete(hwpodId) {
+      await ensureSchema();
+      const result = await pool.query(`DELETE FROM ${qualifiedTable} WHERE hwpod_id=$1 AND authority='runtime' RETURNING hwpod_id, authority, document, created_at, updated_at`, [hwpodId]);
+      return result.rows[0] ? runtimeRow(result.rows[0]) : null;
+    },
+    close: async () => pool.end(),
+  };
+}
+
+function runtimeRow(row: any): HwpodRuntimeSpecRecord {
+  if (row?.authority !== "runtime") throw codedError("invalid_hwpod_runtime_spec", `runtime HWPOD spec authority is invalid: ${String(row?.hwpod_id ?? "<unknown>")}`);
+  const document = normalizedDocument(row.document, `postgres:${String(row.hwpod_id ?? "")}`);
+  const hwpodId = specId(document);
+  if (hwpodId !== row.hwpod_id) throw codedError("invalid_hwpod_runtime_spec", `runtime HWPOD spec identity is invalid: ${String(row.hwpod_id ?? "<unknown>")}`);
+  return { authority: "runtime", hwpodId, createdAt: isoTimestamp(row.created_at), updatedAt: isoTimestamp(row.updated_at), document };
 }
 
 function parseBuiltIns(raw: string | undefined): BuiltInInput[] {
@@ -111,42 +186,18 @@ function normalizeBuiltIns(inputs: BuiltInInput[]) {
   return records;
 }
 
-async function readRuntimeRecords(runtimeDir: string) {
-  const records = new Map<string, RuntimeRecord>();
-  let entries: string[] = [];
-  try { entries = await readdir(runtimeDir); }
-  catch (error: any) { if (error?.code !== "ENOENT") throw error; }
-  for (const name of entries.filter((entry) => entry.endsWith(".json")).sort()) {
-    const file = path.join(runtimeDir, name);
-    let parsed: any;
-    try { parsed = JSON.parse(await readFile(file, "utf8")); }
-    catch (error: any) { throw codedError("invalid_hwpod_runtime_spec", `invalid runtime HWPOD spec record ${file}: ${error?.message ?? String(error)}`, { file }); }
-    const document = normalizedDocument(parsed?.document, file);
-    const hwpodId = specId(document);
-    if (parsed?.authority !== "runtime" || parsed?.hwpodId !== hwpodId) throw codedError("invalid_hwpod_runtime_spec", `runtime HWPOD spec record identity is invalid: ${file}`, { file, hwpodId });
-    if (records.has(hwpodId)) throw codedError("hwpod_spec_authority_conflict", `duplicate runtime HWPOD spec: ${hwpodId}`, { hwpodId });
-    records.set(hwpodId, { contractVersion: CONTRACT_VERSION, authority: "runtime", hwpodId, createdAt: String(parsed.createdAt ?? ""), updatedAt: String(parsed.updatedAt ?? ""), document });
-  }
-  return records;
-}
-
-async function writeRuntimeRecord(runtimeDir: string, record: RuntimeRecord) {
-  await mkdir(runtimeDir, { recursive: true });
-  const target = runtimeRecordPath(runtimeDir, record.hwpodId);
-  const temporary = `${target}.${randomUUID()}.tmp`;
-  await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, "utf8");
-  await rename(temporary, target);
-}
-
-function runtimeRecordPath(runtimeDir: string, hwpodId: string) { return path.join(runtimeDir, `${encodeURIComponent(validId(hwpodId))}.json`); }
+function requiredEnv(env: Record<string, string | undefined>, key: string) { const value = String(env[key] ?? "").trim(); if (!value) throw codedError("hwpod_spec_database_config_required", `${key} is required`); return value; }
+function postgresIdentifier(value: string, name: string) { if (!/^[a-z_][a-z0-9_]*$/u.test(value)) throw codedError("invalid_hwpod_spec_database_identifier", `${name} must be a lowercase PostgreSQL identifier`); return value; }
+function quoteIdentifier(value: string) { return `"${postgresIdentifier(value, "identifier")}"`; }
+function isoTimestamp(value: unknown) { const date = value instanceof Date ? value : new Date(String(value ?? "")); if (!Number.isFinite(date.getTime())) throw codedError("invalid_hwpod_runtime_spec", "runtime HWPOD spec timestamp is invalid"); return date.toISOString(); }
 function normalizedDocument(value: unknown, source: string) { return normalizeHwpodSpec(value, source); }
 function specId(document: any) { return validId(String(document?.metadata?.name ?? document?.metadata?.uid ?? "")); }
 function validId(value: string) { const id = String(value ?? "").trim(); if (!/^[A-Za-z0-9_.:-]{1,120}$/u.test(id)) throw codedError("invalid_hwpod_spec_id", `invalid HWPOD spec id: ${id || "<empty>"}`); return id; }
 function assertNotFrozen(id: string, builtIns: Map<string, any>) { const item = builtIns.get(id); if (item) throw codedError("hwpod_spec_frozen", `YAML-first built-in HWPOD spec is frozen: ${id}`, { hwpodId: id, authority: item.authority, configRef: item.configRef, mutable: false, frozen: true, documentFingerprint: documentFingerprint(item.document), mutation: false }); }
-function assertNoAuthorityConflicts(builtIns: Map<string, any>, runtime: Map<string, RuntimeRecord>) { for (const id of runtime.keys()) if (builtIns.has(id)) throw codedError("hwpod_spec_authority_conflict", `runtime HWPOD spec conflicts with YAML-first built-in spec: ${id}`, { hwpodId: id }); }
+function assertNoAuthorityConflicts(builtIns: Map<string, any>, runtime: Map<string, HwpodRuntimeSpecRecord>) { for (const id of runtime.keys()) if (builtIns.has(id)) throw codedError("hwpod_spec_authority_conflict", `runtime HWPOD spec conflicts with YAML-first built-in spec: ${id}`, { hwpodId: id }); }
 function summary(record: any) { const document = record.document; return { hwpodId: record.hwpodId, authority: record.authority, mutable: record.authority === "runtime", frozen: record.authority !== "runtime", documentFingerprint: documentFingerprint(document), ...(record.configRef ? { configRef: record.configRef, sourceFingerprint: record.sourceFingerprint } : { createdAt: record.createdAt, updatedAt: record.updatedAt }), nodeId: document.spec.nodeBinding.nodeId, workspacePath: document.spec.workspace.path }; }
 function entity(record: any) { return { ok: true, status: "completed", contractVersion: CONTRACT_VERSION, ...summary(record), document: record.document, valuesPrinted: false }; }
-function mutation(status: "created" | "updated", record: RuntimeRecord) { return { ...entity(record), status, mutation: true }; }
+function mutation(status: "created" | "updated", record: HwpodRuntimeSpecRecord) { return { ...entity(record), status, mutation: true }; }
 function documentFingerprint(document: unknown) { return `sha256:${createHash("sha256").update(stableJson(document)).digest("hex")}`; }
 function stableJson(value: unknown): string { if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`; if (value && typeof value === "object") return `{${Object.keys(value as any).sort().map((key) => `${JSON.stringify(key)}:${stableJson((value as any)[key])}`).join(",")}}`; return JSON.stringify(value) ?? "null"; }
 function codedError(code: string, message: string, details?: unknown) { return Object.assign(new Error(message), { code, details }); }

tools/hwlab-cli/hwpod.test.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 import { test } from "bun:test";
 
 import { runHwpodCli } from "../src/hwpod-harness-lib.ts";
+import { createHwpodSpecRegistry, type HwpodRuntimeSpecRecord, type HwpodRuntimeSpecStore } from "../../internal/hwpod/spec-registry.ts";
 
 test("hwpod-cli help exposes workspace cat and apply-patch stdin usage", async () => {
   const result = await runHwpodCli(["help"], { now: () => "2026-06-06T00:00:00.000Z" });
@@ -197,27 +198,27 @@ test("HWPOD operation status requires explicit over-api mode", async () => {
 
 test("HWPOD L0 CLI completes runtime spec CRUD and rejects built-in mutation", async () => {
   const root = await mkdtemp(path.join(os.tmpdir(), "hwpod-spec-cli-test-"));
-  const runtimeDir = path.join(root, "runtime");
   const createPath = path.join(root, "create.yaml");
   const updatePath = path.join(root, "update.yaml");
   const frozenPath = path.join(root, "frozen.yaml");
   const env = {
     HWPOD_BUILTIN_SPEC_DOCUMENTS_JSON: JSON.stringify([{ configRef: "config/hwpod.yaml#spec", document: hwpodSpecDocument("builtin-hwpod", "/builtin") }])
   };
+  const specRegistry = createHwpodSpecRegistry({ store: memoryStore(), builtIns: JSON.parse(env.HWPOD_BUILTIN_SPEC_DOCUMENTS_JSON) });
   try {
     await writeFile(createPath, hwpodSpecText("/runtime-v1", "", "runtime-hwpod"), "utf8");
     await writeFile(updatePath, hwpodSpecText("/runtime-v2", "", "runtime-hwpod"), "utf8");
     await writeFile(frozenPath, hwpodSpecText("/shadow", "", "builtin-hwpod"), "utf8");
 
-    assert.equal((await runHwpodCli(["spec", "create", "--file", createPath, "--local", "--runtime-spec-dir", runtimeDir], { env })).payload.body.status, "created");
-    const listed = await runHwpodCli(["spec", "list", "--local", "--runtime-spec-dir", runtimeDir], { env });
+    assert.equal((await runHwpodCli(["spec", "create", "--file", createPath, "--local"], { env, specRegistry })).payload.body.status, "created");
+    const listed = await runHwpodCli(["spec", "list", "--local"], { env, specRegistry });
     assert.equal(listed.exitCode, 0);
     assert.deepEqual(listed.payload.body.specs.map((item: any) => [item.hwpodId, item.authority]), [["builtin-hwpod", "yaml-first-builtin"], ["runtime-hwpod", "runtime"]]);
-    assert.equal((await runHwpodCli(["spec", "get", "runtime-hwpod", "--local", "--runtime-spec-dir", runtimeDir], { env })).payload.body.document.spec.workspace.path, "/runtime-v1");
-    assert.equal((await runHwpodCli(["spec", "update", "runtime-hwpod", "--file", updatePath, "--local", "--runtime-spec-dir", runtimeDir], { env })).payload.body.status, "updated");
-    assert.equal((await runHwpodCli(["spec", "delete", "runtime-hwpod", "--local", "--runtime-spec-dir", runtimeDir], { env })).payload.body.status, "deleted");
+    assert.equal((await runHwpodCli(["spec", "get", "runtime-hwpod", "--local"], { env, specRegistry })).payload.body.document.spec.workspace.path, "/runtime-v1");
+    assert.equal((await runHwpodCli(["spec", "update", "runtime-hwpod", "--file", updatePath, "--local"], { env, specRegistry })).payload.body.status, "updated");
+    assert.equal((await runHwpodCli(["spec", "delete", "runtime-hwpod", "--local"], { env, specRegistry })).payload.body.status, "deleted");
 
-    const frozen = await runHwpodCli(["spec", "create", "--file", frozenPath, "--local", "--runtime-spec-dir", runtimeDir], { env });
+    const frozen = await runHwpodCli(["spec", "create", "--file", frozenPath, "--local"], { env, specRegistry });
     assert.equal(frozen.exitCode, 1);
     assert.equal(frozen.payload.error.code, "hwpod_spec_frozen");
     assert.equal(frozen.payload.error.details.mutation, false);
@@ -231,3 +232,20 @@ function hwpodSpecText(workspacePath = "F:\\Work\\HWLAB-CASE-F103", buildCommand
 }
 
 function hwpodSpecDocument(name: string, workspacePath: string) { return { kind: "Hwpod", metadata: { name }, spec: { nodeBinding: { nodeId: "test-node" }, workspace: { path: workspacePath }, targetDevice: { board: "test" }, debugProbe: { type: "test" }, ioProbe: { type: "test" } } }; }
+
+function memoryStore(): HwpodRuntimeSpecStore {
+  const records = new Map<string, HwpodRuntimeSpecRecord>();
+  return {
+    list: async () => [...records.values()],
+    get: async (id) => records.get(id) ?? null,
+    create: async (record) => records.has(record.hwpodId) ? false : (records.set(record.hwpodId, structuredClone(record)), true),
+    update: async (id, document, updatedAt) => {
+      const existing = records.get(id);
+      if (!existing) return null;
+      const record = { ...existing, document: structuredClone(document), updatedAt };
+      records.set(id, record);
+      return record;
+    },
+    delete: async (id) => { const record = records.get(id) ?? null; records.delete(id); return record; },
+  };
+}

tools/src/hwpod-harness-lib.ts

@@ -104,7 +104,7 @@ export async function runHwpodCtl(argv: string[], options: { env?: EnvLike; fetc
   }
 }
 
-export async function runHwpodCli(argv: string[], options: { env?: EnvLike; fetchImpl?: FetchLike; stdinText?: string; now?: () => string } = {}) {
+export async function runHwpodCli(argv: string[], options: { env?: EnvLike; fetchImpl?: FetchLike; stdinText?: string; now?: () => string; specRegistry?: any } = {}) {
   const env = options.env ?? process.env;
   const now = options.now ?? (() => new Date().toISOString());
   try {
@@ -118,7 +118,7 @@ export async function runHwpodCli(argv: string[], options: { env?: EnvLike; fetc
         modes: ["l0-native-function", "l1-native-api"]
       });
     }
-    if (command === "spec") return await runHwpodSpecCrud({ parsed, env, fetchImpl: options.fetchImpl, now });
+    if (command === "spec") return await runHwpodSpecCrud({ parsed, env, fetchImpl: options.fetchImpl, now, specRegistry: options.specRegistry });
     if (command === "operation") {
       if (parsed._[1] !== "status") throw cliError("unsupported_operation_command", `unsupported hwpod operation command: ${parsed._[1] || ""}`);
       if (parsed.overApi !== true) throw cliError("hwpod_operation_status_over_api_required", "HWPOD operation status requires --over-api", { next: "pass --over-api" });
@@ -229,21 +229,24 @@ export async function readHwpodSpec(specPath = DEFAULT_HWPOD_SPEC_PATH) {
   return normalizeHwpodSpec(parseSimpleYaml(text, specPath), specPath);
 }
 
-async function runHwpodSpecCrud({ parsed, env, fetchImpl, now }: { parsed: ParsedArgs; env: EnvLike; fetchImpl?: FetchLike; now: () => string }) {
+async function runHwpodSpecCrud({ parsed, env, fetchImpl, now, specRegistry }: { parsed: ParsedArgs; env: EnvLike; fetchImpl?: FetchLike; now: () => string; specRegistry?: any }) {
   if (parsed.local !== true && parsed.overApi !== true) throw cliError("hwpod_spec_transport_required", "HWPOD spec CRUD requires --local or --over-api");
   const subcommand = text(parsed._[1]) || "list";
   if (!new Set(["list", "get", "create", "update", "delete"]).has(subcommand)) throw cliError("unsupported_spec_command", `unsupported hwpod spec command: ${subcommand}`);
   const hwpodId = subcommand === "get" || subcommand === "update" || subcommand === "delete" ? requiredText(parsed.hwpodId ?? parsed._[2], "hwpodId") : "";
   const document = subcommand === "create" || subcommand === "update" ? await readSpecMutationDocument(parsed) : undefined;
   if (parsed.local === true) {
-    const runtimeDir = requiredText(parsed.runtimeSpecDir ?? env.HWPOD_RUNTIME_SPEC_REGISTRY_DIR, "runtimeSpecDir");
-    const registry = hwpodSpecRegistryFromEnv(env, { runtimeDir });
-    const body = subcommand === "list" ? await registry.list()
-      : subcommand === "get" ? await registry.get(hwpodId)
-      : subcommand === "create" ? await registry.create(document)
-      : subcommand === "update" ? await registry.update(hwpodId, document)
-      : await registry.delete(hwpodId);
-    return result(0, ok("hwpod-cli.spec", { mode: "l0-native-function", transport: "native-function", serviceRuntime: false, subcommand, hwpodId: hwpodId || body.hwpodId || null, body }, body.status), now);
+    const registry = specRegistry ?? hwpodSpecRegistryFromEnv(env);
+    try {
+      const body = subcommand === "list" ? await registry.list()
+        : subcommand === "get" ? await registry.get(hwpodId)
+        : subcommand === "create" ? await registry.create(document)
+        : subcommand === "update" ? await registry.update(hwpodId, document)
+        : await registry.delete(hwpodId);
+      return result(0, ok("hwpod-cli.spec", { mode: "l0-native-function", transport: "native-function", serviceRuntime: false, repository: "host-postgresql", subcommand, hwpodId: hwpodId || body.hwpodId || null, body }, body.status), now);
+    } finally {
+      if (specRegistry === undefined) await registry.close?.();
+    }
   }
   const response = await requestHwpodSpecOverApi({ parsed, env, fetchImpl, subcommand, hwpodId, document });
   const exitCode = response.body?.ok === false || response.status >= 400 ? 1 : 0;
@@ -339,7 +342,7 @@ function cliHelp() {
       "hwlab-cli hwpod build --local --spec .hwlab/hwpod-spec.yaml",
       "hwlab-cli hwpod workspace ls . --hwpod-id d601-f103-v2 --over-api",
       "hwlab-cli hwpod operation status <operationId> --over-api",
-      "hwlab-cli hwpod spec list --local --runtime-spec-dir .state/hwpod-specs",
+      "hwlab-cli hwpod spec list --local",
       "hwlab-cli hwpod spec create --file hwpod-spec.yaml --over-api",
       "bun tools/hwpod-cli.ts workspace cat projects/01_baseline/User/main.c --hwpod-id d601-f103-v2 --workspace-path <run-worktree>",
       "bun tools/hwpod-cli.ts workspace read projects/01_baseline/User/main.c --hwpod-id d601-f103-v2 --workspace-path <run-worktree>",
@@ -398,14 +401,14 @@ function hwpodSpecHelp(subcommand = "") {
     command: "spec",
     subcommand: subcommand || null,
     usage: [
-      "hwpod spec list --local --runtime-spec-dir <dir>",
-      "hwpod spec get <hwpodId> --local --runtime-spec-dir <dir>",
-      "hwpod spec create --file <hwpod-spec.yaml> --local --runtime-spec-dir <dir>",
-      "hwpod spec update <hwpodId> --file <hwpod-spec.yaml> --local --runtime-spec-dir <dir>",
-      "hwpod spec delete <hwpodId> --local --runtime-spec-dir <dir>",
+      "hwpod spec list --local",
+      "hwpod spec get <hwpodId> --local",
+      "hwpod spec create --file <hwpod-spec.yaml> --local",
+      "hwpod spec update <hwpodId> --file <hwpod-spec.yaml> --local",
+      "hwpod spec delete <hwpodId> --local",
       "hwpod spec list|get|create|update|delete ... --over-api --api-base-url <native-api>"
     ],
-    boundary: "Runtime CRUD only mutates runtime specs. YAML-first built-in specs are frozen and return hwpod_spec_frozen for create, update, or delete.",
+    boundary: "Runtime CRUD only mutates host PostgreSQL runtime specs. YAML-first built-in specs are frozen and return hwpod_spec_frozen for create, update, or delete.",
     transports: { local: "L0 native function", overApi: "L1 native API" }
   });
 }