@adaas/a-frame 0.0.23 → 0.1.2

package/tests/integration/A-FrameStorage.integration.test.ts

@@ -0,0 +1,598 @@
+/**
+ * A-FrameStorage — storage correctness + stale-cache invalidation tests
+ *
+ * These tests verify that:
+ *  1. On the first run `concept.load()` embeds definitions by calling the
+ *     server and saves them to the local .aframe storage.
+ *  2. On subsequent runs with identical definitions the framework reads from
+ *     the local storage and makes NO server calls at all.
+ *  3. When a component's description (or source) changes, the framework
+ *     detects the hash mismatch, discards the cached embedding, and
+ *     re-embeds only the affected definition.
+ *  4. When nothing changes, the cached embedding is restored verbatim —
+ *     no embedding API call is made.
+ *
+ * Simulation strategy
+ * -------------------
+ * TypeScript decorators run at module-load time, so we cannot change a
+ * decorator's description mid-test.  Instead, after phase 1 we call
+ * `A_FrameIndex.addDefinition()` with the same `name` and `dependency`
+ * values but a different `description`.  Because `definitions.set(def.id, …)`
+ * uses the ASEID id as a key, this atomically replaces the v1 entry with v2
+ * — identical to what happens in production when a developer edits the
+ * description string and restarts the application.
+ */
+
+import { A_Component, A_Concept, A_Container, A_Context, A_Error } from '@adaas/a-concept';
+import { A_Frame, A_FrameTargetType } from '@adaas/a-frame/core';
+import { A_FrameIndex } from '@adaas/a-frame/index';
+import { A_FrameDefinition } from '@adaas/a-frame/definition';
+import { A_FrameNamespace } from '@adaas/a-frame/namespace';
+import { A_FrameChannel } from '@adaas/a-frame/channel';
+import { config } from 'dotenv';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+config();
+
+// Each phase involves a full network round-trip for embedding.
+jest.setTimeout(120_000);
+
+
+// ─── Test-only component classes ──────────────────────────────────────────────
+//
+// StaleTestComp is the component whose description will "change" between phases.
+// StableTestComp never changes — it verifies the framework does NOT re-embed
+// a definition whose hash is still correct.
+
+@A_Frame.Define({
+    description: 'StaleTestComp v1 — original description before the developer made a change',
+})
+class StaleTestComp extends A_Component { }
+
+@A_Frame.Define({
+    description: 'StableTestComp — this description is intentionally never modified',
+})
+class StableTestComp extends A_Component { }
+
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function buildMinimalConcept() {
+    const concept = new A_Concept({
+        name: 'StaleTestConcept',
+        components: [A_Frame],
+        containers: [
+            new A_Container({
+                name: 'StaleTestContainer',
+                components: [StaleTestComp, StableTestComp],
+            }),
+        ],
+    });
+    await concept.load();
+    return concept;
+}
+
+
+// ─── Suite ────────────────────────────────────────────────────────────────────
+
+describe('A-Frame Storage Tests', () => {
+
+    // ── Integration: stale cache invalidation ─────────────────────────────
+    //
+    // Verifies that:
+    //  1. concept.load() embeds definitions on the first run and saves them.
+    //  2. A changed description causes only the affected definition to be
+    //     re-embedded (hash mismatch detected by the storage layer).
+    //  3. Unchanged definitions are restored verbatim from the cache
+    //     (bit-for-bit equal vectors, no embedding API call made).
+
+    describe('Integration — stale cache invalidation', () => {
+
+    let tempStorageDir: string;
+
+    beforeAll(() => {
+        // Enable sync so concept.load() runs the embed-and-save pipeline
+        process.env.A_FRAME_SYNC = 'true';
+
+        // Dedicated temp dir — keeps this suite completely isolated from the
+        // main .aframe cache used by other tests
+        tempStorageDir = fs.mkdtempSync(path.join(os.tmpdir(), 'aframe-stale-'));
+        process.env.A_FRAME_STORAGE_DIR = tempStorageDir;
+    });
+
+    afterAll(() => {
+        process.env.A_FRAME_SYNC = 'false';
+        delete process.env.A_FRAME_STORAGE_DIR;
+
+        // Remove StaleTestComp and StableTestComp from the global singleton
+        // index so they don't interfere with other test suites in watch mode
+        const stale = A_FrameIndex.getDefinition('StaleTestComp');
+        if (stale) A_FrameIndex.removeDefinition(stale);
+        const stable = A_FrameIndex.getDefinition('StableTestComp');
+        if (stable) A_FrameIndex.removeDefinition(stable);
+
+        try { fs.rmSync(tempStorageDir, { recursive: true, force: true }); } catch { /* no-op */ }
+    });
+
+
+    // ── Test 1: stale-hash scenario ──────────────────────────────────────────
+
+    it('re-embeds when description changes; serves unchanged definitions from cache', async () => {
+        try {
+
+            // ── Phase 1 ─ first startup: both definitions are embedded and saved ─
+            // A_Context.reset() is called by jest.setup.ts beforeEach,
+            // so we start with a clean root scope here.
+            let concept = await buildMinimalConcept();
+            let idx = concept.scope.resolve(A_FrameIndex)!;
+
+            const def1Stale = idx.getDefinition('StaleTestComp')!;
+            const def1Stable = idx.getDefinition('StableTestComp')!;
+
+            expect(def1Stale).toBeDefined();
+            expect(def1Stable).toBeDefined();
+            expect(def1Stale.isEmbed).toBe(true);
+            expect(def1Stable.isEmbed).toBe(true);
+
+            const hashV1 = def1Stale.hash;
+            const staleVecV1 = Array.from(def1Stale.vector!.values);
+            const stableVecV1 = Array.from(def1Stable.vector!.values);
+
+            console.log(`\n  [phase 1] StaleTestComp hash=${hashV1} dims=${def1Stale.vector!.dimensions}`);
+            console.log(`  [phase 1] StableTestComp hash=${def1Stable.hash} dims=${def1Stable.vector!.dimensions}`);
+
+
+            // ── Phase 2 ─ description changes → cache miss → re-embed ──────────
+            //
+            // Replace the v1 definition in the global index with a v2 that has
+            // an updated description.  Uses the SAME name + dependency so the
+            // computed ASEID id is identical; only the hash differs (because the
+            // hash includes the description string).
+            A_Context.reset();
+
+            // Must deregister v1 from the index scope before registering v2
+            // (same ASEID id → scope.register would throw "already registered")
+            const existingV1 = A_FrameIndex.getDefinition('StaleTestComp');
+            if (existingV1) A_FrameIndex.removeDefinition(existingV1);
+
+            A_FrameIndex.addDefinition(new A_FrameDefinition({
+                name: 'StaleTestComp',
+                dependency: 'StaleTestComp',
+                description: 'StaleTestComp v2 — description updated to reflect new behaviour',
+                source: 'class StaleTestComp extends A_Component {}',
+                type: A_FrameTargetType.COMPONENT,
+                namespace: A_FrameIndex.getDefaultNamespace(),
+            }));
+
+            concept = await buildMinimalConcept();
+            idx = concept.scope.resolve(A_FrameIndex)!;
+
+            const def2Stale = idx.getDefinition('StaleTestComp')!;
+            const def2Stable = idx.getDefinition('StableTestComp')!;
+
+            expect(def2Stale.isEmbed).toBe(true);
+            expect(def2Stable.isEmbed).toBe(true);
+
+            const hashV2 = def2Stale.hash;
+            expect(hashV2).not.toBe(hashV1);  // description changed → hash changed
+            const staleVecV2 = Array.from(def2Stale.vector!.values);
+
+            // StableTestComp was NOT changed — its cached vector must be
+            // bit-for-bit identical to phase 1 (restored from disk, no API call)
+            expect(Array.from(def2Stable.vector!.values)).toEqual(stableVecV1);
+
+            console.log(`\n  [phase 2] StaleTestComp STALE hash=${hashV1} → fresh hash=${hashV2} (re-embedded)`);
+            console.log(`  [phase 2] StableTestComp vector unchanged: ${Array.from(def2Stable.vector!.values).slice(0, 4).map(v => v.toFixed(4)).join(', ')}…`);
+
+
+            // ── Phase 3 ─ same v2 description → cache hit → identical vector ───
+            //
+            // Nothing changed since phase 2.  The framework should load the v2
+            // embedding from disk without making any embedding API call.
+            // Proof: the Float32Array is bit-for-bit identical (binary
+            // serialisation is lossless; two separate API calls would not produce
+            // the same exact float values).
+            A_Context.reset();
+
+            // Deregister v2 before re-adding it (same ASEID id survives the
+            // context reset in the persistent singleton scope)
+            const existingV2 = A_FrameIndex.getDefinition('StaleTestComp');
+            if (existingV2) A_FrameIndex.removeDefinition(existingV2);
+
+            // Re-add v2 to verify it is served from cache in this phase
+            A_FrameIndex.addDefinition(new A_FrameDefinition({
+                name: 'StaleTestComp',
+                dependency: 'StaleTestComp',
+                description: 'StaleTestComp v2 — description updated to reflect new behaviour',
+                source: 'class StaleTestComp extends A_Component {}',
+                type: A_FrameTargetType.COMPONENT,
+                namespace: A_FrameIndex.getDefaultNamespace(),
+            }));
+
+            concept = await buildMinimalConcept();
+            idx = concept.scope.resolve(A_FrameIndex)!;
+
+            const def3Stale = idx.getDefinition('StaleTestComp')!;
+            const def3Stable = idx.getDefinition('StableTestComp')!;
+
+            expect(def3Stale.isEmbed).toBe(true);
+            expect(def3Stable.isEmbed).toBe(true);
+
+            // Both vectors must be identical to phase 2 — loaded from cache
+            expect(Array.from(def3Stale.vector!.values)).toEqual(staleVecV2);
+            expect(Array.from(def3Stable.vector!.values)).toEqual(stableVecV1);
+
+            console.log(`\n  [phase 3] StaleTestComp vector from cache: ${staleVecV2.slice(0, 4).map(v => v.toFixed(4)).join(', ')}…`);
+            console.log(`  [phase 3] StableTestComp vector from cache: ${stableVecV1.slice(0, 4).map(v => v.toFixed(4)).join(', ')}…`);
+
+        } catch (error) {
+            if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+            else console.error('Unexpected error:', error);
+            throw error;
+        }
+    }, 120_000);
+
+    }); // describe('Integration — stale cache invalidation')
+
+
+    // ── Integration: custom namespace + custom storage path ───────────────
+    //
+    // Verifies the complete first-run / second-run storage contract:
+    //
+    //  Run 1 — storage is empty → the server is called for every definition →
+    //           results are saved to the custom storage directory.
+    //
+    //  Run 2 — storage is populated and hashes match → the server is NOT
+    //           called at all → vectors are bit-for-bit identical to run 1.
+    //
+    // The spy on `A_FrameChannel.prototype.embedDefinition` is the explicit
+    // proof that no network round-trip occurred in run 2.
+
+    describe('Integration — custom namespace, custom storage path', () => {
+
+        const CUSTOM_NS_NAME = 'storage-test-ns';
+
+        // These two definitions live in the custom namespace created below.
+        // They are added to A_FrameIndex manually (same pattern as the stale-
+        // cache suite) so that the test is fully self-contained and does not
+        // depend on globally-registered @A_Frame.Define decorators.
+        const DEF_A_NAME = 'StorageTestCompA';
+        const DEF_B_NAME = 'StorageTestCompB';
+
+        let tempStorageDir: string;
+        let customNamespace: A_FrameNamespace;
+
+        // ── Helpers ─────────────────────────────────────────────────────────
+
+        function makeDefinition(name: string): A_FrameDefinition {
+            return new A_FrameDefinition({
+                name,
+                dependency: name,
+                description: `${name} — definition for storage integration test`,
+                source: `class ${name} extends A_Component {}`,
+                type: A_FrameTargetType.COMPONENT,
+                namespace: customNamespace,
+            });
+        }
+
+        async function buildConcept(): Promise<A_Concept> {
+            const concept = new A_Concept({
+                name: 'StorageTestConcept',
+                components: [A_Frame],
+                containers: [
+                    new A_Container({
+                        name: 'StorageTestContainer',
+                        components: [],
+                    }),
+                ],
+            });
+            await concept.load();
+            return concept;
+        }
+
+        // ── Setup / teardown ─────────────────────────────────────────────────
+
+        beforeAll(() => {
+            process.env.A_FRAME_SYNC = 'true';
+
+            // Custom isolated storage directory
+            tempStorageDir = fs.mkdtempSync(
+                path.join(os.tmpdir(), 'aframe-custom-ns-')
+            );
+            process.env.A_FRAME_STORAGE_DIR = tempStorageDir;
+
+            // Custom namespace — scoped to this test block
+            customNamespace = new A_FrameNamespace({
+                name: CUSTOM_NS_NAME,
+                description: 'Namespace used exclusively by the storage integration test',
+            });
+        });
+
+        afterAll(() => {
+            process.env.A_FRAME_SYNC = 'false';
+            delete process.env.A_FRAME_STORAGE_DIR;
+
+            // Clean up definitions from the global singleton index
+            for (const name of [DEF_A_NAME, DEF_B_NAME]) {
+                const def = A_FrameIndex.getDefinition(name);
+                if (def) A_FrameIndex.removeDefinition(def);
+            }
+
+            try { fs.rmSync(tempStorageDir, { recursive: true, force: true }); } catch { /* no-op */ }
+        });
+
+        // ── Test ─────────────────────────────────────────────────────────────
+
+        it('run 1 calls server and persists; run 2 reads from storage without calling server', async () => {
+            try {
+
+                // ── Setup: register definitions under the custom namespace ────
+                A_FrameIndex.addDefinition(makeDefinition(DEF_A_NAME));
+                A_FrameIndex.addDefinition(makeDefinition(DEF_B_NAME));
+
+                // ── Run 1: empty storage → server MUST be called ─────────────
+
+                const embedSpy = jest
+                    .spyOn(A_FrameChannel.prototype, 'embedDefinition')
+                    .mockResolvedValue(undefined as any);  // handled by parent class
+
+                // We want real embedding here, so restore the original method
+                // immediately and track calls via a wrapping spy instead.
+                embedSpy.mockRestore();
+
+                // Real spy — does not change behaviour, only records calls
+                const serverCallSpy = jest.spyOn(
+                    A_FrameChannel.prototype as any,
+                    'embedDefinition',
+                );
+
+                let concept = await buildConcept();
+                let idx = concept.scope.resolve(A_FrameIndex)!;
+
+                const defA_run1 = idx.getDefinition(DEF_A_NAME)!;
+                const defB_run1 = idx.getDefinition(DEF_B_NAME)!;
+
+                expect(defA_run1).toBeDefined();
+                expect(defB_run1).toBeDefined();
+                expect(defA_run1.isEmbed).toBe(true);
+                expect(defB_run1.isEmbed).toBe(true);
+
+                // Server must have been called for each definition in run 1
+                expect(serverCallSpy).toHaveBeenCalled();
+                const run1CallCount = serverCallSpy.mock.calls.length;
+                expect(run1CallCount).toBeGreaterThanOrEqual(2);
+
+                const vecA_run1 = Array.from(defA_run1.vector!.values);
+                const vecB_run1 = Array.from(defB_run1.vector!.values);
+
+                console.log(
+                    `\n  [run 1] ${DEF_A_NAME} dims=${defA_run1.vector!.dimensions}  server calls=${run1CallCount}`
+                );
+
+                // Verify the storage directory was created and contains files
+                const storedFiles = fs.readdirSync(tempStorageDir);
+                expect(storedFiles.length).toBeGreaterThan(0);
+                console.log(`  [run 1] storage files: ${storedFiles.join(', ')}`);
+
+                serverCallSpy.mockRestore();
+
+
+                // ── Run 2: populated storage, same definitions → NO server calls ─
+
+                A_Context.reset();
+
+                // Re-register the definitions (context reset clears scope, but
+                // A_FrameIndex singleton persists — definitions are still there)
+                const defAAfterReset = A_FrameIndex.getDefinition(DEF_A_NAME);
+                const defBAfterReset = A_FrameIndex.getDefinition(DEF_B_NAME);
+
+                // If context reset cleared them, re-add with identical content
+                if (!defAAfterReset) A_FrameIndex.addDefinition(makeDefinition(DEF_A_NAME));
+                if (!defBAfterReset) A_FrameIndex.addDefinition(makeDefinition(DEF_B_NAME));
+
+                // Spy BEFORE the second concept.load() — must not be called
+                const noServerSpy = jest.spyOn(
+                    A_FrameChannel.prototype as any,
+                    'embedDefinition',
+                );
+
+                concept = await buildConcept();
+                idx = concept.scope.resolve(A_FrameIndex)!;
+
+                const defA_run2 = idx.getDefinition(DEF_A_NAME)!;
+                const defB_run2 = idx.getDefinition(DEF_B_NAME)!;
+
+                expect(defA_run2).toBeDefined();
+                expect(defB_run2).toBeDefined();
+                expect(defA_run2.isEmbed).toBe(true);
+                expect(defB_run2.isEmbed).toBe(true);
+
+                // ─ Key assertion: server was NOT called in run 2 ─
+                expect(noServerSpy).not.toHaveBeenCalled();
+
+                // ─ Vectors must be bit-for-bit identical (loaded from disk) ─
+                expect(Array.from(defA_run2.vector!.values)).toEqual(vecA_run1);
+                expect(Array.from(defB_run2.vector!.values)).toEqual(vecB_run1);
+
+                console.log(`\n  [run 2] server spy call count: ${noServerSpy.mock.calls.length} (expected 0)`);
+                console.log(`  [run 2] ${DEF_A_NAME} vector from storage: ${vecA_run1.slice(0, 4).map(v => v.toFixed(4)).join(', ')}…`);
+                console.log(`  [run 2] ${DEF_B_NAME} vector from storage: ${vecB_run1.slice(0, 4).map(v => v.toFixed(4)).join(', ')}…`);
+
+                noServerSpy.mockRestore();
+
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        }, 120_000);
+
+    }); // describe('Integration — custom namespace, custom storage path')
+
+
+    // ── Integration: A_FRAME_STORAGE_PATTERN — extra-directory discovery ──────
+    //
+    // Verifies the pattern-based read-only merge from secondary storage directories:
+    //
+    //  Step 1 — a "publisher" concept embeds definitions and saves them to a
+    //           dedicated publisher storage directory.
+    //
+    //  Step 2 — a "consumer" concept starts with a completely empty primary
+    //           storage directory.  `A_FRAME_STORAGE_PATTERN` is set so the
+    //           framework discovers the publisher directory via glob.
+    //           The consumer must load definitions from the pattern-matched
+    //           directory WITHOUT making any embedding server calls, and the
+    //           resulting vectors must be bit-for-bit identical to step 1.
+    //
+    // This simulates the real-world scenario where definitions are pre-embedded
+    // inside an npm package (shipped as `.aframe/`) and consumed by an
+    // application that does not call the embedding server at all.
+
+    describe('Integration — A_FRAME_STORAGE_PATTERN extra-directory discovery', () => {
+
+        const PATTERN_NS_NAME = 'pattern-test-ns';
+        const DEF_P_NAME = 'PatternTestCompA';
+        const DEF_Q_NAME = 'PatternTestCompB';
+
+        let publisherDir: string;   // simulates the npm package's .aframe
+        let consumerDir: string;    // consumer's own (initially empty) storage
+        let patternNs: A_FrameNamespace;
+
+        function makePatternDefinition(name: string): A_FrameDefinition {
+            return new A_FrameDefinition({
+                name,
+                dependency: name,
+                description: `${name} — definition for A_FRAME_STORAGE_PATTERN integration test`,
+                source: `class ${name} extends A_Component {}`,
+                type: A_FrameTargetType.COMPONENT,
+                namespace: patternNs,
+            });
+        }
+
+        async function buildPatternConcept(): Promise<A_Concept> {
+            const concept = new A_Concept({
+                name: 'PatternTestConcept',
+                components: [A_Frame],
+                containers: [
+                    new A_Container({
+                        name: 'PatternTestContainer',
+                        components: [],
+                    }),
+                ],
+            });
+            await concept.load();
+            return concept;
+        }
+
+        beforeAll(() => {
+            process.env.A_FRAME_SYNC = 'true';
+
+            publisherDir = fs.mkdtempSync(path.join(os.tmpdir(), 'aframe-publisher-'));
+            consumerDir  = fs.mkdtempSync(path.join(os.tmpdir(), 'aframe-consumer-'));
+
+            patternNs = new A_FrameNamespace({
+                name: PATTERN_NS_NAME,
+                description: 'Namespace used exclusively by the A_FRAME_STORAGE_PATTERN integration test',
+            });
+        });
+
+        afterAll(() => {
+            process.env.A_FRAME_SYNC = 'false';
+            delete process.env.A_FRAME_STORAGE_DIR;
+            delete process.env.A_FRAME_STORAGE_PATTERN;
+
+            for (const name of [DEF_P_NAME, DEF_Q_NAME]) {
+                const def = A_FrameIndex.getDefinition(name);
+                if (def) A_FrameIndex.removeDefinition(def);
+            }
+
+            try { fs.rmSync(publisherDir, { recursive: true, force: true }); } catch { /* no-op */ }
+            try { fs.rmSync(consumerDir,  { recursive: true, force: true }); } catch { /* no-op */ }
+        });
+
+        it('consumer reads definitions from pattern-matched publisher dir without calling the server', async () => {
+            try {
+
+                // ── Step 1: publisher embeds and saves to publisherDir ────────────
+
+                A_FrameIndex.addDefinition(makePatternDefinition(DEF_P_NAME));
+                A_FrameIndex.addDefinition(makePatternDefinition(DEF_Q_NAME));
+
+                process.env.A_FRAME_STORAGE_DIR = publisherDir;
+                delete process.env.A_FRAME_STORAGE_PATTERN;
+
+                let concept = await buildPatternConcept();
+                let idx = concept.scope.resolve(A_FrameIndex)!;
+
+                const defP_pub = idx.getDefinition(DEF_P_NAME)!;
+                const defQ_pub = idx.getDefinition(DEF_Q_NAME)!;
+
+                expect(defP_pub).toBeDefined();
+                expect(defQ_pub).toBeDefined();
+                expect(defP_pub.isEmbed).toBe(true);
+                expect(defQ_pub.isEmbed).toBe(true);
+
+                const vecP_pub = Array.from(defP_pub.vector!.values);
+                const vecQ_pub = Array.from(defQ_pub.vector!.values);
+
+                const publisherFiles = fs.readdirSync(publisherDir);
+                expect(publisherFiles.length).toBeGreaterThan(0);
+                console.log(`\n  [publisher] storage files: ${publisherFiles.join(', ')}`);
+
+                // ── Step 2: consumer starts with empty dir, pattern points to publisher ─
+
+                A_Context.reset();
+
+                // Re-register definitions (context reset drops scoped registrations)
+                const pAfterReset = A_FrameIndex.getDefinition(DEF_P_NAME);
+                const qAfterReset = A_FrameIndex.getDefinition(DEF_Q_NAME);
+                if (!pAfterReset) A_FrameIndex.addDefinition(makePatternDefinition(DEF_P_NAME));
+                if (!qAfterReset) A_FrameIndex.addDefinition(makePatternDefinition(DEF_Q_NAME));
+
+                // Consumer uses a separate, initially-empty storage dir.
+                // The pattern is set to the exact publisher dir path so the glob matches it.
+                process.env.A_FRAME_STORAGE_DIR = consumerDir;
+                process.env.A_FRAME_STORAGE_PATTERN = publisherDir;
+
+                // Spy BEFORE load — must not be called if storage pattern works
+                const noServerSpy = jest.spyOn(
+                    A_FrameChannel.prototype as any,
+                    'embedDefinition',
+                );
+
+                concept = await buildPatternConcept();
+                idx = concept.scope.resolve(A_FrameIndex)!;
+
+                const defP_con = idx.getDefinition(DEF_P_NAME)!;
+                const defQ_con = idx.getDefinition(DEF_Q_NAME)!;
+
+                expect(defP_con).toBeDefined();
+                expect(defQ_con).toBeDefined();
+                expect(defP_con.isEmbed).toBe(true);
+                expect(defQ_con.isEmbed).toBe(true);
+
+                // ─ Key assertion: no server call was made ─
+                expect(noServerSpy).not.toHaveBeenCalled();
+
+                // ─ Vectors must be bit-for-bit identical to the publisher run ─
+                expect(Array.from(defP_con.vector!.values)).toEqual(vecP_pub);
+                expect(Array.from(defQ_con.vector!.values)).toEqual(vecQ_pub);
+
+                console.log(`  [consumer] server spy call count: ${noServerSpy.mock.calls.length} (expected 0)`);
+                console.log(`  [consumer] ${DEF_P_NAME} vector matches publisher: ✓`);
+                console.log(`  [consumer] ${DEF_Q_NAME} vector matches publisher: ✓`);
+
+                noServerSpy.mockRestore();
+
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        }, 120_000);
+
+    }); // describe('Integration — A_FRAME_STORAGE_PATTERN extra-directory discovery')
+
+}); // describe('A-Frame Storage Tests')

package/tests/jest.setup.browser.ts

@@ -9,7 +9,7 @@ config();
 (window as any).A_FRAME_SERVER_URL = process.env.A_FRAME_SERVER_URL ?? 'http://localhost:3000';
 (window as any).A_FRAME_SERVER_API_KEY = process.env.A_FRAME_SERVER_API_KEY ?? '';
 (window as any).A_FRAME_TOKEN = process.env.A_FRAME_TOKEN ?? '';
-(window as any).A_FRAME_STORAGE_DIR = process.env.A_FRAME_STORAGE_DIR ?? '.aframestr';
+(window as any).A_FRAME_STORAGE_DIR = process.env.A_FRAME_STORAGE_DIR ?? '.aframe';
 
 /**
  * Browser environment test hooks

package/tests/jest.setup.ts

@@ -1,6 +1,10 @@
 import { A_Context } from '@adaas/a-concept';
 import fs from 'fs';
 
+// Disable automatic sync/embedding during tests to prevent slow Ollama calls
+// on every concept.load(). Tests that need embedding call .embed() explicitly.
+process.env.A_FRAME_SYNC = 'false';
+
 /**
  * Base hooks for tests
  */

package/tests/jest.setup.unit.ts

@@ -0,0 +1,30 @@
+import { A_Context } from '@adaas/a-concept';
+import fs from 'fs';
+
+// Use a temp (empty) storage dir so that def.load() / ns.load() always
+// find no cached files and return immediately — preventing hangs that would
+// occur if integration-test .aframe files on disk were decrypted with the
+// wrong (mock) encryption key.
+process.env.A_FRAME_STORAGE_DIR = '/tmp/aframe-unit-tests-' + process.pid;
+process.env.A_FRAME_SYNC = 'false';
+
+beforeAll(async () => {
+    return Promise.resolve();
+});
+
+afterAll(async () => {
+    try {
+        fs.unlinkSync('a-concept.conf.json');
+    } catch (_) {}
+    return Promise.resolve();
+});
+
+beforeEach(async () => {
+    A_Context.reset();
+    return Promise.resolve();
+});
+
+afterEach(async () => {
+    A_Context.reset();
+    return Promise.resolve();
+});