Skip to content

feat(core): add deterministic ClaimGraph sections, logs, and query expansion#28

Merged
HiveForensicsAI merged 3 commits intomainfrom
codex/implement-claimgraph-feature-in-monorepo
Mar 3, 2026
Merged

feat(core): add deterministic ClaimGraph sections, logs, and query expansion#28
HiveForensicsAI merged 3 commits intomainfrom
codex/implement-claimgraph-feature-in-monorepo

Conversation

@HiveForensicsAI
Copy link
Copy Markdown
Contributor

Motivation

  • Provide a deterministic, pack-embedded knowledge graph extracted from source docs so runtime agents can share and reason over a stable local graph.
  • Allow agents/tools to record append-only, offline-friendly delta overlays (ClaimGraphLog) with deterministic merge/apply semantics so multiple actors can share state without network services.
  • Enable optional, bounded, deterministic query expansion driven by the graph to improve retrieval while preserving reproducibility and offline operation.

Description

  • Added a new graph subsystem under packages/core/src/graph/ with the following modules: claim_graph.ts (types, normalization, stable id/hash helpers, indexing, validation), build_claim_graph.ts (deterministic extraction rules: markdown links, wiki links, headings→definitions, conservative is/are sentences, evidence collection, bounded per-doc edges), log.ts (append-only ClaimGraphLog types, deterministic merge/apply/serialize/deserialize), and query_expand.ts (deterministic graph-based query expansion with predicate allowlist and caps).
  • Wired graph generation into pack builds by extending buildPack() to accept graph options, build the base ClaimGraph, append an optional trailing JSON graph section to pack bytes, and set meta.claimGraph counts.
  • Updated runtime mount logic (mountPackFromBuffer) and Pack types to detect and parse optional trailing sections robustly (semantic + ClaimGraph), expose pack.claimGraph, and remain tolerant of unknown trailing bytes for backward compatibility.
  • Integrated optional graph expansion into retrieval by adding graph options to QueryOptions and by expanding the query deterministically via expandQueryWithGraph() before lexical tokenization when graph.expand=true.
  • Exported public APIs and types from @knolo/core: ClaimGraph, ClaimNode, ClaimEdge, ClaimGraphLog, ClaimOp, buildClaimGraph, getClaimGraph, applyClaimGraphLog, mergeClaimGraphLogs, createGraphLog, appendOp, serializeClaimGraphLog, deserializeClaimGraphLog, and expandQueryWithGraph.
  • Added tests and fixtures to the core test harness to validate deterministic build, pack round-trip mounting of graph, mount tolerance for unknown trailing bytes, deterministic log merge/tombstone behavior, and deterministic query expansion; and updated READMEs with usage examples and configuration notes.

Testing

  • Ran typecheck/build via npm run build successfully across the monorepo and verified the runtime bundle contains no Node stdlib specifiers (build ✅).
  • Ran core test suite via npm test --workspace @knolo/core which executed added graph tests (deterministic build, pack round-trip, unknown trailing bytes, log merge/tombstone, query expansion) and passed (core tests ✅).
  • Ran full workspace npm test which exercises other packages; @knolo/core tests passed but there are unrelated existing assertion expectations in @knolo/cli tests causing the workspace-wide run to fail (workspace test status ⚠️, unrelated to the ClaimGraph changes).

Codex Task

@HiveForensicsAI HiveForensicsAI merged commit 72af0f5 into main Mar 3, 2026
0 of 2 checks passed
@HiveForensicsAI HiveForensicsAI deleted the codex/implement-claimgraph-feature-in-monorepo branch March 3, 2026 08:51
@HiveForensicsAI HiveForensicsAI added enhancement New feature or request and removed codex labels Mar 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants