@streetjs/storage 1.0.0

package/dist/tests/plugin.test.js

@@ -0,0 +1,112 @@
+// src/tests/plugin.test.js
+// Unit tests for StoragePlugin load/unload (task 23.2).
+//
+// These cover the two behaviors the task mandates:
+//
+//   1. After `onLoad`, the plugin exposes the live Storage facade through its
+//      `storage` accessor and that facade is usable (put/get round-trips)
+//      (Requirements 20.1, 20.3).
+//   2. After `onUnload`, resources are released: the `storage` accessor becomes
+//      `undefined`, the facade's `close()` is called (which stops the
+//      observability refresh timer), and any declarative `wireBridges` detach
+//      functions are invoked (Requirement 20.3).
+//
+// A minimal SandboxedApp-like stub is passed to the hooks — the plugin ignores
+// the app beyond the hook signatures, resolving its metrics/health registries
+// from the plugin options instead. Uses the Node.js built-in test runner
+// (node:test); executed via `node --test dist/tests/*.test.js`.
+//
+// Requirements: 20.1, 20.3
+import test from "node:test";
+import assert from "node:assert/strict";
+import { HealthCheckRegistry, MetricsRegistry } from "streetjs";
+import { StoragePlugin, STORAGE_HEALTH_CHECK_NAME, STORAGE_UPLOADS_METRIC, } from "../index.js";
+/** A minimal SandboxedApp-like stub: exposes only `use` / `on`. */
+function fakeApp() {
+    return { use() { }, on() { } };
+}
+test("onLoad exposes a usable Storage facade via the `storage` accessor (Req 20.1, 20.3)", async () => {
+    const plugin = new StoragePlugin({ provider: "memory" });
+    // No facade before load.
+    assert.equal(plugin.storage, undefined, "no facade before load");
+    await plugin.onLoad(fakeApp());
+    // The accessor now exposes the live facade.
+    assert.ok(plugin.storage, "facade exposed after load");
+    const storage = plugin.storage;
+    // The exposed facade is actually usable — a put/get round-trips.
+    const written = await storage.put("greeting.txt", "hello world");
+    assert.equal(written.key, "greeting.txt");
+    const read = await storage.get("greeting.txt");
+    assert.equal(read.found, true);
+    assert.equal(Buffer.from(read.bytes).toString("utf8"), "hello world");
+    await plugin.onUnload(fakeApp());
+});
+test("onUnload releases resources: accessor cleared, close() called, detachers invoked (Req 20.3)", async () => {
+    let attached = 0;
+    let detached = 0;
+    let bridgedStorage;
+    const plugin = new StoragePlugin({
+        provider: "memory",
+        wireBridges: [
+            (storage) => {
+                attached += 1;
+                bridgedStorage = storage;
+                // Returning a detach function that MUST be called on unload.
+                return () => {
+                    detached += 1;
+                };
+            },
+            () => {
+                attached += 1;
+                // A bridge that returns nothing is allowed (no detach registered).
+            },
+        ],
+    });
+    await plugin.onLoad(fakeApp());
+    assert.equal(attached, 2, "both wireBridges attach fns ran on load");
+    assert.equal(bridgedStorage, plugin.storage, "the attach fn received the live facade");
+    assert.equal(detached, 0, "detach not called before unload");
+    // Spy on the facade's close() so we can assert it is called on unload.
+    const facade = plugin.storage;
+    assert.ok(facade, "facade exposed after load");
+    let closeCalls = 0;
+    const originalClose = facade.close.bind(facade);
+    facade.close = async () => {
+        closeCalls += 1;
+        return originalClose();
+    };
+    await plugin.onUnload(fakeApp());
+    // The accessor is cleared, close() ran exactly once, and the returned detach
+    // function was invoked.
+    assert.equal(plugin.storage, undefined, "facade accessor cleared after unload");
+    assert.equal(closeCalls, 1, "facade close() called on unload");
+    assert.equal(detached, 1, "the returned detach function was called on unload");
+});
+test("observability from plugin-option registries loads and unloads cleanly (Req 20.3)", async () => {
+    const metrics = new MetricsRegistry();
+    const health = new HealthCheckRegistry();
+    const plugin = new StoragePlugin({ provider: "memory", metrics, health });
+    await plugin.onLoad(fakeApp());
+    // Observability wired from the plugin-option registries on load: the storage
+    // health check is registered and the storage metrics are present.
+    const live = await health.runLiveness();
+    assert.ok(STORAGE_HEALTH_CHECK_NAME in live.checks, "storage health check registered on load");
+    assert.equal(metrics.has(STORAGE_UPLOADS_METRIC), true, "storage metrics registered on load");
+    // Unload releases cleanly (stops the observability refresh timer) without throwing.
+    await assert.doesNotReject(() => plugin.onUnload(fakeApp()));
+    assert.equal(plugin.storage, undefined, "facade cleared after unload");
+});
+test("onLoad is idempotent — a second load reuses the same facade", async () => {
+    const plugin = new StoragePlugin({ provider: "memory" });
+    await plugin.onLoad(fakeApp());
+    const first = plugin.storage;
+    await plugin.onLoad(fakeApp());
+    assert.equal(plugin.storage, first, "facade identity unchanged on a second onLoad");
+    await plugin.onUnload(fakeApp());
+});
+test("onUnload is a no-op when never loaded", async () => {
+    const plugin = new StoragePlugin({ provider: "memory" });
+    await assert.doesNotReject(() => plugin.onUnload(fakeApp()));
+    assert.equal(plugin.storage, undefined);
+});
+//# sourceMappingURL=plugin.test.js.map

