@x12i/static-memorix-explorer-api 1.0.0 → 1.1.1

package/guides/using-the-api.md

@@ -0,0 +1,265 @@
+# Using the API
+
+The mock server exposes the full Memorix Explorer API under `/api/explorer/`.
+All responses are JSON. Errors follow the shape `{ ok: false, error: "..." }`.
+
+Base URL defaults to `http://localhost:5030`.
+
+## Endpoints
+
+### Health
+
+| Method | Path                                  | Description                           |
+| ------ | ------------------------------------- | ------------------------------------- |
+| `GET`  | `/health`                             | Simple `{"ok":true}`                  |
+| `GET`  | `/api/explorer/health?includeInventory=1` | Full health with optional inventory |
+
+### Inventory
+
+| Method | Path                                     | Description                         |
+| ------ | ---------------------------------------- | ----------------------------------- |
+| `GET`  | `/api/explorer/inventory/collections`    | Inventory rows for all object types |
+| `GET`  | `/api/explorer/inventory/summary`        | Aggregated counts                   |
+| `GET`  | `/api/explorer/inventory/issues`         | Orphan/missing-collection rows      |
+| `GET`  | `/api/explorer/inventory/graph`          | `{ nodes, edges }` from catalogRelations |
+
+Query param: `sourceLens=db-first|catalox-first` (default: `catalox-first`).
+
+### Snapshots
+
+| Method | Path                                                              | Description                        |
+| ------ | ----------------------------------------------------------------- | ---------------------------------- |
+| `GET`  | `/api/explorer/snapshots/:objectType/:recordId`                   | Normalized snapshot with associated bucket |
+| `GET`  | `/api/explorer/snapshots/:objectType/:recordId/associated`        | Just the associated bucket         |
+| `GET`  | `/api/explorer/snapshots/:objectType/:recordId/associated/:prop`  | Single associated property         |
+| `GET`  | `/api/explorer/snapshots/:objectType/associated-properties`       | All `associated*` properties       |
+| `POST` | `/api/explorer/associations/plan`                                 | Generate association plan          |
+| `POST` | `/api/explorer/associations/apply`                                | Apply association plan             |
+| `POST` | `/api/explorer/associations/verify`                               | Verify association fingerprint     |
+
+### Records
+
+| Method | Path                                    | Description                              |
+| ------ | --------------------------------------- | ---------------------------------------- |
+| `GET`  | `/api/explorer/records/collection`      | Query with filters, search, sort, pagination |
+| `GET`  | `/api/explorer/records/full`            | All content types for a recordId         |
+| `GET`  | `/api/explorer/records/item`            | Single item with optional descriptor hydration |
+| `GET`  | `/api/explorer/records/content`         | Single content record by contentType + identity key |
+| `GET`  | `/api/explorer/records/raw-collection`  | Raw collection array                     |
+| `GET`  | `/api/explorer/records/raw-item`        | Single raw item by collectionName + recordId |
+| `GET`  | `/api/explorer/records/workspace`       | Cross-entity workspace query             |
+| `POST` | `/api/explorer/records/write`           | Write records (validate/dryRun/add/upsert/patch/replace/delete) |
+| `DELETE`| `/api/explorer/records/item`           | Delete a record by entityName + recordId |
+
+### Lists
+
+| Method | Path                                      | Description                   |
+| ------ | ----------------------------------------- | ----------------------------- |
+| `GET`  | `/api/explorer/lists`                     | List all descriptors          |
+| `GET`  | `/api/explorer/lists/:listId`             | Single descriptor             |
+| `GET`  | `/api/explorer/lists/:listId/records`     | Execute list query            |
+| `GET`  | `/api/explorer/lists/:listId/records-ws`  | Execute list query (WS variant)|
+| `GET`  | `/api/explorer/lists/suggest`             | Suggest extensions            |
+| `POST` | `/api/explorer/lists`                     | Create descriptor (requires flag) |
+| `PATCH`| `/api/explorer/lists/:listId`             | Update descriptor (requires flag) |
+| `PUT`  | `/api/explorer/lists/:listId/sort`        | Update sort (requires flag)   |
+| `DELETE`| `/api/explorer/lists/:listId`            | Delete descriptor (requires flag) |
+
+### Narratives
+
+| Method | Path                                            | Description               |
+| ------ | ----------------------------------------------- | ------------------------- |
+| `GET`  | `/api/explorer/narratives`                      | All narratives            |
+| `GET`  | `/api/explorer/narratives/:entity`              | Merged narratives for entity |
+| `GET`  | `/api/explorer/narratives/:entity/raw`          | Raw authored narratives   |
+| `GET`  | `/api/explorer/narratives/:entity/:key`         | Single narrative          |
+| `GET`  | `/api/explorer/narratives/:entity/:key/records` | Records tagged with narrative |
+| `POST` | `/api/explorer/narratives`                      | Create (requires flag)    |
+| `PATCH`| `/api/explorer/narratives/:entity/:key`         | Update (requires flag)    |
+| `DELETE`| `/api/explorer/narratives/:entity/:key`        | Delete (requires flag)    |
+
+### Object Types
+
+| Method | Path                                                       | Description              |
+| ------ | ---------------------------------------------------------- | ------------------------ |
+| `GET`  | `/api/explorer/object-types`                               | List all object types    |
+| `GET`  | `/api/explorer/object-types/:name`                         | Single object type       |
+| `GET`  | `/api/explorer/object-types/:name/root-property-catalog`   | Get root property catalog|
+| `POST` | `/api/explorer/object-types/:name/root-property-catalog/compute` | Compute + persist catalog |
+
+### Agents & Auth
+
+| Method | Path                             | Description                    |
+| ------ | -------------------------------- | ------------------------------ |
+| `GET`  | `/api/explorer/agents`           | Agent registry                 |
+| `POST` | `/api/explorer/auth/token`       | Mock M2M token                 |
+
+## Query conventions
+
+### Filtering
+
+```
+filter=field:operator:value
+```
+
+Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `exists`, `regex`.
+
+Repeatable with `&` or `;`-separated:
+
+```
+filter=severity:eq:critical&filter=status:eq:open
+filter=severity:eq:critical;status:eq:open
+```
+
+For `in`/`nin`, use `|` as the value separator:
+
+```
+filter=severity:in:critical|high
+```
+
+### Virtual narrative filters
+
+Narrative filters rewrite the query to check the `narratives` map on each
+document:
+
+```
+filter=narrativeId:eq:has-vulns
+```
+
+This evaluates `doc.narratives["has-vulns"]` being truthy.
+
+### Sorting
+
+```
+sort=severity:desc&sort=entityId:asc
+```
+
+### Full-text search
+
+```
+searchText=web-prod
+q=web-prod
+```
+
+Substring match across string fields.
+
+### Pagination
+
+```
+limit=50&offset=0&includeTotal=1
+```
+
+- `limit`: max 500, defaults to 100.
+- `offset` or `skip`: number of records to skip.
+- `includeTotal`: when `1`, includes `total` in the response.
+
+### Target tier
+
+```
+target=memory
+```
+
+Queries the memory tier instead of the default entity tier.
+
+## Identity keys
+
+Each record must carry exactly one identity key:
+
+| Key           | Tier     | Used by                        |
+| ------------- | -------- | ------------------------------ |
+| `recordId`    | entities | snapshots, analysis, decisions |
+| `entityId`    | entities | snapshots (secondary)          |
+| `eventId`     | events   | events                         |
+| `knowledgeId` | knowledge| analysis                       |
+| `memoryId`    | memory   | memory                         |
+
+Endpoints like `/records/full` and `/records/content` require exactly one
+identity key per request.
+
+## Snapshot alias translation
+
+The API translates associated data between storage format and client format:
+
+```
+Storage:  associatedData, associatedDiscovery, associatedInferred, associatedAnalysis
+Client:   associated.data, associated.discovery, associated.analysis
+```
+
+`associatedInferred` is merged into `associated.discovery` alongside
+`associatedDiscovery`. Custom buckets (e.g. `associatedCustom`) are mapped to
+`associated.custom`.
+
+## Write operations
+
+`POST /api/explorer/records/write` accepts:
+
+```json
+{
+  "writeDescriptorId": "assets-analysis-write",
+  "operation": "upsert",
+  "input": [
+    { "recordId": "asset-1", "analysisType": "risk", "score": 8.5 }
+  ],
+  "dryRun": false,
+  "validateOnly": false
+}
+```
+
+### Operations
+
+| Operation  | Behavior                                         |
+| ---------- | ------------------------------------------------ |
+| `add`      | Appends records (auto-generates ID if missing)   |
+| `upsert`   | Updates existing by identity key, or appends     |
+| `patch`    | Updates existing by identity key, no-op if missing |
+| `replace`  | Replaces the entire collection (use with caution)|
+| `delete`   | Removes all records matching the supplied identity keys; returns the removed records |
+
+### Required-field semantics
+
+The `schema.required` array is enforced **fully** only for `add` and `replace`
+operations. For `upsert`, `patch`, and `delete`, only the collection's identity
+field (`recordId`, or `memoryId` on the memory tier) is required — every other
+field is optional and treated as a partial update. This lets you send
+`{recordId, status}` on a status-only edit without re-supplying the title.
+
+### Flags
+
+- `validateOnly: true` validates input against the write descriptor schema
+  without modifying state.
+- `dryRun: true` validates and simulates the operation without changing live
+  in-memory state or disk.
+
+### Delete via REST endpoint
+
+For ergonomics, deletes can also be issued with a dedicated REST endpoint.
+It still requires and verifies a write descriptor, so it cannot bypass the
+same collection contract used by `POST /records/write`:
+
+```
+DELETE /api/explorer/records/item?entityName=product&recordId=t1&writeDescriptorId=product-task-write
+```
+
+Returns `{ ok: true, count: <n>, removed: [<record>…] }`. Flushes immediately.
+
+### Delete via `op: "delete"`
+
+The equivalent call via the write endpoint:
+
+```json
+{
+  "writeDescriptorId": "product-task-write",
+  "operation": "delete",
+  "input": { "recordId": "t1" }
+}
+```
+
+## Feature flag gates
+
+Mutation endpoints return `{ ok: false, error: "Metadata writes are disabled" }`
+when the corresponding feature flag is not enabled. Set the environment
+variable to `true` or `1` to allow writes:
+
+```bash
+MEMORIX_EXPLORER_ENABLE_METADATA_WRITES=true mock-memorix-explorer-api
+```

