Vývojový runtime

Co v tomto repozitáři vlastní sémantiku vývoje software, kde každé žije, který povrch smí o čem rozhodovat a jak daleko je kód od této hranice dnes.

Doprovodné dokumenty jsou DYNAMICITY.md, který rozhoduje, kde žije fakt, a CAPABILITIES.md, který rozhoduje, jak se deklaruje operace. Tento dokument je třetí z této sady: rozhoduje, kde žije sémantika. Rozhodnutím je ADR 0040; pravidlem je project.development-semantics-are-canonical@1.

Každý počet v tomto dokumentu byl změřen. Příkazy jsou v How this was measured; žádný není zkopírován z prózy a tvrzení o chování, které dosud není implementováno, je formulováno jako cíl.

Invariant

Kanonickým vývojovým runtimem je registr schopností Rust executable. Vývojová sémantika jsou jeho schopnosti. Cockpit vývojovou sémantiku neprovádí; žádá o operace kanonický runtime a odebírá kanonický stav a události. Stejná věta platí s „CLI“, „HTTP API“, „OpenAPI“ nebo „MCP“ místo „Cockpitu“.

Vývojová sémantika je jakékoli pravidlo, odvození nebo přechod nad plánem, aktivní úlohou, zkompilovaným kontextem, relací, provedením, peerem, událostí, důkazy, povinností nebo dokončením. „Je tento úkol připraven?“, „co tato úloha ještě dluží?“, „smí se tato relace uzavřít?“, „do které vlny tento úkol patří?“ — každá má právě jednu správnou odpověď a runtime je místo, kde se počítá.

Měření, o které se to opírá

Tento repozitář obsluhují dva spustitelné soubory a hranice mezi nimi není vrstvením.

bin/majordomus je shellový nástroj implementovaný pod lib/. Jeho vlastní nápověda seskupuje jeho příkazy jako TASK, CONTEXT, MEMORY, RULES, PLAN a SYSTEM: start, check, finish, session, checkpoint, evidence, handover, decision, question, plan, adr, usecase. Ten seznam je vývojový životní cyklus a lib/ je jediný zapisovatel toho, co vytváří — lib/plan.sh:514-515 je jediné místo, kde se zapisuje YAML úkolu nebo milníku.

bin/majordomus-cli je spustitelný soubor v Rustu. Vlastní registr schopností a každou jeho projekci: MCP, HTTP, OpenAPI, Swagger, Cockpit, příkazovou řádku, generovanou referenci. Jeho nápověda uvádí rozdělení záporně: „Životní cyklus úlohy (init, start, check, finish, doctor, ...) je nástroj shellu bin/majordomus ve stejném repozitáři; tento spustitelný soubor tyto příkazy neimplementuje.“

Toto jsou měření, která činí důsledek přesným. Každé uvádí, co je pravda, ne kolik; příkaz, který reprodukuje součet, je v Jak se to měřilo.

Graf uvádí čtyři zadržené důvody: „asks the person something; a request/response surface would hang“, „effect RepositoryMutation is above the machine ceiling LocalMutation“, „no capability declares this command line, so no machine surface has a typed input schema to execute from“ a „groups other commands; nothing to execute“. Většina grafu je zadržena ze všech strojových povrchů a nejčastějším důvodem je třetí.

Runtime tedy dnes nedokáže změnit jediný vývojový objekt a nic z životního cyklu není dosažitelné z Cockpitu, MCP ani HTTP.

Cockpit není provinilec. Jeho stromy nikde neodkazují na vrstvu; nečte žádný stav a žádný nezapisuje. Jediný odkaz, který tento dokument zaznamenal, když přistálo ADR 0040, byl zobrazovaný popisek — titulek původu u statistic() pojmenovávající cestu vrstvy tam, kde všechna ostatní místa volání pojmenovávají prózu — a od té doby byl také přepsán na prózu, což zbytek souboru dělal už dřív. Je to už ta čistá projekce, kterou vyžadují COCKPIT.md a ADR 0013. Vada je na druhé straně: runtime nemá co nabídnout z vývojové sémantiky, takže Cockpit, který má být vývojovým povrchem, má dvě možnosti — reimplementovat životní cyklus, nebo volat bin/majordomus. Obě vytvářejí druhou implementaci a ta druhá se rozjede.

Kanonický model v názvech nativních pro repozitář