package/dist/tests/plugin.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.test.js","sourceRoot":"","sources":["../../src/tests/plugin.test.ts"],"names":[],"mappings":"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"}

package/dist/tests/prop-concurrent.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prop-concurrent.test.d.ts.map

package/dist/tests/prop-concurrent.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-concurrent.test.d.ts","sourceRoot":"","sources":["../../src/tests/prop-concurrent.test.ts"],"names":[],"mappings":""}

package/dist/tests/prop-concurrent.test.js

@@ -0,0 +1,59 @@
+// Property-based test for concurrent write isolation on the storage facade.
+//
+// Feature: unified-storage-framework, Property 17: Concurrent uploads never
+// corrupt data.
+//
+// For an arbitrary set of DISTINCT keys, each paired with its own byte content,
+// performing all `put` operations CONCURRENTLY (`Promise.all`) against a single
+// storage instance results in every key holding exactly its own content. No
+// key observes another key's bytes (no cross-contamination), and no bytes are
+// corrupted: reading each key back yields bytes exactly equal to the content
+// that was intended for that key.
+//
+// Uses the Node.js built-in test runner (node:test) and fast-check at
+// `{ numRuns: 100 }`, exercising the public facade via
+// `createStorage({ provider: 'memory' })` imported from the built package
+// entry point (`../index.js`), executed via `node --test dist/tests/*.test.js`.
+//
+// Validates: Requirements 26.6
+import test from "node:test";
+import assert from "node:assert/strict";
+import fc from "fast-check";
+import { createStorage } from "../index.js";
+/** A fixed clock so object timestamps are deterministic across runs. */
+const fixedClock = () => 1_700_000_000_000;
+/**
+ * An arbitrary set of distinct keys each mapped to its own byte content.
+ *
+ * `fc.uniqueArray` on non-empty keys guarantees the keys are DISTINCT, so each
+ * concurrent `put` targets a different object and the property genuinely tests
+ * cross-key isolation rather than last-writer-wins on a shared key. `minLength:
+ * 2` ensures there is always genuine concurrency to exercise.
+ */
+const distinctEntriesArb = fc
+    .uniqueArray(fc.string({ minLength: 1, maxLength: 40 }), {
+    minLength: 2,
+    maxLength: 25,
+})
+    .chain((keys) => fc.tuple(fc.constant(keys), fc.array(fc.uint8Array({ minLength: 0, maxLength: 256 }), {
+    minLength: keys.length,
+    maxLength: keys.length,
+})))
+    .map(([keys, contents]) => keys.map((key, index) => [key, contents[index]]));
+test("Feature: unified-storage-framework, Property 17: Concurrent uploads never corrupt data", async () => {
+    await fc.assert(fc.asyncProperty(distinctEntriesArb, async (entries) => {
+        // A single shared storage instance receives every concurrent write.
+        const storage = createStorage({ provider: "memory", clock: fixedClock });
+        // Fire all puts CONCURRENTLY against the one instance.
+        await Promise.all(entries.map(([key, content]) => storage.put(key, content)));
+        // Every key must hold exactly its own content — read them all back
+        // concurrently and assert byte-for-byte equality with the intended value.
+        await Promise.all(entries.map(async ([key, content]) => {
+            const result = await storage.get(key);
+            assert.equal(result.found, true, `key ${JSON.stringify(key)} must be present after concurrent writes`);
+            assert.deepEqual(result.bytes, content, `key ${JSON.stringify(key)} must hold exactly its own content (no cross-contamination)`);
+        }));
+        await storage.close();
+    }), { numRuns: 100 });
+});
+//# sourceMappingURL=prop-concurrent.test.js.map