package/mocks/data/admin/snapshots.json

@@ -0,0 +1,52 @@
+[
+  {
+    "recordId": "t10",
+    "title": "Reconcile initial expenses for Q1 server setup",
+    "status": "todo",
+    "priority": "normal",
+    "owner": "Sam",
+    "area": "admin",
+    "assigneeId": "usr-1",
+    "dueDate": "2026-07-22",
+    "notes": "Compile all receipts for the dedicated server hardware and confirm the ledger matches.",
+    "chat": [],
+    "narratives": {
+      "q1-review": true
+    }
+  },
+  {
+    "recordId": "t11",
+    "title": "File the LLC formation paperwork",
+    "status": "doing",
+    "priority": "urgent",
+    "owner": "Alex",
+    "area": "admin",
+    "assigneeId": "usr-1",
+    "dueDate": "2026-07-20",
+    "notes": "Articles of organization, operating agreement, and EIN application.",
+    "chat": [
+      {
+        "id": "cmt-4",
+        "authorId": "usr-2",
+        "timestamp": "2026-07-19T09:00:00Z",
+        "text": "I have the forms ready. Need your digital signatures."
+      }
+    ],
+    "narratives": {}
+  },
+  {
+    "recordId": "t12",
+    "title": "Review and sign the hosting contract",
+    "status": "done",
+    "priority": "normal",
+    "owner": "Alex",
+    "area": "admin",
+    "assigneeId": "usr-1",
+    "dueDate": "2026-07-15",
+    "notes": "12-month term, 99.9% SLA, 24/7 support included.",
+    "chat": [],
+    "narratives": {
+      "q1-review": true
+    }
+  }
+]

