> 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/sessions/phase26-session01-graph-data-contracts-seed-fixtures/spec.md). # Session Specification **Session ID**: `phase26-session01-graph-data-contracts-seed-fixtures` **Phase**: 26 - Knowledge Graph Shared Brain Port **Status**: Complete **Created**: 2026-06-09 **Completed**: 2026-06-09 *** ## 1. Session Overview This session establishes the typed Knowledge Graph data layer that every later Phase 26 session depends on. It ports the graphify NetworkX node-link shape into AI OS-native TypeScript contracts for graph nodes, graph links, confidence values, registry entries, god nodes, graph metadata, and token/cost savings estimates. The work creates rejecting parsers and normalization helpers so bridge endpoints, the read hook, the 3D renderer, and Hermes grounding do not consume ad hoc JSON. It also adds demo fixtures plus a checked-in AI OS self-graph registry and seed graph, preserving the local-first, demo-safe fallback model already used by Hermes and other AI OS surfaces. This is the natural first session for Phase 26 because Sessions 02 through 06 explicitly consume these contracts, fixtures, and seed data. The reference graphify seed exists at `/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/data/graphs/claude-os.json`, so the only remaining prerequisite is implementation. *** ## 2. Objectives 1. Define TypeScript contracts for graphify node-link graphs, registry entries, god nodes, graph metadata, and savings estimates. 2. Implement rejecting parser functions with clear parse errors and normalization for legacy or partial graph payloads. 3. Add demo fixtures and checked-in seed graph data shaped like the live Knowledge Graph contract. 4. Add focused contract tests for valid parsing, malformed rejection, normalization, and savings estimate behavior. *** ## 3. Prerequisites ### Required Sessions * [x] `phase25-session09-documentation-validation-release` - Phase 25 completed, leaving Hermes Mission Control, admin hooks, and closeout docs available. ### Required Tools/Knowledge * Bun 1.3.14, TypeScript, Vitest, and existing AI OS path aliases. * Existing parser/test patterns in `src/lib/hermes-types.ts`, `src/lib/hermes-admin-types.ts`, and `src/lib/__tests__/hermes-types.test.ts`. * Graphify reference shape from `/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/components/graphify-graph-3d.tsx`. * Reference seed registry and graph under `/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/data/graphs/`. ### Environment Requirements * Local filesystem access to the AI OS repo and the Claude OS v2.4 reference tree. * No live graphify binary, network access, or admin bridge is required for this session. *** ## 4. Scope ### In Scope (MVP) * AI OS can import typed Knowledge Graph contracts - implement `src/lib/knowledge-graph-types.ts` with node, link, registry, god-node, metadata, and savings estimate types. * AI OS can reject malformed graph payloads - implement parser functions that throw explicit parse errors for missing arrays, invalid node/link ids, invalid confidence values, and malformed registry entries. * AI OS can normalize safe legacy or partial graph payloads - preserve valid graph data while defaulting optional fields and deriving counts where needed. * AI OS can run offline/demo Knowledge Graph flows later - add demo fixtures in `src/lib/knowledge-graph-demo-data.ts` that parse through the same contracts. * AI OS can serve a bundled seed later - add `src/data/graphs/index.json` and `src/data/graphs/ai-os.json` in graphify-compatible shape. * AI OS can prove contract behavior - add contract tests under `src/lib/__tests__/`. ### Out of Scope (Deferred) * Bridge endpoints - *Reason: Session 02 owns loopback-only read endpoints and Session 03 owns admin-gated ingest/removal endpoints.* * 3D renderer - *Reason: Session 04 owns reusable rendering, capping, bloom, density, and cleanup behavior.* * `/knowledge-graph` route and read hook - *Reason: Session 05 owns route, hook, gallery, hero, and sidebar wiring.* * Ingest UI and connect prompt - *Reason: Session 06 owns admin UI and starter chips.* * Hermes chat grounding and Shared Brain scripts - *Reason: Sessions 07 and 08 own chat grounding, scripts, homepage, and OAuth readiness fixes.* *** ## 5. Technical Approach ### Architecture Add a narrow typed data layer in `src/lib/knowledge-graph-types.ts`. The module should be usable from browser code, bridge code, tests, and demo fixtures without importing React, filesystem APIs, or Vite-only behavior. Parser functions should follow the existing AI OS read-admin parser style: accept `unknown`, validate at the boundary, return typed objects, and throw a dedicated parse error for unsafe or malformed input. The checked-in seed graph should stay compatible with graphify's NetworkX node-link output: top-level `nodes` and `links` arrays, node ids as strings, link source and target ids, optional labels/file metadata, community ids, and confidence values limited to `EXTRACTED`, `INFERRED`, or `AMBIGUOUS`. The seed registry should keep a workspace-relative `graphPath` so later read bridge work can resolve and confine paths explicitly. ### Design Patterns * Boundary parser: All external JSON enters through parser functions before application code consumes it. * Additive normalization: Optional legacy fields may receive safe defaults, but malformed required fields are rejected. * Demo data through real contracts: Demo fixtures should call or satisfy the same parser contract as seed/live data. * Static seed fallback: Checked-in graph files provide a useful offline baseline before live graphify ingest exists. ### Technology Stack * TypeScript 6.0.3. * Bun 1.3.14. * Vitest 4.1.6. * Existing AI OS `@/` import alias. * JSON graph fixtures under `src/data/graphs/`. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------- | ------------------------------------------------------------------------------- | ---------- | | `src/lib/knowledge-graph-types.ts` | Typed graph, registry, metadata, savings contracts plus parsers and normalizers | \~340 | | `src/lib/knowledge-graph-demo-data.ts` | Parser-backed demo registry and graph fixtures for offline mode | \~180 | | `src/data/graphs/index.json` | Checked-in AI OS seed registry | \~45 | | `src/data/graphs/ai-os.json` | Checked-in AI OS self-graph seed in graphify node-link shape | \~1-2500 | | `src/lib/__tests__/knowledge-graph-types.test.ts` | Contract tests for parsing, rejection, normalization, and seed data | \~260 | ### Files to Modify | File | Changes | Est. Lines | | ------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------- | | None expected | This session should be additive unless implementation discovers an existing export barrel that already owns lib exports | \~0 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `parseKnowledgeGraph()` accepts valid graphify node-link graphs. * [ ] `parseKnowledgeGraph()` rejects malformed payloads instead of silently coercing required fields. * [ ] Registry parsers accept the checked-in seed registry and reject invalid ids, counts, god nodes, colors, and graph paths. * [ ] Demo fixtures parse through the same public contract as seed/live data. * [ ] Savings estimates are typed, bounded, and deterministic. ### Testing Requirements * [ ] Unit tests written and passing for valid seed graph and registry parsing. * [ ] Unit tests written and passing for malformed graph and registry rejection. * [ ] Unit tests written and passing for normalization and savings estimate behavior. * [ ] Focused `bun run test -- src/lib/__tests__/knowledge-graph-types.test.ts` completed. * [ ] `bun run typecheck` completed or a documented blocker recorded. ### Non-Functional Requirements * [ ] Parser errors are explicit enough for later bridge/UI error mapping. * [ ] Seed and demo data are browser-safe and contain no secrets or private machine paths. * [ ] No new runtime dependency is introduced. * [ ] Data files remain compatible with later loopback read bridge path confinement. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. *** ## 8. Implementation Notes ### Key Considerations * Keep graphify wire compatibility while using AI OS naming for module exports. * Prefer manual parser helpers consistent with Hermes parser modules unless implementation shows an established local Zod pattern is a better fit for this specific contract. * Treat `graphPath` as data only in this session; path resolution and confinement belong to the read bridge in Session 02. * Keep the seed graph labeled as a bundled seed snapshot so future live ingest can supersede it without confusing demo/real provenance. ### Potential Challenges * Seed graph creation: Use the reference shape as the schema guide, but generate an AI OS self-graph rather than copying the Claude OS graph. * Large JSON readability: Minified graph JSON is acceptable if tests parse it and the registry remains readable. * Partial graph normalization: Default optional metadata only; reject missing `nodes`, missing `links`, and invalid ids to avoid hiding broken ingest. ### Relevant Considerations * \[P01] **3D vendor chunk budget**: This session should not import the 3D vendor stack; keep data contracts renderer-agnostic. * \[P04] **Hermes bridge guardrails must stay intact**: This session prepares contracts only; do not introduce bridge behavior or write paths. * \[P24] **Fail-closed bridges need boundary validation**: Parser functions must reject malformed external input so later bridge endpoints can fail closed. * \[P25] **Writes stay on the shared admin contract**: Do not add ad hoc graph ingest/remove behavior in this session. * \[P02] **Typed degradation over throws**: Use typed demo/fallback states for known offline behavior, while rejecting malformed graph data at the contract boundary. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Malformed graph JSON being silently accepted and breaking later render or bridge code. * Demo/seed data being mistaken for live graphify output without explicit provenance. * Parser exports drifting from the graphify wire shape that later endpoints and renderer code will consume. *** ## 9. Testing Strategy ### Unit Tests * Parse a valid minimal graph. * Parse `src/data/graphs/index.json` and `src/data/graphs/ai-os.json`. * Parse demo fixtures exported by `src/lib/knowledge-graph-demo-data.ts`. * Reject malformed payloads: non-object graph, missing arrays, bad node id, bad link source/target, invalid confidence, bad registry count, bad graph path. * Normalize partial graph payloads with optional node labels, communities, and confidence values. * Verify deterministic savings estimate math and bounds. ### Integration Tests * No bridge or route integration tests are required in this session. * Seed registry plus seed graph parsing functions as the contract-level integration check. ### Manual Testing * Inspect seed registry and graph path names for AI OS naming and no private absolute paths. * Run the focused Vitest file and TypeScript typecheck. ### Edge Cases * Empty graph with valid `nodes: []` and `links: []`. * Link source/target values that are already object-shaped from force-graph runtime and need to normalize to ids only when explicitly supported. * Unknown confidence values. * Duplicate node ids. * Registry entry count mismatches with graph metadata. * Missing optional node labels or file metadata. *** ## 10. Dependencies ### External Libraries * None new. ### Internal Dependencies * `src/lib/hermes-types.ts` and `src/lib/hermes-admin-types.ts` for parser style. * `src/lib/graph-types.ts` for existing force-graph boundary terminology. * `src/lib/__tests__/hermes-types.test.ts` for contract test structure. * Reference graphify files under `/home/aiwithapex/projects/claudeos/claude-os-v2.4/`. ### Other Sessions * **Depends on**: Phase 25 completion. * **Depended by**: Phase 26 Sessions 02, 03, 04, 05, 06, 07, 08, and 09. *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # 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/sessions/phase26-session01-graph-data-contracts-seed-fixtures/spec.md?ask=&goal= ``` `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.