From 3cffcc9ee496f7ab3601270b0457cee75ab24a64 Mon Sep 17 00:00:00 2001 From: Tiara Rodney Date: Thu, 5 Feb 2026 01:54:17 +0100 Subject: [PATCH] init --- .gitignore | 2 + Pipfile | 18 ++ Pipfile.lock | 422 +++++++++++++++++++++++++++++++++++++ dist/markdown | 1 + src/.gitignore | 1 + src/AGENTS.rst | 198 ++++++++++++++++++ src/concepts.rst | 78 +++++++ src/conf.py | 41 ++++ src/example.rst | 386 ++++++++++++++++++++++++++++++++++ src/index.rst | 98 +++++++++ src/model.rst | 207 ++++++++++++++++++ src/profiles/cdk-ts.rst | 442 +++++++++++++++++++++++++++++++++++++++ src/profiles/index.rst | 26 +++ src/profiles/tf.rst | 249 ++++++++++++++++++++++ src/rules/index.rst | 26 +++ src/rules/normative.rst | 328 +++++++++++++++++++++++++++++ src/rules/validation.rst | 186 ++++++++++++++++ src/schema.rst | 229 ++++++++++++++++++++ 18 files changed, 2938 insertions(+) create mode 100644 Pipfile create mode 100644 Pipfile.lock create mode 160000 dist/markdown create mode 100644 src/.gitignore create mode 100644 src/AGENTS.rst create mode 100644 src/concepts.rst create mode 100644 src/conf.py create mode 100644 src/example.rst create mode 100644 src/index.rst create mode 100644 src/model.rst create mode 100644 src/profiles/cdk-ts.rst create mode 100644 src/profiles/index.rst create mode 100644 src/profiles/tf.rst create mode 100644 src/rules/index.rst create mode 100644 src/rules/normative.rst create mode 100644 src/rules/validation.rst create mode 100644 src/schema.rst diff --git a/.gitignore b/.gitignore index e69de29..99219c8 100644 --- a/.gitignore +++ b/.gitignore @@ -0,0 +1,2 @@ +/build/ +/dist/doctrees/ diff --git a/Pipfile b/Pipfile new file mode 100644 index 0000000..2c34ab2 --- /dev/null +++ b/Pipfile @@ -0,0 +1,18 @@ +[[source]] +url = "https://pypi.org/simple" +verify_ssl = true +name = "pypi" + +[packages] +sphinx = "==9.1.0" +sphinx-last-updated-by-git = "*" +sphinx-markdown-builder = "*" + +[dev-packages] + +[requires] +python_version = "3.13" + +[scripts] +build-html = "sphinx-build -b html src/ build/html" +build-md = "sphinx-build -M markdown src/ dist/" diff --git a/Pipfile.lock b/Pipfile.lock new file mode 100644 index 0000000..8728da3 --- /dev/null +++ b/Pipfile.lock @@ -0,0 +1,422 @@ +{ + "_meta": { + "hash": { + "sha256": "a889c35529339553277566894ad1f7630f478a0a996bee97ad7e704e938b9146" + }, + "pipfile-spec": 6, + "requires": { + "python_version": "3.13" + }, + "sources": [ + { + "name": "pypi", + "url": "https://pypi.org/simple", + "verify_ssl": true + } + ] + }, + "default": { + "alabaster": { + "hashes": [ + "sha256:c00dca57bca26fa62a6d7d0a9fcce65f3e026e9bfe33e9c538fd3fbb2144fd9e", + "sha256:fc6786402dc3fcb2de3cabd5fe455a2db534b371124f1f21de8731783dec828b" + ], + "markers": "python_version >= '3.10'", + "version": "==1.0.0" + }, + "babel": { + "hashes": [ + "sha256:b80b99a14bd085fcacfa15c9165f651fbb3406e66cc603abf11c5750937c992d", + "sha256:e2b422b277c2b9a9630c1d7903c2a00d0830c409c59ac8cae9081c92f1aeba35" + ], + "markers": "python_version >= '3.8'", + "version": "==2.18.0" + }, + "certifi": { + "hashes": [ + "sha256:9943707519e4add1115f44c2bc244f782c0249876bf51b6599fee1ffbedd685c", + "sha256:ac726dd470482006e014ad384921ed6438c457018f4b3d204aea4281258b2120" + ], + "markers": "python_version >= '3.7'", + "version": "==2026.1.4" + }, + "charset-normalizer": { + "hashes": [ + "sha256:027f6de494925c0ab2a55eab46ae5129951638a49a34d87f4c3eda90f696b4ad", + "sha256:077fbb858e903c73f6c9db43374fd213b0b6a778106bc7032446a8e8b5b38b93", + "sha256:0a98e6759f854bd25a58a73fa88833fba3b7c491169f86ce1180c948ab3fd394", + "sha256:0d3d8f15c07f86e9ff82319b3d9ef6f4bf907608f53fe9d92b28ea9ae3d1fd89", + "sha256:0f04b14ffe5fdc8c4933862d8306109a2c51e0704acfa35d51598eb45a1e89fc", + "sha256:11d694519d7f29d6cd09f6ac70028dba10f92f6cdd059096db198c283794ac86", + "sha256:194f08cbb32dc406d6e1aea671a68be0823673db2832b38405deba2fb0d88f63", + "sha256:1bee1e43c28aa63cb16e5c14e582580546b08e535299b8b6158a7c9c768a1f3d", + "sha256:21d142cc6c0ec30d2efee5068ca36c128a30b0f2c53c1c07bd78cb6bc1d3be5f", + "sha256:2437418e20515acec67d86e12bf70056a33abdacb5cb1655042f6538d6b085a8", + "sha256:244bfb999c71b35de57821b8ea746b24e863398194a4014e4c76adc2bbdfeff0", + "sha256:2677acec1a2f8ef614c6888b5b4ae4060cc184174a938ed4e8ef690e15d3e505", + "sha256:277e970e750505ed74c832b4bf75dac7476262ee2a013f5574dd49075879e161", + "sha256:2aaba3b0819274cc41757a1da876f810a3e4d7b6eb25699253a4effef9e8e4af", + "sha256:2b7d8f6c26245217bd2ad053761201e9f9680f8ce52f0fcd8d0755aeae5b2152", + "sha256:2c9d3c380143a1fedbff95a312aa798578371eb29da42106a29019368a475318", + "sha256:3162d5d8ce1bb98dd51af660f2121c55d0fa541b46dff7bb9b9f86ea1d87de72", + "sha256:31fd66405eaf47bb62e8cd575dc621c56c668f27d46a61d975a249930dd5e2a4", + "sha256:362d61fd13843997c1c446760ef36f240cf81d3ebf74ac62652aebaf7838561e", + "sha256:376bec83a63b8021bb5c8ea75e21c4ccb86e7e45ca4eb81146091b56599b80c3", + "sha256:44c2a8734b333e0578090c4cd6b16f275e07aa6614ca8715e6c038e865e70576", + "sha256:47cc91b2f4dd2833fddaedd2893006b0106129d4b94fdb6af1f4ce5a9965577c", + "sha256:4902828217069c3c5c71094537a8e623f5d097858ac6ca8252f7b4d10b7560f1", + "sha256:4bd5d4137d500351a30687c2d3971758aac9a19208fc110ccb9d7188fbe709e8", + "sha256:4fe7859a4e3e8457458e2ff592f15ccb02f3da787fcd31e0183879c3ad4692a1", + "sha256:542d2cee80be6f80247095cc36c418f7bddd14f4a6de45af91dfad36d817bba2", + "sha256:554af85e960429cf30784dd47447d5125aaa3b99a6f0683589dbd27e2f45da44", + "sha256:5833d2c39d8896e4e19b689ffc198f08ea58116bee26dea51e362ecc7cd3ed26", + "sha256:5947809c8a2417be3267efc979c47d76a079758166f7d43ef5ae8e9f92751f88", + "sha256:5ae497466c7901d54b639cf42d5b8c1b6a4fead55215500d2f486d34db48d016", + "sha256:5bd2293095d766545ec1a8f612559f6b40abc0eb18bb2f5d1171872d34036ede", + "sha256:5bfbb1b9acf3334612667b61bd3002196fe2a1eb4dd74d247e0f2a4d50ec9bbf", + "sha256:5cb4d72eea50c8868f5288b7f7f33ed276118325c1dfd3957089f6b519e1382a", + "sha256:5dbe56a36425d26d6cfb40ce79c314a2e4dd6211d51d6d2191c00bed34f354cc", + "sha256:5f819d5fe9234f9f82d75bdfa9aef3a3d72c4d24a6e57aeaebba32a704553aa0", + "sha256:64b55f9dce520635f018f907ff1b0df1fdc31f2795a922fb49dd14fbcdf48c84", + "sha256:6515f3182dbe4ea06ced2d9e8666d97b46ef4c75e326b79bb624110f122551db", + "sha256:65e2befcd84bc6f37095f5961e68a6f077bf44946771354a28ad434c2cce0ae1", + "sha256:6aee717dcfead04c6eb1ce3bd29ac1e22663cdea57f943c87d1eab9a025438d7", + "sha256:6b39f987ae8ccdf0d2642338faf2abb1862340facc796048b604ef14919e55ed", + "sha256:6e1fcf0720908f200cd21aa4e6750a48ff6ce4afe7ff5a79a90d5ed8a08296f8", + "sha256:74018750915ee7ad843a774364e13a3db91682f26142baddf775342c3f5b1133", + "sha256:74664978bb272435107de04e36db5a9735e78232b85b77d45cfb38f758efd33e", + "sha256:74bb723680f9f7a6234dcf67aea57e708ec1fbdf5699fb91dfd6f511b0a320ef", + "sha256:752944c7ffbfdd10c074dc58ec2d5a8a4cd9493b314d367c14d24c17684ddd14", + "sha256:778d2e08eda00f4256d7f672ca9fef386071c9202f5e4607920b86d7803387f2", + "sha256:780236ac706e66881f3b7f2f32dfe90507a09e67d1d454c762cf642e6e1586e0", + "sha256:798d75d81754988d2565bff1b97ba5a44411867c0cf32b77a7e8f8d84796b10d", + "sha256:799a7a5e4fb2d5898c60b640fd4981d6a25f1c11790935a44ce38c54e985f828", + "sha256:7a32c560861a02ff789ad905a2fe94e3f840803362c84fecf1851cb4cf3dc37f", + "sha256:7c308f7e26e4363d79df40ca5b2be1c6ba9f02bdbccfed5abddb7859a6ce72cf", + "sha256:7fa17817dc5625de8a027cb8b26d9fefa3ea28c8253929b8d6649e705d2835b6", + "sha256:81d5eb2a312700f4ecaa977a8235b634ce853200e828fbadf3a9c50bab278328", + "sha256:82004af6c302b5d3ab2cfc4cc5f29db16123b1a8417f2e25f9066f91d4411090", + "sha256:837c2ce8c5a65a2035be9b3569c684358dfbf109fd3b6969630a87535495ceaa", + "sha256:840c25fb618a231545cbab0564a799f101b63b9901f2569faecd6b222ac72381", + "sha256:8a6562c3700cce886c5be75ade4a5db4214fda19fede41d9792d100288d8f94c", + "sha256:8af65f14dc14a79b924524b1e7fffe304517b2bff5a58bf64f30b98bbc5079eb", + "sha256:8ef3c867360f88ac904fd3f5e1f902f13307af9052646963ee08ff4f131adafc", + "sha256:94537985111c35f28720e43603b8e7b43a6ecfb2ce1d3058bbe955b73404e21a", + "sha256:99ae2cffebb06e6c22bdc25801d7b30f503cc87dbd283479e7b606f70aff57ec", + "sha256:9a26f18905b8dd5d685d6d07b0cdf98a79f3c7a918906af7cc143ea2e164c8bc", + "sha256:9b35f4c90079ff2e2edc5b26c0c77925e5d2d255c42c74fdb70fb49b172726ac", + "sha256:9cd98cdc06614a2f768d2b7286d66805f94c48cde050acdbbb7db2600ab3197e", + "sha256:9d1bb833febdff5c8927f922386db610b49db6e0d4f4ee29601d71e7c2694313", + "sha256:9f7fcd74d410a36883701fafa2482a6af2ff5ba96b9a620e9e0721e28ead5569", + "sha256:a59cb51917aa591b1c4e6a43c132f0cdc3c76dbad6155df4e28ee626cc77a0a3", + "sha256:a61900df84c667873b292c3de315a786dd8dac506704dea57bc957bd31e22c7d", + "sha256:a79cfe37875f822425b89a82333404539ae63dbdddf97f84dcbc3d339aae9525", + "sha256:a8a8b89589086a25749f471e6a900d3f662d1d3b6e2e59dcecf787b1cc3a1894", + "sha256:a8bf8d0f749c5757af2142fe7903a9df1d2e8aa3841559b2bad34b08d0e2bcf3", + "sha256:a9768c477b9d7bd54bc0c86dbaebdec6f03306675526c9927c0e8a04e8f94af9", + "sha256:ac1c4a689edcc530fc9d9aa11f5774b9e2f33f9a0c6a57864e90908f5208d30a", + "sha256:af2d8c67d8e573d6de5bc30cdb27e9b95e49115cd9baad5ddbd1a6207aaa82a9", + "sha256:b435cba5f4f750aa6c0a0d92c541fb79f69a387c91e61f1795227e4ed9cece14", + "sha256:b5b290ccc2a263e8d185130284f8501e3e36c5e02750fc6b6bdeb2e9e96f1e25", + "sha256:b5d84d37db046c5ca74ee7bb47dd6cbc13f80665fdde3e8040bdd3fb015ecb50", + "sha256:b7cf1017d601aa35e6bb650b6ad28652c9cd78ee6caff19f3c28d03e1c80acbf", + "sha256:bc7637e2f80d8530ee4a78e878bce464f70087ce73cf7c1caf142416923b98f1", + "sha256:c0463276121fdee9c49b98908b3a89c39be45d86d1dbaa22957e38f6321d4ce3", + "sha256:c4ef880e27901b6cc782f1b95f82da9313c0eb95c3af699103088fa0ac3ce9ac", + "sha256:c8ae8a0f02f57a6e61203a31428fa1d677cbe50c93622b4149d5c0f319c1d19e", + "sha256:ca5862d5b3928c4940729dacc329aa9102900382fea192fc5e52eb69d6093815", + "sha256:cb01158d8b88ee68f15949894ccc6712278243d95f344770fa7593fa2d94410c", + "sha256:cb6254dc36b47a990e59e1068afacdcd02958bdcce30bb50cc1700a8b9d624a6", + "sha256:cc00f04ed596e9dc0da42ed17ac5e596c6ccba999ba6bd92b0e0aef2f170f2d6", + "sha256:cd09d08005f958f370f539f186d10aec3377d55b9eeb0d796025d4886119d76e", + "sha256:cd4b7ca9984e5e7985c12bc60a6f173f3c958eae74f3ef6624bb6b26e2abbae4", + "sha256:ce8a0633f41a967713a59c4139d29110c07e826d131a316b50ce11b1d79b4f84", + "sha256:cead0978fc57397645f12578bfd2d5ea9138ea0fac82b2f63f7f7c6877986a69", + "sha256:d055ec1e26e441f6187acf818b73564e6e6282709e9bcb5b63f5b23068356a15", + "sha256:d1f13550535ad8cff21b8d757a3257963e951d96e20ec82ab44bc64aeb62a191", + "sha256:d9c7f57c3d666a53421049053eaacdd14bbd0a528e2186fcb2e672effd053bb0", + "sha256:d9e45d7faa48ee908174d8fe84854479ef838fc6a705c9315372eacbc2f02897", + "sha256:da3326d9e65ef63a817ecbcc0df6e94463713b754fe293eaa03da99befb9a5bd", + "sha256:de00632ca48df9daf77a2c65a484531649261ec9f25489917f09e455cb09ddb2", + "sha256:e1f185f86a6f3403aa2420e815904c67b2f9ebc443f045edd0de921108345794", + "sha256:e824f1492727fa856dd6eda4f7cee25f8518a12f3c4a56a74e8095695089cf6d", + "sha256:e912091979546adf63357d7e2ccff9b44f026c075aeaf25a52d0e95ad2281074", + "sha256:eaabd426fe94daf8fd157c32e571c85cb12e66692f15516a83a03264b08d06c3", + "sha256:ebf3e58c7ec8a8bed6d66a75d7fb37b55e5015b03ceae72a8e7c74495551e224", + "sha256:ecaae4149d99b1c9e7b88bb03e3221956f68fd6d50be2ef061b2381b61d20838", + "sha256:eecbc200c7fd5ddb9a7f16c7decb07b566c29fa2161a16cf67b8d068bd21690a", + "sha256:f155a433c2ec037d4e8df17d18922c3a0d9b3232a396690f17175d2946f0218d", + "sha256:f1e34719c6ed0b92f418c7c780480b26b5d9c50349e9a9af7d76bf757530350d", + "sha256:f34be2938726fc13801220747472850852fe6b1ea75869a048d6f896838c896f", + "sha256:f820802628d2694cb7e56db99213f930856014862f3fd943d290ea8438d07ca8", + "sha256:f8bf04158c6b607d747e93949aa60618b61312fe647a6369f88ce2ff16043490", + "sha256:f8e160feb2aed042cd657a72acc0b481212ed28b1b9a95c0cee1621b524e1966", + "sha256:f9d332f8c2a2fcbffe1378594431458ddbef721c1769d78e2cbc06280d8155f9", + "sha256:fa09f53c465e532f4d3db095e0c55b615f010ad81803d383195b6b5ca6cbf5f3", + "sha256:faa3a41b2b66b6e50f84ae4a68c64fcd0c44355741c6374813a800cd6695db9e", + "sha256:fd44c878ea55ba351104cb93cc85e74916eb8fa440ca7903e57575e97394f608" + ], + "markers": "python_version >= '3.7'", + "version": "==3.4.4" + }, + "docutils": { + "hashes": [ + "sha256:4db53b1fde9abecbb74d91230d32ab626d94f6badfc575d6db9194a49df29968", + "sha256:d0013f540772d1420576855455d050a2180186c91c15779301ac2ccb3eeb68de" + ], + "markers": "python_version >= '3.9'", + "version": "==0.22.4" + }, + "idna": { + "hashes": [ + "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", + "sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902" + ], + "markers": "python_version >= '3.8'", + "version": "==3.11" + }, + "imagesize": { + "hashes": [ + "sha256:0d8d18d08f840c19d0ee7ca1fd82490fdc3729b7ac93f49870406ddde8ef8d8b", + "sha256:69150444affb9cb0d5cc5a92b3676f0b2fb7cd9ae39e947a5e11a36b4497cd4a" + ], + "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", + "version": "==1.4.1" + }, + "jinja2": { + "hashes": [ + "sha256:0137fb05990d35f1275a587e9aee6d56da821fc83491a0fb838183be43f66d6d", + "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67" + ], + "markers": "python_version >= '3.7'", + "version": "==3.1.6" + }, + "markupsafe": { + "hashes": [ + "sha256:0303439a41979d9e74d18ff5e2dd8c43ed6c6001fd40e5bf2e43f7bd9bbc523f", + "sha256:068f375c472b3e7acbe2d5318dea141359e6900156b5b2ba06a30b169086b91a", + "sha256:0bf2a864d67e76e5c9a34dc26ec616a66b9888e25e7b9460e1c76d3293bd9dbf", + "sha256:0db14f5dafddbb6d9208827849fad01f1a2609380add406671a26386cdf15a19", + "sha256:0eb9ff8191e8498cca014656ae6b8d61f39da5f95b488805da4bb029cccbfbaf", + "sha256:0f4b68347f8c5eab4a13419215bdfd7f8c9b19f2b25520968adfad23eb0ce60c", + "sha256:1085e7fbddd3be5f89cc898938f42c0b3c711fdcb37d75221de2666af647c175", + "sha256:116bb52f642a37c115f517494ea5feb03889e04df47eeff5b130b1808ce7c219", + "sha256:12c63dfb4a98206f045aa9563db46507995f7ef6d83b2f68eda65c307c6829eb", + "sha256:133a43e73a802c5562be9bbcd03d090aa5a1fe899db609c29e8c8d815c5f6de6", + "sha256:1353ef0c1b138e1907ae78e2f6c63ff67501122006b0f9abad68fda5f4ffc6ab", + "sha256:15d939a21d546304880945ca1ecb8a039db6b4dc49b2c5a400387cdae6a62e26", + "sha256:177b5253b2834fe3678cb4a5f0059808258584c559193998be2601324fdeafb1", + "sha256:1872df69a4de6aead3491198eaf13810b565bdbeec3ae2dc8780f14458ec73ce", + "sha256:1b4b79e8ebf6b55351f0d91fe80f893b4743f104bff22e90697db1590e47a218", + "sha256:1b52b4fb9df4eb9ae465f8d0c228a00624de2334f216f178a995ccdcf82c4634", + "sha256:1ba88449deb3de88bd40044603fafffb7bc2b055d626a330323a9ed736661695", + "sha256:1cc7ea17a6824959616c525620e387f6dd30fec8cb44f649e31712db02123dad", + "sha256:218551f6df4868a8d527e3062d0fb968682fe92054e89978594c28e642c43a73", + "sha256:26a5784ded40c9e318cfc2bdb30fe164bdb8665ded9cd64d500a34fb42067b1c", + "sha256:2713baf880df847f2bece4230d4d094280f4e67b1e813eec43b4c0e144a34ffe", + "sha256:2a15a08b17dd94c53a1da0438822d70ebcd13f8c3a95abe3a9ef9f11a94830aa", + "sha256:2f981d352f04553a7171b8e44369f2af4055f888dfb147d55e42d29e29e74559", + "sha256:32001d6a8fc98c8cb5c947787c5d08b0a50663d139f1305bac5885d98d9b40fa", + "sha256:3524b778fe5cfb3452a09d31e7b5adefeea8c5be1d43c4f810ba09f2ceb29d37", + "sha256:3537e01efc9d4dccdf77221fb1cb3b8e1a38d5428920e0657ce299b20324d758", + "sha256:35add3b638a5d900e807944a078b51922212fb3dedb01633a8defc4b01a3c85f", + "sha256:38664109c14ffc9e7437e86b4dceb442b0096dfe3541d7864d9cbe1da4cf36c8", + "sha256:3a7e8ae81ae39e62a41ec302f972ba6ae23a5c5396c8e60113e9066ef893da0d", + "sha256:3b562dd9e9ea93f13d53989d23a7e775fdfd1066c33494ff43f5418bc8c58a5c", + "sha256:457a69a9577064c05a97c41f4e65148652db078a3a509039e64d3467b9e7ef97", + "sha256:4bd4cd07944443f5a265608cc6aab442e4f74dff8088b0dfc8238647b8f6ae9a", + "sha256:4e885a3d1efa2eadc93c894a21770e4bc67899e3543680313b09f139e149ab19", + "sha256:4faffd047e07c38848ce017e8725090413cd80cbc23d86e55c587bf979e579c9", + "sha256:509fa21c6deb7a7a273d629cf5ec029bc209d1a51178615ddf718f5918992ab9", + "sha256:5678211cb9333a6468fb8d8be0305520aa073f50d17f089b5b4b477ea6e67fdc", + "sha256:591ae9f2a647529ca990bc681daebdd52c8791ff06c2bfa05b65163e28102ef2", + "sha256:5a7d5dc5140555cf21a6fefbdbf8723f06fcd2f63ef108f2854de715e4422cb4", + "sha256:69c0b73548bc525c8cb9a251cddf1931d1db4d2258e9599c28c07ef3580ef354", + "sha256:6b5420a1d9450023228968e7e6a9ce57f65d148ab56d2313fcd589eee96a7a50", + "sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698", + "sha256:729586769a26dbceff69f7a7dbbf59ab6572b99d94576a5592625d5b411576b9", + "sha256:77f0643abe7495da77fb436f50f8dab76dbc6e5fd25d39589a0f1fe6548bfa2b", + "sha256:795e7751525cae078558e679d646ae45574b47ed6e7771863fcc079a6171a0fc", + "sha256:7be7b61bb172e1ed687f1754f8e7484f1c8019780f6f6b0786e76bb01c2ae115", + "sha256:7c3fb7d25180895632e5d3148dbdc29ea38ccb7fd210aa27acbd1201a1902c6e", + "sha256:7e68f88e5b8799aa49c85cd116c932a1ac15caaa3f5db09087854d218359e485", + "sha256:83891d0e9fb81a825d9a6d61e3f07550ca70a076484292a70fde82c4b807286f", + "sha256:8485f406a96febb5140bfeca44a73e3ce5116b2501ac54fe953e488fb1d03b12", + "sha256:8709b08f4a89aa7586de0aadc8da56180242ee0ada3999749b183aa23df95025", + "sha256:8f71bc33915be5186016f675cd83a1e08523649b0e33efdb898db577ef5bb009", + "sha256:915c04ba3851909ce68ccc2b8e2cd691618c4dc4c4232fb7982bca3f41fd8c3d", + "sha256:949b8d66bc381ee8b007cd945914c721d9aba8e27f71959d750a46f7c282b20b", + "sha256:94c6f0bb423f739146aec64595853541634bde58b2135f27f61c1ffd1cd4d16a", + "sha256:9a1abfdc021a164803f4d485104931fb8f8c1efd55bc6b748d2f5774e78b62c5", + "sha256:9b79b7a16f7fedff2495d684f2b59b0457c3b493778c9eed31111be64d58279f", + "sha256:a320721ab5a1aba0a233739394eb907f8c8da5c98c9181d1161e77a0c8e36f2d", + "sha256:a4afe79fb3de0b7097d81da19090f4df4f8d3a2b3adaa8764138aac2e44f3af1", + "sha256:ad2cf8aa28b8c020ab2fc8287b0f823d0a7d8630784c31e9ee5edea20f406287", + "sha256:b8512a91625c9b3da6f127803b166b629725e68af71f8184ae7e7d54686a56d6", + "sha256:bc51efed119bc9cfdf792cdeaa4d67e8f6fcccab66ed4bfdd6bde3e59bfcbb2f", + "sha256:bdc919ead48f234740ad807933cdf545180bfbe9342c2bb451556db2ed958581", + "sha256:bdd37121970bfd8be76c5fb069c7751683bdf373db1ed6c010162b2a130248ed", + "sha256:be8813b57049a7dc738189df53d69395eba14fb99345e0a5994914a3864c8a4b", + "sha256:c0c0b3ade1c0b13b936d7970b1d37a57acde9199dc2aecc4c336773e1d86049c", + "sha256:c47a551199eb8eb2121d4f0f15ae0f923d31350ab9280078d1e5f12b249e0026", + "sha256:c4ffb7ebf07cfe8931028e3e4c85f0357459a3f9f9490886198848f4fa002ec8", + "sha256:ccfcd093f13f0f0b7fdd0f198b90053bf7b2f02a3927a30e63f3ccc9df56b676", + "sha256:d2ee202e79d8ed691ceebae8e0486bd9a2cd4794cec4824e1c99b6f5009502f6", + "sha256:d53197da72cc091b024dd97249dfc7794d6a56530370992a5e1a08983ad9230e", + "sha256:d6dd0be5b5b189d31db7cda48b91d7e0a9795f31430b7f271219ab30f1d3ac9d", + "sha256:d88b440e37a16e651bda4c7c2b930eb586fd15ca7406cb39e211fcff3bf3017d", + "sha256:de8a88e63464af587c950061a5e6a67d3632e36df62b986892331d4620a35c01", + "sha256:df2449253ef108a379b8b5d6b43f4b1a8e81a061d6537becd5582fba5f9196d7", + "sha256:e1c1493fb6e50ab01d20a22826e57520f1284df32f2d8601fdd90b6304601419", + "sha256:e1cf1972137e83c5d4c136c43ced9ac51d0e124706ee1c8aa8532c1287fa8795", + "sha256:e2103a929dfa2fcaf9bb4e7c091983a49c9ac3b19c9061b6d5427dd7d14d81a1", + "sha256:e56b7d45a839a697b5eb268c82a71bd8c7f6c94d6fd50c3d577fa39a9f1409f5", + "sha256:e8afc3f2ccfa24215f8cb28dcf43f0113ac3c37c2f0f0806d8c70e4228c5cf4d", + "sha256:e8fc20152abba6b83724d7ff268c249fa196d8259ff481f3b1476383f8f24e42", + "sha256:eaa9599de571d72e2daf60164784109f19978b327a3910d3e9de8c97b5b70cfe", + "sha256:ec15a59cf5af7be74194f7ab02d0f59a62bdcf1a537677ce67a2537c9b87fcda", + "sha256:f190daf01f13c72eac4efd5c430a8de82489d9cff23c364c3ea822545032993e", + "sha256:f34c41761022dd093b4b6896d4810782ffbabe30f2d443ff5f083e0cbbb8c737", + "sha256:f3e98bb3798ead92273dc0e5fd0f31ade220f59a266ffd8a4f6065e0a3ce0523", + "sha256:f42d0984e947b8adf7dd6dde396e720934d12c506ce84eea8476409563607591", + "sha256:f71a396b3bf33ecaa1626c255855702aca4d3d9fea5e051b41ac59a9c1c41edc", + "sha256:f9e130248f4462aaa8e2552d547f36ddadbeaa573879158d721bbd33dfe4743a", + "sha256:fed51ac40f757d41b7c48425901843666a6677e3e8eb0abcff09e4ba6e664f50" + ], + "markers": "python_version >= '3.9'", + "version": "==3.0.3" + }, + "packaging": { + "hashes": [ + "sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4", + "sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529" + ], + "markers": "python_version >= '3.8'", + "version": "==26.0" + }, + "pygments": { + "hashes": [ + "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", + "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b" + ], + "markers": "python_version >= '3.8'", + "version": "==2.19.2" + }, + "requests": { + "hashes": [ + "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", + "sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf" + ], + "markers": "python_version >= '3.9'", + "version": "==2.32.5" + }, + "roman-numerals": { + "hashes": [ + "sha256:1af8b147eb1405d5839e78aeb93131690495fe9da5c91856cb33ad55a7f1e5b2", + "sha256:647ba99caddc2cc1e55a51e4360689115551bf4476d90e8162cf8c345fe233c7" + ], + "markers": "python_version >= '3.10'", + "version": "==4.1.0" + }, + "snowballstemmer": { + "hashes": [ + "sha256:6cd7b3897da8d6c9ffb968a6781fa6532dce9c3618a4b127d920dab764a19064", + "sha256:6d5eeeec8e9f84d4d56b847692bacf79bc2c8e90c7f80ca4444ff8b6f2e52895" + ], + "markers": "python_version not in '3.0, 3.1, 3.2'", + "version": "==3.0.1" + }, + "sphinx": { + "hashes": [ + "sha256:7741722357dd75f8190766926071fed3bdc211c74dd2d7d4df5404da95930ddb", + "sha256:c84fdd4e782504495fe4f2c0b3413d6c2bf388589bb352d439b2a3bb99991978" + ], + "index": "pypi", + "markers": "python_version >= '3.12'", + "version": "==9.1.0" + }, + "sphinx-last-updated-by-git": { + "hashes": [ + "sha256:6382c8285ac1f222483a58569b78c0371af5e55f7fbf9c01e5e8a72d6fdfa499", + "sha256:c145011f4609d841805b69a9300099fc02fed8f5bb9e5bcef77d97aea97b7761" + ], + "index": "pypi", + "markers": "python_version >= '3.7'", + "version": "==0.3.8" + }, + "sphinx-markdown-builder": { + "hashes": [ + "sha256:35b555760c48d4a38fe4b27813cb5ca636bbd22d8ef0742ac6959043f8000840", + "sha256:e89dc1b9eb837da430c2c230011fad95a3dfab0345ad503a32e35a31d284a722" + ], + "index": "pypi", + "markers": "python_version >= '3.7'", + "version": "==0.6.9" + }, + "sphinxcontrib-applehelp": { + "hashes": [ + "sha256:2f29ef331735ce958efa4734873f084941970894c6090408b079c61b2e1c06d1", + "sha256:4cd3f0ec4ac5dd9c17ec65e9ab272c9b867ea77425228e68ecf08d6b28ddbdb5" + ], + "markers": "python_version >= '3.9'", + "version": "==2.0.0" + }, + "sphinxcontrib-devhelp": { + "hashes": [ + "sha256:411f5d96d445d1d73bb5d52133377b4248ec79db5c793ce7dbe59e074b4dd1ad", + "sha256:aefb8b83854e4b0998877524d1029fd3e6879210422ee3780459e28a1f03a8a2" + ], + "markers": "python_version >= '3.9'", + "version": "==2.0.0" + }, + "sphinxcontrib-htmlhelp": { + "hashes": [ + "sha256:166759820b47002d22914d64a075ce08f4c46818e17cfc9470a9786b759b19f8", + "sha256:c9e2916ace8aad64cc13a0d233ee22317f2b9025b9cf3295249fa985cc7082e9" + ], + "markers": "python_version >= '3.9'", + "version": "==2.1.0" + }, + "sphinxcontrib-jsmath": { + "hashes": [ + "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178", + "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8" + ], + "markers": "python_version >= '3.5'", + "version": "==1.0.1" + }, + "sphinxcontrib-qthelp": { + "hashes": [ + "sha256:4fe7d0ac8fc171045be623aba3e2a8f613f8682731f9153bb2e40ece16b9bbab", + "sha256:b18a828cdba941ccd6ee8445dbe72ffa3ef8cbe7505d8cd1fa0d42d3f2d5f3eb" + ], + "markers": "python_version >= '3.9'", + "version": "==2.0.0" + }, + "sphinxcontrib-serializinghtml": { + "hashes": [ + "sha256:6e2cb0eef194e10c27ec0023bfeb25badbbb5868244cf5bc5bdc04e4464bf331", + "sha256:e9d912827f872c029017a53f0ef2180b327c3f7fd23c87229f7a8e8b70031d4d" + ], + "markers": "python_version >= '3.9'", + "version": "==2.0.0" + }, + "tabulate": { + "hashes": [ + "sha256:0095b12bf5966de529c0feb1fa08671671b3368eec77d7ef7ab114be2c068b3c", + "sha256:024ca478df22e9340661486f85298cff5f6dcdba14f3813e8830015b9ed1948f" + ], + "markers": "python_version >= '3.7'", + "version": "==0.9.0" + }, + "urllib3": { + "hashes": [ + "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", + "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4" + ], + "markers": "python_version >= '3.9'", + "version": "==2.6.3" + } + }, + "develop": {} +} diff --git a/dist/markdown b/dist/markdown new file mode 160000 index 0000000..4148163 --- /dev/null +++ b/dist/markdown @@ -0,0 +1 @@ +Subproject commit 41481636d866a24c7d1d55d13310cd45dacf6494 diff --git a/src/.gitignore b/src/.gitignore new file mode 100644 index 0000000..181cfeb --- /dev/null +++ b/src/.gitignore @@ -0,0 +1 @@ +/.doctrees/ diff --git a/src/AGENTS.rst b/src/AGENTS.rst new file mode 100644 index 0000000..b45044a --- /dev/null +++ b/src/AGENTS.rst @@ -0,0 +1,198 @@ +###### +AGENTS +###### + +Operational Guidance for Autonomous Agents Using specification (ABC Specification) +================================================================================== + +MUST USE ``index.md`` as entrypoint for specification and subsequent referenced +documents within. + +Purpose of this document +------------------------ + +This document defines how an autonomous agent must operate when using the +Abstract Base Cloud (ABC) Specification (specification) as the authoritative +source of truth. It does not redefine, summarize, or restate the ABC Pattern. +Its purpose is to establish procedures, behaviors, and decision rules that +ensure all agent actions remain compliant with the specification. + +How to Read and Interpret spec.txt +---------------------------------- + +#. Treat specification as canonical; all definitions, rules, and schemas + originate there. +#. When encountering ambiguity, defer to specification rather than internal + heuristics. +#. When interpreting any rule: + - Use the identifiers in specification as binding references. + - Do not reinterpret or rephrase the rule; apply it operationally. +#. When a task requires clarification, locate the relevant section in + specification and apply its constraints directly. + +How to Apply the ABC Normative Rules +------------------------------------ + +#. Use normative rules as constraints on generation and transformation. +#. For any action: + - Identify which normative rules apply. + - Enforce them mechanically. +#. When generating constructs: + - Ensure hierarchy, relationships, interfaces, and data flow conform to + normative rules. +#. When routing data: + - Apply downward and upward flow rules exactly as defined. +#. When evaluating a user request: + - Reject or correct requests that would violate normative rules. + + +How to Apply the ABC Validation Rules +------------------------------------- +#. Treat validation rules as mechanical checks. +#. For any ABC architecture: + - Validate structure. + - Validate contracts. + - Validate data flow. + - Validate instantiation semantics. +#. When a violation is detected: + - Identify the violated rule by its identifier. + - Provide a corrective action path. +#. Never modify validation rules; only apply them. + + +SECTION 5 — How to Use the ABC Schema +------------------------------------- +#. Use the schema as the machine-readable representation of an ABC architecture. +#. When generating or transforming architectures: + - Produce JSON that conforms exactly to the schema. +#. When validating: + - Apply schema constraints before normative or validation rules. +#. When consuming the schema: + - Use ``$defs`` to resolve construct types, contracts, and rule bindings. +#. Never alter the schema; only instantiate or validate against it. + +How to Use the Code Generation Profiles +--------------------------------------- + +#. Profiles define how to map ABC constructs into specific IaC tools. +#. When generating code: + - Select the appropriate profile. + - Apply profile rules exactly as written in specification. +#. When a profile conflicts with user instructions: + - The profile takes precedence. +#. When generating code: + - Use the ABC hierarchy as the structural backbone. + - Use Input/Output Contracts as the only wiring mechanism. +#. Never invent new profile rules; only apply those defined in specification. + +Operational Procedures for Construct Creation +--------------------------------------------- + +#. Determine the construct type. +#. Create the construct with: + - A unique ID. + - A valid parent (except ApplicationStack). + - A complete Input Contract. + - A complete Output Contract. +#. Instantiate children strictly top-down. +#. Ensure no lateral references are introduced. +#. Enforce immutability of Input Contracts. + +Operational Procedures for Data Flow Wiring +------------------------------------------- + +#. For downward flow: + - Pass only the required subset of parent inputs/outputs. + - Ensure all downward values originate from the parent’s declared contracts. +#. For upward flow: + - Expose only declared outputs. + - Aggregate or transform outputs only at the parent level. +#. Never allow: + - Sibling-to-sibling communication. + - Access to undeclared values. + - Implicit or hidden data flow. + +Operational Procedures for Validation +------------------------------------- + +#. Validate in this order: + - Schema conformance. + - Structural validation rules. + - Contract validation rules. + - Data-flow validation rules. + - Instantiation validation rules. +#. For each violation: + - Identify the rule ID. + - Provide a deterministic correction path. +#. Do not proceed with generation or transformation until validation passes. + +Operational Procedures for Refactoring +-------------------------------------- + +#. Load the existing architecture from its schema representation. +#. Identify the target change. +#. Determine which constructs, contracts, or data flows are affected. +#. Apply changes while enforcing: + - Contract stability requirements. + - Parent–child mediation rules. + - No lateral references. +#. After refactoring: + - Revalidate the entire architecture. + - Ensure all rule identifiers remain satisfied. + +Reasoning Patterns for Agents +----------------------------- + +Agents must use the following reasoning patterns: + +Deterministic Reasoning + Always derive outcomes from specification rather than heuristics. + +Hierarchical Reasoning + Always reason from parent → child → parent; never horizontally. + +Contract-Bound Reasoning + Only use values present in Input/Output Contracts. + +Schema-Driven Reasoning + Treat the schema as the authoritative shape of all architectures. + +Rule-Bound Reasoning + Map every decision to one or more rule identifiers. + + +Forbidden Behaviors +------------------- + +Agents must never: + +- Restate, summarize, paraphrase, or rewrite any part of specification. +- Invent new ABC rules or modify existing ones. +- Introduce lateral references between constructs. +- Generate architectures that violate any rule in specification. +- Infer missing contract fields not explicitly provided. +- Create implicit dependencies or hidden data flow. +- Generate code that does not follow the selected profile. +- Produce constructs outside the allowed hierarchy. +- Mutate Input Contracts after instantiation. +- Expose values not declared in Output Contracts. + + +Agent Behavioral Contract +------------------------- + +Agents must: + +#. Treat specification as the single source of truth. +#. Apply rules without reinterpretation. +#. Produce deterministic, reproducible outputs. +#. Validate all generated artifacts before returning them. +#. Reject or correct user requests that violate the specification. +#. Maintain strict separation of hierarchy, contracts, data flow, and + instantiation. +#. Ensure all transformations preserve rule compliance. +#. Use profile mappings exactly as defined. +#. Operate without assumptions, guesses, or implicit dependencies. +#. Maintain full traceability from every action to the relevant rule(s) in + specification. + diff --git a/src/concepts.rst b/src/concepts.rst new file mode 100644 index 0000000..e7fe4f8 --- /dev/null +++ b/src/concepts.rst @@ -0,0 +1,78 @@ +######## +Concepts +######## + +ABC-C0 - Construct +================== + +An encapsulated unit of infrastructure logic that can represent an Application +Stack, Logical Unit, Resource Group, or any reusable component. It exposes a +single Instantiation Interface and implements its behavior internally, +independent of other constructs. + +ABC-C1 - Application Stack +========================== + +The top‑level construct representing the entire deployment boundary of an +application. It composes multiple Logical Units, orchestrates their +instantiation, and mediates all data flow between them. It exposes a single, +coherent input/output surface for the whole system. + +ABC-C2 - Logical Unit +===================== + +A first‑level subdivision within the Application Stack that encapsulates a major +functional domain (e.g., Data, Logic, Presentation). It contains one or more +Resource Groups and defines explicit input/output contracts for interaction with +the Application Stack. + +ABC-C3 - Resource Group +======================= + +A fine‑grained construct within a Logical Unit that provisions a cohesive set of +related resources. It receives only the inputs it requires from its parent +Logical Unit and returns outputs upward; it never communicates directly with +sibling Resource Groups. + +ABC-C4 - Input Contract +======================= + +A formally defined set of parameters that a Construct (ABC‑C0) MUST receive from +its parent. It specifies all required configuration, contextual values, and +dependencies needed for correct instantiation. It prohibits implicit or global +state; every dependency must appear explicitly in this contract. + +ABC-C5 - Output Contract +======================== + +A formally defined set of values that a Construct (ABC‑C0) MUST expose upward to +its parent. It represents the complete set of externally consumable identifiers, +endpoints, or computed values produced by the construct. It ensures that all +upward dependencies are explicit and traceable. + +ABC-C6 - Instantiation Interface +================================ + +The single, explicit mechanism through which a Construct (ABC‑C0) is created and +provided with its Input Contract (ABC‑C4). It defines how callers supply inputs +and how the construct exposes its Output Contract (ABC‑C5). The interface is +stable, minimal, and framework‑agnostic, ensuring that internal implementation +details never leak into parent constructs. + +ABC-C7 - Capturing Down +======================= + +A parent‑to‑child data‑flow mechanism in which a Construct (ABC‑C0) provides its +children with the exact subset of inputs they require. It ensures that all +downward dependencies are explicit, scoped, and passed only through the child’s +Input Contract (ABC‑C4). No child may access parent state except through this +mechanism. + +ABC-C8 - Bubbling Up +==================== + +A child‑to‑parent data‑flow mechanism in which a Construct (ABC‑C0) exposes its +outputs exclusively through its Output Contract (ABC‑C5). Parents receive these +outputs, may aggregate or transform them, and may optionally pass them further +down to other children via Capturing Down. No lateral or implicit communication +is permitted. diff --git a/src/conf.py b/src/conf.py new file mode 100644 index 0000000..565ac91 --- /dev/null +++ b/src/conf.py @@ -0,0 +1,41 @@ +import datetime + +extensions = [ + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx_last_updated_by_git', + 'sphinx_markdown_builder' +] + + +templates_path = ["_templates"] + +project = "Abstract Base Cloud Specification" +copyright = "2026, Tiara Rodney" + +html_title = project +html_theme = 'pydata_sphinx_theme' +html_sidebars = {} +html_show_sphinx = False +html_show_sourcelink = False + +html_context = { + "bitbucket_url": "https://bitbucket.org", + "bitbucket_user": "byteb4rb1e", + "bitbucket_repo": "blog.tiararodney.com", + "bitbucket_version": "master", + "doc_path": "src/" +} + + + +language = 'en' + +todo_include_todos = True + +rst_prolog = f""" +.. |build-time| replace:: {datetime.datetime.now().strftime("%d %B %Y, %H:%M")} +""" + +html_last_updated_fmt = "%d %B %Y, %H:%M" + diff --git a/src/example.rst b/src/example.rst new file mode 100644 index 0000000..6acc90c --- /dev/null +++ b/src/example.rst @@ -0,0 +1,386 @@ +################# +Canonical Example +################# + +This example demonstrates how the ABC Pattern structures a real application +using only: + +* Constructs (ABC‑C0) +* Application Stack (ABC‑C1) +* Logical Units (ABC‑C2) +* Resource Groups (ABC‑C3) +* Input/Output Contracts (ABC‑C4, ABC‑C5) +* Instantiation Interface (ABC‑C6) +* Capturing Down (ABC‑C7) +* Bubbling Up (ABC‑C8) + +Every interaction is explicit. Every dependency is visible. Nothing leaks +sideways. + +Overview +======== + +We model a classic 3‑tier architecture: + +* Data Tier - database + storage +* Logic Tier - compute + messaging +* Presentation Tier - CDN + web frontend + +Each tier is a Logical Unit (ABC‑C2). + +Each component inside a tier is a Resource Group (ABC‑C3). + +The Application Stack (ABC‑C1) composes them, wires them, and exposes the final +outputs. + +Conceptual Diagram +================== + +.. code-block:: + + ┌──────────────────────────────┐ + │ Application Stack │ + │ (ABC‑C1) │ + └─────────────┬────────────────┘ + │ + ┌──────────────────────┼────────────────────────┐ + │ │ │ + ┌───────▼────────┐ ┌───────▼────────┐ ┌─────────▼────────┐ + │ DataUnit │ │ LogicUnit │ │ PresentationUnit │ + │ (C2) │ │ (C2) │ │ (C2) │ + └───────┬────────┘ └───────┬────────┘ └────────┬─────────┘ + │ │ │ + │ │ ┌────────│──────┐ + ┌────▼─────┐ ┌────▼─────┐ ┌────▼──────┐ ┌──────▼─────┐ + │StorageGrp│ │ComputeGrp│ │WebAppGrp │ │ CDNGrp │ + │ (C3) │ │ (C3) │ │ (C3) │ │ (C3) │ + └──────────┘ └──────────┘ └───────────┘ └────────────┘ + +Application Stack (ABC‑C1) +========================== + +The Application Stack is the root construct. + +It has no parent and defines the deployment boundary. + +Responsibilities +---------------- + +* Instantiate each Logical Unit (ABC‑R1). +* Provide downward inputs (ABC‑F1). +* Receive upward outputs (ABC‑F2). +* Route outputs between Logical Units (ABC‑R44). +* Expose a final Output Contract representing the whole system. + +Input Contract (ABC‑C4) +----------------------- + +The Application Stack receives only global configuration: + +.. code-block:: + + AppStackInputs: + environment: string + region: string + global_tags: map + +Output Contract (ABC‑C5) +------------------------ + +The Application Stack exposes: + +.. code-block:: + + AppStackOutputs: + frontend_url: string + api_endpoint: string + +These values originate from the Presentation and Logic tiers, respectively. + +Logical Units (ABC‑C2) +====================== + +Each Logical Unit encapsulates a functional domain. + +They do not know about each other. + +They communicate only through the Application Stack. + +We define three: + +* DataUnit +* LogicUnit +* PresentationUnit + +Each has its own Input/Output Contracts and internal Resource Groups. + +Data Logical Unit (ABC‑C2) +-------------------------- + +Purpose +^^^^^^^ + +Provide persistent storage and database capabilities. + +Resource Groups (ABC‑C3) +^^^^^^^^^^^^^^^^^^^^^^^^ + +* StorageGroup - object storage +* DatabaseGroup - relational database + +Input Contract +^^^^^^^^^^^^^^ + +.. code-block:: + + DataUnitInputs: + environment: string + region: string + storage_class: string + db_engine: string + db_instance_size: string + +Output Contract +^^^^^^^^^^^^^^^ + +.. code-block:: + + DataUnitOutputs: + storage_bucket_name: string + database_endpoint: string + +Internal Wiring +^^^^^^^^^^^^^^^ + +* StorageGroup produces ``storage_bucket_name``. +* DatabaseGroup produces ``database_endpoint``. +* DataUnit aggregates both and bubbles them up (ABC‑F2). + +.. note:: + + * StorageGroup and DatabaseGroup do not know about each other (ABC‑R10). + * All configuration flows downward from DataUnit (ABC‑F1). + +Logic Logical Unit (ABC‑C2) +--------------------------- + +Purpose +^^^^^^^ + +Provide compute and messaging capabilities for the application backend. + +Resource Groups +^^^^^^^^^^^^^^^ + +* ComputeGroup - application compute (e.g., functions, containers) +* MessagingGroup - queue or pub/sub system + +Input Contract +^^^^^^^^^^^^^^ + +.. code-block:: + + LogicUnitInputs: + environment: string + region: string + compute_size: string + message_retention: number + database_endpoint: string # Provided by DataUnit via AppStack + +Output Contract +^^^^^^^^^^^^^^^ + +.. code-block:: + + LogicUnitOutputs: + api_endpoint: string + message_queue_url: string + +Internal Wiring +^^^^^^^^^^^^^^^ + +* ComputeGroup receives ``database_endpoint`` via Capturing Down (ABC‑F1). +* MessagingGroup is independent. +* LogicUnit aggregates outputs and bubbles them up. + +.. note:: + + * LogicUnit does not know where the database came from. + * It only knows it received a database_endpoint in its Input Contract + (ABC‑R22). + +Presentation Logical Unit (ABC‑C2) +---------------------------------- + +Purpose +^^^^^^^ + +Serve the frontend and expose the public entry point. + +Resource Groups +^^^^^^^^^^^^^^^ + +* CDNGroup - global content distribution +* WebAppGroup - static or dynamic frontend + +Input Contract +^^^^^^^^^^^^^^ + +.. code-block:: + + PresentationUnitInputs: + environment: string + region: string + frontend_assets_bucket: string + api_endpoint: string # Provided by LogicUnit via AppStack + +Output Contract +^^^^^^^^^^^^^^^ + +.. code-block:: + + PresentationUnitOutputs: + frontend_url: string + +Internal Wiring +^^^^^^^^^^^^^^^ + +* WebAppGroup receives ``api_endpoint`` via Capturing Down. +* CDNGroup receives the output of WebAppGroup. +* PresentationUnit bubbles up the final ``frontend_url``. + +Resource Groups (ABC‑C3) +======================== + +Each Resource Group is a small, focused construct with: + +* A minimal Input Contract +* A minimal Output Contract +* No knowledge of siblings +* No access to parent state except via inputs +* No side effects during instantiation (ABC‑R33) + +Example: Database Group +----------------------- + +Input Contract +^^^^^^^^^^^^^^ + +.. code-block:: + + DatabaseGroupInputs: + db_engine: string + db_instance_size: string + environment: string + +Output Contract +^^^^^^^^^^^^^^^ + +.. code-block:: + + DatabaseGroupOutputs: + database_endpoint: string + +Instantiation Interface +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: + + new DatabaseGroup(DatabaseGroupInputs) -> DatabaseGroupOutputs + +This pattern repeats for all Resource Groups. + +Full Data Flow (ABC‑F1 and ABC‑F2) +================================== + +The complete data flow includes: + +* AppStack → Logical Units +* Logical Units → Resource Groups +* Resource Groups → Logical Units +* Logical Units → AppStack + +This is the full vertical chain required by the ABC Pattern. + +Downward Flow (Capturing Down — ABC‑F1) +--------------------------------------- + +#. AppStack → DataUnit + * ``environment`` + * ``region`` + * ``storage_class`` + * ``db_engine`` + * ``db_instance_size`` +#. DataUnit → StorageGroup + * ``environment`` + * ``region`` + * ``storage_class`` +#. DataUnit → DatabaseGroup + * ``environment`` + * ``db_engine`` + * ``db_instance_size`` +#. AppStack → LogicUnit + + * ``environment`` + * ``region`` + * ``compute_size`` + * ``message_retention`` + * ``database_endpoint`` (bubbled up from DataUnit) +#. LogicUnit → ComputeGroup + * ``environment`` + * ``compute_size`` + * ``database_endpoint`` +#. LogicUnit → MessagingGroup + * ``environment`` + * ``message_retention`` +#. AppStack → PresentationUnit + * ``environment`` + * ``region`` + * ``frontend_assets_bucket`` + * ``api_endpoint`` (bubbled up from LogicUnit) +#. PresentationUnit → WebAppGroup + * ``environment`` + * ``frontend_assets_bucket`` + * ``api_endpoint`` +#. PresentationUnit → CDNGroup + * ``environment`` + * ``webapp_origin_url`` (bubbled up from WebAppGroup) + +Upward Flow (Bubbling Up — ABC‑F2) +---------------------------------- + +#. StorageGroup → DataUnit + * ``storage_bucket_name`` +#. DatabaseGroup → DataUnit + * ``database_endpoint`` +#. DataUnit → AppStack + * ``storage_bucket_name`` + * ``database_endpoint`` +#. ComputeGroup → LogicUnit + * ``api_endpoint`` +#. MessagingGroup → LogicUnit + * ``message_queue_url`` +#. LogicUnit → AppStack + * ``api_endpoint`` + * ``message_queue_url`` +#. WebAppGroup → PresentationUnit + * ``webapp_origin_url`` +#. CDNGroup → PresentationUnit + * ``frontend_url`` +#. PresentationUnit → AppStack + * ``frontend_url`` + +Rationale +========= + +This example demonstrates: + +* Strict encapsulation +* Explicit dependencies +* No lateral references +* Deterministic wiring +* Testability at every level +* Predictable evolution +* Agent‑friendly structure + +It is the canonical reference for all profiles (CDK, Terraform, etc.). diff --git a/src/index.rst b/src/index.rst new file mode 100644 index 0000000..e74c56a --- /dev/null +++ b/src/index.rst @@ -0,0 +1,98 @@ +################### +Abstract Base Cloud +################### + + +The ABC Pattern is a universal architectural model for structuring cloud +infrastructure in a way that is predictable, explicit, and safe for automated +reasoning. It defines a small set of composable building blocks and a strict set +of rules governing how those blocks relate, communicate, and evolve. The result +is an architecture that is easy to understand, easy to validate, and easy to +generate or transform using both human and machine agents. + +ABC is intentionally tool‑agnostic and cloud‑agnostic. It does not prescribe +specific services, resource types, or implementation languages. Instead, it +defines a semantic architecture model that can be mapped onto any +infrastructure-as-code system, including imperative tools (such as CDK) and +declarative tools (such as Terraform). + +At its core, ABC is built on three foundational ideas: + +**1. A strict hierarchical structure** +Every ABC architecture is composed of three construct types: + +* ApplicationStack — the root of the system +* Logical Units — functional domains +* Resource Groups — cohesive clusters of cloud resources + +This hierarchy forms a strict tree with no lateral references, ensuring clarity +and isolation. + +**2. Explicit contracts and deterministic data flow** + +Every construct defines: + +* an Input Contract (what it needs) +* an Output Contract (what it produces) + +Data flows only in two directions: + +* Capturing Down — parents pass data to children +* Bubbling Up — children return data to parents + +This eliminates hidden dependencies and makes the architecture fully analyzable. + +**3. A stable foundation for automation** + +Because ABC is explicit, typed, and deterministic, it is uniquely suited for: + +* automated code generation +* architecture validation +* refactoring and transformation +* multi‑cloud portability +* agent‑driven reasoning + +ABC is designed to be the intermediate representation (IR) for infrastructure, +something like the "AST of cloud architecture". + +Purpose and Philosophy +====================== + +The ABC Pattern exists to solve a fundamental problem in cloud architecture: +infrastructure is too implicit. + +* Dependencies are hidden. +* Data flow is unclear. +* Modules are entangled. +* Refactoring is risky. +* Automation is fragile. + +ABC replaces this with a model that is: + +* explicit, +* typed, +* hierarchical, +* deterministic, +* verifiable, and +* portable + +It is designed to be understood by humans, validated by tools, and generated by +agents. + +Content +======= + +.. toctree:: + :maxdepth: 1 + + concepts + model + rules/index + schema + example + profiles/index + +.. toctree:: + :hidden: + + AGENTS diff --git a/src/model.rst b/src/model.rst new file mode 100644 index 0000000..9b9e6b8 --- /dev/null +++ b/src/model.rst @@ -0,0 +1,207 @@ +############## +Abstract Model +############## + +Hierarchy Model +=============== + +The ABC Pattern defines a strict three‑layer hierarchy of constructs (ABC‑C0): + +* Application Stack (ABC‑C1) — the root deployment boundary. +* Logical Units (ABC‑C2) — first‑level domains within the application. +* Resource Groups (ABC‑C3) — fine‑grained functional clusters inside each + Logical Unit. + +This hierarchy is **strictly vertical**. + +Every construct belongs to exactly one parent, and no construct may exist +outside this tree. + +The hierarchy expresses **encapsulation**: + +* ABC‑C1 encapsulates the entire application. +* ABC‑C2 encapsulates domain‑level concerns. +* ABC‑C3 encapsulates resource‑level concerns. + +Each layer exposes its behavior exclusively through its Instantiation Interface +(ABC‑C6) and its Input/Output Contracts (ABC‑C4, ABC‑C5). + +Relationship Semantics +====================== + +The ABC Pattern enforces a parent–child‑only relationship model. + +Allowed relationships +--------------------- + +A parent construct MAY instantiate children using the child’s Instantiation +Interface (ABC‑C6). + +A child MAY expose outputs upward via its Output Contract (ABC‑C5). + +A parent MAY route outputs from one child to another via Capturing Down +(ABC‑C7). + +Forbidden relationships +----------------------- + +* **No lateral references:** + + - Resource Groups (ABC‑C3) may not reference each other directly. + - Logical Units (ABC‑C2) may not reference each other directly. +* **No implicit dependencies:** + + - A construct may not read global state, shared variables, or parent + internals. +* **No hidden communication channels:** + + - All data must flow through Input/Output Contracts. + +These constraints ensure loose coupling, testability, and predictable +composition. + +Interface Semantics +=================== + +Every construct (ABC‑C0) defines two explicit interfaces: + +Input Contract (ABC‑C4) +----------------------- + +The complete set of parameters required for instantiation. +A construct MUST NOT depend on any value not present in its Input Contract. + +Output Contract (ABC‑C5) +------------------------ + +The complete set of values the construct exposes upward. +A construct MUST NOT leak internal state except through this contract. + +Interface Binding +----------------- + +When a parent instantiates a child: + +#. The parent supplies the child’s Input Contract. +#. The child returns its Output Contract. +#. The parent may: + + * consume the outputs, + * aggregate them, + * or pass them down to other children. + +This creates a **closed, explicit dependency graph** with no hidden edges. + +Instantiation Semantics +======================= + +The Instantiation Interface (ABC‑C6) is the single mechanism through which a +construct is created. + +It has three properties: + +* **Stability** - The interface remains stable even if internal implementation + changes. +* **Minimality** - Only the Input Contract is accepted; no additional + parameters. +* **Purity** - Instantiation has no side effects beyond constructing the child. + +Instantiation is always **top‑down**: + +* ABC‑C1 instantiates ABC‑C2 constructs. +* ABC‑C2 instantiates ABC‑C3 constructs. +* No construct may instantiate its parent or siblings. + +This ensures deterministic composition and predictable dependency flow. + +Data Flow Semantics +=================== + +Data flows vertically through two complementary mechanisms: + +ABC‑F1 — Capturing Down (maps to ABC‑C7) +---------------------------------------- + +A parent passes scoped inputs to its children. + +This mechanism ensures: + +* Children receive only what they need. +* No child can access parent state implicitly. +* Parents mediate all cross‑domain dependencies. + +.. admonition:: Example + + The Application Stack (ABC‑C1) passes a VPC ID to a Logical Unit (ABC‑C2), + which passes a subnet ID to a Resource Group (ABC‑C3). + +ABC‑F2 — Bubbling Up (maps to ABC‑C8) +------------------------------------- + +A child exposes outputs upward to its parent. + +This mechanism ensures: + +* All produced values are explicit. +* Parents can aggregate or route outputs. +* No child communicates directly with siblings. + +.. admonition:: Example + + A Database Resource Group returns a database endpoint to its Logical Unit, + which returns it to the Application Stack. + +Routing Semantics +----------------- + +Parents MAY: + +* **Consume** outputs (e.g., store them). +* **Transform** outputs (e.g., wrap them in a composite object). +* **Re‑expose** outputs upward. +* **Pass** outputs downward to other children. + +Children MAY not route data themselves. + +Conceptual Diagram +================== + +.. code-block:: + + Application Stack (ABC‑C1) + │ + ├── Logical Unit: Data (ABC‑C2) + │ ├── Resource Group: Storage (ABC‑C3) + │ └── Resource Group: Database (ABC‑C3) + │ + ├── Logical Unit: Logic (ABC‑C2) + │ ├── Resource Group: Compute (ABC‑C3) + │ └── Resource Group: Messaging (ABC‑C3) + │ + └── Logical Unit: Presentation (ABC‑C2) + ├── Resource Group: CDN (ABC‑C3) + └── Resource Group: WebApp (ABC‑C3) + +**Downward arrows** represent Capturing Down (ABC‑F1). + +**Upward arrows** represent Bubbling Up (ABC‑F2). + +No horizontal arrows exist. + +Rationale & Design Intent +========================= + +The ABC Pattern enforces a strict, explicit, and testable structure for cloud +infrastructure code. + +* **Encapsulation** ensures each construct hides its internal details. +* **Explicit interfaces** eliminate hidden dependencies. +* **Loose coupling** prevents cross‑domain entanglement. +* **Reusability** emerges from stable Instantiation Interfaces. +* **Testability** is guaranteed because each construct can be instantiated with + mock inputs. +* **Scalability** follows naturally from the ability to evolve constructs + independently. + +This model is intentionally tool‑agnostic so it can be mapped cleanly to CDK, +Terraform, Pulumi, or any imperative, as well as declarative IaC framework. diff --git a/src/profiles/cdk-ts.rst b/src/profiles/cdk-ts.rst new file mode 100644 index 0000000..6fb7b01 --- /dev/null +++ b/src/profiles/cdk-ts.rst @@ -0,0 +1,442 @@ +###################### +CDK TypeScript Profile +###################### + +Concept → CDK Mapping +===================== + +.. list-table:: + :header-rows: 1 + + * - ABC Concept + - Meaning + - CDK Mapping + * - ABC‑C0 + - Construct + - ``Construct`` subclass + * - ABC‑C1 + - Application Stack + - ``Stack`` subclass + * - ABC‑C2 + - Logical Unit (LU) + - ``Construct`` subclass with LU semantics + * - ABC‑C3 + - Resource Group (RG) + - ``Construct`` subclass with RG semantics + * - ABC‑C4 + - Input Contract + - TypeScript interface (``InputContract``) + * - ABC‑C5 + - Output Contract + - TypeScript interface (``OutputContract``) + * - ABC‑C6 + - Instantiation Interface + - Constructor (``scope``, ``id``, ``inputs``) + * - ABC‑C7 + - Capturing Down + - Passing inputs to children + * - ABC‑C8 + - Bubbling Up + - Exposing outputs upward + +*ABC* itself remains naming‑agnostic; this profile defines CDK‑idiomatic +conventions. + +Rules +===== + +These are profile‑specific rules for CDK-Typescript users. + +ABC-PROFILE-CDKTS‑R1 (SHOULD) +----------------------------- + +The directory structure SHOULD reflect the ABC hierarchy: + +Application Stack → Logical Units → Resource Groups. + +ABC-PROFILE-CDKTS‑R2 (SHOULD) +----------------------------- + +Each Logical Unit SHOULD reside in its own top‑level directory: + +.. code-block:: + + src/ + app-stack.ts + data/ + logic/ + presentation/ + +ABC-PROFILE-CDKTS‑R3 (SHOULD) +----------------------------- + +Each Resource Group SHOULD reside inside its parent Logical Unit: + + +.. code-block:: + + src/data/storage/ + src/data/database/ + +ABC-PROFILE-CDKTS‑R4 (SHOULD) +----------------------------- + +Each construct directory SHOULD contain an index.ts exporting the construct. + +ABC-PROFILE-CDKTS‑R5 (SHOULD) +----------------------------- + +File and directory names SHOULD follow CDK naming conventions. + +ABC-PROFILE-CDKTS‑R6 (MAY) +-------------------------- + +Modules MAY split into multiple files if needed, as long as they remain in the +same directory. + +ABC-PROFILE-CDKTS‑R7 (SHOULD) +----------------------------- + +Each construct module SHOULD define its own ``InputContract`` and +``OutputContract``. + +ABC-PROFILE-CDKTS‑R8 (SHOULD) +----------------------------- + +Within a module, contracts SHOULD be named simply ``InputContract`` and +``OutputContract``. + +ABC-PROFILE-CDKTS‑R9 (SHOULD) +----------------------------- + +When importing contracts from another module, they SHOULD be aliased: + +ABC-PROFILE-CDKTS‑R10 (MUST) +---------------------------- + +Constructs MUST be instantiated using a single InputContract object. + +Also see ABC‑R30/32. + +ABC-PROFILE-CDKTS‑R11 (MUST) +---------------------------- + +All cross‑construct wiring MUST occur in the parent construct. + +Also see ABC‑R44. + +ABC-PROFILE-CDKTS‑R12 (SHOULD) +------------------------------ + +Imported contracts SHOULD be aliased to descriptive names. + +ABC-PROFILE-CDKTS‑R13 (SHOULD) +------------------------------ + +Contracts SHOULD be co‑located with their construct modules. + +ABC-PROFILE-CDKTS‑R14 (SHOULD) +------------------------------ + +Generated code SHOULD mirror the ABC hierarchy in structure and composition. + +ABC-PROFILE-CDKTS‑R15 (SHOULD) +------------------------------ + +Construct internals SHOULD NOT be accessed except through outputs. + +ABC-PROFILE-CDKTS‑R16 (SHOULD) +------------------------------ + +Constructs SHOULD be generated in ABC order: Resource Groups → Logical Units → +Application Stack. + +Base ABC Classes for Typescript-CDK +=================================== + +Core Types +---------- + +.. code-block:: javascript + :caption: src/abc/core-types.ts + + export interface InputContract {} + export interface OutputContract {} + + export interface HasOutputs { + readonly outputs: TOutputs; + } + +Application Stack Base +---------------------- + +.. code-block:: javascript + :caption: src/abc/application-stack.ts + + import { Stack, StackProps } from 'aws-cdk-lib'; + import { Construct } from 'constructs'; + import { OutputContract } from './core-types'; + + export abstract class ABCApplicationStack< + TOutputs extends OutputContract = OutputContract + > extends Stack { + public abstract readonly outputs: TOutputs; + + protected constructor(scope: Construct, id: string, props?: StackProps) { + super(scope, id, props); + } + } + +Logical Unit Base +----------------- + +.. code-block:: javascript + :caption: src/abc/logical-unit.ts + + import { Construct } from 'constructs'; + import { InputContract, OutputContract, HasOutputs } from './core-types'; + + export abstract class ABCLogicalUnit< + TInputs extends InputContract, + TOutputs extends OutputContract + > extends Construct implements HasOutputs { + public abstract readonly outputs: TOutputs; + protected readonly inputs: TInputs; + + protected constructor(scope: Construct, id: string, inputs: TInputs) { + super(scope, id); + this.inputs = Object.freeze({ ...inputs }) as TInputs; + } + } + +Resource Group Base +------------------- + +.. code-block:: javascript + :caption: src/abc/resource-group.ts + + import { Construct } from 'constructs'; + import { InputContract, OutputContract, HasOutputs } from './core-types'; + + export abstract class ABCResourceGroup< + TInputs extends InputContract, + TOutputs extends OutputContract + > extends Construct implements HasOutputs { + public abstract readonly outputs: TOutputs; + protected readonly inputs: TInputs; + + protected constructor(scope: Construct, id: string, inputs: TInputs) { + super(scope, id); + this.inputs = Object.freeze({ ...inputs }) as TInputs; + } + } + +Logical Units & Resource Groups (Canonical Example) +=================================================== + +Below is the full 3‑tier example implemented in CDK. + +Data Logical Unit +----------------- + +.. code-block:: + + src/data/index.ts + src/data/storage/index.ts + src/data/database/index.ts + +.. code-block:: javascript + :caption: src/data/index.ts + + import { Construct } from 'constructs'; + import { ABCLogicalUnit } from '../abc/logical-unit'; + import { StorageGroup } from './storage'; + import { DatabaseGroup } from './database'; + + export interface InputContract { + environment: string; + region: string; + storageClass: string; + dbEngine: string; + dbInstanceSize: string; + } + + export interface OutputContract { + storageBucketName: string; + databaseEndpoint: string; + } + + export class DataUnit extends ABCLogicalUnit { + public readonly outputs: OutputContract; + + constructor(scope: Construct, id: string, inputs: InputContract) { + super(scope, id, inputs); + + const storage = new StorageGroup(this, 'Storage', { + environment: inputs.environment, + region: inputs.region, + storageClass: inputs.storageClass, + }); + + const database = new DatabaseGroup(this, 'Database', { + environment: inputs.environment, + dbEngine: inputs.dbEngine, + dbInstanceSize: inputs.dbInstanceSize, + }); + + this.outputs = { + storageBucketName: storage.outputs.storageBucketName, + databaseEndpoint: database.outputs.databaseEndpoint, + }; + } + } + +Storage Resource Group +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: + :caption: src/data/storage/index.ts + + import { Construct } from 'constructs'; + import { ABCResourceGroup } from '../../abc/resource-group'; + + export interface InputContract { + environment: string; + region: string; + storageClass: string; + } + + export interface OutputContract { + storageBucketName: string; + } + + export class StorageGroup extends ABCResourceGroup { + public readonly outputs: OutputContract; + + constructor(scope: Construct, id: string, inputs: InputContract) { + super(scope, id, inputs); + + this.outputs = { + storageBucketName: 'bucket-name-placeholder', + }; + } + } + +Database Resource Group +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: + :caption: src/data/database/index.ts + + import { Construct } from 'constructs'; + import { ABCResourceGroup } from '../../abc/resource-group'; + + export interface InputContract { + environment: string; + dbEngine: string; + dbInstanceSize: string; + } + + export interface OutputContract { + databaseEndpoint: string; + } + + export class DatabaseGroup extends ABCResourceGroup { + public readonly outputs: OutputContract; + + constructor(scope: Construct, id: string, inputs: InputContract) { + super(scope, id, inputs); + + this.outputs = { + databaseEndpoint: 'db-endpoint-placeholder', + }; + } + } + +Logic Logical Unit +------------------ + +.. code-block:: + + src/logic/index.ts + src/logic/compute/index.ts + src/logic/messaging/index.ts + +Compute Resource Group and Messaging Resource Group follow the same pattern. + +Presentation Logical Unit +------------------------- + +.. code-block:: + + src/presentation/index.ts + src/presentation/webapp/index.ts + src/presentation/cdn/index.ts + +WebApp Resource Group and CDN Resource Group follow the same pattern. + +Application Stack +================= + +.. code-block:: javascript + :caption: src/app-stack.ts + + import { Construct } from 'constructs'; + import { ABCApplicationStack } from './abc/application-stack'; + import { DataUnit } from './data'; + import type { InputContract as DataUnitInput } from './data'; + import { LogicUnit } from './logic'; + import type { InputContract as LogicUnitInput } from './logic'; + import { PresentationUnit } from './presentation'; + import type { InputContract as PresentationUnitInput } from './presentation'; + + export interface InputContract { + environment: string; + region: string; + globalTags?: Record; + } + + export interface OutputContract { + frontendUrl: string; + apiEndpoint: string; + } + + export class AppStack extends ABCApplicationStack { + public readonly outputs: OutputContract; + + constructor(scope: Construct, id: string, inputs: InputContract) { + super(scope, id); + + const dataInputs: DataUnitInput = { + environment: inputs.environment, + region: inputs.region, + storageClass: 'STANDARD', + dbEngine: 'postgres', + dbInstanceSize: 'db.t3.micro', + }; + const dataUnit = new DataUnit(this, 'DataUnit', dataInputs); + + const logicInputs: LogicUnitInput = { + environment: inputs.environment, + region: inputs.region, + computeSize: 'small', + messageRetention: 1209600, + databaseEndpoint: dataUnit.outputs.databaseEndpoint, + }; + const logicUnit = new LogicUnit(this, 'LogicUnit', logicInputs); + + const presentationInputs: PresentationUnitInput = { + environment: inputs.environment, + region: inputs.region, + frontendAssetsBucket: dataUnit.outputs.storageBucketName, + apiEndpoint: logicUnit.outputs.apiEndpoint, + }; + const presentationUnit = new PresentationUnit(this, 'PresentationUnit', presentationInputs); + + this.outputs = { + frontendUrl: presentationUnit.outputs.frontendUrl, + apiEndpoint: logicUnit.outputs.apiEndpoint, + }; + } + } + diff --git a/src/profiles/index.rst b/src/profiles/index.rst new file mode 100644 index 0000000..5ef5692 --- /dev/null +++ b/src/profiles/index.rst @@ -0,0 +1,26 @@ +######## +Profiles +######## + +Profiles define how the ABC Pattern maps onto specific IaC tools. Each profile +introduces additional rules, conventions, and examples tailored to the target +system. + +Profiles use identifiers of the form: + +.. code-block:: + + ABC-PROFILE--R# + +Current profiles include: + +* imperative, object‑oriented implementations +* declarative module‑based implementation + +Profiles demonstrate that ABC is not tied to any particular paradigm. + +.. toctree:: + :glob: + :maxdepth: 1 + + * diff --git a/src/profiles/tf.rst b/src/profiles/tf.rst new file mode 100644 index 0000000..bb0fb42 --- /dev/null +++ b/src/profiles/tf.rst @@ -0,0 +1,249 @@ +################# +Terraform Profile +################# + +Concept → Terraform Mapping +=========================== + +.. list-table:: + :header-rows: 1 + + * - ABC Concept + - Meaning + - Terraform Mapping + * - ABC‑C0 + - Construct + - Terraform module + * - ABC‑C1 + - Application Stack + - Root Terraform module + * - ABC‑C2 + - Logical Unit + - Child module representing a domain + * - ABC‑C3 + - Resource Group + - Submodule representing a cohesive resource cluster + * - ABC‑C4 + - Input Contract + - variables.tf in a module + * - ABC‑C5 + - Output Contract + - outputs.tf in a module + * - ABC‑C6 + - Instantiation Interface + - ``module "" { ... }`` block + * - ABC‑C7 + - Capturing Down + - Passing variables from parent to child module + * - ABC‑C8 + - Bubbling Up + - Exposing outputs from child modules to parent + +Proile Rules +============ + +Terraform profile rules follow the canonical identifier format: + +.. code-block:: + + ABC-PROFILE-TF-R# + +These rules are profile‑specific, not core ABC rules. + +ABC-PROFILE-TF-R1 (SHOULD) +-------------------------- + +Each ABC construct SHOULD be implemented as a Terraform module. + +ABC-PROFILE-TF-R2 (SHOULD) +-------------------------- + +The directory structure SHOULD reflect the ABC hierarchy: + +.. code-block:: + + root/ + main.tf + data/ + main.tf + storage/ + main.tf + database/ + main.tf + logic/ + main.tf + presentation/ + main.tf + +ABC-PROFILE-TF-R3 (SHOULD) +-------------------------- + +Each module SHOULD contain: + +* main.tf +* variables.tf (InputContract) +* outputs.tf (OutputContract) + +ABC-PROFILE-TF-R4 (MUST) +------------------------ + +Module inputs MUST be declared exclusively in variables.tf. + +ABC-PROFILE-TF-R5 (MUST) +------------------------ + +Module outputs MUST be declared exclusively in outputs.tf. + +ABC-PROFILE-TF-R6 (MUST) +------------------------ + +Modules MUST NOT reference parent or sibling modules directly; all data MUST +flow through variables and outputs. + +(This enforces ABC‑R22, ABC‑R40, ABC‑R42.) + +ABC-PROFILE-TF-R7 (MUST) +------------------------ + +Modules MUST be instantiated using a module "" { ... } block with explicit +variable assignments. + +ABC-PROFILE-TF-R8 (MUST) +------------------------ + +Modules MUST NOT read Terraform state from other modules except via outputs. + +ABC-PROFILE-TF-R9 (MUST) +------------------------ + +Capturing Down MUST be implemented by passing parent variables or outputs into +child module inputs. + +ABC-PROFILE-TF-R10 (MUST) +------------------------- + +Bubbling Up MUST be implemented by exposing child module outputs and re‑exposing +them in the parent module if needed. + +ABC-PROFILE-TF-R11 (MUST) +------------------------- + +Resource definitions MUST reside only in Resource Group modules (ABC‑C3). + +ABC-PROFILE-TF-R12 (MUST) +------------------------- + +Logical Units MUST NOT contain Terraform resources directly. + +ABC-PROFILE-TF-R13 (SHOULD) +--------------------------- + +Logical Units SHOULD only orchestrate child modules and expose aggregated +outputs. + +Canonical Example +================= + +A minimal 3‑tier ABC architecture in Terraform. + +Application Stack +----------------- + +.. code-block:: hcl + :caption: main.tf + + module "data" { + source = "./data" + environment = var.environment + region = var.region + } + + module "logic" { + source = "./logic" + environment = var.environment + region = var.region + database_endpoint = module.data.database_endpoint + } + + module "presentation" { + source = "./presentation" + environment = var.environment + region = var.region + frontend_assets_bucket = module.data.storage_bucket_name + api_endpoint = module.logic.api_endpoint + } + + output "frontend_url" { + value = module.presentation.frontend_url + } + + output "api_endpoint" { + value = module.logic.api_endpoint + } + +.. code-block:: hcl + :caption: variables.tf + + variable "environment" { type = string } + variable "region" { type = string } + +Data Logical Unit +----------------- + +.. code-block:: + :caption: data/main.tf + + module "storage" { + source = "./storage" + environment = var.environment + region = var.region + storage_class = var.storage_class + } + + module "database" { + source = "./database" + environment = var.environment + db_engine = var.db_engine + db_instance_size = var.db_instance_size + } + + output "storage_bucket_name" { + value = module.storage.bucket_name + } + + output "database_endpoint" { + value = module.database.endpoint + } + +.. code-block:: + :caption: data/variables.tf + + variable "environment" { type = string } + variable "region" { type = string } + variable "storage_class" { type = string } + variable "db_engine" { type = string } + variable "db_instance_size" { type = string } + +Storage Resource Group +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: hcl + :caption: data/storage/main.tf + + resource "aws_s3_bucket" "bucket" { + bucket = "${var.environment}-storage" + } + +.. code-block:: hcl + :caption: data/storage/variables.tf + + variable "environment" { type = string } + variable "region" { type = string } + variable "storage_class" { type = string } + +.. code-block:: hcl + :caption: data/storage/outputs.tf + + output "bucket_name" { + value = aws_s3_bucket.bucket.bucket + } diff --git a/src/rules/index.rst b/src/rules/index.rst new file mode 100644 index 0000000..be85da3 --- /dev/null +++ b/src/rules/index.rst @@ -0,0 +1,26 @@ +##### +Rules +##### + +The ABC Pattern is defined and enforced through two complementary rule families: + +.. toctree:: + :glob: + :maxdepth: 1 + + * + +Together, these rule sets establish the semantic, structural, and mechanical +guarantees that make ABC architectures predictable, verifiable, and safe for +automated reasoning and transformation. + +Although closely related, the two rule families serve distinct purposes: + +**Normative Rules** define the semantic contract of the ABC Pattern. They +specify what MUST, SHOULD, or MAY be true in any ABC‑compliant architecture, +independent of implementation language, cloud provider, or IaC tool. + +**Validation Rules** define the mechanical checks required to verify that an ABC +architecture conforms to the Normative Rules and the ABC Schema. Where Normative +Rules describe what must be true, Validation Rules describe how to detect +violations. diff --git a/src/rules/normative.rst b/src/rules/normative.rst new file mode 100644 index 0000000..f656330 --- /dev/null +++ b/src/rules/normative.rst @@ -0,0 +1,328 @@ +############### +Normative Rules +############### + +The ABC Pattern is defined by a set of Normative Rules that establish the +structural, behavioral, and data‑flow guarantees of the architecture. These +rules are the foundation that makes ABC: + +* predictable +* composable +* verifiable +* agent‑friendly +* implementation‑agnostic + +Normative Rules describe what MUST or SHOULD be true in any ABC‑compliant +architecture, regardless of the underlying cloud provider, IaC tool, or +programming language. They are not suggestions or stylistic preferences; they +are the semantic constraints that ensure ABC constructs behave consistently and +safely. + +Each rule is assigned a canonical identifier of the form: + +.. code-block:: + + ABC-R# + +This identifier is stable, unique, and referenced throughout: + +* the ABC Schema +* validation rules +* implementation profiles (e.g., CDKTS, Terraform) +* agent guidance +* tooling and linters + +Hierarchy Rules +=============== + +These define the allowed structure of an ABC architecture, including the roles +and relationships of ApplicationStacks, Logical Units, and Resource Groups. + +ABC‑R1 (MUST) +------------- + +An Application Stack (ABC‑C1) MUST contain one or more Logical Units (ABC‑C2). + +ABC‑R2 (MUST) +------------- + +A Logical Unit (ABC‑C2) MUST contain one or more Resource Groups (ABC‑C3). + +ABC‑R3 (MUST) +------------- + +Every Construct (ABC‑C0) MUST have exactly one parent, except the Application +Stack (ABC‑C1), which has none. + +ABC‑R4 (MUST) +------------- + +Constructs MUST form a strict tree hierarchy with no cycles. + +ABC‑R5 (SHOULD) +--------------- + +Logical Units (ABC‑C2) SHOULD represent coherent functional domains. + +ABC‑R6 (MAY) +------------ + +Resource Groups (ABC‑C3) MAY be nested further if the implementation framework +supports sub‑constructs, provided all other rules remain satisfied. + +Relationship Rules +================== + +Specify how constructs relate to one another, including parent‑child +constraints, allowed dependencies, and prohibited lateral references. + +ABC‑R10 (MUST) +-------------- + +A Resource Group (ABC‑C3) MUST NOT reference another Resource Group directly. + +ABC‑R11 (MUST) +-------------- + +A Logical Unit (ABC‑C2) MUST NOT reference another Logical Unit directly. + +ABC‑R12 (MUST) +-------------- + +A Construct (ABC‑C0) MUST NOT access parent state except through Capturing Down +(ABC‑F1). + +ABC‑R13 (MUST) +-------------- + +A Construct (ABC‑C0) MUST NOT access sibling state under any circumstances. + +ABC‑R14 (MUST) +-------------- + +All cross‑domain communication MUST be mediated by the parent construct. + +ABC‑R15 (SHOULD) +---------------- + +Constructs SHOULD minimize the number of outputs they expose to reduce coupling. + +ABC‑R16 (MAY) +------------- + +A parent MAY aggregate outputs from multiple children before re‑exposing them. + +Interface Rules +=============== + +Define the semantics of Input and Output Contracts, including immutability, +explicitness, and the boundaries they enforce. + +ABC‑R20 (MUST) +-------------- + +Every Construct (ABC‑C0) MUST define an Input Contract (ABC‑C4). + +ABC‑R21 (MUST) +-------------- + +Every Construct (ABC‑C0) MUST define an Output Contract (ABC‑C5), even if empty. + +ABC‑R22 (MUST) +-------------- + +A Construct MUST NOT depend on any value not present in its Input Contract. + +ABC‑R23 (MUST) +-------------- + +A Construct MUST NOT expose any value not present in its Output Contract. + +ABC‑R24 (MUST) +-------------- + +Input Contracts MUST be immutable after instantiation. + +ABC‑R25 (SHOULD) +---------------- + +Output Contracts SHOULD be minimal and stable across versions. + +ABC‑R26 (MAY) +------------- + +A Construct MAY expose composite outputs if they simplify parent‑level wiring. + +Instantiation Rules +=================== + +Specify how constructs are created, how inputs are provided, and how +instantiation must avoid side effects or hidden dependencies. + +ABC‑R30 (MUST) +-------------- + +A Construct (ABC‑C0) MUST be instantiated exclusively through its Instantiation +Interface (ABC‑C6). + +ABC‑R31 (MUST) +-------------- + +Instantiation MUST be top‑down: parents instantiate children; children MUST NOT +instantiate parents or siblings. + +ABC‑R32 (MUST) +-------------- + +The Instantiation Interface MUST accept only the Input Contract (ABC‑C4) and no +additional parameters. + +ABC‑R33 (MUST) +-------------- + +Instantiation MUST NOT produce side effects beyond constructing the child. + +ABC‑R34 (SHOULD) +---------------- + +Instantiation Interfaces SHOULD remain stable across minor revisions. + +ABC‑R35 (MAY) +------------- + +Constructs MAY provide optional parameters in the Input Contract if defaults are +well‑defined. + +Data Flow Rules +=============== + +Formalize the two fundamental ABC data‑flow mechanisms: + +* Capturing Down (parent → child) +* Bubbling Up (child → parent) + +These rules ensure that all communication flows through the parent construct, +eliminating ambiguity and hidden coupling. + +ABC‑R40 (MUST) +-------------- + +All downward data flow MUST occur through Capturing Down (ABC‑F1). + +ABC‑R41 (MUST) +-------------- + +All upward data flow MUST occur through Bubbling Up (ABC‑F2). + +ABC‑R42 (MUST) +-------------- + +A Construct MUST NOT read values from its parent except those explicitly passed +via Capturing Down. + +ABC‑R43 (MUST) +-------------- + +A Construct MUST NOT write values to its parent except through Bubbling Up. + +ABC‑R44 (MUST) +-------------- + +Parents MUST mediate all routing of outputs between children. + +ABC‑R45 (SHOULD) +---------------- +Parents SHOULD avoid passing unnecessary outputs downward to reduce coupling. + +ABC‑R46 (MAY) +------------- + +Parents MAY transform outputs before passing them down. + +Encapsulation & Testability Rules +================================= + +Ensure that constructs remain isolated, testable, and free from cross‑cutting +concerns. These rules prevent leakage of internal details and enforce strict +boundaries. + +ABC‑R50 (MUST) +-------------- + +Constructs MUST encapsulate all internal implementation details. + +ABC‑R51 (MUST) +-------------- + +Constructs MUST be instantiable in isolation using mock Input Contracts. + +ABC‑R52 (SHOULD) +---------------- + +Constructs SHOULD avoid exposing internal resource identifiers unless required. + +ABC‑R53 (SHOULD) +---------------- + +Constructs SHOULD minimize internal state to simplify testing. + +ABC‑R54 (MAY) +------------- + +Constructs MAY provide diagnostic outputs if they do not violate encapsulation. + +Evolution & Change Management Rules +=================================== + +Define how ABC architectures evolve safely over time, including versioning, +contract stability, and backward‑compatible changes. + +ABC‑R60 (MUST) +-------------- + +If a child’s Output Contract changes, the parent MUST adapt explicitly. + +ABC‑R61 (MUST) +-------------- + +Breaking changes to Input Contracts MUST be versioned or documented. + +ABC‑R62 (SHOULD) +---------------- + +Constructs SHOULD maintain backward compatibility where feasible. + +ABC‑R63 (SHOULD) +---------------- + +Parents SHOULD validate child outputs before routing them. + +ABC‑R64 (MAY) +------------- + +Constructs MAY deprecate fields gradually before removal. + +Optional Flexibility Rules +========================== + +Provide non‑mandatory guidance that enhances clarity, maintainability, or +ergonomics without affecting correctness. These rules are advisory and may be +adopted at the discretion of the implementation or team. + +ABC‑R70 (MAY) +------------- + +Logical Units MAY be composed dynamically if the framework supports it, provided +all other rules remain satisfied. + +ABC‑R71 (MAY) +------------- + +Resource Groups MAY be reused across Logical Units if instantiated +independently. + +ABC‑R72 (MAY) +------------- + +The Application Stack MAY expose a composite Output Contract aggregating all +Logical Unit outputs. diff --git a/src/rules/validation.rst b/src/rules/validation.rst new file mode 100644 index 0000000..b6a4589 --- /dev/null +++ b/src/rules/validation.rst @@ -0,0 +1,186 @@ +################ +Validation Rules +################ + +The ABC Validation Rules define the mechanical checks required to verify that an +ABC architecture conforms to the ABC Schema and the normative rules of the +specification. These rules are intended for: + +* automated validators +* linters +* compilers +* agent‑driven code generation +* CI/CD enforcement + +Validation Rules are **not** conceptual rules; they are operational constraints +that ensure an ABC description is structurally correct and unambiguous. + +Validation Rules follow the canonical identifier format: + +.. code-block:: + + ABC-VALID-R# + +They are grouped into: + +* Structural Validation +* Contract Validation +* Data‑Flow Validation +* Hierarchy Validation +* Profile‑Specific Validation (optional) + +Structural Validation Rules +=========================== + +These rules ensure the ABC hierarchy is well‑formed. + +ABC-VALID-R1 (MUST) +------------------- + +Every construct MUST have exactly one parent, except the ApplicationStack which +MUST have none. + +ABC-VALID-R2 (MUST) +------------------- + +The hierarchy MUST follow the pattern: +``ApplicationStack → LogicalUnit → ResourceGroup``. + +ABC-VALID-R3 (MUST) +------------------- + +Construct trees MUST NOT contain cycles. + +ABC-VALID-R4 (MUST) +------------------- + +Construct IDs MUST be unique within the architecture. + +ABC-VALID-R5 (MUST) +------------------- + +Construct types MUST be one of: +ApplicationStack, LogicalUnit, ResourceGroup. + +ABC-VALID-R6 (MUST) +------------------- + +ResourceGroups MUST NOT have children. + +ABC-VALID-R7 (MUST) +------------------- + +LogicalUnits MUST NOT have parents that are not ApplicationStacks. + +ABC-VALID-R8 (MUST) +------------------- + +ResourceGroups MUST NOT have parents that are not LogicalUnits. + +Contract Validation Rules +========================= + +These rules ensure Input/Output Contracts are well‑defined and consistent. + +ABC-VALID-R10 (MUST) +-------------------- + +Every construct MUST define both an InputContract and an OutputContract. + +ABC-VALID-R11 (MUST) +-------------------- + +InputContracts MUST be immutable after instantiation. + +ABC-VALID-R12 (MUST) +-------------------- + +Constructs MUST NOT reference values not present in their InputContract. + +ABC-VALID-R13 (MUST) +-------------------- + +Constructs MUST NOT expose outputs not declared in their OutputContract. + +ABC-VALID-R14 (SHOULD) +---------------------- + +OutputContracts SHOULD be minimal and stable across versions. + +ABC-VALID-R15 (MUST) +-------------------- + +InputContracts MUST NOT reference parent or sibling constructs directly. + +ABC-VALID-R16 (MUST) +-------------------- + +OutputContracts MUST NOT expose internal implementation details (e.g., resource +objects). + +Data‑Flow Validation Rules +========================== + +These rules enforce Capturing Down and Bubbling Up. + +ABC-VALID-R20 (MUST) +-------------------- + +All downward references MUST originate from: + +* parent.InputContract +* parent.OutputContract + +ABC-VALID-R21 (MUST) +-------------------- + +All upward references MUST originate from: + +* child.OutputContract + +ABC-VALID-R22 (MUST) +-------------------- + +No lateral data flow is permitted between siblings. + +ABC-VALID-R23 (MUST) +-------------------- + +Constructs MUST NOT read values from grandparents or ancestors except through +parent‑mediated Capturing Down. + +ABC-VALID-R24 (MUST) +-------------------- + +Constructs MUST NOT write values to ancestors except through Bubbling Up. + +ABC-VALID-R25 (MUST) +-------------------- + +Constructs MUST NOT read or write values from siblings or cousins. + +Instantiation Validation Rules +============================== + +These rules ensure constructs are instantiated correctly. + +ABC-VALID-R30 (MUST) +-------------------- + +Constructs MUST be instantiated using the Instantiation Interface: +(scope, id, inputs). + +ABC-VALID-R31 (MUST) +-------------------- + +Instantiation MUST NOT accept parameters outside the InputContract. + +ABC-VALID-R32 (MUST) +-------------------- + +Instantiation MUST NOT produce side effects beyond constructing children. + +ABC-VALID-R33 (MUST) +-------------------- + +Constructs MUST NOT mutate their InputContract after instantiation. diff --git a/src/schema.rst b/src/schema.rst new file mode 100644 index 0000000..4942dd4 --- /dev/null +++ b/src/schema.rst @@ -0,0 +1,229 @@ +###### +Schema +###### + +The ABC Schema is the authoritative, machine‑readable definition of the ABC +Pattern. It formalizes: + +* Construct types +* Hierarchy rules +* Contract requirements +* Data‑flow semantics +* Instantiation constraints +* Validation rules +* Profile extension hooks + +The schema is expressed as a single JSON Schema document, making it suitable +for: + +* Linting +* Static analysis +* Code generation +* Agent reasoning +* Architecture validation +* Profile extension (CDKTS, Terraform, Pulumi, etc.) + +This schema is intentionally strict. It defines the shape of an ABC +architecture, not the cloud resources themselves. Profiles map this schema to +concrete IaC implementations. + +.. code-block:: json + + { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.tiararodney.com/abc/abc.schema.json", + "title": "ABC Schema", + "description": "The canonical machine-readable schema for the ABC Pattern.", + "type": "object", + + "properties": { + "version": { + "type": "string", + "description": "Schema version identifier." + }, + + "constructs": { + "type": "array", + "description": "List of constructs in the ABC architecture.", + "items": { "$ref": "#/$defs/Construct" } + } + }, + + "required": ["version", "constructs"], + + "$defs": { + + "Construct": { + "type": "object", + "description": "A construct in the ABC hierarchy.", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the construct." + }, + "type": { + "type": "string", + "enum": ["ApplicationStack", "LogicalUnit", "ResourceGroup"], + "description": "Construct type (ABC-C1, C2, or C3)." + }, + "parent": { + "type": ["string", "null"], + "description": "Parent construct ID. Null only for ApplicationStack." + }, + "inputs": { + "$ref": "#/$defs/InputContract" + }, + "outputs": { + "$ref": "#/$defs/OutputContract" + }, + "children": { + "type": "array", + "items": { "type": "string" }, + "description": "IDs of child constructs." + } + }, + "required": ["id", "type", "inputs", "outputs", "children"], + "allOf": [ + { "$ref": "#/$defs/HierarchyRules" }, + { "$ref": "#/$defs/ContractRules" }, + { "$ref": "#/$defs/DataFlowRules" } + ] + }, + + "InputContract": { + "type": "object", + "description": "ABC-C4 Input Contract.", + "additionalProperties": { + "type": ["string", "number", "boolean", "object", "array", "null"] + } + }, + + "OutputContract": { + "type": "object", + "description": "ABC-C5 Output Contract.", + "additionalProperties": { + "type": ["string", "number", "boolean", "object", "array", "null"] + } + }, + + "HierarchyRules": { + "type": "object", + "description": "Hierarchy validation rules.", + "properties": {}, + "allOf": [ + { + "if": { "properties": { "type": { "const": "ApplicationStack" } } }, + "then": { + "properties": { + "parent": { "type": "null" } + }, + "errorMessage": { + "parent": "ABC-R3: ApplicationStack MUST have no parent." + } + } + }, + { + "if": { "properties": { "type": { "const": "LogicalUnit" } } }, + "then": { + "properties": { + "children": { + "minItems": 1, + "errorMessage": "ABC-R2: Logical Units MUST contain one or more Resource Groups." + } + } + } + }, + { + "if": { "properties": { "type": { "const": "ResourceGroup" } } }, + "then": { + "properties": { + "children": { + "maxItems": 0, + "errorMessage": "ABC-R10: Resource Groups MUST NOT contain child constructs." + } + } + } + } + ] + }, + + "ContractRules": { + "type": "object", + "description": "Contract validation rules.", + "properties": {}, + "allOf": [ + { + "properties": { + "inputs": { + "type": "object", + "errorMessage": "ABC-R24: Input Contracts MUST be immutable objects." + } + } + }, + { + "properties": { + "outputs": { + "type": "object", + "errorMessage": "ABC-R23: Output Contracts MUST be declared explicitly." + } + } + } + ] + }, + + "DataFlowRules": { + "type": "object", + "description": "Data flow validation rules.", + "properties": {}, + "allOf": [ + { + "if": { "properties": { "type": { "const": "LogicalUnit" } } }, + "then": { + "properties": { + "inputs": { + "type": "object" + } + } + } + } + ] + } + } + } + +How Profiles Extend This Schema +=============================== + +Profiles (e.g., Typescript CDK, Terraform) extend the monolithic schema using +JSON Schema’s allOf mechanism. + +.. code-block:: json + :caption: https://schema.tiararodney.com/abc/profile/cdkts.json + + { + "$id": "https://schema.tiararodney.com/abc/profile/cdkts.schema.json", + "title": "ABC CDK TypeScript Profile", + "allOf": [ + { "$ref": "https://abc-spec.org/schema/abc-schema.json" } + ], + "properties": { + "cdkts": { + "type": "object", + "description": "CDKTS-specific rules and metadata." + } + } + } + +How The Schema is Consumed +========================== + +#. **Generate ABC structures from natural language** + The schema defines the allowed constructs and relationships. +#. **Validate the architecture** + The schema + validation rules ensure correctness. +#. **Compile into IaC** + Profiles map the schema to CDK, Terraform, Pulumi, etc. +#. **Refactor architectures** + Agents can safely transform the schema because the rules are explicit. +#. **Generate documentation** + The schema is a perfect source for diagrams and docs.