Migrate VeriSimDB client to verified v0.2.0 octad contract

.github/CONTRIBUTING.md

@@ -29,9 +29,11 @@ npm install
 cp .env.example .env
 source .env
 
-# Start verisimdb (in another terminal)
-cd /var$REPOS_DIR/verisimdb
-cargo run -p verisim-api
+# Start the pinned VeriSimDB server (in another terminal)
+git clone https://github.com/hyperpolymath/verisimdb.git
+cd verisimdb
+git checkout 10f8a21f4d0f2eacce84eee29e504f66fbe9e332
+VERISIM_HOST=127.0.0.1 VERISIM_ENABLE_IPV4=true cargo run -p verisim-api
 
 # Start the API
 deno run --watch=apps/api --allow-net --allow-env apps/api/main.ts

.github/workflows/actions.lock

@@ -13,8 +13,8 @@ workflows:
         - 'actions/upload-pages-artifact@v3.0.1'
         - 'haskell-actions/setup@v2.7.5'
     '.github/workflows/ci.yml':
-        - 'actions/checkout@v6.0.2'
-        - 'denoland/setup-deno@v2.0.4'
+        - 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1'
+        - 'denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed'
     '.github/workflows/codeql.yml':
         - 'actions/checkout@v7.0.1'
         - 'github/codeql-action@v4.39.0'
@@ -37,6 +37,11 @@ dependencies:
         commit: 'sha1-0057852bfaa89a56745cba8c7296529d2fc39830'
         owner_id: 44036562
         repo_id: 215566462
+    'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1':
+        ref: 'v7.0.1'
+        commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1'
+        owner_id: 44036562
+        repo_id: 197814629
     'actions/checkout@v4.1.1':
         ref: 'v4.1.1'
         commit: 'sha1-b4ffde65f46336ab88eb53be808477a3936bae11'
@@ -79,9 +84,9 @@ dependencies:
         repo_id: 496012378
         uses:
             - 'actions/upload-artifact@v4'
-    'denoland/setup-deno@v2.0.4':
-        ref: 'v2.0.4'
-        commit: 'sha1-667a34cdef165d8d2b2e98dde39547c9daac7282'
+    'denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed':
+        ref: 'v2.0.5'
+        commit: 'sha1-22d081ff2d3a40755e97629de92e3bcbfa7cf2ed'
         owner_id: 42048915
         repo_id: 356423100
     'github/codeql-action@v4.39.0':

.github/workflows/ci.yml

@@ -1,30 +1,77 @@
 # This workflow is managed by gh actions-lock.
 # SPDX-License-Identifier: MPL-2.0
 # This workflow is managed by gh actions-lock.
