From 0661903e94c8e3d0ea47cf9971fe4911cebace9c Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 20 Sep 2026 09:11:04 +0300 Subject: [PATCH] Clarify composition and consumer generation boundaries --- DOCS/Backends.md | 43 ++- ...ewer-specgraph-integration-source-draft.md | 297 ++++++++++++++++++ RFC/Hypercode.md | 34 +- .../Hypercode/Documentation.docc/Hypercode.md | 17 + 4 files changed, 389 insertions(+), 2 deletions(-) create mode 100644 DOCS/uml-viewer-specgraph-integration-source-draft.md diff --git a/DOCS/Backends.md b/DOCS/Backends.md index d54a9a0..c5c9b78 100644 --- a/DOCS/Backends.md +++ b/DOCS/Backends.md @@ -12,7 +12,7 @@ Compilation to a concrete language or format is **not** part of Hypercode core. ## Rules -- A **backend/adapter** consumes the IR (`hypercode.ir/v1`, see +- A **backend/adapter** consumes the IR (`hypercode.ir/v2`, or legacy v1; see [`Schema/`](../Schema/)) and emits one target. It lives in the **consumer** repo, never in Hypercode. - Hypercode emits only the canonical, schema-agnostic IR (`hypercode emit`). @@ -37,3 +37,44 @@ Hypercode never learns the ontology schema. The consumer implementation reads reviewable class drafts. Imports remain draft-only: a Hypercode context may resolve `approval_status`, but trusted Ontology approval is a governance decision, not an import side effect. + +## Composition, generation contracts, and observations + +Core supplies an addressable composition and resolved context. Consumer-owned +contracts give it platform meaning: assembly, dependency provision, input +routing, results, and lifecycle. A versioned system prompt is one possible first +form of that contract; it is guidance, not enforcement. Record the contract +version alongside source/IR revisions in generation evidence. + +A richer source-code graph does not require a richer core language. A scanner +may report inheritance, calls, imports, or cycles without those becoming `.hc` +constructs. A consumer comparing desired composition with observations must +preserve extra relations, source locations, scanner capabilities, revision, and +mapping ambiguity. Projecting to a tree must not silently hide violations. +`hypercode diff` remains an IR-to-IR change report, not a code scanner. + +Existing HCS contracts (§9.4 of the RFC) constrain resolved properties by +intersection and narrowing. They do not establish code-level architectural +conformance or enforce quality metrics. A future quality-policy consumer must +separately define scope, measurement provenance, thresholds, and aggregation; +measured values are observations, not authored requirements. + +| Owner | Responsibility | +|---|---| +| Hypercode | Minimal structure, HCS resolution/contracts, canonical IR and provenance | +| Application / generator | Platform profile or prompt, code generation, scanners and tests | +| SpecGraph (proposed integration) | Composition/observation mapping, rule evaluation, evidence and unknown results | +| Metrics | Reusable metric definitions and pack contracts; application policies choose thresholds | +| Viewer consumer | Projection, overlays, and navigation to evidence | + +The existing [codegen demo](../Examples/codegen-demo/README.md) checks node-hash +freshness and generated CONFIG values against property contracts. It is a +bounded example, not a general architecture scanner. A UML Viewer adapter should +start with an explicit composition subset; full EDN round-trip is not a core +requirement. Future consumer work may use a separate Clojure application to +exercise scanner and viewer output; no application or adapter is introduced here. + +The [integration source draft](uml-viewer-specgraph-integration-source-draft.md) +records the discussion. Proposed SpecGraph contract: +[SG-RFC-0219](https://github.com/0al-spec/SpecGraph/blob/main/docs/proposals/0219_composition_observation_contract.md). +It is not an implemented integration or a change to Hypercode grammar/IR. diff --git a/DOCS/uml-viewer-specgraph-integration-source-draft.md b/DOCS/uml-viewer-specgraph-integration-source-draft.md new file mode 100644 index 0000000..1876e6b --- /dev/null +++ b/DOCS/uml-viewer-specgraph-integration-source-draft.md @@ -0,0 +1,297 @@ +# Hypercode, UML Viewer и SpecGraph: композиция, генерация и проверка реализации + +> **Статус:** временный source draft для последующей подготовки и декомпозиции proposals. Это структурирование обсуждения, а не утверждённая спецификация, proposal или описание уже реализованной интеграции. Первый выделенный proposal: [SG-RFC-0219](https://github.com/0al-spec/SpecGraph/blob/main/docs/proposals/0219_composition_observation_contract.md). Остальные темы не имеют назначенных IDs. +> +> **Источники:** чат ChatGPT «Транспиляция UML Hypercode» от 2026-09-19 и последующая дискуссия с автором Hypercode 2026-09-20 о композиции, направленности, внешнем контракте генерации и quality policies. Исходные проекты: [UML Viewer](https://github.com/unclebob/uml-viewer), [Hypercode](https://github.com/0al-spec/Hypercode). +> +> Уточнения автора Hypercode определяют направление этого draft. Варианты реализации, схема сравнения, каскад quality policies и MVP ниже остаются предложениями для исследования. Текущие грамматика, IR и возможности инструментов здесь не проходили аудит. + +## Ядро идеи после уточнения + +Hypercode должен сохранять ограниченную декларативную модель архитектуры: композицию и иерархию, чтение от целого к деталям, направленное предоставление данных и зависимостей. Эти ограничения являются частью замысла языка и авторского видения Elegant Objects. Возможность выразить дополнительные сведения через HCS сама по себе не служит основанием добавлять произвольные архитектурные связи. + +Целевая интеграция позволяет генерировать и проверять реализацию такой модели: + +- **Hypercode** задаёт состав программы и композиционную структуру. +- **Внешний контракт генерации** определяет, как воплотить структуру на конкретной платформе. Первой формой контракта может быть системный prompt LLM-агента. +- **Quality policies** задают требования к качеству и условия проверок; место их хранения и связь с HCS ещё не выбраны. +- **Scanners и измерительные инструменты** извлекают факты из кода и результаты измерений с provenance. +- **SpecGraph** потенциально сопоставляет реализацию со структурой Hypercode, внешним контрактом и quality policies, объясняя результаты через evidence. +- **UML Viewer** может стать visual consumer и внешним форматом для ограниченного adapter, не определяя выразительные возможности Hypercode. + +```text +.hc / применимые .hcs ──► Desired composition ───────┐ + │ +Внешний контракт генерации ─────────────────────────┤ + ├─► SpecGraph +Quality policies ──────────────────────────────────┤ compare / explain + │ +Код ──► scanners ──► Observed Graph ────────────────┤ +Проверки и измерения ──► evidence / metrics ─────────┘ +``` + +Формула **Desired Graph ↔ Observed Graph** сохраняется, но не означает равенство двух произвольных графов. Desired Graph может быть деревом композиции. Observed Graph может содержать более богатые отношения, необходимые для анализа фактического кода, без переноса этих отношений в язык Hypercode. + +## Уточнение после сверки репозиториев + +В Hypercode уже определены consumer-owned adapters и IR boundary +([Backends.md](Backends.md)), а HCS property contracts уже накапливаются по +пересечению и только сужаются ([Usage.md](Usage.md#2-guardrails-contracts-as-a-ci-gate)). +Предложенный каскад quality policies ниже не заменяет эти правила: применение +измерений и code-level проверок требует отдельного consumer contract. +[Codegen demo](../Examples/codegen-demo/README.md) уже иллюстрирует генерацию и +проверку freshness/CONFIG, но не произвольный architecture comparison. + +Основной контракт сопоставления вынесен в SpecGraph; Hypercode получает только +уточнение композиционных принципов и ответственности consumers. Внешний +контракт генерации первоначально может жить рядом с приложением. Возможный +следующий эксперимент — отдельный Clojure-репозиторий для проверки scanner и +UML Viewer output. Его создание и совместимость пока не проверены и не входят +в текущие изменения. Reusable metric packs относятся к Metrics, пороги — к +явно выбранной policy приложения, их оценка — к consumer проверки. + +## 1. От транспиляции EDN к сохранению модели Hypercode + +Исходная идея возникла из примера UML Viewer на EDN: packages, classes, fields, operations, типизированные edges, namespace identity и overlay metrics. Первой гипотезой был сохранный перенос этой структуры в Hypercode с обратным экспортом в EDN. + +После обсуждения эта гипотеза перестала быть исходным требованием. Полный EDN round-trip может вынуждать Hypercode выражать наследование, associations и другие связи, которые автор сознательно не хочет вводить в архитектурную модель. + +Новая последовательность: сначала определить допустимую композиционную модель Hypercode, затем исследовать её отображение во внешние представления. Для ограниченного adapter нужно явно описать поддерживаемое подмножество и обработку неподдерживаемых элементов. Нельзя молча терять связи или объявлять полный round-trip доказанным по одному подмножеству. + +В исходной беседе рассматривался путь: + +```text +.hc + .hcs → resolved graph → canonical IR → adapter → target +``` + +Это ориентир для исследования. Его соответствие текущему коду и схемам Hypercode необходимо проверить перед реализационным proposal. Даже если внутренний IR способен хранить произвольные связи, из этого не следует, что они должны стать разрешёнными конструкциями авторского языка. + +## 2. Архитектурное намерение автора Hypercode + +В дискуссии сформулированы четыре взаимосвязанных принципа: + +| Принцип | Целевой смысл | +|---|---| +| Пользователь читает сверху вниз | Описание раскрывает целое через состав его частей | +| Программа инициализируется от App к Button | Корень организует создание вложенной композиции | +| Данные входят через корень | Внешние входы принадлежат границе системы и маршрутизируются внутрь | +| Крупное зависит от меньшего, но не наоборот | Составной компонент использует части; часть не должна знать устройство включающего её целого | + +Иллюстрация структуры, не пример синтаксиса `.hc`: + +```text +App +└── Screen + └── Form + └── Button +``` + +Желаемые свойства — декларативность, каскадность, линейность чтения и локальная понятность. Для понимания части не должно требоваться восстановление произвольной сети связей со всем приложением. + +Наследование и произвольное переплетение сущностей не являются целями расширения Hypercode. Почти императивные сценарии и ручное описание temporal coupling также не должны появляться только ради совместимости с внешним форматом. + +При этом порядок создания и temporal coupling следует различать. Runtime может вывести порядок сборки из декларативной композиции. Отдельная проблема — скрытая обязанность пользователя компонента вызывать `prepare → attach → start` в правильном порядке. Конкретные ограничения такого рода могут принадлежать внешнему контракту генерации. + +Эти принципы пока не определяют формально, что считается зависимостью, как устроены shared dependencies, переиспользование, асинхронность и lifecycle. «От App к Button» выражает направление организации сборки, а не утверждает уже выбранный порядок вызовов конструкторов на каждой платформе. + +## 3. Внешний input, маршрутизация и результаты + +Обсуждение UIKit уточнило смысл входа через корень. Касание не появляется в Button как независимый внешний input: hit-testing начинается от корня view hierarchy, обычно UIWindow, и определяет получателя через вложенные views. Это пример маршрутизации, организованной runtime. См. [Apple: Delivering touch events](https://developer.apple.com/library/archive/qa/qa2013/qa1812.html). + +Дальнейшая обработка имеет несколько механизмов. Необработанные touch events могут передаваться по responder chain; действие UIControl доставляется через target–action, а при `nil` target обработчик ищется через responder chain. Это не обязательный обратный проход по тому же дереву для каждого нажатия. См. [Apple: UIResponder](https://developer.apple.com/documentation/uikit/uiresponder) и [Target–action](https://developer.apple.com/documentation/uikit/responding-to-control-based-events-using-target-action). + +Архитектурный ориентир: + +```text +Внешний input + → граница системы / runtime + → маршрутизация по композиции + → обработка компонентом + → результат через контракт компонента +``` + +Возврат результата сам по себе не требует знания конкретного родителя. Аналогия — функция, возвращающая значение вызывающей стороне без знания её реализации. Для событий конкретный механизм должен определяться контрактом генератора. + +Корень маршрутизации может принадлежать платформенному runtime. Это не требует вручную описывать диспетчеризацию каждого события внутри App или переносить responder chain, callbacks и target–action в `.hc`. + +## 4. Внешний контракт генерации + +Детали воплощения композиции могут находиться снаружи Hypercode. Например, системный prompt агента, генерирующего код по `.hc`, может предписывать: + +> Собирай компоненты через композицию сверху вниз. Предоставляй зависимости при создании. Дочерний компонент не должен знать конкретный тип родителя. Подключай внешние входы через механизмы платформы. Возвращай результаты через контракт компонента. Избегай обязательных многошаговых протоколов настройки, когда готовность можно обеспечить при создании. + +Это иллюстрация возможного контракта, не принятый platform profile. Конкретные механизмы доставки событий, lifecycle, state management и ограничения наследования в генерируемом коде требуют отдельного решения. Отсутствие наследования в архитектурном языке не означает автоматически запрет любого платформенного subclassing, например UIKit. + +```text +.hc + применимые .hcs + внешний контракт генерации + ↓ + LLM-агент-генератор + ↓ + исходный код +``` + +Prompt направляет генерацию, но не гарантирует соблюдение правил. Для значимых требований нужны review, scanner checks, тесты или runtime evidence. Правила, пока сформулированные только естественным языком, нельзя выдавать за механически проверенный контракт. + +Для прослеживаемости полезно связывать результат генерации с revision Hypercode source и версией внешнего контракта. Сам контракт не обязан находиться в `.hc`; расположение, формат, версии и приоритеты нескольких контрактов остаются предметом проектирования. + +## 5. Desired composition и Observed Graph имеют разные роли + +Hypercode задаёт намерение автора. Scanner фиксирует обнаруженное в реализации. Ни один источник не должен автоматически подменять другой. + +Observed Graph может содержать inheritance, calls, references, imports, cycles и другие отношения, если scanner умеет их извлекать. Это словарь наблюдений, а не перечень новых конструкций Hypercode. + +Например, scanner обнаружил ссылку из Button на конкретный Form. Для сообщения об этом не нужно добавлять такую связь в `.hc`. SpecGraph может сопоставить наблюдение с внешним правилом независимости дочернего компонента от конкретного родителя. + +Наличие дополнительной связи не всегда является нарушением. Сначала нужно определить её семантику, архитектурную значимость и применимое правило. Платформенные детали могут быть допустимыми согласно контракту генератора. + +Сравнение должно отвечать на вопросы: + +- Реализованы ли ожидаемые компоненты и композиция? +- Какие наблюдения подтверждают соответствие выбранным правилам? +- Какие связи нарушают конкретный контракт или policy? +- Для каких утверждений данных недостаточно? + +Проекция Observed Graph на дерево не должна молча отбрасывать оставшиеся связи: иначе проверка скроет именно нежелательные переплетения. Нужно сохранять их как наблюдения и явно показывать результат их рассмотрения или границы проверки. + +## 6. Identity, provenance и объяснение результатов + +Общая схема ещё не согласована. Нужна совместимость идентичности и сопоставления, а не обязательно единый универсальный словарь отношений. + +Для каждого типа данных следует сохранять своё основание: + +| Данные | Необходимая прослеживаемость | +|---|---| +| Desired component / composition | Identity, источник в `.hc` или применимом `.hcs`, revision | +| Правило генерации | Источник и версия внешнего контракта, идентифицируемое правило | +| Quality requirement | Источник policy, область действия, версия | +| Наблюдаемая сущность / связь | Источник в коде, source span при наличии, revision, scanner и его версия | +| Результат проверки | Применённое правило, mapping, evidence и ограничения проверки | + +Отображаемая метка не должна автоматически считаться identity. Namespace, aliases, неоднозначность и случаи соответствия одного компонента нескольким сущностям кода требуют отдельного контракта. Упомянутое в исходном примере правило UML Viewer для `:ns` нужно учитывать при разработке adapter, не превращая его автоматически в универсальную identity Hypercode. + +Пример объяснения, не схема данных: + +```text +Структура .hc: + Form содержит Button + +Внешний контракт генерации: + дочерний компонент не зависит от конкретного типа родителя + +Наблюдение: + Button хранит ссылку типа Form + evidence: Button.swift:47, revision R, scanner S + +Результат: + нарушение правила внешнего контракта + область: компонент Button из .hc +``` + +«Не обнаружено» не означает «отсутствует». Проверка должна учитывать охват scanner и возможность состояния `unknown` / «недостаточно evidence». Статическое сканирование само по себе не доказывает порядок инициализации, доставку всех runtime events или корректность программы. + +## 7. Метрики и quality policies + +Метрики остаются отдельным слоем наблюдений: coverage, CRAP, cyclomatic complexity, mutation testing и другие измерения. Они не являются ни структурой композиции, ни автоматически требованиями к ней. + +Нужно различать: + +```text +Структура: Form состоит из Button +Policy: для выбранной области действует порог mutation score +Observation: на revision R инструментом T измерено значение M +Check result: значение оценено по policy P с учётом области и полноты +``` + +Для измерения нужны источник, revision/timestamp, версия инструмента, единицы, область применимости и сведения о полноте. Измеренное значение нельзя записывать как authored requirement или переносить в overlay без provenance. + +**Каскад quality policies по дереву композиции — возможное развитие идеи, ещё не принятое решение.** Корень мог бы задавать базовые требования, а вложенные области получать и уточнять их. Необходимо определить, разрешено ли ослабление родительских требований, как выражаются исключения и как разрешаются конфликты. + +Каскад требований не задаёт способ агрегации измерений. Например, coverage родителя нельзя в общем случае получить простым средним процентов дочерних компонентов; нужно учитывать исходные числители, знаменатели и пересечение областей. + +Хранение policies снаружи Hypercode, в HCS или в отдельном overlay следует исследовать. Не следует заранее расширять `.hc` деталями метрик. Quality gates и их полномочия также требуют отдельного контракта. + +## 8. Роль UML Viewer и Clojure + +UML Viewer может использоваться независимо в нескольких ролях: + +1. **Visual consumer** композиции Hypercode. +2. **Ограниченный adapter** для явно выбранного подмножества EDN. +3. **Review surface** для desired structure, observed facts и результатов проверок. +4. **Источник scanner observations и metric overlays**, если реальные контракты и лицензирование допускают такое использование. + +Ни одна из этих ролей не требует полного переноса UML-семантики в Hypercode. Отображение двух состояний и diff остаётся гипотезой интеграции, а не подтверждённой возможностью готового adapter. + +Clojure концептуально близок части намерений: functional programming, immutable data и полиморфизм без implementation inheritance в собственной модели типов. Но язык реализации viewer не гарантирует линейную архитектуру, отсутствие temporal coupling или соответствие ограничениям Hypercode. Сам UML Viewer описывает namespaces и зависимости между ними. См. [Clojure: Functional Programming](https://clojure.org/about/functional_programming), [Runtime Polymorphism](https://clojure.org/about/runtime_polymorphism), [UML Viewer README](https://github.com/unclebob/uml-viewer). + +Наследование семантики UML Viewer через adapter не является целью. Перед реализацией всё ещё требуется аудит актуальных EDN schema, scanner pipeline, UI, лицензирования и стабильности форматов. + +## 9. Возможный feedback loop + +Дальняя цель — генерация или исправление кода с проверкой относительно явно указанных оснований: + +```text +Hypercode + внешний контракт генерации + ↓ + генерация / patch + ↓ + код + ↓ + scan + tests + measurements + ↓ + SpecGraph: структура + правила + policies + ↓ + объяснимые результаты → review + ↓ + ограниченная задача агенту, если разрешена +``` + +Агент получает локализованную проблему, затронутую композиционную область, применимое правило и evidence. После изменения повторяются необходимые проверки. + +Отсутствие найденных нарушений не равно доказанной корректности. Результат должен показывать охват, непроверенные требования и использованную revision. Полномочия агента, gates и критерии завершения здесь не утверждены. + +## Возможная декомпозиция будущих proposals + +Это темы для исследования и proposal shaping, без зарезервированных IDs: + +1. **Граница композиционной модели Hypercode.** Сверить авторское намерение с текущими грамматикой, HCS и IR; определить допустимые структуры без расширения языка ради UML. +2. **Внешний контракт генерации.** Выбрать один platform profile, описать правила, версионирование и проверяемое подмножество; системный prompt может быть первой формой. +3. **Identity, mapping и provenance.** Связать authored composition, правила и наблюдения, включая неоднозначные соответствия. +4. **Observed graph ingestion.** Зафиксировать scanner capabilities, полноту и сохранение связей за пределами композиционного дерева. +5. **Проверка в SpecGraph.** Разделить соответствие структуре, нарушения внешних правил и недостаток evidence. +6. **Композиционный adapter / viewer.** Проверить отображение выбранного подмножества, не обещая полный EDN round-trip. +7. **Metric observations и quality policies.** Определить области, thresholds, возможный каскад, исключения и агрегацию отдельно от структуры. +8. **Ограниченный agent feedback loop.** После появления проверяемых контрактов определить review, полномочия и повторную проверку. + +## Варианты первого bounded MVP + +Предлагаемый первый шаг — один пример композиции, один внешний контракт и одна проверяемая реализация. Например: + +- небольшой `.hc` fixture с вложенными компонентами; +- внешнее правило, запрещающее дочернему компоненту зависеть от конкретного типа родителя; +- два code fixtures: соответствующий правилу и содержащий намеренное нарушение; +- scanner observations и явный mapping к компонентам; +- результат с указанием правила, источника нарушения и ограничений проверки; +- неполное наблюдение как отдельный случай, который не должен давать ложный результат соответствия. + +Это проверит ограниченное сопоставление структуры и внешнего правила. Генерацию LLM можно подключить отдельным экспериментом; её не требуется включать в первый тест comparison contract. Такой MVP не доказывает все четыре архитектурных принципа, полноценную conformance или универсальность scanner. + +Если первичная цель — исследовать визуальное представление, альтернативный MVP: экспорт одной композиции в поддерживаемое подмножество EDN и визуальная проверка. Он проверит adapter и отображение, но не scanner→SpecGraph цикл. Round-trip возможен только для явно определённого подмножества. + +Метрики, каскад policies, интерактивное редактирование и автоматическое исправление кода не следует объединять с этими шагами в один MVP. + +## Открытые вопросы и границы + +- Что уже выражают текущие `.hc`, `.hcs` и IR, и где они расходятся с уточнённым намерением автора? +- Какая иерархия является определяющей: композиция, ownership, создание или namespace? Не считать их тождественными без контракта. +- Что именно считается зависимостью части от целого? Как учитывать shared services, callbacks, interfaces и platform runtime? +- Как задаются корни входа для нескольких окон, фоновых событий, сетевого input и других платформенных границ? +- Какие требования относятся к Hypercode, какие — к генератору, какие — к quality policies? Как разрешаются конфликты? +- Какие правила можно проверить статически, какие требуют runtime evidence, какие остаются предметом review? +- Как сравнивать композицию с кодом при неоднозначном mapping и неполном scan, сохраняя дополнительные наблюдения? +- Нужен ли каскад policies, разрешено ли их ослабление и где хранить исключения? +- Не преобразовывать observations автоматически в авторитетный Hypercode source и не выдавать prompt за enforcement. +- Не трактовать этот source draft как принятый контракт, реализованную интеграцию или основание для назначения proposal IDs без штатного intake. + +## Короткая формулировка для последующего proposal intake + +Исследовать проверяемую генерацию и анализ программ, в которых Hypercode задаёт ограниченную декларативную композицию и иерархию, а внешний контракт определяет детали реализации. SpecGraph потенциально сопоставляет код со структурой Hypercode, правилами генерации и quality policies, сохраняя identity, provenance и границы evidence. Более богатый Observed Graph не расширяет автоматически семантику Hypercode. UML Viewer рассматривается как consumer и adapter выбранного подмножества. Первый bounded шаг должен проверить один контракт сравнения либо одно отображение композиции; метрики, каскад policies и agent feedback loop исследуются отдельно. diff --git a/RFC/Hypercode.md b/RFC/Hypercode.md index 8a44325..e62395d 100644 --- a/RFC/Hypercode.md +++ b/RFC/Hypercode.md @@ -45,7 +45,30 @@ The Hypercode paradigm is built on three main components: * **Hypercode Cascade Sheet (`.hcs` file):** A YAML-like file that defines how to interpret and configure the commands in the Hypercode file. It uses selectors to target commands and apply configurations. It is analogous to a CSS stylesheet. -* **Runtime Environment:** An engine that parses both the `.hc` and `.hcs` files, resolves the configurations by applying the HCS rules to the Hypercode structure, and executes the resulting program. +* **Resolution and consumer execution:** Hypercode resolves `.hc` and `.hcs` into canonical IR at build/generation time. A consumer-owned generator or runtime gives that structure platform-specific behavior; executing the resulting program is outside core (see §9.8 and [Backends](../DOCS/Backends.md)). + +### 3.1.1 Composition and Direction + +The architectural model intentionally favors **composition and hierarchy**. +Authors read from the whole to its parts; the root organizes assembly from App +to Button; external inputs enter through the system boundary and are routed +inward; a composite uses its parts without requiring a part to know the concrete +whole that contains it. These are design principles, not new compiler checks or +a prescribed constructor-call order. The current core also permits multiple +root nodes; this does not introduce a single-root grammar restriction. + +Nesting describes composition, not implementation inheritance or an imperative +schedule. `.class` is a selector marker, not a superclass. Arbitrary UML edges, +cross-component wiring, and temporal protocols are not additions to core merely +because an external diagram or scanner can represent them. HCS extensibility +does not automatically give such metadata structural or execution semantics. + +Platform details belong to a **consumer-owned generation contract**, which may +initially be a versioned system prompt: dependency provision, input routing, +result delivery, lifecycle, and permitted platform mechanisms. A result flowing +back does not by itself require a dependency on the concrete parent. The input +routing root may be supplied by the platform runtime. A prompt guides generation; +scanner checks, tests, and review must establish which rules the code satisfies. ### 3.2 Terminology @@ -317,6 +340,15 @@ Spec-driven development is converging on the view that the specification is the * **A fixed generated/durable boundary.** Classic MDA demanded complete models; an LLM generator tolerates incompleteness, so `.hc` can stay a skeleton. The node boundary fixes the division of labor: orchestration and wiring are derived from the resolved graph (mechanically where possible), while durable leaf implementations live behind generated interfaces and are never overwritten. Node-level hashes over the resolved IR (`hypercode.ir/v2`, [schema](../Schema/hypercode-ir-v2.schema.json)) provide the invalidation signal for incremental regeneration: the hash covers the stable resolved content — type, class, id, resolved values, child hashes — so a provenance-only change (a different rule winning with the same value) does not invalidate. `hypercode diff` computes the affected-node set between two resolved documents, with reasons (old/new value and winning rule), emitting `hypercode.diff/v1` ([schema](../Schema/hypercode-diff-v1.schema.json)) as the machine-readable feed. * **Review compression.** The unit of human review shifts from generated code to the specification diff: humans approve a small, formally resolved change; machines expand it into code and validate the expansion against the same graph. +A downstream checker may compare this desired composition with a richer +**Observed Graph** extracted from code. That comparison is distinct from +`hypercode diff`, which compares two resolved IR documents. Observations must +retain their provenance and must not automatically become authored requirements +or new `.hc` relation types. The checker should identify whether a finding comes +from the composition, an HCS property contract, an external generation rule, or +a quality policy, and report insufficient evidence rather than infer absence +from an incomplete scan. See [Backends](../DOCS/Backends.md). + ### 9.8. Acknowledged Limits * **Context binds at resolve time.** `--ctx` is supplied when resolving: Hypercode's default mode decides context at build/generation time. Runtime feature-flag systems (OpenFeature, LaunchDarkly) decide flag values per request at runtime — a different layer that composes with Hypercode rather than competing with it. Serving dynamic context from a single deployment (e.g., many tenants per process) would require embedding the resolver as a runtime library; that mode raises its own caching, latency, and provenance questions and is **decided out of scope** for the reference implementation (HC-114, decision record with revisit conditions: [`DOCS/RuntimeBoundary.md`](../DOCS/RuntimeBoundary.md)). The resolver remains an embeddable pure function of `(sheet, context)`, but core makes no runtime API commitments — no caching, no sheet hot-reload, no per-request provenance sink. diff --git a/Sources/Hypercode/Documentation.docc/Hypercode.md b/Sources/Hypercode/Documentation.docc/Hypercode.md index 4c17b49..f53cb29 100644 --- a/Sources/Hypercode/Documentation.docc/Hypercode.md +++ b/Sources/Hypercode/Documentation.docc/Hypercode.md @@ -25,6 +25,23 @@ semantic IR diff (``IRDiffer``). The `hypercode` CLI exposes `parse`, See also: the [resolution semantics](https://github.com/0al-spec/Hypercode/blob/main/EBNF/Hypercode_Resolution.md) and the [architecture overview](https://github.com/0al-spec/Hypercode/blob/main/DOCS/Architecture.md). +## Composition and consumer boundary + +The architectural intent is composition and hierarchy: top-down reading, +root-organized assembly and input routing, and parts that do not depend on the +concrete whole. Nesting is not inheritance or an imperative execution schedule; +these principles do not add compiler checks or change the current multi-root +grammar. Platform behavior belongs to a consumer-owned generation contract, +which may begin as a versioned system prompt and needs independent verification. + +Consumers may compare desired composition with scanner observations while +preserving extra relations, mapping ambiguity, and evidence. This is separate +from `hypercode diff` between resolved IR documents. HCS contracts constrain +resolved properties; they do not prove code conformance or metric thresholds. +Backends and viewer adapters remain consumer-owned. See the +[backend boundary](https://github.com/0al-spec/Hypercode/blob/main/DOCS/Backends.md) +and [RFC §3.1.1](https://github.com/0al-spec/Hypercode/blob/main/RFC/Hypercode.md#311-composition-and-direction). + ## Usage Given a structure and a cascade sheet: