@adaas/a-frame 0.0.22 → 0.0.23

package/src/lib/A-FrameStorage/node/A-FrameNodeStorage.component.ts

@@ -0,0 +1,464 @@
+import { A_Caller, A_Feature, A_Inject } from "@adaas/a-concept";
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { A_FrameStorageFeatures } from "../A-FrameStorage.constants";
+import { A_FrameStorage } from "../A-FrameStorage.component";
+import { A_FrameEnv } from "../../A-FrameEnv/A-FrameEnv.fragment.env-node";
+import { A_FrameStorageOperation } from "../A-FrameStorageOperation.context";
+import { A_FrameCrypto } from "../../A-FrameCrypto/A-FrameCrypto.component.env-node";
+import { A_FrameNamespace_Serialized } from "../../A-FrameNamespace/A-FrameNamespace.types";
+import { A_FrameStorageCodec } from "../A-FrameStorage.codec";
+import { A_FrameDefinitionFeatures } from "../../A-FrameDefinition/A-FrameDefinition.constants";
+import { A_FrameDefinition } from "../../A-FrameDefinition";
+import { A_FrameDefinition_Serialized } from "../../A-FrameDefinition/A-FrameDefinition.types";
+import { A_FrameContext } from "../../A-Frame/A-Frame.context";
+import { A_FrameNamespace } from "../../A-FrameNamespace";
+import { A_FrameNamespaceFeatures } from "../../A-FrameNamespace/A-FrameNamespace.constants";
+import { A_FrameStorageDestroyDefinitionsOperation, A_FrameStorageDestroyNamespacesOperation, A_FrameStorageLoadDefinitionsOperation, A_FrameStorageLoadNamespacesOperation, A_FrameStorageSaveDefinitionOperation, A_FrameStorageSaveNamespaceOperation } from "../A-FrameStorage.types";
+import { A_FrameStorageError } from "../A-FrameStorage.error";
+
+
+/** Reserved filename for the namespace binary index */
+
+/**
+ * A_FrameStorageProvider — Node.js environment
+ *
+ * Reads and writes encrypted binary index files (*.bin) on the local filesystem.
+ * Definition records are grouped by namespace into <namespace>.bin files.
+ * Namespace records are stored in the reserved __namespaces.bin file.
+ *
+ * File layout on disk:  [IV 12B][AuthTag 16B][Ciphertext ...]
+ */
+export class A_FrameNodeStorage extends A_FrameStorage {
+
+    /** Returns file contents, or null when the file does not exist yet. Re-throws all other I/O errors. */
+    private async tryReadFile(filePath: string): Promise<Buffer | null> {
+        try {
+            return await fs.readFile(filePath);
+        } catch (err: any) {
+            if (err?.code === 'ENOENT') return null;
+            throw err;
+        }
+    }
+
+    //---------------------------------------------------------------------------------------
+    //--------------------------Definition Features Extensions-------------------------------
+    //---------------------------------------------------------------------------------------
+    /**
+     * Save a single definition to local file storage. This is called as part of A_FrameDefinition.save() when using the local file storage provider. It reads the existing namespace file, merges in the new or updated definition, and writes back the encrypted file.
+     * 
+     * @param definition 
+     * @param env 
+     * @param context 
+     * @param codec 
+     */
+    @A_Feature.Extend({
+        name: A_FrameDefinitionFeatures.Save,
+        scope: [A_FrameDefinition]
+    })
+    async saveDefinitionToDisk(
+        @A_Inject(A_Caller) definition: A_FrameDefinition,
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+    ): Promise<void> {
+        const namespace = definition.namespace
+
+        const incoming = definition.toJSON();
+        if (!incoming.embedding)
+            throw new Error('Only definitions with embeddings can be saved to storage');
+
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace.id)));
+        const existing: A_FrameDefinition_Serialized[] = rawBuf
+            ? codec.decodePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
+            : [];
+
+        const merged = new Map<string, A_FrameDefinition_Serialized>();
+        for (const r of existing) merged.set(r.hash, r);
+        merged.set(incoming.hash, incoming);
+
+        const records = Array.from(merged.values());
+        const payload = codec.encodePayload(records);
+        const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
+
+        await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace.id)), encrypted);
+    }
+    /**
+     * Load a single definition from local file storage. This is called as part of A_FrameDefinition.load() when using the local file storage provider. It reads the namespace file, finds the record for the requested definition, and if found and hash matches, populates the definition with the stored data.
+     */
+    @A_Feature.Extend({
+        name: A_FrameDefinitionFeatures.Load,
+        scope: [A_FrameDefinition]
+    })
+    async loadDefinitionFromDisk(
+        @A_Inject(A_Caller) definition: A_FrameDefinition,
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+    ): Promise<void> {
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(definition.namespace.id)));
+        if (!rawBuf) return;
+
+        const plain = await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!);
+        const records = codec.decodePayload(plain);
+
+        const record = records.find(r => r.aseid === definition.aseid.toString());
+
+        if (
+            record &&
+            record.hash === definition.hash &&
+            record.aFrameServerVersion === context.serverVersion
+        ) {
+            definition.fromJSON(record);
+        }
+
+
+    }
+    /**
+     * Delete a single definition from local file storage. This is called as part of A_FrameDefinition.destroy() when using the local file storage provider. It reads the namespace file, removes the record for the requested definition, and writes back the encrypted file.
+     * 
+     * @param definition 
+     * @param env 
+     * @param context 
+     * @param codec 
+     */
+    @A_Feature.Extend({
+        name: A_FrameDefinitionFeatures.Destroy,
+        scope: [A_FrameDefinition]
+    })
+    async destroyDefinitionFromDisk(
+        @A_Inject(A_Caller) definition: A_FrameDefinition,
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+
+    ): Promise<void> {
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(definition.namespace.id)));
+        if (!rawBuf) return;
+
+        const plain = await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!);
+        const records = codec.decodePayload(plain);
+
+        const filtered = records.filter(r => r.aseid !== definition.aseid.toString());
+
+        const payload = codec.encodePayload(filtered);
+        const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
+
+        await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(definition.namespace.id)), encrypted);
+    }
+
+    // ---------------------------------------------------------------------------------------
+    //--------------------------Namespaces Features Extensions-------------------------------
+    //---------------------------------------------------------------------------------------
+
+    @A_Feature.Extend({
+        name: A_FrameNamespaceFeatures.Save,
+        scope: [A_FrameNamespace]
+    })
+    async saveNamespaceToDisk(
+        @A_Inject(A_Caller) namespace: A_FrameNamespace,
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+    ): Promise<void> {
+        const incoming = namespace.toJSON();
+
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()));
+        const existing: A_FrameNamespace_Serialized[] = rawBuf
+            ? codec.decodeNamespacePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
+            : [];
+
+        const merged = new Map<string, A_FrameNamespace_Serialized>();
+        for (const r of existing) merged.set(r.aseid, r);
+        merged.set(incoming.aseid.toString(), incoming);
+
+        const records = Array.from(merged.values());
+        const payload = codec.encodeNamespacePayload(records);
+
+        const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
+
+        await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()), encrypted);
+    }
+
+    @A_Feature.Extend({
+        name: A_FrameNamespaceFeatures.Load,
+        scope: [A_FrameNamespace]
+    })
+    async loadNamespaceFromDisk(
+        @A_Inject(A_Caller) namespace: A_FrameNamespace,
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+    ): Promise<void> {
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()));
+        if (!rawBuf) return;
+
+        const plain = await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!);
+        const records = codec.decodeNamespacePayload(plain);
+
+        const record = records.find(r => r.aseid === namespace.aseid.toString());
+
+        if (
+            record &&
+            record.hash === namespace.hash &&
+            record.aFrameServerVersion === context.serverVersion
+        ) {
+            namespace.fromJSON(record);
+        }
+    }
+
+    @A_Feature.Extend({
+        name: A_FrameNamespaceFeatures.Destroy,
+        scope: [A_FrameNamespace]
+    })
+    async destroyNamespaceFromLocalFileStorage(
+        @A_Inject(A_Caller) namespace: A_FrameNamespace,
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+    ): Promise<void> {
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()));
+        if (!rawBuf) return;
+
+        const plain = await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!);
+        const records = codec.decodeNamespacePayload(plain);
+
+        const filtered = records.filter(r => r.aseid !== namespace.aseid.toString());
+
+        const payload = codec.encodeNamespacePayload(filtered);
+        const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
+
+        await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()), encrypted);
+
+        /**
+         * 2. Then drop definitions file related to the namespace.
+         */
+        try {
+            await fs.unlink(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace.id)));
+        } catch {
+            // no-op if file doesn't exist
+        }
+    }
+
+
+
+
+
+    // ---------------------------------------------------------------------------------------
+    //--------------------------Storage Features Extensions-------------------------------
+    //---------------------------------------------------------------------------------------
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.SaveDefinitions,
+        scope: [A_FrameStorage]
+    })
+    async saveDefinitionsToDisk(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageSaveDefinitionOperation,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+    ): Promise<void> {
+        const records = operation.params.records;
+        const namespace = records[0].namespace;
+
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace)));
+        const existing: A_FrameDefinition_Serialized[] = rawBuf
+            ? codec.decodePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
+            : [];
+
+        const merged = new Map<string, A_FrameDefinition_Serialized>();
+        for (const r of existing) merged.set(r.hash, r);
+        for (const d of records) merged.set(d.hash, d);
+
+        const result = Array.from(merged.values());
+        const payload = codec.encodePayload(result);
+        const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
+
+        await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace)), encrypted);
+
+        operation.complete({
+            saved: records.length
+        });
+    }
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.LoadDefinitions,
+        scope: [A_FrameStorage]
+    })
+    async loadDefinitionsFromDisk(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageLoadDefinitionsOperation,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+    ): Promise<void> {
+        const namespace = operation.params.namespaceId;
+
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace)));
+        const records: A_FrameDefinition_Serialized[] = rawBuf
+            ? codec.decodePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
+            : [];
+
+        operation.complete({
+            records
+        });
+    }
+
+
+
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.DestroyDefinitions,
+        scope: [A_FrameStorage]
+    })
+    async destroyDefinitionsFromDisk(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageDestroyDefinitionsOperation,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+    ): Promise<void> {
+        const namespace = operation.params.namespaceId;
+        const definitionId = operation.params.definitionId;
+
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace)));
+        const records: A_FrameDefinition_Serialized[] = rawBuf
+            ? codec.decodePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
+            : [];
+
+        const filtered = records.filter(r => r.aseid !== definitionId);
+
+        const payload = codec.encodePayload(filtered);
+        const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
+
+        await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace)), encrypted);
+
+        operation.complete({
+            records: filtered
+        });
+    }
+
+
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.SaveNamespaces,
+        scope: [A_FrameStorage]
+    })
+    async saveNamespacesToDisk(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageSaveNamespaceOperation,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+    ): Promise<void> {
+        const records = operation.params.records;
+
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()));
+        const existing: A_FrameNamespace_Serialized[] = rawBuf
+            ? codec.decodeNamespacePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
+            : [];
+
+        const merged = new Map<string, A_FrameNamespace_Serialized>();
+        for (const r of existing) merged.set(r.aseid, r);
+        for (const d of records) merged.set(d.aseid.toString(), d);
+
+        const result = Array.from(merged.values());
+        const payload = codec.encodeNamespacePayload(result);
+
+        const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
+
+        await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()), encrypted);
+
+        operation.complete({
+            success: true
+        });
+    }
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.LoadNamespaces,
+        scope: [A_FrameStorage]
+    })
+    async loadNamespacesFromDisk(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageLoadNamespacesOperation,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+    ): Promise<void> {
+        const ids = operation.params.namespaces;
+
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()));
+        const records: A_FrameNamespace_Serialized[] = rawBuf
+            ? codec.decodeNamespacePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
+            : [];
+
+        operation.complete({
+            records: ids ? records.filter(r => ids.includes(r.name)) : records
+        });
+    }
+
+
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.DestroyNamespaces,
+        scope: [A_FrameStorage]
+    })
+    async destroyNamespacesFromDisk(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageDestroyNamespacesOperation,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
+    ): Promise<void> {
+        const ids = operation.params.namespaces;
+
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()));
+        const records: A_FrameNamespace_Serialized[] = rawBuf
+            ? codec.decodeNamespacePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
+            : [];
+
+        const filtered = records.filter(r => !ids.includes(r.aseid));
+
+        const payload = codec.encodeNamespacePayload(filtered);
+        const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
+
+        await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()), encrypted);
+
+        /**
+         * 2. Then drop definitions file related to the namespace.
+         */
+        try {
+            for (const id of ids) {
+                await fs.unlink(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(id)));
+            }
+            operation.complete({
+                success: true
+            });
+        } catch (error) {
+
+            operation.fail(new A_FrameStorageError({
+                title: A_FrameStorageError.DestroyNamespacesFailed,
+                description: `Failed to destroy namespace records.`,
+            }));
+
+            operation.complete({
+                success: false
+            });
+        }
+    }
+
+}