Repozitář už má jméno pro každou fázi, kterou vývojový povrch potřebuje. Zavedení synonyma pro kteroukoli z nich je vada, ne rozšíření. Mapování níže je model; worker rozšiřující kteroukoli fázi konverguje ke jménu ve středním sloupci.

Dvě fáze, které pipeline mandátu jmenuje zvlášť, jsou tady jedna věc, a říct to je důležitější než diagram: vývojová úloha je existující task, ne nový objekt vedle ní, a provedení workflow je execution z command grafu příkazů, ne třetí plánovač.

Hranice vlastnictví

flowchart TD
  store["THE LAYER · storage<br/><small>.ai/repo (shared) + .ai/local<br/>typed by share/kinds.yaml<br/>discovered by .ai/repo/knowledge/sources.yaml</small>"]
  runtime["THE CANONICAL RUNTIME · semantics<br/><small>apps/majordomus-cli/src/capability/<br/>one capability! per operation, typed in/out<br/>exposure derived by command_graph/policy.rs</small><br/>docs/CAPABILITIES.md"]
  store <-->|"reads and writes"| runtime
  subgraph surfaces["projections · surfaces"]
    cockpitui["Cockpit<br/>docs/COCKPIT.md"]
    http["HTTP + WS"]
    openapi["OpenAPI"]
    mcp["MCP<br/>docs/MCP.md"]
    cli["CLI<br/>docs/CLI.md"]
  end
  runtime --> cockpitui
  runtime --> http
  runtime --> openapi
  runtime --> mcp
  runtime --> cli

Vrstva vlastní úložiště. Každý vývojový objekt je typovaný soubor .ai/. Jeho druh je deklarován v share/kinds.yaml, jehož deklarativní druhy vypisuje projekce registru, jeho kontrakt v share/schemas/majordomus/<kind>/<kind>.v1.schema.json a jeho umístění v .ai/repo/knowledge/sources.yaml jako pathspec :(glob). Tři soubory se shodují, jinak objekt nemá typ ani autoritu.

Runtime vlastní sémantiku. Jedna deklarace capability! na operaci, s typovaným vstupem a výstupem. Kde je vystavena, se odvozuje z jejího efektu a interaktivity pomocí command_graph/policy.rs, nikdy se nevolí po plochách.

Povrch vlastní prezentaci a nic víc. Vykresluje výstup schopnosti a odesílá vstup schopnosti. Nepočítá žádný stav, nerozhoduje o žádném přechodu, nečte ani nezapisuje žádný soubor vrstvy a nespouští žádný program, aby získal sémantiku. Povrch, který volá shell, vlastní sestavení argumentů, výklad návratového kódu a vykreslení chyb — tři sémantiky v povrchu, nedeklarované.

Odpovědnosti povrchů

Úložiště: rozhodnuto a znovu použito

Žádné nové úložiště dat. Každé rozhodnutí níže je úložiště, které repozitář už má.

Dvě úrovně událostí, pojmenované. Trvalá změna stavu je událost účetní knihy, jejíž název je registrován v share/events.yaml. Typovaný stream provádění je živý pohled na běžící runtime a nikdy není záznamem. Vývojová schopnost, která mění stav, připisuje do knihy; stream nese stejnou změnu, jak se děje. Žádná z úrovní nesmí držet trvalý fakt, který druhá nevidí — což dnes v obou směrech dělá.

Provedení zůstávají nedurabilní. executions list viditelně nemá co číst a pokušením je úložiště. Zamítnuto tak, jak je napsáno: durabilní záznam už existuje a je jím kniha. Úložiště provedení zůstává omezené a v procesu; durabilita je úkolem knihy.

Tok dat, tok změn, tok událostí

Čtení. Povrch se zeptá schopnosti. Schopnost čte index — objekty objevené z sources.yaml, otypované kinds.yaml, ověřené proti schématu druhu — nebo odvození nad ním (plan.rs, graph.rs, product.rs, why.rs, obligations.rs). Žádný povrch nečte soubor.

flowchart LR
  layer[".ai/**"] -->|discovery| index["index"]
  index -->|derivation| capability["capability"]
  capability -->|projection| surface["surface"]

Mutace. Cílový tok. Povrch pošle typovaný vstup schopnosti druhu command. Schopnost zvaliduje proti svému vstupnímu schématu, aplikuje přechod na objekt v jeho kanonickém úložišti, připojí registrovanou událost ledgeru a vrátí nový stav. Totéž volání přes MCP, HTTP, CLI i Cockpit je jedna cesta kódem.

