Persist typed vector graph edges

.gitignore

@@ -1,6 +1,7 @@
 # Root-level build artifacts and binaries
 /*.so
 /qihse-server
+/qihse_keygen
 /test_mldsa
 /fuzzer
 
@@ -11,10 +12,19 @@
 # Root-level cache, logs, and temp files
 /qihse_qmag_telemetry.log
 /wal.log
+/wal.log.old
 /qihse_audit.log
 /qihse_integrity.chain
 /.DS_Store
 /__pycache__/
+**/__pycache__/
+*.py[cod]
+
+# Local agent indexes, memory, and personal integration state
+/.devin/
+/.learn/
+/.qlearn/
+/memory-bank/
 
 # CNSA 2.0 PQC key material (generate with scripts/qihse_keygen.sh)
 /qihse_kem_key.pem

Makefile

@@ -10,25 +10,24 @@ QIHSE_CFLAGS_EXTRA?=
 # ---------------------------------------------------------------------------
 # CPU ISA feature flags
 # ---------------------------------------------------------------------------
-# Each flag defaults to auto-detect via compiler probe at make time.
+# Each flag defaults to auto-detect from the build host's advertised CPU flags.
 # Override on the command line or environment, e.g.:
 #   make QIHSE_ENABLE_AVX2=1 QIHSE_ENABLE_AVX512=0 QIHSE_ENABLE_AMX=0
 #
-# Hosts without a feature MUST set it to 0; the build will not crash but the
-# corresponding sources/flags are simply omitted.
+# Cross-builds may override each flag explicitly on the make command line.
 #
 # R320/E5-2450 v2: AVX only – AVX2, FMA, AVX-512, VNNI, AMX all absent.
 # Sapphire Rapids+: all features available.
 
-# ---- probe helpers ---------------------------------------------------------
-# Returns "1" if the compiler can assemble the given flag, "0" otherwise.
-cc_supports = $(shell echo 'int x;' | $(CC) $(1) -x c - -c -o /dev/null 2>/dev/null && echo 1 || echo 0)
+# ---- host feature helpers --------------------------------------------------
+HOST_CPU_FLAGS ?= $(shell awk -F: '/^flags/{sub(/^ /, "", $$2); print $$2; exit}' /proc/cpuinfo 2>/dev/null)
+cpu_has = $(if $(filter $(1),$(HOST_CPU_FLAGS)),1,0)
 
 # ---- per-ISA defaults (auto-detect unless already set in env/CLI) ----------
-QIHSE_ENABLE_AVX2     ?= $(call cc_supports,-mavx2)
-QIHSE_ENABLE_AVX512   ?= $(call cc_supports,-mavx512f)
-QIHSE_ENABLE_AVX_VNNI ?= $(call cc_supports,-mavxvnni)
-QIHSE_ENABLE_AMX      ?= $(call cc_supports,-mamx-tile)
+QIHSE_ENABLE_AVX2     ?= $(call cpu_has,avx2)
+QIHSE_ENABLE_AVX512   ?= $(if $(and $(filter avx512f,$(HOST_CPU_FLAGS)),$(filter avx512dq,$(HOST_CPU_FLAGS)),$(filter avx512bw,$(HOST_CPU_FLAGS)),$(filter avx512vl,$(HOST_CPU_FLAGS))),1,0)
+QIHSE_ENABLE_AVX_VNNI ?= $(call cpu_has,avx_vnni)
+QIHSE_ENABLE_AMX      ?= $(if $(and $(filter amx_tile,$(HOST_CPU_FLAGS)),$(filter amx_int8,$(HOST_CPU_FLAGS)),$(filter amx_bf16,$(HOST_CPU_FLAGS))),1,0)
 
 # ---------------------------------------------------------------------------
 # Security & Audit Configuration
@@ -146,7 +145,7 @@ endif
 # because their functionality is already partially in qihse_math.c / qihse_search.c 
 # or provided by qihse_exports.c stubs.
 