package/mocks/data/assets/analysis.json

@@ -0,0 +1,14 @@
+[
+  {
+    "recordId": "asset-1",
+    "analysisType": "vulnerability-scan",
+    "score": 9.1,
+    "notes": ["Outdated TLS", "Public exposure"]
+  },
+  {
+    "recordId": "asset-2",
+    "analysisType": "vulnerability-scan",
+    "score": 7.4,
+    "notes": ["Unpatched engine"]
+  }
+]

package/mocks/data/assets/decisions.json

@@ -0,0 +1,14 @@
+[
+  {
+    "recordId": "asset-1",
+    "decision": "remediate-now",
+    "owner": "sec-team",
+    "sla": "24h"
+  },
+  {
+    "recordId": "asset-2",
+    "decision": "monitor",
+    "owner": "db-team",
+    "sla": "7d"
+  }
+]

package/mocks/data/assets/events.json

@@ -0,0 +1,4 @@
+[
+  { "recordId": "asset-1", "event": "scan-started", "at": "2026-07-01T10:00:00Z" },
+  { "recordId": "asset-1", "event": "scan-completed", "at": "2026-07-01T10:05:00Z" }
+]

package/mocks/data/assets/snapshots.json

@@ -0,0 +1,49 @@
+[
+  {
+    "recordId": "asset-1",
+    "entityId": "web-prod-01",
+    "severity": "critical",
+    "status": "open",
+    "region": "us-east-1",
+    "ownerId": "agent-1",
+    "narratives": { "has-vulns": true, "exposed-public": true },
+    "associatedData": [
+      { "kind": "tag", "value": "prod" },
+      { "kind": "tag", "value": "web" }
+    ],
+    "associatedInferred": [
+      { "kind": "discovery", "value": "public-ip" }
+    ],
+    "associatedAnalysis": [
+      { "kind": "analysis", "value": "cve-score-9" }
+    ]
+  },
+  {
+    "recordId": "asset-2",
+    "entityId": "db-prod-01",
+    "severity": "high",
+    "status": "open",
+    "region": "us-east-1",
+    "ownerId": "agent-2",
+    "narratives": { "has-vulns": true, "critical-owner": true },
+    "associatedData": [
+      { "kind": "tag", "value": "prod" },
+      { "kind": "tag", "value": "database" }
+    ],
+    "associatedDiscovery": [
+      { "kind": "discovery", "value": "internal-rds" }
+    ]
+  },
+  {
+    "recordId": "asset-3",
+    "entityId": "cache-dev-01",
+    "severity": "low",
+    "status": "closed",
+    "region": "eu-west-1",
+    "ownerId": "agent-1",
+    "narratives": { "exposed-public": true },
+    "associatedData": [
+      { "kind": "tag", "value": "dev" }
+    ]
+  }
+]

