Skip to content

docs(k3): audit code-graph intelligence donors - #131

Merged
TheHalfMoon merged 2 commits into
mainfrom
docs/k3-code-graph-donor-differential-audit
Aug 20, 2026
Merged

TheHalfMoon merged 2 commits into
mainfrom
docs/k3-code-graph-donor-differential-audit

Conversation

@TheHalfMoon

@TheHalfMoon TheHalfMoon commented Aug 20, 2026 •

Copy link
Copy Markdown
Owner

Purpose

Record a docs-only K3 donor differential audit for two high-value repository-intelligence sources:

  • vitali87/code-graph-rag pinned at 963faa05ced113d841dedd81856e95c334c72201
  • Graphify-Labs/graphify pinned at b2cd36267456c166788c95be6e68574064a92a42

Decision

The audit treats the donors as complementary:

  • Graphify: strongest donor for local deterministic graph semantics, blast-radius / affected, graph navigation/diff, provenance labels, and incremental ergonomics.
  • Code-Graph-RAG: strongest donor for rich multi-language relation schema, resource/data-flow edges, dead-code reachability, and runtime-observed call evidence.

Kodac should combine the best ideas behind Kodac-owned snapshot/freshness/evidence/query contracts, not adopt either project as canonical backend or wholesale dependency.

Recommended future candidate

A separate founder-reviewed first graph slice should be limited to:

immutable snapshot-bound relation graph
+ bounded impact / related-files query
+ Kodac-owned gold benchmark

with no persistence, model calls, embeddings, vector store, process execution, new dependencies, or code import unless separately authorized.

Runtime tracing is explicitly separated into a future K2-governed evidence gate.

Scope

Exactly one new documentation file:

docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md

Explicit non-grants

K3-R6+=NOT_AUTHORIZED
CODE_IMPORT=NOT_AUTHORIZED
NEW_DEPENDENCIES=NOT_AUTHORIZED
PERSISTENT_GRAPH_STORAGE=NOT_AUTHORIZED
VECTOR_EMBEDDINGS=NOT_AUTHORIZED
MODEL_DERIVED_GRAPH_EDGES=NOT_AUTHORIZED
K2_AUTHORITY_CHANGE=NO
PR_130_SCOPE_CHANGE=NO
R4B_B2=NOT_AUTHORIZED
H6=NOT_AUTHORIZED

Summary by cubic

Audits repository-intelligence donors Graphify-Labs/graphify and vitali87/code-graph-rag to guide K3 code-graph direction. No behavior changes; sets explicit non-grants and a first graph-slice recommendation.

  • Treats donors as complementary: graphify for local deterministic impact/blast-radius ergonomics; code-graph-rag for richer multi-language schema, resource/data-flow edges, and runtime-observed calls.
  • Declines adopting a backend or dependencies; no code import, persistence, vectors/embeddings, or model-derived edges; K2 authority unchanged; K3-R6+ not authorized.
  • Recommends a first follow-up: immutable, snapshot-bound relation graph with bounded impact/related-files query and a Kodac-owned benchmark; in-memory and deterministic.
  • Adds one file: docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md; proposes backend-neutral contracts and queries (impact, related_files, related_tests) with explicit provenance and snapshot binding; no rollout or migration actions.

Written for commit 4136fb8. Summary will update on new commits.

Review in cubic

Summary by CodeRabbit

  • Documentation
    • Added an audit comparing potential code-graph technology sources.
    • Documented capabilities, licensing, operational considerations, and compatibility with existing boundaries.
    • Recorded recommendations for a deterministic, in-memory relation graph with bounded queries and explicit provenance.
    • Outlined future review gates for runtime observation, persistence, benchmarking, and related functionality.

@coderabbitai

coderabbitai Bot commented Aug 20, 2026 •

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 638228c1-9be0-41c3-a171-3ced7744f805

📥 Commits

Reviewing files that changed from the base of the PR and between ef83818 and 3137e42.

📒 Files selected for processing (1)
  • docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md

Included review availability: Your plan provides up to 10 included reviews per hour; 2 remain after this review.


📝 Walkthrough

Walkthrough

The pull request adds a documentation-only audit of Code-Graph-RAG and Graphify as potential Kodac code-graph donors. It defines authority boundaries, candidate graph contracts, bounded queries, implementation gates, benchmarks, threat requirements, and provenance rules.

Changes

K3 code-graph donor audit