package/dist/tests/prop-concurrent.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-concurrent.test.js","sourceRoot":"","sources":["../../src/tests/prop-concurrent.test.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,4EAA4E;AAC5E,gBAAgB;AAChB,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,kCAAkC;AAClC,EAAE;AACF,sEAAsE;AACtE,uDAAuD;AACvD,0EAA0E;AAC1E,gFAAgF;AAChF,EAAE;AACF,+BAA+B;AAE/B,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,wEAAwE;AACxE,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,iBAAiB,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,kBAAkB,GAAG,EAAE;KAC1B,WAAW,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,EAAE;IACvD,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,EAAE;CACd,CAAC;KACD,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CACd,EAAE,CAAC,KAAK,CACN,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EACjB,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE;IACxD,SAAS,EAAE,IAAI,CAAC,MAAM;IACtB,SAAS,EAAE,IAAI,CAAC,MAAM;CACvB,CAAC,CACH,CACF;KACA,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,CACxB,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAwB,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CACvE,CAAC;AAEJ,IAAI,CAAC,wFAAwF,EAAE,KAAK,IAAI,EAAE;IACxG,MAAM,EAAE,CAAC,MAAM,CACb,EAAE,CAAC,aAAa,CAAC,kBAAkB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACrD,oEAAoE;QACpE,MAAM,OAAO,GAAG,aAAa,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;QAEzE,uDAAuD;QACvD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QAE9E,mEAAmE;QACnE,0EAA0E;QAC1E,MAAM,OAAO,CAAC,GAAG,CACf,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE;YACnC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;YACvG,MAAM,CAAC,SAAS,CACd,MAAM,CAAC,KAAK,EACZ,OAAO,EACP,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,6DAA6D,CACxF,CAAC;QACJ,CAAC,CAAC,CACH,CAAC;QAEF,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC,CAAC,EACF,EAAE,OAAO,EAAE,GAAG,EAAE,CACjB,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/tests/prop-copy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prop-copy.test.d.ts.map

package/dist/tests/prop-copy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-copy.test.d.ts","sourceRoot":"","sources":["../../src/tests/prop-copy.test.ts"],"names":[],"mappings":""}

package/dist/tests/prop-copy.test.js

@@ -0,0 +1,63 @@
+// Property-based test for the storage facade `copy` operation.
+//
+// Feature: unified-storage-framework, Property 2: Copy is non-mutating and
+// duplicates content.
+//
+// For arbitrary, distinct source/destination keys and arbitrary content, after
+// `put(source, bytes)` followed by `copy(source, dest)`:
+//   - the source still returns the original bytes (unchanged),
+//   - the destination returns bytes equal to the source content, and
+//   - the copy result is `{ copied: true }`.
+// Additionally, copying a source key that was never written returns
+// `{ copied: false }` and creates nothing at the destination.
+//
+// Uses the Node.js built-in test runner (node:test) and fast-check at
+// `{ numRuns: 100 }`, exercising the public facade via
+// `createStorage({ provider: 'memory' })` imported from the built package
+// entry point (`../index.js`), executed via `node --test dist/tests/*.test.js`.
+//
+// Validates: Requirements 4.5, 26.3
+import test from "node:test";
+import assert from "node:assert/strict";
+import fc from "fast-check";
+import { createStorage } from "../index.js";
+/** A fixed clock so object timestamps are deterministic across runs. */
+const fixedClock = () => 1_700_000_000_000;
+/**
+ * Arbitrary object content: arbitrary byte arrays (including empty) mapped to a
+ * Uint8Array, which is what the facade/driver persists.
+ */
+const contentArb = fc.uint8Array({ minLength: 0, maxLength: 256 });
+/**
+ * Two distinct, non-empty object keys. Keys are constrained to non-empty
+ * strings and the pair is filtered so the source and destination never collide
+ * (a copy onto itself is a different scenario than "duplicate to a new key").
+ */
+const distinctKeysArb = fc
+    .tuple(fc.string({ minLength: 1, maxLength: 40 }), fc.string({ minLength: 1, maxLength: 40 }))
+    .filter(([source, dest]) => source !== dest);
+test("Feature: unified-storage-framework, Property 2: Copy is non-mutating and duplicates content", async () => {
+    await fc.assert(fc.asyncProperty(distinctKeysArb, contentArb, async ([source, dest], content) => {
+        // A fresh storage instance per case keeps runs independent.
+        const storage = createStorage({ provider: "memory", clock: fixedClock });
+        // ── Copy of a missing source: no-op that creates nothing ────────────────
+        const missing = await storage.copy(source, dest);
+        assert.equal(missing.copied, false, "copy of a missing source must report copied:false");
+        assert.equal(await storage.exists(source), false, "missing source must not be created by copy");
+        assert.equal(await storage.exists(dest), false, "destination must not be created when source is missing");
+        // ── Copy after a real write: duplicates content, source unchanged ───────
+        await storage.put(source, content);
+        const result = await storage.copy(source, dest);
+        assert.equal(result.copied, true, "copy of an existing source must report copied:true");
+        // Source still returns the original bytes (non-mutating).
+        const afterSource = await storage.get(source);
+        assert.equal(afterSource.found, true, "source must still exist after copy");
+        assert.deepEqual(afterSource.bytes, content, "source bytes must be unchanged after copy");
+        // Destination returns bytes equal to the source content (duplicated).
+        const afterDest = await storage.get(dest);
+        assert.equal(afterDest.found, true, "destination must exist after copy");
+        assert.deepEqual(afterDest.bytes, content, "destination bytes must equal the source content");
+        await storage.close();
+    }), { numRuns: 100 });
+});
+//# sourceMappingURL=prop-copy.test.js.map

package/dist/tests/prop-copy.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-copy.test.js","sourceRoot":"","sources":["../../src/tests/prop-copy.test.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,EAAE;AACF,2EAA2E;AAC3E,sBAAsB;AACtB,EAAE;AACF,+EAA+E;AAC/E,yDAAyD;AACzD,+DAA+D;AAC/D,qEAAqE;AACrE,6CAA6C;AAC7C,oEAAoE;AACpE,8DAA8D;AAC9D,EAAE;AACF,sEAAsE;AACtE,uDAAuD;AACvD,0EAA0E;AAC1E,gFAAgF;AAChF,EAAE;AACF,oCAAoC;AAEpC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,wEAAwE;AACxE,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,iBAAiB,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,GAAG,EAAE,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;AAEnE;;;;GAIG;AACH,MAAM,eAAe,GAAG,EAAE;KACvB,KAAK,CACJ,EAAE,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,EAC1C,EAAE,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAC3C;KACA,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC;AAE/C,IAAI,CAAC,6FAA6F,EAAE,KAAK,IAAI,EAAE;IAC7G,MAAM,EAAE,CAAC,MAAM,CACb,EAAE,CAAC,aAAa,CAAC,eAAe,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE;QAC9E,4DAA4D;QAC5D,MAAM,OAAO,GAAG,aAAa,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;QAEzE,2EAA2E;QAC3E,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACjD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,mDAAmD,CAAC,CAAC;QACzF,MAAM,CAAC,KAAK,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,4CAA4C,CAAC,CAAC;QAChG,MAAM,CAAC,KAAK,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,wDAAwD,CAAC,CAAC;QAE1G,2EAA2E;QAC3E,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAEnC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAChD,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,oDAAoD,CAAC,CAAC;QAExF,0DAA0D;QAC1D,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC9C,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,oCAAoC,CAAC,CAAC;QAC5E,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,2CAA2C,CAAC,CAAC;QAE1F,sEAAsE;QACtE,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,mCAAmC,CAAC,CAAC;QACzE,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,iDAAiD,CAAC,CAAC;QAE9F,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC,CAAC,EACF,EAAE,OAAO,EAAE,GAAG,EAAE,CACjB,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/tests/prop-delete.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prop-delete.test.d.ts.map

