> 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_03_graph_ingest_removal_admin_bridge.md).

# Session 03: Graph Ingest And Removal Admin Bridge

**Session ID**: `phase26-session03-graph-ingest-removal-admin-bridge` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Add the admin-gated ingest and removal bridge that turns a local path or GitHub URL into a stored, registered graph by shelling `graphify` and `git` through argv arrays only, behind the full AI OS admin preflight, with vendored-deps and node-cap guards, metadata computation, path-aware id generation, and absolute graphPath registry writes -- the highest-risk surface in this phase.

***

## Scope

### In Scope (MVP)

* `scripts/lib/knowledge-graph-admin-bridge.ts` exporting `registerKnowledgeGraphAdminBridge(server, options)`.
* `POST /__graphify_ingest`: JSON body parse + required path; git/GitHub URL detection, validation, shallow clone into temp + cleanup; local path expansion
  * existence check; graphify binary resolution; `execFileSync(bin, ["update", repoPath])`; read generated artifact; vendored-deps guard + >12,000 node refusal; metadata computation (degree, god nodes, extracted %, communities, language); path-aware id + collision hash; graph write + registry entry with absolute `graphPath`; scratch/temp cleanup + large-graph warning.
* `DELETE /__graphify_remove?id=`: artifact + registry deletion, path-confined.
* Full admin preflight: server enforces loopback + per-run `X-Claude-OS-Token` + `HERMES_DASHBOARD_ADMIN=1`; the browser/admin hook enforces non-demo + hook-mediated writes. `graphify` remains optional with an explicit error when absent.
* Registration in `vite.config.ts`.
* Bridge tests including rejection paths (no token, non-loopback, oversized, malformed body, missing binary, path escape).

### Out of Scope

* Ingest UI (Session 06).
* Setup/installer scripts (Session 08).

***

## Prerequisites

* [ ] Session 01 contracts and Session 02 read bridge available.
* [ ] Hermes admin-bridge preflight pattern confirmed in `scripts/lib/hermes-admin-bridge.ts`.

***

## Deliverables

1. `scripts/lib/knowledge-graph-admin-bridge.ts` with ingest + remove handlers.
2. Process-spawn helpers (argv-only graphify/git, temp clone + cleanup).
3. `vite.config.ts` registration wiring.
4. Bridge tests covering success and every rejection path.

***

## Success Criteria

* [ ] Ingest and removal work only behind the full admin gate; server-side checks and browser hook/demo checks are all enforced.
* [ ] graphify/git run via `execFileSync` argv arrays; no shell strings.
* [ ] Node cap (>12,000) and vendored-deps guard refuse oversized graphs.
* [ ] Registry entries store absolute `graphPath`; ids are path-confined.
* [ ] Removal deletes artifact + registry entry safely.
* [ ] Tests cover success and unauthorized/oversized/malformed/missing-binary.

***

## Folded Port Detail

### Source Project Reference Links

#### AI OS Targets

* [Admin bridge (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/knowledge-graph-admin-bridge.ts)
* [Registration site](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/vite.config.ts)
* [Hermes admin bridge pattern](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/hermes-admin-bridge.ts)
* [Read bridge from Session 02](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/knowledge-graph-dev-bridge.ts)
* [Sanitize helpers](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/sanitize.ts)

#### Claude OS v2.4 Reference

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

### Reference (v2.4)

* `DELETE /__graphify_remove?id=`: `v2.4/vite.config.ts:397-446`.
* `POST /__graphify_ingest` shell/security contract: `v2.4/vite.config.ts:448-464`.
* JSON body parse + required path: `v2.4/vite.config.ts:465-489`.
* Git/GitHub detection, validation, shallow clone, temp cleanup: `v2.4/vite.config.ts:491-538`.
* Local path expansion + existence check: `v2.4/vite.config.ts:539-547`.
* Graphify resolution + `execFileSync(bin, ["update", repoPath])`: `v2.4/vite.config.ts:549-563`.
* Read generated artifact: `v2.4/vite.config.ts:564-577`.
* Vendored-deps guard, refuses >12,000 nodes: `v2.4/vite.config.ts:579-599`.
* Metadata computation: `v2.4/vite.config.ts:600-626`.
* Path-aware id + collision hash: `v2.4/vite.config.ts:642-664`.
* Graph write + registry entry with `graphPath`: `v2.4/vite.config.ts:666-697`.
* Scratch/temp cleanup + large-graph warning: `v2.4/vite.config.ts:698-719`.

### Build Steps

1. Build the admin preflight wrapper (reuse the Hermes admin pattern).
2. Implement body parse + path/URL handling (git detection, validation).
3. Implement temp shallow clone + guaranteed cleanup for git/GitHub sources.
4. Resolve and invoke graphify via `execFileSync` argv; handle missing binary.
5. Read artifact, apply vendored-deps guard + node cap, compute metadata.
6. Generate path-aware id + collision hash; write graph + absolute-path registry.
7. Implement `/__graphify_remove` (confined artifact + registry deletion).
8. Register in `vite.config.ts`; write success + rejection tests.

### Exit Criteria

* Ingest and remove operate only behind the admin gate, with argv-only spawning, guards, and path confinement, all covered by tests.


---

# 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_03_graph_ingest_removal_admin_bridge.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.