Layer / File(s) Summary
Donor analysis and authority boundaries
docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md
Records pinned donor revisions, capabilities, licenses, provenance requirements, and Kodac authority limits. It rejects wholesale runtime imports and trust-source authority.
Snapshot-bound graph contracts and queries
docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md
Defines candidate immutable graph fields, bounded relation types, backend-neutral queries, and an initial deterministic in-memory implementation slice.
Governance, benchmarking, and adoption gates
docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md
Specifies deferred storage and vector infrastructure, threat-model requirements, benchmarks, donor adoption rules, licensing controls, and scope separation from H4/PR #130.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 3137e

This docs-only change records a donor audit without changing code, runtime behavior, dependencies, permissions, or deployment configuration; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely identifies the documentation audit of code-graph donors, which is the main change.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/k3-code-graph-donor-differential-audit

Comment @coderabbitai help to get the list of available commands.

@qodo-code-review

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Grey Divider

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Grey Divider

Tip of the day
💡 Did you know, you can copy the agent prompt from any finding and feed it to your IDE agent

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Docs: K3 code-graph donor differential audit (Graphify vs Code-Graph-RAG)

📝 Documentation 🕐 20-40 Minutes

Grey Divider

AI Description

• Adds a K3 donor differential audit for Graphify and Code-Graph-RAG at pinned commits.
• Recommends a Kodac-owned snapshot-bound relation-graph contract and bounded impact queries.
• Records explicit non-authorizations (no code import, deps, persistence, vectors, or runtime
 execution).
Diagram

graph TD
  A["K3 donor audit doc"] --> B["Donor comparison"] --> C["Kodac-owned graph contract"] --> D["First slice: snapshot graph + impact query"]
  D --> E["Future gate: runtime tracing"]
  D --> F["Future gate: persistence/cache"]
  B --> G{{"Graphify donor"}}
  B --> H{{"Code-Graph-RAG donor"}}
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Split into two donor audit docs
  • ➕ Simplifies each document’s narrative and reduces cross-references
  • ➕ Makes future updates independent per donor
  • ➖ Loses the side-by-side differential framing that drives the key conclusion
  • ➖ Encourages duplicate discussion of Kodac boundaries and non-grants
2. Record as an ADR + appendices
  • ➕ Keeps the core decision crisp and easier to review
  • ➕ Appendices can hold long capability tables and threat-model detail
  • ➖ Requires ADR conventions and indexing that may not exist for K3 planning
  • ➖ Risk of separating rationale from constraints that reviewers must see together

Recommendation: Keep the current single differential audit document: the main value is explicitly comparing complementary donor strengths while restating Kodac boundary/non-authorization constraints in one place. If readability becomes an issue, consider extracting only the final decision and “recommended first slice” into an ADR-style summary while keeping this as the detailed evidence appendix.

Files changed (1) +1049 / -0

Documentation (1) +1049 / -0
KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.mdAdd K3 donor differential audit for code-graph intelligence +1049/-0

Add K3 donor differential audit for code-graph intelligence

• Introduces a detailed docs-only audit comparing Graphify and Code-Graph-RAG at pinned commits, including capability differentials, licensing/provenance notes, and explicit rejection of wholesale adoption. Defines a proposed Kodac-owned snapshot-bound relation-graph contract, candidate vocabulary and query facade, and separates runtime tracing and persistence into future explicitly authorized gates.

docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md

Copy link
Copy Markdown
Owner Author

@coderabbitai review

Fresh review requested against the current exact PR head 3137e42f74711730c3876cb8d5f227d0a2f01626 after PR #130 became canonical on main=ff455b648632b37c2460353c36f447e797b17e4e.

Please review this PR strictly as a docs-only K3 donor differential audit. Confirm that it does not authorize K3-R6+, R4B-B2, H6, code import, new dependencies, persistence, vectors/embeddings, model-derived graph edges, or any K2 authority change. Treat the pinned historical Kodac base recorded inside the audit as audit provenance, not as a claim that current main remains at that SHA.

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Aug 20, 2026 •

Copy link
Copy Markdown
🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '== checked-out commit =='
git rev-parse HEAD
echo

echo '== changed files from stated main =='
git diff --name-status ff455b648632b37c2460353c36f447e797b17e4e...3137e42f74711730c3876cb8d5f227d0a2f01626
echo

audit_file='docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md'
echo '== audit file presence and size =='
test -f "$audit_file"
wc -l "$audit_file"
echo

echo '== audit heading outline =='
rg -n '^#{1,4} ' "$audit_file"
echo

