# CISG PoC v0.1 — RepoLumen code-induced semantic graph experiment

## Status

**Result: feasible at the tested static-analysis layer.**

This experiment tests whether a repository can be mechanically transformed from source-text organization into a typed graph whose nodes and edges are induced by implementation evidence rather than by a hand-written architecture diagram.

The name used here is:

**CISG — Code-Induced Semantic Graph（程式碼誘導語義圖）**

The distinction is intentional:

```text
Architecture graph: design/author description -> graph
CISG:              implemented code -> mechanically extracted graph
Runtime graph:      observed execution -> graph
```

**作者：** Neo.K  
**機構：** EveMissLab／一言諾科技有限公司  
**日期：** 2026-10-08（整理日期；原稿未標註日期）  
**版本：** v0.1  

## Evidence boundary

The strict evidence set contains **7 real RepoLumen Python files** at Git commit:

`008af74574b2ac6468970f76262cf23410aad4e8`

All seven local source copies were validated by recomputing Git blob SHA-1 and comparing with the GitHub blob SHA. Result:

**7/7 exact byte-level matches.**

This report deliberately does **not** claim full-repository coverage. It is a verified core slice used to test the representation and detector before scaling to the whole repository.

## CISG representation

The current graph uses typed nodes:

- file
- class / function / method
- control node (branch, loop, try, with, match)
- state node (observed attribute mutation target)
- effect node (conservative keyword-derived hint)
- boundary module / boundary call

Typed edges:

- contains
- imports
- calls
- controls
- writes_state
- effect

Every code-derived node/edge records:

- repository-relative path
- source line / line range where available
- Git commit identity
- whether a relation is local-resolved or remains a boundary

## Baseline result

```json
{
  "loaded_files": 7,
  "nodes": 182,
  "edges": 334,
  "node_types": {
    "file": 7,
    "function": 25,
    "class": 1,
    "method": 2,
    "boundary_module": 7,
    "control": 72,
    "boundary_call": 63,
    "effect": 3,
    "state": 2
  },
  "edge_types": {
    "contains": 28,
    "imports": 26,
    "controls": 72,
    "calls": 194,
    "effect": 11,
    "writes_state": 3
  },
  "resolved_local_calls": 34,
  "boundary_calls": 160,
  "capability_counts": {
    "architecture": 7,
    "execution": 8,
    "grounding": 2,
    "validation_bounds": 6,
    "orchestration": 1,
    "history": 3,
    "core_utility": 1,
    "change_analysis": 7
  },
  "import_cycles": 0,
  "call_cycles": 0
}
```

Key observations:

- **7 exact upstream files** were parsed.
- The slice became **182 typed nodes** and **334 typed edges**.
- **34 calls** were resolved to functions inside the loaded graph.
- **160 calls** were intentionally retained as unresolved/external boundaries instead of fabricated local semantics.
- No module-import cycle or resolved local call cycle was found in the baseline slice.
- Baseline anomaly output contains only informational hotspot classes (`high_call_fanout`, `boundary_heavy`); these are not asserted as defects.

## Cross-module relations recovered directly from code

- `repo_semantic/grounding.py::build_grounding_catalog` -> `repo_semantic/architecture_reconstruction.py::reconstruct_architecture` (source line 28)
- `repo_semantic/grounding.py::build_provider_request` -> `repo_semantic/architecture_reconstruction.py::reconstruct_architecture` (source line 138)
- `repo_semantic/historical_timeline.py::build_historical_timeline` -> `repo_semantic/incremental.py::diff_file_fingerprints` (source line 44)
- `repo_semantic/historical_timeline.py::build_historical_timeline` -> `repo_semantic/semantic_diff.py::build_semantic_diff` (source line 45)


These are not relationships copied from README prose; they come from import/call syntax and symbol resolution.

## Deterministic capability motifs

The first classifier is intentionally non-LLM. It uses path/symbol/call vocabulary to assign conservative motif labels. Current counts:

```json
{
  "architecture": 7,
  "execution": 8,
  "grounding": 2,
  "validation_bounds": 6,
  "orchestration": 1,
  "history": 3,
  "core_utility": 1,
  "change_analysis": 7
}
```

This is only a coarse first layer. In a mature system, motif classification should be treated as an inference layer with confidence/provenance, not as canonical semantics.

## Mutation validation: can the same graph engine find basic bug forms?

A separate copy of the exact slice was modified with four known fixtures. They are **not** RepoLumen upstream defects:

1. mutable default argument;
2. statement after unconditional `return`;
3. bare `except:`;
4. deliberate module import cycle.

The detector found all four:

```json
{
  "mutable_default": 1,
  "unreachable_statement": 1,
  "bare_except": 1,
  "module_import_cycle": 1
}
```

Therefore, the same repository-to-graph compiler can serve both representation and rule-based structural defect detection. The graph is not merely a visualization product.

## What this says about a program base space

The experiment does **not** prove a universal program ontology. It does demonstrate a practical factorization:

```text
source syntax
  -> parser/AST evidence
  -> typed semantic relations
  -> CISG
  -> graph algorithms / defect rules / capability motifs / higher projections
```

The important point is that the graph can discard part of the original textual organization while retaining operationally useful structure: containment, calls, control, state mutation hints, effect boundaries, and provenance.

A useful working distinction is:

```text
P*        = underlying program semantic object / program base-space state
C_L       = source projection in language L
rho(C_L)  = reconstructed code-induced semantic graph
```

with:

```text
rho(C_L) = P_hat
P_hat approximates only the observable/recoverable part of P*
```

This avoids the false claim that static analysis can recover author intent or complete runtime truth.

## Why this is different from an architecture graph

An architecture diagram is usually a declared model. CISG is an evidence-derived model. The comparison itself becomes analyzable:

```text
G_intent  <->  G_CISG  <->  G_runtime
```

Potential discrepancy classes:

- intent/code mismatch;
- code/runtime mismatch;
- internal structural anomaly inside CISG;
- historical topology drift across revisions.

## Next technical step

The strongest next experiment is not prettier visualization. It is to extend the canonical graph with:

- SSA/data-flow nodes;
- alias and memory/state regions;
- exception flow;
- type/effect constraints;
- runtime trace overlay;
- cross-language normalization.

At that point we can test whether different source projections converge toward the same normalized subgraph.

## Files in this bundle

- `cisg_analyzer.py` — deterministic PoC compiler/anomaly engine
- `repolumen_slice/` — exact SHA-validated RepoLumen source evidence used by the experiment
- `output/cisg.json` — canonical JSON graph
- `output/cisg.graphml` — graph exchange form
- `output/cisg.svg` — code-derived graph visualization
- `output/capability_graph.svg` — coarse functional motif graph
- `output/anomalies.json` — baseline anomaly/hotspot output
- `output/source_integrity.json` — Git blob SHA validation
- `mutation_slice/` — deliberately corrupted validation copy
- `mutation_output/` — mutation-test graph/results
- `tests/test_cisg.py` — reproducible checks