package/mocks/data/findings/analysis.json

@@ -0,0 +1,4 @@
+[
+  { "recordId": "finding-1", "analysisType": "cvss", "score": 9.1 },
+  { "recordId": "finding-2", "analysisType": "cvss", "score": 7.4 }
+]

package/mocks/data/findings/decisions.json

@@ -0,0 +1,4 @@
+[
+  { "recordId": "finding-1", "decision": "patch", "owner": "sec-team" },
+  { "recordId": "finding-2", "decision": "patch", "owner": "db-team" }
+]

package/mocks/data/findings/events.json

@@ -0,0 +1,3 @@
+[
+  { "recordId": "finding-1", "event": "detected", "at": "2026-07-01T10:05:00Z" }
+]

package/mocks/data/findings/snapshots.json

@@ -0,0 +1,21 @@
+[
+  {
+    "recordId": "finding-1",
+    "entityId": "web-prod-01",
+    "assetId": "asset-1",
+    "severity": "critical",
+    "status": "open",
+    "cve": "CVE-2026-1234",
+    "narratives": { "high-severity": true },
+    "associatedData": [{ "kind": "reference", "value": "CVE-2026-1234" }]
+  },
+  {
+    "recordId": "finding-2",
+    "entityId": "db-prod-01",
+    "assetId": "asset-2",
+    "severity": "high",
+    "status": "open",
+    "cve": "CVE-2026-5678",
+    "narratives": { "high-severity": true }
+  }
+]