-.PHONY: all build build-native clean pristine workspace workspace-clean lib lib-ctypes liboqs oqs-provider persistence persistence-check test benchmark install dev-setup docs test-persist test-trinary-codec test-memory-planner test-memory-topology-probe test-memory-planner-trace test-memory-allocation-policy test-memory-coherence test-memory-migration-policy test-memory-migration test-memory-device-placement test-memory-migration-backend test-memory-migration-scheduler bench-trinary-codec bench-trinary-db-candidate bench-micro bench-trinary-search-path bench-trinary-search-sweep bench-trinary-random-sweep bench-trinary-weighted-sweep bench-trinary-magnitude-sweep bench-reference-workloads bench-reference-runner-smoke sample-vxug-pdf-workload bench-vxug-pdf-workload bench-reference-workload bench-reference-result-summary bench-sift1m-workload bench-sift1m-fallback-data calibrate-sift1m-workload validate-reference-workflow check-upstream-workflow check-upstream-workflow-strict check upstream-pr-loop test-all-isa test-vnni-bench test-vnni-only test-avx2-only test-avx512-direct test-amx-only test-direct-execution test-simple-exec
+.PHONY: all build build-native clean pristine workspace workspace-clean lib lib-ctypes liboqs oqs-provider persistence persistence-check test benchmark install dev-setup docs test-persist test-edge-persistence test-kv-read-integrity test-trinary-codec test-memory-planner test-memory-topology-probe test-memory-planner-trace test-memory-allocation-policy test-memory-coherence test-memory-migration-policy test-memory-migration test-memory-device-placement test-memory-migration-backend test-memory-migration-scheduler bench-trinary-codec bench-trinary-db-candidate bench-micro bench-trinary-search-path bench-trinary-search-sweep bench-trinary-random-sweep bench-trinary-weighted-sweep bench-trinary-magnitude-sweep bench-reference-workloads bench-reference-runner-smoke sample-vxug-pdf-workload bench-vxug-pdf-workload bench-reference-workload bench-reference-result-summary bench-sift1m-workload bench-sift1m-fallback-data calibrate-sift1m-workload validate-reference-workflow check-upstream-workflow check-upstream-workflow-strict check upstream-pr-loop test-all-isa test-vnni-bench test-vnni-only test-avx2-only test-avx512-direct test-amx-only test-direct-execution test-simple-exec
 .NOTPARALLEL: validate-reference-workflow
 
 all: liboqs oqs-provider lib server keygen
@@ -225,7 +224,19 @@ test-persist: lib
 	    -L. -lqihse $(LDFLAGS)
 	LD_LIBRARY_PATH=. ./tests/qihse_vector_db_persistence_test
 
-test: test-omni test-e2e test-e2e-memory-planner test-persist test-bytecode test-document-store test-column-store test-fts-engine test-timeseries test-trinary-codec test-memory-planner test-memory-topology-probe test-memory-planner-trace test-memory-allocation-policy test-memory-coherence test-memory-migration-policy test-memory-migration test-memory-device-placement test-memory-migration-backend test-memory-migration-scheduler test-quantization
+test-edge-persistence: lib
+	$(CC) $(CFLAGS) -o tests/qihse_edge_persistence_test \
+	    tests/qihse_edge_persistence_test.c \
+	    -L. -lqihse $(LDFLAGS)
+	LD_LIBRARY_PATH=. ./tests/qihse_edge_persistence_test
+
+test: test-omni test-e2e test-e2e-memory-planner test-persist test-bytecode test-document-store test-column-store test-fts-engine test-timeseries test-trinary-codec test-memory-planner test-memory-topology-probe test-memory-planner-trace test-memory-allocation-policy test-memory-coherence test-memory-migration-policy test-memory-migration test-memory-device-placement test-memory-migration-backend test-memory-migration-scheduler test-quantization test-kv-read-integrity
+
+test-kv-read-integrity: lib
+	$(CC) $(CFLAGS) -o tests/test_kv_read_integrity tests/test_kv_read_integrity.c -L. -lqihse $(LDFLAGS)
+	rm -f qihse_integrity.chain*
+	@status=0; LD_LIBRARY_PATH=. ./tests/test_kv_read_integrity || status=$$?; \
+		rm -f tests/test_kv_read_integrity; exit $$status
 
 test-bytecode: lib
 	$(CC) $(CFLAGS) -o tests/test_bytecode tests/test_bytecode.c -L. -lqihse $(LDFLAGS)

README.md

@@ -172,6 +172,21 @@ make test
 make bench-micro
 ```
 
+The repository also includes a unified Linux launcher for the common build,
+status, test, benchmark, database, and SDK workflows:
+
+```bash
+./qihse status
+./qihse build
+./qihse test
+./qihse db --help
+./qihse python
+```
+
+Run `./qihse --help` for the complete command list. The launcher delegates to
+the existing Make targets and scripts; it does not install a daemon or modify
+system configuration.
+
 ### Minimal C Example
 
 ```c

include/qihse_vector_db.h

@@ -532,6 +532,9 @@ bool qihse_vector_db_add_model_weights(
  *
  * @param vdb Vector database handle
  * @param vector_id External vector ID to delete
+ * Deletion fails with EBUSY while explicit edges reference the vector; remove
+ * those relationships first so every persisted edge retains valid endpoints.
+ *
  * @return true if a live vector was deleted, false on failure or missing ID
  */
 bool qihse_vector_db_delete_by_id(
@@ -721,6 +724,30 @@ bool qihse_vector_db_search_batch(
  * EXPLICIT GRAPH EDGE MANAGEMENT (QQL/Graph DB)
  * ============================================================================ */
 
+#define QIHSE_EDGE_TYPE_MAX 31u
+
+typedef enum qihse_edge_direction_e {
+    QIHSE_EDGE_OUTGOING = 0,
+    QIHSE_EDGE_INCOMING = 1,
+    QIHSE_EDGE_BOTH = 2
+} qihse_edge_direction_t;
+
+typedef struct qihse_edge_input_s {
+    uint64_t from_id;
+    uint64_t to_id;
+    const char* edge_type;
+    const void* metadata;
+    size_t metadata_size;
+} qihse_edge_input_t;
+
+typedef struct qihse_edge_result_s {
+    uint64_t from_id;
+    uint64_t to_id;
+    char edge_type[QIHSE_EDGE_TYPE_MAX + 1u];
+    void* metadata;
+    size_t metadata_size;
+} qihse_edge_result_t;
+
 /**
  * Add an explicit edge between two vector nodes.
  *
@@ -759,6 +786,55 @@ int qihse_vector_db_get_edges(
     size_t max_edges
 );
 
+/** Add or idempotently retain a batch of typed edges. */
+bool qihse_vector_db_add_edges(
+    qihse_vector_db_t vdb,
+    const qihse_edge_input_t* edges,
+    size_t edge_count,
+    size_t* changed_count
+);
+
+/** Replace metadata on an existing typed edge. */
+bool qihse_vector_db_replace_edge(
+    qihse_vector_db_t vdb,
+    uint64_t from_id,
+    uint64_t to_id,
+    const char* edge_type,
+    const void* metadata,
+    size_t metadata_size
+);
+
+/** Remove an existing typed edge. Missing edges are idempotent success. */
+bool qihse_vector_db_remove_edge(
+    qihse_vector_db_t vdb,
+    uint64_t from_id,
+    uint64_t to_id,
+    const char* edge_type
+);
+
+/** Retrieve typed neighbors in the requested direction. */
+int qihse_vector_db_get_typed_neighbors(
+    qihse_vector_db_t vdb,
+    uint64_t node_id,
+    const char* edge_type,
+    qihse_edge_direction_t direction,
+    uint64_t* out_ids,
+    size_t max_edges
+);
+
+/** Retrieve edge records including owned metadata copies. */
+int qihse_vector_db_get_edge_records(
+    qihse_vector_db_t vdb,
+    uint64_t node_id,
+    const char* edge_type,
+    qihse_edge_direction_t direction,
+    qihse_edge_result_t* results,
+    size_t max_edges
+);
+
+/** Release metadata allocated by qihse_vector_db_get_edge_records. */
+void qihse_vector_db_free_edge_records(qihse_edge_result_t* results, size_t count);
+
 /* ============================================================================
  * EMBEDDED QUERY EXECUTION (QQL & SQL)
  * ============================================================================ */

persistence/qihse_container.h

@@ -35,10 +35,11 @@ extern "C" {
 #define QIHSE_CTR_SEC_GRAPH     0x0009u
 #define QIHSE_CTR_SEC_INT8      0x000Au
 #define QIHSE_CTR_SEC_TIER      0x000Bu
+#define QIHSE_CTR_SEC_EDGES     0x000Cu
 #define QIHSE_CTR_SEC_KEY       0x1000u
 #define QIHSE_CTR_SEC_SIGNATURE 0x1001u
 
-#define QIHSE_CTR_NUM_SECTIONS  13u
+#define QIHSE_CTR_NUM_SECTIONS  14u
 
 /* ── Layout constants ─────────────────────────────────────────────── */
 #define QIHSE_CTR_MAGIC         "QIHSEQDB"

persistence/qihse_vector_store.c

@@ -819,7 +819,8 @@ bool qihse_vector_store_flush(const char* db_path, const qihse_vector_store_flus
         (!in->metadata && in->metadata_bytes != 0u) ||
         (!in->idmap && in->idmap_count != 0u) ||
         (!in->trinary && in->trinary_bytes != 0u) ||
-        (!in->magnitude && in->magnitude_bytes != 0u)) {
+        (!in->magnitude && in->magnitude_bytes != 0u) ||
+        (!in->explicit_edges && in->explicit_edges_bytes != 0u)) {
         errno = EINVAL;
         return false;
     }
@@ -909,7 +910,7 @@ bool qihse_vector_store_flush(const char* db_path, const qihse_vector_store_flus
     {
         /* Build the section buffer list for the atomic container flush.
          * Order: MANIFEST last so a partial write can be detected on reopen. */
-        qihse_ctr_section_buf_t bufs[8];
+        qihse_ctr_section_buf_t bufs[9];
         size_t nb = 0u;
         bufs[nb].section_id = QIHSE_CTR_SEC_VECTORS;
         bufs[nb].data       = in->vectors;
@@ -939,6 +940,10 @@ bool qihse_vector_store_flush(const char* db_path, const qihse_vector_store_flus
             bufs[nb].size       = in->magnitude_bytes;
             nb++;
         }
+        bufs[nb].section_id = QIHSE_CTR_SEC_EDGES;
+        bufs[nb].data       = in->explicit_edges;
+        bufs[nb].size       = in->explicit_edges_bytes;
+        nb++;
         bufs[nb].section_id = QIHSE_CTR_SEC_MANIFEST;
         bufs[nb].data       = manifest_data;
         bufs[nb].size       = sizeof(manifest_data);

persistence/qihse_vector_store.h

@@ -120,6 +120,8 @@ typedef struct qihse_vector_store_flush_s {
     uint64_t magnitude_generation;
     uint64_t magnitude_row_bytes;
     uint32_t magnitude_flags;
+    const void* explicit_edges;
+    size_t explicit_edges_bytes;
 } qihse_vector_store_flush_t;
 
 bool qihse_vector_store_load(const char* db_path, qihse_vector_store_snapshot_t* out);