flowchart LR
  surface["surface"] -->|typed input| capability["capability"]
  capability --> object["object in .ai/**"]
  object --> ledger["ledger event"]
  ledger --> events["/events"]

Skutečný tok dnes. U mutujících příkazů životního cyklu je povrchem terminál a schopnost neexistuje: bin/majordomus posílá do lib/<name>.sh, které zapíše objekt a samo připojí řádek registru. To je dluh, který tento dokument zaznamenává, uzamčený ratchetem v .ai/repo/development-semantics-baseline.txt.

Události. Trvalé: mj_ledger_append odmítne jméno, které share/events.yaml nedeklaruje, a takové, kterému chybí povinné pole; history --event odmítne filtrovat podle nedeklarovaného jména; history --validate hlásí uložený řádek, který nezná žádný čtenář. Živé: ExecutionStore::publish aplikuje událost na snímek pod jedním zámkem, odmítne přechod, který ExecutionState::may_move_to nepovoluje, přidělí sekvenci, událost uchová a předá odběratelům — takže klient čtoucí snímek a klient čtoucí stream se nemohou rozcházet.

Záruky konzistence

Co dnes není zaručeno, uvedeno proto, aby se výše uvedený seznam nečetl jako víc, než je: vývojový objekt zapsaný lib/ se neověřuje proti vstupnímu schématu své schopnosti, protože žádná schopnost neexistuje; a fakt, který se dostane do ledgeru, se nedostane do proudu provádění, ani naopak.

Řetězec odvozování, kterým prochází každý zpřístupněný objekt

flowchart TD
  decl["canonical declaration<br>capability! under src/capability/builtin/&lt;module&gt;.rs<br>(or, for a layer object, its kind in share/kinds.yaml)"]
  schema["serialization schema<br>CanonicalSchema from the typed input/output<br>(or share/schemas/majordomus/&lt;kind&gt;/&lt;kind&gt;.v1.schema.json)"]
  http["HTTP route + OpenAPI<br>src/http/router.rs<br>docs/generated/openapi.json, openapi.yaml"]
  mcp["MCP tool or resource<br>majordomus://&lt;kind&gt;/&lt;identity&gt;,<br>or a tool by capability id"]
  cockpit["Cockpit contract<br>the page that renders that capability's JSON"]
  decl --> schema
  schema --> http
  http --> mcp
  mcp --> cockpit

Každý článek je generovaný. Nic na řetězu se nepíše ručně a ručně psaný záznam kdekoli na něm je porušením project.rust-canonical-declaration@1 (ADR 0004) stejně jako ADR 0040. Řetěz kontrolují majordomus capabilities validate, majordomus generate --check a kontroly projection-closure a rust-generated.

U objektu vrstvy začíná řetěz o krok dříve, u schématu dokumentu: Markdown kind je popsán v <kind>.v1.proto (Header = front matter, Body = sekce), z čehož se generují JSON Schema, allow-list front matteru pod share/allow/ a požadavky na sekce těla pod share/sections/.

Rozšiřitelnost: přidání vývojové sémantiky

Záměrně krátké. Pokud tento seznam roste, architektura regredovala.

1. Deklarujte jedno capability! v souboru jeho modulu pod apps/majordomus-cli/src/capability/builtin/ s typovaným vstupem, typovaným výstupem a BenchmarkCases vstupu. Nový modul je jedno module! plus jedno jméno v compose_modules!.
2. Pokud mutuje, dejte mu kind: command a připojte událost knihy — přidejte jeho název do share/events.yaml s příkazem, který ji zapisuje, a klíči payloadu, které vyžaduje.
3. Spusťte majordomus generate, poté majordomus capabilities validate. Každý povrch — HTTP, OpenAPI, MCP, stránka Cockpit, generovaná reference, cíl měření výkonu — následuje bez druhé registrace.
4. Spusťte majordomus usecase impact a každou mezeru v pokrytí, kterou jmenuje, uzavřete případem užití, který se provede.
5. Pokud sémantiku zastřešoval shellový příkaz, nasměrujte ho na schopnost a odstraňte jeho položku z .ai/repo/development-semantics-baseline.txt. Základní linie se smí zmenšovat a nesmí růst.

Žádný jiný soubor se neupravuje, aby operace existovala všude, kde má.

Inventář