package/mocks/data/marketing/snapshots.json

@@ -0,0 +1,75 @@
+[
+  {
+    "recordId": "t6",
+    "title": "Draft the open-source monetization blog post",
+    "status": "doing",
+    "priority": "urgent",
+    "owner": "Jordan",
+    "area": "marketing",
+    "assigneeId": "usr-3",
+    "dueDate": "2026-07-22",
+    "notes": "Focus the narrative on programmatic SEO strategies and the managed service provider angle.",
+    "chat": [
+      {
+        "id": "cmt-2",
+        "authorId": "usr-1",
+        "timestamp": "2026-07-20T10:15:00Z",
+        "text": "Let me know when the first draft is ready for review."
+      },
+      {
+        "id": "cmt-3",
+        "authorId": "usr-3",
+        "timestamp": "2026-07-20T11:30:00Z",
+        "text": "Will have it by end of day."
+      }
+    ],
+    "narratives": {
+      "blog-content": true
+    }
+  },
+  {
+    "recordId": "t7",
+    "title": "Record product demo video for the landing page",
+    "status": "todo",
+    "priority": "normal",
+    "owner": "Jordan",
+    "area": "marketing",
+    "assigneeId": "usr-3",
+    "dueDate": "2026-07-28",
+    "notes": "Keep it under 60 seconds. Highlight the drag-and-drop workflow and real-time collaboration.",
+    "chat": [],
+    "narratives": {
+      "website-refresh": true
+    }
+  },
+  {
+    "recordId": "t8",
+    "title": "Set up the email newsletter welcome sequence",
+    "status": "todo",
+    "priority": "normal",
+    "owner": "Casey",
+    "area": "marketing",
+    "assigneeId": "usr-3",
+    "dueDate": "2026-07-24",
+    "notes": "Three emails over 5 days. First email delivers value, third has CTA for trial signup.",
+    "chat": [],
+    "narratives": {
+      "launch-prep": true
+    }
+  },
+  {
+    "recordId": "t9",
+    "title": "Schedule 3 posts for the launch week",
+    "status": "someday",
+    "priority": "low",
+    "owner": "",
+    "area": "marketing",
+    "assigneeId": null,
+    "dueDate": "",
+    "notes": "Topics: technical deep dive, customer story, and product announcement.",
+    "chat": [],
+    "narratives": {
+      "launch-prep": true
+    }
+  }
+]

package/mocks/data/memory/memory.json