-name: CI
-on:
-  pull_request:
-  push:
-    branches: [main]
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-permissions:
-  actions: read
-  contents: read
-jobs:
-  engine:
-    name: Matching engine + API (fmt, lint, typecheck, tests)
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@v7.0.1
-      - uses: denoland/setup-deno@v2.0.5
-        with:
-          deno-version: v2.x
-      - name: Format check (engine)
-        run: deno task fmt:check
-      - name: Lint + typecheck (engine, legacy domain, API)
-        run: deno task check
-      - name: Engine unit tests
-        run: deno task test
+---
+{
+  name: "CI",
+  on: {
+    pull_request: null,
+    push: {
+      branches: [
+        "main",
+      ],
+    },
+  },
+  concurrency: {
+    group: "${{ github.workflow }}-${{ github.ref }}",
+    cancel-in-progress: true,
+  },
+  # Checkout and Actions metadata are read-only; no write token is needed.
+  permissions: {
+    actions: "read",
+    contents: "read",
+  },
+  jobs: {
+    engine: {
+      name: "Matching engine + API contract (lint, typecheck, tests)",
+      runs-on: "ubuntu-latest",
+      timeout-minutes: 10,
+      steps: [
+        {
+          uses: "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1", # v7.0.1
+          with: {
+            persist-credentials: false,
+          },
+        },
+        {
+          uses: "denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed", # v2.0.5
+          with: {
+            deno-version: "2.9.6",
+          },
+        },
+        {
+          name: "Format check (changed JavaScript)",
+          run: "deno fmt --check packages/shared/src/encoding.js apps/api/src/verisimTransport.js apps/api/src/verisimTransport.contract.js tests/integration/verisimdb_contract.js",
+        },
+        {
+          name: "Lint + typecheck (engine, legacy domain, API transport)",
+          run: "deno lint packages/shared/src apps/api/src/verisimTransport.js apps/api/src/verisimTransport.contract.js tests/integration/verisimdb_contract.js && deno check packages/shared/src/index.js packages/shared/src/matching/index.js apps/api/src/verisimTransport.js",
+        },
+        {
+          name: "Engine unit tests",
+          run: "deno test packages/shared/src",
+        },
+        {
+          name: "Install verified Bun 1.4.2",
+          run: "set -euo pipefail\ncurl --proto '=https' --proto-redir '=https' --fail --silent --show-error --location https://github.com/oven-sh/bun/releases/download/bun-v1.4.2/bun-linux-x64.zip --output \"$RUNNER_TEMP/bun.zip\"\necho \"36368faef7527875d5ffa52e53cd48021741f2a83eb6208a8dd64068d422a913  $RUNNER_TEMP/bun.zip\" | sha256sum --check --strict\nunzip -q \"$RUNNER_TEMP/bun.zip\" -d \"$RUNNER_TEMP\"\necho \"$RUNNER_TEMP/bun-linux-x64\" >> \"$GITHUB_PATH\"\n",
+        },
+        {
+          name: "Install contract-test dependencies",
+          run: "bun install --frozen-lockfile --ignore-scripts --cwd apps/api",
+        },
+        {
+          name: "VeriSimDB v0.2.0 consumer contract tests",
+          run: "cd apps/api && bun test ./src/verisimTransport.contract.js",
+        },
+        {
+          name: "Install pinned ijson-jcs",
+          run: "cargo install --git https://github.com/hyperpolymath/ijson-jcs --rev 0fdeea716fd558e9807362acf6f8202d56d8d88f --locked ijson-jcs",
+        },
+        {
+          name: "New JSON is I-JSON + JCS",
+          run: "ijson-jcs check apps/api/package.json\nijson-jcs check tests/contracts/verisimdb/v0.2.0/manifest.json\nijson-jcs check tests/contracts/verisimdb/v0.2.0/octad-input.json\n",
+        },
+      ],
+    },
+  },
+}

.machine_readable/integrations/verisimdb.a2ml

@@ -8,6 +8,7 @@ repository = "https://github.com/hyperpolymath/nextgen-databases"
 data-store = "verisimdb-data"
 
 [feed-config]
+# Legacy analytics-feed format only; not the flat-mate app's VeriSimDB API contract.
 emit-scan-results = true
 emit-build-metrics = true
 emit-dependency-graph = true

0-AI-MANIFEST.a2ml