Změřeno, ne zapamatováno. Vlastník je ten, kdo dnes sémantiku rozhoduje; Cesta mutace je jediná věc, která ji smí zapsat. Koncept, jehož vlastník je lib/*.sh, je dluh proti ADR 0040, ne architektura.

Vývojový životní cyklus

Runtime

Jak se runtime chová při každém selhání, které může zažít, a co to dokazuje, je tabulka selhání v MCP.md: každý řádek jmenuje testy, které jej provádějí, nebo uvádí omezení, že to nedělá nic, a test/cases/3056 odmítne řádek, který nemá ani jedno.

Správa a plochy

Mezery oproti cílové pipeline

Seřazeno podle toho, co nejvíce blokuje vývojový povrch.

1. Neexistuje žádná mutující vývojová schopnost. Schopnost druhu command deklarují jen roviny provádění a peerů. Každý přechod úkolu, událost životního cyklu relace, kontrolní bod, předávka, připojení důkazu a rozhodnutí o dokončení je z MCP, HTTP a Cockpitu nedostupné. Uzavření: schopnost kind: command na přechod, ratchetovaná od .ai/repo/development-semantics-baseline.txt.
2. Graf příkazů nevidí podpříkazy životního cyklu. Každý uzel nástroje je skupina na první úrovni; majordomus plan done <id> uzlem není. Politika expozice proto nemá co posuzovat a engine doplňování nemá co nabídnout. Jak to uzavřít: deklarujte shell podpříkazy v share/commands.yaml, nebo z každého udělejte schopnost a nechte graf, ať jej odvodí.
3. Většina příkazů životního cyklu je interaktivní. Graf je zadržuje jako „ptá se člověka na něco; plocha požadavek/odpověď by zamrzla“. Interaktivita není vlastnost, kterou plocha může obejít. Uzavření: project.commands-run-non-interactively@2, blokující od dodatku ADR 0039, rozhodováno jeho skeny.
4. Dva disjunktní modely událostí. Trvalý slovník účetní knihy a živý slovník streamu, bez mostu mezi nimi. Cockpit nemůže ukázat jediný feed aktivity. Uzavření: mutující vývojová schopnost připojí registrovanou událost do účetní knihy a publikuje tutéž změnu do streamu; žádná vrstva nedrží trvalý fakt, který by druhá neviděla.
5. Dokončení se rozhoduje na dvou místech. obligations.closure čte smlouvu; lib/finish.sh o ní rozhoduje. Dvě implementace jedné smlouvy. Uzavření: rozhodnutí se přesune do modulu obligations a finish se na ně ptá.
6. Kompilovaný kontext nemá schopnost. directories.list hlásí kontrakty kontextu; kompilovaný, rozpočtovaný kontext, který pracovník skutečně dostane, je jen lib/context.sh a DYNAMICITY.md už uvádí tabulku poskytovatelů jako entitu bez vlastníka.
7. Provedení nejsou trvalá. Rozhodnutím, ne opomenutím — ale znamená to, že Cockpit nemůže ukázat, co běželo před aktuálním procesem. Uzavření: kniha, podle §4.
8. Dva zapisovatelé docs/generated/. src/generate.rs plus sada shellu. Stávající dluh, už v území HARDCODING_LEDGER.yaml, který zasáhne každý nový generovaný vývojový artefakt.
9. CLI je nejméně úplný konzument, ne nejúplnější. Méně než polovina vestavěných schopností má projekci CLI — objects.get, repository.info, každé plan.* a graph.* a health.report žádnou nemají. Člověk u terminálu tedy dosáhne na méně kanonického runtimu než klient MCP, což obrací obvyklý předpoklad, že CLI je referenčním povrchem a ostatní ho dohánějí. Jak to uzavřít: politika vystavení o tom rozhoduje z efektu a interaktivity; dotaz zadržený před CLI je buď rozhodnutí politiky, které stojí za vyslovení, nebo opomenutí, které stojí za opravu, a dnes nic neříká, které z nich.
10. Pojmy se shellovým vlastníkem a vůbec žádnou schopností runtime: kontexty relací, znalosti, dovednosti, prompty, otázky, historie, vyhledávání.
11. Přidělování čísel ADR není hlídané. 0039 dnes nárokují dva různé soubory na dvou větvích. Vývojový povrch, který navrhuje rozhodnutí, to zhorší.

Vynucování

Pravidlem je project.development-semantics-are-canonical@1, class: blocking. Podle doktríny tohoto repozitáře — a v souladu s každým projektovým pravidlem, z nichž žádné nenese blok x-majordomus — se vynucuje kontrolou CI, a ne validátorem lib/.

scripts/development-semantics-check je kontrola, zapojená jako development-semantics v jobu structure souboru .ai/repo/ci/gates.yaml. Čte jen sledované soubory a nepotřebuje sestavení. Rozhoduje dvě věci:

• Podložení. Veřejný příkaz share/commands.yaml, jehož class mutuje a jehož writes jmenuje strom vývojových objektů, pro který docs/generated/registry.json v odpovídajícím modulu nedeklaruje žádnou schopnost druhu command.
• Čistota plochy. Odkaz na .ai/repo, .ai/local nebo spustitelný soubor majordomus uvnitř apps/majordomus-cli/src/cockpit/** nebo share/cockpit/**, s výjimkou hlavičky původu samotného generátoru.

Každé zjištění, které dnes hlásí, je v .ai/repo/development-semantics-baseline.txt: nepodložené příkazy mutující stav — adr, checkpoint, decision, evidence, finish, handover, init, migrate, plan, question, rules, session, start, update a usecase — a jeden zobrazovaný popisek Cockpitu. Zjištění mimo baseline selže; řádek baseline, který nic neodpovídá, také selže, takže ratchet utahuje, místo aby hnil.

Dvě věci, o kterých kontrola nerozhoduje, aby se její mlčení nečetlo jako průchod:

• Zda je odvození v povrchu sémantické, nebo prezentační. Šablona, která skloňuje počet, není druhou implementací; ta, která počítá připravenost, ano. Kontrola, která by hádala, by byla neauditovatelná. Rozhoduje recenzent, přesně jako majordomus.decision-threshold@1 nechává svou vlastní hranici na recenzentovi.
• Kdo zapisuje vývojový objekt. Zápis v shellu nemá spolehlivý syntaktický tvar a grep na stromy objektů by hlásil každého čtenáře jako zapisovatele. Rozhodnout by to dalo jen zapisovatele deklarované jako data — pole writes v share/commands.yaml rozšířené o jméno zapisující funkce, sladěné s lib/ tak, jak už je exit_codes. To je otevřená položka, ne kontrola.

Jak se to měřilo

# the two programs and the split between them
bin/majordomus --help
bin/majordomus-cli --help

# what the registry holds, which capabilities can mutate, and the module/kind breakdown
bin/majordomus-cli capabilities list --format json > caps.json
jq -r '{count, summary}' caps.json
jq -r '.capabilities[] | select(.provenance.source=="builtin")
        | "\(.id)\t\(.kind)\t\((.exposure|keys)|join(","))"' caps.json
jq -r '.capabilities | group_by(.module)
        | map("\(.[0].module)\t\(length)") | .[]' caps.json

# the commands, their origins, every withheld reason, and the depth per origin
bin/majordomus-cli commands graph --format json > cg.json
jq -r '.commands|group_by(.origin)|map("\(.[0].origin)\t\(length)")|.[]' cg.json
jq -r '[.commands[].projections.withheld|select(.)]
        | group_by(.)|map("\(length)\t\(.[0])")|.[]' cg.json
jq -r '.commands|group_by(.origin)
        | map({o:.[0].origin,
               d:(map(.path|length)|group_by(.)|map({d:.[0],n:length}))})|.[]' cg.json

# executions keep nothing across a process; the stream's message vocabulary
bin/majordomus-cli executions list
bin/majordomus-cli executions protocol

# the effective rules, the class split, and which of them the tool enforces
bin/majordomus rules list --json

# the durable ledger event names
grep -oE '^\s+- id: [a-z._]+' share/events.yaml

# the generation targets
bin/majordomus-cli generate --help

# the web surfaces and their mounts
bin/majordomus-cli web list

# who writes what
grep -rln 'project/issues\|project/milestones' lib/ bin/ scripts/
grep -rln 'docs/generated' lib/ bin/ scripts/
grep -rn '\.ai/\|bin/majordomus' apps/majordomus-cli/src/cockpit/ share/cockpit/*.js

# sizes and the test surface
cat lib/*.sh | wc -l ; ls test/cases/*.sh | wc -l
ls apps/majordomus-cli/tests/*.rs | wc -l

# the gate over this document's own rule
scripts/development-semantics-check

Počty čehokoli v tomto repozitáři zastarávají; měřte, místo abyste věřili číslu napsanému zde, včetně těchto.