A local, file-based toolchain for source normalization and structured graphs with evidence attached. Spec 1.1 adds precise locators, stable claims, explicit inference boundaries, safe merging, and deterministic offline artifacts while keeping Spec 1.0 inputs valid. Semantic Segment-to-Graph creation remains an external agent or compiler responsibility.
The repository implements normalization and deterministic post-compilation stages. Steps 02–04 describe the contract an external semantic graph producer must satisfy; the local runner does not invoke a model or apply a compiler profile. The source adapter and runner are separate tools, not an automatic end-to-end handoff.
The .knowledge.json graph is authoritative. Deterministic tools can derive a
human-readable Markdown view and additional offline artifacts without changing the source graph.
## Evidence
### `evidence-alpha-beta`
- Source: `source-1`
- Support: `supports`
- Attribution basis: `source_explicit`
- Review status: `reviewed`
**Selector:**
{
"type": "TextQuoteSelector",
"exact": "Alpha enables Beta in the German deployment profile.",
"prefix": "The guide states: ",
"suffix": " Two deployments were observed."
}
**Excerpt:**
"Alpha enables Beta in the German deployment profile."
{
// selected fields from the canonical graph
"@context": {
"@vocab": "https://schema.org/",
"kd": "https://knowledge-distiller.dev/v4/"
},
"metadata": {
"distiller_spec_version": "1.1",
"conformance_score": 100,
"sources": [{ "id": "source-1",
"file": "deployment-guide.txt",
"content_sha256": "aaaa…" }]
},
"evidence": [{
"id": "evidence-alpha-beta",
"source": "source-1",
"selector": {
"type": "TextQuoteSelector",
"exact": "Alpha enables Beta…"
},
"support": "supports"
}],
"nodes": [{
"id": "alpha",
"resource": "urn:kd:concept:alpha",
"statements": ["Alpha enables Beta… [1]"],
"evidence": ["evidence-alpha-beta"],
"claim_ids": ["claim-alpha-enables-beta"]
}],
"claims": [{
"id": "claim-alpha-enables-beta",
"node": "alpha",
"origin": "source_stated",
"evidence": ["evidence-alpha-beta"],
"review_status": "reviewed"
}]
}
The canonical graph follows a versioned specification enforced by code. Validation measures format conformance, not semantic truth; derived artifacts are regenerated from the graph, and Spec 1.0 files remain valid inputs.
SPEC.md and the JSON Schema define producer rules, compatibility, references, and versioning. The validator reports a reproducible conformance_score and states that semantic accuracy was not evaluated.origin, short derivation summaries, and review status inspectable.resource, then ID, unions compatible payloads, and never silently overwrites them. Contradictions fail or become explicit fact conflicts; every successful CLI merge archives the prior bytes and writes JSON plus Markdown diffs..knowledge.html provides search, zoom, pan, drag, cluster focus, backlinks, and supersession views through safe DOM rendering—with no CDN or third-party runtime.
Source dates, validity intervals, and distillation dates keep time claims explicit.
These fields do not decide whether two values agree: distinct facts remain distinct,
and a reviewed fact_conflict can link a tension or supersession.
| Layer | Fields | Purpose |
|---|---|---|
| Source | source_date, source_period | When was the knowledge published? |
| Validity | valid_from, valid_until | When does this information apply? |
| Distillation | metadata.distillation_date | When was the extraction performed? |
ISO 8601 with flexible granularity: exact date, quarter, fiscal year, or interval
// Both payloads are retained "facts": [{ "id": "deployments-source", "value": "2", "temporal": { "source_period": "2026-Q3", "temporal_confidence": "explicit" }, "evidence": ["evidence-alpha-beta"] }, { "id": "deployments-review", "value": "3", "origin": "human_added" }], // The disagreement is explicit "fact_conflicts": [{ "id": "deployment-count", "facts": ["deployments-source", "deployments-review"], "relation": "tension", "reason": "Different retained counts" }]
build_exports.py emits deterministic Neo4j 5 Cypher, KD-CTXT/1, and Obsidian/JSON Canvas files while preserving source graph payloads in the target representation.--token-file; CORS and arbitrary command execution remain disabled.Eight relationship types define the compatible edge vocabulary. Each edge carries a type, numeric weight, and confidence rating; Spec 1.1 can also attach evidence, origin, derivation, time, and spatial roles.
| Type | Meaning | Symbol |
|---|---|---|
| uses | Dependency | → |
| enables | Causality | → |
| based-on | Foundation | → |
| part-of | Composition | → |
| tension | Trade-off / Contradiction | ↔ |
| replaces | Supersession | → |
| extends | Extension | → |
| example-of | Instantiation | → |
// Evidence locates support; it does not assert truth "evidence": [{ "id": "evidence-1", "source": "source-1", "selector": { "type": "TextQuoteSelector", "exact": "Located source text" }, "support": "supports" }], // Inference boundaries are explicit and reviewable "claims": [{ "id": "claim-1", "node": "concept-a", "statement": "Conservative synthesis [1]", "confidence": "medium", "origin": "model_inferred", "evidence": ["evidence-1"], "derivation": { "kind": "model_inferred", "activity": "profile-synthesis-v1", "inputs": ["evidence:evidence-1"], "summary": "Short transformation summary", "review_status": "unreviewed" } }]
.knowledge.md + .knowledge.json.
Embedding-ready clean-text chunks. JSON-LD with schema.org context.
Local paths only. PDF/OCR, images, audio/video, PPTX/XLSX, URLs, macros, encrypted files, unknown binaries, unsafe archives, and invalid UTF-8 are rejected rather than guessed.
Clone the repository, validate the shipped Spec 1.1 fixture, then derive only the artifacts you need. Unsupported inputs and unsafe paths fail explicitly.