@@ -0,0 +1,31 @@
+[
+  {
+    "memoryId": "mem-1",
+    "entityId": "web-prod-01",
+    "kind": "conversation-summary",
+    "summary": "Discussed upgrade path for web-prod-01 from v2 to v3.",
+    "createdAt": "2026-07-10T08:00:00Z"
+  },
+  {
+    "memoryId": "mem-2",
+    "entityId": "db-prod-01",
+    "kind": "decision-rationale",
+    "summary": "Chose AWS RDS over self-hosted for db-prod-01 due to maintenance costs.",
+    "createdAt": "2026-07-10T09:00:00Z"
+  },
+  {
+    "memoryId": "mem-3",
+    "eventId": "evt-1",
+    "kind": "post-mortem",
+    "summary": "Investigated event-1 (disk pressure) and added alerts.",
+    "createdAt": "2026-07-10T10:00:00Z"
+  },
+  {
+    "memoryId": "mem-99",
+    "kind": "test"
+  },
+  {
+    "memoryId": "mem-99",
+    "kind": "test"
+  }
+]

package/mocks/data/product/snapshots.json

@@ -0,0 +1,84 @@
+[
+  {
+    "recordId": "t1",
+    "title": "Review new frontend styling for the landing page",
+    "status": "doing",
+    "priority": "urgent",
+    "owner": "Sam",
+    "area": "product",
+    "assigneeId": "usr-2",
+    "dueDate": "2026-07-21",
+    "notes": "Ensure the dark-mode contrast ratios meet the updated accessibility guidelines we discussed.",
+    "chat": [],
+    "narratives": {
+      "website-refresh": true
+    }
+  },
+  {
+    "recordId": "t2",
+    "title": "Finalize the API rate-limiting strategy",
+    "status": "todo",
+    "priority": "normal",
+    "owner": "Alex",
+    "area": "product",
+    "assigneeId": "usr-2",
+    "dueDate": "2026-07-23",
+    "notes": "Document the rate limits per endpoint and implement exponential backoff for exceeded clients.",
+    "chat": [],
+    "narratives": {
+      "launch-prep": true
+    }
+  },
+  {
+    "recordId": "t3",
+    "title": "Write unit tests for the auth module",
+    "status": "todo",
+    "priority": "normal",
+    "owner": "Sam",
+    "area": "product",
+    "assigneeId": "usr-2",
+    "dueDate": "2026-07-25",
+    "notes": "Focus on edge cases: expired tokens, malformed payloads, and concurrent login attempts.",
+    "chat": [
+      {
+        "id": "cmt-1",
+        "authorId": "usr-1",
+        "timestamp": "2026-07-19T14:22:00Z",
+        "text": "Can you add tests for the refresh token flow as well?"
+      }
+    ],
+    "narratives": {
+      "launch-prep": true
+    }
+  },
+  {
+    "recordId": "t4",
+    "title": "Set up error tracking in production",
+    "status": "done",
+    "priority": "urgent",
+    "owner": "Alex",
+    "area": "product",
+    "assigneeId": "usr-1",
+    "dueDate": "2026-07-18",
+    "notes": "Configure Sentry to capture unhandled exceptions and track error rates by endpoint.",
+    "chat": [],
+    "narratives": {
+      "launch-prep": true
+    }
+  },
+  {
+    "recordId": "t5",
+    "title": "Add dark mode toggle to settings",
+    "status": "someday",
+    "priority": "low",
+    "owner": "",
+    "area": "product",
+    "assigneeId": null,
+    "dueDate": "",
+    "notes": "Save preference to localStorage and persist to user profile on next sync.",
+    "chat": [],
+    "narratives": {
+      "website-refresh": true
+    }
+  }
+]

package/mocks/data/system/inventory.json

@@ -0,0 +1,8 @@
+{
+  "policy": {
+    "seedInventoryEnabled": true,
+    "defaultLens": "catalox-first",
+    "collectionOverrides": {}
+  },
+  "collectionOverrides": []
+}

package/mocks/data/users/snapshots.json

@@ -0,0 +1,5 @@
+[
+  { "recordId": "usr-1", "name": "Ami", "role": "owner" },
+  { "recordId": "usr-2", "name": "Devran", "role": "engineer" },
+  { "recordId": "usr-3", "name": "Ilan", "role": "growth" }
+]