# INITKOA CONTEXT PACK
repository: Rejean-McCormick/kOA_Digital_Ecosystem
source_commit: 0ea910d8eeb38b962f0de8e7deefc3327cd770e6
source_mode: git
working_tree_markdown: clean
working_tree_selected: clean
selection_mode: markdown
wiki_source_commit: 830fb28abe030d070752041488d19a185057d6c1
wiki_working_tree_markdown: clean
policy_version: 2026-09-10.13
repo_files: 71
wiki_files: 29
source_files: 100
included_files: 100
excluded_files: 0
duplicate_files: 0
content_bytes: 603988
authority_counts: {"reference":100}
content_role_counts: {"knowledge":71,"navigation":29}
generated_at: 2026-09-10T13:04:24-04:00
files: 100
content_sha256: 87d10257609f88f2179a1379bc95798c983120981bf3c2d94fc42c63d8212237
================================================================================================
FILE INDEX
================================================================================================
001. [reference] [navigation] wiki/_Footer.md | bytes=812 | sha256=5f3ad57440e70f4bb84e442a2d66a6d64010e8829c6b3260602d7f7c3e142f4b
002. [reference] [navigation] wiki/_Sidebar.md | bytes=981 | sha256=983d5f4ff741cdca2790ac24885ce6dae6b4f9d8bac642fed9b4023b619027f3
003. [reference] [navigation] wiki/Artifacts-Kristal.md | bytes=3803 | sha256=b2edebb5817f0dffb9388cef01e60ed7d2d4e3819d18d1636e3ced0edb918369
004. [reference] [navigation] wiki/Artifacts-Operational.md | bytes=5065 | sha256=f5b6df29934fb28746e11804ad6cac55574f7d835a720cbecc3b1719c9031086
005. [reference] [navigation] wiki/Artifacts.md | bytes=2984 | sha256=6ad95a84d0cf74d8624efa2d064fcae8834ca02dcba4df969425fffce2c72fbf
006. [reference] [navigation] wiki/Components-Architect.md | bytes=4416 | sha256=ceb15adc5b5f1f0bc92148e63de5e2774e2567ab1493622a764407ab7260b088
007. [reference] [navigation] wiki/Components-Binah.md | bytes=4548 | sha256=bfd82af04a6dafb91a0c890658da1c921974d33f2a3d341d6e22515c2309afc4
008. [reference] [navigation] wiki/Components-Chokmah.md | bytes=5431 | sha256=97d02563ae57fee433f75b13c7b313ed38f63881a953285e0e16218fa2924a29
009. [reference] [navigation] wiki/Components-Konnaxion-and-Malkuth.md | bytes=5270 | sha256=d49d3c54204783d831dc9cc6863df5064df00817f042890c1fd250e43b76ccb3
010. [reference] [navigation] wiki/Components-Kristal-and-Daat.md | bytes=4470 | sha256=fd1460139066f8ef2f1f20b2648aa9d248dfbf3f7ba3de29e71d192d80e39f4e
011. [reference] [navigation] wiki/Components-Orgo.md | bytes=5426 | sha256=2e3041f9361a1bcf23127a139f098b785b961410805da2b17774164603dd8288
012. [reference] [navigation] wiki/Components-SenTient.md | bytes=4472 | sha256=2dc21de607303bac3a8d3160cd358ec6c20d7cd50de54afe2ed07fa6f78020e1
013. [reference] [navigation] wiki/Components-SwarmCraft.md | bytes=5075 | sha256=776f705c66c1b3e2b8ab1b8028f7bd9ed2777c1b8a3d880d0299cfbbc2235682
014. [reference] [navigation] wiki/Components.md | bytes=4249 | sha256=afbc2e228e0a1258278ffac90400f281194fa81acd073e0ca4df4d6c9e9046a0
015. [reference] [navigation] wiki/FAQ.md | bytes=3496 | sha256=2c7a3b1f9b5ef87aab0030953e16570cfc10e7bf5b5ecc9655e737fadad76e46
016. [reference] [navigation] wiki/Glossary.md | bytes=5704 | sha256=b6f6bada5cd677f67ad1b815d775ce8d31fd91b03604b442023f65cda7fc2c5a
017. [reference] [navigation] wiki/Home.md | bytes=3985 | sha256=e9b30cfe70cb1084ec0bf83b4d01de3c0c13e9901a2dc1cf8be5130ce77a1b40
018. [reference] [navigation] wiki/Integration-External-systems.md | bytes=5837 | sha256=4415d4e912cf1b1044f342cd9346e2384214405475e3e6f6810424cdb8636ec5
019. [reference] [navigation] wiki/Integration-Kristal-v4.md | bytes=3987 | sha256=20f1b79573b0dc2c02de6daeaee6ccfe2215a69a75d79bce4e500b1f6565e399
020. [reference] [navigation] wiki/Integration.md | bytes=3382 | sha256=e8fd5a11d3c04611ca883a569eec61e4fb58a38577b03e8b6880246892e70077
021. [reference] [navigation] wiki/Lifecycle.md | bytes=8489 | sha256=a0bd380b85585e61baf590ffb0540ced1b49a74b39be3a1afd39380472be0140
022. [reference] [navigation] wiki/Non-goals.md | bytes=2346 | sha256=522f9d677705082d203fe04addf22be95e9c8b5f59ae421443f12fc63c8b4f6c
023. [reference] [navigation] wiki/Operations-Builds.md | bytes=4668 | sha256=99cb6476de2837644b4b647cee7c1307f1b52a1917ce72081452b3db0c8f9f7d
024. [reference] [navigation] wiki/Operations-Incident-response.md | bytes=9030 | sha256=d05e417e14ed43881220227abcaae3dc7cafac28a5173c3fa5efffcd112eeed4
025. [reference] [navigation] wiki/Operations-Observability.md | bytes=5979 | sha256=7b4257b37bf869c0757321ca4b379ed9d0a5904b9634b95097a3096c5428c77a
026. [reference] [navigation] wiki/Operations-Releases.md | bytes=6472 | sha256=b3a503247cfa7cd4febc0f8294a0f07f4ccccd871f9545814f0e08f1ee553b08
027. [reference] [navigation] wiki/Operations-Rollbacks.md | bytes=6057 | sha256=cf98677c24b73cfcb5c01519f7816d0d05c08c893bcc28b28e6116abdbc2bc46
028. [reference] [navigation] wiki/Operations.md | bytes=4152 | sha256=1d680411e0019d66477bc98e287318f8ebf1d664589a656fd964f201d97932f7
029. [reference] [navigation] wiki/Principles-and-invariants.md | bytes=3189 | sha256=97dc92a4d0dfca742cf27e13a77334953a6dad13536804e23192180119808ffe
030. [reference] [knowledge] docs_layer-model/00_README.md | bytes=5506 | sha256=815c7efb4be28fbb98a930d82a39d4d886e35b0a7dda8e4dfd93806052f46bc1
031. [reference] [knowledge] docs_layer-model/01_LAYER_MODEL.md | bytes=17873 | sha256=a19059eb79f12948b17167802aff2908ac246ce447086b407e39af5bc5f7a4d0
032. [reference] [knowledge] docs_layer-model/02_LAYER_INDEX.md | bytes=13320 | sha256=075428e57d42c75480c77a839ad26908b06414df4d91d00cbe4df262244daddd
033. [reference] [knowledge] docs_layer-model/03_LAYER_TEMPLATE.md | bytes=8806 | sha256=bc1584c4c4ef486cdafbfc054f9c3a353bd4699117e021bf55c5ab8db1ce361c
034. [reference] [knowledge] docs_layer-model/layers/00_separation_of_functions.md | bytes=8107 | sha256=7343afd22c2ea6319529204126604b53dc21c9fa5846de2db6b968ad9ef9e282
035. [reference] [knowledge] docs_layer-model/layers/01_orientation_mandate.md | bytes=5649 | sha256=3265ac2a0c1454fbf501fa173f072b09b88325fcb9160d89b6ff869b508c867a
036. [reference] [knowledge] docs_layer-model/layers/02_semantics_meaning.md | bytes=12471 | sha256=2f81bd4d14d7338d7f376aae309452b9bdfdbd17bee1e87f6465fb9cf992d814
037. [reference] [knowledge] docs_layer-model/layers/03_provenance_ingestion.md | bytes=9618 | sha256=f32302dfee8911e1e7d5a62f1d0ee35cbcfd3f77e586c28a9dc3661d9893487c
038. [reference] [knowledge] docs_layer-model/layers/04_structured_knowledge.md | bytes=11783 | sha256=45a78ec3478b51cad1e12a13d4ed7bad339879a7944c1d462b1d9a8ec19c1a97
039. [reference] [knowledge] docs_layer-model/layers/05_validation_canon.md | bytes=7907 | sha256=b7b33aa7d641634428e77ec2effaf71e48b92935d593fb4b3fc5acd8a60e4a25
040. [reference] [knowledge] docs_layer-model/layers/06_deliberation.md | bytes=11617 | sha256=1aa3dae5957cd82ce7be7efd97d736ecdacf30f2daef5ef38dae8d0d73ff0338
041. [reference] [knowledge] docs_layer-model/layers/07_decision_legitimacy.md | bytes=10667 | sha256=110f1e6b300f02939800160921c7e260b57d39091a54c0a30744a494570dcd5c
042. [reference] [knowledge] docs_layer-model/layers/08_execution.md | bytes=10497 | sha256=544d5b950b01d186b7dcde4de7a6b2767486802eeddc7f326663cac45134521d
043. [reference] [knowledge] docs_layer-model/layers/09_memory_learning.md | bytes=8855 | sha256=bdac49397597ed842b41abb8208f8cf86ecb76f7a3ce40d4ea4304b1e2fb05c6
044. [reference] [knowledge] docs_layer-model/layers/10_resilience_autonomy.md | bytes=10693 | sha256=f37587ef697758f4a0d0fe6951db840fa8d2419043f11190b0f554075b3b4856
045. [reference] [knowledge] docs_layer-model/layers/11_learning_interface.md | bytes=9324 | sha256=b791d9ec27db0d2cadf7b74dfabca20f1ade2b6ff914c6b45a958054717f477e
046. [reference] [knowledge] docs_layer-model/layers/12_narrative_adoption.md | bytes=15268 | sha256=a8f9b09170d1a1c588f4b3f87278dcab351ccb6a0787ac930c98bd0ae54d386d
047. [reference] [knowledge] docs_layer-model/layers/13_deployment_translation.md | bytes=14475 | sha256=1ca0ea008b8e0486a18c14b0a8a6ce74f48cdac5ba196d3b73ee7504060af8f1
048. [reference] [knowledge] docs_technical/00-overview/faq.md | bytes=3496 | sha256=2609c453ddc8a89b926a29f7716f65e3d2bc2866f8ed3a68f3ee108f21dc9748
049. [reference] [knowledge] docs_technical/00-overview/glossary.md | bytes=8276 | sha256=97dc1ea00f423ea41eefa259e2e2ce99a5ab5e1c607c1816d153c8c805735dff
050. [reference] [knowledge] docs_technical/00-overview/scope.md | bytes=3818 | sha256=53895b514f20d33e17354f906c2f78a09a0f5676c5a295b121aa652b4176093b
051. [reference] [knowledge] docs_technical/00-overview/system-at-a-glance.md | bytes=2842 | sha256=bb12d067f6d51c458fdf3dfa6036b37130814a16642357d6c43fc9224ebee0dc
052. [reference] [knowledge] docs_technical/10-system/architecture.md | bytes=5898 | sha256=b5ac08b8ffa2b727d3b0fe53dca2b9e6f8504831621f0c9b7925e1b4f0e29e9b
053. [reference] [knowledge] docs_technical/10-system/components.md | bytes=6681 | sha256=1fb254c0a98b1e669b70ccc04da5e7f0cd04243b69c4d01a39f3445d774d97cc
054. [reference] [knowledge] docs_technical/10-system/determinism.md | bytes=6747 | sha256=4075ec4087f338ee75553ec5a1ef548d8eb2cc93042b2353f13244e509eb8499
055. [reference] [knowledge] docs_technical/10-system/failure-modes.md | bytes=7776 | sha256=aca7e979d2e639e40c669717cc110f5339ed2aa48415e227025cf65e101ec79b
056. [reference] [knowledge] docs_technical/10-system/lifecycle.md | bytes=8491 | sha256=6334f49a0bc78d30fdd71478f4fb80db0e91f111a7a6480e924fc7c690399781
057. [reference] [knowledge] docs_technical/10-system/trust-boundaries.md | bytes=5455 | sha256=2a59a0e3caf86dcfd9814577621a6d74ef9ac018de64fa957e8784efb1034385
058. [reference] [knowledge] docs_technical/20-nodes/binah-blueprint.md | bytes=4452 | sha256=07c85296cbe486979d580517a805d411fcd5f8f08acf4784960b7ea315118462
059. [reference] [knowledge] docs_technical/20-nodes/chesed-konnaxion.md | bytes=3656 | sha256=b59e0ab977d66c659588202c6e399e557cf47dda88f5bf2cde71d21db5ae0b41
060. [reference] [knowledge] docs_technical/20-nodes/chokmah-inputs.md | bytes=6535 | sha256=aa44f685a4115b641fc7c7df3563699b1f0d0500a92685b0a56c508316ebc0c3
061. [reference] [knowledge] docs_technical/20-nodes/daat-kristal-bridge.md | bytes=3898 | sha256=d81e7d298a5929762afaf3de6f59f9bf37c3c7229276eb9eb30551b508da0c0b
062. [reference] [knowledge] docs_technical/20-nodes/gevurah-orgo.md | bytes=7902 | sha256=ba76111a4db68714dd0c63737270028118a4bc20e8e391984170dc36d4e2ecf5
063. [reference] [knowledge] docs_technical/20-nodes/hod-architect-render.md | bytes=6867 | sha256=b02124d0d7c85a983d3b18401b5bb902f1bb0d28d59e3ebcf498d2d4cea6352e
064. [reference] [knowledge] docs_technical/20-nodes/index.md | bytes=3097 | sha256=70a25dc0f56497573dff5cb9041282c59a58e15f1dd7f506478dea24b510a0e6
065. [reference] [knowledge] docs_technical/20-nodes/keter-mandate.md | bytes=3741 | sha256=2c3fd3886bb9ac3e09b1f377d0669a9150761be8a7b6bb1de1573047dd53360b
066. [reference] [knowledge] docs_technical/20-nodes/malkuth-runtime.md | bytes=7170 | sha256=b7df294af537ac05519d3e9615119696bb1f157e8eee15a15ea746b1b5476017
067. [reference] [knowledge] docs_technical/20-nodes/netzach-architect-strategy.md | bytes=6538 | sha256=b3bef8707d8434a3e0d780c9ba322a27e493c0328e79bc208e8ae82dd10d3726
068. [reference] [knowledge] docs_technical/20-nodes/tiferet-sentient.md | bytes=6323 | sha256=034af7974799cb89f0357ca352c7215342c77d300e6cd0fe0d7915a33cd1b4ab
069. [reference] [knowledge] docs_technical/20-nodes/yesod-compiler.md | bytes=5655 | sha256=9293ce8c2228f92cd3c12097c4f694bcc91a5cfa9eefba0101f64337f466a332
070. [reference] [knowledge] docs_technical/30-artifacts/build-record.md | bytes=5927 | sha256=708aeb464ca7806cb93382a5add9ebdf78253af93ac776a7e6d49250e2c21487
071. [reference] [knowledge] docs_technical/30-artifacts/index.md | bytes=1826 | sha256=a03e8bc5320d53e52bd3973617182b0f4fc2e5c248ce1e3d6065ae97232579be
072. [reference] [knowledge] docs_technical/30-artifacts/konnaxion-state.md | bytes=4680 | sha256=ba8b90f5b1d36cf852bbeddd86cee10f9a62bacd7b13aa7c63f8fefcd67b302c
073. [reference] [knowledge] docs_technical/30-artifacts/mandate-bundle.md | bytes=2953 | sha256=ac72096ac5a192dd77c91e1f003f1a3a590702962df3ff8b78cc1dc8e1c6dfcc
074. [reference] [knowledge] docs_technical/30-artifacts/orgo-case.md | bytes=4849 | sha256=f3cda66d6b7792db91b022b8ce8b2b3f42baeb8fef0c93bdd8b6f92ad3de93e7
075. [reference] [knowledge] docs_technical/30-artifacts/orgo-task.md | bytes=7150 | sha256=0f1bf58334facc73b1898613adaa0e9ad05833948de7f809454765d2bd98223d
076. [reference] [knowledge] docs_technical/30-artifacts/release-record.md | bytes=3679 | sha256=d10e2fb5a0601040d193f79891cf045e8fdfd070046031bb8ba0cc502846591c
077. [reference] [knowledge] docs_technical/40-integration/kristal-v4/conformance.md | bytes=5118 | sha256=ff4564e3a8d4f6fd5ecf8ad7b5404f8140de609f34724b4d13b024cab8e441fd
078. [reference] [knowledge] docs_technical/40-integration/kristal-v4/contract-pointers.md | bytes=5151 | sha256=ade3499f5eb4545ce5f75c6950283f5089e62f75fce81edae95c60ee9694d065
079. [reference] [knowledge] docs_technical/40-integration/kristal-v4/index.md | bytes=2059 | sha256=d7d7c2735ca211628de226f84de21f2a04976f13bffbfd9b2dbe669ff3e376f9
080. [reference] [knowledge] docs_technical/40-integration/kristal-v4/koa-profile.md | bytes=7118 | sha256=5c219c63d2681d4d9a79bb845aaad406ffa035ac037355276ef139b989c9ba63
081. [reference] [knowledge] docs_technical/40-integration/kristal-v4/legacy-compat.md | bytes=4344 | sha256=23b0b062aba4efc740324a7b6e297250d45352d74d8e5a3497197d2e3bab1fe2
082. [reference] [knowledge] docs_technical/40-integration/kristal-v4/pinned-dependency.md | bytes=2726 | sha256=12fbf5f5fea0e1c4b48a5f258877639ad8c5968ff74fa22dae9882c0c2e9db6b
083. [reference] [knowledge] docs_technical/50-operations/incident-response.md | bytes=10186 | sha256=069c80a3d2b39c267277ec95ef0898fe85fbcd573847276cac5e2a9e38f2eb56
084. [reference] [knowledge] docs_technical/50-operations/key-management.md | bytes=5425 | sha256=549931765d5602ac7288936e5ac14f562221c05d70cefd4aaaabbf3c3cc240eb
085. [reference] [knowledge] docs_technical/50-operations/pipeline.md | bytes=4893 | sha256=5b4cc7a87fbaa3e03648fadfc6e8b78def3be9d57b3ddee03bb4cdde66cfa8d3
086. [reference] [knowledge] docs_technical/50-operations/releases.md | bytes=3541 | sha256=9231e59dcef97aa74037adaed849bcd524465ff13b8deaeb01624850eac2a194
087. [reference] [knowledge] docs_technical/50-operations/rollback.md | bytes=8789 | sha256=80526a1664da06a95be5478fbde9c09f50c789b76b1da668bdf3bcc63c8781b1
088. [reference] [knowledge] docs_technical/60-guides/implementers.md | bytes=5796 | sha256=ff8fae13a7fb6387de10db86d204c1c1ae601497fc32e50d4c6a19d46a42d674
089. [reference] [knowledge] docs_technical/60-guides/integrators.md | bytes=5365 | sha256=0938ef7575a087d190a4948001720c5b250751ba100ae2142b3bde315baa7766
090. [reference] [knowledge] docs_technical/60-guides/testing.md | bytes=4754 | sha256=42cffdfd24d00b4a5233307bf1ec9b5898bf698bb865209a19929abe4206bbc9
091. [reference] [knowledge] docs_technical/60-guides/tooling.md | bytes=3006 | sha256=b42efa5455d44955ad8e324b44bf95603c93e2ab90a57a025b731f1b73034605
092. [reference] [knowledge] docs_technical/90-reference/adr/adr-0001-truth-boundary.md | bytes=2808 | sha256=8b5f126d606f8343ff3ae34feb92acad7461c318e23eba8124a7bb4445cdbe23
093. [reference] [knowledge] docs_technical/90-reference/adr/adr-0002-determinism-policy.md | bytes=4790 | sha256=21dbf02275e596eaf1734c1bf30bd0e35681c5cb4c1f732cb93904002599a41d
094. [reference] [knowledge] docs_technical/90-reference/adr/adr-0003-konnaxion-activation-rollback.md | bytes=6650 | sha256=432edf312971e1f38b75a32ed4907503d126545cf6d19ac08afff146b49c4a7a
095. [reference] [knowledge] docs_technical/90-reference/adr/adr-0004-architect-split.md | bytes=2927 | sha256=33af0f6a845be7d71615a21a1320474da16fbf52f81218ed8df73cdeb4834f7e
096. [reference] [knowledge] docs_technical/90-reference/adr/adr-0005-compatibility-versioning.md | bytes=3865 | sha256=28f6e89fb8bff902c6b01c917f4a33a0192cb739614787cba693ad06ba976313
097. [reference] [knowledge] docs_technical/90-reference/adr/index.md | bytes=1177 | sha256=d902b03ababe39c55d1734675bf419291da5bf47caabbc20cb8a81b6608a15b2
098. [reference] [knowledge] docs_technical/90-reference/terminology.md | bytes=4381 | sha256=bff1dbc6d8b2d5ad6892daafa00b50a8238a985a9c266b218510345fb41538d8
099. [reference] [knowledge] docs_technical/index.md | bytes=2589 | sha256=6034c826804c389417fede25461b449b8ead2c1a5a934d4a024fb7662350b778
100. [reference] [knowledge] README.md | bytes=13941 | sha256=49ae6a49f498ed72e2108a59f5ad808646530e15054f13f06114bd77aa5c23fd
================================================================================================
FILE: wiki/_Footer.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 5f3ad57440e70f4bb84e442a2d66a6d64010e8829c6b3260602d7f7c3e142f4b
CONTENT_BYTES: 812
================================================================================================
---
**kOA Digital Ecosystem Wiki**
- [Home](Home) · [Lifecycle](Lifecycle) · [Components](Components) · [Artifacts](Artifacts) · [Operations](Operations) · [Integration](Integration) · [Glossary](Glossary) · [FAQ](FAQ)
**Normative boundary**
- Kristal v4 is the source of truth for Kristal artifact contracts (Exchange, Runtime Pack, Validation Report, etc.).
- This wiki documents kOA architecture, responsibilities, operational workflows, and kOA-native artifacts; it does not duplicate Kristal schemas.
- See: [Kristal v4 integration](Integration-Kristal-v4)
**Contributing**
- Propose changes via PRs and link new/updated pages from `_Sidebar.md`.
- When changing invariants or system-wide rules, add/update an ADR under `docs/90-reference/adr/` and reference it from the relevant wiki page.
---
================================================================================================
FILE: wiki/_Sidebar.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 983d5f4ff741cdca2790ac24885ce6dae6b4f9d8bac642fed9b4023b619027f3
CONTENT_BYTES: 981
================================================================================================
* [Home](Home)
* [Principles & invariants](Principles-and-invariants)
* [Non-goals](Non-goals)
* [Lifecycle](Lifecycle)
* [Components](Components)
* [Orgo](Components-Orgo)
* [Chokmah](Components-Chokmah)
* [Binah](Components-Binah)
* [SenTient](Components-SenTient)
* [Kristal & Daat](Components-Kristal-and-Daat)
* [Konnaxion & Malkuth](Components-Konnaxion-and-Malkuth)
* [Architect](Components-Architect)
* [SwarmCraft](Components-SwarmCraft)
* [Artifacts](Artifacts)
* [Kristal artifacts](Artifacts-Kristal)
* [Operational artifacts](Artifacts-Operational)
* [Operations](Operations)
* [Builds](Operations-Builds)
* [Releases](Operations-Releases)
* [Rollbacks](Operations-Rollbacks)
* [Observability](Operations-Observability)
* [Incident response](Operations-Incident-response)
* [Integration](Integration)
* [Kristal v4](Integration-Kristal-v4)
* [External systems](Integration-External-systems)
* [Glossary](Glossary)
* [FAQ](FAQ)
================================================================================================
FILE: wiki/Artifacts-Kristal.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: b2edebb5817f0dffb9388cef01e60ed7d2d4e3819d18d1636e3ced0edb918369
CONTENT_BYTES: 3803
================================================================================================
# Kristal Artifacts
**Normative for kOA:** NO
**External normative reference:** Kristal v4 (pinned)
Kristal artifacts are the **contract boundary** where “truth” becomes canonical and where offline runtime behavior is packaged for distribution. In kOA, these artifacts are **normatively defined by Kristal v4**; kOA documents only how they are used, gated, verified, and referenced.
## Non-redundancy rule
kOA **must not** duplicate Kristal schemas, field lists, canonicalization rules, or signature formats in this wiki. Instead, point to the pinned Kristal dependency and its schema/spec paths.
## Where Kristal artifacts sit in the lifecycle
```mermaid
flowchart LR
A[Ingest inputs] --> B[Extract -> Claim-IR]
B --> C[Resolve -> Resolved Claim-IR]
C --> D[Validate -> Validation Report]
D --> E[Compile -> Exchange + Runtime Pack]
E --> F[Distribute/Verify/Activate Runtime Pack]
```
High-level stage ordering reference:
## The core Kristal artifacts used by kOA
| Artifact | What it is (plain terms) | Typical producer in kOA | Primary consumer in kOA |
| -------------------------------------- | -------------------------------------------------------------------- | ----------------------- | ----------------------------------- |
| **Claim-IR** | Proposed structured claims extracted from inputs | Extractors | SenTient + Validation |
| **Resolved Claim-IR** | Claims after entity/property/literal resolution (ambiguity explicit) | SenTient | Validation + Compilation |
| **Validation Report** | Deterministic accept/reject decision + reasons | Validator | Orgo gate (“no compile on fail”) |
| **Exchange (commit + manifest)** | Canonical truth boundary (what is “canon”) | Kristal compiler | Query / Render / Export |
| **Runtime Pack (manifest + payloads)** | Offline execution boundary (what gets activated at the edge) | Kristal compiler | Konnaxion verify/activate/rollback |
## How kOA uses these artifacts (without schema details)
### 1) Validate before “truth” (hard gate)
* The Validation Report is produced deterministically and is used to authorize compilation.
* If validation fails, compilation must not proceed (“no compile on fail”).
### 2) Compile into canon + offline runtime
* Compilation produces **Exchange** (canon) and **Runtime Pack** (offline runtime form).
### 3) Verify before activation (fail-closed)
Before a Runtime Pack can become active, kOA requires **verify-before-activate** and **fail-closed** behavior (schema validity, integrity, compatibility), with **atomic activation** and deterministic rollback to last-known-good.
## What kOA records about Kristal artifacts
kOA operational artifacts (Build/Release records, Cases/Tasks) must store Kristal artifacts as **opaque references** (IDs + manifest refs / hashes), without assuming Kristal internal structure.
## Where to find the actual Kristal contracts
Use these kOA integration docs as the single pointer set:
* **Pinned dependency (how the Kristal version is pinned, and how to reference schema paths):** `40-integration/kristal-v4/pinned-dependency.md`
* **Contract pointers (exact Kristal schema paths for each artifact):** `40-integration/kristal-v4/contract-pointers.md`
* **Conformance (the gates and checks required in CI/runtime):** `40-integration/kristal-v4/conformance.md`
## Related pages
* `Artifacts-Operational` (kOA-native artifacts)
* `Integration-Kristal-v4` (integration invariant and quick start)
================================================================================================
FILE: wiki/Artifacts-Operational.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: f5b6df29934fb28746e11804ad6cac55574f7d835a720cbecc3b1719c9031086
CONTENT_BYTES: 5065
================================================================================================
# Operational Artifacts (kOA-native)
Operational artifacts are **typed payloads** used to **operate, govern, distribute, and observe** the ecosystem. :contentReference[oaicite:0]{index=0}
They do **not** redefine Kristal artifacts; they reference Kristal outputs by opaque IDs defined in the pinned Kristal spec. :contentReference[oaicite:1]{index=1}
---
## What makes an artifact “operational”
An operational artifact exists to answer questions like:
- What work was authorized and executed?
- What inputs/policies were pinned?
- What passed/failed (and why)?
- What was rolled out, where, and what is active now?
- What was rolled back, and what evidence supports that decision?
Each kOA artifact has:
- a documented contract (human-readable),
- a JSON Schema for validation, and
- explicit versioning/compat expectations. :contentReference[oaicite:2]{index=2}
---
## Operational artifact catalog
### 1) Governance artifacts (Orgo)
#### Orgo Case
A **case** is the top-level unit of governed operational work (incident, remediation, investigation, rollout review, etc.). It provides:
- a stable identifier and status,
- ownership and routing,
- links to evidence and related tasks.
#### Orgo Task
A **task** is an executable unit of work under constraints (tool/agent/human/hybrid), with pinned inputs and declared expected outputs.
Tasks are the primary way the system turns “needed action” into auditable execution and evidence linkage. :contentReference[oaicite:3]{index=3}
**Typical usage**
- “Investigate repeated validation failures”
- “Re-run build under pinned context”
- “Rollback stable channel to last-known-good”
- “Rotate trust material and verify activation”
---
### 2) Pipeline operational records
#### Build Record
A **Build Record** is the audit-grade record of a pipeline run. It must allow an auditor to reconstruct:
- exactly which input snapshots were used,
- what pinned context was applied (blueprint/mandate/policy/toolchain identity),
- which stages ran and their outcomes,
- gate decisions (especially validation),
- which outputs were produced (Kristal Exchange + Runtime Pack refs). :contentReference[oaicite:4]{index=4}
**Key invariant**
- **No compile on fail**: if validation fails, the Build Record must not claim Exchange/Runtime Pack outputs for that attempt. :contentReference[oaicite:5]{index=5}
**Why it exists**
- Reproducibility (“same pinned context → comparable results”)
- Gate accountability (“what failed, where, and why”)
- Release eligibility input (releases start from a PASS build)
---
#### Release Record
A **Release Record** captures **distribution intent** and **rollout state** for publishing verified build outputs (e.g., Runtime Packs) to channels/cohorts. :contentReference[oaicite:6]{index=6}
It binds:
- what is being released (references to build outputs),
- where it is released (channels/cohorts),
- how it is released (policy + rollout strategy),
- what happened (verification/activation outcomes, timestamps, operators, reasons). :contentReference[oaicite:7]{index=7}
**Important boundary**
- A Release Record does not mutate canonical truth; it is operational governance used by Orgo/Konnaxion. :contentReference[oaicite:8]{index=8}
---
### 3) Policy / mandate
#### Mandate Bundle
A **Mandate Bundle** is a pinned, versioned bundle of governance inputs that define what the ecosystem is allowed to do and how it must behave. :contentReference[oaicite:9]{index=9}
It exists to:
- provide a single content-addressed governance package referenced by builds/releases/audits,
- enable reproducible policy decisions,
- separate governance configuration from runtime execution and from canonical truth artifacts. :contentReference[oaicite:10]{index=10}
---
### 4) Distribution / runtime
#### Konnaxion State
**Konnaxion State** captures the local distribution/activation state of a Konnaxion instance (or cluster) in a structured, auditable form. :contentReference[oaicite:11]{index=11}
It is designed to:
- provide a consistent view of what is installed/active/pinned,
- support deterministic rollback decisions,
- correlate activation outcomes with health signals. :contentReference[oaicite:12]{index=12}
**When it’s emitted**
Konnaxion updates this record on verify/activate attempts (success or fail), rollback start/completion, pin/unpin changes, and optionally periodic heartbeat. :contentReference[oaicite:13]{index=13}
---
## How these artifacts fit together (operator mental model)
- **Orgo Case/Task**: the governed work and evidence linkage.
- **Build Record**: what ran, under what pinned context, and what passed/failed.
- **Release Record**: how a successful build was rolled out (channels/cohorts), and what happened.
- **Konnaxion State**: what is actually installed/active/pinned in runtime environments.
- **Mandate Bundle**: the pinned policy context that constrains all of the above.
---
## Related pages
- Artifacts.md
- Operations.md
- Operations-Builds.md
- Operations-Releases.md
- Operations-Rollbacks.md
================================================================================================
FILE: wiki/Artifacts.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 6ad95a84d0cf74d8624efa2d064fcae8834ca02dcba4df969425fffce2c72fbf
CONTENT_BYTES: 2984
================================================================================================
# Artifacts
Artifacts are the **typed payloads** that cross boundaries between kOA components (and between kOA and Kristal). They exist so the system can be **deterministic, auditable, and operable** without hidden shared state.
## Two artifact families
### 1) Kristal artifacts (external, normative)
Kristal defines the contracts for:
- Claim-IR / Resolved Claim-IR
- Validation Report
- Exchange (canonical truth)
- Runtime Pack (offline-executable pack) and manifests/signatures
kOA treats these as **opaque references** (IDs + manifest references) and does not restate their schemas here.
### 2) kOA-native artifacts (kOA-owned)
kOA defines artifacts needed to **operate, govern, distribute, and observe** the ecosystem. Examples:
- **Governance:** Orgo Case, Orgo Task (work + approvals + audit trail)
- **Pipeline records:** Build Record, Release Record (what ran, what passed, what was promoted)
- **Distribution/runtime state:** Konnaxion State, activation/rollback records, cache/index artifacts
- **Policy context:** Mandate Bundle (pinned policy/mandate context)
## What artifacts are for (why they exist)
Artifacts make the system:
- **Reproducible:** build/release decisions can be reconstructed from pinned references
- **Fail-closed:** gates and verification have explicit, recorded outcomes
- **Auditable:** operations leave an append-only trail of what happened and why
- **Composable:** integrations exchange references, not implicit state
## How artifacts are handled (high-level rules)
### References, not payloads
- Prefer **content-addressed references** where possible.
- Do not embed large payloads inside operational artifacts; store pointers/hashes instead.
- References should include enough context to resolve the artifact (type + ID + hash/ref).
### Opaque IDs across boundaries
- Kristal artifact IDs and internals are treated as **opaque** by kOA-native records.
- kOA records store “what” (refs + outcomes), not Kristal’s internal structure.
## Contract expectations (what “done” looks like)
Each **kOA-native** artifact should have:
- A human-readable contract page (this wiki)
- A machine-validated schema (in-repo schemas folder)
- Clear versioning/compatibility expectations
## Minimal artifact lifecycle (operator view)
1. **Produced** by a component (e.g., ingest snapshot, build record, runtime state)
2. **Referenced** by governance/work records (Case/Task) and pipeline records (Build/Release)
3. **Promoted** via release controls (channel/cohort/pinning)
4. **Activated** by Konnaxion after verification (atomic switch, rollback-safe)
5. **Superseded** by a newer build/release or rolled back to last-known-good
6. **Audited** via append-only records and stored references
## Where to go next
- For the list of kOA-native artifacts: see `Artifacts-Operational.md`
- For Kristal artifacts and authoritative contracts: see `Integration-Kristal-v4.md`
- For operational behavior (release/rollback): see `Operations.md`
================================================================================================
FILE: wiki/Components-Architect.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: ceb15adc5b5f1f0bc92148e63de5e2774e2567ab1493622a764407ab7260b088
CONTENT_BYTES: 4416
================================================================================================
# Architect (Articulation Plane)
Architect is the ecosystem’s **articulation layer**: it turns canonical knowledge into **actionable plans** and **user-facing outputs** while preserving the truth boundary.
Architect is explicitly split into two roles:
- **Architect-Strategy (Netzach):** decides *what to do next* (governed work proposals)
- **Architect-Render (Hod):** explains *what is true* (deterministic outputs with traceability)
---
## Why Architect is split
Combining planning and rendering creates failure modes (plans being treated as truth, rendering varying based on planning heuristics, feedback loops hiding provenance). The split enforces a clean separation between **governed proposals** and **deterministic articulation**.
---
## Architect-Strategy (Netzach)
### What it does
Architect-Strategy converts **canonical truth + operating context** into **governed work proposals** that Orgo can accept, decompose into Cases/Tasks, execute, and audit.
### What it produces
- Plans that map cleanly to **Orgo Cases/Tasks**
- (Optionally) rendering specs/templates selection (without inventing facts)
### Key constraints (plain language)
- Strategy proposals are **not truth**. They can recommend actions, but they do not publish or mutate canonical knowledge.
- Strategy may use heuristic/probabilistic methods, but outcomes must be captured as governed work objects.
---
## Architect-Render (Hod)
### What it does
Architect-Render turns **validated knowledge** into **user-consumable outputs** (text or structured blocks) under strict rules:
- deterministic output
- **no new facts**
- complete trace coverage (`trace_map`)
- explicit ambiguity handling
- deterministic refusal/error behavior
Architect-Render is formatting and composing—not deciding truth, not executing work.
### What it consumes (conceptual)
Architect-Render accepts only **validated** bundles derived from:
- Runtime Pack query results, or
- Exchange-derived verified query results
plus a **pinned** template/profile and rendering parameters.
### What it produces (conceptual)
A **Render Bundle** containing:
- the rendered output
- a machine-readable `trace_map`
- render metadata (template/profile version, language, etc.)
### Non-negotiable behavior
- **Accept only validated inputs** (reject unverified/untraceable provenance)
- **Deterministic rendering** (same pinned inputs + same template/profile/params ⇒ identical output and identical `trace_map`)
- **No new facts** (no “gap filling” with plausible guesses; no external factual enrichment)
- **Trace coverage** (every factual statement must trace to validated lineage; otherwise omit / mark-uncertain only if upstream uncertainty exists / or refuse)
- **Ambiguity preservation** (render ambiguity explicitly or refuse; never silently disambiguate)
- **Offline correctness** (no network dependency for factual correctness; network calls, if used for non-factual assets, must not affect factual assertions)
### Deterministic refusal (examples)
Architect-Render refuses deterministically with stable codes when, for example:
- input provenance cannot be proven (`UNVERIFIED_INPUT`)
- stable evidence identifiers are missing (`MISSING_TRACE_IDS`)
- ambiguity cannot be rendered under requested constraints (`AMBIGUOUS_INPUT`)
- render kind is unsupported (`UNSUPPORTED_RENDER_KIND`)
- projection constraints are violated (`PROJECTION_MISMATCH`)
- requested output would introduce an unsupported fact (`POLICY_VIOLATION_NEW_FACT_RISK`)
---
## Where Architect sits in the lifecycle
- **Render is Stage 7**: it runs after validation + compilation and produces Render Bundles with trace coverage.
- **Strategy feeds Orgo**: it produces governed work proposals that Orgo manages through its lifecycle and auditing.
---
## Operational signals (what operators should expect)
Architect-Render should emit, at minimum:
- Exchange/Pack reference used
- template/profile id + version
- render kind, language, (optional) projection
- determinism mode
- status + refusal/error code (if not `ok`)
- trace coverage metrics (assertions rendered / omitted / uncertain / refused)
---
## Links
- [Lifecycle](Lifecycle)
- [Artifacts](Artifacts) (Render Bundle)
- [Operations](Operations) (release/rollback behavior that keeps the runtime safe)
- [Components — Orgo](Components-Orgo)
- [Components — Konnaxion & Malkuth](Components-Konnaxion-and-Malkuth)
================================================================================================
FILE: wiki/Components-Binah.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: bfd82af04a6dafb91a0c890658da1c921974d33f2a3d341d6e22515c2309afc4
CONTENT_BYTES: 4548
================================================================================================
# Binah — Blueprint
**Normative for kOA:** YES
**External normative reference:** Kristal v4 (pinned)
Binah is the planning node that turns a **Mandate** + **available inputs** into a **Blueprint**: an explicit, auditable plan describing what will be built, how it will be grounded, and which downstream nodes execute each step.
Binah does **not** validate truth. It structures work so that truth validation downstream is possible and deterministic.
---
## Responsibility
### Binah owns
- Producing a **Blueprint** that is complete enough for deterministic execution downstream
- Declaring required inputs, grounding strategy, and which policy gates must be enforced downstream
- Assigning execution responsibilities across downstream nodes (e.g., SenTient, Architect, Compiler, Daat)
### Binah does not own
- Ground-truth resolution (SenTient)
- Kristal artifact verification or publication (Daat)
- Distribution/activation (Konnaxion)
- Governance approvals (Orgo), except to request them via work items
---
## Inputs
- **Mandate Bundle** — goals, constraints, target channels/environments, approvals state
- **Input Snapshot References** — opaque references to deterministic input sets
- **Policy Configuration** — which policy families must be enforced downstream
- **System Capabilities** — supported compilers/runtimes, target environment matrix, feature flags
---
## Outputs
### Blueprint (kOA artifact)
A Blueprint specifies:
- Plan steps with explicit stage boundaries
- Evidence/anchor requirements per step
- Policy gates (by name)
- Expected Kristal artifact *types* to be produced (by type only)
### Optional: Orgo Work Items
Requests for missing inputs, approvals, or exception handling.
### Diagnostics
Reasons planning is blocked (e.g., missing inputs, conflicting constraints).
---
## Blueprint at a glance
A Blueprint is an **ordered set of steps**. Each step should make the following explicit (kOA-level, not schema-level):
- Stable step identity
- Which node executes the step
- Which artifact types are required as inputs and expected as outputs
- Preconditions/guards (including “must be Kristal-verified” where applicable)
- Named policy gates to be enforced
- Determinism constraints (e.g., pinned toolchain required)
- Rollback plan (required when the plan targets activation channels)
Binah may include scheduling/parallelization metadata, but must not introduce nondeterministic dependencies.
---
## Guards (when Binah refuses to emit a Blueprint)
Binah must refuse to emit a Blueprint if any of the following are true:
- Mandate is missing required approvals for the requested channel(s)
- Required input snapshot references are missing or not pinned
- The plan would require producing Kristal artifacts without a declared path through Daat
- The plan depends on non-pinned tools, non-versioned policies, or “live” data without snapshot identity
- Target environments include incompatible runtime constraints without a mitigation/rollback plan
---
## Failure modes
- **F1 Input acquisition failures:** missing snapshot references, input identity ambiguity
- **F2 Planning failures:** inconsistent constraints, incomplete step guards, missing rollback plan
- **F4 Determinism failures (prevention):** plan depends on unpinned toolchain or nondeterministic execution
- **F6 Activation risk:** plan targets rollout without rollback path
---
## Operational notes
- **Idempotent planning:** if Mandate + Snapshot References + Policy Profile are unchanged, Binah must emit the same Blueprint (or a blueprint with a stable semantic hash).
- **Change control:** any change in inputs, policies, or target matrix requires a new Blueprint revision.
- **Traceability:** step outputs must remain traceable to their inputs via references captured downstream (Build/Release records).
---
## Interfaces with other nodes
- **Keter → Binah:** mandate content and governance constraints
- **Chokmah → Binah:** snapshot references for deterministic inputs
- **Binah → SenTient:** resolution steps and evidence requirements
- **Binah → Architect:** render strategy and deterministic constraints
- **Binah → Compiler:** toolchain pinning and packaging targets
- **Binah → Daat:** expected Kristal artifacts and publish/verification intent
- **Binah → Orgo:** approvals and remediation work items
---
## Related pages
- Components: Orgo, Chokmah, SenTient, Daat, Konnaxion
- Artifacts: Mandate Bundle, Build Record, Release Record
- Operations: Pipeline, Releases, Rollbacks
================================================================================================
FILE: wiki/Components-Chokmah.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 97d02563ae57fee433f75b13c7b313ed38f63881a953285e0e16218fa2924a29
CONTENT_BYTES: 5431
================================================================================================
# Chokmah (Inputs)
Chokmah is the system’s **ingest + provenance boundary**. It captures raw external inputs and turns them into **immutable, content-addressed snapshots** so downstream stages can be reproduced and audited.
Chokmah does **not** decide truth. It guarantees only that “what we saw” is captured, traceable, and replayable.
---
## Purpose
- Provide a safe, repeatable ingest boundary for raw data (files, feeds, APIs, user submissions).
- Produce stable snapshot references that the rest of the pipeline can pin to a build.
---
## Responsibilities
Chokmah **must**:
- Ingest raw materials from configured sources.
- Produce **immutable Input Snapshots** stored in a content-addressed store.
- Capture and persist **provenance** per snapshot (source identity, retrieval time, auth/context, routing tags, policy tags).
- Enforce confidentiality and access control (including encryption at rest when required).
- Provide **idempotent ingestion** (same bytes → same snapshot reference).
- Emit a deterministic, machine-readable **input set** reference for downstream builds.
- Emit deterministic ingestion results with stable error codes.
Chokmah **may**:
- Normalize transport/container formats **without changing meaning** (e.g., decode/decompress/charset normalization) only if:
- the transform is deterministic, and
- the transform is recorded explicitly in the snapshot manifest (tool id/version + steps).
Chokmah **must not**:
- Interpret, enrich, or “fix” content in a way that changes meaning without recording it as a derived artifact.
- Generate or alter canonical truth artifacts.
---
## Interfaces
### Inputs to Chokmah
**Ingest Request** (from Orgo or an ingestion orchestrator), including:
- Source descriptor (URI / connector type / credentials reference)
- Expected content type and size (if known)
- Confidentiality classification / handling constraints
- Mandate/policy tags
- Optional retention/quarantine directives
### Outputs from Chokmah
- **Input Snapshot Set**: one or more content-addressed snapshot references
- **Snapshot Manifest**:
- deterministic mapping of snapshot ref → provenance + acquisition metadata
- ingestion policy version/ref applied
- transformation steps (if any) with deterministic tooling identifiers
- integrity metadata (hashes/checksums)
- **Ingest Receipt**:
- snapshot refs created/confirmed
- errors/partial results (if any)
- diagnostics pointers
- Optional **Quarantine Report** (when content is blocked/sanitized/quarantined per policy)
---
## Snapshot identity model
- Snapshot identity is **content-addressed**: same payload bytes → same snapshot reference.
- Metadata changes do **not** change the payload reference; metadata lives in the manifest/records.
- If the source is mutable (e.g., “latest.json”), Chokmah still stores the retrieved bytes as an immutable snapshot and records retrieval context.
---
## Invariants
1) **Immutability**: once issued, snapshot bytes never change.
2) **Content addressing**: refs derive from content (and any explicitly defined deterministic packaging rules).
3) **Complete provenance**: every snapshot records where/when/how it was fetched, under what policy/authority context, and any transformations applied.
4) **Confidentiality enforcement**: restricted snapshots are encrypted at rest and access-controlled; downstream should receive only refs unless explicitly authorized to fetch bytes.
5) **Idempotent ingestion**: re-ingesting identical bytes returns the same ref; retries don’t create duplicates.
6) **Build reproducibility**: Orgo can bind a build to a stable snapshot set; downstream must not depend on live sources.
7) **No hidden enrichment**: ingest captures and packages input material; it does not introduce new facts.
---
## Error handling (fail closed)
Chokmah fails closed when it cannot guarantee correctness. Common failures include:
- Source unreachable / authentication failure
- Partial download or truncated payload
- Hash mismatch during streaming verification
- Policy violation (disallowed source / classification mismatch)
- Quarantine triggered (malware, sensitive data, unsafe content)
- Unsupported format / decoding failure
- Storage failure (cannot commit snapshot immutably)
- Malformed content violating declared type constraints (record as ingest error; do not coerce)
Errors should be structured and stable:
- `code` (stable)
- `message` (human)
- `diagnostics_ref` (pointer)
---
## Observability
Chokmah should emit:
### Metrics
- ingest requests, successes/failures
- bytes ingested, throughput
- latency per connector/source type
- retry counts and idempotency hits
- rejection/quarantine rates and reasons
### Structured logs
- request id, source descriptor hash, snapshot refs
- policy/classification decisions
- failure codes and diagnostics pointers
### Audit events
- snapshot created/confirmed
- access grants/denials
- retention/expiration actions
---
## Security and trust boundary notes
- Chokmah touches untrusted external data; treat all inputs as untrusted until committed immutably.
- Connector credentials are handled via a secure secret mechanism (never embedded in artifacts).
- Confidentiality policy is enforced consistently with mandate and operational policy.
---
## Related pages
- Components-Orgo.md
- Lifecycle.md
- Operations-Builds.md
- Artifacts-Operational.md
================================================================================================
FILE: wiki/Components-Konnaxion-and-Malkuth.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: d49d3c54204783d831dc9cc6863df5064df00817f042890c1fd250e43b76ccb3
CONTENT_BYTES: 5270
================================================================================================
# Components — Konnaxion & Malkuth
Konnaxion and Malkuth are the **distribution + runtime** pair that make “offline-first, verified knowledge” real:
- **Konnaxion (Distribution)** decides what can be installed/activated, verifies it **fail-closed**, activates it **atomically**, and rolls back **deterministically**.
- **Malkuth (Runtime)** serves deterministic queries (and optionally executes pack-defined routines) **only** over the currently active, verified pack.
---
## Konnaxion (Distribution)
### Purpose
Safely deliver Runtime Packs to environments (edge, device, offline node, cluster) and ensure that only **verified, compatible** packs become active.
### Owns
- Fetching/mirroring Runtime Packs and keeping multiple versions installed per channel/environment.
- Verification-before-activation (integrity/signature/required content).
- Compatibility checks before activation.
- Atomic activation and deterministic rollback.
- Downgrade and substitution protection (per policy).
- Offline-capable trust verification (no correctness dependency on online trust-root fetches).
### Does not own
- Defining Runtime Pack format/schemas (external).
- Deciding canonical truth (upstream of distribution).
- Rendering user-facing outputs (Architect).
- Executing tasks (SwarmCraft).
### How it works (high level)
1. **Receive** a candidate pack reference (from a release channel/index or an explicit operator action).
2. **Verify** the pack (fail-closed): parse/validate the manifest, validate integrity, validate signatures (when declared), ensure required files are present.
3. **Check compatibility** with the local runtime capabilities/profile.
4. **Activate atomically**: switch the “active” pointer from old → new with no partial states.
5. **Record state and diagnostics** for operators and Orgo (including stable reason codes on failures).
6. If needed, **rollback deterministically** (pinned known-good or last-known-good), with explicit authorization and auditability.
### Key invariants (non-negotiable)
- **Verification-before-activation** (fail-closed).
- **Compatibility is mandatory** (incompatible means no activation).
- **Atomic activation** (partial activation forbidden).
- **Deterministic rollback** (same triggers + same verified inputs → same rollback outcome).
- **Offline correctness**: trust verification must be possible offline; do not require live network trust roots for correctness.
### Operational artifact: Konnaxion State
Konnaxion emits a structured **Konnaxion State** record so operators and Orgo can see:
- what is installed,
- what is active,
- what is pinned/revoked,
- what the last attempt did and why,
- what rollback target is available.
This is an operational record; it references external artifacts by ID, it does not redefine them.
---
## Malkuth (Runtime)
### Purpose
Provide a stable runtime surface over the currently active pack:
- deterministic **query/lookup/search** over pack-provided indexes/tables, and
- optionally deterministic **execute** for pack-defined routines (policy-gated).
### Owns
- Deterministic serving over active pack payloads.
- Fail-closed refusal to serve if the active pack is not verified/compatible.
- Stable error codes and stable ordering/tie-breakers.
- Runtime safety controls (sandboxing, quotas/timeouts, deterministic-mode constraints).
### Does not own
- Activating packs (Konnaxion).
- Deciding truth or compiling canon (upstream).
- Mutating pack payloads (read-only).
- Introducing new canonical facts.
### How it works (high level)
1. Reads the **active pack pointer** as set by Konnaxion.
2. Validates that the active pack is **verified and compatible** (or refuses).
3. Serves deterministic queries over pack data structures.
4. Emits observability signals (pack identity, request ids, stable error codes, resource usage).
### Key invariants (non-negotiable)
- **No new facts**: outputs are derived only from the active pack payloads plus explicit request inputs.
- **Fail-closed** if pack verification/compatibility is not satisfied.
- **Deterministic serving**: stable outputs, stable ordering, stable tie-breakers under the same inputs/config.
- **Immutable payload**: pack is read-only.
---
## How they work together
```mermaid
flowchart LR
R[Release/Channel Index] --> K[Konnaxion]
K -->|verified + activated pack| A[(Active Pack Pointer)]
A --> M[Malkuth]
M --> C[Consumers (apps, Architect, SwarmCraft, tooling)]
K --> S[Konnaxion State (ops/audit)]
S --> O[Orgo / Ops / Monitoring]
````
* Konnaxion is the **gatekeeper**: it prevents corrupted, incompatible, revoked, substituted, or downgraded packs from becoming active.
* Malkuth is the **runtime contract**: it only serves from what Konnaxion has made active, and it stays deterministic and fail-closed.
---
## Operator cues (what to look at first)
* If a rollout “stalls”: check Konnaxion State for the last attempt’s **reason code** and whether verification or compatibility blocked activation.
* If runtime answers look inconsistent: confirm Malkuth is in deterministic mode and that the active pack identity matches expectations.
* If an incident occurs: prefer **explicit rollback** to last-known-good/pinned known-good, and preserve the audit trail.
================================================================================================
FILE: wiki/Components-Kristal-and-Daat.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: fd1460139066f8ef2f1f20b2648aa9d248dfbf3f7ba3de29e71d192d80e39f4e
CONTENT_BYTES: 4470
================================================================================================
# Kristal & Daat
Kristal is the system’s **truth compiler**. Daat is the **governed bridge** between kOA and Kristal that makes the Kristal interaction reproducible, auditable, and safe.
---
## What this component is responsible for
### Kristal (truth compiler)
- Compiles **validated knowledge** into **canonical truth artifacts**
- Produces derived runtime deliverables (e.g., **Runtime Packs**) that downstream runtime systems can verify and use offline
- Treats validation as a hard gate: **no compilation or publish of “truth” if validation failed**
### Daat (Kristal bridge)
- Pins and controls the **Kristal version** used (no floating “latest”)
- Ensures kOA only consumes/produces **Kristal-defined artifact types**
- Enforces **fail-closed** behavior at the boundary (schema/compatibility/integrity checks must pass)
- Records the operational evidence needed to reproduce and audit a build/release
---
## What it is not responsible for
- It does **not** decide what the product UI should look like (that’s rendering)
- It does **not** execute tasks or workflows (that’s execution)
- It does **not** mutate canonical truth directly via side effects (truth changes happen only through the governed pipeline)
---
## Inputs and outputs (high level)
### Typical inputs (to the Kristal boundary)
- Claim proposals (extracted facts that are not yet canonical)
- Resolution outputs (explicit decisions about entities/properties/values where needed)
- Validation policy context (what rules must be satisfied for truth to be accepted)
### Typical outputs (from the Kristal boundary)
- Validation report (pass/fail + reasons)
- Canonical truth artifacts (the compiled “truth” set)
- Runtime Pack + manifest (portable, verifiable bundle for runtime/offline use)
> Note: The exact schemas and names of Kristal artifacts are defined by the pinned Kristal version. This wiki intentionally avoids duplicating those contracts.
---
## How it works (conceptual)
1. **Pin Kristal**
- Daat selects the approved Kristal version for the environment and build.
2. **Submit staged inputs**
- kOA hands off prepared artifacts to the Kristal boundary (claims, resolutions, policy context).
3. **Validate (hard gate)**
- Kristal produces a validation report.
- If validation fails, the pipeline stops at the truth boundary.
4. **Compile**
- When validation passes, Kristal compiles canonical truth.
5. **Package**
- Kristal produces a Runtime Pack intended for verification and offline/runtime consumption.
6. **Handoff**
- Daat registers outputs as immutable build results and makes them available to distribution/release.
---
## Operational expectations
- **Reproducibility**
- The same pinned Kristal version + the same pinned inputs should produce the same canonical results (or canonically equivalent results).
- **Auditability**
- Builds and releases should be able to reference “what Kristal produced” without copying it into operational records.
- **Safety at the boundary**
- If any verification, compatibility, or integrity check fails, the system must not activate or promote outputs downstream.
---
## Common failure modes (non-technical)
- **Pinned version mismatch**
- A build tries to compile with a Kristal version that is not approved for that environment.
- **Schema/contract mismatch**
- An artifact presented to Kristal (or received from Kristal) does not conform to the expected contract.
- **Validation fails**
- The report indicates a deterministic failure; compilation and release must not proceed.
- **Pack cannot be verified**
- Downstream systems reject activation; rollback or hold is required.
---
## Upgrade and compatibility policy (practical)
- Treat Kristal upgrades like a release:
- Pin a new version
- Run conformance checks
- Roll out gradually (channels/cohorts)
- Keep rollback available to the last-known-good Kristal pin and pack lineage
---
## Quick FAQ
**Why have Daat instead of calling Kristal directly?**
To keep the truth boundary governed: pinning, fail-closed checks, and operational evidence are enforced consistently.
**Why not document the Kristal schemas here?**
To avoid drift. Kristal schemas are owned by Kristal and are referenced by pin, not duplicated in the wiki.
**Does Kristal run the product runtime?**
No. Kristal produces truth and packs. Runtime systems consume verified packs to serve queries and experiences.
================================================================================================
FILE: wiki/Components-Orgo.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 2e3041f9361a1bcf23127a139f098b785b961410805da2b17774164603dd8288
CONTENT_BYTES: 5426
================================================================================================
# Orgo (Control Plane)
**Role:** Governance + pipeline control plane.
Orgo enforces the canonical stage spine (ingest → extract → resolve → validate → compile → distribute → render/execute), applies deterministic gates, and records an auditable trail of what happened and why.
```mermaid
flowchart LR
O[Orgo
control plane] --> S[Stage spine
orchestration + gates]
S --> BR[Build Record]
S --> RR[Release Record]
S --> D[Distribute/Activate
(Konnaxion)]
S --> R[Render/Execute
(Architect/SwarmCraft)]
```
## What Orgo owns (and what it doesn’t)
### Owns
* **Stage orchestration:** enforce stage order; run stages with explicit inputs and pinned configs; idempotent retries.
* **Deterministic gating:** enforce “no compile on fail”; block downstream activation/release when integrity checks fail (fail-closed).
* **Governance workflow:** Cases/Tasks lifecycle and deterministic routing.
* **Audit + reproducibility evidence:** Build Record + Release Record; immutable audit logs for gate outcomes and governance changes.
### Does not own
* Kristal artifact formats/schemas/canonicalization rules (treated as external, pinned contracts).
## Responsibilities (operator-facing)
### 1) Enforce the stage spine
Orgo enforces an ordered pipeline from ingest through activation and feedback.
### 2) Make “truth gating” non-negotiable
If validation fails, Orgo stops the pipeline and must not run compile (“no compile on fail”).
### 3) Make releases controlled and auditable
Orgo ties an eligible build to a rollout intent (channels/cohorts/pins), monitors rollout, and drives rollback when needed—while recording the full decision trail in Release Records.
## Inputs (what Orgo listens to)
### Upstream signals
* Ingest/provenance signals (Chokmah)
* Blueprint/policy bundles (Keter/Binah)
* Resolution outputs (SenTient)
* Verification/activation telemetry (Konnaxion)
* Execution telemetry (SwarmCraft, if present)
### Operator actions
* Create/triage/resolve Cases and Tasks; approve/pin/revoke releases; trigger rebuilds/rollbacks (within policy).
## Outputs (what Orgo produces)
### kOA-native artifacts (owned by Orgo)
* Orgo Case, Orgo Task, Build Record, Release Record.
Orgo persists a **Build Record** for every pipeline execution and a **Release Record** for every promotion/publish action.
## Deterministic gates (what Orgo blocks/permits)
Orgo gates are policy-driven but must be deterministic for the same inputs/configuration.
Gate categories:
1. **Schema/contract gates:** validate kOA-native artifacts against kOA schemas; validate Kristal artifacts against pinned Kristal v4 schemas.
2. **Stage dependency gates:** stages run only when dependencies are complete/valid; compile/release prohibited unless validation passes.
3. **Integrity gates:** distribution/activation must be fail-closed; rollback must be deterministic under policy.
## Invariants (must always hold)
* **No compile on fail:** validation failure blocks compilation, release intent, and activation.
* **Explicit decisions are recorded:** policy/blueprint selection and overrides are recorded in Build/Release Records.
* **Auditability:** terminal failures include stable reason codes and traceable references.
* **Idempotent stage execution:** retries do not create ambiguous dual outputs; Orgo records what is authoritative.
* **Fail-closed rollout:** verification/compat uncertainty blocks activation unless policy explicitly overrides (and it’s recorded).
## Interfaces (recommended shapes)
### Control-plane API
* Case/Task CRUD + lifecycle transitions
* Build orchestration (start/stop/retry stage, fetch build status)
* Release orchestration (create intent, promote, pin, revoke, rollback)
* Read-only audit endpoints (gate decisions, stage timeline, artifact refs)
### Event stream
Orgo should emit events for stage start/finish/fail, gate pass/fail (with stable reason codes), Case/Task transitions, rollout milestones, rollback triggers/completion.
### Storage (non-negotiable)
Orgo persists Case/Task history, Build/Release Records, gate outcomes, and operator actions with append-only or versioned history.
## Failure modes (classes)
* Pipeline failures: missing/incorrect provenance; invalid extractor/resolver outputs; validation failures (must block compile/release).
* Governance failures: conflicting manual actions; inconsistent case/task state; intent drift vs rollout state.
* Safety failures (critical): attempted activation without verification; bypassed gates; unlogged admin changes.
## Observability (minimum)
Metrics and logs should make it easy to answer:
* What build/release is failing, where, and why?
* Which reason codes are trending?
* How often are rollbacks happening, and what triggered them?
Minimum metrics: build throughput/durations, validation pass rate and top reasons, release success/time-to-rollout, rollback frequency, case/task lead time/backlog.
Minimum logs: gate decisions with reason codes and referenced artifact IDs; operator actions with before/after state.
Recommended traces: correlate build IDs across stage jobs and downstream distribution; correlate release IDs to activation/rollback and client health.
## Related pages
* Pipeline operations (Orgo): `Operations-Builds` / `Operations`
* Orgo-native artifacts: Build Record / Release Record / Case / Task
================================================================================================
FILE: wiki/Components-SenTient.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 2dc21de607303bac3a8d3160cd358ec6c20d7cd50de54afe2ed07fa6f78020e1
CONTENT_BYTES: 4472
================================================================================================
# Components — SenTient (Resolution Plane)
**Normative for kOA:** YES
**External normative reference:** Kristal v4 (pinned) for Claim-IR / Resolved Claim-IR schemas
## Purpose
SenTient is the ecosystem’s **resolution and reconciliation engine**. It takes extracted claim proposals (Claim-IR) and produces **Resolved Claim-IR** by:
- mapping ambiguous surfaces to explicit, canonical identifiers (e.g., entities/properties),
- normalizing literals deterministically (dates, numbers, units, etc.),
- preserving unresolved ambiguity explicitly (never guessing “silently”).
SenTient sits between **Extract** and **Validate** in the stage spine: it makes claims *explicit enough* for deterministic validation and compilation.
## What SenTient owns (and why)
SenTient owns the **deterministic resolution boundary**:
- candidate selection outputs (with stable ordering + tie-breakers),
- literal normalization,
- explicit ambiguity objects (when resolution is not unique),
- structured warnings/errors that downstream gates can use.
This is what turns “probably this thing” into “these are the possible things, ranked, with reasons” (or “no valid resolution”).
## What SenTient does NOT own
SenTient does not:
- validate acceptance (that is the Validation gate),
- compile or mutate canonical truth (Kristal),
- publish artifacts to channels (Orgo/Konnaxion),
- invent missing facts or “fill gaps”.
## Inputs (conceptual)
- **Claim-IR batch** (structured claim proposals; pre-truth)
- **Resolution policy + candidate sources** (pinned versions/resources)
- Optional: provenance attachments for audit (as references)
## Outputs (conceptual)
- **Resolved Claim-IR batch** reference
- resolved identifiers where possible,
- normalized literals,
- explicit ambiguity preserved where unresolved,
- diagnostics (warnings/errors) emitted deterministically.
On **partial resolution**, SenTient still emits Resolved Claim-IR but marks affected claims as ambiguous/rejected with diagnostics.
## Key invariants
- **Deterministic behavior:** same inputs + same pinned resources/policies ⇒ same outputs.
- **Ambiguity preservation:** unresolved ambiguity must remain explicit (no silent coercion).
- **Stable ordering:** candidate lists must be stably ordered with deterministic tie-breakers.
- **Stable diagnostics:** warnings/errors use stable codes and structured parameters (not free-text-only).
Orgo decides gating rules; SenTient must provide the signals needed for those decisions.
## Error model (high-level)
SenTient emits stable warning/error codes. Typical categories include:
- entity resolution not found / ambiguous,
- property resolution not found / ambiguous,
- literal normalization invalid / lossy,
- evidence pointer invalid,
- policy violation,
- missing pinned resource/version,
- internal resolver error.
Each diagnostic should include: claim reference, field/path (when relevant), severity, and deterministic message template + parameters.
## Failure modes (examples)
- Candidate source unavailable or version not pinned
- Ambiguity too high (no deterministic selection)
- Invalid or lossy literal normalization
- Policy blocks a resolution path
- Resource integrity issue (hash/signature mismatch)
- Determinism violation (non-stable ordering, non-pinned dependency)
## Observability (minimum)
SenTient should emit:
- resolver identity/version/config reference
- input content reference(s)
- pinned policy/resource versions
- resolved-claim-ir output reference
- diagnostic code counts + key rates
Suggested metrics:
- throughput (claims/sec)
- latency (p50/p95/p99)
- candidate hit-rate (entity/property)
- ambiguity rate
- rejection rate
- normalization error rate
- resource cache hit-rate
## Security and privacy
- Treat inputs as potentially sensitive; follow tenant policy for logging/redaction.
- Resolver resources must be integrity-checked and version-pinned.
- No external network calls unless explicitly allowed by policy and audited.
## Conformance expectations (summary)
Minimum tests typically cover:
- deterministic rerun (same inputs/resources ⇒ same outputs)
- ambiguity preservation
- literal normalization golden tests
- resource pinning failures (mismatched resource ref ⇒ failure)
- diagnostic stability (codes and shapes stable across patch releases)
## Related pages
- [Lifecycle](Lifecycle)
- [Integration — Kristal v4](Integration-Kristal-v4)
- [Operations](Operations)
================================================================================================
FILE: wiki/Components-SwarmCraft.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 776f705c66c1b3e2b8ab1b8028f7bd9ed2777c1b8a3d880d0299cfbbc2235682
CONTENT_BYTES: 5075
================================================================================================
# SwarmCraft
SwarmCraft is the system’s **execution layer**. It runs **governed tasks** using already-validated knowledge, produces **telemetry**, and reports outcomes back to operations—without changing canonical truth by side effects.
---
## What SwarmCraft is responsible for
- Executing **approved tasks** derived from the pipeline (e.g., refresh jobs, checks, downstream actions)
- Enforcing **governance constraints** at runtime (what can run, where, and under which mandate)
- Producing **execution evidence**:
- task outcomes (success/failure)
- timing and performance metrics
- structured logs and traces
- retry/rollback signals (when applicable)
- Keeping execution **separate from truth**:
- SwarmCraft can *use* canonical truth and packs
- SwarmCraft does **not** create or mutate canonical truth directly
---
## What it is not responsible for
- Defining canonical truth (that’s handled upstream by validation/compilation)
- Packaging/distributing runtime packs (that’s distribution/runtime infrastructure)
- Rendering user-facing explanations (that’s rendering)
- Making release decisions (that’s operations/control plane)
---
## Inputs and outputs (high level)
### Inputs
- A **task definition** (what to do, with what limits)
- A **mandate/context** (who authorized it, policy constraints)
- References to **validated artifacts** or an **activated runtime pack**
- Execution parameters (target, schedule, scope, concurrency limits)
### Outputs
- **Task result** (success/failure + reason category)
- **Execution telemetry** (metrics/logs/traces)
- **Operational events** (alerts, escalation hooks, retry signals)
- Optional **derived artifacts** that are explicitly marked as non-canonical outputs (e.g., reports)
---
## How it works (conceptual)
1. **Receive a governed task**
- The task arrives with an explicit authorization context and constraints.
2. **Acquire the correct truth snapshot**
- SwarmCraft executes against a specified, activated pack or pinned artifact references.
- It should not “wing it” with whatever is latest.
3. **Execute with guardrails**
- Applies resource limits, timeouts, concurrency rules, and allow/deny constraints.
4. **Report outcomes**
- Emits structured results and telemetry for operations.
- Failures are classified so they can be routed (retry, hold, rollback, escalate).
5. **Feed back into governance**
- Execution outcomes become inputs for future governed work (e.g., follow-up tasks, incident handling).
---
## Task classes (examples)
- **Verification tasks**
- sanity checks, pack validation checks, drift detectors
- **Maintenance tasks**
- cache warmups, index refresh, routine housekeeping
- **Operational workflows**
- canary probes, rollout health checks, automated rollback triggers
- **External actions (controlled)**
- calling downstream systems via approved connectors, with explicit scopes and rate limits
---
## Safety and governance guarantees
- **No “new truth”**
- SwarmCraft cannot introduce facts into canonical truth. Any new knowledge must go back through the governed pipeline.
- **Pinned execution context**
- Tasks execute against a specific pack or pinned artifact set to preserve reproducibility.
- **Fail closed by default**
- If required context is missing or verification fails, the task should not proceed.
- **Evidence-first**
- Every meaningful action produces telemetry and an auditable outcome record.
---
## Common failure modes (non-technical)
- **Missing or invalid execution context**
- No approved mandate, expired authorization, or incompatible pack reference.
- **External dependency outage**
- Downstream system is unavailable; SwarmCraft records failure category and follows retry/backoff policy.
- **Resource exhaustion**
- Limits exceeded (time, memory, concurrency); task is terminated and reported.
- **Non-deterministic inputs**
- Task attempted to use “latest” rather than the pinned context; should be blocked or flagged.
- **Policy violation**
- Task attempted an action outside its allowed scope; execution is denied and logged.
---
## Operational guidance
- Prefer **small, composable tasks** with clear success criteria.
- Use **canary execution** for risky task types before broad rollout.
- Treat repeated failures as **signals for rollback/hold**, not as reasons to loosen gates.
- Keep telemetry **consistent and structured** so incidents can be triaged quickly.
---
## Quick FAQ
**Does SwarmCraft change the knowledge base?**
No. It uses validated knowledge and reports outcomes. Any change to canonical truth must go through the governed pipeline.
**Can SwarmCraft run while offline?**
It can execute tasks that only require an activated pack and local dependencies. Tasks that need external systems must be explicitly approved and handled as such.
**How is SwarmCraft related to releases?**
SwarmCraft can run health checks and rollout-related tasks, but it does not decide promotions. Operations/control plane decides.
================================================================================================
FILE: wiki/Components.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: afbc2e228e0a1258278ffac90400f281194fa81acd073e0ca4df4d6c9e9046a0
CONTENT_BYTES: 4249
================================================================================================
# Components
This page is a map of the ecosystem’s components, their responsibilities, and how they fit together. It is intentionally **not** a node spec and does **not** restate Kristal artifact schemas.
## Planes (system at a glance)
- **Control plane:** Orgo (governance, orchestration, audit)
- **Truth plane (canonical):** Kristal (Exchange + Runtime Pack)
- **Resolution plane:** SenTient (Claim-IR → Resolved Claim-IR)
- **Distribution + interface plane:** Konnaxion (verify/activate/rollback; offline delivery + navigation)
- **Articulation plane:** Architect (Strategy + Render; deterministic outputs + trace)
- **Execution plane:** SwarmCraft (governed execution + telemetry)
- **Trust + impact plane (optional):** EkoH (signals/ledger; never mutates canon)
## Where components sit in the lifecycle
```mermaid
flowchart LR
A[Chokmah
Ingest + provenance] --> B[Binah
Blueprint planning]
B --> C[SenTient
Resolve ambiguity]
C --> D[Kristal
Compile canonical truth]
D --> E[Konnaxion
Distribute + verify + activate]
E --> F[Malkuth
Runtime query/serve]
F --> G[Architect
Render with trace]
G --> H[SwarmCraft
Execute governed tasks]
H --> I[Feedback -> Orgo
New governed work]
````
## Component index (what to read next)
| Component | What it does (high-level) | Wiki page |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Orgo** | Enforces stage order + hard gates; records operational evidence; drives releases/rollbacks | [Components-Orgo](Components-Orgo) |
| **Chokmah** | Ingest boundary: turns raw inputs into immutable, provenance-pinned snapshots | [Components-Chokmah](Components-Chokmah) |
| **Binah** | Planning: converts mandate + available inputs into an auditable Blueprint (what will be built and how) | [Components-Binah](Components-Binah) |
| **SenTient** | Resolution: produces explicit, deterministic resolution outputs while preserving ambiguity when needed | [Components-SenTient](Components-SenTient) |
| **Kristal + Daat** | Truth compilation + bridge: compile canonical Exchange + Runtime Pack; enforce pinned Kristal contracts at boundaries | [Components-Kristal-and-Daat](Components-Kristal-and-Daat) |
| **Konnaxion + Malkuth** | Distribution/runtime: verify-before-activate (fail-closed), atomic activation, deterministic rollback; serve offline queries | [Components-Konnaxion-and-Malkuth](Components-Konnaxion-and-Malkuth) |
| **Architect** | Strategy + Render: propose governed work; render deterministic user-facing outputs with trace and “no new facts” | [Components-Architect](Components-Architect) |
| **SwarmCraft** | Execution: runs governed tasks, emits telemetry, does not mutate canonical truth directly | [Components-SwarmCraft](Components-SwarmCraft) |
## Boundaries (what crosses between components)
kOA components exchange **typed artifacts**, not implicit state. The main pipeline carries (by type): input snapshots, claim proposals, resolution outputs, validation evidence, canonical truth artifacts, derived runtime packs, render outputs with trace, and kOA operational artifacts (cases/tasks/records).
## Where the detailed contracts live
* Node-by-node interface specs: see [Architecture / Nodes](Components-%28Nodes%29) (and each node page)
* kOA-owned operational artifacts: see [Artifacts](Artifacts)
* Kristal artifact contracts/schemas: see [Kristal v4 integration](Kristal-v4-integration) (pinned references; not duplicated here)
================================================================================================
FILE: wiki/FAQ.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 2c7a3b1f9b5ef87aab0030953e16570cfc10e7bf5b5ecc9655e737fadad76e46
CONTENT_BYTES: 3496
================================================================================================
# FAQ
## What is this wiki?
This wiki explains the **kOA Digital Ecosystem**: what it does, its major components, and how it is operated in production.
## What is *not* in this wiki?
This wiki does **not** re-specify **Kristal** artifact contracts (schemas, canonicalization rules, signature formats, etc.). Kristal v4 remains the external source of truth for those contracts.
## Where is the Kristal spec?
See the pinned Kristal v4 reference and pointers in:
- [Integration: Kristal v4](Integration-Kristal-v4)
## What is “canonical” vs “informative” here?
- **Canonical for kOA**: ecosystem invariants, operational rules, component responsibilities, and **kOA-native** operational artifacts.
- **External canonical**: Kristal artifacts and schemas (Exchange, Runtime Pack, Validation Report, Claim-IR, Resolved Claim-IR, etc.).
## Which artifacts are “kOA-native”?
Artifacts owned by kOA components, for example:
- Orgo operational artifacts (Cases, Tasks, Build/Release Records)
- Konnaxion operational state and rollout/activation records (where standardized here)
Kristal artifacts remain externally specified.
## How do I know what schemas to validate against?
- For **kOA-native artifacts**, validate against the schemas shipped with this repo (operational artifact schemas).
- For **Kristal artifacts**, validate against the **pinned Kristal v4 schemas** referenced from the Kristal integration section.
## Why is there a hard “no redundancy” rule?
Duplicating normative contracts causes drift. kOA documentation stays stable by pointing to Kristal as the source of truth, and only documenting **kOA’s integration constraints, gates, and operational policies**.
## Where do I start if I’m implementing?
Start with:
- [Home](Home)
- [Principles & invariants](Principles-and-invariants)
- [Lifecycle](Lifecycle)
- [Components](Components)
- [Artifacts](Artifacts)
- [Integration: Kristal v4](Integration-Kristal-v4)
- [Operations](Operations)
## Where do I start if I’m operating?
Start with:
- [Operations](Operations)
- [Operations: Releases](Operations-Releases)
- [Operations: Rollbacks](Operations-Rollbacks)
- [Operations: Observability](Operations-Observability)
- [Operations: Incident response](Operations-Incident-response)
## How do changes get made safely?
- Changes to **kOA** invariants/interfaces/operational contracts should be accompanied by an ADR and conformance updates.
- Changes to **Kristal** contracts must happen in the pinned Kristal source of truth, and then kOA updates its Kristal integration profile/conformance accordingly.
## What should I do if I find a mismatch between kOA and Kristal?
Treat it as a **kOA integration issue** unless you are also changing the pinned Kristal version. Update:
- [Integration: Kristal v4](Integration-Kristal-v4)
- Any impacted operations or artifact pages that reference the integration behavior
## Does kOA require online connectivity to use Kristal artifacts?
No by default. Distribution/activation and runtime use are designed to be compatible with offline-first operation; connectivity is a deployment choice, not a contract requirement.
## What are the core components?
- **Orgo**: workflow/control plane + gating
- **SenTient**: resolution/reconciliation
- **Kristal**: truth pivot + compilation (externally specified)
- **Konnaxion**: distribution/activation + rollback safety
- **Architect**: deterministic rendering (no new facts)
- **SwarmCraft**: governed execution (optional)
================================================================================================
FILE: wiki/Glossary.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: b6f6bada5cd677f67ad1b815d775ce8d31fd91b03604b442023f65cda7fc2c5a
CONTENT_BYTES: 5704
================================================================================================
# Glossary
## Activation
Making a specific Runtime Pack the currently active pack for a target scope (environment/channel/cohort), typically as an atomic switch.
## Artifact
A versioned, typed output that crosses a component boundary (inputs/outputs/results/evidence). Artifacts are used to make runs reproducible and auditable.
## Audit trail
The recorded evidence showing what ran, what was produced, what was released, where it went, and why decisions were made.
## Blueprint
An auditable plan for a run that declares required inputs, gates, determinism constraints, and rollback expectations.
## Build
A completed pipeline run that produced eligible outputs (e.g., a Runtime Pack) and recorded evidence about inputs, policies, gates, and results.
## Canonical truth
The system’s authoritative, compiled knowledge state. It exists only after deterministic validation and compilation.
## Channel
A named release lane (e.g., canary/stable/lts) that defines rollout behavior and guardrails.
## Claim
A proposed statement about the world (an assertion) produced by extraction, before validation/compilation.
## Claim-IR
A structured representation of claims intended for validation/compilation. Pre-truth.
## Cohort
A subset of a channel (by tenant group, region, rollout percentage, etc.) used to ramp exposure gradually.
## Compile / Compilation
Transforming validated knowledge into canonical truth artifacts and derived runtime artifacts (e.g., Runtime Packs).
## Conformance
Meeting the required integration and safety expectations (e.g., pinned dependencies, schema validation, fail-closed behavior, determinism).
## Determinism
The property that the same pinned inputs, policies, and configuration produce the same outputs (or canonically identical outputs).
## Distribution
Making a Runtime Pack available to runtime systems (fetch/cache) without implying activation.
## Exchange
A standardized bundle of artifacts used to move validated/compiled knowledge across boundaries (as defined by Kristal).
## Fail-closed
If a required check cannot be completed or fails, the system must not proceed (e.g., no activation without verification).
## Feedback
Signals or observations produced downstream (runtime/rendering/execution) that are turned into new governed work, not direct truth mutation.
## Gate
A pass/fail checkpoint that must succeed before moving to the next stage (e.g., validation gate, verification gate).
## Ingest
Capturing inputs as immutable, provenance-linked snapshots so they can be audited and replayed.
## Integrity check
Verification that an artifact/pack is unmodified and complete (e.g., hash/signature/manifest checks).
## Kristal
The truth compilation subsystem and the normative source for Kristal artifact contracts (schemas/canonicalization/signing rules).
## Konnaxion
The distribution/runtime platform that fetches/caches packs, verifies them fail-closed, activates atomically, and supports deterministic rollback.
## Last-known-good (LKG)
A known safe pack/version that can be selected deterministically as a rollback target.
## Mandate Bundle
The governance and policy context used to run and release safely (rules, constraints, approvals, and references).
## Malkuth
The runtime environment that serves queries and execution over the currently active pack in a safe, repeatable way.
## Node
A named component with a clear responsibility and defined artifact boundaries.
## Orgo
The control plane: orchestrates stage ordering, enforces gates, records operational evidence, and drives releases.
## Pack / Runtime Pack
A portable, offline-capable bundle of compiled knowledge and required runtime metadata used by runtime systems.
## Pinning / Version pinning
Locking dependencies, policies, or packs to a specific version/reference to prevent “floating latest” behavior.
## Policy
The rules and constraints that govern what is allowed (validation requirements, rollout rules, downgrade prevention, logging/redaction, etc.).
## Provenance
The recorded origin and lineage of inputs and outputs (what source data was used, how it was processed, and by which versions).
## Renderer
A component that produces user-facing outputs deterministically from the active pack and must not introduce new facts.
## Resolution
The process of mapping ambiguous surfaces to explicit identifiers and normalized literals, preserving ambiguity explicitly when unresolved.
## Resolved Claim-IR
Claim-IR after resolution: explicit identifiers/normalized literals plus explicit ambiguity and diagnostics as needed.
## Release
The operational act of distributing and activating a specific Runtime Pack in target environments/channels/cohorts.
## Rollback
Restoring a previous pack/version (typically LKG or pinned prior) via a controlled, atomic activation when a release fails or regresses.
## Schema
A formal contract describing artifact structure and validation requirements.
## Stage spine
The end-to-end lifecycle of stages from ingest through feedback, used as the shared mental model for the system.
## Telemetry
Operational signals emitted by components (metrics/logs/traces/events) used for monitoring, debugging, and audit support.
## Tenant isolation
Ensuring one tenant’s data, behavior, and failures cannot affect another tenant.
## Trace
A record linking a user-facing output back to the canonical sources/artifacts it was derived from (for transparency and auditability).
## Validate / Validation
Deterministic acceptance/rejection of resolved claims against rules and constraints, producing a validation report.
## Verification
Runtime-side checks (integrity/compatibility/policy) that must pass before activation is allowed.
================================================================================================
FILE: wiki/Home.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: e9b30cfe70cb1084ec0bf83b4d01de3c0c13e9901a2dc1cf8be5130ce77a1b40
CONTENT_BYTES: 3985
================================================================================================
# kOA Digital Ecosystem
kOA is a **contract-driven pipeline** that turns raw inputs into **validated, canonical knowledge** (via Kristal) and then safely **distributes and uses** that knowledge in **offline-capable** products and workflows.
This wiki focuses on **features**, **operational behavior**, and **how the pieces fit together**—without diving into schema-level technicalities.
---
## System at a glance
### The stage spine (end-to-end)
1. **Ingest** raw inputs (snapshots + provenance)
2. **Extract** structured proposals (claims)
3. **Resolve** ambiguity (entities, properties, literals)
4. **Validate** deterministically (accept/reject with a report)
5. **Compile** canonical knowledge + a portable offline pack
6. **Distribute** packs with fail-closed verification
7. **Render** deterministic user-facing output with trace coverage
8. **Execute** work (tasks) with telemetry
9. **Feedback** becomes new governed work (never mutates canon)
```mermaid
flowchart TD
A[Mandate + Blueprint] --> B[Ingest Inputs]
B --> C[Extract -> Claim proposals]
C --> D[Resolve -> Explicit resolutions]
D --> E{Validate?}
E -- fail --> X[Stop: No Canon / No Pack / No Release]
E -- pass --> F[Compile -> Exchange + Runtime Pack]
F --> G{Verify for Activation?}
G -- fail --> Y[Reject: Fail-Closed / Rollback-or-Stay]
G -- pass --> H[Distribute Runtime Pack]
H --> I[Render -> Render Bundle + trace_map]
I --> J[Execute Tasks -> Telemetry]
J --> K[Feedback -> New Case/Task]
````
---
## Core components (who does what)
* **Orgo (control plane):** orchestrates stages, enforces gates, records operational evidence, drives releases.
* **SenTient (resolver):** turns ambiguous surfaces into explicit resolution outputs (keeps ambiguity explicit when unresolved).
* **Kristal (truth pivot):** compiles canonical truth artifacts (Exchange) and derived offline artifacts (Runtime Pack).
* **Konnaxion (distribution + platform):** verifies/activates/rolls back packs; powers offline-first delivery.
* **Architect (renderer):** produces deterministic outputs that cannot introduce new facts and must trace.
* **SwarmCraft (execution):** executes tasks under constraints; emits telemetry.
---
## The rules that keep the ecosystem safe
* **Truth boundary:** only validated + compiled artifacts become canonical; downstream does not mutate canon.
* **No compile on fail:** failed validation blocks compilation/publication.
* **Fail-closed distribution:** verification/compatibility must pass before activation; otherwise stay on current/last-known-good.
* **Atomic activation + deterministic rollback:** no partial activation; rollback is explicit and reproducible.
* **No new facts downstream:** rendering must trace to validated lineage or refuse deterministically.
See: [Principles & invariants](Principles-and-invariants)
---
## What this wiki covers (and what it doesn’t)
### In scope here
* What each component is responsible for, and how they cooperate
* Operational behavior: gates, releases, rollback, observability, incident response
* Integration expectations (without duplicating external specs)
### Out of scope (by design)
* Field-level Kristal schemas, canonicalization mechanics, signature formats, etc.
See: [Non-goals](Non-goals)
---
## How to navigate
* Want the flow: [Lifecycle](Lifecycle)
* Want the parts: [Components](Components)
* Want what crosses boundaries: [Artifacts](Artifacts)
* Want how it runs in production: [Operations](Operations)
* Want external integration: [Integration](Integration)
* Need vocabulary and quick answers: [Glossary](Glossary), [FAQ](FAQ)
---
## Who this is for
* **Implementers:** building services that produce/consume artifacts and participate in gates
* **Integrators:** connecting external systems to ingestion, distribution, or rendering
* **Operators:** running builds, releases, rollbacks, incident response, and audits
* **Architects:** evolving contracts and invariants through ADRs
================================================================================================
FILE: wiki/Integration-External-systems.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 4415d4e912cf1b1044f342cd9346e2384214405475e3e6f6810424cdb8636ec5
CONTENT_BYTES: 5837
================================================================================================
# Integration — External systems
This page describes **how kOA connects to systems outside the ecosystem** without breaking the core invariants (truth boundary, determinism, fail-closed gates, offline correctness).
kOA integrates with external systems through **explicit adapters and artifacts**—not implicit shared state.
---
## Integration map (conceptual)
```mermaid
flowchart LR
subgraph External["External systems"]
S1[Content sources\n(docs, feeds, uploads)]
S2[Systems of record\n(services, databases)]
S3[Automation\n(schedule/webhook/CI)]
S4[Identity & secrets\n(SSO, KMS/HSM, secret store)]
S5[Observability\n(logs/metrics/traces)]
S6[Runtime consumers\n(apps/services/devices)]
end
S1 --> A[Ingest adapters\n-> snapshots + provenance]
S2 --> A
S3 --> O[Orgo\ncontrol plane]
S4 --> O
S4 --> K[Konnaxion\nverify/activate/rollback]
S5 <--> O
S5 <--> K
A --> P[Pipeline stages\n(extract/resolve/validate/compile)]
P --> K --> S6
````
---
## 1) Ingest sources (how external inputs enter safely)
**Goal:** turn external inputs into **immutable snapshots with provenance**, so builds are replayable and auditable.
Common source types:
* Documents and file drops (batches)
* Feeds and APIs (polled or pushed)
* Operational inputs (tickets, incidents, runbooks)
* Manual uploads (operator-triggered)
Integration pattern:
* Build an **ingest adapter** per source type.
* The adapter produces **snapshots** (content-addressed is recommended) plus **provenance pointers** (opaque references are fine).
* Credentials and access policies are managed outside the adapter logic (see Security).
Design rules:
* Do not let “live” external state flow downstream un-snapshotted.
* Treat ingest as **capture + provenance**, not interpretation.
---
## 2) Automation triggers (how work starts)
External systems may initiate work via:
* **Manual** operator requests
* **Schedules** (cron/CI timers)
* **Webhooks** (push events from external systems)
* **Incident** triggers (operational events)
* **Release** triggers (promotion/rollback workflows)
Integration pattern:
* External triggers create or update **governed work** in Orgo (Cases/Tasks).
* Triggers must be recorded with “who/why/where from” metadata (for auditability).
Rule:
* A trigger may start work, but it **cannot bypass gates** (validation, verification-before-activation, etc.).
---
## 3) Runtime consumers (how downstream products use knowledge)
**Goal:** downstream consumers receive **verified Runtime Packs** and can operate **offline**.
Typical consumers:
* Edge nodes / devices
* Internal services that need fast local query
* User-facing applications that must remain deterministic and traceable
Integration pattern:
* Consumers talk to Konnaxion (or the platform layer it powers) to obtain packs.
* Activation is **atomic** and can be **rolled back deterministically**.
* Consumers should treat the pack as their source of facts; avoid coupling correctness to live external calls.
Rule:
* If a consumer needs “freshness,” it is handled by **controlled pack rollout**, not by bypassing the pack.
---
## 4) Security integrations (identity, secrets, key management)
**Goal:** external security platforms provide identity and cryptographic trust while kOA enforces fail-closed behavior.
What typically integrates here:
* **SSO / identity provider** (human access)
* **Workload identity** (service-to-service auth)
* **Secret manager** (adapter credentials, CI secrets, non-prod keys)
* **KMS/HSM** (distribution signing keys, trust roots, rotation)
Integration rules:
* Production verification must rely on **production-trusted keys only** (no dev/test keys).
* Key rotation must be operationally safe (planned and auditable).
* Authorization must respect environment and tenant boundaries.
---
## 5) Observability and audit integrations
**Goal:** external observability stacks make the system operable, and audit evidence stays linkable.
What to emit (minimum):
* Build and release identifiers
* Artifact references (snapshot-set, validation evidence, pack identifiers)
* Gate outcomes (validation pass/fail, verify pass/fail, activation/rollback)
* Deterministic refusal/error codes for downstream stages
Integration pattern:
* Logs/metrics/traces go to your existing stack (SIEM, metrics store, tracing backend).
* Audit evidence should be recoverable by operators and correlate to releases and rollbacks.
Rule:
* “What happened?” must be answerable from records without re-running the pipeline.
---
## 6) Multi-environment and multi-tenant considerations
Recommended separation:
* Separate channels/environments (dev/staging/prod) with distinct trust roots and signing policies.
* Explicit tenant isolation for snapshots, packs, and activation state.
* Prevent cross-environment artifact reuse unless explicitly allowed by policy.
Rule:
* Treat boundaries as security boundaries: keys, identities, and activation state should not bleed across.
---
## Integration checklist (non-technical)
Before connecting an external system, confirm:
* [ ] The integration point is an **adapter or artifact boundary**, not shared mutable state.
* [ ] Inputs become **snapshots + provenance** before entering the pipeline.
* [ ] Triggers create **governed work** and do not bypass gates.
* [ ] Runtime consumers rely on **verified packs** (offline correctness preserved).
* [ ] Keys/secrets are managed by **approved identity and key platforms**.
* [ ] Observability ties events to **build/release ids** and gate outcomes.
* [ ] Rollback story is clear (what happens on verify failure or bad rollout).
---
## Links
* [Integration (Overview)](Integration)
* [Integration — Kristal v4](Integration-Kristal-v4)
* [Operations](Operations)
* [Artifacts](Artifacts)
================================================================================================
FILE: wiki/Integration-Kristal-v4.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 20f1b79573b0dc2c02de6daeaee6ccfe2215a69a75d79bce4e500b1f6565e399
CONTENT_BYTES: 3987
================================================================================================
# Kristal v4 integration
Kristal v4 is the **normative source** for truth-compilation contracts in this ecosystem (schemas, canonicalization rules, and integrity targets). kOA integrates with Kristal by **pinning** a specific Kristal version, enforcing **fail-closed gates**, and recording **opaque references** to Kristal artifacts (not re-specifying them).
## What this integration is (in one sentence)
kOA uses Kristal v4 to turn validated inputs into **canonical truth + runtime packs**, while kOA owns orchestration, governance, release/rollback, and operational evidence.
## Integration principles
1. **Pin Kristal (no floating “latest”)**
- Builds and releases must reference a specific Kristal version.
2. **Do not duplicate Kristal contracts**
- This wiki does not restate Kristal schemas or canonicalization rules.
3. **Fail-closed boundaries**
- If validation/verification cannot be completed, the system must not compile or activate.
4. **Opaque references across the boundary**
- kOA-native records store Kristal artifact IDs/manifests/references, not Kristal internals.
## What flows between kOA and Kristal (conceptual)
### Into Kristal
- Pinned inputs (snapshots + policy context)
- Resolved/validated material required for compilation
- Compilation intent (what pack(s) to build)
### Out of Kristal
- Canonical truth artifacts (Exchange)
- Runtime artifacts (Runtime Pack + manifests)
- Evidence artifacts (Validation Report and related outputs)
kOA treats these as **Kristal-owned artifact families**.
## Where the contracts live
- **Kristal schemas/specs:** in the pinned Kristal v4 dependency (authoritative)
- **kOA integration profile:** the kOA rules for how Kristal is used (pinning, gating, release expectations)
- **Conformance tests/checks:** the minimum checks required for a build/release to be considered valid in kOA
This page stays at the “what/why” level; see `Integration.md` for the overall integration map and `Operations.md` for release/rollback behavior.
## Pinning and upgrades (operator view)
### Pinning
- The Kristal version used by a build is recorded as part of the build/release evidence.
- Different channels/environments may intentionally run different pinned versions during staged rollouts.
### Upgrading
Upgrades are treated like a controlled change:
1. Pin the new Kristal version (explicitly).
2. Run conformance checks.
3. Build packs in a pre-production channel.
4. Canary rollout with monitoring.
5. Promote to stable if gates remain green; rollback if integrity or behavior deviates.
## Conformance expectations (plain language)
A conformant kOA↔Kristal integration should ensure:
- **Typed artifact boundaries** (no hidden shared state)
- **Schema validation** against the pinned Kristal version
- **Fail-closed behavior** at compilation and activation boundaries
- **Deterministic builds** for pinned inputs/policies/configuration
- **Auditable evidence** (records that show what ran and what was promoted)
## What kOA owns vs what Kristal owns
### kOA owns
- Orchestration and gates (control plane)
- Governance workflow and operational evidence (build/release records)
- Distribution/activation/rollback mechanics
- Observability and incident process
### Kristal owns
- Normative schema contracts for Kristal artifacts
- Canonicalization rules and integrity targets for truth artifacts and runtime packs
- The artifact family definitions themselves
## Common integration failures (non-technical)
- “Drift”: Kristal version was not pinned consistently across build/release.
- “Contract mismatch”: artifacts validated against the wrong Kristal version.
- “Best-effort activation”: pack was activated without full verification.
- “Leaky boundary”: downstream layers treat non-canonical outputs as truth.
## Related pages
- `Integration.md` (overall integration map)
- `Operations.md` (release/rollback behavior)
- `Artifacts.md` (artifact families and why they exist)
================================================================================================
FILE: wiki/Integration.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: e8fd5a11d3c04611ca883a569eec61e4fb58a38577b03e8b6880246892e70077
CONTENT_BYTES: 3382
================================================================================================
# Integration
This section explains how external systems integrate with the kOA Digital Ecosystem—without requiring you to learn internal schemas or deep implementation details.
## What “integration” means here
An integration is any system that:
- produces inputs that flow toward canonical truth,
- implements a pipeline stage under Orgo control,
- consumes runtime knowledge (Runtime Packs) through Konnaxion/Malkuth,
- or needs to interoperate with Kristal v4 artifacts at the contract boundary.
## Non-negotiable integration rules
- **Do not duplicate Kristal contracts.** Kristal v4 is the sole normative source for Kristal artifact schemas/contracts. kOA points to the pinned Kristal source-of-truth.
- **Pin Kristal v4.** Never integrate against “latest”; always integrate against a pinned Kristal version + pinned schema pointers.
- **Fail-closed.** If verification/validation cannot be proven, do not proceed. No “best effort” activation or truth compilation paths.
- **Opaque references.** kOA operational records store opaque references to Kristal artifacts (IDs + manifest refs), not re-parsed Kristal internals.
## Integration entry points (choose what you are)
### 1) Input producer (upstream)
You provide raw inputs/evidence that will eventually become canonical through validation + compilation. Expect to provide stable provenance and replayable snapshots (so builds can be reproduced).
### 2) Stage service (pipeline component)
You implement a stage (e.g., extractor, resolution adjunct, validation adjunct) that Orgo orchestrates. Your contract is: accept explicit artifact references, produce explicit artifacts, be retry-safe, and emit stable reason codes.
### 3) Distribution/runtime consumer
You run Konnaxion (or consume its outputs) to deliver offline-first Runtime Packs to runtime environments. Your contract is: verify-before-activate, atomic activation, deterministic rollback, and auditable events.
## Where the authoritative contracts live
- **Kristal v4 boundary contracts (pinned):** see [Integration-Kristal-v4](Integration-Kristal-v4)
- **kOA operational expectations (gates, rollout, rollback, evidence):** see [Operations](Operations)
- **Practical checklists/patterns:** see Integrator Guide (optional) in the main docs set (not duplicated in the wiki)
## Quick start checklist
1. Confirm the pinned Kristal v4 dependency used by this repo.
2. Produce/consume Kristal artifacts using the pinned Kristal schema pointers.
3. Apply the kOA profile defaults (verification/activation expectations).
4. Run the conformance suite (determinism + fail-closed + rollback).
5. If migrating legacy formats, use the documented legacy-compat window and deprecation path.
## Telemetry expectations (high level)
Integrations should emit:
- build/release correlation IDs (from Orgo),
- stage timing and stable error codes,
- references to logs/traces (not raw blobs in-band),
- activation/rollback outcomes and health signals (if distribution/runtime).
## Security expectations (high level)
- Never leak secrets into logs/telemetry.
- Treat verification (schema/integrity/signature/compatibility) as mandatory gates.
- Prefer least privilege and audit-grade logging for privileged actions.
## Next pages
- [Integration-Kristal-v4](Integration-Kristal-v4)
- [Integration-External-systems](Integration-External-systems)
================================================================================================
FILE: wiki/Lifecycle.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: a0bd380b85585e61baf590ffb0540ced1b49a74b39be3a1afd39380472be0140
CONTENT_BYTES: 8489
================================================================================================
# Lifecycle (kOA end-to-end)
**Purpose:** Define the end-to-end lifecycle of the ecosystem: how raw inputs become validated canonical truth (Kristal Exchange), how that truth becomes portable offline execution artifacts (Runtime Packs), how outputs are rendered deterministically, how work is executed, and how feedback re-enters the system without mutating canon.
---
## 1) Key terms
- **Build:** A governed run of the pipeline producing a new Kristal Exchange + Runtime Pack (or failing before canon).
- **Release:** A distributed publication of a Runtime Pack (and associated metadata) through Konnaxion.
- **Case / Task:** Orgo’s governance units. A **Task** is the atomic unit of work; a **Case** groups tasks over time.
- **Canon:** Kristal Exchange (the authoritative, immutable truth artifact).
- **Derived:** Runtime Pack and Render Bundles (must be traceable to canon + pinned configuration).
- **Gate:** A deterministic acceptance point; failure blocks downstream stages (fail-closed when integrity is declared).
---
## 2) Lifecycle overview
### 2.1 High-level stage spine
0) Load Mandate + Blueprint
1) Ingest inputs
2) Extract Claim-IR
3) Resolve Claim-IR (SenTient)
4) Validate (Orgo gate)
5) Compile canon + runtime (Kristal)
6) Publish/Distribute (Konnaxion)
7) Render outputs (Architect-Render)
8) Execute work (SwarmCraft)
9) Feedback → new governed work (Orgo)
### 2.2 Mermaid (conceptual)
```mermaid
flowchart TD
A[Mandate + Blueprint] --> B[Ingest Inputs]
B --> C[Extract -> Claim-IR]
C --> D[Resolve -> Resolved Claim-IR]
D --> E{Validate?}
E -- fail --> X[Stop: No Canon / No Pack / No Release]
E -- pass --> F[Compile -> Exchange + Runtime Pack]
F --> G{Verify for Activation?}
G -- fail --> Y[Reject: Fail-Closed / Rollback-or-Stay]
G -- pass --> H[Distribute Runtime Pack]
H --> I[Render -> Render Bundle + trace_map]
I --> J[Execute Tasks -> Telemetry]
J --> K[Feedback -> New Case/Task]
K --> C
```
---
## 3) Stage-by-stage specification
Each stage specifies: **Owner**, **Inputs**, **Outputs**, **Gate**, **Observability**.
### Stage 0 — Mandate + Blueprint load
**Owner:** Keter (Mandate) + Binah (Blueprint), enforced by Orgo.
**Inputs**
- Mandate bundle (scope, constraints, success criteria)
- Blueprint bundle (schemas, ontologies, policies, versions)
**Outputs**
- Pinned runtime context reference (immutable refs to mandate + blueprint)
**Gate**
- Must refuse to run without an active mandate (when required by policy).
- Must pin exact blueprint revisions used for the build.
**Observability**
- mandate_ref, blueprint_ref, policy pins
- correlation IDs (build_id / request_id if present)
---
### Stage 1 — Ingest (raw inputs)
**Owner:** Chokmah (Inputs adapters), orchestrated by Orgo.
**Inputs**
- Source documents, feeds, uploads, connectors
- Ingest policy + provenance rules (from Blueprint)
**Outputs**
- Input snapshots (immutable snapshot refs)
- Optional snapshot set manifest (listing snapshots + provenance pointers)
**Gate**
- Provenance must be preserved.
- Snapshots must be immutable (content-addressed strongly recommended).
**Observability**
- ingest adapter version/config ref
- snapshot IDs, snapshot-set ref
- provenance pointers (opaque refs allowed)
---
### Stage 2 — Extract → Claim-IR
**Owner:** Extractor(s), governed by Orgo.
**Inputs**
- Input snapshots (or snapshot-set ref)
- Claim-IR schema/policy (pinned from Blueprint)
**Outputs**
- Claim-IR batch reference
**Gate**
- Extractors must output proposals only (no “truth”).
- Evidence pointers and uncertainty markers must be preserved.
**Observability**
- extractor identity/version/config ref
- input snapshot refs used
- claim-ir ref
---
### Stage 3 — Resolve → Resolved Claim-IR (SenTient)
**Owner:** SenTient, governed by Orgo.
**Inputs**
- Claim-IR batch
- Resolution policy + candidate sources (pinned)
**Outputs**
- Resolved Claim-IR batch reference (with explicit ambiguity preserved)
**Gate**
- Must be deterministic under pinned policy/config.
- Must preserve unresolved ambiguity explicitly (no silent coercion).
**Observability**
- resolver identity/version/config ref
- warnings/errors summary (stable codes)
- resolved-claim-ir ref
---
### Stage 4 — Validate (deterministic acceptance gate)
**Owner:** Validation engine, enforced by Orgo.
**Inputs**
- Resolved Claim-IR
- Validation policy/profile set (pinned)
**Outputs**
- Validation Report reference
**Gate (hard)**
- If validation fails, compilation must not proceed (“no compile on fail”).
**Observability**
- validator identity/version/config ref
- validation report ref
- gate decision + reason codes
---
### Stage 5 — Compile (Kristal)
**Owner:** Kristal compiler, invoked by Orgo after Stage 4 pass.
**Inputs**
- Resolved Claim-IR
- Validation Report (pass)
- Compiler config + pinned profiles/policies
**Outputs**
- Kristal Exchange (+ Exchange Manifest)
- Runtime Pack (+ Runtime Pack Manifest)
**Gate**
- Must produce schema-conformant artifacts (Kristal-owned schemas).
- Must record reproducibility metadata sufficient for rebuild determinism (via manifests/build records).
**Observability**
- compiler identity/version/config ref
- exchange refs + pack refs
- manifest refs
- content-hash / signature verification results (if produced)
---
### Stage 6 — Publish / Distribute (Konnaxion)
**Owner:** Konnaxion (distribution facet), triggered and tracked by Orgo.
**Inputs**
- Runtime Pack + manifest
- Channel/release intent (from Orgo)
- Trust roots / revocation info (tenant-scoped)
**Outputs**
- Published artifacts in channel(s)
- Activation/verification status updates
- Rollback records (when applicable)
**Gate (hard)**
- If integrity material is declared (hash/signatures), verification must be fail-closed.
- Activation must be atomic; rollback must be deterministic.
**Observability**
- verification results (pass/fail + codes)
- active pack ID, previous pack ID
- rollout cohort/channel + timestamps
---
### Stage 7 — Render outputs (Architect-Render)
**Owner:** Architect-Render.
**Inputs**
- Kristal query results (from Exchange and/or Pack, per policy)
- Render template + parameters (pinned)
- Render policy (no-new-facts + trace requirements)
**Outputs**
- Render Bundle (includes trace coverage)
**Gate (hard)**
- Rendering must not introduce new facts.
- Output must be deterministic under pinned inputs/template/params.
- If trace coverage is insufficient, renderer must deterministically omit / mark-uncertain / refuse per policy.
**Observability**
- renderer identity/version/config ref
- template + params refs
- render bundle ref + trace coverage metrics
---
### Stage 8 — Execute work (SwarmCraft)
**Owner:** SwarmCraft (or equivalent execution plane), governed by Orgo.
**Inputs**
- Orgo Tasks (and required inputs)
- Execution policy (resource caps, tool allow-lists)
**Outputs**
- Execution results
- Telemetry events
**Gate**
- Must follow deterministic policy where required (stable toolchain versions, fixed seeds when applicable).
- Must emit telemetry sufficient for audit and feedback routing.
**Observability**
- task_id, case_id, correlation IDs
- result refs
- telemetry refs
---
### Stage 9 — Feedback → new governed work
**Owner:** Orgo (ingestion of signals).
**Inputs**
- Telemetry, user feedback, ops events, trust/impact signals
**Outputs**
- New Cases/Tasks (governed work items)
- Optional prioritization/triage updates
**Gate**
- Feedback must not mutate canon directly.
- Any canon-affecting change must be a new build (new artifacts, new IDs).
**Observability**
- signal source + classification
- created case/task IDs + routing
- linkage to triggering build/release IDs (when applicable)
---
## 4) Cross-cutting hard rules (summary)
- **No compile on fail:** Stage 4 fail blocks Stage 5.
- **Fail-closed integrity:** Any declared hashes/signatures must verify before activation/publish.
- **Immutable canon:** Exchange is never edited in place; updates produce new artifacts/IDs.
- **No new facts downstream:** Rendering cannot invent; it must trace or refuse deterministically.
---
## 5) Pointers
- Build orchestration details: `Operations-Builds.md` / `Operations.md`
- Releases + rollback: `Operations-Releases.md`, `Operations-Rollbacks.md`
- Kristal v4 integration: `Integration-Kristal-v4.md`
- Conformance and testing: `Operations-Observability.md` / `Reference` pages
================================================================================================
FILE: wiki/Non-goals.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 522f9d677705082d203fe04addf22be95e9c8b5f59ae421443f12fc63c8b4f6c
CONTENT_BYTES: 2346
================================================================================================
# Non-goals
This page defines what kOA (and this wiki) intentionally does **not** try to be. These boundaries prevent drift, “best effort” correctness, and accidental duplication of external contracts.
## 1) Not a restatement of Kristal
- This wiki does **not** restate or re-implement Kristal’s normative artifact definitions (schemas, canonicalization, hashing, signing targets).
- When Kristal details are needed, we **link** to the pinned Kristal v4 source and kOA’s integration pointers.
## 2) Not a schema catalog for boundary artifacts
- We do not list field-by-field schemas for Claim-IR, Resolved Claim-IR, Validation Report, Exchange, Runtime Pack, Render Bundle, etc.
- We describe where each artifact sits in the lifecycle and what kOA requires at the boundary (gates, verification, determinism), not the artifact internals.
## 3) Not product marketing or a user manual
- No product marketing, UX copy, or end-user documentation for specific applications built on top of kOA.
- Only ecosystem-level behavior, responsibilities, and operational expectations.
## 4) Not a deployment/topology specification
- No cloud-vendor specifics, infrastructure wiring, or full deployment topology.
- Ops content focuses on portable procedures (release/rollback/incident response), not “how to run it on Vendor X”.
## 5) Not an “always-available” system that trades correctness for uptime
- No “best effort” integrity checks at truth-compilation or activation boundaries.
- If declared verification cannot be completed, the correct behavior is to **stop/deny/rollback**, not to proceed.
## 6) Not a mutable truth store
- Canonical truth is not hot-edited during incidents or runtime.
- Fixes happen by creating new governed work and producing new versions, not patching canon in place.
## 7) Not an ungoverned execution platform
- Nothing executes “just because it can.”
- Execution is expressed as governed work with recorded inputs/outputs and auditability.
---
## If you were looking for…
- **Kristal schemas/contracts:** see **Integration → Kristal v4** (pinned dependency + contract pointers).
- **What kOA does cover:** see **Architecture**, **How it works (Lifecycle)**, **Components**, **Artifacts**, and **Operations**.
- **Operational safety rules:** see **Operations → Incident response**.
================================================================================================
FILE: wiki/Operations-Builds.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 99cb6476de2837644b4b647cee7c1307f1b52a1917ce72081452b3db0c8f9f7d
CONTENT_BYTES: 4668
================================================================================================
# Operations — Builds
This page explains how kOA runs **builds** in operational terms (no schema deep-dives).
A **build** is one governed pipeline run that *attempts* to produce:
- a **Kristal Exchange** (canonical truth), and
- a **Runtime Pack** (portable/offline runtime artifact),
with full audit evidence.
---
## 1) What a build is (and is not)
A build is:
- reproducible under pinned inputs/config/policies,
- gated (deterministic pass/fail),
- auditable (a Build Record exists for every attempt).
A build is not:
- a “best effort” job that partially publishes on failure,
- a way to hot-edit canon (canon changes require a new build).
---
## 2) Preconditions (before you start)
A build must have:
- a pinned **Blueprint** (schemas/config/policies),
- a pinned **Mandate** when required (governance/approvals),
- a defined input surface (sources/tenants/scope),
- a place to persist artifacts and operational records.
Operational rule: Orgo must be able to persist a **Build Record** for every attempt.
---
## 3) Stage spine (normative ordering)
Orgo enforces this ordered spine:
1. **Ingest** → input snapshots recorded
2. **Extract** → Claim-IR produced
3. **Resolve** → Resolved Claim-IR produced
4. **Validate** → Validation Report produced (**acceptance gate**)
5. **Compile** → Exchange + Runtime Pack produced
6. (Optional in build flow) **Distribute / Activate** happens via Release operations
Hard rule: **If Validate fails, the build stops and must not Compile** (“no compile on fail”).
---
## 4) What gets recorded (Build Record)
Every build attempt produces a **Build Record** that allows someone to reconstruct:
- exactly which inputs were used,
- what was pinned (blueprint/mandate/policies/tool identities),
- which stages ran and in what order,
- the gate decisions (especially validation),
- which outputs were produced (or explicitly absent on failure).
The Build Record is the primary operational evidence for:
- audits,
- reproducibility checks,
- release eligibility decisions,
- incident triage.
---
## 5) Gates (what can block the build)
### 5.1 Validation gate (hard)
- Deterministic pass/fail.
- On FAIL: stop; persist the Validation Report reference; open a triage Case/Task if required by policy.
### 5.2 Schema/contract checks (hard where applicable)
- Produced artifacts must be schema-valid against the pinned contracts (Kristal-owned for Kristal artifacts; kOA-owned for kOA artifacts).
### 5.3 Integrity checks (policy-defined)
- If hashes/signatures are declared, verification is fail-closed (no bypass).
---
## 6) Outputs (what “success” means)
A successful build produces references to:
- Validation Report (PASS),
- Exchange + Exchange Manifest,
- Runtime Pack + Runtime Pack Manifest,
and records them in the Build Record.
A failed build produces:
- Build Record (FAIL),
- the most recent stage outputs (as refs),
- deterministic failure reason codes,
- **no** Exchange/Runtime Pack outputs if validation did not pass.
---
## 7) Reruns and idempotency (operational expectations)
- Re-running a build with the **same pinned context** should yield identical (or canonically identical) outputs.
- Retries should not create ambiguous “double outputs”: the Build Record must make it clear which attempt/output is authoritative.
- If determinism cannot be met, move nondeterminism upstream and freeze it as an input artifact.
---
## 8) Common failure classes (operator view)
- Ingest: missing provenance, access policy rejection, snapshotting failure
- Extract/Resolve: schema-invalid outputs, unstable ordering, unresolved ambiguity mishandled
- Validate: deterministic rejection (expected), or unstable rejection (investigate determinism)
- Compile: compiler failure or non-conformant output (block downstream)
- Environment/tooling: unpinned dependency drift, incompatible pins, artifact store failures
---
## 9) Operator checklist (quick)
1. Identify `build_id`
2. Retrieve the Build Record
3. Confirm pinned context: blueprint/mandate/policy/tool identities
4. Inspect stage timeline + first failing stage
5. For validation failures: retrieve Validation Report ref and failure codes
6. Confirm “no compile on fail” was respected
7. If recurring failures: open/attach Orgo Case and track remediation tasks
---
## 10) Links
- Pipeline runbook (stage-by-stage operational checks): `Operations.md` / pipeline references
- Releases (turn builds into controlled rollouts): `Operations-Releases.md`
- Rollbacks (when distribution/activation goes wrong): `Operations-Rollbacks.md`
- Artifact evidence: `Artifacts.md` → Build Record / Release Record
================================================================================================
FILE: wiki/Operations-Incident-response.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: d05e417e14ed43881220227abcaae3dc7cafac28a5173c3fa5efffcd112eeed4
CONTENT_BYTES: 9030
================================================================================================
# Operations — Incident response
**Status:** Normative (kOA)
**External normative references:** Kristal v4 docs + schemas (pinned dependency)
---
## 1) Purpose
Provide a deterministic, auditable procedure for detecting, triaging, mitigating, and resolving incidents across:
- Orgo build pipeline (validation/compile/publish)
- Konnaxion distribution/activation/rollback
- Architect rendering (trace / no-new-facts)
- SwarmCraft execution (side effects + telemetry)
- Trust roots / keys / revocations
- Multi-tenant isolation
This runbook avoids schema-level duplication. When you need artifact formats, follow the pinned Kristal references or kOA-native schemas.
---
## 2) Non-negotiable rules
1. **Fail-closed on declared integrity** (no bypass on signature/hash failures).
2. **No canon mutation under incident pressure** (no “hot edits” to canon).
3. **Prefer rollback over patching** when a publish/activation broke consumers.
4. **Preserve evidence** (snapshot first; do not overwrite).
5. **Tenant isolation always** (no cross-tenant “quick fixes”).
---
## 3) Roles and ownership
- **Incident Commander (IC):** timeline, decisions, comms, final resolution call.
- **Operations Lead (Ops):** freezes/holds, rollbacks, rollout controls.
- **Security Lead (Sec):** keys, trust roots, revocations, tampering response.
- **Orgo Lead:** pipeline gates, reproducibility, publish controls.
- **Konnaxion Lead:** activation/rollback, channel integrity, cache/runtime state.
- **Architect Lead:** render determinism, trace coverage, template/model regressions.
- **SwarmCraft Lead:** execution failures, telemetry integrity, side-effect containment.
---
## 4) Severity model
- **SEV0:** active compromise, cross-tenant breach, or integrity-bypass risk.
- **SEV1:** system-wide outage or incorrect canon distribution (bad pack broadly activated).
- **SEV2:** major degradation or correctness risk limited to a subset.
- **SEV3:** minor degradation, localized issue, workaround exists.
- **SEV4:** informational / no user impact.
Escalate to **SEV0/SEV1** when integrity or isolation is uncertain (signature/hash failures at scale, downgrade/substitution attempts, key compromise suspicion, cross-tenant mixing, or regulated “no-new-facts” violations).
---
## 5) Triage checklist (first 10 minutes)
### 5.1 Stabilize
- [ ] Assign IC + required leads.
- [ ] Freeze risky automation if it could worsen impact (publishes, auto-activation, key rotation).
- [ ] Establish incident channel + single source of timeline truth.
### 5.2 Identify scope
- [ ] Which tenants/channels/environments are impacted?
- [ ] Which stage is failing: build, publish, activation, render, execute?
- [ ] Is this correctness, availability, or security?
### 5.3 Preserve evidence (before destructive actions)
Snapshot:
- [ ] Orgo Build Record + stage logs
- [ ] Validation report(s) for failing builds
- [ ] Runtime Pack Manifest + channel index (as received)
- [ ] Konnaxion activation/local state (active pack, LKG, rejection reasons)
- [ ] Render bundles + trace maps for affected outputs
- [ ] SwarmCraft execution envelopes + telemetry for affected tasks
- [ ] Trust root set (per channel) + revocation state
---
## 6) Containment and mitigation playbooks
### 6.1 Bad release / bad pack activated
**Goal:** stop spread and restore last-known-good deterministically.
- [ ] Pause auto-activation for affected channel(s).
- [ ] Roll back to last-known-good pack (per channel/targets).
- [ ] Pin channel to a known safe release (if supported).
- [ ] Quarantine offending release (revoke/block in distribution controls).
- [ ] Open a governed Orgo Case to fix forward.
### 6.2 Verification failures (signature/hash mismatch)
**Goal:** decide if this is packaging error, wrong trust roots, or tampering.
- [ ] Identify which verification step failed (index vs manifest vs payload hash).
- [ ] Confirm tenant/channel trust roots are correct.
- [ ] Re-fetch artifacts via a trusted path to rule out transient corruption.
- [ ] If mismatch persists: treat as **SEV0/SEV1** until proven benign; quarantine artifacts.
- [ ] If trust roots are wrong: deploy corrected, tenant-scoped roots; do not broaden acceptance without governance + audit.
### 6.3 Schema validation failures (manifests / envelopes)
**Goal:** detect non-conformant producer vs incorrect consumer pinning.
- [ ] Identify schema version expected by the consumer.
- [ ] Confirm producer pinned dependency version (Kristal v4 tag/commit).
- [ ] If producer is non-conformant: block publish at Orgo gate; fix producer; regenerate.
- [ ] If consumer pinning is wrong: roll back consumer deployment or correct pinning; do not relax validation in production.
### 6.4 Canon mismatch / reproducibility failure (same inputs, different IDs)
**Goal:** locate non-determinism source.
- [ ] Confirm canonicalization settings are pinned and consistent.
- [ ] Confirm inputs are identical (snapshot refs, blueprint/config refs, policy refs).
- [ ] Compare toolchain/environment metadata.
- [ ] If any dependency is unpinned: treat as root cause; remediate by pinning.
- [ ] Block publish until determinism is restored.
### 6.5 Rendering correctness incident (no-new-facts / trace failures)
**Goal:** prevent propagation of untraceable or policy-violating outputs.
- [ ] Disable/gate affected templates/models for impacted tenants.
- [ ] Switch to safe rendering mode (strict trace-required; omit/refuse when not traced).
- [ ] Capture render bundle + trace map examples and failing assertions.
- [ ] If systematic: roll back template/model bundle; open a governed Orgo Case with repro steps.
### 6.6 Execution incident (side effects, runaway tasks, unsafe actions)
**Goal:** stop harm, contain side effects, preserve audit.
- [ ] Halt dispatch for affected task types/queues.
- [ ] Isolate/cancel running tasks when safe (do not destroy evidence).
- [ ] Capture task envelopes, runtime logs, telemetry, and external side-effect audit logs.
- [ ] Review mandate constraints (permissions, approvals, forbidden actions).
- [ ] Resume only after control-plane gates are corrected.
### 6.7 Suspected security compromise (keys, trust roots, tampering, cross-tenant)
**Goal:** contain and rotate without breaking invariants.
- [ ] Treat as **SEV0**.
- [ ] Freeze publish/activation for impacted channels.
- [ ] Snapshot and lock down trust root stores, revocation sources, and signing infrastructure.
- [ ] Rotate keys per tenant/environment; publish revocations via governed mechanism.
- [ ] Validate that consumers reject compromised keys post-rotation.
- [ ] Perform cross-tenant audit (ensure no shared roots were incorrectly configured).
---
## 7) Communication requirements
### 7.1 Internal updates (IC cadence)
- SEV0/SEV1: every 15 minutes
- SEV2: every 30 minutes
- SEV3/SEV4: as needed
Each update includes:
- what changed since last update
- current impact/scope
- mitigation status (freeze/rollback/quarantine)
- next actions + owner
### 7.2 External updates (if applicable)
Only publish externally when:
- scope is confirmed
- mitigation path exists
- you can state clear customer impact and next steps
Avoid speculation about root cause until verified.
---
## 8) Recovery and validation
Before declaring resolved:
- [ ] Impact has stopped (no new failures / incorrect outputs).
- [ ] Stable state achieved (LKG active; gates re-enabled safely).
- [ ] Verification checks pass end-to-end (publish → distribute → activate → render → execute).
- [ ] Monitoring confirms recovery (errors, verify rejects, trace failures, task failures).
- [ ] A governed Orgo Case exists for permanent fix (if not already created).
---
## 9) Post-incident requirements (within 24–72 hours)
### 9.1 Postmortem packet (required)
- Timeline (UTC)
- Impact scope (tenants/channels)
- Root cause analysis (technical + process)
- What worked / what didn’t
- Corrective actions (owners + deadlines)
### 9.2 Corrective actions (typical)
- Strengthen conformance tests (schema, determinism, verification ordering).
- Improve guardrails (publish holds, canary activation, stricter rollback criteria).
- Update pinned dependencies and document them.
- If contract changes are needed: record a kOA ADR; update integration profile docs; never patch around divergence silently.
---
## 10) Quick reference (by symptom)
- **Activation failing across a channel** → pause auto-activation → rollback → inspect verification step
- **New release causes crashes** → rollback → quarantine release → open fix-forward case
- **Signature/hash mismatch** → quarantine → verify trust roots → treat as security until proven otherwise
- **Schema validation errors** → block publish → confirm pinned versions → fix producer/consumer pinning
- **Untraceable rendered facts** → safe rendering mode → roll back template/model → collect bundles
- **Unsafe execution behavior** → halt dispatch → isolate tasks → capture telemetry → enforce mandate gates
================================================================================================
FILE: wiki/Operations-Observability.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 7b4257b37bf869c0757321ca4b379ed9d0a5904b9634b95097a3096c5428c77a
CONTENT_BYTES: 5979
================================================================================================
# Observability
This page defines the **minimum observability** needed to operate kOA safely: detect failures early, explain outcomes deterministically, and preserve evidence for audit and incident response.
kOA treats observability as part of the pipeline: Orgo includes an explicit **Observe** stage (metrics/events/logs) before feedback/cases are created. :contentReference[oaicite:0]{index=0}
---
## Goals
1. **Fail fast, fail closed**: if the system cannot verify/validate, it must not proceed and must emit enough telemetry to diagnose without guesswork. :contentReference[oaicite:1]{index=1}
2. **Deterministic diagnosis**: failures should produce **stable reason codes** and repeatable outcomes. :contentReference[oaicite:2]{index=2}
3. **End-to-end correlation**: every signal ties back to a build/release/task and the active pack lineage. :contentReference[oaicite:3]{index=3} :contentReference[oaicite:4]{index=4}
4. **Audit-grade evidence**: key actions and decisions are reconstructable (especially activation, rollback, and trust events). :contentReference[oaicite:5]{index=5}
---
## Correlation model (what every signal must reference)
At minimum, emit correlation IDs for:
- **Build** (pipeline execution) :contentReference[oaicite:6]{index=6}
- **Release** (promotion/publish action)
- **Task** (Orgo Task identity + attempt identity) :contentReference[oaicite:7]{index=7}
- **Runtime Pack** (pack ID / manifest ref) :contentReference[oaicite:8]{index=8}
- **Target scope** (tenant / env / channel / cohort / device group), as applicable
Do not embed large payloads in-band; emit **references to logs/traces** and content-addressed artifacts instead. :contentReference[oaicite:9]{index=9} :contentReference[oaicite:10]{index=10}
---
## Required telemetry (baseline)
Integrations and operators should emit, at minimum: :contentReference[oaicite:11]{index=11}
- build/release correlation IDs (from Orgo)
- stage timing (start/end/fail)
- stable error codes + human-readable summaries
- references to logs/traces (not raw blobs in-band)
If you operate Konnaxion, also emit **Konnaxion State** records and activation/rollback outcomes with health signals. :contentReference[oaicite:12]{index=12} :contentReference[oaicite:13]{index=13}
---
## Signals by category
### Metrics
Use metrics to answer: “Is it healthy?” and “Is it getting worse?”
Typical examples (not exhaustive):
- Pipeline: stage success/failure rate; latency per stage; determinism/rebuild pass rate
- Distribution/runtime (Konnaxion): fetch latency/failure, verification pass/fail by reason, activation success/time, rollback frequency/triggers, cache utilization and corruption detection, active-pack drift :contentReference[oaicite:14]{index=14}
- Ingest (Chokmah): ingest req/success/failure, bytes/throughput, latency per connector/source type, retries/idempotency hits, quarantine/rejection rates by reason :contentReference[oaicite:15]{index=15}
### Logs (structured)
Logs must be structured and include correlation IDs and stable reason codes. :contentReference[oaicite:16]{index=16}
Example ingest log fields: request id, source descriptor hash, snapshot refs, policy decisions, failure codes, diagnostics pointers. :contentReference[oaicite:17]{index=17}
### Traces
Traces should connect:
- Orgo stage execution → produced artifact refs → downstream distribution/activation attempts
- Task dispatch (Orgo Task) → executor run → result + telemetry refs :contentReference[oaicite:18]{index=18}
### Events (audit / operational)
Emit explicit events for:
- stage transitions (start/finish/fail) with reason codes :contentReference[oaicite:19]{index=19}
- key activation actions (verify/activate/rollback/pin/unpin/revoke)
- trust material events (key creation/rotation/revocation; verification failures) :contentReference[oaicite:20]{index=20}
### Operational artifacts as observability
Some observability is captured as **typed artifacts**, not just logs:
- **Konnaxion State** (installed/active/pinned, last attempt status, health, telemetry refs) :contentReference[oaicite:21]{index=21} :contentReference[oaicite:22]{index=22}
- Orgo Case/Task audit trails for decisions and remediation work :contentReference[oaicite:23]{index=23}
---
## Release and rollback observability (must-have)
### During activation and rollback
Emit, per target: activation attempt events, preflight outcomes (pass/fail + reason codes), post-activation health results, and final active pack ID. :contentReference[oaicite:24]{index=24}
### Dashboards and alerts should include
- rollback success rate by channel/environment
- time-to-restore by incident
- rollback loops (flapping)
- divergence: reported active pack ID vs expected :contentReference[oaicite:25]{index=25}
---
## Diagnostic standards
- **Stable reason codes**: required for fail-closed behavior and repeatable triage. :contentReference[oaicite:26]{index=26}
- **Deterministic diagnostics** at activation boundaries (verification failures must produce stable reason codes). :contentReference[oaicite:27]{index=27}
- **Diagnostics pointers**: prefer `diagnostics_ref` / `telemetry_refs` over dumping blobs into control-plane records. :contentReference[oaicite:28]{index=28} :contentReference[oaicite:29]{index=29}
---
## Minimal checklist
- [ ] Every stage emits start/end/fail with duration and stable reason code. :contentReference[oaicite:30]{index=30}
- [ ] Every signal includes build/release/task correlation IDs. :contentReference[oaicite:31]{index=31}
- [ ] Konnaxion emits verification/activation/rollback signals and Konnaxion State updates. :contentReference[oaicite:32]{index=32}
- [ ] Rollback dashboards include success rate, TTR, flapping, and drift detection. :contentReference[oaicite:33]{index=33}
- [ ] Trust events (rotate/revoke/verify failures) are recorded and routed to security monitoring and incident response. :contentReference[oaicite:34]{index=34}
================================================================================================
FILE: wiki/Operations-Releases.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: b3a503247cfa7cd4febc0f8294a0f07f4ccccd871f9545814f0e08f1ee553b08
CONTENT_BYTES: 6472
================================================================================================
# Operations — Releases
Releases are how validated knowledge moves into runtime safely. A release takes an eligible build output (Runtime Pack) and rolls it out through controlled stages (channels/cohorts), with verification gates, monitoring, and reversible activation.
## Goals
- Deliver new knowledge to users safely and predictably
- Prevent partial or unsafe activations (fail-closed)
- Support controlled rollout (canary → stable) and fast rollback
- Preserve evidence: what was released, where, why, and with which results
## Core concepts
### Build vs Release
- **Build**: the result of the pipeline producing artifacts (including a Runtime Pack) that are eligible for distribution.
- **Release**: the operational act of distributing and activating a specific Runtime Pack in one or more environments/channels.
### Channel
A named release lane (examples: `canary`, `stable`, `lts`). Channels define default rollout speed, guardrails, and who receives updates.
### Cohort
A subset within a channel (by tenant group, region, percent rollout, etc.). Cohorts let you ramp exposure gradually.
### Pinning
Holding a channel (or cohort) to a specific pack/version to stop automatic upgrades until intentionally changed.
### Last-known-good (LKG)
A known safe pack/version you can roll back to deterministically.
## Release lifecycle (high level)
1. **Request**
- A release is requested for a specific build output (Runtime Pack reference) and a target (env + channel + optional cohort plan).
2. **Prepare**
- Resolve targets (channels/cohorts), confirm eligibility, and collect the operational record that will track the release.
3. **Distribute**
- Make the pack available to runtime distribution (fetchable by Konnaxion).
- Distribution must not imply activation.
4. **Verify (fail-closed)**
- Integrity, compatibility, and policy checks must pass before activation is allowed.
5. **Activate (atomic)**
- Activation is an atomic switch of “active pack” for the target scope.
- No partial activation is allowed.
6. **Monitor**
- Observe key health signals over a defined window (errors, latency, correctness signals, downstream impacts).
7. **Promote / Expand**
- Expand cohorts (or promote from canary → stable) only after monitoring criteria are met.
8. **Pin / Hold (optional)**
- Pin a channel/cohort to lock it to a specific pack/version.
9. **Close**
- Record outcomes (success, rolled back, pinned, aborted) and link postmortems if needed.
## Eligibility (what can be released)
A pack is eligible only if:
- It was produced from a validated pipeline run (validation gate passed).
- It matches the target’s compatibility constraints (schema/profile/runtime).
- It has all required references for audit (provenance and build identity).
## Verification gates (non-negotiable)
Release must fail closed if any of the following fails:
- Pack integrity (hash/signature/manifest mismatch)
- Schema/profile compatibility with the pinned runtime expectations
- Policy blocks (forbidden downgrade, forbidden source, forbidden scope, etc.)
- Missing required evidence records (build identity, provenance references)
## Operator workflow
### Pre-flight checklist
- Confirm target environment(s) and channels
- Confirm cohort plan (if used) and monitoring window
- Confirm rollback target strategy (LKG or pinned prior)
- Confirm alerting/observability is in place for the release window
- Confirm the release has an owner and an escalation path
### Execution checklist
- Start release in smallest safe scope (canary / smallest cohort)
- Confirm verification gates passed before any activation
- Activate atomically
- Monitor until criteria are met or violated
- If clean: expand cohort / promote channel
- If not clean: roll back deterministically and preserve evidence
## Monitoring (what “good” looks like)
Define success criteria per release. Typical signals:
- Activation success rate and time-to-activate
- Runtime error rates (spikes, new error classes)
- Latency regressions (p95/p99)
- Data correctness signals (trace coverage, query mismatch alarms)
- Tenant-impact indicators (support tickets, escalation rate)
Minimum monitoring windows:
- Canary: short but real (enough to catch immediate failures)
- Stable: longer (enough to catch delayed regressions)
## Promotion and expansion
Promotion is gated by:
- Canary health within thresholds
- No new critical errors introduced
- No policy violations observed
- Rollback readiness confirmed (LKG available and valid)
Recommended strategy:
- **Canary first**, then expand cohorts gradually, then promote to stable.
## Pinning strategy (when to pin)
Pin when you need:
- Controlled freeze during incident response
- A stable baseline for audits or regulated workflows
- A compatibility hold while upstream/downstream dependencies catch up
Pinning should be time-bounded and recorded with rationale.
## Rollback (what triggers it)
Rollback triggers:
- Verification failure (never activate)
- Activation failure (immediate rollback)
- Monitoring failure (regression detected)
- Policy violation discovered post-activation
- Unexpected tenant impact
Rollback principles:
- Deterministic target selection (pinned or LKG)
- Atomic activation of the rollback target
- Preserve the release record and link incident notes
See: [Operations — Rollbacks](Operations-Rollbacks)
## Evidence and audit trail
Every release should leave an auditable trail:
- Release identity (who/what/when)
- Target scope (env/channel/cohort)
- Pack identity (what was activated)
- Gate outcomes (verification results, activation result)
- Monitoring window + results
- Promotion/pinning/rollback decisions + rationale
- Links to incident/postmortem if applicable
See: [Artifacts — Operational](Artifacts-Operational)
## Common pitfalls
- Activating without a verified pack (must be fail-closed)
- Rolling out too broadly before monitoring criteria are met
- Not defining a rollback plan before activating
- Allowing “floating latest” dependencies that break determinism
- Missing evidence links (hard to debug, hard to audit)
## Related pages
- [Operations](Operations)
- [Operations — Builds](Operations-Builds)
- [Operations — Rollbacks](Operations-Rollbacks)
- [Operations — Observability](Operations-Observability)
- [Operations — Incident response](Operations-Incident-response)
- [Integration — Kristal v4](Integration-Kristal-v4)
================================================================================================
FILE: wiki/Operations-Rollbacks.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: cf98677c24b73cfcb5c01519f7816d0d05c08c893bcc28b28e6116abdbc2bc46
CONTENT_BYTES: 6057
================================================================================================
# Rollbacks
**Purpose:** Restore a known-safe runtime state quickly and deterministically when a release causes correctness, availability, or safety risk.
Rollback is an operational action on **Runtime Pack activation state**. It does not modify canonical truth or Kristal artifact schemas.
---
## Non-negotiables
- **Fail-closed:** if a candidate pack cannot be verified or is incompatible, do not activate it.
- **Atomic activation:** activation is an all-or-nothing switch; partial activation is forbidden.
- **Downgrade prevention:** do not activate older versions unless explicitly authorized as a rollback.
- **Deterministic rollback:** given the same triggers and state history, rollback target selection must be deterministic.
- **Offline correctness:** rollback/activation must not depend on fetching trust roots over the network.
---
## Rollback modes
At minimum, support one (recommended: both):
1) **Pinned rollback**
Activate an explicitly pinned known-good pack.
2) **Last-known-good (LKG) rollback**
Activate the most recent previously active verified pack that is still present and passes preflight.
---
## When rollback is the correct action
Rollback is the correct action if:
- A newly activated pack causes elevated errors, regressions, or unsafe outcomes.
- Policy enforcement is not functioning as expected.
- Determinism or verification guarantees are in question.
- Activation is partially complete and must be normalized quickly.
Do not rollback (or rollback only after containment) if:
- The issue is purely upstream (inputs) and the active pack is not implicated.
- The issue is confined to a single target with environmental failure (prefer repair).
- The rollback candidate is known-bad for the same failure class.
---
## Triggers (examples)
Rollback can be triggered by:
- Explicit operator action (recommended primary trigger).
- Verified distribution control updates (e.g., revocation added, rollback authorization published).
- Local runtime health signals (optional; must be policy-defined).
---
## End-to-end shape (mental model)
```mermaid
flowchart LR
A[Detect issue] --> B[Freeze / stop rollout]
B --> C[Select rollback target (Pinned or LKG)]
C --> D[Preflight: verify + compatibility]
D -->|pass| E[Atomic activate rollback target]
D -->|fail| F[Try earlier candidate or Safe Mode]
E --> G[Post-check: health + correctness]
G --> H[Record evidence + unfreeze (gated)]
````
---
## Procedure: automatic rollback (activation-time)
Automatic rollback is triggered when rollout detects:
* activation preflight failure
* post-activation health check failure
* policy enforcement failure (channel-defined)
Steps:
1. Stop further rollout in the same stage.
2. Attempt rollback to the **last-known-good** pack for the failing target(s).
3. If rollback succeeds:
* mark rollout as failed
* require human approval to proceed further
4. If rollback fails:
* escalate to emergency procedure
* place targets in **safe mode** if supported
---
## Procedure: emergency rollback
Use when there is strong evidence of integrity compromise, unsafe behavior, or fast-spreading outage.
1. **Immediate freeze**
* Freeze promotions and activations for the entire channel (or all channels if global).
2. **Scope containment**
* Identify impacted targets and expand scope conservatively if uncertain.
3. **Rollback to LKG**
* Execute rollback with priority on restoring safe operation.
* If LKG is unavailable or fails preflight, select the most recent prior verified pack that passes preflight.
4. **If rollback cannot restore safety**
* Enter **safe mode** (only if explicitly allowed for the channel):
* deny/disable unsafe capabilities
* serve minimal safe responses
* disable optional modules suspected in failures
5. **Trust response (if integrity concern)**
* Rotate or revoke trust material as required by policy.
* Require conformance re-verification before any new promotion.
6. **Audit + incident**
* Open/attach an incident.
* Record all decisions and activation events in Release Record + Orgo.
---
## Rollback failure handling
If rollback activation fails on any target:
* Stop further actions for that stage.
* Attempt rollback to an earlier candidate (prior LKG) if policy allows.
* If no candidate passes preflight:
* place target into safe mode (if supported)
* escalate to incident response
* require manual remediation
---
## Required observability and audit
During rollback, emit:
* per-target activation attempt events
* preflight outcomes (pass/fail + reason codes)
* post-activation health results
* final active pack ID per target
Dashboards/alerts should include:
* rollback success rate by channel and environment
* time-to-restore by incident
* repeated rollback loops (flapping)
* divergence: reported active pack ID vs expected
Audit linkage requirements:
* every rollback-related metric/event must reference `build_id` and/or `release_id` and relevant artifact refs (where applicable)
Konnaxion must also update and emit **Konnaxion State** on:
* rollback start and rollback completion
* failed verification or failed activation attempt
---
## Operational hygiene
* Maintain at least **N prior verified packs** per channel (policy-defined) to ensure rollback availability.
* Periodically perform **rollback drills** in non-prod and canary channels.
* Treat frequent rollbacks as a signal to investigate pipeline quality, conformance tests, and gate strictness.
* Ensure rollback tooling remains compatible across runtime versions (backward compatibility plan).
---
## Orgo integration
Operator-initiated and emergency rollbacks should be expressed as:
* an **Orgo Case** (incident/regression)
* one or more **Orgo Tasks**, such as:
* `freeze-promotions`
* `rollback-activation`
* `post-rollback-validation`
* `unfreeze-promotions` (optional, gated)
Rollback tasks must reference:
* channel/targets
* candidate selection rule or explicit candidate IDs
* required validations and success criteria
================================================================================================
FILE: wiki/Operations.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 1d680411e0019d66477bc98e287318f8ebf1d664589a656fd964f201d97932f7
CONTENT_BYTES: 4152
================================================================================================
# Operations
This page describes how to run the system safely in production terms: how builds become releases, how rollouts are controlled, and how recovery works when something goes wrong.
## What “Operations” owns
Operations ensures that:
- Only **validated** outputs become candidates for release (“no compile on fail”).
- Only **verified** runtime packs activate (“fail closed”).
- Rollouts are controlled (channels/cohorts/pinning) and fully auditable.
- Rollbacks are deterministic and prevent partial activation.
## Golden path (build → release → runtime)
```mermaid
flowchart LR
A[Build (Orgo)
gated pipeline] --> B[Eligible output
passed validation]
B --> C[Release (channels/cohorts)
promotion + monitoring]
C --> D[Konnaxion
verify -> activate]
D --> E[Runtime (Malkuth)
serve offline]
E --> F[Rollback if needed
deterministic target]
````
## Key operational concepts
* **Build**: a gated run that produces a candidate Runtime Pack and evidence of what happened.
* **Release**: controlled rollout of a Runtime Pack into an environment via channels/cohorts.
* **Channel**: a logical track (e.g., canary/stable/lts) with its own promotion and rollback behavior.
* **Cohort**: a controlled subset of traffic/tenants/devices for progressive rollout.
* **Pin**: holding a channel/cohort to a specific pack (freeze promotion).
* **Last-known-good (LKG)**: the deterministic fallback target used for rollback when not explicitly pinned.
## Build operations
### What happens in a build
* Inputs are ingested as immutable snapshots with provenance.
* Claim extraction/resolution happens upstream of truth.
* Validation is a hard gate.
* If validation passes, compilation produces canonical outputs + a Runtime Pack for distribution.
### What operators care about
* A build is **eligible** only if all gates pass.
* Every build produces operational evidence (records) so it can be audited and reproduced.
## Release operations
### Release lifecycle
1. **Create release** from an eligible build.
2. **Select channel + cohorts** for progressive rollout.
3. **Verify-before-activate**: integrity/compatibility checks must pass (fail closed).
4. **Monitor** health signals during rollout.
5. **Promote or pin** once confidence is sufficient.
6. **Record** outcomes and decisions (promotion/pin/rollback) in auditable release records.
### Operator checklist for a safe rollout
* Start with canary cohort(s)
* Require verification success before activation
* Promote in steps, not all at once
* Pin if signals are uncertain
* Roll back quickly if verification or health regresses
## Rollback operations
Rollback is the default recovery mechanism when a release is unsafe.
### Rollback triggers (examples)
* Pack verification failures
* Runtime health regressions during rollout
* Detected incompatibility with an environment/channel
* Policy violation or unexpected determinism drift
### Rollback invariants
* Target selection is deterministic (pinned target or LKG).
* Activation is atomic (avoid partial activation).
* Downgrade prevention policies may block unsafe rollback targets.
* Evidence is preserved (rollback is recorded; nothing is silently overwritten).
## Observability
Operations relies on two categories of signals:
### 1) System health signals (for go/no-go decisions)
* Verification pass/fail rates
* Activation success rates and latency
* Cohort/channel error rates and performance regressions
* Pack fetch/cache integrity signals (offline readiness)
### 2) Evidence and audit signals (for explainability)
* Build records: what inputs/policies were used and which gates passed/failed
* Release records: which pack was promoted/pinned/rolled back, where, and why
## Incident response (operator posture)
When an incident is declared:
1. **Stop the blast radius**: pause promotion and/or pin the channel.
2. **Prefer rollback** over patching in place.
3. **Preserve evidence** (records and traces) for root cause.
4. **Recover deterministically** (pinned/LKG targets; atomic activation).
5. **Document** what happened and what changed (post-incident record).
================================================================================================
FILE: wiki/Principles-and-invariants.md
AUTHORITY: reference
CONTENT_ROLE: navigation
CONTENT_SHA256: 97dc92a4d0dfca742cf27e13a77334953a6dad13536804e23192180119808ffe
CONTENT_BYTES: 3189
================================================================================================
# Principles & invariants
This page is the “non-negotiables” view of the system. If any of these are violated, treat it as a bug or an incident, not an acceptable tradeoff.
## 1) Truth boundary
- **Canonical truth exists only after compilation** into the canonical truth artifact (the “truth pivot”).
- **Upstream outputs are proposals**, not truth (inputs, extracted claims, resolved claims, validation outputs).
- **Validation is a hard gate**: if validation fails, canonical outputs must not be produced or distributed.
## 2) No redundancy of external contracts
- **Do not copy or restate external artifact contracts** (schemas, canonicalization rules, signing formats, etc.).
- The system points to the pinned external spec and enforces it at boundaries.
## 3) Typed boundaries (no hidden state)
- Components exchange **typed artifacts**, not implicit shared state.
- “Truth” cannot move through side channels; it must go through the declared pipeline and gates.
## 4) Determinism over availability
- Same **pinned inputs + pinned configuration + pinned policies** must yield **identical (or canonically identical)** results.
- Determinism also applies to failure behavior: same pinned context → same class of failure + stable reasons.
## 5) Fail-closed integrity and activation
- If integrity is declared (hashes/signatures/compat rules), **verification is mandatory**.
- If verification cannot be completed or fails, **activation must not proceed**.
- Activation must be **atomic** (no partial activation).
## 6) Immutable canon and governed change
- Canonical artifacts are **immutable once published**.
- Any canon-affecting change is a **new build**, producing new artifacts/IDs (no hot-edits).
## 7) No new facts downstream
- Rendering and execution layers must **not introduce new factual claims**.
- They can only:
- trace outputs to canonical sources,
- omit/refuse deterministically under policy,
- emit governed feedback that becomes new work.
## 8) Offline correctness
- Correctness must not depend on live network calls at the moment of use.
- Runtime behavior is based on verified, activated packs that can be used offline.
## 9) Auditability as a first-class requirement
- Every build/release must leave an auditable trail that can answer:
- what inputs were used,
- which policies/configuration applied,
- which gates ran and why they passed/failed,
- which outputs were produced and promoted.
## 10) Tenant isolation and pinned trust roots
- Trust roots and acceptance policy are **tenant-scoped** and **pinned**.
- The system must resist downgrade/substitution and cross-tenant trust confusion.
## Quick “invariant check” list
If you’re reviewing a change, confirm:
- Validation failure cannot produce publishable/activatable outputs.
- Any declared integrity mismatch blocks publish/activation (no bypass).
- A component cannot smuggle facts around validation/compile.
- Output is deterministic under pinned context (including error behavior).
- Rendering cannot invent facts and always provides trace coverage or deterministic refusal.
- Activation is atomic and rollback target selection is deterministic.
================================================================================================
FILE: docs_layer-model/00_README.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 815c7efb4be28fbb98a930d82a39d4d886e35b0a7dda8e4dfd93806052f46bc1
CONTENT_BYTES: 5506
================================================================================================
Content for:
```text
C:\mycode\kOA\kOA_Digital_Ecosystem\layer-model\00_README.md
```
````markdown
# kOA Layer Model
**Status:** Conceptual orientation
**Normative for kOA:** NO
**External normative reference:** None
---
## Purpose
This documentation set defines the **layered architecture of kOA**.
It explains how kOA functions as an architecture of passages:
```text
meaning → knowledge → decision → action → memory → future capacity
````
The goal is to make the full kOA system easier to understand, teach, compare, and communicate without collapsing it into only one of its parts.
This layer model does **not** replace the technical documentation of the kOA Digital Ecosystem. It provides a higher-level conceptual map that helps readers understand how the technical ecosystem fits into the broader kOA architecture.
---
## Core thesis
kOA is a **collective-capacity architecture**.
It helps communities:
1. clarify meaning;
2. structure knowledge;
3. deliberate;
4. make legitimate decisions;
5. execute decisions;
6. preserve memory;
7. learn from experience;
8. transmit capacity;
9. deploy the system into real contexts.
In short:
```text
kOA turns collective intelligence into collective capacity.
```
---
## Core flow
The simplified flow is:
```text
Meaning
→ Knowledge
→ Decision
→ Action
→ Memory
→ Capacity
```
The operational cycle is:
```text
Know → Choose → Act → Remember
```
The full layer model expands that cycle into distinct functional layers.
---
## Layer stack
The kOA Layer Model is organized as follows:
```text
0. Separation of functions
1. Orientation / mandate
2. Semantics / meaning
3. Provenance / ingestion
4. Structured knowledge
5. Validation / canon
6. Deliberation
7. Decision / legitimacy
8. Execution
9. Memory / learning
10. Resilience / autonomy
11. Learning / interface
12. Narrative / adoption
13. Deployment / translation
```
Each layer answers a specific question.
Each layer prevents a specific failure mode.
Each layer connects to the layers before and after it.
---
## Relationship to the technical documentation
The technical kOA Digital Ecosystem documentation defines concrete system architecture, nodes, artifacts, schemas, operations, trust boundaries, determinism, integration rules, and runtime behavior.
This layer model does not redefine those contracts.
Instead, it explains how the technical ecosystem fits into the broader kOA structure.
For technical implementation, use:
```text
../technical-docs/
```
For conceptual layer definitions, use:
```text
./layer-model/
```
---
## Non-goals
This documentation set does **not**:
* redefine Kristal contracts;
* redefine kOA-native artifact schemas;
* replace node specifications;
* replace operational runbooks;
* replace trust-boundary documentation;
* define partner strategy;
* define funding strategy;
* define pilot implementation plans;
* serve as a marketing deck.
It exists to define the layers.
---
## How to use this documentation set
Start here:
```text
00_README.md
```
Then read:
```text
01_LAYER_MODEL.md
02_LAYER_INDEX.md
```
Use the template when adding or revising a layer:
```text
03_LAYER_TEMPLATE.md
```
Then read the individual layer files:
```text
layers/
```
---
## File map
```text
layer-model/
├── 00_README.md
├── 01_LAYER_MODEL.md
├── 02_LAYER_INDEX.md
├── 03_LAYER_TEMPLATE.md
└── layers/
├── 00_separation_of_functions.md
├── 01_orientation_mandate.md
├── 02_semantics_meaning.md
├── 03_provenance_ingestion.md
├── 04_structured_knowledge.md
├── 05_validation_canon.md
├── 06_deliberation.md
├── 07_decision_legitimacy.md
├── 08_execution.md
├── 09_memory_learning.md
├── 10_resilience_autonomy.md
├── 11_learning_interface.md
├── 12_narrative_adoption.md
└── 13_deployment_translation.md
```
---
## Authoring rules
When writing or editing layer files:
1. Keep each layer focused.
2. Do not turn layer files into partner pitches.
3. Do not duplicate technical contracts from the technical documentation.
4. Use kOA internal vocabulary, but translate it into external vocabulary where useful.
5. Identify the failure mode each layer prevents.
6. Explain how each layer relates to the layers before and after it.
7. Keep the model conceptual, readable, and reusable.
---
## Standard layer structure
Each layer file should include:
```text
1. Function
2. Core question
3. Internal kOA components
4. Inputs
5. Outputs
6. External vocabulary
7. Failure mode if absent
8. Relation to other layers
9. One-sentence definition
```
---
## Core distinction
The technical documentation answers:
```text
How does the kOA Digital Ecosystem work?
```
The layer model answers:
```text
What functions must exist for kOA to turn meaning into collective capacity?
```
Both are connected.
They should remain distinct.
---
## One-sentence summary
kOA is a layered architecture that transforms meaning into knowledge, knowledge into decision, decision into action, action into memory, and memory into future collective capacity.
```
This keeps the file focused on defining the layer model while respecting the existing Digital Ecosystem docs, which already define technical architecture, artifacts, nodes, operations, and non-redundancy around Kristal contracts. :contentReference[oaicite:0]{index=0}
```
================================================================================================
FILE: docs_layer-model/01_LAYER_MODEL.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: a19059eb79f12948b17167802aff2908ac246ce447086b407e39af5bc5f7a4d0
CONTENT_BYTES: 17873
================================================================================================
# kOA Layer Model
**File:** `layer-model/01_LAYER_MODEL.md`
**Status:** Conceptual orientation
**Normative for kOA:** NO
**External normative reference:** None
---
## 1. Purpose
This document defines the **kOA Layer Model**: a conceptual map of the functional layers that make the broader kOA architecture readable.
It explains how kOA moves from:
```text
meaning → knowledge → decision → action → memory → future capacity
````
This file does **not** replace the technical Digital Ecosystem documentation. It does not define schemas, contracts, node interfaces, runtime gates, Kristal artifact formats, or operational procedures.
The technical Digital Ecosystem documentation remains the authority for:
* system architecture;
* node responsibilities;
* kOA-owned artifacts;
* operational workflows;
* trust boundaries;
* determinism;
* pipeline behavior;
* release, rollback, and failure procedures.
This layer model is a **conceptual map**. It helps humans understand the whole system before entering the technical documentation.
---
## 2. Core thesis
kOA is an architecture of passages.
It helps a group move through the full cycle of collective capacity:
```text
sense-making
→ knowledge structuring
→ deliberation
→ decision
→ execution
→ memory
→ learning
→ transmission
```
The central claim is:
> kOA does not only store knowledge or coordinate tasks. It structures the passages between meaning, knowledge, judgment, action, memory, and future collective capacity.
---
## 3. Core flow
The simplest flow is:
```text
Meaning → Knowledge → Decision → Action → Memory → Capacity
```
Expanded:
```text
raw inputs
→ interpreted meaning
→ structured knowledge
→ validated canon
→ deliberation
→ legitimate decision
→ operational execution
→ memory
→ learning
→ future capacity
```
This corresponds to the public kOA cycle:
```text
Know → Choose → Act → Remember
```
Where:
* **Know** means gathering, structuring, validating, and preserving knowledge.
* **Choose** means deliberating, comparing options, and making decisions legible.
* **Act** means converting decisions into tasks, responsibilities, workflows, and execution.
* **Remember** means preserving results, errors, lessons, and updated knowledge for the next cycle.
---
## 4. Relation to the technical Digital Ecosystem
The technical Digital Ecosystem already defines a contract-driven operational spine:
```text
Ingest
→ Extract
→ Resolve
→ Validate
→ Compile
→ Distribute
→ Render
→ Execute
→ Feedback
```
The layer model sits above that spine.
It explains the broader human, semantic, institutional, and strategic functions around the technical pipeline.
Approximate mapping:
| Layer model | Technical spine |
| ------------------------ | ------------------------------------------- |
| Orientation / mandate | mandate bundle, control-plane constraints |
| Provenance / ingestion | ingest, extract |
| Semantics / meaning | resolve, reconcile, render meaning |
| Structured knowledge | Kristal bridge, canonical artifacts |
| Validation / canon | validate, compile, conformance gates |
| Deliberation | Konnaxion / ethiKos-facing state |
| Decision / legitimacy | EkoH, Smart Vote, decision records |
| Execution | Orgo, SwarmCraft, runtime behavior |
| Memory / learning | feedback, logs, archives, updated artifacts |
| Resilience / autonomy | offline behavior, rollback, determinism |
| Learning / interface | UCKK, guides, user-facing pathways |
| Narrative / adoption | King Klown, Kin City, public pedagogy |
| Deployment / translation | pilots, partners, external vocabulary |
This mapping is approximate. The technical documentation remains authoritative for implementation details.
---
## 5. Layer stack
The kOA Layer Model has fourteen layers.
```text
0. Separation of functions
1. Orientation / mandate
2. Semantics / meaning
3. Provenance / ingestion
4. Structured knowledge
5. Validation / canon
6. Deliberation
7. Decision / legitimacy
8. Execution
9. Memory / learning
10. Resilience / autonomy
11. Learning / interface
12. Narrative / adoption
13. Deployment / translation
```
These layers are not isolated modules. They are functional zones.
A single technical component may participate in several layers. A single layer may involve several components.
---
## 6. Layer 0 — Separation of functions
### Function
Separates the major powers and roles inside the broader kOA architecture.
### Core question
What must remain distinct so the system does not collapse into one authority, one platform, one narrative, or one person?
### Internal kOA components
* kOA
* UCKK
* kOA Digital Ecosystem
* King Klown
* Inquisiteur
* Assemblées
* Archives
### Role in the system
This layer prevents confusion between:
```text
movement
school
technical infrastructure
narrative interface
ethical safeguard
collective legitimacy
memory
```
### One-sentence definition
Separation of functions is the layer that prevents kOA from becoming a single undifferentiated authority.
---
## 7. Layer 1 — Orientation / mandate
### Function
Defines purpose, constraints, principles, and intended direction.
### Core question
Why are we acting, under what mandate, and with what limits?
### Internal kOA components
* mandate
* principles
* operating constraints
* intended impact
* non-domination
* truth boundary
* governance limits
### Inputs
* mission
* context
* ethical principles
* community needs
* constraints
* scope
### Outputs
* mandate bundle
* operating direction
* decision constraints
* evaluation frame
### One-sentence definition
Orientation is the layer that gives the system its purpose, boundaries, and direction before it processes knowledge or action.
---
## 8. Layer 2 — Semantics / meaning
### Function
Clarifies terms, concepts, relations, categories, ambiguity, and translation.
### Core question
What do the words, concepts, and categories mean?
### Internal kOA components
* SemantiK
* SenTient
* semantic mappings
* controlled vocabulary
* ontologies
* knowledge graphs
* reconciliation
### Inputs
* raw language
* claims
* concepts
* categories
* domain terms
* conflicting meanings
* multilingual expressions
### Outputs
* clarified meanings
* resolved ambiguities
* semantic relations
* mapped concepts
* structured definitions
### One-sentence definition
Semantics is the layer where meaning becomes explicit enough to be governed, translated, compared, and reused.
---
## 9. Layer 3 — Provenance / ingestion
### Function
Captures sources, contributions, evidence, context, and origin.
### Core question
Where did this come from, and can we trace it?
### Internal kOA components
* source capture
* snapshots
* input records
* provenance metadata
* evidence chain
* Chokmah / inputs
* ingestion gates
### Inputs
* documents
* datasets
* testimony
* discussion
* observations
* public records
* expert input
* lived experience
### Outputs
* source records
* provenance trails
* traceable inputs
* evidence metadata
* reproducible snapshots
### One-sentence definition
Provenance is the layer that ensures knowledge does not lose its origin, context, and traceability.
---
## 10. Layer 4 — Structured knowledge
### Function
Transforms sources, claims, evidence, and context into reusable knowledge artifacts.
### Core question
What do we know clearly enough to preserve, reuse, compare, or act on?
### Internal kOA components
* Kristal
* claims
* evidence
* references
* uncertainty
* validation metadata
* Runtime Packs
* Da’at / Kristal bridge
### Inputs
* provenance-aware material
* resolved concepts
* claims
* evidence
* context
* expert knowledge
* lived experience
### Outputs
* structured knowledge artifacts
* reusable claims
* validated references
* portable knowledge units
* machine-usable knowledge packages
### One-sentence definition
Structured knowledge is the layer where raw contributions become reusable, verifiable knowledge artifacts.
---
## 11. Layer 5 — Validation / canon
### Function
Stabilizes knowledge without allowing hidden mutation, unchecked authority, or silent drift.
### Core question
What can be accepted, released, reused, or treated as canonical?
### Internal kOA components
* canon
* validation gates
* conformance checks
* build records
* release records
* feedback governance
* fail-closed rules
* canonical artifacts
### Inputs
* structured knowledge
* proposed artifacts
* schemas
* validation reports
* review signals
* trust constraints
### Outputs
* validated artifacts
* rejected artifacts
* canonical releases
* build records
* release records
* audit traces
### One-sentence definition
Validation is the layer that decides what may enter the canon and under what traceable conditions.
---
## 12. Layer 6 — Deliberation
### Function
Structures disagreement, consultation, argument, synthesis, and collective sense-making.
### Core question
How do we turn many voices, claims, objections, and perspectives into a deliberative process?
### Internal kOA components
* Konnaxion
* ethiKos
* Korum
* consultations
* argument mapping
* synthesis
* consensus mapping
* collaborative drafting
### Inputs
* structured knowledge
* community input
* options
* objections
* arguments
* stakeholder perspectives
### Outputs
* deliberation records
* mapped disagreements
* argument structures
* synthesis notes
* draft proposals
* decision-ready options
### One-sentence definition
Deliberation is the layer that turns public input and disagreement into structured collective reasoning.
---
## 13. Layer 7 — Decision / legitimacy
### Function
Makes choices visible, comparable, contestable, and legitimate.
### Core question
How do we choose without hiding power inside a single opaque score?
### Internal kOA components
* EkoH
* Smart Vote
* raw vote
* weighted reading
* domain-bounded expertise
* ethical reliability
* stakeholder filters
* decision records
### Inputs
* deliberation outputs
* options
* support signals
* expertise signals
* ethical reliability signals
* stakeholder views
* criteria
### Outputs
* decision readings
* raw support
* weighted support
* legitimacy signals
* selected options
* contestable decision records
### One-sentence definition
Decision / legitimacy is the layer that shows how choices are made and why they can be trusted, challenged, or revised.
---
## 14. Layer 8 — Execution
### Function
Converts decisions into tasks, roles, responsibilities, workflows, follow-up, and closure.
### Core question
How does a decision become real work?
### Internal kOA components
* Orgo
* Orgo Case
* Orgo Task
* SwarmCraft
* workflow
* assignments
* escalation
* status
* closure
* operational logs
### Inputs
* decisions
* mandates
* task definitions
* roles
* constraints
* available resources
* runtime packages
### Outputs
* tasks
* cases
* assignments
* execution logs
* status updates
* completed actions
* unresolved issues
* operational records
### One-sentence definition
Execution is the layer where collective choices become coordinated, accountable action.
---
## 15. Layer 9 — Memory / learning
### Function
Transforms action, results, errors, and feedback into reusable institutional memory.
### Core question
What happened, what did we learn, and how does the next cycle start stronger?
### Internal kOA components
* Archives
* logs
* post-mortems
* feedback records
* updated Kristals
* learning records
* institutional memory
* release history
### Inputs
* execution logs
* outcomes
* failures
* participant feedback
* audit records
* decision results
* updated evidence
### Outputs
* lessons learned
* memory records
* updated knowledge artifacts
* improved processes
* future constraints
* next-cycle inputs
### One-sentence definition
Memory is the layer where past action becomes future collective capacity.
---
## 16. Layer 10 — Resilience / autonomy
### Function
Protects the system against dependence, capture, drift, network failure, and fragile centralization.
### Core question
Can the system keep functioning under constraint, offline, or without a single controlling platform?
### Internal kOA components
* offline-first behavior
* local execution
* Runtime Packs
* fail-closed verification
* deterministic builds
* rollback
* portability
* duplication
* synchronization control
* trust roots
### Inputs
* validated artifacts
* runtime packages
* keys
* local state
* release records
* operational constraints
### Outputs
* portable execution
* local runtime behavior
* rollback paths
* resilient deployments
* reproducible behavior
* reduced platform dependency
### One-sentence definition
Resilience is the layer that keeps kOA portable, auditable, and functional under constraint.
---
## 17. Layer 11 — Learning / interface
### Function
Makes the system teachable, navigable, usable, and transmissible.
### Core question
How do people learn to understand and use the architecture?
### Internal kOA components
* UCKK
* courses
* learning guides
* pathways
* Voies
* Paliers
* Parchemins
* interfaces
* visualizations
* documentation
* Kin City
### Inputs
* layer model
* canon
* technical documentation
* learning objectives
* course material
* participant needs
* practical exercises
### Outputs
* courses
* learning paths
* competency recognition
* participant artifacts
* guides
* onboarding flows
* trained users
### One-sentence definition
Learning / interface is the layer that turns kOA from an architecture into something people can understand, practice, and transmit.
---
## 18. Layer 12 — Narrative / adoption
### Function
Makes the architecture memorable, public, symbolic, and culturally transmissible.
### Core question
How does a complex architecture become visible, memorable, and socially adoptable?
### Internal kOA components
* King Klown
* Kin City
* public pedagogy
* narrative interface
* theatre
* symbolic roles
* challenges
* stories
* movement language
### Inputs
* concepts
* tensions
* public problems
* learning goals
* symbolic material
* movement strategy
### Outputs
* public narratives
* symbolic entry points
* memorable explanations
* challenges
* scenes
* adoption pathways
* cultural resonance
### One-sentence definition
Narrative / adoption is the layer that translates kOA into public imagination without replacing evidence, governance, or procedure.
---
## 19. Layer 13 — Deployment / translation
### Function
Translates the layer stack for partners, pilots, external institutions, and real-world adoption.
### Core question
Which part of the system should be shown to which audience, in which vocabulary, for which next step?
### Internal kOA components
* partner framing
* pilot framing
* external vocabulary
* institutional translation
* public-interest deployment
* field-building strategy
### Inputs
* layer model
* evidence base
* partner needs
* pilot requirements
* external frameworks
* institutional constraints
### Outputs
* partner-specific explanations
* pilot proposals
* alignment maps
* adoption pathways
* external translation documents
* implementation roadmaps
### One-sentence definition
Deployment / translation is the layer that turns the kOA architecture into forms that partners, institutions, communities, and pilots can actually use.
---
## 20. Layer relationships
The layers are directional but not strictly linear.
The common forward path is:
```text
orientation
→ semantics
→ provenance
→ structured knowledge
→ validation
→ deliberation
→ decision
→ execution
→ memory
```
The learning loop is:
```text
memory
→ updated knowledge
→ better deliberation
→ better decisions
→ better action
```
The adoption loop is:
```text
interface
→ learning
→ narrative
→ participation
→ deployment
→ feedback
→ memory
```
The resilience loop is:
```text
validated artifacts
→ portable runtime
→ local execution
→ audit
→ rollback
→ corrected release
```
---
## 21. Layer model vs. technical implementation
The layer model should not be read as a directory map, class diagram, schema map, or node map.
It is a conceptual architecture.
For implementation, consult the technical Digital Ecosystem documentation.
Layer model:
```text
What function does this part of the system serve?
```
Technical docs:
```text
What component, artifact, node, schema, or process implements it?
```
Both are needed.
The layer model makes kOA understandable.
The technical docs make kOA buildable, testable, and operable.
---
## 22. Non-goals
This file does not:
* define Kristal schemas;
* restate Kristal contracts;
* define JSON field lists;
* define canonicalization rules;
* replace technical node documentation;
* define operational runbooks;
* define partner strategy in detail;
* define UCKK curriculum;
* define narrative canon;
* define certification policy.
Those belong in their own documentation sets.
---
## 23. One-page summary
kOA is a layered architecture for collective capacity.
It separates functions, orients action, clarifies meaning, captures provenance, structures knowledge, validates canon, organizes deliberation, makes decisions legible, executes responsibilities, preserves memory, protects resilience, teaches participation, supports narrative adoption, and translates itself for deployment.
In short:
> kOA is an architecture of passages: from meaning to knowledge, from knowledge to decision, from decision to action, from action to memory, and from memory to future collective capacity.
================================================================================================
FILE: docs_layer-model/02_LAYER_INDEX.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 075428e57d42c75480c77a839ad26908b06414df4d91d00cbe4df262244daddd
CONTENT_BYTES: 13320
================================================================================================
# kOA Layer Index
**File:** `layer-model/02_LAYER_INDEX.md`
**Status:** Conceptual orientation
**Normative for kOA:** NO
**External normative references:** None
---
## 1. Purpose
This file indexes the functional layers of the broader kOA architecture.
The layer model does not replace the kOA Digital Ecosystem technical documentation. It provides a conceptual map of how the system moves from orientation and meaning to knowledge, decision, action, memory, learning, narrative adoption, and deployment translation.
The technical documentation remains responsible for system architecture, node responsibilities, kOA-owned artifacts, operational workflows, trust boundaries, determinism, and integration constraints.
---
## 2. Core Flow
```text
Meaning → Knowledge → Decision → Action → Memory → Capacity
````
Expanded:
```text
Orientation
→ Semantics
→ Provenance
→ Structured Knowledge
→ Validation
→ Deliberation
→ Decision
→ Execution
→ Memory
→ Resilience
→ Learning
→ Narrative
→ Deployment Translation
```
Canonical kOA cycle:
```text
Know → Choose → Act → Remember
```
---
## 3. Layer Index
| Layer | Name | Core Function | Layer File |
| ----: | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| 0 | Separation of Functions | Separates movement, school, digital infrastructure, narrative interface, ethical safeguard, collective legitimacy, and memory. | `layers/00_separation_of_functions.md` |
| 1 | Orientation / Mandate | Defines purpose, mandate, ethical direction, constraints, and intended impact before the system acts. | `layers/01_orientation_mandate.md` |
| 2 | Semantics / Meaning | Clarifies terms, concepts, categories, relationships, ambiguity, and translation. | `layers/02_semantics_meaning.md` |
| 3 | Provenance / Ingestion | Captures sources, contributions, inputs, context, and origin with traceability. | `layers/03_provenance_ingestion.md` |
| 4 | Structured Knowledge | Turns raw sources and contributions into reusable, verifiable knowledge artifacts. | `layers/04_structured_knowledge.md` |
| 5 | Validation / Canon | Stabilizes knowledge, releases, and artifacts without hidden mutation or unsupported claims. | `layers/05_validation_canon.md` |
| 6 | Deliberation | Structures disagreement, consultation, argument, synthesis, and public reasoning. | `layers/06_deliberation.md` |
| 7 | Decision / Legitimacy | Makes choices visible, comparable, contestable, and legitimate through multiple decision readings. | `layers/07_decision_legitimacy.md` |
| 8 | Execution | Converts decisions into tasks, roles, workflows, follow-up, responsibility, and closure. | `layers/08_execution.md` |
| 9 | Memory / Learning | Turns action, results, errors, and feedback into institutional memory and future capacity. | `layers/09_memory_learning.md` |
| 10 | Resilience / Autonomy | Protects portability, offline use, redundancy, deterministic behavior, and non-dependence. | `layers/10_resilience_autonomy.md` |
| 11 | Learning / Interface | Makes the system teachable, usable, navigable, and appropriable by learners and communities. | `layers/11_learning_interface.md` |
| 12 | Narrative / Adoption | Makes the architecture memorable, publicly transmissible, symbolically accessible, and culturally adoptable. | `layers/12_narrative_adoption.md` |
| 13 | Deployment / Translation | Translates the layer model for pilots, partners, institutions, external vocabularies, and adoption pathways. | `layers/13_deployment_translation.md` |
---
## 4. Layer Groups
The layers can be read in four groups.
### A. Foundation Layers
```text
0. Separation of Functions
1. Orientation / Mandate
2. Semantics / Meaning
3. Provenance / Ingestion
```
These layers define what the system is, why it acts, what its terms mean, and where its inputs come from.
Without these layers, the system becomes ambiguous, ungrounded, or vulnerable to hidden capture.
### B. Knowledge and Legitimacy Layers
```text
4. Structured Knowledge
5. Validation / Canon
6. Deliberation
7. Decision / Legitimacy
```
These layers transform input into knowledge, knowledge into public reasoning, and public reasoning into legitimate choices.
Without these layers, information remains scattered, decisions become opaque, and expertise can become either invisible or authoritarian.
### C. Action and Memory Layers
```text
8. Execution
9. Memory / Learning
10. Resilience / Autonomy
```
These layers convert choices into action, action into learning, and learning into durable capacity.
Without these layers, the system remains performative: people discuss, decide, and announce, but do not reliably execute, remember, or improve.
### D. Transmission and Adoption Layers
```text
11. Learning / Interface
12. Narrative / Adoption
13. Deployment / Translation
```
These layers make the system teachable, usable, memorable, and translatable for real communities, partners, and institutions.
Without these layers, the architecture remains technically coherent but socially inaccessible.
---
## 5. Layer Dependencies
Each layer depends on the layers below it.
```text
Deployment depends on adoption.
Adoption depends on interface and learning.
Learning depends on memory.
Memory depends on execution.
Execution depends on decision.
Decision depends on deliberation.
Deliberation depends on validated knowledge.
Validated knowledge depends on structured knowledge.
Structured knowledge depends on provenance.
Provenance depends on semantic clarity.
Semantic clarity depends on orientation.
Orientation depends on separation of functions.
```
In short:
```text
No orientation → no coherent meaning.
No meaning → no reliable knowledge.
No knowledge → no grounded decision.
No decision → no legitimate execution.
No execution → no real action.
No memory → no learning.
No learning → no transmission.
No transmission → no durable collective capacity.
```
---
## 6. Relation to the kOA Digital Ecosystem Pipeline
The technical kOA Digital Ecosystem pipeline can be summarized as:
```text
Ingest → Extract → Resolve → Validate → Compile → Distribute → Render → Execute → Feedback
```
The layer model is broader. It includes the technical pipeline, but also includes institutional, semantic, learning, narrative, and deployment layers.
Approximate mapping:
| Layer Model | Digital Ecosystem Relation |
| ------------------------ | ---------------------------------------------------------------- |
| Orientation / Mandate | Keter / mandate inputs / operating constraints |
| Semantics / Meaning | semantic resolution, mappings, definitions, ambiguity handling |
| Provenance / Ingestion | source capture, inputs, snapshots, traceability |
| Structured Knowledge | Kristal-adjacent knowledge artifacts and structured outputs |
| Validation / Canon | conformance, gates, canonical releases, fail-closed behavior |
| Deliberation | Konnaxion / ethiKos / structured public reasoning |
| Decision / Legitimacy | EkoH / Smart Vote / transparent decision readings |
| Execution | Orgo / SwarmCraft / task and workflow execution |
| Memory / Learning | feedback, logs, archives, updated artifacts, post-cycle learning |
| Resilience / Autonomy | offline operation, deterministic behavior, rollback, portability |
| Learning / Interface | UCKK, courses, guides, user-facing interfaces |
| Narrative / Adoption | King Klown, Kin City, public pedagogy, symbolic interface |
| Deployment / Translation | partner-facing explanations, pilots, adoption pathways |
---
## 7. One-Sentence Definitions
### Layer 0 — Separation of Functions
Separates the major functions of kOA so that movement, school, infrastructure, narrative, ethics, legitimacy, and memory do not collapse into one authority.
### Layer 1 — Orientation / Mandate
Defines why the system acts, what it is allowed to do, and what principles constrain it.
### Layer 2 — Semantics / Meaning
Makes meaning explicit by clarifying words, categories, definitions, relationships, and ambiguities.
### Layer 3 — Provenance / Ingestion
Captures input with enough context and traceability for later verification, comparison, and reuse.
### Layer 4 — Structured Knowledge
Transforms inputs into reusable, verifiable knowledge artifacts.
### Layer 5 — Validation / Canon
Determines what can be stabilized, released, or treated as canonical without hidden mutation.
### Layer 6 — Deliberation
Turns disagreement, contribution, and consultation into structured public reasoning.
### Layer 7 — Decision / Legitimacy
Turns deliberation into transparent, contestable, multi-readable choices.
### Layer 8 — Execution
Turns decisions into tasks, responsibilities, workflows, and follow-through.
### Layer 9 — Memory / Learning
Turns action and feedback into institutional memory and improved future capacity.
### Layer 10 — Resilience / Autonomy
Ensures the system can remain portable, deterministic, recoverable, and usable under constraint.
### Layer 11 — Learning / Interface
Makes the system teachable and usable through learning paths, guides, interfaces, and UCKK.
### Layer 12 — Narrative / Adoption
Makes the system memorable and publicly transmissible through narrative, symbolic interface, and public pedagogy.
### Layer 13 — Deployment / Translation
Translates the layer model into partner-facing, pilot-facing, and institution-facing language.
---
## 8. External Vocabulary Bridge
The layer model can be translated into recognized external vocabularies.
| kOA Layer | External Vocabulary |
| ------------------------ | ----------------------------------------------------------------------------- |
| Separation of Functions | governance architecture, separation of roles |
| Orientation / Mandate | mission, theory of change, intended impact, operating principles |
| Semantics / Meaning | semantic interoperability, ontology, taxonomy, knowledge graph |
| Provenance / Ingestion | provenance, data lineage, source metadata, evidence chain |
| Structured Knowledge | verified knowledge artifact, knowledge object, FAIR-aligned knowledge package |
| Validation / Canon | quality assurance, conformance, validation gate, canonical release |
| Deliberation | public participation, deliberative democracy, civic engagement |
| Decision / Legitimacy | decision support, legitimacy lens, participatory weighting |
| Execution | workflow management, case management, operational governance |
| Memory / Learning | institutional memory, organizational learning, lessons learned |
| Resilience / Autonomy | resilience engineering, offline-first, fail-closed integrity |
| Learning / Interface | systems literacy, capacity building, competency-based education |
| Narrative / Adoption | narrative change, public pedagogy, civic imagination |
| Deployment / Translation | ecosystem building, scaling strategy, field building |
---
## 9. Intended Use
Use this index to:
1. navigate the layer files;
2. keep layer definitions consistent;
3. explain kOA without collapsing everything into one module;
4. translate internal kOA vocabulary into external language;
5. identify which layer matters for a given partner, pilot, or technical document.
This index is not a technical contract. It is a conceptual navigation document.
---
## 10. Maintenance Rule
When a new layer is added, renamed, merged, or removed:
1. update this file;
2. update `01_LAYER_MODEL.md`;
3. update the corresponding file under `layers/`;
4. verify that no technical contract in the Digital Ecosystem docs is duplicated or contradicted.
Layer documentation must explain the architecture without redefining technical schemas, artifact formats, or normative Kristal contracts.
================================================================================================
FILE: docs_layer-model/03_LAYER_TEMPLATE.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: bc1584c4c4ef486cdafbfc054f9c3a353bd4699117e021bf55c5ab8db1ce361c
CONTENT_BYTES: 8806
================================================================================================
# Layer Template
**File:** `layer-model/03_LAYER_TEMPLATE.md`
**Status:** Template
**Normative for kOA:** NO
**External normative references:** None
---
## Purpose
This template defines the standard structure for all files in:
```text
layer-model/layers/
````
Each layer file explains one functional layer of the broader kOA architecture.
The layer model is a **conceptual orientation model**. It does not redefine technical contracts, node responsibilities, schemas, Kristal artifact formats, canonicalization rules, validation gates, or operational runbooks.
Technical and normative system behavior remains defined in the kOA Digital Ecosystem technical documentation and its pinned dependencies.
---
## Layer File Naming
Layer files should use the following pattern:
```text
XX_short_layer_name.md
```
Examples:
```text
00_separation_of_functions.md
04_structured_knowledge.md
08_execution.md
13_deployment_translation.md
```
Use:
* two-digit numeric prefix;
* lowercase;
* underscores;
* short descriptive name;
* no spaces;
* no accents;
* no punctuation except underscores and hyphens if needed.
---
## Standard Layer File Structure
Use the following structure for every layer file.
````markdown
# Layer XX — Layer Name
**File:** `layer-model/layers/XX_layer_name.md`
**Status:** Conceptual layer definition
**Normative for kOA:** NO
**External normative references:** None
---
## 1. One-Sentence Definition
A short, reusable definition of the layer.
Example:
> Structured Knowledge is the layer where raw contributions become reusable, verifiable knowledge artifacts.
---
## 2. Core Function
Explain what this layer does in the kOA architecture.
This section should answer:
- What transformation happens here?
- What does this layer make possible?
- Why does this layer need to exist separately?
---
## 3. Core Question
State the key question this layer answers.
Example:
> What do we know clearly enough to preserve, compare, reuse, or act on?
---
## 4. Position in the Stack
Explain where this layer sits in the broader flow.
```text
Previous layer → This layer → Next layer
````
Example:
```text
Provenance / ingestion → Structured knowledge → Validation / canon
```
---
## 5. Inputs
List what enters this layer.
Examples:
* source material;
* participant contributions;
* documents;
* claims;
* context;
* observations;
* decisions from previous layers;
* feedback from later layers.
---
## 6. Outputs
List what this layer produces.
Examples:
* structured artifacts;
* validated references;
* decision records;
* tasks;
* memory records;
* learning objects;
* interface-ready outputs.
---
## 7. Internal kOA Components
List the kOA-specific concepts, modules, roles, or artifacts related to this layer.
Examples:
* Kristal;
* Orgo;
* ethiKos;
* EkoH;
* Smart Vote;
* Konnaxion;
* UCKK;
* King Klown;
* Inquisiteur;
* Assemblées;
* Archives.
Only include components that are directly relevant to the layer.
---
## 8. External Vocabulary
Translate the layer into language used outside kOA.
Examples:
* semantic interoperability;
* provenance;
* knowledge object;
* deliberative democracy;
* decision support;
* workflow management;
* institutional memory;
* systems literacy;
* narrative change;
* deployment strategy.
This section helps outside readers understand the layer without needing to know the full kOA vocabulary.
---
## 9. Comparable Frameworks or Standards
Mention external frameworks, standards, or fields that partially overlap with this layer.
Examples:
* OODA Loop;
* Viable System Model;
* FAIR Principles;
* W3C PROV;
* Verifiable Credentials;
* IAP2 Public Participation;
* Collective Impact;
* Competency-Based Education;
* Responsible AI;
* workflow / case management;
* organizational learning.
Do not overclaim equivalence. Use language such as:
> This layer is comparable to...
or:
> This layer partially overlaps with...
---
## 10. Failure Mode if Absent
Explain what breaks if this layer does not exist.
Examples:
* meaning remains ambiguous;
* sources cannot be trusted;
* knowledge is lost in feeds or documents;
* deliberation becomes noise;
* decisions become opaque;
* action is not followed through;
* lessons are forgotten;
* the system becomes dependent on a central authority;
* the architecture becomes too complex to adopt.
---
## 11. Boundary Rules
Define what this layer does **not** do.
This prevents layer confusion.
Examples:
* This layer does not decide truth.
* This layer does not execute tasks.
* This layer does not replace human judgment.
* This layer does not redefine Kristal contracts.
* This layer does not create new facts.
* This layer does not act as a source of institutional legitimacy by itself.
---
## 12. Relationship to Other Layers
Explain key relationships with adjacent and non-adjacent layers.
Use short bullets.
Example:
* Receives provenance-aware material from Layer 03.
* Produces structured artifacts for Layer 05.
* Feeds memory updates into Layer 09.
* Is surfaced through Layer 11 interfaces.
* May be explained publicly through Layer 12 narrative adoption.
---
## 13. Example
Provide one concrete example of this layer in use.
Keep it short.
Example:
> A public consultation produces many comments, documents, and claims. This layer turns selected claims into structured knowledge artifacts with sources, uncertainty, provenance, and reuse conditions.
---
## 14. Partner-Relevant Translation
Explain how this layer can be described to external partners.
Examples:
For civic tech partners:
> This layer helps transform public input into traceable decision material.
For education partners:
> This layer helps learners produce evidence of understanding and competence.
For data governance partners:
> This layer extends data governance into knowledge governance.
---
## 15. Minimal Definition for Index
One compact sentence to reuse in `02_LAYER_INDEX.md`.
Example:
> Structured Knowledge turns sources, claims, evidence, and context into reusable knowledge artifacts.
---
## 16. Open Questions
List unresolved issues.
Examples:
* What examples should be documented?
* Which external vocabulary is most appropriate?
* What should be validated in a pilot?
* Which internal components need clearer boundaries?
* What belongs in technical documentation instead of the layer model?
---
## 17. Change Notes
Track important updates.
```text
YYYY-MM-DD — Initial draft.
```
````
---
## Authoring Rules
When creating a layer file:
1. Keep the layer definition conceptual.
2. Do not duplicate technical contracts from the Digital Ecosystem docs.
3. Do not duplicate Kristal schemas, fields, canonicalization rules, or artifact contracts.
4. Do not turn layer files into pitch documents.
5. Do not add partner strategy unless it clarifies external vocabulary.
6. Keep examples short and concrete.
7. Clearly state what the layer does and does not do.
8. Preserve separation between conceptual architecture and technical implementation.
9. Use kOA internal terms, but always provide external vocabulary.
10. Prefer clarity over completeness.
---
## Recommended Layer File List
```text
layer-model/layers/00_separation_of_functions.md
layer-model/layers/01_orientation_mandate.md
layer-model/layers/02_semantics_meaning.md
layer-model/layers/03_provenance_ingestion.md
layer-model/layers/04_structured_knowledge.md
layer-model/layers/05_validation_canon.md
layer-model/layers/06_deliberation.md
layer-model/layers/07_decision_legitimacy.md
layer-model/layers/08_execution.md
layer-model/layers/09_memory_learning.md
layer-model/layers/10_resilience_autonomy.md
layer-model/layers/11_learning_interface.md
layer-model/layers/12_narrative_adoption.md
layer-model/layers/13_deployment_translation.md
````
---
## Compact Blank Template
Use this when drafting a new layer quickly.
````markdown
# Layer XX — Layer Name
**File:** `layer-model/layers/XX_layer_name.md`
**Status:** Conceptual layer definition
**Normative for kOA:** NO
**External normative references:** None
---
## 1. One-Sentence Definition
> ...
---
## 2. Core Function
...
---
## 3. Core Question
> ...
---
## 4. Position in the Stack
```text
Previous layer → This layer → Next layer
````
---
## 5. Inputs
* ...
---
## 6. Outputs
* ...
---
## 7. Internal kOA Components
* ...
---
## 8. External Vocabulary
* ...
---
## 9. Comparable Frameworks or Standards
* ...
---
## 10. Failure Mode if Absent
...
---
## 11. Boundary Rules
This layer does not:
* ...
---
## 12. Relationship to Other Layers
* ...
---
## 13. Example
...
---
## 14. Partner-Relevant Translation
...
---
## 15. Minimal Definition for Index
> ...
---
## 16. Open Questions
* ...
---
================================================================================================
FILE: docs_layer-model/layers/00_separation_of_functions.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 7343afd22c2ea6319529204126604b53dc21c9fa5846de2db6b968ad9ef9e282
CONTENT_BYTES: 8107
================================================================================================
# Layer 00 — Separation of Functions
**Layer ID:** 00
**Layer name:** Separation of Functions
**Status:** Conceptual orientation layer
**Normative for kOA Digital Ecosystem:** No
**External normative reference:** None
---
## 1. Function
This layer separates the major functions of the broader kOA architecture so they do not collapse into one another.
It defines the high-level distinction between:
- the movement;
- the learning institution;
- the digital infrastructure;
- the narrative interface;
- the ethical safeguard;
- the collective legitimacy mechanisms;
- the memory/archive function.
This layer exists before the technical pipeline. It clarifies what each major part of the system is allowed to do, what it is not allowed to become, and how it relates to the rest of the architecture.
The purpose is to prevent capture by a single person, single platform, single narrative, single institution, or single authority function.
---
## 2. Core Question
What must remain separate so that the kOA system can stay governable, explainable, criticizable, and non-capturing?
---
## 3. Internal kOA Components
The core separation is:
| Component | Function |
|---|---|
| `kOA` | Movement / broad civilizational initiative |
| `UCKK` | Learning city / educational institution |
| `kOA Digital Ecosystem` | Digital infrastructure and operational system |
| `King Klown` | Narrative interface / mobilization figure |
| `Inquisiteur` | Ethical and evidentiary safeguard |
| `Assemblées` | Collective legitimacy and deliberative bodies |
| `Archives` | Memory, continuity, and institutional learning |
---
## 4. Functional Distinctions
### 4.1 kOA — Movement
`kOA` is the broad movement and horizon.
It carries the civilizational, social, philosophical, and strategic intent of the initiative.
It is not identical to UCKK, Konnaxion, Orgo, Kristal, King Klown, or any single module.
**Function:** orientation, movement-building, strategic coherence.
---
### 4.2 UCKK — Learning City
`UCKK` is the educational and transmission layer.
It teaches people to understand systems, read the Grand Social Game, use the kOA tools responsibly, produce knowledge, participate in assemblies, launch challenges, and transform rules with lucidity.
It is not the whole of kOA.
It is also not to be represented as a publicly accredited university unless such accreditation exists.
**Function:** learning, training, progression, transmission, capacity-building.
---
### 4.3 kOA Digital Ecosystem — Infrastructure
The `kOA Digital Ecosystem` is the operational digital infrastructure.
It defines technical architecture, node responsibilities, kOA-owned artifacts, operational workflows, trust boundaries, deterministic behavior, and integration with Kristal.
It is not the whole movement.
It is not the narrative layer.
It is not the educational institution.
**Function:** digital operation, knowledge-to-action infrastructure, runtime behavior, traceability, execution support.
---
### 4.4 King Klown — Narrative Interface
`King Klown` is a narrative and pedagogical interface.
It can attract attention, dramatize systems, make complex structures memorable, and open public imagination.
It is not the supreme authority of kOA or UCKK.
It does not replace evidence, procedure, assemblies, validation, or ethical review.
**Function:** narrative access, public pedagogy, symbolic mobilization.
---
### 4.5 Inquisiteur — Ethical Safeguard
`L’Inquisiteur` is the integrity function.
It protects truthfulness, dignity, evidentiary discipline, non-manipulation, procedural clarity, and the right to question even central symbolic figures.
It is not a punitive authority.
It is not a hidden sovereign.
**Function:** integrity, ethical review, evidence review, anti-abuse safeguard.
---
### 4.6 Assemblées — Collective Legitimacy
`Les Assemblées` are the collective deliberative and legitimacy bodies.
They allow knowledge, challenges, complaints, decisions, governance questions, and institutional evolution to be handled through collective processes rather than personal authority.
They are not decorative.
They are not replaced by King Klown, software, AI, or founder intent.
**Function:** legitimacy, deliberation, collective governance.
---
### 4.7 Archives — Memory
`Les Archives` preserve continuity.
They hold institutional memory, decisions, lessons, records, outputs, canon versions, and learning traces.
They prevent the system from restarting from zero after every action or conflict.
**Function:** memory, continuity, learning, accountability.
---
## 5. Inputs
This layer receives:
- the broad kOA vision;
- the UCKK canon;
- Digital Ecosystem documentation;
- governance principles;
- ethical constraints;
- public-facing narrative elements;
- institutional roles;
- archive and memory requirements.
---
## 6. Outputs
This layer produces:
- a clear separation of system functions;
- a map of major entities and their roles;
- boundaries between movement, school, infrastructure, narrative, legitimacy, ethics, and memory;
- a safeguard against role confusion;
- a reference model for explaining the system to outsiders;
- a foundation for all later layers.
---
## 7. External Vocabulary
Comparable external vocabulary includes:
- separation of concerns;
- institutional architecture;
- governance model;
- role separation;
- checks and balances;
- functional decomposition;
- anti-capture design;
- accountability architecture;
- sociotechnical governance.
---
## 8. Failure Mode if Absent
If this layer is absent, the system becomes confusing and vulnerable to capture.
Possible failures include:
- the movement being confused with a platform;
- UCKK being mistaken for the entire project;
- King Klown being mistaken for supreme authority;
- the founder being mistaken for the system;
- the digital infrastructure being treated as the source of legitimacy;
- the narrative layer overpowering evidence and procedure;
- ethical review becoming optional;
- assemblies becoming symbolic rather than legitimate;
- archives being treated as storage instead of institutional memory.
Without this layer, kOA risks appearing as a personality project, a platform project, a school project, or a narrative project, instead of a layered architecture of collective capacity.
---
## 9. Relation to Other Layers
This layer comes before all other layers.
It defines the institutional and functional boundaries that allow the rest of the architecture to operate safely.
It supports:
- Layer 01 — Orientation / Mandate
by clarifying which entity carries which purpose.
- Layer 06 — Deliberation
by distinguishing deliberative legitimacy from narrative influence.
- Layer 07 — Decision / Legitimacy
by preventing decision authority from being hidden in software, charisma, or expertise.
- Layer 09 — Memory / Learning
by assigning memory to Archives rather than personal recollection or platform state alone.
- Layer 11 — Learning / Interface
by distinguishing UCKK from the whole kOA system.
- Layer 12 — Narrative / Adoption
by limiting King Klown to narrative and pedagogical functions.
- Layer 13 — Deployment / Translation
by allowing different partners to enter through the correct function without misunderstanding the whole.
---
## 10. Design Principle
No single function may absorb the others.
The movement does not replace the school.
The school does not replace the digital ecosystem.
The digital ecosystem does not replace the assemblies.
The narrative does not replace evidence.
The founder does not replace governance.
The AI does not replace collective judgment.
The archive does not replace living deliberation.
The safeguard does not become sovereign authority.
---
## 11. One-Sentence Definition
Separation of Functions is the layer that keeps kOA’s movement, school, infrastructure, narrative, safeguards, legitimacy, and memory distinct so the whole system remains governable, criticizable, transmissible, and resistant to capture.
================================================================================================
FILE: docs_layer-model/layers/01_orientation_mandate.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 3265ac2a0c1454fbf501fa173f072b09b88325fcb9160d89b6ff869b508c867a
CONTENT_BYTES: 5649
================================================================================================
# Layer 01 — Orientation / Mandate
**Layer status:** Conceptual layer
**Normative for kOA:** NO
**Primary technical anchor:** `technical-docs/20-nodes/keter-mandate.md`
---
## 1. Function
The Orientation / Mandate layer defines the purpose, direction, constraints, and governing intent of the system.
It answers the question:
> What is this system allowed, required, and forbidden to do?
This layer does not produce canonical truth. It does not execute work. It does not deliberate or decide specific cases. It defines the mandate under which all downstream layers operate.
In the kOA Digital Ecosystem, this layer is technically anchored by **Keter: Mandate**, which publishes versioned governance artifacts used by Orgo, Kristal gates, Konnaxion distribution policy, and Architect behavior policies.
---
## 2. Core question
What is the governing purpose of the system, and under which constraints must all downstream activity occur?
Sub-questions:
- What mission is being served?
- What scope is included or excluded?
- What ethical, legal, operational, or institutional constraints apply?
- What risks are acceptable or unacceptable?
- Which policies are active?
- What must fail closed?
- What requires review or approval?
- What is explicitly forbidden?
---
## 3. Internal kOA components
Relevant internal components:
- **Keter**
- **Mandate Bundle**
- policy selections
- enforcement levels
- operating principles
- governance constraints
- risk thresholds
- prohibited actions
- review requirements
- mission / scope statements
Related downstream components:
- **Orgo** — consumes mandate constraints for pipeline governance
- **Kristal gates** — apply mandate-bound validation constraints
- **Konnaxion** — applies distribution and activation policies
- **Architect** — respects behavior policies and planning constraints
---
## 4. Inputs
The Orientation / Mandate layer receives:
- organizational objectives;
- community purpose;
- mission statements;
- ethical requirements;
- legal or regulatory constraints;
- risk appetite;
- operational service-level expectations;
- approved policy templates;
- governance decisions;
- institutional boundaries;
- non-goals and exclusions.
These inputs must be made explicit enough to guide deterministic downstream interpretation.
---
## 5. Outputs
The primary output is a **governance mandate**.
In the technical ecosystem, this becomes a **Mandate Bundle**: a versioned, auditable container that can include mandate identity, descriptive fields, constraints, objectives, policy documents, rule sets, and optional signatures.
Conceptually, this layer outputs:
- a mission definition;
- a scope definition;
- explicit constraints;
- active policy selections;
- enforcement levels;
- forbidden actions;
- review requirements;
- decision principles;
- non-goals;
- success criteria;
- reproducibility-relevant policy context.
These outputs constrain later layers. They do not replace them.
---
## 6. External vocabulary
Comparable external terms:
- mandate;
- mission;
- charter;
- governance source;
- policy bundle;
- operating principles;
- intended impact;
- theory of change;
- institutional mandate;
- governance framework;
- constitutional layer;
- policy-as-code;
- organizational constraints;
- decision rights;
- authority boundary.
Useful public-facing translation:
> This is the layer where the system defines its purpose, limits, and rules before knowledge, decisions, or actions are produced.
---
## 7. Failure mode if absent
If this layer is absent, the system can still process inputs, generate outputs, or execute tasks, but it lacks governed direction.
Common failure modes:
- unclear purpose;
- mission drift;
- hidden policy assumptions;
- ad-hoc overrides;
- conflicting downstream behavior;
- ambiguous authority;
- unbounded execution;
- unverifiable policy changes;
- runtime exceptions replacing governance;
- downstream components making implicit decisions they should not own.
In the technical ecosystem, a missing or ambiguous mandate means the governed pipeline cannot start safely. Downstream components cannot know which policies apply, what constraints bind them, or when to fail closed.
---
## 8. Relation to other layers
### Previous layer
**Layer 00 — Separation of Functions**
Layer 00 separates the major institutional and functional roles: movement, school, infrastructure, narrative, safeguards, legitimacy, and memory.
Layer 01 then gives the active mandate under which those functions operate.
### Next layer
**Layer 02 — Semantics / Meaning**
Once the mandate is defined, the system must clarify the meanings, terms, categories, and concepts used under that mandate.
Without semantic clarity, the mandate cannot be interpreted reliably.
### Downstream dependency
All later layers depend on this one:
```text
Orientation / Mandate
→ Semantics
→ Provenance
→ Structured Knowledge
→ Validation
→ Deliberation
→ Decision
→ Execution
→ Memory
````
The mandate constrains the whole chain.
---
## 9. Layer boundary
This layer defines governing intent and constraints.
It does not:
* validate factual truth;
* produce Kristals;
* resolve claims;
* run deliberations;
* count votes;
* execute tasks;
* mutate canon;
* override downstream gates at runtime.
Its role is to define the policy surface that downstream layers must respect.
---
## 10. One-sentence definition
**Orientation / Mandate is the layer where kOA defines the mission, scope, constraints, policies, and governing intent that bind all downstream knowledge, decision, execution, and memory processes.**
================================================================================================
FILE: docs_layer-model/layers/02_semantics_meaning.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 2f81bd4d14d7338d7f376aae309452b9bdfdbd17bee1e87f6465fb9cf992d814
CONTENT_BYTES: 12471
================================================================================================
# Layer 02 — Semantics / Meaning
**Layer:** 02
**Name:** Semantics / Meaning
**Status:** Conceptual layer definition
**Normative for kOA:** NO
**External normative reference:** None
**Technical scope:** Orientation layer only. This file does not define schemas, canonicalization rules, artifact contracts, runtime behavior, or validation gates.
---
## 1. Function
The Semantics / Meaning layer makes meaning explicit before knowledge is structured, validated, deliberated, or acted upon.
Its function is to clarify:
- what terms mean;
- what concepts are being used;
- how concepts relate;
- where meanings are ambiguous;
- where different words refer to the same thing;
- where the same word refers to different things;
- how meaning shifts across domains, communities, languages, and contexts.
This layer prevents the system from treating raw language as already-understood knowledge.
It does not decide truth.
It does not validate claims.
It does not produce final canon.
It prepares meaning so later layers can work responsibly.
---
## 2. Core question
> What does this mean, in this context, and what ambiguities must remain visible before the system treats it as knowledge?
Secondary questions:
- Which terms require definition?
- Which concepts are equivalent, related, conflicting, or domain-specific?
- Which meanings are uncertain or disputed?
- Which definitions are local to a community, field, institution, or use case?
- What must be preserved so later layers do not collapse meaning too early?
---
## 3. Position in the layer stack
The Semantics / Meaning layer sits after orientation and before structured knowledge.
```text
Layer 01 — Orientation / Mandate
↓
Layer 02 — Semantics / Meaning
↓
Layer 03 — Provenance / Ingestion
↓
Layer 04 — Structured Knowledge
↓
Layer 05 — Validation / Canon
````
In practice, semantics interacts with provenance continuously. Meaning is never separated from context, source, speaker, domain, language, and use.
---
## 4. Internal kOA components
Relevant internal components and concepts include:
* SemantiK
* SenTient
* Architect
* controlled vocabulary
* concept maps
* term registry
* aliases
* definitions
* semantic mappings
* ambiguity records
* translation mappings
* domain-bounded meanings
* knowledge graph structures
* glossary entries
* meaning constraints
* semantic reconciliation notes
This layer may support Kristal production, but it does not define Kristal schemas or contracts.
---
## 5. Inputs
Typical inputs include:
* raw language;
* source documents;
* participant contributions;
* public comments;
* debate material;
* institutional terms;
* technical terms;
* cultural terms;
* claims;
* questions;
* translations;
* domain vocabularies;
* project-specific terminology;
* user-generated labels;
* legacy documents;
* existing glossaries.
Examples:
```text
"expertise"
"support"
"public good"
"commons"
"credential"
"university"
"sovereignty"
"AI governance"
"collective intelligence"
"ethical reliability"
```
Each of these terms can mean different things depending on context. The Semantics / Meaning layer prevents the system from pretending otherwise.
---
## 6. Outputs
This layer produces meaning-ready structures such as:
* normalized terms;
* concept definitions;
* aliases;
* disputed meanings;
* ambiguity notes;
* semantic mappings;
* domain-specific definitions;
* translation mappings;
* relationship maps;
* entity/concept distinctions;
* assumptions;
* unresolved semantic questions;
* glossary candidates;
* references to source contexts.
Example output:
```text
Term: "credential"
Possible meanings:
1. Formal accredited diploma
2. Internal competency recognition
3. Machine-verifiable claim
4. Portfolio-backed evidence of skill
kOA handling:
Do not collapse these meanings. Preserve distinction.
UCKK Parchemins are internal competency recognitions unless officially accredited.
```
---
## 7. External vocabulary
Useful external language for this layer:
| kOA language | External vocabulary |
| ---------------------- | ----------------------------------------- |
| Semantics / Meaning | semantic layer |
| SemantiK | semantic architecture |
| concept mapping | ontology / taxonomy / knowledge graph |
| glossary | controlled vocabulary |
| aliases | synonym mapping / entity resolution |
| ambiguity record | semantic uncertainty / unresolved meaning |
| translation mapping | multilingual semantic alignment |
| meaning constraints | semantic governance |
| domain-bounded meaning | contextual definition / domain ontology |
Recommended external terms:
* semantic interoperability;
* ontology;
* taxonomy;
* controlled vocabulary;
* knowledge graph;
* data dictionary;
* concept map;
* entity resolution;
* semantic reconciliation;
* multilingual mapping;
* sensemaking;
* semantic governance.
---
## 8. Boundaries
This layer is responsible for meaning.
It is not responsible for:
* proving that a claim is true;
* deciding which option should win;
* assigning tasks;
* executing workflows;
* certifying competence;
* publishing final canon;
* redefining Kristal artifact contracts;
* replacing community deliberation;
* replacing human interpretation.
Boundary rule:
> Meaning must be clarified before it is structured as knowledge, but clarification is not the same as validation.
---
## 9. Operational principles
### 9.1 Preserve ambiguity
If a term has multiple meanings, the system must preserve that ambiguity instead of silently selecting one.
```text
Bad:
"support" = one meaning
Good:
"support" may mean agreement, funding, technical help, emotional care, welfare support, or political endorsement depending on context.
```
### 9.2 Keep raw expression and normalized concept separate
The original wording should remain available.
```text
Raw expression:
"The system should support communities."
Possible normalized concepts:
- provide tools to communities
- fund communities
- emotionally support communities
- politically endorse communities
- technically maintain community infrastructure
```
### 9.3 Do not turn semantic resolution into truth
Resolving what a statement means does not prove that the statement is true.
```text
Semantic resolution:
The claim is about funding access.
Validation:
The claim is accurate, sourced, current, and within scope.
```
### 9.4 Context matters
Meanings may be:
* field-specific;
* community-specific;
* culturally specific;
* legally specific;
* historically specific;
* project-specific;
* language-specific.
### 9.5 Translation is mapping, not identity
A translation is not always an exact equivalent. The system should preserve possible loss, shift, or mismatch of meaning.
### 9.6 Meaning must remain contestable
Definitions should be versioned, reviewable, and revisable. A definition can stabilize usage without becoming untouchable dogma.
---
## 10. Failure mode if absent
If this layer is missing, the system may:
* confuse words with knowledge;
* treat ambiguous terms as settled;
* merge different concepts incorrectly;
* split equivalent concepts unnecessarily;
* misclassify expertise;
* apply EkoH weights to the wrong domain;
* distort Smart Vote readings;
* produce invalid Kristals;
* validate claims under the wrong meaning;
* assign Orgo tasks based on misunderstood decisions;
* let narrative framing override semantic precision;
* create conflict because people appear to disagree when they are using different meanings.
Core failure:
> Without the Semantics / Meaning layer, later layers may act on misunderstood language.
---
## 11. Relation to other layers
### Previous layer: Layer 01 — Orientation / Mandate
Orientation defines why the system is operating and within what mandate.
Semantics clarifies the meaning of the terms used inside that mandate.
Example:
```text
Mandate:
"Support community sovereignty."
Semantic questions:
What does "support" mean?
What does "community" mean?
What does "sovereignty" mean?
Is this legal, cultural, technical, political, educational, or infrastructural sovereignty?
```
### Next layer: Layer 03 — Provenance / Ingestion
Provenance captures where material comes from.
Semantics interprets what the material means.
The two layers must remain linked:
```text
meaning without provenance = floating interpretation
provenance without meaning = raw trace without understanding
```
### Downstream relation: Layer 04 — Structured Knowledge
Structured knowledge depends on clarified meaning.
A Kristal should not encode a claim if the meaning of the claim is unresolved or misleadingly collapsed.
### Downstream relation: Layer 06 — Deliberation
Deliberation needs semantic clarity so participants know what they are agreeing or disagreeing about.
### Downstream relation: Layer 07 — Decision / Legitimacy
Decision readings require stable terms. A vote on an ambiguous proposal produces ambiguous legitimacy.
### Downstream relation: Layer 08 — Execution
Execution requires semantic precision. A task based on unclear meaning may be executed correctly but still achieve the wrong thing.
---
## 12. Example: UCKK and the word “university”
Semantic issue:
```text
UCKK uses university-like language internally, but it is not an accredited university.
```
Required semantic distinction:
```text
"Université" as symbolic/internal language
≠ accredited legal university
≠ public diploma-granting institution
≠ informal learning community
≠ experimental learning city
```
Layer 02 responsibility:
* preserve the distinction;
* make the term externally legible;
* prevent misleading claims;
* support correct partner-facing language.
External wording:
```text
UCKK is an experimental learning city / systems-literacy learning ecosystem.
```
---
## 13. Example: EkoH and “expertise”
Semantic issue:
```text
Expertise can mean formal credentials, demonstrated contribution, lived experience, domain-specific skill, ethical reliability, or institutional status.
```
Layer 02 responsibility:
* separate these meanings;
* prevent expertise from becoming a single global score;
* support domain-bounded interpretation;
* distinguish expertise from legitimacy;
* distinguish credibility from authority.
External wording:
```text
EkoH provides domain-bounded trust and expertise signals. It does not define the total value of a person.
```
---
## 14. Example: Smart Vote and “support”
Semantic issue:
```text
Support can mean preference, endorsement, informed agreement, stakeholder approval, ethical acceptance, or willingness to participate.
```
Layer 02 responsibility:
* clarify which type of support is being measured;
* preserve multiple readings;
* prevent raw popularity from being mistaken for full legitimacy;
* support transparent decision lenses.
External wording:
```text
Smart Vote provides transparent decision-support readings, not a single hidden authority score.
```
---
## 15. Design constraint
The Semantics / Meaning layer must support the kOA Digital Ecosystem without duplicating technical contracts.
It may define:
* conceptual role;
* vocabulary;
* distinctions;
* examples;
* failure modes;
* relationships to other layers.
It must not define:
* Kristal schemas;
* canonicalization rules;
* field lists;
* signature formats;
* runtime pack contracts;
* validation gate implementations.
Those belong to the technical documentation and pinned Kristal references.
---
## 16. Minimal validation checklist
A semantic process is minimally valid when it can answer:
* What are the key terms?
* What do they mean in this context?
* Are there competing meanings?
* Are any meanings domain-specific?
* Are raw expressions preserved?
* Are normalized concepts clearly separated from original wording?
* Are translations or aliases marked as mappings rather than exact identities?
* Are unresolved meanings flagged?
* Are downstream layers prevented from treating ambiguity as settled knowledge?
---
## 17. One-sentence definition
The Semantics / Meaning layer is where kOA makes terms, concepts, relationships, ambiguities, and contextual meanings explicit before they become structured knowledge, decisions, or actions.
================================================================================================
FILE: docs_layer-model/layers/03_provenance_ingestion.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: f32302dfee8911e1e7d5a62f1d0ee35cbcfd3f77e586c28a9dc3661d9893487c
CONTENT_BYTES: 9618
================================================================================================
# Layer 03 — Provenance / Ingestion
## 1. Function
The Provenance / Ingestion layer captures external material before it becomes knowledge.
Its function is to bring raw inputs into kOA in a way that is:
- traceable;
- reproducible;
- auditable;
- content-addressed where possible;
- policy-aware;
- safe for downstream processing.
This layer does not decide what is true. It preserves what entered the system, where it came from, under what context, and how it was captured.
In the kOA Digital Ecosystem, the main technical node corresponding to this layer is **Chokmah — Inputs**, the ingest and provenance boundary.
## 2. Core question
> What did the system receive, from where, under what conditions, and can that exact input be referenced again?
This layer answers the pre-knowledge question:
> Before we interpret, validate, deliberate, decide, or act — what exactly did we see?
## 3. Internal kOA components
Primary internal components:
- **Chokmah** — ingest and provenance boundary;
- **Input Snapshot** — immutable captured input;
- **Input Snapshot Set** — stable set of snapshot references;
- **Snapshot Manifest** — provenance and acquisition metadata;
- **Ingest Receipt** — result of an ingestion attempt;
- **Quarantine Report** — optional report when material is blocked, restricted, unsafe, or requires special handling;
- **Orgo Build Record** — downstream operational record binding builds to stable input references;
- **Mandate / policy tags** — constraints inherited from the mandate and blueprint context.
Related technical references:
- `technical-docs/20-nodes/chokmah-inputs.md`
- `technical-docs/10-system/architecture.md`
- `technical-docs/10-system/lifecycle.md`
- `technical-docs/30-artifacts/build-record.md`
- `technical-docs/30-artifacts/mandate-bundle.md`
- `technical-docs/60-guides/integrators.md`
If the repository still uses `docs/` instead of `technical-docs/`, replace `technical-docs/` with `docs/`.
## 4. Inputs
This layer receives raw material from configured sources.
Typical inputs include:
- files;
- feeds;
- APIs;
- user submissions;
- curated evidence bundles;
- source documents;
- uploads;
- connectors;
- external datasets;
- prior artifact references;
- contextual metadata;
- mandate and policy tags;
- confidentiality classifications;
- retention or quarantine directives.
The input is not yet trusted knowledge. It is material to be captured.
## 5. Outputs
This layer produces stable references and ingestion evidence.
Primary outputs:
- **Input Snapshot Set**
- one or more content-addressed snapshot references;
- **Snapshot Manifest**
- mapping from snapshot reference to provenance and acquisition metadata;
- source identity;
- retrieval time;
- authority or authentication context;
- routing tags;
- policy tags;
- deterministic transformation steps, if any;
- integrity metadata such as hashes or checksums;
- **Ingest Receipt**
- snapshot references created or confirmed;
- warnings;
- errors;
- partial result indicators;
- diagnostics references;
- **Quarantine Report**, when applicable
- blocked content;
- unsafe content;
- restricted content;
- policy violation;
- classification mismatch;
- malware or sensitive data handling.
The downstream system should depend on recorded snapshot references, not live sources.
## 6. External vocabulary
Comparable external terms:
- provenance;
- data lineage;
- source traceability;
- evidence chain;
- chain of custody;
- immutable snapshot;
- content-addressed input;
- audit trail;
- reproducible input reference;
- ingestion boundary;
- source metadata;
- input manifest;
- evidence intake;
- acquisition metadata.
Useful external framing:
> Provenance / Ingestion is kOA’s source traceability layer.
Or:
> It is the layer that preserves evidence before interpretation.
## 7. Boundary rules
This layer may capture, package, and reference inputs.
It must not silently interpret them.
### This layer may
- ingest raw material;
- store immutable snapshots;
- record provenance;
- normalize transport or container formats if deterministic and explicitly recorded;
- classify confidentiality and handling requirements;
- produce deterministic ingest results;
- quarantine material under policy;
- emit stable references for downstream processing.
### This layer must not
- decide truth;
- create canonical knowledge;
- alter meaning silently;
- “fix” content without recording the transformation;
- enrich content as if the enrichment were part of the original source;
- allow downstream stages to depend on mutable live sources;
- erase provenance;
- hide transformation steps;
- leak restricted or confidential material downstream.
## 8. Invariants
### 8.1 Immutability
Once a snapshot reference is issued, the referenced bytes must not change.
If the source changes, a new snapshot is created.
### 8.2 Content addressing
Same payload bytes should resolve to the same snapshot reference, subject to the defined packaging rules.
Metadata changes belong in the manifest, not in the payload identity.
### 8.3 Complete provenance
Every snapshot must have enough provenance for audit and reproduction:
- where it came from;
- when it was retrieved;
- under which policy or authority context;
- what access constraints applied;
- what transformations were applied;
- which tools or adapters were involved.
### 8.4 Idempotent ingestion
Re-ingesting the same payload should return the same reference.
Retries must not create duplicate distinct snapshots for identical bytes.
### 8.5 Confidentiality enforcement
Restricted material must remain access-controlled.
Downstream stages should receive references unless explicitly authorized to fetch bytes.
### 8.6 No hidden enrichment
The ingestion layer captures material. It does not introduce new facts.
Any derived interpretation belongs to a later layer.
### 8.7 Build reproducibility
Orgo must be able to bind a build to a stable input set.
Downstream compilation must depend on recorded snapshot references, not mutable external sources.
## 9. Relation to other layers
### Previous layer
Layer 02 — **Semantics / Meaning**
The semantic layer defines the concepts, categories, and meaning structures that help describe inputs and route them properly.
### This layer
Layer 03 — **Provenance / Ingestion**
Captures raw material with traceability before interpretation.
### Next layer
Layer 04 — **Structured Knowledge**
Transforms provenance-preserved inputs into structured claims, evidence objects, Kristal-adjacent artifacts, and eventually validated knowledge.
The transition is:
```text
Raw external material
→ provenance-preserved snapshots
→ structured proposals / claims
→ validation
→ canonical knowledge
````
## 10. Failure mode if absent
Without this layer, the system cannot reliably know what its knowledge is based on.
Typical failures:
* sources are cited but cannot be reproduced;
* live external data changes without record;
* claims lose their evidence chain;
* downstream outputs cannot be audited;
* participants dispute what was originally submitted;
* restricted material leaks;
* transformations alter meaning silently;
* builds cannot be reproduced;
* validation becomes unverifiable;
* memory becomes anecdotal rather than evidential.
The result is epistemic drift:
> The system may appear to know, but it can no longer prove what it saw.
## 11. Failure handling
This layer should fail closed when it cannot guarantee correct capture or provenance.
Common failure cases:
* source unreachable;
* authentication failure;
* partial download;
* truncated payload;
* hash mismatch;
* unsupported format;
* unsafe content;
* policy violation;
* classification mismatch;
* storage failure;
* inability to commit immutable snapshot;
* malformed content that violates declared constraints.
Expected behavior:
* stop ingestion where required;
* return stable error codes;
* preserve diagnostic references;
* quarantine when required;
* avoid coercing malformed content into a false-valid state;
* avoid downstream continuation without sufficient provenance.
## 12. Observability
This layer should emit enough observability to support debugging, auditing, and rebuilds.
Useful signals:
* ingest adapter identity;
* ingest adapter version;
* configuration reference;
* source descriptor reference;
* snapshot ID;
* snapshot set reference;
* manifest reference;
* retrieval timestamp;
* policy tag reference;
* classification applied;
* transformation steps;
* warnings;
* stable error codes;
* diagnostics references;
* correlation ID;
* build ID or request ID when available.
## 13. Example flow
```text
1. Orgo receives or schedules an ingest request.
2. Chokmah reads the source descriptor.
3. Chokmah fetches the source material.
4. Chokmah stores the exact retrieved bytes as an immutable snapshot.
5. Chokmah records provenance and acquisition metadata in a snapshot manifest.
6. Chokmah emits an ingest receipt.
7. Orgo binds the input snapshot set to a build context.
8. Downstream extractors use snapshot references, not live sources.
```
## 14. Layer definition
**Provenance / Ingestion** is the layer where external material enters kOA as traceable, immutable, policy-aware input references before it can become structured knowledge.
## 15. One-sentence definition
Provenance / Ingestion preserves exactly what kOA received, where it came from, and under what conditions, so downstream knowledge, decisions, actions, and memory remain auditable and reproducible.
================================================================================================
FILE: docs_layer-model/layers/04_structured_knowledge.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 45a78ec3478b51cad1e12a13d4ed7bad339879a7944c1d462b1d9a8ec19c1a97
CONTENT_BYTES: 11783
================================================================================================
# Layer 04 — Structured Knowledge
## 1. Function
The Structured Knowledge layer turns source-bound material into reusable knowledge artifacts.
Its role is to transform raw or semi-structured inputs — documents, claims, evidence, definitions, observations, testimony, datasets, prior outputs, and resolved semantic material — into knowledge units that can be validated, compiled, distributed, queried, rendered, reused, and remembered.
In kOA terms, this layer is where knowledge stops being only prose, discussion, notes, or files, and becomes part of a governed knowledge substrate.
This layer does **not** define Kristal artifact schemas. Kristal v4 remains the normative source for Kristal-owned artifact contracts. The layer model describes the role that structured knowledge plays in the broader kOA architecture.
---
## 2. Core question
What do we know clearly enough to preserve, validate, reuse, query, render, distribute, or act on?
Sub-questions:
- What claim, concept, entity, definition, or relationship is being represented?
- What evidence supports it?
- Where did the supporting material come from?
- What uncertainty, conflict, ambiguity, or limitation remains?
- Can the knowledge be validated?
- Can it be reused outside the original context?
- Can it be carried into later decision, execution, or memory layers?
---
## 3. Internal kOA components
Relevant kOA components and concepts:
- Kristal
- Claim-IR
- Resolved Claim-IR
- Validation Report
- Exchange
- Runtime Pack
- Da’at / Kristal Bridge
- SenTient
- Konnaxion
- Orgo build records
- Release records
- provenance references
- content-addressed references
- schema conformance checks
- canonical artifacts
- offline query/runtime material
The central operational role is played by the Kristal boundary: kOA prepares, validates, hands off, consumes, distributes, and operates knowledge artifacts without re-specifying Kristal’s normative contracts.
---
## 4. Inputs
This layer receives material from earlier layers, especially Layer 03 — Provenance / Ingestion.
Inputs may include:
- source snapshots;
- source references;
- documents;
- datasets;
- testimony;
- civic input;
- discussions;
- extracted claims;
- definitions;
- entities;
- semantic relationships;
- candidate mappings;
- resolved claims;
- ambiguity markers;
- validation diagnostics;
- policy bundles;
- mandate constraints;
- provenance metadata.
Inputs must retain enough provenance for later audit, validation, reproduction, or refusal.
---
## 5. Outputs
This layer produces or prepares structured knowledge outputs such as:
- reusable claims;
- structured definitions;
- entity and relationship records;
- provenance-bound knowledge units;
- validation-ready material;
- validation results;
- canonical knowledge artifacts;
- Exchange artifacts;
- Runtime Packs;
- content-addressed references;
- queryable knowledge packages;
- material suitable for rendering, distribution, execution, and memory.
The outputs of this layer should be portable enough to support downstream use without forcing every later actor to reread and reinterpret the original sources.
---
## 6. External vocabulary
Useful external vocabulary for explaining this layer:
- structured knowledge;
- knowledge artifact;
- verified knowledge artifact;
- knowledge object;
- knowledge package;
- FAIR knowledge object;
- knowledge graph;
- semantic data;
- claim-level provenance;
- evidence-backed claim;
- provenance-aware knowledge unit;
- portable knowledge artifact;
- canonical knowledge artifact;
- runtime knowledge package;
- queryable evidence base;
- machine-verifiable knowledge;
- data lineage;
- evidence lineage;
- semantic memory substrate.
Recommended public phrasing:
> Structured Knowledge is the layer where raw contributions become reusable, provenance-aware knowledge artifacts.
Technical phrasing:
> This layer prepares and consumes validated, schema-conformant knowledge artifacts that can be compiled into canonical exchange and runtime forms.
---
## 7. Failure mode if absent
If this layer is missing, knowledge remains trapped in unstable forms:
- posts;
- comments;
- PDFs;
- reports;
- notes;
- oral memory;
- isolated databases;
- private files;
- chat logs;
- human interpretation only.
Without structured knowledge:
- claims cannot be reliably traced to evidence;
- definitions drift;
- versions become confused;
- contradictions remain hidden;
- summaries replace validation;
- downstream decisions depend on fragile interpretation;
- AI may hallucinate or over-compress;
- later users must redo the same interpretation work;
- communities lose memory;
- knowledge cannot be carried offline;
- validated results cannot become durable infrastructure.
The failure mode is not only technical. It is civic: groups cannot govern what they cannot structure, verify, reuse, or remember.
---
## 8. Relation to other layers
### Previous layer
Layer 03 — Provenance / Ingestion
Structured Knowledge depends on provenance-aware input. The system should know where material came from, when it was captured, under what authority or policy context, and what transformations were applied.
### Current layer
Layer 04 — Structured Knowledge
This layer organizes meaning into reusable knowledge units and prepares material for validation, compilation, distribution, rendering, and memory.
### Next layer
Layer 05 — Validation / Canon
Structured knowledge is not automatically canonical. It must pass validation gates before it can become accepted canonical material or be compiled into publishable/distributable artifacts.
### Downstream layers
Structured knowledge feeds:
- deliberation;
- decision support;
- execution;
- rendering;
- distribution;
- offline runtime;
- memory;
- education;
- audit;
- future cycles.
---
## 9. Core invariants
This layer should respect the following invariants:
1. **No schema duplication**
kOA layer-model documentation must not restate Kristal v4 schemas, field lists, canonicalization rules, signing rules, or artifact contracts.
2. **Kristal remains normative**
When a Kristal-owned artifact is involved, the pinned Kristal v4 documentation is the source of truth.
3. **Provenance must be preserved**
Structured knowledge must retain links to source material, validation context, and relevant diagnostic information.
4. **Validation precedes canon**
Structured material is not canonical merely because it is structured. It must pass validation.
5. **No compile on fail**
If validation fails, compilation must not proceed.
6. **No hidden mutation of truth**
Feedback, corrections, disputes, and updates must become governed work, not silent edits to canon.
7. **Portability matters**
Knowledge should be structured so it can travel across contexts, systems, and runtime environments.
8. **Offline usability matters**
When packaged into runtime form, knowledge should remain usable without continuous reliance on a central online platform.
9. **Structured does not mean certain**
Structured knowledge may preserve uncertainty, ambiguity, conflict, or unresolved status explicitly.
---
## 10. Relationship to Kristal
Kristal is the truth substrate and artifact boundary for this layer.
In the kOA Digital Ecosystem, Kristal-owned artifacts include canonical outputs such as Exchange and Runtime Pack forms. kOA integrates with these artifacts through pinned Kristal v4 references, conformance requirements, and the Da’at / Kristal Bridge.
This layer therefore uses the term “structured knowledge” at the conceptual level, while avoiding field-level duplication of Kristal contracts.
Correct relation:
```text
kOA layer model
→ explains the role of structured knowledge
kOA technical docs
→ define kOA responsibilities, nodes, gates, and operational behavior
Kristal v4
→ defines normative Kristal artifact contracts and schemas
````
---
## 11. Example flow
```text
source material
→ provenance snapshot
→ extracted claim
→ resolved claim
→ validation report
→ Kristal compilation
→ Exchange
→ Runtime Pack
→ distribution / activation
→ rendering / query / execution
→ feedback / memory
```
This flow shows how knowledge becomes increasingly structured, validated, portable, and operational.
---
## 12. Minimal example
A community consultation produces a long discussion about housing.
Without Layer 04:
```text
discussion thread
→ summary
→ opinion
→ forgotten context
```
With Layer 04:
```text
discussion thread
→ extracted claims
→ source-linked evidence
→ definitions and entities
→ unresolved conflicts marked explicitly
→ validation-ready knowledge units
→ compiled artifact
→ reusable basis for deliberation, decision, and memory
```
The difference is that knowledge becomes reusable infrastructure rather than disposable content.
---
## 13. External alignment
This layer can be aligned with existing external concepts:
| kOA concept | External alignment |
| ---------------------- | ---------------------------------------------------- |
| Kristal | portable verified knowledge artifact |
| Claim-IR | claim representation / evidence-bearing assertion |
| Resolved Claim-IR | resolved semantic claim / disambiguated claim object |
| Validation Report | acceptance gate / quality assurance output |
| Exchange | canonical knowledge exchange artifact |
| Runtime Pack | portable offline knowledge package |
| provenance refs | evidence lineage / data lineage |
| content-addressed refs | integrity-aware knowledge reference |
| queryable pack | local knowledge runtime / offline evidence base |
The point is not to replace external vocabulary, but to make kOA’s internal terms legible to people coming from data governance, civic tech, knowledge graphs, responsible AI, education, and public-sector infrastructure.
---
## 14. One-sentence definition
Structured Knowledge is the layer where provenance-aware inputs become reusable, verifiable knowledge artifacts that can be validated, compiled, distributed, queried, rendered, acted on, and remembered.
---
## 15. Short public explanation
Most systems treat knowledge as documents or content. kOA treats knowledge as infrastructure.
Layer 04 is where that shift happens.
It turns human material — claims, sources, discussions, definitions, evidence, and context — into structured knowledge artifacts that can travel, be verified, support decisions, survive offline, and feed future learning.
---
## 16. Implementation boundary
This file is conceptual.
It should not be used as:
* a Kristal schema;
* a field-level artifact contract;
* a canonicalization rule;
* a signature rule;
* a validation test vector;
* a replacement for Kristal v4 documentation;
* a replacement for kOA technical integration docs.
For implementation, use the technical documentation and pinned Kristal references.
---
## 17. Related technical documentation
From the kOA Digital Ecosystem technical docs:
* `technical-docs/index.md`
* `technical-docs/10-system/architecture.md`
* `technical-docs/20-nodes/daat-kristal-bridge.md`
* `technical-docs/20-nodes/tiferet-sentient.md`
* `technical-docs/20-nodes/yesod-compiler.md`
* `technical-docs/40-integration/kristal-v4/index.md`
* `technical-docs/40-integration/kristal-v4/contract-pointers.md`
* `technical-docs/40-integration/kristal-v4/conformance.md`
* `technical-docs/50-operations/pipeline.md`
If the technical folder is still named `docs/`, replace `technical-docs/` with `docs/`.
================================================================================================
FILE: docs_layer-model/layers/05_validation_canon.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: b7b33aa7d641634428e77ec2effaf71e48b92935d593fb4b3fc5acd8a60e4a25
CONTENT_BYTES: 7907
================================================================================================
# Layer 05 — Validation / Canon
## 1. Function
The Validation / Canon layer determines what may become stable enough to be compiled, published, distributed, referenced, rendered, or acted on.
Its role is not to create truth by assertion. Its role is to enforce the boundary where proposed knowledge becomes validated, canonical, versioned, traceable, and safe to reuse.
In the kOA Digital Ecosystem, validation sits between resolved knowledge and canonical compilation:
```text
Ingest → Extract → Resolve → Validate → Compile → Publish/Distribute
````
Nothing should enter the canon merely because it was submitted, generated, summarized, popular, or useful. It must pass explicit validation gates.
## 2. Core question
What is stable, validated, and traceable enough to become canonical or canon-adjacent?
Sub-questions:
* Has the claim, artifact, or resolution been validated?
* Are its sources and provenance traceable?
* Are ambiguities preserved rather than hidden?
* Are failures explicit and structured?
* Are inputs, policies, configurations, and references pinned?
* Can the result be rebuilt, audited, compared, or contested?
* Is this allowed to become canonical truth, or only proposed work?
## 3. Internal kOA components
Relevant kOA components:
* Orgo
* Kristal
* SenTient
* Validation Report
* Kristal Exchange
* Runtime Pack
* Build Record
* Release Record
* Orgo Case
* Orgo Task
* artifact references
* gate outcomes
* pinned policies
* canonical refs
* governed feedback
Role split:
* **SenTient** resolves ambiguity and produces explicit resolved structures.
* **Validation** checks whether resolved inputs pass deterministic acceptance criteria.
* **Orgo** enforces stage ordering, gates, audit records, and publication rules.
* **Kristal** compiles validated knowledge into canonical Exchange and derived Runtime Packs.
* **Konnaxion** verifies, activates, and rolls back distributed Runtime Packs fail-closed.
* **Feedback** creates new governed work; it does not mutate canon directly.
## 4. Inputs
This layer receives material from previous layers, especially:
* resolved claims;
* structured knowledge candidates;
* provenance-aware inputs;
* ambiguity reports;
* policy context;
* mandate references;
* validation rules;
* schema references;
* pinned toolchain information;
* prior canonical references;
* proposed changes to existing canon;
* feedback that has been turned into governed work.
Typical input artifacts:
```text
Input Snapshot Set
Claim-IR
Resolved Claim-IR
policy / mandate refs
blueprint refs
candidate artifact refs
```
## 5. Outputs
This layer produces or enables:
* Validation Reports;
* PASS / FAIL gate outcomes;
* structured error codes and categories;
* Build Records;
* Release Records;
* canonical artifact references;
* Kristal Exchange compilation eligibility;
* Runtime Pack compilation eligibility;
* rejection records;
* new governed work for failed, partial, or contested inputs.
Typical output path:
```text
Resolved Claim-IR
→ Validation Report
→ if PASS: Compile via Kristal
→ Kristal Exchange + Runtime Pack
→ Release / Distribution
```
If validation fails:
```text
Resolved Claim-IR
→ Validation Report FAIL
→ no compile
→ Orgo Case / Task for correction, review, or rejection
```
## 6. External vocabulary
Useful external vocabulary for this layer:
* validation gate;
* quality assurance;
* conformance testing;
* evidence governance;
* canon governance;
* truth boundary;
* canonical release;
* schema conformance;
* deterministic validation;
* content-addressed artifact;
* immutable release;
* audit trail;
* change control;
* versioned knowledge base;
* governed feedback loop.
## 7. Core invariants
### 7.1 No compile on fail
If validation fails, Orgo must not compile Exchange or Runtime Pack.
Validation failure blocks compilation, publication, activation, and downstream canonical use.
### 7.2 Fail-closed by default
When validation or verification cannot prove correctness, the system must refuse progression.
A failed or uncertain validation state is not treated as partial truth.
### 7.3 Canon is immutable after publication
Canonical truth artifacts are immutable once published.
Changes produce new versions. They do not mutate the existing canonical artifact in place.
### 7.4 Feedback does not mutate canon directly
Feedback creates new governed work.
It may trigger new Cases, Tasks, validations, builds, or releases, but it does not directly rewrite canon.
### 7.5 Determinism is required at the gate
Given the same pinned inputs, policies, configurations, and toolchain versions, validation must produce the same gate outcome and stable error categories.
### 7.6 Canonical truth depends on typed artifacts
Canon is not implicit state.
kOA boundaries exchange typed artifacts and references, not hidden memory or informal assumptions.
### 7.7 kOA does not redefine Kristal contracts
Kristal-owned artifact formats and schemas remain defined by the pinned Kristal dependency.
This layer describes kOA’s use of validation and canon boundaries; it does not restate Kristal schemas, canonicalization rules, hashing rules, or signature rules.
## 8. Failure mode if absent
Without this layer:
* proposals become “truth” too easily;
* summaries replace validated knowledge;
* feedback silently rewrites canon;
* generated outputs can introduce unsupported facts;
* failed validation may still leak downstream;
* conflicting versions become indistinguishable;
* decisions cannot be audited;
* downstream action may execute on untrusted knowledge;
* rollback and investigation become unreliable;
* communities lose the ability to contest what became official.
The result is epistemic drift: the system appears to know, but cannot prove how it knows.
## 9. Relation to other layers
### Previous layer: Layer 04 — Structured Knowledge
Layer 04 turns sources, claims, evidence, and context into structured knowledge candidates.
Layer 05 decides whether those candidates may become validated, canonical, or eligible for compilation.
### Next layer: Layer 06 — Deliberation
Layer 06 can use validated knowledge as a shared substrate for structured discussion.
Deliberation should know whether it is discussing:
* proposed knowledge;
* validated knowledge;
* canonical knowledge;
* contested knowledge;
* failed or rejected knowledge.
### Later layers
Layer 07 — Decision / Legitimacy depends on this layer so that decisions can distinguish evidence from unsupported opinion.
Layer 08 — Execution depends on this layer so that tasks do not operate on unvalidated canon.
Layer 09 — Memory / Learning depends on this layer so that lessons learned become governed updates rather than uncontrolled mutation.
## 10. Layer boundary
This layer is the boundary between:
```text
structured but not yet canonical
```
and:
```text
validated, versioned, traceable, canon-eligible
```
It is also the boundary between:
```text
feedback as social input
```
and:
```text
feedback as governed work
```
## 11. Minimal example
A community submits a set of claims about a civic issue.
1. Sources are ingested with provenance.
2. Claims are extracted.
3. SenTient resolves ambiguity where possible.
4. Validation checks consistency, provenance, schema conformance, policy requirements, and deterministic criteria.
5. If validation passes, Kristal may compile the validated material into canonical artifacts.
6. If validation fails, Orgo records the failure and creates governed work for correction, review, or rejection.
At no point does a comment, vote, AI summary, or feedback event directly mutate canon.
## 12. One-sentence definition
Validation / Canon is the layer where structured knowledge is tested, gated, versioned, and made eligible for canonical use without allowing hidden mutation, unverifiable truth, or downstream drift.
================================================================================================
FILE: docs_layer-model/layers/06_deliberation.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 1aa3dae5957cd82ce7be7efd97d736ecdacf30f2daef5ef38dae8d0d73ff0338
CONTENT_BYTES: 11617
================================================================================================
# Layer 06 — Deliberation
**Status:** Conceptual layer definition
**Normative for kOA:** NO
**External normative reference:** None
---
## 1. Function
The Deliberation layer transforms contributions, disagreements, questions, proposals, evidence, and perspectives into a structured process that can be examined, compared, revised, and prepared for decision.
Its role is not to decide.
Its role is to make collective reasoning visible.
This layer exists so that public input does not remain scattered as comments, posts, reactions, informal conversations, or isolated opinions. It gives disagreement a form that can be worked with.
Deliberation is the passage between structured knowledge and legitimate decision.
```text
Structured knowledge
→ arguments
→ objections
→ alternatives
→ amendments
→ convergence / divergence
→ decision-ready material
````
---
## 2. Core question
This layer answers:
```text
How do we turn many voices, claims, disagreements, and proposals into a structured public reasoning process?
```
Secondary questions:
```text
What is being discussed?
Who is affected?
What evidence is being used?
Where do participants agree?
Where do they disagree?
Which objections remain unresolved?
Which alternatives are available?
What is ready for decision?
```
---
## 3. Internal kOA components
Relevant internal components may include:
```text
Konnaxion
ethiKos
Korum
Assemblies
Kristals
EkoH
Smart Vote
Archives
Inquisiteur
```
### Konnaxion
Konnaxion can serve as the public coordination and contribution surface where people, projects, learning resources, civic tools, and deliberative processes become discoverable and connected.
Within the broader kOA architecture, Konnaxion is not only a place to publish material. It is a coordination surface for connecting people, questions, projects, knowledge artifacts, and public processes.
### ethiKos
ethiKos is the deliberation and public decision pipeline.
It structures public reasoning around:
```text
questions
claims
evidence
arguments
objections
counterarguments
amendments
proposals
decision records
follow-up
```
ethiKos is not a raw discussion forum.
It exists to make deliberation auditable, readable, and reusable.
### Korum
Korum can host high-level public debates, structured claims, counters, source-linked positions, and issue-based discussion.
Its purpose is to bring public questions into a structured environment where reasoning can be traced.
### Assemblies
Assemblies are the collective legitimacy bodies that may receive deliberative outputs and transform them into decisions, mandates, or further work.
### Inquisiteur
The Inquisiteur is the integrity safeguard.
In this layer, the Inquisiteur protects against manipulation, humiliation, fabricated evidence, confusion between fact and fiction, abuse of vulnerability, and personality capture.
---
## 4. Inputs
The Deliberation layer receives material from previous layers.
Typical inputs include:
```text
structured knowledge artifacts
Kristals
claims
evidence notes
source summaries
problem statements
mandates
questions
public submissions
expert contributions
lived experience
stakeholder concerns
draft proposals
objections
constraints
uncertainties
```
From Layer 04 — Structured Knowledge:
```text
reusable knowledge artifacts
validated claims
evidence packages
contextualized references
```
From Layer 05 — Validation / Canon:
```text
validated or bounded material
known uncertainty
canon references
validation status
constraints
```
The Deliberation layer should preserve the distinction between:
```text
validated knowledge
unverified claims
opinion
interpretation
proposal
objection
decision
```
---
## 5. Outputs
The Deliberation layer produces decision-ready material.
Typical outputs include:
```text
structured deliberation records
argument maps
objection lists
amendment proposals
consensus / dissensus maps
stakeholder summaries
decision memos
consultation reports
decision-ready options
unresolved questions
recommended next steps
new Kristal candidates
Orgo work requests
Archive entries
```
The output should make clear:
```text
what was discussed
what evidence was used
who contributed
which options emerged
where agreement exists
where disagreement remains
which objections are unresolved
what can move to decision
what must return to knowledge work
```
Deliberation may produce material for:
```text
Layer 07 — Decision / Legitimacy
Layer 08 — Execution
Layer 09 — Memory / Learning
Layer 04 — Structured Knowledge, if new knowledge artifacts must be created
```
---
## 6. External vocabulary
Comparable external vocabulary:
```text
deliberative democracy
public deliberation
public participation
civic engagement
structured consultation
participatory governance
argument mapping
issue mapping
stakeholder consultation
consensus mapping
sensemaking
public reasoning
collaborative governance
civic intelligence
```
Useful external phrases:
```text
structured public reasoning
decision-preparation process
deliberative infrastructure
public input pipeline
civic reasoning layer
participation-to-decision bridge
```
Possible external framing:
```text
The Deliberation layer is kOA's civic reasoning infrastructure.
It turns public input, evidence, disagreement, and proposals into structured material that can support legitimate decisions.
```
---
## 7. Failure mode if absent
If the Deliberation layer is absent, several failures occur.
### 7.1 Discussion remains noise
Public input remains trapped in:
```text
comment threads
social media posts
unstructured meetings
private conversations
informal influence
status games
```
No shared reasoning object is produced.
### 7.2 Popularity replaces reasoning
Without structured deliberation, visibility can be confused with legitimacy.
The loudest, most connected, most emotional, or most institutionally powerful voices can dominate the process.
### 7.3 Expertise and lived experience fail to meet
Experts may speak in one channel.
Affected people may speak in another.
Institutions may consult separately.
The Deliberation layer exists to let these perspectives become comparable without collapsing them into one undifferentiated crowd.
### 7.4 Decisions lack traceability
If deliberation is not structured, later decisions cannot clearly answer:
```text
Why was this option chosen?
What alternatives were considered?
What objections were raised?
What evidence mattered?
What tradeoffs were accepted?
Who is responsible for follow-up?
```
### 7.5 Memory cannot form
Unstructured deliberation is difficult to archive, learn from, or reuse.
Without this layer, each consultation or debate risks being lost as temporary activity rather than becoming institutional memory.
---
## 8. Relation to other layers
### Previous layer
The Deliberation layer receives material from:
```text
Layer 04 — Structured Knowledge
Layer 05 — Validation / Canon
```
It depends on those layers because deliberation requires usable material:
```text
claims
evidence
context
definitions
constraints
validation status
uncertainty
```
Without structured knowledge and validation, deliberation becomes unstable.
### Next layer
The Deliberation layer feeds:
```text
Layer 07 — Decision / Legitimacy
```
It prepares options, arguments, objections, and decision records so that decision-making can be transparent, contestable, and multi-readable.
### Feedback paths
Deliberation can also send material backward.
If new claims, contradictions, uncertainties, or evidence gaps emerge, they should return to:
```text
Layer 03 — Provenance / Ingestion
Layer 04 — Structured Knowledge
Layer 05 — Validation / Canon
```
Deliberation can also send action requests forward to:
```text
Layer 08 — Execution
```
when a discussion creates tasks, reviews, investigations, or follow-up work.
---
## 9. One-sentence definition
Deliberation is the layer where collective input, evidence, disagreement, and proposals become structured public reasoning that can support legitimate decision-making.
---
## 10. Compact definition
```text
Deliberation turns many voices into a structured reasoning process.
```
---
## 11. Layer formula
```text
Knowledge + disagreement + public input
→ structured arguments
→ mapped objections
→ revised options
→ decision-ready material
```
---
## 12. Boundary rule
Deliberation must not silently become decision.
The Deliberation layer prepares choices.
It does not finalize legitimacy by itself.
Final decision, weighting, mandate, or authority belongs to:
```text
Layer 07 — Decision / Legitimacy
```
Likewise, deliberation must not mutate canon directly.
If new knowledge emerges, it must return through the appropriate validation path.
---
## 13. Internal / external translation
| Internal kOA term | External vocabulary |
| ----------------- | --------------------------------------------------------- |
| ethiKos | deliberation and public decision pipeline |
| Konnaxion | public coordination platform |
| Korum | structured public debate space |
| Assemblies | participatory governance bodies |
| Inquisiteur | integrity safeguard / ethics and evidence review function |
| Kristals | reusable knowledge artifacts |
| EkoH | domain-bounded trust and expertise weighting |
| Smart Vote | transparent decision-support lens |
---
## 14. Practical examples
### Example 1 — Public issue
A community wants to discuss a local housing issue.
The Deliberation layer structures:
```text
problem statement
stakeholders
evidence
arguments
objections
constraints
possible interventions
unresolved questions
decision-ready options
```
The output is not just a comment thread.
It is a structured deliberation record.
### Example 2 — Course governance
UCKK participants propose changes to a learning pathway.
The Deliberation layer structures:
```text
proposal
reasoning
evidence from participant experience
pedagogical concerns
alternative versions
agreement / disagreement
recommended revision
```
The output can then move to decision, validation, or further design.
### Example 3 — Civic technology
A public consultation receives thousands of inputs.
The Deliberation layer helps transform them into:
```text
themes
argument clusters
stakeholder concerns
evidence gaps
major tensions
possible amendments
decision-ready summaries
```
This prevents public participation from becoming symbolic activity without follow-through.
---
## 15. Design principle
Deliberation should make reasoning more visible, not make people less human.
The layer must preserve:
```text
dignity
context
minority positions
uncertainty
disagreement
traceability
contestability
```
It must avoid:
```text
manipulation
humiliation
manufactured consensus
false neutrality
opaque weighting
erasure of dissent
```
---
## 16. Summary
The Deliberation layer is the civic reasoning layer of kOA.
It receives structured knowledge and validated material, opens them to collective reasoning, preserves disagreement, organizes arguments, prepares options, and produces decision-ready records.
It protects the passage from knowledge to decision.
Without it, kOA would risk becoming either a knowledge repository with no public reasoning, or a decision system without visible deliberation.
================================================================================================
FILE: docs_layer-model/layers/07_decision_legitimacy.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 110f1e6b300f02939800160921c7e260b57d39091a54c0a30744a494570dcd5c
CONTENT_BYTES: 10667
================================================================================================
# Layer 07 — Decision / Legitimacy
**File:** `layer-model/layers/07_decision_legitimacy.md`
**Status:** Conceptual layer definition
**Normative for kOA:** NO
**External normative reference:** None
---
## 1. Function
The Decision / Legitimacy layer turns deliberation outputs into visible, comparable, contestable choices.
Its function is not simply to count votes. Its function is to make decision-making more legible:
- what options exist;
- what criteria matter;
- what tradeoffs are visible;
- what forms of support exist;
- where expertise and public preference align;
- where they diverge;
- what thresholds or constraints apply;
- how a decision was finalized;
- what record must be preserved for future accountability.
This layer raises decision quality without reallocating decision rights.
---
## 2. Core question
How do we choose without hiding power inside a single opaque score?
Secondary questions:
- What are the available options?
- What are the relevant criteria?
- What do different groups support?
- What does the raw baseline show?
- What does the advisory competence-weighted lens show?
- What ethical, risk, or safety constraints apply?
- Where do readings converge or diverge?
- What decision rule is being used?
- Can the result be audited, contested, and revised?
---
## 3. Internal kOA components
Core components:
- EkoH
- Smart Vote
- ethiKos decision stage
- Konnaxion decision surfaces
- decision records
- raw vote
- weighted reading
- domain-bounded expertise signals
- ethical reliability signals
- stakeholder lenses
- risk thresholds
- decision rules
- dissent records
- legitimacy traces
Related components:
- Kristals
- Korum
- Konsultations
- Architect-Strategy
- Orgo
- Archives
---
## 4. Inputs
This layer receives:
- deliberation outputs;
- options;
- proposals;
- arguments;
- objections;
- criteria;
- thresholds;
- public input;
- expert input;
- stakeholder input;
- domain-specific evidence;
- risk constraints;
- ethical constraints;
- relevant Kristals;
- consultation results;
- draft decisions.
---
## 5. Outputs
This layer produces:
- decision surfaces;
- comparable readings;
- raw support results;
- advisory weighted results;
- stakeholder-specific readings;
- risk-constrained readings;
- legitimacy signals;
- selected options;
- decision records;
- justification summaries;
- dissent documentation;
- decision rules;
- handoff material for execution;
- memory-ready decision artifacts.
---
## 6. External vocabulary
Comparable external terms:
- decision support;
- participatory decision-making;
- deliberative decision process;
- legitimacy layer;
- advisory weighting;
- multi-criteria decision support;
- stakeholder-weighted analysis;
- domain-bounded credibility signals;
- algorithmic accountability;
- transparent decision record;
- public-interest decision infrastructure.
Avoid framing this layer as:
- expert rule;
- technocracy;
- popularity ranking;
- AI decision-making;
- social credit;
- universal merit score;
- hidden algorithmic authority.
---
## 7. Design principle
The core design principle is:
> Raise decision quality without reallocating decision rights.
This means:
- the public baseline remains visible;
- competence signals are advisory;
- ethical reliability can inform weighting;
- expertise is domain-bounded;
- weightings must be visible and contestable;
- the system shows multiple readings instead of producing one hidden answer.
The system does not say:
> Experts decide.
It says:
> Here is what the raw baseline shows.
> Here is what a domain-bounded competence lens shows.
> Here is what risk or ethical constraints show.
> Here is where the readings agree or diverge.
---
## 8. Multiple readings
Smart Vote should preserve multiple readings rather than collapse all judgment into one final number.
Common readings include:
1. **Baseline reading**
One-person-one-vote or unweighted support.
2. **Advisory competence-weighted reading**
Support interpreted through domain-bounded EkoH signals.
3. **Ethical reliability reading**
Support adjusted or qualified by integrity, transparency, conflict-of-interest, or conduct signals.
4. **Risk-constrained reading**
Options failing safety, legal, operational, or ethical thresholds are flagged.
5. **Stakeholder reading**
Views filtered by affected group, region, role, domain, or other governed criteria.
6. **Dissent reading**
Objections, minority positions, and unresolved concerns are preserved.
The purpose of multiple readings is not to fragment legitimacy. It is to make legitimacy visible from several principled angles.
---
## 9. EkoH role
EkoH provides domain-bounded credibility and reliability signals.
It should be understood as a situated advisory layer, not a universal ranking of persons.
EkoH may consider signals such as:
- demonstrated domain expertise;
- relevant contribution history;
- ethical reliability;
- transparency;
- peer recognition;
- practical impact;
- knowledge transfer;
- conflict-of-interest signals;
- time decay;
- domain relevance.
EkoH must remain:
- domain-bounded;
- explainable;
- contestable;
- auditable;
- revisable;
- non-sovereign.
EkoH must not become:
- a global human value score;
- a social credit system;
- a hidden authority;
- a substitute for deliberation;
- a substitute for democratic legitimacy.
---
## 10. Smart Vote role
Smart Vote uses EkoH and other governed signals to produce transparent decision readings.
Its role is to show how support changes under different principled lenses.
Smart Vote should:
- keep the raw baseline visible;
- display weighted readings separately;
- explain which criteria were applied;
- expose coefficients, thresholds, or rules where appropriate;
- preserve dissent;
- flag divergence between readings;
- support investigation of why readings differ;
- produce decision records that can be audited later.
Smart Vote should not:
- hide the decision logic;
- replace human judgment;
- override governance rules;
- erase minority views;
- present weighted output as unquestionable truth;
- turn a complex decision into a magic number.
---
## 11. Decision surface
Before a decision is finalized, this layer should produce a decision surface.
A decision surface makes the choice legible.
It may include:
- list of options;
- scenario comparison;
- expected outcomes;
- known constraints;
- legal constraints;
- cost and timeline estimates;
- distributional impacts;
- risk zones;
- uncertainty zones;
- affected stakeholders;
- relevant Kristals;
- decision criteria;
- threshold rules;
- visible objections;
- unresolved issues.
The decision surface transforms deliberation into a structured choice.
---
## 12. Decision finalization
A decision is not just a vote.
A decision is a governed transition from deliberation to execution.
A finalized decision should include:
- selected option;
- decision rule used;
- raw support result;
- advisory weighted result;
- applicable risk or ethical constraints;
- justification summary;
- source-linked evidence;
- dissent record;
- unresolved objections;
- responsible body or role;
- execution handoff;
- memory record.
This output feeds Layer 08 — Execution.
---
## 13. Failure mode if absent
If this layer is absent, several failures occur.
### Popularity collapse
Decisions collapse into raw popularity, virality, charisma, or mobilization capacity.
### Technocratic capture
Expertise may dominate without public legitimacy or contestability.
### Opaque algorithmic authority
A hidden score or recommendation may decide without people understanding why.
### Legitimacy gap
Participants cannot see how input became a decision.
### Expertise invisibility
People with relevant knowledge are drowned out by noise, status, or volume.
### No handoff
Decisions remain symbolic because they are not structured for execution.
### No memory
Future participants cannot inspect why a decision was made.
---
## 14. Relation to other layers
### Previous layer
Layer 06 — Deliberation produces:
- arguments;
- objections;
- proposals;
- synthesis;
- options;
- public input;
- decision-ready material.
Layer 07 receives this material and converts it into structured choice.
### Next layer
Layer 08 — Execution receives:
- selected decision;
- decision record;
- responsibilities;
- constraints;
- dissent notes;
- execution handoff.
Layer 08 then turns the decision into tasks, workflows, follow-up, closure, and operational memory.
### Memory loop
Layer 09 — Memory / Learning preserves:
- decision record;
- readings shown;
- criteria used;
- dissent;
- execution result;
- later evaluation.
This allows future decisions to improve.
---
## 15. Boundaries
This layer does not define:
- exact EkoH scoring formulas;
- Smart Vote implementation details;
- database schemas;
- UI components;
- legal voting rules;
- constitutional authority;
- public accreditation;
- binding civic authority.
Those belong in technical, governance, legal, or implementation documents.
This layer defines the conceptual role:
> making collective choice legible, auditable, contestable, and legitimate.
---
## 16. Minimal requirements
A decision-legitimacy process should minimally preserve:
- raw baseline result;
- applied decision rule;
- visible criteria;
- source-linked justification;
- dissent record;
- contestability path;
- execution handoff;
- memory record.
If any of these are missing, the decision may become opaque, fragile, or unaccountable.
---
## 17. One-sentence definition
Decision / Legitimacy is the layer that makes collective choices visible, comparable, contestable, and legitimate before they become action.
---
## 18. Short reusable definition
Layer 07 turns deliberation into decision.
It preserves the raw democratic baseline while adding transparent advisory readings such as domain-bounded competence, ethical reliability, stakeholder perspective, and risk constraints.
Its purpose is to raise decision quality without hiding authority or replacing human judgment.
---
## 19. Summary
The Decision / Legitimacy layer protects the passage between public reasoning and collective action.
It ensures that decisions are not merely popular, expert-driven, algorithmic, or opaque.
Instead, decisions should be:
- legible;
- plural-readable;
- source-linked;
- contestable;
- auditable;
- ethically bounded;
- ready for execution;
- preserved for memory.
In short:
> kOA does not ask communities to trust a black box. It shows the readings, the rules, the evidence, the disagreements, and the handoff to action.
================================================================================================
FILE: docs_layer-model/layers/08_execution.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 544d5b950b01d186b7dcde4de7a6b2767486802eeddc7f326663cac45134521d
CONTENT_BYTES: 10497
================================================================================================
# Layer 08 — Execution
**File:** `layer-model/layers/08_execution.md`
**Status:** Conceptual orientation
**Normative for kOA:** NO
**External normative references:** None
---
## 1. Function
The Execution layer transforms decisions, plans, signals, or orientations into governed work.
It is the layer where a choice stops being only a deliberative or decision output and becomes:
- tasks;
- roles;
- responsibilities;
- workflows;
- deadlines;
- dependencies;
- escalation paths;
- progress evidence;
- closure;
- telemetry;
- operational memory.
In kOA, execution is not treated as an afterthought. It is a first-class layer because a decision without follow-through remains incomplete.
---
## 2. Core Question
**How does a decision become real work that can be assigned, followed, audited, completed, and remembered?**
Secondary questions:
- Who is responsible?
- What must be done?
- By when?
- Under which constraints?
- What dependencies exist?
- What happens if the work is blocked?
- How is progress proven?
- When is the action complete?
- What must be preserved for memory?
---
## 3. Internal kOA Components
Primary components:
- **Orgo**
- **Orgo Cases**
- **Orgo Tasks**
- **Architect-Strategy**
- **SwarmCraft**
- **Build Records**
- **Release Records**
- **Operational logs**
- **Telemetry**
- **Konnaxion feedback capture**
- **Memory / Archives**
Related components:
- **Smart Vote**
- **EkoH**
- **ethiKos**
- **Kristal**
- **Runtime Packs**
- **Malkuth**
---
## 4. Primary kOA Role
The primary execution component is **Orgo**.
Orgo is the execution, continuity, and operational memory layer. It transforms decisions, signals, or orientations into tasks, responsibilities, escalations, follow-up, closure, and verifiable traces.
In the kOA Digital Ecosystem, Orgo functions as the control-plane layer that enforces stage ordering, gates, audit records, and release workflows.
---
## 5. Inputs
The Execution layer receives governed intent from earlier layers.
Typical inputs include:
- decision records;
- approved orientations;
- validated plans;
- mandate constraints;
- policy constraints;
- Smart Vote / EkoH decision readings;
- ethiKos deliberation outputs;
- Architect-Strategy plans;
- Kristal references;
- Runtime Pack references;
- user or institutional goals;
- operational context;
- incidents;
- feedback requiring action.
Execution should not receive vague intention alone. It should receive enough structure to produce governed work.
---
## 6. Outputs
The Execution layer produces operational artifacts and evidence.
Typical outputs include:
- Orgo Cases;
- Orgo Tasks;
- assigned responsibilities;
- task status;
- deadlines;
- dependencies;
- escalation records;
- progress evidence;
- execution telemetry;
- completion records;
- closure records;
- incident records;
- implementation outputs;
- feedback for future governed work;
- memory-ready operational records.
Outputs from execution feed the Memory / Learning layer.
---
## 7. Minimal Action Requirements
Every kOA-grade action should have:
- a responsible person, group, agent, or role;
- a status;
- a deadline or review date;
- a priority;
- an origin decision or mandate;
- dependencies;
- evidence of progress;
- closure criteria;
- a memory destination.
Without these elements, the action is not fully governable.
---
## 8. Minimal Execution States
A minimal execution lifecycle may include:
```text
signal_received
→ triaged
→ assigned
→ in_progress
→ blocked
→ escalated
→ completed
→ closed
→ archived
→ reviewed
````
These states may be adapted by implementation, but the conceptual requirement remains:
> execution must be trackable from origin to closure and memory.
---
## 9. External Vocabulary
The Execution layer can be explained with external terms such as:
| kOA Term | External Vocabulary |
| --------------- | ---------------------------------------- |
| Orgo | operational governance layer |
| Orgo Case | case management container |
| Orgo Task | governed unit of work |
| Execution layer | workflow management / task orchestration |
| Escalation | exception handling / escalation pathway |
| Closure | completion gate / lifecycle closure |
| Telemetry | operational observability |
| Logs | audit records / operational trace |
| Responsibility | accountability assignment |
| Follow-up | implementation tracking |
Useful external fields:
* workflow management;
* case management;
* operational governance;
* project execution;
* service delivery;
* process management;
* accountability systems;
* incident response;
* auditability;
* organizational learning.
---
## 10. Boundaries
The Execution layer does not decide what is true.
It does not create canonical truth artifacts.
It does not replace deliberation.
It does not replace decision legitimacy.
It does not mutate canon directly.
Its role is to execute governed work and produce operational evidence.
### Execution may:
* create tasks;
* route work;
* assign responsibilities;
* track progress;
* escalate blockers;
* emit telemetry;
* produce outputs;
* close work;
* trigger feedback into governed processes.
### Execution must not:
* silently change validated knowledge;
* rewrite the canon;
* treat a plan as truth;
* hide responsibility;
* bypass validation gates;
* erase blockers or failures;
* convert AI suggestions into action without governance;
* execute work with no trace.
---
## 11. Relation to Previous Layer
The previous layer is:
```text
Layer 07 — Decision / Legitimacy
```
That layer produces visible, contestable, multi-readable choices.
Execution receives those choices and asks:
> What concrete work now follows from this decision?
The transition is:
```text
decision
→ implementation plan
→ cases
→ tasks
→ responsible actors
→ tracked progress
→ closure
```
A decision without execution remains incomplete.
---
## 12. Relation to Next Layer
The next layer is:
```text
Layer 09 — Memory / Learning
```
Execution produces the operational traces that memory requires.
The transition is:
```text
tasks
→ status changes
→ blockers
→ outputs
→ completion records
→ post-mortems
→ reusable memory
```
Without execution records, memory becomes vague.
Without memory, execution does not improve the system.
---
## 13. Failure Mode If Absent
If the Execution layer is absent, the system remains performative.
Symptoms:
* decisions are announced but not implemented;
* discussions do not produce follow-through;
* responsibility remains vague;
* blockers disappear into private messages;
* deadlines drift;
* failures are not visible;
* learning is lost;
* communities repeatedly restart from zero;
* power returns to informal actors who control implementation behind the scenes.
Without execution, collective intelligence does not become collective capacity.
---
## 14. Governance Risks
Execution is a powerful layer because it controls what actually happens.
Risks include:
* hidden implementation drift;
* informal capture by operators;
* unlogged side effects;
* unreviewed escalation;
* sensitive information exposure;
* execution without consent or mandate;
* responsibility laundering;
* AI-driven action without human governance;
* task closure without real completion;
* private operational systems overriding public decisions.
The layer must therefore preserve:
* traceability;
* privacy boundaries;
* responsibility;
* auditability;
* escalation visibility;
* governed closure;
* feedback into memory.
---
## 15. Privacy and Transparency
The Execution layer must distinguish between public accountability and protected operational detail.
Public-facing execution may show:
* decision origin;
* responsible role or body;
* current status;
* milestones;
* non-sensitive blockers;
* completion state;
* review date;
* public outcomes.
Protected execution may include:
* personal information;
* sensitive internal details;
* security details;
* medical, social, disciplinary, or private context;
* protected identities;
* internal operational notes.
Rule:
> Transparency of power. Protection of persons.
---
## 16. AI in the Execution Layer
AI may assist execution by:
* summarizing work;
* detecting dependencies;
* suggesting task decomposition;
* identifying blockers;
* drafting follow-up messages;
* preparing reports;
* routing routine signals;
* comparing status with plans.
AI must not secretly govern execution.
AI must not be solely responsible for:
* assigning authority;
* closing critical tasks;
* changing critical status;
* escalating disciplinary processes;
* erasing uncertainty;
* bypassing review;
* executing sensitive actions without authorization.
Principle:
> AI may assist execution. It must not secretly own execution.
---
## 17. Layer Pattern
The Execution layer follows this pattern:
```text
governed decision or plan
→ case
→ task
→ assignment
→ execution
→ telemetry
→ blocker / escalation / completion
→ closure
→ memory
```
Expanded:
```text
Decision Record
→ Orgo Case
→ Orgo Tasks
→ Responsible actors
→ Work execution
→ Logs and telemetry
→ Status changes
→ Closure criteria
→ Operational memory
```
---
## 18. Example
A community decides to launch a local repair initiative.
Layer 07 produces:
* decision record;
* reasons;
* criteria;
* vote readings;
* dissent;
* responsibilities of execution;
* review date.
Layer 08 turns that into:
* one Orgo Case: `local_repair_initiative`;
* tasks for venue, tools, volunteers, safety, communication, budget;
* deadlines;
* assigned roles;
* dependencies;
* escalation path if venue or budget fails;
* progress logs;
* completion criteria;
* final operational report.
Layer 09 then preserves:
* what worked;
* what failed;
* reusable templates;
* revised assumptions;
* updated Kristals;
* memory for the next initiative.
---
## 19. One-Sentence Definition
**Execution is the layer where decisions become governed work: tasks, responsibilities, workflows, follow-up, closure, and operational memory.**
---
## 20. Short Definition
Execution turns choice into coordinated, traceable action.
---
## 21. Ultra-Short Formula
```text
Decision → Tasks → Responsibility → Follow-through → Closure → Memory
```
================================================================================================
FILE: docs_layer-model/layers/09_memory_learning.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: bdac49397597ed842b41abb8208f8cf86ecb76f7a3ce40d4ea4304b1e2fb05c6
CONTENT_BYTES: 8855
================================================================================================
# Layer 09 — Memory / Learning
**File:** `layer-model/layers/09_memory_learning.md`
**Status:** Conceptual layer definition
**Normative for kOA:** NO
**External normative references:** None
---
## 1. One-Sentence Definition
> Memory / Learning is the layer where actions, outcomes, errors, feedback, and traces become structured memory that can improve the next cycle of collective action.
---
## 2. Core Function
This layer transforms experience into reusable collective capacity.
In kOA, memory is not passive storage. It is the function that allows a group to:
- understand what happened;
- recover why decisions were made;
- inspect whether actions matched intentions;
- identify errors, blockers, and partial successes;
- preserve lessons learned;
- reuse validated knowledge;
- improve future decisions, workflows, courses, and collective practices.
Memory / Learning closes the loop between action and the next cycle of knowing.
It ensures that:
```text
Action → Trace → Feedback → Learning → Updated capacity
````
Without this layer, the system would act without accumulating wisdom.
---
## 3. Core Question
> What must be preserved from experience so the group can understand, correct, improve, and transmit what happened?
---
## 4. Position in the Stack
```text
Execution → Memory / Learning → Resilience / Autonomy
```
Layer 09 receives traces, outcomes, errors, and feedback from Layer 08 — Execution.
It produces structured memory that can feed:
* Layer 02 — Semantics / Meaning;
* Layer 04 — Structured Knowledge;
* Layer 05 — Validation / Canon;
* Layer 06 — Deliberation;
* Layer 08 — Execution;
* Layer 11 — Learning / Interface.
Memory also supports Layer 10 — Resilience / Autonomy by preserving what is needed for recovery, rollback, audit, and future continuity.
---
## 5. Inputs
This layer receives:
* decisions;
* reasons for decisions;
* Orgo tasks;
* task states;
* responsibilities;
* execution logs;
* blockers;
* errors;
* escalations;
* completed work;
* partial results;
* failed attempts;
* telemetry;
* participant feedback;
* deliberation outcomes;
* action results;
* review notes;
* post-mortems;
* validation outcomes;
* release records;
* rollback records;
* updated evidence;
* reusable lessons;
* learning artifacts;
* participant reflections.
---
## 6. Outputs
This layer produces:
* memory records;
* learning records;
* post-mortem summaries;
* reusable lessons;
* feedback signals;
* updated issue maps;
* improved task patterns;
* new Orgo cases or tasks;
* candidate knowledge updates;
* candidate Kristal updates;
* course improvements;
* governance recommendations;
* audit trails;
* participant learning evidence;
* institutional memory;
* archive entries;
* future-cycle inputs.
Outputs from this layer do **not** automatically mutate canon.
When memory produces a candidate knowledge update, that update must re-enter the appropriate governed pipeline: provenance, structured knowledge, validation, and canon.
---
## 7. Internal kOA Components
Relevant kOA components include:
* **Archives**;
* **Kristals**;
* **Orgo**;
* **Konnaxion**;
* **SemantiK Architect**;
* **SenTient**;
* **Build Records**;
* **Release Records**;
* **Rollback Records**;
* **Konnaxion State**;
* **feedback signals**;
* **Orgo Cases**;
* **Orgo Tasks**;
* **UCKK learning records**;
* **Assemblées**, when collective review is required.
---
## 8. External Vocabulary
Comparable external vocabulary includes:
* institutional memory;
* organizational learning;
* knowledge management;
* lessons learned;
* after-action review;
* feedback loop;
* audit trail;
* learning record;
* retrospective;
* post-mortem;
* continuous improvement;
* evidence-based improvement;
* decision memory;
* operational memory;
* reflective practice.
---
## 9. Comparable Frameworks or Standards
This layer partially overlaps with:
* organizational learning;
* knowledge management;
* after-action review practices;
* post-mortem practices in engineering and operations;
* continuous improvement loops;
* learning organizations;
* audit and accountability systems;
* decision records;
* incident review processes;
* competency-based learning portfolios.
It also relates to the kOA technical pipeline, where observation and feedback are part of the stage spine and where feedback creates governed work rather than silently mutating truth.
This layer is not equivalent to any one framework. Its specific role in kOA is to connect action, audit, learning, knowledge renewal, and future collective capacity.
---
## 10. Failure Mode if Absent
If this layer is absent:
* actions disappear after execution;
* groups repeat the same mistakes;
* decisions cannot be reconstructed;
* responsibilities become unclear;
* blockers are forgotten;
* lessons stay informal or private;
* knowledge does not improve through use;
* participants cannot learn from prior cycles;
* trust weakens because promises cannot be compared with outcomes;
* the system becomes performative rather than cumulative;
* collective intelligence fails to become collective memory.
Without Memory / Learning, kOA would still be able to act, but it would not become wiser.
---
## 11. Boundary Rules
This layer does **not**:
* create canonical truth by itself;
* mutate Kristals directly;
* bypass validation;
* replace provenance;
* decide legitimacy;
* execute tasks;
* hide failures;
* erase ambiguity;
* turn feedback into canon without review;
* replace human interpretation;
* replace Assemblées where collective review is needed.
Memory records may initiate new work, but they do not automatically settle truth.
A feedback signal can open an Orgo Case or Task.
A lesson can become a candidate update.
A candidate update must still pass through governed validation before becoming canonical.
---
## 12. Relationship to Other Layers
* Receives execution traces from **Layer 08 — Execution**.
* Preserves reasons and decision context from **Layer 07 — Decision / Legitimacy**.
* Feeds new evidence or corrections back toward **Layer 03 — Provenance / Ingestion**.
* Produces candidate knowledge updates for **Layer 04 — Structured Knowledge**.
* Sends validated updates toward **Layer 05 — Validation / Canon**.
* Provides material for future deliberation in **Layer 06 — Deliberation**.
* Supports rollback, recovery, and continuity in **Layer 10 — Resilience / Autonomy**.
* Supplies learning artifacts to **Layer 11 — Learning / Interface**.
* Gives narrative material to **Layer 12 — Narrative / Adoption**, without allowing narrative to replace evidence.
---
## 13. Example
A community uses ethiKos to deliberate about a local problem.
Smart Vote and EkoH help make different readings of the decision visible.
Orgo turns the chosen direction into tasks, roles, responsibilities, and follow-up.
After execution, the Memory / Learning layer preserves:
* what was decided;
* why it was decided;
* who was responsible;
* what actions were completed;
* what failed;
* what was blocked;
* what evidence changed;
* what participants learned;
* what should be reused;
* what should be revised next time.
The result is not just an archive.
It becomes material for the next cycle:
```text
Remember → Know better → Choose better → Act better
```
---
## 14. Partner-Relevant Translation
For civic tech partners:
> This layer turns public decisions and implementation outcomes into inspectable civic memory.
For data governance partners:
> This layer extends data governance into decision memory and learning records.
For education partners:
> This layer lets participants produce evidence of learning through reflection, artifacts, feedback, and improved practice.
For funders and social innovation partners:
> This layer makes impact learning cumulative instead of anecdotal.
For technical partners:
> This layer captures feedback, telemetry, release outcomes, and operational traces without allowing downstream systems to mutate canonical truth.
---
## 15. Minimal Definition for Index
> Memory / Learning turns actions, outcomes, errors, feedback, and traces into structured memory that improves future cycles of collective action.
---
## 16. Open Questions
* What is the minimal memory record required after each action cycle?
* Which memories should remain operational, educational, public, private, or archival?
* How should feedback be routed into Orgo Cases or Tasks?
* When does a lesson become a candidate Kristal update?
* Which memories require Assembly review?
* How should participant learning records connect to UCKK progression?
* What should be forgotten, expired, anonymized, or protected?
* How should narrative memory remain distinct from evidentiary memory?
* Which indicators show that memory is improving future action?
================================================================================================
FILE: docs_layer-model/layers/10_resilience_autonomy.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: f37587ef697758f4a0d0fe6951db840fa8d2419043f11190b0f554075b3b4856
CONTENT_BYTES: 10693
================================================================================================
# Layer 10 — Resilience / Autonomy
**Layer ID:** 10
**Layer name:** Resilience / Autonomy
**Status:** Conceptual orientation layer
**Normative for kOA Digital Ecosystem:** No
**External normative reference:** None
---
## 1. Function
This layer protects the ability of kOA-based communities, institutions, and systems to keep operating under constraint.
It ensures that knowledge, decisions, workflows, and memory are not dependent on fragile centralized platforms, constant cloud access, unverifiable updates, or opaque authorities.
Resilience / Autonomy is the layer where kOA turns knowledge infrastructure into survivable civic infrastructure.
It emphasizes:
- offline-capable operation;
- local continuity;
- deterministic behavior;
- fail-closed integrity;
- auditability;
- rollback;
- portability;
- duplication;
- controlled synchronization;
- trusted activation;
- reduced dependency on centralized infrastructure.
This layer does not replace the technical specifications for determinism, rollback, key management, trust roots, Runtime Packs, or Kristal conformance. Those remain in the technical documentation.
---
## 2. Core Question
Can the system continue to operate safely, verifiably, and locally when connectivity, trust, infrastructure, or institutions fail?
---
## 3. Internal kOA Components
Relevant internal components include:
| Component | Resilience / Autonomy role |
|---|---|
| `Runtime Pack` | Portable offline distribution unit |
| `Konnaxion` | Verifies, activates, distributes, rolls back Runtime Packs |
| `Malkuth` | Offline runtime substrate serving active packs read-only |
| `Kristal` | Canonical knowledge substrate compiled into portable artifacts |
| `Orgo` | Enforces workflow gates, audit records, and controlled change |
| `Build Record` | Captures reproducible build evidence |
| `Release Record` | Captures distribution and activation intent/outcomes |
| `Archives` | Preserve long-term memory and continuity |
| `Kristal Farms` | Physical/local compute infrastructure for sovereignty and locality |
| `Trust roots / keys` | Support verification, activation, revocation, and tenant boundaries |
---
## 4. Inputs
This layer receives:
- validated Kristal Exchanges;
- Runtime Packs;
- manifests;
- signatures;
- hashes;
- trust roots;
- tenant policies;
- compatibility declarations;
- Build Records;
- Release Records;
- activation records;
- rollback records;
- telemetry;
- archive records;
- local deployment constraints;
- offline operation requirements;
- incident reports.
---
## 5. Outputs
This layer produces or enables:
- verified active Runtime Packs;
- offline-readable knowledge packages;
- deterministic local query behavior;
- last-known-good rollback states;
- activation records;
- rollback records;
- audit trails;
- continuity under constrained conditions;
- local autonomy over critical knowledge services;
- reduced dependency on external platforms;
- evidence of integrity, provenance, and operational control.
---
## 6. External Vocabulary
Comparable external vocabulary includes:
- resilience engineering;
- local-first software;
- offline-first systems;
- cyber-resilience;
- disaster continuity;
- operational continuity;
- sovereign infrastructure;
- fail-closed security;
- deterministic systems;
- reproducible builds;
- signed artifacts;
- content-addressed distribution;
- rollback strategy;
- edge verification;
- local compute;
- distributed infrastructure;
- data portability;
- system survivability;
- infrastructure autonomy.
---
## 7. Failure Mode if Absent
If this layer is absent, kOA becomes fragile.
Possible failures include:
- communities cannot operate without internet access;
- knowledge remains locked inside centralized platforms;
- unverified artifacts may be activated;
- corrupted updates may overwrite working states;
- systems may fail open instead of refusing unsafe changes;
- rollback may be impossible or unreliable;
- trust becomes dependent on “trust us” rather than inspection;
- AI-generated or downstream outputs may become impossible to reproduce;
- canonical truth may be mutated under pressure;
- local institutions lose continuity during crisis;
- private or sensitive workflows become dependent on external infrastructure;
- communities cannot preserve autonomy over critical knowledge and decision systems.
Without this layer, kOA risks becoming another platform dependency instead of an infrastructure for collective sovereignty.
---
## 8. Design Principles
### 8.1 Offline-capable by design
Critical knowledge and workflows should be usable in constrained environments.
A community should be able to operate in a closed loop when needed:
- local data;
- local compute;
- local continuity;
- local access to validated knowledge;
- local query of active Runtime Packs.
Offline capability is not a convenience. It is a sovereignty requirement.
---
### 8.2 Fail-closed integrity
A governable system must refuse unsafe activation.
If integrity, compatibility, schema validation, signature verification, trust roots, required files, or policy checks fail, the system should not activate the artifact.
Failure should be explicit, deterministic, and auditable.
The safer default is:
```text
if verification fails:
do not activate
remain on current or last-known-good state
emit deterministic reason
````
---
### 8.3 Deterministic-first behavior
Critical transformations should be reproducible.
Given the same pinned inputs, pinned configuration, pinned policies, and pinned resources, the system should produce the same output or the same explicit refusal.
AI may assist, summarize, draft, or propose, but core truth and activation paths must remain governed by reproducible artifacts and deterministic gates.
---
### 8.4 Auditability as civic infrastructure
Resilience requires inspection.
A resilient system must allow authorized parties to trace:
```text
source
→ claim
→ validation
→ compilation
→ distribution
→ activation
→ rendering
→ execution
→ feedback
```
If transformations cannot be traced, the system cannot be governed.
---
### 8.5 Portability over platform lock-in
Knowledge should be packaged so it can move.
Runtime Packs and related artifacts allow validated knowledge to be carried into:
* local institutions;
* community hubs;
* offline networks;
* emergency environments;
* low-connectivity regions;
* closed or regulated settings;
* independent deployments.
Portability reduces domination through infrastructure dependency.
---
### 8.6 Rollback before panic patching
When activation breaks consumers or fails verification, the system should prefer controlled rollback to known-good states over ad hoc patching.
Rollback must be:
* deterministic;
* auditable;
* tied to records;
* compatible with tenant boundaries;
* protected against unauthorized downgrade.
---
### 8.7 Local autonomy with controlled synchronization
Autonomy does not mean isolation.
Local deployments should be able to:
* operate independently;
* preserve local continuity;
* synchronize when appropriate;
* share validated outputs selectively;
* keep private or sensitive data under local control;
* participate in broader knowledge commons without surrendering autonomy.
---
## 9. Relation to Other Layers
### Previous layers
Layer 10 depends on the outputs of earlier layers:
* **Layer 03 — Provenance / Ingestion**
supplies traceable sources and snapshots.
* **Layer 04 — Structured Knowledge**
supplies portable knowledge artifacts.
* **Layer 05 — Validation / Canon**
ensures only validated artifacts become canonical.
* **Layer 08 — Execution**
supplies operational traces, tasks, and telemetry.
* **Layer 09 — Memory / Learning**
supplies archives, post-mortems, lessons, and updated knowledge.
### Following layers
Layer 10 supports later layers:
* **Layer 11 — Learning / Interface**
by allowing UCKK, interfaces, and learning pathways to operate with durable local access.
* **Layer 12 — Narrative / Adoption**
by making the system credible as infrastructure rather than symbolic rhetoric.
* **Layer 13 — Deployment / Translation**
by enabling partner-facing claims around portability, offline readiness, public trust, and autonomy.
---
## 10. Technical Reference Points
This layer is conceptual. Technical details are defined elsewhere.
Relevant technical documentation includes:
```text
../../technical-docs/10-system/architecture.md
../../technical-docs/10-system/determinism.md
../../technical-docs/10-system/failure-modes.md
../../technical-docs/10-system/trust-boundaries.md
../../technical-docs/20-nodes/chesed-konnaxion.md
../../technical-docs/20-nodes/malkuth-runtime.md
../../technical-docs/30-artifacts/build-record.md
../../technical-docs/30-artifacts/release-record.md
../../technical-docs/40-integration/kristal-v4/
../../technical-docs/50-operations/rollback.md
../../technical-docs/50-operations/incident-response.md
../../technical-docs/50-operations/key-management.md
```
This layer should not restate:
* Kristal schemas;
* Runtime Pack manifest fields;
* signature formats;
* canonicalization rules;
* exact rollback algorithms;
* trust-root mechanics;
* key-management procedures.
Those remain in the technical documentation and pinned dependencies.
---
## 11. Resilience Pattern
The core resilience pattern is:
```text
validated knowledge
→ portable package
→ fail-closed verification
→ atomic activation
→ offline use
→ telemetry
→ governed feedback
→ reproducible rebuild
→ deterministic rollback if needed
```
This pattern keeps the system usable without turning fragility into authority.
---
## 12. Autonomy Pattern
The core autonomy pattern is:
```text
local copy
+ local runtime
+ local policies
+ local continuity
+ controlled synchronization
+ auditable links to broader commons
```
Autonomy means the community can keep operating without surrendering control of its knowledge, decisions, or memory.
---
## 13. Boundary Rule
Resilience / Autonomy must not become an excuse for hidden mutation.
Offline or local operation does not permit:
* silent canon changes;
* bypassing validation;
* activating unverifiable artifacts;
* editing canonical truth under incident pressure;
* collapsing tenant boundaries;
* replacing audit with trust;
* using AI outputs as canonical truth without validation.
Local autonomy must remain governed autonomy.
---
## 14. One-Sentence Definition
Resilience / Autonomy is the layer that allows kOA to keep knowledge, decisions, execution, and memory usable, verifiable, portable, and locally controllable under constraint.
================================================================================================
FILE: docs_layer-model/layers/11_learning_interface.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: b791d9ec27db0d2cadf7b74dfabca20f1ade2b6ff914c6b45a958054717f477e
CONTENT_BYTES: 9324
================================================================================================
# Layer 11 — Learning / Interface
**Layer status:** Conceptual layer
**Normative for kOA:** NO
**Primary canonical anchor:** `UCKK_Canon/00_index.md`
**Related technical anchor:** `technical-docs/00-overview/`, `technical-docs/60-guides/`
---
## 1. Function
The Learning / Interface layer makes the kOA architecture teachable, navigable, usable, and adoptable by humans.
It translates the internal system into learning paths, courses, exercises, guides, interfaces, roles, portfolios, and participant-facing artifacts.
This layer answers the question:
> How do people learn to understand, use, critique, and reproduce the kOA system?
The Learning / Interface layer does not define the technical contracts of the kOA Digital Ecosystem. It does not replace the canon, the runtime pipeline, Orgo execution, Kristal validation, or Assembly governance. It provides the human-facing learning surface through which people enter, practice, and internalize the system.
In the broader kOA architecture, this layer is primarily embodied by **UCKK — Univers-Cité King Klown**, the educational branch of the movement.
---
## 2. Core question
How can the system become understandable and usable by people who are not already experts in its architecture?
Sub-questions:
- How do participants learn the core cycle?
- How do they understand the Grand Social Game?
- How do they learn to read systems?
- How do they use kOA tools without confusing the tools with the whole movement?
- How do they produce evidence, artifacts, projects, and learning traces?
- How do they progress through learning paths?
- How is competence demonstrated without false accreditation?
- How does learning become contribution?
---
## 3. Internal kOA components
Relevant internal components:
- **UCKK / Univers-Cité King Klown**
- learning paths
- Voies
- Paliers
- Parchemins UCKK
- tronc commun
- course guides
- narrated slide videos
- exercises
- participant artifacts
- dossiers de preuves
- Assemblées
- Inquisiteur
- Archives
- Konnaxion profiles / portfolios
- kOA Digital Ecosystem as object of study
- kOA Digital Ecosystem as infrastructure for practice
Related internal concepts:
- Grand Jeu social
- joueur lucide
- bâtisseur
- archiviste
- cartographe de systèmes
- systems literacy
- responsible AI use
- evidence production
- deliberation practice
- action planning
- memory and feedback
---
## 4. Inputs
The Learning / Interface layer receives:
- the kOA canon;
- the kOA Digital Ecosystem documentation;
- layer definitions;
- course outlines;
- learning objectives;
- participant needs;
- exercises;
- examples;
- case studies;
- workflows;
- system diagrams;
- interface mockups;
- public challenges;
- prior participant work;
- feedback from learners;
- evidence of competence;
- artifacts produced in other layers.
It also receives outputs from earlier layers:
- structured knowledge from Layer 04;
- validated material from Layer 05;
- deliberation patterns from Layer 06;
- decision examples from Layer 07;
- execution traces from Layer 08;
- memory records from Layer 09.
---
## 5. Outputs
This layer produces human-facing learning and adoption artifacts.
Outputs include:
- learning paths;
- course manuals / learning guides;
- narrated slide videos;
- exercises;
- rubrics;
- participant assignments;
- system maps;
- portfolios;
- dossiers de preuves;
- internal recognitions;
- Parchemins UCKK;
- course completion records;
- onboarding guides;
- interface explanations;
- glossary entries;
- diagrams;
- feedback records;
- updated learning material;
- participant-generated knowledge artifacts.
The outputs of this layer should help participants move from passive understanding to active use.
---
## 6. External vocabulary
Comparable external terms:
- learning ecosystem;
- capacity-building layer;
- systems literacy;
- civic education;
- public pedagogy;
- competency-based education;
- portfolio-based assessment;
- micro-credentialing;
- learning pathway;
- curriculum architecture;
- knowledge transfer;
- user onboarding;
- interface layer;
- adoption layer;
- communities of practice;
- train-the-trainer model;
- learning management system;
- human-computer interaction;
- educational interface;
- experiential learning.
Useful public-facing translation:
> This is the layer where kOA becomes learnable: courses, guides, exercises, interfaces, portfolios, and pathways that help people understand systems and act with lucidity.
---
## 7. Failure mode if absent
If this layer is absent, the kOA system may still exist technically, but it remains inaccessible to most people.
Common failure modes:
- the system remains understandable only to its creator or technical experts;
- participants cannot find a clear entry point;
- the architecture appears too abstract or overwhelming;
- tools are used without understanding their purpose;
- people confuse kOA, UCKK, Konnaxion, King Klown, and the Digital Ecosystem;
- learning does not become practice;
- competence is not documented;
- participant contributions disappear;
- adoption depends on charisma instead of method;
- the system cannot be reproduced, taught, or decentralized.
Without this layer, kOA risks becoming a powerful architecture without a transmission mechanism.
---
## 8. Relation to other layers
### Previous layer
**Layer 10 — Resilience / Autonomy**
Layer 10 protects continuity, portability, offline use, and non-dependence.
Layer 11 translates that protected system into usable learning pathways. Resilience makes the system durable; Learning / Interface makes it inhabitable.
### Next layer
**Layer 12 — Narrative / Adoption**
Layer 11 teaches the system through structured learning.
Layer 12 makes the system memorable, emotionally accessible, publicly visible, and narratively transmissible.
### Upstream dependencies
This layer depends on:
```text
Orientation / Mandate
→ Semantics
→ Provenance
→ Structured Knowledge
→ Validation
→ Deliberation
→ Decision
→ Execution
→ Memory
→ Resilience
````
The learning layer should not invent content independently of these upstream layers. It should translate and teach them.
### Downstream influence
This layer feeds:
* public adoption;
* participant competence;
* future contributors;
* facilitators;
* builders;
* archivists;
* course improvements;
* UCKK progression;
* community replication.
---
## 9. Layer boundary
This layer teaches, exposes, translates, and interfaces with the system.
It does not:
* create formal state accreditation;
* replace public universities or professional orders;
* redefine Kristal contracts;
* override Orgo execution gates;
* decide official truth;
* replace Assemblies;
* replace the Inquisiteur’s integrity function;
* turn symbolic recognition into public legal credentials;
* collapse narrative, learning, and governance into one authority.
UCKK recognitions, Paliers, and Parchemins must remain internal unless future external recognition is explicitly granted.
---
## 10. Learning pattern
The Learning / Interface layer adapts the core kOA cycle into a pedagogical method:
```text
Know the game
→ Choose a move
→ Act with method
→ Remember what was learned
→ Play better
```
This means that learning is not only content consumption. It is structured practice.
A learner should progressively become able to:
1. read a system;
2. identify visible and invisible rules;
3. distinguish claims, evidence, assumptions, and uncertainty;
4. use AI responsibly as an analytical tool;
5. participate in structured deliberation;
6. produce reusable artifacts;
7. turn insight into action;
8. document what happened;
9. improve the next cycle.
---
## 11. Interface pattern
This layer also defines how humans encounter the system.
Interfaces may include:
* course pages;
* navigation maps;
* knowledge dashboards;
* participant portfolios;
* challenge pages;
* Assembly interfaces;
* Konnaxion profiles;
* evidence folders;
* visual explanations;
* course videos;
* diagrams;
* glossary-driven navigation.
The interface should reduce cognitive overload without hiding complexity.
Good interface behavior:
* clarify where the user is;
* show what layer is active;
* explain what input is expected;
* show what output will be produced;
* preserve links to evidence;
* separate learning, deliberation, execution, and memory;
* make the next action clear.
---
## 12. Integrity requirements
Because this layer works with learning, progression, identity, and recognition, it must preserve trust.
Integrity requirements:
* distinguish internal recognition from public accreditation;
* keep fiction and fact separate;
* make course criteria explicit;
* make participant progress auditable;
* document evidence for recognition;
* avoid manipulation or coercive pedagogy;
* avoid cult-of-personality dynamics;
* preserve participant dignity;
* allow critique of the system;
* route integrity concerns to the Inquisiteur or relevant Assembly.
---
## 13. One-sentence definition
**Learning / Interface is the layer where kOA becomes teachable and usable: it turns the architecture into courses, guides, interfaces, exercises, portfolios, and learning pathways that help people understand systems, practice collective capacity, and transmit the method.**
================================================================================================
FILE: docs_layer-model/layers/12_narrative_adoption.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: a8f9b09170d1a1c588f4b3f87278dcab351ccb6a0787ac930c98bd0ae54d386d
CONTENT_BYTES: 15268
================================================================================================
# Layer 12 — Narrative / Adoption
**Layer:** 12
**Name:** Narrative / Adoption
**Status:** Conceptual layer definition
**Normative for kOA:** NO
**External normative reference:** None
**Technical scope:** Orientation layer only. This file does not define schemas, artifact contracts, runtime behavior, validation gates, governance procedures, or institutional authority.
---
## 1. Function
The Narrative / Adoption layer makes the kOA architecture publicly legible, memorable, and socially transmissible.
Its function is to translate complex structures into forms people can notice, understand, remember, discuss, and enter.
This layer may use:
- public pedagogy;
- story;
- metaphor;
- symbolic figures;
- theater;
- humor;
- satire;
- challenge formats;
- social media;
- music;
- visual motifs;
- scenes;
- fictional or semi-fictional scenarios;
- public-facing explanations.
The layer does not replace the architecture.
It does not create truth.
It does not validate claims.
It does not govern UCKK.
It does not override the Inquisitor, Assemblies, Archives, canon, or technical documentation.
Its role is adoption through intelligibility.
---
## 2. Core question
> How can a complex architecture become understandable, memorable, inviting, and transmissible without becoming misleading, manipulative, or sovereign?
Secondary questions:
- What narrative form helps people enter the system?
- What metaphor makes the architecture easier to grasp?
- What public scene turns an abstract concept into a learning event?
- What challenge activates participation?
- What must be clarified afterward?
- What must be archived?
- What must remain clearly fictional, symbolic, or pedagogical?
---
## 3. Position in the layer stack
The Narrative / Adoption layer sits after learning/interface and before deployment/translation.
```text
Layer 11 — Learning / Interface
↓
Layer 12 — Narrative / Adoption
↓
Layer 13 — Deployment / Translation
````
It also loops backward into earlier layers:
```text
Narrative attracts attention
→ learning gives structure
→ deliberation gives collective form
→ execution gives consequence
→ memory preserves what happened
```
Narrative should open a path into the system, not trap attention around itself.
---
## 4. Internal kOA components
Relevant internal components and concepts include:
* King Klown
* Kin City
* UCKK public theater
* Défis de King Klown
* responsible public pedagogy
* fiction pédagogique
* surréalité opératoire
* public scenes
* social media as pedagogical stage
* narrative challenges
* symbolic interfaces
* public-facing explainers
* mythos
* songs
* videos
* staged formats
* public archives
* Inquisitor oversight
* Assemblies
* Archives
King Klown is the most visible figure of this layer, but the layer is broader than King Klown alone.
---
## 5. Inputs
Typical inputs include:
* complex kOA concepts;
* UCKK lessons;
* social issues;
* public controversies;
* institutional absurdities;
* civic problems;
* technical mechanisms;
* course material;
* deliberation outputs;
* unresolved tensions;
* examples from the Grand Social Game;
* partner-facing explanations;
* participant contributions;
* archived lessons;
* public events;
* cultural material.
Examples:
```text
A technical concept becomes a visual metaphor.
A social mechanism becomes a public challenge.
A governance rule becomes a staged scene.
A course idea becomes a short video.
A contradiction in society becomes a King Klown intervention.
A complex process becomes a map, story, or performance.
```
---
## 6. Outputs
This layer produces public-facing forms such as:
* stories;
* scenes;
* videos;
* songs;
* challenges;
* contests;
* public prompts;
* short explainers;
* symbolic maps;
* narrative guides;
* Kin City spaces;
* public lessons;
* social media sequences;
* calls to builders;
* invitations to assemblies;
* archived contributions;
* partner-facing narrative bridges.
Example output:
```text
Concept:
"Decision legitimacy requires more than raw popularity."
Narrative form:
A public scene where several groups vote on the same issue, then King Klown reveals how different readings produce different meanings.
Clarifying return:
A short document explains raw vote, expert reading, stakeholder reading, and ethical safeguards.
Archive:
The challenge, responses, explanation, and corrections are preserved.
```
---
## 7. External vocabulary
Useful external language for this layer:
| kOA language | External vocabulary |
| -------------------------- | ------------------------------------------------- |
| Narrative / Adoption | adoption layer |
| King Klown | narrative interface / public pedagogy vehicle |
| Kin City | spatial interface / symbolic learning environment |
| Défis | participatory learning challenges |
| théâtre public responsable | responsible public pedagogy |
| fiction pédagogique | pedagogical fiction |
| surréalité opératoire | symbolic scenario-based learning |
| scène publique | public engagement format |
| mythos | narrative framework |
| adoption | public uptake / cultural transmission |
| archives publiques | public memory / learning record |
Recommended external terms:
* public pedagogy;
* narrative change;
* civic imagination;
* symbolic interface;
* adoption layer;
* public engagement;
* learning activation;
* sensemaking;
* cultural transmission;
* participatory storytelling;
* social movement communication;
* narrative infrastructure.
---
## 8. Boundaries
This layer is responsible for public intelligibility and adoption.
It is not responsible for:
* defining truth;
* certifying knowledge;
* validating facts;
* replacing deliberation;
* replacing Assemblies;
* replacing the Inquisitor;
* replacing technical documentation;
* governing UCKK;
* creating false partner support;
* presenting fiction as fact;
* making unsupported claims;
* manipulating vulnerable people;
* manufacturing legitimacy through spectacle.
Boundary rule:
> Narrative may open the door, but it must always return to clarity, method, evidence, and memory.
---
## 9. Operational principles
### 9.1 Narrative must illuminate
Narrative may surprise, provoke, amuse, dramatize, or enchant.
But it must clarify.
```text
Good:
A scene makes a hidden social rule visible.
Bad:
A spectacle gathers attention without helping people understand the system.
```
### 9.2 Fiction must remain distinguishable from fact
Pedagogical fiction is allowed.
Confusion is not.
```text
Allowed:
"This scene is fictional but illustrates a real governance problem."
Not allowed:
Presenting fictional support, fictional events, or fictional institutional recognition as real.
```
### 9.3 Narrative is not authority
A narrative figure can translate a system.
It cannot become the source of validity.
```text
King Klown can reveal the game.
King Klown cannot replace evidence, Assemblies, the Inquisitor, Archives, or technical documentation.
```
### 9.4 Adoption must lead to participation
Attention should move toward:
* learning;
* questions;
* challenges;
* courses;
* contribution;
* deliberation;
* projects;
* archives;
* partner engagement.
If attention does not lead anywhere, the layer is failing.
### 9.5 Humor must not humiliate
Humor, satire, and provocation may expose absurdity.
They must not rely on:
* degradation;
* harassment;
* intimidation;
* targeted cruelty;
* abuse of vulnerability;
* manipulation;
* cult of personality.
### 9.6 Public scenes must return to traceable outputs
A public event should produce something that can be reviewed:
* explanation;
* challenge record;
* participant work;
* correction;
* archive;
* lesson;
* assembly note;
* project artifact.
### 9.7 Narrative must remain subordinate to the architecture
The architecture defines the system.
Narrative helps people enter it.
```text
Narrative serves kOA.
Narrative does not become kOA.
```
---
## 10. Failure mode if absent
If this layer is missing, the system may:
* remain too abstract;
* appear inaccessible;
* be understood only by experts;
* fail to attract participants;
* fail to become memorable;
* fail to reach public imagination;
* fail to transform attention into learning;
* fail to transmit across communities;
* remain trapped in documentation;
* appear cold, technical, or bureaucratic;
* lose adoption despite strong internal coherence.
Core failure:
> Without the Narrative / Adoption layer, the system may be correct but socially unreadable.
---
## 11. Failure mode if overgrown
If this layer becomes too strong or poorly bounded, the system may:
* appear manipulative;
* appear cult-like;
* replace clarity with spectacle;
* let personality override procedure;
* let fiction blur into fact;
* let popularity replace legitimacy;
* let viral attention replace learning;
* let symbolic authority replace evidence;
* make partners distrust the architecture;
* weaken the credibility of the technical and educational layers.
Core failure:
> If narrative becomes sovereign, it damages the system it was meant to translate.
---
## 12. Relation to other layers
### Previous layer: Layer 11 — Learning / Interface
Learning gives participants a structured way to understand the system.
Narrative gives people a reason to enter.
```text
Layer 11 teaches.
Layer 12 attracts, translates, and activates.
```
### Next layer: Layer 13 — Deployment / Translation
Deployment turns the architecture toward partners, pilots, institutions, communities, and public use.
Narrative helps create entry points, but deployment must use accurate, partner-specific language.
### Upstream relation: Layer 02 — Semantics / Meaning
Narrative uses symbols and metaphors.
Semantics prevents those symbols from becoming confusing or misleading.
### Upstream relation: Layer 05 — Validation / Canon
Narrative may produce examples, questions, or contributions.
Only validation/canon can stabilize knowledge.
### Upstream relation: Layer 06 — Deliberation
Narrative may open discussion.
Deliberation structures disagreement.
### Upstream relation: Layer 09 — Memory / Learning
Narrative events should leave records.
Archives prevent spectacle from disappearing without learning.
---
## 13. King Klown as narrative interface
King Klown belongs to this layer.
King Klown is:
* a public pedagogy figure;
* a narrative interface;
* a mobilization persona;
* a challenge launcher;
* a symbolic guide into the Grand Social Game.
King Klown is not:
* a guru;
* a sovereign;
* an absolute authority;
* a replacement for proof;
* a replacement for UCKK governance;
* a replacement for kOA Digital Ecosystem documentation;
* a source of truth beyond review.
Operational formula:
```text
King Klown attracts.
The Inquisitor verifies.
The Assemblies legitimize.
The Builders realize.
The Archivist preserves memory.
```
---
## 14. Example: attention to learning
Narrative input:
```text
A King Klown video exposes how a social platform ranks content.
```
Narrative action:
```text
The video dramatizes how visibility can shape legitimacy.
```
Required return path:
```text
1. Short explanation of ranking systems
2. Exercise in mapping platform incentives
3. Optional UCKK lesson
4. Public challenge
5. Archive of best participant analyses
```
Layer 12 succeeds if attention becomes learning.
---
## 15. Example: learning to challenge
Narrative input:
```text
A public challenge asks participants to map an invisible rule in their school, workplace, city, or platform.
```
Adoption path:
```text
attention → participation → evidence → reflection → contribution → archive
```
Layer 12 succeeds if the challenge produces artifacts that can be remembered, discussed, or used.
---
## 16. Example: fiction and clarity
Narrative input:
```text
A fictional Kin City scene shows citizens walking through different civic systems as buildings, gates, archives, courts, workshops, and assemblies.
```
Required distinction:
```text
Kin City is symbolic.
The civic mechanisms it represents must be explained separately.
```
External wording:
```text
Kin City is a symbolic interface and pedagogical map, not the system of record.
```
---
## 17. Relation to social media
Social media can be used as a pedagogical stage.
Allowed uses:
* mini-lessons;
* public challenges;
* corrections;
* system maps;
* short explanations;
* calls to builders;
* invitations to assemblies;
* public archives;
* King Klown appearances;
* Inquisitor interventions.
But social media must not govern the system.
Rules:
```text
Virality must not replace truth.
Engagement must not replace learning.
Popularity must not replace legitimate decision.
Spectacle must not replace memory.
```
---
## 18. Editorial constraints
The narrative tone should combine:
```text
lucidity
humor
responsibility
proof
imagination
accessibility
dignity
action
memory
```
Preferred tone:
* vivid;
* clear;
* playful;
* demanding;
* generous;
* non-cynical;
* non-humiliating;
* non-manipulative.
Avoid:
* messianic tone;
* opacity;
* threats;
* arrogance;
* sectarian framing;
* defamation;
* confusion;
* unsupported claims;
* excessive esotericism without explanation;
* institutional dryness without life.
---
## 19. Design constraint
The Narrative / Adoption layer must support the kOA architecture without replacing its technical, educational, ethical, or institutional layers.
It may define:
* public-facing metaphors;
* narrative roles;
* adoption pathways;
* examples;
* boundaries;
* tone;
* failure modes;
* responsible theatrical uses;
* relation to learning, archives, and assemblies.
It must not define:
* truth criteria;
* artifact schemas;
* Kristal contracts;
* Orgo workflow contracts;
* Smart Vote formulas;
* EkoH scoring rules;
* formal institutional authority;
* official accreditation;
* partner commitments;
* factual claims without evidence.
---
## 20. Minimal validation checklist
A narrative/adoption artifact is minimally valid when it can answer:
* What concept does this narrative clarify?
* What public entry point does it create?
* What is fictional, symbolic, or theatrical?
* What is factual?
* What learning path does it point toward?
* What action or challenge does it activate?
* What record or archive will preserve the output?
* Are participants protected from manipulation or humiliation?
* Can the Inquisitor question or suspend it?
* Can the Assemblies review its public effects?
* Does it return to documentation, method, evidence, or memory?
---
## 21. One-sentence definition
The Narrative / Adoption layer is where kOA turns complex architecture into public-facing stories, scenes, challenges, symbols, and interfaces that attract attention, support learning, activate participation, and return people to evidence, action, and memory.
================================================================================================
FILE: docs_layer-model/layers/13_deployment_translation.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 1ca0ea008b8e0486a18c14b0a8a6ce74f48cdac5ba196d3b73ee7504060af8f1
CONTENT_BYTES: 14475
================================================================================================
# Layer 13 — Deployment / Translation
## 1. Function
The Deployment / Translation layer converts the kOA layer model into forms that external people, partners, communities, institutions, funders, developers, educators, and public audiences can understand and act on.
Its function is not to redefine the system.
Its function is to translate the system.
This layer turns the internal architecture into:
- partner-specific explanations;
- pilot-ready scopes;
- public narratives;
- institutional language;
- adoption pathways;
- documentation packages;
- audience-specific entry points;
- strategic asks;
- external vocabulary mappings;
- deployment plans.
This layer exists because kOA is multi-layered by design. Different audiences should not be forced to understand the full architecture at once.
A partner concerned with civic technology may enter through **ethiKos**, auditability, public decision records, and data governance.
A partner concerned with education may enter through **UCKK**, systems literacy, learning pathways, and competency recognition.
A partner concerned with infrastructure may enter through **Kristal**, Runtime Packs, offline behavior, and traceability.
A public audience may enter through **King Klown**, challenges, narrative, theater, and cultural pedagogy.
Deployment / Translation is the layer that decides which door to open first.
## 2. Core question
> How should the kOA architecture be translated for this audience, context, partner, pilot, or deployment path without distorting the system?
Secondary questions:
- Which layer is most relevant to this audience?
- Which internal terms need external vocabulary?
- Which claims are safe to make at this stage?
- Which parts should remain in the background?
- What is the appropriate ask?
- What proof or artifact should be shown?
- What limits must be stated clearly?
- What should not be confused?
## 3. Internal kOA components
Relevant internal components:
- **kOA** — movement, vision, principles, strategy;
- **UCKK** — educational and capacity-building branch;
- **kOA Digital Ecosystem** — operable digital infrastructure;
- **Konnaxion** — public coordination and contribution platform;
- **Kristal** — structured, verifiable, reusable knowledge artifact;
- **ethiKos** — deliberation and public decision pipeline;
- **EkoH** — domain-bounded trust, expertise, ethics and credibility weighting;
- **Smart Vote** — transparent decision-support and multiple decision readings;
- **Orgo** — execution, tasks, responsibilities, escalation and operational memory;
- **Archives** — memory, conservation, trace and reuse;
- **King Klown** — narrative interface and public pedagogy vehicle;
- **Inquisiteur** — integrity safeguard and methodological check;
- **Assemblées** — collective legitimacy;
- **Bâtisseurs** — passage from learning or decision into real projects.
## 4. Inputs
This layer receives material from the full system.
Typical inputs include:
- layer model;
- glossary;
- canon excerpts;
- technical documentation;
- course materials;
- public essays;
- codebase summaries;
- module status;
- partner requirements;
- pilot goals;
- funding criteria;
- audience profile;
- screenshots or demos;
- evidence of existing assets;
- risk notes;
- ethical limits;
- legal or institutional constraints;
- public communication needs.
This layer also receives contextual questions such as:
- Is the audience technical?
- Is the audience institutional?
- Is the audience civic?
- Is the audience educational?
- Is the audience artistic?
- Is the audience public-facing?
- Is the goal funding, partnership, adoption, review, validation, or recruitment?
## 5. Outputs
This layer produces translated artifacts.
Primary outputs:
- partner pitch;
- one-page explanation;
- pilot brief;
- application text;
- email outreach;
- presentation outline;
- public landing-page copy;
- technical-to-nontechnical glossary;
- layer-to-partner map;
- proof package outline;
- audience-specific narrative;
- external vocabulary mapping;
- risk and boundary statement;
- adoption pathway;
- deployment roadmap.
Examples:
- **Ashoka translation**
- kOA as collective-capacity infrastructure;
- UCKK as first pilot-ready learning branch;
- focus on systems change and changemaker capacity.
- **Innoweave translation**
- UCKK Pilot 01 as a measurable learning pathway;
- focus on theory of change, intended impact, learning outcomes and replication.
- **Open North translation**
- ethiKos / Konnaxion as civic decision infrastructure;
- focus on data governance, deliberation, auditability, public trust and responsible AI.
- **District 3 translation**
- kOA / Konnaxion as social-tech infrastructure entering pilot deployment;
- focus on product clarity, user pathway, MVP and adoption.
- **Public translation**
- King Klown as narrative interface;
- focus on making complex systems visible, memorable and actionable.
## 6. External vocabulary
Comparable external vocabulary:
- deployment strategy;
- adoption pathway;
- ecosystem building;
- field building;
- partner alignment;
- stakeholder translation;
- implementation strategy;
- public communication;
- narrative change;
- public pedagogy;
- technology transfer;
- knowledge mobilization;
- capacity-building strategy;
- pilot-to-scale pathway;
- theory of change communication;
- civic innovation translation;
- sociotechnical adoption.
Useful framing:
> Deployment / Translation is the layer that turns kOA from internal architecture into appropriate external entry points.
Or:
> It is the layer that selects the right language, proof and doorway for each audience.
## 7. Boundary rules
This layer may translate, package, sequence and adapt explanations.
It must not falsify, inflate, erase limits, or change the underlying architecture.
### This layer may
- simplify without distorting;
- choose an entry point;
- map internal terms to external vocabulary;
- create audience-specific explanations;
- prepare partner-specific asks;
- define pilot scopes;
- create public communication;
- decide what to foreground or background;
- identify missing proof;
- state limits clearly;
- create progressive disclosure paths.
### This layer must not
- present incomplete modules as fully deployed;
- present UCKK as an accredited university;
- present King Klown as a sovereign authority;
- present the kOA Digital Ecosystem as all of kOA;
- present kOA as only a platform;
- present symbolic or metaphysical material as mandatory belief;
- hide known risks;
- remove ethical safeguards for rhetorical advantage;
- confuse narrative, fact, fiction, infrastructure and governance;
- overpromise deployment status;
- claim institutional partnerships that do not exist.
## 8. Invariants
### 8.1 Audience-specific entry
Every deployment message should begin from the layer most relevant to the audience.
Examples:
```text
Education audience → UCKK / systems literacy
Civic tech audience → ethiKos / Konnaxion / auditability
Technical audience → Kristal / Orgo / Runtime Packs
Public audience → King Klown / narrative pedagogy
Systems-change audience → kOA / collective capacity
````
### 8.2 No total-system overload
The full kOA architecture should not be presented all at once unless the audience explicitly needs the full map.
A deployment artifact should usually show:
```text
full system map
→ relevant layer
→ concrete pilot or ask
```
Not:
```text
entire metaphysics
+ all modules
+ all partners
+ all future strategies
+ all narratives
```
### 8.3 Internal / external vocabulary pairing
Branded kOA terms should be paired with recognized external vocabulary.
Examples:
```text
Kristal = portable verified knowledge artifact
Orgo = operational governance / workflow layer
ethiKos = deliberation and public decision pipeline
EkoH = domain-bounded trust and expertise weighting
Smart Vote = transparent decision-support lens
UCKK = systems-literacy learning ecosystem
King Klown = narrative interface / public pedagogy vehicle
```
### 8.4 Limits remain visible
Every deployment message must preserve the relevant limits.
Examples:
* UCKK is experimental unless formally accredited.
* King Klown is a narrative interface, not a guru or sovereign.
* AI supports judgment; it does not replace human governance.
* EkoH and Smart Vote provide readings; they do not abolish democratic legitimacy.
* kOA Digital Ecosystem is an infrastructure branch; it is not the total movement.
### 8.5 Proof follows claim
Every external claim should have an available proof category.
Examples:
```text
Claim: course pipeline exists
Proof: sample course, guide, slides, narration, exercises
Claim: code exists
Proof: repository, module summary, demo, screenshots
Claim: canon exists
Proof: canon excerpts, hierarchy, limits, role definitions
Claim: module emerging
Proof: status note, demo, issue list, next milestone
```
### 8.6 Translation is not mutation
External language may change.
The architecture must not.
The role of this layer is to create bridges, not to rewrite the system to please each audience.
## 9. Relation to other layers
### Previous layer
Layer 12 — **Narrative / Adoption**
The narrative layer makes complex architecture visible, memorable and publicly approachable.
It converts:
```text
Architecture → récit
System → scene
Rule → challenge
Attention → learning
Learning → action
```
### This layer
Layer 13 — **Deployment / Translation**
Turns the layer stack into audience-specific explanations, partner pathways, pilot scopes and external vocabulary.
### Downstream use
This layer feeds:
* grant applications;
* partner meetings;
* pilot design;
* public communication;
* landing pages;
* documentation packages;
* onboarding;
* recruitment;
* institutional validation;
* adoption strategy.
Unlike earlier layers, Deployment / Translation is not a runtime stage inside the technical system. It is the system-facing-outward layer.
## 10. Failure mode if absent
Without this layer, kOA remains too large to be understood.
Typical failures:
* partners see only one fragment and misunderstand the whole;
* technical audiences are given narrative material too early;
* public audiences are given technical detail too early;
* funders see complexity instead of a clear pilot;
* incubators assume the project is underdeveloped because it is not packaged;
* narrative elements are mistaken for institutional authority;
* UCKK is mistaken for an accredited university;
* kOA Digital Ecosystem is mistaken for all of kOA;
* Konnaxion is mistaken for another silo platform;
* the public sees names but not functions;
* the architecture appears scattered instead of layered;
* the wrong proof is shown to the wrong audience.
The result is translation failure:
> The system may be real, but the audience cannot find the correct door into it.
## 11. Failure handling
When a deployment artifact fails to land, the response should not be to shrink kOA.
The response should be to identify which translation failed.
Common failures and corrections:
### Failure: “Too complex”
Correction:
* show the layer map;
* identify only the relevant layer;
* provide a one-sentence entry point;
* defer the rest.
### Failure: “Not advanced enough”
Correction:
* distinguish concept, documentation, code, module, course and pilot status;
* show existing assets;
* state the next deployable unit.
### Failure: “Sounds like a school”
Correction:
* explain that UCKK is the educational branch, not the whole system;
* relate it to kOA and the Digital Ecosystem.
### Failure: “Sounds like a platform”
Correction:
* explain that Konnaxion is the coordination layer, not the whole movement;
* show the broader layer model.
### Failure: “Sounds like a cult or guru system”
Correction:
* foreground the Inquisiteur, Assemblées, limits, fiction/fact distinction, anti-manipulation rules, and the non-sovereign role of King Klown.
### Failure: “Too abstract”
Correction:
* present a pilot;
* show a course;
* show a module;
* show an artifact;
* show a user pathway.
## 12. Observability
This layer should track whether translation is working.
Useful signals:
* which audience received which framing;
* which layer was used as entry point;
* what proof was shown;
* what questions came back;
* what was misunderstood;
* what caused resistance;
* which vocabulary worked;
* which vocabulary failed;
* whether the audience understood the hierarchy;
* whether the audience understood the ask;
* whether follow-up occurred;
* whether the next step was clear.
Possible tracking format:
```text
Audience
→ entry layer
→ message used
→ proof shown
→ misunderstanding
→ correction
→ next action
```
## 13. Example entry-point map
```text
Ashoka
→ Layer 13 + Layer 11 + Layer 0
→ collective-capacity infrastructure / systems change / UCKK pilot
Innoweave
→ Layer 11 + Layer 13
→ impact clarity / theory of change / pilot learning pathway
Open North
→ Layer 03 + Layer 04 + Layer 06 + Layer 07
→ data governance / knowledge governance / decision records / auditability
District 3
→ Layer 06 + Layer 07 + Layer 08
→ social-tech product / deployable module / user pathway
Mitacs or CCTT
→ Layer 04 + Layer 06 + Layer 11
→ research-action / learning outcomes / validated artifacts
Public audience
→ Layer 12 + Layer 11
→ narrative pedagogy / Grand Jeu social / learning entry point
Technical implementer
→ Layer 03 + Layer 04 + Layer 05 + Layer 08 + Layer 10
→ provenance / artifacts / validation / execution / resilience
```
## 14. Example flow
```text
1. Identify the audience.
2. Select the relevant entry layer.
3. Translate internal kOA vocabulary into external vocabulary.
4. Select proof appropriate to the audience.
5. State the boundary conditions.
6. Present a concrete ask.
7. Capture feedback and misunderstandings.
8. Update the translation package without mutating the canon.
```
## 15. Layer definition
**Deployment / Translation** is the layer where the kOA architecture is converted into audience-specific language, proof packages, pilot scopes and adoption pathways without changing the underlying system.
## 16. One-sentence definition
Deployment / Translation opens the correct door into kOA for each audience, so the system can be understood, tested, adopted and scaled without being distorted.
================================================================================================
FILE: docs_technical/00-overview/faq.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 2609c453ddc8a89b926a29f7716f65e3d2bc2866f8ed3a68f3ee108f21dc9748
CONTENT_BYTES: 3496
================================================================================================
# FAQ
## What is this documentation set?
This is the **kOA Digital Ecosystem** documentation: how the ecosystem is structured, how its components behave, and how it operates in production.
## What is *not* in this documentation set?
It does **not** re-specify **Kristal** artifact contracts (schemas, canonicalization rules, signature formats, etc.). Those are owned by the **Kristal v4** documentation and schemas.
## Where is the Kristal spec?
See: `docs/40-integration/kristal-v4/` (especially `pinned-dependency.md` and `contract-pointers.md`). This is the single place in the kOA docs that points to the pinned Kristal v4 source-of-truth.
## What is “canonical” vs “informative” here?
- **Canonical for kOA**: ecosystem invariants, operational rules, node responsibilities, and kOA-native artifact contracts (e.g., Orgo Case/Task, Build/Release records).
- **External canonical**: Kristal artifacts and schemas (Exchange, Runtime Pack, Validation Report, etc.).
## Which artifacts are “kOA-native”?
Artifacts owned by kOA components (examples):
- Orgo operational artifacts (Cases, Tasks, Build/Release records)
- Konnaxion operational state/telemetry envelopes (if defined here)
Kristal artifacts remain externally specified.
## How do I know what schemas to validate against?
- For **kOA-native artifacts**, validate against schemas in `docs/30-artifacts/schemas/`.
- For **Kristal artifacts**, validate against the pinned Kristal v4 schemas referenced in `docs/40-integration/kristal-v4/contract-pointers.md`.
## Why is there a hard “no redundancy” rule?
Duplicating normative contracts causes drift. kOA docs stay stable by pointing to Kristal v4 as the source-of-truth, and only documenting kOA’s integration constraints and operational policies.
## Where do I start if I’m implementing?
- `docs/00-overview/system-at-a-glance.md`
- `docs/10-system/architecture.md`
- `docs/60-guides/implementers.md`
- `docs/40-integration/kristal-v4/conformance.md`
## Where do I start if I’m operating?
- `docs/50-operations/pipeline.md`
- `docs/50-operations/releases.md`
- `docs/50-operations/rollback.md`
- `docs/50-operations/incident-response.md`
## How do changes get made safely?
- Changes to **kOA** invariants/interfaces: add/update an ADR under `docs/90-reference/adr/`.
- Changes to **Kristal** contracts: must happen in the pinned Kristal v4 source; then kOA updates its integration profile/conformance docs accordingly.
## What should I do if I find a mismatch between kOA and Kristal?
Treat it as a **kOA integration bug** (not a Kristal contract bug) unless you are also changing the pinned Kristal version. Update:
- `docs/40-integration/kristal-v4/koa-profile.md` (policy/constraints)
- `docs/40-integration/kristal-v4/conformance.md` (tests/acceptance)
- Any impacted kOA ops/guides that reference the integration behavior
## Does kOA require online connectivity to use Kristal artifacts?
No by default. Distribution/activation and runtime use should be compatible with offline-first operation; connectivity is a deployment choice, not a contract requirement.
## What are the core components?
- **Orgo**: workflow/control plane + gating
- **SenTient**: resolution/reconciliation
- **Kristal**: truth pivot + compilation (externally specified)
- **Konnaxion**: distribution/activation + rollback safety
- **Architect**: deterministic rendering (no new facts)
- **SwarmCraft**: execution (optional)
- **EkoH**: ledger/trust mechanisms (if deployed)
================================================================================================
FILE: docs_technical/00-overview/glossary.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 97dc1ea00f423ea41eefa259e2e2ce99a5ab5e1c607c1816d153c8c805735dff
CONTENT_BYTES: 8276
================================================================================================
# Glossary
**Normative for kOA:** YES (terminology usage within kOA docs)
**External normative references:** Kristal v4 (pinned) for Kristal-defined terms; kOA does not restate Kristal contracts
**Purpose:** Define the shared vocabulary used across the kOA Digital Ecosystem docs.
**Rule:** If a term is *normatively defined by Kristal v4*, this glossary **does not restate** the contract— it points to the Kristal source (via the pinned Kristal dependency).
## Conventions
- **Normative (Kristal):** The term’s format/semantics are defined in Kristal v4 docs/schemas.
- **Normative (kOA):** The term is defined by kOA contracts/policies/operations.
- **Informative:** Helpful interpretation only.
---
## Terms (A–Z)
### Activation (kOA)
Atomic switch from one verified Runtime Pack to another on a device/node, with deterministic rollback guarantees.
### Artifact (kOA)
A typed payload crossing a boundary between components (e.g., Case, Task, Build Record, Release Record).
If the artifact is a Kristal artifact (Claim-IR, Exchange, Runtime Pack, Validation Report), see Kristal v4 (pinned).
### Authority Registry (Kristal)
Normative registry of trust roots and acceptance rules for signatures.
See Kristal (pinned): `vendor/kristal/02-schemas/authority-registry.schema.json`.
### Blueprint (kOA)
The pinned bundle of schemas/config/policies that governs a build and makes downstream outputs reproducible.
### Build (kOA)
One governed pipeline run producing outputs (at minimum: Exchange + Runtime Pack), with recorded inputs/config/policies and audit linkage.
### Build Record (kOA)
Operational evidence of a build: inputs, pinned blueprint, policy selections, component identities, outputs, and gate results.
### Canonicalization (Kristal)
Deterministic normalization of JSON/signing targets used for hashing/signatures and stable identity.
See Kristal (pinned): `vendor/kristal/01-core-spec/ids-canonicalization-hashing.md`.
### Canonical Truth (kOA)
Truth that exists only after deterministic validation and compilation into a Kristal Exchange artifact (immutable once published).
### Case (Orgo Case) (kOA)
Long-lived container for operational work, context, and governance state; parent of Tasks.
### Claim-IR (Kristal)
Proposal-format for extracted claims (schema-constrained, uncertainty + evidence explicit).
See Kristal (pinned): `vendor/kristal/02-schemas/claim-ir.schema.json`.
### Compile (kOA)
The stage that invokes Kristal compilation to produce Kristal artifacts (Exchange + Runtime Pack) from validated inputs. Must be blocked if validation fails.
### Compatibility Policy (kOA)
Rules for accepting/activating artifacts across versions (schemas, policies, runtime constraints); used by Orgo and Konnaxion.
### Conformance (kOA)
The property of an implementation satisfying the ecosystem’s invariants and required contracts; typically enforced via tests and gates.
### Determinism (kOA)
Same pinned inputs + config + policies → identical (or canonical-identical) outputs; enforced at gates and required for reproducibility.
### Deterministic Gate (kOA)
Acceptance checkpoint that is deterministic and fail-closed (e.g., validation gate; signature verification gate).
### Distribution (kOA)
Packaging, publishing, fetching, verifying, caching, and activating Runtime Packs across devices/nodes.
### Downgrade Prevention (kOA)
Rules preventing activation of an older (or policy-incompatible) Runtime Pack when it violates safety/compatibility constraints.
### Exchange (Kristal Exchange) (Kristal)
Canonical, content-addressed truth artifact compiled after validation.
See Kristal (pinned): `vendor/kristal/02-schemas/exchange-manifest.schema.json` and core spec.
### Fail-Closed (kOA)
If declared integrity material (hashes/signatures/refs) is missing/invalid/mismatched, the operation must stop (no best-effort).
### Federation (Kristal)
Multi-authority model for shard/federation manifests, acceptance rules, and trust roots.
See Kristal (pinned): `vendor/kristal/02-schemas/exchange-federation-manifest.schema.json`.
### Hash / Content Hash (Kristal)
Canonical hash of signing target / content; used for IDs and verification.
See Kristal (pinned): `vendor/kristal/01-core-spec/ids-canonicalization-hashing.md`.
### Integrity Material (kOA)
Hashes, signatures, key references, and authority metadata required to verify an artifact. Verification is fail-closed.
### Konnaxion (kOA)
Distribution and platform layer facet responsible for pack fetch/verify/cache/activate/rollback and offline-first delivery behavior.
### Mandate Bundle (kOA)
Pinned policy/mandate context required for operation; if absent or revoked, the system must not operate.
### No Compile on Fail (kOA)
Hard gate: if validation fails, compilation (Exchange/Runtime Pack) must not run.
### No New Facts Downstream (kOA)
Render/execution layers must not invent facts; they must trace statements back to validated lineage or omit/refuse deterministically.
### Orgo (kOA)
Control plane: orchestrates pipeline stages, enforces gating, records Build/Release records, and governs operational work (Cases/Tasks).
### Pack (Runtime Pack) (Kristal)
Derived offline-executable artifact compiled from Exchange; consumed by Konnaxion/runtime.
See Kristal (pinned): `vendor/kristal/02-schemas/runtime-pack-manifest.schema.json`.
### Pack Index (kOA)
Signed/verified index describing available packs in a channel (e.g., latest/pinned/revoked), used by Konnaxion.
### Policy Selections (kOA)
The set of enabled policies/profiles used for a build/run; must be recorded for reproducibility and audit.
### Provenance (kOA)
Recorded lineage linking outputs to inputs, configs, policies, and gate results (Build Record + artifact manifests).
### Render Bundle (kOA)
Deterministic renderer output envelope with trace coverage and events.
kOA-native definition lives in `docs/30-artifacts/` (do not treat as Kristal-normative unless explicitly adopted in `docs/40-integration/kristal-v4/`).
### Release Record (kOA)
Operational record tying a build’s outputs to distribution intent (channels/cohorts/timestamps/status), enabling traceability and rollback.
### Resolution (SenTient) (kOA integration)
Mapping surfaces to candidates (QIDs/PIDs) + literal normalization + explicit ambiguity preservation.
Kristal defines the Resolved Claim-IR artifact schema.
### Resolved Claim-IR (Kristal)
Resolution output format consumed by validation/compile.
See Kristal (pinned): `vendor/kristal/02-schemas/resolved-claim-ir.schema.json`.
### Rollback (kOA)
Deterministic restoration to a known-good active pack state following activation failure, policy violation, or operator action.
### Schema (kOA)
A machine-validated contract defining artifact structure. Kristal schemas remain authoritative for Kristal artifacts.
### Shard (Kristal)
Partitioned Exchange unit with its own manifest and acceptance rules.
See Kristal (pinned): `vendor/kristal/02-schemas/exchange-shard-manifest.schema.json`.
### Signature / Signing Profile (Kristal)
Signature envelope and verification semantics (key_id, alg, payload_hash, etc.).
See Kristal (pinned): `vendor/kristal/01-core-spec/signatures-trust.md`.
### SenTient (kOA)
Resolution engine responsible for producing Resolved Claim-IR from Claim-IR while preserving uncertainty and determinism.
### Task (Orgo Task) (kOA)
Canonical unit of operational work with lifecycle state; executable by downstream actors (e.g., SwarmCraft) under governance rules.
### Trace Map (Render) (kOA)
Mapping from rendered assertions to supporting validated lineage (claims, entities, evidence); used to enforce “no new facts.”
### Trust Roots (Kristal + kOA deployment)
Pinned roots used to verify signatures (authority registry / deployment policy).
See Kristal (pinned): `vendor/kristal/02-schemas/authority-registry.schema.json`.
### Validation Report (Kristal)
Deterministic acceptance output from validation stage; compile must be blocked on failure.
See Kristal (pinned): `vendor/kristal/02-schemas/validation-report.schema.json`.
### Versioning (kOA)
Rules for evolving schemas/policies without breaking verification, reproducibility, or activation safety (see compatibility policy).
---
================================================================================================
FILE: docs_technical/00-overview/scope.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 53895b514f20d33e17354f906c2f78a09a0f5676c5a295b121aa652b4176093b
CONTENT_BYTES: 3818
================================================================================================
# Documentation Scope
**Normative for kOA:** YES
**External normative reference:** Kristal v4 (pinned)
This documentation describes the **kOA Digital Ecosystem**: a contract-driven pipeline and operating model that turns inputs into **validated knowledge artifacts** (via Kristal) and then distributes, renders, executes, and governs outcomes across the ecosystem.
## Goals
- Provide a clear, implementable understanding of **kOA components**, their responsibilities, and their interfaces.
- Define **kOA-owned contracts** (Orgo workflow objects, Build/Release records, Konnaxion operational state, etc.).
- Specify **operational behavior** (gates, safety, rollback, observability, incident response).
- Make integration with **Kristal v4** explicit **without duplicating** Kristal’s normative contracts.
## Non-goals
- Re-stating or re-implementing Kristal’s normative artifact definitions (schemas, canonicalization, hashing, signing targets).
- Providing product marketing, UX copy, or user manuals for specific applications.
- Defining deployment topology, cloud-specific infrastructure, or vendor-specific operational procedures beyond general guidance.
## Normative boundaries (ownership)
### Kristal-owned (external normative source)
Kristal defines the normative contracts for:
- Claim-IR, Resolved Claim-IR, Validation Report
- Exchange Manifest / Exchange identity rules
- Runtime Pack Manifest and offline execution constraints
- Canonicalization identifiers and integrity envelope shapes (hash/signature rules)
kOA docs must **reference** these, not duplicate them. Use:
- `40-integration/kristal-v4/pinned-dependency.md` (pin + required paths)
- `40-integration/kristal-v4/contract-pointers.md` (links to the exact pinned schemas/spec)
### kOA-owned (normative here)
kOA defines the normative contracts for:
- Orgo governance objects (Cases/Tasks), routing taxonomy, and workflow stage gating
- Build/Release records (operational evidence linking inputs → outputs)
- Konnaxion distribution/activation/rollback state and operational signals
- Ecosystem-level invariants (truth boundary enforcement, fail-closed policies, deterministic gate behavior)
## What “no redundancy” means in practice
- If a page needs to mention a Kristal artifact, it should:
1) name the artifact and where it sits in the pipeline,
2) specify **kOA-specific requirements around it** (e.g., “Orgo must block publish on failed verification”),
3) link to the pinned Kristal spec/schema for field-level definitions.
- kOA docs should never carry “illustrative manifests” for Kristal artifacts unless they are **verbatim** copied from the pinned Kristal version and clearly marked as such (preferred: link instead).
## Audiences
- **Implementers**: building services that produce/consume artifacts and participate in gates.
- **Integrators**: connecting external systems to ingestion, distribution, or rendering.
- **Operators**: running builds, releases, rollbacks, incident response, and audits.
- **Architects**: evolving contracts and invariants through ADRs.
## Change control
Any change to:
- an invariant,
- a kOA-owned artifact schema,
- a gate rule or safety policy,
must be accompanied by an ADR and a conformance test update (where applicable).
Changes to Kristal contracts must happen in the pinned Kristal source; then kOA updates its integration profile/conformance docs accordingly.
## Suggested reading order
1. `index.md`
2. `00-overview/system-at-a-glance.md`
3. `10-system/` (architecture/lifecycle/components/boundaries)
4. `20-nodes/` (node-by-node interface specs)
5. `30-artifacts/` (kOA-owned artifacts + schemas)
6. `40-integration/kristal-v4/` (pinned dependency + pointers + kOA profile + conformance)
7. `50-operations/` and `60-guides/` (how to run and build)
================================================================================================
FILE: docs_technical/00-overview/system-at-a-glance.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: bb12d067f6d51c458fdf3dfa6036b37130814a16642357d6c43fc9224ebee0dc
CONTENT_BYTES: 2842
================================================================================================
# System at a Glance
**Purpose:** One-page mental model of the kOA ecosystem: what it is, what flows through it, and where “truth” lives.
## What this system does
kOA turns messy inputs into **validated, canonical knowledge** and then safely distributes and uses that knowledge in offline-capable products and workflows.
## The stage spine (end-to-end)
1. **Ingest** raw inputs (snapshots + provenance)
2. **Extract** structured proposals (claims)
3. **Resolve** ambiguity (entities, properties, literals)
4. **Validate** deterministically (accept/reject with a report)
5. **Compile** canonical knowledge + a portable offline pack
6. **Distribute** packs with fail-closed verification
7. **Render** deterministic user-facing output with trace coverage
8. **Execute** work (tasks) with telemetry
9. **Feedback** becomes new governed work (never mutates canon)
## Core components (who does what)
* **Orgo (control plane):** orchestrates stages, enforces gates, records operational evidence, drives releases.
* **SenTient (resolver):** turns ambiguous surfaces into explicit, typed resolution outputs (keeps ambiguity explicit when unresolved).
* **Kristal (truth pivot):** compiles canonical truth artifacts (Exchange) and derived offline artifacts (Runtime Pack).
* **Konnaxion (distribution + platform):** verifies/activates/rolls back packs; powers offline-first delivery and product navigation.
* **Architect (renderer):** produces deterministic natural-language (or other outputs) that cannot introduce new facts and must trace.
* **SwarmCraft (execution):** executes tasks into deliverables under constraints; emits telemetry.
## Artifact families (what crosses boundaries)
* **Pre-truth artifacts:** snapshots, claim proposals, resolution outputs, validation reports
* **Canonical truth artifacts:** the compiled knowledge source of truth
* **Derived distribution artifacts:** portable offline packs + indexes
* **Operational artifacts:** cases/tasks, build/release records, activation/rollback records, telemetry events
## Where “truth” lives
* “Truth” exists only as **typed artifacts produced after deterministic validation + compilation**.
* Downstream systems (rendering, execution, social/feedback) must not invent or mutate canonical truth.
## What this repo is responsible for
This repo documents:
* kOA’s **system behavior**, responsibilities, operations, and kOA-owned artifacts (workflow + distribution + execution).
* The **integration stance**: how kOA depends on Kristal (pinned version, compatibility expectations, conformance checks).
This repo does **not** re-specify Kristal artifact formats/schemas.
## Next reads
* `docs/10-system/architecture.md`
* `docs/10-system/lifecycle.md`
* `docs/20-nodes/index.md`
* `docs/40-integration/kristal-v4/index.md`
* `docs/50-operations/pipeline.md`
================================================================================================
FILE: docs_technical/10-system/architecture.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: b5ac08b8ffa2b727d3b0fe53dca2b9e6f8504831621f0c9b7925e1b4f0e29e9b
CONTENT_BYTES: 5898
================================================================================================
# Architecture
**Normative for kOA:** YES (system architecture)
**External normative references:** Kristal v4 (pinned) for Kristal artifact formats/schemas; kOA does not restate Kristal contracts
---
## 1) Purpose
Define the kOA ecosystem architecture as a **contract-driven pipeline** that turns raw inputs into **canonical knowledge artifacts** (via Kristal) and then distributes, renders, operationalizes, and governs them safely.
This document describes:
- the major components (nodes) and their boundaries,
- the control-plane vs data-plane split,
- the stage spine (lifecycle),
- cross-cutting properties (determinism, fail-closed verification, auditability, offline behavior).
It does **not** redefine Kristal schemas or artifact formats; those are external normative sources pinned under `docs/40-integration/kristal-v4/`.
---
## 2) Scope and non-goals
### In scope
- kOA nodes and responsibilities
- Stage ordering and gates (architecture-level, not schema-level)
- Operational flow and failure containment
- Where Kristal artifacts enter/exit kOA boundaries
### Out of scope (by design)
- Field-level schemas for Kristal artifacts (Claim-IR, Exchange, Runtime Pack, Validation Report, etc.)
- Canonicalization/signature/hashing mechanics beyond “what is required at boundaries”
- Full deployment topology details (documented in operations)
---
## 3) System at a glance
kOA is a governed ecosystem organized around one rule: **contracts and invariants define truth**.
High-level flow:
1. Ingest inputs → snapshot provenance
2. Extract → Claim-IR
3. Resolve → Resolved Claim-IR
4. Validate (deterministic) → Validation Report
5. Compile → Kristal Exchange + Runtime Pack
6. Distribute → verify/activate/rollback
7. Render → deterministic output + trace map
8. Execute → tasks + telemetry
9. Feedback → new governed work
---
## 4) Primary nodes (components)
### 4.1 Control plane (governance + orchestration)
- **Orgo**: workflow controller; enforces stage ordering, gating, audit records, and publication rules.
### 4.2 Knowledge compilation (truth substrate)
- **Kristal**: compiles validated knowledge into canonical Exchange and derived Runtime Packs. Kristal is the **truth pivot** inside the ecosystem.
- **SenTient**: reconciliation/resolution engine producing Resolved Claim-IR from Claim-IR, preserving ambiguity explicitly.
### 4.3 Distribution + runtime
- **Konnaxion (distribution facet)**: verifies, activates, and rolls back Runtime Packs **fail-closed**, with atomic activation and deterministic rollback.
- **Malkuth (runtime)**: offline serving and execution substrate consuming the active Runtime Pack (read-only), providing deterministic query and (optional) routine execution.
### 4.4 Rendering (human-facing outputs)
- **Architect-Render**: deterministic generation **after** validation; must not introduce new facts and must provide traceability coverage (Render Bundle + trace map) per the kOA contract.
### 4.5 Optional execution (work output)
- **SwarmCraft**: executes governed tasks and emits telemetry; does not mutate canonical truth directly.
---
## 5) Boundary contracts (what crosses interfaces)
kOA boundaries exchange **typed artifacts**, not implicit state.
At a minimum, the pipeline carries:
- Input snapshots (provenance-pinned)
- Claim-IR (proposal boundary; Kristal-defined)
- Resolved Claim-IR (resolution boundary; Kristal-defined)
- Validation Report (deterministic acceptance evidence; Kristal-defined)
- Kristal Exchange (canonical truth; Kristal-defined)
- Runtime Pack (offline query payload; Kristal-defined)
- Render Bundle (deterministic user-facing output + trace map; kOA-defined)
- Orgo Cases/Tasks and operational records (kOA-native)
**Normative note:** Kristal artifact schemas are owned externally; kOA references the pinned Kristal version rather than duplicating schema definitions.
---
## 6) Stage spine and gate semantics (architecture-level)
### 6.1 Mandatory stage ordering
Orgo enforces this order:
**Ingest → Extract → Resolve → Validate → Compile → Publish/Distribute**.
(“Compile” invokes Kristal to produce Exchange and Runtime Pack from validated inputs.)
### 6.2 Hard gates (fail-closed)
- If validation fails, Orgo must not compile Exchange or Runtime Pack (“no compile on fail”).
- If distribution verification fails (hashes/signatures/compat), activation must not proceed.
### 6.3 Immutability and governed change
- Canonical truth artifacts are immutable once published; changes produce new versions (no in-place mutation).
- Feedback creates new governed work (Cases/Tasks) and can trigger new builds, not direct mutation.
---
## 7) Cross-cutting properties
### 7.1 Determinism
Determinism is enforced by pinned inputs, pinned policies/config, and deterministic gates. kOA documents determinism as a system invariant; Kristal defines canonicalization and identity mechanics externally (pinned reference).
### 7.2 Auditability
Every stage output must be traceable via Orgo records and artifact references, enabling reproducibility and investigation.
### 7.3 Offline-first distribution
Runtime Packs are designed for offline execution; Konnaxion operationalizes offline verification/activation/rollback, and Malkuth serves the active pack offline.
### 7.4 Multi-tenancy and trust boundaries
Tenant-scoped policies and trust roots must be enforced at verification and publication boundaries (documented in operations/security; Kristal supplies authority/trust schema structures externally).
---
## 8) Where to go next
- Lifecycle: `docs/10-system/lifecycle.md`
- Components map: `docs/10-system/components.md`
- Trust boundaries: `docs/10-system/trust-boundaries.md`
- Determinism: `docs/10-system/determinism.md`
- Node specs: `docs/20-nodes/`
- Kristal integration (pinned references + kOA profile): `docs/40-integration/kristal-v4/`
================================================================================================
FILE: docs_technical/10-system/components.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 1fb254c0a98b1e669b70ccc04da5e7f0cd04243b69c4d01a39f3445d774d97cc
CONTENT_BYTES: 6681
================================================================================================
# Components
**Normative for kOA:** NO (system map; descriptive)
**External normative references:** Kristal v4 (pinned) for Kristal artifact formats/schemas (referenced, not restated)
**Purpose:** Map the ecosystem’s components, responsibilities, and interfaces—without re-defining node specs or artifact schemas.
---
## 1) Planes (system at a glance)
- **Control Plane:** Orgo (governance + workflow orchestration + audit)
- **Truth Plane (Canonical):** Kristal (Exchange + Runtime Pack; canonical IDs, hashing, signatures; query contract)
- **Resolution Plane:** SenTient (reconciliation / normalization / ambiguity structures)
- **Articulation Plane:** Architect (Strategy + Render; deterministic outputs; trace)
- **Execution Plane:** SwarmCraft (tool/agent/human execution; telemetry)
- **Distribution + Runtime Plane:** Konnaxion (pack distribution, verification, caching, activation/rollback) + Malkuth (offline serving/execution substrate)
- **Trust + Impact Plane:** EkoH (reputation/ethics, votes, impact ledger; never mutates canonical truth)
---
## 2) Component responsibilities and interfaces
### 2.1 Orgo (Control Plane)
**Owns**
- Workflow ordering and gating (ingest → Claim-IR → resolution → validation → compile → publish)
- Governance: approvals, policies, tenant boundaries, audit logging
- Build records: inputs, config hashes, policy selections, outputs (content-addressed references)
- Distribution triggers and distribution status tracking
**Does not own**
- Canon mutation from feedback
- Resolution internals
- Rendering internals
**Interfaces**
- Ingest adapters (sources → snapshots)
- Extractors (snapshots → Claim-IR)
- SenTient (Claim-IR → Resolved Claim-IR)
- Validation engine (Resolved Claim-IR → Validation Report)
- Kristal compiler (validated inputs → Exchange + Runtime Pack)
- Konnaxion (publish/fetch/verify/activate packs; telemetry back)
- EkoH (optional governance-weighting signals)
---
### 2.2 Kristal (Truth Plane / Canon)
**Owns (external normative)**
- Canonical truth representation (Exchange)
- Offline execution representation (Runtime Pack)
- Canonicalization + hashing rules, signatures/trust roots
- Profiles/exports and query contract (portable semantics)
**Does not own**
- Workflow governance (Orgo)
- UI presentation (Konnaxion)
- Downstream non-deterministic invention
**Interfaces (as used by kOA)**
- Compiler API (inputs → Exchange/Pack + manifests)
- Verification API (hash/signature verification)
- Query API (portable query semantics over Exchange/Pack)
- Integration contracts for Orgo / SenTient / Architect / Konnaxion
> kOA does not restate Kristal contracts here. See `docs/40-integration/kristal-v4/`.
---
### 2.3 SenTient (Resolution Plane)
**Owns**
- Deterministic resolution boundary (candidate IDs, normalized literals, explicit ambiguity objects, structured warnings/errors)
- Schema-valid, reproducible Resolved Claim-IR output (Kristal-defined artifact)
**Does not own**
- Canon compilation
- Validation acceptance policy
- Direct publication
**Interfaces**
- Input: Claim-IR batches (+ optional context)
- Output: Resolved Claim-IR + warnings/errors
- Optional: provenance attachments for audit
---
### 2.4 Validation Engine (Acceptance Gate)
**Owns**
- Deterministic acceptance decision (“no compile on fail”)
- Validation report artifacts (machine-readable pass/fail + reasons; Kristal-defined artifact)
**Interfaces**
- Input: Resolved Claim-IR + policy selections
- Output: Validation Report
---
### 2.5 Architect (Articulation Plane)
Architect is explicitly split into two roles.
#### 2.5.1 Architect-Strategy
**Owns**
- Planning and decomposition of objectives into structured work (Cases/Tasks)
- Selection of rendering specs/templates (but not editorial invention of facts)
**Interfaces**
- Input: Mandate + user goal + available canon/pack index
- Output: Plans → Orgo Cases/Tasks; Rendering Specs
#### 2.5.2 Architect-Render
**Owns**
- Deterministic rendering from validated knowledge only
- Output packaging (Render Bundle: content + trace map + metadata; kOA-owned)
- Refusal/error behavior when trace coverage is incomplete
**Interfaces**
- Input: Runtime Pack query results (via Malkuth/Konnaxion) OR verified Exchange-derived query results + Rendering Spec
- Output: Render Bundle (content + trace map + events/metadata)
---
### 2.6 SwarmCraft (Execution Plane)
**Owns**
- Execution of typed work (tasks) via tools/agents/humans
- Telemetry emission (status, logs, correlation IDs, outputs)
- Retry and resilience at execution level (not truth mutation)
**Does not own**
- Canon creation
- UI distribution
**Interfaces**
- Input: Orgo Tasks (typed, scoped, policy-aware)
- Output: execution results + telemetry signals (which may open new governed work)
---
### 2.7 Konnaxion (Distribution + Interface Plane)
Konnaxion is treated as two facets.
#### 2.7.1 Distribution facet (Runtime Packs)
**Owns**
- Pack distribution (channels/tenants/environments)
- Integrity verification (fail-closed where declared)
- Caching/storage layout, activation, rollback/downgrade behavior
- Surfacing pack provenance/version metadata to higher layers
**Interfaces**
- Input: Published Runtime Packs + manifests + trust roots/keys
- Output: Activated pack set + activation state + telemetry
#### 2.7.2 Interface / Navigation facet
**Owns**
- User navigation/search across available packs/exchanges
- Presentation routing to Architect-Render (render requests)
- Feedback capture (signals → Orgo as governed work)
---
### 2.8 Malkuth (Runtime Substrate)
**Owns**
- Serving the active pack read-only (offline-first)
- Deterministic query/lookup over pack payloads
- Optional routine execution under sandbox/resource controls
- Runtime telemetry (without canon mutation)
**Interfaces**
- Input: Activated pack mount + activation metadata (from Konnaxion)
- Output: query/execution results + telemetry
---
### 2.9 EkoH (Trust + Impact Plane)
**Owns**
- Trust/impact ledger (expertise/ethics scoring, vote aggregation, impact history)
**Non-negotiable boundary**
- EkoH never mutates canonical truth; it produces governance-weighting signals.
---
## 3) Where the detailed contracts live
- Node-level responsibilities and boundary specifics: `docs/20-nodes/*` (one page per component role).
- kOA-owned artifact contracts and schemas (e.g., Orgo Case/Task, Build/Release records): `docs/30-artifacts/*`.
- Kristal artifact contracts/schemas (Exchange, Runtime Pack, Claim-IR, Resolved Claim-IR, Validation Report): referenced via the pinned Kristal v4 dependency (not duplicated here): `docs/40-integration/kristal-v4/`.
================================================================================================
FILE: docs_technical/10-system/determinism.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 4075ec4087f338ee75553ec5a1ef548d8eb2cc93042b2353f13244e509eb8499
CONTENT_BYTES: 6747
================================================================================================
# Determinism (kOA system)
**Status:** Normative (kOA)
**Scope:** End-to-end behavior across Orgo → Kristal → Konnaxion → Architect, including gates, builds, distribution, and rendering.
## 1) Purpose
Determinism is the property that the system produces **identical** (or **canonically identical**) outputs when given identical pinned inputs + pinned configuration + pinned policies, and that failures occur with **stable error behavior**.
This document defines:
- what kOA means by determinism,
- what must be pinned/recorded,
- what classes of nondeterminism are forbidden at boundaries,
- what conformance tests kOA requires.
**Not in scope:** re-specifying Kristal artifact schemas, hash targets, canonicalization, signing formats, or Kristal compiler internals. Those are treated as external normative dependencies (see `../40-integration/kristal-v4/contract-pointers.md`).
## 2) Definitions
- **Deterministic output:** bit-identical outputs for the same pinned inputs/config/policies.
- **Canonically identical output:** outputs may differ in non-semantic representation but are identical after applying the declared canonicalization (e.g., JCS).
- **Pinned inputs:** a content-addressed snapshot of all upstream artifacts used (inputs, Claim-IR, Resolved Claim-IR, rulesets, etc.).
- **Pinned configuration:** exact compiler/runtime config captured by a config hash and versioned component identities.
- **Portable policy:** an enumerated policy selection recorded in manifests/records such that another implementation can reproduce behavior.
## 3) Determinism layers (kOA)
kOA determinism is enforced at multiple layers:
### 3.1 Workflow determinism (Orgo)
- Stage ordering is fixed and auditable.
- Validation failure deterministically blocks compilation (“no compile on fail”).
- A Build Record deterministically binds inputs → config → policy → outputs.
### 3.2 Canon determinism (Kristal compilation)
- Exchange and Runtime Pack are built deterministically under pinned inputs/config/policies.
- Content-addressed IDs, hashes, and manifests must be reproducible across implementations.
### 3.3 Distribution determinism (Konnaxion)
- Activation is atomic and verification is fail-closed.
- Rollback behavior is deterministic given the same trigger sequence and available pack set.
### 3.4 Rendering determinism (Architect-Render)
- Rendering must be deterministic from the same validated inputs + templates + parameters.
- Rendering must not introduce new facts; it must trace every factual statement or refuse/omit deterministically.
## 4) What MUST be pinned/recorded (minimum reproducibility surface)
kOA requires that the following are recorded in the operational evidence (Build/Release records and/or referenced manifests):
1) **Inputs**
- input snapshot identifier(s)
- upstream artifact references required to rebuild
2) **Policy selections**
- policy IDs/versions (and any enumerated policy knobs that affect output)
3) **Component identities**
- compiler / validator / renderer / packager names + versions
- dependency lock versions where applicable
4) **Configuration hash**
- hash of the effective configuration that influences outputs
5) **Canonicalization declaration**
- declared canonicalization profile + version for any content-addressed JSON material
6) **Integrity declarations**
- declared file hashes and signatures (if present) sufficient for offline verification
## 5) Forbidden (or constrained) sources of nondeterminism
### 5.1 Wall-clock timestamps
- Timestamps may exist for audit and correlation, but MUST NOT affect any content-addressed ID or hash target unless a profile explicitly includes them.
### 5.2 Randomness / probabilistic components
- Any probabilistic component MUST support a deterministic mode for tests and reproducible builds:
- fixed seed
- pinned model version
- pinned dependency versions
- frozen candidate sources (if applicable)
- If deterministic mode is impossible, the nondeterministic stage must be moved **upstream of the truth boundary** and its outputs must be frozen as inputs (e.g., store Claim-IR and do not re-extract).
### 5.3 Concurrency and ordering
- Any output that depends on iteration order MUST define deterministic sorting and tie-breakers.
- Parallelism may be used, but output order and aggregation MUST be deterministic.
### 5.4 Floating-point / platform differences
- Algorithms that can vary across CPU/OS (float math, hashing libraries, locale collation) MUST be stabilized by:
- integer-only representations where possible,
- explicit rounding rules,
- canonical byte encodings,
- pinned library implementations.
### 5.5 External dependencies (network, live services)
- Any external dependency MUST be represented as a content-addressed input snapshot (or otherwise pinned and recorded) for any deterministic build claim.
- Network lookups are not allowed inside deterministic compilation unless their results are captured as pinned inputs.
## 6) Canonicalization and hashing (kOA rule, Kristal normative)
kOA requires that all content-addressed JSON material uses the declared canonicalization profile/version and that the system’s reproducibility tests compute IDs/hashes using that canonicalization.
The **normative** canonicalization/hashing rules for Kristal artifacts are treated as external dependencies and must be followed exactly as pinned in `../40-integration/kristal-v4/contract-pointers.md`.
## 7) Deterministic failure behavior
Determinism also applies to failures:
- Given identical inputs/config/policies, validation failures must produce stable error categories/codes and stable gating outcomes.
- Rendering must deterministically:
- trace, or
- omit, or
- mark uncertain (only when upstream uncertainty exists), or
- refuse,
under the same policy + inputs.
## 8) Conformance expectations (what kOA will test)
kOA conformance includes (minimum):
- Canonicalization and hashing checks under the declared profile.
- Rebuild determinism: same pinned inputs/config/policies → same content IDs and declared file hashes.
- Fail-closed verification: any declared integrity mismatch blocks publish/activation.
- Deterministic rendering: same validated inputs/template/params → same outputs and trace coverage (or same deterministic refusal/omission behavior).
## 9) Operational notes
- Determinism does not prohibit optimization; it constrains optimization to **declared policies** and requires those policy selections to be recorded.
- Where kOA must interoperate with multiple implementations, kOA should treat “deterministic build rules” and “reproducibility acceptance tests” from the pinned Kristal dependency as gating requirements for release.
================================================================================================
FILE: docs_technical/10-system/failure-modes.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: aca7e979d2e639e40c669717cc110f5339ed2aa48415e227025cf65e101ec79b
CONTENT_BYTES: 7776
================================================================================================
# Failure Modes
**Normative for kOA:** YES
**External normative reference:** Kristal v4 (pinned)
This page defines the kOA system-level failure taxonomy, how failures propagate across nodes, and what constitutes safe behavior at the kOA truth boundary. Kristal v4 defines the normative artifact validity rules; kOA defines how the system reacts when those rules are not met.
## Principles
* **Fail closed at the truth boundary.** Any artifact that fails Kristal verification, schema validation, or determinism checks must not be compiled, promoted, activated, or served.
* **Determinism over availability.** If determinism cannot be guaranteed, kOA must halt promotion/activation rather than proceed with “best effort.”
* **Separate “content invalid” from “system impaired.”** Content failures are handled via quarantine and repair; infrastructure failures are handled via retry/backoff, degradation, and operator escalation.
* **No implicit mutation.** Runtime feedback, overrides, or emergency controls cannot silently change canon; they must be recorded as governed kOA work items.
## Failure classes
### F1 — Input acquisition failures
**Description:** Missing, unreadable, or inconsistent source inputs before Claim-IR formation.
**Examples**
* Input snapshot missing/expired
* Source connector unavailable
* Permission/credential failure
* Partial fetch leading to non-reproducible inputs
**Required behavior**
* Mark run as blocked; do not emit candidate artifacts
* Retry only if inputs can be fetched deterministically (same snapshot identity)
* Record an Orgo Task for remediation (credential fix, snapshot regeneration)
**Operator signals**
* Elevated fetch errors, timeouts, checksum mismatch on snapshots
---
### F2 — Claim formation and resolution failures
**Description:** The system cannot produce a well-formed Claim-IR or cannot resolve it to a fully grounded, policy-compliant Resolved Claim-IR.
**Examples**
* Claim-IR schema invalid (kOA-side pre-check)
* Missing required citations/anchors in resolution
* Policy gate rejects resolution (e.g., insufficient evidence, disallowed sources)
**Required behavior**
* Do not proceed to validation/compile
* Emit a failure report (kOA build record) with actionable error codes
* Create Orgo work item (repair claim, adjust mandate, fix input coverage)
**Operator signals**
* Increased policy rejections
* Repeated failures on the same mandate indicating systemic rule breakage
---
### F3 — Kristal verification failures (truth boundary)
**Description:** Any failure to verify Kristal artifacts or their integrity. This is the hard gate.
**Examples**
* Signature invalid or signer not trusted
* Hash mismatch (artifact tampering or corruption)
* Canonicalization mismatch
* Schema nonconformance for Kristal artifacts
* Traceability requirements not satisfied (missing references, broken links)
**Required behavior**
* Quarantine the artifact set (do not compile, do not publish)
* Prevent activation and rollback if already active
* Raise high-severity alert if failure occurs in a promoted/active channel
* Record exact verification results and offending artifact IDs in the build record
**Operator signals**
* Verification error spikes
* Trust store changes correlated with failures
* Artifact store corruption indicators
---
### F4 — Determinism failures
**Description:** The same declared inputs and policies do not reproduce identical outputs.
**Examples**
* Non-deterministic compilation output
* Runtime Pack differs across rebuilds with identical inputs
* Environment-dependent variation (locale/timezone, unordered maps, nondeterministic dependency versions)
**Required behavior**
* Block promotion
* Require reproducibility replay in a clean environment
* If repeated: open incident and treat as systemic defect, not content defect
**Operator signals**
* Rebuild mismatch rate
* Differences clustered by runner image/version
---
### F5 — Compilation and packaging failures
**Description:** Compiler cannot produce a valid runtime output from a verified/validated input set.
**Examples**
* Compiler crash
* Unsupported feature in the target runtime
* Missing dependency in build environment
* Packaging step fails (bundle assembly)
**Required behavior**
* Fail build; do not publish
* Retry only with identical toolchain and pinned dependencies
* Escalate if failures exceed threshold or affect multiple mandates
**Operator signals**
* Build failures correlated with toolchain upgrades
* Increased package assembly errors
---
### F6 — Distribution and activation failures (Konnaxion)
**Description:** Artifacts cannot be distributed, verified, or activated in target environments.
**Examples**
* Target cannot fetch pack
* Activation preflight fails (integrity, compatibility, policy mismatch)
* Partial rollout stalls
* Rollback fails or is unavailable
**Required behavior**
* Do not activate partially unless rollout policy explicitly allows staged activation
* Prefer automatic rollback on activation failure
* Maintain last-known-good active pack per channel/environment
* Ensure activation is idempotent and auditable
**Operator signals**
* Rollout stuck percentage
* Activation failure rate by environment
* Rollback latency increases
---
### F7 — Runtime enforcement and safety failures
**Description:** Active runtime violates declared constraints or cannot enforce gating logic.
**Examples**
* Policy enforcement module disabled or bypassed
* Missing trace map at runtime where required
* Runtime uses stale pack without declaring it
* Safety filter failure (must degrade to safe responses)
**Required behavior**
* Degrade to safe mode (read-only, deny, or minimal behavior as defined by kOA policy)
* Trigger emergency rollback if policy requires
* Generate incident ticket with high severity
**Operator signals**
* Missing policy decision logs
* Drift between active pack ID and reported pack ID
* Increased unsafe output detections
---
### F8 — Observability and audit failures
**Description:** The system cannot produce sufficient logs/records to reconstruct what happened.
**Examples**
* Missing build record or release record
* Missing activation events
* Incomplete verification logs
**Required behavior**
* Treat as a release blocker for regulated/strict channels
* Continue running last-known-good but halt new promotions
* Escalate to operators
**Operator signals**
* Logging pipeline errors
* Missing event streams, gaps in audit timeline
---
## Propagation rules (how failures move through the system)
* **F1–F2** are “pre-boundary” and should not produce promotable outputs.
* **F3–F4** are “boundary/integrity” and must block promotion/activation and trigger quarantine.
* **F5** blocks publication but does not necessarily indicate content corruption.
* **F6–F7** require environment-specific safety behavior (staged rollback, safe mode).
* **F8** blocks promotions in strict channels because auditability is part of safety.
## Severity and required response
* **SEV-1:** Any F3/F7 impacting an active channel in production, or rollback unavailable when required.
* **SEV-2:** Widespread F4 determinism failures, repeated F6 activation failures across environments.
* **SEV-3:** Elevated F1/F5 rates, localized F6, or intermittent F8.
* **SEV-4:** Single-mandate issues with clear remediation.
## Required artifacts (kOA-owned) for failure handling
* **Build Record:** captures stage outcomes, exact error codes, artifact IDs, and verification results.
* **Release Record:** captures what was promoted, where, and under which policies.
* **Orgo Task/Case:** tracks remediation actions with ownership and approval.
(Definitions live in `30-artifacts/`.)
================================================================================================
FILE: docs_technical/10-system/lifecycle.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 6334f49a0bc78d30fdd71478f4fb80db0e91f111a7a6480e924fc7c690399781
CONTENT_BYTES: 8491
================================================================================================
# Lifecycle (kOA end-to-end)
**Status:** Canonical (system-level)
**Purpose:** Define the canonical lifecycle of the ecosystem: how raw inputs become validated canonical truth (Kristal Exchange), how that truth becomes portable offline execution artifacts (Runtime Packs), how outputs are rendered deterministically, how work is executed, and how feedback re-enters the system without mutating canon.
---
## 1) Key terms
- **Build:** A governed run of the pipeline producing a new Kristal Exchange + Runtime Pack (or failing before canon).
- **Release:** A distributed publication of a Runtime Pack (and associated metadata) through Konnaxion.
- **Case / Task:** Orgo’s governance units. A **Task** is the atomic unit of work; a **Case** groups tasks over time.
- **Canon:** Kristal Exchange (the authoritative, immutable truth artifact).
- **Derived:** Runtime Pack and Render Bundles (must be traceable to canon + pinned configuration).
- **Gate:** A deterministic acceptance point; failure blocks downstream stages (fail-closed when integrity is declared).
---
## 2) Lifecycle overview
### 2.1 High-level stage spine
0) Load Mandate + Blueprint
1) Ingest inputs
2) Extract Claim-IR
3) Resolve Claim-IR (SenTient)
4) Validate (Orgo gate)
5) Compile canon + runtime (Kristal)
6) Publish/Distribute (Konnaxion)
7) Render outputs (Architect-Render)
8) Execute work (SwarmCraft)
9) Feedback → new governed work (Orgo)
### 2.2 Mermaid (conceptual)
```mermaid
flowchart TD
A[Mandate + Blueprint] --> B[Ingest Inputs]
B --> C[Extract -> Claim-IR]
C --> D[Resolve -> Resolved Claim-IR]
D --> E{Validate?}
E -- fail --> X[Stop: No Canon / No Pack / No Release]
E -- pass --> F[Compile -> Exchange + Runtime Pack]
F --> G{Verify for Activation?}
G -- fail --> Y[Reject: Fail-Closed / Rollback-or-Stay]
G -- pass --> H[Distribute Runtime Pack]
H --> I[Render -> Render Bundle + trace_map]
I --> J[Execute Tasks -> Telemetry]
J --> K[Feedback -> New Case/Task]
K --> C
````
---
## 3) Stage-by-stage specification
Each stage specifies: **Owner**, **Inputs**, **Outputs**, **Gate**, **Observability**.
### Stage 0 — Mandate + Blueprint load
**Owner:** Keter (Mandate) + Binah (Blueprint), enforced by Orgo.
**Inputs**
* Mandate bundle (scope, constraints, success criteria)
* Blueprint bundle (schemas, ontologies, policies, versions)
**Outputs**
* Pinned runtime context reference (immutable refs to mandate + blueprint)
**Gate**
* Must refuse to run without an active mandate (when required by policy).
* Must pin exact blueprint revisions used for the build.
**Observability**
* mandate_ref, blueprint_ref, policy pins
* correlation IDs (build_id / request_id if present)
---
### Stage 1 — Ingest (raw inputs)
**Owner:** Chokmah (Inputs adapters), orchestrated by Orgo.
**Inputs**
* Source documents, feeds, uploads, connectors
* Ingest policy + provenance rules (from Blueprint)
**Outputs**
* Input snapshots (immutable snapshot refs)
* Optional snapshot set manifest (listing snapshots + provenance pointers)
**Gate**
* Provenance must be preserved.
* Snapshots must be immutable (content-addressed strongly recommended).
**Observability**
* ingest adapter version/config ref
* snapshot IDs, snapshot-set ref
* provenance pointers (opaque refs allowed)
---
### Stage 2 — Extract → Claim-IR
**Owner:** Extractor(s), governed by Orgo.
**Inputs**
* Input snapshots (or snapshot-set ref)
* Claim-IR schema/policy (pinned from Blueprint)
**Outputs**
* Claim-IR batch reference
**Gate**
* Extractors must output proposals only (no “truth”).
* Evidence pointers and uncertainty markers must be preserved.
**Observability**
* extractor identity/version/config ref
* input snapshot refs used
* claim-ir ref
---
### Stage 3 — Resolve → Resolved Claim-IR (SenTient)
**Owner:** SenTient, governed by Orgo.
**Inputs**
* Claim-IR batch
* Resolution policy + candidate sources (pinned)
**Outputs**
* Resolved Claim-IR batch reference (with explicit ambiguity preserved)
**Gate**
* Must be deterministic under pinned policy/config.
* Must preserve unresolved ambiguity explicitly (no silent coercion).
**Observability**
* resolver identity/version/config ref
* warnings/errors summary (stable codes)
* resolved-claim-ir ref
---
### Stage 4 — Validate (deterministic acceptance gate)
**Owner:** Validation engine, enforced by Orgo.
**Inputs**
* Resolved Claim-IR
* Validation policy/profile set (pinned)
**Outputs**
* Validation Report reference
**Gate (hard)**
* If validation fails, compilation must not proceed (“no compile on fail”).
**Observability**
* validator identity/version/config ref
* validation report ref
* gate decision + reason codes
---
### Stage 5 — Compile (Kristal)
**Owner:** Kristal compiler, invoked by Orgo after Stage 4 pass.
**Inputs**
* Resolved Claim-IR
* Validation Report (pass)
* Compiler config + pinned profiles/policies
**Outputs**
* Kristal Exchange (+ Exchange Manifest)
* Runtime Pack (+ Runtime Pack Manifest)
**Gate**
* Must produce schema-conformant artifacts (Kristal-owned schemas).
* Must record reproducibility metadata sufficient for rebuild determinism (via manifests/build records).
**Observability**
* compiler identity/version/config ref
* exchange refs + pack refs
* manifest refs
* content-hash / signature verification results (if produced)
---
### Stage 6 — Publish / Distribute (Konnaxion)
**Owner:** Konnaxion (distribution facet), triggered and tracked by Orgo.
**Inputs**
* Runtime Pack + manifest
* Channel/release intent (from Orgo)
* Trust roots / revocation info (tenant-scoped)
**Outputs**
* Published artifacts in channel(s)
* Activation/verification status updates
* Rollback records (when applicable)
**Gate (hard)**
* If integrity material is declared (hash/signatures), verification must be fail-closed.
* Activation must be atomic; rollback must be deterministic.
**Observability**
* verification results (pass/fail + codes)
* active pack ID, previous pack ID
* rollout cohort/channel + timestamps
---
### Stage 7 — Render outputs (Architect-Render)
**Owner:** Architect-Render.
**Inputs**
* Kristal query results (from Exchange and/or Pack, per policy)
* Render template + parameters (pinned)
* Render policy (no-new-facts + trace requirements)
**Outputs**
* Render Bundle (includes trace coverage)
**Gate (hard)**
* Rendering must not introduce new facts.
* Output must be deterministic under pinned inputs/template/params.
* If trace coverage is insufficient, renderer must deterministically omit / mark-uncertain / refuse per policy.
**Observability**
* renderer identity/version/config ref
* template + params refs
* render bundle ref + trace coverage metrics
---
### Stage 8 — Execute work (SwarmCraft)
**Owner:** SwarmCraft (or equivalent execution plane), governed by Orgo.
**Inputs**
* Orgo Tasks (and required inputs)
* Execution policy (resource caps, tool allow-lists)
**Outputs**
* Execution results
* Telemetry events
**Gate**
* Must follow deterministic policy where required (stable toolchain versions, fixed seeds when applicable).
* Must emit telemetry sufficient for audit and feedback routing.
**Observability**
* task_id, case_id, correlation IDs
* result refs
* telemetry refs
---
### Stage 9 — Feedback → new governed work
**Owner:** Orgo (ingestion of signals).
**Inputs**
* Telemetry, user feedback, ops events, trust/impact signals
**Outputs**
* New Cases/Tasks (governed work items)
* Optional prioritization/triage updates
**Gate**
* Feedback must not mutate canon directly.
* Any canon-affecting change must be a new build (new artifacts, new IDs).
**Observability**
* signal source + classification
* created case/task IDs + routing
* linkage to triggering build/release IDs (when applicable)
---
## 4) Cross-cutting hard rules (summary)
* **No compile on fail:** Stage 4 fail blocks Stage 5.
* **Fail-closed integrity:** Any declared hashes/signatures must verify before activation/publish.
* **Immutable canon:** Exchange is never edited in place; updates produce new artifacts/IDs.
* **No new facts downstream:** Rendering cannot invent; it must trace or refuse deterministically.
---
## 5) Pointers
* Build orchestration details: `docs/50-operations/pipeline.md`
* Kristal v4 integration profile and contract pointers: `docs/40-integration/kristal-v4/`
* Conformance tests: `docs/60-guides/testing.md`
================================================================================================
FILE: docs_technical/10-system/trust-boundaries.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 2a59a0e3caf86dcfd9814577621a6d74ef9ac018de64fa957e8784efb1034385
CONTENT_BYTES: 5455
================================================================================================
# Trust Boundaries
**File:** `docs/10-system/trust-boundaries.md`
**Status:** Normative (kOA)
**External normative references:** Kristal v4 docs + schemas (pinned dependency)
---
## 1) Purpose
Define the hard boundaries that keep the ecosystem:
- auditable,
- offline-correct,
- tenant-safe,
- fail-closed when integrity is declared,
- resistant to downgrade/substitution and cross-tenant trust confusion.
This page is *system-level*. It does **not** restate Kristal artifact schemas.
---
## 2) Boundary map (what is allowed to change, where)
### 2.1 Truth boundary (canon boundary)
**Where canon is created:** deterministic validation → compilation into Kristal Exchange.
**Downstream rule:** nothing downstream mutates canon; changes become new governed work that yields new artifacts.
### 2.2 Integrity boundary (verification boundary)
**Where bytes become trusted:** at publish (Orgo) and at activation/use (Konnaxion).
If integrity material is declared, verification is mandatory and fail-closed.
### 2.3 Distribution boundary (activation boundary)
**Where “what runs locally” is decided:** Konnaxion activation pipeline (atomic switch, compatibility checks, downgrade prevention, rollback constraints).
### 2.4 Rendering boundary (no-new-facts boundary)
**Where language/UI is produced:** Architect-Render must not introduce unsupported facts; it must trace to canon.
### 2.5 Execution boundary (side-effects boundary)
**Where real-world/side-effect work happens:** SwarmCraft (or equivalent). Execution produces telemetry and artifacts, not canon edits.
### 2.6 Tenancy boundary (isolation boundary)
**Where data and trust must not cross:** tenant/environment boundaries across storage, trust roots, channels, and policy.
---
## 3) Trust roots and trust material
### 3.1 Trust roots are pinned and tenant-scoped
- Trust roots MUST be pinned per channel and scoped to tenant/environment.
- Correctness MUST NOT depend on fetching trust roots over the network at activation time.
### 3.2 Trust material types (typical)
- channel index signatures (optional but recommended)
- Runtime Pack Manifest signatures
- per-file inventory hashes in pack bundles
- authority registries / revocation lists (if your deployment uses them)
---
## 4) Orgo boundaries (control plane)
### 4.1 Gate enforcement
Orgo enforces stage ordering and gates (especially “no compile on fail”) and blocks publish if required integrity checks fail.
### 4.2 Evidence recording
Orgo records:
- build/release identifiers and artifact identifiers,
- signer identity (`key_id`) and signature metadata,
- policy selection / configuration identity,
- references needed for reproducibility and audit.
### 4.3 Tenant-safe trust handling
Orgo MUST not mix trust roots across tenants/channels and should manage rotation and revocation publication.
---
## 5) Konnaxion boundaries (distribution facet)
### 5.1 Activation rule (atomic and gated)
Konnaxion activates a pack only when:
1) integrity verification passes (as declared; fail-closed)
2) manifest parses + schema validates
3) referenced files exist
4) runtime compatibility checks pass
5) activation is an atomic switch (no partial activation)
### 5.2 Verification ordering (recommended)
1) verify channel index (if present)
2) verify Runtime Pack Manifest signature(s)
3) verify bundle file hashes (inventory)
4) activate
### 5.3 Downgrade prevention + substitution safety
- Maintain deterministic, persisted state (per channel) for highest activated release.
- Reject same-release substitutions unless explicitly authorized.
- Do not activate revoked artifacts when a verified revocation mechanism exists.
### 5.4 Rollback is explicit and policy-authorized
Rollback must be deterministic given the same verified inputs and triggers, and must not occur silently.
---
## 6) Multi-tenancy boundaries
### 6.1 Data isolation
- Inputs, build artifacts, packs, logs, and telemetry are tenant-scoped.
- Access control and storage layout must prevent cross-tenant reads/writes.
### 6.2 Trust isolation
- Trust roots are tenant/environment/channel scoped.
- Signature verification must be tenant-correct (no cross-tenant key acceptance unless explicitly configured and auditable).
### 6.3 Policy isolation
- Mandates/policies and blueprint/config pins are tenant-scoped unless explicitly shared by design (and then treated as shared dependencies with explicit governance).
---
## 7) Failure modes (must be handled deterministically)
- **Wrong trust root set** (cross-tenant confusion) → hard fail (no activation/publish).
- **Tampered bytes** (hash/signature mismatch) → fail-closed.
- **Downgrade attempt** (lower release_id without rollback authorization) → refuse activation.
- **Substitution** (same release_id, different artifact_id) → refuse unless reissue authorization exists.
- **Revoked pack/key** → refuse activation when revocation is enforced.
---
## 8) Minimum conformance checklist
- [ ] Truth boundary enforced (no compile on fail; no downstream canon edits).
- [ ] Pinned trust roots per channel; offline verification possible.
- [ ] Fail-closed on any declared integrity material.
- [ ] Atomic activation; deterministic rollback behavior.
- [ ] Downgrade prevention + substitution safety.
- [ ] Tenant isolation for data + trust roots + policy.
- [ ] Orgo records build/release provenance and integrity metadata (`key_id`, signatures, hashes).
================================================================================================
FILE: docs_technical/20-nodes/binah-blueprint.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 07c85296cbe486979d580517a805d411fcd5f8f08acf4784960b7ea315118462
CONTENT_BYTES: 4452
================================================================================================
# Binah — Blueprint
**Normative for kOA:** YES
**External normative reference:** Kristal v4 (pinned)
Binah is the planning node that converts a mandate + available inputs into a **Blueprint**: an explicit, auditable plan for what will be built, how it will be grounded, and which downstream nodes will execute each step. Binah does not validate truth; it structures work so that truth validation is possible and deterministic.
## Responsibility
Binah owns:
* Producing a **Blueprint** that is complete enough for deterministic execution downstream
* Declaring required inputs, retrieval/grounding strategy, and policy gates to be applied
* Assigning execution responsibilities across downstream nodes (SenTient, Architect, Compiler, Daat)
Binah does not own:
* Ground-truth resolution (SenTient)
* Kristal artifact verification or publication (Daat)
* Distribution/activation (Konnaxion)
* Governance approvals (Orgo), except to request them via work items
## Inputs
* **Mandate Bundle** (kOA artifact) — goals, constraints, required channels/environments, approvals state
* **Input Snapshot References** (from Chokmah) — opaque references to deterministic input sets
* **Policy Configuration** (kOA profile) — which policy families must be enforced downstream
* **System Capabilities** — supported compilers/runtimes, target environment matrix, feature flags
## Outputs
* **Blueprint** (kOA artifact)
* Plan steps with explicit stage boundaries
* Declared evidence/anchor requirements per step
* Declared policy gates (by name), not their internal Kristal details
* Expected Kristal artifact types to be produced (by type only)
* **Orgo Work Items** (optional)
* Requests for missing inputs, approvals, or exception handling
* **Diagnostics**
* Reasons for blocked planning (missing inputs, conflicting constraints)
## Blueprint structure (kOA-level)
A Blueprint is an ordered set of steps. Each step must include:
* `step_id` (stable)
* `owner_node` (which node executes it)
* `inputs` (artifact references by type + ID)
* `outputs` (artifact references by type)
* `guards` (preconditions; including “must be Kristal-verified” where applicable)
* `policy_gates` (named gates to be enforced by downstream nodes)
* `determinism_constraints` (e.g., pinned toolchain required, canonicalization required)
* `rollback_plan` (required when the plan targets activation channels)
Binah may include optional metadata for scheduling or parallelization, but it must not introduce nondeterministic dependencies.
## Guards
Binah must refuse to emit a Blueprint if any of the following are true:
* Mandate is missing required approvals for the requested channel(s)
* Required input snapshot references are missing or not pinned
* The plan would require producing Kristal artifacts without a declared path through Daat
* The plan includes steps that depend on non-pinned tools, non-versioned policies, or “live” data without snapshot identity
* Target environments include incompatible runtime constraints without a mitigation/rollback plan
## Failure modes
* **F1 Input acquisition failures:** missing snapshot references, input identity ambiguity
* **F2 Planning failures:** inconsistent constraints, incomplete step guards, missing rollback plan
* **F4 Determinism failures (prevention):** plan depends on unpinned toolchain or nondeterministic execution
* **F6 Activation risk:** plan targets rollout without rollback path
(See `10-system/failure-modes.md`.)
## Operational notes
* **Idempotent planning:** If Mandate + Snapshot References + Profile are unchanged, Binah must emit the same Blueprint (or a blueprint with a stable semantic hash).
* **Change control:** Any change in inputs, policies, or target matrix requires a new Blueprint revision.
* **Traceability:** Blueprint step outputs must be traceable to their inputs via references captured downstream (Build/Release records).
## Interfaces with other nodes
* **Keter → Binah:** mandate content and governance constraints
* **Chokmah → Binah:** snapshot references for deterministic inputs
* **Binah → SenTient:** resolution steps and evidence requirements
* **Binah → Architect:** render strategy and deterministic constraints
* **Binah → Compiler:** toolchain pinning and packaging targets
* **Binah → Daat:** expected Kristal artifacts and publish/verification intent
* **Binah → Orgo:** approvals and remediation work items
================================================================================================
FILE: docs_technical/20-nodes/chesed-konnaxion.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: b59e0ab977d66c659588202c6e399e557cf47dda88f5bf2cde71d21db5ae0b41
CONTENT_BYTES: 3656
================================================================================================
# Chesed: Konnaxion
**Role:** Connectivity + distribution + offline platform boundary.
**Primary responsibility:** safely deliver **verified, pinned** knowledge packs to products and services, and provide deterministic access patterns without mutating canonical truth.
## Responsibilities
* Fetch, cache, and serve **Runtime Packs** and related indexes/channels.
* Verify pack integrity **fail-closed** before activation (signatures, hashes, compatibility).
* Activate packs atomically and support deterministic rollback to a last-known-good or pinned version.
* Provide local query and retrieval interfaces over active packs (offline-first).
* Enforce distribution policy (channels, cohorting, pinning, revocation, downgrade prevention).
* Emit telemetry and operational signals (activation outcomes, verification failures, cache health).
## Inputs
* Release intent / rollout directives (channel, cohort, pin rules).
* Candidate pack artifacts and metadata (manifest + payloads + signatures).
* Verification keys and trust policy (key sets, allowed signers, required checks).
* Compatibility policy (supported schema versions, feature flags, migration rules).
## Outputs
* Active pack selection (the currently activated pack ID / version).
* Activation / rollback records (local operational evidence).
* Verification reports (why a candidate was rejected).
* Telemetry signals for Orgo (distribution health, failures, drift).
## Invariants
* **Fail-closed verification:** no activation unless all required checks pass.
* **Atomic activation:** a pack becomes active in one switch; partial activation is impossible.
* **Deterministic rollback:** given the same triggers and state history, rollback target selection is deterministic.
* **Downgrade prevention:** policy can forbid activating older/unsafe versions even if signatures are valid.
* **No truth mutation:** Konnaxion never edits canonical truth; it only distributes and serves verified artifacts.
* **Pinned determinism:** the same active pack + same query yields the same results (within the defined query interface).
## Failure modes
* Network/source unavailable (cannot fetch updates)
* Verification failure (signature mismatch, hash mismatch, untrusted signer)
* Compatibility failure (unsupported schema/features)
* Cache corruption / partial download
* Rollback loops (repeated activation failures)
* Key rotation mishandling (valid pack rejected due to stale trust set)
## Observability
* Pack fetch latency and failure rate
* Verification pass/fail counts by reason
* Activation success rate and time-to-activate
* Rollback frequency and triggers
* Cache utilization, corruption detection, disk pressure
* “Active pack drift” (unexpected active pack changes)
## Interfaces
### Upstream
* Distribution channels / artifact stores
* Orgo release controller (rollout directives)
* Key management service (trusted signers, revocations)
### Downstream
* Product runtimes (offline query, lookup, retrieval)
* UI services (navigation/search backed by pack indexes)
* Audit/telemetry pipeline (activation + verification evidence)
## Minimal contract (conceptual)
Konnaxion must expose:
* `get_active_pack()` → active pack identifier + metadata
* `activate(pack_ref, policy)` → success/failure + reasons
* `rollback(target_policy)` → selected target + evidence
* `query(interface, params)` → deterministic results over active pack
* `health()` → cache + verification + storage status
## Related docs
* `docs/40-integration/kristal-v4/koa-profile.md`
* `docs/50-operations/releases.md`
* `docs/50-operations/rollback.md`
* `docs/30-artifacts/konnaxion-state.md`
================================================================================================
FILE: docs_technical/20-nodes/chokmah-inputs.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: aa44f685a4115b641fc7c7df3563699b1f0d0500a92685b0a56c508316ebc0c3
CONTENT_BYTES: 6535
================================================================================================
# Chokmah — Inputs (Ingest + Provenance Boundary)
**File:** `docs/20-nodes/chokmah-inputs.md`
**Normative scope:** kOA node behavior and interfaces.
**Non-normative:** Kristal artifact schemas (external).
---
## 1) Purpose
Chokmah is the ecosystem’s **ingest and provenance boundary**. It turns raw external inputs into **immutable, content-addressed snapshots** that downstream stages can reference reproducibly (extraction, resolution, validation, compilation).
Chokmah does **not** decide truth. It guarantees only that **“what we saw”** is captured, auditable, and replayable.
---
## 2) Responsibilities
Chokmah MUST:
- Ingest raw materials from configured sources (files, feeds, APIs, user submissions).
- Produce **immutable Input Snapshots** stored in a content-addressed store.
- Capture and persist **provenance** for every snapshot (source identity, retrieval time, auth/context, routing tags, policy tags).
- Enforce confidentiality and access control on ingested materials (PII, restricted sources), including encryption at rest when required.
- Provide **idempotent ingestion** (same bytes → same snapshot ref; safe retries).
- Emit a deterministic, machine-readable **input set** reference for downstream builds (recorded in Orgo Build Record).
- Emit deterministic ingestion results (success/warnings/failures) with stable error codes.
Chokmah MAY:
- Normalize **transport/container** format **without changing meaning** (e.g., decoding, decompressing, charset normalization), **only** when:
- the transform is deterministic, and
- the transform is recorded explicitly in the snapshot manifest (tool id/version + steps).
Chokmah MUST NOT:
- Interpret, enrich, or “fix” content in a way that changes meaning without recording it explicitly as a derived artifact.
- Generate or alter canonical truth artifacts.
---
## 3) Interfaces
### 3.1 Inputs to Chokmah
- **Ingest Request** (from Orgo or an ingestion orchestrator)
- Source descriptors (URI, connector type, credentials reference)
- Expected content type and size (if known)
- Confidentiality classification / handling constraints
- Applicable mandate/policy tags (from Keter)
- Optional: retention/quarantine directives
### 3.2 Outputs from Chokmah
- **Input Snapshot Set**
- One or more snapshot refs (content-addressed)
- **Snapshot Manifest**
- Deterministic mapping from snapshot ref → provenance + acquisition metadata
- Ingestion policy version/ref applied
- Transformation steps (if any), with deterministic tooling identifiers
- Integrity metadata (hashes/checksums)
- **Ingest Receipt**
- Snapshot refs created/confirmed
- Errors and partial results (if any)
- Retrieval diagnostics pointers
- Optional: **Quarantine Report**
- When content is blocked/sanitized/quarantined per policy
> Field-level schemas for kOA-owned operational artifacts live under `docs/30-artifacts/`. If you maintain a dedicated Input Snapshot / Snapshot Manifest schema, treat it as kOA-owned.
---
## 4) Snapshot identity model
- Snapshot identity is **content-addressed**:
- Same payload bytes MUST yield the same snapshot reference.
- **Metadata changes MUST NOT change the payload reference**; they belong in snapshot metadata/manifest records.
- If the ingest source is mutable (e.g., `latest.json`), Chokmah MUST still store the retrieved bytes as an immutable snapshot and record the retrieval context.
---
## 5) Invariants (normative)
1. **Immutability**
- Once a snapshot reference is issued, the referenced bytes MUST never change.
2. **Content addressing**
- Snapshot references MUST be derived from content (and any explicitly defined deterministic packaging rules for stored bytes).
3. **Complete provenance**
- Every snapshot MUST have provenance sufficient for audit and reproduction:
- where it came from
- when it was fetched
- under what policy/authority context
- what transformations were applied (ideally none)
4. **Confidentiality enforcement**
- Restricted snapshots MUST be encrypted at rest and access-controlled.
- Downstream stages SHOULD receive only references unless explicitly authorized to fetch bytes.
5. **Idempotent ingestion**
- Re-ingesting the same payload MUST return the same reference.
- Retries MUST NOT create duplicate “distinct” snapshots for identical bytes.
6. **Build reproducibility**
- Orgo MUST be able to bind a build to a stable set of snapshot refs (“input set”).
- Downstream compilation MUST NOT depend on live sources—only recorded snapshot refs.
7. **No hidden enrichment**
- Ingestion MUST NOT introduce new facts; it only captures and packages input material.
---
## 6) Error handling and failure modes
Chokmah MUST fail closed when it cannot guarantee correctness.
Common failures:
- Source unreachable / authentication failure
- Partial download or truncated payload
- Hash mismatch during streaming verification
- Policy violation (attempt to ingest disallowed source / classification mismatch)
- Quarantine triggered (malware, sensitive data, unsafe content)
- Unsupported format / decoding failure
- Storage failure (cannot commit snapshot immutably)
- Malformed content violating declared type constraints (record as ingest error; do not coerce)
Chokmah SHOULD return structured errors stable across minor versions:
- `code` (stable)
- `message` (human)
- `diagnostics_ref` (pointer)
---
## 7) Observability
Chokmah SHOULD emit:
### 7.1 Metrics
- ingest requests, successes/failures
- bytes ingested, throughput
- latency per connector/source type
- retry counts and idempotency hits
- rejection/quarantine rates and reasons
### 7.2 Logs (structured)
- request id, source descriptor hash, snapshot refs
- policy/classification decisions
- failure codes and diagnostics pointers
### 7.3 Audit events
- snapshot created/confirmed
- access grants/denials
- retention/expiration actions
---
## 8) Security and trust boundaries
- Chokmah touches untrusted external data; treat all inputs as untrusted until committed immutably.
- Connector credentials MUST be handled via a secure secret mechanism; never embedded in artifacts.
- Confidentiality policy MUST be enforced consistently with Keter mandate and kOA operations policy.
---
## 9) Related docs
- `docs/10-system/trust-boundaries.md`
- `docs/50-operations/pipeline.md`
- `docs/30-artifacts/build-record.md`
- `docs/30-artifacts/mandate-bundle.md`
- `docs/40-integration/kristal-v4/contract-pointers.md`
================================================================================================
FILE: docs_technical/20-nodes/daat-kristal-bridge.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: d81e7d298a5929762afaf3de6f59f9bf37c3c7229276eb9eb30551b508da0c0b
CONTENT_BYTES: 3898
================================================================================================
# Da’at: Kristal Bridge
**Role:** Boundary adapter between the kOA ecosystem and the Kristal truth system.
**Primary responsibility:** ensure kOA produces/consumes **Kristal v4–conformant artifacts** without re-specifying Kristal contracts inside kOA docs.
This node is the *integration surface*, not the Kristal spec.
## Responsibilities
* Pin the Kristal dependency version used by kOA (tag/commit) and keep it auditable.
* Route kOA pipeline stage outputs into Kristal compilation inputs (Claim-IR → Resolved Claim-IR → Validation results → compile request).
* Enforce that any produced Kristal artifacts (Exchange, Runtime Pack, their manifests) are **schema-valid** against pinned Kristal schemas.
* Maintain compatibility rules between kOA operational records (build/release records) and Kristal artifacts (IDs, references, provenance).
* Provide deterministic “artifact handoff” semantics:
* what gets passed to Kristal
* what comes back
* what is recorded by Orgo
## Inputs
* Pre-truth artifacts from upstream stages:
* Input Snapshot refs + provenance
* Claim proposals (Claim-IR)
* Resolved claims (Resolved Claim-IR)
* Validation report (pass/fail + diagnostics)
* kOA policy bundles that influence compilation choices (as *parameters*, not schema changes)
* Pinned Kristal version reference (commit/tag) and schema locations
## Outputs
* Kristal canonical artifacts (produced by Kristal compiler):
* Exchange artifact + manifest
* Runtime Pack artifact + manifest
* kOA operational records updated with content-addressed references:
* build record output refs
* release record refs (if release proceeds)
* Compatibility/verification evidence:
* schema validation results
* canonicalization/profile checks
* signer/trust assertions (if applicable)
## Invariants
* **Kristal is normative:** any field-level or schema-level truth about Exchange/Runtime Pack comes from the pinned Kristal v4 spec, not kOA docs.
* **No compile on fail:** if validation fails, compilation is not invoked and no new canonical artifacts are published.
* **Schema conformance:** the bridge must validate produced artifacts against pinned Kristal schemas before kOA considers them publishable/distributable.
* **Deterministic handoff:** given the same inputs + pinned Kristal version + pinned policies, the handoff request and recorded references are reproducible.
* **Stable referencing:** kOA records references to Kristal artifacts in a consistent, content-addressed way (no ad hoc IDs in place of canonical ones).
## Failure modes
* Kristal dependency not pinned / ambiguous version
* Schema mismatch between produced artifact and pinned schema
* Drift: kOA passes parameters not supported by the pinned Kristal compiler
* Non-determinism detected (toolchain/version drift)
* Partial publication (attempt to publish Exchange without corresponding recorded evidence)
## Observability
* Compile invocation counts, latency, and failure rate
* Schema validation pass/fail counts by artifact type
* “Pinned dependency drift” alerts (unexpected Kristal version changes)
* Determinism checks (same inputs → same artifact references) sampling
* Publication outcomes (published, rejected, quarantined)
## Interfaces
### Upstream
* Orgo (pipeline orchestrator; provides stage outputs and gating decisions)
### Downstream
* Kristal compiler toolchain (pinned version)
* Artifact store / registry (where Exchange and Packs are published)
* Konnaxion distribution (consumes Runtime Packs after verification)
## What lives elsewhere (by design)
* Normative Kristal artifact definitions and schemas: `docs/40-integration/kristal-v4/contract-pointers.md`
* kOA’s chosen profile / operational constraints: `docs/40-integration/kristal-v4/koa-profile.md`
* kOA conformance tests for Kristal artifacts: `docs/40-integration/kristal-v4/conformance.md`
================================================================================================
FILE: docs_technical/20-nodes/gevurah-orgo.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: ba76111a4db68714dd0c63737270028118a4bc20e8e391984170dc36d4e2ecf5
CONTENT_BYTES: 7902
================================================================================================
# Gevurah — Orgo (Governance + Control Plane)
## Purpose
**Orgo** is the ecosystem’s **governance and control plane**. It enforces the canonical stage spine (ingest → extract → resolve → validate → compile → distribute → render/execute), applies deterministic gates, and records an auditable trail of what happened and why.
Orgo is the owner of **kOA-native operational artifacts** (Cases, Tasks, Build Records, Release Records) and the authority that decides whether downstream steps are allowed to proceed.
---
## Responsibilities
### 1) Stage orchestration (normative)
Orgo MUST:
- Orchestrate the pipeline stages and enforce **stage order**.
- Provide idempotent execution semantics for each stage (retries must not create ambiguous state).
- Ensure each stage runs with explicit inputs, pinned configs, and recorded provenance.
### 2) Deterministic gating (normative)
Orgo MUST:
- Enforce **“no compile on fail”**: compilation and release actions are prohibited unless validation is passing.
- Enforce policy/blueprint selection as an explicit, recorded decision per build.
- Block downstream activation/release when integrity checks fail (**fail-closed**).
Kristal contract details are external; see:
- `docs/40-integration/kristal-v4/contract-pointers.md`
- `docs/40-integration/kristal-v4/conformance.md`
### 3) Governance workflow (cases/tasks) (normative)
Orgo MUST:
- Create, update, and close **Orgo Cases** and **Orgo Tasks**.
- Enforce task lifecycle rules (terminal states, reopen rules, ownership, priority/severity/visibility).
- Route work deterministically based on taxonomy and policy.
### 4) Reproducibility and audit (normative)
Orgo MUST:
- Emit a **Build Record** that references stage outputs and decisions.
- Emit a **Release Record** that ties a build to distribution intent (channels/cohorts/pins), and tracks rollout status.
- Store immutable audit logs for gate outcomes and changes in governance state.
### 5) Operator experience (recommended)
Orgo SHOULD:
- Provide a single operator view for: current build state, failures, validation outcomes, active releases, and rollback status.
- Provide tooling hooks to regenerate artifacts deterministically given the recorded inputs/configs.
---
## Inputs
### Upstream signals
- Ingest/provenance signals from Inputs (Chokmah)
- Blueprint/policy bundles from Mandate (Keter) and Blueprint (Binah)
- Resolution outputs from SenTient (Tiferet)
- Verification/activation telemetry from Konnaxion (Chesed)
- Execution telemetry (if present) from SwarmCraft
### Operator actions
- Create/triage/resolve cases and tasks
- Approve/pin/revoke releases
- Trigger rebuilds and rollbacks (within policy constraints)
---
## Outputs (Artifacts)
### kOA-native (owned by Orgo)
- `docs/30-artifacts/orgo-case.md`
- `docs/30-artifacts/orgo-task.md`
- `docs/30-artifacts/build-record.md`
- `docs/30-artifacts/release-record.md`
Schemas:
- `docs/30-artifacts/schemas/orgo-case.schema.json`
- `docs/30-artifacts/schemas/orgo-task.schema.json`
- `docs/30-artifacts/schemas/build-record.schema.json`
- `docs/30-artifacts/schemas/release-record.schema.json`
### Externally specified (referenced by Orgo; not defined here)
Orgo records and references Kristal artifacts (Exchange, Runtime Pack, Validation Report, etc.) but does not redefine them.
See `docs/40-integration/kristal-v4/contract-pointers.md`.
---
## Interfaces
### Control-plane API (recommended shape)
- Case/Task CRUD + lifecycle transitions
- Build orchestration endpoints (start/stop/retry stage, fetch build status)
- Release orchestration endpoints (create release intent, promote, pin, revoke, rollback)
- Read-only audit endpoints (gate decisions, stage timeline, artifact refs)
### Event stream (recommended)
Orgo SHOULD emit events for:
- Stage start/finish/fail
- Gate pass/fail (with stable reason codes)
- Case/Task lifecycle transitions
- Release intent changes and rollout milestones
- Rollback triggers and completion
### Storage (normative)
Orgo MUST persist:
- Case/Task state and history
- Build Records and Release Records
- Gate outcomes and operator actions (append-only or versioned history)
---
## Deterministic gates
Orgo’s gates are **policy-driven** but must be **deterministic** in outcome given the same inputs/configuration.
### Gate categories
1) **Schema/contract gates**
- Validate kOA-native artifacts against kOA schemas.
- Validate Kristal artifacts against pinned Kristal v4 schemas (external).
2) **Stage dependency gates**
- A stage may only run if its dependencies are complete and valid.
- Compilation/release prohibited unless validation passes.
3) **Integrity gates**
- Downstream distribution/activation MUST be fail-closed.
- Rollback MUST be deterministic given the same triggers and policy.
---
## Invariants (must always hold)
1) **No compile on fail**
- If validation fails, Orgo must not allow compilation, release intent, or activation.
2) **Explicit decisions are recorded**
- Policy/blueprint selection and any override MUST be recorded in the Build Record / Release Record.
3) **Auditability**
- Every terminal failure includes a stable reason code and traceable references to inputs and stage outputs.
4) **Idempotent stage execution**
- Retries do not create ambiguous dual outputs; Orgo records which output is authoritative for the build.
5) **Fail-closed rollout**
- Any verification/compatibility uncertainty blocks activation until resolved or explicitly overridden by policy (and recorded).
---
## Failure modes
### Pipeline failures
- Upstream input provenance missing or inconsistent
- Extract/resolve jobs produce invalid outputs
- Validation fails (must block compile/release)
- External dependency unavailable (artifact store, runner pool, key service)
### Governance failures
- Conflicting manual actions (double-approvals, invalid transitions)
- Partial updates causing inconsistent case/task state
- Release intent drift from actual rollout state
### Safety failures (critical)
- Attempted activation without verification
- Bypassing deterministic gates
- Unlogged administrative changes
---
## Observability
### Metrics (minimum)
- Build throughput, stage durations, queue depth
- Validation pass rate, top failure reasons
- Release success rate, time-to-rollout, rollback frequency
- Case/task lead time, backlog size, SLA compliance
### Logs (minimum)
- Gate decisions with reason codes and referenced artifact IDs
- Operator actions (who/what/when) with before/after state
### Traces (recommended)
- Correlate a build ID across all stage jobs and downstream distribution events
- Correlate a release ID to activation events, rollback events, and client health
---
## Security & access control
Orgo MUST enforce:
- Strong authentication for operator actions
- Authorization by role (operator, approver, auditor, automation)
- Immutable/auditable logging for privileged actions
- Secret isolation (keys used for signing/verifying are never exposed to untrusted jobs)
Orgo SHOULD:
- Support break-glass procedures with mandatory audit logging
- Separate duties for “approve release” vs “execute rollback” if required by policy
---
## Versioning & compatibility
- kOA-native artifact schemas evolve under `docs/90-reference/adr/`.
- Kristal artifact compatibility is governed by the pinned Kristal v4 dependency and the kOA profile:
- `docs/40-integration/kristal-v4/pinned-dependency.md`
- `docs/40-integration/kristal-v4/koa-profile.md`
- `docs/40-integration/kristal-v4/legacy-compat.md`
---
## Links
- System gates: `docs/10-system/trust-boundaries.md`, `docs/10-system/determinism.md`
- Operations: `docs/50-operations/pipeline.md`, `docs/50-operations/releases.md`, `docs/50-operations/rollback.md`
- kOA-native artifacts: `docs/30-artifacts/`
- Kristal integration: `docs/40-integration/kristal-v4/`
================================================================================================
FILE: docs_technical/20-nodes/hod-architect-render.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: b02124d0d7c85a983d3b18401b5bb902f1bb0d28d59e3ebcf498d2d4cea6352e
CONTENT_BYTES: 6867
================================================================================================
# Hod: Architect-Render (Deterministic Articulation)
**Normative for kOA:** YES (node specification)
**External normative references:** Kristal v4 (pinned) for Kristal-facing artifacts/contracts referenced by this node (see `docs/40-integration/kristal-v4/contract-pointers.md`)
## Purpose
Architect-Render turns **validated knowledge** into **user-consumable outputs** (text or structured blocks) under strict rules:
- deterministic output
- **no new facts**
- complete trace coverage (`trace_map`)
- explicit ambiguity handling
- deterministic refusal/error behavior
It is the ecosystem’s articulation layer: formatting and composing, not deciding truth, not executing work.
---
## Non-responsibilities
Architect-Render:
- does not write to Kristal Exchange (canonical truth) or mutate truth artifacts
- does not validate or canonicalize (upstream gate and compile)
- does not execute tasks (SwarmCraft)
- does not decide strategy/plan (Architect-Strategy)
- does not “enrich facts” from the internet or probabilistic sources as truth
---
## Contract boundaries
### Upstream producers
Architect-Render accepts validated bundles produced by:
- Runtime Pack query systems (via Konnaxion/Malkuth), or
- Exchange-derived verified query systems
### Downstream consumers
- Konnaxion UI/navigation surfaces
- Systems persisting render bundles for auditability/publication
- Optional: EkoH surfaces (when presenting ledger-derived signals, without mutating canon)
---
## Responsibilities
### R1 — Accept only validated inputs
Architect-Render MUST operate as a pure function over validated inputs and MUST reject inputs that cannot be proven to derive from a specific Exchange/Pack reference.
### R2 — Deterministic rendering
Given identical validated input bytes + template/profile id+version + language + rendering parameters, the output MUST be identical (including `trace_map`), modulo explicitly allowed non-content metadata excluded by policy.
### R3 — No new facts
Architect-Render MUST NOT introduce factual assertions not supported by validated inputs. It MUST NOT “fill gaps” with plausible guesses.
### R4 — Trace coverage (accountability)
Architect-Render MUST produce a render bundle that includes `trace_map` coverage for factual assertions. If support is missing, it MUST omit, explicitly mark uncertainty (only if upstream uncertainty exists), or refuse deterministically.
### R5 — Ambiguity preservation
If inputs contain unresolved ambiguity, Architect-Render MUST either render ambiguity explicitly or refuse to render the ambiguous claim as a fact. It MUST NOT silently disambiguate unless inputs explicitly declare the resolved selection.
### R6 — Deterministic refusal/error codes
Architect-Render MUST implement stable refusal/error codes and return:
- `status = "ok" | "refused" | "error"`
- `code` (stable string)
- `message` (human-readable)
- optional structured `details`
Minimum refusal/error codes include:
- `UNVERIFIED_INPUT`
- `MISSING_TRACE_IDS`
- `AMBIGUOUS_INPUT`
- `UNSUPPORTED_RENDER_KIND`
- `PROJECTION_MISMATCH`
- `POLICY_VIOLATION_NEW_FACT_RISK`
### R7 — Multilingual constraints
Architect-Render MAY translate labels and explanatory text, but MUST NOT alter factual content. Locale formatting is permitted only if meaning does not change and normalized values remain traceable.
### R8 — Offline correctness / security
Architect-Render MUST NOT require network calls to produce correct factual output. If network calls are used for non-factual assets, they MUST NOT affect factual assertions.
---
## Interfaces
### Inputs (required, conceptual)
Architect-Render MUST accept one of:
1) **Runtime Pack query bundle** (validated, ordered results; references the pack and query contract), or
2) **Exchange-derived verified query bundle** (validated derivation proof + deterministic query spec).
Inputs MUST include stable identifiers sufficient for traceability:
- Exchange/Pack reference
- stable statement identifiers and evidence pointers (preferred `statement_id`)
A separate rendering request MUST declare:
- render kind (article/snippet/summary/qa/card)
- language
- template/profile identifier + version
- constraints (policy-bound; must not change factual content)
### Outputs (required, conceptual)
Architect-Render MUST output a **Render Bundle** as the only permitted boundary artifact.
A Render Bundle MUST include:
- rendered output (text or structured blocks)
- `trace_map` (machine-readable)
- `render_metadata`
Trace map coverage rules:
- every factual statement must have at least one support pointer
- if unsupported: omit, mark uncertainty (only if upstream uncertainty exists), or refuse deterministically
---
## Invariants (must hold)
- Determinism: same validated inputs + same template/profile + same params ⇒ identical output and identical `trace_map`.
- Truth fidelity: no new facts; no external factual enrichment.
- Coverage: every factual statement is supported in `trace_map`.
- Ambiguity: rendered explicitly or refused; never silently coerced.
- Projection consistency: if a projection is declared, render only from that projection and label output metadata.
- Input integrity: reject unverified/untraceable inputs.
- Offline correctness: no network dependency for factual correctness.
---
## Failure modes and required behavior
Architect-Render MUST fail deterministically with stable codes when:
- inputs are unverified / provenance cannot be proven (`UNVERIFIED_INPUT`)
- stable statement/evidence identifiers are missing (`MISSING_TRACE_IDS`)
- ambiguity cannot be rendered under requested constraints (`AMBIGUOUS_INPUT`)
- render kind is unsupported (`UNSUPPORTED_RENDER_KIND`)
- projection constraints are violated (`PROJECTION_MISMATCH`)
- requested output would introduce an unsupported fact (`POLICY_VIOLATION_NEW_FACT_RISK`)
---
## Observability (minimum)
Architect-Render MUST emit:
- Exchange/Pack reference used
- template/profile id + version
- render kind, language, projection
- determinism mode
- status + refusal/error code (if not `ok`)
- trace coverage metrics (e.g., assertions rendered, omitted, marked uncertain, refused)
Recommended metrics:
- deterministic golden-test pass rate (per template/profile)
- refusal rate by code
- coverage gap rate (unsupported assertions encountered)
- latency by render kind and template/profile
---
## Conformance tests (required)
A conformant Architect-Render MUST provide tests for:
- deterministic rendering (golden outputs + golden `trace_map`)
- “no new facts” enforcement (adversarial templates/prompts must not yield unsupported assertions)
- trace coverage enforcement (missing supports ⇒ omit/uncertain/refuse deterministically)
- refusal/error code stability for the minimum code set
- offline correctness (network-disabled run produces identical factual output)
================================================================================================
FILE: docs_technical/20-nodes/index.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 70a25dc0f56497573dff5cb9041282c59a58e15f1dd7f506478dea24b510a0e6
CONTENT_BYTES: 3097
================================================================================================
# Nodes
**Normative for kOA:** YES
**External normative reference:** Kristal v4 (pinned)
This section defines the kOA node model: each node has a clear responsibility, declared inputs/outputs (at the artifact-type level), and explicit failure modes. Node pages are **kOA interface specs**, not Kristal artifact specs.
Kristal artifacts (Exchange / Runtime Pack / Render Bundle and their schemas) are referenced via `40-integration/kristal-v4/` and must not be duplicated here.
## How to read a node spec
Each node page follows the same structure:
1. **Responsibility**
* What the node owns (and what it does not own)
2. **Inputs**
* Artifact types and upstream dependencies (no Kristal field-level contracts)
3. **Outputs**
* Artifact types, events, and side effects
4. **Guards**
* Preconditions and gates (including “must be Kristal-verified” where applicable)
5. **Failure modes**
* Node-local failures and propagation expectations (see `10-system/failure-modes.md`)
6. **Operational notes**
* Rollout/rollback, observability requirements, idempotency guarantees
## Node topology
High-level flow (conceptual):
* **Mandate** → **Inputs** → **Blueprint** → **Resolution** → **Verification** → **Compile/Pack** → **Distribute/Activate** → **Runtime**
* Truth boundary enforcement is applied wherever Kristal artifacts are consumed or produced.
## Node index
* `keter-mandate.md` — mandate definition, governance entrypoint
* `chokmah-inputs.md` — input acquisition and snapshotting
* `binah-blueprint.md` — blueprint formation and planning
* `tiferet-sentient.md` — resolution, grounding, and policy gating (content-level)
* `netzach-architect-strategy.md` — strategy orchestration (non-render)
* `hod-architect-render.md` — deterministic render planning (no new facts)
* `yesod-compiler.md` — compilation and packaging (deterministic toolchain)
* `daat-kristal-bridge.md` — Kristal boundary integration (verify/emit/publish)
* `chesed-konnaxion.md` — distribution, activation, rollback, channel management
* `gevurah-orgo.md` — workflow control, approvals, remediation tracking
* `malkuth-runtime.md` — runtime enforcement, safe modes, telemetry
## Common contracts (kOA-side only)
Nodes must satisfy these kOA-level requirements:
* **Explicit inputs/outputs:** no hidden dependencies
* **Idempotency:** re-running with identical declared inputs must be safe
* **Fail-closed behavior:** do not proceed when guards fail
* **Auditability:** emit sufficient records to reconstruct decisions and deployments
* **No silent mutation of canon:** feedback becomes governed work (Orgo), not implicit edits
## Kristal integration rule
If a node consumes or produces Kristal artifacts, the node page must:
* reference the pinned Kristal v4 dependency (`40-integration/kristal-v4/pinned-dependency.md`)
* reference the kOA profile (`40-integration/kristal-v4/koa-profile.md`)
* reference conformance requirements (`40-integration/kristal-v4/conformance.md`)
Node pages must **not** inline Kristal schemas or field lists.
================================================================================================
FILE: docs_technical/20-nodes/keter-mandate.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 2c3fd3886bb9ac3e09b1f377d0669a9150761be8a7b6bb1de1573047dd53360b
CONTENT_BYTES: 3741
================================================================================================
# Keter: Mandate (Governance Source)
**Normative for kOA:** YES
**External normative references:** Kristal v4 (pinned) for Kristal artifact contracts; none for Mandate Bundle (kOA-owned)
## Purpose
**Keter (Mandate)** is the ecosystem’s **governance source**: it defines the mission, scope, constraints, and enforceable policy bundles that guide the rest of the system. Keter does not produce canonical truth artifacts; it produces **governance artifacts** that constrain how truth is produced, distributed, rendered, and operationalized.
Keter’s output is consumed by Orgo (pipeline governance), Kristal compilation gates, Konnaxion distribution policy, and Architect behavior policies.
---
## Responsibilities
Keter MUST:
- Define and publish the active **Mandate Bundle** for an organization (mission + constraints + policies).
- Version mandate and policy changes; preserve history (no silent mutation).
- Provide unambiguous policy selections usable by Orgo/Kristal/Konnaxion/Architect.
- Declare enforcement levels (MUST/SHOULD/MAY) and scope of each policy rule.
Keter MUST NOT:
- Directly alter canonical truth artifacts (Exchange) or derived distribution artifacts (Runtime Packs).
- Override deterministic gates at runtime without a versioned mandate/policy change.
---
## Inputs
- Organizational objectives and constraints
- Regulatory/ethics requirements
- Risk appetite and operational SLOs
- Approved policy templates
---
## Outputs
### Primary output: Mandate Bundle (kOA-owned)
A Mandate Bundle is a versioned, auditable container that includes:
- mandate identity and descriptive fields
- constraints and objectives
- one or more policy documents / rule sets
- optional signatures for authenticity
Schema: `docs/30-artifacts/schemas/mandate-bundle.schema.json`
---
## Interfaces
### 1) Retrieve current mandate
- `GET /mandate/current` → Mandate Bundle
### 2) Retrieve by bundle id
- `GET /mandate/{bundle_id}` → Mandate Bundle
### 3) Policy selection interface (to Orgo)
Orgo selects policies by stable identifiers from the Mandate Bundle:
- `policy_id`
- `version`
- optional parameters (must be recorded if used)
Orgo MUST record the selected policy set in operational records (Build/Release), and treat those selections as part of the reproducibility surface.
---
## Invariants (Non-negotiable)
1) **Versioned governance**
All mandate/policy changes must produce a new bundle version (immutable history).
2) **Deterministic policy interpretation**
Given the same Mandate Bundle and policy selection, downstream components must interpret policy rules deterministically.
3) **No runtime overrides**
Runtime behavior changes require a mandate/policy update; ad-hoc overrides are forbidden for anything affecting truth boundary, compile gates, activation gates, or rendering trace requirements.
4) **Scope clarity**
Policies must declare where they apply (stages, artifacts, components) and how they are enforced.
---
## Failure Modes
- Missing Mandate Bundle (system cannot start governed pipeline safely)
- Ambiguous/conflicting policy rules without deterministic tie-breaking
- Unauthorized mandate updates (signature or access control failure)
- Breaking policy changes without compatibility plan
---
## Observability
Keter MUST emit:
- current mandate bundle id/version
- change events (bundle published/rotated)
- policy selection usage metrics (which policies are active downstream)
- authorization/verification failures
---
## Security
- Mandate Bundle publishing must require strong authentication and authorization.
- Bundles should be signed (recommended) and verified by consumers in strict environments.
- Do not embed secrets in mandate/policy artifacts.
---
================================================================================================
FILE: docs_technical/20-nodes/malkuth-runtime.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: b7df294af537ac05519d3e9615119696bb1f157e8eee15a15ea746b1b5476017
CONTENT_BYTES: 7170
================================================================================================
# 10 — Malkuth: Runtime (Offline Serving + Execution Substrate)
## Purpose
**Malkuth Runtime** is the ecosystem’s **local, offline-capable serving and execution substrate**. It loads the **active Runtime Pack** (as activated by Konnaxion), exposes deterministic query/lookup interfaces, and executes pack-defined routines in a controlled environment.
Malkuth is **downstream of the truth boundary**. It must not create or mutate canonical truth. It only serves and operationalizes **derived artifacts**.
---
## Responsibilities
Malkuth MUST:
- Load and serve the **active Runtime Pack** selected by Konnaxion.
- Provide deterministic query/lookup over pack payloads (indexes, embeddings, tables, rules, templates).
- Execute pack-defined routines (if present) with pinned dependencies and stable behavior.
- Enforce isolation and resource controls (sandboxing, quotas, timeouts).
- Emit structured telemetry about queries/executions (without mutating canon).
- Support offline operation and stable behavior under network absence.
Malkuth MUST NOT:
- Fetch non-pinned external data during deterministic operations (unless explicitly configured as a non-deterministic mode and recorded upstream).
- Modify Exchange or pack payloads in place.
- Activate or roll back packs (Konnaxion owns activation).
---
## Inputs
### Primary input
- **Active Runtime Pack** (payload + manifest), provided via Konnaxion’s activation mechanism.
### Secondary inputs (optional)
- Local runtime configuration (feature flags, resource budgets, allowed interfaces).
- Local policy overlays (only if explicitly permitted and recorded; must not affect canonical IDs).
---
## Outputs
- Query results (deterministic, traceable to pack version and query inputs).
- Execution results (task outputs, logs, metrics; optionally artifacts for Orgo ingestion).
- Telemetry events to Orgo (or local store) for observability and governance.
---
## Interfaces
### 1) Pack mount interface (from Konnaxion)
Konnaxion provides Malkuth with:
- Active pack identity (pack_id / version)
- Verified payload location(s)
- Activation epoch or activation record reference
- Optional compatibility metadata (runtime ABI level)
Malkuth MUST refuse to start if the active pack is missing or fails runtime compatibility.
### 2) Query interface (to consumers)
Consumers (Architect-Render, local apps, SwarmCraft, tooling) call:
- `GET /runtime/info` → active pack identity + runtime version
- `POST /runtime/query` → deterministic queries over pack indexes/tables
- `POST /runtime/lookup` → point lookups by key/entity id
- `POST /runtime/search` → deterministic search over pack-provided indexes (if present)
All responses MUST include:
- active pack identity
- query parameters hash (or echoed request id)
- deterministic error codes on failure
### 3) Execution interface (optional; to SwarmCraft / Orgo)
If Malkuth runs pack-defined routines:
- `POST /runtime/execute` with:
- routine id
- inputs (content-addressed if applicable)
- execution policy (timeout, memory, CPU budget)
- required determinism mode (strict / best-effort)
Execution outputs MUST include:
- routine id + version
- active pack identity
- exit code + deterministic error code mapping
- logs/metrics (structured)
---
## Invariants (Non-negotiable)
1) **No new facts**
Malkuth must not introduce new canonical truth. Any outputs are **derived** and must be attributable to:
- active pack payloads, and
- explicit query/execute inputs.
2) **Fail-closed on integrity and compatibility**
If the active pack is not verified/compatible, Malkuth must refuse to serve.
3) **Deterministic serving**
For a given (pack_id, query input, runtime config in deterministic mode), outputs must be:
- bit-identical or canonically identical,
- with stable ordering and stable tie-breakers.
4) **Immutable pack payload**
Malkuth must treat pack payloads as read-only.
---
## Determinism Rules
### 1) Sorting and tie-breakers
Any results that depend on ordering MUST define:
- stable primary sort key(s)
- stable tie-breakers (e.g., lexical id ordering)
### 2) Randomness
Randomness is forbidden in strict deterministic mode.
If a routine requires randomness, it MUST accept an explicit seed and record it in the execution output.
### 3) Time and locale
Wall-clock time, locale, and environment differences MUST NOT affect deterministic outputs.
If timestamps are emitted for observability, they must not influence computed results.
### 4) Floating point / platform stability
If pack routines use float operations, Malkuth must enforce stable:
- numeric representation,
- rounding rules,
- and pinned libraries.
---
## Failure Modes
### Activation / pack load failures
- Pack missing or unreadable
- ABI/runtime version incompatibility
- Payload corruption detected at load time
- Required payload component missing (index/table not present)
### Query failures
- Invalid query schema
- Unsupported query type for this pack
- Determinism violation detected (e.g., non-stable comparator)
- Resource exhaustion (timeout / memory cap)
### Execution failures (optional)
- Routine not found
- Sandbox violation (filesystem/network access denied)
- Deterministic mode requested but routine not deterministic-capable
- Dependency mismatch (required runtime module absent)
All failures MUST produce:
- stable error codes
- active pack identity
- request id
- minimal safe diagnostics (no sensitive data leaks)
---
## Observability
Malkuth MUST emit:
- active pack state (pack_id, activation epoch)
- request counters (query/lookup/execute)
- latency histograms
- cache hit rates (if caching is enabled)
- error codes + rates
- resource usage (CPU, memory, disk IO)
Malkuth SHOULD emit:
- per-request trace spans (request id propagated end-to-end)
- deterministic mode flags (strict vs best-effort)
Telemetry MUST NOT contain:
- raw sensitive inputs unless explicitly allowed by policy
- secrets or private keys
- user-identifying data unless required and governed
---
## Security and Privacy
- Run all routines in a sandbox with least privilege.
- Deny network by default in deterministic mode.
- Restrict filesystem access to the activated pack mount + designated scratch.
- Enforce quotas and timeouts per request.
- Treat pack payload as untrusted until verified by Konnaxion (Malkuth still must validate expected structure before use).
---
## Compatibility
Malkuth MUST enforce a runtime compatibility policy:
- minimum runtime ABI version required by pack
- feature flags supported by runtime
- downgrade prevention (if required by policy)
If compatibility fails, Malkuth MUST refuse to serve (fail-closed) and surface a compatibility error code.
---
## Implementation Notes (Non-normative)
Common implementation choices:
- embed a local query engine (e.g., parquet reader + ANN index + rules engine)
- isolate routine execution via WASM/containers
- use memory-mapped indexes for performance
- maintain a small, deterministic caching layer keyed by (pack_id, request_hash)
The primary goal is not maximum performance; it is **repeatability, safety, and auditability** under offline constraints.
================================================================================================
FILE: docs_technical/20-nodes/netzach-architect-strategy.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: b3bef8707d8434a3e0d780c9ba322a27e493c0328e79bc208e8ae82dd10d3726
CONTENT_BYTES: 6538
================================================================================================
# 07 — Netzach: Architect-Strategy (Planning / Work Orchestration)
**File:** `docs/20-nodes/netzach-architect-strategy.md`
**Status:** Normative (kOA)
**External normative references:** Kristal v4 docs + schemas (pinned dependency)
---
## 1) Purpose
**Architect-Strategy** converts canonical truth + operating context into **governed work proposals**.
It does not render user-facing outputs and does not mutate canon. It produces **plans** that Orgo can accept, decompose into Cases/Tasks, execute, and audit.
---
## 2) Position in the system
### 2.1 Upstream inputs (typical)
- Kristal Exchange reference (pinned canonical truth)
- Mandate bundle (policy/constraints, approvals, prohibited actions)
- Blueprint (system configuration + interface constraints)
- Operational context (availability, incidents, release state, backlog, telemetry summaries)
### 2.2 Downstream consumers (typical)
- Orgo (for gating, decomposition, lifecycle management)
- SwarmCraft (execution of Orgo tasks; not directly commanded by Strategy)
- Observability/analytics (plan quality, drift, throughput)
---
## 3) Responsibilities (MUST / SHOULD)
### 3.1 MUST
- Produce **plan artifacts** that are schema-valid and auditable.
- Pin all dependencies used to construct a plan (exchange ref, mandate ref, blueprint ref, context snapshot ref).
- Separate **proposal** from **truth**:
- Plans may *recommend* changes/work, but do not assert canon updates.
- Emit work in **governable units**:
- proposals must map cleanly to Orgo Cases/Tasks with explicit owners, types, priorities, and constraints.
- Respect mandate constraints (permissions, risk thresholds, forbidden actions, review requirements).
- Provide explicit **rationale** and **evidence pointers** for each proposed work item.
### 3.2 SHOULD
- Produce plans that are stable under small input changes (reduce churn).
- Prefer incremental diffs to prior plans when possible (reduce operational noise).
- Detect conflicts (duplicate work, incompatible tasks, dependency cycles) and surface them explicitly.
- Provide estimated impact/cost/risk fields suitable for Orgo routing and approval.
---
## 4) Inputs (interfaces)
Architect-Strategy consumes references, not raw truth bytes, unless explicitly allowed by policy.
### 4.1 Required references (recommended baseline)
- `exchange_ref` (points to the Kristal Exchange used)
- `mandate_ref` (policy bundle / mandate version)
- `blueprint_ref` (system contract/config bundle)
- `context_ref` (serialized summary of operational context and telemetry inputs)
### 4.2 Optional inputs
- Previous plan reference (for diffing / continuity)
- Open Orgo cases/tasks snapshot (for dedupe / routing)
- Release/channel state (for rollout-aware planning)
---
## 5) Outputs (artifacts)
Architect-Strategy produces **pre-truth** artifacts only.
### 5.1 Primary output: Plan Envelope (kOA artifact)
A plan envelope is a typed object that includes:
- pinned dependency references (exchange/mandate/blueprint/context)
- proposed cases/tasks (or pointers to them)
- ordering/precedence constraints and dependency edges
- gating requirements (human review, multi-party approval, risk signoff)
- rationale and evidence pointers
### 5.2 Secondary outputs (optional)
- Plan diff vs previous plan
- Risk register entries
- Coverage summary (what domains/areas were assessed, what was intentionally omitted)
---
## 6) Invariants (non-negotiable)
1. **No canon mutation:** Strategy cannot write or patch Kristal Exchange.
2. **Pinned inputs:** Every plan must name the exact Exchange + policy/config + context it was derived from.
3. **Governed work only:** All actions must be representable as Orgo Cases/Tasks (no direct execution commands).
4. **Policy compliance:** A plan that violates mandate constraints is invalid.
5. **Auditability:** Every proposed work item has rationale + evidence pointers sufficient for review.
---
## 7) Determinism and reproducibility
Strategy may use probabilistic methods, but it must be **auditable and reproducible enough for governance**.
### 7.1 Required
- Record generator identity/version and key parameters.
- Record a stable `plan_id` and `plan_schema_version`.
- Record a `context_ref` that is sufficient to explain the plan.
### 7.2 Recommended
- Record a `random_seed` (or equivalent) when stochastic behavior is used.
- Provide a “replay mode” that can regenerate the same plan given the same pinned inputs.
---
## 8) Failure modes
### 8.1 Input failures
- Missing or incompatible `exchange_ref` / `mandate_ref` / `blueprint_ref`
- Stale or invalid context snapshot
- Insufficient permissions (mandate prohibits required actions)
### 8.2 Planning failures
- Dependency cycles in proposed tasks
- Duplicate/conflicting work proposals
- Excessive churn (plan oscillation without meaningful input change)
### 8.3 Output failures
- Plan envelope schema invalid
- Missing rationale/evidence pointers
- Tasks not representable in Orgo taxonomy (unknown type/category/owner)
---
## 9) Orgo interaction model
Architect-Strategy proposes; Orgo decides and enforces.
### 9.1 Submission
- Strategy submits Plan Envelope to Orgo intake.
- Orgo validates:
- schema validity
- mandate compliance
- compatibility with current release/channel state
- dedupe vs open work
### 9.2 Decomposition
- Orgo decomposes plan into Cases/Tasks (or accepts Strategy-provided tasks if allowed).
- Orgo assigns routing, approvals, and execution constraints.
### 9.3 Feedback loop
- Orgo returns acceptance/rejection with reasons.
- Strategy may revise plans, but must preserve audit trail (superseding plan links).
---
## 10) Observability
### 10.1 Logs/events (minimum)
- plan_generated (with plan_id, pinned refs, counts by task type, churn metrics)
- plan_rejected (reason codes, violated constraints)
- plan_accepted (case/task counts, routing summary)
### 10.2 Metrics (recommended)
- plan_generation_latency
- plan_acceptance_rate / rejection_rate
- task_dedupe_rate
- plan_churn_rate (diff size over time)
- policy_violation_attempt_rate
- downstream_execution_outcomes (success/failure distribution by plan lineage)
---
## 11) Security and access control
- Strategy must operate under least-privilege:
- read access to pinned inputs it is authorized to consume
- write access only to pre-truth proposal artifacts
- Strategy must not access tenant data outside scope of the current mandate.
- Any cross-tenant/shared planning is an explicit design choice and must be governed.
---
================================================================================================
FILE: docs_technical/20-nodes/tiferet-sentient.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 034af7974799cb89f0357ca352c7215342c77d300e6cd0fe0d7915a33cd1b4ab
CONTENT_BYTES: 6323
================================================================================================
# Tiferet — SenTient (Resolution Engine)
**File:** `docs/20-nodes/tiferet-sentient.md`
**Normative scope:** kOA node behavior and interfaces.
**Non-normative:** Kristal artifact schemas (external), cryptographic/canonicalization specifics (external).
---
## 1) Purpose
SenTient is the ecosystem’s **resolution and reconciliation engine**. It converts *proposed* claims (Claim-IR) into **explicit, typed, auditable resolution outputs** (Resolved Claim-IR), while preserving uncertainty and enforcing deterministic structure so downstream gates remain reproducible.
SenTient does not “create truth.” It produces **well-structured candidates and decisions** that can be validated and compiled into canonical truth later.
---
## 2) Responsibilities
SenTient MUST:
- Resolve **entity surfaces** to ranked candidate identifiers.
- Resolve **property surfaces** to ranked candidate identifiers.
- Normalize **literal values** into typed forms (dates, quantities, coordinates, identifiers), recording any lossy steps as warnings.
- Preserve ambiguity explicitly (no silent coercion).
- Produce **schema-valid** Resolved Claim-IR outputs with stable ordering and deterministic structure.
- Emit stable, machine-readable **diagnostics** (warnings/errors) for downstream gating and operator review.
- Maintain traceability from each resolved item back to its originating claim and evidence pointers.
SenTient SHOULD:
- Provide per-domain resolvers (people/orgs/places/medical/finance/etc.) behind a single interface.
- Support “policy-driven resolution” (e.g., stricter normalization rules) without changing the public artifact contract.
---
## 3) Inputs
### 3.1 Required inputs
- **Claim-IR batch** (proposed claims with evidence pointers and extraction context)
- **Resolution policy bundle** (kOA policy/config applicable to this run)
- **Resolver resources** (indexes, dictionaries, embeddings, lookup tables, ontologies), versioned and pinned by Orgo
### 3.2 Optional inputs
- **Context bundles** (domain packs, locale packs, tenant-specific mappings)
- **Prior state hints** (e.g., last-known mappings) as *non-authoritative* hints
---
## 4) Outputs
### 4.1 Primary output
- **Resolved Claim-IR batch**: a deterministic, schema-valid batch where each claim is transformed into:
- typed normalized literals (where applicable),
- ranked candidates for entities/properties,
- explicit resolution state (resolved / ambiguous / rejected / error),
- diagnostics and provenance pointers.
### 4.2 Secondary outputs
- **Resolution diagnostics report** (optional): aggregated counters and top error categories for observability.
- **Resolver telemetry** (required): structured events for latency, hit-rate, and drift detection (no new facts).
---
## 5) Determinism and invariants
### 5.1 Determinism requirements
SenTient output MUST be deterministic given:
- the exact Claim-IR input,
- pinned resolver resources,
- pinned policy bundle,
- pinned code version.
Determinism means:
- stable ordering of records and candidate lists,
- stable scoring behavior (within defined numerical tolerances),
- stable diagnostic codes.
### 5.2 No silent upgrades
SenTient MUST NOT change:
- normalization rules,
- ranking thresholds,
- candidate set construction
without a versioned change that Orgo can pin and audit.
### 5.3 Ambiguity preservation
If multiple candidates are plausible, SenTient MUST record ambiguity explicitly rather than choosing silently.
### 5.4 No truth mutation
SenTient MUST NOT:
- rewrite or “correct” upstream evidence,
- invent missing facts,
- collapse uncertainty into a single asserted truth.
---
## 6) Interface (Orgo integration)
### 6.1 Invocation
SenTient is invoked by Orgo as a pipeline stage:
- input: content-addressed Claim-IR reference + policy/resource refs
- output: content-addressed Resolved Claim-IR reference + diagnostics refs
### 6.2 Idempotency
Re-running SenTient with identical pinned inputs MUST produce byte-identical (or canonical-identical) outputs.
### 6.3 Failure handling contract
- On **hard failure**, SenTient returns a structured error and produces no Resolved Claim-IR output.
- On **partial resolution**, SenTient still produces Resolved Claim-IR but marks affected claims as ambiguous/rejected with diagnostics.
Orgo decides gating rules; SenTient must provide the signals needed for those decisions.
---
## 7) Error model
SenTient MUST emit stable error/warning codes, including (minimum):
- `RESOLVE_ENTITY_NOT_FOUND`
- `RESOLVE_ENTITY_AMBIGUOUS`
- `RESOLVE_PROPERTY_NOT_FOUND`
- `RESOLVE_PROPERTY_AMBIGUOUS`
- `NORMALIZE_LITERAL_INVALID`
- `NORMALIZE_LITERAL_LOSSY`
- `EVIDENCE_POINTER_INVALID`
- `POLICY_VIOLATION`
- `RESOURCE_VERSION_MISSING`
- `INTERNAL_RESOLVER_ERROR`
Each diagnostic MUST include:
- claim reference
- field/path reference (where applicable)
- severity
- deterministic message template + structured parameters
---
## 8) Observability
SenTient MUST emit:
### 8.1 Metrics
- throughput (claims/sec)
- p50/p95/p99 latency
- candidate hit-rate (entity/property)
- ambiguity rate
- rejection rate
- normalization error rate
- resource cache hit-rate
### 8.2 Logs (structured)
- run_id / build_id (from Orgo)
- input content ref
- pinned policy/resource versions
- top diagnostic codes + counts
### 8.3 Tracing
- stage span per run
- child spans per resolver component (entity/property/literal normalization)
---
## 9) Security and privacy
- SenTient must treat inputs as potentially sensitive and follow tenant policy for logging/redaction.
- Resolver resources must be integrity-checked (hash/signature) and version-pinned by Orgo.
- No external network calls unless explicitly allowed by policy and audited.
---
## 10) Test and conformance expectations (kOA)
Minimum test suite:
- deterministic rerun test (same inputs/resources → same outputs)
- ambiguity preservation test
- literal normalization golden tests (per domain)
- resource pinning test (mismatched resource ref → failure)
- diagnostic stability test (codes and shapes stable across patch releases)
---
## 11) Links
- Node map and lifecycle: `docs/10-system/`
- Orgo pipeline stage contract: `docs/50-operations/pipeline.md`
- Integration profile for Kristal compilation boundaries: `docs/40-integration/kristal-v4/`
================================================================================================
FILE: docs_technical/20-nodes/yesod-compiler.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 9293ce8c2228f92cd3c12097c4f694bcc91a5cfa9eefba0101f64337f466a332
CONTENT_BYTES: 5655
================================================================================================
# Yesod — Compiler (Build Executor)
**Normative for kOA:** YES
**External normative reference:** Kristal v4 (pinned)
## Purpose
Yesod is the ecosystem’s **hermetic compilation executor**: it runs the pinned Kristal compiler in a controlled environment to produce **Kristal Exchange + Runtime Pack** outputs after Orgo authorizes compilation.
## Scope boundary
Yesod executes compilation. It does **not** decide acceptance (validation gate) and does **not** define Kristal artifact formats (Kristal is the normative source). Orgo orchestrates the workflow and invokes Yesod as a pipeline stage.
---
## Responsibilities
Yesod MUST:
1) **Execute compilation deterministically**
- Run the compiler with pinned inputs, pinned config, and pinned toolchain identity.
- Declare the enabled Kristal profiles that may affect outputs (if any).
2) **Produce schema-conformant Kristal artifacts**
- Exchange generation MUST satisfy the Kristal Exchange commit contract; the Exchange manifest MUST conform to the pinned Kristal schema.
- Runtime Pack generation MUST satisfy the Kristal Runtime Pack contract; the Pack manifest MUST conform to the pinned Kristal schema.
3) **Fail closed on declared integrity**
- If integrity material is declared (hashes/signatures/authority refs) and Yesod performs verification, it MUST fail closed on mismatch.
4) **Emit audit-grade build evidence**
- Emit stable output references/IDs back to Orgo for Build Record linkage (inputs → configs → outputs).
- Emit deterministic reason codes on failure.
Yesod MUST NOT:
- Compile when validation has not passed (it must reject compile requests missing Orgo authorization).
- Invent facts or alter validated content; it only compiles/packages under pinned inputs.
---
## Inputs
Yesod receives compilation jobs from Orgo that include:
- References to **Resolved Claim-IR** and a **PASS Validation Report** (or an Orgo-attested gate decision).
- Pinned **Mandate/Blueprint/Policy** references (or a single pinned context reference).
- Compiler identity/version + configuration reference (container digest / buildpack digest / binary hash).
- Declared Kristal profiles enabled for this compilation (if any).
- Target output locations (artifact store destinations / channels).
---
## Outputs
Yesod produces, at minimum:
- **Kristal Exchange** payload + **Exchange Manifest** (schema-conformant).
- **Runtime Pack** payload + **Runtime Pack Manifest** (schema-conformant).
- Optional export artifacts (only if implemented and declared as enabled profiles).
Yesod returns to Orgo:
- Artifact refs/IDs for Exchange + Pack + manifests
- Declared payload/file hashes
- Signature material (if produced)
- Execution environment digest pointer (for reproducibility/audit)
---
## Interfaces
### Orgo → Yesod (Compile Request)
A job request that includes:
- `build_id`
- gate authorization (attesting Validation PASS)
- input refs (Resolved Claim-IR, policy/blueprint/mandate refs)
- pinned compiler/config refs
- output destinations
### Yesod → Orgo (Compile Result)
A result object containing:
- compile status (success/fail + deterministic reason codes)
- output refs: exchange + pack + manifests
- integrity refs (hashes/signatures) where applicable
- reproducibility metadata pointer (execution environment digest)
---
## Invariants (non-negotiable)
1) **No compile without gate authorization**
Yesod MUST reject compilation if not explicitly authorized by Orgo post-validation.
2) **Schema conformance (Kristal-owned)**
Produced Exchange/Pack manifests MUST conform to the pinned Kristal schemas.
3) **Deterministic execution under pinned inputs**
Given identical pinned inputs/config/toolchain, compilation MUST be replayable (subject to enabled profiles).
4) **Fail-closed integrity**
If integrity is declared and verification is performed, mismatches MUST halt compilation and return a failure result (no partial canon).
---
## Failure modes
- **Gate missing/invalid** → reject compile request (authorization failure).
- **Schema validation failure (manifests)** → fail compile; emit deterministic error codes and pointers.
- **Integrity mismatch** (declared hash/signature) → fail closed.
- **Resource limit breach** (time/memory/disk) → fail with explicit resource-limit codes; do not emit partial canon.
- **Non-determinism detected** (byte drift across replay test) → fail build/conformance; quarantine the compiler/toolchain release.
---
## Observability
Yesod MUST emit trace spans/events that include:
- `tenant_id`, `environment`, `component`, `version`
- `build_id` and correlation id(s)
- output artifact IDs/refs (exchange_id/kristal_id, runtime_pack_id/pack_id, manifest refs)
- pinned policy/blueprint/mandate refs
- gate decision codes (as span events)
- deterministic failure reason codes on error
---
## Conformance expectations
- Provide valid/invalid fixtures for manifest schemas and ensure deterministic failure codes/locations.
- Ensure stage ordering is upheld end-to-end (Orgo enforces; Yesod refuses unauthorized compile).
- Ship and run the Kristal-required canonicalization/hash test vectors required by the pinned Kristal version.
---
## Pointers
- Orgo stage ordering and compile authorization: `50-operations/pipeline.md`
- kOA determinism requirements: `10-system/determinism.md`
- Kristal integration entry + conformance gates: `40-integration/kristal-v4/index.md`, `40-integration/kristal-v4/conformance.md`
- Pinned Kristal schemas (do not duplicate):
- `vendor/kristal/02-schemas/exchange-manifest.schema.json`
- `vendor/kristal/02-schemas/runtime-pack-manifest.schema.json`
================================================================================================
FILE: docs_technical/30-artifacts/build-record.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 708aeb464ca7806cb93382a5add9ebdf78253af93ac776a7e6d49250e2c21487
CONTENT_BYTES: 5927
================================================================================================
# Build Record (kOA)
**Artifact class:** Operational (governance + reproducibility)
**Owned by:** Orgo (control plane)
**Schema:** `docs/30-artifacts/schemas/build-record.schema.json`
**Purpose:** Provide a single, auditable, content-addressed (or at least tamper-evident) record of *what was built*, *from what*, *under which pinned policies/blueprints*, *which gates ran*, and *what artifacts were produced*.
This record is kOA-owned. It references Kristal artifacts by **opaque IDs + manifest refs**, but does not redefine Kristal contracts.
---
## 1) Producer → Consumers
**Producer:** Orgo (pipeline orchestrator)
**Consumers:** Audit tooling, release tooling, CI/CD, operators, conformance tests, incident response
---
## 2) Identity
- `build_id` is the primary identifier (kOA namespace).
- Orgo SHOULD additionally compute a `record_hash` over a canonicalized representation of the Build Record (kOA-defined) and optionally sign it.
---
## 3) What the Build Record must answer
A Build Record MUST allow an auditor to reconstruct:
1) **Inputs**: exactly which upstream input snapshots were used (content-addressed refs).
2) **Pinned environment**: blueprint/mandate/policy selections and toolchain identity.
3) **Stage spine**: which stages ran, in what order, with what outcomes.
4) **Gate decisions**: validation results and any hard-stop reasons.
5) **Outputs**: the produced Kristal artifacts (Exchange + Runtime Pack) and their manifest references.
---
## 4) Minimum required sections (contract)
### 4.1 Header
- `build_id`
- `created_at`
- `actor` (who/what triggered it; human, scheduler, CI)
- `pipeline` (pipeline name + version)
- `environment` (workspace/cluster, optional but recommended)
### 4.2 Pinned context
- `mandate_ref` (kOA mandate bundle ref; may be absent for dev)
- `blueprint_ref` (pinned blueprint bundle ref)
- `policy_selections` (kOA list of enabled policies/profiles)
### 4.3 Inputs
- `input_snapshots[]` (content-addressed refs)
- Optional: `input_summary` (counts, high-level metadata, no raw content)
### 4.4 Stages (timeline)
A list of stage executions, each with:
- `stage` (enum/name)
- `started_at`, `ended_at`
- `status` (`PASS|FAIL|SKIP`)
- `artifacts_out[]` (refs produced by that stage)
- `metrics` (optional)
- `errors[]` (stable codes/messages)
### 4.5 Gate outcomes
- `validation_gate` result (pass/fail + reference to the Kristal Validation Report artifact)
- Any additional gates (policy gate, safety gate, compatibility gate), if used
### 4.6 Outputs (references only)
- `validation_report_ref` (Kristal artifact ref)
- `exchange_manifest_ref` (Kristal artifact ref)
- `exchange_id` (Kristal identifier; opaque string)
- `runtime_pack_manifest_ref` (Kristal artifact ref)
- `runtime_pack_id` (Kristal identifier; opaque string)
### 4.7 Integrity (recommended)
- `record_hash` (kOA hash object)
- `signatures[]` (kOA signature envelope; trust roots are kOA deployment policy)
---
## 5) Invariants
- **No compile on fail:** If validation fails, the Build Record MUST NOT contain Exchange/Runtime Pack output refs for that build attempt (or must mark them as absent and record a terminal failure).
- **Reproducibility:** If the same `input_snapshots`, `blueprint_ref`, `policy_selections`, and toolchain versions are used, reruns MUST be comparable and explain any non-determinism via explicit recorded variance.
- **Tamper evidence:** If `record_hash` is present, it MUST verify; if signatures are present, verification MUST be fail-closed for any workflow that treats the Build Record as authoritative (release, promotion, audit export).
---
## 6) Failure modes
- Missing or non-content-addressed `input_snapshots`
- Missing pinned `blueprint_ref` (for non-dev pipelines)
- Stage list does not contain required gates
- Output refs present despite failed validation gate
- Integrity block present but unverifiable
---
## 7) Minimal example (illustrative)
```json
{
"build_id": "bld_2026_02_27_0007",
"created_at": "2026-02-27T14:12:03Z",
"actor": { "type": "ci", "id": "gha:org/repo#8421" },
"pipeline": { "name": "orgo-pipeline", "version": "1.4.0" },
"mandate_ref": "sha256:...mandate-bundle...",
"blueprint_ref": "sha256:...blueprint-bundle...",
"policy_selections": ["policy:baseline", "profile:strict-determinism"],
"input_snapshots": ["sha256:...snap1...", "sha256:...snap2..."],
"stages": [
{
"stage": "extract",
"started_at": "2026-02-27T14:12:05Z",
"ended_at": "2026-02-27T14:12:44Z",
"status": "PASS",
"artifacts_out": ["sha256:...claim-ir..."]
},
{
"stage": "resolve",
"started_at": "2026-02-27T14:12:45Z",
"ended_at": "2026-02-27T14:13:21Z",
"status": "PASS",
"artifacts_out": ["sha256:...resolved-claim-ir..."]
},
{
"stage": "validate",
"started_at": "2026-02-27T14:13:22Z",
"ended_at": "2026-02-27T14:13:58Z",
"status": "PASS",
"artifacts_out": ["sha256:...validation-report..."]
},
{
"stage": "compile",
"started_at": "2026-02-27T14:14:01Z",
"ended_at": "2026-02-27T14:14:33Z",
"status": "PASS",
"artifacts_out": ["sha256:...exchange-manifest...", "sha256:...runtime-pack-manifest..."]
}
],
"validation_report_ref": "sha256:...validation-report...",
"exchange_manifest_ref": "sha256:...exchange-manifest...",
"exchange_id": "kristal:exchange:...",
"runtime_pack_manifest_ref": "sha256:...runtime-pack-manifest...",
"runtime_pack_id": "kristal:pack:...",
"record_hash": { "alg": "sha256", "value": "..." }
}
````
---
## 8) Versioning and compatibility
* The Build Record schema is kOA-owned and versioned by kOA.
* Fields referencing Kristal artifacts (`exchange_*`, `runtime_pack_*`, `validation_report_ref`) are **opaque** and must not assume Kristal internal structure beyond “identifier + manifest ref”.
---
================================================================================================
FILE: docs_technical/30-artifacts/index.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: a03e8bc5320d53e52bd3973617182b0f4fc2e5c248ce1e3d6065ae97232579be
CONTENT_BYTES: 1826
================================================================================================
# kOA Artifacts
**Scope:** kOA-owned artifacts only (operational + distribution + governance).
**Non-goal:** This section does not redefine Kristal artifacts (Claim-IR, Resolved Claim-IR, Validation Report, Exchange, Runtime Pack). Those are normatively defined in Kristal v4 and referenced from `docs/40-integration/kristal-v4/`.
---
## What belongs here
kOA artifacts are typed payloads that exist to operate, govern, distribute, and observe the ecosystem. Examples include:
- **Orgo governance artifacts:** Case, Task, routing labels, audit objects
- **Pipeline operational records:** Build Record, Release Record
- **Distribution/runtime state:** Konnaxion State, Activation Record, Rollback Record, Cache Indexes
- **Mandate/policy bundles (kOA deployment):** Mandate Bundle (pinned mandate/policy context used by Orgo/Konnaxion)
Each artifact has:
- A **documented contract** (human-readable)
- A **JSON Schema** (machine-validated) under `docs/30-artifacts/schemas/`
- **Versioning/compat** expectations (see `docs/10-system/determinism.md` and `docs/40-integration/kristal-v4/koa-profile.md`)
---
## Artifact index
### Governance (Orgo)
- `orgo-case.md`
- `orgo-task.md`
### Pipeline records
- `build-record.md`
- `release-record.md`
### Policy / mandate
- `mandate-bundle.md`
### Distribution/runtime
- `konnaxion-state.md`
---
## Schemas
Schemas live in:
- `docs/30-artifacts/schemas/`
Naming rules:
- One schema per artifact
- `$id` must be stable and owned by kOA (do not use Kristal namespaces)
- `additionalProperties: false` unless explicitly justified
- Use semver for schema versioning inside the artifact where needed
---
## References
- Kristal v4 integration: `docs/40-integration/kristal-v4/`
- System invariants: `docs/10-system/trust-boundaries.md`, `docs/10-system/determinism.md`
================================================================================================
FILE: docs_technical/30-artifacts/konnaxion-state.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: ba8b90f5b1d36cf852bbeddd86cee10f9a62bacd7b13aa7c63f8fefcd67b302c
CONTENT_BYTES: 4680
================================================================================================
# Konnaxion State (kOA-native Operational Artifact)
## Purpose
**Konnaxion State** is a **kOA-native operational artifact** that captures the local distribution/activation state of a Konnaxion instance (or cluster) in a structured, auditable form.
It is designed to:
- provide operators and Orgo a consistent view of what is installed/active/pinned,
- support deterministic rollback decisions,
- correlate activation outcomes with health signals.
This artifact does **not** redefine Kristal artifacts (Exchange, Runtime Pack, Validation Report). It references them by ID as defined in the pinned Kristal v4 spec. See `docs/40-integration/kristal-v4/`.
---
## Ownership
- **Produced by:** Konnaxion
- **Consumed by:** Orgo (ops + audit), rollout tooling, monitoring/telemetry pipelines
- **Storage:** local state store + optional upstream audit store
---
## When it is emitted
Konnaxion MUST emit an updated Konnaxion State record on:
- successful verify+activate
- failed verification or failed activation attempt
- rollback start and rollback completion
- pin/unpin or revocation changes
- periodic heartbeat (recommended)
---
## Identifier
- `state_id`: unique ID for the record (UUID recommended)
- `instance_id`: stable identifier of the Konnaxion instance emitting the record
- `created_at`: RFC3339 UTC timestamp
---
## Semantics (normative)
### Active set invariants
Konnaxion State MUST represent:
- exactly one **active** Runtime Pack per activation domain (e.g., per channel, per tenant, per environment), according to your rollout model
- the complete set of **installed** packs available for activation
- any **pinned** or **revoked** pack constraints that affect activation decisions
### Fail-closed status
If verification cannot be completed (missing metadata, signature failure, compatibility uncertainty), the state MUST reflect a fail-closed outcome:
- `last_attempt.status = "FAILED"`
- `last_attempt.reason_code` populated
- no change to active pack unless explicitly permitted by policy
### Deterministic rollback
Rollback decisions should be derivable from:
- `active_pack` + `last_known_good_pack`
- policy pins and revocations
- deterministic triggers (health thresholds, explicit operator action)
---
## Data model (fields)
### 1) Top-level fields
- `state_id`
- `instance_id`
- `environment` (e.g., prod/stage/dev)
- `created_at`
- `active` (object; current active pack(s))
- `installed[]` (objects; installed packs)
- `pins` (object; pin/revoke constraints)
- `last_attempt` (object; most recent verify/activate/rollback attempt)
- `health` (object; summarized health signals at time of emission)
- `telemetry_refs` (object; pointers to detailed logs/traces)
### 2) Pack references
All pack references use Kristal identifiers as defined in the pinned Kristal v4 spec:
- `pack_id`
- `pack_manifest_ref` (content reference)
- `exchange_ref` (if relevant to provenance)
- `content_hash` / `signature_ref` as declared by Kristal artifacts
The exact field names and meaning are defined by Kristal; this artifact only stores references.
---
## Example (illustrative)
```json
{
"state_id": "6d4d1a3e-9e78-4f5c-8f8f-4b3c3e1f2c11",
"instance_id": "konnaxion-prod-a-03",
"environment": "prod",
"created_at": "2026-02-27T14:22:13Z",
"active": {
"channel": "stable",
"pack_id": "pack_2026_02_27_0007",
"activated_at": "2026-02-27T14:19:02Z",
"exchange_ref": "kristal_exchange_ref_placeholder"
},
"installed": [
{
"pack_id": "pack_2026_02_27_0007",
"installed_at": "2026-02-27T14:10:00Z",
"manifest_ref": "contentref:sha256:...",
"status": "VERIFIED"
},
{
"pack_id": "pack_2026_02_26_0004",
"installed_at": "2026-02-26T10:12:00Z",
"manifest_ref": "contentref:sha256:...",
"status": "AVAILABLE"
}
],
"pins": {
"pinned_pack_id": "pack_2026_02_27_0007",
"revoked_pack_ids": ["pack_2026_02_20_0011"]
},
"last_attempt": {
"type": "ACTIVATE",
"target_pack_id": "pack_2026_02_27_0007",
"status": "SUCCEEDED",
"reason_code": "OK",
"started_at": "2026-02-27T14:18:50Z",
"finished_at": "2026-02-27T14:19:02Z"
},
"health": {
"status": "HEALTHY",
"signals": [
{ "name": "startup_ok", "value": true },
{ "name": "query_smoke_ok", "value": true }
]
},
"telemetry_refs": {
"logs": "logref:...",
"trace": "traceref:..."
}
}
````
---
## Validation
Schema: `docs/30-artifacts/schemas/konnaxion-state.schema.json`
---
## Change control
This is a kOA-native contract. Changes require:
* an ADR in `docs/90-reference/adr/`
* a schema version bump per your compatibility policy
================================================================================================
FILE: docs_technical/30-artifacts/mandate-bundle.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: ac72096ac5a192dd77c91e1f003f1a3a590702962df3ff8b78cc1dc8e1c6dfcc
CONTENT_BYTES: 2953
================================================================================================
# Mandate Bundle
**Owner:** kOA (Keter / Mandate)
**Role:** A pinned, versioned bundle of governance inputs that shape what the ecosystem is allowed to do and how it must behave.
The Mandate Bundle is **kOA-owned**. It is not a Kristal artifact. It provides policy and constraints that upstream and control-plane components use to decide what work is permitted and how it must be processed.
## Purpose
* Provide a single, content-addressed “governance package” that can be referenced by builds, releases, and audits.
* Enable reproducible decisions: given the same Mandate Bundle, policy evaluation results should be consistent.
* Separate governance configuration from runtime execution and from canonical truth artifacts.
## What it contains
A Mandate Bundle typically includes:
* **Policy selections**: identifiers of active policies (with versions).
* **Validation policy config**: which validators run, thresholds, required checks.
* **Distribution policy config**: channel rules, pinning rules, downgrade prevention, signer requirements.
* **Rendering policy config**: determinism constraints, refusal/omission rules, trace coverage requirements.
* **Execution policy config**: allowed task categories, rate limits, escalation rules.
* **Key/trust policy**: trusted signer sets, revocations, key-rotation rules.
* **Metadata**: bundle ID, created time, author/approver identity, change log reference.
## Consumers
* **Orgo:** uses it to enforce gate decisions and stage ordering, and to record policy provenance in Build/Release records.
* **Validation stage:** uses it to decide which checks are required and how results are scored.
* **Konnaxion:** uses it to enforce verification/activation rules and rollback constraints.
* **Architect-Render:** uses it to enforce no-new-facts and trace/omission/refusal policies.
* **SwarmCraft:** uses it to enforce execution constraints.
## Invariants
* **Content-addressed:** bundle ID is derived from canonical bytes of the bundle.
* **Immutable:** a published bundle is never edited; changes create a new bundle.
* **Auditable:** includes provenance (who approved it, when, why).
* **Deterministic evaluation:** policy interpretation must be stable under the pinned policy engine/version.
* **Explicit scope:** bundle clearly states which parts apply to which stages (validation vs distribution vs rendering vs execution).
## Failure modes
* Missing or ambiguous policy identifiers
* Non-deterministic policy evaluation (engine drift)
* Unauthorized bundle publication (approval chain broken)
* Incompatible policy set (e.g., requires validators not available)
## Storage and referencing
* Bundles should be stored in an artifact store with:
* content hash
* human-readable version tag (optional)
* approval metadata
* Build/Release records reference the Mandate Bundle by content-addressed ID.
## Schema
* JSON schema: `docs/30-artifacts/schemas/mandate-bundle.schema.json`
================================================================================================
FILE: docs_technical/30-artifacts/orgo-case.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: f3cda66d6b7792db91b022b8ce8b2b3f42baeb8fef0c93bdd8b6f92ad3de93e7
CONTENT_BYTES: 4849
================================================================================================
# Orgo Case
## Purpose
An **Orgo Case** is the durable, auditable container for governed work in the kOA ecosystem. It groups context, policies, linked artifacts, and a set of Orgo Tasks into a single lifecycle-managed unit.
A Case is the unit operators and automation use to:
- track why work exists,
- enforce stage gating and approvals,
- link work to provenance and outcomes,
- audit decisions and changes over time.
## Scope and ownership
- **Normative here (kOA-owned):** Orgo Case structure, lifecycle states, routing/labeling, audit requirements.
- **Not defined here:** Kristal artifact schemas (Claim-IR, Validation Report, Exchange, Runtime Pack). This doc only references them by content-addressed IDs.
## Core identifiers
- `case_id`: globally unique identifier for the Case.
- `organization_id`: tenant / authority scope.
- `created_at`, `updated_at`: ISO-8601 timestamps.
- `status`: lifecycle state (see below).
- `label`: routing taxonomy string (canonical dot-separated label).
## Required fields (normative)
An Orgo Case MUST include:
- Identity:
- `case_id`
- `organization_id`
- `created_at`
- `updated_at`
- Classification:
- `source` (who/what created it: user, automation, system)
- `type` (broad case type: build, incident, review, ingest, release, etc.)
- `category` (routing category)
- `label` (canonical routing label string)
- Lifecycle:
- `status`
- `priority` (e.g., P0–P3 or equivalent)
- `severity` (if applicable)
- `visibility` (internal/private/public per policy)
- Governance + audit:
- `owners` (responsible parties)
- `audit` (append-only event list or references)
- Linkage:
- `tasks[]` (references to Orgo Tasks)
- `refs[]` (content-addressed refs to related artifacts, including Kristal artifacts when applicable)
## Optional fields (recommended)
- `summary`: short operator-facing description.
- `description`: longer context / rationale.
- `tags[]`: free-form tags for filtering.
- `policy_context`: references to mandate/policies that govern this case.
- `due_at`: target completion time.
- `sla`: response/resolve targets.
## Lifecycle states (normative)
A Case MUST implement a finite state model with terminal semantics.
Recommended states:
- `OPEN`: created, work not yet complete
- `IN_PROGRESS`: active work underway
- `BLOCKED`: cannot proceed (dependency, policy, external system)
- `WAITING_REVIEW`: awaiting human or policy review/approval
- `COMPLETED`: terminal success (all required tasks satisfied)
- `CANCELLED`: terminal stop (no further work)
- `FAILED`: terminal failure (work ended unsuccessfully)
Rules:
- Terminal states: `COMPLETED`, `CANCELLED`, `FAILED`
- A Case in a terminal state MUST NOT accept new Tasks unless explicitly reopened (policy-controlled).
- Status transitions MUST be recorded in `audit`.
## Tasks and containment
- A Case MUST contain zero or more Orgo Tasks.
- Orgo Tasks reference their parent Case via `case_id`.
- A Case MAY be created before tasks exist (e.g., to reserve audit context), but should eventually contain at least one task or be cancelled.
## References to external artifacts
Cases commonly reference content-addressed artifacts:
- Input snapshot sets (kOA ingest outputs)
- Kristal outputs (Validation Report, Exchange reference, Runtime Pack reference)
- Release records and activation records
Rules:
- References MUST be content-addressed where possible.
- A Case MUST NOT embed large payloads; store pointers and hashes instead.
- References MUST include enough context to resolve the artifact (type + ID + hash/ref).
## Audit model (normative)
A Case MUST provide an append-only audit trail of:
- creation and updates
- status transitions
- task creation/updates (or references)
- policy/approval events
- artifact reference additions/removals
- assignment/ownership changes
Audit entries SHOULD include:
- `event_id`
- `timestamp`
- `actor` (user/service)
- `event_type`
- `diff` or structured fields describing what changed
- optional `reason`
## Label taxonomy (routing)
`label` is a canonical dot-separated string:
`...`
Rules:
- dot-separated, lowercase recommended
- stable segments; changes require a migration plan
- labels SHOULD be derived deterministically from `type/category` and policy routing rules
## Failure modes
- Missing required fields → reject write (fail closed).
- Invalid state transitions → reject write.
- Attempted mutation of audit history → reject write.
- Case references a Task that does not exist → accept only if Task will be created within the same transaction; otherwise reject or mark as inconsistent per policy.
## Schema
The JSON schema for Orgo Case lives at:
- `docs/30-artifacts/schemas/orgo-case.schema.json`
This doc is normative; the schema is the executable contract.
================================================================================================
FILE: docs_technical/30-artifacts/orgo-task.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 0f1bf58334facc73b1898613adaa0e9ad05833948de7f809454765d2bd98223d
CONTENT_BYTES: 7150
================================================================================================
# Orgo Task
**Normative for kOA:** YES
**External normative reference:** None (may reference Kristal artifact IDs as opaque refs)
An **Orgo Task** is the **atomic, executable unit of governed work** in kOA. Nothing executes unless it is expressed as an Orgo Task in an executable state.
Schema: `30-artifacts/schemas/orgo-task.schema.json`
## Purpose
An Orgo Task provides:
* a single executable contract for SwarmCraft (or any executor)
* explicit inputs/expected outputs at the artifact-type level
* deterministic gating rules (what must be true before dispatch)
* auditability (who/what/why/when), including lineage to mandate/blueprint/canonical refs
* a status lifecycle with allowed transitions and structured reasons
## Core invariants
* **Governance before execution:** tasks must pass Orgo gates before dispatch.
* **Pinned context:** tasks must reference pinned mandate/blueprint; and when relevant pinned external artifact IDs (no “latest”).
* **Auditability:** execution must emit telemetry with correlation + attempt identity and bind produced artifacts to the task.
* **No canon mutation:** task outcomes may produce new artifacts and new work, but must not mutate external canon directly.
## Identity and scope
Minimum identity fields:
* `task_id` (globally unique, stable)
* `case_id` (required; tasks always belong to a Case)
* `tenant_id` (required)
* `organization_id` (required in multi-tenant org-scoped deployments)
Recommended:
* `title` (human-readable)
* `created_at`, `created_by`
* `labels[]` (routing and filtering)
* `confidentiality` (visibility rules)
## Status lifecycle
A Task has a single `status` and optional `status_reason` + `reason_codes[]`.
Recommended statuses:
* `DRAFT` — incomplete; not executable; editable
* `BLOCKED` — cannot become executable until gates are satisfied; must include reasons
* `READY` — executable; can be dispatched
* `RUNNING` — execution in progress; bound to an `attempt_id`
* `DONE` — terminal success
* `FAILED` — terminal failure (with deterministic `error_code`)
* `CANCELED` — terminal canceled
* `PAUSED` — optional; not dispatched until resumed
Allowed transition sketch (policy may further restrict):
* `DRAFT → READY | BLOCKED | CANCELED`
* `BLOCKED → DRAFT | READY | CANCELED`
* `READY → RUNNING | BLOCKED | CANCELED`
* `RUNNING → DONE | FAILED | PAUSED`
* `PAUSED → READY | CANCELED`
Orgo MUST NOT set a task directly to `RUNNING` unless it is dispatching it.
## Routing and priority
Routing is used for ownership, queues, and policy:
* `routing.base`
* `routing.category`
* `routing.subcategory`
* optional `routing.role` (horizontal axis)
Priority is discrete, e.g. `P0`–`P4`.
## Method (how the task is executed)
`method.type` is one of:
* `tool` — deterministic tool execution
* `agent` — agentic execution under explicit constraints
* `human` — requires human action
* `hybrid` — composed, must still be auditable
Method includes:
* `method.name` (executor/tool/agent identifier)
* `method.params` (structured parameters; must be stable for determinism)
* optional `method.capabilities[]` (required capabilities)
## Inputs and expected outputs
Inputs are artifact references, not embedded payloads:
* `inputs[]`: list of `{ artifact_type, artifact_id, hash? }`
Expected outputs are declarations of what must be produced:
* `expected_outputs[]`: list of `{ artifact_type, artifact_id? }`
If `expected_outputs[]` is present, the executor MUST either:
* produce the outputs and emit `ARTIFACT_PRODUCED`, or
* fail with a deterministic `error_code`.
## Constraints
Tasks may include constraints such as:
* `deadline_at`
* `max_attempts`
* `retry_policy` (deterministic)
* `require_human_approval` (boolean)
* `tool_allowlist[]` / `tool_denylist[]`
* `time_budget_ms` / `cpu_budget` (if applicable)
* `partial_ok` (only if policy allows partial completion)
## Gates (executable-state requirements)
A Task is executable (`READY`) only if all applicable gates pass:
1. **Schema valid** (task conforms to `orgo-task.schema.json`)
2. **Pinned references**
* `mandate_id` and blueprint reference are pinned
* any external/canonical/runtime refs are explicit IDs (no floating “latest”)
3. **Capability constraints**
* method/tool/agent is allowed by mandate/blueprint/policy
4. **Approval gates**
* if `require_human_approval=true`, Orgo must record approval before dispatch
5. **Attempts**
* dispatch only if `attempt_count < max_attempts` (if set)
If any gate fails, Orgo keeps the task `DRAFT` or `BLOCKED` with structured reasons and MUST NOT dispatch.
## Telemetry contract (required)
Tasks define minimum telemetry expectations so Orgo can reconcile status deterministically.
Minimum required fields on every execution event:
* `task_id`, `case_id`, `tenant_id`
* `correlation_id` (stable per dispatch chain)
* `attempt_id` (unique per run)
* `timestamp`
* `producer` (executor identity/version)
Minimum event types:
* `TASK_STARTED`
* `STEP_STARTED` (optional but recommended for multi-step methods)
* `STEP_FINISHED`
* `ARTIFACT_PRODUCED` (for each produced artifact; includes type/id/hash)
* `TASK_FINISHED` or `TASK_FAILED`
## Results and reconciliation
Executors return (or Orgo derives from telemetry):
* terminal status (`DONE` / `FAILED` / `CANCELED`)
* `error_code` (stable, deterministic on failures)
* `diagnostics` (structured)
* `produced_artifacts[]` (type/id/hash)
* `warnings[]` (structured)
Orgo MUST bind produced artifacts to the Task record and update Case-level rollups.
## Relationships
Orgo Task commonly references:
* `mandate_id` (from Mandate Bundle)
* `blueprint_id` / `blueprint_version`
* upstream work: `plan_id` (if used)
* external artifact refs (opaque IDs)
* downstream artifacts: Build Record / Release Record IDs (kOA-owned)
## Minimal example
```json
{
"schema_version": "1",
"task_id": "task:01HTQ2W6JY7Y9KZC6B0M9Y2B3A",
"case_id": "case:01HTQ2W4QZ0K4B2R3F2M6X9H1P",
"tenant_id": "tenant:acme",
"organization_id": "org:acme",
"title": "Validate resolved claims for mandate v12",
"status": "READY",
"priority": "P2",
"routing": { "base": "build", "category": "validate", "subcategory": "claims" },
"method": {
"type": "tool",
"name": "validator",
"params": { "profile": "default" }
},
"inputs": [
{ "artifact_type": "resolved-claims", "artifact_id": "rcir:01HTQ2..." }
],
"expected_outputs": [
{ "artifact_type": "validation-report" }
],
"constraints": {
"max_attempts": 2,
"require_human_approval": false,
"tool_allowlist": ["validator"]
},
"lineage": {
"mandate_id": "mandate:01HTQ1...",
"blueprint_id": "blueprint:01HTQ1...:v12",
"source_refs": [
{ "ref_type": "external", "ref_id": "exchange:01ABC..." }
]
},
"telemetry_contract": {
"require_correlation_id": true,
"required_events": [
"TASK_STARTED",
"STEP_STARTED",
"STEP_FINISHED",
"ARTIFACT_PRODUCED",
"TASK_FINISHED",
"TASK_FAILED"
]
},
"created_at": "2026-02-27T14:05:00Z",
"created_by": "user:ops"
}
```
================================================================================================
FILE: docs_technical/30-artifacts/release-record.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: d10e2fb5a0601040d193f79891cf045e8fdfd070046031bb8ba0cc502846591c
CONTENT_BYTES: 3679
================================================================================================
# Release Record (kOA-native artifact)
**File:** `docs/30-artifacts/release-record.md`
**Normative scope:** kOA-native artifact contract (control-plane).
**Non-normative:** Kristal artifact schemas and cryptographic/canonicalization mechanics (external).
---
## 1) Purpose
A **Release Record** is the kOA control-plane artifact that captures **distribution intent** and **rollout state** for publishing one or more verified build outputs (e.g., Runtime Packs) to one or more channels/cohorts.
It binds:
- **what** is being released (references to build outputs),
- **where** it is being released (channels/cohorts),
- **how** it is being released (policy + rollout strategy),
- **what happened** (verification/activation outcomes, timestamps, operators, reasons).
A Release Record does not mutate canonical truth. It is an operational governance artifact used by Orgo/Konnaxion.
---
## 2) Producer / consumer
- **Produced by:** Orgo (release controller)
- **Consumed by:** Konnaxion distribution facet, rollout tooling, ops/audit systems
---
## 3) Identity and immutability
- `release_id` is the primary identifier.
- Release Records are append-only in audit stores; state transitions are recorded as events.
---
## 4) Minimal fields (conceptual contract)
### 4.1 Core identifiers
- `release_id` (string, unique)
- `created_at` (RFC3339 timestamp)
- `created_by` (principal/user/service identity)
### 4.2 What is being released
- `build_ref` (content ref / ID pointing to the Build Record)
- `artifacts[]` (list of artifact refs; typically Runtime Pack refs; may include additional derived artifacts)
- each item includes:
- `artifact_type`
- `artifact_ref` (content ref / ID)
- `artifact_hash` (hash object, if applicable)
- `compat` (optional compatibility metadata)
### 4.3 Where it is being released
- `channels[]` (e.g., `stable`, `beta`, `canary`, tenant-scoped channels)
- each channel entry includes:
- `channel_id`
- `target_cohorts[]` (optional)
- `constraints` (optional policy constraints)
### 4.4 Rollout strategy
- `strategy` (object)
- examples: `all_at_once`, `percentage`, `staged`, `pinned`
- `rollout_plan` (optional; stages with conditions)
### 4.5 Verification + activation policy hooks
- `verification_policy_ref` (policy identifier/ref)
- `activation_policy_ref` (policy identifier/ref)
### 4.6 Current state
- `status` (enum): `DRAFT | QUEUED | VERIFYING | VERIFIED | RELEASING | RELEASED | PAUSED | ROLLED_BACK | FAILED | CANCELED`
- `status_reason` (optional text/code)
- `updated_at` (RFC3339 timestamp)
### 4.7 Events (append-only)
- `events[]` ordered list of state transitions / actions
- each event includes:
- `at` timestamp
- `type` (e.g., `QUEUED`, `VERIFY_STARTED`, `VERIFY_FAILED`, `ACTIVATE_SUCCEEDED`, `ROLLBACK_SUCCEEDED`)
- `actor`
- `details` (structured)
---
## 5) Invariants (kOA)
- Release Records MUST be produced only by Orgo-controlled workflows.
- Activation MUST be fail-closed: if verification fails, `RELEASED` must never occur.
- Rollback MUST be traceable and recorded as events.
- Release Records MUST never rewrite canonical artifacts; they only reference them.
---
## 6) Failure modes
- Missing or unverifiable artifact refs → `FAILED`
- Incompatible runtime pack vs target cohort constraints → `PAUSED` or `FAILED` (policy-dependent)
- Partial rollout failures → `PAUSED` with cohort-specific event details
---
## 7) Storage and access
- Stored in Orgo audit store (append-only).
- Exposed via Orgo API for operators and automation.
---
## 8) Schema
- JSON Schema: `docs/30-artifacts/schemas/release-record.schema.json`
---
================================================================================================
FILE: docs_technical/40-integration/kristal-v4/conformance.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: ff4564e3a8d4f6fd5ecf8ad7b5404f8140de609f34724b4d13b024cab8e441fd
CONTENT_BYTES: 5118
================================================================================================
# Kristal v4 Conformance (kOA)
**File:** `docs/40-integration/kristal-v4/conformance.md`
**Normative scope:** kOA requirements for producing/consuming Kristal artifacts (conformance gates).
**External normative source:** Kristal v4 (pinned) schemas and spec.
---
## 1) Purpose
Define the kOA conformance requirements for any component that:
- produces Kristal-adjacent artifacts for compilation, or
- consumes Kristal outputs (Exchange / Runtime Packs), or
- performs verification/activation (Konnaxion distribution facet).
This document is a **kOA gate checklist**. It does not restate Kristal artifact schemas; it points to the pinned Kristal v4 dependency.
---
## 2) What “conformant” means in kOA
A kOA implementation is conformant if it satisfies all of the following:
1. **Stage gating is enforced**: Orgo ensures stage order and hard gates (no compile on fail).
2. **Typed boundaries**: the system exchanges typed artifacts at boundaries; no implicit truth.
3. **Kristal artifacts validate** against the pinned Kristal v4 schemas before:
- publication (Exchange),
- activation (Runtime Pack).
4. **Fail-closed verification**: any mismatch in integrity, schema, or compatibility prevents activation.
5. **Determinism**: reruns with pinned inputs/resources/policies yield identical (or canonical-identical) outputs.
---
## 3) Pinned Kristal v4 dependency
kOA MUST pin:
- Kristal version (tag/commit)
- schema paths used for validation (Exchange Manifest, Runtime Pack Manifest, Validation Report, etc.)
- canonicalization profile/version expectations (as specified by Kristal v4)
See: `docs/40-integration/kristal-v4/pinned-dependency.md`.
---
## 4) Producer conformance checks (upstream of Kristal compile)
### 4.1 Claim-IR producers (extractors)
MUST:
- emit schema-valid Claim-IR for the pinned Kristal v4 contract
- include stable evidence pointers and deterministic ordering
- avoid generating “truth claims” that bypass validation (no side channels)
SHOULD:
- emit stable diagnostic codes for extraction errors
### 4.2 SenTient (resolution) outputs
MUST:
- emit schema-valid Resolved Claim-IR (pinned Kristal v4 contract)
- preserve ambiguity explicitly
- ensure deterministic ordering and stable scoring outputs
---
## 5) Validator conformance (pre-compile gate)
### 5.1 Validation report artifact
MUST:
- be produced deterministically from pinned inputs
- include enough detail for operators to reproduce failures
- include stable codes for policy/schema violations
### 5.2 Gate rule
MUST:
- prevent compilation/publishing of Exchange/Runtime Pack when validation status is failing (no compile on fail)
---
## 6) Compiler/packaging conformance (Kristal outputs)
### 6.1 Exchange publication
MUST:
- validate the Exchange Manifest and any referenced required artifacts against pinned Kristal v4 schemas
- produce content-addressed identity as defined by Kristal v4
- publish immutably (no in-place mutation)
### 6.2 Runtime Pack production
MUST:
- validate Runtime Pack Manifest against pinned Kristal v4 schema
- bind Runtime Pack identity to the declared Exchange reference(s) per Kristal v4
- include all payloads referenced by the manifest
---
## 7) Consumer conformance (Konnaxion / runtime)
### 7.1 Verify-before-activate (fail-closed)
Konnaxion MUST verify, in order:
1. **Schema validity**
- Validate the Runtime Pack Manifest against pinned Kristal v4 schema
2. **Integrity**
- Verify declared hashes for all payloads
- Verify signatures according to the pinned trust policy
3. **Compatibility**
- Enforce compatibility rules (version constraints, downgrade prevention, tenant policy)
4. **Atomic activation**
- Activate as a single atomic switch
- Ensure deterministic rollback to last-known-good
Any failure MUST stop activation and produce an auditable event.
### 7.2 Rollback
MUST:
- be deterministic given the same triggers
- produce an activation/rollback record and emit telemetry
---
## 8) Determinism tests (minimum suite)
Implementations MUST pass:
- **Rerun determinism**: same pinned inputs/resources/policies → identical outputs
- **Ordering determinism**: stable ordering for lists/maps in produced artifacts
- **Golden tests**: fixed fixtures for Claim-IR/Resolved Claim-IR/Validation Report
- **Compatibility tests**: reject incompatible Runtime Packs; prevent downgrades
- **Failure tests**: corrupt payload hash → fail-closed; invalid schema → fail-closed
---
## 9) Audit and evidence requirements
kOA MUST be able to show, for any active Runtime Pack:
- the originating Build Record reference
- the pinned Kristal version used for schema validation
- verification outcomes (hash/signature/compat)
- the activation timeline (events)
- the rollback history (if any)
---
## 10) Conformance reporting (kOA-native)
kOA SHOULD maintain a kOA-native **conformance report** per release:
- test suite version
- Kristal pinned version
- verification policy version
- pass/fail summary + links to evidence artifacts
(If you formalize this, it belongs under `docs/30-artifacts/` as a kOA artifact.)
---
================================================================================================
FILE: docs_technical/40-integration/kristal-v4/contract-pointers.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: ade3499f5eb4545ce5f75c6950283f5089e62f75fce81edae95c60ee9694d065
CONTENT_BYTES: 5151
================================================================================================
# Kristal v4 — Contract Pointers (kOA integration)
**Normative for kOA:** YES
**External normative reference:** Kristal v4 (pinned)
**Purpose:** Provide the canonical pointers from kOA → Kristal v4 normative contracts (schemas/spec).
**Rule:** kOA does not redefine Kristal artifact formats. If anything here conflicts with Kristal v4, Kristal v4 wins.
See also:
- `40-integration/kristal-v4/pinned-dependency.md`
- `40-integration/kristal-v4/koa-profile.md`
---
## 1) Mandatory inter-system interface contracts (Kristal-owned)
> **Important:** All Kristal-owned references in kOA docs MUST go through the pinned dependency path (e.g., `vendor/kristal/...`).
### 1.1 Claim-IR (proposal boundary)
**Kristal source**
- `vendor/kristal/02-schemas/claim-ir.schema.json`
**kOA usage**
- Produced by extractors; consumed by SenTient and validation.
**kOA pointers**
- `10-system/lifecycle.md`
- `20-nodes/tiferet-sentient.md`
---
### 1.2 Resolved Claim-IR (resolution boundary)
**Kristal source**
- `vendor/kristal/02-schemas/resolved-claim-ir.schema.json`
**kOA usage**
- Produced by SenTient; consumed by validation and compilation.
**kOA pointers**
- `10-system/lifecycle.md`
- `20-nodes/tiferet-sentient.md`
---
### 1.3 Validation Report (acceptance gate)
**Kristal source**
- `vendor/kristal/02-schemas/validation-report.schema.json`
**kOA usage**
- Produced by validation; used by Orgo to authorize compilation. Validation failure blocks compilation.
**kOA pointers**
- `10-system/lifecycle.md`
- `20-nodes/gevurah-orgo.md`
- `20-nodes/yesod-compiler.md`
- `50-operations/pipeline.md`
---
### 1.4 Exchange commit contract (canon boundary)
**Kristal source**
- Manifest schema: `vendor/kristal/02-schemas/exchange-manifest.schema.json`
- Federation/shard schemas (if used):
- `vendor/kristal/02-schemas/exchange-federation-manifest.schema.json`
- `vendor/kristal/02-schemas/exchange-shard-manifest.schema.json`
**kOA usage**
- Produced by Kristal compiler; consumed by query/render/export.
**kOA pointers**
- `10-system/lifecycle.md`
- `20-nodes/daat-kristal-bridge.md`
- `20-nodes/yesod-compiler.md`
---
### 1.5 Runtime Pack contract (offline execution boundary)
**Kristal source**
- Manifest schema: `vendor/kristal/02-schemas/runtime-pack-manifest.schema.json`
**kOA usage**
- Produced by Kristal compiler; distributed/verified/activated by Konnaxion; queried offline.
**kOA pointers**
- `10-system/lifecycle.md`
- `20-nodes/chesed-konnaxion.md`
- `20-nodes/daat-kristal-bridge.md`
- `50-operations/releases.md`
- `50-operations/rollback.md`
---
## 2) Core normative rules (Kristal-owned; do not restate)
kOA implementers MUST follow Kristal v4 rules (see Kristal spec + test vectors for exact wording and fixtures), including:
- **Schema conformance:** Exchange and Runtime Pack manifests MUST conform to their Kristal schemas.
- **No compile on fail:** validation failure blocks compilation.
- **Rebuild determinism:** identical inputs/compiler/config/policies reproduce identical IDs and declared file hashes.
- **Signature envelope:** signatures are separated so hashed content is unambiguous.
- **Fail-closed integrity:** declared hashes/signatures/key refs must verify or the consumer fails closed.
- **Forward compatibility:** unknown non-integrity fields may be ignored; integrity fields are never best-effort.
---
## 3) Query contract and profiles (Kristal-owned)
**Core query contract**
- `vendor/kristal/04-query/query-contract.md`
**Optional profiles (examples)**
- `vendor/kristal/05-profiles/profile-query-tpf-pagination.md`
- `vendor/kristal/05-profiles/profile-jsonld-export.md`
- `vendor/kristal/05-profiles/profile-rdf-wdqs-export.md`
- `vendor/kristal/05-profiles/profile-rdf-integrity-rdfc.md`
- `vendor/kristal/05-profiles/profile-provenance-nanopub-provo.md`
**Test vectors**
- `vendor/kristal/09-test-vectors/` (canonicalization/hash fixtures; validation pass/fail fixtures; query determinism fixtures)
---
## 4) Naming / compatibility notes (integration guidance)
- When Kristal declares `runtime_pack_id`, other integration surfaces may call it `pack_id`; treat them as synonyms unless a Kristal profile says otherwise.
- Prefer Kristal’s declared canonicalization identifiers exactly as recorded in Kristal schemas/manifests.
---
## 5) kOA policy surfaces (kOA-owned)
Anything that is a **policy choice** rather than an artifact format lives in kOA and must be recorded/pinned in build/release records, for example:
- rollout/activation policy (channels/cohorts, rollback triggers)
- key management and trust root pinning policy
- resource caps for validation, compilation, and query
- operational SLOs/alerting requirements
See:
- `40-integration/kristal-v4/koa-profile.md`
- `50-operations/`
- `30-artifacts/build-record.md`
- `30-artifacts/release-record.md`
---
## 6) Non-redundancy rule (kOA enforcement)
- Do not copy Kristal schema field lists or canonicalization rules into kOA docs.
- Do not maintain parallel “kOA versions” of Kristal contracts.
- Reference the pinned Kristal dependency (`vendor/kristal/...`) and link to the exact schema/spec path.
================================================================================================
FILE: docs_technical/40-integration/kristal-v4/index.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: d7d7c2735ca211628de226f84de21f2a04976f13bffbfd9b2dbe669ff3e376f9
CONTENT_BYTES: 2059
================================================================================================
# Kristal v4 Integration (kOA)
**Purpose:** Define how the kOA Digital Ecosystem integrates with **Kristal v4** without duplicating Kristal’s normative contracts.
**Rule:** Kristal artifacts (Claim-IR, Resolved Claim-IR, Validation Report, Exchange, Runtime Pack, manifests, signatures) are **normatively defined by Kristal v4**. kOA only defines:
- how it **pins** the Kristal dependency,
- which **profiles/policies** it chooses,
- which **gates** it enforces (fail-closed),
- which **conformance checks** are required,
- how it handles **legacy compatibility**.
## What lives in this section
- `pinned-dependency.md`
How kOA pins Kristal v4 (commit/tag), how references are made, and how updates are managed.
- `contract-pointers.md`
The authoritative links/paths into Kristal v4 docs/schemas for each Kristal artifact used by kOA.
- `koa-profile.md`
kOA’s selected profiles/policies for canonicalization, signing, validation strictness, distribution/activation behavior.
- `conformance.md`
Required tests and gate checks (CI + runtime) to be considered conformant.
- `legacy-compat.md`
Allowed legacy spellings/aliases on input (if any), and kOA’s deprecation windows.
## Integration invariant (kOA)
kOA MUST NOT:
- redefine Kristal schemas/contracts in kOA docs,
- publish or validate Kristal artifacts against kOA-owned schemas,
- accept non-verifying or “best effort” integrity checks for activation or truth compilation paths.
kOA MUST:
- treat Kristal v4 schemas as the contract boundary,
- fail-closed on verification and gate failures,
- record opaque references to Kristal artifacts in kOA operational records (Build/Release).
## Quick start
1. Pin Kristal v4 (see `pinned-dependency.md`).
2. Implement artifact production/consumption using Kristal v4 schemas (see `contract-pointers.md`).
3. Apply the kOA profile defaults (see `koa-profile.md`).
4. Run conformance suite (see `conformance.md`).
5. Configure legacy acceptance window if migrating from older artifacts (see `legacy-compat.md`).
================================================================================================
FILE: docs_technical/40-integration/kristal-v4/koa-profile.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 5c219c63d2681d4d9a79bb845aaad406ffa035ac037355276ef139b989c9ba63
CONTENT_BYTES: 7118
================================================================================================
# kOA Profile for Kristal v4 (Pinned)
**Normative for kOA:** YES
**External normative references:** Kristal v4 (pinned) docs + schemas (Kristal-owned artifact contracts)
## Purpose
This document defines the **kOA-required profile** for producing, distributing, verifying, and consuming Kristal artifacts (Exchange + Runtime Packs) within the kOA ecosystem, **without duplicating** Kristal’s normative schemas/spec.
kOA treats Kristal v4 as the **sole normative source** for Kristal-owned artifact formats and schemas. This document adds only **kOA-specific enforcement** (gates, compatibility rules, activation behavior).
---
## 1) Scope and normative sources
### 1.1 Normative (external)
Kristal v4 pinned dependency (vendored/submodule) is the normative source for:
- Exchange Manifest schema: `vendor/kristal/02-schemas/exchange-manifest.schema.json`
- Runtime Pack Manifest schema: `vendor/kristal/02-schemas/runtime-pack-manifest.schema.json`
- Validation Report schema (if consumed as a contract): `vendor/kristal/02-schemas/validation-report.schema.json`
- Core spec (IDs/canonicalization/hashing, signatures/trust): `vendor/kristal/01-core-spec/`
### 1.2 Normative (kOA)
kOA requirements for:
- activation/rollback behavior at the edge (Konnaxion)
- compatibility checks and downgrade prevention
- operational conformance tests and enforcement gates
These are kOA-owned rules and must not redefine Kristal identity semantics.
---
## 2) kOA baseline conformance level
kOA’s baseline profile targets **Kristal core semantics** as defined by the pinned Kristal v4 dependency, including:
- RFC 8785 (JCS) canonicalization (per Kristal’s declared profile identifiers)
- SHA-256 content addressing for core hashes/IDs
- explicit determinism declaration for Runtime Packs (when the schema/profile requires it)
Optional capabilities (exports, advanced integrity, provenance packaging) MUST be claimed via explicit Kristal profiles and must not redefine core identity semantics.
---
## 3) Canonicalization, hashing, and ID rules (kOA-enforced)
### 3.1 Canonicalization identifiers
kOA producers MUST record canonicalization fields using the canonical values:
- `canonicalization_profile = "kristal.v3:jcs-rfc8785"`
- `canonicalization_version = "1"`
Legacy spellings MUST NOT appear in emitted artifacts or examples (including `"jcs-rfc8785"`, `"jcs-rfc8785@1"`, `"1.0"`).
### 3.2 Hash/sign workflow
kOA follows Kristal’s normative order:
1) remove signature material from the signing/hash target (as defined by Kristal)
2) canonicalize via the declared profile (JCS)
3) hash (SHA-256 for core IDs and declared integrity)
4) verify and/or attach signatures
### 3.3 Signature envelope placement
If signatures are present, they MUST be carried in a top-level `signatures[]` array (not interleaved into signed content).
### 3.4 Hash object field name
kOA uses `alg` (not `algo`) in hash objects.
---
## 4) Determinism and reproducibility (kOA baseline)
### 4.1 Determinism declaration (Runtime Packs)
If the pinned Kristal schema/profile requires an explicit determinism declaration, kOA Runtime Packs claiming baseline conformance MUST set it as required by that schema/profile (e.g., a boolean `build.deterministic = true` or equivalent field).
### 4.2 Inputs and config are part of determinism
A deterministic build MUST be parameterized by an explicit input snapshot set; the Runtime Pack Manifest MUST reference the Exchange it was compiled from; compiler configuration affecting output bytes MUST be hashed and recorded.
### 4.3 Portable policy surface
Build-affecting behaviors MUST be selected from the allowed policy set. If a needed behavior is not covered, the build must either:
- propose a new standard policy, or
- emit a non-baseline (non-core) profile pack.
Ordering policies affecting bytes MUST be recorded (e.g., data ordering / projection ordering / index ordering policies).
---
## 5) Integrity and fail-closed enforcement (kOA baseline)
### 5.1 Fail-closed semantics
If any integrity material is declared (hashes, signatures, signer identity/key reference), verifiers MUST fail closed on:
- verification failure,
- malformed integrity material,
- hash mismatch,
- missing required files referenced by the manifest (per policy).
### 5.2 kOA requirement: edge verification before activation
Konnaxion MUST verify a pack before activation, including:
- manifest parsing + schema validation (against pinned Kristal schema)
- integrity verification (manifest and/or file hashes, per policy)
- signature verification (if `signatures[]` present) using pinned trust roots
- required file presence checks
If verification fails: do not activate; remain on current/last-known-good; emit deterministic error/reason codes.
---
## 6) Compatibility, activation, downgrade prevention, rollback (kOA baseline)
### 6.1 Compatibility checks (mandatory)
Before activation, Konnaxion MUST validate compatibility between:
- the pack’s declared query/contract version (as defined by the pinned Kristal dependency), and
- the client runtime’s supported contract versions.
It MUST also check required capabilities/projections and relevant locale compatibility; on incompatibility: do not activate; remain on current pack; emit deterministic diagnostics.
### 6.2 Atomic activation
Activation MUST be atomic (no partial state).
### 6.3 Downgrade prevention
Default policy: do not activate a pack with lower `pack_version` than current; downgrade is permitted only via explicit rollback or operator-approved policy.
### 6.4 Deterministic rollback
Konnaxion MUST provide deterministic rollback to a verified pack:
- pinned known-good rollback
- last-known-good rollback
---
## 7) Query semantics (kOA baseline)
Runtime Packs MUST support constrained offline queries; baseline requires deterministic ordering and deterministic paging semantics as declared.
kOA pins the query contract version via the pinned Kristal dependency and enforces the compatibility checks in §6.1.
---
## 8) Rendering and “no new facts” downstream (kOA baseline)
### 8.1 Separation of Strategy vs Render
Rendering must be deterministic and must not introduce new facts; kOA keeps Architect split into Strategy vs Render to prevent truth drift.
### 8.2 Render Bundle requirement (system boundary)
Architect-Render produces a typed Render Bundle with mandatory `trace_map`; outputs must be reproducible and traceable to validated lineage artifacts.
Architect-Render MUST NOT introduce unsupported factual assertions; if trace coverage is insufficient it MUST omit, mark uncertain (only if uncertainty exists upstream), or refuse deterministically.
---
## 9) Required conformance gates (kOA)
kOA deployments MUST gate releases on:
- schema conformance for Exchange + Runtime Pack manifests (pinned Kristal schemas)
- determinism declaration when required by the pinned Kristal schema/profile
- fail-closed verification behavior at activation time
- compatibility checks and downgrade/rollback rules
- render determinism + no-new-facts + trace coverage enforcement for user-facing outputs
================================================================================================
FILE: docs_technical/40-integration/kristal-v4/legacy-compat.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 23b0b062aba4efc740324a7b6e297250d45352d74d8e5a3497197d2e3bab1fe2
CONTENT_BYTES: 4344
================================================================================================
# Legacy Compatibility (kOA ↔ Kristal v4)
## Purpose
Define how kOA handles legacy or out-of-date Kristal artifacts and related metadata **without** weakening the fail-closed truth boundary.
This document is **kOA-specific**. Normative Kristal contract details remain in the pinned Kristal v4 source.
---
## Compatibility stance
### 1) Input tolerance vs output strictness (normative)
kOA components MAY accept legacy spellings/fields **only as input**, but MUST:
- normalize to the pinned Kristal v4 canonical forms internally, and
- emit only canonical Kristal v4–conformant artifacts at boundaries, and
- record a normalization note in kOA-native operational artifacts (Build Record / Release Record / Konnaxion State) when legacy input was encountered.
### 2) Fail-closed on ambiguity (normative)
If legacy input prevents unambiguous normalization (unknown profile, missing required fields, unclear signature target), kOA MUST fail-closed:
- Orgo blocks compilation/release steps.
- Konnaxion blocks activation.
- The failure reason MUST be recorded with a stable reason code.
---
## Allowed legacy forms (input only)
### A) Canonicalization identifiers
kOA MAY accept legacy canonicalization identifiers ONLY if they can be deterministically mapped to the pinned Kristal v4 canonical identifier set.
Examples of legacy spellings that may appear:
- `canonicalization_profile: "jcs-rfc8785"`
- `canonicalization_version: "1.0"`
- combined forms such as `jcs-rfc8785@1.0`
Normalization behavior:
- map to the pinned Kristal v4 canonical values for profile/version (see `contract-pointers.md`).
If the mapping is not explicitly defined for the pinned Kristal version, treat as **unsupported** and fail-closed.
### B) Legacy manifest field names (kOA operational ingestion only)
kOA MAY accept legacy field names in upstream operational records (e.g., build logs or older Orgo records) when a deterministic mapping exists, for example:
- `build_timestamp` → `created_at`
- `input_snapshots` → the canonical “inputs.*” structure (where applicable)
- `policy_selections` → the canonical “policies.*” structure
Rules:
- Only normalize when the mapping is one-to-one or losslessly representable.
- If normalization would discard meaning (lossy), mark the record as `DEGRADED_COMPAT` and require operator action.
### C) Key identifier naming
Legacy signature metadata may use `kid` in some ecosystems.
kOA policy:
- Accept `kid` only if it can be mapped deterministically to the pinned Kristal v4 `key_id` semantics.
- Never allow both `kid` and `key_id` to conflict; if both exist and differ, fail-closed.
---
## Compatibility levels
### Level 0 — Strict v4 only (recommended default)
- Reject any legacy spellings/fields.
- Best for production truth pipelines with controlled producers.
### Level 1 — Normalize legacy identifiers (recommended for migration windows)
- Accept legacy canonicalization identifiers and deterministic field aliases.
- Emit canonical v4 only.
- Require telemetry + audit notes when normalization occurs.
### Level 2 — Extended legacy acceptance (not recommended)
- Accept broader legacy variations.
- Higher risk of ambiguity and inconsistent verification.
- Only allowed with explicit operator approval and documented ADR.
kOA deployments MUST declare which level applies per environment (dev/stage/prod).
---
## Operational requirements
### Logging (normative)
When legacy normalization occurs, log:
- source artifact ref / producer
- legacy fields encountered
- canonical replacements applied
- whether the change was lossless
- reason code and compatibility level applied
### Metrics (recommended)
Track:
- count of legacy artifacts observed
- normalization success/failure rates
- top legacy patterns encountered
- time-to-zero legacy usage (migration progress)
---
## Security implications
Legacy acceptance expands the input surface. Therefore:
- only allow legacy normalization in controlled ingestion paths
- never bypass signature or hash verification due to legacy fields
- treat unknown legacy forms as potential tampering until proven otherwise
---
## Change control
- Any expansion of “Allowed legacy forms” requires an ADR under `docs/90-reference/adr/`.
- Compatibility level defaults and environment policy must be recorded in `koa-profile.md`.
================================================================================================
FILE: docs_technical/40-integration/kristal-v4/pinned-dependency.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 12fbf5f5fea0e1c4b48a5f258877639ad8c5968ff74fa22dae9882c0c2e9db6b
CONTENT_BYTES: 2726
================================================================================================
# Kristal v4 — Pinned Dependency
## Purpose
This section defines how the kOA Digital Ecosystem **depends on Kristal v4** without duplicating Kristal’s normative contracts (schemas, canonicalization rules, signing targets, and artifact definitions).
kOA MUST treat Kristal as an **external normative source** for Kristal-owned artifacts. Local copies of Kristal schemas or “illustrative manifests” are not permitted unless they are vendored verbatim from the pinned version and clearly labeled as such.
## Pin policy (normative)
kOA MUST pin Kristal v4 by **one** of these mechanisms:
1. **Git submodule** (preferred)
2. **Vendored subtree** at an immutable commit hash
3. **Artifact registry** download pinned by digest (if your build system supports it)
A floating reference (e.g., `main`, `latest`, unpinned tags) is not allowed.
## What is pinned
The pin MUST include:
- Kristal specification docs (the normative text)
- Kristal schemas (the executable contracts)
- Conformance tests (if provided) or the schema set necessary to run kOA conformance tests
Recommended repo layout (example):
- `vendor/kristal/` (submodule or subtree)
- `02-schemas/`
- `03-artifacts/` (if present)
- `04-protocols/` (if present)
- `CHANGELOG.md` / `VERSION` / release notes (if present)
## Required metadata in kOA
kOA MUST record the Kristal pin in:
- `docs/40-integration/kristal-v4/index.md` (human-readable)
- `docs/40-integration/kristal-v4/contract-pointers.md` (normative links)
- Build/Release records (machine-verifiable)
At minimum, record:
- `kristal_version` (semantic version or release label)
- `kristal_commit` (full commit hash) or `kristal_digest` (registry digest)
- `kristal_schema_set_id` (optional: hash of the schema directory contents)
## Contract references
All kOA documentation MUST reference Kristal-owned artifacts via the pinned path, for example:
- `vendor/kristal/02-schemas/exchange-manifest.schema.json`
- `vendor/kristal/02-schemas/runtime-pack-manifest.schema.json`
kOA docs must not restate field lists from these schemas.
## Upgrade policy
Upgrading the Kristal pin MUST:
- be done as a single explicit change (one PR/change set)
- include a compatibility review against kOA’s conformance checks
- update `docs/40-integration/kristal-v4/legacy-compat.md` if any behavior changes are required
- be recorded in an ADR under `docs/90-reference/adr/`
## Enforcement (recommended)
kOA SHOULD add a CI check that fails if:
- Kristal schemas are duplicated under `docs/` outside the `vendor/kristal/` pin
- any kOA doc includes a Kristal manifest “example” that does not match the pinned schema set
- unpinned Kristal references appear in build scripts or docs
================================================================================================
FILE: docs_technical/50-operations/incident-response.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 069c80a3d2b39c267277ec95ef0898fe85fbcd573847276cac5e2a9e38f2eb56
CONTENT_BYTES: 10186
================================================================================================
# Incident Response
**File:** `docs/50-operations/incident-response.md`
**Status:** Normative (kOA)
**External normative references:** Kristal v4 docs + schemas (pinned dependency)
---
## 1) Purpose
Provide a deterministic, auditable procedure for detecting, triaging, mitigating, and resolving incidents across:
- Orgo build pipeline (validation/compile/publish),
- Konnaxion distribution/activation/rollback,
- Architect rendering (trace/no-new-facts),
- SwarmCraft execution (side effects + telemetry),
- Trust roots / keys / revocations,
- Multi-tenant isolation.
This runbook avoids schema-level duplication. When you need artifact formats, follow the pinned Kristal references (integration section) or kOA-native schemas under `docs/30-artifacts/schemas/`.
---
## 2) Non-negotiable rules
1. **Fail-closed on declared integrity:** if signatures/hashes are present and verification fails, do not bypass.
2. **No canon mutation under incident pressure:** canon changes require governed work; do not “hot-edit” Exchange.
3. **Prefer rollback over patching:** if activation/publish broke consumers, roll back to last-known-good and then fix forward.
4. **Preserve evidence:** do not overwrite logs/artifacts; snapshot first.
5. **Tenant isolation always:** no cross-tenant “quick fixes” (keys, packs, configs).
---
## 3) Roles and ownership
- **Incident Commander (IC):** directs response, owns timeline, decisions, and comms.
- **Operations Lead (Ops):** executes mitigations (rollbacks, holds, traffic shaping).
- **Security Lead (Sec):** keys, trust roots, revocations, suspected tampering.
- **Orgo Lead:** pipeline gates, build reproducibility, publish controls.
- **Konnaxion Lead:** activation/rollback, channel integrity, cache layout.
- **Architect Lead:** render determinism, trace coverage, template regressions.
- **SwarmCraft Lead:** execution failures, telemetry integrity, side-effect safety.
---
## 4) Severity model
- **SEV0:** active security compromise, cross-tenant breach, or widespread integrity bypass risk.
- **SEV1:** system-wide outage or incorrect canon distribution (bad pack broadly activated).
- **SEV2:** major degradation, partial outage, or correctness risk limited to a subset.
- **SEV3:** minor degradation, localized issue, workaround exists.
- **SEV4:** informational / no user impact.
Escalate to **SEV0/SEV1** when:
- signatures/hashes fail unexpectedly at scale,
- downgrade/substitution attempts are detected,
- trust roots/keys appear compromised,
- cross-tenant mixing is suspected,
- “no-new-facts” violations occur in regulated contexts.
---
## 5) Triage checklist (first 10 minutes)
### 5.1 Stabilize
- [ ] Assign IC + leads (Ops/Sec/Orgo/Konnaxion/Architect/SwarmCraft as needed).
- [ ] Freeze risky automation (publishes, auto-activation, key rotation) if it could worsen impact.
- [ ] Establish an incident channel + single source timeline.
### 5.2 Identify scope
- [ ] Which tenants/channels/environments are impacted?
- [ ] Which stage is failing: build, publish, activation, render, execute?
- [ ] Is this correctness, availability, or security?
### 5.3 Preserve evidence (before any destructive action)
Collect and snapshot:
- Orgo build record + stage logs (validation/compile/publish)
- Validation report(s) for failing builds
- Runtime Pack Manifest + channel index (as received)
- Activation record / local state from Konnaxion (active pack id, last-known-good, rejection reasons)
- Render bundles + trace maps for affected outputs
- SwarmCraft execution envelopes + telemetry for affected tasks
- Trust root set used for verification (per channel) + revocation state
---
## 6) Containment and mitigation playbooks
### 6.1 Bad release / bad pack activated
**Goal:** stop spread and restore last-known-good deterministically.
- [ ] Pause auto-activation for the affected channel(s).
- [ ] Roll back to last-known-good pack (per channel) using Konnaxion rollback procedure.
- [ ] Pin the channel to a known safe release (if your channel supports pinning).
- [ ] Quarantine the offending release (mark as revoked/blocked in distribution controls).
- [ ] Open a governed Orgo Case to fix forward.
### 6.2 Verification failures (signature/hash mismatch)
**Goal:** determine whether it is (a) packaging error, (b) wrong trust roots, (c) tampering.
- [ ] Confirm which verification step failed (index signature vs manifest signature vs file hash).
- [ ] Confirm the trust root set used for the channel is correct for the tenant/environment.
- [ ] Re-fetch artifacts via a trusted path (if network is involved) to rule out transient corruption.
- [ ] If mismatch persists:
- treat as **SEV0/SEV1** until proven benign,
- quarantine the artifact and suspect distribution integrity.
- [ ] If the trust root set is wrong:
- fix by deploying corrected roots (tenant-scoped),
- do not “accept both” unless explicitly governed and audited.
### 6.3 Schema validation failures (manifests / envelopes)
**Goal:** determine whether the producer emitted non-conformant artifacts or the consumer is pinned to the wrong version.
- [ ] Identify the schema version expected by the consumer.
- [ ] Confirm the producer’s pinned dependency versions (Kristal v4 commit/tag).
- [ ] If producer emitted non-conformant artifacts:
- block publish (Orgo gate),
- fix producer and regenerate artifacts.
- [ ] If consumer is pinned incorrectly:
- roll back consumer deployment or adjust its pinned dependency,
- do not relax validation in production as an emergency bypass.
### 6.4 Canon mismatch / reproducibility failure (same inputs, different IDs)
**Goal:** locate the source of non-determinism.
- [ ] Verify canonicalization settings are pinned and consistent across toolchains.
- [ ] Verify inputs are identical (input snapshot refs, blueprint/config refs, policy refs).
- [ ] Compare compilation environment metadata (compiler version, config hash, build constraints).
- [ ] If any dependency is not pinned, treat as root cause and remediate by pinning.
- [ ] Block publish until determinism is restored.
### 6.5 Rendering correctness incident (no-new-facts / trace failures)
**Goal:** prevent propagation of untraceable outputs.
- [ ] Disable or gate the affected templates/models (render pipeline) for impacted tenants.
- [ ] Switch to “safe rendering mode” (strict trace-required; omit if not traced).
- [ ] Capture render bundle + trace map for examples and failing assertions.
- [ ] If the issue is systematic:
- roll back template/model bundle,
- open a governed Orgo Case with reproduction steps and affected surfaces.
### 6.6 Execution incident (side effects, runaway tasks, unsafe actions)
**Goal:** stop harm, contain side effects, preserve audit.
- [ ] Halt task dispatch for affected task types/queues.
- [ ] Cancel or isolate running tasks if safe to do so (do not destroy evidence).
- [ ] Capture task envelopes, runtime logs, telemetry, and any external side-effect audit logs.
- [ ] Review mandate constraints (permissions, approvals, forbidden actions).
- [ ] Resume only after the control-plane gates are corrected.
### 6.7 Suspected security compromise (keys, trust roots, tampering, cross-tenant)
**Goal:** contain and rotate without breaking invariants.
- [ ] Treat as **SEV0**.
- [ ] Freeze publish/activation for impacted channels.
- [ ] Snapshot and lock down trust root stores, revocation sources, and signing infrastructure.
- [ ] Rotate keys per tenant/environment as required; publish revocations through the governed mechanism.
- [ ] Validate that no consumers accept the compromised keys post-rotation.
- [ ] Perform cross-tenant audit: ensure no shared roots were incorrectly configured.
---
## 7) Communication requirements
### 7.1 Internal updates (IC cadence)
- SEV0/SEV1: every 15 minutes
- SEV2: every 30 minutes
- SEV3/SEV4: as needed
Each update includes:
- what changed since last update,
- current impact/scope,
- mitigation status (rollback/pause/quarantine),
- next actions and owner.
### 7.2 External updates (if applicable)
Only publish externally when:
- scope is confirmed,
- a mitigation path exists,
- you can state clear customer impact and next steps.
Avoid speculation about root cause until verified.
---
## 8) Recovery and validation
Before declaring resolved:
- [ ] Impact has stopped (no new failures, no new incorrect outputs).
- [ ] Stable state achieved (last-known-good active; gates re-enabled safely).
- [ ] Verification checks pass end-to-end (publish → distribute → activate → render → execute).
- [ ] Monitoring confirms recovery (error rates, activation rejects, render trace failures, task failures).
- [ ] A governed Orgo Case exists for permanent fix (if not already created).
---
## 9) Post-incident requirements (within 24–72 hours)
### 9.1 Postmortem packet (required)
- Timeline (UTC)
- Impact scope (tenants/channels)
- Root cause analysis (technical + process)
- What worked / what didn’t
- Corrective actions (owners + deadlines)
### 9.2 Corrective actions (typical)
- Add/strengthen conformance tests (schemas, determinism checks, verification ordering).
- Improve guardrails (publish holds, canary activation, stricter rollback criteria).
- Update pinned dependencies and document them (Kristal v4 version pin).
- If contract changes are needed:
- record a kOA ADR,
- update integration profile docs,
- never patch around contract divergence silently.
---
## 10) Quick reference: what to do first (by symptom)
- **Activation failing across a channel** → pause auto-activation → rollback → inspect verification step
- **New release causes crashes** → rollback → quarantine release → open fix-forward case
- **Signature/hash mismatch** → quarantine → verify trust roots → treat as security until proven otherwise
- **Schema validation errors** → block publish → confirm pinned versions → fix producer/consumer pinning
- **Untraceable rendered facts** → safe rendering mode → roll back template/model → collect bundles
- **Unsafe execution behavior** → halt dispatch → isolate tasks → capture telemetry → enforce mandate gates
================================================================================================
FILE: docs_technical/50-operations/key-management.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 549931765d5602ac7288936e5ac14f562221c05d70cefd4aaaabbf3c3cc240eb
CONTENT_BYTES: 5425
================================================================================================
# Key Management
## Purpose
Define how the kOA Digital Ecosystem manages cryptographic keys used for:
- signing and verifying distribution artifacts (e.g., channel indexes, activation metadata),
- authenticating internal services,
- enforcing fail-closed activation and deterministic rollback.
Kristal-owned artifact signing targets and signature field shapes are defined in the pinned Kristal v4 dependency. This document defines **kOA operational policy**: where keys live, how they rotate, how trust is anchored, and how verification gates behave.
## Scope
This doc covers:
- key roles and trust boundaries
- key storage and access control
- rotation and revocation
- verification policy at activation time
- auditing and incident response tie-ins
Not in scope:
- Kristal schema definitions
- exact signature object shapes for Kristal artifacts (refer to pinned Kristal v4)
## Key roles
### 1) Root trust (offline)
- Purpose: anchor trust for distribution verification (e.g., signing intermediate keys).
- Storage: offline HSM or equivalent.
- Access: highly restricted; dual control recommended.
### 2) Distribution signing keys (online)
- Purpose: sign channel indexes or release metadata used by Konnaxion to decide what to fetch/activate.
- Storage: online HSM / KMS.
- Rotation: frequent compared to root (e.g., 30–180 days by policy).
### 3) Service identity keys (online)
- Purpose: authenticate kOA services (Orgo, Konnaxion, pipeline components).
- Storage: workload identity platform or KMS-backed keys.
- Rotation: automated.
### 4) Developer/test keys (non-production)
- Purpose: local development and CI test signing.
- Storage: repository secrets / ephemeral CI secrets.
- MUST NOT be trusted by production verification policy.
## Key identifiers
kOA MUST use stable key identifiers in operational metadata:
- `key_id` (preferred terminology across the ecosystem)
- key metadata includes algorithm family and usage constraints
- key identifiers must be unique within the authority domain
If an external ecosystem uses `kid`, treat it as an alias mapping to `key_id` in kOA operational tooling.
## Trust store and verification policy
### Trust store contents
Konnaxion and verification services MUST maintain a trust store with:
- trusted root(s)
- allowed intermediate signer keys
- key status (active, rotated, revoked)
- validity windows and constraints
### Fail-closed verification
Activation and distribution decisions MUST be fail-closed:
- unknown key → reject
- revoked key → reject
- signature missing when required → reject
- signature invalid → reject
- algorithm not allowed by policy → reject
- key usage mismatch (wrong purpose) → reject
### Deterministic rollback coupling
If activation fails verification, the system MUST:
- preserve the last-known-good active pack state
- record a deterministic rollback decision (reason + evidence)
- emit an operational event for Orgo
## Rotation policy
### Rotation requirements
- Rotation MUST be planned and periodic for online keys.
- Rotation MUST be supported without downtime.
- Multiple valid keys MAY be accepted during an overlap window.
### Overlap window (recommended)
- Configure Konnaxion to accept signatures from:
- the “current” key
- the “previous” key
during a short overlap to allow safe rollout.
### Rotation procedure (high level)
1. Generate new key under controlled environment.
2. Publish the new key to the trust store with status `PENDING`.
3. Sign next release metadata with both current and new key (if supported) or switch signing to new key.
4. Promote new key to `ACTIVE` after verification in staging/limited cohort.
5. Demote old key to `DEPRECATED` and then `RETIRED`.
6. Update documentation and ADR if policy changes.
## Revocation policy
Revocation MUST be supported for:
- key compromise
- unauthorized signing
- policy violation
- cryptographic deprecation
Revocation actions:
- mark key `REVOKED` in trust store
- push trust store update to all verifiers
- block activation and downloads relying on revoked keys
- trigger rollback if an active pack’s trust chain becomes invalid (policy decision)
## Storage and access control
- Production keys MUST be stored in an HSM/KMS or equivalent.
- Keys MUST never be stored in plaintext on disk.
- Private keys MUST be accessible only to the minimum set of signing services.
- Signing services MUST authenticate to KMS with least privilege.
- All key usage MUST be logged (who, when, what was signed).
## Audit and observability
kOA MUST record:
- key creation events
- key rotation events (old→new mapping)
- signing events (artifact type, digest, signer key_id)
- verification failures (deterministic error code + reason)
- revocation events and propagation status
These events should feed:
- security monitoring
- incident response runbooks
- Orgo Cases/Tasks for remediation work
## Incident response hooks
Key compromise response SHOULD:
1. Revoke compromised key(s).
2. Freeze releases and distribution updates until trust restored.
3. Roll back affected deployments (fail-closed).
4. Create Orgo Case(s) for investigation and remediation.
5. Rotate affected trust roots/intermediates as required.
## Related docs
- `docs/50-operations/rollback.md`
- `docs/50-operations/releases.md`
- `docs/40-integration/kristal-v4/conformance.md`
- `docs/90-reference/adr/adr-0003-konnaxion-activation-rollback.md`
================================================================================================
FILE: docs_technical/50-operations/pipeline.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 5b4cc7a87fbaa3e03648fadfc6e8b78def3be9d57b3ddee03bb4cdde66cfa8d3
CONTENT_BYTES: 4893
================================================================================================
# Pipeline Operations (Orgo)
**Scope:** Operational runbook for the kOA pipeline as orchestrated by **Orgo**.
**Non-goal:** This document does not restate Kristal artifact schemas. When a stage produces/consumes Kristal artifacts, it references them as opaque refs and points to `docs/40-integration/kristal-v4/contract-pointers.md`.
---
## 1) Stage spine (normative for kOA)
Orgo enforces this ordered stage spine:
1. **Ingest** → record `input_snapshots[]` (content-addressed refs)
2. **Extract** → produce Claim-IR (Kristal artifact)
3. **Resolve** → produce Resolved Claim-IR (Kristal artifact)
4. **Validate** → produce Validation Report (Kristal artifact)
5. **Compile** → produce Exchange + Runtime Pack (Kristal artifacts)
6. **Distribute** → publish pack(s) to channels (kOA)
7. **Activate** → verify + switch active pack (Konnaxion)
8. **Observe** → metrics/events/logs (kOA)
9. **Feedback** → cases/tasks (kOA)
**Hard rule:** If the Validate stage fails, Orgo MUST stop and MUST NOT run Compile (“no compile on fail”).
---
## 2) Required operational records (kOA)
For every pipeline execution, Orgo MUST persist a **Build Record**:
- `docs/30-artifacts/build-record.md`
For every promotion/publish action, Orgo MUST persist a **Release Record**:
- `docs/30-artifacts/release-record.md`
---
## 3) Inputs (Ingest)
### 3.1 What to verify at ingest
- Inputs are stored immutably and referenced by content hash
- Provenance recorded (source, timestamps, access controls)
- Any confidentiality policy applied before downstream processing
### 3.2 Failure handling
- If an input cannot be content-addressed or provenance is incomplete: fail the build attempt
- If access policy forbids use: exclude and record exclusion
---
## 4) Extract (Claim-IR)
### 4.1 Operational checks
- Extractor version is pinned and recorded
- Output is schema-valid per Kristal v4 (see pointers doc)
- Output is content-addressed and recorded
### 4.2 Failure handling
- If schema validation fails: stop build, record failure, open Orgo Case
---
## 5) Resolve (Resolved Claim-IR)
### 5.1 Operational checks
- Resolver version pinned and recorded
- Output is schema-valid per Kristal v4
- Ambiguity preserved; no silent coercion
### 5.2 Failure handling
- Stop build on schema invalid output
- Record deterministic error codes for repeated failures
---
## 6) Validate (Validation Report) — the acceptance gate
### 6.1 Operational checks
- Validator version pinned and recorded
- Report is schema-valid per Kristal v4
- Gate decision recorded in Build Record
### 6.2 Failure handling (hard)
- On validation failure:
- Do **not** compile
- Persist the Validation Report ref
- Create an Orgo Case (triage) and attach the report
---
## 7) Compile (Exchange + Runtime Pack)
### 7.1 Preconditions
- Validation gate PASS
- Pinned blueprint + mandate + policy selections recorded
- Compiler version pinned and recorded
### 7.2 Operational checks
- Produced artifacts are schema-valid per Kristal v4
- Manifest refs recorded
- IDs/hashes/signatures verified at rest (spot-check or full verify per policy)
### 7.3 Failure handling
- If compile fails: record failure, do not distribute, open Orgo Case
---
## 8) Distribute (channels)
### 8.1 Publish rules
- Distribution is keyed by Release Record intent
- Packs are immutable; publishing creates new version identifiers
### 8.2 Failure handling
- If publish fails mid-way: mark release as failed and do not advance cohorts
---
## 9) Activate (Konnaxion)
### 9.1 Preconditions
- Pack fetched successfully
- Verification is **fail-closed**:
- signature verification
- hash verification
- compatibility policy check
### 9.2 Activation rules
- Atomic switch of active pack
- Deterministic rollback to last-known-good on failure
- Downgrade prevention per compatibility policy
---
## 10) Observability (minimum signals)
### 10.1 Pipeline metrics
- Stage durations
- PASS/FAIL/SKIP counts
- Validation failure codes
- Compile failure codes
### 10.2 Distribution metrics
- Fetch success rate
- Verify failures (by reason)
- Activation/rollback events
### 10.3 Audit linkage
Every metric/event MUST reference:
- `build_id` and/or `release_id`
- associated artifact refs (where applicable)
---
## 11) Incident playbook triggers (examples)
- Repeated validation failures for the same blueprint/policy set
- Increase in activation verify failures
- Increase in rollback events
- Pack distribution channel drift (unexpected “latest”)
---
## 12) Operator checklist (quick)
- Identify `build_id` / `release_id`
- Retrieve Build/Release Records
- Retrieve referenced Kristal artifacts (Validation Report, manifests)
- Confirm gate outcomes and failure reasons
- If activation incident: confirm rollback executed and downgrade prevention state
- Create/attach Orgo Case and Tasks for remediation
================================================================================================
FILE: docs_technical/50-operations/releases.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 9231e59dcef97aa74037adaed849bcd524465ff13b8deaeb01624850eac2a194
CONTENT_BYTES: 3541
================================================================================================
# Releases
**Purpose:** Define how kOA turns a successful build into a controlled rollout, with verified distribution, activation, monitoring, and rollback.
This page describes **kOA release operations**. It does not define Kristal artifact formats.
## 1) Inputs to a release
A release is initiated when Orgo has:
* A **Build Record** (kOA-owned) for an eligible build
* A validation outcome of **PASS**
* References to Kristal-produced artifacts:
* Exchange reference (opaque)
* Runtime Pack reference (opaque)
* A pinned **Mandate Bundle** (governance + policy)
* A target rollout plan (channels/cohorts/regions)
## 2) Release stages (operational)
1. **Eligibility check**
* Build status is PASS
* Required approvals exist (per Mandate)
* Required artifact references exist
* Target channel is allowed
2. **Candidate publication**
* Publish/announce the candidate Runtime Pack ref to the distribution store/channel tooling
* Record the release intent (Release Record)
3. **Verification pre-check**
* Confirm the candidate pack can be fetched
* Confirm required signer keys are available and not revoked
* Confirm compatibility policy allows this pack for the target cohort
4. **Rollout**
* Gradual cohort expansion (canary → partial → full), or pinned rollout
* Enforce “no silent jumps” (explicit cohort size changes)
5. **Monitoring**
* Activation success rate
* Verification failure reasons
* Error budget / incident triggers
6. **Promotion / pin**
* If metrics are healthy, promote to “latest” and/or pin
* Record final state in Release Record
7. **Rollback (if triggered)**
* Deterministic selection of rollback target (pinned or last-known-good)
* Stop further rollout, revert cohorts, mark the candidate as rejected/revoked if needed
## 3) Channels, cohorts, and pinning
* **Channel:** logical lane (e.g., `canary`, `stable`, `lts`)
* **Cohort:** subset of clients (region, tenant, app version, feature flag)
* **Pinned:** clients must remain on a specific pack ID until explicitly changed
Rules (typical):
* Canary channel moves fastest, smallest cohorts
* Stable channel requires stricter thresholds
* LTS channel changes only with explicit approval and longer bake windows
* Pinning overrides “latest” resolution
## 4) Required invariants
* **Fail-closed activation:** clients must not activate an unverified pack.
* **Atomic switch:** activation is all-or-nothing.
* **Deterministic rollback:** rollback target selection must be deterministic under the policy.
* **No truth mutation:** releases change what pack is active, not canonical truth itself.
* **Auditable intent:** every promotion, pin, and rollback is recorded.
## 5) Rollback triggers (examples)
* Activation success rate drops below threshold
* Verification failures spike (e.g., signature mismatch, revoked signer)
* Crash/error rates exceed SLO
* Pack compatibility failures exceed threshold
* Security advisory or key compromise event
## 6) Operational records
kOA should record:
* **Release Record**: intent + current rollout state
* Activation metrics snapshots (by cohort/channel)
* Decisions: promote, pin, pause, rollback (with actor + reason)
## 7) What to reference for Kristal specifics
All field-level definitions for:
* Exchange / Exchange Manifest
* Runtime Pack / Runtime Pack Manifest
* Canonicalization and signing
are defined in the pinned Kristal v4 specification referenced in:
* `docs/40-integration/kristal-v4/contract-pointers.md`
================================================================================================
FILE: docs_technical/50-operations/rollback.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 80526a1664da06a95be5478fbde9c09f50c789b76b1da668bdf3bcc63c8781b1
CONTENT_BYTES: 8789
================================================================================================
# Rollback
**Normative for kOA:** YES
**External normative reference:** Kristal v4 (pinned)
This runbook defines how kOA rolls back deployments safely and deterministically. Kristal v4 defines artifact validity; rollback procedures reference Kristal artifacts only by **opaque IDs** and rely on **verification** at activation time.
## Goals
* Restore a **last-known-good (LKG)** runtime state per channel/environment.
* Prevent partial or inconsistent activation across a rollout surface.
* Preserve auditability: every rollback produces a **Release Record** update (or a dedicated rollback record) and an Orgo trail.
## Definitions
* **Channel:** a named deployment lane (e.g., `prod`, `staging`, `canary`, `eu-prod`).
* **Target:** a concrete environment/cluster/edge group within a channel.
* **Active Pack:** the currently serving Runtime Pack for a target.
* **LKG Pack:** the most recent pack that was fully verified and healthy for the same target.
* **Rollback:** switching Active Pack from current → LKG (or another explicitly selected prior pack).
## Rollback types
1. **Automatic rollback (activation-time)**
* Triggered when activation preflight fails or health checks fail during rollout.
2. **Operator-initiated rollback**
* Triggered by incidents, regressions, policy/safety concerns, or customer impact.
3. **Emergency rollback**
* Triggered by integrity compromise suspicion, unsafe behavior, or widespread outage.
* May include freezes and trust/allowlist changes.
## Preconditions and safety gates
Rollback MUST be blocked if any of the following are true:
* No verified LKG pack exists for the target.
* The rollback candidate pack is not available in the artifact store.
* Activation preflight cannot run (e.g., verification subsystem down).
* The target is in a state requiring manual intervention (e.g., corrupted runtime, missing dependency) and “safe mode” must be used.
Rollback SHOULD be blocked (or require explicit override) if:
* The rollback candidate is older than policy permits for the channel.
* The rollback candidate is incompatible with the current runtime version.
* The rollback would violate an active governance constraint (unless emergency procedures apply).
## Inputs (required)
* `channel`
* `targets` (one or many)
* `rollback_reason` (structured: incident ID, regression ID, policy trigger)
* `rollback_mode` (automatic/operator/emergency)
* `candidate_pack_id` (optional; if omitted, use LKG)
* `release_record_id` (if rolling back a specific release)
* `operator_id` (for operator/emergency)
## Outputs (required)
* Updated **Release Record** (or a new rollback entry) including:
* previous active pack ID
* new active pack ID
* scope (channel/targets)
* timestamps
* reason + authorizing entity
* Konnaxion activation events:
* activation attempt IDs
* per-target outcomes
* Orgo Tasks/Case updates (if operator initiated)
## Default policy
* Prefer **automatic rollback** on activation failure unless a channel explicitly disables it.
* Prefer **LKG rollback** unless the operator explicitly chooses another prior pack.
* Rollback is **idempotent**: repeating the same rollback request should not produce inconsistent state.
## Procedure: operator-initiated rollback (standard)
1. **Freeze promotions (channel)**
* Prevent new activations while rollback runs.
* If a release pipeline is mid-flight, halt at the next safe boundary.
2. **Select candidate**
* If `candidate_pack_id` is not provided:
* choose **LKG** for each target (can differ by target if policy allows)
* If provided:
* confirm it is a previously deployed pack for the same channel family (unless override)
3. **Preflight**
* For each target:
* verify candidate pack availability
* run activation preflight (integrity + compatibility + policy gates)
* confirm rollback will not strand dependent components (if runtime requires paired components)
4. **Execute rollback**
* Perform activation to the candidate pack per target.
* Use the channel’s rollout policy:
* all-at-once (small surfaces)
* staged (clusters → regions → global)
* canary-first (recommended)
* Enforce “no partial completion” unless explicitly configured:
* if any stage fails, stop and proceed to “rollback of rollback” decision.
5. **Post-check**
* Validate health and correctness signals:
* runtime health checks
* key business metrics
* safety/policy guard telemetry
* Confirm the active pack ID matches expected on all targets.
6. **Record and unfreeze**
* Update Release Record / rollback entry.
* Close/advance the Orgo Task.
* Unfreeze promotions only after:
* stability window criteria met (channel-defined), or
* operator override with documented reason.
## Procedure: automatic rollback (activation-time)
Automatic rollback is triggered when rollout detects:
* activation preflight failure
* post-activation health check failure
* policy enforcement failure (channel-defined)
Steps:
1. Stop further rollout in the same stage.
2. Attempt rollback to the last-known-good pack for the failing target(s).
3. If rollback succeeds:
* mark rollout as failed and require human approval to proceed.
4. If rollback fails:
* escalate to emergency procedure.
* place targets in safe mode if supported.
## Procedure: emergency rollback
Use when there is strong evidence of integrity compromise, unsafe behavior, or fast-spreading outage.
1. **Immediate freeze**
* Freeze promotions and activations for the entire channel (or all channels if global).
2. **Scope containment**
* Identify impacted targets and expand scope conservatively if uncertain.
3. **Rollback to LKG**
* Execute rollback with priority on restoring safe operation.
* If LKG is unavailable or fails preflight, select the most recent prior verified pack that passes preflight.
4. **If rollback cannot restore safety**
* Enter **safe mode**:
* deny/disable unsafe capabilities
* serve minimal safe responses
* disable optional modules that may be triggering failures
* Keep service alive only if safe mode is explicitly approved for that channel.
5. **Trust response (if integrity concern)**
* Rotate or revoke trust material as required by policy.
* Require conformance re-verification before any new promotion.
6. **Audit + incident**
* Open/attach an incident.
* Record all decisions and activation events in Release Record + Orgo.
## Decision guide
Rollback is the correct action if:
* A newly activated pack causes elevated errors, regressions, or unsafe outcomes.
* Policy enforcement is not functioning as expected.
* Determinism or verification guarantees are in question.
* Activation is partially complete and must be normalized quickly.
Do not rollback (or rollback only after containment) if:
* The issue is purely upstream (inputs) and the active pack is not implicated.
* The issue is confined to a single target with environmental failure (prefer repair).
* The rollback candidate is known-bad for the same failure class.
## Rollback failure handling
If rollback activation fails on any target:
* Stop further actions for that stage.
* Attempt rollback to an earlier candidate (prior LKG) if policy allows.
* If no candidate passes preflight:
* place target into safe mode (if supported)
* escalate to incident response
* require manual remediation
## Observability requirements
During rollback, the system must emit:
* per-target activation attempt events
* preflight outcomes (pass/fail + reason codes)
* post-activation health results
* the final active pack ID per target
Dashboards/alerts should include:
* rollback success rate by channel and environment
* time-to-restore by incident
* repeated rollback loops (flapping)
* divergence: reported active pack ID vs expected
## Operational hygiene
* Maintain at least **N prior verified packs** per channel (policy-defined) to ensure rollback availability.
* Periodically perform **rollback drills** in non-prod and canary channels.
* Treat frequent rollbacks as a signal:
* investigate pipeline quality, conformance tests, and gating strictness.
* Ensure rollback tooling is compatible across runtime versions (backward compatibility plan).
## Orgo integration
Operator-initiated and emergency rollbacks must be expressed as:
* an Orgo Case (incident/regression)
* one or more Orgo Tasks:
* `freeze-promotions`
* `rollback-activation`
* `post-rollback-validation`
* `unfreeze-promotions` (optional gated task)
Rollback tasks must reference:
* channel/targets
* candidate selection rule or explicit candidate IDs
* required validations and success criteria
================================================================================================
FILE: docs_technical/60-guides/implementers.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: ff8fae13a7fb6387de10db86d204c1c1ae601497fc32e50d4c6a19d46a42d674
CONTENT_BYTES: 5796
================================================================================================
# Implementers Guide (kOA)
**Audience:** engineers implementing kOA components or integrating existing systems into the kOA stage spine.
**Normative scope:** kOA behavior and integration expectations.
**External normative dependencies:** Kristal v4 artifact contracts (pinned in `../40-integration/kristal-v4/`).
---
## 1) What you are implementing
kOA is a contract-driven ecosystem with a strict stage spine:
1) Ingest inputs (Orgo)
2) Extract Claim-IR
3) Resolve to Resolved Claim-IR (SenTient)
4) Validate (deterministic gate)
5) Compile (Kristal) → Exchange + Runtime Pack
6) Distribute / activate / rollback (Konnaxion)
7) Render (Architect-Render)
8) Execute (SwarmCraft / local runtime)
9) Feedback (governed; creates new work)
Your implementation is conformant if:
- it respects the stage ordering and gates,
- it produces/consumes the correct artifact types at boundaries,
- it is deterministic where required, and
- it is fail-closed where required.
---
## 2) Hard rules (must not violate)
### 2.1 Truth boundary
Only validated + compiled artifacts become canonical. Downstream components must not mutate canon.
### 2.2 No compile on fail
Validation failure must block compilation and publication.
### 2.3 Fail-closed distribution
Activation must verify integrity and compatibility before switching active packs.
### 2.4 Deterministic rendering
Rendering must be deterministic and must not introduce new facts.
---
## 3) Boundary contracts you must treat as external truth
Do not re-implement or “re-interpret” these contracts in kOA docs or code:
- Kristal Exchange contracts
- Runtime Pack contracts
- Canonicalization profiles/versions
- Hash/sign target rules
Instead, depend on the pinned Kristal v4 reference and schemas:
- `../40-integration/kristal-v4/pinned-dependency.md`
- `../40-integration/kristal-v4/contract-pointers.md`
---
## 4) Component implementation notes
### 4.1 Orgo (governance + pipeline)
Implement Orgo as the deterministic controller:
- enforces stage ordering and gates
- records content-addressed references for stage outputs
- emits Build/Release records
- blocks compilation on validation failure
Minimum implementation deliverables:
- stage runner with stable state machine
- artifact store interface (content refs)
- policy selection handling
- audit trail (immutable records, append-only where possible)
### 4.2 Extractors (inputs → Claim-IR)
Extractor outputs are pre-truth:
- must be schema-valid for Claim-IR (as defined in Kristal)
- must be reproducible given the same input snapshot set
- if using probabilistic extraction, pin seeds/models or freeze outputs upstream
### 4.3 SenTient (Claim-IR → Resolved Claim-IR)
Resolution must:
- preserve ambiguity explicitly
- normalize literals deterministically
- produce stable candidate ordering with tie-breakers
- emit stable warnings/errors (codes not free-text)
### 4.4 Validator (deterministic gate)
Validation must:
- accept the same inputs and produce the same Validation Report output
- produce stable error codes and categories
- be fail-closed in Orgo (no compile if validation fails)
### 4.5 Kristal compiler integration
You do not “define” Kristal outputs here. You:
- call the pinned Kristal compiler
- persist outputs and references
- publish artifacts through Orgo’s release workflow
### 4.6 Konnaxion (distribution/activation)
Implement distribution as:
- verify → stage → atomic switch
- deterministic rollback
- downgrade prevention (if policy requires)
- telemetry emission to Orgo
### 4.7 Architect (Strategy vs Render)
- Strategy proposes work (plans/cases/tasks) but does not mutate canon.
- Render produces deterministic bundles with trace coverage.
### 4.8 SwarmCraft / Runtime (execution)
Execution must:
- treat packs as read-only
- record telemetry deterministically (structure stable)
- surface failures with stable codes
- never mutate canon directly (feedback becomes new governed work)
---
## 5) Required records (kOA-owned)
kOA implementations must produce these operational records (schemas are in `../30-artifacts/schemas/`):
- Build Record
- Release Record
- Orgo Case / Task
- (Optional) Konnaxion State / Activation Records (if standardized)
These are kOA-owned and may evolve independently of Kristal, but must not conflict with Kristal artifact contracts.
---
## 6) Determinism checklist
Your component should answer “yes” to:
- Do identical pinned inputs produce identical outputs?
- Is ordering stable and explicitly defined?
- Are failure modes stable (codes/categories) across runs?
- Are all external dependencies either pinned or forbidden in deterministic mode?
- Are seeds/models pinned when probabilistic behavior exists?
If any answer is “no”, the nondeterminism must be moved upstream of the truth boundary and frozen as an input artifact.
---
## 7) Security checklist
- No secret material in logs/telemetry.
- Verify pack integrity before use (fail-closed).
- Sandbox untrusted code/data (especially pack routines).
- Deny network access by default in deterministic modes.
- Enforce quotas/timeouts; prefer explicit policy configuration.
---
## 8) Conformance tests you should run
Minimum tests (see `../40-integration/kristal-v4/conformance.md`):
- deterministic rebuild (same inputs/config/policy → same IDs/hashes)
- fail-closed validation/activation behavior
- deterministic rendering outputs and trace coverage
- rollback determinism
---
## 9) Versioning and compatibility
- Treat Kristal as a pinned dependency; upgrades require an explicit change record and conformance rerun.
- kOA record schemas should use SemVer and be backward compatible where possible.
- Any change affecting gates, determinism, or activation semantics requires an ADR.
---
================================================================================================
FILE: docs_technical/60-guides/integrators.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 0938ef7575a087d190a4948001720c5b250751ba100ae2142b3bde315baa7766
CONTENT_BYTES: 5365
================================================================================================
# Integrator Guide (kOA)
## Purpose
This guide explains how to integrate a system into the kOA Digital Ecosystem as a producer/consumer of kOA-native operational artifacts and as a consumer/producer of Kristal artifacts **via the pinned Kristal v4 dependency**.
This guide does **not** redefine Kristal schemas or artifact formats.
---
## 1) Integration entry points
### A) Integrating as an input producer
You provide upstream inputs that eventually become canonical via validation + Kristal compilation.
Typical integrations:
- ingest raw data feeds into the input pipeline
- submit curated evidence bundles
- provide domain-specific extractors that emit Claim-IR candidates (if you operate that stage)
You must:
- provide stable provenance metadata
- support content-addressed input snapshots (or equivalent reproducible input references)
- use deterministic processing settings where required by policy
### B) Integrating as a pipeline stage service
You implement a stage component (e.g., extractor, resolver, validator adjunct) controlled by Orgo.
You must:
- accept inputs as explicit artifact references (not implicit shared state)
- produce outputs as explicit artifacts (content-addressed where applicable)
- emit stable reason codes on failure
- be idempotent under retry
### C) Integrating as a distribution/activation consumer
You run Konnaxion or consume Konnaxion outputs.
You must:
- verify and activate runtime artifacts fail-closed
- support deterministic rollback
- emit operational state/telemetry back to Orgo
See `docs/50-operations/rollback.md` and `docs/30-artifacts/konnaxion-state.md`.
---
## 2) Normative sources (do not duplicate)
### Kristal artifacts
All Kristal artifacts (Exchange, Runtime Pack, Validation Report, etc.) are externally specified.
Use:
- `docs/40-integration/kristal-v4/pinned-dependency.md`
- `docs/40-integration/kristal-v4/contract-pointers.md`
- `docs/40-integration/kristal-v4/conformance.md`
### kOA-native artifacts
kOA-native operational artifacts are specified here:
- `docs/30-artifacts/` and `docs/30-artifacts/schemas/`
---
## 3) Required integration contracts
### A) Identity and references
Your integration should treat artifact references as immutable and stable:
- never overwrite canonical artifacts in place
- always create a new artifact/ref for changes
- propagate references through Orgo (Build/Release records) rather than “out-of-band” IDs
### B) Determinism requirements
If your component participates in a deterministic gate, you must:
- pin non-deterministic dependencies (models, templates, configs)
- avoid time-based randomness unless explicitly recorded as an input
- produce stable outputs for the same inputs
### C) Fail-closed behavior
If you cannot verify or validate:
- do not proceed
- return a stable failure reason code
- emit enough telemetry for an operator to diagnose without guessing
---
## 4) Integration patterns
### Pattern 1 — Upstream feed → Orgo ingest
1. Your system publishes inputs + provenance.
2. Orgo ingests and records snapshot references.
3. Downstream stages proceed under Orgo control.
Checklist:
- provenance fields complete
- snapshot references immutable
- inputs discoverable for rebuild
### Pattern 2 — External validator adjunct
1. Orgo runs the canonical validation gate.
2. Your service provides additional checks (lint, domain constraints, policy evaluation).
3. Results are returned as structured findings.
4. Orgo decides pass/fail under policy.
Checklist:
- deterministic check outputs
- stable finding IDs and reason codes
- no mutation of truth artifacts
### Pattern 3 — Runtime Pack distribution mirror
1. Your system mirrors pack distribution to edge/offline environments.
2. Konnaxion verifies signatures/hashes.
3. Activation occurs atomically, rollback deterministic.
Checklist:
- fail-closed verification
- multi-version cache supported
- rollback path tested
---
## 5) Required telemetry
You should emit (minimum):
- build/release correlation IDs (from Orgo)
- stage timing (start/end/fail)
- stable error codes + human-readable summaries
- references to logs/traces (not raw blobs in-band)
If you operate Konnaxion:
- emit Konnaxion State records (`docs/30-artifacts/konnaxion-state.md`)
- report activation/rollback outcomes and health signals
---
## 6) Security expectations
Integrators must:
- secure any signing/verifying keys (never embed in jobs or logs)
- authenticate Orgo control-plane requests
- enforce least privilege for stage execution workers
- log privileged actions with audit-grade detail
---
## 7) Compatibility and migration
If you are migrating from earlier Kristal conventions:
- follow `docs/40-integration/kristal-v4/legacy-compat.md`
- do not emit legacy spellings at boundaries
- track normalization metrics until legacy usage is eliminated
---
## 8) Go-live checklist
- [ ] You can run end-to-end with deterministic settings (where required).
- [ ] You handle retries idempotently.
- [ ] You emit stable reason codes on failure.
- [ ] You validate against the correct schemas (kOA-native locally; Kristal via pinned dependency).
- [ ] You verify/activate/rollback fail-closed (distribution consumers).
- [ ] You provide telemetry refs (logs/traces/metrics) tied to build/release IDs.
- [ ] You have an operator escalation path for failed gates/rollouts.
================================================================================================
FILE: docs_technical/60-guides/testing.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 42cffdfd24d00b4a5233307bf1ec9b5898bf698bb865209a19929abe4206bbc9
CONTENT_BYTES: 4754
================================================================================================
# Testing (kOA)
**File:** `docs/60-guides/testing.md`
**Normative scope:** kOA testing expectations and test organization.
**Non-normative:** Kristal artifact schemas/formats (external); this guide references the pinned Kristal v4 dependency for schema validation.
---
## 1) Purpose
Define the kOA test strategy and minimum suite required to ensure:
- deterministic behavior across the pipeline,
- correct stage gating (“no compile on fail”),
- fail-closed verification and activation,
- conformance to the pinned Kristal v4 schemas where kOA produces/consumes Kristal artifacts,
- reliable operations (rollback, incident handling, observability).
---
## 2) Test layers
### 2.1 Unit tests (component-local)
Scope:
- deterministic pure functions
- schema helpers
- validators
- policy evaluators
- hash/signature utilities (kOA side)
Examples:
- normalization helpers (SenTient)
- manifest parsing and strict validation logic
- downgrade-prevention logic (Konnaxion)
### 2.2 Contract tests (boundary artifacts)
Scope:
- producer emits artifact that validates against its schema
- consumer rejects malformed artifacts
- stable error codes and failure shapes
Rule:
- For Kristal artifacts, use the **pinned Kristal v4 schemas** (do not copy schemas into kOA).
See: `docs/40-integration/kristal-v4/pinned-dependency.md`.
### 2.3 Integration tests (multi-component)
Scope:
- Orgo → Extract → SenTient → Validate → (Kristal compile) → Konnaxion verify/activate
- “happy path” and controlled failures
- telemetry emission
### 2.4 End-to-end tests (release simulation)
Scope:
- build + publish + staged rollout
- cohort targeting
- rollback under controlled conditions
- audit evidence completeness
---
## 3) Minimum required test suite (kOA)
### 3.1 Determinism
- **Rerun determinism**: identical pinned inputs/resources/policies → identical outputs
- **Ordering determinism**: stable ordering for lists/maps; no nondeterministic iteration
- **Golden fixtures**: fixed fixtures for:
- Claim-IR
- Resolved Claim-IR
- Validation Report
- Runtime Pack verification flows
### 3.2 Gate semantics
- **No compile on fail**: validation failure prevents any publish/packaging step
- **Explicit failure artifacts**: failures produce structured reports, not partial truth
### 3.3 Schema conformance
- Validate all emitted artifacts against their schemas.
- For Kristal artifacts, validate against pinned Kristal v4 schemas.
- For kOA-native artifacts (Orgo Task/Case, Build Record, Release Record, etc.), validate against kOA schemas under `docs/30-artifacts/schemas/`.
### 3.4 Verification + activation (fail-closed)
- Corrupted payload hash → activation must fail
- Missing payload → activation must fail
- Invalid signature/trust root → activation must fail
- Schema invalid → activation must fail
- Compatibility mismatch / downgrade attempt → activation must fail
### 3.5 Rollback
- Rollback to last-known-good is deterministic
- Rollback emits required audit events and telemetry
- Partial activation cannot occur (atomic switch verified)
### 3.6 Observability and audit
- Required structured events are emitted for:
- stage start/finish
- validation outcomes
- verification outcomes
- activation/rollback
- Evidence links exist for:
- Build Record
- Release Record
- active pack reference (and history)
---
## 4) Test data and fixtures
### 4.1 Fixture categories
- **tiny**: minimal valid artifacts for fast checks
- **golden**: representative “real” artifacts for regression
- **adversarial**: malformed/edge-case artifacts
- **compat**: multi-version artifacts to test downgrade prevention and compatibility policies
### 4.2 Fixture management
- Fixtures must be content-addressed and versioned
- Any fixture change requires:
- reason
- expected behavior update
- snapshot of previous expected outputs (for auditability)
---
## 5) Suggested CI gates
Minimum CI pipeline stages:
1. Lint / static checks
2. Unit tests
3. Contract tests (schemas)
4. Integration tests (pipeline spine)
5. End-to-end rollout simulation (nightly or pre-release)
6. Conformance report publication (kOA-native artifact, optional)
---
## 6) Failure triage playbook (testing perspective)
When a test fails, capture:
- pinned versions (code, policy bundle, resource bundles, Kristal dependency)
- input references (snapshots/fixtures)
- full diagnostics artifacts (validation report, verification logs)
- reproduction command or harness
---
## 7) Related docs
- Conformance checklist: `docs/40-integration/kristal-v4/conformance.md`
- Operations pipeline: `docs/50-operations/pipeline.md`
- Rollout/rollback: `docs/50-operations/rollback.md`
- Determinism: `docs/10-system/determinism.md`
================================================================================================
FILE: docs_technical/60-guides/tooling.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: b42efa5455d44955ad8e324b44bf95603c93e2ab90a57a025b731f1b73034605
CONTENT_BYTES: 3006
================================================================================================
# Tooling
**Purpose:** Describe the tooling expectations for working with kOA docs, artifacts, builds, releases, and conformance—without embedding Kristal contract definitions.
## 1) Documentation toolchain (recommended)
* **Markdown-first** docs under `docs/`
* A static site generator (pick one):
* MkDocs (simple)
* Docusaurus (richer)
* Sphinx/MD (if you already use it)
Baseline expectations:
* Link checking in CI (no broken internal links)
* Spellcheck / style lint (optional)
* Build the docs site on every main-branch merge
## 2) Schema and contract tooling
kOA-owned schemas live under:
* `docs/30-artifacts/schemas/`
Recommended tooling:
* JSON Schema validation in CI (Draft 2020-12)
* Schema versioning policy:
* bump `urn:koa:schema::` when breaking
* semver `record_version` inside records (e.g., `1.0.0`)
Kristal schemas:
* Must be referenced from the pinned Kristal v4 dependency (do not copy/paste into kOA).
## 3) Build tooling (Orgo)
Minimum CLI/automation capabilities:
* `orgo build start` (create build + record trigger)
* `orgo build status `
* `orgo build artifacts ` (list content refs)
* `orgo build export ` (export Build Record + referenced metadata)
Recommended:
* Determinism checks (same inputs/policy/toolchain → same content refs)
* Artifact store client tooling (push/pull by content ref)
## 4) Release tooling
Minimum CLI/automation capabilities:
* `orgo release create --build --channel --cohort `
* `orgo release promote --release --percent `
* `orgo release pin --release --pack [`
* `orgo release rollback --release [--policy pinned|lkg]`
* `orgo release status `
Konnaxion-side tools (often separate):
* `konnaxion verify `
* `konnaxion activate `
* `konnaxion rollback [--to |--policy lkg]`
* `konnaxion active`
## 5) Conformance and validation tooling
kOA should maintain a conformance suite that checks:
* Build Record schema validity
* Release Record schema validity
* Konnaxion activation invariants (fail-closed, atomic, deterministic rollback)
* Kristal artifact conformance via pinned Kristal schemas:
* Exchange/Pack artifacts validate against the pinned spec
* canonicalization identifiers match the pinned requirements
* signatures/keys policy enforced (as configured in kOA profile)
## 6) Operational observability tooling
Minimum:
* Structured logs for build/release/activation events
* Metrics export:
* build stage durations
* validation pass/fail
* activation success/fail
* rollback events and triggers
* Trace/audit store for immutable records
Recommended:
* Dashboard templates per channel/cohort
* Alert rules tied to rollback triggers
## 7) Repo maintenance tooling (quality gates)
* Pre-commit hooks (format + lint)
* CI gates:
* docs build
* link check
* schema validation
* conformance tests
* security scanning for dependencies (as applicable)
================================================================================================
FILE: docs_technical/90-reference/adr/adr-0001-truth-boundary.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 8b5f126d606f8343ff3ae34feb92acad7461c318e23eba8124a7bb4445cdbe23
CONTENT_BYTES: 2808
================================================================================================
# ADR-0001: Truth Boundary (kOA)
**Status:** Accepted
**Date:** 2026-02-27
**Decision Owner:** kOA Architecture
**Scope:** Ecosystem invariant and operational enforcement (not Kristal schema design)
---
## Context
The kOA ecosystem requires a single, enforceable definition of where “truth” becomes canonical so that downstream systems (distribution, rendering, execution, feedback) cannot accidentally introduce, mutate, or launder unverified claims into canon.
kOA integrates with Kristal as the canonical truth compiler. Kristal v4 defines the normative artifact contracts for Exchange and related Kristal-owned artifacts; kOA must not duplicate those contracts in kOA documentation. kOA must instead enforce the boundary operationally and record evidence.
---
## Decision
1. **Canonical truth exists only after Kristal compilation.**
Upstream artifacts (inputs, Claim-IR, Resolved Claim-IR, validation outputs) are non-canonical until the Kristal compile step produces a canonical Exchange artifact.
2. **No compile on fail.**
If deterministic validation fails, kOA must stop the build pipeline and must not publish or distribute Exchange/Runtime Pack outputs.
3. **Fail-closed distribution and activation.**
Any artifact fetched for activation must be verified (schema compatibility + integrity checks). If verification cannot be completed, activation is rejected and the system rolls back deterministically to the last-known-good state.
4. **Downstream “no new facts.”**
Rendering and execution layers cannot introduce new factual claims into canon. They may:
- trace output to canonical sources,
- emit governed feedback that creates new work (Cases/Tasks),
- but must not mutate canonical truth directly.
---
## Consequences
- Orgo must enforce stage order and gates, and record the full evidence chain for each build/release (inputs → validation → canonical outputs).
- Konnaxion must treat verification as a hard gate for activation and rollback.
- Docs and code must treat Kristal schemas as the normative definitions for Kristal artifacts; kOA docs provide only integration and operational policy.
---
## Implementation notes
- The pinned Kristal dependency is recorded under:
- `docs/40-integration/kristal-v4/pinned-dependency.md`
- kOA operational enforcement points include:
- `docs/50-operations/pipeline.md`
- `docs/50-operations/rollback.md`
- `docs/50-operations/releases.md`
---
## Alternatives considered
- Allow downstream systems to “patch” canon directly (rejected: violates auditability and determinism).
- Duplicate Kristal schemas inside kOA docs (rejected: causes drift and contract divergence).
---
## Links
- `docs/01-principles/02-truth-boundary.md`
- `docs/40-integration/kristal-v4/index.md`
================================================================================================
FILE: docs_technical/90-reference/adr/adr-0002-determinism-policy.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 21dbf02275e596eaf1734c1bf30bd0e35681c5cb4c1f732cb93904002599a41d
CONTENT_BYTES: 4790
================================================================================================
# ADR-0002: Determinism Policy (kOA)
**Status:** Accepted
**Date:** 2026-02-27
**Decision Owner:** kOA Ecosystem Architecture
**Scope:** kOA determinism expectations for pipeline gates, distribution, rendering, and operations.
**Depends on:** Kristal v4 (pinned). Normative artifact formats are defined in Kristal; this ADR defines kOA policy and enforcement.
---
## 1) Context
kOA is a governed ecosystem where **truth** is produced only at the validation→compile boundary, and distribution/activation must be safe under offline and adversarial conditions. Determinism is required to make:
- rebuilds and comparisons meaningful,
- integrity verification stable across toolchains,
- rollouts safe (repeatable activation/rollback),
- audits reproducible.
Kristal v4 defines canonicalization/hashing/signature semantics for Kristal artifacts. kOA must adopt a clear policy for:
- what must be deterministic,
- what may vary (and how variance is recorded),
- what gates enforce determinism,
- how compatibility is handled across versions.
---
## 2) Decision
### 2.1 Determinism levels
kOA defines three determinism levels for components/stages:
1. **Strict Determinism**
- Same pinned inputs + blueprint + policy selections + toolchain versions → identical outputs (byte-identical or canonical-identical).
- Required for: validation gate decisions, Exchange/Runtime Pack compilation targets, verification inputs.
2. **Operational Determinism**
- Outputs may include benign operational variance (timestamps, attempt IDs), but the *deterministic core* must be stable and separately hashed/signed.
- Allowed for: Build Records, Release Records, telemetry envelopes.
3. **Presentation Determinism**
- Rendering must be deterministic for the same pinned Exchange + templates + params, but may include runtime-dependent formatting constraints (screen size) if recorded and traceable.
- Required for: Render bundles, trace maps, refusal/omission events.
### 2.2 Required enforcement points (gates)
kOA enforces determinism at these gates:
- **Validation gate (hard):** deterministic pass/fail and stable error codes for the same resolved inputs.
- **Compile gate:** compile must not run unless validation gate is PASS (“no compile on fail”).
- **Verification gate (distribution/activation):** fail-closed verification of signatures/hashes/compat policy.
- **Render gate:** deterministic outputs + trace coverage; no new facts.
- **Rollback gate:** deterministic rollback decision for a given trigger and stored history.
### 2.3 What must be pinned
To claim determinism at any level, these must be pinned and recorded:
- Input snapshot refs (content-addressed)
- Blueprint ref (schemas/config/templates)
- Mandate ref (policy context), if applicable
- Policy selections (enabled profiles)
- Toolchain identities (component name + version + build hash if available)
---
## 3) Consequences
### 3.1 Allowed variance (must be recorded)
The following may vary without violating kOA determinism policy, provided it is recorded:
- attempt/retry identifiers
- processing timestamps in operational records
- machine/environment metadata (hostnames, regions)
- telemetry sampling (if explicitly configured and recorded)
### 3.2 Disallowed variance
The following is disallowed:
- changing gate outcomes under the same pinned context
- producing different Exchange/Runtime Pack identities for the same pinned context (except when explicitly versioned and recorded as a change)
- accepting unverifiable artifacts (“best effort” verification)
- rendering new facts not traceable to validated lineage
---
## 4) Implementation requirements
### 4.1 Recording requirements (kOA artifacts)
- Build Record must record pinned context + gate outcomes + artifact refs.
- Release Record must record promotion intent + target channels/cohorts + activation expectations.
### 4.2 Test requirements
A conformance suite must include:
- deterministic rebuild tests (same pinned context → same canonical identities)
- verification fail-closed tests (bad signature/hash → no activation)
- rollback determinism tests (same trigger history → same rollback outcome)
- render determinism + trace coverage tests
---
## 5) Migration and compatibility
- Determinism requirements apply from the adoption of the pinned Kristal v4 dependency onward.
- Any relaxation or tightening requires a new ADR and a documented rollout window.
- Legacy acceptance is controlled by `docs/40-integration/kristal-v4/legacy-compat.md`.
---
## 6) References (non-normative)
- Kristal v4 pinned dependency: `docs/40-integration/kristal-v4/pinned-dependency.md`
- kOA pipeline runbook: `docs/50-operations/pipeline.md`
- kOA conformance: `docs/40-integration/kristal-v4/conformance.md`
================================================================================================
FILE: docs_technical/90-reference/adr/adr-0003-konnaxion-activation-rollback.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 432edf312971e1f38b75a32ed4907503d126545cf6d19ac08afff146b49c4a7a
CONTENT_BYTES: 6650
================================================================================================
# ADR-0003: Konnaxion Activation and Rollback
- **Status**: Accepted
- **Date**: 2026-02-09
- **Owner**: Konnaxion (Distribution) + Orgo (Release Control Plane)
- **Scope**: Runtime Pack verification, activation gating, downgrade prevention, rollback, offline/storage behavior
- **Out of scope**: Kristal artifact formats/schemas (normative in Kristal v4); Konnaxion-Social behaviors
---
## Context
Konnaxion distributes Runtime Packs to edge nodes/devices and activates them locally. A bad pack (corrupted, tampered, incompatible, substituted, revoked, or downgraded) can break correctness, safety, reproducibility, and user trust.
We need a deterministic, fail-closed, auditable activation and rollback contract that:
- prevents partial activation,
- prevents downgrade vulnerabilities,
- supports fast rollback,
- preserves offline correctness.
Kristal v4 defines the Runtime Pack and its manifest schema; kOA defines activation policy and operations.
---
## Decision
### 1) Verification-before-activation (fail-closed)
Konnaxion MUST verify a candidate pack before activation.
Verification MUST include (deterministic, profile-defined):
1) Manifest parsing + schema validation (Kristal v4 schema)
2) Integrity verification (as declared)
3) Signature verification (as declared) using pinned trust roots
4) Required-file presence checks for all manifest-declared required paths
If any verification step fails:
- activation MUST NOT proceed
- Konnaxion MUST remain on the current active pack (or last-known-good)
- deterministic diagnostics MUST be emitted (stable reason codes)
### 2) Compatibility checks before activation (mandatory)
Before activation, Konnaxion MUST validate compatibility between:
- pack-declared contract version(s) / required profiles
- local runtime supported versions / capabilities
On incompatibility:
- do not activate
- emit deterministic diagnostics
- remain on current active pack
### 3) Atomic activation (mandatory)
Activation MUST be an atomic switch:
- either the new pack becomes the active pointer, or
- no state changes occur.
Partial activation is forbidden.
### 4) Downgrade prevention with persisted safety state (mandatory)
Konnaxion MUST implement downgrade prevention using deterministic, persisted per-channel state.
Minimum required rule:
- MUST NOT activate a release/version lower than the highest previously activated release in the same channel, unless an explicit policy-authorized rollback is present.
Required persisted state (per channel):
- `highest_activated_release_id`
- (recommended) `highest_seen_release_id`
- last successful verification metadata (artifact_id, signer, timestamp)
Revocation-aware rule:
- MUST NOT activate packs listed as revoked by a verified channel control surface.
Substitution safety:
- If a pack is presented with the same release identifier but different immutable artifact identifier, treat as a hard error unless an explicit reissue authorization is present in a verified control surface.
### 5) Deterministic rollback (mandatory)
Konnaxion MUST support at least one rollback mode:
- **Pinned rollback**: activate an explicitly pinned known-good pack
- **Last-known-good rollback**: activate the most recent previously active verified pack still present and verified
Rollback MUST be:
- explicit (never silent)
- policy-authorized (see below)
- deterministic given the same trigger sequence and verified inputs
Rollback authorization MAY be conveyed via:
- a verified channel index that includes an explicit rollback authorization record, and/or
- an explicit operator action that is auditable and policy-gated (deployment-specific)
Rollback triggers MAY include:
- explicit operator action (recommended)
- verified index updates (e.g., “current revoked”, rollback authorization added)
- local runtime health signals (optional; must be policy-defined)
### 6) Trust roots pinned; offline correctness (mandatory)
Trust roots MUST be pinned per channel scope (tenant/environment/region/audience as applicable) and MUST be verifiable offline.
Trust roots MUST NOT be fetched over the network at activation time as a dependency for correctness.
### 7) Signed channel index as recommended control surface
Konnaxion SHOULD consume a signed per-channel distribution index (e.g., `pack_index.json`).
If present, it MUST be verified using pinned trust roots (fail-closed) and treated as the primary control surface for:
- what is current/latest,
- what is pinned,
- minimum allowed release,
- revocations,
- (optionally) rollback authorization.
### 8) Offline caching and storage contract (mandatory to define)
Konnaxion MUST define deterministic storage + cache policies that support:
- multiple installed versions per channel
- atomic activation pointers
- garbage collection with pinning rules
- retaining at least: active + last-known-good (+ pinned set if used)
If offline, Konnaxion MUST:
- continue serving from the active pack
- not attempt activation requiring network-dependent trust roots
- optionally surface “stale pack” metadata
Recommended layout (example; not normative):
- `////packs//...`
- `////active -> `
- `////state.json` (persisted safety metadata)
---
## Consequences
### Positive
- Prevents silent regressions and downgrade vulnerabilities
- Makes activation decisions auditable and reproducible
- Enables safe offline-first operation and deterministic recovery
### Costs / Requirements
- Requires persistent per-channel state and stable diagnostic codes
- Requires clear policy surfaces for rollback authorization and health-triggered rollback
- Requires deterministic cache/eviction behavior and pinned retention rules
---
## Conformance tests (required)
A conformant Konnaxion-Distribution implementation MUST provide tests for:
- schema validation success/failure (fail-closed)
- integrity verification success/failure (fail-closed)
- signature verification success/failure (fail-closed)
- atomic activation (no partial state)
- downgrade prevention behavior (monotonic + persisted state)
- substitution safety behavior
- revocation-aware activation blocking
- rollback modes and rollback determinism
- offline behavior (serve active; no network dependency for trust roots)
- cache eviction respects active/last-known-good/pinned retention rules
---
## References (kOA)
- `docs/20-nodes/chesed-konnaxion.md`
- `docs/50-operations/releases.md`
- `docs/50-operations/rollback.md`
- `docs/40-integration/kristal-v4/contract-pointers.md`
- `docs/40-integration/kristal-v4/koa-profile.md`
================================================================================================
FILE: docs_technical/90-reference/adr/adr-0004-architect-split.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 33af0f6a845be7d71615a21a1320474da16fbf52f81218ed8df73cdeb4834f7e
CONTENT_BYTES: 2927
================================================================================================
# ADR-0004: Architect split (Strategy vs Render)
**Status:** Accepted
**Date:** 2026-02-27
**Decision Owner:** kOA Ecosystem Architecture
**Scope:** Component boundaries, determinism guarantees, and responsibility separation for the Architect role.
---
## 1) Context
The ecosystem requires:
- a strict truth boundary (canonical truth only after validation + compilation),
- deterministic downstream behavior (rendering and execution must not introduce new facts),
- clear governance over work creation and lifecycle (cases/tasks).
A single “Architect” component combining planning and rendering creates failure modes:
- plans may become implicitly treated as truth,
- rendering may vary based on planning heuristics,
- feedback loops can accidentally mutate canon or hide provenance.
We need explicit responsibility separation.
---
## 2) Decision
Split the Architect role into two components:
1) **Architect-Strategy (Netzach)**
- proposes work (plans → cases/tasks),
- performs prioritization, scheduling, decomposition,
- can use heuristic / probabilistic methods **upstream of truth**,
- does not publish canonical truth artifacts.
2) **Architect-Render (Hod)**
- produces user-facing outputs (Render Bundles),
- must be deterministic given pinned inputs + templates + parameters,
- must not introduce new facts; all factual statements must be traced or deterministically omitted/refused.
---
## 3) Boundaries and interfaces
### 3.1 Strategy → Orgo
- Strategy outputs **work proposals** (plan envelope / case/task creation requests).
- Orgo owns lifecycle state and auditing.
- Strategy must not mutate canon directly; it can only request work.
### 3.2 Render → Consumers
- Render consumes validated artifacts (via Kristal Exchange and/or Runtime Pack) and templates/params.
- Render emits a Render Bundle with a Trace Map sufficient for audit/verification.
---
## 4) Determinism and governance implications
- Strategy is allowed to be non-deterministic, but its outputs must be captured and governed as work objects (cases/tasks).
- Render must be deterministic and policy-driven; if policy disallows an output, Render must deterministically refuse/omit.
---
## 5) Consequences
### Positive
- Clear separation of “decide what to do” vs “explain what is true”.
- Stronger determinism guarantees for downstream artifacts.
- Reduced risk of silent canon mutation through planning behavior.
### Trade-offs
- Requires an explicit plan envelope / routing mechanism to Orgo.
- Requires clear template/parameter pinning for deterministic rendering.
---
## 6) Follow-ups
- Define the minimal Plan → Case/Task request format (kOA-owned artifact) if not already standardized.
- Ensure conformance tests include deterministic Render Bundle checks.
- Update node docs (`docs/20-nodes/netzach-architect-strategy.md`, `docs/20-nodes/hod-architect-render.md`) to reflect this split.
---
================================================================================================
FILE: docs_technical/90-reference/adr/adr-0005-compatibility-versioning.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 28f6e89fb8bff902c6b01c917f4a33a0192cb739614787cba693ad06ba976313
CONTENT_BYTES: 3865
================================================================================================
# ADR-0005: Compatibility & Versioning Policy (kOA)
**Status:** Accepted
**Date:** 2026-02-27
**Decision Owner:** Ecosystem Architecture
**Scope:** kOA-native artifacts + integration compatibility; Kristal pinning strategy
---
## 1) Context
kOA integrates with Kristal as an external, normative artifact system. kOA also defines its own operational artifacts (Cases, Tasks, Build/Release Records, Konnaxion State) and must evolve them without breaking production pipelines.
Historical duplication of external contracts causes drift and ambiguity. Therefore, kOA must:
- pin external dependencies (Kristal) to a known version,
- define clear compatibility rules for kOA-native artifacts,
- treat ambiguous inputs as unsafe and fail-closed.
---
## 2) Decision
### 2.1 Kristal pinning (normative)
kOA MUST treat Kristal as an external dependency and MUST pin:
- a specific Kristal version (tag/commit)
- the exact schema set used for validation and generation
kOA documentation MUST reference Kristal via:
- `docs/40-integration/kristal-v4/pinned-dependency.md`
- `docs/40-integration/kristal-v4/contract-pointers.md`
kOA MUST NOT copy Kristal schemas as kOA-normative contracts.
### 2.2 kOA-native artifact versioning (normative)
All kOA-native artifacts MUST include:
- `schema_version` (semantic version, e.g., `1.2.0`)
- `created_at` timestamps
- stable IDs (UUID or policy-defined IDs)
Schema evolution rules:
- **PATCH** (`x.y.Z`): backward compatible bug fixes; no required-field additions.
- **MINOR** (`x.Y.z`): backward compatible additions (optional fields only).
- **MAJOR** (`X.y.z`): breaking changes (required-field changes, meaning changes, removals).
### 2.3 Compatibility guarantees (normative)
Within a given deployment environment:
- Producers MUST NOT emit artifacts newer than what consumers declare they support.
- Consumers MUST accept the full range of PATCH/MINOR versions within the same MAJOR line, unless explicitly prohibited by policy.
### 2.4 Deprecation policy (normative)
kOA MAY deprecate fields or behaviors, but MUST:
- keep deprecated fields readable for at least one MINOR cycle after deprecation is announced,
- emit warnings when deprecated inputs are used,
- remove deprecated fields only in the next MAJOR version.
### 2.5 Fail-closed on ambiguity (normative)
If an artifact cannot be validated against:
- a known schema version, or
- a pinned external contract (Kristal),
then kOA MUST fail-closed:
- Orgo blocks downstream pipeline steps
- Konnaxion blocks activation
- the failure is recorded with a stable reason code
---
## 3) Compatibility declarations
### 3.1 Producer declarations (recommended)
Producers SHOULD declare:
- supported schema versions they can emit
- maximum supported consumer versions (if constrained)
### 3.2 Consumer declarations (recommended)
Consumers SHOULD declare:
- accepted schema MAJOR lines
- optional feature flags for MINOR additions
---
## 4) Migration handling
### 4.1 Migration windows (recommended)
When introducing a breaking change:
- run dual-acceptance (old + new) in controlled environments
- emit canonical new versions
- convert legacy forms at boundaries only when deterministic and lossless
### 4.2 Legacy spellings for external contracts
Any tolerance for legacy spellings of Kristal-related fields must follow:
- `docs/40-integration/kristal-v4/legacy-compat.md`
---
## 5) Consequences
- External contract drift is prevented by pinning Kristal and referencing it directly.
- kOA-native artifacts evolve under semver rules with explicit compatibility boundaries.
- Operational safety is increased by failing closed on ambiguous inputs.
---
## 6) Follow-ups
- Ensure each kOA-native schema includes `schema_version`.
- Add conformance tests verifying version acceptance rules.
- Document supported versions per environment in ops runbooks.
================================================================================================
FILE: docs_technical/90-reference/adr/index.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: d902b03ababe39c55d1734675bf419291da5bf47caabbc20cb8a81b6608a15b2
CONTENT_BYTES: 1177
================================================================================================
# ADR Index (kOA)
**Purpose:** Architecture Decision Records (ADRs) capture **kOA-owned** decisions: invariants, operational policies, compatibility rules, governance behavior, and component splits.
**Rule:** ADRs must not duplicate Kristal’s normative artifact contracts. When a decision depends on Kristal, the ADR must reference the pinned Kristal v4 dependency (see `docs/40-integration/kristal-v4/pinned-dependency.md`) and point to the specific Kristal doc/schema section.
---
## ADR workflow
### When an ADR is required
Create an ADR when you change:
- kOA invariants (truth boundary, determinism policy, fail-closed rules)
- kOA artifact schemas (Build Record, Release Record, Orgo Case/Task, etc.)
- compatibility or versioning policy
- activation/rollback policy
- component boundaries and responsibilities
- required conformance tests / gates
### Status values
- Draft
- Accepted
- Superseded
- Rejected
### Filename convention
`adr-####-short-slug.md`
---
## ADR list
- `adr-0001-truth-boundary.md`
- `adr-0002-determinism-policy.md`
- `adr-0003-konnaxion-activation-rollback.md`
- `adr-0004-architect-split.md`
- `adr-0005-compatibility-versioning.md`
================================================================================================
FILE: docs_technical/90-reference/terminology.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: bff1dbc6d8b2d5ad6892daafa00b50a8238a985a9c266b218510345fb41538d8
CONTENT_BYTES: 4381
================================================================================================
# Terminology (kOA)
**File:** `docs/90-reference/terminology.md`
**Purpose:** Provide a concise, kOA-first vocabulary with explicit mapping to external Kristal terms where applicable.
**Rule:** If a term is defined normatively in Kristal v4, kOA references it rather than redefining it.
---
## 1) kOA ecosystem terms (system-level)
### Artifact
A typed payload exchanged at a boundary. In kOA, artifacts are the only way truth, governance state, and operational intent move between components.
### Truth boundary
The point where “truth” becomes canonical: after deterministic validation and compilation into a Kristal Exchange.
### Gate
A deterministic stage check enforced by Orgo (and/or other control-plane nodes) that can stop the pipeline.
### No compile on fail
Gate rule: if validation fails, compilation/publishing of canonical truth artifacts must not occur.
### Control plane
The governance/orchestration layer (primarily Orgo) that enforces stage order, gates, auditability, and release intent.
### Data plane
The content and distribution layer (artifacts and payloads) that is produced/verified/served to consumers.
---
## 2) Nodes (kOA component names)
### Orgo
kOA governance and orchestration node. Enforces stage order, gating, audit records, and release workflows.
### Konnaxion
Connectivity and distribution node. In distribution mode: verifies, activates, rolls back Runtime Packs fail-closed.
### SenTient
Resolution engine that converts Claim-IR → Resolved Claim-IR while preserving uncertainty.
### Architect-Strategy
Planning node that proposes work (cases/tasks) and objectives; does not publish truth.
### Architect-Render
Deterministic renderer that produces user-facing outputs with traceability and no-new-facts constraints.
### SwarmCraft
Execution node that runs governed tasks and emits telemetry; does not mutate canonical truth directly.
### EkoH
Ledger and scoring subsystem (trust/ethics/weights) used for governance and influence.
### Kristal (truth pivot)
Compilation boundary that produces canonical Exchange and derived Runtime Packs.
---
## 3) kOA-native artifacts (owned by kOA)
### Orgo Case
Operational container grouping context and tasks under a lifecycle.
### Orgo Task
Canonical unit of work for execution/processing; has strict lifecycle semantics at APIs.
### Build Record
kOA record of a pipeline run: pinned inputs, pinned policies/resources, stage outputs, and references to published artifacts.
### Release Record
kOA record of distribution intent and rollout/activation outcomes across channels/cohorts.
### Konnaxion State (local)
Local operational metadata describing active pack, cache layout, activation history, rollback state.
---
## 4) Kristal artifacts (external, referenced)
kOA uses these terms as **references** to the pinned Kristal v4 dependency:
### Claim-IR
Pre-truth proposed claims produced by extractors.
### Resolved Claim-IR
Pre-truth resolved claims produced by SenTient.
### Validation Report
Deterministic report produced by the validation stage and used as the compilation gate input.
### Kristal Exchange / Exchange Manifest
Canonical truth artifact produced by Kristal compilation.
### Runtime Pack / Runtime Pack Manifest
Derived offline package produced from the Exchange, verified and activated by Konnaxion.
### Render Bundle
Deterministic output artifact produced by Architect-Render containing outputs and trace mapping.
---
## 5) Common mappings and aliases (avoid ambiguity)
### Exchange ID / kristal_id
If both terms appear historically, prefer the Kristal v4 term and treat any alias as legacy.
### Key identifier
Prefer `key_id` (kOA) when describing signature references; treat `kid` as a legacy alias if encountered in older docs.
### Policies
Prefer “policy bundle / pinned policy ref” over ad hoc field names; kOA stores references, Kristal defines canonical manifest structures externally.
---
## 6) Versioning language
### Pinned dependency
A specific, immutable Kristal version (tag/commit) used for validation and conformance.
### Compatibility policy
Rules describing what versions/packs can be activated, including downgrade prevention.
### Legacy compatibility window
A defined period where older spellings/aliases may be accepted on input, but canonical forms are emitted and validated for publication/activation.
---
================================================================================================
FILE: docs_technical/index.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 6034c826804c389417fede25461b449b8ead2c1a5a934d4a024fb7662350b778
CONTENT_BYTES: 2589
================================================================================================
# kOA Digital Ecosystem Documentation
kOA is an ecosystem for producing, distributing, and operating deterministic knowledge-backed runtime behavior across environments. It defines the **system architecture**, **node responsibilities**, **kOA-owned artifacts**, and **operational workflows**. Kristal defines the **normative boundary artifacts** (Exchange, Runtime Pack, Render Bundle, etc.).
## Non-redundancy rule
* **Kristal v4 is the sole normative source** for Kristal artifact contracts and schemas.
* kOA documentation **must not duplicate** Kristal schemas, field lists, or canonicalization rules.
* kOA documentation may define **kOA-specific constraints and profiles** for how kOA uses Kristal v4.
See: `40-integration/kristal-v4/`
## Start here
* System summary: `00-overview/system-at-a-glance.md`
* Architecture & invariants: `10-system/architecture.md`, `10-system/trust-boundaries.md`, `10-system/determinism.md`
* Nodes (interfaces + responsibilities): `20-nodes/index.md`
* kOA-owned artifacts + schemas: `30-artifacts/index.md`
* Kristal integration (pinned + profile + conformance): `40-integration/kristal-v4/index.md`
* Operations (pipeline, release, rollback): `50-operations/pipeline.md`
* Guides (implementers/integrators/testing/tooling): `60-guides/`
## Documentation map
* `00-overview/` — scope, glossary, FAQ, quick orientation
* `10-system/` — architecture, lifecycle, components, trust boundaries, determinism, failure modes
* `20-nodes/` — node specs (inputs/outputs at the artifact-type level; behavior; error modes)
* `30-artifacts/` — kOA-native artifacts and their schemas (does not contain Kristal artifacts)
* `40-integration/kristal-v4/` — Kristal v4 dependency pin, pointers, kOA profile, conformance, legacy-compat
* `50-operations/` — runbooks and operational procedures
* `60-guides/` — practical implementation and integration guidance
* `90-reference/` — ADRs and reference terminology
## Authoring conventions
* Each page should clearly indicate whether it is:
* **Normative for kOA** (YES/NO)
* **External normative reference** (Kristal v4 pinned reference or none)
* If a page needs Kristal specifics, **link to the pinned Kristal v4 source** in `40-integration/kristal-v4/pinned-dependency.md` rather than copying content.
## Key pointers
* Kristal v4 integration entry: `40-integration/kristal-v4/index.md`
* Pinned Kristal v4 dependency: `40-integration/kristal-v4/pinned-dependency.md`
* kOA profile and conformance: `40-integration/kristal-v4/koa-profile.md`, `40-integration/kristal-v4/conformance.md`
================================================================================================
FILE: README.md
AUTHORITY: reference
CONTENT_ROLE: knowledge
CONTENT_SHA256: 49ae6a49f498ed72e2108a59f5ad808646530e15054f13f06114bd77aa5c23fd
CONTENT_BYTES: 13941
================================================================================================
ÿþ# k O A D i g i t a l E c o s y s t e m
* * A c o n t r a c t - d r i v e n k n o w l e d g e s y s t e m f o r c a n o n i c a l t r u t h , o f f l i n e R u n t i m e P a c k s , a n d d e t e r m i n i s t i c e x e c u t i o n * *
# # O v e r v i e w
T h e * * k O A D i g i t a l E c o s y s t e m * * a d d r e s s e s a c o r e f a i l u r e m o d e i n g e n e r a t i v e a n d a g e n t i c s y s t e m s : * * n o n - d e t e r m i n i s t i c i n f o r m a t i o n d r i f t i n g i n t o d o w n s t r e a m b e h a v i o r * * . k O A e n f o r c e s a s t r i c t * * t r u t h b o u n d a r y * * :
- * * U p s t r e a m i s p r o p o s a l s * * ( c l a i m s d e r i v e d f r o m i n p u t s ) .
- * * D o w n s t r e a m i s c a n o n i c a l * * o n l y a f t e r d e t e r m i n i s t i c v a l i d a t i o n a n d c o m p i l a t i o n i n t o * * K r i s t a l * * a r t i f a c t s ( E x c h a n g e + R u n t i m e P a c k ) .
T h i s r e p o s i t o r y c o n t a i n s t h e * * s y s t e m a r c h i t e c t u r e * * , * * n o d e r e s p o n s i b i l i t i e s * * , * * k O A - o w n e d a r t i f a c t c o n t r a c t s * * , a n d * * o p e r a t i o n a l w o r k f l o w s * * . K r i s t a l v 4 r e m a i n s t h e * * s o l e n o r m a t i v e s o u r c e * * f o r K r i s t a l a r t i f a c t s c h e m a s ( C l a i m - I R , E x c h a n g e , R u n t i m e P a c k , V a l i d a t i o n R e p o r t , e t c . ) . k O A i n t e g r a t e s b y p i n n i n g K r i s t a l a n d e n f o r c i n g b o u n d a r y r u l e s w i t h o u t d u p l i c a t i n g K r i s t a l s s c h e m a d e f i n i t i o n s .
- - -
# # K e y i d e a s
# # # 1 ) T r u t h b o u n d a r y ( p r o p o s a l ’! c a n o n )
I n f o r m a t i o n b e c o m e s c a n o n i c a l o n l y a f t e r i t i s :
1 ) r e s o l v e d i n t o e x p l i c i t s t r u c t u r e s ,
2 ) d e t e r m i n i s t i c a l l y v a l i d a t e d ,
3 ) c o m p i l e d i n t o a K r i s t a l E x c h a n g e ( c a n o n i c a l t r u t h ) a n d R u n t i m e P a c k ( o f f l i n e q u e r y / r u n t i m e p a y l o a d ) .
D o w n s t r e a m l a y e r s ( d i s t r i b u t i o n , r u n t i m e , r e n d e r i n g , e x e c u t i o n ) * * m u s t n o t i n v e n t n e w f a c t s * * ; t h e y m u s t d e r i v e f r o m c a n o n i c a l a r t i f a c t s a n d p r o d u c e t r a c e a b l e o u t p u t s .
# # # 2 ) D e t e r m i n i s m ( r e p e a t a b i l i t y b y c o n s t r u c t i o n )
G i v e n t h e s a m e :
- * * p i n n e d i n p u t s * * ( s n a p s h o t s a n d u p s t r e a m a r t i f a c t s ) ,
- * * p i n n e d p o l i c i e s / m a n d a t e s * * ,
- * * p i n n e d c o n f i g u r a t i o n / t o o l c h a i n * * ,
t h e s y s t e m m u s t p r o d u c e i d e n t i c a l ( o r c a n o n i c a l l y i d e n t i c a l ) o u t p u t s a n d s t a b l e f a i l u r e s ( r e a s o n c o d e s ) . A h a r d g a t e a p p l i e s : * * n o c o m p i l e o n f a i l * * .
# # # 3 ) F a i l - c l o s e d s a f e t y g a t e s
- I f v a l i d a t i o n f a i l s : d o n o t c o m p i l e o r p u b l i s h c a n o n i c a l a r t i f a c t s .
- I f p a c k v e r i f i c a t i o n f a i l s : d o n o t a c t i v a t e ( r e m a i n o n c u r r e n t / l a s t - k n o w n - g o o d ) .
- A c t i v a t i o n m u s t b e a t o m i c ; r o l l b a c k m u s t b e d e t e r m i n i s t i c .
# # # 4 ) O f f l i n e - f i r s t o p e r a t i o n
R u n t i m e P a c k s a r e d e s i g n e d f o r o f f l i n e u s e . D i s t r i b u t i o n + a c t i v a t i o n + r o l l b a c k p o l i c i e s e n s u r e c o r r e c t n e s s w i t h o u t r e l y i n g o n l i v e d r i f t i n g d a t a .
- - -
# # L i f e c y c l e ( s t a g e s p i n e )
` ` ` m e r m a i d
f l o w c h a r t L R
A [ I n g e s t ( s n a p s h o t s + p r o v e n a n c e ) ] - - > B [ E x t r a c t ( C l a i m - I R p r o p o s a l s ) ]
B - - > C [ R e s o l v e ( R e s o l v e d C l a i m - I R ) ]
C - - > D [ V a l i d a t e ( d e t e r m i n i s t i c ) - > V a l i d a t i o n R e p o r t ]
D - - > E [ C o m p i l e ( K r i s t a l E x c h a n g e + R u n t i m e P a c k ) ]
E - - > F [ D i s t r i b u t e ( v e r i f y / a c t i v a t e / r o l l b a c k ) ]
F - - > G [ R u n t i m e s e r v e ( o f f l i n e q u e r i e s / e x e c u t i o n ) ]
G - - > H [ R e n d e r ( d e t e r m i n i s t i c o u t p u t + t r a c e ) ]
H - - > I [ E x e c u t e ( g o v e r n e d t a s k s + t e l e m e t r y ) ]
I - - > J [ F e e d b a c k - > n e w g o v e r n e d w o r k ]
` ` ` `
- - -
# # C o m p o n e n t s ( n o d e s )
k O A i s m o d u l a r : e a c h n o d e h a s e x p l i c i t r e s p o n s i b i l i t i e s a n d e x c h a n g e s t y p e d a r t i f a c t s a c r o s s b o u n d a r i e s ( n o t h i d d e n s t a t e ) .
# # # G o v e r n a n c e a n d c o n t r o l
* * * K e t e r ( M a n d a t e ) : * * g o v e r n a n c e s o u r c e m i s s i o n , c o n s t r a i n t s , p o l i c y b u n d l e s .
* * * O r g o ( C o n t r o l P l a n e ) : * * w o r k f l o w o r c h e s t r a t i o n a n d g a t e s ; a p p r o v a l s ; a u d i t r e c o r d s ; b u i l d / r e l e a s e r e c o r d s ; p u b l i c a t i o n r u l e s .
# # # I n p u t s , p l a n n i n g , a n d r e s o l u t i o n
* * * C h o k m a h ( I n p u t s ) : * * i n p u t a c q u i s i t i o n + i m m u t a b l e s n a p s h o t t i n g w i t h p r o v e n a n c e .
* * * B i n a h ( B l u e p r i n t ) : * * p l a n n i n g n o d e c o n v e r t s m a n d a t e + i n p u t s i n t o a n a u d i t a b l e B l u e p r i n t d e s c r i b i n g w h a t w i l l b e b u i l t a n d w h i c h n o d e s e x e c u t e e a c h s t e p .
* * * S e n T i e n t ( R e s o l u t i o n ) : * * r e c o n c i l i a t i o n / n o r m a l i z a t i o n ; p r o d u c e s R e s o l v e d C l a i m - I R w h i l e p r e s e r v i n g a m b i g u i t y e x p l i c i t l y .
# # # C o m p i l a t i o n a n d K r i s t a l b o u n d a r y
* * * Y e s o d ( C o m p i l e r ) : * * d e t e r m i n i s t i c c o m p i l a t i o n a n d p a c k a g i n g p i p e l i n e ( t o o l c h a i n p i n n e d ) .
* * * D a a t ( K r i s t a l B r i d g e ) : * * t h e K r i s t a l b o u n d a r y i n t e g r a t i o n p o i n t v e r i f i e s / e m i t s / p u b l i s h e s K r i s t a l a r t i f a c t s u n d e r p i n n e d d e p e n d e n c y r u l e s .
# # # D i s t r i b u t i o n a n d r u n t i m e
* * * K o n n a x i o n ( D i s t r i b u t i o n ) : * * p a c k d i s t r i b u t i o n , v e r i f i c a t i o n , c a c h i n g , a c t i v a t i o n / r o l l b a c k , c h a n n e l m a n a g e m e n t .
* * * M a l k u t h ( R u n t i m e ) : * * s e r v e s t h e a c t i v e R u n t i m e P a c k ( d e t e r m i n i s t i c q u e r y / l o o k u p / e x e c u t e ) , e n f o r c e s o f f l i n e c o n s t r a i n t s a n d f a i l - c l o s e d b e h a v i o r .
# # # A r t i c u l a t i o n a n d e x e c u t i o n
* * * A r c h i t e c t - S t r a t e g y ( N e t z a c h ) : * * t u r n s c a n o n + c o n t e x t i n t o g o v e r n e d w o r k p r o p o s a l s ( p l a n s ) , w i t h o u t m u t a t i n g c a n o n .
* * * A r c h i t e c t - R e n d e r ( H o d ) : * * d e t e r m i n i s t i c h u m a n - f a c i n g o u t p u t ; m u s t n o t i n t r o d u c e n e w f a c t s ; e m i t s t r a c e c o v e r a g e .
* * * S w a r m C r a f t ( E x e c u t i o n ) : * * e x e c u t e s g o v e r n e d t a s k s a n d e m i t s t e l e m e t r y ; d o e s n o t m u t a t e c a n o n i c a l t r u t h d i r e c t l y .
> O p t i o n a l / a d j a c e n t p l a n e : * * E k o H ( T r u s t + I m p a c t ) * * m a y p r o v i d e r e p u t a t i o n / e t h i c s / i m p a c t s i g n a l s b u t * * n e v e r m u t a t e s c a n o n i c a l t r u t h * * .
- - -
# # A r t i f a c t s ( w h a t c r o s s e s b o u n d a r i e s )
k O A t r e a t s a l l b o u n d a r y c r o s s i n g s a s t y p e d a r t i f a c t s . A t a m i n i m u m , t h e e n d - t o - e n d p i p e l i n e c a r r i e s :
* * * I n p u t S n a p s h o t s * * ( p r o v e n a n c e - p i n n e d )
* * * C l a i m - I R * * ( p r o p o s a l b o u n d a r y )
* * * R e s o l v e d C l a i m - I R * * ( r e s o l u t i o n b o u n d a r y )
* * * V a l i d a t i o n R e p o r t * * ( d e t e r m i n i s t i c a c c e p t a n c e e v i d e n c e )
* * * K r i s t a l E x c h a n g e * * ( c a n o n i c a l t r u t h )
* * * R u n t i m e P a c k * * ( o f f l i n e r u n t i m e p a y l o a d )
* * * R e n d e r B u n d l e + T r a c e M a p * * ( d e t e r m i n i s t i c u s e r - f a c i n g o u t p u t + l i n e a g e c o v e r a g e )
* * * k O A - n a t i v e o p e r a t i o n a l a r t i f a c t s * * ( C a s e s / T a s k s , B u i l d / R e l e a s e r e c o r d s , K o n n a x i o n s t a t e )
* * I m p o r t a n t : * * K r i s t a l a r t i f a c t s a r e d e f i n e d e x t e r n a l l y b y K r i s t a l v 4 ; t h i s r e p o r e f e r e n c e s t h e p i n n e d K r i s t a l d e p e n d e n c y r a t h e r t h a n d u p l i c a t i n g s c h e m a s .
- - -
# # R e p o s i t o r y l a y o u t
* ` d o c s / i n d e x . m d ` d o c u m e n t a t i o n e n t r y p o i n t a n d m a p
* ` d o c s / 0 0 - o v e r v i e w / ` s c o p e , g l o s s a r y , F A Q , o r i e n t a t i o n
* ` d o c s / 1 0 - s y s t e m / ` a r c h i t e c t u r e , l i f e c y c l e , d e t e r m i n i s m , t r u s t b o u n d a r i e s , f a i l u r e m o d e s
* ` d o c s / 2 0 - n o d e s / ` n o d e s p e c s ( r e s p o n s i b i l i t i e s , i n p u t s / o u t p u t s a t a r t i f a c t - t y p e l e v e l , g u a r d s , f a i l u r e m o d e s )
* ` d o c s / 3 0 - a r t i f a c t s / ` k O A - n a t i v e a r t i f a c t s + s c h e m a s ( d o e s n o t c o n t a i n K r i s t a l s c h e m a s )
* ` d o c s / 4 0 - i n t e g r a t i o n / k r i s t a l - v 4 / ` p i n n e d d e p e n d e n c y , c o n t r a c t p o i n t e r s , k O A p r o f i l e , c o n f o r m a n c e
* ` d o c s / 5 0 - o p e r a t i o n s / ` p i p e l i n e , r e l e a s e s , r o l l b a c k , i n c i d e n t r e s p o n s e
* ` d o c s / 6 0 - g u i d e s / ` p r a c t i c a l i m p l e m e n t a t i o n a n d i n t e g r a t i o n g u i d a n c e
* ` d o c s / 9 0 - r e f e r e n c e / ` A D R s a n d r e f e r e n c e t e r m i n o l o g y
- - -
# # C o n f o r m a n c e t e s t i n g ( h i g h - l e v e l )
I m p l e m e n t a t i o n s s h o u l d d e m o n s t r a t e :
* d e t e r m i n i s t i c r e b u i l d s ( s a m e p i n n e d c o n t e x t ’! s a m e c a n o n i c a l i d e n t i t i e s )
* v e r i f i c a t i o n f a i l - c l o s e d ( b a d s i g n a t u r e / h a s h ’! n o a c t i v a t i o n )
* r o l l b a c k d e t e r m i n i s m ( s a m e t r i g g e r h i s t o r y ’! s a m e r o l l b a c k o u t c o m e )
* r e n d e r d e t e r m i n i s m + t r a c e c o v e r a g e
S e e ` d o c s / 4 0 - i n t e g r a t i o n / k r i s t a l - v 4 / c o n f o r m a n c e . m d ` .
- - -
# # S t a r t h e r e
1 . ` d o c s / i n d e x . m d `
2 . ` d o c s / 0 0 - o v e r v i e w / s y s t e m - a t - a - g l a n c e . m d `
3 . ` d o c s / 1 0 - s y s t e m / a r c h i t e c t u r e . m d ` + ` d o c s / 1 0 - s y s t e m / t r u s t - b o u n d a r i e s . m d ` + ` d o c s / 1 0 - s y s t e m / d e t e r m i n i s m . m d `
4 . ` d o c s / 2 0 - n o d e s / i n d e x . m d `
5 . ` d o c s / 5 0 - o p e r a t i o n s / p i p e l i n e . m d ` ( t h e n r e l e a s e s / r o l l b a c k )
6 . ` d o c s / 4 0 - i n t e g r a t i o n / k r i s t a l - v 4 / i n d e x . m d ` ( p i n / p r o f i l e / c o n f o r m a n c e )
]