[Agent: Claude] feat(lws): .lwsowner sidecar primitives + ensureDeclaredType merge helper

charlesvardeman · claude · charlesvardeman · commit 626943b63df5 · 2026-07-22T13:42:57.000-04:00
- ownerStorePath/readOwners/writeOwners (URI-validated, dedup, ≥1)
- ensureDeclaredType: read-merge-write marker stamp for the boot backfill

Co-Authored-By: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/src/lws/type-metadata.js b/src/lws/type-metadata.js
@@ -50,6 +50,42 @@ export async function readDeclaredTypes(storage, storagePath) {
   catch { return []; }
 }
 
+// Merge one type into `.lwstypes` without clobbering what's there —
+// captureDeclaredTypes overwrites by design (provisioning), but the boot
+// backfill (governance round 2026-07-22) touches roots that may already
+// carry client-declared types. Returns true only when it wrote.
+export async function ensureDeclaredType(storage, storagePath, typeUri) {
+  const existing = await readDeclaredTypes(storage, storagePath);
+  if (existing.includes(typeUri)) return false;
+  await storage.write(typeStorePath(storagePath), Buffer.from(JSON.stringify([...existing, typeUri])));
+  return true;
+}
+
+// Per-storage owner record (governance round 2026-07-22): solid:owner URIs
+// for a storage root, System-Managed like `.lwstypes`. In-storage (not
+// config) because ownership travels with the data on re-homing; the
+// deployment operator (schema:provider) is config precisely because it
+// does not. Design: docs/superpowers/specs/2026-07-22-* in lws-pod.
+export function ownerStorePath(storagePath) {
+  return storagePath + '.lwsowner';
+}
+
+export async function readOwners(storage, storagePath) {
+  const p = ownerStorePath(storagePath);
+  if (!(await storage.exists(p))) return [];
+  const buf = await storage.read(p);
+  if (!buf) return [];
+  try { const arr = JSON.parse(buf.toString('utf8')); return Array.isArray(arr) ? arr.filter((o) => isAbsoluteUri(o)) : []; }
+  catch { return []; }
+}
+
+export async function writeOwners(storage, storagePath, ownerUris) {
+  const clean = [];
+  for (const o of (ownerUris || [])) if (isAbsoluteUri(o) && !clean.includes(o)) clean.push(o);
+  if (!clean.length) return;                                  // ≥1 owner or no record
+  await storage.write(ownerStorePath(storagePath), Buffer.from(JSON.stringify(clean)));
+}
+
 // Earned conformsTo provenance (System-Managed): which profile a member's
 // CONTAINER declared at the moment the member was admitted. Distinct from
 // the client-managed `.meta` dct:conformsTo (declared binding intent) — a
diff --git a/test/lwsowner-metadata.test.js b/test/lwsowner-metadata.test.js
@@ -0,0 +1,38 @@
+// test/lwsowner-metadata.test.js
+// Governance round (2026-07-22): .lwsowner sidecar primitives + the
+// read-merge-write marker helper the boot backfill depends on.
+import { describe, it, before } from 'node:test';
+import assert from 'node:assert/strict';
+import { startLwsPod } from './helpers.js';
+import * as storage from '../src/storage/filesystem.js';
+import {
+  ownerStorePath, readOwners, writeOwners, ensureDeclaredType,
+  readDeclaredTypes, typeStorePath, LWS_STORAGE,
+} from '../src/lws/type-metadata.js';
+
+describe('.lwsowner primitives + marker merge', () => {
+  let pod, root;
+  before(async (t) => { pod = await startLwsPod(t, 'govmeta'); root = `/${pod.podName}/`; });
+
+  it('writeOwners/readOwners round-trip, dedupe, URI-only', async () => {
+    await writeOwners(storage, root, [pod.webId, pod.webId, 'not a uri']);
+    assert.deepEqual(await readOwners(storage, root), [pod.webId]);
+    assert.equal(ownerStorePath(root), `${root}.lwsowner`);
+  });
+
+  it('readOwners returns [] for missing/corrupt sidecars', async () => {
+    assert.deepEqual(await readOwners(storage, '/nowhere/'), []);
+    await storage.write(ownerStorePath(root), Buffer.from('{corrupt'));
+    assert.deepEqual(await readOwners(storage, root), []);
+    await writeOwners(storage, root, [pod.webId]);            // restore
+  });
+
+  it('ensureDeclaredType merges, never overwrites, idempotent', async () => {
+    await storage.write(typeStorePath(root), Buffer.from(JSON.stringify(['https://example.org/Custom'])));
+    assert.equal(await ensureDeclaredType(storage, root, LWS_STORAGE), true);
+    const types = await readDeclaredTypes(storage, root);
+    assert.ok(types.includes('https://example.org/Custom'));   // merge, not overwrite
+    assert.ok(types.includes(LWS_STORAGE));
+    assert.equal(await ensureDeclaredType(storage, root, LWS_STORAGE), false);  // idempotent
+  });
+});
