> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_26/session_02_graph_read_bridge_registry_endpoints.md).

# Session 02: Graph Read Bridge And Registry Endpoints

**Session ID**: `phase26-session02-graph-read-bridge-registry-endpoints` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Add a loopback-only Knowledge Graph read bridge that lists the graph registry (with auto-prune of missing artifacts) and streams a graph by id with path confinement and a bundled seed fallback, registered into the Vite dev server the same way the Hermes read bridge is.

***

## Scope

### In Scope (MVP)

* `scripts/lib/knowledge-graph-dev-bridge.ts` exporting a `registerKnowledgeGraphDevBridge(server, options)` function.
* `GET /__graphify_list`: read the registry, auto-prune entries whose graph artifact no longer exists or whose local source path no longer exists, keep `git:` and empty-path entries, return typed list payload.
* `GET /__graphify_graph?id=`: sanitize id, confine to the shared graph directory, stream the graph file, fall back to the bundled seed graph.
* Loopback-only gating and id/path sanitization.
* Registration in `vite.config.ts` via `configureServer`.
* Bridge tests (registry read, prune, id confinement, fallback, non-loopback rejection).

### Out of Scope

* Ingest/removal writes (Session 03).
* UI consumption (Session 05).

***

## Prerequisites

* [ ] Session 01 contracts available.
* [ ] Hermes read-bridge registration pattern confirmed in `vite.config.ts`.

***

## Deliverables

1. `scripts/lib/knowledge-graph-dev-bridge.ts` read bridge.
2. Shared graph directory + registry path resolution helpers.
3. `vite.config.ts` registration wiring.
4. Bridge tests under `scripts/lib/__tests__/`.

***

## Success Criteria

* [ ] `/__graphify_list` returns a typed registry list, prunes stale local entries, and retains durable `git:`/empty-path entries.
* [ ] `/__graphify_graph?id=` streams a confined graph and falls back to seed.
* [ ] Non-loopback and path-escape attempts are rejected.
* [ ] Bridge tests pass.

***

## Folded Port Detail

### Source Project Reference Links

#### AI OS Targets

* [Read bridge (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/knowledge-graph-dev-bridge.ts)
* [Registration site](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/vite.config.ts)
* [Hermes read bridge pattern](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/hermes-dev-bridge.ts)
* [Contracts from Session 01](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/knowledge-graph-types.ts)

#### Claude OS v2.4 Reference

* [Reference graph endpoints](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/vite.config.ts)

### Reference (v2.4)

* Shared graph directory constant: `v2.4/vite.config.ts:302-308`.
* `GET /__graphify_list` registry read + auto-prune (graph missing or local source path missing; keep `git:`/empty source paths): `v2.4/vite.config.ts:310-353`.
* `GET /__graphify_graph?id=` streamed graph read: `v2.4/vite.config.ts:355-395`.
* Security posture: graph endpoints loopback-gated; ids sanitized/path-confined.

### Build Steps

1. Add a shared graph directory + registry path helper (env/workspace aware).
2. Implement `/__graphify_list` with auto-prune of missing artifacts or missing local source paths, while retaining `git:`/empty source entries.
3. Implement `/__graphify_graph?id=` with id sanitization, path confinement, and bundled seed fallback.
4. Apply loopback-only gating consistent with the Hermes read bridge.
5. Register the bridge in `vite.config.ts`.
6. Write tests for list/prune, stream, confinement, fallback, and rejection.

### Exit Criteria

* Both read endpoints serve typed payloads and are loopback-gated.
* Auto-prune and seed fallback behave per `v2.4` and are tested.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_26/session_02_graph_read_bridge_registry_endpoints.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.