# Single upload doc

- generated_at: 2026-06-12T18:33:36.001468
- output_format: text
- volumes: 2



===== BEGIN VOLUME Kristal_20260612_183335_01_kristal-framework.txt :: FOLDER: kristal-framework =====
==== VOLUME META ====
generated_at: 2026-06-12T18:33:35.978764
title: FOLDER: kristal-framework
root_dir: C:\mycode\Kristal
file_count: 77
total_size_mb: 1.4903
home: 00_START_HERE.instructions.md
next_volume: Kristal_20260612_183335_02_kristal-framework.wiki.txt
prev_title: 
next_title: kristal-framework.wiki
short_title: kristal-framework

==== FILE_INDEX ====
ENTRY id=ae8b2d0d5002 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/conformance-and-alignment.md" kind=markdown size=32739 lines=1261 line_ref=1-1261 chunks=4 chunk_refs=1-350,351-700,701-1050,1051-1261 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=2ea4f6113e51 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/ecosystem-integration.md" kind=markdown size=21246 lines=455 line_ref=1-455 chunks=2 chunk_refs=1-350,351-455 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=32e3af149365 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/plural-validation-and-federated-authority.md" kind=markdown size=24526 lines=983 line_ref=1-983 chunks=3 chunk_refs=1-350,351-700,701-983 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=30a0f5f98f5d path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/sharding-and-federation.md" kind=markdown size=23593 lines=879 line_ref=1-879 chunks=3 chunk_refs=1-350,351-700,701-879 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=d136e9cb43cb path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/validation-certainty-and-authority.md" kind=markdown size=32464 lines=1230 line_ref=1-1230 chunks=4 chunk_refs=1-350,351-700,701-1050,1051-1230 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=2f07d967def4 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/vision-and-scope.md" kind=markdown size=14625 lines=273 line_ref=1-273 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=d27d8f21ccf7 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/what-is-kristal-v5.md" kind=markdown size=20089 lines=767 line_ref=1-767 chunks=3 chunk_refs=1-350,351-700,701-767 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=cc1ff1f56b82 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/assertion-status-and-certainty.md" kind=markdown size=24555 lines=950 line_ref=1-950 chunks=3 chunk_refs=1-350,351-700,701-950 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=dd81676442c2 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/authority-recognition.md" kind=markdown size=33494 lines=1545 line_ref=1-1545 chunks=5 chunk_refs=1-350,351-700,701-1050,1051-1400,1401-1545 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=9bb118d6c160 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/ids-canonicalization-hashing.md" kind=markdown size=18810 lines=515 line_ref=1-515 chunks=2 chunk_refs=1-350,351-515 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=8f0c8c114e55 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/kristal-v5-core-spec.md" kind=markdown size=38531 lines=1359 line_ref=1-1359 chunks=4 chunk_refs=1-350,351-700,701-1050,1051-1359 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=493098d308ac path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/signatures-trust.md" kind=markdown size=25448 lines=624 line_ref=1-624 chunks=2 chunk_refs=1-350,351-624 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=03b159b0e78e path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/structured-epistemic-state.md" kind=markdown size=27482 lines=1258 line_ref=1-1258 chunks=4 chunk_refs=1-350,351-700,701-1050,1051-1258 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=5f549afd519e path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/assertion-status.schema.json" kind=source size=20099 lines=853 line_ref=1-853 chunks=3 chunk_refs=1-350,351-700,701-853 symbols=0 imports=0 summary="Source file."
ENTRY id=c2217a68a45d path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/authority-recognition.schema.json" kind=source size=22869 lines=944 line_ref=1-944 chunks=3 chunk_refs=1-350,351-700,701-944 symbols=0 imports=0 summary="Source file."
ENTRY id=89c9703edda5 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/authority-registry.schema.json" kind=source size=21403 lines=748 line_ref=1-748 chunks=3 chunk_refs=1-350,351-700,701-748 symbols=0 imports=0 summary="Source file."
ENTRY id=b04719b54c98 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/claim-ir.schema.json" kind=source size=26034 lines=1119 line_ref=1-1119 chunks=4 chunk_refs=1-350,351-700,701-1050,1051-1119 symbols=0 imports=0 summary="Source file."
ENTRY id=70c8f4ea4c12 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/exchange-federation-manifest.schema.json" kind=source size=14823 lines=756 line_ref=1-756 chunks=3 chunk_refs=1-350,351-700,701-756 symbols=0 imports=0 summary="Source file."
ENTRY id=caf71ff7fef4 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/exchange-manifest.schema.json" kind=source size=30055 lines=1107 line_ref=1-1107 chunks=4 chunk_refs=1-350,351-700,701-1050,1051-1107 symbols=0 imports=0 summary="Source file."
ENTRY id=d3715886bd60 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/exchange-shard-manifest.schema.json" kind=source size=19944 lines=1084 line_ref=1-1084 chunks=4 chunk_refs=1-350,351-700,701-1050,1051-1084 symbols=0 imports=0 summary="Source file."
ENTRY id=b2f82861c760 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/reader-policy.schema.json" kind=source size=18593 lines=1207 line_ref=1-1207 chunks=4 chunk_refs=1-350,351-700,701-1050,1051-1207 symbols=0 imports=0 summary="Source file."
ENTRY id=b6dfc4679611 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/resolved-claim-ir.schema.json" kind=source size=23628 lines=512 line_ref=1-512 chunks=2 chunk_refs=1-350,351-512 symbols=0 imports=0 summary="Source file."
ENTRY id=4905af33cbbc path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/revocations.schema.json" kind=source size=25030 lines=1025 line_ref=1-1025 chunks=3 chunk_refs=1-350,351-700,701-1025 symbols=0 imports=0 summary="Source file."
ENTRY id=95d2a3ba4b79 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/runtime-pack-manifest.schema.json" kind=source size=23383 lines=844 line_ref=1-844 chunks=3 chunk_refs=1-350,351-700,701-844 symbols=0 imports=0 summary="Source file."
ENTRY id=d9f3f19790f7 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/structured-epistemic-state.schema.json" kind=source size=39124 lines=1621 line_ref=1-1621 chunks=5 chunk_refs=1-350,351-700,701-1050,1051-1400,1401-1621 symbols=0 imports=0 summary="Source file."
ENTRY id=bf4d6901a2ac path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/validation-report.schema.json" kind=source size=30778 lines=1340 line_ref=1-1340 chunks=4 chunk_refs=1-350,351-700,701-1050,1051-1340 symbols=0 imports=0 summary="Source file."
ENTRY id=9acf5c7e9b29 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/03-reproducibility/allowed-runtime-pack-policies.md" kind=markdown size=18218 lines=558 line_ref=1-558 chunks=2 chunk_refs=1-350,351-558 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=57fcef1acfc5 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/03-reproducibility/deterministic-build-rules.md" kind=markdown size=25449 lines=594 line_ref=1-594 chunks=2 chunk_refs=1-350,351-594 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=fe6a832e3f34 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/03-reproducibility/reproducibility-acceptance-tests.md" kind=markdown size=7926 lines=262 line_ref=1-262 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=35295fac5daa path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/03-reproducibility/subset-recipes.md" kind=markdown size=25853 lines=1009 line_ref=1-1009 chunks=3 chunk_refs=1-350,351-700,701-1009 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=78e1d3d41ce2 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/04-query/query-contract.md" kind=markdown size=23831 lines=731 line_ref=1-731 chunks=3 chunk_refs=1-350,351-700,701-731 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=1b8c9e516342 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/04-query/reader-policy-profiles.md" kind=markdown size=36538 lines=1473 line_ref=1-1473 chunks=5 chunk_refs=1-350,351-700,701-1050,1051-1400,1401-1473 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=cd00e0008279 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-jsonld-export.md" kind=markdown size=22603 lines=866 line_ref=1-866 chunks=3 chunk_refs=1-350,351-700,701-866 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=b8048769c60b path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-provenance-nanopub-provo.md" kind=markdown size=22387 lines=744 line_ref=1-744 chunks=3 chunk_refs=1-350,351-700,701-744 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=230b305326ba path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-query-tpf-pagination.md" kind=markdown size=18110 lines=574 line_ref=1-574 chunks=2 chunk_refs=1-350,351-574 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=60641ec4b4e5 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-rdf-integrity-rdfc.md" kind=markdown size=15721 lines=370 line_ref=1-370 chunks=2 chunk_refs=1-350,351-370 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=af7ce63c7144 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-rdf-wdqs-export.md" kind=markdown size=22605 lines=808 line_ref=1-808 chunks=3 chunk_refs=1-350,351-700,701-808 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=9dc7e7feaf59 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-transparency-log.md" kind=markdown size=23955 lines=880 line_ref=1-880 chunks=3 chunk_refs=1-350,351-700,701-880 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=770dbd1a7a70 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-validation-shacl.md" kind=markdown size=15898 lines=462 line_ref=1-462 chunks=2 chunk_refs=1-350,351-462 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=fdeae3a1b827 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-validation-shex.md" kind=markdown size=17105 lines=644 line_ref=1-644 chunks=2 chunk_refs=1-350,351-644 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=1fd51b71ac91 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/06-integration/architect-rendering-contract.md" kind=markdown size=20627 lines=755 line_ref=1-755 chunks=3 chunk_refs=1-350,351-700,701-755 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=5ba5fe342ac1 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/06-integration/konnaxion-distribution-contract.md" kind=markdown size=27742 lines=846 line_ref=1-846 chunks=3 chunk_refs=1-350,351-700,701-846 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=ee2ed7c75587 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/06-integration/orgo-workflow-contract.md" kind=markdown size=27053 lines=982 line_ref=1-982 chunks=3 chunk_refs=1-350,351-700,701-982 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=25f49a775c7d path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/06-integration/sentient-resolution-contract.md" kind=markdown size=14750 lines=505 line_ref=1-505 chunks=2 chunk_refs=1-350,351-505 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=837756bce0f3 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/07-security/downgrade-rollback-policy.md" kind=markdown size=32736 lines=902 line_ref=1-902 chunks=3 chunk_refs=1-350,351-700,701-902 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=54d15f4aa834 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/07-security/key-management-and-trust-roots.md" kind=markdown size=24924 lines=725 line_ref=1-725 chunks=3 chunk_refs=1-350,351-700,701-725 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=8e02d62cc0eb path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/07-security/multi-tenancy-boundaries.md" kind=markdown size=22037 lines=575 line_ref=1-575 chunks=2 chunk_refs=1-350,351-575 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=704994204680 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/08-ops/failure-paths-and-resilience.md" kind=markdown size=21254 lines=764 line_ref=1-764 chunks=3 chunk_refs=1-350,351-700,701-764 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=dfe25adfac55 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/08-ops/logging-and-correlation-ids.md" kind=markdown size=22123 lines=854 line_ref=1-854 chunks=3 chunk_refs=1-350,351-700,701-854 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=21a1f45b6bf0 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/08-ops/operational-guidance-template.md" kind=markdown size=12058 lines=774 line_ref=1-774 chunks=3 chunk_refs=1-350,351-700,701-774 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=49f83ff2ffd2 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/08-ops/release-strategies.md" kind=markdown size=21787 lines=752 line_ref=1-752 chunks=3 chunk_refs=1-350,351-700,701-752 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=3a6bdc9be4ff path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/09-test-vectors/jcs/expected-hashes.txt" kind=source size=865 lines=15 line_ref=1-15 chunks=0 chunk_refs= symbols=0 imports=0 summary="Source file."
ENTRY id=75033c08f888 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/09-test-vectors/jcs/README.md" kind=markdown size=12211 lines=364 line_ref=1-364 chunks=2 chunk_refs=1-350,351-364 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=efba40925aac path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/09-test-vectors/jcs/vectors.json" kind=source size=7845 lines=190 line_ref=1-190 chunks=0 chunk_refs= symbols=0 imports=0 summary="Source file."
ENTRY id=fecddf7ace4a path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/09-test-vectors/rdfc/README.md" kind=markdown size=17560 lines=701 line_ref=1-701 chunks=3 chunk_refs=1-350,351-700,701-701 symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=d8e4595aa560 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/authority-registry.example.json" kind=source size=12954 lines=585 line_ref=1-585 chunks=2 chunk_refs=1-350,351-585 symbols=0 imports=0 summary="Source file."
ENTRY id=350b7b4382aa path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/claim-ir.example.json" kind=source size=8326 lines=324 line_ref=1-324 chunks=0 chunk_refs= symbols=0 imports=0 summary="Source file."
ENTRY id=31098e1b03fb path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/divergent-fork.example.json" kind=source size=27874 lines=756 line_ref=1-756 chunks=3 chunk_refs=1-350,351-700,701-756 symbols=0 imports=0 summary="Source file."
ENTRY id=8efa6d5199eb path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/exchange-federation-manifest.example.json" kind=source size=14422 lines=490 line_ref=1-490 chunks=2 chunk_refs=1-350,351-490 symbols=0 imports=0 summary="Source file."
ENTRY id=7f2b3ca4ae7d path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/exchange-shard-manifest.example.json" kind=source size=9228 lines=338 line_ref=1-338 chunks=0 chunk_refs= symbols=0 imports=0 summary="Source file."
ENTRY id=5617c713d86c path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/exchange.example.json" kind=source size=10076 lines=373 line_ref=1-373 chunks=2 chunk_refs=1-350,351-373 symbols=0 imports=0 summary="Source file."
ENTRY id=2b41f7fb1cb8 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/independent-research-evidence-bundle.example.json" kind=source size=27670 lines=959 line_ref=1-959 chunks=3 chunk_refs=1-350,351-700,701-959 symbols=0 imports=0 summary="Source file."
ENTRY id=bac8452dfd4e path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/medical-authority-recognition.example.json" kind=source size=13945 lines=367 line_ref=1-367 chunks=2 chunk_refs=1-350,351-367 symbols=0 imports=0 summary="Source file."
ENTRY id=7c6be3888293 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/mythology-corpus-kristal.example.json" kind=source size=27233 lines=725 line_ref=1-725 chunks=3 chunk_refs=1-350,351-700,701-725 symbols=0 imports=0 summary="Source file."
ENTRY id=969615b07759 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/plural-authority-federation.example.json" kind=source size=20560 lines=748 line_ref=1-748 chunks=3 chunk_refs=1-350,351-700,701-748 symbols=0 imports=0 summary="Source file."
ENTRY id=e5d011fb9e36 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/publisher-declared-system-kristal.example.json" kind=source size=38766 lines=1012 line_ref=1-1012 chunks=3 chunk_refs=1-350,351-700,701-1012 symbols=0 imports=0 summary="Source file."
ENTRY id=6862843bf96a path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/reader-policy-validated-only.example.json" kind=source size=10032 lines=381 line_ref=1-381 chunks=2 chunk_refs=1-350,351-381 symbols=0 imports=0 summary="Source file."
ENTRY id=bcd3187f29bc path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/resolved-claim-ir.example.json" kind=source size=9945 lines=405 line_ref=1-405 chunks=2 chunk_refs=1-350,351-405 symbols=0 imports=0 summary="Source file."
ENTRY id=4d99cd26e183 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/revocations.example.json" kind=source size=3753 lines=123 line_ref=1-123 chunks=0 chunk_refs= symbols=0 imports=0 summary="Source file."
ENTRY id=bff023f99da2 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/runtime-pack-manifest.example.json" kind=source size=6976 lines=231 line_ref=1-231 chunks=0 chunk_refs= symbols=0 imports=0 summary="Source file."
ENTRY id=f92658fc8d71 path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/structured-epistemic-state.example.json" kind=source size=28072 lines=1005 line_ref=1-1005 chunks=3 chunk_refs=1-350,351-700,701-1005 symbols=0 imports=0 summary="Source file."
ENTRY id=9b064813b4da path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/validation-report.example.json" kind=source size=13570 lines=450 line_ref=1-450 chunks=2 chunk_refs=1-350,351-450 symbols=0 imports=0 summary="Source file."
ENTRY id=a5ff2b228c2b path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/wikidata-seed-kristal.example.json" kind=source size=26769 lines=962 line_ref=1-962 chunks=3 chunk_refs=1-350,351-700,701-962 symbols=0 imports=0 summary="Source file."
ENTRY id=180434040cf8 path="kristal-framework/GitSink.bat" kind=source size=781 lines=33 line_ref=1-33 chunks=0 chunk_refs= symbols=0 imports=0 summary="Source file."
ENTRY id=c793b5606fb7 path="kristal-framework/LICENSE" kind=source size=694 lines=14 line_ref=1-14 chunks=0 chunk_refs= symbols=0 imports=0 summary="Source file."
ENTRY id=c462e3498d96 path="kristal-framework/mkdocs.yml" kind=source size=1817 lines=64 line_ref=1-64 chunks=0 chunk_refs= symbols=0 imports=0 summary="Source file."
ENTRY id=e81fe850384f path="kristal-framework/README.md" kind=markdown size=14111 lines=375 line_ref=1-375 chunks=2 chunk_refs=1-350,351-375 symbols=0 imports=0 summary="Markdown documentation."

==== FILES ====

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/conformance-and-alignment.md"
id=ae8b2d0d5002
kind=markdown
size=32739
lines=1261
line_ref=1-1261
chunks=4
chunk_refs=1-350,351-700,701-1050,1051-1261
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=ae8b2d0d5002:1-350
start=1
end=350
----
# Conformance and Alignment (Kristal v5)

## Status

Draft — normative alignment guide for Kristal v5 documentation, schemas, examples, profiles, manifests, and implementation contracts.

## Purpose

This document defines the cross-file alignment rules for Kristal v5.

Its purpose is to keep the Kristal v5 specification internally consistent across:

* overview documents;
* core specification documents;
* JSON Schemas;
* reproducibility rules;
* query contracts;
* standardized profiles;
* integration contracts;
* security guidance;
* operational guidance;
* examples and test vectors.

Kristal v5 is a deterministic, portable epistemic artifact system.

It allows hypotheses, claims, references, myths, fictional corpora, institutional records, research submissions, technical declarations, disputed positions, and validated reference material to coexist without being confused.

The core conformance principle is:

> A Kristal may contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.
> A Kristal must not present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.

This document defines the alignment requirements that make that principle enforceable.

---

## Normative keywords

The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as normative requirements.

---

# 1. Global constants

All Kristal v5 documents, schemas, examples, profiles, and manifests MUST align with the following constants unless a profile explicitly declares a different versioned surface.

```text
SPEC_NAME = "Kristal v5"
SPEC_VERSION = "5.0"
DOC_ROOT = "kristal-docs-v5"
SCHEMA_BASE_URL = "https://kristal.org/schemas/v5/"
CANONICALIZATION_PROFILE = "kristal.v5:jcs-rfc8785"
CANONICALIZATION_VERSION = "1"
HASH_ALG = "sha256"
DEFAULT_SIGNATURE_ALG = "ed25519"
PRIMARY_LANGUAGE = "en"
```

Schema documents MUST use:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/<schema-name>.schema.json"
}
```

Artifacts and manifests MUST use:

```json
{
  "schema_version": "5.0"
}
```

Runtime Packs SHOULD use:

```json
{
  "runtime_pack_version": "5.0"
}
```

Exchange artifacts SHOULD use:

```json
{
  "exchange_version": "5.0"
}
```

---

# 2. Required conceptual separation

Kristal v5 conformance depends on keeping the following concepts separate:

```text
artifact existence
≠ artifact integrity
≠ assertion status
≠ certainty level
≠ validation status
≠ authority recognition
≠ reader visibility
≠ runtime activation
```

A Kristal artifact may be:

* well-formed;
* content-addressed;
* reproducible;
* signed;
* queryable;
* distributable;

while still containing assertions that are:

* hypothetical;
* uncertain;
* disputed;
* fiction-scoped;
* mythology-scoped;
* rejected by some authority channels;
* recognized only by a local authority;
* not visible under a strict reader policy.

Conformant implementations MUST preserve this separation.

---

# 3. Required vocabulary

The following terms SHOULD be used consistently across Kristal v5:

```text
Kristal
Structured Epistemic State
Working Artifact
Reference Artifact
Exchange
Runtime Pack
Shard
Federation Manifest
Authority Channel
Authority Registry
Validation Policy
Validation Decision
Authority Recognition
Recognition Scope
Certainty Level
Assertion Status
Reader Policy
Transparency Log
```

## 3.1 Terms to avoid

The following terms MUST NOT be used as normative Kristal v5 status labels:

```text
canonical truth
truth object
canonical artifact
canonical status
source of truth
truth-plane
promotion
promoted
fail-safe
```

The following terms SHOULD NOT be used in public-facing or conceptual v5 documentation:

```text
fail-closed
no compile on fail
hard truth gate
single truth authority
universal truth authority
```

Exception: `canonicalization` is allowed because it refers to a stable byte representation for hashing, not to truth authority.

## 3.2 Replacement terms

Use the following replacements:

```text
canonical truth          -> recognized reference / validated reference / trusted-for-scope reference
truth object             -> structured reference artifact
canonical artifact       -> reference artifact
canonical status         -> recognized status / reference status
source of truth          -> reference source / authority-recognized source
promotion                -> recognition / validation decision / reference acceptance
promoted                 -> recognized / accepted / reference-approved
fail-closed              -> required verification / integrity enforcement / activation requirements
```

---

# 4. Artifact classes

Kristal v5 documents and schemas SHOULD use the following artifact type vocabulary.

```text
structured_epistemic_state
working_exchange
reference_exchange
runtime_pack
exchange_shard_manifest
exchange_federation_manifest
authority_registry
authority_recognition
validation_decision
validation_report
review_bundle
revocations
reader_policy
transparency_log_entry
```

The following artifact types MUST NOT be introduced in v5 schemas or examples:

```text
canonical_exchange
canonical_artifact
truth_artifact
```

---

# 5. Artifact status

Kristal v5 uses `artifact_status` for the lifecycle status of artifacts.

Allowed values:

```text
draft
working
under_review
recognized
reference
deprecated
superseded
revoked
```

Rules:

* `working` means the artifact exists and may be inspected, reviewed, queried, distributed, or used under policy.
* `under_review` means the artifact is being evaluated by one or more validation or recognition processes.
* `recognized` means at least one declared authority channel recognizes the artifact under a declared scope and policy.
* `reference` means the artifact is stable enough to be used as a reference under a selected authority channel and reader policy.
* `deprecated` means the artifact remains historically inspectable but is no longer preferred.
* `superseded` means another artifact replaces it under a declared lineage relationship.
* `revoked` means the artifact must not be accepted under the affected trust, validation, or recognition policy.

`artifact_status` MUST NOT be used as a substitute for assertion-level validation.

---

# 6. Assertion status

Kristal v5 uses `assertion_status` for the epistemic state of an assertion.

Allowed values:

```text
hypothesis
claimed
sourced
disputed
reviewed
validated
rejected
retracted
superseded
```

Rules:

* An assertion may be valid as a hypothesis.
* An assertion may be valid as mythology, fiction, symbolic structure, or publisher declaration.
* `validated` MUST NOT be interpreted as universal truth.
* `validated` MUST be interpreted together with `validated_as`, `certainty_level`, `authority_channel`, `validation_policy`, and `scope`.

A conformant reader MUST NOT display `assertion_status = validated` without preserving the relevant scope and authority context when that context exists.

---

# 7. Certainty levels

Kristal v5 uses `certainty_level` for the strength of an assertion inside a declared scope.

Allowed values:

```text
unknown
speculative
low
medium
high
established
not_applicable
```

Rules:

* `not_applicable` SHOULD be used for fictional, mythological, symbolic, doctrinal, or publisher-declared material when physical-world certainty is not the relevant axis.
* `established` SHOULD be reserved for high-confidence reference material under a selected authority channel and validation policy.
* A reader policy MAY include only validated data while still allowing multiple certainty levels.
* A Runtime Pack MUST NOT remove certainty labels required by its declared reader policy or query contract.

---

# 8. Validation modes

Kristal v5 uses `validated_as` to specify what kind of status has been validated.

Allowed values:

```text
hypothesis
claim
sourced_claim
reviewed_claim
high_confidence_fact
institutional_reference
publisher_declaration
technical_specification
legal_or_policy_position
mythological_corpus
fictional_corpus
symbolic_model
disputed_position
rejected_claim
```

Rules:

* Validation answers: who accepts this status, under which policy, for which scope.
* Certainty answers: how strong the assertion is within that scope.
* Validation does not always imply high certainty.
* Validation does not imply universal recognition.
* Validation by one authority channel does not imply validation by another.

A conformant validation object MUST NOT use:
--- CHUNK END ---

--- CHUNK BEGIN ---
id=ae8b2d0d5002:351-700
start=351
end=700
----

```json
{ "validated": true }
```

as a complete validation representation.

It MUST instead declare, directly or by reference:

```text
validation_status
validated_as
certainty_level
authority_channel
validation_policy_ref
scope
```

---

# 9. Validation status

Allowed values for `validation_status`:

```text
not_evaluated
in_review
validated
conditionally_validated
disputed
rejected
revoked
```

Rules:

* `not_evaluated` is a valid state, not an error.
* `in_review` means evaluation is active or pending.
* `conditionally_validated` means acceptance depends on declared limits or requirements.
* `disputed` means one or more relevant authority channels or review processes contest the assertion or artifact.
* `rejected` means the target failed a validation decision under a declared authority channel and policy.
* `revoked` means a previous validation status is no longer accepted under the relevant authority channel and policy.

---

# 10. Authority recognition

Kristal v5 uses authority channels to represent scoped sources of recognition.

A conformant authority channel SHOULD include:

```text
authority_channel_id
name
authority_type
scope
trust_roots
validation_policies
recognition_policies
revocation_policy_ref
```

Allowed `authority_type` values:

```text
individual
community
association
research_collective
academic_institution
standards_body
company
government
intergovernmental_organization
ai_validator
hybrid_collective
```

Allowed `recognition_status` values:

```text
recognized
conditionally_recognized
under_review
disputed
rejected
deprecated
revoked
```

Rules:

* No authority channel has universal monopoly by default.
* Recognition is scoped.
* Authorities may recognize other authorities.
* Delegation MUST be explicit.
* Recognition by one authority channel MUST NOT be presented as recognition by another authority channel unless declared.

---

# 11. Scope

Kristal v5 uses `scope` to constrain meaning, authority, validation, recognition, and reader visibility.

Minimum shape:

```json
{
  "domain": "string"
}
```

Recommended shape:

```json
{
  "domain": "science",
  "subdomain": "climate",
  "jurisdiction": "global",
  "time_window": "2026",
  "tenant_id": "tenant:example",
  "environment": "prod",
  "language": "en"
}
```

Allowed `domain` values SHOULD include:

```text
general
wikidata
science
health
education
heritage
law
policy
technology
environment
culture
mythology
fiction
research
operations
civic
local_notes
```

Rules:

* `domain` is required.
* `subdomain` is optional but recommended for large corpora.
* `jurisdiction` SHOULD be used when legal, civic, regulatory, or governmental scope matters.
* `time_window` SHOULD be used when source validity changes over time.
* `tenant_id` SHOULD be used in multi-tenant deployments.
* `environment` SHOULD be used in deployment-specific artifacts.
* `language` SHOULD be used when language affects interpretation or reader presentation.

---

# 12. Reader policy

Reader policy controls visible material.

Allowed reader modes:

```text
reference_only
validated_only
high_certainty_only
research
creative
all_with_labels
custom
```

Rules:

* `reference_only` SHOULD include only material accepted by selected reference channels.
* `validated_only` SHOULD include only material satisfying the active validation policy.
* `high_certainty_only` SHOULD include only material at accepted high-certainty levels.
* `research` MAY include drafts, disputed claims, hypotheses, partial reviews, and lower-certainty material.
* `creative` MAY include fiction, mythological corpora, speculative models, symbolic models, and worldbuilding material.
* `all_with_labels` MAY expose broad material, but labels MUST remain visible.
* `custom` MUST declare the filters it applies.

A reader policy MUST NOT silently convert scoped validation into universal truth.

---

# 13. Structured Epistemic State

Kristal v5 uses Structured Epistemic State as the normative input unit for compiled epistemic artifacts.

Minimum shape:

```json
{
  "schema_version": "5.0",
  "artifact_type": "structured_epistemic_state",
  "state_id": "sha256:<hex>",
  "created_at": "RFC3339",
  "created_by": {},
  "scope": {},
  "source_refs": [],
  "derived_from": [],
  "merged_from": [],
  "supersedes": [],
  "assertions": [],
  "provenance": [],
  "review_refs": [],
  "policy_refs": [],
  "certainty_summary": {},
  "validation_summary": {},
  "extensions": {}
}
```

Rules:

* Structured Epistemic State is the v5 normative input surface.
* Claim-IR MAY be used as an extractor proposal profile.
* Claim-IR MUST NOT be the universal required input format for Kristal v5.
* A human expert, institution, dataset, or authority channel MAY produce Structured Epistemic State directly.

---

# 14. Claim-IR alignment

Claim-IR remains useful, but its role is narrower in Kristal v5.

Required role:

```text
Claim-IR = extractor proposal profile
```

Allowed pipeline:

```text
LLM / OCR / parser / scraper
-> Claim-IR
-> Structured Epistemic State
-> Working Artifact
```

Also allowed:

```text
human expert / institution / dataset
-> Structured Epistemic State
-> Working Artifact
```

Conformant documents MUST NOT state that Claim-IR is the only allowed proposal boundary.

Conformant documents MUST NOT state that failed validation universally blocks compilation.

---

# 15. Exchange alignment

Kristal v5 uses Exchange artifacts as structured, content-addressed references.

Exchange artifacts may be:

```text
working_exchange
reference_exchange
```

Rules:

* A `working_exchange` exists before or without reference recognition.
* A `reference_exchange` is recognized under one or more authority channels and reader policies.
* An Exchange MUST preserve provenance, source references, validation references, recognition references, and scope.
* An Exchange MUST NOT be described as a truth object.
* An Exchange MUST NOT be described as universally canonical.

Recommended fields:

```json
{
  "schema_version": "5.0",
  "artifact_type": "working_exchange",
  "exchange_version": "5.0",
  "kristal_id": "sha256:<hex>",
  "artifact_status": "working",
  "source_state_refs": [],
  "scope": {},
  "authority_recognition_refs": [],
  "validation_refs": [],
  "certainty_summary": {},
  "content_hash": {},
  "build": {},
  "signatures": [],
  "extensions": {}
}
```

---

# 16. Runtime Pack alignment

A Runtime Pack is a deployable offline package derived from an Exchange or shard set.

Rules:

* Runtime Packs MUST declare their source artifact status.
* Runtime Packs MUST preserve validation, certainty, authority, scope, provenance, and lineage labels required by their query contract or reader policy.
* Runtime Packs MAY materialize full source data or filtered reader-policy views.
* Filtered Runtime Packs MUST NOT present themselves as containing the full source artifact.
* Runtime Pack signatures prove package integrity, not universal truth.
* Runtime Pack activation is governed by activation policy, trust roots, signatures, revocation, downgrade policy, compatibility, and reader-policy requirements.

Recommended fields:

```json
{
  "schema_version": "5.0",
  "artifact_type": "runtime_pack_manifest",
  "runtime_pack_id": "sha256:<hex>",
  "runtime_pack_version": "5.0",
  "source_exchange_ref": {},
  "source_artifact_status": "working",
  "reader_policy_refs": [],
  "query_contract_ref": {},
  "integrity": {},
  "build": {},
  "signatures": [],
  "extensions": {}
}
```

---

# 17. Federation alignment

Federation composes Kristal shards without silently merging their authority, identity, validation, or certainty.

Rules:

* Federation preserves source identities.
* Federation does not rewrite shards.
* Federation composes references under explicit policy.
* Federation may expose disagreement.
* Federation MUST NOT silently merge conflicting claims.
* Federation MUST preserve authority-channel boundaries.
* Federation MUST preserve validation and certainty labels.
* Federation MUST expose or reference its composition policy.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=ae8b2d0d5002:701-1050
start=701
end=1050
----

Recommended composition policy fields:

```json
{
  "policy_id": "kristal.v5:composition-policy:default",
  "policy_version": "1",
  "overlap_strategy": "authority_precedence",
  "conflict_strategy": "preserve_disagreement",
  "default_visibility": "reader_policy",
  "ordering": "stable",
  "parameters": {}
}
```

Allowed `conflict_strategy` values:

```text
preserve_disagreement
authority_precedence
mark_disputed
exclude_conflict
require_reader_choice
```

Default:

```text
preserve_disagreement
```

---

# 18. Hashing and identity alignment

Kristal v5 uses content-addressed identity.

Rules:

* JSON hash targets MUST use RFC 8785 JSON Canonicalization Scheme under `kristal.v5:jcs-rfc8785`.
* The hash algorithm MUST be `sha256`.
* Hash values MUST be lowercase hexadecimal.
* Output ID fields MUST be excluded from their own hash targets.
* Signature fields MUST be excluded from content-addressed hash targets unless a profile explicitly defines a signature-bound derived hash.
* Attestation fields MUST be excluded from identity hash targets unless a profile explicitly defines otherwise.
* Timestamps MUST NOT affect content-addressed IDs unless they are part of the declared hashed material.
* Hash object fields MUST use `alg`, not `algo`.

Required hash object shape:

```json
{
  "alg": "sha256",
  "value": "<64 lowercase hex characters>"
}
```

---

# 19. Signature alignment

Kristal v5 signatures protect declared signing targets.

Rules:

* Baseline signature algorithm is `ed25519`.
* Compatibility algorithm `rsa-pss-sha256` MAY be supported by deployment policy.
* Signatures MUST declare `key_id`.
* Signatures MUST declare `alg`.
* Signatures MUST declare `payload_hash`.
* Signature verification MUST use the declared signing target.
* Signatures MUST be excluded from the signed content hash unless a profile explicitly defines a different signing target.
* A valid signature does not imply universal validation.
* A valid signature does not imply universal authority recognition.
* A valid signature does not turn a working artifact into a reference artifact.

Recommended signature object:

```json
{
  "sig_id": "sig:example",
  "key_id": "key:example",
  "alg": "ed25519",
  "payload_hash": {
    "alg": "sha256",
    "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "signature": "base64url-or-multibase-signature",
  "created_at": "2026-01-01T00:00:00Z"
}
```

---

# 20. Build record alignment

A v5-aware Build Record SHOULD distinguish:

```text
compile_status
validation_status
review_status
recognition_status
publication_status
activation_status
working_outputs[]
reference_outputs[]
reason_codes[]
```

Rules:

* Compilation may succeed before validation is complete.
* Validation may fail without invalidating the existence of the working artifact.
* Recognition is separate from validation.
* Publication is separate from recognition.
* Activation is separate from publication.
* A build record MUST NOT treat all successful compilation outputs as reference outputs.
* A build record MUST NOT treat rejected recognition as failed compilation.

Recommended shape:

```json
{
  "build_id": "build:example",
  "schema_version": "5.0",
  "compile_status": "succeeded",
  "validation_status": "in_review",
  "review_status": "pending",
  "recognition_status": "none",
  "publication_status": "not_published",
  "activation_status": "not_applicable",
  "working_outputs": [],
  "reference_outputs": [],
  "reason_codes": [],
  "created_at": "2026-01-01T00:00:00Z"
}
```

---

# 21. Reason codes

Reason codes SHOULD be stable, machine-readable strings.

Recommended values:

```text
schema_valid
schema_invalid
provenance_sufficient
provenance_insufficient
evidence_sufficient
evidence_insufficient
authority_recognized
authority_not_recognized
scope_mismatch
policy_satisfied
policy_failed
signature_valid
signature_invalid
hash_valid
hash_invalid
conflict_detected
disagreement_preserved
certainty_too_low_for_policy
rejected_by_authority_channel
revoked_by_authority_channel
unsupported_profile
unsupported_schema_version
unsupported_policy_value
unknown_authority_channel
reader_policy_excluded
```

---

# 22. Query and reader alignment

Queries MUST preserve Kristal v5 labels when the active query contract or reader policy requires them.

Queryable dimensions SHOULD include:

```text
artifact_status
assertion_status
validation_status
certainty_level
validated_as
authority_channel
recognition_status
scope.domain
scope.subdomain
reader_policy
include_disputed
include_fictional
include_mythological
```

Rules:

* Query profiles MUST use `kristal.v5:jcs-rfc8785` for query hashing when JCS is required.
* Pagination MUST use stable ordering.
* Filtered Runtime Packs MUST include filter identity in the pack identity or manifest identity surface as defined by the relevant profile.
* Query responses MUST NOT flatten scoped validation into universal truth.
* Reader policies MUST remain visible or retrievable.

---

# 23. Runtime activation alignment

Runtime activation is the process of making a Runtime Pack active for a channel, device, tenant, or environment.

Rules:

* Activation policy MUST be explicit.
* Activation MUST check required signatures, hashes, schema validity, compatibility, revocation policy, downgrade policy, and reader-policy requirements when those are declared.
* A candidate pack that does not satisfy the active policy MUST NOT become active for that policy.
* A rejected candidate MAY remain inspectable as inactive, diagnostic, or untrusted material.
* Activation MUST preserve source artifact status.
* Activation MUST NOT convert a working artifact into a reference artifact.

Preferred language:

```text
required verification
activation requirements
integrity enforcement
policy-bound activation
```

Avoid using activation language as a global epistemic claim.

---

# 24. Schema alignment requirements

All v5 schemas MUST follow these requirements:

1. `$id` MUST use `/schemas/v5/`.
2. `schema_version` MUST be `"5.0"`.
3. Titles SHOULD say `Kristal v5`.
4. Hash fields MUST use `alg`.
5. Hash values MUST use lowercase 64-character SHA-256 hex.
6. Signature fields MUST use `signatures`.
7. Signature payload hashes MUST use the common hash object shape.
8. Schema examples MUST validate against their schemas.
9. Schemas with `additionalProperties: false` MUST declare every field used in examples.
10. Registry identifiers MUST allow v5 content-addressed or registry-scoped IDs.
11. Schema text MUST distinguish artifact integrity from validation and recognition.
12. Schemas MUST NOT introduce unqualified `canonical` truth terminology.

---

# 25. Example alignment requirements

All examples in `10-examples/` MUST align with v5 vocabulary and schema rules.

Examples SHOULD include:

```text
structured-epistemic-state.example.json
plural-authority-federation.example.json
wikidata-seed-kristal.example.json
mythology-corpus-kristal.example.json
medical-authority-recognition.example.json
publisher-declared-system-kristal.example.json
independent-research-evidence-bundle.example.json
divergent-fork.example.json
reader-policy-validated-only.example.json
```

Rules:

* Examples MUST use `schema_version = "5.0"`.
* Examples MUST use v5 schema IDs where applicable.
* Examples MUST preserve labels.
* Examples MUST avoid universal truth claims.
* Examples MUST distinguish working artifacts from reference artifacts.
* Examples MUST distinguish validation from recognition.
* Examples MUST distinguish certainty from validation.
* Examples MUST show scope.
* Examples involving fiction or mythology MUST use `certainty_level = "not_applicable"` where physical-world certainty is not relevant.
* Examples involving disputed material MUST preserve disagreement.

---

# 26. Test vector alignment

Test vectors SHOULD cover:

* identity hash stability;
* exclusion of output ID fields from hash targets;
* exclusion of signatures from hash targets;
* signature verification;
* signature failure;
* hash failure;
* unsupported schema version;
* unsupported policy value;
* reader-policy filtering;
* authority-channel filtering;
* validation-status filtering;
* certainty-level filtering;
* federation conflict preservation;
* Runtime Pack filtered materialization;
* downgrade prevention;
* revocation handling.

Test vectors SHOULD include both positive and negative cases.

Negative cases SHOULD verify that nonconforming artifacts are not accepted under the requested policy, while still allowing diagnostic inspection where implementation policy permits.

---

# 27. File naming alignment

Kristal v5 file names SHOULD describe the current model directly.

Use:

```text
what-is-kristal-v5.md
vision-and-scope.md
ecosystem-integration.md
sharding-and-federation.md
plural-validation-and-federated-authority.md
validation-certainty-and-authority.md
conformance-and-alignment.md
kristal-v5-core-spec.md
structured-epistemic-state.md
assertion-status-and-certainty.md
authority-recognition.md
reader-policy-profiles.md
```

Do not use active v5 document names such as:

```text
v4-to-v5-summary.md
migration.md
upgrade.md
errata.md
```

The v5 documentation describes what Kristal v5 is, not how earlier drafts changed.

---

# 28. Component responsibility alignment

--- CHUNK END ---

--- CHUNK BEGIN ---
id=ae8b2d0d5002:1051-1261
start=1051
end=1261
----
Kristal v5 stack responsibilities SHOULD remain separated.

## 28.1 Kristal

Kristal owns:

* compiled epistemic artifacts;
* content-addressed identities;
* manifests;
* schemas;
* query contracts;
* assertion status;
* certainty metadata;
* authority recognition references;
* reproducibility rules.

## 28.2 Orgo

Orgo owns:

* workflow;
* review process;
* approvals;
* operational audit;
* routing;
* release records;
* lifecycle control.

## 28.3 Konnaxion

Konnaxion owns:

* distribution;
* reader surfaces;
* Runtime Pack activation;
* offline access;
* user-facing policy selection.

## 28.4 SenTient

SenTient owns or supports:

* resolution;
* disambiguation;
* normalization;
* extraction support;
* Claim-IR profile support.

## 28.5 Architect

Architect owns or supports:

* deterministic rendering;
* label-visible summaries;
* reader-policy-aware presentation;
* prevention of hidden authority laundering.

Architect MUST NOT hide validation, authority, certainty, or disputed-status labels when they are material to the active reader policy.

---

# 29. Public language alignment

Public-facing descriptions SHOULD use language such as:

```text
Kristal makes knowledge status explicit.
Kristal preserves disagreement without silent merging.
Kristal lets readers choose policy.
Kristal separates validation from certainty.
Kristal supports plural authority channels.
Kristal protects artifact integrity.
Kristal makes source, authority, and scope inspectable.
```

Public-facing descriptions SHOULD NOT imply that Kristal guarantees:

* zero erroneous data;
* a single universal truth;
* global expert consensus;
* universal validation;
* universal recognition;
* automatic institutional approval;
* maximum certainty.

---

# 30. Conformance classes

Kristal v5 implementations MAY claim conformance at different levels.

## 30.1 Schema conformant

An implementation is schema conformant if it:

* emits artifacts that validate against the relevant v5 schemas;
* uses v5 schema IDs;
* uses v5 schema versions;
* preserves required fields;
* rejects or marks unsupported schema versions.

## 30.2 Core artifact conformant

An implementation is core artifact conformant if it:

* implements v5 canonicalization and hashing rules;
* implements content-addressed identity rules;
* preserves artifact status;
* preserves assertion status and certainty labels;
* preserves validation and recognition references;
* distinguishes working and reference artifacts.

## 30.3 Runtime Pack conformant

An implementation is Runtime Pack conformant if it:

* emits Runtime Pack manifests with v5 policies;
* records required build-affecting policies;
* preserves source artifact status;
* supports declared query contracts;
* preserves labels required by reader policy;
* enforces declared activation requirements.

## 30.4 Federation conformant

An implementation is federation conformant if it:

* preserves shard identities;
* applies explicit composition policies;
* preserves disagreement;
* preserves authority-channel boundaries;
* exposes conflicts according to policy;
* avoids silent merging.

## 30.5 Authority conformant

An implementation is authority conformant if it:

* supports authority channels;
* supports scoped recognition;
* supports validation policies;
* supports revocation policy where declared;
* does not treat one authority’s recognition as universal.

## 30.6 Reader-policy conformant

An implementation is reader-policy conformant if it:

* supports declared reader modes;
* applies filters deterministically;
* exposes labels;
* does not hide scope or authority;
* clearly marks excluded or unavailable material when appropriate.

---

# 31. Nonconformance

An artifact, implementation, schema, example, or profile is nonconforming if it:

* uses v3 or v4 schema IDs in v5 files;
* uses `schema_version = "3.0"` or `"4.0"` in v5 examples unless explicitly modeling legacy interop;
* describes Exchange as a truth object;
* describes reference status as universal truth;
* uses Claim-IR as the universal required input;
* states that validation universally blocks compilation;
* collapses validation and certainty;
* collapses authority recognition and validation;
* hides scope;
* hides reader policy;
* silently merges conflicting authorities;
* omits required labels;
* uses `algo` instead of `alg`;
* includes signatures in content hash targets without a declared profile;
* allows timestamps to alter content-addressed IDs without declaring them as hashed material;
* uses fields in examples that are forbidden by `additionalProperties: false`;
* returns partial or misleading query results under a declared capability.

---

# 32. Summary

Kristal v5 conformance is not only schema validity.

A conformant Kristal v5 system preserves the distinctions that make plural, validated, uncertain, fictional, mythological, institutional, and scientific knowledge coexist without confusion.

The alignment rules are:

```text
Use v5 versions.
Use v5 schema IDs.
Preserve artifact identity.
Preserve labels.
Separate validation from certainty.
Separate recognition from validation.
Separate reader visibility from artifact existence.
Keep authority scoped.
Keep federation explicit.
Keep Runtime Pack activation policy-bound.
Use canonicalization only for stable hashing.
Do not turn scoped acceptance into universal truth.
```

The final invariant is:

> Integrity protects artifacts.
> Authority is plural.
> Recognition is scoped.
> Certainty is explicit.
> Readers choose policy.
> Federation preserves disagreement.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/ecosystem-integration.md"
id=2ea4f6113e51
kind=markdown
size=21246
lines=455
line_ref=1-455
chunks=2
chunk_refs=1-350,351-455
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=2ea4f6113e51:1-350
start=1
end=350
----
# Kristals in the Ecosystem: Konnaxion × Orgo × Architect × SenTient

## 1) What “Kristal” is in your stack

**Kristal is the portable, offline-usable epistemic artifact format of the kOA ecosystem.** It is not a document and not free text; it is a **compiled knowledge artifact** designed to be **Wikidata/Wikibase-aligned**, **traceable**, **AI-ready**, **queryable**, and **usable offline**.

A Kristal can contain claims, hypotheses, references, institutional records, technical declarations, mythological corpora, fictional structures, disputed positions, and high-confidence factual knowledge. The point is not that every Kristal is automatically true. The point is that its claims carry explicit structure: provenance, scope, authority channel, validation status, certainty level, lineage, and reader-policy visibility.

Kristal exists as a **standard + compilation model + exchange format + runtime pack**:

* **Structured Epistemic State**: the normative input unit for Kristal v5. It represents structured claims, evidence, uncertainty, provenance, scope, and status before they become portable artifacts.
* **Claim-IR**: an extractor proposal profile. Probabilistic extractors such as LLMs, classical extractors, OCR systems, and hybrids may emit Claim-IR, but Claim-IR is not the universal required input to Kristal.
* **Resolution (SenTient)**: maps surface forms to candidate QIDs/PIDs, normalizes values, and preserves unresolved ambiguity instead of forcing premature certainty.
* **Validation & Recognition**: scoped decisions made by declared authority channels under explicit validation policies. Validation does not always mean maximum certainty; it means accepted as something, by someone, for some scope, under some policy.
* **Kristal Exchange**: Wikibase-aligned, content-addressed structured reference artifact. It is the artifact you cite, inspect, compare, federate, and use as the source for runtime packs.
* **Kristal Runtime Pack**: derived, offline-usable indexed form optimized for constrained query and local access. It does not require SPARQL, a live network, or an LLM dependency.
* **Deterministic Rendering (Architect)**: renders query results into natural language or other user-facing outputs while preserving Kristal labels: authority, validation status, certainty, scope, and disagreement.

## 2) Landscape: where Kristals sit

**Kristals sit between messy reality and user-facing platforms + operational systems**, as the structured knowledge substrate that makes claims portable, inspectable, filterable, and reusable.

They are not meant to erase disagreement. They make disagreement legible.

**High-level flow: authoring → structuring → validation/recognition → distribution → use → feedback**

### A. Inputs

Inputs may include:

* documents;
* web pages;
* PDFs;
* datasets;
* emails or archives;
* institutional submissions;
* human expert drafts;
* research notes;
* cultural corpora;
* fictional or mythological material;
* optional hints, mappings, or source references.

### B. Knowledge compilation

The Kristal stack turns inputs into structured artifacts:

* input material or dataset;
* Structured Epistemic State;
* optional Claim-IR when extraction is probabilistic;
* SenTient resolution and normalization;
* validation decisions, authority recognition, review records, and provenance;
* Kristal Exchange;
* Runtime Pack.

Compilation and validation are distinct. A system may compile a working artifact before final recognition. Reader policies then decide which artifacts or assertions are visible in a given context.

### C. Consumers in the ecosystem

* **Konnaxion** consumes Kristals to power discovery, search, navigation, knowledge delivery, education, civic workflows, collective curation, and offline-oriented user experiences.
* **Orgo** consumes Kristals to turn knowledge into operational work, and produces operational signals that can trigger new Kristal builds, reviews, validations, or revisions.
* **Architect** consumes Kristal query results and produces deterministic multilingual text or other generated outputs while preserving labels and not laundering scoped validation into universal truth.
* **SenTient** is the reconciliation engine that bridges unstructured or ambiguous inputs into Wikidata/Wikibase-shaped identifiers and normalized values.

## 3) Clear role boundaries

### Kristal: the epistemic substrate

**Primary job:** produce portable, traceable, queryable, offline-usable knowledge artifacts with deterministic identity, provenance, status, and policy-aware semantics.

Kristal owns:

* structured epistemic states;
* exchange artifacts;
* runtime pack manifests;
* schemas;
* content-addressed identity;
* canonicalization for hashing;
* signatures and trust roots;
* assertion status;
* certainty metadata;
* authority recognition references;
* validation decision references;
* federation manifests;
* query contracts.

**Non-goals:**

* Kristal is not a workflow engine.
* Kristal is not a voting system.
* Kristal is not a user interface.
* Kristal is not a monopoly over truth.
* Kristal Runtime Packs do not need full SPARQL semantics; they intentionally constrain query execution to remain offline, predictable, and portable.

### SenTient: the resolver / reconciler

**Primary job:** convert ambiguity into ranked candidate identities and normalized values.

SenTient handles:

* surface-form detection;
* QID/PID candidate generation;
* semantic ranking;
* value normalization;
* ambiguity preservation;
* confidence signals;
* reconciliation warnings.

SenTient does not decide universal truth. It provides resolution support that downstream Kristal validation policies may use.

### Architect: the deterministic renderer

**Primary job:** transform Kristal query results into deterministic text or other user-facing outputs without changing the epistemic status of the underlying claims.

Architect must preserve:

* validation labels;
* authority labels;
* certainty labels;
* scope labels;
* disputed status;
* fictional, mythological, symbolic, or speculative mode when applicable.

Architect must not flatten scoped validation into universal truth.

### Konnaxion: the mass platform layer

**Primary job:** provide a unified multi-module platform with global navigation, search, content delivery, offline access, collective intelligence, and public-facing knowledge surfaces.

Konnaxion uses Kristals as:

* search primitives;
* offline knowledge payloads;
* educational references;
* debate references;
* civic-process references;
* curation targets;
* distribution units;
* user-selectable knowledge layers.

Konnaxion can expose different reader policies, such as validated-only, reference-only, research, creative, or all-with-labels.

### Orgo: the operating system layer

**Primary job:** ingest messy signals and turn them into structured work under operational constraints such as multi-tenancy, identity separation, auditability, offline sync, routing, approvals, and lifecycle management.

Orgo handles:

* cases;
* tasks;
* assignments;
* approvals;
* review workflows;
* validation requests;
* publication workflows;
* distribution status;
* operational audit logs;
* feedback loops;
* sync conflicts.

Orgo does not own the Kristal knowledge payload. It orchestrates the work around that payload.

## 4) The place of Kristals inside each product

### 4.1 Kristals inside Konnaxion

Konnaxion’s platform structure is ideal for Kristals because it already wants:

1. one global search/navigation layer across modules;
2. offline and low-bandwidth delivery modes;
3. weighted curation and expert review workflows;
4. versioned offline packages;
5. public-facing knowledge surfaces;
6. support for civic disagreement without silent merging.

**Concrete placement:**

* **Kristal Runtime Packs become offline knowledge payloads** distributed to devices, users, schools, organizations, regions, or communities.
* **Kristal Exchanges become auditable structured references** for knowledge items that Konnaxion modules can cite, compare, discuss, rank, or attach to civic processes.
* **Konnaxion reader policies decide what users see by default.** A user or institution may choose a strict view containing only selected authority channels and validated material, or a broader research/creative view that includes hypotheses, disputed material, mythology, fiction, or divergent forks with labels.
* **Ekoh/Konsensus can weight recognition, visibility, distribution priority, featured packs, recommended references, or curation status** without pretending that a vote alone decides physical-world truth.
* **Smart Vote and other civic mechanisms can refer to Kristals** as structured evidence or policy references while preserving the difference between claims, validation, authority, and certainty.

**What this unlocks on massive platforms:**

* a consistent knowledge primitive for feeds, search results, debate references, educational modules, and moderation/verification badges;
* offline access without relying on live endpoints;
* transparent disagreement between authority channels;
* user-selectable trust and certainty layers;
* structured feedback that can become future Kristal work.

### 4.2 Kristals inside Orgo

Orgo is about converting messy signals into structured work and doing it safely at scale: multi-tenant, identity-aware, auditable, and offline-capable.

**Concrete placement:**

* **Orgo becomes the operational control plane for Kristal production, review, validation, recognition, publication, and distribution.**
* When Orgo ingests signals such as email, HTTP submissions, offline imports, documents, or datasets, it can trigger “needs-a-kristal” workflows.
* Orgo can create Cases and Tasks for structuring, extraction, reconciliation, review, validation, authority recognition, release, revocation, and update.
* Orgo’s offline nodes and sync sessions can distribute Kristal packs to constrained environments such as schools, field devices, regulated deployments, local communities, or disaster-response contexts.
* Orgo feedback can trigger new Kristal versions, new authority decisions, new review bundles, or new divergent forks.

**Orgo ↔ Kristal division of labor:**

* Orgo stores assignments, cases, approvals, review workflows, operational audit logs, distribution status, sync conflicts, and lifecycle events.
* Kristal stores the structured epistemic payload: assertions, provenance, scopes, validation decisions, authority recognitions, exchange artifacts, runtime packs, and query contracts.

### 4.3 Kristals inside SenTient

SenTient provides the resolution layer that maps ambiguity into structured identifiers and normalized values.

Kristal relies on SenTient where inputs contain unresolved ambiguity:

* ambiguous names;
* entity references;
* property references;
* dates;
* units;
* multilingual labels;
* partial statements;
* conflicting identifiers;
* uncertain mappings.

SenTient’s funnel architecture operationalizes this at scale:

1. fast candidate spotting;
2. semantic scoring;
3. ranking;
4. QA / judging;
5. unresolved ambiguity preservation.

**Concrete placement:**

* SenTient acts as the resolver service for Claim-IR and other structured input profiles.
* SenTient outputs ranked candidates, normalized values, warnings, and unresolved ambiguity records.
* Those outputs feed Kristal validation, review, and reference-building processes.
* SenTient does not force certainty when evidence is insufficient.
* SenTient does not replace authority recognition. It supports it.

### 4.4 Kristals inside Architect

Architect renders Kristal query results into human-facing output.

Architect is already designed as a build pipeline with clear stages:

* filesystem;
* indexer;
* JSON;
* orchestrator/factory;
* compiled artifacts;
* worker/API.

Kristal gives Architect a structured epistemic source to render from.

**Concrete placement:**

* Architect consumes queries over Kristal Runtime Packs or Exchange-derived query results.
* Architect produces human-readable articles, snippets, multilingual variants, structured educational pages, summaries, civic explanations, and interface text.
* Architect must preserve claim status, validation status, certainty level, authority channel, and scope.
* Architect can render different reader-policy modes:

  * reference-only;
  * validated-only;
  * high-certainty-only;
  * research;
  * creative;
  * all-with-labels;
  * custom authority channels.

Architect’s deterministic ethos aligns with Kristal’s model: preserve uncertainty, preserve labels, be deterministic in rendering, and do not introduce unsupported facts.

## 5) The core operating loop

### Loop 1: Reality → Kristal

1. **Signal enters** through Konnaxion submission, Orgo case, email/import/API, web/PDF ingestion, dataset import, institutional submission, or human-authored draft.
2. **Structured Epistemic State is produced** with claims, status, scope, provenance, evidence, uncertainty, and lineage.
3. **Claim-IR may be used** when the source is probabilistic extraction, but it is not mandatory for all inputs.
4. **SenTient resolves** surfaces to ranked QIDs/PIDs and normalized values when resolution is needed.
5. **A working Kristal Exchange is compiled** as a structured, content-addressed artifact.
6. **Review, validation, and authority recognition occur** according to explicit policies.
7. **Some artifacts or assertions become recognized references** under one or more authority channels.
8. **Runtime Packs are compiled** for offline access and constrained query execution.

### Loop 2: Kristal → People

9. **Konnaxion distributes** runtime packs and reference surfaces through versioned packages, PWA/offline mode, low-bandwidth UX, and platform search/navigation.
10. **Architect renders** user-facing text from Kristal query results while preserving labels and policies.
11. **Orgo operationalizes** gaps, verification requests, publication processes, distribution issues, and review needs.

### Loop 3: People → System feedback

12. **Feedback becomes structured signals** through Orgo cases, Konnaxion votes, curation signals, expert reviews, institutional updates, user reports, and conflicting submissions.
13. **Feedback can trigger new Kristals**, updated authority decisions, revisions, revocations, forks, or new reader-policy surfaces.

## 6) Validation, certainty, and reader policy

Kristal separates five things that are often confused:

1. artifact existence;
2. artifact integrity;
3. assertion status;
4. certainty level;
5. authority recognition;
6. reader visibility.

A Kristal may contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.

A Kristal must not present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.

### Validation

Validation answers:

* Who accepts this?
* Under which policy?
* For which domain or scope?
* As what kind of assertion?

Validation does not always mean high certainty.

An assertion may be validated as:

* a hypothesis;
* a sourced claim;
* a reviewed claim;
* a high-confidence fact;
* an institutional reference;
* a publisher declaration;
* a technical specification;
* a legal or policy position;
* a mythological corpus;
* a fictional corpus;
* a symbolic model;
* a disputed position;
* a rejected claim.

### Certainty

Certainty answers how strong the assertion is within its declared scope.

A simple certainty ladder can include:

* unknown;
* speculative;
* low;
* medium;
* high;
* established;
* not applicable.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=2ea4f6113e51:351-455
start=351
end=455
----

“Not applicable” is useful for fiction, mythology, symbolic models, doctrine, publisher declarations, or other cases where physical-world certainty is not the right measure.

### Reader policy

People and applications can choose how strict they want the reading surface to be.

Examples:

* **reference-only**: show only material recognized as reference by selected authority channels;
* **validated-only**: show only material accepted under chosen validation policies, even if some claims are validated as hypotheses or low-certainty statements;
* **high-certainty-only**: show only high or established certainty claims;
* **research**: include hypotheses, disputed claims, drafts, and lower-certainty material with visible labels;
* **creative**: include fictional, mythological, speculative, or symbolic Kristals when the user intentionally enters that scope;
* **all-with-labels**: show everything allowed by access control, while keeping labels visible;
* **custom**: let the user, institution, or application select authority channels, scopes, and certainty thresholds.

“100% validated data” means that all visible assertions satisfy the active reader policy. It does not mean all assertions have maximum certainty, all authorities agree, or all statements are universally true.

## 7) Federation and plural authority

Kristal does not assume one universal authority over truth.

Different authorities may publish, approve, reject, recognize, or fork different versions of the same corpus, shard, or assertion. A government, association, company, research collective, expert body, religious community, standards organization, international institution, AI-assisted validator, or individual may participate under explicit scope and policy.

Federation keeps those views composable without silently merging them.

A federation manifest should preserve:

* source identity;
* shard identity;
* publisher identity;
* authority channel;
* validation policy;
* certainty level;
* recognition status;
* lineage;
* conflict strategy;
* reader policy.

The default federation rule is:

**Preserve disagreement. Do not silently merge conflicting claims. Do not let one authority masquerade as another.**

### Authority recognition

Authority channels may recognize other authority channels.

Examples:

* UNESCO may recognize WHO for public-health reference material.
* A government may recognize its national statistics agency for demographic datasets.
* A standards body may recognize a technical working group for a specification.
* A university may recognize a lab for a research shard.
* A company may be the primary authority on the declared structure of its own systems, while other authorities may evaluate safety, compliance, environmental claims, or social impact.

Recognition by one authority channel does not imply recognition by every other channel.

## 8) Practical deployment model

### Model A — Kristals as an internal backbone

This is the recommended first deployment model.

* **Orgo runs the Kristal workflow**: ingest → structure → resolve → review → validate → recognize → publish → distribute.
* **SenTient runs as a resolution service** invoked by the workflow when ambiguity needs reconciliation.
* **Kristal produces Exchange artifacts and Runtime Packs**.
* **Konnaxion consumes Runtime Packs** for offline knowledge delivery, search, navigation, education, curation, and civic workflows.
* **Architect consumes Kristal query results** for deterministic publishing and multilingual output.
* **Reader policies control visibility** according to user, institution, domain, scope, and selected authority channels.

Outputs per release may include:

* Structured Epistemic State;
* working Exchange;
* reference Exchange;
* authority recognition records;
* validation decisions;
* federation manifest;
* runtime pack;
* query contract;
* reader policies;
* revocation or update records when needed.

### Model B — Kristals as a public standard

Once stable internally, the Kristal format can be published externally as the interoperability layer for portable epistemic artifacts.

The public standard should expose:

* schemas;
* exchange manifests;
* runtime pack manifests;
* validation decision formats;
* authority recognition formats;
* reader policy profiles;
* federation manifests;
* query contracts;
* examples for Wikidata-aligned data, research claims, institutional submissions, mythology, fiction, disputed forks, and authority-recognized references.

Orgo and Konnaxion remain operational advantages: they provide workflow, distribution, adoption, offline access, and user-facing integration around the standard.

## 9) One-sentence placement summary

**Kristals are portable, traceable, offline-usable epistemic artifacts; SenTient resolves ambiguity into structured identifiers; Architect renders labeled knowledge without changing its status; Orgo operationalizes workflows, review, validation, recognition, and distribution; Konnaxion delivers Kristals at platform scale through search, navigation, offline access, reader policies, and collective curation.**
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/plural-validation-and-federated-authority.md"
id=32e3af149365
kind=markdown
size=24526
lines=983
line_ref=1-983
chunks=3
chunk_refs=1-350,351-700,701-983
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=32e3af149365:1-350
start=1
end=350
----
# Plural Validation and Federated Authority

## Status

Draft (v5 normative overview)

## Purpose

This document defines how Kristal v5 handles plural validation, authority channels, certainty levels, divergent forks, and federated knowledge.

Kristal v5 does not assume that one institution, platform, model, government, company, association, or community owns truth for every domain.

Instead, Kristal v5 makes authority explicit.

A Kristal may contain hypotheses, sourced claims, disputed claims, fictional structures, mythological corpora, research drafts, institutional records, technical declarations, and high-confidence reference material. These may coexist in the same ecosystem without being confused.

The core rule is:

> A Kristal may contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.
> A Kristal must not present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.

Validation is scoped.

Authority is plural.

Certainty is explicit.

Readers choose policy.

Federation preserves disagreement.

Integrity protects artifact identity and provenance.

---

## 1. Normative language

The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as normative requirements.

---

## 2. Core model

Kristal v5 separates six concepts that MUST NOT be collapsed:

```text
artifact existence
artifact integrity
assertion status
certainty level
authority recognition
reader visibility
```

A Kristal object may exist and be well-formed without being recognized by any authority.

A Kristal object may be signed and content-addressed without being accepted as a reference artifact.

An assertion may be validated as a hypothesis without being validated as a high-confidence fact.

A mythological corpus may be valid as mythology without being valid as a physical-world claim.

A reader may choose to show only material accepted by selected authority channels, but that reader policy does not erase the existence of other material.

---

## 3. Artifact existence

A Kristal may be created by:

* an individual;
* a research collective;
* an association;
* a company;
* a government;
* an academic institution;
* an intergovernmental organization;
* an AI-assisted validator;
* a community;
* a hybrid human-machine process.

Creation does not imply recognition.

Publication does not imply recognition.

Signature does not imply recognition.

Distribution does not imply recognition.

Existence only means that the object exists as a structured Kristal artifact.

---

## 4. Artifact integrity

Artifact integrity answers questions such as:

* Is the artifact well-formed?
* Does it match its schema?
* Does its hash match its declared content?
* Are its signatures valid?
* Is its provenance structurally present?
* Does it preserve lineage?
* Is it reproducible under the declared profile?

Artifact integrity does not answer:

* Is the assertion true?
* Is the assertion high certainty?
* Is the authority competent?
* Is the artifact accepted by a given institution?
* Should a reader show this artifact by default?

Integrity protects the object.

It does not decide truth.

---

## 5. Assertion status

Assertions in Kristal v5 SHOULD carry an explicit `assertion_status`.

Recommended assertion statuses are:

```text
hypothesis
claimed
sourced
disputed
reviewed
validated
rejected
retracted
superseded
```

An assertion status describes the epistemic state of the assertion inside a declared process.

It MUST NOT be interpreted without scope, provenance, and authority context.

For example:

```text
validated
```

is incomplete unless the system can also answer:

```text
validated as what?
validated by whom?
validated under which policy?
validated for which scope?
validated at what certainty level?
```

---

## 6. Certainty level

Assertions in Kristal v5 SHOULD carry an explicit `certainty_level`.

Recommended certainty levels are:

```text
unknown
speculative
low
medium
high
established
not_applicable
mixed
```

Certainty describes the strength, confidence, or applicability of an assertion within its declared scope.

Certainty is not the same as validation.

A claim may be:

```text
validated as a hypothesis
```

while still having:

```text
certainty_level = speculative
```

A fictional or mythological assertion may be:

```text
validated as fictional_corpus
```

or:

```text
validated as mythological_corpus
```

with:

```text
certainty_level = not_applicable
```

A technical declaration by a company about its own system may be:

```text
validated as publisher_declaration
```

without being independently validated as a physical, legal, environmental, or social impact claim.

---

## 7. Validation mode

Validation MUST be scoped by `validated_as`.

Recommended validation modes are:

```text
hypothesis
claim
sourced_claim
reviewed_claim
high_confidence_fact
institutional_reference
publisher_declaration
technical_specification
legal_or_policy_position
mythological_corpus
fictional_corpus
symbolic_model
disputed_position
rejected_claim
```

Validation does not always mean maximum certainty.

Validation means:

```text
accepted as X
by authority channel Y
under policy Z
for scope S
with certainty level C
```

A reader may choose to use only validated data, but that does not mean every visible assertion has the same certainty level or the same epistemic mode.

For example, a `validated_only` reader policy may include:

* validated hypotheses;
* validated institutional references;
* validated technical specifications;
* validated mythology corpora;
* validated high-confidence facts;
* validated publisher declarations.

The reader policy decides which of those validation modes are visible.

---

## 8. Authority channels

An authority channel declares who is recognized for a domain, under which scope, and according to which policy.

An authority channel SHOULD include:

```json
{
  "authority_channel_id": "authority:<slug>",
  "name": "string",
  "authority_type": "institution|government|association|company|research_collective|individual|ai_validator|community|standards_body",
  "scope": {},
  "recognized_by": [],
  "trust_roots": [],
  "validation_policies": [],
  "revocation_policy_ref": null
}
```

Authority channels MAY represent:

* individual researchers;
* research groups;
* universities;
* companies;
* governments;
* associations;
* standards bodies;
* expert bodies;
* community groups;
* intergovernmental organizations;
* AI-assisted validation systems;
* hybrid human-machine collectives.

No authority channel has universal scope unless an explicit policy defines the scope and other authority channels recognize it.

Recognition by one authority channel MUST NOT imply recognition by another.

---

## 9. Authority delegation

Authority channels MAY recognize other authority channels.

Examples:

* an international education channel may recognize a scientific organization for a science education scope;
* a government may recognize a national statistics agency for population data;
* a standards body may recognize a technical working group for a protocol profile;
* a university may recognize a laboratory for a research shard;
* a company may be recognized as the primary publisher for documentation about its own systems.

Delegation MUST be explicit.

A delegated authority MUST have:

* a declared scope;
* a recognition record;
* a validation policy or policy reference;
* a revocation or correction path, when applicable.

Delegation MUST NOT erase attribution.

A downstream reader MUST be able to distinguish:

```text
directly validated by authority A
```

from:

```text
recognized by authority A because authority A recognizes authority B for this scope
```

---

## 10. Authority recognition

Authority recognition records that an authority channel accepts a target under a declared scope and policy.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=32e3af149365:351-700
start=351
end=700
----

The target MAY be:

```text
artifact
shard
assertion
authority_channel
dataset
runtime_pack
reader_policy
```

Recommended shape:

```json
{
  "recognition_id": "sha256:<hex>",
  "artifact_type": "authority_recognition",
  "issuer_authority_channel": "authority:<slug>",
  "target_ref": {},
  "target_level": "artifact|shard|assertion|authority_channel|dataset|runtime_pack",
  "recognition_status": "recognized",
  "recognized_as": "institutional_reference",
  "scope": {},
  "validation_policy_ref": {},
  "reason_codes": [],
  "evidence_refs": [],
  "created_at": "RFC3339",
  "expires_at": null,
  "signatures": []
}
```

Recommended recognition statuses are:

```text
recognized
conditionally_recognized
under_review
disputed
rejected
deprecated
revoked
```

Recognition is not universal unless the recognition scope says so and the reader policy chooses to treat it that way.

---

## 11. Validation reports

A validation report records what was checked, by whom or by what system, under which policy, for which target.

A validation report MAY apply to:

* an artifact;
* a Structured Epistemic State;
* an Exchange;
* a shard;
* a federation;
* an assertion;
* an authority channel;
* an authority registry;
* a runtime pack;
* a reader policy;
* a dataset;
* an export.

A validation report MUST NOT be reduced to a single universal boolean.

The following is insufficient:

```json
{
  "validated": true
}
```

A v5 validation report SHOULD instead record:

```json
{
  "validation_status": "validated",
  "validated_as": "high_confidence_fact",
  "certainty_level": "high",
  "authority_channel": "authority:<slug>",
  "validation_policy_ref": {},
  "scope": {}
}
```

Validation reports may support recognition decisions, reader policies, publication decisions, or runtime decisions, but they do not automatically make every consuming system accept the target.

---

## 12. Reader policies

A reader policy decides what a person, application, AI system, or runtime surface chooses to display or use.

Reader policy is not the same as validation.

Reader policy is not the same as authority recognition.

Reader policy is a visibility and selection rule.

Recommended reader modes are:

```text
reference_only
validated_only
high_certainty_only
research
creative
all_with_labels
custom
```

A reader policy MAY filter by:

* artifact status;
* assertion status;
* validation status;
* certainty level;
* validated-as mode;
* authority channel;
* recognition status;
* domain;
* subdomain;
* jurisdiction;
* time window;
* language;
* inclusion of disputed material;
* inclusion of fictional material;
* inclusion of mythological material.

Recommended shape:

```json
{
  "reader_policy_id": "reader_policy:<slug>",
  "mode": "validated_only",
  "allowed_authority_channels": [],
  "allowed_validation_statuses": [],
  "allowed_certainty_levels": [],
  "allowed_validated_as": [],
  "include_disputed": false,
  "include_fictional": false,
  "include_mythological": false,
  "show_labels": true,
  "fallback_behavior": "show_unavailable"
}
```

A reader may choose “only validated data.”

That means:

```text
all visible assertions satisfy the active reader policy
```

It does not mean:

```text
all visible assertions have maximum certainty
all authorities agree
all assertions are universally true
all omitted assertions do not exist
```

---

## 13. Federation

Federation allows multiple Kristals, shards, authority channels, or corpora to coexist and be composed without silent merging.

Federation MUST preserve:

* source identity;
* shard identity;
* authority channel;
* validation status;
* certainty metadata;
* scope;
* provenance;
* lineage;
* disagreement.

Federation MUST NOT silently collapse conflicting assertions into a single unlabelled claim.

Recommended federation rule:

```text
preserve disagreement by default
```

A federation policy MAY define precedence rules, but precedence MUST be explicit and visible.

Examples of composition strategies:

```text
authority_precedence
latest_time_window
explicit_allow_deny
preserve_all
reader_policy_selected
```

Examples of conflict strategies:

```text
preserve_disagreement
authority_precedence
mark_disputed
exclude_conflict
require_reader_choice
```

The default v5 conflict strategy SHOULD be:

```text
preserve_disagreement
```

---

## 14. Divergent forks

A Kristal MAY be copied, forked, extended, reinterpreted, or republished under another authority channel.

Forking is permitted.

Forking MUST preserve lineage.

A forked Kristal MUST NOT inherit authority recognition from the source unless that recognition is explicitly preserved by the recognizing authority channel.

A forked Kristal SHOULD declare:

* source artifact reference;
* lineage;
* publisher;
* authority channel;
* scope;
* validation policy;
* recognition status;
* certainty metadata;
* reader-policy recommendations.

Divergent forks are valid artifacts when they are well-formed and preserve their labels.

They are not necessarily reference artifacts.

They are not necessarily recognized by the same authorities as the source.

---

## 15. Disputed and fringe positions

Kristal v5 allows disputed, minority, speculative, or fringe positions to be represented as structured artifacts.

This is intentional.

The system’s job is not to prevent divergent world-models from being expressed.

The system’s job is to prevent them from being mislabeled.

For example, a group may publish a Kristal containing its arguments for a disputed physical-world claim.

Such a Kristal may be:

```text
artifact_status = working
authority_channel = authority:<group>
validated_as = disputed_position
certainty_level = low
recognition_status = recognized by that group
```

Another authority channel may mark the same assertion as:

```text
validation_status = rejected
validated_as = rejected_claim
certainty_level = established
authority_channel = authority:<scientific-body>
```

Federation preserves both records without making them equivalent.

Reader policies decide what is visible by default.

---

## 16. Mythology, fiction, and symbolic systems

A Kristal may describe mythology, fiction, religious narratives, symbolic systems, games, simulations, or imaginary worlds.

Such a Kristal may be valid within its own scope.

Examples:

```text
validated_as = mythological_corpus
certainty_level = not_applicable
scope.domain = mythology
```

```text
validated_as = fictional_corpus
certainty_level = not_applicable
scope.domain = fiction
```

A mythology Kristal MUST NOT be presented as validated physical-world truth unless a declared authority channel explicitly validates that epistemic mode and the reader policy includes that mode.

A fiction Kristal MUST NOT be presented as historical or scientific reference unless such a mapping is explicitly declared and validated by an appropriate authority channel.

---

## 17. Research and independent claims

Kristal v5 supports independent research.

An independent researcher may publish a Kristal containing:

* hypotheses;
* evidence;
* prototype data;
* experiments;
* models;
* citations;
* objections;
* responses;
* uncertainty;
* replication requests.

Such a Kristal may begin as:

```text
assertion_status = hypothesis
certainty_level = speculative
artifact_status = working
```

It may later receive:

* peer review;
* institutional validation;
* expert-body recognition;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=32e3af149365:701-983
start=701
end=983
----
* governmental recognition;
* intergovernmental recognition;
* replication evidence;
* rejection or correction.

The system MUST preserve the research lifecycle without requiring final recognition before materialization.

---

## 18. Institutional and publisher declarations

A company, agency, institution, or organization may publish Kristals describing its own systems, policies, datasets, or operations.

Such Kristals may be validated as:

```text
publisher_declaration
technical_specification
legal_or_policy_position
institutional_reference
```

A publisher declaration is not automatically a high-confidence independent fact.

For example:

* a software company may be authoritative for the declared interface of its own API;
* it may not be the only authority for security impact, environmental impact, legal compliance, or social consequences;
* those other scopes may require other authority channels.

Kristal v5 MUST allow multiple authority channels to attach separate recognition and validation records to the same target.

---

## 19. Wikidata Seed Kristal

The first global seed corpus may be represented as a Wikidata Seed Kristal.

This means a Kristal-compatible packaging or alignment of the Wikidata corpus.

It SHOULD preserve as much of the source structure as possible, including:

* entities;
* properties;
* statements;
* qualifiers;
* references;
* ranks;
* labels;
* aliases;
* descriptions;
* source identifiers.

The seed corpus MAY be recognized as an institutional or public reference corpus.

That recognition MUST NOT imply that every inherited statement is maximally certain.

A Wikidata Seed Kristal may contain mixed certainty levels and multiple assertion statuses.

A reader policy may choose a high-confidence view, a full-statement view, a best-rank projection, or a research view.

The source corpus remains valuable because it provides a structured base for further validation, correction, extension, and federation.

---

## 20. Global reference authority

An intergovernmental or international organization MAY act as a global reference authority channel for selected scopes.

Such an authority channel MAY:

* recognize seed corpora;
* recognize other authority channels;
* recognize expert bodies;
* validate public reference artifacts;
* publish global reader policies;
* define correction and revocation processes;
* delegate domain-specific authority.

It MUST NOT be treated as owning all truth.

It MUST declare scope.

It MUST expose policy.

It MUST preserve lineage.

It MUST allow other authorities to exist.

It SHOULD make delegated recognition visible.

Example pattern:

```text
authority:global-reference
recognizes authority:health-organization
for scope.domain = health
under validation_policy_ref = policy:global-health-reference
```

The global authority does not need to revalidate every assertion manually if it explicitly recognizes another authority channel as competent for the scope.

---

## 21. Authority laundering

Authority laundering occurs when recognition or validation from one scope is presented as if it came from another scope or stronger authority.

Kristal v5 MUST prevent authority laundering.

Examples of authority laundering include:

* presenting a community-recognized claim as if it were recognized by a scientific body;
* presenting a company declaration as if it were independent audit;
* presenting a mythological corpus as physical-world fact;
* presenting a reader-policy selection as universal truth;
* hiding that a claim is disputed;
* dropping rejected-status metadata during export;
* omitting authority channel labels from a rendered view.

Systems that render, query, export, distribute, or summarize Kristals MUST preserve authority labels when they affect meaning.

---

## 22. Rendering obligations

User-facing systems SHOULD make the following visible or inspectable:

* assertion status;
* certainty level;
* validated-as mode;
* authority channel;
* recognition status;
* validation policy;
* scope;
* provenance;
* evidence references;
* dispute status;
* lineage;
* reader policy currently active.

A summary or UI MAY simplify presentation, but it MUST NOT flatten scoped validation into universal truth.

Architect, readers, search surfaces, agents, exports, and dashboards SHOULD preserve labels whenever omission would mislead the user.

---

## 23. Query obligations

Kristal v5 query systems SHOULD be able to filter or expose:

```text
artifact_status
assertion_status
certainty_level
validated_as
validation_status
authority_channel
recognition_status
scope.domain
scope.subdomain
reader_policy
include_disputed
include_fictional
include_mythological
```

A query result SHOULD indicate whether it is filtered by a reader policy.

A query result MUST NOT imply that omitted material does not exist unless the query explicitly searched the complete source set.

---

## 24. Export obligations

Exports such as JSON-LD, RDF, WDQS-compatible projections, runtime packs, summaries, reports, and static bundles MUST preserve status metadata when that metadata affects meaning.

An export MAY be filtered.

If filtered, it SHOULD declare:

* export policy;
* reader policy;
* included authority channels;
* included validation statuses;
* included certainty levels;
* included validated-as modes;
* projection mode.

Exporting a Kristal MUST NOT silently remove disagreement in a way that changes the meaning of the remaining artifact.

---

## 25. Runtime and distribution obligations

Runtime systems and distribution systems MAY choose stricter activation or display policies.

For example, a runtime may choose:

* only reference artifacts;
* only selected authority channels;
* only high-certainty assertions;
* only validated assertions;
* no disputed material;
* no fictional or mythological material unless explicitly enabled.

Such choices are reader or runtime policies.

They do not define global truth.

Runtime systems SHOULD preserve enough metadata for users and downstream systems to understand what was included, excluded, or deferred.

---

## 26. Correction, revocation, and supersession

Authority channels SHOULD support correction and revocation paths.

A recognition may be:

```text
deprecated
revoked
superseded
```

An assertion may be:

```text
retracted
superseded
rejected
```

Revocation MUST preserve history and lineage sufficient to understand what was revoked and by whom.

A revocation by one authority channel does not automatically revoke recognition by all other authority channels unless a policy explicitly links them.

---

## 27. Minimal conforming plural authority behavior

A Kristal v5 implementation that supports plural validation and federated authority MUST:

1. represent authority channels explicitly;
2. represent scope explicitly;
3. distinguish validation status from certainty level;
4. distinguish artifact integrity from assertion status;
5. support validation or recognition references;
6. avoid universal `validated = true` semantics;
7. preserve disagreement under federation;
8. avoid silent authority laundering;
9. expose reader policy where filtering is applied;
10. preserve lineage when forking or composing artifacts.

---

## 28. Non-goals

This document does not define:

* which authority channels should be trusted by default;
* which institution should validate a specific domain;
* which reader policy a platform must use;
* whether a disputed claim is correct;
* how social consensus is formed;
* how expert review is conducted operationally;
* how an AI validator reaches a judgment;
* how Orgo workflows approve submissions;
* how Konnaxion distributes runtime packs;
* how SenTient resolves ambiguous source material;
* how Architect renders every UI state.

Those concerns are handled by other Kristal v5 documents, ecosystem contracts, authority policies, and implementation-specific workflows.

This document defines the shared conceptual and normative boundary:

> multiple authorities may exist;
> validation is scoped;
> certainty is explicit;
> readers choose policy;
> federation preserves disagreement;
> no authority recognition may be silently borrowed from another scope.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/sharding-and-federation.md"
id=30a0f5f98f5d
kind=markdown
size=23593
lines=879
line_ref=1-879
chunks=3
chunk_refs=1-350,351-700,701-879
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=30a0f5f98f5d:1-350
start=1
end=350
----
# Sharding and Federation

## Status

Draft — Kristal v5

## Purpose

This document defines the Kristal v5 model for **sharding** and **federation**.

Sharding lets large or scoped Kristal corpora be split into smaller, independently addressable artifacts.

Federation lets multiple shards, publishers, authority channels, validation decisions, and reader policies be composed without silently merging their claims or hiding disagreement.

The goal is to support portable, offline-usable, authority-aware knowledge composition across domains, institutions, communities, research groups, companies, governments, cultural bodies, and individual publishers.

---

## Normative language

The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as normative requirements.

---

## 1. Core model

Kristal v5 separates:

* artifact existence;
* artifact integrity;
* assertion status;
* certainty level;
* validation status;
* authority recognition;
* reader visibility;
* federation composition.

A shard may contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.

A federation may compose such shards.

The federation layer MUST preserve the status, provenance, authority channel, certainty, scope, and lineage of the shards and assertions it composes.

A federation MUST NOT make one authority channel appear to speak for another.

A federation MUST NOT silently merge conflicting claims.

A federation MUST NOT represent an assertion as validated, recognized, or reference-level outside the authority channel, scope, certainty level, and validation policy that support that status.

---

## 2. Shards

### 2.1 Definition

A **shard** is a scoped Kristal Exchange artifact.

A shard represents a coherent subset of a larger corpus, such as:

* a domain subset;
* a jurisdictional subset;
* a time-window subset;
* a language subset;
* a tenant subset;
* a publisher subset;
* a source-dataset subset;
* a research subset;
* a fictional or mythological corpus subset;
* a reference subset recognized by an authority channel.

A shard is not merely a file split. It carries identity, scope, provenance, status, and policy metadata.

### 2.2 Shard identity

Each shard MUST have a stable content-addressed identifier.

Recommended field:

```json
{
  "shard_id": "sha256:<hex>"
}
```

A shard MAY also carry a `kristal_id` if the shard is itself a complete Kristal Exchange artifact.

If both `shard_id` and `kristal_id` are present, the schema or manifest MUST define whether they are identical or whether `shard_id` identifies the shard wrapper while `kristal_id` identifies the contained Exchange.

### 2.3 Shard status

A shard MUST declare an artifact status.

Recommended values:

* `draft`
* `working`
* `under_review`
* `recognized`
* `reference`
* `deprecated`
* `superseded`
* `revoked`

A shard with `artifact_status = "working"` MAY be useful for review, research, diagnostics, collaboration, or creative exploration.

A shard with `artifact_status = "reference"` has been recognized as a reference under one or more declared authority channels and scopes.

`reference` MUST NOT be interpreted as universal truth.

### 2.4 Shard scope

A shard MUST declare scope.

Recommended shape:

```json
{
  "scope": {
    "domain": "heritage",
    "subdomain": "unesco",
    "jurisdiction": null,
    "time_window": "2020-01-01T00:00:00Z/2025-12-31T23:59:59Z",
    "tenant_id": "tenant_demo",
    "environment": "prod",
    "language": "en"
  }
}
```

`scope.domain` is REQUIRED.

Recommended domain values include:

* `general`
* `wikidata`
* `science`
* `health`
* `education`
* `heritage`
* `law`
* `policy`
* `technology`
* `environment`
* `culture`
* `mythology`
* `fiction`
* `research`
* `operations`
* `civic`
* `local_notes`

Implementations MAY extend the domain list if the extension is declared by profile or policy.

### 2.5 Shard provenance

A shard SHOULD preserve:

* source snapshot references;
* structured epistemic state references;
* dataset references;
* prior shard references;
* prior Exchange references;
* publisher identity;
* compiler identity;
* build configuration hash;
* validation decision references;
* authority recognition references;
* lineage.

A shard SHOULD NOT erase source identity when it is republished, copied, forked, transformed, or federated.

---

## 3. Federation

### 3.1 Definition

A **federation** is a deterministic composition of multiple Kristal shards, Exchanges, datasets, or references under an explicit composition policy.

A federation can present a unified query or navigation surface while preserving:

* who published each shard;
* who validated or recognized it;
* which authority channel applies;
* which scope applies;
* which reader policy is active;
* which claims are disputed;
* which claims conflict;
* which claims are excluded by policy;
* which claims remain visible only under broader views.

### 3.2 Federation is not silent merging

Federation MUST preserve source identities.

Federation MUST NOT rewrite shard identities.

Federation MUST NOT silently merge conflicting claims.

Federation MUST NOT treat recognition by one authority channel as recognition by another.

Federation MUST NOT hide that a reader policy filtered out disputed, fictional, mythological, rejected, revoked, or unrecognized material.

### 3.3 Federation can expose multiple views

A federation MAY expose multiple reader-policy views over the same composed corpus.

Examples:

* `reference_only`
* `validated_only`
* `high_certainty_only`
* `research`
* `creative`
* `all_with_labels`
* `custom`

Each view MUST declare which authority channels, validation statuses, certainty levels, scopes, and validated-as modes are included.

---

## 4. Federation Manifest

### 4.1 Purpose

A Federation Manifest describes the composition of shards and the policy used to interpret them.

Recommended artifact type:

```json
{
  "artifact_type": "exchange_federation_manifest"
}
```

### 4.2 Required fields

A Kristal v5 Federation Manifest SHOULD contain:

```json
{
  "schema_version": "5.0",
  "artifact_type": "exchange_federation_manifest",
  "federation_id": "sha256:<hex>",
  "created_at": "RFC3339",
  "artifact_status": "working|under_review|recognized|reference|deprecated|revoked",
  "scope": {},
  "authority_registry_ref": {},
  "shards": [],
  "composition_policy": {},
  "reader_policy_refs": [],
  "validation_refs": [],
  "authority_recognition_refs": [],
  "publisher": {},
  "content_hash": {},
  "signatures": [],
  "extensions": {}
}
```

### 4.3 Federation identity

A federation MUST have a stable identifier.

Recommended field:

```json
{
  "federation_id": "sha256:<hex>"
}
```

The hash target for `federation_id` MUST be defined by the applicable canonicalization and hashing rules.

The signatures array MUST NOT be included in the signed payload hash unless an explicit profile says otherwise.

Timestamp fields such as `created_at` MUST NOT affect content-addressed identifiers unless an explicit profile declares them part of the identity surface.

---

## 5. Shard references

A federation manifest contains shard references.

Recommended shape:

```json
{
  "shard_id": "sha256:<hex>",
  "artifact_type": "exchange_shard_manifest",
  "manifest_hash": {
    "alg": "sha256",
    "value": "<hex>"
  },
  "uri": "konnaxion://shards/<id>.json",
  "required": true,
  "scope": {
    "domain": "heritage",
    "subdomain": "unesco",
    "jurisdiction": null,
    "time_window": "2020-01-01T00:00:00Z/2025-12-31T23:59:59Z",
    "tenant_id": "tenant_demo",
    "environment": "prod",
    "language": "en"
  },
  "authority_channel": "authority:unesco-heritage",
  "artifact_status": "reference",
  "validation_refs": [],
  "authority_recognition_refs": []
}
```

### 5.1 Required versus optional shards

A shard reference SHOULD declare whether the shard is required.

If a required shard is unavailable, corrupted, revoked, or not accepted by policy, the federation view MUST report that the composed view is incomplete or unavailable under that policy.

If an optional shard is unavailable, the federation MAY still produce a view, provided the result clearly indicates that optional material was unavailable or excluded.

### 5.2 Shard order

Shard order MUST be deterministic.

Shard ordering MAY be based on:

* explicit order in the manifest;
* stable lexical order by `shard_id`;
* authority precedence;
* scope precedence;
* time-window precedence;
* declared composition policy.

The active ordering rule MUST be declared.

---

## 6. Composition policy

### 6.1 Purpose

The composition policy defines how a federation handles overlap, conflict, visibility, ordering, and authority selection.

Recommended shape:

```json
{
  "policy_id": "kristal.v5:composition-policy:<slug>",
  "policy_version": "1",
  "overlap_strategy": "authority_precedence",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=30a0f5f98f5d:351-700
start=351
end=700
----
  "conflict_strategy": "preserve_disagreement",
  "default_visibility": "reader_policy",
  "ordering": "stable",
  "parameters": {}
}
```

### 6.2 Overlap strategies

Recommended `overlap_strategy` values:

* `authority_precedence`
* `latest_time_window`
* `explicit_allow_deny`
* `preserve_all`
* `reader_policy_selected`

### 6.3 Conflict strategies

Recommended `conflict_strategy` values:

* `preserve_disagreement`
* `authority_precedence`
* `mark_disputed`
* `exclude_conflict`
* `require_reader_choice`

Default Kristal v5 behavior SHOULD be:

```text
conflict_strategy = "preserve_disagreement"
```

### 6.4 Preserve disagreement

When `conflict_strategy = "preserve_disagreement"`, the federation MUST:

* retain all conflicting assertions that are visible under the active reader policy;
* preserve source shard identity for each assertion;
* preserve authority channel identity for each assertion;
* preserve validation and recognition status;
* mark the conflict in the result surface or conflict index;
* allow downstream readers or interfaces to display the disagreement.

### 6.5 Authority precedence

When `overlap_strategy` or `conflict_strategy` uses authority precedence, the manifest MUST declare the relevant authority order or authority-selection rule.

Authority precedence MUST be scoped.

Example:

```json
{
  "authority_precedence": [
    {
      "scope": {
        "domain": "health"
      },
      "order": [
        "authority:who",
        "authority:national-health-agency",
        "authority:local-clinic"
      ]
    }
  ]
}
```

Authority precedence in one scope MUST NOT imply precedence in another scope.

### 6.6 Reader-policy-selected composition

When composition depends on reader policy, the result MUST expose or record the active reader policy.

A query or rendered view SHOULD make clear that results are policy-filtered.

---

## 7. Authority Registry

### 7.1 Purpose

An Authority Registry records authority channels, trust roots, validation policies, recognition policies, revocation references, and scope-bound rules.

The registry does not create universal truth. It declares which authorities are recognized for which scopes and under which policies.

### 7.2 Authority channel

Recommended authority channel shape:

```json
{
  "authority_channel_id": "authority:<slug>",
  "name": "string",
  "authority_type": "institution|government|association|company|research_collective|individual|ai_validator|community|standards_body|intergovernmental_organization|hybrid_collective",
  "scope": {},
  "recognized_by": [],
  "trust_roots": [],
  "validation_policies": [],
  "revocation_policy_ref": null
}
```

### 7.3 Authority recognition

Authority channels MAY recognize other authority channels.

Examples:

* an international organization recognizes a health authority for public-health reference material;
* a government recognizes a national statistics agency for demographic datasets;
* a standards body recognizes a technical working group for a technical specification;
* a company is recognized as the primary authority for its own declared system architecture.

Recognition MUST be explicit and scoped.

Recognition by one authority channel MUST NOT imply recognition by another.

### 7.4 Registry references

A federation manifest SHOULD reference an Authority Registry.

Recommended shape:

```json
{
  "authority_registry_ref": {
    "registry_id": "kristal:authority-registry:sha256:<hex>",
    "registry_hash": {
      "alg": "sha256",
      "value": "<hex>"
    },
    "uri": "konnaxion://authority-registries/<id>.json"
  }
}
```

Implementations MAY support registry identifiers in more than one form, such as:

* `sha256:<hex>`
* `kristal:authority-registry:sha256:<hex>`

The accepted forms MUST be documented.

---

## 8. Validation and recognition in federations

### 8.1 Validation is scoped

A validation decision MUST declare:

* target;
* target level;
* validation status;
* validated-as mode;
* certainty level where applicable;
* authority channel;
* validation policy reference;
* scope;
* findings or reason codes;
* timestamp;
* signatures where required.

A federation MUST NOT collapse validation decisions into a single boolean.

Invalid:

```json
{
  "validated": true
}
```

Recommended pattern:

```json
{
  "validation_status": "validated",
  "validated_as": "institutional_reference",
  "certainty_level": "high",
  "authority_channel": "authority:unesco-heritage",
  "validation_policy_ref": "policy:unesco-heritage-reference-validation@1",
  "scope": {
    "domain": "heritage",
    "subdomain": "unesco"
  }
}
```

### 8.2 Recognition is scoped

Authority recognition records whether an authority channel recognizes a target.

Targets MAY include:

* assertion;
* shard;
* Exchange;
* Runtime Pack;
* dataset;
* federation;
* authority channel;
* validation policy;
* reader policy.

Recognition MUST be scoped.

Recognition MUST NOT be inherited by a fork unless the recognizing authority explicitly recognizes the fork.

### 8.3 Federation-level recognition

A federation itself MAY be recognized as a reference artifact.

Federation-level recognition means that the federation manifest, composition policy, selected shards, reader policies, and authority assumptions are recognized under the declared scope.

It does not automatically mean that every assertion in every shard has maximum certainty.

---

## 9. Reader policies

### 9.1 Purpose

Reader policies determine which material is visible in a view.

They can be used by Runtime Packs, query wrappers, Konnaxion surfaces, Architect renderers, institutional deployments, research tools, or creative tools.

### 9.2 Recommended reader modes

Recommended reader modes:

* `reference_only`
* `validated_only`
* `high_certainty_only`
* `research`
* `creative`
* `all_with_labels`
* `custom`

### 9.3 Reader policy shape

Recommended shape:

```json
{
  "reader_policy_id": "reader_policy:<slug>",
  "mode": "validated_only",
  "allowed_authority_channels": [],
  "allowed_validation_statuses": [],
  "allowed_certainty_levels": [],
  "allowed_validated_as": [],
  "include_disputed": false,
  "include_fictional": false,
  "include_mythological": false,
  "show_labels": true,
  "fallback_behavior": "show_unavailable"
}
```

### 9.4 Validated-only view

A `validated_only` view means all visible assertions satisfy the active reader policy.

It does not mean:

* all assertions have maximum certainty;
* all assertions are physical-world facts;
* all authorities agree;
* all claims are universally true.

A validated-only view may include assertions validated as:

* hypotheses;
* sourced claims;
* institutional references;
* publisher declarations;
* technical specifications;
* legal or policy positions;
* mythological corpora;
* fictional corpora;
* disputed positions.

The validated-as mode, authority channel, certainty level, and scope MUST remain visible or recoverable.

---

## 10. Query behavior

Federation-aware query systems MUST preserve the distinction between:

* source shard;
* assertion status;
* certainty level;
* validation status;
* validated-as mode;
* authority channel;
* recognition status;
* scope;
* reader policy;
* conflict status.

A federation-aware query system SHOULD support filters for:

* `artifact_status`
* `assertion_status`
* `certainty_level`
* `validation_status`
* `validated_as`
* `authority_channel`
* `recognition_status`
* `scope.domain`
* `scope.subdomain`
* `scope.jurisdiction`
* `scope.language`
* `source_shard`
* `reader_policy`
* `include_disputed`
* `include_fictional`
* `include_mythological`
* `show_disagreement`

If query results are filtered by reader policy, responses SHOULD expose the active reader policy.

---

## 11. Integrity and offline behavior

### 11.1 Local verification

A federation may be used offline if all required manifests, shards, registries, policies, revocation records, and Runtime Packs needed by the active reader policy are locally available.

Implementations SHOULD verify:

* shard hashes;
* federation manifest hash;
* registry hash;
* policy hashes;
* signatures required by the active policy;
* revocation status where available;
* schema conformance.

### 11.2 Required verification

If a channel, reader policy, release policy, or activation policy requires a verification step, that step MUST be completed before the artifact is represented as trusted, recognized, reference-level, released, or active for that channel.

If a candidate shard or federation cannot satisfy the active policy, the implementation MUST preserve the current accepted view or clearly mark the candidate as unavailable, unrecognized, incomplete, or rejected under that policy.

This requirement does not prevent the candidate from being inspected in diagnostic, review, research, or creative contexts when policy allows it.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=30a0f5f98f5d:701-879
start=701
end=879
----

### 11.3 Revocation-aware behavior

Federation-aware systems SHOULD support revocation lists or revocation records.

If a shard, signing key, authority channel, recognition record, validation decision, or federation manifest is revoked under the active policy, the system MUST NOT present it as accepted for that policy.

The system MAY preserve it for audit, lineage, dispute review, or historical analysis if policy allows.

---

## 12. Forks and divergence

### 12.1 Forks are allowed

Kristal v5 allows forks.

A fork may be created by:

* a researcher;
* a community;
* a government;
* an association;
* a company;
* an expert group;
* a cultural institution;
* a religious or mythological community;
* a creative project;
* an individual.

Forking a shard or federation MUST preserve lineage.

### 12.2 Fork metadata

A fork SHOULD declare:

* source artifact reference;
* fork reason;
* publisher;
* authority channel;
* scope;
* validation status;
* recognition status;
* reader policies;
* conflict relationship to the source.

### 12.3 Recognition does not automatically transfer

A fork MUST NOT inherit recognition from the source artifact unless the recognizing authority explicitly recognizes the fork.

A fork MAY be valid under one authority channel and rejected, ignored, disputed, or excluded by another.

### 12.4 Divergent claims

Divergent claims MAY be represented if they preserve labels and authority.

Examples:

* a scientific reference shard and a fringe-position shard may coexist;
* a government policy shard and an activist critique shard may coexist;
* a mythology shard may be recognized as mythology;
* a fictional shard may be recognized as fiction;
* a company may publish a system-description shard while regulators publish safety or compliance shards.

Federation preserves these distinctions.

---

## 13. Examples

### 13.1 Heritage federation

A heritage federation may compose:

* a UNESCO heritage reference shard;
* national heritage datasets;
* local cultural inventories;
* disputed or pending nominations;
* language-specific label shards;
* historical revision shards.

A strict reader policy may show only material recognized by the UNESCO heritage authority channel.

A research reader policy may also show disputed, pending, or locally asserted material with labels.

### 13.2 Wikidata seed federation

A Wikidata Seed Kristal may be sharded by:

* entity ranges;
* property groups;
* language labels;
* statement type;
* domain;
* dump timestamp;
* source namespace.

The seed SHOULD preserve full statement structure where possible, including:

* entities;
* properties;
* statements;
* qualifiers;
* references;
* ranks;
* labels;
* aliases;
* descriptions.

A query layer may expose a best-rank or truthy-like projection, but the source federation SHOULD preserve the richer structure when available.

### 13.3 Medical authority federation

A health federation may compose:

* WHO-recognized guidance;
* national agency guidance;
* hospital policy;
* research evidence bundles;
* deprecated or revoked guidance;
* disputed recommendations.

A reader policy for clinical reference use may exclude drafts and disputed material.

A research policy may include lower-certainty material with clear labels.

### 13.4 Fiction and mythology federation

A mythology federation may be recognized as cultural or mythological material.

A fiction federation may be recognized as a fictional corpus.

Such recognition MUST NOT imply validation as physical-world fact.

---

## 14. Conformance

An implementation supporting Kristal v5 sharding and federation MUST:

* preserve shard identity;
* preserve source lineage;
* preserve publisher identity;
* preserve scope;
* preserve authority-channel metadata;
* preserve validation and recognition references;
* preserve assertion status and certainty metadata when present;
* implement deterministic composition policies;
* expose or record reader-policy filtering;
* avoid silent merging of conflicting claims;
* avoid presenting scoped recognition as universal recognition;
* verify required integrity material before representing artifacts as trusted under a policy;
* support revocation-aware behavior when revocation records are declared by policy;
* distinguish working artifacts from reference artifacts;
* support offline composition when all required local material is available.

---

## 15. Minimal mental model

A shard answers:

> “What does this scoped artifact assert, and under which provenance, status, and authority context?”

A federation answers:

> “How do multiple scoped artifacts coexist under an explicit composition policy?”

An authority channel answers:

> “Who recognizes what, under which rules, for which scope?”

A reader policy answers:

> “Which parts of this composed knowledge surface are visible right now?”

The core Kristal v5 rule is:

> Federation preserves disagreement without silent merging.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/validation-certainty-and-authority.md"
id=d136e9cb43cb
kind=markdown
size=32464
lines=1230
line_ref=1-1230
chunks=4
chunk_refs=1-350,351-700,701-1050,1051-1230
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=d136e9cb43cb:1-350
start=1
end=350
----
# Validation, Certainty, and Authority

## Status

Draft (Kristal v5 normative overview)

## Purpose

This document defines how Kristal v5 separates:

* validation;
* certainty;
* authority recognition;
* artifact integrity;
* reader policy;
* federation.

Kristal v5 does not assume that every compiled artifact is final, universally true, expert-approved, or high-certainty. It allows hypotheses, sourced claims, disputed assertions, research bundles, fictional worlds, mythological corpora, technical declarations, institutional records, and high-confidence reference material to coexist without being confused.

The core invariant is:

> A Kristal MAY contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.
>
> A Kristal MUST NOT present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.

This document provides the shared vocabulary and model used by schemas, examples, query contracts, federation manifests, authority registries, validation reports, Runtime Packs, and reader policies.

---

## Normative keywords

MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as normative requirement keywords.

---

## Core distinction

Kristal v5 separates five concepts that are often conflated:

```text
artifact existence
≠ artifact integrity
≠ assertion validity
≠ certainty level
≠ authority recognition
≠ reader visibility
```

A Kristal artifact may be structurally valid, content-addressed, signed, and reproducible while containing assertions that are speculative, disputed, fictional, mythological, low-certainty, or not yet evaluated.

A signature proves that a key signed an artifact identity. It does not prove that the artifact is true.

A validation decision says that a target was evaluated under a policy. It does not automatically imply universal truth or maximum certainty.

An authority recognition says that a channel accepts, rejects, classifies, or references a target within a declared scope. It does not grant authority outside that scope.

A reader policy decides what a user, runtime, interface, application, or AI system chooses to expose or rely on.

---

## Short definition

Kristal v5 is a deterministic, portable epistemic artifact system.

It allows claims, hypotheses, references, myths, technical declarations, research claims, institutional corpora, and disputed forks to coexist without confusion.

Validation is scoped.

Authority is plural.

Certainty is explicit.

Readers choose policy.

Federation preserves disagreement.

Integrity protects artifacts.

---

## Conceptual model

```text
Signal / Draft / Dataset / Submission
  -> Structured Epistemic State
  -> Compile
  -> Working Artifact
  -> Review / Validation / Attestation / Federation
  -> Authority Recognition
  -> Reference Artifact
  -> Distribution / Runtime Pack / Reader Policy
```

This is not a universal mandatory pipeline.

Some artifacts may begin as institutional datasets. Some may come from human experts. Some may come from Wikidata-compatible source data. Some may come from extractors, OCR, LLMs, parsers, or scrapers. Some may be fictional or mythological corpora.

Claim-IR MAY be used as an extractor proposal profile.

Claim-IR MUST NOT be treated as the universal required input to Kristal v5.

Structured Epistemic State is the normative input model for compiled epistemic content.

---

## Validation

Validation answers:

```text
Who accepted this?
As what?
Under which policy?
For which scope?
At which target level?
```

Validation does not answer, by itself:

```text
Is this universally true?
Does every authority agree?
Is this maximum certainty?
Should every reader display it?
```

A validation decision MUST be scoped.

A validation decision SHOULD identify:

* the target being validated;
* the target level;
* the validation status;
* the validated-as status;
* the certainty level, if applicable;
* the authority channel;
* the validation policy;
* the scope;
* the evidence or review basis;
* the time of decision;
* the issuer;
* signatures, when required by policy.

A validation decision MUST NOT be represented only as:

```json
{ "validated": true }
```

This is insufficient in Kristal v5 because it hides authority, scope, policy, and certainty.

---

## Validation status

The standard validation status values are:

```text
validation_status:
  - not_evaluated
  - in_review
  - validated
  - conditionally_validated
  - disputed
  - rejected
  - revoked
```

### `not_evaluated`

The target has not been evaluated under the relevant validation policy.

### `in_review`

The target is undergoing review or validation.

### `validated`

The target satisfies the declared validation policy for the declared scope and validated-as status.

### `conditionally_validated`

The target satisfies the declared validation policy only under stated conditions, limitations, time windows, jurisdictions, reader policies, or authority-channel constraints.

### `disputed`

The target is actively contested, or conflicting authority channels disagree about its status.

### `rejected`

The target was evaluated and rejected under the declared validation policy.

### `revoked`

A previous validation or recognition was withdrawn by the relevant authority channel or policy process.

---

## Validated-as status

Validation does not always mean high certainty.

An assertion may be validated as a hypothesis, as a publisher declaration, as a mythological corpus, as a fictional statement, as an institutional reference, or as a high-confidence factual assertion.

The standard `validated_as` values are:

```text
validated_as:
  - hypothesis
  - claim
  - sourced_claim
  - reviewed_claim
  - high_confidence_fact
  - institutional_reference
  - publisher_declaration
  - technical_specification
  - legal_or_policy_position
  - mythological_corpus
  - fictional_corpus
  - symbolic_model
  - disputed_position
  - rejected_claim
```

### `hypothesis`

The assertion is valid as a hypothesis. It may be useful for research or reasoning without being established as fact.

### `claim`

The assertion is recorded as a claim by a source, publisher, person, institution, model, or dataset.

### `sourced_claim`

The assertion is linked to evidence, references, or source material.

### `reviewed_claim`

The assertion has been reviewed by a person, system, group, or authority process, but may not yet be accepted as a reference.

### `high_confidence_fact`

The assertion is accepted as high-confidence factual content under the declared authority channel and validation policy.

### `institutional_reference`

The assertion or artifact is recognized as a reference by an institution or authority channel for a declared scope.

### `publisher_declaration`

The assertion is validated as a statement made by its publisher.

For example, a company may publish a Kristal describing its own systems. That does not make every downstream safety, policy, or environmental implication validated by external authorities.

### `technical_specification`

The assertion is validated as a technical specification under a declared authority or publisher scope.

### `legal_or_policy_position`

The assertion is validated as a legal, regulatory, civic, or policy position. This may be jurisdiction-specific and time-bound.

### `mythological_corpus`

The assertion or artifact is validated as mythology, cultural memory, symbolic narrative, religious corpus, or heritage material.

This MUST NOT be represented as validated physical-world truth unless an authority channel explicitly validates that epistemic mode.

### `fictional_corpus`

The assertion or artifact is validated as fiction or creative world-building.

This MUST NOT be represented as validated physical-world truth.

### `symbolic_model`

The assertion is validated as a symbolic, metaphorical, representational, or interpretive model.

### `disputed_position`

The assertion is valid as a position held by a declared source or authority channel, while remaining disputed by other channels.

### `rejected_claim`

The assertion is validated as rejected under a declared policy. This is useful for preserving audit trails, refutations, reviews, and disagreement.

---

## Certainty

Certainty answers:

```text
How strong is the assertion within its declared scope?
```

Certainty does not answer:

```text
Who validates it?
Who recognizes it?
Which reader should display it?
Whether it is signed?
Whether it is globally true?
```

The standard certainty levels are:

```text
certainty_level:
  - unknown
  - speculative
  - low
  - medium
  - high
  - established
  - not_applicable
```

### `unknown`

No certainty level has been assigned, or the certainty level is unavailable.

### `speculative`

The assertion is exploratory, conjectural, creative, early-stage, or weakly supported.

### `low`

The assertion has limited support, uncertain evidence, unresolved ambiguity, or weak confidence.

### `medium`

The assertion has meaningful support but remains open to revision, context dependency, or further review.

### `high`

The assertion has strong support under the declared scope and policy.

### `established`

The assertion is accepted as established within the declared authority channel, scope, and validation policy.

`established` MUST NOT be interpreted as universal or permanent truth.

### `not_applicable`

Certainty does not apply in the ordinary factual sense.

Use this for fiction, mythology, symbolic models, publisher declarations, legal positions, cultural corpora, and other contexts where “truth strength” is not the right evaluation dimension.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=d136e9cb43cb:351-700
start=351
end=700
----

---

## Assertion status

Assertion status describes the current epistemic state of an assertion.

The standard values are:

```text
assertion_status:
  - hypothesis
  - claimed
  - sourced
  - disputed
  - reviewed
  - validated
  - rejected
  - retracted
  - superseded
```

### `hypothesis`

The assertion is intentionally recorded as a hypothesis.

### `claimed`

The assertion is stated by a source, author, publisher, model, institution, or dataset.

### `sourced`

The assertion has evidence, references, provenance, or source links.

### `disputed`

The assertion is contested or has unresolved disagreement.

### `reviewed`

The assertion has been reviewed under a declared process.

### `validated`

The assertion has a validation decision under a declared authority channel, policy, and scope.

### `rejected`

The assertion was rejected under a declared authority channel, policy, and scope.

### `retracted`

The assertion was withdrawn by its publisher, source, or authority channel.

### `superseded`

The assertion has been replaced by a newer assertion, artifact, or version.

---

## Authority channels

Kristal v5 does not define one universal authority over truth.

An authority channel declares:

* who or what is acting as an authority;
* what scope the authority covers;
* which trust roots are used;
* which validation policies are accepted;
* which publishers, validators, or other authorities it recognizes;
* how recognition, rejection, revocation, and disputes are handled.

Authority channels may include:

```text
authority_type:
  - individual
  - community
  - association
  - research_collective
  - academic_institution
  - standards_body
  - company
  - government
  - intergovernmental_organization
  - ai_validator
  - hybrid_collective
```

A recognition by one authority channel MUST NOT be interpreted as recognition by another authority channel unless an explicit recognition relationship supports that interpretation.

---

## Authority recognition

Authority recognition answers:

```text
Does this authority channel recognize this target?
Recognized as what?
For which scope?
Under which policy?
```

Recognition may target:

```text
target_level:
  - artifact
  - shard
  - assertion
  - authority_channel
  - dataset
  - runtime_pack
```

The standard recognition statuses are:

```text
recognition_status:
  - recognized
  - conditionally_recognized
  - under_review
  - disputed
  - rejected
  - deprecated
  - revoked
```

Authority recognition SHOULD be represented through an explicit Authority Recognition artifact.

An authority recognition record SHOULD include:

```json
{
  "recognition_id": "sha256:<hex>",
  "artifact_type": "authority_recognition",
  "issuer_authority_channel": "authority:<slug>",
  "target_ref": {},
  "target_level": "artifact",
  "recognition_status": "recognized",
  "recognized_as": "institutional_reference",
  "scope": {},
  "validation_policy_ref": {},
  "reason_codes": [],
  "evidence_refs": [],
  "created_at": "RFC3339",
  "expires_at": null,
  "signatures": []
}
```

---

## Delegated authority

Authority channels MAY recognize other authority channels.

For example:

* an international organization may recognize a health authority for public health reference material;
* a government may recognize a national statistical agency;
* a university may recognize a laboratory for a research shard;
* a standards body may recognize a technical working group;
* a company may recognize a product team for documentation about its own systems.

Delegated recognition MUST be explicit.

A delegated authority relationship SHOULD specify:

* recognizing authority;
* recognized authority;
* scope;
* domain;
* subdomain;
* jurisdiction, if applicable;
* validation policy;
* expiration, if applicable;
* revocation path;
* signatures.

Delegated recognition MUST NOT grant universal authority outside the declared scope.

---

## Reader policy

Reader policy answers:

```text
What should this reader, application, runtime, AI system, or user interface include or hide?
```

A reader policy may choose strict or permissive views.

The standard reader modes are:

```text
reader_mode:
  - reference_only
  - validated_only
  - high_certainty_only
  - research
  - creative
  - all_with_labels
  - custom
```

### `reference_only`

Display only artifacts or assertions recognized as reference material under selected authority channels and reader policies.

### `validated_only`

Display only material that satisfies selected validation policies.

This does not necessarily mean maximum certainty.

A `validated_only` view MAY include assertions validated as hypotheses, publisher declarations, mythological corpora, fictional corpora, or legal positions if the active reader policy explicitly allows those validated-as statuses.

### `high_certainty_only`

Display only material whose certainty level satisfies the policy threshold.

### `research`

Display working, uncertain, disputed, low-certainty, or not-yet-validated material with labels preserved.

### `creative`

Display fictional, mythological, symbolic, speculative, or imaginative corpora when the user intentionally enters that scope.

### `all_with_labels`

Display all available material allowed by access policy, with validation, certainty, dispute, authority, and scope labels preserved.

### `custom`

A user-defined or deployment-defined reader policy.

---

## Reader policy object

A reader policy SHOULD be machine-readable.

Recommended shape:

```json
{
  "reader_policy_id": "reader_policy:<slug>",
  "mode": "validated_only",
  "allowed_authority_channels": [],
  "allowed_validation_statuses": [],
  "allowed_certainty_levels": [],
  "allowed_validated_as": [],
  "include_disputed": false,
  "include_fictional": false,
  "include_mythological": false,
  "show_labels": true,
  "fallback_behavior": "show_unavailable"
}
```

Reader policies MUST NOT silently remove labels required to understand validation, certainty, scope, or authority.

A reader policy that filters material MUST NOT imply that excluded material does not exist.

---

## Artifact status

Artifact status describes the lifecycle state of an artifact.

The standard artifact status values are:

```text
artifact_status:
  - draft
  - working
  - under_review
  - recognized
  - reference
  - deprecated
  - superseded
  - revoked
```

### `draft`

The artifact is incomplete or local.

### `working`

The artifact is compiled and usable as structured material, but it is not necessarily recognized as reference material.

### `under_review`

The artifact is being evaluated.

### `recognized`

The artifact has been recognized by at least one declared authority channel.

### `reference`

The artifact is accepted as reference material under one or more declared authority channels, scopes, and reader policies.

### `deprecated`

The artifact is still identifiable but no longer recommended.

### `superseded`

The artifact has been replaced by another artifact.

### `revoked`

The artifact has been withdrawn or invalidated by the relevant authority, publisher, or policy process.

---

## Working artifacts and reference artifacts

A Working Artifact may contain:

* hypotheses;
* claims;
* sourced claims;
* disputed assertions;
* unresolved assertions;
* research material;
* fictional or mythological corpora;
* low-certainty material;
* rejected claims preserved for audit;
* incomplete structures.

A Reference Artifact is an artifact recognized by one or more authority channels or reader policies for a declared scope.

A Working Artifact MUST NOT be represented as a Reference Artifact unless a recognition or validation decision supports that status.

A Reference Artifact MUST NOT be represented as universally true unless a scope and authority policy explicitly support that claim.

---

## Federation and disagreement

Federation allows multiple Kristals, shards, authorities, or reference views to coexist.

--- CHUNK END ---

--- CHUNK BEGIN ---
id=d136e9cb43cb:701-1050
start=701
end=1050
----
Federation MUST preserve:

* source identity;
* publisher identity;
* authority channel;
* validation status;
* recognition status;
* certainty level;
* scope;
* lineage;
* conflict status;
* reader policy context.

Federation MUST NOT silently merge conflicting claims as if they came from the same authority or had the same status.

The default conflict strategy in Kristal v5 is:

```text
conflict_strategy = "preserve_disagreement"
```

Other conflict strategies MAY be used if explicitly declared by a composition policy.

---

## Divergent forks

Divergent forks are allowed.

A fork may be produced for:

* research;
* criticism;
* alternative authority recognition;
* local governance;
* education;
* fictional or mythological exploration;
* minority or dissenting interpretations;
* error correction;
* experimental modeling.

A divergent fork MUST preserve lineage.

A divergent fork MUST declare its authority channel, scope, reader policy context, or lack of recognition when applicable.

A fork MUST NOT inherit recognition from its source unless the recognizing authority explicitly recognizes the fork.

---

## Fiction, mythology, and symbolic corpora

A Kristal may represent fiction, mythology, symbolic systems, cultural memory, religious corpora, or imaginative worlds.

Such a Kristal may be valid and reference-worthy within its declared scope.

For example:

```text
validated_as = "mythological_corpus"
certainty_level = "not_applicable"
scope.domain = "mythology"
```

or:

```text
validated_as = "fictional_corpus"
certainty_level = "not_applicable"
scope.domain = "fiction"
```

A mythological or fictional Kristal MUST NOT be represented as validated physical-world truth unless a declared authority channel explicitly validates that epistemic mode.

---

## Research and hypotheses

A hypothesis may be valid as a hypothesis.

A research bundle may be valuable before expert consensus exists.

A low-certainty assertion may be worth preserving if its uncertainty is explicit.

Kristal v5 therefore allows research material to be compiled, distributed, cited, queried, and reviewed without presenting it as established fact.

A reader or runtime MAY choose to hide such material by default under strict policies.

---

## Institutional and delegated references

Some artifacts are reference-worthy because a competent institution declares or recognizes them.

Examples:

* a health authority recognizing clinical guidance;
* a standards body recognizing a technical specification;
* a government agency recognizing official statistics;
* a company publishing authoritative documentation about its own systems;
* a museum or cultural institution recognizing a heritage corpus.

Institutional recognition MUST be scoped.

A company may be authoritative for its own product documentation but not for independent safety claims.

A health authority may be authoritative for medical guidance but not for unrelated technical standards.

An international organization may recognize an authority channel without independently re-validating every assertion inside every artifact.

---

## Wikidata-compatible seed corpora

A Wikidata-compatible seed Kristal may package a Wikidata corpus as structured Kristal-compatible material.

Such a seed SHOULD preserve, as applicable:

* entities;
* properties;
* statements;
* qualifiers;
* references;
* ranks;
* labels;
* aliases;
* descriptions;
* source identity;
* provenance;
* compatible export structures.

A seed corpus may be recognized as a reference corpus without implying that every statement inside it is maximum-certainty or universally true.

The recognition status of the corpus and the certainty status of individual assertions MUST remain distinguishable.

---

## Required fields for validation-aware assertions

A validation-aware assertion SHOULD include:

```json
{
  "assertion_id": "sha256:<hex>",
  "statement": {},
  "assertion_status": "sourced",
  "certainty_level": "medium",
  "validated_as": "sourced_claim",
  "validation_status": "not_evaluated",
  "scope": {},
  "provenance_refs": [],
  "evidence_refs": [],
  "authority_recognition_refs": [],
  "validation_decision_refs": [],
  "lineage": {}
}
```

The following fields SHOULD be queryable:

```text
assertion_id
assertion_status
certainty_level
validated_as
validation_status
authority_channel
recognition_status
scope.domain
scope.subdomain
reader_policy
include_disputed
include_fictional
include_mythological
```

---

## Validation decision shape

A validation decision SHOULD follow this general shape:

```json
{
  "validation_decision_id": "sha256:<hex>",
  "artifact_type": "validation_decision",
  "target_ref": {},
  "target_level": "artifact",
  "validation_status": "validated",
  "validated_as": "high_confidence_fact",
  "certainty_level": "high",
  "authority_channel": "authority:<slug>",
  "validation_policy_ref": {},
  "scope": {},
  "findings": [],
  "reason_codes": [],
  "created_at": "RFC3339",
  "signatures": []
}
```

Validation decision identifiers SHOULD be content-addressed unless a profile defines another deterministic identifier scheme.

---

## Authority recognition shape

An authority recognition record SHOULD follow this general shape:

```json
{
  "recognition_id": "sha256:<hex>",
  "artifact_type": "authority_recognition",
  "issuer_authority_channel": "authority:<slug>",
  "target_ref": {},
  "target_level": "artifact",
  "recognition_status": "recognized",
  "recognized_as": "institutional_reference",
  "scope": {},
  "validation_policy_ref": {},
  "reason_codes": [],
  "evidence_refs": [],
  "created_at": "RFC3339",
  "expires_at": null,
  "signatures": []
}
```

Recognition identifiers SHOULD be content-addressed unless a profile defines another deterministic identifier scheme.

---

## Reason codes

Implementations SHOULD use stable reason codes when reporting validation, recognition, dispute, rejection, or reader-policy decisions.

Recommended reason codes:

```text
schema_valid
schema_invalid
provenance_sufficient
provenance_insufficient
evidence_sufficient
evidence_insufficient
authority_recognized
authority_not_recognized
scope_mismatch
policy_satisfied
policy_failed
signature_valid
signature_invalid
hash_valid
hash_invalid
conflict_detected
disagreement_preserved
certainty_too_low_for_policy
validated_as_not_allowed_by_policy
rejected_by_authority_channel
revoked_by_authority_channel
reader_policy_satisfied
reader_policy_not_satisfied
```

---

## Query implications

A Kristal v5 query system SHOULD support filtering by:

```text
artifact_status
assertion_status
certainty_level
validated_as
validation_status
authority_channel
recognition_status
scope.domain
scope.subdomain
reader_policy
include_disputed
include_fictional
include_mythological
```

A query result SHOULD preserve the fields needed to explain why a result is visible.

A query result MUST NOT hide that an assertion is disputed, rejected, fictional, mythological, low-certainty, not evaluated, or recognized only by a specific authority channel when that status is known.

---

## Runtime Pack implications

A Runtime Pack SHOULD declare:

* whether it derives from a Working Artifact or Reference Artifact;
* which reader policies it supports;
* which authority channels it includes;
* which validation statuses it includes;
* which certainty levels it includes;
* whether disputed material is included;
* whether fictional or mythological material is included;
* which source artifact and build produced it.

A Runtime Pack built for a permissive research or creative view MUST NOT be activated as a strict reference-only or validated-only pack unless it satisfies that stricter policy.

---

## Rendering implications

Rendering systems such as Architect MUST preserve:

* validation labels;
* authority labels;
* certainty labels;
* disputed status;
* rejected or revoked status;
* fictional or mythological scope;
* reader policy context.

Rendering systems MUST NOT flatten scoped validation into universal truth.

Rendering systems MUST NOT hide that a claim is validated only by a specific authority channel.

---

## Examples

### Example 1: validated hypothesis

```json
{
  "assertion_status": "hypothesis",
  "validation_status": "validated",
  "validated_as": "hypothesis",
  "certainty_level": "speculative",
  "authority_channel": "authority:research-lab-alpha",
  "scope": {
    "domain": "research",
    "subdomain": "early-stage-model"
  }
}
```

This means the assertion is valid as a hypothesis under the research lab’s policy.

It does not mean the assertion is established fact.

---

--- CHUNK END ---

--- CHUNK BEGIN ---
id=d136e9cb43cb:1051-1230
start=1051
end=1230
----
### Example 2: mythology corpus

```json
{
  "assertion_status": "validated",
  "validation_status": "validated",
  "validated_as": "mythological_corpus",
  "certainty_level": "not_applicable",
  "authority_channel": "authority:cultural-heritage-institute",
  "scope": {
    "domain": "mythology",
    "subdomain": "classical-greek"
  }
}
```

This means the artifact is validated as mythology or cultural material.

It does not mean the events are validated as physical-world history.

---

### Example 3: company technical declaration

```json
{
  "assertion_status": "validated",
  "validation_status": "validated",
  "validated_as": "publisher_declaration",
  "certainty_level": "not_applicable",
  "authority_channel": "authority:company-example",
  "scope": {
    "domain": "technology",
    "subdomain": "product-documentation"
  }
}
```

This means the company declares the content as its own product documentation.

It does not automatically validate independent claims about safety, compliance, or social impact.

---

### Example 4: medical institutional reference

```json
{
  "assertion_status": "validated",
  "validation_status": "validated",
  "validated_as": "institutional_reference",
  "certainty_level": "high",
  "authority_channel": "authority:health-organization",
  "scope": {
    "domain": "health",
    "subdomain": "clinical-guidance"
  },
  "authority_recognition_refs": [
    "recognition:global-health-reference"
  ]
}
```

This means the content is recognized as a health reference under the declared authority channel and scope.

---

### Example 5: divergent fork

```json
{
  "artifact_status": "working",
  "validation_status": "not_evaluated",
  "recognition_status": "recognized",
  "validated_as": "disputed_position",
  "certainty_level": "low",
  "authority_channel": "authority:local-association-example",
  "scope": {
    "domain": "research",
    "subdomain": "minority-position"
  },
  "lineage": {
    "forked_from": [
      "sha256:<source-artifact-id>"
    ]
  }
}
```

This means a local association recognizes the fork as its own position.

It does not imply recognition by scientific, educational, governmental, or international authority channels.

---

## Conformance requirements

A Kristal v5 conformant implementation MUST:

1. distinguish validation status from certainty level;
2. distinguish signature verification from validation;
3. distinguish validation from authority recognition;
4. distinguish artifact status from assertion status;
5. support scoped validation decisions;
6. support plural authority channels;
7. preserve validation, authority, certainty, and scope labels in federation;
8. allow reader policies to select which statuses and channels are visible;
9. avoid representing working material as reference material without recognition;
10. avoid representing fictional, mythological, disputed, rejected, or low-certainty material as high-confidence physical-world truth.

A conformant implementation SHOULD:

1. expose validation and certainty fields in query results;
2. expose authority-channel context in reader interfaces;
3. preserve disagreement during federation;
4. support delegated authority recognition;
5. support reader policies for strict, research, creative, and all-with-labels modes;
6. preserve uncertainty and rejected claims when used for audit, review, or research.

---

## Anti-patterns

The following patterns are non-conformant or strongly discouraged:

```text
validated = true
```

without authority, scope, policy, and validated-as status.

```text
signed = true
therefore true = true
```

because signatures do not imply truth.

```text
recognized by one authority
therefore recognized by all authorities
```

because authority is scoped.

```text
mythology corpus
therefore validated physical-world fact
```

because mythological validity is not physical-world validation.

```text
reader hides rejected claims
therefore rejected claims do not exist
```

because reader visibility is not corpus existence.

```text
federation merges conflicting claims silently
```

because federation must preserve disagreement or declare a policy for conflict handling.

---

## Open questions

The following decisions remain open:

* Should `established` be allowed as a certainty level, or should `high` be the strongest level?
* Should `validated_as` be a closed enum in the base schema, or an extensible controlled vocabulary?
* Should `reader_policy` be required on all Runtime Packs?
* Should `authority_channel` be required on all validation decisions?
* Should `recognition_status` be required on all Reference Artifacts?
* Should delegated authority recognition always require expiry?
* Should fictional and mythological corpora use `certainty_level = not_applicable` by default?
* Should `validated_only` reader mode allow validated hypotheses by default, or require explicit inclusion?
* Should `reference` be an artifact status or only a reader-policy result?
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/vision-and-scope.md"
id=2f07d967def4
kind=markdown
size=14625
lines=273
line_ref=1-273
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Vision and scope (Kristal v5)
000002 | 
000003 | Kristal is the portable, verifiable, offline-executable unit of structured epistemic knowledge in the ecosystem. A Kristal is **not a document** and not free text. It is a **compiled epistemic artifact** designed to be **Wikidata/Wikibase-aligned**, **traceable**, **AI-ready**, **federable**, and **executable offline**.
000004 | 
000005 | Kristal v5 makes structured knowledge usable without pretending that all knowledge has the same status. A Kristal may contain claims, hypotheses, references, myths, technical declarations, research claims, institutional corpora, disputed forks, and validated assertions. The system’s role is to keep those states explicit, queryable, and non-confused.
000006 | 
000007 | Validation in Kristal v5 is scoped. It means that an assertion, artifact, shard, authority channel, or dataset is accepted **as something**, **by someone**, **under a policy**, **for a scope**. It does not automatically mean universal truth or maximum certainty.
000008 | 
000009 | Certainty is explicit. Readers, applications, institutions, and AI systems can choose policies such as reference-only, validated-only, high-certainty-only, research, creative, or custom authority-channel views.
000010 | 
000011 | ## Goals
000012 | 
000013 | Kristal v5 aims to:
000014 | 
000015 | 1. **Interoperable identity**
000016 | 
000017 |    * Identical content yields identical IDs across languages and toolchains.
000018 |    * Hashing and signature verification behavior is fully specified.
000019 |    * Artifact identity remains stable across implementations.
000020 | 
000021 | 2. **Deterministic compilation**
000022 | 
000023 |    * Exchange and Runtime Pack generation is reproducible.
000024 |    * Build-affecting policies and parameters are recorded in manifests.
000025 |    * Compilation does not imply validation, recognition, or reference status.
000026 | 
000027 | 3. **Structured epistemic states**
000028 | 
000029 |    * The normative input unit is a **Structured Epistemic State**.
000030 |    * A Structured Epistemic State is schema-constrained, provenance-bearing, scope-aware, and explicit about assertion status and certainty.
000031 |    * Claim-IR remains available as an extractor proposal profile, but it is not the universal required input format.
000032 | 
000033 | 4. **Plural validation**
000034 | 
000035 |    * Validation is expressed through authority channels, validation policies, scopes, and validation decisions.
000036 |    * An assertion may be validated as a hypothesis, a sourced claim, a high-confidence fact, a publisher declaration, a technical specification, a mythological corpus, a fictional corpus, or a disputed position.
000037 |    * Recognition by one authority channel does not imply recognition by every other authority channel.
000038 | 
000039 | 5. **Explicit certainty**
000040 | 
000041 |    * Assertions carry machine-readable certainty levels.
000042 |    * A validated assertion does not need to have maximum certainty.
000043 |    * A mythology corpus may be valid as mythology; a fictional corpus may be valid as fiction; a technical declaration may be valid as a publisher’s declared system description.
000044 | 
000045 | 6. **Federated authority**
000046 | 
000047 |    * Kristals can be sharded and federated without rewriting source artifacts.
000048 |    * Different authorities may recognize different versions of the same corpus, shard, or assertion.
000049 |    * Federation preserves disagreement and prevents silent merging of incompatible claims.
000050 | 
000051 | 7. **Reader policy**
000052 | 
000053 |    * Readers and applications choose which authority channels, validation states, certainty levels, and epistemic modes they accept.
000054 |    * A “validated-only” reader view means all visible assertions satisfy the active reader policy.
000055 |    * It does not mean that all visible assertions are universally true, maximally certain, or accepted by all authorities.
000056 | 
000057 | 8. **Offline execution**
000058 | 
000059 |    * Runtime Packs are executable offline and do not depend on SPARQL endpoints, network access, or LLMs.
000060 |    * Query semantics are intentionally constrained to remain predictable and portable.
000061 |    * Runtime Packs declare whether they are derived from working artifacts, reference artifacts, or another declared source status.
000062 | 
000063 | 9. **Standards-aligned exports**
000064 | 
000065 |    * Define stable export profiles, including JSON-LD and RDF/WDQS-aligned projections.
000066 |    * Preserve Wikidata/Wikibase structures where appropriate, including entities, properties, statements, qualifiers, references, ranks, labels, aliases, and descriptions.
000067 |    * Provide optional integrity, provenance, validation, and transparency profiles for high-assurance contexts.
000068 | 
000069 | ## Non-goals
000070 | 
000071 | Kristal v5 does **not** attempt to:
000072 | 
000073 | * Provide full SPARQL semantics in Runtime Packs.
000074 | * Make every compiled artifact a validated or recognized reference.
000075 | * Declare one universal authority over truth.
000076 | * Collapse all validation into a single global score.
000077 | * Treat all assertions inside a Kristal as having the same certainty.
000078 | * Hide disagreement between authority channels.
000079 | * Prevent creative, fictional, mythological, speculative, or divergent Kristals from existing.
000080 | * Replace Orgo’s operational logging, auditing, workflow, and governance systems.
000081 | * Guarantee identical performance across implementations.
000082 | * Guarantee truth by artifact existence alone.
000083 | 
000084 | Kristal records epistemic structure, provenance, certainty, validation status, recognition status, build metadata, and queryable artifact identity. Orgo records workflow and governance. Konnaxion handles distribution and reader-facing access. Architect renders traceable outputs. SenTient supports resolution and extraction workflows where needed.
000085 | 
000086 | ## Core model and artifacts
000087 | 
000088 | Kristal exists as: **standard + compilation model + artifact contracts + runtime pack**.
000089 | 
000090 | ### Core artifacts
000091 | 
000092 | Kristal v5 defines the following primary artifact families:
000093 | 
000094 | 1. **Structured Epistemic State**
000095 | 
000096 |    * The normative input unit for compilation.
000097 |    * Contains assertions, provenance, evidence references, scope, certainty, status, lineage, and policy references.
000098 |    * May originate from human authorship, institutional datasets, collaborative editing, automated extraction, research workflows, imported corpora, or hybrid human/AI processes.
000099 | 
000100 | 2. **Working Exchange**
000101 | 
000102 |    * A compiled, content-addressed artifact representing a structured epistemic state.
000103 |    * May contain uncertain, partial, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.
000104 |    * Must distinguish artifact validity from assertion validity and certainty.
000105 | 
000106 | 3. **Reference Exchange**
000107 | 
000108 |    * A compiled artifact recognized under one or more authority channels for a declared scope.
000109 |    * Recognition does not erase uncertainty or disagreement.
000110 |    * A Reference Exchange must retain traceability to its source state, validation decisions, and authority recognition records.
000111 | 
000112 | 4. **Kristal Runtime Pack**
000113 | 
000114 |    * A derived, offline-executable indexed form for constrained queries.
000115 |    * Optimized for offline distribution and predictable execution.
000116 |    * Declares its source artifact status, reader policy references, query contract, build metadata, and integrity material.
000117 | 
000118 | 5. **Shard**
000119 | 
000120 |    * A scoped Exchange artifact representing a domain, subdomain, time window, jurisdiction, tenant, environment, or other declared boundary.
000121 |    * Enables smaller offline packages, targeted publication, and distributed authority.
000122 | 
000123 | 6. **Federation Manifest**
000124 | 
000125 |    * A composition artifact that references multiple shards and declares deterministic composition rules.
000126 |    * Does not rewrite shard content, shard identity, or source recognition.
000127 |    * Preserves disagreement unless an explicit reader policy or composition policy selects otherwise.
000128 | 
000129 | 7. **Authority Registry**
000130 | 
000131 |    * Pinned, versioned policy data defining authority channels, trust roots, allowed scopes, required profiles, recognition rules, and revocation policy.
000132 |    * Supports plural authority and scoped recognition.
000133 | 
000134 | 8. **Validation Decision**
000135 | 
000136 |    * A machine-readable record describing the validation status of an artifact, shard, assertion, authority channel, dataset, or runtime pack.
000137 |    * Always declares target, authority channel, validation policy, scope, certainty level, and validated-as mode.
000138 | 
000139 | 9. **Authority Recognition**
000140 | 
000141 |    * A record by which one authority channel recognizes an artifact, shard, assertion, dataset, runtime pack, or another authority channel.
000142 |    * Supports delegated authority, such as one institution recognizing a specialized authority for a domain.
000143 | 
000144 | 10. **Reader Policy**
000145 | 
000146 | * A machine-readable policy defining which validation statuses, certainty levels, authority channels, scopes, and epistemic modes are visible to a reader or application.
000147 | * Enables reference-only, validated-only, high-certainty-only, research, creative, all-with-labels, and custom views.
000148 | 
000149 | ### Conceptual flow
000150 | 
000151 | 1. **Signal / Draft / Dataset / Submission**
000152 | 
000153 |    * Documents, datasets, Wikidata/Wikibase corpora, institutional submissions, research claims, creative corpora, operational signals, human drafts, or extractor outputs.
000154 | 
000155 | 2. **Structured Epistemic State**
000156 | 
000157 |    * Assertions are represented with status, certainty, provenance, evidence, scope, lineage, and policy references.
000158 | 
000159 | 3. **Compile**
000160 | 
000161 |    * A deterministic compiler produces a Working Exchange.
000162 |    * Compilation records build-affecting inputs, compiler identity, policy selections, configuration hashes, and output identities.
000163 | 
000164 | 4. **Review / Validation / Attestation**
000165 | 
000166 |    * Assertions, artifacts, shards, datasets, or authority channels may be reviewed, validated, rejected, disputed, revoked, or recognized.
000167 |    * Validation decisions are scoped and authority-bound.
000168 | 
000169 | 5. **Authority Recognition**
000170 | 
000171 |    * An authority channel may recognize a target as a reference for a declared scope.
000172 |    * Authorities may also recognize other authorities.
000173 | 
000174 | 6. **Reference Exchange**
000175 | 
000176 |    * A Working Exchange may become a Reference Exchange under one or more authority channels.
000177 |    * Reference status is not universal unless explicitly recognized by the relevant authority channels.
000178 | 
000179 | 7. **Federation**
000180 | 
000181 |    * Multiple shards or reference artifacts can be composed without rewriting them.
000182 |    * Composition policies define precedence, conflict behavior, visibility, and reader policy defaults.
000183 | 
000184 | 8. **Runtime Pack**
000185 | 
000186 |    * Offline executable packs are compiled from declared source artifacts.
000187 |    * Packs preserve source status, authority references, validation references, and reader policy metadata.
000188 | 
000189 | 9. **Render / Query / Use**
000190 | 
000191 |    * Architect, Konnaxion, AI systems, readers, and other consumers query or render Kristal data.
000192 |    * Rendering must preserve labels for validation, authority, certainty, disagreement, fiction, mythology, and rejected or disputed status.
000193 | 
000194 | ## Normative core vs profiles
000195 | 
000196 | Kristal v5 is structured as:
000197 | 
000198 | * **Core (normative, required):** artifact identity, deterministic compilation, Structured Epistemic State, assertion status, certainty, validation decisions, authority recognition, federation basics, reader policy hooks, and constrained query behavior.
000199 | * **Profiles (optional, standardized):** advanced features for export, validation, provenance, transparency, pagination, RDF integrity, and high-assurance distribution.
000200 | 
000201 | ### v5 Core includes
000202 | 
000203 | * RFC 8785 (JCS) canonicalization for hashed JSON objects.
000204 | * Explicit hashing material and exclusions.
000205 | * Signatures excluded from hashed payloads.
000206 | * Output ID fields excluded from their own hash targets.
000207 | * `created_at` excluded from content-addressed IDs unless a profile explicitly says otherwise.
000208 | * Standard hash object shape using `alg`, not `algo`.
000209 | * Deterministic build requirements and reproducible manifests.
000210 | * Structured Epistemic State contracts.
000211 | * Assertion status and certainty model.
000212 | * Validation Decision records.
000213 | * Authority Recognition records.
000214 | * Authority Registry contracts.
000215 | * Federation and sharding contracts.
000216 | * Reader Policy contracts.
000217 | * Core schemas and core test vectors.
000218 | * Required verification for declared hashes, signatures, trust roots, compatibility constraints, and revocation policies.
000219 | 
000220 | ### Profiles include
000221 | 
000222 | * JSON-LD export profile.
000223 | * RDF/WDQS-aligned export profile.
000224 | * RDF Integrity profile using RDFC and resource limits.
000225 | * Provenance packaging profile using nanopublication and PROV-O patterns.
000226 | * Validation profiles such as SHACL and ShEx.
000227 | * Query pagination profile with TPF-like semantics.
000228 | * Transparency Log profile for recognition, validation, revocation, and correction events.
000229 | * Reader Policy profiles for reference-only, validated-only, high-certainty, research, creative, and custom views.
000230 | 
000231 | ## Ecosystem integration placement (Orgo × SenTient × Architect × Konnaxion)
000232 | 
000233 | * **Orgo**
000234 | 
000235 |   * Operational control plane for Kristal workflows.
000236 |   * Owns intake, review routing, approvals, audit, lifecycle, release coordination, and operational governance.
000237 |   * Records workflow state, build records, review records, distribution status, and governance events.
000238 | 
000239 | * **SenTient**
000240 | 
000241 |   * Resolver and reconciler for extraction-oriented workflows.
000242 |   * Supports Claim-IR as an extractor proposal profile.
000243 |   * Performs disambiguation, normalization, candidate ranking, and unresolved ambiguity preservation where needed.
000244 |   * Is not required for every Structured Epistemic State.
000245 | 
000246 | * **Architect**
000247 | 
000248 |   * Deterministic renderer consuming Kristal query results and producing traceable outputs.
000249 |   * Must not introduce unsupported facts.
000250 |   * Must preserve labels for certainty, validation, authority channel, recognition status, disputed status, fictional mode, mythological mode, and rejected status.
000251 |   * Must not flatten scoped validation into universal truth.
000252 | 
000253 | * **Konnaxion**
000254 | 
000255 |   * Distribution, offline UX, search, navigation, reader policy, and Runtime Pack access layer.
000256 |   * Handles reader-facing policy selection, caching, versioning, verification, rollback/downgrade rules, and low-bandwidth access.
000257 |   * Allows users, institutions, and applications to choose which authority channels and certainty levels they accept.
000258 | 
000259 | Operational patterns such as circuit breakers, DLQs, CQRS framing, canary/blue-green rollout, structured logs, and correlation IDs are used as **non-normative guidance** for the build and distribution system. They are not embedded into Kristal artifact schemas unless a specific profile declares them.
000260 | 
000261 | ## Document map
000262 | 
000263 | * Overview: `00-overview/`
000264 | * Normative core: `01-core-spec/`
000265 | * Schemas: `02-schemas/`
000266 | * Reproducibility: `03-reproducibility/`
000267 | * Query and reader policy: `04-query/`
000268 | * Profiles: `05-profiles/`
000269 | * Integration contracts: `06-integration/`
000270 | * Security and tenancy: `07-security/`
000271 | * Operational guidance: `08-ops/`
000272 | * Test vectors: `09-test-vectors/`
000273 | * Examples: `10-examples/`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/00-overview/what-is-kristal-v5.md"
id=d27d8f21ccf7
kind=markdown
size=20089
lines=767
line_ref=1-767
chunks=3
chunk_refs=1-350,351-700,701-767
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=d27d8f21ccf7:1-350
start=1
end=350
----
# What is Kristal v5?

## Status

Draft

## Purpose

This document defines Kristal v5 at the overview level: what it is, what it is for, what it is not for, and how its main concepts fit together.

Kristal v5 is a deterministic, portable epistemic artifact system.

It allows claims, hypotheses, references, myths, technical declarations, research claims, institutional corpora, and disputed forks to coexist without confusion.

Validation is scoped.
Authority is plural.
Certainty is explicit.
Readers choose policy.
Federation preserves disagreement.
Integrity protects artifacts.

---

## 1. Definition

A **Kristal** is a portable, verifiable, offline-executable unit of structured epistemic knowledge.

A Kristal is **not** a document, article, database dump, free-text file, or model output. It is a compiled artifact with deterministic identity, explicit provenance, queryable structure, and machine-readable epistemic metadata.

A Kristal can contain:

* factual assertions;
* sourced claims;
* hypotheses;
* unresolved or disputed assertions;
* mythological corpora;
* fictional corpora;
* symbolic models;
* technical specifications;
* publisher declarations;
* research claims;
* institutional references;
* authority recognition records;
* validation decisions;
* provenance and evidence links.

The core responsibility of Kristal v5 is not to guarantee that every assertion inside an artifact is true. Its responsibility is to prevent confusion between different epistemic states.

An assertion may exist without being validated.
An assertion may be validated without being maximally certain.
An assertion may be valid as fiction, mythology, hypothesis, publisher declaration, or high-confidence fact.
An assertion recognized by one authority channel is not automatically recognized by every other authority channel.

---

## 2. Core invariant

Kristal v5 is governed by this invariant:

> A Kristal may contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.
> A Kristal must not present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.

This means artifact existence, artifact integrity, assertion validity, certainty, authority recognition, and reader visibility are distinct.

```text
artifact existence
≠ artifact integrity
≠ assertion validity
≠ certainty
≠ authority recognition
≠ reader visibility
```

A Kristal can be technically valid, content-addressed, reproducible, signed, and queryable while still containing assertions that are low-certainty, disputed, rejected by some authorities, fictional, or mythological.

That is acceptable when the metadata is explicit.

---

## 3. What Kristal v5 is for

Kristal v5 is designed for:

* compiling structured epistemic states into portable artifacts;
* preserving provenance, evidence, certainty, and assertion status;
* supporting plural authority and scoped validation;
* making disagreement visible instead of silently merging it;
* enabling offline knowledge access;
* enabling deterministic query surfaces;
* supporting Wikidata/Wikibase-aligned data models;
* supporting institutional, scientific, civic, cultural, creative, and research corpora;
* allowing people and applications to choose reader policies;
* enabling AI systems to reason over structured, labeled knowledge without flattening authority or certainty.

Kristal v5 is especially useful when knowledge must be:

* portable;
* inspectable;
* versioned;
* queryable;
* reproducible;
* federated;
* provenance-bearing;
* authority-aware;
* usable offline;
* safe to render through AI or deterministic generation systems.

---

## 4. What Kristal v5 is not

Kristal v5 is not:

* a universal truth authority;
* a single global fact database;
* a replacement for scientific, legal, cultural, or institutional review;
* a claim that all included assertions are true;
* a guarantee that all authorities agree;
* a document format for prose;
* a workflow engine;
* a debate platform;
* a user interface;
* a social voting system;
* a full SPARQL engine;
* a replacement for Orgo, Konnaxion, SenTient, or Architect.

Kristal provides artifact contracts and epistemic structure. Other systems handle workflow, distribution, resolution, rendering, governance, and user experience.

---

## 5. The v5 epistemic model

Kristal v5 separates five concerns that are often confused.

### 5.1 Artifact validity

Artifact validity answers:

> Is this artifact well-formed, reproducible, content-addressed, and verifiable under its declared schema and policies?

Artifact validity does not mean every assertion inside the artifact is true.

### 5.2 Assertion status

Assertion status answers:

> What state is this assertion in?

Common assertion statuses include:

* `hypothesis`
* `claimed`
* `sourced`
* `disputed`
* `reviewed`
* `validated`
* `rejected`
* `retracted`
* `superseded`

### 5.3 Certainty level

Certainty answers:

> How strong is this assertion within its declared scope?

Common certainty levels include:

* `unknown`
* `speculative`
* `low`
* `medium`
* `high`
* `established`
* `not_applicable`

`not_applicable` is used when certainty is not the right scale, such as fiction, mythology, symbolic models, or declared publisher descriptions.

### 5.4 Validation

Validation answers:

> Who accepts this assertion or artifact, as what, under which rules, for which scope?

Validation is always scoped.

A claim can be validated as:

* a hypothesis;
* a sourced claim;
* a reviewed claim;
* a high-confidence fact;
* an institutional reference;
* a publisher declaration;
* a technical specification;
* a mythological corpus;
* a fictional corpus;
* a symbolic model;
* a disputed position;
* a rejected claim.

Validation does not always mean high certainty.

### 5.5 Authority recognition

Authority recognition answers:

> Which authority channel recognizes this target, and under what policy?

Authorities may include:

* individuals;
* communities;
* associations;
* research collectives;
* academic institutions;
* standards bodies;
* companies;
* governments;
* intergovernmental organizations;
* AI validators;
* hybrid collectives.

No authority channel has a universal monopoly by default. Recognition by one authority channel does not imply recognition by another.

---

## 6. Authority channels

An **Authority Channel** is a scoped source of recognition.

An authority channel may define:

* who can issue validation decisions;
* what scope it covers;
* which evidence standards it requires;
* which policies apply;
* which trust roots are valid;
* which other authorities it recognizes;
* how revocation works;
* how conflict is handled.

Examples:

```text
authority:unesco
authority:who
authority:microsoft
authority:canada-statistics
authority:local-history-society
authority:flat-earth-association-example
authority:independent-researcher-example
authority:fictional-world-author-example
```

An authority channel may recognize another authority channel for a scope.

For example:

```text
UNESCO may recognize WHO for a health reference scope.
A government may recognize its statistical agency for national demographic data.
A company may be the primary authority for its own published system specifications.
A research institution may recognize a lab for a specific experimental corpus.
```

Authority recognition is explicit, scoped, and revocable.

---

## 7. Reader policies

A **Reader Policy** determines which parts of a Kristal are visible or usable for a reader, application, institution, or AI system.

Reader policies may filter by:

* artifact status;
* assertion status;
* validation status;
* recognition status;
* authority channel;
* certainty level;
* validated-as mode;
* domain;
* subdomain;
* jurisdiction;
* time window;
* fictional mode;
* mythological mode;
* disputed status;
* rejected status;
* revoked status.

Common reader modes include:

* `reference_only`
* `validated_only`
* `high_certainty_only`
* `research`
* `creative`
* `all_with_labels`
* `custom`

A `validated_only` reader policy means all visible assertions satisfy the active reader policy.

It does not mean:

* all visible assertions are universally true;
* all visible assertions have maximum certainty;
* all visible assertions are accepted by every authority;
* all authorities agree.

---

## 8. Claim-IR and Structured Epistemic State

Kristal v5 uses **Structured Epistemic State** as the normative input unit.

A Structured Epistemic State is schema-constrained, provenance-bearing, scope-aware, and explicit about assertion status, certainty, validation references, authority recognition references, and lineage.

It may originate from:

* human authorship;
* institutional datasets;
* collaborative editing;
* Wikidata/Wikibase snapshots;
* research workflows;
* publisher declarations;
* creative worldbuilding;
* mythological corpora;
* automated extraction;
* hybrid human/AI authoring.

**Claim-IR** remains supported, but its role is narrower.

Claim-IR is an extractor proposal profile. It is useful when LLMs, OCR systems, scrapers, parsers, or other extractors propose claims from unstructured sources.

```text
LLM / OCR / parser / scraper
-> Claim-IR
-> Structured Epistemic State
-> Working Exchange
```

But Claim-IR is not the universal required input format.

```text
human expert
-> Structured Epistemic State

--- CHUNK END ---

--- CHUNK BEGIN ---
id=d27d8f21ccf7:351-700
start=351
end=700
----
institutional dataset
-> Structured Epistemic State

Wikidata seed
-> Structured Epistemic State or Exchange-compatible corpus
```

---

## 9. Core artifact families

Kristal v5 defines several artifact families.

### 9.1 Structured Epistemic State

The normative input unit for compilation.

It contains:

* assertions;
* provenance;
* evidence references;
* source references;
* status metadata;
* certainty metadata;
* scope;
* lineage;
* review references;
* validation references;
* authority recognition references;
* policy references.

### 9.2 Working Exchange

A compiled, content-addressed artifact representing a Structured Epistemic State.

A Working Exchange may contain assertions that are:

* uncertain;
* partial;
* disputed;
* fictional;
* mythological;
* speculative;
* incomplete;
* erroneous;
* not yet validated;
* not yet recognized.

Working Exchange existence does not imply reference status.

### 9.3 Reference Exchange

A compiled artifact recognized under one or more authority channels for a declared scope.

Reference status is scoped. A Reference Exchange recognized by one authority channel is not automatically recognized by another.

A Reference Exchange must preserve traceability to its source state, validation decisions, recognition records, and build metadata.

### 9.4 Runtime Pack

A derived offline-executable artifact optimized for constrained queries.

A Runtime Pack declares:

* its source artifact;
* source artifact status;
* query contract;
* reader policy references;
* validation references where applicable;
* authority recognition references where applicable;
* file inventory;
* build metadata;
* integrity metadata.

A Runtime Pack derived from a Working Exchange is not equivalent to one derived from a Reference Exchange.

### 9.5 Shard

A scoped Exchange artifact representing part of a corpus.

A shard may be scoped by:

* domain;
* subdomain;
* jurisdiction;
* tenant;
* environment;
* language;
* time window;
* authority channel;
* dataset boundary.

### 9.6 Federation Manifest

A composition artifact that references multiple shards or exchanges and declares deterministic composition rules.

Federation does not rewrite source shards.

Federation preserves:

* source identity;
* lineage;
* scope;
* authority recognition;
* validation status;
* disagreement.

A federation must not silently merge conflicting assertions as though they agree.

### 9.7 Authority Registry

Pinned, versioned policy data describing:

* authority channels;
* trust roots;
* allowed scopes;
* required profiles;
* recognition rules;
* validation rules;
* revocation policy.

### 9.8 Validation Decision

A machine-readable record that describes validation for a target.

Targets may include:

* assertions;
* artifacts;
* shards;
* datasets;
* authority channels;
* runtime packs.

A validation decision declares:

* target;
* authority channel;
* validation policy;
* scope;
* validation status;
* validated-as mode;
* certainty level;
* findings;
* reason codes;
* signatures where applicable.

### 9.9 Authority Recognition

A record by which one authority channel recognizes a target.

Targets may include:

* assertions;
* artifacts;
* shards;
* datasets;
* runtime packs;
* authority channels.

Authority recognition supports delegated authority and plural validation.

### 9.10 Reader Policy

A machine-readable policy defining what is visible or usable for a reader or application.

Reader Policy is how Kristal supports strict reference views, research views, creative views, institutional views, and custom authority-channel views.

---

## 10. Conceptual flow

Kristal v5 follows this conceptual flow:

```text
Signal / Draft / Dataset / Submission
-> Structured Epistemic State
-> Compile
-> Working Exchange
-> Review / Validation / Attestation / Federation
-> Authority Recognition
-> Reference Exchange
-> Runtime Pack
-> Reader Policy
-> Query / Render / Use
```

This is not a single mandatory workflow. It is a conceptual map.

A project may start from a Wikidata snapshot.
A company may start from its own technical specification.
A researcher may start from an evidence bundle.
A fiction author may start from a fictional world model.
A cultural institution may start from a mythological corpus.
A parser may start from Claim-IR.
A federation may compose multiple shards from different authorities.

The common requirement is that status, certainty, provenance, scope, validation, authority, and lineage remain explicit.

---

## 11. Federation and disagreement

Kristal v5 is designed to make disagreement legible.

Different groups may publish different Kristals about the same domain. Different authorities may recognize different shards. Some assertions may be validated by one authority and rejected by another.

This is allowed.

Federation provides the structure for coexistence:

* source shards keep their identities;
* authority recognition remains scoped;
* conflicts are preserved or handled under explicit policy;
* reader policies decide what is visible by default;
* lineage remains traceable.

A divergent fork may exist. It must not inherit recognition from its source unless that recognition is explicitly granted.

---

## 12. Wikidata alignment

Kristal v5 is designed to be Wikidata/Wikibase-aligned.

A Wikidata Seed Kristal should preserve as much of the source structure as possible, including:

* entities;
* properties;
* statements;
* qualifiers;
* references;
* ranks;
* labels;
* aliases;
* descriptions.

The seed should be understood as Kristal-compatible packaging or alignment of the Wikidata corpus, not as a semantic transformation that changes the meaning of the source data.

Reader policies and export profiles may provide simplified projections, such as truthy or best-rank views, but the source artifact should preserve the richer statement structure where possible.

---

## 13. Integrity and verification

Kristal v5 uses deterministic identity, canonicalization, hashing, signatures, trust roots, manifests, and revocation records to protect artifact integrity.

The v5 canonicalization profile is:

```text
kristal.v5:jcs-rfc8785
```

The v5 canonicalization version is:

```text
1
```

Hash objects use:

```json
{
  "alg": "sha256",
  "value": "<64 lowercase hexadecimal characters>"
}
```

Core hashing rules include:

* use `alg`, not `algo`;
* exclude output ID fields from their own hash targets;
* exclude signatures from primary content hash targets;
* exclude equivalent proof or attestation overlays unless a profile declares otherwise;
* do not let `created_at` affect content-addressed IDs unless explicitly profile-bound.

Integrity verification protects artifact identity and policy satisfaction. It does not itself prove that every assertion is true.

---

## 14. Runtime and offline use

Kristal Runtime Packs are designed for offline and low-bandwidth environments.

Runtime Packs:

* do not require live SPARQL endpoints;
* do not require network access for normal local queries;
* do not require LLMs for execution;
* use constrained query contracts;
* preserve source status and reader policy metadata;
* support predictable local execution;
* can be distributed, cached, activated, rolled back, and versioned by Konnaxion.

Offline use does not remove epistemic labels. The reader still needs to know what is validated, by whom, under which scope, with which certainty, and under which reader policy.

---

## 15. Ecosystem roles

### Kristal

Kristal owns:

* compiled epistemic artifacts;
* artifact identity;
* schemas;
* manifests;
* deterministic compilation contracts;
* assertion status;
* certainty metadata;
* validation decision references;
* authority recognition references;
* query contracts;
* reader policy hooks;
* federation semantics.

### Orgo

Orgo owns:

* workflow;
* intake;
* review routing;
* approvals;
* audit;
* lifecycle control;
* release coordination;
* build records;
* operational governance.

### Konnaxion

Konnaxion owns:

* distribution;
* offline access;
* Runtime Pack activation;
* caching;
* rollback;
* reader surfaces;
* search and navigation;
* user-facing policy selection.

### SenTient

SenTient owns:

* resolution;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=d27d8f21ccf7:701-767
start=701
end=767
----
* disambiguation;
* normalization;
* extraction support;
* Claim-IR profile support;
* ambiguity preservation.

SenTient is useful for extraction and reconciliation workflows, but it is not required for every Structured Epistemic State.

### Architect

Architect owns:

* deterministic rendering;
* traceable summaries;
* multilingual or structured outputs;
* label-preserving generated views.

Architect must not hide authority, certainty, validation status, disputed status, fictional mode, mythological mode, rejection, or revocation when those labels are relevant to the output.

---

## 16. Minimal mental model

A Kristal is not “the truth”.

A Kristal is a structured, portable, verifiable epistemic artifact.

It can contain different kinds of assertions, at different levels of certainty, recognized by different authorities, under different policies, for different scopes.

The important question is not only:

```text
Is this in the Kristal?
```

The important questions are:

```text
What does it claim?
What status does it have?
How certain is it?
Who validates it?
As what?
Under which policy?
For which scope?
Who recognizes it?
Who rejects or disputes it?
Which reader policy is active?
```

Kristal v5 exists to make those answers explicit, portable, queryable, and usable offline.

---

## 17. Document map

* Overview: `00-overview/`
* Normative core: `01-core-spec/`
* Schemas: `02-schemas/`
* Reproducibility: `03-reproducibility/`
* Query and reader policy: `04-query/`
* Profiles: `05-profiles/`
* Integration contracts: `06-integration/`
* Security and tenancy: `07-security/`
* Operational guidance: `08-ops/`
* Test vectors: `09-test-vectors/`
* Examples: `10-examples/`
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/assertion-status-and-certainty.md"
id=cc1ff1f56b82
kind=markdown
size=24555
lines=950
line_ref=1-950
chunks=3
chunk_refs=1-350,351-700,701-950
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=cc1ff1f56b82:1-350
start=1
end=350
----
# Assertion Status and Certainty

## Status

Draft
Spec: Kristal v5
Version: 5.0
Normative: true

## Purpose

This document defines how Kristal v5 represents assertion status, certainty level, validation scope, and authority-bound recognition.

Kristal v5 does not assume that every assertion inside a Kristal has the same epistemic weight. A Kristal may contain hypotheses, claims, sourced statements, reviewed assertions, validated facts, disputed positions, mythological structures, fictional corpora, publisher declarations, technical specifications, rejected claims, or retracted assertions.

The purpose of this specification is to ensure that those different states can coexist without confusion.

The core rule is:

> A Kristal MAY contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.
> A Kristal MUST NOT present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.

## Scope

This document defines:

* assertion status values;
* certainty level values;
* `validated_as` values;
* required assertion-level metadata;
* the distinction between validation, certainty, authority recognition, and reader visibility;
* lifecycle rules for assertion status changes;
* reader-policy implications;
* federation behavior for disputed or divergent assertions.

This document does not define:

* full Exchange manifest structure;
* full Structured Epistemic State structure;
* authority registry schema;
* validation report schema;
* reader policy schema;
* Runtime Pack activation policy;
* user interface rendering rules.

Those are defined by their respective Kristal v5 documents and schemas.

## Core distinction

Kristal v5 separates the following concepts:

```text
artifact existence
≠ artifact integrity
≠ assertion status
≠ certainty level
≠ validation status
≠ authority recognition
≠ reader visibility
```

An artifact can be well-formed, signed, content-addressed, and reproducible while containing assertions that are hypothetical, disputed, fictional, low-certainty, or rejected by a particular authority channel.

The system’s responsibility is not to make every assertion true. The system’s responsibility is to prevent status confusion.

## Assertion

An assertion is a structured statement or claim-like unit inside a Kristal artifact.

An assertion may describe:

* a physical-world fact;
* a historical claim;
* a scientific claim;
* a legal or policy position;
* a technical specification;
* an institutional declaration;
* a research hypothesis;
* a mythological or religious corpus;
* a fictional-world statement;
* a disputed or rejected position;
* a symbolic or interpretive model.

Assertions are not required to be factual claims about the physical world. Their epistemic mode must be explicit when ambiguity is possible.

## Required assertion fields

Every assertion in a Kristal v5 artifact MUST be representable with the following minimum fields:

```json
{
  "assertion_id": "sha256:<hex>",
  "statement": {},
  "assertion_status": "sourced",
  "certainty_level": "medium",
  "validated_as": "sourced_claim",
  "scope": {
    "domain": "general"
  },
  "provenance_refs": [],
  "evidence_refs": [],
  "authority_recognition_refs": [],
  "validation_refs": [],
  "lineage": {}
}
```

The exact shape of `statement` is defined by the artifact type, profile, or schema using the assertion.

## Assertion ID

`assertion_id` is the stable identifier for an assertion.

Recommended form:

```text
sha256:<hex>
```

The assertion ID SHOULD be content-addressed when the assertion can be represented by a deterministic hash target.

The hash target SHOULD exclude:

* signatures;
* transient workflow metadata;
* UI rendering metadata;
* operational logs;
* fields that would cause the identifier to change merely because the assertion was reviewed, rendered, or transported.

When assertion identity depends on a profile-specific hash target, that profile MUST declare the hash target.

## Assertion status

`assertion_status` describes the current epistemic state of the assertion itself.

Allowed values:

```text
hypothesis
claimed
sourced
disputed
reviewed
validated
rejected
retracted
superseded
```

### `hypothesis`

The assertion is explicitly speculative.

Use when:

* the assertion is a research idea;
* the assertion is proposed for investigation;
* evidence is incomplete;
* the assertion is intentionally exploratory.

A hypothesis may be valid as a hypothesis.

A hypothesis MUST NOT be presented as a validated physical-world fact unless a validation decision explicitly changes its status and scope.

### `claimed`

The assertion has been stated by a publisher, source, author, institution, model, extractor, or contributor, but has not yet been sufficiently sourced or reviewed.

Use when:

* the assertion exists as a claim;
* the publisher is known;
* evidence may be absent or not yet assessed.

### `sourced`

The assertion is linked to one or more sources or evidence references.

Use when:

* provenance exists;
* evidence is attached or referenced;
* the assertion has not necessarily been reviewed or validated.

A sourced assertion may still be wrong, outdated, disputed, or low-certainty.

### `disputed`

The assertion is contested by at least one relevant source, reviewer, authority channel, or competing Kristal.

Use when:

* competing assertions exist;
* authority channels disagree;
* evidence conflicts;
* the assertion is known to be controversial within the declared scope.

Disputed assertions SHOULD preserve references to the disagreement.

### `reviewed`

The assertion has been inspected under a declared review process.

Use when:

* human review occurred;
* AI-assisted review occurred;
* institutional review occurred;
* review criteria are recorded.

Reviewed does not automatically mean validated.

### `validated`

The assertion has been accepted under a declared validation policy by a declared authority channel for a declared scope.

A validated assertion MUST declare:

* `validated_as`;
* `certainty_level`;
* `scope`;
* `validation_refs`;
* authority channel through `validation_refs`, `authority_recognition_refs`, or equivalent metadata.

Validation is always scoped.

An assertion MUST NOT be marked `validated` without enough metadata to answer:

```text
validated as what?
validated by whom?
under which policy?
for which scope?
at what certainty level?
```

### `rejected`

The assertion has been rejected by a validation decision, review process, authority channel, or reader policy.

Rejected does not mean the assertion must disappear. It may remain visible in research, audit, dispute, or lineage contexts.

### `retracted`

The publisher or responsible authority has withdrawn the assertion.

Retracted assertions SHOULD preserve lineage and reason codes.

### `superseded`

The assertion has been replaced by a newer assertion.

Superseded assertions SHOULD point to the replacing assertion when possible.

## Certainty level

`certainty_level` describes the strength or applicability of the assertion within its declared scope.

Allowed values:

```text
unknown
speculative
low
medium
high
established
not_applicable
```

### `unknown`

The certainty level has not been evaluated or cannot be determined.

Use when:

* evidence exists but has not been assessed;
* imported data lacks certainty metadata;
* the system cannot infer confidence reliably.

### `speculative`

The assertion is exploratory, conjectural, imaginative, or early-stage.

Use for:

* research hypotheses;
* design proposals;
* speculative models;
* creative exploration.

### `low`

The assertion has weak support, limited evidence, or low confidence.

Use when:

* evidence is thin;
* sources are unreliable;
* review is incomplete;
* the assertion is plausible but fragile.

### `medium`

The assertion has meaningful support but is not yet high-confidence.

Use when:

* sources are credible but incomplete;
* review exists but is limited;
* some disagreement remains;
* confidence is moderate.

### `high`

The assertion has strong support in the declared scope.

Use when:

* evidence is strong;
* review is substantial;
* authority recognition exists;
* disagreement is low or well-addressed.

### `established`

The assertion is stable enough to function as a reference-level assertion in a declared authority channel and scope.

Use when:

* the assertion is broadly recognized by selected authority channels;
* evidence and review are strong;
* the assertion is suitable for default reference views.

`established` MUST NOT be used as a universal truth marker. It is always scoped.

### `not_applicable`

Certainty is not the correct dimension for this assertion.

Use for:

* fictional-world statements;
* mythological corpora;
* symbolic structures;
* religious narratives;
* artistic interpretations;
* publisher declarations;
* technical self-descriptions;
* legal or policy positions where the relevant question is authority or applicability rather than empirical confidence.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=cc1ff1f56b82:351-700
start=351
end=700
----

Example:

```json
{
  "assertion_status": "validated",
  "validated_as": "mythological_corpus",
  "certainty_level": "not_applicable"
}
```

## Validated-as

`validated_as` describes the epistemic mode under which the assertion is accepted.

Allowed values:

```text
hypothesis
claim
sourced_claim
reviewed_claim
high_confidence_fact
institutional_reference
publisher_declaration
technical_specification
legal_or_policy_position
mythological_corpus
fictional_corpus
symbolic_model
disputed_position
rejected_claim
```

### `hypothesis`

The assertion is accepted as a valid hypothesis.

This does not imply that the hypothesis is true.

### `claim`

The assertion is accepted as a claim made by a source or publisher.

### `sourced_claim`

The assertion is accepted as a claim with attached source material.

### `reviewed_claim`

The assertion is accepted as having passed review under a declared process.

### `high_confidence_fact`

The assertion is accepted as a high-confidence factual assertion within the declared scope.

This status SHOULD require strong provenance, evidence, review, and authority support.

### `institutional_reference`

The assertion is accepted as reference material by an institution or recognized authority channel.

Example:

```json
{
  "authority_channel": "authority:who",
  "validated_as": "institutional_reference",
  "scope": {
    "domain": "health"
  }
}
```

### `publisher_declaration`

The assertion is accepted as the publisher’s declared position or description.

Example:

A company may publish a Kristal describing its own system. The assertion may be validated as the company’s declaration without implying that all external claims about safety, impact, performance, or public value are independently validated.

### `technical_specification`

The assertion is accepted as a technical specification.

Use for:

* APIs;
* schemas;
* system contracts;
* protocol definitions;
* implementation requirements.

### `legal_or_policy_position`

The assertion is accepted as a legal, regulatory, governance, or policy position.

This does not automatically imply empirical truth. It means the position is recognized within the declared legal, institutional, or policy scope.

### `mythological_corpus`

The assertion is accepted as part of a mythological, religious, symbolic, cultural, or narrative corpus.

It MUST NOT be silently presented as a validated physical-world fact.

### `fictional_corpus`

The assertion is accepted as part of a fictional world or creative corpus.

It MUST NOT be silently presented as a validated physical-world fact.

### `symbolic_model`

The assertion is accepted as symbolic, interpretive, conceptual, or metaphorical.

### `disputed_position`

The assertion is accepted as a position that exists in a dispute.

This does not mean the assertion is accepted as fact.

### `rejected_claim`

The assertion is accepted as a claim that has been rejected by a declared authority, policy, review, or validation decision.

Rejected claims may still be preserved for audit, education, dispute mapping, lineage, or research.

## Validation status vs assertion status

`assertion_status` describes the assertion itself.

`validation_status` describes the outcome of a validation process.

Allowed validation status values are defined in the validation report and validation decision specifications:

```text
not_evaluated
in_review
validated
conditionally_validated
disputed
rejected
revoked
```

An assertion may have:

```json
{
  "assertion_status": "hypothesis",
  "validation_status": "validated",
  "validated_as": "hypothesis"
}
```

This means the assertion is validated as a hypothesis, not as an established fact.

## Authority recognition

Authority recognition describes whether an authority channel recognizes an assertion, artifact, shard, dataset, runtime pack, or another authority channel.

Recognition is not universal.

Recognition by one authority channel MUST NOT imply recognition by another authority channel.

Example:

```json
{
  "assertion_status": "validated",
  "certainty_level": "high",
  "validated_as": "high_confidence_fact",
  "authority_recognition_refs": [
    {
      "id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "artifact_type": "authority_recognition"
    }
  ],
  "scope": {
    "domain": "science",
    "subdomain": "astronomy"
  }
}
```

## Reader visibility

Reader visibility is controlled by reader policy.

An assertion may exist in a Kristal but be hidden, marked, downgraded, or excluded from a particular reader view.

Reader policies may filter by:

* `assertion_status`;
* `certainty_level`;
* `validated_as`;
* `validation_status`;
* `authority_channel`;
* `recognition_status`;
* `scope.domain`;
* `scope.subdomain`;
* disputed status;
* fictional status;
* mythological status.

A reader policy MUST NOT change the underlying assertion. It only controls visibility and presentation.

## “Validated-only” does not mean maximum certainty

A reader policy may show only validated assertions.

This does not mean every visible assertion has maximum certainty.

“Validated-only” means:

```text
all visible assertions satisfy the active reader policy’s validation requirements
```

It does not mean:

```text
all visible assertions are universally true
all visible assertions have maximum certainty
all authorities agree
all assertions describe physical-world facts
```

Example:

```json
{
  "reader_policy_id": "reader_policy:validated_only",
  "mode": "validated_only",
  "allowed_validation_statuses": [
    "validated",
    "conditionally_validated"
  ],
  "allowed_certainty_levels": [
    "unknown",
    "speculative",
    "low",
    "medium",
    "high",
    "established",
    "not_applicable"
  ],
  "show_labels": true
}
```

This policy allows validated assertions at multiple certainty levels, provided their labels remain visible.

## Status transitions

Kristal v5 does not require a single universal assertion lifecycle.

However, implementations SHOULD preserve a transition history when assertion status changes.

Common transitions include:

```text
hypothesis -> claimed
claimed -> sourced
sourced -> reviewed
reviewed -> validated
validated -> disputed
validated -> superseded
validated -> revoked
disputed -> reviewed
disputed -> rejected
rejected -> superseded
claimed -> retracted
```

Implementations MUST NOT erase prior status when it is needed for audit, lineage, dispute analysis, reproducibility, or authority comparison.

## Transition record

A status transition SHOULD be recorded as:

```json
{
  "transition_id": "sha256:<hex>",
  "assertion_id": "sha256:<hex>",
  "from_status": "sourced",
  "to_status": "reviewed",
  "changed_at": "2026-01-07T12:34:56Z",
  "changed_by": {
    "authority_channel": "authority:example-review-body"
  },
  "reason_codes": [
    "evidence_sufficient",
    "policy_satisfied"
  ],
  "evidence_refs": [],
  "validation_refs": [],
  "signatures": []
}
```

Transition records MAY be stored in review bundles, validation reports, authority recognition artifacts, transparency logs, or artifact lineage.

## Reason codes

Reason codes SHOULD use stable bounded strings.

Recommended values:

```text
schema_valid
schema_invalid
provenance_sufficient
provenance_insufficient
evidence_sufficient
evidence_insufficient
authority_recognized
authority_not_recognized
scope_mismatch
policy_satisfied
policy_failed
signature_valid
signature_invalid
hash_valid
hash_invalid
conflict_detected
disagreement_preserved
certainty_too_low_for_policy
rejected_by_authority_channel
revoked_by_authority_channel
reader_policy_filtered
reader_policy_unsupported
projection_unavailable
profile_execution_failed
timeout
memory_limit_exceeded
access_denied
```

## Federation behavior

Federation MUST preserve disagreement.

If two Kristals contain incompatible assertions, federation MUST NOT silently merge them into a single assertion unless an explicit composition policy permits the merge and preserves lineage.

When assertions conflict, a federation manifest or composition policy SHOULD use one of the following strategies:

```text
preserve_disagreement
--- CHUNK END ---

--- CHUNK BEGIN ---
id=cc1ff1f56b82:701-950
start=701
end=950
----
authority_precedence
mark_disputed
exclude_conflict
require_reader_choice
```

Default v5 behavior SHOULD be:

```text
preserve_disagreement
```

## Divergent forks

Divergent forks are allowed.

A forked Kristal may contain assertions rejected by another authority channel.

A fork MUST preserve lineage when derived from another artifact.

A fork MUST NOT inherit validation or recognition from the source unless that recognition explicitly applies to the fork.

Example:

```json
{
  "assertion_id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "statement": {
    "subject": "earth",
    "predicate": "shape",
    "object": "flat"
  },
  "assertion_status": "validated",
  "certainty_level": "low",
  "validated_as": "disputed_position",
  "scope": {
    "domain": "science",
    "subdomain": "astronomy"
  },
  "authority_recognition_refs": [
    {
      "id": "authority:example-flat-earth-association",
      "artifact_type": "authority_recognition"
    }
  ],
  "validation_refs": [],
  "lineage": {
    "derived_from": []
  }
}
```

This assertion may be valid as a disputed position within a specific authority channel. It must not be presented as established scientific reference unless a reader policy and authority channel explicitly choose that interpretation.

## Mythology and fiction

A mythology or fiction Kristal may be valid as mythology or fiction.

Example:

```json
{
  "assertion_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "statement": {
    "subject": "unicorn",
    "predicate": "appears_in",
    "object": "medieval_bestiary"
  },
  "assertion_status": "validated",
  "certainty_level": "not_applicable",
  "validated_as": "mythological_corpus",
  "scope": {
    "domain": "mythology",
    "subdomain": "medieval-symbolic-animals"
  }
}
```

This means the assertion is valid within a mythological or cultural corpus. It does not mean the system treats unicorns as physical-world animals.

## Publisher declarations

A publisher declaration can be valid as a declaration without validating every external implication of the declaration.

Example:

```json
{
  "assertion_id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
  "statement": {
    "subject": "example-system",
    "predicate": "supports_feature",
    "object": "offline_query"
  },
  "assertion_status": "validated",
  "certainty_level": "not_applicable",
  "validated_as": "publisher_declaration",
  "scope": {
    "domain": "technology",
    "subdomain": "system-documentation"
  },
  "authority_recognition_refs": [
    {
      "id": "authority:example-publisher",
      "artifact_type": "authority_recognition"
    }
  ]
}
```

Other authorities may separately validate performance, safety, interoperability, security, or environmental claims.

## Wikidata seed assertions

A Wikidata Seed Kristal SHOULD preserve source structure as much as possible, including:

* entities;
* properties;
* statements;
* qualifiers;
* references;
* ranks;
* labels;
* aliases;
* descriptions.

Imported Wikidata assertions SHOULD NOT automatically be treated as universally established facts.

A Wikidata Seed Kristal may validate the corpus packaging, lineage, and source identity while preserving mixed assertion certainty.

Example:

```json
{
  "assertion_id": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "statement": {
    "subject": "Q42",
    "predicate": "P31",
    "object": "Q5"
  },
  "assertion_status": "sourced",
  "certainty_level": "medium",
  "validated_as": "sourced_claim",
  "scope": {
    "domain": "wikidata"
  },
  "provenance_refs": [
    {
      "id": "wikidata:Q42",
      "artifact_type": "external_dataset"
    }
  ]
}
```

## Conformance requirements

A conforming Kristal v5 implementation MUST:

1. Support `assertion_status`.
2. Support `certainty_level`.
3. Support `validated_as` when assertions are validated, reviewed, rejected, fictional, mythological, symbolic, or scoped by authority.
4. Preserve assertion-level provenance references.
5. Preserve assertion-level evidence references when available.
6. Preserve validation references when a validation decision exists.
7. Preserve authority recognition references when recognition exists.
8. Prevent unqualified `validated = true` semantics.
9. Support reader-policy filtering without mutating assertion status.
10. Preserve disagreement during federation unless an explicit composition policy declares otherwise.
11. Avoid presenting scoped validation as universal truth.
12. Avoid presenting fiction, mythology, symbolic models, or publisher declarations as physical-world facts unless an explicit authority channel validates that epistemic mode.

## Non-conforming patterns

The following patterns are non-conforming:

```json
{
  "validated": true
}
```

Reason: validation is unscoped.

```json
{
  "assertion_status": "validated"
}
```

Reason: validated as what, by whom, under which policy, for which scope, and at what certainty level are not declared.

```json
{
  "certainty_level": "established",
  "scope": {}
}
```

Reason: established status requires declared scope.

```json
{
  "validated_as": "fictional_corpus",
  "certainty_level": "high"
}
```

Reason: fictional validity should normally use `not_applicable`, unless a profile explicitly defines a different interpretation.

```json
{
  "assertion_status": "validated",
  "validated_as": "publisher_declaration",
  "scope": {
    "domain": "technology"
  }
}
```

Reason: publisher declaration needs publisher or authority-channel context.

## Recommended rendering rule

Any rendering system, including Architect, browsers, AI agents, dashboards, and Runtime Pack readers, SHOULD preserve the following labels when they are relevant:

```text
assertion_status
certainty_level
validated_as
validation_status
authority_channel
recognition_status
scope
disputed status
fictional or mythological status
```

A rendering system MUST NOT flatten scoped validation into universal truth.

## Summary

Kristal v5 treats assertion status and certainty as first-class epistemic metadata.

Validation is scoped.
Authority is plural.
Certainty is explicit.
Reader policy controls visibility.
Federation preserves disagreement.
Integrity protects artifacts, not ideology.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/authority-recognition.md"
id=dd81676442c2
kind=markdown
size=33494
lines=1545
line_ref=1-1545
chunks=5
chunk_refs=1-350,351-700,701-1050,1051-1400,1401-1545
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=dd81676442c2:1-350
start=1
end=350
----
# Authority Recognition

## Status

Draft. Normative core specification for Kristal v5.

## Spec

```text
Spec: Kristal v5
Version: 5.0
Normative: true
```

## Purpose

Authority recognition defines how a Kristal v5 authority channel accepts, rejects, disputes, delegates, revokes, or conditionally recognizes a target.

A target may be:

```text
artifact
shard
assertion
authority_channel
dataset
runtime_pack
reader_policy
validation_decision
```

Authority recognition answers:

```text
Who recognizes this target?
As what?
For which scope?
Under which policy?
With which evidence?
For how long?
With which revocation path?
```

Authority recognition does **not** define universal truth.

Recognition by one authority channel does not imply recognition by another authority channel. Kristal v5 supports plural authority, scoped recognition, disagreement preservation, and reader-selected trust policies.

---

## Core principle

Kristal v5 separates:

```text
artifact existence
artifact integrity
assertion status
certainty level
validation decision
authority recognition
reader visibility
```

An artifact MAY exist, be signed, hash-valid, queryable, and distributable without being recognized by any authority channel.

An assertion MAY be valid as a hypothesis, mythological corpus, fictional corpus, publisher declaration, disputed position, technical specification, institutional reference, or high-confidence factual claim.

Authority recognition MUST always be scoped.

A recognition record MUST NOT silently convert scoped recognition into universal truth.

---

## Definitions

### Authority channel

An authority channel is a declared source of recognition for a scope.

Examples:

```text
authority:unesco-global-reference
authority:who-health
authority:microsoft-product-docs
authority:local-school-board
authority:research-lab-example
authority:mythology-archive
authority:community-review-group
```

An authority channel can represent an institution, government, association, company, standards body, research collective, community, AI validator, individual, or hybrid collective.

Authority channels are declared in an Authority Registry.

---

### Authority recognition

An authority recognition is a signed or otherwise verifiable record stating that one authority channel recognizes a target under declared rules.

It may recognize:

```text
a Kristal artifact
a shard
an assertion
another authority channel
a dataset
a runtime pack
a validation decision
a reader policy
```

Recognition is not an assertion that the target is universally true.

It is a scoped statement of acceptance by the issuing authority channel.

---

### Validation decision

A validation decision records the outcome of applying a validation policy.

It answers:

```text
Was this target evaluated?
What status was assigned?
What was it validated as?
At what certainty level?
Under which policy?
By which authority channel?
```

A validation decision may be used as evidence for authority recognition, but it is not identical to authority recognition.

---

### Reader policy

A reader policy determines what a reader, application, runtime, AI system, or user-facing surface chooses to show.

A reader policy may use authority recognition as an input.

Reader policy decides visibility. Authority recognition decides scoped acceptance.

---

## Required invariant

The following invariant applies across all Kristal v5 files, schemas, profiles, manifests, and examples:

```text
A Kristal may contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.

A Kristal must not present an assertion as validated or recognized outside the authority channel, scope, certainty level, and validation policy that support that status.
```

---

## Recognition targets

A recognition record MUST declare a `target_level`.

Allowed values:

```text
artifact
shard
assertion
authority_channel
dataset
runtime_pack
reader_policy
validation_decision
```

### `artifact`

Recognition applies to a whole Kristal artifact, such as an Exchange or Reference Artifact.

This does not imply that every assertion inside the artifact has the same certainty level.

### `shard`

Recognition applies to a shard.

This is useful for domain, jurisdiction, dataset, tenant, time-window, or authority-specific partitions.

### `assertion`

Recognition applies to one assertion.

This is the most precise recognition target.

### `authority_channel`

Recognition applies to another authority channel.

This enables delegated or federated authority.

Example:

```text
authority:unesco-global-reference recognizes authority:who-health for health reference material.
```

### `dataset`

Recognition applies to a dataset or external corpus.

Example:

```text
authority:example recognizes Wikidata Seed Kristal as a seed reference corpus.
```

### `runtime_pack`

Recognition applies to a Runtime Pack.

This means the pack is recognized for a scope or channel. It does not imply that runtime activation equals assertion validation.

### `reader_policy`

Recognition applies to a reader policy.

Example:

```text
authority:school-board recognizes reader_policy:curriculum-reference-only for school use.
```

### `validation_decision`

Recognition applies to a validation decision.

This allows an authority channel to accept the result of another validator or review process.

---

## Recognition status

Authority recognition status MUST use one of the following values:

```text
recognized
conditionally_recognized
under_review
disputed
rejected
deprecated
revoked
```

### `recognized`

The issuing authority channel accepts the target under the declared scope and policy.

### `conditionally_recognized`

The target is accepted only under declared conditions.

Conditions MUST be explicit.

### `under_review`

The authority channel has not reached a final recognition status.

### `disputed`

The authority channel records a dispute, unresolved objection, competing interpretation, or conflict.

### `rejected`

The authority channel rejects the target for the declared scope.

### `deprecated`

The authority channel no longer recommends the target for new use, but does not necessarily revoke historical recognition.

### `revoked`

The authority channel withdraws prior recognition.

Revocation MUST preserve enough information to identify what was revoked and why.

---

## Recognized as

The `recognized_as` field states what the target is recognized as.

Allowed values:

```text
hypothesis
claim
sourced_claim
reviewed_claim
high_confidence_fact
institutional_reference
publisher_declaration
technical_specification
legal_or_policy_position
mythological_corpus
fictional_corpus
symbolic_model
disputed_position
rejected_claim
```

Recognition MUST NOT omit `recognized_as`.

Recognition does not always imply high certainty.

Examples:

```text
recognized_as = "hypothesis"
recognized_as = "mythological_corpus"
recognized_as = "publisher_declaration"
recognized_as = "technical_specification"
recognized_as = "institutional_reference"
recognized_as = "high_confidence_fact"
```

A mythology Kristal can be recognized as mythology.

A fictional Kristal can be recognized as fiction.

A company’s system description can be recognized as a publisher declaration.

A scientific claim can be recognized as a high-confidence fact only under a policy and authority channel that support that status.

---

## Scope

Every authority recognition MUST declare a scope.

A scope MUST include `domain`.

Recommended scope shape:

```json
{
  "domain": "health",
  "subdomain": "clinical-guidelines",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=dd81676442c2:351-700
start=351
end=700
----
  "jurisdiction": null,
  "time_window": null,
  "tenant_id": null,
  "environment": null,
  "language": "en"
}
```

Allowed top-level domains:

```text
general
wikidata
science
health
education
heritage
law
policy
technology
environment
culture
mythology
fiction
research
operations
civic
local_notes
```

Recognition outside the declared scope MUST NOT be inferred.

---

## Authority delegation

Authority channels MAY recognize other authority channels.

This enables scoped delegation.

Example:

```text
authority:unesco-global-reference
  recognizes authority:who-health
  for domain = "health"
  recognized_as = "institutional_reference"
```

Delegated authority MUST be explicit.

Recognition of an authority channel MUST declare:

```text
issuer_authority_channel
target authority_channel
scope
recognition_status
recognized_as
validation_policy_ref
created_at
```

Recognition of an authority channel does not grant authority outside the declared scope.

Authority delegation is not transitive by default.

If transitive recognition is allowed, the policy MUST explicitly declare:

```text
transitive = true
max_depth
allowed_target_types
allowed_scope_constraints
```

Default:

```text
transitive = false
```

---

## Recognition and validation

Authority recognition and validation decisions are related but distinct.

A validation decision may say:

```text
This assertion was reviewed and validated as a high-confidence fact by authority:example-health under policy P.
```

An authority recognition may say:

```text
authority:unesco-global-reference recognizes authority:example-health as competent for domain health.
```

or:

```text
authority:unesco-global-reference recognizes this health shard as an institutional reference because it was validated by authority:who-health.
```

A recognition record MAY reference validation decisions.

A recognition record MUST NOT replace validation decisions when the validation outcome itself is required.

---

## Recognition and certainty

Recognition MUST NOT be treated as maximum certainty.

Recognition states that an authority accepts a target as something.

Certainty states how strong the assertion is within its scope.

Examples:

```json
{
  "recognition_status": "recognized",
  "recognized_as": "hypothesis",
  "certainty_level": "speculative"
}
```

```json
{
  "recognition_status": "recognized",
  "recognized_as": "mythological_corpus",
  "certainty_level": "not_applicable"
}
```

```json
{
  "recognition_status": "recognized",
  "recognized_as": "high_confidence_fact",
  "certainty_level": "high"
}
```

If certainty is represented in a recognition record, it MUST use the Kristal v5 certainty ladder:

```text
unknown
speculative
low
medium
high
established
not_applicable
```

---

## Recognition and federation

Federation composes multiple Kristals, shards, or authority channels without silently merging their claims.

Recognition is a key input to federation.

A federation manifest MAY use recognition records to decide:

```text
which shards are included
which shards are visible by default
which authority channel has precedence for a given scope
which disagreements must be preserved
which claims are marked disputed
which claims are excluded by a reader policy
```

Federation MUST preserve attribution.

Federation MUST NOT erase disagreement.

Federation MUST NOT make one authority’s recognition appear to be another authority’s recognition.

---

## Recognition and reader policy

Reader policies MAY use authority recognition to determine visibility.

Examples:

```text
reference_only
validated_only
high_certainty_only
research
creative
all_with_labels
custom
```

A `validated_only` or `reference_only` reader policy MAY require recognition from selected authority channels.

Example:

```json
{
  "reader_policy_id": "reader_policy:validated_only",
  "allowed_authority_channels": [
    "authority:unesco-global-reference",
    "authority:who-health"
  ],
  "allowed_recognition_statuses": [
    "recognized",
    "conditionally_recognized"
  ],
  "show_labels": true
}
```

A reader policy MUST NOT hide recognition scope when showing recognized material.

A reader policy MUST NOT flatten scoped recognition into universal truth.

---

## Recognition object

A recognition record SHOULD use this shape.

```json
{
  "schema_version": "5.0",
  "artifact_type": "authority_recognition",
  "recognition_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
  "created_at": "2026-06-12T00:00:00Z",
  "expires_at": null,

  "issuer_authority_channel": "authority:example",
  "target_ref": {
    "artifact_type": "reference_exchange",
    "artifact_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
  },
  "target_level": "artifact",

  "recognition_status": "recognized",
  "recognized_as": "institutional_reference",
  "certainty_level": "high",

  "scope": {
    "domain": "education",
    "subdomain": "curriculum",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": null,
    "language": "en"
  },

  "validation_policy_ref": {
    "policy_id": "kristal.v5:validation-policy:example",
    "policy_version": "1"
  },

  "evidence_refs": [],
  "validation_decision_refs": [],
  "reason_codes": [
    "authority_recognized",
    "policy_satisfied"
  ],

  "content_hash": {
    "alg": "sha256",
    "value": "2222222222222222222222222222222222222222222222222222222222222222"
  },

  "signatures": []
}
```

---

## Required fields

An authority recognition record MUST include:

```text
schema_version
artifact_type
recognition_id
created_at
issuer_authority_channel
target_ref
target_level
recognition_status
recognized_as
scope
validation_policy_ref
reason_codes
content_hash
signatures
```

`expires_at` MAY be `null`.

`certainty_level` SHOULD be included when recognition concerns assertions, datasets, shards, or artifacts whose epistemic strength matters.

`validation_decision_refs` SHOULD be included when recognition relies on validation decisions.

`evidence_refs` SHOULD be included when recognition relies on external evidence.

---

## Field definitions

### `schema_version`

MUST be:

```text
5.0
```

### `artifact_type`

MUST be:

```text
authority_recognition
```

### `recognition_id`

Content-addressed ID of the recognition record.

Recommended form:

```text
sha256:<hex>
```

The `recognition_id` field itself MUST be excluded from its own hash target.

### `created_at`

RFC3339 timestamp.

Timestamps MUST NOT affect content-addressed IDs unless the profile explicitly includes them in the hash target.

### `expires_at`
--- CHUNK END ---

--- CHUNK BEGIN ---
id=dd81676442c2:701-1050
start=701
end=1050
----

Optional RFC3339 timestamp or `null`.

If present, recognition SHOULD be treated as inactive after expiry unless a reader policy or authority policy explicitly allows historical use.

### `issuer_authority_channel`

Authority channel issuing the recognition.

Pattern:

```text
authority:<slug>
```

### `target_ref`

Reference to the target being recognized.

The target may be content-addressed, URI-addressed, or both.

### `target_level`

Level at which recognition applies.

Allowed values:

```text
artifact
shard
assertion
authority_channel
dataset
runtime_pack
reader_policy
validation_decision
```

### `recognition_status`

Status assigned by the issuer.

Allowed values:

```text
recognized
conditionally_recognized
under_review
disputed
rejected
deprecated
revoked
```

### `recognized_as`

What the target is recognized as.

Allowed values:

```text
hypothesis
claim
sourced_claim
reviewed_claim
high_confidence_fact
institutional_reference
publisher_declaration
technical_specification
legal_or_policy_position
mythological_corpus
fictional_corpus
symbolic_model
disputed_position
rejected_claim
```

### `certainty_level`

Optional but recommended.

Allowed values:

```text
unknown
speculative
low
medium
high
established
not_applicable
```

### `scope`

Declared recognition scope.

Recognition MUST NOT be applied outside this scope unless another recognition record explicitly extends it.

### `validation_policy_ref`

Reference to the policy used to issue recognition.

### `evidence_refs`

References to supporting evidence, documents, datasets, observations, audits, expert reviews, or external artifacts.

### `validation_decision_refs`

References to validation decisions used as input to recognition.

### `reason_codes`

Stable reason codes explaining the recognition outcome.

### `content_hash`

Hash of the canonicalized recognition hash target.

Use:

```json
{
  "alg": "sha256",
  "value": "<64 lowercase hex chars>"
}
```

Use `alg`, not `algo`.

### `signatures`

Signatures over the canonicalized recognition hash target.

Signatures MUST be excluded from the signed hash target.

---

## Recommended reason codes

Recognition reason codes SHOULD use stable strings.

Recommended codes:

```text
authority_recognized
authority_not_recognized
authority_delegated
authority_delegation_expired
scope_satisfied
scope_mismatch
policy_satisfied
policy_failed
provenance_sufficient
provenance_insufficient
evidence_sufficient
evidence_insufficient
validation_decision_accepted
validation_decision_missing
validation_decision_rejected
signature_valid
signature_invalid
hash_valid
hash_invalid
conflict_detected
disagreement_preserved
certainty_too_low_for_policy
recognized_by_parent_authority
rejected_by_authority_channel
revoked_by_authority_channel
expired
superseded
```

Reason codes SHOULD be machine-readable.

Human-readable explanations MAY be provided in `notes`.

---

## Recognition lifecycle

A recognition record MAY move through these states:

```text
under_review
recognized
conditionally_recognized
disputed
deprecated
revoked
```

A recognition record SHOULD NOT be mutated in place after publication if it is content-addressed.

Instead, later records SHOULD reference earlier records using:

```text
supersedes
revokes
replaces
derived_from
```

A revoked recognition remains part of history, but reader policies SHOULD treat it according to revocation rules.

---

## Revocation

Authority recognition can be revoked.

A revocation MUST identify:

```text
the recognition being revoked
the authority channel issuing the revocation
the reason codes
the effective time
the signature or trust root authorizing revocation
```

Revocation does not delete the earlier recognition record.

Revocation changes how the recognition is interpreted.

A revocation SHOULD use the Kristal v5 revocation schema when available.

---

## Expiry

Recognition MAY expire.

If `expires_at` is set, consumers SHOULD treat the recognition as inactive after that time unless the reader policy explicitly allows historical recognition.

Expired recognition SHOULD NOT be silently treated as active recognition.

---

## Conditional recognition

A conditionally recognized target MUST declare conditions.

Recommended shape:

```json
{
  "recognition_status": "conditionally_recognized",
  "conditions": [
    {
      "condition_id": "condition:example",
      "description": "Recognized only for educational use, not clinical use.",
      "scope": {
        "domain": "education"
      },
      "expires_at": null
    }
  ]
}
```

Conditions MUST be visible to readers, validators, and federation policies.

---

## Conflicting recognitions

Multiple authority channels may issue conflicting recognitions.

Example:

```text
authority:A recognizes target X.
authority:B rejects target X.
authority:C marks target X disputed.
```

This is valid.

Kristal v5 MUST preserve the conflict.

Conflict resolution belongs to:

```text
federation composition policy
reader policy
authority registry policy
application policy
```

A conflict MUST NOT be silently collapsed into a single universal answer.

---

## Recognition inheritance

Recognition does not automatically inherit across:

```text
forks
derived artifacts
runtime packs
federations
translations
summaries
exports
reader projections
```

Recognition inheritance MAY occur only when an explicit policy permits it.

If recognition is inherited, the inheritance policy MUST declare:

```text
source recognition
target artifact
transform type
allowed scope
loss conditions
reason codes
```

Default:

```text
recognition_inheritance = false
```

---

## Recognition of forks

A forked Kristal MAY preserve lineage to the source artifact.

It MUST NOT inherit recognition from the source unless an authority channel explicitly recognizes the fork or a policy explicitly permits recognition inheritance.

A fork SHOULD declare:

```text
source artifact
fork author
fork reason
changed assertions
authority channel
scope
reader policy implications
```

Divergent forks are allowed.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=dd81676442c2:1051-1400
start=1051
end=1400
----

Divergent forks MUST preserve attribution and recognition boundaries.

---

## Recognition of fiction, mythology, and symbolic material

A fiction, mythology, or symbolic Kristal MAY be recognized.

Examples:

```text
recognized_as = "fictional_corpus"
recognized_as = "mythological_corpus"
recognized_as = "symbolic_model"
certainty_level = "not_applicable"
```

Such recognition MUST NOT be presented as validation of physical-world truth unless an authority channel explicitly recognizes that epistemic mode.

Reader policies SHOULD allow users to include or exclude these scopes.

---

## Recognition of publisher declarations

A publisher MAY be the appropriate authority for its own declarations.

Example:

```text
authority:microsoft-product-docs recognizes a system documentation Kristal as publisher_declaration.
```

This means the publisher declares the system behavior.

It does not automatically mean:

```text
the system is safe
the system is compliant
the system is environmentally sound
the system has no security issues
```

Other authority channels may recognize, dispute, audit, or reject those aspects under their own scopes.

---

## Recognition of institutional references

An institutional reference is a target recognized by an authority channel for broad use in a declared scope.

Example:

```text
authority:who-health recognizes a medical guideline shard as institutional_reference for health.
```

Another authority may then recognize the authority channel itself:

```text
authority:unesco-global-reference recognizes authority:who-health for health education references.
```

This creates layered recognition without requiring one authority to inspect every assertion directly.

---

## Recognition record hash target

The content hash of an authority recognition record MUST exclude:

```text
recognition_id
content_hash
signatures
runtime cache data
operational logs
non-declared external fetch results
```

The content hash SHOULD include:

```text
schema_version
artifact_type
created_at
expires_at
issuer_authority_channel
target_ref
target_level
recognition_status
recognized_as
certainty_level
scope
validation_policy_ref
evidence_refs
validation_decision_refs
reason_codes
conditions
lineage
extensions if declared hash-relevant
```

Hashing MUST use:

```text
canonicalization_profile = kristal.v5:jcs-rfc8785
canonicalization_version = 1
hash_alg = sha256
```

---

## Signature requirements

Authority recognition records SHOULD be signed by the issuing authority channel.

A signature MUST declare:

```text
key_id
alg
signature
created_at
```

Recommended signature algorithm:

```text
ed25519
```

Use `alg`, not `algo`.

The signer SHOULD be resolvable through the Authority Registry or another declared trust root.

Signatures are excluded from their own hash target.

---

## Authority Registry relationship

The Authority Registry declares authority channels, trust roots, scopes, validation policies, revocation policies, and recognition constraints.

Authority recognition records SHOULD reference authority channels declared in an Authority Registry.

A consumer MAY reject or mark recognition as untrusted if:

```text
issuer_authority_channel is unknown
issuer authority is outside scope
required trust roots are missing
signature verification fails
authority registry is stale beyond policy limits
revocation data is unavailable when required
```

Unknown authority does not make the target false.

It means the recognition is not accepted under the consumer’s active policy.

---

## Query requirements

Kristal v5 query systems SHOULD support filters for authority recognition.

Recommended filters:

```text
issuer_authority_channel
target_level
target_ref
recognition_status
recognized_as
certainty_level
scope.domain
scope.subdomain
scope.jurisdiction
validation_policy_ref
created_at
expires_at
reason_codes
include_expired
include_revoked
include_disputed
```

Query results SHOULD preserve enough metadata to show:

```text
who recognized the target
what was recognized
as what
for which scope
under which policy
with what status
```

---

## Rendering requirements

Architect, reader, and application renderers MUST NOT flatten authority recognition into universal truth.

Rendered summaries SHOULD preserve:

```text
recognition_status
recognized_as
issuer_authority_channel
scope
certainty_level
validation_policy_ref
dispute/revocation/expiry indicators
```

Examples of acceptable labels:

```text
Recognized by authority:who-health as institutional_reference for health.
Recognized by authority:mythology-archive as mythological_corpus.
Rejected by authority:example-science-channel for physical-world claim scope.
Under review by authority:local-board for education/curriculum.
```

Examples of unacceptable labels:

```text
True.
Official truth.
Validated everywhere.
Canonical.
Universally accepted.
```

---

## Minimal example: authority recognizes another authority

```json
{
  "schema_version": "5.0",
  "artifact_type": "authority_recognition",
  "recognition_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "created_at": "2026-06-12T00:00:00Z",
  "expires_at": null,
  "issuer_authority_channel": "authority:unesco-global-reference",
  "target_ref": {
    "artifact_type": "authority_channel",
    "artifact_id": "authority:who-health"
  },
  "target_level": "authority_channel",
  "recognition_status": "recognized",
  "recognized_as": "institutional_reference",
  "certainty_level": "not_applicable",
  "scope": {
    "domain": "health",
    "subdomain": "public-health-guidance",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": null,
    "language": "en"
  },
  "validation_policy_ref": {
    "policy_id": "kristal.v5:authority-recognition:institutional-delegation",
    "policy_version": "1"
  },
  "evidence_refs": [],
  "validation_decision_refs": [],
  "reason_codes": [
    "authority_recognized",
    "scope_satisfied",
    "policy_satisfied"
  ],
  "content_hash": {
    "alg": "sha256",
    "value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  },
  "signatures": []
}
```

---

## Minimal example: publisher declaration

```json
{
  "schema_version": "5.0",
  "artifact_type": "authority_recognition",
  "recognition_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "created_at": "2026-06-12T00:00:00Z",
  "expires_at": null,
  "issuer_authority_channel": "authority:example-company-docs",
  "target_ref": {
    "artifact_type": "reference_exchange",
    "artifact_id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
  },
  "target_level": "artifact",
  "recognition_status": "recognized",
  "recognized_as": "publisher_declaration",
  "certainty_level": "not_applicable",
  "scope": {
    "domain": "technology",
    "subdomain": "product-documentation",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": null,
    "language": "en"
  },
  "validation_policy_ref": {
    "policy_id": "kristal.v5:publisher-declaration",
    "policy_version": "1"
  },
  "evidence_refs": [],
  "validation_decision_refs": [],
  "reason_codes": [
    "authority_recognized",
    "policy_satisfied"
  ],
  "content_hash": {
    "alg": "sha256",
    "value": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
  },
  "signatures": []
}
```

---

## Minimal example: mythological corpus

```json
{
  "schema_version": "5.0",
  "artifact_type": "authority_recognition",
  "recognition_id": "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
  "created_at": "2026-06-12T00:00:00Z",
  "expires_at": null,
  "issuer_authority_channel": "authority:example-cultural-archive",
  "target_ref": {
    "artifact_type": "reference_exchange",
    "artifact_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
  },
  "target_level": "artifact",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=dd81676442c2:1401-1545
start=1401
end=1545
----
  "recognition_status": "recognized",
  "recognized_as": "mythological_corpus",
  "certainty_level": "not_applicable",
  "scope": {
    "domain": "mythology",
    "subdomain": "comparative-mythology",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": null,
    "language": "en"
  },
  "validation_policy_ref": {
    "policy_id": "kristal.v5:cultural-corpus-recognition",
    "policy_version": "1"
  },
  "evidence_refs": [],
  "validation_decision_refs": [],
  "reason_codes": [
    "authority_recognized",
    "scope_satisfied",
    "policy_satisfied"
  ],
  "content_hash": {
    "alg": "sha256",
    "value": "2222222222222222222222222222222222222222222222222222222222222222"
  },
  "signatures": []
}
```

---

## Minimal example: rejected physical-world claim

```json
{
  "schema_version": "5.0",
  "artifact_type": "authority_recognition",
  "recognition_id": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
  "created_at": "2026-06-12T00:00:00Z",
  "expires_at": null,
  "issuer_authority_channel": "authority:example-science-channel",
  "target_ref": {
    "artifact_type": "assertion",
    "artifact_id": "sha256:4444444444444444444444444444444444444444444444444444444444444444"
  },
  "target_level": "assertion",
  "recognition_status": "rejected",
  "recognized_as": "rejected_claim",
  "certainty_level": "high",
  "scope": {
    "domain": "science",
    "subdomain": "physical-world-claims",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": null,
    "language": "en"
  },
  "validation_policy_ref": {
    "policy_id": "kristal.v5:science-reference-review",
    "policy_version": "1"
  },
  "evidence_refs": [],
  "validation_decision_refs": [],
  "reason_codes": [
    "rejected_by_authority_channel",
    "evidence_insufficient",
    "policy_satisfied"
  ],
  "content_hash": {
    "alg": "sha256",
    "value": "5555555555555555555555555555555555555555555555555555555555555555"
  },
  "signatures": []
}
```

---

## Conformance requirements

A Kristal v5 implementation that handles authority recognition MUST:

1. Preserve recognition scope.
2. Preserve issuer authority channel.
3. Preserve target level.
4. Preserve recognition status.
5. Preserve `recognized_as`.
6. Preserve certainty level when present.
7. Preserve validation policy reference.
8. Preserve revocation and expiry status.
9. Preserve signatures and content hashes.
10. Avoid treating recognition as universal truth.
11. Avoid inheriting recognition across forks or derived artifacts unless explicitly permitted by policy.
12. Avoid silently merging conflicting recognitions.
13. Expose recognition labels to reader and rendering layers.
14. Support recognition filtering in query systems where authority-aware query is supported.

---

## Non-goals

Authority recognition does not:

```text
define universal truth
replace validation decisions
replace assertion status
replace certainty level
replace reader policy
replace federation composition policy
replace provenance
replace signatures
replace revocation handling
make one authority globally dominant
```

---

## Summary

Authority recognition is the Kristal v5 mechanism for scoped acceptance by named authorities.

It makes it possible to say:

```text
This target is recognized by this authority,
as this kind of thing,
for this scope,
under this policy,
with these reasons,
until this expiry or revocation.
```

It also makes it possible to preserve disagreement without confusion.

Recognition is plural.

Recognition is scoped.

Recognition is inspectable.

Recognition is not universal truth.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/ids-canonicalization-hashing.md"
id=9bb118d6c160
kind=markdown
size=18810
lines=515
line_ref=1-515
chunks=2
chunk_refs=1-350,351-515
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=9bb118d6c160:1-350
start=1
end=350
----
# 01-core-spec/ids-canonicalization-hashing.md

## Status

Draft (v5)

## Purpose

This document specifies the **normative** rules for:

* `canonical_json` — how Kristal objects are canonicalized
* `content_hash` — how stable digest material is recorded
* `kristal_id` — how Exchange-level content-addressed IDs are computed
* `state_id` — how Structured Epistemic State IDs are computed
* `assertion_id` — how assertion-level IDs are computed
* manifest IDs — how sidecar manifests are content-addressed
* optional `rdf_hash` — RDF-level hash for deterministic RDF exports

Kristal v5 requires that two independent implementations produce identical IDs for identical hash targets under the same canonicalization profile.

Canonicalization and hashing protect artifact identity, reproducibility, and integrity. They do not decide truth, certainty, recognition, or authority.

---

## 0. Scope note: payloads vs manifests (normative)

This document defines ID computation for Kristal v5 content-addressed objects, including:

* Structured Epistemic States
* Exchange payloads
* assertions
* shard manifests
* federation manifests
* runtime pack manifests
* authority registries
* validation decisions
* authority recognition records
* revocation records
* reader policies, where content-addressed

The **Exchange payload** is the structured Kristal artifact used for reference, federation, querying, and runtime packaging.

**Manifests** are sidecar or package-level objects that record build inputs, parameters, profiles, dependency references, integrity material, timestamps, publication status, runtime packaging details, or operational metadata.

A manifest MAY have its own content-addressed ID, but it is **not part of the Exchange payload hash target** unless a profile explicitly says otherwise.

**Core conformance implication:**

* Wall-clock timestamps and volatile compilation telemetry MUST NOT appear inside the Exchange payload hashed region unless they are intended to be part of the stable content identity.
* Operational timestamps, logs, environment telemetry, and build-run metadata SHOULD be recorded in sidecar manifests or operational logs.
* Validation, recognition, certainty, and reader-policy metadata MAY be part of a payload hash target when they are part of the stable artifact content. They MUST NOT be silently excluded.

---

## 1. Terminology

* **Kristal object**: any JSON object governed by this specification and intended to be canonicalized, hashed, signed, referenced, or distributed.
* **Structured Epistemic State**: the normative v5 input unit for structured claims, sources, provenance, certainty, review, and validation metadata.
* **Exchange payload**: a Kristal Exchange JSON object containing structured content, references, validation metadata, recognition metadata, queryable material, and artifact identity fields.
* **Reference Exchange**: an Exchange payload recognized under one or more authority channels for a declared scope.
* **Working Exchange**: an Exchange payload that is materialized and usable but not necessarily recognized as a reference by any authority channel.
* **Exchange Manifest**: a sidecar manifest that records reproducibility, build, integrity, policy, and dependency declarations for an Exchange.
* **Runtime Pack Manifest**: the sidecar manifest for a compiled offline Runtime Pack.
* **canonical_json**: the canonical byte representation of an object after applying this specification’s canonicalization rules.
* **Hash target**: the exact JSON object that is canonicalized and hashed to produce an ID or digest.
* **JCS**: JSON Canonicalization Scheme, RFC 8785, used as the mandatory canonicalization method for the v5 core profile.
* **content_hash**: a recorded digest object identifying the hash algorithm and digest value.
* **signature**: a cryptographic signature over a canonicalized hash target or digest according to the signing profile.
* **attestation**: a signed or recorded claim about validation, recognition, publication, review, runtime packaging, or operational status.

Normative keywords: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY.

---

## 2. Normative `canonical_json` profile

### 2.1 Canonicalization method

`canonical_json` MUST be produced using **RFC 8785 JSON Canonicalization Scheme (JCS)** under the v5 core profile.

### 2.2 Canonicalization profile recording

Every content-addressed Kristal object MUST record:

* `schema_version`
* `canonicalization_profile`
* `canonicalization_version`

The default v5 core values are:

```json
{
  "schema_version": "5.0",
  "canonicalization_profile": "kristal.v5:jcs-rfc8785",
  "canonicalization_version": "1"
}
```

Implementations MAY introduce additional canonicalization profiles, but they MUST make them explicit.

An implementation MUST NOT claim v5 core conformance for an object whose canonicalization profile is missing, ambiguous, or incompatible with this document.

### 2.3 Canonicalization boundaries

Canonicalization applies to the selected hash target object.

It does not imply that every adjacent file, manifest, signature, runtime package, or operational log is part of the same hash target.

Where multiple objects are bundled together, each content-addressed object MUST declare or inherit the hash target rules that apply to it.

---

## 3. Hash algorithms and digest representation

### 3.1 Mandatory hash algorithm

The mandatory v5 core hash algorithm is:

```text
sha256
```

### 3.2 Digest encoding

SHA-256 digests MUST be encoded as lowercase hexadecimal.

A content-addressed identifier MUST use the form:

```text
sha256:<lowercase-hex>
```

### 3.3 `content_hash` object shape

When a digest is stored as a field rather than as the object ID itself, it MUST use:

```json
{
  "alg": "sha256",
  "value": "<lowercase-hex>"
}
```

The key name MUST be `alg`, not `algo`.

### 3.4 Hash stability

A hash target MUST contain only the fields intended to define the stable identity of the object.

Volatile fields such as compilation wall-clock time, local filesystem path, machine hostname, CI job ID, or transient runtime telemetry MUST NOT be included in a hash target unless a profile explicitly defines them as stable identity material.

---

## 4. General hash target selection

### 4.1 Mandatory exclusions

To compute an ID for a Kristal object, implementations MUST derive a hash target object by removing:

1. the output ID field being computed;
2. `content_hash`, when it stores the digest being computed;
3. top-level `signatures`, when present;
4. top-level `attestations`, when present;
5. any nested field whose key is exactly `signatures` or `attestations`, for defensive compatibility.

The output ID field depends on the object type. Examples include:

```text
kristal_id
state_id
assertion_id
shard_id
federation_id
runtime_pack_id
validation_decision_id
recognition_id
registry_id
revocation_id
reader_policy_id
```

### 4.2 Signature placement rule

Signatures MUST be carried in a top-level `signatures` array when present.

Attestations SHOULD be carried in a top-level `attestations` array when the object embeds attestations directly.

Profiles MAY store attestations as separate signed records referenced by ID. That form is preferred when attestations may change independently of the object being attested.

### 4.3 No implicit exclusions

Except for the exclusions in Section 4.1, implementations MUST NOT silently exclude additional fields from the hash target.

If a profile needs a different stable-content boundary, that boundary MUST be declared through an explicit profile identifier and version.

### 4.4 Hash target determinism

For a given object, canonicalization profile, canonicalization version, and hash target rule, implementations MUST derive the same hash target.

If two implementations disagree about the hash target, the object is not portable under this specification until the disagreement is resolved by profile clarification or conformance correction.

---

## 5. `kristal_id` computation

### 5.1 Definition

An Exchange payload uses content-addressing:

```text
kristal_id = "sha256:" + hex(SHA-256(JCS(hash_target(E))))
```

Where:

* `E` is the Exchange payload JSON object;
* `hash_target(E)` is derived using Section 4;
* `JCS(...)` is RFC 8785 canonicalization;
* `hex(...)` is lowercase hexadecimal encoding.

### 5.2 Algorithm

Given an Exchange JSON object `E`:

1. Produce `T = hash_target(E)` by applying Section 4.
2. Serialize `T` to bytes `B = JCS(T)`.
3. Compute `H = SHA-256(B)`.
4. Encode `H` as lowercase hex.
5. Set:

```text
kristal_id = "sha256:" + hex(H)
```

### 5.3 Acceptance criteria

Two independent implementations MUST produce identical `kristal_id` values for the same Exchange payload under the same:

* `schema_version`
* `canonicalization_profile`
* `canonicalization_version`
* hash target rule

### 5.4 Exchange status is part of identity when present

If `artifact_status`, `validation_refs`, `authority_recognition_refs`, `certainty_summary`, `reader_policy_refs`, or equivalent status fields are present inside the Exchange payload, they are part of the hash target unless a profile explicitly excludes them.

This means that a Working Exchange and a Reference Exchange MAY have different `kristal_id` values even when they share the same underlying assertions.

That difference is intentional when recognition, validation, or status metadata is part of the artifact’s stable identity.

---

## 6. `state_id` computation

### 6.1 Purpose

A `state_id` identifies a Structured Epistemic State.

Structured Epistemic States are used to represent claims, hypotheses, evidence, provenance, certainty, scope, and review or validation references before or outside Exchange packaging.

### 6.2 Definition

```text
state_id = "sha256:" + hex(SHA-256(JCS(hash_target(S))))
```

Where `S` is the Structured Epistemic State object.

### 6.3 Hash target

The `state_id` hash target MUST exclude:

* `state_id`
* `content_hash`, when it stores the digest being computed
* `signatures`
* `attestations`

It MUST NOT exclude assertions, provenance, evidence, certainty, validation, scope, lineage, or policy references unless a profile explicitly defines a different state identity boundary.

### 6.4 Acceptance criteria

Two Structured Epistemic States with identical stable content MUST produce the same `state_id`.

If a certainty level, assertion status, validation reference, recognition reference, scope, or provenance entry changes, the `state_id` SHOULD change unless the profile explicitly stores that change outside the state hash target.

---

## 7. `assertion_id` computation

### 7.1 Purpose

A stable `assertion_id` enables:

* deduplication
* merge operations
* provenance tracking
* validation decisions at assertion level
* authority recognition at assertion level
* dispute preservation across federation
* query filtering by assertion status, certainty, scope, and authority channel

### 7.2 Definition

If `assertion_id` is present, the producer MUST compute it deterministically from an assertion hash target.

```text
assertion_id = "sha256:" + hex(SHA-256(JCS(hash_target(A))))
```

Where `A` is the assertion object or normalized assertion target.

### 7.3 Minimum assertion hash target

The assertion hash target SHOULD include, when applicable:

* normalized subject
* normalized predicate or property
* normalized value
* assertion scope
* qualifiers
* references or evidence pointers
* provenance pointers
* assertion status
* certainty level
* `validated_as`, when present
* authority recognition references, when present and intended to be part of assertion identity
* validation decision references, when present and intended to be part of assertion identity

Profiles MAY define a narrower assertion identity if they need to distinguish the claim core from review, validation, certainty, or recognition metadata.

If a profile uses a narrower identity, it MUST define separate IDs or references for status-bearing assertion versions.

### 7.4 Wikidata-compatible statement material

For Wikidata-compatible statements, the assertion hash target SHOULD preserve the relevant statement structure, including:

* entity ID or subject reference
* property ID or predicate
* value
* qualifiers
* references
* rank, when present
* statement-level metadata needed to preserve source meaning

A Kristal profile MAY expose a Wikidata-compatible `statement_id` as an alias or source identifier, but `assertion_id` is the v5 normative field for Kristal assertion identity.

### 7.5 Ordering rules

Where assertion substructures are semantically sets, implementations MUST sort deterministically before hashing.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=9bb118d6c160:351-515
start=351
end=515
----

Recommended ordering:

1. primary sort key: predicate/property identifier ascending lexicographically;
2. secondary sort key: canonicalized value representation, compared lexicographically over `canonical_json` bytes;
3. tertiary sort key: canonicalized representation of the full substructure.

This applies to qualifiers, references, evidence pointers, provenance references, and equivalent set-like structures.

---

## 8. Manifest ID computation

### 8.1 Scope

Manifests MAY be content-addressed independently from the payloads or packages they describe.

This applies to:

* Exchange Manifest
* Runtime Pack Manifest
* Exchange Shard Manifest
* Exchange Federation Manifest
* Authority Registry
* Validation Decision
* Authority Recognition
* Revocation Record
* Reader Policy
* Transparency Log Entry

### 8.2 Definition

A manifest ID MUST be computed using the same core rule:

```text
<object_id> = "sha256:" + hex(SHA-256(JCS(hash_target(M))))
```

Where `M` is the manifest or record object.

### 8.3 Manifest hash target

The manifest hash target MUST exclude:

* the output ID field being computed;
* `content_hash`, when it stores the digest being computed;
* `signatures`;
* `attestations`.

The manifest hash target MUST include declared stable manifest content, including dependency references, policy references, source artifact references, scope, profile identifiers, and integrity declarations.

Operationally volatile fields SHOULD be placed outside the manifest hash target or in a separate operational log.

### 8.4 Manifests do not mutate referenced artifacts

A manifest that references an Exchange, Runtime Pack, shard, or authority record MUST NOT change the identity of that referenced object.

If a manifest records new validation, recognition, publication, or runtime information, that information belongs to the manifest or related signed record unless the artifact itself is intentionally reissued with new status-bearing content.

---

## 9. Optional RDF-level hashing: `rdf_hash`

Kristal v5 supports optional RDF integrity mode for RDF exports.

When enabled, `rdf_hash` is computed using **RDF Dataset Canonicalization (RDFC-1.0)** from canonical N-Quads.

This mode is optional and enabled only under an explicit profile, such as:

```text
05-profiles/profile-rdf-integrity-rdfc.md
```

When enabled, implementations SHOULD use conformance tests for RDFC behavior and SHOULD define resource limits for canonicalization.

The RDF hash does not replace `kristal_id` unless a profile explicitly defines that behavior.

---

## 10. Optional human-verifiable ID representations

Profiles MAY define human-verifiable or URI-compatible representations of:

* `kristal_id`
* `state_id`
* `assertion_id`
* `content_hash`
* `rdf_hash`

Examples may include ni-URI-style or Trusty URI-style representations.

Such representations MUST be derived from the normative digest and MUST NOT change the underlying content-addressed ID.

---

## 11. Signing workflow dependency

The signing and verification workflow is:

```text
remove signatures
-> derive hash target
-> canonicalize
-> hash or verify digest
-> sign or verify signature
```

Declared hashes and signatures are verified according to:

```text
01-core-spec/signatures-trust.md
```

This file defines the ID, hash target, and canonicalization prerequisites that signing depends on.

Failure to verify a declared hash or signature is an integrity result. It does not, by itself, decide assertion certainty, authority recognition, reader visibility, or truth status.

---

## 12. Conformance requirements

A v5 conforming implementation MUST:

1. support RFC 8785 JCS for `canonical_json`;
2. record `schema_version = "5.0"` on v5 objects;
3. record `canonicalization_profile = "kristal.v5:jcs-rfc8785"` under the v5 core profile;
4. record `canonicalization_version = "1"` under the v5 core profile;
5. compute SHA-256 digests as lowercase hexadecimal;
6. use `sha256:<hex>` for content-addressed IDs;
7. exclude the output ID field from its own hash target;
8. exclude `signatures` and `attestations` from hash targets;
9. exclude `content_hash` when it stores the digest being computed;
10. avoid volatile operational telemetry in stable hash targets unless explicitly profiled;
11. preserve deterministic ordering for set-like substructures before hashing;
12. distinguish artifact identity from validation, recognition, certainty, and reader policy.

A v5 conforming implementation MUST NOT:

1. silently exclude undeclared fields from a hash target;
2. use `algo` instead of `alg`;
3. include signatures in the bytes being signed unless an explicit signature profile requires it;
4. treat `kristal_id` as proof of truth;
5. treat hash verification as authority recognition;
6. treat a Runtime Pack hash as replacing the identity of its source Exchange;
7. claim v5 core conformance under an unspecified canonicalization profile.

---

## 13. Non-goals

This document does not define:

* which claims are true;
* which authority channels are recognized;
* which certainty levels are acceptable for a reader;
* which validation policies are authoritative;
* which artifacts should be visible by default;
* how Orgo workflows approve or reject submissions;
* how Konnaxion chooses runtime activation policies;
* how Architect renders user-facing labels;
* how SenTient resolves ambiguous source material.

Those concerns are defined by separate Kristal v5 documents and ecosystem contracts.

This document defines only the stable identity, canonicalization, and hashing rules that those layers depend on.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/kristal-v5-core-spec.md"
id=8f0c8c114e55
kind=markdown
size=38531
lines=1359
line_ref=1-1359
chunks=4
chunk_refs=1-350,351-700,701-1050,1051-1359
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=8f0c8c114e55:1-350
start=1
end=350
----
# Kristal v5 Core Specification

## Status

Draft (normative core)

## Purpose

Define the minimal normative requirements for Kristal v5 conformance.

Kristal v5 is a deterministic, portable epistemic artifact system. It allows structured knowledge, hypotheses, references, technical declarations, institutional records, research claims, fictional corpora, mythological corpora, disputed positions, and validated reference material to coexist without being confused.

The core specification focuses on:

* deterministic artifact identity;
* canonical JSON serialization;
* content hashing;
* signature handling;
* structured epistemic inputs;
* working and reference artifacts;
* validation status;
* certainty metadata;
* authority recognition;
* federation;
* Runtime Pack derivation;
* reader-policy-aware query surfaces;
* cross-implementation interoperability.

Everything not explicitly required here is either:

* specified as an optional standardized profile;
* specified in a schema document;
* provided as non-normative implementation guidance;
* owned by another layer such as Orgo, Konnaxion, Architect, or SenTient.

## Scope and Non-goals

### In scope

Kristal v5 core defines:

* artifact type vocabulary;
* core content-addressed identity rules;
* JCS canonicalization requirements;
* SHA-256 hashing requirements;
* signature exclusion rules;
* minimal manifest requirements;
* distinction between Working Exchange and Reference Exchange;
* Structured Epistemic State as the normative input unit;
* Claim-IR as an optional extractor proposal profile;
* validation status and certainty metadata requirements;
* authority-recognition references;
* federation composition principles;
* Runtime Pack source-status requirements;
* reader-policy visibility requirements;
* deterministic reproducibility requirements;
* required conformance tests.

### Out of scope

Kristal v5 core does not define:

* full SPARQL semantics;
* a workflow engine;
* a review UI;
* voting systems;
* reputation systems;
* task routing;
* institutional governance process;
* legal authority;
* final truth arbitration;
* specific database engines;
* specific indexing engines;
* specific runtime performance guarantees;
* specific UI behavior beyond preservation of required labels and status metadata.

Orgo owns workflow, review process, approvals, audit, routing, operational policies, and lifecycle control.

Konnaxion owns distribution, channel policy, offline availability, runtime activation, cache management, and rollback/downgrade enforcement.

Architect owns deterministic rendering and must preserve validation, certainty, authority, and reader-policy labels.

SenTient may support extraction, reconciliation, disambiguation, normalization, and Claim-IR production, but Kristal v5 does not require all inputs to pass through SenTient.

## Normative Language

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as normative requirements.

## Core Definition

Kristal v5 is a deterministic, portable epistemic artifact system.

It supports the following invariant:

> A Kristal may contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.
>
> A Kristal must not present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.

Kristal v5 separates:

```text
artifact existence
≠ artifact integrity
≠ assertion validity
≠ certainty
≠ authority recognition
≠ reader visibility
```

A technically valid artifact may contain weak, speculative, disputed, fictional, or false assertions. The core requirement is that status, certainty, provenance, scope, and authority recognition remain explicit and machine-readable.

## Global Constants

Kristal v5 core uses the following default constants unless a specific profile declares otherwise:

```text
SPEC_NAME = "Kristal v5"
SPEC_VERSION = "5.0"
SCHEMA_BASE_URL = "https://kristal.org/schemas/v5/"
CANONICALIZATION_PROFILE = "kristal.v5:jcs-rfc8785"
CANONICALIZATION_VERSION = "1"
HASH_ALG = "sha256"
DEFAULT_SIGNATURE_ALG = "ed25519"
```

Schemas for core artifacts SHOULD use:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/<schema-name>.schema.json",
  "schema_version": "5.0"
}
```

## Artifact Types

Kristal v5 core recognizes the following artifact types:

```text
structured_epistemic_state
claim_ir
working_exchange
reference_exchange
runtime_pack_manifest
exchange_shard_manifest
exchange_federation_manifest
authority_registry
authority_recognition
validation_decision
validation_report
review_bundle
revocations
reader_policy
transparency_log_entry
```

Implementations MAY define additional artifact types through explicit profiles, but they MUST NOT redefine the semantics of the core artifact types.

## Artifact Status

Every compiled Exchange or derived artifact MUST declare a machine-readable artifact status.

Core artifact statuses are:

```text
draft
working
under_review
recognized
reference
deprecated
superseded
revoked
```

Status meanings:

* `draft`: incomplete or pre-compilation material.
* `working`: compiled and usable under policy, but not recognized as reference material.
* `under_review`: submitted to a review or validation process.
* `recognized`: accepted by at least one authority channel under a declared scope and policy.
* `reference`: recognized as reference material under one or more declared authority channels.
* `deprecated`: retained for history or compatibility, but no longer recommended.
* `superseded`: replaced by another artifact.
* `revoked`: explicitly invalidated by an authority, publisher, or policy process.

Implementations MUST NOT infer `reference` status only by convention. It MUST be declared.

## Structured Epistemic State

Structured Epistemic State is the normative input unit for Kristal v5 compilation.

A Structured Epistemic State represents a bounded, structured body of assertions, provenance, evidence, scope, certainty metadata, and policy references that can be compiled into a Working Exchange.

A minimal Structured Epistemic State SHOULD contain:

```json
{
  "schema_version": "5.0",
  "artifact_type": "structured_epistemic_state",
  "state_id": "sha256:<hex>",
  "created_at": "RFC3339",
  "created_by": {},
  "scope": {},
  "source_refs": [],
  "derived_from": [],
  "merged_from": [],
  "supersedes": [],
  "assertions": [],
  "provenance": [],
  "review_refs": [],
  "policy_refs": [],
  "certainty_summary": {},
  "validation_summary": {},
  "extensions": {}
}
```

A Structured Epistemic State MAY be produced by:

* a human expert;
* an institution;
* an editor;
* a research collective;
* a dataset import process;
* an LLM-assisted extractor;
* an OCR pipeline;
* a parser;
* a scraper;
* a reconciliation system;
* a collaborative review process.

## Claim-IR Role

Claim-IR is retained in Kristal v5 as an extractor proposal profile.

Claim-IR MAY be used by extraction systems that propose claims from raw or semi-structured material.

Claim-IR MUST NOT be required as the universal input format for Kristal v5.

Valid pathways include:

```text
LLM / OCR / parser / scraper -> Claim-IR -> Structured Epistemic State
```

and:

```text
human expert -> Structured Epistemic State
institutional dataset -> Structured Epistemic State
Wikidata seed corpus -> Structured Epistemic State or Exchange-compatible corpus
```

Claim-IR artifacts MUST NOT imply validation, authority recognition, reference status, or high certainty.

## Assertions

An assertion is a structured claim about a subject, predicate, object, relation, source, classification, or status.

A minimal assertion SHOULD include:

```json
{
  "assertion_id": "sha256:<hex>",
  "statement": {},
  "assertion_status": "sourced",
  "certainty_level": "medium",
  "validated_as": "sourced_claim",
  "scope": {},
  "provenance_refs": [],
  "evidence_refs": [],
  "authority_recognition_refs": [],
  "lineage": {}
}
```

Assertions MAY be true, false, speculative, fictional, mythological, disputed, reviewed, rejected, or validated under a declared authority channel and scope.

Assertions MUST preserve enough metadata for readers and systems to determine:

* what is asserted;
* who asserted it;
* what evidence supports it;
* what certainty level is declared;
* what validation status applies;
* which authority channels recognize or reject it;
* which scope governs the assertion.

## Assertion Status

Core assertion statuses are:

```text
hypothesis
claimed
sourced
disputed
reviewed
validated
rejected
retracted
superseded
```

Status meanings:

* `hypothesis`: proposed idea or possible claim.
* `claimed`: asserted by a publisher or source.
* `sourced`: linked to evidence, citation, dataset, observation, or document.
* `disputed`: contested by at least one declared source, channel, or policy.
* `reviewed`: inspected under a declared review process.
* `validated`: accepted under a declared validation policy and authority channel.
* `rejected`: rejected under a declared validation policy or authority channel.
* `retracted`: withdrawn by its publisher or authority.
* `superseded`: replaced by a later assertion.

The value `validated` MUST NOT be used alone to imply universal truth.

A validated assertion MUST declare, directly or by reference:

* `validated_as`;
* `authority_channel`;
* `scope`;
* `validation_policy_ref`;
* `certainty_level`.

## Certainty Levels

Core certainty levels are:

```text
unknown
speculative
low
medium
high
established
not_applicable
```

Certainty meanings:

* `unknown`: no usable certainty assessment is available.
* `speculative`: exploratory or hypothetical.
* `low`: weak support or limited evidence.
* `medium`: supported but not settled.
* `high`: strong support within the declared scope.
* `established`: accepted as stable reference material under the active authority channel and scope.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=8f0c8c114e55:351-700
start=351
end=700
----
* `not_applicable`: certainty is not a factual-world scale for this assertion, such as fiction, mythology, symbolic models, or publisher declarations.

Validation and certainty are separate.

Validation answers:

```text
Who accepts this status, under which rules, for which scope?
```

Certainty answers:

```text
How strong is the assertion within that scope?
```

## Validated-as Values

Core `validated_as` values are:

```text
hypothesis
claim
sourced_claim
reviewed_claim
high_confidence_fact
institutional_reference
publisher_declaration
technical_specification
legal_or_policy_position
mythological_corpus
fictional_corpus
symbolic_model
disputed_position
rejected_claim
```

Examples:

* A hypothesis may be validated as a hypothesis.
* A mythological corpus may be validated as mythology.
* A fictional world may be validated as fiction.
* A company may validate a technical description as its publisher declaration.
* A health authority may validate a medical assertion as a high-confidence fact within its scope.
* A standards body may validate a technical specification.

## Scope

Every assertion, validation decision, authority recognition, federation rule, and reader policy SHOULD be scoped.

A standard scope object is:

```json
{
  "domain": "string",
  "subdomain": "string|null",
  "jurisdiction": "string|null",
  "time_window": "string|null",
  "tenant_id": "string|null",
  "environment": "string|null",
  "language": "string|null"
}
```

`domain` is required where scope is required.

Core domain values SHOULD include:

```text
general
wikidata
science
health
education
heritage
law
policy
technology
environment
culture
mythology
fiction
research
operations
civic
local_notes
```

Profiles MAY add domain-specific vocabularies.

## Exchange

An Exchange is a structured Kristal artifact compiled from one or more Structured Epistemic States, datasets, shards, or source artifacts.

There are two core Exchange statuses:

```text
working_exchange
reference_exchange
```

A Working Exchange is compiled, structured, queryable, and reproducible, but not necessarily recognized as reference material.

A Reference Exchange is a Working Exchange or equivalent compiled artifact that has been recognized by one or more authority channels under declared validation policies and scopes.

A minimal Exchange SHOULD include:

```json
{
  "schema_version": "5.0",
  "artifact_type": "working_exchange",
  "exchange_version": "5.0",
  "kristal_id": "sha256:<hex>",
  "artifact_status": "working",
  "source_state_refs": [],
  "scope": {},
  "authority_recognition_refs": [],
  "validation_refs": [],
  "certainty_summary": {},
  "content_hash": {},
  "build": {},
  "signatures": [],
  "extensions": {}
}
```

An Exchange MUST NOT be described as a universal truth object.

An Exchange MAY be a structured reference, a working artifact, a research artifact, a cultural artifact, an institutional artifact, or a reference artifact depending on its status, scope, authority recognition, and reader policy.

## Reference Exchange

A Reference Exchange MUST declare:

* `artifact_type = "reference_exchange"`;
* `artifact_status = "reference"`;
* at least one `authority_recognition_ref`;
* the scope of recognition;
* the validation or recognition policy used;
* the source Working Exchange or source state lineage.

Reference status is scoped.

Recognition by one authority channel MUST NOT imply recognition by another authority channel unless an explicit authority-recognition record says so.

## Runtime Pack

A Runtime Pack is a derived offline-usable package produced from an Exchange.

A Runtime Pack MUST declare:

* its source Exchange reference;
* whether the source is a Working Exchange or Reference Exchange;
* its query contract;
* its packaging policies;
* its content hash;
* its build information;
* its signatures, if present;
* its reader-policy references, if applicable.

A minimal Runtime Pack manifest SHOULD include:

```json
{
  "schema_version": "5.0",
  "artifact_type": "runtime_pack_manifest",
  "runtime_pack_id": "sha256:<hex>",
  "runtime_pack_version": "5.0",
  "source_exchange_ref": {},
  "source_artifact_status": "working",
  "reader_policy_refs": [],
  "query_contract_ref": {},
  "integrity": {},
  "build": {},
  "signatures": [],
  "extensions": {}
}
```

A Runtime Pack derived from a Working Exchange MUST NOT be treated as equivalent to a Runtime Pack derived from a Reference Exchange unless a reader policy explicitly allows that equivalence.

Runtime Pack possession does not imply authorization to use it.

Runtime Pack integrity does not imply epistemic validation.

## Authority Channel

An authority channel is a scoped authority context that may recognize, validate, reject, dispute, deprecate, or revoke artifacts, shards, assertions, Runtime Packs, datasets, or other authority channels.

A minimal authority channel SHOULD include:

```json
{
  "authority_channel_id": "authority:<slug>",
  "name": "string",
  "authority_type": "institution",
  "scope": {},
  "recognized_by": [],
  "trust_roots": [],
  "validation_policies": [],
  "revocation_policy_ref": null
}
```

Core authority types are:

```text
individual
community
association
research_collective
academic_institution
standards_body
company
government
intergovernmental_organization
ai_validator
hybrid_collective
```

No authority channel has universal monopoly over all Kristal truth.

Authority recognition is scoped.

Authorities MAY recognize other authorities.

Recognition by one authority channel MUST NOT imply recognition by another.

## Authority Recognition

Authority recognition declares that an authority channel accepts a target under a declared scope and policy.

A minimal authority-recognition artifact SHOULD include:

```json
{
  "recognition_id": "sha256:<hex>",
  "artifact_type": "authority_recognition",
  "issuer_authority_channel": "authority:<slug>",
  "target_ref": {},
  "target_level": "artifact",
  "recognition_status": "recognized",
  "recognized_as": "institutional_reference",
  "scope": {},
  "validation_policy_ref": {},
  "reason_codes": [],
  "evidence_refs": [],
  "created_at": "RFC3339",
  "expires_at": null,
  "signatures": []
}
```

Core recognition statuses are:

```text
recognized
conditionally_recognized
under_review
disputed
rejected
deprecated
revoked
```

Authority recognition MUST NOT be collapsed into a boolean.

The following is insufficient:

```json
{
  "recognized": true
}
```

## Validation Decision

A validation decision records the result of applying a validation policy to a target.

A minimal validation decision SHOULD include:

```json
{
  "validation_decision_id": "sha256:<hex>",
  "artifact_type": "validation_decision",
  "target_ref": {},
  "target_level": "artifact",
  "validation_status": "validated",
  "validated_as": "high_confidence_fact",
  "certainty_level": "high",
  "authority_channel": "authority:<slug>",
  "validation_policy_ref": {},
  "scope": {},
  "findings": [],
  "reason_codes": [],
  "created_at": "RFC3339",
  "signatures": []
}
```

Core validation statuses are:

```text
not_evaluated
in_review
validated
conditionally_validated
disputed
rejected
revoked
```

Validation MAY affect:

* reference status;
* publication eligibility;
* reader visibility;
* authority recognition;
* Runtime Pack activation policy;
* warning labels;
* query filtering.

Validation MUST NOT be treated as a universal compile blocker.

Compilation may produce a Working Exchange even when validation has not occurred, is incomplete, is disputed, or is rejected for reference use.

## Reader Policy

A reader policy determines which artifacts, assertions, validation statuses, certainty levels, authority channels, and scopes are visible or usable in a reading surface.

A minimal reader policy SHOULD include:

```json
{
  "reader_policy_id": "reader_policy:<slug>",
  "mode": "validated_only",
  "allowed_authority_channels": [],
  "allowed_validation_statuses": [],
  "allowed_certainty_levels": [],
  "allowed_validated_as": [],
  "include_disputed": false,
  "include_fictional": false,
  "include_mythological": false,
  "show_labels": true,
  "fallback_behavior": "show_unavailable"
}
```

Core reader modes are:

--- CHUNK END ---

--- CHUNK BEGIN ---
id=8f0c8c114e55:701-1050
start=701
end=1050
----
```text
reference_only
validated_only
high_certainty_only
research
creative
all_with_labels
custom
```

A reader policy MAY allow users or applications to use only validated material.

“Validated-only” means all visible assertions satisfy the active reader policy. It does not mean:

* all visible assertions have maximum certainty;
* all visible assertions are universally true;
* all authority channels agree;
* all assertions are factual-world claims.

Reader surfaces MUST preserve labels for validation, certainty, authority, scope, and dispute status.

## Federation

Federation composes multiple Kristal artifacts, shards, authority channels, scopes, or datasets without silently merging their authority, provenance, or disagreement.

A federation manifest SHOULD include:

```json
{
  "schema_version": "5.0",
  "artifact_type": "exchange_federation_manifest",
  "federation_id": "sha256:<hex>",
  "created_at": "RFC3339",
  "authority_registry_ref": {},
  "shards": [],
  "composition_policy": {},
  "reader_policy_refs": [],
  "publisher": {},
  "content_hash": {},
  "signatures": [],
  "extensions": {}
}
```

Federation MUST preserve source identities.

Federation MUST NOT rewrite shard identities.

Federation MUST declare composition policy.

Federation MUST preserve disagreement unless an explicit reader policy, authority policy, or composition profile declares otherwise.

Default v5 conflict strategy SHOULD be:

```text
preserve_disagreement
```

## Composition Policy

A composition policy defines how overlapping shards, assertions, scopes, or authority channels are presented.

A minimal composition policy SHOULD include:

```json
{
  "policy_id": "kristal.v5:composition-policy:<slug>",
  "policy_version": "1",
  "overlap_strategy": "authority_precedence",
  "conflict_strategy": "preserve_disagreement",
  "default_visibility": "reader_policy",
  "ordering": "stable",
  "parameters": {}
}
```

Core overlap strategies are:

```text
authority_precedence
latest_time_window
explicit_allow_deny
preserve_all
reader_policy_selected
```

Core conflict strategies are:

```text
preserve_disagreement
authority_precedence
mark_disputed
exclude_conflict
require_reader_choice
```

Composition MUST NOT make one authority appear to speak for another.

## Canonical JSON

Kristal v5 core uses RFC 8785 JSON Canonicalization Scheme for JSON content-addressed identity.

Artifacts and manifests that declare content hashes MUST declare:

```text
canonicalization_profile = "kristal.v5:jcs-rfc8785"
canonicalization_version = "1"
```

Where a profile uses a different canonicalization surface, that profile MUST declare its canonicalization method, version, and hash target.

The term canonicalization in Kristal v5 refers only to deterministic byte representation for hashing and signing. It does not imply canonical truth.

## Content Hashing

Core JSON content hashes MUST use SHA-256 over canonicalized JSON bytes.

The standard hash object shape is:

```json
{
  "alg": "sha256",
  "value": "<64 lowercase hex characters>"
}
```

Implementations MUST use `alg`, not `algo`.

For content-addressed IDs, implementations SHOULD use:

```text
sha256:<hex>
```

Examples:

```text
kristal_id = "sha256:<hex>"
state_id = "sha256:<hex>"
assertion_id = "sha256:<hex>"
shard_id = "sha256:<hex>"
federation_id = "sha256:<hex>"
runtime_pack_id = "sha256:<hex>"
validation_decision_id = "sha256:<hex>"
recognition_id = "sha256:<hex>"
```

Policy artifacts MAY use richer namespaced identifiers if their schemas explicitly allow them.

## Hash Target Rules

Each artifact schema or profile MUST define its hash target.

Unless explicitly stated otherwise, the hash target excludes:

* signatures;
* detached signatures;
* proofs;
* tenant-local access-control metadata;
* workflow state;
* approval queues;
* distribution state;
* runtime activation state;
* local cache state;
* reader session state;
* transient UI state.

The hash target MAY include validation references, certainty summaries, authority recognition references, or reader-policy references when the artifact schema declares them part of the artifact content boundary.

The hash target MUST be test-vectorized for core artifacts.

## Signature Rules

If an artifact or manifest includes signatures, signatures MUST be placed in a clearly separated signature envelope.

The default signature location is:

```json
{
  "signatures": []
}
```

The minimal signature object is:

```json
{
  "key_id": "string",
  "alg": "ed25519",
  "signature": "string",
  "created_at": "RFC3339"
}
```

The signing and verification workflow is:

```text
remove signature material
canonicalize declared hash target
hash canonical bytes
verify or attach signature
```

A valid signature verifies artifact integrity and signer identity under the relevant trust roots.

A valid signature does not imply:

* authority recognition;
* validation;
* high certainty;
* universal truth;
* reader-policy visibility.

## Integrity Verification

If an artifact or manifest declares content hashes, signatures, signer identity, key references, or integrity material, verifiers MUST check the declared integrity material before accepting the artifact under any policy that requires it.

If declared integrity material is malformed, incomplete, ambiguous, unsupported, or mismatched, the verifier MUST report a structured verification issue.

If the active policy requires the integrity material, the artifact MUST NOT be accepted under that policy.

Recommended verification statuses are:

```text
verified
verification_failed
verification_not_possible
algorithm_unsupported
hash_mismatch
signature_invalid
signature_missing
malformed_integrity_material
```

This is a policy outcome about artifact acceptance. It is not a statement about the factual truth or falsity of the assertions inside the artifact.

## Build Records

A v5-aware build record SHOULD distinguish:

```text
compile_status
validation_status
review_status
recognition_status
publication_status
activation_status
working_outputs[]
reference_outputs[]
reason_codes[]
created_at
```

Recommended build status values:

```json
{
  "compile_status": "succeeded",
  "validation_status": "not_evaluated",
  "review_status": "not_required",
  "recognition_status": "none",
  "publication_status": "not_published",
  "activation_status": "not_applicable",
  "working_outputs": [],
  "reference_outputs": [],
  "reason_codes": [],
  "created_at": "RFC3339"
}
```

Compilation success MUST NOT imply validation success.

Validation success MUST NOT imply authority recognition unless a recognition artifact is present.

Authority recognition MUST NOT imply universal truth.

Runtime activation MUST remain governed by the active tenant, channel, integrity, compatibility, and reader policies.

## Determinism and Reproducibility

Kristal v5 requires deterministic compilation within the declared reproducibility surface.

A reproducibility surface SHOULD declare:

* source artifact references;
* source snapshots;
* compiler name;
* compiler version;
* compiler configuration hash;
* schema versions;
* canonicalization profile;
* canonicalization version;
* policy selections;
* ordering rules;
* normalization rules;
* profile activation;
* extension activation;
* build environment constraints when relevant.

Given identical inputs and identical declared policy selections, implementations MUST reproduce:

* the same content hashes;
* the same content-addressed IDs;
* the same deterministic exports;
* the same Runtime Pack outputs where portable policies are identical.

If two builds differ because policy selections differ, that difference MUST be declared in the manifests.

## Query Semantics

Runtime-capable Kristal artifacts MUST expose or reference a constrained query contract.

At minimum, query-capable artifacts SHOULD support filtering or exposing:

```text
artifact_status
assertion_status
certainty_level
validated_as
validation_status
authority_channel
recognition_status
scope.domain
scope.subdomain
reader_policy
include_disputed
include_fictional
include_mythological
```

Query results MUST preserve enough metadata for the reader to know:

* what artifact supplied the result;
* what assertion status applies;
* what certainty level applies;
* which authority channels recognize the result;
* what reader policy allowed the result to appear;
* whether disagreement or dispute exists.

Query surfaces MUST NOT silently flatten scoped validation into universal truth.

## Profiles and Extensions

Optional capabilities MUST be specified as explicit profiles.

If a profile is enabled or claimed:

* it MUST be declared in manifests;
* it MUST be testable;
* it MUST NOT redefine core identity semantics;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=8f0c8c114e55:1051-1359
start=1051
end=1359
----
* it MUST NOT redefine validation as universal truth;
* it MUST NOT hide authority, certainty, scope, or reader-policy metadata required by core.

Core standardized profile categories include:

* RDF WDQS export;
* RDF integrity using RDFC;
* JSON-LD export;
* Provenance using Nanopub and PROV-O;
* SHACL validation;
* ShEx validation;
* TPF-like query pagination;
* transparency logs;
* reader policy profiles.

## RDF Exports

If an implementation supports RDF exports, the export MUST be deterministic under its declared export profile.

RDF exports MAY support:

* full statements;
* truthy or best-rank projections;
* named graphs;
* references;
* qualifiers;
* ranks;
* provenance graphs;
* authority recognition graphs;
* validation-decision graphs;
* certainty metadata.

RDF export integrity is not core identity. RDF-level hashing belongs to the RDF Integrity profile.

RDF export integrity does not imply epistemic validation.

## Wikidata-Compatible Seed Corpora

A Wikidata-compatible Kristal seed corpus SHOULD preserve as much source structure as possible, including:

* entities;
* properties;
* statements;
* qualifiers;
* references;
* ranks;
* labels;
* aliases;
* descriptions;
* source identifiers.

A Wikidata-compatible seed MUST NOT collapse full statement structure into only a truthy view unless the artifact explicitly declares that reduced projection as its content boundary.

The recommended language is:

```text
Kristal-compatible packaging or alignment of the Wikidata corpus.
```

Implementations SHOULD NOT describe this as a transformation of truth.

## Multi-tenancy

Kristal v5 separates global content identity from tenant access control.

Tenant identifiers, ACLs, approvals, workflow state, distribution state, and runtime activation state MUST NOT influence global content IDs unless a tenant-scoped artifact profile explicitly declares them inside the content boundary.

Tenant isolation SHOULD be enforced by:

* access control;
* tenant-scoped artifact handles;
* signing domains;
* trust roots;
* distribution channels;
* reader policies;
* Runtime Pack activation policies;
* tenant-scoped logs.

The same content MAY produce the same global content ID across tenants.

Different tenants MAY sign the same content with different keys.

Different tenants MAY recognize, reject, hide, or expose the same content differently.

## Security and Trust

Kristal v5 protects artifact integrity and makes epistemic status explicit.

It does not guarantee that all contained assertions are true.

Implementations MUST preserve the distinction between:

* valid artifact;
* valid signature;
* recognized artifact;
* validated assertion;
* high-certainty assertion;
* visible result under reader policy.

Security controls SHOULD prevent:

* authority laundering;
* hidden downgrade or rollback;
* cross-tenant leakage;
* cross-channel cache confusion;
* signature trust-root confusion;
* silent merging of disagreements;
* presentation of fictional, mythological, or disputed claims as factual-world reference material.

## Authority Laundering

Authority laundering occurs when a claim, artifact, shard, or Runtime Pack recognized under one authority channel is presented as if it were recognized by another authority channel.

Implementations MUST NOT launder authority.

Reader surfaces MUST preserve:

* issuer authority channel;
* recognition status;
* validation policy;
* scope;
* certainty level;
* dispute status;
* rejection status where relevant.

## Fiction, Mythology, Symbolic Models, and Creative Corpora

A mythology or fiction Kristal MAY be valid as mythology or fiction.

It MUST NOT be represented as validated physical-world truth unless an authority channel explicitly validates that epistemic mode.

Examples:

```text
validated_as = "mythological_corpus"
certainty_level = "not_applicable"
scope.domain = "mythology"
```

```text
validated_as = "fictional_corpus"
certainty_level = "not_applicable"
scope.domain = "fiction"
```

Such artifacts MAY be first-class Kristals and MAY be queryable, federated, cited, versioned, and preserved.

## Divergent Forks

Divergent forks are allowed.

A divergent fork MUST preserve lineage.

A divergent fork MUST declare its publisher or authority channel where available.

A divergent fork MUST declare scope.

A divergent fork MUST NOT inherit recognition from its source unless explicitly recognized by the relevant authority channel.

Federation SHOULD preserve divergent views rather than silently rewriting them.

## Revocation and Supersession

Kristal v5 artifacts MAY be revoked, deprecated, or superseded.

Revocation records SHOULD declare:

* target reference;
* target level;
* issuing authority or publisher;
* scope;
* reason codes;
* evidence references;
* created timestamp;
* signatures.

Revocation of an artifact under one authority channel MUST NOT imply universal revocation unless recognized by the active reader policy or authority channel.

Supersession SHOULD preserve lineage to the superseded artifact.

## Forward Compatibility

Readers MUST ignore unknown non-integrity fields unless the active profile declares them required.

Readers MUST NOT ignore malformed or mismatched declared integrity material when the active policy requires integrity verification.

Writers SHOULD avoid breaking schema changes. If breaking changes are unavoidable, writers MUST bump schema version and declare profile compatibility.

Unknown artifact types MAY be retained and displayed as unsupported, but MUST NOT be presented as validated or recognized unless the relevant status can be verified.

## Conformance

An implementation is Kristal v5 Core Conformant if it:

1. Implements JCS canonicalization for core JSON artifacts.
2. Implements SHA-256 content hashing for core content-addressed IDs.
3. Excludes signatures from content hash targets.
4. Uses `schema_version = "5.0"` for v5 core artifacts.
5. Uses `canonicalization_profile = "kristal.v5:jcs-rfc8785"` where applicable.
6. Supports Structured Epistemic State as a normative input unit.
7. Treats Claim-IR as an optional extractor proposal profile.
8. Distinguishes Working Exchange from Reference Exchange.
9. Preserves artifact status, assertion status, certainty level, validation status, authority recognition, and reader-policy metadata.
10. Does not treat validation as a universal compile blocker.
11. Does not treat a valid artifact or valid signature as universal truth.
12. Supports deterministic reproducibility within declared reproducibility surfaces.
13. Preserves federation source identities and disagreement.
14. Supports Runtime Pack manifests with source artifact status.
15. Passes required JCS and hashing test vectors.
16. Reports structured issues for integrity, validation, recognition, and policy failures.
17. Does not present scoped recognition as universal recognition.
18. Does not hide fictional, mythological, disputed, rejected, or low-certainty status where that status is known.

## Required Test Vectors

A conformant implementation MUST ship or reference test vectors for:

* JCS canonicalization;
* SHA-256 content hashing;
* signature exclusion;
* tenant metadata exclusion;
* artifact status preservation;
* assertion status preservation;
* certainty level preservation;
* authority recognition references;
* validation decision references;
* federation disagreement preservation;
* Runtime Pack source-status declaration;
* reader-policy filtering.

If an implementation fails the core canonicalization or hashing vectors, its content-addressed IDs are not interoperable.

## Non-conformance

An implementation is not Kristal v5 Core Conformant if it:

* computes content IDs from non-canonical JSON;
* includes signatures in content hashes;
* changes global content IDs based on tenant-local metadata;
* requires Claim-IR as the only possible input;
* prevents all compilation before validation;
* presents Working Exchange as Reference Exchange without recognition;
* collapses validation into universal truth;
* hides certainty level or authority scope;
* silently merges conflicting authority channels;
* hides dispute status where known;
* ignores required integrity failures under an active policy;
* presents Runtime Packs from Working Exchanges as equivalent to Reference Exchange Runtime Packs without policy declaration.

## Minimal Core File Set

The Kristal v5 core expects the following related files to exist:

```text
01-core-spec/ids-canonicalization-hashing.md
01-core-spec/signatures-trust.md
01-core-spec/structured-epistemic-state.md
01-core-spec/assertion-status-and-certainty.md
01-core-spec/authority-recognition.md

02-schemas/structured-epistemic-state.schema.json
02-schemas/assertion-status.schema.json
02-schemas/authority-recognition.schema.json
02-schemas/claim-ir.schema.json
02-schemas/exchange-manifest.schema.json
02-schemas/exchange-shard-manifest.schema.json
02-schemas/exchange-federation-manifest.schema.json
02-schemas/runtime-pack-manifest.schema.json
02-schemas/validation-report.schema.json
02-schemas/reader-policy.schema.json

04-query/query-contract.md
04-query/reader-policy-profiles.md

09-test-vectors/jcs/README.md
09-test-vectors/jcs/vectors.json
09-test-vectors/jcs/expected-hashes.txt
```

## Summary

Kristal v5 core defines portable epistemic artifacts with deterministic identity, explicit status, scoped validation, plural authority, queryable certainty, and reader-policy-aware visibility.

The core invariant is:

```text
A Kristal may contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.

A Kristal must not present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.
```

Kristal v5 therefore provides:

```text
deterministic identity
+ structured epistemic state
+ working artifacts
+ reference artifacts
+ scoped validation
+ explicit certainty
+ plural authority recognition
+ federation without silent merging
+ reader-policy visibility
+ reproducible runtime packaging
```

The result is not a universal truth machine.

It is a structured, portable, verifiable artifact system for knowledge whose status remains explicit.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/signatures-trust.md"
id=493098d308ac
kind=markdown
size=25448
lines=624
line_ref=1-624
chunks=2
chunk_refs=1-350,351-624
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=493098d308ac:1-350
start=1
end=350
----
# 01-core-spec/signatures-trust.md

## Status

Draft (v5)

## Purpose

This document specifies the **normative** rules for:

* signature and attestation structures used in Kristal v5 artifacts
* what is signed and how signing inputs are constructed
* required verification semantics for signatures, content identity, and trust roots
* trust-root and key identity (`key_id` / KID), including offline verification expectations
* minimum interoperability requirements for mandatory-to-implement algorithms
* the relationship between signatures, authority recognition, validation status, and reader policy

This document applies to:

* **Structured Epistemic State** artifacts
* **Kristal Exchange** artifacts
* **Runtime Pack** manifests
* **Exchange Shard** manifests
* **Exchange Federation** manifests
* **Authority Registry** artifacts
* **Authority Recognition** artifacts
* **Validation Decision** artifacts
* **Revocation** artifacts
* other derived Kristal artifacts that explicitly declare conformance to this signature model

---

## 1. Terminology

* **Artifact**: a JSON object that declares a Kristal v5 `artifact_type`.
* **Content identity**: the artifact’s content-addressed identifier, computed per `01-core-spec/ids-canonicalization-hashing.md`.
* **Hash target**: the JSON object that is canonicalized and hashed to produce content identity, with signature overlays and any excluded self-identifying fields removed according to the ID and canonicalization rules.
* **Signature**: a cryptographic proof that binds an issuer key to an artifact’s content identity.
* **Attestation**: a signature produced by a third party, such as an auditor, publisher, validator, distributor, authority channel, or review body, over the same content identity.
* **Trust root**: a pinned set of public keys, certificates, or equivalent verifier-recognized trust material used for a given scope, tenant, authority channel, environment, or reader policy.
* **Authority channel**: a declared source of recognition or validation within a specific scope and policy.
* **Validation decision**: a scoped decision asserting that an artifact, shard, assertion, runtime pack, or authority channel has a particular validation status under a declared policy.
* **Recognition**: a scoped acceptance by an authority channel that a target is trusted, reference-worthy, conditionally accepted, rejected, revoked, or otherwise classified under that channel.
* **Reader policy**: a policy used by a reader, runtime, application, or user interface to decide which artifacts, assertions, validation statuses, certainty levels, and authority channels are visible or trusted in a given view.
* **Unsigned artifact**: an artifact with no `signatures` field, or with an empty `signatures` array.
* **Required signature**: a signature whose `required` field is `true` or omitted.

Normative keywords: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY.

---

## 2. Core principles

1. **Content IDs are not signatures.**
   Content identity proves content equivalence. Signatures prove issuer authenticity, issuer continuity, or issuer authorization relative to a trust store or authority channel.

2. **Signatures MUST NOT be included in the content-hash target.**
   Signatures are overlays. The content identity is computed over the artifact with signature fields excluded.

3. **Output identity fields MUST NOT hash themselves.**
   Any field that stores the artifact’s own content identity, such as `kristal_id`, `state_id`, `runtime_pack_id`, `federation_id`, `shard_id`, `recognition_id`, or `validation_decision_id`, MUST be excluded from the hash target used to produce that same identity.

4. **Verification MUST be offline-capable.**
   A verifier MUST be able to verify a signed artifact with no network access, given the artifact, its declared signature material, and the relevant trust roots.

5. **Integrity verification protects artifact identity.**
   Signature verification determines whether a key recognized by the verifier signed the artifact’s content identity. It does not, by itself, prove that the artifact is universally true, globally valid, high-certainty, or recognized by every authority channel.

6. **Validation, certainty, and recognition are separate from signatures.**
   A signature MAY support publication, distribution, recognition, validation, or audit, but those statuses MUST be expressed through explicit validation decisions, authority recognition records, manifests, or reader policies.

7. **Verification failure is a status, not a metaphysical judgment.**
   If a required signature cannot be verified, the artifact MUST NOT be treated as signature-verified or accepted by any policy requiring that signature. The artifact MAY still be stored, inspected, rendered with warning labels, used in research contexts, or processed under a policy that allows unverified material.

---

## 3. Signature envelope

### 3.1 Where signatures live

Artifacts that support signatures MUST include signatures only in the top-level field:

* `signatures`: an array of signature objects

If `signatures` is absent or empty, the artifact is considered **unsigned**.

Signature objects MUST be carried only in the top-level `signatures` field. If signature-like fields appear elsewhere, verifiers MUST exclude them from the hash target and SHOULD mark the artifact as non-conformant unless the relevant artifact profile explicitly defines those fields.

### 3.2 Signature object schema

Each entry in `signatures[]` MUST be an object with:

* `key_id` (string): key identifier used to locate the issuer public key in a trust store
* `alg` (string): signing algorithm identifier
* `signature` (string): signature bytes encoded as base64url without padding
* `created_at` (string, optional): ISO 8601 / RFC 3339 timestamp
* `required` (boolean, optional): defaults to `true`

Optional fields:

* `purpose` (string): signature purpose, such as `"publisher"`, `"validator"`, `"authority"`, `"auditor"`, `"distributor"`, or `"reviewer"`
* `signer` (object): human-readable signer metadata, such as `{ "name": "...", "org": "..." }`
* `authority_channel` (string): authority channel under which the signature is issued or interpreted
* `scope` (object): optional scope for which the signature is intended
* `validation_policy_ref` (object): optional reference to the policy that interprets this signature
* `expires_at` (string): ISO 8601 / RFC 3339 timestamp
* `notes` (string)
* `x5c` (array of strings): X.509 certificate chain, encoded as base64 DER, if a profile enables certificate-chain verification
* `extensions` (object): implementation-specific extension fields

A signature object MUST NOT be interpreted as a validation decision unless a profile or policy explicitly maps that signature to a validation decision or authority recognition record.

### 3.3 Mandatory-to-implement algorithms

To ensure interoperability, Kristal v5 implementations MUST support verification for:

* `alg = "ed25519"`
* content identity hash algorithm `sha256`
* canonicalization profile `kristal.v5:jcs-rfc8785`

Implementations MAY support additional algorithms, but MUST NOT claim Kristal v5 signature conformance if they cannot verify Ed25519 signatures over Kristal v5 SHA-256 content identities.

---

## 4. Signing input construction

### 4.1 Goals

The signing input MUST:

* bind the issuer to the artifact’s content identity
* prevent ambiguous “what exactly was signed” situations
* be reconstructable deterministically by verifiers from the artifact alone
* remain stable when signatures are added, removed, reordered, or replaced

### 4.2 Signing input

For each signature object `S` in `A.signatures[]`, the signing input MUST be the raw digest bytes of the artifact’s content identity.

For a content identity encoded as:

```text
sha256:<hex>
```

the signing input is the 32 raw bytes represented by `<hex>`.

For artifacts whose identity field stores only the hex digest, the signing input is the 32 raw bytes represented by that hex value.

The following artifact identity fields are recognized by this document:

* `state_id`
* `kristal_id`
* `runtime_pack_id`
* `shard_id`
* `federation_id`
* `registry_id`
* `recognition_id`
* `validation_decision_id`
* `revocation_id`
* any profile-defined identity field that explicitly declares conformance to the Kristal v5 content identity model

### 4.3 Identity recomputation requirement

Before verifying any signatures, verifiers MUST recompute the artifact’s content identity from the artifact itself, according to `01-core-spec/ids-canonicalization-hashing.md`.

The recomputation MUST exclude:

* the top-level `signatures` field
* the artifact’s own identity field
* any profile-declared signature overlays
* any profile-declared non-hash fields

If the recomputed identity does not match the declared identity field, the artifact’s identity verification fails.

An artifact whose identity verification fails MUST NOT be treated as content-identity-verified. Any reader, runtime, publisher, or validator that requires verified identity MUST reject it for that policy.

The artifact MAY still be preserved, inspected, analyzed, or displayed as unverified if the active reader policy allows that behavior.

### 4.4 Signature computation

For `alg = "ed25519"`:

* signature input MUST be the raw digest bytes described in Section 4.2
* `signature` MUST be the base64url-encoded Ed25519 signature bytes, without padding

---

## 5. Verification rules

### 5.1 Verification procedure

Given an artifact `A`:

1. If `A.signatures` is absent or empty, the artifact is **unsigned**.
2. If `A.signatures` is present:

   1. Recompute `A`’s content identity from `A`, excluding signatures and other declared non-hash fields.
   2. Compare the recomputed identity to the declared identity.
   3. For each signature object `S` in `A.signatures`:

      * validate that required fields exist and are well-formed;
      * resolve the public key for `S.key_id` from the verifier’s trust store;
      * verify that `S.alg` is supported;
      * verify `S.signature` over the signing input defined in Section 4.2;
      * evaluate optional fields such as `expires_at`, `purpose`, `authority_channel`, and `scope` if required by the active policy.
3. Apply required and optional signature semantics:

   * if `S.required` is true or missing, it is required;
   * if `S.required` is false, the signature is optional;
   * required signatures affect whether the artifact satisfies policies that require verified signatures;
   * optional signature failures MUST be reported but do not by themselves invalidate other successfully verified signatures.

### 5.2 Required verification semantics

If an artifact contains a required signature, and that required signature cannot be verified, then:

* the artifact MUST NOT be treated as signed by that key;
* the artifact MUST NOT satisfy any policy that requires that signature, key, authority channel, purpose, or trust root;
* the artifact MUST NOT be published, distributed, activated, rendered as verified, or recognized under a policy that requires successful verification of that signature;
* the failure MUST be visible to validation, distribution, runtime, or reader systems that evaluate the artifact.

The artifact MAY still exist as an unsigned, partially verified, unverified, disputed, research, archival, or diagnostic object if a policy explicitly allows that status.

### 5.3 Partial verification

Verifiers MUST NOT silently skip signatures they cannot process if those signatures are required.

If a verifier does not support the algorithm referenced by a required signature, verification for that signature MUST fail for that verifier.

If a verifier cannot resolve the key referenced by a required signature, verification for that signature MUST fail for that verifier.

If a verifier can verify some signatures but not others, the verifier MUST report signature status per signature.

### 5.4 Signature status values

Implementations SHOULD expose signature verification results using the following statuses:

```text
signature_status:
  - not_present
  - verified
  - failed
  - unsupported_alg
  - missing_key
  - expired
  - malformed
  - identity_mismatch
  - policy_not_satisfied
  - not_evaluated
```

A single artifact MAY contain signatures with different statuses.

### 5.5 Artifact verification status

Implementations SHOULD expose artifact-level verification status using the following values:

```text
artifact_verification_status:
  - unsigned
  - identity_verified
  - identity_mismatch
  - signature_verified
  - partially_verified
  - signature_failed
  - policy_satisfied
  - policy_not_satisfied
  - not_evaluated
```

Artifact verification status MUST NOT be confused with assertion validation status, authority recognition, or certainty level.

---

## 6. Trust roots, key identity, and multi-tenancy

### 6.1 Trust roots

Each verifier MUST maintain or receive a trust store containing:

* trusted public keys, certificates, or equivalent trust material keyed by `key_id`
* the scope, tenant, environment, authority channel, or policy for which each key is trusted
* optional validity windows
* optional revocation metadata
* optional allowed purposes

Trust stores MAY be:

* tenant-scoped
* environment-scoped
* device-scoped
* authority-channel-scoped
* reader-policy-scoped
* runtime-pack-scoped
* offline-bundled

### 6.2 `key_id` format

Recommended `key_id` formats include:

* stable string key IDs, such as `"orgo-prod-ed25519-2026-01"`
* key fingerprints using a stable encoding
* URI-like identifiers controlled by an authority channel
* certificate-bound identifiers when an X.509 profile is enabled

A `key_id` MUST be stable enough for deterministic offline verification.

A `key_id` MUST NOT rely on network lookup as the only way to resolve the key.

### 6.3 Key rotation

Implementations SHOULD support key rotation by:

* allowing overlapping validity windows where old and new keys are trusted;
* preserving historical trust material needed to verify older artifacts;
* using short-lived signing keys under longer-lived root keys where appropriate;
* publishing revocations or trust-store updates through explicit revocation artifacts or transparency-log profiles;
* ensuring that offline verifiers can determine whether a key was valid for the artifact and policy being evaluated.

### 6.4 Multi-tenancy

The same signature MAY have different policy effects in different tenants, environments, or authority channels.

For example, a signature may be recognized by one reader policy but ignored by another. A company’s signature may be sufficient for its own technical documentation, but insufficient for an independent safety validation.

Verifiers MUST NOT assume that a valid cryptographic signature implies universal recognition.

---

## 7. What signatures authorize

This specification binds signatures to content identity.

Whether a signature is enough to:

* publish an Exchange into a registry;
* recognize an artifact as a reference;
* distribute a Runtime Pack;
* activate a Runtime Pack;
* display a “verified” label;
* satisfy a validation policy;
* satisfy an authority recognition policy;
* include material in a reader policy view;

is governed by explicit policy.

Recommended minimum policy separation:

* **Kristal** defines artifact identity, canonicalization, hashing, signatures, manifests, query contracts, and verification semantics.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=493098d308ac:351-624
start=351
end=624
----
* **Orgo** manages workflows, review routing, approvals, audit records, release records, and operational lifecycle.
* **Konnaxion** distributes Kristals, applies reader policies, manages runtime access, and surfaces validation, authority, and certainty labels.
* **Architect** renders artifacts and summaries without hiding validation labels, authority labels, certainty levels, or disputed status.
* **SenTient** may support extraction, normalization, disambiguation, and Claim-IR profile processing, but Claim-IR is not the universal required input to Kristal v5.

A signature proves that a key signed a content identity. It does not prove that:

* the artifact is globally true;
* every assertion inside the artifact is true;
* every assertion has high certainty;
* the artifact is recognized by all authority channels;
* the artifact is suitable for every reader policy;
* the artifact is validated outside its declared scope.

---

## 8. Relationship to validation, certainty, and recognition

### 8.1 Signatures and validation

A signed artifact MAY be used as evidence in a validation decision.

A signature MAY be required by a validation policy.

A signature MAY be produced by an authority channel as part of a validation decision.

However, signature verification alone MUST NOT be represented as validation unless a validation decision or policy explicitly says so.

### 8.2 Signatures and certainty

A signature does not set certainty level.

Certainty MUST be expressed through fields such as:

```text
certainty_level
validated_as
assertion_status
validation_status
recognition_status
```

An artifact may be signed and still contain low-certainty, disputed, speculative, mythological, fictional, or rejected assertions.

An artifact may be unsigned and still be useful as research material, provided the active reader policy allows it and the status is visible.

### 8.3 Signatures and authority recognition

Authority recognition MUST be represented explicitly through an authority recognition artifact, validation decision, registry entry, or policy-defined equivalent.

A signature may support recognition, but it does not replace the recognition record unless a profile explicitly defines that behavior.

### 8.4 Signatures and reader policy

Reader policies decide which materials are visible or trusted in a particular view.

A reader policy MAY require:

* signed artifacts only;
* signatures from specific authority channels;
* signatures with specific `purpose` values;
* validation decisions signed by recognized validators;
* runtime packs signed by recognized distributors;
* unsigned or partially verified artifacts to remain hidden by default.

A reader policy MAY also allow unsigned, unverified, disputed, fictional, mythological, or low-certainty material in research, creative, archival, or diagnostic modes.

---

## 9. Optional attestation layers

Implementations MAY support multiple signatures in `signatures[]`.

Common signature purposes include:

* `publisher`: the entity that released the artifact
* `validator`: the entity that issued a validation decision
* `authority`: the authority channel recognizing or classifying the artifact
* `auditor`: a third party that reviewed the artifact
* `distributor`: the entity that served or packaged the artifact
* `reviewer`: a person, group, or system that participated in review
* `compiler`: the system that compiled the artifact
* `registry`: the registry that accepted or indexed the artifact

A deployment MAY require:

* at least one valid required signature;
* a specific `purpose` signature;
* a signature from a specific authority channel;
* multiple independent signatures;
* a signature chain;
* a signature plus a validation decision;
* a signature plus a transparency-log entry.

Such requirements MUST be expressed in a validation policy, authority policy, deployment policy, or reader policy.

---

## 10. Revocation and expiry

### 10.1 Expiry

If a signature includes `expires_at`, verifiers SHOULD evaluate it when the active policy requires time validity.

If a signature is expired under the active policy, the signature status SHOULD be `expired`.

Expired signatures MUST NOT satisfy policies requiring currently valid signatures.

A policy MAY still allow expired signatures for archival, historical, or reproducibility purposes.

### 10.2 Revocation

If a key, signature, authority recognition, validation decision, or artifact is revoked, the revocation MUST be represented through a revocation artifact or an authority-channel-specific revocation mechanism.

Revocation evaluation is policy-dependent. Implementations SHOULD expose whether revocation status was checked, unavailable, not applicable, or satisfied.

Recommended revocation statuses:

```text
revocation_status:
  - not_checked
  - not_revoked
  - revoked
  - unknown
  - unavailable_offline
  - not_applicable
```

Offline verifiers SHOULD use the revocation material bundled with the artifact, runtime pack, trust store, registry snapshot, or transparency-log profile.

---

## 11. Transparency log profile

A transparency log is optional but recommended for ecosystems that need public auditability of publication, validation, recognition, revocation, and distribution events.

A transparency log entry MAY record:

* artifact identity
* artifact type
* publisher
* authority channel
* validation decision
* recognition decision
* revocation event
* runtime pack publication
* signature metadata
* timestamp
* inclusion proof
* previous entry or log checkpoint
* signatures over the log entry

A transparency log MUST NOT be required for basic Kristal v5 signature conformance unless a deployment profile explicitly requires it.

---

## 12. Conformance tests

A Kristal v5 implementation MUST provide test vectors that cover:

* positive verification cases with valid identity and valid signature;
* negative cases where artifact tampering causes identity mismatch;
* wrong key;
* missing key;
* malformed signature;
* unsupported algorithm on a required signature;
* expired signature when expiry is policy-enforced;
* required and optional signature mixes;
* multiple signatures with mixed results;
* unsigned artifacts;
* artifacts allowed by research or diagnostic policy despite missing signatures;
* artifacts rejected by a strict reader or activation policy because required verification is not satisfied.

Test vectors SHOULD include:

* Structured Epistemic State artifacts
* Exchange artifacts
* Runtime Pack manifests
* Exchange Shard manifests
* Exchange Federation manifests
* Authority Recognition artifacts
* Validation Decision artifacts
* Revocation artifacts
* multiple `key_id` resolutions
* multiple trust stores
* tenant-scoped and authority-channel-scoped trust roots

A conformant implementation MUST clearly distinguish:

* identity verification;
* signature verification;
* policy acceptance;
* validation status;
* authority recognition;
* certainty level;
* reader visibility.

---

## 13. Interoperability requirements

A Kristal v5 implementation claiming signature conformance MUST:

1. support `ed25519`;
2. support `sha256` content identities;
3. support `kristal.v5:jcs-rfc8785` canonicalization;
4. exclude signatures from hash targets;
5. exclude self-identity fields from their own hash targets;
6. expose per-signature verification status;
7. expose artifact-level verification status;
8. support unsigned artifacts as a distinct status;
9. avoid treating signature verification as universal validation;
10. support offline verification with supplied trust roots.

---

## 14. Security considerations

Implementations SHOULD defend against:

* signature wrapping attacks;
* signature fields embedded outside the top-level `signatures` array;
* hash target ambiguity;
* self-referential identity hashing;
* unsupported algorithm downgrade;
* key substitution;
* stale trust roots;
* revoked keys;
* expired signatures;
* tenant/environment trust confusion;
* authority-channel confusion;
* validation laundering;
* rendering verified signatures as universal truth;
* hiding failed or missing verification status from users or downstream systems.

User interfaces and APIs SHOULD avoid ambiguous labels such as:

```text
trusted
true
canonical
official
safe
```

unless the label is scoped by authority channel, reader policy, validation decision, and certainty level.

Preferred labels include:

```text
signed
identity-verified
signature-verified
recognized by <authority channel>
validated as <status>
reference under <reader policy>
not verified
verification failed
unsigned
```

---

## 15. Open questions

The following profile decisions remain open:

* Should `expires_at` become required for some authority-channel signatures?
* Should `key_id` use a required fingerprint format instead of allowing stable strings?
* Should the transparency log profile be mandatory for public authority recognition?
* Should signatures bind only content identity, or also selected policy metadata?
* Should runtime-pack signatures include additional pack-level integrity surfaces beyond the content identity of the manifest?
* Should validation decisions require separate signatures from both validator and authority channel?
* Should reader policies be signed when distributed in Runtime Packs?
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/01-core-spec/structured-epistemic-state.md"
id=03b159b0e78e
kind=markdown
size=27482
lines=1258
line_ref=1-1258
chunks=4
chunk_refs=1-350,351-700,701-1050,1051-1258
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=03b159b0e78e:1-350
start=1
end=350
----
# Structured Epistemic State

## Status

Draft

## Spec

Kristal v5

## Purpose

This document defines the **Structured Epistemic State** as the primary input unit for Kristal v5.

A Structured Epistemic State is a deterministic, portable, inspectable representation of knowledge work before it becomes an Exchange, shard, federation, Runtime Pack, or recognized reference artifact.

It can contain:

* hypotheses
* claims
* sourced assertions
* reviewed assertions
* validated assertions
* disputed assertions
* rejected assertions
* fictional or mythological assertions
* institutional declarations
* technical declarations
* research material
* imported dataset statements
* authority-scoped recognition metadata

A Structured Epistemic State is not required to contain only high-certainty or fully validated material. Its role is to preserve epistemic structure: what is being asserted, by whom, from which sources, under which scope, with which status, and with which level of certainty.

## Core Principle

A Kristal may contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.

A Kristal must not present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.

## Definition

A **Structured Epistemic State** is a JSON-compatible artifact that groups assertions, provenance, evidence, scope, certainty metadata, validation metadata, authority references, review references, and lineage into a deterministic input for Kristal v5 compilation.

It is the preferred input boundary for Kristal v5.

It is not a workflow object, user interface object, task object, or review case. Workflow ownership belongs to Orgo. Distribution ownership belongs to Konnaxion. Rendering ownership belongs to Architect. Resolution and normalization support may be provided by SenTient. Kristal owns the artifact structure, identity, compilation semantics, and portable query contract.

## Relationship to Claim-IR

Claim-IR remains supported as an extractor proposal profile.

Claim-IR may be used when an extractor, parser, OCR system, LLM, scraper, or resolver produces proposed claims that require normalization before entering the Kristal artifact layer.

Claim-IR is not the universal required input format for Kristal v5.

Valid input paths include:

```text
LLM / OCR / parser / scraper
-> Claim-IR
-> Structured Epistemic State
-> Working Exchange
```

```text
Human expert
-> Structured Epistemic State
-> Working Exchange
```

```text
Institutional dataset
-> Structured Epistemic State
-> Working Exchange
```

```text
Wikidata-compatible corpus
-> Structured Epistemic State or Exchange-compatible source package
-> Working Exchange
```

Claim-IR should be treated as an extraction and proposal format. Structured Epistemic State is the normative Kristal v5 state format.

## Conceptual Model

A Structured Epistemic State separates:

```text
artifact existence
artifact integrity
assertion status
certainty level
validation status
authority recognition
reader visibility
```

These are independent dimensions.

A state may be structurally valid and content-addressable while containing assertions that are unresolved, low-certainty, disputed, fictional, rejected, or not yet evaluated.

A state may contain assertions that are validated at different certainty levels.

Validation does not always mean high certainty. Validation means that an assertion or artifact has been accepted as a specific kind of thing, by a specific authority channel, under a specific policy, for a specific scope.

Examples:

```text
validated as hypothesis
validated as mythological corpus
validated as publisher declaration
validated as technical specification
validated as high-confidence fact
validated as disputed position
validated as rejected claim
```

## Normative Keywords

The keywords **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as described in RFC 2119 and RFC 8174 when they appear in uppercase.

## Artifact Type

The artifact type for this document is:

```text
structured_epistemic_state
```

A conforming Structured Epistemic State MUST declare:

```json
{
  "schema_version": "5.0",
  "artifact_type": "structured_epistemic_state"
}
```

## Required Top-Level Fields

A Structured Epistemic State MUST contain:

```text
schema_version
artifact_type
state_id
created_at
created_by
scope
assertions
provenance
```

A Structured Epistemic State SHOULD contain:

```text
source_refs
evidence_refs
authority_channel_refs
authority_recognition_refs
validation_refs
review_refs
policy_refs
lineage
certainty_summary
validation_summary
extensions
```

## Minimal Shape

```json
{
  "schema_version": "5.0",
  "artifact_type": "structured_epistemic_state",
  "state_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
  "created_at": "2026-01-01T00:00:00Z",
  "created_by": {
    "type": "individual",
    "id": "creator:example",
    "name": "Example Creator"
  },
  "scope": {
    "domain": "general",
    "subdomain": null,
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": null,
    "language": "en"
  },
  "source_refs": [],
  "evidence_refs": [],
  "authority_channel_refs": [],
  "authority_recognition_refs": [],
  "validation_refs": [],
  "review_refs": [],
  "policy_refs": [],
  "lineage": {
    "source_artifacts": [],
    "transforms": [],
    "compiler": null,
    "policy_refs": []
  },
  "assertions": [],
  "provenance": [],
  "certainty_summary": {},
  "validation_summary": {},
  "extensions": {}
}
```

## Field Definitions

### `schema_version`

Type: string

Required value:

```text
5.0
```

Identifies the Structured Epistemic State schema version.

### `artifact_type`

Type: string

Required value:

```text
structured_epistemic_state
```

Artifact discriminator.

### `state_id`

Type: string

Recommended form:

```text
sha256:<hex>
```

The `state_id` SHOULD be content-addressed.

The `state_id` MUST NOT be included in its own hash target.

The hash target SHOULD exclude signatures and operational timestamps unless a profile explicitly declares otherwise.

### `created_at`

Type: RFC3339 date-time string

Records when this state artifact was produced.

`created_at` is operational metadata. It SHOULD NOT affect content-addressed identity unless a profile explicitly declares it part of the hash target.

### `created_by`

Type: object

Identifies the creator or producer of the state.

Allowed creator types:

```text
individual
community
association
research_collective
academic_institution
standards_body
company
government
intergovernmental_organization
ai_validator
hybrid_collective
software_agent
system_process
```

Recommended shape:

```json
{
  "type": "software_agent",
  "id": "agent:example",
  "name": "Example Extractor",
  "authority_channel_id": "authority:example-channel"
}
```

### `scope`

Type: object

Defines the domain and context of the state.

The `domain` field is required.

Recommended shape:

```json
{
  "domain": "science",
  "subdomain": "astronomy",
  "jurisdiction": null,
  "time_window": null,
  "tenant_id": null,
  "environment": null,
  "language": "en"
}
```

Allowed domain values:

```text
general
wikidata
science
health
education
heritage
law
policy
technology
environment
culture
mythology
fiction
research
operations
civic
local_notes
```

A Structured Epistemic State SHOULD use the narrowest useful scope.

A scope MUST NOT imply global validity. Scope only defines where the state is intended to apply.

### `source_refs`

Type: array
--- CHUNK END ---

--- CHUNK BEGIN ---
id=03b159b0e78e:351-700
start=351
end=700
----

References to source artifacts, datasets, documents, corpora, APIs, uploads, or prior Kristal artifacts.

Each source ref SHOULD include:

```text
artifact_type
id
ref
content_hash
```

Example:

```json
{
  "artifact_type": "source_document",
  "id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "ref": "sources/source-001.pdf",
  "content_hash": {
    "alg": "sha256",
    "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### `evidence_refs`

Type: array

References to evidence objects used by assertions.

Evidence may include documents, datasets, observations, instrument readings, citations, audit reports, prototypes, tests, or authority attestations.

Evidence references do not automatically validate an assertion. They provide material that a validation policy may evaluate.

### `authority_channel_refs`

Type: array

References to authority channels relevant to the state.

Authority channels identify who may recognize, validate, classify, or reject assertions within a declared scope.

Example:

```json
{
  "authority_channel_id": "authority:who",
  "name": "World Health Organization",
  "scope": {
    "domain": "health",
    "subdomain": "public-health",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": null,
    "language": "en"
  }
}
```

### `authority_recognition_refs`

Type: array

References to authority recognition records.

Recognition by one authority channel MUST NOT imply recognition by another authority channel.

### `validation_refs`

Type: array

References to validation reports or validation decisions.

Validation references SHOULD be scoped and SHOULD identify:

```text
target level
authority channel
validation policy
validation status
validated-as classification
certainty level
scope
```

### `review_refs`

Type: array

References to review records, review cases, audit notes, or Orgo workflow outputs.

Review is not the same as validation.

A review may support validation, but review alone does not imply recognition unless the applicable authority policy says so.

### `policy_refs`

Type: array

References to policies used to interpret, validate, compile, recognize, or read the state.

Examples:

```text
validation policy
reader policy
composition policy
runtime pack policy
authority registry policy
revocation policy
```

### `lineage`

Type: object

Records how this state relates to source material, transforms, merges, prior artifacts, and compiler behavior.

Recommended shape:

```json
{
  "source_artifacts": [],
  "transforms": [],
  "compiler": {
    "name": "kristal-compiler",
    "version": "5.0"
  },
  "policy_refs": []
}
```

Lineage is intended for traceability, not historical storytelling.

### `assertions`

Type: array

The core list of structured assertions.

Each assertion MUST have:

```text
assertion_id
statement
assertion_status
certainty_level
scope
provenance_refs
```

Each assertion SHOULD have:

```text
validated_as
validation_status
authority_channel_refs
authority_recognition_refs
evidence_refs
review_refs
policy_refs
lineage
extensions
```

### `provenance`

Type: array

Provenance records attached to source refs, assertions, evidence refs, validation refs, or state-level transformations.

Provenance SHOULD be sufficient to answer:

```text
Where did this assertion come from?
Who produced it?
When was it produced?
Which source material supports it?
Which transformations were applied?
Which authority or policy evaluated it?
```

### `certainty_summary`

Type: object

Optional summary of certainty distribution across assertions.

Example:

```json
{
  "unknown": 2,
  "speculative": 1,
  "low": 4,
  "medium": 12,
  "high": 8,
  "established": 3,
  "not_applicable": 5
}
```

### `validation_summary`

Type: object

Optional summary of validation distribution across assertions.

Example:

```json
{
  "not_evaluated": 7,
  "in_review": 3,
  "validated": 12,
  "conditionally_validated": 4,
  "disputed": 2,
  "rejected": 1,
  "revoked": 0
}
```

### `extensions`

Type: object

Implementation-specific fields.

Extensions MUST NOT change core identity, validation, certainty, authority, provenance, or compilation semantics unless a profile explicitly defines the extension as normative.

## Assertion Model

An assertion is a structured statement with metadata.

Minimal assertion shape:

```json
{
  "assertion_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
  "statement": {
    "subject": {
      "type": "entity",
      "id": "Q42"
    },
    "predicate": {
      "type": "property",
      "id": "P31"
    },
    "object": {
      "type": "entity",
      "id": "Q5"
    }
  },
  "assertion_status": "sourced",
  "certainty_level": "medium",
  "validated_as": "sourced_claim",
  "validation_status": "not_evaluated",
  "scope": {
    "domain": "wikidata",
    "subdomain": null,
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": null,
    "language": "en"
  },
  "provenance_refs": [],
  "evidence_refs": [],
  "authority_channel_refs": [],
  "authority_recognition_refs": [],
  "validation_refs": [],
  "review_refs": [],
  "policy_refs": [],
  "lineage": {},
  "extensions": {}
}
```

## Statement Model

The `statement` object represents the assertion itself.

Recommended fields:

```text
subject
predicate
object
qualifiers
references
rank
```

Example:

```json
{
  "subject": {
    "type": "entity",
    "id": "Q42"
  },
  "predicate": {
    "type": "property",
    "id": "P31"
  },
  "object": {
    "type": "entity",
    "id": "Q5"
  },
  "qualifiers": [],
  "references": [],
  "rank": "normal"
}
```

The statement object MAY be compatible with Wikidata-like entity and property models, RDF-like triple models, document claims, local ontology assertions, or domain-specific structured records.

The statement object MUST be deterministic under the selected canonicalization profile.

## Assertion Status

Allowed assertion statuses:

```text
hypothesis
claimed
sourced
disputed
reviewed
validated
rejected
retracted
superseded
```

### `hypothesis`

The assertion is explicitly speculative and may be useful for research, exploration, or future validation.

### `claimed`

The assertion has been made by a source or publisher but does not yet carry sufficient evidence or review metadata.

### `sourced`

The assertion has at least one source or evidence reference.

--- CHUNK END ---

--- CHUNK BEGIN ---
id=03b159b0e78e:701-1050
start=701
end=1050
----
### `disputed`

The assertion is contested by at least one relevant authority channel, reviewer, or conflicting source.

### `reviewed`

The assertion has been reviewed under a declared process.

### `validated`

The assertion has been accepted under a declared validation policy, by a declared authority channel, for a declared scope.

### `rejected`

The assertion has been rejected under a declared validation policy or authority channel.

### `retracted`

The publisher or responsible authority has withdrawn the assertion.

### `superseded`

A newer assertion or artifact is intended to replace the assertion for a declared scope.

## Validation Status

Allowed validation statuses:

```text
not_evaluated
in_review
validated
conditionally_validated
disputed
rejected
revoked
```

A validation status MUST NOT be interpreted without:

```text
authority channel
validation policy
scope
validated-as value
certainty level
```

A boolean such as:

```json
{
  "validated": true
}
```

is not sufficient in Kristal v5.

## Validated-As Classification

Allowed `validated_as` values:

```text
hypothesis
claim
sourced_claim
reviewed_claim
high_confidence_fact
institutional_reference
publisher_declaration
technical_specification
legal_or_policy_position
mythological_corpus
fictional_corpus
symbolic_model
disputed_position
rejected_claim
```

Validation answers:

```text
accepted as what?
by whom?
under which policy?
for which scope?
```

Certainty answers:

```text
how strong is the assertion within that scope?
```

## Certainty Level

Allowed certainty levels:

```text
unknown
speculative
low
medium
high
established
not_applicable
```

### `unknown`

No useful certainty estimate is available.

### `speculative`

The assertion is intentionally exploratory.

### `low`

The assertion has weak support or unresolved uncertainty.

### `medium`

The assertion has meaningful support but is not treated as high-confidence.

### `high`

The assertion is strongly supported within the declared scope.

### `established`

The assertion is stable enough to be treated as a reference-level assertion under the selected authority channel and reader policy.

### `not_applicable`

The assertion is valid in a mode where factual certainty is not the relevant measure, such as fiction, mythology, symbolic systems, publisher declarations, or technical specifications.

## Authority Channels

Authority channels are scoped.

An authority channel may recognize, validate, reject, classify, or delegate trust for a domain.

Authority recognition is not universal.

Example:

```json
{
  "authority_channel_id": "authority:example-medical-body",
  "name": "Example Medical Body",
  "authority_type": "association",
  "scope": {
    "domain": "health",
    "subdomain": "clinical-guidelines",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": null,
    "language": "en"
  },
  "recognized_by": [
    "authority:example-global-reference"
  ],
  "trust_roots": [],
  "validation_policies": [],
  "revocation_policy_ref": null
}
```

Allowed authority types:

```text
individual
community
association
research_collective
academic_institution
standards_body
company
government
intergovernmental_organization
ai_validator
hybrid_collective
software_agent
system_process
```

## Reader Policy Interaction

Structured Epistemic States may contain more material than a reader chooses to display.

A reader policy determines which assertions are visible under a given context.

Reader policies may filter by:

```text
artifact status
assertion status
validation status
certainty level
validated-as value
authority channel
recognition status
scope domain
scope subdomain
disputed inclusion
fiction inclusion
mythology inclusion
```

Allowed reader modes:

```text
reference_only
validated_only
high_certainty_only
research
creative
all_with_labels
custom
```

“Validated-only” means all visible assertions satisfy the active reader policy.

It does not mean:

```text
all visible assertions have maximum certainty
all visible assertions are universally accepted
all authorities agree
all assertions are physical-world factual claims
```

## Compilation Semantics

A Structured Epistemic State may compile into a Working Exchange.

Compilation means that the state has been materialized into a deterministic artifact form.

Compilation does not by itself mean that all assertions are validated, recognized, high-certainty, or reference-level.

A Working Exchange may contain assertions with different statuses and certainty levels.

A Reference Exchange requires explicit validation or recognition according to the relevant authority channel, validation policy, scope, and reader policy.

## Conformance Requirements

A conforming Structured Epistemic State MUST:

1. declare `schema_version = "5.0"`;
2. declare `artifact_type = "structured_epistemic_state"`;
3. contain a deterministic `state_id`;
4. declare a scope with at least `domain`;
5. represent assertions with explicit assertion status;
6. represent certainty level explicitly;
7. preserve provenance references when available;
8. avoid representing scoped validation as universal validation;
9. avoid representing authority recognition by one channel as recognition by another;
10. remain deterministic under the declared canonicalization profile.

A conforming Structured Epistemic State SHOULD:

1. include evidence refs when assertions are sourced;
2. include validation refs when assertions have been evaluated;
3. include authority recognition refs when relevant;
4. include review refs when review occurred;
5. include policy refs for validation, reader policy, composition, or runtime use;
6. include lineage sufficient to reproduce or audit the state;
7. include summaries for validation and certainty distribution.

## Determinism Requirements

The state MUST be serializable under:

```text
kristal.v5:jcs-rfc8785
```

with canonicalization version:

```text
1
```

The hash algorithm SHOULD be:

```text
sha256
```

The content-addressed hash target SHOULD exclude:

```text
state_id
signatures
created_at
operational logs
non-deterministic runtime metadata
```

unless a profile explicitly declares otherwise.

Repeated builds from identical inputs and identical policy settings SHOULD produce identical content hashes.

## Integrity

Integrity protects artifact identity and provenance.

Integrity does not claim that every assertion is true.

A Structured Epistemic State may be integrity-valid and still contain unresolved, low-certainty, disputed, fictional, mythological, rejected, or otherwise non-reference assertions.

## Common Patterns

### Hypothesis

```json
{
  "assertion_id": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
  "statement": {
    "subject": {
      "type": "local_entity",
      "id": "research:prototype-x"
    },
    "predicate": {
      "type": "property",
      "id": "may_reduce_pollution"
    },
    "object": {
      "type": "boolean",
      "value": true
    }
  },
  "assertion_status": "hypothesis",
  "validation_status": "not_evaluated",
  "validated_as": "hypothesis",
  "certainty_level": "speculative",
  "scope": {
    "domain": "research",
    "subdomain": "environmental-technology",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": null,
    "language": "en"
  },
  "provenance_refs": [],
  "evidence_refs": [],
  "authority_channel_refs": [],
  "authority_recognition_refs": [],
--- CHUNK END ---

--- CHUNK BEGIN ---
id=03b159b0e78e:1051-1258
start=1051
end=1258
----
  "validation_refs": [],
  "review_refs": [],
  "policy_refs": [],
  "lineage": {},
  "extensions": {}
}
```

### Mythological Corpus Assertion

```json
{
  "assertion_id": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
  "statement": {
    "subject": {
      "type": "mythological_entity",
      "id": "example:unicorn"
    },
    "predicate": {
      "type": "property",
      "id": "has_trait"
    },
    "object": {
      "type": "text",
      "value": "horned horse-like creature"
    }
  },
  "assertion_status": "validated",
  "validation_status": "validated",
  "validated_as": "mythological_corpus",
  "certainty_level": "not_applicable",
  "scope": {
    "domain": "mythology",
    "subdomain": "example-corpus",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": null,
    "language": "en"
  },
  "provenance_refs": [],
  "evidence_refs": [],
  "authority_channel_refs": [
    "authority:example-cultural-archive"
  ],
  "authority_recognition_refs": [],
  "validation_refs": [],
  "review_refs": [],
  "policy_refs": [],
  "lineage": {},
  "extensions": {}
}
```

### Publisher Declaration

```json
{
  "assertion_id": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
  "statement": {
    "subject": {
      "type": "software_system",
      "id": "vendor:system-a"
    },
    "predicate": {
      "type": "property",
      "id": "supports_feature"
    },
    "object": {
      "type": "text",
      "value": "offline query cache"
    }
  },
  "assertion_status": "validated",
  "validation_status": "validated",
  "validated_as": "publisher_declaration",
  "certainty_level": "not_applicable",
  "scope": {
    "domain": "technology",
    "subdomain": "publisher-system-description",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": "production",
    "language": "en"
  },
  "provenance_refs": [],
  "evidence_refs": [],
  "authority_channel_refs": [
    "authority:vendor"
  ],
  "authority_recognition_refs": [],
  "validation_refs": [],
  "review_refs": [],
  "policy_refs": [],
  "lineage": {},
  "extensions": {}
}
```

## Interaction With Other Kristal Artifacts

### Exchange

A Structured Epistemic State may be compiled into:

```text
working_exchange
reference_exchange
```

The output status depends on validation, recognition, and policy.

### Validation Report

A validation report may evaluate:

```text
the state as a whole
an assertion
a group of assertions
a shard
an Exchange
a Runtime Pack
```

### Authority Recognition

Authority recognition may target:

```text
artifact
shard
assertion
authority_channel
dataset
runtime_pack
```

### Runtime Pack

A Runtime Pack may be built from a Working Exchange or Reference Exchange.

The Runtime Pack MUST preserve enough metadata to determine:

```text
source artifact status
reader policy refs
validation refs
authority recognition refs
certainty labels
```

### Federation

A federation may compose shards derived from multiple Structured Epistemic States.

Federation preserves source identity and authority context. It must not silently merge disagreement.

## Security and Privacy Considerations

Structured Epistemic States may contain sensitive source references, unpublished research, personal data, institutional records, or disputed claims.

Implementations SHOULD:

* avoid leaking raw source content in logs;
* preserve source hashes instead of raw documents where possible;
* keep tenant boundaries explicit;
* avoid mixing authority scopes silently;
* preserve labels for disputed, rejected, fictional, mythological, or low-certainty assertions;
* ensure signatures and hashes protect the intended artifact target.

## Operational Notes

A Structured Epistemic State is often created before review, validation, authority recognition, or publication.

Operational systems SHOULD therefore support:

```text
partial states
draft states
working states
under-review states
validation reports
authority recognition records
reader policy filtering
revocation and replacement records
```

Operational systems SHOULD NOT assume that a compiled artifact is a reference artifact.

## Summary

Structured Epistemic State is the primary Kristal v5 state format.

It allows knowledge, hypotheses, references, myths, technical declarations, research claims, institutional corpora, and disputed forks to coexist without confusion.

Validation is scoped.

Authority is plural.

Certainty is explicit.

Readers choose policy.

Federation preserves disagreement.

Integrity protects artifacts.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/assertion-status.schema.json"
id=5f549afd519e
kind=source
size=20099
lines=853
line_ref=1-853
chunks=3
chunk_refs=1-350,351-700,701-853
summary="Source file."

--- CHUNK BEGIN ---
id=5f549afd519e:1-350
start=1
end=350
----
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/assertion-status.schema.json",
  "title": "Kristal v5 Assertion Status",
  "description": "Schema for assertion status, certainty level, validation status, authority recognition, scoped epistemic classification, and reader-policy relevant labels in Kristal v5.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "artifact_type",
    "assertion_id",
    "assertion_status",
    "certainty_level",
    "validation_status",
    "scope"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "5.0"
    },
    "artifact_type": {
      "type": "string",
      "const": "assertion_status"
    },
    "status_record_id": {
      "$ref": "#/$defs/sha256_uri"
    },
    "assertion_id": {
      "type": "string",
      "minLength": 1
    },
    "statement_ref": {
      "$ref": "#/$defs/statement_ref"
    },
    "assertion_status": {
      "$ref": "#/$defs/assertion_status"
    },
    "certainty_level": {
      "$ref": "#/$defs/certainty_level"
    },
    "validation_status": {
      "$ref": "#/$defs/validation_status"
    },
    "validated_as": {
      "$ref": "#/$defs/validated_as"
    },
    "recognition_status": {
      "$ref": "#/$defs/recognition_status"
    },
    "scope": {
      "$ref": "#/$defs/scope"
    },
    "authority_channel": {
      "$ref": "#/$defs/authority_ref"
    },
    "validation_policy_ref": {
      "$ref": "#/$defs/policy_ref"
    },
    "recognition_policy_ref": {
      "$ref": "#/$defs/policy_ref"
    },
    "reader_policy_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/reader_policy_ref"
      },
      "default": []
    },
    "validation_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "authority_recognition_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/authority_recognition_ref"
      },
      "default": []
    },
    "provenance_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "evidence_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/evidence_ref"
      },
      "default": []
    },
    "lineage": {
      "$ref": "#/$defs/lineage"
    },
    "reason_codes": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/reason_code"
      },
      "default": []
    },
    "findings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/finding"
      },
      "default": []
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "created_by": {
      "$ref": "#/$defs/agent_ref"
    },
    "expires_at": {
      "type": ["string", "null"],
      "format": "date-time"
    },
    "replaces_status_record_id": {
      "$ref": "#/$defs/sha256_uri"
    },
    "canonicalization_profile": {
      "type": "string",
      "const": "kristal.v5:jcs-rfc8785"
    },
    "canonicalization_version": {
      "type": "string",
      "const": "1"
    },
    "content_hash": {
      "$ref": "#/$defs/hash_ref"
    },
    "hash_target_policy": {
      "$ref": "#/$defs/hash_target_policy"
    },
    "signatures": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/signature"
      },
      "default": []
    },
    "extensions": {
      "type": "object",
      "additionalProperties": true,
      "default": {}
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "validation_status": {
            "enum": ["validated", "conditionally_validated", "rejected", "revoked"]
          }
        },
        "required": ["validation_status"]
      },
      "then": {
        "required": [
          "validated_as",
          "authority_channel",
          "validation_policy_ref",
          "scope"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "recognition_status": {
            "enum": [
              "recognized",
              "conditionally_recognized",
              "disputed",
              "rejected",
              "deprecated",
              "revoked"
            ]
          }
        },
        "required": ["recognition_status"]
      },
      "then": {
        "required": [
          "authority_channel",
          "recognition_policy_ref",
          "scope"
        ]
      }
    }
  ],
  "$defs": {
    "sha256_hex": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}$"
    },
    "sha256_uri": {
      "type": "string",
      "pattern": "^sha256:[0-9a-fA-F]{64}$"
    },
    "hash_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["alg", "value"],
      "properties": {
        "alg": {
          "type": "string",
          "const": "sha256"
        },
        "value": {
          "$ref": "#/$defs/sha256_hex"
        }
      }
    },
    "hash_target_policy": {
      "type": "object",
      "additionalProperties": false,
      "required": ["exclude_fields"],
      "properties": {
        "exclude_fields": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "status_record_id",
              "content_hash",
              "signatures"
            ]
          },
          "uniqueItems": true
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "signature": {
      "type": "object",
      "additionalProperties": false,
      "required": ["key_id", "alg", "signature", "created_at"],
      "properties": {
        "key_id": {
          "type": "string",
          "minLength": 1
        },
        "alg": {
          "type": "string",
          "const": "ed25519"
        },
        "signature": {
          "type": "string",
          "minLength": 1
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      }
    },
    "assertion_status": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claimed",
        "sourced",
        "disputed",
        "reviewed",
        "validated",
        "rejected",
        "retracted",
        "superseded"
      ]
    },
    "certainty_level": {
      "type": "string",
      "enum": [
        "unknown",
        "speculative",
        "low",
        "medium",
        "high",
        "established",
        "not_applicable"
      ]
    },
    "validation_status": {
      "type": "string",
      "enum": [
        "not_evaluated",
        "in_review",
        "validated",
        "conditionally_validated",
        "disputed",
        "rejected",
        "revoked"
      ]
    },
    "validated_as": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claim",
        "sourced_claim",
        "reviewed_claim",
        "high_confidence_fact",
        "institutional_reference",
        "publisher_declaration",
        "technical_specification",
        "legal_or_policy_position",
        "mythological_corpus",
        "fictional_corpus",
        "symbolic_model",
        "disputed_position",
        "rejected_claim"
      ]
    },
    "recognition_status": {
      "type": "string",
      "enum": [
        "not_evaluated",
        "recognized",
        "conditionally_recognized",
        "under_review",
        "disputed",
        "rejected",
        "deprecated",
        "revoked"
      ]
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": ["domain"],
      "properties": {
        "domain": {
          "type": "string",
          "enum": [
            "general",
            "wikidata",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=5f549afd519e:351-700
start=351
end=700
----
            "science",
            "health",
            "education",
            "heritage",
            "law",
            "policy",
            "technology",
            "environment",
            "culture",
            "mythology",
            "fiction",
            "research",
            "operations",
            "civic",
            "local_notes"
          ]
        },
        "subdomain": {
          "type": ["string", "null"]
        },
        "jurisdiction": {
          "type": ["string", "null"]
        },
        "time_window": {
          "type": ["string", "null"]
        },
        "tenant_id": {
          "type": ["string", "null"]
        },
        "environment": {
          "type": ["string", "null"]
        },
        "language": {
          "type": ["string", "null"]
        }
      }
    },
    "authority_channel_id": {
      "type": "string",
      "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
    },
    "authority_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["authority_channel_id"],
      "properties": {
        "authority_channel_id": {
          "$ref": "#/$defs/authority_channel_id"
        },
        "name": {
          "type": "string"
        },
        "authority_registry_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      }
    },
    "artifact_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "artifact_id": {
          "type": "string",
          "minLength": 1
        },
        "artifact_type": {
          "type": "string",
          "minLength": 1
        },
        "uri": {
          "type": "string",
          "format": "uri"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "anyOf": [
        {
          "required": ["artifact_id"]
        },
        {
          "required": ["uri"]
        },
        {
          "required": ["content_hash"]
        }
      ]
    },
    "policy_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "policy_id": {
          "type": "string",
          "minLength": 1
        },
        "policy_version": {
          "type": "string",
          "minLength": 1
        },
        "policy_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      },
      "anyOf": [
        {
          "required": ["policy_id"]
        },
        {
          "required": ["policy_ref"]
        }
      ]
    },
    "reader_mode": {
      "type": "string",
      "enum": [
        "reference_only",
        "validated_only",
        "high_certainty_only",
        "research",
        "creative",
        "all_with_labels",
        "custom"
      ]
    },
    "reader_policy_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "reader_policy_id": {
          "type": "string",
          "pattern": "^reader_policy:[a-z0-9][a-z0-9._:-]*$"
        },
        "mode": {
          "$ref": "#/$defs/reader_mode"
        },
        "policy_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      },
      "anyOf": [
        {
          "required": ["reader_policy_id"]
        },
        {
          "required": ["policy_ref"]
        }
      ]
    },
    "source_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "source_id": {
          "type": "string",
          "minLength": 1
        },
        "source_type": {
          "type": "string",
          "enum": [
            "dataset",
            "document",
            "web_page",
            "wikidata_dump",
            "api_result",
            "human_submission",
            "institutional_record",
            "claim_ir",
            "resolved_claim_ir",
            "structured_epistemic_state",
            "exchange",
            "runtime_pack",
            "other"
          ]
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        },
        "title": {
          "type": "string"
        },
        "publisher": {
          "type": "string"
        },
        "retrieved_at": {
          "type": "string",
          "format": "date-time"
        },
        "license": {
          "type": "string"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      },
      "anyOf": [
        {
          "required": ["source_id"]
        },
        {
          "required": ["source_url"]
        },
        {
          "required": ["content_hash"]
        }
      ]
    },
    "evidence_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["source_ref"],
      "properties": {
        "evidence_id": {
          "type": "string",
          "minLength": 1
        },
        "source_ref": {
          "$ref": "#/$defs/source_ref"
        },
        "quote": {
          "type": "string"
        },
        "page": {
          "type": "integer",
          "minimum": 1
        },
        "section": {
          "type": "string"
        },
        "offsets": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "start_char": {
              "type": "integer",
              "minimum": 0
            },
            "end_char": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "evidence_status": {
          "type": "string",
          "enum": [
            "provided",
            "missing",
            "weak",
            "sufficient",
            "contested"
          ]
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        }
      }
    },
    "authority_recognition_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["recognition_status", "authority_channel"],
      "properties": {
        "recognition_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "recognition_status": {
          "$ref": "#/$defs/recognition_status"
        },
        "recognized_as": {
          "$ref": "#/$defs/validated_as"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "validation_policy_ref": {
          "$ref": "#/$defs/policy_ref"
        },
        "recognition_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      }
    },
    "agent_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "agent_id": {
          "type": "string",
          "minLength": 1
        },
        "name": {
          "type": "string"
        },
        "agent_type": {
          "type": "string",
          "enum": [
            "individual",
            "community",
            "association",
            "research_collective",
            "academic_institution",
            "standards_body",
            "company",
            "government",
            "intergovernmental_organization",
            "ai_validator",
            "hybrid_collective",
            "service",
            "system"
          ]
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      },
      "anyOf": [
        {
          "required": ["agent_id"]
        },
        {
          "required": ["name"]
        },
        {
          "required": ["authority_channel"]
        }
      ]
    },
    "statement_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "statement_id": {
          "type": "string",
          "minLength": 1
        },
        "statement_hash": {
          "$ref": "#/$defs/hash_ref"
--- CHUNK END ---

--- CHUNK BEGIN ---
id=5f549afd519e:701-853
start=701
end=853
----
        },
        "subject_ref": {
          "type": "string",
          "minLength": 1
        },
        "predicate_ref": {
          "type": "string",
          "minLength": 1
        },
        "object_ref": {
          "type": "string",
          "minLength": 1
        },
        "source_artifact_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      },
      "anyOf": [
        {
          "required": ["statement_id"]
        },
        {
          "required": ["statement_hash"]
        },
        {
          "required": ["source_artifact_ref"]
        }
      ]
    },
    "lineage": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "source_assertions": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "source_artifacts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "transforms": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/transform_record"
          }
        }
      }
    },
    "transform_record": {
      "type": "object",
      "additionalProperties": false,
      "required": ["transform_id", "transform_type"],
      "properties": {
        "transform_id": {
          "type": "string",
          "minLength": 1
        },
        "transform_type": {
          "type": "string",
          "enum": [
            "import",
            "extraction",
            "resolution",
            "normalization",
            "merge",
            "split",
            "manual_edit",
            "review",
            "validation",
            "recognition",
            "revocation"
          ]
        },
        "tool": {
          "type": "string"
        },
        "policy_ref": {
          "$ref": "#/$defs/policy_ref"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "finding": {
      "type": "object",
      "additionalProperties": false,
      "required": ["finding_id", "severity", "message"],
      "properties": {
        "finding_id": {
          "type": "string",
          "minLength": 1
        },
        "severity": {
          "type": "string",
          "enum": [
            "info",
            "warning",
            "error",
            "critical"
          ]
        },
        "message": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "reason_code": {
          "$ref": "#/$defs/reason_code"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      }
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "schema_valid",
        "schema_invalid",
        "provenance_sufficient",
        "provenance_insufficient",
        "evidence_sufficient",
        "evidence_insufficient",
        "authority_recognized",
        "authority_not_recognized",
        "scope_mismatch",
        "policy_satisfied",
        "policy_failed",
        "signature_valid",
        "signature_invalid",
        "hash_valid",
        "hash_invalid",
        "conflict_detected",
        "disagreement_preserved",
        "certainty_too_low_for_policy",
        "rejected_by_authority_channel",
        "revoked_by_authority_channel"
      ]
    }
  }
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/authority-recognition.schema.json"
id=c2217a68a45d
kind=source
size=22869
lines=944
line_ref=1-944
chunks=3
chunk_refs=1-350,351-700,701-944
summary="Source file."

--- CHUNK BEGIN ---
id=c2217a68a45d:1-350
start=1
end=350
----
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/authority-recognition.schema.json",
  "title": "Authority Recognition v5",
  "description": "Authority Recognition records how one authority channel recognizes, conditionally recognizes, disputes, rejects, deprecates, or revokes a target artifact, shard, assertion, dataset, runtime pack, or authority channel under an explicit scope and validation policy. Recognition is scoped and does not imply universal truth.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "artifact_type",
    "recognition_id",
    "recognition_status",
    "created_at",
    "issuer_authority_channel",
    "target",
    "target_level",
    "recognized_as",
    "scope",
    "validation_policy_ref"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "5.0"
    },
    "artifact_type": {
      "type": "string",
      "const": "authority_recognition"
    },
    "recognition_id": {
      "$ref": "#/$defs/sha256_uri"
    },
    "recognition_status": {
      "$ref": "#/$defs/recognition_status"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "expires_at": {
      "type": ["string", "null"],
      "format": "date-time"
    },
    "canonicalization_profile": {
      "type": "string",
      "const": "kristal.v5:jcs-rfc8785"
    },
    "canonicalization_version": {
      "type": "string",
      "const": "1"
    },
    "content_hash": {
      "$ref": "#/$defs/hash_ref"
    },
    "hash_target_policy": {
      "$ref": "#/$defs/hash_target_policy"
    },
    "issuer_authority_channel": {
      "$ref": "#/$defs/authority_ref"
    },
    "issuer_agent": {
      "$ref": "#/$defs/agent_ref"
    },
    "target_level": {
      "$ref": "#/$defs/target_level"
    },
    "target": {
      "$ref": "#/$defs/recognition_target"
    },
    "recognized_as": {
      "$ref": "#/$defs/validated_as"
    },
    "scope": {
      "$ref": "#/$defs/scope"
    },
    "validation_policy_ref": {
      "$ref": "#/$defs/validation_policy_ref"
    },
    "recognition_basis": {
      "$ref": "#/$defs/recognition_basis"
    },
    "certainty_level": {
      "$ref": "#/$defs/certainty_level"
    },
    "validation_status": {
      "$ref": "#/$defs/validation_status"
    },
    "assertion_status": {
      "$ref": "#/$defs/assertion_status"
    },
    "delegated_authority_refs": {
      "description": "Authority channels that the issuer recognizes as competent within the declared scope.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/authority_delegation"
      },
      "default": []
    },
    "recognizes_authority_channels": {
      "description": "Authority channels recognized by this recognition artifact. Use when target_level is authority_channel or when the recognition delegates competence to another authority.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/authority_ref"
      },
      "default": []
    },
    "evidence_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/evidence_ref"
      },
      "default": []
    },
    "provenance_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "review_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "supersedes": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "conflicts_with": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "reason_codes": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/reason_code"
      },
      "default": []
    },
    "effects": {
      "$ref": "#/$defs/recognition_effects"
    },
    "reader_policy_effect": {
      "type": "string",
      "description": "Human-readable summary of how readers should treat this recognition under policy-controlled views."
    },
    "notes": {
      "type": "string"
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/warning"
      },
      "default": []
    },
    "signatures": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/signature"
      },
      "default": []
    },
    "extensions": {
      "type": "object",
      "additionalProperties": true,
      "default": {}
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "recognition_status": {
            "enum": ["recognized", "conditionally_recognized"]
          }
        }
      },
      "then": {
        "required": [
          "recognized_as",
          "scope",
          "validation_policy_ref",
          "recognition_basis"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "target_level": {
            "const": "authority_channel"
          }
        }
      },
      "then": {
        "properties": {
          "target": {
            "required": ["authority_channel"]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "target_level": {
            "const": "assertion"
          }
        }
      },
      "then": {
        "properties": {
          "target": {
            "required": ["assertion_id"]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "target_level": {
            "enum": ["artifact", "shard", "dataset", "runtime_pack"]
          }
        }
      },
      "then": {
        "properties": {
          "target": {
            "required": ["artifact_ref"]
          }
        }
      }
    }
  ],
  "$defs": {
    "sha256_hex": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}$"
    },
    "sha256_uri": {
      "type": "string",
      "pattern": "^sha256:[0-9a-fA-F]{64}$"
    },
    "hash_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["alg", "value"],
      "properties": {
        "alg": {
          "type": "string",
          "const": "sha256"
        },
        "value": {
          "$ref": "#/$defs/sha256_hex"
        }
      }
    },
    "hash_target_policy": {
      "type": "object",
      "additionalProperties": false,
      "required": ["exclude_fields"],
      "properties": {
        "exclude_fields": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "recognition_id",
              "content_hash",
              "signatures"
            ]
          },
          "uniqueItems": true
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "signature": {
      "type": "object",
      "additionalProperties": false,
      "required": ["key_id", "alg", "signature", "created_at"],
      "properties": {
        "key_id": {
          "type": "string",
          "minLength": 1
        },
        "alg": {
          "type": "string",
          "const": "ed25519"
        },
        "signature": {
          "type": "string",
          "minLength": 1
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      }
    },
    "qid": {
      "type": "string",
      "pattern": "^Q[1-9][0-9]*$"
    },
    "pid": {
      "type": "string",
      "pattern": "^P[1-9][0-9]*$"
    },
    "lang": {
      "type": "string",
      "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$"
    },
    "authority_channel_id": {
      "type": "string",
      "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
    },
    "authority_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["authority_channel_id"],
      "properties": {
        "authority_channel_id": {
          "$ref": "#/$defs/authority_channel_id"
        },
        "name": {
          "type": "string"
        },
        "authority_type": {
          "$ref": "#/$defs/authority_type"
        },
--- CHUNK END ---

--- CHUNK BEGIN ---
id=c2217a68a45d:351-700
start=351
end=700
----
        "authority_registry_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      }
    },
    "authority_type": {
      "type": "string",
      "enum": [
        "individual",
        "community",
        "association",
        "research_collective",
        "academic_institution",
        "standards_body",
        "company",
        "government",
        "intergovernmental_organization",
        "ai_validator",
        "hybrid_collective"
      ]
    },
    "agent_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "agent_id": {
          "type": "string",
          "minLength": 1
        },
        "name": {
          "type": "string"
        },
        "agent_type": {
          "type": "string",
          "enum": [
            "individual",
            "community",
            "association",
            "research_collective",
            "academic_institution",
            "standards_body",
            "company",
            "government",
            "intergovernmental_organization",
            "ai_validator",
            "hybrid_collective",
            "service",
            "system"
          ]
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      },
      "anyOf": [
        {
          "required": ["agent_id"]
        },
        {
          "required": ["name"]
        },
        {
          "required": ["authority_channel"]
        }
      ]
    },
    "artifact_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "artifact_id": {
          "type": "string",
          "minLength": 1
        },
        "artifact_type": {
          "type": "string",
          "minLength": 1
        },
        "uri": {
          "type": "string",
          "format": "uri"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "anyOf": [
        {
          "required": ["artifact_id"]
        },
        {
          "required": ["uri"]
        },
        {
          "required": ["content_hash"]
        }
      ]
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": ["domain"],
      "properties": {
        "domain": {
          "type": "string",
          "enum": [
            "general",
            "wikidata",
            "science",
            "health",
            "education",
            "heritage",
            "law",
            "policy",
            "technology",
            "environment",
            "culture",
            "mythology",
            "fiction",
            "research",
            "operations",
            "civic",
            "local_notes"
          ]
        },
        "subdomain": {
          "type": ["string", "null"]
        },
        "jurisdiction": {
          "type": ["string", "null"]
        },
        "time_window": {
          "type": ["string", "null"]
        },
        "tenant_id": {
          "type": ["string", "null"]
        },
        "environment": {
          "type": ["string", "null"]
        },
        "language": {
          "type": ["string", "null"]
        }
      }
    },
    "target_level": {
      "type": "string",
      "enum": [
        "artifact",
        "shard",
        "assertion",
        "authority_channel",
        "dataset",
        "runtime_pack"
      ]
    },
    "recognition_target": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "artifact_ref": {
          "$ref": "#/$defs/artifact_ref"
        },
        "assertion_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "statement_id": {
          "type": "string",
          "minLength": 1
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        },
        "dataset_id": {
          "type": "string",
          "minLength": 1
        },
        "runtime_pack_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "description": {
          "type": "string"
        }
      },
      "anyOf": [
        {
          "required": ["artifact_ref"]
        },
        {
          "required": ["assertion_id"]
        },
        {
          "required": ["statement_id"]
        },
        {
          "required": ["authority_channel"]
        },
        {
          "required": ["dataset_id"]
        },
        {
          "required": ["runtime_pack_id"]
        }
      ]
    },
    "recognition_status": {
      "type": "string",
      "enum": [
        "recognized",
        "conditionally_recognized",
        "under_review",
        "disputed",
        "rejected",
        "deprecated",
        "revoked"
      ]
    },
    "validation_status": {
      "type": "string",
      "enum": [
        "not_evaluated",
        "in_review",
        "validated",
        "conditionally_validated",
        "disputed",
        "rejected",
        "revoked"
      ]
    },
    "assertion_status": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claimed",
        "sourced",
        "disputed",
        "reviewed",
        "validated",
        "rejected",
        "retracted",
        "superseded"
      ]
    },
    "certainty_level": {
      "type": "string",
      "enum": [
        "unknown",
        "speculative",
        "low",
        "medium",
        "high",
        "established",
        "not_applicable"
      ]
    },
    "validated_as": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claim",
        "sourced_claim",
        "reviewed_claim",
        "high_confidence_fact",
        "institutional_reference",
        "publisher_declaration",
        "technical_specification",
        "legal_or_policy_position",
        "mythological_corpus",
        "fictional_corpus",
        "symbolic_model",
        "disputed_position",
        "rejected_claim"
      ]
    },
    "validation_policy_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "policy_id": {
          "type": "string",
          "minLength": 1
        },
        "policy_version": {
          "type": "string",
          "minLength": 1
        },
        "policy_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      },
      "anyOf": [
        {
          "required": ["policy_id"]
        },
        {
          "required": ["policy_ref"]
        }
      ]
    },
    "recognition_basis": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "basis_type": {
          "type": "string",
          "enum": [
            "direct_review",
            "delegated_authority",
            "publisher_declaration",
            "institutional_attestation",
            "standards_conformance",
            "evidence_review",
            "dataset_identity",
            "technical_integrity",
            "community_position",
            "automated_validation",
            "hybrid_review"
          ]
        },
        "summary": {
          "type": "string"
        },
        "review_process_ref": {
          "$ref": "#/$defs/artifact_ref"
        },
        "attestation_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        },
        "policy_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/validation_policy_ref"
          },
          "default": []
        }
      }
    },
    "authority_delegation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "delegated_authority_channel",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=c2217a68a45d:701-944
start=701
end=944
----
        "delegation_scope",
        "delegation_status"
      ],
      "properties": {
        "delegated_authority_channel": {
          "$ref": "#/$defs/authority_ref"
        },
        "delegation_scope": {
          "$ref": "#/$defs/scope"
        },
        "delegation_status": {
          "type": "string",
          "enum": [
            "recognized",
            "conditionally_recognized",
            "under_review",
            "rejected",
            "revoked"
          ]
        },
        "delegation_policy_ref": {
          "$ref": "#/$defs/validation_policy_ref"
        },
        "expires_at": {
          "type": ["string", "null"],
          "format": "date-time"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "evidence_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["source_ref"],
      "properties": {
        "evidence_id": {
          "type": "string",
          "minLength": 1
        },
        "source_ref": {
          "$ref": "#/$defs/source_ref"
        },
        "quote": {
          "type": "string"
        },
        "page": {
          "type": "integer",
          "minimum": 1
        },
        "section": {
          "type": "string"
        },
        "offsets": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "start_char": {
              "type": "integer",
              "minimum": 0
            },
            "end_char": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "evidence_status": {
          "type": "string",
          "enum": [
            "provided",
            "missing",
            "weak",
            "sufficient",
            "contested"
          ]
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        }
      }
    },
    "source_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "source_id": {
          "type": "string",
          "minLength": 1
        },
        "source_type": {
          "type": "string",
          "enum": [
            "dataset",
            "document",
            "web_page",
            "wikidata_dump",
            "api_result",
            "human_submission",
            "institutional_record",
            "claim_ir",
            "resolved_claim_ir",
            "structured_epistemic_state",
            "exchange",
            "runtime_pack",
            "other"
          ]
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        },
        "title": {
          "type": "string"
        },
        "publisher": {
          "type": "string"
        },
        "retrieved_at": {
          "type": "string",
          "format": "date-time"
        },
        "license": {
          "type": "string"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      },
      "anyOf": [
        {
          "required": ["source_id"]
        },
        {
          "required": ["source_url"]
        },
        {
          "required": ["content_hash"]
        }
      ]
    },
    "recognition_effects": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "eligible_for_reference_views": {
          "type": "boolean"
        },
        "eligible_for_validated_only_views": {
          "type": "boolean"
        },
        "eligible_for_high_certainty_views": {
          "type": "boolean"
        },
        "requires_visible_label": {
          "type": "boolean"
        },
        "requires_dispute_label": {
          "type": "boolean"
        },
        "requires_authority_label": {
          "type": "boolean"
        },
        "requires_certainty_label": {
          "type": "boolean"
        },
        "distribution_allowed": {
          "type": "boolean"
        },
        "runtime_activation_allowed": {
          "type": "boolean"
        },
        "reader_policy_effect": {
          "type": "string"
        }
      }
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "schema_valid",
        "schema_invalid",
        "provenance_sufficient",
        "provenance_insufficient",
        "evidence_sufficient",
        "evidence_insufficient",
        "authority_recognized",
        "authority_not_recognized",
        "authority_delegated",
        "authority_delegation_expired",
        "scope_mismatch",
        "policy_satisfied",
        "policy_failed",
        "signature_valid",
        "signature_invalid",
        "hash_valid",
        "hash_invalid",
        "conflict_detected",
        "disagreement_preserved",
        "certainty_too_low_for_policy",
        "recognized_by_authority_channel",
        "conditionally_recognized_by_authority_channel",
        "rejected_by_authority_channel",
        "revoked_by_authority_channel",
        "deprecated_by_authority_channel"
      ]
    },
    "warning": {
      "type": "object",
      "additionalProperties": false,
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "LOW_CERTAINTY",
            "DISPUTED_RECOGNITION",
            "CONDITIONAL_RECOGNITION",
            "RECOGNITION_SCOPE_NARROW",
            "AUTHORITY_DELEGATION_USED",
            "AUTHORITY_CHANNEL_UNRECOGNIZED_BY_READER_POLICY",
            "EVIDENCE_WEAK",
            "EVIDENCE_CONTESTED",
            "EXPIRES_AT_PRESENT",
            "CONFLICT_DETECTED"
          ]
        },
        "message": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "reason_code": {
          "$ref": "#/$defs/reason_code"
        }
      }
    }
  }
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/authority-registry.schema.json"
id=89c9703edda5
kind=source
size=21403
lines=748
line_ref=1-748
chunks=3
chunk_refs=1-350,351-700,701-748
summary="Source file."

--- CHUNK BEGIN ---
id=89c9703edda5:1-350
start=1
end=350
----
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/authority-registry.schema.json",
  "title": "Kristal v5 Authority Registry",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "artifact_type",
    "registry_id",
    "created_at",
    "canonicalization_profile",
    "canonicalization_version",
    "content_hash",
    "authority_channels",
    "trust_roots",
    "rules",
    "signatures"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "5.0",
      "description": "Schema version for this registry format."
    },

    "artifact_type": {
      "type": "string",
      "const": "authority_registry",
      "description": "Artifact discriminator."
    },

    "registry_id": {
      "type": "string",
      "pattern": "^(sha256:[a-f0-9]{64}|kristal:authority-registry:sha256:[a-f0-9]{64})$",
      "description": "Content-addressed ID of this registry artifact."
    },

    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "UTC timestamp when this registry was produced."
    },

    "canonicalization_profile": {
      "type": "string",
      "const": "kristal.v5:jcs-rfc8785",
      "description": "Canonicalization profile identifier used for stable hashing."
    },

    "canonicalization_version": {
      "type": "string",
      "const": "1",
      "description": "Canonicalization profile version."
    },

    "content_hash": {
      "$ref": "#/$defs/hash",
      "description": "Hash of the canonicalized registry content with signatures excluded."
    },

    "registry_scope": {
      "$ref": "#/$defs/scope",
      "description": "Optional declared scope for this registry. If omitted, rules define scope boundaries."
    },

    "authority_channels": {
      "type": "array",
      "minItems": 1,
      "description": "Authority channels declared by this registry. Authority is scoped and plural; recognition by one channel does not imply recognition by another.",
      "items": { "$ref": "#/$defs/authority_channel" }
    },

    "trust_roots": {
      "type": "object",
      "additionalProperties": false,
      "required": ["active_roots", "deprecated_roots", "blocked_roots"],
      "properties": {
        "active_roots": {
          "type": "array",
          "minItems": 1,
          "description": "Pinned trust roots accepted for verification under registry rules.",
          "items": { "$ref": "#/$defs/trust_root" }
        },
        "deprecated_roots": {
          "type": "array",
          "description": "Pinned trust roots accepted only if the applicable policy allows a grace period.",
          "items": { "$ref": "#/$defs/trust_root" }
        },
        "blocked_roots": {
          "type": "array",
          "description": "Pinned trust roots explicitly rejected.",
          "items": { "$ref": "#/$defs/trust_root" }
        }
      }
    },

    "validation_policies": {
      "type": "array",
      "description": "Validation policies declared or referenced by this registry.",
      "items": { "$ref": "#/$defs/validation_policy" }
    },

    "recognition_policies": {
      "type": "array",
      "description": "Recognition policies used to decide whether an artifact, shard, assertion, runtime pack, dataset, or authority channel is recognized within a scope.",
      "items": { "$ref": "#/$defs/recognition_policy" }
    },

    "revocation_list": {
      "type": "object",
      "additionalProperties": false,
      "description": "Optional offline-friendly revocation list reference, content-addressed and signed.",
      "properties": {
        "artifact_path": {
          "type": "string",
          "minLength": 1,
          "description": "Relative or absolute path/URI to the revocation list artifact, for example 'revocations.json'."
        },
        "content_hash": { "$ref": "#/$defs/hash" },
        "signatures": {
          "type": "array",
          "items": { "$ref": "#/$defs/signature" }
        }
      }
    },

    "rules": {
      "type": "array",
      "minItems": 1,
      "description": "Scope-based acceptance, validation, and recognition rules for authority channels, shards, federations, runtime packs, and assertions.",
      "items": { "$ref": "#/$defs/rule" }
    },

    "signatures": {
      "type": "array",
      "minItems": 1,
      "description": "Signatures over the registry signing target. Signatures are excluded from the registry content hash.",
      "items": { "$ref": "#/$defs/signature" }
    },

    "extensions": {
      "type": "object",
      "description": "Implementation-specific fields. Extensions must not change core identity, hashing, authority, validation, or recognition semantics.",
      "additionalProperties": true
    }
  },

  "$defs": {
    "hash": {
      "type": "object",
      "additionalProperties": false,
      "required": ["alg", "value"],
      "properties": {
        "alg": {
          "type": "string",
          "enum": ["sha256"]
        },
        "value": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        }
      }
    },

    "signature": {
      "type": "object",
      "additionalProperties": false,
      "required": ["key_id", "alg", "payload_hash", "signature"],
      "properties": {
        "sig_id": {
          "type": "string",
          "minLength": 1
        },
        "key_id": {
          "type": "string",
          "minLength": 1
        },
        "alg": {
          "type": "string",
          "enum": ["ed25519", "rsa-pss-sha256"]
        },
        "payload_hash": {
          "$ref": "#/$defs/hash"
        },
        "signature": {
          "type": "string",
          "minLength": 16,
          "description": "Signature bytes encoded as base64, base64url, or multibase according to the applicable signing profile."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },

    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": ["domain"],
      "properties": {
        "domain": {
          "type": "string",
          "enum": [
            "general",
            "wikidata",
            "science",
            "health",
            "education",
            "heritage",
            "law",
            "policy",
            "technology",
            "environment",
            "culture",
            "mythology",
            "fiction",
            "research",
            "operations",
            "civic",
            "local_notes"
          ]
        },
        "subdomain": {
          "type": "string",
          "minLength": 1
        },
        "jurisdiction": {
          "type": "string",
          "minLength": 1
        },
        "time_window": {
          "type": "string",
          "minLength": 1
        },
        "tenant_id": {
          "type": "string",
          "minLength": 1
        },
        "environment": {
          "type": "string",
          "minLength": 1
        },
        "language": {
          "type": "string",
          "minLength": 1
        }
      }
    },

    "authority_channel": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "authority_channel_id",
        "name",
        "authority_type",
        "scope",
        "trust_roots",
        "validation_policies"
      ],
      "properties": {
        "authority_channel_id": {
          "type": "string",
          "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$",
          "description": "Stable identifier for this authority channel."
        },
        "name": {
          "type": "string",
          "minLength": 1
        },
        "authority_type": {
          "$ref": "#/$defs/authority_type"
        },
        "description": {
          "type": "string"
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "recognized_by": {
          "type": "array",
          "description": "Authority channels that recognize this authority channel, if any. Recognition is scoped and does not imply universal authority.",
          "items": {
            "type": "string",
            "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
          }
        },
        "recognizes": {
          "type": "array",
          "description": "Authority channels recognized by this authority channel, if any.",
          "items": {
            "type": "string",
            "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
          }
        },
        "trust_roots": {
          "type": "array",
          "minItems": 1,
          "description": "root_id values authorized to sign for this authority channel.",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "validation_policies": {
          "type": "array",
          "minItems": 1,
          "description": "Validation policy IDs applicable to this authority channel.",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "recognition_policies": {
          "type": "array",
          "description": "Recognition policy IDs applicable to this authority channel.",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "revocation_policy_ref": {
          "type": ["string", "null"],
          "minLength": 1
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },

    "authority_type": {
      "type": "string",
      "enum": [
        "individual",
        "community",
        "association",
        "research_collective",
        "academic_institution",
        "standards_body",
        "company",
        "government",
        "intergovernmental_organization",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=89c9703edda5:351-700
start=351
end=700
----
        "ai_validator",
        "hybrid_collective"
      ]
    },

    "trust_root": {
      "type": "object",
      "additionalProperties": false,
      "required": ["root_id", "category"],
      "properties": {
        "root_id": {
          "type": "string",
          "minLength": 1
        },
        "category": {
          "type": "string",
          "enum": [
            "personal",
            "community",
            "association",
            "research_collective",
            "academic_institution",
            "standards_body",
            "company",
            "government",
            "intergovernmental_organization",
            "ai_validator",
            "hybrid_collective",
            "recognized"
          ]
        },
        "label": {
          "type": "string"
        },
        "authority_channel_ids": {
          "type": "array",
          "description": "Authority channels this trust root may sign for.",
          "items": {
            "type": "string",
            "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
          }
        },
        "key_id": {
          "type": "string",
          "minLength": 1,
          "description": "Optional identifier for the root key."
        },
        "did": {
          "type": "string",
          "minLength": 1
        },
        "public_key_jwk": {
          "type": "object",
          "description": "Optional JWK for offline verification.",
          "additionalProperties": true
        },
        "x5c": {
          "type": "array",
          "description": "Optional X.509 certificate chain, base64 DER.",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "not_before": {
          "type": "string",
          "format": "date-time"
        },
        "not_after": {
          "type": "string",
          "format": "date-time"
        }
      },
      "anyOf": [
        { "required": ["public_key_jwk"] },
        { "required": ["did"] },
        { "required": ["x5c"] },
        { "required": ["key_id"] }
      ]
    },

    "validation_policy": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "policy_id",
        "policy_version",
        "scope",
        "allowed_validation_statuses",
        "allowed_validated_as"
      ],
      "properties": {
        "policy_id": {
          "type": "string",
          "minLength": 1
        },
        "policy_version": {
          "type": "string",
          "minLength": 1
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "allowed_validation_statuses": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/validation_status" }
        },
        "allowed_validated_as": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/validated_as" }
        },
        "allowed_certainty_levels": {
          "type": "array",
          "items": { "$ref": "#/$defs/certainty_level" }
        },
        "required_evidence": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "required_profiles": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "min_signatures": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        }
      }
    },

    "recognition_policy": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "policy_id",
        "policy_version",
        "scope",
        "target_levels",
        "allowed_recognition_statuses"
      ],
      "properties": {
        "policy_id": {
          "type": "string",
          "minLength": 1
        },
        "policy_version": {
          "type": "string",
          "minLength": 1
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "target_levels": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/target_level" }
        },
        "allowed_recognition_statuses": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/$defs/recognition_status" }
        },
        "allowed_validated_as": {
          "type": "array",
          "items": { "$ref": "#/$defs/validated_as" }
        },
        "allowed_certainty_levels": {
          "type": "array",
          "items": { "$ref": "#/$defs/certainty_level" }
        },
        "required_authority_channels": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
          }
        },
        "allow_delegated_authority": {
          "type": "boolean",
          "default": true
        }
      }
    },

    "rule": {
      "type": "object",
      "additionalProperties": false,
      "required": ["rule_id", "scope"],
      "properties": {
        "rule_id": {
          "type": "string",
          "minLength": 1
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },

        "target_levels": {
          "type": "array",
          "description": "Artifact levels to which this rule applies. If omitted, the rule applies to all target levels in its scope.",
          "items": { "$ref": "#/$defs/target_level" }
        },

        "allowed_authority_channel_ids": {
          "type": "array",
          "description": "Optional allow-list of authority_channel_id values accepted under this rule.",
          "items": {
            "type": "string",
            "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
          }
        },

        "allowed_authority_types": {
          "type": "array",
          "description": "Optional allow-list of authority types accepted under this rule.",
          "items": { "$ref": "#/$defs/authority_type" }
        },

        "allowed_root_categories": {
          "type": "array",
          "description": "Optional allow-list of trust root categories accepted under this rule.",
          "items": {
            "type": "string",
            "enum": [
              "personal",
              "community",
              "association",
              "research_collective",
              "academic_institution",
              "standards_body",
              "company",
              "government",
              "intergovernmental_organization",
              "ai_validator",
              "hybrid_collective",
              "recognized"
            ]
          }
        },

        "allowed_root_ids": {
          "type": "array",
          "description": "Optional allow-list of specific root_id values. If omitted, trust roots are selected by authority channel, root category, validation policy, recognition policy, and deployment policy.",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },

        "required_validation_policies": {
          "type": "array",
          "description": "Validation policy IDs required for artifacts or assertions in this scope.",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },

        "required_recognition_policies": {
          "type": "array",
          "description": "Recognition policy IDs required for artifacts, shards, datasets, authority channels, runtime packs, or assertions in this scope.",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },

        "allowed_validation_statuses": {
          "type": "array",
          "items": { "$ref": "#/$defs/validation_status" }
        },

        "allowed_recognition_statuses": {
          "type": "array",
          "items": { "$ref": "#/$defs/recognition_status" }
        },

        "allowed_validated_as": {
          "type": "array",
          "items": { "$ref": "#/$defs/validated_as" }
        },

        "allowed_certainty_levels": {
          "type": "array",
          "items": { "$ref": "#/$defs/certainty_level" }
        },

        "min_signatures": {
          "type": "integer",
          "minimum": 1,
          "default": 1,
          "description": "Minimum number of valid signatures required for acceptance under this rule."
        },

        "revocation_policy": {
          "type": "string",
          "enum": ["ignore", "require_if_present", "require_strict"],
          "default": "require_if_present",
          "description": "How revocation list presence affects acceptance."
        },

        "delegation_policy": {
          "type": "string",
          "enum": ["none", "explicit_only", "allow_recognized_authorities"],
          "default": "explicit_only",
          "description": "Whether authority channels may rely on recognition or delegation from other authority channels."
        },

        "disagreement_policy": {
          "type": "string",
          "enum": ["preserve_disagreement", "authority_precedence", "mark_disputed", "exclude_conflict", "require_reader_choice"],
          "default": "preserve_disagreement",
          "description": "How conflicting claims or recognitions are handled in this scope."
        }
      }
    },

    "target_level": {
      "type": "string",
      "enum": [
        "artifact",
        "shard",
        "assertion",
        "authority_channel",
        "dataset",
        "runtime_pack"
      ]
    },

    "validation_status": {
      "type": "string",
      "enum": [
        "not_evaluated",
        "in_review",
        "validated",
        "conditionally_validated",
        "disputed",
        "rejected",
        "revoked"
      ]
    },
--- CHUNK END ---

--- CHUNK BEGIN ---
id=89c9703edda5:701-748
start=701
end=748
----

    "recognition_status": {
      "type": "string",
      "enum": [
        "recognized",
        "conditionally_recognized",
        "under_review",
        "disputed",
        "rejected",
        "deprecated",
        "revoked"
      ]
    },

    "certainty_level": {
      "type": "string",
      "enum": [
        "unknown",
        "speculative",
        "low",
        "medium",
        "high",
        "established",
        "not_applicable"
      ]
    },

    "validated_as": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claim",
        "sourced_claim",
        "reviewed_claim",
        "high_confidence_fact",
        "institutional_reference",
        "publisher_declaration",
        "technical_specification",
        "legal_or_policy_position",
        "mythological_corpus",
        "fictional_corpus",
        "symbolic_model",
        "disputed_position",
        "rejected_claim"
      ]
    }
  }
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/claim-ir.schema.json"
id=b04719b54c98
kind=source
size=26034
lines=1119
line_ref=1-1119
chunks=4
chunk_refs=1-350,351-700,701-1050,1051-1119
summary="Source file."

--- CHUNK BEGIN ---
id=b04719b54c98:1-350
start=1
end=350
----
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/claim-ir.schema.json",
  "title": "Claim-IR v5",
  "description": "Claim-IR v5 is an extractor proposal profile. It represents extracted or proposed claims that may be converted into a Structured Epistemic State. It is not the universal normative input format for Kristal v5 and it does not imply validation or authority recognition.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "artifact_type",
    "subject",
    "claims"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "5.0"
    },
    "artifact_type": {
      "type": "string",
      "const": "claim_ir"
    },
    "profile_role": {
      "type": "string",
      "const": "extractor_proposal_profile",
      "description": "Declares that this artifact is a proposal/extraction profile, not a validated reference artifact."
    },
    "canonicalization_profile": {
      "type": "string",
      "const": "kristal.v5:jcs-rfc8785"
    },
    "document": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "doc_id": {
          "type": "string",
          "minLength": 1
        },
        "title": {
          "type": "string"
        },
        "lang": {
          "$ref": "#/$defs/lang"
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        },
        "source_id": {
          "type": "string",
          "minLength": 1
        },
        "retrieved_at": {
          "type": "string",
          "format": "date-time"
        },
        "published_at": {
          "type": "string",
          "format": "date-time"
        },
        "content_hash": {
          "$ref": "#/$defs/content_hash"
        },
        "license": {
          "type": "string"
        },
        "publisher": {
          "type": "string"
        }
      },
      "anyOf": [
        {
          "required": [
            "source_url"
          ]
        },
        {
          "required": [
            "source_id"
          ]
        },
        {
          "required": [
            "doc_id"
          ]
        }
      ]
    },
    "extraction": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "run_id": {
          "type": "string",
          "minLength": 1
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "producer": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "llm",
                "rules",
                "hybrid",
                "human",
                "parser",
                "ocr",
                "scraper"
              ]
            },
            "name": {
              "type": "string"
            },
            "version": {
              "type": "string"
            }
          }
        },
        "model": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "provider": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "version": {
              "type": "string"
            }
          }
        },
        "prompt_ref": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "prompt_id": {
              "type": "string",
              "minLength": 1
            },
            "version": {
              "type": "string"
            },
            "content_hash": {
              "$ref": "#/$defs/content_hash"
            }
          }
        },
        "method": {
          "type": "string"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "scope": {
      "$ref": "#/$defs/scope"
    },
    "subject": {
      "$ref": "#/$defs/entity_ref"
    },
    "claims": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/claim"
      }
    },
    "provenance_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ref"
      }
    },
    "target_state": {
      "type": "object",
      "additionalProperties": false,
      "description": "Optional hints for conversion into a Structured Epistemic State.",
      "properties": {
        "artifact_type": {
          "type": "string",
          "const": "structured_epistemic_state"
        },
        "state_id_hint": {
          "type": "string",
          "pattern": "^sha256:[0-9a-fA-F]{64}$"
        },
        "conversion_policy_ref": {
          "$ref": "#/$defs/ref"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/warning"
      }
    },
    "errors": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/error"
      }
    },
    "extensions": {
      "type": "object",
      "additionalProperties": true
    }
  },
  "$defs": {
    "qid": {
      "type": "string",
      "pattern": "^Q[1-9][0-9]*$"
    },
    "pid": {
      "type": "string",
      "pattern": "^P[1-9][0-9]*$"
    },
    "lang": {
      "type": "string",
      "pattern": "^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$"
    },
    "content_hash": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "alg",
        "value"
      ],
      "properties": {
        "alg": {
          "type": "string",
          "enum": [
            "sha256"
          ]
        },
        "value": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{64}$"
        }
      }
    },
    "ref": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "ref"
      ],
      "properties": {
        "ref": {
          "type": "string",
          "minLength": 1
        },
        "kind": {
          "type": "string",
          "enum": [
            "document",
            "source",
            "evidence",
            "policy",
            "authority_channel",
            "validation_decision",
            "authority_recognition",
            "artifact",
            "shard",
            "runtime_pack",
            "other"
          ]
        },
        "content_hash": {
          "$ref": "#/$defs/content_hash"
        }
      }
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "domain"
      ],
      "properties": {
        "domain": {
          "type": "string",
          "enum": [
            "general",
            "wikidata",
            "science",
            "health",
            "education",
            "heritage",
            "law",
            "policy",
            "technology",
            "environment",
            "culture",
            "mythology",
            "fiction",
            "research",
            "operations",
            "civic",
            "local_notes"
          ]
        },
        "subdomain": {
          "type": [
            "string",
            "null"
          ]
        },
        "jurisdiction": {
          "type": [
            "string",
            "null"
          ]
        },
        "time_window": {
          "type": [
            "string",
            "null"
          ]
        },
        "tenant_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "environment": {
          "type": [
            "string",
            "null"
          ]
        },
        "language": {
          "anyOf": [
            {
--- CHUNK END ---

--- CHUNK BEGIN ---
id=b04719b54c98:351-700
start=351
end=700
----
              "$ref": "#/$defs/lang"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "assertion_status": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claimed",
        "sourced",
        "disputed",
        "reviewed",
        "validated",
        "rejected",
        "retracted",
        "superseded"
      ]
    },
    "certainty_level": {
      "type": "string",
      "enum": [
        "unknown",
        "speculative",
        "low",
        "medium",
        "high",
        "established",
        "not_applicable"
      ]
    },
    "validated_as": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claim",
        "sourced_claim",
        "reviewed_claim",
        "high_confidence_fact",
        "institutional_reference",
        "publisher_declaration",
        "technical_specification",
        "legal_or_policy_position",
        "mythological_corpus",
        "fictional_corpus",
        "symbolic_model",
        "disputed_position",
        "rejected_claim"
      ]
    },
    "entity_candidate": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "score"
      ],
      "properties": {
        "id": {
          "$ref": "#/$defs/qid"
        },
        "score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "label": {
          "type": "string"
        },
        "source": {
          "type": "string"
        }
      }
    },
    "property_candidate": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "score"
      ],
      "properties": {
        "id": {
          "$ref": "#/$defs/pid"
        },
        "score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "label": {
          "type": "string"
        },
        "source": {
          "type": "string"
        }
      }
    },
    "entity_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "qid": {
          "$ref": "#/$defs/qid"
        },
        "surface": {
          "type": "string",
          "minLength": 1
        },
        "lang": {
          "$ref": "#/$defs/lang"
        },
        "candidates": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/entity_candidate"
          }
        },
        "external_id": {
          "type": "string"
        },
        "source_ref": {
          "$ref": "#/$defs/ref"
        }
      },
      "anyOf": [
        {
          "required": [
            "qid"
          ]
        },
        {
          "required": [
            "surface"
          ]
        },
        {
          "required": [
            "external_id"
          ]
        }
      ]
    },
    "predicate_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "pid": {
          "$ref": "#/$defs/pid"
        },
        "surface": {
          "type": "string",
          "minLength": 1
        },
        "lang": {
          "$ref": "#/$defs/lang"
        },
        "candidates": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/property_candidate"
          }
        },
        "external_id": {
          "type": "string"
        },
        "source_ref": {
          "$ref": "#/$defs/ref"
        }
      },
      "anyOf": [
        {
          "required": [
            "pid"
          ]
        },
        {
          "required": [
            "surface"
          ]
        },
        {
          "required": [
            "external_id"
          ]
        }
      ]
    },
    "object_value": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "kind",
        "value"
      ],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "item",
            "string",
            "quantity",
            "time",
            "monolingual_text",
            "coord",
            "url",
            "boolean",
            "external_id",
            "none"
          ]
        },
        "value": {}
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "kind": {
                "const": "item"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "$ref": "#/$defs/entity_ref"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "string"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "string"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "url"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "boolean"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "boolean"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "external_id"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "none"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "null"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "quantity"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "amount"
                ],
                "properties": {
                  "amount": {
                    "type": "number"
                  },
                  "unit_qid": {
                    "$ref": "#/$defs/qid"
                  },
                  "unit_label": {
                    "type": "string"
                  },
                  "lower_bound": {
                    "type": "number"
                  },
                  "upper_bound": {
                    "type": "number"
                  }
                }
              }
--- CHUNK END ---

--- CHUNK BEGIN ---
id=b04719b54c98:701-1050
start=701
end=1050
----
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "time"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "iso8601"
                ],
                "properties": {
                  "iso8601": {
                    "type": "string",
                    "pattern": "^-?\\d{4}-\\d{2}-\\d{2}"
                  },
                  "precision": {
                    "type": "string",
                    "enum": [
                      "year",
                      "month",
                      "day",
                      "hour",
                      "minute",
                      "second"
                    ]
                  },
                  "calendar": {
                    "type": "string"
                  },
                  "timezone": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "monolingual_text"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "text",
                  "lang"
                ],
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "lang": {
                    "$ref": "#/$defs/lang"
                  }
                }
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "coord"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "lat",
                  "lon"
                ],
                "properties": {
                  "lat": {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90
                  },
                  "lon": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180
                  },
                  "precision": {
                    "type": "number",
                    "minimum": 0
                  },
                  "globe": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      ]
    },
    "evidence": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "source"
      ],
      "properties": {
        "source": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "source_id": {
              "type": "string",
              "minLength": 1
            },
            "source_url": {
              "type": "string",
              "format": "uri"
            },
            "title": {
              "type": "string"
            },
            "retrieved_at": {
              "type": "string",
              "format": "date-time"
            },
            "content_hash": {
              "$ref": "#/$defs/content_hash"
            }
          },
          "anyOf": [
            {
              "required": [
                "source_url"
              ]
            },
            {
              "required": [
                "source_id"
              ]
            }
          ]
        },
        "evidence_type": {
          "type": "string",
          "enum": [
            "quote",
            "citation",
            "dataset_row",
            "observation",
            "measurement",
            "document_reference",
            "other"
          ]
        },
        "quote": {
          "type": "string"
        },
        "page": {
          "type": "integer",
          "minimum": 1
        },
        "offsets": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "start_char": {
              "type": "integer",
              "minimum": 0
            },
            "end_char": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "selector": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "css",
                "xpath",
                "json_pointer",
                "pdf_region",
                "text_quote",
                "row_id"
              ]
            },
            "value": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "strength": {
          "type": "string",
          "enum": [
            "unknown",
            "weak",
            "medium",
            "strong"
          ]
        }
      }
    },
    "uncertainty": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "certainty_level": {
          "$ref": "#/$defs/certainty_level"
        },
        "confidence_interval": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "low",
            "high"
          ],
          "properties": {
            "low": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "high": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          }
        },
        "method": {
          "type": "string"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "claim": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "predicate",
        "object"
      ],
      "properties": {
        "claim_id": {
          "type": "string",
          "minLength": 1
        },
        "predicate": {
          "$ref": "#/$defs/predicate_ref"
        },
        "object": {
          "$ref": "#/$defs/object_value"
        },
        "proposed_assertion_status": {
          "$ref": "#/$defs/assertion_status"
        },
        "proposed_certainty_level": {
          "$ref": "#/$defs/certainty_level"
        },
        "proposed_validated_as": {
          "$ref": "#/$defs/validated_as"
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "qualifiers": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "predicate",
              "object"
            ],
            "properties": {
              "predicate": {
                "$ref": "#/$defs/predicate_ref"
              },
              "object": {
                "$ref": "#/$defs/object_value"
              }
            }
          }
        },
        "evidence": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/evidence"
          }
        },
        "evidence_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ref"
          }
        },
        "authority_channel_refs": {
          "type": "array",
          "description": "Authority channels mentioned by the extraction. Presence here does not imply recognition.",
          "items": {
            "$ref": "#/$defs/ref"
          }
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "uncertainty": {
          "$ref": "#/$defs/uncertainty"
        },
        "alternatives": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/claim"
          }
        },
        "notes": {
          "type": "string"
        },
--- CHUNK END ---

--- CHUNK BEGIN ---
id=b04719b54c98:1051-1119
start=1051
end=1119
----
        "extensions": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "warning": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "NO_CLAIMS_EXTRACTED",
            "LOW_CONFIDENCE_EXTRACTION",
            "AMBIGUOUS_SUBJECT",
            "AMBIGUOUS_PREDICATE",
            "UNRESOLVED_QID",
            "UNRESOLVED_PID",
            "EVIDENCE_MISSING",
            "EVIDENCE_WEAK",
            "VALUE_NORMALIZATION_NEEDED",
            "SCOPE_MISSING",
            "AUTHORITY_NOT_ESTABLISHED",
            "CERTAINTY_NOT_ASSIGNED"
          ]
        },
        "message": {
          "type": "string"
        },
        "path": {
          "type": "string"
        }
      }
    },
    "error": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "SCHEMA_INVALID",
            "REQUIRED_FIELD_MISSING",
            "UNSUPPORTED_KIND",
            "INVALID_VALUE_SHAPE",
            "INVALID_SCOPE",
            "INVALID_STATUS",
            "INVALID_CERTAINTY_LEVEL"
          ]
        },
        "message": {
          "type": "string"
        },
        "path": {
          "type": "string"
        }
      }
    }
  }
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/exchange-federation-manifest.schema.json"
id=70c8f4ea4c12
kind=source
size=14823
lines=756
line_ref=1-756
chunks=3
chunk_refs=1-350,351-700,701-756
summary="Source file."

--- CHUNK BEGIN ---
id=70c8f4ea4c12:1-350
start=1
end=350
----
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://kristal.org/schemas/v5/exchange-federation-manifest.schema.json",
"title": "Kristal v5 Exchange Federation Manifest",
"type": "object",
"additionalProperties": false,
"required": [
"schema_version",
"artifact_type",
"created_at",
"federation_id",
"canonicalization_profile",
"canonicalization_version",
"content_hash",
"authority_registry_ref",
"shards",
"composition_policy",
"reader_policy_refs",
"authority_recognition_refs",
"validation_policy_refs",
"publisher",
"signatures"
],
"properties": {
"schema_version": {
"type": "string",
"const": "5.0",
"description": "Manifest schema version."
},
"artifact_type": {
"type": "string",
"const": "exchange_federation_manifest",
"description": "Artifact discriminator."
},
"manifest_id": {
"type": "string",
"minLength": 1,
"description": "Optional non-content-addressed operational identifier for this manifest."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "UTC timestamp when the manifest was produced. It is not part of the federation hash target."
},
"federation_id": {
"$ref": "#/$defs/federation_id",
"description": "Content-addressed ID of this federation manifest."
},
"canonicalization_profile": {
"type": "string",
"const": "kristal.v5:jcs-rfc8785",
"description": "Canonicalization profile identifier used to derive content_hash and federation_id."
},
"canonicalization_version": {
"type": "string",
"const": "1",
"description": "Canonicalization profile version."
},
"content_hash": {
"$ref": "#/$defs/hash",
"description": "Hash of the canonicalized federation hash target. federation_id, content_hash, signatures, manifest_id, and created_at are excluded."
},
"authority_registry_ref": {
"$ref": "#/$defs/authority_registry_ref",
"description": "Pinned authority registry used to interpret authority channels, recognition, validation policy, and reader policy."
},
"shards": {
"type": "array",
"minItems": 1,
"description": "Referenced shards. Federation preserves shard identity and does not rewrite shard contents.",
"items": {
"$ref": "#/$defs/shard_ref"
}
},
"composition_policy": {
"$ref": "#/$defs/composition_policy",
"description": "Deterministic composition rules for overlap, ordering, conflict visibility, and reader-policy selection."
},
"reader_policy_refs": {
"type": "array",
"description": "Reader policies available for this federation, such as reference_only, validated_only, research, creative, all_with_labels, or custom.",
"items": {
"$ref": "#/$defs/reader_policy_ref"
}
},
"authority_recognition_refs": {
"type": "array",
"description": "Recognition records that state which authority channels recognize this federation, its shards, or selected assertions.",
"items": {
"$ref": "#/$defs/authority_recognition_ref"
}
},
"validation_policy_refs": {
"type": "array",
"description": "Validation policies used or referenced by this federation.",
"items": {
"$ref": "#/$defs/validation_policy_ref"
}
},
"trust_requirements": {
"$ref": "#/$defs/trust_requirements",
"description": "Optional machine-readable requirements for consuming this federation under selected channels or scopes."
},
"publisher": {
"$ref": "#/$defs/publisher",
"description": "Publisher identity metadata for the federation manifest."
},
"signatures": {
"type": "array",
"minItems": 1,
"description": "Publisher or authority signatures over the federation manifest signing target.",
"items": {
"$ref": "#/$defs/signature"
}
},
"references": {
"type": "object",
"description": "Optional references to specs or docs for traceability.",
"additionalProperties": false,
"properties": {
"spec_version": {
"type": "string",
"const": "5.0"
},
"docs_uri": {
"type": "string",
"format": "uri"
}
}
},
"extensions": {
"type": "object",
"description": "Implementation-specific fields. Extensions must not change core identity, hashing, validation, recognition, or federation semantics.",
"additionalProperties": true
}
},
"$defs": {
"sha256_hex": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"sha256_prefixed": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"federation_id": {
"$ref": "#/$defs/sha256_prefixed"
},
"hash": {
"type": "object",
"additionalProperties": false,
"required": [
"alg",
"value"
],
"properties": {
"alg": {
"type": "string",
"enum": [
"sha256"
],
"description": "Hash algorithm identifier."
},
"value": {
"$ref": "#/$defs/sha256_hex",
"description": "Lowercase hex-encoded hash digest."
}
}
},
"signature": {
"type": "object",
"additionalProperties": false,
"required": [
"key_id",
"alg",
"payload_hash",
"signature"
],
"properties": {
"sig_id": {
"type": "string",
"minLength": 1,
"description": "Optional unique signature identifier."
},
"key_id": {
"type": "string",
"minLength": 1,
"description": "Key identifier used to verify this signature."
},
"alg": {
"type": "string",
"enum": [
"ed25519",
"rsa-pss-sha256",
"ecdsa-p256-sha256"
],
"description": "Signature algorithm identifier."
},
"payload_hash": {
"$ref": "#/$defs/hash",
"description": "Hash of the signing target bytes as defined by the signing target rules."
},
"signature": {
"type": "string",
"minLength": 1,
"description": "Signature value. Encoding is defined by the signature profile; base64url is recommended."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"purpose": {
"type": "string",
"enum": [
"publisher",
"authority",
"auditor",
"distributor",
"transparency_log"
]
},
"signer": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"org": {
"type": "string",
"minLength": 1
},
"authority_channel_id": {
"$ref": "#/$defs/authority_channel_id"
}
}
},
"certificate_uri": {
"type": "string",
"format": "uri",
"description": "Optional pointer to a certificate chain or public key material."
}
}
},
"authority_channel_id": {
"type": "string",
"pattern": "^authority:[a-z0-9][a-z0-9.*:-]*$"
},
"authority_registry_id": {
"type": "string",
"anyOf": [
{
"pattern": "^kristal:authority-registry:sha256:[a-f0-9]{64}$"
},
{
"pattern": "^sha256:[a-f0-9]{64}$"
},
{
"pattern": "^authority-registry:[a-z0-9][a-z0-9.*:-]*$"
}
]
},
"authority_registry_ref": {
"type": "object",
"additionalProperties": false,
"required": [
"registry_id",
"ref",
"content_hash"
],
"properties": {
"registry_id": {
"$ref": "#/$defs/authority_registry_id",
"description": "Identifier of the referenced authority registry."
},
"ref": {
"type": "string",
"minLength": 1,
"description": "Relative path or URI to the registry artifact within the distribution."
},
"content_hash": {
"$ref": "#/$defs/hash"
},
"signatures": {
"type": "array",
"description": "Optional signatures for the referenced registry artifact.",
"items": {
"$ref": "#/$defs/signature"
}
}
}
},
"scope": {
"type": "object",
"additionalProperties": false,
"required": [
"domain"
],
"properties": {
"domain": {
"type": "string",
"enum": [
"general",
"wikidata",
"science",
"health",
"education",
"heritage",
"law",
"policy",
"technology",
"environment",
"culture",
"mythology",
"fiction",
"research",
"operations",
"civic",
"local_notes"
]
},
"subdomain": {
"type": [
"string",
"null"
],
"minLength": 1
},
"jurisdiction": {
"type": [
"string",
"null"
],
"minLength": 1
},
"time_window": {
"type": [
"string",
"null"
],
"minLength": 1,
"description": "Implementation-defined time slice label, such as 2026-01."
--- CHUNK END ---

--- CHUNK BEGIN ---
id=70c8f4ea4c12:351-700
start=351
end=700
----
},
"tenant_id": {
"type": [
"string",
"null"
],
"minLength": 1
},
"environment": {
"type": [
"string",
"null"
],
"minLength": 1
},
"language": {
"type": [
"string",
"null"
],
"minLength": 2
}
}
},
"artifact_ref": {
"type": "object",
"additionalProperties": false,
"required": [
"artifact_type",
"id",
"ref",
"content_hash"
],
"properties": {
"artifact_type": {
"type": "string",
"minLength": 1
},
"id": {
"type": "string",
"minLength": 1
},
"ref": {
"type": "string",
"minLength": 1,
"description": "Relative path or URI to the referenced artifact."
},
"content_hash": {
"$ref": "#/$defs/hash"
}
}
},
"reader_policy_ref": {
"allOf": [
{
"$ref": "#/$defs/artifact_ref"
},
{
"type": "object",
"properties": {
"artifact_type": {
"const": "reader_policy"
}
}
}
]
},
"authority_recognition_ref": {
"allOf": [
{
"$ref": "#/$defs/artifact_ref"
},
{
"type": "object",
"properties": {
"artifact_type": {
"const": "authority_recognition"
}
}
}
]
},
"validation_policy_ref": {
"allOf": [
{
"$ref": "#/$defs/artifact_ref"
},
{
"type": "object",
"properties": {
"artifact_type": {
"const": "validation_policy"
}
}
}
]
},
"validation_ref": {
"allOf": [
{
"$ref": "#/$defs/artifact_ref"
},
{
"type": "object",
"properties": {
"artifact_type": {
"enum": [
"validation_report",
"validation_decision"
]
}
}
}
]
},
"shard_ref": {
"type": "object",
"additionalProperties": false,
"required": [
"shard_id",
"scope",
"artifact_status",
"shard_manifest_ref",
"shard_manifest_hash"
],
"properties": {
"shard_id": {
"$ref": "#/$defs/sha256_prefixed",
"description": "Content-addressed ID of the shard Exchange."
},
"scope": {
"$ref": "#/$defs/scope"
},
"artifact_status": {
"type": "string",
"enum": [
"draft",
"working",
"under_review",
"recognized",
"reference",
"deprecated",
"superseded",
"revoked"
],
"description": "Status of the shard artifact within its declared authority channel and scope."
},
"shard_manifest_ref": {
"type": "string",
"minLength": 1,
"description": "Relative path or URI to the shard manifest artifact."
},
"shard_manifest_hash": {
"$ref": "#/$defs/hash",
"description": "Hash of the referenced shard manifest."
},
"authority_channel_refs": {
"type": "array",
"description": "Authority channels relevant to this shard.",
"items": {
"$ref": "#/$defs/authority_channel_id"
}
},
"authority_recognition_refs": {
"type": "array",
"description": "Recognition records scoped to this shard.",
"items": {
"$ref": "#/$defs/authority_recognition_ref"
}
},
"validation_refs": {
"type": "array",
"description": "Validation reports or decisions scoped to this shard.",
"items": {
"$ref": "#/$defs/validation_ref"
}
},
"seals": {
"type": "array",
"description": "Optional signatures copied from the shard manifest for self-contained verification.",
"items": {
"$ref": "#/$defs/signature"
}
},
"extensions": {
"type": "object",
"additionalProperties": true
}
}
},
"composition_policy": {
"type": "object",
"additionalProperties": false,
"required": [
"policy_id",
"policy_version",
"overlap_strategy",
"conflict_strategy",
"default_visibility",
"ordering"
],
"properties": {
"policy_id": {
"type": "string",
"minLength": 1,
"description": "Deterministic composition policy identifier."
},
"policy_version": {
"type": "string",
"minLength": 1,
"description": "Policy version identifier."
},
"overlap_strategy": {
"type": "string",
"enum": [
"authority_precedence",
"latest_time_window",
"explicit_allow_deny",
"preserve_all",
"reader_policy_selected"
],
"description": "How overlapping shards are selected or retained."
},
"conflict_strategy": {
"type": "string",
"enum": [
"preserve_disagreement",
"authority_precedence",
"mark_disputed",
"exclude_conflict",
"require_reader_choice"
],
"description": "How conflicting claims remain visible or are selected."
},
"default_visibility": {
"type": "string",
"enum": [
"reader_policy",
"reference_only",
"validated_only",
"all_with_labels",
"custom"
],
"description": "Default visibility mode before a reader policy is explicitly chosen."
},
"ordering": {
"type": "string",
"enum": [
"stable",
"authority_then_scope_then_hash",
"scope_then_time_then_hash",
"manifest_order"
],
"description": "Deterministic ordering rule for composed shards."
},
"authority_precedence": {
"type": "array",
"description": "Optional ordered authority channel IDs used when overlap_strategy or conflict_strategy is authority_precedence.",
"items": {
"$ref": "#/$defs/authority_channel_id"
}
},
"parameters": {
"type": "object",
"description": "Additional deterministic policy parameters for a given federation_id.",
"additionalProperties": true
}
}
},
"trust_requirements": {
"type": "array",
"description": "Optional consuming requirements by scope. These requirements constrain display or activation under selected reader and authority policies.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"scope"
],
"properties": {
"scope": {
"type": "object",
"additionalProperties": false,
"properties": {
"domain": {
"type": "string",
"minLength": 1
},
"subdomain": {
"type": "string",
"minLength": 1
},
"shard_id": {
"$ref": "#/$defs/sha256_prefixed"
}
},
"anyOf": [
{
"required": [
"domain"
]
},
{
"required": [
"shard_id"
]
}
]
},
"required_authority_channels": {
"type": "array",
"items": {
"$ref": "#/$defs/authority_channel_id"
}
},
"allowed_validation_statuses": {
"type": "array",
"items": {
"type": "string",
"enum": [
"not_evaluated",
"in_review",
"validated",
"conditionally_validated",
"disputed",
"rejected",
"revoked"
]
}
},
"allowed_certainty_levels": {
"type": "array",
"items": {
"type": "string",
"enum": [
"unknown",
"speculative",
"low",
"medium",
"high",
"established",
"not_applicable"
]
}
},
"allowed_validated_as": {
"type": "array",
"items": {
"type": "string",
"enum": [
"hypothesis",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=70c8f4ea4c12:701-756
start=701
end=756
----
"claim",
"sourced_claim",
"reviewed_claim",
"high_confidence_fact",
"institutional_reference",
"publisher_declaration",
"technical_specification",
"legal_or_policy_position",
"mythological_corpus",
"fictional_corpus",
"symbolic_model",
"disputed_position",
"rejected_claim"
]
}
},
"include_disputed": {
"type": "boolean",
"default": false
},
"include_fictional": {
"type": "boolean",
"default": false
},
"include_mythological": {
"type": "boolean",
"default": false
}
}
}
},
"publisher": {
"type": "object",
"additionalProperties": false,
"required": [
"authority_channel_id",
"key_id"
],
"properties": {
"authority_channel_id": {
"$ref": "#/$defs/authority_channel_id",
"description": "Publisher authority channel identifier."
},
"key_id": {
"type": "string",
"minLength": 1,
"description": "Publisher key identifier."
},
"name": {
"type": "string",
"minLength": 1
}
}
}
}
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/exchange-manifest.schema.json"
id=caf71ff7fef4
kind=source
size=30055
lines=1107
line_ref=1-1107
chunks=4
chunk_refs=1-350,351-700,701-1050,1051-1107
summary="Source file."

--- CHUNK BEGIN ---
id=caf71ff7fef4:1-350
start=1
end=350
----
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/exchange-manifest.schema.json",
  "title": "Kristal v5 Exchange Manifest",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "artifact_type",
    "exchange_version",
    "created_at",
    "kristal_id",
    "artifact_status",
    "canonicalization_profile",
    "canonicalization_version",
    "content_hash",
    "build",
    "inputs",
    "scope"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "5.0",
      "description": "Manifest schema version."
    },
    "artifact_type": {
      "type": "string",
      "enum": [
        "working_exchange",
        "reference_exchange"
      ],
      "description": "Exchange artifact type. A working exchange is compiled and inspectable. A reference exchange has been recognized for a declared scope by one or more authority channels."
    },
    "exchange_version": {
      "type": "string",
      "const": "5.0",
      "description": "Kristal Exchange format version."
    },
    "manifest_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique ID for this manifest. Recommended form: sha256:<hex> over the manifest hash target, excluding signatures."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "UTC timestamp when the manifest was produced. Timestamps are not part of content-addressed Exchange payload IDs unless a profile explicitly says so."
    },
    "kristal_id": {
      "$ref": "#/$defs/kristal_id",
      "description": "Content-addressed ID of the Exchange payload (sha256:<hex>)."
    },
    "artifact_status": {
      "type": "string",
      "enum": [
        "draft",
        "working",
        "under_review",
        "recognized",
        "reference",
        "deprecated",
        "superseded",
        "revoked"
      ],
      "description": "Lifecycle status of the Exchange artifact. Use 'working' for compiled artifacts not yet recognized as a reference, and 'reference' for artifacts accepted under declared authority channels and policies."
    },
    "canonicalization_profile": {
      "type": "string",
      "const": "kristal.v5:jcs-rfc8785",
      "description": "Canonicalization profile identifier for deterministic hashing. The word canonicalization refers only to stable serialization."
    },
    "canonicalization_version": {
      "type": "string",
      "const": "1",
      "description": "Canonicalization profile version."
    },
    "content_hash": {
      "$ref": "#/$defs/hash",
      "description": "Hash of the canonicalized Exchange payload hash target. The hash target excludes kristal_id, content_hash, signatures, and external attestations."
    },
    "scope": {
      "$ref": "#/$defs/scope",
      "description": "Declared scope for this Exchange."
    },
    "build": {
      "$ref": "#/$defs/build",
      "description": "Deterministic build record and compiler identity. Build metadata is not part of the Exchange payload hash target unless a profile explicitly says so."
    },
    "inputs": {
      "$ref": "#/$defs/inputs",
      "description": "Input snapshot identifiers and upstream artifact references."
    },
    "source_state_refs": {
      "type": "array",
      "description": "Structured Epistemic State references used to produce this Exchange.",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "authority_registry_ref": {
      "$ref": "#/$defs/artifact_ref",
      "description": "Optional authority registry used to evaluate authority channels for this Exchange."
    },
    "authority_recognition_refs": {
      "type": "array",
      "description": "References to authority recognition artifacts that recognize this Exchange, one of its shards, or assertions within it.",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "validation_refs": {
      "type": "array",
      "description": "References to validation decisions or validation reports. Validation is scoped by authority channel, policy, certainty level, and domain.",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "review_refs": {
      "type": "array",
      "description": "References to review bundles, attestations, or workflow records.",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "reader_policy_refs": {
      "type": "array",
      "description": "Reader policies known to be compatible with this Exchange. Reader policies control visibility by authority channel, validation status, certainty level, and scope.",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "profiles_enabled": {
      "type": "array",
      "description": "Explicitly enabled optional profiles during compilation, validation, export, or distribution.",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "uniqueItems": true
    },
    "certainty_summary": {
      "$ref": "#/$defs/certainty_summary",
      "description": "Aggregate certainty information for the Exchange. This summary must not replace assertion-level status."
    },
    "validation_summary": {
      "$ref": "#/$defs/validation_summary",
      "description": "Aggregate validation information for the Exchange. This summary must not replace scoped validation decisions."
    },
    "exports": {
      "$ref": "#/$defs/exports",
      "description": "Deterministic export declarations and optional export integrity hashes."
    },
    "policies": {
      "$ref": "#/$defs/policies",
      "description": "Portable policy selections that may affect derived artifacts; Exchange should record those relevant to reproducibility, reader selection, and authority recognition."
    },
    "references": {
      "type": "array",
      "description": "Human-facing references associated with the Exchange manifest.",
      "items": {
        "$ref": "#/$defs/reference"
      }
    },
    "signatures": {
      "type": "array",
      "description": "Detached or embedded signatures over the manifest signature target. Signatures are excluded from content_hash and manifest_id hash targets.",
      "items": {
        "$ref": "#/$defs/signature"
      }
    },
    "extensions": {
      "type": "object",
      "description": "Extension namespace. Extension keys should be URI-like or reverse-DNS names to avoid collisions.",
      "additionalProperties": true
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "artifact_type": {
            "const": "reference_exchange"
          }
        },
        "required": [
          "artifact_type"
        ]
      },
      "then": {
        "properties": {
          "artifact_status": {
            "enum": [
              "recognized",
              "reference",
              "deprecated",
              "superseded",
              "revoked"
            ]
          }
        },
        "anyOf": [
          {
            "required": [
              "authority_recognition_refs"
            ],
            "properties": {
              "authority_recognition_refs": {
                "minItems": 1
              }
            }
          },
          {
            "required": [
              "validation_refs"
            ],
            "properties": {
              "validation_refs": {
                "minItems": 1
              }
            }
          }
        ]
      }
    },
    {
      "if": {
        "properties": {
          "artifact_type": {
            "const": "working_exchange"
          }
        },
        "required": [
          "artifact_type"
        ]
      },
      "then": {
        "properties": {
          "artifact_status": {
            "enum": [
              "draft",
              "working",
              "under_review",
              "deprecated",
              "superseded",
              "revoked"
            ]
          }
        }
      }
    }
  ],
  "$defs": {
    "sha256_hex": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "sha256_prefixed": {
      "type": "string",
      "pattern": "^sha256:[a-f0-9]{64}$"
    },
    "kristal_id": {
      "$ref": "#/$defs/sha256_prefixed"
    },
    "hash": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "alg",
        "value"
      ],
      "properties": {
        "alg": {
          "type": "string",
          "enum": [
            "sha256"
          ],
          "description": "Hash algorithm identifier."
        },
        "value": {
          "$ref": "#/$defs/sha256_hex",
          "description": "Lowercase hex-encoded hash digest."
        }
      }
    },
    "artifact_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "artifact_type"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "Artifact identifier. Recommended form: sha256:<hex> or a namespaced Kristal URI."
        },
        "artifact_type": {
          "type": "string",
          "enum": [
            "structured_epistemic_state",
            "working_exchange",
            "reference_exchange",
            "runtime_pack",
            "exchange_shard_manifest",
            "exchange_federation_manifest",
            "authority_registry",
            "authority_recognition",
            "validation_report",
            "validation_decision",
            "review_bundle",
            "revocations",
            "reader_policy",
            "transparency_log_entry",
            "external_dataset",
            "external_document"
          ]
        },
        "content_hash": {
          "$ref": "#/$defs/hash"
        },
        "uri": {
          "type": "string",
          "format": "uri"
        },
        "media_type": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "domain"
      ],
      "properties": {
        "domain": {
          "type": "string",
          "enum": [
            "general",
            "wikidata",
            "science",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=caf71ff7fef4:351-700
start=351
end=700
----
            "health",
            "education",
            "heritage",
            "law",
            "policy",
            "technology",
            "environment",
            "culture",
            "mythology",
            "fiction",
            "research",
            "operations",
            "civic",
            "local_notes"
          ]
        },
        "subdomain": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1
        },
        "jurisdiction": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1
        },
        "time_window": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1
        },
        "tenant_id": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1
        },
        "environment": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1
        },
        "language": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "description": "BCP 47 language tag when applicable."
        }
      }
    },
    "build": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "build_id",
        "compiler_name",
        "compiler_version",
        "config_hash",
        "compile_status"
      ],
      "properties": {
        "build_id": {
          "type": "string",
          "minLength": 1,
          "description": "Correlation ID for end-to-end tracing."
        },
        "compiler_name": {
          "type": "string",
          "minLength": 1
        },
        "compiler_version": {
          "type": "string",
          "minLength": 1
        },
        "config_hash": {
          "$ref": "#/$defs/hash",
          "description": "Digest of compilation configuration."
        },
        "compile_status": {
          "type": "string",
          "enum": [
            "succeeded",
            "failed",
            "partial"
          ]
        },
        "validation_status": {
          "$ref": "#/$defs/validation_status",
          "default": "not_evaluated"
        },
        "review_status": {
          "type": "string",
          "enum": [
            "not_required",
            "pending",
            "completed",
            "blocked"
          ],
          "default": "not_required"
        },
        "recognition_status": {
          "type": "string",
          "enum": [
            "none",
            "recognized",
            "conditionally_recognized",
            "under_review",
            "disputed",
            "rejected",
            "revoked"
          ],
          "default": "none"
        },
        "publication_status": {
          "type": "string",
          "enum": [
            "not_published",
            "published",
            "blocked"
          ],
          "default": "not_published"
        },
        "activation_status": {
          "type": "string",
          "enum": [
            "not_applicable",
            "activated",
            "blocked",
            "revoked"
          ],
          "default": "not_applicable"
        },
        "working_outputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        },
        "reference_outputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        },
        "reason_codes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/reason_code"
          },
          "uniqueItems": true
        },
        "git_commit": {
          "type": "string",
          "minLength": 1,
          "description": "Optional SCM commit identifier for the compiler/runtime."
        },
        "environment": {
          "type": "object",
          "description": "Optional build environment metadata.",
          "additionalProperties": true
        }
      }
    },
    "inputs": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "source_refs"
      ],
      "properties": {
        "source_refs": {
          "type": "array",
          "description": "Input documents, datasets, Structured Epistemic States, Claim-IR artifacts, prior Exchanges, or external corpora used to build this Exchange.",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "source_snapshot_id": {
          "type": "string",
          "minLength": 1,
          "description": "Optional identifier of the source snapshot used to build the Exchange."
        },
        "recipe_id": {
          "type": "string",
          "minLength": 1,
          "description": "Optional subset/build recipe identifier."
        },
        "structured_epistemic_state_ids": {
          "type": "array",
          "description": "Optional list of Structured Epistemic State artifact IDs used.",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "uniqueItems": true
        },
        "claim_ir_ids": {
          "type": "array",
          "description": "Optional list of Claim-IR artifact identifiers used by extractor proposal profiles. Claim-IR is not the universal required input format in Kristal v5.",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "uniqueItems": true
        },
        "resolved_claim_ir_ids": {
          "type": "array",
          "description": "Optional list of Resolved Claim-IR artifact identifiers used when a resolution profile is part of the build.",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "uniqueItems": true
        },
        "previous_exchange_ids": {
          "type": "array",
          "description": "Optional parent Exchange IDs for incremental builds, forks, merges, or lineage.",
          "items": {
            "$ref": "#/$defs/kristal_id"
          },
          "uniqueItems": true
        },
        "derived_from": {
          "type": "array",
          "description": "Artifacts this Exchange derives from.",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        },
        "merged_from": {
          "type": "array",
          "description": "Artifacts merged to create this Exchange.",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        },
        "supersedes": {
          "type": "array",
          "description": "Artifacts superseded by this Exchange.",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        }
      }
    },
    "exports": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "rdf": {
          "$ref": "#/$defs/export_decl"
        },
        "jsonld": {
          "$ref": "#/$defs/export_decl"
        },
        "wdqs": {
          "$ref": "#/$defs/export_decl"
        },
        "tpf": {
          "$ref": "#/$defs/export_decl"
        },
        "custom": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/export_decl"
          }
        }
      }
    },
    "export_decl": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "profile",
        "enabled"
      ],
      "properties": {
        "profile": {
          "type": "string",
          "minLength": 1
        },
        "enabled": {
          "type": "boolean"
        },
        "content_hash": {
          "$ref": "#/$defs/hash"
        },
        "uri": {
          "type": "string",
          "format": "uri"
        },
        "media_type": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "policies": {
      "type": "object",
      "description": "Portable policy selections for reproducibility, reader selection, validation, recognition, and distribution.",
      "additionalProperties": false,
      "properties": {
        "ordering_policies": {
          "type": "array",
          "description": "Selected triple-table orderings.",
          "minItems": 1,
          "items": {
            "type": "string",
            "enum": [
              "SPO",
              "SOP",
              "PSO",
              "POS",
              "OSP",
              "OPS"
            ]
          },
          "uniqueItems": true
        },
        "row_group_policy": {
          "$ref": "#/$defs/row_group_policy"
        },
        "reader_policy_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        },
        "validation_policy_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
--- CHUNK END ---

--- CHUNK BEGIN ---
id=caf71ff7fef4:701-1050
start=701
end=1050
----
          },
          "default": []
        },
        "recognition_policy_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        },
        "composition_policy": {
          "$ref": "#/$defs/composition_policy"
        },
        "allowed_runtime_pack_policies": {
          "type": "array",
          "description": "Runtime pack policy identifiers allowed for this Exchange.",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "uniqueItems": true
        }
      }
    },
    "row_group_policy": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "FIXED_ROWS",
            "FIXED_BYTES",
            "ADAPTIVE"
          ]
        },
        "rows": {
          "type": "integer",
          "minimum": 1
        },
        "bytes": {
          "type": "integer",
          "minimum": 1
        },
        "target_rows": {
          "type": "integer",
          "minimum": 1
        },
        "target_bytes": {
          "type": "integer",
          "minimum": 1
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "type": {
                "const": "FIXED_ROWS"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "required": [
              "rows"
            ]
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "FIXED_BYTES"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "required": [
              "bytes"
            ]
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "ADAPTIVE"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "required": [
              "target_rows",
              "target_bytes"
            ]
          }
        }
      ]
    },
    "composition_policy": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "policy_id",
        "policy_version",
        "overlap_strategy",
        "conflict_strategy",
        "default_visibility",
        "ordering"
      ],
      "properties": {
        "policy_id": {
          "type": "string",
          "minLength": 1
        },
        "policy_version": {
          "type": "string",
          "minLength": 1
        },
        "overlap_strategy": {
          "type": "string",
          "enum": [
            "authority_precedence",
            "latest_time_window",
            "explicit_allow_deny",
            "preserve_all",
            "reader_policy_selected"
          ]
        },
        "conflict_strategy": {
          "type": "string",
          "enum": [
            "preserve_disagreement",
            "authority_precedence",
            "mark_disputed",
            "exclude_conflict",
            "require_reader_choice"
          ]
        },
        "default_visibility": {
          "type": "string",
          "enum": [
            "reader_policy",
            "show_all_with_labels",
            "reference_only",
            "validated_only"
          ]
        },
        "ordering": {
          "type": "string",
          "enum": [
            "stable",
            "source_order",
            "authority_order",
            "time_order"
          ]
        },
        "parameters": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "certainty_summary": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "default_certainty_level": {
          "$ref": "#/$defs/certainty_level"
        },
        "contains_mixed_certainty": {
          "type": "boolean"
        },
        "counts_by_certainty_level": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "contains_hypotheses": {
          "type": "boolean"
        },
        "contains_disputed_assertions": {
          "type": "boolean"
        },
        "contains_fictional_or_mythological_material": {
          "type": "boolean"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "validation_summary": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "default_validation_status": {
          "$ref": "#/$defs/validation_status"
        },
        "validated_as": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/validated_as"
          },
          "uniqueItems": true
        },
        "authority_channels": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/authority_channel_id"
          },
          "uniqueItems": true
        },
        "recognition_statuses": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/recognition_status"
          },
          "uniqueItems": true
        },
        "counts_by_validation_status": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "validation_status": {
      "type": "string",
      "enum": [
        "not_evaluated",
        "in_review",
        "validated",
        "conditionally_validated",
        "disputed",
        "rejected",
        "revoked"
      ]
    },
    "recognition_status": {
      "type": "string",
      "enum": [
        "recognized",
        "conditionally_recognized",
        "under_review",
        "disputed",
        "rejected",
        "deprecated",
        "revoked"
      ]
    },
    "certainty_level": {
      "type": "string",
      "enum": [
        "unknown",
        "speculative",
        "low",
        "medium",
        "high",
        "established",
        "not_applicable"
      ]
    },
    "validated_as": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claim",
        "sourced_claim",
        "reviewed_claim",
        "high_confidence_fact",
        "institutional_reference",
        "publisher_declaration",
        "technical_specification",
        "legal_or_policy_position",
        "mythological_corpus",
        "fictional_corpus",
        "symbolic_model",
        "disputed_position",
        "rejected_claim"
      ]
    },
    "authority_channel_id": {
      "type": "string",
      "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "schema_valid",
        "schema_invalid",
        "provenance_sufficient",
        "provenance_insufficient",
        "evidence_sufficient",
        "evidence_insufficient",
        "authority_recognized",
        "authority_not_recognized",
        "scope_mismatch",
        "policy_satisfied",
        "policy_failed",
        "signature_valid",
        "signature_invalid",
        "hash_valid",
        "hash_invalid",
        "conflict_detected",
        "disagreement_preserved",
        "certainty_too_low_for_policy",
        "rejected_by_authority_channel",
        "revoked_by_authority_channel"
      ]
    },
    "reference": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "label",
        "uri"
      ],
      "properties": {
        "label": {
          "type": "string",
          "minLength": 1
        },
        "uri": {
          "type": "string",
          "format": "uri"
        },
        "description": {
          "type": "string"
        }
      }
--- CHUNK END ---

--- CHUNK BEGIN ---
id=caf71ff7fef4:1051-1107
start=1051
end=1107
----
    },
    "signature": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "key_id",
        "alg",
        "signature"
      ],
      "properties": {
        "key_id": {
          "type": "string",
          "minLength": 1,
          "description": "Key identifier used to verify this signature."
        },
        "alg": {
          "type": "string",
          "enum": [
            "ed25519"
          ],
          "description": "Signature algorithm identifier."
        },
        "signature": {
          "type": "string",
          "minLength": 1,
          "description": "Signature value, encoded as specified by the signing profile."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "signer": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1
            },
            "org": {
              "type": "string",
              "minLength": 1
            },
            "authority_channel": {
              "$ref": "#/$defs/authority_channel_id"
            }
          }
        },
        "certificate_uri": {
          "type": "string",
          "format": "uri",
          "description": "Optional pointer to a certificate chain or public key material."
        }
      }
    }
  }
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/exchange-shard-manifest.schema.json"
id=d3715886bd60
kind=source
size=19944
lines=1084
line_ref=1-1084
chunks=4
chunk_refs=1-350,351-700,701-1050,1051-1084
summary="Source file."

--- CHUNK BEGIN ---
id=d3715886bd60:1-350
start=1
end=350
----
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://kristal.org/schemas/v5/exchange-shard-manifest.schema.json",
"title": "Kristal v5 Exchange Shard Manifest",
"type": "object",
"additionalProperties": false,
"required": [
"schema_version",
"artifact_type",
"manifest_id",
"created_at",
"shard_id",
"canonicalization_profile",
"canonicalization_version",
"content_hash",
"producer",
"build",
"inputs",
"policies",
"scope",
"artifact_status",
"assertion_status_summary",
"certainty_summary",
"validation_refs",
"authority_recognition_refs",
"reader_policy_refs",
"integrity",
"signatures"
],
"properties": {
"schema_version": {
"type": "string",
"const": "5.0",
"description": "Manifest schema version."
},
"artifact_type": {
"type": "string",
"const": "exchange_shard_manifest",
"description": "Artifact discriminator."
},
"manifest_id": {
"$ref": "#/$defs/kristal_id",
"description": "Content-addressed ID of this manifest. The manifest_id field itself is excluded from the manifest hash target."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "UTC timestamp when the manifest was produced. Timestamps are not part of content-addressed shard IDs unless a profile explicitly includes them."
},
"shard_id": {
"$ref": "#/$defs/kristal_id",
"description": "Content-addressed ID of the shard Exchange payload."
},
"kristal_id": {
"$ref": "#/$defs/kristal_id",
"description": "Alias for shard_id when the shard is addressed as a Kristal artifact."
},
"source_exchange_ref": {
"$ref": "#/$defs/artifact_ref",
"description": "Optional reference to the source Exchange artifact from which this shard manifest was derived."
},
"artifact_status": {
"$ref": "#/$defs/artifact_status",
"description": "Lifecycle status of the shard artifact. This status describes the artifact, not the universal truth of its assertions."
},
"canonicalization_profile": {
"type": "string",
"const": "kristal.v5:jcs-rfc8785",
"description": "Canonicalization profile identifier for hashing/signing. The word canonicalization here means stable byte representation, not truth authority."
},
"canonicalization_version": {
"type": "string",
"const": "1",
"description": "Canonicalization version for hashing/signing."
},
"content_hash": {
"$ref": "#/$defs/hash",
"description": "Hash of the canonicalized shard Exchange payload hash target. Signatures, attestations, and output ID fields are excluded from the hash target."
},
"producer": {
"$ref": "#/$defs/producer",
"description": "Producer identity for this shard manifest."
},
"build": {
"$ref": "#/$defs/build",
"description": "Build record for deterministic compilation, validation status, recognition status, publication status, and activation status."
},
"inputs": {
"$ref": "#/$defs/inputs",
"description": "Input snapshot identifiers and upstream artifact references."
},
"policies": {
"$ref": "#/$defs/policies",
"description": "Policies used for compilation, validation, recognition, composition, reader filtering, runtime packaging, and distribution."
},
"scope": {
"$ref": "#/$defs/scope",
"description": "Declared scope of this shard."
},
"assertion_status_summary": {
"$ref": "#/$defs/assertion_status_summary",
"description": "Summary of assertion statuses present in the shard."
},
"certainty_summary": {
"$ref": "#/$defs/certainty_summary",
"description": "Summary of certainty levels present in the shard."
},
"validation_refs": {
"type": "array",
"description": "Validation decisions that apply to this shard, to assertions within it, or to related authority channels. A validation ref does not imply universal truth.",
"items": {
"$ref": "#/$defs/validation_ref"
},
"default": []
},
"authority_recognition_refs": {
"type": "array",
"description": "Authority recognitions that apply to this shard, to assertions within it, or to related authority channels.",
"items": {
"$ref": "#/$defs/authority_recognition_ref"
},
"default": []
},
"reader_policy_refs": {
"type": "array",
"description": "Reader policies known to be compatible with this shard. Readers may use these to expose reference-only, validated-only, research, creative, or custom views.",
"items": {
"$ref": "#/$defs/reader_policy_ref"
},
"default": []
},
"integrity": {
"$ref": "#/$defs/integrity",
"description": "Integrity and verification requirements for this shard manifest."
},
"lineage": {
"$ref": "#/$defs/lineage",
"description": "Lineage metadata preserving source artifacts, transforms, merges, and supersession relationships."
},
"extensions": {
"type": "object",
"description": "Namespaced extension data. Extension keys SHOULD use reverse-DNS or URI-like names.",
"additionalProperties": true
},
"signatures": {
"type": "array",
"description": "Signatures over the canonicalized manifest hash target. Signatures are excluded from the signed hash target.",
"items": {
"$ref": "#/$defs/signature"
},
"default": []
}
},
"$defs": {
"kristal_id": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$",
"description": "Content-addressed identifier using sha256:<hex>."
},
"artifact_status": {
"type": "string",
"enum": [
"draft",
"working",
"under_review",
"recognized",
"reference",
"deprecated",
"superseded",
"revoked"
],
"description": "Artifact lifecycle status."
},
"assertion_status": {
"type": "string",
"enum": [
"hypothesis",
"claimed",
"sourced",
"disputed",
"reviewed",
"validated",
"rejected",
"retracted",
"superseded"
],
"description": "Status of an assertion."
},
"certainty_level": {
"type": "string",
"enum": [
"unknown",
"speculative",
"low",
"medium",
"high",
"established",
"not_applicable"
],
"description": "Certainty level within the declared scope."
},
"validated_as": {
"type": "string",
"enum": [
"hypothesis",
"claim",
"sourced_claim",
"reviewed_claim",
"high_confidence_fact",
"institutional_reference",
"publisher_declaration",
"technical_specification",
"legal_or_policy_position",
"mythological_corpus",
"fictional_corpus",
"symbolic_model",
"disputed_position",
"rejected_claim"
],
"description": "What the assertion, shard, or artifact was validated as."
},
"validation_status": {
"type": "string",
"enum": [
"not_evaluated",
"in_review",
"validated",
"conditionally_validated",
"disputed",
"rejected",
"revoked"
],
"description": "Validation status under a declared authority channel and policy."
},
"recognition_status": {
"type": "string",
"enum": [
"none",
"recognized",
"conditionally_recognized",
"under_review",
"disputed",
"rejected",
"deprecated",
"revoked"
],
"description": "Recognition status under an authority channel."
},
"reader_mode": {
"type": "string",
"enum": [
"reference_only",
"validated_only",
"high_certainty_only",
"research",
"creative",
"all_with_labels",
"custom"
],
"description": "Reader policy mode."
},
"domain": {
"type": "string",
"enum": [
"general",
"wikidata",
"science",
"health",
"education",
"heritage",
"law",
"policy",
"technology",
"environment",
"culture",
"mythology",
"fiction",
"research",
"operations",
"civic",
"local_notes"
],
"description": "Controlled top-level scope domain."
},
"hash": {
"type": "object",
"additionalProperties": false,
"required": [
"alg",
"value"
],
"properties": {
"alg": {
"type": "string",
"const": "sha256",
"description": "Hash algorithm. Use alg, not algo."
},
"value": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest."
}
}
},
"artifact_ref": {
"type": "object",
"additionalProperties": false,
"required": [
"artifact_type",
"artifact_id"
],
"properties": {
"artifact_type": {
"type": "string",
"minLength": 1
},
"artifact_id": {
"$ref": "#/$defs/kristal_id"
},
"content_hash": {
"$ref": "#/$defs/hash"
},
"uri": {
"type": "string",
"format": "uri"
},
"version": {
"type": "string",
"minLength": 1
}
}
},
"producer": {
"type": "object",
"additionalProperties": false,
"required": [
"producer_id",
"name"
],
"properties": {
"producer_id": {
"type": "string",
"minLength": 1,
"description": "Stable producer identifier."
},
"name": {
"type": "string",
"minLength": 1
},
"org": {
--- CHUNK END ---

--- CHUNK BEGIN ---
id=d3715886bd60:351-700
start=351
end=700
----
"type": "string",
"minLength": 1
},
"authority_channel": {
"type": "string",
"pattern": "^authority:[a-z0-9][a-z0-9.*:-]*$",
"description": "Authority channel under which the producer publishes, if applicable."
},
"software": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"source_uri": {
"type": "string",
"format": "uri"
},
"build_hash": {
"$ref": "#/$defs/hash"
}
}
}
}
},
"build": {
"type": "object",
"additionalProperties": false,
"required": [
"build_id",
"schema_version",
"compile_status",
"validation_status",
"review_status",
"recognition_status",
"publication_status",
"activation_status",
"working_outputs",
"reference_outputs",
"reason_codes",
"created_at"
],
"properties": {
"build_id": {
"type": "string",
"minLength": 1
},
"schema_version": {
"type": "string",
"const": "5.0"
},
"compile_status": {
"type": "string",
"enum": [
"succeeded",
"failed",
"partial"
]
},
"validation_status": {
"$ref": "#/$defs/validation_status"
},
"review_status": {
"type": "string",
"enum": [
"not_required",
"pending",
"completed",
"blocked"
]
},
"recognition_status": {
"$ref": "#/$defs/recognition_status"
},
"publication_status": {
"type": "string",
"enum": [
"not_published",
"published",
"blocked"
]
},
"activation_status": {
"type": "string",
"enum": [
"not_applicable",
"activated",
"blocked",
"revoked"
]
},
"working_outputs": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_ref"
},
"default": []
},
"reference_outputs": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_ref"
},
"default": []
},
"reason_codes": {
"type": "array",
"items": {
"$ref": "#/$defs/reason_code"
},
"default": []
},
"created_at": {
"type": "string",
"format": "date-time"
},
"compiler": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"profile": {
"type": "string",
"minLength": 1
}
}
}
}
},
"reason_code": {
"type": "string",
"enum": [
"schema_valid",
"schema_invalid",
"provenance_sufficient",
"provenance_insufficient",
"evidence_sufficient",
"evidence_insufficient",
"authority_recognized",
"authority_not_recognized",
"scope_mismatch",
"policy_satisfied",
"policy_failed",
"signature_valid",
"signature_invalid",
"hash_valid",
"hash_invalid",
"conflict_detected",
"disagreement_preserved",
"certainty_too_low_for_policy",
"rejected_by_authority_channel",
"revoked_by_authority_channel"
]
},
"inputs": {
"type": "object",
"additionalProperties": false,
"required": [
"source_refs",
"derived_from",
"merged_from",
"supersedes"
],
"properties": {
"source_refs": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_ref"
},
"default": []
},
"derived_from": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_ref"
},
"default": []
},
"merged_from": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_ref"
},
"default": []
},
"supersedes": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_ref"
},
"default": []
},
"input_hashes": {
"type": "array",
"items": {
"$ref": "#/$defs/hash"
},
"default": []
}
}
},
"policies": {
"type": "object",
"additionalProperties": false,
"required": [
"compilation_policy_ref",
"validation_policy_refs",
"recognition_policy_refs",
"composition_policy_ref",
"reader_policy_refs",
"runtime_policy_refs"
],
"properties": {
"compilation_policy_ref": {
"$ref": "#/$defs/policy_ref"
},
"validation_policy_refs": {
"type": "array",
"items": {
"$ref": "#/$defs/policy_ref"
},
"default": []
},
"recognition_policy_refs": {
"type": "array",
"items": {
"$ref": "#/$defs/policy_ref"
},
"default": []
},
"composition_policy_ref": {
"$ref": "#/$defs/policy_ref"
},
"reader_policy_refs": {
"type": "array",
"items": {
"$ref": "#/$defs/reader_policy_ref"
},
"default": []
},
"runtime_policy_refs": {
"type": "array",
"items": {
"$ref": "#/$defs/policy_ref"
},
"default": []
}
}
},
"policy_ref": {
"type": "object",
"additionalProperties": false,
"required": [
"policy_id"
],
"properties": {
"policy_id": {
"type": "string",
"minLength": 1
},
"policy_version": {
"type": "string",
"minLength": 1
},
"uri": {
"type": "string",
"format": "uri"
},
"content_hash": {
"$ref": "#/$defs/hash"
}
}
},
"reader_policy_ref": {
"type": "object",
"additionalProperties": false,
"required": [
"reader_policy_id",
"mode"
],
"properties": {
"reader_policy_id": {
"type": "string",
"pattern": "^reader_policy:[a-z0-9][a-z0-9.*:-]*$"
},
"mode": {
"$ref": "#/$defs/reader_mode"
},
"uri": {
"type": "string",
"format": "uri"
},
"content_hash": {
"$ref": "#/$defs/hash"
}
}
},
"scope": {
"type": "object",
"additionalProperties": false,
"required": [
"domain"
],
"properties": {
"domain": {
"$ref": "#/$defs/domain"
},
"subdomain": {
"type": [
"string",
"null"
],
"minLength": 1
},
"jurisdiction": {
"type": [
"string",
"null"
],
"minLength": 1
},
"time_window": {
"type": [
"string",
"null"
],
"minLength": 1
},
"tenant_id": {
"type": [
"string",
"null"
],
"minLength": 1
},
"environment": {
"type": [
--- CHUNK END ---

--- CHUNK BEGIN ---
id=d3715886bd60:701-1050
start=701
end=1050
----
"string",
"null"
],
"minLength": 1
},
"language": {
"type": [
"string",
"null"
],
"minLength": 1
}
}
},
"assertion_status_summary": {
"type": "object",
"additionalProperties": false,
"required": [
"counts"
],
"properties": {
"counts": {
"type": "object",
"additionalProperties": {
"type": "integer",
"minimum": 0
},
"description": "Map of assertion_status to count."
},
"dominant_status": {
"$ref": "#/$defs/assertion_status"
},
"contains_disputed": {
"type": "boolean",
"default": false
},
"contains_rejected": {
"type": "boolean",
"default": false
}
}
},
"certainty_summary": {
"type": "object",
"additionalProperties": false,
"required": [
"counts"
],
"properties": {
"counts": {
"type": "object",
"additionalProperties": {
"type": "integer",
"minimum": 0
},
"description": "Map of certainty_level to count."
},
"lowest_certainty_level": {
"$ref": "#/$defs/certainty_level"
},
"highest_certainty_level": {
"$ref": "#/$defs/certainty_level"
},
"mixed_certainty": {
"type": "boolean",
"default": true
}
}
},
"validation_ref": {
"type": "object",
"additionalProperties": false,
"required": [
"validation_decision_id",
"target_level",
"validation_status",
"validated_as",
"certainty_level",
"authority_channel",
"scope"
],
"properties": {
"validation_decision_id": {
"$ref": "#/$defs/kristal_id"
},
"target_ref": {
"$ref": "#/$defs/artifact_ref"
},
"target_level": {
"type": "string",
"enum": [
"artifact",
"shard",
"assertion",
"authority_channel",
"runtime_pack"
]
},
"validation_status": {
"$ref": "#/$defs/validation_status"
},
"validated_as": {
"$ref": "#/$defs/validated_as"
},
"certainty_level": {
"$ref": "#/$defs/certainty_level"
},
"authority_channel": {
"type": "string",
"pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
},
"validation_policy_ref": {
"$ref": "#/$defs/policy_ref"
},
"scope": {
"$ref": "#/$defs/scope"
},
"reason_codes": {
"type": "array",
"items": {
"$ref": "#/$defs/reason_code"
},
"default": []
}
}
},
"authority_recognition_ref": {
"type": "object",
"additionalProperties": false,
"required": [
"recognition_id",
"issuer_authority_channel",
"target_level",
"recognition_status",
"recognized_as",
"scope"
],
"properties": {
"recognition_id": {
"$ref": "#/$defs/kristal_id"
},
"issuer_authority_channel": {
"type": "string",
"pattern": "^authority:[a-z0-9][a-z0-9.*:-]*$"
},
"target_ref": {
"$ref": "#/$defs/artifact_ref"
},
"target_level": {
"type": "string",
"enum": [
"artifact",
"shard",
"assertion",
"authority_channel",
"dataset",
"runtime_pack"
]
},
"recognition_status": {
"$ref": "#/$defs/recognition_status"
},
"recognized_as": {
"$ref": "#/$defs/validated_as"
},
"scope": {
"$ref": "#/$defs/scope"
},
"validation_policy_ref": {
"$ref": "#/$defs/policy_ref"
},
"reason_codes": {
"type": "array",
"items": {
"$ref": "#/$defs/reason_code"
},
"default": []
}
}
},
"integrity": {
"type": "object",
"additionalProperties": false,
"required": [
"hash_alg",
"signature_required",
"trust_root_required",
"verification_requirements"
],
"properties": {
"hash_alg": {
"type": "string",
"const": "sha256"
},
"signature_required": {
"type": "boolean"
},
"trust_root_required": {
"type": "boolean"
},
"verification_requirements": {
"type": "array",
"items": {
"type": "string",
"enum": [
"schema_validation",
"hash_verification",
"signature_verification",
"trust_root_verification",
"policy_check",
"scope_check",
"authority_recognition_check",
"reader_policy_check"
]
},
"default": []
},
"trust_roots": {
"type": "array",
"items": {
"$ref": "#/$defs/trust_root"
},
"default": []
}
}
},
"trust_root": {
"type": "object",
"additionalProperties": false,
"required": [
"trust_root_id",
"type"
],
"properties": {
"trust_root_id": {
"type": "string",
"minLength": 1
},
"type": {
"type": "string",
"enum": [
"public_key",
"certificate",
"authority_registry",
"transparency_log"
]
},
"uri": {
"type": "string",
"format": "uri"
},
"content_hash": {
"$ref": "#/$defs/hash"
}
}
},
"lineage": {
"type": "object",
"additionalProperties": false,
"properties": {
"source_artifacts": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_ref"
},
"default": []
},
"transforms": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"transform_id",
"name"
],
"properties": {
"transform_id": {
"type": "string",
"minLength": 1
},
"name": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"policy_ref": {
"$ref": "#/$defs/policy_ref"
}
}
},
"default": []
},
"compiler": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
}
}
},
"policy_refs": {
"type": "array",
"items": {
"$ref": "#/$defs/policy_ref"
},
"default": []
}
}
},
"signature": {
"type": "object",
"additionalProperties": false,
"required": [
"key_id",
"alg",
"signature",
"created_at"
],
"properties": {
"key_id": {
"type": "string",
"minLength": 1,
"description": "Signing key identifier."
},
"alg": {
"type": "string",
"const": "ed25519",
"description": "Signature algorithm. Use alg, not algo."
},
"signature": {
"type": "string",
"minLength": 1,
"description": "Signature value, encoded as specified by the signing profile."
},
"created_at": {
"type": "string",
"format": "date-time"
},
"expires_at": {
"type": "string",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=d3715886bd60:1051-1084
start=1051
end=1084
----
"format": "date-time"
},
"purpose": {
"type": "string",
"minLength": 1,
"description": "Optional signature purpose label."
},
"signer": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"org": {
"type": "string",
"minLength": 1
},
"authority_channel": {
"type": "string",
"pattern": "^authority:[a-z0-9][a-z0-9.*:-]*$"
}
}
},
"certificate_uri": {
"type": "string",
"format": "uri",
"description": "Optional pointer to a certificate chain or public key material."
}
}
}
}
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/reader-policy.schema.json"
id=b2f82861c760
kind=source
size=18593
lines=1207
line_ref=1-1207
chunks=4
chunk_refs=1-350,351-700,701-1050,1051-1207
summary="Source file."

--- CHUNK BEGIN ---
id=b2f82861c760:1-350
start=1
end=350
----
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://kristal.org/schemas/v5/reader-policy.schema.json",
"title": "Reader Policy v5",
"description": "Reader Policy defines which Kristal v5 artifacts, assertions, authority channels, validation statuses, certainty levels, scopes, and epistemic modes are eligible for display or use by a reader, renderer, query engine, runtime pack, or application surface.",
"type": "object",
"additionalProperties": false,
"required": [
"schema_version",
"artifact_type",
"reader_policy_id",
"mode",
"created_at",
"policy"
],
"properties": {
"schema_version": {
"type": "string",
"const": "5.0"
},
"artifact_type": {
"type": "string",
"const": "reader_policy"
},
"reader_policy_id": {
"$ref": "#/$defs/reader_policy_id"
},
"name": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string"
},
"mode": {
"$ref": "#/$defs/reader_mode"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"created_by": {
"$ref": "#/$defs/agent_ref"
},
"issuer_authority_channel": {
"$ref": "#/$defs/authority_ref"
},
"canonicalization_profile": {
"type": "string",
"const": "kristal.v5:jcs-rfc8785"
},
"canonicalization_version": {
"type": "string",
"const": "1"
},
"content_hash": {
"$ref": "#/$defs/hash_ref"
},
"hash_target_policy": {
"$ref": "#/$defs/hash_target_policy"
},
"scope": {
"$ref": "#/$defs/scope"
},
"policy": {
"$ref": "#/$defs/policy_body"
},
"fallback_behavior": {
"$ref": "#/$defs/fallback_behavior"
},
"rendering": {
"$ref": "#/$defs/rendering_policy"
},
"query": {
"$ref": "#/$defs/query_policy"
},
"federation": {
"$ref": "#/$defs/federation_policy"
},
"offline": {
"$ref": "#/$defs/offline_policy"
},
"revocation": {
"$ref": "#/$defs/revocation_policy"
},
"lineage": {
"$ref": "#/$defs/lineage_policy"
},
"policy_refs": {
"type": "array",
"items": {
"$ref": "#/$defs/policy_ref"
},
"default": []
},
"derived_from": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_ref"
},
"default": []
},
"supersedes": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_ref"
},
"default": []
},
"warnings": {
"type": "array",
"items": {
"$ref": "#/$defs/warning"
},
"default": []
},
"extensions": {
"type": "object",
"additionalProperties": true,
"default": {}
},
"signatures": {
"type": "array",
"items": {
"$ref": "#/$defs/signature"
},
"default": []
}
},
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "reference_only"
}
}
},
"then": {
"properties": {
"policy": {
"properties": {
"allowed_artifact_statuses": {
"contains": {
"const": "reference"
}
},
"allowed_validation_statuses": {
"contains": {
"const": "validated"
}
},
"allow_unrecognized_authority_channels": {
"const": false
}
}
}
}
}
},
{
"if": {
"properties": {
"mode": {
"const": "validated_only"
}
}
},
"then": {
"properties": {
"policy": {
"properties": {
"allowed_validation_statuses": {
"contains": {
"const": "validated"
}
}
}
}
}
}
},
{
"if": {
"properties": {
"mode": {
"const": "high_certainty_only"
}
}
},
"then": {
"properties": {
"policy": {
"properties": {
"allowed_certainty_levels": {
"minItems": 1,
"items": {
"enum": [
"high",
"established"
]
}
}
}
}
}
}
},
{
"if": {
"properties": {
"mode": {
"const": "creative"
}
}
},
"then": {
"properties": {
"policy": {
"properties": {
"include_fictional": {
"const": true
},
"include_mythological": {
"const": true
}
}
}
}
}
}
],
"$defs": {
"sha256_hex": {
"type": "string",
"pattern": "^[0-9a-fA-F]{64}$"
},
"sha256_uri": {
"type": "string",
"pattern": "^sha256:[0-9a-fA-F]{64}$"
},
"reader_policy_id": {
"type": "string",
"pattern": "^reader_policy:[a-z0-9][a-z0-9.*:-]*$"
},
"authority_channel_id": {
"type": "string",
"pattern": "^authority:[a-z0-9][a-z0-9.*:-]*$"
},
"lang": {
"type": "string",
"pattern": "^[a-z]{2,3}(-[A-Z]{2})?$"
},
"hash_ref": {
"type": "object",
"additionalProperties": false,
"required": [
"alg",
"value"
],
"properties": {
"alg": {
"type": "string",
"const": "sha256"
},
"value": {
"$ref": "#/$defs/sha256_hex"
}
}
},
"hash_target_policy": {
"type": "object",
"additionalProperties": false,
"required": [
"exclude_fields"
],
"properties": {
"exclude_fields": {
"type": "array",
"items": {
"type": "string",
"enum": [
"content_hash",
"signatures"
]
},
"uniqueItems": true
},
"notes": {
"type": "string"
}
}
},
"signature": {
"type": "object",
"additionalProperties": false,
"required": [
"key_id",
"alg",
"signature",
"created_at"
],
"properties": {
"key_id": {
"type": "string",
"minLength": 1
},
"alg": {
"type": "string",
"const": "ed25519"
},
"signature": {
"type": "string",
"minLength": 1
},
"created_at": {
"type": "string",
"format": "date-time"
},
"authority_channel": {
"$ref": "#/$defs/authority_ref"
}
}
},
"reader_mode": {
"type": "string",
"enum": [
"reference_only",
"validated_only",
"high_certainty_only",
"research",
"creative",
"all_with_labels",
"custom"
]
},
"artifact_status": {
"type": "string",
"enum": [
"draft",
"working",
"under_review",
"recognized",
"reference",
"deprecated",
"superseded",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=b2f82861c760:351-700
start=351
end=700
----
"revoked"
]
},
"assertion_status": {
"type": "string",
"enum": [
"hypothesis",
"claimed",
"sourced",
"disputed",
"reviewed",
"validated",
"rejected",
"retracted",
"superseded"
]
},
"certainty_level": {
"type": "string",
"enum": [
"unknown",
"speculative",
"low",
"medium",
"high",
"established",
"not_applicable"
]
},
"validation_status": {
"type": "string",
"enum": [
"not_evaluated",
"in_review",
"validated",
"conditionally_validated",
"disputed",
"rejected",
"revoked"
]
},
"validated_as": {
"type": "string",
"enum": [
"hypothesis",
"claim",
"sourced_claim",
"reviewed_claim",
"high_confidence_fact",
"institutional_reference",
"publisher_declaration",
"technical_specification",
"legal_or_policy_position",
"mythological_corpus",
"fictional_corpus",
"symbolic_model",
"disputed_position",
"rejected_claim"
]
},
"recognition_status": {
"type": "string",
"enum": [
"recognized",
"conditionally_recognized",
"under_review",
"disputed",
"rejected",
"deprecated",
"revoked"
]
},
"domain": {
"type": "string",
"enum": [
"general",
"wikidata",
"science",
"health",
"education",
"heritage",
"law",
"policy",
"technology",
"environment",
"culture",
"mythology",
"fiction",
"research",
"operations",
"civic",
"local_notes"
]
},
"scope": {
"type": "object",
"additionalProperties": false,
"required": [
"domain"
],
"properties": {
"domain": {
"$ref": "#/$defs/domain"
},
"subdomain": {
"type": [
"string",
"null"
]
},
"jurisdiction": {
"type": [
"string",
"null"
]
},
"time_window": {
"type": [
"string",
"null"
]
},
"tenant_id": {
"type": [
"string",
"null"
]
},
"environment": {
"type": [
"string",
"null"
]
},
"language": {
"type": [
"string",
"null"
]
}
}
},
"artifact_ref": {
"type": "object",
"additionalProperties": false,
"properties": {
"artifact_id": {
"type": "string",
"minLength": 1
},
"artifact_type": {
"type": "string",
"minLength": 1
},
"uri": {
"type": "string",
"format": "uri"
},
"content_hash": {
"$ref": "#/$defs/hash_ref"
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"anyOf": [
{
"required": [
"artifact_id"
]
},
{
"required": [
"uri"
]
},
{
"required": [
"content_hash"
]
}
]
},
"policy_ref": {
"type": "object",
"additionalProperties": false,
"properties": {
"policy_id": {
"type": "string",
"minLength": 1
},
"policy_version": {
"type": "string",
"minLength": 1
},
"policy_ref": {
"$ref": "#/$defs/artifact_ref"
}
},
"anyOf": [
{
"required": [
"policy_id"
]
},
{
"required": [
"policy_ref"
]
}
]
},
"authority_ref": {
"type": "object",
"additionalProperties": false,
"required": [
"authority_channel_id"
],
"properties": {
"authority_channel_id": {
"$ref": "#/$defs/authority_channel_id"
},
"name": {
"type": "string"
},
"authority_registry_ref": {
"$ref": "#/$defs/artifact_ref"
}
}
},
"agent_ref": {
"type": "object",
"additionalProperties": false,
"properties": {
"agent_id": {
"type": "string",
"minLength": 1
},
"name": {
"type": "string"
},
"agent_type": {
"type": "string",
"enum": [
"individual",
"community",
"association",
"research_collective",
"academic_institution",
"standards_body",
"company",
"government",
"intergovernmental_organization",
"ai_validator",
"hybrid_collective",
"service",
"system"
]
},
"authority_channel": {
"$ref": "#/$defs/authority_ref"
}
},
"anyOf": [
{
"required": [
"agent_id"
]
},
{
"required": [
"name"
]
},
{
"required": [
"authority_channel"
]
}
]
},
"authority_filter": {
"type": "object",
"additionalProperties": false,
"properties": {
"allowed_authority_channels": {
"type": "array",
"items": {
"$ref": "#/$defs/authority_ref"
},
"default": []
},
"blocked_authority_channels": {
"type": "array",
"items": {
"$ref": "#/$defs/authority_ref"
},
"default": []
},
"allow_unrecognized_authority_channels": {
"type": "boolean",
"default": false
},
"allow_conditionally_recognized_authorities": {
"type": "boolean",
"default": false
},
"allow_revoked_authorities": {
"type": "boolean",
"default": false
}
}
},
"scope_filter": {
"type": "object",
"additionalProperties": false,
"properties": {
"allowed_domains": {
"type": "array",
"items": {
"$ref": "#/$defs/domain"
},
"uniqueItems": true,
"default": []
},
"blocked_domains": {
"type": "array",
"items": {
"$ref": "#/$defs/domain"
},
"uniqueItems": true,
"default": []
},
"allowed_scopes": {
"type": "array",
"items": {
"$ref": "#/$defs/scope"
},
"default": []
},
"blocked_scopes": {
"type": "array",
"items": {
"$ref": "#/$defs/scope"
},
"default": []
},
"language_priority": {
"type": "array",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=b2f82861c760:701-1050
start=701
end=1050
----
"items": {
"$ref": "#/$defs/lang"
},
"default": []
},
"jurisdiction_priority": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
}
},
"policy_body": {
"type": "object",
"additionalProperties": false,
"properties": {
"allowed_artifact_statuses": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_status"
},
"uniqueItems": true,
"default": []
},
"blocked_artifact_statuses": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_status"
},
"uniqueItems": true,
"default": [
"revoked"
]
},
"allowed_assertion_statuses": {
"type": "array",
"items": {
"$ref": "#/$defs/assertion_status"
},
"uniqueItems": true,
"default": []
},
"blocked_assertion_statuses": {
"type": "array",
"items": {
"$ref": "#/$defs/assertion_status"
},
"uniqueItems": true,
"default": [
"retracted"
]
},
"allowed_validation_statuses": {
"type": "array",
"items": {
"$ref": "#/$defs/validation_status"
},
"uniqueItems": true,
"default": []
},
"blocked_validation_statuses": {
"type": "array",
"items": {
"$ref": "#/$defs/validation_status"
},
"uniqueItems": true,
"default": [
"revoked"
]
},
"allowed_recognition_statuses": {
"type": "array",
"items": {
"$ref": "#/$defs/recognition_status"
},
"uniqueItems": true,
"default": []
},
"blocked_recognition_statuses": {
"type": "array",
"items": {
"$ref": "#/$defs/recognition_status"
},
"uniqueItems": true,
"default": [
"revoked"
]
},
"allowed_certainty_levels": {
"type": "array",
"items": {
"$ref": "#/$defs/certainty_level"
},
"uniqueItems": true,
"default": []
},
"blocked_certainty_levels": {
"type": "array",
"items": {
"$ref": "#/$defs/certainty_level"
},
"uniqueItems": true,
"default": []
},
"allowed_validated_as": {
"type": "array",
"items": {
"$ref": "#/$defs/validated_as"
},
"uniqueItems": true,
"default": []
},
"blocked_validated_as": {
"type": "array",
"items": {
"$ref": "#/$defs/validated_as"
},
"uniqueItems": true,
"default": []
},
"authority_filter": {
"$ref": "#/$defs/authority_filter"
},
"scope_filter": {
"$ref": "#/$defs/scope_filter"
},
"include_disputed": {
"type": "boolean",
"default": false
},
"include_rejected": {
"type": "boolean",
"default": false
},
"include_revoked": {
"type": "boolean",
"default": false
},
"include_deprecated": {
"type": "boolean",
"default": false
},
"include_fictional": {
"type": "boolean",
"default": false
},
"include_mythological": {
"type": "boolean",
"default": false
},
"include_symbolic": {
"type": "boolean",
"default": false
},
"include_speculative": {
"type": "boolean",
"default": false
},
"include_unknown_certainty": {
"type": "boolean",
"default": false
},
"require_labels_for_uncertainty": {
"type": "boolean",
"default": true
},
"require_labels_for_dispute": {
"type": "boolean",
"default": true
},
"require_labels_for_scoped_validation": {
"type": "boolean",
"default": true
},
"require_labels_for_authority": {
"type": "boolean",
"default": true
},
"require_traceability": {
"type": "boolean",
"default": true
},
"require_evidence": {
"type": "boolean",
"default": false
},
"require_validation_policy_ref": {
"type": "boolean",
"default": false
},
"require_authority_channel": {
"type": "boolean",
"default": false
},
"custom_rules": {
"type": "array",
"items": {
"$ref": "#/$defs/custom_rule"
},
"default": []
}
}
},
"custom_rule": {
"type": "object",
"additionalProperties": false,
"required": [
"rule_id",
"effect"
],
"properties": {
"rule_id": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string"
},
"target": {
"type": "string",
"enum": [
"artifact",
"assertion",
"authority_channel",
"scope",
"query_result",
"render_segment"
]
},
"condition": {
"type": "object",
"additionalProperties": true
},
"effect": {
"type": "string",
"enum": [
"allow",
"block",
"label",
"downgrade_visibility",
"require_user_choice",
"require_review"
]
},
"label": {
"type": "string"
}
}
},
"fallback_behavior": {
"type": "string",
"enum": [
"show_unavailable",
"omit_silently",
"omit_with_notice",
"show_with_labels",
"require_user_choice",
"error"
],
"default": "show_unavailable"
},
"rendering_policy": {
"type": "object",
"additionalProperties": false,
"properties": {
"show_labels": {
"type": "boolean",
"default": true
},
"show_authority_channel": {
"type": "boolean",
"default": true
},
"show_certainty_level": {
"type": "boolean",
"default": true
},
"show_validation_status": {
"type": "boolean",
"default": true
},
"show_recognition_status": {
"type": "boolean",
"default": true
},
"show_scope": {
"type": "boolean",
"default": true
},
"show_dispute_status": {
"type": "boolean",
"default": true
},
"show_fictional_or_mythological_mode": {
"type": "boolean",
"default": true
},
"show_trace_summary": {
"type": "boolean",
"default": false
},
"max_summary_length": {
"type": "integer",
"minimum": 1
}
}
},
"query_policy": {
"type": "object",
"additionalProperties": false,
"properties": {
"default_limit": {
"type": "integer",
"minimum": 1
},
"max_limit": {
"type": "integer",
"minimum": 1
},
"default_ordering": {
"type": "string",
"enum": [
"stable",
"authority_then_certainty",
"certainty_then_authority",
"source_order",
"created_at",
"updated_at"
]
},
"allow_cross_scope_queries": {
"type": "boolean",
"default": false
},
"allow_cross_authority_queries": {
"type": "boolean",
"default": false
},
"conflict_behavior": {
"type": "string",
"enum": [
"preserve_disagreement",
"authority_precedence",
"mark_disputed",
"exclude_conflict",
"require_reader_choice"
],
"default": "preserve_disagreement"
--- CHUNK END ---

--- CHUNK BEGIN ---
id=b2f82861c760:1051-1207
start=1051
end=1207
----
}
}
},
"federation_policy": {
"type": "object",
"additionalProperties": false,
"properties": {
"allow_federated_sources": {
"type": "boolean",
"default": true
},
"allowed_federations": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_ref"
},
"default": []
},
"blocked_federations": {
"type": "array",
"items": {
"$ref": "#/$defs/artifact_ref"
},
"default": []
},
"allow_disagreement": {
"type": "boolean",
"default": true
},
"composition_strategy": {
"type": "string",
"enum": [
"reader_policy_selected",
"authority_precedence",
"preserve_all",
"explicit_allow_deny"
],
"default": "reader_policy_selected"
}
}
},
"offline_policy": {
"type": "object",
"additionalProperties": false,
"properties": {
"allow_offline_use": {
"type": "boolean",
"default": true
},
"require_local_integrity_check": {
"type": "boolean",
"default": true
},
"require_signature_check": {
"type": "boolean",
"default": false
},
"allow_stale_packs": {
"type": "boolean",
"default": false
},
"max_staleness_seconds": {
"type": "integer",
"minimum": 0
},
"unavailable_behavior": {
"$ref": "#/$defs/fallback_behavior"
}
}
},
"revocation_policy": {
"type": "object",
"additionalProperties": false,
"properties": {
"exclude_revoked_artifacts": {
"type": "boolean",
"default": true
},
"exclude_revoked_assertions": {
"type": "boolean",
"default": true
},
"exclude_revoked_authority_channels": {
"type": "boolean",
"default": true
},
"exclude_revoked_keys": {
"type": "boolean",
"default": true
},
"show_revocation_labels": {
"type": "boolean",
"default": true
},
"allow_historical_revoked_material": {
"type": "boolean",
"default": false
}
}
},
"lineage_policy": {
"type": "object",
"additionalProperties": false,
"properties": {
"require_lineage": {
"type": "boolean",
"default": false
},
"preserve_source_identity": {
"type": "boolean",
"default": true
},
"show_lineage": {
"type": "boolean",
"default": false
},
"allow_forks": {
"type": "boolean",
"default": true
},
"allow_unrecognized_forks": {
"type": "boolean",
"default": false
}
}
},
"warning": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"enum": [
"POLICY_ALLOWS_UNCERTAIN_MATERIAL",
"POLICY_ALLOWS_DISPUTED_MATERIAL",
"POLICY_ALLOWS_FICTIONAL_MATERIAL",
"POLICY_ALLOWS_MYTHOLOGICAL_MATERIAL",
"POLICY_ALLOWS_UNRECOGNIZED_AUTHORITIES",
"POLICY_EXCLUDES_REFERENCE_MATERIAL",
"POLICY_REQUIRES_LABELS",
"POLICY_HAS_CUSTOM_RULES"
]
},
"message": {
"type": "string"
},
"path": {
"type": "string"
}
}
}
}
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/resolved-claim-ir.schema.json"
id=b6dfc4679611
kind=source
size=23628
lines=512
line_ref=1-512
chunks=2
chunk_refs=1-350,351-512
summary="Source file."

--- CHUNK BEGIN ---
id=b6dfc4679611:1-350
start=1
end=350
----
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/resolved-claim-ir.schema.json",
  "title": "Resolved Claim-IR v5",
  "description": "Resolved Claim-IR is a Kristal v5 extractor-resolution profile. It resolves Claim-IR outputs into scoped, provenance-bearing, certainty-bearing assertions that may be projected into Structured Epistemic State. It is not the universal Kristal v5 input boundary.",
  "type": "object",
  "additionalProperties": false,
  "required": ["schema_version", "artifact_type", "profile_role", "input", "resolution", "scope", "subject", "claims"],
  "properties": {
    "schema_version": { "type": "string", "const": "5.0" },
    "artifact_type": { "type": "string", "const": "resolved_claim_ir" },
    "profile_role": { "type": "string", "const": "extractor_resolution_profile" },
    "input": {
      "type": "object",
      "additionalProperties": false,
      "required": ["claim_ir_ref"],
      "properties": {
        "claim_ir_ref": { "$ref": "#/$defs/artifact_ref" },
        "claim_ir_hash": { "$ref": "#/$defs/hash_ref" },
        "source_refs": { "type": "array", "items": { "$ref": "#/$defs/source_ref" } },
        "notes": { "type": "string" }
      }
    },
    "resolution": {
      "type": "object",
      "additionalProperties": false,
      "required": ["run_id", "created_at", "resolver"],
      "properties": {
        "run_id": { "type": "string", "minLength": 1 },
        "created_at": { "type": "string", "format": "date-time" },
        "resolver": { "$ref": "#/$defs/resolver" },
        "limits": { "$ref": "#/$defs/resolution_limits" },
        "summary": { "$ref": "#/$defs/resolution_summary" },
        "notes": { "type": "string" }
      }
    },
    "scope": { "$ref": "#/$defs/scope" },
    "subject": { "$ref": "#/$defs/entity_resolution" },
    "claims": { "type": "array", "items": { "$ref": "#/$defs/resolved_claim" } },
    "structured_epistemic_state_projection": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "target_schema": { "type": "string", "const": "https://kristal.org/schemas/v5/structured-epistemic-state.schema.json" },
        "state_id": { "$ref": "#/$defs/sha256_uri" },
        "assertion_refs": { "type": "array", "items": { "$ref": "#/$defs/assertion_ref" } },
        "projection_policy_ref": { "$ref": "#/$defs/artifact_ref" },
        "notes": { "type": "string" }
      }
    },
    "warnings": { "type": "array", "items": { "$ref": "#/$defs/warning" } },
    "errors": { "type": "array", "items": { "$ref": "#/$defs/error" } },
    "extensions": { "type": "object", "additionalProperties": true }
  },
  "$defs": {
    "sha256_hex": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" },
    "sha256_uri": { "type": "string", "pattern": "^sha256:[0-9a-fA-F]{64}$" },
    "qid": { "type": "string", "pattern": "^Q[1-9][0-9]*$" },
    "pid": { "type": "string", "pattern": "^P[1-9][0-9]*$" },
    "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$" },
    "hash_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["alg", "value"],
      "properties": {
        "alg": { "type": "string", "const": "sha256" },
        "value": { "$ref": "#/$defs/sha256_hex" }
      }
    },
    "artifact_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "artifact_id": { "type": "string", "minLength": 1 },
        "artifact_type": { "type": "string", "minLength": 1 },
        "doc_id": { "type": "string", "minLength": 1 },
        "source_id": { "type": "string", "minLength": 1 },
        "source_url": { "type": "string", "format": "uri" },
        "run_id": { "type": "string", "minLength": 1 },
        "content_hash": { "$ref": "#/$defs/hash_ref" }
      },
      "anyOf": [
        { "required": ["artifact_id"] },
        { "required": ["doc_id"] },
        { "required": ["source_id"] },
        { "required": ["source_url"] }
      ]
    },
    "source_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "source_id": { "type": "string", "minLength": 1 },
        "source_url": { "type": "string", "format": "uri" },
        "title": { "type": "string" },
        "publisher": { "type": "string" },
        "retrieved_at": { "type": "string", "format": "date-time" },
        "content_hash": { "$ref": "#/$defs/hash_ref" }
      },
      "anyOf": [
        { "required": ["source_id"] },
        { "required": ["source_url"] }
      ]
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": ["domain"],
      "properties": {
        "domain": {
          "type": "string",
          "enum": ["general", "wikidata", "science", "health", "education", "heritage", "law", "policy", "technology", "environment", "culture", "mythology", "fiction", "research", "operations", "civic", "local_notes"]
        },
        "subdomain": { "type": ["string", "null"] },
        "jurisdiction": { "type": ["string", "null"] },
        "time_window": { "type": ["string", "null"] },
        "tenant_id": { "type": ["string", "null"] },
        "environment": { "type": ["string", "null"] },
        "language": { "type": ["string", "null"] }
      }
    },
    "authority_channel_id": { "type": "string", "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$" },
    "authority_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["authority_channel_id"],
      "properties": {
        "authority_channel_id": { "$ref": "#/$defs/authority_channel_id" },
        "name": { "type": "string" },
        "authority_registry_ref": { "$ref": "#/$defs/artifact_ref" }
      }
    },
    "validation_policy_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "policy_id": { "type": "string", "minLength": 1 },
        "policy_version": { "type": "string", "minLength": 1 },
        "policy_ref": { "$ref": "#/$defs/artifact_ref" }
      },
      "anyOf": [
        { "required": ["policy_id"] },
        { "required": ["policy_ref"] }
      ]
    },
    "resolver": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name", "version"],
      "properties": {
        "name": { "type": "string", "minLength": 1 },
        "version": { "type": "string", "minLength": 1 },
        "kind": { "type": "string", "enum": ["sentient", "hybrid", "human", "ai_agent", "service"] },
        "authority_channel": { "$ref": "#/$defs/authority_ref" },
        "model_ref": { "$ref": "#/$defs/artifact_ref" }
      }
    },
    "resolution_limits": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "timeout_ms": { "type": "integer", "minimum": 1 },
        "max_candidates": { "type": "integer", "minimum": 1 },
        "max_hops": { "type": "integer", "minimum": 0 },
        "max_calls": { "type": "integer", "minimum": 1 }
      }
    },
    "resolution_summary": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "entities_resolved": { "type": "integer", "minimum": 0 },
        "entities_ambiguous": { "type": "integer", "minimum": 0 },
        "entities_unresolved": { "type": "integer", "minimum": 0 },
        "properties_resolved": { "type": "integer", "minimum": 0 },
        "properties_ambiguous": { "type": "integer", "minimum": 0 },
        "properties_unresolved": { "type": "integer", "minimum": 0 },
        "claims_projectable_to_structured_epistemic_state": { "type": "integer", "minimum": 0 },
        "claims_blocked_from_projection": { "type": "integer", "minimum": 0 },
        "warnings": { "type": "integer", "minimum": 0 },
        "errors": { "type": "integer", "minimum": 0 }
      }
    },
    "resolution_status": { "type": "string", "enum": ["resolved", "ambiguous", "unresolved", "failed"] },
    "decision_method": { "type": "string", "enum": ["exact_match", "alias_match", "embedding_rank", "graph_lookup", "authority_registry_lookup", "judge", "human", "hybrid"] },
    "resolution_decision": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "method": { "$ref": "#/$defs/decision_method" },
        "score_threshold": { "type": "number", "minimum": 0, "maximum": 1 },
        "chosen_candidate_index": { "type": "integer", "minimum": 0 },
        "authority_channel": { "$ref": "#/$defs/authority_ref" },
        "notes": { "type": "string" }
      }
    },
    "entity_candidate": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "score"],
      "properties": {
        "id": { "oneOf": [{ "$ref": "#/$defs/qid" }, { "type": "string", "minLength": 1 }] },
        "score": { "type": "number", "minimum": 0, "maximum": 1 },
        "label": { "type": "string" },
        "description": { "type": "string" },
        "source": { "type": "string" },
        "authority_channel": { "$ref": "#/$defs/authority_ref" }
      }
    },
    "property_candidate": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "score"],
      "properties": {
        "id": { "oneOf": [{ "$ref": "#/$defs/pid" }, { "type": "string", "minLength": 1 }] },
        "score": { "type": "number", "minimum": 0, "maximum": 1 },
        "label": { "type": "string" },
        "description": { "type": "string" },
        "source": { "type": "string" },
        "authority_channel": { "$ref": "#/$defs/authority_ref" }
      }
    },
    "entity_resolution": {
      "type": "object",
      "additionalProperties": false,
      "required": ["status"],
      "properties": {
        "status": { "$ref": "#/$defs/resolution_status" },
        "qid": { "$ref": "#/$defs/qid" },
        "external_id": { "type": "string", "minLength": 1 },
        "surface": { "type": "string", "minLength": 1 },
        "lang": { "$ref": "#/$defs/lang" },
        "candidates": { "type": "array", "items": { "$ref": "#/$defs/entity_candidate" } },
        "decision": { "$ref": "#/$defs/resolution_decision" },
        "warnings": { "type": "array", "items": { "$ref": "#/$defs/warning" } }
      },
      "allOf": [
        {
          "if": { "properties": { "status": { "const": "resolved" } } },
          "then": { "anyOf": [{ "required": ["qid"] }, { "required": ["external_id"] }] }
        },
        {
          "if": { "properties": { "status": { "enum": ["ambiguous", "unresolved"] } } },
          "then": { "anyOf": [{ "required": ["surface"] }, { "required": ["candidates"] }] }
        }
      ]
    },
    "predicate_resolution": {
      "type": "object",
      "additionalProperties": false,
      "required": ["status"],
      "properties": {
        "status": { "$ref": "#/$defs/resolution_status" },
        "pid": { "$ref": "#/$defs/pid" },
        "external_id": { "type": "string", "minLength": 1 },
        "surface": { "type": "string", "minLength": 1 },
        "lang": { "$ref": "#/$defs/lang" },
        "candidates": { "type": "array", "items": { "$ref": "#/$defs/property_candidate" } },
        "decision": { "$ref": "#/$defs/resolution_decision" },
        "warnings": { "type": "array", "items": { "$ref": "#/$defs/warning" } }
      },
      "allOf": [
        {
          "if": { "properties": { "status": { "const": "resolved" } } },
          "then": { "anyOf": [{ "required": ["pid"] }, { "required": ["external_id"] }] }
        },
        {
          "if": { "properties": { "status": { "enum": ["ambiguous", "unresolved"] } } },
          "then": { "anyOf": [{ "required": ["surface"] }, { "required": ["candidates"] }] }
        }
      ]
    },
    "normalized_value": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "canonical_value": {},
        "unit_qid": { "$ref": "#/$defs/qid" },
        "precision": { "type": "string" },
        "normalization_policy_ref": { "$ref": "#/$defs/artifact_ref" },
        "notes": { "type": "string" }
      }
    },
    "object_value": {
      "type": "object",
      "additionalProperties": false,
      "required": ["kind", "value"],
      "properties": {
        "kind": { "type": "string", "enum": ["item", "string", "quantity", "time", "monolingual_text", "coord", "url", "external_id", "boolean", "null"] },
        "value": {},
        "normalized": { "$ref": "#/$defs/normalized_value" }
      },
      "allOf": [
        { "if": { "properties": { "kind": { "const": "item" } } }, "then": { "properties": { "value": { "$ref": "#/$defs/entity_resolution" } } } },
        { "if": { "properties": { "kind": { "const": "string" } } }, "then": { "properties": { "value": { "type": "string" } } } },
        { "if": { "properties": { "kind": { "const": "url" } } }, "then": { "properties": { "value": { "type": "string", "format": "uri" } } } },
        { "if": { "properties": { "kind": { "const": "external_id" } } }, "then": { "properties": { "value": { "type": "string" } } } },
        { "if": { "properties": { "kind": { "const": "boolean" } } }, "then": { "properties": { "value": { "type": "boolean" } } } },
        { "if": { "properties": { "kind": { "const": "null" } } }, "then": { "properties": { "value": { "type": "null" } } } },
        {
          "if": { "properties": { "kind": { "const": "quantity" } } },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": ["amount"],
                "properties": {
                  "amount": { "type": "number" },
                  "unit_qid": { "$ref": "#/$defs/qid" },
                  "unit_label": { "type": "string" },
                  "lower_bound": { "type": "number" },
                  "upper_bound": { "type": "number" }
                }
              }
            }
          }
        },
        {
          "if": { "properties": { "kind": { "const": "time" } } },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": ["iso8601"],
                "properties": {
                  "iso8601": { "type": "string", "pattern": "^-?\\d{4}(-\\d{2})?(-\\d{2})?(T.*)?$" },
                  "precision": { "type": "string", "enum": ["year", "month", "day", "hour", "minute", "second"] },
                  "calendar": { "type": "string" },
                  "timezone": { "type": "string" }
                }
              }
            }
          }
        },
        {
          "if": { "properties": { "kind": { "const": "monolingual_text" } } },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": ["text", "lang"],
                "properties": {
                  "text": { "type": "string" },
                  "lang": { "$ref": "#/$defs/lang" }
                }
              }
            }
--- CHUNK END ---

--- CHUNK BEGIN ---
id=b6dfc4679611:351-512
start=351
end=512
----
          }
        },
        {
          "if": { "properties": { "kind": { "const": "coord" } } },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": ["lat", "lon"],
                "properties": {
                  "lat": { "type": "number", "minimum": -90, "maximum": 90 },
                  "lon": { "type": "number", "minimum": -180, "maximum": 180 },
                  "globe": { "type": "string" }
                }
              }
            }
          }
        }
      ]
    },
    "evidence_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["source"],
      "properties": {
        "source": { "$ref": "#/$defs/source_ref" },
        "quote": { "type": "string" },
        "page": { "type": "integer", "minimum": 1 },
        "offsets": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "start_char": { "type": "integer", "minimum": 0 },
            "end_char": { "type": "integer", "minimum": 0 }
          }
        },
        "evidence_status": { "type": "string", "enum": ["provided", "missing", "weak", "sufficient", "contested"] }
      }
    },
    "uncertainty": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
        "method": { "type": "string" },
        "notes": { "type": "string" }
      }
    },
    "assertion_status": { "type": "string", "enum": ["hypothesis", "claimed", "sourced", "disputed", "reviewed", "validated", "rejected", "retracted", "superseded"] },
    "certainty_level": { "type": "string", "enum": ["unknown", "speculative", "low", "medium", "high", "established", "not_applicable"] },
    "validation_status": { "type": "string", "enum": ["not_evaluated", "in_review", "validated", "conditionally_validated", "disputed", "rejected", "revoked"] },
    "validated_as": { "type": "string", "enum": ["hypothesis", "claim", "sourced_claim", "reviewed_claim", "high_confidence_fact", "institutional_reference", "publisher_declaration", "technical_specification", "legal_or_policy_position", "mythological_corpus", "fictional_corpus", "symbolic_model", "disputed_position", "rejected_claim"] },
    "validation_summary": {
      "type": "object",
      "additionalProperties": false,
      "required": ["validation_status"],
      "properties": {
        "validation_status": { "$ref": "#/$defs/validation_status" },
        "validated_as": { "$ref": "#/$defs/validated_as" },
        "certainty_level": { "$ref": "#/$defs/certainty_level" },
        "authority_channel": { "$ref": "#/$defs/authority_ref" },
        "validation_policy_ref": { "$ref": "#/$defs/validation_policy_ref" },
        "scope": { "$ref": "#/$defs/scope" },
        "reason_codes": { "type": "array", "items": { "$ref": "#/$defs/reason_code" } },
        "validation_refs": { "type": "array", "items": { "$ref": "#/$defs/artifact_ref" } },
        "notes": { "type": "string" }
      },
      "allOf": [
        {
          "if": { "properties": { "validation_status": { "enum": ["validated", "conditionally_validated", "rejected"] } } },
          "then": { "required": ["validated_as", "authority_channel", "validation_policy_ref", "scope"] }
        }
      ]
    },
    "recognition_status": { "type": "string", "enum": ["recognized", "conditionally_recognized", "under_review", "disputed", "rejected", "deprecated", "revoked"] },
    "authority_recognition_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["recognition_status", "authority_channel"],
      "properties": {
        "recognition_id": { "$ref": "#/$defs/sha256_uri" },
        "recognition_status": { "$ref": "#/$defs/recognition_status" },
        "recognized_as": { "$ref": "#/$defs/validated_as" },
        "authority_channel": { "$ref": "#/$defs/authority_ref" },
        "scope": { "$ref": "#/$defs/scope" },
        "validation_policy_ref": { "$ref": "#/$defs/validation_policy_ref" },
        "recognition_ref": { "$ref": "#/$defs/artifact_ref" }
      }
    },
    "assertion_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["assertion_id"],
      "properties": {
        "assertion_id": { "$ref": "#/$defs/sha256_uri" },
        "source_claim_id": { "type": "string", "minLength": 1 },
        "claim_id": { "type": "string", "minLength": 1 }
      }
    },
    "qualifier": {
      "type": "object",
      "additionalProperties": false,
      "required": ["predicate", "object"],
      "properties": {
        "predicate": { "$ref": "#/$defs/predicate_resolution" },
        "object": { "$ref": "#/$defs/object_value" },
        "scope": { "$ref": "#/$defs/scope" },
        "notes": { "type": "string" }
      }
    },
    "resolved_claim": {
      "type": "object",
      "additionalProperties": false,
      "required": ["claim_id", "predicate", "object", "assertion_status", "certainty_level", "validation"],
      "properties": {
        "claim_id": { "type": "string", "minLength": 1 },
        "assertion_id": { "$ref": "#/$defs/sha256_uri" },
        "source_claim_id": { "type": "string", "minLength": 1 },
        "subject": { "$ref": "#/$defs/entity_resolution" },
        "predicate": { "$ref": "#/$defs/predicate_resolution" },
        "object": { "$ref": "#/$defs/object_value" },
        "qualifiers": { "type": "array", "items": { "$ref": "#/$defs/qualifier" } },
        "evidence": { "type": "array", "items": { "$ref": "#/$defs/evidence_ref" } },
        "provenance_refs": { "type": "array", "items": { "$ref": "#/$defs/artifact_ref" } },
        "authority_recognition_refs": { "type": "array", "items": { "$ref": "#/$defs/authority_recognition_ref" } },
        "assertion_status": { "$ref": "#/$defs/assertion_status" },
        "certainty_level": { "$ref": "#/$defs/certainty_level" },
        "validation": { "$ref": "#/$defs/validation_summary" },
        "uncertainty": { "$ref": "#/$defs/uncertainty" },
        "projection_status": { "type": "string", "enum": ["projectable", "projected", "blocked", "requires_review", "not_applicable"] },
        "notes": { "type": "string" }
      }
    },
    "reason_code": {
      "type": "string",
      "enum": ["schema_valid", "schema_invalid", "provenance_sufficient", "provenance_insufficient", "evidence_sufficient", "evidence_insufficient", "authority_recognized", "authority_not_recognized", "scope_mismatch", "policy_satisfied", "policy_failed", "signature_valid", "signature_invalid", "hash_valid", "hash_invalid", "conflict_detected", "disagreement_preserved", "certainty_too_low_for_policy", "rejected_by_authority_channel", "revoked_by_authority_channel"]
    },
    "warning": {
      "type": "object",
      "additionalProperties": false,
      "required": ["code", "message"],
      "properties": {
        "code": { "type": "string", "enum": ["AMBIGUOUS_SUBJECT", "AMBIGUOUS_PREDICATE", "UNRESOLVED_QID", "UNRESOLVED_PID", "VALUE_NORMALIZATION_NEEDED", "LOW_CONFIDENCE_RESOLUTION", "LIMIT_REACHED", "EVIDENCE_WEAK", "SCOPE_MISSING", "AUTHORITY_CHANNEL_MISSING", "VALIDATION_SCOPE_MISSING", "CERTAINTY_UNSPECIFIED", "PROJECTION_REQUIRES_REVIEW"] },
        "message": { "type": "string" },
        "path": { "type": "string" },
        "reason_code": { "$ref": "#/$defs/reason_code" }
      }
    },
    "error": {
      "type": "object",
      "additionalProperties": false,
      "required": ["code", "message"],
      "properties": {
        "code": { "type": "string", "enum": ["SCHEMA_INVALID", "RESOLUTION_FAILED", "INVALID_VALUE_SHAPE", "UNSUPPORTED_KIND", "POLICY_REF_INVALID", "SCOPE_INVALID", "AUTHORITY_REF_INVALID", "PROJECTION_BLOCKED"] },
        "message": { "type": "string" },
        "path": { "type": "string" },
        "reason_code": { "$ref": "#/$defs/reason_code" }
      }
    }
  }
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/revocations.schema.json"
id=4905af33cbbc
kind=source
size=25030
lines=1025
line_ref=1-1025
chunks=3
chunk_refs=1-350,351-700,701-1025
summary="Source file."

--- CHUNK BEGIN ---
id=4905af33cbbc:1-350
start=1
end=350
----
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/revocations.schema.json",
  "title": "Kristal Revocations v5",
  "description": "A Kristal v5 revocations artifact records scoped revocation, suspension, deprecation, or replacement decisions for keys, authority channels, artifacts, shards, assertions, validation decisions, recognitions, runtime packs, federation manifests, and reader policies. Revocation does not erase lineage; it changes the status and reader-policy treatment of the target.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "artifact_type",
    "created_at",
    "revocations_id",
    "canonicalization_profile",
    "canonicalization_version",
    "issuer_authority_channel",
    "content_hash",
    "scope",
    "entries"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "5.0"
    },
    "artifact_type": {
      "type": "string",
      "const": "revocations"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "revocations_id": {
      "$ref": "#/$defs/sha256_uri"
    },
    "canonicalization_profile": {
      "type": "string",
      "const": "kristal.v5:jcs-rfc8785"
    },
    "canonicalization_version": {
      "type": "string",
      "const": "1"
    },
    "issuer_authority_channel": {
      "$ref": "#/$defs/authority_ref"
    },
    "content_hash": {
      "$ref": "#/$defs/hash_ref"
    },
    "hash_target_policy": {
      "$ref": "#/$defs/hash_target_policy"
    },
    "scope": {
      "$ref": "#/$defs/scope"
    },
    "revocation_policy_ref": {
      "$ref": "#/$defs/policy_ref"
    },
    "entries": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/revocation_entry"
      }
    },
    "lineage": {
      "$ref": "#/$defs/lineage"
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/warning"
      },
      "default": []
    },
    "signatures": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/signature"
      },
      "default": []
    },
    "extensions": {
      "type": "object",
      "additionalProperties": true,
      "default": {}
    }
  },
  "$defs": {
    "sha256_hex": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}$"
    },
    "sha256_uri": {
      "type": "string",
      "pattern": "^sha256:[0-9a-fA-F]{64}$"
    },
    "hash_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["alg", "value"],
      "properties": {
        "alg": {
          "type": "string",
          "const": "sha256"
        },
        "value": {
          "$ref": "#/$defs/sha256_hex"
        }
      }
    },
    "hash_target_policy": {
      "type": "object",
      "additionalProperties": false,
      "required": ["exclude_fields"],
      "properties": {
        "exclude_fields": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "revocations_id",
              "content_hash",
              "signatures"
            ]
          },
          "uniqueItems": true
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": ["domain"],
      "properties": {
        "domain": {
          "type": "string",
          "enum": [
            "general",
            "wikidata",
            "science",
            "health",
            "education",
            "heritage",
            "law",
            "policy",
            "technology",
            "environment",
            "culture",
            "mythology",
            "fiction",
            "research",
            "operations",
            "civic",
            "local_notes"
          ]
        },
        "subdomain": {
          "type": ["string", "null"]
        },
        "jurisdiction": {
          "type": ["string", "null"]
        },
        "time_window": {
          "type": ["string", "null"]
        },
        "tenant_id": {
          "type": ["string", "null"]
        },
        "environment": {
          "type": ["string", "null"]
        },
        "language": {
          "type": ["string", "null"]
        }
      }
    },
    "authority_channel_id": {
      "type": "string",
      "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
    },
    "authority_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["authority_channel_id"],
      "properties": {
        "authority_channel_id": {
          "$ref": "#/$defs/authority_channel_id"
        },
        "name": {
          "type": "string"
        },
        "authority_registry_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      }
    },
    "artifact_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "artifact_id": {
          "type": "string",
          "minLength": 1
        },
        "artifact_type": {
          "type": "string",
          "minLength": 1
        },
        "uri": {
          "type": "string",
          "format": "uri"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "anyOf": [
        {
          "required": ["artifact_id"]
        },
        {
          "required": ["uri"]
        },
        {
          "required": ["content_hash"]
        }
      ]
    },
    "policy_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "policy_id": {
          "type": "string",
          "minLength": 1
        },
        "policy_version": {
          "type": "string",
          "minLength": 1
        },
        "policy_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      },
      "anyOf": [
        {
          "required": ["policy_id"]
        },
        {
          "required": ["policy_ref"]
        }
      ]
    },
    "signature": {
      "type": "object",
      "additionalProperties": false,
      "required": ["key_id", "alg", "signature", "created_at"],
      "properties": {
        "key_id": {
          "type": "string",
          "minLength": 1
        },
        "alg": {
          "type": "string",
          "const": "ed25519"
        },
        "signature": {
          "type": "string",
          "minLength": 1
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      }
    },
    "target_level": {
      "type": "string",
      "enum": [
        "key",
        "authority_channel",
        "artifact",
        "shard",
        "assertion",
        "validation_decision",
        "authority_recognition",
        "reader_policy",
        "runtime_pack",
        "federation",
        "dataset"
      ]
    },
    "revocation_kind": {
      "type": "string",
      "enum": [
        "key_id",
        "authority_channel_id",
        "artifact_id",
        "shard_id",
        "assertion_id",
        "validation_decision_id",
        "recognition_id",
        "reader_policy_id",
        "runtime_pack_id",
        "federation_id",
        "dataset_id"
      ]
    },
    "revocation_status": {
      "type": "string",
      "enum": [
        "revoked",
        "conditionally_revoked",
        "suspended",
        "deprecated",
        "superseded",
        "expired",
        "reinstated"
      ]
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "planned_key_rotation",
        "key_compromise",
        "key_lost",
        "authority_suspended",
        "authority_revoked",
        "temporary_suspension_pending_review",
        "post_publication_validation_revoked",
        "validation_decision_revoked",
        "recognition_revoked",
        "artifact_integrity_failure",
        "artifact_superseded",
        "artifact_deprecated",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=4905af33cbbc:351-700
start=351
end=700
----
        "scope_mismatch",
        "policy_failed",
        "policy_superseded",
        "reader_policy_revoked",
        "runtime_pack_revoked",
        "federation_manifest_revoked",
        "publisher_request",
        "legal_or_compliance_request",
        "administrative_correction",
        "other"
      ]
    },
    "target_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "key_id": {
          "type": "string",
          "minLength": 1
        },
        "authority_channel_id": {
          "$ref": "#/$defs/authority_channel_id"
        },
        "name": {
          "type": "string"
        },
        "artifact_id": {
          "type": "string",
          "minLength": 1
        },
        "artifact_type": {
          "type": "string",
          "minLength": 1
        },
        "shard_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "assertion_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "validation_decision_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "recognition_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "reader_policy_id": {
          "type": "string",
          "pattern": "^reader_policy:[a-z0-9][a-z0-9._:-]*$"
        },
        "runtime_pack_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "federation_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "dataset_id": {
          "type": "string",
          "minLength": 1
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        },
        "artifact_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      },
      "anyOf": [
        {
          "required": ["key_id"]
        },
        {
          "required": ["authority_channel_id"]
        },
        {
          "required": ["artifact_id"]
        },
        {
          "required": ["shard_id"]
        },
        {
          "required": ["assertion_id"]
        },
        {
          "required": ["validation_decision_id"]
        },
        {
          "required": ["recognition_id"]
        },
        {
          "required": ["reader_policy_id"]
        },
        {
          "required": ["runtime_pack_id"]
        },
        {
          "required": ["federation_id"]
        },
        {
          "required": ["dataset_id"]
        },
        {
          "required": ["artifact_ref"]
        }
      ]
    },
    "replacement_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "key_id": {
          "type": "string",
          "minLength": 1
        },
        "authority_channel_id": {
          "$ref": "#/$defs/authority_channel_id"
        },
        "artifact_id": {
          "type": "string",
          "minLength": 1
        },
        "artifact_type": {
          "type": "string",
          "minLength": 1
        },
        "validation_decision_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "recognition_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "reader_policy_id": {
          "type": "string",
          "pattern": "^reader_policy:[a-z0-9][a-z0-9._:-]*$"
        },
        "runtime_pack_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "federation_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "artifact_ref": {
          "$ref": "#/$defs/artifact_ref"
        },
        "notes": {
          "type": "string"
        }
      },
      "anyOf": [
        {
          "required": ["key_id"]
        },
        {
          "required": ["authority_channel_id"]
        },
        {
          "required": ["artifact_id"]
        },
        {
          "required": ["validation_decision_id"]
        },
        {
          "required": ["recognition_id"]
        },
        {
          "required": ["reader_policy_id"]
        },
        {
          "required": ["runtime_pack_id"]
        },
        {
          "required": ["federation_id"]
        },
        {
          "required": ["artifact_ref"]
        }
      ]
    },
    "revocation_effect": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "new_signatures_allowed": {
          "type": "boolean"
        },
        "new_recognitions_allowed": {
          "type": "boolean"
        },
        "new_validation_decisions_allowed": {
          "type": "boolean"
        },
        "new_distribution_allowed": {
          "type": "boolean"
        },
        "new_runtime_activation_allowed": {
          "type": "boolean"
        },
        "historical_signatures_remain_verifiable": {
          "type": "boolean"
        },
        "existing_recognitions_remain_visible": {
          "type": "boolean"
        },
        "existing_traces_remain_visible": {
          "type": "boolean"
        },
        "reader_policy_effect": {
          "type": "string",
          "enum": [
            "exclude",
            "label_only",
            "mark_as_revoked",
            "mark_as_deprecated",
            "mark_as_superseded",
            "mark_as_suspended",
            "exclude_or_label_material_recognized_only_by_this_authority_channel_when_policy_disallows_conditionally_revoked_authorities",
            "mark_as_revoked_and_exclude_under_reader_policies_that_disallow_revoked_artifacts",
            "treat_new_artifacts_signed_only_by_this_key_as_untrusted_for_selected_authority_channel",
            "custom"
          ]
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "revocation_entry": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "entry_id",
        "target_level",
        "kind",
        "target",
        "revocation_status",
        "revoked_at",
        "effective_at",
        "reason_code",
        "reason"
      ],
      "properties": {
        "entry_id": {
          "type": "string",
          "minLength": 1
        },
        "target_level": {
          "$ref": "#/$defs/target_level"
        },
        "kind": {
          "$ref": "#/$defs/revocation_kind"
        },
        "target": {
          "$ref": "#/$defs/target_ref"
        },
        "revocation_status": {
          "$ref": "#/$defs/revocation_status"
        },
        "revoked_at": {
          "type": "string",
          "format": "date-time"
        },
        "effective_at": {
          "type": "string",
          "format": "date-time"
        },
        "expires_at": {
          "type": ["string", "null"],
          "format": "date-time"
        },
        "reason_code": {
          "$ref": "#/$defs/reason_code"
        },
        "reason": {
          "type": "string",
          "minLength": 1
        },
        "replacement_ref": {
          "$ref": "#/$defs/replacement_ref"
        },
        "validation_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/validation_decision_ref"
          },
          "default": []
        },
        "recognition_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/recognition_ref"
          },
          "default": []
        },
        "evidence_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/evidence_ref"
          },
          "default": []
        },
        "effect": {
          "$ref": "#/$defs/revocation_effect"
        },
        "issued_by": {
          "$ref": "#/$defs/authority_ref"
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "notes": {
          "type": "string"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "kind": {
                "const": "key_id"
              }
            }
          },
          "then": {
            "properties": {
              "target_level": {
                "const": "key"
              },
              "target": {
                "required": ["key_id"]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "authority_channel_id"
              }
            }
          },
          "then": {
            "properties": {
              "target_level": {
                "const": "authority_channel"
              },
              "target": {
                "required": ["authority_channel_id"]
              }
            }
--- CHUNK END ---

--- CHUNK BEGIN ---
id=4905af33cbbc:701-1025
start=701
end=1025
----
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "artifact_id"
              }
            }
          },
          "then": {
            "properties": {
              "target_level": {
                "const": "artifact"
              },
              "target": {
                "required": ["artifact_id"]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "assertion_id"
              }
            }
          },
          "then": {
            "properties": {
              "target_level": {
                "const": "assertion"
              },
              "target": {
                "required": ["assertion_id"]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "validation_decision_id"
              }
            }
          },
          "then": {
            "properties": {
              "target_level": {
                "const": "validation_decision"
              },
              "target": {
                "required": ["validation_decision_id"]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "recognition_id"
              }
            }
          },
          "then": {
            "properties": {
              "target_level": {
                "const": "authority_recognition"
              },
              "target": {
                "required": ["recognition_id"]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "runtime_pack_id"
              }
            }
          },
          "then": {
            "properties": {
              "target_level": {
                "const": "runtime_pack"
              },
              "target": {
                "required": ["runtime_pack_id"]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "federation_id"
              }
            }
          },
          "then": {
            "properties": {
              "target_level": {
                "const": "federation"
              },
              "target": {
                "required": ["federation_id"]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "reader_policy_id"
              }
            }
          },
          "then": {
            "properties": {
              "target_level": {
                "const": "reader_policy"
              },
              "target": {
                "required": ["reader_policy_id"]
              }
            }
          }
        }
      ]
    },
    "validation_decision_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["validation_decision_id"],
      "properties": {
        "validation_decision_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "validation_status": {
          "type": "string",
          "enum": [
            "not_evaluated",
            "in_review",
            "validated",
            "conditionally_validated",
            "disputed",
            "rejected",
            "revoked"
          ]
        },
        "artifact_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      }
    },
    "recognition_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["recognition_id"],
      "properties": {
        "recognition_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "recognition_status": {
          "type": "string",
          "enum": [
            "recognized",
            "conditionally_recognized",
            "under_review",
            "disputed",
            "rejected",
            "deprecated",
            "revoked"
          ]
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        },
        "artifact_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      }
    },
    "evidence_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "evidence_id": {
          "type": "string",
          "minLength": 1
        },
        "source_ref": {
          "$ref": "#/$defs/source_ref"
        },
        "quote": {
          "type": "string"
        },
        "section": {
          "type": "string"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        }
      },
      "anyOf": [
        {
          "required": ["evidence_id"]
        },
        {
          "required": ["source_ref"]
        },
        {
          "required": ["content_hash"]
        }
      ]
    },
    "source_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "source_id": {
          "type": "string",
          "minLength": 1
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        },
        "title": {
          "type": "string"
        },
        "publisher": {
          "type": "string"
        },
        "retrieved_at": {
          "type": "string",
          "format": "date-time"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      },
      "anyOf": [
        {
          "required": ["source_id"]
        },
        {
          "required": ["source_url"]
        },
        {
          "required": ["content_hash"]
        }
      ]
    },
    "lineage": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "source_artifacts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        },
        "supersedes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        },
        "derived_from": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        },
        "policy_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/policy_ref"
          },
          "default": []
        }
      }
    },
    "warning": {
      "type": "object",
      "additionalProperties": false,
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "TARGET_ALREADY_REVOKED",
            "TARGET_NOT_FOUND",
            "TEMPORARY_REVOCATION",
            "REVOCATION_EXPIRES",
            "REPLACEMENT_DECLARED",
            "AUTHORITY_SCOPE_LIMITED",
            "READER_POLICY_EFFECT_DECLARED"
          ]
        },
        "message": {
          "type": "string"
        },
        "path": {
          "type": "string"
        }
      }
    }
  }
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/runtime-pack-manifest.schema.json"
id=95d2a3ba4b79
kind=source
size=23383
lines=844
line_ref=1-844
chunks=3
chunk_refs=1-350,351-700,701-844
summary="Source file."

--- CHUNK BEGIN ---
id=95d2a3ba4b79:1-350
start=1
end=350
----
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/runtime-pack-manifest.schema.json",
  "title": "Kristal v5 Runtime Pack Manifest",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "artifact_type",
    "runtime_pack_id",
    "runtime_pack_version",
    "created_at",
    "source_exchange_ref",
    "source_artifact_status",
    "compiler",
    "build",
    "policies",
    "reader_policy_refs",
    "query_contract_ref",
    "files",
    "integrity"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "5.0",
      "description": "Kristal schema version."
    },
    "artifact_type": {
      "type": "string",
      "const": "runtime_pack_manifest",
      "description": "Artifact type discriminator."
    },
    "runtime_pack_id": {
      "$ref": "#/$defs/sha256_id",
      "description": "Content-addressed ID for this runtime pack. Preferred form: sha256:<hex>."
    },
    "runtime_pack_version": {
      "type": "string",
      "description": "Runtime Pack manifest version.",
      "pattern": "^5\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-[0-9A-Za-z.-]+)?$"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp when the runtime pack was produced. MUST NOT affect any content-addressed IDs unless an explicit profile declares otherwise."
    },
    "profiles": {
      "type": "array",
      "description": "Optional standardized profiles this pack claims conformance to.",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "uniqueItems": true
    },
    "source_exchange_ref": {
      "type": "object",
      "description": "Reference to the Kristal Exchange this pack was compiled from.",
      "additionalProperties": false,
      "required": [
        "exchange_id",
        "artifact_type"
      ],
      "properties": {
        "exchange_id": {
          "$ref": "#/$defs/sha256_id",
          "description": "Content-addressed ID of the Kristal Exchange this pack was compiled from."
        },
        "artifact_type": {
          "type": "string",
          "enum": [
            "working_exchange",
            "reference_exchange"
          ],
          "description": "Type of Exchange artifact used as the source for this Runtime Pack."
        },
        "exchange_manifest_hash": {
          "$ref": "#/$defs/sha256_id",
          "description": "Optional content hash of the Exchange manifest referenced by this pack."
        },
        "exchange_version": {
          "type": "string",
          "description": "Optional human version label for the source Exchange.",
          "minLength": 1
        },
        "scope": {
          "$ref": "#/$defs/scope"
        }
      }
    },
    "source_artifact_status": {
      "type": "string",
      "description": "Status of the source Exchange at the time this Runtime Pack was built.",
      "enum": [
        "working",
        "under_review",
        "recognized",
        "reference",
        "deprecated",
        "superseded",
        "revoked"
      ]
    },
    "validation_refs": {
      "type": "array",
      "description": "Validation decisions associated with the source Exchange, shard, or selected assertions.",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "uniqueItems": true
    },
    "authority_recognition_refs": {
      "type": "array",
      "description": "Authority recognition records associated with the source Exchange, shard, Runtime Pack, or selected assertions.",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "uniqueItems": true
    },
    "compiler": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "version"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "version": {
          "type": "string",
          "minLength": 1
        },
        "git_commit": {
          "type": "string",
          "description": "Optional compiler source revision.",
          "minLength": 7
        },
        "build_platform": {
          "type": "string",
          "description": "Optional platform identifier, for example linux-x86_64.",
          "minLength": 1
        }
      }
    },
    "build": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "build_id",
        "deterministic",
        "canonicalization_profile",
        "canonicalization_version",
        "config_hash",
        "compile_status"
      ],
      "properties": {
        "build_id": {
          "type": "string",
          "description": "Opaque build correlation ID.",
          "minLength": 8
        },
        "deterministic": {
          "type": "boolean",
          "description": "True if this pack claims deterministic and reproducible build behavior under recorded policies.",
          "const": true
        },
        "canonicalization_profile": {
          "type": "string",
          "description": "Canonicalization profile identifier used for hashed JSON objects.",
          "const": "kristal.v5:jcs-rfc8785"
        },
        "canonicalization_version": {
          "type": "string",
          "description": "Canonicalization profile version identifier.",
          "const": "1"
        },
        "config_hash": {
          "$ref": "#/$defs/sha256_id",
          "description": "Content hash of the compiler configuration that affects outputs."
        },
        "compile_status": {
          "type": "string",
          "description": "Compilation status for this Runtime Pack.",
          "enum": [
            "succeeded",
            "failed",
            "partial"
          ]
        },
        "validation_status": {
          "$ref": "#/$defs/validation_status"
        },
        "recognition_status": {
          "$ref": "#/$defs/recognition_status"
        },
        "publication_status": {
          "type": "string",
          "enum": [
            "not_published",
            "published",
            "blocked"
          ]
        },
        "activation_status": {
          "type": "string",
          "enum": [
            "not_applicable",
            "activated",
            "blocked",
            "revoked"
          ]
        },
        "reason_codes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/reason_code"
          },
          "uniqueItems": true
        }
      }
    },
    "policies": {
      "type": "object",
      "description": "Portable policies and parameters sufficient to reproduce the Runtime Pack.",
      "additionalProperties": false,
      "required": [
        "data_ordering",
        "row_grouping",
        "membership_filter",
        "bitmap"
      ],
      "properties": {
        "data_ordering": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "policy"
          ],
          "properties": {
            "policy": {
              "type": "string",
              "description": "Portable ordering policy for deterministic output.",
              "enum": [
                "qid_pid_statement_id_asc",
                "lexicographic_sop_asc",
                "source_order_preserved",
                "none"
              ]
            },
            "notes": {
              "type": "string"
            }
          }
        },
        "row_grouping": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "policy"
          ],
          "properties": {
            "policy": {
              "type": "string",
              "description": "Portable row-group sizing policy for deterministic layout.",
              "enum": [
                "fixed_rows_100k",
                "fixed_rows_1m",
                "fixed_bytes_128mb"
              ]
            },
            "notes": {
              "type": "string"
            }
          }
        },
        "membership_filter": {
          "description": "Membership filter policy used by the pack, if any, and the parameters required to reproduce it.",
          "oneOf": [
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "kind"
              ],
              "properties": {
                "kind": {
                  "type": "string",
                  "const": "none"
                }
              }
            },
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "kind",
                "seed",
                "bits_per_key"
              ],
              "properties": {
                "kind": {
                  "type": "string",
                  "const": "bloom"
                },
                "seed": {
                  "type": "integer",
                  "minimum": 0
                },
                "bits_per_key": {
                  "type": "integer",
                  "minimum": 1
                },
                "hash_functions": {
                  "type": "integer",
                  "minimum": 1
                },
                "notes": {
                  "type": "string"
                }
              }
            },
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "kind",
                "seed",
                "fingerprint_bits",
                "load_factor"
              ],
              "properties": {
                "kind": {
                  "type": "string",
                  "const": "cuckoo"
                },
                "seed": {
                  "type": "integer",
                  "minimum": 0
                },
                "fingerprint_bits": {
                  "type": "integer",
                  "minimum": 4
                },
                "load_factor": {
                  "type": "number",
                  "minimum": 0.01,
--- CHUNK END ---

--- CHUNK BEGIN ---
id=95d2a3ba4b79:351-700
start=351
end=700
----
                  "maximum": 0.99
                },
                "notes": {
                  "type": "string"
                }
              }
            },
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "kind",
                "seed",
                "bits"
              ],
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "xor8",
                    "xor16"
                  ]
                },
                "seed": {
                  "type": "integer",
                  "minimum": 0
                },
                "bits": {
                  "type": "integer",
                  "enum": [
                    8,
                    16
                  ]
                },
                "notes": {
                  "type": "string"
                }
              }
            }
          ]
        },
        "bitmap": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "format",
            "run_optimize"
          ],
          "properties": {
            "format": {
              "type": "string",
              "description": "Portable bitmap or index encoding convention for deterministic runtime behavior.",
              "enum": [
                "roaring",
                "roaring_run_optimized"
              ]
            },
            "run_optimize": {
              "type": "boolean",
              "description": "Whether run optimization was applied."
            },
            "notes": {
              "type": "string"
            }
          }
        },
        "parquet": {
          "type": "object",
          "description": "Parquet-level policies that affect deterministic output. Keep to portable, enumerated values.",
          "additionalProperties": false,
          "properties": {
            "compression": {
              "type": "string",
              "enum": [
                "zstd",
                "snappy",
                "gzip",
                "none"
              ]
            },
            "dictionary_encoding": {
              "type": "boolean"
            },
            "statistics": {
              "type": "string",
              "enum": [
                "none",
                "page",
                "rowgroup"
              ]
            },
            "bloom_filters": {
              "type": "object",
              "description": "Optional Parquet Bloom filter configuration.",
              "additionalProperties": false,
              "required": [
                "enabled"
              ],
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "fpp": {
                  "type": "number",
                  "minimum": 0.0000001,
                  "maximum": 0.5,
                  "description": "False positive probability target."
                },
                "columns": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  },
                  "uniqueItems": true
                }
              }
            }
          }
        },
        "reader_policy_selection": {
          "type": "object",
          "description": "Optional policy-selection metadata used to build or filter this pack.",
          "additionalProperties": false,
          "properties": {
            "mode": {
              "$ref": "#/$defs/reader_mode"
            },
            "include_disputed": {
              "type": "boolean"
            },
            "include_fictional": {
              "type": "boolean"
            },
            "include_mythological": {
              "type": "boolean"
            },
            "notes": {
              "type": "string"
            }
          }
        }
      }
    },
    "reader_policy_refs": {
      "type": "array",
      "description": "Reader policies supported by or associated with this Runtime Pack.",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "uniqueItems": true
    },
    "query_contract_ref": {
      "type": "object",
      "description": "Reference to the offline query contract supported by this pack.",
      "additionalProperties": false,
      "required": [
        "contract_id"
      ],
      "properties": {
        "contract_id": {
          "type": "string",
          "minLength": 1
        },
        "contract_hash": {
          "$ref": "#/$defs/sha256_id"
        },
        "contract_version": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "query_capabilities": {
      "type": "object",
      "description": "Optional declaration of the offline query capabilities supported by this pack.",
      "additionalProperties": false,
      "properties": {
        "supports_pagination": {
          "type": "boolean"
        },
        "supports_cardinality_estimates": {
          "type": "boolean"
        },
        "supports_authority_channel_filter": {
          "type": "boolean"
        },
        "supports_validation_status_filter": {
          "type": "boolean"
        },
        "supports_certainty_level_filter": {
          "type": "boolean"
        },
        "supports_validated_as_filter": {
          "type": "boolean"
        },
        "supports_scope_filter": {
          "type": "boolean"
        },
        "supports_disagreement_view": {
          "type": "boolean"
        }
      }
    },
    "files": {
      "type": "array",
      "minItems": 1,
      "description": "All physical files included in the Runtime Pack, with integrity metadata.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "path",
          "role",
          "sha256",
          "size_bytes"
        ],
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1,
            "description": "Relative path within the Runtime Pack container."
          },
          "role": {
            "type": "string",
            "enum": [
              "parquet_data",
              "bitmap_index",
              "membership_filter",
              "dictionary",
              "metadata",
              "query_index",
              "reader_policy",
              "validation_index",
              "recognition_index",
              "certainty_index",
              "scope_index",
              "other"
            ]
          },
          "sha256": {
            "$ref": "#/$defs/sha256_hex"
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 0
          },
          "mime_type": {
            "type": "string"
          }
        }
      }
    },
    "integrity": {
      "type": "object",
      "description": "Integrity metadata for the pack as a whole.",
      "additionalProperties": false,
      "required": [
        "hash_alg"
      ],
      "properties": {
        "hash_alg": {
          "type": "string",
          "const": "sha256"
        },
        "pack_hash": {
          "$ref": "#/$defs/sha256_id",
          "description": "Optional content hash of the full pack container."
        },
        "manifest_hash": {
          "$ref": "#/$defs/sha256_id",
          "description": "Optional hash of this manifest content excluding signatures."
        }
      }
    },
    "signatures": {
      "type": "array",
      "description": "Optional signatures over declared hashed material. When signatures are declared, verification requirements are defined by the applicable trust-root and reader or activation policy.",
      "items": {
        "$ref": "#/$defs/signature"
      }
    },
    "extensions": {
      "type": "object",
      "description": "Optional extension object for profile-specific metadata.",
      "additionalProperties": true
    }
  },
  "$defs": {
    "sha256_hex": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "sha256_prefixed": {
      "type": "string",
      "pattern": "^sha256:[a-f0-9]{64}$"
    },
    "sha256_id": {
      "oneOf": [
        {
          "$ref": "#/$defs/sha256_prefixed"
        },
        {
          "$ref": "#/$defs/sha256_hex"
        }
      ]
    },
    "artifact_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "$ref": "#/$defs/sha256_id"
        },
        "artifact_type": {
          "type": "string",
          "minLength": 1
        },
        "hash": {
          "$ref": "#/$defs/sha256_id"
        },
        "uri": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "domain"
      ],
      "properties": {
        "domain": {
          "type": "string",
          "enum": [
            "general",
            "wikidata",
            "science",
            "health",
            "education",
            "heritage",
            "law",
            "policy",
            "technology",
            "environment",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=95d2a3ba4b79:701-844
start=701
end=844
----
            "culture",
            "mythology",
            "fiction",
            "research",
            "operations",
            "civic",
            "local_notes"
          ]
        },
        "subdomain": {
          "type": [
            "string",
            "null"
          ]
        },
        "jurisdiction": {
          "type": [
            "string",
            "null"
          ]
        },
        "time_window": {
          "type": [
            "string",
            "null"
          ]
        },
        "tenant_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "environment": {
          "type": [
            "string",
            "null"
          ]
        },
        "language": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "validation_status": {
      "type": "string",
      "enum": [
        "not_evaluated",
        "in_review",
        "validated",
        "conditionally_validated",
        "disputed",
        "rejected",
        "revoked"
      ]
    },
    "recognition_status": {
      "type": "string",
      "enum": [
        "none",
        "recognized",
        "conditionally_recognized",
        "under_review",
        "disputed",
        "rejected",
        "deprecated",
        "revoked"
      ]
    },
    "reader_mode": {
      "type": "string",
      "enum": [
        "reference_only",
        "validated_only",
        "high_certainty_only",
        "research",
        "creative",
        "all_with_labels",
        "custom"
      ]
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "schema_valid",
        "schema_invalid",
        "provenance_sufficient",
        "provenance_insufficient",
        "evidence_sufficient",
        "evidence_insufficient",
        "authority_recognized",
        "authority_not_recognized",
        "scope_mismatch",
        "policy_satisfied",
        "policy_failed",
        "signature_valid",
        "signature_invalid",
        "hash_valid",
        "hash_invalid",
        "conflict_detected",
        "disagreement_preserved",
        "certainty_too_low_for_policy",
        "rejected_by_authority_channel",
        "revoked_by_authority_channel"
      ]
    },
    "signature": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "key_id",
        "alg",
        "signature"
      ],
      "properties": {
        "key_id": {
          "type": "string",
          "minLength": 1
        },
        "alg": {
          "type": "string",
          "description": "Signature algorithm identifier.",
          "enum": [
            "ed25519",
            "rsa-pss-sha256",
            "ecdsa-p256-sha256"
          ]
        },
        "signature": {
          "type": "string",
          "description": "Base64-encoded signature bytes.",
          "minLength": 16
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/structured-epistemic-state.schema.json"
id=d9f3f19790f7
kind=source
size=39124
lines=1621
line_ref=1-1621
chunks=5
chunk_refs=1-350,351-700,701-1050,1051-1400,1401-1621
summary="Source file."

--- CHUNK BEGIN ---
id=d9f3f19790f7:1-350
start=1
end=350
----
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/structured-epistemic-state.schema.json",
  "title": "Structured Epistemic State v5",
  "description": "Structured Epistemic State is the normative Kristal v5 input unit. It represents claims, hypotheses, references, myths, fictional corpora, technical declarations, research claims, institutional corpora, and disputed positions with explicit provenance, scope, certainty, validation, and authority metadata.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "artifact_type",
    "state_id",
    "artifact_status",
    "created_at",
    "created_by",
    "scope",
    "assertions",
    "provenance"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "5.0"
    },
    "artifact_type": {
      "type": "string",
      "const": "structured_epistemic_state"
    },
    "state_id": {
      "$ref": "#/$defs/sha256_uri"
    },
    "artifact_status": {
      "$ref": "#/$defs/artifact_status"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "created_by": {
      "$ref": "#/$defs/agent_ref"
    },
    "canonicalization_profile": {
      "type": "string",
      "const": "kristal.v5:jcs-rfc8785"
    },
    "canonicalization_version": {
      "type": "string",
      "const": "1"
    },
    "content_hash": {
      "$ref": "#/$defs/hash_ref"
    },
    "hash_target_policy": {
      "$ref": "#/$defs/hash_target_policy"
    },
    "scope": {
      "$ref": "#/$defs/scope"
    },
    "source_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/source_ref"
      },
      "default": []
    },
    "derived_from": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "merged_from": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "supersedes": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "assertions": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/assertion"
      }
    },
    "provenance": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/provenance_record"
      }
    },
    "review_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "policy_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/policy_ref"
      },
      "default": []
    },
    "authority_recognition_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/authority_recognition_ref"
      },
      "default": []
    },
    "reader_policy_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/reader_policy_ref"
      },
      "default": []
    },
    "certainty_summary": {
      "$ref": "#/$defs/certainty_summary"
    },
    "validation_summary": {
      "$ref": "#/$defs/state_validation_summary"
    },
    "lineage": {
      "$ref": "#/$defs/lineage"
    },
    "build": {
      "$ref": "#/$defs/build_record"
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/warning"
      },
      "default": []
    },
    "extensions": {
      "type": "object",
      "additionalProperties": true,
      "default": {}
    },
    "signatures": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/signature"
      },
      "default": []
    }
  },
  "$defs": {
    "sha256_hex": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}$"
    },
    "sha256_uri": {
      "type": "string",
      "pattern": "^sha256:[0-9a-fA-F]{64}$"
    },
    "qid": {
      "type": "string",
      "pattern": "^Q[1-9][0-9]*$"
    },
    "pid": {
      "type": "string",
      "pattern": "^P[1-9][0-9]*$"
    },
    "lang": {
      "type": "string",
      "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$"
    },
    "hash_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["alg", "value"],
      "properties": {
        "alg": {
          "type": "string",
          "const": "sha256"
        },
        "value": {
          "$ref": "#/$defs/sha256_hex"
        }
      }
    },
    "hash_target_policy": {
      "type": "object",
      "additionalProperties": false,
      "required": ["exclude_fields"],
      "properties": {
        "exclude_fields": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": ["state_id", "content_hash", "signatures"]
          },
          "uniqueItems": true
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "signature": {
      "type": "object",
      "additionalProperties": false,
      "required": ["key_id", "alg", "signature", "created_at"],
      "properties": {
        "key_id": {
          "type": "string",
          "minLength": 1
        },
        "alg": {
          "type": "string",
          "const": "ed25519"
        },
        "signature": {
          "type": "string",
          "minLength": 1
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      }
    },
    "artifact_status": {
      "type": "string",
      "enum": [
        "draft",
        "working",
        "under_review",
        "recognized",
        "reference",
        "deprecated",
        "superseded",
        "revoked"
      ]
    },
    "assertion_status": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claimed",
        "sourced",
        "disputed",
        "reviewed",
        "validated",
        "rejected",
        "retracted",
        "superseded"
      ]
    },
    "certainty_level": {
      "type": "string",
      "enum": [
        "unknown",
        "speculative",
        "low",
        "medium",
        "high",
        "established",
        "not_applicable"
      ]
    },
    "validation_status": {
      "type": "string",
      "enum": [
        "not_evaluated",
        "in_review",
        "validated",
        "conditionally_validated",
        "disputed",
        "rejected",
        "revoked"
      ]
    },
    "validated_as": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claim",
        "sourced_claim",
        "reviewed_claim",
        "high_confidence_fact",
        "institutional_reference",
        "publisher_declaration",
        "technical_specification",
        "legal_or_policy_position",
        "mythological_corpus",
        "fictional_corpus",
        "symbolic_model",
        "disputed_position",
        "rejected_claim"
      ]
    },
    "recognition_status": {
      "type": "string",
      "enum": [
        "recognized",
        "conditionally_recognized",
        "under_review",
        "disputed",
        "rejected",
        "deprecated",
        "revoked"
      ]
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "schema_valid",
        "schema_invalid",
        "provenance_sufficient",
        "provenance_insufficient",
        "evidence_sufficient",
        "evidence_insufficient",
        "authority_recognized",
        "authority_not_recognized",
        "scope_mismatch",
        "policy_satisfied",
        "policy_failed",
        "signature_valid",
        "signature_invalid",
        "hash_valid",
        "hash_invalid",
        "conflict_detected",
        "disagreement_preserved",
        "certainty_too_low_for_policy",
        "rejected_by_authority_channel",
        "revoked_by_authority_channel"
      ]
    },
    "scope": {
      "type": "object",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=d9f3f19790f7:351-700
start=351
end=700
----
      "additionalProperties": false,
      "required": ["domain"],
      "properties": {
        "domain": {
          "type": "string",
          "enum": [
            "general",
            "wikidata",
            "science",
            "health",
            "education",
            "heritage",
            "law",
            "policy",
            "technology",
            "environment",
            "culture",
            "mythology",
            "fiction",
            "research",
            "operations",
            "civic",
            "local_notes"
          ]
        },
        "subdomain": {
          "type": ["string", "null"]
        },
        "jurisdiction": {
          "type": ["string", "null"]
        },
        "time_window": {
          "type": ["string", "null"]
        },
        "tenant_id": {
          "type": ["string", "null"]
        },
        "environment": {
          "type": ["string", "null"]
        },
        "language": {
          "type": ["string", "null"]
        }
      }
    },
    "agent_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "agent_id": {
          "type": "string",
          "minLength": 1
        },
        "name": {
          "type": "string"
        },
        "agent_type": {
          "type": "string",
          "enum": [
            "individual",
            "community",
            "association",
            "research_collective",
            "academic_institution",
            "standards_body",
            "company",
            "government",
            "intergovernmental_organization",
            "ai_validator",
            "hybrid_collective",
            "service",
            "system"
          ]
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      },
      "anyOf": [
        {
          "required": ["agent_id"]
        },
        {
          "required": ["name"]
        },
        {
          "required": ["authority_channel"]
        }
      ]
    },
    "authority_channel_id": {
      "type": "string",
      "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
    },
    "authority_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["authority_channel_id"],
      "properties": {
        "authority_channel_id": {
          "$ref": "#/$defs/authority_channel_id"
        },
        "name": {
          "type": "string"
        },
        "authority_registry_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      }
    },
    "policy_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "policy_id": {
          "type": "string",
          "minLength": 1
        },
        "policy_version": {
          "type": "string",
          "minLength": 1
        },
        "policy_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      },
      "anyOf": [
        {
          "required": ["policy_id"]
        },
        {
          "required": ["policy_ref"]
        }
      ]
    },
    "validation_policy_ref": {
      "$ref": "#/$defs/policy_ref"
    },
    "reader_policy_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "reader_policy_id": {
          "type": "string",
          "pattern": "^reader_policy:[a-z0-9][a-z0-9._:-]*$"
        },
        "mode": {
          "$ref": "#/$defs/reader_mode"
        },
        "policy_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      },
      "anyOf": [
        {
          "required": ["reader_policy_id"]
        },
        {
          "required": ["policy_ref"]
        }
      ]
    },
    "reader_mode": {
      "type": "string",
      "enum": [
        "reference_only",
        "validated_only",
        "high_certainty_only",
        "research",
        "creative",
        "all_with_labels",
        "custom"
      ]
    },
    "artifact_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "artifact_id": {
          "type": "string",
          "minLength": 1
        },
        "artifact_type": {
          "type": "string",
          "minLength": 1
        },
        "uri": {
          "type": "string",
          "format": "uri"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "anyOf": [
        {
          "required": ["artifact_id"]
        },
        {
          "required": ["uri"]
        },
        {
          "required": ["content_hash"]
        }
      ]
    },
    "source_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "source_id": {
          "type": "string",
          "minLength": 1
        },
        "source_type": {
          "type": "string",
          "enum": [
            "dataset",
            "document",
            "web_page",
            "wikidata_dump",
            "api_result",
            "human_submission",
            "institutional_record",
            "claim_ir",
            "resolved_claim_ir",
            "structured_epistemic_state",
            "exchange",
            "runtime_pack",
            "other"
          ]
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        },
        "title": {
          "type": "string"
        },
        "publisher": {
          "type": "string"
        },
        "retrieved_at": {
          "type": "string",
          "format": "date-time"
        },
        "license": {
          "type": "string"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      },
      "anyOf": [
        {
          "required": ["source_id"]
        },
        {
          "required": ["source_url"]
        },
        {
          "required": ["content_hash"]
        }
      ]
    },
    "provenance_record": {
      "type": "object",
      "additionalProperties": false,
      "required": ["provenance_id", "event_type", "created_at"],
      "properties": {
        "provenance_id": {
          "type": "string",
          "minLength": 1
        },
        "event_type": {
          "type": "string",
          "enum": [
            "created",
            "imported",
            "extracted",
            "resolved",
            "normalized",
            "reviewed",
            "validated",
            "recognized",
            "merged",
            "derived",
            "superseded",
            "revoked"
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "agent": {
          "$ref": "#/$defs/agent_ref"
        },
        "source_ref": {
          "$ref": "#/$defs/source_ref"
        },
        "artifact_ref": {
          "$ref": "#/$defs/artifact_ref"
        },
        "policy_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/policy_ref"
          }
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "entity_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "qid": {
          "$ref": "#/$defs/qid"
        },
        "external_id": {
          "type": "string",
          "minLength": 1
        },
        "iri": {
          "type": "string",
          "format": "uri"
        },
        "label": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "language": {
          "$ref": "#/$defs/lang"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      },
--- CHUNK END ---

--- CHUNK BEGIN ---
id=d9f3f19790f7:701-1050
start=701
end=1050
----
      "anyOf": [
        {
          "required": ["qid"]
        },
        {
          "required": ["external_id"]
        },
        {
          "required": ["iri"]
        },
        {
          "required": ["label"]
        }
      ]
    },
    "predicate_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "pid": {
          "$ref": "#/$defs/pid"
        },
        "external_id": {
          "type": "string",
          "minLength": 1
        },
        "iri": {
          "type": "string",
          "format": "uri"
        },
        "label": {
          "type": "string"
        },
        "language": {
          "$ref": "#/$defs/lang"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      },
      "anyOf": [
        {
          "required": ["pid"]
        },
        {
          "required": ["external_id"]
        },
        {
          "required": ["iri"]
        },
        {
          "required": ["label"]
        }
      ]
    },
    "normalized_value": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "value": {},
        "unit_qid": {
          "$ref": "#/$defs/qid"
        },
        "unit_label": {
          "type": "string"
        },
        "precision": {
          "type": "string"
        },
        "normalization_policy_ref": {
          "$ref": "#/$defs/policy_ref"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "object_value": {
      "type": "object",
      "additionalProperties": false,
      "required": ["kind", "value"],
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "item",
            "string",
            "quantity",
            "time",
            "monolingual_text",
            "coord",
            "url",
            "external_id",
            "boolean",
            "null",
            "json"
          ]
        },
        "value": {},
        "normalized": {
          "$ref": "#/$defs/normalized_value"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "kind": {
                "const": "item"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "$ref": "#/$defs/entity_ref"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "string"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "string"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "url"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "external_id"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "string"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "boolean"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "boolean"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "null"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "null"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "json"
              }
            }
          },
          "then": {
            "properties": {
              "value": {}
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "quantity"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": ["amount"],
                "properties": {
                  "amount": {
                    "type": "number"
                  },
                  "unit_qid": {
                    "$ref": "#/$defs/qid"
                  },
                  "unit_label": {
                    "type": "string"
                  },
                  "lower_bound": {
                    "type": "number"
                  },
                  "upper_bound": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "time"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": ["iso8601"],
                "properties": {
                  "iso8601": {
                    "type": "string",
                    "pattern": "^-?\\d{4}(-\\d{2})?(-\\d{2})?(T.*)?$"
                  },
                  "precision": {
                    "type": "string",
                    "enum": ["year", "month", "day", "hour", "minute", "second"]
                  },
                  "calendar": {
                    "type": "string"
                  },
                  "timezone": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "monolingual_text"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": ["text", "lang"],
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "lang": {
                    "$ref": "#/$defs/lang"
                  }
                }
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "kind": {
                "const": "coord"
              }
            }
          },
          "then": {
            "properties": {
              "value": {
                "type": "object",
                "additionalProperties": false,
                "required": ["lat", "lon"],
                "properties": {
                  "lat": {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90
                  },
                  "lon": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180
                  },
                  "globe": {
                    "type": "string"
                  },
                  "precision": {
                    "type": "number",
                    "minimum": 0
                  }
                }
              }
            }
          }
        }
      ]
    },
    "statement": {
--- CHUNK END ---

--- CHUNK BEGIN ---
id=d9f3f19790f7:1051-1400
start=1051
end=1400
----
      "type": "object",
      "additionalProperties": false,
      "required": ["subject", "predicate", "object"],
      "properties": {
        "subject": {
          "$ref": "#/$defs/entity_ref"
        },
        "predicate": {
          "$ref": "#/$defs/predicate_ref"
        },
        "object": {
          "$ref": "#/$defs/object_value"
        },
        "qualifiers": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/qualifier"
          },
          "default": []
        },
        "rank": {
          "type": "string",
          "enum": ["preferred", "normal", "deprecated", "not_applicable"]
        },
        "statement_hash": {
          "$ref": "#/$defs/hash_ref"
        }
      }
    },
    "qualifier": {
      "type": "object",
      "additionalProperties": false,
      "required": ["predicate", "object"],
      "properties": {
        "predicate": {
          "$ref": "#/$defs/predicate_ref"
        },
        "object": {
          "$ref": "#/$defs/object_value"
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "evidence_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["source_ref"],
      "properties": {
        "evidence_id": {
          "type": "string",
          "minLength": 1
        },
        "source_ref": {
          "$ref": "#/$defs/source_ref"
        },
        "quote": {
          "type": "string"
        },
        "page": {
          "type": "integer",
          "minimum": 1
        },
        "section": {
          "type": "string"
        },
        "offsets": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "start_char": {
              "type": "integer",
              "minimum": 0
            },
            "end_char": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "evidence_status": {
          "type": "string",
          "enum": ["provided", "missing", "weak", "sufficient", "contested"]
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        }
      }
    },
    "uncertainty": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "method": {
          "type": "string"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "validation_summary": {
      "type": "object",
      "additionalProperties": false,
      "required": ["validation_status"],
      "properties": {
        "validation_status": {
          "$ref": "#/$defs/validation_status"
        },
        "validated_as": {
          "$ref": "#/$defs/validated_as"
        },
        "certainty_level": {
          "$ref": "#/$defs/certainty_level"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        },
        "validation_policy_ref": {
          "$ref": "#/$defs/validation_policy_ref"
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "reason_codes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/reason_code"
          }
        },
        "validation_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "notes": {
          "type": "string"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "validation_status": {
                "enum": ["validated", "conditionally_validated", "rejected", "revoked"]
              }
            }
          },
          "then": {
            "required": ["validated_as", "authority_channel", "validation_policy_ref", "scope"]
          }
        }
      ]
    },
    "authority_recognition_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": ["recognition_status", "authority_channel"],
      "properties": {
        "recognition_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "recognition_status": {
          "$ref": "#/$defs/recognition_status"
        },
        "recognized_as": {
          "$ref": "#/$defs/validated_as"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "validation_policy_ref": {
          "$ref": "#/$defs/validation_policy_ref"
        },
        "recognition_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      }
    },
    "assertion": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "assertion_id",
        "statement",
        "assertion_status",
        "certainty_level",
        "scope"
      ],
      "properties": {
        "assertion_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "source_assertion_id": {
          "type": "string",
          "minLength": 1
        },
        "statement": {
          "$ref": "#/$defs/statement"
        },
        "natural_language_statement": {
          "type": "object",
          "additionalProperties": false,
          "required": ["text", "lang"],
          "properties": {
            "text": {
              "type": "string"
            },
            "lang": {
              "$ref": "#/$defs/lang"
            }
          }
        },
        "assertion_status": {
          "$ref": "#/$defs/assertion_status"
        },
        "certainty_level": {
          "$ref": "#/$defs/certainty_level"
        },
        "validated_as": {
          "$ref": "#/$defs/validated_as"
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "evidence_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/evidence_ref"
          },
          "default": []
        },
        "provenance_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          },
          "default": []
        },
        "authority_recognition_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/authority_recognition_ref"
          },
          "default": []
        },
        "validation": {
          "$ref": "#/$defs/validation_summary"
        },
        "uncertainty": {
          "$ref": "#/$defs/uncertainty"
        },
        "lineage": {
          "$ref": "#/$defs/assertion_lineage"
        },
        "conflicts_with": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/sha256_uri"
          },
          "default": []
        },
        "supersedes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/sha256_uri"
          },
          "default": []
        },
        "notes": {
          "type": "string"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "assertion_status": {
                "const": "validated"
              }
            }
          },
          "then": {
            "required": ["validated_as", "validation"]
          }
        },
        {
          "if": {
            "properties": {
              "assertion_status": {
                "enum": ["rejected", "retracted"]
              }
            }
          },
          "then": {
            "required": ["validation"]
          }
        }
      ]
    },
    "assertion_lineage": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "source_assertions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/sha256_uri"
          }
        },
        "source_artifacts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "transforms": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/transform_record"
          }
        }
      }
    },
    "transform_record": {
      "type": "object",
      "additionalProperties": false,
      "required": ["transform_id", "transform_type"],
      "properties": {
        "transform_id": {
          "type": "string",
          "minLength": 1
        },
        "transform_type": {
          "type": "string",
          "enum": [
            "import",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=d9f3f19790f7:1401-1621
start=1401
end=1621
----
            "extraction",
            "resolution",
            "normalization",
            "merge",
            "split",
            "manual_edit",
            "review",
            "validation",
            "recognition"
          ]
        },
        "tool": {
          "type": "string"
        },
        "policy_ref": {
          "$ref": "#/$defs/policy_ref"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "certainty_summary": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "counts_by_certainty_level": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "counts_by_assertion_status": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "counts_by_validated_as": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "state_validation_summary": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "validation_status": {
          "$ref": "#/$defs/validation_status"
        },
        "recognition_status": {
          "$ref": "#/$defs/recognition_status"
        },
        "authority_channels": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/authority_ref"
          }
        },
        "validation_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "recognition_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/authority_recognition_ref"
          }
        },
        "reason_codes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/reason_code"
          }
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "lineage": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "source_artifacts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "source_states": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "transforms": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/transform_record"
          }
        },
        "compiler": {
          "$ref": "#/$defs/agent_ref"
        },
        "policy_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/policy_ref"
          }
        }
      }
    },
    "build_record": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "build_id": {
          "type": "string",
          "minLength": 1
        },
        "schema_version": {
          "type": "string",
          "const": "5.0"
        },
        "compile_status": {
          "type": "string",
          "enum": ["succeeded", "failed", "partial"]
        },
        "validation_status": {
          "$ref": "#/$defs/validation_status"
        },
        "review_status": {
          "type": "string",
          "enum": ["not_required", "pending", "completed", "blocked"]
        },
        "recognition_status": {
          "type": "string",
          "enum": ["none", "recognized", "conditionally_recognized", "rejected", "revoked"]
        },
        "publication_status": {
          "type": "string",
          "enum": ["not_published", "published", "blocked"]
        },
        "activation_status": {
          "type": "string",
          "enum": ["not_applicable", "activated", "blocked", "revoked"]
        },
        "working_outputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "reference_outputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "reason_codes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/reason_code"
          }
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "warning": {
      "type": "object",
      "additionalProperties": false,
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "LOW_CERTAINTY",
            "DISPUTED_ASSERTION",
            "MISSING_EVIDENCE",
            "WEAK_EVIDENCE",
            "AUTHORITY_CHANNEL_MISSING",
            "VALIDATION_SCOPE_MISSING",
            "SCOPE_MISMATCH",
            "UNRECOGNIZED_AUTHORITY",
            "PROJECTION_REQUIRES_REVIEW",
            "CONFLICT_DETECTED"
          ]
        },
        "message": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "reason_code": {
          "$ref": "#/$defs/reason_code"
        }
      }
    }
  }
}

--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/02-schemas/validation-report.schema.json"
id=bf4d6901a2ac
kind=source
size=30778
lines=1340
line_ref=1-1340
chunks=4
chunk_refs=1-350,351-700,701-1050,1051-1340
summary="Source file."

--- CHUNK BEGIN ---
id=bf4d6901a2ac:1-350
start=1
end=350
----
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://kristal.org/schemas/v5/validation-report.schema.json",
  "title": "Validation Report v5",
  "description": "A Kristal v5 Validation Report records a scoped validation decision for an artifact, shard, assertion, authority channel, dataset, runtime pack, or query result. Validation is always authority-scoped, policy-scoped, and certainty-aware. A validation report does not imply universal truth unless a reader policy or authority channel explicitly treats it that way.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "artifact_type",
    "validation_report_id",
    "created_at",
    "issuer_authority_channel",
    "target",
    "target_level",
    "scope",
    "validation_policy_ref",
    "validation_status",
    "findings"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "const": "5.0"
    },
    "artifact_type": {
      "type": "string",
      "const": "validation_report"
    },
    "validation_report_id": {
      "$ref": "#/$defs/sha256_uri"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "canonicalization_profile": {
      "type": "string",
      "const": "kristal.v5:jcs-rfc8785"
    },
    "canonicalization_version": {
      "type": "string",
      "const": "1"
    },
    "content_hash": {
      "$ref": "#/$defs/hash_ref"
    },
    "hash_target_policy": {
      "$ref": "#/$defs/hash_target_policy"
    },
    "issuer_authority_channel": {
      "$ref": "#/$defs/authority_ref"
    },
    "target": {
      "$ref": "#/$defs/target_ref"
    },
    "target_level": {
      "$ref": "#/$defs/target_level"
    },
    "scope": {
      "$ref": "#/$defs/scope"
    },
    "validation_policy_ref": {
      "$ref": "#/$defs/validation_policy_ref"
    },
    "validation_status": {
      "$ref": "#/$defs/validation_status"
    },
    "validated_as": {
      "$ref": "#/$defs/validated_as"
    },
    "certainty_level": {
      "$ref": "#/$defs/certainty_level"
    },
    "recognition_status": {
      "$ref": "#/$defs/recognition_status"
    },
    "authority_recognition_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/authority_recognition_ref"
      },
      "default": []
    },
    "reader_policy_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/reader_policy_ref"
      },
      "default": []
    },
    "input_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "evidence_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/evidence_ref"
      },
      "default": []
    },
    "provenance_refs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_ref"
      },
      "default": []
    },
    "findings": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/finding"
      }
    },
    "assertion_results": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/assertion_validation_result"
      },
      "default": []
    },
    "artifact_checks": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/artifact_check"
      },
      "default": []
    },
    "policy_evaluation": {
      "$ref": "#/$defs/policy_evaluation"
    },
    "summary": {
      "$ref": "#/$defs/validation_summary"
    },
    "lineage": {
      "$ref": "#/$defs/lineage"
    },
    "build": {
      "$ref": "#/$defs/build_record"
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/warning"
      },
      "default": []
    },
    "errors": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/error"
      },
      "default": []
    },
    "signatures": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/signature"
      },
      "default": []
    },
    "extensions": {
      "type": "object",
      "additionalProperties": true,
      "default": {}
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "validation_status": {
            "enum": [
              "validated",
              "conditionally_validated",
              "rejected",
              "revoked"
            ]
          }
        }
      },
      "then": {
        "required": [
          "validated_as",
          "certainty_level"
        ]
      }
    }
  ],
  "$defs": {
    "sha256_hex": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}$"
    },
    "sha256_uri": {
      "type": "string",
      "pattern": "^sha256:[0-9a-fA-F]{64}$"
    },
    "hash_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "alg",
        "value"
      ],
      "properties": {
        "alg": {
          "type": "string",
          "const": "sha256"
        },
        "value": {
          "$ref": "#/$defs/sha256_hex"
        }
      }
    },
    "hash_target_policy": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "exclude_fields"
      ],
      "properties": {
        "exclude_fields": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "validation_report_id",
              "content_hash",
              "signatures"
            ]
          },
          "uniqueItems": true
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "signature": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "key_id",
        "alg",
        "signature",
        "created_at"
      ],
      "properties": {
        "key_id": {
          "type": "string",
          "minLength": 1
        },
        "alg": {
          "type": "string",
          "const": "ed25519"
        },
        "signature": {
          "type": "string",
          "minLength": 1
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      }
    },
    "scope": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "domain"
      ],
      "properties": {
        "domain": {
          "type": "string",
          "enum": [
            "general",
            "wikidata",
            "science",
            "health",
            "education",
            "heritage",
            "law",
            "policy",
            "technology",
            "environment",
            "culture",
            "mythology",
            "fiction",
            "research",
            "operations",
            "civic",
            "local_notes"
          ]
        },
        "subdomain": {
          "type": [
            "string",
            "null"
          ]
        },
        "jurisdiction": {
          "type": [
            "string",
            "null"
          ]
        },
        "time_window": {
          "type": [
            "string",
            "null"
          ]
        },
        "tenant_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "environment": {
          "type": [
            "string",
            "null"
          ]
        },
        "language": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "authority_channel_id": {
      "type": "string",
      "pattern": "^authority:[a-z0-9][a-z0-9._:-]*$"
    },
--- CHUNK END ---

--- CHUNK BEGIN ---
id=bf4d6901a2ac:351-700
start=351
end=700
----
    "authority_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "authority_channel_id"
      ],
      "properties": {
        "authority_channel_id": {
          "$ref": "#/$defs/authority_channel_id"
        },
        "name": {
          "type": "string"
        },
        "authority_registry_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      }
    },
    "artifact_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "artifact_id": {
          "type": "string",
          "minLength": 1
        },
        "artifact_type": {
          "type": "string",
          "minLength": 1
        },
        "uri": {
          "type": "string",
          "format": "uri"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "anyOf": [
        {
          "required": [
            "artifact_id"
          ]
        },
        {
          "required": [
            "uri"
          ]
        },
        {
          "required": [
            "content_hash"
          ]
        }
      ]
    },
    "target_level": {
      "type": "string",
      "enum": [
        "artifact",
        "shard",
        "assertion",
        "authority_channel",
        "dataset",
        "runtime_pack",
        "query_result",
        "reader_policy",
        "validation_policy",
        "federation",
        "exchange",
        "structured_epistemic_state"
      ]
    },
    "target_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "target_id": {
          "type": "string",
          "minLength": 1
        },
        "artifact_id": {
          "type": "string",
          "minLength": 1
        },
        "artifact_type": {
          "type": "string",
          "minLength": 1
        },
        "assertion_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "shard_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "federation_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "runtime_pack_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "state_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "exchange_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        },
        "uri": {
          "type": "string",
          "format": "uri"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        }
      },
      "anyOf": [
        {
          "required": [
            "target_id"
          ]
        },
        {
          "required": [
            "artifact_id"
          ]
        },
        {
          "required": [
            "assertion_id"
          ]
        },
        {
          "required": [
            "shard_id"
          ]
        },
        {
          "required": [
            "federation_id"
          ]
        },
        {
          "required": [
            "runtime_pack_id"
          ]
        },
        {
          "required": [
            "state_id"
          ]
        },
        {
          "required": [
            "exchange_id"
          ]
        },
        {
          "required": [
            "authority_channel"
          ]
        },
        {
          "required": [
            "uri"
          ]
        },
        {
          "required": [
            "content_hash"
          ]
        }
      ]
    },
    "validation_status": {
      "type": "string",
      "enum": [
        "not_evaluated",
        "in_review",
        "validated",
        "conditionally_validated",
        "disputed",
        "rejected",
        "revoked"
      ]
    },
    "validated_as": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claim",
        "sourced_claim",
        "reviewed_claim",
        "high_confidence_fact",
        "institutional_reference",
        "publisher_declaration",
        "technical_specification",
        "legal_or_policy_position",
        "mythological_corpus",
        "fictional_corpus",
        "symbolic_model",
        "disputed_position",
        "rejected_claim"
      ]
    },
    "certainty_level": {
      "type": "string",
      "enum": [
        "unknown",
        "speculative",
        "low",
        "medium",
        "high",
        "established",
        "not_applicable"
      ]
    },
    "assertion_status": {
      "type": "string",
      "enum": [
        "hypothesis",
        "claimed",
        "sourced",
        "disputed",
        "reviewed",
        "validated",
        "rejected",
        "retracted",
        "superseded"
      ]
    },
    "recognition_status": {
      "type": "string",
      "enum": [
        "recognized",
        "conditionally_recognized",
        "under_review",
        "disputed",
        "rejected",
        "deprecated",
        "revoked"
      ]
    },
    "validation_policy_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "policy_id": {
          "type": "string",
          "minLength": 1
        },
        "policy_version": {
          "type": "string",
          "minLength": 1
        },
        "policy_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      },
      "anyOf": [
        {
          "required": [
            "policy_id"
          ]
        },
        {
          "required": [
            "policy_ref"
          ]
        }
      ]
    },
    "reader_policy_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "reader_policy_id": {
          "type": "string",
          "pattern": "^reader_policy:[a-z0-9][a-z0-9._:-]*$"
        },
        "mode": {
          "type": "string",
          "enum": [
            "reference_only",
            "validated_only",
            "high_certainty_only",
            "research",
            "creative",
            "all_with_labels",
            "custom"
          ]
        },
        "policy_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      },
      "anyOf": [
        {
          "required": [
            "reader_policy_id"
          ]
        },
        {
          "required": [
            "policy_ref"
          ]
        }
      ]
    },
    "authority_recognition_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "recognition_status",
        "authority_channel"
      ],
      "properties": {
        "recognition_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "recognition_status": {
          "$ref": "#/$defs/recognition_status"
        },
        "recognized_as": {
          "$ref": "#/$defs/validated_as"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "validation_policy_ref": {
          "$ref": "#/$defs/validation_policy_ref"
        },
        "recognition_ref": {
          "$ref": "#/$defs/artifact_ref"
        }
      }
    },
    "evidence_ref": {
      "type": "object",
      "additionalProperties": false,
      "required": [
--- CHUNK END ---

--- CHUNK BEGIN ---
id=bf4d6901a2ac:701-1050
start=701
end=1050
----
        "source_ref"
      ],
      "properties": {
        "evidence_id": {
          "type": "string",
          "minLength": 1
        },
        "source_ref": {
          "$ref": "#/$defs/source_ref"
        },
        "quote": {
          "type": "string"
        },
        "page": {
          "type": "integer",
          "minimum": 1
        },
        "section": {
          "type": "string"
        },
        "offsets": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "start_char": {
              "type": "integer",
              "minimum": 0
            },
            "end_char": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "evidence_status": {
          "type": "string",
          "enum": [
            "provided",
            "missing",
            "weak",
            "sufficient",
            "contested"
          ]
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        }
      }
    },
    "source_ref": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "source_id": {
          "type": "string",
          "minLength": 1
        },
        "source_type": {
          "type": "string",
          "enum": [
            "dataset",
            "document",
            "web_page",
            "wikidata_dump",
            "api_result",
            "human_submission",
            "institutional_record",
            "claim_ir",
            "resolved_claim_ir",
            "structured_epistemic_state",
            "exchange",
            "runtime_pack",
            "other"
          ]
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        },
        "title": {
          "type": "string"
        },
        "publisher": {
          "type": "string"
        },
        "retrieved_at": {
          "type": "string",
          "format": "date-time"
        },
        "license": {
          "type": "string"
        },
        "content_hash": {
          "$ref": "#/$defs/hash_ref"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        }
      },
      "anyOf": [
        {
          "required": [
            "source_id"
          ]
        },
        {
          "required": [
            "source_url"
          ]
        },
        {
          "required": [
            "content_hash"
          ]
        }
      ]
    },
    "finding_status": {
      "type": "string",
      "enum": [
        "passed",
        "failed",
        "warning",
        "not_applicable",
        "not_evaluated"
      ]
    },
    "finding_severity": {
      "type": "string",
      "enum": [
        "info",
        "low",
        "medium",
        "high",
        "critical"
      ]
    },
    "finding": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "finding_id",
        "check_id",
        "status"
      ],
      "properties": {
        "finding_id": {
          "type": "string",
          "minLength": 1
        },
        "check_id": {
          "type": "string",
          "minLength": 1
        },
        "check_type": {
          "type": "string",
          "enum": [
            "schema",
            "integrity",
            "signature",
            "hash",
            "provenance",
            "evidence",
            "authority",
            "scope",
            "certainty",
            "policy",
            "conflict",
            "reader_policy",
            "custom"
          ]
        },
        "status": {
          "$ref": "#/$defs/finding_status"
        },
        "severity": {
          "$ref": "#/$defs/finding_severity"
        },
        "reason_code": {
          "$ref": "#/$defs/reason_code"
        },
        "message": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "target": {
          "$ref": "#/$defs/target_ref"
        },
        "evidence_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/evidence_ref"
          }
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "assertion_validation_result": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "assertion_id",
        "validation_status",
        "certainty_level"
      ],
      "properties": {
        "assertion_id": {
          "$ref": "#/$defs/sha256_uri"
        },
        "assertion_status": {
          "$ref": "#/$defs/assertion_status"
        },
        "validation_status": {
          "$ref": "#/$defs/validation_status"
        },
        "validated_as": {
          "$ref": "#/$defs/validated_as"
        },
        "certainty_level": {
          "$ref": "#/$defs/certainty_level"
        },
        "authority_channel": {
          "$ref": "#/$defs/authority_ref"
        },
        "scope": {
          "$ref": "#/$defs/scope"
        },
        "validation_policy_ref": {
          "$ref": "#/$defs/validation_policy_ref"
        },
        "findings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/finding"
          }
        },
        "reason_codes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/reason_code"
          }
        },
        "notes": {
          "type": "string"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "validation_status": {
                "enum": [
                  "validated",
                  "conditionally_validated",
                  "rejected",
                  "revoked"
                ]
              }
            }
          },
          "then": {
            "required": [
              "validated_as",
              "authority_channel",
              "scope",
              "validation_policy_ref"
            ]
          }
        }
      ]
    },
    "artifact_check": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "check_id",
        "check_type",
        "status"
      ],
      "properties": {
        "check_id": {
          "type": "string",
          "minLength": 1
        },
        "check_type": {
          "type": "string",
          "enum": [
            "schema",
            "integrity",
            "signature",
            "hash",
            "canonicalization",
            "lineage",
            "scope",
            "authority",
            "policy",
            "compatibility",
            "runtime_activation",
            "query_contract",
            "custom"
          ]
        },
        "status": {
          "$ref": "#/$defs/finding_status"
        },
        "severity": {
          "$ref": "#/$defs/finding_severity"
        },
        "reason_code": {
          "$ref": "#/$defs/reason_code"
        },
        "message": {
          "type": "string"
        },
        "target": {
          "$ref": "#/$defs/target_ref"
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "policy_evaluation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "policy_ref",
        "status"
      ],
      "properties": {
        "policy_ref": {
          "$ref": "#/$defs/validation_policy_ref"
        },
        "status": {
          "$ref": "#/$defs/finding_status"
        },
        "matched_rules": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "failed_rules": {
          "type": "array",
          "items": {
            "type": "string"
--- CHUNK END ---

--- CHUNK BEGIN ---
id=bf4d6901a2ac:1051-1340
start=1051
end=1340
----
          }
        },
        "reason_codes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/reason_code"
          }
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "validation_summary": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "total_findings": {
          "type": "integer",
          "minimum": 0
        },
        "passed": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        },
        "warnings": {
          "type": "integer",
          "minimum": 0
        },
        "not_applicable": {
          "type": "integer",
          "minimum": 0
        },
        "not_evaluated": {
          "type": "integer",
          "minimum": 0
        },
        "assertions_total": {
          "type": "integer",
          "minimum": 0
        },
        "assertions_validated": {
          "type": "integer",
          "minimum": 0
        },
        "assertions_conditionally_validated": {
          "type": "integer",
          "minimum": 0
        },
        "assertions_disputed": {
          "type": "integer",
          "minimum": 0
        },
        "assertions_rejected": {
          "type": "integer",
          "minimum": 0
        },
        "counts_by_certainty_level": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "counts_by_validated_as": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "notes": {
          "type": "string"
        }
      }
    },
    "lineage": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "source_artifacts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "source_reports": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "derived_from": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "supersedes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        }
      }
    },
    "build_record": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "build_id": {
          "type": "string",
          "minLength": 1
        },
        "schema_version": {
          "type": "string",
          "const": "5.0"
        },
        "compile_status": {
          "type": "string",
          "enum": [
            "succeeded",
            "failed",
            "partial"
          ]
        },
        "validation_status": {
          "$ref": "#/$defs/validation_status"
        },
        "review_status": {
          "type": "string",
          "enum": [
            "not_required",
            "pending",
            "completed",
            "blocked"
          ]
        },
        "recognition_status": {
          "type": "string",
          "enum": [
            "none",
            "recognized",
            "conditionally_recognized",
            "rejected",
            "revoked"
          ]
        },
        "publication_status": {
          "type": "string",
          "enum": [
            "not_published",
            "published",
            "blocked"
          ]
        },
        "activation_status": {
          "type": "string",
          "enum": [
            "not_applicable",
            "activated",
            "blocked",
            "revoked"
          ]
        },
        "working_outputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "reference_outputs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/artifact_ref"
          }
        },
        "reason_codes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/reason_code"
          }
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "warning": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "LOW_CERTAINTY",
            "DISPUTED_ASSERTION",
            "MISSING_EVIDENCE",
            "WEAK_EVIDENCE",
            "AUTHORITY_CHANNEL_MISSING",
            "VALIDATION_SCOPE_MISSING",
            "SCOPE_MISMATCH",
            "UNRECOGNIZED_AUTHORITY",
            "POLICY_WARNING",
            "CONFLICT_DETECTED",
            "PARTIAL_VALIDATION"
          ]
        },
        "message": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "reason_code": {
          "$ref": "#/$defs/reason_code"
        }
      }
    },
    "error": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "SCHEMA_INVALID",
            "INTEGRITY_CHECK_FAILED",
            "SIGNATURE_INVALID",
            "HASH_INVALID",
            "PROVENANCE_INSUFFICIENT",
            "EVIDENCE_INSUFFICIENT",
            "AUTHORITY_NOT_RECOGNIZED",
            "VALIDATION_POLICY_FAILED",
            "SCOPE_MISMATCH",
            "TARGET_UNRESOLVED",
            "UNSUPPORTED_TARGET_LEVEL"
          ]
        },
        "message": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "reason_code": {
          "$ref": "#/$defs/reason_code"
        }
      }
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "schema_valid",
        "schema_invalid",
        "provenance_sufficient",
        "provenance_insufficient",
        "evidence_sufficient",
        "evidence_insufficient",
        "authority_recognized",
        "authority_not_recognized",
        "scope_mismatch",
        "policy_satisfied",
        "policy_failed",
        "signature_valid",
        "signature_invalid",
        "hash_valid",
        "hash_invalid",
        "conflict_detected",
        "disagreement_preserved",
        "certainty_too_low_for_policy",
        "rejected_by_authority_channel",
        "revoked_by_authority_channel"
      ]
    }
  }
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/03-reproducibility/allowed-runtime-pack-policies.md"
id=9acf5c7e9b29
kind=markdown
size=18218
lines=558
line_ref=1-558
chunks=2
chunk_refs=1-350,351-558
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=9acf5c7e9b29:1-350
start=1
end=350
----
# Allowed Runtime Pack Policies (Kristal v5)

## Status

Draft — normative for Kristal v5 portability

## Purpose

Kristal v5 keeps the **determinism surface area small** while enabling high-performance offline execution, filtered reader views, and portable Runtime Packs.

A Runtime Pack is a deployable offline package derived from a Kristal Exchange or shard set. It may support strict reference use, validated-only use, research use, creative use, or custom reader policies. The pack must make its construction policies explicit so another implementation can compare, reproduce, or reject it under the same declared constraints.

A Kristal v5 Runtime Pack MUST:

1. Select policy values from the allowed sets below.
2. Record those selections in the Runtime Pack manifest under `policies`.
3. Declare any reader-policy materialization, source filtering, authority-channel filtering, or validation/certainty filtering that affects included data or indexes.
4. Preserve validation labels, certainty labels, authority labels, and source lineage.

Anything outside these policies is either:

* a **non-normative implementation detail**, or
* an **optional profile extension** that MUST be explicitly declared and MUST NOT change core IDs unless included in the declared reproducibility surface.

## Normative language

The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as normative requirements.

---

# 1. Policy recording requirements

## 1.1 Manifest structure — minimum

The Runtime Pack manifest MUST include a `policies` object with, at minimum:

* `policies.data_ordering`
* `policies.row_grouping`
* `policies.membership_filter`
* `policies.bitmap`

The manifest MAY also include:

* `policies.parquet`
* `policies.source_materialization`
* `policies.reader_policy_materialization`
* `policies.validation_materialization`
* `policies.authority_materialization`

Implementations MAY include additional policy keys only if the Runtime Pack manifest schema permits them. Implementations MUST NOT omit the required policy keys above.

## 1.2 Manifest linkage

A Runtime Pack manifest SHOULD declare:

* `source_exchange_ref`
* `source_artifact_status`
* `reader_policy_refs`
* `query_contract_ref`

If the pack is derived from a working artifact, `source_artifact_status` SHOULD be `working`.

If the pack is derived from a reference artifact, `source_artifact_status` SHOULD be `reference`.

A Runtime Pack MUST NOT imply that a working artifact is a reference artifact. It MUST preserve the source artifact status.

## 1.3 Determinism requirement

Given identical:

* inputs,
* source snapshots,
* compiler version,
* compiler config hash,
* selected reader policies,
* selected authority channels,
* selected validation/certainty filters,
* and the same recorded Runtime Pack policies,

the resulting Runtime Pack MUST be reproducible according to `03-reproducibility/reproducibility-acceptance-tests.md`.

## 1.4 Label preservation requirement

Runtime Pack construction MUST preserve, expose, or faithfully index the following Kristal v5 labels when they exist in the source artifact:

* `artifact_status`
* `assertion_status`
* `validation_status`
* `certainty_level`
* `validated_as`
* `authority_channel`
* `recognition_status`
* `scope`
* `provenance_refs`
* `evidence_refs`
* `lineage`

A Runtime Pack MUST NOT flatten scoped validation into universal truth.

A Runtime Pack MUST NOT remove the fact that an assertion is hypothetical, disputed, fictional, mythological, rejected, revoked, or validated only under a specific authority channel.

---

# 2. Data ordering policies

Ordering is treated as an index. Runtime Pack builders MUST pick from the following ordering policies for the primary assertion or triples store.

## 2.1 Allowed ordering policies

Exactly one of the following MUST be selected in `policies.data_ordering.policy`:

* `qid_pid_statement_id_asc`
* `subject_predicate_object_statement_id_asc`
* `lexicographic_sop_asc`
* `lexicographic_spo_asc`
* `none`

## 2.2 Semantics

* `qid_pid_statement_id_asc` MUST define a total order where the primary sort is by subject identifier, then predicate identifier, then a stable statement identifier.
* `subject_predicate_object_statement_id_asc` MUST define a total order by subject, predicate, object, then stable statement identifier.
* `lexicographic_sop_asc` MUST define a total order by stable byte-wise lexicographic comparison of a deterministic triple key encoding whose fields are `(s, o, p)` in that order.
* `lexicographic_spo_asc` MUST define a total order by stable byte-wise lexicographic comparison of a deterministic triple key encoding whose fields are `(s, p, o)` in that order.
* `none` indicates that the pack does not declare a portable total order.

Packs that claim stable pagination profiles SHOULD NOT use `none`.

## 2.3 Tie-breakers

If the chosen ordering can produce ties under its primary keys, implementations MUST apply a deterministic tie-breaker chain that produces a total order:

1. The ordering policy’s primary keys.
2. A stable statement identifier when available.
3. Stable byte comparison of a deterministic serialized key.
4. Stable byte comparison of the content-addressed assertion or row identifier.

---

# 3. Row-group sizing policies

Row-group policy impacts scan behavior, Parquet block indexes, pagination behavior, and reproducibility.

## 3.1 Allowed row-group modes

Exactly one of the following MUST be selected in `policies.row_grouping.policy`:

* `fixed_rows_100k`
* `fixed_rows_1m`
* `fixed_bytes_128mb`
* `fixed_bytes_512mb`

## 3.2 Determinism constraints

* The selected policy MUST be applied deterministically.
* Implementations MUST NOT vary row groups based on unstable runtime factors such as CPU count, memory pressure, wall-clock time, thread scheduling, or host-specific file-system behavior.
* If `fixed_bytes_*` policies are used, byte-size computation MUST be defined by the pack profile or manifest schema.

---

# 4. Membership filter policies

Membership filters accelerate scans by quickly rejecting “not present” membership queries.

They are probabilistic. Kristal v5 therefore makes determinism and semantic safety requirements explicit.

## 4.1 Allowed filter kinds

Exactly one of the following MUST be selected in `policies.membership_filter.kind`:

* `none`
* `bloom`
* `cuckoo`
* `xor8`
* `xor16`

## 4.2 Required parameters

For `kind = none`, no additional parameters are required.

For `kind != none`, the manifest MUST record all required parameters for that kind.

For `bloom`:

* `seed`
* `bits_per_key`
* `hash_functions`

For `cuckoo`:

* `seed`
* `fingerprint_bits`
* `load_factor`

For `xor8` or `xor16`:

* `seed`
* `bits_per_key`

## 4.3 False positives

Membership filters MAY return false positives.

Therefore:

* A membership hit MUST NOT be treated as proof of membership.
* Implementations MUST deterministically prune false positives by validating against the source store or declared authoritative index inside the pack.
* No probabilistic acceptance is permitted at the semantic layer.
* Query results MUST NOT change assertion status, certainty level, validation status, or authority recognition because of a membership filter hit.

---

# 5. Bitmap index policies

Bitmaps accelerate joins, multi-value lookups, authority-channel filters, validation-status filters, certainty filters, and reader-policy views.

## 5.1 Allowed bitmap formats

Exactly one of the following MUST be selected in `policies.bitmap.format`:

* `roaring`
* `roaring_run_optimized`

## 5.2 Run optimization

If run optimization is enabled, it MUST be recorded as:

```json
{
  "policies": {
    "bitmap": {
      "run_optimize": true
    }
  }
}
```

If run optimization is not enabled, it MUST be recorded as:

```json
{
  "policies": {
    "bitmap": {
      "run_optimize": false
    }
  }
}
```

## 5.3 Required bitmap label indexes

A Runtime Pack intended for v5 reader-policy filtering SHOULD provide bitmap or equivalent deterministic indexes for:

* `artifact_status`
* `assertion_status`
* `validation_status`
* `certainty_level`
* `validated_as`
* `authority_channel`
* `recognition_status`
* `scope.domain`

If those indexes are omitted, the manifest SHOULD declare which filters require scan-based evaluation.

## 5.4 Container statistics

Recording bitmap container statistics for cost modeling is an OPTIONAL profile extension.

If enabled, it MUST be declared as a profile and MUST NOT affect core identity unless included in the declared reproducibility surface.

---

# 6. Parquet-level policies

## 6.1 Parquet schema invariants

If a Runtime Pack uses Parquet:

* Column names and logical types MUST follow the v5 runtime schema definition or a declared v5-compatible profile.
* Sorting declarations MUST match the chosen data ordering policy, if applicable.
* Validation, certainty, authority, provenance, and lineage fields MUST NOT be silently dropped if they are required by the declared reader policy or query contract.

## 6.2 Allowed Parquet policy fields

If `policies.parquet` is present, it MUST use only allowed enumerations:

* `compression` in `{zstd, snappy, gzip, none}`
* `dictionary_encoding` in `{true, false}`
* `statistics` in `{none, page, rowgroup}`

## 6.3 Parquet Bloom filters

Parquet Bloom filters MAY be enabled as an optional performance profile, recorded as:

```json
{
  "policies": {
    "parquet": {
      "bloom_filters": {
        "enabled": true
      }
    }
  }
}
```

If enabled and the manifest schema permits additional details, the pack SHOULD record:

* which columns have Bloom filters;
* sizing parameters;
* hash parameters;
* seed parameters needed to reproduce them.

Bloom filters MUST NOT be required for core conformance.

---

# 7. Source materialization policies

A Runtime Pack may represent the full source artifact or a filtered materialization.

## 7.1 Allowed source materialization policies

If `policies.source_materialization` is present, exactly one of the following MUST be selected in `policies.source_materialization.policy`:

* `full_source`
* `reader_policy_view`
* `authority_channel_view`
* `validation_status_view`
* `certainty_view`
* `custom_profile`

## 7.2 Semantics

* `full_source` means the pack contains the full selected source artifact or shard set.
* `reader_policy_view` means the pack materializes only the data visible under one or more declared reader policies.
* `authority_channel_view` means the pack materializes only data associated with selected authority channels.
* `validation_status_view` means the pack materializes only data matching selected validation statuses.
* `certainty_view` means the pack materializes only data matching selected certainty levels.
* `custom_profile` means the pack uses a declared profile-specific filtering rule.

## 7.3 Required declarations

If the source is filtered during pack construction, the Runtime Pack manifest MUST declare:

* source artifact references;
* source artifact status;
* selected shards or datasets;
* selected authority channels, if any;
* selected reader policies, if any;
* selected validation statuses, if any;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=9acf5c7e9b29:351-558
start=351
end=558
----
* selected certainty levels, if any;
* selected `validated_as` values, if any;
* selected scopes, if any;
* profile IDs, if `custom_profile` is used.

A filtered Runtime Pack MUST NOT present itself as containing the full source artifact.

---

# 8. Reader-policy materialization

People and applications may choose strict or broad reading surfaces. Runtime Packs may support or materialize those choices.

## 8.1 Allowed reader-policy materialization modes

If `policies.reader_policy_materialization` is present, exactly one of the following MUST be selected in `policies.reader_policy_materialization.mode`:

* `none`
* `index_only`
* `filtered_materialization`

## 8.2 Semantics

* `none` means the Runtime Pack does not provide reader-policy-specific materialization.
* `index_only` means the Runtime Pack contains the source data but provides deterministic indexes for reader-policy filtering.
* `filtered_materialization` means the Runtime Pack contains only the subset visible under declared reader policies.

## 8.3 Reader-policy references

If `index_only` or `filtered_materialization` is used, the manifest MUST declare `reader_policy_refs`.

A Runtime Pack MAY support reader modes such as:

* `reference_only`
* `validated_only`
* `high_certainty_only`
* `research`
* `creative`
* `all_with_labels`
* `custom`

A `validated_only` reader policy means that all visible assertions satisfy the active validation policy. It does not mean all visible assertions have maximum certainty or universal agreement.

---

# 9. Validation and certainty materialization

Validation and certainty are separate dimensions.

Validation answers:

```text
Who accepts this claim or artifact, under which rules, for which scope?
```

Certainty answers:

```text
How strong is the assertion within that scope?
```

## 9.1 Allowed validation materialization modes

If `policies.validation_materialization` is present, exactly one of the following MUST be selected in `policies.validation_materialization.mode`:

* `none`
* `index_only`
* `filtered_materialization`

## 9.2 Required fields

If `index_only` or `filtered_materialization` is used, the manifest SHOULD record:

* `included_validation_statuses`
* `included_certainty_levels`
* `included_validated_as`
* `included_authority_channels`
* `included_recognition_statuses`

## 9.3 Label constraints

Runtime Pack construction MUST NOT convert:

* `hypothesis` into `high_confidence_fact`;
* `fictional_corpus` into physical-world fact;
* `mythological_corpus` into physical-world fact;
* `disputed_position` into recognized reference;
* authority-scoped validation into universal validation.

A Runtime Pack may contain only validated data if the active reader policy requires it. That validated data may still include multiple certainty levels, provided the certainty level and `validated_as` status remain explicit.

---

# 10. Authority materialization

Authority channels are plural and scoped.

A Runtime Pack MAY be built for one or more authority channels.

## 10.1 Allowed authority materialization modes

If `policies.authority_materialization` is present, exactly one of the following MUST be selected in `policies.authority_materialization.mode`:

* `none`
* `index_only`
* `filtered_materialization`

## 10.2 Required fields

If `index_only` or `filtered_materialization` is used, the manifest SHOULD record:

* `included_authority_channels`
* `included_authority_types`
* `included_recognition_statuses`
* `authority_registry_ref`

## 10.3 Authority constraints

Recognition by one authority channel MUST NOT be represented as recognition by another authority channel unless the second authority channel explicitly recognizes it.

A Runtime Pack built for a selected authority channel MUST preserve the fact that the selection occurred.

---

# 11. Query contract linkage

This document specifies build-affecting Runtime Pack construction policies.

Runtime query semantics are specified by `04-query/query-contract.md` and any declared query profiles.

A Runtime Pack SHOULD declare `query_contract` in the manifest, including:

* `contract_id`;
* capability flags;
* supported reader modes;
* supported filters;
* supported pagination behavior;
* supported authority-channel filters;
* supported validation-status filters;
* supported certainty-level filters.

Any declared pagination behavior MUST derive its stable order from `policies.data_ordering`.

Any declared filtered view MUST derive its inclusion rules from declared reader, validation, certainty, source, or authority materialization policies.

---

# 12. Unknown policy handling

Implementations MUST reject unknown policy values and unknown schema/profile versions unless explicitly configured to allow them.

If an implementation is configured to allow unknown values, it MUST mark the Runtime Pack as using implementation-specific behavior.

Unknown policy acceptance MUST NOT silently change:

* content-addressed identity;
* validation status;
* certainty level;
* authority recognition;
* reader-policy visibility;
* query semantics.

---

# 13. Versioning

Policy enumerations are versioned by the Runtime Pack manifest schema version.

For Kristal v5:

```text
schema_version = 5.0
runtime_pack_version = 5.0
```

Any change to enumerations or semantics MUST bump the relevant schema or profile version.

Patch-level documentation edits that do not change Runtime Pack semantics MAY leave the schema/profile version unchanged.

---

# 14. Summary — portable minimum

A Kristal v5 Runtime Pack MUST record, at minimum:

* `policies.data_ordering`
* `policies.row_grouping`
* `policies.membership_filter`
* `policies.bitmap`

A Kristal v5 Runtime Pack SHOULD also declare:

* `source_exchange_ref`
* `source_artifact_status`
* `reader_policy_refs`
* `query_contract_ref`

A Runtime Pack that filters, materializes, or indexes a subset SHOULD also record, when applicable:

* `policies.source_materialization`
* `policies.reader_policy_materialization`
* `policies.validation_materialization`
* `policies.authority_materialization`
* `policies.parquet`

These policies define the **portable comparability surface** for Runtime Packs in Kristal v5.

The purpose is not to guarantee that all data is final, universally true, or maximally certain. The purpose is to make Runtime Packs reproducible, inspectable, filterable, and honest about their source, validation status, certainty level, authority channel, and reader policy.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/03-reproducibility/deterministic-build-rules.md"
id=57fcef1acfc5
kind=markdown
size=25449
lines=594
line_ref=1-594
chunks=2
chunk_refs=1-350,351-594
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=57fcef1acfc5:1-350
start=1
end=350
----
# Deterministic build rules (Kristal v5)

## Status

Normative (v5 core)

## Purpose

This document defines the **deterministic build requirements** for producing Kristal v5 artifacts, specifically:

* **Working Exchange**
* **Reference Exchange**
* **Kristal Runtime Pack**
* **Exchange Shard Manifest**
* **Exchange Federation Manifest**
* derived manifests, indexes, inventories, and content-addressed outputs

The goal is **interoperability and reproducibility**: independent implementations MUST be able to rebuild artifacts with **bit-identical outputs** when given identical inputs, identical compiler versions, and the same recorded policies and parameters.

Kristal v5 separates compilation from validation and authority recognition. A deterministic build may produce a Working Exchange before all assertions are validated or recognized. Validation and recognition decisions are recorded separately and may affect reference status, publication, distribution, activation, reader visibility, or downstream use.

## Scope

These rules apply to:

* compilation stages that produce Working Exchanges, Reference Exchanges, Runtime Packs, shard manifests, and federation manifests;
* all content-addressed IDs associated with these artifacts;
* manifests and files that claim deterministic outputs;
* build-affecting reader policies, validation policies, authority registries, query policies, and runtime-pack policies;
* signatures, hashes, inventories, and artifact references used to verify identity and integrity.

These rules do **not** mandate a specific runtime performance strategy. They mandate that whatever strategy is used must be selected from **portable, enumerated policies** and must be **fully recorded** to enable reproducibility.

These rules do **not** require every compiled artifact to be validated, recognized, or reference-approved. Compilation proves that an artifact was built deterministically from declared inputs. It does not prove that the artifact’s assertions are true, validated, high-certainty, or recognized by any authority channel.

## Definitions

* **Deterministic build:** given the same input snapshot, compiler identity, configuration, policies, and parameters, the compiler produces identical outputs.
* **Reproducible build:** a third party can rerun the compiler using only the recorded manifests, referenced inputs, compiler version, and policy declarations and reproduce the exact outputs.
* **Input snapshot:** the complete set of inputs used for compilation.
* **Structured Epistemic State:** the normative input unit for Kristal v5 compilation. It contains assertions, provenance, evidence references, scope, certainty, status, lineage, and policy references.
* **Claim-IR:** an extractor proposal profile. Claim-IR MAY be part of an input snapshot, but it is not the universal required input format.
* **Working Exchange:** a compiled, content-addressed artifact representing a Structured Epistemic State that may or may not be validated or recognized.
* **Reference Exchange:** a compiled artifact recognized under one or more authority channels for a declared scope.
* **Authority recognition:** a scoped record by which an authority channel recognizes an artifact, shard, assertion, dataset, runtime pack, or another authority channel.
* **Validation decision:** a scoped record describing the validation status of an artifact, shard, assertion, authority channel, dataset, or runtime pack.
* **Reader policy:** a machine-readable policy defining which validation states, authority channels, certainty levels, and epistemic modes are visible to a reader or application.
* **Portable policy:** an allowed, enumerated policy defined in `03-reproducibility/allowed-runtime-pack-policies.md`.
* **Hash target:** the JSON object or declared projection that is canonicalized and hashed to produce a content-addressed ID, after applying required exclusions.

Normative keywords: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY.

## Normative requirements

### 1) Determinism declaration

1.1 Any Runtime Pack claiming v5 core conformance MUST declare whether it is deterministic.

1.2 Kristal v5 Runtime Packs claiming v5 core conformance MUST set:

```json
{
  "build": {
    "deterministic": true
  }
}
```

1.3 If an implementation cannot guarantee determinism for a given build, it MUST either:

* refuse to emit a v5 core-conformant pack; or
* emit a pack under a non-core profile that explicitly states non-deterministic behavior.

1.4 Working Exchanges, Reference Exchanges, shard manifests, and federation manifests that claim deterministic identity MUST record enough build-affecting information to reproduce their content-addressed IDs.

1.5 Determinism applies to output bytes and identity material. It does not imply validation, authority recognition, high certainty, publication approval, or reader visibility.

### 2) Canonicalization and hashing dependencies

2.1 Any JSON object or JSON projection used for content-addressed IDs MUST be canonicalized using the declared canonicalization profile.

2.2 v5 core requires:

```text
canonicalization_profile = "kristal.v5:jcs-rfc8785"
canonicalization_version = "1"
```

2.3 These values MUST be recorded by:

* every Working Exchange;
* every Reference Exchange;
* every Runtime Pack Manifest;
* every Exchange Shard Manifest;
* every Exchange Federation Manifest;
* every Authority Registry;
* every Validation Decision when content-addressed;
* every Authority Recognition when content-addressed;
* every Revocations artifact.

2.4 For any content-addressed ID computation, the hashed material MUST:

* exclude the output ID field itself, such as `kristal_id`, `exchange_id`, `runtime_pack_id`, `shard_id`, `federation_id`, `state_id`, `recognition_id`, `validation_decision_id`, or `revocations_id`;
* exclude `signatures` fields wherever they appear;
* exclude equivalent signature, attestation, or proof overlays unless a profile explicitly defines them as part of a separate proof hash;
* follow the relevant hashed-material projection for the artifact type.

2.5 `created_at` MAY reflect build time, but it MUST NOT affect content-addressed IDs unless a profile explicitly includes it in a declared hash target.

2.6 Hash objects MUST use the field name `alg`, not `algo`.

2.7 v5 core hash objects MUST use the following shape:

```json
{
  "alg": "sha256",
  "value": "<64 lowercase hexadecimal characters>"
}
```

2.8 When an artifact declares hashes, signatures, trust roots, compatibility constraints, revocation policy, or authority registry requirements, consumers MUST verify those requirements before treating the artifact as satisfying the corresponding policy.

### 3) Input snapshot is part of determinism

3.1 A deterministic build MUST be parameterized by an explicit input snapshot.

3.2 The input snapshot MAY include:

* Structured Epistemic State artifacts;
* Claim-IR artifacts when extractor workflows are used;
* Resolved Claim-IR artifacts when resolution workflows are used;
* source datasets;
* Wikidata/Wikibase snapshots;
* source documents or evidence blobs;
* validation rulesets;
* validation decisions;
* authority recognition records;
* authority registries;
* revocation lists;
* reader policies;
* subset recipes;
* query profiles;
* runtime-pack policies;
* federation manifests or shard manifests;
* compiler configuration.

3.3 The compiler configuration that affects output bytes MUST be hashed and recorded as `build.config_hash`.

3.4 Any implicit inputs that affect output bytes MUST be eliminated or explicitly recorded. This includes:

* default configuration;
* environment variables;
* locale;
* timezone;
* system time;
* dependency versions;
* compiler feature flags;
* nondeterministic random seeds;
* host-specific filesystem ordering;
* platform-specific path handling.

3.5 If an implementation uses external resources during compilation, the exact resource identity, version, and content hash MUST be recorded.

3.6 A build MUST NOT depend on mutable network state unless that state has been pinned into the input snapshot.

### 4) Ordering determinism

4.1 The compiler MUST NOT rely on non-deterministic iteration order.

4.2 All collections that affect output bytes MUST be processed in a deterministic order defined by an allowed ordering policy.

4.3 If an ordering policy is used, it MUST be recorded under the relevant manifest policy section.

4.4 Stable ordering MUST apply to all build-affecting collections, including:

* assertions;
* provenance records;
* evidence references;
* validation references;
* authority recognition references;
* file inventories;
* shard lists;
* federation composition rules;
* reader policy references;
* manifest references;
* dictionary encodings;
* index rows;
* generated lookup tables;
* membership-filter inputs;
* bitmap inputs.

4.5 Deterministic ordering MUST NOT silently erase disagreement. If two assertions conflict, ordering MAY determine presentation or precedence under a declared policy, but conflict handling MUST remain explicit.

### 5) Portable, enumerated policies

5.1 Build-affecting behaviors MUST be chosen from the allowed policy set defined in:

```text
03-reproducibility/allowed-runtime-pack-policies.md
```

5.2 If a required behavior is not covered by an allowed policy, the implementation MUST either:

* propose a new policy for standardization; or
* emit a non-core profile artifact that does not claim v5 core conformance.

5.3 This requirement exists to prevent builds that are technically reproducible but practically incomparable.

5.4 Policy declarations MUST include enough information to reproduce output bytes.

5.5 Policy declarations MUST distinguish at least:

* compilation policies;
* canonicalization policies;
* data ordering policies;
* query policies;
* reader policies;
* validation policies;
* authority recognition policies;
* runtime-pack policies;
* federation composition policies;
* integrity policies.

### 6) Structured Epistemic State determinism

6.1 A Structured Epistemic State used as a build input MUST be schema-valid under the declared schema version.

6.2 A Structured Epistemic State MUST be content-addressable or have a declared canonical hash target.

6.3 If a Structured Epistemic State contains assertions, their order in the source file MUST NOT affect compiled output unless an explicit ordering policy says otherwise.

6.4 Assertions MUST carry stable identifiers or be deterministically assigned identifiers from declared hash targets.

6.5 Assertion identity derivation MUST exclude fields that are not part of assertion meaning or declared identity, including signatures and output ID fields.

6.6 A Structured Epistemic State MAY include uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions. The compiler MUST preserve their declared status and certainty metadata.

6.7 The compiler MUST NOT convert assertion uncertainty into validation or recognition status.

### 7) Validation and recognition are not universal compile gates

7.1 Compilation MAY produce a Working Exchange from a schema-valid Structured Epistemic State even when validation has not been completed.

7.2 Validation MAY affect:

* assertion status;
* certainty level;
* validation status;
* authority recognition eligibility;
* reference status;
* publication status;
* runtime-pack activation status;
* reader visibility;
* downstream query behavior.

7.3 Validation MUST NOT be treated as a universal compilation blocker.

7.4 Validation MAY block creation of a Reference Exchange if the applicable authority channel or validation policy requires it.

7.5 Validation MAY block publication, distribution, activation, or reader visibility on selected channels.

7.6 Authority recognition MAY be required for reference status, but lack of recognition MUST NOT prevent a Working Exchange from existing unless a local workflow policy explicitly requires that behavior.

7.7 A build manifest MUST distinguish compilation status from validation status, recognition status, publication status, and activation status.

### 8) Working Exchange and Reference Exchange derivation

8.1 A Working Exchange MUST declare:

* `schema_version`;
* `artifact_type`;
* content-addressed ID;
* source state references;
* compiler identity;
* configuration hash;
* canonicalization profile and version;
* build policies;
* scope;
* assertion status and certainty metadata or summaries;
* validation references when present;
* authority recognition references when present.

8.2 A Reference Exchange MUST additionally declare the authority recognition records, validation decisions, policy references, and scope under which reference status is granted.

8.3 Reference status MUST be scoped. A Reference Exchange recognized by one authority channel MUST NOT be treated as recognized by another authority channel unless such recognition is explicitly recorded.

8.4 A Reference Exchange MUST retain traceability to the Working Exchange or Structured Epistemic State from which it was derived.

8.5 Compilers MUST NOT collapse assertion certainty, validation status, and authority recognition into a single boolean field.

8.6 A field such as:

```json
{ "validated": true }
```

MUST NOT be used as the only representation of validation.

8.7 Validation status MUST be qualified by target, authority channel, validation policy, scope, certainty level, and validated-as mode.

### 9) Runtime Pack source status

9.1 A Runtime Pack MUST reference the Exchange or federation source it was compiled from.

9.2 A Runtime Pack MUST declare the source artifact status, such as:

```text
working
reference
deprecated
superseded
revoked
```

9.3 A Runtime Pack derived from a Working Exchange is not equivalent to a Runtime Pack derived from a Reference Exchange.

9.4 A Runtime Pack MUST include enough metadata for consumers to apply reader policies.

9.5 A Runtime Pack MUST NOT present unrecognized or unvalidated assertions as recognized reference material unless the active reader policy explicitly allows that interpretation.

### 10) Reader policy determinism

10.1 If a Runtime Pack or query surface applies a reader policy during compilation, the reader policy MUST be included in the input snapshot.

10.2 Reader policies that affect output bytes MUST be content-addressed or referenced by content hash.

10.3 Reader policies MAY filter by:

* artifact status;
* assertion status;
* validation status;
* recognition status;
* authority channel;
* certainty level;
* validated-as mode;
* scope;
* domain;
* subdomain;
* jurisdiction;
* time window;
* fictional mode;
* mythological mode;
* disputed status.

10.4 A reader policy MUST NOT silently convert scoped validation into universal truth.

10.5 A “validated-only” reader policy means all visible assertions satisfy the active reader policy. It does not mean all visible assertions are universally true, maximally certain, or accepted by all authorities.

### 11) Federation and sharding determinism

--- CHUNK END ---

--- CHUNK BEGIN ---
id=57fcef1acfc5:351-594
start=351
end=594
----
11.1 A shard is a scoped Exchange artifact and MUST have deterministic identity.

11.2 A federation manifest MUST have deterministic identity.

11.3 A federation manifest MUST NOT rewrite shard bytes, shard identities, source hashes, or recognition records.

11.4 A federation manifest MUST declare deterministic composition policy, including:

* shard ordering;
* overlap handling;
* conflict handling;
* authority precedence, if used;
* reader policy defaults, if used;
* optional vs required shard behavior;
* treatment of revoked or deprecated shards.

11.5 Federation MUST preserve disagreement unless the declared composition policy explicitly filters or selects among conflicting assertions.

11.6 If two shards assert incompatible claims, the compiler MUST NOT silently merge them as though they agree.

11.7 If authority precedence is used, the applicable authority registry and recognition policy MUST be included in the input snapshot.

### 12) Parquet determinism

12.1 If Parquet is used, deterministic builds MUST:

* use a portable `data_ordering` policy;
* use a portable `row_grouping` policy;
* record Parquet encoding settings that affect file bytes;
* record compression settings;
* record dictionary encoding settings;
* record statistics settings;
* record bloom-filter settings if enabled.

12.2 The exact Parquet-related settings MUST be recorded under the relevant manifest policy section.

12.3 If bloom filters are enabled, they MUST be treated as profile-bound unless explicitly included in v5 core allowed policies.

12.4 Parquet output MUST be stable across supported toolchains claiming the same conformance profile.

### 13) Membership filters and bitmap determinism

13.1 If a pack includes membership filters, the kind and all parameters that affect bytes MUST be recorded, including as applicable:

* filter type;
* seed or seed derivation rule;
* bits per key;
* false-positive probability target;
* fingerprint size;
* load factor;
* hash function family;
* hash count;
* builder variant identifiers.

13.2 If a pack includes bitmaps, the bitmap format and any optimization steps that affect bytes MUST be recorded, including whether run optimization was applied.

13.3 Implementations MUST ensure membership-filter and bitmap construction is deterministic.

13.4 Random seeds MUST NOT be used unless explicitly recorded or deterministically derived from declared input material.

### 14) File inventory and integrity

14.1 The Runtime Pack Manifest MUST enumerate all files included in the pack under `files[]`, including:

* `path`;
* `role`;
* `sha256`;
* `size_bytes`.

14.2 The set of files and their hashes MUST be sufficient for consumers to verify pack contents and integrity.

14.3 The file inventory MUST be deterministic.

14.4 `files[]` entries MUST have stable deterministic ordering, such as lexical ordering by normalized path.

14.5 Path values MUST be normalized and MUST NOT depend on platform-specific path separators.

14.6 The inventory MUST include all files required for the declared query contract, reader policy behavior, integrity verification, and runtime execution.

### 15) Runtime Pack ID derivation

15.1 The `runtime_pack_id` MUST be derived from a canonical deterministic representation of the pack’s hashed material.

15.2 The hashed material MUST exclude:

* `runtime_pack_id` itself;
* `signatures` fields;
* equivalent signature or attestation overlays;
* non-identity timestamps unless explicitly included by a profile.

15.3 The hashed material MUST include, at minimum, a canonical projection covering:

* referenced source Exchange, federation, or shard identity;
* source artifact status;
* source content hash;
* deterministic build identity inputs;
* compiler identity;
* `build.config_hash`;
* `build.deterministic`;
* declared canonicalization profile and version;
* recorded portable policy selections;
* reader policy references that affect output bytes;
* validation or authority recognition references that affect output bytes;
* file inventory entries;
* query contract reference;
* runtime layout policy.

15.4 Each file inventory entry included in the hash target MUST include:

* `path`;
* `sha256`;
* `size_bytes`;
* `role`.

15.5 The exact hashed-material projection, including field set, ordering, exclusions, and path normalization, MUST be documented and test-vectorized.

### 16) Exchange ID derivation

16.1 Exchange IDs MUST be derived from a canonical deterministic representation of the Exchange hashed material.

16.2 Exchange hashed material MUST exclude:

* the output ID field itself;
* signatures;
* equivalent attestation overlays;
* non-identity timestamps unless explicitly included by a profile.

16.3 Working Exchange hashed material MUST include the declared source state references, scope, compilation policy, compiler identity, config hash, and compiled payload.

16.4 Reference Exchange hashed material MUST include the recognition and validation references that are part of its reference status.

16.5 A Reference Exchange with different authority recognition records MUST have a different content-addressed identity unless the recognition records are deliberately stored outside the hashed material by a declared profile.

### 17) Time, randomness, and environment constraints

17.1 The build MUST NOT incorporate non-deterministic sources into bytes that are hashed or part of deterministic outputs.

17.2 Non-deterministic sources include:

* system time;
* nondeterministic PRNG;
* thread scheduling;
* filesystem enumeration order;
* locale defaults;
* timezone defaults;
* host-specific path handling;
* unpinned dependency behavior;
* network response timing;
* mutable external resources.

17.3 `created_at` MAY reflect build time but MUST NOT affect content-addressed IDs unless a profile explicitly includes it.

17.4 If parallel compilation is used, the output MUST be equivalent to a deterministic serial order.

17.5 Any randomness required for a data structure MUST be replaced by deterministic seed derivation or explicitly recorded seed values.

### 18) Build record requirements

18.1 A v5 build record SHOULD distinguish at least:

* `compile_status`;
* `validation_status`;
* `review_status`;
* `recognition_status`;
* `publication_status`;
* `activation_status`;
* `working_outputs`;
* `reference_outputs`;
* `runtime_pack_outputs`;
* `reason_codes`.

18.2 `compile_status` MUST NOT be overloaded to mean validation status.

18.3 `validation_status` MUST NOT be overloaded to mean authority recognition.

18.4 `recognition_status` MUST NOT be treated as global unless the recognition scope explicitly says so.

18.5 Build records belong to operational metadata. They MAY be referenced by Kristal artifacts but SHOULD remain distinct from the epistemic content itself.

### 19) Signatures and verification

19.1 Signatures MUST be excluded from the primary content-addressed hash target unless a profile defines a separate proof hash.

19.2 Signature objects SHOULD use the minimal v5 shape:

```json
{
  "key_id": "string",
  "alg": "ed25519",
  "signature": "string",
  "created_at": "RFC3339"
}
```

19.3 Consumers MUST verify signatures required by the applicable artifact, authority registry, runtime policy, reader policy, or activation policy before treating the artifact as satisfying that policy.

19.4 Signature verification failure affects the policy that depends on that signature. It does not imply that the artifact bytes cannot exist or be inspected.

19.5 Revoked keys MUST NOT be accepted for policies whose scope and effective time are covered by the revocation.

### 20) Reproducibility acceptance criteria

20.1 A v5 core-conformant build MUST pass the acceptance tests defined in:

```text
03-reproducibility/reproducibility-acceptance-tests.md
```

20.2 At minimum, acceptance testing MUST verify:

* identical inputs and policies produce identical output bytes;
* identical inputs and policies produce identical content-addressed IDs;
* independent implementations produce stable IDs;
* file inventories are stable;
* hashed-material exclusions are applied consistently;
* signatures are excluded from primary hash targets;
* output ID fields are excluded from their own hash targets;
* `created_at` does not affect content-addressed IDs unless explicitly profile-bound;
* reader-policy-filtered outputs are reproducible;
* federation composition is deterministic;
* disagreement is preserved or handled according to declared policy;
* runtime-pack query outputs are stable under the declared query contract.

20.3 Acceptance tests SHOULD include examples for:

* Working Exchange compilation;
* Reference Exchange derivation;
* Structured Epistemic State compilation;
* authority recognition;
* validation decisions;
* reader policy filtering;
* Runtime Pack generation;
* shard compilation;
* federation composition;
* revoked keys;
* revoked targets.

## Non-normative notes

* Keeping the policy surface area small is intentional. It encourages comparable builds and reduces ecosystem fragmentation.
* Advanced optimizations, such as Parquet bloom filters, should typically be gated behind explicit profiles unless they are proven portable and deterministic across toolchains.
* Operational resilience patterns such as circuit breakers, DLQs, blue/green deployment, canary releases, retries, structured logs, and correlation IDs are described in `08-ops/` and are not part of artifact conformance unless explicitly referenced by a profile.
* A deterministic build can faithfully reproduce a bad, disputed, fictional, mythological, low-certainty, or rejected assertion. Determinism only means the artifact was built reproducibly.
* Validation, certainty, authority recognition, and reader policy determine how the resulting artifact should be interpreted.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/03-reproducibility/reproducibility-acceptance-tests.md"
id=fe6a832e3f34
kind=markdown
size=7926
lines=262
line_ref=1-262
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Reproducibility Acceptance Tests (Kristal v4)
000002 | 
000003 | ## Status
000004 | Draft (normative acceptance criteria)
000005 | 
000006 | ## Purpose
000007 | Define the **acceptance tests** that determine whether a Kristal v4 implementation produces **reproducible** artifacts.
000008 | 
000009 | In v3, reproducibility is a first-class requirement:
000010 | - Exchange rebuilds MUST produce identical `kristal_id` given the same inputs and rules.
000011 | - Runtime Pack rebuilds MUST produce identical `pack_id` (or equivalent) and identical declared payload hashes given the same inputs, compiler, configuration, and policy selections.
000012 | 
000013 | These tests are designed to prevent “works on my machine” builds and to ensure artifacts are comparable across toolchains.
000014 | 
000015 | ## Normative language
000016 | The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as normative requirements.
000017 | 
000018 | ---
000019 | 
000020 | # 1. Definitions
000021 | 
000022 | ## 1.1 Inputs
000023 | An **Input Snapshot** is a content-addressed reference to the exact source inputs used for a build (datasets, Claim-IR sets, resolved Claim-IR sets, configuration files, etc.).
000024 | 
000025 | ## 1.2 Build determinism surface
000026 | The determinism surface for a build is defined by:
000027 | - the declared input snapshots,
000028 | - the compiler identity and version,
000029 | - the full build configuration (identified by `config_hash`),
000030 | - and the recorded `policy_selections` (see `03-reproducibility/allowed-runtime-pack-policies.md`).
000031 | 
000032 | ## 1.3 Artifact hashes
000033 | - `kristal_id`: content hash of Exchange (signatures excluded).
000034 | - `pack_id`: content hash of Runtime Pack (as defined by Runtime Pack contract).
000035 | - `payload_hashes`: hashes of pack payload components (Parquet files, index files, etc.), as declared in the pack manifest.
000036 | 
000037 | ---
000038 | 
000039 | # 2. Exchange reproducibility tests (mandatory)
000040 | 
000041 | ## EX-1: Exchange hash determinism (same toolchain)
000042 | **Goal:** Exchange rebuild is byte-stable and ID-stable.
000043 | 
000044 | **Given**
000045 | - identical input snapshots
000046 | - identical compiler version
000047 | - identical config hash
000048 | - identical canonicalization profile/version
000049 | 
000050 | **Then**
000051 | - the rebuilt Exchange MUST produce the same `kristal_id`
000052 | - and the canonicalized Exchange bytes used for hashing MUST match (byte equality)
000053 | 
000054 | **Failure**
000055 | - If `kristal_id` differs, build is non-reproducible → FAIL.
000056 | 
000057 | ---
000058 | 
000059 | ## EX-2: Exchange hash determinism (cross toolchain)
000060 | **Goal:** Independent implementations converge on the same ID.
000061 | 
000062 | **Given**
000063 | - a published Exchange fixture + expected `kristal_id`
000064 | - canonicalization defined as RFC 8785 (JCS)
000065 | 
000066 | **Then**
000067 | - any v3 core conformant implementation MUST compute the expected `kristal_id`.
000068 | 
000069 | **Failure**
000070 | - mismatch → FAIL (interop-breaking).
000071 | 
000072 | ---
000073 | 
000074 | ## EX-3: Signature envelope invariance
000075 | **Goal:** Signature presence does not alter the hashed payload.
000076 | 
000077 | **Given**
000078 | - an Exchange artifact `E0` without signatures
000079 | - a signed Exchange artifact `E1` containing signatures in the signature envelope
000080 | 
000081 | **Then**
000082 | - the hash input (`exchange_without_signatures`) MUST be identical for `E0` and `E1`
000083 | - `kristal_id(E0)` MUST equal `kristal_id(E1)`
000084 | 
000085 | **Failure**
000086 | - if signatures affect hash input → FAIL.
000087 | 
000088 | ---
000089 | 
000090 | ## EX-4: Fail-closed verification (Exchange)
000091 | **Goal:** declared integrity cannot be ignored.
000092 | 
000093 | **Given**
000094 | - an Exchange artifact that declares a hash/signature
000095 | - a verifier implementation
000096 | 
000097 | **Then**
000098 | - verifier MUST error if:
000099 |   - signature verification fails
000100 |   - declared hash does not match computed hash
000101 |   - integrity material is malformed/ambiguous
000102 | 
000103 | **Failure**
000104 | - verifier continues “best effort” → FAIL.
000105 | 
000106 | ---
000107 | 
000108 | # 3. Runtime Pack reproducibility tests (mandatory)
000109 | 
000110 | ## RP-1: Pack rebuild determinism (same toolchain)
000111 | **Goal:** same inputs → identical pack.
000112 | 
000113 | **Given**
000114 | - identical input snapshots
000115 | - identical compiler identity + version
000116 | - identical config hash
000117 | - identical policy selections
000118 | 
000119 | **Then**
000120 | - rebuilt Runtime Pack MUST produce identical:
000121 |   - `pack_id`
000122 |   - `payload_hashes` (for each payload component)
000123 |   - `policy_selections` recorded in manifest
000124 | 
000125 | **Failure**
000126 | - any mismatch → FAIL.
000127 | 
000128 | ---
000129 | 
000130 | ## RP-2: Pack determinism under stable ordering policy
000131 | **Goal:** ordering is not implementation-dependent.
000132 | 
000133 | **Given**
000134 | - a fixed ordering policy (e.g., `ORDER_SET([SPO])`)
000135 | - a fixed tie-breaker rule (including `claim_id`)
000136 | 
000137 | **Then**
000138 | - the triples table ordering MUST be identical between rebuilds
000139 | - and consistent across platforms (Windows/Linux/macOS) for the same toolchain.
000140 | 
000141 | **Failure**
000142 | - any reordering → FAIL.
000143 | 
000144 | ---
000145 | 
000146 | ## RP-3: Row-group policy determinism
000147 | **Goal:** row-group assignment is deterministic.
000148 | 
000149 | **Given**
000150 | - a declared row-group policy (e.g., `FIXED_ROWS(500000)`)
000151 | 
000152 | **Then**
000153 | - the boundaries of row-groups MUST be identical across rebuilds
000154 | - and MUST NOT depend on unstable runtime factors (thread scheduling, CPU count, memory pressure)
000155 | 
000156 | **Failure**
000157 | - row-group boundaries differ → FAIL.
000158 | 
000159 | ---
000160 | 
000161 | ## RP-4: Membership filter determinism
000162 | **Goal:** filter metadata and behavior are reproducible.
000163 | 
000164 | **Given**
000165 | - membership filter policy declared (e.g., `BINARY_FUSE`)
000166 | - declared parameters (seed(s), bits-per-key, variant, key-space encoding)
000167 | 
000168 | **Then**
000169 | - the filter construction MUST be identical across rebuilds
000170 | - filter metadata recorded in manifest MUST match exactly
000171 | 
000172 | **And**
000173 | - filter false positives MUST be pruned deterministically against authoritative data
000174 | 
000175 | **Failure**
000176 | - filter differs under same seeds/params → FAIL.
000177 | 
000178 | ---
000179 | 
000180 | ## RP-5: Bitmap determinism (Roaring + run optimization)
000181 | **Goal:** bitmap encoding does not drift.
000182 | 
000183 | **Given**
000184 | - bitmap policy `ROARING`
000185 | - run optimization flag ENABLED or DISABLED
000186 | 
000187 | **Then**
000188 | - emitted bitmap files (or their declared hashes) MUST match across rebuilds.
000189 | 
000190 | **Failure**
000191 | - mismatch → FAIL.
000192 | 
000193 | ---
000194 | 
000195 | ## RP-6: Fail-closed verification (Runtime Pack)
000196 | **Goal:** declared integrity cannot be ignored.
000197 | 
000198 | **Given**
000199 | - a Runtime Pack that declares payload hashes and/or signatures
000200 | 
000201 | **Then**
000202 | - pack loaders/verifiers MUST error if:
000203 |   - any payload hash mismatch occurs
000204 |   - any declared signature fails verification
000205 |   - integrity fields are malformed/ambiguous
000206 | 
000207 | **Failure**
000208 | - “load anyway” behavior → FAIL.
000209 | 
000210 | ---
000211 | 
000212 | # 4. Cross-platform reproducibility tests (recommended)
000213 | 
000214 | ## XP-1: Cross-OS rebuild reproducibility
000215 | **Goal:** avoid platform-specific drift.
000216 | 
000217 | **Run**
000218 | - Build the same inputs/config/policies on at least two OS environments.
000219 | 
000220 | **Then**
000221 | - Exchange `kristal_id` MUST match.
000222 | - Runtime Pack `pack_id` and payload hashes SHOULD match.
000223 | 
000224 | **Note**
000225 | If exact Runtime Pack bit identity is not feasible cross-OS due to dependency formats, the implementation MUST:
000226 | - declare which payload components are excluded from the reproducibility surface, and
000227 | - provide a deterministic canonical representation for pack identity.
000228 | 
000229 | ---
000230 | 
000231 | # 5. Performance and resource invariants (recommended)
000232 | 
000233 | These are not core determinism requirements, but SHOULD be recorded for operational predictability:
000234 | - build wall time
000235 | - peak memory
000236 | - pack size
000237 | - index sizes (bitmaps, filters)
000238 | 
000239 | If recorded, these MUST NOT affect core identity unless explicitly included in the declared reproducibility surface.
000240 | 
000241 | ---
000242 | 
000243 | # 6. Test artifacts and fixtures
000244 | 
000245 | Implementations MUST provide:
000246 | - Exchange fixtures + expected `kristal_id`
000247 | - Runtime Pack fixtures + expected `pack_id` + expected payload hashes
000248 | - JCS canonicalization vectors + expected hashes
000249 | - Query fixtures for stable paging (cursor/offset), join caps, and error modes
000250 | 
000251 | See `09-test-vectors/` and `10-examples/`.
000252 | 
000253 | ---
000254 | 
000255 | # 7. Definition of done (reproducibility)
000256 | 
000257 | A Kristal v4 implementation passes reproducibility if:
000258 | - All Exchange tests EX-1 through EX-4 pass (mandatory).
000259 | - All Runtime Pack tests RP-1 through RP-6 pass (mandatory).
000260 | - Cross-platform test XP-1 is run for at least one release candidate (recommended).
000261 | 
000262 | Failure of any mandatory test blocks release of v3 artifacts.
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/03-reproducibility/subset-recipes.md"
id=35295fac5daa
kind=markdown
size=25853
lines=1009
line_ref=1-1009
chunks=3
chunk_refs=1-350,351-700,701-1009
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=35295fac5daa:1-350
start=1
end=350
----
# Subset recipes (Kristal v5 reproducibility)

## Status

Draft (normative for subset builder reproducibility)

## Purpose

A **subset recipe** is a declarative, reproducible input that defines how to derive a **deterministic subset** of a larger source snapshot so that the resulting Kristal artifacts are reproducible and comparable across toolchains.

Subset recipes are first-class in Kristal v5. They specify seeds, deterministic expansion rules, allow/deny constraints, depth limits, stopping criteria, reader-policy constraints, authority constraints, and snapshot identifiers.

A subset recipe may be used to produce:

* a Structured Epistemic State;
* a Working Exchange;
* a Reference Exchange;
* a Runtime Pack;
* a shard;
* a federation member;
* a reader-policy-specific package.

Subset recipes are part of the build input snapshot. If a recipe affects selected entities, statements, assertions, evidence, authority recognition records, validation decisions, or output bytes, it MUST be recorded in the relevant manifest or build record.

Normative keywords: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY.

---

## 1. Scope and non-goals

### 1.1 In scope

This document defines:

* recipe object model;
* recipe identity;
* deterministic subset selection;
* deterministic expansion rules;
* deterministic filtering by source, scope, status, certainty, validation, recognition, and authority channel;
* deterministic truncation and stopping criteria;
* how subset recipes participate in build determinism;
* how to record recipe references in Exchange, Runtime Pack, shard, federation, and build manifests.

### 1.2 Out of scope

This document does not define:

* full Wikidata subset research algorithms;
* ranking algorithms outside declared deterministic policies;
* runtime query behavior;
* reader UI behavior;
* Runtime Pack layout policies;
* authority governance procedures;
* validation policy semantics beyond deterministic filtering and recording.

For query/runtime behavior, see:

```text
04-query/query-contract.md
```

For Runtime Pack layout policies, see:

```text
03-reproducibility/allowed-runtime-pack-policies.md
```

For reader policy behavior, see:

```text
04-query/reader-policy-profiles.md
```

---

## 2. Determinism contract

### 2.1 Deterministic subset requirement

Given identical:

* source snapshot;
* subset recipe;
* compiler identity and version;
* declared source profiles;
* declared policies;
* declared authority registry;
* declared validation and recognition inputs;
* declared reader policy inputs;
* declared stopping and ordering rules;

the subset builder MUST produce identical selected sets.

Selected sets may include:

* selected entities;
* selected properties;
* selected statements;
* selected assertions;
* selected qualifiers;
* selected references;
* selected labels, aliases, and descriptions;
* selected evidence blobs;
* selected provenance records;
* selected validation decisions;
* selected authority recognition records;
* selected revocation records;
* selected reader policy records.

The selected sets MUST therefore be able to reproduce identical downstream artifacts when compiled under the same deterministic build rules.

### 2.2 Offline constraint

Subset evaluation MUST be executable without network access.

Any external dependency MUST be represented as a content-addressed input snapshot referenced by the recipe or by the build manifests.

Mutable live network state MUST NOT affect subset selection unless it has first been pinned into a content-addressed snapshot.

### 2.3 Selection does not imply validation

Selecting an assertion into a subset does not validate it.

Selecting a source, entity, claim, assertion, evidence reference, validation decision, or authority recognition record only means that it is included in the selected material.

Validation, certainty, and authority recognition remain explicit metadata and MUST NOT be inferred from inclusion alone.

---

## 3. Recipe identity

### 3.1 `recipe_id`

A subset recipe MUST have a stable content-addressed identifier:

```text
recipe_id = "sha256:" + hex(SHA-256(JCS(hash_target(recipe))))
```

Where:

* `JCS` is RFC 8785 JSON Canonicalization Scheme;
* `hash_target(recipe)` is the recipe object after applying required exclusions.

The v5 canonicalization values are:

```text
canonicalization_profile = "kristal.v5:jcs-rfc8785"
canonicalization_version = "1"
```

### 3.2 Hash target exclusions

The recipe hash target MUST exclude:

* `recipe_id`;
* `signatures`;
* signature envelopes;
* attestation overlays;
* proof overlays;
* any equivalent non-content verification wrapper.

`created_at` MAY appear on recipe objects, but it MUST NOT affect `recipe_id` unless a profile explicitly includes it in the hash target.

### 3.3 Canonical recipe representation

The normative recipe format is a JSON object.

If a producer stores recipes in another syntax, such as YAML or TOML, it MUST define a deterministic mapping into the normative JSON object prior to hashing.

The resulting JSON object MUST be the one used to compute `recipe_id`.

---

## 4. Recipe object model

A conforming recipe MUST be a JSON object with the following top-level fields.

### 4.1 Required fields

* `schema_version`

  * MUST be `"5.0"`.
* `artifact_type`

  * MUST be `"subset_recipe"`.
* `recipe_id`

  * MUST be present and MUST match the computed content-addressed ID.
* `canonicalization_profile`

  * MUST be `"kristal.v5:jcs-rfc8785"`.
* `canonicalization_version`

  * MUST be `"1"`.
* `source_snapshot_ref`

  * Content-addressed reference to the upstream dataset, corpus, Structured Epistemic State, Exchange, shard, federation, or other source snapshot.
* `seeds`

  * Seed sets that anchor the subset.
* `expansion`

  * Deterministic expansion rules.
* `constraints`

  * Allow/deny lists and other eligibility guards.
* `stopping`

  * Depth, budget, and termination rules.

### 4.2 Optional fields

* `recipe_version`

  * Human-managed semantic version for the recipe’s intent.
  * Does not replace `recipe_id`.
* `created_at`

  * Timestamp for recipe production.
  * MUST NOT affect `recipe_id` unless explicitly included by profile.
* `created_by`

  * Creator metadata.
* `description`

  * Human-readable description.
* `scope`

  * Declared recipe scope.
* `profiles_enabled`

  * Optional profiles that affect selection behavior.
* `reader_policy_ref`

  * Reader policy used as a selection constraint.
* `authority_registry_ref`

  * Authority registry used for authority-channel constraints.
* `validation_policy_refs`

  * Validation policies used for filtering or inclusion.
* `recognition_policy_refs`

  * Recognition policies used for filtering or inclusion.
* `signatures`

  * Optional signatures.
  * MUST NOT affect `recipe_id`.
* `extensions`

  * Implementation-specific fields that MUST NOT change core identity or deterministic selection semantics unless a profile explicitly defines them.

---

## 5. Source snapshot references

### 5.1 Source kinds

A subset recipe MAY target any source snapshot kind declared by Kristal v5, including:

* `wikidata_snapshot`;
* `wikibase_snapshot`;
* `structured_epistemic_state`;
* `working_exchange`;
* `reference_exchange`;
* `runtime_pack`;
* `exchange_shard`;
* `exchange_federation`;
* `dataset`;
* `evidence_bundle`;
* `authority_registry`;
* `validation_decision_set`;
* `authority_recognition_set`.

### 5.2 Source reference shape

A source snapshot reference SHOULD include:

```json
{
  "artifact_id": "sha256:<hex>",
  "artifact_type": "wikidata_snapshot",
  "ref": "snapshots/wikidata/full-2026-01.json",
  "content_hash": {
    "alg": "sha256",
    "value": "<64 lowercase hexadecimal characters>"
  }
}
```

### 5.3 Source stability

The source snapshot MUST be immutable for the purposes of recipe evaluation.

If the upstream source changes, a new source snapshot identifier MUST be used.

---

## 6. Seeds

### 6.1 Seed kinds

`seeds` MUST include at least one seed set.

Seed sets MAY include:

* `entity_ids`;
* `property_ids`;
* `statement_ids`;
* `assertion_ids`;
* `shard_ids`;
* `authority_channel_ids`;
* `validation_decision_ids`;
* `recognition_ids`;
* `dataset_ids`;
* `evidence_ids`;
* `scope_selectors`;
* `query_patterns`.

### 6.2 Entity, property, and statement seeds

For Wikidata/Wikibase-aligned sources:

* `entity_ids` SHOULD use stable entity identifiers, such as QID-like strings.
* `property_ids` SHOULD use stable property identifiers, such as PID-like strings.
* `statement_ids` SHOULD use stable statement identifiers where available.

### 6.3 Assertion seeds

For Kristal-native sources:

* `assertion_ids` SHOULD use stable content-addressed assertion IDs.
* Assertion seeds MUST NOT imply validation or recognition.
* Assertion status and certainty MUST be preserved during selection.

### 6.4 Scope selectors

Scope selectors MAY select material by:

* `domain`;
* `subdomain`;
* `jurisdiction`;
* `time_window`;
* `tenant_id`;
* `environment`;
* `language`.

### 6.5 Deterministic seed normalization

--- CHUNK END ---

--- CHUNK BEGIN ---
id=35295fac5daa:351-700
start=351
end=700
----
Before evaluation:

* seed arrays MUST be deduplicated;
* seed arrays MUST be sorted deterministically using stable byte-wise lexicographic order over their canonical string form;
* empty identifiers MUST be rejected;
* unknown identifiers MUST either be rejected or recorded as unresolved according to a declared policy;
* seed normalization MUST be independent of input file order.

---

## 7. Expansion rules

`expansion.rules` MUST be an array of rule objects.

Each rule object MUST have:

* `rule_id`

  * string, non-empty, unique within the recipe;
* `kind`

  * string enum or profile-defined rule kind;
* `params`

  * object containing parameters for the rule.

Rules are applied in a deterministic pipeline:

1. Seeds initialize the frontier at depth `0`.
2. For each depth `d` from `0` to `max_depth`, rules are applied in recipe order.
3. All sets produced at each step MUST be merged with deterministic deduplication and deterministic ordering.
4. Constraints are applied consistently.
5. Stopping criteria are applied deterministically.

### 7.1 Required portable baseline rule kinds

Implementations claiming conformance to the v5 subset-recipe baseline MUST implement the following rule kinds.

#### 7.1.1 `OUTGOING_EDGES`

Meaning:

For each entity or assertion in the frontier, include statements where the item is the subject, and optionally add referenced target entities to the next frontier.

Required params:

* `predicates`

  * array of property IDs, or `"*"`.
* `include_targets`

  * boolean.
* `include_qualifiers`

  * boolean.
* `include_references`

  * boolean.
* `include_assertion_metadata`

  * boolean.

#### 7.1.2 `INCOMING_EDGES`

Meaning:

For each entity in the frontier, include statements where the entity appears as an entity-valued object, and optionally add the statement subjects to the next frontier.

Required params:

* `predicates`

  * array of property IDs, or `"*"`.
* `include_subjects`

  * boolean.
* `include_qualifiers`

  * boolean.
* `include_references`

  * boolean.
* `include_assertion_metadata`

  * boolean.

#### 7.1.3 `TAXONOMY_CLOSURE`

Meaning:

Include closure over a declared taxonomy predicate set up to a bound.

Required params:

* `predicates`

  * array of property IDs.
* `direction`

  * `"up"`, `"down"`, or `"both"`.
* `max_hops`

  * integer greater than or equal to `1`.

#### 7.1.4 `LABELS_AND_DESCRIPTIONS`

Meaning:

Include label, alias, and description facts required for UX, query, or reader display.

Required params:

* `languages`

  * array of BCP-47 tags, or `"*"`.
* `include_aliases`

  * boolean.
* `include_descriptions`

  * boolean.

#### 7.1.5 `PROVENANCE_AND_EVIDENCE`

Meaning:

Include provenance and evidence records referenced by selected assertions or statements.

Required params:

* `include_provenance`

  * boolean.
* `include_evidence_refs`

  * boolean.
* `include_evidence_blobs`

  * boolean.
* `max_evidence_blobs`

  * integer greater than or equal to `0`, or `null`.

#### 7.1.6 `VALIDATION_DECISIONS`

Meaning:

Include validation decisions that target selected assertions, artifacts, shards, datasets, or authority channels.

Required params:

* `authority_channels`

  * array of authority channel IDs, or `"*"`.
* `validation_statuses`

  * array of validation statuses, or `"*"`.
* `validated_as`

  * array of validated-as modes, or `"*"`.
* `include_revoked`

  * boolean.

#### 7.1.7 `AUTHORITY_RECOGNITIONS`

Meaning:

Include authority recognition records that target selected assertions, artifacts, shards, datasets, runtime packs, or authority channels.

Required params:

* `authority_channels`

  * array of authority channel IDs, or `"*"`.
* `recognition_statuses`

  * array of recognition statuses, or `"*"`.
* `recognized_as`

  * array of recognized-as modes, or `"*"`.
* `include_revoked`

  * boolean.

#### 7.1.8 `READER_POLICY_CLOSURE`

Meaning:

Include metadata required to evaluate the declared reader policy offline.

Required params:

* `reader_policy_ref`

  * artifact reference or `"recipe.reader_policy_ref"`.
* `include_authority_registry`

  * boolean.
* `include_revocations`

  * boolean.
* `include_validation_policies`

  * boolean.
* `include_recognition_policies`

  * boolean.

### 7.2 Additional rule kinds

If an implementation supports additional rule kinds, they MUST be declared through `profiles_enabled`.

Additional rule kinds MUST remain:

* deterministic;
* testable;
* offline-evaluable;
* documented;
* portable within the declaring profile.

---

## 8. Constraints

`constraints` MUST include allow/deny fields.

### 8.1 Required constraint groups

A recipe MUST include:

* `allow_entities`;
* `deny_entities`;
* `allow_properties`;
* `deny_properties`.

Each field MUST be an array. Empty arrays are allowed.

### 8.2 Optional constraint groups

A recipe MAY include:

* `allow_assertions`;
* `deny_assertions`;
* `allow_authority_channels`;
* `deny_authority_channels`;
* `allow_validation_statuses`;
* `deny_validation_statuses`;
* `allow_recognition_statuses`;
* `deny_recognition_statuses`;
* `allow_certainty_levels`;
* `deny_certainty_levels`;
* `allow_validated_as`;
* `deny_validated_as`;
* `allow_domains`;
* `deny_domains`;
* `allow_scopes`;
* `deny_scopes`;
* `include_disputed`;
* `include_rejected`;
* `include_revoked`;
* `include_fictional`;
* `include_mythological`.

### 8.3 Constraint precedence

Deny lists MUST take precedence over allow lists.

If an allow list is non-empty, only identifiers or values present in it are eligible after applying deny precedence.

Constraints MUST apply consistently to:

* seed sets;
* expansion results;
* selected statements;
* selected assertions;
* next-frontier candidates;
* provenance records;
* evidence records;
* validation decisions;
* authority recognition records;
* reader policy closure records;
* truncation tie-breaking sets.

### 8.4 Reader policy constraints

If a recipe declares `reader_policy_ref`, the reader policy MAY constrain selection.

Reader policy constraints MUST be deterministic.

A reader policy MUST NOT silently convert scoped validation into universal truth.

A `validated_only` reader policy means all visible assertions satisfy the active reader policy. It does not mean all visible assertions are universally true, maximally certain, or accepted by all authorities.

---

## 9. Deterministic ordering and truncation

### 9.1 Stable ordering keys

All intermediate and final sets MUST be ordered deterministically.

The following ordering keys are normative unless a profile declares a different deterministic ordering policy.

#### Entity ordering key

Canonical string ID, byte-wise lexicographic.

#### Property ordering key

Canonical string ID, byte-wise lexicographic.

#### Statement ordering key

Preferred:

1. stable `statement_id`, if available;
2. otherwise deterministic surrogate key computed as JCS + SHA-256 over a canonical tuple of:

   * `subject_id`;
   * `predicate_id`;
   * `object_value`;
   * `qualifiers`;
   * `references`;
   * assertion metadata included in statement identity, if any.

#### Assertion ordering key

Preferred:

1. stable `assertion_id`, if available;
2. otherwise deterministic surrogate key computed as JCS + SHA-256 over the assertion hash target.

#### Evidence ordering key

Preferred:

1. stable `evidence_id`, if available;
2. otherwise content hash.

#### Validation decision ordering key

Preferred:

1. `validation_decision_id`;
2. otherwise deterministic surrogate key over target, authority channel, policy, status, scope, and created identity material.

#### Authority recognition ordering key

Preferred:
--- CHUNK END ---

--- CHUNK BEGIN ---
id=35295fac5daa:701-1009
start=701
end=1009
----

1. `recognition_id`;
2. otherwise deterministic surrogate key over issuer authority channel, target, recognition status, recognized-as mode, scope, and policy reference.

### 9.2 Budget limits and deterministic truncation

When a stopping or budget limit is reached, the subset builder MUST truncate deterministically.

It MUST:

* sort candidates by the relevant stable ordering key;
* select the first `N` items deterministically;
* record that truncation occurred;
* record which limit triggered truncation;
* record resulting counts.

Silent, undeclared truncation MUST NOT occur.

### 9.3 Truncation and epistemic status

Truncation MUST NOT imply rejection, low certainty, or invalidity.

If relevant material is omitted because of budget limits, the build metadata SHOULD make that visible to downstream consumers.

---

## 10. Stopping criteria

`stopping` MUST include:

* `max_depth`

  * integer greater than or equal to `0`;
* at least one global budget.

### 10.1 Required budget

At least one of the following MUST be present:

* `max_entities`;
* `max_statements`;
* `max_assertions`.

### 10.2 Optional budgets

A recipe MAY include:

* `max_properties`;
* `max_evidence_blobs`;
* `max_provenance_records`;
* `max_validation_decisions`;
* `max_authority_recognitions`;
* `max_frontier_per_depth`;
* `max_runtime_bytes_estimate`.

### 10.3 Stopping semantics

Depth is evaluated as BFS depth from seeds.

Budgets are global across the run unless a profile explicitly defines per-depth budgets.

When a frontier exceeds `max_frontier_per_depth`, the frontier MUST be truncated deterministically.

---

## 11. Recording subset recipes in manifests

Subset recipes participate in determinism as inputs.

### 11.1 Structured Epistemic State

If a Structured Epistemic State was produced using a subset recipe, the state SHOULD record the recipe reference.

Recommended location:

```text
source_refs[]
```

or:

```text
extensions.subset_recipe
```

The reference SHOULD include:

* `recipe_id`;
* `schema_version`;
* `source_snapshot_ref`;
* `content_hash`;
* `ref`, if available.

### 11.2 Working Exchange

If a subset recipe was used to produce a Working Exchange, the Exchange Manifest MUST record the recipe reference in a deterministic way.

Recommended location:

```text
inputs.subset_recipe
```

If the schema does not provide a dedicated field, producers SHOULD record:

```text
extensions.subset_recipe.recipe_id
extensions.subset_recipe.schema_version
extensions.subset_recipe.source_snapshot_ref
```

### 11.3 Reference Exchange

If a subset recipe affected the content of a Reference Exchange, the Reference Exchange MUST retain traceability to the recipe directly or through its source Working Exchange.

If the subset recipe affected authority recognition or validation inclusion, the relevant policy and recognition references MUST also be recorded.

### 11.4 Runtime Pack Manifest

If a Runtime Pack was compiled from an Exchange built via a subset recipe, the Runtime Pack Manifest SHOULD record the subset recipe reference directly or carry a deterministic pointer to the source Exchange Manifest.

If reader-policy filtering was applied during Runtime Pack compilation, the active reader policy MUST also be recorded.

### 11.5 Shard manifest

If a shard was produced using a subset recipe, the shard manifest MUST record the subset recipe reference.

The shard scope and recipe scope MUST be compatible, or the manifest MUST record the reason for the mismatch under a deterministic reason code.

### 11.6 Federation manifest

If a federation includes shards selected by subset recipes, the federation manifest SHOULD preserve recipe references through shard references.

If the federation itself was produced by a recipe, the federation manifest MUST record that recipe reference.

---

## 12. Conformance tests

Implementations SHOULD add subset recipe fixtures to the reproducibility test corpus.

### 12.1 Required test categories

Conformance tests SHOULD include:

* same toolchain reproducibility;
* cross-toolchain reproducibility;
* budget truncation;
* seed normalization;
* source snapshot pinning;
* stable `recipe_id` computation;
* deterministic evidence selection;
* deterministic validation-decision selection;
* deterministic authority-recognition selection;
* reader-policy-filtered selection;
* revoked target exclusion or inclusion according to policy;
* federation member selection.

### 12.2 Suggested fixtures

#### SR-1: Same toolchain

Same `source_snapshot_ref` and same recipe JSON produce identical selected sets.

#### SR-2: Cross toolchain

Published recipe fixture with expected `recipe_id` and expected selected-set hashes matches independent implementations.

#### SR-3: Budget truncation

Force truncation and verify deterministic truncation plus explicit truncation declaration.

#### SR-4: Reader policy

Apply a `validated_only` reader policy and verify that visible assertions satisfy the policy without changing underlying assertion meaning.

#### SR-5: Authority recognition

Select only assertions recognized by a specified authority channel and verify deterministic inclusion.

#### SR-6: Disagreement preservation

Select conflicting assertions from different shards and verify that disagreement is preserved unless a declared policy filters one side.

#### SR-7: Revocation behavior

Select authority recognition records and apply revocations according to declared policy.

---

## 13. Minimal example

The following example is non-normative.

```json
{
  "schema_version": "5.0",
  "artifact_type": "subset_recipe",
  "recipe_id": "sha256:<computed>",
  "canonicalization_profile": "kristal.v5:jcs-rfc8785",
  "canonicalization_version": "1",

  "source_snapshot_ref": {
    "artifact_id": "sha256:<snapshot>",
    "artifact_type": "wikidata_snapshot",
    "ref": "snapshots/wikidata/full.json",
    "content_hash": {
      "alg": "sha256",
      "value": "<64 lowercase hexadecimal characters>"
    }
  },

  "description": "Small deterministic subset for an offline education pack.",

  "scope": {
    "domain": "education",
    "subdomain": "general-reference",
    "language": "en"
  },

  "seeds": {
    "entity_ids": ["Q1", "Q42"],
    "property_ids": ["P31"],
    "statement_ids": [],
    "assertion_ids": []
  },

  "expansion": {
    "rules": [
      {
        "rule_id": "r1",
        "kind": "OUTGOING_EDGES",
        "params": {
          "predicates": "*",
          "include_targets": true,
          "include_qualifiers": true,
          "include_references": true,
          "include_assertion_metadata": true
        }
      },
      {
        "rule_id": "r2",
        "kind": "LABELS_AND_DESCRIPTIONS",
        "params": {
          "languages": ["en", "fr"],
          "include_aliases": true,
          "include_descriptions": true
        }
      },
      {
        "rule_id": "r3",
        "kind": "PROVENANCE_AND_EVIDENCE",
        "params": {
          "include_provenance": true,
          "include_evidence_refs": true,
          "include_evidence_blobs": false,
          "max_evidence_blobs": 0
        }
      }
    ]
  },

  "constraints": {
    "allow_entities": [],
    "deny_entities": [],
    "allow_properties": [],
    "deny_properties": [],

    "allow_assertions": [],
    "deny_assertions": [],

    "allow_authority_channels": [],
    "deny_authority_channels": [],

    "allow_validation_statuses": [],
    "deny_validation_statuses": [],

    "allow_recognition_statuses": [],
    "deny_recognition_statuses": [],

    "allow_certainty_levels": [],
    "deny_certainty_levels": [],

    "allow_validated_as": [],
    "deny_validated_as": [],

    "allow_domains": ["education", "wikidata"],
    "deny_domains": [],

    "allow_scopes": [],
    "deny_scopes": [],

    "include_disputed": true,
    "include_rejected": false,
    "include_revoked": false,
    "include_fictional": false,
    "include_mythological": false
  },

  "stopping": {
    "max_depth": 2,
    "max_entities": 50000,
    "max_statements": 200000,
    "max_assertions": 200000,
    "max_evidence_blobs": 0,
    "max_frontier_per_depth": 10000
  }
}
```
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/04-query/query-contract.md"
id=78e1d3d41ce2
kind=markdown
size=23831
lines=731
line_ref=1-731
chunks=3
chunk_refs=1-350,351-700,701-731
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=78e1d3d41ce2:1-350
start=1
end=350
----
# Query Contract

## Status

Draft — Kristal v5

## Purpose

This document defines the **offline query contract** for Kristal v5 **Runtime Packs** and any local wrapper service that exposes them.

The goal is a **portable, deterministic, offline-usable** query surface that supports common retrieval needs: search/navigation primitives, constrained graph lookups, assertion-status filters, validation filters, certainty filters, authority-channel filters, and reader-policy views.

This contract is intentionally constrained to preserve offline predictability, reproducibility, and local execution. It does not attempt to implement full SPARQL.

---

## 1. Scope and non-goals

### 1.1 In scope

This contract covers:

* a triple-pattern query model over `(s, p, o)` with any subset bound or unbound;
* deterministic result ordering derived from recorded Runtime Pack policies;
* deterministic paging by cursor or offset;
* deterministic behavior for declared resource limits;
* optional constrained joins;
* optional cardinality metadata;
* explicit support for reader-policy filtering;
* explicit support for validation, certainty, scope, authority-channel, and recognition filters;
* offline query behavior over a local Runtime Pack.

### 1.2 Out of scope

This contract does not require:

* full SPARQL 1.1 semantics;
* `OPTIONAL`;
* `UNION`;
* arbitrary `FILTER` expressions;
* property paths;
* subqueries;
* federated network queries;
* runtime dependence on live Wikidata, live SPARQL endpoints, LLM calls, or remote authority services;
* non-deterministic query behavior;
* adaptive sampling unless declared by a profile.

A Runtime Pack may be derived from Wikidata, Wikibase, RDF, JSON-LD, internal datasets, institutional corpora, fictional corpora, mythological corpora, or research submissions. The query contract only defines how local query behavior must be exposed once the pack exists.

---

## 2. Core model

A Kristal Runtime Pack exposes structured epistemic data.

A query result may include facts, claims, hypotheses, disputed statements, fictional statements, mythological statements, institutional declarations, or high-confidence reference assertions. The query layer must not hide the status of those assertions when the pack contains that metadata.

Kristal v5 separates:

* artifact existence;
* artifact integrity;
* assertion status;
* certainty level;
* validation status;
* authority recognition;
* reader visibility.

Query implementations must preserve that separation.

A query result being returned does not mean the claim is universally true. It means the claim exists in the pack and is visible under the active query parameters and reader policy.

---

## 3. Terminology

* **Term**: a subject, property, object identifier, or literal.
* **Triple**: `(s, p, o)` where `s` and `p` are identifiers and `o` is an identifier or literal.
* **Triple pattern**: a triple where any of `s`, `p`, or `o` may be unbound.
* **Binding**: a concrete value for an unbound position.
* **Result set**: ordered list of matching triples, bindings, statements, or assertion views.
* **Statement**: a claim-like unit that may include qualifiers, references, rank, provenance, status, certainty, and authority metadata.
* **Assertion**: an epistemic statement with status, certainty, provenance, and scope.
* **Assertion status**: status such as `hypothesis`, `claimed`, `sourced`, `disputed`, `reviewed`, `validated`, `rejected`, `retracted`, or `superseded`.
* **Certainty level**: strength of the assertion within its scope, such as `unknown`, `speculative`, `low`, `medium`, `high`, `established`, or `not_applicable`.
* **Validation status**: decision status such as `not_evaluated`, `in_review`, `validated`, `conditionally_validated`, `disputed`, `rejected`, or `revoked`.
* **Validated as**: the epistemic mode under which an assertion was validated, such as `hypothesis`, `institutional_reference`, `publisher_declaration`, `mythological_corpus`, or `fictional_corpus`.
* **Authority channel**: declared authority under which a claim, artifact, shard, or pack is validated, recognized, rejected, or disputed.
* **Recognition status**: authority-recognition state such as `recognized`, `conditionally_recognized`, `under_review`, `disputed`, `rejected`, `deprecated`, or `revoked`.
* **Reader policy**: a declared visibility policy that determines which authority channels, validation statuses, certainty levels, and epistemic modes are included.
* **Paging mode**: either `CURSOR` or `OFFSET`, as recorded in pack policies.
* **Cursor**: opaque paging token that resumes iteration deterministically.
* **Offset paging**: deterministic paging by `(offset, limit)` against a deterministic ordering.
* **Page size**: number of results requested per page. This is `limit` in the core contract. Profiles may name it `page_size`.
* **join1**: constrained two-stage lookup pattern with a declared cap and strictness mode.

Normative keywords: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY.

---

## 4. Query model

### 4.1 Required query primitive

An implementation MUST support querying a single triple pattern.

Inputs:

* `s` — bound or unbound;
* `p` — bound or unbound;
* `o` — bound or unbound;
* `limit` — positive integer page size;
* paging parameters according to the pack’s declared paging mode.

Output:

* an ordered sequence of results, each result containing either:

  * matching triples `(s, p, o)`;
  * bindings for unbound positions;
  * statement objects;
  * assertion objects;
  * or a declared stable combination of the above.

Implementations MUST document which output shape they use and MUST keep it stable within a declared `contract_id`.

### 4.2 Required metadata preservation

If the Runtime Pack contains the following metadata, the query layer MUST be able to expose it either inline or through an explicitly declared expansion/profile:

* assertion identifier;
* assertion status;
* certainty level;
* validation status;
* validated-as mode;
* authority channel;
* recognition status;
* provenance references;
* evidence references;
* scope;
* source shard;
* source artifact;
* lineage reference;
* dispute/conflict marker.

A query surface MAY offer compact results by default, but it MUST document how clients can request or resolve the status-bearing form when supported by the pack.

### 4.3 Determinism

Given:

* identical Runtime Pack bytes;
* identical recorded portable policy selections;
* identical query inputs;
* identical reader policy;
* identical wrapper configuration;

the implementation MUST return:

* identical result ordering;
* identical paging behavior;
* identical cap behavior;
* identical error behavior.

---

## 5. Data model constraints

### 5.1 Identifiers and literals

Subjects and properties MUST be represented in a stable identifier space, such as QID/PID-like strings or an equivalent stable encoding.

Literal normalization rules for numbers, dates, time zones, language tags, units, and datatypes MUST be deterministic and MUST be consistent with the Runtime Pack manifest or a referenced normalization profile.

### 5.2 Statement projections

Runtime Packs MUST define whether the runtime query surface returns:

* the full statement set;
* a best-rank or truthy-like projection;
* a reader-policy-filtered projection;
* a scope-filtered projection;
* or multiple named projections.

If a truthy-like projection is supported, mapping rules MUST be deterministic and documented.

If only export profiles define truthy-like behavior and the runtime does not, the runtime MUST state that clearly.

### 5.3 Assertion-status projection

A Runtime Pack MAY expose statement triples without assertion metadata for compact query use. However, if the pack supports v5 assertion metadata, the query contract SHOULD expose at least one projection that preserves:

* assertion status;
* certainty level;
* validation status;
* authority channel;
* recognition status;
* scope.

Recommended projection names:

* `triples`;
* `statements`;
* `assertions`;
* `reference_view`;
* `validated_view`;
* `reader_policy_view`.

---

## 6. Reader-policy filtering

### 6.1 Purpose

Reader policies allow people and applications to choose what they want to see.

Examples:

* `reference_only`;
* `validated_only`;
* `high_certainty_only`;
* `research`;
* `creative`;
* `all_with_labels`;
* `custom`.

A reader policy is not a truth engine. It is a visibility rule.

### 6.2 Required reader-policy declaration

If a Runtime Pack supports reader-policy filtering, the manifest SHOULD reference one or more reader policies through `reader_policy_refs`.

The query contract SHOULD expose the active reader policy in responses, either by ID or resolved metadata.

### 6.3 Reader-policy inputs

A query MAY include:

* `reader_policy_id`;
* `reader_mode`;
* `allowed_authority_channels`;
* `allowed_validation_statuses`;
* `allowed_certainty_levels`;
* `allowed_validated_as`;
* `include_disputed`;
* `include_fictional`;
* `include_mythological`;
* `include_rejected`;
* `show_labels`.

If the query surface does not allow arbitrary inline reader-policy parameters, it MUST document the supported named reader policies.

### 6.4 Validated-only behavior

`validated_only` means:

* all visible assertions satisfy the active validation policy;
* validation is scoped by authority, policy, and domain;
* visible assertions may still have different certainty levels;
* visible assertions may be validated as hypotheses, institutional records, publisher declarations, mythological corpora, fictional corpora, disputed positions, or high-confidence facts.

`validated_only` MUST NOT be interpreted as:

* all visible assertions have maximum certainty;
* all authorities agree;
* every assertion is universally true;
* every assertion is a physical-world factual claim.

---

## 7. Filters

### 7.1 Core triple filters

The query primitive MUST support:

* `s`;
* `p`;
* `o`.

### 7.2 Recommended v5 epistemic filters

If the pack contains the relevant metadata, implementations SHOULD support filters for:

* `artifact_status`;
* `assertion_status`;
* `certainty_level`;
* `validation_status`;
* `validated_as`;
* `authority_channel`;
* `recognition_status`;
* `scope.domain`;
* `scope.subdomain`;
* `scope.jurisdiction`;
* `scope.language`;
* `source_shard`;
* `source_artifact`;
* `reader_policy`.

### 7.3 Disagreement filters

If the pack supports federation or conflict metadata, implementations SHOULD support:

* `include_disputed`;
* `include_conflicts`;
* `conflict_strategy`;
* `authority_precedence`;
* `show_disagreement`.

Default behavior SHOULD be determined by the active reader policy.

### 7.4 Fiction, mythology, and symbolic scopes

If a pack contains fictional, mythological, symbolic, or speculative material, implementations SHOULD preserve those labels and SHOULD support filtering them through:

* `include_fictional`;
* `include_mythological`;
* `include_symbolic`;
* `include_speculative`;
* `validated_as`.

A query implementation MUST NOT silently present fictional or mythological assertions as validated physical-world truth.

---

## 8. Result ordering

### 8.1 Ordering policy

Result ordering MUST be derived from the Runtime Pack’s recorded ordering policy, such as `policies.data_ordering`.

Implementations MUST NOT use implementation-dependent iteration order.

### 8.2 Stable tie-breakers

If multiple rows compare equal under the primary ordering keys, implementations MUST define stable tie-breakers so ordering is total and deterministic.

Possible tie-breakers:

* statement ID;
* assertion ID;
* shard ID;
* source row ID;
* content hash;
* stable lexical ordering.

### 8.3 Ordering disclosure

Implementations MUST document:

* primary ordering keys;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=78e1d3d41ce2:351-700
start=351
end=700
----
* tie-breakers;
* whether ordering is over triples, statements, assertions, or bindings;
* whether filtering happens before or after ordering;
* whether paging happens before or after policy filtering.

Recommended rule:

* filtering SHOULD happen before paging;
* ordering SHOULD happen after filtering;
* paging SHOULD apply to the ordered, filtered result set.

---

## 9. Resource limits and join caps

### 9.1 Required limits

Implementations MUST declare, at minimum:

* maximum allowed page size: `limit_max`;
* timeout policy, if any;
* memory/resource cap policy, if any;
* join cap policy if `join1` is supported:

  * `join1_cap.default`;
  * `join1_cap.mode`.

These MUST be surfaced in either:

* the Runtime Pack manifest;
* the query contract;
* or the local wrapper configuration if the wrapper is the enforcement point.

They MUST remain deterministic for a given pack and configuration.

### 9.2 join1

If the runtime supports a constrained two-stage lookup, it MUST define `join1` explicitly.

Example:

1. Evaluate pattern A to produce intermediate bindings.
2. Bound intermediate bindings by `join1_cap.default`.
3. Use each binding to evaluate pattern B.
4. Combine results deterministically.
5. Apply declared ordering, filtering, and paging rules.

If `join1` is not supported, the implementation MUST reject such requests deterministically with a stable error code.

### 9.3 Cap breach behavior

When a cap is exceeded, behavior MUST be determined by the declared `join1_cap.mode`:

* `STRICT`: return an error response with a stable error code.
* `TRUNCATE`: truncate intermediate results deterministically and return `truncated=true` plus deterministic counts where feasible.

Silently truncating without a flag MUST NOT occur.

### 9.4 Recommended strictness

For correctness-sensitive views such as `reference_only`, `validated_only`, legal, health, scientific, or institutional reference contexts, `STRICT` is recommended.

For exploratory views such as `research`, `creative`, or `all_with_labels`, `TRUNCATE` MAY be acceptable when visibly declared.

---

## 10. Paging contract

An implementation MUST support exactly one declared paging mode per contract identifier:

* `CURSOR`; or
* `OFFSET`.

A Runtime Pack or wrapper MAY expose multiple query contracts if it supports multiple paging modes.

### 10.1 Cursor paging

If cursor paging is supported:

* the cursor MUST be opaque to callers;
* the cursor MUST resume iteration deterministically for the same pack, query inputs, reader policy, and wrapper configuration;
* the cursor MUST become invalid if the pack changes;
* the cursor MUST become invalid if query parameters change, unless explicitly supported;
* the cursor SHOULD encode or bind to the active reader policy.

Core response fields:

* `next_cursor`;
* `has_more`.

### 10.2 Offset paging

If offset paging is supported:

* ordering MUST be deterministic;
* `(offset, limit)` MUST be deterministic over the filtered and ordered result set;
* responses SHOULD include:

  * `offset`;
  * `limit`;
  * `total`, if cheap or declared by a profile.

### 10.3 Pagination profile

If the pack claims `profile-query-tpf-pagination@v5`, the normative request/response envelope, stable-order requirements, and optional cardinality fields are defined by:

* `05-profiles/profile-query-tpf-pagination.md`.

This contract does not define a transport. A local wrapper MAY expose HTTP endpoints, file APIs, embedded APIs, WASM calls, or device-local APIs, but MUST preserve the profile’s normative behaviors and remain usable offline.

---

## 11. Error model

### 11.1 Stable error codes

Implementations MUST return stable, machine-readable error codes.

At minimum:

* `invalid_query_schema`;
* `invalid_parameter_type`;
* `unsupported_query_shape`;
* `unsupported_projection`;
* `unsupported_filter`;
* `unsupported_reader_policy`;
* `reader_policy_not_available`;
* `cap_exceeded`;
* `cursor_invalid`;
* `cursor_expired`;
* `pack_not_found`;
* `pack_integrity_failed`;
* `pack_signature_invalid`;
* `pack_not_accepted_by_policy`;
* `query_contract_mismatch`;
* `resource_limit_exceeded`;
* `internal_corruption`;
* `unsupported_profile`.

### 11.2 Deterministic error behavior

Errors MUST be deterministic for a given:

* pack;
* query input;
* reader policy;
* recorded policies;
* wrapper configuration.

### 11.3 Integrity-related errors

If a pack fails required integrity verification under the active query, reader, or activation policy, the implementation MUST NOT return results as trusted.

It SHOULD return a stable error such as:

* `pack_integrity_failed`;
* `pack_signature_invalid`;
* `pack_not_accepted_by_policy`.

An implementation MAY expose limited diagnostic metadata if allowed by policy, but it MUST clearly mark the pack as unavailable for trusted query use.

---

## 12. Optional cardinality metadata

If the pack declares cardinality estimates as supported, responses MAY include a `cardinality` object:

```json
{
  "type": "exact",
  "value": 42,
  "scope": "pattern"
}
```

Allowed fields:

* `type`: `exact` or `approx`;
* `value`: integer;
* `bounds`: optional `{ "lower": int, "upper": int }`;
* `confidence`: optional float in `[0,1]`;
* `scope`: for example `pattern`, `pattern+projection`, `pattern+reader_policy`, or `pattern+filters`.

Rules:

* If `type = "exact"`, `value` MUST be correct.
* If `type = "approx"`, the implementation MUST document the approximation method.
* Cardinality MUST specify whether it is counted before or after reader-policy filtering.
* Cardinality MUST specify whether it is counted before or after authority, validation, and certainty filters.

---

## 13. Query request shape

This contract does not require one transport, but implementations SHOULD expose an equivalent request shape.

Example:

```json
{
  "contract_id": "kristal.v5:query:triple-pattern@1",
  "projection": "assertions",
  "pattern": {
    "s": "Q42",
    "p": null,
    "o": null
  },
  "filters": {
    "reader_policy_id": "reader_policy:validated-only-global-reference",
    "authority_channel": ["authority:unesco-global-reference"],
    "validation_status": ["validated", "conditionally_validated"],
    "certainty_level": ["medium", "high", "established"],
    "include_disputed": false,
    "include_fictional": false,
    "include_mythological": false
  },
  "paging": {
    "mode": "CURSOR",
    "limit": 100,
    "cursor": null
  },
  "include": {
    "labels": true,
    "provenance": true,
    "validation": true,
    "recognition": true,
    "certainty": true,
    "scope": true
  }
}
```

---

## 14. Query response shape

Implementations SHOULD expose an equivalent response shape.

Example:

```json
{
  "contract_id": "kristal.v5:query:triple-pattern@1",
  "runtime_pack_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "source_exchange_id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "projection": "assertions",
  "reader_policy_id": "reader_policy:validated-only-global-reference",
  "results": [
    {
      "s": "Q42",
      "p": "P31",
      "o": "Q5",
      "assertion_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "assertion_status": "validated",
      "validation_status": "validated",
      "validated_as": "high_confidence_fact",
      "certainty_level": "established",
      "authority_channel": "authority:wikidata-seed",
      "recognition_status": "recognized",
      "scope": {
        "domain": "wikidata",
        "subdomain": null,
        "jurisdiction": null,
        "time_window": null,
        "tenant_id": null,
        "environment": null,
        "language": "en"
      },
      "provenance_refs": [],
      "evidence_refs": []
    }
  ],
  "paging": {
    "next_cursor": null,
    "has_more": false
  },
  "diagnostics": {
    "truncated": false,
    "filters_applied_before_paging": true,
    "ordering_policy": "qid_pid_statement_id_asc"
  }
}
```

---

## 15. Manifest requirements

### 15.1 Contract declaration

A Runtime Pack that claims conformance to this query contract SHOULD declare `query_contract_ref` in the Runtime Pack Manifest.

Recommended fields:

* `query_contract_ref.contract_id`;
* `query_contract_ref.contract_hash`;
* `query_contract_ref.contract_version`.

If the pack claims a pagination profile, it MUST also declare pagination support in `query_capabilities`.

If the pack supports cardinality metadata, it SHOULD declare that in `query_capabilities`.

### 15.2 Policy linkage

To interpret query behavior deterministically, the Runtime Pack Manifest MUST record or reference the portable policy selections that govern:

* ordering;
* paging mode;
* join caps;
* strictness mode;
* projections;
* reader-policy availability;
* authority-channel filters;
* validation-status filters;
* certainty-level filters;
* scope filters.

These may be declared directly in the Runtime Pack Manifest or through referenced policies.

### 15.3 Reader-policy linkage

If reader-policy filtering is supported, the Runtime Pack Manifest SHOULD include `reader_policy_refs`.

Each referenced reader policy SHOULD declare:

* allowed authority channels;
* allowed validation statuses;
* allowed certainty levels;
* allowed validated-as modes;
* whether disputed material is included;
* whether fictional material is included;
* whether mythological material is included;
* whether labels must be shown;
* fallback behavior.

---

## 16. Conformance tests

A Kristal v5 implementation MUST ship fixtures or tests that validate:

* deterministic ordering for a known pack;
* stable paging across repeated runs;
* cap breach behavior matching declared strictness mode;
* stable error codes;
* projection behavior;
* reader-policy filtering;
* authority-channel filtering;
* validation-status filtering;
* certainty-level filtering;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=78e1d3d41ce2:701-731
start=701
end=731
----
* disputed-claim visibility;
* fictional/mythological scope visibility;
* integrity-error behavior;
* pagination profile behavior if enabled;
* cardinality behavior if enabled.

Test fixtures SHOULD include at least:

* a Wikidata-like factual statement;
* a sourced but not validated claim;
* a validated hypothesis;
* a high-certainty reference assertion;
* a disputed assertion;
* a fictional or mythological assertion;
* two authority channels that disagree;
* a reader policy that excludes one assertion and includes another.

---

## 17. Non-normative implementation notes

* Prefer cursor paging over offset for large packs.
* Enforce resource limits early to protect offline devices.
* Keep query wrappers small and deterministic.
* Avoid implementation-dependent iteration order.
* Do not hide assertion labels in user-facing views.
* Do not let reader-policy filtering silently remove disagreement without exposing that a filter is active.
* If a pack declares signatures or integrity hashes, verify according to the active reader, trust-root, or activation policy before returning trusted results.
* For strict institutional deployments, use `reference_only`, `validated_only`, or `high_certainty_only` reader policies.
* For research and creative deployments, use broader policies with labels visible.
* For mythology and fiction, use `validated_as` and `certainty_level = "not_applicable"` where physical-world certainty is not the right metric.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/04-query/reader-policy-profiles.md"
id=1b8c9e516342
kind=markdown
size=36538
lines=1473
line_ref=1-1473
chunks=5
chunk_refs=1-350,351-700,701-1050,1051-1400,1401-1473
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=1b8c9e516342:1-350
start=1
end=350
----
# Reader Policy Profiles

## Status

Draft (Kristal v5 normative query profile)

## Purpose

This document defines how Kristal v5 readers, query engines, Runtime Packs, APIs, applications, and AI systems select which artifacts and assertions are visible or usable under a given policy.

Kristal v5 allows material at many epistemic states to coexist:

* hypotheses;
* claims;
* sourced claims;
* disputed assertions;
* rejected assertions;
* fictional corpora;
* mythological corpora;
* symbolic models;
* research bundles;
* publisher declarations;
* institutional references;
* high-confidence factual assertions.

Reader policies make this usable by declaring which statuses, certainty levels, validation decisions, authority channels, scopes, and artifact states are included in a given view.

A reader policy does not determine whether an artifact exists.

A reader policy determines what a reader, runtime, query surface, application, or user chooses to expose or rely on.

---

## Normative keywords

MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as normative requirement keywords.

---

## Core invariant

A Kristal MAY contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.

A reader policy MAY hide or include those assertions.

A reader policy MUST NOT erase their status.

A reader policy MUST NOT present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.

---

## Scope

This document defines:

* standard reader policy modes;
* required and recommended reader policy fields;
* filtering semantics for validation status, certainty level, authority channel, artifact status, and assertion status;
* how Runtime Packs declare supported reader policies;
* how query systems apply reader policy profiles;
* how applications preserve labels when rendering filtered results;
* conformance requirements for strict, research, creative, and custom views.

This document does not define:

* authority-channel governance;
* trust-root distribution;
* signature algorithms;
* validation policy internals;
* user interface layout;
* access-control or authentication rules;
* RDF export behavior.

Access control MAY be layered on top of reader policy, but access control and reader policy MUST remain distinct.

---

## Reader policy definition

A **Reader Policy** is a machine-readable object that specifies which Kristal material is visible, trusted, queryable, or active in a given reader context.

Reader policies may be used by:

* query engines;
* Runtime Pack activators;
* Konnaxion readers;
* Architect renderers;
* Orgo review surfaces;
* AI agents;
* search indexes;
* exports;
* offline clients;
* educational interfaces;
* research tools;
* creative tools.

Reader policy answers:

```text
What should this reader include?
What should this reader hide?
Which authority channels are allowed?
Which validation statuses are allowed?
Which certainty levels are allowed?
Which labels must remain visible?
What happens when required data is unavailable?
```

Reader policy does not answer:

```text
Is this universally true?
Does every authority agree?
Is this assertion maximum-certainty?
Is this artifact signed?
Is this source globally authoritative?
```

---

## Standard reader modes

Kristal v5 defines these standard reader modes:

```text
reader_mode:
  - reference_only
  - validated_only
  - high_certainty_only
  - research
  - creative
  - all_with_labels
  - custom
```

Implementations MAY define additional modes, but custom modes MUST declare explicit filtering rules.

---

## Reader mode semantics

### `reference_only`

The strictest standard mode.

A `reference_only` reader SHOULD include only artifacts or assertions that are recognized as reference material under selected authority channels, scopes, and reader policies.

Typical filters:

```json
{
  "mode": "reference_only",
  "allowed_artifact_statuses": ["reference"],
  "allowed_recognition_statuses": ["recognized", "conditionally_recognized"],
  "allowed_validation_statuses": ["validated", "conditionally_validated"],
  "include_disputed": false,
  "include_rejected": false,
  "include_revoked": false,
  "include_fictional": false,
  "include_mythological": false,
  "show_labels": true
}
```

A `reference_only` view MUST NOT include Working Artifacts unless an explicit policy recognizes them as reference material for that scope.

---

### `validated_only`

A `validated_only` reader includes material that satisfies selected validation policies.

This mode does not necessarily mean maximum certainty.

A validated assertion may be validated as:

* a hypothesis;
* a publisher declaration;
* a sourced claim;
* a reviewed claim;
* a mythological corpus;
* a fictional corpus;
* a legal or policy position;
* a high-confidence fact;
* an institutional reference.

The policy MUST specify which `validated_as` values are allowed.

Typical filters:

```json
{
  "mode": "validated_only",
  "allowed_validation_statuses": ["validated", "conditionally_validated"],
  "allowed_validated_as": [
    "sourced_claim",
    "reviewed_claim",
    "high_confidence_fact",
    "institutional_reference"
  ],
  "include_disputed": false,
  "include_rejected": false,
  "include_revoked": false,
  "show_labels": true
}
```

If `validated_as = "hypothesis"` is allowed, the reader MUST preserve the hypothesis label.

---

### `high_certainty_only`

A `high_certainty_only` reader includes material whose certainty level satisfies a configured threshold.

Typical filters:

```json
{
  "mode": "high_certainty_only",
  "allowed_certainty_levels": ["high", "established"],
  "include_disputed": false,
  "include_rejected": false,
  "include_revoked": false,
  "show_labels": true
}
```

This mode MUST NOT treat certainty as authority recognition.

A high-certainty assertion under one authority channel may still be rejected or ignored by another authority channel.

---

### `research`

A `research` reader includes working, uncertain, disputed, low-certainty, not-yet-validated, or exploratory material with labels preserved.

Typical filters:

```json
{
  "mode": "research",
  "allowed_artifact_statuses": ["draft", "working", "under_review", "recognized", "reference"],
  "allowed_validation_statuses": [
    "not_evaluated",
    "in_review",
    "validated",
    "conditionally_validated",
    "disputed",
    "rejected"
  ],
  "allowed_certainty_levels": ["unknown", "speculative", "low", "medium", "high", "established", "not_applicable"],
  "include_disputed": true,
  "include_rejected": true,
  "include_revoked": false,
  "include_fictional": false,
  "include_mythological": false,
  "show_labels": true
}
```

A research reader MAY include rejected material for audit, refutation, review, or epistemic comparison.

Rejected or disputed material MUST be clearly labeled.

---

### `creative`

A `creative` reader includes fictional, mythological, symbolic, speculative, and imaginative corpora when the user or application intentionally enters that scope.

Typical filters:

```json
{
  "mode": "creative",
  "allowed_validated_as": [
    "fictional_corpus",
    "mythological_corpus",
    "symbolic_model",
    "hypothesis",
    "claim",
    "sourced_claim"
  ],
  "allowed_certainty_levels": ["unknown", "speculative", "low", "medium", "not_applicable"],
  "include_fictional": true,
  "include_mythological": true,
  "include_disputed": true,
  "include_rejected": false,
  "include_revoked": false,
  "show_labels": true
}
```

A creative reader MUST NOT present fictional or mythological material as validated physical-world truth.

---

### `all_with_labels`

An `all_with_labels` reader includes all material allowed by access-control and distribution policy, while preserving all relevant labels.

Typical filters:

```json
{
  "mode": "all_with_labels",
  "allowed_artifact_statuses": ["draft", "working", "under_review", "recognized", "reference", "deprecated", "superseded"],
  "allowed_validation_statuses": [
    "not_evaluated",
    "in_review",
    "validated",
    "conditionally_validated",
    "disputed",
    "rejected",
    "revoked"
  ],
  "allowed_certainty_levels": ["unknown", "speculative", "low", "medium", "high", "established", "not_applicable"],
  "include_disputed": true,
  "include_rejected": true,
  "include_revoked": true,
  "include_fictional": true,
  "include_mythological": true,
  "show_labels": true
}
```

This mode is useful for audit, debugging, governance, provenance review, transparency logs, and expert inspection.

---

### `custom`

A `custom` reader policy MUST explicitly declare its inclusion and exclusion rules.

A custom policy MUST NOT rely only on the label `"custom"`.

It SHOULD declare:

* artifact statuses;
* assertion statuses;
* validation statuses;
* certainty levels;
* validated-as statuses;
* recognition statuses;
* authority channels;
* scopes;
* dispute inclusion;
* rejected inclusion;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=1b8c9e516342:351-700
start=351
end=700
----
* revoked inclusion;
* fictional inclusion;
* mythological inclusion;
* fallback behavior;
* required label visibility.

---

## Reader policy object

A reader policy SHOULD use the following shape:

```json
{
  "schema_version": "5.0",
  "artifact_type": "reader_policy",
  "reader_policy_id": "reader_policy:<slug>",
  "name": "string",
  "mode": "validated_only",

  "scope": {
    "domain": "string",
    "subdomain": "string|null",
    "jurisdiction": "string|null",
    "time_window": "string|null",
    "tenant_id": "string|null",
    "environment": "string|null",
    "language": "string|null"
  },

  "allowed_authority_channels": [],
  "denied_authority_channels": [],

  "allowed_artifact_statuses": [],
  "allowed_assertion_statuses": [],
  "allowed_validation_statuses": [],
  "allowed_recognition_statuses": [],
  "allowed_certainty_levels": [],
  "allowed_validated_as": [],

  "include_disputed": false,
  "include_rejected": false,
  "include_revoked": false,
  "include_deprecated": false,
  "include_superseded": false,
  "include_fictional": false,
  "include_mythological": false,
  "include_symbolic": false,
  "include_not_evaluated": false,

  "require_provenance": false,
  "require_evidence": false,
  "require_signature": false,
  "require_validation_decision": false,
  "require_authority_recognition": false,

  "fallback_behavior": "show_unavailable",
  "show_labels": true,
  "label_requirements": [],

  "ordering_policy": {
    "primary": "authority_precedence",
    "secondary": "certainty_level",
    "tie_breaker": "stable_id"
  },

  "conflict_policy": {
    "strategy": "preserve_disagreement",
    "require_user_choice": false
  },

  "created_at": "RFC3339",
  "created_by": {},
  "policy_refs": [],
  "signatures": [],
  "extensions": {}
}
```

---

## Field semantics

### `reader_policy_id`

The stable identifier for the reader policy.

Recommended format:

```text
reader_policy:<slug>
```

A content-addressed identifier MAY be used when policies are immutable or signed as artifacts.

---

### `mode`

The standard reader mode.

Allowed values:

```text
reference_only
validated_only
high_certainty_only
research
creative
all_with_labels
custom
```

---

### `scope`

Defines where the reader policy applies.

A reader policy MAY be global, domain-scoped, tenant-scoped, environment-scoped, jurisdiction-scoped, or language-scoped.

If a policy declares a scope, implementations MUST NOT silently apply it outside that scope.

---

### `allowed_authority_channels`

List of authority channels whose validation or recognition may be included.

An empty list means policy-defined default behavior.

A strict implementation SHOULD treat an empty list as “no authority channels allowed” unless the policy profile defines a default registry.

Recommended values:

```text
authority:<slug>
```

---

### `denied_authority_channels`

List of authority channels explicitly excluded.

If an authority channel appears in both allowed and denied lists, denial SHOULD win unless the policy explicitly declares another precedence rule.

---

### `allowed_artifact_statuses`

Allowed artifact lifecycle states.

Standard values:

```text
draft
working
under_review
recognized
reference
deprecated
superseded
revoked
```

---

### `allowed_assertion_statuses`

Allowed assertion states.

Standard values:

```text
hypothesis
claimed
sourced
disputed
reviewed
validated
rejected
retracted
superseded
```

---

### `allowed_validation_statuses`

Allowed validation states.

Standard values:

```text
not_evaluated
in_review
validated
conditionally_validated
disputed
rejected
revoked
```

---

### `allowed_recognition_statuses`

Allowed authority recognition states.

Standard values:

```text
recognized
conditionally_recognized
under_review
disputed
rejected
deprecated
revoked
```

---

### `allowed_certainty_levels`

Allowed certainty levels.

Standard values:

```text
unknown
speculative
low
medium
high
established
not_applicable
```

---

### `allowed_validated_as`

Allowed validated-as statuses.

Standard values:

```text
hypothesis
claim
sourced_claim
reviewed_claim
high_confidence_fact
institutional_reference
publisher_declaration
technical_specification
legal_or_policy_position
mythological_corpus
fictional_corpus
symbolic_model
disputed_position
rejected_claim
```

---

### Inclusion flags

The following flags provide readable shortcuts for common policy decisions:

```text
include_disputed
include_rejected
include_revoked
include_deprecated
include_superseded
include_fictional
include_mythological
include_symbolic
include_not_evaluated
```

If an inclusion flag conflicts with an explicit allowed list, the explicit allowed list SHOULD take precedence.

---

### Requirement flags

The following flags declare minimum requirements for inclusion:

```text
require_provenance
require_evidence
require_signature
require_validation_decision
require_authority_recognition
```

For example, if `require_evidence = true`, assertions without evidence MUST NOT be included unless an explicit exception rule applies.

---

### `fallback_behavior`

Defines what happens when required policy information is unavailable.

Allowed values:

```text
show_unavailable
hide_unavailable
show_with_warning
hold
error
```

#### `show_unavailable`

Show that relevant data exists but cannot be displayed under the active policy.

#### `hide_unavailable`

Silently hide material that cannot be evaluated.

This SHOULD be avoided for audit, research, and governance contexts.

#### `show_with_warning`

Show material with a clear warning that policy evaluation was incomplete.

#### `hold`

Do not activate or publish the view until required policy data becomes available.

#### `error`

Treat policy evaluation failure as an error for this operation.

---

### `show_labels`

If `show_labels` is true, readers MUST preserve relevant validation, certainty, authority, dispute, and scope labels.

If `show_labels` is false, the policy MUST explain why labels may be hidden.

A strict or public-facing reader SHOULD keep `show_labels = true`.

---
--- CHUNK END ---

--- CHUNK BEGIN ---
id=1b8c9e516342:701-1050
start=701
end=1050
----

### `label_requirements`

A reader policy MAY require specific labels to be displayed.

Recommended values:

```text
artifact_status
assertion_status
validation_status
validated_as
certainty_level
authority_channel
recognition_status
scope
source
provenance
evidence
dispute_status
reader_policy
```

---

## Policy evaluation model

A reader evaluates a candidate artifact or assertion by applying the active reader policy.

Recommended evaluation order:

1. Check access-control and distribution permissions.
2. Check artifact status.
3. Check assertion status.
4. Check validation status.
5. Check validated-as status.
6. Check certainty level.
7. Check authority channel.
8. Check authority recognition.
9. Check scope compatibility.
10. Check provenance and evidence requirements.
11. Check signature or identity requirements.
12. Check dispute, rejection, revocation, deprecated, and superseded flags.
13. Check reader-mode-specific rules.
14. Apply conflict policy.
15. Return included, excluded, held, or included-with-warning.

Evaluation MUST be deterministic given the same inputs and policy.

---

## Policy evaluation result

Implementations SHOULD expose policy evaluation results.

Recommended shape:

```json
{
  "reader_policy_id": "reader_policy:<slug>",
  "target_ref": {},
  "target_level": "assertion",
  "decision": "included",
  "reason_codes": [],
  "labels_required": [],
  "warnings": [],
  "evaluated_at": "RFC3339"
}
```

Allowed decisions:

```text
included
included_with_warning
excluded
held
error
not_evaluated
```

---

## Reason codes

Implementations SHOULD use stable reason codes.

Recommended reason codes:

```text
artifact_status_allowed
artifact_status_not_allowed
assertion_status_allowed
assertion_status_not_allowed
validation_status_allowed
validation_status_not_allowed
validated_as_allowed
validated_as_not_allowed
certainty_allowed
certainty_too_low_for_policy
authority_channel_allowed
authority_channel_denied
authority_channel_missing
recognition_status_allowed
recognition_status_not_allowed
scope_match
scope_mismatch
provenance_present
provenance_missing
evidence_present
evidence_missing
signature_required
signature_present
signature_missing
signature_failed
validation_decision_required
validation_decision_missing
authority_recognition_required
authority_recognition_missing
disputed_included
disputed_excluded
rejected_included
rejected_excluded
revoked_included
revoked_excluded
fictional_included
fictional_excluded
mythological_included
mythological_excluded
not_evaluated_included
not_evaluated_excluded
conflict_preserved
conflict_requires_user_choice
fallback_show_unavailable
fallback_hide_unavailable
fallback_show_with_warning
fallback_hold
fallback_error
```

---

## Conflict policy

Reader policies MUST specify or inherit a conflict policy.

Recommended shape:

```json
{
  "strategy": "preserve_disagreement",
  "require_user_choice": false,
  "preferred_authority_order": [],
  "show_conflict_labels": true
}
```

Standard conflict strategies:

```text
preserve_disagreement
authority_precedence
mark_disputed
exclude_conflict
require_reader_choice
```

Default:

```text
preserve_disagreement
```

A reader policy MUST NOT silently merge conflicting claims unless a declared composition policy explicitly permits that behavior.

---

## Ordering policy

Reader policies MAY specify result ordering.

Recommended shape:

```json
{
  "primary": "authority_precedence",
  "secondary": "certainty_level",
  "tie_breaker": "stable_id"
}
```

Allowed ordering terms:

```text
authority_precedence
certainty_level
validation_status
recognition_status
artifact_status
created_at
updated_at
source_order
stable_id
```

Ordering MUST be deterministic.

If `authority_precedence` is used, the policy MUST define or reference an authority order.

---

## Runtime Pack relationship

A Runtime Pack MAY declare the reader policies it supports.

Recommended field:

```json
{
  "reader_policy_refs": [
    {
      "reader_policy_id": "reader_policy:validated-only-global-reference",
      "policy_hash": {
        "alg": "sha256",
        "value": "<hex>"
      }
    }
  ]
}
```

A Runtime Pack built for a permissive research or creative view MUST NOT be activated as a strict `reference_only` or `validated_only` Runtime Pack unless it also satisfies that stricter policy.

A Runtime Pack SHOULD declare:

* source artifact status;
* included authority channels;
* included validation statuses;
* included certainty levels;
* included validated-as statuses;
* whether disputed material is included;
* whether rejected material is included;
* whether fictional material is included;
* whether mythological material is included;
* supported reader policies.

---

## Query contract relationship

Query systems SHOULD accept a reader policy parameter.

Example:

```json
{
  "query": {
    "type": "entity_lookup",
    "entity_id": "Q42"
  },
  "reader_policy_id": "reader_policy:validated-only-global-reference"
}
```

Query results SHOULD include policy explanation metadata.

Example:

```json
{
  "result_id": "sha256:<hex>",
  "included": true,
  "reader_policy_id": "reader_policy:validated-only-global-reference",
  "policy_decision": "included",
  "reason_codes": [
    "validation_status_allowed",
    "authority_channel_allowed",
    "certainty_allowed"
  ],
  "visible_labels": {
    "validation_status": "validated",
    "validated_as": "institutional_reference",
    "certainty_level": "high",
    "authority_channel": "authority:global-reference"
  }
}
```

A query result MUST NOT hide that a visible assertion is disputed, rejected, fictional, mythological, low-certainty, not evaluated, or recognized only by a specific authority channel when that status is known.

---

## Federation relationship

Federations may contain shards or Exchanges with different authority channels, validation statuses, certainty levels, scopes, and conflict statuses.

A reader policy applied to a federation MUST evaluate each included target according to policy.

Federation MUST preserve source identity.

Reader policy MUST NOT silently erase:

* shard identity;
* source artifact identity;
* publisher identity;
* authority channel;
* validation status;
* recognition status;
* certainty level;
* scope;
* lineage;
* conflict status.

---

## Authority-channel relationship

A reader policy MAY select authority channels.

Examples:

```json
{
  "allowed_authority_channels": [
    "authority:unesco-global-reference",
    "authority:who-health",
    "authority:wikidata-community"
  ]
}
```

Authority selection is scoped.

Recognition by one authority channel MUST NOT be treated as recognition by another unless an explicit authority-recognition relationship supports that interpretation.

If delegated authority is allowed, the reader policy SHOULD declare whether delegated channels are included.

Recommended field:

```json
{
  "include_delegated_authorities": true,
  "delegation_depth": 1
}
```

---

## Strict validated-only profile

--- CHUNK END ---

--- CHUNK BEGIN ---
id=1b8c9e516342:1051-1400
start=1051
end=1400
----
Recommended profile:

```json
{
  "schema_version": "5.0",
  "artifact_type": "reader_policy",
  "reader_policy_id": "reader_policy:strict-validated-only",
  "name": "Strict validated-only",
  "mode": "validated_only",

  "allowed_artifact_statuses": ["recognized", "reference"],
  "allowed_assertion_statuses": ["validated"],
  "allowed_validation_statuses": ["validated"],
  "allowed_recognition_statuses": ["recognized"],
  "allowed_certainty_levels": ["medium", "high", "established"],
  "allowed_validated_as": [
    "reviewed_claim",
    "high_confidence_fact",
    "institutional_reference",
    "technical_specification"
  ],

  "include_disputed": false,
  "include_rejected": false,
  "include_revoked": false,
  "include_deprecated": false,
  "include_superseded": false,
  "include_fictional": false,
  "include_mythological": false,
  "include_symbolic": false,
  "include_not_evaluated": false,

  "require_provenance": true,
  "require_evidence": true,
  "require_signature": true,
  "require_validation_decision": true,
  "require_authority_recognition": true,

  "fallback_behavior": "show_unavailable",
  "show_labels": true,
  "label_requirements": [
    "validation_status",
    "validated_as",
    "certainty_level",
    "authority_channel",
    "recognition_status",
    "scope"
  ],

  "conflict_policy": {
    "strategy": "preserve_disagreement",
    "require_user_choice": false,
    "show_conflict_labels": true
  }
}
```

---

## Research profile

Recommended profile:

```json
{
  "schema_version": "5.0",
  "artifact_type": "reader_policy",
  "reader_policy_id": "reader_policy:research",
  "name": "Research",
  "mode": "research",

  "allowed_artifact_statuses": ["draft", "working", "under_review", "recognized", "reference", "deprecated", "superseded"],
  "allowed_assertion_statuses": ["hypothesis", "claimed", "sourced", "disputed", "reviewed", "validated", "rejected", "superseded"],
  "allowed_validation_statuses": ["not_evaluated", "in_review", "validated", "conditionally_validated", "disputed", "rejected"],
  "allowed_recognition_statuses": ["recognized", "conditionally_recognized", "under_review", "disputed", "rejected", "deprecated"],
  "allowed_certainty_levels": ["unknown", "speculative", "low", "medium", "high", "established", "not_applicable"],
  "allowed_validated_as": [
    "hypothesis",
    "claim",
    "sourced_claim",
    "reviewed_claim",
    "high_confidence_fact",
    "institutional_reference",
    "publisher_declaration",
    "technical_specification",
    "legal_or_policy_position",
    "disputed_position",
    "rejected_claim"
  ],

  "include_disputed": true,
  "include_rejected": true,
  "include_revoked": false,
  "include_deprecated": true,
  "include_superseded": true,
  "include_fictional": false,
  "include_mythological": false,
  "include_symbolic": true,
  "include_not_evaluated": true,

  "require_provenance": false,
  "require_evidence": false,
  "require_signature": false,
  "require_validation_decision": false,
  "require_authority_recognition": false,

  "fallback_behavior": "show_with_warning",
  "show_labels": true
}
```

---

## Creative profile

Recommended profile:

```json
{
  "schema_version": "5.0",
  "artifact_type": "reader_policy",
  "reader_policy_id": "reader_policy:creative",
  "name": "Creative",
  "mode": "creative",

  "allowed_artifact_statuses": ["draft", "working", "under_review", "recognized", "reference"],
  "allowed_assertion_statuses": ["hypothesis", "claimed", "sourced", "disputed", "reviewed", "validated"],
  "allowed_validation_statuses": ["not_evaluated", "in_review", "validated", "conditionally_validated", "disputed"],
  "allowed_recognition_statuses": ["recognized", "conditionally_recognized", "under_review", "disputed"],
  "allowed_certainty_levels": ["unknown", "speculative", "low", "medium", "not_applicable"],
  "allowed_validated_as": [
    "hypothesis",
    "claim",
    "sourced_claim",
    "mythological_corpus",
    "fictional_corpus",
    "symbolic_model",
    "disputed_position"
  ],

  "include_disputed": true,
  "include_rejected": false,
  "include_revoked": false,
  "include_deprecated": false,
  "include_superseded": false,
  "include_fictional": true,
  "include_mythological": true,
  "include_symbolic": true,
  "include_not_evaluated": true,

  "require_provenance": false,
  "require_evidence": false,
  "require_signature": false,
  "require_validation_decision": false,
  "require_authority_recognition": false,

  "fallback_behavior": "show_with_warning",
  "show_labels": true
}
```

---

## All-with-labels profile

Recommended profile:

```json
{
  "schema_version": "5.0",
  "artifact_type": "reader_policy",
  "reader_policy_id": "reader_policy:all-with-labels",
  "name": "All with labels",
  "mode": "all_with_labels",

  "allowed_artifact_statuses": ["draft", "working", "under_review", "recognized", "reference", "deprecated", "superseded", "revoked"],
  "allowed_assertion_statuses": ["hypothesis", "claimed", "sourced", "disputed", "reviewed", "validated", "rejected", "retracted", "superseded"],
  "allowed_validation_statuses": ["not_evaluated", "in_review", "validated", "conditionally_validated", "disputed", "rejected", "revoked"],
  "allowed_recognition_statuses": ["recognized", "conditionally_recognized", "under_review", "disputed", "rejected", "deprecated", "revoked"],
  "allowed_certainty_levels": ["unknown", "speculative", "low", "medium", "high", "established", "not_applicable"],
  "allowed_validated_as": [
    "hypothesis",
    "claim",
    "sourced_claim",
    "reviewed_claim",
    "high_confidence_fact",
    "institutional_reference",
    "publisher_declaration",
    "technical_specification",
    "legal_or_policy_position",
    "mythological_corpus",
    "fictional_corpus",
    "symbolic_model",
    "disputed_position",
    "rejected_claim"
  ],

  "include_disputed": true,
  "include_rejected": true,
  "include_revoked": true,
  "include_deprecated": true,
  "include_superseded": true,
  "include_fictional": true,
  "include_mythological": true,
  "include_symbolic": true,
  "include_not_evaluated": true,

  "require_provenance": false,
  "require_evidence": false,
  "require_signature": false,
  "require_validation_decision": false,
  "require_authority_recognition": false,

  "fallback_behavior": "show_with_warning",
  "show_labels": true
}
```

---

## “100% validated” interpretation

In Kristal v5, a reader may choose a “100% validated” view.

This means:

```text
All visible assertions satisfy the active reader policy.
```

It does not mean:

```text
All assertions have maximum certainty.
All assertions are universally true.
All authorities agree.
All hidden assertions do not exist.
All material outside the policy is invalid.
```

For example, a strict validated-only reader may include a validated hypothesis if the policy allows:

```json
{
  "validation_status": "validated",
  "validated_as": "hypothesis",
  "certainty_level": "speculative"
}
```

The assertion is valid as a hypothesis, not as established fact.

---

## Missing information

Reader policies MUST define what happens when information required for policy evaluation is missing.

Examples:

* validation status missing;
* certainty level missing;
* authority channel missing;
* provenance missing;
* evidence missing;
* signature status unavailable;
* revocation status unavailable offline;
* authority registry unavailable;
* reader policy hash mismatch.

The result MUST be one of:

```text
included
included_with_warning
excluded
held
error
not_evaluated
```

A strict policy SHOULD exclude or hold when required information is unavailable.

A research policy MAY include with warning.

---

## Label preservation

Readers MUST preserve labels needed to understand why material is visible.

At minimum, when available, a reader SHOULD expose:

* artifact status;
* assertion status;
* validation status;
* validated-as status;
* certainty level;
* authority channel;
* recognition status;
* scope;
* provenance or source link;
* dispute status;
* reader policy ID.

A reader MUST NOT flatten scoped validation into universal truth.

A reader MUST NOT hide that a claim is fictional, mythological, disputed, rejected, revoked, or validated only by a specific authority channel when that status is known.

---

## Caching and offline behavior

Offline readers MAY use cached reader policies.

A cached reader policy SHOULD include:

* `reader_policy_id`;
* policy hash;
* created time;
* issuer;
* scope;
* signatures, if required;
* expiry, if required;
* source authority registry reference.

If a reader policy is expired or cannot be verified, the client MUST follow fallback behavior.

A Runtime Pack MUST NOT be activated under an unverifiable reader policy when the distribution or activation policy requires reader policy verification.

---

## Security and correctness considerations

Implementations SHOULD defend against:

* authority laundering;
* validation laundering;
* certainty laundering;
* hiding low-certainty labels;
* hiding dispute labels;
* hiding rejected or revoked status;
* presenting filtered views as complete corpora;
* applying a permissive Runtime Pack under a strict reader policy;
* applying a reader policy outside its declared scope;
* silently changing authority-channel lists;
* silently changing policy hashes;
* treating signatures as validation;
* treating authority recognition as universal authority;
* treating “validated-only” as “maximum-certainty-only”;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=1b8c9e516342:1401-1473
start=1401
end=1473
----
* treating missing evidence as equivalent to validated evidence;
* treating fictional or mythological material as physical-world truth.

---

## Conformance requirements

A Kristal v5 reader-policy implementation MUST:

1. support the standard reader modes;
2. expose or apply explicit filtering rules for each mode;
3. distinguish validation status from certainty level;
4. distinguish authority recognition from validation;
5. distinguish artifact status from assertion status;
6. preserve labels required by active policy;
7. apply policy deterministically;
8. preserve disagreement unless the policy declares another conflict strategy;
9. prevent Working Artifacts from being shown as Reference Artifacts unless recognition supports that status;
10. prevent fictional or mythological material from being shown as physical-world truth unless explicitly validated under that epistemic mode.

A conformant implementation SHOULD:

1. support signed reader policies;
2. expose policy evaluation decisions;
3. expose reason codes;
4. support offline reader policy evaluation;
5. allow runtime activation to check reader policy compatibility;
6. support delegated authority-channel selection;
7. support research and creative modes without losing labels;
8. support strict public modes for validated or reference-only views.

---

## Conformance tests

A conforming implementation MUST provide fixtures demonstrating:

* `reference_only` includes recognized reference material;
* `reference_only` excludes Working Artifacts without recognition;
* `validated_only` includes allowed validated-as statuses;
* `validated_only` preserves validated hypothesis labels when allowed;
* `high_certainty_only` excludes low-certainty material;
* `research` includes low-certainty material with labels;
* `research` includes disputed material with labels;
* `creative` includes fictional material with labels;
* `creative` includes mythological material with labels;
* `creative` does not present fiction as physical-world truth;
* `all_with_labels` preserves rejected and revoked status;
* custom mode fails if no explicit rules are declared;
* missing evidence is handled according to fallback behavior;
* missing authority channel is handled according to fallback behavior;
* reader-policy mismatch blocks Runtime Pack activation when required;
* permissive Runtime Pack is not activated as strict reference-only pack;
* conflict policy preserves disagreement by default;
* authority-channel denial overrides allowance when both are present;
* policy evaluation is deterministic for the same inputs.

---

## Open questions

The following decisions remain open:

* Should `show_labels` be required to be `true` for all public reader policies?
* Should `validated_only` include validated hypotheses by default, or require explicit inclusion?
* Should `reference_only` require authority recognition in addition to validation?
* Should reader policies be signed artifacts in all Runtime Packs?
* Should delegated authority inclusion default to false?
* Should `all_with_labels` include revoked material by default, or only under audit mode?
* Should strict public readers hide unavailable material or show unavailable placeholders?
* Should reader policy hashes be mandatory in Runtime Pack manifests?
* Should conflict strategy be part of reader policy, federation policy, or both?
* Should access control and reader policy share a profile, or remain completely separate?
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-jsonld-export.md"
id=cd00e0008279
kind=markdown
size=22603
lines=866
line_ref=1-866
chunks=3
chunk_refs=1-350,351-700,701-866
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=cd00e0008279:1-350
start=1
end=350
----
# 05-profiles/profile-jsonld-export.md

# JSON-LD export profile

## Status

Draft (v5 profile)

## Purpose

This document defines the **JSON-LD 1.1 export profile** for Kristal v5.

Goals:

* Provide a **deterministic**, **portable**, and **Wikibase-aligned** JSON-LD representation of Kristal Exchange content.
* Ensure exporters across languages and toolchains produce **byte-stable output** given the same source artifact and export policy.
* Define clear boundaries between:

  * Kristal Exchange payloads as structured reference artifacts; and
  * JSON-LD export artifacts as derived interoperability projections.

This profile is optional, but if enabled, it is conformance-testable.

JSON-LD export does not decide validation, certainty, authority recognition, or reader visibility. It serializes selected Kristal content into an interoperable JSON-LD representation while preserving the relevant identifiers, provenance, status, and scope metadata.

---

## 1. Scope and non-goals

### 1.1 In scope

This profile defines:

* Deterministic JSON-LD 1.1 structure for exporting claims, assertions, statements, and related metadata from a Kristal Exchange.
* Stable `@context` and `@type` usage to enable consistent RDF interpretation.
* Deterministic ordering rules so the export is byte-stable.
* Rules for encoding:

  * entities;
  * properties;
  * literals;
  * datatypes;
  * language tags;
  * qualifiers;
  * references;
  * evidence pointers;
  * ranks, where present;
  * assertion status;
  * certainty level;
  * validation references;
  * authority recognition references;
  * scope metadata;
  * full or best-rank projections.

### 1.2 Out of scope

This profile does not define:

* the Kristal Exchange schema itself;
* Structured Epistemic State schema;
* validation policy semantics;
* authority recognition semantics;
* reader policy selection;
* Runtime Pack query behavior;
* RDF Dataset Canonicalization;
* RDF-level hashing;
* which claims should be accepted as true.

RDF dataset canonicalization and RDF hashing are handled by:

```text
05-profiles/profile-rdf-integrity-rdfc.md
```

---

## 2. Profile identification

If JSON-LD export is produced, the exporter MUST declare:

```text
export_profile_id = "kristal.v5:jsonld-1.1"
export_profile_version = "1"
```

The export metadata MUST also record:

* `schema_version = "5.0"`;
* the source artifact reference;
* the source artifact type;
* the `kristal_id` of the source Exchange, when exporting from an Exchange;
* the `state_id`, when exporting from a Structured Epistemic State profile that explicitly permits export;
* the `canonicalization_profile` used by the source artifact;
* the `canonicalization_version` used by the source artifact;
* the export projection;
* the statement model;
* the export policy or reader policy used, if any filtering was applied.

Recommended metadata shape:

```json
{
  "schema_version": "5.0",
  "artifact_type": "jsonld_export",
  "export_profile_id": "kristal.v5:jsonld-1.1",
  "export_profile_version": "1",
  "source_artifact": {
    "artifact_type": "reference_exchange",
    "kristal_id": "sha256:<hex>",
    "uri": "https://example.org/kristals/<id>"
  },
  "source_canonicalization": {
    "canonicalization_profile": "kristal.v5:jcs-rfc8785",
    "canonicalization_version": "1"
  },
  "statement_model": "wikibase-aligned",
  "projection": "full"
}
```

---

## 3. Export source

### 3.1 Supported source artifacts

A JSON-LD export MAY be produced from:

* `working_exchange`;
* `reference_exchange`;
* another Exchange-compatible artifact explicitly allowed by profile.

A JSON-LD export SHOULD NOT be produced directly from an arbitrary raw source, draft, scraper output, or unstructured dataset unless that source has first been represented as a Kristal v5 artifact.

### 3.2 Source status preservation

Exporters MUST preserve source status metadata when present and selected by export policy.

Relevant metadata includes:

* `artifact_status`;
* `assertion_status`;
* `certainty_level`;
* `validated_as`;
* `validation_refs`;
* `authority_recognition_refs`;
* `scope`;
* `provenance_refs`;
* `evidence_refs`;
* `lineage`.

Exporting to JSON-LD MUST NOT flatten scoped validation into universal truth.

### 3.3 Derived artifact boundary

A JSON-LD export is a derived artifact.

It MAY have its own export ID, content hash, signature, or publication record.

Those fields identify the export artifact itself. They do not replace the identity of the source Exchange.

---

## 4. Determinism requirements

### 4.1 Byte-stable export

Given identical source artifact content, export policy, reader policy, profile version, context version, and projection settings, two implementations MUST output identical JSON bytes after applying:

* the serialization rules declared for export artifacts;
* the deterministic ordering rules in this profile.

The recommended serialization method for byte-stable JSON-LD export artifacts is RFC 8785 JCS.

### 4.2 Export canonicalization metadata

If the JSON-LD export artifact itself is content-addressed, signed, or tested for byte stability, it MUST record:

```json
{
  "canonicalization_profile": "kristal.v5:jcs-rfc8785",
  "canonicalization_version": "1"
}
```

This describes the export artifact’s serialization profile, not necessarily the source Exchange’s own content hash target.

### 4.3 Ordering rules

Where arrays represent conceptually unordered sets, they MUST be sorted deterministically.

Minimum required ordering:

* entities: by entity ID or `@id`, lexicographically;
* assertions/statements: by `assertion_id` if present;
* source-system statements: by `statement_id` if present and `assertion_id` is absent;
* fallback statement ordering: by `(subject, property, value, qualifiers_hash, references_hash)`;
* qualifiers: by `(property, value)` lexicographically;
* references and evidence pointers: by stable `evidence_id`, `reference_id`, or equivalent;
* validation references: by referenced ID lexicographically;
* authority recognition references: by referenced ID lexicographically;
* language maps: by language code lexicographically;
* graph nodes: by `@id` lexicographically when `@id` exists.

No field MAY be emitted in an implementation-dependent order.

### 4.4 Normalization rules

Exporters MUST preserve normalized values present in the source artifact.

Exporters MUST NOT:

* re-normalize numbers or dates during export;
* coerce datatypes beyond what is declared in the source artifact;
* resolve unresolved ambiguity by guessing;
* hide assertion status, certainty level, or authority scope when those fields are selected for export;
* silently discard references or evidence pointers needed to preserve meaning.

If an export policy intentionally excludes metadata, the policy MUST be declared.

---

## 5. JSON-LD document structure

### 5.1 Top-level document shape

The export MUST be a JSON-LD document with:

* `@context`; and
* one of:

  * `@graph`; or
  * a top-level node array, if explicitly declared by profile extension.

The recommended v5 shape is:

```json
{
  "@context": { },
  "@graph": [ ]
}
```

The exporter MUST choose one shape and keep it stable within `export_profile_version`.

### 5.2 Metadata node

The export SHOULD include a metadata node describing the export artifact.

Recommended shape:

```json
{
  "@id": "kristal-export:sha256:<hex>",
  "@type": "kristal:JsonLdExport",
  "kristal:schemaVersion": "5.0",
  "kristal:exportProfileId": "kristal.v5:jsonld-1.1",
  "kristal:exportProfileVersion": "1",
  "kristal:sourceArtifact": {
    "@id": "kristal:sha256:<hex>"
  },
  "kristal:projection": "full",
  "kristal:statementModel": "wikibase-aligned"
}
```

The metadata node MUST NOT be used to overwrite or reinterpret the source artifact’s validation status.

### 5.3 Context requirements

The `@context` MUST:

* be stable;
* be versioned;
* define compact terms for:

  * entity identifiers;
  * property identifiers;
  * assertion or statement model fields;
  * qualifiers;
  * references;
  * evidence pointers;
  * ranks;
  * provenance pointers;
  * assertion status;
  * certainty level;
  * validation references;
  * authority recognition references;
  * scope fields.

Recommended context strategy:

* Use a stable context URI per profile version, for example:

```text
https://kristal.org/contexts/v5/jsonld/v1
```

* Include explicit prefix mappings when using Wikidata-style IRIs, such as:

```text
wd:
wdt:
p:
ps:
pq:
pr:
prov:
xsd:
kristal:
```

A profile MAY use an embedded context, but the embedded context MUST be byte-stable under the export profile.

---

## 6. Node identity

### 6.1 Entity nodes

Entity nodes MUST have stable `@id` values derived from the entity identifier.

Recommended Wikidata-compatible mapping:

```text
Q123 -> wd:Q123
P456 -> wd:P456
```

A Kristal-native profile MAY use Kristal IRIs instead, such as:

```text
kristal-entity:Q123
kristal-property:P456
```

The chosen mapping MUST be declared in export metadata.

### 6.2 Assertion or statement nodes

Assertion or statement nodes SHOULD have stable `@id` values.

Recommended:

```text
assertion_id -> kristal-assertion:sha256:<hex>
statement_id -> wikibase statement IRI or kristal-statement:<id>
```

If both `assertion_id` and source-system `statement_id` are present:
--- CHUNK END ---

--- CHUNK BEGIN ---
id=cd00e0008279:351-700
start=351
end=700
----

* `assertion_id` SHOULD be the Kristal identity;
* `statement_id` SHOULD be preserved as a source-system identifier.

### 6.3 Evidence and reference nodes

Evidence and reference nodes SHOULD have stable `@id` values derived from:

* `evidence_id`;
* `reference_id`;
* content hash;
* source URI, if no stronger identifier exists.

Large raw evidence blobs MUST NOT be embedded unless enabled by an explicit profile extension.

---

## 7. Statement model

### 7.1 Supported models

The export MUST represent assertions/statements using one declared statement model:

```text
statement_model = "wikibase-aligned"
```

or:

```text
statement_model = "kristal-native"
```

An implementation MAY support both, but each export artifact MUST declare exactly one primary statement model.

### 7.2 Wikibase-aligned model

In the Wikibase-aligned model, statements SHOULD be represented in a way that preserves:

* subject entity;
* property;
* main value;
* qualifiers;
* references;
* rank, when present;
* assertion identity;
* source statement identity, when present;
* evidence and provenance pointers.

The export MAY use Wikidata-style IRIs and statement reification patterns.

### 7.3 Kristal-native model

In the Kristal-native model, statements SHOULD be represented using Kristal terms while preserving explicit mappings to Wikibase concepts when available.

A Kristal-native statement SHOULD include:

* `kristal:assertionId`;
* `kristal:subject`;
* `kristal:property`;
* `kristal:value`;
* `kristal:qualifier`;
* `kristal:reference`;
* `kristal:evidence`;
* `kristal:assertionStatus`;
* `kristal:certaintyLevel`;
* `kristal:validatedAs`;
* `kristal:scope`;
* `kristal:validationRef`;
* `kristal:authorityRecognitionRef`.

### 7.4 Assertion identity inclusion

If `assertion_id` exists in the source artifact, it MUST be included in the export.

If `statement_id` exists in the source artifact, it SHOULD be included as a source-system identifier.

If neither exists, exporters MUST compute a deterministic surrogate key for ordering. The surrogate key MUST NOT be presented as a Kristal content-addressed ID unless explicitly defined by a profile.

---

## 8. Literals and datatypes

### 8.1 Typed literals

Typed values MUST be expressed using JSON-LD value objects:

```json
{
  "@value": "2020-01-01",
  "@type": "xsd:date"
}
```

### 8.2 Language-tagged strings

Language values MUST be expressed using:

```json
{
  "@value": "Bonjour",
  "@language": "fr"
}
```

Language tags SHOULD be lowercase unless the source artifact intentionally preserves a specific normalized form.

### 8.3 Entity references

Values that are entities MUST be represented as `@id` references, not as plain strings.

Example:

```json
{
  "@id": "wd:Q123"
}
```

### 8.4 Numeric and temporal values

Exporters MUST preserve the normalized lexical form from the source artifact.

Exporters MUST NOT reinterpret precision, timezone, calendar model, unit, or datatype unless the source artifact explicitly contains a mapping that allows it.

---

## 9. Qualifiers and references

### 9.1 Qualifiers

Qualifiers MUST be represented as arrays or objects that remain deterministic under the export profile.

If arrays are used, they MUST be sorted according to Section 4.3.

A qualifier SHOULD preserve:

* property;
* value;
* datatype;
* source pointer, if available;
* certainty or validation metadata, if the qualifier itself is status-bearing.

### 9.2 References and evidence pointers

References MUST include stable pointers back to source evidence or reference objects.

Minimum requirement:

* `evidence_id`, `reference_id`, or equivalent stable identifier;
* source URI, when available;
* content hash, when available;
* provenance pointer, when available.

Export MUST NOT embed large raw evidence blobs unless explicitly enabled by an additional profile.

### 9.3 Provenance

When provenance metadata is selected for export, it SHOULD preserve:

* source artifact references;
* source URI;
* publisher or contributor identity;
* derivation references;
* merge references;
* transformation references;
* validation or review references.

Provenance export MUST preserve attribution and MUST NOT silently merge different authority channels.

---

## 10. Assertion status, certainty, and authority metadata

### 10.1 Assertion status

If present in the source artifact and selected by export policy, `assertion_status` MUST be exported.

Recommended values are:

```text
hypothesis
claimed
sourced
disputed
reviewed
validated
rejected
retracted
superseded
```

### 10.2 Certainty level

If present in the source artifact and selected by export policy, `certainty_level` MUST be exported.

Recommended values are:

```text
unknown
speculative
low
medium
high
established
not_applicable
mixed
```

### 10.3 Validated as

If present in the source artifact and selected by export policy, `validated_as` MUST be exported.

Recommended values include:

```text
hypothesis
claim
sourced_claim
reviewed_claim
high_confidence_fact
institutional_reference
publisher_declaration
technical_specification
legal_or_policy_position
mythological_corpus
fictional_corpus
symbolic_model
disputed_position
rejected_claim
```

### 10.4 Authority recognition references

Authority recognition references SHOULD be exported when they are present and selected by policy.

The export MUST preserve the distinction between:

* who published a claim;
* who validated a claim;
* who recognized a claim;
* which scope the recognition applies to;
* which policy was used.

A claim validated or recognized under one authority channel MUST NOT be represented as validated or recognized under another authority channel unless the source artifact explicitly records that recognition.

### 10.5 Scope metadata

Scope metadata SHOULD be exported when present and selected by policy.

Recommended scope fields:

* `domain`;
* `subdomain`;
* `jurisdiction`;
* `time_window`;
* `tenant_id`;
* `environment`;
* `language`.

---

## 11. Full and best-rank projections

### 11.1 Supported projections

This profile supports two projections:

```text
projection = "full"
```

and:

```text
projection = "best_rank"
```

The `full` projection exports all selected statements and preserves rank metadata when present.

The `best_rank` projection exports selected statements according to a deterministic rank policy.

### 11.2 Default projection

The default projection is:

```text
projection = "full"
```

If best-rank rules are not implemented, exporters MUST emit only `projection = "full"`.

### 11.3 Best-rank projection rules

If `best_rank` is supported, the exporter MUST:

* define the rule;
* keep it deterministic;
* declare the rule in export metadata;
* preserve enough metadata for consumers to understand that the export is a projection;
* avoid presenting omitted statements as nonexistent.

Recommended metadata:

```json
{
  "projection": "best_rank",
  "projection_policy": {
    "policy_id": "kristal.v5:projection-policy:wikibase-best-rank",
    "policy_version": "1"
  }
}
```

### 11.4 Compatibility alias

For Wikibase compatibility, a profile MAY expose `best_rank` as equivalent to a “truthy” projection.

When this term is used, it MUST be treated as a technical projection label, not as a universal truth claim.

---

## 12. Export policies and reader policies

### 12.1 Export policy

An export policy defines what content is included in the JSON-LD artifact.

It MAY filter by:

* artifact status;
* assertion status;
* validation status;
* certainty level;
* validated-as mode;
* authority channel;
* recognition status;
* domain;
* jurisdiction;
* language;
* projection;
* reader policy.

### 12.2 Reader policy linkage

If a JSON-LD export is produced from a reader policy, the export metadata MUST record the reader policy reference.

Example:

```json
--- CHUNK END ---

--- CHUNK BEGIN ---
id=cd00e0008279:701-866
start=701
end=866
----
{
  "reader_policy_ref": {
    "ref": "reader_policy:validated_only"
  }
}
```

### 12.3 Visibility is policy-bound

If content is excluded due to export policy, the export SHOULD record the policy used.

The absence of an assertion from a filtered export MUST NOT be interpreted as proof that the assertion does not exist in the source artifact.

---

## 13. Integrity linkage

The JSON-LD export SHOULD include:

* `source_kristal_id`;
* `source_artifact_ref`;
* `source_content_hash`, when available;
* `export_content_hash`, when the export artifact is content-addressed;
* `export_artifact_id`, when defined;
* export profile ID and version;
* projection policy ID and version, when applicable.

Recommended content hash shape:

```json
{
  "alg": "sha256",
  "value": "<lowercase-hex>"
}
```

If the system uses signatures:

* the JSON-LD export MAY be signed as a derived artifact;
* signatures MUST follow the v5 signature and hashing rules;
* signatures MUST NOT be interpreted as validation of truth unless the signature is part of a declared authority recognition or validation policy.

---

## 14. Example skeleton

A minimal JSON-LD export SHOULD follow this general shape:

```json
{
  "@context": "https://kristal.org/contexts/v5/jsonld/v1",
  "@graph": [
    {
      "@id": "kristal-export:sha256:<hex>",
      "@type": "kristal:JsonLdExport",
      "kristal:schemaVersion": "5.0",
      "kristal:exportProfileId": "kristal.v5:jsonld-1.1",
      "kristal:exportProfileVersion": "1",
      "kristal:sourceArtifact": {
        "@id": "kristal:sha256:<hex>"
      },
      "kristal:projection": "full",
      "kristal:statementModel": "wikibase-aligned"
    },
    {
      "@id": "wd:Q123",
      "@type": "kristal:Entity",
      "kristal:assertion": {
        "@id": "kristal-assertion:sha256:<hex>"
      }
    },
    {
      "@id": "kristal-assertion:sha256:<hex>",
      "@type": "kristal:Assertion",
      "kristal:subject": {
        "@id": "wd:Q123"
      },
      "kristal:property": {
        "@id": "wdt:P31"
      },
      "kristal:value": {
        "@id": "wd:Q5"
      },
      "kristal:assertionStatus": "validated",
      "kristal:certaintyLevel": "high",
      "kristal:validatedAs": "high_confidence_fact",
      "kristal:authorityRecognitionRef": {
        "@id": "authority-recognition:sha256:<hex>"
      }
    }
  ]
}
```

This example is illustrative. Conformance depends on the normative rules in this profile, not on this exact shape.

---

## 15. Conformance tests

An implementation claiming conformance to:

```text
kristal.v5:jsonld-1.1
```

MUST provide fixtures that validate:

* deterministic output bytes for a fixed source artifact and export policy;
* correct profile metadata;
* correct context versioning and stability;
* correct ordering of entities, assertions, qualifiers, references, validation references, and authority recognition references;
* correct encoding of typed literals;
* correct encoding of language-tagged strings;
* correct encoding of entity references as `@id`;
* preservation of assertion identity;
* preservation of source statement identity when present;
* preservation of assertion status when selected by policy;
* preservation of certainty level when selected by policy;
* preservation of validation and authority recognition references when selected by policy;
* correct handling of `full` projection;
* correct handling of `best_rank` projection, if supported;
* byte-stable output across at least two independent runs.

An implementation MUST NOT claim conformance if its export order depends on map iteration order, database return order, filesystem order, locale-dependent sorting, or nondeterministic runtime behavior.

---

## 16. Required implementation declarations

A conforming exporter MUST declare:

```text
export_profile_id
export_profile_version
schema_version
source_artifact_ref
source_artifact_type
statement_model
projection
context_version_or_uri
canonicalization_profile_for_export
canonicalization_version_for_export
```

If filtering is applied, it MUST also declare one or more of:

```text
export_policy_ref
reader_policy_ref
authority_channel_filter
certainty_filter
validation_status_filter
assertion_status_filter
scope_filter
```

---

## 17. Non-goals

This profile does not determine whether an assertion should be trusted.

It only defines how selected Kristal content is projected into deterministic JSON-LD.

Authority, validation, certainty, and reader visibility remain explicit metadata and policy decisions. They MUST NOT be hidden by the export process.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-provenance-nanopub-provo.md"
id=b8048769c60b
kind=markdown
size=22387
lines=744
line_ref=1-744
chunks=3
chunk_refs=1-350,351-700,701-744
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=b8048769c60b:1-350
start=1
end=350
----
# Profile: Provenance Packaging (Nanopublication + PROV-O)

## Status

Draft (Kristal v5 optional standardized profile)

## Purpose

Provide a portable, interoperable way to package **assertions + provenance + publication metadata** for Kristal exports using:

* **Nanopublication structure**: named graphs for Head, Assertion, Provenance, and PubInfo
* **PROV-O** relations for provenance modeling
* Kristal v5 identifiers for assertions, evidence, source artifacts, validation decisions, authority recognition, certainty, and reader policy context

This profile is **optional** and MUST NOT affect core Kristal identity, hashing, signing, validation status, authority recognition, certainty level, or Runtime Pack activation unless explicitly declared by a separate integrity, validation, or distribution profile.

This profile is for packaging and interoperability. It does not decide whether an assertion is true, validated, recognized, high-certainty, disputed, fictional, mythological, rejected, or visible under a reader policy.

---

## Scope

This profile defines:

* the required named graphs and minimum required triples for a nanopublication
* how Kristal assertion and evidence identifiers map into nanopublication and provenance structures
* how to reference source artifacts, including Structured Epistemic States, Exchanges, shards, federations, Runtime Packs, validation decisions, recognition records, and build metadata
* how to carry validation, certainty, and authority-recognition metadata without collapsing them into universal truth
* interoperability rules for stable IRIs, deterministic emission, and serialization

Non-scope:

* defining trust roots, key distribution, or signature algorithms
* mandating RDF dataset hashing
* mandating full PROV completeness beyond the minimal required terms
* determining which authority channels are trusted
* determining whether an assertion is visible under a given reader policy
* turning a signed, exported, or packaged assertion into a validated assertion

Signing and trust behavior is handled by `01-core-spec/signatures-trust.md`.

RDF dataset hashing, when required, is handled by the RDF integrity profile.

Reader visibility is handled by reader policy profiles.

---

## Profile identifier

* `profile_id`: `kristal.v5:provenance-nanopub-provo`
* `profile_version`: `2.0`
* `spec_version`: `5.0`

---

## Inputs

Inputs MAY include any of the following Kristal v5 artifacts:

* a **Structured Epistemic State**
* a **Working Exchange**
* a **Reference Exchange**
* an **Exchange Shard**
* an **Exchange Federation**
* a **Runtime Pack manifest**
* a **Validation Decision**
* an **Authority Recognition** artifact
* a **Revocation** artifact
* source evidence artifacts
* deterministic RDF projections produced by an RDF export profile

The profile operates over Kristal v5 identifiers including:

* `assertion_id`
* `evidence_id`
* `state_id`
* `kristal_id`
* `shard_id`
* `federation_id`
* `runtime_pack_id`
* `validation_decision_id`
* `recognition_id`
* `revocation_id`
* `build_id`

Legacy `claim_id` values MAY be included for compatibility when the source pipeline produced Claim-IR, but Kristal v5 provenance packaging MUST treat `assertion_id` as the primary assertion identifier.

Claim-IR is an extractor proposal profile in Kristal v5. It is not the universal required input to this profile.

---

## Outputs

The output is one or more nanopublications, each expressed as RDF with named graphs:

* `:Head`
* `:Assertion`
* `:Provenance`
* `:PubInfo`

Recommended serialization:

* N-Quads, preferred for transport and tooling
* TriG, acceptable for human-readable named graph exchange

This profile does not require RDF dataset hashing. If RDF hashing is required, the export MUST explicitly declare an RDF integrity profile.

---

## Normative requirements

### R1. Graph structure

Each nanopublication MUST contain exactly these four named graphs:

1. **Head graph**: links the nanopublication to the other graphs
2. **Assertion graph**: contains the assertion triples
3. **Provenance graph**: contains provenance about the assertion
4. **PubInfo graph**: contains publication metadata such as creator, time, software, source Kristal identifiers, validation references, and authority-recognition references

The Head graph MUST identify the Assertion, Provenance, and PubInfo graphs.

The Assertion, Provenance, and PubInfo graphs MUST be distinct graph IRIs.

---

### R2. Stable identifiers

Nanopublication and graph IRIs MUST be stable and deterministic for a given assertion bundle and export policy.

A conforming implementation MUST use one of the following strategies.

#### Strategy A: content-addressed nanopublication IRI

Recommended.

```text
np_id = sha256(deterministic_representation_of(assertion_bundle + export_policy))
base IRI = urn:kristal:np:<np_id>
```

Graph IRIs:

```text
urn:kristal:np:<np_id>#Head
urn:kristal:np:<np_id>#Assertion
urn:kristal:np:<np_id>#Provenance
urn:kristal:np:<np_id>#PubInfo
```

#### Strategy B: deterministic hierarchical IRI

The base IRI is derived from:

```text
source artifact identity + assertion_id OR deterministic assertion bundle id + export policy id
```

Graph IRIs are formed by suffixing:

```text
#Head
#Assertion
#Provenance
#PubInfo
```

The chosen strategy MUST be declared in export metadata.

Implementations MUST NOT generate random nanopublication IRIs for deterministic exports.

---

### R3. Assertion mapping

The Assertion graph MUST correspond to one of:

* a single Kristal `assertion_id`; or
* a deterministic bundle of assertions; or
* a deterministic entity, topic, shard, or scope projection, provided bundling rules are deterministic and recorded.

The Assertion graph MUST contain:

* RDF triples representing the assertion or assertion bundle under the selected RDF export profile
* a link back to each Kristal `assertion_id`
* any legacy `claim_id` only as compatibility metadata, not as the primary v5 identifier

Recommended predicates:

```text
kristal:assertionId
kristal:legacyClaimId
kristal:assertionStatus
kristal:certaintyLevel
kristal:validatedAs
kristal:validationStatus
kristal:authorityChannel
kristal:recognitionStatus
```

A conforming implementation MAY use equivalent stable predicates, but the predicates MUST be declared in export metadata.

---

### R4. Provenance mapping

The Provenance graph MUST express at least one provenance relation from the assertion or assertion bundle to its evidence, source artifact, or derivation record.

Evidence MUST be identified using deterministic IDs, stable source URIs, or source artifact references.

The minimal requirement is:

```text
<assertionNode> prov:wasDerivedFrom <evidenceNode> .
```

If the assertion was compiled from a Structured Epistemic State, the Provenance graph SHOULD include:

```text
<assertionNode> prov:wasDerivedFrom <stateIRI> .
```

If the assertion was included in an Exchange, shard, federation, or Runtime Pack, the Provenance graph SHOULD include references to those artifacts.

Recommended predicates:

```text
kristal:sourceStateId
kristal:kristalId
kristal:shardId
kristal:federationId
kristal:runtimePackId
kristal:evidenceId
kristal:buildId
```

---

### R5. Validation, certainty, and recognition metadata

This profile MUST preserve validation, certainty, and authority-recognition metadata when such metadata is present in the source artifact or export policy.

The export MUST NOT flatten scoped validation into universal truth.

The export MUST distinguish:

```text
artifact identity
assertion identity
assertion status
certainty level
validation status
validated-as status
authority channel
authority recognition
reader policy
```

A signed or exported nanopublication MUST NOT be interpreted as validated unless a validation decision, authority recognition record, or policy explicitly supports that interpretation.

If validation metadata is included, it SHOULD reference explicit Kristal v5 records:

```text
validation_decision_id
recognition_id
authority_channel_id
reader_policy_id
```

Recommended predicates:

```text
kristal:validationDecisionId
kristal:recognitionId
kristal:authorityChannelId
kristal:readerPolicyId
kristal:validatedAs
kristal:certaintyLevel
kristal:assertionStatus
kristal:validationStatus
kristal:recognitionStatus
```

---

### R6. Publication info

The PubInfo graph MUST include:

* `prov:generatedAtTime`
* `prov:wasAttributedTo`
* a pointer to the software or tooling version that produced the nanopublication
* the profile identifier and profile version used for the export

The PubInfo graph SHOULD include:

* source artifact identifiers
* build identifiers
* compiler identity and version
* RDF export profile identifier
* serialization format
* IRI strategy
* bundling policy
* selected reader policy, if the export was produced under one
* authority channel context, if applicable

Required pattern:

```text
<npIRI> prov:generatedAtTime "YYYY-MM-DDThh:mm:ssZ"^^xsd:dateTime .
<npIRI> prov:wasAttributedTo <agentIRI> .
<npIRI> kristal:profileId "kristal.v5:provenance-nanopub-provo" .
<npIRI> kristal:profileVersion "2.0" .
<npIRI> kristal:compilerVersion "..." .
```

---

### R7. Deterministic emission

Given identical inputs, export profile, reader policy selection, bundling policy, IRI strategy, serialization format, and ordering rules, implementations MUST emit byte-stable nanopublication datasets.

Determinism MUST cover:

* nanopublication IRIs
* graph IRIs
* assertion node IRIs
* evidence node IRIs
* ordering of triples or quads
* ordering of evidence references
* ordering of validation and recognition references
* serialization format
* namespace prefix declarations, if the serialization format exposes them

This requirement is about deterministic export generation.

Hashing the RDF dataset is not required by this profile.

---

### R8. No changes to core identity

Enabling this provenance packaging profile MUST NOT change:

* `state_id`
* `kristal_id`
* `shard_id`
* `federation_id`
* `runtime_pack_id`
* Exchange `content_hash`
--- CHUNK END ---

--- CHUNK BEGIN ---
id=b8048769c60b:351-700
start=351
end=700
----
* Runtime Pack content hashes
* authority recognition identifiers
* validation decision identifiers

unless a separate integrity profile explicitly includes these exports in hash coverage.

This profile packages provenance. It does not redefine core Kristal identity.

---

### R9. Working, reference, and research material

Nanopublication export MAY be performed for working, reference, research, archival, disputed, fictional, mythological, or low-certainty material if the active export policy allows it.

The export MUST preserve the relevant status labels.

A nanopublication generated from a Working Exchange MUST NOT be labeled as a Reference Exchange unless an authority recognition or validation decision supports that status.

A nanopublication generated from research or low-certainty material MUST NOT omit its uncertainty, scope, or validation status when that status is available in the source artifact.

---

### R10. Reader policy context

If an export is produced under a reader policy, the PubInfo graph SHOULD identify that policy.

Reader policy context MAY explain why some assertions were included or excluded.

A provenance nanopublication MUST NOT imply that excluded assertions do not exist. It only represents the selected projection.

Recommended predicate:

```text
kristal:readerPolicyId
```

---

## Recommended conventions

### C1. One nanopublication per assertion

Default behavior SHOULD be one nanopublication per `assertion_id` for maximal addressability and incremental updates.

Bundled nanopublications MAY be used when:

* the bundle is deterministic;
* the bundle policy is declared;
* each included `assertion_id` remains addressable;
* the export preserves assertion-level provenance and status.

---

### C2. Include pointers to source artifacts and build metadata

PubInfo SHOULD include:

* `kristal:stateId`
* `kristal:kristalId`
* `kristal:shardId`
* `kristal:federationId`
* `kristal:runtimePackId`
* `kristal:buildId`
* compiler identity
* compiler version
* RDF export profile
* serialization profile

---

### C3. Use PROV-O consistently

Use PROV-O terms:

* `prov:Entity` for evidence artifacts, source states, Exchanges, shards, Runtime Packs, and exported datasets
* `prov:Activity` for build, extraction, normalization, compilation, review, validation, recognition, publication, and export steps
* `prov:Agent` for organizations, services, individuals, validators, authority channels, compilers, distributors, and publishers

Recommended activity labels:

```text
kristal:IngestActivity
kristal:ExtractActivity
kristal:NormalizeActivity
kristal:CompileActivity
kristal:ReviewActivity
kristal:ValidateActivity
kristal:RecognizeActivity
kristal:PublishActivity
kristal:ExportActivity
```

Implementations SHOULD NOT assume that every Kristal v5 artifact passed through Claim-IR, resolution, validation, and compile stages in that exact order.

---

### C4. Preserve uncertainty

When the source artifact includes uncertainty, dispute, fictional scope, mythological scope, rejection, revocation, or low-certainty status, the export SHOULD preserve it.

Recommended values to preserve:

```text
assertion_status
certainty_level
validated_as
validation_status
recognition_status
authority_channel
scope
```

---

### C5. Avoid authority laundering

Exports SHOULD avoid ambiguous labels such as:

```text
true
official
canonical
trusted
safe
```

unless the label is scoped by authority channel, validation policy, recognition status, certainty level, and reader policy.

Preferred labels include:

```text
recognized by <authority channel>
validated as <status>
reference under <reader policy>
asserted by <publisher>
signed by <issuer>
not evaluated
disputed
rejected
revoked
low certainty
fictional
mythological
```

---

## Minimal required triples

### Head graph

Required pattern:

```text
<npIRI> np:hasAssertion <assertionGraphIRI> .
<npIRI> np:hasProvenance <provenanceGraphIRI> .
<npIRI> np:hasPublicationInfo <pubInfoGraphIRI> .
```

Exact nanopublication predicates depend on the chosen nanopublication vocabulary. The implementation MUST declare vocabulary IRIs in export metadata.

---

### Assertion graph

Required pattern:

```text
<assertionNode> kristal:assertionId "<assertion_id>" .
```

If the export contains RDF projection triples for the assertion, those triples MUST appear in the Assertion graph.

Recommended pattern when metadata is available:

```text
<assertionNode> kristal:assertionStatus "<assertion_status>" .
<assertionNode> kristal:certaintyLevel "<certainty_level>" .
<assertionNode> kristal:validatedAs "<validated_as>" .
<assertionNode> kristal:validationStatus "<validation_status>" .
```

---

### Provenance graph

Required pattern:

```text
<assertionNode> prov:wasDerivedFrom <evidenceNode> .
```

Recommended pattern:

```text
<evidenceNode> kristal:evidenceId "<evidence_id>" .
<assertionNode> prov:wasDerivedFrom <sourceArtifactNode> .
<sourceArtifactNode> kristal:kristalId "<kristal_id>" .
```

If a validation decision is referenced:

```text
<assertionNode> kristal:validationDecisionId "<validation_decision_id>" .
```

If an authority recognition is referenced:

```text
<assertionNode> kristal:recognitionId "<recognition_id>" .
```

---

### PubInfo graph

Required pattern:

```text
<npIRI> prov:generatedAtTime "YYYY-MM-DDThh:mm:ssZ"^^xsd:dateTime .
<npIRI> prov:wasAttributedTo <agentIRI> .
<npIRI> kristal:profileId "kristal.v5:provenance-nanopub-provo" .
<npIRI> kristal:profileVersion "2.0" .
<npIRI> kristal:compilerVersion "..." .
```

Recommended pattern:

```text
<npIRI> kristal:sourceStateId "<state_id>" .
<npIRI> kristal:kristalId "<kristal_id>" .
<npIRI> kristal:buildId "<build_id>" .
<npIRI> kristal:rdfExportProfileId "<profile_id>" .
<npIRI> kristal:readerPolicyId "<reader_policy_id>" .
<npIRI> kristal:iriStrategy "<strategy_id>" .
<npIRI> kristal:serializationFormat "application/n-quads" .
```

---

## Interoperability constraints

Implementations MUST document:

* which nanopublication vocabulary is used
* which PROV-O vocabulary version is used
* the IRI strategy
* bundling rules, if bundling is used
* the serialization format
* deterministic ordering rules
* RDF export profile used
* whether validation, certainty, and authority-recognition metadata are included
* whether reader policy context is included
* whether the export is covered by any RDF integrity profile

Implementations SHOULD declare these settings in machine-readable export metadata.

---

## Failure modes and required behaviors

### Missing source artifact identity

If the source artifact identity cannot be determined, export MAY proceed only if the export policy allows anonymous or source-limited exports.

The missing identity MUST be reflected in export metadata or validation output.

---

### Missing assertion identifier

If an assertion lacks a deterministic `assertion_id`, nanopublication emission MUST NOT proceed for that assertion.

---

### Missing evidence

If an evidence link is missing for an assertion:

* emission MUST NOT proceed if the active export policy requires evidence;
* emission MAY proceed if the active export policy allows evidence-limited assertions;
* the emitted nanopublication MUST preserve the assertion’s status, certainty level, and warning metadata when available.

This profile MUST NOT assume that missing evidence is always fatal. Fatality depends on export policy, validation policy, and reader policy.

---

### Validation not completed

If validation has not been completed for an assertion or artifact, nanopublication emission MAY proceed if the export policy allows non-validated material.

The export MUST NOT represent the assertion as validated.

---

### Validation rejected or revoked

If an assertion, artifact, validation decision, or authority recognition is rejected or revoked, nanopublication emission MAY proceed for archival, audit, research, diagnostic, or transparency purposes if the export policy allows it.

The export MUST preserve the rejected or revoked status.

---

### Unsupported serialization

If an implementation cannot emit the declared serialization format, export MUST fail for that profile execution.

---

### Non-deterministic bundle

If bundling rules are non-deterministic, export MUST fail for that bundle.

---

## Conformance tests

A conforming implementation MUST provide fixtures demonstrating:

* deterministic nanopublication IRI generation for the same inputs and policies
* deterministic dataset emission for the same inputs and policies
* correct mapping of `assertion_id` into the Assertion graph
* compatibility mapping of legacy `claim_id`, when present
* correct mapping of `evidence_id` and evidence links into PROV-O relations
* preservation of assertion status
* preservation of certainty level
* preservation of validation status
* preservation of `validated_as`
* preservation of authority recognition references
* preservation of reader policy context, when used
* one nanopublication per assertion
* deterministic bundled nanopublications
* enforcement that this profile does not alter core identity or hashing
* export of working material without falsely labeling it as reference material
* export of validated material without implying universal truth
* export of rejected, disputed, fictional, or mythological material with labels preserved

Conformance tests SHOULD include:

* Structured Epistemic State input
* Working Exchange input
* Reference Exchange input
* shard input
* federation input
* Runtime Pack reference
* validation decision reference
* authority recognition reference
* reader-policy-filtered export
* missing-evidence warning case
* missing-evidence fatal case
--- CHUNK END ---

--- CHUNK BEGIN ---
id=b8048769c60b:701-744
start=701
end=744
----
* rejected assertion export
* mythological corpus export
* fictional corpus export
* independent research bundle export
* Wikidata Seed Kristal export

---

## Security and correctness considerations

Implementations SHOULD defend against:

* provenance laundering
* authority laundering
* converting publication metadata into validation metadata
* converting signatures into universal trust
* omitting uncertainty labels
* omitting rejection, revocation, or disputed status
* silently dropping evidence references
* silently changing assertion identifiers
* non-deterministic IRI generation
* non-deterministic triple ordering
* graph IRI collisions
* bundle ambiguity
* reader-policy confusion
* exporting a filtered projection as if it were the complete corpus

A provenance nanopublication is a packaging artifact. It is not, by itself, proof that the assertion is true, validated, high-certainty, or recognized by any particular authority channel.

---

## Open questions

The following profile decisions remain open:

* Which nanopublication vocabulary will be standardized, or should a small allowed set be supported?
* Should one nanopublication per assertion become a MUST instead of a SHOULD?
* Should multiple evidence nodes per assertion be mandatory when available?
* Should evidence node ordering be defined by lexical IRI order, deterministic source order, or canonicalized evidence object hash?
* Should reader policy context be mandatory for filtered exports?
* Should validation and authority recognition references be required for Reference Exchange exports?
* Should profile exports optionally include a compact JSON sidecar for non-RDF runtimes?
* Should RDF integrity be recommended by default for public authority-recognized exports?
* Should rejected or revoked assertions be exportable by default only in archival or audit modes?
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-query-tpf-pagination.md"
id=230b305326ba
kind=markdown
size=18110
lines=574
line_ref=1-574
chunks=2
chunk_refs=1-350,351-574
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=230b305326ba:1-350
start=1
end=350
----
# Profile: Query — TPF-like Pagination (Kristal v5)

## Status

Optional standardized profile — Kristal v5

## Purpose

This profile defines an **offline-friendly, TPF-like pagination contract** for querying Kristal Runtime Packs.

The intent is to provide:

* predictable, cacheable, low-bandwidth query behavior;
* stable pagination semantics across implementations;
* reproducible cursor behavior over immutable Runtime Pack snapshots;
* optional cardinality metadata to support planning and user interfaces;
* pagination over reader-policy, validation-status, certainty-level, and authority-channel views.

This profile does **not** attempt to replicate full SPARQL semantics. Runtime Packs remain intentionally constrained, offline-executable, and governed by their declared query contract.

## Scope

This profile specifies:

* request and response envelopes for paginated queries;
* cursor-token pagination semantics;
* cursor stability guarantees;
* ordering requirements for correct pagination;
* optional cardinality metadata;
* declared-capability behavior;
* interaction with reader policies, authority channels, validation status, and certainty levels.

This profile does not specify:

* the full query language, which is defined by `04-query/query-contract.md`;
* network transport, such as HTTP versus local API;
* how Runtime Packs are built, which is defined by Runtime Pack construction policies;
* how authority channels validate or recognize claims, which is defined by authority and validation contracts.

Normative behaviors in this profile MUST hold regardless of transport.

---

## Conformance

An implementation claims this profile by including the following profile identifier in the Runtime Pack Manifest `profiles[]`:

```text
kristal.v5:profile-query-tpf-pagination@1
```

The Runtime Pack Manifest MUST also declare `query_contract` with:

* `query_contract.contract_id`, non-empty;
* `query_contract.supports_pagination = true`.

If the implementation supports cardinality estimates, it MUST also declare:

* `query_contract.supports_cardinality_estimates = true`.

If the implementation supports reader-policy filtering, authority-channel filtering, validation-status filtering, certainty-level filtering, or `validated_as` filtering, it MUST declare those capabilities in `query_contract.supported_filters` or an equivalent v5-compatible capability field.

If this profile is claimed, the implementation MUST meet the requirements below.

---

## Terminology

* **Page**: a bounded subset of results from a query.
* **Cursor token**: an opaque token allowing the client to fetch the next page.
* **Stable order**: a total order over the result set that does not change during pagination.
* **Reader policy**: a declared policy that determines which assertions, artifacts, authorities, validation statuses, certainty levels, or scopes are visible to a reader.
* **Filtered view**: a query view restricted by reader policy, authority channel, validation status, certainty level, scope, or profile-specific filters.
* **Snapshot**: the immutable Runtime Pack content addressed by `runtime_pack_id`.

---

# 1. Capability declaration

## 1.1 Required manifest fields

A Runtime Pack that claims this profile MUST declare the query contract in the Runtime Pack Manifest:

* `query_contract.contract_id`;
* `query_contract.supports_pagination = true`.

The Runtime Pack SHOULD also declare:

* `query_contract.supported_filters`;
* `query_contract.supported_reader_modes`;
* `query_contract.supported_ordering`;
* `query_contract.max_page_size`, if a maximum is enforced;
* `query_contract.capabilities_ref`, if capabilities are stored in a separate file.

## 1.2 Declared capabilities

If a Runtime Pack claims this profile and a consumer requests pagination within the declared capability set, the implementation MUST provide pagination behavior as specified here.

If a request asks for a capability not declared by the Runtime Pack, the implementation MUST return a structured error rather than returning partial or misleading results.

## 1.3 Capability labels

If the Runtime Pack supports filtering by Kristal v5 epistemic labels, the capabilities object SHOULD indicate support for:

* `artifact_status`;
* `assertion_status`;
* `validation_status`;
* `certainty_level`;
* `validated_as`;
* `authority_channel`;
* `recognition_status`;
* `scope.domain`;
* `scope.subdomain`;
* `reader_policy`.

---

# 2. Stable ordering is mandatory for pagination

## 2.1 Stable total order

Paginated queries MUST have a stable total order over results.

The order MUST be derived from one of:

* the Runtime Pack’s recorded `policies.data_ordering`;
* a query-contract-declared stable ordering profile;
* an explicit ordering parameter allowed by the base query contract.

Implementations MUST NOT paginate over an unstable or implementation-dependent ordering.

## 2.2 Ordering and filtered views

If the query is evaluated over a filtered view, the stable order MUST be applied after the filter is resolved.

Examples of filtered views include:

* `reader_policy = validated_only`;
* selected authority channels;
* selected validation statuses;
* selected certainty levels;
* selected scopes;
* selected `validated_as` values.

The filter MUST NOT change the meaning of the ordering policy. It only changes the visible result set.

## 2.3 Unorderable queries

If a query’s semantics do not produce a stable order, or if the Runtime Pack cannot derive one from declared policies, the implementation MUST reject pagination for that query with a structured error.

---

# 3. Page size

## 3.1 Required parameter

Implementations MUST support a `page_size` parameter.

`page_size` MUST be an integer greater than zero.

## 3.2 Maximum page size

Implementations SHOULD enforce a maximum page size to protect offline devices.

If enforced, the maximum MUST be documented and discoverable via capabilities.

## 3.3 Mapping to base query contract

The base query contract uses `limit`.

When this pagination profile is used:

* the effective `limit` MUST equal `page_size`;
* clients SHOULD omit `limit` inside the `query` object;
* if `query.limit` is present and differs from `page_size`, the implementation MUST return `INVALID_QUERY`.

---

# 4. Cursor tokens

## 4.1 Opaque tokens

Cursor tokens MUST be opaque to clients.

Clients MUST NOT depend on cursor token structure.

## 4.2 Determinism

Cursor tokens MUST be deterministic for the same:

* `runtime_pack_id`;
* `query_hash`;
* `page_size`;
* `cursor_position`;
* selected reader policy;
* selected filters;
* stable ordering policy.

Cursor tokens MUST NOT depend on wall-clock time.

## 4.3 Runtime Pack binding

Cursor tokens MUST be bound to the specific Runtime Pack identified by `runtime_pack_id`.

A token from one Runtime Pack MUST NOT be valid on another Runtime Pack.

## 4.4 Query binding

Cursor tokens MUST be bound to the query payload used to produce them.

A cursor token produced for one query MUST NOT be accepted for another query.

## 4.5 Resume behavior

Cursor tokens MUST include sufficient information, directly or indirectly, to resume iteration without changing the result sequence.

The internal mechanism is implementation-defined, but the externally visible behavior MUST be stable.

---

# 5. Pagination API — logical contract

Regardless of transport, the logical interface MUST accept:

* `query`: a query object defined in `04-query/query-contract.md`;
* `page_size`: integer greater than zero;
* `cursor`: optional opaque token;
* `reader_policy`: optional reader policy identifier or inline reader policy object, if supported;
* `filters`: optional object containing declared filter dimensions, if supported.

The query object MUST omit `limit` or set it equal to `page_size`.

The response MUST return:

* `runtime_pack_id`;
* `query_hash`;
* `page_size`;
* `results`;
* `next_cursor`;
* `page_info`.

If supported and declared, the response MAY also return:

* `cardinality`;
* `applied_reader_policy`;
* `applied_filters`;
* `result_labels`;
* `warnings`.

---

# 6. Response envelope

A conformant response MUST include:

* `runtime_pack_id`: Runtime Pack identifier;
* `query_hash`: hash of the canonical query payload;
* `page_size`: integer;
* `results`: array;
* `next_cursor`: string or null;
* `page_info`: object.

`page_info` MUST include:

* `returned`: integer count of results returned;
* `has_more`: boolean.

If the implementation supports cardinality estimates and declares that support in the manifest, responses MUST also include `cardinality`.

## 6.1 Result labels

If the query contract supports epistemic labels, results SHOULD preserve or expose relevant labels, including:

* `assertion_status`;
* `validation_status`;
* `certainty_level`;
* `validated_as`;
* `authority_channel`;
* `recognition_status`;
* `scope`;
* `provenance_refs`;
* `evidence_refs`.

If labels are omitted from individual rows for performance reasons, the response MUST provide a declared mechanism for retrieving them.

A response MUST NOT flatten authority-scoped validation into universal validation.

A response MUST NOT hide that a result is hypothetical, disputed, fictional, mythological, rejected, revoked, or validated only by a specific authority channel when that information is part of the source artifact and relevant to the active reader policy.

---

# 7. Query hashing

## 7.1 Query hash computation

Implementations MUST compute:

```text
query_hash = sha256(JCS(query_payload))
```

where `query_payload` includes:

* the query object;
* `page_size`;
* any explicit ordering parameters allowed by the base query contract;
* selected reader policy identifiers or inline reader policy content;
* selected authority-channel filters;
* selected validation-status filters;
* selected certainty-level filters;
* selected `validated_as` filters;
* selected scope filters;
* any other declared query-affecting filters.

`query_payload` MUST NOT include:

* `cursor`.

## 7.2 Limit normalization

For query hashing, `limit` MUST be normalized according to this profile:

* if `query.limit` is omitted, the normalized query payload uses `limit = page_size`;
* if `query.limit` is present and equals `page_size`, it MAY remain present or be normalized to the same canonical representation;
* if `query.limit` differs from `page_size`, the request is invalid and no query hash needs to be returned.

## 7.3 Canonicalization

Canonicalization for `query_hash` MUST use RFC 8785 JCS under the Kristal v5 canonicalization identifiers:

```text
canonicalization_profile = "kristal.v5:jcs-rfc8785"
canonicalization_version = "1"
```

---

# 8. Capabilities discovery

Implementations MUST provide a capabilities object discoverable via one of:

* an explicit API call;
* a static file in the Runtime Pack, for example `query/capabilities.json`;
* a manifest-declared `query_contract.capabilities_ref`.

Capabilities MUST include at least:

* supported query contract IDs;
* supported query profile IDs;
* maximum page size, if enforced;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=230b305326ba:351-574
start=351
end=574
----
* whether cardinality estimates are supported;
* supported ordering modes;
* supported reader modes;
* supported filters.

Capabilities SHOULD include support declarations for:

* `reader_policy`;
* `artifact_status`;
* `assertion_status`;
* `validation_status`;
* `certainty_level`;
* `validated_as`;
* `authority_channel`;
* `recognition_status`;
* `scope.domain`;
* `scope.subdomain`.

---

# 9. Cardinality metadata

Cardinality metadata is optional but standardized.

If the implementation supports cardinality estimates, it MUST:

* set `query_contract.supports_cardinality_estimates = true` in the Runtime Pack manifest;
* include `cardinality` in paginated responses.

## 9.1 Cardinality object

```json
{
  "cardinality": {
    "type": "estimate",
    "value": 12345,
    "confidence": "medium"
  }
}
```

## 9.2 Cardinality rules

* `value` MUST be a non-negative integer.
* `type` MUST be either `estimate` or `exact`.
* If exact cardinality is available, the implementation MAY use `"type": "exact"` and omit `confidence`.
* If cardinality is not supported, responses MUST NOT include `cardinality`.

## 9.3 Cardinality over filtered views

If the query uses reader-policy or epistemic filters, cardinality MUST refer to the filtered result set, not the unfiltered source artifact.

---

# 10. Error handling

Errors MUST be structured and MUST include:

* `code`: stable string identifier;
* `message`: human-readable message;
* `details`: optional object.

Required error codes:

* `UNSUPPORTED_PAGINATION`: query type cannot be paginated;
* `INVALID_CURSOR`: token is invalid or not bound to this pack/query;
* `PAGE_SIZE_TOO_LARGE`: requested page size exceeds the supported maximum;
* `INVALID_QUERY`: query does not conform to the base query contract or this profile;
* `UNSUPPORTED_FILTER`: requested filter is not supported by the declared query contract;
* `UNSUPPORTED_READER_POLICY`: requested reader policy is not supported;
* `UNSTABLE_ORDERING`: query cannot be paginated with stable ordering;
* `PACK_MISMATCH`: cursor or query is bound to another Runtime Pack;
* `INTERNAL_ERROR`: unexpected implementation error.

An implementation MUST NOT return partial or incorrect results when a request cannot be satisfied under declared capabilities.

---

# 11. Determinism and snapshot guarantees

## 11.1 Repeated calls

For a given Runtime Pack, pagination MUST be consistent across repeated calls:

* using the same cursor token MUST yield the same subsequent results;
* using the same query, page size, reader policy, filters, and cursor MUST yield the same page;
* tokens MUST remain valid for the lifetime of the Runtime Pack.

## 11.2 Immutable snapshots

Implementations MUST treat Runtime Packs as immutable snapshots.

If the underlying data changes, it MUST be represented as a new Runtime Pack with a new `runtime_pack_id`.

## 11.3 Filtered snapshots

If a Runtime Pack materializes a filtered view, the filter set is part of the snapshot identity.

A filtered Runtime Pack MUST NOT present itself as containing the full source artifact.

---

# 12. Declared-capability correctness

If a Runtime Pack Manifest claims this profile but the implementation cannot provide correct pagination behavior for a request that falls within the declared capability set, it MUST return a structured error.

It MUST NOT return partial, unstable, unlabeled, or misleading results.

This rule applies especially when:

* ordering cannot be made stable;
* cursor state is invalid;
* a requested reader policy is unsupported;
* a requested validation or certainty filter is unsupported;
* a requested authority-channel filter is unsupported;
* the implementation cannot preserve required result labels.

---

# 13. Non-normative guidance

Implementers SHOULD prefer cursor designs that can resume without full scans, such as:

* last-seen key;
* index position;
* stable row group position;
* bitmap-backed filter position;
* deterministic shard cursor.

Cursor tokens should remain opaque even when they encode deterministic state.

Implementers SHOULD keep default page sizes small for offline or low-memory environments.

Offline clients may use the following as a primary cache key strategy:

```text
(runtime_pack_id, query_hash, cursor)
```

If reader policies or filters are used, they are already included in `query_hash`.

---

# 14. Example request and response

## 14.1 Example request

```json
{
  "query": {
    "type": "spo",
    "s": "Q42",
    "p": "P31"
  },
  "page_size": 50,
  "reader_policy": "reader_policy:validated-only",
  "filters": {
    "authority_channel": ["authority:wikidata-seed"],
    "validation_status": ["validated"],
    "certainty_level": ["medium", "high", "established"]
  }
}
```

## 14.2 Example response

```json
{
  "runtime_pack_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "query_hash": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "page_size": 50,
  "results": [
    {
      "s": "Q42",
      "p": "P31",
      "o": "Q5",
      "assertion_status": "validated",
      "validation_status": "validated",
      "certainty_level": "established",
      "validated_as": "institutional_reference",
      "authority_channel": "authority:wikidata-seed",
      "scope": {
        "domain": "wikidata"
      }
    }
  ],
  "next_cursor": "opaque-token",
  "page_info": {
    "returned": 1,
    "has_more": true
  },
  "cardinality": {
    "type": "estimate",
    "value": 12345,
    "confidence": "medium"
  },
  "applied_reader_policy": "reader_policy:validated-only",
  "applied_filters": {
    "authority_channel": ["authority:wikidata-seed"],
    "validation_status": ["validated"],
    "certainty_level": ["medium", "high", "established"]
  }
}
```

---

# 15. Summary

A Kristal v5 Runtime Pack that claims this profile provides stable, deterministic pagination over immutable Runtime Pack snapshots.

The profile guarantees:

* stable ordering;
* deterministic cursor behavior;
* query hashing for cacheability and comparability;
* structured errors;
* optional cardinality metadata;
* declared support for reader policies and epistemic filters;
* preservation of validation, certainty, authority, and scope labels.

This profile does not claim that all visible data is universally true or maximally certain.

It guarantees that paginated query behavior is stable, explicit, inspectable, and aligned with the Runtime Pack’s declared policies.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-rdf-integrity-rdfc.md"
id=60641ec4b4e5
kind=markdown
size=15721
lines=370
line_ref=1-370
chunks=2
chunk_refs=1-350,351-370
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=60641ec4b4e5:1-350
start=1
end=350
----
# Profile: RDF Integrity (RDFC) (Kristal v5)

## Status

Draft

## Purpose

Provide an optional, standardized integrity mechanism for Kristal v5 RDF exports by computing a deterministic `rdf_hash` over a declared RDF projection using an RDF Dataset Canonicalization method and CI conformance gating.

This profile is designed for deployments that need **semantic-web grade export integrity**. Independent verifiers can confirm that exported RDF content matches the declared hash, while Kristal v5 keeps its normative core focused on portable epistemic artifacts, structured references, provenance, authority recognition, validation status, certainty metadata, and query semantics.

This profile does not decide whether an assertion is true, validated, recognized, disputed, fictional, mythological, or high-certainty. It only verifies that a declared RDF export projection is byte-stable after RDF dataset canonicalization and that its declared hash matches the exported RDF content.

## Scope

In scope:

* Canonicalization and hashing of RDF datasets for selected export projections
* CI conformance gating using an RDFC test suite subset or declared equivalent
* Explicit coverage declaration for hashed RDF projections
* Resource limits for RDF canonicalization and hashing
* Structured reporting when integrity production or verification cannot be completed
* Export-level integrity verification independent of Kristal core JSON identity

Out of scope:

* Kristal core JSON canonicalization and `kristal_id`, which are handled by the Kristal v5 core using JCS-based canonicalization
* Runtime Pack hashing, which is handled by Runtime Pack manifests
* Authority recognition, validation decisions, certainty levels, or reader-policy filtering
* Any requirement that this profile is enabled by default
* Any claim that RDF export integrity implies epistemic validation

## Dependencies

This profile depends on at least one deterministic RDF export profile, typically:

* `profile-rdf-wdqs-export` using a declared projection such as `full` or `truthy`

The export MUST be deterministic and byte-stable according to its export profile before this integrity profile is applied.

If the underlying RDF export profile is non-deterministic, incomplete, underspecified, or projection-ambiguous, this RDF integrity profile MUST report that it cannot produce or verify a reliable `rdf_hash` for that projection.

## Normative keywords

MUST, SHOULD, and MAY are used as in RFC 2119.

## Profile activation

An implementation enables this profile by declaring, in its export manifest:

* `profile.id = "rdf-integrity-rdfc"`
* `profile.version = "5.0"`
* `rdfc.algorithm = "RDFC-1.0"` or a later explicitly supported algorithm
* `rdf_hash.alg = "sha256"`
* `rdf_hash.coverage` with explicitly enumerated projections covered by the hash

Profile activation means only that RDF export integrity is being computed or verified for the declared projection(s). It does not mean that the exported assertions are validated, recognized, high-certainty, or visible under any particular reader policy.

## Covered projections

When enabled, the implementation MUST declare exactly which RDF projection or projections are hash-covered.

At minimum, the manifest MUST include:

* `coverage.projection`: `"full"`, `"truthy"`, or another declared export projection
* `coverage.export_profile_id`: for example, `"rdf-wdqs"`
* `coverage.graphs`: which named graphs are included in the hash
* `coverage.exclusions`: which graphs, triples, metadata fields, timestamps, signatures, or generated artifacts are excluded
* `coverage.scope`: the Kristal scope covered by the export, when applicable
* `coverage.source_artifact_ref`: the Exchange, shard, dataset, or export artifact from which the RDF projection was produced

Coverage MUST be explicit enough that an independent verifier can reconstruct the same RDF dataset boundary.

## Projection equivalence rules

Differences between projections, such as `full` versus `truthy`, MUST NOT be treated as integrity failures unless the export profile explicitly requires projection equivalence.

Each projection’s `rdf_hash` is independently meaningful.

For example:

* a `full` projection hash verifies the declared full RDF projection;
* a `truthy` projection hash verifies the declared truthy RDF projection;
* a mismatch between `full` and `truthy` is not an integrity problem unless a profile incorrectly declared them equivalent.

## Canonicalization method

The canonicalization algorithm MUST be an RDF Dataset Canonicalization method compatible with RDFC-1.0 style conformance, such as a method producing canonical N-Quads output.

Requirements:

* The input MUST be an RDF dataset.
* A single RDF graph MUST be represented as a dataset before canonicalization.
* The canonicalization method MUST produce a deterministic canonical byte stream.
* Blank nodes MUST be deterministically canonicalized, or deterministically skolemized before canonicalization if the selected algorithm and export profile explicitly allow and document that behavior.
* The selected canonicalization method and version MUST be recorded in the manifest.
* The canonicalization implementation identifier and version MUST be recorded in the manifest.

The term “canonicalization” in this profile refers only to deterministic RDF dataset normalization for hashing. It does not imply canonical truth, universal authority, or epistemic finality.

## Hash computation

`rdf_hash.value` MUST be computed as:

```text
SHA-256(canonical_rdf_bytes)
```

Where:

* `canonical_rdf_bytes` is the canonical output produced by the selected RDFC algorithm;
* canonical bytes MUST be treated as a raw byte sequence;
* no platform-dependent newline, Unicode, path, locale, or serialization normalization may be applied after canonicalization unless the selected algorithm explicitly defines it.

The manifest MUST include:

* RDF canonicalization algorithm identifier
* RDF canonicalization algorithm version
* canonicalization implementation identifier and version
* hash algorithm identifier
* exact export artifact or artifacts hashed
* exact projection coverage
* any declared exclusions

## Resource limits

Because RDF dataset canonicalization can exhibit worst-case behavior, implementations MUST support resource limits and MUST declare them in the manifest.

Minimum required limit fields:

* `limits.timeout_ms`
* `limits.max_triples` or equivalent dataset size cap
* `limits.max_blank_nodes` or equivalent blank-node complexity cap
* `limits.max_memory_mb`

Recommended additional limit fields:

* `limits.max_named_graphs`
* `limits.max_output_bytes`
* `limits.max_cpu_ms`
* `limits.max_recursion_depth`, when relevant to the implementation

## Limit exceed behavior

If declared resource limits are exceeded during canonicalization or hashing:

* the implementation MUST NOT emit a partial `rdf_hash`;
* the implementation MUST emit a structured issue in the export report;
* the implementation MUST preserve enough diagnostic information for reproducibility and review;
* the export manifest MUST NOT present the missing hash as successfully produced.

If a consuming policy declares `rdf_hash` as required for a given artifact, projection, authority channel, or assurance level, then a missing or unverified `rdf_hash` means the artifact is **not accepted under that policy**.

This is a policy outcome, not a statement about the underlying truth or falsity of the exported assertions.

## CI gating

If this profile is enabled in a build:

* CI MUST gate the canonicalization implementation against a selected subset of the W3C RDFC-1.0 test suite or an equivalent conformance suite declared by the implementation.
* The selected subset MUST be documented.
* The selected subset MUST be versioned.
* The rationale for subset selection SHOULD be documented when the full suite is not used.
* CI results SHOULD be linked from the export report or build record.

A build that cannot demonstrate conformance to the declared test subset MUST NOT claim conformance to this profile.

## Verification procedure

A verifier checks:

1. The export manifest declares `rdf-integrity-rdfc` profile activation, coverage, algorithms, implementation versions, and resource limits.
2. The verifier regenerates or loads the RDF export for the declared projection.
3. The verifier confirms that the declared coverage boundary is reproducible.
4. The verifier canonicalizes the RDF dataset using the declared algorithm.
5. The verifier hashes the canonical bytes with SHA-256.
6. The verifier compares the computed value to `rdf_hash.value`.
7. The verifier reports verification status for the declared projection.

Verification statuses SHOULD include:

* `verified`
* `hash_mismatch`
* `verification_not_possible`
* `coverage_ambiguous`
* `algorithm_unsupported`
* `limits_exceeded`
* `source_artifact_unavailable`

If the computed hash does not match `rdf_hash.value`, verification fails for that RDF projection.

If resource limits prevent verification, the verifier MUST report `verification_not_possible` or `limits_exceeded` with structured details.

If the active reader policy, export policy, authority channel, or assurance context requires RDF hash verification, then a projection that cannot be verified MUST NOT be treated as accepted under that policy.

## Manifest fields

Implementations SHOULD represent profile activation in the export manifest with fields similar to:

```json
{
  "profiles": [
    {
      "id": "rdf-integrity-rdfc",
      "version": "5.0",
      "enabled": true,
      "params": {
        "rdfc": {
          "algorithm": "RDFC-1.0",
          "version": "1.0",
          "implementation": {
            "name": "string",
            "version": "string"
          }
        },
        "coverage": {
          "projection": "full",
          "export_profile_id": "rdf-wdqs",
          "graphs": [],
          "exclusions": [],
          "scope": {},
          "source_artifact_ref": {}
        },
        "limits": {
          "timeout_ms": 30000,
          "max_triples": 1000000,
          "max_blank_nodes": 100000,
          "max_memory_mb": 4096
        },
        "rdf_hash": {
          "alg": "sha256",
          "value": "string",
          "artifact_ref": "string"
        }
      }
    }
  ]
}
```

The exact manifest schema MAY differ, but it MUST preserve the same semantics: profile identity, profile version, algorithm declaration, coverage declaration, limits, and hash value.

## Error and warning reporting

When enabled, the exporter MUST emit structured issues.

Errors:

* `RDFC_CANONICALIZATION_FAILED`
* `RDFC_LIMIT_EXCEEDED`
* `RDFC_UNSUPPORTED_DATASET_FEATURE`
* `RDFC_HASH_MISMATCH`
* `RDFC_COVERAGE_AMBIGUOUS`
* `RDFC_EXPORT_NON_DETERMINISTIC`
* `RDFC_ALGORITHM_UNSUPPORTED`
* `RDFC_SOURCE_ARTIFACT_UNAVAILABLE`

Warnings:

* `RDFC_SUBSET_TEST_SUITE`
* `RDFC_LIMITS_TIGHT`
* `RDFC_SKOLEMIZED_BLANK_NODES`
* `RDFC_METADATA_GRAPH_EXCLUDED`
* `RDFC_PROJECTION_NOT_EQUIVALENT`
* `RDFC_OPTIONAL_PROFILE_NOT_ENABLED`

Each issue SHOULD include:

* `code`
* `severity`
* `message`
* `path` or `artifact_ref`
* `projection`
* `details`

Recommended issue shape:

```json
{
  "code": "RDFC_LIMIT_EXCEEDED",
  "severity": "error",
  "message": "RDF canonicalization exceeded the declared blank-node limit.",
  "artifact_ref": "exports/wdqs-full.nq",
  "projection": "full",
  "details": {
    "limit": "max_blank_nodes",
    "declared_value": 100000,
    "observed_value": 145392
  }
}
```

## Determinism requirements

If the underlying export is deterministic according to its export profile, and the canonicalization algorithm passes CI gating, then `rdf_hash` MUST be stable across runs given identical inputs.

If determinism is violated and the hash changes across identical rebuilds:

* the build MUST be treated as non-conformant under this profile;
* the export report MUST include a structured error;
* the manifest MUST NOT claim a verified stable RDF hash for that projection.

Determinism requirements apply to the declared RDF projection only. They do not imply that other projections, exports, reader-policy views, or runtime packs are identical.

## Conformance

A build is conformant to this profile if:

* profile activation is declared with `profile.id = "rdf-integrity-rdfc"`;
* `profile.version = "5.0"` is declared;
* coverage boundaries are explicitly declared;
* canonicalization and hashing follow the declared algorithms;
* resource limits are enforced and recorded;
* CI gating is applied when the profile is enabled;
* structured errors are emitted when hash production or verification cannot complete;
* no partial `rdf_hash` is emitted;
* deterministic rebuilds produce stable hashes for identical inputs;
* verification procedures can be independently reproduced within declared limits.

A build is not conformant to this profile if:

* the RDF projection boundary is ambiguous;
* the hash algorithm or canonicalization algorithm is not declared;
* profile activation is claimed without a verifiable hash;
* a partial hash is emitted after canonicalization failure;
* failures are hidden or downgraded into successful verification;
* the manifest presents export integrity as epistemic validation.

## Interactions with other profiles

* **RDF WDQS Export** provides the RDF dataset this profile hashes.
* **Provenance (Nanopub + PROV-O)** may package related graphs, attribution, and provenance structures, but does not substitute for canonical RDF dataset hashing.
* **Validation SHACL** and **Validation ShEx** may validate RDF shape conformance, but shape validity does not substitute for RDF export integrity.
* **Reader Policy** may require or ignore this profile depending on assurance needs.
* **Authority Recognition** may require RDF integrity evidence before recognizing an export, but RDF integrity alone does not imply recognition.
* **Runtime Pack Manifest** handles runtime distribution integrity separately.
* **Kristal Core Identity** remains defined by the core manifest and JSON canonicalization rules; this profile MUST NOT redefine `kristal_id`.

## Security and trust considerations

This profile protects RDF export integrity, not epistemic truth.

A successful RDF hash verification means:

* the declared RDF projection was reproduced;
* the canonicalized RDF bytes match the declared hash;
* the export boundary, algorithm, and limits were sufficient for verification.

It does not mean:
--- CHUNK END ---

--- CHUNK BEGIN ---
id=60641ec4b4e5:351-370
start=351
end=370
----

* every exported assertion is true;
* every assertion is validated;
* the export is recognized by an authority channel;
* the export is visible under a strict reader policy;
* the export has high certainty.

Implementations and user interfaces SHOULD keep these distinctions visible.

## Summary

This profile adds optional RDF export integrity to Kristal v5.

It provides a deterministic way to verify RDF projections using RDF Dataset Canonicalization and SHA-256 hashing. It does not define truth, validation, recognition, certainty, or reader visibility.

The profile’s responsibility is narrow and technical:

> A declared RDF projection can be independently canonicalized, hashed, and compared against the manifest.

All epistemic status remains governed by Kristal v5 validation, certainty, authority recognition, federation, and reader-policy rules.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-rdf-wdqs-export.md"
id=af7ce63c7144
kind=markdown
size=22605
lines=808
line_ref=1-808
chunks=3
chunk_refs=1-350,351-700,701-808
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=af7ce63c7144:1-350
start=1
end=350
----
# Profile: RDF WDQS Export (Kristal v5)

## Status

Draft

## Purpose

Define a deterministic RDF export profile for Kristal v5 that is compatible with common Wikidata Query Service (WDQS) expectations and downstream RDF tooling, while keeping Kristal’s core identity, scoped validation, authority recognition, certainty metadata, and offline runtime constraints intact.

This profile specifies:

* what graphs are exported,
* how statements are represented, including qualifiers and references,
* rank and WDQS-style `truthy` projection behavior,
* how Kristal validation, certainty, and authority metadata MAY be exposed in RDF,
* required determinism rules,
* and conformance expectations.

This profile does not make exported RDF globally true by default. It exports structured assertions and their metadata in a deterministic RDF shape. Reader policy, authority recognition, validation scope, and certainty level remain explicit Kristal concerns.

## Scope

In scope:

* RDF dataset shape and serialization requirements
* item, property, statement, qualifier, reference, and value modeling
* rank and WDQS-style `truthy` projection rules
* deterministic output requirements
* optional RDF exposure of Kristal validation, certainty, authority, and reader-policy metadata

Out of scope:

* RDF dataset hashing / canonicalization, handled by the optional **RDF Integrity (RDFC)** profile
* live SPARQL service behavior
* full WDQS feature parity
* validation decisions themselves
* authority recognition decisions themselves
* reader-policy enforcement beyond export selection and manifest declaration

Kristal Runtime Packs remain offline-capable and constrained. This profile defines an export compatibility format, not a hosted WDQS clone.

## Terminology

* **Item**: Wikibase-style entity with a QID, such as `Q123`.
* **Property**: Wikibase-style property with a PID, such as `P123`.
* **Statement**: an assertion about an item using a property and a value, with optional qualifiers, references, rank, validation metadata, certainty metadata, and authority metadata.
* **Qualifier**: additional information attached to a statement.
* **Reference**: provenance or evidence attached to a statement.
* **Rank**: Wikibase-style rank value used for projection behavior: `preferred`, `normal`, or `deprecated`.
* **Truthy projection**: a WDQS-compatible technical projection selecting best-ranked statements for a given `(subject, property)`. In this profile, `truthy` is a compatibility term and does not mean universal truth.
* **Validation status**: Kristal status describing whether a statement or artifact is not evaluated, in review, validated, conditionally validated, disputed, rejected, or revoked.
* **Certainty level**: Kristal metadata describing how strong a statement is within its declared scope.
* **Authority channel**: a scoped authority that may recognize, validate, reject, or classify artifacts or assertions.
* **Reader policy**: a policy selecting which validation statuses, certainty levels, authority channels, and scopes are visible to a reader or consuming system.

Normative keywords: MUST, SHOULD, MAY.

## Inputs

The input to this profile is a Kristal v5 artifact or selected subset of artifacts.

Supported inputs:

* `working_exchange`
* `reference_exchange`
* exchange shards referenced by an `exchange_federation_manifest`
* selected assertions from a Structured Epistemic State, if the export pipeline supports direct state export

The export configuration MUST select:

```json
{
  "export_profile": "rdf-wdqs",
  "export_profile_version": "5.0",
  "projection": "full",
  "reader_policy_ref": null
}
```

Allowed projection values:

```text
full
truthy
```

Optional export configuration MAY include:

* language preferences for labels
* namespace mode
* statement node identity mode
* authority channels to include
* validation statuses to include
* certainty levels to include
* whether to include disputed statements
* whether to include fictional or mythological corpora
* whether to emit Kristal metadata graphs

Labels are optional in RDF export unless explicitly enabled.

## Outputs

The output is a deterministic RDF dataset serialized as N-Quads or Turtle.

Recommended primary serialization:

```text
export.rdf.nq
```

Required output artifacts:

```text
export.rdf.nq
export.manifest.json
```

Allowed alternative serialization:

```text
export.rdf.ttl
```

Turtle is allowed only when the exporter defines additional determinism constraints for prefix ordering, subject ordering, predicate ordering, object ordering, blank node handling, and serializer configuration.

The export manifest MUST record:

* profile id
* profile version
* projection
* source artifact refs
* reader policy refs, if any
* authority registry ref, if any
* namespace choices
* statement node identity scheme
* rank representation mode
* validation / certainty metadata export mode
* sorting and serialization parameters
* deterministic export normalization parameters

## Dataset Structure

### Required graphs

The export MUST be an RDF dataset with at least the following named graphs.

#### 1. Assertion graph

Required.

Contains:

* item-to-value triples
* item-to-statement-node triples
* statement node triples
* qualifiers
* rank representation
* statement-level metadata required by the selected export mode

#### 2. Reference graph

Required if references exist.

Contains:

* reference nodes
* reference details
* deterministic links from statement nodes to reference nodes

If references are present in the source data, a reference graph MUST be emitted.

#### 3. Metadata graph

Optional.

Contains:

* export metadata
* build id
* source artifact refs
* profile selection
* projection mode
* reader policy refs
* authority registry refs
* timestamps

The metadata graph MUST NOT affect the Kristal core content hash unless an integrity profile explicitly declares that it is part of the RDF hash target.

### Optional graphs

#### 4. Validation graph

Optional but RECOMMENDED when validation metadata exists.

Contains:

* validation status
* validated-as classification
* validation decision refs
* validation policy refs
* authority channel refs
* validation scope

#### 5. Certainty graph

Optional but RECOMMENDED when certainty metadata exists.

Contains:

* certainty level
* confidence summaries, if present
* scope-specific certainty metadata

#### 6. Authority graph

Optional but RECOMMENDED when authority recognition metadata exists.

Contains:

* authority channel refs
* authority recognition refs
* recognition status
* recognized-as classification
* authority scope

#### 7. Reader policy graph

Optional.

Contains:

* reader policy refs
* active reader mode
* allowed validation statuses
* allowed certainty levels
* allowed authority channels
* inclusion flags for disputed, fictional, or mythological material

## URI Policy

The export MUST define deterministic URI construction for:

* items
* properties
* statement nodes
* reference nodes
* value nodes, where needed
* validation decision nodes, if exported
* authority recognition nodes, if exported
* reader policy nodes, if exported

### Recommended URI scheme

Wikibase-aligned prefixes SHOULD be used where compatibility is desired:

```text
wd:   items
wdt:  direct properties
p:    statement properties
ps:   statement value properties
pq:   qualifier properties
pr:   reference properties
prov: provenance linkage
rdf:  RDF core predicates
xsd:  XML Schema datatypes
```

An implementation MAY use standard Wikidata namespace forms, but MUST be consistent and deterministic.

Kristal-specific metadata SHOULD use a declared namespace such as:

```text
kri:  Kristal artifact, validation, certainty, authority, and reader-policy terms
```

The exact namespace bindings MUST be recorded in `export.manifest.json`.

## Statement Node Identity

Each exported statement MUST have a stable identifier across runs given identical inputs.

Requirement:

* If the source provides a stable `assertion_id`, the statement node SHOULD be derived from it.
* If the source provides a stable Wikibase statement id, the statement node MAY be derived from it.
* If neither is available, the statement node MUST be derived from a deterministic hash of:

  * subject QID
  * predicate PID
  * normalized object value
  * normalized qualifiers, sorted deterministically
  * normalized references, sorted deterministically when included in identity mode
  * and an optional disambiguator when multiple identical statements exist.

The exact construction MUST be documented and recorded in the export manifest.

Recommended form:

```text
kri:statement/sha256:<hex>
```

or, for Wikibase-compatible exports:

```text
wds:<stable-statement-id>
```

Blank nodes SHOULD be avoided. If blank nodes are used, they MUST be deterministically skolemized.

## Statement Modeling

### Full projection

When:

```json
{
  "projection": "full"
}
```

the export MUST emit all selected statements according to the active export configuration and reader policy.

The full projection MUST emit:

* direct-value triples using `wdt:Pxx`, when compatible with the value type
* statement-node triples using `p:Pxx`
* statement-value triples using `ps:Pxx`
* qualifier triples using `pq:Pxx`
* reference linkage using `prov:wasDerivedFrom` or Wikibase-style reference linkage
* rank representation
* all selected references
* all selected qualifiers

If validation, certainty, authority, or reader-policy metadata is included, the export SHOULD emit it in separate metadata graphs rather than mixing it into the assertion graph.

### Truthy projection

When:

```json
{
  "projection": "truthy"
}
```

the export MUST emit only best-ranked statements per `(subject, property)` according to the rank rules below.

--- CHUNK END ---

--- CHUNK BEGIN ---
id=af7ce63c7144:351-700
start=351
end=700
----
Rules:

* If preferred-rank statements exist for a given `(subject, property)`, only preferred statements are emitted.
* Else, normal-rank statements are emitted.
* Deprecated statements MUST NOT be emitted in truthy projection.
* If multiple statements share the best rank, all best-ranked statements MUST be emitted.
* The truthy projection MUST be deterministic given identical inputs.

The `truthy` projection is a WDQS compatibility projection. It MUST NOT be described as universal truth. It is only a rank-based selection of statements under the selected input, reader policy, and export configuration.

## Rank Rules

Kristal v5 WDQS export MUST support at least the following ranks:

```text
preferred
normal
deprecated
```

Rank MUST be represented deterministically.

Acceptable methods include:

* Wikibase-style rank predicates
* explicit rank triples using a dedicated Kristal or export-profile predicate

The method MUST be stated in the export manifest.

Recommended representation:

```text
wikibase:rank wikibase:PreferredRank
wikibase:rank wikibase:NormalRank
wikibase:rank wikibase:DeprecatedRank
```

## Value Modeling

Object values MUST be serialized in a way compatible with WDQS expectations.

### Item values

Item values SHOULD be serialized as item IRIs:

```text
wd:Q123
```

### String values

Plain strings MUST be RDF literals.

Language tags MUST only be used where the value is explicitly monolingual or language-scoped.

### Monolingual text

Monolingual text MUST be serialized as an RDF literal with a language tag.

### Time values

Time values SHOULD use:

```text
xsd:date
xsd:dateTime
```

Precision handling MUST be documented.

If the source provides lower precision than the RDF datatype can express directly, the exporter MUST either:

* preserve precision metadata using an additional predicate, or
* document the precision normalization in the export manifest.

### Quantity values

Quantities SHOULD be serialized as numeric literals.

Unit modeling MUST be documented.

If the unit is known, the exporter SHOULD emit a unit IRI or unit predicate.

### Coordinates

Coordinates MAY be serialized using:

* WKT literals, or
* dedicated latitude / longitude predicates.

The selected method MUST be documented.

### URLs

URLs SHOULD be serialized as IRIs.

### External identifiers

External identifiers SHOULD be serialized as literals unless a profile declares a deterministic IRI expansion rule.

## Value Normalization

Values MUST use Kristal-normalized forms from the source artifact where available.

If the export performs additional normalization, that normalization:

* MUST be deterministic,
* MUST be documented,
* MUST be recorded in the export manifest.

Normalization MUST NOT silently erase validation status, certainty level, authority scope, or reference metadata.

## Qualifiers

Qualifiers MUST be emitted as triples attached to the statement node.

Qualifier ordering in serialized output MUST be deterministic.

If a statement has multiple qualifiers for the same property, all MUST be emitted unless the selected reader policy or export configuration excludes them.

## References

References MUST be emitted as reference nodes.

Statement nodes MUST link to reference nodes deterministically.

If a statement has multiple references, all selected references MUST be emitted.

Reference node identity MUST be stable across runs given identical inputs.

Recommended reference node identity:

```text
kri:reference/sha256:<hex>
```

The hash target SHOULD include:

* normalized reference claims
* normalized source identifiers
* normalized evidence refs
* deterministic ordering of reference components

The exact construction MUST be documented and recorded in the export manifest.

## Validation, Certainty, and Authority Metadata

Kristal v5 separates:

* artifact identity,
* statement identity,
* assertion status,
* certainty level,
* validation status,
* authority recognition,
* and reader visibility.

This profile MAY expose that metadata in RDF.

If exported, the metadata MUST remain scoped. An assertion MUST NOT be represented as generally validated without also exposing the authority channel, validation policy, and scope that support that status.

### Assertion status

Allowed assertion status values:

```text
hypothesis
claimed
sourced
disputed
reviewed
validated
rejected
retracted
superseded
```

### Validation status

Allowed validation status values:

```text
not_evaluated
in_review
validated
conditionally_validated
disputed
rejected
revoked
```

### Certainty level

Allowed certainty level values:

```text
unknown
speculative
low
medium
high
established
not_applicable
```

### Validated-as values

Allowed validated-as values:

```text
hypothesis
claim
sourced_claim
reviewed_claim
high_confidence_fact
institutional_reference
publisher_declaration
technical_specification
legal_or_policy_position
mythological_corpus
fictional_corpus
symbolic_model
disputed_position
rejected_claim
```

### Authority metadata

If authority metadata is exported, it SHOULD include:

* authority channel id,
* recognition status,
* recognized-as value,
* validation policy ref,
* recognition scope,
* evidence refs where available.

Recognition by one authority channel MUST NOT imply recognition by another authority channel.

## Reader Policy Interaction

The exporter MAY accept a reader policy that filters which statements are exported.

Reader policy may select:

* authority channels,
* validation statuses,
* certainty levels,
* validated-as values,
* domains,
* subdomains,
* whether disputed statements are included,
* whether fictional corpora are included,
* whether mythological corpora are included.

If a reader policy is used, the export manifest MUST record:

* reader policy id,
* reader mode,
* included authority channels,
* included validation statuses,
* included certainty levels,
* included validated-as values,
* inclusion flags for disputed, fictional, and mythological material.

Allowed reader modes:

```text
reference_only
validated_only
high_certainty_only
research
creative
all_with_labels
custom
```

“Validated-only” means all visible statements satisfy the active reader policy. It does not mean all statements have maximum certainty or universal agreement.

## Determinism Requirements

The export MUST be byte-stable given identical inputs and the same profile settings.

Minimum requirements:

1. Use deterministic serializer configuration.
2. Prefer N-Quads for primary export.
3. Sort output N-Quads lexicographically by:

   1. graph IRI
   2. subject
   3. predicate
   4. object
4. Avoid blank nodes where possible.
5. If blank nodes are used, deterministically skolemize them.
6. Ensure deterministic namespace selection.
7. Ensure deterministic statement node identity.
8. Ensure deterministic reference node identity.
9. Ensure deterministic ordering of repeated qualifiers.
10. Ensure deterministic ordering of repeated references.
11. Ensure deterministic handling of language labels.
12. Ensure deterministic handling of rank projection.

The export manifest MUST record:

* profile id and version,
* projection,
* namespace choices,
* statement node identity scheme,
* reference node identity scheme,
* sorting parameters,
* serialization parameters,
* reader policy, if any,
* validation metadata export mode,
* authority metadata export mode,
* certainty metadata export mode.

## Export Manifest

The export manifest MUST be JSON.

Minimum shape:

```json
{
  "schema_version": "5.0",
  "artifact_type": "rdf_wdqs_export_manifest",
  "export_profile": "rdf-wdqs",
  "export_profile_version": "5.0",
  "created_at": "2026-01-01T00:00:00Z",
  "source_artifacts": [],
  "projection": "full",
  "serialization": {
    "format": "application/n-quads",
    "file": "export.rdf.nq",
    "sort_order": [
      "graph",
      "subject",
      "predicate",
      "object"
    ],
    "blank_node_policy": "avoid"
  },
  "namespaces": {},
  "statement_node_identity": {
    "mode": "assertion_id",
    "fallback": "deterministic_hash"
  },
  "reference_node_identity": {
    "mode": "deterministic_hash"
--- CHUNK END ---

--- CHUNK BEGIN ---
id=af7ce63c7144:701-808
start=701
end=808
----
  },
  "rank_representation": {
    "mode": "wikibase_rank_predicates"
  },
  "reader_policy_ref": null,
  "authority_registry_ref": null,
  "metadata_graphs": {
    "validation": false,
    "certainty": false,
    "authority": false,
    "reader_policy": false
  }
}
```

Implementations MAY extend this manifest, but extensions MUST NOT change core export semantics without declaring a distinct profile or profile version.

## Conformance

An export is conformant to this profile if:

* it emits the required graphs for the selected projection,
* it follows deterministic URI and statement identity rules,
* it models statements, qualifiers, references, and ranks according to this profile,
* it preserves selected references and qualifiers,
* it is byte-stable under repeated builds,
* it records all required export parameters in the manifest,
* it does not represent scoped validation as universal validation,
* and it does not erase authority, certainty, or reader-policy distinctions when those distinctions are part of the selected export.

## Recommended Tests

Implementations SHOULD provide tests for:

### Fixture output

A fixture dataset with known expected N-Quads output.

### Determinism

Same inputs and same settings MUST produce identical bytes across runs.

### Rank / truthy projection

Tests SHOULD verify:

* preferred overrides normal,
* normal is used when preferred is absent,
* deprecated is excluded from truthy projection,
* multiple best-ranked statements are retained.

### Multi-reference stability

Tests SHOULD verify stable ordering and stable identity for multiple references.

### Qualifier stability

Tests SHOULD verify stable ordering and stable identity behavior when qualifiers repeat or overlap.

### Metadata graph separation

Tests SHOULD verify that metadata graph inclusion does not affect Kristal core content hash unless an integrity profile explicitly declares it.

### Reader policy filtering

Tests SHOULD verify that selected reader policies include and exclude statements deterministically.

### Authority-scoped validation

Tests SHOULD verify that validation metadata remains attached to its authority channel, validation policy, and scope.

## Interactions with Other Profiles

### RDF Integrity (RDFC)

The **RDF Integrity (RDFC)** profile may consume the deterministic RDF dataset emitted by this profile and compute RDF hashes or integrity proofs.

This WDQS export profile defines export shape and determinism. RDFC defines RDF canonicalization and integrity.

### Provenance Nanopub + PROV-O

The **Provenance Nanopub + PROV-O** profile may reuse the same statement and reference nodes.

Packaging remains separate from this WDQS export profile unless an implementation declares a combined profile.

### Query TPF Pagination

The **Query TPF Pagination** profile may expose exported RDF through constrained offline or local query surfaces.

This profile does not require a live SPARQL endpoint.

### Reader Policy Profile

The **Reader Policy** profile may define which authority channels, certainty levels, validation statuses, and validated-as values are included in the export.

When a reader policy is applied, it MUST be recorded in the export manifest.

### Authority Recognition Profile

The **Authority Recognition** profile may define the authority recognition records referenced or exported by this profile.

Recognition metadata MUST remain scoped.

## Notes

This profile preserves WDQS compatibility where useful, but Kristal v5 does not collapse knowledge into a single global truth layer.

The RDF export is a deterministic projection of selected Kristal artifacts under explicit profile settings. The meaning of “validated,” “recognized,” “reference,” or “truthy” depends on declared authority channels, validation policies, scopes, certainty levels, and reader policy.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-transparency-log.md"
id=9dc7e7feaf59
kind=markdown
size=23955
lines=880
line_ref=1-880
chunks=3
chunk_refs=1-350,351-700,701-880
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=9dc7e7feaf59:1-350
start=1
end=350
----
# Profile: Transparency Log (Kristal v5)

## Status

Optional standardized profile — Kristal v5.

## Purpose

This profile defines a transparency log pattern for Kristal v5 artifacts, validation decisions, authority recognitions, revocations, Runtime Pack releases, and trust-root changes.

A transparency log provides an append-oriented audit surface that makes it possible to inspect:

* what was published;
* who signed or recognized it;
* under which authority channel;
* under which scope;
* under which validation or recognition policy;
* when it was recorded;
* whether it was later superseded, revoked, disputed, or deprecated.

This profile does **not** create a universal truth authority.

A transparency log records events and signed statements. It does not, by itself, prove that every logged assertion is true, high-certainty, globally recognized, or visible under every reader policy.

---

## Scope

This profile specifies:

* transparency log entry structure;
* event types;
* append-only sequencing;
* hash-chain requirements;
* signature requirements;
* authority-channel linkage;
* validation and recognition event linkage;
* revocation and correction linkage;
* Runtime Pack release linkage;
* query and audit expectations;
* offline verification expectations.

This profile does not specify:

* a single network transport;
* a required storage backend;
* a global log operator;
* governance rules for every authority channel;
* semantic validation of claims;
* reader-policy inclusion rules.

---

## Normative keywords

The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as normative requirements.

---

# 1. Conformance

An implementation claims this profile by declaring the following profile identifier:

```text
kristal.v5:profile-transparency-log@1
```

A conformant transparency log MUST provide:

* append-oriented log entries;
* stable entry identifiers;
* deterministic entry hashing;
* monotonic sequence numbers within a log;
* previous-entry linkage;
* signed log checkpoints or signed entries;
* event type classification;
* target artifact references;
* authority-channel references when applicable;
* scope references when applicable;
* revocation or supersession linkage when applicable.

A Runtime Pack, Authority Registry, Exchange, Federation Manifest, Validation Decision, or Authority Recognition MAY reference one or more transparency logs.

---

# 2. Conceptual model

A transparency log records claims about artifact events.

Examples:

```text
artifact X was published
artifact X was signed by key Y
artifact X was recognized by authority channel Z
assertion A was validated as a hypothesis
runtime pack P was released to channel C
key K was revoked
authority channel Y delegated scope S to authority channel Z
```

A transparency log entry is not the same thing as the target artifact.

A transparency log entry records an event about a target.

The target remains governed by its own schema, signatures, content hash, authority channel, validation status, certainty level, and reader policy.

---

# 3. Design goals

Transparency logs in Kristal v5 support:

* auditability;
* compromise detection;
* release traceability;
* validation traceability;
* authority-recognition traceability;
* offline verification;
* public accountability where desired;
* correction and revocation visibility;
* federation without hidden authority laundering.

Transparency logs SHOULD make it difficult to silently rewrite the history of published artifacts, recognition decisions, revocations, or releases.

---

# 4. Log identity

A transparency log MUST have a stable `log_id`.

Recommended shape:

```json
{
  "log_id": "kristal:transparency-log:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "schema_version": "5.0",
  "profile": "kristal.v5:profile-transparency-log@1"
}
```

A log SHOULD declare:

* operator identity;
* authority channel, if operated by an authority;
* scope;
* trust roots;
* signing policy;
* retention policy;
* public or private visibility status;
* checkpoint policy.

---

# 5. Entry identity

Each transparency log entry MUST have a stable `entry_id`.

Recommended shape:

```text
sha256:<64 lowercase hex characters>
```

The `entry_id` MUST be derived from the canonicalized log entry hash target.

The entry hash target MUST exclude signatures.

The entry hash target SHOULD exclude `entry_id` itself.

Hashing MUST use:

```text
canonicalization_profile = "kristal.v5:jcs-rfc8785"
canonicalization_version = "1"
hash_alg = "sha256"
```

---

# 6. Entry structure

A conformant transparency log entry SHOULD use the following structure:

```json
{
  "schema_version": "5.0",
  "artifact_type": "transparency_log_entry",
  "profile": "kristal.v5:profile-transparency-log@1",
  "log_id": "kristal:transparency-log:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "entry_id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "sequence": 1,
  "created_at": "2026-01-01T00:00:00Z",
  "event_type": "artifact_published",
  "target_ref": {
    "artifact_type": "reference_exchange",
    "artifact_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
    "content_hash": {
      "alg": "sha256",
      "value": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
    }
  },
  "target_level": "artifact",
  "issuer": {
    "authority_channel_id": "authority:example",
    "key_id": "key:example"
  },
  "scope": {
    "domain": "science"
  },
  "policy_refs": [],
  "previous_entry_id": null,
  "entry_hash": {
    "alg": "sha256",
    "value": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
  },
  "signatures": [],
  "extensions": {}
}
```

---

# 7. Required entry fields

A transparency log entry MUST include:

* `schema_version`;
* `artifact_type`;
* `profile`;
* `log_id`;
* `entry_id`;
* `sequence`;
* `created_at`;
* `event_type`;
* `target_ref`;
* `target_level`;
* `entry_hash`.

It SHOULD include:

* `issuer`;
* `scope`;
* `policy_refs`;
* `previous_entry_id`;
* `signatures`.

If the event involves validation, recognition, authority, release, revocation, or delegation, the entry MUST include enough references to identify the relevant authority channel and policy.

---

# 8. Event types

Allowed `event_type` values SHOULD include:

```text
artifact_submitted
artifact_compiled
artifact_published
artifact_deprecated
artifact_superseded
artifact_revoked
validation_decision_recorded
validation_decision_revoked
authority_recognition_recorded
authority_recognition_revoked
authority_channel_registered
authority_channel_deprecated
authority_channel_revoked
authority_delegation_recorded
authority_delegation_revoked
runtime_pack_built
runtime_pack_released
runtime_pack_activated
runtime_pack_revoked
reader_policy_registered
reader_policy_deprecated
trust_root_added
trust_root_deprecated
trust_root_blocked
revocation_list_published
federation_manifest_published
correction_recorded
dispute_recorded
checkpoint_published
```

Implementations MAY define additional event types through profile extensions.

Extension event types MUST be namespaced or otherwise clearly distinguishable from core event types.

---

# 9. Target levels

Allowed `target_level` values SHOULD include:

```text
artifact
shard
assertion
authority_channel
dataset
runtime_pack
validation_decision
authority_recognition
reader_policy
trust_root
revocation_list
federation_manifest
release
checkpoint
```

Rules:

* `target_level = assertion` MUST include a target reference to the assertion ID or containing artifact and assertion path.
* `target_level = runtime_pack` MUST include the Runtime Pack ID.
* `target_level = authority_channel` MUST include the authority channel ID.
* `target_level = validation_decision` MUST include the validation decision ID.
* `target_level = authority_recognition` MUST include the recognition ID.

---

# 10. Append-only sequencing

Within a log, entries MUST have monotonic sequence numbers.

Sequence numbers MUST NOT be reused.

If an entry is invalid, corrected, superseded, or revoked, the log MUST NOT mutate or delete the prior entry. It SHOULD append a new entry recording the correction, supersession, or revocation.

A transparency log MAY be segmented into epochs, shards, or checkpoints. If segmented, the segment identity and ordering rules MUST be declared.

---

# 11. Hash-chain linkage

A transparency log SHOULD provide hash-chain linkage.

Each entry SHOULD include:

```json
{
  "previous_entry_id": "sha256:<previous-entry-id-or-null>"
}
```

The first entry in a log or segment SHOULD use:

--- CHUNK END ---

--- CHUNK BEGIN ---
id=9dc7e7feaf59:351-700
start=351
end=700
----
```json
{
  "previous_entry_id": null
}
```

If the log is sharded or checkpointed, each shard or checkpoint MUST declare how previous-entry linkage is preserved or summarized.

Implementations SHOULD provide a way to verify that no entries are missing between two known sequence numbers or checkpoints.

---

# 12. Checkpoints

A transparency log MAY publish checkpoints.

A checkpoint summarizes a known log state.

Recommended checkpoint structure:

```json
{
  "schema_version": "5.0",
  "artifact_type": "transparency_log_checkpoint",
  "profile": "kristal.v5:profile-transparency-log@1",
  "log_id": "kristal:transparency-log:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "checkpoint_id": "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
  "created_at": "2026-01-01T00:00:00Z",
  "sequence_min": 1,
  "sequence_max": 1000,
  "entry_count": 1000,
  "root_hash": {
    "alg": "sha256",
    "value": "1111111111111111111111111111111111111111111111111111111111111111"
  },
  "previous_checkpoint_id": null,
  "signatures": []
}
```

A checkpoint SHOULD be signed.

A checkpoint MAY use:

* linear hash-chain root;
* Merkle root;
* shard root;
* implementation-specific accumulator root.

The accumulator method MUST be declared.

---

# 13. Signatures

A transparency log MAY sign each entry individually.

A transparency log SHOULD sign checkpoints.

A transparency log operated by an authority channel MUST declare the signing authority or signing policy.

Signatures MUST use the common Kristal v5 signature semantics:

```json
{
  "key_id": "key:example",
  "alg": "ed25519",
  "payload_hash": {
    "alg": "sha256",
    "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "signature": "base64url-or-multibase-signature",
  "created_at": "2026-01-01T00:00:00Z"
}
```

A signature over a log entry proves that the signer signed that log entry.

It does not prove that the target artifact is universally true, globally validated, or recognized by every authority channel.

---

# 14. Authority-channel linkage

If a log entry records an authority action, it MUST identify the authority channel.

Examples of authority actions include:

* validation decision recorded;
* authority recognition recorded;
* authority delegation recorded;
* trust root added;
* revocation list published;
* reference artifact accepted;
* runtime pack released by authority channel.

Recommended shape:

```json
{
  "issuer": {
    "authority_channel_id": "authority:example",
    "key_id": "key:example"
  }
}
```

Recognition by one authority channel MUST NOT be represented as recognition by another authority channel unless the second authority explicitly records or delegates that recognition.

---

# 15. Validation decision linkage

A `validation_decision_recorded` event SHOULD reference a Validation Decision artifact.

Recommended target:

```json
{
  "event_type": "validation_decision_recorded",
  "target_level": "validation_decision",
  "target_ref": {
    "validation_decision_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "target_ref": {
      "artifact_id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    }
  }
}
```

The log entry SHOULD preserve or reference:

* validation status;
* `validated_as`;
* certainty level;
* authority channel;
* validation policy;
* scope;
* target level.

A transparency log MUST NOT flatten scoped validation into universal truth.

---

# 16. Authority recognition linkage

An `authority_recognition_recorded` event SHOULD reference an Authority Recognition artifact.

The log entry SHOULD preserve or reference:

* issuer authority channel;
* target reference;
* target level;
* recognition status;
* recognized-as status;
* scope;
* policy references;
* evidence references.

Recognition MUST remain scoped.

Recognition by one authority channel MUST NOT imply recognition by another.

---

# 17. Runtime Pack release linkage

A `runtime_pack_released` event SHOULD reference:

* Runtime Pack ID;
* Runtime Pack manifest hash;
* source Exchange reference;
* source artifact status;
* release channel;
* pack version;
* reader policy references;
* authority registry reference;
* release record reference;
* signer key ID;
* timestamp.

Recommended shape:

```json
{
  "event_type": "runtime_pack_released",
  "target_level": "runtime_pack",
  "target_ref": {
    "runtime_pack_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "source_exchange_ref": {
      "artifact_id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    },
    "source_artifact_status": "reference",
    "pack_version": "5.0.0"
  },
  "release": {
    "channel_id": "channel:prod",
    "reader_policy_refs": ["reader_policy:validated-only"],
    "authority_registry_ref": {
      "registry_id": "kristal:authority-registry:sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
    }
  }
}
```

A Runtime Pack release entry MUST NOT imply that the pack is valid for every channel or reader policy.

---

# 18. Revocation linkage

A revocation event SHOULD identify:

* revoked target;
* revocation issuer;
* effective timestamp;
* revocation reason;
* affected authority channel;
* affected scope;
* policy reference;
* replacement target, if any.

Recommended reason codes:

```text
key_compromise
artifact_corruption
manifest_invalid
payload_hash_mismatch
signature_invalid
authority_channel_revoked
validation_decision_revoked
recognition_revoked
policy_withdrawn
scope_error
publisher_error
evidence_retracted
superseded_by_replacement
```

Revocation does not necessarily delete historical records.

It changes current trust, recognition, validation, release, or activation status under a declared policy.

---

# 19. Corrections and disputes

A correction event records that a previous artifact, decision, entry, or assertion has been corrected.

A dispute event records that an authority channel, reviewer, user group, or process contests a prior assertion, validation decision, recognition, or publication.

Correction and dispute entries SHOULD include:

* target reference;
* prior entry reference;
* issuer;
* reason;
* scope;
* policy reference;
* replacement reference, if any.

A dispute entry does not automatically revoke the target. It records contestation.

Reader policies decide how disputes affect visibility.

---

# 20. Offline verification

A transparency log SHOULD support offline verification.

Offline verification may use:

* signed checkpoints;
* bundled log entry ranges;
* Merkle proofs;
* hash-chain proofs;
* signed release bundles;
* Authority Registry references.

A Runtime Pack MAY include a transparency log subset sufficient to verify its release history, validation decisions, recognition decisions, or revocation status.

If an active policy requires transparency-log verification and the required log data is unavailable, the implementation MUST NOT represent the target as accepted under that policy.

It MAY still expose the target as unavailable, unverified, diagnostic, or untrusted material depending on reader policy.

---

# 21. Query expectations

A transparency log SHOULD be queryable by:

* `log_id`;
* `entry_id`;
* `sequence`;
* `event_type`;
* `target_level`;
* `target_ref`;
* `authority_channel_id`;
* `scope.domain`;
* `validation_status`;
* `recognition_status`;
* `runtime_pack_id`;
* `release channel`;
* `created_at`;
* `revocation reason`.

Query responses MUST preserve authority, scope, and status labels when those labels exist.

A query response MUST NOT imply universal truth from log presence alone.

---

# 22. Privacy and access control

Transparency logs may be public, private, tenant-scoped, authority-scoped, or deployment-scoped.

A private or restricted transparency log SHOULD still provide auditability to authorized verifiers.

If logs contain sensitive metadata, implementations SHOULD minimize exposure while preserving verifiability.

Possible strategies include:

* redacted entries;
* hashed target references;
* scoped access;
* encrypted payloads with public hashes;
* split public/private logs;
* aggregate checkpoints.

Privacy controls MUST NOT allow silent mutation of already-audited public claims.

---

# 23. Retention

Transparency log retention policy SHOULD be explicit.

Retention policy SHOULD declare:

* how long entries are retained;
* whether old checkpoints remain available;
* whether old entries may be archived;
* how archived entries are verified;
* whether revocation and correction entries remain available indefinitely.

If entries are removed from online service but remain part of a signed historical checkpoint, the system SHOULD provide a way to distinguish:

* missing data;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=9dc7e7feaf59:701-880
start=701
end=880
----
* archived data;
* intentionally redacted data;
* unavailable data;
* invalid data.

---

# 24. Federation

A federation may reference multiple transparency logs.

Federated logs MUST preserve:

* log identity;
* authority-channel boundaries;
* target references;
* event scope;
* event status;
* sequence or checkpoint verification.

Federation MUST NOT silently merge events from different authority channels as though they were issued by one authority.

If two transparency logs disagree, the federation layer SHOULD preserve the disagreement or apply an explicit composition policy.

---

# 25. Example: Authority recognition entry

```json
{
  "schema_version": "5.0",
  "artifact_type": "transparency_log_entry",
  "profile": "kristal.v5:profile-transparency-log@1",
  "log_id": "kristal:transparency-log:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "entry_id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "sequence": 42,
  "created_at": "2026-01-01T00:00:00Z",
  "event_type": "authority_recognition_recorded",
  "target_level": "authority_recognition",
  "target_ref": {
    "recognition_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
    "target_ref": {
      "artifact_id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
    }
  },
  "issuer": {
    "authority_channel_id": "authority:unesco-global-reference",
    "key_id": "key:unesco-example"
  },
  "scope": {
    "domain": "education",
    "jurisdiction": "global"
  },
  "policy_refs": [
    {
      "policy_id": "kristal.v5:recognition-policy:global-education-reference"
    }
  ],
  "previous_entry_id": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "entry_hash": {
    "alg": "sha256",
    "value": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
  },
  "signatures": [
    {
      "key_id": "key:unesco-example",
      "alg": "ed25519",
      "payload_hash": {
        "alg": "sha256",
        "value": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
      },
      "signature": "base64url-or-multibase-signature",
      "created_at": "2026-01-01T00:00:01Z"
    }
  ],
  "extensions": {}
}
```

---

# 26. Example: Runtime Pack release entry

```json
{
  "schema_version": "5.0",
  "artifact_type": "transparency_log_entry",
  "profile": "kristal.v5:profile-transparency-log@1",
  "log_id": "kristal:transparency-log:sha256:1111111111111111111111111111111111111111111111111111111111111111",
  "entry_id": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
  "sequence": 87,
  "created_at": "2026-01-01T00:00:00Z",
  "event_type": "runtime_pack_released",
  "target_level": "runtime_pack",
  "target_ref": {
    "runtime_pack_id": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
    "source_exchange_ref": {
      "artifact_id": "sha256:4444444444444444444444444444444444444444444444444444444444444444"
    },
    "source_artifact_status": "reference",
    "pack_version": "5.0.0"
  },
  "issuer": {
    "authority_channel_id": "authority:wikidata-seed",
    "key_id": "key:wikidata-seed-release"
  },
  "scope": {
    "domain": "wikidata"
  },
  "release": {
    "channel_id": "channel:public-reference",
    "reader_policy_refs": ["reader_policy:validated-only"],
    "authority_registry_ref": {
      "registry_id": "kristal:authority-registry:sha256:5555555555555555555555555555555555555555555555555555555555555555"
    }
  },
  "previous_entry_id": "sha256:6666666666666666666666666666666666666666666666666666666666666666",
  "entry_hash": {
    "alg": "sha256",
    "value": "7777777777777777777777777777777777777777777777777777777777777777"
  },
  "signatures": [
    {
      "key_id": "key:wikidata-seed-release",
      "alg": "ed25519",
      "payload_hash": {
        "alg": "sha256",
        "value": "7777777777777777777777777777777777777777777777777777777777777777"
      },
      "signature": "base64url-or-multibase-signature",
      "created_at": "2026-01-01T00:00:01Z"
    }
  ],
  "extensions": {}
}
```

---

# 27. Nonconformance

A transparency log implementation is nonconforming if it:

* mutates previous entries without preserving an audit trail;
* reuses sequence numbers;
* omits target references;
* omits authority channel references for authority events;
* represents log inclusion as universal truth;
* represents one authority’s recognition as another’s recognition;
* hides revocation or correction events required by active policy;
* uses ambiguous signing targets;
* includes signatures in entry hashes without a declared profile;
* fails to preserve scope;
* fails to distinguish validation from recognition;
* fails to distinguish certainty from validation.

---

# 28. Summary

A Kristal v5 transparency log records auditable events about artifacts, validation decisions, authority recognitions, revocations, releases, trust roots, and corrections.

It does not create a universal truth layer.

The core rules are:

```text
Log entries are append-oriented.
Entry identity is content-addressed.
Checkpoints should be signed.
Authority is scoped.
Recognition is scoped.
Validation is scoped.
Revocation changes current trust status.
Corrections do not erase history.
Reader policies decide visibility.
Log inclusion does not equal truth.
```

Transparency logs make Kristal ecosystems more inspectable, accountable, and resilient without collapsing plural authority into a single truth monopoly.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-validation-shacl.md"
id=770dbd1a7a70
kind=markdown
size=15898
lines=462
line_ref=1-462
chunks=2
chunk_refs=1-350,351-462
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=770dbd1a7a70:1-350
start=1
end=350
----
# Profile: Validation Reporting (SHACL)

## Status

Draft (Kristal v5 optional standardized profile)

## Purpose

Provide an interoperable **SHACL-based conformance report** for Kristal artifacts that:

* is **machine-consumable**,
* maps cleanly to Kristal **Validation Report** issue codes and severity levels,
* can be used in CI/CD as an optional validation output,
* can support review, validation decisions, authority recognition, and reader policy evaluation without becoming a default global gate.

This profile is **optional** and does not change core Kristal identity, content addressing, hashing, or artifact status by itself.

## Profile identifier

* `profile_id`: `validation-shacl`
* `profile_version`: `1.0`
* `spec_version`: `5.0`

## Scope

This profile defines:

* required outputs: SHACL shapes graph and SHACL validation report graph;
* minimum mapping rules from SHACL results to Kristal Validation Report issues;
* deterministic reporting requirements;
* linkage requirements between SHACL reports, Kristal artifacts, build records, validation decisions, and authority recognition records where applicable;
* extension predicates that improve interoperability between SHACL outputs and Kristal issue locations.

Non-scope:

* choosing a specific SHACL engine implementation;
* mandating RDF export integrity hashing, which is handled by the RDF integrity / RDFC profile;
* embedding workflow, review, approval, or authority-recognition processes directly into Exchange or Runtime Pack schemas;
* making SHACL validation a default compilation, publication, recognition, or activation gate.

## Inputs

A SHACL validation profile implementation may consume one or more of:

* a Kristal `working_exchange`;
* a Kristal `reference_exchange`;
* an Exchange shard;
* a Runtime Pack manifest;
* a Structured Epistemic State;
* a derived RDF projection suitable for SHACL checking;
* an existing Kristal Validation Report;
* a validation decision target;
* an authority recognition target.

If Claim-IR or Resolved Claim-IR artifacts are used, they are treated as extractor or resolution profile inputs, not as universal Kristal v5 input requirements.

## Outputs

When enabled, an implementation MUST produce:

1. a SHACL shapes graph, or a stable reference to it;
2. a SHACL validation report graph;
3. a Kristal Validation Report entry or report section linking the SHACL execution to the checked artifact;
4. deterministic metadata sufficient to reproduce the SHACL profile execution.

Recommended serializations:

* Turtle for shapes;
* Turtle, N-Quads, or TriG for reports.

When byte-stable output is required, the implementation MUST declare the serialization profile and deterministic ordering rules used.

## Normative requirements

### R1. Shapes availability (MUST)

Implementations MUST provide one of:

* `shapes_uri`: a stable URI to the SHACL shapes graph; or
* `shapes_inline`: an embedded shapes graph for offline packaging.

The shapes MUST be versioned, and the version MUST be recorded.

The shapes version SHOULD be referenced from the Kristal Validation Report and MAY also be referenced from a validation decision, authority recognition record, or profile execution record.

### R2. Deterministic execution (MUST)

Given identical inputs, the same shapes version, the same profile configuration, and the same data projection:

* the set of reported SHACL results MUST be identical;
* result normalization MUST be deterministic;
* serialization ordering MUST be deterministic when byte-stable reports are required.

SHACL engines may differ in native result ordering. Kristal determinism applies to the normalized result set and to the declared deterministic serialization rules, not to unspecified engine-internal ordering.

### R3. Required linkage to Kristal artifacts (MUST)

The SHACL report MUST be linkable to the Kristal artifact or projection being checked via one or more of:

* `kristal:kristalId`;
* `kristal:artifactId`;
* `kristal:shardId`;
* `kristal:stateId`;
* `kristal:runtimePackId`;
* `kristal:buildId`;
* `kristal:contentHash`.

The related Kristal Validation Report MUST declare `profile_id = validation-shacl` in its enabled profiles list, profile execution list, or equivalent profile metadata section.

### R4. Mapping rules (MUST)

Each SHACL validation result MUST map to a Kristal Validation Report issue.

Severity mapping:

* `sh:Violation` maps to `severity = ERROR`;
* `sh:Warning` maps to `severity = WARNING`;
* `sh:Info` maps to `severity = INFO`.

Each mapped issue MUST include:

* `code`: a stable Kristal issue code;
* `severity`: the mapped Kristal severity;
* `message`: a human-readable explanation;
* `location`: a JSON pointer, RDF focus node IRI, artifact reference, assertion reference, or other stable target locator;
* `source_profile`: `validation-shacl`;
* `source_shape` or `source_constraint_component` when available.

### R5. Minimum SHACL result fields (MUST)

Each SHACL result node SHOULD include, and implementations MUST be able to produce, at minimum:

* `sh:focusNode`;
* `sh:resultSeverity`;
* `sh:sourceShape` or `sh:sourceConstraintComponent`;
* `sh:resultMessage`.

If an engine does not provide one of these fields natively, the implementation MUST either derive it during normalization or record a profile execution issue explaining the missing field.

### R6. No default effect on compilation, recognition, or activation (MUST)

Enabling SHACL output MUST NOT change core compilation behavior by itself.

A SHACL profile result MAY inform:

* a validation decision;
* a review process;
* an authority recognition decision;
* a reader policy;
* CI/CD reporting;
* publication checks;
* Runtime Pack activation policy.

However, this effect MUST be explicitly configured. The default behavior is reporting only.

SHACL conformance MUST NOT be treated as universal truth, universal validation, or authority recognition. It only reports conformance to the selected shapes graph under the declared profile configuration.

### R7. Scoped validation semantics (MUST)

A SHACL report MUST NOT imply that an artifact or assertion is globally valid.

If SHACL results are used to support validation, the resulting Kristal validation decision MUST remain scoped by:

* authority channel;
* validation policy;
* domain or subdomain;
* target level;
* certainty level where applicable;
* `validated_as` where applicable.

A SHACL-conformant artifact may still contain uncertain, disputed, fictional, mythological, speculative, or low-certainty assertions. SHACL conformance only means that the checked graph satisfies the declared shapes.

### R8. Target level declaration (MUST)

A SHACL profile execution MUST declare the target level being checked.

Allowed target levels:

* `artifact`;
* `shard`;
* `assertion`;
* `structured_epistemic_state`;
* `exchange`;
* `runtime_pack`;
* `rdf_projection`;
* `authority_registry`;
* `validation_report`;
* `reader_policy`.

The target level MUST be reflected in the Kristal Validation Report issue locations or profile execution metadata.

### R9. Projection declaration (MUST)

If SHACL is applied to a derived RDF projection rather than the native Kristal artifact, the report MUST declare:

* projection profile;
* projection version;
* source artifact ID;
* source content hash;
* projection content hash when available;
* projection generation configuration.

A SHACL report over a projection MUST NOT be silently presented as a direct report over the native artifact unless the projection profile explicitly guarantees equivalence for the checked constraints.

## Recommended conventions

### C1. Shape naming and versioning (SHOULD)

Shapes SHOULD use stable IRIs containing:

* `spec_version`;
* artifact type or target level;
* `shape_version`.

Example:

```text
urn:kristal:shapes:v5:exchange:1.0
```

Additional examples:

```text
urn:kristal:shapes:v5:structured-epistemic-state:1.0
urn:kristal:shapes:v5:runtime-pack:1.0
urn:kristal:shapes:v5:authority-registry:1.0
urn:kristal:shapes:v5:reader-policy:1.0
```

### C2. Code system (SHOULD)

Define a code namespace for SHACL-mapped issues:

```text
KRS_V5_<CATEGORY>_<NAME>
```

Examples:

```text
KRS_V5_SCHEMA_MISSING_REQUIRED_FIELD
KRS_V5_EVIDENCE_MISSING
KRS_V5_VALUE_NORMALIZATION_FAILED
KRS_V5_SCOPE_MISMATCH
KRS_V5_AUTHORITY_CHANNEL_MISSING
KRS_V5_CERTAINTY_LEVEL_INVALID
KRS_V5_VALIDATED_AS_MISSING
KRS_V5_READER_POLICY_UNSUPPORTED
KRS_V5_PROJECTION_MISMATCH
```

### C3. Include both JSON and RDF pointers where possible (SHOULD)

If the validator can derive a JSON pointer for the corresponding location in a Kristal artifact, include it in:

* Kristal Validation Report `location.json_pointer`;
* SHACL result message; or
* a Kristal extension triple.

If the validator can identify RDF locations, include:

* `sh:focusNode`;
* `sh:resultPath`;
* `kristal:rdfNode`;
* `kristal:rdfGraph`;
* `kristal:rdfTriple` where applicable.

### C4. Preserve authority and certainty labels (SHOULD)

When SHACL validation touches assertion-level data, mapped issues SHOULD preserve or reference:

* `assertion_id`;
* `assertion_status`;
* `certainty_level`;
* `validated_as`;
* `authority_channel`;
* `scope`.

This prevents SHACL reporting from flattening scoped validation into an unqualified pass/fail result.

### C5. Reader policy integration (SHOULD)

If a SHACL report is used by a reader, browser, AI agent, or Runtime Pack, the consuming system SHOULD expose whether the report affects:

* `reference_only` mode;
* `validated_only` mode;
* `high_certainty_only` mode;
* `research` mode;
* `creative` mode;
* `all_with_labels` mode;
* a custom reader policy.

SHACL results SHOULD NOT hide labels, uncertainty, disagreement, fictionality, mythology, or disputed status.

## Report structure requirements

### Shapes graph

The shapes graph:

* MUST contain SHACL shapes such as `sh:NodeShape` and/or `sh:PropertyShape`;
* MUST declare an explicit version identifier via `owl:versionInfo`, a Kristal predicate, or both;
* SHOULD declare the target artifact type or target level;
* SHOULD declare the Kristal spec version;
* SHOULD identify whether it applies to native Kristal JSON, RDF projection output, or both.

### Report graph

The report graph MUST follow SHACL Validation Report structure, including:

* `sh:conforms` boolean;
* `sh:result` entries for validation result nodes.

Each result node SHOULD include Kristal extension metadata when available.

## Required extension predicates

To improve interoperability between SHACL outputs and Kristal issue locations, implementations SHOULD emit the following predicates on each `sh:ValidationResult` when applicable:

* `kristal:issueCode`;
* `kristal:jsonPointer`;
* `kristal:artifactId`;
* `kristal:kristalId`;
* `kristal:shardId`;
* `kristal:stateId`;
* `kristal:runtimePackId`;
* `kristal:assertionId`;
* `kristal:evidenceId`;
* `kristal:authorityChannel`;
* `kristal:validationPolicy`;
* `kristal:certaintyLevel`;
* `kristal:validatedAs`;
* `kristal:scopeDomain`;
* `kristal:profileId`;
* `kristal:profileVersion`;
* `kristal:buildId`.

These extensions MUST NOT be required by generic SHACL tools, but they SHOULD be emitted by Kristal-aware implementations to make downstream automation reliable.

## Failure modes and required behaviors

### Shapes unavailable

If shapes are unavailable, the SHACL profile execution MUST fail and record an `ERROR` in the Kristal Validation Report.

Core compilation may still proceed unless the active deployment policy explicitly makes this SHACL profile a gate.

### Shapes invalid

If the shapes graph is invalid, the SHACL profile execution MUST fail and record an `ERROR` with:
--- CHUNK END ---

--- CHUNK BEGIN ---
id=770dbd1a7a70:351-462
start=351
end=462
----

* shape reference;
* shape version;
* validation engine;
* error message;
* profile configuration.

### Execution limits exceeded

If SHACL execution exceeds configured limits such as timeout, memory, graph size, or result count, the profile MUST fail and record an `ERROR` with explicit limit information.

### Projection unavailable

If SHACL requires an RDF projection and that projection cannot be produced, the profile MUST fail and record an `ERROR`.

If the profile is configured as report-only, this failure MUST NOT block compilation or artifact materialization.

### Mapping failure

If a SHACL result cannot be mapped to a Kristal Validation Report issue, the implementation MUST record an `ERROR` or `WARNING` describing the mapping failure.

The original SHACL result SHOULD be preserved or referenced for inspection.

### Partial execution

If partial execution is allowed by deployment policy, the report MUST declare:

* `execution_status = partial`;
* which shapes were executed;
* which shapes were skipped;
* why execution was incomplete;
* whether the partial result is allowed to inform validation, recognition, or reader policy.

## Conformance tests

A conforming implementation MUST provide fixtures demonstrating:

* stable shapes versioning;
* reproducible report production;
* correct severity mapping for `sh:Violation`, `sh:Warning`, and `sh:Info`;
* stable mapping to Kristal issue codes;
* linkability via `kristal_id`, artifact ID, or `build_id`;
* deterministic serialization rules for the chosen format or formats;
* projection declaration when SHACL is run against RDF derived from a native Kristal artifact;
* preservation of target level;
* preservation of scoped validation metadata when applicable;
* behavior when shapes are unavailable;
* behavior when shapes are invalid;
* behavior when execution limits are exceeded;
* behavior when a result cannot be mapped cleanly.

## Example profile execution metadata

```json
{
  "profile_id": "validation-shacl",
  "profile_version": "1.0",
  "spec_version": "5.0",
  "target_level": "exchange",
  "target_ref": {
    "id": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "artifact_type": "working_exchange"
  },
  "shapes_uri": "urn:kristal:shapes:v5:exchange:1.0",
  "shapes_version": "1.0",
  "projection_profile": "rdf-wdqs-export",
  "projection_version": "1.0",
  "execution_status": "completed",
  "engine": {
    "name": "example-shacl-engine",
    "version": "1.0.0"
  },
  "result_summary": {
    "conforms": false,
    "error_count": 1,
    "warning_count": 2,
    "info_count": 0
  }
}
```

## Example severity mapping

```text
sh:Violation -> ERROR
sh:Warning   -> WARNING
sh:Info      -> INFO
```

## Example Kristal issue mapping

```json
{
  "code": "KRS_V5_AUTHORITY_CHANNEL_MISSING",
  "severity": "ERROR",
  "message": "The assertion is marked as validated but does not declare an authority channel.",
  "location": {
    "json_pointer": "/assertions/12/authority_channel",
    "rdf_focus_node": "urn:kristal:assertion:12"
  },
  "source_profile": "validation-shacl",
  "source_shape": "urn:kristal:shapes:v5:exchange:authority-channel-required"
}
```

## Open questions

* Do we standardize a single shapes vocabulary per artifact type, or allow multiple named shape sets per target level?
* Do we require engines to output `sh:sourceConstraintComponent` consistently, or treat it as best effort?
* Should Kristal define a compact canonical SHACL report profile for byte-stable report hashing?
* Should reader policy evaluation have its own SHACL shape set, or remain outside this profile?
* Should authority recognition checks be expressed as SHACL constraints, or only referenced from validation policies?
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/05-profiles/profile-validation-shex.md"
id=fdeae3a1b827
kind=markdown
size=17105
lines=644
line_ref=1-644
chunks=2
chunk_refs=1-350,351-644
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=fdeae3a1b827:1-350
start=1
end=350
----
# Profile: Validation ShEx

## Status

Optional standardized profile for Kristal v5.

## Profile ID

```text
profile-validation-shex@2
```

## Purpose

This profile defines how a Kristal v5 implementation MAY publish **ShEx (Shape Expressions)** artifacts derived from declared Kristal Exchange projections to support:

* structural conformance checking by external tooling;
* implementer guidance and ecosystem interoperability;
* debugging and validation transparency;
* inspection of how Kristal assertions, scopes, provenance, authority recognition, and certainty metadata are projected into RDF-compatible forms.

ShEx outputs are **structural validation aids**. They do not determine Kristal truth, authority recognition, assertion status, certainty level, or reader visibility.

A ShEx artifact MAY help verify that a projected graph has the expected shape. It MUST NOT be treated as proof that the underlying assertions are validated, true, recognized, high-certainty, or accepted by an authority channel.

ShEx artifacts do not change the Exchange, Shard, Federation, Runtime Pack, Authority Registry, Validation Decision, or Reader Policy schemas. They do not affect content-addressed IDs unless explicitly included in hashed material by a separate declared profile.

---

## Scope

This profile specifies:

* required and optional ShEx artifacts;
* deterministic generation rules, when deterministic generation is claimed;
* packaging and manifest references;
* integrity verification requirements when ShEx artifacts are declared;
* the relationship between ShEx structural validation and Kristal v5 validation semantics.

This profile does **not**:

* make ShEx the primary Kristal validation mechanism;
* assign assertion status;
* assign certainty levels;
* create authority recognition;
* validate claims as fact, hypothesis, myth, fiction, policy, or institutional reference;
* require ShEx for Kristal v5 core conformance;
* require specific ShEx engines or toolchains;
* require consumers to execute ShEx validation during normal reading.

Kristal v5 validation remains scoped by:

```text
authority_channel
validation_policy
validation_status
validated_as
certainty_level
scope
reader_policy
```

ShEx only describes whether a declared RDF projection conforms to declared shapes.

---

## Conformance

An implementation claims this profile by including:

```text
profile-validation-shex@2
```

in one or more of:

* the Exchange Manifest `profiles[]`, if ShEx artifacts are attached to an Exchange;
* the Exchange Shard Manifest `profiles[]`, if ShEx artifacts are attached to a shard;
* the Exchange Federation Manifest `profiles[]`, if ShEx artifacts describe a federated projection;
* the Runtime Pack Manifest `profiles[]`, if ShEx artifacts are shipped with Runtime Packs.

If an implementation claims this profile, it MUST meet the requirements below.

---

## Relationship to Kristal v5 validation

ShEx validation and Kristal validation are different operations.

### ShEx structural validation

ShEx answers:

```text
Does this RDF projection have the expected structural shape?
```

Examples:

* required predicates are present;
* values have expected datatypes;
* projected nodes match declared shape constraints;
* expected provenance or authority fields are structurally present.

### Kristal validation

Kristal validation answers:

```text
Who accepts this claim, artifact, shard, or authority channel,
under which policy,
for which scope,
as what,
and at what certainty level?
```

Examples:

* an assertion is validated as a hypothesis;
* a shard is recognized by an authority channel;
* a medical corpus is recognized through a health authority;
* a mythological corpus is valid as mythology;
* a disputed claim is structurally preserved but rejected by a selected authority channel.

A passing ShEx result MUST NOT imply:

```text
validation_status = "validated"
recognition_status = "recognized"
certainty_level = "high"
artifact_status = "reference"
```

Those statuses require Kristal v5 validation decisions, authority recognition records, or reader policy evaluation.

---

## Artifacts

### Required artifacts

If this profile is claimed, the implementation MUST provide the following artifacts.

### 1. Primary ShEx schema

Recommended path:

```text
validation/shex/kristal.shex
```

Any path is allowed if referenced in the manifest.

Supported formats:

```text
ShExC: text/shex
ShExJ: application/json
```

The schema MUST describe the shapes relevant to the declared RDF projection covered by this profile.

The schema SHOULD include shapes for projected Kristal v5 concepts when present:

* Exchange;
* Exchange Shard;
* Federation Manifest;
* assertion;
* provenance reference;
* evidence reference;
* scope;
* authority channel;
* authority recognition;
* validation decision;
* certainty level;
* reader policy reference.

The schema MUST NOT claim to validate truth, authority, certainty, or recognition unless those concepts are represented as structural fields in the projection.

---

### 2. ShEx metadata descriptor

Recommended path:

```text
validation/shex/manifest.json
```

The descriptor MUST declare:

* profile ID;
* Kristal spec version;
* schema format;
* covered export projection or projections;
* generation tool information;
* generator configuration hash;
* deterministic generation flag;
* Exchange, Shard, Federation, or Runtime Pack reference;
* whether ShEx artifacts are included in content-addressed material;
* whether ShEx execution is required by the declaring profile.

---

## Optional artifacts

The implementation MAY provide:

```text
validation/shex/examples/
validation/shex/examples/passing/
validation/shex/examples/failing/
validation/shex/mapping.md
validation/shex/reports/
```

Optional artifact meanings:

* `examples/passing/`: minimal projected RDF examples expected to pass.
* `examples/failing/`: minimal projected RDF examples expected to fail structurally.
* `mapping.md`: human-readable mapping from Kristal v5 constructs to ShEx shapes.
* `reports/`: example validation reports; not normative unless explicitly declared by a separate profile.

---

## Coverage and projection rules

ShEx shapes MUST be defined against a **declared RDF projection** of Kristal material.

Implementations MUST specify one or more of the following projections.

### Projection A: WDQS-aligned RDF

The RDF projection defined in:

```text
05-profiles/profile-rdf-wdqs-export.md
```

This projection SHOULD preserve the relevant Wikidata-compatible structures when used for Wikidata Seed Kristals or WDQS-compatible exports.

### Projection B: JSON-LD RDF mapping

The JSON-LD export defined in:

```text
05-profiles/profile-jsonld-export.md
```

interpreted as RDF.

### Projection C: implementation-defined RDF projection

Allowed only if the exact projection is specified in:

```text
validation/shex/manifest.json
```

The implementation-defined projection MUST include:

* projection ID;
* projection version;
* projection description;
* source artifact type;
* mapping rules;
* hash of the projection definition, if deterministic generation is claimed.

The ShEx schema MUST explicitly name which projection or projections it covers.

---

## Deterministic generation requirements

If the implementation claims deterministic generation for ShEx artifacts, then generation MUST be deterministic given:

* the same source artifact snapshot;
* the same declared RDF projection;
* the same generation tool name and version;
* the same generation configuration;
* the same canonicalization rules for generated artifacts.

The ShEx metadata descriptor MUST include:

```text
generator.name
generator.version
generator.config_hash
source_ref
projection.id
projection.version
deterministic = true
```

Any ordering within ShExJ output that affects bytes MUST be deterministic. This includes stable ordering of:

* shapes;
* predicates;
* node constraints;
* value constraints;
* imports;
* prefixes, when emitted in order-sensitive formats.

If deterministic generation is not claimed, the profile MAY still be used, but the metadata descriptor MUST set:

```json
"deterministic": false
```

When `deterministic` is `false`, ShEx artifacts MUST NOT be used as the basis for content-addressed Kristal IDs.

---

## Packaging and manifest references

### If attached to an Exchange

The Exchange Manifest MUST list the ShEx files in its file inventory section, if such a section is present.

Each declared ShEx file MUST include:

```text
path
media_type
sha256
size_bytes
role
```

Recommended role:

```text
metadata
```

### If attached to an Exchange Shard

The Exchange Shard Manifest MUST reference the ShEx descriptor or ShEx files when the profile is claimed for that shard.

The manifest SHOULD indicate whether the ShEx artifacts describe:

```text
the shard only
the source Exchange projection
a subset projection
a federated projection
```

### If attached to a Federation Manifest

--- CHUNK END ---

--- CHUNK BEGIN ---
id=fdeae3a1b827:351-644
start=351
end=644
----
The Federation Manifest MUST specify whether the ShEx artifacts describe:

```text
each shard independently
the composed federated projection
both
```

Federated ShEx artifacts MUST NOT hide disagreement between shards. If conflicting claims are preserved by federation, the projection and shapes SHOULD preserve enough structure to expose those conflicts.

### If attached to Runtime Packs

The Runtime Pack Manifest MUST include the ShEx files in `files[]` with:

```text
role = "metadata"
sha256
size_bytes
media_type
```

A future profile MAY define a dedicated role such as:

```text
validation_schema
```

Until then, `metadata` is the standard role.

---

## Verification requirements

If ShEx artifacts are declared in a manifest and the consumer is configured to verify package integrity, then the consumer MUST verify:

* file presence;
* declared `sha256`;
* declared `size_bytes`, if present;
* descriptor consistency;
* profile ID consistency;
* projection ID consistency.

If a declared ShEx file is missing or its hash does not match, the artifact package MUST be marked as failing integrity verification for that declared profile.

This does not mean the underlying Kristal assertions are false. It means the declared ShEx profile package is incomplete or inconsistent.

Consumers MAY continue to inspect the rest of the package according to reader policy, provided that the missing or invalid ShEx profile status is visible.

---

## ShEx execution semantics

Running a ShEx engine is OPTIONAL for consumers.

A consumer MAY execute ShEx validation to check whether a declared RDF projection conforms to the declared ShEx schema.

A consumer MUST NOT require ShEx execution for Kristal v5 core conformance unless a separate profile explicitly requires it.

A ShEx execution result MUST be interpreted as structural evidence only.

A passing ShEx result means:

```text
The tested RDF projection conforms to the declared ShEx shapes.
```

A failing ShEx result means:

```text
The tested RDF projection does not conform to the declared ShEx shapes,
or the ShEx engine could not complete validation.
```

A failing ShEx result MUST NOT automatically imply:

```text
assertion_status = "rejected"
validation_status = "rejected"
recognition_status = "revoked"
certainty_level = "low"
```

Those statuses require Kristal validation decisions or authority recognition records.

---

## Failure and status semantics

When ShEx artifacts are declared but cannot be verified, implementations SHOULD report a profile-level status.

Recommended profile status values:

```text
not_declared
declared
verified
verification_failed
execution_not_run
execution_passed
execution_failed
unsupported
```

Example:

```json
{
  "profile": "profile-validation-shex@2",
  "profile_status": "verification_failed",
  "reason_codes": ["hash_invalid"],
  "affected_files": ["validation/shex/kristal.shex"]
}
```

Recommended reason codes:

```text
schema_file_missing
descriptor_missing
hash_invalid
size_mismatch
projection_mismatch
profile_id_mismatch
unsupported_shex_format
unsupported_projection
execution_error
shape_validation_failed
```

These reason codes MAY appear in validation reports, runtime diagnostics, or reader-facing inspection panels.

---

## Interaction with reader policies

Reader policies MAY use ShEx profile status as a structural quality signal.

Examples:

* a strict reader policy MAY require declared ShEx files to verify successfully;
* a research reader policy MAY show artifacts even when ShEx execution has not been run;
* a creative reader policy MAY ignore ShEx entirely;
* a reference-only reader policy MAY require both Kristal authority recognition and ShEx package verification.

Reader policies MUST NOT treat ShEx structural conformance as equivalent to authority recognition.

---

## Interaction with authority recognition

An authority channel MAY require ShEx artifacts as part of its validation policy.

Example:

```text
authority:example-health-body
requires:
  - schema validation
  - provenance sufficiency
  - ShEx structural conformance against projection A
  - expert review
```

In that case, ShEx results are inputs to the authority’s validation policy. They are not the validation decision itself.

The authority recognition record remains the authoritative place to express:

```text
recognition_status
recognized_as
scope
validation_policy_ref
reason_codes
```

---

## Minimal `validation/shex/manifest.json` schema

This section is non-normative.

Recommended fields:

```json
{
  "profile": "profile-validation-shex@2",
  "spec_version": "5.0",
  "deterministic": true,
  "included_in_content_hash": false,
  "source_ref": {
    "artifact_type": "reference_exchange",
    "artifact_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "content_hash": {
      "alg": "sha256",
      "value": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  },
  "projection": {
    "id": "profile-rdf-wdqs-export@1",
    "version": "1",
    "notes": "Shapes target the WDQS-aligned RDF projection."
  },
  "schema": {
    "path": "validation/shex/kristal.shex",
    "format": "ShExC",
    "media_type": "text/shex",
    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
    "size_bytes": 0
  },
  "generator": {
    "name": "kristal-shex-gen",
    "version": "2.0.0",
    "config_hash": {
      "alg": "sha256",
      "value": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  }
}
```

---

## Minimal profile status report

This section is non-normative.

```json
{
  "profile": "profile-validation-shex@2",
  "spec_version": "5.0",
  "profile_status": "execution_passed",
  "source_ref": {
    "artifact_type": "reference_exchange",
    "artifact_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
  },
  "projection": {
    "id": "profile-rdf-wdqs-export@1",
    "version": "1"
  },
  "schema_ref": {
    "path": "validation/shex/kristal.shex",
    "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
  },
  "execution": {
    "engine": {
      "name": "example-shex-engine",
      "version": "1.0.0"
    },
    "started_at": "2026-06-12T00:00:00Z",
    "completed_at": "2026-06-12T00:00:01Z",
    "result": "passed"
  },
  "reason_codes": []
}
```

---

## Security and integrity notes

ShEx artifacts can improve transparency, but they also create additional files that must be tracked correctly.

Implementations SHOULD ensure that:

* ShEx files are included in package inventories when declared;
* hashes use `alg`, not `algo`;
* signatures are excluded from their own hash targets;
* generated ShExJ output is deterministically ordered when determinism is claimed;
* source artifact IDs are not recomputed using generated ShEx artifacts unless explicitly included by profile;
* profile failures are visible to readers or operators.

---

## Summary

This profile standardizes how Kristal v5 implementations may publish ShEx artifacts for structural validation of RDF projections.

ShEx helps answer:

```text
Does this projected graph have the expected shape?
```

It does not answer:

```text
Is this claim true?
Who recognizes it?
At what certainty level?
Under which authority channel?
For which reader policy?
```

Those questions remain governed by Kristal v5 validation decisions, certainty metadata, authority recognition, federation semantics, and reader policies.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/06-integration/architect-rendering-contract.md"
id=1fd51b71ac91
kind=markdown
size=20627
lines=755
line_ref=1-755
chunks=3
chunk_refs=1-350,351-700,701-755
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=1fd51b71ac91:1-350
start=1
end=350
----
# Architect rendering contract

## Status

Draft (Kristal v5 integration contract)

## Purpose

This document defines the contract between **Architect** and **Kristal v5**.

Architect is the deterministic renderer. It produces text and other publishable outputs from Kristal query results without introducing new factual claims, without hiding provenance, and without flattening scoped validation into universal truth.

Architect does not decide what is true. It renders what the selected Kristal input and active reader policy allow it to render.

This contract applies to rendering from:

* Runtime Pack query result bundles;
* Exchange-derived query result bundles;
* Structured Epistemic State projections;
* federation-derived query results;
* authority-recognized reference artifacts;
* working artifacts when the active reader policy allows them.

Normative keywords: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY.

---

## 1. Scope and non-goals

### 1.1 In scope

* Inputs Architect is allowed to consume
* Reader policy requirements
* Determinism requirements for rendering
* Prohibitions on introducing new factual claims
* Traceability requirements
* Authority, validation, certainty, and scope preservation
* Error and refusal behavior
* Multilingual rendering rules and templating boundaries
* Output packaging
* Machine-readable trace maps
* Render bundle identity and optional signing

### 1.2 Out of scope

* How Kristals are built
* How review workflows are routed
* How authority channels are governed
* Runtime query engine implementation details
* Konnaxion UI presentation requirements
* Editorial policy beyond deterministic rendering, traceability, and status preservation

---

## 2. Contract overview

Architect rendering is a pure function over explicit inputs:

* input bundle;
* reader policy;
* rendering request;
* template or render profile;
* language and locale parameters.

Architect MUST produce deterministic output for identical inputs.

Architect MUST NOT introduce factual claims that are not supported by the input bundle.

Architect MUST preserve visible distinctions between:

* artifact status;
* assertion status;
* validation status;
* certainty level;
* validated-as mode;
* authority channel;
* recognition status;
* scope;
* disputed status;
* fictional, mythological, symbolic, speculative, or research mode.

Architect MAY render uncertain, disputed, fictional, mythological, speculative, or low-certainty material when the active reader policy permits it.

Architect MUST NOT present such material as higher-certainty, more broadly validated, or more widely recognized than the input supports.

---

## 3. Inputs

### 3.1 Allowed input types

Architect MUST accept only declared Kristal input bundles.

Allowed input types are:

**A) Runtime Pack query result bundle**

* `runtime_pack_id` or pack content ID;
* `runtime_pack_manifest` or manifest reference;
* `source_exchange_ref`;
* `source_artifact_status`;
* `query_contract_version`;
* `reader_policy_ref` or embedded reader policy;
* `query_results`;
* `result_provenance`;
* integrity metadata.

**B) Exchange-derived query result bundle**

* `source_kristal_id`;
* `exchange_manifest` or manifest reference;
* `artifact_type`, either `working_exchange` or `reference_exchange`;
* deterministic query spec;
* `query_results`;
* validation, recognition, or status metadata for the returned claims;
* proof that results were computed from the referenced Exchange under a declared query contract.

**C) Structured Epistemic State projection bundle**

* `state_id`;
* `schema_version`;
* `scope`;
* `assertions`;
* `projection_policy_ref`;
* provenance references;
* assertion status, certainty, and validation metadata.

**D) Federation-derived query result bundle**

* `federation_id`;
* `exchange_federation_manifest`;
* `authority_registry_ref`;
* `composition_policy`;
* `reader_policy_ref` or embedded reader policy;
* ordered query results;
* source shard references;
* conflict and disagreement metadata where applicable.

Architect MUST reject or refuse inputs that:

* cannot be traced to a stable Kristal artifact, state, shard, federation, Exchange, or Runtime Pack;
* do not provide stable assertion or statement identifiers;
* do not provide enough provenance to support trace maps;
* do not declare the active reader policy;
* do not declare validation, certainty, authority, and scope metadata where factual claims are rendered;
* violate the active reader policy.

Architect MUST NOT reject an input merely because it contains uncertainty, dispute, fiction, mythology, speculation, or low-certainty claims. Those are valid Kristal states when explicitly labeled and allowed by the reader policy.

---

## 4. Required identifiers

Inputs MUST include enough identifiers to support complete traceability.

At minimum, an input bundle MUST include one or more of:

* `kristal_id`;
* `runtime_pack_id`;
* `state_id`;
* `federation_id`;
* `shard_id`;
* `exchange_id`;
* `source_artifact_ref`.

For each rendered factual assertion, inputs MUST provide:

* `assertion_id` or deterministic assertion pointer;
* statement or claim pointer;
* evidence pointer, source pointer, or provenance reference;
* assertion status;
* certainty level;
* validation status;
* validated-as mode, when evaluated;
* authority channel, when validated or recognized;
* scope.

If no stable identifier exists, Architect MAY use a deterministic surrogate pointer derived from:

* subject;
* predicate;
* object;
* qualifiers;
* source artifact ID;
* content hash;
* scope.

The surrogate pointer MUST be recorded in the trace map.

---

## 5. Rendering request specification

Architect MUST take a rendering request object.

The rendering request MUST include:

* `render_kind`, such as `article`, `snippet`, `summary`, `qa`, `card`, `report`, `compare`, or `explain`;
* `language`, as a BCP-47 tag, such as `en` or `fr-CA`;
* `template_id` or `render_profile_id`;
* `template_version` or `render_profile_version`;
* `reader_policy_id` or embedded reader policy;
* `projection`, when supported;
* `constraints`.

The rendering request MAY include:

* `audience_profile`;
* `tone_profile`;
* `length_target`;
* `format`;
* `locale`;
* `citation_style`;
* `include_trace_summary`;
* `include_disputed_material`;
* `include_uncertainty_labels`;
* `include_authority_labels`;
* `include_certainty_labels`.

Audience and tone profiles MUST NOT change factual content.

---

## 6. Reader policy

Architect MUST render under an active reader policy.

The reader policy determines which material is eligible for rendering.

A reader policy MAY restrict:

* artifact statuses;
* assertion statuses;
* validation statuses;
* certainty levels;
* validated-as modes;
* authority channels;
* recognition statuses;
* domains;
* scopes;
* jurisdictions;
* languages;
* disputed material;
* fictional material;
* mythological material;
* symbolic material;
* speculative or research material.

Supported reader modes SHOULD include:

* `reference_only`;
* `validated_only`;
* `high_certainty_only`;
* `research`;
* `creative`;
* `all_with_labels`;
* `custom`.

### 6.1 Validated-only does not mean maximum certainty

A `validated_only` reader policy means that all rendered assertions satisfy the active validation policy.

It does not mean:

* all rendered assertions have maximum certainty;
* all rendered assertions are universally true;
* all authority channels agree;
* all assertions are physical-world factual claims.

For example:

* a hypothesis may be validated as a hypothesis;
* a mythological corpus may be validated as mythology;
* a fictional corpus may be validated as fiction;
* a technical document may be validated as a publisher declaration;
* a scientific claim may be validated as a high-confidence fact.

Architect MUST preserve these distinctions in output metadata and, when required by the render profile, in visible text.

---

## 7. Deterministic rendering rules

### 7.1 Determinism requirement

For identical:

* input bundle bytes;
* reader policy;
* template or render profile ID and version;
* language;
* locale;
* rendering parameters;

Architect MUST produce identical render bundles, modulo explicitly declared nondeterministic fields that are excluded from output hashing.

Examples of excluded fields MAY include:

* run timestamp;
* local execution environment ID;
* non-factual logging correlation ID.

### 7.2 No new factual claims

Architect MUST NOT introduce any factual assertion that is not supported by at least one input assertion, statement, claim, or provenance-bearing source.

This includes:

* numbers;
* dates;
* names;
* causal relationships;
* rankings;
* comparisons;
* superlatives;
* categorical claims;
* historical claims;
* scientific claims;
* legal claims;
* policy claims;
* institutional claims.

Architect MUST NOT add “common knowledge” filler if that filler asserts a new fact.

Architect MUST NOT use external enrichment from the network for factual claims.

Architect MAY add:

* headings;
* transitions;
* formatting;
* connective phrasing;
* summaries that are fully supported by traced input;
* uncertainty language when uncertainty is present in the input;
* non-factual stylistic phrasing that does not add information.

### 7.3 Status preservation

Architect MUST preserve the status of input claims.

Architect MUST NOT convert:

* `hypothesis` into fact;
* `claimed` into validated;
* `sourced` into high-confidence;
* `disputed` into settled;
* `fictional_corpus` into physical-world truth;
* `mythological_corpus` into physical-world truth;
* one authority’s recognition into another authority’s recognition;
* scoped validation into universal validation.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=1fd51b71ac91:351-700
start=351
end=700
----

### 7.4 Ambiguity preservation

If input contains unresolved ambiguity, Architect MUST either:

* render the ambiguity explicitly;
* omit the ambiguous claim;
* refuse to render the ambiguous claim as factual;
* fail deterministically if the render request requires a single resolved fact.

Architect MUST NOT silently choose one disambiguation unless the input explicitly declares a resolved selection.

### 7.5 Disagreement preservation

If input contains conflicting claims, Architect MUST follow the active reader policy.

Architect MAY:

* preserve disagreement;
* show multiple authority-scoped positions;
* select one position according to authority precedence;
* mark a claim as disputed;
* omit claims outside the reader policy.

Architect MUST NOT silently merge conflicting claims.

Architect MUST NOT hide that a claim is disputed when the input declares dispute and the render profile requires dispute visibility.

### 7.6 Projection consistency

If the input bundle declares a projection, Architect MUST:

* render only from that projection;
* record the projection in render metadata;
* preserve projection limitations in the trace map.

If the requested projection and input projection conflict, Architect MUST refuse or return a deterministic error.

---

## 8. Output requirements

Architect MUST output a render bundle.

A render bundle MUST include:

1. `rendered_text` or structured rendered blocks;
2. `trace_map`;
3. `render_metadata`;
4. `status`.

A render bundle MAY include:

* `render_hash`;
* signatures;
* template references;
* reader policy snapshot;
* warnings;
* refusal details;
* render diagnostics.

---

## 9. Render metadata

`render_metadata` MUST include:

* `schema_version`;
* `artifact_type`;
* `render_kind`;
* `language`;
* `template_id`;
* `template_version`;
* `reader_policy_id`;
* `reader_mode`;
* `source_refs`;
* `query_contract_version`, if from runtime query results;
* `projection`;
* `build_id`;
* `created_at`.

`artifact_type` MUST be:

```text
architect_render_bundle
```

`schema_version` MUST be:

```text
5.0
```

`source_refs` MUST identify the source artifact or artifacts, such as:

* Runtime Pack;
* Exchange;
* Structured Epistemic State;
* Federation;
* Shard;
* query bundle.

---

## 10. Trace map

The trace map MUST provide complete coverage of factual assertions.

### 10.1 Required structure

The trace map MUST include:

* `segments[]`;
* `source_refs[]`;
* `coverage_summary`.

Each segment MUST include:

* `segment_id`;
* `text_span`, byte offsets, token indices, or `block_id`;
* `segment_kind`;
* `assertions[]`;
* `status_labels[]`, when applicable.

Each assertion trace MUST include:

* `assertion_id` or deterministic assertion pointer;
* `support[]`;
* `assertion_status`;
* `certainty_level`;
* `validation_status`;
* `validated_as`, when evaluated;
* `authority_channel`, when evaluated or recognized;
* `recognition_status`, when recognized;
* `scope`;
* `notes`, if needed.

Each support pointer MUST include:

* statement ID, claim ID, or deterministic statement pointer;
* evidence IDs or reference pointers;
* source artifact reference;
* source kind, such as `exchange`, `runtime_pack`, `structured_epistemic_state`, `federation`, or `shard`;
* content hash, when available.

### 10.2 Coverage rule

Every factual statement in `rendered_text` MUST have at least one support entry in `trace_map`.

If a segment cannot be supported, Architect MUST do one of the following:

* omit the unsupported claim;
* render it only as explicitly marked uncertainty, if that uncertainty is supported by the input;
* fail the render with a deterministic error.

### 10.3 Label coverage

When the render profile requires visible labels, Architect MUST expose:

* uncertainty;
* dispute;
* fiction;
* mythology;
* symbolic mode;
* low certainty;
* scoped validation;
* authority channel;
* rejection or revocation;
* recognition status.

When the render profile does not require visible labels, Architect MUST still preserve them in machine-readable metadata.

---

## 11. Validation and refusal behavior

Architect MUST implement deterministic status and refusal behavior.

The top-level render status MUST be one of:

```text
ok
refused
error
partial
```

Architect MUST return:

* `status`;
* `code`;
* `message`;
* `details`, when applicable.

### 11.1 Required refusal and error codes

Architect MUST support at least:

* `INPUT_INTEGRITY_UNVERIFIED`;
* `MISSING_TRACE_IDS`;
* `MISSING_READER_POLICY`;
* `READER_POLICY_VIOLATION`;
* `AUTHORITY_POLICY_MISMATCH`;
* `CERTAINTY_POLICY_MISMATCH`;
* `VALIDATION_POLICY_MISMATCH`;
* `RECOGNITION_POLICY_MISMATCH`;
* `AMBIGUOUS_INPUT`;
* `DISPUTED_INPUT_NOT_ALLOWED`;
* `FICTIONAL_INPUT_NOT_ALLOWED`;
* `MYTHOLOGICAL_INPUT_NOT_ALLOWED`;
* `UNSUPPORTED_RENDER_KIND`;
* `PROJECTION_MISMATCH`;
* `POLICY_VIOLATION_NEW_FACT_RISK`;
* `UNSUPPORTED_LANGUAGE`;
* `UNSUPPORTED_TEMPLATE`;
* `TRACE_COVERAGE_FAILED`.

### 11.2 Refusal is not epistemic judgment

A refusal means the render request cannot be satisfied under the given input, policy, or template.

A refusal does not mean the underlying Kristal is false.

A refusal may mean:

* required provenance is missing;
* the reader policy excludes the material;
* uncertainty labels are required but unavailable;
* authority recognition is insufficient for the selected mode;
* the template would require unsupported factual claims;
* ambiguity cannot be resolved under the requested constraints.

---

## 12. Multilingual rendering

### 12.1 Language fidelity

Architect MAY translate labels, connective text, headings, and explanatory text.

Architect MUST NOT alter factual content.

Architect MUST preserve named entities, identifiers, quantities, dates, and scoped claims unless the input or template provides a deterministic localization rule.

### 12.2 Localized formatting

Architect MAY apply locale-specific formatting for:

* numbers;
* dates;
* currencies;
* units;
* punctuation;
* typography.

Localized formatting MUST NOT change meaning.

The underlying normalized value MUST remain traceable.

### 12.3 Cross-language determinism

Rendering in different languages may produce different bytes.

For each language, output MUST be deterministic given the same:

* input bundle;
* reader policy;
* language;
* locale;
* template;
* rendering parameters.

### 12.4 Translation of status labels

Status labels SHOULD be localized when the render profile requires human-readable labels.

The localized label MUST map back to the machine-readable source status.

For example:

```text
assertion_status = "hypothesis"
```

may render in French as:

```text
hypothèse
```

but the trace map MUST preserve:

```text
hypothesis
```

---

## 13. Security and offline constraints

Architect MUST NOT require network calls to produce correct factual output.

If network calls are used for non-factual assets, such as fonts or templates, they MUST NOT affect factual assertions.

If inputs are signed, Architect SHOULD verify signatures or rely on a verified delivery chain from Orgo, Konnaxion, or another declared runtime authority.

Architect MUST reject inputs that cannot satisfy the active deployment’s integrity and reader policy requirements.

Architect MUST preserve authority, validation, certainty, and scope metadata in offline rendering.

Offline rendering MUST NOT silently upgrade material from one status to another.

---

## 14. Render bundle identity and hashing

Architect render bundles MAY be content-addressed.

When content-addressed, the render hash MUST be computed over a deterministic serialization of:

* rendered output;
* trace map;
* render metadata;
* reader policy snapshot or reference;
* source refs;
* template refs.

The following fields MUST be excluded from the hash target unless a profile explicitly includes them:

* signatures;
* local runtime logs;
* non-factual correlation IDs;
* nondeterministic timestamps.

Hash objects MUST use:

```json
{
  "alg": "sha256",
  "value": "<hex>"
}
```

Architect MUST use `alg`, not `algo`.

Signatures MUST be outside the hash target.

---

## 15. Conformance tests
--- CHUNK END ---

--- CHUNK BEGIN ---
id=1fd51b71ac91:701-755
start=701
end=755
----

An implementation claiming conformance to this contract MUST provide tests for:

* deterministic rendering;
* trace coverage;
* no-new-facts enforcement;
* ambiguity preservation;
* disagreement preservation;
* reader policy enforcement;
* authority channel filtering;
* certainty filtering;
* validation status filtering;
* fictional and mythological scope handling;
* projection handling;
* multilingual determinism;
* render hash stability, when render hashing is supported.

### 15.1 Minimum test cases

A conforming implementation MUST include at least the following tests:

1. Same input bundle and render request produce identical render bundles.
2. Every factual claim has support pointers.
3. Unsupported factual additions are refused or removed.
4. Ambiguous input is rendered as ambiguous or refused.
5. Disputed input is preserved, labeled, omitted, or refused according to reader policy.
6. A `validated_only` reader policy excludes non-validated material.
7. A `research` reader policy may include lower-certainty material with labels.
8. A `creative` reader policy may include fictional or mythological material with labels.
9. A mythological claim is not rendered as physical-world fact.
10. Authority recognition by one channel is not rendered as recognition by another channel.
11. Projection mismatch triggers deterministic refusal or error.
12. Trace coverage failure triggers deterministic refusal or error.

---

## 16. Implementation notes

Architect should be boring.

It should not infer hidden truth.

It should not “improve” facts.

It should not smooth away disagreement.

It should not erase uncertainty.

It should not translate scoped recognition into universal recognition.

Architect’s job is to render clearly, deterministically, and traceably from Kristal artifacts under a selected reader policy.

The core invariant is:

> A rendered claim must never appear more certain, more validated, more recognized, more factual, or more universal than the Kristal input and reader policy support.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/06-integration/konnaxion-distribution-contract.md"
id=5ba5fe342ac1
kind=markdown
size=27742
lines=846
line_ref=1-846
chunks=3
chunk_refs=1-350,351-700,701-846
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=5ba5fe342ac1:1-350
start=1
end=350
----
# Konnaxion distribution contract (Kristal v5 integration)

## Status

Draft (v5 integration contract)

## Purpose

This document defines the contract for how **Konnaxion** distributes, verifies, caches, activates, and exposes **Kristal v5 Runtime Packs** and associated metadata for offline and low-bandwidth operation.

Konnaxion’s responsibilities in the ecosystem are to:

* distribute versioned offline packages;
* verify declared hashes, signatures, trust roots, compatibility constraints, and revocation policies;
* provide predictable activation, rollback, downgrade-prevention, and cache behavior;
* surface pack provenance, version metadata, source status, authority channels, validation state, certainty metadata, and reader policy metadata to higher-level modules;
* support user-facing and application-facing reader policies, including reference-only, validated-only, high-certainty-only, research, creative, all-with-labels, and custom views.

Konnaxion distributes and activates Runtime Packs. It does not decide universal truth. It enforces declared distribution policy, artifact integrity, compatibility, reader-policy behavior, and channel-specific authority requirements.

Normative keywords: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY.

---

## 1. Scope and non-goals

### 1.1 In scope

This contract covers:

* Runtime Pack bundle packaging and required metadata;
* distribution channels and signed channel indexes;
* authority registries and trust roots used by distribution channels;
* verification requirements for declared hashes, signatures, manifests, trust roots, compatibility constraints, and revocation lists;
* versioning, activation, rollback, downgrade prevention, and substitution prevention;
* reader policy distribution and application;
* offline caching behavior and storage layout expectations;
* distribution channels scoped by tenant, environment, region, audience, authority channel, or reader policy;
* telemetry and feedback signals as operational signals.

### 1.2 Out of scope

This contract does not define:

* how Kristal artifacts are compiled;
* how Structured Epistemic States are authored;
* how assertions are validated;
* how authority channels decide recognition;
* how facts, claims, myths, hypotheses, or disputed positions are debated;
* full device management or MDM integration;
* user interface design;
* Runtime Pack internal query semantics, except where query-contract compatibility affects activation.

Build workflows are owned by Orgo and the Kristal compiler. Validation and recognition are represented by Kristal validation decisions and authority recognition records. Konnaxion consumes those records according to distribution policy and reader policy.

---

## 2. Artifact types and identifiers

### 2.1 Runtime Pack bundle

A distributable Runtime Pack bundle MUST include:

* `runtime-pack-manifest.json`;
* pack payload files, such as tables, indexes, filters, dictionaries, projections, manifests, and policy payloads;
* file inventory metadata sufficient for offline verification;
* optional detached or embedded signature envelopes;
* optional signed channel index;
* optional authority registry;
* optional revocation list;
* optional reader policies;
* optional validation decision records;
* optional authority recognition records;
* optional transparency log entries.

The Runtime Pack Manifest MUST conform to:

```text
02-schemas/runtime-pack-manifest.schema.json
```

Backward compatibility aliases such as `pack_manifest.json` MAY be accepted by local tooling, but v5 emitters SHOULD publish:

```text
runtime-pack-manifest.json
```

### 2.2 Required identifiers

Each Runtime Pack bundle intended for distribution MUST be uniquely and unambiguously identified by the following metadata, carried either in the Runtime Pack Manifest, channel index, or both:

* `schema_version = "5.0"`;
* `artifact_type = "runtime_pack"`;
* `runtime_pack_id`;
* `runtime_pack_version`;
* `release_id`;
* `build_id`;
* source artifact reference;
* source artifact status;
* created timestamp for audit and debugging;
* distribution channel;
* signer key identifier where signatures are declared;
* content hash;
* query contract reference;
* reader policy references;
* authority registry reference where authority checks are required;
* revocation list reference where revocation checks are required.

Konnaxion MUST treat `runtime_pack_id` as the primary identity for pack selection, verification binding, caching, and activation.

### 2.3 Source artifact reference

A Runtime Pack MUST reference the source artifact or source composition from which it was compiled.

The source MAY be:

* `working_exchange`;
* `reference_exchange`;
* `exchange_shard_manifest`;
* `exchange_federation_manifest`;
* another declared source artifact type supported by the Runtime Pack profile.

A Runtime Pack derived from a Working Exchange is not equivalent to a Runtime Pack derived from a Reference Exchange.

Konnaxion MUST preserve and expose source status metadata to consumers, reader policies, search surfaces, and AI-facing integrations.

### 2.4 Source artifact status

A Runtime Pack MUST declare source artifact status.

Allowed source statuses SHOULD include:

* `working`;
* `under_review`;
* `recognized`;
* `reference`;
* `deprecated`;
* `superseded`;
* `revoked`.

Konnaxion MUST NOT infer that a pack is a reference pack from artifact existence alone.

### 2.5 Compatibility aliases

For transition and compatibility, consumers MAY accept older or alternate field names internally, but v5 emitters SHOULD use v5 names.

Compatibility aliases MAY include:

* `pack_id` as alias for `runtime_pack_id`;
* `pack_version` as alias for `release_id`;
* `source_kristal_id` as alias for a source artifact identifier;
* `kid` as alias for `key_id`.

Konnaxion MUST normalize accepted aliases to the v5 internal field names before verification, activation, and policy enforcement.

---

## 3. Distribution channels and indexes

### 3.1 Channels

Packs MUST be distributed via channels.

A channel MUST be scoped at minimum by:

* `tenant_id`;
* `environment`.

A channel MAY additionally be scoped by:

* `region`;
* `jurisdiction`;
* `audience_segment`;
* `authority_channel`;
* `reader_policy`;
* `domain`;
* `subdomain`;
* `language`;
* `deployment cohort`.

Konnaxion MUST NOT mix trust roots, authority registries, revocation state, reader policy defaults, verification policy, activation state, rollback state, or downgrade-prevention state across channels unless explicitly configured.

### 3.2 Channel identity

A channel SHOULD have a stable identifier:

```text
channel_id
```

The `channel_id` SHOULD be deterministic from declared channel scope or explicitly assigned by deployment policy.

Example channel dimensions:

```json
{
  "tenant_id": "tenant:example",
  "environment": "prod",
  "region": "ca-qc",
  "domain": "education",
  "reader_policy": "reader_policy:validated_only",
  "authority_channel": "authority:unesco"
}
```

### 3.3 Signed channel index

Konnaxion SHOULD consume a signed distribution index per channel.

A channel index is a control artifact that tells Konnaxion which Runtime Pack or pack set should be installed, staged, pinned, rejected, revoked, or activated.

If present, the channel index MUST be verified using the channel’s declared trust roots and authority policy before it is used for activation decisions.

A channel index MUST include at minimum:

* `schema_version`;
* `artifact_type = "distribution_channel_index"`;
* `channel_id`;
* `created_at`;
* `current` pointer;
* signing identity;
* signatures.

The `current` pointer MUST include:

* `release_id`;
* `runtime_pack_id`;
* source artifact status;
* required reader policy references, if any;
* required authority registry reference, if any;
* required revocation list reference, if any.

A channel index SHOULD additionally include:

* staged or canary pointers;
* cohort targeting metadata;
* pinned known-good packs;
* minimum allowed release ID;
* revoked artifact IDs or release IDs;
* revocation epoch marker;
* rollback authorization records;
* compatibility constraints;
* reader policy defaults;
* authority channel defaults;
* domain/subdomain constraints.

If a verified channel index is present, Konnaxion MUST treat it as the primary control plane for what to install or activate, subject to local verification, compatibility checks, downgrade prevention, reader policy constraints, and activation requirements.

---

## 4. Versioning and release semantics

### 4.1 Release identifiers

Konnaxion MUST treat release identifiers as structured, not ad hoc strings.

The authoritative monotonic field is:

```text
release_id
```

`release_id` is monotonic within a channel.

Implementations MUST define deterministic comparison rules per channel.

Recommended scheme:

```text
integer sequence
```

Compatibility aliases such as `pack_version` MAY be accepted, but Konnaxion MUST normalize to a single internal `release_id`.

### 4.2 Runtime Pack identity vs release identity

`runtime_pack_id` identifies artifact content.

`release_id` identifies a channel release position.

The same Runtime Pack MAY appear in multiple channels or releases if policy permits.

The same `release_id` MUST NOT point to different Runtime Pack IDs in the same channel unless a verified reissue authorization is present.

### 4.3 Source version metadata

The Runtime Pack Manifest SHOULD record:

* source artifact ID;
* source artifact type;
* source artifact status;
* source artifact content hash;
* source scope;
* authority recognition references;
* validation decision references;
* reader policy references;
* build ID;
* compiler identity;
* config hash.

Konnaxion SHOULD surface this metadata to higher-level modules.

---

## 5. Activation semantics

### 5.1 Activation rule

Konnaxion MUST only activate a Runtime Pack when all channel-required checks pass.

At minimum, activation requires:

1. Runtime Pack Manifest parses and passes schema validation.
2. Runtime Pack Manifest declares `schema_version = "5.0"`.
3. Runtime Pack Manifest declares deterministic build intent where required.
4. Runtime Pack Manifest includes a complete file inventory with hashes sufficient for offline verification.
5. Required files referenced by the manifest exist in the bundle.
6. Required file hashes verify.
7. Required signatures verify.
8. Required trust roots are available.
9. Required authority registry checks pass.
10. Required revocation checks pass.
11. Required reader policies are present and schema-valid.
12. Query contract compatibility is satisfied.
13. Required optional profiles are supported.
14. Pack is compatible with the client runtime.
15. Channel index, if used, authorizes the pack.
16. Downgrade-prevention and substitution-prevention rules pass.

Activation MUST be atomic.

Konnaxion MUST NOT leave the runtime in a partially activated state.

### 5.2 Activation does not mean truth

Activation means that the Runtime Pack is installed and usable under the declared channel and reader policies.

Activation MUST NOT be represented as universal validation, universal truth, maximum certainty, or recognition by every authority.

Activation does not change assertion status.

Activation does not create authority recognition.

Activation does not raise certainty.

### 5.3 Working and reference packs

Konnaxion MAY activate packs derived from Working Exchanges if channel policy permits.

Konnaxion MAY restrict some channels to packs derived from Reference Exchanges only.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=5ba5fe342ac1:351-700
start=351
end=700
----

Konnaxion MUST make source status available to the reader policy layer.

A user-facing or API-facing surface MUST NOT present a working pack as a reference pack unless a policy explicitly defines such behavior and labels remain visible.

### 5.4 Required labels

Activated packs MUST preserve enough metadata for consumers to distinguish:

* working vs reference source status;
* assertion status;
* validation status;
* recognition status;
* authority channel;
* certainty level;
* validated-as mode;
* scope;
* disputed status;
* rejected status;
* revoked status;
* fictional mode;
* mythological mode.

---

## 6. Downgrade prevention and substitution safety

### 6.1 Downgrade prevention

Konnaxion MUST implement downgrade prevention with deterministic, persisted state.

Minimum required rule:

Konnaxion MUST NOT activate an artifact with a lower `release_id` than the highest previously activated release in the same channel unless a policy-authorized rollback is present.

Konnaxion MUST persist per channel:

* `highest_activated_release_id`;
* active `runtime_pack_id`;
* active source artifact reference;
* active source artifact status;
* active reader policy references;
* active authority registry reference, if any;
* last successful verification metadata.

Konnaxion SHOULD also persist:

* `highest_seen_release_id`;
* last successful activation timestamp;
* signer key identifier;
* channel index hash;
* revocation list hash;
* compatibility decision metadata.

### 6.2 Substitution prevention

If a pack is received with the same `release_id` but a different `runtime_pack_id`, Konnaxion MUST treat this as an error unless a verified reissue authorization is present.

A reissue authorization MUST be:

* signed or otherwise verified under the channel policy;
* scoped to the channel;
* explicit about the replaced artifact;
* explicit about the replacement artifact;
* recorded for audit.

### 6.3 Revocation-aware activation

Konnaxion MUST NOT activate packs listed as revoked in a verified channel index, revocation list, authority registry policy, or equivalent verified revocation mechanism applicable to the channel.

Konnaxion MUST apply revocations according to:

* scope;
* authority channel;
* effective time;
* target type;
* channel policy;
* reader policy, where relevant.

---

## 7. Rollback behavior

### 7.1 Rollback modes

Konnaxion MUST support at least one rollback mode:

* **Pinned rollback**: activate a previously pinned known-good pack.
* **Last-known-good rollback**: activate the most recent previously active pack that is still present, verified, compatible, and not revoked.

### 7.2 Rollback authorization

Rollback MUST be explicit and policy-authorized.

Authorization MAY be conveyed through:

* a verified channel index containing a rollback authorization record;
* a verified operator action;
* a deployment-specific governance action;
* an Orgo workflow event referenced by a verified distribution policy.

If rollback is permitted, it MUST NOT occur silently.

### 7.3 Rollback constraints

A rollback target MUST satisfy:

* manifest schema validation;
* file inventory verification;
* required signature verification;
* required trust-root verification;
* revocation checks;
* compatibility checks;
* reader policy availability;
* channel scope compatibility.

Rollback MUST NOT bypass required verification.

Rollback MUST NOT silently change reader policy, authority channel, source status, or scope.

### 7.4 Rollback triggers

Rollback MAY be triggered by:

* explicit operator action;
* verified channel index update;
* current pack revocation;
* failed activation;
* local runtime health signals, if permitted by deployment policy;
* Orgo workflow event;
* compatibility failure after staged rollout.

Rollback MUST be deterministic given the same trigger event sequence and verified inputs.

---

## 8. Verification requirements

### 8.1 Verification scope

If the Runtime Pack Manifest, channel index, authority registry, revocation list, reader policy, validation decision, authority recognition record, or bundle declares any required verification material, Konnaxion MUST verify it before relying on the corresponding policy.

Verification material may include:

* hashes;
* file inventory hashes;
* signatures;
* signer identity;
* trust roots;
* authority registry references;
* revocation list references;
* compatibility constraints;
* reader policy references;
* validation decision references;
* authority recognition references.

### 8.2 Verification failure

If verification fails, Konnaxion MUST NOT treat the affected artifact as satisfying the corresponding policy.

Verification failure does not mean the bytes cannot exist, be inspected, quarantined, debugged, or used in a non-trusted diagnostic context.

Verification failure MUST block activation when activation depends on the failed verification.

### 8.3 Trust roots

Konnaxion MUST pin trust roots per channel.

Trust roots MUST be available offline at activation time.

Trust roots MUST NOT be fetched over the network at activation time as a dependency for correctness.

Trust roots may be:

* pre-provisioned;
* securely cached;
* delivered through a previously verified channel update;
* provided through a signed authority registry.

### 8.4 Recommended verification order

Recommended order:

1. Verify channel index, if used.
2. Verify authority registry, if required.
3. Verify revocation list, if required.
4. Verify reader policy artifacts, if required.
5. Verify Runtime Pack Manifest schema.
6. Verify Runtime Pack Manifest signatures, if required.
7. Verify Runtime Pack Manifest content hash, if applicable.
8. Verify bundle file inventory hashes.
9. Verify validation decision and authority recognition references needed for the active policy.
10. Verify compatibility constraints.
11. Activate atomically.

Implementations MAY choose a different order if the result is deterministic and no policy is treated as satisfied before its prerequisites are verified.

---

## 9. Reader policy distribution and application

### 9.1 Reader policy role

Reader policies define which assertions, artifacts, authority channels, validation statuses, certainty levels, and epistemic modes are visible to a reader or application.

Konnaxion MUST support distribution of reader policies when Runtime Packs depend on them.

Reader policies MAY be embedded in the pack, referenced by content hash, distributed through the channel index, or provided by local deployment policy.

### 9.2 Reader policy modes

Reader policies SHOULD support the following modes:

* `reference_only`;
* `validated_only`;
* `high_certainty_only`;
* `research`;
* `creative`;
* `all_with_labels`;
* `custom`.

### 9.3 Validated-only semantics

A `validated_only` reader policy means that all visible assertions satisfy the active reader policy.

It does not mean:

* all visible assertions are universally true;
* all visible assertions have maximum certainty;
* all visible assertions are recognized by every authority;
* all authorities agree.

### 9.4 Reader policy metadata

Konnaxion MUST preserve and expose reader-policy-relevant metadata, including:

* `artifact_status`;
* `source_artifact_status`;
* `assertion_status`;
* `validation_status`;
* `recognition_status`;
* `authority_channel`;
* `certainty_level`;
* `validated_as`;
* `scope`;
* disputed status;
* rejected status;
* revoked status;
* fictional mode;
* mythological mode.

### 9.5 Label preservation

Konnaxion MUST NOT hide labels required to distinguish certainty, authority, validation, recognition, dispute, rejection, fiction, mythology, or revocation state unless a reader policy explicitly filters the corresponding assertion out of view.

A reader policy MAY simplify presentation, but it MUST NOT silently launder scoped validation into universal truth.

---

## 10. Offline caching and storage contract

### 10.1 Storage layout

Konnaxion SHOULD store packs in a layout that supports:

* multiple installed versions per channel;
* multiple reader policies per channel;
* multiple authority registries per channel where configured;
* atomic activation;
* garbage collection with pinning rules;
* persisted per-channel safety state;
* last-known-good recovery.

Example layout:

```text
/<tenant>/<env>/<channel>/packs/<runtime_pack_id>/...
/<tenant>/<env>/<channel>/active -> <runtime_pack_id>
/<tenant>/<env>/<channel>/reader-policies/<reader_policy_id>.json
/<tenant>/<env>/<channel>/authority/authority-registry.json
/<tenant>/<env>/<channel>/authority/revocations.json
/<tenant>/<env>/<channel>/state.json
```

### 10.2 Cache policy

Konnaxion MUST define deterministic cache policies.

Cache policies MUST define:

* maximum disk usage per channel;
* eviction policy;
* pinned-pack behavior;
* minimum retained packs;
* treatment of revoked packs;
* treatment of deprecated packs;
* treatment of reader policy artifacts;
* treatment of authority registries and revocation lists.

Recommended minimum retained set:

* active pack;
* last-known-good pack;
* pinned packs;
* active reader policy artifacts;
* active authority registry;
* active revocation list.

### 10.3 Offline behavior

If offline, Konnaxion MUST:

* continue serving from the active pack;
* continue applying the active reader policy;
* continue using cached trust roots, authority registry, and revocation list;
* not attempt activation requiring network-dependent trust roots;
* not treat unavailable network state as new validation or recognition.

Konnaxion SHOULD surface stale metadata where useful, including:

* active release ID;
* active source status;
* active reader policy;
* active authority registry version;
* active revocation list version;
* last successful update check;
* last successful activation.

---

## 11. Compatibility checks

Before activation, Konnaxion MUST verify compatibility from the Runtime Pack Manifest and channel policy.

Compatibility checks MUST include:

* schema version compatibility;
* Runtime Pack manifest version compatibility;
* query contract compatibility;
* required profile support;
* required data projections;
* required reader policy support;
* required authority registry support;
* required revocation support;
* source artifact status policy;
* policy selections within the allowed portable policy set;
* runtime engine support.

If incompatible, Konnaxion MUST:

--- CHUNK END ---

--- CHUNK BEGIN ---
id=5ba5fe342ac1:701-846
start=701
end=846
----
* not activate the pack;
* emit a deterministic error code;
* emit a diagnostic payload;
* preserve the currently active pack if possible.

### 11.1 Source status compatibility

A channel MAY require:

* reference packs only;
* working packs allowed;
* research packs allowed;
* creative packs allowed;
* specific authority channels;
* specific reader policies;
* specific certainty thresholds.

Konnaxion MUST enforce these requirements before activation.

---

## 12. Telemetry and feedback signals

Konnaxion MAY emit operational signals to Orgo.

Operational signals MAY include:

* download failures;
* verification failures;
* activation success or failure;
* rollback events;
* downgrade-prevention events;
* substitution-prevention events;
* query runtime errors;
* performance summaries;
* pack usage metrics;
* reader policy usage metrics;
* stale-pack events;
* missing authority registry events;
* missing revocation list events;
* missing reader policy events.

These signals MUST NOT mutate Kristal Exchange directly.

These signals SHOULD create Cases, Tasks, release records, distribution adjustments, or review workflows.

Telemetry MUST NOT silently change assertion status, certainty level, validation status, authority recognition, or reference status.

---

## 13. Error codes

Konnaxion SHOULD emit deterministic error codes for activation and verification failures.

Recommended codes:

* `manifest_schema_invalid`;
* `manifest_missing_required_field`;
* `file_inventory_missing`;
* `file_hash_mismatch`;
* `signature_invalid`;
* `signature_missing`;
* `trust_root_missing`;
* `authority_registry_missing`;
* `authority_registry_invalid`;
* `revocation_list_missing`;
* `revocation_list_invalid`;
* `runtime_pack_revoked`;
* `source_artifact_revoked`;
* `reader_policy_missing`;
* `reader_policy_invalid`;
* `query_contract_unsupported`;
* `profile_unsupported`;
* `release_id_downgrade_blocked`;
* `release_id_substitution_blocked`;
* `rollback_not_authorized`;
* `source_status_not_allowed`;
* `authority_channel_not_allowed`;
* `certainty_policy_not_satisfied`;
* `activation_incomplete`;
* `activation_aborted`.

---

## 14. Conformance tests

A Konnaxion implementation claiming v5 conformance MUST provide tests for:

* Runtime Pack Manifest schema validation;
* file inventory hash verification;
* signature verification success and failure;
* trust-root verification;
* authority registry verification;
* revocation-list behavior;
* activation blocking when required verification fails;
* atomic activation and no partial state;
* downgrade prevention with persisted `highest_activated_release_id`;
* same `release_id` with different `runtime_pack_id` substitution rejection;
* policy-authorized rollback;
* rollback rejection without authorization;
* offline behavior using active cached pack;
* no network dependency for activation correctness;
* cache eviction respecting pinned and last-known-good packs;
* reader policy presence and schema validation;
* `validated_only` reader policy behavior;
* source status enforcement;
* reference-pack-only channel enforcement;
* working-pack-allowed channel behavior;
* revoked pack rejection;
* revoked key rejection;
* unsupported query contract rejection;
* unsupported profile rejection.

### 14.1 Reader policy tests

Reader policy conformance tests SHOULD verify that Konnaxion:

* preserves labels required for certainty, validation, recognition, and authority;
* does not present working data as reference data;
* does not treat scoped validation as universal truth;
* filters rejected, revoked, fictional, mythological, disputed, or low-certainty assertions according to active policy;
* serves active reader policy behavior offline.

### 14.2 Federation tests

Federation-related distribution tests SHOULD verify that Konnaxion:

* activates federation-derived packs only when required shards are present;
* verifies shard references and hashes;
* applies required authority registries;
* handles optional shards according to declared policy;
* does not silently merge conflicting claims;
* preserves source status and authority metadata.

---

## 15. Open questions

* Do v5 core channels require pre-activation verification of all bundle file hashes, or should verify-on-first-use be a declared profile?
* Should delta update manifests be standardized as a Runtime Pack distribution profile?
* Should the distribution channel index have its own JSON Schema under `02-schemas/`?
* Should reader policies be embedded in Runtime Packs by default or distributed as separate signed artifacts?
* Should authority registries be channel-bound, pack-bound, or both?
* Should Konnaxion require active revocation lists for all reference-only channels?
* Should stale-pack metadata be a mandatory API surface or a recommended UX feature?
* Should `runtime-pack-manifest.json` be the only canonical filename, with alias support limited to migration tools?
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/06-integration/orgo-workflow-contract.md"
id=ee2ed7c75587
kind=markdown
size=27053
lines=982
line_ref=1-982
chunks=3
chunk_refs=1-350,351-700,701-982
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=ee2ed7c75587:1-350
start=1
end=350
----
# Orgo Workflow Contract

## Status

Draft — Kristal v5 normative integration contract

## Purpose

This document defines the required **workflow orchestration**, **governance**, **review**, **validation**, **recognition**, **release**, and **auditability** behavior for Orgo when Orgo acts as the control plane for Kristal production and distribution.

This contract is concerned with:

* managing Kristal workflow lifecycle;
* recording structured inputs, outputs, decisions, and releases;
* separating compilation from validation and authority recognition;
* supporting review and validation workflows across multiple authority channels;
* ensuring every build is reproducible where reproducibility is claimed;
* ensuring production and distribution actions are auditable and tenant-safe;
* preserving feedback as structured signals that may produce new artifacts, revisions, validations, recognitions, or forks.

This document does **not** define the internal Orgo task model beyond what is necessary for Kristal interoperability.

---

## Normative language

The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as normative requirements.

---

# 1. Roles and responsibilities

## 1.1 Orgo is the workflow control plane

Orgo MUST:

* create and manage the lifecycle of Kristal workflows;
* store workflow state, assignments, approvals, review outcomes, validation decisions, recognition decisions, release decisions, and audit logs;
* record build inputs, outputs, and their content-addressed identifiers;
* record authority channels, validation policies, reader policies, and release policies used by a workflow;
* trigger publication and distribution actions;
* track publication and distribution status;
* surface deterministic errors, warnings, and blocking conditions to operators;
* preserve tenant boundaries and trust-root boundaries;
* preserve provenance from input signals through released artifacts.

Orgo MUST NOT:

* mutate Kristal Exchange artifacts in place as a result of feedback signals;
* treat compilation, validation, and authority recognition as the same state;
* present an artifact or assertion as recognized outside the authority channel, validation policy, scope, and certainty level that support that status;
* silently override validation, recognition, integrity, tenant, or release-policy decisions.

## 1.2 Pipeline systems referenced by Orgo

Orgo may orchestrate interactions with:

* input systems that provide documents, datasets, web pages, PDFs, submissions, emails, forms, archives, APIs, or offline imports;
* extractors that may output Claim-IR as an extractor proposal profile;
* human editors, reviewers, domain experts, institutional validators, or AI-assisted validators;
* SenTient for resolution, reconciliation, normalization, and ambiguity preservation;
* Kristal compiler services for Structured Epistemic State, Exchange, shard, federation, and Runtime Pack creation;
* validation engines;
* authority registries;
* signing and trust-root services;
* Konnaxion or other distribution systems;
* Architect or other rendering systems;
* transparency logs or audit archives.

## 1.3 Kristal-owned versus Orgo-owned responsibilities

Kristal owns:

* structured epistemic states;
* exchange artifacts;
* runtime pack manifests;
* schemas;
* content-addressed identity;
* canonicalization for hashing;
* signatures and trust roots;
* assertion status;
* certainty metadata;
* authority recognition references;
* validation decision references;
* federation manifests;
* query contracts.

Orgo owns:

* workflow lifecycle;
* operational cases and tasks;
* review routing;
* approval routing;
* human and institutional coordination;
* validation request tracking;
* authority recognition request tracking;
* build records;
* release records;
* distribution records;
* tenant-scoped audit logs;
* feedback handling;
* operational remediation.

---

# 2. Workflow model

## 2.1 Required workflow capabilities

A Kristal workflow managed by Orgo MUST be able to represent the following stages:

1. **Ingest**
2. **Structure**
3. **Resolve**
4. **Compile Working Artifact**
5. **Review**
6. **Validate**
7. **Recognize**
8. **Compile or Select Reference Artifact**
9. **Compile Runtime Pack**
10. **Verify Release Requirements**
11. **Publish**
12. **Distribute**
13. **Post-release monitoring**
14. **Feedback and revision**

Orgo MAY split these stages into sub-stages.

Orgo MAY omit stages that are not applicable to a given workflow, provided that omitted stages are recorded as not applicable rather than silently ignored.

## 2.2 No universal required path

Orgo MUST NOT assume that every Kristal workflow begins with Claim-IR.

Valid inputs may include:

* Structured Epistemic State;
* existing datasets;
* Wikidata-aligned corpora;
* institutional submissions;
* expert-authored claims;
* research bundles;
* fictional or mythological corpora;
* Claim-IR produced by an extractor;
* Resolved Claim-IR produced through SenTient;
* prior Kristal Exchanges;
* prior shards;
* prior federations;
* prior Runtime Packs;
* feedback-derived structured signals.

Claim-IR MAY be used where probabilistic extraction is involved. It is not the universal required input format.

## 2.3 Compilation and validation are distinct

Orgo MUST support workflows where a working Kristal artifact is compiled before final validation or authority recognition.

Compilation materializes structured work into portable artifacts.

Validation records whether an artifact, shard, assertion, dataset, or authority channel is accepted under a declared policy and scope.

Authority recognition records whether an authority channel recognizes an artifact, shard, assertion, dataset, Runtime Pack, or other authority channel.

These states MUST remain distinct.

## 2.4 Recommended stage order

A common workflow SHOULD follow this order:

1. **Ingest**
2. **Structure → Structured Epistemic State**
3. **Optional extraction → Claim-IR**
4. **Optional resolution → SenTient outputs**
5. **Compile → Working Exchange**
6. **Review**
7. **Validation decision**
8. **Authority recognition**
9. **Reference Exchange selection or compilation**
10. **Runtime Pack compilation**
11. **Release verification**
12. **Publish and distribute**
13. **Monitor and collect feedback**

This order is recommended, not universal. Orgo MAY support alternative workflows when policy allows them and records the reason.

---

# 3. Stage semantics

## 3.1 Ingest

The Ingest stage records input material.

Orgo MUST record:

* input source;
* input snapshot reference;
* tenant scope;
* submitter or publisher identity when available;
* access-control constraints;
* timestamps;
* source format;
* declared domain or scope when available.

Orgo SHOULD produce content-addressed references for every input snapshot.

## 3.2 Structure

The Structure stage produces or registers a **Structured Epistemic State**.

A Structured Epistemic State SHOULD include:

* assertions;
* scope;
* provenance;
* evidence references;
* uncertainty;
* assertion status;
* certainty level;
* lineage;
* policy references;
* review references where available.

Orgo MUST record the Structured Epistemic State reference used by subsequent stages.

## 3.3 Extraction

Extraction is optional.

When probabilistic extractors are used, Orgo SHOULD require their direct output to be Claim-IR or another declared extractor proposal profile.

Orgo MUST record:

* extractor identity;
* extractor version;
* input snapshot refs;
* output refs;
* configuration refs;
* uncertainty and confidence fields when supplied;
* whether extractor outputs were frozen for replay.

## 3.4 Resolution

Resolution is optional but SHOULD be used when inputs contain ambiguous names, properties, entities, dates, units, or multilingual labels.

Orgo may invoke SenTient to produce:

* candidate QIDs/PIDs;
* ranking signals;
* normalized values;
* ambiguity records;
* unresolved references;
* warnings.

Orgo MUST preserve unresolved ambiguity rather than forcing certainty when resolution is insufficient.

## 3.5 Compile Working Artifact

The Compile Working Artifact stage produces a working Kristal artifact such as a `working_exchange`.

Orgo MUST record:

* compiler identity;
* compiler version;
* configuration hash;
* canonicalization profile;
* canonicalization version;
* source input refs;
* output artifact refs;
* compile status;
* reason codes where applicable.

A working artifact MAY contain uncertain, disputed, incomplete, fictional, mythological, speculative, or erroneous assertions, provided that their statuses are explicit.

## 3.6 Review

The Review stage coordinates human, institutional, expert, automated, or hybrid review.

Orgo SHOULD record:

* reviewer identity or reviewer group;
* authority channel, if applicable;
* review policy;
* scope;
* review result;
* review comments or structured findings;
* reviewed targets;
* timestamps;
* signatures or attestations when applicable.

Review is not the same as validation unless a validation policy explicitly treats a review outcome as a validation decision.

## 3.7 Validation

The Validation stage records scoped validation decisions.

A validation decision MUST declare:

* target reference;
* target level: artifact, shard, assertion, authority channel, dataset, or Runtime Pack;
* validation status;
* validated-as mode;
* certainty level, where applicable;
* authority channel;
* validation policy reference;
* scope;
* findings;
* reason codes;
* timestamp;
* signatures where required.

Orgo MUST NOT record validation as a bare boolean.

Invalid:

```json
{ "validated": true }
```

Required pattern:

```json
{
  "validation_status": "validated",
  "validated_as": "sourced_claim",
  "certainty_level": "medium",
  "authority_channel": "authority:example",
  "validation_policy_ref": "policy:example",
  "scope": {
    "domain": "science"
  }
}
```

## 3.8 Recognition

Recognition records whether an authority channel accepts or recognizes a target.

A recognition decision MAY target:

* an assertion;
* a shard;
* an Exchange;
* a Runtime Pack;
* a dataset;
* a federation;
* another authority channel;
* a validation policy.

Recognition MUST be scoped.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=ee2ed7c75587:351-700
start=351
end=700
----

Recognition by one authority channel MUST NOT imply recognition by another authority channel.

## 3.9 Reference Artifact

A Reference Artifact is an artifact recognized as a reference under one or more authority channels and scopes.

Orgo MUST preserve the distinction between:

* working artifacts;
* under-review artifacts;
* recognized artifacts;
* reference artifacts;
* deprecated artifacts;
* revoked artifacts.

Orgo MUST NOT present a working artifact as a reference artifact unless recognition and release policy allow it.

## 3.10 Runtime Pack compilation

A Runtime Pack is a derived, offline-usable indexed form of a Kristal Exchange.

Orgo MUST record:

* source Exchange reference;
* source artifact status;
* compiler identity;
* build configuration hash;
* query contract reference;
* reader policy references;
* runtime pack manifest reference;
* file hashes;
* integrity metadata;
* signatures where applicable.

A Runtime Pack MUST declare whether it is derived from a working artifact or a reference artifact.

## 3.11 Release verification

Before publication or distribution, Orgo MUST verify release requirements declared by the applicable release policy.

Release verification MAY include:

* hash verification;
* signature verification;
* trust-root verification;
* schema conformance;
* tenant-scope conformance;
* authority-channel requirements;
* validation-status requirements;
* recognition-status requirements;
* reader-policy availability;
* downgrade-prevention requirements;
* revocation checks.

If required verification fails, Orgo MUST block the release action and record the failure reason.

## 3.12 Publish and distribute

Publication makes artifacts available to declared channels.

Distribution moves artifacts, manifests, or Runtime Packs to target environments.

Orgo MUST record:

* release ID;
* artifact references;
* runtime pack references;
* target channels;
* tenant or audience scope;
* release timestamp;
* verification status;
* distribution status;
* rollout strategy where applicable.

---

# 4. Status model

## 4.1 Workflow status

Orgo MUST represent workflow status using stable values.

Recommended values:

* `draft`
* `ingesting`
* `structuring`
* `resolving`
* `compiling_working_artifact`
* `under_review`
* `validating`
* `recognizing`
* `compiling_reference_artifact`
* `compiling_runtime_pack`
* `verifying_release`
* `publishing`
* `distributing`
* `released`
* `blocked`
* `failed`
* `revoked`
* `deprecated`
* `superseded`

## 4.2 Compile status

Recommended values:

* `not_started`
* `succeeded`
* `failed`
* `partial`
* `blocked`

## 4.3 Review status

Recommended values:

* `not_required`
* `pending`
* `in_progress`
* `completed`
* `blocked`
* `rejected`

## 4.4 Validation status

Recommended values:

* `not_evaluated`
* `in_review`
* `validated`
* `conditionally_validated`
* `disputed`
* `rejected`
* `revoked`

## 4.5 Recognition status

Recommended values:

* `none`
* `recognized`
* `conditionally_recognized`
* `under_review`
* `disputed`
* `rejected`
* `deprecated`
* `revoked`

## 4.6 Publication status

Recommended values:

* `not_published`
* `published`
* `blocked`
* `revoked`

## 4.7 Distribution status

Recommended values:

* `not_started`
* `pending`
* `in_progress`
* `distributed`
* `partially_distributed`
* `failed`
* `rolled_back`
* `revoked`

---

# 5. Build Record requirements

For every Kristal build, Orgo MUST persist a **Build Record**.

## 5.1 Identifiers

The Build Record MUST contain:

* `build_id`;
* `tenant_id` in multi-tenant deployments;
* `workflow_id`;
* `case_id` or task reference when applicable;
* `created_at`;
* `created_by` or triggering actor when available.

## 5.2 Inputs

The Build Record MUST contain `input_snapshots[]`.

Input snapshots MAY include:

* source dataset snapshots;
* document snapshots;
* web archive snapshots;
* API snapshots;
* user submissions;
* institutional submissions;
* Claim-IR snapshots;
* Structured Epistemic State snapshots;
* prior Exchange refs;
* prior Runtime Pack refs;
* configuration snapshots.

## 5.3 Compiler identity and configuration

The Build Record MUST contain:

* `compiler.name`;
* `compiler.version`;
* `config_hash`;
* `canonicalization_profile`;
* `canonicalization_version`.

For Kristal v5, the canonicalization profile SHOULD be:

```text
kristal.v5:jcs-rfc8785
```

and the canonicalization version SHOULD be:

```text
1
```

## 5.4 Policy selections

The Build Record MUST record policy selections that affect outputs or decisions.

These MAY include:

* compilation policy;
* validation policy;
* recognition policy;
* reader policy;
* federation composition policy;
* query policy;
* runtime pack policy;
* release policy;
* tenant policy;
* trust-root policy;
* downgrade-prevention policy.

## 5.5 Outputs

The Build Record SHOULD distinguish:

* `working_outputs[]`;
* `reference_outputs[]`;
* `runtime_pack_outputs[]`;
* `validation_decisions[]`;
* `authority_recognitions[]`;
* `review_records[]`;
* `release_records[]`;
* `revocation_records[]`.

Each output SHOULD be content-addressed when possible.

## 5.6 Status summary

The Build Record MUST distinguish:

* `compile_status`;
* `review_status`;
* `validation_status`;
* `recognition_status`;
* `publication_status`;
* `distribution_status`;
* `activation_status`, when applicable.

These statuses MUST NOT be collapsed into one pass/fail field.

## 5.7 Reason codes

The Build Record SHOULD include stable reason codes.

Recommended codes include:

* `schema_valid`;
* `schema_invalid`;
* `provenance_sufficient`;
* `provenance_insufficient`;
* `evidence_sufficient`;
* `evidence_insufficient`;
* `authority_recognized`;
* `authority_not_recognized`;
* `scope_mismatch`;
* `policy_satisfied`;
* `policy_failed`;
* `signature_valid`;
* `signature_invalid`;
* `hash_valid`;
* `hash_invalid`;
* `conflict_detected`;
* `disagreement_preserved`;
* `certainty_too_low_for_policy`;
* `rejected_by_authority_channel`;
* `revoked_by_authority_channel`.

---

# 6. Integrity verification requirements

## 6.1 Verification before release

Before publishing or distributing Exchange or Runtime Pack artifacts, Orgo MUST verify all integrity material required by the active release policy.

This MAY include:

* declared content hashes;
* manifest hashes;
* pack hashes;
* signatures;
* signing keys;
* trust roots;
* revocation status;
* schema conformance;
* tenant-scope conformance.

If required verification fails, Orgo MUST:

* block the release or distribution action;
* record the failure reason;
* preserve the failed candidate for inspection if policy allows;
* prevent the candidate from being represented as released, recognized, or trusted for that channel.

## 6.2 Declared integrity material

If an artifact declares integrity material, Orgo MUST verify it according to the applicable trust-root, tenant, release, and reader policies before using it as trusted material.

Orgo MUST NOT “publish anyway” when required verification fails.

Orgo MUST treat malformed required integrity fields as errors.

## 6.3 Diagnostic access

Orgo MAY allow operators to inspect failed candidates, malformed artifacts, or unrecognized artifacts in diagnostic or review contexts.

Such access MUST clearly mark the artifact status and MUST NOT present the artifact as recognized, released, or trusted.

---

# 7. Distribution workflow requirements

## 7.1 Versioned Release records
--- CHUNK END ---

--- CHUNK BEGIN ---
id=ee2ed7c75587:701-982
start=701
end=982
----

Orgo MUST create a **Release Record** per published version.

A Release Record MUST include:

* release ID;
* release version;
* tenant or channel scope;
* Exchange references;
* Runtime Pack references;
* source artifact status;
* authority recognition references where applicable;
* validation decision references where applicable;
* reader policy references;
* target channels;
* publish timestamp;
* verification status;
* distribution status.

## 7.2 Rollout controls

Orgo SHOULD support progressive rollout strategies:

* staged rollouts by cohort;
* canary releases;
* blue/green releases;
* region-scoped releases;
* tenant-scoped releases;
* device-cohort releases;
* automatic rollback on required verification failures;
* rollback on high operational error rates where policy allows.

These rollout mechanics are operational guidance. The Release Record MUST remain auditable.

## 7.3 Downgrade prevention

If the distribution environment supports version pinning, Orgo MUST provide a mechanism to prevent downgrade to a vulnerable, invalid, revoked, or disallowed pack version.

Orgo MUST record pinned minimum versions per channel when used.

## 7.4 Revocation-aware distribution

Orgo SHOULD check revocation records before publishing or distributing artifacts.

If an artifact or signing authority is revoked under the applicable policy, Orgo MUST block distribution unless the release policy explicitly permits diagnostic or archival distribution.

---

# 8. Multi-tenancy and isolation

## 8.1 Tenant scoping

All workflow records MUST be tenant-scoped in multi-tenant deployments.

Orgo MUST prevent cross-tenant visibility of build inputs, outputs, validation decisions, recognition decisions, and release records unless explicitly configured for shared artifacts.

## 8.2 Shared artifacts

If artifacts are shared across tenants, Orgo MUST record:

* source tenant or publisher;
* sharing policy;
* permitted target tenants;
* authority channels;
* trust roots;
* reader policies;
* access-control constraints.

## 8.3 Keys and signing

Signing keys MAY be tenant-scoped even when artifact IDs are global and content-addressed.

Orgo MUST:

* record which keys signed which artifacts or releases;
* record which trust roots were used for verification;
* enforce that verification uses the correct trust roots for the tenant, channel, and release policy.

---

# 9. Feedback loop handling

## 9.1 Feedback must not mutate Exchange directly

Orgo MUST represent feedback as:

* Cases;
* Tasks;
* review requests;
* validation requests;
* recognition requests;
* structured signals;
* correction proposals;
* revocation requests;
* fork requests;
* new Structured Epistemic States;
* new Claim-IR proposals where extraction is involved.

Orgo MUST NOT edit Exchange artifacts in place due to votes, curation, user edits, operator comments, or feedback signals.

## 9.2 Feedback-to-build linkage

Orgo SHOULD link:

* feedback signals;
* cases;
* tasks;
* review records;
* validation decisions;
* recognition decisions;
* resulting builds;
* resulting releases.

This linkage makes governance auditable.

## 9.3 Fork handling

If feedback produces a divergent corpus or shard, Orgo MAY initiate a fork workflow.

Fork workflows MUST preserve:

* source lineage;
* fork reason;
* publisher;
* authority channel;
* validation scope;
* recognition status;
* relationship to the source artifact.

A fork MUST NOT inherit recognition from the source unless the recognizing authority explicitly recognizes the fork.

---

# 10. Validation and authority workflows

## 10.1 Validation requests

Orgo SHOULD support validation requests targeting:

* assertions;
* shards;
* Exchanges;
* Runtime Packs;
* datasets;
* authority channels;
* reader policies.

A validation request SHOULD declare:

* target;
* requested authority channel;
* validation policy;
* scope;
* requested validated-as mode;
* evidence refs;
* submitter;
* deadline or review window where applicable.

## 10.2 Authority recognition requests

Orgo SHOULD support authority recognition requests.

Recognition requests MAY ask one authority channel to recognize:

* an artifact;
* a shard;
* an assertion;
* another authority channel;
* a dataset;
* a validation policy;
* a Runtime Pack;
* a release.

Recognition MUST be recorded as scoped.

## 10.3 Delegated authority

Authority channels MAY recognize other authority channels.

Examples:

* an international organization recognizes a health authority for public-health references;
* a government recognizes a national statistics office for demographic data;
* a standards body recognizes a working group for a technical specification;
* a company is recognized as the primary source for its own declared system architecture.

Orgo MUST record delegated recognition explicitly.

---

# 11. Observability requirements

Orgo SHOULD emit structured logs or events for each stage.

Events SHOULD include:

* `build_id`;
* `workflow_id`;
* `case_id`;
* `tenant_id`;
* `kristal_id`;
* `exchange_id`;
* `runtime_pack_id`;
* `release_id`;
* stage name;
* stage outcome;
* compile status;
* review status;
* validation status;
* recognition status;
* publication status;
* distribution status;
* reason codes;
* hash verification result;
* signature verification result;
* authority channel;
* reader policy;
* correlation ID.

Logs MUST NOT leak cross-tenant data.

---

# 12. Minimal API surface

This section is informative.

Orgo implementations typically expose operations equivalent to:

* `CreateKristalWorkflow(input_snapshots, config_ref, policy_selections)`
* `RegisterStructuredEpistemicState(workflow_id, state_ref)`
* `AttachClaimIR(workflow_id, claim_ir_ref)`
* `RequestResolution(workflow_id, target_ref)`
* `AdvanceStage(workflow_id, stage, outputs)`
* `CreateReviewTask(workflow_id, target_ref, reviewer_ref, policy_ref)`
* `RecordReviewOutcome(workflow_id, review_record_ref)`
* `RequestValidation(workflow_id, target_ref, authority_channel, policy_ref)`
* `RecordValidationDecision(workflow_id, validation_decision_ref)`
* `RequestAuthorityRecognition(workflow_id, target_ref, authority_channel, policy_ref)`
* `RecordAuthorityRecognition(workflow_id, recognition_ref)`
* `CompileWorkingExchange(workflow_id)`
* `CompileReferenceExchange(workflow_id)`
* `CompileRuntimePack(workflow_id)`
* `GetBuildRecord(build_id)`
* `CreateRelease(build_id, channels, reader_policies)`
* `VerifyRelease(release_id)`
* `PublishRelease(release_id)`
* `GetReleaseStatus(release_id)`
* `CreateRevisionWorkflow(source_artifact_ref, feedback_refs)`
* `CreateForkWorkflow(source_artifact_ref, fork_policy_ref)`

API shape is implementation-specific.

---

# 13. Conformance checklist

Orgo satisfies this contract if it:

* manages Kristal workflows as auditable lifecycle objects;
* supports Structured Epistemic State as the normative input unit;
* treats Claim-IR as an optional extractor proposal profile, not a universal required input;
* distinguishes compilation from review, validation, recognition, publication, distribution, and activation;
* records build inputs, configuration, policies, outputs, statuses, and reason codes in Build Records;
* records scoped validation decisions;
* records scoped authority recognitions;
* records Runtime Pack and Exchange references separately;
* verifies required hashes, signatures, trust roots, revocation status, and release requirements before trusted publication or distribution;
* blocks release or distribution when required verification fails;
* creates auditable versioned Release Records;
* isolates multi-tenant workflows and enforces correct trust roots;
* preserves feedback as structured signals that trigger new workflows rather than in-place Exchange edits;
* supports forks without silently inheriting authority recognition;
* keeps reader-policy, authority-channel, validation, certainty, and scope information available to downstream systems.

---

# 14. Core invariant

A Kristal workflow may produce artifacts that contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.

Orgo’s responsibility is not to erase those states. Orgo’s responsibility is to make sure each state is recorded, scoped, auditable, and never presented as more recognized, certain, validated, or authoritative than the applicable policies and authority channels allow.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/06-integration/sentient-resolution-contract.md"
id=25f49a775c7d
kind=markdown
size=14750
lines=505
line_ref=1-505
chunks=2
chunk_refs=1-350,351-505
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=25f49a775c7d:1-350
start=1
end=350
----
# 06-integration/sentient-resolution-contract.md

# SenTient Resolution Contract

## Status

Draft (v5 normative integration contract)

## Purpose

Define the required **inputs**, **outputs**, and **deterministic semantics** for SenTient when SenTient acts as a resolution, disambiguation, normalization, or extraction-support engine for Kristal v5.

This contract ensures:

* ambiguity is preserved explicitly;
* outputs are schema-valid and deterministically structured;
* downstream compilation, validation, review, federation, and recognition remain reproducible and auditable;
* failure modes are explicit;
* SenTient does not silently convert uncertainty into validated knowledge.

This document does **not** prescribe SenTient’s internal retrieval, scoring, judging, or modeling architecture. It specifies the interoperability boundary only.

## Normative language

The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as normative requirements.

---

# 1. SenTient role in Kristal v5

SenTient supports Kristal v5 by resolving and normalizing source material into structured forms usable by Kristal artifacts.

SenTient may operate on:

* Claim-IR batches emitted by extractors;
* Structured Epistemic States;
* datasets;
* human-authored drafts;
* institutional submissions;
* unresolved assertion fragments;
* source-system records such as Wikidata-compatible statements.

SenTient may produce:

* ranked candidate identifiers;
* normalized typed literals;
* explicit unresolved ambiguity structures;
* warnings and errors;
* extraction proposals;
* resolution metadata;
* candidate mappings to existing entities, properties, references, or authority channels.

SenTient MUST NOT:

* force disambiguation without sufficient evidence;
* silently coerce ambiguous surfaces into single IDs;
* introduce new assertions beyond what the input or resolution policy permits;
* mark an assertion as validated or recognized by an authority channel;
* hide ambiguity from downstream Kristal artifacts.

In Kristal v5, SenTient is not the universal proposal boundary. Claim-IR is an extractor proposal profile. Structured Epistemic State is the normative Kristal v5 input form.

---

# 2. Inputs

## 2.1 Supported inputs

SenTient MUST accept at least one of the following input types, depending on implementation scope:

* a Claim-IR batch conforming to `02-schemas/claim-ir.schema.json`;
* a Structured Epistemic State conforming to `02-schemas/structured-epistemic-state.schema.json`;
* an Exchange or Exchange fragment;
* a dataset record batch declared by profile;
* a source-system statement batch declared by profile.

A SenTient implementation MUST declare which input profiles it supports.

## 2.2 Claim-IR input

When SenTient accepts Claim-IR, it treats Claim-IR as an extractor proposal profile, not as the universal Kristal v5 input requirement.

Claim-IR input SHOULD include:

* `claim_id` or stable local ID;
* surface forms for entities and properties;
* proposed literals or values;
* evidence pointers;
* uncertainty representation;
* source references;
* extraction metadata.

SenTient MAY emit a Resolved Claim-IR batch when operating in a Claim-IR compatibility profile.

## 2.3 Structured Epistemic State input

When SenTient accepts a Structured Epistemic State, the input SHOULD include:

* `state_id`, if already content-addressed;
* assertions or assertion fragments;
* surface forms requiring resolution;
* provenance references;
* evidence references;
* certainty metadata, if available;
* scope metadata;
* policy references;
* prior resolution references, if available.

SenTient MAY emit an updated Structured Epistemic State, a resolution bundle, or resolution findings referencing the input state.

## 2.4 Optional hints and constraints

SenTient MAY accept optional hints, including:

* preferred language or locale;
* candidate constraints;
* allowed QID/PID sets;
* tenant-specific mapping overlays;
* domain or subdomain constraints;
* jurisdiction constraints;
* time-window constraints;
* authority-channel hints;
* prior resolution state;
* corpus snapshot IDs;
* reader-policy hints;
* validation-policy hints.

If hints are used, SenTient MUST:

* treat them as advisory unless the active resolution policy says otherwise;
* record their presence in output metadata;
* preserve enough metadata for downstream systems to understand how hints affected the resolution run.

---

# 3. Outputs

## 3.1 Supported output types

SenTient MAY output one or more of:

* Resolved Claim-IR batch;
* Structured Epistemic State;
* Resolution Bundle;
* Validation Report findings;
* candidate mapping bundle;
* normalized literal bundle;
* warnings and errors attached to the input object;
* lineage or provenance records.

An implementation MUST declare which output profiles it supports.

## 3.2 Resolved Claim-IR compatibility output

When outputting Resolved Claim-IR, SenTient MUST conform to:

```text
02-schemas/resolved-claim-ir.schema.json
```

The output MUST preserve a stable mapping to input Claim-IR items.

Every output resolution result MUST reference the originating `claim_id`.

## 3.3 Structured Epistemic State output

When outputting or updating a Structured Epistemic State, SenTient MUST preserve:

* source assertion identity where present;
* provenance references;
* evidence references;
* unresolved ambiguity;
* scope;
* certainty metadata unless explicitly changed under policy;
* lineage from input to output.

SenTient MUST NOT silently replace a lower-certainty state with a higher-certainty one.

If SenTient changes certainty metadata, it MUST record the reason and policy basis for the change.

## 3.4 Resolution Bundle output

A Resolution Bundle SHOULD include:

* `resolution_bundle_id`;
* `schema_version = "5.0"`;
* `artifact_type = "resolution_bundle"`;
* `created_at`;
* `created_by`;
* `input_refs`;
* `resolution_run_id`;
* `resolution_policy_ref`;
* `scope`;
* `results`;
* `warnings`;
* `errors`;
* `lineage`;
* `signatures`, when applicable.

A Resolution Bundle is a support artifact. It does not itself validate or recognize claims.

---

# 4. Resolution results per surface

For each resolvable surface, including entity surfaces, property surfaces, value normalization targets, references, authority-channel candidates, or scope candidates, SenTient MUST provide an explicit result.

## 4.1 Ranked candidates

A resolution result SHOULD include ranked candidates.

Each candidate SHOULD include:

* `id`;
* `candidate_type`;
* `score`;
* `evidence_refs`;
* optional `features`;
* optional `source_corpus_ref`;
* optional `authority_channel`, when the candidate is authority-scoped.

Candidate lists MUST be sorted deterministically.

## 4.2 Decision state

One of the following decision states MUST be explicitly recorded:

```text
resolved_single
resolved_multi
unresolved
error
not_applicable
```

Meanings:

* `resolved_single`: resolved to one selected candidate.
* `resolved_multi`: multiple candidates remain plausible; no single candidate is forced.
* `unresolved`: no adequate candidate is available.
* `error`: resolution process failed in a defined way.
* `not_applicable`: the surface does not require resolution.

## 4.3 Selected binding

If the decision state is `resolved_single`, SenTient MUST provide:

* `selected.id`;
* `selected.score`, when scoring is used;
* selected candidate type.

If the decision state is `resolved_multi`, SenTient MUST NOT provide a selected binding unless a profile explicitly marks it as a non-authoritative UI suggestion.

If the decision state is `unresolved` or `error`, SenTient MUST NOT provide a selected binding.

## 4.4 Ambiguity preservation

If evidence is insufficient for unique resolution, SenTient MUST use:

```text
resolved_multi
```

or:

```text
unresolved
```

SenTient MUST NOT hide unresolved ambiguity by selecting a single candidate for convenience.

---

# 5. Determinism and portability

## 5.1 Output structure determinism

SenTient output MUST be deterministic in structure:

* stable field names;
* stable types;
* stable decision-state vocabulary;
* stable ordering rules;
* stable serialization behavior when canonicalized.

This does not require scores to remain identical across model versions.

It requires that:

* the output is well formed;
* candidate ranking is explicit;
* ambiguity is explicit;
* the same scoring run produces stable ordering.

## 5.2 Candidate list truncation

If SenTient returns only top-K candidates:

* K MUST be declared in output metadata;
* truncation MUST be consistent by surface type;
* truncation MUST be reported when it may affect interpretation.

Recommended declaration:

```json
{
  "candidate_top_k": {
    "entity": 20,
    "property": 10,
    "authority_channel": 10,
    "literal_normalization": 5
  }
}
```

## 5.3 Stable sorting rules

SenTient MUST define deterministic tie-breakers for candidates.

Default ordering:

1. score descending;
2. stable identifier ascending lexicographically;
3. deterministic hash of `(surface, candidate_id, candidate_type)`.

This avoids nondeterminism when scores collide.

## 5.4 Literal normalization determinism

When normalizing literals such as dates, quantities, coordinates, identifiers, time ranges, or units, SenTient MUST:

* produce typed outputs in a deterministic schema form;
* include explicit unit, precision, calendar, timezone, or coordinate system fields when relevant;
* record lossy normalization decisions as warnings;
* preserve the original surface form when relevant.

---

# 6. Output metadata

SenTient output MUST include metadata sufficient for downstream compilation, validation, review, federation, and audit.

## 6.1 Required metadata

SenTient output MUST include:

* `resolution_run_id`;
* `schema_version`;
* `sentient_version` or resolver version string;
* `created_at`;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=25f49a775c7d:351-505
start=351
end=505
----
* `input_refs`;
* `hints_used`;
* `hint_refs`, if hints were used;
* `policies`, including:

  * `candidate_top_k`;
  * `tie_breakers`;
  * `normalization_ruleset_id`;
  * `resolution_policy_ref`.

## 6.2 Optional metadata

SenTient output MAY include:

* resource limits encountered;
* timeouts;
* corpus snapshot IDs;
* model identifiers used for semantic scoring;
* source corpus versions;
* tenant scope;
* authority-channel hints;
* reader-policy hints;
* validation-policy hints.

If optional metadata is recorded, it MUST NOT affect core identity unless included in the declared hash target or reproducibility surface.

---

# 7. Warnings and errors

## 7.1 Structured codes

SenTient MUST emit warnings and errors as structured records containing:

* machine-readable `code`;
* severity;
* human-readable `message`;
* optional `details`;
* input linkage, where applicable;
* surface linkage, where applicable.

Severity values SHOULD be:

```text
info
warning
error
```

Codes MUST be stable across minor versions.

## 7.2 Required warning categories

SenTient SHOULD include warning codes for:

* unresolved entity surfaces;
* unresolved property surfaces;
* ambiguous multi-candidate surfaces;
* literal normalization loss;
* unit coercion;
* precision loss;
* date or time ambiguity;
* evidence insufficiency;
* weak grounding;
* top-K truncation;
* timeout;
* upstream outage;
* tenant overlay conflict;
* scope mismatch;
* authority-channel ambiguity.

## 7.3 Failure behavior

If SenTient cannot complete resolution for a claim or assertion due to transient issues, resource limits, upstream outages, or internal errors, SenTient MUST:

* return a syntactically valid output object for the declared output profile;
* mark affected surfaces as `unresolved` or `error`;
* emit explicit error codes;
* preserve input linkage;
* avoid silently dropping claims, assertions, evidence, or provenance.

---

# 8. Interaction with validation, recognition, and compilation

Validation stages MUST be able to interpret SenTient outputs deterministically.

Therefore SenTient MUST:

* keep all resolution states explicit;
* keep warning and error codes stable and structured;
* provide all required metadata needed to interpret results;
* preserve provenance and ambiguity.

SenTient output MAY be compiled into a Working Exchange when the compilation policy permits.

SenTient output MUST NOT by itself imply:

* validation;
* authority recognition;
* high certainty;
* reference status;
* reader visibility.

A validation report may cite SenTient results as evidence, findings, or diagnostics. It must not treat SenTient resolution as automatic truth.

---

# 9. Security and multi-tenancy

## 9.1 Tenant scoping

If SenTient is used in a multi-tenant environment:

* tenant-specific hints and overlays MUST be isolated by `tenant_id`;
* output metadata MUST indicate tenant scope when applicable;
* candidate generation MUST NOT leak tenant-private records into another tenant’s output.

## 9.2 Input confidentiality

SenTient MUST NOT leak:

* evidence pointers;
* source snippets;
* private corpus references;
* tenant-specific mappings;
* internal candidate features;

across tenants or unauthorized authority contexts.

## 9.3 Authority-channel isolation

If authority-channel-specific mappings or hints are used, SenTient MUST preserve which authority channel supplied or constrained them.

A candidate preferred under one authority channel MUST NOT be presented as generally preferred unless the policy explicitly permits that interpretation.

---

# 10. Conformance checklist

SenTient satisfies this contract if it:

* accepts and declares at least one supported Kristal v5 input profile;
* produces at least one declared Kristal v5 output profile;
* emits ranked candidates where resolution is attempted;
* records explicit decision states;
* preserves ambiguity;
* avoids silent coercion;
* applies deterministic sorting and tie-breakers;
* produces deterministic literal normalization structures;
* emits structured warnings and errors with stable codes;
* preserves input linkage;
* preserves provenance and evidence references;
* returns valid outputs even on partial failure;
* does not mark claims as validated, recognized, or high-certainty without an explicit validation or authority policy outside SenTient’s resolution role.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/07-security/downgrade-rollback-policy.md"
id=837756bce0f3
kind=markdown
size=32736
lines=902
line_ref=1-902
chunks=3
chunk_refs=1-350,351-700,701-902
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=837756bce0f3:1-350
start=1
end=350
----
# Downgrade and Rollback Policy (Kristal v5)

## Status

Draft (normative)

## Purpose

Define how Kristal v5 distributors, clients, Runtime Pack consumers, and authority-channel-controlled distribution flows prevent:

* **downgrade attacks**: maliciously providing an older, vulnerable, revoked, or compromised artifact;
* unsafe **rollbacks**: unintended reversion to older packs due to caching, sync conflicts, stale indexes, or operator error;
* authority-channel confusion: applying trust roots, reader policies, activation rules, or recognition status from one channel to another;
* silent substitution: replacing an artifact with another artifact using the same version label but a different content identity.

This policy is required to make signed Runtime Packs, Exchange release pointers, authority-recognized references, and offline Kristal distributions safe to use at scale, especially in offline or intermittently connected environments.

This policy protects artifact identity, distribution integrity, and activation state. It does not assert that all content inside an artifact is universally true, high-certainty, or recognized by every authority channel.

---

## Scope

In scope:

* Versioning and monotonic update rules for Runtime Packs and Exchange release pointers
* Minimum metadata required to enforce downgrade and rollback prevention
* Client enforcement behavior: accept, reject, hold, activate, rollback, or quarantine
* Offline-friendly mechanisms that do not rely on live services at activation time
* Planned rollback and emergency rollback
* Interaction with pinned trust roots and offline revocation data where available
* Channel-scoped activation rules for tenants, environments, regions, audiences, authority channels, and reader policies
* Relationship between Runtime Pack activation, artifact verification, authority recognition, validation status, and reader policy

Out of scope:

* Key lifecycle procedures beyond what is required for downgrade and rollback enforcement
* Full content trust model beyond artifact identity, signature verification, pinned trust roots, and declared policy
* UI/UX specifics
* Determining whether an assertion is true, high-certainty, validated, rejected, mythological, fictional, disputed, or visible under a given reader policy
* Defining authority-channel governance rules beyond the metadata required for enforcement

See also:

* `01-core-spec/signatures-trust.md`
* `01-core-spec/authority-recognition.md`
* `02-schemas/runtime-pack-manifest.schema.json`
* `02-schemas/exchange-manifest.schema.json`
* `02-schemas/authority-registry.schema.json`
* `02-schemas/reader-policy.schema.json`
* `06-integration/konnaxion-distribution-contract.md`
* `08-ops/release-strategies.md`

---

## Normative keywords

MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as normative requirement keywords.

---

## Core concepts

### Artifact types

Rollback and downgrade policies apply to the following Kristal v5 artifacts:

* **Working Exchange**: a compiled, portable artifact that may contain unvalidated, partially validated, research, disputed, low-certainty, fictional, mythological, or otherwise scoped material.
* **Reference Exchange**: an Exchange that is recognized under one or more authority channels or reader policies for a declared scope.
* **Runtime Pack**: a derived, offline-usable distribution payload identified by `runtime_pack_id` and scoped by channel, version, source Exchange, build, and reader policy context.
* **Exchange Shard**: a scoped subset of Exchange content, identity, provenance, validation references, and recognition references.
* **Exchange Federation**: a manifest that composes shards or Exchanges without silently merging identities, authorities, scopes, or disagreements.
* **Authority Registry**: a registry of authority channels, trust roots, scopes, validation policies, and recognition relationships.
* **Authority Recognition**: a scoped record saying that an authority channel recognizes, conditionally recognizes, rejects, revokes, or classifies a target.
* **Validation Decision**: a scoped decision saying that an artifact, shard, assertion, Runtime Pack, or authority channel has a validation status under a declared policy.
* **Reader Policy**: a policy that determines which authority channels, certainty levels, validation statuses, and artifact statuses are visible or trusted in a reader or runtime context.

Rollback and downgrade policies apply most critically to Runtime Packs, but SHOULD also apply to Exchange release pointers, federation manifests, authority registries, validation decisions, recognition records, and reader policies where stale or substituted versions could affect trust or visibility.

---

## Terminology mapping

To avoid ambiguity:

* **`release_id`**: the monotonic, channel-scoped version identifier used by a distribution channel.
* **`pack_version`**: the Runtime Pack’s monotonic version within a channel.
* **Runtime Pack release**: `release_id == pack_version`.
* **Exchange release pointer**: a channel-scoped pointer to a Working Exchange or Reference Exchange.
* **Reference pointer**: a pointer to an artifact recognized under a declared authority channel or reader policy.
* **Channel**: a distribution and activation context scoped by tenant, environment, region, audience, authority channel, and optionally reader policy.
* **Activation**: the local act of making a Runtime Pack or pointer active for a client, node, runtime, or reader policy.
* **Rollback**: an explicit, authorized activation of an older version.
* **Downgrade**: unauthorized activation or acceptance of an older version when a newer valid version is already known or active.
* **Reissue**: a signed, policy-authorized replacement of a pack or pointer using the same version label but a different content identity.
* **Hold state**: a non-activation state in which the client keeps the current active artifact and records why the candidate was not activated.
* **Quarantine state**: a state in which a candidate artifact is preserved for diagnostics or audit but cannot be activated under the active policy.

---

## Threat model

This policy defends against:

* a malicious distributor or compromised mirror serving old artifacts;
* a network attacker replaying older signed artifacts;
* offline caches or sync conflicts reactivating older Runtime Packs;
* operator mistakes pushing the wrong version to a region, audience, or channel;
* “same version, different bytes” substitution;
* trust-root confusion between tenants, environments, regions, audiences, or authority channels;
* reader-policy confusion, where a pack intended for one visibility policy is activated under another;
* stale authority registries, validation decisions, recognition records, or revocation lists;
* accidental use of a Working Exchange as if it were a Reference Exchange.

This policy assumes:

* signature verification exists for artifacts that declare signatures;
* trust roots are pinned per channel and can be verified offline;
* Runtime Pack distribution is offline-friendly;
* revocation data MAY or MAY NOT be available offline;
* clients may operate for long periods without network access;
* different reader policies may intentionally expose different subsets of validated, uncertain, disputed, fictional, mythological, research, or low-certainty material.

This policy does not assume that a valid signature means universal truth, universal validation, or maximum certainty.

---

## Cryptographic and integrity baseline

### Supported signature algorithms

An implementation MUST support:

* `ed25519`

An implementation MAY support additional algorithms through profiles, but such algorithms MUST NOT replace `ed25519` as the mandatory-to-implement baseline for Kristal v5 signature verification.

### Hashing baseline

Where a hash object is used, it MUST use:

```json
{
  "alg": "sha256",
  "value": "<hex>"
}
```

The field name MUST be `alg`, not `algo`.

### Canonicalization baseline

The default Kristal v5 canonicalization profile is:

```text
kristal.v5:jcs-rfc8785
```

RDF-specific integrity profiles MAY define additional canonicalization rules for RDF datasets, but they MUST NOT alter the core JSON artifact identity rules unless explicitly declared by that profile.

---

## Runtime Pack signing scope

A Runtime Pack MUST be distributable as an integrity-protected bundle.

At minimum:

* the Runtime Pack manifest MUST be signed when the channel policy requires signed packs;
* the Runtime Pack manifest MUST include hashes for all payload files it declares;
* consumers MUST verify declared payload file hashes when the active policy requires payload integrity;
* signatures MUST be excluded from the hash target;
* self-identity fields MUST be excluded from their own hash targets.

This ensures offline caches cannot silently substitute payload files while keeping the manifest identity or signature apparently valid.

---

## Required metadata for enforcement

### A. Runtime Pack identifiers

Each Runtime Pack bundle MUST be uniquely identified by:

* `runtime_pack_id`
* `runtime_pack_version`
* `pack_version`
* `source_exchange_ref`
* `source_artifact_status`
* `build.build_id`
* `channel_id`
* `content_hash`
* `signatures`, when required by policy

`source_artifact_status` MUST distinguish at least:

```text
working
reference
deprecated
revoked
```

A Runtime Pack derived from a Working Exchange MUST NOT be represented as derived from a Reference Exchange unless an authority recognition or validation decision supports that status.

---

### B. Channel and trust scoping

Packs MUST be distributed through channels scoped at minimum by:

* `tenant_id`
* `environment`

Channels SHOULD also declare:

* `region`
* `audience_segment`
* `authority_channel`
* `reader_policy_id`
* `scope.domain`
* `scope.subdomain`
* `distribution_purpose`

A client MUST NOT mix trust roots, version state, activation rules, reader policies, authority-channel rules, or rollback permissions across channels unless explicitly configured.

---

### C. Channel distribution index

Clients SHOULD consume a signed channel index as the primary “what to install or activate” control plane.

Example filename:

```text
pack_index.json
```

If present, the channel index MUST be verified using the channel’s pinned trust roots before it can satisfy any policy requiring a verified index.

A channel index SHOULD contain, at minimum:

* `channel_id`
* `tenant_id`
* `environment`
* optional `region`
* optional `audience_segment`
* optional `authority_channel`
* optional `reader_policy_id`
* `latest` pointer or pointers
* optional `pinned` pointer or pointers
* optional `minimum_allowed_version`
* optional `maximum_allowed_version`
* optional `revoked` list or reference to revocation artifacts
* optional staged pointers or cohorts
* optional `reissue_allowed`
* optional `reissue_flags`
* optional rollback authorization records or references
* `created_at`
* `expires_at`, recommended
* `content_hash`
* `signatures`

A channel index MUST NOT be used as authority recognition unless an authority-recognition policy explicitly defines that behavior.

---

### D. Offline revocation data

If an offline revocation artifact is provided, then clients MUST treat it as policy input for activation decisions.

Example artifact:

```text
revocations.json
```

If the active channel policy requires revocation checking and no acceptable revocation data is available offline, the client MUST NOT activate a candidate that depends on that revocation check.

The client MAY keep the current active pack and enter a hold state.

Recommended revocation metadata:

* `revocation_id`
* `target_ref`
* `target_level`
* `revocation_status`
* `authority_channel`
* `scope`
* `issued_at`
* `expires_at`
* `reason`
* `signatures`

---

### E. Timestamps and signatures

Timestamps such as `created_at`, `issued_at`, and `expires_at` MAY be present for audit, validity windows, and policy evaluation.

Timestamps MUST NOT affect content-addressed IDs unless a profile explicitly includes them in the identity target.

Signature and attestation material MUST be excluded from hash targets wherever it appears.

---

## Monotonic version formats

An implementation MUST choose one monotonic scheme and enforce it consistently per channel.

Allowed schemes:

* integer sequence, recommended;
* semantic version with strict deterministic ordering rules;
* hybrid integer sequence plus human label.

Examples:

```text
42
43
44
```

```text
5.0.0+channel.42
5.0.0+channel.43
```

Comparison MUST be deterministic and documented.

A version string MUST NOT be compared lexically unless the chosen scheme explicitly defines lexical ordering as valid.

---

## Client state requirements

Clients MUST persist per channel:

* `highest_activated_pack_version[channel]`
* `highest_seen_pack_version[channel]`
* `current_active_pack_version[channel]`
* `current_active_runtime_pack_id[channel]`
* `current_reader_policy_id[channel]`, when applicable
* `current_authority_channel[channel]`, when applicable
* last successful identity verification metadata
* last successful signature verification metadata
* last successful index verification metadata
* last revocation-check status
* last activation decision
--- CHUNK END ---

--- CHUNK BEGIN ---
id=837756bce0f3:351-700
start=351
end=700
----
* rollback authorization state, if applicable

Clients SHOULD also persist:

* `highest_seen_release_id[channel]`
* `last_reference_exchange_id[channel]`
* `last_working_exchange_id[channel]`
* `last_authority_registry_id[channel]`
* `last_reader_policy_hash[channel]`
* correlation IDs for activation, rollback, and rejection events

Client state MUST be scoped by channel. It MUST NOT be globally reused across unrelated tenants, environments, regions, audiences, authority channels, or reader policies.

---

## Client enforcement rules

### 1. Basic rule: never activate a lower version without authorization

A client MUST NOT activate a Runtime Pack with a lower `pack_version` than the highest previously activated version in the same channel unless an explicit rollback authorization permits it.

A client SHOULD NOT activate a Runtime Pack lower than `highest_seen_pack_version[channel]` unless:

* a rollback authorization permits it; or
* a policy explicitly allows activation from cache under a constrained offline mode.

---

### 2. Verification before activation

Before switching active packs, clients MUST evaluate the checks required by the active channel policy.

Depending on policy, checks MAY include:

* channel index signature verification;
* Runtime Pack manifest signature verification;
* Runtime Pack payload hash verification;
* source Exchange identity verification;
* source Exchange status check;
* authority registry verification;
* authority recognition verification;
* validation decision verification;
* reader policy verification;
* revocation status check;
* version monotonicity check;
* rollback authorization check;
* reissue authorization check.

If a required check is not satisfied, the candidate MUST NOT be activated under that policy.

The client MAY preserve, inspect, cache, or quarantine the candidate if policy allows.

---

### 3. Atomic activation

Activation MUST be an atomic switch from old pack to new pack.

A client MUST NOT partially activate a Runtime Pack.

If activation fails after verification but before completion, the previous active pack SHOULD remain active.

If the previous active pack is unavailable, the client SHOULD enter hold state or recovery state according to deployment policy.

---

### 4. Channel isolation

Downgrade and rollback decisions MUST be scoped by channel.

At minimum, channel scope includes:

```text
tenant_id
environment
```

When present, the following MUST also participate in channel isolation:

```text
region
audience_segment
authority_channel
reader_policy_id
scope.domain
scope.subdomain
```

A client MUST NOT activate a pack from one channel into another channel unless a signed channel policy explicitly allows cross-channel use.

---

### 5. Equal version, different identity

If a client receives a pack with the same `pack_version` but a different `runtime_pack_id`, the client MUST treat this as a substitution conflict unless an explicit reissue authorization is present in a verified channel index or equivalent signed policy artifact.

Reissue authorization MUST bind:

* `channel_id`
* `pack_version`
* previous `runtime_pack_id`, if known
* allowed replacement `runtime_pack_id`
* reason
* issuer
* issued_at
* optional `expires_at`
* signatures

Clients MUST log reissue activations.

Clients MUST NOT silently accept same-version identity changes.

---

### 6. Revocation-aware blocking

If a verified channel index includes a `revoked` list or references a revocation artifact, clients MUST NOT activate any target revoked under the active channel policy.

If `minimum_allowed_version` is present in a verified index, clients MUST NOT activate packs below that minimum unless an explicit rollback authorization overrides the minimum and the policy allows that override.

If a source Exchange, Runtime Pack, validation decision, authority recognition, reader policy, or key is revoked, the client MUST evaluate the revocation according to active policy before activation.

---

### 7. Reader policy compatibility

A Runtime Pack MAY be built for a specific reader policy or set of reader policies.

If the Runtime Pack declares `reader_policy_refs`, a client MUST NOT activate it under an incompatible reader policy unless a compatibility policy explicitly allows it.

A Runtime Pack built for a permissive research or creative policy MUST NOT be activated as a strict `reference_only` or `validated_only` pack unless the pack also satisfies that stricter policy.

A Runtime Pack built for `validated_only` view MAY contain assertions validated at different certainty levels, provided every visible assertion satisfies the active reader policy.

---

### 8. Authority-channel compatibility

If a Runtime Pack, Exchange, shard, federation, recognition, or validation decision declares an `authority_channel`, the client MUST evaluate whether that channel is allowed by the active distribution or reader policy.

Recognition by one authority channel MUST NOT be treated as recognition by another authority channel unless an authority-recognition relationship explicitly supports that interpretation.

---

### 9. Working versus reference artifacts

A Runtime Pack derived from a Working Exchange MAY be activated under research, review, diagnostic, archival, or creative policies if allowed.

A Runtime Pack derived from a Working Exchange MUST NOT be activated as a Reference Exchange Runtime Pack under a strict reference policy unless a recognized authority channel or validation policy supports that status.

Clients SHOULD expose whether the active pack is derived from:

```text
working_exchange
reference_exchange
mixed_federation
research_bundle
archival_bundle
```

---

## Policy-authorized rollback

Rollback is operationally necessary but MUST be explicit and signed when it crosses monotonic version boundaries.

### Rollback authorization record

A rollback MUST be authorized by a signed rollback authorization record, either embedded in the channel index or distributed alongside it.

The record MUST contain:

* `rollback_authorization_id`
* `channel_id`
* `authorized_rollback_to_pack_version`
* optional `target_runtime_pack_id`, recommended
* `reason`
* `issued_at`
* optional `expires_at`, recommended
* `issuer`
* `authority_channel`, if applicable
* `reader_policy_id`, if applicable
* `scope`, if applicable
* signatures by an authority key or deployment key accepted by the channel policy

Clients MUST:

* verify authorization signature;
* ensure the authorization is within the required validity window when the policy enforces expiry;
* ensure the rollback target is not revoked or blocked by active policy;
* ensure the rollback target matches the authorized identity if `target_runtime_pack_id` is specified;
* record that rollback occurred.

### Rollback activation state

When rollback authorization is present, clients MAY activate the rollback target even if it is lower than the highest previously activated version.

Clients MUST:

* keep `highest_seen_pack_version[channel]` unchanged;
* preserve evidence that a newer release was seen;
* record `current_active_pack_version[channel]` separately from `highest_activated_pack_version[channel]`;
* log rollback activation with reason and authorization reference.

Clients SHOULD set a rollback mode marker until a newer non-rollback release is activated.

---

## Emergency rollback

Emergency rollback MAY be used when a current pack, key, validation decision, authority recognition, reader policy, or source Exchange is compromised, unsafe, revoked, or operationally broken.

Emergency rollback SHOULD prefer one of the following:

1. a new higher `pack_version` containing the corrective content;
2. a signed reissue of the same `pack_version`, if reissue is allowed;
3. a rollback to an older pack authorized by a signed rollback record.

If a key compromise occurs, rollback to an older pack is allowed only if:

* the older pack was signed by keys still trusted under the active policy; or
* the active policy explicitly recognizes an emergency trust path;
* revocation policy does not invalidate the older pack;
* the rollback authorization itself is verifiable.

Clients SHOULD prefer a new higher `pack_version` over rollback whenever feasible.

---

## Offline and sync edge cases

### Offline clients without index updates

If a client is offline and only has cached artifacts, it MUST NOT activate a lower `pack_version` than previously active in that channel unless a cached rollback authorization is present and valid under the active policy.

If only an older pack is available and no valid rollback authorization exists, the client SHOULD enter hold state rather than silently downgrading.

The client MAY continue using the current active pack if policy allows.

The client SHOULD record that no acceptable newer or rollback-authorized pack was available.

---

### Offline revocation uncertainty

If revocation data is unavailable offline:

* if the active policy requires current revocation data, the candidate MUST NOT be activated;
* if the active policy allows stale or unavailable revocation data, the activation decision MAY proceed with status labels indicating revocation was not fully checked.

Recommended revocation-check statuses:

```text
not_checked
not_revoked
revoked
unknown
unavailable_offline
stale
not_applicable
```

---

### Sync conflicts

When Orgo, Konnaxion, device sync, mirror sync, or operator workflows introduce conflicting current pointers, the client MUST choose the highest valid `pack_version` according to channel rules unless rollback authorization exists.

Conflicts SHOULD be logged with correlation IDs.

If conflict resolution cannot be completed safely under policy, the client SHOULD enter hold state.

---

### Stale authority registry

If a Runtime Pack or Exchange depends on an Authority Registry that is older than the active policy allows, the client MUST NOT activate the candidate under policies requiring fresh authority registry data.

If policy allows stale authority registry data, the client MAY activate with status labels indicating the registry freshness state.

---

### Reader policy drift

If a Runtime Pack was produced under one reader policy but a client attempts to activate it under another, the client MUST evaluate compatibility.

If compatibility cannot be proven, activation MUST NOT proceed under the new reader policy.

---

## Operational rollout patterns

Recommended rollout patterns include:

* **Canary releases**: channel index lists cohorts or staged pointers; clients still gate activation locally with verification, version checks, and policy checks.
* **Blue/green**: clients keep active and standby slots; activation is atomic after checks pass.
* **Staged rollouts**: progressively advance `latest` or cohort pointers in the signed channel index.
* **Pinned reference releases**: clients remain on a selected Reference Exchange or Runtime Pack until the active authority channel advances the pointer.
* **Research channel releases**: clients may consume Working Exchanges or lower-certainty material under explicit research reader policies.
* **Emergency channel override**: a constrained channel policy temporarily permits rollback, reissue, or pinning.

---

## Logging and observability

Clients and distributors SHOULD emit structured events.

Recommended events:

```text
PACK_CANDIDATE_SEEN
PACK_IDENTITY_VERIFIED
PACK_SIGNATURE_VERIFIED
PACK_PAYLOAD_HASHES_VERIFIED
PACK_POLICY_SATISFIED
PACK_POLICY_NOT_SATISFIED
PACK_REJECTED
PACK_HELD
PACK_QUARANTINED
PACK_ACTIVATED
DOWNGRADE_BLOCKED
ROLLBACK_AUTH_ACCEPTED
ROLLBACK_AUTH_REJECTED
ROLLBACK_ACTIVATED
REISSUE_ACCEPTED
REISSUE_REJECTED
REVOCATION_BLOCKED
AUTHORITY_CHANNEL_MISMATCH
READER_POLICY_MISMATCH
REFERENCE_STATUS_MISMATCH
```

Recommended event fields:

* `runtime_pack_id`
* `pack_version`
* `source_exchange_ref`
* `source_artifact_status`
* `build_id`
* `channel_id`
* `tenant_id`
* `environment`
* `region`
* `audience_segment`
* `authority_channel`
* `reader_policy_id`
* `signer_key_id`
* `verification_status`
* `revocation_status`
* `activation_status`
--- CHUNK END ---

--- CHUNK BEGIN ---
id=837756bce0f3:701-902
start=701
end=902
----
* `reason_code`
* `device_id` or `node_id`
* `correlation_id`

---

## Reason codes

Implementations SHOULD use stable reason codes.

Recommended reason codes:

```text
schema_valid
schema_invalid
identity_verified
identity_mismatch
signature_valid
signature_invalid
missing_signature
missing_key
unsupported_alg
hash_valid
hash_invalid
payload_hash_mismatch
trust_root_missing
trust_root_mismatch
authority_recognized
authority_not_recognized
authority_channel_mismatch
reader_policy_satisfied
reader_policy_not_satisfied
reader_policy_mismatch
validation_policy_satisfied
validation_policy_failed
version_monotonic
downgrade_blocked
rollback_authorized
rollback_not_authorized
rollback_expired
rollback_target_revoked
reissue_authorized
reissue_not_authorized
same_version_identity_conflict
revocation_checked
revocation_unavailable
revoked_by_authority_channel
minimum_version_blocked
source_status_mismatch
working_not_allowed_by_policy
reference_required_by_policy
activation_succeeded
activation_blocked
held_for_policy
quarantined_for_diagnostics
```

---

## Minimum acceptance criteria

A deployment satisfies this policy if:

1. Clients persist per-channel highest seen, highest activated, and current active versions.
2. Clients block downgrades unless an explicit signed rollback authorization permits them.
3. Rollbacks require explicit signed authorization.
4. “Same version but different identity” is rejected unless explicitly authorized by a signed reissue policy.
5. Required identity, signature, payload-hash, trust-root, reader-policy, authority-channel, and revocation checks are evaluated before activation.
6. Trust roots are pinned or bundled for offline verification.
7. Offline clients hold rather than silently downgrading when no valid rollback authorization exists.
8. Runtime Pack integrity covers declared payload files.
9. Working Exchange packs are not activated as Reference Exchange packs unless recognition or validation policy supports that status.
10. Reader policy and authority-channel scope are preserved during activation.
11. Verification, validation, recognition, certainty, and reader visibility remain distinct in logs and APIs.

---

## Conformance tests

A conforming implementation MUST provide fixtures demonstrating:

* normal activation of a higher valid `pack_version`;
* downgrade blocked without rollback authorization;
* rollback accepted with valid signed authorization;
* rollback rejected with expired authorization;
* rollback rejected when target pack is revoked;
* same version and same identity accepted;
* same version and different identity rejected without reissue authorization;
* same version and different identity accepted with valid reissue authorization;
* identity mismatch blocked by policy;
* payload hash mismatch blocked by policy;
* missing required signature blocked by policy;
* unsupported required algorithm blocked by policy;
* missing trust root blocked by policy;
* stale or unavailable revocation data handled according to policy;
* activation under matching reader policy;
* activation blocked under incompatible reader policy;
* activation under matching authority channel;
* activation blocked under authority-channel mismatch;
* Working Exchange pack allowed in research mode;
* Working Exchange pack blocked in reference-only mode;
* Reference Exchange pack activated under a matching reference policy;
* offline cached older pack held rather than silently activated;
* sync conflict resolved by highest valid version;
* sync conflict held when no valid policy resolution exists.

Conformance tests SHOULD include:

* tenant-scoped channels;
* environment-scoped channels;
* region-scoped channels;
* audience-segment-scoped channels;
* authority-channel-scoped trust roots;
* reader-policy-scoped activation;
* signed channel indexes;
* offline revocation artifacts;
* authority registry updates;
* validation decision references;
* authority recognition references;
* Runtime Packs derived from federations;
* Runtime Packs derived from shards.

---

## Security and correctness considerations

Implementations SHOULD defend against:

* replay of old signed artifacts;
* mirror compromise;
* stale cache activation;
* same-version substitution;
* trust-root substitution;
* authority-channel confusion;
* reader-policy confusion;
* stale authority registry use;
* stale or missing revocation data;
* rollback authorization reuse outside its scope;
* expired rollback authorization;
* cross-tenant or cross-environment activation;
* treating a Working Exchange as a Reference Exchange;
* treating a valid signature as universal validation;
* treating authority recognition from one channel as recognition by another;
* hiding downgrade or rollback decisions from logs;
* partial Runtime Pack activation;
* non-deterministic version comparison.

User interfaces and APIs SHOULD avoid ambiguous labels such as:

```text
safe
official
canonical
true
trusted
```

unless they are scoped by:

```text
authority_channel
reader_policy
validation_status
recognition_status
certainty_level
artifact_status
```

Preferred labels include:

```text
identity verified
signature verified
payload verified
recognized by <authority channel>
reference under <reader policy>
validated as <status>
not activated
held by policy
rollback authorized
downgrade blocked
reader-policy mismatch
authority-channel mismatch
revoked
```

---

## Open questions

The following profile decisions remain open:

* Whether `pack_version` is global per tenant or strictly per channel, region, and audience segment.
* Whether a signed channel index is required in all production environments.
* Whether revocation artifacts are mandatory for production channels.
* What freshness rules should apply to offline revocation artifacts.
* Whether reader policies must be signed before being bundled into Runtime Packs.
* Whether authority registries must use monotonic versions similar to Runtime Packs.
* Whether rollback authorization should always require expiry.
* Whether emergency rollback should require dual signatures from operations and authority-channel owners.
* Whether Runtime Packs derived from federations require additional shard-level rollback metadata.
* Whether Reference Exchange pointers and Runtime Pack pointers should share one channel index format or use separate indexes.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/07-security/key-management-and-trust-roots.md"
id=54d15f4aa834
kind=markdown
size=24924
lines=725
line_ref=1-725
chunks=3
chunk_refs=1-350,351-700,701-725
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=54d15f4aa834:1-350
start=1
end=350
----
# Key Management and Trust Roots (Kristal v5)

## Status

Draft — implementation-ready defaults; future profiles may extend.

## Purpose

This document defines how Kristal v5 artifacts are signed, how trust roots are established, how authority channels are anchored, and how verifiers validate signatures, hashes, revocations, and signing scopes when integrity declarations are present.

This document is security and operations focused. It does **not** change Kristal’s core content-addressed identity rules. It defines the trust model around distribution, verification, authority recognition, Runtime Pack activation, and offline use.

Kristal v5 separates:

* artifact integrity;
* authority recognition;
* validation status;
* certainty level;
* reader policy;
* runtime activation.

A signed artifact is not automatically true, validated, or recognized by every authority. A signature proves that a signer, key, or authority channel made or approved a declared artifact under a declared scope.

## Scope

In scope:

* key types and roles;
* supported signature algorithms;
* trust root pinning models;
* authority-channel trust roots;
* signature verification requirements for distributors and clients;
* signing targets for Exchange artifacts, Runtime Packs, Authority Registries, Validation Decisions, and Recognition artifacts;
* rotation, revocation, and compromise handling;
* minimum manifest fields for signer identity and key metadata;
* Runtime Pack signing scope;
* offline verification requirements.

Out of scope:

* network PKI / CA integration details, which may be deployment-specific;
* secrets storage implementation, such as HSM, KMS, or local secure enclaves;
* authority governance process outside the machine-readable trust model;
* semantic validation of claims;
* reader-policy selection.

## Normative keywords

The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as normative requirements.

---

# 1. Design goals

Kristal v5 key management has the following design goals:

* **Integrity enforcement:** when signatures, hashes, trust roots, or revocation requirements are declared, verifiers enforce them according to policy.
* **Authority pluralism:** different authority channels may use different trust roots and policies.
* **Scoped recognition:** recognition by one authority channel does not imply recognition by another.
* **Tenant isolation:** tenants may use independent trust roots and keys.
* **Offline viability:** verification should be possible without network access.
* **Operational safety:** rotation, rollback prevention, and compromise response are first-class.
* **Label preservation:** signature verification must not erase validation status, certainty level, scope, or authority-channel information.

---

# 2. Supported signature algorithms

## 2.1 Baseline

Verifiers MUST support:

* `ed25519`

Artifacts SHOULD prefer `ed25519` when available.

## 2.2 Compatibility

Verifiers MAY support:

* `rsa-pss-sha256`

Deployments MUST document which compatibility algorithms are enabled.

Compatibility algorithms MUST NOT silently weaken trust decisions. If a deployment restricts certain algorithms to specific authority channels, environments, or artifact types, those restrictions MUST be explicit in policy.

---

# 3. Key roles

## 3.1 Trust Root

A trust root is a long-lived key or root set that anchors trust for a tenant, environment, authority channel, or registry.

Requirements:

* Trust roots MUST be pin-able by distributors and clients.
* Trust roots SHOULD be offline or highly protected.
* Trust roots SHOULD NOT sign ordinary artifacts directly.
* Trust roots SHOULD sign intermediates, authority registry updates, revocation lists, or root-transition attestations.
* Trust roots MUST be scoped by tenant, environment, authority channel, or deployment policy.

## 3.2 Intermediate / Release Authority Key

An intermediate key is a medium-lived key used to sign artifact signing keys, release signing certificates, validation decision keys, or recognition attestations.

Requirements:

* Intermediates MUST be signed by a trust root or another valid intermediate under declared policy.
* Intermediates MUST include validity windows.
* Intermediates SHOULD be rotated on a scheduled basis.
* Intermediates MUST declare their permitted scope.

Permitted scope may include:

* tenant;
* environment;
* artifact type;
* authority channel;
* validation policy;
* recognition policy;
* Runtime Pack profile;
* publication channel.

## 3.3 Artifact Signing Key

An artifact signing key is a shorter-lived key used to sign Kristal artifacts.

Artifact signing keys MAY sign:

* Exchange artifacts;
* Runtime Pack manifests;
* Authority Registries;
* Validation Decisions;
* Authority Recognition artifacts;
* revocation lists;
* transparency log entries;
* release bundles.

Requirements:

* Signing keys MUST be scoped.
* Signing keys SHOULD be rotated regularly.
* Signing keys MUST be auditable.
* Signing keys MUST have stable `key_id` values.
* Signing keys MUST NOT be used outside their declared scope.

## 3.4 Authority Channel Signing Key

An authority channel signing key is a key authorized to sign on behalf of a declared authority channel.

It may sign:

* validation decisions;
* recognition decisions;
* authority-channel metadata;
* scope declarations;
* policy declarations;
* delegated authority attestations.

Requirements:

* The key MUST be linked to an `authority_channel_id`.
* The key MUST be included in or referenced by the Authority Registry.
* The key MUST only sign decisions within its declared scope.
* A verifier MUST NOT treat an authority-channel signature as universal recognition outside its scope.

## 3.5 Runtime Pack Signing Key

A Runtime Pack signing key signs deployable offline packages.

Requirements:

* The key MUST be scoped to Runtime Pack signing.
* The signing target MUST include the Runtime Pack manifest and referenced file integrity.
* The signature MUST preserve source artifact status.
* A Runtime Pack signature MUST NOT imply that a working artifact is a reference artifact.

---

# 4. Trust models

## 4.1 Tenant-pinned trust roots

Each tenant has its own trust root or root set. Clients pin the tenant’s root fingerprints.

Advantages:

* strong tenant isolation;
* offline verification;
* reduced blast radius.

This model is recommended for multi-tenant deployments.

## 4.2 Environment-pinned trust roots

A deployment pins roots by environment, such as development, staging, or production. Tenants are separated by access control and authority registry policy rather than by separate roots.

Advantages:

* simpler operation for small deployments;
* offline verification.

Risk:

* larger blast radius if the root is compromised.

## 4.3 Authority-channel trust roots

Each authority channel may declare its own trust roots.

Examples:

* `authority:wikidata-seed`;
* `authority:who`;
* `authority:unesco-global-reference`;
* `authority:microsoft-systems`;
* `authority:local-research-collective`.

Requirements:

* Authority-channel trust roots MUST be declared in or referenced by an Authority Registry.
* Recognition by an authority channel MUST be scoped.
* Recognition by one authority channel MUST NOT imply recognition by another authority channel.
* Delegated authority MUST be explicit.

## 4.4 Hybrid trust roots

A deployment MAY combine tenant, environment, and authority-channel roots.

If hybrid trust roots are used, the Authority Registry or deployment policy MUST make precedence and scope explicit.

---

# 5. Authority Registry

Deployments SHOULD maintain a pinned, versioned **Authority Registry** artifact.

An Authority Registry defines:

* active, deprecated, and blocked trust roots;
* authority channels;
* authority-channel scopes;
* allowed signing keys;
* validation policies;
* recognition policies;
* delegation rules;
* revocation list references;
* required profiles;
* minimum signature requirements.

When present, distributors and clients SHOULD treat the Authority Registry as the policy input for verification, validation recognition, and authority-channel trust decisions.

The Authority Registry does not make all contained claims true. It defines which authorities, keys, policies, and scopes are accepted for a particular verification or recognition decision.

---

# 6. Artifact signature requirements

## 6.1 When signatures are present

If an artifact declares signatures, verifiers MUST:

1. Validate the signature against the artifact’s declared signing target.
2. Validate the signing target against the artifact’s canonical hashing rules.
3. Validate signer identity.
4. Validate signer scope.
5. Validate the key chain to a pinned trust root or Authority Registry root.
6. Enforce validity windows.
7. Enforce revocation policy when applicable.
8. Enforce downgrade and rollback policy when applicable.
9. Preserve validation, certainty, scope, and authority-channel labels.

If any required step fails, the artifact MUST NOT be accepted for the requested trust decision.

A failed signature verification MAY still allow inspection of the artifact in a diagnostic, forensic, research, or untrusted view, provided the artifact is clearly marked as not accepted under the requested trust policy.

## 6.2 What a signature proves

A valid signature proves that the declared signer signed the declared signing target under a declared key and scope.

A valid signature does not, by itself, prove:

* that all assertions are true;
* that all assertions are high certainty;
* that an artifact is recognized by every authority;
* that a working artifact is a reference artifact;
* that a Runtime Pack contains the full source artifact;
* that a reader policy should include the artifact by default.

Those decisions require validation policy, recognition policy, scope, authority channel, and reader policy.

---

# 7. Signing targets

The signed payload MUST be the canonical hash of the artifact’s declared hash target, excluding signatures themselves.

The signing target MUST be unambiguous and recorded in the artifact or manifest.

## 7.1 Exchange artifacts

For Exchange artifacts:

* The signing target MUST be the canonical hash of the Exchange identity payload.
* The signing target MUST exclude `signatures`.
* The manifest MUST make it unambiguous how the payload hash was computed.
* The signature MUST preserve `artifact_status`, such as `working` or `reference`.

A signature over a `working_exchange` MUST NOT be interpreted as recognition of a `reference_exchange`.

## 7.2 Runtime Packs

For Runtime Packs, the signing target MUST cover:

1. the canonical hash of the Runtime Pack manifest, excluding signatures;
2. the integrity of all referenced payload files as recorded in the manifest;
3. the declared source artifact references;
4. the declared Runtime Pack policies;
5. the declared reader-policy materialization, if any;
6. the declared validation, certainty, or authority-channel materialization, if any.

A Runtime Pack manifest MUST include hashes for every payload file it references.

The pack signature MUST be computed over the manifest that includes those hashes.

Manifest-only signing MAY exist only as a deployment-specific profile. It MUST NOT be the default.

## 7.3 Authority Registry

For Authority Registries:

* The signing target MUST include trust roots.
* The signing target MUST include authority channels.
* The signing target MUST include validation policies.
* The signing target MUST include recognition policies.
* The signing target MUST include revocation list references.
* The signing target MUST exclude registry signatures.

A verifier MUST NOT apply an Authority Registry whose signature target is ambiguous.

## 7.4 Validation Decisions

For Validation Decisions:

* The signing target MUST include the target reference.
* The signing target MUST include target level.
* The signing target MUST include validation status.
* The signing target MUST include `validated_as`.
* The signing target MUST include certainty level.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=54d15f4aa834:351-700
start=351
end=700
----
* The signing target MUST include authority channel.
* The signing target MUST include validation policy reference.
* The signing target MUST include scope.
* The signing target MUST exclude signatures.

A Validation Decision MUST NOT be interpreted outside its declared scope.

## 7.5 Authority Recognition artifacts

For Authority Recognition artifacts:

* The signing target MUST include issuer authority channel.
* The signing target MUST include target reference.
* The signing target MUST include target level.
* The signing target MUST include recognition status.
* The signing target MUST include recognized-as status.
* The signing target MUST include scope.
* The signing target MUST include recognition or validation policy references.
* The signing target MUST exclude signatures.

Recognition by one authority channel MUST NOT be treated as recognition by another unless explicit delegation or recognition exists.

## 7.6 Revocation lists

For revocation lists:

* The signing target MUST include revoked key IDs or artifact IDs.
* The signing target MUST include reasons.
* The signing target MUST include effective timestamps.
* The signing target MUST include issuer identity.
* The signing target MUST exclude signatures.

Revocation lists SHOULD be signed by a trust root or authorized intermediate.

---

# 8. Recommended signature envelope fields

Signed artifacts SHOULD include a `signatures[]` section in a manifest-like structure with:

* `sig_id`;
* `alg`;
* `key_id`;
* `signer`;
* `signer_type`;
* `authority_channel_id`, if applicable;
* `created_at`;
* `expires_at`, if applicable;
* `scope`, if applicable;
* `payload_hash`;
* `signature`;
* `chain`, if applicable;
* `policy_refs`, if applicable.

Recommended shape:

```json
{
  "sig_id": "sig:example",
  "alg": "ed25519",
  "key_id": "key:example",
  "signer": "Example Authority",
  "signer_type": "authority_channel",
  "authority_channel_id": "authority:example",
  "created_at": "2026-01-01T00:00:00Z",
  "expires_at": "2027-01-01T00:00:00Z",
  "scope": {
    "domain": "science"
  },
  "payload_hash": {
    "alg": "sha256",
    "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "signature": "base64url-or-multibase-signature",
  "chain": [],
  "policy_refs": []
}
```

Exact envelope shape is implementation-defined, but all required semantic fields MUST be representable.

Fields used for signature verification MUST NOT be ambiguous.

---

# 9. Trust root pinning and distribution

## 9.1 Pins

A pin is a stable fingerprint of a trust root public key.

Requirements:

* Pins MUST be distributed to clients out-of-band or via a secure bootstrap channel.
* Pins MUST be stored and enforced locally for offline verification.
* Pins SHOULD support multiple active roots to enable rotation.
* Pins SHOULD be associated with tenant, environment, and authority-channel scope.

## 9.2 Pin sets

Clients and distributors SHOULD support pin sets:

* `active_roots[]`;
* `deprecated_roots[]`;
* `blocked_roots[]`.

Policies around acceptance of deprecated roots MUST be documented.

Blocked roots MUST NOT be accepted for new trust decisions.

## 9.3 Offline pinning

Clients that operate offline MUST have access to the required pins, Authority Registry, and revocation data needed by the active policy.

If the active policy requires a trust root or registry that is unavailable, the client MUST NOT represent the artifact as accepted under that policy.

---

# 10. Authority delegation

Authority channels MAY recognize other authority channels.

Examples:

* an international organization recognizes a domain-specific authority;
* a government recognizes a national statistical office;
* a university recognizes a laboratory;
* a standards body recognizes a working group;
* a company recognizes a product documentation signing authority.

Delegation requirements:

* Delegation MUST be explicit.
* Delegation MUST be scoped.
* Delegation MUST declare the delegating authority channel.
* Delegation MUST declare the delegated authority channel.
* Delegation MUST declare the target domain or subdomain.
* Delegation MUST declare whether delegation is transitive.
* Delegation MUST be revocable.

Recognition of an authority channel does not imply universal recognition of all artifacts published by that channel. The applicable validation and recognition policies still apply.

---

# 11. Key rotation

## 11.1 Planned rotation

Trust roots rotate rarely and require careful migration.

Intermediates rotate periodically.

Signing keys rotate frequently.

Rotation requirements:

* Rotation MUST support overlap windows.
* Clients MUST support multiple pinned roots or intermediates during overlap.
* Artifacts SHOULD record which `key_id` signed them.
* Rotation events SHOULD be recorded in operational logs.
* Authority Registries SHOULD reflect current key status.

## 11.2 Emergency rotation

On compromise:

* mark affected key IDs as revoked;
* stop issuing new artifacts signed by the compromised key;
* re-issue current artifacts or packs signed with new keys when needed;
* update Authority Registries;
* update revocation lists;
* apply downgrade and rollback protections;
* publish operational notice through the appropriate distribution channel.

If an artifact was signed by a compromised key, verifiers MUST apply the active revocation and rollback policy.

---

# 12. Revocation

Because clients may be offline, revocation must work without live OCSP or online CRLs.

## 12.1 Recommended approach

Maintain signed revocation list artifacts per tenant, environment, authority channel, or registry scope.

A revocation list SHOULD contain:

* revoked `key_id` values;
* revoked artifact IDs, if applicable;
* revoked authority-channel IDs, if applicable;
* reasons;
* effective timestamps;
* issuer;
* scope;
* signatures.

Revocation lists SHOULD be:

* content-addressed;
* signed;
* versioned;
* distributed alongside Runtime Packs or through Orgo/Konnaxion sync channels.

## 12.2 Client behavior

Clients MUST consult the latest available revocation list before accepting a signature when a revocation list is present and applicable.

If policy requires revocation checking and no revocation list is available, the client MUST NOT accept the artifact under that policy.

Deployments MUST define the revocation policy level per environment.

Example policy levels:

* `ignore`;
* `require_if_present`;
* `require_strict`.

## 12.3 Revocation effects

A revoked key MUST NOT be accepted for new trust decisions after the revocation effective time.

A revoked authority channel MUST NOT be treated as recognized after the revocation effective time.

A revoked artifact MUST NOT be presented as accepted under the affected authority channel or policy.

Revocation does not necessarily delete historical records. It changes their current trust status.

---

# 13. Downgrade and rollback protection

Kristal deployments MUST protect Runtime Pack activation from downgrade and rollback attacks.

Requirements:

* Runtime Packs SHOULD include monotonic version or sequence metadata.
* Activation policy MUST compare candidate packs against the currently active pack.
* A candidate pack signed by revoked keys MUST NOT replace a valid active pack.
* A candidate pack with an older sequence MUST NOT replace a newer pack unless an explicit rollback policy allows it.
* Rollbacks MUST preserve audit records.
* Rollbacks SHOULD require explicit authority or operator action.

A Runtime Pack that fails activation requirements MAY still be inspected as an inactive candidate if the reader clearly marks it as not active under the selected policy.

---

# 14. Verification responsibilities by component

## 14.1 Orgo — control plane

Orgo MUST record:

* build ID;
* artifact IDs;
* signer `key_id`;
* signature metadata;
* validation decision references;
* authority recognition references;
* release status;
* publication status;
* activation status when applicable.

Orgo SHOULD:

* enforce “no publish without required signatures” in environments where signatures are required;
* manage rotation schedules;
* manage revocation list publication;
* publish or update Authority Registries;
* record operational audit trails;
* preserve distinction between working artifacts and reference artifacts.

## 14.2 Konnaxion — distribution and client UX

Konnaxion MUST:

* verify signatures when present and required by policy before activating a Runtime Pack;
* pin trust roots per tenant, environment, or Authority Registry policy;
* enforce rollback and downgrade policy;
* preserve artifact status;
* expose validation, certainty, authority, and reader-policy labels where applicable.

Konnaxion MUST NOT present a Runtime Pack as accepted under an authority channel unless the applicable trust, validation, and recognition requirements are satisfied.

## 14.3 Architect — renderer

Architect SHOULD verify that inputs satisfy the active reader policy before rendering.

Architect MUST preserve:

* validation labels;
* certainty labels;
* authority labels;
* disputed status;
* fictional or mythological scope;
* provenance traceability.

Architect MUST NOT flatten scoped validation into universal truth.

Architect does not need to re-sign artifacts unless it produces distributable outputs.

## 14.4 SenTient — resolver

SenTient is not typically a signer.

SenTient MAY sign resolver outputs if the deployment treats resolver output as a distributable artifact.

If SenTient signs outputs, those signatures MUST declare scope and target.

## 14.5 Kristal compiler

The Kristal compiler MUST produce deterministic artifact identity and hashing outputs according to the declared canonicalization and reproducibility profiles.

The compiler MAY produce working artifacts before validation decisions are complete.

Compiler output signatures prove compiler output identity and integrity. They do not imply authority recognition unless a recognized authority channel signs or recognizes the artifact.

---

# 15. Minimum security acceptance criteria

A deployment meets minimum Kristal v5 security criteria if:

1. Signed artifacts are verified according to their declared signing target.
2. Trust roots are pinned and enforceable offline.
3. Authority channels are scoped and auditable.
4. Key rotation is supported.
5. Revocation list distribution exists for environments where revocation is required.
6. Downgrade and rollback protection is implemented for Runtime Pack activation.
7. Signature verification preserves artifact status, validation status, certainty level, scope, and authority-channel labels.
8. A valid signature is not treated as universal truth, universal validation, or universal recognition.
9. Runtime Packs do not erase whether they derive from working artifacts or reference artifacts.
10. Reader policies remain explicit and inspectable.

---

# 16. Optional profiles

Future optional profiles MAY define:

* transparency logs;
* append-only release ledgers;
* threshold signatures;
* multi-authority recognition;
* hardware-backed signing;
* remote attestation;
* authority-channel delegation graphs;
* policy-specific revocation models;
* audit bundle formats.

--- CHUNK END ---

--- CHUNK BEGIN ---
id=54d15f4aa834:701-725
start=701
end=725
----
Transparency logs are recommended for environments that require strong auditability, compromise detection, or public accountability.

---

# 17. Summary

Kristal v5 key management protects artifact identity, signing authority, policy scope, and offline verification.

It does not create a universal truth authority.

A signed artifact means:

> This signer signed this target, under this key, within this declared scope.

A recognized artifact means:

> This authority channel accepts this target under this recognition policy and scope.

A validated assertion means:

> This authority channel accepts this assertion as a specific kind of claim, at a declared certainty level, under a declared validation policy and scope.

These meanings MUST remain separate.

Integrity protects artifacts. Authority is plural. Recognition is scoped. Certainty remains explicit.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/07-security/multi-tenancy-boundaries.md"
id=8e02d62cc0eb
kind=markdown
size=22037
lines=575
line_ref=1-575
chunks=2
chunk_refs=1-350,351-575
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=8e02d62cc0eb:1-350
start=1
end=350
----
# Multi-tenancy Boundaries (Global Content IDs + Tenant Access Control Layering)

## Status

Draft

## Purpose

Define the multi-tenancy boundary model for Kristal v5 so that:

* IDs remain globally content-addressed where the artifact identity is content-derived;
* tenant isolation is enforced by access control, trust roots, signing domains, distribution channels, and reader policies;
* global references can be reused safely across tenants without cross-tenant leakage;
* operational systems such as Orgo and Konnaxion can manage builds, review, authority recognition, publication, offline distribution, and runtime activation without confusing artifact identity with tenant visibility.

This document is normative where it uses MUST, SHOULD, or MAY.

## Definitions

* **Tenant**: an isolated administrative, security, governance, or operational domain. A tenant may represent an organization, deployment, customer, jurisdiction, community, institution, or environment.
* **Exchange**: a structured Kristal artifact containing portable epistemic content, provenance, validation references, authority recognition references, certainty metadata, and query-relevant structure.
* **Working Exchange**: an Exchange that has been compiled and may be reviewed, inspected, distributed, or used under policy, but is not necessarily recognized as a reference artifact by an authority channel.
* **Reference Exchange**: an Exchange recognized by one or more declared authority channels for a declared scope and validation policy.
* **Runtime Pack**: a derived offline-usable package produced from an Exchange for query, reading, or local runtime use.
* **Global content ID**: an ID derived only from canonicalized artifact content, excluding signatures and tenant-local control-plane metadata.
* **Tenant artifact handle**: a tenant-scoped handle that maps to a global content ID while hiding or contextualizing it for access-control and correlation-risk purposes.
* **Access layer**: authorization, reader policy, tenant policy, and distribution controls that determine who can obtain, view, activate, or use an artifact.
* **Signing domain**: key material, trust roots, and signature policies used to sign or verify artifacts within a tenant, environment, authority channel, or distribution channel.
* **Authority channel**: a scoped authority context that may recognize, validate, reject, dispute, or revoke artifacts, shards, assertions, runtime packs, or other authority channels.
* **Reader policy**: a policy that determines which validation statuses, certainty levels, authority channels, scopes, and artifact statuses are visible or usable in a given reading surface.

## Core Model

### 1. Global content IDs

Kristal v5 uses content-addressed identity for artifacts whose identity is derived from their canonicalized content.

When an Exchange declares a global content ID:

* `kristal_id` MUST be computed solely from canonicalized Exchange content.
* `kristal_id` MUST exclude signatures.
* `kristal_id` MUST exclude tenant-local access control metadata.
* `kristal_id` MUST exclude workflow state, approval state, distribution state, and runtime activation state.
* The same Exchange content produced in two tenants MUST yield the same `kristal_id`.

Rationale: global content IDs enable caching, deduplication, reproducible builds, cross-implementation comparability, public reference reuse, and independent verification.

### 2. Tenant isolation is layered above IDs

Tenant separation MUST be enforced above content identity by:

* access control;
* tenant-scoped artifact handles;
* signing keys and trust roots;
* distribution channels;
* reader policies;
* authority-channel recognition policies;
* runtime activation policies;
* tenant-separated operational records.

Tenant isolation MUST NOT be implemented by altering the core content hash of the same artifact.

### 3. Tenant metadata must not influence global content hashes

Tenant identifiers, ACLs, approvals, workflow state, review queues, distribution status, runtime activation status, and tenant-local UI state MUST NOT be included in:

* Exchange canonicalization for `kristal_id`;
* Exchange `content_hash`;
* global artifact identity;
* Runtime Pack content hash, unless a separate declared integrity profile explicitly includes tenant packaging metadata.

Tenant metadata belongs in Orgo, Konnaxion, tenant registries, access-control records, release records, reader-policy records, or distribution-channel records.

It does not belong in global Kristal payload identity.

## Artifact Visibility and Authorization

### 4. Access decisions

Implementations MUST enforce access control at the following boundaries:

* Exchange lookup;
* Exchange fetch;
* Exchange read;
* shard lookup;
* shard fetch;
* Runtime Pack lookup;
* Runtime Pack fetch;
* Runtime Pack activation;
* offline cache use;
* reader-policy view construction;
* authority-recognition inspection when the recognition record is tenant-private.

Access checks MUST be tenant-scoped.

Access checks MUST prevent:

* cross-tenant enumeration of artifact existence;
* inference through error messages;
* unauthorized inspection of authority-channel membership;
* unauthorized discovery of distribution-channel contents;
* unauthorized activation of Runtime Packs;
* unauthorized reuse of tenant-private cached artifacts.

Where appropriate, systems SHOULD use consistent “not found or not authorized” responses rather than revealing whether a given global content ID exists in another tenant.

### 5. Content-addressability and privacy

Global content IDs can create correlation risk. If two tenants independently produce identical content, they may share the same `kristal_id`.

Deployments SHOULD consider:

* restricting exposure of raw `kristal_id` values outside authorized contexts;
* using tenant-scoped artifact handles in UI and public APIs;
* avoiding raw content IDs in unauthenticated URLs;
* preventing existence checks against raw IDs;
* ensuring logs containing raw IDs are tenant-scoped;
* applying rate limits to artifact lookup endpoints;
* separating public reference registries from private tenant registries.

If a deployment requires no cross-tenant correlation in external surfaces, it MUST use a tenant-scoped indirection layer while keeping global content IDs internally.

## Tenant Artifact Handles

### 6. Tenant-scoped indirection

A tenant MAY expose a tenant artifact handle instead of a raw global content ID.

Recommended shape:

```json
{
  "tenant_artifact_handle": "tenant-artifact:<tenant-scope>:<opaque-id>",
  "tenant_id": "tenant:<slug>",
  "target": {
    "artifact_type": "working_exchange",
    "kristal_id": "sha256:<hex>"
  },
  "allowed_channels": [],
  "reader_policy_refs": [],
  "authority_channel_refs": [],
  "trust_root_refs": [],
  "created_at": "RFC3339"
}
```

Tenant artifact handles MAY be opaque.

Tenant artifact handles MUST NOT be treated as global artifact identity.

A tenant artifact handle MAY be revoked, rotated, hidden, or remapped without changing the underlying global content ID.

### 7. Public reference artifacts

Some Kristals are intended to be cross-tenant by design, such as public education packs, public standards, public institutional records, or public Wikidata-derived reference artifacts.

Such artifacts SHOULD be published through a declared public tenant, public authority channel, public distribution channel, or shared reference registry.

A public reference artifact may expose raw global content IDs when correlation is intended and safe.

Private tenants MAY still map public reference artifacts through tenant-local handles if their access model requires it.

## Signing, Trust Roots, and Tenant Domains

### 8. Tenant-scoped signing domains

Each tenant or environment MUST have a defined trust root set used to verify signatures.

Trust root sets MAY include:

* tenant keys;
* environment keys;
* authority-channel keys;
* publisher keys;
* distribution-channel keys;
* public reference registry keys;
* delegated trust roots.

Artifacts MAY be signed by tenant-specific keys even when their global content IDs are identical.

Verification MUST use the trust roots pinned by the active tenant, authority channel, distribution channel, or reader policy.

### 9. Same content, different signatures

It MUST be possible for:

* Tenant A and Tenant B to publish the same Exchange with the same `kristal_id`;
* Tenant A and Tenant B to sign that Exchange with different keys;
* different authority channels to recognize or reject the same Exchange independently;
* different distribution channels to package the same Exchange differently.

Signatures MUST be treated as metadata over declared content hashes or manifest targets.

Signatures MUST NOT change `kristal_id`.

### 10. Trust roots and authority recognition

Trust roots verify signatures.

Authority recognition declares that an authority channel accepts an artifact, shard, assertion, runtime pack, dataset, or another authority channel under a declared scope and policy.

These concepts MUST remain separate.

A valid signature does not imply authority recognition.

Authority recognition does not imply universal truth.

A tenant may trust a signer for distribution while not recognizing the artifact as reference material.

A tenant may recognize an authority channel for one scope while rejecting it for another.

## Distribution Channel Isolation

### 11. Distribution channels

Runtime Pack distribution MUST be isolated per tenant or per declared public channel by one or more of:

* separate package indexes;
* tenant-authenticated endpoints;
* tenant-specific offline bundle channels;
* public reference channels;
* signed release channels;
* pinned channel manifests;
* access-controlled replication.

Clients MUST NOT activate packs from channels that are not trusted under the active tenant or reader policy.

Clients MUST NOT assume that a valid signature under another tenant’s trust roots authorizes local activation.

### 12. Runtime Pack source status

Runtime Packs MUST declare the status of the source artifact from which they were produced.

At minimum, the manifest SHOULD distinguish:

* `working_exchange`;
* `reference_exchange`;
* `deprecated_exchange`;
* `revoked_exchange`, when relevant.

A Runtime Pack derived from a Working Exchange may be usable in research, review, creative, or internal contexts.

A Runtime Pack derived from a Reference Exchange may be usable in stricter reader policies, depending on authority recognition, validation status, certainty level, and tenant policy.

The source status MUST be visible to policy engines and reader surfaces.

## Control Plane vs Data Plane

### 13. Orgo as control plane

Orgo SHOULD store tenant-scoped control-plane records, including:

* workflow state;
* review state;
* approval state;
* build requests;
* validation tasks;
* authority-recognition workflow;
* distribution status;
* audit logs;
* policy configuration;
* reader-policy assignments;
* key references;
* trust-root sets;
* tenant artifact handles;
* operational release records.

Kristal artifacts SHOULD store:

* content;
* manifests;
* provenance;
* validation references;
* authority-recognition references;
* certainty metadata;
* reproducibility policy selections;
* query semantics;
* signatures;
* integrity hashes.

Workflow state MUST NOT be required to compute global artifact identity.

### 14. Konnaxion distribution and offline caching

Konnaxion clients and nodes MUST:

* verify signatures against the active trust roots before activating a pack;
* check distribution-channel authorization;
* enforce tenant-separated caches;
* enforce reader-policy visibility;
* preserve artifact status labels;
* preserve validation and certainty labels;
* prevent unauthorized cross-tenant cache reuse;
* enforce rollback and downgrade policies within each tenant or channel;
* distinguish between local possession and tenant-authorized use.

Konnaxion MAY store the same underlying bytes once for efficiency, but only if cache access is logically partitioned and authorization is checked before every tenant-visible use.

### 15. Architect rendering

Architect and other rendering systems MUST preserve tenant, authority, validation, certainty, and reader-policy labels when rendering Kristal content.

Rendering systems MUST NOT flatten scoped recognition into universal truth.

Rendering systems MUST NOT show tenant-private artifacts to unauthorized readers.

Rendering systems SHOULD make it clear when the current view is filtered by tenant, authority channel, certainty level, validation status, or reader policy.

## Reproducibility and Comparability Across Tenants

### 16. Tenant-independent reproducibility

Given identical inputs, canonicalization rules, and policy selections, two tenants compiling the same Exchange content MUST be able to produce:

* identical Exchange content hashes;
* the same `kristal_id`;
* byte-identical exports when using the same export profile and serialization rules;
* reproducible Runtime Packs when using the same portable runtime policies.

Tenant-local approvals, access controls, logs, and distribution status MUST NOT break reproducibility of the underlying Exchange content.

### 17. Tenant-configurable policy selection

Tenants MAY choose different portable policies for Runtime Packs, including:

* row groups;
* ordering policies;
* query indexes;
* subset recipes;
* reader-policy filters;
* authority-channel selection;
* offline packaging options;
* distribution-channel constraints.

When tenants choose different portable policies, those selections MUST be recorded in the relevant manifests so artifacts remain comparable and reproducible within their policy class.

### 18. Reader-policy-specific outputs

A tenant may generate different reader-policy views from the same underlying Exchange.

For example:

* `reference_only`;
* `validated_only`;
* `high_certainty_only`;
* `research`;
* `creative`;
* `all_with_labels`;
* `custom`.

--- CHUNK END ---

--- CHUNK BEGIN ---
id=8e02d62cc0eb:351-575
start=351
end=575
----
These views MUST NOT alter the underlying global content ID unless they create a distinct derived artifact with its own declared content boundary.

Reader-policy views MUST preserve enough metadata to show what was included, excluded, or hidden by policy.

## Authority Channels Across Tenants

### 19. Tenant authority channels

A tenant may define local authority channels.

A tenant may recognize external authority channels.

A tenant may reject or ignore external authority channels.

A tenant may delegate recognition to another authority channel for a declared scope.

Example:

```text
A tenant may recognize WHO for health guidance.
A tenant may recognize UNESCO for heritage or global education references.
A tenant may recognize a company for documentation of its own systems.
A tenant may recognize a local board for municipal policy.
```

Recognition MUST remain scoped.

Recognition by one tenant or authority channel MUST NOT imply recognition by another.

### 20. Shared authority channels

Multiple tenants MAY subscribe to the same authority channel.

When they do, each tenant MUST still declare or inherit:

* which trust roots are accepted;
* which scopes are recognized;
* which validation policies apply;
* which reader policies use the recognition;
* which revocation sources are monitored.

Shared authority channels simplify reference reuse, but they do not remove tenant access-control obligations.

## Threat Considerations

### 21. Correlation risk

Global IDs can reveal that two tenants have identical content if IDs are exposed publicly.

Mitigations SHOULD include:

* opaque handles externally;
* tenant-authenticated lookup;
* avoiding raw IDs in public URLs;
* rate-limited artifact lookup;
* consistent “not found or not authorized” responses;
* tenant-scoped logs;
* separated public and private registries.

### 22. Downgrade and rollback attacks

Clients MUST apply a per-tenant or per-channel rollback and downgrade prevention policy.

Signed latest pointers, pinned release channels, monotonic version channels, revocation records, or transparency logs SHOULD be used where appropriate.

A client MUST NOT activate an older Runtime Pack if the active tenant or channel policy rejects rollback to that version.

### 23. Cross-tenant cache pollution

Client caches MUST be logically partitioned by tenant and channel.

Package indices MUST be tenant-authenticated or channel-authenticated.

A client MUST NOT satisfy a tenant request with cached content from another tenant unless explicit policy allows it and all authorization, signature, trust-root, and reader-policy checks succeed.

### 24. Unauthorized inference

Systems MUST avoid revealing sensitive tenant information through:

* error messages;
* timing differences;
* package index enumeration;
* signature metadata exposure;
* authority-channel membership queries;
* release-channel probing;
* log access;
* shared cache hits.

Where correlation risk matters, deployments SHOULD prefer opaque handles and tenant-authenticated lookup.

### 25. Trust-root confusion

Clients MUST verify artifacts under the active tenant or channel trust roots.

A signature valid under one tenant’s trust roots MUST NOT be accepted as valid under another tenant unless that second tenant explicitly recognizes the signer, trust root, or authority channel.

### 26. Reader-policy confusion

A user interface MUST NOT present an artifact as visible, recognized, validated, or high-certainty unless it satisfies the active reader policy.

Possession of a Runtime Pack does not imply permission to use it.

Successful integrity verification does not imply reader-policy acceptance.

Authority recognition does not imply visibility for every tenant.

## Recommended Implementation Patterns

### Tenant-scoped artifact registry

Use a tenant-scoped artifact registry that maps:

```text
tenant_artifact_handle
→ kristal_id
→ allowed_channels
→ authority_channel_refs
→ trust_root_refs
→ reader_policy_refs
→ policy_class
→ visibility_state
```

The registry may store:

* tenant-local handles;
* raw global content IDs;
* channel membership;
* trust-root bindings;
* visibility policies;
* access grants;
* revocation status;
* release-channel state.

### Public reference registry

Use a separate public reference registry for intentionally shared Kristals.

The public registry may expose raw global content IDs when correlation is intended.

Private tenants may mirror public reference artifacts through local handles.

### Cache partitioning

Implementations MAY deduplicate bytes internally, but MUST partition access logically by:

* tenant;
* environment;
* distribution channel;
* reader policy;
* activation status;
* trust-root set.

### Structured logs

Structured logs SHOULD include fields such as:

```json
{
  "tenant_id": "tenant:<slug>",
  "environment": "prod",
  "build_id": "build:<id>",
  "kristal_id": "sha256:<hex>",
  "tenant_artifact_handle": "tenant-artifact:<tenant-scope>:<opaque-id>",
  "authority_channel": "authority:<slug>",
  "reader_policy_id": "reader_policy:<slug>",
  "runtime_pack_id": "sha256:<hex>",
  "event": "runtime_pack_activation_checked"
}
```

Log access MUST be tenant-scoped.

Logs SHOULD avoid exposing raw global content IDs in contexts where correlation risk matters.

## Conformance

A deployment conforms to this multi-tenancy boundary model if:

* global content IDs are derived from canonicalized content, not tenant metadata;
* tenant isolation is enforced through access control, trust roots, signing domains, distribution channels, and reader policies;
* signatures do not alter global content IDs;
* Runtime Pack caches are tenant-separated or logically partitioned;
* cross-tenant artifact enumeration is prevented;
* tenant-local handles are used where correlation risk requires them;
* Orgo control-plane records do not affect global artifact identity;
* Konnaxion activation checks are tenant- and channel-scoped;
* authority recognition remains scoped;
* reader-policy visibility remains explicit;
* downgrade and rollback protections are enforced per tenant or channel.

A deployment is not conformant if:

* tenant metadata changes `kristal_id` for identical Exchange content;
* raw global IDs are exposed in unauthenticated contexts where correlation risk is prohibited;
* clients can activate packs from untrusted tenant or channel contexts;
* signatures from one tenant are accepted in another without explicit trust-root or authority recognition;
* cross-tenant caches leak private artifacts;
* UI surfaces hide tenant, validation, certainty, authority, or reader-policy distinctions.

## Summary

Kristal v5 keeps artifact identity and tenant access control separate.

The same content may produce the same global content ID across tenants, but access, visibility, recognition, signing, distribution, activation, and reader-policy use are tenant-scoped.

The rule is:

> Global content identity enables reproducibility and shared references.
> Tenant policy decides who can see, trust, recognize, activate, or use them.

Multi-tenancy in Kristal v5 is therefore a layering model:

```text
global artifact identity
+ tenant-scoped handles
+ access control
+ signing domains
+ authority recognition
+ distribution channels
+ reader policies
+ runtime activation policy
```

This preserves reproducibility without weakening tenant isolation.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/08-ops/failure-paths-and-resilience.md"
id=704994204680
kind=markdown
size=21254
lines=764
line_ref=1-764
chunks=3
chunk_refs=1-350,351-700,701-764
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=704994204680:1-350
start=1
end=350
----
# Failure Paths and Resilience

## Status

Non-normative operational guidance for Kristal v5

## Purpose

This document provides operational guidance for building, reviewing, validating, publishing, distributing, and rendering Kristals reliably in the ecosystem:

* **Orgo** — workflow, orchestration, review, approvals, routing, build lifecycle
* **SenTient** — resolution, disambiguation, normalization, extraction support
* **Kristal compiler** — Structured Epistemic State compile, Exchange generation, Runtime Pack compile
* **Konnaxion** — distribution, offline caching, reader-policy selection, Runtime Pack access
* **Architect** — deterministic rendering with visible status, certainty, authority, and validation labels

These patterns are **not** part of Kristal artifact schemas and do not affect conformance, except where core/spec requirements already mandate behavior such as hash verification, signature verification, deterministic builds, atomic publication, or immutable artifact identity.

## Principles

* **Preserve artifact integrity where declared.**
* **Separate compilation from validation.**
* **Preserve ambiguity instead of erasing it.**
* **Represent partial, uncertain, disputed, or unresolved work explicitly.**
* **Quarantine poison inputs instead of infinite retry or silent drop.**
* **Bound resource usage with timeouts, quotas, and cancellation.**
* **Prefer immutable snapshots: new data produces new artifacts.**
* **Keep validation status, certainty level, authority channel, and reader policy visible.**
* **Avoid silently presenting working, disputed, or low-certainty material as recognized reference material.**

Kristal v5 does not treat every unresolved or invalid claim as a pipeline failure. A build may produce a Working Artifact containing unresolved, disputed, partial, or low-certainty assertions, provided their status is explicit and the selected policy allows them.

## 1) Circuit Breaker for SenTient Resolution Calls

### Concept

A circuit breaker prevents repeated calls to an unhealthy dependency, reducing cascading failures.

### Problem It Addresses

Resolution services can fail or degrade because of timeouts, high latency, partial outages, malformed input, overloaded models, unavailable indexes, or tenant-specific limits.

Without protection, a build pipeline can stall, retries can amplify load, and Orgo queues can back up.

### Recommended Approach

* Wrap SenTient calls behind a circuit breaker per tenant and per resolver endpoint.
* Prefer scoped breakers instead of one global breaker.
* Use a fallback that preserves unresolved ambiguity when policy allows.
* Record the circuit state in the build record or operational logs.
* Keep unresolved material explicit instead of dropping or pretending it is resolved.

### Suggested States

* **Closed** — normal operation
* **Open** — calls are skipped and fail quickly with a structured reason
* **Half-open** — limited probe calls test recovery

### Trigger Thresholds

Guidance:

* Open after N consecutive timeouts or dependency errors within a short window.
* Remain open for a cooldown interval.
* Enter half-open mode with limited probes.
* Close only after successful probes.

### Output Semantics

If SenTient fails and the pipeline policy allows unresolved preservation, emit a Structured Epistemic State or build output with:

```json
{
  "resolution_status": "unresolved",
  "assertion_status": "claimed",
  "certainty_level": "unknown",
  "warnings": [
    {
      "reason_code": "RESOLVE_DEP_UNAVAILABLE",
      "correlation_id": "..."
    }
  ]
}
```

If policy does not allow unresolved preservation, the stage may be blocked, but the failure should be recorded as a workflow or policy outcome, not as a corruption of the Kristal model.

### Pitfalls

* Hiding failures: always log and surface circuit state changes.
* Global breakers: avoid one tenant taking down all tenants.
* False certainty: never mark unresolved output as reviewed, validated, or recognized.
* Silent fallback: a fallback must preserve status labels.

## 2) Dead Letter Queue for Ingestion and Build Stages

### Concept

A Dead Letter Queue stores messages, inputs, or jobs that cannot be processed after bounded retries.

### Problem It Addresses

Poison inputs can block queues indefinitely if retried endlessly, or disappear if dropped.

Examples:

* corrupt PDFs
* malformed extractor output
* pathological resolution cases
* invalid schema instances
* missing authority registry references
* invalid signatures
* incompatible Runtime Pack manifests
* unsupported value types
* oversized source bundles

### Recommended Approach

Use staged queues for:

```text
ingest
extract
normalize
resolve
compile
review
validate
recognize
publish
package
distribute
```

Each stage should have:

* bounded retries
* exponential backoff with jitter
* structured error output
* DLQ on repeated failure
* ownership for triage
* retention policy

### DLQ Payload Requirements

Guidance payload:

```json
{
  "build_id": "build:...",
  "tenant_id": "tenant:...",
  "stage": "resolve",
  "input_ref": "sha256:...",
  "artifact_ref": null,
  "error_code": "RESOLVE_TIMEOUT",
  "error_message": "Bounded diagnostic message.",
  "attempt_count": 3,
  "first_seen_at": "2026-01-01T00:00:00Z",
  "last_seen_at": "2026-01-01T00:05:00Z",
  "correlation_id": "..."
}
```

### Operational Loop

DLQ items should create Orgo Cases or Tasks automatically for triage.

Triage outcomes:

* fix input and requeue
* adjust policy if the constraint was non-core
* split the input into smaller units
* preserve as unresolved or partial if allowed
* mark the assertion as rejected with recorded reason
* revoke or supersede an artifact if publication already occurred
* close as non-actionable with explanation

### Pitfalls

* DLQ as a graveyard: require ownership, SLAs, dashboards, and expiry.
* Infinite DLQ growth: apply retention, sampling, and aggregation for high-volume failures.
* Over-redaction: preserve enough diagnostic context to repair the issue.
* Under-redaction: avoid logging sensitive input content unnecessarily.

## 3) Timeouts and Cancellation

### Concept

Every stage must have bounded execution time to prevent resource exhaustion and queue collapse.

### Recommended Guidance by Stage

#### Ingestion

* Hard timeout.
* If source acquisition fails, emit structured failure.
* Do not create a partial source artifact unless the source boundary is explicit.

#### Extraction

* Hard timeout.
* Partial extractor output may be emitted only if schema-valid and explicitly marked partial.
* Claim-IR may be used as an extractor proposal profile, but it is not the universal required input format.

#### Normalization

* Hard timeout.
* If normalization is incomplete, preserve explicit warnings.
* Do not erase source identity or provenance.

#### Resolution

* Hard timeout.
* Preserve unresolved state when policy allows.
* Record warning and correlation ID.

#### Compilation

* Hard timeout.
* Safe abort if artifact construction cannot complete.
* If partial compilation is supported, it must produce a clearly marked Working Artifact, not a Reference Artifact.
* Do not publish incomplete packs as current.

#### Review

* Timeout produces a workflow status such as `review_status = "pending"` or `review_status = "blocked"`.
* Review timeout does not necessarily invalidate the compiled artifact.

#### Validation

* Timeout produces `validation_status = "in_review"` or `validation_status = "not_evaluated"` unless policy defines another outcome.
* Validation timeout does not automatically erase the Working Artifact.
* Validation timeout prevents recognition only when the selected recognition policy requires completed validation.

#### Recognition

* Timeout or authority unavailability produces `recognition_status = "none"` or `recognition_status = "under_review"`.
* Recognition by one authority channel must not be inferred from another.

#### Runtime Pack Compilation

* Hard timeout.
* Safe abort.
* No partial pack publication as active.
* A failed pack compile does not necessarily invalidate the source Exchange.

#### Distribution

* Retry with backoff.
* Never serve incomplete packs as current.
* Preserve previous active pack until the candidate pack satisfies activation requirements.

### Cancellation Propagation

If Orgo cancels a build:

* downstream workers should stop;
* final build status should be emitted;
* partial work should be marked clearly;
* partially signed or partially published artifacts must not be exposed as active Reference Artifacts or active Runtime Packs.

### Pitfalls

* Long-tail jobs blocking worker pools.
* Cancellation creating orphaned partial artifacts.
* Validation timeouts being misrepresented as rejection.
* Partial publication without clear status.
* Hidden retries causing non-deterministic outputs.

## 4) Quotas and Rate Limiting

### Concept

Quotas bound per-tenant resource usage to protect system stability.

### Recommended Quota Dimensions

* ingest volume: bytes/day, documents/day
* extraction calls: jobs/hour, tokens/day when applicable
* resolution calls: requests/minute, candidates/build
* validation complexity: assertions/build, references/assertion
* review workload: open cases/tenant, reviewers/stage
* build concurrency: active builds/tenant
* Runtime Pack compilation: MB/build, index size
* distribution bandwidth: MB/day/region
* offline cache size: per device, per tenant, per reader policy

### Enforcement Guidance

* Enforce at the Orgo orchestration boundary.
* Return structured errors with remediation hints.
* Prefer “burst then throttle” behavior over hard drops when possible.
* Rate limiting must not change artifact content.
* Scheduling changes must not affect deterministic build outputs.

### Pitfalls

* Non-deterministic throttling affecting output.
* One tenant starving shared workers.
* Silent throttling without user-visible queue status.
* Resource exhaustion in offline nodes because pack size was not bounded.

## 5) Backpressure and Queue Hygiene

### Concept

When downstream systems are slow, upstream systems must slow down safely.

### Recommended Approach

Use bounded queues with explicit backpressure signals to producers.

Recommended queues:

```text
ingest_queue
extract_queue
resolve_queue
compile_queue
review_queue
validate_queue
recognize_queue
package_queue
distribution_queue
```

Priority classes may include:

* security rebuilds
* revocations
* rollback / recovery
* small builds
* user-facing hotfixes
* scheduled batch builds
* experimental or research builds

### Backpressure Signals

Backpressure should include:

* queue depth
* estimated delay band
* admission status
* retry-after hints
* tenant quota state
* degraded dependency state

### Pitfalls

* Priority inversion.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=704994204680:351-700
start=351
end=700
----
* Large jobs starving small jobs.
* Hotfixes bypassing validation labels.
* Queues retaining stale builds after supersession.

## 6) Integrity-Critical Points

These are operational restatements of spec-level requirements.

### Hash Verification

When a content hash is declared, verification must confirm that the bytes match the declared hash before the object is accepted for the target operation.

### Signature Verification

When signatures are declared as required by policy, signature verification must confirm:

* signing target
* key id
* algorithm
* payload hash
* signature value
* trust root or authority channel
* expiration, where relevant
* revocation state, where relevant

### Atomic Publish

A release is either fully published and verifiable, or not published.

Partially published artifacts must not be exposed as active Reference Artifacts or active Runtime Packs.

### Immutable Snapshots

Updates produce new artifact identities.

New data should create a new Exchange, shard, federation manifest, Runtime Pack, or validation/recognition record as appropriate.

### Activation Requirements

A Runtime Pack is not active just because it exists on disk.

Before activation, the system should check the declared requirements for the selected channel, reader policy, and runtime environment.

If a candidate pack does not satisfy the requirements, the previous active pack remains in place and the candidate receives a clear status.

### Validation and Recognition

A validation failure does not necessarily prevent compilation of a Working Artifact.

It prevents the artifact or assertion from being represented as validated under that validation policy.

A recognition failure does not necessarily invalidate the artifact.

It prevents the artifact from being represented as recognized by the relevant authority channel.

## 7) Release Safety: Canary and Blue-Green Distribution

### Concept

Canary and blue-green strategies reduce blast radius when shipping new Runtime Packs or Reference Artifacts.

### Recommended Approach

#### Canary

Deliver a new pack to a small cohort, device class, tenant, or region first.

Observe health signals before wider rollout.

#### Blue-Green

Keep the previous pack live while the candidate pack is verified.

Switch traffic only when the candidate satisfies the selected activation requirements.

#### Rollback

Rollback should use a signed, pinned prior release whose status remains acceptable under the active downgrade and revocation policies.

Rollback must not activate an unsigned, revoked, or policy-incompatible artifact.

### Health Signals

* hash verification success rate
* signature verification success rate
* Runtime Pack activation success rate
* query error rate
* pack download success and latency
* device cache hit rates
* offline query success rate
* reader policy application errors
* authority registry lookup failures
* validation metadata load failures
* label rendering errors in Architect

### Pitfalls

* Rollback that bypasses revocation.
* Canary cohort hiding tenant-specific failures.
* Activating a candidate pack before reader policies are available.
* Serving a pack whose source Exchange status is unclear.

## 8) Observability: Correlation IDs and Structured Logs

### Required Operational Identifiers

Guidance:

```text
build_id
state_id
kristal_id
exchange_id
shard_id
federation_id
runtime_pack_id
assertion_id
validation_decision_id
recognition_id
reader_policy_id
authority_channel_id
input_ref
tenant_id
correlation_id
```

### Log Events

Log events should be emitted for:

* stage start and end
* circuit breaker state transitions
* retries
* DLQ moves
* timeout events
* cancellation propagation
* validation status changes
* review status changes
* recognition status changes
* publication attempts
* Runtime Pack activation attempts
* reader-policy selection
* authority registry loading
* revocation checks
* rollback events

### Bounded Logging

Logs should include bounded summaries, not unlimited source payloads.

Validation, extraction, and resolution failures should include:

* reason code
* stage
* target ref
* policy ref, when applicable
* authority channel, when applicable
* correlation ID
* bounded diagnostic message

### Pitfalls

* Logging sensitive source content.
* Logging too little to repair failures.
* Missing authority channel context.
* Losing the difference between validation status and recognition status.

## 9) Suggested Minimal Error Taxonomy

### Ingestion and Extraction

```text
INGEST_PARSE_ERROR
INGEST_SOURCE_UNAVAILABLE
INGEST_TOO_LARGE
EXTRACT_TIMEOUT
EXTRACT_SCHEMA_INVALID
EXTRACT_PARTIAL_OUTPUT
```

### Resolution

```text
RESOLVE_TIMEOUT
RESOLVE_DEP_UNAVAILABLE
RESOLVE_AMBIGUOUS
RESOLVE_UNSUPPORTED_VALUE
RESOLVE_POLICY_BLOCKED
```

### Compilation

```text
COMPILE_FAILED
COMPILE_PARTIAL
COMPILE_SCHEMA_INVALID
COMPILE_HASH_MISMATCH
COMPILE_UNSUPPORTED_ARTIFACT_TYPE
```

### Review and Validation

```text
REVIEW_TIMEOUT
REVIEW_BLOCKED
VALIDATION_NOT_EVALUATED
VALIDATION_IN_REVIEW
VALIDATION_FAILED
VALIDATION_TIMEOUT
VALIDATION_POLICY_MISSING
VALIDATION_SCOPE_MISMATCH
CERTAINTY_TOO_LOW_FOR_POLICY
```

### Recognition and Authority

```text
AUTHORITY_REGISTRY_MISSING
AUTHORITY_CHANNEL_UNKNOWN
AUTHORITY_NOT_RECOGNIZED
RECOGNITION_IN_REVIEW
RECOGNITION_REJECTED
RECOGNITION_REVOKED
TRUST_ROOT_UNAVAILABLE
```

### Publication and Distribution

```text
PUBLISH_ATOMICITY_FAILED
PUBLISH_POLICY_BLOCKED
RUNTIME_PACK_COMPILE_FAILED
RUNTIME_PACK_ACTIVATION_BLOCKED
VERIFY_HASH_FAILED
VERIFY_SIGNATURE_FAILED
DISTRIBUTION_FAILED
ROLLBACK_BLOCKED
REVOCATION_CHECK_FAILED
```

### Resource Control

```text
QUOTA_EXCEEDED
RATE_LIMITED
QUEUE_BACKPRESSURE
TENANT_LIMIT_REACHED
TIMEOUT
CANCELLED
```

## 10) Build Record Guidance

A Kristal v5 build record should distinguish compilation, review, validation, recognition, publication, and activation.

Recommended shape:

```json
{
  "build_id": "build:2026-01-01T00:00:00Z:example",
  "schema_version": "5.0",
  "compile_status": "succeeded",
  "review_status": "pending",
  "validation_status": "not_evaluated",
  "recognition_status": "none",
  "publication_status": "not_published",
  "activation_status": "not_applicable",
  "working_outputs": [],
  "reference_outputs": [],
  "runtime_pack_outputs": [],
  "reason_codes": [],
  "created_at": "2026-01-01T00:00:00Z",
  "correlation_id": "..."
}
```

Allowed compile statuses:

```text
succeeded
failed
partial
cancelled
```

Allowed review statuses:

```text
not_required
pending
completed
blocked
cancelled
```

Allowed validation statuses:

```text
not_evaluated
in_review
validated
conditionally_validated
disputed
rejected
revoked
```

Allowed recognition statuses:

```text
none
under_review
recognized
conditionally_recognized
disputed
rejected
revoked
```

Allowed publication statuses:

```text
not_published
published
blocked
superseded
revoked
```

Allowed activation statuses:

```text
not_applicable
candidate
activated
blocked
superseded
revoked
```

## 11) Reader Policy Resilience

Reader policies may fail to load, become unavailable, or reference authority channels that are missing from the local registry.

### Recommended Behavior

If a selected reader policy cannot be loaded:

* do not silently switch to a broader policy;
* preserve the previous reader policy when available;
--- CHUNK END ---

--- CHUNK BEGIN ---
id=704994204680:701-764
start=701
end=764
----
* show a clear unavailable status;
* log the reason code and correlation ID.

If an authority registry cannot be loaded:

* do not infer authority recognition;
* show artifacts with available local labels;
* mark recognition status as unavailable or unresolved;
* avoid presenting scoped validation as universal validation.

### Pitfalls

* Falling back from `validated_only` to `all_with_labels` without user awareness.
* Hiding labels because metadata is unavailable.
* Treating missing authority data as rejection.
* Treating missing authority data as recognition.

## 12) Architect Rendering Resilience

Architect must render Kristal content without hiding epistemic status.

### Recommended Behavior

Architect should preserve and display:

* assertion status
* certainty level
* validation status
* validated-as classification
* authority channel
* recognition status
* scope
* disputed status
* reader policy mode

### Rendering Degradation

If some metadata is unavailable:

* show the content with an explicit status marker;
* do not present it as validated or recognized;
* do not flatten scoped validation into universal truth;
* do not hide that a claim is fictional, mythological, disputed, rejected, or validated only under a specific authority channel.

### Pitfalls

* Simplifying labels away for readability.
* Showing only the selected answer without authority context.
* Merging multiple authority positions into one statement.
* Treating absence of metadata as high confidence.

## Appendix: Recommended Least-Worst Defaults

* Circuit breaker enabled for SenTient by default.
* DLQs enabled for every pipeline stage.
* Hard timeouts for every stage.
* Quotas enforced at Orgo admission control.
* Compilation may produce Working Artifacts when validation is incomplete or unavailable, if policy allows.
* Reference Artifacts require explicit recognition or validation according to policy.
* Runtime Pack activation requires declared integrity and compatibility checks.
* Canary rollout for Runtime Packs before broad distribution.
* Previous active pack remains in place when candidate activation requirements are not satisfied.
* Reader policy fallback must never silently broaden visibility.
* Architect must preserve status, certainty, authority, and validation labels.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/08-ops/logging-and-correlation-ids.md"
id=dfe25adfac55
kind=markdown
size=22123
lines=854
line_ref=1-854
chunks=3
chunk_refs=1-350,351-700,701-854
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=dfe25adfac55:1-350
start=1
end=350
----
# Logging and correlation IDs (non-normative)

## Status

Non-normative operational guidance (Kristal v5)

## Purpose

This document defines a consistent logging and correlation-ID practice for the Kristal build, validation, recognition, and distribution ecosystem (Orgo × SenTient × Architect × Konnaxion).

The goal is to:

* make failures diagnosable quickly;
* support reliable audit and provenance workflows;
* enable end-to-end tracing across workflow, compilation, validation, recognition, publication, and distribution stages;
* preserve multi-tenant isolation while retaining debuggability;
* keep scoped validation, authority recognition, certainty labels, and reader-policy decisions traceable without embedding operational logs into Kristal artifacts.

These practices are **not** embedded as first-class objects in Kristal Exchange or Runtime Pack schemas. They are operational conventions used by build, review, validation, distribution, rendering, and reader systems, and may be referenced in logs, metrics, Orgo audit records, validation reports, profile execution records, and authority-recognition records.

## Principles

* Use **structured logs** with stable field names.
* Generate correlation IDs at the **earliest** operational boundary, usually Orgo admission.
* Propagate IDs across service boundaries, including HTTP headers, message metadata, job context, profile execution context, and audit records.
* Avoid PII in logs; log hashes, opaque IDs, or pointers instead.
* Prefer immutable identifiers, especially content-addressed IDs, for durable linkage.
* Distinguish operational failure from epistemic status.
* Do not flatten scoped validation into universal truth in logs.
* Preserve authority-channel, validation-policy, certainty-level, and reader-policy context when those decisions affect behavior.
* Keep logs operational; do not turn logs into Kristal source material unless explicitly imported as evidence under a declared policy.

## Core identifiers

### 1) `build_id` (required)

**Scope:** One end-to-end Kristal build workflow execution.
**Generated by:** Orgo or the workflow/orchestration boundary.
**Format:** UUIDv4 recommended, or equivalent unique opaque string.
**Stability:** Constant across all stages and retries of the same build workflow.

Used for tracing:

* admission;
* source intake;
* extraction or import;
* normalization;
* resolution;
* compilation;
* validation reporting;
* validation decisions;
* review;
* authority recognition;
* Exchange publication;
* Runtime Pack compilation;
* distribution;
* rendering;
* reader-policy evaluation.

### 2) `tenant_id` (required in multi-tenant deployments)

**Scope:** Tenant or namespace boundary for admission control, authorization, policy selection, and isolation.
**Generated by:** Orgo or identity layer.
**Format:** Stable opaque ID.

For public or shared logs, `tenant_id` SHOULD be redacted, hashed, or replaced with an operational alias if it could reveal sensitive information.

### 3) `trace_id` (recommended)

**Scope:** Distributed tracing span across services.
**Generated by:** Observability infrastructure or Orgo.
**Format:** Implementation-defined, stable within one trace.

Used for connecting logs, metrics, and traces across Orgo, SenTient, Kristal compiler, Architect, Konnaxion, storage, queues, and CI/CD systems.

### 4) `span_id` and `parent_span_id` (recommended)

**Scope:** One operation within a distributed trace.
**Generated by:** Observability infrastructure or service runtime.

Used for ordering nested operations and identifying local service bottlenecks.

### 5) Content-addressed artifact IDs (required where applicable)

#### `kristal_id`

Content-addressed identifier for the Exchange payload or top-level Kristal unit when used as the primary artifact ID.

#### `exchange_id`

Identifier for a Kristal Exchange artifact.

If `exchange_id` and `kristal_id` are the same in a deployment, logs SHOULD either use one consistently or include both with the same value.

#### `shard_id`

Content-addressed identifier for an Exchange shard when operating at shard granularity.

#### `federation_id`

Identifier for an Exchange Federation Manifest when operating across multiple shards or authority channels.

#### `runtime_pack_id`

Content-addressed identifier for the Runtime Pack artifact derived from an Exchange or federation.

#### `state_id`

Identifier for a Structured Epistemic State used as input to compilation.

#### `manifest_id`

Identifier for a manifest object, when distinct from the artifact payload ID.

### 6) Assertion-level IDs

#### `assertion_id` (required when operating at assertion granularity)

Stable identifier for an assertion in a Structured Epistemic State, Exchange, shard, validation report, or reader surface.

Used to trace:

* source material;
* extractor proposal outputs;
* resolution outcomes;
* validation results;
* authority recognition decisions;
* Exchange assertions;
* Architect render outputs;
* reader-policy visibility decisions.

#### `claim_id` (optional compatibility field)

`claim_id` MAY be logged when a Claim-IR or Resolved Claim-IR profile is used.

In Kristal v5, Claim-IR is an extractor proposal profile, not the universal input format. New v5 systems SHOULD prefer `assertion_id`.

#### `statement_id` (optional)

If an assertion expands into multiple normalized statements, log `statement_id` to disambiguate.

### 7) Authority and validation IDs

#### `authority_channel_id`

Identifier for the authority channel involved in a validation, recognition, publication, or reader-policy decision.

Recommended format:

```text
authority:<slug>
```

#### `validation_policy_id`

Identifier for the validation policy applied to an artifact, shard, assertion, profile execution, or Runtime Pack activation decision.

#### `validation_decision_id`

Identifier for a validation decision record.

#### `recognition_id`

Identifier for an authority recognition record.

#### `reader_policy_id`

Identifier for the reader policy used to determine visibility, filtering, labeling, or default presentation.

### 8) Input references

#### `input_ref` (recommended)

A hash or pointer for the original input unit, such as a document, email archive, PDF blob, dataset snapshot, RDF graph, JSON file, wiki dump, API snapshot, or shard.

Prefer:

* content hash of the raw blob;
* stable opaque dataset snapshot ID;
* stable URI hash if the raw URI cannot be logged safely.

Avoid logging raw URLs, file paths, filenames, email subjects, or document titles if they can leak PII or sensitive operational details.

### 9) Resolution references

#### `surface_id` / `mention_id` (optional)

If SenTient processes many surfaces, spans, mentions, labels, or candidate references, log a stable ID per surface or mention to isolate failures.

#### `candidate_id` (optional)

If SenTient returns ranked candidate entity IDs, property IDs, authority IDs, or assertion targets, log the selected candidate ID when a selection is made.

If no selection is made, log ambiguity using a bounded reason code rather than raw candidate lists when those lists may leak sensitive data.

## Propagation rules

### Orgo → workers/services

Orgo MUST attach `build_id` and, where applicable, `tenant_id` to:

* queue messages;
* job metadata;
* API requests to SenTient;
* API requests to Architect;
* compiler invocations;
* validation profile executions;
* authority-recognition workflows;
* Runtime Pack compilation jobs;
* Konnaxion distribution jobs;
* audit records.

Where available, Orgo SHOULD also attach:

* `trace_id`;
* `parent_span_id`;
* `reader_policy_id`;
* `validation_policy_id`;
* `authority_channel_id`;
* `source_state_refs`;
* `input_ref`.

### Service-to-service HTTP propagation

Use headers:

```text
X-Build-Id: <build_id>
X-Tenant-Id: <tenant_id>
X-Trace-Id: <trace_id>
X-Parent-Span-Id: <span_id>
X-Reader-Policy-Id: <reader_policy_id>
X-Validation-Policy-Id: <validation_policy_id>
X-Authority-Channel-Id: <authority_channel_id>
```

`X-Tenant-Id` MAY be omitted, hashed, or replaced with a scoped operational alias when crossing trust boundaries.

### Message queue propagation

Attach IDs as message metadata fields:

```text
build_id
tenant_id
trace_id
parent_span_id
stage
attempt
input_ref
authority_channel_id
validation_policy_id
reader_policy_id
```

Message payloads SHOULD avoid raw source content unless the queue is explicitly designed and secured for sensitive payloads.

### Artifact linkage

Operational logs SHOULD reference artifact IDs rather than embedding artifact contents.

Validation reports, authority recognition records, and Runtime Pack manifests MAY include `build_id` or equivalent trace metadata for operational linkage, but logs themselves do not become part of artifact identity.

## Structured log fields

All services SHOULD emit structured JSON logs with the following fields where applicable.

### Recommended minimum fields

```text
ts
level
service
stage
event
build_id
tenant_id
attempt
duration_ms
error_code
error_message
```

### Field definitions

#### `ts`

RFC 3339 timestamp.

#### `level`

One of:

```text
DEBUG
INFO
WARN
ERROR
```

#### `service`

Stable service identifier.

Examples:

```text
orgo
sentient
kristal-compiler
kristal-validator
architect
konnaxion
runtime-pack-builder
authority-registry
reader-policy-engine
ci
```

#### `stage`

Stable stage identifier.

Recommended values:

```text
admit
import
extract
normalize
resolve
compile
validate
review
recognize
exchange_publish
pack_compile
pack_activate
distribute
render
reader_policy_eval
revoke
rollback
```

#### `event`

Short stable event name.

Examples:
--- CHUNK END ---

--- CHUNK BEGIN ---
id=dfe25adfac55:351-700
start=351
end=700
----

```text
STAGE_START
STAGE_END
VALIDATION_DECISION_RECORDED
AUTHORITY_RECOGNITION_RECORDED
PACK_ACTIVATION_BLOCKED
```

#### `build_id`

End-to-end build workflow identifier.

#### `tenant_id`

Tenant or namespace identifier, when applicable.

#### `artifact IDs`

Include where known:

```text
state_id
kristal_id
exchange_id
shard_id
federation_id
runtime_pack_id
manifest_id
validation_decision_id
recognition_id
```

#### Assertion-level IDs

Include where applicable:

```text
assertion_id
claim_id
statement_id
evidence_id
```

#### Policy and authority fields

Include where applicable:

```text
authority_channel_id
validation_policy_id
reader_policy_id
scope_domain
scope_subdomain
validated_as
certainty_level
validation_status
recognition_status
artifact_status
```

#### Retry and performance fields

Include where applicable:

```text
attempt
duration_ms
timeout_ms
memory_limit_mb
result_count
queue_name
worker_id
```

#### Failure fields

Include where applicable:

```text
error_code
error_message
reason_code
retryable
limit_type
limit_value
```

`error_message` MUST be bounded and SHOULD avoid raw input content.

## Event taxonomy

### Stage lifecycle

```text
STAGE_START
STAGE_END
STAGE_RETRY
STAGE_CANCELLED
STAGE_SKIPPED
STAGE_PARTIAL
```

### Admission and import

```text
ADMISSION_REQUEST
ADMISSION_ACCEPTED
ADMISSION_REJECTED
INPUT_REGISTERED
INPUT_HASHED
INPUT_SNAPSHOT_CREATED
INPUT_ACCESS_DENIED
```

### Extraction and Structured Epistemic State

```text
EXTRACT_START
EXTRACT_SUCCESS
EXTRACT_PARTIAL
EXTRACT_FAILED
STRUCTURED_STATE_CREATED
STRUCTURED_STATE_UPDATED
STRUCTURED_STATE_REJECTED_BY_POLICY
```

### Resolution (SenTient)

```text
RESOLVE_REQUEST
RESOLVE_SUCCESS
RESOLVE_TIMEOUT
RESOLVE_CIRCUIT_OPEN
RESOLVE_AMBIGUOUS
RESOLVE_UNRESOLVED_PRESERVED
RESOLVE_CANDIDATE_SELECTED
```

### Compilation

```text
COMPILE_START
COMPILE_SUCCESS
COMPILE_PARTIAL
COMPILE_FAILED
WORKING_EXCHANGE_CREATED
REFERENCE_EXCHANGE_CREATED
```

### Validation reporting

```text
VALIDATION_START
VALIDATION_REPORT_CREATED
VALIDATION_DECISION_RECORDED
VALIDATION_TIMEOUT
VALIDATION_PARTIAL
VALIDATION_FAILED
VALIDATION_POLICY_FAILED
VALIDATION_PROFILE_FAILED
```

### Review

```text
REVIEW_REQUESTED
REVIEW_STARTED
REVIEW_COMPLETED
REVIEW_BLOCKED
REVIEW_REJECTED
REVIEW_RETURNED_FOR_REVISION
```

### Authority recognition

```text
AUTHORITY_RECOGNITION_REQUESTED
AUTHORITY_RECOGNITION_RECORDED
AUTHORITY_RECOGNITION_REJECTED
AUTHORITY_RECOGNITION_REVOKED
AUTHORITY_CHANNEL_NOT_RECOGNIZED
AUTHORITY_SCOPE_MISMATCH
```

### Certainty and assertion status

```text
ASSERTION_STATUS_UPDATED
CERTAINTY_LEVEL_UPDATED
ASSERTION_MARKED_DISPUTED
ASSERTION_REJECTED
ASSERTION_RETRACTED
DISAGREEMENT_PRESERVED
```

### Exchange / Runtime Pack

```text
EXCHANGE_PUBLISH_START
EXCHANGE_PUBLISH_SUCCESS
EXCHANGE_PUBLISH_BLOCKED
PACK_COMPILE_START
PACK_COMPILE_SUCCESS
PACK_COMPILE_FAILED
PACK_ACTIVATION_START
PACK_ACTIVATION_SUCCESS
PACK_ACTIVATION_BLOCKED
```

### Integrity and verification

```text
SIGNATURE_VERIFY_START
SIGNATURE_VERIFY_SUCCESS
SIGNATURE_VERIFY_FAILED
HASH_VERIFY_START
HASH_VERIFY_SUCCESS
HASH_MISMATCH
TRUST_ROOT_NOT_FOUND
TRUST_ROOT_REVOKED
POLICY_REQUIREMENT_NOT_MET
```

### Distribution (Konnaxion)

```text
PACK_PUBLISH_START
PACK_PUBLISH_SUCCESS
PACK_ROLLOUT_CANARY_START
PACK_ROLLOUT_CANARY_FAIL
PACK_ROLLBACK
PACK_DEPRECATED
PACK_REVOKED
```

### Rendering and reader policies

```text
RENDER_START
RENDER_SUCCESS
RENDER_BLOCKED_BY_POLICY
READER_POLICY_EVAL_START
READER_POLICY_EVAL_SUCCESS
READER_POLICY_FILTERED_ASSERTION
READER_POLICY_UNSUPPORTED
LABELS_PRESERVED
```

### DLQ / quarantine

```text
DLQ_ENQUEUE
DLQ_TRIAGE_DECISION
QUARANTINE_ENQUEUE
QUARANTINE_RELEASED
QUARANTINE_REJECTED
```

## Reason codes

Logs SHOULD use stable bounded reason codes.

Recommended values:

```text
schema_valid
schema_invalid
provenance_sufficient
provenance_insufficient
evidence_sufficient
evidence_insufficient
authority_recognized
authority_not_recognized
scope_mismatch
policy_satisfied
policy_failed
signature_valid
signature_invalid
hash_valid
hash_invalid
conflict_detected
disagreement_preserved
certainty_too_low_for_policy
rejected_by_authority_channel
revoked_by_authority_channel
reader_policy_filtered
reader_policy_unsupported
projection_unavailable
profile_execution_failed
timeout
memory_limit_exceeded
access_denied
```

## Recommended linkage in artifacts

Do not embed operational log structures into Exchange or Runtime Pack schemas as first-class log objects.

However:

* `build.build_id` SHOULD be captured where build metadata is already part of the manifest or report structure.
* Exchange manifests MAY record `build_id` for traceability.
* Runtime Pack manifests SHOULD record their source Exchange or federation reference.
* Validation reports SHOULD include `build_id`, target artifact references, assertion IDs where applicable, profile execution metadata, and mapped issue locations.
* Authority recognition records SHOULD include target artifact references, authority channel, validation policy, scope, and recognition status.
* Reader policy records SHOULD include policy ID and selection criteria, not operational logs.

## Privacy and security guidance

* Do not log raw extracted text unless explicitly required, protected, and justified.
* Prefer hashed references to evidence blobs, documents, datasets, and source snapshots.
* Avoid logging full signatures, private key material, access tokens, credentials, session IDs, or secret URLs.
* Avoid logging raw URLs or file paths when they may reveal sensitive tenant, user, or document information.
* Redact or hash `tenant_id` in public or cross-boundary logs if it could be sensitive.
* Keep `error_message` bounded and safe for operational viewing.
* Use structured `error_code` and `reason_code` fields instead of embedding sensitive details in messages.
* Do not use logs as evidence unless the log source, retention policy, integrity controls, and authority channel are declared.

## Examples

### Stage start log

```json
{
  "ts": "2026-01-07T14:10:12Z",
  "level": "INFO",
  "service": "kristal-compiler",
  "stage": "compile",
  "event": "STAGE_START",
  "build_id": "f3a2c6f8-7dd4-4a5f-9b84-4a0a7b1d0d0d",
  "tenant_id": "tenant_123",
  "input_ref": "sha256:9b3c00000000000000000000000000000000000000000000000000000000e21a",
  "attempt": 1
}
```

### Validation report log

```json
{
  "ts": "2026-01-07T14:10:44Z",
  "level": "INFO",
  "service": "kristal-validator",
  "stage": "validate",
  "event": "VALIDATION_REPORT_CREATED",
  "build_id": "f3a2c6f8-7dd4-4a5f-9b84-4a0a7b1d0d0d",
  "tenant_id": "tenant_123",
  "exchange_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "validation_policy_id": "kristal.v5:validation-policy:exchange-basic",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=dfe25adfac55:701-854
start=701
end=854
----
  "validation_status": "validated",
  "duration_ms": 32150
}
```

### Validation decision log

```json
{
  "ts": "2026-01-07T14:11:02Z",
  "level": "INFO",
  "service": "orgo",
  "stage": "validate",
  "event": "VALIDATION_DECISION_RECORDED",
  "build_id": "f3a2c6f8-7dd4-4a5f-9b84-4a0a7b1d0d0d",
  "tenant_id": "tenant_123",
  "validation_decision_id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "authority_channel_id": "authority:example-health-body",
  "validation_policy_id": "kristal.v5:validation-policy:health-reference",
  "validated_as": "institutional_reference",
  "certainty_level": "high",
  "scope_domain": "health",
  "validation_status": "validated"
}
```

### Assertion-level issue log

```json
{
  "ts": "2026-01-07T14:11:19Z",
  "level": "WARN",
  "service": "kristal-validator",
  "stage": "validate",
  "event": "VALIDATION_POLICY_FAILED",
  "build_id": "f3a2c6f8-7dd4-4a5f-9b84-4a0a7b1d0d0d",
  "tenant_id": "tenant_123",
  "assertion_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "error_code": "KRS_V5_CERTAINTY_LEVEL_INVALID",
  "reason_code": "certainty_too_low_for_policy",
  "error_message": "The active validation policy requires high certainty for this scope.",
  "certainty_level": "medium",
  "validated_as": "sourced_claim",
  "duration_ms": 620
}
```

### Authority recognition log

```json
{
  "ts": "2026-01-07T14:12:03Z",
  "level": "INFO",
  "service": "authority-registry",
  "stage": "recognize",
  "event": "AUTHORITY_RECOGNITION_RECORDED",
  "build_id": "f3a2c6f8-7dd4-4a5f-9b84-4a0a7b1d0d0d",
  "tenant_id": "tenant_123",
  "recognition_id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
  "exchange_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "authority_channel_id": "authority:example-global-reference",
  "recognition_status": "recognized",
  "scope_domain": "education"
}
```

### Runtime Pack activation blocked by policy

```json
{
  "ts": "2026-01-07T14:13:45Z",
  "level": "WARN",
  "service": "konnaxion",
  "stage": "pack_activate",
  "event": "PACK_ACTIVATION_BLOCKED",
  "build_id": "f3a2c6f8-7dd4-4a5f-9b84-4a0a7b1d0d0d",
  "tenant_id": "tenant_123",
  "runtime_pack_id": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "reader_policy_id": "reader_policy:validated_only",
  "reason_code": "policy_failed",
  "error_code": "PACK_POLICY_REQUIREMENT_NOT_MET",
  "error_message": "The pack does not satisfy the active reader policy requirements."
}
```

### Reader policy filtering log

```json
{
  "ts": "2026-01-07T14:14:05Z",
  "level": "INFO",
  "service": "reader-policy-engine",
  "stage": "reader_policy_eval",
  "event": "READER_POLICY_FILTERED_ASSERTION",
  "build_id": "f3a2c6f8-7dd4-4a5f-9b84-4a0a7b1d0d0d",
  "tenant_id": "tenant_123",
  "reader_policy_id": "reader_policy:high_certainty_only",
  "assertion_id": "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
  "assertion_status": "sourced",
  "certainty_level": "low",
  "validation_status": "not_evaluated",
  "reason_code": "reader_policy_filtered"
}
```

## Appendix: recommended dashboards

Recommended dashboards include:

* build success rate by stage and tenant;
* compile success, partial, and failure counts;
* median and p95 stage duration;
* SenTient timeout rate and circuit breaker opens;
* validation report issue counts by severity and code;
* validation decision counts by authority channel and scope;
* authority recognition status by authority channel;
* uncertainty and disputed assertion counts by corpus or shard;
* reader policy filtering rates;
* Runtime Pack publish, activation, rollback, and revocation events;
* DLQ depth and age;
* quarantine depth and age;
* top reason codes by service and stage.

## Appendix: recommended alerts

Recommended alerts include:

* repeated `HASH_MISMATCH`;
* repeated `SIGNATURE_VERIFY_FAILED`;
* validation timeout rate above threshold;
* authority recognition service unavailable;
* Runtime Pack activation failure spike;
* Konnaxion rollout rollback spike;
* DLQ age above threshold;
* quarantine growth above threshold;
* unexpected increase in `scope_mismatch`;
* unexpected increase in `reader_policy_unsupported`;
* unresolved SenTient ambiguity above threshold.

## Appendix: non-goals

This document does not define:

* Kristal artifact identity;
* schema hashing rules;
* signature verification rules;
* validation semantics;
* authority recognition semantics;
* reader policy semantics;
* Runtime Pack activation policy;
* audit-log retention policy;
* legal compliance policy.

Those are defined by their respective Kristal v5 specifications, profiles, operational policies, or deployment policies.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/08-ops/operational-guidance-template.md"
id=21a1f45b6bf0
kind=markdown
size=12058
lines=774
line_ref=1-774
chunks=3
chunk_refs=1-350,351-700,701-774
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=21a1f45b6bf0:1-350
start=1
end=350
----
# Operational guidance template

## Status

Template, non-normative.

## Purpose

A consistent structure for operational and implementation guidance across the Kristal ecosystem:

```text
Kristal
Orgo
SenTient
Architect
Konnaxion
Compiler
Client
Reader
Runtime
```

This template is **non-normative**. It does not define conformance requirements for Kristal artifacts.

Use it to document failure paths, resilience, observability, operational trade-offs, degraded conditions, reader policy behavior, authority recognition handling, and least-worst implementation choices.

This template describes operational behavior. It does not define truth, authority, certainty, validation status, or recognition status.

---

## 1) Concept

**Name:**
**One-liner:**
What it is.

**Applies to:**

```text
Kristal / Orgo / SenTient / Architect / Konnaxion / Compiler / Client / Reader / Runtime
```

**Lifecycle stage:**

```text
ingest
extract
normalize
structure
compile
review
validate
recognize
federate
package
distribute
activate
query
render
observe
recover
```

**Primary goal:**
Examples:

```text
availability
correctness
reproducibility
integrity
isolation
traceability
reader safety
status transparency
```

**Secondary goals:**
Examples:

```text
latency
cost
debuggability
operator clarity
offline usability
ecosystem interoperability
```

**Kristal v5 concepts involved:**

```text
Structured Epistemic State
Working Artifact
Reference Artifact
Exchange
Shard
Federation Manifest
Runtime Pack
Authority Channel
Authority Registry
Validation Decision
Authority Recognition
Reader Policy
Assertion Status
Certainty Level
```

---

## 2) Problem

**What can go wrong?**

Failure modes:

```text
timeouts
partial outputs
poisoned inputs
overload
nondeterminism
cache corruption
hash mismatch
signature mismatch
authority registry unavailable
reader policy mismatch
scope mismatch
stale runtime pack
incomplete shard
conflicting federation inputs
ambiguous assertion status
missing certainty metadata
missing validation decision
missing authority recognition
profile artifact mismatch
projection mismatch
```

Blast radius:

```text
single assertion
single shard
single build
single runtime pack
single authority channel
single tenant
single reader policy
single region
federated distribution
global distribution
```

User-facing impact:

```text
missing pack
stale knowledge
incorrect rendering
unavailable query
incomplete labels
blocked publication
blocked activation
unrecognized artifact
disputed result shown without enough context
validated-only view hiding lower-status material
research view exposing disputed material with labels
```

**How it fails today, if known:**

Symptoms:

```text
```

Triggers:

```text
```

Observed frequency:

```text
```

---

## 3) Solution

**Approach:**
What you do and why.

**Mechanics:**

Inputs:

```text
```

Outputs:

```text
```

State transitions:

```text
```

Retry policy:

```text
```

Backoff policy:

```text
```

Quarantine / dead-letter policy:

```text
```

Timeouts and resource limits:

```text
```

Determinism guarantees:

```text
```

Specify what must remain identical across reruns, such as:

```text
content-addressed IDs
canonicalized hash targets
query results under the same snapshot and reader policy
build records
validation decision references
authority recognition references
runtime pack manifests
```

**Data contracts / artifacts involved:**

Use only the relevant entries:

```text
Structured Epistemic State
Exchange
Exchange Shard Manifest
Exchange Federation Manifest
Runtime Pack Manifest
Authority Registry
Validation Decision
Authority Recognition
Reader Policy
Validation Report
Review Bundle
Revocation Record
Claim-IR
Resolved Claim-IR
```

`Claim-IR` and `Resolved Claim-IR` are extraction or resolution profiles. They are not the universal required input path for Kristal v5.

**IDs that must be carried end-to-end:**

Use only the relevant entries:

```text
build_id
state_id
kristal_id
exchange_id
shard_id
federation_id
runtime_pack_id
assertion_id
evidence_id
validation_decision_id
recognition_id
authority_channel_id
reader_policy_id
tenant_id
correlation_id
```

**Security and integrity considerations:**

```text
trust roots
signature verification points
hash verification points
authority registry verification
reader policy enforcement
tenant isolation boundaries
downgrade and rollback rules
revocation handling
key rotation
runtime pack activation requirements
profile artifact verification
```

**Status and policy considerations:**

Specify how the solution preserves or reports:

```text
artifact_status
assertion_status
certainty_level
validation_status
validated_as
recognition_status
authority_channel
scope
reader_policy
reason_codes
```

---

## 4) When to use

**Use when:**

Examples:

```text
a dependency is flaky
workload spikes
offline distribution is required
RDF canonicalization is expensive
authority registry access is intermittent
runtime pack activation must be delayed
reader policy must hide non-recognized material
a shard is incomplete but still useful for review
a validation decision is pending
a research view should expose lower-certainty material
```

**Do not use when:**

Examples:
--- CHUNK END ---

--- CHUNK BEGIN ---
id=21a1f45b6bf0:351-700
start=351
end=700
----

```text
it would hide status labels
it would mask integrity failures
it would present unresolved ambiguity as resolved fact
it would present scoped validation as universal truth
it would introduce nondeterministic content-addressed outputs
it would silently merge conflicting authority channels
it would enlarge the normative surface area without need
```

**Preconditions / dependencies:**

Examples:

```text
feature flags
queue support
local disk cache
stable clock
monotonic counters
authority registry snapshot
reader policy snapshot
runtime pack inventory
signature verification keys
revocation list
profile support
local query index
```

---

## 5) Pitfalls and trade-offs

**Pitfalls:**

Examples:

```text
silent degradation
retry storms
inconsistent caches
partial acceptance of probabilistic results
ambiguous authority labels
missing certainty labels
reader policy drift
authority channel confusion
profile verification treated as truth validation
runtime activation treated as authority recognition
operational metadata affecting content hashes
downstream generation introducing new facts
```

**Trade-offs:**

Correctness vs availability:

```text
```

Latency vs cost:

```text
```

Reproducibility vs performance:

```text
```

Isolation vs deduplication:

```text
```

Strict reader policy vs exploratory access:

```text
```

Authority consistency vs plural federation:

```text
```

Offline usability vs freshness:

```text
```

**Anti-patterns to avoid:**

```text
Bypassing required integrity verification when integrity is declared.
Writing unresolved ambiguity as resolved fact.
Presenting scoped validation as universal truth.
Treating ShEx, SHACL, JSON Schema, or RDF projection conformance as authority recognition.
Treating runtime pack activation as claim validation.
Letting operational metadata affect content hashes or IDs.
Making downstream generation introduce new facts.
Silently merging conflicting shards.
Hiding disputed, rejected, fictional, mythological, or low-certainty status.
Treating "validated-only" as "maximum certainty only."
```

---

## 6) Observability

**Logs: structured fields**

Required where applicable:

```text
tenant_id
build_id
state_id
kristal_id
exchange_id
shard_id
federation_id
runtime_pack_id
assertion_id
validation_decision_id
recognition_id
authority_channel_id
reader_policy_id
stage
attempt
duration_ms
outcome
error_code
reason_codes
dependency
correlation_id
```

Allowed `outcome` values:

```text
success
fail
partial
blocked
skipped
degraded
not_applicable
```

**Metrics:**

```text
throughput_items_per_sec
success_rate
failure_rate
partial_rate
blocked_rate
retry_rate
queue_depth
queue_lag_ms
cache_hit_rate
hash_verification_failures
signature_verification_failures
authority_registry_failures
validation_error_counts_by_code
recognition_error_counts_by_code
reader_policy_exclusion_counts
runtime_pack_activation_failures
query_error_rate
render_label_omission_count
```

**Tracing:**

Correlation IDs SHOULD be propagated across services.

Recommended spans:

```text
ingest
extract
normalize
structure
compile
review
validate
recognize
federate
package
distribute
activate
query
render
profile_verify
recover
```

**Dashboards / alerts:**

SLOs:

```text
```

Paging thresholds:

```text
```

Anomaly detection:

```text
```

Recommended alert dimensions:

```text
authority_channel_id
reader_policy_id
tenant_id
runtime_pack_id
stage
error_code
reason_code
```

---

## 7) Runbook

**Detection:**

What alerts fire?

```text
```

What dashboards to check first?

```text
```

**Mitigation:**

Step-by-step actions, ordered:

```text
1.
2.
3.
```

Safe fallback modes:

```text
```

Fallback modes must preserve:

```text
deterministic behavior where declared
status visibility
authority labels
certainty labels
reader policy behavior
artifact identity
integrity labels
```

How to quarantine inputs:

```text
```

How to disable a profile:

```text
```

How to roll back a runtime pack:

```text
```

How to block activation without deleting the candidate artifact:

```text
```

How to preserve user-visible labels during degraded operation:

```text
```

**Recovery:**

Criteria for returning to normal mode:

```text
```

Post-incident checks:

```text
reproducibility tests
hash verification
signature verification
authority registry consistency
reader policy consistency
runtime pack inventory consistency
cache consistency
query consistency
render label checks
revocation checks
```

**Postmortem notes:**

Root cause:

```text
```

Prevent recurrence:

```text
```

Action items:

```text
-
-
-
```

---

## 8) Example

Optional.

**Scenario:**

```text
```

**Before:**

```text
--- CHUNK END ---

--- CHUNK BEGIN ---
id=21a1f45b6bf0:701-774
start=701
end=774
----
```

**After:**

```text
```

**Key outputs: sample log fields**

```json
{
  "tenant_id": "tenant:example",
  "build_id": "build:2026-06-12T00:00:00Z:example",
  "state_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
  "kristal_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
  "shard_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
  "authority_channel_id": "authority:example",
  "reader_policy_id": "reader_policy:validated_only",
  "stage": "validate",
  "attempt": 1,
  "duration_ms": 1234,
  "outcome": "partial",
  "error_code": "AUTHORITY_REGISTRY_TIMEOUT",
  "reason_codes": [
    "authority_not_recognized"
  ],
  "dependency": "authority-registry",
  "correlation_id": "corr:example"
}
```

---

## 9) Versioning and ownership

**Owner team:**

```text
```

**Last updated:**

```text
```

**Applies to versions:**

```text
Kristal v5.0
```

Optional ecosystem versions:

```text
Orgo:
SenTient:
Architect:
Konnaxion:
Compiler:
Runtime:
Reader:
```

**Change policy:**

This template is non-normative. Changes to the template do not change Kristal artifact conformance requirements.

If a guidance page introduces normative requirements, those requirements must be moved to the appropriate Kristal v5 specification, schema, profile, or contract.

**Change log:**

```text
YYYY-MM-DD:
```
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/08-ops/release-strategies.md"
id=49f83ff2ffd2
kind=markdown
size=21787
lines=752
line_ref=1-752
chunks=3
chunk_refs=1-350,351-700,701-752
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=49f83ff2ffd2:1-350
start=1
end=350
----
# Release Strategies for Kristal Runtime Packs (Blue/Green, Canary)

## Status

Draft — non-normative operational guidance for Kristal v5.

## Purpose

This document defines operational release strategies for distributing **Kristal Runtime Packs** to online, offline, constrained, or intermittently connected environments.

It provides recommended operational patterns for Orgo as the control plane and Konnaxion as the distribution and client-facing layer.

The goals are to preserve:

* deterministic artifacts;
* required integrity verification;
* auditable release records;
* downgrade and rollback safety;
* clear artifact status;
* validation, certainty, authority, and reader-policy labels.

This document is **non-normative**. It does not change Kristal artifact formats, schema conformance, validation policy, authority recognition, or reader-policy semantics.

It assumes channels may use a signed channel index, such as `pack_index.json`, as the primary control surface for rollout, rollback, staged activation, and client selection.

---

# 1. Terms and goals

## 1.1 Terms

* **Pack**: a Kristal Runtime Pack artifact, including manifest and payloads.
* **Pack version**: a monotonic version within a channel used for activation and downgrade prevention, commonly recorded as `pack_version`.
* **Runtime Pack ID**: content-addressed identifier for an immutable Runtime Pack.
* **Source artifact status**: whether the pack derives from a `working` artifact, `reference` artifact, or other declared source status.
* **Release**: a versioned publication event, normally recorded by Orgo, referencing a pack, channel scope, signer, status, and policy context.
* **Channel**: a distribution target grouping, such as tenant, environment, region, device cohort, authority channel, or reader-policy channel.
* **Channel pack index**: a signed per-channel index, for example `pack_index.json`, containing channel metadata, latest pointers, pinned pointers, minimum allowed version, revoked pack IDs, reader-policy constraints, and activation rules.
* **Cohort**: a deterministic subset of a channel, such as 1% of devices.
* **Reader policy**: a declared policy controlling which data is visible to a user or application.
* **Authority channel**: a scoped authority source whose recognition, validation, or publication status may affect reader-policy selection.
* **Activation**: the local switch from one active Runtime Pack to another.

## 1.2 Goals

Release strategies SHOULD:

* minimize blast radius of a bad pack release;
* prevent activation of packs that fail required integrity, schema, compatibility, or policy checks;
* support explicit rollback without creating downgrade vulnerabilities;
* maintain auditable linkage from build to release to distribution index to device state;
* preserve validation labels, certainty labels, authority-channel labels, source lineage, and reader-policy context;
* allow offline clients to make deterministic activation decisions from locally available policy data.

A “bad pack” may mean:

* corrupted or incomplete payloads;
* invalid signatures or hashes;
* incompatible query contract;
* broken indexes;
* unacceptable performance;
* missing labels required by reader policy;
* missing authority registry or revocation data required by activation policy;
* incorrect pack construction relative to declared policies.

It does not mean that all contained assertions are globally false or true. Kristal v5 separates Runtime Pack integrity from semantic validation, authority recognition, and certainty.

---

# 2. Release invariants

These invariants SHOULD hold regardless of rollout strategy.

## 2.1 Immutable pack identity

A `runtime_pack_id` identifies immutable content.

Implementations MUST NOT “fix” a Runtime Pack in place.

If the manifest, payloads, indexes, labels, policies, or metadata change, the result is a new Runtime Pack with a new content-addressed identity.

## 2.2 Required verification

If signatures, hashes, trust roots, authority registry references, revocation requirements, or compatibility requirements are declared by the active channel policy, every distribution node and client SHOULD verify them before activation.

If a signed channel index is used, clients SHOULD verify the index using pinned trust roots or an Authority Registry policy before applying it.

A pack that fails required verification MUST NOT become active for that channel.

It MAY remain inspectable as an inactive or diagnostic candidate if the interface clearly marks it as not accepted under the selected policy.

## 2.3 Activation gating and atomic activation

Activation SHOULD occur only after required checks pass.

Typical checks include:

* manifest schema validity;
* content hash verification;
* payload file presence;
* signature verification, if required;
* authority registry availability, if required;
* revocation policy evaluation, if required;
* downgrade and rollback policy evaluation;
* query contract compatibility;
* reader-policy compatibility;
* Runtime Pack construction-policy compatibility;
* required label availability;
* local smoke tests.

Activation SHOULD be an atomic switch from old to new.

Partial activation SHOULD NOT occur.

## 2.4 Auditable release records

Every activation SHOULD be traceable to:

* `channel_id`;
* `runtime_pack_id`;
* `pack_version`;
* `source_exchange_ref`;
* `source_artifact_status`;
* signer;
* authority channel, if applicable;
* reader policy, if applicable;
* activation policy;
* timestamp;
* local verification result;
* Orgo release record, if present.

## 2.5 Explicit rollback and downgrade policy

Downgrades SHOULD be prevented by default.

Rollback SHOULD be explicit, auditable, deterministic, and revocation-aware.

A client SHOULD NOT activate an older pack unless the channel index, local policy, or operator action explicitly authorizes rollback.

## 2.6 Label preservation

Release and activation procedures MUST NOT erase or flatten Kristal v5 epistemic labels.

The following labels, when present and required by reader policy, SHOULD remain traceable after release:

* `artifact_status`;
* `assertion_status`;
* `validation_status`;
* `certainty_level`;
* `validated_as`;
* `authority_channel`;
* `recognition_status`;
* `scope`;
* `provenance_refs`;
* `evidence_refs`;
* `lineage`.

A release process MUST NOT present a pack derived from a working artifact as a reference artifact unless a valid recognition or release policy explicitly supports that status.

---

# 3. Channel pack index

## 3.1 Purpose

A channel pack index is a signed control object used to determine which Runtime Pack is current, staged, pinned, revoked, or allowed for a given channel.

Common filename:

```text
pack_index.json
```

The exact schema is deployment-specific unless standardized by a separate profile.

## 3.2 Recommended contents

A channel pack index SHOULD contain:

* `channel_id`;
* `channel_scope`;
* `latest`;
* `pinned`;
* `staged`;
* `canary`;
* `minimum_allowed_version`;
* `revoked`;
* `reader_policy_refs`;
* `authority_registry_ref`;
* `activation_policy_ref`;
* `rollback_policy_ref`;
* `updated_at`;
* `signer_key_id`;
* `signatures`.

## 3.3 Latest pointer

`latest` identifies the pack or packs that should normally become active for the channel.

## 3.4 Pinned pointer

`pinned` identifies known-good packs that may be used for rollback, recovery, or offline continuity.

A pinned pack is not automatically current. It is a controlled fallback target.

## 3.5 Staged pointer

`staged` identifies candidate packs that may be downloaded, verified, warmed up, or tested before activation.

## 3.6 Canary pointer

`canary` identifies packs that should be activated only by selected cohorts.

Cohort selection SHOULD be deterministic.

## 3.7 Minimum allowed version

`minimum_allowed_version` prevents activation of packs below a declared version threshold.

Clients SHOULD persist the highest activated version per channel and apply local anti-downgrade policy alongside the signed channel index.

## 3.8 Revoked packs

`revoked` identifies pack IDs or versions that must not be activated under the channel policy.

Revocation SHOULD include a reason code and effective time.

---

# 4. Blue/Green releases

## 4.1 Concept

Blue/Green releases maintain two production slots per channel:

* **Blue**: current active pack version;
* **Green**: new candidate pack version.

Devices or nodes switch to Green only after Green has passed required checks under the channel policy.

## 4.2 Procedure

### Step 1 — Publish Green

Orgo publishes a release record referencing:

* new `runtime_pack_id`;
* `pack_version`;
* source artifact references;
* source artifact status;
* channel scope;
* signer;
* build record;
* declared Runtime Pack policies;
* reader-policy references;
* authority registry reference, if applicable.

Konnaxion replicates pack payloads to the Green slot or staged cache location.

### Step 2 — Verify at rest

Edge nodes or devices verify:

* manifest schema validity;
* payload file presence;
* payload hashes;
* signatures, if required;
* channel index signature, if used;
* Authority Registry reference, if required;
* revocation policy, if required;
* query contract compatibility;
* Runtime Pack policy compatibility;
* reader-policy compatibility;
* required label availability.

Any required verification failure blocks activation.

The candidate may remain staged for diagnostics.

### Step 3 — Warm-up and readiness checks

Run pack-local checks such as:

* query smoke tests;
* pagination checks;
* join behavior checks;
* reader-policy filter checks;
* authority-channel filter checks;
* validation-status and certainty-level filter checks;
* memory footprint thresholds;
* latency thresholds;
* payload integrity re-checks where appropriate.

Outcomes SHOULD be logged with correlation IDs.

### Step 4 — Switch traffic through signed channel index

Update the channel pack index:

* set `latest` to the Green pack;
* optionally keep Blue in `pinned`;
* update `minimum_allowed_version` if needed;
* add revoked pack IDs if needed;
* preserve reader-policy and authority-policy metadata.

Sign the updated index.

Clients verify the updated index before applying it.

Devices activate Green using an atomic switch.

### Step 5 — Post-switch monitoring

Observe:

* verification failures;
* activation failures;
* query error rates;
* pagination errors;
* unsupported filter errors;
* reader-policy mismatches;
* latency;
* memory pressure;
* pack download failures;
* unexpected rollback attempts.

If thresholds fail, trigger explicit rollback.

## 4.3 Advantages

Blue/Green releases provide:

* simple operational model;
* predictable rollback target;
* clean staging;
* offline-friendly activation;
* easy auditability.

## 4.4 Pitfalls

Blue/Green releases may require:

* additional storage;
* explicit split-brain tolerance for offline devices;
* clear audit records for asynchronous activation;
* careful handling of reader-policy and authority-policy changes.

Offline devices may remain on Blue longer than online devices. This is acceptable if the pack remains valid under channel policy.

---
--- CHUNK END ---

--- CHUNK BEGIN ---
id=49f83ff2ffd2:351-700
start=351
end=700
----

# 5. Canary releases

## 5.1 Concept

Canary releases roll out a new pack to a small cohort first, observe behavior, then expand.

Canary is recommended for high-risk changes, such as:

* new Runtime Pack construction policies;
* new query contract versions;
* new reader-policy filtering;
* new authority-channel filtering;
* new validation or certainty materialization;
* large dataset changes;
* new client versions;
* new compression or index formats.

## 5.2 Procedure

### Step 1 — Create cohorts

Example stages:

* 1%;
* 10%;
* 50%;
* 100%.

Cohorts SHOULD be stable and deterministic.

Example cohort rule:

```text
hash(device_id) mod 100 < cohort_percentage
```

### Step 2 — Publish candidate pack

Publish and stage the pack as in Blue/Green.

The pack should be available before cohort activation begins.

### Step 3 — Update channel index for canary

Update the channel pack index so only selected cohorts resolve current pack selection to the canary pack.

The distribution index is the primary control point for staged releases.

The index update SHOULD include:

* canary pack pointer;
* cohort rule;
* cohort percentage;
* observation window;
* rollback target;
* relevant reader policy;
* relevant authority policy.

Sign and distribute the updated index.

Clients verify the index before applying it.

### Step 4 — Activation gating

Canary devices verify:

* integrity;
* schema validity;
* contract compatibility;
* reader-policy compatibility;
* authority registry requirements;
* revocation requirements;
* local smoke tests.

Activation occurs only if required checks pass.

### Step 5 — Promote

After the observation window, expand cohorts by updating and signing the channel index.

Promotion steps SHOULD be auditable and deterministic.

### Step 6 — Abort and rollback

If health metrics fail:

* stop promotion;
* revert affected cohorts to previous index pointers;
* mark the failed pack as blocked or revoked if appropriate;
* preserve release and activation audit records;
* avoid silent downgrade behavior.

## 5.3 Metrics to watch

Canary metrics SHOULD include:

* manifest verification failures;
* payload hash verification failures;
* index signature verification failures;
* Runtime Pack activation failures;
* query error rates;
* pagination errors;
* unsupported filter errors;
* reader-policy mismatch errors;
* authority-registry mismatch errors;
* validation-status filter errors;
* certainty-level filter errors;
* median and P95 query latency;
* memory pressure;
* out-of-memory events;
* pack download failures;
* excessive download size complaints;
* unexpected cardinality or pagination behavior.

## 5.4 Pitfalls

Canary releases require:

* stable cohort assignment;
* clean cohort targeting;
* auditable index updates;
* compatible offline behavior.

Offline devices may skip cohorts or activate later. Treat cohort targeting as best-effort and rely on activation-time verification, local checks, and audit records.

---

# 6. Rollback and downgrade safety

Rollback is operationally necessary.

Uncontrolled downgrade is a security and integrity risk.

## 6.1 Default anti-downgrade rule

Clients SHOULD NOT activate a pack whose `pack_version` is lower than the currently active pack for the same channel unless an explicit rollback policy authorizes it.

Clients SHOULD persist:

* active pack ID;
* active pack version;
* highest activated pack version;
* active channel ID;
* activation timestamp;
* activation policy;
* rollback authorization, if any.

## 6.2 Rollback targets

Preferred rollback targets are:

* a pinned known-good pack;
* the last-known-good previously active pack;
* a recovery pack explicitly authorized by policy.

A rollback target must still satisfy applicable verification, revocation, and activation requirements.

## 6.3 Minimum version pin

A channel index SHOULD maintain:

```text
minimum_allowed_version
```

Clients SHOULD NOT activate packs below this minimum, even if cached, unless an explicit emergency policy allows it.

## 6.4 Revocation

If a pack is discovered to be invalid, vulnerable, corrupted, mislabeled, or unsafe to activate:

* add it to `revoked` in the signed channel index;
* update revocation lists if used;
* raise `minimum_allowed_version` if needed;
* publish a replacement pack when appropriate.

## 6.5 Rollback audit

Rollback events SHOULD record:

* rollback reason;
* operator or authority;
* previous pack;
* rollback target;
* channel ID;
* device or cohort scope;
* timestamp;
* policy reference;
* verification result.

---

# 7. Offline and constrained environments

## 7.1 Activation is local and asynchronous

Offline devices may:

* download a pack later than publication;
* activate it later than download;
* miss intermediate canary stages;
* remain on older packs for extended periods.

Therefore:

* required verification SHOULD occur at activation time;
* activation decisions SHOULD be stored locally;
* devices SHOULD record audit markers;
* clients SHOULD avoid silent downgrade.

Recommended audit marker:

```text
channel_id + runtime_pack_id + pack_version + activation_policy + timestamp
```

## 7.2 Holding behavior

If a device is offline and only has older packs available, and rollback is not explicitly authorized, the correct behavior is to hold the current active pack rather than silently downgrade.

If the current pack is revoked and no valid replacement is available, the client SHOULD expose a clear inactive, degraded, or unavailable status according to deployment policy.

## 7.3 Storage constraints

If devices cannot hold Blue and Green simultaneously, they SHOULD retain at minimum:

* current active manifest;
* previous active manifest, if available;
* signatures;
* pack index material;
* revocation material;
* enough metadata to justify activation and rollback decisions.

Deployments MAY implement a checkpoint pack strategy, retaining last-known-good payloads where feasible.

## 7.4 Delta updates

If packs are large, deployments MAY use delta distribution at the transport layer.

The final reconstructed payloads MUST match the hashes declared in the Runtime Pack manifest.

Delta transport MUST NOT change Runtime Pack identity.

---

# 8. Suggested control-plane data model

A practical Orgo/Konnaxion release system typically maintains the following records.

## 8.1 Build Record

```text
BuildRecord(
  build_id,
  runtime_pack_id,
  source_exchange_ref,
  source_artifact_status,
  compiler_version,
  config_hash,
  policies,
  inputs,
  signatures,
  compile_status,
  validation_status,
  recognition_status,
  created_at
)
```

## 8.2 Release Record

```text
ReleaseRecord(
  release_id,
  channel_id,
  runtime_pack_id,
  pack_version,
  signing_key_id,
  source_artifact_status,
  reader_policy_refs,
  authority_registry_ref,
  published_at,
  status
)
```

## 8.3 Channel Pack Index

```text
ChannelPackIndex(
  channel_id,
  latest,
  staged,
  canary,
  pinned,
  minimum_allowed_version,
  revoked,
  reader_policy_refs,
  authority_registry_ref,
  signature,
  signer_key_id,
  updated_at
)
```

## 8.4 Device State

```text
DeviceState(
  device_id,
  channel_id,
  active_pack_id,
  active_pack_version,
  highest_activated_pack_version,
  active_reader_policy,
  authority_registry_ref,
  last_verified_at,
  verification_status,
  activation_status
)
```

These models are illustrative. Exact implementation is system-specific.

---

# 9. Recommended default strategy

For most deployments:

* use Blue/Green as the default;
* add Canary for high-risk changes;
* keep a pinned known-good pack during the rollback window;
* sign channel pack indexes;
* verify required material before activation;
* preserve activation audit records.

Canary is especially useful for:

* new portable policies;
* new ordering or row-grouping strategies;
* new membership filters;
* new bitmap formats;
* large schema changes;
* new query extensions;
* new reader-policy behavior;
* new authority-channel filters;
* new validation or certainty materialization;
* new client versions.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=49f83ff2ffd2:701-752
start=701
end=752
----

---

# 10. Checklist

## 10.1 Blue/Green

* [ ] Pack published and staged.
* [ ] Manifest schema verified.
* [ ] Payload hashes verified.
* [ ] Signatures verified if required.
* [ ] Authority Registry available if required.
* [ ] Revocation policy evaluated if required.
* [ ] Query contract compatibility checked.
* [ ] Runtime Pack policy compatibility checked.
* [ ] Reader-policy compatibility checked.
* [ ] Required labels available.
* [ ] Smoke tests pass.
* [ ] Channel index updated and signed.
* [ ] Green set as `latest`.
* [ ] Blue retained as pinned rollback target.
* [ ] Monitoring and rollback window defined.
* [ ] `minimum_allowed_version` updated when needed.
* [ ] `revoked` updated when needed.
* [ ] Activation audit records preserved.

## 10.2 Canary

* [ ] Cohorts stable and targetable.
* [ ] Candidate pack published and staged.
* [ ] Canary targeting represented in signed channel index.
* [ ] Observation metrics defined.
* [ ] Promotion steps defined.
* [ ] Rollback target defined.
* [ ] Abort path defined.
* [ ] Offline activation still verifies required material.
* [ ] Smoke tests include reader-policy and query behavior.
* [ ] Audit records preserve cohort, pack, channel, signer, and policy context.

---

# 11. Summary

Kristal v5 Runtime Pack releases are operational events over immutable artifacts.

Blue/Green provides a clean default rollout strategy.

Canary reduces risk for high-impact changes.

Rollback is allowed, but it must be explicit, auditable, policy-bound, and downgrade-safe.

Release strategy does not decide what is universally true. It decides which immutable pack is active for a channel, under which policy, with which verification, reader-policy, authority, validation, certainty, and audit context.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/09-test-vectors/jcs/expected-hashes.txt"
id=3a6bdc9be4ff
kind=source
size=865
lines=15
line_ref=1-15
chunks=0
chunk_refs=
summary="Source file."
----
000001 | # Kristal v5 JCS test vectors — expected hashes
000002 | # Hash algorithm: SHA-256
000003 | # Hash input: UTF-8 bytes of expected_canonical_json (RFC 8785 JCS output)
000004 | # Canonicalization profile: kristal.v5:jcs-rfc8785
000005 | # Canonicalization version: 1
000006 | # Format: <vector_id> <sha256_hex>
000007 | 
000008 | jcs-001 43258cff783fe7036d8a43033f830adfc60ec037382473548ac742b888292777
000009 | jcs-002 59d176cd99b72175a563664f429ecec5d1cb31754d7d090b0592bda9b53fc021
000010 | jcs-003 1956211cdd1b997e12419186832911195c511ff444db406c7e53fd35b600e21d
000011 | jcs-004 17073ac6186d8c60c0c0da712ce30cdb52ed5a9155f616983da39a9785dce715
000012 | jcs-005 31966e8f9b0d5b511eab8f56edc1edb07c7403f8bd904a165c0025b0503ec0e3
000013 | jcs-006 49b33db53718cfff9f0ca7cef74a955f68e0bdb941774e5fd92b75c3fd658a6c
000014 | jcs-007 8811ce97e7b0a5549448d9c8243ec05ba8fb57a40354b82b1d0c5c513cc63856
000015 | jcs-008 53152b34512bdb2f05bbfa2d41f4f7e5e379e5df67c831f3039ccacc7b1ea7bd
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/09-test-vectors/jcs/README.md"
id=75033c08f888
kind=markdown
size=12211
lines=364
line_ref=1-364
chunks=2
chunk_refs=1-350,351-364
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=75033c08f888:1-350
start=1
end=350
----
# JCS Test Vectors (Kristal v5)

## Status

Draft (normative test-vector guidance)

## Purpose

This folder contains golden test vectors for Kristal v5 canonicalization and content-addressed identity rules.

Kristal v5 requires that:

* `canonical_json` uses RFC 8785 JSON Canonicalization Scheme (JCS);
* content-addressed IDs are computed from canonicalized JSON bytes;
* signatures are excluded from content-addressed identity;
* tenant-local metadata, access-control metadata, workflow state, distribution state, and runtime activation state are excluded from global content identity;
* validation status, certainty metadata, authority recognition references, and reader-policy metadata are included or excluded according to the artifact’s declared content boundary.

For an artifact whose global identity is content-derived, the default rule is:

```text id="8e3zfh"
sha256(JCS(json_object_without_signatures_and_non_content_control_metadata))
```

These vectors ensure that independent implementations in different languages compute identical canonical bytes and identical hashes for the same declared artifact boundary.

## Files in this folder

* `vectors.json`
  A collection of JCS input cases and expected canonical outputs.

* `expected-hashes.txt`
  Expected SHA-256 hashes for each vector’s canonical output.

## Vector format

Each entry in `vectors.json` SHOULD use the following shape:

```json id="nmg708"
{
  "id": "jcs-0001",
  "description": "Brief description of the case",
  "profile": "kristal.v5:jcs-rfc8785",
  "artifact_type": "generic_json",
  "content_boundary": {
    "exclude_fields": []
  },
  "input": {
    "...": "original JSON object"
  },
  "expected_canonical": "{\"a\":1,\"b\":2}",
  "expected_sha256_hex": "..."
}
```

Notes:

* `profile` SHOULD be `kristal.v5:jcs-rfc8785`.
* `expected_canonical` MUST be the exact UTF-8 string output of JCS.
* `expected_sha256_hex` MUST be the SHA-256 digest of `expected_canonical` bytes, represented as lower-case hexadecimal.
* `content_boundary.exclude_fields` SHOULD declare any excluded fields, such as signatures or tenant-local control metadata.
* Implementations MAY split `expected_sha256_hex` into `expected-hashes.txt` instead of embedding it in JSON, but the correspondence MUST be unambiguous.

## Required coverage

The vector set MUST include cases covering the following areas.

### 1. Object key ordering

The vector set MUST include:

* keys out of order in input;
* nested objects;
* repeated ordering checks across different object depths;
* objects containing arrays and nested objects.

### 2. Arrays

The vector set MUST include:

* arrays preserving order;
* nested arrays;
* arrays containing objects;
* arrays containing mixed JSON scalar values.

### 3. Numbers

The vector set MUST include:

* integers;
* floating-point values;
* negative values;
* zero;
* exponent notation;
* values that must not be represented in a non-canonical form.

Implementations MUST NOT apply language-specific or platform-specific numeric formatting beyond RFC 8785 requirements.

### 4. Strings and escaping

The vector set MUST include:

* quotes;
* backslashes;
* unicode characters;
* unicode escape equivalence;
* control characters;
* strings containing visually similar but byte-distinct characters where relevant.

### 5. Booleans and null

The vector set MUST include:

* `true`;
* `false`;
* `null`.

### 6. Signature exclusion fixture

The vector set MUST include at least one fixture where:

* the input contains a signature envelope section or mock signature fields;
* the canonicalization/hash input explicitly excludes those fields;
* the expected canonical output corresponds to the object after signature exclusion.

This ensures implementations match Kristal’s rule:

```text id="9xhncg"
remove signatures -> canonicalize -> hash
```

The following field names SHOULD be treated as signature fields when the artifact profile declares them outside the content boundary:

* `signatures`
* `signature`
* `proof`
* `proofs`
* `jws`
* `detached_signatures`

The exact excluded fields MUST be declared by the artifact profile or vector metadata.

### 7. Tenant metadata exclusion fixture

The vector set MUST include at least one fixture where:

* the input contains tenant-local metadata;
* the global content identity excludes that tenant-local metadata;
* two inputs with identical content and different tenant metadata produce the same canonical output and hash.

Examples of tenant-local metadata include:

* `tenant_id`
* `tenant_artifact_handle`
* `acl`
* `access_control`
* `workflow_state`
* `approval_state`
* `distribution_status`
* `activation_status`
* `cache_state`
* `reader_session`

These fields MUST NOT influence global content IDs unless a specific derived artifact profile explicitly declares them inside its content boundary.

### 8. Validation and certainty boundary fixture

The vector set MUST include at least one fixture demonstrating whether validation and certainty metadata are inside or outside the content boundary for a given artifact type.

For Kristal v5:

* validation references may be part of an Exchange content boundary when the Exchange declares them as content;
* authority recognition references may be part of an Exchange content boundary when the Exchange declares them as content;
* reader-policy selections are usually control-plane or view-plane metadata unless a derived reader-policy artifact declares them as content;
* workflow state is not part of the global Exchange content boundary.

The vector metadata MUST make the boundary explicit.

### 9. Derived view fixture

The vector set SHOULD include a fixture for a derived reader-policy view where the view itself has a declared content boundary.

Example:

* source Exchange remains unchanged;
* reader-policy-filtered output is represented as a derived artifact;
* the derived artifact receives its own hash based on its declared content boundary.

This prevents implementations from accidentally reusing the source Exchange identity for a filtered or transformed view.

## How to use these vectors

### Step 1: Determine the content boundary

For each vector:

1. Read the vector metadata.
2. Determine which fields are inside the declared content boundary.
3. Remove excluded fields before canonicalization.
4. Do not remove fields that are explicitly part of the declared artifact content.

### Step 2: Canonicalization

For each vector:

1. Parse `input` into an in-memory JSON object.
2. Apply the declared content-boundary exclusions.
3. Serialize the resulting object using RFC 8785 JCS.
4. Compare the resulting UTF-8 bytes to `expected_canonical`.

### Step 3: Hashing

For each vector:

1. Compute SHA-256 over the canonical bytes.
2. Compare the result to `expected_sha256_hex` or to the corresponding line in `expected-hashes.txt`.

Any mismatch indicates that:

* the implementation is not RFC 8785 compliant;
* the implementation is applying additional transformations;
* excluded fields were not removed correctly;
* required content fields were incorrectly removed;
* the declared content boundary was misapplied;
* the vector’s expected value is incorrect and must be corrected through the test-vector update process.

## Conformance requirement

A Kristal v5 core implementation MUST:

* ship or reference a JCS vector set;
* pass the required JCS canonicalization vectors in CI;
* pass the required signature-exclusion vectors in CI;
* pass the required tenant-metadata exclusion vectors in CI;
* apply declared content boundaries consistently;
* compute SHA-256 over the exact canonical UTF-8 bytes.

If an implementation claims Kristal v5 core conformance but fails these vectors, its content-addressed IDs are not interoperable.

## Updating the vectors

### Versioning

If vectors change materially:

* increment the vector set version;
* preserve old vectors where possible;
* add a changelog entry outside the normative test data;
* avoid changing expected output for existing vector IDs unless correcting a documented vector error.

`vectors.json` SHOULD include root-level metadata similar to:

```json id="9etgcs"
{
  "vector_set_id": "kristal.v5:jcs-test-vectors",
  "vector_set_version": "5.0.0",
  "canonicalization_profile": "kristal.v5:jcs-rfc8785",
  "hash_alg": "sha256",
  "vectors": []
}
```

### Adding new vectors

Prefer adding new IDs rather than modifying existing ones.

Recommended ID format:

```text id="21der8"
jcs-v5-0001
jcs-v5-0002
jcs-v5-0003
```

Vector IDs MUST remain stable after publication.

## Suggested commands

The exact runner is language-specific, but a test runner should perform the equivalent of:

```text id="kb0efn"
load vectors.json
for each vector:
  boundary_input = apply_content_boundary(input, content_boundary)
  canonical = JCS(boundary_input)
  hash = sha256(canonical)
  assert canonical == expected_canonical
  assert hash == expected_sha256_hex
```

For vectors stored with `expected-hashes.txt`, the runner must also verify that each vector ID maps unambiguously to its expected hash.

## Interaction with Kristal v5 artifacts

### Exchange

Exchange identity uses the content boundary declared by the Exchange schema and profile.

Signatures MUST be excluded.

Tenant-local metadata MUST be excluded.

Validation references, certainty summaries, and authority recognition references are included only when declared as part of the Exchange content boundary.

### Runtime Pack

Runtime Pack identity uses the content boundary declared by the Runtime Pack manifest.

Runtime Pack signatures MUST be excluded from Runtime Pack content hashes.

Tenant-local cache state, installation state, activation state, and distribution state MUST be excluded unless explicitly declared in a separate tenant-scoped packaging profile.

### Authority Recognition

Authority recognition artifacts may be content-addressed.

Their signatures MUST be excluded from the recognition content hash.

The recognition decision itself, issuer authority channel, target reference, scope, recognized status, reason codes, and evidence references SHOULD be included in the content boundary.

### Validation Decision

Validation decision artifacts may be content-addressed.

Their signatures MUST be excluded from the validation decision content hash.

The validation status, validated-as status, certainty level, authority channel, target reference, findings, reason codes, and evidence references SHOULD be included in the content boundary.

### Reader Policy

Reader policy artifacts may be content-addressed when represented as portable artifacts.

If content-addressed, their selected authority channels, allowed statuses, certainty levels, included scopes, and fallback behavior SHOULD be included in the content boundary.

A reader session, UI state, user identity, or tenant-local access grant MUST NOT be included in the global reader-policy artifact hash.

## Non-goals

These vectors do not validate:

* epistemic truth;
* authority recognition;
* assertion correctness;
* certainty level accuracy;
* reader-policy appropriateness;
* RDF canonicalization;
* Runtime Pack query behavior.

They only verify JSON canonicalization, declared field exclusion, and SHA-256 hashing over the declared content boundary.

--- CHUNK END ---

--- CHUNK BEGIN ---
id=75033c08f888:351-364
start=351
end=364
----
## Summary

The JCS test vectors ensure that Kristal v5 implementations compute the same canonical JSON bytes and the same content-addressed IDs for the same declared artifact boundary.

The core rule is:

```text id="kmure7"
declare content boundary
remove excluded fields
canonicalize using RFC 8785 JCS
hash canonical UTF-8 bytes with SHA-256
```

This preserves deterministic identity while allowing Kristal v5 to separate artifact content from signatures, tenant-local metadata, workflow state, distribution state, activation state, and reader-session state.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/09-test-vectors/jcs/vectors.json"
id=efba40925aac
kind=source
size=7845
lines=190
line_ref=1-190
chunks=0
chunk_refs=
summary="Source file."
----
000001 | {
000002 |   "schema_version": "5.0",
000003 |   "artifact_type": "jcs_test_vectors",
000004 |   "canonicalization_profile": "kristal.v5:jcs-rfc8785",
000005 |   "canonicalization_version": "1",
000006 |   "hash_alg": "sha256",
000007 |   "generated_at": "2026-06-12T16:22:19Z",
000008 |   "notes": [
000009 |     "These vectors avoid floating-point numbers to prevent implementation-dependent number formatting.",
000010 |     "Canonical strings are UTF-8 JSON strings with object keys sorted lexicographically and no insignificant whitespace.",
000011 |     "For hash-target vectors, excluded_json_pointers are removed before canonicalization and hashing."
000012 |   ],
000013 |   "vectors": [
000014 |     {
000015 |       "name": "empty_object",
000016 |       "description": "Canonicalization of an empty object.",
000017 |       "input": {},
000018 |       "excluded_json_pointers": [],
000019 |       "canonical": "{}",
000020 |       "sha256": "44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
000021 |     },
000022 |     {
000023 |       "name": "sorted_keys_nested",
000024 |       "description": "Object keys are sorted lexicographically at every object level; array order is preserved.",
000025 |       "input": {
000026 |         "z": "last",
000027 |         "a": {
000028 |           "b": 2,
000029 |           "a": 1
000030 |         },
000031 |         "m": [
000032 |           {
000033 |             "y": true,
000034 |             "x": false
000035 |           },
000036 |           null,
000037 |           "text"
000038 |         ]
000039 |       },
000040 |       "excluded_json_pointers": [],
000041 |       "canonical": "{\"a\":{\"a\":1,\"b\":2},\"m\":[{\"x\":false,\"y\":true},null,\"text\"],\"z\":\"last\"}",
000042 |       "sha256": "f45ed16183caf10d3a60b77fe6b2db8cae797c847bd81391b43887abd68fe7c2"
000043 |     },
000044 |     {
000045 |       "name": "unicode_and_escaping",
000046 |       "description": "Unicode is preserved as UTF-8; control characters are escaped by JSON serialization.",
000047 |       "input": {
000048 |         "fr": "école",
000049 |         "emoji": "🜂",
000050 |         "quote": "Kristal \"v5\"",
000051 |         "newline": "line one\nline two"
000052 |       },
000053 |       "excluded_json_pointers": [],
000054 |       "canonical": "{\"emoji\":\"🜂\",\"fr\":\"école\",\"newline\":\"line one\\nline two\",\"quote\":\"Kristal \\\"v5\\\"\"}",
000055 |       "sha256": "68defeb9da2ff00fb2f129615c50f62cc7a4f6dc7255e9b3958e0df41c785673"
000056 |     },
000057 |     {
000058 |       "name": "hash_ref_shape",
000059 |       "description": "Hash references use alg/value, not algo/hash.",
000060 |       "input": {
000061 |         "content_hash": {
000062 |           "alg": "sha256",
000063 |           "value": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
000064 |         },
000065 |         "schema_version": "5.0"
000066 |       },
000067 |       "excluded_json_pointers": [],
000068 |       "canonical": "{\"content_hash\":{\"alg\":\"sha256\",\"value\":\"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"},\"schema_version\":\"5.0\"}",
000069 |       "sha256": "ee7ebf24d933706ec2abdef203464c9bcc2bc0d149e72336668d65eb04ab536f"
000070 |     },
000071 |     {
000072 |       "name": "structured_epistemic_state_hash_target",
000073 |       "description": "Structured Epistemic State content hash target excludes state_id, content_hash, and signatures.",
000074 |       "input": {
000075 |         "schema_version": "5.0",
000076 |         "artifact_type": "structured_epistemic_state",
000077 |         "state_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
000078 |         "created_at": "2026-06-12T16:00:00Z",
000079 |         "content_hash": {
000080 |           "alg": "sha256",
000081 |           "value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
000082 |         },
000083 |         "scope": {
000084 |           "domain": "science",
000085 |           "subdomain": "example",
000086 |           "jurisdiction": null,
000087 |           "time_window": null,
000088 |           "tenant_id": null,
000089 |           "environment": "test",
000090 |           "language": "en"
000091 |         },
000092 |         "assertions": [
000093 |           {
000094 |             "assertion_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
000095 |             "assertion_status": "hypothesis",
000096 |             "certainty_level": "speculative",
000097 |             "validated_as": "hypothesis"
000098 |           }
000099 |         ],
000100 |         "signatures": [
000101 |           {
000102 |             "key_id": "example_ed25519_v1",
000103 |             "alg": "ed25519",
000104 |             "signature": "ZHVtbXk=",
000105 |             "created_at": "2026-06-12T16:00:01Z"
000106 |           }
000107 |         ]
000108 |       },
000109 |       "excluded_json_pointers": [
000110 |         "/state_id",
000111 |         "/content_hash",
000112 |         "/signatures"
000113 |       ],
000114 |       "canonical": "{\"artifact_type\":\"structured_epistemic_state\",\"assertions\":[{\"assertion_id\":\"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc\",\"assertion_status\":\"hypothesis\",\"certainty_level\":\"speculative\",\"validated_as\":\"hypothesis\"}],\"created_at\":\"2026-06-12T16:00:00Z\",\"schema_version\":\"5.0\",\"scope\":{\"domain\":\"science\",\"environment\":\"test\",\"jurisdiction\":null,\"language\":\"en\",\"subdomain\":\"example\",\"tenant_id\":null,\"time_window\":null}}",
000115 |       "sha256": "561287ce34bd41afdf847454fe2d74ba86e803ecc7494494bfdb6c8f93da1012"
000116 |     },
000117 |     {
000118 |       "name": "revocations_hash_target",
000119 |       "description": "Revocations content hash target excludes revocations_id, content_hash, and signatures.",
000120 |       "input": {
000121 |         "schema_version": "5.0",
000122 |         "artifact_type": "revocations",
000123 |         "revocations_id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
000124 |         "created_at": "2026-06-12T16:05:00Z",
000125 |         "content_hash": {
000126 |           "alg": "sha256",
000127 |           "value": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
000128 |         },
000129 |         "scope": {
000130 |           "domain": "operations",
000131 |           "subdomain": "trust-roots",
000132 |           "jurisdiction": null,
000133 |           "time_window": null,
000134 |           "tenant_id": "tenant_123",
000135 |           "environment": "test",
000136 |           "language": "en"
000137 |         },
000138 |         "entries": [
000139 |           {
000140 |             "entry_id": "rev-0001",
000141 |             "target_level": "key",
000142 |             "kind": "key_id",
000143 |             "target": {
000144 |               "key_id": "tenant_123_root_ed25519_v1"
000145 |             },
000146 |             "revocation_status": "revoked",
000147 |             "revoked_at": "2026-06-12T16:04:00Z",
000148 |             "effective_at": "2026-06-12T16:05:00Z",
000149 |             "reason_code": "planned_key_rotation",
000150 |             "reason": "Key rotation"
000151 |           }
000152 |         ],
000153 |         "signatures": [
000154 |           {
000155 |             "key_id": "tenant_123_root_ed25519_v2",
000156 |             "alg": "ed25519",
000157 |             "signature": "ZHVtbXk=",
000158 |             "created_at": "2026-06-12T16:05:01Z"
000159 |           }
000160 |         ]
000161 |       },
000162 |       "excluded_json_pointers": [
000163 |         "/revocations_id",
000164 |         "/content_hash",
000165 |         "/signatures"
000166 |       ],
000167 |       "canonical": "{\"artifact_type\":\"revocations\",\"created_at\":\"2026-06-12T16:05:00Z\",\"entries\":[{\"effective_at\":\"2026-06-12T16:05:00Z\",\"entry_id\":\"rev-0001\",\"kind\":\"key_id\",\"reason\":\"Key rotation\",\"reason_code\":\"planned_key_rotation\",\"revocation_status\":\"revoked\",\"revoked_at\":\"2026-06-12T16:04:00Z\",\"target\":{\"key_id\":\"tenant_123_root_ed25519_v1\"},\"target_level\":\"key\"}],\"schema_version\":\"5.0\",\"scope\":{\"domain\":\"operations\",\"environment\":\"test\",\"jurisdiction\":null,\"language\":\"en\",\"subdomain\":\"trust-roots\",\"tenant_id\":\"tenant_123\",\"time_window\":null}}",
000168 |       "sha256": "3c732cc156f035153e129992aed5c0e7f8097bc90d5b5e9fc574208f2c5ee32d"
000169 |     },
000170 |     {
000171 |       "name": "array_order_preserved",
000172 |       "description": "Arrays are not sorted; their declared order is part of the canonical bytes.",
000173 |       "input": {
000174 |         "items": [
000175 |           {
000176 |             "id": "b",
000177 |             "value": 2
000178 |           },
000179 |           {
000180 |             "id": "a",
000181 |             "value": 1
000182 |           }
000183 |         ]
000184 |       },
000185 |       "excluded_json_pointers": [],
000186 |       "canonical": "{\"items\":[{\"id\":\"b\",\"value\":2},{\"id\":\"a\",\"value\":1}]}",
000187 |       "sha256": "83cb4e99d3c052bd4f2e4c3a909f1435b8b8a9014be158b8ab2478a99d133891"
000188 |     }
000189 |   ]
000190 | }
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/09-test-vectors/rdfc/README.md"
id=fecddf7ace4a
kind=markdown
size=17560
lines=701
line_ref=1-701
chunks=3
chunk_refs=1-350,351-700,701-701
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=fecddf7ace4a:1-350
start=1
end=350
----
# RDFC Test Vectors and Fixtures

## Status

Draft.

## Purpose

This directory contains pointers and packaging conventions for the optional Kristal v5 profile:

```text
profile-rdf-integrity-rdfc@2
```

This profile covers RDF dataset canonicalization, `rdf_hash`, fixture packaging, and CI gating for RDF projections of Kristal artifacts.

The goal is to make RDF integrity **verifiable, reproducible, and interoperable** by:

* standardizing how fixtures are stored and referenced;
* standardizing how expected hashes are recorded;
* documenting which RDFC conformance tests are gated in CI;
* capturing resource limits alongside fixtures;
* keeping RDF structural integrity separate from Kristal validation, certainty, authority recognition, and reader policy decisions.

RDFC fixtures help answer:

```text
Do these RDF projection bytes canonicalize and hash as expected?
```

They do not answer:

```text
Is this assertion true?
Is this assertion validated?
Who recognizes this artifact?
At what certainty level?
Under which reader policy should it be visible?
```

Those questions belong to Kristal v5 validation decisions, authority recognition, certainty metadata, federation semantics, and reader policies.

---

## Scope

In scope:

* fixture layout and naming;
* required metadata for reproducing `rdf_hash`;
* expected output recording;
* CI gating configuration pointers;
* resource limit declaration;
* projection coverage boundaries;
* integrity verification of RDF canonicalization outputs.

Out of scope:

* shipping the full W3C RDFC test suite inside this repository;
* making RDFC mandatory for Kristal v5 core conformance;
* using RDFC as proof of truth, authority recognition, or assertion validation;
* defining RDF export semantics directly;
* defining reader policy behavior.

Implementations MAY vendor the W3C RDFC test suite, reference it externally, or maintain a minimal local subset for CI.

---

## Relationship to Kristal v5

RDFC is an integrity profile for RDF projections.

Kristal v5 distinguishes:

```text
artifact integrity
assertion status
certainty level
validation status
authority recognition
reader visibility
```

RDFC affects only the RDF projection integrity layer.

A passing RDFC fixture means:

```text
The RDF projection canonicalizes and hashes as expected under the declared profile, algorithm, coverage boundaries, and resource limits.
```

It does not imply:

```text
assertion_status = "validated"
certainty_level = "high"
validation_status = "validated"
recognition_status = "recognized"
artifact_status = "reference"
```

Those statuses require explicit Kristal v5 metadata or records.

---

## Directory layout

Recommended layout:

```text
09-test-vectors/rdfc/
  README.md

  fixtures/
    wdqs-full/
      case-0001/
        export.rdf.nq
        export.manifest.json
        expected.rdf_hash.sha256
      case-0002/
        ...

    wdqs-truthy/
      case-0001/
        export.rdf.nq
        export.manifest.json
        expected.rdf_hash.sha256

    jsonld-rdf/
      case-0001/
        export.rdf.nq
        export.manifest.json
        expected.rdf_hash.sha256

    implementation-defined/
      case-0001/
        export.rdf.nq
        export.manifest.json
        expected.rdf_hash.sha256

    stress/
      case-0001/
        export.rdf.nq
        export.manifest.json
        expected.rdf_hash.sha256

  ci/
    rdfc-gating.json
    rdfc-gating-notes.md
```

---

## Fixture case contents

Each `case-XXXX/` directory MUST include the following files.

### 1. `export.rdf.nq`

The RDF dataset export for the declared projection.

Requirements:

* MUST be deterministic for the declared export profile;
* MUST use N-Quads when named graphs are relevant;
* MUST follow the RDF export profile’s sorting and serialization rules before RDFC canonicalization;
* MUST correspond exactly to the coverage boundaries declared in `export.manifest.json`.

The file MAY contain RDF derived from:

```text
Exchange
Exchange Shard
Exchange Federation Manifest
Structured Epistemic State
Authority Registry
Validation Decision
Authority Recognition
Reader Policy
Runtime Pack metadata
```

Only the declared projection is covered.

---

### 2. `export.manifest.json`

The fixture manifest.

It MUST declare:

* fixture ID;
* Kristal spec version;
* RDF export profile ID and version;
* projection ID;
* projection mode;
* integrity profile ID and version;
* source artifact reference;
* coverage boundaries;
* canonicalization algorithm ID and version;
* resource limits used for canonicalization;
* skolemization policy, if applicable;
* blank node handling policy;
* expected hash file path;
* whether the fixture is included in default CI gating.

Recommended profile IDs:

```text
profile-rdf-wdqs-export@2
profile-jsonld-export@2
profile-rdf-integrity-rdfc@2
```

---

### 3. `expected.rdf_hash.sha256`

A single line containing the expected SHA-256 hash hex string.

Requirements:

* MUST contain exactly 64 lowercase hexadecimal characters;
* MUST NOT include prefixes such as `sha256:`;
* SHOULD end with a newline;
* MUST correspond to the RDF canonicalization output declared in `export.manifest.json`.

Example:

```text
0000000000000000000000000000000000000000000000000000000000000000
```

---

## Optional fixture files

A fixture case MAY include:

```text
notes.md
expected.canonical.nq
expected.profile-status.json
expected.validation-report.json
```

Meanings:

* `notes.md`: explains special modeling cases such as blank nodes, datatypes, ranks, named graphs, provenance graphs, validation decision graphs, or authority recognition graphs.
* `expected.canonical.nq`: stores canonicalized RDF output for debugging.
* `expected.profile-status.json`: stores expected profile-level status.
* `expected.validation-report.json`: stores expected structural validation or CI report output.

`expected.canonical.nq` can be useful for diagnosis, but it may increase repository size. It SHOULD be included only for small or strategically important fixtures unless the repository explicitly chooses to store canonical outputs.

---

## Naming conventions

Fixture groups SHOULD use stable names.

Recommended projection groups:

```text
wdqs-full/
wdqs-truthy/
jsonld-rdf/
implementation-defined/
stress/
```

Meanings:

* `wdqs-full/`: RDF WDQS export preserving full statements, qualifiers, references, ranks, and supporting graphs where applicable.
* `wdqs-truthy/`: RDF WDQS export using a truthy or best-rank projection.
* `jsonld-rdf/`: RDF interpreted from the JSON-LD export profile.
* `implementation-defined/`: implementation-specific RDF projection with explicit projection metadata.
* `stress/`: fixtures that exceed default CI limits or are intended for performance, memory, or pathological canonicalization testing.

Case IDs:

```text
case-0001
case-0002
case-0003
```

Case IDs MUST be stable.

If a fixture changes in a way that affects semantics, projection coverage, canonicalized output, or expected hash, create a new case ID rather than overwriting the old one.

---

## Coverage boundaries

Fixtures MUST explicitly record coverage boundaries because RDFC hashing is meaningful only relative to what the RDF projection includes.

A fixture MUST declare:

* which projection is covered;
* which artifact type is the source;
* which named graphs are included;
* which named graphs are excluded;
* whether provenance graphs are included;
* whether validation decision graphs are included;
* whether authority recognition graphs are included;
* whether reader policy graphs are included;
* whether operational metadata is excluded;
* whether timestamps are excluded;
* whether signatures are excluded;
* whether content-addressed ID fields are excluded from their own hash target.

A fixture without explicit coverage boundaries is non-conformant to this profile.

---

## Projection modes

Recommended projection modes:

```text
full
truthy
jsonld
authority
validation
reader_policy
federated
implementation_defined
```

Projection mode meanings:

* `full`: preserves all available RDF-representable statements and metadata in the selected profile.
* `truthy`: exports a reduced or best-rank view.
* `jsonld`: RDF derived from the JSON-LD profile.
* `authority`: emphasizes authority registry and recognition records.
* `validation`: emphasizes validation decisions and assertion status metadata.
* `reader_policy`: emphasizes reader policy filters and visibility metadata.
* `federated`: covers a composed federation projection.
* `implementation_defined`: projection is defined by the implementation and must be fully described in the manifest.

---

## Resource limits

Because RDF dataset canonicalization may have worst-case behavior, each fixture MUST record the resource limits used when generating the expected hash.

Required limits:
--- CHUNK END ---

--- CHUNK BEGIN ---
id=fecddf7ace4a:351-700
start=351
end=700
----

```text
timeout_ms
max_triples
max_blank_nodes
```

Recommended limits:

```text
max_memory_mb
max_named_graphs
max_bytes
```

If a fixture exceeds default limits on a reference implementation, it SHOULD be moved to:

```text
fixtures/stress/
```

Stress fixtures SHOULD NOT be part of default CI gating unless the implementation explicitly opts in.

---

## Skolemization policy

If the RDF projection uses skolem IRIs, the fixture manifest MUST declare:

```text
skolemization.enabled
skolemization.policy_id
skolemization.base_iri
skolemization.deterministic
```

If no skolemization is used, the fixture manifest MUST declare:

```json
{
  "skolemization": {
    "enabled": false
  }
}
```

Blank node handling MUST be explicit because it affects RDF canonicalization.

---

## CI gating configuration

The file:

```text
ci/rdfc-gating.json
```

SHOULD define:

* which RDFC test suite and version is used;
* which subset is gated;
* which local fixture cases are included in CI;
* which stress fixtures are excluded by default;
* resource limits used in CI;
* expected profile ID and version;
* expected algorithm ID and version.

Example:

```json
{
  "profile": "profile-rdf-integrity-rdfc@2",
  "spec_version": "5.0",
  "rdfc_suite": {
    "name": "W3C RDFC-1.0",
    "version": "1.0",
    "source": "external"
  },
  "gated_tests": [
    "t001",
    "t002",
    "t010"
  ],
  "fixtures": [
    {
      "path": "fixtures/wdqs-full/case-0001",
      "projection_mode": "full",
      "included_in_default_ci": true
    },
    {
      "path": "fixtures/wdqs-truthy/case-0001",
      "projection_mode": "truthy",
      "included_in_default_ci": true
    }
  ],
  "excluded_by_default": [
    {
      "path": "fixtures/stress/case-0001",
      "reason": "resource_limits_exceeded"
    }
  ],
  "limits": {
    "timeout_ms": 30000,
    "max_triples": 500000,
    "max_blank_nodes": 200000,
    "max_named_graphs": 10000,
    "max_memory_mb": 1024
  }
}
```

---

## Minimal `export.manifest.json`

Non-normative example:

```json
{
  "fixture_id": "rdfc:wdqs-full:case-0001",
  "spec_version": "5.0",
  "source_ref": {
    "artifact_type": "reference_exchange",
    "artifact_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "content_hash": {
      "alg": "sha256",
      "value": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  },
  "rdf_export_profile": {
    "id": "profile-rdf-wdqs-export@2",
    "projection_mode": "full",
    "version": "2"
  },
  "integrity_profile": {
    "id": "profile-rdf-integrity-rdfc@2",
    "version": "2"
  },
  "canonicalization": {
    "algorithm": "RDFC-1.0",
    "algorithm_version": "1.0",
    "hash_alg": "sha256"
  },
  "coverage": {
    "included_graphs": [
      "assertions",
      "provenance",
      "evidence",
      "validation_decisions",
      "authority_recognition"
    ],
    "excluded_graphs": [
      "operational_metadata",
      "runtime_cache",
      "signatures"
    ],
    "includes_provenance": true,
    "includes_validation_decisions": true,
    "includes_authority_recognition": true,
    "includes_reader_policy": false,
    "excludes_timestamps": true,
    "excludes_signatures": true,
    "excludes_output_id_from_own_hash": true
  },
  "skolemization": {
    "enabled": false
  },
  "limits": {
    "timeout_ms": 30000,
    "max_triples": 500000,
    "max_blank_nodes": 200000,
    "max_named_graphs": 10000,
    "max_memory_mb": 1024
  },
  "files": {
    "rdf_export": "export.rdf.nq",
    "expected_hash": "expected.rdf_hash.sha256",
    "expected_canonical": null
  },
  "ci": {
    "included_in_default_ci": true,
    "stress": false
  }
}
```

---

## Expected hash semantics

The expected hash file records the SHA-256 hash of the canonical RDF dataset bytes produced by the declared RDFC algorithm and fixture manifest.

The expected hash MUST be computed over:

```text
canonical RDF output bytes
```

It MUST NOT be computed over:

```text
export.manifest.json
expected.rdf_hash.sha256
signatures
operational logs
runtime cache files
timestamps excluded by coverage policy
```

If another profile explicitly includes RDFC artifacts in a larger package hash, that package hash is separate from `rdf_hash`.

---

## Verification procedure

Implementers SHOULD use this directory as follows:

1. Generate an RDF export for a fixture case using the declared RDF export profile.
2. Verify that the export matches the declared projection and coverage boundaries.
3. Apply `profile-rdf-integrity-rdfc@2`.
4. Produce canonical RDF bytes.
5. Compute SHA-256 over the canonical RDF bytes.
6. Compare the result to `expected.rdf_hash.sha256`.
7. Run the CI gate subset defined in `ci/rdfc-gating.json`.
8. Report profile status.

Recommended profile status values:

```text
not_declared
declared
verified
verification_failed
execution_not_run
execution_passed
execution_failed
unsupported
resource_limit_exceeded
```

---

## Failure semantics

If a fixture cannot be verified, implementations SHOULD report a fixture-level or profile-level failure.

Examples:

```json
{
  "profile": "profile-rdf-integrity-rdfc@2",
  "fixture_id": "rdfc:wdqs-full:case-0001",
  "profile_status": "verification_failed",
  "reason_codes": [
    "hash_invalid"
  ]
}
```

Recommended reason codes:

```text
manifest_missing
rdf_export_missing
expected_hash_missing
hash_invalid
coverage_missing
coverage_mismatch
projection_mismatch
unsupported_projection
unsupported_rdfc_algorithm
resource_limit_exceeded
canonicalization_error
nondeterministic_output
```

A failed RDFC fixture means the RDF integrity profile failed for that fixture.

It does not mean that the underlying Kristal assertion is false, rejected, unrecognized, or low-certainty.

---

## Reader policy interaction

Reader policies MAY use RDFC fixture or package verification status as a structural quality signal.

Examples:

* a strict reference-only reader policy MAY require RDF integrity verification for RDF-backed views;
* a validated-only reader policy MAY ignore RDF fixture status if it does not rely on RDF projection;
* a research reader policy MAY show RDF-backed material with visible verification warnings;
* a creative reader policy MAY ignore RDFC fixtures entirely.

Reader policies MUST NOT treat RDFC verification as authority recognition.

---

## Authority recognition interaction

An authority channel MAY require RDFC verification as one input to its validation policy.

Example:

```text
authority:example-data-body
requires:
  - schema validation
  - provenance sufficiency
  - RDF projection coverage declaration
  - RDFC hash verification
  - review by declared validator
```

In that case, RDFC verification is evidence used by the authority channel.

The authority recognition record remains the place to express:

```text
recognition_status
recognized_as
scope
validation_policy_ref
reason_codes
```

---

## Notes on full vs truthy projections

For Wikidata-aligned exports:

* `full` fixtures SHOULD preserve full statements, qualifiers, references, ranks, and supporting graphs where applicable.
* `truthy` fixtures MAY expose a reduced best-rank projection.
* The fixture manifest MUST state which mode is used.
* A `truthy` fixture MUST NOT be treated as equivalent to a full reference artifact.

The source Kristal may preserve more structure than a given RDF projection exposes.

---

## Open questions

To finalize:

* Whether to store `expected.canonical.nq` for all default fixtures or only selected debug fixtures.
* Whether to vendor a minimal RDFC subset locally or require implementations to pull the suite externally.
* Whether to include additional projections beyond `full`, `truthy`, `jsonld`, and `implementation_defined`.
* Whether stress fixtures should have a separate CI profile.
* Whether profile status reports should be stored beside each fixture by default.
--- CHUNK END ---

--- CHUNK BEGIN ---
id=fecddf7ace4a:701-701
start=701
end=701
----
* Whether authority and validation graphs should be included in default `wdqs-full` fixtures or split into dedicated fixture groups.
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/authority-registry.example.json"
id=d8e4595aa560
kind=source
size=12954
lines=585
line_ref=1-585
chunks=2
chunk_refs=1-350,351-585
summary="Source file."

--- CHUNK BEGIN ---
id=d8e4595aa560:1-350
start=1
end=350
----
{
"schema_version": "5.0",
"artifact_type": "authority_registry",
"registry_id": "sha256:0d8c7b6a5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b",
"created_at": "2026-06-12T16:40:00Z",
"canonicalization_profile": "kristal.v5:jcs-rfc8785",
"canonicalization_version": "1",
"content_hash": {
"alg": "sha256",
"value": "b10a8db164e0754105b7a99be72e3fe5a1b3c2d4e5f60718293a4b5c6d7e8f90"
},
"registry_scope": {
"domain": "general",
"subdomain": "example-authority-registry",
"environment": "example",
"language": "en"
},
"authority_channels": [
{
"authority_channel_id": "authority:curator",
"name": "Example Curator Authority",
"authority_type": "individual",
"description": "Example local curator channel used to publish and sign this registry.",
"scope": {
"domain": "general",
"subdomain": "registry-publication",
"environment": "example",
"language": "en"
},
"recognized_by": [],
"recognizes": [
"authority:unesco",
"authority:local-notes"
],
"trust_roots": [
"root:curator-ed25519-2026-01"
],
"validation_policies": [
"kristal.v5:validation-policy:registry-publication"
],
"recognition_policies": [
"kristal.v5:recognition-policy:scoped-authority-channel"
],
"revocation_policy_ref": "kristal.v5:revocation-policy:example-authority-registry",
"metadata": {
"example": true
}
},
{
"authority_channel_id": "authority:unesco",
"name": "UNESCO Example Heritage Channel",
"authority_type": "intergovernmental_organization",
"description": "Example heritage authority channel. Recognition is scoped to heritage examples and does not imply universal authority.",
"scope": {
"domain": "heritage",
"subdomain": "unesco",
"time_window": "2026-01",
"environment": "example",
"language": "en"
},
"recognized_by": [
"authority:curator"
],
"recognizes": [],
"trust_roots": [
"root:unesco-example-ed25519-2026-01"
],
"validation_policies": [
"kristal.v5:validation-policy:heritage-reference"
],
"recognition_policies": [
"kristal.v5:recognition-policy:heritage-reference"
],
"revocation_policy_ref": "kristal.v5:revocation-policy:example-authority-registry",
"metadata": {
"example": true
}
},
{
"authority_channel_id": "authority:local-notes",
"name": "Local Notes Example Channel",
"authority_type": "individual",
"description": "Example local-notes authority channel. Material from this channel is scoped as local notes unless another authority recognizes it under a different policy.",
"scope": {
"domain": "local_notes",
"subdomain": "personal-notes",
"time_window": "2026-01",
"environment": "example",
"language": "en"
},
"recognized_by": [
"authority:curator"
],
"recognizes": [],
"trust_roots": [
"root:local-notes-ed25519-2026-01"
],
"validation_policies": [
"kristal.v5:validation-policy:local-notes-declaration"
],
"recognition_policies": [
"kristal.v5:recognition-policy:local-notes"
],
"revocation_policy_ref": "kristal.v5:revocation-policy:example-authority-registry",
"metadata": {
"example": true
}
}
],
"trust_roots": {
"active_roots": [
{
"root_id": "root:curator-ed25519-2026-01",
"category": "personal",
"label": "Example curator signing root",
"authority_channel_ids": [
"authority:curator"
],
"key_id": "curator-ed25519-2026-01",
"public_key_jwk": {
"kty": "OKP",
"crv": "Ed25519",
"kid": "curator-ed25519-2026-01",
"x": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
},
"not_before": "2026-01-01T00:00:00Z",
"not_after": "2027-01-01T00:00:00Z"
},
{
"root_id": "root:unesco-example-ed25519-2026-01",
"category": "intergovernmental_organization",
"label": "Example UNESCO heritage signing root",
"authority_channel_ids": [
"authority:unesco"
],
"key_id": "unesco-example-ed25519-2026-01",
"public_key_jwk": {
"kty": "OKP",
"crv": "Ed25519",
"kid": "unesco-example-ed25519-2026-01",
"x": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
},
"not_before": "2026-01-01T00:00:00Z",
"not_after": "2027-01-01T00:00:00Z"
},
{
"root_id": "root:local-notes-ed25519-2026-01",
"category": "personal",
"label": "Example local notes signing root",
"authority_channel_ids": [
"authority:local-notes"
],
"key_id": "local-notes-ed25519-2026-01",
"public_key_jwk": {
"kty": "OKP",
"crv": "Ed25519",
"kid": "local-notes-ed25519-2026-01",
"x": "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC"
},
"not_before": "2026-01-01T00:00:00Z",
"not_after": "2027-01-01T00:00:00Z"
}
],
"deprecated_roots": [],
"blocked_roots": []
},
"validation_policies": [
{
"policy_id": "kristal.v5:validation-policy:registry-publication",
"policy_version": "1",
"scope": {
"domain": "general",
"subdomain": "registry-publication",
"environment": "example",
"language": "en"
},
"allowed_validation_statuses": [
"validated",
"conditionally_validated"
],
"allowed_validated_as": [
"technical_specification",
"publisher_declaration"
],
"allowed_certainty_levels": [
"high",
"established",
"not_applicable"
],
"required_evidence": [
"registry-signature",
"content-hash"
],
"required_profiles": [
"kristal.v5:jcs-rfc8785"
],
"min_signatures": 1
},
{
"policy_id": "kristal.v5:validation-policy:heritage-reference",
"policy_version": "1",
"scope": {
"domain": "heritage",
"subdomain": "unesco",
"environment": "example",
"language": "en"
},
"allowed_validation_statuses": [
"validated",
"conditionally_validated",
"disputed"
],
"allowed_validated_as": [
"institutional_reference",
"reviewed_claim",
"disputed_position"
],
"allowed_certainty_levels": [
"medium",
"high",
"established"
],
"required_evidence": [
"institutional-source",
"provenance-reference"
],
"required_profiles": [
"kristal.v5:authority-recognition"
],
"min_signatures": 1
},
{
"policy_id": "kristal.v5:validation-policy:local-notes-declaration",
"policy_version": "1",
"scope": {
"domain": "local_notes",
"subdomain": "personal-notes",
"environment": "example",
"language": "en"
},
"allowed_validation_statuses": [
"not_evaluated",
"in_review",
"validated",
"disputed"
],
"allowed_validated_as": [
"claim",
"sourced_claim",
"publisher_declaration",
"disputed_position"
],
"allowed_certainty_levels": [
"unknown",
"speculative",
"low",
"medium"
],
"required_evidence": [
"source-declaration"
],
"required_profiles": [],
"min_signatures": 1
}
],
"recognition_policies": [
{
"policy_id": "kristal.v5:recognition-policy:scoped-authority-channel",
"policy_version": "1",
"scope": {
"domain": "general",
"subdomain": "authority-channel-recognition",
"environment": "example",
"language": "en"
},
"target_levels": [
"authority_channel"
],
"allowed_recognition_statuses": [
"recognized",
"conditionally_recognized",
"under_review",
"rejected",
"revoked"
],
"allowed_validated_as": [
"institutional_reference",
"publisher_declaration",
"technical_specification"
],
"allowed_certainty_levels": [
"medium",
"high",
"established",
"not_applicable"
],
"required_authority_channels": [
"authority:curator"
],
"allow_delegated_authority": true
},
{
"policy_id": "kristal.v5:recognition-policy:heritage-reference",
"policy_version": "1",
"scope": {
"domain": "heritage",
"subdomain": "unesco",
"environment": "example",
"language": "en"
},
"target_levels": [
"artifact",
"shard",
"assertion",
"dataset"
],
"allowed_recognition_statuses": [
"recognized",
"conditionally_recognized",
"under_review",
"disputed"
],
"allowed_validated_as": [
"institutional_reference",
"reviewed_claim",
"disputed_position"
],
"allowed_certainty_levels": [
"medium",
"high",
"established"
],
"required_authority_channels": [
"authority:unesco"
],
"allow_delegated_authority": true
},
{
"policy_id": "kristal.v5:recognition-policy:local-notes",
"policy_version": "1",
"scope": {
"domain": "local_notes",
"subdomain": "personal-notes",
"environment": "example",
"language": "en"
},
"target_levels": [
"artifact",
"assertion",
"dataset"
--- CHUNK END ---

--- CHUNK BEGIN ---
id=d8e4595aa560:351-585
start=351
end=585
----
],
"allowed_recognition_statuses": [
"recognized",
"conditionally_recognized",
"under_review",
"disputed"
],
"allowed_validated_as": [
"claim",
"sourced_claim",
"publisher_declaration",
"disputed_position"
],
"allowed_certainty_levels": [
"unknown",
"speculative",
"low",
"medium"
],
"required_authority_channels": [
"authority:local-notes"
],
"allow_delegated_authority": false
}
],
"revocation_list": {
"artifact_path": "revocations.json",
"content_hash": {
"alg": "sha256",
"value": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"signatures": [
{
"key_id": "curator-ed25519-2026-01",
"alg": "ed25519",
"payload_hash": {
"alg": "sha256",
"value": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"signature": "ZHVtbXktcmV2b2NhdGlvbi1saXN0LXNpZ25hdHVyZQ",
"created_at": "2026-06-12T16:40:00Z"
}
]
},
"rules": [
{
"rule_id": "rule:heritage-reference-scope",
"scope": {
"domain": "heritage",
"subdomain": "unesco",
"environment": "example",
"language": "en"
},
"target_levels": [
"artifact",
"shard",
"assertion",
"dataset"
],
"allowed_authority_channel_ids": [
"authority:unesco"
],
"allowed_authority_types": [
"intergovernmental_organization"
],
"allowed_root_categories": [
"intergovernmental_organization",
"recognized"
],
"allowed_root_ids": [
"root:unesco-example-ed25519-2026-01"
],
"required_validation_policies": [
"kristal.v5:validation-policy:heritage-reference"
],
"required_recognition_policies": [
"kristal.v5:recognition-policy:heritage-reference"
],
"allowed_validation_statuses": [
"validated",
"conditionally_validated",
"disputed"
],
"allowed_recognition_statuses": [
"recognized",
"conditionally_recognized",
"under_review",
"disputed"
],
"allowed_validated_as": [
"institutional_reference",
"reviewed_claim",
"disputed_position"
],
"allowed_certainty_levels": [
"medium",
"high",
"established"
],
"min_signatures": 1,
"revocation_policy": "require_if_present",
"delegation_policy": "explicit_only",
"disagreement_policy": "preserve_disagreement"
},
{
"rule_id": "rule:local-notes-scope",
"scope": {
"domain": "local_notes",
"subdomain": "personal-notes",
"environment": "example",
"language": "en"
},
"target_levels": [
"artifact",
"assertion",
"dataset"
],
"allowed_authority_channel_ids": [
"authority:local-notes"
],
"allowed_authority_types": [
"individual"
],
"allowed_root_categories": [
"personal"
],
"allowed_root_ids": [
"root:local-notes-ed25519-2026-01"
],
"required_validation_policies": [
"kristal.v5:validation-policy:local-notes-declaration"
],
"required_recognition_policies": [
"kristal.v5:recognition-policy:local-notes"
],
"allowed_validation_statuses": [
"not_evaluated",
"in_review",
"validated",
"disputed"
],
"allowed_recognition_statuses": [
"recognized",
"conditionally_recognized",
"under_review",
"disputed"
],
"allowed_validated_as": [
"claim",
"sourced_claim",
"publisher_declaration",
"disputed_position"
],
"allowed_certainty_levels": [
"unknown",
"speculative",
"low",
"medium"
],
"min_signatures": 1,
"revocation_policy": "require_if_present",
"delegation_policy": "none",
"disagreement_policy": "mark_disputed"
},
{
"rule_id": "rule:registry-publication",
"scope": {
"domain": "general",
"subdomain": "registry-publication",
"environment": "example",
"language": "en"
},
"target_levels": [
"authority_channel",
"artifact"
],
"allowed_authority_channel_ids": [
"authority:curator"
],
"allowed_authority_types": [
"individual"
],
"allowed_root_categories": [
"personal"
],
"allowed_root_ids": [
"root:curator-ed25519-2026-01"
],
"required_validation_policies": [
"kristal.v5:validation-policy:registry-publication"
],
"required_recognition_policies": [
"kristal.v5:recognition-policy:scoped-authority-channel"
],
"allowed_validation_statuses": [
"validated",
"conditionally_validated"
],
"allowed_recognition_statuses": [
"recognized",
"conditionally_recognized",
"under_review"
],
"allowed_validated_as": [
"technical_specification",
"publisher_declaration"
],
"allowed_certainty_levels": [
"high",
"established",
"not_applicable"
],
"min_signatures": 1,
"revocation_policy": "require_strict",
"delegation_policy": "explicit_only",
"disagreement_policy": "preserve_disagreement"
}
],
"signatures": [
{
"sig_id": "sig:authority-registry-example-0001",
"key_id": "curator-ed25519-2026-01",
"alg": "ed25519",
"payload_hash": {
"alg": "sha256",
"value": "b10a8db164e0754105b7a99be72e3fe5a1b3c2d4e5f60718293a4b5c6d7e8f90"
},
"signature": "ZHVtbXktYXV0aG9yaXR5LXJlZ2lzdHJ5LXNpZ25hdHVyZQ",
"created_at": "2026-06-12T16:40:00Z"
}
],
"extensions": {
"example_purpose": "Demonstrates a Kristal v5 authority registry with scoped authority channels, trust roots, validation policies, recognition policies, revocation linkage, and rule-based acceptance."
}
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/claim-ir.example.json"
id=350b7b4382aa
kind=source
size=8326
lines=324
line_ref=1-324
chunks=0
chunk_refs=
summary="Source file."
----
000001 | {
000002 | "schema_version": "5.0",
000003 | "artifact_type": "claim_ir",
000004 | "profile_role": "extractor_proposal_profile",
000005 | "canonicalization_profile": "kristal.v5:jcs-rfc8785",
000006 | "document": {
000007 | "doc_id": "doc:example-great-library-alexandria",
000008 | "title": "Example source note on the Great Library of Alexandria",
000009 | "lang": "en",
000010 | "source_id": "source:example-great-library-note",
000011 | "source_url": "https://example.org/sources/great-library-alexandria",
000012 | "retrieved_at": "2026-06-12T16:22:19Z",
000013 | "published_at": "2026-06-01T00:00:00Z",
000014 | "license": "example-only",
000015 | "publisher": "Example Historical Notes",
000016 | "content_hash": {
000017 | "alg": "sha256",
000018 | "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
000019 | }
000020 | },
000021 | "extraction": {
000022 | "run_id": "extract:20260612T162219Z:claim-ir-example",
000023 | "created_at": "2026-06-12T16:22:19Z",
000024 | "producer": {
000025 | "kind": "hybrid",
000026 | "name": "Kristal Example Extractor",
000027 | "version": "5.0.0"
000028 | },
000029 | "model": {
000030 | "provider": "example",
000031 | "name": "example-extractor-model",
000032 | "version": "2026-06-12"
000033 | },
000034 | "prompt_ref": {
000035 | "prompt_id": "prompt:claim-ir-extraction-example",
000036 | "version": "1",
000037 | "content_hash": {
000038 | "alg": "sha256",
000039 | "value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
000040 | }
000041 | },
000042 | "method": "hybrid_llm_rules_with_human_review_hint",
000043 | "confidence": 0.86
000044 | },
000045 | "scope": {
000046 | "domain": "heritage",
000047 | "subdomain": "historical-knowledge",
000048 | "jurisdiction": null,
000049 | "time_window": null,
000050 | "tenant_id": "tenant_demo",
000051 | "environment": "example",
000052 | "language": "en"
000053 | },
000054 | "subject": {
000055 | "surface": "Great Library of Alexandria",
000056 | "lang": "en",
000057 | "candidates": [
000058 | {
000059 | "id": "Q435",
000060 | "score": 0.94,
000061 | "label": "Library of Alexandria",
000062 | "source": "wikidata"
000063 | },
000064 | {
000065 | "id": "Q88",
000066 | "score": 0.32,
000067 | "label": "Alexandria",
000068 | "source": "wikidata"
000069 | }
000070 | ],
000071 | "source_ref": {
000072 | "ref": "source:example-great-library-note",
000073 | "kind": "source",
000074 | "content_hash": {
000075 | "alg": "sha256",
000076 | "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
000077 | }
000078 | }
000079 | },
000080 | "claims": [
000081 | {
000082 | "claim_id": "claim:great-library-location-0001",
000083 | "predicate": {
000084 | "surface": "located in",
000085 | "lang": "en",
000086 | "candidates": [
000087 | {
000088 | "id": "P131",
000089 | "score": 0.81,
000090 | "label": "located in the administrative territorial entity",
000091 | "source": "wikidata"
000092 | },
000093 | {
000094 | "id": "P276",
000095 | "score": 0.64,
000096 | "label": "location",
000097 | "source": "wikidata"
000098 | }
000099 | ]
000100 | },
000101 | "object": {
000102 | "kind": "item",
000103 | "value": {
000104 | "surface": "Alexandria",
000105 | "lang": "en",
000106 | "candidates": [
000107 | {
000108 | "id": "Q88",
000109 | "score": 0.96,
000110 | "label": "Alexandria",
000111 | "source": "wikidata"
000112 | }
000113 | ]
000114 | }
000115 | },
000116 | "proposed_assertion_status": "sourced",
000117 | "proposed_certainty_level": "high",
000118 | "proposed_validated_as": "sourced_claim",
000119 | "scope": {
000120 | "domain": "heritage",
000121 | "subdomain": "historical-knowledge",
000122 | "jurisdiction": null,
000123 | "time_window": null,
000124 | "tenant_id": "tenant_demo",
000125 | "environment": "example",
000126 | "language": "en"
000127 | },
000128 | "evidence": [
000129 | {
000130 | "source": {
000131 | "source_id": "source:example-great-library-note",
000132 | "source_url": "https://example.org/sources/great-library-alexandria",
000133 | "title": "Example source note on the Great Library of Alexandria",
000134 | "retrieved_at": "2026-06-12T16:22:19Z",
000135 | "content_hash": {
000136 | "alg": "sha256",
000137 | "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
000138 | }
000139 | },
000140 | "evidence_type": "quote",
000141 | "quote": "The Great Library of Alexandria was located in Alexandria, Egypt.",
000142 | "selector": {
000143 | "kind": "text_quote",
000144 | "value": "located in Alexandria, Egypt"
000145 | },
000146 | "strength": "strong"
000147 | }
000148 | ],
000149 | "authority_channel_refs": [
000150 | {
000151 | "ref": "authority:example-heritage-review",
000152 | "kind": "authority_channel"
000153 | }
000154 | ],
000155 | "confidence": 0.91,
000156 | "uncertainty": {
000157 | "confidence": 0.91,
000158 | "certainty_level": "high",
000159 | "method": "extractor-confidence-plus-source-match",
000160 | "notes": "The claim is extracted as sourced, not validated or authority-recognized."
000161 | },
000162 | "notes": "This Claim-IR claim proposes a structured assertion for later resolution and possible projection into Structured Epistemic State."
000163 | },
000164 | {
000165 | "claim_id": "claim:great-library-destruction-0002",
000166 | "predicate": {
000167 | "surface": "was destroyed",
000168 | "lang": "en",
000169 | "candidates": [
000170 | {
000171 | "id": "P793",
000172 | "score": 0.72,
000173 | "label": "significant event",
000174 | "source": "wikidata"
000175 | }
000176 | ]
000177 | },
000178 | "object": {
000179 | "kind": "string",
000180 | "value": "destroyed or declined through multiple historical events"
000181 | },
000182 | "proposed_assertion_status": "hypothesis",
000183 | "proposed_certainty_level": "medium",
000184 | "proposed_validated_as": "hypothesis",
000185 | "scope": {
000186 | "domain": "heritage",
000187 | "subdomain": "historical-knowledge",
000188 | "jurisdiction": null,
000189 | "time_window": null,
000190 | "tenant_id": "tenant_demo",
000191 | "environment": "example",
000192 | "language": "en"
000193 | },
000194 | "qualifiers": [
000195 | {
000196 | "predicate": {
000197 | "surface": "epistemic mode",
000198 | "lang": "en"
000199 | },
000200 | "object": {
000201 | "kind": "string",
000202 | "value": "historical uncertainty"
000203 | }
000204 | }
000205 | ],
000206 | "evidence": [
000207 | {
000208 | "source": {
000209 | "source_id": "source:example-great-library-note",
000210 | "source_url": "https://example.org/sources/great-library-alexandria",
000211 | "title": "Example source note on the Great Library of Alexandria",
000212 | "retrieved_at": "2026-06-12T16:22:19Z",
000213 | "content_hash": {
000214 | "alg": "sha256",
000215 | "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
000216 | }
000217 | },
000218 | "evidence_type": "quote",
000219 | "quote": "The fate of the Great Library is disputed, and some accounts describe a gradual decline rather than one single destruction event.",
000220 | "selector": {
000221 | "kind": "text_quote",
000222 | "value": "disputed ... gradual decline"
000223 | },
000224 | "strength": "medium"
000225 | }
000226 | ],
000227 | "authority_channel_refs": [
000228 | {
000229 | "ref": "authority:example-heritage-review",
000230 | "kind": "authority_channel"
000231 | }
000232 | ],
000233 | "confidence": 0.68,
000234 | "uncertainty": {
000235 | "confidence": 0.68,
000236 | "certainty_level": "medium",
000237 | "confidence_interval": {
000238 | "low": 0.52,
000239 | "high": 0.78
000240 | },
000241 | "method": "extractor-confidence-with-ambiguity-flag",
000242 | "notes": "The extraction preserves historical ambiguity and proposes hypothesis status."
000243 | },
000244 | "alternatives": [
000245 | {
000246 | "claim_id": "claim:great-library-destruction-alt-0002a",
000247 | "predicate": {
000248 | "surface": "was destroyed by a single event",
000249 | "lang": "en"
000250 | },
000251 | "object": {
000252 | "kind": "boolean",
000253 | "value": false
000254 | },
000255 | "proposed_assertion_status": "claimed",
000256 | "proposed_certainty_level": "low",
000257 | "proposed_validated_as": "claim",
000258 | "scope": {
000259 | "domain": "heritage",
000260 | "subdomain": "historical-knowledge",
000261 | "jurisdiction": null,
000262 | "time_window": null,
000263 | "tenant_id": "tenant_demo",
000264 | "environment": "example",
000265 | "language": "en"
000266 | },
000267 | "confidence": 0.41,
000268 | "uncertainty": {
000269 | "confidence": 0.41,
000270 | "certainty_level": "low",
000271 | "method": "alternative-extraction",
000272 | "notes": "Alternative retained for downstream review; not selected as a resolved fact."
000273 | },
000274 | "notes": "This alternative is included to preserve ambiguity for SenTient and review workflows."
000275 | }
000276 | ],
000277 | "notes": "This claim intentionally remains a hypothesis. It should not be rendered as a settled factual assertion."
000278 | }
000279 | ],
000280 | "provenance_refs": [
000281 | {
000282 | "ref": "source:example-great-library-note",
000283 | "kind": "source",
000284 | "content_hash": {
000285 | "alg": "sha256",
000286 | "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
000287 | }
000288 | },
000289 | {
000290 | "ref": "extract:20260612T162219Z:claim-ir-example",
000291 | "kind": "extraction_run",
000292 | "content_hash": {
000293 | "alg": "sha256",
000294 | "value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
000295 | }
000296 | }
000297 | ],
000298 | "target_state": {
000299 | "target_schema": "https://kristal.org/schemas/v5/structured-epistemic-state.schema.json",
000300 | "projection_mode": "requires_resolution",
000301 | "expected_artifact_type": "structured_epistemic_state",
000302 | "conversion_policy_ref": {
000303 | "ref": "policy:kristal.v5:claim-ir-to-structured-epistemic-state@1",
000304 | "kind": "policy"
000305 | },
000306 | "notes": "This Claim-IR batch may be projected into a Structured Epistemic State after resolution and review. Claim-IR itself does not imply validation or authority recognition."
000307 | },
000308 | "warnings": [
000309 | {
000310 | "code": "AMBIGUOUS_PREDICATE",
000311 | "message": "The location predicate has multiple plausible Wikidata property candidates.",
000312 | "path": "/claims/0/predicate"
000313 | },
000314 | {
000315 | "code": "LOW_CONFIDENCE_EXTRACTION",
000316 | "message": "The destruction-history claim is preserved as a hypothesis because the source material is historically ambiguous.",
000317 | "path": "/claims/1"
000318 | }
000319 | ],
000320 | "errors": [],
000321 | "extensions": {
000322 | "example_purpose": "Demonstrates Claim-IR v5 as an extractor proposal profile that preserves uncertainty, evidence, candidate resolution hints, and proposed epistemic status without implying validation."
000323 | }
000324 | }
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/divergent-fork.example.json"
id=31098e1b03fb
kind=source
size=27874
lines=756
line_ref=1-756
chunks=3
chunk_refs=1-350,351-700,701-756
summary="Source file."

--- CHUNK BEGIN ---
id=31098e1b03fb:1-350
start=1
end=350
----
{
  "schema_version": "5.0",
  "artifact_type": "structured_epistemic_state",
  "state_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
  "artifact_status": "working",
  "created_at": "2026-06-12T16:30:00Z",
  "created_by": {
    "agent_id": "agent:flat-earth-collective-example",
    "name": "Flat Earth Collective Example",
    "agent_type": "community",
    "authority_channel": {
      "authority_channel_id": "authority:flat-earth-collective-example",
      "name": "Flat Earth Collective Example"
    }
  },
  "canonicalization_profile": "kristal.v5:jcs-rfc8785",
  "canonicalization_version": "1",
  "content_hash": {
    "alg": "sha256",
    "value": "2222222222222222222222222222222222222222222222222222222222222222"
  },
  "hash_target_policy": {
    "exclude_fields": ["state_id", "content_hash", "signatures"],
    "notes": "The content_hash is computed over the deterministic canonical serialization of the unsigned Structured Epistemic State, excluding state_id, content_hash, and signatures."
  },
  "scope": {
    "domain": "research",
    "subdomain": "divergent-world-model",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": "example",
    "language": "en"
  },
  "source_refs": [
    {
      "source_id": "source:flat-earth-collective-example-brief",
      "source_type": "human_submission",
      "title": "Example divergent position brief",
      "publisher": "Flat Earth Collective Example",
      "retrieved_at": "2026-06-12T16:20:00Z",
      "license": "example-only",
      "content_hash": {
        "alg": "sha256",
        "value": "3333333333333333333333333333333333333333333333333333333333333333"
      },
      "authority_channel": {
        "authority_channel_id": "authority:flat-earth-collective-example",
        "name": "Flat Earth Collective Example"
      }
    },
    {
      "source_id": "source:global-science-reference-earth-shape",
      "source_type": "institutional_record",
      "title": "Global science reference position on Earth shape",
      "publisher": "Global Science Reference Example",
      "retrieved_at": "2026-06-12T16:21:00Z",
      "license": "example-only",
      "content_hash": {
        "alg": "sha256",
        "value": "4444444444444444444444444444444444444444444444444444444444444444"
      },
      "authority_channel": {
        "authority_channel_id": "authority:global-science-reference-example",
        "name": "Global Science Reference Example"
      }
    }
  ],
  "derived_from": [
    {
      "artifact_id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
      "artifact_type": "reference_exchange",
      "content_hash": {
        "alg": "sha256",
        "value": "6666666666666666666666666666666666666666666666666666666666666666"
      },
      "created_at": "2026-06-01T00:00:00Z"
    }
  ],
  "merged_from": [],
  "supersedes": [],
  "assertions": [
    {
      "assertion_id": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
      "source_assertion_id": "flat-earth-claim-0001",
      "statement": {
        "subject": {
          "label": "Earth",
          "description": "The planet Earth",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:global-science-reference-example",
            "name": "Global Science Reference Example"
          }
        },
        "predicate": {
          "label": "has asserted shape",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:flat-earth-collective-example",
            "name": "Flat Earth Collective Example"
          }
        },
        "object": {
          "kind": "string",
          "value": "flat"
        },
        "qualifiers": [
          {
            "predicate": {
              "label": "epistemic mode",
              "language": "en"
            },
            "object": {
              "kind": "string",
              "value": "divergent physical-world claim"
            },
            "scope": {
              "domain": "research",
              "subdomain": "divergent-world-model",
              "jurisdiction": null,
              "time_window": null,
              "tenant_id": null,
              "environment": "example",
              "language": "en"
            },
            "notes": "This qualifier marks the assertion as a divergent physical-world claim, not as a reference scientific claim."
          }
        ],
        "rank": "normal",
        "statement_hash": {
          "alg": "sha256",
          "value": "8888888888888888888888888888888888888888888888888888888888888888"
        }
      },
      "natural_language_statement": {
        "text": "Earth is flat.",
        "lang": "en"
      },
      "assertion_status": "disputed",
      "certainty_level": "low",
      "validated_as": "disputed_position",
      "scope": {
        "domain": "research",
        "subdomain": "divergent-world-model",
        "jurisdiction": null,
        "time_window": null,
        "tenant_id": null,
        "environment": "example",
        "language": "en"
      },
      "evidence_refs": [
        {
          "evidence_id": "evidence:flat-earth-brief-0001",
          "source_ref": {
            "source_id": "source:flat-earth-collective-example-brief",
            "source_type": "human_submission",
            "title": "Example divergent position brief",
            "publisher": "Flat Earth Collective Example",
            "content_hash": {
              "alg": "sha256",
              "value": "3333333333333333333333333333333333333333333333333333333333333333"
            },
            "authority_channel": {
              "authority_channel_id": "authority:flat-earth-collective-example",
              "name": "Flat Earth Collective Example"
            }
          },
          "quote": "The collective asserts that Earth should be modeled as flat within this divergent research fork.",
          "section": "Position statement",
          "evidence_status": "provided",
          "content_hash": {
            "alg": "sha256",
            "value": "9999999999999999999999999999999999999999999999999999999999999999"
          }
        }
      ],
      "provenance_refs": [
        {
          "artifact_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "artifact_type": "human_submission",
          "content_hash": {
            "alg": "sha256",
            "value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
          },
          "created_at": "2026-06-12T16:10:00Z"
        }
      ],
      "authority_recognition_refs": [
        {
          "recognition_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
          "recognition_status": "recognized",
          "recognized_as": "disputed_position",
          "authority_channel": {
            "authority_channel_id": "authority:flat-earth-collective-example",
            "name": "Flat Earth Collective Example"
          },
          "scope": {
            "domain": "research",
            "subdomain": "divergent-world-model",
            "jurisdiction": null,
            "time_window": null,
            "tenant_id": null,
            "environment": "example",
            "language": "en"
          },
          "validation_policy_ref": {
            "policy_id": "kristal.v5:validation-policy:divergent-position-self-declared",
            "policy_version": "1"
          }
        },
        {
          "recognition_id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
          "recognition_status": "rejected",
          "recognized_as": "rejected_claim",
          "authority_channel": {
            "authority_channel_id": "authority:global-science-reference-example",
            "name": "Global Science Reference Example"
          },
          "scope": {
            "domain": "science",
            "subdomain": "planetary-science",
            "jurisdiction": null,
            "time_window": null,
            "tenant_id": null,
            "environment": "example",
            "language": "en"
          },
          "validation_policy_ref": {
            "policy_id": "kristal.v5:validation-policy:scientific-reference-review",
            "policy_version": "1"
          }
        }
      ],
      "validation": {
        "validation_status": "validated",
        "validated_as": "disputed_position",
        "certainty_level": "low",
        "authority_channel": {
          "authority_channel_id": "authority:flat-earth-collective-example",
          "name": "Flat Earth Collective Example"
        },
        "validation_policy_ref": {
          "policy_id": "kristal.v5:validation-policy:divergent-position-self-declared",
          "policy_version": "1"
        },
        "scope": {
          "domain": "research",
          "subdomain": "divergent-world-model",
          "jurisdiction": null,
          "time_window": null,
          "tenant_id": null,
          "environment": "example",
          "language": "en"
        },
        "reason_codes": ["authority_recognized", "disagreement_preserved"],
        "validation_refs": [],
        "notes": "Validated only as a self-declared disputed position within the divergent fork authority channel. This does not imply scientific recognition."
      },
      "uncertainty": {
        "confidence": 0.1,
        "method": "authority-scoped example confidence",
        "notes": "Low certainty outside the self-declared divergent authority channel."
      },
      "lineage": {
        "source_assertions": [],
        "source_artifacts": [
          {
            "artifact_id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
            "artifact_type": "reference_exchange",
            "content_hash": {
              "alg": "sha256",
              "value": "6666666666666666666666666666666666666666666666666666666666666666"
            }
          }
        ],
        "transforms": [
          {
            "transform_id": "transform:fork-creation-0001",
            "transform_type": "manual_edit",
            "tool": "example-editor",
            "policy_ref": {
              "policy_id": "kristal.v5:fork-policy:preserve-lineage-and-scope",
              "policy_version": "1"
            },
            "created_at": "2026-06-12T16:15:00Z",
            "notes": "Created as an explicit divergent fork. Recognition from the source reference artifact is not inherited."
          }
        ]
      },
      "conflicts_with": [
        "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
      ],
      "supersedes": [],
      "notes": "This assertion may be rendered only with labels that preserve its disputed status, low certainty, and authority scope."
    },
    {
      "assertion_id": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "source_assertion_id": "science-reference-claim-0001",
      "statement": {
        "subject": {
          "label": "Earth",
          "description": "The planet Earth",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:global-science-reference-example",
            "name": "Global Science Reference Example"
          }
        },
        "predicate": {
          "label": "has asserted shape",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:global-science-reference-example",
            "name": "Global Science Reference Example"
          }
        },
        "object": {
          "kind": "string",
          "value": "approximately spherical"
        },
        "qualifiers": [
          {
            "predicate": {
              "label": "epistemic mode",
              "language": "en"
            },
            "object": {
              "kind": "string",
              "value": "scientific reference claim"
            },
            "scope": {
              "domain": "science",
              "subdomain": "planetary-science",
              "jurisdiction": null,
              "time_window": null,
              "tenant_id": null,
              "environment": "example",
              "language": "en"
            }
          }
        ],
        "rank": "preferred",
        "statement_hash": {
          "alg": "sha256",
          "value": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
        }
      },
      "natural_language_statement": {
        "text": "Earth is approximately spherical.",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=31098e1b03fb:351-700
start=351
end=700
----
        "lang": "en"
      },
      "assertion_status": "validated",
      "certainty_level": "established",
      "validated_as": "high_confidence_fact",
      "scope": {
        "domain": "science",
        "subdomain": "planetary-science",
        "jurisdiction": null,
        "time_window": null,
        "tenant_id": null,
        "environment": "example",
        "language": "en"
      },
      "evidence_refs": [
        {
          "evidence_id": "evidence:science-reference-0001",
          "source_ref": {
            "source_id": "source:global-science-reference-earth-shape",
            "source_type": "institutional_record",
            "title": "Global science reference position on Earth shape",
            "publisher": "Global Science Reference Example",
            "content_hash": {
              "alg": "sha256",
              "value": "4444444444444444444444444444444444444444444444444444444444444444"
            },
            "authority_channel": {
              "authority_channel_id": "authority:global-science-reference-example",
              "name": "Global Science Reference Example"
            }
          },
          "quote": "The reference model describes Earth as approximately spherical for general scientific and educational use.",
          "section": "Reference position",
          "evidence_status": "sufficient",
          "content_hash": {
            "alg": "sha256",
            "value": "abababababababababababababababababababababababababababababababab"
          }
        }
      ],
      "provenance_refs": [
        {
          "artifact_id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
          "artifact_type": "reference_exchange",
          "content_hash": {
            "alg": "sha256",
            "value": "6666666666666666666666666666666666666666666666666666666666666666"
          },
          "created_at": "2026-06-01T00:00:00Z"
        }
      ],
      "authority_recognition_refs": [
        {
          "recognition_id": "sha256:babababababababababababababababababababababababababababababababa",
          "recognition_status": "recognized",
          "recognized_as": "high_confidence_fact",
          "authority_channel": {
            "authority_channel_id": "authority:global-science-reference-example",
            "name": "Global Science Reference Example"
          },
          "scope": {
            "domain": "science",
            "subdomain": "planetary-science",
            "jurisdiction": null,
            "time_window": null,
            "tenant_id": null,
            "environment": "example",
            "language": "en"
          },
          "validation_policy_ref": {
            "policy_id": "kristal.v5:validation-policy:scientific-reference-review",
            "policy_version": "1"
          }
        }
      ],
      "validation": {
        "validation_status": "validated",
        "validated_as": "high_confidence_fact",
        "certainty_level": "established",
        "authority_channel": {
          "authority_channel_id": "authority:global-science-reference-example",
          "name": "Global Science Reference Example"
        },
        "validation_policy_ref": {
          "policy_id": "kristal.v5:validation-policy:scientific-reference-review",
          "policy_version": "1"
        },
        "scope": {
          "domain": "science",
          "subdomain": "planetary-science",
          "jurisdiction": null,
          "time_window": null,
          "tenant_id": null,
          "environment": "example",
          "language": "en"
        },
        "reason_codes": ["authority_recognized", "evidence_sufficient", "policy_satisfied"],
        "validation_refs": [],
        "notes": "Included to preserve the source reference position that the divergent fork disputes."
      },
      "uncertainty": {
        "confidence": 0.99,
        "method": "authority-scoped example confidence",
        "notes": "Established within the global science reference example channel."
      },
      "lineage": {
        "source_assertions": [],
        "source_artifacts": [
          {
            "artifact_id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
            "artifact_type": "reference_exchange",
            "content_hash": {
              "alg": "sha256",
              "value": "6666666666666666666666666666666666666666666666666666666666666666"
            }
          }
        ],
        "transforms": [
          {
            "transform_id": "transform:reference-preservation-0001",
            "transform_type": "import",
            "tool": "example-importer",
            "policy_ref": {
              "policy_id": "kristal.v5:fork-policy:preserve-lineage-and-scope",
              "policy_version": "1"
            },
            "created_at": "2026-06-12T16:16:00Z",
            "notes": "Preserved as the source reference claim against which the divergent assertion is positioned."
          }
        ]
      },
      "conflicts_with": [
        "sha256:7777777777777777777777777777777777777777777777777777777777777777"
      ],
      "supersedes": [],
      "notes": "This assertion remains recognized by its own authority channel. The divergent fork does not revoke or overwrite it."
    }
  ],
  "provenance": [
    {
      "provenance_id": "prov:fork-created-0001",
      "event_type": "created",
      "created_at": "2026-06-12T16:15:00Z",
      "agent": {
        "agent_id": "agent:flat-earth-collective-example",
        "name": "Flat Earth Collective Example",
        "agent_type": "community",
        "authority_channel": {
          "authority_channel_id": "authority:flat-earth-collective-example",
          "name": "Flat Earth Collective Example"
        }
      },
      "source_ref": {
        "source_id": "source:flat-earth-collective-example-brief",
        "source_type": "human_submission",
        "title": "Example divergent position brief",
        "publisher": "Flat Earth Collective Example",
        "content_hash": {
          "alg": "sha256",
          "value": "3333333333333333333333333333333333333333333333333333333333333333"
        },
        "authority_channel": {
          "authority_channel_id": "authority:flat-earth-collective-example",
          "name": "Flat Earth Collective Example"
        }
      },
      "policy_refs": [
        {
          "policy_id": "kristal.v5:fork-policy:preserve-lineage-and-scope",
          "policy_version": "1"
        }
      ],
      "notes": "The divergent fork was created without inheriting recognition from the source reference artifact."
    },
    {
      "provenance_id": "prov:reference-imported-0001",
      "event_type": "imported",
      "created_at": "2026-06-12T16:16:00Z",
      "agent": {
        "agent_id": "agent:example-importer",
        "name": "Example Importer",
        "agent_type": "system"
      },
      "artifact_ref": {
        "artifact_id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
        "artifact_type": "reference_exchange",
        "content_hash": {
          "alg": "sha256",
          "value": "6666666666666666666666666666666666666666666666666666666666666666"
        },
        "created_at": "2026-06-01T00:00:00Z"
      },
      "policy_refs": [
        {
          "policy_id": "kristal.v5:fork-policy:preserve-lineage-and-scope",
          "policy_version": "1"
        }
      ],
      "notes": "The source reference assertion is preserved so readers can inspect the disagreement."
    }
  ],
  "review_refs": [],
  "policy_refs": [
    {
      "policy_id": "kristal.v5:fork-policy:preserve-lineage-and-scope",
      "policy_version": "1"
    },
    {
      "policy_id": "kristal.v5:validation-policy:divergent-position-self-declared",
      "policy_version": "1"
    },
    {
      "policy_id": "kristal.v5:validation-policy:scientific-reference-review",
      "policy_version": "1"
    }
  ],
  "authority_recognition_refs": [
    {
      "recognition_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "recognition_status": "recognized",
      "recognized_as": "disputed_position",
      "authority_channel": {
        "authority_channel_id": "authority:flat-earth-collective-example",
        "name": "Flat Earth Collective Example"
      },
      "scope": {
        "domain": "research",
        "subdomain": "divergent-world-model",
        "jurisdiction": null,
        "time_window": null,
        "tenant_id": null,
        "environment": "example",
        "language": "en"
      },
      "validation_policy_ref": {
        "policy_id": "kristal.v5:validation-policy:divergent-position-self-declared",
        "policy_version": "1"
      }
    },
    {
      "recognition_id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
      "recognition_status": "rejected",
      "recognized_as": "rejected_claim",
      "authority_channel": {
        "authority_channel_id": "authority:global-science-reference-example",
        "name": "Global Science Reference Example"
      },
      "scope": {
        "domain": "science",
        "subdomain": "planetary-science",
        "jurisdiction": null,
        "time_window": null,
        "tenant_id": null,
        "environment": "example",
        "language": "en"
      },
      "validation_policy_ref": {
        "policy_id": "kristal.v5:validation-policy:scientific-reference-review",
        "policy_version": "1"
      }
    }
  ],
  "reader_policy_refs": [
    {
      "reader_policy_id": "reader_policy:research-all-with-labels",
      "mode": "all_with_labels"
    },
    {
      "reader_policy_id": "reader_policy:validated-only-selected-authorities",
      "mode": "validated_only"
    }
  ],
  "certainty_summary": {
    "counts_by_certainty_level": {
      "low": 1,
      "established": 1
    },
    "counts_by_assertion_status": {
      "disputed": 1,
      "validated": 1
    },
    "counts_by_validated_as": {
      "disputed_position": 1,
      "high_confidence_fact": 1
    },
    "notes": "This example intentionally contains conflicting assertions to demonstrate divergent fork behavior."
  },
  "validation_summary": {
    "validation_status": "disputed",
    "recognition_status": "disputed",
    "authority_channels": [
      {
        "authority_channel_id": "authority:flat-earth-collective-example",
        "name": "Flat Earth Collective Example"
      },
      {
        "authority_channel_id": "authority:global-science-reference-example",
        "name": "Global Science Reference Example"
      }
    ],
    "validation_refs": [],
    "recognition_refs": [
      {
        "recognition_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
        "recognition_status": "recognized",
        "recognized_as": "disputed_position",
        "authority_channel": {
          "authority_channel_id": "authority:flat-earth-collective-example",
          "name": "Flat Earth Collective Example"
        }
      },
      {
        "recognition_id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
        "recognition_status": "rejected",
        "recognized_as": "rejected_claim",
        "authority_channel": {
          "authority_channel_id": "authority:global-science-reference-example",
          "name": "Global Science Reference Example"
        }
      }
    ],
    "reason_codes": ["conflict_detected", "disagreement_preserved"],
    "notes": "The state is valid as a divergent fork example. It is not a reference artifact and should not be rendered as a universal factual reference."
  },
  "lineage": {
    "source_artifacts": [
      {
        "artifact_id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
        "artifact_type": "reference_exchange",
        "content_hash": {
          "alg": "sha256",
          "value": "6666666666666666666666666666666666666666666666666666666666666666"
        },
        "created_at": "2026-06-01T00:00:00Z"
      }
    ],
    "source_states": [],
    "transforms": [
      {
        "transform_id": "transform:divergent-fork-0001",
        "transform_type": "manual_edit",
        "tool": "example-editor",
        "policy_ref": {
          "policy_id": "kristal.v5:fork-policy:preserve-lineage-and-scope",
          "policy_version": "1"
        },
        "created_at": "2026-06-12T16:15:00Z",
        "notes": "A divergent fork may disagree with a source reference artifact while preserving source identity, conflict metadata, and authority scope."
      }
    ],
--- CHUNK END ---

--- CHUNK BEGIN ---
id=31098e1b03fb:701-756
start=701
end=756
----
    "compiler": {
      "agent_id": "agent:example-compiler",
      "name": "Example Compiler",
      "agent_type": "system"
    },
    "policy_refs": [
      {
        "policy_id": "kristal.v5:fork-policy:preserve-lineage-and-scope",
        "policy_version": "1"
      }
    ]
  },
  "build": {
    "build_id": "build:20260612T163000Z:divergent-fork-example",
    "schema_version": "5.0",
    "compile_status": "succeeded",
    "validation_status": "disputed",
    "review_status": "completed",
    "recognition_status": "none",
    "publication_status": "not_published",
    "activation_status": "not_applicable",
    "working_outputs": [],
    "reference_outputs": [],
    "reason_codes": ["conflict_detected", "disagreement_preserved"],
    "created_at": "2026-06-12T16:30:00Z"
  },
  "warnings": [
    {
      "code": "CONFLICT_DETECTED",
      "message": "This Structured Epistemic State contains assertions that conflict across authority channels.",
      "path": "/assertions",
      "reason_code": "conflict_detected"
    },
    {
      "code": "LOW_CERTAINTY",
      "message": "The divergent fork assertion has low certainty outside its declaring authority channel.",
      "path": "/assertions/0",
      "reason_code": "certainty_too_low_for_policy"
    }
  ],
  "extensions": {
    "example_purpose": "Demonstrates that divergent forks may exist, preserve lineage, declare authority scope, and remain filterable by reader policy without inheriting reference recognition."
  },
  "signatures": [
    {
      "key_id": "flat_earth_collective_example_ed25519_v1",
      "alg": "ed25519",
      "signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
      "created_at": "2026-06-12T16:30:10Z",
      "authority_channel": {
        "authority_channel_id": "authority:flat-earth-collective-example",
        "name": "Flat Earth Collective Example"
      }
    }
  ]
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/exchange-federation-manifest.example.json"
id=8efa6d5199eb
kind=source
size=14422
lines=490
line_ref=1-490
chunks=2
chunk_refs=1-350,351-490
summary="Source file."

--- CHUNK BEGIN ---
id=8efa6d5199eb:1-350
start=1
end=350
----
{
"schema_version": "5.0",
"artifact_type": "exchange_federation_manifest",
"manifest_id": "sha256:0f4a2c8e9b1d3f5a6c7e8d9f0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2de",
"created_at": "2026-03-01T12:00:00Z",
"federation_id": "sha256:0f4a2c8e9b1d3f5a6c7e8d9f0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2de",
"canonicalization_profile": "kristal.v5:jcs-rfc8785",
"canonicalization_version": "1",
"content_hash": {
"alg": "sha256",
"value": "0f4a2c8e9b1d3f5a6c7e8d9f0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2de"
},
"authority_registry_ref": {
"registry_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"ref": "authority/authority-registry.json",
"content_hash": {
"alg": "sha256",
"value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"signatures": [
{
"sig_id": "sig:authority-registry-example-0001",
"key_id": "kristal-reference-ops-ed25519-2026-03",
"alg": "ed25519",
"payload_hash": {
"alg": "sha256",
"value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"signature": "ZHVtbXktYXV0aG9yaXR5LXJlZ2lzdHJ5LXNpZ25hdHVyZQ",
"created_at": "2026-03-01T12:00:00Z",
"purpose": "authority"
}
]
},
"shards": [
{
"shard_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"scope": {
"domain": "education",
"subdomain": "science-reference",
"jurisdiction": null,
"time_window": null,
"tenant_id": "tenant_demo",
"environment": "dev",
"language": "en"
},
"artifact_status": "reference",
"shard_manifest_ref": "shards/science-earth-shape-reference/exchange-shard-manifest.json",
"shard_manifest_hash": {
"alg": "sha256",
"value": "1111111111111111111111111111111111111111111111111111111111111111"
},
"authority_channel_refs": [
"authority:unesco-science-education"
],
"authority_recognition_refs": [
{
"artifact_type": "authority_recognition",
"id": "sha256:1313131313131313131313131313131313131313131313131313131313131313",
"ref": "authority-recognitions/unesco-science-earth-shape-reference.json",
"content_hash": {
"alg": "sha256",
"value": "1313131313131313131313131313131313131313131313131313131313131313"
}
}
],
"validation_refs": [
{
"artifact_type": "validation_report",
"id": "sha256:1212121212121212121212121212121212121212121212121212121212121212",
"ref": "validation-reports/science-earth-shape-reference-validation.json",
"content_hash": {
"alg": "sha256",
"value": "1212121212121212121212121212121212121212121212121212121212121212"
}
}
],
"extensions": {
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_level": "established",
"validated_as": "high_confidence_fact"
}
},
{
"shard_id": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
"scope": {
"domain": "wikidata",
"subdomain": "seed-reference",
"jurisdiction": null,
"time_window": "2026-03-01",
"tenant_id": "tenant_demo",
"environment": "dev",
"language": "en"
},
"artifact_status": "reference",
"shard_manifest_ref": "shards/wikidata-seed-earth-shape/exchange-shard-manifest.json",
"shard_manifest_hash": {
"alg": "sha256",
"value": "2222222222222222222222222222222222222222222222222222222222222222"
},
"authority_channel_refs": [
"authority:wikidata-seed"
],
"authority_recognition_refs": [
{
"artifact_type": "authority_recognition",
"id": "sha256:2424242424242424242424242424242424242424242424242424242424242424",
"ref": "authority-recognitions/wikidata-seed-recognition.json",
"content_hash": {
"alg": "sha256",
"value": "2424242424242424242424242424242424242424242424242424242424242424"
}
}
],
"validation_refs": [
{
"artifact_type": "validation_report",
"id": "sha256:2323232323232323232323232323232323232323232323232323232323232323",
"ref": "validation-reports/wikidata-seed-packaging-validation.json",
"content_hash": {
"alg": "sha256",
"value": "2323232323232323232323232323232323232323232323232323232323232323"
}
}
],
"extensions": {
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_profile": "mixed",
"validated_as": "institutional_reference"
}
},
{
"shard_id": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
"scope": {
"domain": "research",
"subdomain": "earth-observation-notes",
"jurisdiction": null,
"time_window": "2025-01-01/2026-03-01",
"tenant_id": "tenant_demo",
"environment": "dev",
"language": "en"
},
"artifact_status": "under_review",
"shard_manifest_ref": "shards/independent-research-earth-observation-notes/exchange-shard-manifest.json",
"shard_manifest_hash": {
"alg": "sha256",
"value": "3333333333333333333333333333333333333333333333333333333333333333"
},
"authority_channel_refs": [
"authority:independent-research-collective"
],
"authority_recognition_refs": [],
"validation_refs": [],
"extensions": {
"validation_status": "in_review",
"recognition_status": "under_review",
"certainty_level": "medium",
"validated_as": "reviewed_claim"
}
},
{
"shard_id": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
"scope": {
"domain": "local_notes",
"subdomain": "divergent-earth-shape-claims",
"jurisdiction": null,
"time_window": null,
"tenant_id": "tenant_demo",
"environment": "dev",
"language": "en"
},
"artifact_status": "working",
"shard_manifest_ref": "shards/local-community-divergent-earth-shape-claims/exchange-shard-manifest.json",
"shard_manifest_hash": {
"alg": "sha256",
"value": "4444444444444444444444444444444444444444444444444444444444444444"
},
"authority_channel_refs": [
"authority:local-community-archive"
],
"authority_recognition_refs": [
{
"artifact_type": "authority_recognition",
"id": "sha256:4646464646464646464646464646464646464646464646464646464646464646",
"ref": "authority-recognitions/local-community-divergent-position-recognition.json",
"content_hash": {
"alg": "sha256",
"value": "4646464646464646464646464646464646464646464646464646464646464646"
}
}
],
"validation_refs": [
{
"artifact_type": "validation_report",
"id": "sha256:4545454545454545454545454545454545454545454545454545454545454545",
"ref": "validation-reports/local-community-divergent-position-validation.json",
"content_hash": {
"alg": "sha256",
"value": "4545454545454545454545454545454545454545454545454545454545454545"
}
}
],
"extensions": {
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_level": "low",
"validated_as": "disputed_position"
}
},
{
"shard_id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
"scope": {
"domain": "mythology",
"subdomain": "cosmology-symbolic-systems",
"jurisdiction": null,
"time_window": null,
"tenant_id": "tenant_demo",
"environment": "dev",
"language": "en"
},
"artifact_status": "reference",
"shard_manifest_ref": "shards/mythological-cosmology-corpus/exchange-shard-manifest.json",
"shard_manifest_hash": {
"alg": "sha256",
"value": "5555555555555555555555555555555555555555555555555555555555555555"
},
"authority_channel_refs": [
"authority:cultural-heritage-archive"
],
"authority_recognition_refs": [
{
"artifact_type": "authority_recognition",
"id": "sha256:5757575757575757575757575757575757575757575757575757575757575757",
"ref": "authority-recognitions/cultural-heritage-mythology-recognition.json",
"content_hash": {
"alg": "sha256",
"value": "5757575757575757575757575757575757575757575757575757575757575757"
}
}
],
"validation_refs": [
{
"artifact_type": "validation_report",
"id": "sha256:5656565656565656565656565656565656565656565656565656565656565656",
"ref": "validation-reports/mythological-cosmology-corpus-validation.json",
"content_hash": {
"alg": "sha256",
"value": "5656565656565656565656565656565656565656565656565656565656565656"
}
}
],
"extensions": {
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_level": "not_applicable",
"validated_as": "mythological_corpus"
}
}
],
"composition_policy": {
"policy_id": "kristal.v5:composition-policy:preserve-disagreement-demo",
"policy_version": "1",
"overlap_strategy": "preserve_all",
"conflict_strategy": "preserve_disagreement",
"default_visibility": "reader_policy",
"ordering": "stable",
"authority_precedence": [
"authority:unesco-science-education",
"authority:wikidata-seed",
"authority:independent-research-collective",
"authority:local-community-archive",
"authority:cultural-heritage-archive"
],
"parameters": {
"conflict_labels_required": true,
"preserve_source_shard_ids": true,
"preserve_authority_channels": true
}
},
"reader_policy_refs": [
{
"artifact_type": "reader_policy",
"id": "reader_policy:reference-only-science-education",
"ref": "reader-policies/reference-only-science-education.json",
"content_hash": {
"alg": "sha256",
"value": "6161616161616161616161616161616161616161616161616161616161616161"
}
},
{
"artifact_type": "reader_policy",
"id": "reader_policy:validated-only-with-labels",
"ref": "reader-policies/validated-only-with-labels.json",
"content_hash": {
"alg": "sha256",
"value": "6262626262626262626262626262626262626262626262626262626262626262"
}
},
{
"artifact_type": "reader_policy",
"id": "reader_policy:research-all-with-labels",
"ref": "reader-policies/research-all-with-labels.json",
"content_hash": {
"alg": "sha256",
"value": "6363636363636363636363636363636363636363636363636363636363636363"
}
},
{
"artifact_type": "reader_policy",
"id": "reader_policy:creative-and-mythology",
"ref": "reader-policies/creative-and-mythology.json",
"content_hash": {
"alg": "sha256",
"value": "6464646464646464646464646464646464646464646464646464646464646464"
}
}
],
"authority_recognition_refs": [
{
"artifact_type": "authority_recognition",
"id": "sha256:8181818181818181818181818181818181818181818181818181818181818181",
"ref": "authority-recognitions/kristal-reference-ops-federation-recognition.json",
"content_hash": {
"alg": "sha256",
"value": "8181818181818181818181818181818181818181818181818181818181818181"
}
}
],
"validation_policy_refs": [
{
"artifact_type": "validation_policy",
"id": "kristal.v5:validation-policy:federation-schema-validation",
"ref": "validation-policies/federation-schema-validation.json",
"content_hash": {
"alg": "sha256",
"value": "7171717171717171717171717171717171717171717171717171717171717171"
}
}
],
"trust_requirements": [
{
"scope": {
"domain": "education",
"subdomain": "science-reference"
},
"required_authority_channels": [
"authority:unesco-science-education"
],
--- CHUNK END ---

--- CHUNK BEGIN ---
id=8efa6d5199eb:351-490
start=351
end=490
----
"allowed_validation_statuses": [
"validated",
"conditionally_validated"
],
"allowed_certainty_levels": [
"high",
"established"
],
"allowed_validated_as": [
"high_confidence_fact"
],
"include_disputed": false,
"include_fictional": false,
"include_mythological": false
},
{
"scope": {
"domain": "local_notes",
"subdomain": "divergent-earth-shape-claims"
},
"required_authority_channels": [
"authority:local-community-archive"
],
"allowed_validation_statuses": [
"validated",
"disputed"
],
"allowed_certainty_levels": [
"low",
"medium"
],
"allowed_validated_as": [
"disputed_position"
],
"include_disputed": true,
"include_fictional": false,
"include_mythological": false
},
{
"scope": {
"domain": "mythology"
},
"required_authority_channels": [
"authority:cultural-heritage-archive"
],
"allowed_validation_statuses": [
"validated",
"conditionally_validated"
],
"allowed_certainty_levels": [
"not_applicable"
],
"allowed_validated_as": [
"mythological_corpus"
],
"include_disputed": true,
"include_fictional": false,
"include_mythological": true
}
],
"publisher": {
"authority_channel_id": "authority:kristal-reference-ops",
"key_id": "kristal-reference-ops-ed25519-2026-03",
"name": "Kristal Reference Operations"
},
"signatures": [
{
"sig_id": "sig:plural-authority-federation-0001",
"key_id": "kristal-reference-ops-ed25519-2026-03",
"alg": "ed25519",
"payload_hash": {
"alg": "sha256",
"value": "0f4a2c8e9b1d3f5a6c7e8d9f0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2de"
},
"signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
"created_at": "2026-03-01T12:00:10Z",
"purpose": "publisher",
"signer": {
"name": "Kristal Reference Operations",
"org": "Kristal Foundation",
"authority_channel_id": "authority:kristal-reference-ops"
}
}
],
"references": {
"spec_version": "5.0",
"docs_uri": "https://kristal.org/docs/v5/exchange-federation-manifest"
},
"extensions": {
"example_name": "plural-authority-federation",
"example_purpose": "Demonstrates Kristal v5 federation across multiple authority channels, reader policies, certainty levels, and preserved disagreement.",
"query_contract_ref": {
"artifact_type": "query_contract",
"id": "kristal.v5:query:triple-pattern@1",
"ref": "query-contracts/kristal-v5-triple-pattern-v1.json",
"content_hash": {
"alg": "sha256",
"value": "9191919191919191919191919191919191919191919191919191919191919191"
}
},
"conflict_summary": {
"conflict_strategy": "preserve_disagreement",
"conflicts_detected": true,
"conflict_count": 1,
"conflicts": [
{
"conflict_id": "conflict:earth-shape-primary-claim",
"target_statement_key": "earth_shape",
"status": "preserved",
"visible_in_reader_policies": [
"reader_policy:validated-only-with-labels",
"reader_policy:research-all-with-labels"
],
"hidden_in_reader_policies": [
"reader_policy:reference-only-science-education"
],
"claims": [
{
"source_shard_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"authority_channel": "authority:unesco-science-education",
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_level": "established",
"validated_as": "high_confidence_fact"
},
{
"source_shard_id": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
"authority_channel": "authority:local-community-archive",
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_level": "low",
"validated_as": "disputed_position"
}
]
}
]
},
"notes": "This example includes a recognized science-education shard, a Wikidata seed shard, a research shard, a local divergent-position shard, and a mythological corpus shard. Federation preserves labels and does not silently merge or universalize authority recognition."
}
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/exchange-shard-manifest.example.json"
id=7f2b3ca4ae7d
kind=source
size=9228
lines=338
line_ref=1-338
chunks=0
chunk_refs=
summary="Source file."
----
000001 | {
000002 | "schema_version": "5.0",
000003 | "artifact_type": "exchange_shard_manifest",
000004 | "manifest_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
000005 | "created_at": "2026-02-26T18:05:00Z",
000006 | "shard_id": "sha256:9f3a0d6c7b0a1f2e3d4c5b6a7980a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c",
000007 | "kristal_id": "sha256:9f3a0d6c7b0a1f2e3d4c5b6a7980a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c",
000008 | "artifact_status": "reference",
000009 | "canonicalization_profile": "kristal.v5:jcs-rfc8785",
000010 | "canonicalization_version": "1",
000011 | "content_hash": {
000012 | "alg": "sha256",
000013 | "value": "9f3a0d6c7b0a1f2e3d4c5b6a7980a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c"
000014 | },
000015 | "producer": {
000016 | "producer_id": "producer:kristal-compiler",
000017 | "name": "kristal-compiler",
000018 | "org": "Kristal Framework",
000019 | "authority_channel": "authority:unesco-heritage",
000020 | "software": {
000021 | "name": "kristal-compiler",
000022 | "version": "5.0.0",
000023 | "build_hash": {
000024 | "alg": "sha256",
000025 | "value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
000026 | }
000027 | }
000028 | },
000029 | "build": {
000030 | "build_id": "build-2026-02-26T180500Z-0001",
000031 | "schema_version": "5.0",
000032 | "compile_status": "succeeded",
000033 | "validation_status": "validated",
000034 | "review_status": "completed",
000035 | "recognition_status": "recognized",
000036 | "publication_status": "published",
000037 | "activation_status": "not_applicable",
000038 | "working_outputs": [],
000039 | "reference_outputs": [
000040 | {
000041 | "artifact_type": "exchange_shard",
000042 | "artifact_id": "sha256:9f3a0d6c7b0a1f2e3d4c5b6a7980a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c",
000043 | "content_hash": {
000044 | "alg": "sha256",
000045 | "value": "9f3a0d6c7b0a1f2e3d4c5b6a7980a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c"
000046 | }
000047 | }
000048 | ],
000049 | "reason_codes": [
000050 | "schema_valid",
000051 | "provenance_sufficient",
000052 | "evidence_sufficient",
000053 | "policy_satisfied",
000054 | "authority_recognized",
000055 | "hash_valid",
000056 | "signature_valid"
000057 | ],
000058 | "created_at": "2026-02-26T18:05:00Z",
000059 | "compiler": {
000060 | "name": "kristal-compiler",
000061 | "version": "5.0.0",
000062 | "profile": "kristal.v5:exchange-shard"
000063 | }
000064 | },
000065 | "inputs": {
000066 | "source_refs": [
000067 | {
000068 | "artifact_type": "source_snapshot",
000069 | "artifact_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
000070 | "uri": "konnaxion://snapshots/snap-2026-02-25-unesco-dump",
000071 | "content_hash": {
000072 | "alg": "sha256",
000073 | "value": "1111111111111111111111111111111111111111111111111111111111111111"
000074 | }
000075 | },
000076 | {
000077 | "artifact_type": "build_recipe",
000078 | "artifact_id": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
000079 | "uri": "konnaxion://recipes/recipe-unesco-heritage-core",
000080 | "content_hash": {
000081 | "alg": "sha256",
000082 | "value": "2222222222222222222222222222222222222222222222222222222222222222"
000083 | }
000084 | },
000085 | {
000086 | "artifact_type": "structured_epistemic_state",
000087 | "artifact_id": "sha256:4b2f0a7c9e1d8f6a3c5b7d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c",
000088 | "uri": "konnaxion://structured-epistemic-states/sha256:4b2f0a7c9e1d8f6a3c5b7d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c.json"
000089 | },
000090 | {
000091 | "artifact_type": "claim_ir",
000092 | "artifact_id": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
000093 | "uri": "konnaxion://claim-ir/ci-2f5c2a9b-6c6d-4f9f-8caa-31c6a0b1b7d4.json"
000094 | },
000095 | {
000096 | "artifact_type": "resolved_claim_ir",
000097 | "artifact_id": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
000098 | "uri": "konnaxion://resolved-claim-ir/rci-7a2f3df0-3e9b-4e63-9fd3-2f8b9a7d5d5c.json"
000099 | }
000100 | ],
000101 | "derived_from": [
000102 | {
000103 | "artifact_type": "source_snapshot",
000104 | "artifact_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
000105 | "uri": "konnaxion://snapshots/snap-2026-02-25-unesco-dump"
000106 | }
000107 | ],
000108 | "merged_from": [],
000109 | "supersedes": [],
000110 | "input_hashes": [
000111 | {
000112 | "alg": "sha256",
000113 | "value": "7b1a9c2d3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e8f"
000114 | }
000115 | ]
000116 | },
000117 | "policies": {
000118 | "compilation_policy_ref": {
000119 | "policy_id": "kristal.v5:compilation-policy:heritage-shard",
000120 | "policy_version": "1"
000121 | },
000122 | "validation_policy_refs": [
000123 | {
000124 | "policy_id": "policy:unesco-heritage-reference-validation",
000125 | "policy_version": "1"
000126 | }
000127 | ],
000128 | "recognition_policy_refs": [
000129 | {
000130 | "policy_id": "policy:unesco-heritage-authority-recognition",
000131 | "policy_version": "1"
000132 | }
000133 | ],
000134 | "composition_policy_ref": {
000135 | "policy_id": "kristal.v5:composition-policy:heritage-authority-precedence",
000136 | "policy_version": "1"
000137 | },
000138 | "reader_policy_refs": [
000139 | {
000140 | "reader_policy_id": "reader_policy:reference-only-unesco-heritage",
000141 | "mode": "reference_only"
000142 | },
000143 | {
000144 | "reader_policy_id": "reader_policy:validated-only-unesco-heritage",
000145 | "mode": "validated_only"
000146 | }
000147 | ],
000148 | "runtime_policy_refs": [
000149 | {
000150 | "policy_id": "kristal.v5:runtime-policy:offline-reference-pack",
000151 | "policy_version": "1"
000152 | }
000153 | ]
000154 | },
000155 | "scope": {
000156 | "domain": "heritage",
000157 | "subdomain": "unesco",
000158 | "jurisdiction": null,
000159 | "time_window": "2020-01-01T00:00:00Z/2025-12-31T23:59:59Z",
000160 | "tenant_id": "tenant_demo",
000161 | "environment": "prod",
000162 | "language": "en"
000163 | },
000164 | "assertion_status_summary": {
000165 | "counts": {
000166 | "sourced": 1200,
000167 | "reviewed": 1100,
000168 | "validated": 1000
000169 | },
000170 | "dominant_status": "validated",
000171 | "contains_disputed": false,
000172 | "contains_rejected": false
000173 | },
000174 | "certainty_summary": {
000175 | "counts": {
000176 | "medium": 200,
000177 | "high": 600,
000178 | "established": 400
000179 | },
000180 | "lowest_certainty_level": "medium",
000181 | "highest_certainty_level": "established",
000182 | "mixed_certainty": true
000183 | },
000184 | "validation_refs": [
000185 | {
000186 | "validation_decision_id": "sha256:2f3e4d5c6b7a8901b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f50617283",
000187 | "target_ref": {
000188 | "artifact_type": "exchange_shard",
000189 | "artifact_id": "sha256:9f3a0d6c7b0a1f2e3d4c5b6a7980a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c",
000190 | "uri": "konnaxion://exchange-shards/heritage-unesco-2026-02.json"
000191 | },
000192 | "target_level": "shard",
000193 | "validation_status": "validated",
000194 | "validated_as": "institutional_reference",
000195 | "certainty_level": "high",
000196 | "authority_channel": "authority:unesco-heritage",
000197 | "validation_policy_ref": {
000198 | "policy_id": "policy:unesco-heritage-reference-validation",
000199 | "policy_version": "1"
000200 | },
000201 | "scope": {
000202 | "domain": "heritage",
000203 | "subdomain": "unesco",
000204 | "jurisdiction": null,
000205 | "time_window": "2020-01-01T00:00:00Z/2025-12-31T23:59:59Z",
000206 | "tenant_id": "tenant_demo",
000207 | "environment": "prod",
000208 | "language": "en"
000209 | },
000210 | "reason_codes": [
000211 | "schema_valid",
000212 | "provenance_sufficient",
000213 | "evidence_sufficient",
000214 | "policy_satisfied"
000215 | ]
000216 | }
000217 | ],
000218 | "authority_recognition_refs": [
000219 | {
000220 | "recognition_id": "sha256:6d7e8f9a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c",
000221 | "issuer_authority_channel": "authority:unesco-heritage",
000222 | "target_ref": {
000223 | "artifact_type": "exchange_shard",
000224 | "artifact_id": "sha256:9f3a0d6c7b0a1f2e3d4c5b6a7980a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c",
000225 | "uri": "konnaxion://exchange-shards/heritage-unesco-2026-02.json"
000226 | },
000227 | "target_level": "shard",
000228 | "recognition_status": "recognized",
000229 | "recognized_as": "institutional_reference",
000230 | "scope": {
000231 | "domain": "heritage",
000232 | "subdomain": "unesco",
000233 | "jurisdiction": null,
000234 | "time_window": "2020-01-01T00:00:00Z/2025-12-31T23:59:59Z",
000235 | "tenant_id": "tenant_demo",
000236 | "environment": "prod",
000237 | "language": "en"
000238 | },
000239 | "validation_policy_ref": {
000240 | "policy_id": "policy:unesco-heritage-reference-validation",
000241 | "policy_version": "1"
000242 | },
000243 | "reason_codes": [
000244 | "authority_recognized",
000245 | "policy_satisfied"
000246 | ]
000247 | }
000248 | ],
000249 | "reader_policy_refs": [
000250 | {
000251 | "reader_policy_id": "reader_policy:reference-only-unesco-heritage",
000252 | "mode": "reference_only"
000253 | },
000254 | {
000255 | "reader_policy_id": "reader_policy:validated-only-unesco-heritage",
000256 | "mode": "validated_only"
000257 | }
000258 | ],
000259 | "integrity": {
000260 | "hash_alg": "sha256",
000261 | "signature_required": true,
000262 | "trust_root_required": true,
000263 | "verification_requirements": [
000264 | "schema_validation",
000265 | "hash_verification",
000266 | "signature_verification",
000267 | "trust_root_verification",
000268 | "policy_check",
000269 | "scope_check",
000270 | "authority_recognition_check",
000271 | "reader_policy_check"
000272 | ],
000273 | "trust_roots": [
000274 | {
000275 | "trust_root_id": "trust-root:unesco-prod-2026",
000276 | "type": "authority_registry",
000277 | "uri": "konnaxion://authority-registries/unesco-prod-2026.json",
000278 | "content_hash": {
000279 | "alg": "sha256",
000280 | "value": "5555555555555555555555555555555555555555555555555555555555555555"
000281 | }
000282 | }
000283 | ]
000284 | },
000285 | "lineage": {
000286 | "source_artifacts": [
000287 | {
000288 | "artifact_type": "source_snapshot",
000289 | "artifact_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
000290 | "uri": "konnaxion://snapshots/snap-2026-02-25-unesco-dump"
000291 | }
000292 | ],
000293 | "transforms": [
000294 | {
000295 | "transform_id": "transform:recipe-unesco-heritage-core",
000296 | "name": "kristal-compatible-packaging",
000297 | "version": "1",
000298 | "policy_ref": {
000299 | "policy_id": "kristal.v5:compilation-policy:heritage-shard",
000300 | "policy_version": "1"
000301 | }
000302 | }
000303 | ],
000304 | "compiler": {
000305 | "name": "kristal-compiler",
000306 | "version": "5.0.0"
000307 | },
000308 | "policy_refs": [
000309 | {
000310 | "policy_id": "kristal.v5:compilation-policy:heritage-shard",
000311 | "policy_version": "1"
000312 | },
000313 | {
000314 | "policy_id": "policy:unesco-heritage-reference-validation",
000315 | "policy_version": "1"
000316 | }
000317 | ]
000318 | },
000319 | "signatures": [
000320 | {
000321 | "key_id": "unesco-prod-ed25519-2026-01",
000322 | "alg": "ed25519",
000323 | "signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
000324 | "created_at": "2026-02-26T18:05:10Z",
000325 | "purpose": "manifest-signature",
000326 | "signer": {
000327 | "name": "UNESCO Heritage Reference Channel",
000328 | "org": "UNESCO Example",
000329 | "authority_channel": "authority:unesco-heritage"
000330 | }
000331 | }
000332 | ],
000333 | "extensions": {
000334 | "source_namespace": "unesco",
000335 | "source_channel": "unesco-official",
000336 | "notes": "Example Kristal v5 shard manifest for a heritage reference shard. Validation and recognition are scoped to the declared UNESCO heritage authority channel."
000337 | }
000338 | }
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/exchange.example.json"
id=5617c713d86c
kind=source
size=10076
lines=373
line_ref=1-373
chunks=2
chunk_refs=1-350,351-373
summary="Source file."

--- CHUNK BEGIN ---
id=5617c713d86c:1-350
start=1
end=350
----
{
"schema_version": "5.0",
"artifact_type": "reference_exchange",
"exchange_version": "5.0",
"manifest_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"created_at": "2026-01-07T16:10:00Z",
"kristal_id": "sha256:9f3a0d6c7b0a1f2e3d4c5b6a7980a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c",
"artifact_status": "reference",
"canonicalization_profile": "kristal.v5:jcs-rfc8785",
"canonicalization_version": "1",
"content_hash": {
"alg": "sha256",
"value": "9f3a0d6c7b0a1f2e3d4c5b6a7980a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c"
},
"scope": {
"domain": "wikidata",
"subdomain": "seed-example",
"jurisdiction": null,
"time_window": "2026-01",
"tenant_id": "tenant_demo",
"environment": "demo",
"language": "en"
},
"build": {
"build_id": "build-2026-01-07T161000Z-0007",
"compiler_name": "kristal-compiler",
"compiler_version": "5.0.0",
"config_hash": {
"alg": "sha256",
"value": "3c8a8fe8f10f4c4a44b8f4d4b6b1f8b7f1a9e9c5a2b1c0d9e8f7a6b5c4d3e2f1"
},
"compile_status": "succeeded",
"validation_status": "validated",
"review_status": "completed",
"recognition_status": "recognized",
"publication_status": "published",
"activation_status": "not_applicable",
"working_outputs": [],
"reference_outputs": [
{
"id": "sha256:9f3a0d6c7b0a1f2e3d4c5b6a7980a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c",
"artifact_type": "reference_exchange",
"content_hash": {
"alg": "sha256",
"value": "9f3a0d6c7b0a1f2e3d4c5b6a7980a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c"
}
}
],
"reason_codes": [
"schema_valid",
"hash_valid",
"signature_valid",
"provenance_sufficient",
"policy_satisfied",
"authority_recognized"
],
"git_commit": "a1b2c3d4e5f6a7b8c9d0",
"environment": {
"created_at": "2026-01-07T16:10:00Z"
}
},
"inputs": {
"source_refs": [
{
"id": "sha256:2c8a8fe8f10f4c4a44b8f4d4b6b1f8b7f1a9e9c5a2b1c0d9e8f7a6b5c4d3e2f2",
"artifact_type": "structured_epistemic_state",
"content_hash": {
"alg": "sha256",
"value": "2c8a8fe8f10f4c4a44b8f4d4b6b1f8b7f1a9e9c5a2b1c0d9e8f7a6b5c4d3e2f2"
}
},
{
"id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"artifact_type": "external_dataset",
"content_hash": {
"alg": "sha256",
"value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
}
},
{
"id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
"artifact_type": "external_dataset",
"content_hash": {
"alg": "sha256",
"value": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
}
}
],
"source_snapshot_id": "snap-2026-01-06-wikidata-seed-demo",
"recipe_id": "recipe-demo-encyclopedia-core",
"structured_epistemic_state_ids": [
"sha256:2c8a8fe8f10f4c4a44b8f4d4b6b1f8b7f1a9e9c5a2b1c0d9e8f7a6b5c4d3e2f2"
],
"claim_ir_ids": [
"sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
],
"resolved_claim_ir_ids": [
"sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
],
"previous_exchange_ids": []
},
"source_state_refs": [
{
"id": "sha256:2c8a8fe8f10f4c4a44b8f4d4b6b1f8b7f1a9e9c5a2b1c0d9e8f7a6b5c4d3e2f2",
"artifact_type": "structured_epistemic_state",
"content_hash": {
"alg": "sha256",
"value": "2c8a8fe8f10f4c4a44b8f4d4b6b1f8b7f1a9e9c5a2b1c0d9e8f7a6b5c4d3e2f2"
}
}
],
"authority_registry_ref": {
"id": "sha256:0d8c7b6a5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b",
"artifact_type": "authority_registry",
"content_hash": {
"alg": "sha256",
"value": "b10a8db164e0754105b7a99be72e3fe5a1b3c2d4e5f60718293a4b5c6d7e8f90"
}
},
"authority_recognition_refs": [
{
"id": "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"artifact_type": "authority_recognition",
"content_hash": {
"alg": "sha256",
"value": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
}
}
],
"validation_refs": [
{
"id": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"artifact_type": "validation_report",
"content_hash": {
"alg": "sha256",
"value": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
}
}
],
"review_refs": [],
"reader_policy_refs": [
{
"id": "reader_policy:validated-only-wikidata-reference",
"artifact_type": "reader_policy"
},
{
"id": "reader_policy:research-all-with-labels",
"artifact_type": "reader_policy"
}
],
"profiles_enabled": [
"kristal.v5:jsonld-1.1@1",
"kristal.v5:rdf-wdqs-export@1",
"kristal.v5:profile-query-tpf-pagination@1"
],
"certainty_summary": {
"default_certainty_level": "high",
"contains_mixed_certainty": true,
"counts_by_certainty_level": {
"established": 2,
"high": 1,
"medium": 1,
"low": 0,
"speculative": 0,
"unknown": 0,
"not_applicable": 0
},
"contains_hypotheses": false,
"contains_disputed_assertions": false,
"contains_fictional_or_mythological_material": false,
"notes": "Example summary for a small Wikidata seed reference exchange. Counts are illustrative."
},
"validation_summary": {
"default_validation_status": "validated",
"validated_as": [
"institutional_reference",
"sourced_claim"
],
"authority_channels": [
"authority:wikidata-seed-demo"
],
"recognition_statuses": [
"recognized"
],
"counts_by_validation_status": {
"validated": 3,
"not_evaluated": 1,
"disputed": 0,
"rejected": 0,
"revoked": 0
},
"notes": "This Exchange is recognized as a reference artifact for the declared Wikidata seed demo scope. Recognition does not imply that every assertion is universally true."
},
"exports": {
"jsonld": {
"enabled": true,
"profile": "kristal.v5:jsonld-1.1@1",
"uri": "file:exports/demo-wikidata-seed.jsonld",
"media_type": "application/ld+json",
"content_hash": {
"alg": "sha256",
"value": "1111111111111111111111111111111111111111111111111111111111111111"
}
},
"wdqs": {
"enabled": true,
"profile": "kristal.v5:rdf-wdqs-export@1",
"uri": "file:exports/demo-wikidata-seed-full.nt",
"media_type": "application/n-triples",
"content_hash": {
"alg": "sha256",
"value": "2222222222222222222222222222222222222222222222222222222222222222"
}
}
},
"policies": {
"ordering_policies": [
"SPO",
"POS"
],
"row_group_policy": {
"type": "FIXED_ROWS",
"rows": 100000
},
"reader_policy_refs": [
{
"id": "reader_policy:validated-only-wikidata-reference",
"artifact_type": "reader_policy"
},
{
"id": "reader_policy:research-all-with-labels",
"artifact_type": "reader_policy"
}
],
"validation_policy_refs": [
{
"id": "kristal.v5:validation-policy:wikidata-seed-demo",
"artifact_type": "validation_decision"
}
],
"recognition_policy_refs": [
{
"id": "kristal.v5:recognition-policy:wikidata-seed-demo",
"artifact_type": "authority_recognition"
}
],
"composition_policy": {
"policy_id": "kristal.v5:composition-policy:wikidata-seed-demo",
"policy_version": "1",
"overlap_strategy": "preserve_all",
"conflict_strategy": "preserve_disagreement",
"default_visibility": "reader_policy",
"ordering": "stable",
"parameters": {
"default_reader_policy_id": "reader_policy:validated-only-wikidata-reference",
"supported_reader_modes": [
"reference_only",
"validated_only",
"research",
"all_with_labels"
],
"membership_filter_policy": {
"family": "binary_fuse",
"variant": "3wise",
"key_space": "spo_hash",
"target_fpr": 0.001,
"bits_per_key": 9.5,
"seed": 42
},
"bitmap_policy": {
"format": "roaring",
"run_opt": true
},
"join1_cap_policy": {
"cap": 5000,
"strict_mode": true,
"on_exceed": "error"
}
}
},
"allowed_runtime_pack_policies": [
"kristal.v5:runtime-pack-policy:offline-reference"
]
},
"references": [
{
"label": "Demo Wikidata seed Structured Epistemic State",
"uri": "file:states/demo-wikidata-seed.state.json",
"description": "Source state used to compile this reference Exchange."
},
{
"label": "Demo Wikidata seed validation report",
"uri": "file:validation/demo-wikidata-seed-validation-report.json",
"description": "Validation report used to recognize this Exchange for the declared scope."
}
],
"signatures": [
{
"key_id": "wikidata-seed-demo-ed25519-2026-01",
"alg": "ed25519",
"signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
"created_at": "2026-01-07T16:10:10Z",
"signer": {
"name": "Wikidata Seed Demo Publisher",
"authority_channel": "authority:wikidata-seed-demo"
}
}
],
"extensions": {
"example_purpose": "Demonstrates a Kristal v5 reference Exchange compiled from a Wikidata seed Structured Epistemic State.",
"source_namespace": "wikidata",
"source_mode": "full_statements",
"assertion_status_summary": {
"counts_by_assertion_status": {
"validated": 3,
"sourced": 1,
"disputed": 0,
"rejected": 0,
"revoked": 0
}
},
"query_contract": {
"contract_id": "kristal-query-core@1",
"supports_pagination": true,
"supports_cardinality_estimates": false,
"supported_filters": [
"artifact_status",
"assertion_status",
"validation_status",
"certainty_level",
"validated_as",
"authority_channel",
"recognition_status",
"scope.domain",
"scope.subdomain",
"reader_policy"
],
"supported_reader_modes": [
"reference_only",
"validated_only",
"research",
"all_with_labels"
],
"supported_ordering": [
"SPO",
"POS"
]
},
"publisher": {
"authority_channel_id": "authority:wikidata-seed-demo",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=5617c713d86c:351-373
start=351
end=373
----
"key_id": "wikidata-seed-demo-ed25519-2026-01",
"name": "Wikidata Seed Demo Publisher"
},
"integrity": {
"hash_alg": "sha256",
"manifest_hash": {
"alg": "sha256",
"value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"hash_target_policy": {
"exclude_fields": [
"manifest_id",
"kristal_id",
"content_hash",
"extensions.integrity",
"signatures"
],
"notes": "IDs, content hashes, integrity envelopes, and signatures are excluded from their own hash targets. This integrity envelope is stored under extensions because it is not a top-level field in exchange-manifest.schema.json."
}
},
"notes": "This example preserves scoped validation, authority recognition, certainty summaries, reader policy references, deterministic build metadata, and implementation-specific query/runtime policy details under extensions."
}
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/independent-research-evidence-bundle.example.json"
id=2b41f7fb1cb8
kind=source
size=27670
lines=959
line_ref=1-959
chunks=3
chunk_refs=1-350,351-700,701-959
summary="Source file."

--- CHUNK BEGIN ---
id=2b41f7fb1cb8:1-350
start=1
end=350
----
{
"schema_version": "5.0",
"artifact_type": "structured_epistemic_state",
"state_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"artifact_status": "working",
"created_at": "2026-06-12T00:00:00Z",
"created_by": {
"agent_id": "agent:independent-researcher-example",
"name": "Independent Researcher",
"agent_type": "individual",
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
"canonicalization_profile": "kristal.v5:jcs-rfc8785",
"canonicalization_version": "1",
"content_hash": {
"alg": "sha256",
"value": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
},
"hash_target_policy": {
"exclude_fields": [
"state_id",
"content_hash",
"signatures"
],
"notes": "The content_hash is computed over the deterministic canonical serialization of the unsigned Structured Epistemic State, excluding state_id, content_hash, and signatures."
},
"scope": {
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
},
"source_refs": [
{
"source_id": "source:prototype-report",
"source_type": "document",
"source_url": "https://example.org/research/prototype-test-report",
"title": "Prototype Test Report for Low-Energy Atmospheric Particulate Capture",
"publisher": "Independent Researcher",
"retrieved_at": "2026-05-20T00:00:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
},
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
{
"source_id": "source:lab-measurements",
"source_type": "dataset",
"source_url": "https://example.org/research/prototype-measurements",
"title": "Prototype Measurement Dataset",
"publisher": "Independent Researcher",
"retrieved_at": "2026-05-21T00:00:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
},
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
{
"source_id": "source:initial-review-notes",
"source_type": "document",
"source_url": "https://example.org/research/initial-review-notes",
"title": "Initial Research Review Notes",
"publisher": "Example Environmental Review Group",
"retrieved_at": "2026-05-25T00:00:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "abababababababababababababababababababababababababababababababab"
},
"authority_channel": {
"authority_channel_id": "authority:example-environmental-review-group",
"name": "Example Environmental Review Group"
}
}
],
"derived_from": [],
"merged_from": [],
"supersedes": [],
"assertions": [
{
"assertion_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"source_assertion_id": "research-claim-0001",
"statement": {
"subject": {
"external_id": "prototype:low-energy-particulate-capture-device",
"label": "Low-energy atmospheric particulate capture prototype",
"description": "Research prototype submitted by an independent researcher",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
"predicate": {
"external_id": "predicate:has_claimed_function",
"label": "has claimed function",
"language": "en"
},
"object": {
"kind": "string",
"value": "captures airborne particulate matter using a low-energy electrostatic process"
},
"qualifiers": [
{
"predicate": {
"external_id": "predicate:claim_mode",
"label": "claim mode",
"language": "en"
},
"object": {
"kind": "string",
"value": "research submission"
},
"scope": {
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
}
}
],
"rank": "normal",
"statement_hash": {
"alg": "sha256",
"value": "0101010101010101010101010101010101010101010101010101010101010101"
}
},
"natural_language_statement": {
"text": "The prototype is claimed to capture airborne particulate matter using a low-energy electrostatic process.",
"lang": "en"
},
"assertion_status": "claimed",
"certainty_level": "medium",
"validated_as": "claim",
"scope": {
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
},
"evidence_refs": [
{
"evidence_id": "evidence:prototype-video",
"source_ref": {
"source_id": "source:prototype-report",
"source_type": "document",
"source_url": "https://example.org/research/prototype-test-report",
"title": "Prototype Test Report for Low-Energy Atmospheric Particulate Capture",
"publisher": "Independent Researcher",
"retrieved_at": "2026-05-20T00:00:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
},
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
"quote": "Demonstration evidence shows the prototype operating during a controlled example run.",
"section": "Prototype demonstration",
"evidence_status": "provided",
"content_hash": {
"alg": "sha256",
"value": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
}
},
{
"evidence_id": "evidence:lab-measurements",
"source_ref": {
"source_id": "source:lab-measurements",
"source_type": "dataset",
"source_url": "https://example.org/research/prototype-measurements",
"title": "Prototype Measurement Dataset",
"publisher": "Independent Researcher",
"retrieved_at": "2026-05-21T00:00:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
},
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
"quote": "Measurements were produced by the submitter and require independent replication.",
"section": "Measurement summary",
"evidence_status": "provided",
"content_hash": {
"alg": "sha256",
"value": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
}
}
],
"provenance_refs": [
{
"artifact_id": "source:prototype-report",
"artifact_type": "document",
"content_hash": {
"alg": "sha256",
"value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
},
"created_at": "2026-05-20T00:00:00Z"
}
],
"authority_recognition_refs": [],
"validation": {
"validation_status": "not_evaluated",
"validated_as": "claim",
"certainty_level": "medium",
"scope": {
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
},
"reason_codes": [
"provenance_sufficient"
],
"notes": "Claim is structured and supported by submitter-provided materials, but has not been independently validated."
},
"uncertainty": {
"confidence": 0.55,
"method": "research_submission_precheck",
"notes": "Medium confidence as a research claim; not recognized as a reference fact."
},
"lineage": {
"source_artifacts": [
{
"artifact_id": "source:prototype-report",
"artifact_type": "document",
"content_hash": {
"alg": "sha256",
"value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
}
],
"transforms": [
{
"transform_id": "transform:manual-research-structuring",
"transform_type": "manual_edit",
"tool": "kristal-example-editor",
"policy_ref": {
"policy_id": "kristal.v5:research-submission-policy",
"policy_version": "1"
},
"created_at": "2026-06-12T00:00:00Z",
"notes": "Manual structuring of a submitter-provided research claim."
}
]
},
"conflicts_with": [],
"supersedes": [],
"notes": "This assertion may be rendered in research mode with labels."
},
{
"assertion_id": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
"source_assertion_id": "research-claim-0002",
"statement": {
"subject": {
"external_id": "prototype:low-energy-particulate-capture-device",
"label": "Low-energy atmospheric particulate capture prototype",
"description": "Research prototype submitted by an independent researcher",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
"predicate": {
"external_id": "predicate:measured_particulate_reduction_percent",
"label": "measured particulate reduction percent",
"language": "en"
},
"object": {
"kind": "quantity",
"value": {
"amount": 37.4,
"unit_label": "percent"
},
"normalized": {
"value": 37.4,
"unit_label": "percent",
"precision": "one decimal place",
"notes": "Reported by the submitter from a sealed-room test chamber run."
}
},
"qualifiers": [
{
"predicate": {
"external_id": "predicate:test_condition",
"label": "test condition",
"language": "en"
},
"object": {
"kind": "string",
"value": "sealed-room test chamber, 45-minute run, initial PM2.5 concentration above local baseline"
},
"scope": {
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
}
}
],
"rank": "normal",
"statement_hash": {
"alg": "sha256",
"value": "0202020202020202020202020202020202020202020202020202020202020202"
}
},
"natural_language_statement": {
"text": "The submitter reports a 37.4 percent particulate reduction in a sealed-room test chamber run.",
"lang": "en"
},
"assertion_status": "sourced",
"certainty_level": "medium",
"validated_as": "sourced_claim",
"scope": {
--- CHUNK END ---

--- CHUNK BEGIN ---
id=2b41f7fb1cb8:351-700
start=351
end=700
----
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
},
"evidence_refs": [
{
"evidence_id": "evidence:lab-measurements",
"source_ref": {
"source_id": "source:lab-measurements",
"source_type": "dataset",
"source_url": "https://example.org/research/prototype-measurements",
"title": "Prototype Measurement Dataset",
"publisher": "Independent Researcher",
"retrieved_at": "2026-05-21T00:00:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
},
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
"quote": "The submitted measurement summary reports a 37.4 percent reduction during the test run.",
"section": "Measurement summary",
"evidence_status": "provided",
"content_hash": {
"alg": "sha256",
"value": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
}
},
{
"evidence_id": "evidence:instrument-calibration",
"source_ref": {
"source_id": "source:instrument-calibration",
"source_type": "document",
"source_url": "https://example.org/research/sensor-calibration",
"title": "Sensor Calibration Record",
"publisher": "Independent Researcher",
"retrieved_at": "2026-05-17T09:00:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
},
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
"quote": "Calibration record for the measurement instrument used in the test.",
"section": "Calibration summary",
"evidence_status": "provided",
"content_hash": {
"alg": "sha256",
"value": "f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0"
}
}
],
"provenance_refs": [
{
"artifact_id": "source:lab-measurements",
"artifact_type": "dataset",
"content_hash": {
"alg": "sha256",
"value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
},
"created_at": "2026-05-21T00:00:00Z"
}
],
"authority_recognition_refs": [],
"validation": {
"validation_status": "not_evaluated",
"validated_as": "sourced_claim",
"certainty_level": "medium",
"scope": {
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
},
"reason_codes": [
"provenance_sufficient",
"evidence_sufficient",
"certainty_too_low_for_policy"
],
"notes": "Submitter-provided measurement evidence is present, but independent replication is required before high-confidence recognition."
},
"uncertainty": {
"confidence": 0.62,
"method": "research_submission_precheck",
"notes": "Medium confidence as a sourced research claim; not authority-recognized as a high-confidence fact."
},
"lineage": {
"source_artifacts": [
{
"artifact_id": "source:lab-measurements",
"artifact_type": "dataset",
"content_hash": {
"alg": "sha256",
"value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
}
}
],
"transforms": [
{
"transform_id": "transform:measurement-summary",
"transform_type": "extraction",
"tool": "kristal-example-editor",
"policy_ref": {
"policy_id": "kristal.v5:research-evidence-policy",
"policy_version": "1"
},
"created_at": "2026-06-12T00:00:00Z",
"notes": "Structured measurement summary from the submitted dataset."
}
]
},
"conflicts_with": [],
"supersedes": [],
"notes": "This assertion should not be rendered as established fact until independent replication is recorded."
},
{
"assertion_id": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
"source_assertion_id": "research-claim-0003",
"statement": {
"subject": {
"external_id": "prototype:low-energy-particulate-capture-device",
"label": "Low-energy atmospheric particulate capture prototype",
"description": "Research prototype submitted by an independent researcher",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
"predicate": {
"external_id": "predicate:requires_independent_replication",
"label": "requires independent replication",
"language": "en"
},
"object": {
"kind": "boolean",
"value": true
},
"qualifiers": [],
"rank": "preferred",
"statement_hash": {
"alg": "sha256",
"value": "0303030303030303030303030303030303030303030303030303030303030303"
}
},
"natural_language_statement": {
"text": "Independent replication is required before the performance claim can be recognized as a high-confidence fact.",
"lang": "en"
},
"assertion_status": "reviewed",
"certainty_level": "high",
"validated_as": "reviewed_claim",
"scope": {
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
},
"evidence_refs": [
{
"evidence_id": "evidence:review-notes",
"source_ref": {
"source_id": "source:initial-review-notes",
"source_type": "document",
"source_url": "https://example.org/research/initial-review-notes",
"title": "Initial Research Review Notes",
"publisher": "Example Environmental Review Group",
"retrieved_at": "2026-05-25T00:00:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "abababababababababababababababababababababababababababababababab"
},
"authority_channel": {
"authority_channel_id": "authority:example-environmental-review-group",
"name": "Example Environmental Review Group"
}
},
"quote": "The bundle is structurally reviewable. Performance claims require independent replication and domain authority review.",
"section": "Initial review summary",
"evidence_status": "sufficient",
"content_hash": {
"alg": "sha256",
"value": "abababababababababababababababababababababababababababababababab"
}
}
],
"provenance_refs": [
{
"artifact_id": "source:initial-review-notes",
"artifact_type": "document",
"content_hash": {
"alg": "sha256",
"value": "abababababababababababababababababababababababababababababababab"
},
"created_at": "2026-05-25T00:00:00Z"
}
],
"authority_recognition_refs": [
{
"recognition_id": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
"recognition_status": "under_review",
"recognized_as": "reviewed_claim",
"authority_channel": {
"authority_channel_id": "authority:example-environmental-review-group",
"name": "Example Environmental Review Group"
},
"scope": {
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:research-review-policy",
"policy_version": "1"
}
}
],
"validation": {
"validation_status": "in_review",
"validated_as": "reviewed_claim",
"certainty_level": "high",
"scope": {
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
},
"reason_codes": [
"provenance_sufficient",
"evidence_sufficient",
"certainty_too_low_for_policy"
],
"validation_refs": [
{
"artifact_id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
"artifact_type": "validation_report",
"content_hash": {
"alg": "sha256",
"value": "5656565656565656565656565656565656565656565656565656565656565656"
}
}
],
"notes": "Initial methodology precheck is complete; independent replication is still required."
},
"uncertainty": {
"confidence": 0.85,
"method": "review_precheck",
"notes": "High confidence that independent replication is required before reference recognition."
},
"lineage": {
"source_artifacts": [
{
"artifact_id": "source:initial-review-notes",
"artifact_type": "document",
"content_hash": {
"alg": "sha256",
"value": "abababababababababababababababababababababababababababababababab"
}
}
],
"transforms": [
{
"transform_id": "transform:review-summary",
"transform_type": "review",
"tool": "kristal-example-review-tool",
"policy_ref": {
"policy_id": "kristal.v5:research-review-policy",
"policy_version": "1"
},
"created_at": "2026-06-12T00:00:00Z",
"notes": "Review summary converted into an explicit reviewed assertion."
}
]
},
"conflicts_with": [],
"supersedes": [],
"notes": "This assertion is a review-status assertion, not a validation of the prototype's performance claim."
}
],
"provenance": [
{
"provenance_id": "provenance:submission",
"event_type": "created",
"created_at": "2026-05-22T00:05:00Z",
"agent": {
"agent_id": "agent:independent-researcher-example",
"name": "Independent Researcher",
"agent_type": "individual",
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
"source_ref": {
"source_id": "source:prototype-report",
"source_type": "document",
"source_url": "https://example.org/research/prototype-test-report",
"title": "Prototype Test Report for Low-Energy Atmospheric Particulate Capture",
"publisher": "Independent Researcher",
"retrieved_at": "2026-05-20T00:00:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
},
"authority_channel": {
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
}
},
"policy_refs": [
{
"policy_id": "kristal.v5:research-submission-policy",
"policy_version": "1"
}
],
"notes": "Independent researcher submitted the initial research bundle for structured review."
},
{
"provenance_id": "provenance:review-precheck",
"event_type": "reviewed",
"created_at": "2026-05-25T00:00:00Z",
"agent": {
"agent_id": "agent:example-environmental-review-group",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=2b41f7fb1cb8:701-959
start=701
end=959
----
"name": "Example Environmental Review Group",
"agent_type": "research_collective",
"authority_channel": {
"authority_channel_id": "authority:example-environmental-review-group",
"name": "Example Environmental Review Group"
}
},
"source_ref": {
"source_id": "source:initial-review-notes",
"source_type": "document",
"source_url": "https://example.org/research/initial-review-notes",
"title": "Initial Research Review Notes",
"publisher": "Example Environmental Review Group",
"retrieved_at": "2026-05-25T00:00:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "abababababababababababababababababababababababababababababababab"
},
"authority_channel": {
"authority_channel_id": "authority:example-environmental-review-group",
"name": "Example Environmental Review Group"
}
},
"policy_refs": [
{
"policy_id": "kristal.v5:research-review-policy",
"policy_version": "1"
}
],
"notes": "Initial methodology precheck recorded that the bundle is structurally reviewable but not reference-recognized."
}
],
"review_refs": [
{
"artifact_id": "review:initial-methodology-precheck",
"artifact_type": "review_bundle",
"content_hash": {
"alg": "sha256",
"value": "4545454545454545454545454545454545454545454545454545454545454545"
},
"created_at": "2026-05-25T00:00:00Z"
}
],
"policy_refs": [
{
"policy_id": "kristal.v5:research-submission-policy",
"policy_version": "1"
},
{
"policy_id": "kristal.v5:research-evidence-policy",
"policy_version": "1"
},
{
"policy_id": "kristal.v5:research-review-policy",
"policy_version": "1"
}
],
"authority_recognition_refs": [
{
"recognition_id": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
"recognition_status": "under_review",
"recognized_as": "reviewed_claim",
"authority_channel": {
"authority_channel_id": "authority:example-environmental-review-group",
"name": "Example Environmental Review Group"
},
"scope": {
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:research-review-policy",
"policy_version": "1"
}
}
],
"reader_policy_refs": [
{
"reader_policy_id": "reader_policy:research",
"mode": "research"
},
{
"reader_policy_id": "reader_policy:all-with-labels",
"mode": "all_with_labels"
}
],
"certainty_summary": {
"counts_by_certainty_level": {
"medium": 2,
"high": 1
},
"counts_by_assertion_status": {
"claimed": 1,
"sourced": 1,
"reviewed": 1
},
"counts_by_validated_as": {
"claim": 1,
"sourced_claim": 1,
"reviewed_claim": 1
},
"notes": "The bundle contains research material under review. It is not recognized as reference knowledge."
},
"validation_summary": {
"validation_status": "in_review",
"recognition_status": "under_review",
"authority_channels": [
{
"authority_channel_id": "authority:independent-researcher-example",
"name": "Independent Researcher Example Channel"
},
{
"authority_channel_id": "authority:example-environmental-review-group",
"name": "Example Environmental Review Group"
}
],
"validation_refs": [
{
"artifact_id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
"artifact_type": "validation_report",
"content_hash": {
"alg": "sha256",
"value": "5656565656565656565656565656565656565656565656565656565656565656"
}
}
],
"recognition_refs": [
{
"recognition_id": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
"recognition_status": "under_review",
"recognized_as": "reviewed_claim",
"authority_channel": {
"authority_channel_id": "authority:example-environmental-review-group",
"name": "Example Environmental Review Group"
},
"scope": {
"domain": "research",
"subdomain": "environmental-technology",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "research-review",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:research-review-policy",
"policy_version": "1"
}
}
],
"reason_codes": [
"provenance_sufficient",
"evidence_sufficient",
"certainty_too_low_for_policy"
],
"notes": "This bundle is structured for review. It is not a reference artifact and has not been recognized as a high-confidence factual corpus."
},
"lineage": {
"source_artifacts": [
{
"artifact_id": "source:prototype-report",
"artifact_type": "document",
"content_hash": {
"alg": "sha256",
"value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
},
{
"artifact_id": "source:lab-measurements",
"artifact_type": "dataset",
"content_hash": {
"alg": "sha256",
"value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
}
}
],
"transforms": [
{
"transform_id": "transform:manual-research-structuring",
"transform_type": "manual_edit",
"tool": "kristal-example-editor",
"policy_ref": {
"policy_id": "kristal.v5:research-submission-policy",
"policy_version": "1"
},
"created_at": "2026-06-12T00:00:00Z",
"notes": "Manual research structuring."
},
{
"transform_id": "transform:measurement-summary",
"transform_type": "extraction",
"tool": "kristal-example-editor",
"policy_ref": {
"policy_id": "kristal.v5:research-evidence-policy",
"policy_version": "1"
},
"created_at": "2026-06-12T00:00:00Z",
"notes": "Measurement summary extraction."
}
],
"compiler": {
"agent_id": "agent:kristal-example-compiler",
"name": "kristal-example-compiler",
"agent_type": "system"
},
"policy_refs": [
{
"policy_id": "kristal.v5:research-submission-policy",
"policy_version": "1"
}
]
},
"build": {
"build_id": "build:20260612T000000Z:independent-research-evidence-bundle",
"schema_version": "5.0",
"compile_status": "succeeded",
"validation_status": "in_review",
"review_status": "pending",
"recognition_status": "none",
"publication_status": "not_published",
"activation_status": "not_applicable",
"working_outputs": [],
"reference_outputs": [],
"reason_codes": [
"provenance_sufficient",
"evidence_sufficient",
"certainty_too_low_for_policy"
],
"created_at": "2026-06-12T00:00:00Z"
},
"warnings": [
{
"code": "LOW_CERTAINTY",
"message": "Performance claims are medium-certainty research claims until independent replication is recorded.",
"path": "/assertions/1",
"reason_code": "certainty_too_low_for_policy"
},
{
"code": "UNRECOGNIZED_AUTHORITY",
"message": "The independent researcher channel is the source authority, but the bundle is not yet recognized as reference knowledge by a domain authority.",
"path": "/authority_recognition_refs",
"reason_code": "authority_not_recognized"
}
],
"extensions": {
"example_purpose": "Demonstrates an independent research evidence bundle that is structured, sourced, and under review without being represented as validated reference knowledge.",
"display": {
"recommended_label": "Independent research evidence bundle",
"recommended_warning": "Research material under review. Not authority-recognized as reference knowledge."
}
},
"signatures": []
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/medical-authority-recognition.example.json"
id=bac8452dfd4e
kind=source
size=13945
lines=367
line_ref=1-367
chunks=2
chunk_refs=1-350,351-367
summary="Source file."

--- CHUNK BEGIN ---
id=bac8452dfd4e:1-350
start=1
end=350
----
{
  "schema_version": "5.0",
  "artifact_type": "authority_recognition",
  "recognition_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
  "recognition_status": "recognized",
  "created_at": "2026-01-07T00:00:00Z",
  "expires_at": null,
  "canonicalization_profile": "kristal.v5:jcs-rfc8785",
  "canonicalization_version": "1",
  "content_hash": {
    "alg": "sha256",
    "value": "1111111111111111111111111111111111111111111111111111111111111111"
  },
  "hash_target_policy": {
    "exclude_fields": [
      "recognition_id",
      "content_hash",
      "signatures"
    ],
    "notes": "Content hash is computed over the deterministic JCS serialization excluding recognition_id, content_hash, and signatures."
  },
  "issuer_authority_channel": {
    "authority_channel_id": "authority:unesco-global-reference",
    "name": "UNESCO Global Reference Channel",
    "authority_type": "intergovernmental_organization",
    "authority_registry_ref": {
      "artifact_id": "kristal:authority-registry:sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "artifact_type": "authority_registry",
      "content_hash": {
        "alg": "sha256",
        "value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      }
    }
  },
  "issuer_agent": {
    "name": "UNESCO Global Reference Channel",
    "agent_type": "intergovernmental_organization",
    "authority_channel": {
      "authority_channel_id": "authority:unesco-global-reference",
      "name": "UNESCO Global Reference Channel",
      "authority_type": "intergovernmental_organization"
    }
  },
  "target_level": "authority_channel",
  "target": {
    "authority_channel": {
      "authority_channel_id": "authority:who",
      "name": "World Health Organization",
      "authority_type": "intergovernmental_organization",
      "authority_registry_ref": {
        "artifact_id": "kristal:authority-channel:who",
        "artifact_type": "authority_channel",
        "content_hash": {
          "alg": "sha256",
          "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
        }
      }
    },
    "description": "Recognition of WHO as an authority channel for public-health and clinical-guidance reference material within the declared scope."
  },
  "recognized_as": "institutional_reference",
  "scope": {
    "domain": "health",
    "subdomain": "public-health-and-clinical-guidance",
    "jurisdiction": null,
    "time_window": null,
    "tenant_id": null,
    "environment": "reference",
    "language": "en"
  },
  "validation_policy_ref": {
    "policy_id": "validation-policy:health-authority-recognition",
    "policy_version": "1",
    "policy_ref": {
      "artifact_id": "validation-policy:health-authority-recognition",
      "artifact_type": "validation_policy",
      "content_hash": {
        "alg": "sha256",
        "value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
      }
    }
  },
  "recognition_basis": {
    "basis_type": "institutional_attestation",
    "summary": "Recognition is based on institutional mandate, domain competence, public documentation, global scope, and governance process for public-health and clinical-guidance material.",
    "attestation_refs": [
      {
        "artifact_id": "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
        "artifact_type": "source_document",
        "content_hash": {
          "alg": "sha256",
          "value": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
        }
      },
      {
        "artifact_id": "sha256:9999999999999999999999999999999999999999999999999999999999999999",
        "artifact_type": "source_document",
        "content_hash": {
          "alg": "sha256",
          "value": "9999999999999999999999999999999999999999999999999999999999999999"
        }
      }
    ],
    "policy_refs": [
      {
        "policy_id": "kristal.v5:recognition-policy:health-authority-recognition",
        "policy_version": "1"
      },
      {
        "policy_id": "validation-policy:health-authority-recognition",
        "policy_version": "1"
      }
    ]
  },
  "certainty_level": "high",
  "validation_status": "validated",
  "assertion_status": "validated",
  "delegated_authority_refs": [
    {
      "delegated_authority_channel": {
        "authority_channel_id": "authority:who-affiliated-technical-panel",
        "name": "WHO-affiliated technical panel",
        "authority_type": "research_collective"
      },
      "delegation_scope": {
        "domain": "health",
        "subdomain": "public-health-and-clinical-guidance",
        "jurisdiction": null,
        "time_window": null,
        "tenant_id": null,
        "environment": "reference",
        "language": "en"
      },
      "delegation_status": "conditionally_recognized",
      "delegation_policy_ref": {
        "policy_id": "kristal.v5:delegation-policy:health-technical-panel",
        "policy_version": "1"
      },
      "expires_at": null,
      "notes": "Delegation requires an explicit downstream authority-recognition record."
    }
  ],
  "recognizes_authority_channels": [
    {
      "authority_channel_id": "authority:who",
      "name": "World Health Organization",
      "authority_type": "intergovernmental_organization"
    }
  ],
  "evidence_refs": [
    {
      "evidence_id": "evidence:who-institutional-mandate",
      "source_ref": {
        "source_id": "source:who-institutional-mandate",
        "source_type": "institutional_record",
        "title": "WHO institutional mandate evidence bundle",
        "publisher": "Example evidence registry",
        "retrieved_at": "2026-01-07T00:00:00Z",
        "content_hash": {
          "alg": "sha256",
          "value": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
        },
        "authority_channel": {
          "authority_channel_id": "authority:unesco-global-reference",
          "name": "UNESCO Global Reference Channel",
          "authority_type": "intergovernmental_organization"
        }
      },
      "section": "mandate",
      "evidence_status": "sufficient",
      "content_hash": {
        "alg": "sha256",
        "value": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
      }
    },
    {
      "evidence_id": "evidence:who-guideline-process",
      "source_ref": {
        "source_id": "source:who-guideline-process",
        "source_type": "institutional_record",
        "title": "WHO guideline and expert-review process evidence bundle",
        "publisher": "Example evidence registry",
        "retrieved_at": "2026-01-07T00:00:00Z",
        "content_hash": {
          "alg": "sha256",
          "value": "9999999999999999999999999999999999999999999999999999999999999999"
        },
        "authority_channel": {
          "authority_channel_id": "authority:unesco-global-reference",
          "name": "UNESCO Global Reference Channel",
          "authority_type": "intergovernmental_organization"
        }
      },
      "section": "governance-process",
      "evidence_status": "sufficient",
      "content_hash": {
        "alg": "sha256",
        "value": "9999999999999999999999999999999999999999999999999999999999999999"
      }
    }
  ],
  "provenance_refs": [
    {
      "artifact_id": "kristal:authority-registry:sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "artifact_type": "authority_registry",
      "content_hash": {
        "alg": "sha256",
        "value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      }
    }
  ],
  "review_refs": [
    {
      "artifact_id": "review:health-authority-recognition-2026-01-07",
      "artifact_type": "review_bundle",
      "content_hash": {
        "alg": "sha256",
        "value": "1212121212121212121212121212121212121212121212121212121212121212"
      }
    }
  ],
  "supersedes": [],
  "conflicts_with": [],
  "reason_codes": [
    "authority_recognized",
    "policy_satisfied",
    "provenance_sufficient",
    "evidence_sufficient"
  ],
  "effects": {
    "eligible_for_reference_views": true,
    "eligible_for_validated_only_views": true,
    "eligible_for_high_certainty_views": true,
    "requires_visible_label": true,
    "requires_dispute_label": false,
    "requires_authority_label": true,
    "requires_certainty_label": true,
    "distribution_allowed": true,
    "runtime_activation_allowed": true,
    "reader_policy_effect": "WHO may be treated as a recognized authority channel only for the declared health scope and only when the active reader policy accepts this issuer, validation policy, and recognition status."
  },
  "reader_policy_effect": "Reference, validated-only, and high-certainty views may use this recognition only within the declared health scope. It does not imply universal truth and does not bypass assertion-level validation.",
  "notes": "Recognition applies to the authority channel and does not automatically validate every downstream assertion or artifact.",
  "warnings": [
    {
      "code": "RECOGNITION_SCOPE_NARROW",
      "message": "Recognition is scoped to health/public-health-and-clinical-guidance and does not apply outside that scope.",
      "path": "$.scope",
      "reason_code": "scope_mismatch"
    },
    {
      "code": "AUTHORITY_DELEGATION_USED",
      "message": "Delegated validation is allowed only when represented by explicit downstream authority-recognition records.",
      "path": "$.delegated_authority_refs",
      "reason_code": "authority_recognized"
    }
  ],
  "signatures": [
    {
      "key_id": "ed25519:unesco-global-reference-example-key-01",
      "alg": "ed25519",
      "signature": "base64:ZmFrZV9zaWduYXR1cmVfZm9yX21lZGljYWxfYXV0aG9yaXR5X3JlY29nbml0aW9u",
      "created_at": "2026-01-07T00:00:00Z",
      "authority_channel": {
        "authority_channel_id": "authority:unesco-global-reference",
        "name": "UNESCO Global Reference Channel",
        "authority_type": "intergovernmental_organization"
      }
    }
  ],
  "extensions": {
    "recognition_policy": {
      "policy_id": "kristal.v5:recognition-policy:health-authority-recognition",
      "policy_version": "1",
      "recognition_basis": [
        "institutional_mandate",
        "domain_competence",
        "public_documentation",
        "global_scope",
        "governance_process"
      ],
      "requires_direct_review_of_all_downstream_assertions": false,
      "allows_delegated_validation": true,
      "delegated_validation_scope": {
        "domain": "health",
        "subdomain": "public-health-and-clinical-guidance",
        "jurisdiction": null,
        "time_window": null,
        "tenant_id": null,
        "environment": "reference",
        "language": "en"
      }
    },
    "recognition_effect_detail": {
      "recognized_targets": [
        "authority_channel"
      ],
      "may_validate": [
        "structured_epistemic_state",
        "working_exchange",
        "reference_exchange",
        "exchange_shard",
        "exchange_federation_manifest",
        "runtime_pack"
      ],
      "may_recognize_downstream_artifacts": true,
      "downstream_recognition_requires_policy_match": true,
      "downstream_recognition_is_scoped": true,
      "does_not_imply_universal_truth": true,
      "does_not_bypass_assertion_level_validation": true,
      "does_not_apply_outside_scope": true
    },
    "delegation_rules": {
      "may_delegate_to": [
        "authority:who-affiliated-technical-panel",
        "authority:who-recognized-research-body",
        "authority:national-public-health-agency"
      ],
      "delegation_requires_explicit_record": true,
      "delegation_must_preserve_scope": true,
      "delegation_must_preserve_validation_policy": true,
      "delegation_must_be_revocable": true
    },
    "conditions": [
      {
        "condition_id": "condition:scope-health-only",
        "description": "Recognition applies only to the declared health scope and does not extend to unrelated domains."
      },
      {
        "condition_id": "condition:policy-bound",
        "description": "Downstream Kristals validated by the recognized authority must declare the validation policy used."
      },
      {
        "condition_id": "condition:assertion-status-visible",
        "description": "Downstream assertions must preserve validation status, certainty level, and validated-as classification."
      },
      {
        "condition_id": "condition:revocation-aware",
        "description": "Consumers must check revocation status before treating this recognition as active."
      }
    ],
    "exclusions": [
      {
        "exclusion_id": "exclusion:no-universal-truth",
        "description": "This recognition does not mean every assertion in every downstream health Kristal is universally true."
      },
      {
        "exclusion_id": "exclusion:no-out-of-scope-recognition",
        "description": "This recognition does not apply to domains outside public health and clinical guidance."
      },
--- CHUNK END ---

--- CHUNK BEGIN ---
id=bac8452dfd4e:351-367
start=351
end=367
----
      {
        "exclusion_id": "exclusion:no-silent-authority-transfer",
        "description": "Recognition by the issuer authority channel does not automatically imply recognition by any other authority channel."
      }
    ],
    "validity": {
      "valid_from": "2026-01-07T00:00:00Z",
      "expires_at": null,
      "review_interval": "P1Y",
      "revocable": true
    },
    "compiler": {
      "name": "kristal-authority-recognition-builder",
      "version": "5.0"
    }
  }
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/mythology-corpus-kristal.example.json"
id=7c6be3888293
kind=source
size=27233
lines=725
line_ref=1-725
chunks=3
chunk_refs=1-350,351-700,701-725
summary="Source file."

--- CHUNK BEGIN ---
id=7c6be3888293:1-350
start=1
end=350
----
{
  "schema_version": "5.0",
  "artifact_type": "structured_epistemic_state",
  "state_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
  "artifact_status": "recognized",
  "created_at": "2026-06-12T16:40:00Z",
  "created_by": {
    "agent_id": "agent:hellenic-cultural-archive-example",
    "name": "Hellenic Cultural Archive Example",
    "agent_type": "academic_institution",
    "authority_channel": {
      "authority_channel_id": "authority:hellenic-cultural-archive-example",
      "name": "Hellenic Cultural Archive Example"
    }
  },
  "canonicalization_profile": "kristal.v5:jcs-rfc8785",
  "canonicalization_version": "1",
  "content_hash": {
    "alg": "sha256",
    "value": "2222222222222222222222222222222222222222222222222222222222222222"
  },
  "hash_target_policy": {
    "exclude_fields": ["state_id", "content_hash", "signatures"],
    "notes": "The content_hash is computed over the deterministic canonical serialization of the unsigned Structured Epistemic State, excluding state_id, content_hash, and signatures."
  },
  "scope": {
    "domain": "mythology",
    "subdomain": "greek-mythology",
    "jurisdiction": null,
    "time_window": "classical-antiquity-to-modern-cultural-reference",
    "tenant_id": null,
    "environment": "example",
    "language": "en"
  },
  "source_refs": [
    {
      "source_id": "source:greek-mythology-cultural-corpus-example",
      "source_type": "document",
      "title": "Greek Mythology Cultural Corpus Example",
      "publisher": "Hellenic Cultural Archive Example",
      "retrieved_at": "2026-06-12T16:30:00Z",
      "license": "example-only",
      "content_hash": {
        "alg": "sha256",
        "value": "3333333333333333333333333333333333333333333333333333333333333333"
      },
      "authority_channel": {
        "authority_channel_id": "authority:hellenic-cultural-archive-example",
        "name": "Hellenic Cultural Archive Example"
      }
    },
    {
      "source_id": "source:mythology-reader-policy-example",
      "source_type": "institutional_record",
      "title": "Reader policy guidance for mythology corpora",
      "publisher": "Kristal v5 Example Authority",
      "retrieved_at": "2026-06-12T16:31:00Z",
      "license": "example-only",
      "content_hash": {
        "alg": "sha256",
        "value": "4444444444444444444444444444444444444444444444444444444444444444"
      },
      "authority_channel": {
        "authority_channel_id": "authority:kristal-v5-example",
        "name": "Kristal v5 Example Authority"
      }
    }
  ],
  "derived_from": [],
  "merged_from": [],
  "supersedes": [],
  "assertions": [
    {
      "assertion_id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
      "source_assertion_id": "mythology-claim-0001",
      "statement": {
        "subject": {
          "label": "Zeus",
          "description": "A figure in Greek mythology",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:hellenic-cultural-archive-example",
            "name": "Hellenic Cultural Archive Example"
          }
        },
        "predicate": {
          "label": "is described in mythology as",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:hellenic-cultural-archive-example",
            "name": "Hellenic Cultural Archive Example"
          }
        },
        "object": {
          "kind": "monolingual_text",
          "value": {
            "text": "the ruler of the Olympian gods",
            "lang": "en"
          }
        },
        "qualifiers": [
          {
            "predicate": {
              "label": "epistemic mode",
              "language": "en"
            },
            "object": {
              "kind": "string",
              "value": "mythological corpus"
            },
            "scope": {
              "domain": "mythology",
              "subdomain": "greek-mythology",
              "jurisdiction": null,
              "time_window": "classical-antiquity-to-modern-cultural-reference",
              "tenant_id": null,
              "environment": "example",
              "language": "en"
            },
            "notes": "This qualifier marks the assertion as valid within a mythological corpus, not as a physical-world factual claim."
          }
        ],
        "rank": "normal",
        "statement_hash": {
          "alg": "sha256",
          "value": "6666666666666666666666666666666666666666666666666666666666666666"
        }
      },
      "natural_language_statement": {
        "text": "In Greek mythology, Zeus is described as the ruler of the Olympian gods.",
        "lang": "en"
      },
      "assertion_status": "validated",
      "certainty_level": "not_applicable",
      "validated_as": "mythological_corpus",
      "scope": {
        "domain": "mythology",
        "subdomain": "greek-mythology",
        "jurisdiction": null,
        "time_window": "classical-antiquity-to-modern-cultural-reference",
        "tenant_id": null,
        "environment": "example",
        "language": "en"
      },
      "evidence_refs": [
        {
          "evidence_id": "evidence:greek-mythology-corpus-0001",
          "source_ref": {
            "source_id": "source:greek-mythology-cultural-corpus-example",
            "source_type": "document",
            "title": "Greek Mythology Cultural Corpus Example",
            "publisher": "Hellenic Cultural Archive Example",
            "content_hash": {
              "alg": "sha256",
              "value": "3333333333333333333333333333333333333333333333333333333333333333"
            },
            "authority_channel": {
              "authority_channel_id": "authority:hellenic-cultural-archive-example",
              "name": "Hellenic Cultural Archive Example"
            }
          },
          "quote": "Zeus is presented in this corpus as ruler of the Olympian gods.",
          "section": "Olympian figures",
          "evidence_status": "sufficient",
          "content_hash": {
            "alg": "sha256",
            "value": "7777777777777777777777777777777777777777777777777777777777777777"
          }
        }
      ],
      "provenance_refs": [
        {
          "artifact_id": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
          "artifact_type": "document",
          "content_hash": {
            "alg": "sha256",
            "value": "9999999999999999999999999999999999999999999999999999999999999999"
          },
          "created_at": "2026-06-12T16:25:00Z"
        }
      ],
      "authority_recognition_refs": [
        {
          "recognition_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "recognition_status": "recognized",
          "recognized_as": "mythological_corpus",
          "authority_channel": {
            "authority_channel_id": "authority:hellenic-cultural-archive-example",
            "name": "Hellenic Cultural Archive Example"
          },
          "scope": {
            "domain": "mythology",
            "subdomain": "greek-mythology",
            "jurisdiction": null,
            "time_window": "classical-antiquity-to-modern-cultural-reference",
            "tenant_id": null,
            "environment": "example",
            "language": "en"
          },
          "validation_policy_ref": {
            "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
            "policy_version": "1"
          }
        }
      ],
      "validation": {
        "validation_status": "validated",
        "validated_as": "mythological_corpus",
        "certainty_level": "not_applicable",
        "authority_channel": {
          "authority_channel_id": "authority:hellenic-cultural-archive-example",
          "name": "Hellenic Cultural Archive Example"
        },
        "validation_policy_ref": {
          "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
          "policy_version": "1"
        },
        "scope": {
          "domain": "mythology",
          "subdomain": "greek-mythology",
          "jurisdiction": null,
          "time_window": "classical-antiquity-to-modern-cultural-reference",
          "tenant_id": null,
          "environment": "example",
          "language": "en"
        },
        "reason_codes": ["authority_recognized", "policy_satisfied", "evidence_sufficient"],
        "validation_refs": [],
        "notes": "Validated as a mythological corpus assertion. This does not validate the assertion as a physical-world factual claim."
      },
      "uncertainty": {
        "confidence": 1,
        "method": "scope-based cultural validation",
        "notes": "Certainty about physical-world truth is not applicable. The assertion is validated only as a mythological-corpus statement."
      },
      "lineage": {
        "source_assertions": [],
        "source_artifacts": [
          {
            "artifact_id": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
            "artifact_type": "document",
            "content_hash": {
              "alg": "sha256",
              "value": "9999999999999999999999999999999999999999999999999999999999999999"
            }
          }
        ],
        "transforms": [
          {
            "transform_id": "transform:mythology-import-0001",
            "transform_type": "import",
            "tool": "example-cultural-corpus-importer",
            "policy_ref": {
              "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
              "policy_version": "1"
            },
            "created_at": "2026-06-12T16:35:00Z",
            "notes": "Imported as a mythology-domain assertion with explicit non-physical-world scope."
          }
        ]
      },
      "conflicts_with": [],
      "supersedes": [],
      "notes": "Reader surfaces must not render this claim as physical-world truth."
    },
    {
      "assertion_id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "source_assertion_id": "mythology-claim-0002",
      "statement": {
        "subject": {
          "label": "Poseidon",
          "description": "A figure in Greek mythology",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:hellenic-cultural-archive-example",
            "name": "Hellenic Cultural Archive Example"
          }
        },
        "predicate": {
          "label": "is described in mythology as associated with",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:hellenic-cultural-archive-example",
            "name": "Hellenic Cultural Archive Example"
          }
        },
        "object": {
          "kind": "monolingual_text",
          "value": {
            "text": "the sea, storms, and earthquakes",
            "lang": "en"
          }
        },
        "qualifiers": [
          {
            "predicate": {
              "label": "epistemic mode",
              "language": "en"
            },
            "object": {
              "kind": "string",
              "value": "mythological corpus"
            },
            "scope": {
              "domain": "mythology",
              "subdomain": "greek-mythology",
              "jurisdiction": null,
              "time_window": "classical-antiquity-to-modern-cultural-reference",
              "tenant_id": null,
              "environment": "example",
              "language": "en"
            },
            "notes": "This is a scoped mythology assertion."
          }
        ],
        "rank": "normal",
        "statement_hash": {
          "alg": "sha256",
          "value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
        }
      },
      "natural_language_statement": {
        "text": "In Greek mythology, Poseidon is associated with the sea, storms, and earthquakes.",
        "lang": "en"
      },
      "assertion_status": "validated",
      "certainty_level": "not_applicable",
      "validated_as": "mythological_corpus",
      "scope": {
        "domain": "mythology",
        "subdomain": "greek-mythology",
        "jurisdiction": null,
        "time_window": "classical-antiquity-to-modern-cultural-reference",
        "tenant_id": null,
        "environment": "example",
        "language": "en"
      },
      "evidence_refs": [
        {
          "evidence_id": "evidence:greek-mythology-corpus-0002",
          "source_ref": {
            "source_id": "source:greek-mythology-cultural-corpus-example",
            "source_type": "document",
            "title": "Greek Mythology Cultural Corpus Example",
            "publisher": "Hellenic Cultural Archive Example",
            "content_hash": {
              "alg": "sha256",
              "value": "3333333333333333333333333333333333333333333333333333333333333333"
            },
            "authority_channel": {
--- CHUNK END ---

--- CHUNK BEGIN ---
id=7c6be3888293:351-700
start=351
end=700
----
              "authority_channel_id": "authority:hellenic-cultural-archive-example",
              "name": "Hellenic Cultural Archive Example"
            }
          },
          "quote": "Poseidon is presented in this corpus as associated with the sea, storms, and earthquakes.",
          "section": "Olympian figures",
          "evidence_status": "sufficient",
          "content_hash": {
            "alg": "sha256",
            "value": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
          }
        }
      ],
      "provenance_refs": [
        {
          "artifact_id": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
          "artifact_type": "document",
          "content_hash": {
            "alg": "sha256",
            "value": "9999999999999999999999999999999999999999999999999999999999999999"
          },
          "created_at": "2026-06-12T16:25:00Z"
        }
      ],
      "authority_recognition_refs": [
        {
          "recognition_id": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
          "recognition_status": "recognized",
          "recognized_as": "mythological_corpus",
          "authority_channel": {
            "authority_channel_id": "authority:hellenic-cultural-archive-example",
            "name": "Hellenic Cultural Archive Example"
          },
          "scope": {
            "domain": "mythology",
            "subdomain": "greek-mythology",
            "jurisdiction": null,
            "time_window": "classical-antiquity-to-modern-cultural-reference",
            "tenant_id": null,
            "environment": "example",
            "language": "en"
          },
          "validation_policy_ref": {
            "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
            "policy_version": "1"
          }
        }
      ],
      "validation": {
        "validation_status": "validated",
        "validated_as": "mythological_corpus",
        "certainty_level": "not_applicable",
        "authority_channel": {
          "authority_channel_id": "authority:hellenic-cultural-archive-example",
          "name": "Hellenic Cultural Archive Example"
        },
        "validation_policy_ref": {
          "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
          "policy_version": "1"
        },
        "scope": {
          "domain": "mythology",
          "subdomain": "greek-mythology",
          "jurisdiction": null,
          "time_window": "classical-antiquity-to-modern-cultural-reference",
          "tenant_id": null,
          "environment": "example",
          "language": "en"
        },
        "reason_codes": ["authority_recognized", "policy_satisfied", "evidence_sufficient"],
        "validation_refs": [],
        "notes": "Validated as a mythological corpus assertion. This does not validate the assertion as a physical-world factual claim."
      },
      "uncertainty": {
        "confidence": 1,
        "method": "scope-based cultural validation",
        "notes": "Physical-world certainty is not applicable to this mythology-scope assertion."
      },
      "lineage": {
        "source_assertions": [],
        "source_artifacts": [
          {
            "artifact_id": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
            "artifact_type": "document",
            "content_hash": {
              "alg": "sha256",
              "value": "9999999999999999999999999999999999999999999999999999999999999999"
            }
          }
        ],
        "transforms": [
          {
            "transform_id": "transform:mythology-import-0002",
            "transform_type": "import",
            "tool": "example-cultural-corpus-importer",
            "policy_ref": {
              "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
              "policy_version": "1"
            },
            "created_at": "2026-06-12T16:35:00Z",
            "notes": "Imported as a mythology-domain assertion with explicit cultural scope."
          }
        ]
      },
      "conflicts_with": [],
      "supersedes": [],
      "notes": "This claim is valid as mythology, not as an empirical claim about the physical world."
    }
  ],
  "provenance": [
    {
      "provenance_id": "prov:mythology-corpus-created-0001",
      "event_type": "created",
      "created_at": "2026-06-12T16:35:00Z",
      "agent": {
        "agent_id": "agent:hellenic-cultural-archive-example",
        "name": "Hellenic Cultural Archive Example",
        "agent_type": "academic_institution",
        "authority_channel": {
          "authority_channel_id": "authority:hellenic-cultural-archive-example",
          "name": "Hellenic Cultural Archive Example"
        }
      },
      "source_ref": {
        "source_id": "source:greek-mythology-cultural-corpus-example",
        "source_type": "document",
        "title": "Greek Mythology Cultural Corpus Example",
        "publisher": "Hellenic Cultural Archive Example",
        "content_hash": {
          "alg": "sha256",
          "value": "3333333333333333333333333333333333333333333333333333333333333333"
        },
        "authority_channel": {
          "authority_channel_id": "authority:hellenic-cultural-archive-example",
          "name": "Hellenic Cultural Archive Example"
        }
      },
      "policy_refs": [
        {
          "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
          "policy_version": "1"
        }
      ],
      "notes": "The corpus was created as a mythology-domain Structured Epistemic State."
    },
    {
      "provenance_id": "prov:mythology-corpus-reviewed-0001",
      "event_type": "reviewed",
      "created_at": "2026-06-12T16:38:00Z",
      "agent": {
        "agent_id": "agent:cultural-review-board-example",
        "name": "Cultural Review Board Example",
        "agent_type": "association",
        "authority_channel": {
          "authority_channel_id": "authority:hellenic-cultural-archive-example",
          "name": "Hellenic Cultural Archive Example"
        }
      },
      "artifact_ref": {
        "artifact_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
        "artifact_type": "structured_epistemic_state",
        "content_hash": {
          "alg": "sha256",
          "value": "2222222222222222222222222222222222222222222222222222222222222222"
        },
        "created_at": "2026-06-12T16:40:00Z"
      },
      "policy_refs": [
        {
          "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
          "policy_version": "1"
        }
      ],
      "notes": "Reviewed for cultural-corpus scope and labeling."
    }
  ],
  "review_refs": [
    {
      "artifact_id": "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
      "artifact_type": "review_bundle",
      "content_hash": {
        "alg": "sha256",
        "value": "1212121212121212121212121212121212121212121212121212121212121212"
      },
      "created_at": "2026-06-12T16:38:00Z"
    }
  ],
  "policy_refs": [
    {
      "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
      "policy_version": "1"
    },
    {
      "policy_id": "kristal.v5:reader-policy:mythology-with-labels",
      "policy_version": "1"
    },
    {
      "policy_id": "kristal.v5:reader-policy:reference-only-exclude-mythology",
      "policy_version": "1"
    }
  ],
  "authority_recognition_refs": [
    {
      "recognition_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "recognition_status": "recognized",
      "recognized_as": "mythological_corpus",
      "authority_channel": {
        "authority_channel_id": "authority:hellenic-cultural-archive-example",
        "name": "Hellenic Cultural Archive Example"
      },
      "scope": {
        "domain": "mythology",
        "subdomain": "greek-mythology",
        "jurisdiction": null,
        "time_window": "classical-antiquity-to-modern-cultural-reference",
        "tenant_id": null,
        "environment": "example",
        "language": "en"
      },
      "validation_policy_ref": {
        "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
        "policy_version": "1"
      }
    }
  ],
  "reader_policy_refs": [
    {
      "reader_policy_id": "reader_policy:mythology-with-labels",
      "mode": "all_with_labels"
    },
    {
      "reader_policy_id": "reader_policy:creative",
      "mode": "creative"
    },
    {
      "reader_policy_id": "reader_policy:reference-only-exclude-mythology",
      "mode": "reference_only"
    }
  ],
  "certainty_summary": {
    "counts_by_certainty_level": {
      "not_applicable": 2
    },
    "counts_by_assertion_status": {
      "validated": 2
    },
    "counts_by_validated_as": {
      "mythological_corpus": 2
    },
    "notes": "The corpus is validated as mythology. Physical-world certainty is intentionally not applicable."
  },
  "validation_summary": {
    "validation_status": "validated",
    "recognition_status": "recognized",
    "authority_channels": [
      {
        "authority_channel_id": "authority:hellenic-cultural-archive-example",
        "name": "Hellenic Cultural Archive Example"
      }
    ],
    "validation_refs": [],
    "recognition_refs": [
      {
        "recognition_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "recognition_status": "recognized",
        "recognized_as": "mythological_corpus",
        "authority_channel": {
          "authority_channel_id": "authority:hellenic-cultural-archive-example",
          "name": "Hellenic Cultural Archive Example"
        },
        "scope": {
          "domain": "mythology",
          "subdomain": "greek-mythology",
          "jurisdiction": null,
          "time_window": "classical-antiquity-to-modern-cultural-reference",
          "tenant_id": null,
          "environment": "example",
          "language": "en"
        },
        "validation_policy_ref": {
          "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
          "policy_version": "1"
        }
      }
    ],
    "reason_codes": ["authority_recognized", "policy_satisfied", "evidence_sufficient"],
    "notes": "This Structured Epistemic State is recognized as a mythology corpus. It must not be rendered as a physical-world factual reference."
  },
  "lineage": {
    "source_artifacts": [
      {
        "artifact_id": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
        "artifact_type": "document",
        "content_hash": {
          "alg": "sha256",
          "value": "9999999999999999999999999999999999999999999999999999999999999999"
        },
        "created_at": "2026-06-12T16:25:00Z"
      }
    ],
    "source_states": [],
    "transforms": [
      {
        "transform_id": "transform:mythology-corpus-build-0001",
        "transform_type": "import",
        "tool": "example-cultural-corpus-importer",
        "policy_ref": {
          "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
          "policy_version": "1"
        },
        "created_at": "2026-06-12T16:35:00Z",
        "notes": "Compiled as a Structured Epistemic State for mythology-domain use."
      },
      {
        "transform_id": "transform:mythology-corpus-review-0001",
        "transform_type": "review",
        "tool": "example-cultural-review-workflow",
        "policy_ref": {
          "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
          "policy_version": "1"
        },
        "created_at": "2026-06-12T16:38:00Z",
        "notes": "Reviewed to ensure mythology scope and non-physical-world labels are explicit."
      }
    ],
    "compiler": {
      "agent_id": "agent:example-compiler",
      "name": "Example Compiler",
      "agent_type": "system"
    },
    "policy_refs": [
      {
        "policy_id": "kristal.v5:validation-policy:cultural-corpus-review",
        "policy_version": "1"
      }
    ]
  },
  "build": {
    "build_id": "build:20260612T164000Z:mythology-corpus-example",
    "schema_version": "5.0",
    "compile_status": "succeeded",
    "validation_status": "validated",
    "review_status": "completed",
    "recognition_status": "recognized",
    "publication_status": "not_published",
    "activation_status": "not_applicable",
    "working_outputs": [],
    "reference_outputs": [],
    "reason_codes": ["authority_recognized", "policy_satisfied", "evidence_sufficient"],
    "created_at": "2026-06-12T16:40:00Z"
--- CHUNK END ---

--- CHUNK BEGIN ---
id=7c6be3888293:701-725
start=701
end=725
----
  },
  "warnings": [
    {
      "code": "PROJECTION_REQUIRES_REVIEW",
      "message": "Reader surfaces must preserve the mythology scope and must not render mythology-domain assertions as physical-world factual claims.",
      "path": "/assertions",
      "reason_code": "scope_mismatch"
    }
  ],
  "extensions": {
    "example_purpose": "Demonstrates that a Kristal can be validated as a mythology corpus while explicitly avoiding physical-world truth claims."
  },
  "signatures": [
    {
      "key_id": "hellenic_cultural_archive_example_ed25519_v1",
      "alg": "ed25519",
      "signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
      "created_at": "2026-06-12T16:40:10Z",
      "authority_channel": {
        "authority_channel_id": "authority:hellenic-cultural-archive-example",
        "name": "Hellenic Cultural Archive Example"
      }
    }
  ]
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/plural-authority-federation.example.json"
id=969615b07759
kind=source
size=20560
lines=748
line_ref=1-748
chunks=3
chunk_refs=1-350,351-700,701-748
summary="Source file."

--- CHUNK BEGIN ---
id=969615b07759:1-350
start=1
end=350
----
{
"schema_version": "5.0",
"artifact_type": "exchange_federation_manifest",
"manifest_id": "manifest:plural-authority-federation-example",
"created_at": "2026-03-01T12:00:00Z",
"federation_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000",

"canonicalization_profile": "kristal.v5:jcs-rfc8785",
"canonicalization_version": "1",

"content_hash": {
"alg": "sha256",
"value": "0000000000000000000000000000000000000000000000000000000000000000"
},

"authority_registry_ref": {
"registry_id": "kristal:authority-registry:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"ref": "authority/kristal-v5-demo-authorities.json",
"content_hash": {
"alg": "sha256",
"value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
},

"shards": [
{
"shard_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"scope": {
"domain": "education",
"subdomain": "science-reference",
"jurisdiction": null,
"time_window": null,
"tenant_id": "tenant_demo",
"environment": "dev",
"language": "en"
},
"artifact_status": "reference",
"shard_manifest_ref": "shards/science-earth-shape-reference/exchange-shard-manifest.json",
"shard_manifest_hash": {
"alg": "sha256",
"value": "1111111111111111111111111111111111111111111111111111111111111111"
},
"authority_channel_refs": [
"authority:unesco-science-education"
],
"validation_refs": [
{
"artifact_type": "validation_report",
"id": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
"ref": "validation-reports/science-earth-shape-reference-validation.json",
"content_hash": {
"alg": "sha256",
"value": "2222222222222222222222222222222222222222222222222222222222222222"
}
}
],
"authority_recognition_refs": [
{
"artifact_type": "authority_recognition",
"id": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
"ref": "authority-recognitions/unesco-science-earth-shape-reference.json",
"content_hash": {
"alg": "sha256",
"value": "3333333333333333333333333333333333333333333333333333333333333333"
}
}
],
"extensions": {
"required": true,
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_level": "established",
"validated_as": "high_confidence_fact"
}
},
{
"shard_id": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
"scope": {
"domain": "wikidata",
"subdomain": "seed-reference",
"jurisdiction": null,
"time_window": "2026-03-01T00:00:00Z/2026-03-01T23:59:59Z",
"tenant_id": "tenant_demo",
"environment": "dev",
"language": "en"
},
"artifact_status": "reference",
"shard_manifest_ref": "shards/wikidata-seed-earth-shape/exchange-shard-manifest.json",
"shard_manifest_hash": {
"alg": "sha256",
"value": "4444444444444444444444444444444444444444444444444444444444444444"
},
"authority_channel_refs": [
"authority:wikidata-seed"
],
"validation_refs": [
{
"artifact_type": "validation_report",
"id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
"ref": "validation-reports/wikidata-seed-packaging-validation.json",
"content_hash": {
"alg": "sha256",
"value": "5555555555555555555555555555555555555555555555555555555555555555"
}
}
],
"authority_recognition_refs": [
{
"artifact_type": "authority_recognition",
"id": "sha256:6666666666666666666666666666666666666666666666666666666666666666",
"ref": "authority-recognitions/wikidata-seed-recognition.json",
"content_hash": {
"alg": "sha256",
"value": "6666666666666666666666666666666666666666666666666666666666666666"
}
}
],
"extensions": {
"required": false,
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_level": "medium",
"validated_as": "institutional_reference"
}
},
{
"shard_id": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
"scope": {
"domain": "research",
"subdomain": "earth-observation-notes",
"jurisdiction": null,
"time_window": "2025-01-01T00:00:00Z/2026-03-01T00:00:00Z",
"tenant_id": "tenant_demo",
"environment": "dev",
"language": "en"
},
"artifact_status": "working",
"shard_manifest_ref": "shards/independent-research-earth-observation-notes/exchange-shard-manifest.json",
"shard_manifest_hash": {
"alg": "sha256",
"value": "7777777777777777777777777777777777777777777777777777777777777777"
},
"authority_channel_refs": [
"authority:independent-research-collective"
],
"validation_refs": [],
"authority_recognition_refs": [],
"extensions": {
"required": false,
"validation_status": "in_review",
"recognition_status": "under_review",
"certainty_level": "medium",
"validated_as": "reviewed_claim"
}
},
{
"shard_id": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
"scope": {
"domain": "local_notes",
"subdomain": "divergent-earth-shape-claims",
"jurisdiction": null,
"time_window": null,
"tenant_id": "tenant_demo",
"environment": "dev",
"language": "en"
},
"artifact_status": "working",
"shard_manifest_ref": "shards/local-community-divergent-earth-shape-claims/exchange-shard-manifest.json",
"shard_manifest_hash": {
"alg": "sha256",
"value": "8888888888888888888888888888888888888888888888888888888888888888"
},
"authority_channel_refs": [
"authority:local-community-archive"
],
"validation_refs": [
{
"artifact_type": "validation_report",
"id": "sha256:9999999999999999999999999999999999999999999999999999999999999999",
"ref": "validation-reports/local-community-divergent-position-validation.json",
"content_hash": {
"alg": "sha256",
"value": "9999999999999999999999999999999999999999999999999999999999999999"
}
}
],
"authority_recognition_refs": [
{
"artifact_type": "authority_recognition",
"id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"ref": "authority-recognitions/local-community-divergent-position-recognition.json",
"content_hash": {
"alg": "sha256",
"value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
}
],
"extensions": {
"required": false,
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_level": "low",
"validated_as": "disputed_position"
}
},
{
"shard_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"scope": {
"domain": "mythology",
"subdomain": "cosmology-symbolic-systems",
"jurisdiction": null,
"time_window": null,
"tenant_id": "tenant_demo",
"environment": "dev",
"language": "en"
},
"artifact_status": "reference",
"shard_manifest_ref": "shards/mythological-cosmology-corpus/exchange-shard-manifest.json",
"shard_manifest_hash": {
"alg": "sha256",
"value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
},
"authority_channel_refs": [
"authority:cultural-heritage-archive"
],
"validation_refs": [
{
"artifact_type": "validation_report",
"id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
"ref": "validation-reports/mythological-cosmology-corpus-validation.json",
"content_hash": {
"alg": "sha256",
"value": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
}
}
],
"authority_recognition_refs": [
{
"artifact_type": "authority_recognition",
"id": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"ref": "authority-recognitions/cultural-heritage-mythology-recognition.json",
"content_hash": {
"alg": "sha256",
"value": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
}
}
],
"extensions": {
"required": false,
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_level": "not_applicable",
"validated_as": "mythological_corpus"
}
}
],

"composition_policy": {
"policy_id": "kristal.v5:composition-policy:preserve-disagreement-demo",
"policy_version": "1",
"overlap_strategy": "preserve_all",
"conflict_strategy": "preserve_disagreement",
"default_visibility": "reader_policy",
"ordering": "stable",
"authority_precedence": [
"authority:unesco-science-education",
"authority:wikidata-seed",
"authority:independent-research-collective",
"authority:local-community-archive",
"authority:cultural-heritage-archive"
],
"parameters": {
"stable_order": [
"authority_precedence",
"scope.domain",
"shard_id"
],
"conflict_labels_required": true,
"preserve_source_shard_ids": true,
"preserve_authority_channels": true,
"reader_policy_must_select_visibility": true
}
},

"reader_policy_refs": [
{
"artifact_type": "reader_policy",
"id": "reader_policy:reference-only-science-education",
"ref": "reader-policies/reference-only-science-education.json",
"content_hash": {
"alg": "sha256",
"value": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
}
},
{
"artifact_type": "reader_policy",
"id": "reader_policy:validated-only-with-labels",
"ref": "reader-policies/validated-only-with-labels.json",
"content_hash": {
"alg": "sha256",
"value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
},
{
"artifact_type": "reader_policy",
"id": "reader_policy:research-all-with-labels",
"ref": "reader-policies/research-all-with-labels.json",
"content_hash": {
"alg": "sha256",
"value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
},
{
"artifact_type": "reader_policy",
"id": "reader_policy:creative-and-mythology",
"ref": "reader-policies/creative-and-mythology.json",
"content_hash": {
"alg": "sha256",
"value": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
}
}
],

"authority_recognition_refs": [
{
"artifact_type": "authority_recognition",
"id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
"ref": "authority-recognitions/kristal-reference-ops-federation-recognition.json",
"content_hash": {
"alg": "sha256",
"value": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
}
}
],

"validation_policy_refs": [
{
"artifact_type": "validation_policy",
"id": "kristal.v5:validation-policy:federation-schema-validation",
"ref": "validation-policies/federation-schema-validation.json",
"content_hash": {
"alg": "sha256",
"value": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
}
},
{
"artifact_type": "validation_policy",
"id": "kristal.v5:validation-policy:scientific-reference-review",
"ref": "validation-policies/scientific-reference-review.json",
"content_hash": {
--- CHUNK END ---

--- CHUNK BEGIN ---
id=969615b07759:351-700
start=351
end=700
----
"alg": "sha256",
"value": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
}
},
{
"artifact_type": "validation_policy",
"id": "kristal.v5:validation-policy:heritage-corpus-validation",
"ref": "validation-policies/heritage-corpus-validation.json",
"content_hash": {
"alg": "sha256",
"value": "0000000000000000000000000000000000000000000000000000000000000000"
}
},
{
"artifact_type": "validation_policy",
"id": "kristal.v5:validation-policy:local-community-disputed-position",
"ref": "validation-policies/local-community-disputed-position.json",
"content_hash": {
"alg": "sha256",
"value": "1111111111111111111111111111111111111111111111111111111111111111"
}
}
],

"trust_requirements": [
{
"scope": {
"domain": "education",
"subdomain": "science-reference"
},
"required_authority_channels": [
"authority:unesco-science-education",
"authority:wikidata-seed"
],
"allowed_validation_statuses": [
"validated",
"conditionally_validated"
],
"allowed_certainty_levels": [
"high",
"established"
],
"allowed_validated_as": [
"high_confidence_fact",
"institutional_reference"
],
"include_disputed": false,
"include_fictional": false,
"include_mythological": false
},
{
"scope": {
"domain": "research"
},
"required_authority_channels": [
"authority:independent-research-collective"
],
"allowed_validation_statuses": [
"in_review",
"validated",
"conditionally_validated"
],
"allowed_certainty_levels": [
"low",
"medium",
"high"
],
"allowed_validated_as": [
"hypothesis",
"sourced_claim",
"reviewed_claim"
],
"include_disputed": true,
"include_fictional": false,
"include_mythological": false
},
{
"scope": {
"domain": "mythology"
},
"required_authority_channels": [
"authority:cultural-heritage-archive"
],
"allowed_validation_statuses": [
"validated",
"conditionally_validated"
],
"allowed_certainty_levels": [
"not_applicable"
],
"allowed_validated_as": [
"mythological_corpus",
"symbolic_model"
],
"include_disputed": true,
"include_fictional": false,
"include_mythological": true
}
],

"publisher": {
"authority_channel_id": "authority:kristal-reference-ops",
"key_id": "kristal-reference-ops-ed25519-2026-03",
"name": "Kristal Reference Operations"
},

"signatures": [
{
"sig_id": "sig:plural-authority-federation-example-0001",
"key_id": "kristal-reference-ops-ed25519-2026-03",
"alg": "ed25519",
"payload_hash": {
"alg": "sha256",
"value": "0000000000000000000000000000000000000000000000000000000000000000"
},
"signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
"created_at": "2026-03-01T12:00:10Z",
"purpose": "publisher",
"signer": {
"name": "Kristal Reference Operations",
"org": "Kristal Foundation",
"authority_channel_id": "authority:kristal-reference-ops"
}
}
],

"references": {
"spec_version": "5.0",
"docs_uri": "https://kristal.org/docs/v5/exchange-federation-manifest"
},

"extensions": {
"example_name": "plural-authority-federation",
"example_purpose": "Demonstrates Kristal v5 federation across multiple authority channels, reader policies, certainty levels, and preserved disagreement.",
"producer": {
"kind": "compiler",
"name": "kristal-compiler",
"version": "5.0.0"
},
"build": {
"build_id": "build-2026-03-01T120000Z-plural-authority-federation-0001",
"schema_version": "5.0",
"compiler": {
"name": "kristal-compiler",
"version": "5.0.0",
"git_commit": "b7c8d9e0f1a2b3c4d5e6"
},
"config_hash": {
"alg": "sha256",
"value": "1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e8f9a0"
},
"compile_status": "succeeded",
"review_status": "completed",
"validation_status": "not_evaluated",
"recognition_status": "none",
"publication_status": "not_published",
"activation_status": "not_applicable",
"reason_codes": [
"schema_valid",
"provenance_sufficient",
"conflict_detected",
"disagreement_preserved"
]
},
"federation_scope": {
"domain": "education",
"subdomain": "plural-authority-example",
"jurisdiction": null,
"time_window": "2026-03-01T00:00:00Z/2026-12-31T23:59:59Z",
"tenant_id": "tenant_demo",
"environment": "dev",
"language": "en"
},
"reader_policy_summaries": [
{
"reader_policy_id": "reader_policy:reference-only-science-education",
"mode": "reference_only",
"allowed_authority_channels": [
"authority:unesco-science-education",
"authority:wikidata-seed"
],
"allowed_validation_statuses": [
"validated",
"conditionally_validated"
],
"allowed_certainty_levels": [
"high",
"established"
],
"allowed_validated_as": [
"high_confidence_fact",
"institutional_reference"
],
"include_disputed": false,
"include_fictional": false,
"include_mythological": false,
"show_labels": true,
"fallback_behavior": "show_unavailable"
},
{
"reader_policy_id": "reader_policy:validated-only-with-labels",
"mode": "validated_only",
"allowed_authority_channels": [
"authority:unesco-science-education",
"authority:wikidata-seed",
"authority:local-community-archive",
"authority:cultural-heritage-archive"
],
"allowed_validation_statuses": [
"validated",
"conditionally_validated"
],
"allowed_certainty_levels": [
"low",
"medium",
"high",
"established",
"not_applicable"
],
"allowed_validated_as": [
"high_confidence_fact",
"institutional_reference",
"disputed_position",
"mythological_corpus"
],
"include_disputed": true,
"include_fictional": false,
"include_mythological": true,
"show_labels": true,
"fallback_behavior": "show_unavailable"
},
{
"reader_policy_id": "reader_policy:research-all-with-labels",
"mode": "research",
"allowed_authority_channels": [
"authority:unesco-science-education",
"authority:wikidata-seed",
"authority:independent-research-collective",
"authority:local-community-archive",
"authority:cultural-heritage-archive"
],
"allowed_validation_statuses": [
"not_evaluated",
"in_review",
"validated",
"conditionally_validated",
"disputed",
"rejected"
],
"allowed_certainty_levels": [
"unknown",
"speculative",
"low",
"medium",
"high",
"established",
"not_applicable"
],
"allowed_validated_as": [
"hypothesis",
"claim",
"sourced_claim",
"reviewed_claim",
"high_confidence_fact",
"institutional_reference",
"disputed_position",
"mythological_corpus"
],
"include_disputed": true,
"include_fictional": false,
"include_mythological": true,
"show_labels": true,
"fallback_behavior": "show_unavailable"
},
{
"reader_policy_id": "reader_policy:creative-and-mythology",
"mode": "creative",
"allowed_authority_channels": [
"authority:cultural-heritage-archive"
],
"allowed_validation_statuses": [
"validated",
"conditionally_validated",
"in_review"
],
"allowed_certainty_levels": [
"not_applicable"
],
"allowed_validated_as": [
"mythological_corpus",
"fictional_corpus",
"symbolic_model"
],
"include_disputed": true,
"include_fictional": true,
"include_mythological": true,
"show_labels": true,
"fallback_behavior": "show_unavailable"
}
],
"authority_channels": [
{
"authority_channel_id": "authority:unesco-science-education",
"name": "UNESCO Science Education Reference Channel",
"authority_type": "intergovernmental_organization",
"recognized_by": [
"authority:kristal-reference-ops"
]
},
{
"authority_channel_id": "authority:wikidata-seed",
"name": "Wikidata Seed Kristal Channel",
"authority_type": "community",
"recognized_by": [
"authority:kristal-reference-ops"
]
},
{
"authority_channel_id": "authority:independent-research-collective",
"name": "Independent Research Collective",
"authority_type": "research_collective",
"recognized_by": []
},
{
"authority_channel_id": "authority:local-community-archive",
"name": "Local Community Archive",
"authority_type": "community",
"recognized_by": []
},
{
"authority_channel_id": "authority:cultural-heritage-archive",
"name": "Cultural Heritage Archive",
"authority_type": "academic_institution",
"recognized_by": [
"authority:kristal-reference-ops"
]
}
],
"conflict_summary": {
"conflict_strategy": "preserve_disagreement",
"conflicts_detected": true,
"conflict_count": 1,
"conflicts": [
{
"conflict_id": "conflict:earth-shape-primary-claim",
"target_statement_key": "earth_shape",
"status": "preserved",
"visible_in_reader_policies": [
"reader_policy:validated-only-with-labels",
"reader_policy:research-all-with-labels"
--- CHUNK END ---

--- CHUNK BEGIN ---
id=969615b07759:701-748
start=701
end=748
----
],
"hidden_in_reader_policies": [
"reader_policy:reference-only-science-education"
],
"claims": [
{
"source_shard_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"authority_channel": "authority:unesco-science-education",
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_level": "established",
"validated_as": "high_confidence_fact"
},
{
"source_shard_id": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
"authority_channel": "authority:local-community-archive",
"validation_status": "validated",
"recognition_status": "recognized",
"certainty_level": "low",
"validated_as": "disputed_position"
}
]
}
]
},
"query_contract_ref": {
"id": "kristal.v5:query:triple-pattern@1",
"artifact_type": "query_contract",
"ref": "query-contracts/kristal-v5-triple-pattern-v1.json",
"content_hash": {
"alg": "sha256",
"value": "9999999999999999999999999999999999999999999999999999999999999999"
}
},
"query_capabilities": {
"supports_pagination": true,
"supports_cardinality_estimates": true,
"supports_authority_channel_filter": true,
"supports_validation_status_filter": true,
"supports_certainty_level_filter": true,
"supports_validated_as_filter": true,
"supports_scope_filter": true,
"supports_disagreement_view": true,
"supports_reader_policy_filter": true
},
"notes": "This example intentionally includes a recognized scientific reference shard, a Wikidata seed shard, a research shard, a local divergent-position shard, and a mythological corpus shard. Federation preserves labels and does not silently merge or universalize authority recognition."
}
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/publisher-declared-system-kristal.example.json"
id=e5d011fb9e36
kind=source
size=38766
lines=1012
line_ref=1-1012
chunks=3
chunk_refs=1-350,351-700,701-1012
summary="Source file."

--- CHUNK BEGIN ---
id=e5d011fb9e36:1-350
start=1
end=350
----
{
  "schema_version": "5.0",
  "artifact_type": "structured_epistemic_state",
  "state_id": "sha256:1212121212121212121212121212121212121212121212121212121212121212",
  "artifact_status": "recognized",
  "created_at": "2026-06-12T16:45:00Z",
  "created_by": {
    "agent_id": "agent:examplesoft-systems",
    "name": "ExampleSoft Systems",
    "agent_type": "company",
    "authority_channel": {
      "authority_channel_id": "authority:examplesoft-systems",
      "name": "ExampleSoft Systems"
    }
  },
  "canonicalization_profile": "kristal.v5:jcs-rfc8785",
  "canonicalization_version": "1",
  "content_hash": {
    "alg": "sha256",
    "value": "2323232323232323232323232323232323232323232323232323232323232323"
  },
  "hash_target_policy": {
    "exclude_fields": ["state_id", "content_hash", "signatures"],
    "notes": "The content_hash is computed over the deterministic canonical serialization of the unsigned Structured Epistemic State, excluding state_id, content_hash, and signatures."
  },
  "scope": {
    "domain": "technology",
    "subdomain": "publisher-system-description",
    "jurisdiction": null,
    "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
    "tenant_id": null,
    "environment": "production",
    "language": "en"
  },
  "source_refs": [
    {
      "source_id": "source:examplesoft-system-a-product-manual-2026",
      "source_type": "document",
      "title": "ExampleSoft System A Product Manual",
      "publisher": "ExampleSoft Systems",
      "retrieved_at": "2026-06-12T16:35:00Z",
      "license": "example-only",
      "content_hash": {
        "alg": "sha256",
        "value": "3434343434343434343434343434343434343434343434343434343434343434"
      },
      "authority_channel": {
        "authority_channel_id": "authority:examplesoft-systems",
        "name": "ExampleSoft Systems"
      }
    },
    {
      "source_id": "source:examplesoft-system-a-api-reference-2026",
      "source_type": "document",
      "title": "ExampleSoft System A API Reference",
      "publisher": "ExampleSoft Systems",
      "retrieved_at": "2026-06-12T16:36:00Z",
      "license": "example-only",
      "content_hash": {
        "alg": "sha256",
        "value": "4545454545454545454545454545454545454545454545454545454545454545"
      },
      "authority_channel": {
        "authority_channel_id": "authority:examplesoft-systems",
        "name": "ExampleSoft Systems"
      }
    },
    {
      "source_id": "source:examplesoft-system-a-security-notes-2026",
      "source_type": "document",
      "title": "ExampleSoft System A Security and Deployment Notes",
      "publisher": "ExampleSoft Systems",
      "retrieved_at": "2026-06-12T16:37:00Z",
      "license": "example-only",
      "content_hash": {
        "alg": "sha256",
        "value": "5656565656565656565656565656565656565656565656565656565656565656"
      },
      "authority_channel": {
        "authority_channel_id": "authority:examplesoft-systems",
        "name": "ExampleSoft Systems"
      }
    }
  ],
  "derived_from": [],
  "merged_from": [],
  "supersedes": [],
  "assertions": [
    {
      "assertion_id": "sha256:6767676767676767676767676767676767676767676767676767676767676767",
      "source_assertion_id": "examplesoft-system-a-claim-0001",
      "statement": {
        "subject": {
          "external_id": "vendor:examplesoft:system-a",
          "label": "ExampleSoft System A",
          "description": "Example publisher-declared software system",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:examplesoft-systems",
            "name": "ExampleSoft Systems"
          }
        },
        "predicate": {
          "external_id": "kristal:property:supports_feature",
          "label": "supports feature",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:examplesoft-systems",
            "name": "ExampleSoft Systems"
          }
        },
        "object": {
          "kind": "string",
          "value": "offline query cache"
        },
        "qualifiers": [
          {
            "predicate": {
              "external_id": "kristal:property:declared_by",
              "label": "declared by",
              "language": "en"
            },
            "object": {
              "kind": "string",
              "value": "ExampleSoft Systems"
            },
            "scope": {
              "domain": "technology",
              "subdomain": "publisher-system-description",
              "jurisdiction": null,
              "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
              "tenant_id": null,
              "environment": "production",
              "language": "en"
            },
            "notes": "This is a publisher declaration about the publisher's own system."
          }
        ],
        "rank": "normal",
        "statement_hash": {
          "alg": "sha256",
          "value": "7878787878787878787878787878787878787878787878787878787878787878"
        }
      },
      "natural_language_statement": {
        "text": "ExampleSoft System A supports an offline query cache.",
        "lang": "en"
      },
      "assertion_status": "validated",
      "certainty_level": "not_applicable",
      "validated_as": "publisher_declaration",
      "scope": {
        "domain": "technology",
        "subdomain": "publisher-system-description",
        "jurisdiction": null,
        "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
        "tenant_id": null,
        "environment": "production",
        "language": "en"
      },
      "evidence_refs": [
        {
          "evidence_id": "evidence:examplesoft-manual-offline-query-cache",
          "source_ref": {
            "source_id": "source:examplesoft-system-a-product-manual-2026",
            "source_type": "document",
            "title": "ExampleSoft System A Product Manual",
            "publisher": "ExampleSoft Systems",
            "content_hash": {
              "alg": "sha256",
              "value": "3434343434343434343434343434343434343434343434343434343434343434"
            },
            "authority_channel": {
              "authority_channel_id": "authority:examplesoft-systems",
              "name": "ExampleSoft Systems"
            }
          },
          "quote": "System A includes an offline query cache for local Runtime Pack access.",
          "section": "Runtime behavior",
          "evidence_status": "sufficient",
          "content_hash": {
            "alg": "sha256",
            "value": "8989898989898989898989898989898989898989898989898989898989898989"
          }
        }
      ],
      "provenance_refs": [
        {
          "artifact_id": "sha256:9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a",
          "artifact_type": "publisher_document",
          "content_hash": {
            "alg": "sha256",
            "value": "3434343434343434343434343434343434343434343434343434343434343434"
          },
          "created_at": "2026-06-01T10:00:00Z"
        }
      ],
      "authority_recognition_refs": [
        {
          "recognition_id": "sha256:abababababababababababababababababababababababababababababababab",
          "recognition_status": "recognized",
          "recognized_as": "publisher_declaration",
          "authority_channel": {
            "authority_channel_id": "authority:examplesoft-systems",
            "name": "ExampleSoft Systems"
          },
          "scope": {
            "domain": "technology",
            "subdomain": "publisher-system-description",
            "jurisdiction": null,
            "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
            "tenant_id": null,
            "environment": "production",
            "language": "en"
          },
          "validation_policy_ref": {
            "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
            "policy_version": "1"
          }
        }
      ],
      "validation": {
        "validation_status": "validated",
        "validated_as": "publisher_declaration",
        "certainty_level": "not_applicable",
        "authority_channel": {
          "authority_channel_id": "authority:examplesoft-systems",
          "name": "ExampleSoft Systems"
        },
        "validation_policy_ref": {
          "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
          "policy_version": "1"
        },
        "scope": {
          "domain": "technology",
          "subdomain": "publisher-system-description",
          "jurisdiction": null,
          "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
          "tenant_id": null,
          "environment": "production",
          "language": "en"
        },
        "reason_codes": ["authority_recognized", "provenance_sufficient", "policy_satisfied"],
        "validation_refs": [],
        "notes": "Validated only as a publisher declaration by the publisher authority channel. This does not imply third-party performance, safety, compliance, environmental, or social-impact validation."
      },
      "uncertainty": {
        "confidence": 1,
        "method": "publisher-declared-system-description",
        "notes": "Certainty is not measured as physical-world certainty. The assertion is validated as the publisher's own declaration."
      },
      "lineage": {
        "source_assertions": [],
        "source_artifacts": [
          {
            "artifact_id": "sha256:9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a",
            "artifact_type": "publisher_document",
            "content_hash": {
              "alg": "sha256",
              "value": "3434343434343434343434343434343434343434343434343434343434343434"
            }
          }
        ],
        "transforms": [
          {
            "transform_id": "transform:publisher-system-import-0001",
            "transform_type": "import",
            "tool": "example-publisher-importer",
            "policy_ref": {
              "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
              "policy_version": "1"
            },
            "created_at": "2026-06-12T16:40:00Z",
            "notes": "Imported from the publisher's own documentation."
          }
        ]
      },
      "conflicts_with": [],
      "supersedes": [],
      "notes": "Readers must not render this assertion as independent third-party validation."
    },
    {
      "assertion_id": "sha256:bcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbc",
      "source_assertion_id": "examplesoft-system-a-claim-0002",
      "statement": {
        "subject": {
          "external_id": "vendor:examplesoft:system-a",
          "label": "ExampleSoft System A",
          "description": "Example publisher-declared software system",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:examplesoft-systems",
            "name": "ExampleSoft Systems"
          }
        },
        "predicate": {
          "external_id": "kristal:property:exposes_api_endpoint",
          "label": "exposes API endpoint",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:examplesoft-systems",
            "name": "ExampleSoft Systems"
          }
        },
        "object": {
          "kind": "string",
          "value": "/v1/runtime-packs/{pack_id}/query"
        },
        "qualifiers": [
          {
            "predicate": {
              "external_id": "kristal:property:http_method",
              "label": "HTTP method",
              "language": "en"
            },
            "object": {
              "kind": "string",
              "value": "POST"
            },
            "scope": {
              "domain": "technology",
              "subdomain": "publisher-system-description",
              "jurisdiction": null,
              "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
              "tenant_id": null,
              "environment": "production",
              "language": "en"
            }
          },
          {
            "predicate": {
              "external_id": "kristal:property:api_version",
              "label": "API version",
              "language": "en"
            },
            "object": {
              "kind": "string",
              "value": "v1"
            },
            "scope": {
              "domain": "technology",
              "subdomain": "publisher-system-description",
              "jurisdiction": null,
              "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
              "tenant_id": null,
              "environment": "production",
              "language": "en"
            }
          }
        ],
--- CHUNK END ---

--- CHUNK BEGIN ---
id=e5d011fb9e36:351-700
start=351
end=700
----
        "rank": "normal",
        "statement_hash": {
          "alg": "sha256",
          "value": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd"
        }
      },
      "natural_language_statement": {
        "text": "ExampleSoft System A exposes the API endpoint /v1/runtime-packs/{pack_id}/query using POST.",
        "lang": "en"
      },
      "assertion_status": "validated",
      "certainty_level": "not_applicable",
      "validated_as": "technical_specification",
      "scope": {
        "domain": "technology",
        "subdomain": "publisher-system-description",
        "jurisdiction": null,
        "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
        "tenant_id": null,
        "environment": "production",
        "language": "en"
      },
      "evidence_refs": [
        {
          "evidence_id": "evidence:examplesoft-api-runtime-pack-query-endpoint",
          "source_ref": {
            "source_id": "source:examplesoft-system-a-api-reference-2026",
            "source_type": "document",
            "title": "ExampleSoft System A API Reference",
            "publisher": "ExampleSoft Systems",
            "content_hash": {
              "alg": "sha256",
              "value": "4545454545454545454545454545454545454545454545454545454545454545"
            },
            "authority_channel": {
              "authority_channel_id": "authority:examplesoft-systems",
              "name": "ExampleSoft Systems"
            }
          },
          "quote": "POST /v1/runtime-packs/{pack_id}/query executes a declared local query contract against the referenced Runtime Pack.",
          "section": "Runtime Pack query API",
          "evidence_status": "sufficient",
          "content_hash": {
            "alg": "sha256",
            "value": "dededededededededededededededededededededededededededededededede"
          }
        }
      ],
      "provenance_refs": [
        {
          "artifact_id": "sha256:efefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
          "artifact_type": "publisher_document",
          "content_hash": {
            "alg": "sha256",
            "value": "4545454545454545454545454545454545454545454545454545454545454545"
          },
          "created_at": "2026-06-01T11:00:00Z"
        }
      ],
      "authority_recognition_refs": [
        {
          "recognition_id": "sha256:f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1",
          "recognition_status": "recognized",
          "recognized_as": "technical_specification",
          "authority_channel": {
            "authority_channel_id": "authority:examplesoft-systems",
            "name": "ExampleSoft Systems"
          },
          "scope": {
            "domain": "technology",
            "subdomain": "publisher-system-description",
            "jurisdiction": null,
            "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
            "tenant_id": null,
            "environment": "production",
            "language": "en"
          },
          "validation_policy_ref": {
            "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
            "policy_version": "1"
          }
        }
      ],
      "validation": {
        "validation_status": "validated",
        "validated_as": "technical_specification",
        "certainty_level": "not_applicable",
        "authority_channel": {
          "authority_channel_id": "authority:examplesoft-systems",
          "name": "ExampleSoft Systems"
        },
        "validation_policy_ref": {
          "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
          "policy_version": "1"
        },
        "scope": {
          "domain": "technology",
          "subdomain": "publisher-system-description",
          "jurisdiction": null,
          "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
          "tenant_id": null,
          "environment": "production",
          "language": "en"
        },
        "reason_codes": ["authority_recognized", "provenance_sufficient", "policy_satisfied"],
        "validation_refs": [],
        "notes": "Validated as the publisher's declared technical specification for its own API surface."
      },
      "uncertainty": {
        "confidence": 1,
        "method": "publisher-declared-technical-specification",
        "notes": "Certainty is not a physical-world truth measure. The assertion is validated as the publisher's declared API specification."
      },
      "lineage": {
        "source_assertions": [],
        "source_artifacts": [
          {
            "artifact_id": "sha256:efefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
            "artifact_type": "publisher_document",
            "content_hash": {
              "alg": "sha256",
              "value": "4545454545454545454545454545454545454545454545454545454545454545"
            }
          }
        ],
        "transforms": [
          {
            "transform_id": "transform:publisher-system-import-0002",
            "transform_type": "import",
            "tool": "example-publisher-importer",
            "policy_ref": {
              "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
              "policy_version": "1"
            },
            "created_at": "2026-06-12T16:41:00Z",
            "notes": "Imported from the publisher's own API reference."
          }
        ]
      },
      "conflicts_with": [],
      "supersedes": [],
      "notes": "This assertion describes the publisher-declared API surface. It is not an independent interoperability audit."
    },
    {
      "assertion_id": "sha256:a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2a2",
      "source_assertion_id": "examplesoft-system-a-claim-0003",
      "statement": {
        "subject": {
          "external_id": "vendor:examplesoft:system-a",
          "label": "ExampleSoft System A",
          "description": "Example publisher-declared software system",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:examplesoft-systems",
            "name": "ExampleSoft Systems"
          }
        },
        "predicate": {
          "external_id": "kristal:property:stores_audit_logs_for",
          "label": "stores audit logs for",
          "language": "en",
          "authority_channel": {
            "authority_channel_id": "authority:examplesoft-systems",
            "name": "ExampleSoft Systems"
          }
        },
        "object": {
          "kind": "quantity",
          "value": {
            "amount": 90,
            "unit_label": "days"
          },
          "normalized": {
            "value": 90,
            "unit_label": "days",
            "precision": "integer-day",
            "notes": "Publisher-declared default audit-log retention period."
          }
        },
        "qualifiers": [
          {
            "predicate": {
              "external_id": "kristal:property:configuration_scope",
              "label": "configuration scope",
              "language": "en"
            },
            "object": {
              "kind": "string",
              "value": "default production deployment"
            },
            "scope": {
              "domain": "technology",
              "subdomain": "publisher-system-description",
              "jurisdiction": null,
              "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
              "tenant_id": null,
              "environment": "production",
              "language": "en"
            }
          }
        ],
        "rank": "normal",
        "statement_hash": {
          "alg": "sha256",
          "value": "b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3b3"
        }
      },
      "natural_language_statement": {
        "text": "ExampleSoft System A stores audit logs for 90 days in its default production deployment.",
        "lang": "en"
      },
      "assertion_status": "validated",
      "certainty_level": "not_applicable",
      "validated_as": "publisher_declaration",
      "scope": {
        "domain": "technology",
        "subdomain": "publisher-system-description",
        "jurisdiction": null,
        "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
        "tenant_id": null,
        "environment": "production",
        "language": "en"
      },
      "evidence_refs": [
        {
          "evidence_id": "evidence:examplesoft-audit-log-retention",
          "source_ref": {
            "source_id": "source:examplesoft-system-a-security-notes-2026",
            "source_type": "document",
            "title": "ExampleSoft System A Security and Deployment Notes",
            "publisher": "ExampleSoft Systems",
            "content_hash": {
              "alg": "sha256",
              "value": "5656565656565656565656565656565656565656565656565656565656565656"
            },
            "authority_channel": {
              "authority_channel_id": "authority:examplesoft-systems",
              "name": "ExampleSoft Systems"
            }
          },
          "quote": "The default production deployment stores audit logs for 90 days unless a tenant-specific policy overrides the default.",
          "section": "Audit and retention",
          "evidence_status": "sufficient",
          "content_hash": {
            "alg": "sha256",
            "value": "c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4c4"
          }
        }
      ],
      "provenance_refs": [
        {
          "artifact_id": "sha256:d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5",
          "artifact_type": "publisher_document",
          "content_hash": {
            "alg": "sha256",
            "value": "5656565656565656565656565656565656565656565656565656565656565656"
          },
          "created_at": "2026-06-01T12:00:00Z"
        }
      ],
      "authority_recognition_refs": [
        {
          "recognition_id": "sha256:e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6e6",
          "recognition_status": "recognized",
          "recognized_as": "publisher_declaration",
          "authority_channel": {
            "authority_channel_id": "authority:examplesoft-systems",
            "name": "ExampleSoft Systems"
          },
          "scope": {
            "domain": "technology",
            "subdomain": "publisher-system-description",
            "jurisdiction": null,
            "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
            "tenant_id": null,
            "environment": "production",
            "language": "en"
          },
          "validation_policy_ref": {
            "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
            "policy_version": "1"
          }
        }
      ],
      "validation": {
        "validation_status": "validated",
        "validated_as": "publisher_declaration",
        "certainty_level": "not_applicable",
        "authority_channel": {
          "authority_channel_id": "authority:examplesoft-systems",
          "name": "ExampleSoft Systems"
        },
        "validation_policy_ref": {
          "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
          "policy_version": "1"
        },
        "scope": {
          "domain": "technology",
          "subdomain": "publisher-system-description",
          "jurisdiction": null,
          "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
          "tenant_id": null,
          "environment": "production",
          "language": "en"
        },
        "reason_codes": ["authority_recognized", "provenance_sufficient", "policy_satisfied"],
        "validation_refs": [],
        "notes": "Validated as the publisher's declared default behavior. Tenant-specific deployments may override this value."
      },
      "uncertainty": {
        "confidence": 1,
        "method": "publisher-declared-system-description",
        "notes": "This is a declared default configuration, not a third-party audit of deployed tenant behavior."
      },
      "lineage": {
        "source_assertions": [],
        "source_artifacts": [
          {
            "artifact_id": "sha256:d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5",
            "artifact_type": "publisher_document",
            "content_hash": {
              "alg": "sha256",
              "value": "5656565656565656565656565656565656565656565656565656565656565656"
            }
          }
        ],
        "transforms": [
          {
            "transform_id": "transform:publisher-system-import-0003",
            "transform_type": "import",
            "tool": "example-publisher-importer",
            "policy_ref": {
              "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
              "policy_version": "1"
            },
            "created_at": "2026-06-12T16:42:00Z",
            "notes": "Imported from the publisher's own security and deployment notes."
          }
        ]
      },
      "conflicts_with": [],
      "supersedes": [],
      "notes": "Readers should preserve that this is a publisher-declared default configuration."
    }
  ],
  "provenance": [
    {
      "provenance_id": "prov:examplesoft-system-state-created-0001",
      "event_type": "created",
      "created_at": "2026-06-12T16:45:00Z",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=e5d011fb9e36:701-1012
start=701
end=1012
----
      "agent": {
        "agent_id": "agent:examplesoft-systems",
        "name": "ExampleSoft Systems",
        "agent_type": "company",
        "authority_channel": {
          "authority_channel_id": "authority:examplesoft-systems",
          "name": "ExampleSoft Systems"
        }
      },
      "source_ref": {
        "source_id": "source:examplesoft-system-a-product-manual-2026",
        "source_type": "document",
        "title": "ExampleSoft System A Product Manual",
        "publisher": "ExampleSoft Systems",
        "content_hash": {
          "alg": "sha256",
          "value": "3434343434343434343434343434343434343434343434343434343434343434"
        },
        "authority_channel": {
          "authority_channel_id": "authority:examplesoft-systems",
          "name": "ExampleSoft Systems"
        }
      },
      "policy_refs": [
        {
          "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
          "policy_version": "1"
        }
      ],
      "notes": "Created from publisher-owned system documentation."
    },
    {
      "provenance_id": "prov:examplesoft-api-reference-imported-0001",
      "event_type": "imported",
      "created_at": "2026-06-12T16:46:00Z",
      "agent": {
        "agent_id": "agent:example-publisher-importer",
        "name": "Example Publisher Importer",
        "agent_type": "system"
      },
      "source_ref": {
        "source_id": "source:examplesoft-system-a-api-reference-2026",
        "source_type": "document",
        "title": "ExampleSoft System A API Reference",
        "publisher": "ExampleSoft Systems",
        "content_hash": {
          "alg": "sha256",
          "value": "4545454545454545454545454545454545454545454545454545454545454545"
        },
        "authority_channel": {
          "authority_channel_id": "authority:examplesoft-systems",
          "name": "ExampleSoft Systems"
        }
      },
      "policy_refs": [
        {
          "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
          "policy_version": "1"
        }
      ],
      "notes": "Imported from publisher-owned API documentation."
    },
    {
      "provenance_id": "prov:examplesoft-security-notes-imported-0001",
      "event_type": "imported",
      "created_at": "2026-06-12T16:47:00Z",
      "agent": {
        "agent_id": "agent:example-publisher-importer",
        "name": "Example Publisher Importer",
        "agent_type": "system"
      },
      "source_ref": {
        "source_id": "source:examplesoft-system-a-security-notes-2026",
        "source_type": "document",
        "title": "ExampleSoft System A Security and Deployment Notes",
        "publisher": "ExampleSoft Systems",
        "content_hash": {
          "alg": "sha256",
          "value": "5656565656565656565656565656565656565656565656565656565656565656"
        },
        "authority_channel": {
          "authority_channel_id": "authority:examplesoft-systems",
          "name": "ExampleSoft Systems"
        }
      },
      "policy_refs": [
        {
          "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
          "policy_version": "1"
        }
      ],
      "notes": "Imported from publisher-owned security notes."
    },
    {
      "provenance_id": "prov:examplesoft-publisher-validation-0001",
      "event_type": "validated",
      "created_at": "2026-06-12T16:48:00Z",
      "agent": {
        "agent_id": "agent:examplesoft-release-office",
        "name": "ExampleSoft Release Office",
        "agent_type": "company",
        "authority_channel": {
          "authority_channel_id": "authority:examplesoft-systems",
          "name": "ExampleSoft Systems"
        }
      },
      "policy_refs": [
        {
          "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
          "policy_version": "1"
        }
      ],
      "notes": "The publisher authority channel validates these assertions only as publisher declarations and technical specifications about its own system."
    }
  ],
  "review_refs": [
    {
      "artifact_id": "sha256:f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7f7",
      "artifact_type": "review_bundle",
      "content_hash": {
        "alg": "sha256",
        "value": "a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8a8"
      },
      "created_at": "2026-06-12T16:49:00Z"
    }
  ],
  "policy_refs": [
    {
      "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
      "policy_version": "1"
    },
    {
      "policy_id": "kristal.v5:reader-policy:publisher-declarations-with-labels",
      "policy_version": "1"
    }
  ],
  "authority_recognition_refs": [
    {
      "recognition_id": "sha256:b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9",
      "recognition_status": "recognized",
      "recognized_as": "publisher_declaration",
      "authority_channel": {
        "authority_channel_id": "authority:examplesoft-systems",
        "name": "ExampleSoft Systems"
      },
      "scope": {
        "domain": "technology",
        "subdomain": "publisher-system-description",
        "jurisdiction": null,
        "time_window": "2026-01-01T00:00:00Z/2026-12-31T23:59:59Z",
        "tenant_id": null,
        "environment": "production",
        "language": "en"
      },
      "validation_policy_ref": {
        "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
        "policy_version": "1"
      }
    }
  ],
  "reader_policy_refs": [
    {
      "reader_policy_id": "reader_policy:publisher-declarations-with-labels",
      "mode": "all_with_labels"
    },
    {
      "reader_policy_id": "reader_policy:validated-only-selected-authorities",
      "mode": "validated_only"
    }
  ],
  "certainty_summary": {
    "counts_by_certainty_level": {
      "not_applicable": 3
    },
    "counts_by_assertion_status": {
      "validated": 3
    },
    "counts_by_validated_as": {
      "publisher_declaration": 2,
      "technical_specification": 1
    },
    "notes": "The assertions are validated as publisher declarations or publisher technical specifications. Physical-world certainty is not the correct metric for these claims."
  },
  "validation_summary": {
    "validation_status": "validated",
    "recognition_status": "recognized",
    "authority_channels": [
      {
        "authority_channel_id": "authority:examplesoft-systems",
        "name": "ExampleSoft Systems"
      }
    ],
    "validation_refs": [],
    "recognition_refs": [
      {
        "recognition_id": "sha256:b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9",
        "recognition_status": "recognized",
        "recognized_as": "publisher_declaration",
        "authority_channel": {
          "authority_channel_id": "authority:examplesoft-systems",
          "name": "ExampleSoft Systems"
        }
      }
    ],
    "reason_codes": ["authority_recognized", "provenance_sufficient", "policy_satisfied"],
    "notes": "This state is recognized only under the publisher's own authority channel. It does not imply external certification, compliance approval, safety validation, environmental validation, or social-impact validation."
  },
  "lineage": {
    "source_artifacts": [
      {
        "artifact_id": "sha256:9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a9a",
        "artifact_type": "publisher_document",
        "content_hash": {
          "alg": "sha256",
          "value": "3434343434343434343434343434343434343434343434343434343434343434"
        },
        "created_at": "2026-06-01T10:00:00Z"
      },
      {
        "artifact_id": "sha256:efefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
        "artifact_type": "publisher_document",
        "content_hash": {
          "alg": "sha256",
          "value": "4545454545454545454545454545454545454545454545454545454545454545"
        },
        "created_at": "2026-06-01T11:00:00Z"
      },
      {
        "artifact_id": "sha256:d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5d5",
        "artifact_type": "publisher_document",
        "content_hash": {
          "alg": "sha256",
          "value": "5656565656565656565656565656565656565656565656565656565656565656"
        },
        "created_at": "2026-06-01T12:00:00Z"
      }
    ],
    "source_states": [],
    "transforms": [
      {
        "transform_id": "transform:publisher-declared-system-state-0001",
        "transform_type": "import",
        "tool": "example-publisher-importer",
        "policy_ref": {
          "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
          "policy_version": "1"
        },
        "created_at": "2026-06-12T16:45:00Z",
        "notes": "Publisher documentation was imported into a Structured Epistemic State with publisher-scoped validation."
      },
      {
        "transform_id": "transform:publisher-declared-system-review-0001",
        "transform_type": "review",
        "tool": "example-review-workflow",
        "policy_ref": {
          "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
          "policy_version": "1"
        },
        "created_at": "2026-06-12T16:49:00Z",
        "notes": "Review confirmed that assertions are labeled as publisher declarations rather than external validation."
      }
    ],
    "compiler": {
      "agent_id": "agent:example-compiler",
      "name": "Example Compiler",
      "agent_type": "system"
    },
    "policy_refs": [
      {
        "policy_id": "kristal.v5:validation-policy:publisher-declared-system-description",
        "policy_version": "1"
      }
    ]
  },
  "build": {
    "build_id": "build:20260612T164500Z:publisher-declared-system-kristal",
    "schema_version": "5.0",
    "compile_status": "succeeded",
    "validation_status": "validated",
    "review_status": "completed",
    "recognition_status": "recognized",
    "publication_status": "not_published",
    "activation_status": "not_applicable",
    "working_outputs": [],
    "reference_outputs": [],
    "reason_codes": ["authority_recognized", "provenance_sufficient", "policy_satisfied"],
    "created_at": "2026-06-12T16:45:00Z"
  },
  "warnings": [
    {
      "code": "UNRECOGNIZED_AUTHORITY",
      "message": "No external regulator, auditor, standards body, or public authority is declared as recognizing these assertions.",
      "path": "/authority_recognition_refs",
      "reason_code": "authority_not_recognized"
    }
  ],
  "extensions": {
    "example_purpose": "Demonstrates a Kristal v5 Structured Epistemic State for a publisher-declared system description. The publisher is authoritative for its own declared system structure, but this example does not imply external certification, safety validation, compliance approval, environmental validation, or social-impact validation."
  },
  "signatures": [
    {
      "key_id": "examplesoft_systems_ed25519_2026_01",
      "alg": "ed25519",
      "signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
      "created_at": "2026-06-12T16:50:00Z",
      "authority_channel": {
        "authority_channel_id": "authority:examplesoft-systems",
        "name": "ExampleSoft Systems"
      }
    }
  ]
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/reader-policy-validated-only.example.json"
id=6862843bf96a
kind=source
size=10032
lines=381
line_ref=1-381
chunks=2
chunk_refs=1-350,351-381
summary="Source file."

--- CHUNK BEGIN ---
id=6862843bf96a:1-350
start=1
end=350
----
{
"schema_version": "5.0",
"artifact_type": "reader_policy",
"reader_policy_id": "reader_policy:validated-only",
"name": "Validated Only",
"description": "A reader policy that exposes only assertions accepted under selected validation policies and authority channels. Validated-only does not mean maximum certainty, universal truth, or universal agreement. It means every visible assertion satisfies this policy's validation, authority, certainty, and scope filters.",
"mode": "validated_only",
"created_at": "2026-06-12T16:22:19Z",
"updated_at": "2026-06-12T16:22:19Z",
"created_by": {
"agent_id": "agent:example-reader-policy-author",
"name": "Example Reader Policy Author",
"agent_type": "system"
},
"issuer_authority_channel": {
"authority_channel_id": "authority:reader-policy-examples",
"name": "Reader Policy Examples"
},
"canonicalization_profile": "kristal.v5:jcs-rfc8785",
"canonicalization_version": "1",
"content_hash": {
"alg": "sha256",
"value": "6262626262626262626262626262626262626262626262626262626262626262"
},
"hash_target_policy": {
"exclude_fields": [
"content_hash",
"signatures"
],
"notes": "The content_hash is computed over the deterministic canonical serialization of the unsigned reader policy, excluding content_hash and signatures."
},
"scope": {
"domain": "general",
"subdomain": "validated-reader-view",
"jurisdiction": null,
"time_window": null,
"tenant_id": null,
"environment": "example",
"language": "en"
},
"policy": {
"allowed_artifact_statuses": [
"recognized",
"reference"
],
"blocked_artifact_statuses": [
"revoked",
"deprecated",
"superseded"
],
"allowed_assertion_statuses": [
"validated"
],
"blocked_assertion_statuses": [
"claimed",
"rejected",
"retracted",
"superseded"
],
"allowed_validation_statuses": [
"validated",
"conditionally_validated"
],
"blocked_validation_statuses": [
"not_evaluated",
"in_review",
"rejected",
"revoked"
],
"allowed_recognition_statuses": [
"recognized",
"conditionally_recognized"
],
"blocked_recognition_statuses": [
"rejected",
"deprecated",
"revoked"
],
"allowed_certainty_levels": [
"low",
"medium",
"high",
"established",
"not_applicable"
],
"blocked_certainty_levels": [
"unknown",
"speculative"
],
"allowed_validated_as": [
"hypothesis",
"sourced_claim",
"reviewed_claim",
"high_confidence_fact",
"institutional_reference",
"publisher_declaration",
"technical_specification",
"legal_or_policy_position",
"mythological_corpus",
"fictional_corpus",
"symbolic_model",
"disputed_position"
],
"blocked_validated_as": [
"claim",
"rejected_claim"
],
"authority_filter": {
"allowed_authority_channels": [
{
"authority_channel_id": "authority:unesco-science-education",
"name": "UNESCO Science Education Example"
},
{
"authority_channel_id": "authority:wikidata-seed",
"name": "Wikidata Seed Example"
},
{
"authority_channel_id": "authority:who",
"name": "WHO Example"
},
{
"authority_channel_id": "authority:local-community-archive",
"name": "Local Community Archive Example"
},
{
"authority_channel_id": "authority:cultural-heritage-archive",
"name": "Cultural Heritage Archive Example"
},
{
"authority_channel_id": "authority:publisher-declared-systems",
"name": "Publisher Declared Systems Example"
},
{
"authority_channel_id": "authority:independent-research-collective",
"name": "Independent Research Collective Example"
}
],
"blocked_authority_channels": [],
"allow_unrecognized_authority_channels": false,
"allow_conditionally_recognized_authorities": true,
"allow_revoked_authorities": false
},
"scope_filter": {
"allowed_domains": [
"general",
"wikidata",
"science",
"health",
"education",
"heritage",
"law",
"policy",
"technology",
"environment",
"culture",
"mythology",
"fiction",
"research",
"operations",
"civic"
],
"blocked_domains": [
"local_notes"
],
"allowed_scopes": [
{
"domain": "general",
"subdomain": "validated-reader-view",
"jurisdiction": null,
"time_window": null,
"tenant_id": null,
"environment": "example",
"language": "en"
}
],
"blocked_scopes": [],
"language_priority": [
"en",
"fr-CA"
],
"jurisdiction_priority": []
},
"include_disputed": true,
"include_rejected": false,
"include_revoked": false,
"include_deprecated": false,
"include_fictional": true,
"include_mythological": true,
"include_symbolic": true,
"include_speculative": false,
"include_unknown_certainty": false,
"require_labels_for_uncertainty": true,
"require_labels_for_dispute": true,
"require_labels_for_scoped_validation": true,
"require_labels_for_authority": true,
"require_traceability": true,
"require_evidence": false,
"require_validation_policy_ref": true,
"require_authority_channel": true,
"custom_rules": [
{
"rule_id": "rule:validated-only-preserve-scope-labels",
"description": "Material with scoped validation must keep authority, scope, certainty, and validated-as labels available to readers.",
"target": "assertion",
"condition": {
"validation_status": [
"validated",
"conditionally_validated"
]
},
"effect": "label",
"label": "validated_with_scope"
},
{
"rule_id": "rule:exclude-rejected-and-revoked",
"description": "Rejected or revoked material is not visible under this policy.",
"target": "assertion",
"condition": {
"validation_status": [
"rejected",
"revoked"
]
},
"effect": "block",
"label": "excluded_rejected_or_revoked"
}
]
},
"fallback_behavior": "show_unavailable",
"rendering": {
"show_labels": true,
"show_authority_channel": true,
"show_certainty_level": true,
"show_validation_status": true,
"show_recognition_status": true,
"show_scope": true,
"show_dispute_status": true,
"show_fictional_or_mythological_mode": true,
"show_trace_summary": true,
"max_summary_length": 800
},
"query": {
"default_limit": 50,
"max_limit": 500,
"default_ordering": "authority_then_certainty",
"allow_cross_scope_queries": false,
"allow_cross_authority_queries": false,
"conflict_behavior": "preserve_disagreement"
},
"federation": {
"allow_federated_sources": true,
"allowed_federations": [],
"blocked_federations": [],
"allow_disagreement": true,
"composition_strategy": "reader_policy_selected"
},
"offline": {
"allow_offline_use": true,
"require_local_integrity_check": true,
"require_signature_check": true,
"allow_stale_packs": false,
"max_staleness_seconds": 86400,
"unavailable_behavior": "show_unavailable"
},
"revocation": {
"exclude_revoked_artifacts": true,
"exclude_revoked_assertions": true,
"exclude_revoked_authority_channels": true,
"exclude_revoked_keys": true,
"show_revocation_labels": true,
"allow_historical_revoked_material": false
},
"lineage": {
"require_lineage": true,
"preserve_source_identity": true,
"show_lineage": true,
"allow_forks": true,
"allow_unrecognized_forks": false
},
"policy_refs": [
{
"policy_id": "kristal.v5:reader-policy:validated-only",
"policy_version": "1"
}
],
"derived_from": [],
"supersedes": [],
"warnings": [
{
"code": "POLICY_HAS_CUSTOM_RULES",
"message": "This example includes custom rules to preserve scoped validation labels and block rejected or revoked material.",
"path": "$.policy.custom_rules"
}
],
"extensions": {
"example_purpose": "Demonstrates a Kristal v5 validated-only reader policy. The policy allows only validated or conditionally validated material, while preserving certainty, authority, scope, fiction, mythology, and disputed-position labels.",
"selection_notes": [
"This policy includes only material with validation_status validated or conditionally_validated.",
"The policy may include low or not_applicable certainty when the assertion is explicitly validated as a hypothesis, fictional corpus, mythological corpus, symbolic model, publisher declaration, technical specification, or disputed position.",
"This policy does not present scoped validation as universal truth.",
"This policy requires labels to remain visible or recoverable so readers know validated as what, by whom, for which scope, and at which certainty level."
],
"examples": {
"allowed": [
{
"assertion_status": "validated",
"validation_status": "validated",
"certainty_level": "established",
"validated_as": "high_confidence_fact",
"authority_channel": "authority:unesco-science-education",
"scope": {
"domain": "science",
"subdomain": "education",
"language": "en"
}
},
{
"assertion_status": "validated",
"validation_status": "validated",
"certainty_level": "not_applicable",
"validated_as": "mythological_corpus",
"authority_channel": "authority:cultural-heritage-archive",
"scope": {
"domain": "mythology",
"subdomain": "cultural-corpus",
"language": "en"
}
},
{
"assertion_status": "validated",
"validation_status": "conditionally_validated",
"certainty_level": "low",
"validated_as": "hypothesis",
"authority_channel": "authority:independent-research-collective",
"scope": {
"domain": "research",
"subdomain": "early-stage-hypothesis",
"language": "en"
}
}
],
"excluded": [
{
"assertion_status": "claimed",
"validation_status": "not_evaluated",
"certainty_level": "medium",
"validated_as": "claim",
"reason": "Not validated under the active policy."
},
--- CHUNK END ---

--- CHUNK BEGIN ---
id=6862843bf96a:351-381
start=351
end=381
----
{
"assertion_status": "rejected",
"validation_status": "rejected",
"certainty_level": "low",
"validated_as": "rejected_claim",
"reason": "Rejected material is excluded by this policy."
},
{
"assertion_status": "validated",
"validation_status": "validated",
"certainty_level": "high",
"validated_as": "high_confidence_fact",
"authority_channel": "authority:unselected-authority",
"reason": "The validating authority channel is not allowed by this policy."
}
]
}
},
"signatures": [
{
"key_id": "example_reader_policy_ed25519_v1",
"alg": "ed25519",
"signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
"created_at": "2026-06-12T16:22:29Z",
"authority_channel": {
"authority_channel_id": "authority:reader-policy-examples",
"name": "Reader Policy Examples"
}
}
]
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/resolved-claim-ir.example.json"
id=bcd3187f29bc
kind=source
size=9945
lines=405
line_ref=1-405
chunks=2
chunk_refs=1-350,351-405
summary="Source file."

--- CHUNK BEGIN ---
id=bcd3187f29bc:1-350
start=1
end=350
----
{
"schema_version": "5.0",
"artifact_type": "resolved_claim_ir",
"profile_role": "extractor_resolution_profile",
"input": {
"claim_ir_ref": {
"artifact_id": "ci-2f5c2a9b-6c6d-4f9f-8caa-31c6a0b1b7d4",
"artifact_type": "claim_ir",
"content_hash": {
"alg": "sha256",
"value": "2f5c2a9b6c6d4f9f8caa31c6a0b1b7d42f5c2a9b6c6d4f9f8caa31c6a0b1b7d4"
}
},
"source_refs": [
{
"source_id": "snap-2026-01-06-wikipedia-dump-en",
"title": "Wikipedia English dump snapshot",
"publisher": "Example snapshot provider",
"retrieved_at": "2026-01-06T09:12:43Z",
"content_hash": {
"alg": "sha256",
"value": "1111111111111111111111111111111111111111111111111111111111111111"
}
},
{
"source_id": "recipe-demo-encyclopedia-core",
"title": "Demo encyclopedia core extraction recipe",
"content_hash": {
"alg": "sha256",
"value": "2222222222222222222222222222222222222222222222222222222222222222"
}
}
],
"notes": "Resolved Claim-IR example derived from a Claim-IR extractor output. Claim-IR is an extractor profile, not the universal Kristal v5 input boundary."
},
"resolution": {
"run_id": "rci-7a2f3df0-3e9b-4e63-9fd3-2f8b9a7d5d5c",
"created_at": "2026-01-07T15:20:00Z",
"resolver": {
"name": "SenTient",
"version": "0.9.0",
"kind": "sentient",
"authority_channel": {
"authority_channel_id": "authority:sentient-demo",
"name": "SenTient Demo Resolver"
},
"model_ref": {
"artifact_id": "sha256:7d3d5b7a2b6f4d6d2c3fbb65d36d7b6c3a2f8f7f8c9a0b1c2d3e4f5a6b7c8d9e",
"artifact_type": "resolver_config"
}
},
"limits": {
"max_candidates": 5
},
"summary": {
"entities_resolved": 2,
"entities_ambiguous": 1,
"entities_unresolved": 0,
"properties_resolved": 2,
"properties_ambiguous": 0,
"properties_unresolved": 0,
"claims_projectable_to_structured_epistemic_state": 1,
"claims_blocked_from_projection": 1,
"warnings": 1,
"errors": 0
},
"notes": "Preserves unresolved ambiguity when candidate confidence does not satisfy the configured acceptance threshold."
},
"scope": {
"domain": "wikidata",
"subdomain": "demo-encyclopedia-core",
"jurisdiction": null,
"time_window": "2026-01",
"tenant_id": "tenant_demo",
"environment": "demo",
"language": "en"
},
"subject": {
"status": "ambiguous",
"surface": "mixed example subjects",
"lang": "en",
"candidates": [
{
"id": "wd:Q42",
"score": 0.997,
"label": "Douglas Adams",
"source": "exact_alias"
},
{
"id": "wd:Q90",
"score": 0.881,
"label": "Paris",
"source": "context_rank"
},
{
"id": "wd:Q207511",
"score": 0.211,
"label": "Paris (mythology)",
"source": "context_rank"
}
]
},
"claims": [
{
"claim_id": "clm-0001",
"assertion_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"source_claim_id": "clm-0001",
"subject": {
"status": "resolved",
"qid": "Q42",
"surface": "Douglas Adams",
"lang": "en",
"candidates": [
{
"id": "wd:Q42",
"score": 0.997,
"label": "Douglas Adams",
"source": "exact_alias"
},
{
"id": "wd:Q214338",
"score": 0.031,
"label": "Douglas Adams (disambiguation)",
"source": "embedding_rank"
}
],
"decision": {
"method": "alias_match",
"score_threshold": 0.92,
"chosen_candidate_index": 0,
"authority_channel": {
"authority_channel_id": "authority:sentient-demo",
"name": "SenTient Demo Resolver"
},
"notes": "Resolved from exact alias and supporting evidence context."
}
},
"predicate": {
"status": "resolved",
"pid": "P569",
"surface": "date of birth",
"lang": "en",
"candidates": [
{
"id": "wd:P569",
"score": 0.995,
"label": "date of birth",
"source": "label_match"
},
{
"id": "wd:P570",
"score": 0.072,
"label": "date of death",
"source": "embedding_rank"
}
],
"decision": {
"method": "exact_match",
"score_threshold": 0.92,
"chosen_candidate_index": 0,
"authority_channel": {
"authority_channel_id": "authority:sentient-demo",
"name": "SenTient Demo Resolver"
}
}
},
"object": {
"kind": "time",
"value": {
"iso8601": "1952-03-11",
"precision": "day",
"calendar": "gregorian",
"timezone": "UTC"
},
"normalized": {
"canonical_value": "1952-03-11",
"precision": "day",
"notes": "Parsed from surface value '11 March 1952'."
}
},
"evidence": [
{
"quote": "Douglas Noel Adams (11 March 1952 – 11 May 2001) was an English author...",
"evidence_status": "provided",
"source": {
"source_id": "source:wikipedia:douglas-adams",
"source_url": "https://en.wikipedia.org/wiki/Douglas_Adams",
"title": "Douglas Adams",
"publisher": "Wikipedia",
"retrieved_at": "2026-01-06T09:12:43Z",
"content_hash": {
"alg": "sha256",
"value": "0b6d7cf44a2e2a8f8356a0a40c6b2d9b4e9d0f7d4c1b2a3f9e8d7c6b5a4f3e2d"
}
}
}
],
"assertion_status": "sourced",
"certainty_level": "high",
"validation": {
"validation_status": "not_evaluated",
"validated_as": "sourced_claim",
"certainty_level": "high",
"scope": {
"domain": "wikidata",
"subdomain": "demo-encyclopedia-core",
"jurisdiction": null,
"time_window": "2026-01",
"tenant_id": "tenant_demo",
"environment": "demo",
"language": "en"
},
"reason_codes": [
"evidence_sufficient"
],
"notes": "Resolved and sourced; validation by an authority channel has not yet been performed."
},
"uncertainty": {
"confidence": 0.98,
"method": "resolver_candidate_score",
"notes": "Object normalization confidence inherited from resolver decision."
},
"projection_status": "projectable",
"notes": "Resolution can be projected into Structured Epistemic State as a sourced claim."
},
{
"claim_id": "clm-0002",
"assertion_id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"source_claim_id": "clm-0002",
"subject": {
"status": "ambiguous",
"surface": "Paris",
"lang": "en",
"candidates": [
{
"id": "wd:Q90",
"score": 0.881,
"label": "Paris",
"source": "context_rank"
},
{
"id": "wd:Q207511",
"score": 0.211,
"label": "Paris (mythology)",
"source": "context_rank"
},
{
"id": "wd:Q191",
"score": 0.144,
"label": "Paris, Texas",
"source": "context_rank"
}
],
"decision": {
"method": "embedding_rank",
"score_threshold": 0.92,
"authority_channel": {
"authority_channel_id": "authority:sentient-demo",
"name": "SenTient Demo Resolver"
},
"notes": "Top candidate did not meet the configured acceptance threshold; ambiguity is preserved."
},
"warnings": [
{
"code": "AMBIGUOUS_SUBJECT",
"message": "Multiple plausible entity matches for 'Paris' given limited context; preserving ambiguity.",
"path": "$.claims[1].subject"
}
]
},
"predicate": {
"status": "resolved",
"pid": "P17",
"surface": "country",
"lang": "en",
"candidates": [
{
"id": "wd:P17",
"score": 0.991,
"label": "country",
"source": "label_match"
}
],
"decision": {
"method": "exact_match",
"score_threshold": 0.92,
"chosen_candidate_index": 0,
"authority_channel": {
"authority_channel_id": "authority:sentient-demo",
"name": "SenTient Demo Resolver"
}
}
},
"object": {
"kind": "item",
"value": {
"status": "resolved",
"qid": "Q142",
"surface": "France",
"lang": "en",
"candidates": [
{
"id": "wd:Q142",
"score": 0.996,
"label": "France",
"source": "exact_alias"
}
],
"decision": {
"method": "alias_match",
"score_threshold": 0.92,
"chosen_candidate_index": 0,
"authority_channel": {
"authority_channel_id": "authority:sentient-demo",
"name": "SenTient Demo Resolver"
}
}
}
},
"evidence": [
{
"quote": "Paris is the capital of France. Paris has many museums.",
"evidence_status": "weak",
"source": {
"source_id": "source:travel-briefing",
"source_url": "https://example.org/notes/travel-briefing.txt",
"title": "Travel briefing notes",
"publisher": "Example notes publisher",
"retrieved_at": "2026-01-06T10:00:00Z",
"content_hash": {
"alg": "sha256",
"value": "c9f5a2a9f3b2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6"
}
}
}
],
"assertion_status": "sourced",
"certainty_level": "medium",
"validation": {
"validation_status": "not_evaluated",
"validated_as": "sourced_claim",
"certainty_level": "medium",
"scope": {
"domain": "wikidata",
"subdomain": "demo-encyclopedia-core",
"jurisdiction": null,
"time_window": "2026-01",
"tenant_id": "tenant_demo",
"environment": "demo",
"language": "en"
--- CHUNK END ---

--- CHUNK BEGIN ---
id=bcd3187f29bc:351-405
start=351
end=405
----
},
"reason_codes": [
"evidence_insufficient"
],
"notes": "Subject ambiguity blocks projection as a resolved factual assertion until review or stronger context is supplied."
},
"uncertainty": {
"confidence": 0.62,
"method": "candidate_margin",
"notes": "Subject candidate score is below acceptance threshold."
},
"projection_status": "requires_review",
"notes": "Ambiguity preserved; may be rendered only with ambiguity labels or reviewed before projection."
}
],
"structured_epistemic_state_projection": {
"target_schema": "https://kristal.org/schemas/v5/structured-epistemic-state.schema.json",
"assertion_refs": [
{
"assertion_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"source_claim_id": "clm-0001",
"claim_id": "clm-0001"
}
],
"projection_policy_ref": {
"artifact_id": "kristal.v5:projection-policy:resolved-claim-ir-to-ses",
"artifact_type": "projection_policy"
},
"notes": "Only projectable resolved claims are included automatically. Ambiguous claims require review."
},
"warnings": [
{
"code": "AMBIGUOUS_SUBJECT",
"message": "Subject entity for clm-0002 could not be uniquely resolved under the active resolver threshold.",
"path": "$.claims[1].subject",
"reason_code": "evidence_insufficient"
},
{
"code": "PROJECTION_REQUIRES_REVIEW",
"message": "clm-0002 is retained but not automatically projected as a resolved assertion.",
"path": "$.claims[1]"
}
],
"errors": [],
"extensions": {
"legacy_v3_artifact_id": "rci-7a2f3df0-3e9b-4e63-9fd3-2f8b9a7d5d5c",
"tenant_id": "tenant_demo",
"build_id": "build-2026-01-07T152000Z-0001",
"legacy_resolver_config": {
"scoring_model": "funnel-v1",
"preserve_ambiguity": true,
"min_confidence_accept": 0.92
}
}
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/revocations.example.json"
id=4d99cd26e183
kind=source
size=3753
lines=123
line_ref=1-123
chunks=0
chunk_refs=
summary="Source file."
----
000001 | {
000002 | "schema_version": "5.0",
000003 | "artifact_type": "revocations",
000004 | "created_at": "2026-02-26T18:55:00Z",
000005 | 
000006 | "revocations_id": "sha256:4d2c1a9b8e7f6051423a1b0c9d8e7f6051423a1b0c9d8e7f6051423a1b0c9d8e",
000007 | "canonicalization_profile": "kristal.v5:jcs-rfc8785",
000008 | "canonicalization_version": "1",
000009 | 
000010 | "issuer_authority_channel": {
000011 | "authority_channel_id": "authority:tenant_123",
000012 | "name": "Tenant 123 Trust Root"
000013 | },
000014 | 
000015 | "content_hash": {
000016 | "alg": "sha256",
000017 | "value": "4d2c1a9b8e7f6051423a1b0c9d8e7f6051423a1b0c9d8e7f6051423a1b0c9d8e"
000018 | },
000019 | 
000020 | "hash_target_policy": {
000021 | "exclude_fields": ["revocations_id", "content_hash", "signatures"],
000022 | "notes": "The content_hash is computed over the deterministic canonical serialization of the unsigned revocation artifact, excluding revocations_id, content_hash, and signatures."
000023 | },
000024 | 
000025 | "scope": {
000026 | "domain": "operations",
000027 | "subdomain": "trust-roots",
000028 | "jurisdiction": null,
000029 | "time_window": null,
000030 | "tenant_id": "tenant_123",
000031 | "environment": "prod",
000032 | "language": "en"
000033 | },
000034 | 
000035 | "revocation_policy_ref": {
000036 | "policy_id": "kristal.v5:revocation-policy:tenant_123-prod",
000037 | "policy_version": "1"
000038 | },
000039 | 
000040 | "entries": [
000041 | {
000042 | "entry_id": "rev-0001",
000043 | "target_level": "key",
000044 | "kind": "key_id",
000045 | "target": {
000046 | "key_id": "tenant_123_root_ed25519_v1"
000047 | },
000048 | "revocation_status": "revoked",
000049 | "revoked_at": "2026-02-20T09:12:03Z",
000050 | "effective_at": "2026-02-20T10:00:00Z",
000051 | "expires_at": null,
000052 | "reason_code": "planned_key_rotation",
000053 | "reason": "Key rotation (planned)",
000054 | "replacement_ref": {
000055 | "key_id": "tenant_123_root_ed25519_v2"
000056 | },
000057 | "effect": {
000058 | "new_signatures_allowed": false,
000059 | "historical_signatures_remain_verifiable": true,
000060 | "reader_policy_effect": "treat_new_artifacts_signed_only_by_this_key_as_untrusted_for_selected_authority_channel"
000061 | },
000062 | "notes": "Replaced by tenant_123_root_ed25519_v2."
000063 | },
000064 | {
000065 | "entry_id": "rev-0002",
000066 | "target_level": "authority_channel",
000067 | "kind": "authority_channel_id",
000068 | "target": {
000069 | "authority_channel_id": "authority:unesco",
000070 | "name": "UNESCO"
000071 | },
000072 | "revocation_status": "conditionally_revoked",
000073 | "revoked_at": "2026-02-22T14:30:00Z",
000074 | "effective_at": "2026-02-22T14:30:00Z",
000075 | "expires_at": "2026-03-01T00:00:00Z",
000076 | "reason_code": "temporary_suspension_pending_review",
000077 | "reason": "Authority temporarily suspended",
000078 | "effect": {
000079 | "new_recognitions_allowed": false,
000080 | "existing_recognitions_remain_visible": true,
000081 | "reader_policy_effect": "exclude_or_label_material_recognized_only_by_this_authority_channel_when_policy_disallows_conditionally_revoked_authorities"
000082 | },
000083 | "notes": "Temporary suspension pending review."
000084 | },
000085 | {
000086 | "entry_id": "rev-0003",
000087 | "target_level": "artifact",
000088 | "kind": "artifact_id",
000089 | "target": {
000090 | "artifact_id": "sha256:9f3e6e5d2c1a4b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c",
000091 | "artifact_type": "reference_exchange"
000092 | },
000093 | "revocation_status": "revoked",
000094 | "revoked_at": "2026-02-24T18:05:10Z",
000095 | "effective_at": "2026-02-24T18:05:10Z",
000096 | "expires_at": null,
000097 | "reason_code": "post_publication_validation_revoked",
000098 | "reason": "Validation decision revoked after publication",
000099 | "validation_refs": [
000100 | {
000101 | "validation_decision_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
000102 | }
000103 | ],
000104 | "effect": {
000105 | "new_distribution_allowed": false,
000106 | "existing_traces_remain_visible": true,
000107 | "reader_policy_effect": "mark_as_revoked_and_exclude_under_reader_policies_that_disallow_revoked_artifacts"
000108 | },
000109 | "notes": "Consumers should preserve lineage and display the revoked status. Federations that include this artifact should expose the revocation and apply the active reader policy."
000110 | }
000111 | ],
000112 | 
000113 | "signatures": [
000114 | {
000115 | "key_id": "tenant_123_root_ed25519_v2",
000116 | "alg": "ed25519",
000117 | "signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
000118 | "created_at": "2026-02-26T18:55:10Z"
000119 | }
000120 | ],
000121 | 
000122 | "extensions": {}
000123 | }
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/runtime-pack-manifest.example.json"
id=bff023f99da2
kind=source
size=6976
lines=231
line_ref=1-231
chunks=0
chunk_refs=
summary="Source file."
----
000001 | {
000002 | "schema_version": "5.0",
000003 | "artifact_type": "runtime_pack_manifest",
000004 | "runtime_pack_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
000005 | "runtime_pack_version": "5.0.0",
000006 | "created_at": "2026-06-12T16:45:00Z",
000007 | 
000008 | "profiles": [
000009 | "kristal.v5:profile-query-tpf-pagination@1"
000010 | ],
000011 | 
000012 | "source_exchange_ref": {
000013 | "exchange_id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
000014 | "artifact_type": "reference_exchange",
000015 | "exchange_manifest_hash": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
000016 | "exchange_version": "5.0.0",
000017 | "scope": {
000018 | "domain": "education",
000019 | "subdomain": "wikidata-seed-reference",
000020 | "jurisdiction": null,
000021 | "time_window": "2026-06",
000022 | "tenant_id": null,
000023 | "environment": "example",
000024 | "language": "en"
000025 | }
000026 | },
000027 | 
000028 | "source_artifact_status": "reference",
000029 | 
000030 | "validation_refs": [
000031 | {
000032 | "id": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
000033 | "artifact_type": "validation_report",
000034 | "hash": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
000035 | "uri": "kristal://validation-reports/sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
000036 | }
000037 | ],
000038 | 
000039 | "authority_recognition_refs": [
000040 | {
000041 | "id": "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
000042 | "artifact_type": "authority_recognition",
000043 | "hash": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
000044 | "uri": "kristal://authority-recognitions/sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"
000045 | }
000046 | ],
000047 | 
000048 | "compiler": {
000049 | "name": "kristal-runtime-pack-compiler",
000050 | "version": "5.0.0",
000051 | "git_commit": "a1b2c3d4",
000052 | "build_platform": "linux-x86_64"
000053 | },
000054 | 
000055 | "build": {
000056 | "build_id": "build:20260612T164500Z:runtime-pack-example",
000057 | "deterministic": true,
000058 | "canonicalization_profile": "kristal.v5:jcs-rfc8785",
000059 | "canonicalization_version": "1",
000060 | "config_hash": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
000061 | "compile_status": "succeeded",
000062 | "validation_status": "validated",
000063 | "recognition_status": "recognized",
000064 | "publication_status": "published",
000065 | "activation_status": "activated",
000066 | "reason_codes": [
000067 | "schema_valid",
000068 | "provenance_sufficient",
000069 | "evidence_sufficient",
000070 | "authority_recognized",
000071 | "policy_satisfied",
000072 | "hash_valid",
000073 | "signature_valid"
000074 | ]
000075 | },
000076 | 
000077 | "policies": {
000078 | "data_ordering": {
000079 | "policy": "qid_pid_statement_id_asc",
000080 | "notes": "Primary assertion table ordered by subject identifier, predicate identifier, then stable statement identifier."
000081 | },
000082 | "row_grouping": {
000083 | "policy": "fixed_rows_100k",
000084 | "notes": "Row groups are deterministically cut every 100000 rows."
000085 | },
000086 | "membership_filter": {
000087 | "kind": "bloom",
000088 | "seed": 12345,
000089 | "bits_per_key": 10,
000090 | "hash_functions": 7,
000091 | "notes": "Bloom filter generated deterministically from stable assertion keys."
000092 | },
000093 | "bitmap": {
000094 | "format": "roaring_run_optimized",
000095 | "run_optimize": true,
000096 | "notes": "Roaring bitmap indexes use deterministic run optimization."
000097 | },
000098 | "parquet": {
000099 | "compression": "zstd",
000100 | "dictionary_encoding": true,
000101 | "statistics": "rowgroup",
000102 | "bloom_filters": {
000103 | "enabled": true,
000104 | "fpp": 0.01,
000105 | "columns": [
000106 | "subject_id",
000107 | "predicate_id",
000108 | "assertion_id"
000109 | ]
000110 | }
000111 | },
000112 | "reader_policy_selection": {
000113 | "mode": "validated_only",
000114 | "include_disputed": false,
000115 | "include_fictional": false,
000116 | "include_mythological": false,
000117 | "notes": "This pack materializes a validated-only reference view while preserving labels and source lineage."
000118 | }
000119 | },
000120 | 
000121 | "reader_policy_refs": [
000122 | {
000123 | "id": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
000124 | "artifact_type": "reader_policy",
000125 | "hash": "sha256:4444444444444444444444444444444444444444444444444444444444444444",
000126 | "uri": "kristal://reader-policies/validated-only-reference"
000127 | }
000128 | ],
000129 | 
000130 | "query_contract_ref": {
000131 | "contract_id": "kristal.v5:query-contract:offline-core",
000132 | "contract_hash": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
000133 | "contract_version": "1"
000134 | },
000135 | 
000136 | "query_capabilities": {
000137 | "supports_pagination": true,
000138 | "supports_cardinality_estimates": true,
000139 | "supports_authority_channel_filter": true,
000140 | "supports_validation_status_filter": true,
000141 | "supports_certainty_level_filter": true,
000142 | "supports_validated_as_filter": true,
000143 | "supports_scope_filter": true,
000144 | "supports_disagreement_view": true
000145 | },
000146 | 
000147 | "files": [
000148 | {
000149 | "path": "data/assertions.parquet",
000150 | "role": "parquet_data",
000151 | "sha256": "6666666666666666666666666666666666666666666666666666666666666666",
000152 | "size_bytes": 1048576,
000153 | "mime_type": "application/vnd.apache.parquet"
000154 | },
000155 | {
000156 | "path": "indexes/assertion-order.idx",
000157 | "role": "query_index",
000158 | "sha256": "7777777777777777777777777777777777777777777777777777777777777777",
000159 | "size_bytes": 262144,
000160 | "mime_type": "application/octet-stream"
000161 | },
000162 | {
000163 | "path": "indexes/membership-filter.bin",
000164 | "role": "membership_filter",
000165 | "sha256": "8888888888888888888888888888888888888888888888888888888888888888",
000166 | "size_bytes": 65536,
000167 | "mime_type": "application/octet-stream"
000168 | },
000169 | {
000170 | "path": "indexes/validation-status.roaring",
000171 | "role": "validation_index",
000172 | "sha256": "9999999999999999999999999999999999999999999999999999999999999999",
000173 | "size_bytes": 32768,
000174 | "mime_type": "application/octet-stream"
000175 | },
000176 | {
000177 | "path": "indexes/recognition-status.roaring",
000178 | "role": "recognition_index",
000179 | "sha256": "abababababababababababababababababababababababababababababababab",
000180 | "size_bytes": 32768,
000181 | "mime_type": "application/octet-stream"
000182 | },
000183 | {
000184 | "path": "indexes/certainty-level.roaring",
000185 | "role": "certainty_index",
000186 | "sha256": "babababababababababababababababababababababababababababababababa",
000187 | "size_bytes": 32768,
000188 | "mime_type": "application/octet-stream"
000189 | },
000190 | {
000191 | "path": "indexes/scope-domain.roaring",
000192 | "role": "scope_index",
000193 | "sha256": "cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
000194 | "size_bytes": 32768,
000195 | "mime_type": "application/octet-stream"
000196 | },
000197 | {
000198 | "path": "policies/reader-policy.validated-only.json",
000199 | "role": "reader_policy",
000200 | "sha256": "dededededededededededededededededededededededededededededededede",
000201 | "size_bytes": 4096,
000202 | "mime_type": "application/json"
000203 | },
000204 | {
000205 | "path": "metadata/pack-metadata.json",
000206 | "role": "metadata",
000207 | "sha256": "efefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
000208 | "size_bytes": 8192,
000209 | "mime_type": "application/json"
000210 | }
000211 | ],
000212 | 
000213 | "integrity": {
000214 | "hash_alg": "sha256",
000215 | "pack_hash": "sha256:f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1f1",
000216 | "manifest_hash": "sha256:f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2f2"
000217 | },
000218 | 
000219 | "signatures": [
000220 | {
000221 | "key_id": "authority_example_reference_ed25519_v1",
000222 | "alg": "ed25519",
000223 | "signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
000224 | "created_at": "2026-06-12T16:45:10Z"
000225 | }
000226 | ],
000227 | 
000228 | "extensions": {
000229 | "example_purpose": "Demonstrates a Kristal v5 Runtime Pack derived from a reference Exchange with validated-only reader policy materialization, query capabilities, deterministic build policies, file-level hashes, and pack-level integrity metadata."
000230 | }
000231 | }
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/structured-epistemic-state.example.json"
id=f92658fc8d71
kind=source
size=28072
lines=1005
line_ref=1-1005
chunks=3
chunk_refs=1-350,351-700,701-1005
summary="Source file."

--- CHUNK BEGIN ---
id=f92658fc8d71:1-350
start=1
end=350
----
{
"schema_version": "5.0",
"artifact_type": "structured_epistemic_state",
"state_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"artifact_status": "working",
"created_at": "2026-06-12T16:40:00Z",
"updated_at": "2026-06-12T16:40:00Z",
"created_by": {
"agent_id": "agent:kristal-example-compiler",
"name": "Kristal Example Compiler",
"agent_type": "system"
},
"canonicalization_profile": "kristal.v5:jcs-rfc8785",
"canonicalization_version": "1",
"content_hash": {
"alg": "sha256",
"value": "2222222222222222222222222222222222222222222222222222222222222222"
},
"hash_target_policy": {
"exclude_fields": [
"state_id",
"content_hash",
"signatures"
],
"notes": "The content_hash is computed over the deterministic canonical serialization of the unsigned Structured Epistemic State, excluding state_id, content_hash, and signatures."
},
"scope": {
"domain": "research",
"subdomain": "example-knowledge-state",
"jurisdiction": null,
"time_window": null,
"tenant_id": null,
"environment": "example",
"language": "en"
},
"source_refs": [
{
"source_id": "source:example-research-note-001",
"source_type": "human_submission",
"title": "Example research note on urban tree canopy",
"publisher": "Example Research Collective",
"retrieved_at": "2026-06-12T16:20:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "3333333333333333333333333333333333333333333333333333333333333333"
},
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
}
},
{
"source_id": "source:example-city-open-data-2026",
"source_type": "dataset",
"title": "Example City Open Data — Tree Canopy Survey 2026",
"publisher": "Example City Open Data Office",
"retrieved_at": "2026-06-12T16:22:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "4444444444444444444444444444444444444444444444444444444444444444"
},
"authority_channel": {
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
}
}
],
"derived_from": [],
"merged_from": [],
"supersedes": [],
"assertions": [
{
"assertion_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"source_assertion_id": "research-note-hypothesis-001",
"statement": {
"subject": {
"label": "Increasing urban tree canopy",
"description": "A proposed intervention to increase tree cover in urban neighborhoods",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
}
},
"predicate": {
"label": "may reduce",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
}
},
"object": {
"kind": "string",
"value": "summer surface temperature in selected neighborhoods"
},
"qualifiers": [
{
"predicate": {
"label": "epistemic mode",
"language": "en"
},
"object": {
"kind": "string",
"value": "research hypothesis"
},
"scope": {
"domain": "research",
"subdomain": "urban-climate",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"notes": "This assertion is explicitly represented as a hypothesis, not as an established fact."
}
],
"rank": "normal",
"statement_hash": {
"alg": "sha256",
"value": "5555555555555555555555555555555555555555555555555555555555555555"
}
},
"natural_language_statement": {
"text": "Increasing urban tree canopy may reduce summer surface temperature in selected neighborhoods.",
"lang": "en"
},
"assertion_status": "hypothesis",
"certainty_level": "speculative",
"validated_as": "hypothesis",
"scope": {
"domain": "research",
"subdomain": "urban-climate",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"evidence_refs": [
{
"evidence_id": "evidence:research-note-hypothesis-001",
"source_ref": {
"source_id": "source:example-research-note-001",
"source_type": "human_submission",
"title": "Example research note on urban tree canopy",
"publisher": "Example Research Collective",
"content_hash": {
"alg": "sha256",
"value": "3333333333333333333333333333333333333333333333333333333333333333"
},
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
}
},
"quote": "The collective proposes that canopy expansion may reduce measured surface temperature during summer heat events.",
"section": "Hypothesis",
"evidence_status": "provided",
"content_hash": {
"alg": "sha256",
"value": "6666666666666666666666666666666666666666666666666666666666666666"
}
}
],
"provenance_refs": [
{
"artifact_id": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
"artifact_type": "human_submission",
"content_hash": {
"alg": "sha256",
"value": "8888888888888888888888888888888888888888888888888888888888888888"
},
"created_at": "2026-06-12T16:10:00Z"
}
],
"authority_recognition_refs": [],
"validation": {
"validation_status": "validated",
"validated_as": "hypothesis",
"certainty_level": "speculative",
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:research-hypothesis-registration",
"policy_version": "1"
},
"scope": {
"domain": "research",
"subdomain": "urban-climate",
"jurisdiction": null,
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"reason_codes": [
"policy_satisfied",
"provenance_sufficient"
],
"validation_refs": [],
"notes": "Validated only as a registered research hypothesis. This does not imply the claim is established."
},
"uncertainty": {
"confidence": 0.35,
"method": "example confidence assigned by research collective",
"notes": "Speculative claim requiring further evidence."
},
"lineage": {
"source_assertions": [],
"source_artifacts": [
{
"artifact_id": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
"artifact_type": "human_submission",
"content_hash": {
"alg": "sha256",
"value": "8888888888888888888888888888888888888888888888888888888888888888"
}
}
],
"transforms": [
{
"transform_id": "transform:example-hypothesis-registration-001",
"transform_type": "manual_edit",
"tool": "example-editor",
"policy_ref": {
"policy_id": "kristal.v5:validation-policy:research-hypothesis-registration",
"policy_version": "1"
},
"created_at": "2026-06-12T16:30:00Z",
"notes": "Human-authored hypothesis represented as a Structured Epistemic State assertion."
}
]
},
"conflicts_with": [],
"supersedes": [],
"notes": "This assertion is valid as a hypothesis and should not be rendered as an established factual claim."
},
{
"assertion_id": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"source_assertion_id": "city-open-data-claim-001",
"statement": {
"subject": {
"label": "Example City central district",
"description": "A district in the example city dataset",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
}
},
"predicate": {
"label": "has measured tree canopy coverage",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
}
},
"object": {
"kind": "quantity",
"value": {
"amount": 18.4,
"unit_label": "percent"
},
"normalized": {
"value": 0.184,
"precision": "0.001",
"notes": "Percent converted to decimal fraction for normalized query use."
}
},
"qualifiers": [
{
"predicate": {
"label": "survey year",
"language": "en"
},
"object": {
"kind": "time",
"value": {
"iso8601": "2026",
"precision": "year",
"calendar": "gregorian"
}
},
"scope": {
"domain": "environment",
"subdomain": "urban-tree-canopy",
"jurisdiction": "Example City",
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
}
}
],
"rank": "preferred",
"statement_hash": {
"alg": "sha256",
"value": "9999999999999999999999999999999999999999999999999999999999999999"
}
},
"natural_language_statement": {
"text": "Example City central district has measured tree canopy coverage of 18.4% in the 2026 survey.",
"lang": "en"
},
"assertion_status": "sourced",
"certainty_level": "medium",
"validated_as": "sourced_claim",
"scope": {
"domain": "environment",
"subdomain": "urban-tree-canopy",
"jurisdiction": "Example City",
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"evidence_refs": [
{
"evidence_id": "evidence:city-open-data-tree-canopy-001",
"source_ref": {
"source_id": "source:example-city-open-data-2026",
"source_type": "dataset",
"title": "Example City Open Data — Tree Canopy Survey 2026",
"publisher": "Example City Open Data Office",
"content_hash": {
"alg": "sha256",
"value": "4444444444444444444444444444444444444444444444444444444444444444"
},
"authority_channel": {
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
}
},
"section": "district_canopy_coverage.csv row district=central",
"evidence_status": "sufficient",
"content_hash": {
"alg": "sha256",
"value": "abababababababababababababababababababababababababababababababab"
}
}
],
"provenance_refs": [
{
--- CHUNK END ---

--- CHUNK BEGIN ---
id=f92658fc8d71:351-700
start=351
end=700
----
"artifact_id": "sha256:cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
"artifact_type": "dataset",
"content_hash": {
"alg": "sha256",
"value": "dededededededededededededededededededededededededededededededede"
},
"created_at": "2026-06-12T16:22:00Z"
}
],
"authority_recognition_refs": [
{
"recognition_id": "sha256:efefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
"recognition_status": "recognized",
"recognized_as": "institutional_reference",
"authority_channel": {
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
},
"scope": {
"domain": "environment",
"subdomain": "urban-tree-canopy",
"jurisdiction": "Example City",
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:publisher-declared-dataset",
"policy_version": "1"
}
}
],
"validation": {
"validation_status": "validated",
"validated_as": "publisher_declaration",
"certainty_level": "medium",
"authority_channel": {
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:publisher-declared-dataset",
"policy_version": "1"
},
"scope": {
"domain": "environment",
"subdomain": "urban-tree-canopy",
"jurisdiction": "Example City",
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"reason_codes": [
"authority_recognized",
"evidence_sufficient",
"policy_satisfied"
],
"validation_refs": [],
"notes": "Validated as the publisher's declared dataset value, not as an independently audited scientific result."
},
"uncertainty": {
"confidence": 0.8,
"method": "publisher dataset confidence example",
"notes": "Medium confidence due to reliance on publisher-declared dataset without independent audit."
},
"lineage": {
"source_assertions": [],
"source_artifacts": [
{
"artifact_id": "sha256:cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
"artifact_type": "dataset",
"content_hash": {
"alg": "sha256",
"value": "dededededededededededededededededededededededededededededededede"
}
}
],
"transforms": [
{
"transform_id": "transform:city-open-data-import-001",
"transform_type": "import",
"tool": "example-dataset-importer",
"policy_ref": {
"policy_id": "kristal.v5:validation-policy:publisher-declared-dataset",
"policy_version": "1"
},
"created_at": "2026-06-12T16:31:00Z",
"notes": "Dataset row imported into Structured Epistemic State."
}
]
},
"conflicts_with": [],
"supersedes": [],
"notes": "This assertion is validated as a publisher declaration and can be used by reader policies that allow this authority channel."
},
{
"assertion_id": "sha256:fafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafafa",
"source_assertion_id": "reviewed-claim-001",
"statement": {
"subject": {
"label": "Example City tree canopy dataset",
"description": "The 2026 example city tree canopy survey dataset",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
}
},
"predicate": {
"label": "is usable for",
"language": "en"
},
"object": {
"kind": "string",
"value": "preliminary neighborhood-level planning analysis"
},
"qualifiers": [
{
"predicate": {
"label": "review status",
"language": "en"
},
"object": {
"kind": "string",
"value": "reviewed by example research collective"
},
"scope": {
"domain": "research",
"subdomain": "urban-planning",
"jurisdiction": "Example City",
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
}
}
],
"rank": "normal",
"statement_hash": {
"alg": "sha256",
"value": "bcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbcbc"
}
},
"natural_language_statement": {
"text": "The Example City tree canopy dataset is usable for preliminary neighborhood-level planning analysis.",
"lang": "en"
},
"assertion_status": "validated",
"certainty_level": "high",
"validated_as": "reviewed_claim",
"scope": {
"domain": "research",
"subdomain": "urban-planning",
"jurisdiction": "Example City",
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"evidence_refs": [
{
"evidence_id": "evidence:reviewed-claim-001",
"source_ref": {
"source_id": "source:example-city-open-data-2026",
"source_type": "dataset",
"title": "Example City Open Data — Tree Canopy Survey 2026",
"publisher": "Example City Open Data Office",
"content_hash": {
"alg": "sha256",
"value": "4444444444444444444444444444444444444444444444444444444444444444"
},
"authority_channel": {
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
}
},
"section": "dataset documentation and review checklist",
"evidence_status": "sufficient",
"content_hash": {
"alg": "sha256",
"value": "cfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcf"
}
}
],
"provenance_refs": [
{
"artifact_id": "sha256:edededededededededededededededededededededededededededededededed",
"artifact_type": "review_bundle",
"content_hash": {
"alg": "sha256",
"value": "1212121212121212121212121212121212121212121212121212121212121212"
},
"created_at": "2026-06-12T16:35:00Z"
}
],
"authority_recognition_refs": [
{
"recognition_id": "sha256:3434343434343434343434343434343434343434343434343434343434343434",
"recognition_status": "recognized",
"recognized_as": "reviewed_claim",
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
},
"scope": {
"domain": "research",
"subdomain": "urban-planning",
"jurisdiction": "Example City",
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:research-dataset-review",
"policy_version": "1"
}
}
],
"validation": {
"validation_status": "validated",
"validated_as": "reviewed_claim",
"certainty_level": "high",
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:research-dataset-review",
"policy_version": "1"
},
"scope": {
"domain": "research",
"subdomain": "urban-planning",
"jurisdiction": "Example City",
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"reason_codes": [
"authority_recognized",
"evidence_sufficient",
"policy_satisfied"
],
"validation_refs": [
{
"artifact_id": "sha256:edededededededededededededededededededededededededededededededed",
"artifact_type": "review_bundle",
"content_hash": {
"alg": "sha256",
"value": "1212121212121212121212121212121212121212121212121212121212121212"
}
}
],
"notes": "Validated as a reviewed claim for preliminary planning analysis."
},
"uncertainty": {
"confidence": 0.9,
"method": "example review process",
"notes": "High confidence within the declared planning-analysis scope."
},
"lineage": {
"source_assertions": [
"sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
],
"source_artifacts": [
{
"artifact_id": "sha256:cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
"artifact_type": "dataset",
"content_hash": {
"alg": "sha256",
"value": "dededededededededededededededededededededededededededededededede"
}
}
],
"transforms": [
{
"transform_id": "transform:research-review-001",
"transform_type": "review",
"tool": "example-review-workflow",
"policy_ref": {
"policy_id": "kristal.v5:validation-policy:research-dataset-review",
"policy_version": "1"
},
"created_at": "2026-06-12T16:35:00Z",
"notes": "Review concluded that the dataset is usable for preliminary planning analysis."
}
]
},
"conflicts_with": [],
"supersedes": [],
"notes": "This assertion demonstrates a validated reviewed claim with a high certainty level within a narrow scope."
}
],
"provenance": [
{
"provenance_id": "prov:example-state-created-001",
"event_type": "created",
"created_at": "2026-06-12T16:40:00Z",
"agent": {
"agent_id": "agent:kristal-example-compiler",
"name": "Kristal Example Compiler",
"agent_type": "system"
},
"policy_refs": [
{
"policy_id": "kristal.v5:state-policy:example-structured-epistemic-state",
"policy_version": "1"
}
],
"notes": "Created as a compact example of the Structured Epistemic State schema."
},
{
"provenance_id": "prov:research-note-imported-001",
"event_type": "imported",
"created_at": "2026-06-12T16:30:00Z",
"agent": {
"agent_id": "agent:example-research-importer",
"name": "Example Research Importer",
"agent_type": "system"
},
"source_ref": {
"source_id": "source:example-research-note-001",
"source_type": "human_submission",
"title": "Example research note on urban tree canopy",
"publisher": "Example Research Collective",
"content_hash": {
"alg": "sha256",
"value": "3333333333333333333333333333333333333333333333333333333333333333"
},
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
}
},
"policy_refs": [
{
"policy_id": "kristal.v5:validation-policy:research-hypothesis-registration",
"policy_version": "1"
}
],
"notes": "Imported the example research hypothesis."
},
{
"provenance_id": "prov:city-dataset-imported-001",
"event_type": "imported",
"created_at": "2026-06-12T16:31:00Z",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=f92658fc8d71:701-1005
start=701
end=1005
----
"agent": {
"agent_id": "agent:example-dataset-importer",
"name": "Example Dataset Importer",
"agent_type": "system"
},
"source_ref": {
"source_id": "source:example-city-open-data-2026",
"source_type": "dataset",
"title": "Example City Open Data — Tree Canopy Survey 2026",
"publisher": "Example City Open Data Office",
"content_hash": {
"alg": "sha256",
"value": "4444444444444444444444444444444444444444444444444444444444444444"
},
"authority_channel": {
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
}
},
"policy_refs": [
{
"policy_id": "kristal.v5:validation-policy:publisher-declared-dataset",
"policy_version": "1"
}
],
"notes": "Imported one publisher-declared dataset value."
},
{
"provenance_id": "prov:research-review-completed-001",
"event_type": "reviewed",
"created_at": "2026-06-12T16:35:00Z",
"agent": {
"agent_id": "agent:example-research-collective-reviewer",
"name": "Example Research Collective Reviewer",
"agent_type": "research_collective",
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
}
},
"artifact_ref": {
"artifact_id": "sha256:edededededededededededededededededededededededededededededededed",
"artifact_type": "review_bundle",
"content_hash": {
"alg": "sha256",
"value": "1212121212121212121212121212121212121212121212121212121212121212"
},
"created_at": "2026-06-12T16:35:00Z"
},
"policy_refs": [
{
"policy_id": "kristal.v5:validation-policy:research-dataset-review",
"policy_version": "1"
}
],
"notes": "Recorded the example review event."
}
],
"review_refs": [
{
"artifact_id": "sha256:edededededededededededededededededededededededededededededededed",
"artifact_type": "review_bundle",
"content_hash": {
"alg": "sha256",
"value": "1212121212121212121212121212121212121212121212121212121212121212"
},
"created_at": "2026-06-12T16:35:00Z"
}
],
"policy_refs": [
{
"policy_id": "kristal.v5:state-policy:example-structured-epistemic-state",
"policy_version": "1"
},
{
"policy_id": "kristal.v5:validation-policy:research-hypothesis-registration",
"policy_version": "1"
},
{
"policy_id": "kristal.v5:validation-policy:publisher-declared-dataset",
"policy_version": "1"
},
{
"policy_id": "kristal.v5:validation-policy:research-dataset-review",
"policy_version": "1"
}
],
"authority_recognition_refs": [
{
"recognition_id": "sha256:efefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
"recognition_status": "recognized",
"recognized_as": "institutional_reference",
"authority_channel": {
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
},
"scope": {
"domain": "environment",
"subdomain": "urban-tree-canopy",
"jurisdiction": "Example City",
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:publisher-declared-dataset",
"policy_version": "1"
}
},
{
"recognition_id": "sha256:3434343434343434343434343434343434343434343434343434343434343434",
"recognition_status": "recognized",
"recognized_as": "reviewed_claim",
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
},
"scope": {
"domain": "research",
"subdomain": "urban-planning",
"jurisdiction": "Example City",
"time_window": "2026",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:research-dataset-review",
"policy_version": "1"
}
}
],
"reader_policy_refs": [
{
"reader_policy_id": "reader_policy:research",
"mode": "research"
},
{
"reader_policy_id": "reader_policy:validated-only-selected-authorities",
"mode": "validated_only"
},
{
"reader_policy_id": "reader_policy:all-with-labels",
"mode": "all_with_labels"
}
],
"certainty_summary": {
"counts_by_certainty_level": {
"speculative": 1,
"medium": 1,
"high": 1
},
"counts_by_assertion_status": {
"hypothesis": 1,
"sourced": 1,
"validated": 1
},
"counts_by_validated_as": {
"hypothesis": 1,
"publisher_declaration": 1,
"reviewed_claim": 1
},
"notes": "This example intentionally includes multiple certainty levels to demonstrate that validation and certainty are separate concepts."
},
"validation_summary": {
"validation_status": "validated",
"recognition_status": "recognized",
"authority_channels": [
{
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
},
{
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
}
],
"validation_refs": [
{
"artifact_id": "sha256:edededededededededededededededededededededededededededededededed",
"artifact_type": "review_bundle",
"content_hash": {
"alg": "sha256",
"value": "1212121212121212121212121212121212121212121212121212121212121212"
}
}
],
"recognition_refs": [
{
"recognition_id": "sha256:efefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
"recognition_status": "recognized",
"recognized_as": "institutional_reference",
"authority_channel": {
"authority_channel_id": "authority:example-city-open-data-office",
"name": "Example City Open Data Office"
}
},
{
"recognition_id": "sha256:3434343434343434343434343434343434343434343434343434343434343434",
"recognition_status": "recognized",
"recognized_as": "reviewed_claim",
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
}
}
],
"reason_codes": [
"policy_satisfied",
"provenance_sufficient",
"evidence_sufficient"
],
"notes": "The state contains a validated hypothesis, a validated publisher declaration, and a validated reviewed claim. They do not carry the same certainty level."
},
"lineage": {
"source_artifacts": [
{
"artifact_id": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
"artifact_type": "human_submission",
"content_hash": {
"alg": "sha256",
"value": "8888888888888888888888888888888888888888888888888888888888888888"
},
"created_at": "2026-06-12T16:10:00Z"
},
{
"artifact_id": "sha256:cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
"artifact_type": "dataset",
"content_hash": {
"alg": "sha256",
"value": "dededededededededededededededededededededededededededededededede"
},
"created_at": "2026-06-12T16:22:00Z"
}
],
"source_states": [],
"transforms": [
{
"transform_id": "transform:structured-state-assembly-001",
"transform_type": "merge",
"tool": "example-state-assembler",
"policy_ref": {
"policy_id": "kristal.v5:state-policy:example-structured-epistemic-state",
"policy_version": "1"
},
"created_at": "2026-06-12T16:40:00Z",
"notes": "Merged a research hypothesis, a publisher-declared dataset value, and a reviewed planning assertion into one Structured Epistemic State."
}
],
"compiler": {
"agent_id": "agent:kristal-example-compiler",
"name": "Kristal Example Compiler",
"agent_type": "system"
},
"policy_refs": [
{
"policy_id": "kristal.v5:state-policy:example-structured-epistemic-state",
"policy_version": "1"
}
]
},
"build": {
"build_id": "build:20260612T164000Z:structured-epistemic-state-example",
"schema_version": "5.0",
"compile_status": "succeeded",
"validation_status": "validated",
"review_status": "completed",
"recognition_status": "recognized",
"publication_status": "not_published",
"activation_status": "not_applicable",
"working_outputs": [],
"reference_outputs": [],
"reason_codes": [
"schema_valid",
"provenance_sufficient",
"evidence_sufficient",
"policy_satisfied"
],
"created_at": "2026-06-12T16:40:00Z"
},
"warnings": [
{
"code": "LOW_CERTAINTY",
"message": "One assertion is validated only as a speculative research hypothesis.",
"path": "/assertions/0",
"reason_code": "certainty_too_low_for_policy"
}
],
"extensions": {
"example_purpose": "Demonstrates that Structured Epistemic State can contain assertions with different statuses, certainty levels, validation scopes, and authority channels."
},
"signatures": [
{
"key_id": "example_research_collective_ed25519_v1",
"alg": "ed25519",
"signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
"created_at": "2026-06-12T16:40:10Z",
"authority_channel": {
"authority_channel_id": "authority:example-research-collective",
"name": "Example Research Collective"
}
}
]
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/validation-report.example.json"
id=9b064813b4da
kind=source
size=13570
lines=450
line_ref=1-450
chunks=2
chunk_refs=1-350,351-450
summary="Source file."

--- CHUNK BEGIN ---
id=9b064813b4da:1-350
start=1
end=350
----
{
"schema_version": "5.0",
"artifact_type": "validation_report",
"validation_report_id": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"created_at": "2026-06-12T16:45:00Z",
"updated_at": "2026-06-12T16:45:00Z",

"canonicalization_profile": "kristal.v5:jcs-rfc8785",
"canonicalization_version": "1",

"content_hash": {
"alg": "sha256",
"value": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
},

"hash_target_policy": {
"exclude_fields": ["validation_report_id", "content_hash", "signatures"],
"notes": "The content_hash is computed over the deterministic canonical serialization of the unsigned validation report, excluding validation_report_id, content_hash, and signatures."
},

"issuer_authority_channel": {
"authority_channel_id": "authority:global-science-reference-example",
"name": "Global Science Reference Example"
},

"target": {
"state_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"artifact_type": "structured_epistemic_state",
"content_hash": {
"alg": "sha256",
"value": "2222222222222222222222222222222222222222222222222222222222222222"
}
},

"target_level": "structured_epistemic_state",

"scope": {
"domain": "science",
"subdomain": "planetary-science",
"jurisdiction": null,
"time_window": null,
"tenant_id": null,
"environment": "example",
"language": "en"
},

"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:scientific-reference-review",
"policy_version": "1"
},

"validation_status": "validated",
"validated_as": "high_confidence_fact",
"certainty_level": "established",
"recognition_status": "recognized",

"authority_recognition_refs": [
{
"recognition_id": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
"recognition_status": "recognized",
"recognized_as": "high_confidence_fact",
"authority_channel": {
"authority_channel_id": "authority:global-science-reference-example",
"name": "Global Science Reference Example"
},
"scope": {
"domain": "science",
"subdomain": "planetary-science",
"jurisdiction": null,
"time_window": null,
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:scientific-reference-review",
"policy_version": "1"
}
}
],

"reader_policy_refs": [
{
"reader_policy_id": "reader_policy:reference-only-global-science",
"mode": "reference_only"
},
{
"reader_policy_id": "reader_policy:validated-only-selected-authorities",
"mode": "validated_only"
}
],

"input_refs": [
{
"artifact_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"artifact_type": "structured_epistemic_state",
"content_hash": {
"alg": "sha256",
"value": "2222222222222222222222222222222222222222222222222222222222222222"
},
"created_at": "2026-06-12T16:30:00Z"
}
],

"evidence_refs": [
{
"evidence_id": "evidence:science-reference-earth-shape-0001",
"source_ref": {
"source_id": "source:global-science-reference-earth-shape",
"source_type": "institutional_record",
"title": "Global science reference position on Earth shape",
"publisher": "Global Science Reference Example",
"retrieved_at": "2026-06-12T16:21:00Z",
"license": "example-only",
"content_hash": {
"alg": "sha256",
"value": "4444444444444444444444444444444444444444444444444444444444444444"
},
"authority_channel": {
"authority_channel_id": "authority:global-science-reference-example",
"name": "Global Science Reference Example"
}
},
"quote": "The reference model describes Earth as approximately spherical for general scientific and educational use.",
"section": "Reference position",
"evidence_status": "sufficient",
"content_hash": {
"alg": "sha256",
"value": "abababababababababababababababababababababababababababababababab"
}
}
],

"provenance_refs": [
{
"artifact_id": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
"artifact_type": "reference_exchange",
"content_hash": {
"alg": "sha256",
"value": "6666666666666666666666666666666666666666666666666666666666666666"
},
"created_at": "2026-06-01T00:00:00Z"
}
],

"findings": [
{
"finding_id": "finding:schema-valid-0001",
"check_id": "check:schema-validation",
"check_type": "schema",
"status": "passed",
"severity": "info",
"reason_code": "schema_valid",
"message": "The target Structured Epistemic State satisfies the applicable Kristal v5 schema requirements.",
"target": {
"state_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"artifact_type": "structured_epistemic_state"
}
},
{
"finding_id": "finding:integrity-valid-0001",
"check_id": "check:content-hash",
"check_type": "hash",
"status": "passed",
"severity": "info",
"reason_code": "hash_valid",
"message": "The target content hash matched the declared hash.",
"target": {
"state_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"content_hash": {
"alg": "sha256",
"value": "2222222222222222222222222222222222222222222222222222222222222222"
}
}
},
{
"finding_id": "finding:evidence-sufficient-0001",
"check_id": "check:evidence-sufficiency",
"check_type": "evidence",
"status": "passed",
"severity": "info",
"reason_code": "evidence_sufficient",
"message": "The reviewed assertion has sufficient evidence for the selected authority channel and validation policy.",
"target": {
"assertion_id": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
},
"evidence_refs": [
{
"evidence_id": "evidence:science-reference-earth-shape-0001",
"source_ref": {
"source_id": "source:global-science-reference-earth-shape",
"source_type": "institutional_record",
"title": "Global science reference position on Earth shape",
"publisher": "Global Science Reference Example",
"content_hash": {
"alg": "sha256",
"value": "4444444444444444444444444444444444444444444444444444444444444444"
},
"authority_channel": {
"authority_channel_id": "authority:global-science-reference-example",
"name": "Global Science Reference Example"
}
},
"evidence_status": "sufficient"
}
]
},
{
"finding_id": "finding:disagreement-preserved-0001",
"check_id": "check:federated-disagreement",
"check_type": "conflict",
"status": "passed",
"severity": "info",
"reason_code": "disagreement_preserved",
"message": "The target preserves the disagreement between the scientific reference assertion and the divergent fork assertion without silently merging them.",
"target": {
"state_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
}
}
],

"assertion_results": [
{
"assertion_id": "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
"assertion_status": "validated",
"validation_status": "validated",
"validated_as": "high_confidence_fact",
"certainty_level": "established",
"authority_channel": {
"authority_channel_id": "authority:global-science-reference-example",
"name": "Global Science Reference Example"
},
"scope": {
"domain": "science",
"subdomain": "planetary-science",
"jurisdiction": null,
"time_window": null,
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:scientific-reference-review",
"policy_version": "1"
},
"findings": [
{
"finding_id": "finding:assertion-evidence-sufficient-0001",
"check_id": "check:assertion-evidence",
"check_type": "evidence",
"status": "passed",
"severity": "info",
"reason_code": "evidence_sufficient",
"message": "The assertion is supported by sufficient evidence under the selected scientific reference review policy."
},
{
"finding_id": "finding:assertion-authority-recognized-0001",
"check_id": "check:authority-channel",
"check_type": "authority",
"status": "passed",
"severity": "info",
"reason_code": "authority_recognized",
"message": "The validating authority channel is recognized for this example science scope."
}
],
"reason_codes": ["authority_recognized", "evidence_sufficient", "policy_satisfied"],
"notes": "Validated as a high-confidence scientific reference assertion within the declared authority channel and scope."
},
{
"assertion_id": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
"assertion_status": "disputed",
"validation_status": "rejected",
"validated_as": "rejected_claim",
"certainty_level": "low",
"authority_channel": {
"authority_channel_id": "authority:global-science-reference-example",
"name": "Global Science Reference Example"
},
"scope": {
"domain": "science",
"subdomain": "planetary-science",
"jurisdiction": null,
"time_window": null,
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:scientific-reference-review",
"policy_version": "1"
},
"findings": [
{
"finding_id": "finding:assertion-rejected-0001",
"check_id": "check:scientific-reference-position",
"check_type": "policy",
"status": "failed",
"severity": "high",
"reason_code": "rejected_by_authority_channel",
"message": "The divergent assertion is rejected under the selected scientific reference review policy."
},
{
"finding_id": "finding:conflict-detected-0001",
"check_id": "check:conflict-detection",
"check_type": "conflict",
"status": "warning",
"severity": "medium",
"reason_code": "conflict_detected",
"message": "The assertion conflicts with the validated scientific reference assertion."
}
],
"reason_codes": ["rejected_by_authority_channel", "conflict_detected"],
"notes": "Rejected only under the global science reference example authority channel. This does not erase the assertion from the divergent fork; it defines how this authority evaluates it."
}
],

"artifact_checks": [
{
"check_id": "check:target-schema-valid",
"check_type": "schema",
"status": "passed",
"severity": "info",
"reason_code": "schema_valid",
"message": "Target artifact schema is valid.",
"target": {
"state_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
}
},
{
"check_id": "check:target-integrity-valid",
"check_type": "integrity",
"status": "passed",
"severity": "info",
"reason_code": "hash_valid",
"message": "Target artifact integrity check passed.",
"target": {
"state_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"content_hash": {
"alg": "sha256",
"value": "2222222222222222222222222222222222222222222222222222222222222222"
}
}
},
{
"check_id": "check:target-scope-valid",
"check_type": "scope",
"status": "passed",
"severity": "info",
"reason_code": "policy_satisfied",
"message": "The target scope matches the validation policy scope.",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=9b064813b4da:351-450
start=351
end=450
----
"target": {
"state_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
}
}
],

"policy_evaluation": {
"policy_ref": {
"policy_id": "kristal.v5:validation-policy:scientific-reference-review",
"policy_version": "1"
},
"status": "passed",
"matched_rules": [
"schema_valid",
"content_hash_valid",
"authority_channel_recognized",
"evidence_sufficient_for_reference_assertion",
"disagreement_preserved"
],
"failed_rules": [],
"reason_codes": ["policy_satisfied"],
"notes": "The validation report evaluates the target under the declared scientific reference review policy."
},

"summary": {
"total_findings": 4,
"passed": 4,
"failed": 0,
"warnings": 0,
"not_applicable": 0,
"not_evaluated": 0,
"assertions_total": 2,
"assertions_validated": 1,
"assertions_conditionally_validated": 0,
"assertions_disputed": 1,
"assertions_rejected": 1,
"counts_by_certainty_level": {
"established": 1,
"low": 1
},
"counts_by_validated_as": {
"high_confidence_fact": 1,
"rejected_claim": 1
},
"notes": "This report demonstrates scoped validation: one assertion is validated by the scientific authority channel, while a conflicting divergent assertion is rejected by that same channel but remains traceable."
},

"lineage": {
"source_artifacts": [
{
"artifact_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"artifact_type": "structured_epistemic_state",
"content_hash": {
"alg": "sha256",
"value": "2222222222222222222222222222222222222222222222222222222222222222"
},
"created_at": "2026-06-12T16:30:00Z"
}
],
"source_reports": [],
"derived_from": [],
"supersedes": []
},

"build": {
"build_id": "build:20260612T164500Z:validation-report-example",
"schema_version": "5.0",
"compile_status": "succeeded",
"validation_status": "validated",
"review_status": "completed",
"recognition_status": "recognized",
"publication_status": "not_published",
"activation_status": "not_applicable",
"working_outputs": [],
"reference_outputs": [],
"reason_codes": ["schema_valid", "hash_valid", "policy_satisfied", "disagreement_preserved"],
"created_at": "2026-06-12T16:45:00Z"
},

"warnings": [],

"errors": [],

"signatures": [
{
"key_id": "global_science_reference_example_ed25519_v1",
"alg": "ed25519",
"signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
"created_at": "2026-06-12T16:45:10Z",
"authority_channel": {
"authority_channel_id": "authority:global-science-reference-example",
"name": "Global Science Reference Example"
}
}
],

"extensions": {
"example_purpose": "Demonstrates a Kristal v5 validation report where validation is scoped by authority, policy, domain, certainty, and validated-as mode."
}
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/docs/Technical-Reference/kristal-docs-v5/10-examples/wikidata-seed-kristal.example.json"
id=a5ff2b228c2b
kind=source
size=26769
lines=962
line_ref=1-962
chunks=3
chunk_refs=1-350,351-700,701-962
summary="Source file."

--- CHUNK BEGIN ---
id=a5ff2b228c2b:1-350
start=1
end=350
----
{
"schema_version": "5.0",
"artifact_type": "structured_epistemic_state",
"state_id": "sha256:0101010101010101010101010101010101010101010101010101010101010101",
"artifact_status": "reference",
"created_at": "2026-06-12T17:00:00Z",
"created_by": {
"agent_id": "agent:wikidata-seed-importer-example",
"name": "Wikidata Seed Importer Example",
"agent_type": "system",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
}
},
"canonicalization_profile": "kristal.v5:jcs-rfc8785",
"canonicalization_version": "1",
"content_hash": {
"alg": "sha256",
"value": "0202020202020202020202020202020202020202020202020202020202020202"
},
"hash_target_policy": {
"exclude_fields": [
"state_id",
"content_hash",
"signatures"
],
"notes": "The content_hash is computed over the deterministic canonical serialization of the unsigned Structured Epistemic State, excluding state_id, content_hash, and signatures."
},
"scope": {
"domain": "wikidata",
"subdomain": "seed-corpus",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"source_refs": [
{
"source_id": "source:wikidata-dump-example-20260612",
"source_type": "wikidata_dump",
"source_url": "https://dumps.wikimedia.org/wikidatawiki/entities/",
"title": "Wikidata JSON dump example snapshot",
"publisher": "Wikidata",
"retrieved_at": "2026-06-12T16:45:00Z",
"license": "CC0-1.0",
"content_hash": {
"alg": "sha256",
"value": "0303030303030303030303030303030303030303030303030303030303030303"
},
"authority_channel": {
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
}
],
"derived_from": [],
"merged_from": [],
"supersedes": [],
"assertions": [
{
"assertion_id": "sha256:0404040404040404040404040404040404040404040404040404040404040404",
"source_assertion_id": "wikidata:Q42:P31:statement-example-0001",
"statement": {
"subject": {
"qid": "Q42",
"label": "Douglas Adams",
"description": "English writer and humorist",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
},
"predicate": {
"pid": "P31",
"label": "instance of",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
},
"object": {
"kind": "item",
"value": {
"qid": "Q5",
"label": "human",
"description": "common name of Homo sapiens, unique extant species of the genus Homo",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
}
},
"qualifiers": [],
"rank": "normal",
"statement_hash": {
"alg": "sha256",
"value": "0505050505050505050505050505050505050505050505050505050505050505"
}
},
"natural_language_statement": {
"text": "Douglas Adams is an instance of human.",
"lang": "en"
},
"assertion_status": "validated",
"certainty_level": "medium",
"validated_as": "institutional_reference",
"scope": {
"domain": "wikidata",
"subdomain": "seed-corpus",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"evidence_refs": [
{
"evidence_id": "evidence:wikidata:Q42:P31:statement-example-0001",
"source_ref": {
"source_id": "source:wikidata-dump-example-20260612",
"source_type": "wikidata_dump",
"source_url": "https://dumps.wikimedia.org/wikidatawiki/entities/",
"title": "Wikidata JSON dump example snapshot",
"publisher": "Wikidata",
"retrieved_at": "2026-06-12T16:45:00Z",
"license": "CC0-1.0",
"content_hash": {
"alg": "sha256",
"value": "0303030303030303030303030303030303030303030303030303030303030303"
},
"authority_channel": {
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
},
"section": "Q42 claims P31",
"evidence_status": "sufficient",
"content_hash": {
"alg": "sha256",
"value": "0606060606060606060606060606060606060606060606060606060606060606"
}
}
],
"provenance_refs": [
{
"artifact_id": "sha256:0707070707070707070707070707070707070707070707070707070707070707",
"artifact_type": "wikidata_dump_import",
"content_hash": {
"alg": "sha256",
"value": "0808080808080808080808080808080808080808080808080808080808080808"
},
"created_at": "2026-06-12T16:50:00Z"
}
],
"authority_recognition_refs": [
{
"recognition_id": "sha256:0909090909090909090909090909090909090909090909090909090909090909",
"recognition_status": "recognized",
"recognized_as": "institutional_reference",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
},
"scope": {
"domain": "wikidata",
"subdomain": "seed-corpus",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
}
}
],
"validation": {
"validation_status": "validated",
"validated_as": "institutional_reference",
"certainty_level": "medium",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
},
"scope": {
"domain": "wikidata",
"subdomain": "seed-corpus",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"reason_codes": [
"schema_valid",
"provenance_sufficient",
"authority_recognized",
"policy_satisfied"
],
"validation_refs": [],
"notes": "Validated as a faithful Kristal-compatible packaging of a Wikidata statement, not as a universal physical-world truth claim."
},
"uncertainty": {
"confidence": 0.8,
"method": "source-preserving seed import example",
"notes": "Certainty reflects source packaging status and Wikidata reference scope, not independent external verification."
},
"lineage": {
"source_assertions": [],
"source_artifacts": [
{
"artifact_id": "sha256:0707070707070707070707070707070707070707070707070707070707070707",
"artifact_type": "wikidata_dump_import",
"content_hash": {
"alg": "sha256",
"value": "0808080808080808080808080808080808080808080808080808080808080808"
}
}
],
"transforms": [
{
"transform_id": "transform:wikidata-seed-import-0001",
"transform_type": "import",
"tool": "wikidata-seed-importer-example",
"policy_ref": {
"policy_id": "kristal.v5:import-policy:preserve-wikidata-statements",
"policy_version": "1"
},
"created_at": "2026-06-12T16:50:00Z",
"notes": "Imported while preserving Wikidata entity IDs, property IDs, statement rank, references, qualifiers, labels, aliases, and descriptions where available."
}
]
},
"conflicts_with": [],
"supersedes": [],
"notes": "This assertion is part of a seed corpus. It is usable under reader policies that allow Wikidata-scoped institutional references."
},
{
"assertion_id": "sha256:0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a",
"source_assertion_id": "wikidata:Q42:P569:statement-example-0002",
"statement": {
"subject": {
"qid": "Q42",
"label": "Douglas Adams",
"description": "English writer and humorist",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
},
"predicate": {
"pid": "P569",
"label": "date of birth",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
},
"object": {
"kind": "time",
"value": {
"iso8601": "1952-03-11",
"precision": "day",
"calendar": "Gregorian",
"timezone": "UTC"
},
"normalized": {
"value": "1952-03-11",
"precision": "day",
"normalization_policy_ref": {
"policy_id": "kristal.v5:normalization-policy:wikidata-time-values",
"policy_version": "1"
}
}
},
"qualifiers": [
{
"predicate": {
"pid": "P1480",
"label": "sourcing circumstances",
"language": "en"
},
"object": {
"kind": "string",
"value": "imported from Wikidata statement metadata"
},
"scope": {
"domain": "wikidata",
"subdomain": "seed-corpus",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"notes": "Example qualifier showing that Wikidata qualifiers may be preserved during seed packaging."
}
],
"rank": "normal",
"statement_hash": {
"alg": "sha256",
"value": "0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b"
}
},
"natural_language_statement": {
"text": "Douglas Adams has date of birth 1952-03-11.",
"lang": "en"
},
"assertion_status": "validated",
"certainty_level": "medium",
"validated_as": "institutional_reference",
"scope": {
"domain": "wikidata",
"subdomain": "seed-corpus",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"evidence_refs": [
{
"evidence_id": "evidence:wikidata:Q42:P569:statement-example-0002",
"source_ref": {
"source_id": "source:wikidata-dump-example-20260612",
"source_type": "wikidata_dump",
"source_url": "https://dumps.wikimedia.org/wikidatawiki/entities/",
"title": "Wikidata JSON dump example snapshot",
"publisher": "Wikidata",
"retrieved_at": "2026-06-12T16:45:00Z",
"license": "CC0-1.0",
"content_hash": {
"alg": "sha256",
"value": "0303030303030303030303030303030303030303030303030303030303030303"
},
"authority_channel": {
"authority_channel_id": "authority:wikidata",
--- CHUNK END ---

--- CHUNK BEGIN ---
id=a5ff2b228c2b:351-700
start=351
end=700
----
"name": "Wikidata"
}
},
"section": "Q42 claims P569",
"evidence_status": "sufficient",
"content_hash": {
"alg": "sha256",
"value": "0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c"
}
}
],
"provenance_refs": [
{
"artifact_id": "sha256:0707070707070707070707070707070707070707070707070707070707070707",
"artifact_type": "wikidata_dump_import",
"content_hash": {
"alg": "sha256",
"value": "0808080808080808080808080808080808080808080808080808080808080808"
},
"created_at": "2026-06-12T16:50:00Z"
}
],
"authority_recognition_refs": [
{
"recognition_id": "sha256:0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d",
"recognition_status": "recognized",
"recognized_as": "institutional_reference",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
},
"scope": {
"domain": "wikidata",
"subdomain": "seed-corpus",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
}
}
],
"validation": {
"validation_status": "validated",
"validated_as": "institutional_reference",
"certainty_level": "medium",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
},
"scope": {
"domain": "wikidata",
"subdomain": "seed-corpus",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"reason_codes": [
"schema_valid",
"provenance_sufficient",
"authority_recognized",
"policy_satisfied"
],
"validation_refs": [],
"notes": "Validated as a faithful source-preserving Wikidata seed assertion under the declared import policy."
},
"uncertainty": {
"confidence": 0.8,
"method": "source-preserving seed import example",
"notes": "Certainty reflects source packaging status and Wikidata reference scope, not independent external verification."
},
"lineage": {
"source_assertions": [],
"source_artifacts": [
{
"artifact_id": "sha256:0707070707070707070707070707070707070707070707070707070707070707",
"artifact_type": "wikidata_dump_import",
"content_hash": {
"alg": "sha256",
"value": "0808080808080808080808080808080808080808080808080808080808080808"
}
}
],
"transforms": [
{
"transform_id": "transform:wikidata-seed-import-0002",
"transform_type": "normalization",
"tool": "wikidata-seed-importer-example",
"policy_ref": {
"policy_id": "kristal.v5:normalization-policy:wikidata-time-values",
"policy_version": "1"
},
"created_at": "2026-06-12T16:51:00Z",
"notes": "Normalized Wikidata time value while preserving original statement provenance."
}
]
},
"conflicts_with": [],
"supersedes": [],
"notes": "This example demonstrates preservation of Wikidata time values, rank, qualifiers, and source identity."
},
{
"assertion_id": "sha256:0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e0e",
"source_assertion_id": "wikidata:Q42:label:en",
"statement": {
"subject": {
"qid": "Q42",
"label": "Douglas Adams",
"description": "English writer and humorist",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
},
"predicate": {
"external_id": "wikibase:label",
"label": "label",
"language": "en",
"authority_channel": {
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
},
"object": {
"kind": "monolingual_text",
"value": {
"text": "Douglas Adams",
"lang": "en"
}
},
"qualifiers": [
{
"predicate": {
"external_id": "wikibase:description",
"label": "description",
"language": "en"
},
"object": {
"kind": "monolingual_text",
"value": {
"text": "English writer and humorist",
"lang": "en"
}
},
"scope": {
"domain": "wikidata",
"subdomain": "entity-labels",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
}
}
],
"rank": "not_applicable",
"statement_hash": {
"alg": "sha256",
"value": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f"
}
},
"natural_language_statement": {
"text": "The English Wikidata label for Q42 is Douglas Adams.",
"lang": "en"
},
"assertion_status": "validated",
"certainty_level": "not_applicable",
"validated_as": "publisher_declaration",
"scope": {
"domain": "wikidata",
"subdomain": "entity-labels",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"evidence_refs": [
{
"evidence_id": "evidence:wikidata:Q42:label:en",
"source_ref": {
"source_id": "source:wikidata-dump-example-20260612",
"source_type": "wikidata_dump",
"source_url": "https://dumps.wikimedia.org/wikidatawiki/entities/",
"title": "Wikidata JSON dump example snapshot",
"publisher": "Wikidata",
"retrieved_at": "2026-06-12T16:45:00Z",
"license": "CC0-1.0",
"content_hash": {
"alg": "sha256",
"value": "0303030303030303030303030303030303030303030303030303030303030303"
},
"authority_channel": {
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
},
"section": "Q42 labels.en and descriptions.en",
"evidence_status": "sufficient",
"content_hash": {
"alg": "sha256",
"value": "1010101010101010101010101010101010101010101010101010101010101010"
}
}
],
"provenance_refs": [
{
"artifact_id": "sha256:0707070707070707070707070707070707070707070707070707070707070707",
"artifact_type": "wikidata_dump_import",
"content_hash": {
"alg": "sha256",
"value": "0808080808080808080808080808080808080808080808080808080808080808"
},
"created_at": "2026-06-12T16:50:00Z"
}
],
"authority_recognition_refs": [
{
"recognition_id": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"recognition_status": "recognized",
"recognized_as": "publisher_declaration",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
},
"scope": {
"domain": "wikidata",
"subdomain": "entity-labels",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
}
}
],
"validation": {
"validation_status": "validated",
"validated_as": "publisher_declaration",
"certainty_level": "not_applicable",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
},
"scope": {
"domain": "wikidata",
"subdomain": "entity-labels",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"reason_codes": [
"schema_valid",
"provenance_sufficient",
"policy_satisfied"
],
"validation_refs": [],
"notes": "Validated as a source-preserved publisher declaration of label and description data from the Wikidata snapshot."
},
"uncertainty": {
"method": "not applicable to label declaration",
"notes": "Certainty is not applicable because this assertion records a label declaration in the source corpus, not an external factual claim."
},
"lineage": {
"source_assertions": [],
"source_artifacts": [
{
"artifact_id": "sha256:0707070707070707070707070707070707070707070707070707070707070707",
"artifact_type": "wikidata_dump_import",
"content_hash": {
"alg": "sha256",
"value": "0808080808080808080808080808080808080808080808080808080808080808"
}
}
],
"transforms": [
{
"transform_id": "transform:wikidata-label-import-0001",
"transform_type": "import",
"tool": "wikidata-seed-importer-example",
"policy_ref": {
"policy_id": "kristal.v5:import-policy:preserve-wikidata-labels-aliases-descriptions",
"policy_version": "1"
},
"created_at": "2026-06-12T16:52:00Z",
"notes": "Imported labels and descriptions as source declarations rather than physical-world claims."
}
]
},
"conflicts_with": [],
"supersedes": [],
"notes": "This example demonstrates that labels and descriptions can be preserved as publisher declarations."
}
],
"provenance": [
{
"provenance_id": "prov:wikidata-seed-import-created-0001",
"event_type": "created",
"created_at": "2026-06-12T16:50:00Z",
"agent": {
"agent_id": "agent:wikidata-seed-importer-example",
"name": "Wikidata Seed Importer Example",
"agent_type": "system",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
}
},
"source_ref": {
"source_id": "source:wikidata-dump-example-20260612",
"source_type": "wikidata_dump",
"source_url": "https://dumps.wikimedia.org/wikidatawiki/entities/",
"title": "Wikidata JSON dump example snapshot",
"publisher": "Wikidata",
"retrieved_at": "2026-06-12T16:45:00Z",
"license": "CC0-1.0",
"content_hash": {
"alg": "sha256",
"value": "0303030303030303030303030303030303030303030303030303030303030303"
},
"authority_channel": {
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
},
"policy_refs": [
{
"policy_id": "kristal.v5:import-policy:preserve-wikidata-statements",
"policy_version": "1"
--- CHUNK END ---

--- CHUNK BEGIN ---
id=a5ff2b228c2b:701-962
start=701
end=962
----
},
{
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
}
],
"notes": "Created as a Kristal-compatible packaging and alignment of Wikidata source content. This does not transform Wikidata declarations into universal truth."
},
{
"provenance_id": "prov:wikidata-seed-validated-0001",
"event_type": "validated",
"created_at": "2026-06-12T16:55:00Z",
"agent": {
"agent_id": "agent:wikidata-seed-validator-example",
"name": "Wikidata Seed Validator Example",
"agent_type": "system",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
}
},
"artifact_ref": {
"artifact_id": "sha256:0101010101010101010101010101010101010101010101010101010101010101",
"artifact_type": "structured_epistemic_state",
"content_hash": {
"alg": "sha256",
"value": "0202020202020202020202020202020202020202020202020202020202020202"
},
"created_at": "2026-06-12T17:00:00Z"
},
"policy_refs": [
{
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
}
],
"notes": "Validated as source-preserving seed packaging under the declared policy."
}
],
"review_refs": [],
"policy_refs": [
{
"policy_id": "kristal.v5:import-policy:preserve-wikidata-statements",
"policy_version": "1"
},
{
"policy_id": "kristal.v5:import-policy:preserve-wikidata-labels-aliases-descriptions",
"policy_version": "1"
},
{
"policy_id": "kristal.v5:normalization-policy:wikidata-time-values",
"policy_version": "1"
},
{
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
}
],
"authority_recognition_refs": [
{
"recognition_id": "sha256:1212121212121212121212121212121212121212121212121212121212121212",
"recognition_status": "recognized",
"recognized_as": "institutional_reference",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
},
"scope": {
"domain": "wikidata",
"subdomain": "seed-corpus",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
}
}
],
"reader_policy_refs": [
{
"reader_policy_id": "reader_policy:wikidata-seed-reference",
"mode": "validated_only"
},
{
"reader_policy_id": "reader_policy:research-all-with-labels",
"mode": "all_with_labels"
}
],
"certainty_summary": {
"counts_by_certainty_level": {
"medium": 2,
"not_applicable": 1
},
"counts_by_assertion_status": {
"validated": 3
},
"counts_by_validated_as": {
"institutional_reference": 2,
"publisher_declaration": 1
},
"notes": "This seed example distinguishes source-preserved Wikidata statements from independent external truth validation."
},
"validation_summary": {
"validation_status": "validated",
"recognition_status": "recognized",
"authority_channels": [
{
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
},
{
"authority_channel_id": "authority:wikidata",
"name": "Wikidata"
}
],
"validation_refs": [],
"recognition_refs": [
{
"recognition_id": "sha256:1212121212121212121212121212121212121212121212121212121212121212",
"recognition_status": "recognized",
"recognized_as": "institutional_reference",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
},
"scope": {
"domain": "wikidata",
"subdomain": "seed-corpus",
"jurisdiction": null,
"time_window": "2026-06-12",
"tenant_id": null,
"environment": "example",
"language": "en"
},
"validation_policy_ref": {
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
}
}
],
"reason_codes": [
"schema_valid",
"provenance_sufficient",
"authority_recognized",
"policy_satisfied"
],
"notes": "The state is validated as a Kristal-compatible Wikidata seed corpus, preserving source identity, references, qualifiers, ranks, labels, aliases, and descriptions where available."
},
"lineage": {
"source_artifacts": [
{
"artifact_id": "sha256:0707070707070707070707070707070707070707070707070707070707070707",
"artifact_type": "wikidata_dump_import",
"content_hash": {
"alg": "sha256",
"value": "0808080808080808080808080808080808080808080808080808080808080808"
},
"created_at": "2026-06-12T16:50:00Z"
}
],
"source_states": [],
"transforms": [
{
"transform_id": "transform:wikidata-seed-packaging-0001",
"transform_type": "import",
"tool": "wikidata-seed-importer-example",
"policy_ref": {
"policy_id": "kristal.v5:import-policy:preserve-wikidata-statements",
"policy_version": "1"
},
"created_at": "2026-06-12T16:50:00Z",
"notes": "Packaged Wikidata source content into Kristal-compatible Structured Epistemic State form without treating every statement as universal truth."
}
],
"compiler": {
"agent_id": "agent:wikidata-seed-compiler-example",
"name": "Wikidata Seed Compiler Example",
"agent_type": "system",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
}
},
"policy_refs": [
{
"policy_id": "kristal.v5:import-policy:preserve-wikidata-statements",
"policy_version": "1"
},
{
"policy_id": "kristal.v5:validation-policy:wikidata-seed-packaging",
"policy_version": "1"
}
]
},
"build": {
"build_id": "build:20260612T170000Z:wikidata-seed-kristal-example",
"schema_version": "5.0",
"compile_status": "succeeded",
"validation_status": "validated",
"review_status": "completed",
"recognition_status": "recognized",
"publication_status": "not_published",
"activation_status": "not_applicable",
"working_outputs": [],
"reference_outputs": [
{
"artifact_id": "sha256:0101010101010101010101010101010101010101010101010101010101010101",
"artifact_type": "structured_epistemic_state",
"content_hash": {
"alg": "sha256",
"value": "0202020202020202020202020202020202020202020202020202020202020202"
},
"created_at": "2026-06-12T17:00:00Z"
}
],
"reason_codes": [
"schema_valid",
"provenance_sufficient",
"policy_satisfied"
],
"created_at": "2026-06-12T17:00:00Z"
},
"warnings": [
{
"code": "AUTHORITY_CHANNEL_MISSING",
"message": "Some upstream Wikidata references may not map one-to-one to a Kristal authority channel in a complete import. This example keeps authority explicit at the seed and source level.",
"path": "/source_refs/0",
"reason_code": "authority_recognized"
}
],
"extensions": {
"example_purpose": "Demonstrates a Wikidata seed Kristal as source-preserving packaging and alignment, not as a transformation of all statements into universal truth.",
"wikidata_preservation_targets": [
"entities",
"properties",
"statements",
"qualifiers",
"references",
"ranks",
"labels",
"aliases",
"descriptions"
],
"reabsorption_note": "A future Wikidata-facing exporter may emit changes or additions from Kristal back into Wikidata-compatible formats, subject to Wikidata contribution rules and external review."
},
"signatures": [
{
"key_id": "kristal_wikidata_seed_example_ed25519_v1",
"alg": "ed25519",
"signature": "ZHVtbXktc2lnbmF0dXJlLWJ5dGVz",
"created_at": "2026-06-12T17:00:10Z",
"authority_channel": {
"authority_channel_id": "authority:kristal-wikidata-seed-example",
"name": "Kristal Wikidata Seed Example"
}
}
]
}
--- CHUNK END ---
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/GitSink.bat"
id=180434040cf8
kind=source
size=781
lines=33
line_ref=1-33
chunks=0
chunk_refs=
summary="Source file."
----
000001 | @echo off
000002 | REM Check if a commit message was provided as an argument
000003 | if "%1"=="" (
000004 |     set /p "commit_message=Enter commit message (e.g., 'Minor fix'): "
000005 | ) else (
000006 |     set commit_message=%1
000007 | )
000008 | 
000009 | echo.
000010 | echo =================================
000011 | echo Starting Git Commit and Push...
000012 | echo Commit Message: "%commit_message%"
000013 | echo =================================
000014 | echo.
000015 | 
000016 | REM Add all changes to the staging area
000017 | echo Running: git add .
000018 | call git add .
000019 | 
000020 | REM Commit the changes
000021 | echo Running: git commit -m "%commit_message%"
000022 | call git commit -m "%commit_message%"
000023 | 
000024 | REM Push the changes to the remote repository
000025 | echo Running: git push
000026 | call git push
000027 | 
000028 | echo.
000029 | echo =================================
000030 | echo Git process complete!
000031 | echo =================================
000032 | 
000033 | pause
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/LICENSE"
id=c793b5606fb7
kind=source
size=694
lines=14
line_ref=1-14
chunks=0
chunk_refs=
summary="Source file."
----
000001 | Copyright (C) 2026 Réjean McCormick or owner of this repo
000002 | 
000003 | Kristal is free software: you can redistribute it and/or modify
000004 | it under the terms of the GNU Affero General Public License as published
000005 | by the Free Software Foundation, either version 3 of the License, or
000006 | (at your option) any later version.
000007 | 
000008 | Kristal is distributed in the hope that it will be useful,
000009 | but WITHOUT ANY WARRANTY; without even the implied warranty of
000010 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
000011 | GNU Affero General Public License for more details.
000012 | 
000013 | You should have received a copy of the GNU Affero General Public License
000014 | along with this program. If not, see <https://www.gnu.org/licenses/>.
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/mkdocs.yml"
id=c462e3498d96
kind=source
size=1817
lines=64
line_ref=1-64
chunks=0
chunk_refs=
summary="Source file."
----
000001 | site_name: Kristals Documentation
000002 | site_description: Technical documentation for Kristals (enhanced Wikidata/Orgo-aligned knowledge artifacts)
000003 | site_author: Réjean McCormick
000004 | repo_name: kristal-framework
000005 | repo_url: https://example.com/kristal-framework
000006 | edit_uri: ""
000007 | 
000008 | theme:
000009 |   name: material
000010 |   language: en
000011 |   features:
000012 |     - navigation.sections
000013 |     - navigation.indexes
000014 |     - navigation.top
000015 |     - toc.integrate
000016 |     - content.code.copy
000017 |     - search.suggest
000018 |     - search.highlight
000019 | 
000020 | markdown_extensions:
000021 |   - admonition
000022 |   - attr_list
000023 |   - footnotes
000024 |   - def_list
000025 |   - tables
000026 |   - toc:
000027 |       permalink: true
000028 |   - pymdownx.highlight
000029 |   - pymdownx.superfences
000030 |   - pymdownx.inlinehilite
000031 |   - pymdownx.details
000032 | 
000033 | plugins:
000034 |   - search
000035 | 
000036 | nav:
000037 |   - Home: README.md
000038 | 
000039 |   - Introduction:
000040 |       - docs/en/introduction.md
000041 | 
000042 |   - Specification:
000043 |       - Format (Kristal): docs/en/specification/format_kristal.md
000044 |       - SPARQL & Queries: docs/en/specification/sparql_queries.md
000045 |       - Ontology & Contexts: docs/en/specification/ontology_contexts.md
000046 | 
000047 |   - Architecture:
000048 |       - Components: docs/en/architecture/components.md
000049 |       - Sentient Pipeline: docs/en/architecture/sentient_pipeline.md
000050 | 
000051 |   - Tutorials:
000052 |       - Download a Kristal: docs/en/tutorials/download_kristal.md
000053 |       - Edit a Kristal: docs/en/tutorials/edit_kristal.md
000054 |       - Reload a Kristal: docs/en/tutorials/reload_kristal.md
000055 | 
000056 |   - Contributors:
000057 |       - Propose a Change: docs/en/contributors/propose_change.md
000058 |       - Test a Kristal: docs/en/contributors/test_kristal.md
000059 |       - Validate a Version: docs/en/contributors/validate_version.md
000060 | 
000061 |   - Use Cases:
000062 |       - Botanist: docs/en/use_cases/botanist.md
000063 |       - Historian: docs/en/use_cases/historian.md
000064 |       - Offline Researcher: docs/en/use_cases/offline_researcher.md
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework/README.md"
id=e81fe850384f
kind=markdown
size=14111
lines=375
line_ref=1-375
chunks=2
chunk_refs=1-350,351-375
summary="Markdown documentation."

--- CHUNK BEGIN ---
id=e81fe850384f:1-350
start=1
end=350
----
# Kristal docs (v5)

This repository contains the documentation set for **Kristal v5**, a deterministic, portable epistemic artifact system.

Kristal v5 defines how **Structured Epistemic States** are compiled into immutable, portable, queryable, and verifiable artifacts while separating:

* **artifact existence** from **artifact integrity**
* **compilation** from **validation**
* **working artifacts** from **reference artifacts**
* **assertion status** from **certainty level**
* **validation status** from **authority recognition**
* **authority recognition** from **reader visibility**
* **distribution** from **runtime activation**

Kristal is designed for portable, verifiable, offline-capable knowledge operation across toolchains, authority channels, reader policies, and runtime environments.

---

## Start here

1. `00-overview/what-is-kristal-v5.md`
2. `00-overview/vision-and-scope.md`
3. `00-overview/validation-certainty-and-authority.md`
4. `00-overview/plural-validation-and-federated-authority.md`
5. `00-overview/conformance-and-alignment.md`
6. `01-core-spec/kristal-v5-core-spec.md`

If you are implementing specific surfaces:

* Core model, artifact lifecycle, and validation boundaries → `01-core-spec/kristal-v5-core-spec.md`
* Structured Epistemic State → `01-core-spec/structured-epistemic-state.md`
* Assertion status and certainty → `01-core-spec/assertion-status-and-certainty.md`
* Authority recognition → `01-core-spec/authority-recognition.md`
* IDs, technical canonicalization, and hashing → `01-core-spec/ids-canonicalization-hashing.md`
* Signatures and trust roots → `01-core-spec/signatures-trust.md`
* Normative JSON Schemas → `02-schemas/`
* Reproducibility and build surfaces → `03-reproducibility/`
* Offline query surface → `04-query/query-contract.md`
* Reader policy profiles → `04-query/reader-policy-profiles.md`
* Optional interoperability profiles → `05-profiles/`
* Ecosystem contracts: Orgo, SenTient, Architect, Konnaxion → `06-integration/`
* Security, trust roots, downgrade policy, rollback policy, and multi-tenancy → `07-security/`
* Operational guidance → `08-ops/`
* Golden vectors and fixtures → `09-test-vectors/`
* Worked examples → `10-examples/`

---

## What Kristal v5 is

Kristal v5 is a deterministic artifact system for compiling structured epistemic work.

It allows claims, hypotheses, references, myths, fictional corpora, technical declarations, research claims, institutional corpora, and disputed positions to coexist without confusion.

Core principles:

* **Validation is scoped.**
* **Authority is plural.**
* **Certainty is explicit.**
* **Readers choose policy.**
* **Federation preserves disagreement.**
* **Integrity protects artifacts.**

A Kristal may contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.

A Kristal must not present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.

---

## Core model

Kristal v5 keeps the following concepts separate:

```text
artifact existence
≠ artifact integrity
≠ assertion status
≠ certainty level
≠ validation status
≠ authority recognition
≠ reader visibility
≠ runtime activation
```

This separation is the basis for v5 conformance.

An artifact can be well-formed, signed, content-addressed, reproducible, queryable, and distributable while still containing assertions that are hypothetical, disputed, fictional, mythological, low-certainty, rejected by one authority channel, recognized by another, or hidden by a reader policy.

---

## Core pipeline

The v5 model is:

```text
Signal / Draft / Dataset / Submission
-> Structured Epistemic State
-> Compile
-> Working Artifact
-> Review / Validation / Attestation / Federation
-> Authority Recognition
-> Reference Artifact
-> Distribution / Runtime Pack / Reader Policy
```

Compilation creates portable artifacts.

Validation evaluates assertions, artifacts, or datasets under declared policy and scope.

Authority recognition records which authority channel recognizes what, for which scope, and under which policy.

Reader policy determines what a reader or runtime is allowed to see.

---

## Input model

The normative input unit for Kristal v5 is the **Structured Epistemic State**.

`Claim-IR` may be used by extractors, resolvers, or ingestion pipelines, but it is not the universal required input boundary for Kristal v5.

A conformant v5 pipeline may compile from:

* Structured Epistemic State
* extractor proposals projected into Structured Epistemic State
* institutional datasets
* research submissions
* local notes
* mythology or fiction corpora
* technical declarations
* authority-recognized reference artifacts
* federated shard inputs

All inputs must make their provenance, scope, certainty, and validation metadata explicit when those fields are applicable.

---

## Artifact classes

Kristal v5 distinguishes at least the following artifact classes.

### 1. Structured Epistemic State

A schema-constrained, versioned, provenance-bearing assertional state suitable for compilation.

Typical contents:

* identity and revision metadata
* scope and tenant metadata where applicable
* assertions
* assertion status
* certainty level
* validation metadata
* authority recognition references
* provenance references
* evidence references
* lineage
* review or attestation references

### 2. Working Exchange

A compiled artifact representing a working epistemic state.

Properties:

* immutable
* content-addressed
* queryable
* portable
* reproducible within its declared surface
* explicitly marked as `working`

A Working Exchange may contain unvalidated, disputed, low-certainty, fictional, mythological, speculative, or incomplete assertions when those statuses are explicit.

### 3. Reference Exchange

An Exchange recognized for one or more declared scopes by one or more authority channels.

A Reference Exchange does not imply universal agreement or universal certainty. It means the artifact has been accepted as a reference under declared authority, validation, certainty, and scope constraints.

### 4. Validation Report

A scoped artifact recording validation findings, validation status, certainty level, validated-as classification, policy references, and evidence references.

A validation report may validate an assertion, artifact, shard, dataset, runtime pack, authority channel, reader policy, or federation surface.

### 5. Authority Recognition

An artifact recording recognition by an authority channel.

Authority recognition is scoped. It may be conditional, disputed, deprecated, revoked, rejected, or limited to a domain, jurisdiction, environment, tenant, language, or time window.

### 6. Federation Manifest

A manifest describing composition across shards, authority channels, reader policies, validation policies, and disagreement-preserving federation rules.

Federation does not erase disagreement. It preserves source identity, authority channel, scope, status, certainty, and validation metadata.

### 7. Runtime Pack

An offline-capable runtime/query representation derived from an Exchange or shard set.

A Runtime Pack must preserve source artifact status, reader policy constraints, validation labels, certainty labels, authority labels, and lineage.

---

## Trust and recognition model

Kristal v5 separates **artifact integrity** from **authority recognition**.

Integrity asks:

* Is the artifact well-formed?
* Does the hash match?
* Does the signature verify?
* Are the declared technical canonicalization and hashing rules satisfied?
* Is the artifact reproducible under its declared build surface?

Authority recognition asks:

* Which authority channel recognizes this artifact, assertion, dataset, shard, or policy?
* Under what scope?
* Under what validation policy?
* At what certainty level?
* As what kind of assertion or corpus?
* With what status?
* With what revocation or supersession rules?

Reader visibility asks:

* Which reader policy is active?
* Which statuses are allowed?
* Which authorities are allowed?
* Which certainty levels are allowed?
* Which domains and scopes are allowed?
* Which labels must remain visible?

Kristal v5 does not flatten these layers into a single status.

---

## Reader policies

Reader policies determine what material is visible or usable for a reader, runtime, export, or rendering surface.

Standard reader modes include:

* `reference_only`
* `validated_only`
* `high_certainty_only`
* `research`
* `creative`
* `all_with_labels`
* `custom`

A validated-only reader policy does not mean every visible assertion is a universal fact. It means every visible assertion satisfies that reader policy’s validation, authority, certainty, and scope filters.

For example, a validated-only reader policy may include:

* high-confidence scientific facts
* institutional references
* publisher declarations
* technical specifications
* legal or policy positions
* mythological corpora
* fictional corpora
* symbolic models
* disputed positions

provided those assertions are explicitly validated as such under the active policy.

---

## Conformance model

### v5 Core

Implementations claiming **Kristal v5 Core** conformance must, at minimum:

* support Structured Epistemic State as the normative input unit
* distinguish working artifacts from reference artifacts
* distinguish artifact status from assertion status
* distinguish certainty level from validation status
* distinguish validation status from authority recognition
* distinguish authority recognition from reader visibility
* support deterministic compilation within the declared reproducibility surface
* use the declared technical canonicalization and hashing rules for identity-bearing artifacts
* preserve traceability from compiled artifacts back to provenance-bearing source states
* preserve validation labels, certainty labels, authority labels, scope labels, and lineage
* produce manifests recording build-affecting configuration, policy, source identity, and compiler identity
* enforce required verification where hashes, signatures, trust roots, revocation checks, or runtime activation rules are declared as mandatory
* pass the core test vectors in `09-test-vectors/`

### Profiles

Advanced capabilities are expressed as explicit profiles in `05-profiles/`.

Implementations may claim profile conformance individually, including profiles such as:

* JSON-LD export
* RDF integrity and RDF dataset canonicalization
* Wikidata/Wikibase export
* SHACL validation
* ShEx validation
* provenance packaging
* transparency logs
* query pagination

Profiles must:

* state requirements and limits
* state what is hashed, signed, or identity-bearing
* state whether they affect reproducibility surfaces
* include conformance tests or fixtures where applicable
* preserve Kristal v5 labels for status, certainty, validation, authority, scope, and lineage

---

## Repository structure

* `00-overview/` — scope, concepts, conformance, federation, authority, and ecosystem placement
* `01-core-spec/` — normative core specification, artifact model, status model, authority model, signatures, IDs, and hashing
* `02-schemas/` — normative JSON Schemas for v5 artifacts
* `03-reproducibility/` — deterministic compilation rules, identity surfaces, runtime pack policies, and acceptance tests
* `04-query/` — offline query contract and reader policy profiles
* `05-profiles/` — optional standardized profiles
* `06-integration/` — inter-system contracts for Orgo, SenTient, Architect, and Konnaxion
* `07-security/` — trust roots, key management, downgrade and rollback policy, and multi-tenancy boundaries
* `08-ops/` — operational guidance and release patterns
* `09-test-vectors/` — golden vectors for canonicalization, hashing, manifests, and identity-bearing surfaces
* `10-examples/` — worked examples for implementers

---

## Editing rules

* Normative language uses **MUST**, **SHOULD**, **MAY**, **MUST NOT**, and **SHOULD NOT**.
* Keep the core small and explicit.
* Do not hide optional behavior inside undocumented extensions.
* Any optional behavior that affects identity, trust, reproducibility, query semantics, reader visibility, or distribution must be expressed as a profile or an explicitly versioned core rule.
* Do not conflate:

  * compile with validate
  * working with reference
  * validation with authority recognition
  * authority recognition with reader visibility
  * certainty with validation status
  * artifact integrity with assertion validity
  * technical canonicalization with epistemic authority

--- CHUNK END ---

--- CHUNK BEGIN ---
id=e81fe850384f:351-375
start=351
end=375
----
---

## Versioning

Any change that affects hashes, IDs, deterministic outputs, schema semantics, validation semantics, authority recognition, reader policy behavior, runtime activation, or trust-surface behavior requires:

* updated test vectors in `09-test-vectors/`
* an explicit version bump in the relevant schema, profile, policy, or artifact identifier
* compatibility guidance where applicable
* clear notes explaining the affected conformance surface

Major-version changes are required for changes that alter:

* core artifact classes
* identity-bearing technical canonicalization or hashing rules
* compile, validation, or recognition semantics
* trust-surface semantics
* reader policy semantics
* runtime compatibility guarantees

---

## One-sentence definition

> Kristal v5 is a deterministic, portable epistemic artifact system that compiles Structured Epistemic States into verifiable artifacts while keeping validation scoped, authority plural, certainty explicit, reader policy selectable, and disagreement preserved.
--- CHUNK END ---
----- FILE END -----

===== END VOLUME Kristal_20260612_183335_01_kristal-framework.txt =====


===== BEGIN VOLUME Kristal_20260612_183335_02_kristal-framework.wiki.txt :: FOLDER: kristal-framework.wiki =====
==== VOLUME META ====
generated_at: 2026-06-12T18:33:36.000190
title: FOLDER: kristal-framework.wiki
root_dir: C:\mycode\Kristal
file_count: 32
total_size_mb: 0.0604
home: 00_START_HERE.instructions.md
prev_volume: Kristal_20260612_183335_01_kristal-framework.txt
prev_title: kristal-framework
next_title: 
short_title: kristal-framework.wiki

==== FILE_INDEX ====
ENTRY id=6478a1fbeaac path="kristal-framework.wiki/_Footer.md" kind=markdown size=528 lines=9 line_ref=1-9 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=e176a8ee61d1 path="kristal-framework.wiki/_Sidebar.md" kind=markdown size=931 lines=44 line_ref=1-44 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=e5eb200d511c path="kristal-framework.wiki/Artifact-Authority-Registry.md" kind=markdown size=2198 lines=93 line_ref=1-93 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=8d5a9c272697 path="kristal-framework.wiki/Artifact-Exchange.md" kind=markdown size=2310 lines=91 line_ref=1-91 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=a1dd68c786ee path="kristal-framework.wiki/Artifact-Federation-Manifest.md" kind=markdown size=2046 lines=68 line_ref=1-68 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=ce1b864c0d75 path="kristal-framework.wiki/Artifact-Runtime-Pack.md" kind=markdown size=2050 lines=80 line_ref=1-80 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=a16d8db4f60d path="kristal-framework.wiki/Artifact-Shard-Manifest.md" kind=markdown size=1845 lines=63 line_ref=1-63 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=37c529bfbad1 path="kristal-framework.wiki/Artifact-Validation-Report.md" kind=markdown size=1798 lines=84 line_ref=1-84 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=8439669af8b4 path="kristal-framework.wiki/Artifacts.md" kind=markdown size=2908 lines=98 line_ref=1-98 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=f8f4059883f7 path="kristal-framework.wiki/Concepts-and-Mental-Model.md" kind=markdown size=3294 lines=113 line_ref=1-113 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=e2e3f636dab0 path="kristal-framework.wiki/FAQ.md" kind=markdown size=3055 lines=45 line_ref=1-45 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=1aac360d48b5 path="kristal-framework.wiki/Getting-Started.md" kind=markdown size=2582 lines=85 line_ref=1-85 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=fe217bc7e8fa path="kristal-framework.wiki/GitSink.bat" kind=source size=750 lines=33 line_ref=1-33 chunks=0 chunk_refs= symbols=0 imports=0 summary="Source file."
ENTRY id=374da005ac9e path="kristal-framework.wiki/Glossary.md" kind=markdown size=3885 lines=80 line_ref=1-80 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=0bcc3c149b08 path="kristal-framework.wiki/Home.md" kind=markdown size=2711 lines=85 line_ref=1-85 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=6770a0a26b4c path="kristal-framework.wiki/Identity-and-Determinism.md" kind=markdown size=2893 lines=101 line_ref=1-101 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=e0dc9271943f path="kristal-framework.wiki/Operations-Compatibility.md" kind=markdown size=2191 lines=82 line_ref=1-82 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=b0a79527eed2 path="kristal-framework.wiki/Operations-Observability-and-Troubleshooting.md" kind=markdown size=2278 lines=103 line_ref=1-103 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=6808747f544c path="kristal-framework.wiki/Operations-Release-Strategy.md" kind=markdown size=1293 lines=76 line_ref=1-76 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=a951160d8094 path="kristal-framework.wiki/Operations.md" kind=markdown size=1255 lines=51 line_ref=1-51 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=229f916608aa path="kristal-framework.wiki/Query-Basics.md" kind=markdown size=1439 lines=63 line_ref=1-63 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=f53751c29c4b path="kristal-framework.wiki/Query-Pagination-and-Capabilities.md" kind=markdown size=1331 lines=59 line_ref=1-59 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=6af37cf02ff3 path="kristal-framework.wiki/Query.md" kind=markdown size=1355 lines=70 line_ref=1-70 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=405becb17dd6 path="kristal-framework.wiki/Quickstart.md" kind=markdown size=2452 lines=123 line_ref=1-123 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=da12fe38fd09 path="kristal-framework.wiki/Trust-Authority-and-Signatures.md" kind=markdown size=2144 lines=89 line_ref=1-89 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=61d912555f6d path="kristal-framework.wiki/What-is-Kristal.md" kind=markdown size=2607 lines=91 line_ref=1-91 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=4ee7c65bf280 path="kristal-framework.wiki/Workflow-Activate-Rollback-Downgrade.md" kind=markdown size=1663 lines=79 line_ref=1-79 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=1560badba1b6 path="kristal-framework.wiki/Workflow-Build-and-Validate.md" kind=markdown size=2084 lines=96 line_ref=1-96 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=5e2fea8796e9 path="kristal-framework.wiki/Workflow-Federation-and-Curation.md" kind=markdown size=1749 lines=86 line_ref=1-86 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=351582445e14 path="kristal-framework.wiki/Workflow-Publish-and-Distribute.md" kind=markdown size=1772 lines=84 line_ref=1-84 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=2410faa9c84a path="kristal-framework.wiki/Workflow-Subsets-Recipes.md" kind=markdown size=1166 lines=68 line_ref=1-68 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."
ENTRY id=1543f894e134 path="kristal-framework.wiki/Workflows.md" kind=markdown size=804 lines=39 line_ref=1-39 chunks=0 chunk_refs= symbols=0 imports=0 summary="Markdown documentation."

==== FILES ====

----- FILE BEGIN -----
path="kristal-framework.wiki/_Footer.md"
id=6478a1fbeaac
kind=markdown
size=528
lines=9
line_ref=1-9
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | _Last updated:_ 2026-06-12 · _Kristal Framework Wiki_
000002 | 
000003 | - Source repo: https://github.com/Rejean-McCormick/kristal-framework
000004 | - Technical docs: `docs/Technical-Reference/kristal-docs-v5/`
000005 | - Schemas: `docs/Technical-Reference/kristal-docs-v5/02-schemas/`
000006 | - Examples: `docs/Technical-Reference/kristal-docs-v5/10-examples/`
000007 | - Issues / feedback: https://github.com/Rejean-McCormick/kristal-framework/issues
000008 | 
000009 | > This wiki is operational and product-oriented. For normative requirements, use the Kristal v5 technical docs and schemas.
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/_Sidebar.md"
id=e176a8ee61d1
kind=markdown
size=931
lines=44
line_ref=1-44
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Kristal Wiki
000002 | 
000003 | ## Démarrer
000004 | - [[Home]]
000005 | - [[Getting-Started]]
000006 | - [[Quickstart]]
000007 | - [[Glossary]]
000008 | 
000009 | ## Comprendre Kristal v5
000010 | - [[What-is-Kristal]]
000011 | - [[Concepts-and-Mental-Model]]
000012 | - [[Identity-and-Determinism]]
000013 | - [[Trust-Authority-and-Signatures]]
000014 | 
000015 | ## Artefacts
000016 | - [[Artifacts]]
000017 | - [[Artifact-Exchange]]
000018 | - [[Artifact-Runtime-Pack]]
000019 | - [[Artifact-Validation-Report]]
000020 | - [[Artifact-Shard-Manifest]]
000021 | - [[Artifact-Federation-Manifest]]
000022 | - [[Artifact-Authority-Registry]]
000023 | 
000024 | ## Workflows
000025 | - [[Workflows]]
000026 | - [[Workflow-Build-and-Validate]]
000027 | - [[Workflow-Publish-and-Distribute]]
000028 | - [[Workflow-Activate-Rollback-Downgrade]]
000029 | - [[Workflow-Subsets-Recipes]]
000030 | - [[Workflow-Federation-and-Curation]]
000031 | 
000032 | ## Query & reader policy
000033 | - [[Query]]
000034 | - [[Query-Basics]]
000035 | - [[Query-Pagination-and-Capabilities]]
000036 | 
000037 | ## Ops
000038 | - [[Operations]]
000039 | - [[Operations-Release-Strategy]]
000040 | - [[Operations-Observability-and-Troubleshooting]]
000041 | - [[Operations-Compatibility]]
000042 | 
000043 | ## Support
000044 | - [[FAQ]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Artifact-Authority-Registry.md"
id=e5eb200d511c
kind=markdown
size=2198
lines=93
line_ref=1-93
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Artifact: Authority Registry
000002 | 
000003 | The **Authority Registry** defines authority channels, trust roots, validation policies, recognition policies, and scoped rules used to decide which authorities are acceptable for which purposes.
000004 | 
000005 | It is the policy artifact that makes plural authority usable without hiding disagreement.
000006 | 
000007 | ---
000008 | 
000009 | ## What it is
000010 | 
000011 | A versioned, content-addressed registry that records:
000012 | 
000013 | - authority channels;
000014 | - trust roots;
000015 | - validation policies;
000016 | - recognition policies;
000017 | - revocation references;
000018 | - scope rules;
000019 | - signature material.
000020 | 
000021 | ---
000022 | 
000023 | ## Why it exists
000024 | 
000025 | Kristal v5 assumes authority is plural.
000026 | 
000027 | Different groups, institutions, communities, validators, publishers, and research collectives may recognize different artifacts or assertions for different scopes.
000028 | 
000029 | The Authority Registry makes those boundaries explicit.
000030 | 
000031 | ---
000032 | 
000033 | ## What it contains
000034 | 
000035 | ### Authority channels
000036 | 
000037 | Authority channels identify who is making a validation, recognition, publication, or policy decision.
000038 | 
000039 | Examples:
000040 | 
000041 | - individual;
000042 | - community;
000043 | - research collective;
000044 | - academic institution;
000045 | - standards body;
000046 | - company;
000047 | - government;
000048 | - intergovernmental organization;
000049 | - AI validator;
000050 | - hybrid collective.
000051 | 
000052 | ### Trust roots
000053 | 
000054 | Trust roots anchor verification for signatures and recognition.
000055 | 
000056 | ### Policies
000057 | 
000058 | The registry may include or reference:
000059 | 
000060 | - validation policies;
000061 | - recognition policies;
000062 | - revocation policies;
000063 | - delegation rules;
000064 | - scope rules.
000065 | 
000066 | ---
000067 | 
000068 | ## How consumers use it
000069 | 
000070 | A consumer typically:
000071 | 
000072 | 1. loads the authority registry referenced by an artifact, shard, federation, or local configuration;
000073 | 2. identifies the active authority channel and scope;
000074 | 3. verifies signatures and trust roots where required;
000075 | 4. checks whether the authority is recognized for the target domain/scope;
000076 | 5. applies the active reader policy.
000077 | 
000078 | ---
000079 | 
000080 | ## Related pages
000081 | 
000082 | - [[Trust-Authority-and-Signatures]]
000083 | - [[Artifact-Federation-Manifest]]
000084 | - [[Artifact-Shard-Manifest]]
000085 | - [[Artifact-Validation-Report]]
000086 | 
000087 | ---
000088 | 
000089 | ## Technical details
000090 | 
000091 | - Schema: `kristal-docs-v5/02-schemas/authority-registry.schema.json`
000092 | - Example: `kristal-docs-v5/10-examples/authority-registry.example.json`
000093 | - Core spec: `kristal-docs-v5/01-core-spec/authority-recognition.md`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Artifact-Exchange.md"
id=8d5a9c272697
kind=markdown
size=2310
lines=91
line_ref=1-91
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Artifact: Exchange
000002 | 
000003 | An **Exchange** is a compiled Kristal artifact.
000004 | 
000005 | It may be a **Working Exchange** or a **Reference Exchange**.
000006 | 
000007 | A Working Exchange is portable, immutable, content-addressed, and queryable, but it may contain unvalidated, disputed, low-certainty, fictional, mythological, speculative, or incomplete assertions when those statuses are explicit.
000008 | 
000009 | A Reference Exchange is recognized under one or more authority channels for declared scopes.
000010 | 
000011 | ---
000012 | 
000013 | ## What it is for
000014 | 
000015 | Use an Exchange when you need:
000016 | 
000017 | - a portable compiled artifact;
000018 | - stable content identity;
000019 | - reproducible build metadata;
000020 | - queryable assertion payloads;
000021 | - preserved provenance and evidence references;
000022 | - validation, certainty, authority, and scope labels;
000023 | - a source artifact for Runtime Packs.
000024 | 
000025 | ---
000026 | 
000027 | ## What it contains conceptually
000028 | 
000029 | An Exchange typically records:
000030 | 
000031 | - artifact identity and status;
000032 | - technical canonicalization and hashing metadata;
000033 | - source Structured Epistemic State or input references;
000034 | - build metadata;
000035 | - assertions or compiled payload references;
000036 | - validation report references;
000037 | - authority recognition references;
000038 | - reader policy references;
000039 | - lineage and provenance;
000040 | - signatures where applicable.
000041 | 
000042 | ---
000043 | 
000044 | ## Working vs Reference Exchange
000045 | 
000046 | ### Working Exchange
000047 | 
000048 | Used for drafting, review, research, internal collaboration, partial validation, disputed positions, or material awaiting authority recognition.
000049 | 
000050 | ### Reference Exchange
000051 | 
000052 | Used when an authority channel recognizes the artifact for a declared scope.
000053 | 
000054 | Reference status is scoped. It does not imply universal truth or universal agreement.
000055 | 
000056 | ---
000057 | 
000058 | ## Who produces and consumes it
000059 | 
000060 | **Produced by**
000061 | 
000062 | - compiler/build pipeline;
000063 | - ingestion workflows;
000064 | - federation or shard builders.
000065 | 
000066 | **Consumed by**
000067 | 
000068 | - validators;
000069 | - Runtime Pack builders;
000070 | - query services;
000071 | - renderers;
000072 | - Konnaxion distribution/activation flows;
000073 | - authority and governance workflows.
000074 | 
000075 | ---
000076 | 
000077 | ## Related pages
000078 | 
000079 | - [[Artifacts]]
000080 | - [[Artifact-Runtime-Pack]]
000081 | - [[Artifact-Validation-Report]]
000082 | - [[Trust-Authority-and-Signatures]]
000083 | - [[Workflow-Build-and-Validate]]
000084 | 
000085 | ---
000086 | 
000087 | ## Technical details
000088 | 
000089 | - Schema: `kristal-docs-v5/02-schemas/exchange-manifest.schema.json`
000090 | - Example: `kristal-docs-v5/10-examples/exchange.example.json`
000091 | - Core spec: `kristal-docs-v5/01-core-spec/kristal-v5-core-spec.md`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Artifact-Federation-Manifest.md"
id=a1dd68c786ee
kind=markdown
size=2046
lines=68
line_ref=1-68
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Artifact: Federation Manifest
000002 | 
000003 | A **Federation Manifest** defines deterministic composition across shards, authority channels, validation policies, reader policies, and disagreement-preserving rules.
000004 | 
000005 | Federation does not rewrite shards or erase disagreement. It preserves shard identity, source authority, validation status, certainty level, and scope.
000006 | 
000007 | ---
000008 | 
000009 | ## What it is for
000010 | 
000011 | Use a Federation Manifest when you need to:
000012 | 
000013 | - combine multiple shards into one federated Kristal view;
000014 | - preserve the authority channel behind each shard;
000015 | - expose different views through reader policies;
000016 | - keep conflicts visible rather than silently resolving them;
000017 | - update one shard without rebuilding every other shard;
000018 | - distribute a single composition entrypoint.
000019 | 
000020 | ---
000021 | 
000022 | ## What it contains conceptually
000023 | 
000024 | A Federation Manifest typically records:
000025 | 
000026 | - federation identity;
000027 | - shard references;
000028 | - shard scopes;
000029 | - authority channel references;
000030 | - validation report references;
000031 | - authority recognition references;
000032 | - reader policy references;
000033 | - validation policy references;
000034 | - composition policy;
000035 | - trust requirements;
000036 | - publisher signatures;
000037 | - optional conflict summaries.
000038 | 
000039 | ---
000040 | 
000041 | ## Conflict strategy
000042 | 
000043 | Kristal v5’s default federation strategy is:
000044 | 
000045 | ```text
000046 | preserve_disagreement
000047 | ```
000048 | 
000049 | This means a federation may contain multiple claims or positions about the same topic when their authority, certainty, validation status, or scope differs.
000050 | 
000051 | Reader policies decide which material is visible.
000052 | 
000053 | ---
000054 | 
000055 | ## Relationship to other artifacts
000056 | 
000057 | - **Shard Manifest**: referenced by the federation.
000058 | - **Authority Registry**: defines which authority channels are acceptable.
000059 | - **Validation Report**: records validation findings for shards or the federation.
000060 | - **Reader Policy**: selects which federated material is visible.
000061 | 
000062 | ---
000063 | 
000064 | ## Technical details
000065 | 
000066 | - Schema: `kristal-docs-v5/02-schemas/exchange-federation-manifest.schema.json`
000067 | - Example: `kristal-docs-v5/10-examples/exchange-federation-manifest.example.json`
000068 | - Overview: `kristal-docs-v5/00-overview/sharding-and-federation.md`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Artifact-Runtime-Pack.md"
id=ce1b864c0d75
kind=markdown
size=2050
lines=80
line_ref=1-80
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Artifact: Runtime Pack
000002 | 
000003 | A **Runtime Pack** is an offline-capable runtime/query artifact derived from an Exchange or shard set.
000004 | 
000005 | It is optimized for activation and query performance while preserving the Kristal v5 labels needed for validation, certainty, authority, scope, provenance, and reader policy.
000006 | 
000007 | ---
000008 | 
000009 | ## What it is for
000010 | 
000011 | Use a Runtime Pack when you need to:
000012 | 
000013 | - activate a Kristal in a local or service runtime;
000014 | - serve queries efficiently;
000015 | - support offline operation;
000016 | - record runtime policies that affect reproducibility;
000017 | - preserve labels required by reader policies;
000018 | - support safe rollout, rollback, and compatibility checks.
000019 | 
000020 | ---
000021 | 
000022 | ## What it contains conceptually
000023 | 
000024 | A Runtime Pack typically includes:
000025 | 
000026 | - manifest identity;
000027 | - source Exchange or federation reference;
000028 | - source artifact status;
000029 | - data files;
000030 | - indexes and auxiliary structures;
000031 | - query contract reference;
000032 | - reader policy references;
000033 | - runtime policies;
000034 | - validation and authority labels;
000035 | - integrity and signature metadata.
000036 | 
000037 | ---
000038 | 
000039 | ## What it must preserve
000040 | 
000041 | Runtime Pack construction must preserve or faithfully index:
000042 | 
000043 | - artifact status;
000044 | - assertion status;
000045 | - validation status;
000046 | - certainty level;
000047 | - `validated_as`;
000048 | - authority channel;
000049 | - recognition status;
000050 | - scope;
000051 | - provenance references;
000052 | - evidence references;
000053 | - lineage.
000054 | 
000055 | A Runtime Pack must not flatten scoped validation into universal truth.
000056 | 
000057 | ---
000058 | 
000059 | ## Activation
000060 | 
000061 | Runtime activation is separate from artifact existence and validation.
000062 | 
000063 | A pack may exist and verify technically, but still be unavailable under a deployment’s reader policy, authority policy, environment, tenant, or rollback constraints.
000064 | 
000065 | ---
000066 | 
000067 | ## Related pages
000068 | 
000069 | - [[Artifact-Exchange]]
000070 | - [[Query-Basics]]
000071 | - [[Workflow-Activate-Rollback-Downgrade]]
000072 | - [[Operations-Release-Strategy]]
000073 | 
000074 | ---
000075 | 
000076 | ## Technical details
000077 | 
000078 | - Schema: `kristal-docs-v5/02-schemas/runtime-pack-manifest.schema.json`
000079 | - Example: `kristal-docs-v5/10-examples/runtime-pack-manifest.example.json`
000080 | - Runtime policies: `kristal-docs-v5/03-reproducibility/allowed-runtime-pack-policies.md`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Artifact-Shard-Manifest.md"
id=a16d8db4f60d
kind=markdown
size=1845
lines=63
line_ref=1-63
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Artifact: Shard Manifest
000002 | 
000003 | A **Shard Manifest** describes a scoped shard of Kristal material and the metadata needed to verify, validate, recognize, and compose it.
000004 | 
000005 | A shard may represent a domain, subdomain, tenant, time window, authority channel, dataset subset, or federation slice.
000006 | 
000007 | ---
000008 | 
000009 | ## What it is
000010 | 
000011 | A Shard Manifest is a verifiable pointer to shard content or a shard Exchange, annotated with:
000012 | 
000013 | - shard identity;
000014 | - artifact status;
000015 | - scope;
000016 | - authority channel;
000017 | - validation references;
000018 | - authority recognition references;
000019 | - integrity metadata;
000020 | - lineage;
000021 | - reader-policy-relevant labels.
000022 | 
000023 | ---
000024 | 
000025 | ## When it exists
000026 | 
000027 | You create a Shard Manifest when:
000028 | 
000029 | - a publisher produces a domain-scoped artifact;
000030 | - an authority channel publishes only a scoped subset;
000031 | - a federation needs to compose many sources;
000032 | - a tenant, environment, or time window needs independent update cadence;
000033 | - you want validation and authority metadata at the shard boundary.
000034 | 
000035 | ---
000036 | 
000037 | ## How consumers use it
000038 | 
000039 | Consumers typically:
000040 | 
000041 | 1. read the shard scope;
000042 | 2. verify integrity metadata if required;
000043 | 3. inspect validation report references;
000044 | 4. inspect authority recognition references;
000045 | 5. check the authority registry and reader policy;
000046 | 6. decide whether the shard can be used, hidden, rejected, or exposed with labels.
000047 | 
000048 | ---
000049 | 
000050 | ## Relationship to other artifacts
000051 | 
000052 | - **Exchange**: shard content may be an Exchange or Exchange-derived payload.
000053 | - **Validation Report**: records checks on the shard.
000054 | - **Authority Registry**: determines authority acceptance for the shard scope.
000055 | - **Federation Manifest**: composes shard manifests.
000056 | - **Runtime Pack**: may materialize a shard or federated shard set.
000057 | 
000058 | ---
000059 | 
000060 | ## Technical details
000061 | 
000062 | - Schema: `kristal-docs-v5/02-schemas/exchange-shard-manifest.schema.json`
000063 | - Example: `kristal-docs-v5/10-examples/exchange-shard-manifest.example.json`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Artifact-Validation-Report.md"
id=37c529bfbad1
kind=markdown
size=1798
lines=84
line_ref=1-84
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Artifact: Validation Report
000002 | 
000003 | A **Validation Report** records a scoped validation decision and the findings behind it.
000004 | 
000005 | It does not turn a claim into universal truth. It records what was evaluated, by whom or by which validator, under which policy, for which scope, with which result.
000006 | 
000007 | ---
000008 | 
000009 | ## What it can validate
000010 | 
000011 | A Validation Report may target:
000012 | 
000013 | - an assertion;
000014 | - a Structured Epistemic State;
000015 | - an Exchange;
000016 | - a shard;
000017 | - a Federation Manifest;
000018 | - a Runtime Pack;
000019 | - a dataset;
000020 | - a reader policy;
000021 | - a validation policy;
000022 | - an authority channel.
000023 | 
000024 | ---
000025 | 
000026 | ## What it records
000027 | 
000028 | At a high level, it records:
000029 | 
000030 | - target artifact or assertion;
000031 | - target level;
000032 | - scope;
000033 | - issuer authority channel;
000034 | - validation policy reference;
000035 | - validation status;
000036 | - certainty level;
000037 | - `validated_as` classification;
000038 | - findings;
000039 | - evidence and provenance references;
000040 | - authority recognition references;
000041 | - warnings and errors;
000042 | - signatures when applicable.
000043 | 
000044 | ---
000045 | 
000046 | ## Common validation statuses
000047 | 
000048 | - `not_evaluated`
000049 | - `in_review`
000050 | - `validated`
000051 | - `conditionally_validated`
000052 | - `disputed`
000053 | - `rejected`
000054 | - `revoked`
000055 | 
000056 | ---
000057 | 
000058 | ## Why it matters
000059 | 
000060 | Validation Reports make it possible to show readers:
000061 | 
000062 | - validated as what;
000063 | - by whom;
000064 | - under which policy;
000065 | - for which scope;
000066 | - with what certainty;
000067 | - with what evidence;
000068 | - with what limitations.
000069 | 
000070 | ---
000071 | 
000072 | ## Relationship to other artifacts
000073 | 
000074 | - Exchanges and Shards may reference Validation Reports.
000075 | - Federation Manifests may require Validation Reports for included shards.
000076 | - Reader Policies may expose only assertions with matching validation status.
000077 | - Runtime Packs must preserve validation labels when materializing indexes.
000078 | 
000079 | ---
000080 | 
000081 | ## Technical details
000082 | 
000083 | - Schema: `kristal-docs-v5/02-schemas/validation-report.schema.json`
000084 | - Example: `kristal-docs-v5/10-examples/validation-report.example.json`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Artifacts.md"
id=8439669af8b4
kind=markdown
size=2908
lines=98
line_ref=1-98
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Artifacts
000002 | 
000003 | Kristal v5 produces a small set of standard artifacts that can be verified, distributed, queried, composed, and interpreted under reader policy.
000004 | 
000005 | This page is a map of what exists, what it is for, and when you see it.
000006 | 
000007 | > This wiki stays high-level. For exact fields and schemas, use `kristal-docs-v5/02-schemas/` and the examples in `kristal-docs-v5/10-examples/`.
000008 | 
000009 | ---
000010 | 
000011 | ## Core artifacts
000012 | 
000013 | ### Structured Epistemic State
000014 | 
000015 | **What it is:** the normative v5 input unit. It represents assertions with scope, status, certainty, provenance, evidence, validation, and authority metadata.
000016 | 
000017 | **When you get it:** before compilation, after extraction/resolution, or as an explicit submitted state.
000018 | 
000019 | ### Exchange
000020 | 
000021 | **What it is:** a compiled working or reference artifact.
000022 | 
000023 | **When you get it:** after compiling a Structured Epistemic State or equivalent accepted input.
000024 | 
000025 | See: [[Artifact-Exchange]]
000026 | 
000027 | ### Validation Report
000028 | 
000029 | **What it is:** scoped validation findings for an assertion, artifact, shard, dataset, runtime pack, reader policy, federation, or authority surface.
000030 | 
000031 | See: [[Artifact-Validation-Report]]
000032 | 
000033 | ### Runtime Pack
000034 | 
000035 | **What it is:** an offline/query-optimized package derived from an Exchange or shard set.
000036 | 
000037 | See: [[Artifact-Runtime-Pack]]
000038 | 
000039 | ---
000040 | 
000041 | ## Federation artifacts
000042 | 
000043 | ### Shard Manifest
000044 | 
000045 | **What it is:** a manifest for a scoped shard, including scope, integrity, validation, and authority-channel metadata.
000046 | 
000047 | See: [[Artifact-Shard-Manifest]]
000048 | 
000049 | ### Federation Manifest
000050 | 
000051 | **What it is:** a deterministic composition of shards, authority channels, validation policies, reader policies, and disagreement-preserving composition rules.
000052 | 
000053 | See: [[Artifact-Federation-Manifest]]
000054 | 
000055 | ### Authority Registry
000056 | 
000057 | **What it is:** the artifact that defines authority channels, trust roots, recognition policies, validation policies, revocation rules, and scope rules.
000058 | 
000059 | See: [[Artifact-Authority-Registry]]
000060 | 
000061 | ---
000062 | 
000063 | ## Supporting artifact families
000064 | 
000065 | Kristal v5 also uses or may reference:
000066 | 
000067 | - Authority Recognition artifacts
000068 | - Reader Policies
000069 | - Revocations
000070 | - Review bundles
000071 | - Transparency log entries
000072 | - Query contracts
000073 | - Runtime pack manifests
000074 | - Test vectors
000075 | 
000076 | ---
000077 | 
000078 | ## Conceptual dependency graph
000079 | 
000080 | ```text
000081 | Structured Epistemic State -> Exchange
000082 | Exchange -> Runtime Pack
000083 | Exchange / Shard / Assertion -> Validation Report
000084 | Authority Channel -> Authority Recognition
000085 | Shard Manifest -> Exchange or shard payload
000086 | Federation Manifest -> Shard Manifests + authority registry + reader policies
000087 | Reader Policy -> visible/queryable/renderable subset
000088 | ```
000089 | 
000090 | ---
000091 | 
000092 | ## How to choose what you need
000093 | 
000094 | - If you want to compile structured work: **Structured Epistemic State + Exchange**
000095 | - If you want to evaluate status: **Validation Report**
000096 | - If you want offline query: **Runtime Pack**
000097 | - If you want multi-authority composition: **Shard Manifest + Federation Manifest + Authority Registry**
000098 | - If you want controlled visibility: **Reader Policy**
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Concepts-and-Mental-Model.md"
id=f8f4059883f7
kind=markdown
size=3294
lines=113
line_ref=1-113
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Concepts & Mental Model
000002 | 
000003 | This page explains Kristal v5 in system terms: what the pieces are, how they fit, and what guarantees you should expect.
000004 | 
000005 | ---
000006 | 
000007 | ## Mental model in one sentence
000008 | 
000009 | Kristal turns structured epistemic work into portable, verifiable artifacts without confusing existence, integrity, validation, authority, certainty, or reader visibility.
000010 | 
000011 | ---
000012 | 
000013 | ## The core loop
000014 | 
000015 | 1. **Collect** signals, drafts, datasets, submissions, or extracted claims.
000016 | 2. **Represent** them as a Structured Epistemic State.
000017 | 3. **Compile** them into a Working Artifact.
000018 | 4. **Validate** assertions, datasets, artifacts, or shards under scoped policies.
000019 | 5. **Recognize** authority for declared scopes.
000020 | 6. **Publish** working or reference artifacts.
000021 | 7. **Package** Runtime Packs for offline/query use.
000022 | 8. **Read/query/render** through explicit reader policies.
000023 | 9. **Evolve** through versions, forks, revocations, rollback, and federation.
000024 | 
000025 | ---
000026 | 
000027 | ## The separation that matters
000028 | 
000029 | ```text
000030 | artifact existence
000031 | ≠ artifact integrity
000032 | ≠ assertion status
000033 | ≠ certainty level
000034 | ≠ validation status
000035 | ≠ authority recognition
000036 | ≠ reader visibility
000037 | ≠ runtime activation
000038 | ```
000039 | 
000040 | This is the core of Kristal v5.
000041 | 
000042 | An artifact may be technically valid and still contain uncertain, disputed, fictional, mythological, speculative, or rejected assertions.
000043 | 
000044 | ---
000045 | 
000046 | ## Structured Epistemic State
000047 | 
000048 | The Structured Epistemic State is the normative input unit for Kristal v5.
000049 | 
000050 | It can contain assertions, provenance, evidence, certainty, validation metadata, authority references, scope, and lineage.
000051 | 
000052 | `Claim-IR` may still be used by extractors and resolvers, but it is not the universal required input boundary.
000053 | 
000054 | ---
000055 | 
000056 | ## Working vs Reference artifacts
000057 | 
000058 | A **Working Artifact** is compiled, portable, and queryable. It may contain unvalidated or disputed material if those states are explicit.
000059 | 
000060 | A **Reference Artifact** is recognized for a declared scope by one or more authority channels.
000061 | 
000062 | Reference does not mean universal certainty or universal agreement.
000063 | 
000064 | ---
000065 | 
000066 | ## Validation
000067 | 
000068 | Validation is scoped. It answers questions like:
000069 | 
000070 | - What was evaluated?
000071 | - Which validation policy applied?
000072 | - Which authority channel issued the validation?
000073 | - What status was assigned?
000074 | - What certainty level and `validated_as` classification apply?
000075 | - Which evidence supports the result?
000076 | 
000077 | Validation can apply to assertions, artifacts, datasets, shards, runtime packs, reader policies, and federations.
000078 | 
000079 | ---
000080 | 
000081 | ## Authority
000082 | 
000083 | Authority is plural.
000084 | 
000085 | Different authority channels may recognize different assertions, corpora, policies, or reference artifacts for different scopes.
000086 | 
000087 | Federation must preserve those authority labels rather than merging everything into a single undifferentiated truth layer.
000088 | 
000089 | ---
000090 | 
000091 | ## Reader policy
000092 | 
000093 | Reader policy determines what a reader, runtime, query, export, or renderer may expose.
000094 | 
000095 | Examples:
000096 | 
000097 | - `reference_only`
000098 | - `validated_only`
000099 | - `high_certainty_only`
000100 | - `research`
000101 | - `creative`
000102 | - `all_with_labels`
000103 | - `custom`
000104 | 
000105 | ---
000106 | 
000107 | ## Integrity
000108 | 
000109 | Integrity protects artifacts. It does not decide whether every assertion is true.
000110 | 
000111 | Hashes, signatures, trust roots, and reproducibility checks answer whether an artifact is the artifact it claims to be.
000112 | 
000113 | They do not erase uncertainty, disagreement, fiction, mythology, or scoped validation labels.
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/FAQ.md"
id=e2e3f636dab0
kind=markdown
size=3055
lines=45
line_ref=1-45
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # FAQ
000002 | 
000003 | ## What is Kristal, in one sentence?
000004 | Kristal v5 is a deterministic, portable epistemic artifact system that compiles Structured Epistemic States into verifiable artifacts while keeping validation scoped, authority plural, certainty explicit, reader policy selectable, and disagreement preserved.
000005 | 
000006 | ## Is Kristal a database?
000007 | Not exactly. Kristal produces portable artifacts such as Exchanges and Runtime Packs that can be queried, but it is primarily a build, verification, distribution, federation, and reader-policy framework.
000008 | 
000009 | ## Does Kristal decide what is universally true?
000010 | No. Kristal records assertion status, certainty level, validation status, authority recognition, scope, and reader visibility. It prevents those labels from being confused.
000011 | 
000012 | ## What is a Structured Epistemic State?
000013 | It is the normative v5 input unit. It represents assertions with provenance, evidence, scope, certainty, validation, authority, and lineage metadata.
000014 | 
000015 | ## Is Claim-IR still used?
000016 | Yes, but as an extractor proposal profile. It is not the universal required input boundary for Kristal v5.
000017 | 
000018 | ## What is the difference between Working and Reference artifacts?
000019 | A Working Artifact is compiled and portable but may contain unvalidated, disputed, or incomplete material. A Reference Artifact is recognized by one or more authority channels for a declared scope.
000020 | 
000021 | ## What is a Validation Report?
000022 | A Validation Report records what was validated, under which policy and scope, by which authority or validator, with which findings, certainty level, and `validated_as` classification.
000023 | 
000024 | ## What is an Authority Registry?
000025 | It is a registry of authority channels, trust roots, recognition policies, validation policies, revocation references, and scope rules.
000026 | 
000027 | ## What is a reader policy?
000028 | A reader policy decides what material is visible or usable for a reader, query, export, renderer, or runtime. Examples include `reference_only`, `validated_only`, `research`, `creative`, and `all_with_labels`.
000029 | 
000030 | ## Does validated-only mean all visible content is universally factual?
000031 | No. Validated-only means the visible content satisfies that reader policy’s validation, authority, certainty, and scope filters. It may include material validated as a hypothesis, mythological corpus, fictional corpus, symbolic model, publisher declaration, or disputed position.
000032 | 
000033 | ## What are Shards and Federations?
000034 | A shard is scoped material that can be validated, recognized, and updated independently. A federation composes shards while preserving source identity, authority, validation, certainty, scope, and disagreement labels.
000035 | 
000036 | ## What does strict verification mean?
000037 | When hashes, signatures, trust roots, revocation checks, or activation rules are declared mandatory, consumers reject artifacts that do not satisfy those checks.
000038 | 
000039 | ## Where are the technical details?
000040 | Use the technical docs in the main repository:
000041 | 
000042 | - Core specs: `kristal-docs-v5/01-core-spec/`
000043 | - Schemas: `kristal-docs-v5/02-schemas/`
000044 | - Examples: `kristal-docs-v5/10-examples/`
000045 | - Test vectors: `kristal-docs-v5/09-test-vectors/`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Getting-Started.md"
id=1aac360d48b5
kind=markdown
size=2582
lines=85
line_ref=1-85
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Getting Started
000002 | 
000003 | Kristal v5 is a deterministic, portable epistemic artifact system. You build artifacts from structured epistemic work, validate and recognize them under scoped policies, distribute them with integrity metadata, and query or render them under reader policy.
000004 | 
000005 | ---
000006 | 
000007 | ## What you can do with Kristal
000008 | 
000009 | - Compile Structured Epistemic States into Working Artifacts.
000010 | - Preserve provenance, evidence, status, certainty, validation, authority, and scope labels.
000011 | - Validate assertions or artifacts under explicit policy.
000012 | - Recognize artifacts or assertions through authority channels.
000013 | - Publish Reference Artifacts for declared scopes.
000014 | - Build Runtime Packs for offline query.
000015 | - Federate shards from multiple authorities without erasing disagreement.
000016 | - Control visibility through reader policies.
000017 | 
000018 | ---
000019 | 
000020 | ## Core building blocks
000021 | 
000022 | - **Structured Epistemic State** — normative input unit.
000023 | - **Exchange** — compiled artifact, either working or reference.
000024 | - **Validation Report** — scoped validation findings and status.
000025 | - **Authority Registry** — authority channels, trust roots, and rules.
000026 | - **Shard Manifest** — scoped shard metadata.
000027 | - **Federation Manifest** — deterministic composition of shards.
000028 | - **Runtime Pack** — offline/query-optimized artifact.
000029 | - **Reader Policy** — visibility and selection rules.
000030 | 
000031 | ---
000032 | 
000033 | ## Typical workflow
000034 | 
000035 | 1. **Represent**
000036 |    - Create or ingest a Structured Epistemic State.
000037 |    - Preserve provenance, evidence, scope, certainty, and assertion status.
000038 | 
000039 | 2. **Compile**
000040 |    - Produce a Working Exchange.
000041 |    - Record build metadata and technical canonicalization/hash policy.
000042 | 
000043 | 3. **Validate**
000044 |    - Run schema, profile, policy, or domain validation.
000045 |    - Produce Validation Reports.
000046 | 
000047 | 4. **Recognize**
000048 |    - Record authority recognition where applicable.
000049 |    - Keep recognition scoped.
000050 | 
000051 | 5. **Publish & distribute**
000052 |    - Publish working or reference artifacts.
000053 |    - Include integrity and signature metadata where required.
000054 | 
000055 | 6. **Package & activate**
000056 |    - Build Runtime Packs.
000057 |    - Activate only when local policy allows.
000058 | 
000059 | 7. **Query or render**
000060 |    - Apply reader policy.
000061 |    - Preserve labels for status, certainty, validation, authority, scope, and lineage.
000062 | 
000063 | ---
000064 | 
000065 | ## If you are new
000066 | 
000067 | Read these pages first:
000068 | 
000069 | - [[What-is-Kristal]]
000070 | - [[Concepts-and-Mental-Model]]
000071 | - [[Artifacts]]
000072 | - [[Workflow-Build-and-Validate]]
000073 | - [[Query-Basics]]
000074 | - [[FAQ]]
000075 | 
000076 | ---
000077 | 
000078 | ## Technical details
000079 | 
000080 | Use the main repository technical docs:
000081 | 
000082 | - `kristal-docs-v5/00-overview/`
000083 | - `kristal-docs-v5/01-core-spec/`
000084 | - `kristal-docs-v5/02-schemas/`
000085 | - `kristal-docs-v5/10-examples/`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/GitSink.bat"
id=fe217bc7e8fa
kind=source
size=750
lines=33
line_ref=1-33
chunks=0
chunk_refs=
summary="Source file."
----
000001 | @echo off
000002 | REM Check if a commit message was provided as an argument
000003 | if "%1"=="" (
000004 |     set /p "commit_message=Enter commit message (e.g., 'Minor fix'): "
000005 | ) else (
000006 |     set commit_message=%1
000007 | )
000008 | 
000009 | echo.
000010 | echo =================================
000011 | echo Starting Git Commit and Push...
000012 | echo Commit Message: "%commit_message%"
000013 | echo =================================
000014 | echo.
000015 | 
000016 | REM Add all changes to the staging area
000017 | echo Running: git add .
000018 | call git add .
000019 | 
000020 | REM Commit the changes
000021 | echo Running: git commit -m "%commit_message%"
000022 | call git commit -m "%commit_message%"
000023 | 
000024 | REM Push the changes to the remote repository
000025 | echo Running: git push
000026 | call git push
000027 | 
000028 | echo.
000029 | echo =================================
000030 | echo Git process complete!
000031 | echo =================================
000032 | 
000033 | pause
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Glossary.md"
id=374da005ac9e
kind=markdown
size=3885
lines=80
line_ref=1-80
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Glossary
000002 | 
000003 | A compact reference of Kristal v5 terms used across the wiki. Formal definitions live in the technical docs.
000004 | 
000005 | ---
000006 | 
000007 | ## Artifact
000008 | A packaged, distributable unit produced or consumed by the Kristal pipeline.
000009 | 
000010 | ## Artifact integrity
000011 | The technical property that an artifact matches its declared identity, hashes, signatures, and verification metadata.
000012 | 
000013 | ## Assertion
000014 | A structured statement or claim-like unit inside a Kristal artifact. Assertions may be factual, hypothetical, disputed, fictional, mythological, symbolic, institutional, technical, or policy-oriented.
000015 | 
000016 | ## Assertion status
000017 | The epistemic state of an assertion, such as `hypothesis`, `claimed`, `sourced`, `disputed`, `reviewed`, `validated`, `rejected`, `retracted`, or `superseded`.
000018 | 
000019 | ## Authority channel
000020 | The entity or channel that issues validation, recognition, publication, policy, or trust decisions for a declared scope.
000021 | 
000022 | ## Authority recognition
000023 | A scoped decision that an authority channel recognizes a target as valid, accepted, disputed, deprecated, rejected, or revoked under a declared policy.
000024 | 
000025 | ## Authority Registry
000026 | A v5 artifact that records authority channels, trust roots, validation policies, recognition policies, revocation references, and scope rules.
000027 | 
000028 | ## Certainty level
000029 | A label describing certainty, such as `unknown`, `speculative`, `low`, `medium`, `high`, `established`, or `not_applicable`.
000030 | 
000031 | ## Claim-IR
000032 | An extractor proposal profile that may be used by extraction pipelines. It is not the universal required input boundary for Kristal v5.
000033 | 
000034 | ## Compilation
000035 | The deterministic process of producing a portable artifact from a Structured Epistemic State or accepted input.
000036 | 
000037 | ## Federation
000038 | A composition of multiple shards or artifacts that preserves source identity, authority, validation, certainty, scope, and disagreement labels.
000039 | 
000040 | ## Federation Manifest
000041 | A manifest that defines shard composition, authority references, validation policy references, reader policy references, and disagreement-preserving composition rules.
000042 | 
000043 | ## Integrity
000044 | Hashing, signatures, reproducibility, and verification mechanisms that protect artifact identity.
000045 | 
000046 | ## Reader policy
000047 | A policy that determines what material a reader, query, export, renderer, or runtime is allowed to expose.
000048 | 
000049 | ## Reference Artifact
000050 | An artifact recognized by one or more authority channels for a declared scope.
000051 | 
000052 | ## Runtime Pack
000053 | An offline-capable, query-optimized artifact derived from an Exchange or shard set.
000054 | 
000055 | ## Scope
000056 | The domain, subdomain, jurisdiction, time window, tenant, environment, or language context where a status, validation, or recognition applies.
000057 | 
000058 | ## Shard
000059 | A scoped artifact or artifact subset used for independent publishing, update, validation, and federation.
000060 | 
000061 | ## Shard Manifest
000062 | A manifest describing a shard’s identity, scope, authority channel, validation references, recognition references, and integrity metadata.
000063 | 
000064 | ## Structured Epistemic State
000065 | The normative Kristal v5 input unit for representing assertions with provenance, evidence, scope, certainty, validation, authority, and lineage metadata.
000066 | 
000067 | ## Technical canonicalization
000068 | A stable byte-representation process used for hashing and signatures. It is not an epistemic authority claim.
000069 | 
000070 | ## Validation
000071 | A scoped evaluation of a target under a validation policy.
000072 | 
000073 | ## Validation Report
000074 | An artifact recording validation target, policy, findings, status, certainty, `validated_as`, evidence, and issuer authority channel.
000075 | 
000076 | ## Validated as
000077 | A classification of what kind of thing the assertion is validated as, for example `high_confidence_fact`, `institutional_reference`, `publisher_declaration`, `technical_specification`, `mythological_corpus`, `fictional_corpus`, `symbolic_model`, or `disputed_position`.
000078 | 
000079 | ## Working Artifact
000080 | A compiled artifact that may be used for review, research, staging, or collaboration before authority recognition as a reference artifact.
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Home.md"
id=0bcc3c149b08
kind=markdown
size=2711
lines=85
line_ref=1-85
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Kristal Framework — Wiki
000002 | 
000003 | Kristal v5 is a deterministic, portable epistemic artifact system.
000004 | 
000005 | It compiles **Structured Epistemic States** into immutable, verifiable, queryable artifacts while keeping validation scoped, authority plural, certainty explicit, reader policy selectable, and disagreement preserved.
000006 | 
000007 | This wiki is product and usage oriented. Normative requirements, JSON Schemas, examples, and conformance rules live in the technical docs under:
000008 | 
000009 | ```text
000010 | C:\mycode\Kristal\kristal-framework\docs\Technical-Reference\kristal-docs-v5
000011 | ```
000012 | 
000013 | ---
000014 | 
000015 | ## Start here
000016 | 
000017 | - **Quickstart:** [[Quickstart]]
000018 | - **What is Kristal:** [[What-is-Kristal]]
000019 | - **Mental model:** [[Concepts-and-Mental-Model]]
000020 | - **Glossary:** [[Glossary]]
000021 | 
000022 | ---
000023 | 
000024 | ## What Kristal v5 does
000025 | 
000026 | Kristal v5 lets teams:
000027 | 
000028 | - compile structured epistemic work into portable artifacts;
000029 | - preserve provenance, evidence, scope, certainty, validation, and authority metadata;
000030 | - distribute artifacts that can be verified offline;
000031 | - query or render selected material under explicit reader policy;
000032 | - federate multiple authority channels without erasing disagreement;
000033 | - operate rollouts, rollback, and compatibility checks safely.
000034 | 
000035 | ---
000036 | 
000037 | ## Core distinction
000038 | 
000039 | Kristal v5 keeps these concepts separate:
000040 | 
000041 | ```text
000042 | artifact existence
000043 | ≠ artifact integrity
000044 | ≠ assertion status
000045 | ≠ certainty level
000046 | ≠ validation status
000047 | ≠ authority recognition
000048 | ≠ reader visibility
000049 | ≠ runtime activation
000050 | ```
000051 | 
000052 | An artifact can be signed, content-addressed, reproducible, and queryable while still containing assertions that are hypothetical, disputed, fictional, mythological, low-certainty, rejected by one authority channel, recognized by another, or hidden by a reader policy.
000053 | 
000054 | ---
000055 | 
000056 | ## Core artifacts
000057 | 
000058 | - [[Artifact-Exchange]] — compiled working or reference artifact
000059 | - [[Artifact-Runtime-Pack]] — offline/query-optimized runtime artifact
000060 | - [[Artifact-Validation-Report]] — scoped validation results and findings
000061 | - [[Artifact-Shard-Manifest]] — scoped shard pointer with authority and validation metadata
000062 | - [[Artifact-Federation-Manifest]] — composition across shards and authority channels
000063 | - [[Artifact-Authority-Registry]] — scoped authority channels, trust roots, and rules
000064 | 
000065 | ---
000066 | 
000067 | ## Core workflows
000068 | 
000069 | - [[Workflow-Build-and-Validate]]
000070 | - [[Workflow-Publish-and-Distribute]]
000071 | - [[Workflow-Activate-Rollback-Downgrade]]
000072 | - [[Workflow-Subsets-Recipes]]
000073 | - [[Workflow-Federation-and-Curation]]
000074 | 
000075 | ---
000076 | 
000077 | ## Technical docs
000078 | 
000079 | For exact fields, schemas, conformance requirements, test vectors, and examples, use:
000080 | 
000081 | - `kristal-docs-v5/00-overview/`
000082 | - `kristal-docs-v5/01-core-spec/`
000083 | - `kristal-docs-v5/02-schemas/`
000084 | - `kristal-docs-v5/09-test-vectors/`
000085 | - `kristal-docs-v5/10-examples/`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Identity-and-Determinism.md"
id=6770a0a26b4c
kind=markdown
size=2893
lines=101
line_ref=1-101
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Identity and Determinism
000002 | 
000003 | Kristal v5 is designed so independent builders can produce the same identifiers and verifiable artifacts from the same inputs, policies, profiles, and compiler configuration.
000004 | 
000005 | This page explains the operational model. Exact technical canonicalization and hashing rules are defined in the technical docs.
000006 | 
000007 | ---
000008 | 
000009 | ## Identity
000010 | 
000011 | Identity answers: **which artifact is this?**
000012 | 
000013 | Kristal artifacts use content-derived identifiers and hash references so consumers can verify that the artifact they received matches the artifact that was built, signed, published, or activated.
000014 | 
000015 | Identity protects artifacts. It does not decide whether every assertion inside an artifact is true.
000016 | 
000017 | ---
000018 | 
000019 | ## Determinism
000020 | 
000021 | Determinism answers: **will the same inputs produce the same output?**
000022 | 
000023 | A deterministic build requires declared:
000024 | 
000025 | - inputs;
000026 | - source snapshots;
000027 | - compiler identity;
000028 | - compiler configuration;
000029 | - build-affecting policies;
000030 | - technical canonicalization profile;
000031 | - hashing rules;
000032 | - optional profile behavior that affects output.
000033 | 
000034 | ---
000035 | 
000036 | ## Technical canonicalization
000037 | 
000038 | In Kristal v5, the word **canonicalization** should be used for the technical hashing process only: producing a stable byte representation for identity, hashes, and signatures.
000039 | 
000040 | It should not be used to mean epistemic authority, truth, or reference acceptance.
000041 | 
000042 | ---
000043 | 
000044 | ## What must be recorded
000045 | 
000046 | At minimum, identity-bearing artifacts should record:
000047 | 
000048 | 1. **Inputs**
000049 |    - source snapshots;
000050 |    - Structured Epistemic State references;
000051 |    - prior artifacts;
000052 |    - recipes or subset policies.
000053 | 
000054 | 2. **Policies**
000055 |    - ordering;
000056 |    - membership filters;
000057 |    - reader policy materialization;
000058 |    - authority or validation filters that affect output.
000059 | 
000060 | 3. **Tooling identity**
000061 |    - compiler name and version;
000062 |    - configuration hash;
000063 |    - build identifiers.
000064 | 
000065 | 4. **Integrity metadata**
000066 |    - hash algorithm;
000067 |    - technical canonicalization profile;
000068 |    - hash target policy;
000069 |    - signatures where applicable.
000070 | 
000071 | ---
000072 | 
000073 | ## Strict verification
000074 | 
000075 | When a manifest declares that hashes, signatures, trust roots, revocation data, or activation rules are mandatory, consumers should enforce those requirements strictly.
000076 | 
000077 | Strict verification failure protects the artifact boundary.
000078 | 
000079 | It does not erase the need to preserve assertion status, certainty level, validation status, authority recognition, and reader visibility labels.
000080 | 
000081 | ---
000082 | 
000083 | ## What is not part of identity
000084 | 
000085 | The following should not change content identity unless a profile explicitly makes them identity-bearing:
000086 | 
000087 | - wall-clock timestamps used only for logging;
000088 | - local paths;
000089 | - hostnames;
000090 | - transient deployment metadata;
000091 | - runtime cache state;
000092 | - UI rendering state;
000093 | - operational logs.
000094 | 
000095 | ---
000096 | 
000097 | ## Technical details
000098 | 
000099 | - `kristal-docs-v5/01-core-spec/ids-canonicalization-hashing.md`
000100 | - `kristal-docs-v5/03-reproducibility/deterministic-build-rules.md`
000101 | - `kristal-docs-v5/09-test-vectors/jcs/`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Operations-Compatibility.md"
id=e0dc9271943f
kind=markdown
size=2191
lines=82
line_ref=1-82
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Operations: Compatibility
000002 | 
000003 | This page explains how to operate Kristal v5 artifacts without breaking consumers.
000004 | 
000005 | Compatibility is about preserving artifact identity, query expectations, runtime behavior, reader policy semantics, and verification rules.
000006 | 
000007 | ---
000008 | 
000009 | ## Compatibility goals
000010 | 
000011 | A compatibility strategy should ensure:
000012 | 
000013 | - consumers can reject incompatible artifacts early;
000014 | - publishers can roll out changes gradually;
000015 | - rollback remains possible;
000016 | - reader policy behavior remains explicit;
000017 | - authority and validation labels remain interpretable;
000018 | - schema and profile changes are versioned.
000019 | 
000020 | ---
000021 | 
000022 | ## What should remain stable
000023 | 
000024 | Across compatible changes, keep stable:
000025 | 
000026 | - artifact identity expectations;
000027 | - technical canonicalization and hashing behavior;
000028 | - signature verification semantics;
000029 | - query contract semantics;
000030 | - reader policy interpretation;
000031 | - required labels for status, validation, certainty, authority, and scope.
000032 | 
000033 | ---
000034 | 
000035 | ## What may change with coordination
000036 | 
000037 | - additive optional fields;
000038 | - new profiles;
000039 | - new validation policies;
000040 | - new reader policy modes;
000041 | - new query capabilities;
000042 | - new Runtime Pack policies;
000043 | - new authority channels.
000044 | 
000045 | These should be explicitly declared and versioned.
000046 | 
000047 | ---
000048 | 
000049 | ## Breaking changes
000050 | 
000051 | Treat these as breaking unless explicitly version-gated:
000052 | 
000053 | - removing required fields;
000054 | - changing field meaning;
000055 | - changing technical canonicalization or hashing;
000056 | - changing signature semantics;
000057 | - changing reader policy semantics;
000058 | - changing federation composition behavior;
000059 | - changing Runtime Pack activation compatibility;
000060 | - changing authority recognition semantics.
000061 | 
000062 | ---
000063 | 
000064 | ## Upgrade playbook
000065 | 
000066 | 1. Publish new artifacts without activation.
000067 | 2. Validate schemas and profiles.
000068 | 3. Run smoke queries under representative reader policies.
000069 | 4. Verify rollback targets remain available.
000070 | 5. Canary activation for a small scope.
000071 | 6. Expand activation gradually.
000072 | 7. Keep prior artifacts available for audit and rollback.
000073 | 8. Deprecate old surfaces only after consumers have migrated.
000074 | 
000075 | ---
000076 | 
000077 | ## Related pages
000078 | 
000079 | - [[Workflow-Activate-Rollback-Downgrade]]
000080 | - [[Operations-Release-Strategy]]
000081 | - [[Operations-Observability-and-Troubleshooting]]
000082 | - [[Query-Pagination-and-Capabilities]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Operations-Observability-and-Troubleshooting.md"
id=b0a79527eed2
kind=markdown
size=2278
lines=103
line_ref=1-103
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Operations: Observability & Troubleshooting
000002 | 
000003 | This page describes what to monitor and how to diagnose Kristal v5 build, validation, distribution, activation, federation, reader policy, and query failures.
000004 | 
000005 | ---
000006 | 
000007 | ## What to observe
000008 | 
000009 | ### Build pipeline
000010 | 
000011 | - success/failure rate;
000012 | - duration;
000013 | - queue depth;
000014 | - retries and timeouts;
000015 | - compiler version and config hash;
000016 | - reproducibility mismatches.
000017 | 
000018 | ### Validation
000019 | 
000020 | - validation status counts;
000021 | - validation policy failures;
000022 | - evidence missing;
000023 | - schema failures;
000024 | - profile failures;
000025 | - rejected or disputed assertions.
000026 | 
000027 | ### Authority and trust
000028 | 
000029 | - signature verification failures;
000030 | - trust root mismatch;
000031 | - unrecognized authority channel;
000032 | - revoked key or authority;
000033 | - recognition status changes.
000034 | 
000035 | ### Distribution and activation
000036 | 
000037 | - publish failures;
000038 | - missing artifact references;
000039 | - hash mismatch events;
000040 | - activation failures;
000041 | - rollback events;
000042 | - downgrade blocks;
000043 | - stale pack rejection.
000044 | 
000045 | ### Query and reader policy
000046 | 
000047 | - query latency;
000048 | - pagination errors;
000049 | - capability mismatch;
000050 | - reader policy denial;
000051 | - missing labels;
000052 | - unexpected visibility.
000053 | 
000054 | ---
000055 | 
000056 | ## Recommended log fields
000057 | 
000058 | Use structured logs with:
000059 | 
000060 | - `tenant_id`
000061 | - `environment`
000062 | - `build_id`
000063 | - `artifact_id`
000064 | - `runtime_pack_id`
000065 | - `authority_channel_id`
000066 | - `reader_policy_id`
000067 | - `validation_policy_id`
000068 | - `scope.domain`
000069 | - `scope.subdomain`
000070 | - `stage`
000071 | - `event`
000072 | - `duration_ms`
000073 | - `error_code`
000074 | - `correlation_id`
000075 | 
000076 | ---
000077 | 
000078 | ## Common troubleshooting paths
000079 | 
000080 | ### Artifact verifies but content is hidden
000081 | 
000082 | Check reader policy, authority channel filters, validation status filters, certainty level filters, and scope filters.
000083 | 
000084 | ### Artifact exists but cannot activate
000085 | 
000086 | Check activation policy, revocation state, compatibility, tenant/environment scope, and Runtime Pack source artifact status.
000087 | 
000088 | ### Federation shows conflicting claims
000089 | 
000090 | This may be expected. Check whether the composition policy is `preserve_disagreement` and whether reader policy includes disputed positions.
000091 | 
000092 | ### Query result missing labels
000093 | 
000094 | Check Runtime Pack materialization and query contract. The pack may not have preserved labels required by the reader policy.
000095 | 
000096 | ---
000097 | 
000098 | ## Related pages
000099 | 
000100 | - [[Operations]]
000101 | - [[Operations-Release-Strategy]]
000102 | - [[Query-Pagination-and-Capabilities]]
000103 | - [[Workflow-Activate-Rollback-Downgrade]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Operations-Release-Strategy.md"
id=6808747f544c
kind=markdown
size=1293
lines=76
line_ref=1-76
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Operations: Release Strategy
000002 | 
000003 | A Kristal release strategy controls how artifacts, Runtime Packs, authority registries, reader policies, and activation pointers move through environments.
000004 | 
000005 | ---
000006 | 
000007 | ## Release units
000008 | 
000009 | A release may include:
000010 | 
000011 | - Exchange;
000012 | - Runtime Pack;
000013 | - Validation Reports;
000014 | - Authority Recognition artifacts;
000015 | - Authority Registry updates;
000016 | - Federation Manifest;
000017 | - Shard Manifests;
000018 | - Reader Policies;
000019 | - Revocation updates.
000020 | 
000021 | ---
000022 | 
000023 | ## Release stages
000024 | 
000025 | Common stages:
000026 | 
000027 | 1. build;
000028 | 2. validate;
000029 | 3. recognize if applicable;
000030 | 4. publish;
000031 | 5. distribute;
000032 | 6. verify;
000033 | 7. activate;
000034 | 8. monitor;
000035 | 9. rollback if needed.
000036 | 
000037 | ---
000038 | 
000039 | ## Activation strategy
000040 | 
000041 | Activation should be scoped by:
000042 | 
000043 | - tenant;
000044 | - environment;
000045 | - region;
000046 | - service;
000047 | - authority channel;
000048 | - reader policy;
000049 | - Runtime Pack version.
000050 | 
000051 | ---
000052 | 
000053 | ## Canary strategy
000054 | 
000055 | Canary releases should validate:
000056 | 
000057 | - hash/signature verification;
000058 | - query behavior;
000059 | - reader policy enforcement;
000060 | - label preservation;
000061 | - latency and error rates;
000062 | - rollback readiness.
000063 | 
000064 | ---
000065 | 
000066 | ## Rollback readiness
000067 | 
000068 | A release is not operationally safe unless the prior known-good activation target is still available and verifies under current policy.
000069 | 
000070 | ---
000071 | 
000072 | ## Related pages
000073 | 
000074 | - [[Workflow-Publish-and-Distribute]]
000075 | - [[Workflow-Activate-Rollback-Downgrade]]
000076 | - [[Operations-Compatibility]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Operations.md"
id=a951160d8094
kind=markdown
size=1255
lines=51
line_ref=1-51
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Operations
000002 | 
000003 | Kristal operations cover release, distribution, activation, rollback, compatibility, observability, and troubleshooting.
000004 | 
000005 | The operational model preserves the v5 separations:
000006 | 
000007 | ```text
000008 | artifact existence
000009 | ≠ artifact integrity
000010 | ≠ validation status
000011 | ≠ authority recognition
000012 | ≠ reader visibility
000013 | ≠ runtime activation
000014 | ```
000015 | 
000016 | ---
000017 | 
000018 | ## Main operations pages
000019 | 
000020 | - [[Operations-Release-Strategy]]
000021 | - [[Operations-Observability-and-Troubleshooting]]
000022 | - [[Operations-Compatibility]]
000023 | 
000024 | ---
000025 | 
000026 | ## Operational responsibilities
000027 | 
000028 | Operators should ensure:
000029 | 
000030 | - artifacts are published with stable identity;
000031 | - required hashes and signatures verify;
000032 | - revocations are applied;
000033 | - activation is atomic;
000034 | - rollback is available;
000035 | - reader policy is enforced;
000036 | - authority and scope labels are preserved;
000037 | - Runtime Packs preserve validation and certainty labels;
000038 | - monitoring surfaces integrity, validation, activation, and query failures separately.
000039 | 
000040 | ---
000041 | 
000042 | ## What operations must not do
000043 | 
000044 | Operations should not:
000045 | 
000046 | - treat working artifacts as reference artifacts without recognition;
000047 | - hide validation scope;
000048 | - flatten authority channels;
000049 | - strip certainty labels;
000050 | - expose rejected or revoked material when policy blocks it;
000051 | - present scoped validation as universal truth.
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Query-Basics.md"
id=229f916608aa
kind=markdown
size=1439
lines=63
line_ref=1-63
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Query Basics
000002 | 
000003 | Kristal v5 query is label-preserving.
000004 | 
000005 | A query result should not lose the labels that tell a reader what kind of assertion they are seeing, who recognizes it, how certain it is, and which policy made it visible.
000006 | 
000007 | ---
000008 | 
000009 | ## Basic query flow
000010 | 
000011 | 1. Select a source artifact or Runtime Pack.
000012 | 2. Verify integrity if required.
000013 | 3. Select or resolve a reader policy.
000014 | 4. Execute the declared query contract.
000015 | 5. Return results with labels and provenance references.
000016 | 
000017 | ---
000018 | 
000019 | ## Common filters
000020 | 
000021 | - subject / predicate / object;
000022 | - domain or scope;
000023 | - authority channel;
000024 | - assertion status;
000025 | - validation status;
000026 | - certainty level;
000027 | - `validated_as`;
000028 | - recognition status;
000029 | - reader policy;
000030 | - time window or tenant.
000031 | 
000032 | ---
000033 | 
000034 | ## Result labels
000035 | 
000036 | Results should keep visible:
000037 | 
000038 | - `assertion_status`;
000039 | - `validation_status`;
000040 | - `certainty_level`;
000041 | - `validated_as`;
000042 | - `authority_channel`;
000043 | - `recognition_status`;
000044 | - `scope`;
000045 | - evidence/provenance references when available.
000046 | 
000047 | ---
000048 | 
000049 | ## Reader policy examples
000050 | 
000051 | - `reference_only`: show recognized reference material.
000052 | - `validated_only`: show material validated under allowed policies and authority channels.
000053 | - `research`: show broader material with labels.
000054 | - `creative`: show fictional, mythological, or symbolic corpora when allowed.
000055 | - `all_with_labels`: show all allowed material with explicit status labels.
000056 | 
000057 | ---
000058 | 
000059 | ## Related pages
000060 | 
000061 | - [[Query]]
000062 | - [[Query-Pagination-and-Capabilities]]
000063 | - [[Artifact-Runtime-Pack]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Query-Pagination-and-Capabilities.md"
id=f53751c29c4b
kind=markdown
size=1331
lines=59
line_ref=1-59
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Query: Pagination & Capabilities
000002 | 
000003 | Kristal query runtimes declare their capabilities so clients can adapt, fail early, or select a different reader policy or runtime pack.
000004 | 
000005 | ---
000006 | 
000007 | ## Capabilities
000008 | 
000009 | A runtime may declare support for:
000010 | 
000011 | - pagination;
000012 | - cardinality estimates;
000013 | - subject/predicate/object filters;
000014 | - authority channel filters;
000015 | - validation status filters;
000016 | - certainty level filters;
000017 | - `validated_as` filters;
000018 | - scope filters;
000019 | - disagreement views;
000020 | - reader policy filters.
000021 | 
000022 | ---
000023 | 
000024 | ## Pagination
000025 | 
000026 | Pagination must be deterministic for the declared ordering and query contract.
000027 | 
000028 | Continuation tokens should preserve enough state to avoid skipped or duplicated rows under the same artifact identity and query contract.
000029 | 
000030 | ---
000031 | 
000032 | ## Capability mismatch
000033 | 
000034 | A client should not assume unsupported filters exist.
000035 | 
000036 | If a reader policy requires a filter that the runtime cannot enforce, the runtime should return an explicit capability error or require a different materialized view.
000037 | 
000038 | ---
000039 | 
000040 | ## Label preservation
000041 | 
000042 | Pagination and capabilities must not strip labels required by reader policy.
000043 | 
000044 | At minimum, returned results should preserve labels needed to understand:
000045 | 
000046 | - validation;
000047 | - certainty;
000048 | - authority;
000049 | - scope;
000050 | - status;
000051 | - lineage.
000052 | 
000053 | ---
000054 | 
000055 | ## Related pages
000056 | 
000057 | - [[Query]]
000058 | - [[Query-Basics]]
000059 | - [[Operations-Observability-and-Troubleshooting]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Query.md"
id=6af37cf02ff3
kind=markdown
size=1355
lines=70
line_ref=1-70
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Query
000002 | 
000003 | Kristal query surfaces expose selected material from Exchanges, Runtime Packs, shards, or federations under declared query contracts and reader policies.
000004 | 
000005 | Query does not decide truth. It returns what the active artifact, query contract, and reader policy allow.
000006 | 
000007 | ---
000008 | 
000009 | ## Query sources
000010 | 
000011 | Queries may run over:
000012 | 
000013 | - Runtime Packs;
000014 | - Exchanges;
000015 | - shard sets;
000016 | - federation-derived views;
000017 | - reader-policy-selected subsets;
000018 | - exported indexes.
000019 | 
000020 | ---
000021 | 
000022 | ## What query results must preserve
000023 | 
000024 | Query results should preserve or expose:
000025 | 
000026 | - assertion ID;
000027 | - statement or payload reference;
000028 | - assertion status;
000029 | - validation status;
000030 | - certainty level;
000031 | - `validated_as`;
000032 | - authority channel;
000033 | - recognition status;
000034 | - scope;
000035 | - provenance and evidence references;
000036 | - lineage;
000037 | - reader policy used.
000038 | 
000039 | ---
000040 | 
000041 | ## Reader policy
000042 | 
000043 | Reader policy is part of the query surface.
000044 | 
000045 | A validated-only query should not expose unvalidated assertions.
000046 | 
000047 | A research query may expose disputed or low-certainty material if the active policy permits it and labels are preserved.
000048 | 
000049 | ---
000050 | 
000051 | ## Query contract
000052 | 
000053 | The query contract declares:
000054 | 
000055 | - supported operators;
000056 | - pagination behavior;
000057 | - ordering;
000058 | - limits;
000059 | - filters;
000060 | - continuation token semantics;
000061 | - capability reporting;
000062 | - error behavior.
000063 | 
000064 | ---
000065 | 
000066 | ## Related pages
000067 | 
000068 | - [[Query-Basics]]
000069 | - [[Query-Pagination-and-Capabilities]]
000070 | - [[Artifact-Runtime-Pack]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Quickstart.md"
id=405becb17dd6
kind=markdown
size=2452
lines=123
line_ref=1-123
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Quickstart
000002 | 
000003 | This quickstart gives the operational shape of a Kristal v5 flow. It is conceptual; exact commands depend on your compiler, storage, and runtime tooling.
000004 | 
000005 | ---
000006 | 
000007 | ## 1. Start with structured epistemic input
000008 | 
000009 | The v5 input model starts from a **Structured Epistemic State**.
000010 | 
000011 | It should preserve:
000012 | 
000013 | - assertions;
000014 | - assertion status;
000015 | - certainty level;
000016 | - scope;
000017 | - provenance;
000018 | - evidence;
000019 | - validation metadata where available;
000020 | - authority references where available;
000021 | - lineage.
000022 | 
000023 | `Claim-IR` may be used by extractors, but it is not the universal required input boundary.
000024 | 
000025 | ---
000026 | 
000027 | ## 2. Compile a Working Exchange
000028 | 
000029 | Compile the state into a Working Exchange.
000030 | 
000031 | The Working Exchange is:
000032 | 
000033 | - immutable;
000034 | - content-addressed;
000035 | - queryable;
000036 | - portable;
000037 | - reproducible within its declared build surface;
000038 | - explicit about its artifact status.
000039 | 
000040 | Working does not mean false. It means not necessarily recognized as a reference artifact.
000041 | 
000042 | ---
000043 | 
000044 | ## 3. Validate under declared policy
000045 | 
000046 | Run validation appropriate to the target:
000047 | 
000048 | - schema validation;
000049 | - profile validation;
000050 | - evidence checks;
000051 | - authority checks;
000052 | - domain-specific validation;
000053 | - reader-policy validation.
000054 | 
000055 | Produce Validation Reports.
000056 | 
000057 | ---
000058 | 
000059 | ## 4. Apply authority recognition if needed
000060 | 
000061 | If the artifact or assertions should become reference material for a scope, record Authority Recognition.
000062 | 
000063 | Recognition must identify:
000064 | 
000065 | - authority channel;
000066 | - scope;
000067 | - recognition status;
000068 | - validation policy;
000069 | - certainty level;
000070 | - `validated_as` classification.
000071 | 
000072 | ---
000073 | 
000074 | ## 5. Publish and distribute
000075 | 
000076 | Publish the Exchange, Validation Reports, Authority Recognition artifacts, and supporting files.
000077 | 
000078 | Distributors should preserve integrity metadata, signatures, revocation references, and lineage.
000079 | 
000080 | ---
000081 | 
000082 | ## 6. Build a Runtime Pack
000083 | 
000084 | Build a Runtime Pack when you need offline or optimized query.
000085 | 
000086 | The Runtime Pack must preserve labels needed by reader policy:
000087 | 
000088 | - assertion status;
000089 | - validation status;
000090 | - certainty level;
000091 | - `validated_as`;
000092 | - authority channel;
000093 | - scope;
000094 | - provenance;
000095 | - lineage.
000096 | 
000097 | ---
000098 | 
000099 | ## 7. Query with reader policy
000100 | 
000101 | Select a reader policy before presenting results.
000102 | 
000103 | Common modes:
000104 | 
000105 | - `reference_only`
000106 | - `validated_only`
000107 | - `high_certainty_only`
000108 | - `research`
000109 | - `creative`
000110 | - `all_with_labels`
000111 | - `custom`
000112 | 
000113 | Reader policy determines visibility, not artifact existence.
000114 | 
000115 | ---
000116 | 
000117 | ## Next pages
000118 | 
000119 | - [[What-is-Kristal]]
000120 | - [[Artifacts]]
000121 | - [[Workflow-Build-and-Validate]]
000122 | - [[Workflow-Publish-and-Distribute]]
000123 | - [[Query-Basics]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Trust-Authority-and-Signatures.md"
id=da12fe38fd09
kind=markdown
size=2144
lines=89
line_ref=1-89
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Trust, Authority & Signatures
000002 | 
000003 | Kristal v5 separates artifact integrity from authority recognition.
000004 | 
000005 | A signature may prove that a key signed an artifact. It does not by itself prove universal truth, universal authority, or reader visibility.
000006 | 
000007 | ---
000008 | 
000009 | ## Artifact integrity
000010 | 
000011 | Integrity asks:
000012 | 
000013 | - Does the content hash match?
000014 | - Was the declared technical canonicalization used?
000015 | - Does the signature verify?
000016 | - Is the key trusted for this purpose?
000017 | - Has the artifact, key, or authority channel been revoked?
000018 | 
000019 | ---
000020 | 
000021 | ## Authority recognition
000022 | 
000023 | Authority recognition asks:
000024 | 
000025 | - Which authority channel recognizes this artifact, assertion, dataset, shard, policy, or runtime pack?
000026 | - For which scope?
000027 | - Under which validation policy?
000028 | - With which recognition status?
000029 | - At what certainty level?
000030 | - As what kind of assertion or corpus?
000031 | 
000032 | ---
000033 | 
000034 | ## Authority channels
000035 | 
000036 | An authority channel may represent:
000037 | 
000038 | - an individual;
000039 | - a community;
000040 | - a research collective;
000041 | - an academic institution;
000042 | - a standards body;
000043 | - a company;
000044 | - a government;
000045 | - an intergovernmental organization;
000046 | - an AI validator;
000047 | - a hybrid collective.
000048 | 
000049 | Authority is scoped. A channel may be trusted for one domain, jurisdiction, tenant, language, time window, or environment and not another.
000050 | 
000051 | ---
000052 | 
000053 | ## Signatures
000054 | 
000055 | Signatures protect artifact identity and attest that a signer produced, published, validated, recognized, or approved a declared target.
000056 | 
000057 | Consumers still need policy to decide whether that signer is acceptable for the target scope.
000058 | 
000059 | ---
000060 | 
000061 | ## Authority Registry
000062 | 
000063 | The Authority Registry records:
000064 | 
000065 | - authority channels;
000066 | - trust roots;
000067 | - validation policies;
000068 | - recognition policies;
000069 | - revocation references;
000070 | - scope rules.
000071 | 
000072 | See: [[Artifact-Authority-Registry]]
000073 | 
000074 | ---
000075 | 
000076 | ## Reader policy
000077 | 
000078 | Even when an artifact verifies and an authority recognizes it, a reader policy may still hide or label it.
000079 | 
000080 | Reader policy controls visibility.
000081 | 
000082 | ---
000083 | 
000084 | ## Technical details
000085 | 
000086 | - `kristal-docs-v5/01-core-spec/signatures-trust.md`
000087 | - `kristal-docs-v5/01-core-spec/authority-recognition.md`
000088 | - `kristal-docs-v5/02-schemas/authority-recognition.schema.json`
000089 | - `kristal-docs-v5/02-schemas/authority-registry.schema.json`
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/What-is-Kristal.md"
id=61d912555f6d
kind=markdown
size=2607
lines=91
line_ref=1-91
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # What is Kristal?
000002 | 
000003 | Kristal v5 is a deterministic, portable epistemic artifact system.
000004 | 
000005 | It compiles structured epistemic work into immutable, verifiable, queryable artifacts while preserving the labels needed to understand what each assertion is, who recognizes it, how certain it is, and which reader policies may expose it.
000006 | 
000007 | ---
000008 | 
000009 | ## One-sentence definition
000010 | 
000011 | > Kristal v5 compiles Structured Epistemic States into portable and verifiable artifacts while keeping validation scoped, authority plural, certainty explicit, reader policy selectable, and disagreement preserved.
000012 | 
000013 | ---
000014 | 
000015 | ## What Kristal is for
000016 | 
000017 | Kristal is useful when you need to:
000018 | 
000019 | - preserve provenance and evidence across compilation;
000020 | - make artifacts reproducible and content-addressed;
000021 | - validate claims, corpora, datasets, or artifacts under scoped policies;
000022 | - recognize authority without pretending that one authority is universal;
000023 | - publish offline-verifiable artifacts;
000024 | - query selected material under explicit reader policies;
000025 | - federate multiple sources without flattening disagreement.
000026 | 
000027 | ---
000028 | 
000029 | ## What Kristal is not
000030 | 
000031 | Kristal is not a single global truth database.
000032 | 
000033 | It does not say that every assertion inside an artifact is universally true.
000034 | 
000035 | A Kristal may contain:
000036 | 
000037 | - hypotheses;
000038 | - claims;
000039 | - sourced statements;
000040 | - high-confidence facts;
000041 | - institutional references;
000042 | - publisher declarations;
000043 | - legal or policy positions;
000044 | - mythological corpora;
000045 | - fictional corpora;
000046 | - symbolic models;
000047 | - disputed positions;
000048 | - rejected or retracted claims.
000049 | 
000050 | The system’s job is to prevent status confusion.
000051 | 
000052 | ---
000053 | 
000054 | ## Core rule
000055 | 
000056 | A Kristal may contain uncertain, disputed, fictional, mythological, speculative, incomplete, or erroneous assertions.
000057 | 
000058 | A Kristal must not present an assertion as validated outside the authority channel, scope, certainty level, and validation policy that support that status.
000059 | 
000060 | ---
000061 | 
000062 | ## Core pipeline
000063 | 
000064 | ```text
000065 | Signal / Draft / Dataset / Submission
000066 | -> Structured Epistemic State
000067 | -> Compile
000068 | -> Working Artifact
000069 | -> Review / Validation / Attestation / Federation
000070 | -> Authority Recognition
000071 | -> Reference Artifact
000072 | -> Distribution / Runtime Pack / Reader Policy
000073 | ```
000074 | 
000075 | ---
000076 | 
000077 | ## Reader policy matters
000078 | 
000079 | Readers do not have to see everything inside an artifact.
000080 | 
000081 | A reader policy can select only:
000082 | 
000083 | - reference material;
000084 | - validated material;
000085 | - high-certainty material;
000086 | - research material;
000087 | - creative or mythological material;
000088 | - all material with labels;
000089 | - a custom combination.
000090 | 
000091 | A validated-only policy does not mean “universal truth.” It means visible assertions satisfy that policy’s validation, authority, certainty, and scope filters.
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Workflow-Activate-Rollback-Downgrade.md"
id=4ee7c65bf280
kind=markdown
size=1663
lines=79
line_ref=1-79
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Workflow: Activate, Rollback & Downgrade
000002 | 
000003 | Activation selects which artifact or Runtime Pack is active for a tenant, environment, region, service, reader policy, or authority channel.
000004 | 
000005 | Activation is separate from artifact existence and validation.
000006 | 
000007 | ---
000008 | 
000009 | ## Activation
000010 | 
000011 | Before activation, a client or platform should check:
000012 | 
000013 | - artifact identity;
000014 | - required hashes;
000015 | - required signatures;
000016 | - trust roots;
000017 | - revocation status;
000018 | - compatibility constraints;
000019 | - source artifact status;
000020 | - reader policy constraints;
000021 | - environment and tenant scope.
000022 | 
000023 | ---
000024 | 
000025 | ## Runtime Packs
000026 | 
000027 | Runtime Packs are common activation targets because they are optimized for query and offline use.
000028 | 
000029 | A Runtime Pack must preserve the source artifact status and reader-policy-relevant labels.
000030 | 
000031 | ---
000032 | 
000033 | ## Rollback
000034 | 
000035 | Rollback returns activation to a previous known-good artifact or pack.
000036 | 
000037 | Rollback should be:
000038 | 
000039 | - atomic;
000040 | - auditable;
000041 | - tied to explicit artifact IDs;
000042 | - subject to the same verification and policy checks as normal activation.
000043 | 
000044 | ---
000045 | 
000046 | ## Downgrade
000047 | 
000048 | Downgrade means selecting an older artifact or runtime surface.
000049 | 
000050 | It should be policy-gated because older artifacts may be:
000051 | 
000052 | - revoked;
000053 | - superseded;
000054 | - incompatible;
000055 | - missing required labels;
000056 | - signed by deprecated keys;
000057 | - outside an active reader policy.
000058 | 
000059 | ---
000060 | 
000061 | ## What activation does not mean
000062 | 
000063 | Activation does not mean:
000064 | 
000065 | - every assertion is universally true;
000066 | - every assertion is validated;
000067 | - all authority channels agree;
000068 | - all readers can see all material.
000069 | 
000070 | Reader policy still applies.
000071 | 
000072 | ---
000073 | 
000074 | ## Related pages
000075 | 
000076 | - [[Operations-Release-Strategy]]
000077 | - [[Operations-Compatibility]]
000078 | - [[Artifact-Runtime-Pack]]
000079 | - [[Trust-Authority-and-Signatures]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Workflow-Build-and-Validate.md"
id=1560badba1b6
kind=markdown
size=2084
lines=96
line_ref=1-96
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Workflow: Build & Validate
000002 | 
000003 | This workflow turns structured epistemic input into a compiled artifact and records validation findings without confusing validation with compilation.
000004 | 
000005 | ---
000006 | 
000007 | ## Inputs
000008 | 
000009 | Typical inputs include:
000010 | 
000011 | - Structured Epistemic State;
000012 | - extractor outputs projected into Structured Epistemic State;
000013 | - datasets;
000014 | - institutional records;
000015 | - research submissions;
000016 | - local notes;
000017 | - mythology or fiction corpora;
000018 | - previous artifacts or shard inputs.
000019 | 
000020 | ---
000021 | 
000022 | ## Build
000023 | 
000024 | The build step compiles input into a Working Exchange.
000025 | 
000026 | It should record:
000027 | 
000028 | - source references;
000029 | - build ID;
000030 | - compiler name and version;
000031 | - configuration hash;
000032 | - technical canonicalization profile;
000033 | - hash target policy;
000034 | - reproducibility-affecting policies;
000035 | - lineage.
000036 | 
000037 | ---
000038 | 
000039 | ## Validate
000040 | 
000041 | Validation may target:
000042 | 
000043 | - assertions;
000044 | - Structured Epistemic States;
000045 | - Exchanges;
000046 | - shards;
000047 | - datasets;
000048 | - Runtime Packs;
000049 | - reader policies;
000050 | - federation manifests.
000051 | 
000052 | Validation produces Validation Reports.
000053 | 
000054 | ---
000055 | 
000056 | ## Important v5 distinction
000057 | 
000058 | Validation is scoped.
000059 | 
000060 | A failed or incomplete validation does not necessarily mean the artifact cannot exist. It means the artifact or assertion must not be presented as validated outside the supporting policy, scope, certainty level, and authority channel.
000061 | 
000062 | ---
000063 | 
000064 | ## Outputs
000065 | 
000066 | Common outputs:
000067 | 
000068 | - Working Exchange;
000069 | - Validation Reports;
000070 | - warnings and errors;
000071 | - lineage records;
000072 | - optional Authority Recognition artifacts;
000073 | - optional Reference Exchange when recognition applies.
000074 | 
000075 | ---
000076 | 
000077 | ## Operational checklist
000078 | 
000079 | - [ ] Is the input represented as or projected into Structured Epistemic State?
000080 | - [ ] Are assertion statuses explicit?
000081 | - [ ] Are certainty levels explicit?
000082 | - [ ] Are validation policies declared?
000083 | - [ ] Are authority channels declared where relevant?
000084 | - [ ] Are scope fields present?
000085 | - [ ] Are provenance and evidence references preserved?
000086 | - [ ] Are build-affecting policies recorded?
000087 | - [ ] Are Validation Reports emitted?
000088 | 
000089 | ---
000090 | 
000091 | ## Related pages
000092 | 
000093 | - [[Artifact-Exchange]]
000094 | - [[Artifact-Validation-Report]]
000095 | - [[Trust-Authority-and-Signatures]]
000096 | - [[Identity-and-Determinism]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Workflow-Federation-and-Curation.md"
id=5e2fea8796e9
kind=markdown
size=1749
lines=86
line_ref=1-86
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Workflow: Federation & Curation
000002 | 
000003 | Federation composes shards from multiple scopes, publishers, or authority channels without rewriting them into a single flattened status.
000004 | 
000005 | Curation selects and labels material. It does not erase disagreement.
000006 | 
000007 | ---
000008 | 
000009 | ## When to federate
000010 | 
000011 | Use federation when you need:
000012 | 
000013 | - multiple publishers;
000014 | - multiple authority channels;
000015 | - scoped domains or subdomains;
000016 | - independent update cadence;
000017 | - tenant-specific views;
000018 | - reference and working material side by side;
000019 | - reader-policy-selected visibility;
000020 | - preserved disagreement.
000021 | 
000022 | ---
000023 | 
000024 | ## Federation inputs
000025 | 
000026 | Typical inputs:
000027 | 
000028 | - Shard Manifests;
000029 | - shard Exchanges;
000030 | - Validation Reports;
000031 | - Authority Recognition artifacts;
000032 | - Authority Registry;
000033 | - Reader Policies;
000034 | - Composition Policy.
000035 | 
000036 | ---
000037 | 
000038 | ## Composition
000039 | 
000040 | A Federation Manifest records composition rules.
000041 | 
000042 | The recommended default conflict behavior is:
000043 | 
000044 | ```text
000045 | preserve_disagreement
000046 | ```
000047 | 
000048 | This means conflicting assertions can coexist when their authority channel, validation status, certainty level, validated-as classification, or scope differs.
000049 | 
000050 | ---
000051 | 
000052 | ## Curation
000053 | 
000054 | A curator may select which shards are included and which reader policies are available.
000055 | 
000056 | Curation must preserve:
000057 | 
000058 | - source shard IDs;
000059 | - authority channels;
000060 | - validation references;
000061 | - certainty levels;
000062 | - `validated_as` labels;
000063 | - scopes;
000064 | - disagreement labels.
000065 | 
000066 | ---
000067 | 
000068 | ## Reader policy
000069 | 
000070 | Different reader policies can expose different views of the same federation.
000071 | 
000072 | For example:
000073 | 
000074 | - reference-only science education view;
000075 | - validated-only with labels;
000076 | - research-all-with-labels;
000077 | - creative/mythology view.
000078 | 
000079 | ---
000080 | 
000081 | ## Related pages
000082 | 
000083 | - [[Artifact-Federation-Manifest]]
000084 | - [[Artifact-Shard-Manifest]]
000085 | - [[Artifact-Authority-Registry]]
000086 | - [[Trust-Authority-and-Signatures]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Workflow-Publish-and-Distribute.md"
id=351582445e14
kind=markdown
size=1772
lines=84
line_ref=1-84
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Workflow: Publish & Distribute
000002 | 
000003 | Publishing makes Kristal artifacts available. Distribution moves them across stores, mirrors, clients, or platforms.
000004 | 
000005 | Publishing does not by itself make every assertion validated, recognized, or visible.
000006 | 
000007 | ---
000008 | 
000009 | ## What can be published
000010 | 
000011 | A publisher may publish:
000012 | 
000013 | - Working Exchanges;
000014 | - Reference Exchanges;
000015 | - Validation Reports;
000016 | - Authority Recognition artifacts;
000017 | - Authority Registries;
000018 | - Shard Manifests;
000019 | - Federation Manifests;
000020 | - Runtime Packs;
000021 | - Reader Policies;
000022 | - Revocation lists;
000023 | - test vectors and examples.
000024 | 
000025 | ---
000026 | 
000027 | ## Publication metadata
000028 | 
000029 | Published artifacts should preserve:
000030 | 
000031 | - artifact status;
000032 | - content hashes;
000033 | - signatures where applicable;
000034 | - validation references;
000035 | - authority recognition references;
000036 | - reader policy references;
000037 | - scope;
000038 | - lineage;
000039 | - revocation references.
000040 | 
000041 | ---
000042 | 
000043 | ## Working vs reference publication
000044 | 
000045 | A Working Artifact may be published for review, research, staging, or collaboration.
000046 | 
000047 | A Reference Artifact should indicate the authority channel, recognition status, scope, validation policy, and certainty metadata that support its reference use.
000048 | 
000049 | ---
000050 | 
000051 | ## Distribution checks
000052 | 
000053 | Consumers should enforce required verification when declared:
000054 | 
000055 | - hash checks;
000056 | - signature checks;
000057 | - trust root checks;
000058 | - revocation checks;
000059 | - compatibility checks;
000060 | - downgrade/rollback rules;
000061 | - reader policy constraints.
000062 | 
000063 | ---
000064 | 
000065 | ## Konnaxion role
000066 | 
000067 | Konnaxion distribution flows may manage:
000068 | 
000069 | - artifact retrieval;
000070 | - manifest resolution;
000071 | - signature verification;
000072 | - activation pointers;
000073 | - runtime pack delivery;
000074 | - cache and rollback state;
000075 | - reader-policy-selected access.
000076 | 
000077 | ---
000078 | 
000079 | ## Related pages
000080 | 
000081 | - [[Workflow-Activate-Rollback-Downgrade]]
000082 | - [[Artifact-Runtime-Pack]]
000083 | - [[Artifact-Federation-Manifest]]
000084 | - [[Operations-Release-Strategy]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Workflow-Subsets-Recipes.md"
id=2410faa9c84a
kind=markdown
size=1166
lines=68
line_ref=1-68
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Workflow: Subsets & Recipes
000002 | 
000003 | Subsets and recipes let builders produce scoped artifacts from larger inputs without losing determinism, provenance, or reader-policy-relevant labels.
000004 | 
000005 | ---
000006 | 
000007 | ## What a subset is
000008 | 
000009 | A subset is a selected portion of source material, such as:
000010 | 
000011 | - a domain;
000012 | - a subdomain;
000013 | - an authority channel;
000014 | - a tenant;
000015 | - a language;
000016 | - a time window;
000017 | - a reader-policy-selected view;
000018 | - a research or review slice.
000019 | 
000020 | ---
000021 | 
000022 | ## What a recipe is
000023 | 
000024 | A recipe records how the subset was selected.
000025 | 
000026 | It should be stable, explicit, and reproducible.
000027 | 
000028 | ---
000029 | 
000030 | ## What must be preserved
000031 | 
000032 | Subset generation must preserve:
000033 | 
000034 | - source identity;
000035 | - assertion IDs where possible;
000036 | - assertion status;
000037 | - certainty level;
000038 | - validation status;
000039 | - `validated_as`;
000040 | - authority channel;
000041 | - recognition status;
000042 | - scope;
000043 | - provenance;
000044 | - evidence;
000045 | - lineage.
000046 | 
000047 | ---
000048 | 
000049 | ## Where subsets appear
000050 | 
000051 | Subsets may produce:
000052 | 
000053 | - Structured Epistemic States;
000054 | - Working Exchanges;
000055 | - Reference Exchanges;
000056 | - Shards;
000057 | - Runtime Packs;
000058 | - query result bundles;
000059 | - export artifacts.
000060 | 
000061 | ---
000062 | 
000063 | ## Related pages
000064 | 
000065 | - [[Identity-and-Determinism]]
000066 | - [[Artifact-Shard-Manifest]]
000067 | - [[Artifact-Runtime-Pack]]
000068 | - [[Query-Basics]]
----- FILE END -----

----- FILE BEGIN -----
path="kristal-framework.wiki/Workflows.md"
id=1543f894e134
kind=markdown
size=804
lines=39
line_ref=1-39
chunks=0
chunk_refs=
summary="Markdown documentation."
----
000001 | # Workflows
000002 | 
000003 | Kristal v5 workflows separate compilation, validation, authority recognition, distribution, runtime activation, and reader visibility.
000004 | 
000005 | ---
000006 | 
000007 | ## Main workflow pages
000008 | 
000009 | - [[Workflow-Build-and-Validate]]
000010 | - [[Workflow-Publish-and-Distribute]]
000011 | - [[Workflow-Activate-Rollback-Downgrade]]
000012 | - [[Workflow-Subsets-Recipes]]
000013 | - [[Workflow-Federation-and-Curation]]
000014 | 
000015 | ---
000016 | 
000017 | ## End-to-end flow
000018 | 
000019 | ```text
000020 | Structured Epistemic State
000021 | -> Working Exchange
000022 | -> Validation Reports
000023 | -> Authority Recognition
000024 | -> Reference Exchange or working publication
000025 | -> Runtime Pack
000026 | -> Reader-policy selected query/render output
000027 | ```
000028 | 
000029 | ---
000030 | 
000031 | ## Key principle
000032 | 
000033 | Compilation creates portable artifacts.
000034 | 
000035 | Validation and authority recognition assign scoped status.
000036 | 
000037 | Reader policy controls visibility.
000038 | 
000039 | No workflow should confuse these layers.
----- FILE END -----

===== END VOLUME Kristal_20260612_183335_02_kristal-framework.wiki.txt =====