@@ -8,7 +8,7 @@
   (project "flat-mate")
   (description "London-first flatmate matching and room listings for students.
     Three-app monorepo: Deno API, React web, Expo mobile, with shared domain logic.
-    Uses verisimdb hexads for persistence via vector and text search.")
+    Uses pinned VeriSimDB v0.2.0 octads for persistence via vector and text search.")
 
   (canonical-locations
     (scm-files ".machine_readable/"
@@ -19,8 +19,8 @@
       (mobile "apps/mobile/" (runtime "expo") (language "jsx"))
       (shared "packages/shared/" (language "javascript")))
     (documentation "docs/")
-    (architecture "docs/architecture.md")
-    (topology "TOPOLOGY.md")
+    (architecture "docs/architecture.adoc")
+    (topology "TOPOLOGY.adoc")
     (license "LICENSE" (spdx "MPL-2.0"))
     (security "SECURITY.md")
     (well-known ".well-known/"))

EXPLAINME.adoc

@@ -12,9 +12,11 @@ listing (where to live). flat-mate handles both in one flow, with profile compat
 and listing discovery centered around London boroughs and universities.
 ____
 
-Profiles, listings, and swipe events are stored as hexads in VeriSimDB. The API runs
-on Deno; the web client uses React + Vite; the mobile client uses Expo. See
-link:docs/architecture.md[] and link:TOPOLOGY.md[] for the full architecture.
+Profiles, listings, and swipe events in the legacy v0 flow are stored as octads
+through the pinned VeriSimDB v0.2.0 API. The API runs on Deno; the web client
+uses React + Vite; the mobile client uses Expo. See link:docs/architecture.adoc[],
+link:TOPOLOGY.adoc[], and link:docs/verisimdb-contract.adoc[] for the architecture
+and persistence contract.
 
 **Caveat:** This is an MVP. University email validation (`.ac.uk`) *is* enforced
 server-side — every profile write runs `validateProfileInput`
@@ -46,6 +48,6 @@ the Squad Audit — see link:docs/design/squad-audit-v1.adoc[].
 | `packages/shared/`
 | Shared domain models and VeriSimDB encoding helpers
 
-| `docs/architecture.md`
+| `docs/architecture.adoc`
 | Architecture is documented
 |===

README.adoc

@@ -37,27 +37,32 @@ link:docs/design/squad-audit-v1.adoc[].
 
 == Architecture
 
-`flat-mate` writes entities as hexads in `verisimdb` (`POST /hexads`,
-`GET /search/text`, `POST /search/vector`). Because current `verisimdb` API
-responses are compact, the app stores encoded payloads in searchable document
-titles as an MVP strategy.
+The legacy v0 flow writes entities as octads through the pinned VeriSimDB
+v0.2.0 API (`POST /api/v1/octads`, `GET /api/v1/search/text`,
+`POST /api/v1/search/vector`). App-facing `OctadInput` payloads are adapted to
+that release's actual REST `OctadRequest`; this is deliberately more than a
+route rename. Because the server's search responses are compact, the app
+stores encoded payloads in searchable document titles as an MVP strategy.
+See link:docs/verisimdb-contract.adoc[the verified contract and test guide].
 
 The in-tree profile/listing/swipe write paths are the legacy v0 flow. The v1
 target is an epistemic-typed server: per-field governance metadata,
 conceal-lattice disclosure tiers, no special-category fields by schema
 construction — see the design doc. Matching rules live in
 `packages/shared/src/matching/`, never in UI components.
 
-See `docs/architecture.md`, link:TOPOLOGY.md[], and link:EXPLAINME.adoc[].
+See link:docs/architecture.adoc[], link:TOPOLOGY.adoc[], and link:EXPLAINME.adoc[].
 
 == Quick Start
 
-. Start verisimdb in another terminal:
+. Start the pinned VeriSimDB server in another terminal:
 +
 [source,bash]
 ----
-cd /var/mnt/eclipse/repos/verisimdb
-cargo run -p verisim-api
+git clone https://github.com/hyperpolymath/verisimdb.git
+cd verisimdb
+git checkout 10f8a21f4d0f2eacce84eee29e504f66fbe9e332
+VERISIM_HOST=127.0.0.1 VERISIM_ENABLE_IPV4=true cargo run -p verisim-api
 ----
 
 . Install web/mobile dependencies:

TOPOLOGY.adoc

@@ -35,7 +35,7 @@ not yet wired into any app.
                                    ▼                   ▼
                         ┌───────────────────────┐  ┌────────────────────────────────┐
                         │ SHARED PACKAGE        │  │ VERISIMDB INTERFACE            │
-                        │ - Domain Models       │  │ - Hexad encoding               │
+                        │ - Domain Models       │  │ - Octad document encoding      │
                         │ - Compatibility Logic │  │ - Vector/Text search           │
                         └──────────┬────────────┘  └──────────┬─────────────────────┘
                                    │                          │
@@ -78,8 +78,9 @@ tests exist (`+*.test.js+`; run `+deno test packages/shared+`).
 |`+apps/mobile+` (Expo) |*LEGACY* v0 only |Wired to the legacy flow; not
 wired to the matching engine.
 
-|Test coverage |Matching-engine unit tests only |`+tests/+` contains a
-fuzz placeholder; no API/web/mobile tests exist.
+|Test coverage |Matching-engine unit tests and legacy API contract tests
+|`+tests/+` contains a fuzz placeholder and an opt-in VeriSimDB live
+integration test; no web/mobile tests exist.
 
 |`+.machine_readable/+` |Present |STATE.a2ml is the source of truth for
 completion status.
@@ -88,7 +89,7 @@ completion status.
 === Key Dependencies
 
 ....
-User Profile ───► Hexad Encoding ───► verisimdb (Write)
+User Profile ───► Octad Document Encoding ───► verisimdb (Write)
      │                 │                   │
      ▼                 ▼                   ▼
 Matching UI ◄───► API Layer ◄───────► Vector Search

apps/api/package.json

@@ -0,0 +1 @@
+{"devDependencies":{"ajv":"8.17.1"},"name":"flat-mate-api-contract-tests","private":true,"version":"0.0.0"}