echo '== boundary and provenance statements =='
rg -n -i -C 2 \
  'K3-R6|R4B-B2|H6|NOT_AUTHORIZED|CODE_IMPORT|NEW_DEPENDENCIES|PERSISTENT_GRAPH_STORAGE|VECTOR_EMBEDDINGS|MODEL_DERIVED_GRAPH_EDGES|K2_AUTHORITY_CHANGE|PR_130_SCOPE_CHANGE|historical|provenance|base|main|snapshot|persistence|embedding|model-derived|runtime' \
  "$audit_file"

Length of output: 23988


🏁 Script executed:

#!/bin/bash
set -euo pipefail

audit_file='docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md'

for range in '1,105p' '189,220p' '540,718p' '719,790p' '904,990p' '995,1049p'; do
  echo "== ${audit_file}:${range%p} =="
  sed -n "$range" "$audit_file"
  echo
done

Length of output: 16724


@TheHalfMoon Review complete for 3137e42f74711730c3876cb8d5f227d0a2f01626.

No findings.

The PR adds only docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md.

The audit does not authorize K3-R6+, R4B-B2, H6, code import, new dependencies, persistent storage, vectors or embeddings, model-derived graph edges, or K2 authority changes.

It keeps runtime tracing behind a separate future K2-governed gate. It keeps persistence behind a separate future storage/mutation gate. The recorded historical Kodac base is treated as audit provenance, not as the current main revision.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai

coderabbitai Bot commented Aug 20, 2026 •

Copy link
Copy Markdown
⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Copy link
Copy Markdown
Owner Author

Final exact-head evidence ledger — K3 donor differential audit

PR=131
HEAD=3137e42f74711730c3876cb8d5f227d0a2f01626
CURRENT_CANONICAL_MAIN=ff455b648632b37c2460353c36f447e797b17e4e
PR_ORIGINAL_BASE=ef83818812b76a90d843e8309073cbe320bda80e
CHANGED_PATHS=1_DOCS_ONLY

Independent review evidence:

QODO=NO_MATERIAL_ISSUES
CODERABBIT_RUN=638228c1-9be0-41c3-a171-3ced7744f805
CODERABBIT_ACTIONABLE_COMMENTS=0
CODERABBIT_MERGE_RISK=MINIMAL
UNRESOLVED_REVIEW_THREADS=0

Exact-head CI already completed successfully:

governance #1838=SUCCESS
k2-runtime #789=SUCCESS

Independent donor-pin verification before merge:

vitali87/code-graph-rag
pin=963faa05ced113d841dedd81856e95c334c72201
version=0.0.694
license=MIT

Graphify-Labs/graphify
branch=v8
pin=b2cd36267456c166788c95be6e68574064a92a42
version=0.9.48
project_license=Apache-2.0
NOTICE=prior MIT portions retained under those terms

The CANONICAL KODAC BASE=ef838188... recorded inside the audit is treated as the immutable repository base against which the audit was authored, not as a claim about current live main. PR #130 is now merged/canonical at current main and this audit does not alter its implementation or authority.

Scope/non-grants remain unchanged:

K3_R6_PLUS=NOT_AUTHORIZED
R4B_B2=NOT_AUTHORIZED
H6=NOT_AUTHORIZED
CODE_IMPORT=NOT_AUTHORIZED
NEW_DEPENDENCIES=NOT_AUTHORIZED
PERSISTENT_GRAPH_STORAGE=NOT_AUTHORIZED
VECTOR_EMBEDDINGS=NOT_AUTHORIZED
MODEL_DERIVED_GRAPH_EDGES=NOT_AUTHORIZED
K2_AUTHORITY_CHANGE=NO

Final merge is authorized only if live main/head/path/review fences remain unchanged.

Copy link
Copy Markdown
Owner Author

@coderabbitai review

Fresh exact-head review requested after the non-destructive merge-from-main synchronization required by strict branch rules.

HEAD=4136fb8555a6414758a894c7fcf93d70795f284b
BASE=ff455b648632b37c2460353c36f447e797b17e4e
BEHIND_BY=0
DIFF=exactly one docs file
AUDIT_BLOB=ddc062de054e3086f34c0906624b4683b545359d (unchanged)

Please verify no material issue and no authority widening. This audit still does NOT authorize K3-R6+, R4B-B2, H6, code import, new dependencies, graph persistence, vectors/embeddings, model-derived graph edges, or any K2 authority change.