package/dist/tests/prop-delete.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-delete.test.d.ts","sourceRoot":"","sources":["../../src/tests/prop-delete.test.ts"],"names":[],"mappings":""}

package/dist/tests/prop-delete.test.js

@@ -0,0 +1,35 @@
+// Property-based test for the storage facade's delete semantics.
+//
+// Property 4: Delete removes visibility. For any stored object, after
+// `put(key, bytes)` then `delete(key)`, the object becomes invisible through
+// every read surface: `exists(key)` is false, `get(key)` reports not-found,
+// and `stat(key)` returns null.
+//
+// Backed by the zero-dependency in-memory provider via `createStorage({
+// provider: 'memory' })`, exercised across arbitrary keys and byte contents
+// with fast-check at { numRuns: 100 }. Executed via the Node.js built-in test
+// runner (`node --test dist/tests/*.test.js`).
+//
+// Feature: unified-storage-framework, Property 4
+// Validates: Requirements 4.4, 26.4
+import test from "node:test";
+import assert from "node:assert/strict";
+import fc from "fast-check";
+import { createStorage } from "../index.js";
+test("Feature: unified-storage-framework, Property 4 — delete removes visibility", async () => {
+    await fc.assert(fc.asyncProperty(
+    // Arbitrary non-empty keys and arbitrary byte contents.
+    fc.string({ minLength: 1 }), fc.uint8Array(), async (key, content) => {
+        const storage = createStorage({ provider: "memory" });
+        await storage.put(key, content);
+        await storage.delete(key);
+        // exists reports false after delete.
+        assert.equal(await storage.exists(key), false);
+        // get reports not-found (never throws).
+        const result = await storage.get(key);
+        assert.equal(result.found, false);
+        // stat returns null for the deleted key.
+        assert.equal(await storage.stat(key), null);
+    }), { numRuns: 100 });
+});
+//# sourceMappingURL=prop-delete.test.js.map

package/dist/tests/prop-delete.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-delete.test.js","sourceRoot":"","sources":["../../src/tests/prop-delete.test.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,sEAAsE;AACtE,6EAA6E;AAC7E,4EAA4E;AAC5E,gCAAgC;AAChC,EAAE;AACF,wEAAwE;AACxE,4EAA4E;AAC5E,8EAA8E;AAC9E,+CAA+C;AAC/C,EAAE;AACF,iDAAiD;AACjD,oCAAoC;AAEpC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,IAAI,CACF,4EAA4E,EAC5E,KAAK,IAAI,EAAE;IACT,MAAM,EAAE,CAAC,MAAM,CACb,EAAE,CAAC,aAAa;IACd,wDAAwD;IACxD,EAAE,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,EAC3B,EAAE,CAAC,UAAU,EAAE,EACf,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE;QACrB,MAAM,OAAO,GAAG,aAAa,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;QAEtD,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAE1B,qCAAqC;QACrC,MAAM,CAAC,KAAK,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QAE/C,wCAAwC;QACxC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAElC,yCAAyC;QACzC,MAAM,CAAC,KAAK,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;IAC9C,CAAC,CACF,EACD,EAAE,OAAO,EAAE,GAAG,EAAE,CACjB,CAAC;AACJ,CAAC,CACF,CAAC"}

package/dist/tests/prop-directory.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prop-directory.test.d.ts.map

package/dist/tests/prop-directory.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-directory.test.d.ts","sourceRoot":"","sources":["../../src/tests/prop-directory.test.ts"],"names":[],"mappings":""}

package/dist/tests/prop-directory.test.js

@@ -0,0 +1,118 @@
+// Property-based test for the storage Directory API over the flat key space.
+//
+// Feature: unified-storage-framework, Property 16 — Directory operations over a
+// flat key space. For an arbitrary set of `/`-delimited keys put into storage,
+// the directory operations are consistent over the flat key space:
+//
+//  - walk(prefix) returns exactly the keys beneath the prefix (Req 15.4).
+//  - listDirectory(prefix) returns exactly the immediate children (files plus
+//    collapsed sub-directory entries) with no duplicates and nothing outside
+//    the prefix (Req 15.2).
+//  - removeDirectory(prefix) removes exactly the keys beneath the prefix, and
+//    returns { removed: false } for an empty/missing prefix (Req 15.3, 15.6).
+//
+// Each observation is asserted against a computed expectation derived directly
+// from the generated key set.
+//
+// Uses the public facade via `createStorage({ provider: 'memory' })`, the
+// Node.js built-in test runner (node:test), and fast-check configured with
+// { numRuns: 100 }. Executed via `node --test dist/tests/*.test.js`.
+//
+// Validates: Requirements 15.2, 15.3, 15.4, 15.6
+import test from "node:test";
+import assert from "node:assert/strict";
+import fc from "fast-check";
+import { createStorage } from "../index.js";
+// Segments are drawn from a tiny alphabet so shared prefixes arise frequently,
+// exercising both matching and non-matching keys against a directory prefix.
+const segArb = fc.constantFrom("a", "b", "c");
+// A key is 1–3 `/`-delimited segments (no leading/trailing delimiter).
+const keyArb = fc
+    .array(segArb, { minLength: 1, maxLength: 3 })
+    .map((segments) => segments.join("/"));
+// A directory path is 0–2 segments; the empty path denotes the root.
+const dirArb = fc
+    .array(segArb, { minLength: 0, maxLength: 2 })
+    .map((segments) => segments.join("/"));
+/** Normalize a directory path the same way the Directory API does. */
+function toPrefix(path) {
+    return path === "" ? "" : path + "/";
+}
+/** Keys strictly beneath `prefix` in the flat key set (no markers here). */
+function expectedWalk(keys, prefix) {
+    return keys.filter((key) => key.startsWith(prefix) && key !== prefix);
+}
+/** Immediate children beneath `prefix`: file keys and collapsed sub-dir keys. */
+function expectedImmediate(keys, prefix) {
+    const entries = new Set();
+    for (const key of keys) {
+        if (!key.startsWith(prefix))
+            continue;
+        const remainder = key.slice(prefix.length);
+        if (remainder === "")
+            continue; // the directory marker itself, if any
+        const slash = remainder.indexOf("/");
+        if (slash === -1) {
+            entries.add(key); // immediate file child
+        }
+        else {
+            entries.add(prefix + remainder.slice(0, slash) + "/"); // sub-directory
+        }
+    }
+    return entries;
+}
+test("Feature: unified-storage-framework, Property 16 — directory operations are consistent over the flat key space", async () => {
+    await fc.assert(fc.asyncProperty(
+    // A set of unique keys, each paired with arbitrary string content.
+    fc.uniqueArray(fc.tuple(keyArb, fc.string()), {
+        selector: ([key]) => key,
+        minLength: 0,
+        maxLength: 15,
+    }), 
+    // An arbitrary directory path, possibly the root, possibly unrelated.
+    dirArb, async (entries, dirPath) => {
+        const storage = createStorage({ provider: "memory" });
+        const keys = entries.map(([key]) => key);
+        for (const [key, content] of entries) {
+            await storage.put(key, content, {});
+        }
+        const prefix = toPrefix(dirPath);
+        const under = expectedWalk(keys, prefix);
+        // --- walk: exactly the keys beneath the prefix (15.4) -------------
+        const walked = await storage.directory.walk(dirPath);
+        const walkedSet = new Set(walked);
+        assert.equal(walkedSet.size, walked.length, "walk returned duplicate keys");
+        assert.equal(walkedSet.size, under.length, "walk cardinality");
+        for (const key of under) {
+            assert.ok(walkedSet.has(key), `walk missing key: ${key}`);
+        }
+        for (const key of walked) {
+            assert.ok(key.startsWith(prefix), `walk leaked key outside prefix: ${key}`);
+        }
+        // --- listDirectory: exactly the immediate children (15.2) --------
+        const listing = await storage.directory.listDirectory(dirPath);
+        const listedKeys = listing.map((item) => item.key);
+        const listedSet = new Set(listedKeys);
+        assert.equal(listedSet.size, listedKeys.length, "listDirectory returned duplicate entries");
+        const expectedChildren = expectedImmediate(keys, prefix);
+        assert.equal(listedSet.size, expectedChildren.size, "listDirectory cardinality");
+        for (const key of expectedChildren) {
+            assert.ok(listedSet.has(key), `listDirectory missing child: ${key}`);
+        }
+        for (const key of listedKeys) {
+            assert.ok(key.startsWith(prefix) && key !== prefix, `listDirectory leaked entry outside prefix: ${key}`);
+        }
+        // --- removeDirectory: removes exactly the keys beneath (15.3/15.6)
+        const result = await storage.directory.removeDirectory(dirPath);
+        assert.deepEqual(result, { removed: under.length > 0 }, "removeDirectory removed flag");
+        // Nothing beneath the prefix survives; everything else is intact.
+        assert.deepEqual(await storage.directory.walk(dirPath), [], "removeDirectory left keys beneath the prefix");
+        const remaining = new Set(await storage.directory.walk(""));
+        const expectedRemaining = keys.filter((key) => !key.startsWith(prefix));
+        assert.equal(remaining.size, expectedRemaining.length);
+        for (const key of expectedRemaining) {
+            assert.ok(remaining.has(key), `removeDirectory wrongly removed sibling: ${key}`);
+        }
+    }), { numRuns: 100 });
+});
+//# sourceMappingURL=prop-directory.test.js.map

package/dist/tests/prop-directory.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-directory.test.js","sourceRoot":"","sources":["../../src/tests/prop-directory.test.ts"],"names":[],"mappings":"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"}

package/dist/tests/prop-driver-conformance.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prop-driver-conformance.test.d.ts.map

package/dist/tests/prop-driver-conformance.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-driver-conformance.test.d.ts","sourceRoot":"","sources":["../../src/tests/prop-driver-conformance.test.ts"],"names":[],"mappings":""}

package/dist/tests/prop-driver-conformance.test.js

@@ -0,0 +1,110 @@
+// Property-based test: every available driver conforms to the StorageDriver contract.
+//
+// Property 19: Every available (zero-dependency) driver conforms to the shared
+// StorageDriver contract. This reuses the parameterized contract-conformance
+// suite from `./contract.js` (task 27.1) — `runStorageDriverContract` and
+// `storageDriverContractChecks` — asserting the returned report passes for both
+// the Memory and Local drivers.
+//
+// Because the contract checks use fixed internal keys, this property ALSO folds
+// in a fast-check-generated round-trip assertion per driver over arbitrary
+// key+byte inputs (put→get equals, exists→true, delete→exists false,
+// get→found:false) so the property genuinely varies its inputs at
+// { numRuns: 100 }. A fresh driver is constructed per run; each Local driver is
+// rooted at a unique temp directory that is cleaned up after the run.
+//
+// Executed via the Node.js built-in test runner (`node --test dist/tests/*.test.js`).
+//
+// Feature: unified-storage-framework, Property 19
+// Validates: Requirements 2.1, 2.3, 2.4, 26.6
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import fc from "fast-check";
+import { runStorageDriverContract, storageDriverContractChecks, } from "./contract.js";
+import { MemoryStorageDriver } from "../drivers/memory.js";
+import { LocalStorageDriver } from "../drivers/local.js";
+/** A fixed clock for deterministic timestamps. */
+const fixedClock = () => 1_700_000_000_000;
+/** Temp roots allocated for Local drivers, cleaned up after the run. */
+const tempRoots = [];
+/** Factory: a fresh in-memory driver per call. */
+function makeMemoryDriver() {
+    return new MemoryStorageDriver({ clock: fixedClock });
+}
+/** Factory: a fresh filesystem driver rooted at a unique temp dir per call. */
+function makeLocalDriver() {
+    const root = mkdtempSync(join(tmpdir(), "streetjs-storage-conformance-"));
+    tempRoots.push(root);
+    return new LocalStorageDriver({ root, clock: fixedClock });
+}
+/** The available zero-dependency drivers under test. */
+const DRIVERS = [
+    { label: "memory", make: makeMemoryDriver },
+    { label: "local", make: makeLocalDriver },
+];
+/**
+ * A generator over the domain of *valid object keys*.
+ *
+ * A key is generated as one or more non-empty path segments joined by `/`,
+ * where each segment is drawn from a filesystem-safe character set and is never
+ * the reserved relative-path names `.` or `..`. This deliberately excludes keys
+ * that no real object store accepts as an object key and that the Local driver
+ * (which maps keys onto filesystem paths) cannot represent equivalently to the
+ * opaque-map Memory driver:
+ *   - the empty string and empty segments (e.g. `""`, `"a//b"`),
+ *   - a leading or trailing `/` (e.g. `"/a"`, `"a/"`),
+ *   - the relative segments `"."` / `".."` (path traversal),
+ *   - control characters such as NUL.
+ * Such inputs resolve to an existing/invalid filesystem path (EISDIR / ENOTDIR
+ * / ERR_INVALID_ARG_VALUE) on the Local driver while the Memory driver treats
+ * them as opaque map keys — an out-of-domain divergence, not a driver defect.
+ * This matches the valid-key domain the equivalence property (Property 18)
+ * already documents for its curated key pool.
+ */
+const KEY_SEGMENT_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.".split("");
+const segmentArb = fc
+    .array(fc.constantFrom(...KEY_SEGMENT_CHARS), { minLength: 1, maxLength: 12 })
+    .map((chars) => chars.join(""))
+    .filter((segment) => segment !== "." && segment !== "..");
+const keyArb = fc
+    .array(segmentArb, { minLength: 1, maxLength: 4 })
+    .map((segments) => segments.join("/"));
+test.after(() => {
+    for (const root of tempRoots) {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+test("Feature: unified-storage-framework, Property 19 — every driver conforms to the StorageDriver contract", async () => {
+    await fc.assert(fc.asyncProperty(
+    // A valid object key and arbitrary byte content drive an additional
+    // round-trip so inputs genuinely vary across runs. See `keyArb` for why
+    // the key domain excludes path-relative / empty-segment / control-char
+    // keys that the two drivers cannot represent equivalently.
+    keyArb, fc.uint8Array(), async (key, content) => {
+        for (const { label, make } of DRIVERS) {
+            // 1. The full contract-conformance suite must pass for the driver.
+            const report = await runStorageDriverContract(make);
+            assert.equal(report.passed, true, `${label} driver must conform to the contract, got: ${JSON.stringify(report.results)}`);
+            assert.equal(report.results.length, storageDriverContractChecks.length, `${label} driver must run every contract check`);
+            // 2. An input-varying round-trip on a fresh driver instance.
+            const driver = await make();
+            await driver.put(key, content, {});
+            // put→get returns the exact stored bytes.
+            const found = await driver.get(key);
+            assert.equal(found.found, true, `${label}: get must find the stored key`);
+            assert.ok(found.found === true, `${label}: result must be the found variant`);
+            assert.deepEqual(found.bytes, content, `${label}: get must return the exact stored bytes`);
+            // exists reports presence.
+            assert.equal(await driver.exists(key), true, `${label}: exists must be true after put`);
+            // delete removes visibility.
+            await driver.delete(key);
+            assert.equal(await driver.exists(key), false, `${label}: exists must be false after delete`);
+            const missing = await driver.get(key);
+            assert.equal(missing.found, false, `${label}: get must report not-found after delete`);
+        }
+    }), { numRuns: 100 });
+});
+//# sourceMappingURL=prop-driver-conformance.test.js.map

package/dist/tests/prop-driver-conformance.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-driver-conformance.test.js","sourceRoot":"","sources":["../../src/tests/prop-driver-conformance.test.ts"],"names":[],"mappings":"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"}

package/dist/tests/prop-driver-equivalence.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prop-driver-equivalence.test.d.ts.map

package/dist/tests/prop-driver-equivalence.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-driver-equivalence.test.d.ts","sourceRoot":"","sources":["../../src/tests/prop-driver-equivalence.test.ts"],"names":[],"mappings":""}