package/src/lib/A-FrameStorage/server/A-FrameServerStorage.component.ts

@@ -0,0 +1,177 @@
+import { A_Feature, A_Inject } from "@adaas/a-concept";
+import { A_FrameStorageFeatures } from "../A-FrameStorage.constants";
+import { A_FrameStorage } from "../A-FrameStorage.component";
+import { A_FrameEnv } from "../../A-FrameEnv/A-FrameEnv.fragment.env-node";
+import { A_FrameStorageOperation } from "../A-FrameStorageOperation.context";
+import {
+    A_FrameStorageLoad,
+    A_FrameStorageSave,
+    A_FrameStorageSaveNamespaces,
+} from "../A-FrameStorage.types";
+import { A_FrameDefinition_Record } from "../../A-FrameDefinition/A-FrameDefinition.types";
+import { A_FrameNamespace_Record } from "../../A-FrameNamespace/A-FrameNamespace.types";
+
+
+// ─── JSON-wire types ──────────────────────────────────────────────────────────
+// Float32Array is not JSON-serialisable; the remote server API uses number[].
+
+type DefinitionRecordJSON = Omit<A_FrameDefinition_Record, 'embedding'> & { embedding: number[] };
+type NamespaceRecordJSON  = Omit<A_FrameNamespace_Record,  'embedding'> & { embedding: number[] };
+
+
+/**
+ * A_FrameServerStorageProvider — Remote HTTP storage
+ *
+ * Delegates all storage operations to a remote A-Frame storage server via
+ * plain HTTP/JSON, without touching the local filesystem or in-memory blobs.
+ * Works in both Node.js and browser environments (uses the global fetch).
+ *
+ * Expected server API:
+ *   POST   /api/storage/definitions             — save definition records
+ *   GET    /api/storage/definitions/:namespace  — load records for a namespace
+ *   GET    /api/storage/namespaces              — list namespace slugs
+ *   POST   /api/storage/namespaces/index        — save namespace records
+ *   GET    /api/storage/namespaces/index        — load namespace records
+ */
+export class A_FrameServerStorageProvider extends A_FrameStorage {
+
+    // ─── Definition features ──────────────────────────────────────────────────
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.SAVE,
+        scope: [A_FrameStorage],
+    })
+    async saveToRemoteServer(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) context: A_FrameStorageSave,
+    ): Promise<void> {
+        const namespace = context.request.records[0]?.namespace || 'default';
+        const records: DefinitionRecordJSON[] = context.request.records.map(r => ({
+            ...r,
+            embedding: Array.from(r.embedding),
+        }));
+
+        await this._post(env, '/api/storage/definitions', { namespace, records });
+        context.complete({ success: true });
+    }
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.LOAD,
+        scope: [A_FrameStorage],
+    })
+    async loadFromRemoteServer(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) context: A_FrameStorageLoad,
+    ): Promise<void> {
+        const namespace = context.request.namespaces?.[0] ?? 'default';
+
+        try {
+            const data = await this._get<{ records: DefinitionRecordJSON[] }>(
+                env, `/api/storage/definitions/${encodeURIComponent(namespace)}`
+            );
+            context.complete({
+                records: data.records.map(r => ({
+                    ...r,
+                    embedding: new Float32Array(r.embedding),
+                })),
+            });
+        } catch {
+            context.complete({ records: [] });
+        }
+    }
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.LIST,
+        scope: [A_FrameStorage],
+    })
+    async listNamespacesFromRemoteServer(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) context: A_FrameStorageOperation,
+    ): Promise<void> {
+        try {
+            const data = await this._get<{ namespaces: string[] }>(env, '/api/storage/namespaces');
+            context.complete({ recordIds: data.namespaces });
+        } catch {
+            context.complete({ recordIds: [] });
+        }
+    }
+
+
+    // ─── Namespace features ───────────────────────────────────────────────────
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.SAVE_NAMESPACES,
+        scope: [A_FrameStorage],
+    })
+    async saveNamespacesToRemoteServer(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) context: A_FrameStorageSaveNamespaces,
+    ): Promise<void> {
+        const namespaces: NamespaceRecordJSON[] = context.request.namespaces.map(r => ({
+            ...r,
+            embedding: Array.from(r.embedding),
+        }));
+
+        await this._post(env, '/api/storage/namespaces/index', { namespaces });
+        context.complete({ success: true });
+    }
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.LOAD_NAMESPACES,
+        scope: [A_FrameStorage],
+    })
+    async loadNamespacesFromRemoteServer(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) context: A_FrameStorageOperation,
+    ): Promise<void> {
+        try {
+            const data = await this._get<{ namespaces: NamespaceRecordJSON[] }>(
+                env, '/api/storage/namespaces/index'
+            );
+            context.complete({
+                namespaces: data.namespaces.map(r => ({
+                    ...r,
+                    embedding: new Float32Array(r.embedding),
+                })),
+            });
+        } catch {
+            context.complete({ namespaces: [] });
+        }
+    }
+
+
+    // ─── HTTP helpers ──────────────────────────────────────────────────────────
+
+    private authHeaders(env: A_FrameEnv): Record<string, string> {
+        return {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${env.A_FRAME_TOKEN}`,
+        };
+    }
+
+    private async _get<T>(env: A_FrameEnv, path: string): Promise<T> {
+        const resp = await fetch(`${env.A_FRAME_SERVER_URL}${path}`, {
+            method: 'GET',
+            headers: this.authHeaders(env),
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`GET ${path} → ${resp.status}: ${text}`);
+        }
+        return resp.json() as Promise<T>;
+    }
+
+    private async _post<T = void>(env: A_FrameEnv, path: string, body: unknown): Promise<T> {
+        const resp = await fetch(`${env.A_FRAME_SERVER_URL}${path}`, {
+            method: 'POST',
+            headers: this.authHeaders(env),
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`POST ${path} → ${resp.status}: ${text}`);
+        }
+        if (resp.status === 204) return undefined as T;
+        return resp.json() as Promise<T>;
+    }
+}

package/src/lib/{entities/A_FrameVector/A_FrameVector.entity.ts → A-FrameVector/A-FrameVector.entity.ts}

@@ -1,6 +1,11 @@
 import { A_Entity } from "@adaas/a-concept"
 
 export class A_FrameVector extends A_Entity {
+
+    static get concept(): string {
+        return 'a-frame';
+    }
+
     readonly values: Float32Array
 
     constructor(values: number[] | Float32Array) {
@@ -51,4 +56,9 @@ export class A_FrameVector extends A_Entity {
             )
         }
     }
+
+
+    toArray(): number[] {
+        return Array.from(this.values)
+    }
 }

package/src/lib/A-FrameVector/index.ts

@@ -0,0 +1,3 @@
+
+
+export * from './A-FrameVector.entity'