@TheHalfMoon
TheHalfMoon merged commit ccf08bb into main Aug 20, 2026
9 checks passed
@coderabbitai

coderabbitai Bot commented Aug 20, 2026 •

Copy link
Copy Markdown
🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

head='4136fb8555a6414758a894c7fcf93d70795f284b'
base='ff455b648632b37c2460353c36f447e797b17e4e'
audit='docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md'

echo '== checked-out HEAD =='
git rev-parse HEAD
echo '== expected HEAD exists =='
git rev-parse "${head}^{commit}"
echo '== expected base exists =='
git rev-parse "${base}^{commit}"
echo '== base is an ancestor of HEAD =='
git merge-base --is-ancestor "$base" "$head" && echo yes
echo '== merge base =='
git merge-base "$base" "$head"

echo '== changed paths: base...HEAD =='
git diff --name-status "$base...$head"

echo '== audit blob at HEAD =='
git rev-parse "$head:$audit"
echo '== audit line count =='
git show "$head:$audit" | wc -l

echo '== audit scope, authority, and provenance statements =='
git show "$head:$audit" | rg -n -i -C 2 \
  'K3-R6|R4B-B2|H6|NOT_AUTHORIZED|CODE_IMPORT|NEW_DEPENDENCIES|PERSISTENT_GRAPH_STORAGE|VECTOR_EMBEDDINGS|MODEL_DERIVED_GRAPH_EDGES|K2_AUTHORITY_CHANGE|historical|provenance|canonical kodac base|current.*main|runtime tracing|persistence|embedding|model-derived'

Length of output: 12627


@TheHalfMoon Review complete for 4136fb8555a6414758a894c7fcf93d70795f284b.

No findings.

The stated base is the merge base and an ancestor of the reviewed head. The diff adds exactly one file:

docs/planning/KODAC_K3_CODE_GRAPH_DONOR_DIFFERENTIAL_AUDIT_2026-08-20.md

The audit blob remains ddc062de054e3086f34c0906624b4683b545359d.

The audit does not authorize K3-R6+, R4B-B2, H6, code import, new dependencies, persistent graph storage, vectors or embeddings, model-derived graph edges, or K2 authority changes.

It keeps runtime tracing behind a separate future K2-governed evidence gate. It keeps persistence and watcher behavior behind a separate future storage/mutation gate. The historical Kodac base remains audit provenance and does not claim that current main remains at that revision.

⚠️ Action not completed

No files to review.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Copy link
Copy Markdown
Owner Author

Canonical merge verification — PR #131

PR=131
STATE=MERGED / CLOSED
FINAL_HEAD=4136fb8555a6414758a894c7fcf93d70795f284b
PRE_MERGE_MAIN=ff455b648632b37c2460353c36f447e797b17e4e
MERGE_COMMIT=ccf08bbf007eae0794332c691838d5c96ce8f77b
CANONICAL_MAIN=ccf08bbf007eae0794332c691838d5c96ce8f77b
CANONICAL_TREE=c1ef986d513dca6297dbba75d672e064cd0aa60e
SIGNATURE_VERIFIED=true
SIGNATURE_REASON=valid
ORDERED_PARENTS:
1. ff455b648632b37c2460353c36f447e797b17e4e
2. 4136fb8555a6414758a894c7fcf93d70795f284b

The branch was synchronized with canonical main using a normal non-destructive merge commit because strict required checks rejected the stale-base candidate. No force update, rebase, or history rewrite occurred.

Post-sync exact-head gates:

governance #1851=SUCCESS
k2-runtime #796=SUCCESS
CodeRabbit status=SUCCESS
review_threads=0
behind_by=0
changed_paths=1 docs-only

The merged audit file is byte-identical to the originally reviewed audit artifact:

AUDIT_BLOB=ddc062de054e3086f34c0906624b4683b545359d

No implementation authority is granted by this merge:

K3_R6_PLUS=NOT_AUTHORIZED
R4B_B2=NOT_AUTHORIZED
H6=NOT_AUTHORIZED
CODE_IMPORT=NOT_AUTHORIZED
NEW_DEPENDENCIES=NOT_AUTHORIZED
PERSISTENT_GRAPH_STORAGE=NOT_AUTHORIZED
VECTOR_EMBEDDINGS=NOT_AUTHORIZED
MODEL_DERIVED_GRAPH_EDGES=NOT_AUTHORIZED
K2_AUTHORITY_CHANGE=NO

No graph implementation slice or R4B-B2 work was started.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant